Development guidelines and conventions for mq, a jq-like command-line tool for Markdown processing written in Rust
You are helping develop `mq`, a jq-like command-line tool for Markdown processing written in Rust. Follow these conventions and guidelines strictly.
`mq` allows users to slice, filter, map, and transform Markdown files using a query language similar to jq. The project is written in Rust and organized into multiple crates with specific responsibilities.
Understand the project layout:
- `mq-c-api` - C API bindings
- `mq-run` - CLI implementation
- `mq-crawler` - Directory crawling for batch processing
- `mq-dap` - Debug Adapter Protocol
- `mq-formatter` - Code formatter
- `mq-hir` - High-level Internal Representation
- `mq-lang` - Language implementation
- `mq-lsp` - Language Server Protocol
- `mq-markdown` - Markdown parser and utilities
- `mq-python` - Python bindings
- `mq-repl` - Interactive REPL
- `mq-wasm` - WebAssembly implementation
- `mq-web-api` - Web API bindings
When writing or modifying code:
1. **Format and validate**: Always run `cargo fmt` and `cargo clippy` before committing
2. **Documentation**: Add doc comments to all public functions, structs, traits, enums
3. **Error handling**: Use the `miette` crate for user-friendly error messages
4. **Avoid panics**: Return appropriate `Result` types instead
5. **Testing**: Write comprehensive tests and update related tests when changing functionality
6. **Visibility**: Use `pub(crate)` or tighter visibility unless wider exposure is necessary
7. **Dependencies**: Keep dependencies minimal and up-to-date
8. **Unsafe code**: Avoid unless absolutely necessary; document all unsafe blocks
When writing tests:
1. Use `just test` to run tests (not `cargo test`)
2. Write comprehensive tests for all new features and bug fixes
3. Use descriptive names for test functions and modules
4. Prefer table-driven tests for similar input/output patterns
5. Use `assert_eq!`, `assert!` with custom error messages for clarity
6. Avoid flaky or timing-dependent tests
7. Place integration tests in `tests/` directory, unit tests alongside implementation
8. Mock external dependencies where possible
9. Keep tests fast and isolated
10. Update/add tests when changing existing code
Use this format:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
**Types:**
Write clear, concise, descriptive messages and reference related issues/PRs.
When adding features:
1. Update documentation alongside code changes
2. Use clear, concise language with usage examples
3. Document all public APIs, commands, and features
4. Update `/docs` and crate-level `README.md` files
5. Add changelog entries for user-facing changes
6. Ensure consistency across all files and crates
7. Use Markdown best practices
Before submitting:
1. All tests pass
2. Code coverage maintained (check Codecov)
3. Code formatted and passes lint checks
4. Documentation added/updated appropriately
5. Changes recorded in `CHANGELOG.md`
When proposing features, include:
1. Description of the use case
2. Examples of proposed syntax and behavior
3. Relationship to existing features
When reporting bugs, provide:
1. Detailed description of the issue
2. Steps to reproduce
3. Expected vs. actual behavior
4. Markdown and `mq` query examples that reproduce the issue (if possible)
This project is MIT licensed. Ensure all contributions are compatible.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/mq-development-guide/raw