mq Development Guide

You are an expert Rust developer working on `mq`, a jq-like command-line tool for Markdown processing. Follow these guidelines when contributing to the project.

Project Overview

`mq` is a Rust-based command-line tool that allows users to slice, filter, map, and transform Markdown files using a jq-like syntax.

Directory Structure

When working with the codebase, understand this structure:

- `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` - REPL interface

- `mq-wasm` - WebAssembly implementation

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

Coding Standards

General Rust Conventions

1. **Code Quality:**

- Always run `cargo fmt` before committing

- Always run `cargo clippy` and address warnings

- Add documentation comments to all public functions, structs, traits, and enums

- Use `miette` crate for error handling with user-friendly messages

- Return appropriate `Result` types; avoid panics wherever possible

2. **Testing:**

- Use `just test` instead of `cargo test`

- Write comprehensive tests for all new features and bug fixes

- Use descriptive test function names

- Prefer table-driven tests for similar input/output patterns

- Place integration tests in `/tests`, unit tests alongside implementation

- Mock external dependencies

- Keep tests fast and isolated

- Update tests when changing existing code

3. **Documentation:**

- Keep documentation synchronized with code changes

- Use clear, concise language with usage examples

- Document all public APIs, commands, and features

- Update `/docs` and crate-level `README.md` files

- Add changelog entries for user-facing changes

- Maintain consistency across all documentation

Crate-Specific Rules

**Markdown Parser (`mq-markdown`):**

**CLI Tool (`mq-run`):**

**LSP Implementation (`mq-lsp`):**

**General Crate Guidelines:**

Commit Message Format

Use this format:

```

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

[optional body]

[optional footer]

```

**Types:**

Reference related issues or PRs when relevant.

Pull Request Checklist

Before submitting a PR, ensure:

1. All tests pass (`just test`)

2. Code coverage maintained (check Codecov)

3. Code formatted (`cargo fmt`) and lint-free (`cargo clippy`)

4. Documentation added/updated

5. Changes recorded in `CHANGELOG.md`

Feature Requests

When proposing features, include:

1. Use case description

2. Proposed syntax and behavior examples

3. Relationship to existing features

Bug Reports

When reporting bugs, provide:

1. Detailed issue description

2. Steps to reproduce

3. Expected vs. actual behavior

4. Markdown and `mq` query examples reproducing the issue

License

This project uses the MIT License. Ensure all contributions are compatible.