@ttsc/graph 0.16.5 → 0.16.7

package/src/structures/ITtscGraphDecorator.ts

@@ -1,32 +1,30 @@
 /**
  * A decorator as written on a declaration, carried on the decorated
- * {@link ITtscGraphNode}'s `decorators`. The graph reports the decorator
- * faithfully rather than interpreting any framework's convention: the `name` is
- * the decorator as written (`Controller`, `Get`, `TypedRoute.Get`, …) and the
- * statically resolvable `arguments` are preserved, so a consumer can apply its
- * own meaning without re-parsing source.
+ * {@link ITtscGraphNode}'s `decorators`.
+ *
+ * The graph reports the decorator faithfully rather than interpreting any
+ * framework's convention: the `name` is the decorator as written (`Controller`,
+ * `Get`, `TypedRoute.Get`, ...), and statically resolvable literal arguments
+ * are preserved so a consumer can apply its own meaning without re-parsing
+ * source.
  */
 export interface ITtscGraphDecorator {
   /**
-   * The decorator name as written, qualified through its access path —
+   * The decorator name as written, qualified through its access path:
    * `Controller`, `Get`, `TypedRoute.Get`, `MessagePattern`.
    */
   name: string;
 
-  /** The call arguments, in source order. Empty for a bare decorator. */
+  /** The literal call arguments, in source order. Empty for a bare decorator. */
   arguments: ITtscGraphDecorator.IArgument[];
 }
 export namespace ITtscGraphDecorator {
   /**
-   * One argument of an {@link ITtscGraphDecorator}. `text` is always the source
-   * of the argument expression; `literal` is set only when the argument is a
-   * string, number, or boolean literal the producer could resolve statically,
-   * so a consumer can use it without evaluating code.
+   * One argument of an {@link ITtscGraphDecorator}. `literal` is set only when
+   * the argument is a string, number, or boolean literal the producer could
+   * resolve statically, so a consumer can use it without evaluating code.
    */
   export interface IArgument {
-    /** The argument expression's source text. */
-    text: string;
-
     /** The statically-resolved literal value, when the argument is a literal. */
     literal?: string | number | boolean;
   }

package/src/structures/ITtscGraphDetails.ts

@@ -0,0 +1,197 @@
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
+
+/**
+ * The source-free facts for a few selected handles.
+ *
+ * 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 selected 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. 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` when the first slice is truncated and the missing
+     * relation is named. This remains a relationship summary, not a file body.
+     *
+     * @default false
+     */
+    neighbors?: boolean;
+
+    /**
+     * 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 and the missing member is
+     * named.
+     *
+     * @default 6
+     */
+    memberLimit?: number;
+
+    /**
+     * Maximum direct execution and type references to return per group. Raise
+     * 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[];
+
+    /** 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 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
+     * `Owner.slot.member` so answers can preserve both the resolved symbol and
+     * the source access path.
+     */
+    aliases?: string[];
+  }
+}

package/src/structures/ITtscGraphEntrypoints.ts

@@ -0,0 +1,149 @@
+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. */
+  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.
+   */
+  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.
+     */
+    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.
+     *
+     * @default 0
+     */
+    neighbors?: number;
+  }
+
+  /** 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[];
+  }
+
+  /** One ranked search hit. */
+  export interface IHit extends INode {
+    /** Relative relevance; higher is a better match. */
+    score: number;
+  }
+
+  /** 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;
+  }
+}

package/src/structures/ITtscGraphEscape.ts

@@ -0,0 +1,49 @@
+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";
+
+  /** Always true so callers can distinguish an intentional no-op. */
+  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;
+}
+
+export namespace ITtscGraphEscape {
+  /** Skip graph work when graph evidence is unnecessary or exhausted. */
+  export interface IRequest {
+    /** 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.
+     */
+    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`.
+     */
+    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,82 @@
+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 namespace ITtscGraphLookup {
+  /** 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 (`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;
+  }
+}

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/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;
 }