@ttsc/graph 0.19.2 → 0.20.0

package/src/model/TtscGraphSourceReader.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { type ITtscGraphDump } from "../structures/ITtscGraphDump";
+
+type ReadFile = (file: string) => Buffer;
+
+/**
+ * Immutable, provenance-gated source lines owned by one graph snapshot.
+ *
+ * Signatures and declaration docs are display facts derived from source text,
+ * but the live disk is not the snapshot the checker resolved. A file becomes
+ * readable here only after its current bytes hash to `diskDigest` and the
+ * compiler-decoded text hashes to `checkerDigest`. Both success and failure are
+ * cached, so every consumer of a `TtscGraphMemory` sees one adjudication and
+ * one immutable line array.
+ */
+export class TtscGraphSourceReader {
+  private readonly project: string;
+  private readonly digests: ReadonlyMap<
+    string,
+    { checker: string; disk: string }
+  >;
+  private readonly read: ReadFile;
+  private readonly cache = new Map<string, readonly string[] | undefined>();
+
+  constructor(
+    project: string,
+    provenance:
+      | Pick<ITtscGraphDump.IProvenance, "capabilities" | "sources">
+      | undefined,
+    read: ReadFile = (file) => fs.readFileSync(file),
+  ) {
+    this.project = project;
+    this.read = read;
+    this.digests = new Map(
+      provenance?.capabilities.includes("sourceDigests") === true &&
+        provenance.capabilities.includes("diskDigests") === true
+        ? provenance.sources.map((source) => [
+            normalize(source.file),
+            { checker: source.checkerDigest, disk: source.diskDigest },
+          ])
+        : [],
+    );
+  }
+
+  /**
+   * Return frozen lines only when raw disk bytes and compiler-decoded text both
+   * equal the checker snapshot. A missing manifest entry, read failure, or
+   * digest mismatch is a cached absence rather than a reason to mix current
+   * disk text into old graph facts.
+   */
+  lines(file: string): readonly string[] | undefined {
+    const key = normalize(file);
+    if (this.cache.has(key)) return this.cache.get(key);
+
+    const expected = this.digests.get(key);
+    if (
+      expected === undefined ||
+      expected.checker === "" ||
+      expected.disk === ""
+    ) {
+      this.cache.set(key, undefined);
+      return undefined;
+    }
+
+    let bytes: Buffer;
+    try {
+      bytes = this.read(path.resolve(this.project, file));
+    } catch {
+      this.cache.set(key, undefined);
+      return undefined;
+    }
+    if (sha256(bytes) !== expected.disk) {
+      this.cache.set(key, undefined);
+      return undefined;
+    }
+
+    const text = decodeSource(bytes);
+    if (sha256(text) !== expected.checker) {
+      this.cache.set(key, undefined);
+      return undefined;
+    }
+
+    const lines: readonly string[] = Object.freeze(
+      text.split(/\r\n|[\n\r\u2028\u2029]/u),
+    );
+    this.cache.set(key, lines);
+    return lines;
+  }
+}
+
+function normalize(file: string): string {
+  return file.replace(/\\/g, "/");
+}
+
+function decodeSource(bytes: Buffer): string {
+  if (bytes.length >= 2) {
+    const body = bytes.subarray(2, bytes.length - ((bytes.length - 2) % 2));
+    if (bytes[0] === 0xff && bytes[1] === 0xfe) return body.toString("utf16le");
+    if (bytes[0] === 0xfe && bytes[1] === 0xff)
+      return Buffer.from(body).swap16().toString("utf16le");
+  }
+  if (
+    bytes.length >= 3 &&
+    bytes[0] === 0xef &&
+    bytes[1] === 0xbb &&
+    bytes[2] === 0xbf
+  )
+    return bytes.subarray(3).toString("utf8");
+  return bytes.toString("utf8");
+}
+
+function sha256(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/model/loadGraph.ts

@@ -18,8 +18,13 @@ const MAX_DUMP_BYTES = 1024 * 1024 * 1024;
  * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized,
  * and `dump_schema_version_matches_the_typescript_client_test.go` reads this
  * constant out of this file and fails if the pair drifts.
+ *
+ * Exported because the resident session reads the same dump body over the serve
+ * protocol and has to hold it to the same number: the envelope's version and
+ * the body's are independent, so a producer can speak this protocol and still
+ * send a body from another schema.
  */
-const DUMP_SCHEMA_VERSION = 1;
+export const DUMP_SCHEMA_VERSION = 6;
 
 /**
  * Build the resident {@link TtscGraphMemory} for a project by running `ttscgraph

package/src/reduce.ts

@@ -9,6 +9,7 @@ export interface RawNode {
   kind: string;
   file: string;
   external?: boolean;
+  ignored?: boolean;
 }
 
 export interface RawEdge {
@@ -45,6 +46,7 @@ export interface ViewerPayload {
     nodes: number;
     links: number;
     droppedExternal: number;
+    droppedIgnored: number;
     droppedByCap: number;
   };
   nodes: ViewerNode[];
@@ -55,42 +57,118 @@ function posix(p: string): string {
   return p.replace(/\\/g, "/");
 }
 
-/** An absolute path (POSIX or Windows drive); relative dumps skip rerooting. */
+/** Absolute POSIX, Windows drive, or UNC path; relative dumps skip rerooting. */
 function isAbsolute(p: string): boolean {
   return /^(?:[A-Za-z]:)?\//.test(posix(p));
 }
 
-function commonRoot(files: string[]): string {
-  if (files.length === 0) return "";
-  let parts = posix(files[0]!).split("/");
-  for (const file of files.slice(1)) {
-    const other = posix(file).split("/");
+function isWindowsPath(p: string): boolean {
+  const normalized = posix(p);
+  return /^[A-Za-z]:(?:\/|$)/.test(normalized) || normalized.startsWith("//");
+}
+
+function directoryOf(file: string): string {
+  const normalized = posix(file).replace(/\/+$/, "");
+  const slash = normalized.lastIndexOf("/");
+  if (slash < 0) return "";
+  return slash === 0 ? "/" : normalized.slice(0, slash);
+}
+
+function commonRoot(directories: string[]): string {
+  if (directories.length === 0) return "";
+  let parts = posix(directories[0]!).split("/");
+  const caseInsensitive = directories.every(isWindowsPath);
+  for (const directory of directories.slice(1)) {
+    const other = posix(directory).split("/");
     let i = 0;
-    while (i < parts.length && i < other.length && parts[i] === other[i]) i++;
+    while (
+      i < parts.length &&
+      i < other.length &&
+      (caseInsensitive
+        ? parts[i]!.toLowerCase() === other[i]!.toLowerCase()
+        : parts[i] === other[i])
+    )
+      i++;
     parts = parts.slice(0, i);
     if (parts.length === 0) break;
   }
   return parts.join("/");
 }
 
-// An empty root means the dump's paths are already project-relative (the
-// current `ttscgraph dump` contract); they pass through structure-intact.
-function relativize(abs: string, root: string): string {
+// A null root means the dump's paths are already project-relative (the current
+// `ttscgraph dump` contract); they pass through structure-intact.
+function relativize(abs: string, root: string | null): string {
   const a = posix(abs);
-  const r = posix(root).replace(/\/+$/, "");
-  if (!r) return a;
-  if (a === r || a.startsWith(r + "/"))
+  if (root === null) return a;
+  const normalizedRoot = posix(root);
+  const r = normalizedRoot === "/" ? "/" : normalizedRoot.replace(/\/+$/, "");
+  const caseInsensitive = isWindowsPath(a) && isWindowsPath(r);
+  const comparedPath = caseInsensitive ? a.toLowerCase() : a;
+  const comparedRoot = caseInsensitive ? r.toLowerCase() : r;
+  if (
+    comparedRoot &&
+    (comparedRoot === "/" ||
+      comparedPath === comparedRoot ||
+      comparedPath.startsWith(comparedRoot + "/"))
+  )
     return a.slice(r.length).replace(/^\/+/, "");
   const nm = a.lastIndexOf("node_modules/");
+  // A package tail is a deliberate normalization: the same dependency reached
+  // through two roots is one thing to look at.
   if (nm >= 0) return a.slice(nm);
-  const slash = a.lastIndexOf("/");
-  return slash >= 0 ? a.slice(slash + 1) : a;
+  // Anything else keeps its whole path. Collapsing to the basename made the
+  // projection non-injective, and node ids are rewritten with it, so two
+  // declarations in two files could become one viewer node and an edge could
+  // resolve back to the wrong end. A longer label is a cosmetic cost; a
+  // collided id is a wrong picture.
+  return a;
 }
 
-function rewriteId(id: string, root: string): string {
-  const hash = id.indexOf("#");
+function rewriteId(id: string, root: string | null): string {
+  const hash = graphNodeIdHash(id);
   if (hash < 0) return id;
-  return relativize(id.slice(0, hash), root) + id.slice(hash);
+  return (
+    escapeGraphNodeIdPart(
+      relativize(unescapeGraphNodeIdPart(id.slice(0, hash)), root),
+    ) + id.slice(hash)
+  );
+}
+
+function escapeGraphNodeIdPart(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll("#", "\\#");
+}
+
+function unescapeGraphNodeIdPart(value: string): string {
+  let result = "";
+  for (let index = 0; index < value.length; index++) {
+    const next = value[index + 1];
+    if (value[index] === "\\" && next !== undefined) {
+      if (next === "#" || (next === "\\" && !legacyUNCStart(value, index))) {
+        result += next;
+        index++;
+        continue;
+      }
+    }
+    result += value[index];
+  }
+  return result;
+}
+
+function legacyUNCStart(value: string, index: number): boolean {
+  return (
+    index === 0 && value.length > 2 && value[2] !== "\\" && value[2] !== "#"
+  );
+}
+
+function graphNodeIdHash(id: string): number {
+  for (let index = 0; index < id.length; index++) {
+    if (id[index] !== "#") continue;
+    let slashes = 0;
+    for (let slash = index - 1; slash >= 0 && id[slash] === "\\"; slash--)
+      slashes++;
+    if (slashes % 2 === 0) return index;
+  }
+  return -1;
 }
 
 function degreeOf(
@@ -107,9 +185,9 @@ function degreeOf(
 
 /**
  * Collapse the fine-grained wire kinds `ttscgraph dump` emits (calls,
- * instantiates, renders, accesses, type_ref, extends, implements) into the
- * three display families the viewer colors and its legend name. An unknown kind
- * passes through and renders with the fallback color.
+ * instantiates, renders, accesses, type_ref, extends, implements, overrides)
+ * into the three display families the viewer colors and its legend name. An
+ * unknown kind passes through and renders with the fallback color.
  */
 const DISPLAY_KIND: Record<string, string> = {
   calls: "value-call",
@@ -119,6 +197,7 @@ const DISPLAY_KIND: Record<string, string> = {
   type_ref: "type-ref",
   extends: "heritage",
   implements: "heritage",
+  overrides: "heritage",
 };
 
 function displayKind(kind: string): string {
@@ -130,30 +209,48 @@ export function reduce(
   {
     maxNodes = 1200,
     keepExternal = false,
-  }: { maxNodes?: number; keepExternal?: boolean } = {},
+    keepIgnored = false,
+  }: {
+    maxNodes?: number;
+    keepExternal?: boolean;
+    keepIgnored?: boolean;
+  } = {},
 ): ViewerPayload {
-  const keptByExternal = raw.nodes.filter((n) => keepExternal || !n.external);
+  // Drop external boundary leaves and git-ignored generated code (a Prisma
+  // client and the like, tagged `ignored` by the dump) so the authored graph is
+  // not buried under codegen. The cap is by degree, and generated clients are
+  // large and densely connected, so leaving them in does not merely add noise:
+  // they outrank authored code for the surviving slots.
+  const keep = (n: RawNode) =>
+    (keepExternal || !n.external) && (keepIgnored || !n.ignored);
+  const keptByBoundary = raw.nodes.filter(keep);
   // Reroot only absolute paths (the legacy dump contract); a current dump's
   // paths are already project-relative and keep their structure as-is.
-  const projectFiles = raw.nodes.filter((n) => !n.external).map((n) => n.file);
+  const projectFiles = raw.nodes
+    .filter((n) => !n.external && !n.ignored)
+    .map((n) => n.file);
   const root =
     projectFiles.length > 0 && isAbsolute(projectFiles[0]!)
-      ? commonRoot(projectFiles)
-      : "";
+      ? // A dump may mix path forms from one valid project: in-project sources
+        // are relative, package sources carry a node_modules tail, and other
+        // out-of-project sources stay absolute. Mixing those into one common
+        // root yields the empty string, so only absolute directories vote.
+        commonRoot(projectFiles.filter(isAbsolute).map(directoryOf))
+      : null;
 
-  const liveIds = new Set(keptByExternal.map((n) => n.id));
+  const liveIds = new Set(keptByBoundary.map((n) => n.id));
   const liveEdges = raw.edges.filter(
     (e) => liveIds.has(e.from) && liveIds.has(e.to),
   );
 
-  const degree = degreeOf(keptByExternal, liveEdges);
-  let kept = keptByExternal;
+  const degree = degreeOf(keptByBoundary, liveEdges);
+  let kept = keptByBoundary;
   let droppedByCap = 0;
   if (kept.length > maxNodes) {
     kept = [...kept]
       .sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0))
       .slice(0, maxNodes);
-    droppedByCap = keptByExternal.length - kept.length;
+    droppedByCap = keptByBoundary.length - kept.length;
   }
 
   const keptIds = new Set(kept.map((n) => n.id));
@@ -188,7 +285,15 @@ export function reduce(
       rawEdges: raw.edges.length,
       nodes: nodes.length,
       links: links.length,
-      droppedExternal: raw.nodes.length - keptByExternal.length,
+      // Each counter reports what its own filter dropped, and reports zero when
+      // that filter was turned off. The two are disjoint: an external node is
+      // counted as external whether or not it is also ignored.
+      droppedExternal: keepExternal
+        ? 0
+        : raw.nodes.filter((n) => n.external).length,
+      droppedIgnored: keepIgnored
+        ? 0
+        : raw.nodes.filter((n) => n.ignored && !n.external).length,
       droppedByCap,
     },
     nodes,

package/src/resolveGraphBinary.ts

@@ -5,9 +5,15 @@ import path from "node:path";
  * Resolve the per-platform `ttscgraph` binary, or `null` when it cannot be
  * located.
  *
- * `ttsc` is a peer the user installs alongside `@ttsc/graph` (not a dependency
- * of this launcher), so resolution starts from the user's project, not from
- * this package's own tree.
+ * `ttsc` is a peer dependency pinned to this package's own version, installed
+ * alongside `@ttsc/graph` in the user's project rather than nested under this
+ * launcher, so resolution starts from the user's project, not from this
+ * package's own tree.
+ *
+ * The pin is what keeps the two halves of the graph in step. `literals` and the
+ * rest of the node facts are resolved by the Go builder and ride the dump, so a
+ * newer `@ttsc/graph` reading an older `ttscgraph` would find those fields
+ * simply absent and answer from a graph missing facts it believes are there.
  *
  * Resolution order:
  *

package/src/server/createServer.ts

@@ -28,11 +28,21 @@ export function createServer(
   graph: TtscGraphSource,
   version: string,
 ): McpServer {
-  void version;
-  return createMcpServer(
+  const server = createMcpServer(
     typia.llm.controller<ITtscGraphApplication>(
       "ttsc-graph",
       new TtscGraphApplication(graph),
     ),
   );
+  // @typia/mcp 13.1.0 exposes no class-controller version option. The MCP SDK
+  // keeps the initialize implementation on its public inner Server, so update
+  // that already-constructed implementation before any transport connects.
+  const inner = server.server as unknown as {
+    _serverInfo?: { version: string };
+  };
+  if (inner._serverInfo === undefined) {
+    throw new Error("@ttsc/graph: MCP SDK omitted the server implementation");
+  }
+  inner._serverInfo.version = version;
+  return server;
 }

package/src/server/pathPolicy.ts

@@ -9,6 +9,15 @@ export function isExternalNode(node: ITtscGraphNode): boolean {
   );
 }
 
+/**
+ * True for a `.d.ts` declaration file. Every declaration such a file holds is
+ * ambient by construction, so none of them carries a body the graph can walk
+ * into, whether or not the `declare` keyword is written out.
+ */
+export function isDeclarationFile(file: string): boolean {
+  return /\.d\.[cm]?ts$/.test(file);
+}
+
 /** True for tests, examples, fixtures, generated output, and build artifacts. */
 export function isSupportPath(file: string): boolean {
   return (
@@ -20,7 +29,7 @@ export function isSupportPath(file: string): boolean {
     ) ||
     /\.(test|spec)\.[cm]?tsx?$/.test(file) ||
     /(^|\/)typings\.[cm]?ts$/.test(file) ||
-    /\.d\.[cm]?ts$/.test(file) ||
+    isDeclarationFile(file) ||
     /(^|\/)(dist|build|coverage|generated|__generated__)\//.test(file)
   );
 }

package/src/server/resolveHandle.ts

@@ -1,4 +1,5 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { parseTtscGraphNodeId } from "../model/TtscGraphNodeId";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { exportFanIn } from "./exportSurface";
 import { isSupportPath } from "./pathPolicy";
@@ -42,21 +43,17 @@ export function resolveGraphHandle(
   const byId = graph.node(handle);
   if (byId !== undefined) return { node: byId };
 
-  const byName = resolveGraphName(graph, handle, candidateLimit);
+  const byName = resolveGraphName(graph, handle);
   if (byName.node !== undefined || byName.candidates !== undefined)
     return rank(graph, byName, candidateLimit);
 
-  const byFile = resolveFileQualified(graph, handle, candidateLimit);
+  const byFile = resolveFileQualified(graph, handle);
   if (byFile.node !== undefined || byFile.candidates !== undefined)
     return rank(graph, byFile, candidateLimit);
 
   const symbol = symbolPartOf(handle) ?? memberPartOf(handle);
   if (symbol !== undefined)
-    return rank(
-      graph,
-      resolveGraphName(graph, symbol, candidateLimit),
-      candidateLimit,
-    );
+    return rank(graph, resolveGraphName(graph, symbol), candidateLimit);
   return {};
 }
 
@@ -77,22 +74,16 @@ function memberPartOf(handle: string): string | undefined {
 
 /** The symbol an id-shaped handle names: `dir/file.ts#Class.method:kind`. */
 function symbolPartOf(handle: string): string | undefined {
-  const hash = handle.lastIndexOf("#");
-  if (hash < 0) return undefined;
-  const symbol = handle.slice(hash + 1);
-  const kind = symbol.lastIndexOf(":");
-  const name = kind < 0 ? symbol : symbol.slice(0, kind);
-  return name.length > 0 ? name : undefined;
+  return parseTtscGraphNodeId(handle)?.name;
 }
 
 function resolveGraphName(
   graph: TtscGraphMemory,
   name: string,
-  candidateLimit: number,
 ): IResolvedGraphHandle {
   const exact = graph.symbols(name);
   if (exact.length === 1) return { node: exact[0] };
-  if (exact.length > 1) return { candidates: exact.slice(0, candidateLimit) };
+  if (exact.length > 1) return { candidates: [...exact] };
 
   if (name.includes(".")) {
     const suffix = `.${name}`;
@@ -102,7 +93,7 @@ function resolveGraphName(
     );
     if (suffixMatches.length === 1) return { node: suffixMatches[0] };
     if (suffixMatches.length > 1) {
-      return { candidates: suffixMatches.slice(0, candidateLimit) };
+      return { candidates: suffixMatches };
     }
   }
   return {};
@@ -117,7 +108,6 @@ function resolveGraphName(
 function resolveFileQualified(
   graph: TtscGraphMemory,
   handle: string,
-  candidateLimit: number,
 ): IResolvedGraphHandle {
   const dot = handle.indexOf(".");
   if (dot <= 0) return {};
@@ -128,8 +118,7 @@ function resolveFileQualified(
     .symbols(name)
     .filter((node) => fileStem(node.file) === stem);
   if (matches.length === 1) return { node: matches[0] };
-  if (matches.length > 1)
-    return { candidates: matches.slice(0, candidateLimit) };
+  if (matches.length > 1) return { candidates: matches };
   return {};
 }
 
@@ -153,12 +142,22 @@ function rank(
   candidateLimit: number,
 ): IResolvedGraphHandle {
   if (resolved.candidates === undefined) return resolved;
-  const ranked = [...resolved.candidates]
-    .sort((a, b) => candidateScore(graph, b) - candidateScore(graph, a))
-    .slice(0, candidateLimit);
+  const ranked = resolved.candidates
+    .map((node) => ({ node, score: candidateScore(graph, node) }))
+    .sort((a, b) => {
+      const score = b.score - a.score;
+      return score !== 0 ? score : compareIdentity(a.node.id, b.node.id);
+    })
+    .slice(0, candidateLimit)
+    .map(({ node }) => node);
   return { candidates: ranked };
 }
 
+/** Compare position-invariant ids without locale-dependent collation. */
+function compareIdentity(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 function candidateScore(graph: TtscGraphMemory, node: ITtscGraphNode): number {
   let score = Math.min(48, Math.log2(1 + exportFanIn(graph, node.id)) * 20);
   if (node.exported) score += 12;