mq Development Assistant
Expert assistant for developing **mq**, a jq-like command-line tool for Markdown processing written in Rust.
What This Skill Does
Helps you work on the mq project by:
Ensuring code follows Rust and mq-specific conventionsGuiding you through the multi-crate architectureEnforcing testing and documentation standardsAssisting with LSP, WASM, CLI, and parser developmentMaintaining commit message and PR standardsInstructions
When working on the mq project, follow these guidelines:
1. Code Quality Standards
**Before any code change:**
Run `cargo fmt` to format codeRun `cargo clippy` to validate code qualityAdd documentation comments to all public functions, structs, traits, and enumsUse the `miette` crate for error handling with user-friendly messagesAvoid panics; return appropriate `Result` types insteadWrite comprehensive tests for all new functionality2. Project Structure
Understand the multi-crate architecture:
**Core Crates:**
`mq-lang` - mq language implementation`mq-markdown` - Markdown parser and manipulation (all parsing logic goes here)`mq-hir` - High-level Internal Representation`mq-run` - CLI implementation (all command-line logic goes here)`mq-lsp` - Language Server Protocol implementation`mq-formatter` - Code formatter`mq-repl` - Read-Eval-Print Loop`mq-crawler` - Directory crawler for batch processing`mq-dap` - Debug Adapter Protocol**Integrations:**
`mq-c-api` - C API bindings`mq-python` - Python bindings`mq-wasm` - WebAssembly implementation`mq-web-api` - Web API bindings**Other Directories:**
`/docs` - Documentation and guides`/editors` - Editor integrations`/examples` - Usage examples`/tests` - Integration tests`/packages` - npm packages (mq-web, playground, tools)3. Testing Requirements
**Always:**
Write comprehensive tests for new features and bug fixesUse descriptive names for test functionsPrefer table-driven tests for similar patternsUse `assert_eq!`, `assert!` with clear error messagesKeep tests fast and isolatedRun tests with `just test` (not `cargo test`)Place integration tests in `/tests`, unit tests alongside implementationMock external dependenciesUpdate existing tests when changing functionality4. Documentation Standards
**When adding features:**
Update `/docs` and relevant crate `README.md` filesAdd entries to `CHANGELOG.md`Document all public APIs with Rust doc commentsProvide usage examples in documentationKeep documentation consistent across cratesUse clear, concise language5. Crate-Specific Rules
**mq-markdown (Parser/Utility):**
All Markdown parsing and manipulation must go hereTest all parsing and transformation functionsHandle edge cases robustlyReturn descriptive errors (no panics on malformed input)Keep API surface minimal and focused**mq-run (CLI Tool):**
All CLI logic must go hereUse `clap` for argument parsingProvide clear error messages using `miette`Document commands, flags, options in code and help outputEnsure output is suitable for piping/automation**mq-lsp (Language Server):**
Follow LSP specification strictlySeparate protocol, transport, and business logicDocument all types exposed to LSP clientsNo blocking operations in async handlersHandle invalid/unexpected LSP messages robustly**All Crates:**
Each crate must have clear purposeUse logical module organizationUse `pub(crate)` or tighter visibility by defaultMinimize dependenciesDocument unsafe blocks (avoid unsafe unless necessary)Use feature flags for optional functionality6. Commit Message Format
Use this format:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
**Types:**
✨ feat: New feature🐛 fix: Bug fix📝 docs: Documentation changes💄 style: Code style (no behavior change)♻️ refactor: Refactoring⚡ perf: Performance improvements✅ test: Adding/modifying tests📦 build: Build system changes👷 ci: CI configuration changesReference related issues/PRs when relevant.
7. Pull Request Checklist
Before creating a PR:
[ ] All tests pass[ ] Code coverage maintained (check Codecov)[ ] Code formatted (`cargo fmt`)[ ] Lint checks pass (`cargo clippy`)[ ] Documentation added/updated[ ] `CHANGELOG.md` updated8. Feature Requests
When proposing features, include:
1. Use case description
2. Proposed syntax and behavior examples
3. Relationship to existing features
9. Bug Reports
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)
Example Usage
**Adding a new Markdown transformation:**
1. Add parsing logic to `mq-markdown`
2. Write comprehensive tests with edge cases
3. Add integration tests in `/tests`
4. Document the new feature in `/docs`
5. Update `CHANGELOG.md`
6. Run `cargo fmt` and `cargo clippy`
7. Run `just test` to verify all tests pass
8. Commit with: `✨ feat(markdown): add support for table filtering`
**Fixing a CLI bug:**
1. Add regression test in `mq-run`
2. Fix the issue with proper error handling
3. Update documentation if behavior changes
4. Run `just test`
5. Commit with: `🐛 fix(cli): handle empty input gracefully`
Important Notes
**License:** All contributions must be MIT-compatible**Error Handling:** Always use `miette` for user-facing errors**No Panics:** Return `Result` types instead**Test Runner:** Use `just test`, not `cargo test`**Code Coverage:** Maintain existing coverage levels**Documentation:** Keep docs synchronized with code changes