@ttsc/graph 0.16.6 → 0.16.8

package/src/structures/ITtscGraphDetails.ts

@@ -1,23 +1,32 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /**
- * The resolved symbol details returned for a set of handles.
+ * The source-free facts for a few selected handles.
  *
- * The default payload is source-free: signatures, member outlines, and direct
- * graph summaries with sourceSpan anchors.
+ * This is not a file reader. It returns signatures, member outlines, direct
+ * calls, direct types, implementation candidates, dependency summaries, and
+ * sourceSpan citation anchors.
  */
 export interface ITtscGraphDetails {
   /** Discriminator for selected symbol inspection. */
   type: "details";
 
+  /** 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. */
   unknown: string[];
 }
 export namespace ITtscGraphDetails {
-  /** Which handles to inspect, and how much of each to return. */
+  /** Which selected handles to inspect, and how much of each to return. */
   export interface IRequest {
     /** Discriminator for selected symbol inspection. */
     type: "details";
@@ -25,14 +34,16 @@ export namespace ITtscGraphDetails {
     /**
      * Node ids from another tool, or dotted symbol handles such as
      * `OrderService.create`. Pass the few handles you need for source-free
-     * details; use `trace` when you need a path instead of widening this call.
+     * details. Prefer one to three handles. Use `trace` when you need 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` only when the first slice is not enough.
+     * `neighborLimit` when the first slice is truncated and the missing
+     * relation is named. This remains a relationship summary, not a file body.
      *
      * @default false
      */
@@ -42,13 +53,17 @@ export namespace ITtscGraphDetails {
      * 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.
+     *
      * @default 2
      */
     neighborLimit?: number;
 
     /**
      * Maximum owned members to return for a container or object literal. Raise
-     * only when the first outline is truncated.
+     * only when the first outline is truncated and the missing member is
+     * named.
      *
      * @default 6
      */
@@ -56,73 +71,121 @@ export namespace ITtscGraphDetails {
 
     /**
      * Maximum direct execution and type references to return per group. Raise
-     * only when the first dependency slice is not enough.
+     * only when the first dependency slice is truncated and the missing
+     * dependency is named.
      *
      * @default 1
      */
     dependencyLimit?: number;
+
+    /**
+     * 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.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
   }
 
   /** One inspected node: its declared shape and graph coordinates. */
   export interface INode {
+    /** Stable node id for subsequent `details` or `trace` 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 file that declares this node. */
     file: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The declaration signature: its first line(s) up to the body. */
     signature?: string;
+
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
+
     /** Assigned implementation span, when source comes from one. */
     implementation?: ITtscGraphEvidence;
+
     /** Direct execution dependencies in source order, with edge evidence. */
     calls?: IReference[];
+
     /** Direct type dependencies in source order, with edge evidence. */
     types?: IReference[];
+
+    /** Concrete nodes that implement or override this interface/base member. */
+    implementedBy?: IReference[];
+
     /** String literal values from the signature. */
     literals?: string[];
+
     /**
      * For a container or object-literal variable: the owned symbol or top-level
      * property outline a consumer reaches for, without bodies.
      */
     members?: IMember[];
-    /** The declaration or implementation file and line range, when known. */
+
+    /** Declaration or implementation citation range, when known. */
     sourceSpan?: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">;
+
     /** Symbols this node uses (outgoing dependency edges). */
     dependsOn?: IReference[];
+
     /** Symbols that use this node (incoming dependency edges). */
     dependedOnBy?: IReference[];
   }
 
   /** One member of a container node, with its signature but not its body. */
   export interface IMember {
+    /** Member name, qualified when the graph records an owner-qualified handle. */
     name: string;
+
+    /** Member kind (`method`, `property`, `class`, ...). */
     kind: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The member's declaration signature. */
     signature?: string;
+
     /** Decorators written on this member, when any. */
     decorators?: ITtscGraphDecorator[];
   }
 
   /** A dependency neighbor of an inspected node and the edge that links them. */
   export interface IReference {
+    /** Stable id of the neighboring node. */
     id: string;
+
+    /** Neighbor symbol name, qualified when available. */
     name: string;
+
+    /** Neighbor declaration kind. */
     kind: string;
+
+    /** Project-relative declaration file for the neighbor. */
     file: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The edge kind connecting the two (`calls`, `type_ref`, ...). */
     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 expression that produced this relationship. It is
+     * repository evidence for the edge, not a file-read instruction.
      */
     evidence?: ITtscGraphEvidence;
+
     /**
      * Stable access-path aliases derived from edge evidence. For example, an
      * edge to `Owner.member` through `obj.slot.member` may expose

package/src/structures/ITtscGraphEntrypoints.ts

@@ -1,7 +1,8 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 
-/** The compact source-free entrypoint list returned for a code question. */
+/** The first compact source-free handle list for a TypeScript code question. */
 export interface ITtscGraphEntrypoints {
   /** Discriminator for first-pass question indexing. */
   type: "entrypoints";
@@ -18,8 +19,11 @@ export interface ITtscGraphEntrypoints {
   /** Direct dependency context for the resolved mentions and highest hits. */
   neighborhood: ITtscGraphEntrypoints.INeighborhood[];
 
-  /** Follow-up handles for deeper graph calls. */
-  next: ITtscGraphEntrypoints.INext;
+  /** 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. */
   truncated?: boolean;
@@ -27,9 +31,10 @@ export interface ITtscGraphEntrypoints {
 
 export namespace ITtscGraphEntrypoints {
   /**
-   * Ask the graph for the first entrypoints an agent should read before opening
-   * source: ranked symbols, exact mentioned handles, and nearby dependency
-   * edges.
+   * 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.
    */
   export interface IRequest {
     /** Discriminator for first-pass question indexing. */
@@ -38,13 +43,17 @@ export namespace ITtscGraphEntrypoints {
     /**
      * A natural code question or search phrase. Mix prose with code handles,
      * for example `how Repository.find loads relations` or
-     * `SelectQueryBuilder.setFindOptions join aliases`.
+     * `SelectQueryBuilder.setFindOptions join aliases`. Keep this close to the
+     * user's question; do not turn it into 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;
@@ -53,6 +62,7 @@ export namespace ITtscGraphEntrypoints {
      * 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.
      *
      * @default 0
      */
@@ -61,14 +71,24 @@ export namespace ITtscGraphEntrypoints {
 
   /** A compact symbol coordinate, optionally with its declaration signature. */
   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 head, included only for indexed symbols. */
     signature?: string;
+
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
   }
@@ -81,38 +101,49 @@ export namespace ITtscGraphEntrypoints {
 
   /** A code handle written in the query, with its resolution status. */
   export interface IMention {
+    /** The exact handle text found in the query. */
     handle: string;
+
+    /** Resolved node when the handle maps unambiguously. */
     node?: INode;
+
+    /** Candidate nodes when the handle is ambiguous. */
     candidates?: INode[];
   }
 
   /** Direct dependency context around one indexed symbol. */
   export interface INeighborhood extends INode {
+    /** Symbols this node directly uses, capped by `neighbors`. */
     dependsOn: IReference[];
+
+    /** Symbols that directly use this node, capped by `neighbors`. */
     dependedOnBy: IReference[];
   }
 
   /** One neighboring symbol and the relationship leading to it. */
   export interface IReference {
+    /** Stable id of the neighboring node. */
     id: string;
+
+    /** Neighbor symbol name, qualified when available. */
     name: string;
+
+    /** Neighbor declaration kind. */
     kind: string;
+
+    /** Project-relative declaration file for the neighbor. */
     file: string;
+
     /** 1-based declaration line, when known. */
     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.
      */
     evidence?: ITtscGraphEvidence;
   }
-
-  /** Tool-call handles suggested by this first entrypoints result. */
-  export interface INext {
-    /** Pass these ids to `details` for source-free symbol facts. */
-    details: string[];
-    /** Pass these ids to `trace` when following dependency flow. */
-    traceFrom: string[];
-  }
 }

package/src/structures/ITtscGraphEscape.ts

@@ -1,4 +1,6 @@
-/** The no-op graph result returned when reasoning rejects the graph call. */
+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. */
   type: "escape";
@@ -9,12 +11,18 @@ export interface ITtscGraphEscape {
   /** Why no graph operation should run. */
   reason: string;
 
-  /** The next non-graph step, if useful. */
+  /** 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;
 }
 
 export namespace ITtscGraphEscape {
-  /** Exit after the reasoning review decides graph evidence is unnecessary. */
+  /** Skip graph work when graph evidence is unnecessary or exhausted. */
   export interface IRequest {
     /** Discriminator for the no-op escape route. */
     type: "escape";
@@ -22,17 +30,19 @@ export namespace ITtscGraphEscape {
     /**
      * Why no graph operation should run.
      *
-     * Use this when the review finds the user is asking about package scripts,
-     * config files, generated output, prose documentation, or an answer that
-     * the current graph result already settled.
+     * 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.
      */
     reason: string;
 
     /**
-     * The next non-graph step, if useful.
+     * The final non-graph note, if useful.
      *
-     * Keep this short. Examples: `answer from the prior graph result`, `inspect
-     * package.json`, or `ask the user for a concrete symbol`.
+     * Keep this short. Examples: `answer from the prior graph result`, `source
+     * body needed at returned sourceSpan`, or `ask the user for a concrete
+     * symbol`.
      */
     nextStep?: string;
   }

package/src/structures/ITtscGraphLookup.ts

@@ -1,61 +1,82 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 
-/** The ranked hits returned by targeted symbol lookup. */
+/** 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[];
 
-  /** Follow-up handles for selected symbol details. */
-  next: ITtscGraphLookup.INext;
+  /** How to use this source-free result next. */
+  next: ITtscGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
 }
 export namespace ITtscGraphLookup {
-  /** Find the symbols and clusters most relevant to a natural code query. */
+  /** Find a concrete class, method, function, property, type, or dotted handle. */
   export interface IRequest {
     /** Discriminator for targeted symbol lookup. */
     type: "lookup";
 
     /**
      * What to find, in natural language and code vocabulary mixed freely: a
-     * symbol name, a dotted member (`OrderService.create`), or a phrase
-     * (`shopping order create`, `repository find relations`). Exact names are
-     * not required; subword and CamelCase matches rank too.
+     * 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.
      */
     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.
+     *
      * @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.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
   }
 
   /** One ranked hit with a handle to follow via `details` or `trace`. */
   export interface IHit {
+    /** 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;
+
     /**
      * The hit's declaration signature, so you can often answer without
      * requesting details.
      */
     signature?: string;
+
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
+
     /** Relative relevance; higher is a better match. */
     score: number;
   }
-
-  /** Tool-call handles suggested by this lookup result. */
-  export interface INext {
-    /** Pass these ids to `details` for source-free symbol facts. */
-    details: string[];
-    /** Pass these ids to `trace` when following dependency flow. */
-    traceFrom: string[];
-  }
 }

package/src/structures/ITtscGraphNext.ts

@@ -0,0 +1,23 @@
+/** The required next step from a compiler-derived graph result. */
+export interface ITtscGraphNext {
+  /**
+   * Answer, continue graph inspection, leave graph, or clarify.
+   *
+   * `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.
+   */
+  action: "answer" | "inspect" | "outside" | "clarify";
+
+  /** Smallest graph request type to use when `action` is `inspect`. */
+  request?:
+    | "entrypoints"
+    | "lookup"
+    | "trace"
+    | "details"
+    | "overview"
+    | "tour";
+
+  /** Why the returned graph evidence supports that action. */
+  reason: string;
+}

package/src/structures/ITtscGraphOverview.ts

@@ -1,7 +1,6 @@
-/**
- * A compact, source-read-free architecture map of the project returned by
- * `overview`.
- */
+import { ITtscGraphNext } from "./ITtscGraphNext";
+
+/** A compact, source-read-free project map for broad orientation only. */
 export interface ITtscGraphOverview {
   /** Discriminator for source-free project overview. */
   type: "overview";
@@ -12,6 +11,12 @@ 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[];
 
@@ -22,7 +27,7 @@ export interface ITtscGraphOverview {
   publicApi?: ITtscGraphOverview.IPublicApi[];
 }
 export namespace ITtscGraphOverview {
-  /** Which architecture facets `overview` should return. */
+  /** Which broad architecture facets `overview` should return. */
   export interface IRequest {
     /** Discriminator for source-free project overview. */
     type: "overview";
@@ -32,6 +37,10 @@ export namespace ITtscGraphOverview {
      * layering, `hotspots` the highest-dependency symbols, `publicApi` the
      * 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.
+     *
      * @default "all"
      */
     aspect?: "all" | "layers" | "hotspots" | "publicApi";
@@ -39,9 +48,15 @@ export namespace ITtscGraphOverview {
 
   /** Size of the graph by node/edge totals and per-kind node counts. */
   export interface ICounts {
+    /** Number of source file container nodes. */
     files: number;
+
+    /** Total node count, including declarations and file containers. */
     nodes: number;
+
+    /** Total edge count, including structural edges. */
     edges: number;
+
     /** Node count per kind. */
     byKind: Record<string, number>;
   }