@mrciphersmith/keryx 0.2.9

package/src/gdgraph/config.test.ts

@@ -0,0 +1,47 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { DEFAULT_GDGRAPH_CONFIG, loadGdgraphConfig, mergeGdgraphConfig } from "./config";
+
+test("AC5.1 — defaults: affected.defaultDepth is 1 (back-compat)", () => {
+  expect(DEFAULT_GDGRAPH_CONFIG.affected.defaultDepth).toBe(1);
+  expect(mergeGdgraphConfig({}).repomap.tokenBudget).toBe(8000);
+  expect(mergeGdgraphConfig({}).repomap.tokenEstimator).toBe("chars-div-4");
+});
+
+test("AC5.1 — deep-merge overrides individual fields, keeps the rest", () => {
+  const merged = mergeGdgraphConfig({
+    affected: { defaultDepth: 3 },
+    repomap: { tokenBudget: 100 },
+    treesitter: { languages: ["typescript"] },
+  });
+  expect(merged.affected.defaultDepth).toBe(3);
+  expect(merged.repomap.tokenBudget).toBe(100);
+  // Untouched fields fall back to defaults.
+  expect(merged.repomap.damping).toBe(DEFAULT_GDGRAPH_CONFIG.repomap.damping);
+  expect(merged.treesitter.languages).toEqual(["typescript"]);
+  expect(merged.treesitter.grammarsPath).toBeNull();
+});
+
+test("AC5.1/C0-8 — missing config file ⇒ defaults", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-cfg-"));
+  try {
+    const config = await loadGdgraphConfig(root);
+    expect(config).toEqual(mergeGdgraphConfig({}));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC5.1/C0-8 — malformed JSON ⇒ defaults (never throws)", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-cfg-bad-"));
+  try {
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    await writeFile(path.join(root, ".metaproject", "gdgraph.config.json"), "{ not valid json ");
+    const config = await loadGdgraphConfig(root);
+    expect(config).toEqual(mergeGdgraphConfig({}));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/config.ts

@@ -0,0 +1,113 @@
+// gdgraph config loader + defaults (specification.md §5; T-B2, C0-8).
+//
+// `.metaproject/gdgraph.config.json` is an OPTIONAL file, deep-merged over the
+// built-in defaults. Missing OR malformed JSON degrades to the defaults so every
+// gdgraph command keeps working deterministically (mirrors `loadSecurityConfig`
+// and the `ctx.ts` config idiom). Every field falls back individually.
+
+import path from "node:path";
+import { pathExists } from "../lib/fs";
+import { readJsonFileOr } from "../lib/json";
+
+export type TokenEstimator = "chars-div-4";
+
+export interface GdgraphConfig {
+  affected: {
+    // MUST default to 1 for back-compat (B-3): depth-1 == today's dependents.
+    defaultDepth: number;
+  };
+  repomap: {
+    tokenBudget: number;
+    tokenEstimator: TokenEstimator;
+    maxSymbolsPerFile: number;
+    // PageRank params — FIXED ⇒ deterministic convergence (B-4, B-5).
+    damping: number;
+    iterations: number;
+    tolerance: number;
+    // CALL edge weight for personalized PageRank (import=1.0, defines=0.5).
+    callWeight: number;
+  };
+  treesitter: {
+    // T1 user-provided dir of *.wasm grammars (A-1); null ⇒ resolver cache/pull.
+    grammarsPath: string | null;
+    // Bounded to the languages this project extracts (NG-B3/B-8).
+    languages: string[];
+  };
+}
+
+export const DEFAULT_GDGRAPH_CONFIG: GdgraphConfig = {
+  affected: {
+    defaultDepth: 1,
+  },
+  repomap: {
+    tokenBudget: 8000,
+    tokenEstimator: "chars-div-4",
+    maxSymbolsPerFile: 12,
+    damping: 0.85,
+    iterations: 50,
+    tolerance: 1e-8,
+    callWeight: 1.5,
+  },
+  treesitter: {
+    grammarsPath: null,
+    languages: ["typescript", "tsx", "javascript"],
+  },
+};
+
+export function gdgraphConfigPath(cwd: string): string {
+  return path.join(cwd, ".metaproject", "gdgraph.config.json");
+}
+
+// Deep-merge a partial user config over the defaults, field-by-field. Unknown
+// keys are ignored; each known block falls back individually. Never throws.
+export function mergeGdgraphConfig(parsed: DeepPartial<GdgraphConfig>): GdgraphConfig {
+  const base = DEFAULT_GDGRAPH_CONFIG;
+  const affected = parsed.affected ?? {};
+  const repomap = parsed.repomap ?? {};
+  const treesitter = parsed.treesitter ?? {};
+  return {
+    affected: {
+      defaultDepth: numberOr(affected.defaultDepth, base.affected.defaultDepth),
+    },
+    repomap: {
+      tokenBudget: numberOr(repomap.tokenBudget, base.repomap.tokenBudget),
+      tokenEstimator:
+        repomap.tokenEstimator === "chars-div-4"
+          ? repomap.tokenEstimator
+          : base.repomap.tokenEstimator,
+      maxSymbolsPerFile: numberOr(repomap.maxSymbolsPerFile, base.repomap.maxSymbolsPerFile),
+      damping: numberOr(repomap.damping, base.repomap.damping),
+      iterations: numberOr(repomap.iterations, base.repomap.iterations),
+      tolerance: numberOr(repomap.tolerance, base.repomap.tolerance),
+      callWeight: numberOr(repomap.callWeight, base.repomap.callWeight),
+    },
+    treesitter: {
+      grammarsPath:
+        typeof treesitter.grammarsPath === "string"
+          ? treesitter.grammarsPath
+          : base.treesitter.grammarsPath,
+      languages: Array.isArray(treesitter.languages)
+        ? treesitter.languages.filter((entry): entry is string => typeof entry === "string")
+        : base.treesitter.languages,
+    },
+  };
+}
+
+// Load `.metaproject/gdgraph.config.json`, falling back to defaults when the
+// file is absent OR malformed (advisory-safe, never throws).
+export async function loadGdgraphConfig(cwd: string): Promise<GdgraphConfig> {
+  const file = gdgraphConfigPath(cwd);
+  if (!(await pathExists(file))) {
+    return mergeGdgraphConfig({});
+  }
+  const parsed = await readJsonFileOr<DeepPartial<GdgraphConfig>>(file, {});
+  return mergeGdgraphConfig(parsed);
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K];
+};

package/src/gdgraph/core-sources.test.ts

@@ -0,0 +1,99 @@
+// The copied gdgraph core must be import-closed.
+//
+// `init` and `update` copy a few `src/gdgraph/*.ts` files into
+// `.metaproject/core/gdgraph/` so a project can run the graph builder without
+// the full toolkit. The list was hand-maintained, in two places, and nothing
+// checked it against what those files actually import.
+//
+// So when `query.ts` gained `import { resolveGraphTarget } from "./target"`,
+// neither copy learned about it, and `keryx gdgraph build` — the very first
+// "Next step" that `init` prints — died on every fresh install with
+// `Cannot find module './target'`. The suite stayed green throughout, because
+// nothing ever ran the copied tree.
+//
+// The domain of "which files does the copied core need" is not a list. It is
+// the transitive closure of RUNTIME imports from the entry points, and written
+// as a list it goes stale on the next `import`.
+//
+// The first version of this test matched imports with a regular expression and
+// immediately proved the repository's own lesson about pattern guards: it
+// matched the string `from "./m"` inside a COMMENT in `build.ts` and demanded a
+// file called `m.ts`. So it uses `Bun.Transpiler.scanImports` instead — the same
+// parser-backed scan gdgraph itself uses. That also gets the semantics right:
+// the transpiler drops type-only imports, and a type-only import genuinely does
+// not need its file present at runtime.
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { GDGRAPH_CORE_SOURCES } from "./core-sources";
+
+const GDGRAPH_DIR = import.meta.dir;
+const transpiler = new Bun.Transpiler({ loader: "ts" });
+
+/**
+ * Local imports of one module that must resolve for it to LOAD.
+ *
+ * Two exclusions, both deliberate rather than convenient:
+ *
+ *   * type-only imports never reach runtime — the transpiler drops them, and
+ *     `scanImports` does not report them;
+ *   * a `dynamic-import` is a deliberate lazy edge. `build.ts` reaches `enrich`
+ *     that way precisely so it can run in an environment that lacks it —
+ *     `enrich.ts:9` names "the copied `.metaproject/core/gdgraph`" as that
+ *     environment. Requiring it would copy the whole optional-capability tree
+ *     into every scaffolded project and invert the design.
+ *
+ * So the closure is over `import-statement` only. That is the set whose absence
+ * is a crash at load, which is the failure this test exists to prevent.
+ */
+function runtimeImportsOf(basename: string): string[] {
+  const source = readFileSync(path.join(GDGRAPH_DIR, basename), "utf8");
+  return transpiler
+    .scanImports(source)
+    .filter((entry) => entry.kind === "import-statement" && entry.path.startsWith("./"))
+    .map((entry) => `${entry.path.slice(2).replace(/\.(ts|js)$/, "")}.ts`);
+}
+
+/** Every module reachable from `entries` through runtime local imports. */
+function importClosure(entries: readonly string[]): Set<string> {
+  const seen = new Set<string>();
+  const queue = [...entries];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    for (const next of runtimeImportsOf(current)) queue.push(next);
+  }
+  return seen;
+}
+
+describe("the copied gdgraph core is import-closed", () => {
+  // `cli.ts` is rendered rather than copied, and it drives these two.
+  const ENTRY_POINTS = ["build.ts", "query.ts"] as const;
+
+  test("every module the entry points reach at runtime is copied", () => {
+    const needed = importClosure(ENTRY_POINTS);
+    const copied = new Set(GDGRAPH_CORE_SOURCES);
+    const missing = [...needed].filter((f) => !copied.has(f)).sort();
+    // A failure here means a fresh `keryx init` followed by `keryx gdgraph
+    // build` dies on a missing module. Add the file to GDGRAPH_CORE_SOURCES.
+    expect(missing).toEqual([]);
+  });
+
+  test("every file in the copy list exists", () => {
+    for (const file of GDGRAPH_CORE_SOURCES) {
+      expect(() => readFileSync(path.join(GDGRAPH_DIR, file), "utf8")).not.toThrow();
+    }
+  });
+
+  test("the closure is non-trivial, so a passing test is not vacuous", () => {
+    // If `scanImports` ever silently returned nothing, the first assertion
+    // would pass against an empty set. Pin the floor, and pin the specific file
+    // whose absence caused the outage.
+    const needed = importClosure(ENTRY_POINTS);
+    expect(needed.size).toBeGreaterThanOrEqual(3);
+    expect(needed.has("build.ts")).toBe(true);
+    expect(needed.has("query.ts")).toBe(true);
+    expect(needed.has("target.ts")).toBe(true);
+  });
+});

package/src/gdgraph/core-sources.ts

@@ -0,0 +1,20 @@
+// The `src/gdgraph/*.ts` files that `init` and `update` copy into
+// `.metaproject/core/gdgraph/`, so a scaffolded project can run the graph
+// builder without the full toolkit installed.
+//
+// This list used to live inline in BOTH `commands/init.ts` and
+// `commands/update.ts`, which meant two hand-maintained copies of a fact that
+// nothing checked. When `query.ts` gained an import of `./target`, neither copy
+// learned about it and `keryx gdgraph build` broke on every fresh install —
+// while the suite stayed green, because nothing ran the copied tree.
+//
+// It is one constant now, and `core-sources.test.ts` computes the transitive
+// closure of local imports from the entry points and asserts this list equals
+// it, in both directions. A new `import` in a copied file fails that test
+// instead of a stranger's first five minutes.
+export const GDGRAPH_CORE_SOURCES: readonly string[] = [
+  "build.ts",
+  "query.ts",
+  "target.ts",
+  "types.ts",
+];

package/src/gdgraph/enrich.ts

@@ -0,0 +1,79 @@
+// Symbol-layer enrichment behind the capability seam (specification.md §7, §8.1;
+// T-B13). Called by `build.ts` AFTER the unchanged file-level build. When
+// `gdgraph.treesitter` resolves to an adapter it writes `storage/symbols.jsonl`
+// and `storage/calls.jsonl` ADDITIVELY; when it degrades to `null` (default /
+// dep or grammar missing) nothing is written and the four legacy artifacts stay
+// byte-identical (the golden rule, B-1/C0-7/F-3).
+//
+// `build.ts` imports this module DYNAMICALLY inside a try/catch, so an
+// environment that lacks the seam (e.g. the copied `.metaproject/core/gdgraph`
+// runner) simply falls back to file-level output — the exact degraded behavior.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  resolveCapability,
+  runCapabilityOrFallback,
+  type CapabilityAdapter,
+  type CapabilitySpec,
+} from "../capability/seam";
+import { loadGdgraphConfig } from "./config";
+import { createTreesitterSpec, type BuildInput, type FileRecord } from "./treesitter/adapter";
+import type { SymbolLayer } from "./types";
+
+export interface EnrichResult {
+  enriched: boolean;
+  symbols: number;
+  calls: number;
+}
+
+// Seam resolver, injectable for tests so the availability-true write path can be
+// proven with a mock adapter (the real optional dep is not installed offline).
+export type CapabilityResolver = (
+  cwd: string,
+  spec: CapabilitySpec<BuildInput, SymbolLayer>,
+) => Promise<CapabilityAdapter<BuildInput, SymbolLayer> | null>;
+
+export async function enrichBuildWithSymbols(
+  cwd: string,
+  files: FileRecord[],
+  resolve: CapabilityResolver = resolveCapability,
+): Promise<EnrichResult> {
+  const config = await loadGdgraphConfig(cwd);
+  const spec = createTreesitterSpec(cwd, {
+    languages: config.treesitter.languages,
+    grammarsPath: config.treesitter.grammarsPath,
+  });
+
+  // Gate 1 (manifest-enabled) + dep + grammar + isAvailable. `null` ⇒ degrade
+  // with NO symbol files written; the seam emits the single warn-once on an
+  // enabled-but-unavailable ceiling.
+  const adapter = await resolve(cwd, spec);
+  if (!adapter) {
+    return { enriched: false, symbols: 0, calls: 0 };
+  }
+
+  const layer = await runCapabilityOrFallback<BuildInput, SymbolLayer>(
+    adapter,
+    { files },
+    () => ({ symbols: [], calls: [] }),
+  );
+
+  await writeSymbolLayer(cwd, layer);
+  return { enriched: true, symbols: layer.symbols.length, calls: layer.calls.length };
+}
+
+async function writeSymbolLayer(cwd: string, layer: SymbolLayer): Promise<void> {
+  const storageDir = path.join(cwd, ".metaproject", "data", "gdgraph", "storage");
+  await mkdir(storageDir, { recursive: true });
+  await writeFile(
+    path.join(storageDir, "symbols.jsonl"),
+    layer.symbols.map((symbol) => JSON.stringify(symbol)).join("\n") + "\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(storageDir, "calls.jsonl"),
+    layer.calls.map((call) => JSON.stringify(call)).join("\n") + "\n",
+    "utf8",
+  );
+}

package/src/gdgraph/fallback.test.ts

@@ -0,0 +1,153 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { buildGraph } from "./build";
+import { computeAffected } from "./affected";
+import { loadGdgraphConfig } from "./config";
+import { computeRepomap } from "./repomap";
+import { loadGraph } from "./query";
+import { resetWarnOnce, hasWarned } from "../capability/warn-once";
+
+const ARTIFACTS = [
+  "storage/nodes.jsonl",
+  "storage/edges.jsonl",
+  "artifacts/module-map.json",
+  "artifacts/summary.md",
+];
+
+async function makeProject(): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-fallback-"));
+  await mkdir(path.join(root, "src", "feature"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "index.ts"),
+    "import { value } from './feature/value';\nexport const app = value;\n",
+  );
+  await writeFile(path.join(root, "src", "feature", "value.ts"), "export const value = 1;\n");
+  return root;
+}
+
+async function snapshot(root: string): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const rel of ARTIFACTS) {
+    out[rel] = await readFile(
+      path.join(root, ".metaproject", "data", "gdgraph", rel),
+      "utf8",
+    );
+  }
+  return out;
+}
+
+test("AC4.1/AC4.2 — capability OFF: 4 legacy artifacts deterministic; no symbol files written", async () => {
+  // Two fresh, identical projects, each built ONCE (a rebuild in the same dir is
+  // pre-existingly non-deterministic because the build creates `.metaproject`,
+  // which then appears in the summary's skipped-dirs — unrelated to this block).
+  // Comparing two first-builds isolates the capability-off artifacts precisely.
+  const a = await makeProject();
+  const b = await makeProject();
+  try {
+    await buildGraph(a);
+    await buildGraph(b);
+    expect(await snapshot(b)).toEqual(await snapshot(a));
+
+    for (const root of [a, b]) {
+      const storage = path.join(root, ".metaproject", "data", "gdgraph", "storage");
+      expect(existsSync(path.join(storage, "symbols.jsonl"))).toBe(false);
+      expect(existsSync(path.join(storage, "calls.jsonl"))).toBe(false);
+    }
+  } finally {
+    await rm(a, { recursive: true, force: true });
+    await rm(b, { recursive: true, force: true });
+  }
+});
+
+test("AC4.4 — no-network sandbox: build/affected/repomap open zero sockets", async () => {
+  const root = await makeProject();
+  const originalConnect = net.Socket.prototype.connect;
+  const originalFetch = globalThis.fetch;
+  let socketAttempts = 0;
+  let fetchAttempts = 0;
+
+  net.Socket.prototype.connect = function connect(this: net.Socket) {
+    socketAttempts += 1;
+    // Never actually connect.
+    return this;
+  };
+  // @ts-expect-error — deliberately override for the sandbox assertion.
+  globalThis.fetch = async () => {
+    fetchAttempts += 1;
+    throw new Error("network blocked in sandbox");
+  };
+
+  try {
+    await buildGraph(root);
+    const config = await loadGdgraphConfig(root);
+    const graph = await loadGraph(root);
+    computeAffected(graph, "src/feature/value.ts", { depth: 3 });
+    computeRepomap(graph, config, {});
+    expect(socketAttempts).toBe(0);
+    expect(fetchAttempts).toBe(0);
+  } finally {
+    net.Socket.prototype.connect = originalConnect;
+    globalThis.fetch = originalFetch;
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC4.3 — capability ENABLED but unavailable: exactly one warn, regex path, exit 0, no symbol files", async () => {
+  const root = await makeProject();
+  resetWarnOnce();
+  try {
+    // Enable the ceiling in the manifest but provide NO resolvable grammar and
+    // no installed dep ⇒ resolveCapability degrades with a single warn-once.
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    await writeFile(
+      path.join(root, ".metaproject", "metaproject.json"),
+      JSON.stringify({
+        modules: {
+          gdgraph: {
+            enabled: true,
+            capabilities: [
+              { id: "gdgraph.treesitter", enabled: true, kind: "ceiling", optionalDependency: "web-tree-sitter" },
+            ],
+          },
+        },
+      }),
+    );
+
+    let stderr = "";
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderr += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString();
+      return true;
+    }) as typeof process.stderr.write;
+
+    let exitCodeBefore = process.exitCode;
+    try {
+      await buildGraph(root);
+    } finally {
+      process.stderr.write = originalWrite;
+    }
+
+    // Build did not hard-fail (exitCode untouched by build).
+    expect(process.exitCode).toBe(exitCodeBefore);
+    // Exactly one capability degradation warning was emitted.
+    const warnings = stderr.split("\n").filter((line) => line.includes("gdgraph.treesitter unavailable"));
+    expect(warnings).toHaveLength(1);
+    expect(hasWarned("gdgraph.treesitter")).toBe(true);
+
+    // No symbol files were written (regex/scan path only).
+    const storage = path.join(root, ".metaproject", "data", "gdgraph", "storage");
+    expect(existsSync(path.join(storage, "symbols.jsonl"))).toBe(false);
+    // The 4 legacy artifacts were still produced.
+    for (const rel of ARTIFACTS) {
+      const info = await stat(path.join(root, ".metaproject", "data", "gdgraph", rel));
+      expect(info.isFile()).toBe(true);
+    }
+  } finally {
+    resetWarnOnce();
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/find.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from "bun:test";
+import { findNodes, findSymbols } from "./find";
+import type { GraphData, SymbolNode } from "./types";
+
+function fileNode(path: string) {
+  return { id: path, kind: "file" as const, path, language: "typescript" as const };
+}
+
+function edge(from: string, to: string) {
+  return { id: `${from}->${to}`, from, to, kind: "imports" as const, specifier: to };
+}
+
+const GRAPH: GraphData = {
+  nodes: [
+    fileNode("src/pipelines/utils/clone-pipeline.ts"),
+    fileNode("src/pipelines/features/pipeline-variables/pipeline-variables-store.ts"),
+    fileNode("src/pipelines/api/pipeline-api.ts"),
+    fileNode("src/case/store/case-store.ts"),
+  ],
+  edges: [
+    edge("src/case/store/case-store.ts", "src/pipelines/api/pipeline-api.ts"),
+    edge("src/pipelines/utils/clone-pipeline.ts", "src/pipelines/api/pipeline-api.ts"),
+  ],
+};
+
+test("finds files by concept and ranks by matched terms", () => {
+  const results = findNodes(GRAPH, "pipeline clone");
+  expect(results[0]?.path).toBe("src/pipelines/utils/clone-pipeline.ts");
+  expect(results[0]?.matched.sort()).toEqual(["clone", "pipeline"]);
+});
+
+test("ranks pipeline-variables highest for that query", () => {
+  const results = findNodes(GRAPH, "pipeline variables store");
+  expect(results[0]?.path).toContain("pipeline-variables-store.ts");
+});
+
+test("drops stopwords and short tokens from the query", () => {
+  const results = findNodes(GRAPH, "the clone of a pipeline");
+  expect(results[0]?.path).toBe("src/pipelines/utils/clone-pipeline.ts");
+  // "the", "of", "a" must not have matched anything on their own
+  expect(results.every((r) => !r.matched.includes("the"))).toBe(true);
+});
+
+test("returns empty for a query that matches no path", () => {
+  expect(findNodes(GRAPH, "kubernetes helm chart")).toEqual([]);
+});
+
+test("fan-in breaks ties (more-depended-on file ranks higher)", () => {
+  // both match "pipeline api" equally; pipeline-api has 2 dependents
+  const results = findNodes(GRAPH, "pipeline");
+  const apiIdx = results.findIndex((r) => r.path.endsWith("pipeline-api.ts"));
+  expect(results[apiIdx]?.dependents).toBe(2);
+});
+
+function sym(id: string, name: string, path: string, line: number): SymbolNode {
+  return { id, kind: "function", path, name, container: null, startLine: line, endLine: line + 2, language: "typescript" };
+}
+
+const SYMBOL_GRAPH: GraphData = {
+  nodes: [],
+  edges: [],
+  symbols: [
+    sym("a#clonePipeline", "clonePipeline", "src/a.ts", 12),
+    sym("b#clonePipelineDeep", "clonePipelineDeep", "src/b.ts", 30),
+    sym("c#unrelated", "unrelated", "src/c.ts", 1),
+  ],
+};
+
+test("findSymbols ranks an exact name match above a substring match", () => {
+  const results = findSymbols(SYMBOL_GRAPH, "clonePipeline");
+  expect(results[0]?.name).toBe("clonePipeline"); // exact-name bonus wins
+  expect(results.map((r) => r.name)).toContain("clonePipelineDeep");
+  expect(results.every((r) => r.name !== "unrelated")).toBe(true);
+});
+
+test("findSymbols returns [] when the symbol layer is absent", () => {
+  expect(findSymbols({ nodes: [], edges: [] }, "clonePipeline")).toEqual([]);
+});