If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rust-lang/rustfmt shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 43+ active contributors
• Distributed ownership (top contributor 18% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rust-lang/rustfmt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rust-lang/rustfmt.

What it runs against: a local clone of rust-lang/rustfmt — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rust-lang/rustfmt | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rust-lang/rustfmt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rust-lang/rustfmt.git
#   cd rustfmt
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rust-lang/rustfmt and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rust-lang/rustfmt(\\.git)?\\b" \\
  && ok "origin remote is rust-lang/rustfmt" \\
  || miss "origin remote is not rust-lang/rustfmt (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/bin/main.rs" \\
  && ok "src/bin/main.rs" \\
  || miss "missing critical file: src/bin/main.rs"
test -f "src/formatting.rs" \\
  && ok "src/formatting.rs" \\
  || miss "missing critical file: src/formatting.rs"
test -f "src/config/mod.rs" \\
  && ok "src/config/mod.rs" \\
  || miss "missing critical file: src/config/mod.rs"
test -f "src/emitter/mod.rs" \\
  && ok "src/emitter/mod.rs" \\
  || miss "missing critical file: src/emitter/mod.rs"
test -f "src/cargo-fmt/main.rs" \\
  && ok "src/cargo-fmt/main.rs" \\
  || miss "missing critical file: src/cargo-fmt/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rust-lang/rustfmt"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

rustfmt is the official Rust code formatter that automatically reformats Rust source code according to the Rust style guidelines. It works as a standalone tool (rustfmt binary) and integrates with Cargo (cargo fmt), handling both well-formed code and partial program fragments by leveraging the rustc compiler's AST parsing infrastructure. The project aims for post-1.0 stability where code formatting doesn't change as the tool improves. Multi-binary workspace: src/bin/main.rs (rustfmt CLI), src/cargo-fmt/main.rs (cargo integration), src/format-diff/main.rs (diff viewer), src/git-rustfmt/main.rs (git hook). Supporting subprojects: config_proc_macro/ (derives for configuration), check_diff/ (diff validation tooling), ci/ (build orchestration). Core formatting logic resides in src/ with configuration system driven by procedural macros (config_proc_macro/src/config_type.rs).

Rust developers and teams who need consistent code style across projects; CI/CD pipeline maintainers integrating linting checks; open-source Rust project maintainers enforcing style standards. Contributors are primarily Rust compiler and tooling enthusiasts working on AST manipulation and code generation.

Production-ready and actively maintained. rustfmt is distributed as an official rustup component (stable and nightly channels), has comprehensive CI across Linux/Mac/Windows (.github/workflows/), and uses semver versioning (currently 1.9.0). The codebase is 2.6M lines of Rust with established testing patterns (test suites in tests/ directories across subprojects) and active development visible through integration testing infrastructure (check_diff/, ci/ subprojects).

Low risk for dependencies—uses lean, well-vetted crates (serde, regex, unicode-segmentation) with no obvious unmaintained packages. Moderate risk from tight coupling to rustc internals: the build.rs requires nightly compiler features (rustc_private) and the code explicitly depends on rustc's unstable APIs, meaning breaking changes in rustc could require rapid updates. Single-point-of-failure risk mitigated by being part of the official Rust toolchain distribution, ensuring resource allocation.

Active development on configuration system improvements (config_proc_macro with attrs.rs, config_type.rs, item_enum.rs). Integration testing infrastructure is being maintained (.github/workflows/integration.yml). The Subtree sync procedure (referenced in repo root) indicates ongoing synchronization with rustc repository for AST changes.

git clone https://github.com/rust-lang/rustfmt.git
cd rustfmt
cargo build --release
cargo test

For nightly features (required due to rustc_private): rustup install nightly && cargo +nightly build

Daily commands: Development: cargo build && cargo run -- --help or cargo fmt to format current directory. Tests: cargo test. Format check (CI): cargo fmt -- --check. For nightly-only features: cargo +nightly build. The Makefile.toml may contain additional task definitions.

• src/bin/main.rs — Entry point for the rustfmt binary; handles CLI argument parsing and orchestrates the formatting pipeline.
• src/formatting.rs — Core formatting logic and main public API that transforms Rust source code into formatted output.
• src/config/mod.rs — Configuration system that loads, parses, and applies rustfmt.toml settings across the entire codebase.
• src/emitter/mod.rs — Output abstraction layer that handles writing formatted code to files, stdout, or other destinations in various formats (diff, JSON, checkstyle).
• src/cargo-fmt/main.rs — Cargo integration binary that discovers and formats multiple Rust files in a workspace; critical for end-user experience.
• config_proc_macro/src/lib.rs — Procedural macro that generates configuration boilerplate; reduces manual work and ensures consistency across config options.
• build.rs — Build script that likely generates code or configuration at compile time; essential for understanding pre-compiled artifacts.

Add a New Formatting Configuration Option

1. Define the option type and metadata in src/config/options.rs with appropriate documentation. (src/config/options.rs)
2. Add the field to the Config struct using the #[config_type] proc-macro in src/config/config_type.rs. (src/config/config_type.rs)
3. Implement logic that reads the option value and applies it during formatting in src/formatting.rs or relevant module (expr.rs, chains.rs, etc.). (src/formatting.rs)
4. Add test cases and update Configurations.md documentation with examples and default behavior. (Configurations.md)

Add Support for a New Output Format

1. Create a new file in src/emitter/ (e.g., src/emitter/myformat.rs) implementing the Emitter trait. (src/emitter/mod.rs)
2. Implement the output logic, handling formatted code and optional report metadata in your new emitter. (src/emitter/myformat.rs)
3. Register the emitter in src/emitter/mod.rs and route to it from the CLI argument parser in src/bin/main.rs. (src/bin/main.rs)
4. Add integration tests and documentation for the new format in check_diff or CI utilities. (ci/src/integration.rs)

Extend Formatting Rules for a New Syntax Element

1. Analyze the AST pattern for your syntax element using rustc's syn crate and add matching logic. (src/formatting.rs)
2. Implement the formatting function in a specialized module (src/expr.rs for expressions, src/closures.rs for closures, etc.). (src/expr.rs)
3. Read any relevant configuration options from the Config struct to customize spacing, indentation, and wrapping. (src/config/options.rs)
4. Write comprehensive tests and run check_diff against rustfmt's own source and integration test suites. (check_diff/src/main.rs)

• syn + proc-macro2 (AST parsing) — Provides robust, compiler-aligned Rust syntax tree parsing; used in config macros and formatting logic to handle all Rust constructs accurately.
• Procedural Macros (config_proc_macro) — Eliminates repetitive boilerplate for config serialization/deserialization; allows declarative option definitions with automatic code generation.
• Unified Diff Output (emitter/diff.rs) — Standard format for version control and CI/CD integration; allows developers to see exact changes before applying them.
• Multiple Emitter Strategies (JSON, checkstyle, files) — Supports diverse integration scenarios: IDEs (JSON), enterprise CI (checkstyle), direct formatting (files); decouples output from formatting logic.

• Single-pass formatting without iterative refinement

  • Why: Simpler implementation, faster execution (~100–200ms per file); avoids overhead of multiple AST traversals.
  • Consequence: Some complex nested structures may not achieve optimal layout; trade speed for perfection on edge cases.

• Config cascading: rustfmt.toml → parent directories → defaults

  • Why: Allows per-directory and per-project formatting rules; essential for monorepos and heterogeneous codebases.
  • Consequence: Configuration lookup adds latency and complexity; developers must understand precedence rules.

• Cargo integration via separate cargo-fmt binary instead of rustup component hook

  • Why: Isolated process avoids conflicts with Cargo internals; cleaner separation of concerns.
  • Consequence: Requires duplicate workspace discovery logic; slightly slower invocation due to process spawn.

• Comment preservation as separate pass (not embedded in AST)

  • Why: Rust AST (syn) discards comments; re-attaching them requires heuristic alignment with code spans.
  • Consequence: Comment formatting is fragile and may misalign in pathological cases; developers must test comment-heavy code manually.

• Does not refactor or optimize code semantics (e.g., no dead-code elimination or import optimization).
• Does not validate Rust syntax or type-check code (relies on compiler for that).
• Does not handle language features from unstable/nightly Rust unless explicitly configured via style_edition.
• Does not provide real-time formatting in editors

Rustc nightly requirement: build.rs and source use #[feature(rustc_private)], mandating a nightly Rust toolchain; stable will fail. AST breakage: Any rustc compiler update can break internal APIs rustfmt depends on—watch rustc release notes. Macro expansion dependency: rustfmt relies on full macro expansion during parsing, so code with unexpandable macros will fail to format (documented limitation but surprising to new users). Subtree sync complexity: the repo maintains a subtree relationship with rust-lang/rust for AST types—manual syncs are error-prone (see 'Subtree sync procedure.md'). Config proc macro builds: config_proc_macro must be built before main crate in workspace; parallel builds can fail if not sequenced correctly.

• AST Visitor Pattern — rustfmt traverses the Rust AST using visitor pattern to format each node; understanding how visitors compose is essential to extending formatting rules
• Macro Expansion — rustfmt requires full macro expansion during parsing to format code correctly; handling unexpandable macros is a documented limitation affecting real-world codebases
• Procedural Macros (derive) — The config system is built on procedural macros (config_proc_macro crate); learning how derive macros work is needed to extend configuration options
• Rustc Private API Stability — rustfmt uses rustc_private features that explicitly have no stability guarantees; changes in rustc nightly can break rustfmt, requiring rapid fixes
• Unified Diff Format — The format-diff binary produces unified diffs for CI integration; understanding diff semantics is needed to interpret rustfmt's output in pipelines
• Regression Testing via Snapshot Diffing — check_diff/ subproject uses differential testing to ensure formatting stability post-1.0; new features must pass regression suite or they break the stability guarantee
• Line-Length and Unicode Width Calculation — rustfmt uses unicode-width and unicode-segmentation crates to correctly measure display width (handling tabs, East Asian characters, etc.); mishandling breaks line-length constraints

• rust-lang/rust — The parent Rust compiler repository—rustfmt depends on rustc_private AST types and is synced via subtree
• rust-lang/clippy — Sibling Rust linting tool that also uses rustc internals; shares CI patterns and contributor base
• prettier/prettier — Conceptual predecessor in JavaScript ecosystem demonstrating opinionated code formatting without configuration; influenced rustfmt's philosophy of minimal config options
• golang/gofmt — Go's built-in formatter that inspired Rust's commitment to single canonical style and non-negotiable formatting rules
• rust-lang/rust-clippy — Companion linting tool; rustfmt and clippy are used together in most Rust projects for full style coverage

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for git-rustfmt binary

The repo has src/git-rustfmt/main.rs but no visible test directory for it (unlike src/cargo-fmt/test/ which has message_format.rs). Git integration is a critical feature that deserves dedicated test coverage for scenarios like formatting staged files, handling merge conflicts, and validating git output parsing.

• [ ] Create src/git-rustfmt/test/ directory structure
• [ ] Add tests for git commit parsing and file extraction
• [ ] Add tests for staged vs unstaged file handling
• [ ] Add tests for error cases (invalid git repo, merge conflicts)
• [ ] Integrate tests into CI workflows (linux.yml, mac.yml, windows.yml)

Add missing tests for format-diff binary and enhance check_diff test coverage

The Cargo.toml references src/format-diff/main.rs but there's no visible test directory for it. Meanwhile, check_diff/tests/ has basic tests but the format-diff binary (which is a featured tool) lacks dedicated integration tests for diff parsing, output formatting, and edge cases.

• [ ] Create src/format-diff/test/ directory with integration tests
• [ ] Add tests for unified diff parsing
• [ ] Add tests for various output formats (colored, plain text)
• [ ] Add tests for empty diffs and malformed input handling
• [ ] Verify check_diff/tests/ covers cross-platform diff scenarios

Expand CI coverage with a dedicated 'Configuration Testing' workflow

The repo has Configurations.md documenting all config options, but there's no CI workflow specifically validating that every configuration option in src/ can be parsed correctly and doesn't cause regressions. Current workflows (linux.yml, mac.yml, windows.yml) appear to run general tests but not exhaustive config validation.

• [ ] Create .github/workflows/config-validation.yml
• [ ] Generate test rustfmt.toml files with all possible configuration combinations
• [ ] Add test cases for config parsing edge cases (invalid values, deprecated options)
• [ ] Test that config_proc_macro generated code matches documented Configurations.md
• [ ] Run on each PR to catch config-related regressions early

• Add comprehensive integration tests for all four binary entry points (rustfmt, cargo-fmt, format-diff, git-rustfmt) in tests/ mirroring what exists in check_diff/tests/; currently format-diff and git-rustfmt lack dedicated test coverage
• Extend Configurations.md with real-world examples for each configuration option showing before/after formatting; currently the documentation is sparse for understanding practical impact of settings like fn_single_line or match_block_trailing_comma
• Create architecture diagram and walkthrough document (separate from Design.md) explaining the visitor pattern flow through src/ for newcomers—the AST traversal strategy is implicit and undocumented visually

The rustfmt codebase demonstrates generally good security practices as a formatter tool. It avoids common injection vulnerabilities typical of web applications, contains no exposed secrets in the visible configuration, and uses well-maintained dependencies. The primary concerns are: (1) a known issue with the bytecount dependency's generic-simd feature that was disabled due to CI breakage, (2) reliance on Rust nightly features which may introduce instability, and (3) use of loose dependency version constraints that could allow unexpected updates. The project follows standard Rust best practices with Apache-2.0/MIT dual licensing and maintains CI/CD pipelines across multiple platforms. No critical security vulnerabilities were identified in the provided file structure and configuration.

• Low · Dependency on External Crate with Potential Maintenance Risk — Cargo.toml - bytecount dependency and generic-simd feature flag. The project depends on 'bytecount' version 0.6.9 with a known issue. The Cargo.toml contains a FIXME comment indicating that the 'generic-simd' feature of bytecount is broken and interfering with CI due to an unreleased fix in bytecount. Fix: Monitor bytecount releases for the fix, update to the patched version when available, and re-enable the generic-simd feature. Consider reaching out to bytecount maintainers if the issue is unresolved.
• Low · Use of Nightly Rust Features — Cargo.toml - package.metadata.rust-analyzer and codebase using rustc_private. The package metadata indicates use of '#[feature(rustc_private)]' which requires nightly Rust. This limits stability and may introduce breaking changes with Rust nightly updates. Fix: Document the nightly requirement clearly. Monitor rustc_private API changes and plan for stabilization or alternative approaches when possible. Consider feature-gating or isolating nightly code.
• Low · Permissive Dependency Version Specifications — Cargo.toml - multiple dependencies with loose version specifications. Several dependencies use loose version constraints (e.g., 'annotate-snippets = { version = "0.11" }', 'clap = { version = "4.4.2", ... }') which may allow minor/patch versions with potential undiscovered vulnerabilities. Fix: Consider using more restrictive version specifications (e.g., '=0.11.0' for critical dependencies) or regularly audit dependency updates. Use 'cargo audit' to identify known vulnerabilities.
• Low · Temporary File Handling in Tests — Cargo.toml - dev-dependencies section, tempfile = "3.23.0". The dev-dependency 'tempfile' is used for test purposes. Ensure temporary files are properly cleaned up and not world-readable if processing sensitive code. Fix: Review test code using tempfile to ensure proper permissions are set and cleanup occurs. Verify that temporary files don't retain sensitive formatting data.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.