Evidence
Evidence
Section titled “Evidence”Evidence is the concrete “where and why” attached to metric results. Metrics can emit findings that include file, line, snippet, and recommendation; each finding contains a list of evidence items so you can fix issues directly in the code.
Findings vs Policy Violations
Section titled “Findings vs Policy Violations”| Findings (evidence) | Policy violations | |
|---|---|---|
| Source | Metric plugins (optional) | Policy evaluation |
| Content | Title, description, evidence (file/line/snippet), recommendation | Metric key, expected vs actual, operator |
| Purpose | Explain where and how to fix | Pass/fail gate on numeric thresholds |
A policy violation says “scc.max_cycle_size was 3, expected 0.” A finding with evidence says “cycle involves src/a.ts, src/b.ts, src/c.ts” with file/line/snippet so you can open the exact locations.
Finding Structure
Section titled “Finding Structure”A finding (attached to a MetricResult) typically has:
- finding_type — e.g.
CyclicDependency,LayeringViolation,HighBlastRadius. - severity — For UI/prioritization.
- title / description — Short summary and longer explanation.
- evidence — List of evidence items (see below).
- recommendation — What to do (e.g. “Break the cycle by moving shared code to a util.”).
- effort / impact — For prioritization.
Evidence Structure
Section titled “Evidence Structure”Each evidence item points to a concrete location:
- file — Path to the file (optional).
- line — Line number (optional).
- snippet — Code or context snippet (optional).
- metadata — Extra key-value context (e.g. symbol, weight).
Not all metrics produce findings; many only produce numeric values. Metrics that do emit findings (e.g. cross-metric insights, refactoring recommendations, LLM integration, layer violations) use evidence so reports and UIs can link to the right place in the repo.
Where Evidence Appears
Section titled “Where Evidence Appears”- JSON report —
MetricResult.findings[].evidence[]. - HTML report — Findings rendered with clickable file/line links.
- SARIF — Mapped to SARIF locations and results for IDE/CI integration.
Learn More
Section titled “Learn More”- Metrics — How metric results and findings relate
- Violations — Policy failures (no evidence, just expected/actual)
- Cross-Metric Insights — Example metric that produces findings with evidence