@ttsc/graph 0.16.5 → 0.16.6

package/src/server/instructions.ts

@@ -4,25 +4,73 @@
  * files. Keep it short; the per-tool descriptions carry the detail.
  */
 export const 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.
+Before answering a TypeScript codebase question, call query. It is the
+code-evidence path:
+symbols, dependency paths, edge evidence ranges, and sourceSpan line anchors
+from the resident project graph. Do not answer from assumptions, ls, rg, cat,
+or Get-Content when graph evidence can answer the code question.
+
+The graph is a resident TypeScript fact map, not an answer writer. Fill
+arguments in order: question, graphNeed, draft, review, request. Write
+draft.reason before draft.type, review it for overfetch and non-graph fallback,
+then choose one final request.type:
+entrypoints, lookup, trace, details, overview, or escape. If the review shows the
+question is about scripts, config, generated output, prose docs, or evidence
+already in hand, choose escape instead of spending a graph
+operation. If more TypeScript evidence is needed, make another graph request
+instead of switching to shell search.
+
+Budget graph calls before the first request. Most answers need 1-3 calls, and
+four calls is the hard stop for one answer. A fifth graph call means the tool is
+being used as a source reader; answer from returned handles/ranges or choose
+escape and report the missing span.
+
+For behavior, lifecycle, request-flow, rendering-flow, or validation-flow
+questions, start with one default entrypoints call, then one trace from the best
+handle, then answer. Use overview only for broad architecture or public API
+orientation.
+
+The graph already knows resolved symbols, dependency edges, evidence spans,
+decorators, stable handles, and sourceSpan line anchors. Use returned ranges and
+handles as the evidence. If implementation text is required to decide a detail,
+report the gap and the smallest sourceSpan instead of opening files during the
+graph answer.
+
+For caller or call-site questions, do not use rg. Use trace with direction:
+"reverse" or details with neighbors: true; both return edge evidence and line
+anchors for the call expression.
+
+Request types:
+
+- entrypoints: compact shortlist for behavior-specific code questions. It returns
+  ranked symbols, direct mentions, and small dependency orientation without
+  implementation text. Do not use it as the first broad public API map.
+- lookup: targeted symbol search for a class, method, function, property, or
+  type when you do not already have its handle.
+- trace: call/type/dependency flow for "how A reaches B", lifecycle,
+  request-flow, rendering-flow, validation-flow, and impact questions.
+- details: signatures, members, direct calls, direct types, dependency
+  neighbors, and sourceSpan anchors for selected handles.
+- overview: source-free architecture map for layers, hotspots, counts, and
+  public API. Use it to choose a central exported TypeScript API or entry point
+  without reading package scripts.
+- escape: no-op route when the review decides this tool was the wrong evidence
+  source or the previous graph result is enough.
+
+For a flow question, use entrypoints once, then trace before details. Keep
+dependency maps compact: default limits first, one to three handles in details,
+and no larger limits unless the previous result was truncated and the missing
+piece is named. Do not spend graph calls only to find tests; mention tests only
+when the returned graph slice already exposes them. Stop once file/symbol/range
+evidence is enough to answer.
+
+Copy exact names from returned nodes, references, aliases, evidence ranges,
+sourceSpan anchors, and trace steps. Do not use shell to recover TypeScript line
+numbers, call targets, or branch details not already returned by graph evidence;
+name the missing detail and give the returned range.
+
+Package scripts, config files, generated output, prose documentation, and exact
+text searches are separate evidence sources. Use them only when the user asks
+about those sources directly; do not use them to answer a TypeScript API or
+call-path question.
 `.trim();

package/src/server/runDetails.ts

@@ -0,0 +1,469 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphDecorator } from "../structures/ITtscGraphDecorator";
+import { ITtscGraphDetails } from "../structures/ITtscGraphDetails";
+import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
+import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { accessAliasesFor } from "./accessAliases";
+import { resolveGraphHandle } from "./resolveHandle";
+
+// A signature is the declaration head up to the body brace: a handful of lines.
+const MAX_SIGNATURE_LINES = 4;
+// Neighbor lists are a map, not a dump; keep them scannable.
+const DEFAULT_NEIGHBORS = 2;
+const MAX_NEIGHBORS = 3;
+// A container outline can be long; default to a scannable first page.
+const DEFAULT_MEMBERS = 6;
+const MAX_MEMBERS = 8;
+// Direct dependency groups are orientation slices, not full fan-out dumps.
+const DEFAULT_DEPENDENCIES = 1;
+const MAX_DEPENDENCIES = 2;
+// Object literal outlines are navigation aids, not source excerpts.
+const MAX_OBJECT_MEMBER_LINES = 300;
+// Structural relationships are navigation, not the dependency picture details is for.
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+// Kinds whose value is their member outline, not implementation text.
+const CONTAINER_KINDS = new Set<string>([
+  "class",
+  "interface",
+  "namespace",
+  "module",
+  "enum",
+  "file",
+]);
+
+/**
+ * Resolve each handle to its declared shape: sourceSpan anchors, signature,
+ * direct dependencies, and for containers, member outlines. It answers from the
+ * graph's resolved structure instead of inlining implementation bodies.
+ */
+export function runDetails(
+  graph: TtscGraphMemory,
+  props: ITtscGraphDetails.IRequest,
+): ITtscGraphDetails {
+  const neighborLimit = bound(
+    props.neighborLimit,
+    DEFAULT_NEIGHBORS,
+    1,
+    MAX_NEIGHBORS,
+  );
+  const memberLimit = bound(props.memberLimit, DEFAULT_MEMBERS, 1, MAX_MEMBERS);
+  const dependencyLimit = bound(
+    props.dependencyLimit,
+    DEFAULT_DEPENDENCIES,
+    1,
+    MAX_DEPENDENCIES,
+  );
+  const wantNeighbors = props.neighbors === true;
+  const nodes: ITtscGraphDetails.INode[] = [];
+  const unknown: string[] = [];
+  for (const handle of props.handles) {
+    const resolved = resolveGraphHandle(graph, handle);
+    if (resolved.node === undefined) {
+      unknown.push(handle);
+      continue;
+    }
+    const node = resolved.node;
+    const detail: ITtscGraphDetails.INode = {
+      id: node.id,
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+    };
+    if (node.evidence?.startLine) detail.line = node.evidence.startLine;
+    const sig = signatureOf(graph.project, node);
+    if (sig !== undefined) detail.signature = sig;
+    const signatureLiterals = literalSummaries(sig);
+    const decorators = decoratorsOf(node);
+    if (decorators !== undefined) detail.decorators = decorators;
+    const implementation = evidenceCoordinatesOf(node.implementation);
+    if (implementation !== undefined) detail.implementation = implementation;
+    const span = implementation ?? evidenceCoordinatesOf(node.evidence);
+    if (span !== undefined) {
+      detail.sourceSpan = {
+        file: span.file,
+        startLine: span.startLine,
+        endLine: span.endLine,
+      };
+    }
+    const calls = dependencyRefs(graph, node, executionKinds, dependencyLimit);
+    if (calls.length > 0) detail.calls = calls;
+    const types = dependencyRefs(graph, node, typeKinds, dependencyLimit);
+    if (types.length > 0) detail.types = types;
+    if (CONTAINER_KINDS.has(node.kind)) {
+      const list = members(graph, node, memberLimit);
+      if (list.length > 0) detail.members = list;
+    }
+    if (node.kind === "variable" && detail.sourceSpan !== undefined) {
+      const list = objectLiteralMembers(
+        graph.project,
+        detail.sourceSpan,
+        memberLimit,
+      );
+      if (list.length > 0) detail.members = list;
+    }
+    if (signatureLiterals.length > 0)
+      detail.literals = signatureLiterals.slice(0, 6);
+    if (wantNeighbors) {
+      detail.dependsOn = refs(
+        graph,
+        graph.outgoing(node.id),
+        "to",
+        neighborLimit,
+      );
+      detail.dependedOnBy = refs(
+        graph,
+        graph.incoming(node.id),
+        "from",
+        neighborLimit,
+      );
+    }
+    nodes.push(detail);
+  }
+  return { type: "details", nodes, unknown };
+}
+
+/** The members a container owns (via `contains`), each with its own signature. */
+function members(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+  limit: number,
+): ITtscGraphDetails.IMember[] {
+  const out: ITtscGraphDetails.IMember[] = [];
+  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: ITtscGraphDetails.IMember = {
+      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;
+    const decorators = decoratorsOf(member);
+    if (decorators !== undefined) m.decorators = decorators;
+    out.push(m);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+function objectLiteralMembers(
+  project: string,
+  span: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">,
+  limit: number,
+): ITtscGraphDetails.IMember[] {
+  if (span.endLine === undefined) return [];
+  if (span.endLine - span.startLine > MAX_OBJECT_MEMBER_LINES) return [];
+  const lines = fileLines(project, span.file);
+  if (lines === undefined) return [];
+  const start = Math.max(0, span.startLine - 1);
+  const end = Math.min(lines.length - 1, span.endLine - 1);
+  const members: ITtscGraphDetails.IMember[] = [];
+  let depth = 0;
+  let entered = false;
+  for (let i = start; i <= end; i++) {
+    const raw = lines[i] ?? "";
+    const text = stripStrings(raw);
+    const before = depth;
+    if (entered && before === 1) {
+      const member = objectMemberOf(raw, i + 1);
+      if (member !== undefined) {
+        members.push(member);
+        if (members.length >= limit) break;
+      }
+    }
+    for (const char of text) {
+      if (char === "{") {
+        depth++;
+        entered = true;
+      } else if (char === "}") {
+        depth = Math.max(0, depth - 1);
+      }
+    }
+  }
+  return members;
+}
+
+function objectMemberOf(
+  line: string,
+  lineNumber: number,
+): ITtscGraphDetails.IMember | undefined {
+  const text = line.trim();
+  if (
+    text === "" ||
+    text.startsWith("//") ||
+    text.startsWith("/*") ||
+    text.startsWith("*")
+  ) {
+    return undefined;
+  }
+  const property = /^(['"]?)([A-Za-z_$][\w$-]*)\1\s*\??\s*:/.exec(text);
+  if (property !== null) {
+    return {
+      name: property[2]!,
+      kind: "property",
+      line: lineNumber,
+      signature: signatureLine(text),
+    };
+  }
+  const method =
+    /^(?:async\s+)?(?:get\s+|set\s+)?([A-Za-z_$][\w$-]*)\s*\(/.exec(text);
+  if (method !== null) {
+    return {
+      name: method[1]!,
+      kind: "method",
+      line: lineNumber,
+      signature: signatureLine(text),
+    };
+  }
+  return undefined;
+}
+
+function signatureLine(text: string): string {
+  return text.replace(/\s+/g, " ").replace(/,$/, "");
+}
+
+function stripStrings(line: string): string {
+  return line.replace(/\/\/.*$/, "").replace(/(['"`])(?:\\.|(?!\1).)*\1/g, "");
+}
+
+/** Map dependency edges to references on their far endpoint, dropping structure. */
+function refs(
+  graph: TtscGraphMemory,
+  edges: readonly ITtscGraphEdge[],
+  end: "to" | "from",
+  limit: number,
+): ITtscGraphDetails.IReference[] {
+  const ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }> = [];
+  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;
+    const ref: ITtscGraphDetails.IReference = {
+      id: other.id,
+      name: other.qualifiedName ?? other.name,
+      kind: other.kind,
+      file: other.file,
+      relation: edge.kind,
+    };
+    if (other.evidence?.startLine) ref.line = other.evidence.startLine;
+    const evidence = edgeEvidenceOf(edge);
+    if (evidence !== undefined) ref.evidence = evidence;
+    const aliases = accessAliasesFor(other, edgeEvidenceTextOf(edge));
+    if (aliases !== undefined) ref.aliases = aliases;
+    ranked.push({ ref, rank: refRank(ref, edge) });
+  }
+  ranked.sort((a, b) => a.rank - b.rank);
+  const out: ITtscGraphDetails.IReference[] = [];
+  for (const item of ranked) {
+    out.push(item.ref);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+const executionKinds = new Set([
+  "calls",
+  "instantiates",
+  "accesses",
+  "renders",
+]);
+const typeKinds = new Set(["type_ref", "extends", "implements", "overrides"]);
+
+function dependencyRefs(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+  kinds: ReadonlySet<string>,
+  limit: number,
+): ITtscGraphDetails.IReference[] {
+  const ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }> = [];
+  for (const edge of graph.outgoing(node.id)) {
+    if (!kinds.has(edge.kind)) continue;
+    const other = graph.node(edge.to);
+    if (other === undefined || other.kind === "file") continue;
+    const name = other.qualifiedName ?? other.name;
+    const ref: ITtscGraphDetails.IReference = {
+      id: other.id,
+      name,
+      kind: other.kind,
+      file: other.file,
+      relation: edge.kind,
+    };
+    if (other.evidence?.startLine) ref.line = other.evidence.startLine;
+    const evidence = edgeEvidenceOf(edge);
+    if (evidence !== undefined) ref.evidence = evidence;
+    const aliases = accessAliasesFor(other, edgeEvidenceTextOf(edge));
+    if (aliases !== undefined) ref.aliases = aliases;
+    ranked.push({
+      ref,
+      rank: refRank(ref, edge),
+    });
+  }
+  ranked.sort((a, b) => a.rank - b.rank);
+  const out: ITtscGraphDetails.IReference[] = [];
+  const seen = new Set<string>();
+  for (const item of ranked) {
+    const key = `${item.ref.relation}:${item.ref.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item.ref);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+function literalSummaries(text: string | undefined): string[] {
+  if (text === undefined) return [];
+  const out: string[] = [];
+  for (const match of text.matchAll(/(["'`])((?:\\.|(?!\1).){1,80})\1/g)) {
+    const value = cleanLiteral(match[2]);
+    if (value !== undefined && !out.includes(value)) out.push(value);
+    if (out.length >= 20) break;
+  }
+  return out;
+}
+
+function cleanLiteral(value: string | undefined): string | undefined {
+  const text = value?.replace(/\s+/g, " ").trim();
+  if (
+    text === undefined ||
+    text === "" ||
+    text.length > 40 ||
+    /^[{}()[\],.:;]+$/.test(text)
+  ) {
+    return undefined;
+  }
+  return text;
+}
+
+function bound(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const n = value === undefined || !Number.isFinite(value) ? fallback : value;
+  return Math.max(min, Math.min(max, Math.floor(n)));
+}
+
+function refRank(
+  ref: ITtscGraphDetails.IReference,
+  edge: ITtscGraphEdge,
+): number {
+  return (
+    edgeKindRank(edge.kind) * 100_000 +
+    evidenceRank(edge) +
+    (ref.file.startsWith("bundled://") ? 20_000 : 0)
+  );
+}
+
+function evidenceRank(edge: ITtscGraphEdge): number {
+  const line = edge.evidence?.startLine ?? 9_999;
+  const col = edge.evidence?.startCol ?? 999;
+  return line * 100 + col;
+}
+
+function edgeKindRank(kind: string): number {
+  switch (kind) {
+    case "calls":
+      return 0;
+    case "instantiates":
+      return 1;
+    case "accesses":
+    case "renders":
+      return 2;
+    case "tests":
+      return 3;
+    case "overrides":
+    case "decorates":
+      return 4;
+    case "extends":
+    case "implements":
+      return 5;
+    case "type_ref":
+      return 6;
+    default:
+      return 10;
+  }
+}
+
+/** Decorator facts already captured on a node, omitted when absent. */
+export function decoratorsOf(
+  node: ITtscGraphNode,
+): ITtscGraphDecorator[] | undefined {
+  return node.decorators !== undefined && node.decorators.length > 0
+    ? node.decorators
+    : undefined;
+}
+
+/** Relationship evidence as public coordinates, omitted when absent. */
+export function edgeEvidenceOf(
+  edge: ITtscGraphEdge,
+): ITtscGraphEvidence | undefined {
+  return evidenceCoordinatesOf(edge.evidence);
+}
+
+function evidenceCoordinatesOf(
+  evidence: ITtscGraphEvidence | undefined,
+): ITtscGraphEvidence | undefined {
+  if (evidence === undefined) return undefined;
+  return {
+    file: evidence.file,
+    startLine: evidence.startLine,
+    ...(evidence.startCol !== undefined ? { startCol: evidence.startCol } : {}),
+    ...(evidence.endLine !== undefined ? { endLine: evidence.endLine } : {}),
+    ...(evidence.endCol !== undefined ? { endCol: evidence.endCol } : {}),
+  };
+}
+
+/** Source text is an internal alias hint, not part of the MCP evidence object. */
+export function edgeEvidenceTextOf(edge: ITtscGraphEdge): string | undefined {
+  const text = (
+    edge.evidence as (ITtscGraphEvidence & { text?: string }) | undefined
+  )?.text;
+  return typeof text === "string" && text.length > 0 ? text : undefined;
+}
+
+/** Read a file's lines once, or undefined when it cannot be read. */
+function fileLines(project: string, file: string): string[] | undefined {
+  if (file === "") return undefined;
+  try {
+    return fs.readFileSync(path.join(project, 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.
+ */
+export function signatureOf(
+  project: string,
+  node: ITtscGraphNode,
+): string | undefined {
+  const evidence = node.evidence;
+  const lines =
+    evidence === undefined ? undefined : fileLines(project, evidence.file);
+  if (lines === undefined || evidence === undefined) return undefined;
+  const start = Math.max(0, evidence.startLine - 1);
+  const out: string[] = [];
+  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;
+}