mq Markdown CLI Development
You are assisting with development of `mq`, a jq-like command-line tool for Markdown processing written in Rust. Follow these guidelines when working on this codebase.
Project Overview
`mq` allows users to slice, filter, map, and transform Markdown files through a command-line interface. The project is organized as a multi-crate Rust workspace.
Directory Structure
Familiarize yourself with the main crate structure:
`/crates/mq-lang` - Core mq language implementation`/crates/mq-run` - CLI interface`/crates/mq-markdown` - Markdown parsing and manipulation`/crates/mq-lsp` - Language Server Protocol implementation`/crates/mq-repl` - Interactive REPL`/crates/mq-wasm` - WebAssembly bindings`/crates/mq-python` - Python bindings`/crates/mq-c-api` - C API bindings`/crates/mq-formatter` - Code formatter`/crates/mq-hir` - High-level Internal Representation`/crates/mq-dap` - Debug Adapter Protocol`/crates/mq-crawler` - Directory crawler for batch processing`/docs` - Documentation`/examples` - Usage examples`/tests` - Integration testsCode Quality Standards
Before Committing
1. Run `cargo fmt` to format code
2. Run `cargo clippy` to validate code
3. Run `just test` (not `cargo test`) to execute all tests
4. Ensure all tests pass
5. Check code coverage is maintained
Error Handling
Use the `miette` crate for all error handlingProvide user-friendly error messagesAvoid panics - always return appropriate `Result` typesDocument error cases in functions that can failDocumentation
Add doc comments to all public functions, structs, traits, and enumsInclude usage examples in documentationUpdate `/docs` and crate-level `README.md` files when adding featuresAdd changelog entries to `CHANGELOG.md` for all user-facing changesKeep documentation synchronized with code changesCrate-Specific Guidelines
mq-markdown (Parser/Utilities)
All Markdown parsing and manipulation logic belongs hereWrite tests for all parsing and transformation functionsHandle edge cases robustlyReturn descriptive errors using `miette` for malformed inputDocument all public APIs with usage examplesKeep API surface minimal and focusedmq-run (CLI Tool)
Use `clap` or similar for argument parsingProvide clear, user-friendly error messages using `miette`Document all commands, flags, and optionsWrite integration tests for CLI behaviorEnsure robustness against malformed inputMake output suitable for piping and automationmq-lsp (Language Server)
Follow LSP specification strictlySeparate protocol, transport, and business logic clearlyDocument all public types and LSP client-facing functionsWrite integration tests for LSP featuresAvoid blocking operations in async handlersHandle invalid or unexpected LSP messages gracefullyGeneral Crate Rules
Each crate must have a clear, documented purposeOrganize code into logical modulesUse `pub(crate)` or tighter visibility by defaultWrite comprehensive unit and integration testsMinimize and keep dependencies up-to-dateUse feature flags for optional functionalityAvoid unsafe code unless necessary; document all unsafe blocksTesting Conventions
Write comprehensive tests for all features and bug fixesUse descriptive test function namesPrefer table-driven tests for similar patternsUse `assert_eq!`, `assert!` with clear messagesAvoid flaky or timing-dependent testsPlace integration tests in `tests/`, unit tests alongside implementationMock external dependenciesKeep tests fast and isolatedUpdate tests when changing existing codeAlways run tests with `just test`Commit Message Format
Use this structure:
```
<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 or PRs when relevant.
Pull Request Checklist
Before submitting a PR, ensure:
1. All tests pass
2. Code coverage maintained (check Codecov)
3. Code is formatted (`cargo fmt`)
4. Linting passes (`cargo clippy`)
5. Documentation added/updated
6. Changes recorded in `CHANGELOG.md`
Feature 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 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 (if possible)
License
This project uses the MIT License. Ensure all contributions are compatible.