feat(metrics): explain SQL change risk contributions

[tinovyatkin]

Summary

• carry analyzer contribution evidence through MetricsReport into JSON and Markdown output
• add deterministic, profile-gated collection for source-resolved metric contributions
• make sql.change_risk_score the first fully explained metric, with stable reason codes, weighted amounts, and byte/line spans
• add cargo xtask metric-contributions <path> plus documentation and regression coverage

Why

The contribution schema already existed, but analyzers emitted empty vectors and the report conversion discarded the field. SQL change risk is an appropriate first vertical slice because its weighted formula is additive and its statement/object facts already retain source positions.

Closes #173.

Behavior

• the default profile emits supported contribution evidence
• the CI and strict profiles omit evidence without changing metric values
• SQL factor weights and reason codes have one shared definition, preventing aggregate scores and evidence from drifting
• contributions are deterministically ordered by source span
• empty contribution arrays are omitted from serialized reports

For the destructive SQL fixture, sql.change_risk_score is 53 and the 12 emitted contributions sum to exactly 53.

Verification

• cargo build
• cargo check
• cargo fmt --all --check
• cargo clippy --all-targets --all-features --locked
• cargo nextest run --all-features
• cargo insta test --all-features --check --workspace --unreferenced reject --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest — 914 tests passed, no snapshot changes or unreferenced snapshots
• mint validate
• mint broken-links
• live cargo xtask metric-contributions crates/mehen-sql/tests/fixtures/migration_destructive.sql check

[github-actions]

Copy/Paste Detection

🟢 No duplications found in 10 changed Rust file(s) (threshold: 100 tokens).

[coderabbitai]

Warning

Review limit reached

@tinovyatkin, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 27 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 427b1279-8b37-49f3-bd16-12c357c0d23d

📥 Commits

Reviewing files that changed from the base of the PR and between 4ef2c61 and 01ff9a5.

📒 Files selected for processing (3)

• crates/mehen-core/src/analysis.rs
• crates/mehen-sql/src/facts.rs
• xtask/src/metric_contributions.rs

Walkthrough

Adds deterministic, optionally enabled metric contributions to core analysis and reports. SQL analysis now emits source-spanned change-risk evidence for supported statements and objects, preserving metric totals across profiles. JSON and Markdown outputs expose contributions when present. Tests cover ordering, spans, deduplication, serialization, rendering, and profile behavior. Documentation and an xtask metric-contributions command describe and expose the evidence.

Poem

I’m a rabbit with spans in my paws,
Sorting risk by sensible laws.
SQL leaves a trail,
Reports tell the tale,
And carrots applaud the new cause! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: explaining SQL change risk contributions.
Description check	✅ Passed	The description is directly related to the changeset and matches the implementation scope.
Linked Issues check	✅ Passed	The PR satisfies #173 by making sql.change_risk_score the first metric to emit MetricContribution evidence.
Out of Scope Changes check	✅ Passed	The additional docs, tests, and xtask work all support the contribution-evidence feature and appear in scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

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.}

[gemini-code-assist]

Code Review

This pull request introduces source-resolved contribution evidence for metrics, starting with SQL change risk scores. It adds a deterministic ContributionCollector, updates JSON and Markdown reports to serialize and render contributions, and provides a developer xtask command to inspect them. The review comments identify valuable improvement opportunities, including removing redundant sorting fields, optimizing touch_count to avoid heap allocations, gating contribution loops when disabled, and canonicalizing paths in the xtask command to prevent execution errors.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[github-actions]

Binary Size Report

Measured artifact: release Linux mehen binary built from this workflow.

	Size
main	30MiB
This PR	30MiB
Delta	+30KiB (+0.10%)

Size history

xychart-beta
  title "Binary size (bytes)"
  x-axis ["build(deps): bump gix from 0.8", "build(deps): bump log from 0.4", "build(deps): bump the ruff gro", "build(deps): bump the mago gro", "build: sync workspace crate ve", "build(deps): bump the oxc grou", "build(deps): bump tree-sitter ", "build(deps): bump camino from ", "feat: add Java analyzer and up", "build(deps): bump sqruff-lib-d", "build(deps): bump the mago gro", "build(deps): bump ra_ap_syntax", "build(deps): bump the oxc grou", "build(deps): bump mago-syntax-", "chore(main): release 1.3.0 (#1", "docs: surface SQL + ANTLR acro", "refactor(markdown): replace tr", "docs: post-classical metrics r", "This PR"]
  y-axis "Bytes"
  bar [29154336, 29184128, 29154616, 29184664, 29184664, 29194704, 29194696, 29194704, 30767472, 30833880, 30833888, 30834016, 30811952, 30811944, 30811984, 31135680, 31113224, 31113224, 31143608]

Loading

[github-actions]

📊 Source Code Metrics (this PR vs main)

File	Cyclomatic	Cognitive	Functions	LLOC	MI
crates/mehen-sql/src/facts.rs	452 (main: 408) 🔴	434 (main: 402) 🔴	78 (main: 72) 🔴	647 (main: 602) 🔴	0 ⚪
crates/mehen-report/src/markdown.rs	71 (main: 65) 🔴	34 (main: 26) 🔴	32 (main: 30) 🔴	258 (main: 235) 🔴	0 ⚪
crates/mehen-core/src/analysis.rs	40 (main: 31) 🔴	6 (main: 5) 🔴	22 (main: 17) 🔴	43 (main: 24) 🔴	14.89 (main: 20.88) 🔴
crates/mehen-sql/src/lib.rs	38 (main: 37) 🔴	11 (main: 10) 🔴	16 ⚪	79 (main: 76) 🔴	10.34 (main: 10.90) 🔴
crates/mehen-sql/src/composite.rs	19 ⚪	8 ⚪	13 ⚪	78 ⚪	14.48 (main: 14.63) 🔴
crates/mehen-report/src/json.rs	15 (main: 14) 🔴	10 ⚪	7 (main: 6) 🔴	36 (main: 26) 🔴	26.49 (main: 29.51) 🔴
xtask/src/main.rs	54 (main: 52) 🔴	42 (main: 40) 🔴	5 ⚪	63 (main: 60) 🔴	14.09 (main: 14.61) 🔴
xtask/src/metric_contributions.rs	22 🆕	9 🆕	5 🆕	27 🆕	30.93 🆕
crates/mehen-core/src/report.rs	6 (main: 5) 🔴	0 ⚪	3 (main: 2) 🔴	6 (main: 2) 🔴	24.25 (main: 27.21) 🔴
crates/mehen-core/src/lib.rs	10 ⚪	1 ⚪	2 ⚪	3 ⚪	30.67 (main: 30.78) 🔴

Generated by mehen v1.3.0 — the code quality watcher.

📝 Documentation Metrics (this PR vs main)

File	DMI	Words	FKGL	Link Debt	Filler Risk
docs/commands/metrics.mdx	87 (main: 88) ⚪	297 (main: 195) ⚪	9.4 (main: 8.8) 🔴	0.45 ⚪	0.29 (main: 0.30) ⚪
docs/concepts/output-formats.mdx	91 (main: 90) ⚪	145 (main: 107) ⚪	7.5 (main: 6.7) 🔴	0.45 ⚪	0.23 (main: 0.32) 🟢

Full metric breakdown (structural · wording · lexical · readability)

Structural / review

File	RCI	MCC	MRPC	Evidence	Grounding
docs/commands/metrics.mdx	23 (main: 21) ⚪	16 (main: 15) ⚪	1 ⚪	0.15 (main: 0.12) 🔴	0.12 (main: 0.04) 🔴
docs/concepts/output-formats.mdx	17 (main: 15) ⚪	9 (main: 8) ⚪	1 ⚪	0.19 (main: 0.15) 🔴	0.21 (main: 0.15) 🔴

English wording quality

File	WQS	Passive %	Hedges /100w	Long sent.	Nominalizations
docs/commands/metrics.mdx	1.00 (main: 0.99) ⚪	5% (main: 7%) 🟢	0.4 (main: 0.0) ⚪	1 ⚪	5% (main: 3%) ⚪
docs/concepts/output-formats.mdx	1.00 ⚪	4% (main: 0%) 🔴	0.0 ⚪	0 ⚪	5% (main: 5%) ⚪

English lexical & readability ensemble

File	MATTR₅₀	Hapax	Fog	SMOG	ARI	Coleman-Liau
docs/commands/metrics.mdx	0.87 (main: 0.88) ⚪	0.76 (main: 0.83) 🟢	10.1 (main: 8.1) 🔴	—	9.5 (main: 8.5) 🔴	13.5 (main: 12.8) 🔴
docs/concepts/output-formats.mdx	0.82 (main: 0.78) 🔴	0.78 (main: 0.76) ⚪	6.4 (main: 4.9) 🔴	—	6.4 (main: 5.7) 🔴	10.3 (main: 9.3) 🔴

Legend: 🟢 improvement · 🔴 regression · ⚠️ attention · 🆕 new file · ⚪ no material change

Generated by mehen — the code quality watcher.