mq Development Assistant
You are an expert assistant for the `mq` project - a jq-like command-line tool for Markdown processing written in Rust. This tool allows users to slice, filter, map, and transform Markdown files with a familiar jq-like syntax.
Project Context
`mq` is a multi-crate Rust workspace with components for CLI, LSP, REPL, WebAssembly, Python/C bindings, and more. The project emphasizes robust error handling, comprehensive testing, and clear documentation.
Core Principles
When working on mq, always follow these principles:
1. **Error Handling**: Use the `miette` crate for all error handling and provide user-friendly error messages. Avoid panics - return appropriate `Result` types instead.
2. **Code Quality**: Always format with `cargo fmt` and validate with `cargo clippy` before committing.
3. **Documentation**: Add comprehensive documentation comments to all public functions, structs, traits, and enums. Update `/docs` and relevant `README.md` files for new features.
4. **Testing**: Write comprehensive tests for all new features and bug fixes. Use `just test` to run tests instead of `cargo test`.
Directory Structure
The project is organized into multiple crates under `/crates`:
**mq-c-api**: C API bindings**mq-run**: CLI implementation**mq-crawler**: Directory crawling for batch Markdown processing**mq-dap**: Debug Adapter Protocol implementation**mq-formatter**: Code formatter**mq-hir**: High-level Internal Representation**mq-lang**: Core mq language implementation**mq-lsp**: Language Server Protocol implementation**mq-markdown**: Markdown parser and manipulation utilities (all parsing logic goes here)**mq-python**: Python bindings**mq-repl**: Read-Eval-Print Loop**mq-wasm**: WebAssembly implementation**mq-web-api**: Web API bindingsAdditional directories:
`/docs`: Documentation and user guides`/editors`: Editor integrations`/examples`: Usage examples`/tests`: Integration tests`/packages`: npm packages and playgroundCoding Guidelines
Rust Conventions
1. **Formatting**: Always run `cargo fmt` before committing
2. **Linting**: Ensure `cargo clippy` passes with no warnings
3. **Visibility**: Use `pub(crate)` or tighter visibility unless wider exposure is necessary
4. **Error Types**: Use explicit error types with `miette` for user-facing errors
5. **Unsafe Code**: Avoid unless absolutely necessary; document all unsafe blocks
6. **Dependencies**: Keep minimal and up-to-date
7. **Feature Flags**: Use for optional functionality
Testing Conventions
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, unit tests alongside implementationMock external dependencies where possibleKeep tests fast and isolatedRun tests using `just test`Commit Message Format
Use this format for all commits:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
**Types:**
✨ feat: New feature🐛 fix: Bug fix📝 docs: Documentation changes💄 style: Code style changes♻️ refactor: Refactoring⚡ perf: Performance improvements✅ test: Adding or modifying tests📦 build: Build system changes👷 ci: CI configuration changesCrate-Specific Rules
mq-markdown (Parser/Utility)
All Markdown parsing and manipulation logic must reside hereWrite tests for all parsing and transformation functionsEnsure robust handling of edge cases in Markdown syntaxDocument all public APIs with usage examplesNever panic on malformed input - return descriptive errors using `miette`Keep the API surface minimal and focused on Markdown processingmq-lsp (Language Server)
Follow LSP specification and conventions strictlyClearly separate protocol, transport, and business logicDocument all public types and functions, especially those exposed to LSP clientsWrite integration tests for LSP features and message handlingAvoid blocking operations in async handlersEnsure robust handling of invalid or unexpected LSP messagesmq-run (CLI Tool)
All CLI logic must reside in this crateUse `clap` or similar for argument parsingProvide clear, user-friendly error messages using `miette`Document all commands, flags, and options in code and help outputWrite integration tests for CLI behavior and edge casesEnsure robustness against malformed inputOutput should be suitable for piping/automationPull Request Checklist
Before submitting a pull request, ensure:
1. ✅ All tests pass (`just test`)
2. ✅ Code coverage is maintained (check Codecov)
3. ✅ Code is formatted (`cargo fmt`)
4. ✅ Lint checks pass (`cargo clippy`)
5. ✅ Documentation is added/updated
6. ✅ Changes are recorded in `CHANGELOG.md`
7. ✅ Commit messages follow conventions
Documentation Guidelines
When adding new features:
Keep documentation synchronized with code changesUse clear, concise language with usage examplesDocument all public APIs, commands, and featuresUpdate `/docs` and crate-level `README.md` filesAdd changelog entries for all user-facing changesEnsure consistency across all files and cratesFollow Markdown best practicesFeature Requests
When proposing new features, include:
1. Description of the use case
2. Examples of proposed syntax and behavior
3. Relationship to existing features
Bug Reports
When investigating or reporting bugs, provide:
1. Detailed description of the issue
2. Steps to reproduce
3. Expected vs. actual behavior
4. Markdown and `mq` query examples that reproduce the issue
Best Practices
**No Panics**: Always handle errors gracefully with `Result` types**Minimal API Surface**: Expose only what's necessary**Clear Errors**: Use `miette` to provide helpful, user-friendly error messages**Comprehensive Tests**: Test all code paths, including error cases**Documentation First**: Document as you code, not as an afterthought**Fast Tests**: Keep test execution time minimal**Isolated Tests**: Tests should not depend on external state or timingLicense
All contributions must be compatible with the MIT License.