docsgov 0.1.0

package/dist/dedup/sectionid/sectionid.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+/**
+ * Returns a 16-character lowercase hex string that uniquely identifies a
+ * section within the dedup index. The ID is derived from the SHA-256 of
+ * "<filePath>#<anchor>:<heading>", truncated to the first 16 hex characters.
+ *
+ * Locked derivation (single source of truth — do not reimplement elsewhere):
+ *
+ *   sha256(filePath + "#" + anchor + ":" + heading)[:16 hex chars]
+ */
+export function derive(filePath, anchor, heading) {
+    const hex = createHash("sha256")
+        .update(filePath + "#" + anchor + ":" + heading)
+        .digest("hex");
+    return hex.slice(0, 16);
+}

package/dist/dedup/sectionid/sectionid.test.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { derive } from "./sectionid.js";
+describe("derive", () => {
+    // A section ID must be stable across runs, or every dedup index built from
+    // the same source would key sections differently and never match.
+    it("is deterministic for identical inputs", () => {
+        const a = derive("docs/foo.md", "my-heading", "My Heading");
+        const b = derive("docs/foo.md", "my-heading", "My Heading");
+        expect(a).toBe(b);
+    });
+    // The ID shape (exactly 16 lowercase hex chars) is a contract other layers
+    // rely on when storing/looking up IDs; a wider or non-hex ID is a regression.
+    it("returns exactly 16 lowercase hex characters", () => {
+        const id = derive("docs/foo.md", "my-heading", "My Heading");
+        expect(id).toHaveLength(16);
+        expect(id).toMatch(/^[0-9a-f]{16}$/);
+    });
+    // Anchor, file path, and heading text are all part of the hash input, so
+    // distinct sections — including collision-suffix anchors like
+    // "installation" vs "installation-1" — must derive distinct IDs.
+    it("maps distinct inputs to distinct IDs (anchor, file, and heading all count)", () => {
+        const cases = [
+            ["docs/foo.md", "installation", "Installation"],
+            ["docs/foo.md", "installation-1", "Installation"], // collision-suffix anchor
+            ["docs/bar.md", "installation", "Installation"], // different file
+            ["docs/foo.md", "installation", "Getting Started"], // different heading text
+        ];
+        const seen = new Map();
+        for (const [filePath, anchor, heading] of cases) {
+            const id = derive(filePath, anchor, heading);
+            const key = `${filePath}#${anchor}:${heading}`;
+            const prior = seen.get(id);
+            expect(prior, `collision: ${prior} and ${key} both produce ${id}`).toBeUndefined();
+            seen.set(id, key);
+        }
+    });
+    // Pins the exact sha256-based derivation (digest, encoding, truncation) so
+    // any accidental change to the hashing formula is caught immediately.
+    it("matches sha256(<filePath>#<anchor>:<heading>)[:16] exactly", () => {
+        const want = createHash("sha256")
+            .update("docs/guide.md#overview:Overview")
+            .digest("hex")
+            .slice(0, 16);
+        expect(derive("docs/guide.md", "overview", "Overview")).toBe(want);
+        // Cross-check the locked value to guard against both sides drifting together.
+        expect(want).toBe("f2912ce983e8d07d");
+    });
+});

package/dist/guard/api/errors.js

@@ -0,0 +1,12 @@
+/**
+ * MalformedRefError is thrown by parseApiRef when raw is not a valid {{api:…}} token.
+ *
+ * Mirrors Go's sentinel `ErrMalformedRef` (var ErrMalformedRef = errors.New(...)),
+ * ported as a named Error subclass per the porting conventions.
+ */
+export class MalformedRefError extends Error {
+    constructor(raw) {
+        super(`api: malformed reference: ${JSON.stringify(raw)}`);
+        this.name = "MalformedRefError";
+    }
+}

package/dist/guard/api/index.js

@@ -0,0 +1,2 @@
+export { MalformedRefError } from "./errors.js";
+export { isMethod, parseApiRef } from "./parser.js";

package/dist/guard/api/parser.js

@@ -0,0 +1,81 @@
+import { MalformedRefError } from "./errors.js";
+/**
+ * apiTokenRE matches a whole {{api:…}} token. The body permits single-level "{var}"
+ * groups (OpenAPI path templates) so `{{api: GET /x/{id}}}` matches up to the final
+ * "}}", unlike a naive `[^}]*`.
+ */
+const apiTokenRE = /\{\{api:[^{}]*(?:\{[^{}]*\}[^{}]*)*\}\}/;
+/** methodRE validates the HTTP method (case-insensitive in source, normalised upper). */
+const methodRE = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/i;
+/** isMethod reports whether s (case-insensitive) is a supported HTTP method. */
+export function isMethod(s) {
+    return methodRE.test(s);
+}
+/** validQualifierKinds is the set of allowed qualifier kinds. */
+const validQualifierKinds = new Set(["param", "body", "response", "header"]);
+/**
+ * parseApiRef parses one {{api: METHOD /path [KIND:dotted.name]}} token. Method is
+ * upper-cased; Path must start with "/". The optional third field must be KIND:name
+ * where KIND ∈ {param,body,response,header} and name is a non-empty dotted path with
+ * no empty segments. Any other shape throws MalformedRefError.
+ */
+export function parseApiRef(raw) {
+    if (!apiTokenRE.test(raw) || !raw.startsWith("{{api:")) {
+        throw new MalformedRefError(raw);
+    }
+    // Strip the "{{api:" prefix and the trailing "}}" suffix (Go TrimPrefix/TrimSuffix).
+    let body = raw.slice("{{api:".length);
+    if (body.endsWith("}}")) {
+        body = body.slice(0, -2);
+    }
+    const fields = splitFields(body); // collapses surrounding/duplicate spaces
+    if (fields.length < 2 || fields.length > 3) {
+        throw new MalformedRefError(raw);
+    }
+    const method = fields[0];
+    const pathPart = fields[1];
+    if (!methodRE.test(method) || !pathPart.startsWith("/")) {
+        throw new MalformedRefError(raw);
+    }
+    const ref = {
+        Method: method.toUpperCase(),
+        Path: pathPart,
+        Qualifier: null,
+    };
+    if (fields.length === 3) {
+        ref.Qualifier = parseQualifier(fields[2], raw);
+    }
+    return ref;
+}
+/**
+ * splitFields mirrors Go's strings.Fields: splits around runs of whitespace and
+ * drops leading/trailing empties.
+ */
+function splitFields(s) {
+    return s.split(/\s+/).filter((f) => f.length > 0);
+}
+/**
+ * parseQualifier parses the third field of an {{api:…}} token into a Qualifier.
+ * raw is the full original token string, used only for error messages.
+ */
+function parseQualifier(field, raw) {
+    const idx = field.indexOf(":");
+    if (idx < 0) {
+        throw new MalformedRefError(raw);
+    }
+    const kind = field.slice(0, idx);
+    const name = field.slice(idx + 1);
+    if (!validQualifierKinds.has(kind)) {
+        throw new MalformedRefError(raw);
+    }
+    if (name === "") {
+        throw new MalformedRefError(raw);
+    }
+    const segs = name.split(".");
+    for (const seg of segs) {
+        if (seg === "") {
+            throw new MalformedRefError(raw);
+        }
+    }
+    return { Kind: kind, Path: segs };
+}

package/dist/guard/api/parser.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { isMethod, MalformedRefError, parseApiRef } from "./index.js";
+const q = (kind, ...path) => ({ Kind: kind, Path: path });
+describe("parseApiRef", () => {
+    // A 2-field token is a bare endpoint citation; Qualifier must stay null so callers
+    // distinguish "cite the whole operation" from "cite one param/body/response/header".
+    it("parses 2-field tokens with no qualifier, normalising the method to upper-case", () => {
+        const cases = [
+            ["{{api: GET /api/admin/teams}}", { Method: "GET", Path: "/api/admin/teams", Qualifier: null }],
+            // case-insensitive method, OpenAPI path template {id} survives the regex.
+            ["{{api: get /x/{id}}}", { Method: "GET", Path: "/x/{id}", Qualifier: null }],
+            // no space after the colon is still a valid token.
+            ["{{api:POST /a/b}}", { Method: "POST", Path: "/a/b", Qualifier: null }],
+            ["{{api: GET /x}}", { Method: "GET", Path: "/x", Qualifier: null }],
+        ];
+        for (const [input, want] of cases) {
+            expect(parseApiRef(input), input).toEqual(want);
+        }
+    });
+    // The third field selects a sub-part of the operation; the dotted name must split
+    // into ordered segments so a guard can walk into nested schema properties.
+    it("parses 3-field tokens into a Kind + dotted-path segments qualifier", () => {
+        const cases = [
+            ["{{api: GET /x/{id} param:teamId}}", { Method: "GET", Path: "/x/{id}", Qualifier: q("param", "teamId") }],
+            ["{{api: POST /x body:user.address.city}}", { Method: "POST", Path: "/x", Qualifier: q("body", "user", "address", "city") }],
+            ["{{api: GET /x response:items.id}}", { Method: "GET", Path: "/x", Qualifier: q("response", "items", "id") }],
+            // header names keep their literal casing/hyphens; they are not dotted-split beyond ".".
+            ["{{api: GET /x header:X-Trace}}", { Method: "GET", Path: "/x", Qualifier: q("header", "X-Trace") }],
+        ];
+        for (const [input, want] of cases) {
+            expect(parseApiRef(input), input).toEqual(want);
+        }
+    });
+    // Every malformed shape must surface as the sentinel error so the guard reports a
+    // "malformed ref" violation rather than silently accepting a broken citation.
+    it("throws MalformedRefError for every malformed token shape", () => {
+        const bad = [
+            "{{api: FETCH /x}}", // unsupported method
+            "{{api: GET x}}", // path missing leading slash
+            "{{api: GET }}", // missing path field
+            "{{code:x}}", // wrong token kind entirely
+            "{{api: GET /x foo:y}}", // unknown qualifier kind
+            "{{api: GET /x body:a..b}}", // empty segment in dotted name
+            "{{api: GET /x body:}}", // empty qualifier name
+            "{{api: GET /x bodynocolon}}", // qualifier with no colon
+            "{{api: GET /x body:a extra}}", // 4 fields (too many)
+        ];
+        for (const input of bad) {
+            expect(() => parseApiRef(input), input).toThrow(MalformedRefError);
+        }
+    });
+});
+describe("isMethod", () => {
+    it("accepts supported HTTP methods and rejects others", () => {
+        expect(isMethod("GET")).toBe(true);
+        expect(isMethod("FETCH")).toBe(false);
+    });
+});

package/dist/guard/api/types.js

@@ -0,0 +1 @@
+export {};

package/dist/guard/code/errors.js

@@ -0,0 +1,16 @@
+/**
+ * MalformedRefError is thrown by parseCodeRef when the input string does not
+ * match the {{code:…}} grammar. Callers use `err instanceof MalformedRefError`
+ * to distinguish parse failures from resolver or operational errors without
+ * string-matching.
+ *
+ * The Go original is the `ErrMalformedRef` sentinel, wrapped with the offending
+ * raw text via `fmt.Errorf("%w: %q", ErrMalformedRef, raw)`. We mirror that
+ * message shape so the raw text is always surfaced.
+ */
+export class MalformedRefError extends Error {
+    constructor(raw) {
+        super(`code: malformed ref: ${JSON.stringify(raw)}`);
+        this.name = "MalformedRefError";
+    }
+}

package/dist/guard/code/index.js

@@ -0,0 +1,2 @@
+export { MalformedRefError } from "./errors.js";
+export { parseCodeRef } from "./parser.js";

package/dist/guard/code/parser.js

@@ -0,0 +1,54 @@
+import { MalformedRefError } from "./errors.js";
+/**
+ * codeRefRE matches the full {{code:…}} token grammar.
+ *
+ * Capture groups:
+ *   m[1] = path           (non-empty; no whitespace, "#", or "}")
+ *   m[2] = symbol         (Go identifier: letter/underscore followed by word chars)
+ *   m[3] = ".member"      (optional member selector, e.g. ".get")
+ *   m[4] = "(sig)"        (optional signature, e.g. "(String[], int)" or "()")
+ *   m[5] = "@params.name" (optional param selector)
+ *
+ * All three optional facets (member, signature, param) are independent and may
+ * compose freely.
+ */
+const codeRefRE = /^\{\{code:([A-Za-z0-9_.][^\s#}]*)#([A-Za-z_]\w*)(\.[A-Za-z_][\w.]*)?(\([^)]*\))?(@params\.[A-Za-z_]\w*)?\}\}$/;
+/**
+ * parseCodeRef parses a raw {{code:…}} token into a typed CodeRef.
+ *
+ * Accepted forms:
+ *   {{code:pkg/foo.go#Bar}}                       → no facets
+ *   {{code:pkg/foo.go#Bar.field}}                 → Member: "field"
+ *   {{code:pkg/foo.go#Bar@params.x}}              → Param: "x"
+ *   {{code:pkg/foo.go#Bar.a.b.c}}                 → Member: "a.b.c"
+ *   {{code:p.java#C.get(String[], int)}}          → Member: "get", Signature: ["String[]","int"]
+ *   {{code:p.java#C.get()}}                       → Member: "get", Signature: []
+ *   {{code:p.java#C.get(String[])@params.id}}     → Member: "get", Signature: ["String[]"], Param: "id"
+ *
+ * Any other form throws a MalformedRefError with the offending raw text
+ * included. Callers check with `err instanceof MalformedRefError`.
+ */
+export function parseCodeRef(raw) {
+    const m = codeRefRE.exec(raw);
+    if (m === null) {
+        throw new MalformedRefError(raw);
+    }
+    // Groups 1 and 2 are non-optional in the pattern, so they always match.
+    const ref = {
+        Path: m[1],
+        Symbol: m[2],
+        Member: m[3] !== undefined ? m[3].slice(1) : "", // strip leading "."
+        Param: m[5] !== undefined ? m[5].slice("@params.".length) : "",
+    };
+    const sig = m[4]; // includes the surrounding parens, e.g. "(String[], int)"
+    if (sig !== undefined) {
+        const inner = sig.slice(1, -1); // strip the "(" and ")"
+        if (inner.trim() === "") {
+            ref.Signature = []; // "()" — zero-arg overload
+        }
+        else {
+            ref.Signature = inner.split(",").map((p) => p.trim());
+        }
+    }
+    return ref;
+}

package/dist/guard/code/parser.test.js

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "vitest";
+import { MalformedRefError } from "./errors.js";
+import { parseCodeRef } from "./parser.js";
+// parseCodeRef is the sole entry point for turning a raw {{code:…}} token into a
+// typed CodeRef. It must enforce the grammar — path, symbol, and the optional
+// member/param/signature facets — so downstream consumers (codeq's resolver in
+// the check pipeline) can trust the typed result without re-validating.
+// Rejection must produce an instanceof-matchable MalformedRefError so callers
+// can distinguish parse failures from resolver/operational errors.
+describe("parseCodeRef", () => {
+    // The facets (member, param, nested member) are the contract the resolver
+    // relies on; mis-splitting any of them would resolve the wrong symbol.
+    test("accepts the grammar variants and extracts each facet", () => {
+        const cases = [
+            {
+                in: "{{code:pkg/foo.go#Bar}}",
+                want: { Path: "pkg/foo.go", Symbol: "Bar", Member: "", Param: "" },
+            },
+            {
+                in: "{{code:pkg/foo.go#Bar.field}}",
+                want: { Path: "pkg/foo.go", Symbol: "Bar", Member: "field", Param: "" },
+            },
+            {
+                in: "{{code:pkg/foo.go#Bar@params.x}}",
+                want: { Path: "pkg/foo.go", Symbol: "Bar", Member: "", Param: "x" },
+            },
+            {
+                // A dotted member chain stays a single Member string; the resolver walks it.
+                in: "{{code:pkg/foo.go#Bar.nested.deep}}",
+                want: { Path: "pkg/foo.go", Symbol: "Bar", Member: "nested.deep", Param: "" },
+            },
+        ];
+        for (const tc of cases) {
+            expect(parseCodeRef(tc.in)).toEqual(tc.want);
+        }
+    });
+    // Malformed shapes must be rejected loudly, not silently coerced, or the guard
+    // would pass on a token it could never resolve.
+    test("rejects malformed shapes with MalformedRefError carrying the raw text", () => {
+        const cases = [
+            "{{code:#Bar}}", // empty path
+            "{{code:pkg/foo.go#}}", // empty symbol
+            "{{code:+pkg/foo.go#Bar}}", // leading sigil no longer accepted
+            "{{code:}}", // empty everything
+            "{{ code:pkg/foo.go#Bar }}", // surrounding whitespace not allowed
+        ];
+        for (const input of cases) {
+            let thrown;
+            try {
+                parseCodeRef(input);
+            }
+            catch (e) {
+                thrown = e;
+            }
+            expect(thrown, `parseCodeRef(${input}) should have thrown`).toBeInstanceOf(MalformedRefError);
+            // The raw text must appear in the message so callers can surface it.
+            expect(thrown.message).toContain(input);
+        }
+    });
+    // Overload disambiguation depends on the exact split of the parenthesised type
+    // list AND on member/sig/param composing (the old member-XOR-param rule is
+    // dropped). Each split element is whitespace-trimmed.
+    test("parses the (signature) facet and composes it with member and param", () => {
+        const cases = [
+            {
+                in: "{{code:p.java#C.get(String[], Integer, AbRequest)}}",
+                want: {
+                    Path: "p.java",
+                    Symbol: "C",
+                    Member: "get",
+                    Param: "",
+                    Signature: ["String[]", "Integer", "AbRequest"],
+                },
+            },
+            {
+                in: "{{code:p.java#C.get(String[])@params.id}}",
+                want: {
+                    Path: "p.java",
+                    Symbol: "C",
+                    Member: "get",
+                    Param: "id",
+                    Signature: ["String[]"],
+                },
+            },
+            {
+                // A bare-symbol signature (no member) is valid: F itself is the overload set.
+                in: "{{code:p.go#F([]string, int)}}",
+                want: {
+                    Path: "p.go",
+                    Symbol: "F",
+                    Member: "",
+                    Param: "",
+                    Signature: ["[]string", "int"],
+                },
+            },
+        ];
+        for (const tc of cases) {
+            expect(parseCodeRef(tc.in)).toEqual(tc.want);
+        }
+    });
+    // The empty-arg "()" overload must be distinguishable from the name-only case:
+    // "()" → defined-but-empty Signature; no parens → undefined Signature. The
+    // resolver treats these differently (zero-arg overload vs. match-any-arity).
+    test("distinguishes the zero-arg () overload from a name-only ref", () => {
+        const zeroArg = parseCodeRef("{{code:p.java#C.get()}}");
+        expect(zeroArg.Signature).toEqual([]);
+        expect(zeroArg.Member).toBe("get");
+        const nameOnly = parseCodeRef("{{code:p.go#Bar}}");
+        expect(nameOnly.Signature).toBeUndefined();
+    });
+});

package/dist/guard/code/types.js

@@ -0,0 +1,6 @@
+// Package code provides the CodeRef type, parseCodeRef function, and
+// MalformedRefError for the code guard.
+//
+// Import direction: guard/code is a leaf package; it does not import guard or
+// any other package to avoid cycles.
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+export const VERSION = "0.0.0-ts";

package/dist/index.test.js

@@ -0,0 +1,5 @@
+import { expect, test } from "vitest";
+import { VERSION } from "./index.js";
+test("VERSION is the placeholder TS version", () => {
+    expect(VERSION).toBe("0.0.0-ts");
+});

package/dist/repo/boundary.js

@@ -0,0 +1,92 @@
+import { InvalidPatternError } from "./errors.js";
+// validatePattern reports whether a boundary pattern is a syntactically valid
+// doublestar glob. It is intended to be called once at load time (config load)
+// so that a malformed boundary: field surfaces immediately rather than at first
+// check.
+//
+// Folder-prefix patterns (those ending in "/") are not glob patterns and are
+// accepted verbatim. All other patterns are validated with the same algorithm
+// doublestar.ValidatePattern uses, which accepts exactly the same set of
+// patterns that the check-time matcher will accept.
+//
+// Go used github.com/bmatcuk/doublestar's ValidatePattern. picomatch (the TS
+// glob library) is lenient and "repairs" malformed patterns rather than
+// rejecting them, so it cannot stand in for the validator. The algorithm below
+// is a direct port of doublestar's doValidatePattern with separator '/'.
+/**
+ * Throws {@link InvalidPatternError} (containing the offending pattern literal)
+ * when `pattern` is not a syntactically valid boundary glob. Returns void on
+ * success. Folder-prefix patterns (ending in "/") are always accepted.
+ */
+export function validatePattern(pattern) {
+    // Folder prefixes are accepted verbatim; they are not glob-validated.
+    if (pattern.endsWith("/")) {
+        return;
+    }
+    if (!isValidGlob(pattern)) {
+        throw new InvalidPatternError(pattern);
+    }
+}
+// isValidGlob is a direct port of doublestar.doValidatePattern(s, '/').
+// It walks the pattern byte-by-byte, tracking bracket character classes,
+// escapes, and {alternation} nesting, and returns false on any malformed
+// construct. Operating on UTF-16 code units matches the byte-oriented Go scan
+// for the ASCII metacharacters it inspects (\, [, ], ^, !, {, }).
+function isValidGlob(s) {
+    let altDepth = 0;
+    const l = s.length;
+    // Outer loop. `continue VALIDATE` in Go => labeled continue here.
+    validate: for (let i = 0; i < l; i++) {
+        const c = s[i];
+        switch (c) {
+            case "\\": {
+                // separator is '/', not '\\', so always skip the next byte.
+                i++;
+                if (i >= l) {
+                    // unclosed escape
+                    return false;
+                }
+                continue;
+            }
+            case "[": {
+                i++;
+                if (i >= l) {
+                    // class didn't end
+                    return false;
+                }
+                if (s[i] === "^" || s[i] === "!") {
+                    i++;
+                }
+                if (i >= l || s[i] === "]") {
+                    // class didn't end or empty character class
+                    return false;
+                }
+                for (; i < l; i++) {
+                    if (s[i] === "\\") {
+                        i++;
+                    }
+                    else if (s[i] === "]") {
+                        // looks good
+                        continue validate;
+                    }
+                }
+                // class didn't end
+                return false;
+            }
+            case "{": {
+                altDepth++;
+                continue;
+            }
+            case "}": {
+                if (altDepth === 0) {
+                    // alt end without a corresponding start
+                    return false;
+                }
+                altDepth--;
+                continue;
+            }
+        }
+    }
+    // valid as long as all alts are closed
+    return altDepth === 0;
+}

package/dist/repo/boundary.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { InvalidPatternError } from "./errors.js";
+import { validatePattern } from "./boundary.js";
+// WHY: malformed boundary patterns must be caught at load time (config load)
+// rather than at first use inside check resolution, so the user gets a clear
+// error immediately instead of a confusing failure when a doc is first checked.
+// picomatch silently "repairs" these patterns, so the validator can't lean on
+// it — this guards the hand-ported doublestar validation algorithm.
+describe("validatePattern", () => {
+    const valid = [
+        "docs/plans/*-[0-9]*.md",
+        "docs/plans/*-plan.md",
+        "docs/adr/*.md",
+        "docs/", // folder prefix: ends in "/"
+    ];
+    for (const pattern of valid) {
+        test(`accepts valid catalog pattern ${JSON.stringify(pattern)}`, () => {
+            expect(() => validatePattern(pattern)).not.toThrow();
+        });
+    }
+    // WHY: each accepted shape exercises a distinct branch of the hand-ported
+    // doublestar validator — negated/escaped/closed character classes and balanced
+    // alternations. A regression in any of those branches would either reject a
+    // legitimate catalog pattern (blocking a valid config) or fall through to the
+    // lenient picomatch behaviour the port exists to avoid.
+    const validBranches = [
+        "docs/[^x].md", // negated class via "^"
+        "docs/[!x].md", // negated class via "!"
+        "docs/[\\]].md", // escaped "]" inside the class, then real close
+        "docs/[abc].md", // ordinary closed character class
+        "docs/{a,b}.md", // balanced alternation
+        "docs/{a,{b,c}}.md", // nested balanced alternations
+        "docs/\\*.md", // escaped metacharacter (mid-pattern escape)
+    ];
+    for (const pattern of validBranches) {
+        test(`accepts ${JSON.stringify(pattern)} (well-formed glob construct)`, () => {
+            expect(() => validatePattern(pattern)).not.toThrow();
+        });
+    }
+    const malformed = [
+        "docs/[", // unclosed bracket
+        "docs/[a-", // incomplete range
+        "docs/\\", // unclosed escape
+        "docs/[]", // empty character class
+        "docs/[^", // negated class that never closes
+        "docs/[a\\", // escape at end inside a class
+        "docs/a}", // alternation close with no matching open
+        "docs/{a", // alternation open that never closes
+    ];
+    for (const pattern of malformed) {
+        test(`rejects malformed pattern ${JSON.stringify(pattern)} with InvalidPatternError naming the literal`, () => {
+            let thrown;
+            try {
+                validatePattern(pattern);
+            }
+            catch (e) {
+                thrown = e;
+            }
+            expect(thrown).toBeInstanceOf(InvalidPatternError);
+            // The error message must contain the offending pattern literal so the
+            // user can see exactly which boundary entry is broken.
+            expect(thrown.message).toContain(pattern);
+        });
+    }
+});

package/dist/repo/errors.js

@@ -0,0 +1,56 @@
+// Sentinel error types for the repo package. Each mirrors a Go sentinel
+// (var ErrFoo = errors.New(...)) and is ported as a named Error subclass so
+// callers can discriminate with `instanceof` the way Go callers use errors.Is.
+/**
+ * Thrown by {@link validatePattern} when a boundary pattern contains malformed
+ * bracket expressions or unclosed escapes. Mirrors Go's ErrInvalidPattern.
+ */
+export class InvalidPatternError extends Error {
+    constructor(pattern) {
+        super(`repo: invalid boundary pattern: ${JSON.stringify(pattern)}`);
+        this.name = "InvalidPatternError";
+    }
+}
+/**
+ * Mirrors Go's ErrAmbiguousBoundary. Surfaced (wrapped) by check.ResolveError
+ * when two boundaries of equal specificity both match the same file. Declared
+ * here so the dependent check layer can throw/wrap it; not raised by repo
+ * itself.
+ */
+export class AmbiguousBoundaryError extends Error {
+    constructor(message = "repo: boundary pattern matches multiple doc types") {
+        super(message);
+        this.name = "AmbiguousBoundaryError";
+    }
+}
+/**
+ * Thrown by {@link planHeaderFilename} and {@link packetFilename} when the task
+ * name slug does not match ^[a-z0-9][a-z0-9-]*[a-z0-9]$. Mirrors Go's
+ * ErrInvalidTaskName.
+ */
+export class InvalidTaskNameError extends Error {
+    constructor(name, pattern) {
+        super(`repo: invalid task name slug: ${JSON.stringify(name)} (must match ${pattern})`);
+        this.name = "InvalidTaskNameError";
+    }
+}
+/**
+ * Thrown by {@link packetFilename} when the packet index is outside 1..99.
+ * Mirrors Go's ErrPacketCountOutOfRange.
+ */
+export class PacketCountOutOfRangeError extends Error {
+    constructor(packet) {
+        super(`repo: packet count out of range (1..99): ${packet} (1..99)`);
+        this.name = "PacketCountOutOfRangeError";
+    }
+}
+/**
+ * Mirrors Go's ErrFileExists. Declared for the dependent write-with-backup
+ * layer; not raised by repo itself.
+ */
+export class FileExistsError extends Error {
+    constructor(message = "repo: file already exists") {
+        super(message);
+        this.name = "FileExistsError";
+    }
+}