@ttsc/graph 0.18.3 → 0.19.0

package/src/model/TtscGraphMemory.ts

@@ -1,6 +1,8 @@
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
+import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { ITtscGraphSpan } from "../structures/ITtscGraphSpan";
 import { TtscGraphEdgeKind } from "../structures/TtscGraphEdgeKind";
 
 /**
@@ -122,6 +124,24 @@ function fileNodeId(file: string): string {
   return file;
 }
 
+/**
+ * A wire span with its file put back: the one the builder left out because the
+ * reader has it, or the one it kept because it could not be derived (an
+ * implementation in another file).
+ */
+function spanIn(span: ITtscGraphSpan, file: string): ITtscGraphEvidence {
+  return { ...span, file: span.file ?? file };
+}
+
+/**
+ * The source file a node id names. An id is `path#Qualified.Name:kind`, and a
+ * file node's id is the path itself.
+ */
+function fileOfNodeId(id: string): string {
+  const hash = id.indexOf("#");
+  return hash === -1 ? id : id.slice(0, hash);
+}
+
 function basename(file: string): string {
   const slash = file.lastIndexOf("/");
   return slash >= 0 ? file.slice(slash + 1) : file;
@@ -136,9 +156,49 @@ function synthesize(dump: ITtscGraphDump): {
   nodes: ITtscGraphNode[];
   edges: ITtscGraphEdge[];
 } {
-  // Clone nodes so property refinement does not mutate the caller's dump.
-  const nodes: ITtscGraphNode[] = dump.nodes.map((n) => ({ ...n }));
-  const edges: ITtscGraphEdge[] = dump.edges.slice();
+  // A module node is the dump's name for a source file's export surface, and a
+  // file node is this layer's name for the same file. Fold the two: the module
+  // keeps its file present here even when the file declares nothing (a barrel),
+  // and its `exports` edges are re-anchored on the file id every other tool
+  // already traverses. What the module carried, the file now carries.
+  const moduleFiles = new Set(
+    dump.nodes.filter((n) => n.kind === "module").map((n) => n.file),
+  );
+  const moduleIds = new Map(
+    dump.nodes.filter((n) => n.kind === "module").map((n) => [n.id, n.file]),
+  );
+  // Clone nodes so property refinement does not mutate the caller's dump, and
+  // put back the file the builder left out of every span: a node's span is in
+  // the node's file, an edge's span is in the file its `from` id names. The
+  // builder omits both because they are exactly reconstructible and they are not
+  // small — the two copies are 17% of the document, 55 MB of VS Code's 323 MB,
+  // paid again in the encode, the pipe, the parse and the validation. Nothing
+  // downstream of this line sees a span without its file.
+  const nodes: ITtscGraphNode[] = dump.nodes
+    .filter((n) => n.kind !== "module")
+    .map((n) => {
+      const { evidence, implementation, ...rest } = n;
+      return {
+        ...rest,
+        ...(evidence !== undefined
+          ? { evidence: spanIn(evidence, n.file) }
+          : {}),
+        ...(implementation !== undefined
+          ? { implementation: spanIn(implementation, n.file) }
+          : {}),
+      };
+    });
+  const edges: ITtscGraphEdge[] = dump.edges.map((edge) => {
+    const { evidence, ...rest } = edge;
+    const from = moduleIds.get(edge.from);
+    return {
+      ...rest,
+      ...(from !== undefined ? { from: fileNodeId(from) } : {}),
+      ...(evidence !== undefined
+        ? { evidence: spanIn(evidence, fileOfNodeId(edge.from)) }
+        : {}),
+    };
+  });
 
   // Index workspace nodes by (file, within-file key) so ownership can resolve a
   // member to its declaring class/namespace.
@@ -161,23 +221,34 @@ function synthesize(dump: ITtscGraphDump): {
     }
   }
 
-  // One file container node per distinct workspace source file.
+  // One file container node per distinct workspace source file, plus every file
+  // the dump saw an export surface on — a barrel declares nothing, so its only
+  // trace in the dump is its module node, and it is exactly the file a consumer
+  // imports the package from.
   const fileNodes = new Map<string, ITtscGraphNode>();
+  const addFileNode = (file: string): void => {
+    if (file === "" || fileNodes.has(file)) return;
+    fileNodes.set(file, {
+      id: fileNodeId(file),
+      kind: "file",
+      name: basename(file),
+      file,
+      external: false,
+    });
+  };
   for (const node of nodes) {
-    if (node.external || node.file === "") continue;
-    if (!fileNodes.has(node.file)) {
-      fileNodes.set(node.file, {
-        id: fileNodeId(node.file),
-        kind: "file",
-        name: basename(node.file),
-        file: node.file,
-        external: false,
-      });
-    }
+    if (node.external) continue;
+    addFileNode(node.file);
   }
+  for (const file of moduleFiles) addFileNode(file);
 
   // Ownership: a member is contained by its owner; a top-level declaration by
-  // its file. Exports: a file exports each of its public nodes.
+  // its file. Exports are not synthesized here: the dump's `exports` edges come
+  // from the checker's export table, which follows re-exports and barrels, so
+  // they say which module puts a symbol on the wire. Deriving them from the
+  // `exported` flag instead would say only that the declaring file made it
+  // public, which is the fact that cannot tell a package's front door from its
+  // legacy subpath.
   const structural: ITtscGraphEdge[] = [];
   const membersByOwner = new Map<string, ITtscGraphNode[]>();
   for (const node of nodes) {
@@ -190,13 +261,6 @@ function synthesize(dump: ITtscGraphDump): {
       to: node.id,
       kind: "contains",
     });
-    if (node.exported) {
-      structural.push({
-        from: fileNodeId(node.file),
-        to: node.id,
-        kind: "exports" satisfies TtscGraphEdgeKind,
-      });
-    }
   }
 
   const synthesized = [...edges, ...structural];

package/src/model/TtscGraphSession.ts

@@ -0,0 +1,204 @@
+import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import readline from "node:readline";
+import typia from "typia";
+
+import { ensureExecutable } from "../nativeExecutable";
+import { resolveGraphBinary } from "../resolveGraphBinary";
+import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { TtscGraphMemory } from "./TtscGraphMemory";
+
+interface SessionResponse {
+  id: number;
+  changed: boolean;
+  mode?: "initial" | "unchanged" | "incremental" | "rebuild" | "reload";
+  dump?: unknown;
+  error?: string;
+}
+
+interface Pending {
+  resolve: (response: SessionResponse) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Resident bridge to `ttscgraph serve`.
+ *
+ * Every graph request first asks the native session for the current disk
+ * snapshot. Unchanged requests reuse the existing {@link TtscGraphMemory}; an
+ * edited source reuses tsgo's resident Program through `driver.Session`, while
+ * config and root-file-set changes force a safe full reload.
+ */
+export class TtscGraphSession {
+  private readonly cwd: string;
+  private readonly tsconfig: string;
+  private readonly binary: string;
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private stderr = "";
+  private nextId = 0;
+  private readonly pending = new Map<number, Pending>();
+  private queue: Promise<void> = Promise.resolve();
+  private current: TtscGraphMemory | undefined;
+  private closed = false;
+
+  public constructor(options: {
+    cwd: string;
+    tsconfig: string;
+    binary?: string;
+  }) {
+    // Resolve the platform binary from the project this session serves, so the
+    // MCP server started from an unrelated directory still finds the target's
+    // installed `ttsc`.
+    const binary =
+      options.binary ?? resolveGraphBinary(process.env, options.cwd);
+    if (binary === null) {
+      throw new Error(
+        "@ttsc/graph: could not resolve the ttscgraph binary. " +
+          "Install `ttsc` so its platform package is present, " +
+          "or set TTSC_GRAPH_BINARY to an absolute path.",
+      );
+    }
+    ensureExecutable(binary);
+    this.cwd = options.cwd;
+    this.tsconfig = options.tsconfig;
+    this.binary = binary;
+  }
+
+  /** Return a graph for the current disk snapshot, serialized per tool call. */
+  public graph(): Promise<TtscGraphMemory> {
+    let resolve!: (graph: TtscGraphMemory) => void;
+    let reject!: (error: Error) => void;
+    const result = new Promise<TtscGraphMemory>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.queue = this.queue
+      .catch(() => undefined)
+      .then(async () => {
+        try {
+          resolve(await this.refresh());
+        } catch (error) {
+          reject(asError(error));
+        }
+      });
+    return result;
+  }
+
+  /** Close the native session. Safe to call more than once. */
+  public close(): void {
+    this.closed = true;
+    const child = this.child;
+    this.child = undefined;
+    if (child !== undefined && !child.killed) child.stdin.end();
+    this.failPending(new Error("@ttsc/graph: native session closed"));
+  }
+
+  private async refresh(): Promise<TtscGraphMemory> {
+    const response = await this.request();
+    if (response.error !== undefined) {
+      throw new Error(`@ttsc/graph: ${response.error}`);
+    }
+    if (response.changed) {
+      if (response.dump === undefined) {
+        throw new Error(
+          `@ttsc/graph: native ${response.mode ?? "changed"} response omitted its dump`,
+        );
+      }
+      const dump = typia.assert<ITtscGraphDump>(response.dump);
+      this.current = TtscGraphMemory.from(dump);
+    }
+    if (this.current === undefined) {
+      throw new Error(
+        "@ttsc/graph: native session returned no initial graph snapshot",
+      );
+    }
+    return this.current;
+  }
+
+  private request(): Promise<SessionResponse> {
+    const child = this.ensureChild();
+    const id = ++this.nextId;
+    return new Promise<SessionResponse>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      child.stdin.write(`${JSON.stringify({ id })}\n`, (error) => {
+        if (error === null || error === undefined) return;
+        this.pending.delete(id);
+        reject(
+          new Error(
+            `@ttsc/graph: could not request native snapshot: ${error.message}`,
+          ),
+        );
+      });
+    });
+  }
+
+  private ensureChild(): ChildProcessWithoutNullStreams {
+    if (this.closed) {
+      // A request queued behind the close must not respawn the native
+      // process; an orphaned resident compiler would outlive the MCP server.
+      throw new Error("@ttsc/graph: native session is closed");
+    }
+    if (this.child !== undefined && this.child.exitCode === null) {
+      return this.child;
+    }
+    this.stderr = "";
+    const child = spawn(
+      this.binary,
+      ["serve", "--cwd", this.cwd, "--tsconfig", this.tsconfig],
+      { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    this.child = child;
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      this.stderr = (this.stderr + chunk).slice(-64 * 1024);
+    });
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on("line", (line) => this.onLine(line));
+    child.on("error", (error) => this.failChild(child, error));
+    child.on("exit", (code, signal) => {
+      if (this.child !== child) return;
+      this.child = undefined;
+      this.failPending(
+        new Error(
+          `@ttsc/graph: native session exited (code=${String(code)}, signal=${String(signal)})${
+            this.stderr.trim() === "" ? "" : `: ${this.stderr.trim()}`
+          }`,
+        ),
+      );
+    });
+    return child;
+  }
+
+  private onLine(line: string): void {
+    let response: SessionResponse;
+    try {
+      response = JSON.parse(line) as SessionResponse;
+    } catch (error) {
+      this.failPending(
+        new Error(
+          `@ttsc/graph: native session returned invalid JSON: ${asError(error).message}`,
+        ),
+      );
+      return;
+    }
+    const pending = this.pending.get(response.id);
+    if (pending === undefined) return;
+    this.pending.delete(response.id);
+    pending.resolve(response);
+  }
+
+  private failChild(child: ChildProcessWithoutNullStreams, error: Error): void {
+    if (this.child === child) this.child = undefined;
+    this.failPending(
+      new Error(`@ttsc/graph: native session failed: ${error.message}`),
+    );
+  }
+
+  private failPending(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/model/loadGraph.ts

@@ -13,9 +13,9 @@ const MAX_DUMP_BYTES = 1024 * 1024 * 1024;
 
 /**
  * Build the resident {@link TtscGraphMemory} for a project by running `ttscgraph
- * dump` once and loading its JSON. This is the cold path behind the MCP tool
- * calls: one type-check in Go produces the checker-resolved fact graph, then
- * every later tool call is answered from the in-memory model.
+ * dump` once and loading its JSON. This is the one-shot path for direct callers
+ * and the viewer. The MCP server uses `TtscGraphSession` instead so source
+ * edits refresh a resident compiler session.
  *
  * Throws when the binary cannot be resolved, the dump command fails, or its
  * output is not a readable graph — the server surfaces the failure rather than
@@ -37,7 +37,9 @@ export function loadGraph(
 ): TtscGraphMemory {
   const cwd = options.cwd ?? process.cwd();
   const tsconfig = options.tsconfig ?? "tsconfig.json";
-  const binary = options.binary ?? resolveGraphBinary();
+  // Resolve the platform binary from the selected project cwd, not the caller's
+  // process directory, so a one-shot load names its own installation.
+  const binary = options.binary ?? resolveGraphBinary(process.env, cwd);
   if (binary === null) {
     throw new Error(
       "@ttsc/graph: could not resolve the ttscgraph binary. " +

package/src/resolveGraphBinary.ts

@@ -15,8 +15,10 @@ import path from "node:path";
  * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttscgraph[.exe]`.
  *    That package carries `ttsc`, `ttscserver`, and `ttscgraph` together and is
  *    an `optionalDependency` of `ttsc`, so it is resolved from `ttsc`'s
- *    location — found from `process.cwd()` (the project where the agent ran the
- *    server).
+ *    location — found from `cwd`, the project the caller selected (via `--cwd`
+ *    or an API `cwd` option), defaulting to `process.cwd()` when no project was
+ *    named. A launcher started from an unrelated directory still resolves the
+ *    `ttsc` installed under the target project it was asked to graph.
  */
 export function resolveGraphBinary(
   env: NodeJS.ProcessEnv = process.env,
@@ -27,8 +29,10 @@ export function resolveGraphBinary(
   }
   const exe = process.platform === "win32" ? "ttscgraph.exe" : "ttscgraph";
   try {
+    // Anchor package lookup at the absolute project root so a relative `--cwd`
+    // resolves the same way the native process interprets it.
     const ttscPackageJson = require.resolve("ttsc/package.json", {
-      paths: [cwd],
+      paths: [path.resolve(cwd)],
     });
     const fromTtsc = createRequire(ttscPackageJson);
     return fromTtsc.resolve(

package/src/server/createServer.ts

@@ -1,31 +1,38 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpServer } from "@typia/mcp";
-import typia, { type ILlmController } from "typia";
+import typia from "typia";
 
 import { TtscGraphApplication, TtscGraphSource } from "../TtscGraphApplication";
 import { ITtscGraphApplication } from "../structures/ITtscGraphApplication";
 
 /**
- * Build the MCP server for a graph. `typia.llm.application` reflects
- * {@link ITtscGraphApplication} into the tool schema and validator (no
- * hand-written schema), and `createMcpServer` from `@typia/mcp` handles the
- * list/call registration, argument validation, and structured output.
+ * Build the MCP server for a graph.
  *
- * We assemble the `ILlmController` (`{ protocol, name, application, execute }`)
- * directly rather than via `typia.llm.controller` so the server is named
- * "ttsc-graph" on our terms, not coupled to a reflected class name. Handshake
- * instructions come from the class JSDoc; the single tool is named from its
- * method, `inspect_typescript_graph`.
+ * `typia.llm.controller` reflects {@link ITtscGraphApplication} into the tool's
+ * input and output schemas and its argument validator, with no hand-written
+ * schema: the interface's JSDoc becomes the handshake instructions, the
+ * method's becomes the tool description, and every property's becomes the
+ * description of that field — including `audit`, whose JSDoc is how a caller
+ * learns what the server checked before it answered.
+ *
+ * The registration was hand-written here for a while, because a tool that
+ * declares an output schema must answer with `structuredContent` and the helper
+ * also serialized the same JSON into a text block: the payload crossed the wire
+ * twice, a client counted both copies against its tool-result cap, and a 30 KB
+ * tour arrived as 60 KB, blew the cap, and was spilled to a file the model then
+ * shelled out to read back. `@typia/mcp` 13.1.0 ships the structured result
+ * once (samchon/typia#2020), so the hand-written server had nothing left to fix
+ * and the library owns the registration again.
  */
 export function createServer(
   graph: TtscGraphSource,
   version: string,
 ): McpServer {
-  const controller: ILlmController<ITtscGraphApplication> = {
-    protocol: "class",
-    name: "ttsc-graph",
-    application: typia.llm.application<ITtscGraphApplication>(),
-    execute: new TtscGraphApplication(graph),
-  };
-  return createMcpServer(controller, version);
+  void version;
+  return createMcpServer(
+    typia.llm.controller<ITtscGraphApplication>(
+      "ttsc-graph",
+      new TtscGraphApplication(graph),
+    ),
+  );
 }

package/src/server/exportSurface.ts

@@ -0,0 +1,40 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+
+/**
+ * How public a symbol is, counted from the graph and nothing else.
+ *
+ * A module's `exports` edges are the checker's export table, resolved through
+ * every re-export and barrel it passes. So a symbol carries one edge per module
+ * that puts it on the wire, and that count is the project's own answer to how
+ * far forward the symbol stands: an internal helper is exported by the file
+ * that declares it or by nothing at all, while the name a consumer imports from
+ * the package has been re-exported up a chain of barrels and carries an edge
+ * from each one.
+ *
+ * On zod the count is the whole difference between the current API and the
+ * previous major it still ships: `parse` and `safeParse` in v4's classic
+ * surface carry five, v3's `ZodString` carries three, and v3's
+ * `ZodType.safeParse` — a class method, which no export table ever names —
+ * carries none. A ranker that knew only the `exported` flag saw all of these as
+ * equally public, picked the one whose name matched the question best, and
+ * opened zod's tour on the legacy implementation.
+ *
+ * The count is a fact the compiler resolved. It reads no package.json, guesses
+ * from no filename, and holds for a project that has neither.
+ */
+export function exportFanIn(graph: TtscGraphMemory, id: string): number {
+  let count = 0;
+  for (const edge of graph.incoming(id)) if (edge.kind === "exports") count++;
+  return count;
+}
+
+/** True when the dump carries an export surface at all. */
+export function hasExportSurface(graph: TtscGraphMemory): boolean {
+  const known = cache.get(graph);
+  if (known !== undefined) return known;
+  const found = graph.edges.some((edge) => edge.kind === "exports");
+  cache.set(graph, found);
+  return found;
+}
+
+const cache = new WeakMap<TtscGraphMemory, boolean>();

package/src/server/resolveHandle.ts

@@ -1,12 +1,39 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { exportFanIn } from "./exportSurface";
+import { isSupportPath } from "./pathPolicy";
 
 export interface IResolvedGraphHandle {
   node?: ITtscGraphNode;
   candidates?: ITtscGraphNode[];
 }
 
-/** Resolve a tool handle as an id, exact symbol name, or dotted suffix. */
+/**
+ * Resolve a tool handle as an id, an exact symbol name, a dotted suffix, or a
+ * file-qualified name.
+ *
+ * A model writes handles from memory of an earlier result, and it writes them
+ * the way the result read: a symbol with the file it came from. Three forms all
+ * mean one node and all used to miss.
+ *
+ * - A `file#symbol` id whose file is one refactor stale (`effect.ts#track` for
+ *   what now lives in `dep.ts`). The graph knows the symbol, so it answers
+ *   rather than sending the caller back through a lookup.
+ * - `renderer.render` — the file's stem and the symbol it declares. It is not a
+ *   qualified name, so a suffix match on `.render` finds nothing and the caller
+ *   gets an empty result for a symbol the graph holds. Vue's tour spent a trace
+ *   call and four file reads on exactly this.
+ * - A name the project declares more than once, which is not a name the project
+ *   does not declare. The candidates come back ranked by what the package
+ *   publishes, so the one a caller means is the one it reads first.
+ * - `schema.parse` — a call written the way it is written in a program, on a
+ *   value rather than on the type that declares it. There is no `schema` in the
+ *   graph, so every exact form misses, and the handle resolves to nothing for a
+ *   member the graph holds under `ZodType.parse`. It is how people name a
+ *   method (`db.query`, `app.listen`, `repo.save`), so the member is what it
+ *   means, and the candidates come back ranked when several classes declare
+ *   it.
+ */
 export function resolveGraphHandle(
   graph: TtscGraphMemory,
   handle: string,
@@ -15,12 +42,60 @@ export function resolveGraphHandle(
   const byId = graph.node(handle);
   if (byId !== undefined) return { node: byId };
 
-  const exact = graph.symbols(handle);
+  const byName = resolveGraphName(graph, handle, candidateLimit);
+  if (byName.node !== undefined || byName.candidates !== undefined)
+    return rank(graph, byName, candidateLimit);
+
+  const byFile = resolveFileQualified(graph, handle, candidateLimit);
+  if (byFile.node !== undefined || byFile.candidates !== undefined)
+    return rank(graph, byFile, candidateLimit);
+
+  const symbol = symbolPartOf(handle) ?? memberPartOf(handle);
+  if (symbol !== undefined)
+    return rank(
+      graph,
+      resolveGraphName(graph, symbol, candidateLimit),
+      candidateLimit,
+    );
+  return {};
+}
+
+/**
+ * The member a dotted handle names when its receiver is a value: the last
+ * segment of `schema.parse`, of `this.store.commit`, of `db.query`.
+ *
+ * It is the last thing tried, after the whole handle has failed as an id, as a
+ * qualified name, as a `.suffix`, and as a file-qualified name — so a receiver
+ * that _is_ a type or a file never reaches here.
+ */
+function memberPartOf(handle: string): string | undefined {
+  const dot = handle.lastIndexOf(".");
+  if (dot <= 0) return undefined;
+  const member = handle.slice(dot + 1);
+  return member.length > 0 ? member : undefined;
+}
+
+/** The symbol an id-shaped handle names: `dir/file.ts#Class.method:kind`. */
+function symbolPartOf(handle: string): string | undefined {
+  const hash = handle.lastIndexOf("#");
+  if (hash < 0) return undefined;
+  const symbol = handle.slice(hash + 1);
+  const kind = symbol.lastIndexOf(":");
+  const name = kind < 0 ? symbol : symbol.slice(0, kind);
+  return name.length > 0 ? name : undefined;
+}
+
+function resolveGraphName(
+  graph: TtscGraphMemory,
+  name: string,
+  candidateLimit: number,
+): IResolvedGraphHandle {
+  const exact = graph.symbols(name);
   if (exact.length === 1) return { node: exact[0] };
   if (exact.length > 1) return { candidates: exact.slice(0, candidateLimit) };
 
-  if (handle.includes(".")) {
-    const suffix = `.${handle}`;
+  if (name.includes(".")) {
+    const suffix = `.${name}`;
     const suffixMatches = graph.nodes.filter(
       (node) =>
         node.kind !== "file" && node.qualifiedName?.endsWith(suffix) === true,
@@ -32,3 +107,65 @@ export function resolveGraphHandle(
   }
   return {};
 }
+
+/**
+ * A `file.symbol` handle: the stem of the file a result cited, then the symbol
+ * it declared there (`renderer.render`, `parse.safeParse`). It is how a model
+ * disambiguates a common name from what the graph just showed it, and it names
+ * exactly one node whenever that file declares the symbol.
+ */
+function resolveFileQualified(
+  graph: TtscGraphMemory,
+  handle: string,
+  candidateLimit: number,
+): IResolvedGraphHandle {
+  const dot = handle.indexOf(".");
+  if (dot <= 0) return {};
+  const stem = handle.slice(0, dot).toLowerCase();
+  const name = handle.slice(dot + 1);
+  if (name === "") return {};
+  const matches = graph
+    .symbols(name)
+    .filter((node) => fileStem(node.file) === stem);
+  if (matches.length === 1) return { node: matches[0] };
+  if (matches.length > 1)
+    return { candidates: matches.slice(0, candidateLimit) };
+  return {};
+}
+
+/** `packages/core/src/renderer.ts` -> `renderer`. */
+function fileStem(file: string): string {
+  const base = file.slice(file.lastIndexOf("/") + 1);
+  return base.replace(/\.[cm]?[tj]sx?$/, "").toLowerCase();
+}
+
+/**
+ * Order candidates by how likely a caller means them: what the package
+ * publishes first, then how much of the codebase leans on the node, with test
+ * and fixture declarations last. An unranked list hands back whichever
+ * declaration the graph happened to visit first — Vue's `render` came back as a
+ * template pre-processor's method — and a caller that trusts the order traces
+ * the wrong one.
+ */
+function rank(
+  graph: TtscGraphMemory,
+  resolved: IResolvedGraphHandle,
+  candidateLimit: number,
+): IResolvedGraphHandle {
+  if (resolved.candidates === undefined) return resolved;
+  const ranked = [...resolved.candidates]
+    .sort((a, b) => candidateScore(graph, b) - candidateScore(graph, a))
+    .slice(0, candidateLimit);
+  return { candidates: ranked };
+}
+
+function candidateScore(graph: TtscGraphMemory, node: ITtscGraphNode): number {
+  let score = Math.min(48, Math.log2(1 + exportFanIn(graph, node.id)) * 20);
+  if (node.exported) score += 12;
+  if (node.external) score -= 60;
+  if (isSupportPath(node.file)) score -= 30;
+  const degree =
+    graph.outgoing(node.id).length + graph.incoming(node.id).length;
+  score += Math.min(24, Math.log2(1 + degree) * 6);
+  return score;
+}