memory-impact-analysis

name	memory-impact-analysis
description	Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "is it safe to change X?", "what depends on this?", "what will break?", "show me the blast radius". Also compose with PR review — run this per touched symbol after `gh pr diff`.
metadata	{"version":"0.0.1"}

Impact Analysis with hoangsa-memory

Answer "what breaks if I change X?" using the code graph. This is the one thing the graph does that grep + IDE-nav cannot: it traverses calls, references, and extends edges across files, packages, and languages in one query.

When to Use

• "Is it safe to change this function?"
• "What will break if I modify X?"
• "Who uses this code?"
• Before any rename / signature change / semantic tweak.
• Before committing — cheap sanity check on blast radius.
• As one step in a PR review (see §PR review compose below).

Workflow

1. memory_recall({query: "<name or concept>"})        → find the exact FQN
2. memory_impact({fqn, direction: "up", depth: 3})    → who calls / references
3. (optional) memory_symbol_context({fqn})            → full 360° on target
4. Quote chunk ids in your answer                    → prove grounding

1. Pin the FQN

Graph keys are module::symbol (e.g. server::dispatch_tool). If the user gave you a bare name, run memory_recall first to disambiguate — otherwise memory_impact returns symbol not found.

2. Walk the blast radius

memory_impact {
  fqn: "server::dispatch_tool",
  direction: "up",       // "up" | "down" | "both"
  depth: 3               // 1..8
}

• up (default) — callers, referencers, subtypes. Answers "what breaks". Use this 90% of the time.
• down — callees, parent types. Use when you want "what does this depend on".
• both — union. Expensive; only when you're mapping a whole subsystem.

Results are grouped by BFS depth. Depth 1 is direct dependents; deeper rings are transitive and usually less critical. Quote the depth-1 ring in your answer — that's what actually breaks on change.

3. Read the context (optional)

If you're about to edit the symbol, also pull memory_symbol_context {fqn} to see siblings (other symbols in the same file you might accidentally touch) and unresolved imports (external deps you can't mock).

4. Decide + cite

Answer in this shape:

Changing X affects N callers at depth 1: A::f, B::g, C::h. Transitive reach is M symbols across depth ≤ 3. Safe to change if the signature is preserved; breaking signature changes need follow-up edits in [list].

Always cite the chunk ids from the recall output. If the impact set is large, call out the top 3–5 most load-bearing callers (tests, public API, cross-crate edges).

PR review compose

During PR review, pipe the diff through memory_detect_changes:

1. gh pr diff <n>                                    → unified diff
2. memory_detect_changes({diff, depth: 2})            → touched symbols + upstream
3. For each high-risk symbol: memory_impact({..})    → deeper walk
4. Flag: missing tests, public API breaks, cross-crate edges

memory_detect_changes parses the diff, maps hunks to graph nodes, and returns their upstream callers in one call — cheaper than running memory_impact per symbol. Use it as the first pass, then drill in with memory_impact on anything risky.

Compose with the Gate-4 analyzers (hoangsa-analyzer-failure, hoangsa-analyzer-types, hoangsa-analyzer-claims), which ship with HOANGSA — hoangsa-memory covers the graph side of PR review (blast radius, orphan symbols, test coverage gaps on touched callers); the analyzers cover error handling, type design, and comment accuracy.

Anti-patterns

• Skipping the recall step. Running memory_impact on a guessed FQN wastes a round-trip when symbol not found comes back. Always recall first unless you literally copied the FQN out of prior output.
• Mistaking depth-5 transitive reach for real risk. Most changes don't propagate past depth 2. Lead with the depth-1 ring.
• Using direction: both by default. It's 2–5× the noise. Only reach for it when you genuinely want both directions.
• Forgetting references. memory_impact direction: up includes non-call references (type refs, trait bounds, generic params). A symbol with 0 callers but 20 references is still load-bearing.

When the graph is wrong

The graph reflects the last hoangsa-memory index . run. If the repo has been edited since, callers may be stale. Signs: a caller in the result that the user insists doesn't exist any more. Remedy: hoangsa-memory index . or hoangsa-memory watch . (which re-indexes on save), then retry.

Symbols added in an unsaved edit won't be in the graph at all — that's why impact analysis is a pre-edit tool, not a post-edit one.