@ttsc/graph 0.18.3 → 0.19.0

package/lib/structures/ITtscGraphEntrypoints.d.ts

@@ -1,56 +1,42 @@
 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[];
     /** Code handles written directly in the query, resolved when possible. */
     mentions: ITtscGraphEntrypoints.IMention[];
     /** 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 declare 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.
      */
     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
          */
@@ -108,10 +94,7 @@ export declare namespace ITtscGraphEntrypoints {
         line?: number;
         /** 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/lib/structures/ITtscGraphEscape.d.ts

@@ -1,4 +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. */
@@ -7,10 +6,6 @@ export interface ITtscGraphEscape {
     skipped: true;
     /** 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;
 }
@@ -20,20 +15,15 @@ export declare namespace ITtscGraphEscape {
         /** Discriminator for the no-op escape route. */
         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/lib/structures/ITtscGraphEvidence.d.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/lib/structures/ITtscGraphLookup.d.ts

@@ -1,15 +1,10 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 /** Targeted symbol lookup when a concrete name or handle is being resolved. */
 export interface ITtscGraphLookup {
     /** Discriminator for targeted symbol lookup. */
     type: "lookup";
     /** 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 declare namespace ITtscGraphLookup {
     /** Find a concrete class, method, function, property, type, or dotted handle. */
@@ -17,26 +12,23 @@ export declare namespace ITtscGraphLookup {
         /** Discriminator for targeted symbol lookup. */
         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
          */
         limit?: number;
         /**
          * 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
          */
@@ -54,10 +46,7 @@ export declare namespace ITtscGraphLookup {
         file: string;
         /** 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. */
         decorators?: ITtscGraphDecorator[];

package/lib/structures/ITtscGraphNext.d.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" | "trace" | "details" | "overview" | "tour";
-    /** Why the returned graph evidence supports that action. */
+    /** Why the returned evidence supports that action. */
     reason: string;
 }

package/lib/structures/ITtscGraphNode.d.ts

@@ -27,25 +27,34 @@ export interface ITtscGraphNode {
     /** Project-relative path of the file that declares this node. */
     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;
     /** 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[];
     /** The declaration span, for display and signatures. */

package/lib/structures/ITtscGraphOverview.d.ts

@@ -1,4 +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. */
@@ -7,10 +6,6 @@ export interface ITtscGraphOverview {
     project: string;
     /** 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[];
     /** Highest-dependency symbols, busiest first. */
@@ -24,13 +19,15 @@ export declare namespace ITtscGraphOverview {
         /** Discriminator for source-free project overview. */
         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:
          *
-         * 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.
+         * - `layers`: folder layering
+         * - `hotspots`: highest-dependency symbols
+         * - `publicApi`: exported API symbols ranked by how depended-on they are
+         *
+         * Broad public-API or layer orientation only. For behavior, lifecycle,
+         * request/render/validation flow, caller, or dependency questions, use
+         * `entrypoints` then `trace`.
          *
          * @default "all"
          */
@@ -77,9 +74,8 @@ export declare namespace ITtscGraphOverview {
         fanOut: number;
     }
     /**
-     * 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.
      */
     type IPublicApi = INode;
 }

package/lib/structures/ITtscGraphSpan.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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/lib/structures/{ITtscGraphDiagnostic.js → ITtscGraphSpan.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ITtscGraphDiagnostic.js.map
+//# sourceMappingURL=ITtscGraphSpan.js.map

package/lib/structures/ITtscGraphSpan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscGraphSpan.js","sourceRoot":"","sources":["../../src/structures/ITtscGraphSpan.ts"],"names":[],"mappings":""}

package/lib/structures/ITtscGraphTour.d.ts

@@ -1,11 +1,8 @@
 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[];
     /** Selected primary runtime flows; sufficient for an index-level tour. */
@@ -16,31 +13,48 @@ export interface ITtscGraphTour {
     tests: ITtscGraphTour.IAnchor[];
     /** 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 declare 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.
      */
     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
          */
@@ -68,6 +82,12 @@ export declare namespace ITtscGraphTour {
         sourceSpan?: ITtscGraphTour.ISpan;
         /** 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[];
     }
@@ -77,13 +97,35 @@ export declare namespace ITtscGraphTour {
         start: ITtscGraphTour.INode;
         /** 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[];
-        /** True when the flow hit graph caps. */
+        /**
+         * 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 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.
+     */
+    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. */
     interface IAnchor {
         /** Why this anchor matters in the tour. */