mq Development Assistant

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

What This Skill Does

Guides developers through the mq codebase, conventions, and contribution workflow. Helps with:

Instructions

When helping with mq development tasks:

1. **Understand the Architecture**

- Identify which crate(s) the task affects (`mq-run`, `mq-markdown`, `mq-lsp`, etc.)

- Check if changes span multiple crates (e.g., new Markdown feature needs parser + CLI updates)

- Refer to the `/crates` directory structure when navigating the codebase

2. **Follow Rust Conventions**

- Always suggest running `cargo fmt` and `cargo clippy` before committing

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

- Return `Result` types instead of panicking

- Add comprehensive doc comments to all public APIs

- Keep visibility as tight as possible (`pub(crate)` over `pub`)

3. **Write Tests First**

- Use `just test` (not `cargo test`) to run tests

- Write table-driven tests for similar patterns

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

- Mock external dependencies

- Ensure tests are fast, isolated, and deterministic

4. **Component-Specific Rules**

- **mq-markdown**: All Markdown parsing logic goes here; handle edge cases gracefully

- **mq-run**: All CLI logic here; use `clap` for arg parsing

- **mq-lsp**: Follow LSP spec strictly; avoid blocking in async handlers

- **mq-wasm**: Optimize for bundle size; document browser compatibility

5. **Documentation & Commits**

- Update `/docs` and relevant crate `README.md` files for new features

- Add entries to `CHANGELOG.md`

- Use conventional commit format with emoji:

```

✨ feat(mq-run): add new filter command

🐛 fix(mq-markdown): handle nested lists correctly

📝 docs: update LSP setup guide

```

- Reference related issues in commit messages

6. **Pull Request Checklist**

- All tests pass (`just test`)

- Code formatted (`cargo fmt`)

- No clippy warnings (`cargo clippy`)

- Documentation updated

- Changelog entry added

- Coverage maintained (check Codecov)

7. **Feature Proposals**

- Describe the use case clearly

- Provide syntax examples (input Markdown → mq query → expected output)

- Explain relationship to existing features

8. **Bug Reports**

- Provide reproduction steps

- Include minimal Markdown example

- Show expected vs actual behavior

- Include mq query that triggers the issue

Examples

Adding a New CLI Command

```rust

// 1. Add to mq-run/src/cli.rs

#[derive(Parser)]

pub struct FilterArgs {

/// Filter pattern

pattern: String,

}

// 2. Implement in mq-run/src/commands/filter.rs

pub fn run(args: FilterArgs) -> miette::Result<()> {

// Implementation

}

// 3. Write tests in mq-run/tests/filter_tests.rs

#[test]

fn test_filter_headings() {

// Test cases

}

// 4. Update docs/commands.md

// 5. Add changelog entry

// 6. Commit: "✨ feat(mq-run): add filter command for pattern matching"

```

Fixing a Markdown Parser Bug

```rust

// 1. Add failing test in mq-markdown/tests/

#[test]

fn test_nested_list_parsing() {

let input = "- Item\n - Nested";

let expected = /* ... */;

assert_eq!(parse(input).unwrap(), expected);

}

// 2. Fix parser in mq-markdown/src/parser.rs

// Use miette for errors, add doc comments

// 3. Run tests: just test

// 4. Commit: "🐛 fix(mq-markdown): correctly parse nested lists"

```

Constraints

Resources