Developer Tooling Setup#

This project uses a comprehensive, cross-platform developer tooling setup to ensure code and documentation quality. The main tools are MegaLinter for automated linting, cspell for spell checking, Prettier for formatting, and a Justfile for orchestrating formatting and linting tasks. Pre-commit hooks further enforce standards automatically.

MegaLinter Configuration#

MegaLinter is configured via .mega-linter.yml to provide automated linting across code, documentation, and configuration files. All safe linter fixes are applied automatically (APPLY_FIXES: all). The configuration excludes generated and dependency directories such as target, dist, build, node_modules, .git, .cache, coverage, docs/book, and docs/build from linting to avoid unnecessary noise and false positives. Specific files, like .github/workflows/release.yml, are also excluded using regex filters.

MegaLinter integrates with ActionLint for GitHub Actions workflow validation, with custom arguments to suppress certain shellcheck issues in generated files. Lychee is used for link checking, excluding loopback, private, and mail links, and setting a 10-second timeout. Markdown table formatting is enabled but excludes README.md from formatting. Prettier is run in check mode for JSON and YAML files and respects the .prettierignore file for exclusions. See the MegaLinter configuration for details.

Spell Checking with cspell#

Spell checking is managed by cspell, configured in cspell.config.yaml. The configuration uses English as the primary language and includes multiple dictionaries: en_US, rust, bash, softwareTerms, companies, and misc. It leverages .gitignore to exclude files and directories from spell checking and allows compound words with case insensitivity to reduce false positives.

Ignored paths include build artifacts, dependencies, lock files, and specific workflow files. Regular expressions further exclude hex hashes, UUIDs, URLs, file paths, code fences, inline code, Mermaid diagrams, and base64-like strings. Language-specific settings tailor dictionaries and compound word rules for markdown, YAML, TOML, and JSON files. Project-specific technical terms are whitelisted to avoid unnecessary warnings. See the cspell configuration for details.

Prettier Formatting Rules and Ignore Files#

Prettier enforces consistent formatting for JSON and YAML files. The .prettierignore file excludes Markdown files (*.md, **/*.md), generated files (target/, dist/, build/, node_modules/, docs/book/), and .github/workflows/release.yml from formatting in StringyMcStringFace. In libmagic-rs, .prettierignore excludes all Markdown (**/*.md) and YAML (**/*.yml) files from formatting. This ensures that only relevant files are formatted and avoids conflicts with other formatting tools or generated content. See the StringyMcStringFace .prettierignore and libmagic-rs .prettierignore.

Justfile Recipes for Formatting and Linting#

The Justfile defines recipes for formatting, linting, and environment setup. These recipes are cross-platform and provide a single entry point for contributors to maintain code and documentation quality.

Key recipes include:

• format: Runs all formatters (Rust, JSON/YAML with Prettier, Markdown with mdformat, Justfile).
• lint: Runs all linters (Rust with clippy, spell checking with cspell, markdownlint, lychee for link checking, actionlint for GitHub Actions, Justfile linting).
• setup: Installs Rust components (rustfmt, clippy, llvm-tools-preview), cargo-binstall, and Python tools (mdformat and its extensions via pipx).
• megalinter: Runs MegaLinter with the Rust flavor.
• Aliases like format-rust, format-md, and format-just provide shortcuts for common formatting tasks.

Example usage:

just setup # Install all required development tools
just format # Format all code and documentation
just lint # Run all linters and spell checkers
just megalinter # Run MegaLinter for comprehensive linting

If a formatter like mdformat is not installed, the Justfile will prompt you to run the appropriate install recipe (e.g., just mdformat-install). See the StringyMcStringFace Justfile and libmagic-rs Justfile for details.

Maintaining Code and Documentation Quality#

These tools work together to enforce consistent style, catch errors early, and maintain high standards for both code and documentation. Pre-commit hooks automatically run formatting and linting checks before commits, including Rust formatting/linting, shell script validation, markdown formatting, and commit message linting. Contributors are expected to use the Justfile recipes for formatting and linting; pre-commit hooks will enforce standards automatically. Manual invocation of spell checking (just lint-spell) and MegaLinter (just megalinter) is also possible.

By following this workflow, contributors help ensure that the codebase remains clean, consistent, and free of common errors.