docsgov 0.1.0

package/dist/cmd/main.test.js

@@ -0,0 +1,422 @@
+// Tests the CLI wire-up: exit-code mapping, command routing, --format flag, the
+// check e2e loop, dedup command registration, and the npm-appropriate update
+// command. Port of cmd/docgov/{main,dedup_cli,update}_test.go, adapted to the
+// commander framework and npm distribution.
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { run, newApp, readVersion, ViolationsError, DuplicatesError, exitOK, exitViolation, exitUsage, } from "./main.js";
+// makeNewSchemaRepo builds a minimal temp repo with a .docgov/docgov.yaml and
+// the provided docs files (relPath→content). Returns the temp dir path. Mirrors
+// the Go makeNewSchemaRepo helper.
+function makeNewSchemaRepo(docgovYAML, docs) {
+    const tmp = mkdtempSync(path.join(tmpdir(), "docgov-cmd-"));
+    mkdirSync(path.join(tmp, ".docgov"), { recursive: true });
+    writeFileSync(path.join(tmp, ".docgov", "docgov.yaml"), docgovYAML);
+    for (const [relPath, content] of Object.entries(docs)) {
+        const abs = path.join(tmp, ...relPath.split("/"));
+        mkdirSync(path.dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+    }
+    return tmp;
+}
+// withCwd runs fn with process.cwd() temporarily set to dir, restoring it (and
+// removing the temp dir) afterwards. run() reads process.cwd(), so commands
+// that touch the filesystem must be driven from the target repo. Mirrors the Go
+// chdirCleanup helper.
+async function withCwd(dir, fn) {
+    const orig = process.cwd();
+    process.chdir(dir);
+    try {
+        return await fn();
+    }
+    finally {
+        process.chdir(orig);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+// captureStdout collects everything written to process.stdout while fn runs and
+// returns it. WHY: run()'s check action writes the report to stdout; tests must
+// intercept that stream to verify render wiring. Mirrors the Go captureStdout.
+async function captureStdout(fn) {
+    let out = "";
+    const spy = vi
+        .spyOn(process.stdout, "write")
+        .mockImplementation((chunk) => {
+        out += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString();
+        return true;
+    });
+    try {
+        await fn();
+    }
+    finally {
+        spy.mockRestore();
+    }
+    return out;
+}
+// silenceStderr suppresses commander's framework error messages (it writes to
+// stderr on unknown command / bad usage); tests assert exit codes, not the
+// framework's own text.
+function silenceStderr() {
+    const spy = vi
+        .spyOn(process.stderr, "write")
+        .mockImplementation(() => true);
+    return () => spy.mockRestore();
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("exit-code mapping", () => {
+    // The exit-code contract is the primary interface between the CLI and
+    // CI/agent callers — a wrong mapping silently breaks automation. Mirrors Go's
+    // TestExitCodeMapping.
+    it("no args shows help and exits 0", async () => {
+        const restore = silenceStderr();
+        await captureStdout(async () => {
+            const code = await run([]);
+            expect(code).toBe(exitOK);
+        });
+        restore();
+    });
+    it("unknown command exits 2 (usage)", async () => {
+        const restore = silenceStderr();
+        const code = await run(["notacommand"]);
+        restore();
+        expect(code).toBe(exitUsage);
+    });
+    // --help must never be confused with a usage error: it exits 0. Mirrors Go's
+    // TestExitCodeViolationSentinel.
+    it("--help exits 0", async () => {
+        const restore = silenceStderr();
+        await captureStdout(async () => {
+            const code = await run(["--help"]);
+            expect(code).toBe(exitOK);
+        });
+        restore();
+    });
+    // --version exits 0 (semantics preserved from Go's Version wiring).
+    it("--version exits 0", async () => {
+        await captureStdout(async () => {
+            const code = await run(["--version"]);
+            expect(code).toBe(exitOK);
+        });
+    });
+});
+describe("check command", () => {
+    // Invalid --format values are usage errors per the exit-code contract.
+    // Mirrors Go's TestRunCheckBadFormat.
+    it("invalid --format exits 2", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nHello.\n",
+        });
+        const restore = silenceStderr();
+        const code = await withCwd(tmp, () => run(["check", "--format", "xml"]));
+        restore();
+        expect(code).toBe(exitUsage);
+    });
+    // The pipeline (loadConfig + check.run) must produce a clean result when
+    // there are no violations, not a config error or spurious exit 1. Mirrors
+    // Go's TestCheckNewSchema_CleanExitsZero.
+    it("clean repo exits 0", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nSee [overview](./overview.md).\n",
+            "docs/overview.md": "# Overview\n\nHello.\n",
+        });
+        let code = -1;
+        await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check"]);
+        }));
+        expect(code).toBe(exitOK);
+    });
+    // A dangling link must surface as exit 1 — proves runCheck is wired to
+    // loadConfig + check.run (the doc: boundary is recognized and the missing
+    // target is detected). Mirrors Go's TestCheckNewSchema_DanglingLinkExitsOne.
+    it("dangling link exits 1", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nSee [missing](./nonexistent.md) for details.\n",
+        });
+        let code = -1;
+        await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check"]);
+        }));
+        expect(code).toBe(exitViolation);
+    });
+    // Missing .docgov/docgov.yaml is a usage/config error → exit 2. Mirrors Go's
+    // TestCheckNewSchema_MissingConfigExitsTwo.
+    it("missing docgov.yaml exits 2", async () => {
+        const tmp = mkdtempSync(path.join(tmpdir(), "docgov-cmd-"));
+        mkdirSync(path.join(tmp, ".docgov"), { recursive: true });
+        const restore = silenceStderr();
+        const code = await withCwd(tmp, () => run(["check"]));
+        restore();
+        expect(code).toBe(exitUsage);
+    });
+    // --format json must be accepted and exit 0 on a clean repo. Mirrors Go's
+    // TestCheckNewSchema_FormatJSON.
+    it("--format json on clean repo exits 0", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nHello.\n",
+        });
+        let code = -1;
+        await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check", "--format", "json"]);
+        }));
+        expect(code).toBe(exitOK);
+    });
+    // An empty boundary list produces no violations (no files in scope → guard
+    // silently skipped). Mirrors Go's TestCheckNewSchema_EmptySectionSkipped.
+    it("empty doc boundary exits 0", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary: []\n", {
+            "docs/guide.md": "# Guide\n\n[dangling](./gone.md)\n",
+        });
+        let code = -1;
+        await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check"]);
+        }));
+        expect(code).toBe(exitOK);
+    });
+    // runCheck writes report.text(vs) to stdout — if that wiring were removed,
+    // violations would be silently swallowed despite exit 1. Falsifiable: removing
+    // the stdout write makes this fail. Mirrors Go's
+    // TestCheckNewSchema_DanglingLinkTextOutput.
+    it("renders guard-docs violation to stdout (text)", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nSee [missing](./nonexistent.md) for details.\n",
+        });
+        let code = -1;
+        const out = await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check"]);
+        }));
+        expect(code).toBe(exitViolation);
+        expect(out).toContain("guard-docs");
+        expect(out).toContain("referenced file does not exist");
+    });
+    // runCheck writes report.json(vs) for json format — removing it would silently
+    // drop the violation. Falsifiable. Mirrors Go's
+    // TestCheckNewSchema_FormatJSONRendersViolation.
+    it("renders guard-docs violation as valid JSON", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            "docs/guide.md": "# Guide\n\nSee [missing](./nonexistent.md) for details.\n",
+        });
+        let code = -1;
+        const out = await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["check", "--format", "json"]);
+        }));
+        expect(code).toBe(exitViolation);
+        expect(() => JSON.parse(out.trim())).not.toThrow();
+        expect(out).toContain("guard-docs");
+        expect(out).toContain("referenced file does not exist");
+    });
+});
+describe("command registration", () => {
+    // gen/add/list are retired; check has no --flip flag. Their continued presence
+    // would allow invoking removed functionality. Mirrors Go's
+    // TestRetiredCommandsRemoved.
+    it("retired commands (gen/add/list) are absent; check has no --flip", () => {
+        const app = newApp("test");
+        const names = app.commands.map((c) => c.name());
+        for (const retired of ["gen", "add", "list"]) {
+            expect(names).not.toContain(retired);
+        }
+        const check = app.commands.find((c) => c.name() === "check");
+        expect(check).toBeDefined();
+        const flagNames = check.options.map((o) => o.long);
+        expect(flagNames).not.toContain("--flip");
+    });
+    // dedup is wired as a single command — no separate "index" subcommand — with a
+    // merged action (index folded into the default action). Mirrors Go's
+    // TestDedupCommandRegistered.
+    it("dedup is a single command with no subcommands", () => {
+        const app = newApp("test");
+        const dedup = app.commands.find((c) => c.name() === "dedup");
+        expect(dedup).toBeDefined();
+        expect(dedup.commands.length).toBe(0);
+    });
+});
+describe("error sentinels", () => {
+    // ViolationsError and DuplicatesError are distinct sentinels: ViolationsError
+    // gates on doc violations, DuplicatesError on dedup duplicates. Both map to
+    // exit 1, but conflating them would mean CI gates on the wrong thing. Mirrors
+    // Go's TestErrDuplicatesMapsToViolation.
+    it("ViolationsError and DuplicatesError are distinct types", () => {
+        const v = new ViolationsError();
+        const d = new DuplicatesError();
+        expect(v).toBeInstanceOf(ViolationsError);
+        expect(d).toBeInstanceOf(DuplicatesError);
+        expect(d).not.toBeInstanceOf(ViolationsError);
+        expect(v).not.toBeInstanceOf(DuplicatesError);
+    });
+});
+describe("update command (npm)", () => {
+    // DEVIATION from Go: the GitLab-binary-download + self-replace logic is N/A for
+    // npm. update --check reports current and latest versions, degrading gracefully
+    // when the npm registry is unreachable (offline-safe). Replaces Go's
+    // TestAssetName / TestReplaceExecutable, which have no npm analogue.
+    it("--check handles a failed registry fetch gracefully (exit 0)", async () => {
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn(async () => {
+            throw new Error("offline");
+        });
+        try {
+            let code = -1;
+            const out = await captureStdout(async () => {
+                code = await run(["update", "--check"]);
+            });
+            expect(code).toBe(exitOK);
+            expect(out).toContain("current:");
+            expect(out).toContain("latest:");
+            // Offline path reports an unreachable-registry placeholder, not a crash.
+            expect(out).toContain("registry unreachable");
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    // --check reports the registry's latest version when reachable, and notes
+    // "already up to date" when it equals the current version.
+    it("--check reports the npm registry latest version", async () => {
+        const current = readVersion();
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn(async () => {
+            return new Response(JSON.stringify({ version: current }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        });
+        try {
+            let code = -1;
+            const out = await captureStdout(async () => {
+                code = await run(["update", "--check"]);
+            });
+            expect(code).toBe(exitOK);
+            expect(out).toContain(`latest:  ${current}`);
+            expect(out).toContain("already up to date");
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    // Plain `update` prints the npm install instruction and exits 0 — it does not
+    // attempt any self-replace (the Go behavior is intentionally not ported).
+    it("plain update prints the npm install instruction (exit 0)", async () => {
+        let code = -1;
+        const out = await captureStdout(async () => {
+            code = await run(["update"]);
+        });
+        expect(code).toBe(exitOK);
+        expect(out).toContain("npm install -g docgov@latest");
+    });
+    // `update --version <tag>` is shadowed by commander's program-level --version
+    // flag (added by .version()), which prints the program version and exits 0
+    // before the subcommand action runs. WHY this matters: it pins the real,
+    // surprising precedence so a future change that re-enables the subcommand
+    // tag (and would alter exit semantics) is caught — the flag does NOT print
+    // install guidance today.
+    it("update --version <tag> hits the program version flag (prints version, exit 0)", async () => {
+        let code = -1;
+        const out = await captureStdout(async () => {
+            code = await run(["update", "--version", "v1.2.3"]);
+        });
+        expect(code).toBe(exitOK);
+        expect(out.trim()).toBe(readVersion());
+        expect(out).not.toContain("npm install");
+    });
+    // --check reports a NEWER registry version (different from current) WITHOUT
+    // the "already up to date" line — that line must appear only on an exact match
+    // or the user would be told they are current when an upgrade exists.
+    it("--check reports a newer version and omits 'already up to date'", async () => {
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn(async () => {
+            return new Response(JSON.stringify({ version: "999.999.999" }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        });
+        try {
+            let code = -1;
+            const out = await captureStdout(async () => {
+                code = await run(["update", "--check"]);
+            });
+            expect(code).toBe(exitOK);
+            expect(out).toContain("latest:  999.999.999");
+            expect(out).not.toContain("already up to date");
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    // A non-OK HTTP status (resp.ok === false) is treated as unreachable, not a
+    // crash — fetchLatestVersion's status guard. A 500 from the registry must
+    // degrade to the unreachable placeholder, exit 0.
+    it("--check treats a non-OK HTTP status as unreachable (exit 0)", async () => {
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn(async () => {
+            return new Response("oops", { status: 500 });
+        });
+        try {
+            let code = -1;
+            const out = await captureStdout(async () => {
+                code = await run(["update", "--check"]);
+            });
+            expect(code).toBe(exitOK);
+            expect(out).toContain("registry unreachable");
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    // A 200 body that lacks a string "version" field yields null (not a thrown
+    // error) — the typeof guard in fetchLatestVersion. Malformed registry JSON
+    // must not crash the update command.
+    it("--check treats a version-less 200 body as unreachable (exit 0)", async () => {
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn(async () => {
+            return new Response(JSON.stringify({ notversion: 1 }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        });
+        try {
+            let code = -1;
+            const out = await captureStdout(async () => {
+                code = await run(["update", "--check"]);
+            });
+            expect(code).toBe(exitOK);
+            expect(out).toContain("registry unreachable");
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+});
+describe("dedup command", () => {
+    // The dedup action runs Index (which loads the dedup config) before anything
+    // else. A malformed .docgov/dedup/config.yml makes Load throw, which must map
+    // to a usage/config error (exit 2) — NOT exit 1 (which means duplicates were
+    // found) and NOT a crash. This exercises runDedupAction's Index call and the
+    // engine-error → exit-2 mapping without triggering a model download (Load
+    // throws first). Falsifiable: swallowing the error would change the code to 0.
+    it("malformed dedup config exits 2 (usage)", async () => {
+        const tmp = makeNewSchemaRepo("doc:\n  boundary:\n    - docs/**\n", {
+            ".docgov/dedup/config.yml": ": : : not valid yaml ][\n",
+            "docs/guide.md": "# Guide\n\nHello.\n",
+        });
+        const restore = silenceStderr();
+        let code = -1;
+        await withCwd(tmp, () => captureStdout(async () => {
+            code = await run(["dedup"]);
+        }));
+        restore();
+        expect(code).toBe(exitUsage);
+    });
+});
+// readVersion returns a non-empty string (package.json version or the "dev"
+// fallback) — the npm analogue of Go's ldflags-stamped main.version.
+describe("readVersion", () => {
+    it("returns the package.json version", () => {
+        const v = readVersion();
+        expect(typeof v).toBe("string");
+        expect(v.length).toBeGreaterThan(0);
+    });
+});

package/dist/codeq/cache.js

@@ -0,0 +1,71 @@
+import { isNotExist } from "../repo/fs.js";
+import { FileNotFoundError } from "./errors.js";
+// cache.ts ports internal/codeq/cache.go: the per-file source cache for the
+// lifetime of one resolver instance (one check run). Each file is read at most
+// once, even under concurrent Resolve calls.
+//
+// DEVIATION (recorded): the Go cache stores raw []byte and operates on bytes
+// (tree-sitter-go slices []byte directly). web-tree-sitter operates on JS
+// strings (node.text is UTF-16; offsets are UTF-16, see treesitter.ts), so this
+// cache DECODES the file to a STRING once and caches the string. The decode is
+// the cache's job so every resolver receives ready-to-parse source.
+//
+// CONCURRENCY: Go holds a mutex across the I/O so two goroutines racing on a
+// miss both wait for the single read. The JS analogue caches the in-flight
+// Promise (not just the resolved value): concurrent reads of the same path share
+// one Promise, so readFile runs exactly once per path. This preserves the
+// behaviour TestSourceCache encodes (8 concurrent reads → 1 underlying read).
+const decoder = new TextDecoder("utf-8");
+/**
+ * SourceCache caches decoded source strings by file path. Construct one per
+ * resolver instance (one check run).
+ */
+export class SourceCache {
+    // Caches the in-flight or settled Promise per path. Caching the Promise (not
+    // the string) is what gives the single-read guarantee under concurrency: a
+    // second caller on a miss finds the first caller's pending Promise and awaits
+    // it rather than issuing its own read.
+    byPath = new Map();
+    /**
+     * read returns the decoded source for the file at `path` in `root`. The result
+     * is cached: subsequent calls with the same path return the cached string
+     * without performing another read.
+     *
+     * A missing file (FS readFile throws ENOENT) is mapped to FileNotFoundError,
+     * mirroring Go's ErrFileNotFound wrap. Any other I/O fault propagates.
+     *
+     * This is async because FS.readFile is async (the TS FS abstraction is
+     * Promise-based); the dispatch layer awaits it before calling the SYNC
+     * per-language resolver. See resolver.ts for why resolve itself stays sync.
+     */
+    read(root, path) {
+        const cached = this.byPath.get(path);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const p = this.load(root, path);
+        this.byPath.set(path, p);
+        // If the read fails, evict so a later call can retry rather than caching the
+        // rejection forever (Go re-reads on the next call after an error too — it
+        // only caches on success).
+        p.catch(() => {
+            if (this.byPath.get(path) === p) {
+                this.byPath.delete(path);
+            }
+        });
+        return p;
+    }
+    async load(root, path) {
+        let bytes;
+        try {
+            bytes = await root.readFile(path);
+        }
+        catch (err) {
+            if (isNotExist(err)) {
+                throw new FileNotFoundError(path);
+            }
+            throw err;
+        }
+        return decoder.decode(bytes);
+    }
+}

package/dist/codeq/cache.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { SourceCache } from "./cache.js";
+import { FileNotFoundError } from "./errors.js";
+// WHY: without caching, every Resolve issues a readFile — wasteful, and it
+// compounds latency for runs that check many refs within one file. The cache
+// must read each file at MOST once per instance, even under concurrent access:
+// the Go version holds a mutex across the I/O so racing callers share one read.
+// The TS analogue caches the in-flight Promise; this test pins that 8 concurrent
+// reads of the same path cause exactly ONE underlying readFile. (Port of
+// internal/codeq/cache_test.go TestSourceCache, adapted to the async FS.)
+const enc = new TextEncoder();
+/** countingFS counts readFile calls and serves an in-memory file table. */
+class CountingFS {
+    files;
+    reads = 0;
+    constructor(files) {
+        this.files = files;
+    }
+    async readFile(name) {
+        this.reads++;
+        const content = this.files[name];
+        if (content === undefined) {
+            // Mirror Node's ENOENT so isNotExist() recognises it.
+            const err = new Error(`ENOENT: ${name}`);
+            err.code = "ENOENT";
+            throw err;
+        }
+        return enc.encode(content);
+    }
+    // Unused by SourceCache; present to satisfy the FS contract.
+    async readDir() {
+        return [];
+    }
+    sub() {
+        return this;
+    }
+}
+describe("SourceCache", () => {
+    it("reads each path at most once across sequential calls", async () => {
+        const fs = new CountingFS({ "pkg/foo.go": "package pkg\nfunc A(){}\n" });
+        const cache = new SourceCache();
+        const a = await cache.read(fs, "pkg/foo.go");
+        const b = await cache.read(fs, "pkg/foo.go");
+        expect(a).toBe(b); // identical cached value
+        expect(a).toBe("package pkg\nfunc A(){}\n"); // decoded to a STRING (deviation)
+        expect(fs.reads).toBe(1);
+    });
+    it("reads exactly once under 8 concurrent readers of the same path", async () => {
+        const fs = new CountingFS({ "pkg/foo.go": "package pkg\nfunc A(){}\n" });
+        const cache = new SourceCache();
+        // Fire all 8 before awaiting any: they all hit the same in-flight Promise.
+        const results = await Promise.all(Array.from({ length: 8 }, () => cache.read(fs, "pkg/foo.go")));
+        for (const r of results)
+            expect(r).toBe("package pkg\nfunc A(){}\n");
+        expect(fs.reads).toBe(1);
+    });
+    it("maps a missing file to FileNotFoundError and does not cache the failure", async () => {
+        const fs = new CountingFS({});
+        const cache = new SourceCache();
+        // WHY: absence must surface as FileNotFoundError (Go's ErrFileNotFound), not
+        // a generic throw — the check layer distinguishes "file gone" from "symbol
+        // absent". And a failed read must not be cached, so a later call retries.
+        await expect(cache.read(fs, "missing.go")).rejects.toBeInstanceOf(FileNotFoundError);
+        await expect(cache.read(fs, "missing.go")).rejects.toBeInstanceOf(FileNotFoundError);
+        expect(fs.reads).toBe(2); // retried, not cached
+    });
+});

package/dist/codeq/errors.js

@@ -0,0 +1,52 @@
+// Package codeq resolves code references against the project source tree.
+// It is the only place tree-sitter touches docgov; every consumer above this
+// layer sees the Resolver interface as a boolean oracle.
+//
+// Go's codeq uses sentinel `var Err… = errors.New(…)` values wrapped with
+// `fmt.Errorf("%w: %q", …)`. We mirror each sentinel with a named Error
+// subclass so callers test `err instanceof XError` instead of string-matching,
+// and the offending path is carried in the message exactly as Go wraps it.
+/**
+ * FileNotFoundError is thrown when the referenced file does not exist in the
+ * given FS. It is distinct from ParseFailedError: "the file isn't there" vs
+ * "the file is there but couldn't be parsed".
+ *
+ * Go original: `ErrFileNotFound`, wrapped as `fmt.Errorf("%w: %q", …, path)`.
+ */
+export class FileNotFoundError extends Error {
+    constructor(path) {
+        super(`codeq: file not found: ${JSON.stringify(path)}`);
+        this.name = "FileNotFoundError";
+    }
+}
+/**
+ * ParseFailedError is thrown when tree-sitter produces a tree that contains
+ * ERROR nodes (i.e. the source is not valid for its language). The path is
+ * always included so callers can surface it to the user.
+ *
+ * Go original: `ErrParseFailed`, wrapped as `fmt.Errorf("%w: %q", …, path)`.
+ */
+export class ParseFailedError extends Error {
+    constructor(path) {
+        super(`codeq: parse failed: ${JSON.stringify(path)}`);
+        this.name = "ParseFailedError";
+    }
+}
+/**
+ * UnsupportedLanguageError is thrown when the file extension has no registered
+ * resolver. It is distinct from an operational failure — it means docgov has no
+ * grammar for that language, not that the symbol is absent.
+ *
+ * Go original: `ErrUnsupportedLanguage`, wrapped as `fmt.Errorf("%w: %q", …, ext)`.
+ */
+export class UnsupportedLanguageError extends Error {
+    constructor(ext) {
+        super(`codeq: unsupported language: ${JSON.stringify(ext)}`);
+        this.name = "UnsupportedLanguageError";
+    }
+}
+// DEVIATION (recorded): Go's ErrUnsupportedBuild / the nocodecheck build tag
+// (codeq_off.go) has no TS analogue. TS has no build tags; tree-sitter is always
+// available as the web-tree-sitter npm dep, so the "code-resolution support not
+// compiled in" path collapses to always-on. ErrUnsupportedBuild is intentionally
+// NOT ported.

package/dist/codeq/index.js

@@ -0,0 +1,11 @@
+// Public surface of the codeq package — the only place tree-sitter touches
+// docgov. Consumers above this layer see the Resolver/DefaultResolver boolean
+// oracle and the typed errors, never the binding.
+export { FileNotFoundError, ParseFailedError, UnsupportedLanguageError, } from "./errors.js";
+export { DefaultResolver, createDefaultResolver } from "./resolver.js";
+export { SourceCache } from "./cache.js";
+export { normalizeType, signaturesMatch } from "./signature.js";
+// Re-export the tree-sitter helpers the language resolver modules build on, so
+// resolvers import everything codeq-binding-related from "../index.js" (or the
+// specific module) and never reach for web-tree-sitter directly.
+export { Language, Node, Parser, compileQuery, loadGrammar, nodeText, parseTree, runQuery, } from "./treesitter.js";