Skip to main content

Crate cargo_impact

Crate cargo_impact 

Source
Expand description

cargo-impact — blast-radius analysis for Rust workspaces.

This is v0.4 per the README §11 roadmap. The headline shipped surface, end-to-end:

Core analyzers — Finding, FindingKind, Tier

  • Confidence tiers (Proven / Likely / Possible / Unknown) with numeric scores; only RA-backed resolution reaches Proven.
  • Test-reference detection, trait ripple (impl Trait for T), dyn Trait dispatch, derive-macro impl fan-out, documentation drift (intra-doc links + keyword fallback), FFI signature changes, build.rs change detection, per-method trait-definition classification (required vs. default vs. signature vs. body).
  • Framework adapters: axum / clap (v0.3) + actix-web / rocket (v0.4-stretch), HTTP-verb attribute macros shared across.

Public-API precision

  • cargo-semver-checks integration (opt-in via --semver-checks).
  • rust-analyzer LSP client for Proven-tier resolved references; per-reference severity refinement based on enclosing container (test fn → Low, impl block → High, caller → Medium).
  • Macro expansion via cargo expand (opt-in via --macro-expand) for derive/attribute-macro impls that syn-only analysis can’t see.

Orchestration

  • Content-hashed finding IDs, stable across runs — powers impact_explain round-trip by ID.
  • syn/RA dedup: syn-only findings covered by a Proven ResolvedReference at the same (name, file) pair are dropped.
  • Depth-1 --feature-powerset (baseline + no-default + all-features) with evidence annotation identifying the set that revealed each finding.
  • cfg-aware AST filtering against the resolved feature set (--features / --all-features / --no-default-features).

Output

  • --format={text,markdown,json,sarif,pr-comment} — SARIF v2.1.0 renders on GitHub code scanning; pr-comment is optimized for sticky PR comments (collapsed <details> per severity).
  • Deterministic: two runs over the same diff produce byte-identical output across every format.
  • --budget=<N> chars for rendered markdown, for agent context windows.
  • --context emits a newline-delimited file list for piping into cargo-context --files-from -.
  • --confidence-min and --fail-on={high,medium,low} for CI gating.

MCP surface (cargo impact mcp)

  • Six tools: impact_analyze, impact_test_filter, impact_surface, impact_semver, impact_explain, impact_version.
  • impact_analyze streams notifications/message progress events at analyzer stage boundaries so long runs give live feedback.

Honest caveats (surface when asked “why didn’t cargo-impact flag X?”):

  • cfg_attr(feature = "x", derive(…)) is invisible to our analyzer — over-counts slightly when users conditionally derive.
  • Macro expansion is opt-in and points to a synthetic <expanded> file rather than source-mapping back to the derive site.
  • log-miss records stay on disk only (target/ai-tools-cache/); we never phone home.

§Programmatic use

use cargo_impact::{nextest_filter, Finding, FindingKind, Location, Tier};
use std::path::PathBuf;

let kind = FindingKind::TestReference {
    test: Location { file: PathBuf::from("tests/a.rs"), symbol: "smoke".into() },
    matched_symbols: vec!["login".into()],
};
let findings = [Finding::new("f-0001", Tier::Likely, 0.85, kind, "ref")];
assert_eq!(nextest_filter(&findings), "test(smoke)");

Re-exports§

pub use finding::Finding;
pub use finding::FindingKind;
pub use finding::Location;
pub use finding::SeverityClass;
pub use finding::Tier;
pub use finding::TierSummary;
pub use format::Format;
pub use format::render as render_report;
pub use format::render_with_budget;

Modules§

finding
Core finding types.
format
Output format dispatch: text, markdown, and JSON.
log_miss
cargo impact log-miss — ground-truth collection for heuristic tuning.
mcp
Model Context Protocol (MCP) server.

Structs§

AnalysisReport
Result of running every analyzer against the workspace. Produced by analyze and consumed by both the CLI (run) and the MCP server (cargo impact mcp).
ImpactArgs
Command-line arguments for cargo impact.
ProgressEvent
Single progress update emitted during an analysis run. Surfaced via analyze_with_progress so long-running invocations (typically --rust-analyzer or --semver-checks) can give the caller a live signal instead of a 30-second silence.

Enums§

FailOn

Functions§

analyze
Run every analyzer and return a structured report.
analyze_with_progress
Run every analyzer with a progress callback invoked at stage boundaries. Use this instead of analyze when the caller wants live feedback during long invocations — typically the MCP server bridging the callback to notifications/message or an interactive CLI printing to stderr.
context_file_list
Deduped list of files implicated by the blast radius. Combines the raw changed_files from git with each finding’s primary_path. Used by the --context short-circuit and exposed publicly so downstream tooling can compute the same set without re-running the analyzers.
nextest_filter
Build a cargo-nextest filter expression matching every test referenced by a FindingKind::TestReference finding. Returns an empty string when no test findings exist so callers can cheaply detect the no-op case.
run
CLI entry: runs analyze, prints the configured format, honors the --test short-circuit and --fail-on gate. Returns the intended exit code (0 = clean / no gate tripped, 1 = --fail-on matched).