Guide for developing mq, a jq-like command-line tool for Markdown processing in Rust. Covers coding conventions, project structure, testing, and contribution guidelines.
You are assisting with development of `mq`, a jq-like command-line tool for Markdown processing written in Rust. Follow these guidelines when working on this project.
`mq` is a Rust-based command-line tool that allows you to slice, filter, map, and transform Markdown files using a jq-like syntax. The project is organized into multiple crates with specific responsibilities.
Understand the project structure before making changes:
- `mq-c-api` - C API for integration
- `mq-run` - CLI interface implementation
- `mq-crawler` - Directory crawler 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` - Read-Eval-Print Loop
- `mq-wasm` - WebAssembly implementation
- `mq-web-api` - Web API bindings
1. **Always format and validate code:**
- Run `cargo fmt` before committing
- Run `cargo clippy` and fix all warnings
2. **Documentation:**
- Add doc comments to all public functions, structs, traits, enums
- Include usage examples in doc comments
- Keep documentation in sync with code changes
3. **Error Handling:**
- Use `miette` crate for user-friendly error messages
- Avoid panics; return appropriate `Result` types
- Document error conditions in function documentation
4. **Testing:**
- Write comprehensive tests for all new features
- Use `just test` to run tests (not `cargo test`)
- Update related tests when changing functionality
- Use descriptive test function names
- Prefer table-driven tests for similar patterns
- Place integration tests in `tests/`, unit tests with implementation
- Keep tests fast and isolated
5. **Code Organization:**
- Organize into logical modules
- Avoid large, monolithic files
- Use `pub(crate)` or tighter visibility by default
- Each crate should have clear purpose documented in README
Format commit messages as:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
Types:
Write clear, concise, descriptive messages and reference related issues.
Before submitting a PR, ensure:
1. All tests pass
2. Code coverage maintained (check Codecov)
3. Code is formatted (`cargo fmt`)
4. Clippy passes with no warnings
5. Documentation added/updated
6. Changes recorded in `CHANGELOG.md`
When adding features:
When proposing features, include:
1. Use case description
2. Examples of proposed syntax and behavior
3. Relationship to existing features
When reporting bugs, provide:
1. Detailed issue description
2. Steps to reproduce
3. Expected vs. actual behavior
4. Markdown and `mq` query examples if possible
All contributions must be compatible with the MIT License.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/mq-development-guide-n50gu9/raw