@cosmicdrift/kumiko-guards 0.363.0 → 0.364.0

package/README.md

@@ -15,6 +15,34 @@ repo's root. `--explain` prints the resolved repo and per-guard scan scope
 without running any guard; `--write-security-baseline` freezes current
 findings into the baseline file.
 
+## Dependency checks
+
+Three subcommands check the dependencies of the repo `cwd` sits in. They call
+the npm registry or `bun audit`, so they are not part of the default run and
+not part of `checks`; each takes `--report` (print only, exit 0; for `outdated`
+it adds transitive and major-lag sections and a deprecated direct dependency
+still exits 1). `outdated` lists every package the registry did not answer
+as UNKNOWN with the reason and fails when no direct dependency got an answer.
+
+```
+bunx kumiko-guards licenses   # licence allow/gray/deny classification of installed packages
+bunx kumiko-guards security   # bun audit: critical/high block, moderate warns
+bunx kumiko-guards outdated   # installed direct dependencies the registry marks deprecated
+```
+
+Installed packages (`licenses`, `outdated`) are read from `node_modules` of the
+repo root, its workspace members and every ancestor directory, the resolution
+Bun itself uses, so a hoisted parent workspace and `.wt/` worktrees work. If
+nothing is found the command fails ("nothing scanned"). `security` audits the
+repo root's `bun.lock`, or the nearest ancestor's (announced) when the repo has
+none, and fails if there is no lockfile at all.
+
+Exceptions need a reason, a reviewer and an expiry date. The package ships
+defaults (`dependency-license-exceptions.json`,
+`dependency-security-exceptions.json`); a file of the same name in the repo
+root (and, for `licenses`, in an ancestor whose `node_modules` was scanned) is
+merged on top. A security exception that expires within 14 days blocks.
+
 ## Raw-SQL markers
 
 `guard-raw-sql` blocks `.unsafe()` / `asRawClient()` outside `db/queries/*`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.363.0",
+  "version": "0.364.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.363.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.364.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/agent-docs.ts

@@ -0,0 +1,425 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { type ExportedDeclarations, type JSDocableNode, Node, Project, ts } from "ts-morph";
+
+export const AGENT_DOCS_DIR = "packages/framework/agents";
+
+const FEATURE_MANIFEST_REL = "samples/apps/use-all-bundled/feature-manifest.json";
+const RENDERER_WEB_INDEX_REL = "packages/renderer-web/src/index.ts";
+const RECIPES_REL = "samples/recipes";
+const RECIPE_SLUG_RE = /^[a-z0-9-]+$/;
+const SOURCE_EXTENSIONS = [".ts", ".tsx"];
+
+type ManifestConfigKeyDoc = {
+  readonly key: string;
+  readonly type: string;
+  readonly scope: string;
+  readonly default: string | number | boolean | null;
+};
+
+type ManifestSecretDoc = {
+  readonly qualifiedName: string;
+  readonly scope: string;
+  readonly label: string | null;
+};
+
+type ManifestFeatureDoc = {
+  readonly name: string;
+  readonly description: string | null;
+  readonly category: string | null;
+  readonly requires: readonly string[];
+  readonly optionalRequires: readonly string[];
+  readonly exposesApis: readonly string[];
+  readonly usesApis: readonly string[];
+  readonly configKeys: readonly ManifestConfigKeyDoc[];
+  readonly secrets: readonly ManifestSecretDoc[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function isConfigKeyDoc(value: unknown): value is ManifestConfigKeyDoc {
+  if (!isRecord(value)) return false;
+  const fallback = value["default"];
+  return (
+    typeof value["key"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["scope"] === "string" &&
+    (fallback === null ||
+      typeof fallback === "string" ||
+      typeof fallback === "number" ||
+      typeof fallback === "boolean")
+  );
+}
+
+function isSecretDoc(value: unknown): value is ManifestSecretDoc {
+  return (
+    isRecord(value) &&
+    typeof value["qualifiedName"] === "string" &&
+    typeof value["scope"] === "string" &&
+    isNullableString(value["label"])
+  );
+}
+
+function parseFeatureDoc(value: unknown): ManifestFeatureDoc | undefined {
+  if (!isRecord(value) || typeof value["name"] !== "string") return undefined;
+  const description = value["description"];
+  const configKeys = value["configKeys"];
+  const secrets = value["secrets"];
+  const uiHints = value["uiHints"];
+  const category = isRecord(uiHints) ? uiHints["category"] : undefined;
+  if (
+    !isNullableString(description) ||
+    !isStringArray(value["requires"]) ||
+    !isStringArray(value["optionalRequires"]) ||
+    !isStringArray(value["exposesApis"]) ||
+    !isStringArray(value["usesApis"]) ||
+    !Array.isArray(configKeys) ||
+    !configKeys.every(isConfigKeyDoc) ||
+    !Array.isArray(secrets) ||
+    !secrets.every(isSecretDoc)
+  ) {
+    return undefined;
+  }
+  return {
+    name: value["name"],
+    description,
+    category: typeof category === "string" ? category : null,
+    requires: value["requires"],
+    optionalRequires: value["optionalRequires"],
+    exposesApis: value["exposesApis"],
+    usesApis: value["usesApis"],
+    configKeys,
+    secrets,
+  };
+}
+
+function parseJsonFile(relPath: string, raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${relPath}: invalid JSON`, { cause: error });
+  }
+}
+
+function parseFeatureManifest(raw: string): readonly ManifestFeatureDoc[] {
+  const parsed = parseJsonFile(FEATURE_MANIFEST_REL, raw);
+  const features = isRecord(parsed) ? parsed["features"] : undefined;
+  if (!Array.isArray(features)) {
+    throw new Error(`${FEATURE_MANIFEST_REL}: "features" must be an array`);
+  }
+  return features.map((entry, index) => {
+    const feature = parseFeatureDoc(entry);
+    if (feature === undefined) {
+      throw new Error(`${FEATURE_MANIFEST_REL}: features[${index}] has an unexpected shape`);
+    }
+    return feature;
+  });
+}
+
+function compareCodepoint(left: string, right: string): number {
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+}
+
+function generatedHeader(source: string): string {
+  return `<!-- Generated by \`bun run gen:agent-docs\` from ${source}. Do not edit. -->`;
+}
+
+function finishFile(source: string, body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n").trim();
+  return `${generatedHeader(source)}\n\n${normalized}\n`;
+}
+
+function escapeCell(text: string): string {
+  return text.replace(/\s+/g, " ").trim().replace(/\|/g, "\\|");
+}
+
+function table(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  const lines = [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+  ];
+  return lines.join("\n");
+}
+
+function codeList(values: readonly string[]): string {
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+function renderFeatureSection(feature: ManifestFeatureDoc): string {
+  const parts = [`## ${feature.name}`];
+  if (feature.description !== null) parts.push(feature.description.replace(/\s+/g, " ").trim());
+  if (feature.category !== null) parts.push(`Category: ${feature.category}`);
+  if (feature.requires.length > 0) parts.push(`Requires: ${codeList(feature.requires)}`);
+  if (feature.optionalRequires.length > 0) {
+    parts.push(`Optional requires: ${codeList(feature.optionalRequires)}`);
+  }
+  if (feature.configKeys.length > 0) {
+    const rows = feature.configKeys.map((configKey) => [
+      `\`${configKey.key}\``,
+      configKey.type,
+      configKey.scope,
+      configKey.default === null ? "" : `\`${String(configKey.default)}\``,
+    ]);
+    parts.push(`Config keys:\n\n${table(["Key", "Type", "Scope", "Default"], rows)}`);
+  }
+  if (feature.secrets.length > 0) {
+    const rows = feature.secrets.map((secret) => [
+      `\`${secret.qualifiedName}\``,
+      secret.scope,
+      secret.label ?? "",
+    ]);
+    parts.push(`Secrets:\n\n${table(["Secret", "Scope", "Label"], rows)}`);
+  }
+  if (feature.exposesApis.length > 0) parts.push(`Exposes APIs: ${codeList(feature.exposesApis)}`);
+  if (feature.usesApis.length > 0) parts.push(`Uses APIs: ${codeList(feature.usesApis)}`);
+  return parts.join("\n\n");
+}
+
+function renderFeatures(repoRoot: string): string {
+  const raw = readFileSync(join(repoRoot, FEATURE_MANIFEST_REL), "utf-8");
+  const sections = [...parseFeatureManifest(raw)]
+    .sort((left, right) => compareCodepoint(left.name, right.name))
+    .map(renderFeatureSection);
+  return finishFile(FEATURE_MANIFEST_REL, `# Bundled features\n\n${sections.join("\n\n")}`);
+}
+
+type WidgetGroup = "Components" | "Hooks" | "Functions" | "Constants" | "Classes";
+const WIDGET_GROUP_ORDER: readonly WidgetGroup[] = [
+  "Components",
+  "Hooks",
+  "Functions",
+  "Constants",
+  "Classes",
+];
+
+const HOOK_NAME_RE = /^use[A-Z]/;
+const PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
+
+function isFunctionLike(node: Node | undefined): boolean {
+  return node !== undefined && (Node.isArrowFunction(node) || Node.isFunctionExpression(node));
+}
+
+function isPascalCaseComponentName(name: string): boolean {
+  return PASCAL_CASE_RE.test(name) && /[a-z]/.test(name);
+}
+
+function widgetGroupOf(name: string, declaration: ExportedDeclarations): WidgetGroup | undefined {
+  if (Node.isClassDeclaration(declaration)) return "Classes";
+  if (Node.isEnumDeclaration(declaration)) return "Constants";
+  const isFunction = Node.isFunctionDeclaration(declaration);
+  const isVariable = Node.isVariableDeclaration(declaration);
+  if (!isFunction && !isVariable) return undefined;
+  if (HOOK_NAME_RE.test(name)) return "Hooks";
+  if (isPascalCaseComponentName(name)) return "Components";
+  if (isFunction || isFunctionLike(declaration.getInitializer())) return "Functions";
+  return "Constants";
+}
+
+function jsDocOwnerOf(declaration: ExportedDeclarations): JSDocableNode | undefined {
+  if (Node.isVariableDeclaration(declaration)) return declaration.getVariableStatement();
+  return Node.isJSDocable(declaration) ? declaration : undefined;
+}
+
+const FIRST_SENTENCE_RE = /^(.+?(?<!\be\.g|\bi\.e)[.!?])(?:\s|$)/;
+
+function firstSentence(text: string): string {
+  const flattened = text.replace(/\s+/g, " ").trim();
+  return FIRST_SENTENCE_RE.exec(flattened)?.[1] ?? flattened;
+}
+
+function descriptionOf(declarations: readonly ExportedDeclarations[]): string {
+  for (const declaration of declarations) {
+    const docs = jsDocOwnerOf(declaration)?.getJsDocs() ?? [];
+    const description = docs.at(-1)?.getDescription() ?? "";
+    if (description.trim() !== "") return firstSentence(description);
+  }
+  return "";
+}
+
+function renderWidgets(repoRoot: string): string {
+  const project = new Project({
+    compilerOptions: {
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      target: ts.ScriptTarget.ES2022,
+      jsx: ts.JsxEmit.ReactJSX,
+    },
+  });
+  const indexFile = project.addSourceFileAtPath(join(repoRoot, RENDERER_WEB_INDEX_REL));
+  const grouped = new Map<WidgetGroup, [string, string][]>(
+    WIDGET_GROUP_ORDER.map((group) => [group, []]),
+  );
+  for (const [name, declarations] of indexFile.getExportedDeclarations()) {
+    const group = declarations
+      .map((declaration) => widgetGroupOf(name, declaration))
+      .find((candidate) => candidate !== undefined);
+    if (group === undefined) continue;
+    grouped.get(group)?.push([name, descriptionOf(declarations)]);
+  }
+  const sections: string[] = [];
+  for (const group of WIDGET_GROUP_ORDER) {
+    const entries = (grouped.get(group) ?? []).sort(([left], [right]) =>
+      compareCodepoint(left, right),
+    );
+    if (entries.length === 0) continue;
+    const rows = entries.map(([name, description]) => [`\`${name}\``, description]);
+    sections.push(`## ${group}\n\n${table(["Name", "Description"], rows)}`);
+  }
+  const intro = "Value exports of `@cosmicdrift/kumiko-renderer-web`.";
+  return finishFile(RENDERER_WEB_INDEX_REL, `# Widgets\n\n${intro}\n\n${sections.join("\n\n")}`);
+}
+
+type Recipe = {
+  readonly slug: string;
+  readonly dir: string;
+  readonly description: string;
+};
+
+function readRecipes(repoRoot: string): readonly Recipe[] {
+  const recipesDir = join(repoRoot, RECIPES_REL);
+  if (!existsSync(recipesDir)) return [];
+  const recipes: Recipe[] = [];
+  for (const entry of readdirSync(recipesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(recipesDir, entry.name);
+    const packageJsonPath = join(dir, "package.json");
+    if (!existsSync(packageJsonPath)) continue;
+    if (!RECIPE_SLUG_RE.test(entry.name)) {
+      throw new Error(
+        `${RECIPES_REL}/${entry.name}: recipe directory must match ${RECIPE_SLUG_RE}`,
+      );
+    }
+    const parsed = parseJsonFile(
+      `${RECIPES_REL}/${entry.name}/package.json`,
+      readFileSync(packageJsonPath, "utf-8"),
+    );
+    const description = isRecord(parsed) ? parsed["description"] : undefined;
+    recipes.push({
+      slug: entry.name,
+      dir,
+      description: typeof description === "string" ? description : "",
+    });
+  }
+  return recipes.sort((left, right) => compareCodepoint(left.slug, right.slug));
+}
+
+function renderExamplesIndex(recipes: readonly Recipe[]): string {
+  const rows = recipes.map((recipe) => [
+    `\`${recipe.slug}\``,
+    recipe.description,
+    `\`examples/${recipe.slug}.md\``,
+  ]);
+  return finishFile(
+    `${RECIPES_REL}/*/package.json`,
+    `# Examples\n\n${table(["Example", "Description", "File"], rows)}`,
+  );
+}
+
+function listSourceFiles(dir: string, prefix = ""): string[] {
+  if (!existsSync(dir)) return [];
+  const found: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      found.push(...listSourceFiles(join(dir, entry.name), rel));
+    } else if (SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) {
+      found.push(rel);
+    }
+  }
+  return found.sort(compareCodepoint);
+}
+
+function fenceFor(content: string): string {
+  const longestRun = Math.max(0, ...(content.match(/`+/g) ?? []).map((run) => run.length));
+  return "`".repeat(Math.max(3, longestRun + 1));
+}
+
+function renderRecipe(recipe: Recipe): string {
+  const parts = [`# ${recipe.slug}`];
+  if (recipe.description !== "") parts.push(recipe.description);
+  const readmePath = join(recipe.dir, "README.md");
+  if (existsSync(readmePath)) {
+    parts.push(`## README\n\n${readFileSync(readmePath, "utf-8").replace(/\r\n/g, "\n").trim()}`);
+  }
+  const sourceBlocks = listSourceFiles(join(recipe.dir, "src")).map((rel) => {
+    const content = readFileSync(join(recipe.dir, "src", rel), "utf-8")
+      .replace(/\r\n/g, "\n")
+      .trimEnd();
+    const fence = fenceFor(content);
+    const language = rel.endsWith(".tsx") ? "tsx" : "ts";
+    return `### src/${rel}\n\n${fence}${language}\n${content}\n${fence}`;
+  });
+  if (sourceBlocks.length > 0) parts.push(`## Source files\n\n${sourceBlocks.join("\n\n")}`);
+  return finishFile(`${RECIPES_REL}/${recipe.slug}`, parts.join("\n\n"));
+}
+
+export function renderAgentDocs(repoRoot: string): ReadonlyMap<string, string> {
+  const recipes = readRecipes(repoRoot);
+  const files = new Map<string, string>();
+  files.set("features.md", renderFeatures(repoRoot));
+  files.set("widgets.md", renderWidgets(repoRoot));
+  files.set("examples.md", renderExamplesIndex(recipes));
+  for (const recipe of recipes) files.set(`examples/${recipe.slug}.md`, renderRecipe(recipe));
+  return files;
+}
+
+function listFilesRecursive(dir: string, prefix = ""): string[] {
+  if (!existsSync(dir)) return [];
+  const found: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...listFilesRecursive(join(dir, entry.name), rel));
+    else found.push(rel);
+  }
+  return found.sort(compareCodepoint);
+}
+
+export function readAgentDocsOnDisk(repoRoot: string): ReadonlyMap<string, string> {
+  const dir = join(repoRoot, AGENT_DOCS_DIR);
+  return new Map(
+    listFilesRecursive(dir).map((rel) => [rel, readFileSync(join(dir, rel), "utf-8")]),
+  );
+}
+
+function removeEmptyDirs(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) removeEmptyDirs(join(dir, entry.name));
+  }
+  if (readdirSync(dir).length === 0) rmdirSync(dir);
+}
+
+export function writeAgentDocs(repoRoot: string): number {
+  const outDir = join(repoRoot, AGENT_DOCS_DIR);
+  const files = renderAgentDocs(repoRoot);
+  for (const [rel, content] of files) {
+    const target = join(outDir, rel);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content, "utf-8");
+  }
+  for (const rel of listFilesRecursive(outDir)) {
+    if (!files.has(rel)) unlinkSync(join(outDir, rel));
+  }
+  if (existsSync(outDir) && statSync(outDir).isDirectory()) removeEmptyDirs(outDir);
+  return files.size;
+}

package/src/_lib/dependency-cli.ts

@@ -0,0 +1,27 @@
+import { cliFlagsError } from "./guard-kit";
+import { findLocalRepo } from "./roots";
+
+export const DEPENDENCY_CHECK_FLAGS: readonly string[] = ["--report"];
+
+export type DependencyCliInvocation =
+  | { readonly ok: true; readonly repoRoot: string; readonly reportOnly: boolean }
+  | { readonly ok: false; readonly exitCode: number };
+
+/** Shared argv + repo resolution of the licenses/security/outdated subcommands. */
+export function parseDependencyCli(
+  subcommand: string,
+  argv: readonly string[],
+  cwd: string,
+): DependencyCliInvocation {
+  const flagsError = cliFlagsError(subcommand, argv, DEPENDENCY_CHECK_FLAGS);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    return { ok: false, exitCode: 1 };
+  }
+  const repo = findLocalRepo(cwd);
+  if (!repo) {
+    console.error(`  ${subcommand}: no Kumiko repo root found above ${cwd}.`);
+    return { ok: false, exitCode: 1 };
+  }
+  return { ok: true, repoRoot: repo.absPath, reportOnly: argv.includes("--report") };
+}

package/src/_lib/dependency-exceptions.ts

@@ -0,0 +1,135 @@
+/**
+ * Exception files for the dependency checks (licenses, security). Merged: the
+ * defaults bundled next to this package's sources and an optional file of the
+ * same name in each given root (the scanned repo's root, plus any ancestor
+ * whose installation the scan read packages or a lockfile from).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const BUNDLED_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export type ExceptionValidity = { readonly valid: boolean; readonly expired: boolean };
+
+/** Start of the day after `expires` (a `YYYY-MM-DD` date, UTC) in epoch ms; undefined when it is not a plain date. */
+export function expiryEndMs(expires: string): number | undefined {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(expires)) return undefined;
+  try {
+    return Temporal.PlainDate.from(expires).add({ days: 1 }).toZonedDateTime("UTC")
+      .epochMilliseconds;
+  } catch {
+    return undefined;
+  }
+}
+
+// An exception without an expiry never expires; callers that must not allow that (security) reject it on load.
+export function isExceptionValid(
+  expires: string | undefined,
+  nowMs: number = Date.now(),
+): ExceptionValidity {
+  if (!expires) return { valid: true, expired: false };
+  const endMs = expiryEndMs(expires);
+  if (endMs === undefined) return { valid: false, expired: false };
+  // The exception holds through the END of its expiry day.
+  const expired = nowMs >= endMs;
+  return { valid: !expired, expired };
+}
+
+export function findExpiringSoon<T extends { readonly expires?: string }>(
+  items: readonly T[],
+  withinDays = 30,
+  nowMs: number = Date.now(),
+): T[] {
+  const horizonMs = nowMs + withinDays * DAY_MS;
+  return items.filter((item) => {
+    const endMs = item.expires ? expiryEndMs(item.expires) : undefined;
+    return endMs !== undefined && nowMs < endMs && endMs - DAY_MS <= horizonMs;
+  });
+}
+
+/** Wildcard match for package names (trailing `*` only). */
+export function matchesPackageName(pattern: string, name: string): boolean {
+  if (pattern === name) return true;
+  if (!pattern.endsWith("*")) return false;
+  const prefix = pattern.slice(0, -1);
+  return prefix.length > 0 && name.startsWith(prefix);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+class MissingFieldError extends Error {
+  constructor(readonly field: string) {
+    super(`missing or blank "${field}"`);
+  }
+}
+
+export type ExceptionSource = { readonly file: string; readonly origin: "bundled" | "repo" };
+
+export function exceptionSources(
+  filename: string,
+  roots: readonly string[],
+  bundledDir = BUNDLED_DIR,
+): ExceptionSource[] {
+  const sources: ExceptionSource[] = [
+    { file: join(bundledDir, filename), origin: "bundled" },
+    ...[...new Set(roots)].map((root) => ({ file: join(root, filename), origin: "repo" as const })),
+  ];
+  return sources.filter((source) => existsSync(source.file));
+}
+
+function readExceptionEntries(source: ExceptionSource, filename: string): unknown[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(source.file, "utf-8"));
+  } catch {
+    console.warn(
+      `  WARN: ${source.origin} ${filename} (${source.file}) is not readable JSON — ignored.`,
+    );
+    return [];
+  }
+  const entries = isRecord(parsed) ? parsed["exceptions"] : undefined;
+  if (!Array.isArray(entries)) {
+    console.warn(`  WARN: ${source.origin} ${filename} has no "exceptions" array — ignored.`);
+    return [];
+  }
+  return entries;
+}
+
+/**
+ * Loads and merges the exception entries of `filename`. `parse` builds one
+ * exception from its entry; asking `field(key)` for a missing or blank string
+ * drops that entry with a warning. A broken file or entry is never trusted: a
+ * dropped exception can only make a check stricter.
+ */
+export function loadExceptionEntries<T>(options: {
+  readonly filename: string;
+  readonly roots: readonly string[];
+  readonly parse: (field: (key: string) => string) => T;
+  readonly bundledDir?: string;
+}): T[] {
+  const merged: T[] = [];
+  for (const source of exceptionSources(options.filename, options.roots, options.bundledDir)) {
+    for (const entry of readExceptionEntries(source, options.filename)) {
+      try {
+        if (!isRecord(entry)) throw new MissingFieldError("(entry is not an object)");
+        merged.push(
+          options.parse((key) => {
+            const value = entry[key];
+            if (typeof value !== "string" || value.trim() === "") throw new MissingFieldError(key);
+            return value;
+          }),
+        );
+      } catch (err) {
+        if (!(err instanceof MissingFieldError)) throw err;
+        console.warn(
+          `  WARN: ${source.origin} ${options.filename}: entry dropped, ${err.message}.`,
+        );
+      }
+    }
+  }
+  return merged;
+}