Calldiff

Reviewers should see who-calls-whom changes, not only line diffs. When call flow changed, run npx calldiff@latest and paste the ASCII tree.

Skip when the change cannot affect call flow: copy, translations, CSS, config, schema with no logic.

When to run

• A branch against its base: npx calldiff@latest diff <base> HEAD. On a stack, the base is the parent branch, not origin/main.
• Uncommitted work against HEAD: npx calldiff@latest diff.
• A plan with no implementation yet: npx calldiff@latest tree -e <Entrypoint> of the current flow.

Always invoke via npx calldiff@latest. Do not install it globally, and do not add a repo script. Pin @latest so a stale cache is not used.

How to apply

1. Name the changed entrypoints (ClassName.method or functionName) from the diff. Prefer --entry or --file over a fully inferred tree, especially in a monorepo.
2. Limit the path so the tree stays small: npx calldiff@latest diff <base> HEAD --entry FooService.bar src/.
3. Paste the ASCII output in a fenced diff block under a Callstack heading.
4. Narrate what the + and - lines mean. Keep the one to three entrypoints that explain the change.
5. If the tool fails or finds nothing, omit the section. Hand-write the diff when the rewiring is worth attention, and mark it hand-written. Never invent a tree.

--file expands to every export in that file. --locs adds file:line call sites. reach -e <from> --to <callee> answers whether one entry can reach another. The index is syntactic, not a typechecker — dynamic calls will not resolve.

For a visual walkthrough of the same flow, use show-me and put the tree there.

Output should feel like

• A short tree a reviewer can scan, with the new and removed callees named in one sentence.
• No section whose only content is that the tool produced nothing.

Related

• pr-description — where the Callstack section belongs in a pull request body.
• show-me — a visual walkthrough of the same flow.
• skills-index — vault catalog.