@ttsc/graph 0.16.4 → 0.16.6

package/src/structures/ITtscGraphDump.ts

@@ -0,0 +1,35 @@
+import { ITtscGraphDiagnostic } from "./ITtscGraphDiagnostic";
+import { ITtscGraphEdge } from "./ITtscGraphEdge";
+import { ITtscGraphNode } from "./ITtscGraphNode";
+
+/**
+ * The whole-graph export `ttscgraph dump` writes and the MCP server loads — the
+ * wire contract between the Go fact-builder and the TypeScript graph engine.
+ *
+ * It is the complete graph with none of the per-response caps the MCP tools
+ * apply: every node and edge the build resolved. The server parses it once at
+ * startup (typia-validated) into an in-memory resident graph and answers every
+ * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ *
+ * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
+ * edges, and diagnostics are project-relative.
+ */
+export interface ITtscGraphDump {
+  /** Absolute path of the project root the graph was built for. */
+  project: string;
+
+  /** The tsconfig the program was loaded from, relative to `project`. */
+  tsconfig: string;
+
+  /** Every node the build recorded. */
+  nodes: ITtscGraphNode[];
+
+  /** Every edge the build resolved. */
+  edges: ITtscGraphEdge[];
+
+  /**
+   * Fused compiler and plugin diagnostics, when diagnostics were collected.
+   * Absent when the dump was built without a diagnostics pass.
+   */
+  diagnostics?: ITtscGraphDiagnostic[];
+}

package/src/structures/ITtscGraphEdge.ts

@@ -0,0 +1,24 @@
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { TtscGraphEdgeKind } from "./TtscGraphEdgeKind";
+
+/**
+ * A directed relationship from one {@link ITtscGraphNode} to another, both named
+ * by `id`. The triple `(from, to, kind)` is unique; a repeated relationship
+ * keeps the first source-order evidence.
+ *
+ * Every edge is resolved by the compiler, so there is no per-edge trust flag to
+ * carry — the whole graph is checker-resolved fact.
+ */
+export interface ITtscGraphEdge {
+  /** Node id the relationship originates from. */
+  from: string;
+
+  /** Node id the relationship points to. */
+  to: string;
+
+  /** The relationship kind. */
+  kind: TtscGraphEdgeKind;
+
+  /** The source expression that produced the edge, for display and expansion. */
+  evidence?: ITtscGraphEvidence;
+}

package/src/structures/ITtscGraphEntrypoints.ts

@@ -0,0 +1,118 @@
+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: 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[];
+
+  /** Follow-up handles for deeper graph calls. */
+  next: ITtscGraphEntrypoints.INext;
+
+  /** True when result caps hid additional seeds or references. */
+  truncated?: boolean;
+}
+
+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.
+   */
+  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`.
+     */
+    query: string;
+
+    /**
+     * Maximum ranked hits to return.
+     *
+     * @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 0
+     */
+    neighbors?: number;
+  }
+
+  /** A compact symbol coordinate, optionally with its declaration signature. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    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 {
+    handle: string;
+    node?: INode;
+    candidates?: INode[];
+  }
+
+  /** Direct dependency context around one indexed symbol. */
+  export interface INeighborhood extends INode {
+    dependsOn: IReference[];
+    dependedOnBy: IReference[];
+  }
+
+  /** One neighboring symbol and the relationship leading to it. */
+  export interface IReference {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** 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 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

@@ -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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export interface ITtscGraphEvidence {
+  /** Project-relative path of the file the span lives in. */
+  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 it differs from `startLine`. */
+  endLine?: number;
+
+  /** 1-based column where the span ends, when known. */
+  endCol?: number;
+}

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

@@ -0,0 +1,70 @@
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { TtscGraphNodeKind } from "./TtscGraphNodeKind";
+import { TtscGraphNodeModifier } from "./TtscGraphNodeModifier";
+
+/**
+ * One node in the graph: a declared symbol or a structural container (file,
+ * package).
+ *
+ * The `id` is position-invariant: `path#qualifiedName:kind` (e.g.
+ * `src/order.ts#OrderService.create:method`), so inserting a line above a
+ * declaration does not re-key it. Line and span live in `evidence` and are
+ * never part of identity.
+ */
+export interface ITtscGraphNode {
+  /** Position-invariant identity (see the interface doc for the id grammar). */
+  id: string;
+
+  /** What this node represents. */
+  kind: TtscGraphNodeKind;
+
+  /** The simple, unqualified declared name (`create`, `OrderService`, `App`). */
+  name: string;
+
+  /**
+   * The owner-qualified name, when the node lives inside another declaration:
+   * `OrderService.create`, `Shopping.ISale`. Absent for a top-level
+   * declaration.
+   */
+  qualifiedName?: string;
+
+  /** 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.
+   */
+  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
+   * authored graph.
+   */
+  ignored?: boolean;
+
+  /** True when the symbol is part of its module's export surface. */
+  exported?: 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?: ITtscGraphDecorator[];
+
+  /** 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

@@ -0,0 +1,87 @@
+/**
+ * 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;
+
+  /** Size of the graph. */
+  counts: ITtscGraphOverview.ICounts;
+
+  /** Folder layering, largest first. */
+  layers?: ITtscGraphOverview.ILayer[];
+
+  /** Highest-dependency symbols, busiest first. */
+  hotspots?: ITtscGraphOverview.IHotspot[];
+
+  /** Exported API symbols, most-depended-on first. */
+  publicApi?: ITtscGraphOverview.IPublicApi[];
+}
+export namespace ITtscGraphOverview {
+  /** 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
+     * exported API symbols ranked by how depended-on they are.
+     *
+     * @default "all"
+     */
+    aspect?: "all" | "layers" | "hotspots" | "publicApi";
+  }
+
+  /** Size of the graph by node/edge totals and per-kind node counts. */
+  export interface ICounts {
+    files: number;
+    nodes: number;
+    edges: number;
+    /** Node count per kind. */
+    byKind: Record<string, number>;
+  }
+
+  /** One folder layer: its source files and export surface. */
+  export interface ILayer {
+    /** Directory, project-relative. */
+    dir: string;
+    /** Distinct source files under it. */
+    files: number;
+    /** Exported symbols declared under it. */
+    exported: number;
+  }
+
+  /** 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. */
+    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.
+   */
+  export type IPublicApi = INode;
+}

package/src/structures/ITtscGraphTrace.ts

@@ -0,0 +1,140 @@
+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;
+
+  direction: string;
+
+  /** Edges traversed, in breadth-first order. */
+  hops: ITtscGraphTrace.IHop[];
+
+  /** Unique nodes reached (excluding the start), each with its depth and roles. */
+  reached: ITtscGraphTrace.INode[];
+
+  /** True when the trace hit maxNodes or maxDepth and more flow exists. */
+  truncated: boolean;
+
+  /** The resolved `to` target, when a path was requested. */
+  target?: ITtscGraphTrace.INode;
+
+  /**
+   * When `to` was given: the ordered dependency path from `from` to `to`
+   * (`from` first, `to` last), or empty when `to` is not reachable from
+   * `from`.
+   */
+  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 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
+     * returns its candidates instead of a trace.
+     */
+    from: string;
+
+    /**
+     * 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.
+     */
+    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.
+     *
+     * @default "forward"
+     */
+    direction?: "forward" | "reverse" | "impact";
+
+    /**
+     * 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 "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 6
+     */
+    maxNodes?: number;
+  }
+
+  /** One traversed edge, with its depth from the start. */
+  export interface IHop {
+    from: string;
+    to: string;
+    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. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    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. */
+    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/TtscGraphEdgeKind.ts

@@ -0,0 +1,23 @@
+/**
+ * The relationship a directed edge encodes between two {@link ITtscGraphNode}s.
+ *
+ * Structural edges (`contains`, `exports`, `imports`) come from the declaration
+ * pass. Value and type edges (`calls`, `accesses`, `instantiates`, `type_ref`,
+ * `extends`, `implements`, `overrides`, `renders`) are resolved by the checker
+ * — `renders` is a JSX component use. `decorates` carries a decorator fact and
+ * `tests` a test-to-subject relationship.
+ */
+export type TtscGraphEdgeKind =
+  | "contains"
+  | "exports"
+  | "imports"
+  | "calls"
+  | "accesses"
+  | "instantiates"
+  | "type_ref"
+  | "extends"
+  | "implements"
+  | "overrides"
+  | "decorates"
+  | "renders"
+  | "tests";

package/src/structures/TtscGraphNodeKind.ts

@@ -0,0 +1,26 @@
+/**
+ * What a graph node represents.
+ *
+ * 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 walking into the dependency's
+ * internals.
+ *
+ * Used as the `kind` discriminant on {@link ITtscGraphNode}.
+ */
+export type TtscGraphNodeKind =
+  | "file"
+  | "package"
+  | "namespace"
+  | "module"
+  | "function"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "variable"
+  | "method"
+  | "property"
+  | "parameter"
+  | "external_symbol";

package/src/structures/TtscGraphNodeModifier.ts

@@ -0,0 +1,19 @@
+/**
+ * A declaration modifier carried on a symbol {@link ITtscGraphNode}, when the
+ * declaration pass records it. Used by projections that reason about visibility
+ * and shape — e.g. a public-API overview filters on `export`, a class outline
+ * separates `static` members.
+ */
+export type TtscGraphNodeModifier =
+  | "export"
+  | "default"
+  | "declare"
+  | "abstract"
+  | "static"
+  | "readonly"
+  | "async"
+  | "const"
+  | "public"
+  | "private"
+  | "protected"
+  | "optional";