feat(show): show-engine.ts findSymbolsByName + tests (Tracer 1 of 6)

Pure transport-agnostic lookup engine — same shape audit-engine.ts / query-engine.ts use (PRs #33 / #35). findSymbolsByName({db, name, kind?, inPath?}) returns SymbolMatch[] with deterministic order (file_path ASC, line_start ASC) so callers slice for stable disambiguation output.

Per Q-3 settled: name match is case-sensitive (exact). Per Q-4 settled: inPath uses a directory-vs-file heuristic — trailing slash OR no extension in trailing segment treats as prefix (LIKE 'src/cli/%'); else exact file match (file_path = ?). Caller normalizes via toProjectRelative before passing.

12 unit tests cover: single match, unknown name, ambiguous (3-match deterministic order), kind filter narrowing, inPath as directory (no slash + with slash), inPath as file (exact + miss), kind+inPath compose AND, returned columns, case-sensitivity.

Reuses the symbols table directly. No schema change. Tracer 2 wires the CLI verb on top.

Author: SutuSebastian

src/application/show-engine.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import { createTables } from "../db";
+import type { CodemapDatabase } from "../db";
+import { openCodemapDatabase } from "../sqlite-db";
+import { findSymbolsByName } from "./show-engine";
+
+let db: CodemapDatabase;
+
+beforeEach(() => {
+  db = openCodemapDatabase(":memory:");
+  createTables(db);
+  // Seed a `files` row first so `symbols.file_path` foreign keys resolve.
+  db.run(
+    "INSERT INTO files (path, content_hash, size, line_count, language, last_modified, indexed_at) VALUES (?, ?, ?, ?, ?, ?, ?), (?, ?, ?, ?, ?, ?, ?), (?, ?, ?, ?, ?, ?, ?)",
+    [
+      "src/cli/cmd-show.ts",
+      "h1",
+      100,
+      30,
+      "ts",
+      1,
+      1,
+      "src/legacy/foo.ts",
+      "h2",
+      80,
+      20,
+      "ts",
+      1,
+      1,
+      "src/test/fixtures.ts",
+      "h3",
+      50,
+      15,
+      "ts",
+      1,
+      1,
+    ],
+  );
+  // Three symbols named `foo` across two files + a kind variation.
+  db.run(
+    `INSERT INTO symbols (file_path, name, kind, line_start, line_end, signature, is_exported, is_default_export)
+     VALUES
+       ('src/cli/cmd-show.ts', 'foo', 'function', 5, 15, 'function foo(): void', 1, 0),
+       ('src/legacy/foo.ts',   'foo', 'function', 1, 50, 'function foo(arg: string): number', 0, 0),
+       ('src/test/fixtures.ts','foo', 'const',    3, 3,  'const foo = 42',                    1, 0),
+       ('src/cli/cmd-show.ts', 'bar', 'function', 20, 25,'function bar(): string',           1, 0)`,
+  );
+});
+
+afterEach(() => {
+  db.close();
+});
+
+describe("findSymbolsByName", () => {
+  it("returns single match for a unique name", () => {
+    const r = findSymbolsByName(db, { name: "bar" });
+    expect(r).toHaveLength(1);
+    expect(r[0]).toMatchObject({
+      name: "bar",
+      kind: "function",
+      file_path: "src/cli/cmd-show.ts",
+      line_start: 20,
+      line_end: 25,
+    });
+  });
+
+  it("returns empty array for unknown name", () => {
+    expect(findSymbolsByName(db, { name: "no-such-symbol" })).toEqual([]);
+  });
+
+  it("returns all matches for an ambiguous name (deterministic order)", () => {
+    const r = findSymbolsByName(db, { name: "foo" });
+    expect(r).toHaveLength(3);
+    // Ordered by file_path ASC, line_start ASC.
+    expect(r.map((m) => m.file_path)).toEqual([
+      "src/cli/cmd-show.ts",
+      "src/legacy/foo.ts",
+      "src/test/fixtures.ts",
+    ]);
+  });
+
+  it("filters by kind when set", () => {
+    const r = findSymbolsByName(db, { name: "foo", kind: "const" });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.file_path).toBe("src/test/fixtures.ts");
+  });
+
+  it("kind=function narrows ambiguous name to 2 matches", () => {
+    const r = findSymbolsByName(db, { name: "foo", kind: "function" });
+    expect(r).toHaveLength(2);
+    expect(r.map((m) => m.file_path)).toEqual([
+      "src/cli/cmd-show.ts",
+      "src/legacy/foo.ts",
+    ]);
+  });
+
+  it("inPath as directory (no extension) treats as prefix", () => {
+    const r = findSymbolsByName(db, { name: "foo", inPath: "src/cli" });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.file_path).toBe("src/cli/cmd-show.ts");
+  });
+
+  it("inPath with trailing slash treats as prefix", () => {
+    const r = findSymbolsByName(db, { name: "foo", inPath: "src/legacy/" });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.file_path).toBe("src/legacy/foo.ts");
+  });
+
+  it("inPath with file extension treats as exact match", () => {
+    const r = findSymbolsByName(db, {
+      name: "foo",
+      inPath: "src/test/fixtures.ts",
+    });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.kind).toBe("const");
+  });
+
+  it("inPath exact-match misses when path doesn't match", () => {
+    const r = findSymbolsByName(db, {
+      name: "foo",
+      inPath: "src/test/other.ts",
+    });
+    expect(r).toEqual([]);
+  });
+
+  it("inPath + kind compose (AND, not OR)", () => {
+    const r = findSymbolsByName(db, {
+      name: "foo",
+      kind: "function",
+      inPath: "src/cli",
+    });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.file_path).toBe("src/cli/cmd-show.ts");
+  });
+
+  it("returns kind/visibility/parent_name fields", () => {
+    const r = findSymbolsByName(db, { name: "bar" });
+    expect(r[0]).toMatchObject({
+      kind: "function",
+      visibility: null,
+      parent_name: null,
+      is_exported: 1,
+    });
+  });
+
+  it("name match is case-sensitive", () => {
+    expect(findSymbolsByName(db, { name: "FOO" })).toEqual([]);
+    expect(findSymbolsByName(db, { name: "Foo" })).toEqual([]);
+  });
+});

src/application/show-engine.ts

@@ -0,0 +1,89 @@
+import type { CodemapDatabase } from "../db";
+
+/**
+ * One row from the `symbols` table — the canonical match shape returned by
+ * `findSymbolsByName`. Same columns the CLI / MCP `show` verbs surface in
+ * their `--json` envelopes, plus the always-present `signature` so an agent
+ * can disambiguate without a follow-up read.
+ */
+export interface SymbolMatch {
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  is_exported: number;
+  parent_name: string | null;
+  visibility: string | null;
+}
+
+export interface FindSymbolsOpts {
+  /** Exact symbol name (case-sensitive — per plan §9 Q-3). */
+  name: string;
+  /** Optional `symbols.kind` filter (e.g. "function", "const", "class"). */
+  kind?: string | undefined;
+  /**
+   * Optional file-scope filter. If `<inPath>` ends with `/` or matches a
+   * directory shape, treats as prefix (`AND file_path LIKE 'src/cli/%'`);
+   * otherwise exact match (`AND file_path = 'src/cli/cmd-show.ts'`).
+   * Caller should normalize via `toProjectRelative` before passing — this
+   * engine does no path-shape massaging beyond the prefix/exact split.
+   */
+  inPath?: string | undefined;
+}
+
+/**
+ * Pure transport-agnostic lookup — same shape `cmd-show.ts` and the MCP
+ * `show` tool both call. Mirrors the `audit-engine.ts` / `query-engine.ts`
+ * pattern from PRs #33 / #35.
+ *
+ * Returns rows ordered deterministically (`file_path ASC, line_start ASC`)
+ * so callers can slice the array and get stable disambiguation output.
+ */
+export function findSymbolsByName(
+  db: CodemapDatabase,
+  opts: FindSymbolsOpts,
+): SymbolMatch[] {
+  const clauses: string[] = ["name = ?"];
+  const params: (string | number)[] = [opts.name];
+
+  if (opts.kind !== undefined && opts.kind.length > 0) {
+    clauses.push("kind = ?");
+    params.push(opts.kind);
+  }
+
+  if (opts.inPath !== undefined && opts.inPath.length > 0) {
+    if (looksLikeDirectory(opts.inPath)) {
+      const prefix = opts.inPath.endsWith("/")
+        ? opts.inPath
+        : `${opts.inPath}/`;
+      clauses.push("file_path LIKE ?");
+      params.push(`${prefix}%`);
+    } else {
+      clauses.push("file_path = ?");
+      params.push(opts.inPath);
+    }
+  }
+
+  const sql = `SELECT name, kind, file_path, line_start, line_end, signature,
+                      is_exported, parent_name, visibility
+               FROM symbols
+               WHERE ${clauses.join(" AND ")}
+               ORDER BY file_path ASC, line_start ASC`;
+  return db.query(sql).all(...params) as SymbolMatch[];
+}
+
+// Heuristic: `--in src/cli/` (trailing slash) and `--in src/cli` (no slash, no
+// dot) both mean "prefix"; `--in src/cli/cmd-show.ts` (has a file extension
+// after the last slash) means "exact file match". Conservative: anything
+// ambiguous treats as prefix — over-matching is recoverable (agent narrows
+// further); under-matching silently misses results.
+function looksLikeDirectory(p: string): boolean {
+  if (p.endsWith("/")) return true;
+  const lastSlash = p.lastIndexOf("/");
+  const tail = lastSlash === -1 ? p : p.slice(lastSlash + 1);
+  // No `.` in the trailing segment → directory-shaped (e.g. `src/cli`).
+  // A `.` → file-shaped (e.g. `src/cli/cmd-show.ts`, `cmd-show.ts`).
+  return !tail.includes(".");
+}