@de-otio/repo-aegis-core 0.2.0

package/src/registry.ts

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { readFileSync, existsSync } from "node:fs";
+import { parse } from "yaml";
+import { z } from "zod";
+import { registryPath } from "./paths.js";
+import {
+  RegistryNotFoundError,
+  RegistryParseError,
+  RegistryEncryptedError,
+} from "./exceptions.js";
+import { registryFileSchema, formatZodError } from "./schemas.js";
+
+export interface Engagement {
+  id: string;
+  name: string;
+  started?: string | null;
+  ended?: string | null;
+  reposActive?: string[];
+  markers: string[];
+  notes?: string;
+  /**
+   * GitHub orgs that map to this engagement (Phase 1, schemaVersion 2+).
+   * A repo whose origin's org appears here is auto-classified
+   * `customer-coupled` with this engagement. Lowercased, GitHub
+   * org-name shape; cross-validated for uniqueness across all
+   * engagements and disjointness with {@link Registry.personalOrgs}.
+   */
+  githubOrgs?: string[];
+}
+
+export interface Registry {
+  engagements: Engagement[];
+  alwaysBlock: string[];
+  /**
+   * GitHub orgs the user owns / treats as public (schemaVersion 2+).
+   * A repo whose origin's org is in this list is auto-classified
+   * `public-eligible`. Disjoint from any engagement's `githubOrgs`.
+   * Optional in the type so callers constructing Registry literals
+   * (tests, fixtures) don't have to specify; `loadRegistry` always
+   * populates it (defaults to `[]` for v1 registries that don't
+   * declare the field).
+   */
+  personalOrgs?: string[];
+  /**
+   * Schema version of the on-disk registry. Defaults to 1 when the YAML has
+   * no `schemaVersion:` field (legacy). Readers refuse versions
+   * greater than {@link MAX_SUPPORTED_REGISTRY_SCHEMA_VERSION}. Optional in
+   * the type so callers constructing Registry literals (tests, fixtures)
+   * don't have to specify; loadRegistry always populates it.
+   */
+  schemaVersion?: number;
+}
+
+export const ALWAYS_BLOCK_RESERVED_ID = "_always";
+
+/**
+ * Highest registry `schemaVersion` this build of repo-aegis can read.
+ *
+ * - v1 (legacy): no `schemaVersion`, no `personalOrgs`, no
+ *   `engagements[*].githubOrgs`. Loaded with `personalOrgs: []` and every
+ *   engagement's `githubOrgs` undefined.
+ * - v2 (Phase 1 onboarding): adds `personalOrgs` and
+ *   `engagements[*].githubOrgs` for org-keyed JIT classification.
+ *
+ * Reader policy:
+ *   - missing field => treat as version 1 (legacy);
+ *   - version <= MAX => accept (unknown sibling fields are ignored);
+ *   - version  > MAX => refuse with "upgrade required".
+ * Writers must never lower the version.
+ */
+export const MAX_SUPPORTED_REGISTRY_SCHEMA_VERSION = 2;
+
+export function loadRegistry(path: string = registryPath()): Registry {
+  // If the plaintext registry is absent but a sibling `<path>.age`
+  // ciphertext exists, the registry is in its encrypted-at-rest state.
+  // We deliberately do NOT auto-decrypt: the whole point of the
+  // encryption is that the registry only goes plaintext when the user
+  // explicitly opts in with `repo-aegis registry decrypt --identity
+  // <path>`. Auto-decrypt would defeat the purpose.
+  if (!existsSync(path)) {
+    const ciphertextPath = `${path}.age`;
+    if (existsSync(ciphertextPath)) {
+      throw new RegistryEncryptedError(path, ciphertextPath);
+    }
+    throw new RegistryNotFoundError(path);
+  }
+  let parsed: unknown;
+  try {
+    parsed = parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new RegistryParseError(path, err);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new RegistryParseError(path, new Error("registry must be a YAML mapping"));
+  }
+  // The "missing 'engagements:'" failure used to be a separate check
+  // ahead of structural validation. Surfacing it explicitly makes the
+  // common-case error message punchier than zod's generic
+  // "Required" — and several tests pin on this wording.
+  if (!("engagements" in parsed)) {
+    throw new RegistryParseError(path, new Error("missing 'engagements:' top-level key"));
+  }
+
+  let validated;
+  try {
+    validated = registryFileSchema.parse(parsed);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new RegistryParseError(path, new Error(formatZodError(err, "registry")));
+    }
+    throw err;
+  }
+
+  // Schema-version gate (per design B14). Zod has accepted any number;
+  // the policy decision (reject newer-than-supported with an upgrade
+  // hint) is encoded here rather than as a refine() so the error
+  // wording is exactly what the user-facing tests assert on.
+  const schemaVersion = validated.schemaVersion ?? 1;
+  if (schemaVersion > MAX_SUPPORTED_REGISTRY_SCHEMA_VERSION) {
+    throw new RegistryParseError(
+      path,
+      new Error(
+        `registry schemaVersion ${schemaVersion} is newer than this build supports ` +
+          `(max ${MAX_SUPPORTED_REGISTRY_SCHEMA_VERSION}); ` +
+          `registry written by a newer repo-aegis — please upgrade`,
+      ),
+    );
+  }
+
+  // Map zod's struct shape back to the domain types. The `passthrough()`
+  // on the schema preserves unknown sibling fields, but those are not
+  // part of the public Registry interface — drop them at the boundary.
+  const engagements: Engagement[] = validated.engagements.map(e => ({
+    id: e.id,
+    name: e.name,
+    ...(e.started !== undefined && { started: e.started }),
+    ...(e.ended !== undefined && { ended: e.ended }),
+    ...(e.reposActive !== undefined && { reposActive: e.reposActive }),
+    markers: e.markers,
+    ...(e.notes !== undefined && { notes: e.notes }),
+    ...(e.githubOrgs !== undefined && { githubOrgs: e.githubOrgs }),
+  }));
+
+  return {
+    engagements,
+    alwaysBlock: validated.always_block ?? [],
+    personalOrgs: validated.personalOrgs ?? [],
+    schemaVersion,
+  };
+}
+
+export function isActive(e: Engagement, retentionMonths = 12): boolean {
+  if (!e.ended) return true;
+  const endedDate = new Date(e.ended);
+  if (Number.isNaN(endedDate.getTime())) return true;
+  const cutoff = new Date();
+  cutoff.setMonth(cutoff.getMonth() - retentionMonths);
+  return endedDate > cutoff;
+}
+
+export interface ResolveResult {
+  match: Engagement | null;
+  candidates: Engagement[];
+}
+
+export function resolveEngagement(reg: Registry, query: string): ResolveResult {
+  const q = query.toLowerCase();
+  const exactId = reg.engagements.find(e => e.id.toLowerCase() === q);
+  if (exactId) return { match: exactId, candidates: [exactId] };
+  const exactName = reg.engagements.find(e => e.name.toLowerCase() === q);
+  if (exactName) return { match: exactName, candidates: [exactName] };
+  const fuzzy = reg.engagements.filter(
+    e => e.id.toLowerCase().includes(q) || e.name.toLowerCase().includes(q),
+  );
+  if (fuzzy.length === 1) return { match: fuzzy[0]!, candidates: fuzzy };
+  return { match: null, candidates: fuzzy };
+}

package/src/remote-url.test.ts

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseRemoteUrl } from "./remote-url.js";
+
+describe("parseRemoteUrl — accepted forms", () => {
+  const cases: Array<[string, string, string]> = [
+    // [input, org, repo]
+    ["https://github.com/foo/bar", "foo", "bar"],
+    ["https://github.com/foo/bar.git", "foo", "bar"],
+    ["https://github.com/foo/bar/", "foo", "bar"],
+    ["http://github.com/foo/bar", "foo", "bar"],
+    ["http://github.com/foo/bar.git", "foo", "bar"],
+    ["git@github.com:foo/bar", "foo", "bar"],
+    ["git@github.com:foo/bar.git", "foo", "bar"],
+    ["git@github.com-personal:foo/bar.git", "foo", "bar"],
+    ["git@github.com-work:foo/bar.git", "foo", "bar"],
+    ["git@github.com-MIXED_alias-1:foo/bar", "foo", "bar"],
+    ["ssh://git@github.com/foo/bar.git", "foo", "bar"],
+    ["ssh://git@github.com/foo/bar", "foo", "bar"],
+    ["https://user@github.com/foo/bar.git", "foo", "bar"],
+    ["https://user:token@github.com/foo/bar.git", "foo", "bar"],
+    // Lowercasing
+    ["https://github.com/Foo-Corp/Bar-Repo.git", "foo-corp", "bar-repo"],
+    ["git@github.com:DELL/UMP.git", "dell", "ump"],
+    // Whitespace trimmed
+    ["  https://github.com/foo/bar.git  \n", "foo", "bar"],
+    // Hyphens, digits, dots in repo names
+    ["https://github.com/foo/bar.baz.git", "foo", "bar.baz"],
+    ["https://github.com/foo/bar_baz", "foo", "bar_baz"],
+    ["https://github.com/foo/bar-123", "foo", "bar-123"],
+  ];
+
+  for (const [input, org, repo] of cases) {
+    it(`parses ${JSON.stringify(input)}`, () => {
+      const parsed = parseRemoteUrl(input);
+      assert.deepEqual(parsed, { host: "github.com", org, repo });
+    });
+  }
+});
+
+describe("parseRemoteUrl — rejected forms (return null)", () => {
+  const cases: string[] = [
+    // Non-string
+    "",
+    "   ",
+    // Non-github hosts
+    "https://gitlab.com/foo/bar.git",
+    "git@gitlab.com:foo/bar.git",
+    "https://bitbucket.org/foo/bar.git",
+    "https://example.com/foo/bar",
+    "git@example.com:foo/bar.git",
+    // Self-hosted github-like host
+    "https://github.example.com/foo/bar.git",
+    "https://my-github.com/foo/bar.git",
+    // Missing repo
+    "https://github.com/foo",
+    "https://github.com/foo/",
+    "git@github.com:foo",
+    // Missing org
+    "https://github.com//bar",
+    "git@github.com:/bar.git",
+    // Org starting with hyphen
+    "https://github.com/-bad/bar",
+    "git@github.com:-bad/bar.git",
+    // Extra path segments
+    "https://github.com/foo/bar/tree/main",
+    "https://github.com/foo/bar/issues/1",
+    // Garbage
+    "not a url",
+    "://github.com/foo/bar",
+    "github.com/foo/bar",
+    // Empty parts
+    "https://github.com/",
+    "git@github.com:",
+  ];
+
+  for (const input of cases) {
+    it(`rejects ${JSON.stringify(input)}`, () => {
+      assert.equal(parseRemoteUrl(input), null);
+    });
+  }
+
+  it("returns null for non-string input (typed)", () => {
+    assert.equal(parseRemoteUrl(undefined), null);
+    assert.equal(parseRemoteUrl(null), null);
+    assert.equal(parseRemoteUrl(42), null);
+    assert.equal(parseRemoteUrl({}), null);
+    assert.equal(parseRemoteUrl([]), null);
+  });
+});
+
+describe("parseRemoteUrl — fuzz", () => {
+  it("never throws on random ASCII input", () => {
+    const seed = 0xc0ffee;
+    let s = seed;
+    function rand(): number {
+      // xorshift32 — deterministic
+      s ^= s << 13;
+      s ^= s >>> 17;
+      s ^= s << 5;
+      return Math.abs(s);
+    }
+    for (let i = 0; i < 1000; i++) {
+      const len = rand() % 64;
+      let str = "";
+      for (let j = 0; j < len; j++) {
+        str += String.fromCharCode(0x20 + (rand() % 95));
+      }
+      // Should never throw, regardless of input.
+      const result = parseRemoteUrl(str);
+      // Sanity: result is null or has the expected shape.
+      if (result !== null) {
+        assert.equal(typeof result.host, "string");
+        assert.equal(typeof result.org, "string");
+        assert.equal(typeof result.repo, "string");
+      }
+    }
+  });
+});

package/src/remote-url.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Pure parser for git remote URLs. Used by `classify` to derive the
+// engagement (or personal-org) attribution from `git remote get-url
+// origin`.
+//
+// The parser is total: malformed input returns `null` rather than
+// throwing. This is load-bearing — `parseRemoteUrl` runs in the JIT
+// classify path, and a thrown exception there would surface to the
+// agent as a tool-failure rather than the intended `skipped` status.
+//
+// Phase 1 scope: github.com only (including multi-account ssh aliases
+// like `git@github.com-personal:`). Non-github hosts return `null`;
+// extending to gitlab/bitbucket is a deliberate follow-up.
+
+export interface ParsedRemote {
+  /** Always `"github.com"` in v1; ssh-alias suffixes are stripped. */
+  host: string;
+  /** Lowercased GitHub org name. */
+  org: string;
+  /** Lowercased GitHub repo name (no `.git` suffix). */
+  repo: string;
+}
+
+// SSH form: `git@github.com[-<alias>]:<org>/<repo>[.git][/]`
+// The optional `-<alias>` segment is the multi-account ssh pattern
+// recommended by GitHub for users with multiple accounts on one
+// machine — e.g. `git@github.com-personal:foo/bar.git`. The alias
+// is stripped and the host normalised back to `github.com`.
+const SSH_RE =
+  /^git@github\.com(?:-[a-zA-Z0-9_-]+)?:([a-zA-Z0-9][a-zA-Z0-9-]*)\/([a-zA-Z0-9._-]+?)(?:\.git)?\/?$/;
+
+// URL forms: `(http|https|ssh)://[user[:pw]@]github.com/<org>/<repo>[.git][/]`
+// Credential prefix (`user@` or `user:pw@`) is stripped. We do not
+// validate password content; the gate path never sees this URL.
+const URL_RE =
+  /^(?:https?|ssh):\/\/(?:[^@/]+@)?github\.com\/([a-zA-Z0-9][a-zA-Z0-9-]*)\/([a-zA-Z0-9._-]+?)(?:\.git)?\/?$/;
+
+/**
+ * Parse a git remote URL into `{ host, org, repo }`. Returns `null`
+ * for malformed input or non-github hosts. Never throws.
+ *
+ * Org and repo are lowercased in the output. The original casing is
+ * not preserved — callers that need the casing-as-typed must read
+ * the raw remote themselves.
+ */
+export function parseRemoteUrl(raw: unknown): ParsedRemote | null {
+  if (typeof raw !== "string") return null;
+  const url = raw.trim();
+  if (url.length === 0) return null;
+
+  const sshMatch = SSH_RE.exec(url);
+  if (sshMatch) {
+    const org = sshMatch[1];
+    const repo = sshMatch[2];
+    if (org === undefined || repo === undefined) return null;
+    return {
+      host: "github.com",
+      org: org.toLowerCase(),
+      repo: repo.toLowerCase(),
+    };
+  }
+
+  const urlMatch = URL_RE.exec(url);
+  if (urlMatch) {
+    const org = urlMatch[1];
+    const repo = urlMatch[2];
+    if (org === undefined || repo === undefined) return null;
+    return {
+      host: "github.com",
+      org: org.toLowerCase(),
+      repo: repo.toLowerCase(),
+    };
+  }
+
+  return null;
+}

package/src/render.test.ts

@@ -0,0 +1,206 @@
+// 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 { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderMarkers, MARKER_FORMAT_VERSION } from "./render.js";
+import { computeDenySet } from "./deny-set.js";
+import { PatternValidationError } from "./exceptions.js";
+
+let tmp: string;
+
+before(() => {
+  tmp = mkdtempSync(join(tmpdir(), "repo-aegis-render-"));
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("renderMarkers", () => {
+  it("writes _always.txt and per-engagement files", () => {
+    const dir = join(tmp, "case-1");
+    mkdirSync(dir, { recursive: true });
+    const r = renderMarkers(
+      {
+        engagements: [
+          { id: "customer-a", name: "A", markers: ["acme-corp"] },
+          { id: "customer-b", name: "B", markers: ["betaco"] },
+        ],
+        alwaysBlock: ["PROJECT-CODENAME-ALPHA"],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, flatPath: join(dir, "..", "case-1.flat") },
+    );
+    assert.equal(r.invalidPatterns.length, 0);
+    assert.equal(r.written.length, 3); // _always + 2 engagements
+    assert.ok(existsSync(join(dir, "_always.txt")));
+    assert.ok(existsSync(join(dir, "customer-a.txt")));
+    assert.ok(existsSync(join(dir, "customer-b.txt")));
+    const aBody = readFileSync(join(dir, "customer-a.txt"), "utf8");
+    assert.match(aBody, /acme-corp/);
+    assert.match(aBody, /; engagement: customer-a/);
+  });
+
+  it("dry-run writes nothing", () => {
+    const dir = join(tmp, "case-dry");
+    const r = renderMarkers(
+      {
+        engagements: [{ id: "customer-a", name: "A", markers: ["acme"] }],
+        alwaysBlock: [],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, dryRun: true, flatPath: join(dir, ".flat") },
+    );
+    assert.ok(!existsSync(dir));
+    assert.equal(r.written.length, 2); // _always + 1 engagement listed but not written
+  });
+
+  it("rejects bad patterns by throwing PatternValidationError", () => {
+    const dir = join(tmp, "case-bad");
+    mkdirSync(dir, { recursive: true });
+    assert.throws(
+      () =>
+        renderMarkers(
+          {
+            engagements: [{ id: "customer-a", name: "A", markers: ["(unclosed"] }],
+            alwaysBlock: [],
+            schemaVersion: 1,
+          },
+          { markersDir: dir, flatPath: join(dir, ".flat") },
+        ),
+      PatternValidationError,
+    );
+    // verify no files were written
+    assert.ok(!existsSync(join(dir, "customer-a.txt")));
+  });
+
+  it("removes stale per-engagement files no longer in registry", () => {
+    const dir = join(tmp, "case-stale");
+    mkdirSync(dir, { recursive: true });
+    // Pre-existing stale file
+    writeFileSync(join(dir, "old-engagement.txt"), "old-marker");
+    const r = renderMarkers(
+      {
+        engagements: [{ id: "customer-a", name: "A", markers: ["acme"] }],
+        alwaysBlock: [],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, flatPath: join(dir, ".flat") },
+    );
+    assert.ok(r.removed.some(p => p.endsWith("old-engagement.txt")));
+    assert.ok(!existsSync(join(dir, "old-engagement.txt")));
+  });
+
+  it("excludes engagements past the retention window", () => {
+    const dir = join(tmp, "case-retention");
+    mkdirSync(dir, { recursive: true });
+    const r = renderMarkers(
+      {
+        engagements: [
+          { id: "active", name: "Active", markers: ["foo"] },
+          { id: "past-retention", name: "Past", ended: "2020-01-01", markers: ["bar"] },
+        ],
+        alwaysBlock: [],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, retentionMonths: 12, flatPath: join(dir, ".flat") },
+    );
+    assert.ok(r.written.some(w => w.engagementId === "active"));
+    assert.ok(!r.written.some(w => w.engagementId === "past-retention"));
+  });
+
+  it("writes the flat union file", () => {
+    const dir = join(tmp, "case-flat");
+    mkdirSync(dir, { recursive: true });
+    const flat = join(tmp, "flat.txt");
+    renderMarkers(
+      {
+        engagements: [{ id: "a", name: "A", markers: ["acme"] }],
+        alwaysBlock: ["PROJECT-X"],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, flatPath: flat },
+    );
+    assert.ok(existsSync(flat));
+    const body = readFileSync(flat, "utf8");
+    assert.match(body, /acme/);
+    assert.match(body, /PROJECT-X/);
+  });
+
+  it("writes the repo-aegis-marker-format header line as a comment", () => {
+    const dir = join(tmp, "case-format-header");
+    mkdirSync(dir, { recursive: true });
+    renderMarkers(
+      {
+        engagements: [{ id: "customer-a", name: "A", markers: ["foo-marker"] }],
+        alwaysBlock: ["GLOBAL-MARKER"],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, flatPath: join(tmp, "case-format-header.flat") },
+    );
+
+    const expected = `; repo-aegis-marker-format: ${MARKER_FORMAT_VERSION}`;
+
+    // Per-engagement file: header line is present and is a `;`-comment.
+    const engBody = readFileSync(join(dir, "customer-a.txt"), "utf8");
+    assert.ok(
+      engBody.includes(expected),
+      `expected per-engagement file to contain "${expected}"; got:\n${engBody}`,
+    );
+    // _always file too.
+    const alwaysBody = readFileSync(join(dir, "_always.txt"), "utf8");
+    assert.ok(
+      alwaysBody.includes(expected),
+      `expected _always file to contain "${expected}"; got:\n${alwaysBody}`,
+    );
+    // Flat union too.
+    const flatBody = readFileSync(join(tmp, "case-format-header.flat"), "utf8");
+    assert.ok(
+      flatBody.includes(expected),
+      `expected flat union to contain "${expected}"; got:\n${flatBody}`,
+    );
+
+    // The header must be the SECOND line of the per-engagement file (after
+    // the "generated by" comment) so it's discoverable at the top.
+    const lines = engBody.split("\n");
+    assert.equal(lines[1], expected);
+  });
+
+  it("marker-format header is ignored by the deny-set parser (round-trip)", () => {
+    // Sanity check: the new header must not pollute the pattern set,
+    // because deny-set treats any line starting with `;` as a comment.
+    const dir = join(tmp, "case-format-roundtrip");
+    mkdirSync(dir, { recursive: true });
+    renderMarkers(
+      {
+        engagements: [{ id: "customer-a", name: "A", markers: ["foo-marker"] }],
+        alwaysBlock: [],
+        schemaVersion: 1,
+      },
+      { markersDir: dir, flatPath: join(tmp, "case-format-roundtrip.flat") },
+    );
+    const ds = computeDenySet(
+      {
+        cwd: dir,
+        isGitRepo: false,
+        class: "public-eligible",
+        classExplicit: true,
+        engagements: [],
+      },
+      { markersDir: dir },
+    );
+    assert.deepEqual(ds.patterns, ["foo-marker"]);
+    // No pattern in the deny set should be a comment line.
+    for (const p of ds.patterns) {
+      assert.ok(!p.startsWith(";"), `pattern leaked from header: ${p}`);
+      assert.ok(!p.includes("repo-aegis-marker-format"), `format header leaked into patterns: ${p}`);
+    }
+  });
+
+  it("exports MARKER_FORMAT_VERSION = 1", () => {
+    assert.equal(MARKER_FORMAT_VERSION, 1);
+  });
+});