diffninja 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanishq Kancharla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# diffninja
+
+PR reviews for humans, not prose from a chatbot, run from inside your coding
+agent. Ask Claude Code, Codex, pi, or another MCP-capable agent CLI to review a
+GitHub PR link and diffninja returns a review workspace where you read the diff,
+write inline comments, and submit the review yourself. Give the agent a diff or
+a git range and diffninja returns an evidence-backed reading agenda alongside
+the complete diff, as structured data for the agent and as a page for you.
+
+diffninja is an MCP server (`review_diff`) plus a `diffninja setup` command that
+registers it. It has no terminal review mode.
+
+Analysis is local and deterministic: no model is called, no source leaves your
+machine, and the same input always gives the same report. Each hunk gets change
+facts — did a comparison, a limit, or an input check change; is a failure handed
+to the caller, deferred, or discarded — each pointing at the changed line it
+rests on. Interpreting what the change means is left to you and, if you ask it,
+to the agent you already use. diffninja writes no review prose. You stay the
+reviewer.
+
+## What you need
+
+- **Node.js 22.18 or newer.**
+- **An MCP-capable agent CLI:** Claude Code, Codex, OMP, pi, or any client that
+  can launch a stdio MCP server.
+- **GitHub CLI (`gh`) 2.45.0+, authenticated** (`gh auth login`) — only for
+  reviewing pull requests. diffninja never asks for a token; it reuses your
+  `gh` session.
+- No API key. Git ranges may install missing parsing grammars through npm the
+  first time a language is seen.
+
+## Install
+
+Register the MCP server on every agent CLI you use (Claude Code, Codex, OMP,
+pi) with one command:
+
+```bash
+npx -y diffninja setup
+```
+
+It installs the package globally first, then registers the server in each
+detected CLI. `diffninja setup --help` lists the options (`--cli`,
+`--uninstall`, `--dry-run`, `--no-install`); `docs/mcp-setup.md` has the manual
+entries.
+
+The package ships `diffninja` (setup only) and `diffninja-mcp` (the MCP server).
+`npx` fetches the latest published version on first run; if a cached copy feels
+stale, pin it explicitly (`npx -y diffninja@latest setup`).
+
+On npm 12 and later, which block dependency install scripts by default, setup
+names the ones diffninja needs (`--allow-scripts=diffninja,tree-sitter,...`), so
+nothing extra is required. If you install by hand, pass the same flag:
+`npm install -g --allow-scripts=diffninja,tree-sitter,tree-sitter-javascript,tree-sitter-typescript diffninja`.
+
+## Review a pull request
+
+Ask your agent to review `https://github.com/OWNER/REPO/pull/123`. It calls
+`review_diff` with the link, reads the pull request, sends its reading with
+`finish_review`, and then gives you a loopback review page, loaded from the
+canonical GitHub patch through your `gh` authentication. The link arrives
+once the agent has read the change, so the page opens complete: the agent's
+reading order, its answers, and its suggested comments. Select diff lines,
+write single-line inline comments and a review body, pick Comment, Approve, or
+Request changes, preview the exact payload, and submit. Comments your agent
+suggests wait under their lines until you add them; every word you submit is one
+you chose, and diffninja only carries it to GitHub. It never approves, blocks, or merges
+anything on its own. The page belongs to the agent's MCP connection and closes
+when the agent exits.
+
+The diff opens in the **reading order**: each hunk is a numbered change,
+most important first, with your agent's answers (does this change behavior,
+does a test exercise it, does it serve the stated goal) and the facts to look
+at above its code. Hunks outside the order follow under **Other changes**.
+Press `j` and `k` to step through the changes. A rail beside the diff lists
+them, marks the one you are reading, and fills in as you read. **By file**
+switches to one block per file, with each change's number where it starts,
+and keeps you on the change you were reading. When the agent works inside your local
+clone it passes it as `repo`; once the clone has the pull request's commits,
+the analysis adds definitions and call flows, and the page opens a file's call
+flow in a drawer beside the diff. diffninja never fetches or writes in the
+clone; when it lacks the commits, the page says so and names the `git fetch`
+that would add them.
+
+## Review a diff or a git range
+
+Ask your agent to review a patch, the working tree, or a range such as
+`main..HEAD` in a repository. It calls `review_diff` with `diff` text or with
+`repo`, `from`, and `to`, and receives the report as the tool result: the exact
+expected outcome when supplied (`expectedOutcome`), a short reading agenda,
+bounded automatic findings, explicit check coverage, and every hunk, ranked as
+**attention**, **uncertain**, **low**, or **passed**; git ranges add call flows
+and snapshot-bound source. Claims in a description are not proof that the code
+fulfills them. Once the agent has sent its reading (below), it gets `reportUrl`:
+a read-only page on `127.0.0.1` with the same report for you to read (the
+agenda, call-flow graphs, and every hunk), served from memory for as long as
+the agent's session lasts.
+The tool writes no report files. Arguments and examples:
+[docs/mcp-setup.md](docs/mcp-setup.md). Trying it on real reviews:
+[docs/pilot.md](docs/pilot.md).
+
+## How static analysis works
+
+1. **Evidence first.** No-op hunks and blank-only document changes pass.
+   Repository snapshots support bounded checks for duplicate function bodies and
+   unread `errors` response fields, plus caller and contract source cards.
+   Optional TypeScript reference checking compares before/after diagnostics,
+   including unchanged consumers, using an explicitly trusted installed compiler.
+   Unsupported or incomplete checks say so.
+2. **Change facts per hunk.** The added and removed lines are read lexically —
+   strings and comments set aside, moved lines cancelling out. Code gets six facts:
+   comparison changed, limit changed (a numeric bound, or `<` turned into `<=`),
+   input check changed (type/shape checks, or a changed guard in front of a
+   raise), failure handed to the caller, failure deferred or retried, failure
+   discarded (an empty or defaulting `catch`, `except: pass`, …). Documentation
+   (`.md`, `.rst`, `.txt`, …) is asked whether an instruction to readers changed
+   (must, never, only, at most, …), a link target changed, or a numeric limit
+   changed. Configuration (`.yml`, `.json`, `.toml`, Dockerfiles, `.env`, …) is
+   asked whether a CI gate was weakened (`continue-on-error`, `|| true`, a
+   failure turned into a warning, a check step removed), permissions or secret
+   access changed, a version pin changed, or a limit changed. Each `yes` cites
+   its changed line. `no` speaks only about the lines the hunk shows. A change
+   that only touches formatting, comments, or line breaks is recognized as such.
+   JS/TS, Java, C#, Go, Rust, C/C++, Kotlin, Swift, PHP, Python, Ruby,
+   documentation and configuration are read; any other file type says that no
+   facts were established instead of claiming none.
+3. **Status and order.** A code or configuration change outside a test file
+   reads **attention**; documentation reads **attention** when it changes an
+   instruction, a link, or a limit, **low** otherwise; a test-file change reads
+   **attention** only when it changes a limit, discards a failure, or weakens a
+   gate, **low** otherwise; a formatting-only change **passed**;
+   an unread file type **uncertain**, for a person to read. Priority orders hunks:
+   a fixed base, plus 10 for a real change, plus the heaviest fact of the
+   boundary group (what the change says or bounds) and of the failure group
+   (failures, CI gates, permissions) — each group counts once, never summed. The report lists
+   manual work first (binary and other metadata-only units), then the read hunks
+   by priority, then passes; among equal priorities the hunk that changes more
+   lines comes first. Hunks in test files (by path convention: `test/`,
+   `*.test.ts`, `test_*.py`, `*_test.go`, …, including snapshots diffninja does
+   not read) come after the other hunks, still ordered by their own priority: a
+   regression test changes as much as its fix.
+   Documentation is not demoted, because prose can be normative. Status is a
+   label for filtering and never reorders the report.
+4. **Questions for your agent.** Where a judgment needs meaning rather than
+   syntax, the report asks the agent that requested it — does this hunk change
+   what callers observe, does a test exercise it, does a test change weaken it,
+   do the docs match the code, does the hunk serve the stated goal. Questions
+   are fixed templates with closed options (always including `cannot-tell`).
+   diffninja itself still calls no model.
+   The agent sends its whole reading in one `finish_review` call: an answer to
+   every question, the reading order of every hunk (most important first),
+   and the line comments it would leave (or none). diffninja checks all of it
+   and only then hands out the page link, so every page you open already
+   carries the agent's answers, its order, and its comment decision; an agent
+   cannot give you a half-read page. The pages list every hunk in the agent's
+   order, attributed to it; diffninja's own order stays available one click
+   away, and statuses stay diffninja's. `record_answers`, `record_order`, and
+   `suggest_comments` update a review afterwards. On 159 held-out open-source
+   pull requests, weighted by the severity of maintainers' actual review
+   comments, a host model that read diffninja's report put the serious
+   comments earlier than diffninja's deterministic order did.
+   On a pull request, the suggested line comments are short, in the reviewer's
+   own voice, with no "Finding 1:" scaffolding. The page shows each under its line; you add one
+   or all of them to your draft with a click, edit or dismiss them, and submit
+   the review yourself. Nothing is posted without you.
+5. **Project context (git ranges only).** What a diff does not show is often
+   the project around it. From the local clone alone — nothing is fetched —
+   the report names the commits that last changed each hunk's removed lines
+   (`git blame` at the base), earlier revert commits that touched a changed
+   file or share a rare word with the goal or the changed file names,
+   contributor guidelines that apply (`CONTRIBUTING`, `AGENTS.md`, `.github/`,
+   docs policy pages such as versioning or preview rules), and, for a new
+   file, identifiers most of its same-named siblings use and it does not
+   (`components/*/select.py`). They add questions for your agent: does a hunk
+   undo a fix it removes, does the change reintroduce something reverted, does
+   it follow the guidelines and the sibling pattern. These are pointers, not
+   verdicts, and never change status or order. A shallow clone says so: lines
+   whose origin lies past its boundary count as unknown.
+
+Intent cross-checks keep author claims and generated summaries separate.
+Source matches are navigation evidence, not proof of fulfillment. Broad goals,
+missing metadata, and behavior not established by the available code remain
+explicitly unestablished. Findings likewise state their scope: duplicated syntax
+is not necessarily duplicated responsibility, and an unread field alone does not
+prove that a real failure was mishandled.
+
+Git-range analysis supplies selected call-site blocks from both snapshots,
+including written arguments, declared parameters, locations, and explicit target
+and binding uncertainty. Unambiguous same-file JS/TS and Python calls support
+positional binding; Python also supports named arguments. Imports, member
+dispatch, dynamic targets, and other grammars do not get guessed mappings.
+These are static source expressions, not runtime values or data-flow analysis.
+TypeScript/TSX extraction includes methods of decorated exported classes,
+including stacked and custom decorators; method source spans retain their
+decorators so decorator-only changes still select the method body. Simple explicit class-field and
+constructor-property types identify candidate dependency methods; unsupported
+receiver types stay unresolved rather than borrowing the containing class's
+method. These are not type-checked or proven runtime bindings.
+
+Review context also follows candidate event and queue relations: static
+`emit`/`emitAsync` keys match `@On*Event` handlers; injected queue `.add` keys
+match `@Processor` consumers' `job.name` cases or `@Process` methods only on a
+matching queue channel. String enum values can connect member keys to literal
+cases. These are source-derived relations, not runtime calls or proof of
+delivery; dynamic keys, aliases, and unrecognized framework syntax can be absent.
+Constant resolution is snapshot-local, including when extraction is cached.
+
+Module-level TypeScript/TSX interfaces, type aliases, and enums are addressable
+non-callable context nodes. Signature, body, and generic type references connect
+them to reviewed methods and other contracts. Relative import bindings take
+precedence; unique module-path suffixes and unimported names are candidate
+matches, not type checking. Unresolved imports do not borrow same-named types.
+Barrel re-exports, nested declarations, and class-field contracts may be absent.
+
+Context prioritizes calls adjacent to the hunk, with depth limited to four,
+at most eight arguments per call, and 120 characters per argument excerpt.
+Snapshot-bound changed definitions, callers, callees, dispatch endpoints, and
+type contracts carry complete source plus selected relation evidence. Bodies not
+already shown in the hunk take precedence over duplicate source. Unseen type
+declarations and dispatch endpoints precede ordinary caller chains, nearest
+first, with resulting-snapshot evidence ahead of prior-snapshot duplicates.
+Unresolved own-call expressions remain verbatim in a whole source body rather
+than repeating unknown-binding boilerplate. At most eight distinct definition
+nodes are kept per hunk, each carried whole, never shortened.
+
+Automatic response/caller evidence is narrower than the candidate call graph:
+it requires a supported lexical or typed-constructor binding. Relative modules
+and simple single-target `paths` aliases from snapshot-local, standalone JSON
+`tsconfig.json` files are supported. JSONC, inherited configurations, package or
+barrel resolution, and complex receivers remain unproven rather than borrowing
+an unrelated same-named function. `referenceProject: "path/to/tsconfig.json"`
+opts into the separate TypeScript diagnostic comparison; absent dependencies,
+unsupported project layouts, and exceeded bounds are reported as not checked.
+
+## Good to know
+
+- Tool results embed source code, including unchanged code, and stay in your
+  agent's session. Keep transcripts that contain them private.
+- Connected PR reviews need authenticated `gh`. Nothing else leaves your
+  machine: no model is called and no API key is needed.
+
+## Dev
+
+```bash
+npm run build   # tsc -> dist/
+npm run lint    # oxlint
+npm test        # vitest run
+```
+
+Run the built server directly with `node dist/review/mcp-cli.js` (it speaks MCP
+over stdio and prints nothing else to stdout).
+
+Releases and the npm publishing setup: [docs/npm-release.md](docs/npm-release.md).
+
+## Credits
+
+The call-flow engine is a fork of
+[calldiff](https://github.com/tanishqkancharla/calldiff) by Tanishq Kancharla
+(MIT, see LICENSE). diffninja uses its call graphs to show which flows each
+hunk touches.

package/dist/calltree.d.ts

@@ -0,0 +1,47 @@
+import { type FunctionIndex } from "./extract.js";
+import type { CallNode, FunctionInfo } from "./types.js";
+/** Normalize user-facing paths for entry matching (`\` → `/`, strip `./`). */
+export declare function normalizeEntryPath(entry: string): string;
+/** Unique source paths present in an index. */
+export declare function indexedFiles(index: FunctionIndex): string[];
+/**
+ * Resolve which indexed source files match a `--file` argument.
+ * Exact path wins; otherwise a unique suffix match (`routes.ts` → `src/routes.ts`).
+ */
+export declare function matchEntrypointFiles(entry: string, files: Iterable<string>): string[];
+/**
+ * Resolve a `--file` argument to a single indexed source path.
+ * Throws when missing or ambiguous.
+ */
+export declare function resolveEntrypointFile(entry: string, files: Iterable<string>): string;
+/** Exported definitions in a concrete source path. */
+export declare function exportsInFile(file: string, index: FunctionIndex): FunctionInfo[];
+/**
+ * Exported definitions for a `--file` argument against one index.
+ * Throws when the path is missing/ambiguous; returns [] when the file has no exports.
+ */
+export declare function resolveFileEntrypoints(entry: string, index: FunctionIndex): FunctionInfo[];
+/**
+ * Expand a function into a nested call tree by following known definitions.
+ */
+export declare function buildCallTree(entryKey: string, index: FunctionIndex, maxDepth: number): CallNode;
+/**
+ * Expand a specific definition. Used by `reach` when several functions share a
+ * bare key and first-wins indexing would otherwise hide all but one body.
+ */
+export declare function buildCallTreeFromInfo(info: FunctionInfo, index: FunctionIndex, maxDepth: number): CallNode;
+/**
+ * Every call site written in `info`'s own body as a one-level node: the callee's
+ * definition is attached, but nothing is expanded below it. Branch nesting and
+ * inline calls (arguments, callbacks, JSX) are flattened into the same list, so
+ * a consumer that walks definitions itself sees each site exactly once and can
+ * order them by source position.
+ */
+export declare function buildCallSitesFromInfo(info: FunctionInfo, index: FunctionIndex): CallNode[];
+export declare function resolveEntry(entry: string, index: FunctionIndex): string | null;
+/**
+ * Every definition that matches `entry` (including those shadowed in the
+ * bare-key map). Prefer exact bare-key hits; otherwise Class.method / `new X`.
+ * Order is stable by label, then file — independent of extract order.
+ */
+export declare function resolveAllEntries(entry: string, index: FunctionIndex): FunctionInfo[];

package/dist/calltree.js

@@ -0,0 +1,296 @@
+import { allFunctions, definitionsInFile, fileScopedKey, } from "./extract.js";
+import { callContextFromSyntax } from "./languages/call-syntax.js";
+import { pickLoc } from "./loc.js";
+/** Normalize user-facing paths for entry matching (`\` → `/`, strip `./`). */
+export function normalizeEntryPath(entry) {
+    return entry.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Unique source paths present in an index. */
+export function indexedFiles(index) {
+    return [...new Set(allFunctions(index).map((fn) => fn.file))].sort();
+}
+/**
+ * Resolve which indexed source files match a `--file` argument.
+ * Exact path wins; otherwise a unique suffix match (`routes.ts` → `src/routes.ts`).
+ */
+export function matchEntrypointFiles(entry, files) {
+    const normalized = normalizeEntryPath(entry);
+    const unique = [...new Set(files)];
+    const exact = unique.filter((file) => file === normalized);
+    if (exact.length > 0)
+        return exact.sort();
+    return unique
+        .filter((file) => file === normalized || file.endsWith(`/${normalized}`))
+        .sort();
+}
+/**
+ * Resolve a `--file` argument to a single indexed source path.
+ * Throws when missing or ambiguous.
+ */
+export function resolveEntrypointFile(entry, files) {
+    const matched = matchEntrypointFiles(entry, files);
+    if (matched.length === 0) {
+        throw new Error(`Entrypoint file not found: ${entry}`);
+    }
+    if (matched.length > 1) {
+        throw new Error(`Ambiguous entrypoint file: ${entry} matches ${matched.join(", ")}. Use a more specific path.`);
+    }
+    return matched[0];
+}
+/** Exported definitions in a concrete source path. */
+export function exportsInFile(file, index) {
+    return sortDefinitions(allFunctions(index).filter((fn) => fn.file === file && fn.exported));
+}
+/**
+ * Exported definitions for a `--file` argument against one index.
+ * Throws when the path is missing/ambiguous; returns [] when the file has no exports.
+ */
+export function resolveFileEntrypoints(entry, index) {
+    const file = resolveEntrypointFile(entry, indexedFiles(index));
+    return exportsInFile(file, index);
+}
+/** Is `fn` declared inside `owner`'s source span? */
+function declaredInside(fn, owner) {
+    if (!owner || fn.line == null || owner.line == null)
+        return false;
+    return (fn.line >= owner.line &&
+        (fn.endLine ?? fn.line) <= (owner.endLine ?? owner.line));
+}
+/**
+ * Resolve one call to a definition.
+ *
+ * A definition in the file the call was written in always wins: the bare-key
+ * map is global and first-wins, so without this a call resolves to whichever
+ * same-named function happened to be indexed first, grafting an unrelated body
+ * into the tree. See #19.
+ *
+ * Falls back to the global map, which is what callers across file boundaries
+ * (the common case) rely on.
+ */
+function resolveCall(key, index, callSite, owner) {
+    const file = callSite?.file ?? owner?.file;
+    if (file) {
+        const candidates = definitionsInFile(index, file, key);
+        if (candidates.length === 1)
+            return candidates[0];
+        if (candidates.length > 1) {
+            // One file declaring the name twice: a helper declared inside the calling
+            // function shadows that file's top-level definition.
+            const shadowing = candidates.find((fn) => fn.local && declaredInside(fn, owner));
+            return shadowing ?? candidates[0];
+        }
+    }
+    return index.get(key);
+}
+/** Never borrow a same-named definition's parameters for a lexical binding. */
+function callResolution(info, step) {
+    const declared = step?.syntax?.params;
+    return {
+        resolved: info !== undefined,
+        lexical: info !== undefined && step?.file === info.file && declared?.start !== undefined &&
+            declared.start === info.params?.start && declared.end === info.params?.end,
+    };
+}
+/**
+ * Context for one call node: the target expression and arguments as written,
+ * paired with the callee's declared parameters, plus what this expansion left
+ * unvisited.
+ */
+function callContextFor(step, info, resolution, omittedChildren, omittedInlineChildren) {
+    if (step?.type !== "call" || !step.syntax)
+        return undefined;
+    const context = callContextFromSyntax(step.syntax, info?.params, resolution);
+    // Counts are written only when something was actually left unexpanded.
+    if (omittedChildren)
+        context.omittedChildren = omittedChildren;
+    if (omittedInlineChildren)
+        context.omittedInlineChildren = omittedInlineChildren;
+    return context;
+}
+/** Attach an extracted context without an empty spread. */
+function withContext(node, context) {
+    if (context)
+        node.context = context;
+    return node;
+}
+function displayCallLabel(key, index, info) {
+    if (info)
+        return info.label;
+    const fromIndex = index.get(key);
+    if (fromIndex)
+        return fromIndex.label;
+    return key.includes("(") ? key : `${key}()`;
+}
+function expandSteps(steps, index, depth, maxDepth, visiting, 
+/** Definition these steps were read from, used to scope call resolution. */
+owner) {
+    return steps.map((step) => {
+        if (step.type === "branch") {
+            return {
+                key: step.key,
+                label: step.label,
+                kind: "branch",
+                ...pickLoc(step),
+                children: expandSteps(step.children, index, depth, maxDepth, visiting, owner),
+            };
+        }
+        return expandCall(step.key, index, depth, maxDepth, visiting, step.children, step, undefined, owner);
+    });
+}
+/** Definition location for a resolved call, or nothing when unresolved. */
+function definitionLoc(info) {
+    if (!info || info.line == null)
+        return undefined;
+    const loc = { file: info.file, line: info.line };
+    // Only a multi-line definition carries an end: a single line says so once.
+    if (info.endLine != null && info.endLine !== info.line)
+        loc.endLine = info.endLine;
+    return loc;
+}
+/** Attach the resolved definition to a node without an empty spread. */
+function withDefinition(node, definition) {
+    if (definition)
+        node.definition = definition;
+    return node;
+}
+function expandCall(key, index, depth, maxDepth, visiting, inlineChildren, callSite, 
+/** When set, expand this body even if another definition owns the bare key. */
+infoOverride, 
+/** Definition this call was read from, used to scope call resolution. */
+owner) {
+    const info = infoOverride ?? resolveCall(key, index, callSite, owner);
+    const label = displayCallLabel(key, index, info);
+    const definition = definitionLoc(info);
+    // Recursion is per definition, not per name: two same-named functions in
+    // different files calling each other is not a cycle.
+    const token = info ? fileScopedKey(info.file, info.key) : key;
+    // Root uses the definition start line; every other node uses the call-site in the parent.
+    const loc = depth === 0 && info?.line != null
+        ? pickLoc({ file: info.file, line: info.line })
+        : pickLoc(callSite);
+    // Body steps a further expansion would have produced; the caller can tell a
+    // depth cut from an unresolvable callee by their presence.
+    const bodySteps = info?.steps.length;
+    if (depth >= maxDepth) {
+        return withContext(withDefinition({ key, label, kind: "call", ...loc, children: [] }, definition), callContextFor(callSite, info, callResolution(info, callSite), bodySteps, inlineChildren?.length));
+    }
+    if (!info && !inlineChildren?.length) {
+        return withContext(withDefinition({ key, label, kind: "call", ...loc, children: [] }, definition), callContextFor(callSite, info, callResolution(info, callSite)));
+    }
+    if (info && visiting.has(token)) {
+        // Still expand call-site JSX children; they are not a re-entry into `key`'s body.
+        const callSiteChildren = inlineChildren?.length
+            ? expandSteps(inlineChildren, index, depth + 1, maxDepth, visiting, owner)
+            : [];
+        return withContext(withDefinition({
+            key,
+            label: `${label} ⇄`,
+            kind: "call",
+            ...loc,
+            children: callSiteChildren,
+        }, definition), callContextFor(callSite, info, callResolution(info, callSite), bodySteps, inlineChildren?.length));
+    }
+    if (info)
+        visiting.add(token);
+    const bodyChildren = info
+        ? expandSteps(info.steps, index, depth + 1, maxDepth, visiting, info)
+        : [];
+    const callSiteChildren = inlineChildren?.length
+        ? expandSteps(inlineChildren, index, depth + 1, maxDepth, visiting, owner)
+        : [];
+    if (info)
+        visiting.delete(token);
+    return withContext(withDefinition({
+        key,
+        label,
+        kind: "call",
+        ...loc,
+        children: [...bodyChildren, ...callSiteChildren],
+    }, definition), callContextFor(callSite, info, callResolution(info, callSite)));
+}
+/**
+ * Expand a function into a nested call tree by following known definitions.
+ */
+export function buildCallTree(entryKey, index, maxDepth) {
+    const resolved = resolveEntry(entryKey, index) ?? entryKey;
+    return expandCall(resolved, index, 0, maxDepth, new Set());
+}
+/**
+ * Expand a specific definition. Used by `reach` when several functions share a
+ * bare key and first-wins indexing would otherwise hide all but one body.
+ */
+export function buildCallTreeFromInfo(info, index, maxDepth) {
+    return expandCall(info.key, index, 0, maxDepth, new Set(), undefined, undefined, info);
+}
+/**
+ * Every call site written in `info`'s own body as a one-level node: the callee's
+ * definition is attached, but nothing is expanded below it. Branch nesting and
+ * inline calls (arguments, callbacks, JSX) are flattened into the same list, so
+ * a consumer that walks definitions itself sees each site exactly once and can
+ * order them by source position.
+ */
+export function buildCallSitesFromInfo(info, index) {
+    const sites = [];
+    const visiting = new Set([fileScopedKey(info.file, info.key)]);
+    const walk = (steps) => {
+        for (const step of steps) {
+            if (step.type === "branch") {
+                walk(step.children);
+                continue;
+            }
+            sites.push(expandCall(step.key, index, 1, 1, visiting, undefined, step, undefined, info));
+            // Inline calls belong to the same body; emit them as sites too.
+            if (step.children?.length)
+                walk(step.children);
+        }
+    };
+    walk(info.steps);
+    return sites;
+}
+export function resolveEntry(entry, index) {
+    if (index.has(entry))
+        return entry;
+    const stripped = entry.replace(/\(\)$/, "");
+    if (index.has(stripped))
+        return stripped;
+    const matches = [...index.keys()].filter((key) => key === entry ||
+        key.endsWith(`.${entry}`) ||
+        key === `new ${entry}`);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        const exported = matches.filter((key) => index.get(key)?.exported);
+        if (exported.length === 1)
+            return exported[0];
+        return matches.sort()[0];
+    }
+    return null;
+}
+function entryNameMatches(key, entry) {
+    return (key === entry ||
+        key.endsWith(`.${entry}`) ||
+        key === `new ${entry}`);
+}
+function sortDefinitions(fns) {
+    return [...fns].sort((a, b) => {
+        if (a.label !== b.label)
+            return a.label < b.label ? -1 : 1;
+        if (a.file !== b.file)
+            return a.file < b.file ? -1 : 1;
+        return (a.line ?? 0) - (b.line ?? 0);
+    });
+}
+/**
+ * Every definition that matches `entry` (including those shadowed in the
+ * bare-key map). Prefer exact bare-key hits; otherwise Class.method / `new X`.
+ * Order is stable by label, then file — independent of extract order.
+ */
+export function resolveAllEntries(entry, index) {
+    const stripped = entry.replace(/\(\)$/, "");
+    const all = allFunctions(index);
+    const exact = all.filter((fn) => fn.key === entry || fn.key === stripped);
+    if (exact.length > 0)
+        return sortDefinitions(exact);
+    const matches = all.filter((fn) => entryNameMatches(fn.key, entry) || entryNameMatches(fn.key, stripped));
+    return sortDefinitions(matches);
+}