@mrciphersmith/keryx 0.2.9

package/src/gdgraph/treesitter/adapter.test.ts

@@ -0,0 +1,249 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { createTreesitterSpec, type BuildInput } from "./adapter";
+import type { TsNode } from "./extract";
+import { enrichBuildWithSymbols } from "../enrich";
+import type { CallEdge, SymbolLayer, SymbolNode } from "../types";
+
+// --- tiny structural mock tree: one top-level function `boot` that calls `tick` ---
+function mk(o: {
+  type: string;
+  line?: number;
+  endLine?: number;
+  text?: string;
+  fields?: Record<string, TsNode | null>;
+  namedChildren?: TsNode[];
+}): TsNode {
+  const line = o.line ?? 1;
+  const named = o.namedChildren ?? [];
+  return {
+    type: o.type,
+    text: o.text ?? "",
+    startPosition: { row: line - 1, column: 0 },
+    endPosition: { row: (o.endLine ?? line) - 1, column: 0 },
+    childForFieldName: (field: string) => o.fields?.[field] ?? null,
+    namedChildren: named,
+    children: named,
+  };
+}
+
+function bootTree(): TsNode {
+  const id = (t: string) => mk({ type: "identifier", text: t });
+  const body = mk({
+    type: "statement_block",
+    line: 1,
+    namedChildren: [mk({ type: "call_expression", line: 1, fields: { function: id("tick") }, text: "tick()" })],
+  });
+  const boot = mk({
+    type: "function_declaration",
+    line: 1,
+    endLine: 2,
+    fields: { name: id("boot"), parameters: mk({ type: "formal_parameters", text: "()" }) },
+    namedChildren: [body],
+  });
+  const tick = mk({
+    type: "function_declaration",
+    line: 3,
+    endLine: 3,
+    fields: { name: id("tick"), parameters: mk({ type: "formal_parameters", text: "()" }) },
+  });
+  return mk({ type: "program", line: 1, endLine: 3, namedChildren: [boot, tick] });
+}
+
+// A structural mock of the `web-tree-sitter` module (a Parser constructor with
+// static `init` + `Language.load`). Parse always returns the bootTree.
+function mockParserModule(): unknown {
+  function MockParser(this: unknown) {}
+  (MockParser as unknown as { init: () => Promise<void> }).init = async () => {};
+  (MockParser as unknown as { Language: { load: (p: string) => Promise<unknown> } }).Language = {
+    load: async () => ({}),
+  };
+  MockParser.prototype.setLanguage = function setLanguage(): void {};
+  MockParser.prototype.parse = function parse(): { rootNode: TsNode } {
+    return { rootNode: bootTree() };
+  };
+  return MockParser;
+}
+
+// Create a temp workspace whose lockfile pins a real on-disk grammar file so the
+// Asset Resolver verifies it (availability-true), with a config grammarsPath (T1).
+async function makeWorkspaceWithGrammar(): Promise<{ root: string; grammarsDir: string }> {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-ts-"));
+  const grammarsDir = path.join(root, "grammars");
+  await mkdir(path.join(root, ".metaproject"), { recursive: true });
+  await mkdir(grammarsDir, { recursive: true });
+  const wasmPath = path.join(grammarsDir, "tree-sitter-typescript.wasm");
+  const bytes = Buffer.from("fake-grammar-bytes");
+  await writeFile(wasmPath, bytes);
+  const sha = createHash("sha256").update(bytes).digest("hex");
+  await writeFile(
+    path.join(root, ".metaproject", "assets.lock.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      assets: {
+        "tree-sitter-typescript": {
+          version: "0.22.0",
+          url: "https://example.dev/tree-sitter-typescript.wasm",
+          sha256: sha,
+          size: bytes.length,
+        },
+      },
+    }),
+  );
+  return { root, grammarsDir };
+}
+
+test("AC5.2 availability-true — adapter isAvailable + run() yields the symbol layer", async () => {
+  const { root, grammarsDir } = await makeWorkspaceWithGrammar();
+  try {
+    const spec = createTreesitterSpec(root, { languages: ["typescript"], grammarsPath: grammarsDir });
+    const adapter = spec.load({ dep: mockParserModule(), asset: null });
+
+    expect(await adapter.isAvailable()).toBe(true);
+
+    const layer = await adapter.run({ files: [{ path: "src/boot.ts", content: "ignored-by-mock" }] });
+    const symbolIds = layer.symbols.map((symbol: SymbolNode) => symbol.id).sort();
+    expect(symbolIds).toEqual(["src/boot.ts#boot", "src/boot.ts#tick"]);
+    const callKinds = layer.calls.map((call: CallEdge) => `${call.kind}:${call.from}=>${call.to}`);
+    expect(callKinds).toContain("calls:src/boot.ts#boot=>src/boot.ts#tick");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC5.2 availability-false — no grammar ⇒ isAvailable false", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-ts-none-"));
+  try {
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    const spec = createTreesitterSpec(root, { languages: ["typescript"], grammarsPath: null });
+    const adapter = spec.load({ dep: mockParserModule(), asset: null });
+    expect(await adapter.isAvailable()).toBe(false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("availability-false — missing dep ⇒ isAvailable false", async () => {
+  const { root, grammarsDir } = await makeWorkspaceWithGrammar();
+  try {
+    const spec = createTreesitterSpec(root, { languages: ["typescript"], grammarsPath: grammarsDir });
+    const adapter = spec.load({ dep: undefined, asset: null });
+    expect(await adapter.isAvailable()).toBe(false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC1.1 additive write path — enrich writes symbols.jsonl + calls.jsonl via a mock adapter", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-enrich-"));
+  try {
+    await mkdir(path.join(root, ".metaproject", "data", "gdgraph", "storage"), { recursive: true });
+    const expectedLayer: SymbolLayer = {
+      symbols: [
+        {
+          id: "src/x.ts#run",
+          kind: "function",
+          path: "src/x.ts",
+          name: "run",
+          container: null,
+          startLine: 1,
+          endLine: 1,
+          language: "typescript",
+          signature: "run()",
+        },
+      ],
+      calls: [{ id: "defines:src/x.ts=>src/x.ts#run", from: "src/x.ts", to: "src/x.ts#run", kind: "defines", resolved: true }],
+    };
+
+    const injected = async () => ({
+      id: "gdgraph.treesitter",
+      isAvailable: async () => true,
+      run: async (_input: BuildInput) => expectedLayer,
+    });
+
+    const result = await enrichBuildWithSymbols(root, [{ path: "src/x.ts", content: "" }], injected);
+    expect(result.enriched).toBe(true);
+    expect(result.symbols).toBe(1);
+
+    const storage = path.join(root, ".metaproject", "data", "gdgraph", "storage");
+    const symbolsFile = await readFile(path.join(storage, "symbols.jsonl"), "utf8");
+    const callsFile = await readFile(path.join(storage, "calls.jsonl"), "utf8");
+    expect(symbolsFile.trim()).toBe(JSON.stringify(expectedLayer.symbols[0]));
+    expect(callsFile.trim()).toBe(JSON.stringify(expectedLayer.calls[0]));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Java grammar resolution — grammarForFile selects java for .java files", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-java-"));
+  try {
+    const grammarsDir = path.join(root, "grammars");
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    await mkdir(grammarsDir, { recursive: true });
+
+    const wasmPath = path.join(grammarsDir, "tree-sitter-java.wasm");
+    const bytes = Buffer.from("fake-java-grammar");
+    await writeFile(wasmPath, bytes);
+    const sha = createHash("sha256").update(bytes).digest("hex");
+
+    await writeFile(
+      path.join(root, ".metaproject", "assets.lock.json"),
+      JSON.stringify({
+        schemaVersion: 1,
+        assets: {
+          "tree-sitter-java": {
+            version: "0.1.13",
+            url: "https://example.dev/tree-sitter-java.wasm",
+            sha256: sha,
+            size: bytes.length,
+          },
+        },
+      }),
+    );
+
+    const spec = createTreesitterSpec(root, { languages: ["java"], grammarsPath: grammarsDir });
+    const adapter = spec.load({ dep: mockParserModule(), asset: null });
+    expect(await adapter.isAvailable()).toBe(true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Python grammar resolution — grammarForFile selects python for .py files", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-python-"));
+  try {
+    const grammarsDir = path.join(root, "grammars");
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    await mkdir(grammarsDir, { recursive: true });
+
+    const wasmPath = path.join(grammarsDir, "tree-sitter-python.wasm");
+    const bytes = Buffer.from("fake-python-grammar");
+    await writeFile(wasmPath, bytes);
+    const sha = createHash("sha256").update(bytes).digest("hex");
+
+    await writeFile(
+      path.join(root, ".metaproject", "assets.lock.json"),
+      JSON.stringify({
+        schemaVersion: 1,
+        assets: {
+          "tree-sitter-python": {
+            version: "0.1.13",
+            url: "https://example.dev/tree-sitter-python.wasm",
+            sha256: sha,
+            size: bytes.length,
+          },
+        },
+      }),
+    );
+
+    const spec = createTreesitterSpec(root, { languages: ["python"], grammarsPath: grammarsDir });
+    const adapter = spec.load({ dep: mockParserModule(), asset: null });
+    expect(await adapter.isAvailable()).toBe(true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/treesitter/adapter.ts

@@ -0,0 +1,213 @@
+// Tree-sitter capability adapter (specification.md §7, §8.1; T-B12).
+//
+// Implements the Block 0 `CapabilityAdapter<BuildInput, SymbolLayer>`:
+//   isAvailable() = `web-tree-sitter` imports AND ≥1 configured grammar resolves
+//                   + verifies via the Asset Resolver.
+//   run()         = parse each source file and emit a sorted, stable SymbolLayer.
+//
+// This is the ONLY module in `src/` that loads `web-tree-sitter`, and it does so
+// exclusively via `await import()` (C0-2, AC1.5 — enforced by the static guard).
+// It NEVER throws out (C0-11): every parse error is caught and the file is
+// skipped, so an opt-in ceiling can never break the deterministic seam.
+
+import type { CapabilityAdapter, CapabilitySpec } from "../../capability/seam";
+import type { CallEdge, SymbolLayer, SymbolNode } from "../types";
+import { extractSymbolLayer, resolveCrossFileCalls, type TsNode } from "./extract";
+import {
+  grammarForFile,
+  resolveGrammars,
+  symbolLanguage,
+  toGrammarLanguages,
+  type GrammarLanguage,
+  type ResolvedGrammar,
+} from "./grammars";
+
+export interface FileRecord {
+  path: string;
+  content: string;
+}
+
+export interface BuildInput {
+  files: FileRecord[];
+}
+
+export interface TreesitterAdapterConfig {
+  languages: string[];
+  grammarsPath: string | null;
+}
+
+// Minimal shapes of the `web-tree-sitter` surface we touch (kept local so the
+// dep is never imported for types either — structural typing only).
+interface ParserLike {
+  setLanguage(language: unknown): void;
+  parse(input: string): { rootNode: TsNode } | null;
+}
+// Version-tolerant view over the two shipped APIs:
+//   0.22 — default export is the Parser class; `Parser.Language.load`, `Parser.init`.
+//   0.25 — named `Parser` + top-level `Language.load`; no default export.
+interface ParserApi {
+  init?: () => Promise<void>;
+  loadLanguage: (pathOrBytes: string) => Promise<unknown>;
+  create: () => ParserLike;
+}
+
+// Build the capability spec for `resolveCapability(cwd, spec)`. Dep-only gate at
+// the seam; grammar resolution happens inside `isAvailable()` because the layer
+// spans multiple grammar assets (one per language).
+export function createTreesitterSpec(
+  cwd: string,
+  config: TreesitterAdapterConfig,
+): CapabilitySpec<BuildInput, SymbolLayer> {
+  return {
+    id: "gdgraph.treesitter",
+    optionalDependency: "web-tree-sitter",
+    load: (ctx) => new TreesitterAdapter(cwd, config, ctx.dep),
+  };
+}
+
+class TreesitterAdapter implements CapabilityAdapter<BuildInput, SymbolLayer> {
+  readonly id = "gdgraph.treesitter";
+  private grammars: ResolvedGrammar[] = [];
+
+  constructor(
+    private readonly cwd: string,
+    private readonly config: TreesitterAdapterConfig,
+    private readonly dep: unknown,
+  ) {}
+
+  async isAvailable(): Promise<boolean> {
+    if (!this.dep) {
+      return false;
+    }
+    const languages = toGrammarLanguages(this.config.languages);
+    this.grammars = await resolveGrammars(this.cwd, languages, this.config.grammarsPath);
+    return this.grammars.length > 0;
+  }
+
+  async run(input: BuildInput): Promise<SymbolLayer> {
+    const available: GrammarLanguage[] = this.grammars.map((grammar) => grammar.language);
+    const api = normalizeParserApi(this.dep);
+    if (!api) {
+      return { symbols: [], calls: [] };
+    }
+    if (typeof api.init === "function") {
+      await api.init();
+    }
+
+    // Load + cache one parser per resolved grammar language.
+    const parsers = new Map<GrammarLanguage, ParserLike>();
+    for (const grammar of this.grammars) {
+      try {
+        const language = await api.loadLanguage(grammar.path);
+        if (!language) {
+          continue;
+        }
+        const parser = api.create();
+        parser.setLanguage(language);
+        parsers.set(grammar.language, parser);
+      } catch {
+        // Grammar load failure ⇒ skip this language (never throw out).
+      }
+    }
+
+    const symbols: SymbolNode[] = [];
+    const calls: CallEdge[] = [];
+    for (const file of [...input.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+      const language = grammarForFile(file.path, available);
+      if (!language) {
+        continue;
+      }
+      const parser = parsers.get(language);
+      if (!parser) {
+        continue;
+      }
+      try {
+        const tree = parser.parse(file.content);
+        if (!tree?.rootNode) {
+          continue;
+        }
+        const layer = extractSymbolLayer(tree.rootNode, file.path, symbolLanguage(language));
+        symbols.push(...layer.symbols);
+        calls.push(...layer.calls);
+      } catch {
+        // Parse failure on one file ⇒ skip it deterministically.
+      }
+    }
+
+    return {
+      symbols: symbols.sort(compareSymbols),
+      // Global pass: resolve cross-file calls (per-file extraction can't) before
+      // sorting, so callers/impact don't under-report across module boundaries.
+      calls: resolveCrossFileCalls(symbols, calls).sort(compareCalls),
+    };
+  }
+}
+
+// Resolve a version-tolerant parser API from whatever `web-tree-sitter` shape the
+// runtime provides (0.22 default-export class vs 0.25 named exports).
+function normalizeParserApi(dep: unknown): ParserApi | null {
+  if (!dep) {
+    return null;
+  }
+  const ns = dep as { default?: unknown; Parser?: unknown; Language?: unknown; init?: unknown };
+  const ParserClass =
+    typeof ns.default === "function"
+      ? (ns.default as new () => ParserLike)
+      : typeof ns.Parser === "function"
+        ? (ns.Parser as new () => ParserLike)
+        : typeof dep === "function"
+          ? (dep as new () => ParserLike)
+          : null;
+  if (!ParserClass) {
+    return null;
+  }
+
+  const classInit = (ParserClass as unknown as { init?: unknown }).init;
+  const init =
+    typeof classInit === "function"
+      ? (classInit as () => Promise<void>).bind(ParserClass)
+      : typeof ns.init === "function"
+        ? (ns.init as () => Promise<void>).bind(ns)
+        : undefined;
+
+  // Resolve the grammar loader LAZILY: in 0.22 `Parser.Language.load` only
+  // becomes available AFTER `Parser.init()` runs, so binding it eagerly here
+  // (before init) would miss it and wrongly disable the whole capability.
+  const loadLanguage = (p: string): Promise<unknown> => {
+    const classLoad = (ParserClass as unknown as { Language?: { load?: unknown } }).Language;
+    if (typeof classLoad?.load === "function") {
+      return (classLoad.load as (x: string) => Promise<unknown>).call(classLoad, p); // 0.22
+    }
+    const nsLoad = ns.Language as { load?: unknown } | undefined;
+    if (typeof nsLoad?.load === "function") {
+      return (nsLoad.load as (x: string) => Promise<unknown>).call(nsLoad, p); // 0.25
+    }
+    return Promise.reject(new Error("web-tree-sitter: no Language.load"));
+  };
+
+  return {
+    ...(init ? { init } : {}),
+    loadLanguage,
+    create: () => new ParserClass(),
+  };
+}
+
+function compareSymbols(a: SymbolNode, b: SymbolNode): number {
+  if (a.path !== b.path) {
+    return a.path < b.path ? -1 : 1;
+  }
+  if (a.startLine !== b.startLine) {
+    return a.startLine - b.startLine;
+  }
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+
+function compareCalls(a: CallEdge, b: CallEdge): number {
+  if (a.from !== b.from) {
+    return a.from < b.from ? -1 : 1;
+  }
+  if (a.to !== b.to) {
+    return a.to < b.to ? -1 : 1;
+  }
+  return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+}