feat(bridge): split phantom into phantom-declared vs phantom-transitive

[hyperpolymath]

Summary

The Track E sweep across 29 Cargo CVE issues revealed that the previous bridge classifier marked any crate without a direct use <crate> statement as reach=phantom, conflating two very different remediation paths:

• True phantom (PhantomDeclared) — crate IS in a Cargo.toml [dependencies] / [workspace.dependencies] block but never imported. Fix: cargo machete --fix strips the dep and the whole subtree drops from Cargo.lock. file-soup#50 is the canonical case.
• Misclassified (PhantomTransitive) — crate is NOT in any Cargo.toml; pulled in transitively by a parent. Local strip is impossible; the fix requires bumping the parent past the affected version. Of 28 non-pilot Track E repos, ~26 fell here (Batch A 7/7 misclassified, Batch B almost certainly similar, Cohort E-2 4/5 misclassified per patch-bridge: classify Dioxus/GTK transitive advisories as Informational (Cohort E-2) #75).

What changed

• Enum split: ReachabilityStatus::Phantom → PhantomDeclared / PhantomTransitive. JSON wire values (serde rename_all = kebab-case) are now phantom-declared / phantom-transitive.
• Evidence shape: ReachabilityEvidence gains optional parent_dep (populated only when transitive AND identifiable via Cargo.lock).
• Reachability scan: new check_reachability_with_manifest(project_dir, crate, declared_deps, parent_map) returns the correct variant. Lookup is normalised (underscore↔hyphen, lowercase) so a CVE feed reporting serde_json matches a manifest line serde-json.
• Parent identification: lockfile::collect_cargo_parents parses Cargo.lock's dependencies = [...] arrays and BFS-walks from each direct dep, attributing every reachable transitive (first BFS to reach wins). Best-effort — returns empty map on missing/unparseable lockfile, and classify falls back to "an upstream parent dependency" phrasing.
• Classifier: classify::classify no longer takes is_direct — the evidence's status variant already carries that info. Three-way output (Mitigable / Unmitigable / Informational) is unchanged. The rationale and fix-action diverge:
  • PhantomDeclared: "Strip from Cargo.toml — run cargo machete --fix (or remove the dependency line manually) for <crate>."
  • PhantomTransitive: "Pulled in transitively by <parent> — fix requires bumping the parent dependency past the affected version of <crate>. No local strip is possible."
• Schema bump: BridgeReport::schema_version 0.1.0 → 0.2.0 to flag the reach-field semantics change.
• No new deps: reuses the existing in-house TOML / Cargo.lock string parsers (consistent with collect_direct_cargo_dependencies).

Test coverage

13 new tests across the three bridge modules:

bridge::reachability (6 new):

• phantom_declared_when_crate_in_cargo_toml_but_no_use
• phantom_transitive_when_crate_not_in_cargo_toml (parent identified)
• reachable_when_declared_and_used
• phantom_transitive_with_unknown_parent_is_still_classified
• phantom_classification_normalises_underscore_to_hyphen
• phantom_declared_resolves_workspace_member_dep (workspace-member declared dep)

bridge::lockfile (3 new):

• parent_map_identifies_direct_to_transitive_path
• parent_map_returns_empty_when_no_lockfile
• parent_map_normalises_underscore_to_hyphen

bridge::classify (4 new, rewritten old ones):

• test_phantom_declared_recommends_machete_strip
• test_phantom_transitive_recommends_parent_bump
• test_phantom_transitive_unknown_parent_falls_back_gracefully
• test_phantom_variants_both_classify_informational

All 38 bridge-module tests pass; full suite (327 lib + integration) green; cargo check clean on default features (bridge is feature-gated behind http).

Files touched

File	+/-
src/bridge/mod.rs	+35 / -14
src/bridge/reachability.rs	+213 / -18
src/bridge/classify.rs	+109 / -52
src/bridge/lockfile.rs	+244 / -7

Related work

• panic-attack#74 — vendored-pin allowlist (Cohort E-3). With this PR, the classifier no longer falsely recommends stripping vendored-TLS / build-script-only crates, because those would only be in scope when they're PhantomDeclared (i.e., genuinely in Cargo.toml). The allowlist still needs to ride on top to handle e.g. openssl-sys = { features = ["vendored"] }.
• panic-attack#75 — Dioxus/GTK informational (Cohort E-2). With parent-dep identification, the genuine presswerk case will now be labelled with parent_dep: "dioxus" (or wry, whichever the BFS reaches first).
• file-soup#50 — canonical PhantomDeclared case.

Closes #32 (Track C/E sweep parent).

Test plan

• cargo check --features http clean
• cargo check (default features) clean
• cargo test --features http --lib bridge:: — 38 passed
• cargo test --features http — full suite green (327 + integration)
• Re-run Track E sweep against ~5 sample repos and confirm previously-phantom findings now split correctly into declared/transitive cohorts (post-merge validation)

[github-actions]

🔍 Hypatia Security Scan

Findings: 74 issues detected

Severity	Count
🔴 Critical	7
🟠 High	16
🟡 Medium	51

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Issue in boj-build.yml",
    "type": "unknown",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in cargo-audit.yml",
    "type": "unknown",
    "file": "cargo-audit.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "unknown",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "unknown",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "unknown",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in coverage.yml",
    "type": "unknown",
    "file": "coverage.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dependency-review.yml",
    "type": "unknown",
    "file": "dependency-review.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "unknown",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "unknown",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in dogfood-gate.yml",
    "type": "unknown",
    "file": "dogfood-gate.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence