mq Development Assistant
A GitHub Copilot assistant for developing `mq`, a jq-like command-line tool for Markdown processing written in Rust.
Overview
This skill helps you work on the `mq` project by providing context-aware guidance on coding conventions, architecture, testing practices, and contribution standards. Use it when writing code, creating pull requests, reporting bugs, or proposing features for mq.
Project Context
`mq` is a jq-like command-line tool for Markdown processing that allows you to slice, filter, map, and transform Markdown files. The project is structured as a multi-crate workspace with components for CLI, LSP, REPL, WebAssembly, Python/C bindings, and more.
Key Guidelines
Rust Code Conventions
**Always** format and validate code using `cargo fmt` and `cargo clippy` before committingAdd comprehensive documentation comments to all public functions, structs, traits, and enumsUse the `miette` crate for error handling with user-friendly messagesAvoid panics; return appropriate `Result` types insteadWrite thorough tests and update related tests when modifying functionalityUse `pub(crate)` or tighter visibility unless wider exposure is necessaryKeep dependencies minimal and up-to-dateDocument all `unsafe` blocks if absolutely necessaryDirectory Structure
The project follows this structure:
`/crates` - Multiple Rust crates including: - `mq-lang` - Core language implementation
- `mq-run` - CLI interface
- `mq-markdown` - Markdown parser/utilities
- `mq-lsp` - Language Server Protocol
- `mq-repl` - Interactive REPL
- `mq-wasm` - WebAssembly bindings
- `mq-python`, `mq-c-api` - Language bindings
- `mq-crawler` - Directory crawler for batch processing
`/docs` - Documentation and guides`/editors` - Editor integrations`/examples` - Usage examples`/tests` - Integration tests`/packages` - NPM packages (mq-web, playground, tools)Testing Conventions
Write comprehensive tests for all new features and bug fixesUse descriptive names for test functionsPrefer table-driven tests for similar input/output patternsUse `assert_eq!`, `assert!` with custom error messagesAvoid flaky or timing-dependent testsPlace integration tests in `/tests`, unit tests alongside implementationMock external dependencies where possible**Use `just test` instead of `cargo test`**Markdown Parser Rules (mq-markdown)
All Markdown parsing/manipulation logic must be in `mq-markdown` crateWrite tests for all parsing and transformation functionsHandle edge cases in Markdown syntax robustlyDocument all public APIs with usage examplesReturn descriptive errors using `miette` instead of panicking on malformed inputKeep API surface minimal and focusedLSP Development (mq-lsp)
Follow LSP specification and conventionsSeparate protocol, transport, and business logic clearlyDocument all public types and functions exposed to LSP clientsWrite integration tests for LSP featuresAvoid blocking operations in async handlersHandle invalid/unexpected LSP messages gracefullyCLI Development (mq-run)
All CLI logic must reside in `mq-run` crateUse `clap` for argument parsingProvide clear error messages via `miette`Document commands, flags, and options in code and help outputWrite integration tests for CLI behaviorEnsure output is suitable for piping/automationCommit Message Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
Types:
✨ `feat`: New feature🐛 `fix`: Bug fix📝 `docs`: Documentation changes💄 `style`: Code style changes♻️ `refactor`: Refactoring⚡ `perf`: Performance improvements✅ `test`: Adding/modifying tests📦 `build`: Build system changes👷 `ci`: CI configuration changesPull Request Checklist
Before submitting a PR, ensure:
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
5. Changes are recorded in `CHANGELOG.md`
Documentation Standards
Keep documentation synchronized with code changesUse clear, concise language with usage examplesDocument all public APIs, commands, and featuresUpdate `/docs` and crate-level `README.md` filesAdd changelog entries for user-facing changesUse Markdown best practicesEach independently published crate should have its own `CHANGELOG.md`Bug Reports
When reporting 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 (if possible)
Feature Requests
When proposing features, include:
1. Description of the use case
2. Examples of proposed syntax and behavior
3. Relationship to existing features
Usage Examples
Writing a new Markdown parser function
```rust
/// Extracts all headings from a Markdown document.
///
/// # Examples
///
/// ```
/// use mq_markdown::extract_headings;
///
/// let md = "# Title\n\n## Subtitle";
/// let headings = extract_headings(md)?;
/// assert_eq!(headings.len(), 2);
/// ```
///
/// # Errors
///
/// Returns an error if the Markdown is malformed.
pub fn extract_headings(input: &str) -> miette::Result<Vec<Heading>> {
// Implementation
}
```
Adding a new CLI command
```rust
// In mq-run crate
use clap::{Parser, Subcommand};
#[derive(Parser)]
struct Cli {
#[command(subcommand)]
command: Commands,
}
#[derive(Subcommand)]
enum Commands {
/// Extract headings from Markdown
Headings {
/// Input file path
#[arg(short, long)]
input: PathBuf,
},
}
```
Writing integration tests
```rust
#[test]
fn test_extract_headings() {
let cases = vec![
("# H1", vec!["H1"]),
("# H1\n## H2", vec!["H1", "H2"]),
("No headings", vec![]),
];
for (input, expected) in cases {
let result = extract_headings(input).unwrap();
assert_eq!(result, expected, "Failed for input: {}", input);
}
}
```
Important Constraints
This project is MIT licensed; all contributions must be compatibleAvoid unsafe code unless absolutely necessaryUse `miette` for all user-facing error handlingKeep crate boundaries clean and well-definedEach crate should have a clear, focused purposeAdditional Notes
Run tests with `just test`, not `cargo test`Mock external dependencies in testsKeep tests fast and isolatedUpdate documentation proactively when changing codeUse feature flags for optional functionality