mq Development Assistant
Expert assistant for developing and contributing to `mq`, a jq-like command-line tool for Markdown processing written in Rust.
What This Skill Does
Provides guidance on mq development following project conventions, including:
Rust coding standards and best practicesProject structure and crate organizationTesting, documentation, and PR requirementsLSP, CLI, and parser implementation guidelinesInstructions
When working on mq:
1. Code Quality Standards
**Always enforce these Rust conventions:**
Format code with `cargo fmt` before committingRun `cargo clippy` and address all warningsAdd documentation comments to all public items (functions, structs, traits, enums)Use `miette` crate for error handling with user-friendly messagesReturn `Result` types instead of panickingWrite comprehensive tests for all changes2. Project Structure Awareness
**Understand the crate organization:**
`mq-c-api` - C API bindings`mq-run` - CLI implementation (entry point)`mq-crawler` - Directory crawler for batch processing`mq-dap` - Debug Adapter Protocol`mq-formatter` - Code formatter`mq-hir` - High-level Internal Representation`mq-lang` - Core language implementation`mq-lsp` - Language Server Protocol`mq-markdown` - Markdown parser and utilities (core parsing logic)`mq-python` - Python bindings`mq-repl` - Interactive REPL`mq-wasm` - WebAssembly bindings`mq-web-api` - Web API bindings**Place code in the appropriate crate based on functionality.**
3. Testing Guidelines
**Run tests using:**
```bash
just test
```
**Follow these testing conventions:**
Write comprehensive tests for all features and fixesUse descriptive test function namesPrefer table-driven tests for similar patternsUse `assert_eq!`, `assert!` with custom messagesAvoid flaky or timing-dependent testsPlace integration tests in `tests/` directoryKeep unit tests alongside implementationMock external dependenciesKeep tests fast and isolatedUpdate tests when changing existing code4. Markdown Parser Rules
**When working in `mq-markdown`:**
Keep all parsing/manipulation logic in this crateTest all parsing and transformation functionsHandle edge cases in Markdown syntax robustlyDocument all public APIs with usage examplesReturn descriptive errors (no panics on malformed input)Keep API surface minimal and focused5. CLI Tool Rules
**When working in `mq-run`:**
Keep all CLI logic in this crateUse `clap` for argument parsingProvide user-friendly error messages with `miette`Document commands, flags, and options in code and help outputWrite integration tests for CLI behaviorHandle malformed input gracefullyEnsure output is suitable for piping/automation6. LSP Implementation Rules
**When working in `mq-lsp`:**
Follow LSP specification strictlySeparate protocol, transport, and business logicDocument all public types and functionsWrite integration tests for LSP featuresUse `miette` for user-facing errorsAvoid blocking operations in async handlersHandle invalid/unexpected LSP messages robustly7. 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 changes8. Pull Request Checklist
**Before submitting PRs, ensure:**
[ ] All tests pass (`just test`)[ ] Code coverage maintained (check Codecov)[ ] Code formatted (`cargo fmt`)[ ] Lint checks pass (`cargo clippy`)[ ] Documentation added/updated[ ] Changes recorded in `CHANGELOG.md`9. Documentation Standards
**When documenting:**
Update `/docs` and crate-level `README.md` filesUse clear, concise language with usage examplesDocument all public APIs, commands, and featuresAdd changelog entries for user-facing changesEnsure consistency across all filesFollow Markdown best practices10. General Crate Rules
**For all crates:**
Each crate must have a clear, documented purposeOrganize code into logical modules (avoid monolithic files)Use `pub(crate)` or tighter visibility by defaultUse explicit error types with `miette`Write comprehensive testsDocument all public APIsAvoid unsafe code (document when necessary)Use feature flags for optional functionalityKeep dependencies minimal and currentExamples
**Bug Report Format:**
When reporting bugs, include:
1. Detailed issue description
2. Steps to reproduce
3. Expected vs. actual behavior
4. Markdown and `mq` query examples demonstrating the issue
**Feature Request Format:**
When proposing features, include:
1. Use case description
2. Proposed syntax and behavior examples
3. Relationship to existing features
Constraints
All contributions must be MIT License compatibleAvoid panics; return proper `Result` typesUse `miette` for all user-facing errorsRun `just test` instead of `cargo test`All Markdown parsing must stay in `mq-markdown`All CLI logic must stay in `mq-run`Follow LSP specification for `mq-lsp` work