feat(cli): add structured JSON output for agent consumers

[Jamie-BitFlight]

Supersedes #324 with a clean implementation based on current main.

Purpose

Add a stable machine-readable CLI contract for agents without changing normal human-facing output.

Included

• --json for check/tokens, rules/rule, docs commands, and version
• typed frozen response models and compact single-line JSON
• explicit omission metadata
• recording paths in structured responses
• passed validators recoverable with --show-progress
• reversible POSIX non-UTF-8 path identity
• directory arguments to docs JSON commands classified as usage errors rather than tracebacks
• focused JSON contract/parity tests

This branch was created from current main after #321, #322, #323, and #329 landed rather than rebasing the stale stacked history in #324.

Do not merge until full CI and review are green.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8e868fa4-1354-46d3-a6cf-26485eae0f47

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Benchmark Results

🔴 Regression detected — threshold: 30%

scan-clean

Metric	Base	Compare	Change
files_per_second	204.2 files/s	208.6 files/s	✅ +2.1%
scan_max_ms	5269.9 ms	4852.4 ms	✅ -7.9%
scan_mean_ms	4902.6 ms	4799.7 ms	✅ -2.1%
scan_min_ms	4703.4 ms	4760.6 ms	➡️ +1.2%

scan-violations

Metric	Base	Compare	Change
files_per_second	121.4 files/s	121.2 files/s	➡️ -0.2%
scan_max_ms	1720.3 ms	1676.3 ms	✅ -2.6%
scan_mean_ms	1655.1 ms	1658.9 ms	➡️ +0.2%
scan_min_ms	1608.2 ms	1637.7 ms	➡️ +1.8%

fix-violations

Metric	Base	Compare	Change
fix_files_per_second	309.3 files/s	296.9 files/s	➡️ -4.0%
fix_max_ms	660.7 ms	685.0 ms	➡️ +3.7%
fix_mean_ms	649.8 ms	677.0 ms	➡️ +4.2%
fix_min_ms	642.7 ms	669.3 ms	➡️ +4.1%

cpu

Metric	Base	Compare	Change
cpu_clean_mean_ms	0.5 ms	0.5 ms	➡️ +5.6%
cpu_fix_mean_ms	1.4 ms	1.4 ms	➡️ +0.5%
cpu_violations_mean_ms	0.5 ms	0.5 ms	➡️ +0.0%

import

Metric	Base	Compare	Change
import_package_max_ms	119.6 ms	245.7 ms	🔴 +105.4%
import_package_mean_ms	104.4 ms	143.8 ms	🔴 +37.7%
import_package_min_ms	86.6 ms	89.3 ms	➡️ +3.1%
import_rules_max_ms	162.9 ms	306.4 ms	🔴 +88.1%
import_rules_mean_ms	149.4 ms	198.9 ms	🔴 +33.1%
import_rules_min_ms	142.4 ms	144.3 ms	➡️ +1.3%

View benchmark history

_{Updated 2026-10-07 11:21 UTC}

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[github-actions]

📊 Test Coverage Report

Coverage: 88.25%

📥 Coverage XML available as artifact: coverage-xml