mq AGENTS.md

mq Development Guide

Project Overview

mq is a jq-like command-line tool for Markdown processing. Written in Rust, it allows you to easily slice, filter, map, and transform Markdown files.

Coding Conventions

Rust Code Conventions

• Always format and validate code using cargo fmt and cargo clippy
• Add appropriate documentation comments to all public functions, structs, traits, enums, etc.
• Use the miette crate for error handling and provide user-friendly error messages
• Avoid panics whenever possible and return appropriate Result types
• Write comprehensive tests and update related tests when adding or changing functionality

Commit Message Conventions

Use the following format for commit messages:

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

[optional body]

[optional footer]

• Types include:
  • ✨ feat: New feature
  • 🐛 fix: Bug fix
  • 📝 docs: Documentation changes
  • 💄 style: Code style changes that don't affect behavior
  • ♻️ refactor: Refactoring
  • ⚡ perf: Performance improvements
  • ✅ test: Adding or modifying tests
  • 📦 build: Changes to build system or external dependencies
  • 👷 ci: Changes to CI configuration files and scripts
• Write clear, concise, and descriptive commit messages.
• Reference related issues or pull requests when relevant.

Documentation Guidelines

When adding new features, update the documentation.

• Keep documentation up-to-date with code changes.
• Use clear, concise language and provide usage examples.
• Document all public APIs, commands, and features.
• Update /docs and crate-level README.md files for new features or changes.
• Add changelog entries for all user-facing changes.
• Ensure documentation is consistent across all files and crates.
• Use Markdown best practices for formatting and structure.

Testing Conventions

• Write comprehensive tests for all new features and bug fixes.
• Use descriptive names for test functions and modules.
• Prefer table-driven tests for similar input/output patterns.
• Use assert_eq!, assert!, and custom error messages for clarity.
• Avoid flaky or timing-dependent tests.
• Place integration tests in the tests/ directory and unit tests alongside implementation.
• Mock external dependencies where possible.
• Keep tests fast and isolated.
• Update or add tests when changing existing code.