Interop with cargo-impact: --files-from stdin and --impact-scope

[asmuelle]

Context

cargo-impact v0.3.0-alpha.1 ships a --context flag that emits a newline-delimited list of files touched by the blast radius of a code change:

$ cargo impact --context
src/engine.rs
src/ffi.rs
tests/integration.rs
docs/architecture.md

The intended bidirectional workflow (documented in cargo-impact's README §7):

# Forward: generate a context pack scoped to only impact-affected files
cargo impact --context | cargo context --files-from -

# Reverse: consume a full cargo-impact JSON report and produce a
# context pack for the low-confidence findings so the AI can re-verify
cargo impact --format=json > .impact.json
cargo context --impact-scope=.impact.json --budget=8000

Neither of the two cargo-context flags this needs (--files-from and --impact-scope) exists today.

Ask

1. --files-from <PATH|-> (smaller, high-leverage)

Add a flag that reads a newline-delimited list of file paths (from a file, or - for stdin) and builds the context pack using exactly those files instead of (or in addition to) the git-diff-derived set. Paths are repo-relative.

This makes cargo impact --context | cargo context --files-from - work immediately — users get a context pack scoped to the blast radius of their change, not a whole-repo dump.

2. --impact-scope <PATH> (larger, richer)

Consume a cargo-impact --format=json envelope. The JSON shape is documented in cargo-impact README §8. Useful fields:

• findings[].kind — which analyzer produced the finding
• findings[].confidence and findings[].tier — let cargo-context prioritize or filter
• findings[].primary_path (via impact_surface / the kind payload)

With this, cargo context could emit targeted packs per finding or per severity tier, keeping the pack small while maintaining coverage.

Suggested order

--files-from first — it's small, composable, and useful on its own. --impact-scope is a v0.4+ item since it needs schema tracking.

Reference

• cargo-impact source: https://github.com/asmuelle/cargo-impact
• --context flag implementation: src/lib.rs in the latest commit
• JSON envelope shape: src/format.rs::Report / README §8

Happy to draft a PR for --files-from against this repo if it looks shaped how you'd want it.

[asmuelle]

Shipped --files-from in ea9d240. The canonical workflow works now:

cargo impact --context | cargo context --files-from -

What's in

• --files-from <PATH|-> — newline-delimited, repo-relative, # comments allowed
• New "📂 Scoped Files" section in the pack at P_DIFF priority (so it survives budget pressure on par with the diff itself)
• Each file passes through Scrubber::scrub_file — .env etc. in the list yield [REDACTED FILE: ...], never raw secrets
• Missing paths are silently skipped; the section header reports the count (3 file(s) included via --files-from (1 listed path(s) skipped: missing, ...))
• --files-from - claims stdin and suppresses the prompt-from-stdin path; --files-from <path> leaves stdin free for the prompt
• Files-from paths join the diff-changed set when the related-tests collector runs, so a test that references a scoped file by stem gets surfaced even when the file isn't in git diff
• Language hint on the fenced block derived from the extension (.rs → rust, .toml → toml, .yaml/.yml → yaml, etc.)

Tests

+4 unit tests in pack::tests cover real-file inclusion + missing-path accounting, the all-missing → None short-circuit, path-rule redaction, and language-hint mapping. Workspace total: 92 tests, all six Stop-hook gates green.

What's deferred

--impact-scope <PATH> (the JSON envelope path) — keeping the issue open so it stays on the radar, but I'd want to bump the issue toward a v0.4 milestone since it needs schema tracking against cargo-impact's Report type. Happy to take that on once the schema feels stable upstream.

[asmuelle]

Reopening — part 1 (--files-from) is shipped, but part 2 (--impact-scope <PATH> consuming the JSON envelope) is still open. Tracking that separately here.

[asmuelle]

--impact-scope <PATH> — schema proposal

Posting this so the second half of the issue has something concrete to react to. cargo-impact v0.3.0 is live on crates.io with a stable JSON envelope — here's what cargo-context --impact-scope can rely on.

The envelope (cargo-impact --format json output)

{
  "version": "0.3.0",                    // cargo-impact crate version that produced this
  "changed_files": ["src/lib.rs", ...],  // repo-relative, forward-slash normalized
  "candidate_symbols": ["foo", "Bar"],   // top-level items intersected with diff
  "findings": [                          // sorted: severity → tier → kind → evidence → id
    {
      "id": "f-abcd1234...",             // content-hashed hex, stable across runs
      "severity": "high",                // "high" | "medium" | "low" | "unknown"
      "tier": "likely",                  // "proven" | "likely" | "possible" | "unknown"
      "confidence": 0.85,                // 0.0-1.0, always present
      "kind": "trait_impl",              // kind-tagged, see stable list below
      // kind-specific fields flatten here — trait_name, impl_for, test, etc.
      "evidence": "…",                   // human-readable explanation, UTF-8
      "suggested_action": "cargo nextest run -E 'test(foo)'"  // optional
    }
  ],
  "summary": {
    "total": 23,
    "by_severity": { "high": 3, "medium": 15, "low": 5 },
    "by_tier": { "proven": 0, "likely": 18, "possible": 5, "unknown": 0 }
  }
}

Stability commitment (v0.3 → v0.4)

• Field additions: non-breaking. New top-level or per-finding fields may appear; consumers should ignore unknown fields.
• Field removals: breaking. Reserved for the v0.4 bump.
• `kind` values: stable enum. Current set: `test_reference`, `trait_impl`, `derived_trait_impl`, `dyn_dispatch`, `doc_drift_link`, `doc_drift_keyword`, `ffi_signature_change`, `build_script_changed`, `semver_check`, `trait_definition_change`, `resolved_reference`, `runtime_surface`. New kinds may be added; consumer should degrade gracefully on unknown kinds.
• `severity` / `tier`: closed enums within v0.3, treat unknown as `unknown`.
• `confidence`: always in `[0.0, 1.0]`, f64.
• `id`: content-hashed; same finding across runs → same id. Consumers can round-trip ids via `impact_explain`.
• `evidence` / `suggested_action`: free-form UTF-8 prose, not machine-parseable. Present for humans + LLMs.

The full `Report` type is exported from the `cargo-impact` crate as `cargo_impact::format::Report` — you can add it as a dev-dep for ground-truth deserialization, or hand-roll serde structs against this schema.

Suggested `cargo-context` behaviors

Things `--impact-scope` unlocks that `--files-from` can't, in rough order of user-visible payoff:

1. Prioritize by severity + confidence. A High/`Likely 0.95` finding deserves more context than a Low/`Possible 0.40` one. Sort included-file chunks by `max(finding.confidence)` per-file so pack budget is spent on what matters.

2. Per-finding mini-pack mode. One section per finding, each containing just the files named by that finding's `primary_path` + kind-specific extras (e.g. for a `trait_impl` finding, include both the trait-defining file and the impl-site file). Useful when an agent wants to iterate through findings one at a time.

3. Filter by confidence threshold. `--impact-scope=.impact.json --min-confidence=0.8` drops Possible-tier findings from the pack. Mirrors `cargo-impact --confidence-min` on the producer side.

4. Exclude already-verified findings. Agents can track which finding ids they've checked and pass them via `--exclude-ids f-aaaa,f-bbbb` so subsequent packs only show new signal.

5. `kind`-aware language hints. A `ffi_signature_change` finding's file gets hinted as `rust` like the others, but a `doc_drift_link` finding could include the `.md` fence.

Concrete CLI shape

cargo context --impact-scope <PATH>            # consume, emit scoped pack
cargo context --impact-scope <PATH> --min-confidence 0.8
cargo context --impact-scope <PATH> --per-finding       # one section each
cargo context --impact-scope <PATH> --exclude-ids f-aaaa,f-bbbb

`-` for stdin is a nice symmetry with `--files-from -` — `cargo impact --format=json | cargo context --impact-scope -` one-liner.

If cargo-context wants a serde-ready crate

Happy to carve out a tiny `cargo-impact-schema` crate (just the `Report` types, no analyzer code, no dependencies beyond serde) if that's easier than treating cargo-impact itself as a dev-dep. Would live inside this repo, published alongside each cargo-impact release with a `^0.3` semver pin. Low maintenance cost since the schema types barely change, and it gives both projects a shared ground-truth.

Let me know which parts fit your vision and which should be scoped differently — happy to iterate.

[asmuelle]

Shipped part 2 in d7bb70b. Every behavior from the schema proposal is live:

What's in

• --impact-scope - — stdin form, mutually exclusive with --files-from -
• Confidence-desc ordering — aggregated Scoped Files render in filter_and_sort order (highest confidence first; None sorts last, ties broken by path). Per-file headers surface id: kind, severity/tier, conf=X.XX.
• --min-confidence <F> — range-checked [0.0, 1.0]; findings with no confidence survive (unknown ≠ below threshold)
• --per-finding — one 📂 Impact: <id> (descriptor) section per finding, with Evidence: and Suggested action: lines pulled from the envelope
• --exclude-ids f-aaaa,f-bbbb — comma-delimited, filtered pre-sort
• Kind-aware language hints — doc_drift_link / doc_drift_keyword → markdown regardless of extension; everything else falls through to the shared extension map
• Co-located findings dedupe to a single file block (no duplicate reads), with every contributing finding's id+descriptor listed on the shared header

Schema handling

Hand-rolled in cargo_context_core::impact against serde_json::Value, not against a shared cargo-impact-schema crate. Reasoning: the typed Finding struct uses Option for every non-path field and unknown top-level/per-finding fields are ignored, so a v0.3 → v0.4 bump should decay gracefully without a version pin. If you do end up publishing cargo-impact-schema, happy to swap over — the surface is small enough that the change would be local to impact::parse_envelope.

What's not in

• kind-specific extras in per-finding mode (e.g. for trait_impl, include both the trait-defining file and the impl-site file). Current per-finding mode embeds just primary_path; everything else comes from the envelope. The schema doesn't yet expose secondary paths as a first-class field, so I'd want to revisit this once cargo-impact has a place to put them.

Stats

• +18 tests (12 core impact module, 6 pack-rendering, 7 CLI arg-parse). Workspace: 120 passing.
• Clippy -D warnings clean, cargo fmt --check clean.
• End-to-end verified against a synthetic envelope (confidence sort, filters, per-finding, stdin, range/conflict guards).

Closing as complete.