@ttsc/graph 0.18.3 → 0.19.0

package/src/structures/ITtscGraphEntrypoints.ts

@@ -1,15 +1,11 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /** The first compact source-free handle list for a TypeScript code question. */
 export interface ITtscGraphEntrypoints {
   /** Discriminator for first-pass question indexing. */
   type: "entrypoints";
 
-  /** The original question/search phrase the entrypoints were built for. */
-  query: string;
-
   /** Ranked symbols relevant to the query. */
   hits: ITtscGraphEntrypoints.IHit[];
 
@@ -19,50 +15,37 @@ export interface ITtscGraphEntrypoints {
   /** Direct dependency context for the resolved mentions and highest hits. */
   neighborhood: ITtscGraphEntrypoints.INeighborhood[];
 
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
-
-  /** True when result caps hid additional seeds or references. */
+  /** True when some low-signal seeds or references were capped; the list stands. */
   truncated?: boolean;
 }
 
 export namespace ITtscGraphEntrypoints {
   /**
-   * Ask for first handles when the question is narrow but the symbol is not yet
-   * known. For broad tours, read-next, architecture, or multi-phase runtime
-   * flow, use `tour` instead of decomposing the answer into entrypoints and
-   * follow-up calls.
+   * First handles when the question is narrow but the symbol name is not yet
+   * known.
    */
   export interface IRequest {
     /** Discriminator for first-pass question indexing. */
     type: "entrypoints";
 
     /**
-     * A natural code question or search phrase. Mix prose with code handles,
-     * for example `how Repository.find loads relations` or
-     * `SelectQueryBuilder.setFindOptions join aliases`. Keep this close to the
-     * user's question; do not turn it into a broad keyword dump.
+     * A natural code question or search phrase, prose mixed with code handles
+     * (`how Repository.find loads relations`). Keep it close to the user's
+     * question, not a broad keyword dump.
      */
     query: string;
 
     /**
      * Maximum ranked hits to return.
      *
-     * Prefer the default. Raise only when the first result was truncated and
-     * the missing handle is named.
-     *
      * @default 4
      */
     limit?: number;
 
     /**
-     * Maximum direct dependencies and dependents to return per indexed symbol.
-     * This is an orientation slice, not a dependency dump; use `trace` or
-     * `details` with `neighbors:true` after choosing the specific handles.
-     * Prefer the default zero for the first call.
+     * Maximum direct dependencies and dependents per indexed symbol. An
+     * orientation slice, not a dependency dump; use `trace` or `details` with
+     * `neighbors:true` after choosing the specific handles.
      *
      * @default 0
      */
@@ -140,10 +123,7 @@ export namespace ITtscGraphEntrypoints {
     /** Edge kind connecting the indexed node and this neighbor. */
     relation: string;
 
-    /**
-     * Source span for the expression that produced this relationship. It lets
-     * an agent see why the edge exists without opening the file.
-     */
+    /** Source span for the edge: shows why it exists without opening the file. */
     evidence?: ITtscGraphEvidence;
   }
 }

package/src/structures/ITtscGraphEscape.ts

@@ -1,5 +1,3 @@
-import { ITtscGraphNext } from "./ITtscGraphNext";
-
 /** The no-op result for when graph is not the useful next evidence source. */
 export interface ITtscGraphEscape {
   /** Discriminator for the no-op escape route. */
@@ -11,12 +9,6 @@ export interface ITtscGraphEscape {
   /** Why no graph operation should run. */
   reason: string;
 
-  /** How to proceed after skipping graph work. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
-
   /** Optional note about the next non-graph step. */
   nextStep?: string;
 }
@@ -28,21 +20,16 @@ export namespace ITtscGraphEscape {
     type: "escape";
 
     /**
-     * Why no graph operation should run.
-     *
-     * Use this only when the next evidence is outside the indexed TypeScript
-     * graph: package scripts, config files, generated output, prose docs, exact
-     * text, or exact source body text. Name the smallest returned sourceSpan
-     * when source body text is truly required.
+     * Why no graph operation should run. Use only when the next evidence is
+     * outside the indexed graph: package scripts, config files, generated
+     * output, prose docs, exact text, or source body text. Name the smallest
+     * returned sourceSpan when source body text is truly required.
      */
     reason: string;
 
     /**
-     * The final non-graph note, if useful.
-     *
-     * Keep this short. Examples: `answer from the prior graph result`, `source
-     * body needed at returned sourceSpan`, or `ask the user for a concrete
-     * symbol`.
+     * A short final non-graph note, if useful, for example `answer from the
+     * prior graph result` or `source body needed at returned sourceSpan`.
      */
     nextStep?: string;
   }

package/src/structures/ITtscGraphEvidence.ts

@@ -1,12 +1,9 @@
 /**
- * A source location that grounds a node or edge in real code: the declaration
- * span for a node, or the expression range that produced an edge.
- *
- * Evidence is display and grounding only; it is never identity. A node's id is
- * position-invariant (see {@link ITtscGraphNode}), so an edit that shifts a span
- * does not re-key anything. `startLine`/`startCol` are 1-based. MCP output
- * keeps evidence as coordinates; consumers can read the file themselves when
- * they truly need source text.
+ * A source location grounding a node or edge in real code: the declaration span
+ * for a node, or the expression range that produced an edge. Display and
+ * grounding only, never identity (a node's id is position-invariant, see
+ * {@link ITtscGraphNode}). Lines and columns are 1-based; MCP keeps evidence as
+ * coordinates, so read the file yourself when you truly need source text.
  */
 export interface ITtscGraphEvidence {
   /** Project-relative path of the file the span lives in. */

package/src/structures/ITtscGraphLookup.ts

@@ -1,5 +1,4 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /** Targeted symbol lookup when a concrete name or handle is being resolved. */
 export interface ITtscGraphLookup {
@@ -8,12 +7,6 @@ export interface ITtscGraphLookup {
 
   /** Ranked symbol matches for the query. */
   hits: ITtscGraphLookup.IHit[];
-
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
 }
 export namespace ITtscGraphLookup {
   /** Find a concrete class, method, function, property, type, or dotted handle. */
@@ -22,19 +15,16 @@ export namespace ITtscGraphLookup {
     type: "lookup";
 
     /**
-     * What to find, in natural language and code vocabulary mixed freely: a
-     * symbol name, a dotted member (`Service.create`), or a short phrase
-     * (`request handler`). Exact names are not required, but this is not a
-     * second broad entrypoints call. Use it when a named handle is missing or
-     * ambiguous.
+     * What to find: a symbol name, a dotted member (`Service.create`), or a
+     * short phrase (`request handler`). Exact names are not required, but this
+     * is not a second broad entrypoints call; use it for a missing or ambiguous
+     * named handle.
      */
     query: string;
 
     /**
-     * Maximum hits to return.
-     *
-     * Prefer the default. Large hit lists usually mean the query is too broad;
-     * refine the name instead of raising this.
+     * Maximum hits to return. A large hit list usually means the query is too
+     * broad; refine the name instead of raising this.
      *
      * @default 5
      */
@@ -42,8 +32,8 @@ export namespace ITtscGraphLookup {
 
     /**
      * Include dependency-boundary declarations from node_modules or bundled
-     * `.d.ts` libraries. Leave false for project-source 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
      */
@@ -67,10 +57,7 @@ export namespace ITtscGraphLookup {
     /** 1-based declaration line, when known. */
     line?: number;
 
-    /**
-     * The hit's declaration signature, so you can often answer without
-     * requesting details.
-     */
+    /** Declaration signature, often enough to answer without a `details` call. */
     signature?: string;
 
     /** Decorators written on this declaration, when any. */

package/src/structures/ITtscGraphNext.ts

@@ -1,15 +1,18 @@
-/** The required next step from a compiler-derived graph result. */
+/** What to do with a compiler-derived graph result. */
 export interface ITtscGraphNext {
   /**
-   * Answer, continue graph inspection, leave graph, or clarify.
+   * What to do with this result:
    *
-   * `answer` means the returned graph result already carries the evidence
-   * contract for the current question, even when the slice is capped. Do not
-   * call graph again or read files to re-check or complete it.
+   * - `answer`: the result carries the evidence; stop and answer, do not call
+   *   graph again or read files to re-check it
+   * - `inspect`: the result is genuinely partial; make exactly the one `request`
+   *   named, once
+   * - `outside`: the answer is outside the graph; escape and read source
+   * - `clarify`: the request was malformed or ambiguous; restate it
    */
   action: "answer" | "inspect" | "outside" | "clarify";
 
-  /** Smallest graph request type to use when `action` is `inspect`. */
+  /** The single graph request type to use when `action` is `inspect`. */
   request?:
     | "entrypoints"
     | "lookup"
@@ -18,6 +21,6 @@ export interface ITtscGraphNext {
     | "overview"
     | "tour";
 
-  /** Why the returned graph evidence supports that action. */
+  /** Why the returned evidence supports that action. */
   reason: string;
 }

package/src/structures/ITtscGraphNode.ts

@@ -33,15 +33,14 @@ export interface ITtscGraphNode {
   file: string;
 
   /**
-   * True when the declaration lives outside the workspace (a dependency). The
-   * graph keeps the leaf as a named endpoint but does not walk into its
-   * internals.
+   * True when the declaration is outside the workspace (a dependency): kept as
+   * a named endpoint, not walked into.
    */
   external: boolean;
 
   /**
-   * True when `file` is git-ignored generated code (a Prisma client, a codegen
-   * output). Projections desurface these so generated nodes do not bury the
+   * True when `file` is git-ignored generated code (Prisma client, codegen
+   * output); projections desurface these so generated nodes do not bury the
    * authored graph.
    */
   ignored?: boolean;
@@ -49,13 +48,24 @@ export interface ITtscGraphNode {
   /** True when the symbol is part of its module's export surface. */
   exported?: boolean;
 
+  /**
+   * True for a declaration made inside another declaration's body: Vue's
+   * `baseCreateRenderer.patch`, a callback bound to a const inside a method.
+   *
+   * It is a name the runtime calls, so a trace, a lookup, or a details request
+   * answers with it. An orientation tour does not rank or walk it: a tour is
+   * asked what the project's surface is and how it runs, and a body's inner
+   * functions are neither — letting them into the seed ranking reshuffled which
+   * flows a tour told, and the model went back to the files.
+   */
+  closure?: boolean;
+
   /** Declaration modifiers, when the declaration pass recorded any. */
   modifiers?: TtscGraphNodeModifier[];
 
   /**
-   * The decorators written on this declaration, in source order, when it has
-   * any: raw decorator facts (`@Controller`, `@Get`) a consumer can interpret
-   * without re-parsing source.
+   * Decorators written on this declaration, in source order: raw facts
+   * (`@Controller`, `@Get`) a consumer interprets without re-parsing source.
    */
   decorators?: ITtscGraphDecorator[];
 

package/src/structures/ITtscGraphOverview.ts

@@ -1,5 +1,3 @@
-import { ITtscGraphNext } from "./ITtscGraphNext";
-
 /** A compact, source-read-free project map for broad orientation only. */
 export interface ITtscGraphOverview {
   /** Discriminator for source-free project overview. */
@@ -11,12 +9,6 @@ export interface ITtscGraphOverview {
   /** Size of the graph. */
   counts: ITtscGraphOverview.ICounts;
 
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
-
   /** Folder layering, largest first. */
   layers?: ITtscGraphOverview.ILayer[];
 
@@ -33,13 +25,15 @@ export namespace ITtscGraphOverview {
     type: "overview";
 
     /**
-     * The facet to project, or `all` for every facet. `layers` is the folder
-     * layering, `hotspots` the highest-dependency symbols, `publicApi` the
-     * exported API symbols ranked by how depended-on they are.
+     * Facet to project, or `all` for every facet:
+     *
+     * - `layers`: folder layering
+     * - `hotspots`: highest-dependency symbols
+     * - `publicApi`: exported API symbols ranked by how depended-on they are
      *
-     * Use this only for broad public API or layer orientation. For behavior,
-     * lifecycle, request-flow, rendering-flow, validation-flow, caller, or
-     * dependency questions, use `entrypoints` then `trace` instead.
+     * Broad public-API or layer orientation only. For behavior, lifecycle,
+     * request/render/validation flow, caller, or dependency questions, use
+     * `entrypoints` then `trace`.
      *
      * @default "all"
      */
@@ -94,9 +88,8 @@ export namespace ITtscGraphOverview {
   }
 
   /**
-   * One symbol on the project's exported public API surface. The list is ranked
-   * by how depended-on the symbol is, with test, typings, and generated files
-   * excluded.
+   * One exported public-API symbol. The list is ranked by how depended-on the
+   * symbol is, excluding test, typings, and generated files.
    */
   export type IPublicApi = INode;
 }

package/src/structures/ITtscGraphSpan.ts

@@ -0,0 +1,33 @@
+/**
+ * A span on the wire, without the file it lives in.
+ *
+ * The reader already knows the file: a node's span is in the node's `file`, and
+ * an edge's span is in the file its `from` id names. Sending the path a second
+ * and a third time cost 17% of the document — on VS Code, 55 MB of a 323 MB
+ * dump that then has to be encoded, piped, parsed and validated — for a value
+ * that is reconstructible exactly.
+ *
+ * {@link TtscGraphMemory} puts the file back before any of it is read, so what
+ * the graph engine and the MCP results see is the whole
+ * {@link ITtscGraphEvidence}. This shape exists only between the Go builder and
+ * the loader.
+ */
+export interface ITtscGraphSpan {
+  /**
+   * Present only when it cannot be derived: an `implementation` can live in a
+   * different file from the declaration that owns it.
+   */
+  file?: string;
+
+  /** 1-based line where the span starts. */
+  startLine: number;
+
+  /** 1-based column where the span starts, when known. */
+  startCol?: number;
+
+  /** 1-based line where the span ends, when known. */
+  endLine?: number;
+
+  /** 1-based column where the span ends, when known. */
+  endCol?: number;
+}

package/src/structures/ITtscGraphTour.ts

@@ -1,14 +1,10 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /** Answer-ready, source-free tour evidence for broad code-flow questions. */
 export interface ITtscGraphTour {
   /** Discriminator for code-tour indexing. */
   type: "tour";
 
-  /** Natural code question this tour was built for. */
-  query: string;
-
   /** Central entrypoints selected for the tour. */
   entrypoints: ITtscGraphTour.INode[];
 
@@ -24,36 +20,51 @@ export interface ITtscGraphTour {
   /** Ordered file/line anchors to cite in the final answer, not file reads. */
   answerAnchors: ITtscGraphTour.IAnchor[];
 
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
-
-  /** True when any internal slice hit its cap. */
+  /** True when some low-signal extras were capped; the returned tour stands. */
   truncated?: boolean;
 }
 
 export namespace ITtscGraphTour {
   /**
-   * Build the complete index-level answer surface for broad code tours: central
-   * entrypoints, primary flow, nearby paths, tests, and answer anchors. Use
-   * this instead of decomposing repository-orientation, read-next,
-   * architecture, or multi-phase runtime-flow questions into many
-   * lookup/details/trace calls.
+   * A broad code tour: entrypoints, primary flow, nearby paths, and tests.
+   *
+   * It asks for no question of its own — it ranks against the `question` the
+   * caller has already written, in the user's words.
    */
   export interface IRequest {
     /** Discriminator for code-tour indexing. */
     type: "tour";
 
-    /** The user's natural code-tour question. */
-    query: string;
-
     /**
-     * Maximum central entrypoints to seed the tour.
+     * Symbol names, never a sentence: the machinery you expect the answer to be
+     * made of, spelled the way this codebase would spell it. A question about
+     * how a job reaches a worker is reinterpreted as `["JobQueue.push",
+     * "Scheduler.tick", "Worker.run", "drainQueue"]`.
      *
-     * Prefer the default. Raise only when the question names several distinct
-     * public paths that must all appear in one answer.
+     * Write them from the question, before you have seen a line of the code. A
+     * codebase names many things alike, and the question's own words cannot
+     * tell them apart: a question about _tracking_ matches the debug hook named
+     * after tracking as readily as the function that does it, and one about a
+     * _request_ matches a message listener as readily as an HTTP router. The
+     * names say which you meant.
+     *
+     * Each is resolved like a handle — a symbol name, a `Class.member`. The
+     * ones the graph holds take half the tour's entrypoints, the rest stays
+     * with what the graph finds central, and a name it does not know, or knows
+     * several of, is dropped. So a wrong guess costs nothing, and a specific
+     * name is worth more than a general one: `drainQueue` resolves, `queue`
+     * does not.
+     *
+     * Send `[]` when the question names no machinery — "show me the central
+     * flow" in a repository you have never seen. There is nothing to
+     * reinterpret then: the tour ranks on structure, which is what that
+     * question asks for. Do not look names up first to fill this.
+     */
+    reinterpretations: string[];
+
+    /**
+     * Central entrypoints to seed the tour. Raise only when the question names
+     * several public paths that must all appear in one answer.
      *
      * @default 4
      */
@@ -90,6 +101,13 @@ export namespace ITtscGraphTour {
     /** Declaration head, when available. */
     signature?: string;
 
+    /**
+     * The first sentence of the doc comment above the declaration: what the
+     * project says this symbol is for. A name and an edge say what calls what;
+     * this says why, which is what a tour is asked for.
+     */
+    doc?: string;
+
     /** Decorators written on the declaration, when any. */
     decorators?: ITtscGraphDecorator[];
   }
@@ -102,16 +120,40 @@ export namespace ITtscGraphTour {
     /** Compact edge summaries in graph order. */
     steps: string[];
 
-    /** Nodes reached by this flow. */
-    reached: ITtscGraphTour.INode[];
-
-    /** Edge and node anchors that explain the flow. */
-    anchors: ITtscGraphTour.IAnchor[];
+    /**
+     * Every node this flow reached, with the handle to call the graph with
+     * next.
+     *
+     * A step is prose — it names both of its ends and the file and line the
+     * call sits on — and it carries no handle. So the nodes a step names are
+     * listed here too: `steps` is the story, `reached` is what to go on with.
+     */
+    reached: ITtscGraphTour.IReached[];
 
-    /** True when the flow hit graph caps. */
+    /** True when some low-signal flow steps were capped; the flow stands. */
     truncated?: boolean;
   }
 
+  /**
+   * A node a flow reached, as its handle and its declaration line.
+   *
+   * A node id _is_ its coordinates — `path/to/file.ts#Owner.member:kind` — so a
+   * reached node carrying `file` and `kind` beside it bought the same fact
+   * three times. Across the benchmark corpus that repetition was 15% of every
+   * tour, and a tour is re-sent whole on every turn of the conversation it
+   * opened.
+   */
+  export interface IReached {
+    /** Stable node id for later graph calls: `file#Qualified.Name:kind`. */
+    id: string;
+
+    /** Qualified symbol name when available, otherwise the simple name. */
+    name: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+  }
+
   /** A file/line citation chosen by the graph, not source body text. */
   export interface IAnchor {
     /** Why this anchor matters in the tour. */