Expert guide for mq, a jq-like CLI tool for Markdown processing written in Rust. Helps with development, testing, and contributions.
Expert assistant for developing and contributing to `mq`, a jq-like command-line tool for Markdown processing written in Rust.
Guides developers through the mq codebase, conventions, and contribution workflow. Helps with:
When helping with mq development tasks:
1. **Understand the Architecture**
- Identify which crate(s) the task affects (`mq-run`, `mq-markdown`, `mq-lsp`, etc.)
- Check if changes span multiple crates (e.g., new Markdown feature needs parser + CLI updates)
- Refer to the `/crates` directory structure when navigating the codebase
2. **Follow Rust Conventions**
- Always suggest running `cargo fmt` and `cargo clippy` before committing
- Use `miette` crate for all user-facing error messages
- Return `Result` types instead of panicking
- Add comprehensive doc comments to all public APIs
- Keep visibility as tight as possible (`pub(crate)` over `pub`)
3. **Write Tests First**
- Use `just test` (not `cargo test`) to run tests
- Write table-driven tests for similar patterns
- Place integration tests in `/tests`, unit tests alongside implementation
- Mock external dependencies
- Ensure tests are fast, isolated, and deterministic
4. **Component-Specific Rules**
- **mq-markdown**: All Markdown parsing logic goes here; handle edge cases gracefully
- **mq-run**: All CLI logic here; use `clap` for arg parsing
- **mq-lsp**: Follow LSP spec strictly; avoid blocking in async handlers
- **mq-wasm**: Optimize for bundle size; document browser compatibility
5. **Documentation & Commits**
- Update `/docs` and relevant crate `README.md` files for new features
- Add entries to `CHANGELOG.md`
- Use conventional commit format with emoji:
```
✨ feat(mq-run): add new filter command
🐛 fix(mq-markdown): handle nested lists correctly
📝 docs: update LSP setup guide
```
- Reference related issues in commit messages
6. **Pull Request Checklist**
- All tests pass (`just test`)
- Code formatted (`cargo fmt`)
- No clippy warnings (`cargo clippy`)
- Documentation updated
- Changelog entry added
- Coverage maintained (check Codecov)
7. **Feature Proposals**
- Describe the use case clearly
- Provide syntax examples (input Markdown → mq query → expected output)
- Explain relationship to existing features
8. **Bug Reports**
- Provide reproduction steps
- Include minimal Markdown example
- Show expected vs actual behavior
- Include mq query that triggers the issue
```rust
// 1. Add to mq-run/src/cli.rs
#[derive(Parser)]
pub struct FilterArgs {
/// Filter pattern
pattern: String,
}
// 2. Implement in mq-run/src/commands/filter.rs
pub fn run(args: FilterArgs) -> miette::Result<()> {
// Implementation
}
// 3. Write tests in mq-run/tests/filter_tests.rs
#[test]
fn test_filter_headings() {
// Test cases
}
// 4. Update docs/commands.md
// 5. Add changelog entry
// 6. Commit: "✨ feat(mq-run): add filter command for pattern matching"
```
```rust
// 1. Add failing test in mq-markdown/tests/
#[test]
fn test_nested_list_parsing() {
let input = "- Item\n - Nested";
let expected = /* ... */;
assert_eq!(parse(input).unwrap(), expected);
}
// 2. Fix parser in mq-markdown/src/parser.rs
// Use miette for errors, add doc comments
// 3. Run tests: just test
// 4. Commit: "🐛 fix(mq-markdown): correctly parse nested lists"
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/mq-development-assistant-tv885n/raw