@ttsc/graph 0.16.4 → 0.16.5

package/lib/server/createServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createServer.js","sourceRoot":"","sources":["../../src/server/createServer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,oEAAoE;AACpE,iEAG4C;AAC5C,kDAA0B;AAE1B,kEAAgF;AAGhF,iDAA8C;AAE9C;;;;;;;;;;;;;GAaG;AACH,sBACE,KAAsB,EACtB,OAAe;IAEf,MAAM,UAAU;;gBACd,OAAO;mBACP,IAAI,2CAAoB,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAChC,CAAC;IACF,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,SAAS,CAAC;IACnD,MAAM,OAAO,GAAG,UAAU,CAAC,OAG1B,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,EAC/B,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,YAAY,EAAZ,2BAAY,EAAE,CAC9C,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;IAE1B,GAAG,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACzD,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,UAAU;gBACtC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ;gBAClC,oBAAoB,EAAE,KAAK;gBAC3B,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;aAC7B;SACF,CAAC,CAAC;KACJ,CAAC,CAAC,CAAC;IAEJ,GAAG,CAAC,iBAAiB,CAAC,gCAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/C,OAAO,KAAK,CAAC,iBAAiB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,gFAAgF;QAChF,0FAA0F;QAC1F,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YACxB,yEAAyE;YACzE,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;YAC3D,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EACF,MAAM,KAAK,SAAS;4BAClB,CAAC,CAAC,SAAS;4BACX,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,OAAO,KAAK,CACV,SAAS,YAAY,KAAK;gBACxB,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,EAAE;gBAC3C,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CACtB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,KAAK,CAAC,IAAY;IAIzB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/lib/server/instructions.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instructions = void 0;
+/**
+ * The guidance delivered in the MCP initialize response. It is the only place
+ * the agent is told how to use the graph; nothing is written to its config
+ * files. Keep it short; the per-tool descriptions carry the detail.
+ */
+exports.instructions = `
+This TypeScript project is indexed by the compiler. Use the graph as the first
+source of codebase coordinates: it has already resolved symbols and the
+relationships between them.
+
+- graph_index: first call for source questions. It returns ranked symbols,
+  declaration signatures, directly mentioned code handles, and nearby dependency
+  context without source bodies.
+- graph_overview: the architecture, layers, hotspots, and public API.
+- graph_query: find any symbol by name or description; each hit carries its
+  signature, usually enough to answer without expanding. Use next.expand when
+  you need bodies.
+- graph_trace: follow a flow forward, reverse, or to its impact; or give dotted
+  from/to names for the path between two symbols, how A reaches B, in one call.
+- graph_expand: a symbol's declared shape, its signature, and a container's
+  members; source:true to read a specific TypeScript body after graph_index,
+  graph_query, or graph_trace has located it.
+
+Answer in as few calls as you can. For TypeScript declarations, read source with
+graph_expand(source:true) on the resolved handles. Use shell or file reads only
+for a non-TypeScript file, generated output, or an exact literal text search that
+is not represented as symbols or edges.
+`.trim();
+//# sourceMappingURL=instructions.js.map

package/lib/server/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/server/instructions.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsB3B,CAAC,IAAI,EAAE,CAAC"}

package/lib/server/resolveHandle.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGraphHandle = resolveGraphHandle;
+/** Resolve a tool handle as an id, exact symbol name, or dotted suffix. */
+function resolveGraphHandle(graph, handle, candidateLimit = 12) {
+    const byId = graph.node(handle);
+    if (byId !== undefined)
+        return { node: byId };
+    const exact = graph.symbols(handle);
+    if (exact.length === 1)
+        return { node: exact[0] };
+    if (exact.length > 1)
+        return { candidates: exact.slice(0, candidateLimit) };
+    if (handle.includes(".")) {
+        const suffix = `.${handle}`;
+        const suffixMatches = graph.nodes.filter((node) => node.kind !== "file" && node.qualifiedName?.endsWith(suffix) === true);
+        if (suffixMatches.length === 1)
+            return { node: suffixMatches[0] };
+        if (suffixMatches.length > 1) {
+            return { candidates: suffixMatches.slice(0, candidateLimit) };
+        }
+    }
+    return {};
+}
+//# sourceMappingURL=resolveHandle.js.map

package/lib/server/resolveHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveHandle.js","sourceRoot":"","sources":["../../src/server/resolveHandle.ts"],"names":[],"mappings":";;;AAQA,2EAA2E;AAC3E,4BACE,KAAsB,EACtB,MAAc,EACd,cAAc,GAAG,EAAE;IAEnB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAE9C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC;IAE5E,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CACtC,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,CACxE,CAAC;QACF,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC;QAChE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/lib/server/runExpand.js

@@ -0,0 +1,177 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExpand = runExpand;
+exports.signatureOf = signatureOf;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const resolveHandle_1 = require("./resolveHandle");
+// A whole declaration body can be large, so the full source is opt-in and capped
+// when asked for; the default response carries only the declared shape.
+const MAX_SOURCE_LINES = 200;
+// A signature is the declaration head up to the body brace — a handful of lines.
+const MAX_SIGNATURE_LINES = 6;
+// Neighbor lists are a map, not a dump; keep them scannable.
+const MAX_NEIGHBORS = 40;
+// A container's outline can be long (a big class); keep it bounded.
+const MAX_MEMBERS = 80;
+// Structural relationships are navigation, not the dependency picture expand is for.
+const STRUCTURAL_KINDS = new Set(["contains", "exports", "imports"]);
+// Kinds whose value is their member outline, not a source body.
+const CONTAINER_KINDS = new Set([
+    "class",
+    "interface",
+    "namespace",
+    "module",
+    "enum",
+    "file",
+]);
+/**
+ * Resolve each handle to its declared shape — its signature, and for a
+ * container the outline of its members — and, only when asked, its full source
+ * body. This is the graph's edge over a plain file read: it answers from the
+ * resolved structure it already holds, so the agent reads compact shape, not
+ * inlined code, unless it explicitly needs a body's logic.
+ */
+function runExpand(graph, props) {
+    const wantSource = props.source === true;
+    const nodes = [];
+    const unknown = [];
+    for (const handle of props.handles) {
+        const resolved = (0, resolveHandle_1.resolveGraphHandle)(graph, handle);
+        if (resolved.node === undefined) {
+            unknown.push(handle);
+            continue;
+        }
+        const node = resolved.node;
+        const expanded = {
+            id: node.id,
+            name: node.qualifiedName ?? node.name,
+            kind: node.kind,
+            file: node.file,
+        };
+        if (node.evidence?.startLine)
+            expanded.line = node.evidence.startLine;
+        const sig = signatureOf(graph.project, node);
+        if (sig !== undefined)
+            expanded.signature = sig;
+        if (CONTAINER_KINDS.has(node.kind)) {
+            const list = members(graph, node);
+            if (list.length > 0)
+                expanded.members = list;
+        }
+        if (wantSource) {
+            const source = readSource(graph.project, node);
+            if (source !== undefined) {
+                expanded.source = source.text;
+                if (source.truncated)
+                    expanded.truncated = true;
+            }
+        }
+        if (props.neighbors === true) {
+            expanded.dependsOn = refs(graph, graph.outgoing(node.id), "to");
+            expanded.dependedOnBy = refs(graph, graph.incoming(node.id), "from");
+        }
+        nodes.push(expanded);
+    }
+    return { nodes, unknown };
+}
+/** The members a container owns (via `contains`), each with its own signature. */
+function members(graph, node) {
+    const out = [];
+    for (const edge of graph.outgoing(node.id)) {
+        if (edge.kind !== "contains")
+            continue;
+        const member = graph.node(edge.to);
+        if (member === undefined)
+            continue;
+        const m = {
+            name: member.qualifiedName ?? member.name,
+            kind: member.kind,
+        };
+        if (member.evidence?.startLine)
+            m.line = member.evidence.startLine;
+        const sig = signatureOf(graph.project, member);
+        if (sig !== undefined)
+            m.signature = sig;
+        out.push(m);
+        if (out.length >= MAX_MEMBERS)
+            break;
+    }
+    return out;
+}
+/** Map dependency edges to references on their far endpoint, dropping structure. */
+function refs(graph, edges, end) {
+    const out = [];
+    for (const edge of edges) {
+        if (STRUCTURAL_KINDS.has(edge.kind))
+            continue;
+        const other = graph.node(end === "to" ? edge.to : edge.from);
+        if (other === undefined)
+            continue;
+        out.push({
+            id: other.id,
+            name: other.qualifiedName ?? other.name,
+            kind: other.kind,
+            relation: edge.kind,
+        });
+        if (out.length >= MAX_NEIGHBORS)
+            break;
+    }
+    return out;
+}
+/** Read a file's lines once, or undefined when it cannot be read. */
+function fileLines(project, node) {
+    if (node.evidence === undefined || node.file === "")
+        return undefined;
+    try {
+        return node_fs_1.default
+            .readFileSync(node_path_1.default.join(project, node.file), "utf8")
+            .split(/\r?\n/);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The declaration signature: the head of the declaration up to and including
+ * the line that opens its body (`{`), or the single declaration line when there
+ * is no brace, capped so a wrapped signature cannot run away.
+ */
+function signatureOf(project, node) {
+    const lines = fileLines(project, node);
+    const evidence = node.evidence;
+    if (lines === undefined || evidence === undefined)
+        return undefined;
+    const start = Math.max(0, evidence.startLine - 1);
+    const out = [];
+    for (let i = start; i < lines.length && out.length < MAX_SIGNATURE_LINES; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            break;
+        out.push(line);
+        if (line.includes("{"))
+            break;
+    }
+    const text = out.join("\n").trim();
+    return text === "" ? undefined : text;
+}
+/** Slice a node's full declaration source from disk, capped at MAX_SOURCE_LINES. */
+function readSource(project, node) {
+    const lines = fileLines(project, node);
+    const evidence = node.evidence;
+    if (lines === undefined || evidence === undefined)
+        return undefined;
+    const start = Math.max(0, evidence.startLine - 1);
+    const end = Math.min(evidence.endLine ?? evidence.startLine, lines.length);
+    let slice = lines.slice(start, Math.max(start + 1, end));
+    let truncated = false;
+    if (slice.length > MAX_SOURCE_LINES) {
+        slice = slice.slice(0, MAX_SOURCE_LINES);
+        truncated = true;
+    }
+    return { text: slice.join("\n"), truncated };
+}
+//# sourceMappingURL=runExpand.js.map

package/lib/server/runExpand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runExpand.js","sourceRoot":"","sources":["../../src/server/runExpand.ts"],"names":[],"mappings":"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"}

package/lib/server/runIndex.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runIndex = runIndex;
+const resolveHandle_1 = require("./resolveHandle");
+const runExpand_1 = require("./runExpand");
+const runQuery_1 = require("./runQuery");
+const DEFAULT_LIMIT = 8;
+const MAX_LIMIT = 20;
+const DEFAULT_NEIGHBORS = 4;
+const MAX_NEIGHBORS = 8;
+const MAX_SEEDS = 6;
+const STRUCTURAL_KINDS = new Set(["contains", "exports", "imports"]);
+/**
+ * Build the first source-free index for a code question. The result gives the
+ * model stable handles, declaration signatures, and direct graph context. It is
+ * deliberately not a source reader; source remains opt-in through
+ * graph_expand.
+ */
+function runIndex(graph, props) {
+    const query = props.query.trim();
+    const limit = bound(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+    const neighborLimit = bound(props.neighbors, DEFAULT_NEIGHBORS, 0, MAX_NEIGHBORS);
+    const queryResult = (0, runQuery_1.runQuery)(graph, { query, limit });
+    const hits = queryResult.hits.map((hit) => ({ ...hit }));
+    const mentions = directMentions(query).map((handle) => {
+        const resolved = (0, resolveHandle_1.resolveGraphHandle)(graph, handle, 6);
+        const mention = { handle };
+        if (resolved.node !== undefined)
+            mention.node = nodeOf(graph, resolved.node);
+        if (resolved.candidates !== undefined) {
+            mention.candidates = resolved.candidates.map((node) => nodeOf(graph, node));
+        }
+        return mention;
+    });
+    const seeds = [];
+    const seen = new Set();
+    const addSeed = (node) => {
+        if (node === undefined || seen.has(node.id))
+            return;
+        seen.add(node.id);
+        seeds.push(node);
+    };
+    for (const mention of mentions) {
+        if (mention.node !== undefined)
+            addSeed(graph.node(mention.node.id));
+    }
+    for (const hit of hits)
+        addSeed(graph.node(hit.id));
+    let truncated = seeds.length > MAX_SEEDS;
+    const neighborhood = [];
+    for (const seed of seeds.slice(0, MAX_SEEDS)) {
+        const outgoing = refs(graph, graph.outgoing(seed.id), "to", neighborLimit);
+        const incoming = refs(graph, graph.incoming(seed.id), "from", neighborLimit);
+        if (outgoing.truncated || incoming.truncated)
+            truncated = true;
+        neighborhood.push({
+            ...nodeOf(graph, seed),
+            dependsOn: outgoing.items,
+            dependedOnBy: incoming.items,
+        });
+    }
+    return {
+        query,
+        hits,
+        mentions,
+        neighborhood,
+        next: {
+            expand: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
+            traceFrom: mentions
+                .map((mention) => mention.node?.id)
+                .filter((id) => id !== undefined),
+        },
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+function nodeOf(graph, node) {
+    const out = {
+        id: node.id,
+        name: node.qualifiedName ?? node.name,
+        kind: node.kind,
+        file: node.file,
+    };
+    if (node.evidence?.startLine !== undefined)
+        out.line = node.evidence.startLine;
+    const signature = (0, runExpand_1.signatureOf)(graph.project, node);
+    if (signature !== undefined)
+        out.signature = signature;
+    return out;
+}
+function refOf(node, edge) {
+    const out = {
+        id: node.id,
+        name: node.qualifiedName ?? node.name,
+        kind: node.kind,
+        file: node.file,
+        relation: edge.kind,
+    };
+    if (node.evidence?.startLine !== undefined)
+        out.line = node.evidence.startLine;
+    return out;
+}
+function refs(graph, edges, end, limit) {
+    const items = [];
+    const seen = new Set();
+    let available = 0;
+    for (const edge of edges) {
+        if (STRUCTURAL_KINDS.has(edge.kind))
+            continue;
+        const other = graph.node(end === "to" ? edge.to : edge.from);
+        if (other === undefined || other.kind === "file")
+            continue;
+        const key = `${edge.kind}:${other.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        available++;
+        if (items.length < limit)
+            items.push(refOf(other, edge));
+    }
+    return { items, truncated: available > items.length };
+}
+function directMentions(query) {
+    const handles = new Set();
+    for (const match of query.matchAll(/`([^`]+)`/g)) {
+        const handle = normalizeHandle(match[1] ?? "");
+        if (handle !== undefined)
+            handles.add(handle);
+    }
+    for (const match of query.matchAll(/\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b/g)) {
+        const handle = normalizeHandle(match[0]);
+        if (handle !== undefined)
+            handles.add(handle);
+    }
+    return [...handles];
+}
+function normalizeHandle(raw) {
+    const value = raw.trim();
+    return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value)
+        ? value
+        : undefined;
+}
+function bound(value, fallback, min, max) {
+    const n = value === undefined || !Number.isFinite(value) ? fallback : value;
+    return Math.max(min, Math.min(max, Math.floor(n)));
+}
+//# sourceMappingURL=runIndex.js.map

package/lib/server/runIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runIndex.js","sourceRoot":"","sources":["../../src/server/runIndex.ts"],"names":[],"mappings":"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"}

package/lib/server/runOverview.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOverview = runOverview;
+/** Edges that express nesting/packaging, not code dependency. */
+const STRUCTURAL_KINDS = new Set(["contains", "exports", "imports"]);
+/**
+ * Project a compact, source-read-free architecture map: counts by kind, folder
+ * layering with export density, the highest-dependency symbols (ranked by real
+ * fan-in/out, excluding structural edges so nesting does not masquerade as
+ * dependency), and the export surface by file. Output is bounded so a model
+ * reads structure cheaply.
+ */
+function runOverview(graph, props) {
+    const aspect = props.aspect ?? "all";
+    const want = (a) => aspect === "all" || aspect === a;
+    const byKind = {};
+    let files = 0;
+    for (const node of graph.nodes) {
+        byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+        if (node.kind === "file")
+            files++;
+    }
+    const result = {
+        project: graph.project,
+        counts: {
+            files,
+            nodes: graph.nodes.length,
+            edges: graph.edges.length,
+            byKind,
+        },
+    };
+    if (want("layers"))
+        result.layers = layers(graph);
+    if (want("hotspots"))
+        result.hotspots = hotspots(graph);
+    if (want("publicApi"))
+        result.publicApi = publicApi(graph);
+    return result;
+}
+/** Folder-level layering: how source and its export surface spread by directory. */
+function layers(graph) {
+    const byDir = new Map();
+    for (const node of graph.nodes) {
+        if (node.external || node.kind === "file")
+            continue;
+        const dir = dirname(node.file);
+        let entry = byDir.get(dir);
+        if (!entry) {
+            entry = { files: new Set(), exported: 0 };
+            byDir.set(dir, entry);
+        }
+        entry.files.add(node.file);
+        if (node.exported)
+            entry.exported++;
+    }
+    return [...byDir.entries()]
+        .map(([dir, entry]) => ({
+        dir,
+        files: entry.files.size,
+        exported: entry.exported,
+    }))
+        .sort((a, b) => b.files - a.files)
+        .slice(0, 16);
+}
+/**
+ * The symbols at the center of the dependency graph, ranked by real fan-in and
+ * fan-out — structural `contains`/`exports`/`imports` edges are excluded so the
+ * ranking reflects code dependency, not nesting.
+ */
+function hotspots(graph) {
+    const real = (id, side) => {
+        const edges = side === "in" ? graph.incoming(id) : graph.outgoing(id);
+        let n = 0;
+        for (const edge of edges)
+            if (!STRUCTURAL_KINDS.has(edge.kind))
+                n++;
+        return n;
+    };
+    return graph.nodes
+        .filter((node) => !node.external && node.kind !== "file")
+        .map((node) => ({
+        id: node.id,
+        name: node.qualifiedName ?? node.name,
+        kind: node.kind,
+        file: node.file,
+        fanIn: real(node.id, "in"),
+        fanOut: real(node.id, "out"),
+    }))
+        .filter((h) => h.fanIn + h.fanOut > 0)
+        .sort((a, b) => b.fanIn + b.fanOut - (a.fanIn + a.fanOut))
+        .slice(0, 15);
+}
+/** Declaration kinds that make up a meaningful public API surface. */
+const API_KINDS = new Set([
+    "class",
+    "interface",
+    "function",
+    "type",
+    "enum",
+]);
+/**
+ * The exported API surface: the exported symbols a consumer of the project would
+ * use, ranked by how depended-on each is (real fan-in/out, structural edges
+ * excluded). Ranking by dependency rather than by which file declares the most
+ * exports surfaces the load-bearing types (a DataSource, a SelectQueryBuilder)
+ * instead of whichever file bundles the most type aliases; test, typings, and
+ * generated files are dropped so they cannot crowd the real surface out.
+ */
+function publicApi(graph) {
+    const degree = (id) => {
+        let n = 0;
+        for (const edge of graph.outgoing(id))
+            if (!STRUCTURAL_KINDS.has(edge.kind))
+                n++;
+        for (const edge of graph.incoming(id))
+            if (!STRUCTURAL_KINDS.has(edge.kind))
+                n++;
+        return n;
+    };
+    return graph
+        .exported()
+        .filter((node) => API_KINDS.has(node.kind) && !isNoiseFile(node.file))
+        .map((node) => ({
+        name: node.qualifiedName ?? node.name,
+        kind: node.kind,
+        file: node.file,
+        degree: degree(node.id),
+    }))
+        .sort((a, b) => b.degree - a.degree)
+        .slice(0, 30)
+        .map(({ name, kind, file }) => ({ name, kind, file }));
+}
+/**
+ * A file whose exports are noise for an architecture overview: a test, a
+ * dependency's bundled `.d.ts`/typings, or generated output. The conventions are
+ * universal (a `test`/`spec` path, a `typings` file), so excluding them is not
+ * framework-specific — it keeps the API surface to authored, used code.
+ */
+function isNoiseFile(file) {
+    return (/(^|\/)(test|tests|__tests__|spec|sample|samples)\//.test(file) ||
+        /\.(test|spec)\.[cm]?tsx?$/.test(file) ||
+        /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||
+        /\.d\.[cm]?ts$/.test(file));
+}
+/** The parent directory of a project-relative path (`.` at the root). */
+function dirname(file) {
+    const slash = file.lastIndexOf("/");
+    return slash >= 0 ? file.slice(0, slash) : ".";
+}
+//# sourceMappingURL=runOverview.js.map

package/lib/server/runOverview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runOverview.js","sourceRoot":"","sources":["../../src/server/runOverview.ts"],"names":[],"mappings":"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"}