mq Development Assistant

Expert assistant for developing and contributing to `mq`, a jq-like command-line tool for Markdown processing written in Rust.

Overview

This skill provides guidance for working on the `mq` project, which allows you to slice, filter, map, and transform Markdown files using a jq-like syntax. The tool is built in Rust and includes multiple crates for different functionalities including CLI, LSP, WASM, Python bindings, and more.

Instructions

Understanding the Project Structure

When working with `mq`, familiarize yourself with the multi-crate architecture:

Code Quality Standards

Always ensure your code meets these requirements:

1. **Format and validate** using `cargo fmt` and `cargo clippy` before committing

2. **Add documentation comments** to all public functions, structs, traits, and enums

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

4. **Return `Result` types** instead of panicking

5. **Write comprehensive tests** for all new code and update tests when modifying existing code

6. **Run tests** using `just test` (not `cargo test`)

Writing New Features

When implementing new features:

1. **Determine the correct crate** - Place code in the appropriate crate based on functionality

2. **Use `pub(crate)` visibility** unless wider exposure is necessary

3. **Create minimal, focused APIs** - Keep interfaces simple and purpose-driven

4. **Document with examples** - Include usage examples in doc comments

5. **Handle edge cases** - Never panic on malformed input; return descriptive errors

6. **Update documentation** - Modify `/docs`, crate `README.md`, and `CHANGELOG.md`

7. **Write tests first** - Use table-driven tests for similar patterns, keep tests fast and isolated

Markdown Parser Development

When working on `mq-markdown`:

CLI Development

When working on `mq-run`:

LSP Development

When working on `mq-lsp`:

Testing Guidelines

Follow these testing conventions:

Commit Message Format

Use this format for all commits:

```

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

[optional body]

[optional footer]

```

**Types:**

Reference related issues or PRs when relevant.

Pull Request Checklist

Before submitting a PR, verify:

1. All tests pass (`just test`)

2. Code coverage is maintained (check Codecov)

3. Code is formatted (`cargo fmt`) and passes lint (`cargo clippy`)

4. Documentation is added/updated for new features

5. Changes are recorded in `CHANGELOG.md`

Bug Reporting Format

When reporting or documenting bugs, include:

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

Feature Proposal Format

When proposing new features, include:

1. Description of the use case

2. Examples of proposed syntax and behavior

3. Relationship to existing features

Best Practices

License

This project is under the MIT License. Ensure all contributions are compatible.