@ttsc/graph 0.16.6 → 0.16.8

package/src/structures/ITtscGraphTour.ts

@@ -0,0 +1,150 @@
+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. */
+  primaryFlow: ITtscGraphTour.IFlow[];
+
+  /** Nearby dependency anchors around the selected entrypoints. */
+  nearby: ITtscGraphTour.IAnchor[];
+
+  /** Test or usage anchors reached through graph impact edges. */
+  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. */
+  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.
+   */
+  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.
+     *
+     * Prefer the default. Raise only when the question names several distinct
+     * public paths that must all appear in one answer.
+     *
+     * @default 4
+     */
+    limit?: number;
+
+    /**
+     * Include graph-reached test or usage anchors when available.
+     *
+     * @default true
+     */
+    includeTests?: boolean;
+  }
+
+  /** A compact symbol coordinate for a tour. */
+  export interface INode {
+    /** Stable node id for later graph calls. */
+    id: string;
+
+    /** Qualified symbol name when available, otherwise the simple name. */
+    name: string;
+
+    /** Declaration kind (`class`, `method`, `function`, ...). */
+    kind: string;
+
+    /** Project-relative declaration file. */
+    file: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+
+    /** Declaration or implementation range, when known. */
+    sourceSpan?: ITtscGraphTour.ISpan;
+
+    /** Declaration head, when available. */
+    signature?: string;
+
+    /** Decorators written on the declaration, when any. */
+    decorators?: ITtscGraphDecorator[];
+  }
+
+  /** A primary flow slice from one selected entrypoint. */
+  export interface IFlow {
+    /** Flow start node. */
+    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. */
+    truncated?: boolean;
+  }
+
+  /** A file/line citation chosen by the graph, not source body text. */
+  export interface IAnchor {
+    /** Why this anchor matters in the tour. */
+    reason: string;
+
+    /** Stable node id when the anchor belongs to a node. */
+    id?: string;
+
+    /** Symbol, edge, or test name to show in the answer. */
+    name: string;
+
+    /** Declaration kind, when this anchor belongs to a node. */
+    kind?: string;
+
+    /** Project-relative file. */
+    file: string;
+
+    /** 1-based start line. */
+    startLine: number;
+
+    /** 1-based end line, when known. */
+    endLine?: number;
+  }
+
+  /** Source coordinates without source text. */
+  export interface ISpan {
+    /** Project-relative file. */
+    file: string;
+
+    /** 1-based start line. */
+    startLine: number;
+
+    /** 1-based end line, when known. */
+    endLine?: number;
+  }
+}

package/src/structures/ITtscGraphTrace.ts

@@ -1,6 +1,7 @@
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 
-/** The ordered dependency flow returned from a start symbol. */
+/** The compact dependency or caller flow returned from a selected start symbol. */
 export interface ITtscGraphTrace {
   /** Discriminator for dependency tracing. */
   type: "trace";
@@ -8,6 +9,7 @@ export interface ITtscGraphTrace {
   /** The resolved start node, or undefined when `from` matched nothing. */
   start?: ITtscGraphTrace.INode;
 
+  /** Trace direction actually used by this result. */
   direction: string;
 
   /** Edges traversed, in breadth-first order. */
@@ -32,8 +34,11 @@ export interface ITtscGraphTrace {
   /** Compact hop summaries preserving node names and edge evidence, capped. */
   steps?: string[];
 
-  /** Follow-up handles for inspecting or continuing the trace. */
-  next?: ITtscGraphTrace.INext;
+  /** How to use this source-free result next. */
+  next: ITtscGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
 
   /** When `from` was an ambiguous name, the matches to disambiguate with. */
   candidates?: ITtscGraphTrace.INode[];
@@ -55,14 +60,16 @@ export namespace ITtscGraphTrace {
      * A target symbol: node id, simple symbol name, or dotted member name. When
      * given, the tool returns the dependency path from `from` to this target,
      * the one-call answer for "how does A reach B", instead of an open-ended
-     * trace.
+     * trace. Prefer this path mode whenever both ends are known.
      */
     to?: string;
 
     /**
      * `forward` follows what the start uses (callees, instantiations, renders);
      * `reverse` follows what uses the start (callers); `impact` is a reverse
-     * trace that flags the public API and tests a change would reach.
+     * trace that prioritizes public API and test nodes a change would reach.
+     * Its test nodes are semantic usage edges, not a text-search inventory.
+     * Caller questions usually fit `reverse`.
      *
      * @default "forward"
      */
@@ -71,15 +78,19 @@ export namespace ITtscGraphTrace {
     /**
      * Which non-structural edge family to follow: `execution` follows runtime
      * calls, instantiations, property access, and JSX renders; `types` follows
-     * type references and inheritance; `all` preserves the full graph.
+     * type references and inheritance; `all` preserves the full graph. Flow
+     * questions should usually choose `execution` rather than `all`.
      *
      * @default "all"
      */
     focus?: "all" | "execution" | "types";
 
     /**
-     * How many hops deep to follow. Open traces are capped at 2; path mode is
-     * capped at 12.
+     * How many hops deep to follow. Open forward/reverse traces are capped at
+     * 2; impact traces at 4; path mode at 12.
+     *
+     * Prefer the default for open traces. Raise only for path mode or when the
+     * previous trace named the missing next hop.
      *
      * @default 2
      */
@@ -87,27 +98,45 @@ export namespace ITtscGraphTrace {
 
     /**
      * Cap on reached nodes; the trace stops and marks itself truncated past it.
-     * Open traces are capped at 10 nodes so a broad graph cannot flood
-     * context.
+     * Open forward/reverse traces are capped at 8 nodes, impact at 16 nodes.
+     *
+     * Prefer the default; use larger open traces only when a named missing edge
+     * requires it.
      *
      * @default 6
      */
     maxNodes?: number;
+
+    /**
+     * Include dependency-boundary nodes from node_modules or bundled `.d.ts`
+     * libraries. Leave false for source-flow tours; enable only when the user
+     * asks about external type/API boundaries.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
   }
 
   /** One traversed edge, with its depth from the start. */
   export interface IHop {
+    /** Source node id for this traversed edge. */
     from: string;
+
+    /** Target node id for this traversed edge. */
     to: string;
+
+    /** Edge kind (`calls`, `type_ref`, `accesses`, ...). */
     kind: string;
+
     /** Hops from the start (1 = direct). */
     depth: number;
+
     /**
-     * Source span for the expression that produced this hop. It lets an agent
-     * explain why the trace moves from one symbol to the next without opening
-     * the file.
+     * Source span for the expression that produced this hop. It is repository
+     * evidence for the hop and can be cited without opening the file.
      */
     evidence?: ITtscGraphEvidence;
+
     /**
      * Stable access-path aliases derived from edge evidence. These preserve a
      * resolved member's owner and the concrete property path used at the call
@@ -118,23 +147,31 @@ export namespace ITtscGraphTrace {
 
   /** A node on the trace: the start, a reached node, or a candidate. */
   export interface INode {
+    /** Stable node id for subsequent graph calls. */
     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 declaration file. */
     file: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+
+    /** Declaration or implementation citation range, when known. */
+    sourceSpan?: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">;
+
     /** Hops from the start, on a reached node. */
     depth?: number;
+
     /** The node's signature, carried on path nodes so the path explains itself. */
     signature?: string;
+
     /** Why this node matters to an impact trace: `exported`, `test`. */
     roles?: string[];
   }
-
-  /** Tool-call handles suggested by this trace. */
-  export interface INext {
-    /** Pass these ids to `details` for selected symbol details. */
-    details: string[];
-    /** Continue tracing from these ids when the current result is intermediate. */
-    traceFrom: string[];
-  }
 }

package/src/structures/index.ts

@@ -16,7 +16,9 @@ export * from "./ITtscGraphEntrypoints";
 export * from "./ITtscGraphNode";
 export * from "./ITtscGraphOverview";
 export * from "./ITtscGraphLookup";
+export * from "./ITtscGraphNext";
 export * from "./ITtscGraphTrace";
+export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";
 export * from "./TtscGraphNodeKind";
 export * from "./TtscGraphNodeModifier";

package/lib/server/instructions.js

@@ -1,80 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.instructions = void 0;
-/**
- * The guidance delivered in the MCP initialize response. It is the only place
- * the agent is told how to use the graph; nothing is written to its config
- * files. Keep it short; the per-tool descriptions carry the detail.
- */
-exports.instructions = `
-Before answering a TypeScript codebase question, call query. It is the
-code-evidence path:
-symbols, dependency paths, edge evidence ranges, and sourceSpan line anchors
-from the resident project graph. Do not answer from assumptions, ls, rg, cat,
-or Get-Content when graph evidence can answer the code question.
-
-The graph is a resident TypeScript fact map, not an answer writer. Fill
-arguments in order: question, graphNeed, draft, review, request. Write
-draft.reason before draft.type, review it for overfetch and non-graph fallback,
-then choose one final request.type:
-entrypoints, lookup, trace, details, overview, or escape. If the review shows the
-question is about scripts, config, generated output, prose docs, or evidence
-already in hand, choose escape instead of spending a graph
-operation. If more TypeScript evidence is needed, make another graph request
-instead of switching to shell search.
-
-Budget graph calls before the first request. Most answers need 1-3 calls, and
-four calls is the hard stop for one answer. A fifth graph call means the tool is
-being used as a source reader; answer from returned handles/ranges or choose
-escape and report the missing span.
-
-For behavior, lifecycle, request-flow, rendering-flow, or validation-flow
-questions, start with one default entrypoints call, then one trace from the best
-handle, then answer. Use overview only for broad architecture or public API
-orientation.
-
-The graph already knows resolved symbols, dependency edges, evidence spans,
-decorators, stable handles, and sourceSpan line anchors. Use returned ranges and
-handles as the evidence. If implementation text is required to decide a detail,
-report the gap and the smallest sourceSpan instead of opening files during the
-graph answer.
-
-For caller or call-site questions, do not use rg. Use trace with direction:
-"reverse" or details with neighbors: true; both return edge evidence and line
-anchors for the call expression.
-
-Request types:
-
-- entrypoints: compact shortlist for behavior-specific code questions. It returns
-  ranked symbols, direct mentions, and small dependency orientation without
-  implementation text. Do not use it as the first broad public API map.
-- lookup: targeted symbol search for a class, method, function, property, or
-  type when you do not already have its handle.
-- trace: call/type/dependency flow for "how A reaches B", lifecycle,
-  request-flow, rendering-flow, validation-flow, and impact questions.
-- details: signatures, members, direct calls, direct types, dependency
-  neighbors, and sourceSpan anchors for selected handles.
-- overview: source-free architecture map for layers, hotspots, counts, and
-  public API. Use it to choose a central exported TypeScript API or entry point
-  without reading package scripts.
-- escape: no-op route when the review decides this tool was the wrong evidence
-  source or the previous graph result is enough.
-
-For a flow question, use entrypoints once, then trace before details. Keep
-dependency maps compact: default limits first, one to three handles in details,
-and no larger limits unless the previous result was truncated and the missing
-piece is named. Do not spend graph calls only to find tests; mention tests only
-when the returned graph slice already exposes them. Stop once file/symbol/range
-evidence is enough to answer.
-
-Copy exact names from returned nodes, references, aliases, evidence ranges,
-sourceSpan anchors, and trace steps. Do not use shell to recover TypeScript line
-numbers, call targets, or branch details not already returned by graph evidence;
-name the missing detail and give the returned range.
-
-Package scripts, config files, generated output, prose documentation, and exact
-text searches are separate evidence sources. Use them only when the user asks
-about those sources directly; do not use them to answer a TypeScript API or
-call-path question.
-`.trim();
-//# sourceMappingURL=instructions.js.map

package/lib/server/instructions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/server/instructions.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsE3B,CAAC,IAAI,EAAE,CAAC"}

package/src/server/instructions.ts

@@ -1,76 +0,0 @@
-/**
- * The guidance delivered in the MCP initialize response. It is the only place
- * the agent is told how to use the graph; nothing is written to its config
- * files. Keep it short; the per-tool descriptions carry the detail.
- */
-export const instructions = `
-Before answering a TypeScript codebase question, call query. It is the
-code-evidence path:
-symbols, dependency paths, edge evidence ranges, and sourceSpan line anchors
-from the resident project graph. Do not answer from assumptions, ls, rg, cat,
-or Get-Content when graph evidence can answer the code question.
-
-The graph is a resident TypeScript fact map, not an answer writer. Fill
-arguments in order: question, graphNeed, draft, review, request. Write
-draft.reason before draft.type, review it for overfetch and non-graph fallback,
-then choose one final request.type:
-entrypoints, lookup, trace, details, overview, or escape. If the review shows the
-question is about scripts, config, generated output, prose docs, or evidence
-already in hand, choose escape instead of spending a graph
-operation. If more TypeScript evidence is needed, make another graph request
-instead of switching to shell search.
-
-Budget graph calls before the first request. Most answers need 1-3 calls, and
-four calls is the hard stop for one answer. A fifth graph call means the tool is
-being used as a source reader; answer from returned handles/ranges or choose
-escape and report the missing span.
-
-For behavior, lifecycle, request-flow, rendering-flow, or validation-flow
-questions, start with one default entrypoints call, then one trace from the best
-handle, then answer. Use overview only for broad architecture or public API
-orientation.
-
-The graph already knows resolved symbols, dependency edges, evidence spans,
-decorators, stable handles, and sourceSpan line anchors. Use returned ranges and
-handles as the evidence. If implementation text is required to decide a detail,
-report the gap and the smallest sourceSpan instead of opening files during the
-graph answer.
-
-For caller or call-site questions, do not use rg. Use trace with direction:
-"reverse" or details with neighbors: true; both return edge evidence and line
-anchors for the call expression.
-
-Request types:
-
-- entrypoints: compact shortlist for behavior-specific code questions. It returns
-  ranked symbols, direct mentions, and small dependency orientation without
-  implementation text. Do not use it as the first broad public API map.
-- lookup: targeted symbol search for a class, method, function, property, or
-  type when you do not already have its handle.
-- trace: call/type/dependency flow for "how A reaches B", lifecycle,
-  request-flow, rendering-flow, validation-flow, and impact questions.
-- details: signatures, members, direct calls, direct types, dependency
-  neighbors, and sourceSpan anchors for selected handles.
-- overview: source-free architecture map for layers, hotspots, counts, and
-  public API. Use it to choose a central exported TypeScript API or entry point
-  without reading package scripts.
-- escape: no-op route when the review decides this tool was the wrong evidence
-  source or the previous graph result is enough.
-
-For a flow question, use entrypoints once, then trace before details. Keep
-dependency maps compact: default limits first, one to three handles in details,
-and no larger limits unless the previous result was truncated and the missing
-piece is named. Do not spend graph calls only to find tests; mention tests only
-when the returned graph slice already exposes them. Stop once file/symbol/range
-evidence is enough to answer.
-
-Copy exact names from returned nodes, references, aliases, evidence ranges,
-sourceSpan anchors, and trace steps. Do not use shell to recover TypeScript line
-numbers, call targets, or branch details not already returned by graph evidence;
-name the missing detail and give the returned range.
-
-Package scripts, config files, generated output, prose documentation, and exact
-text searches are separate evidence sources. Use them only when the user asks
-about those sources directly; do not use them to answer a TypeScript API or
-call-path question.
-`.trim();