@de-otio/repo-aegis-core 0.2.0

package/dist/deny-set.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { denySetCachePath as defaultDenySetCachePath, markersDir as defaultMarkersDir, } from "./paths.js";
+export const ALWAYS_FILE_STEM = "_always";
+// Bumped to 2 when patternSources was added; v1 caches are invalidated
+// (the read path's schemaVersion check returns null, falling through to
+// recompute).
+const DENY_SET_CACHE_VERSION = 2;
+/**
+ * Build a fingerprint of the inputs to computeDenySet. Two calls with the
+ * same fingerprint produce the same deny set. Includes:
+ *   - repo class + sorted engagements (these change the per-engagement
+ *     filtering applied to the marker file set)
+ *   - the marker dir's file list, mtimes, and sizes (any edit to a marker
+ *     file or addition/removal invalidates the cache)
+ */
+function computeFingerprint(repo, dir) {
+    const fileSummaries = [];
+    if (existsSync(dir)) {
+        const files = readdirSync(dir).filter(f => f.endsWith(".txt")).sort();
+        for (const f of files) {
+            const st = statSync(join(dir, f));
+            fileSummaries.push(`${f}:${st.mtimeMs}:${st.size}`);
+        }
+    }
+    const sortedEng = [...repo.engagements].sort().join(",");
+    const input = `v${DENY_SET_CACHE_VERSION}|${repo.class}|${sortedEng}|${fileSummaries.join(";")}`;
+    return createHash("sha256").update(input).digest("hex");
+}
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (parsed.schemaVersion !== DENY_SET_CACHE_VERSION ||
+            typeof parsed.key !== "string" ||
+            !Array.isArray(parsed.files) ||
+            !Array.isArray(parsed.patterns) ||
+            !Array.isArray(parsed.patternSources) ||
+            parsed.patternSources.length !== parsed.patterns.length ||
+            typeof parsed.combinedRegex !== "string" ||
+            !Array.isArray(parsed.warnings)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cachePath, entry) {
+    try {
+        mkdirSync(dirname(cachePath), { recursive: true });
+        writeFileSync(cachePath, JSON.stringify(entry, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* cache is best-effort; failure to write is not fatal */
+    }
+}
+/**
+ * Compute the per-repo deny set. Class-aware:
+ *
+ * - `public-eligible` / `private-strict`: full union (every marker file).
+ *   Engagement field on the repo is ignored; if set, a warning is emitted.
+ * - `customer-coupled`: union of `_always.txt` + every per-engagement file
+ *   whose stem is NOT in this repo's `engagements` list.
+ * - `scratch`: same set as `customer-coupled`, but the caller (the CLI's
+ *   `check`) treats hits as advisory and exits 0.
+ */
+export function computeDenySet(repo, opts = {}) {
+    const dir = opts.markersDir ?? defaultMarkersDir();
+    const warnings = [];
+    if ((repo.class === "public-eligible" || repo.class === "private-strict") &&
+        repo.engagements.length > 0) {
+        warnings.push(`repo class is ${repo.class} but ${repo.engagements.length} engagement(s) are set; ` +
+            `engagement field is ignored for non-customer-coupled classes`);
+    }
+    // Cache fast-path. Cache is keyed on (class, engagements, marker-file
+    // mtimes+sizes). An exact key match returns the cached deny set without
+    // re-reading any marker file. Caller can disable with cachePath: null
+    // (tests) or override the path. The base warnings (repo-class engagement
+    // mismatch, computed above) are always recomputed so they reflect the
+    // current call rather than what the cache wrote at fingerprint time.
+    const cachePath = opts.cachePath === null ? null : opts.cachePath ?? defaultDenySetCachePath();
+    const fingerprint = computeFingerprint(repo, dir);
+    if (cachePath !== null) {
+        const cached = readCache(cachePath);
+        if (cached !== null && cached.key === fingerprint) {
+            return {
+                files: cached.files,
+                patterns: cached.patterns,
+                patternSources: cached.patternSources,
+                combinedRegex: cached.combinedRegex,
+                warnings: [...warnings, ...cached.warnings.filter(w => !warnings.includes(w))],
+            };
+        }
+    }
+    if (!existsSync(dir)) {
+        const empty = { files: [], patterns: [], patternSources: [], combinedRegex: "", warnings };
+        if (cachePath !== null) {
+            writeCache(cachePath, {
+                schemaVersion: DENY_SET_CACHE_VERSION,
+                key: fingerprint,
+                files: [],
+                patterns: [],
+                patternSources: [],
+                combinedRegex: "",
+                warnings: [],
+            });
+        }
+        return empty;
+    }
+    const own = new Set(repo.engagements);
+    const useScoping = repo.class === "customer-coupled" || repo.class === "scratch";
+    const files = readdirSync(dir)
+        .filter(f => f.endsWith(".txt"))
+        .map(f => ({ stem: f.replace(/\.txt$/, ""), path: join(dir, f) }))
+        .filter(({ stem }) => {
+        if (stem === ALWAYS_FILE_STEM)
+            return true;
+        if (!useScoping)
+            return true;
+        return !own.has(stem);
+    });
+    const patterns = [];
+    const patternSources = [];
+    for (const f of files) {
+        const lines = readFileSync(f.path, "utf8").split("\n");
+        for (const raw of lines) {
+            const trimmed = raw.trim();
+            // A line is a comment only if its first non-whitespace character is `;`.
+            // Mid-line `;` is part of the pattern (e.g. `db;internal` is a literal
+            // marker, not "db" with a comment).
+            if (trimmed.length === 0 || trimmed.startsWith(";"))
+                continue;
+            patterns.push(trimmed);
+            patternSources.push(f.stem);
+        }
+    }
+    const result = {
+        files,
+        patterns,
+        patternSources,
+        combinedRegex: patterns.join("|"),
+        warnings,
+    };
+    if (cachePath !== null) {
+        writeCache(cachePath, {
+            schemaVersion: DENY_SET_CACHE_VERSION,
+            key: fingerprint,
+            files,
+            patterns,
+            patternSources,
+            combinedRegex: result.combinedRegex,
+            // Cache only the input-derived warnings; the call-time class mismatch
+            // warning is recomputed above per call.
+            warnings: [],
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=deny-set.js.map

package/dist/deny-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny-set.js","sourceRoot":"","sources":["../src/deny-set.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qDAAqD;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,gBAAgB,IAAI,uBAAuB,EAC3C,UAAU,IAAI,iBAAiB,GAChC,MAAM,YAAY,CAAC;AAGpB,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAkC1C,uEAAuE;AACvE,wEAAwE;AACxE,cAAc;AACd,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAYjC;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAAC,IAAgB,EAAE,GAAW;IACvD,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;YAClC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,IAAI,sBAAsB,IAAI,IAAI,CAAC,KAAK,IAAI,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACjG,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,SAAS,CAAC,SAAiB;IAClC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAwB,CAAC;QAClF,IACE,MAAM,CAAC,aAAa,KAAK,sBAAsB;YAC/C,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YAC5B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC/B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC;YACrC,MAAM,CAAC,cAAc,CAAC,MAAM,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM;YACvD,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ;YACxC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAC/B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,MAAoB,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,SAAiB,EAAE,KAAiB;IACtD,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAgB,EAAE,OAAuB,EAAE;IACxE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,EAAE,CAAC;IACnD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,iBAAiB,IAAI,IAAI,CAAC,KAAK,KAAK,gBAAgB,CAAC;QACrE,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,QAAQ,CAAC,IAAI,CACX,iBAAiB,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,MAAM,0BAA0B;YAClF,8DAA8D,CACjE,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,wEAAwE;IACxE,sEAAsE;IACtE,yEAAyE;IACzE,sEAAsE;IACtE,qEAAqE;IACrE,MAAM,SAAS,GACb,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,uBAAuB,EAAE,CAAC;IAC/E,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAElD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,GAAG,KAAK,WAAW,EAAE,CAAC;YAClD,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;aAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,GAAY,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;QACpG,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,SAAS,EAAE;gBACpB,aAAa,EAAE,sBAAsB;gBACrC,GAAG,EAAE,WAAW;gBAChB,KAAK,EAAE,EAAE;gBACT,QAAQ,EAAE,EAAE;gBACZ,cAAc,EAAE,EAAE;gBAClB,aAAa,EAAE,EAAE;gBACjB,QAAQ,EAAE,EAAE;aACb,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,KAAK,kBAAkB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IAEjF,MAAM,KAAK,GAAkB,WAAW,CAAC,GAAG,CAAC;SAC1C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;SACjE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;QACnB,IAAI,IAAI,KAAK,gBAAgB;YAAE,OAAO,IAAI,CAAC;QAC3C,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEL,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,yEAAyE;YACzE,uEAAuE;YACvE,oCAAoC;YACpC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC9D,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAY;QACtB,KAAK;QACL,QAAQ;QACR,cAAc;QACd,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;QACjC,QAAQ;KACT,CAAC;IAEF,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,UAAU,CAAC,SAAS,EAAE;YACpB,aAAa,EAAE,sBAAsB;YACrC,GAAG,EAAE,WAAW;YAChB,KAAK;YACL,QAAQ;YACR,cAAc;YACd,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,sEAAsE;YACtE,wCAAwC;YACxC,QAAQ,EAAE,EAAE;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/deny-set.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deny-set.test.d.ts.map

package/dist/deny-set.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny-set.test.d.ts","sourceRoot":"","sources":["../src/deny-set.test.ts"],"names":[],"mappings":""}

package/dist/deny-set.test.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { computeDenySet, ALWAYS_FILE_STEM } from "./deny-set.js";
+let tmp;
+let markersDir;
+function setupMarkers() {
+    rmSync(markersDir, { recursive: true, force: true });
+    mkdirSync(markersDir, { recursive: true });
+    writeFileSync(join(markersDir, `${ALWAYS_FILE_STEM}.txt`), "PROJECT-CODENAME-ALPHA\n");
+    writeFileSync(join(markersDir, "customer-a.txt"), "acme-corp\nacme\\.com\n");
+    writeFileSync(join(markersDir, "customer-b.txt"), "betaco\nbetaco\\.tech\n");
+}
+function makeRepo(cls, engagements = []) {
+    return {
+        cwd: "/tmp/fake",
+        isGitRepo: true,
+        class: cls,
+        classExplicit: true,
+        engagements,
+    };
+}
+before(() => {
+    tmp = mkdtempSync(join(tmpdir(), "repo-aegis-denyset-"));
+    markersDir = join(tmp, "markers");
+    setupMarkers();
+});
+after(() => {
+    rmSync(tmp, { recursive: true, force: true });
+});
+describe("computeDenySet", () => {
+    it("returns empty set when markers dir does not exist", () => {
+        const ds = computeDenySet(makeRepo("private-strict"), { markersDir: join(tmp, "no-such-dir") });
+        assert.equal(ds.patterns.length, 0);
+        assert.equal(ds.combinedRegex, "");
+    });
+    it("public-eligible: full union (all marker files, no scoping)", () => {
+        const ds = computeDenySet(makeRepo("public-eligible"), { markersDir });
+        assert.equal(ds.files.length, 3);
+        assert.ok(ds.patterns.includes("acme-corp"));
+        assert.ok(ds.patterns.includes("betaco"));
+        assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+    });
+    it("private-strict: same as public-eligible", () => {
+        const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+        assert.equal(ds.files.length, 3);
+    });
+    it("public-eligible warns if engagement is set", () => {
+        const ds = computeDenySet(makeRepo("public-eligible", ["customer-a"]), { markersDir });
+        assert.ok(ds.warnings.length > 0);
+        // engagement is ignored: full deny set
+        assert.equal(ds.files.length, 3);
+        assert.ok(ds.patterns.includes("acme-corp"));
+    });
+    it("customer-coupled: scopes deny set, excluding own engagement", () => {
+        const ds = computeDenySet(makeRepo("customer-coupled", ["customer-a"]), { markersDir });
+        const stems = ds.files.map(f => f.stem).sort();
+        assert.deepEqual(stems, [ALWAYS_FILE_STEM, "customer-b"]);
+        assert.ok(ds.patterns.includes("betaco"));
+        assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+        assert.ok(!ds.patterns.includes("acme-corp"));
+    });
+    it("customer-coupled: still blocks _always", () => {
+        const ds = computeDenySet(makeRepo("customer-coupled", ["customer-a"]), { markersDir });
+        assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+    });
+    it("customer-coupled: multi-engagement excludes both own files", () => {
+        const ds = computeDenySet(makeRepo("customer-coupled", ["customer-a", "customer-b"]), { markersDir });
+        const stems = ds.files.map(f => f.stem).sort();
+        assert.deepEqual(stems, [ALWAYS_FILE_STEM]);
+        assert.ok(!ds.patterns.includes("acme-corp"));
+        assert.ok(!ds.patterns.includes("betaco"));
+    });
+    it("customer-coupled: empty engagements still computes deny set (caller enforces error)", () => {
+        const ds = computeDenySet(makeRepo("customer-coupled", []), { markersDir });
+        // Library doesn't enforce the error; that's the CLI's job. Library returns full set.
+        assert.equal(ds.files.length, 3);
+    });
+    it("scratch: same scoping as customer-coupled", () => {
+        const ds = computeDenySet(makeRepo("scratch", ["customer-a"]), { markersDir });
+        assert.equal(ds.files.length, 2);
+    });
+    it("strips ; comments and blank lines from marker files", () => {
+        writeFileSync(join(markersDir, "customer-c.txt"), "; comment line\n\nfirst-pattern\n; another comment\nsecond-pattern\n");
+        const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+        assert.ok(ds.patterns.includes("first-pattern"));
+        assert.ok(ds.patterns.includes("second-pattern"));
+        assert.ok(!ds.patterns.some(p => p.includes("comment")));
+        // restore
+        rmSync(join(markersDir, "customer-c.txt"));
+    });
+    it("writes a cache file with the expected shape on miss", () => {
+        const cachePath = join(tmp, "cache-shape.json");
+        const repo = makeRepo("private-strict");
+        const ds = computeDenySet(repo, { markersDir, cachePath });
+        assert.ok(existsSync(cachePath), "cache file written");
+        const cached = JSON.parse(readFileSync(cachePath, "utf8"));
+        assert.equal(cached.schemaVersion, 2);
+        assert.equal(typeof cached.key, "string");
+        assert.equal(cached.key.length, 64, "fingerprint is sha256 hex");
+        assert.deepEqual(cached.patterns, ds.patterns);
+        assert.equal(cached.combinedRegex, ds.combinedRegex);
+    });
+    it("invalidates cache when a marker file changes (mtime updated)", () => {
+        const cachePath = join(tmp, "cache-invalidate.json");
+        const repo = makeRepo("private-strict");
+        const ds1 = computeDenySet(repo, { markersDir, cachePath });
+        // Change a marker file with a NEW mtime + different size.
+        const acmePath = join(markersDir, "customer-a.txt");
+        writeFileSync(acmePath, "completely-different-content\n");
+        const ds2 = computeDenySet(repo, { markersDir, cachePath });
+        assert.notDeepEqual(ds2.patterns, ds1.patterns, "cache must invalidate on marker change");
+        assert.ok(ds2.patterns.includes("completely-different-content"));
+        // Restore for downstream tests.
+        setupMarkers();
+    });
+    it("cachePath: null disables caching", () => {
+        const repo = makeRepo("private-strict");
+        const initialFiles = readdirSync(tmp).filter(f => f.endsWith(".json")).length;
+        computeDenySet(repo, { markersDir, cachePath: null });
+        const after = readdirSync(tmp).filter(f => f.endsWith(".json")).length;
+        assert.equal(after, initialFiles, "no cache file should be written");
+    });
+    it("populates patternSources parallel to patterns", () => {
+        const repo = makeRepo("private-strict");
+        const ds = computeDenySet(repo, { markersDir, cachePath: null });
+        assert.equal(ds.patternSources?.length, ds.patterns.length, "lengths must match");
+        // Spot-check: alphabetical file order is _always, customer-a, customer-b
+        const alwaysIdx = ds.patterns.findIndex(p => p === "PROJECT-CODENAME-ALPHA");
+        if (alwaysIdx >= 0) {
+            assert.equal(ds.patternSources[alwaysIdx], "_always");
+        }
+        const acmeIdx = ds.patterns.findIndex(p => p === "acme-corp");
+        if (acmeIdx >= 0) {
+            assert.equal(ds.patternSources[acmeIdx], "customer-a");
+        }
+    });
+    it("preserves mid-line ; characters in marker patterns", () => {
+        // Regression: legitimate patterns containing `;` (e.g. `db;internal`,
+        // `key;value` form codenames) used to be silently truncated at the
+        // first `;`. Only lines whose first non-whitespace character is `;`
+        // are comments.
+        writeFileSync(join(markersDir, "customer-d.txt"), "db;internal\nkey;val;more\n  ; leading-space-comment\n");
+        const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+        assert.ok(ds.patterns.includes("db;internal"), "mid-line ; must not truncate");
+        assert.ok(ds.patterns.includes("key;val;more"), "multiple mid-line ; must survive");
+        assert.ok(!ds.patterns.some(p => p.includes("leading-space-comment")), "leading-whitespace ; lines are still comments");
+        rmSync(join(markersDir, "customer-d.txt"));
+    });
+});
+//# sourceMappingURL=deny-set.test.js.map

package/dist/deny-set.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny-set.test.js","sourceRoot":"","sources":["../src/deny-set.test.ts"],"names":[],"mappings":"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"}

package/dist/exceptions.d.ts

@@ -0,0 +1,96 @@
+export declare class RegistryNotFoundError extends Error {
+    path: string;
+    readonly code: "REGISTRY_NOT_FOUND";
+    constructor(path: string);
+}
+export declare class RegistryParseError extends Error {
+    path: string;
+    cause: unknown;
+    readonly code: "REGISTRY_PARSE";
+    constructor(path: string, cause: unknown);
+}
+/**
+ * Raised by `loadRegistry` when the plaintext registry path is absent
+ * but a sibling `<path>.age` ciphertext exists. The user (or the agent
+ * on their behalf) must run `repo-aegis registry decrypt --identity
+ * <path>` before any registry-reading command will work.
+ *
+ * Why this is its own error: encrypted-at-rest is the *intended* state
+ * during periods of non-use. Auto-decrypt would defeat the purpose
+ * (any process could read the registry). Surfacing a distinct code
+ * lets the agent guide the user to the right command without trying
+ * to recover blindly.
+ */
+export declare class RegistryEncryptedError extends Error {
+    path: string;
+    ciphertextPath: string;
+    readonly code: "REGISTRY_ENCRYPTED";
+    constructor(path: string, ciphertextPath: string);
+}
+export declare class NotAGitRepoError extends Error {
+    readonly code: "NOT_GIT_REPO";
+    constructor();
+}
+export declare class AmbiguousQueryError extends Error {
+    query: string;
+    candidateCount: number;
+    readonly code: "AMBIGUOUS_QUERY";
+    constructor(query: string, candidateCount: number);
+}
+export declare class EngagementNotFoundError extends Error {
+    query: string;
+    readonly code: "ENGAGEMENT_NOT_FOUND";
+    constructor(query: string);
+}
+export declare class PatternValidationError extends Error {
+    invalid: {
+        pattern: string;
+        reason: string;
+        engagementId?: string;
+    }[];
+    readonly code: "PATTERN_VALIDATION";
+    constructor(invalid: {
+        pattern: string;
+        reason: string;
+        engagementId?: string;
+    }[]);
+    /**
+     * Same shape as {@link invalid} but with each `pattern` field passed
+     * through {@link redactMatch} so the literal customer-derived substring
+     * never leaves the process.
+     *
+     * Marker patterns are user-authored regexes that typically embed
+     * customer-derived strings (e.g. `acmeengineering\.com`). They fall
+     * under the same redaction policy as match values whenever they are
+     * surfaced to JSON, log files, or anything an AI agent might
+     * subsequently read.
+     *
+     * Callers serialising this error to JSON, stderr, or any persisted
+     * artifact should prefer `redactedPatterns`. The raw `invalid` field
+     * remains for the in-process renderer (it needs the literal pattern to
+     * point the user at the offending entry in their own marker file) —
+     * that is an internal contract; do not leak it across a process
+     * boundary.
+     */
+    get redactedPatterns(): {
+        pattern: string;
+        reason: string;
+        engagementId?: string;
+    }[];
+}
+export declare class OutsideWorkingTreeError extends Error {
+    path: string;
+    workingTree: string;
+    readonly code: "OUTSIDE_WORKING_TREE";
+    constructor(path: string, workingTree: string);
+}
+export declare class LockTimeoutError extends Error {
+    lockPath: string;
+    readonly code: "LOCK_TIMEOUT";
+    constructor(lockPath: string);
+}
+export declare class CustomerCoupledNoEngagementError extends Error {
+    readonly code: "CUSTOMER_COUPLED_NO_ENGAGEMENT";
+    constructor();
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAIA,qBAAa,qBAAsB,SAAQ,KAAK;IAE3B,IAAI,EAAE,MAAM;IAD/B,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAC3B,IAAI,EAAE,MAAM;CAIhC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAExB,IAAI,EAAE,MAAM;IAAkB,KAAK,EAAE,OAAO;IAD/D,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;gBACvB,IAAI,EAAE,MAAM,EAAkB,KAAK,EAAE,OAAO;CAIhE;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE5B,IAAI,EAAE,MAAM;IAAS,cAAc,EAAE,MAAM;IAD9D,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAC3B,IAAI,EAAE,MAAM,EAAS,cAAc,EAAE,MAAM;CAQ/D;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAG,cAAc,CAAU;;CAKzC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAEzB,KAAK,EAAE,MAAM;IAAS,cAAc,EAAE,MAAM;IAD/D,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBACxB,KAAK,EAAE,MAAM,EAAS,cAAc,EAAE,MAAM;CAIhE;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE7B,KAAK,EAAE,MAAM;IADhC,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;gBAC7B,KAAK,EAAE,MAAM;CAIjC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAGtC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE;IAF9E,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAErC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE;IAM9E;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,gBAAgB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CASnF;CACF;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE7B,IAAI,EAAE,MAAM;IAAS,WAAW,EAAE,MAAM;IAD3D,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;gBAC7B,IAAI,EAAE,MAAM,EAAS,WAAW,EAAE,MAAM;CAI5D;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAEtB,QAAQ,EAAE,MAAM;IADnC,QAAQ,CAAC,IAAI,EAAG,cAAc,CAAU;gBACrB,QAAQ,EAAE,MAAM;CAIpC;AAED,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,EAAG,gCAAgC,CAAU;;CAS3D"}

package/dist/exceptions.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { redactMatch } from "./redaction.js";
+export class RegistryNotFoundError extends Error {
+    path;
+    code = "REGISTRY_NOT_FOUND";
+    constructor(path) {
+        super(`engagement registry not found at ${path}`);
+        this.path = path;
+        this.name = "RegistryNotFoundError";
+    }
+}
+export class RegistryParseError extends Error {
+    path;
+    cause;
+    code = "REGISTRY_PARSE";
+    constructor(path, cause) {
+        super(`failed to parse registry at ${path}: ${cause.message ?? cause}`);
+        this.path = path;
+        this.cause = cause;
+        this.name = "RegistryParseError";
+    }
+}
+/**
+ * Raised by `loadRegistry` when the plaintext registry path is absent
+ * but a sibling `<path>.age` ciphertext exists. The user (or the agent
+ * on their behalf) must run `repo-aegis registry decrypt --identity
+ * <path>` before any registry-reading command will work.
+ *
+ * Why this is its own error: encrypted-at-rest is the *intended* state
+ * during periods of non-use. Auto-decrypt would defeat the purpose
+ * (any process could read the registry). Surfacing a distinct code
+ * lets the agent guide the user to the right command without trying
+ * to recover blindly.
+ */
+export class RegistryEncryptedError extends Error {
+    path;
+    ciphertextPath;
+    code = "REGISTRY_ENCRYPTED";
+    constructor(path, ciphertextPath) {
+        super(`engagement registry at ${path} is encrypted at rest ` +
+            `(ciphertext present at ${ciphertextPath}); ` +
+            `run \`repo-aegis registry decrypt --identity <path>\` first`);
+        this.path = path;
+        this.ciphertextPath = ciphertextPath;
+        this.name = "RegistryEncryptedError";
+    }
+}
+export class NotAGitRepoError extends Error {
+    code = "NOT_GIT_REPO";
+    constructor() {
+        super("not inside a git repository");
+        this.name = "NotAGitRepoError";
+    }
+}
+export class AmbiguousQueryError extends Error {
+    query;
+    candidateCount;
+    code = "AMBIGUOUS_QUERY";
+    constructor(query, candidateCount) {
+        super(`ambiguous engagement query "${query}" (${candidateCount} candidates)`);
+        this.query = query;
+        this.candidateCount = candidateCount;
+        this.name = "AmbiguousQueryError";
+    }
+}
+export class EngagementNotFoundError extends Error {
+    query;
+    code = "ENGAGEMENT_NOT_FOUND";
+    constructor(query) {
+        super(`no engagement matches "${query}"`);
+        this.query = query;
+        this.name = "EngagementNotFoundError";
+    }
+}
+export class PatternValidationError extends Error {
+    invalid;
+    code = "PATTERN_VALIDATION";
+    constructor(invalid) {
+        super(`${invalid.length} marker pattern${invalid.length === 1 ? "" : "s"} failed validation`);
+        this.invalid = invalid;
+        this.name = "PatternValidationError";
+    }
+    /**
+     * Same shape as {@link invalid} but with each `pattern` field passed
+     * through {@link redactMatch} so the literal customer-derived substring
+     * never leaves the process.
+     *
+     * Marker patterns are user-authored regexes that typically embed
+     * customer-derived strings (e.g. `acmeengineering\.com`). They fall
+     * under the same redaction policy as match values whenever they are
+     * surfaced to JSON, log files, or anything an AI agent might
+     * subsequently read.
+     *
+     * Callers serialising this error to JSON, stderr, or any persisted
+     * artifact should prefer `redactedPatterns`. The raw `invalid` field
+     * remains for the in-process renderer (it needs the literal pattern to
+     * point the user at the offending entry in their own marker file) —
+     * that is an internal contract; do not leak it across a process
+     * boundary.
+     */
+    get redactedPatterns() {
+        return this.invalid.map(entry => {
+            const out = {
+                pattern: redactMatch(entry.pattern),
+                reason: entry.reason,
+            };
+            if (entry.engagementId !== undefined)
+                out.engagementId = entry.engagementId;
+            return out;
+        });
+    }
+}
+export class OutsideWorkingTreeError extends Error {
+    path;
+    workingTree;
+    code = "OUTSIDE_WORKING_TREE";
+    constructor(path, workingTree) {
+        super(`path ${path} is outside the working tree ${workingTree}`);
+        this.path = path;
+        this.workingTree = workingTree;
+        this.name = "OutsideWorkingTreeError";
+    }
+}
+export class LockTimeoutError extends Error {
+    lockPath;
+    code = "LOCK_TIMEOUT";
+    constructor(lockPath) {
+        super(`could not acquire registry lock at ${lockPath} (another repo-aegis process is running?)`);
+        this.lockPath = lockPath;
+        this.name = "LockTimeoutError";
+    }
+}
+export class CustomerCoupledNoEngagementError extends Error {
+    code = "CUSTOMER_COUPLED_NO_ENGAGEMENT";
+    constructor() {
+        super("repo-aegis.class=customer-coupled but no repo-aegis.engagement is set; " +
+            "run `repo-aegis allow <engagement-id>` to declare which engagement(s) " +
+            "this repo legitimately references");
+        this.name = "CustomerCoupledNoEngagementError";
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"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"}

package/dist/exit-codes.d.ts

@@ -0,0 +1,4 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_HIT = 1;
+export declare const EXIT_USAGE = 2;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,eAAO,MAAM,UAAU,IAAI,CAAC"}

package/dist/exit-codes.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+export const EXIT_OK = 0;
+export const EXIT_HIT = 1;
+export const EXIT_USAGE = 2;
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AACzB,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC;AAC1B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC"}