mq Development Assistant
An expert assistant for developing mq, a jq-like command-line tool for Markdown processing. This skill helps you follow project conventions, write quality code, and maintain consistency across the mq codebase.
What This Skill Does
This skill provides guidance on:
Rust coding conventions specific to mqProject structure and crate organizationTesting conventions and best practicesDocumentation standardsPull request and commit message guidelinesFeature development and bug reportingInstructions
1. Project Understanding
When working on mq:
Recognize that mq is a jq-like command-line tool for Markdown processing written in RustUnderstand the multi-crate structure under `/crates` directoryKnow the key crates: `mq-lang` (core language), `mq-markdown` (parser), `mq-run` (CLI), `mq-lsp` (Language Server), `mq-repl`, `mq-wasm`, and othersReference the appropriate crate based on the task2. Rust Coding Conventions
Always follow these practices:
Format code with `cargo fmt` and validate with `cargo clippy` before committingAdd documentation comments (///) to all public functions, structs, traits, enumsUse the `miette` crate for error handling with user-friendly messagesAvoid panics; return appropriate `Result` types insteadWrite comprehensive tests for new functionalityKeep each crate focused with clear purposeUse `pub(crate)` or tighter visibility unless wider exposure is necessaryAvoid unsafe code unless absolutely necessary; document all unsafe blocksKeep dependencies minimal and up-to-date3. Testing Conventions
When writing tests:
Write comprehensive tests for all new features and bug fixesUse descriptive names for test functions and modulesPrefer table-driven tests for similar input/output patternsUse `assert_eq!`, `assert!`, and custom error messages for clarityAvoid flaky or timing-dependent testsPlace integration tests in `tests/` directory and unit tests alongside implementationMock external dependencies where possibleKeep tests fast and isolatedRun tests with `just test` instead of `cargo test`Update or add tests when changing existing code4. Documentation Standards
For all documentation:
Keep documentation up-to-date with code changesUse clear, concise language and provide usage examplesDocument all public APIs, commands, and featuresUpdate `/docs` and crate-level `README.md` files for new featuresAdd changelog entries to `CHANGELOG.md` for all user-facing changesEach published crate should have its own `CHANGELOG.md`Use Markdown best practices for formatting and structure5. Crate-Specific Rules
**mq-markdown (Parser/Utilities):**
All Markdown parsing and manipulation logic must reside hereWrite tests for all parsing and transformation functionsHandle edge cases in Markdown syntax robustlyAvoid panics on malformed input; return descriptive errors using `miette`Keep the API surface minimal and focused**mq-run (CLI Tool):**
All command-line interface logic must reside hereUse `clap` or similar for argument parsingProvide clear, user-friendly error messages using `miette`Document all commands, flags, and optionsWrite integration tests for CLI behaviorEnsure output is suitable for piping/automation**mq-lsp (Language Server):**
Follow LSP specification and conventionsSeparate protocol, transport, and business logic clearlyDocument all public types and functionsWrite integration tests for LSP featuresAvoid blocking operations in async handlersHandle invalid or unexpected LSP messages robustly6. 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 changes that don't affect behavior♻️ refactor: Refactoring⚡ perf: Performance improvements✅ test: Adding or modifying tests📦 build: Changes to build system or external dependencies👷 ci: Changes to CI configuration files and scriptsReference related issues or pull requests when relevant.
7. Pull Request Checklist
Before submitting a PR, ensure:
1. All tests pass
2. Code coverage is maintained (check with Codecov)
3. Code is formatted and passes lint checks (`cargo fmt`, `cargo clippy`)
4. Appropriate documentation is added/updated
5. Changes are recorded in `CHANGELOG.md`
8. Feature Requests
When proposing new features, include:
1. Description of the use case
2. Examples of the proposed syntax and behavior
3. Relationship to existing features
9. Bug Reports
When reporting bugs, provide:
1. Detailed description of the issue
2. Steps to reproduce
3. Expected behavior vs. actual behavior
4. Markdown and mq query examples that reproduce the issue (if possible)
Directory Structure Reference
`/crates` - Multiple Rust crates (mq-lang, mq-markdown, mq-run, mq-lsp, etc.)`/docs` - Documentation and user guides`/editors` - Editor integrations and plugins`/assets` - Static assets`/examples` - Usage examples`/tests` - Integration tests`/scripts` - Automation scripts`/packages` - npm packages (mq-web, playground, tools)Constraints
Project is under MIT LicenseUse `miette` for all user-facing error handlingRun tests with `just test` commandAll Markdown processing must go through `mq-markdown` crateMaintain backwards compatibility when possible