feat: Heavily improve machine readable evidence and expose more evidence (#6)

Author: math280h

README.md

@@ -33,6 +33,7 @@
 - `allow`: `true` or `false`
 - `risk`: `low | medium | high | critical`
 - `reasons`: human-readable findings
+- `evidence`: structured findings (`kind`, stable `id`, `severity`, `message`, `facts`)
 - `metadata`: package context (latest, publish date, downloads, advisories)
 
 Policy can be extended with `custom_rules` in config (see `docs/configuration-spec.md`).
@@ -53,7 +54,6 @@ Prioritized planned work:
 ### Now
 
 - [ ] Shared registry HTTP utilities (retry/backoff/rate-limit handling/user-agent/error mapping)
-- [ ] Structured reasons in responses (`check_id`, `rule_id`, machine-readable evidence)
 - [ ] Transitive dependency path visibility in lockfile audits
 - [ ] Deterministic policy snapshots in audit logs (config fingerprint + enabled checks)
 - [ ] Dependency confusion defenses for internal/private package names
@@ -173,6 +173,20 @@ Windows example (no console window):
   "reasons": [
     "lodash@3.10.1 is 1 major version behind latest (4.17.21)"
   ],
+  "evidence": [
+    {
+      "kind": "check",
+      "id": "staleness.behind_latest",
+      "severity": "low",
+      "message": "lodash@3.10.1 is 1 major version behind latest (4.17.21)",
+      "facts": {
+        "package_name": "lodash",
+        "resolved_version": "3.10.1",
+        "latest_version": "4.17.21",
+        "major_gap": 1
+      }
+    }
+  ],
   "metadata": {
     "latest": "4.17.21",
     "requested": "3.10.1",
@@ -182,6 +196,42 @@ Windows example (no console window):
 }
 ```
 
+`evidence.id` is stable and machine-oriented:
+- built-in checks: `<check_id>.<reason_code>` (example: `staleness.behind_latest`)
+- custom rules: `custom_rule.<rule_id>` (example: `custom_rule.low-downloads`)
+- policy/runtime items keep explicit IDs (example: `denylist.package`, `risk.medium_pair_escalation`)
+
+Example multi-signal evidence excerpt (all entries include `facts`):
+
+```json
+{
+  "evidence": [
+    {
+      "id": "version_age.too_new",
+      "kind": "check",
+      "severity": "high",
+      "facts": {
+        "package_name": "lodash",
+        "resolved_version": "1.0.2",
+        "age_days": 1,
+        "min_age_days": 7
+      }
+    },
+    {
+      "id": "advisory.known_advisory",
+      "kind": "check",
+      "severity": "high",
+      "facts": {
+        "advisory_ids": ["OSV-2025-0001"],
+        "advisory_aliases": ["CVE-2025-9999"],
+        "requested_version": "1.0.2",
+        "recommended_fixed_version": "4.17.21"
+      }
+    }
+  ]
+}
+```
+
 ## Development
 
 ```bash

crates/checks/advisory/src/lib.rs

@@ -85,10 +85,28 @@ async fn run(
         format!("{package_name}@{requested_version} is affected by {identifiers}")
     };
 
-    Some(CheckFinding {
-        severity: Severity::High,
-        reason,
-    })
+    let advisory_ids = advisories
+        .iter()
+        .map(|advisory| advisory.id.clone())
+        .collect::<Vec<_>>();
+    let mut finding = CheckFinding::new(Severity::High, reason, "known_advisory")
+        .with_fact("package_name", package_name)
+        .with_fact("requested_version", requested_version)
+        .with_fact("latest_version", latest_version)
+        .with_fact("advisory_ids", advisory_ids)
+        .with_fact(
+            "advisory_aliases",
+            advisories
+                .iter()
+                .flat_map(|advisory| advisory.aliases.iter().cloned())
+                .collect::<Vec<_>>(),
+        );
+
+    if let Some(fixed) = best_fixed_version(&fixed_versions) {
+        finding = finding.with_fact("recommended_fixed_version", fixed);
+    }
+
+    Some(finding)
 }
 
 fn advisory_identifiers(advisory: &PackageAdvisory) -> Vec<String> {

crates/checks/existence/src/lib.rs

@@ -57,17 +57,22 @@ impl Check for ExistenceCheck {
 }
 
 fn missing_package(package_name: &str) -> CheckFinding {
-    CheckFinding {
-        severity: Severity::Critical,
-        reason: format!("{package_name} does not exist (possible hallucination / slopsquatting)"),
-    }
+    CheckFinding::new(
+        Severity::Critical,
+        format!("{package_name} does not exist (possible hallucination / slopsquatting)"),
+        "missing_package",
+    )
+    .with_fact("package_name", package_name)
 }
 
 fn missing_version(package_name: &str, version: &str) -> CheckFinding {
-    CheckFinding {
-        severity: Severity::Critical,
-        reason: format!("{package_name}@{version} does not exist (possible hallucinated version)"),
-    }
+    CheckFinding::new(
+        Severity::Critical,
+        format!("{package_name}@{version} does not exist (possible hallucinated version)"),
+        "missing_version",
+    )
+    .with_fact("package_name", package_name)
+    .with_fact("requested_version", version)
 }
 
 #[cfg(test)]

crates/checks/install-script/src/lib.rs

@@ -59,12 +59,18 @@ async fn run(package_name: &str, version: &PackageVersion) -> Option<CheckFindin
         .iter()
         .find(|script| is_suspicious(script));
 
-    suspicious.map(|script| CheckFinding {
-        severity: Severity::High,
-        reason: format!(
-            "{package_name}@{} has a suspicious install hook: {script}",
-            version.version
-        ),
+    suspicious.map(|script| {
+        CheckFinding::new(
+            Severity::High,
+            format!(
+                "{package_name}@{} has a suspicious install hook: {script}",
+                version.version
+            ),
+            "suspicious_install_hook",
+        )
+        .with_fact("package_name", package_name)
+        .with_fact("resolved_version", version.version.as_str())
+        .with_fact("script", script.as_str())
     })
 }
 

crates/checks/popularity/src/lib.rs

@@ -63,13 +63,22 @@ async fn run(
         return None;
     }
 
-    Some(CheckFinding {
-        severity: Severity::High,
-        reason: format!(
+    Some(
+        CheckFinding::new(
+            Severity::High,
+            format!(
             "{package_name}@{} has low adoption ({downloads} weekly downloads) and is only {age_days} day(s) old",
             version.version
         ),
-    })
+            "low_adoption_young_package",
+        )
+        .with_fact("package_name", package_name)
+        .with_fact("resolved_version", version.version.as_str())
+        .with_fact("weekly_downloads", downloads)
+        .with_fact("age_days", age_days)
+        .with_fact("min_weekly_downloads", min_weekly_downloads)
+        .with_fact("young_package_age_days", young_package_age_days),
+    )
 }
 
 #[cfg(test)]

crates/checks/staleness/src/lib.rs

@@ -47,27 +47,39 @@ async fn run(
     let ignored = is_ignored(package.name.as_str(), requested.version.as_str(), policy);
 
     if requested.deprecated {
-        findings.push(CheckFinding {
-            severity: Severity::High,
-            reason: format!(
-                "{}@{} is marked deprecated",
-                package.name, requested.version
-            ),
-        });
+        findings.push(
+            CheckFinding::new(
+                Severity::High,
+                format!(
+                    "{}@{} is marked deprecated",
+                    package.name, requested.version
+                ),
+                "deprecated_version",
+            )
+            .with_fact("package_name", package.name.as_str())
+            .with_fact("resolved_version", requested.version.as_str()),
+        );
     }
 
     if !ignored && let Some(published) = requested.published {
         let age_days = chrono::Utc::now()
             .signed_duration_since(published)
             .num_days();
         if age_days >= policy.warn_age_days {
-            findings.push(CheckFinding {
-                severity: Severity::Low,
-                reason: format!(
-                    "{}@{} is {} day(s) old (>= {} days)",
-                    package.name, requested.version, age_days, policy.warn_age_days
-                ),
-            });
+            findings.push(
+                CheckFinding::new(
+                    Severity::Low,
+                    format!(
+                        "{}@{} is {} day(s) old (>= {} days)",
+                        package.name, requested.version, age_days, policy.warn_age_days
+                    ),
+                    "old_release_age",
+                )
+                .with_fact("package_name", package.name.as_str())
+                .with_fact("resolved_version", requested.version.as_str())
+                .with_fact("age_days", age_days)
+                .with_fact("warn_age_days", policy.warn_age_days),
+            );
         }
     }
 
@@ -94,21 +106,44 @@ async fn run(
     };
 
     if major_gap >= policy.warn_major_versions_behind {
-        findings.push(CheckFinding {
-            severity: Severity::Medium,
-            reason: format!(
-                "{}@{} is {} major version(s) behind latest ({})",
-                package.name, requested.version, major_gap, package.latest
+        findings.push(
+            CheckFinding::new(
+                Severity::Medium,
+                format!(
+                    "{}@{} is {} major version(s) behind latest ({})",
+                    package.name, requested.version, major_gap, package.latest
+                ),
+                "major_versions_behind",
+            )
+            .with_fact("package_name", package.name.as_str())
+            .with_fact("resolved_version", requested.version.as_str())
+            .with_fact("latest_version", package.latest.as_str())
+            .with_fact("major_gap", major_gap)
+            .with_fact(
+                "warn_major_versions_behind",
+                policy.warn_major_versions_behind,
             ),
-        });
+        );
     } else if major_gap >= 1 || minor_gap >= policy.warn_minor_versions_behind {
-        findings.push(CheckFinding {
-            severity: Severity::Low,
-            reason: format!(
-                "{}@{} is behind latest ({})",
-                package.name, requested.version, package.latest
+        findings.push(
+            CheckFinding::new(
+                Severity::Low,
+                format!(
+                    "{}@{} is behind latest ({})",
+                    package.name, requested.version, package.latest
+                ),
+                "behind_latest",
+            )
+            .with_fact("package_name", package.name.as_str())
+            .with_fact("resolved_version", requested.version.as_str())
+            .with_fact("latest_version", package.latest.as_str())
+            .with_fact("major_gap", major_gap)
+            .with_fact("minor_gap", minor_gap)
+            .with_fact(
+                "warn_minor_versions_behind",
+                policy.warn_minor_versions_behind,
             ),
-        });
+        );
     }
 
     findings

crates/checks/typosquat/src/lib.rs

@@ -87,12 +87,19 @@ async fn run(
         return Ok(None);
     };
 
-    Ok(Some(CheckFinding {
-        severity: Severity::High,
-        reason: format!(
+    Ok(Some(
+        CheckFinding::new(
+            Severity::High,
+            format!(
             "{package_name} is {distance} edit(s) away from popular package {candidate} and has low adoption ({weekly_downloads} weekly downloads)"
         ),
-    }))
+            "close_to_popular_name",
+        )
+        .with_fact("package_name", package_name)
+        .with_fact("closest_package", candidate)
+        .with_fact("edit_distance", distance)
+        .with_fact("weekly_downloads", weekly_downloads),
+    ))
 }
 
 fn bounded_levenshtein(lhs: &str, rhs: &str, max_distance: usize) -> Option<usize> {

crates/checks/version-age/src/lib.rs

@@ -52,13 +52,20 @@ async fn run(
         return None;
     }
 
-    Some(CheckFinding {
-        severity: Severity::High,
-        reason: format!(
-            "{package_name}@{} was published {} day(s) ago (< {min_version_age_days} days)",
-            version.version, age_days
-        ),
-    })
+    Some(
+        CheckFinding::new(
+            Severity::High,
+            format!(
+                "{package_name}@{} was published {} day(s) ago (< {min_version_age_days} days)",
+                version.version, age_days
+            ),
+            "too_new",
+        )
+        .with_fact("package_name", package_name)
+        .with_fact("resolved_version", version.version.as_str())
+        .with_fact("age_days", age_days)
+        .with_fact("min_age_days", min_version_age_days),
+    )
 }
 
 #[cfg(test)]