feat(reporters): file output, rdjson/sonar formats, SARIF safeguards + remediation

[dgenio]

Linked issues

Closes #233
Closes #237
Closes #244
Closes #227
Closes #238

Summary of changes

A single coherent change to the reporter / output layer (vibeguard/reporters/ + the CLI output dispatch), landing five related issues that share the same code area and implementation path.

• Add --output FILE (and multi-report output) to scan, gate, and publish-check #233 — file output & multi-report. --output PATH (-o, - = stdout) on scan/gate/publish-check, and a repeatable --report FORMAT=PATH that emits several formats from one scan (no shell redirection, no double scan). New vibeguard/reporters/registry.py centralizes format → string rendering (also useful for the embedding API). The generated GitHub Actions workflow now uses --output instead of > file.
• Add a reviewdog-compatible output format (rdjson) #237 — reviewdog rdjson. New --rdjson reporter (reporters/rdjson.py) emitting reviewdog's Diagnostic Format; severity map INFO/LOW→INFO, MEDIUM→WARNING, HIGH/CRITICAL→ERROR.
• Add a SonarQube generic-issue-import output format #244 — SonarQube. New --sonar reporter (reporters/sonar.py) emitting the Generic Issue Import JSON for sonar.externalIssuesReportPaths, with a documented severity/type mapping.
• Add SARIF output safeguards for code-scanning ingestion limits #227 — SARIF ingestion safeguards. render_sarif caps results at output.sarif_max_results (default 5,000 — GitHub's per-run limit), ordering by severity and appending a toolExecutionNotifications overflow notice. Output is byte-identical at/below the cap.
• Emit machine-actionable remediation metadata in SARIF and JSON output #238 — machine-actionable remediation. New optional Finding.remediation model (kind/target/line/content/description/confidence), populated on the sourcemaps + committed-.env findings, serialized in JSON and mapped to SARIF fixes for the replace-span/add-line kinds (GitHub renders these as one-click suggestions).

Type of change

• New feature (file output, two new formats, SARIF cap)
• New or updated detection rule (remediation metadata on sourcemaps/secrets)
• Documentation
• Tests
• CI / build / packaging (generated workflow)

How verified

• python -m pytest tests/ — 1072 passed (+~50 new)
• ruff check vibeguard/ tests/ benchmarks/ — All checks passed
• ruff format --check vibeguard/ tests/ benchmarks/ — 140 files already formatted
• python -m mypy vibeguard/ — Success: no issues found in 62 source files (with types-PyYAML installed; the bare-mypy yaml-stub note is the pre-existing environment artifact)
• make docs-check, make bench-precision-check, make check-versions — all clean (no rule-metadata or precision drift; remediation adds no findings)
• Manual (via the vibeguard entrypoint): --report sarif=… --report rdjson=… writes both from one scan; --sonar --output - streams to stdout; --output without a format flag, an unwritable path, mixing --report with a format flag, and a bad/unknown --report spec all exit 2; generated workflow renders and is valid YAML with --output.

Docs impact

• README / docs updated — README output examples; docs/output-schemas.md §4–§8 (remediation, SARIF cap, rdjson, sonar, file output); docs/github-actions.md (file output + large-repo guidance)
• docs/rules.md not regenerated — rule metadata is unchanged (remediation is per-finding data, not registry metadata); make docs-check confirms no drift.

Scope / risk

• New CLI surface (--output, --report, --rdjson, --sonar, output.sarif_max_results) — added to the stability contract; mutual-exclusion and error paths are tested.
• Additive JSON change: every finding now serializes "remediation": null by default. Consumers that ignore unknown/null fields are unaffected; the JSON golden was regenerated for this. SARIF and Markdown goldens are byte-identical. (Per the requester: no backward-compat constraint.)
• New formats only emit when mechanically safe — remediation is attached to high-confidence cohorts (source-map / committed-env), and only replace-span/add-line become SARIF fixes. A wrong auto-fix is worse than none.
• New runtime dependencies: none. Apply-side fix logic is intentionally out of scope (belongs to the vibeguard fix work).

Checklist

• Tests pass locally (pytest)
• Lint and format clean (make lint and make format-check)
• Type check clean (make typecheck) — clean with types-PyYAML; only the known pre-existing yaml-stub note otherwise
• No secrets committed
• Linked issues above
• PR title follows conventional commits

🤖 Generated with Claude Code

https://claude.ai/code/session_01X8ZPCcEw5r2augVrtDqdyJ

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR expands VibeGuard’s reporter/output layer to support writing reports to files (including multi-report output from a single scan), adds two new machine formats (reviewdog rdjson and SonarQube Generic Issue Import), and enhances SARIF output with ingestion safeguards and optional machine-actionable remediation metadata.

Changes:

• Add --output and repeatable --report FORMAT=PATH to scan/gate/publish-check, with a centralized reporter registry for “format → rendered string”.
• Introduce new reporters: rdjson (reviewdog) and sonar (SonarQube), plus goldens and targeted tests.
• Add SARIF result-capping + overflow notification and a new Finding.remediation model mapped to SARIF fixes for precise edit kinds.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vibeguard/rules/sourcemaps.py	Adds structured remediation metadata to sourcemap-related findings.
vibeguard/rules/secrets.py	Adds structured remediation metadata to committed-env findings.
vibeguard/reporters/sonar.py	New SonarQube Generic Issue Import JSON renderer.
vibeguard/reporters/sarif.py	Adds SARIF max-results cap + overflow notice and SARIF fixes mapping.
vibeguard/reporters/registry.py	Centralizes format-name → rendered-string dispatch for CLI and multi-report.
vibeguard/reporters/rdjson.py	New reviewdog rdjson renderer.
vibeguard/models.py	Introduces RemediationKind/Remediation and adds Finding.remediation.
vibeguard/config.py	Adds output.sarif_max_results configuration.
vibeguard/cli.py	Implements --output/--report plumbing and unified output dispatch.
vibeguard/ci_setup.py	Updates generated workflow to use --output instead of shell redirection.
tests/test_sonar.py	Adds Sonar reporter/CLI tests.
tests/test_sarif.py	Adds SARIF cap tests and SARIF fixes tests.
tests/test_reporters_golden.py	Adds golden coverage for rdjson and sonar outputs.
tests/test_remediation.py	Adds remediation model + rule integration tests.
tests/test_rdjson.py	Adds rdjson reporter/CLI tests.
tests/test_cli_e2e.py	Adds e2e coverage for --output and --report.
tests/fixtures/golden/scan_result.sonar.json	Adds sonar golden fixture.
tests/fixtures/golden/scan_result.rdjson	Adds rdjson golden fixture.
tests/fixtures/golden/scan_result.json	Updates JSON golden for remediation: null.
README.md	Documents new output flags and formats.
docs/output-schemas.md	Documents remediation metadata, SARIF cap, rdjson/sonar formats, and file output.
docs/github-actions.md	Updates Actions docs for --output and SARIF cap guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.