Development guidelines for mq, a jq-like command-line tool for Markdown processing in Rust. Covers code conventions, testing, documentation, and crate-specific rules.
Expert development assistant for `mq`, a jq-like command-line tool for Markdown processing written in Rust. Follows project-specific conventions for code quality, testing, documentation, and multi-crate architecture.
`mq` is a Rust-based tool that allows slicing, filtering, mapping, and transforming Markdown files using a jq-like syntax. The project uses a multi-crate workspace architecture with strict conventions for code quality and documentation.
1. **Formatting and Validation**
- Always run `cargo fmt` before committing
- Pass `cargo clippy` checks without warnings
- Add documentation comments to all public APIs
2. **Error Handling**
- Use `miette` crate for all user-facing errors
- Return `Result` types instead of panicking
- Provide clear, actionable error messages
3. **Testing**
- Write comprehensive tests for all functionality
- Use `just test` instead of `cargo test`
- Update related tests when changing functionality
- Prefer table-driven tests for similar patterns
4. **Documentation**
- Document all public functions, structs, traits, and enums
- Include usage examples in doc comments
- Update `/docs` and crate `README.md` files
- Add changelog entries for user-facing changes
Use conventional commits with emoji prefixes:
```
<emoji> <type>(<scope>): <description>
[optional body]
[optional footer]
```
**Types:**
**Example:**
```
āØ feat(markdown): add support for table parsing
Implements CommonMark table extension parsing.
Closes #123
```
1. **Descriptive Naming**
- Use clear, descriptive names for test functions
- Module names should reflect what's being tested
2. **Test Organization**
- Place unit tests alongside implementation
- Put integration tests in `/tests` directory
- Mock external dependencies when possible
3. **Test Quality**
- Use `assert_eq!`, `assert!` with custom messages
- Avoid flaky or timing-dependent tests
- Keep tests fast and isolated
- Update tests when changing code
4. **Run Command**
- Always use `just test` instead of `cargo test`
Before submitting, ensure:
1. ā All tests pass (`just test`)
2. ā Code coverage maintained (check Codecov)
3. ā Code formatted (`cargo fmt`)
4. ā Lints pass (`cargo clippy`)
5. ā Documentation added/updated
6. ā `CHANGELOG.md` updated
When proposing features, include:
1. Detailed use case description
2. Proposed syntax and behavior examples
3. Relationship to existing features
When reporting bugs, provide:
1. Detailed issue description
2. Steps to reproduce
3. Expected vs. actual behavior
4. Minimal reproducible example with Markdown and `mq` query
MIT License - 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-markdown-processor-development/raw