@cosmicdrift/kumiko-guards 0.401.0 → 0.402.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.401.0",
+  "version": "0.402.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.401.0",
+    "@cosmicdrift/kumiko-types": "0.402.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },
@@ -52,7 +52,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.401.0"
+    "@cosmicdrift/kumiko-framework": "0.402.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -60,6 +60,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.401.0"
+    "@cosmicdrift/kumiko-framework": "0.402.0"
   }
 }

package/src/_lib/agent-docs-boot-rules.ts

@@ -0,0 +1,142 @@
+import { relative } from "node:path";
+import { Glob } from "bun";
+import { Node, type ObjectLiteralExpression, type Project } from "ts-morph";
+import { compareCodepoint, finishFile, table } from "./agent-docs-shared";
+
+const RULE_FILE_GLOBS = [
+  "packages/framework/src/engine/boot-validator/*-rules.ts",
+  "packages/bundled-features/src/*/boot-rules.ts",
+];
+const RULE_TABLE_TYPE = "BootRuleTable";
+const RULE_ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*\/[a-z0-9]+(-[a-z0-9]+)*$/;
+const RULE_FIELDS = ["id", "summary", "fix"] as const;
+
+type DocumentedRule = {
+  readonly id: string;
+  readonly summary: string;
+  readonly fix: string;
+  readonly source: string;
+};
+
+// Must match bootRuleDocLink in packages/framework/src/engine/boot-validator/boot-rule.ts.
+function anchorOf(ruleId: string): string {
+  return ruleId.replaceAll("/", "-");
+}
+
+function literalText(node: Node | undefined): string | undefined {
+  if (node === undefined) return undefined;
+  if (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node)) {
+    return node.getLiteralText();
+  }
+  return undefined;
+}
+
+function readRule(source: string, key: string, rule: Node): DocumentedRule {
+  if (!Node.isObjectLiteralExpression(rule)) {
+    throw new Error(`${source}: rule "${key}" must be an object literal`);
+  }
+  const values = RULE_FIELDS.map((field) => {
+    const property = rule.getProperty(field);
+    const text = Node.isPropertyAssignment(property)
+      ? literalText(property.getInitializer())
+      : undefined;
+    if (text === undefined) {
+      throw new Error(
+        `${source}: rule "${key}" property "${field}" must be a plain string literal`,
+      );
+    }
+    return text;
+  });
+  const [id = "", summary = "", fix = ""] = values;
+  if (!RULE_ID_RE.test(id)) {
+    throw new Error(`${source}: rule "${key}" has id "${id}" which does not match ${RULE_ID_RE}`);
+  }
+  return { id, summary, fix, source };
+}
+
+function tableLiteralOf(initializer: Node | undefined): ObjectLiteralExpression | undefined {
+  if (initializer === undefined || !Node.isSatisfiesExpression(initializer)) return undefined;
+  if (initializer.getTypeNode()?.getText() !== RULE_TABLE_TYPE) return undefined;
+  const inner = initializer.getExpression();
+  const unwrapped = Node.isAsExpression(inner) ? inner.getExpression() : inner;
+  return Node.isObjectLiteralExpression(unwrapped) ? unwrapped : undefined;
+}
+
+function readRulesOfFile(project: Project, repoRoot: string, absPath: string): DocumentedRule[] {
+  const source = relative(repoRoot, absPath).split("\\").join("/");
+  const rules: DocumentedRule[] = [];
+  for (const declaration of project.addSourceFileAtPath(absPath).getVariableDeclarations()) {
+    if (!declaration.isExported()) continue;
+    const literal = tableLiteralOf(declaration.getInitializer());
+    if (literal === undefined) continue;
+    for (const property of literal.getProperties()) {
+      if (!Node.isPropertyAssignment(property)) {
+        throw new Error(`${source}: ${declaration.getName()} may only hold plain properties`);
+      }
+      const initializer = property.getInitializer();
+      if (initializer === undefined) continue;
+      rules.push(readRule(source, property.getName(), initializer));
+    }
+  }
+  return rules;
+}
+
+function ruleFilesOf(repoRoot: string): string[] {
+  const found = new Set<string>();
+  for (const pattern of RULE_FILE_GLOBS) {
+    for (const rel of new Glob(pattern).scanSync({ cwd: repoRoot, onlyFiles: true })) {
+      found.add(`${repoRoot}/${rel}`);
+    }
+  }
+  return [...found].sort(compareCodepoint);
+}
+
+function assertUnique(rules: readonly DocumentedRule[]): void {
+  const idSources = new Map<string, string>();
+  const anchorIds = new Map<string, string>();
+  for (const rule of rules) {
+    const knownSource = idSources.get(rule.id);
+    if (knownSource !== undefined) {
+      throw new Error(`Duplicate boot rule id "${rule.id}" in ${rule.source} and ${knownSource}`);
+    }
+    idSources.set(rule.id, rule.source);
+    const anchor = anchorOf(rule.id);
+    const knownId = anchorIds.get(anchor);
+    if (knownId !== undefined) {
+      throw new Error(`Boot rule ids "${rule.id}" and "${knownId}" share the anchor "${anchor}"`);
+    }
+    anchorIds.set(anchor, rule.id);
+  }
+}
+
+// Ids are validated against RULE_ID_RE, so the anchor cannot carry markup.
+function ruleCell(ruleId: string): string {
+  return ['<a id="', anchorOf(ruleId), '"></a>`', ruleId, "`"].join("");
+}
+
+const INTRO = [
+  "`validateBoot` reports every violation as `- [<id>] <message>`, followed by a `Fix:` and a `Rule:` line that links the entry below.",
+  "Violations with an `unclassified/<check>` id have no entry yet.",
+  "`kumiko-schema validate --json` returns the same ids.",
+].join(" ");
+
+export function renderBootRules(repoRoot: string, project: Project): string {
+  const rules = ruleFilesOf(repoRoot).flatMap((file) => readRulesOfFile(project, repoRoot, file));
+  assertUnique(rules);
+  const source = "boot rule tables (`*-rules.ts`, `boot-rules.ts`)";
+  if (rules.length === 0) {
+    return finishFile(source, `# Boot rules\n\n${INTRO}\n\nNo boot rules are registered yet.`);
+  }
+  const byArea = new Map<string, DocumentedRule[]>();
+  for (const rule of rules) {
+    const area = rule.id.split("/", 1)[0] ?? rule.id;
+    byArea.set(area, [...(byArea.get(area) ?? []), rule]);
+  }
+  const sections = [...byArea.keys()].sort(compareCodepoint).map((area) => {
+    const rows = (byArea.get(area) ?? [])
+      .sort((left, right) => compareCodepoint(left.id, right.id))
+      .map((rule) => [ruleCell(rule.id), rule.summary, rule.fix, `\`${rule.source}\``]);
+    return `## ${area}\n\n${table(["Rule", "Summary", "Fix", "Source"], rows)}`;
+  });
+  return finishFile(source, `# Boot rules\n\n${INTRO}\n\n${sections.join("\n\n")}`);
+}

package/src/_lib/agent-docs.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join } from "node:path";
 import { type ExportedDeclarations, type JSDocableNode, Node, type Project } from "ts-morph";
 import { renderApiDocs } from "./agent-docs-api";
+import { renderBootRules } from "./agent-docs-boot-rules";
 import { renderFeatureDocs } from "./agent-docs-features";
 import {
   compareCodepoint,
@@ -197,6 +198,7 @@ export function renderAgentDocs(repoRoot: string): ReadonlyMap<string, string> {
   files.set("features-index.md", featureDocs.featuresIndex);
   files.set("features.md", featureDocs.features);
   files.set("widgets.md", renderWidgets(repoRoot, project));
+  files.set("boot-rules.md", renderBootRules(repoRoot, project));
   for (const [rel, content] of renderApiDocs(repoRoot, project)) files.set(rel, content);
   files.set("examples.md", renderExamplesIndex(recipes));
   for (const recipe of recipes) files.set(`examples/${recipe.slug}.md`, renderRecipe(recipe));

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "New guard boot-raw-throws",
+    "detail": "Freezes the count of raw `throw new Error` in `engine/boot-validator` and bundled `boot-checks.ts` per file in `.kumiko-boot-raw-throws-baseline.json`. New boot checks throw `bootRuleError(RULE, { message })` with a rule table. Only the framework repo is scanned."
+  },
   {
     "version": "0.396.0",
     "type": "improvement",

package/src/guard-boot-raw-throws.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+/**
+ * Boot Raw Throws Guard: freezes raw `throw new Error` in boot validation per file, because new boot rules use `throw bootRuleError(RULE, { message })` with a rule table in `<validator>-rules.ts`; the guard and its baseline `.kumiko-boot-raw-throws-baseline.json` are deleted once every file is at 0.
+ */
+
+import path from "node:path";
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const ROOT = process.cwd();
+const GUARD_NAME = "boot-raw-throws";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  kinds: ["framework"],
+  extensions: ["ts"],
+  frameworkWithin: [
+    "packages/framework/src/engine/boot-validator/**",
+    "packages/bundled-features/src/*/boot-checks.ts",
+  ],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.d\.ts$)/;
+
+export function rawErrorThrowLines(file: SourceFile): number[] {
+  return file
+    .getDescendantsOfKind(SyntaxKind.ThrowStatement)
+    .filter((statement) => {
+      const thrown = statement.getExpression();
+      return (
+        thrown.isKind(SyntaxKind.NewExpression) && thrown.getExpression().getText() === "Error"
+      );
+    })
+    .map((statement) => statement.getStartLineNumber());
+}
+
+export function rawThrowCounts(
+  files: readonly SourceFile[],
+  roots: ReadonlyArray<{ readonly absPath: string }> = resolveRepoRoots(),
+): { counts: Record<string, number>; firstLine: Record<string, number> } {
+  const counts: Record<string, number> = {};
+  const firstLine: Record<string, number> = {};
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    const lines = rawErrorThrowLines(sf);
+    const first = lines[0];
+    if (first === undefined) continue;
+    const file = relFromRepoRoot(sf.getFilePath(), roots);
+    if (!isLocalFinding({ file })) continue;
+    counts[file] = lines.length;
+    firstLine[file] = first;
+  }
+  return { counts, firstLine };
+}
+
+const rawThrowBaseline = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-boot-raw-throws-baseline.json"),
+  formatVersion: 1,
+  unit: "raw throw new Error in boot validation",
+  failClosed: true,
+});
+
+const REMEDIATION =
+  "Declare the rule in the validator's `<validator>-rules.ts` table and throw `bootRuleError(RULES.name, { message })` instead of `new Error(...)`.";
+
+export const guard: AstGuard = {
+  name: GUARD_NAME,
+  scan: SCAN,
+  hint: `after fixing hits: \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\``,
+  run: (files, roots = resolveRepoRoots()) => {
+    const { counts, firstLine } = rawThrowCounts(files, roots);
+    return {
+      violations: rawThrowBaseline.check(counts, REMEDIATION, {
+        formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard=${GUARD_NAME}\` once.`,
+        resolveLine: (file) => firstLine[file] ?? 1,
+      }),
+    };
+  },
+  writeBaseline: (files, roots = resolveRepoRoots()) => {
+    rawThrowBaseline.write(rawThrowCounts(files, roots).counts);
+  },
+};
+
+if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    guard.writeBaseline?.(filesForGuard(project, guard));
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/run-guards.ts

@@ -25,6 +25,7 @@ import { guard as complexity } from "./check-complexity";
 import { guard as predicateExtraction } from "./check-predicates";
 import { guard as adminApi } from "./guard-admin-api";
 import { guard as appFeatureStructure } from "./guard-app-feature-structure";
+import { guard as bootRawThrows } from "./guard-boot-raw-throws";
 import { guard as commentIssueRefOnly } from "./guard-comment-issue-ref-only";
 import { guard as crossFeatureImports } from "./guard-cross-feature-imports";
 import { guard as directEntityWrites } from "./guard-direct-entity-writes";
@@ -96,6 +97,7 @@ export const GUARDS = [
   commentIssueRefOnly,
   testTitle,
   ignoreTagReason,
+  bootRawThrows,
 ];
 
 export const GUARD_FLAGS = [