Skip to content

impact

The question a reviewer, a pre-commit hook, or a nervous contributor asks before an edit: if I touch this file, what else stops working?

impact answers it directly. The same analysis is available as graph --what-depends-on, but it is a flag on a command whose help is mostly about dependency structure — so the primitive worth having as a command is buried behind the one nobody reads the help for.

Terminal window
sephera impact crates/sephera_core/src/plugins.rs # what breaks if this file changes
sephera impact crates/sephera_core/src/plugins.rs --depth 1 # only its direct importers
sephera impact crates/sephera_graph/src/symbol_impact.rs --symbol SymbolImpact # one name, not the whole file

Paths are relative to the repository root.

impact takes one path or several. Asking about five files costs about the same as asking about one, because the graph is built once and every path is measured against it.

Terminal window
sephera impact crates/sephera_context/src/types.rs
# Blast radius for `crates/sephera_context/src/types.rs`
7 files depend on this.
## Dependents
- `crates/sephera_context/src/builder.rs` imports `super::types::ContextDiffMetadata`, `super::types::ContextDiffSelection`, `super::types::ContextFile`, `super::types::ContextLanguageSummary`, `super::types::ContextMetadata`, `super::types::ContextReport`, `super::types::SelectionClass`
- `crates/sephera_context/src/candidate.rs` imports `super::types::SelectionClass`
- `crates/sephera_context/src/excerpt.rs` imports `super::types::ContextExcerpt`, `super::types::ContextFile`, `super::types::SelectionClass`
- `crates/sephera_context/src/focus.rs` imports `super::types::SelectionClass`
- `crates/sephera_context/src/grouping.rs` imports `super::types::ContextFile`, `super::types::ContextGroupKind`, `super::types::ContextGroupSummary`
- `crates/sephera_context/src/lib.rs` imports `self::types`, `types::ContextDiffMetadata`, `types::ContextDiffSelection`, `types::ContextExcerpt`, `types::ContextFile`, `types::ContextGroupKind`, `types::ContextGroupSummary`, `types::ContextLanguageSummary`, `types::ContextMetadata`, `types::ContextReport`, `types::SelectionClass`
- `crates/sephera_context/src/ranker.rs` imports `super::types::SelectionClass`

Each dependent is listed with the names it imports from the target, because “rename tokenize and these two files break” is actionable and a list of paths is not. A file that reaches the target transitively, without naming it, is listed by path alone rather than given an import that does not exist.

The rules matter, because --fail-on compares against this number:

  • The target is never a dependent of itself. A use super::*; inside an inline test module resolves to the file it is written in. That is a self-reference, counted separately in the graph metrics, and it does not add one to the radius. (At the top of a separate child file, the same words name the parent module that declares it — a real edge to a different file, and counted as one.)
  • A file is counted once, not once per path that reaches it. Two files depending on one, through two different chains, is one dependent.
  • Only resolved edges count. An edge the resolver could not place is a path it failed to find, not a coupling. Counting it would claim exactly the connection a blast radius exists to be honest about.
  • mod child; counts. A module declaration is a real dependency: deleting service.rs breaks the module that declared it, so “changing this breaks that” is true. It is excluded from cycle detection instead, because no edit can break a parent and its own child apart — but excluding it from the blast radius once hid 17 of ignore.rs’s 34 real dependents on this repository, because core.rs is the parent of most of the tree.

That last rule is the one worth understanding. A ring is reported only when every link in it is something an edit can remove.

An empty answer says “No file imports this one.” rather than rendering nothing. An empty report and a typo are indistinguishable once it is on a screen, so a path that matches no analysed file is an error, not an empty result.

Terminal window
sephera impact crates/sephera_context/src/types.rs --depth 1

--depth 1 reports only files that import the target directly. 2 also reports files that import those. 0 reports the target with no dependents. Omitting it reports the whole transitive closure.

A bounded answer says so, rather than letting a truncated list read as a complete one.

The number is the number of hops, and graph --depth counts them the same way — the same flag bounds the same walk on both commands.

Terminal window
# Only the 7 files that import it directly
sephera impact crates/sephera_context/src/types.rs --depth 1
# Only the dependents inside one package
sephera impact crates/sephera_context/src/types.rs --focus crates/sephera_context

--focus narrows the answer. A path matches exactly or as a directory prefix at a / boundary, so crates/two covers crates/two/user.rs but not crates/twone/extra.rs. Repeat the flag for several scopes.

The target is never filtered by the scope. Scoping to one package and reporting on a file in another is a question rather than a mistake — it is how you ask what in this package would break from a change over there. The report still names the file you asked about, so an empty answer reads “nothing in this scope depends on it” rather than “nothing at all”.

graph --focus with a reverse query narrows the same way, and the two agree because both use the same path predicate.

The blast radius is the right answer for a change to the file as a whole. It is the wrong answer for a change to one name inside it: renaming a struct should not report the files that only import its neighbour. --symbol narrows the question to one exported name.

Terminal window
sephera impact crates/sephera_graph/src/symbol_impact.rs --symbol SymbolImpact
# Symbol impact for `SymbolImpact` in `crates/sephera_graph/src/symbol_impact.rs`
2 files import `SymbolImpact` from this file.
9 more files are downstream of those.
## Files that import `SymbolImpact`
- `crates/sephera_cli/src/impact.rs` via `sephera_graph::symbol_impact::SymbolImpact`
- `crates/sephera_graph/src/lib.rs` via `symbol_impact::SymbolImpact`
## Downstream
- `crates/sephera_cli/src/change_impact.rs`
- `crates/sephera_cli/src/lib.rs`
- `crates/sephera_cli/src/run.rs`
- `crates/sephera_cli/tests/loc_table.rs`
- `fuzz/fuzz_targets/render_context_markdown.rs`
- `fuzz/fuzz_targets/render_loc_table.rs`
- `gui/src-tauri/src/commands/graph.rs`
- `gui/src-tauri/src/commands/mod.rs`
- `gui/src-tauri/src/main.rs`

The report keeps three lists apart because they are three different strengths of claim:

  • Files that import the symbol — their import statements name it. This is the count --fail-on compares against when --symbol is set.
  • Namespace importers — files that import the target’s namespace wholesale (use a::*). They may use the symbol without naming it, so they are reported as may-use, never merged into the count of users.
  • Downstream — files downstream of the first two groups. A file that imports the target only for a different name, and is reached no other way, is not in this report at all.

The contrast can be stark. crates/sephera_core/src/declarations.rs has 32 dependents as a file; its DeclaredNames type is named by exactly one of them. Both numbers are true — they answer different questions, and --symbol exists so the second one can be asked.

How a use is recognised depends on how the language spells an import. An item path’s last segment is the name (Rust’s crate::a::Router, Java’s com.x.Router); a JavaScript clause records its names on the edge; a Python from m import Router counts when its module statement landed on the target and the name is declared there. Go and C/C++ imports name packages and headers rather than items, so for files in those languages there is almost nothing to narrow with: the symbol report shows few or no direct users rather than inventing them, and the file-level radius remains the answer there.

One coincidence is accepted rather than hidden: a symbol spelled exactly like its own module (json inside crate::json) also matches plain imports of the module, whose last segment is the same word. The evidence path printed with each user shows the module import it came from, so the match cannot pass as an item import.

Terminal window
sephera impact crates/sephera_context/src/types.rs --format json
{
"targets": [
{
"dependent_count": 7,
"dependents": [
{
"file": "crates/sephera_context/src/builder.rs",
"imports": [
"super::types::ContextDiffMetadata",
"super::types::ContextDiffSelection",
"super::types::ContextFile",
"super::types::ContextLanguageSummary",
"super::types::ContextMetadata",
"super::types::ContextReport",
"super::types::SelectionClass"
]
},
{
"file": "crates/sephera_context/src/candidate.rs",
"imports": [
"super::types::SelectionClass"
]
},
{
"file": "crates/sephera_context/src/excerpt.rs",
"imports": [
"super::types::ContextExcerpt",
"super::types::ContextFile",
"super::types::SelectionClass"
]
},
{
"file": "crates/sephera_context/src/focus.rs",
"imports": [
"super::types::SelectionClass"
]
},
{
"file": "crates/sephera_context/src/grouping.rs",
"imports": [
"super::types::ContextFile",
"super::types::ContextGroupKind",
"super::types::ContextGroupSummary"
]
},
{
"file": "crates/sephera_context/src/lib.rs",
"imports": [
"self::types",
"types::ContextDiffMetadata",
"types::ContextDiffSelection",
"types::ContextExcerpt",
"types::ContextFile",
"types::ContextGroupKind",
"types::ContextGroupSummary",
"types::ContextLanguageSummary",
"types::ContextMetadata",
"types::ContextReport",
"types::SelectionClass"
]
},
{
"file": "crates/sephera_context/src/ranker.rs",
"imports": [
"super::types::SelectionClass"
]
}
],
"depth": null,
"target": "crates/sephera_context/src/types.rs"
}
]
}

The shape is the same whether you pass one path or five, so a consumer does not need two parsers. dependent_count is always present, so it never has to distinguish “zero dependents” from “this field is missing”.

Terminal window
sephera impact crates/sephera_cli/src/run.rs --fail-on 40

Exits 2 when at least 40 files depend on the target. The limit is the first failing value, so --fail-on 40 fails on the fortieth dependent and not the thirty-ninth.

With several targets, every target at or over the limit is named on stderr, so a run that violates three rules does not take three CI runs to discover.

The report is still printed; only the exit code changes.

codemeaning
0analysed, nothing crossed the threshold
1the analysis could not run
2analysed, the blast radius crossed --fail-on

The distinction is deliberate. Merging 1 and 2 would make a broken install and a violated rule look identical in a log — and that is the situation where someone teaches their CI to swallow the failing exit code and then never notices either one again.

A single repo’s blast radius answers “what breaks in this repo”. The real world is shared libraries: you change mylib, and a service in another repo that depends on it breaks. --multi answers the cross-repo question by honoring what the manifests already declare — a path dependency in Cargo.toml (or file: in package.json, replace in go.mod, and the other supported manifests) is a declaration that two repos are developed together, so Sephera turns it into edges.

Run it from the repo that declares the path dependency, and point the target at a file inside the dependency repo:

Terminal window
# from the repo that declares `mylib = { path = "../mylib" }`
sephera impact ../mylib/src/lib.rs --multi
## Cross-repo dependents (via path dependencies)
### `../mylib/src/lib.rs`
- `src/main.rs` imports `mylib::greet`
(via path dependency `mylib` → `mylib` in `Cargo.toml`)

Each entry names the importing file, the import path it used, and the path dependency that made the edge possible. The section is omitted entirely when there are no path dependencies or no cross-repo dependents — there is no empty section.

Targets are split per file: a target inside a path dependency gets the cross-repo section, and every other target gets its normal in-repo blast radius, so one run can mix both —

Terminal window
# the dep target reports cross-repo dependents, the local target its
# in-repo blast radius, in one report
sephera impact ../mylib/src/lib.rs src/main.rs --multi

A path dependency inside the repo itself (foo = { path = "crates/foo" }) is still local: its files get the normal blast radius, not the cross-repo section, because the import is already resolved by the in-repo graph.

A target that is in no repo and in no path dependency is an error, exactly as without --multi: a typo or a path outside every known repo is reported as unresolvable, never silently answered with an empty report.

Supported manifests: Cargo.toml (Rust path deps), package.json (npm file:), pyproject.toml (PEP 508 file://), go.mod (replace), settings.gradle/settings.gradle.kts (includeBuild), pom.xml (<modules>), CMakeLists.txt (add_subdirectory), WORKSPACE / MODULE.bazel (local_repository / local_path_override).

Three rules that matter:

  1. Only path dependencies are followed. Version and git dependencies cannot be analyzed without source; their imports are skipped.
  2. Edges come from import declarations (use, import, #include), the same unit as in-repo edges.
  3. Direction is fixed. The target must live in a path dependency of the current repo. Running from the library repo itself reports the in-repo blast radius only.

Known limitation: --format json is ignored for cross-repo targets — the output renders as Markdown. JSON for the cross-repo section is not yet implemented. In a mixed run the in-repo part renders as JSON and the cross-repo section follows it as Markdown.

Two repos, one change the shock jumps the fence unseen one path ties their fate

graph --diff <SPEC> answers the same question for a whole change rather than one file: it reports the blast radius of every file the change touched, widest first, building the graph once.

graph --what-depends-on <FILE> remains available and produces the same answer inside a full dependency report.

Touch one file, then ask count the files that break downstream before you edit