docsgov 0.1.0

package/dist/check/suggest.test.js

@@ -0,0 +1,92 @@
+// Tests for suggestionSuffix — the "did you mean" / owner-missing clause appended
+// to a not-found guard-code violation. These encode WHY the ranking behaves as it
+// does: closest-first within a bounded edit distance, exact matches suppressed,
+// noise (no near name) producing nothing, and owner-missing phrased distinctly.
+import { describe, expect, it } from "vitest";
+import { suggestionSuffix } from "./suggest.js";
+/** ref builds a minimal CodeRef; only the facet under test needs a value. */
+function ref(parts) {
+    return { Path: "x.go", Symbol: "", Member: "", Param: "", ...parts };
+}
+describe("suggestionSuffix", () => {
+    // A single near miss is the headline case: a one-edit typo gets the real name
+    // back, and unrelated names are not offered.
+    it("offers the closest symbol for a one-edit typo and drops far names", () => {
+        const sug = {
+            kind: "symbol",
+            candidates: ["Bar", "Compute", "Qux"],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "Baz" }), sug)).toBe(" (did you mean: Bar?)");
+    });
+    // Ties at equal distance break alphabetically and the list is capped at three,
+    // so the output is deterministic and never floods the message.
+    it("returns the three closest, tie-broken alphabetically", () => {
+        const sug = {
+            kind: "symbol",
+            // all one edit from "bar": bare, barx, bat, car; "zzzzz" is far.
+            candidates: ["car", "bat", "barx", "bare", "zzzzz"],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "bar" }), sug)).toBe(" (did you mean: bare, barx, bat?)");
+    });
+    // A bare symbol ref with no near name must add nothing — a file's symbol set
+    // can be large, so listing it all would flood the message (symbols stay
+    // distance-gated; only member/param refs fall back to a list).
+    it("returns no clause for a symbol ref when nothing is within edit distance", () => {
+        const sug = { kind: "symbol", candidates: ["alpha", "beta"] };
+        expect(suggestionSuffix(ref({ Symbol: "xyzzy" }), sug)).toBe("");
+    });
+    // A wholly-wrong member name (nothing within edit distance) falls back to
+    // listing the owner's members — the Status.TEST case.
+    it("lists available members when the member name is wholly wrong", () => {
+        const sug = {
+            kind: "member",
+            candidates: ["ACTIVE", "INACTIVE", "PENDING"],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "Status", Member: "TEST" }), sug)).toBe(" (Status has: ACTIVE, INACTIVE, PENDING)");
+    });
+    // The param fallback names the function's params distinctly from members.
+    it("lists available params when the param name is wholly wrong", () => {
+        const sug = { kind: "param", candidates: ["input", "token"] };
+        expect(suggestionSuffix(ref({ Symbol: "Compute", Param: "xyz" }), sug)).toBe(" (Compute has params: input, token)");
+    });
+    // A large container collapses the tail into "+N more" so the line stays short.
+    it("caps the available list with a +N more marker", () => {
+        const sug = {
+            kind: "member",
+            candidates: ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "E", Member: "ZZZZ" }), sug)).toBe(" (E has: a, b, c, d, e, f, g, h, +2 more)");
+    });
+    // An exact match means the NAME is right and a deeper facet (signature, param)
+    // failed; both the "did you mean" AND the available-list are suppressed there,
+    // so the message never echoes the container the author already named.
+    it("suppresses everything when the name is exact (deeper facet failed)", () => {
+        const sug = { kind: "member", candidates: ["run", "walk"] };
+        expect(suggestionSuffix(ref({ Symbol: "T", Member: "run" }), sug)).toBe("");
+    });
+    // A member typo ranks against the owner's members (keyed on the member name,
+    // NOT the symbol — "Ctl" is far from both), closest first.
+    it("ranks member candidates against the member name", () => {
+        const sug = { kind: "member", candidates: ["Start", "Stop"] };
+        expect(suggestionSuffix(ref({ Symbol: "Ctl", Member: "Strt" }), sug)).toBe(" (did you mean: Start, Stop?)"); // Start d1 before Stop d2
+    });
+    // A missing owner TYPE is a different failure than a missing member: say so,
+    // rather than listing members of a type that isn't there.
+    it("reports a missing owner type distinctly for member refs", () => {
+        const sug = {
+            kind: "member",
+            ownerMissing: "Ctlx",
+            candidates: [],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "Ctlx", Member: "Start" }), sug)).toBe(" (owner type Ctlx not found)");
+    });
+    // The same owner-missing signal on a param ref names the function, not a type.
+    it("reports a missing function distinctly for param refs", () => {
+        const sug = {
+            kind: "param",
+            ownerMissing: "prase",
+            candidates: [],
+        };
+        expect(suggestionSuffix(ref({ Symbol: "prase", Param: "input" }), sug)).toBe(" (function prase not found)");
+    });
+});

package/dist/check/tokens.js

@@ -0,0 +1,125 @@
+// Port of internal/check/codetokens.go + internal/check/apitokens.go.
+//
+// These scanners read raw markdown source, find every {{code:…}} / {{api:…}}
+// token, and exclude those whose start offset falls inside a code region —
+// fenced code block, indented code block, or inline code span. Tokens inside a
+// code region are GRAMMAR DOCUMENTATION, not live refs (the "code-span /
+// source-scope" rule), and must NOT be checked.
+//
+// Raw-source scanning (vs per-AST-text-node) is required so a token whose body
+// contains characters markdown would fragment across inline nodes ([]/<>/_) is
+// matched whole. The AST is used ONLY to compute the code regions to exclude.
+//
+// The Go original walks the goldmark AST and uses byte offsets; this port walks
+// the mdast tree (remark-parse + remark-gfm) and uses string character offsets.
+// Everything operates on the same decoded string, so offsets are internally
+// consistent (and identical to bytes for the ASCII token bodies docgov scans).
+import { parseMarkdown } from "../dedup/mdsection/index.js";
+/**
+ * codeTokenRE matches a {{code:…}} token anywhere in a text span. It does not
+ * validate the grammar — parseCodeRef is responsible for that. The match
+ * captures the full token text. Mirrors Go's `\{\{code:[^}]*\}\}`.
+ */
+const codeTokenRE = /\{\{code:[^}]*\}\}/g;
+/**
+ * apiTokenRE matches a whole {{api:…}} token in prose. The body permits
+ * single-level "{var}" groups (OpenAPI path templates) so `{{api: GET /x/{id}}}`
+ * matches up to the final "}}", unlike a naive `[^}]*`. Mirrors Go's
+ * `\{\{api:[^{}]*(?:\{[^{}]*\}[^{}]*)*\}\}`.
+ */
+const apiTokenRE = /\{\{api:[^{}]*(?:\{[^{}]*\}[^{}]*)*\}\}/g;
+/**
+ * lineOfOffset returns the 1-based line number for a given character offset in
+ * src. It counts the newlines before the offset and adds 1. Mirrors Go's
+ * lineOfOffset (which counts bytes; identical for the ASCII content scanned).
+ */
+function lineOfOffset(src, offset) {
+    if (offset <= 0) {
+        return 1;
+    }
+    if (offset > src.length) {
+        offset = src.length;
+    }
+    let count = 0;
+    for (let i = 0; i < offset; i++) {
+        if (src.charCodeAt(i) === 0x0a) {
+            count++;
+        }
+    }
+    return count + 1;
+}
+/**
+ * codeRegions walks the mdast tree and returns the source char ranges of fenced
+ * code blocks, indented code blocks, and inline code spans — the regions whose
+ * {{code:…}} / {{api:…}} tokens document the grammar and must not be scanned as
+ * live refs.
+ *
+ * mdast collapses goldmark's KindFencedCodeBlock and KindCodeBlock into a single
+ * "code" node and KindCodeSpan into "inlineCode". Each node's position covers the
+ * whole construct (including fences / backtick delimiters), which is a superset
+ * of goldmark's content-only Lines() range; a token inside the construct still
+ * falls within that range, so the exclusion is faithful.
+ */
+function codeRegions(tree) {
+    const regions = [];
+    const visit = (n) => {
+        if (n.type === "code" || n.type === "inlineCode") {
+            const pos = n.position;
+            if (pos !== undefined &&
+                pos.start.offset !== undefined &&
+                pos.end.offset !== undefined) {
+                regions.push({ start: pos.start.offset, stop: pos.end.offset });
+            }
+            // Do not descend into code nodes (mirrors WalkSkipChildren).
+            return;
+        }
+        const children = n.children;
+        if (children !== undefined) {
+            for (const c of children) {
+                visit(c);
+            }
+        }
+    };
+    visit(tree);
+    return regions;
+}
+/**
+ * scanTokens scans the raw source with re, skipping any match whose start offset
+ * falls inside a code region. Shared by iterCodeTokens and iterApiTokens.
+ */
+function scanTokens(src, re) {
+    const tree = parseMarkdown(src);
+    const regions = codeRegions(tree);
+    const inRegion = (off) => {
+        for (const r of regions) {
+            if (off >= r.start && off < r.stop) {
+                return true;
+            }
+        }
+        return false;
+    };
+    const locs = [];
+    for (const m of src.matchAll(re)) {
+        const start = m.index;
+        if (inRegion(start)) {
+            continue;
+        }
+        locs.push({ token: m[0], line: lineOfOffset(src, start) });
+    }
+    return locs;
+}
+/**
+ * iterCodeTokens scans the raw source for every {{code:…}} token, skipping any
+ * inside a code region (fence / indented block / inline span). Tokens in code
+ * regions document the grammar, not live refs. Tokens in prose are checked.
+ */
+export function iterCodeTokens(src) {
+    return scanTokens(src, codeTokenRE);
+}
+/**
+ * iterApiTokens scans the raw source for every {{api:…}} token, skipping any
+ * inside a code region. Reuses the same region logic as iterCodeTokens.
+ */
+export function iterApiTokens(src) {
+    return scanTokens(src, apiTokenRE);
+}

package/dist/cmd/main.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+// Command docgov is the CLI entrypoint for the docgov documentation-governance
+// engine. Port of cmd/docgov/{main,dedup_on,dedup_off,update}.go.
+//
+// PORTING NOTES (deviations recorded prominently):
+//
+//   1. CLI library: Go used urfave/cli/v3; this port uses `commander`. The
+//      command names, usage strings, flag names, and the 0/1/2 EXIT-CODE
+//      contract are preserved exactly; only the framework differs.
+//
+//   2. Version source: Go injected the version via -ldflags "-X main.version".
+//      npm has no ldflags, so the version is read from package.json at runtime
+//      (see readVersion). The Go default "dev" is used as a fallback when
+//      package.json cannot be read.
+//
+//   3. dedup build tags: Go gated the real dedup impl (dedup_on.go) behind
+//      !nodedup and shipped a stub (dedup_off.go) for cross-compiled binaries.
+//      TS has no build tags, so dedup is ALWAYS ON — the off-stub is dropped.
+//
+//   4. update command: Go's update.go downloaded a GitLab release asset and
+//      replaced the running binary in place. That is incompatible with npm
+//      distribution (the binary is managed by npm, not self-replaced), so the
+//      GitLab-download + self-replace logic is NOT ported. Instead `update`
+//      is an npm-appropriate command:
+//        - `update --check` reports the current version and the latest version
+//          from the npm registry (best-effort; handles offline gracefully);
+//        - plain `update` prints guidance to run `npm install -g docgov@latest`.
+//      The `--version <tag>` flag is kept for compatibility (it is reported back
+//      in the install guidance). The asset-name mapping and replaceExecutable
+//      logic from update.go have no npm analogue and are omitted.
+//
+//   5. Shebang flag: the dedup index uses the built-in node:sqlite module, which
+//      is experimental and makes Node print an "ExperimentalWarning: SQLite ..."
+//      line to stderr on every invocation. node:sqlite is a STATIC import, so a
+//      userland process.emitWarning wrapper cannot suppress it — the builtin is
+//      initialized at module-link time, before any of our code runs. The shebang
+//      therefore launches node with `--disable-warning=ExperimentalWarning`
+//      (env -S splits the args) so the installed `docgov` runs clean. Requires
+//      Node >=22 (engines) where the flag exists.
+import { fileURLToPath } from "node:url";
+import { readFileSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { Command, CommanderError } from "commander";
+import { run as checkRun } from "../check/index.js";
+import { createDefaultResolver } from "../codeq/index.js";
+import { loadConfig } from "../config/index.js";
+import { find } from "../repo/index.js";
+import { text as reportText, json as reportJSON } from "../report/index.js";
+import { Index, Analyze, Load } from "../dedup/index.js";
+import { Render } from "../dedup/report/index.js";
+// Exit-code convention (mirrors Go's main.go exactly):
+//
+//   0 — success
+//   1 — check completed and found violations (or dedup found duplicates)
+//   2 — usage or configuration error
+const exitOK = 0;
+const exitViolation = 1;
+const exitUsage = 2;
+// ViolationsError is the cmd-owned sentinel returned by the check action when a
+// doc fails governance (violations found). It is the only path (alongside
+// DuplicatesError) to exitViolation; every other error maps to exitUsage, so
+// the engine never inherits the CLI framework's own exit codes. Analogue of
+// Go's errViolations.
+class ViolationsError extends Error {
+    constructor() {
+        super("violations found");
+        this.name = "ViolationsError";
+    }
+}
+// DuplicatesError is the cmd-owned sentinel returned by the dedup action when at
+// least one HIGH-confidence duplicate group is found. Maps to exitViolation so
+// CI can gate on duplicates found — parallel role to ViolationsError. Analogue
+// of Go's errDuplicates.
+class DuplicatesError extends Error {
+    constructor() {
+        super("duplicates found");
+        this.name = "DuplicatesError";
+    }
+}
+// readVersion reads the package version from package.json, walking up from this
+// module's directory until a package.json is found (works both from src/ under
+// tsx and from dist/ after a build). Falls back to Go's "dev" sentinel if it
+// cannot be located — the same default Go used before ldflags stamped it.
+export function readVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = path.join(dir, "package.json");
+        try {
+            const raw = readFileSync(candidate, "utf8");
+            const pkg = JSON.parse(raw);
+            if (typeof pkg.version === "string" && pkg.version !== "") {
+                return pkg.version;
+            }
+        }
+        catch {
+            // not here; keep walking up
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return "dev";
+        }
+        dir = parent;
+    }
+}
+// findRepo locates the repo root from CWD. It is the shared first step for every
+// command that touches the filesystem (Go's findRepo).
+async function findRepo() {
+    return find(process.cwd());
+}
+// runCheckAction implements the check command: load config, run check.Run, and
+// emit the report in the chosen format. Throws ViolationsError when violations
+// are found (mapped to exitViolation by run()); any other error maps to
+// exitUsage. Mirrors Go's runCheck.
+async function runCheckAction(format) {
+    switch (format) {
+        case "text":
+        case "json":
+            break;
+        default:
+            throw new Error(`check: unknown --format "${format}" (want text or json)`);
+    }
+    const r = await findRepo();
+    const cfg = await loadConfig(r.fs());
+    const resolver = await createDefaultResolver();
+    const vs = await checkRun(cfg, r, resolver);
+    // Emit the report.
+    if (format === "json") {
+        process.stdout.write(reportJSON(vs) + "\n");
+    }
+    else {
+        const out = reportText(vs);
+        if (out !== "") {
+            process.stdout.write(out);
+        }
+    }
+    if (vs.length > 0) {
+        throw new ViolationsError();
+    }
+}
+// runDedupAction implements "docgov dedup": find repo root → refresh the
+// embedding index → analyze → render the report. The index is rebuilt
+// automatically on every run, so there is no separate index step. Index
+// progress goes to stderr; the report goes to stdout. Throws DuplicatesError
+// when at least one HIGH-confidence group is found. Mirrors Go's runDedup.
+async function runDedupAction() {
+    const r = await findRepo();
+    await Index(r.root(), (msg) => {
+        process.stderr.write(msg.endsWith("\n") ? msg : msg + "\n");
+    });
+    const rep = await Analyze(r.root());
+    // Load config separately to obtain ReportConfig for the renderer (matching
+    // Go's second cheap Load to avoid changing the Analyze signature).
+    let cfg;
+    try {
+        cfg = await Load(r.root());
+    }
+    catch (err) {
+        throw new Error(`dedup: load config for render: ${errMsg(err)}`);
+    }
+    process.stdout.write(Render(rep, cfg.Report));
+    if (rep.HighGroups.length > 0) {
+        throw new DuplicatesError();
+    }
+}
+// runUpdateAction implements the npm-appropriate update command (see the
+// deviation note at the top of this file). With --check it reports the current
+// and latest versions; otherwise it prints install guidance. `version` is the
+// optional target tag, kept for compatibility with Go's --version flag.
+async function runUpdateAction(opts) {
+    const current = readVersion();
+    if (opts.check) {
+        const latest = await fetchLatestVersion();
+        process.stdout.write(`current: ${current}\n`);
+        process.stdout.write(`latest:  ${latest ?? "unknown (registry unreachable)"}\n`);
+        if (latest !== null && latest === current) {
+            process.stdout.write("already up to date\n");
+        }
+        return;
+    }
+    const target = opts.version !== undefined && opts.version !== ""
+        ? `docgov@${opts.version}`
+        : "docgov@latest";
+    process.stdout.write(`current: ${current}\n`);
+    process.stdout.write(`docgov is installed via npm; update it with:\n  npm install -g ${target}\n`);
+}
+// fetchLatestVersion queries the npm registry for the latest published version.
+// Best-effort: returns null on any network/parse failure (offline-safe) so the
+// update command degrades gracefully rather than erroring out.
+async function fetchLatestVersion() {
+    try {
+        const resp = await fetch("https://registry.npmjs.org/docgov/latest");
+        if (!resp.ok) {
+            return null;
+        }
+        const body = (await resp.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+// newApp wires all commands to their engine entry points. Mirrors Go's newApp.
+// Each action throws on failure; run() owns the 0/1/2 exit-code mapping.
+export function newApp(version) {
+    const app = new Command();
+    app
+        .name("docgov")
+        .usage("[command]")
+        .description("config-driven documentation governance")
+        .version(version)
+        // exitOverride makes commander THROW a CommanderError instead of calling
+        // process.exit, so run() is the single owner of the exit-code convention.
+        .exitOverride()
+        // Suppress commander's own "(see --help)" suggestion noise on errors; run()
+        // reports usage errors via stderr "docgov: ...".
+        .showSuggestionAfterError(false);
+    app
+        .command("check")
+        .description("validate docs/ against their governance config")
+        .option("--format <format>", "report format: text (styled) or json", "text")
+        .action(async (opts) => {
+        await runCheckAction(opts.format);
+    });
+    app
+        .command("update")
+        .description("report the latest docgov release (install via npm)")
+        .option("--version <tag>", "report guidance for a specific tag (e.g. v1.2.3)")
+        .option("--check", "report current and latest versions without installing", false)
+        .action(async (opts) => {
+        await runUpdateAction({
+            check: opts.check === true,
+            version: opts.version,
+        });
+    });
+    app
+        .command("dedup")
+        .description("detect and report duplicate documentation concepts in docs/")
+        .action(async () => {
+        await runDedupAction();
+    });
+    return app;
+}
+// run builds the CLI, executes it, and maps the result to an exit code. The CLI
+// framework neither prints generic usage dumps nor exits on its own (exitOverride
+// + the catch below) — this function is the single owner of the 0/1/2 convention.
+// Mirrors Go's run([]string) int.
+export async function run(argv) {
+    const app = newApp(readVersion());
+    // No subcommand → show help and exit 0 (Go's "no args shows help" → exitOK).
+    if (argv.length === 0) {
+        app.outputHelp();
+        return exitOK;
+    }
+    try {
+        await app.parseAsync(argv, { from: "user" });
+        return exitOK;
+    }
+    catch (err) {
+        if (err instanceof ViolationsError || err instanceof DuplicatesError) {
+            return exitViolation;
+        }
+        if (err instanceof CommanderError) {
+            // Help/version display are successful terminations (Go: --help exits 0).
+            if (err.code === "commander.helpDisplayed" ||
+                err.code === "commander.help" ||
+                err.code === "commander.version") {
+                return exitOK;
+            }
+            // Every other framework error (unknown command/option, missing arg) is a
+            // usage error → exit 2. Commander already wrote the message to stderr.
+            return exitUsage;
+        }
+        // Engine/config/operational error → exit 2 with the Go-style prefix.
+        process.stderr.write(`docgov: ${errMsg(err)}\n`);
+        return exitUsage;
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// main is the process entrypoint: run() with process.argv (minus node + script)
+// and exit with the mapped code. Mirrors Go's main(){ os.Exit(run(os.Args)) }.
+// Only invoked when this module is the entry script, so tests can import run()
+// without triggering process.exit.
+async function main() {
+    const code = await run(process.argv.slice(2));
+    // Flush stdout/stderr before exiting. When stdout is a pipe or file (not a
+    // TTY), Node buffers writes asynchronously; calling process.exit() directly
+    // would terminate before the buffer drains and silently truncate the report
+    // (a piped/redirected `docgov check` would print nothing). Draining both
+    // streams first guarantees the output is delivered; process.exit then forces
+    // termination so lingering tree-sitter/onnx handles cannot keep the process
+    // alive (Go used os.Exit for the same immediacy).
+    await Promise.all([drainStream(process.stdout), drainStream(process.stderr)]);
+    process.exit(code);
+}
+// drainStream resolves once everything already written to the stream has been
+// handed to the OS. Stream writes are ordered (FIFO), so the empty final chunk's
+// callback fires only after every prior write has flushed.
+function drainStream(stream) {
+    return new Promise((resolve) => {
+        stream.write("", () => resolve());
+    });
+}
+// Detect "run as the entry script" (NodeNext/ESM). When imported by tests,
+// import.meta.url !== the entry file URL, so main() is not called.
+//
+// The entry (process.argv[1]) must be resolved through realpathSync before
+// comparing: an npm-installed bin is reached via symlinks (bin/docgov →
+// lib/node_modules/docgov → this file), so path.resolve alone leaves it as the
+// symlink path and the comparison fails — which would make main() silently never
+// run when invoked as `docgov`. import.meta.url is already a realpath (Node
+// resolves module specifiers through realpath), so we realpath the entry to match.
+const invokedDirectly = (() => {
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        return false;
+    }
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(path.resolve(entry));
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    void main();
+}
+// Re-exported for tests (exit-code/version/wiring assertions).
+export { exitOK, exitViolation, exitUsage, ViolationsError, DuplicatesError };