@ttsc/graph 0.16.5 → 0.16.6

package/src/structures/ITtscGraphDetails.ts

@@ -0,0 +1,134 @@
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+
+/**
+ * The resolved symbol details returned for a set of handles.
+ *
+ * The default payload is source-free: signatures, member outlines, and direct
+ * graph summaries with sourceSpan anchors.
+ */
+export interface ITtscGraphDetails {
+  /** Discriminator for selected symbol inspection. */
+  type: "details";
+
+  nodes: ITtscGraphDetails.INode[];
+
+  /** 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. */
+  export interface IRequest {
+    /** Discriminator for selected symbol inspection. */
+    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; 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.
+     *
+     * @default false
+     */
+    neighbors?: boolean;
+
+    /**
+     * Maximum dependencies and dependents to return per side when
+     * `neighbors:true`.
+     *
+     * @default 2
+     */
+    neighborLimit?: number;
+
+    /**
+     * Maximum owned members to return for a container or object literal. Raise
+     * only when the first outline is truncated.
+     *
+     * @default 6
+     */
+    memberLimit?: number;
+
+    /**
+     * Maximum direct execution and type references to return per group. Raise
+     * only when the first dependency slice is not enough.
+     *
+     * @default 1
+     */
+    dependencyLimit?: number;
+  }
+
+  /** One inspected node: its declared shape and graph coordinates. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    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[];
+    /** 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. */
+    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 {
+    name: string;
+    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 {
+    id: string;
+    name: string;
+    kind: string;
+    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.
+     */
+    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/{ITtscGraphIndex.ts → ITtscGraphEntrypoints.ts}

@@ -1,31 +1,40 @@
-/** The compact source-free index returned by `graph_index` for a code question. */
-export interface ITtscGraphIndex {
-  /** The original query the index was built for. */
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+
+/** The compact source-free entrypoint list returned for a 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: ITtscGraphIndex.IHit[];
+  hits: ITtscGraphEntrypoints.IHit[];
 
   /** Code handles written directly in the query, resolved when possible. */
-  mentions: ITtscGraphIndex.IMention[];
+  mentions: ITtscGraphEntrypoints.IMention[];
 
   /** Direct dependency context for the resolved mentions and highest hits. */
-  neighborhood: ITtscGraphIndex.INeighborhood[];
+  neighborhood: ITtscGraphEntrypoints.INeighborhood[];
 
   /** Follow-up handles for deeper graph calls. */
-  next: ITtscGraphIndex.INext;
+  next: ITtscGraphEntrypoints.INext;
 
   /** True when result caps hid additional seeds or references. */
   truncated?: boolean;
 }
 
-export namespace ITtscGraphIndex {
+export namespace ITtscGraphEntrypoints {
   /**
-   * Ask the graph for the first index an agent should read before opening
+   * Ask the graph for the first entrypoints an agent should read before opening
    * source: ranked symbols, exact mentioned handles, and nearby dependency
    * edges.
    */
-  export interface IProps {
+  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
@@ -36,14 +45,16 @@ export namespace ITtscGraphIndex {
     /**
      * Maximum ranked hits to return.
      *
-     * @default 8
+     * @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.
      *
-     * @default 4
+     * @default 0
      */
     neighbors?: number;
   }
@@ -58,6 +69,8 @@ export namespace ITtscGraphIndex {
     line?: number;
     /** Declaration head, included only for indexed symbols. */
     signature?: string;
+    /** Decorators written on this declaration, when any. */
+    decorators?: ITtscGraphDecorator[];
   }
 
   /** One ranked search hit. */
@@ -88,13 +101,18 @@ export namespace ITtscGraphIndex {
     /** 1-based declaration line, when known. */
     line?: number;
     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 index. */
+  /** Tool-call handles suggested by this first entrypoints result. */
   export interface INext {
-    /** Pass these ids to `graph_expand`, with `source: true` only when needed. */
-    expand: string[];
-    /** Pass these ids to `graph_trace` when following dependency flow. */
+    /** 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

@@ -0,0 +1,39 @@
+/** The no-op graph result returned when reasoning rejects the graph call. */
+export interface ITtscGraphEscape {
+  /** Discriminator for the no-op escape route. */
+  type: "escape";
+
+  /** Always true so callers can distinguish an intentional no-op. */
+  skipped: true;
+
+  /** Why no graph operation should run. */
+  reason: string;
+
+  /** The next non-graph step, if useful. */
+  nextStep?: string;
+}
+
+export namespace ITtscGraphEscape {
+  /** Exit after the reasoning review decides graph evidence is unnecessary. */
+  export interface IRequest {
+    /** Discriminator for the no-op escape route. */
+    type: "escape";
+
+    /**
+     * 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.
+     */
+    reason: string;
+
+    /**
+     * The next non-graph step, if useful.
+     *
+     * Keep this short. Examples: `answer from the prior graph result`, `inspect
+     * package.json`, or `ask the user for a concrete symbol`.
+     */
+    nextStep?: string;
+  }
+}

package/src/structures/ITtscGraphEvidence.ts

@@ -1,12 +1,12 @@
 /**
- * A source location that grounds a node or edge in real code — the declaration
- * span for a node, or the expression that produced an edge.
+ * 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. `text` is an
- * optional short excerpt the producer may include so a consumer can show the
- * evidence without a file read.
+ * 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.
  */
 export interface ITtscGraphEvidence {
   /** Project-relative path of the file the span lives in. */
@@ -23,7 +23,4 @@ export interface ITtscGraphEvidence {
 
   /** 1-based column where the span ends, when known. */
   endCol?: number;
-
-  /** A short source excerpt of the span, when the producer inlines one. */
-  text?: string;
 }

package/src/structures/ITtscGraphLookup.ts

@@ -0,0 +1,61 @@
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+
+/** The ranked hits returned by targeted symbol lookup. */
+export interface ITtscGraphLookup {
+  /** Discriminator for targeted symbol lookup. */
+  type: "lookup";
+
+  hits: ITtscGraphLookup.IHit[];
+
+  /** Follow-up handles for selected symbol details. */
+  next: ITtscGraphLookup.INext;
+}
+export namespace ITtscGraphLookup {
+  /** Find the symbols and clusters most relevant to a natural code query. */
+  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.
+     */
+    query: string;
+
+    /**
+     * Maximum hits to return.
+     *
+     * @default 5
+     */
+    limit?: number;
+  }
+
+  /** One ranked hit with a handle to follow via `details` or `trace`. */
+  export interface IHit {
+    id: string;
+    name: string;
+    kind: string;
+    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/ITtscGraphNode.ts

@@ -23,7 +23,7 @@ export interface ITtscGraphNode {
   name: string;
 
   /**
-   * The owner-qualified name, when the node lives inside another declaration —
+   * The owner-qualified name, when the node lives inside another declaration:
    * `OrderService.create`, `Shopping.ISale`. Absent for a top-level
    * declaration.
    */
@@ -34,7 +34,7 @@ export interface ITtscGraphNode {
 
   /**
    * True when the declaration lives outside the workspace (a dependency). The
-   * graph keeps the leaf as a named endpoint but does not expand its
+   * graph keeps the leaf as a named endpoint but does not walk into its
    * internals.
    */
   external: boolean;
@@ -54,11 +54,17 @@ export interface ITtscGraphNode {
 
   /**
    * The decorators written on this declaration, in source order, when it has
-   * any — raw decorator facts (`@Controller`, `@Get`) a consumer can interpret
+   * any: raw decorator facts (`@Controller`, `@Get`) a consumer can interpret
    * without re-parsing source.
    */
   decorators?: ITtscGraphDecorator[];
 
-  /** The declaration span, for display and source expansion. */
+  /** The declaration span, for display and signatures. */
   evidence?: ITtscGraphEvidence;
+
+  /**
+   * The implementation span when a callable/property member is implemented by a
+   * function assignment separate from its declaration.
+   */
+  implementation?: ITtscGraphEvidence;
 }

package/src/structures/ITtscGraphOverview.ts

@@ -1,8 +1,11 @@
 /**
- * A compact, source-read-free architecture map of the project — the result of
- * the `graph_overview` tool.
+ * A compact, source-read-free architecture map of the project returned by
+ * `overview`.
  */
 export interface ITtscGraphOverview {
+  /** Discriminator for source-free project overview. */
+  type: "overview";
+
   /** Absolute project root. */
   project: string;
 
@@ -19,8 +22,11 @@ export interface ITtscGraphOverview {
   publicApi?: ITtscGraphOverview.IPublicApi[];
 }
 export namespace ITtscGraphOverview {
-  /** Which architecture facets `graph_overview` should return. */
-  export interface IProps {
+  /** Which architecture facets `overview` should return. */
+  export interface IRequest {
+    /** 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
@@ -50,12 +56,22 @@ export namespace ITtscGraphOverview {
     exported: number;
   }
 
-  /** A high-dependency symbol with its non-structural fan-in and fan-out. */
-  export interface IHotspot {
+  /** A compact symbol coordinate that can be passed to deeper graph tools. */
+  export interface INode {
+    /** Stable handle for `details` or `trace`. */
     id: string;
+    /** The symbol's qualified name when available. */
     name: string;
+    /** Its declaration kind (`class`, `interface`, `function`, ...). */
     kind: string;
+    /** Project-relative path of the file that declares it. */
     file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+  }
+
+  /** A high-dependency symbol with its non-structural fan-in and fan-out. */
+  export interface IHotspot extends INode {
     /** Non-structural edges pointing at this symbol. */
     fanIn: number;
     /** Non-structural edges leaving this symbol. */
@@ -65,15 +81,7 @@ 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, so the names a consumer of the project would reach for surface
-   * first — not whichever file happens to declare the most exports.
+   * excluded.
    */
-  export interface IPublicApi {
-    /** The exported symbol's name. */
-    name: string;
-    /** Its declaration kind (`class`, `interface`, `function`, …). */
-    kind: string;
-    /** Project-relative path of the file that declares it. */
-    file: string;
-  }
+  export type IPublicApi = INode;
 }

package/src/structures/ITtscGraphTrace.ts

@@ -1,8 +1,10 @@
-/**
- * The ordered dependency flow the `graph_trace` tool returns from a start
- * symbol.
- */
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+
+/** The ordered dependency flow returned from a start symbol. */
 export interface ITtscGraphTrace {
+  /** Discriminator for dependency tracing. */
+  type: "trace";
+
   /** The resolved start node, or undefined when `from` matched nothing. */
   start?: ITtscGraphTrace.INode;
 
@@ -27,12 +29,21 @@ export interface ITtscGraphTrace {
    */
   path?: ITtscGraphTrace.INode[];
 
+  /** Compact hop summaries preserving node names and edge evidence, capped. */
+  steps?: string[];
+
+  /** Follow-up handles for inspecting or continuing the trace. */
+  next?: ITtscGraphTrace.INext;
+
   /** When `from` was an ambiguous name, the matches to disambiguate with. */
   candidates?: ITtscGraphTrace.INode[];
 }
 export namespace ITtscGraphTrace {
   /** Where and how far to trace dependency flow. */
-  export interface IProps {
+  export interface IRequest {
+    /** Discriminator for dependency tracing. */
+    type: "trace";
+
     /**
      * Where to start: a node id from another tool, a simple symbol name, or a
      * dotted member name such as `OrderService.create`. An ambiguous name
@@ -42,8 +53,8 @@ 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
+     * 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.
      */
     to?: string;
@@ -58,16 +69,28 @@ export namespace ITtscGraphTrace {
     direction?: "forward" | "reverse" | "impact";
 
     /**
-     * How many hops deep to follow.
+     * 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.
      *
-     * @default 6
+     * @default "all"
+     */
+    focus?: "all" | "execution" | "types";
+
+    /**
+     * How many hops deep to follow. Open traces are capped at 2; path mode is
+     * capped at 12.
+     *
+     * @default 2
      */
     maxDepth?: number;
 
     /**
      * 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.
      *
-     * @default 60
+     * @default 6
      */
     maxNodes?: number;
   }
@@ -79,6 +102,18 @@ export namespace ITtscGraphTrace {
     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.
+     */
+    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
+     * site.
+     */
+    aliases?: string[];
   }
 
   /** A node on the trace: the start, a reached node, or a candidate. */
@@ -89,9 +124,17 @@ export namespace ITtscGraphTrace {
     file: string;
     /** Hops from the start, on a reached node. */
     depth?: number;
-    /** The node's signature — carried on path nodes so the path explains itself. */
+    /** 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/TtscGraphNodeKind.ts

@@ -3,8 +3,8 @@
  *
  * The symbol kinds (`file` through `parameter`) are declarations the TypeScript
  * program owns and the checker resolves. `external_symbol` is a
- * dependency-boundary leaf the workspace references but does not declare — the
- * graph keeps it as a named endpoint without expanding the dependency's
+ * dependency-boundary leaf the workspace references but does not declare. The
+ * graph keeps it as a named endpoint without walking into the dependency's
  * internals.
  *
  * Used as the `kind` discriminant on {@link ITtscGraphNode}.

package/src/structures/index.ts

@@ -10,11 +10,12 @@ export * from "./ITtscGraphDiagnostic";
 export * from "./ITtscGraphDump";
 export * from "./ITtscGraphEdge";
 export * from "./ITtscGraphEvidence";
-export * from "./ITtscGraphExpand";
-export * from "./ITtscGraphIndex";
+export * from "./ITtscGraphEscape";
+export * from "./ITtscGraphDetails";
+export * from "./ITtscGraphEntrypoints";
 export * from "./ITtscGraphNode";
 export * from "./ITtscGraphOverview";
-export * from "./ITtscGraphQuery";
+export * from "./ITtscGraphLookup";
 export * from "./ITtscGraphTrace";
 export * from "./TtscGraphEdgeKind";
 export * from "./TtscGraphNodeKind";