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/rome/tools 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 all four use cases

• 14 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{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 rome/tools repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rome/tools.

What it runs against: a local clone of rome/tools — 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 rome/tools | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1006 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rome/tools. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rome/tools.git
#   cd tools
#
# 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 rome/tools and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/rome_cli/src/main.rs" \\
  && ok "crates/rome_cli/src/main.rs" \\
  || miss "missing critical file: crates/rome_cli/src/main.rs"
test -f "crates/rome_analyze/src/lib.rs" \\
  && ok "crates/rome_analyze/src/lib.rs" \\
  || miss "missing critical file: crates/rome_analyze/src/lib.rs"
test -f "crates/rome_cli/src/commands/mod.rs" \\
  && ok "crates/rome_cli/src/commands/mod.rs" \\
  || miss "missing critical file: crates/rome_cli/src/commands/mod.rs"
test -f "crates/rome_analyze/src/rule.rs" \\
  && ok "crates/rome_analyze/src/rule.rs" \\
  || miss "missing critical file: crates/rome_analyze/src/rule.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 1006 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~976d)"
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/rome/tools"
  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).

Rome is a unified developer toolchain for JavaScript, TypeScript, and web projects written entirely in Rust, providing integrated linting, formatting, bundling, and testing capabilities as a single binary. It eliminates the need to configure and coordinate multiple tools (ESLint, Prettier, Babel, Jest) by replacing them with a cohesive, performant alternative that shares a single AST and configuration model across all operations. Monorepo structured as a Rust workspace (Cargo.toml defines members in crates/*) with specialized crates: rome_analyze for linting rules, rome_js_factory and rome_css_factory for AST construction, rome_formatter for formatting logic, and rome_cli binding them into a CLI binary. npm/rome provides the JavaScript API wrapper. Shared infrastructure lives in helper crates like rome_diagnostics, rome_deserialize, and rome_console for error reporting.

JavaScript and TypeScript developers who want to replace their fragmented tool chains (ESLint + Prettier + Babel + Jest) with a single, faster, opinionated binary; teams building web applications who value unified linting/formatting rules and faster CI/CD pipelines; and developers frustrated with Node.js tool startup time and configuration overhead.

Actively developed and rapidly maturing: the codebase is substantial (7.2M lines of Rust, comprehensive test coverage via .github/workflows/) with organized CI/CD pipelines (bench_analyzer.yml, parser_conformance.yml, release workflows), but Rome itself is still stabilizing its public API—it was absorbed into the Biome project mid-development. Still production-ready for linting and formatting workflows, though the project is transitioning.

The project underwent a significant organizational shift (being rebranded/merged into Biome), creating uncertainty about long-term maintenance and roadmap clarity—check the main branch and GitHub issues for current status. The heavy reliance on a single Rust implementation means any major bugs affect all features simultaneously, and the ecosystem of third-party plugins is minimal compared to ESLint. Dependency risk is low (Rust cargo ecosystem is mature), but API stability may fluctuate during the toolchain's consolidation phase.

The repository shows active benchmark optimization workflows (bench_analyzer.yml, bench_cli.yml, bench_formatter.yml, bench_parser.yml), comprehensive parser conformance testing, and release pipelines for CLI, LSP, and JavaScript API packages. Recent work appears focused on performance tuning, parser robustness, and the transition toward the Biome unified project. Check .github/workflows/main.yml and pull_request.yml for CI signal on current activity.

git clone https://github.com/rome/tools.git
cd tools
cargo build --release
./target/release/rome --help

Or for npm integration: npm install rome and check npm/rome/README.md for JavaScript API usage. For development, install Rust 1.70+ (check .cargo/config.toml for toolchain details).

Daily commands:

# Development build
cargo build

# Run the CLI
cargo run --release -- --help

# Run linter on current directory
cargo run --release -- check .

# Run formatter
cargo run --release -- format .

# Run tests
cargo test --workspace

# Benchmark (requires benchmark deps)
cd benchmark && npm install && node run.js

• Cargo.toml — Workspace root configuration defining all member crates and shared dependencies; essential for understanding the monorepo structure and build system.
• crates/rome_cli/src/main.rs — CLI entry point that orchestrates all Rome commands and serves as the primary user-facing interface.
• crates/rome_analyze/src/lib.rs — Core analysis framework registry and rule execution engine; every linting rule and analysis feature depends on this.
• crates/rome_cli/src/commands/mod.rs — Command dispatcher routing user input to format, lint, check, and other subcommands.
• crates/rome_analyze/src/rule.rs — Rule trait definition and metadata structure; required reading for implementing new lint rules.
• crates/rome_cli/src/configuration.rs — Configuration file parsing and schema validation for rome.json settings across all tools.
• crates/rome_cli/src/execute/process_file.rs — File processing orchestration that routes files through formatting, linting, and checking pipelines.

Add a New Linting Rule

1. Define the rule struct and metadata in a new file under crates/rome_analyze/src/rules/ (crates/rome_analyze/src/rule.rs)
2. Implement the Rule trait with visit_* methods matching the AST nodes to inspect (crates/rome_analyze/src/visitor.rs)
3. Register the rule in crates/rome_analyze/src/registry.rs by adding it to the rule registry (crates/rome_analyze/src/registry.rs)
4. Add rule configuration options to crates/rome_cli/src/configuration.rs if needed (crates/rome_cli/src/configuration.rs)
5. Add tests in the rule module to validate rule behavior (crates/rome_analyze/src/rule.rs)

Add a New CLI Command

1. Create new command module in crates/rome_cli/src/commands/your_command.rs (crates/rome_cli/src/commands/mod.rs)
2. Add command handler function and CLI options struct (crates/rome_cli/src/cli_options.rs)
3. Register command in the command dispatcher (crates/rome_cli/src/commands/mod.rs)
4. Implement file processing logic by extending or reusing execute modules (crates/rome_cli/src/execute/mod.rs)
5. Add diagnostic output using the diagnostic framework (crates/rome_cli/src/diagnostics.rs)

Extend Configuration System

1. Add configuration struct/enum to crates/rome_cli/src/configuration.rs (crates/rome_cli/src/configuration.rs)
2. Update rome.json schema validation logic in the same configuration module (crates/rome_cli/src/configuration.rs)
3. Pass configuration through to rule context in crates/rome_analyze/src/context.rs (crates/rome_analyze/src/context.rs)
4. Update CLI option parsing to bind configuration flags (crates/rome_cli/src/cli_options.rs)

Add a New File Processing Pipeline

1. Create new pipeline module in crates/rome_cli/src/execute/process_file/ (crates/rome_cli/src/execute/process_file.rs)
2. Define pipeline logic extending or complementing format.rs, lint.rs, or check.rs (crates/rome_cli/src/execute/process_file/format.rs)
3. Hook pipeline into process_file.rs dispatcher (crates/rome_cli/src/execute/process_file.rs)
4. Add command handler in crates/rome_cli/src/commands/ to trigger the pipeline (crates/rome_cli/src/commands/mod.rs)

• Rust — High-performance compiled language for CPU-intensive parsing, linting, and formatting operations; enables single-binary distribution.
• Cargo workspace (monorepo) — Enables code sharing across multiple tools (CLI, analyzer, ARIA metadata) while maintaining clear module boundaries and independent testing.
• Visitor pattern for AST analysis — Decouples rule implementations from core traversal logic, allowing independent rule development and composition.
• Plugin-style rule registry — Centralizes rule discovery and metadata, making it easy to enable/disable rules per-project via configuration.

• Single-pass analysis with visitor pattern

  • Why: Performance: avoid multiple tree walks
  • Consequence: Rules cannot easily depend on results from other rules; some checks may require multiple passes

• Configuration via rome.json file

  • Why: User convenience: single project config file
  • Consequence: Changes require file edits and CLI restart; no dynamic reconfiguration at runtime

• Parallel file processing with limited parallelism control

  • Why: Speed on multi-core systems without overwhelming resource usage
  • Consequence: Benchmarks and scaling are machine-dependent; no fine-grained control per rule

• Built-in rules with no external plugin system

  • Why: Ensures quality, security, and unified behavior
  • Consequence: Users cannot author custom rules; must contribute upstream to Rome

• Does not support plugins or custom rule extensions
• Does not integrate with package managers for rule distribution
• Not a real-time file watcher service (daemon mode available but limited)
• Does not auto-fix all issues; some rules report diagnostics only

Rust version: Check .github/workflows for MSRV (minimum supported Rust version)—likely 1.70+. Snapshot tests: Formatter and parser tests use snapshot files (look for .snap files); modifying output requires regenerating snapshots with cargo test -- --nocapture. Workspace isolation: Internal crates use path dependencies (Cargo.toml lines like path = "./crates/rome_analyze"), so you must build from the workspace root, not individual crate roots. Parser conformance: The parser is tested against real-world JavaScript conformance suites (parser_conformance.yml)—parser changes may require updating fixtures. LSP vs CLI: The LSP server (release_lsp.yml) and CLI are separate binaries with overlapping logic—changes to parsing/formatting may need syncing in both paths. Docker/CI environment: Benchmarks use special Docker images (Dockerfile.benchmark, ci/rome-ci-x86-64-centos7); local benchmark results may differ from CI results.

• Abstract Syntax Tree (AST) Visitation — Rome's linting (rome_analyze) and formatting (rome_formatter) engines are built on a shared visitor pattern that traverses a single AST; understanding how to implement visitor methods is essential for adding rules or formatters.
• Cursor-based Token Navigation — Rome's parser uses a cursor (token stream position) to handle whitespace, trivia (comments), and error recovery; understanding cursor movement is key to debugging parser behavior and writing formatters that preserve comments.
• Diagnostic Codes and Rule Categories — Rome organizes linting diagnostics into categories (rome_diagnostics_categories) and uses stable error codes; understanding this taxonomy is crucial for navigating rule configuration and filtering output in CI pipelines.
• Snapshot Testing — Rome's formatter and parser tests rely heavily on snapshot assertions (.snap files); understanding how to update and review snapshots is essential for working on formatting or parser changes without breaking existing behavior.
• Workspace Monorepo (Cargo workspaces) — Rome is structured as a Cargo workspace with interdependent crates (rome_analyze, rome_formatter, rome_cli); understanding workspace dependency resolution and path dependencies is critical for building, testing, and publishing Rome.
• Trivia (Whitespace & Comment Preservation) — Rome's parser tracks 'trivia' (whitespace, comments, line breaks) separately from syntax tokens to enable lossless formatting; formatters must intelligently reconstruct trivia to preserve developer intent while enforcing style rules.
• Rule Metadata and Configuration — Rome rules declare metadata (name, severity, fix capabilities) used to generate configuration schemas and documentation; understanding the metadata system (rome_diagnostics_macros) enables proper rule registration and IDE integration.

• biomejs/biome — Biome is the continuation and unified rebrand of the Rome project after organizational merger; this is where active development moved, making it the spiritual successor.
• eslint/eslint — ESLint is the established linting standard Rome aims to replace; understanding ESLint's rule model and plugin system helps contextualize Rome's design choices.
• prettier/prettier — Prettier defined modern opinionated code formatting; Rome's formatter was designed as a Rust-based replacement with unified linting, comparing implementations illuminates Rome's architectural wins.
• swc-project/swc — SWC is a parallel Rust-based JavaScript toolchain (parser, transpiler, bundler); both projects demonstrate Rust's viability for JS tooling and share similar performance goals.
• denoland/deno — Deno includes built-in linting and formatting (inspired by Rome's unified approach); users evaluating Rome vs. Deno's toolchain benefits from understanding both ecosystems.

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 conformance test suite for CSS parser (rome_css_parser)

The repo has a parser_conformance.yml workflow for JavaScript but no equivalent for CSS. Given that rome_css_parser, rome_css_syntax, and rome_css_factory exist as full crates, there should be conformance tests comparing Rome's CSS parsing output against a reference implementation (like PostCSS or standard W3C test cases). This would ensure CSS parsing reliability before the CSS feature is marked stable.

• [ ] Create crates/rome_css_parser/tests/conformance/ directory structure similar to JS parser tests
• [ ] Add reference CSS test cases (e.g., from W3C CSS Syntax Module test suite)
• [ ] Implement comparison logic in a new xtask/css_conformance crate or extend existing conformance logic
• [ ] Add .github/workflows/parser_conformance_css.yml workflow (parallel to existing parser_conformance.yml)
• [ ] Document CSS conformance testing approach in crates/rome_css_parser/CONTRIBUTING.md

Implement missing diagnostic category documentation for rome_analyze rules

The crates/rome_analyze/src/categories.rs file likely defines diagnostic categories, but there's no corresponding documentation explaining each category's purpose, examples, and when rules fall into them. Contributors adding new rules frequently get confused about category selection. A structured RULES.md or CATEGORIES.md would codify this knowledge.

• [ ] Extract all diagnostic categories from crates/rome_analyze/src/categories.rs and crates/rome_js_analyze/src/rules/
• [ ] Create crates/rome_analyze/RULES_CATEGORIES.md documenting each category with examples of 2-3 existing rules in that category
• [ ] Add a validation check in xtask/lintdoc to ensure new rules reference valid categories from the documented list
• [ ] Update crates/rome_analyze/CONTRIBUTING.md with a link to RULES_CATEGORIES.md
• [ ] Add clippy lint or test to ensure undocumented categories fail CI

Add integration tests for rome_cli config file resolution (Cargo.toml, rome.json, tsconfig.json)

The .github/workflows/main.yml and pull_request.yml exist but don't show dedicated integration tests for the critical config resolution logic in rome_cli. New contributors frequently break config loading without catching it. Adding a test harness that verifies rome.json, tsconfig.json, and package.json precedence across nested directories would prevent regressions.

• [ ] Create crates/rome_cli/tests/config_resolution/ with fixture directories (nested rome.json, tsconfig.json, package.json files)
• [ ] Implement integration test in crates/rome_cli/tests/config_resolution.rs that validates config precedence rules
• [ ] Test edge cases: missing files, conflicting configs, environment variable overrides
• [ ] Add test to crates/rome_cli/tests/ that verifies --config-path CLI flag overrides directory traversal
• [ ] Document config resolution precedence in crates/rome_cli/README.md with a flowchart or table

• Add missing diagnostic categories for CSS rules: rome_diagnostics_categories defines rule groupings; CSS linting (rome_css_analyze) likely has uncategorized rules. Audit crates/rome_css_analyze for new rules without category entries and file a PR adding them to rome_diagnostics_categories/src/lib.rs.
• Expand formatter snapshot test coverage for edge cases: Formatter tests in crates/rome_formatter_test use snapshot assertions; pick an undersupported language construct (e.g., complex nested ternaries, JSX edge cases, CSS custom properties) and add test snapshots demonstrating current behavior and verifying fixes.
• Document the linting rule development workflow: crates/rome_analyze/CONTRIBUTING.md exists but likely needs concrete examples; add a step-by-step tutorial with a minimal rule implementation example (e.g., 'no-unused-imports') showing how to add diagnostics, tests, and snapshots—useful for future contributors.

This Rust-based developer tools repository (Rome) shows generally sound security practices with a monorepo structure and managed dependencies via Cargo. However, several medium-risk issues were identified: incomplete dependency information prevents full vulnerability assessment, development build configurations could be misused, and benchmark/CI scripts may have unaudited dependencies. The repository would benefit from a formal SECURITY.md policy, regular automated dependency scanning via 'cargo audit', and clearer separation of development vs. production build profiles. No hardcoded secrets or obvious injection vulnerabilities were detected in the visible file structure. Overall security posture is moderate-to-good but requires attention to dependency management and process hardening.

• Medium · Workspace Resolver Version Not Explicitly Pinned — Cargo.toml - workspace.dependencies section. The Cargo.toml uses resolver = '2' which is good, but workspace dependencies lack version constraints. Some internal crates use version = '0.0.0' or '0.0.1' which may indicate development versions. This could lead to unexpected behavior in dependency resolution. Fix: Ensure all workspace dependencies have explicit, stable version constraints. Avoid '0.0.x' versions in production; use semantic versioning (e.g., '0.1.0' or higher).
• Medium · Incomplete Dependency Information — Cargo.toml - workspace.dependencies section (incomplete). The provided Cargo.toml snippet is truncated at 'rome_js_factory' definition, making it impossible to verify all dependencies for known vulnerabilities. Critical security information is missing. Fix: Provide complete Cargo.toml file. Run 'cargo audit' regularly to identify vulnerable dependencies. Implement automated dependency scanning in CI/CD pipeline.
• Low · No Explicit Security Policy File — Repository root. While CONTRIBUTING.md and CODE_OF_CONDUCT.md exist, there is no dedicated SECURITY.md file visible for reporting security vulnerabilities. This may delay security incident response. Fix: Create a SECURITY.md file following the standard format (https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) with clear instructions for reporting vulnerabilities.
• Low · Development Build Configuration Exposed — Cargo.toml - profile.release-with-debug section. The Cargo.toml includes a 'release-with-debug' profile that inherits from 'release' but includes debug symbols. This could be accidentally used in production deployments, increasing binary size and exposing debug information. Fix: Clearly document when 'release-with-debug' should be used. Ensure CI/CD pipelines use the standard 'release' profile for production builds. Add warnings or guardrails in deployment scripts.
• Low · Benchmark Files in Repository — benchmark/ directory. Benchmark directory includes package.json with npm dependencies (package-lock.json exists). These may not be regularly audited and could introduce vulnerabilities if benchmark code is ever executed in production contexts. Fix: Keep benchmark dependencies separately maintained. Run 'npm audit' on benchmark/package.json as part of CI. Document that benchmark code is not production-ready and ensure it's excluded from production builds.
• Low · Docker Image Build Configuration — Dockerfile.benchmark. Dockerfile.benchmark exists but no base image specification details are visible. Benchmarking Dockerfiles could potentially use outdated or unvetted base images. Fix: Verify the Dockerfile uses minimal, regularly-updated base images (alpine:latest or specific digest hash). Scan the image with tools like Trivy or Anchore. Use multi-stage builds to minimize attack surface.

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.