mq Development Assistant

Assists with developing mq, a jq-like command-line tool for Markdown processing written in Rust. Enforces project conventions, coding standards, and best practices specific to this multi-crate Rust project.

Project Context

mq is a Rust-based CLI tool that allows users to slice, filter, map, and transform Markdown files using a jq-like query syntax. The project consists of multiple crates organized under `/crates`, each serving a specific purpose.

Directory Structure

When working with mq, recognize these key directories:

- `mq-c-api` - C API bindings

- `mq-run` - CLI implementation

- `mq-crawler` - Directory crawling 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

- `mq-python` - Python bindings

- `mq-repl` - Interactive REPL

- `mq-wasm` - WebAssembly implementation

- `mq-web-api` - Web API bindings

Coding Conventions

Rust Code Standards

1. **Formatting & Linting**

- Always run `cargo fmt` before committing

- Ensure `cargo clippy` passes with no warnings

- Address all clippy suggestions unless explicitly documented otherwise

2. **Documentation**

- Add doc comments (`///`) to all public functions, structs, traits, and enums

- Include usage examples in doc comments where appropriate

- Keep crate-level `README.md` files updated for new features

3. **Error Handling**

- Use the `miette` crate for user-facing error messages

- Return `Result` types instead of panicking

- Provide descriptive, actionable error messages

- Document all unsafe blocks if unavoidable

4. **Testing**

- Write comprehensive unit and integration tests

- Use descriptive test function names

- Prefer table-driven tests for similar patterns

- Run tests using `just test` (not `cargo test`)

- Keep tests fast and isolated

- Mock external dependencies where possible

5. **Code Organization**

- Use `pub(crate)` or tighter visibility by default

- Organize code into logical modules

- Avoid large monolithic files

- Keep dependencies minimal and up-to-date

Crate-Specific Rules

**mq-markdown (Parser/Utility):**

**mq-lsp (Language Server):**

**mq-run (CLI):**

Commit Message Format

Use this format for all commits:

```

<type>(<scope>): <description>

[optional body]

[optional footer]

```

**Types:**

Write clear, concise messages and reference related issues when relevant.

Documentation Requirements

When adding features or making changes:

1. Update relevant documentation in `/docs`

2. Update crate-level `README.md` files

3. Add changelog entries to `CHANGELOG.md`

4. Ensure documentation consistency across all files

5. Provide usage examples for new features

6. Document all public APIs in code comments

Pull Request Checklist

Before creating a PR, ensure:

1. All tests pass (`just test`)

2. Code coverage maintained (check Codecov)

3. `cargo fmt` and `cargo clippy` pass cleanly

4. Appropriate documentation added/updated

5. Changes recorded in `CHANGELOG.md`

6. Feature requests include use cases and syntax examples

Testing Strategy

Feature Development

When proposing new features:

1. Describe the use case clearly

2. Provide syntax and behavior examples

3. Explain relationship to existing features

4. Consider impact on all relevant crates

Bug Reporting

When encountering bugs:

1. Provide detailed description

2. Include steps to reproduce

3. Document expected vs. actual behavior

4. Share Markdown and `mq` query examples if possible

Best Practices