@intentius/chant 0.124.13 → 0.124.15

package/src/workspace/ci-green-workflow.test.ts

@@ -124,15 +124,15 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
   });
 
-  test("--token-secret checks out with the secret, so the push uses it, and nothing else changes", () => {
+  test("--token-secret checks out with the secret, or the Actions token where it is unset (#3624), and nothing else changes", () => {
     const plain = renderCiGreenWorkflow(base);
     const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
     const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN }}" } });
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
     // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
     expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
-    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN }}\n", "")).toBe(plain);
+    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN || github.token }}\n", "")).toBe(plain);
   });
 
   test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
@@ -228,7 +228,7 @@ describe("chant ci workflow (#3573)", () => {
       const withToken = readFileSync(file, "utf-8");
       expect(withToken.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN (in the workspace root)`);
       const steps = (parseYAMLDocument(withToken) as Yaml).jobs.tick.steps;
-      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN }}");
+      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN || github.token }}");
       expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
 
       const app = { args: { ciAppIdVar: "CI_GREEN_APP_ID", ciAppKeySecret: "CI_GREEN_APP_KEY" } } as unknown as CommandContext;

package/src/workspace/ci-green-workflow.ts

@@ -27,7 +27,9 @@
  * commit whose workflow files differ from the default branch's as an update
  * to those workflows, and the Actions token can never hold the `workflows`
  * permission, so it is refused there. `--token-secret <NAME>` checks out
- * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * with `secrets.<NAME>` instead, falling back to the Actions token where the
+ * secret is unset (#3624), so a fork or a fresh clone still tags the commits
+ * that change no workflow file; and `--app-id-var <VAR> --app-key-secret
  * <NAME>` mints a GitHub App token first and checks out with that. The
  * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
  * a fine-grained personal access token can't call the Checks API.
@@ -44,6 +46,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import { parseYAMLDocument } from "../yaml";
 import type { CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
+import { githubSecretOrJobToken } from "../ci-jobs";
 
 /** Where the workflow goes, relative to the repository root. */
 export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
@@ -185,7 +188,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
           `          private-key: \${{ secrets.${push.appKeySecret} }}`,
         ]
       : [];
-  const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
+  const token = !push ? [] : ["secret" in push ? `          token: ${githubSecretOrJobToken(push.secret)}` : "          token: ${{ steps.app-token.outputs.token }}"];
   const lines = [
     `name: ${CI_GREEN_WORKFLOW_NAME}`,
     "",

package/src/workspace/class-data.test.ts

@@ -0,0 +1,64 @@
+/**
+ * #3888: the principals file read by hand, for the gate-decision bundle,
+ * accepts and refuses what chant's ajv-checked `parseClassData` does.
+ */
+
+import { describe, expect, test } from "vitest";
+import { classDataShapeProblems, parseClassDataByHand } from "./class-data";
+import { parseClassData } from "./principal-classes";
+
+const ok = { name: "operator", description: "people who apply infrastructure", role: "ops" };
+
+const FILES: unknown[] = [
+  { schema: 1, classes: [ok] },
+  { $schema: "x", $comment: "y", "x-note": 3, schema: 1, classes: [{ ...ok, "x-extra": true }] },
+  { schema: 1, classes: [ok, { name: "reviewer", description: "r", role: "reviewer" }] },
+  { schema: 1, classes: [ok, { ...ok, role: "other" }] },
+  { schema: 1, classes: [{ ...ok, name: "agent" }] },
+  { schema: 1, classes: [{ ...ok, role: "runner" }] },
+  { schema: 1, classes: [ok, { ...ok, name: "other" }] },
+  { schema: 2, classes: [ok] },
+  { schema: "1", classes: [ok] },
+  { classes: [ok] },
+  { schema: 1 },
+  { schema: 1, classes: [] },
+  { schema: 1, classes: {} },
+  { schema: 1, classes: [ok], extra: 1 },
+  { $schema: 3, schema: 1, classes: [ok] },
+  { $comment: null, schema: 1, classes: [ok] },
+  { schema: 1, classes: [{ ...ok, other: 1 }] },
+  { schema: 1, classes: [{ name: ok.name, role: ok.role }] },
+  { schema: 1, classes: [{ name: ok.name, description: ok.description }] },
+  { schema: 1, classes: [{ description: ok.description, role: ok.role }] },
+  { schema: 1, classes: [{ ...ok, name: "Operator" }] },
+  { schema: 1, classes: [{ ...ok, name: "x-operator" }] },
+  { schema: 1, classes: [{ ...ok, name: "a".repeat(40) }] },
+  { schema: 1, classes: [{ ...ok, name: "a".repeat(41) }] },
+  { schema: 1, classes: [{ ...ok, name: "1op" }] },
+  { schema: 1, classes: [{ ...ok, name: 7 }] },
+  { schema: 1, classes: [{ ...ok, description: "" }] },
+  { schema: 1, classes: [{ ...ok, description: 1 }] },
+  { schema: 1, classes: [{ ...ok, role: "Ops" }] },
+  { schema: 1, classes: [{ ...ok, role: "ops role" }] },
+  { schema: 1, classes: [{ ...ok, role: "op-s2" }] },
+  { schema: 1, classes: [null] },
+  { schema: 1, classes: ["operator"] },
+  [],
+  null,
+  "text",
+];
+
+describe("the principals file read without ajv", () => {
+  test.each(FILES.map((f) => [JSON.stringify(f), f]))("%s reads to the classes ajv's check gives", (_, file) => {
+    const text = JSON.stringify(file);
+    const byAjv = parseClassData(text, "@acme/p");
+    const byHand = parseClassDataByHand(text, "@acme/p");
+    expect(byHand.classes).toEqual(byAjv.classes);
+    expect(byHand.problems.length > 0).toBe(byAjv.problems.length > 0);
+    expect(classDataShapeProblems(file, "@acme/p").length === 0).toBe(byAjv.classes.length > 0 || byAjv.problems.every((p) => /core|twice|another class/.test(p)));
+  });
+
+  test("text that is not JSON", () => {
+    expect(parseClassDataByHand("{", "@acme/p")).toEqual(parseClassData("{", "@acme/p"));
+  });
+});

package/src/workspace/class-data.ts

@@ -0,0 +1,236 @@
+/**
+ * Reading the principal classes a pinned package supplies, without ajv or
+ * any package code (#3888).
+ *
+ * `./principal-classes.ts` reads a package's `./workspace-principals` file
+ * for chant, validating it with ajv against
+ * `workspace-principals.schema.json`. `@intentius/chant/gate-decision` reads
+ * the same files from a bare clone and must bundle without ajv, so the rules
+ * both share live here: where a package's export points, where an installed
+ * package is, what a file must hold beyond its schema, and how classes from
+ * several pins merge. {@link classDataShapeProblems} is the schema written
+ * out by hand for the bundle; `class-data.test.ts` holds it to ajv's answer.
+ *
+ * The module imports node:fs and node:path and nothing else.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, type PrincipalClass } from "./identity-gate-rule";
+
+/** The subpath a package publishes its principal classes at. */
+export const PRINCIPALS_SUBPATH = "./workspace-principals";
+
+export interface ClassData {
+  classes: PrincipalClass[];
+  /** Why some of the data can't be used, one line each. Empty when all of it can. */
+  problems: string[];
+}
+
+/** A package's files, by a `/`-separated path inside it, or undefined when one is not there. */
+export type PackageFiles = (path: string) => string | undefined;
+
+/** A package directory on disk. */
+export function diskFiles(dir: string): PackageFiles {
+  return (path) => {
+    try {
+      return readFileSync(join(dir, ...path.split("/")), "utf-8");
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/**
+ * The directory of an installed package `name`, found the way Node finds a
+ * bare import: `node_modules/<name>` in `fromDir` and each directory above it.
+ * It looks for the directory, not for an entry point, so it works for a
+ * package whose `exports` don't expose `package.json`.
+ */
+export function findInstalledPackage(name: string, fromDir: string): string | undefined {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", ...name.split("/"));
+    try {
+      if (statSync(candidate).isDirectory() && existsSync(join(candidate, "package.json"))) return candidate;
+    } catch {
+      // Not here; keep walking.
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * The file a package's `exports[subpath]` names: undefined when it names
+ * none, a problem when it is not one `.json` file inside the package.
+ */
+export function dataExportTarget(pkg: Record<string, unknown>, subpath: string): string | undefined | { problem: string } {
+  const exports = pkg.exports;
+  if (!exports || typeof exports !== "object" || Array.isArray(exports)) return undefined;
+  const entry = (exports as Record<string, unknown>)[subpath];
+  if (entry === undefined) return undefined;
+  let target: unknown = entry;
+  if (target && typeof target === "object" && !Array.isArray(target)) {
+    const conditions = target as Record<string, unknown>;
+    target = conditions.default ?? conditions.import ?? conditions.require;
+  }
+  if (typeof target !== "string") {
+    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
+  }
+  if (!target.startsWith("./") || !target.endsWith(".json")) {
+    return { problem: `exports["${subpath}"] is ${target}; it must name a .json file inside the package, since chant reads plugin data as data and never runs a package's code` };
+  }
+  return target;
+}
+
+// ── The file ─────────────────────────────────────────────────────────────────
+
+const NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/u;
+const ROLE = /^[a-z][a-z0-9-]*$/u;
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const extra = (key: string, known: readonly string[]) => !known.includes(key) && !key.startsWith("x-");
+
+/**
+ * What `workspace-principals.schema.json` refuses in `raw`, one line each,
+ * written out by hand so the gate-decision bundle needs no ajv. Empty when
+ * the schema accepts it.
+ */
+export function classDataShapeProblems(raw: unknown, source: string): string[] {
+  const p: string[] = [];
+  const say = (where: string, what: string) => p.push(`${source}: ${where || "the principals file"} ${what}`);
+  if (!isObject(raw)) {
+    say("", "must be object");
+    return p;
+  }
+  for (const key of Object.keys(raw)) if (extra(key, ["$schema", "$comment", "schema", "classes"])) say("", `must NOT have additional property ${key}`);
+  for (const key of ["$schema", "$comment"]) if (key in raw && typeof raw[key] !== "string") say(`/${key}`, "must be string");
+  if (!("schema" in raw)) say("", "must have required property 'schema'");
+  else if (raw.schema !== 1) say("/schema", "must be equal to constant 1");
+  if (!("classes" in raw)) say("", "must have required property 'classes'");
+  else if (!Array.isArray(raw.classes)) say("/classes", "must be array");
+  else {
+    if (raw.classes.length < 1) say("/classes", "must NOT have fewer than 1 items");
+    raw.classes.forEach((c: unknown, i: number) => {
+      const at = `/classes/${i}`;
+      if (!isObject(c)) return say(at, "must be object");
+      for (const key of Object.keys(c)) if (extra(key, ["name", "description", "role"])) say(at, `must NOT have additional property ${key}`);
+      for (const key of ["name", "description", "role"]) if (!(key in c)) say(at, `must have required property '${key}'`);
+      if ("name" in c && (typeof c.name !== "string" || !NAME.test(c.name))) say(`${at}/name`, "must be a class name");
+      if ("description" in c && (typeof c.description !== "string" || [...c.description].length < 1)) say(`${at}/description`, "must be a non-empty string");
+      if ("role" in c && (typeof c.role !== "string" || !ROLE.test(c.role))) say(`${at}/role`, "must be a role name");
+    });
+  }
+  return [...new Set(p)];
+}
+
+const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
+
+/**
+ * The classes in a principals file the schema accepts, under the rules the
+ * schema can't say: no core name or core role, and no name or role twice.
+ * `source` names the pin in the classes and in the messages.
+ */
+export function checkClassData(valid: { classes: { name: string; description: string; role: string }[] }, source: string): ClassData {
+  const problems: string[] = [];
+  const classes: PrincipalClass[] = [];
+  const names = new Set<string>();
+  const roles = new Set<string>();
+  for (const c of valid.classes) {
+    if ((CORE_PRINCIPAL_CLASSES as readonly string[]).includes(c.name)) {
+      problems.push(`${source}: class ${c.name} is a core class and can't be supplied by a package`);
+      continue;
+    }
+    if (CORE_ROLES.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which puts a principal in the core ${c.role} class`);
+      continue;
+    }
+    if (names.has(c.name)) {
+      problems.push(`${source}: class ${c.name} is listed twice`);
+      continue;
+    }
+    if (roles.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which another class in the file names; a role puts a principal in one class`);
+      continue;
+    }
+    names.add(c.name);
+    roles.add(c.role);
+    classes.push({ name: c.name, description: c.description, role: c.role, source });
+  }
+  return { classes, problems };
+}
+
+/** A principals file's text read with {@link classDataShapeProblems} for the schema: what chant's ajv-checked `parseClassData` reads, by the same rules. */
+export function parseClassDataByHand(text: string, source: string): ClassData {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { classes: [], problems: [`${source}: the principals file is not JSON (${(err as Error).message})`] };
+  }
+  const problems = classDataShapeProblems(raw, source);
+  return problems.length > 0 ? { classes: [], problems } : checkClassData(raw as Parameters<typeof checkClassData>[0], source);
+}
+
+/** Read the classes a package publishes at `./workspace-principals` through `files`, checking the file with `parse`. Imports nothing. A package that publishes none supplies none. */
+export function readClassFiles(files: PackageFiles, source: string, parse: (text: string, source: string) => ClassData): ClassData {
+  const manifest = files("package.json");
+  if (manifest === undefined) return { classes: [], problems: [`${source}: no readable package.json`] };
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(manifest) as Record<string, unknown>;
+  } catch {
+    return { classes: [], problems: [`${source}: package.json is not JSON`] };
+  }
+  const target = dataExportTarget(pkg, PRINCIPALS_SUBPATH);
+  if (target === undefined) return { classes: [], problems: [] };
+  if (typeof target !== "string") return { classes: [], problems: [`${source}: ${target.problem}`] };
+  const inside = posix.normalize(target.slice(2));
+  if (inside.startsWith("../") || inside === "..") return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] points outside the package`] };
+  const text = files(inside);
+  if (text === undefined) return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] names ${target}, which does not exist`] };
+  return parse(text, source);
+}
+
+/** One pin's classes, as read. */
+export interface PinClassRead {
+  /** The pin's index in the declaration's `pins`. */
+  pin: number;
+  source: string;
+  read: ClassData;
+}
+
+/**
+ * The domain classes of every pin, in pin order and file order. A class
+ * name, or a role, two pins both supply is a problem, and every class
+ * involved is left out, so a rule naming it reads it as unknown and fails
+ * closed.
+ */
+export function mergePinClasses(reads: readonly PinClassRead[]): { classes: PrincipalClass[]; problems: { pin: number; message: string }[] } {
+  const problems: { pin: number; message: string }[] = [];
+  const extra: PrincipalClass[] = [];
+  const byName = new Map<string, string>();
+  const byRole = new Map<string, string>();
+  const clashing = new Set<string>();
+  for (const { pin: i, source, read } of reads) {
+    for (const p of read.problems) problems.push({ pin: i, message: p });
+    for (const c of read.classes) {
+      const named = byName.get(c.name);
+      const roled = byRole.get(c.role!);
+      if (named !== undefined || roled !== undefined) {
+        clashing.add(c.name);
+        if (named !== undefined) {
+          problems.push({ pin: i, message: `class ${c.name} is supplied by both ${named} and ${source}; a class name has one source` });
+        } else {
+          const other = extra.find((e) => e.role === c.role)!;
+          clashing.add(other.name);
+          problems.push({ pin: i, message: `class ${c.name} (${source}) names the role ${c.role}, which class ${other.name} (${roled}) names; a role puts a principal in one class` });
+        }
+        continue;
+      }
+      byName.set(c.name, source);
+      byRole.set(c.role!, source);
+      extra.push(c);
+    }
+  }
+  // A name or role two pins both supply is left out altogether: neither reading is safe.
+  return { classes: extra.filter((c) => !clashing.has(c.name)), problems };
+}

package/src/workspace/declaration.ts

@@ -19,7 +19,7 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import schema from "./declaration.schema.json";
+import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";

package/src/workspace/kinds.ts

@@ -17,13 +17,14 @@
  * fails ({@link resolveKind}).
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import schema from "./workspace-kinds.schema.json";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
+import { dataExportTarget, findInstalledPackage } from "./class-data";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -428,22 +429,7 @@ export interface PackageKinds extends KindData {
  * subpath to code, which chant never runs for plugin data.
  */
 export function kindsExportTarget(pkg: Record<string, unknown>, subpath: string = KINDS_SUBPATH): string | undefined | { problem: string } {
-  const exports = pkg.exports;
-  if (!exports || typeof exports !== "object" || Array.isArray(exports)) return undefined;
-  const entry = (exports as Record<string, unknown>)[subpath];
-  if (entry === undefined) return undefined;
-  let target: unknown = entry;
-  if (target && typeof target === "object" && !Array.isArray(target)) {
-    const conditions = target as Record<string, unknown>;
-    target = conditions.default ?? conditions.import ?? conditions.require;
-  }
-  if (typeof target !== "string") {
-    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
-  }
-  if (!target.startsWith("./") || !target.endsWith(".json")) {
-    return { problem: `exports["${subpath}"] is ${target}; it must name a .json file inside the package, since chant reads plugin data as data and never runs a package's code` };
-  }
-  return target;
+  return dataExportTarget(pkg, subpath);
 }
 
 /** Read the kinds a package directory publishes. Reads files only; imports nothing. */
@@ -515,23 +501,8 @@ export function substituteGraphConfig(config: Record<string, unknown>, at: Graph
   return walk(config) as Record<string, unknown>;
 }
 
-/**
- * The directory of an installed package `name`, found the way Node finds a
- * bare import: `node_modules/<name>` in `fromDir` and each directory above it.
- * It looks for the directory, not for an entry point, so it works for a
- * package whose `exports` don't expose `package.json`.
- */
-export function findInstalledPackage(name: string, fromDir: string): string | undefined {
-  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
-    const candidate = join(dir, "node_modules", ...name.split("/"));
-    try {
-      if (statSync(candidate).isDirectory() && existsSync(join(candidate, "package.json"))) return candidate;
-    } catch {
-      // Not here; keep walking.
-    }
-    if (dirname(dir) === dir) return undefined;
-  }
-}
+/** Where an installed package is, as Node finds a bare import (`./class-data.ts`, so the gate-decision bundle shares it). */
+export { findInstalledPackage };
 
 export interface PinLike {
   package: string | null;

package/src/workspace/lineage-migrations.ts

@@ -25,6 +25,7 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { LockError, type Lineage } from "./lineage-lock";
 import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /** Where a template keeps its migrations, relative to the template's directory. */
 export const MIGRATIONS_DIR = ".chant/migrations";
@@ -281,6 +282,7 @@ export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions
       mkdirSync(dirname(abs), { recursive: true });
       writeFileSync(abs, data);
     }
+    ensureTypeScriptLoader();
     const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
     if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
     await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });

package/src/workspace/points.ts

@@ -35,7 +35,7 @@
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { dirname, posix, relative, resolve, sep } from "node:path";
-import schema from "./decision-points.schema.json";
+import schema from "./decision-points.schema.json" with { type: "json" };
 import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 import type { LoadedRecordKind, ReadRecordsOptions, RecordEntry } from "./records";

package/src/workspace/principal-classes.ts

@@ -22,19 +22,17 @@
  * installed package, which must be at the version the base pins.
  */
 
-import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { join, posix } from "node:path";
-import { kindsExportTarget, pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
-import schema from "./workspace-principals.schema.json";
+import { checkClassData, diskFiles, mergePinClasses, readClassFiles, type ClassData, type PackageFiles, type PinClassRead } from "./class-data";
+import { pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
+import schema from "./workspace-principals.schema.json" with { type: "json" };
 import type { TrustPolicy } from "./trust/policy";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses, type PrincipalClass } from "./identity-gate-rule";
 
 export const PRINCIPALS_SCHEMA_ID = schema.$id;
 
-/** The subpath a package publishes its principal classes at. */
-export const PRINCIPALS_SUBPATH = "./workspace-principals";
+export { PRINCIPALS_SUBPATH } from "./class-data";
 
 export { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, type CorePrincipalClass, type PrincipalClass } from "./identity-gate-rule";
 
@@ -44,8 +42,6 @@ export type PrincipalClassName = string;
 /** The grammar of a class name, as `workspace-principals.schema.json` and the declaration's writeScope keys say it. */
 export const CLASS_NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/;
 
-const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
-
 export interface ClassRegistry {
   get(name: string): PrincipalClass | undefined;
   /** Every class name, core first, for "unknown class" messages. */
@@ -111,11 +107,8 @@ function validator(): Validate {
   return compiled;
 }
 
-export interface ClassData {
-  classes: PrincipalClass[];
-  /** Why some of the data can't be used, one line each. Empty when all of it can. */
-  problems: string[];
-}
+export type { ClassData, PackageFiles } from "./class-data";
+export { diskFiles } from "./class-data";
 
 /**
  * Check the text of a principals file against
@@ -135,46 +128,7 @@ export function parseClassData(text: string, source: string): ClassData {
     const problems = (validate.errors ?? []).map((e) => `${source}: ${e.instancePath || "the principals file"} ${e.message ?? "is invalid"}`);
     return { classes: [], problems: [...new Set(problems)] };
   }
-  const problems: string[] = [];
-  const classes: PrincipalClass[] = [];
-  const names = new Set<string>();
-  const roles = new Set<string>();
-  for (const c of (raw as { classes: { name: string; description: string; role: string }[] }).classes) {
-    if ((CORE_PRINCIPAL_CLASSES as readonly string[]).includes(c.name)) {
-      problems.push(`${source}: class ${c.name} is a core class and can't be supplied by a package`);
-      continue;
-    }
-    if (CORE_ROLES.has(c.role)) {
-      problems.push(`${source}: class ${c.name} names the role ${c.role}, which puts a principal in the core ${c.role} class`);
-      continue;
-    }
-    if (names.has(c.name)) {
-      problems.push(`${source}: class ${c.name} is listed twice`);
-      continue;
-    }
-    if (roles.has(c.role)) {
-      problems.push(`${source}: class ${c.name} names the role ${c.role}, which another class in the file names; a role puts a principal in one class`);
-      continue;
-    }
-    names.add(c.name);
-    roles.add(c.role);
-    classes.push({ name: c.name, description: c.description, role: c.role, source });
-  }
-  return { classes, problems };
-}
-
-/** A package's files, by a `/`-separated path inside it, or undefined when one is not there. */
-export type PackageFiles = (path: string) => string | undefined;
-
-/** A package directory on disk. */
-export function diskFiles(dir: string): PackageFiles {
-  return (path) => {
-    try {
-      return readFileSync(join(dir, ...path.split("/")), "utf-8");
-    } catch {
-      return undefined;
-    }
-  };
+  return checkClassData(raw as Parameters<typeof checkClassData>[0], source);
 }
 
 /** A package directory at `dir` in `tree`, such as the workspace at the base revision. */
@@ -192,22 +146,7 @@ export function treeFiles(tree: WorkspaceTree, dir: string): PackageFiles {
 
 /** Read the classes a package publishes at `./workspace-principals`. Reads files only; imports nothing. A package that publishes none supplies none. */
 export function readPackageClasses(files: PackageFiles, source: string): ClassData {
-  const manifest = files("package.json");
-  if (manifest === undefined) return { classes: [], problems: [`${source}: no readable package.json`] };
-  let pkg: Record<string, unknown>;
-  try {
-    pkg = JSON.parse(manifest) as Record<string, unknown>;
-  } catch {
-    return { classes: [], problems: [`${source}: package.json is not JSON`] };
-  }
-  const target = kindsExportTarget(pkg, PRINCIPALS_SUBPATH);
-  if (target === undefined) return { classes: [], problems: [] };
-  if (typeof target !== "string") return { classes: [], problems: [`${source}: ${target.problem}`] };
-  const inside = posix.normalize(target.slice(2));
-  if (inside.startsWith("../") || inside === "..") return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] points outside the package`] };
-  const text = files(inside);
-  if (text === undefined) return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] names ${target}, which does not exist`] };
-  return parseClassData(text, source);
+  return readClassFiles(files, source, parseClassData);
 }
 
 export interface LoadedClasses {
@@ -227,10 +166,7 @@ export interface LoadedClasses {
  */
 export function loadClassRegistry(pins: readonly PinLike[], workspaceRoot: string, opts: { tree?: WorkspaceTree } = {}): LoadedClasses {
   const problems: KindLoadProblem[] = [];
-  const extra: PrincipalClass[] = [];
-  const byName = new Map<string, string>();
-  const byRole = new Map<string, string>();
-  const clashing = new Set<string>();
+  const reads: PinClassRead[] = [];
   pins.forEach((pin, i) => {
     let files: PackageFiles;
     let source: string;
@@ -247,29 +183,10 @@ export function loadClassRegistry(pins: readonly PinLike[], workspaceRoot: strin
       files = diskFiles(found.dir);
       source = found.source;
     }
-    const read = readPackageClasses(files, source);
-    for (const p of read.problems) problems.push({ pin: i, message: p });
-    for (const c of read.classes) {
-      const named = byName.get(c.name);
-      const roled = byRole.get(c.role!);
-      if (named !== undefined || roled !== undefined) {
-        clashing.add(c.name);
-        if (named !== undefined) {
-          problems.push({ pin: i, message: `class ${c.name} is supplied by both ${named} and ${source}; a class name has one source` });
-        } else {
-          const other = extra.find((e) => e.role === c.role)!;
-          clashing.add(other.name);
-          problems.push({ pin: i, message: `class ${c.name} (${source}) names the role ${c.role}, which class ${other.name} (${roled}) names; a role puts a principal in one class` });
-        }
-        continue;
-      }
-      byName.set(c.name, source);
-      byRole.set(c.role!, source);
-      extra.push(c);
-    }
+    reads.push({ pin: i, source, read: readPackageClasses(files, source) });
   });
-  // A name or role two pins both supply is left out altogether: neither reading is safe.
-  return { registry: createClassRegistry(extra.filter((c) => !clashing.has(c.name))), problems };
+  const merged = mergePinClasses(reads);
+  return { registry: createClassRegistry(merged.classes), problems: [...problems, ...merged.problems].sort((a, b) => a.pin - b.pin) };
 }
 
 /**

package/src/workspace/records-formats.test.ts

@@ -12,7 +12,7 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -472,7 +472,12 @@ describe("the write commands through a declared kind (#2680)", () => {
 
 describe("the decision kind", () => {
   test("still reads as markdown front matter, and says so", async () => {
-    const doc = await queryRecords({ kind: "docs/design/decisions/decision.kind.mjs", cwd: REPO });
+    // The repository's own decision records, copied into a one-commit repository:
+    // a read in the real checkout asks git for the history of every pinned path
+    // across thousands of commits, which took 12 s alone and 20+ s under load.
+    cpSync(join(REPO, "docs", "design", "decisions"), join(root, "docs", "design", "decisions"), { recursive: true });
+    commit();
+    const doc = await queryRecords({ kind: "docs/design/decisions/decision.kind.mjs", cwd: root });
     expect(validateOutput(doc)).toBe(true);
     if ("error" in doc) throw new Error(doc.error.message);
     expect(doc.kind.format).toBe("markdown-front-matter");