docsgov 0.1.0

package/dist/check/run.test.js

@@ -0,0 +1,513 @@
+// Tests for the three-pass run pipeline (port of internal/check/run_test.go).
+//
+// These are behavior-encoding tests: each asserts WHY a guard fires (or stays
+// silent) for a specific drift shape, not merely that some count is produced.
+// A stub Resolver stands in for the codeq oracle (Go's runStubResolver) so the
+// code pass is exercised without a real tree-sitter parse.
+import * as nodefs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadConfig } from "../config/index.js";
+import { find } from "../repo/index.js";
+import { Rules } from "../violation/index.js";
+import { run } from "./run.js";
+// --- stub resolver ---
+/**
+ * StubResolver implements the check Resolver without tree-sitter. It returns the
+ * configured found value (or rejects with err) regardless of the ref — the
+ * analogue of Go's runStubResolver. This isolates the code pass's
+ * parse → source-scope → resolve orchestration from the real symbol oracle.
+ */
+class StubResolver {
+    found;
+    err;
+    constructor(found, err) {
+        this.found = found;
+        this.err = err;
+    }
+    resolve(_root, _ref) {
+        if (this.err !== undefined) {
+            return Promise.reject(this.err);
+        }
+        return Promise.resolve(this.found);
+    }
+}
+/**
+ * SuggestingResolver always reports a symbol absent and returns a fixed
+ * Suggestion, so the not-found path's "did you mean" wiring is exercised without
+ * a real tree-sitter parse.
+ */
+class SuggestingResolver {
+    sug;
+    constructor(sug) {
+        this.sug = sug;
+    }
+    resolve(_root, _ref) {
+        return Promise.resolve(false);
+    }
+    suggest(_root, _ref) {
+        return Promise.resolve(this.sug);
+    }
+}
+// --- temp-repo helper ---
+const createdRoots = [];
+afterEach(async () => {
+    for (const root of createdRoots.splice(0)) {
+        await nodefs.rm(root, { recursive: true, force: true });
+    }
+});
+/**
+ * tempRepo creates a temp dir, writes the given files (map path→content), and
+ * creates a .docgov/ sentinel dir so find() anchors there. Mirrors the Go
+ * tempRepo helper.
+ */
+async function tempRepo(files) {
+    const root = await nodefs.realpath(await nodefs.mkdtemp(path.join(os.tmpdir(), "docgov-check-")));
+    createdRoots.push(root);
+    await nodefs.mkdir(path.join(root, ".docgov"), { recursive: true });
+    for (const [rel, content] of Object.entries(files)) {
+        const abs = path.join(root, ...rel.split("/"));
+        await nodefs.mkdir(path.dirname(abs), { recursive: true });
+        await nodefs.writeFile(abs, content);
+    }
+    return find(root);
+}
+// --- config builders ---
+function cfgCode(boundary, source) {
+    return { Code: { boundary, source } };
+}
+function cfgDoc(boundary) {
+    return { Doc: { boundary, source: [] } };
+}
+function cfgAPI(boundary, source) {
+    return { API: { boundary, source } };
+}
+// openAPIFixtureJSON: GET /api/v1/items with query param "filter", header
+// "X-Trace", body field "name" (+ nested.field), and response field "id".
+const openAPIFixtureJSON = `{
+  "openapi": "3.1.0",
+  "info": {"title": "Test", "version": "1"},
+  "paths": {
+    "/api/v1/items": {
+      "get": {
+        "parameters": [
+          {"name": "filter", "in": "query", "schema": {"type": "string"}},
+          {"name": "X-Trace", "in": "header", "schema": {"type": "string"}}
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {"type": "string"},
+                  "nested": {
+                    "type": "object",
+                    "properties": {"field": {"type": "string"}}
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {"id": {"type": "string"}}
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+// --- CODE PASS ---
+describe("run / code pass", () => {
+    // A well-formed code ref that resolves must produce no code violation — the
+    // happy path the whole pipeline exists to certify.
+    it("emits no code violation for a valid resolved ref", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See {{code:internal/foo.go#Bar}} for details.\n",
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(true));
+        expect(vs.filter((v) => v.rule === Rules.guardCode)).toEqual([]);
+    });
+    // A ref whose path is outside code.source must fail BEFORE resolution — the
+    // source-scope rule keeps docs from citing code the guard isn't told about.
+    it("flags a ref pointing outside code.source", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See {{code:vendor/lib.go#Foo}} for details.\n",
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(true));
+        const codeVs = vs.filter((v) => v.rule === Rules.guardCode);
+        expect(codeVs).toHaveLength(1);
+        expect(codeVs[0]?.message).toBe("ref points outside source");
+    });
+    // resolver found=false means the symbol is gone from the code — the core
+    // drift the code guard catches.
+    it("flags a symbol the resolver cannot find", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See {{code:internal/foo.go#Missing}} for details.\n",
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(false));
+        const codeVs = vs.filter((v) => v.rule === Rules.guardCode);
+        expect(codeVs).toHaveLength(1);
+        expect(codeVs[0]?.message).toBe("referenced symbol not found");
+        expect(codeVs[0]?.expected).toBe("symbol exists");
+    });
+    // When the resolver supplies a suggestion, the not-found message carries a
+    // "did you mean" — proving run wires resolver.suggest into the message.
+    it("appends a did-you-mean clause when the resolver suggests candidates", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See {{code:internal/foo.go#Missing}} for details.\n",
+        });
+        const resolver = new SuggestingResolver({
+            kind: "symbol",
+            candidates: ["Mission", "Other"],
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, resolver);
+        const codeVs = vs.filter((v) => v.rule === Rules.guardCode);
+        expect(codeVs).toHaveLength(1);
+        expect(codeVs[0]?.message).toBe("referenced symbol not found (did you mean: Mission?)");
+    });
+    // A malformed token must fail at parse time with a malformed-ref message, so
+    // an author gets a syntax signal rather than a misleading "not found".
+    it("flags a malformed code token", async () => {
+        const r = await tempRepo({ "docs/guide.md": "See {{code:}} for details.\n" });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(true));
+        const codeVs = vs.filter((v) => v.rule === Rules.guardCode);
+        expect(codeVs).toHaveLength(1);
+        expect(codeVs[0]?.message.startsWith("malformed code ref")).toBe(true);
+    });
+    // An absent cfg.Code section must skip the code pass entirely — undefined is
+    // the "this guard is not configured" signal.
+    it("runs no code pass when cfg.Code is undefined", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See {{code:internal/foo.go#Bar}} for details.\n",
+        });
+        const vs = await run({}, r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardCode)).toEqual([]);
+    });
+    // A {{code:…}} inside an inline code span documents the GRAMMAR and must NOT
+    // be checked, while the same token in prose IS — the code-span rule that keeps
+    // the guard's own grammar docs from self-tripping.
+    it("checks a prose code token but skips one in a code span", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "Grammar is `{{code:vendor/lib.go#X}}`.\n\nLive ref {{code:vendor/lib.go#Y}} here.\n",
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(true));
+        const codeVs = vs.filter((v) => v.rule === Rules.guardCode);
+        // Only the prose token is live; it is outside source → exactly one violation.
+        expect(codeVs).toHaveLength(1);
+        expect(codeVs[0]?.actual).toBe("{{code:vendor/lib.go#Y}}");
+    });
+    // A {{code:…}} inside a fenced code block is grammar documentation and must
+    // not be checked, even though it sits outside source.
+    it("skips a code token inside a fenced code block", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "```\n{{code:vendor/lib.go#Z}}\n```\n",
+        });
+        const vs = await run(cfgCode(["docs/**"], ["internal/**"]), r, new StubResolver(true));
+        expect(vs.filter((v) => v.rule === Rules.guardCode)).toEqual([]);
+    });
+});
+// --- DOC PASS ---
+describe("run / doc pass", () => {
+    // A relative link to an existing file must pass — the doc guard only fires on
+    // real breakage.
+    it("emits no doc violation for a valid relative link", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [other](other.md) for details.\n",
+            "docs/other.md": "# Other\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toEqual([]);
+    });
+    // A relative link to a nonexistent file is a dangling reference — the canonical
+    // doc-guard violation.
+    it("flags a dangling relative link", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [missing](missing.md) for details.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        const docVs = vs.filter((v) => v.rule === Rules.guardDocs);
+        expect(docVs).toHaveLength(1);
+        expect(docVs[0]?.message).toBe("referenced file does not exist");
+    });
+    // External URLs are not files to check; skipping them keeps the guard scoped
+    // to in-repo references.
+    it("skips external https URLs", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [external](https://example.com) for info.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toEqual([]);
+    });
+    // A bare "#anchor" is an in-page link, not a file reference, so it is skipped.
+    it("skips pure fragment links", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [section](#heading) for info.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toEqual([]);
+    });
+    // An absolute path is rejected outright (not stat'd): it cannot be repo-relative
+    // and would leak the host layout.
+    it("rejects an absolute link path", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [absolute](/etc/passwd) for info.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        const docVs = vs.filter((v) => v.rule === Rules.guardDocs);
+        expect(docVs).toHaveLength(1);
+        expect(docVs[0]?.message).toBe("absolute path is not allowed");
+    });
+    // A path that climbs above the repo root is rejected — references must stay
+    // inside the governed tree.
+    it("rejects a path escaping the repo root", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [escape](../../outside.md) for info.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        const docVs = vs.filter((v) => v.rule === Rules.guardDocs);
+        expect(docVs).toHaveLength(1);
+        expect(docVs[0]?.message).toBe("path escapes repo root");
+    });
+    // A "file.md#frag" link must strip the fragment and still pass when the base
+    // file exists — fragments name in-page anchors, not separate files.
+    it("strips a fragment and passes when the base file exists", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [other](other.md#section) for details.\n",
+            "docs/other.md": "# Other\n## Section\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toEqual([]);
+    });
+    // Stripping the fragment must still leave the base path subject to existence
+    // checking — a dangling "missing.md#x" is still dangling.
+    it("flags a fragment link whose base file is missing", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "See [other](nonexistent.md#section) for details.\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toHaveLength(1);
+    });
+    // An image src is existence-checked exactly like a link — broken images are
+    // doc drift too.
+    it("checks image destinations like links", async () => {
+        const r = await tempRepo({
+            "docs/guide.md": "![logo](../assets/logo.png)\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardDocs)).toHaveLength(1);
+    });
+    // Regression: an empty-alt image to a missing file must yield a violation with
+    // a sane line, not crash (the Go port had an inline-node Lines() panic here).
+    it("handles an empty-alt image without crashing", async () => {
+        const r = await tempRepo({ "docs/guide.md": "![](./missing.png)\n" });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        const docVs = vs.filter((v) => v.rule === Rules.guardDocs);
+        expect(docVs).toHaveLength(1);
+        expect(docVs[0]?.line).toBeGreaterThanOrEqual(1);
+    });
+    // Regression: a link whose text is an inline-code span (not plain text) must
+    // not crash and must still be existence-checked.
+    it("handles an inline-code link text without crashing", async () => {
+        const r = await tempRepo({ "docs/guide.md": "[`code`](./missing.md)\n" });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        const docVs = vs.filter((v) => v.rule === Rules.guardDocs);
+        expect(docVs).toHaveLength(1);
+        expect(docVs[0]?.line).toBeGreaterThanOrEqual(1);
+    });
+});
+// --- API PASS ---
+describe("run / api pass", () => {
+    // A token for a real operation passes — the api guard certifies live endpoints.
+    it("emits no api violation for a real operation", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Use {{api: GET /api/v1/items}} to list items.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toEqual([]);
+    });
+    // An operation absent from the spec is the canonical api drift.
+    it("flags an unknown operation", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Use {{api: DELETE /api/v1/items}} to delete.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        const apiVs = vs.filter((v) => v.rule === Rules.guardAPI);
+        expect(apiVs).toHaveLength(1);
+        expect(apiVs[0]?.message).toBe("operation DELETE /api/v1/items not found in spec");
+    });
+    // A nested body field that exists must pass — the qualifier walks the schema.
+    it("passes a body:nested.field that exists", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Field {{api: GET /api/v1/items body:nested.field}} docs.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toEqual([]);
+    });
+    // A body field absent from the schema fails the qualifier.
+    it("flags a body field that does not exist", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Field {{api: GET /api/v1/items body:bogus}} docs.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toHaveLength(1);
+    });
+    // A param qualifier naming a nonexistent param fails.
+    it("flags a param that does not exist", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Use {{api: GET /api/v1/items param:nonexistent}} param.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toHaveLength(1);
+    });
+    // body:filter must fail: "filter" is a QUERY param, not a body field — proving
+    // the body region is enforced, not just any-name-anywhere.
+    it("rejects a param name used in the body region", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Field {{api: GET /api/v1/items body:filter}} is a param.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toHaveLength(1);
+    });
+    // param:name must fail: "name" is a BODY field, not a param — proving the
+    // param region is enforced.
+    it("rejects a body field name used in the param region", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Param {{api: GET /api/v1/items param:name}} is a body field.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI)).toHaveLength(1);
+    });
+    // A non-JSON spec under api.source must surface a load violation, not silently
+    // pass references against an empty model.
+    it("flags a bad JSON spec", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": "not valid json{{",
+            "docs/api.md": "Use {{api: GET /api/v1/items}} here.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI).length).toBeGreaterThanOrEqual(1);
+    });
+    // api.source matching no spec files must produce a zero-spec violation — a
+    // configured api guard with no spec is a misconfiguration, not a silent pass.
+    it("flags zero specs found", async () => {
+        const r = await tempRepo({
+            "docs/api.md": "Use {{api: GET /api/v1/items}} here.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        expect(vs.filter((v) => v.rule === Rules.guardAPI).length).toBeGreaterThanOrEqual(1);
+    });
+    // A malformed token surfaces a malformed-ref message even with a valid spec.
+    it("flags a malformed api token", async () => {
+        const r = await tempRepo({
+            "api/spec/openapi.json": openAPIFixtureJSON,
+            "docs/api.md": "Use {{api:}} here.\n",
+        });
+        const vs = await run(cfgAPI(["docs/**"], ["api/spec/**"]), r, new StubResolver(false));
+        const apiVs = vs.filter((v) => v.rule === Rules.guardAPI);
+        expect(apiVs).toHaveLength(1);
+        expect(apiVs[0]?.message.startsWith("malformed api ref")).toBe(true);
+    });
+});
+// --- E2E + ORDERING ---
+describe("run / e2e", () => {
+    // A clean tree configured with all three guards must produce zero violations
+    // when loaded from a real docgov.yaml — the end-to-end happy path.
+    it("returns no violations for a clean tree across all three guards", async () => {
+        const r = await tempRepo({
+            ".docgov/docgov.yaml": `
+code:
+  boundary: [docs/**]
+  source:   [src/**]
+doc:
+  boundary: [docs/**]
+api:
+  boundary: [docs/**]
+  source:   [api/**]
+`,
+            "src/main.go": "package main\n",
+            "api/openapi.json": openAPIFixtureJSON,
+            "docs/guide.md": "# Guide\n\nSee [api](api.md) for API docs.\n",
+            "docs/api.md": "# API\n\nUse {{api: GET /api/v1/items}} to list items.\n",
+        });
+        const cfg = await loadConfig(r.fs());
+        const vs = await run(cfg, r, new StubResolver(true));
+        expect(vs).toEqual([]);
+    });
+    // A drifted tree must yield exactly one violation per guard — proving the three
+    // passes run independently and collect together.
+    it("returns one violation per guard for a drifted tree", async () => {
+        const r = await tempRepo({
+            ".docgov/docgov.yaml": `
+code:
+  boundary: [docs/**]
+  source:   [src/**]
+doc:
+  boundary: [docs/**]
+api:
+  boundary: [docs/**]
+  source:   [api/**]
+`,
+            "src/main.go": "package main\n",
+            "api/openapi.json": openAPIFixtureJSON,
+            "docs/guide.md": "# Guide\n\nSee [missing-file](nonexistent.md) for details.\n\nCheck {{code:vendor/lib.go#Foo}} which is outside source.\n",
+            "docs/api.md": "# API\n\nUse {{api: DELETE /api/v1/items}} to delete — this op doesn't exist.\n",
+        });
+        const cfg = await loadConfig(r.fs());
+        const vs = await run(cfg, r, new StubResolver(true));
+        const codeCount = vs.filter((v) => v.rule === Rules.guardCode).length;
+        const docCount = vs.filter((v) => v.rule === Rules.guardDocs).length;
+        const apiCount = vs.filter((v) => v.rule === Rules.guardAPI).length;
+        expect(codeCount).toBe(1);
+        expect(docCount).toBe(1);
+        expect(apiCount).toBe(1);
+        // Deterministic (file, line) ordering.
+        for (let i = 1; i < vs.length; i++) {
+            const prev = vs[i - 1];
+            const curr = vs[i];
+            const ordered = prev.file < curr.file ||
+                (prev.file === curr.file && prev.line <= curr.line);
+            expect(ordered).toBe(true);
+        }
+    });
+    // An all-undefined config must short-circuit to zero violations and no error.
+    it("returns no violations for an all-undefined config", async () => {
+        const r = await tempRepo({ "docs/guide.md": "# Hello\n" });
+        const vs = await run({}, r, new StubResolver(false));
+        expect(vs).toEqual([]);
+    });
+    // Violations from multiple files are returned sorted by (file, line), so the
+    // report is deterministic regardless of walk order.
+    it("sorts violations by file then line", async () => {
+        const r = await tempRepo({
+            "docs/b.md": "See [b1](b-missing.md).\nSee [b2](b-missing2.md).\n",
+            "docs/a.md": "See [a1](a-missing.md).\n",
+        });
+        const vs = await run(cfgDoc(["docs/**"]), r, new StubResolver(false));
+        expect(vs.length).toBeGreaterThanOrEqual(3);
+        for (let i = 1; i < vs.length; i++) {
+            const prev = vs[i - 1];
+            const curr = vs[i];
+            const ordered = prev.file < curr.file ||
+                (prev.file === curr.file && prev.line <= curr.line);
+            expect(ordered).toBe(true);
+        }
+    });
+});

package/dist/check/suggest.js

@@ -0,0 +1,134 @@
+// suggest.ts turns a codeq Suggestion (the raw candidate set behind a not-found
+// {{code:…}} ref) into the human "did you mean" / owner-missing clause appended
+// to the guard-code violation message. codeq extracts the candidates from the
+// parse tree; this module owns the ranking and the wording.
+//
+// Ranking is edit-distance "did you mean", top-3: only candidates within
+// MAX_DISTANCE of the missing name are offered, so a genuinely-deleted symbol
+// (no near name) adds nothing rather than suggesting noise. An exact match is
+// excluded — it signals the name is right and a deeper facet (signature, param)
+// is what failed, where listing the name back would mislead.
+//
+// When nothing is within distance, member/param refs fall back to listing what
+// IS available on the container ("<owner> has: …") — a member set is small and
+// bounded, so a wholly-wrong name (e.g. Status.TEST vs ACTIVE/INACTIVE) still
+// gets a useful hint. Bare symbol refs stay distance-gated only: a file's symbol
+// set can be large, so listing it all would flood the message.
+// MAX_DISTANCE is the Levenshtein cutoff for a "did you mean" — the classic
+// spell-check threshold. A candidate further than this is treated as unrelated.
+const MAX_DISTANCE = 2;
+// MAX_SUGGESTIONS caps how many candidates are offered, closest first.
+const MAX_SUGGESTIONS = 3;
+// MAX_AVAILABLE caps the "<owner> has: …" fallback list; the rest collapse to a
+// "+N more" marker so a large class/enum never floods the line.
+const MAX_AVAILABLE = 8;
+/**
+ * suggestionSuffix renders the trailing clause for a not-found code ref, or ""
+ * when there is nothing useful to say. The leading space is included so callers
+ * append it directly to the base message.
+ *
+ *   owner missing → " (owner type Foo not found)" / " (function foo not found)"
+ *   near matches  → " (did you mean: bar, baz?)"
+ *   member/param, no near match → " (Foo has: a, b, c)" / " (foo has params: a, b)"
+ *   bare symbol, no near match  → ""
+ */
+export function suggestionSuffix(ref, sug) {
+    if (sug.ownerMissing !== undefined) {
+        const what = sug.kind === "member" ? "owner type" : "function";
+        return ` (${what} ${sug.ownerMissing} not found)`;
+    }
+    const target = targetName(ref, sug.kind);
+    const picks = rankCandidates(target, sug.candidates);
+    if (picks.length > 0) {
+        return ` (did you mean: ${picks.join(", ")}?)`;
+    }
+    // No near match. A member/param ref names ONE container, so its candidate set
+    // is small — list what's available rather than go silent (the Status.TEST
+    // case). A bare symbol ref can span a whole file, so it stays distance-gated.
+    // The target being AMONG the candidates means the name is right and a deeper
+    // facet (signature/param) failed — suppress there, don't echo the container.
+    if (sug.kind !== "symbol" &&
+        sug.candidates.length > 0 &&
+        !sug.candidates.includes(target)) {
+        return ` (${availableClause(ref.Symbol, sug.kind, sug.candidates)})`;
+    }
+    return "";
+}
+/**
+ * availableClause lists the names on a container whose member/param had no near
+ * match — "<owner> has: a, b, c" (members) or "<owner> has params: a, b" — capped
+ * at MAX_AVAILABLE with a "+N more" overflow marker. Names are de-duplicated and
+ * sorted so the output is deterministic.
+ */
+function availableClause(owner, kind, candidates) {
+    const names = [...new Set(candidates)].sort();
+    const shown = names.slice(0, MAX_AVAILABLE);
+    const extra = names.length - shown.length;
+    const list = shown.join(", ") + (extra > 0 ? `, +${extra} more` : "");
+    const verb = kind === "member" ? "has" : "has params";
+    return `${owner} ${verb}: ${list}`;
+}
+/** targetName is the name the author got wrong, by ref kind. */
+function targetName(ref, kind) {
+    switch (kind) {
+        case "member":
+            return ref.Member;
+        case "param":
+            return ref.Param;
+        case "symbol":
+            return ref.Symbol;
+    }
+}
+/**
+ * rankCandidates returns up to MAX_SUGGESTIONS candidate names within
+ * MAX_DISTANCE of `target`, closest first. Duplicates and exact matches are
+ * dropped; ties break alphabetically so the output is deterministic.
+ */
+function rankCandidates(target, candidates) {
+    const scored = [];
+    const seen = new Set();
+    for (const c of candidates) {
+        if (seen.has(c)) {
+            continue;
+        }
+        seen.add(c);
+        if (c === target) {
+            continue; // name is right; a deeper facet failed — don't echo it back.
+        }
+        const dist = levenshtein(target, c);
+        if (dist <= MAX_DISTANCE) {
+            scored.push({ name: c, dist });
+        }
+    }
+    scored.sort((a, b) => a.dist !== b.dist ? a.dist - b.dist : a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return scored.slice(0, MAX_SUGGESTIONS).map((s) => s.name);
+}
+/**
+ * levenshtein is the standard two-row edit-distance DP (insert/delete/substitute,
+ * cost 1 each). Case-sensitive, since the languages docgov resolves treat
+ * identifiers as case-sensitive.
+ */
+function levenshtein(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    let curr = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // delete
+            curr[j - 1] + 1, // insert
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}