docsgov 0.1.0

package/dist/repo/write.test.js

@@ -0,0 +1,125 @@
+import * as nodefs from "node:fs/promises";
+import * as path from "node:path";
+import { describe, expect, test } from "vitest";
+import { find } from "./repo.js";
+import { makeDir } from "./testutil.js";
+// WHY these tests matter: repo is the SOLE owner of OS path handling and all OS
+// writes. Any path-handling bug here (slash->OS mapping, escaping the root,
+// missing parent dirs) corrupts the user's repository. These verify the OS
+// boundary is honoured structurally, not just by convention.
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+async function statSafe(p) {
+    try {
+        await nodefs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+describe("write capability", () => {
+    // WHY: gen writes to nested paths; without parent creation every subdirectory
+    // write fails and gen can never produce a multi-file tree.
+    test("writeFile creates all missing parent directories", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        const content = enc.encode("hello\n");
+        await r.writeFile(".claude/skills/write-docs/adr/adr.md", content);
+        const got = await nodefs.readFile(path.join(root, ".claude", "skills", "write-docs", "adr", "adr.md"));
+        expect(dec.decode(got)).toBe("hello\n");
+    });
+    // WHY: a slash path must map onto the OS separator so files land at the right
+    // location on every platform.
+    test("writeFile maps a slash path to the nested OS path", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await r.writeFile("subdir/file.txt", enc.encode("data\n"));
+        const got = await nodefs.readFile(path.join(root, "subdir", "file.txt"));
+        expect(dec.decode(got)).toBe("data\n");
+    });
+    // WHY: allowing ".." traversal would let gen overwrite arbitrary files on the
+    // user's system — a security and correctness boundary.
+    test("writeFile refuses a path that escapes the repo root", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.writeFile("../escape.txt", enc.encode("should not be written"))).rejects.toThrow();
+    });
+    // WHY: write-with-backup renames the existing skill dir to <skill>.bak; if
+    // renameDir is broken the backup protocol can't protect the user's tree.
+    test("renameDir moves a directory and its contents", async () => {
+        const root = await makeDir(".docgov", ".claude/skills/write-docs");
+        await nodefs.writeFile(path.join(root, ".claude", "skills", "write-docs", "sentinel.txt"), "x");
+        const r = await find(root);
+        await r.renameDir(".claude/skills/write-docs", ".claude/skills/write-docs.bak");
+        expect(await statSafe(path.join(root, ".claude", "skills", "write-docs"))).toBe(false);
+        expect(await statSafe(path.join(root, ".claude", "skills", "write-docs.bak", "sentinel.txt"))).toBe(true);
+    });
+    // WHY: rollback deletes the partial skill dir before restoring the backup; an
+    // incomplete removeAll leaves partial state in the user's repository.
+    test("removeAll removes a directory tree", async () => {
+        const root = await makeDir(".docgov", ".claude/skills/partial/nested");
+        await nodefs.writeFile(path.join(root, ".claude", "skills", "partial", "nested", "f.txt"), "y");
+        const r = await find(root);
+        await r.removeAll(".claude/skills/partial");
+        expect(await statSafe(path.join(root, ".claude", "skills", "partial"))).toBe(false);
+    });
+    // WHY: stale-bak cleanup calls removeAll unconditionally on first run when no
+    // .bak exists — it must silently succeed.
+    test("removeAll on a nonexistent path is a no-op", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.removeAll(".claude/skills/does-not-exist.bak")).resolves.toBeUndefined();
+    });
+    // WHY: write-with-backup must know whether the skill dir exists before
+    // deciding to back up; a wrong answer skips a needed backup or crashes a
+    // rename of a nonexistent dir.
+    test("dirExists reports true for an existing dir and false otherwise", async () => {
+        const root = await makeDir(".docgov", ".claude/skills/write-docs");
+        const r = await find(root);
+        expect(await r.dirExists(".claude/skills/write-docs")).toBe(true);
+        expect(await r.dirExists(".claude/skills/no-such-dir")).toBe(false);
+    });
+});
+// WHY: the --flip pipeline relies on the two-phase commit to keep on-disk state
+// binary (fully pre-flip or fully post-flip-and-verified). A rollback that
+// mutates the original or leaves a stray temp file breaks that invariant.
+describe("atomicWriteFile two-phase commit", () => {
+    test("commit(false) rolls back leaving the original untouched and no temp", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const target = "docs/a.md";
+        await r.writeFile(target, enc.encode("ORIGINAL\n"));
+        const pw = await r.atomicWriteFile(target, enc.encode("NEW\n"));
+        await pw.commit(false);
+        expect(dec.decode(await r.readFile(target))).toBe("ORIGINAL\n");
+        expect(await statSafe(path.join(root, "docs", "a.md.docgov-flip.tmp"))).toBe(false);
+    });
+    test("commit(true) atomically renames the temp into place", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const target = "docs/a.md";
+        await r.writeFile(target, enc.encode("ORIGINAL\n"));
+        const pw = await r.atomicWriteFile(target, enc.encode("NEW2\n"));
+        await pw.commit(true);
+        expect(dec.decode(await r.readFile(target))).toBe("NEW2\n");
+    });
+    // WHY: the temp must be a SIBLING of the target so the rename stays atomic on
+    // one filesystem. If it ever moved to the OS temp dir (a separate filesystem
+    // on many hosts), the rename would fall back to copy+remove, observable
+    // mid-flight. The real temp path comes from PendingWrite, so this genuinely
+    // fails if the impl changes to use the OS temp dir.
+    test("the temp file is a sibling of the target, not in the OS temp dir", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const target = "docs/a.md";
+        await r.writeFile(target, enc.encode("ORIGINAL\n"));
+        const pw = await r.atomicWriteFile(target, enc.encode("PROBE\n"));
+        const actualTmpPath = pw.tmpAbsForTest();
+        const targetDir = path.join(root, "docs");
+        expect(path.dirname(actualTmpPath)).toBe(targetDir);
+        // The temp file must exist on disk before commit is called.
+        expect(await statSafe(path.join(targetDir, "a.md.docgov-flip.tmp"))).toBe(true);
+        await pw.commit(false); // rollback
+    });
+});

package/dist/report/color.js

@@ -0,0 +1,73 @@
+// Color-enable detection and span styling for the text report.
+//
+// WHY this exists: the Go report styles its text output with charmbracelet/
+// lipgloss, whose default renderer decides whether to emit ANSI escapes from
+// termenv's EnvColorProfile (os.Stdout). When stdout is NOT a color-capable TTY
+// — piped output, `go test`, the golden-test oracle's captured stdout — the
+// profile is Ascii and lipgloss renders the spans as PLAIN TEXT (no escapes).
+// That plain path is the byte-checked surface, so this module replicates Go's
+// color-enable gate exactly: on the no-color path the style helpers return the
+// input unchanged, byte-for-byte identical to lipgloss's Ascii output.
+//
+// The TTY (color-on) path cannot be made byte-identical to lipgloss — lipgloss
+// emits its own escape sequences (and even wraps each rune individually for an
+// underlined style). We approximate it with plain ANSI when color is enabled;
+// see DEVIATIONS in this file. The oracle never exercises the color-on path.
+import pc from "picocolors";
+// colorEnabled mirrors termenv.EnvColorProfile() reduced to "is the profile
+// better than Ascii?". The precedence below matches termenv:
+//
+//   1. NO_COLOR (any non-empty value) → no color. (no-color.org)
+//   2. CLICOLOR_FORCE (non-empty, != "0") → force color on, even off a TTY.
+//   3. CLICOLOR == "0" (without a force) → no color.
+//   4. otherwise: color only if stdout is a TTY whose TERM is not "" or "dumb".
+//
+// Determined once at module load, like lipgloss's sync.Once-cached profile.
+function detectColorEnabled() {
+    const env = process.env;
+    // 1. NO_COLOR wins outright (termenv.EnvNoColor checks NO_COLOR first).
+    if (env["NO_COLOR"] !== undefined && env["NO_COLOR"] !== "") {
+        return false;
+    }
+    // 2. CLICOLOR_FORCE bumps even a non-TTY up out of Ascii.
+    const force = env["CLICOLOR_FORCE"];
+    const forced = force !== undefined && force !== "" && force !== "0";
+    if (forced) {
+        return true;
+    }
+    // 3. CLICOLOR == "0" (no force) disables color.
+    if (env["CLICOLOR"] === "0") {
+        return false;
+    }
+    // 4. TTY + non-dumb TERM. Off a TTY (pipe, file, test capture) → Ascii,
+    //    which is the byte-checked plain path.
+    const term = env["TERM"];
+    const isDumb = term === undefined || term === "" || term === "dumb";
+    const isTTY = process.stdout !== undefined && process.stdout.isTTY === true;
+    return isTTY && !isDumb;
+}
+// colorEnabled is the cached decision. Exported so tests can assert the gate.
+export const colorEnabled = detectColorEnabled();
+// A picocolors instance bound to colorEnabled so its formatters honor our gate
+// (picocolors' own auto-detection differs from termenv: it also turns color on
+// for win32/CI, which would diverge from Go). createColors(false) makes every
+// formatter the identity function — exactly lipgloss's Ascii behavior.
+const colors = pc.createColors(colorEnabled);
+// fileStyle styles the file-path header: lipgloss Bold(true).Underline(true).
+// On the no-color path this returns s unchanged (byte-identical to Go).
+//
+// DEVIATION (color-on path only): lipgloss renders Bold+Underline per-rune as
+// `\x1b[1;4;4m<rune>\x1b[0m` for each rune; this emits picocolors' single
+// `\x1b[1m\x1b[4m…\x1b[24m\x1b[22m` wrap. Not byte-equal to lipgloss when a TTY
+// is attached. The oracle captures non-TTY stdout, so it never sees this path.
+export function fileStyle(s) {
+    return colors.bold(colors.underline(s));
+}
+// ruleStyle styles the rule identifier: lipgloss Italic(true).
+// On the no-color path this returns s unchanged (byte-identical to Go).
+//
+// DEVIATION (color-on path only): lipgloss emits `\x1b[3m…\x1b[0m`; picocolors
+// emits `\x1b[3m…\x1b[23m`. Differs only in the reset code, and only on a TTY.
+export function ruleStyle(s) {
+    return colors.italic(s);
+}

package/dist/report/index.js

@@ -0,0 +1 @@
+export { text, json } from "./report.js";

package/dist/report/report.js

@@ -0,0 +1,112 @@
+// Renders a list of violation records as a human-readable text report (styled
+// like Go's lipgloss output) or as a JSON array for machine consumption.
+//
+// Port of internal/report/report.go. Determinism: violations are sorted by file
+// path with a STABLE sort, so within each file they keep their input order
+// (the document-position order emitted by the check orchestration).
+import { fileStyle, ruleStyle } from "./color.js";
+// text renders vs as a human-readable, styled text report grouped by file.
+// Violations within each file are printed in document-position order. Returns an
+// empty string when vs is empty.
+export function text(vs) {
+    if (vs.length === 0) {
+        return "";
+    }
+    const sorted = sortedByFile(vs);
+    let out = "";
+    // Group by file and render each group.
+    let i = 0;
+    while (i < sorted.length) {
+        const first = sorted[i];
+        // first is defined: i < sorted.length and noUncheckedIndexedAccess guard.
+        if (first === undefined) {
+            break;
+        }
+        const file = first.file;
+        // File header.
+        out += fileStyle(file);
+        out += "\n";
+        // All violations for this file.
+        for (; i < sorted.length; i++) {
+            const v = sorted[i];
+            if (v === undefined || v.file !== file) {
+                break;
+            }
+            out += "  ";
+            if (v.line > 0) {
+                out += `line ${v.line}  `;
+            }
+            out += ruleStyle(v.rule);
+            if (v.sectionID !== "") {
+                out += `  [${v.sectionID}]`;
+            }
+            if (v.expected !== "") {
+                out += `  expected: ${v.expected}`;
+            }
+            if (v.actual !== "") {
+                out += `  actual: ${v.actual}`;
+            }
+            if (v.message !== "") {
+                out += "  ";
+                out += v.message;
+            }
+            out += "\n";
+        }
+        out += "\n";
+    }
+    return out;
+}
+// json renders vs as a JSON array of violation records. Returns "[]" when vs is
+// empty. Field order is fixed (file, line, section_id, rule, expected, actual,
+// message) — matching Go's struct declaration order — and the bytes match Go's
+// encoding/json: compact (no spaces), with HTML-special characters escaped to
+// \uXXXX exactly as Go's encoder does by default.
+export function json(vs) {
+    if (vs.length === 0) {
+        return "[]";
+    }
+    const sorted = sortedByFile(vs);
+    // Build plain objects with the exact key order Go's jsonRecord struct emits.
+    const records = sorted.map((v) => ({
+        file: v.file,
+        line: v.line,
+        section_id: v.sectionID,
+        rule: v.rule,
+        expected: v.expected,
+        actual: v.actual,
+        message: v.message,
+    }));
+    return goJSONStringify(records);
+}
+// goJSONStringify serializes value the way Go's encoding/json.Marshal does:
+// JSON.stringify produces the same compact form and key order (insertion
+// order), but Go additionally HTML-escapes <, >, & and the line/paragraph
+// separators U+2028/U+2029 to their \uXXXX forms. Replicating that escaping is
+// required for byte-for-byte oracle equality when a violation field carries one
+// of those characters.
+function goJSONStringify(value) {
+    const s = JSON.stringify(value);
+    return s
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+// sortedByFile returns a stable-sorted copy of vs, sorted by file path. Within
+// each file, violations preserve their original order (document position).
+// JS's Array.prototype.sort is stable (spec since ES2019), matching Go's
+// sort.SliceStable.
+function sortedByFile(vs) {
+    const out = vs.slice();
+    out.sort((a, b) => {
+        if (a.file < b.file) {
+            return -1;
+        }
+        if (a.file > b.file) {
+            return 1;
+        }
+        return 0;
+    });
+    return out;
+}