@ttsc/graph 0.16.10 → 0.16.11

package/lib/structures/ITtscGraphTour.d.ts

@@ -0,0 +1,113 @@
+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 declare 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.
+     */
+    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. */
+    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. */
+    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. */
+    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. */
+    interface ISpan {
+        /** Project-relative file. */
+        file: string;
+        /** 1-based start line. */
+        startLine: number;
+        /** 1-based end line, when known. */
+        endLine?: number;
+    }
+}

package/lib/structures/ITtscGraphTrace.d.ts

@@ -0,0 +1,143 @@
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
+/** The compact dependency or caller flow returned from a selected start symbol. */
+export interface ITtscGraphTrace {
+    /** Discriminator for dependency tracing. */
+    type: "trace";
+    /** 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. */
+    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[];
+    /** 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[];
+}
+export declare namespace ITtscGraphTrace {
+    /** Where and how far to trace dependency flow. */
+    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. 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 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"
+         */
+        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. Flow
+         * questions should usually choose `execution` rather than `all`.
+         *
+         * @default "all"
+         */
+        focus?: "all" | "execution" | "types";
+        /**
+         * 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
+         */
+        maxDepth?: number;
+        /**
+         * Cap on reached nodes; the trace stops and marks itself truncated past it.
+         * 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. */
+    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 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
+         * site.
+         */
+        aliases?: string[];
+    }
+    /** A node on the trace: the start, a reached node, or a candidate. */
+    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[];
+    }
+}

package/lib/structures/TtscGraphEdgeKind.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/lib/structures/TtscGraphNodeKind.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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/lib/structures/TtscGraphNodeModifier.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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";

package/lib/structures/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./ITtscGraphApplication";
+export * from "./ITtscGraphDecorator";
+export * from "./ITtscGraphDiagnostic";
+export * from "./ITtscGraphDump";
+export * from "./ITtscGraphEdge";
+export * from "./ITtscGraphEvidence";
+export * from "./ITtscGraphEscape";
+export * from "./ITtscGraphDetails";
+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/view.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `ttsc-graph view`: build the project's code graph, reduce it, and serve a
+ * self-contained 3D viewer on a localhost port, opening the browser. The native
+ * binary produces the graph (the same `dump` the docs document); everything
+ * else is local and offline. The process stays alive serving until Ctrl+C.
+ */
+export declare function runView(argv: readonly string[]): number | void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.16.10",
+  "version": "0.16.11",
   "description": "Checker-resolved architecture graph over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -39,7 +39,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "7.0.1-rc",
-    "ttsc": "0.16.10"
+    "ttsc": "0.16.11"
   },
   "repository": {
     "type": "git",