feat(output): promote externalization percentage to headline

[boorad]

Summary

Promote the externalization percentage to the top of every scan report, so adopters can see — and share back — the one number that captures progress on moving authorization out of source code.

• Text: leads with Externalization: N% (X externalized / Y enforcement points) for every non-empty scan, including the 0% and 100% cases (the latter previously fell through findings.is_empty() and printed nothing — now fixed).
• JSON: new top-level headline object alongside the existing summary, with self-consistent fields: externalized + embedded_findings = total_enforcement_points. summary.enforcement_points and summary.externalized_pct keep their existing names for back-compat.

Changes

• src/output/text.rs — headline leads the report, emitted unconditionally when total > 0; 100%-externalized case now reports instead of silently bailing.
• src/output/json.rs — added Headline { externalized_pct, externalized, embedded_findings, total_enforcement_points } as a top-level field; doc comments spell out which fields overlap with summary and which are headline-only.
• src/output/mod.rs — extracted externalized_pct(externalized, embedded) -> usize helper so both formatters share one rounding rule.
• 13 new unit tests across the helper, text formatter (no-signal, 0%, 100% regression, mixed), and JSON shape (incl. back-compat fields).

Test plan

• cargo fmt --check
• cargo clippy --all-targets -- -D warnings
• cargo test (368 passed)
• Manual: cargo run -- scan <repo> shows the headline first
• Manual: cargo run -- scan <repo> --format json | jq .headline returns the four fields

Summary by CodeRabbit

• New Features
  • JSON reports now include a headline object displaying externalization percentage and enforcement metrics.
  • Text output displays an externalization headline with percentage breakdown and enforcement point distribution.
  • Improved handling for reports with zero findings or full externalization scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: aed5918d-7588-4ef8-ad10-2762e47e2cf1

📥 Commits

Reviewing files that changed from the base of the PR and between 53d45ab and 379b375.

📒 Files selected for processing (3)

• src/output/json.rs
• src/output/mod.rs
• src/output/text.rs

---

📝 Walkthrough

Walkthrough

The changes add a unified "Externalization" metrics headline to security scan reports. A shared percentage computation helper is extracted to src/output/mod.rs, then used to populate a new JSON Headline struct in ScanReport and consistently displayed in text output, with backward compatibility maintained for existing JSON summary fields.

Changes

Externalization Metrics Headline

Layer / File(s)	Summary
Core Computation src/output/mod.rs	New externalized_pct(externalized, embedded) -> usize helper computes a 0–100 rounded percentage, with explicit zero-total handling. Includes comprehensive unit tests for rounding and edge cases.
JSON Output Structure src/output/json.rs	ScanReport adds a new top-level Headline struct with externalized_pct, externalized, embedded_findings, and total_enforcement_points fields. print refactors to use the shared externalized_pct helper and populates the headline from enforcement points and findings count. Back-compat summary fields remain populated.
Text Output Display src/output/text.rs	print now unconditionally emits an "Externalization: X% (Y externalized / Z enforcement points)" headline using the shared helper, except when no patterns are found. Early return logic is restructured to handle the case where findings are empty but enforcement points exist (full externalization).
Tests & Validation src/output/json.rs, src/output/text.rs	New and updated test modules validate headline values for zero-signal, edge-case rounding, 0% and 100% scenarios, back-compat summary fields, and mixed percentage formatting.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A headline emerges from the metrics deep,
Externalization percentages we reap.
Shared logic computed with rounding so true,
JSON and text now both tell the clue—
Authorization patterns, externalized through!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and precisely describes the main change: promoting the externalization percentage metric to a headline position in scan reports.
Docstring Coverage	✅ Passed	Docstring coverage is 95.24% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[amazon-q-developer]

The implementation correctly promotes the externalization percentage to the report headline across both text and JSON formats. The refactoring properly extracts the percentage calculation into a shared helper function, ensuring consistent rounding behavior. The bug fix for the 100% externalization case (which previously printed nothing) is now properly handled. All edge cases are covered by comprehensive unit tests including 0%, 100%, and mixed percentage scenarios. The code is ready to merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.