feat(graph): explain bounded dependency impact paths

[DivyamTalwar]

Summary

• add structorium impact <file-or-dir> for bounded dependency blast-radius exploration
• distinguish files that depend on a target from dependencies the target itself reaches
• attach a deterministic shortest-path witness to every reported relationship
• support exact file and directory-prefix seeds
• emit operator text, agent/CI JSON, or review-ready Mermaid
• enforce shared depth/node budgets and mark truncated reports explicitly
• include the narrow deterministic prompt-test fix exposed by the first next-wave CI run

Why this is high leverage

Structorium detects coupling and cycles, but operators still need to answer “what could this change break?” before editing a shared module. The new explorer reuses each language integration's real dependency graph and turns it into bounded, reviewable evidence without Neo4j or another service.

Competitive research and provenance

This is an original implementation informed by public workflows, not copied source:

• dependency-cruiser provides multiple dependency-graph reporters, including Mermaid, for repository-native review: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md
• dependency-cruiser's folder-level graph guidance demonstrates why large graphs need focused views: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md#folder-level-dependency-graph-ddot-reporter
• CodeQL path queries use path evidence to explain reachability: https://codeql.github.com/docs/writing-codeql-queries/creating-path-queries/

Structorium's implementation is multi-language through its existing graph contract, has explicit dependency/dependent semantics, includes shortest witnesses, and shares a hard traversal budget.

Verification

• pytest -q tests/commands/test_cli.py tests/detectors/test_graph.py tests/engine/test_impact.py tests/commands/test_impact_cmd.py — 117 passed
• exact deterministic prompt regression — 1 passed
• focused new-feature/CLI suite plus regression — 8 passed
• compileall on new modules — passed
• Ruff on every changed Python file — passed
• git diff --check — passed

Safety and scope

• no external graph service or dependency is introduced
• invalid limits and unmatched paths fail closed
• the node cap includes seeds and results; large directory targets cannot produce unbounded evidence
• source-to-dependency edges are never inferred or invented by renderers
• no existing PR or branch was changed

The repository dependency-review security job requires the repository dependency graph setting; CodeQL, pip-audit, and secret scan remain the code-authoritative checks.

This PR intentionally remains open and unmerged.

[DivyamTalwar]

Implementation evidence

Contract	Evidence
Real graph semantics	reuses each language integration's source → dependency graph; renderer does not infer edges
Change blast radius	dependents reverses real edges; dependencies follows them; both shares one budget
Explainability	deterministic breadth-first traversal attaches one shortest-path witness to every result
Monorepo safety	depth must be >= 1; hard node budget includes directory-expanded seeds; truncation is explicit
Multi-surface evidence	concise text, stable JSON, and GitHub-renderable Mermaid
Determinism	nodes, edges, traversal neighbors, entries, and seeds are sorted
Local evidence	117 CLI/graph/new-feature regressions passed; exact prior flaky test passed; Ruff/compileall/diff hygiene passed

Primary pattern sources:

• dependency-cruiser reporters: https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md
• dependency-cruiser large-graph guidance: https://github.com/sverweij/dependency-cruiser/blob/main/doc/faq.md#folder-level-dependency-graph-ddot-reporter
• CodeQL path-query evidence: https://codeql.github.com/docs/writing-codeql-queries/creating-path-queries/

No source was copied and no runtime dependency was added.

Latest reviewed head: d01a3e575bc6ad88dafc4910e071935dcee2741e.

This PR is intentionally open and unmerged. GitHub CI/Security on this exact head is now authoritative; dependency-review is expected to remain externally blocked until the repository dependency graph is enabled.

[DivyamTalwar]

Final authoritative verification

Latest head: d01a3e575bc6ad88dafc4910e071935dcee2741e

• CI run 32664005936: success
  • all 9 jobs green: lint, typecheck, architecture contracts, CI contracts, core tests, full tests, package smoke, Python 3.11 compatibility, and Python 3.13 compatibility
• Security run 32664005920:
  • CodeQL job 97254470146: success
  • pip-audit job 97254470143: success
  • secret-scan job 97254470026: success
  • dependency-review job 97254470109: externally blocked because the repository dependency graph is disabled

The Security workflow's aggregate failure is therefore repository configuration, not a source, dependency, secret, or CodeQL failure. The implementation-authoritative CI and security analyzers are green on the exact latest head.

PR state: open, unmerged.