docsgov 0.1.0

package/dist/report/report.test.js

@@ -0,0 +1,368 @@
+// Exercises the text and JSON renderers in the report package.
+//
+// WHY each test group exists (ported from internal/report/report_test.go):
+//
+//   - Text output is deterministic: violations must be sorted by file then by
+//     the order emitted (position). Non-deterministic output would make CI
+//     reports undiffable across runs, hiding real regressions.
+//
+//   - JSON output is stable-ordered: the JSON array must reflect the same sort
+//     order as text, and each object must have stable field order. Unstable JSON
+//     breaks the agent's ability to parse the correction signal reliably.
+//
+//   - Both formats must produce the same violation set — a violation visible in
+//     text but not in JSON (or vice-versa) would silently drop the agent's
+//     correction signal.
+//
+//   - Empty input produces valid (empty) output in both formats — a clean doc
+//     tree must not produce spurious output that triggers an exit 1.
+//
+// The exact-byte tests additionally pin the wire format because the golden-test
+// oracle compares this output byte-for-byte against the Go binary's output. The
+// oracle captures non-TTY stdout, where lipgloss renders spans as plain text;
+// these tests guard on colorEnabled === false so they assert the same plain
+// path and fail loudly if the environment unexpectedly turns color on.
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { text, json } from "./report.js";
+import { colorEnabled } from "./color.js";
+import { Rules } from "../violation/index.js";
+// sampleViolations returns a fixed, deterministic slice of violations used as
+// the canonical input for rendering tests. Mirrors the Go test fixture.
+function sampleViolations() {
+    return [
+        {
+            file: "docs/adr/0001.md",
+            line: 10,
+            sectionID: "",
+            rule: Rules.guardDocs,
+            expected: "",
+            actual: "",
+            message: "referenced file does not exist",
+        },
+        {
+            file: "docs/adr/0002.md",
+            line: 5,
+            sectionID: "",
+            rule: Rules.guardCode,
+            expected: "",
+            actual: "{{code:internal/foo.go#Bar}}",
+            message: "referenced symbol not found",
+        },
+        {
+            file: "docs/adr/0001.md",
+            line: 20,
+            sectionID: "",
+            rule: Rules.guardAPI,
+            expected: "",
+            actual: "{{api: GET /foo}}",
+            message: "endpoint not found in spec",
+        },
+    ];
+}
+// ── Text renderer tests ────────────────────────────────────────────────────
+describe("text", () => {
+    // WHY: the caller (cmd) exits 0 when violations is empty. Spurious output on a
+    // clean run is noise.
+    it("returns empty string for empty input", () => {
+        expect(text([])).toBe("");
+    });
+    // WHY: grouping by file is the user-facing contract (check.md §5 "grouped by
+    // file"). Missing files mean the user cannot locate the violation.
+    it("contains every file name", () => {
+        const got = text(sampleViolations());
+        for (const want of ["docs/adr/0001.md", "docs/adr/0002.md"]) {
+            expect(got).toContain(want);
+        }
+    });
+    // WHY: the rule name is the agent's correction signal — the agent identifies
+    // what to fix by the rule string. Absent rules make the output unactionable.
+    it("contains every rule name", () => {
+        const got = text(sampleViolations());
+        for (const rule of ["guard-docs", "guard-code", "guard-api"]) {
+            expect(got).toContain(rule);
+        }
+    });
+    // WHY: check.md §5 "output is deterministic". Non-deterministic output makes
+    // the report undiffable in CI (every run looks like a change).
+    it("is deterministic across runs", () => {
+        const vs = sampleViolations();
+        expect(text(vs)).toBe(text(vs));
+    });
+    // WHY: check.md §5 "ordered by file path". Sorting by file lets the agent
+    // process all violations for one file in one pass.
+    it("sorts 0001.md before 0002.md", () => {
+        const got = text(sampleViolations());
+        const idx1 = got.indexOf("docs/adr/0001.md");
+        const idx2 = got.indexOf("docs/adr/0002.md");
+        expect(idx1).toBeGreaterThanOrEqual(0);
+        expect(idx2).toBeGreaterThanOrEqual(0);
+        expect(idx1).toBeLessThan(idx2);
+    });
+    // WHY: the golden oracle checks this output byte-for-byte. This pins the exact
+    // plain (non-TTY) wire format: file header, two-space indent, "line N  ",
+    // rule, optional [section]/expected/actual/message, and a blank line after
+    // each file group. Within 0001.md, line 10 precedes line 20 (stable sort
+    // keeps input order within a file).
+    it("pins the exact plain-text wire format", () => {
+        // Guard: the byte-exact assertion only holds on the no-color path. Fail loud
+        // if the environment turned color on (would inject ANSI escapes).
+        expect(colorEnabled).toBe(false);
+        const got = text(sampleViolations());
+        const want = "docs/adr/0001.md\n" +
+            "  line 10  guard-docs  referenced file does not exist\n" +
+            "  line 20  guard-api  actual: {{api: GET /foo}}  endpoint not found in spec\n" +
+            "\n" +
+            "docs/adr/0002.md\n" +
+            "  line 5  guard-code  actual: {{code:internal/foo.go#Bar}}  referenced symbol not found\n" +
+            "\n";
+        expect(got).toBe(want);
+    });
+    // WHY: line 0 means "not applicable" — Go omits the "line N  " prefix when
+    // Line <= 0. A spurious "line 0  " would mislead the agent about position.
+    it("omits the line prefix when line is 0", () => {
+        const vs = [
+            {
+                file: "docs/x.md",
+                line: 0,
+                sectionID: "",
+                rule: Rules.guardDocs,
+                expected: "",
+                actual: "",
+                message: "doc-level problem",
+            },
+        ];
+        expect(text(vs)).toBe("docs/x.md\n  guard-docs  doc-level problem\n\n");
+    });
+    // WHY: section_id, expected, and actual are each emitted only when non-empty,
+    // in a fixed order ([section]  expected:  actual:  message). This pins the
+    // ordering and the bracket/label punctuation the oracle compares.
+    it("renders section, expected, actual, and message in order", () => {
+        const vs = [
+            {
+                file: "docs/y.md",
+                line: 3,
+                sectionID: "context",
+                rule: Rules.guardCode,
+                expected: "docs/target.md",
+                actual: "docs/wrong.md",
+                message: "mismatch",
+            },
+        ];
+        expect(text(vs)).toBe("docs/y.md\n  line 3  guard-code  [context]  expected: docs/target.md  actual: docs/wrong.md  mismatch\n\n");
+    });
+});
+// ── JSON renderer tests ────────────────────────────────────────────────────
+describe("json", () => {
+    // WHY: a clean run must emit valid JSON an agent can parse. "null" or "" would
+    // break parsing on the empty-array path.
+    it("returns [] for empty input", () => {
+        expect(json([])).toBe("[]");
+    });
+    // WHY: the JSON format is the machine-readable correction signal (check.md
+    // §5). Invalid JSON silently drops all violations — the agent thinks the tree
+    // is clean.
+    it("emits valid JSON with one record per violation", () => {
+        const vs = sampleViolations();
+        const records = JSON.parse(json(vs));
+        expect(records).toHaveLength(vs.length);
+    });
+    // WHY: the JSON schema is the agent's contract. Missing fields break parsing;
+    // undocumented fields confuse the agent. All seven fields must be present.
+    it("includes all seven fields in every record", () => {
+        const vs = [
+            {
+                file: "docs/adr/0001.md",
+                line: 10,
+                sectionID: "",
+                rule: Rules.guardDocs,
+                expected: "docs/target.md",
+                actual: "",
+                message: "referenced file does not exist",
+            },
+        ];
+        const records = JSON.parse(json(vs));
+        expect(records).toHaveLength(1);
+        const rec = records[0];
+        for (const field of [
+            "file",
+            "line",
+            "section_id",
+            "rule",
+            "expected",
+            "actual",
+            "message",
+        ]) {
+            expect(rec).toHaveProperty(field);
+        }
+    });
+    // WHY: non-deterministic JSON makes the agent's correction signal unstable
+    // across runs, breaking automated diffing and checksum validation.
+    it("is deterministic across runs", () => {
+        const vs = sampleViolations();
+        expect(json(vs)).toBe(json(vs));
+    });
+    // WHY: the agent processes the array sequentially; sorting by file lets it
+    // batch corrections per file in one pass.
+    it("sorts records by file path", () => {
+        const records = JSON.parse(json(sampleViolations()));
+        for (let i = 1; i < records.length; i++) {
+            expect(records[i - 1].file <= records[i].file).toBe(true);
+        }
+    });
+    // WHY: the golden oracle checks JSON byte-for-byte. This pins the exact wire
+    // bytes: compact (no spaces), fixed field order matching Go's struct, empty
+    // strings present, and the stable file sort. Within 0001.md the line-10
+    // record precedes the line-20 record (stable sort preserves input order).
+    it("pins the exact compact JSON wire format", () => {
+        const got = json(sampleViolations());
+        const want = "[" +
+            '{"file":"docs/adr/0001.md","line":10,"section_id":"","rule":"guard-docs","expected":"","actual":"","message":"referenced file does not exist"},' +
+            '{"file":"docs/adr/0001.md","line":20,"section_id":"","rule":"guard-api","expected":"","actual":"{{api: GET /foo}}","message":"endpoint not found in spec"},' +
+            '{"file":"docs/adr/0002.md","line":5,"section_id":"","rule":"guard-code","expected":"","actual":"{{code:internal/foo.go#Bar}}","message":"referenced symbol not found"}' +
+            "]";
+        expect(got).toBe(want);
+    });
+    // WHY: Go's encoding/json HTML-escapes <, >, & (and U+2028/U+2029) to \uXXXX
+    // by default. JSON.stringify does not. Without replicating that escaping, a
+    // violation whose message contains an angle bracket or ampersand would produce
+    // bytes that differ from Go and fail the oracle.
+    it("HTML-escapes <, >, and & like Go's encoder", () => {
+        const vs = [
+            {
+                file: "docs/a<b>.md",
+                line: 1,
+                sectionID: "",
+                rule: Rules.guardDocs,
+                expected: "",
+                actual: "",
+                message: "x < y && z > w",
+            },
+        ];
+        const got = json(vs);
+        expect(got).toContain("docs/a\\u003cb\\u003e.md");
+        expect(got).toContain("x \\u003c y \\u0026\\u0026 z \\u003e w");
+        // The raw characters must NOT survive in the output.
+        expect(got).not.toContain("<");
+        expect(got).not.toContain(">");
+        expect(got).not.toContain("&");
+    });
+});
+// ── Color-enable gate (color.ts) ────────────────────────────────────────────
+//
+// WHY this group exists: colorEnabled gates whether the text report emits ANSI
+// escapes. The byte-checked golden surface is the PLAIN (no-color) path, so the
+// precedence the report relies on — NO_COLOR > CLICOLOR_FORCE > CLICOLOR=0 >
+// TTY+non-dumb TERM — must hold exactly. A wrong gate would either inject
+// escapes into the oracle-compared output (corrupting it) or suppress color
+// when forced. The decision is cached at module load, so each case re-imports a
+// fresh module with the relevant env / isTTY set.
+describe("color gate (detectColorEnabled precedence)", () => {
+    // Snapshot the env keys the gate reads plus stdout.isTTY so each case starts
+    // clean and the suite leaves the process untouched.
+    const watched = ["NO_COLOR", "CLICOLOR_FORCE", "CLICOLOR", "TERM"];
+    const savedEnv = {};
+    let savedTTY;
+    function clearEnv() {
+        for (const k of watched) {
+            savedEnv[k] = process.env[k];
+            delete process.env[k];
+        }
+        savedTTY = process.stdout.isTTY;
+    }
+    function setTTY(v) {
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: v,
+            configurable: true,
+        });
+    }
+    afterEach(() => {
+        for (const k of watched) {
+            if (savedEnv[k] === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = savedEnv[k];
+        }
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: savedTTY,
+            configurable: true,
+        });
+        vi.resetModules();
+    });
+    // Load a fresh copy of color.ts so detectColorEnabled re-runs against the env
+    // mutated by the test (the real export is cached from initial import).
+    async function freshColor() {
+        vi.resetModules();
+        return import("./color.js");
+    }
+    // WHY: NO_COLOR (no-color.org) must disable color outright, even on a TTY —
+    // it is the highest-precedence override.
+    it("NO_COLOR disables color even with a TTY and good TERM", async () => {
+        clearEnv();
+        process.env["NO_COLOR"] = "1";
+        process.env["TERM"] = "xterm";
+        setTTY(true);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(false);
+        // No-color path: the style helpers are the identity function.
+        expect(m.fileStyle("X")).toBe("X");
+        expect(m.ruleStyle("X")).toBe("X");
+    });
+    // WHY: CLICOLOR_FORCE bumps color ON even off a TTY (e.g. piped output),
+    // overriding the default Ascii-when-piped behavior.
+    it("CLICOLOR_FORCE forces color on even off a TTY", async () => {
+        clearEnv();
+        process.env["CLICOLOR_FORCE"] = "1";
+        setTTY(false);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(true);
+        // Color-on path: the style helpers wrap the input (it is no longer identity).
+        expect(m.fileStyle("X")).not.toBe("X");
+        expect(m.ruleStyle("X")).not.toBe("X");
+    });
+    // WHY: CLICOLOR_FORCE="0" is NOT a force (matches termenv) — it must fall
+    // through to the TTY check rather than forcing color on.
+    it("CLICOLOR_FORCE=0 is not a force and falls through to the TTY check", async () => {
+        clearEnv();
+        process.env["CLICOLOR_FORCE"] = "0";
+        setTTY(false);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(false);
+    });
+    // WHY: CLICOLOR="0" (without a force) disables color — the explicit opt-out
+    // below the force level.
+    it("CLICOLOR=0 disables color when not forced", async () => {
+        clearEnv();
+        process.env["CLICOLOR"] = "0";
+        process.env["TERM"] = "xterm";
+        setTTY(true);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(false);
+    });
+    // WHY: the default path enables color only on a TTY with a real TERM; this is
+    // the one branch where color turns on without an env override.
+    it("enables color on a TTY with a non-dumb TERM", async () => {
+        clearEnv();
+        process.env["TERM"] = "xterm-256color";
+        setTTY(true);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(true);
+    });
+    // WHY: a "dumb" terminal must NOT get color even on a TTY — dumb terminals
+    // cannot render escapes, so emitting them would garble the output.
+    it("disables color when TERM is dumb even on a TTY", async () => {
+        clearEnv();
+        process.env["TERM"] = "dumb";
+        setTTY(true);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(false);
+    });
+    // WHY: off a TTY (pipe/file/test capture) with no override, color is OFF —
+    // this is the byte-checked plain path the oracle depends on.
+    it("disables color off a TTY with no override", async () => {
+        clearEnv();
+        process.env["TERM"] = "xterm";
+        setTTY(false);
+        const m = await freshColor();
+        expect(m.colorEnabled).toBe(false);
+    });
+});

package/dist/violation/index.js

@@ -0,0 +1 @@
+export { Rules } from "./types.js";

package/dist/violation/types.js

@@ -0,0 +1,22 @@
+// Package violation defines the Violation Record and the closed Rule enum for
+// the docgov check surface. It is a leaf package: it imports nothing internal.
+// Every rule the check surface can emit is listed in the Rule set; the set is
+// closed and must exactly match the rule registry in docs/flows/check.md §5.
+// Rules is the closed set of all rule identifiers the check surface can emit.
+// The string value is the wire identifier that appears in both the text and JSON
+// report formats — it is the agent's correction signal and must match the names
+// in docs/flows/check.md §5 ("Rule registry") exactly.
+//
+//   - guardDocs fires when a referenced file is missing, uses an absolute path,
+//     or escapes the repo root.
+//   - guardCode fires when a {{code:…}} reference fails — malformed syntax, an
+//     unresolved symbol, a ref outside source, or a resolver/operational error.
+//     The specific failure mode lives in expected/actual/message.
+//   - guardAPI fires when an {{api:…}} endpoint cross-ref fails — malformed
+//     syntax, an endpoint absent in the OpenAPI spec, a qualifier not satisfied,
+//     or a spec that is missing or unparseable.
+export const Rules = {
+    guardDocs: "guard-docs",
+    guardCode: "guard-code",
+    guardAPI: "guard-api",
+};

package/dist/violation/types.test.js

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { Rules } from "./index.js";
+// documentedRules is the canonical set of rule identifiers from the check flow's
+// rule registry (docs/flows/check.md §5 "Rule registry"). The Rules set in this
+// package must match this set exactly — no more, no fewer — so that the check
+// surface never emits an undocumented rule and never silently drops a documented
+// one. WHY: these rules are the correction signal sent to the agent; an
+// undocumented rule is uninterpretable, a missing rule is unenforceable.
+const documentedRules = ["guard-docs", "guard-code", "guard-api"];
+describe("Rule enum", () => {
+    // Asserts the closed Rule set contains exactly the 3 rules in the three-guard
+    // pipeline. This prevents the check surface from emitting rules the agent
+    // cannot interpret (undocumented) or omitting rules the agent needs.
+    it("exposes exactly the three documented registry rules with exact wire values", () => {
+        expect(documentedRules).toHaveLength(3);
+        // The exact kebab-case wire values the agent receives in the JSON report.
+        expect(Rules.guardDocs).toBe("guard-docs");
+        expect(Rules.guardCode).toBe("guard-code");
+        expect(Rules.guardAPI).toBe("guard-api");
+        // No empty/zero-valued rule and no duplicates.
+        const values = Object.values(Rules);
+        expect(values.every((v) => v.length > 0)).toBe(true);
+        expect(new Set(values).size).toBe(values.length);
+    });
+    // Exhaustiveness in both directions, deriving the enum side from the actual
+    // Rules const rather than a second hand-maintained list. Adding a Rule value
+    // without documenting it (or removing one) fails this test in both directions.
+    //
+    // WHY: documentedRules is the anchor for check.md §5; Object.values(Rules) is
+    // the anchor for what the binary actually emits. If they diverge, either an
+    // undocumented rule leaks into agent reports (uninterpretable) or a documented
+    // rule is silently absent from the set (unenforceable).
+    it("matches the documented registry exactly in both directions", () => {
+        const sourceSet = new Set(Object.values(Rules));
+        const docSet = new Set(documentedRules);
+        expect(sourceSet.size).toBeGreaterThan(0);
+        // Direction 1 — no undocumented values: every source value is documented.
+        for (const v of sourceSet) {
+            expect(docSet.has(v)).toBe(true);
+        }
+        // Direction 2 — no missing values: every documented rule has a source value.
+        for (const v of docSet) {
+            expect(sourceSet.has(v)).toBe(true);
+        }
+    });
+});
+describe("Record", () => {
+    // Verifies a Record can be constructed with all fields documented in check.md
+    // §5 ("file, line, sectionId, rule, expected, actual, message") and that each
+    // field round-trips. The check surface and report package read these fields to
+    // produce both the human-readable text report and the JSON agent signal.
+    it("carries every documented field and round-trips their values", () => {
+        const r = {
+            file: "docs/adr/0001-foo.md",
+            line: 42,
+            sectionID: "context",
+            rule: Rules.guardDocs,
+            expected: "docs/target.md",
+            actual: "",
+            message: "referenced file does not exist",
+        };
+        expect(r.file).toBe("docs/adr/0001-foo.md");
+        expect(r.line).toBe(42);
+        expect(r.sectionID).toBe("context");
+        expect(r.rule).toBe("guard-docs");
+        expect(r.expected).toBe("docs/target.md");
+        expect(r.actual).toBe("");
+        expect(r.message).toBe("referenced file does not exist");
+    });
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "docsgov",
+  "version": "0.1.0",
+  "description": "Config-driven documentation governance: checks that {{code:…}} and {{api:…}} references in your Markdown docs still resolve, that doc links exist, and (via dedup) flags near-duplicate concepts.",
+  "license": "GPL-3.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "docgov": "dist/cmd/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "commander": "^15.0.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.1.2",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.4",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "web-tree-sitter": "^0.26.9",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.8",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}