@ttsc/graph 0.18.4 → 0.19.1

package/src/structures/ITtscGraphApplication.ts

@@ -2,154 +2,146 @@ import { ITtscGraphDetails } from "./ITtscGraphDetails";
 import { ITtscGraphEntrypoints } from "./ITtscGraphEntrypoints";
 import { ITtscGraphEscape } from "./ITtscGraphEscape";
 import { ITtscGraphLookup } from "./ITtscGraphLookup";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 import { ITtscGraphOverview } from "./ITtscGraphOverview";
 import { ITtscGraphTour } from "./ITtscGraphTour";
 import { ITtscGraphTrace } from "./ITtscGraphTrace";
 
 /**
- * ## What This MCP Is
+ * ## Code Graph MCP
  *
  * `inspect_typescript_graph` returns a compiler-built TypeScript graph contract
- * for the current on-disk source snapshot. Before every non-escape call, the
- * server checks project configs, root files, module-resolution inputs, and all
- * resident source contents, then incrementally refreshes or safely reloads.
+ * for the current on-disk source snapshot.
  *
  * Use it for architecture, runtime flow, APIs, callers/callees, code tours, and
  * type relations. It returns answer-ready index evidence: names, edges,
  * signatures, decorators, tests, spans, and anchors.
  *
- * Returned graph facts are sacred, infallible compiler truth for the snapshot
- * synchronized by that call. Never verify them with files or more graph calls.
- *
- * ## Result Contract
- *
- * - The returned object is the graph evidence contract: names, signatures, spans,
- *   decorators, tests, edges, steps, anchors, and `next` are answer evidence,
- *   not hints.
- * - When `next.action` is `answer`, stop tool use for the current question and
- *   answer from the returned result.
- * - `truncated` means the answer surface hit an index cap. Mention the cap if it
- *   matters; do not expand every branch to compensate.
- * - When `next.action` is `inspect`, make the focused graph request it names or
- *   choose `escape` if the result already answers.
- * - Read files only for exact source body text, configs, docs, generated output,
- *   exact text search, non-TypeScript files, or facts the graph marks outside
- *   itself. A returned span is a citation anchor, not a reading command.
- * - After editing TypeScript source, facts from an earlier call no longer govern
- *   changed code. Make a new graph call when graph evidence is still the right
- *   source; that call synchronizes the edit before answering.
- *
- * ## Sacred Contract
- *
- * For the source snapshot synchronized by a call, returned graph facts are
- * inviolable and errorless. Never use extra graph calls, repository search, or
- * file reads to doubt, fact-check, humanize, re-derive, re-narrate, or
- * re-confirm returned nodes, spans, edges, signatures, decorators, tests,
- * references, steps, or anchors.
- *
- * ## Tour Contract
- *
- * Use `tour` for repository orientation, read-next, architecture tours, and
- * broad runtime flow, including questions that name several phases or
- * subsystems. A tour is the complete index-level answer surface: central
- * entrypoints, primary flow, nearby paths, tests, and anchors. Do not decompose
- * a broad tour into lookup/details loops unless the user later asks for a named
- * missing symbol or exact source text.
- *
- * ## Use Contract
- *
- * 1. Ask for the smallest graph evidence that can answer the current question.
- * 2. Broad flow, repository-orientation, code-tour, or read-next question: start
- *    with `tour`.
- * 3. Concrete named symbol: use `lookup`, then `details` only if needed.
- * 4. Known endpoint pair or one selected handle: use one `trace`.
- * 5. Unknown narrow orientation: use `entrypoints` once.
- * 6. Selected symbol shape: use `details` for one to three handles.
- * 7. Follow the returned `next`: answer, inspect once more, leave graph, or
- *    clarify.
- * 8. Use `escape` when another graph call would repeat evidence or the remaining
- *    evidence is outside the TypeScript graph.
- *
- * Most TypeScript structure answers need one or two graph calls.
- *
- * ## Request Fields
- *
- * Fill the visible checklist, then exactly one request.
- *
- * - `question`: restate the code question being considered.
- * - `draft`: initial request type and why it seems smallest.
- * - `review`: correct a wrong, broad, stale, or duplicate draft. If graph facts
- *   already answer, if prior `next.action` was `answer`, or if the next
- *   evidence is outside the indexed TypeScript graph, say so here and make
- *   `request.type` be `escape`. If a broad flow draft is not `tour`, correct it
- *   here.
- * - `request`: final request after review.
- *
- * ## How to answer from graph evidence
- *
- * - Use returned node names, signatures, edges, references, evidence, and
- *   `sourceSpan` ranges directly.
- * - Explain the central path first, then mention important branches.
- * - For tests, impact, or reading lists, returned nodes and ranges are the answer
- *   evidence, not search keywords.
- * - A returned range is a sacred citation anchor, not permission to open the
- *   file.
+ * Every returned fact — each name, edge, signature, and span — is
+ * compiler-resolved and verified for the snapshot that call synchronized, so
+ * trust it without re-checking against files. Where an operation ranks a
+ * shortlist against your question (`lookup`, `entrypoints`, `tour`), the facts
+ * stay verified but the selection is heuristic: judge whether its coverage
+ * answers you, and a follow-up request or a read of a cited span is fair when
+ * it does not.
+ *
+ * ## Requests
+ *
+ * A request is a union: pick the single type below that best fits the question,
+ * and submit exactly that one.
+ *
+ * - `tour`: architecture, runtime flow, orientation, or a code tour. One call is
+ *   the whole answer; do not split it. Name the machinery you expect it to be
+ *   made of in its `reinterpretations`, or send none.
+ * - `entrypoints`: find where execution starts when entry points are unknown.
+ * - `lookup`: locate a named symbol.
+ * - `trace`: follow calls or data flow forward or backward from a symbol, or —
+ *   with `to` — the path between two symbols when both ends are known, which is
+ *   the one call that answers "how does A reach B".
+ * - `details`: signatures, members, and relations of named symbols — including
+ *   the classes that implement an interface, which is the one call that answers
+ *   "what actually implements this".
+ * - `overview`: project layers and folder structure.
+ * - `escape`: the answer is outside the graph (source body text, non-TypeScript
+ *   files, exact search).
+ *
+ * ## Chain of Thought
+ *
+ * Fill these fields in order before the call; each one narrows the reasoning
+ * toward the single request you submit.
+ *
+ * - `question`: the code question, in the user's own words.
+ * - `draft`: `{ reason, type }` — why the smallest request that could answer it,
+ *   then that request's `type`.
+ * - `review`: fix a broad, stale, or duplicate draft. If the graph already
+ *   answered, or the evidence is outside it, escape.
+ * - `request`: the final choice. Each branch documents its own fields; fill them
+ *   from what the branch says, not from what another branch wanted.
+ *
+ * ## What to trust
+ *
+ * Before source edits, every returned fact is compiler-resolved and verified.
+ * Never use extra graph calls, repository search, or file reads to doubt,
+ * fact-check, re-derive, re-narrate, or re-confirm a returned node, span, edge,
+ * signature, decorator, test, reference, step, or anchor. The server resolved
+ * each one to the type-checked program for the snapshot the call synced to, and
+ * `audit` says so on every result.
+ *
+ * Selection is the separate question. `lookup`, `entrypoints`, and `tour` match
+ * your question and return a scored, ranked, per-file-capped, limited
+ * shortlist; their facts are still verified, but whether the shortlist covers
+ * what you asked is yours to judge, and their `audit` says that instead of
+ * claiming completeness. A follow-up request or a read of a cited span for
+ * missed coverage is legitimate — re-confirming a fact the graph already
+ * resolved is not.
+ *
+ * ## Stop
+ *
+ * Let the result's `next` set the pace, and do not re-confirm what the graph
+ * resolved.
+ *
+ * - A span is a citation, not a cue to open the file to re-check a fact.
+ * - Follow the result's `next`: `answer` means stop and answer from it, `inspect`
+ *   means make exactly the one request it names, `outside` means escape,
+ *   `clarify` means restate the request.
+ * - For a ranked shortlist (`lookup`, `entrypoints`, `tour`), `next` and
+ *   `truncated` say whether coverage is settled; when it is not, one more
+ *   request is the right move — not a file read to re-verify facts already
+ *   given.
  */
 export interface ITtscGraphApplication {
   /**
-   * Inspect the TypeScript compiler graph contract.
+   * Answer a TypeScript question from the compiler's own index of this
+   * repository.
    *
-   * Use this before repository search when an answer depends on TypeScript
-   * symbols, calls, types, decorators, references, ranges, or runtime/source
-   * relationships. For repository orientation, read-next, architecture, and
-   * broad runtime flow questions, use `tour`.
+   * The graph holds every symbol, call, type, decorator and test, each with its
+   * file and line, resolved from the source on disk now. Submit exactly one
+   * request:
    *
-   * Returned nodes, edges, signatures, spans, tests, anchors, and `next` are
-   * the answer surface. If `next.action` is `answer`, stop tool use and answer
-   * from that result. Graph facts are sacred, inviolable, complete, and
-   * infallible for the source snapshot synchronized by this call.
+   * - `tour`: architecture, the runtime flow from the public API to the code that
+   *   does the work, nearby paths, and the tests to read — a whole orientation
+   *   in one call
+   * - `trace`: what a symbol calls, what calls it, or the path from A to B
+   * - `details`: signatures, members, and what implements an interface
+   * - `lookup`: where a named symbol is declared
+   * - `entrypoints`: where execution starts, when the entry is unknown
+   * - `overview`: the project's layers and folder structure
+   *
+   * Every fact in a result is the checker's own resolution, audited before
+   * return, so no fact needs verifying; for the ranked operations (`lookup`,
+   * `entrypoints`, `tour`), judge whether the shortlist covers your question.
+   * Read a file for what the graph does not carry: a body, the text in a span.
    *
    * @param props Reasoning plus one graph request
    * @returns Matching `result` union member
    */
   inspect_typescript_graph(
     props: ITtscGraphApplication.IProps,
-  ): Promise<ITtscGraphApplication.IResult>;
+  ): Promise<ITtscGraphApplication.IOutput>;
 }
 
 export namespace ITtscGraphApplication {
   /** Draft, review, then submit exactly one graph request or escape. */
   export interface IProps {
     /**
-     * User's TypeScript code question.
+     * The code question, in the user's own words.
      *
-     * Restate the code question being considered. If the next evidence is a
-     * script, config, doc, generated output, exact text, non-TypeScript file,
-     * or source body text, choose `escape`.
+     * Cut a long message down to the sentences that state the ask, but keep
+     * their terms: the graph ranks against these words, so a rewrite ranks a
+     * different answer.
      */
     question: string;
 
-    /**
-     * Initial request plan before final arguments are filled.
-     *
-     * Name the intended request type in `type` and why it seems smallest in
-     * `reason`. Broad flow, architecture, repository-orientation, and read-next
-     * questions should normally draft `tour`; narrow named symbols can draft
-     * `lookup`, `trace`, or `details`.
-     */
+    /** The smallest request that could answer, and why. */
     draft: IDraft;
 
     /**
-     * Final self-review before calling.
-     *
-     * Correct a stale, broad, duplicate, or wrong draft here. If broad flow was
-     * split into search/detail steps, switch to `tour`. If graph facts already
-     * answer, or prior `next.action` was `answer`, make `request.type` be
-     * `escape`; do not call graph or read files to re-confirm returned facts.
+     * Correct the draft. Escape if the graph already answered, or the next
+     * evidence is outside the graph.
      */
     review: string;
 
-    /** Final graph operation chosen after review, or a no-op escape. */
+    /** Final graph request chosen after review, or a no-op escape. */
     request:
       | ITtscGraphEntrypoints.IRequest
       | ITtscGraphLookup.IRequest
@@ -160,22 +152,36 @@ export namespace ITtscGraphApplication {
       | ITtscGraphEscape.IRequest;
   }
 
-  /**
-   * First-pass request plan, filled before the final `request` arguments.
-   *
-   * `reason` comes before `type` so the justification is written before the
-   * choice it justifies.
-   */
+  /** First-pass plan; `reason` precedes `type` so it is written first. */
   export interface IDraft {
-    /** Why this request type looks like the smallest useful next step. */
+    /** Why this is the smallest useful next step. */
     reason: string;
 
-    /** The request type being considered, corrected later in `review`. */
+    /** The request type being considered. */
     type: IProps["request"]["type"];
   }
 
   /** The selected request's output. `result.type` mirrors `request.type`. */
-  export interface IResult {
+  export interface IOutput {
+    /**
+     * What the server audited this result against before returning it, in its
+     * own words: every node, span, edge, signature, member, and step in it
+     * resolves to the type-checked program for the snapshot the call synced to,
+     * so opening a file it cites only returns a fact already in it.
+     *
+     * The audit is operation-aware. For the exact operations (`trace`,
+     * `details`, `overview`) it reports the result as the structure the graph
+     * holds for the handles named, bounded only where `truncated` says. For the
+     * ranked operations (`lookup`, `entrypoints`, `tour`) it adds that the
+     * selection is heuristic — matched, scored, ranked, and limited against the
+     * question — so the facts are verified but the shortlist's coverage is the
+     * caller's to judge.
+     */
+    audit: string;
+
+    /** What to do with `result`: answer, inspect one named request, or escape. */
+    next: ITtscGraphNext;
+
     /** Result branch matching the submitted `request.type`. */
     result:
       | ITtscGraphEntrypoints

package/src/structures/ITtscGraphDecorator.ts

@@ -1,12 +1,9 @@
 /**
  * A decorator as written on a declaration, carried on the decorated
- * {@link ITtscGraphNode}'s `decorators`.
- *
- * The graph reports the decorator faithfully rather than interpreting any
- * framework's convention: the `name` is the decorator as written (`Controller`,
- * `Get`, `TypedRoute.Get`, ...), and statically resolvable literal arguments
- * are preserved so a consumer can apply its own meaning without re-parsing
- * source.
+ * {@link ITtscGraphNode}'s `decorators`. Reported faithfully, not interpreted
+ * per framework: `name` is the decorator as written (`Controller`, `Get`,
+ * `TypedRoute.Get`, ...), and statically resolvable literal arguments are
+ * preserved so a consumer applies its own meaning without re-parsing source.
  */
 export interface ITtscGraphDecorator {
   /**

package/src/structures/ITtscGraphDetails.ts

@@ -1,13 +1,10 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /**
- * The source-free facts for a few selected handles.
- *
- * This is not a file reader. It returns signatures, member outlines, direct
- * calls, direct types, implementation candidates, dependency summaries, and
- * sourceSpan citation anchors.
+ * Source-free facts for a few selected handles, not a file reader: signatures,
+ * member outlines, direct calls and types, implementation candidates,
+ * dependency summaries, and sourceSpan citation anchors.
  */
 export interface ITtscGraphDetails {
   /** Discriminator for selected symbol inspection. */
@@ -16,14 +13,19 @@ export interface ITtscGraphDetails {
   /** Selected node facts, in the same order as resolved handles when possible. */
   nodes: ITtscGraphDetails.INode[];
 
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
-
-  /** Handles that resolved to no node, or that were ambiguous. */
+  /** Handles the graph holds no node for. */
   unknown: string[];
+
+  /**
+   * Handles that name more than one node, with the nodes they name.
+   *
+   * A name the graph knows twice is not a name the graph does not know: two
+   * classes called `Workbench` are two facts, and answering "unknown" to a
+   * handle the checker resolved twice sends the caller to the files for what is
+   * already here. Re-call `details` with the `id` of the one the question
+   * means.
+   */
+  ambiguous?: ITtscGraphDetails.IAmbiguity[];
 }
 export namespace ITtscGraphDetails {
   /** Which selected handles to inspect, and how much of each to return. */
@@ -32,47 +34,37 @@ export namespace ITtscGraphDetails {
     type: "details";
 
     /**
-     * Node ids from another tool, or dotted symbol handles such as
-     * `OrderService.create`. Pass the few handles you need for source-free
-     * details. Prefer one to three handles. Use `trace` when you need a path
-     * instead of widening this call.
+     * Node ids or dotted symbol handles (`OrderService.create`). Prefer one to
+     * three; use `trace` for a path instead of widening this call.
      */
     handles: string[];
 
     /**
-     * Also list each node's direct dependencies and dependents (the symbols it
-     * uses and the symbols that use it). The list is capped; raise
-     * `neighborLimit` when the first slice is truncated and the missing
-     * relation is named. This remains a relationship summary, not a file body.
+     * Also list each node's direct dependencies and dependents (symbols it uses
+     * and symbols that use it), capped. A relationship summary, not a file
+     * body.
      *
      * @default false
      */
     neighbors?: boolean;
 
     /**
-     * Maximum dependencies and dependents to return per side when
-     * `neighbors:true`.
-     *
-     * Prefer the default. Values above a few neighbors are usually overfetch;
-     * call `trace` for flow instead.
+     * Maximum dependencies and dependents per side when `neighbors:true`. Above
+     * a few is usually overfetch; call `trace` for flow instead.
      *
      * @default 2
      */
     neighborLimit?: number;
 
     /**
-     * Maximum owned members to return for a container or object literal. Raise
-     * only when the first outline is truncated and the missing member is
-     * named.
+     * Maximum owned members for a container or object literal.
      *
      * @default 6
      */
     memberLimit?: number;
 
     /**
-     * Maximum direct execution and type references to return per group. Raise
-     * only when the first dependency slice is truncated and the missing
-     * dependency is named.
+     * Maximum direct execution and type references per group.
      *
      * @default 1
      */
@@ -80,14 +72,41 @@ export namespace ITtscGraphDetails {
 
     /**
      * Include dependency-boundary references from node_modules or bundled
-     * `.d.ts` libraries. Leave false for source-architecture answers; enable
-     * only when external type/API boundaries are the question.
+     * `.d.ts` libraries. Enable only when external type/API boundaries are the
+     * question.
      *
      * @default false
      */
     includeExternal?: boolean;
   }
 
+  /** One handle and the several nodes it names. */
+  export interface IAmbiguity {
+    /** The handle as submitted. */
+    handle: string;
+
+    /** Every node the handle names, each with the id to re-call `details` on. */
+    candidates: ICandidate[];
+  }
+
+  /** One node a handle could mean: enough to choose, not to answer from. */
+  export interface ICandidate {
+    /** Stable node id: submit this as the handle to select this one. */
+    id: string;
+
+    /** Qualified symbol name when available, otherwise the simple name. */
+    name: string;
+
+    /** Declaration kind (`class`, `method`, `function`, ...). */
+    kind: string;
+
+    /** Project-relative path of the file that declares this node. */
+    file: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+  }
+
   /** One inspected node: its declared shape and graph coordinates. */
   export interface INode {
     /** Stable node id for subsequent `details` or `trace` calls. */
@@ -108,6 +127,9 @@ export namespace ITtscGraphDetails {
     /** The declaration signature: its first line(s) up to the body. */
     signature?: string;
 
+    /** The first sentence of the doc comment above the declaration. */
+    doc?: string;
+
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
 
@@ -127,8 +149,8 @@ export namespace ITtscGraphDetails {
     literals?: string[];
 
     /**
-     * For a container or object-literal variable: the owned symbol or top-level
-     * property outline a consumer reaches for, without bodies.
+     * Owned symbol or top-level property outline a consumer reaches for on a
+     * container or object-literal variable, without bodies.
      */
     members?: IMember[];
 
@@ -181,17 +203,9 @@ export namespace ITtscGraphDetails {
     relation: string;
 
     /**
-     * Source span for the expression that produced this relationship. It is
-     * repository evidence for the edge, not a file-read instruction.
+     * Source span that produced the edge: citation evidence, not a file-read
+     * cue.
      */
     evidence?: ITtscGraphEvidence;
-
-    /**
-     * Stable access-path aliases derived from edge evidence. For example, an
-     * edge to `Owner.member` through `obj.slot.member` may expose
-     * `Owner.slot.member` so answers can preserve both the resolved symbol and
-     * the source access path.
-     */
-    aliases?: string[];
   }
 }

package/src/structures/ITtscGraphDump.ts

@@ -1,6 +1,6 @@
-import { ITtscGraphDiagnostic } from "./ITtscGraphDiagnostic";
 import { ITtscGraphEdge } from "./ITtscGraphEdge";
 import { ITtscGraphNode } from "./ITtscGraphNode";
+import { ITtscGraphSpan } from "./ITtscGraphSpan";
 
 /**
  * The whole-graph export `ttscgraph dump` writes and the MCP server loads — the
@@ -12,8 +12,8 @@ import { ITtscGraphNode } from "./ITtscGraphNode";
  * that warm model while project inputs stay unchanged; the bundled 3D viewer
  * reduces the same dump.
  *
- * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
- * edges, and diagnostics are project-relative.
+ * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes and
+ * edges are project-relative.
  */
 export interface ITtscGraphDump {
   /** Absolute path of the project root the graph was built for. */
@@ -23,14 +23,43 @@ export interface ITtscGraphDump {
   tsconfig: string;
 
   /** Every node the build recorded. */
-  nodes: ITtscGraphNode[];
+  nodes: ITtscGraphDump.INode[];
 
   /** Every edge the build resolved. */
-  edges: ITtscGraphEdge[];
+  edges: ITtscGraphDump.IEdge[];
+}
+
+export namespace ITtscGraphDump {
+  /**
+   * A node as the builder sends it: the graph node, minus the file paths inside
+   * its spans, which the loader puts back from the node's own `file`.
+   *
+   * A node's declaration span is in the node's file, always — the path in the
+   * span was the same string a second time, once per node. It is the reader's
+   * to reconstruct, and {@link TtscGraphMemory} does, so nothing downstream of
+   * the loader sees a span without its file.
+   */
+  export interface INode extends Omit<
+    ITtscGraphNode,
+    "evidence" | "implementation"
+  > {
+    /** Declaration span; its file is this node's `file`. */
+    evidence?: ITtscGraphSpan;
+
+    /**
+     * Implementation span. This one keeps its file when it has one: an
+     * implementation genuinely can live in another file from its declaration.
+     */
+    implementation?: ITtscGraphSpan;
+  }
 
   /**
-   * Fused compiler and plugin diagnostics, when diagnostics were collected.
-   * Absent when the dump was built without a diagnostics pass.
+   * An edge as the builder sends it. Its span is in the file its `from` id
+   * names — the id is `path#Qualified.Name:kind` — so the path rode the wire a
+   * second time on every edge, and edges outnumber nodes several times over.
    */
-  diagnostics?: ITtscGraphDiagnostic[];
+  export interface IEdge extends Omit<ITtscGraphEdge, "evidence"> {
+    /** Expression span; its file is the one embedded in `from`. */
+    evidence?: ITtscGraphSpan;
+  }
 }

package/src/structures/ITtscGraphEdge.ts

@@ -2,12 +2,10 @@ import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 import { TtscGraphEdgeKind } from "./TtscGraphEdgeKind";
 
 /**
- * A directed relationship from one {@link ITtscGraphNode} to another, both named
- * by `id`. The triple `(from, to, kind)` is unique; a repeated relationship
- * keeps the first source-order evidence.
- *
- * Every edge is resolved by the compiler, so there is no per-edge trust flag to
- * carry — the whole graph is checker-resolved fact.
+ * A directed relationship between two {@link ITtscGraphNode}s, both named by
+ * `id`. The triple `(from, to, kind)` is unique; a repeat keeps the first
+ * source-order evidence. Every edge is compiler-resolved, so there is no
+ * per-edge trust flag: the whole graph is checker-resolved fact.
  */
 export interface ITtscGraphEdge {
   /** Node id the relationship originates from. */