Cookbook: impact analysis

Use these recipes to estimate what may depend on a symbol, file, or change.

Recipe 1: impact from one symbol

Problem

You plan to change TokenVerifier and want a bounded review scope.

Commands

compass explain TokenVerifier
compass affected TokenVerifier --depth 3

Interpret

explain shows immediate incoming/outgoing context. affected walks incoming impact-relevant relations:

ApiMiddleware --CALLS--> TokenVerifier

change TokenVerifier
        |
        `--> review ApiMiddleware

The result is a review queue, not a required edit list.

Variations

Narrow to one relation:

compass affected TokenVerifier --relation calls --depth 2

Use a saved graph:

compass affected TokenVerifier --graph target/baseline.json --depth 3

Recipe 2: exact direct callers

Problem

You need a deterministic list for automation.

Command

compass query --cql \
  'MATCH (caller)-[edge:CALLS]->(target)
   WHERE target.label = $target
   RETURN caller.id, edge.confidence, target.id
   ORDER BY caller.id
   LIMIT 500' \
  --param target=TokenVerifier \
  --format json \
  --output target/token-verifier-callers.json

Interpret

Review the schema tag, then distinguish direct and resolved evidence by edge.confidence.

If labels repeat, first discover the stable target ID and query by target.id.

Recipe 3: downstream dependencies

Problem

You want to know what a service calls or uses.

Command

compass query --cql \
  'MATCH (source)-[edge:CALLS|USES|IMPORTS_FROM]->(dependency)
   WHERE source.id = $source
   RETURN type(edge), dependency.id, edge.confidence
   ORDER BY type(edge), dependency.id
   LIMIT 500' \
  --param source='"src/auth.rs::TokenVerifier"' \
  --format table

Parameter parsing accepts JSON scalars; quote a string explicitly when shell content could be mistaken for another JSON type.

Recipe 4: review semantic changes across commits

Problem

You need an actionable account of what may break, what behavior changed, and which callers or modules are affected.

Commands

compass history build HEAD~1 --code-only
compass history build HEAD --profile-from HEAD~1
compass diff HEAD~1 HEAD

For automation:

compass diff HEAD~1 HEAD --format json \
  > target/semantic-diff.json

Interpret

The profile-from step makes extraction semantics comparable. Added/removed parameters, dependency changes, behavior summaries, and affected callers are static evidence. They do not prove runtime behavior. Test gaps are reported only when test-mapping evidence is sufficient; otherwise verification is marked partial or unavailable.

Recipe 5: PR review checklist

Problem

A PR changes several files and you want graph-informed review.

Workflow

1. Record changed files:

   git diff --name-only BASE...HEAD

2. Query/explain key changed symbols.

3. Run affected for public or hub symbols.

4. Compare exact commit graphs if both revisions are available.

5. Inspect cross-community edges.

6. Add tests/configuration/consumers to the review list.

Checklist:

[ ] Direct callers reviewed
[ ] Importers/consumers reviewed
[ ] Implementers/inheritors reviewed
[ ] Tests and fixtures reviewed
[ ] Configuration/schema dependencies reviewed
[ ] Ambiguous edges verified manually
[ ] Dynamic/reflection/external behavior considered
[ ] Graph profile and revision recorded

Common false conclusions

Recovery

If results are empty:

• confirm graph freshness and requested revision;
• explain the seed to confirm identity;
• query by file/module first;
• inspect ignore/generated code;
• confirm relation names;
• use --at for historical rather than a current graph.

Related pages

• Explore a codebase
• Provenance
• Versioned history

Next step: convert the impact output into a human review checklist and verify the highest-risk relations in source.