docsgov 0.1.0

package/dist/repo/errors.test.js

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "vitest";
+import { AmbiguousBoundaryError, FileExistsError, InvalidPatternError, InvalidTaskNameError, PacketCountOutOfRangeError, } from "./errors.js";
+// WHY: these are the repo package's discriminable sentinels — callers branch on
+// `instanceof` the way Go callers use errors.Is. If a class stopped extending
+// Error, dropped its stable `name`, or stopped quoting the offending value into
+// its message, callers could neither catch it specifically nor show the user
+// which input was wrong. Each test pins the discriminability (instanceof + name)
+// and that the load-bearing value is embedded in the message.
+describe("InvalidPatternError", () => {
+    // WHY: validatePattern throws this for a malformed boundary glob; the message
+    // must carry the offending literal so the user can find the broken catalog
+    // entry, and instanceof must work so config-load can report it distinctly.
+    test("is an Error, names itself, and quotes the offending pattern", () => {
+        const err = new InvalidPatternError("docs/[");
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(InvalidPatternError);
+        expect(err.name).toBe("InvalidPatternError");
+        // JSON.stringify is the Go %q analogue used in the message.
+        expect(err.message).toContain(JSON.stringify("docs/["));
+        expect(err.message).toContain("invalid boundary pattern");
+    });
+});
+describe("AmbiguousBoundaryError", () => {
+    // WHY: the check layer wraps this when two equal-specificity boundaries match
+    // the same file; a stable default message lets the operator recognise the
+    // condition, and instanceof lets check.ResolveError discriminate it.
+    test("defaults to the boundary-ambiguity message and is discriminable", () => {
+        const err = new AmbiguousBoundaryError();
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(AmbiguousBoundaryError);
+        expect(err.name).toBe("AmbiguousBoundaryError");
+        expect(err.message).toBe("repo: boundary pattern matches multiple doc types");
+    });
+    // WHY: callers may attach a richer context message; the override must replace
+    // the default rather than be ignored, or the operator loses the specifics.
+    test("accepts a custom message override", () => {
+        const err = new AmbiguousBoundaryError("two boundaries hit docs/x.md");
+        expect(err.message).toBe("two boundaries hit docs/x.md");
+    });
+});
+describe("InvalidTaskNameError", () => {
+    // WHY: planHeaderFilename/packetFilename reject a bad slug with this; both the
+    // rejected name AND the required pattern must appear so the user can fix the
+    // slug without guessing the rule.
+    test("quotes the bad name and includes the required pattern", () => {
+        const pattern = "^[a-z0-9][a-z0-9-]*[a-z0-9]$";
+        const err = new InvalidTaskNameError("Bad Name", pattern);
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(InvalidTaskNameError);
+        expect(err.name).toBe("InvalidTaskNameError");
+        expect(err.message).toContain(JSON.stringify("Bad Name"));
+        expect(err.message).toContain(pattern);
+    });
+});
+describe("PacketCountOutOfRangeError", () => {
+    // WHY: packetFilename rejects an index outside 1..99 with this; the offending
+    // number must be in the message so the user sees what they passed, and
+    // instanceof lets callers branch on the range failure specifically.
+    test("includes the out-of-range packet number and the 1..99 bound", () => {
+        const err = new PacketCountOutOfRangeError(100);
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(PacketCountOutOfRangeError);
+        expect(err.name).toBe("PacketCountOutOfRangeError");
+        expect(err.message).toContain("100");
+        expect(err.message).toContain("1..99");
+    });
+});
+describe("FileExistsError", () => {
+    // WHY: the write-with-backup layer throws this when a target already exists;
+    // instanceof is how that layer distinguishes "already there" from a real I/O
+    // fault, and the default message documents the condition.
+    test("defaults to the file-exists message and is discriminable", () => {
+        const err = new FileExistsError();
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(FileExistsError);
+        expect(err.name).toBe("FileExistsError");
+        expect(err.message).toBe("repo: file already exists");
+    });
+    // WHY: callers may name the conflicting path; the override must win so the
+    // operator sees which file blocked the write.
+    test("accepts a custom message override", () => {
+        const err = new FileExistsError("repo: docs/a.md already exists");
+        expect(err.message).toBe("repo: docs/a.md already exists");
+    });
+});

package/dist/repo/exists.test.js

@@ -0,0 +1,72 @@
+import * as nodefs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, test } from "vitest";
+import { find } from "./repo.js";
+import { makeDir } from "./testutil.js";
+describe("exists: exact-case file presence for the docs guard", () => {
+    // WHY: the docs guard calls exists to verify a referenced file is present.
+    // A false negative would flag a valid reference as a violation.
+    test("returns true for a file present at the exact-case path", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        await nodefs.writeFile(path.join(root, "docs", "adr", "0001-foo.md"), "hello");
+        const r = await find(root);
+        expect(await r.exists("docs/adr/0001-foo.md")).toBe(true);
+    });
+    // WHY: a reference to a non-existent file is the most common docs guard
+    // violation; exists must detect absence.
+    test("returns false for a missing file", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        const r = await find(root);
+        expect(await r.exists("docs/adr/nonexistent.md")).toBe(false);
+    });
+    // WHY: a host stat case-folds on macOS/Windows, so a plain stat would wrongly
+    // pass case-mismatched references. The segment-by-segment walk matches each
+    // entry by exact case so reports are byte-identical across platforms.
+    test("rejects a wrong-case filename segment", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        await nodefs.writeFile(path.join(root, "docs", "adr", "0001-foo.md"), "hello");
+        const r = await find(root);
+        expect(await r.exists("docs/adr/0001-FOO.md")).toBe(false);
+    });
+    // WHY: the exact-case rule must hold at EVERY segment, not just the filename;
+    // a wrong-case directory prefix must fail too.
+    test("rejects a wrong-case directory segment", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        await nodefs.writeFile(path.join(root, "docs", "adr", "0001-foo.md"), "hello");
+        const r = await find(root);
+        expect(await r.exists("Docs/adr/0001-foo.md")).toBe(false);
+    });
+    // WHY: the docs guard checks FILE references; a directory path is not a valid
+    // file reference and must not pass.
+    test("returns false for a directory path", async () => {
+        const root = await makeDir(".docgov", "docs/adr");
+        const r = await find(root);
+        expect(await r.exists("docs/adr")).toBe(false);
+    });
+    // WHY: absence must be (false, no error), not an error — otherwise the guard
+    // would abort on every reference to a file that doesn't exist yet, which is
+    // the guard's core purpose.
+    test("treats a missing path as false without throwing", async () => {
+        const root = await makeDir(".docgov");
+        const r = await find(root);
+        await expect(r.exists("does/not/exist.md")).resolves.toBe(false);
+    });
+    // WHY: Rule 12 (fail loud). A permission/IO fault masquerading as "absent"
+    // would silently pass guard checks that should surface the fault. Root
+    // bypasses permission bits, so this can only be exercised as a non-root user.
+    const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+    const ioErrorTest = isRoot || os.platform() === "win32" ? test.skip : test;
+    ioErrorTest("propagates a real I/O error rather than swallowing it as absent", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        const docsPath = path.join(root, "docs");
+        await nodefs.chmod(docsPath, 0o000);
+        try {
+            await expect(r.exists("docs/secret.md")).rejects.toThrow();
+        }
+        finally {
+            await nodefs.chmod(docsPath, 0o755);
+        }
+    });
+});

package/dist/repo/filename.js

@@ -0,0 +1,46 @@
+import { InvalidTaskNameError, PacketCountOutOfRangeError } from "./errors.js";
+// taskNameRE is the canonical slug pattern for plan task names: it matches
+// strings that start and end with a lowercase alphanumeric character and
+// contain only lowercase alphanumerics and hyphens in between.
+const taskNameRE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+// Source literal used in the error message, matching Go's regexp String().
+const taskNameRESrc = "^[a-z0-9][a-z0-9-]*[a-z0-9]$";
+// validateTaskName throws InvalidTaskNameError when name does not match
+// taskNameRE. Package-private: callers use planHeaderFilename / packetFilename.
+function validateTaskName(name) {
+    if (!taskNameRE.test(name)) {
+        throw new InvalidTaskNameError(name, taskNameRESrc);
+    }
+}
+// formatDate renders a Date as YYYYMMDD using its UTC components, matching the
+// Go reference layout "20060102" applied to a time.Time. Callers in Go pass a
+// UTC time.Time; using the UTC getters keeps the slug stable across the host's
+// local timezone.
+function formatDate(date) {
+    const y = date.getUTCFullYear().toString().padStart(4, "0");
+    const m = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const d = date.getUTCDate().toString().padStart(2, "0");
+    return `${y}${m}${d}`;
+}
+/**
+ * Returns the repo-relative slash path for the plan header file:
+ * docs/plans/YYYYMMDD-<taskName>-plan.md. Throws {@link InvalidTaskNameError}
+ * when taskName does not match the required slug pattern.
+ */
+export function planHeaderFilename(date, taskName) {
+    validateTaskName(taskName);
+    return `docs/plans/${formatDate(date)}-${taskName}-plan.md`;
+}
+/**
+ * Returns the repo-relative slash path for the Nth packet file:
+ * docs/plans/YYYYMMDD-<taskName>-N.md. Throws {@link InvalidTaskNameError} when
+ * taskName is invalid, and {@link PacketCountOutOfRangeError} when packet is
+ * outside 1..99.
+ */
+export function packetFilename(date, taskName, packet) {
+    validateTaskName(taskName);
+    if (packet < 1 || packet > 99) {
+        throw new PacketCountOutOfRangeError(packet);
+    }
+    return `docs/plans/${formatDate(date)}-${taskName}-${packet}.md`;
+}

package/dist/repo/filename.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "vitest";
+import { InvalidTaskNameError, PacketCountOutOfRangeError } from "./errors.js";
+import { packetFilename, planHeaderFilename } from "./filename.js";
+// WHY: the filename builders are the canonical source of truth for how plan and
+// packet files are named on disk. Slug validation prevents accidental creation
+// of files whose names break downstream tooling; range validation keeps the
+// packet index within the declared bounds (1..99).
+describe("filename builders", () => {
+    // 2026-05-28 UTC; the Go test uses time.Date(...,time.UTC) and "20060102".
+    const today = new Date(Date.UTC(2026, 4, 28));
+    test("planHeaderFilename formats date + slug into the plans path", () => {
+        expect(planHeaderFilename(today, "code-guard")).toBe("docs/plans/20260528-code-guard-plan.md");
+    });
+    test("packetFilename index 1 lands at the canonical packet path", () => {
+        expect(packetFilename(today, "code-guard", 1)).toBe("docs/plans/20260528-code-guard-1.md");
+    });
+    test("packetFilename index 99 is the inclusive upper bound", () => {
+        expect(packetFilename(today, "code-guard", 99)).toBe("docs/plans/20260528-code-guard-99.md");
+    });
+    test("packetFilename index 0 is out of range", () => {
+        expect(() => packetFilename(today, "code-guard", 0)).toThrow(PacketCountOutOfRangeError);
+    });
+    test("packetFilename index 100 is out of range", () => {
+        expect(() => packetFilename(today, "code-guard", 100)).toThrow(PacketCountOutOfRangeError);
+    });
+    // The slug must start and end with a lowercase alphanumeric and contain only
+    // lowercase alphanumerics and hyphens between — each of these must be rejected.
+    const badSlugs = [
+        ["rejects uppercase", "BadName"],
+        ["rejects leading dash", "-leading"],
+        ["rejects trailing dash", "trailing-"],
+        ["rejects spaces", "with spaces"],
+    ];
+    for (const [why, slug] of badSlugs) {
+        test(`planHeaderFilename ${why}`, () => {
+            expect(() => planHeaderFilename(today, slug)).toThrow(InvalidTaskNameError);
+        });
+    }
+});

package/dist/repo/fs.js

@@ -0,0 +1,53 @@
+import * as nodefs from "node:fs/promises";
+import * as path from "node:path";
+/**
+ * Reports whether `err` represents a not-found condition — the Node analogue of
+ * Go's errors.Is(err, fs.ErrNotExist). Used by callers (e.g. Exists) that treat
+ * absence as (false, no error) but propagate every other I/O fault.
+ */
+export function isNotExist(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === "ENOENT");
+}
+class RealDirEntry {
+    entryName;
+    dir;
+    constructor(entryName, dir) {
+        this.entryName = entryName;
+        this.dir = dir;
+    }
+    name() {
+        return this.entryName;
+    }
+    isDir() {
+        return this.dir;
+    }
+}
+/** An FS backed by the real filesystem, rooted at an absolute OS path. */
+export class RealFS {
+    osRoot;
+    constructor(osRoot) {
+        this.osRoot = osRoot;
+    }
+    /** Maps a slash path (relative to this FS root) to an absolute OS path. */
+    osPath(name) {
+        if (name === "." || name === "") {
+            return this.osRoot;
+        }
+        return path.join(this.osRoot, ...name.split("/"));
+    }
+    async readFile(name) {
+        return nodefs.readFile(this.osPath(name));
+    }
+    async readDir(name) {
+        const entries = await nodefs.readdir(this.osPath(name), {
+            withFileTypes: true,
+        });
+        return entries.map((e) => new RealDirEntry(e.name, e.isDirectory()));
+    }
+    sub(name) {
+        return new RealFS(this.osPath(name));
+    }
+}

package/dist/repo/index.js

@@ -0,0 +1,7 @@
+// Public surface of the repo package — the OS boundary for docgov.
+export { Repo, PendingWrite, find } from "./repo.js";
+export { RealFS, isNotExist } from "./fs.js";
+export { OverlayFS } from "./overlay.js";
+export { validatePattern } from "./boundary.js";
+export { planHeaderFilename, packetFilename } from "./filename.js";
+export { InvalidPatternError, AmbiguousBoundaryError, InvalidTaskNameError, PacketCountOutOfRangeError, FileExistsError, } from "./errors.js";

package/dist/repo/overlay.js

@@ -0,0 +1,36 @@
+// overlay.ts provides OverlayFS, the TS analogue of Go's overlayFS: an FS that
+// intercepts reads of exactly one slash path and returns injected bytes,
+// delegating every other read to a base FS.
+//
+// Safety contract (mirrors the Go doc comment):
+//   - WithOverlay does NOT mutate the receiver Repo.
+//   - The returned Repo shares the base root and write methods; only FS reads
+//     of the one overlaid path are intercepted.
+//   - Non-overlaid paths are served from the base FS — the overlay is a
+//     shallow one-path intercept only.
+//
+// Directory listing (readDir) and descent (sub) always delegate to base: the
+// overlaid file IS present in the base FS on disk, so a walk enumerates it; only
+// the single overlaid file path is intercepted for content.
+export class OverlayFS {
+    base;
+    overlaidPath;
+    content;
+    constructor(base, overlaidPath, content) {
+        this.base = base;
+        this.overlaidPath = overlaidPath;
+        this.content = content;
+    }
+    async readFile(name) {
+        if (name === this.overlaidPath) {
+            return this.content;
+        }
+        return this.base.readFile(name);
+    }
+    async readDir(name) {
+        return this.base.readDir(name);
+    }
+    sub(name) {
+        return this.base.sub(name);
+    }
+}

package/dist/repo/overlay.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import { find } from "./repo.js";
+import { makeDir } from "./testutil.js";
+// WHY these tests matter: withOverlay lets callers present an in-memory version
+// of one file to the check pipeline while the real on-disk file stays untouched.
+// If it delegates reads incorrectly (base content for the overlaid path, or
+// overlay content for other paths), the safety invariant breaks — the check
+// pipeline would see wrong data.
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+describe("withOverlay: single-path in-memory intercept", () => {
+    // Core contract: the check sees the flipped bytes even though the real file
+    // on disk still holds the original.
+    test("overlaid path returns the injected content, not the on-disk bytes", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("---\nstatus: planning\n---\n"));
+        const injected = enc.encode("---\nstatus: implemented\n---\n");
+        const ov = r.withOverlay("docs/a.md", injected);
+        expect(dec.decode(await ov.readFile("docs/a.md"))).toBe("---\nstatus: implemented\n---\n");
+    });
+    // The resolver reads source files (non-overlaid); if the overlay intercepted
+    // those, the resolver would see wrong data.
+    test("non-overlaid path delegates to the base on-disk content", async () => {
+        const root = await makeDir(".docgov", "docs", "pkg");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("original\n"));
+        await r.writeFile("pkg/foo.go", enc.encode("package foo\n"));
+        const ov = r.withOverlay("docs/a.md", enc.encode("injected\n"));
+        expect(dec.decode(await ov.readFile("pkg/foo.go"))).toBe("package foo\n");
+    });
+    // The check pipeline reads files via fs() too (direct reads and the markdown
+    // walk); the overlay FS must agree with overlay readFile.
+    test("fs() serves the injected content for the overlaid path", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("on-disk\n"));
+        const injected = enc.encode("overlay\n");
+        const ov = r.withOverlay("docs/a.md", injected);
+        expect(dec.decode(await ov.fs().readFile("docs/a.md"))).toBe("overlay\n");
+    });
+    // If withOverlay mutated the base repo's FS, the real file would be
+    // effectively overwritten in memory — the exact problem being avoided.
+    test("creating an overlay does not mutate the base repo", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("status: planning\n"));
+        r.withOverlay("docs/a.md", enc.encode("status: implemented\n"));
+        expect(dec.decode(await r.readFile("docs/a.md"))).toBe("status: planning\n");
+    });
+    // WHY: the markdown walk lists directories through the overlay FS; the overlay
+    // is a one-path content intercept only, so readDir must still enumerate the
+    // real on-disk tree (including the overlaid file). If readDir intercepted
+    // anything, the walk would miss or duplicate files.
+    test("readDir delegates to the base so the overlaid file is still enumerated", async () => {
+        const root = await makeDir(".docgov", "docs");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("on-disk\n"));
+        await r.writeFile("docs/b.md", enc.encode("other\n"));
+        // Call readDir on the OverlayFS itself (overlaid path is "docs/a.md"), not
+        // on a sub-FS, so the overlay's own readDir is exercised. The overlaid file
+        // must still appear because the overlay is a content-only intercept.
+        const ov = r.withOverlay("docs/a.md", enc.encode("overlay\n"));
+        const names = (await ov.fs().readDir("docs")).map((e) => e.name());
+        expect(names).toEqual(expect.arrayContaining(["a.md", "b.md"]));
+    });
+    // WHY: descending via sub() must reach the real subtree, not a copy that drops
+    // the overlay's content rule — a sub() that diverged from base would make a
+    // nested read return the wrong bytes for non-overlaid files.
+    test("sub descends into the base subtree", async () => {
+        const root = await makeDir(".docgov", "docs", "pkg");
+        const r = await find(root);
+        await r.writeFile("docs/a.md", enc.encode("on-disk\n"));
+        await r.writeFile("pkg/foo.go", enc.encode("package foo\n"));
+        // sub() on the OverlayFS itself returns the base subtree FS.
+        const ov = r.withOverlay("docs/a.md", enc.encode("overlay\n"));
+        const pkg = ov.fs().sub("pkg");
+        expect(dec.decode(await pkg.readFile("foo.go"))).toBe("package foo\n");
+    });
+});