@cosmicdrift/kumiko-guards 0.1.1 → 0.281.0

package/src/guard-escape-hatch-declared.ts

@@ -6,15 +6,18 @@
  *   R1 raw-outside-system-scope: a TenantDb `.raw` escape used outside a
  *      `r.systemScope()` feature.
  *   R2 unsafe-raw-outside-system-scope: `ctx.systemDb.unsafeRaw(...)` outside
- *      systemScope and outside a handler/hook that lexically declares
- *      `escapeHatch`.
+ *      systemScope, a job scope, an explicit `withUnsafeRawGrant(...)`, a
+ *      handler/hook that lexically declares `escapeHatch`, or a standalone
+ *      function whose direct body declares `declareEscapeHatch({ reason: "..." })`.
  *   R3 system-identity-outside-declared-scope: `queryAs`/`writeAs` called
  *      with a system identity outside systemScope, `.job.ts`, an `r.job(...)`
- *      call, a `*Job` function, or a handler/hook that lexically declares
- *      `escapeHatch`.
- *   R4 generic-reason: `acknowledgeCrossTenant`/`unsafeRaw`, or a declared
- *      `escapeHatch: { reason }`/`unsafeAllTenants: { reason }`, given a
- *      placeholder reason literal — hard-fails everywhere, not baselined.
+ *      call, a `*Job` function, a handler/hook that lexically declares
+ *      `escapeHatch`, or a standalone function whose direct body declares
+ *      `declareEscapeHatch({ reason: "..." })`.
+ *   R4 generic-reason: `acknowledgeCrossTenant`/`unsafeRaw`, a declared
+ *      `escapeHatch: { reason }`/`unsafeAllTenants: { reason }`, or a
+ *      `declareEscapeHatch({ reason })` call, given a placeholder reason
+ *      literal — hard-fails everywhere, not baselined.
  *   R5 unsafe-all-tenants-outside-declared-scope: an `unsafeAllTenants: true`
  *      or `unsafeAllTenants: { reason: "..." }` option, passed directly as a
  *      call argument, outside systemScope, `.job.ts`, an `r.job(...)` call,
@@ -22,28 +25,53 @@
  *
  * escapeHatch (R2/R3) is recognized only as a direct, literal `escapeHatch`
  * property (object literal, or ternary of two object literals) either in the
- * same object literal as an inline `handler` function, or in an options object
- * passed to `r.hook`/`writeHandler`/`queryHandler`/`streamHandler` alongside
- * the handler function argument. Referenced-by-variable functions, spread
- * options, computed/string keys, and non-literal escapeHatch values are
- * conservatively not recognized (miss, don't falsely clear).
+ * same object literal as any inline function property (ArrowFunction or
+ * FunctionExpression, under any key name — e.g. `handler`, `export`,
+ * `delete`), or in an options object passed to
+ * `r.hook`/`writeHandler`/`queryHandler`/`streamHandler`/`useExtension`
+ * alongside the handler function argument. A standalone function (arrow
+ * function, function expression, method declaration, or function
+ * declaration) is additionally recognized when a statement in its own direct
+ * body — not a nested function's, not inside an `if` — calls the bare
+ * identifier `declareEscapeHatch` with exactly one object-literal argument
+ * carrying a literal, non-placeholder `reason` (from
+ * `@cosmicdrift/kumiko-framework/engine`'s `declareEscapeHatch`: a helper
+ * that escalates on a `HandlerContext` handed to it by its caller, rather
+ * than a `HandlerContext` from its own registration). The declaration does
+ * not propagate upward: it covers escalations inside that function's own
+ * body, not the function it is nested inside. This detection is purely
+ * lexical — the guard matches on the name `declareEscapeHatch`, not on where
+ * it was imported from, so a same-named local function clears just as well;
+ * consistent with `escapeHatch:` itself, which is likewise never checked for
+ * origin. Referenced-by-variable functions, spread options, computed/string
+ * keys, and non-literal escapeHatch/reason values are conservatively not
+ * recognized (miss, don't falsely clear).
  *
  * Empty reasons, `openToAll.personalData` and PII are the framework boot validator's
- * job (access-declarations.ts), not this guard's. Known false-negatives:
- * multi-hop aliasing, `ctx["db"]` through an intermediate variable, and a
- * TenantDb/system-identity handed to another function across file
- * boundaries — all conservative (miss, don't falsely flag). R5 additionally
- * misses `unsafeAllTenants` given via an identifier, a ternary, `false`, or
- * `undefined`, and an options object passed by variable reference or spread
- * rather than as a literal call argument — all conservative (miss, don't
- * falsely flag).
+ * job (access-declarations.ts), not this guard's — except a `declareEscapeHatch`
+ * reason, which has no boot validator behind it: an empty or placeholder
+ * reason there is never recognized as a valid declaration (see R4). Known
+ * false-negatives: multi-hop aliasing, `ctx["db"]` through an intermediate
+ * variable, and a TenantDb/system-identity handed to another function across
+ * file boundaries with no `declareEscapeHatch` call at the escalation site
+ * (declarable now, so no longer a blanket false-negative) — all conservative
+ * (miss, don't falsely flag). R5 additionally misses `unsafeAllTenants`
+ * given via an identifier, a ternary, `false`, or `undefined`, and an
+ * options object passed by variable reference or spread rather than as a
+ * literal call argument — all conservative (miss, don't falsely flag).
  *
  * Usage:
  *   bun guards/guard-escape-hatch-declared.ts
  *   Baseline: bun guards/run-guards.ts --write-security-baseline
  */
 import * as path from "node:path";
-import { type Node, type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type Node,
+  type ObjectLiteralExpression,
+  type PropertyAssignment,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { isGenericReason, literalReasonText } from "./_lib/generic-reason";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
@@ -174,7 +202,7 @@ function findUnsafeRawFindings(
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
     if (expr.getName() !== "unsafeRaw") continue;
-    if (isInsideEscapeHatchDeclaredFunction(call)) continue;
+    if (isAllowedEscapeHatchCall(call, sf, systemDirs) || isExplicitUnsafeRawGrant(call)) continue;
     out.push({
       file: path.relative(root, sf.getFilePath()),
       line: call.getStartLineNumber(),
@@ -186,6 +214,19 @@ function findUnsafeRawFindings(
   return out;
 }
 
+function isExplicitUnsafeRawGrant(call: Node): boolean {
+  if (!call.isKind(SyntaxKind.CallExpression)) return false;
+  const expr = call.getExpression();
+  if (!expr.isKind(SyntaxKind.PropertyAccessExpression) || expr.getName() !== "unsafeRaw") {
+    return false;
+  }
+  const receiver = expr.getExpression();
+  return (
+    receiver.isKind(SyntaxKind.CallExpression) &&
+    receiver.getExpression().getText() === "withUnsafeRawGrant"
+  );
+}
+
 function isSystemIdentityExpression(node: Node): boolean {
   if (node.isKind(SyntaxKind.CallExpression)) {
     const calleeText = node.getExpression().getText();
@@ -270,6 +311,7 @@ const ESCAPE_HATCH_CALL_METHODS = new Set([
   "writeHandler",
   "queryHandler",
   "streamHandler",
+  "useExtension",
 ]);
 
 function isEscapeHatchDeclaredFunction(fn: Node): boolean {
@@ -277,13 +319,7 @@ function isEscapeHatchDeclaredFunction(fn: Node): boolean {
   if (!parent) return false;
 
   if (fn.isKind(SyntaxKind.MethodDeclaration)) {
-    const nameNode = fn.getNameNode();
-    return (
-      nameNode.isKind(SyntaxKind.Identifier) &&
-      nameNode.getText() === "handler" &&
-      parent.isKind(SyntaxKind.ObjectLiteralExpression) &&
-      objectDeclaresEscapeHatch(parent)
-    );
+    return parent.isKind(SyntaxKind.ObjectLiteralExpression) && objectDeclaresEscapeHatch(parent);
   }
 
   if (!fn.isKind(SyntaxKind.ArrowFunction) && !fn.isKind(SyntaxKind.FunctionExpression)) {
@@ -291,11 +327,8 @@ function isEscapeHatchDeclaredFunction(fn: Node): boolean {
   }
 
   if (parent.isKind(SyntaxKind.PropertyAssignment)) {
-    const nameNode = parent.getNameNode();
     const obj = parent.getParent();
     return (
-      nameNode.isKind(SyntaxKind.Identifier) &&
-      nameNode.getText() === "handler" &&
       parent.getInitializer() === fn &&
       obj.isKind(SyntaxKind.ObjectLiteralExpression) &&
       objectDeclaresEscapeHatch(obj)
@@ -323,15 +356,72 @@ function isEscapeHatchDeclaredFunction(fn: Node): boolean {
   return false;
 }
 
+// The bare-identifier `reason` PropertyAssignment on an object literal —
+// shared between the declareEscapeHatch statement check below and its R4
+// generic-reason collector, so both agree on what counts as the reason.
+function findReasonPropertyAssignment(
+  obj: ObjectLiteralExpression,
+): PropertyAssignment | undefined {
+  return obj
+    .getProperties()
+    .find(
+      (prop): prop is PropertyAssignment =>
+        prop.isKind(SyntaxKind.PropertyAssignment) &&
+        prop.getNameNode().isKind(SyntaxKind.Identifier) &&
+        prop.getNameNode().getText() === "reason",
+    );
+}
+
+// declareEscapeHatch({ reason: "..." }) as a direct-body statement of a
+// standalone function. No boot validator backs this form (unlike the
+// escapeHatch: {...} property, which access-declarations.ts checks at boot),
+// so an empty/placeholder reason is rejected here rather than left to it.
+function isValidDeclareEscapeHatchCall(stmt: Node): boolean {
+  if (!stmt.isKind(SyntaxKind.ExpressionStatement)) return false;
+  const expr = stmt.getExpression();
+  if (!expr.isKind(SyntaxKind.CallExpression)) return false;
+  const callee = expr.getExpression();
+  if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
+    return false;
+  }
+  const args = expr.getArguments();
+  const arg = args[0];
+  if (args.length !== 1 || !arg?.isKind(SyntaxKind.ObjectLiteralExpression)) return false;
+  const reasonProp = findReasonPropertyAssignment(arg);
+  if (!reasonProp) return false;
+  const reasonText = literalReasonText(reasonProp.getInitializer());
+  return reasonText !== undefined && !isGenericReason(reasonText);
+}
+
+// Only the function's own direct body — not a nested function's, not an
+// `if`'s — so a declareEscapeHatch call does not cover the function it is
+// itself nested inside (miss, don't falsely clear).
+function hasDeclaredEscapeHatchStatement(fn: Node): boolean {
+  let body: Node | undefined;
+  if (
+    fn.isKind(SyntaxKind.ArrowFunction) ||
+    fn.isKind(SyntaxKind.FunctionExpression) ||
+    fn.isKind(SyntaxKind.MethodDeclaration) ||
+    fn.isKind(SyntaxKind.FunctionDeclaration)
+  ) {
+    body = fn.getBody();
+  }
+  if (!body?.isKind(SyntaxKind.Block)) return false;
+  return body.getStatements().some((stmt) => isValidDeclareEscapeHatchCall(stmt));
+}
+
 function isInsideEscapeHatchDeclaredFunction(node: Node): boolean {
   let ancestor: Node | undefined = node.getParent();
   while (ancestor) {
     if (
       ancestor.isKind(SyntaxKind.ArrowFunction) ||
       ancestor.isKind(SyntaxKind.FunctionExpression) ||
-      ancestor.isKind(SyntaxKind.MethodDeclaration)
+      ancestor.isKind(SyntaxKind.MethodDeclaration) ||
+      ancestor.isKind(SyntaxKind.FunctionDeclaration)
     ) {
-      if (isEscapeHatchDeclaredFunction(ancestor)) return true;
+      if (isEscapeHatchDeclaredFunction(ancestor) || hasDeclaredEscapeHatchStatement(ancestor)) {
+        return true;
+      }
     }
     ancestor = ancestor.getParent();
   }
@@ -446,6 +536,35 @@ function findGenericReasonMethodCalls(sf: SourceFile, root: string): GenericReas
   return out;
 }
 
+// The declareEscapeHatch({ reason }) form falls through both existing R4
+// collectors: its callee is a bare identifier, not a PropertyAccessExpression
+// (unlike acknowledgeCrossTenant/unsafeRaw), and its reason sits directly in
+// the call argument, not under an escapeHatch:/unsafeAllTenants: property.
+function findGenericReasonDeclareEscapeHatchCalls(
+  sf: SourceFile,
+  root: string,
+): GenericReasonFinding[] {
+  const out: GenericReasonFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
+      continue;
+    }
+    const arg = call.getArguments()[0];
+    if (!arg?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
+    const reasonProp = findReasonPropertyAssignment(arg);
+    if (!reasonProp) continue;
+    const reasonText = literalReasonText(reasonProp.getInitializer());
+    if (reasonText === undefined || !isGenericReason(reasonText)) continue;
+    out.push({
+      file: path.relative(root, sf.getFilePath()),
+      line: call.getStartLineNumber(),
+      message: `declareEscapeHatch({ reason: "${reasonText}" }) uses a placeholder reason — give a concrete, reviewable justification for this cross-tenant/unsafe access.`,
+    });
+  }
+  return out;
+}
+
 const REASON_OBJECT_PROPERTY_NAMES = ["escapeHatch", "unsafeAllTenants"] as const;
 
 function findGenericReasonObjectProperty(
@@ -481,6 +600,7 @@ export function findGenericReasonCalls(
   const out: GenericReasonFinding[] = [];
   for (const sf of scannableFiles(files)) {
     out.push(...findGenericReasonMethodCalls(sf, root));
+    out.push(...findGenericReasonDeclareEscapeHatchCalls(sf, root));
     for (const propertyName of REASON_OBJECT_PROPERTY_NAMES) {
       out.push(...findGenericReasonObjectProperty(sf, root, propertyName));
     }
@@ -493,7 +613,7 @@ export function createEscapeHatchGuard(opts: { root: string }): AstGuard {
     name: "Escape-Hatch-Declared Guard",
     scan: SCAN,
     security: true,
-    hint: 'Escape-Hatch deklarieren (r.systemScope() auf der Feature-Definition, .job.ts/r.job(...) fuer Jobs, oder { escapeHatch: { reason: "..." } } auf dem Handler oder Hook) oder den ctx.db.raw/unsafeRaw/queryAs|writeAs(system)/unsafeAllTenants-Zugriff entfernen. Baseline nach bewusster Reduktion: `bun guards/run-guards.ts --write-security-baseline`',
+    hint: 'Declare an escape hatch (r.systemScope() on the feature definition, .job.ts/r.job(...) for jobs, or { escapeHatch: { reason: "..." } } on the handler or hook), or remove the ctx.db.raw/unsafeRaw/queryAs|writeAs(system)/unsafeAllTenants access. Baseline after a deliberate reduction: `bun guards/run-guards.ts --write-security-baseline`',
     run(files) {
       const violations: GuardViolation[] = [
         ...findGenericReasonCalls(files, opts.root).map((f) => ({

package/src/guard-fake-tests.ts

@@ -117,7 +117,7 @@ function scanFile(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Fake-Test Guard",
   scan: SCAN,
-  hint: "Test ohne expect() oder mit Tautologie — echtes Verhalten prüfen, nicht Existenz.",
+  hint: "Test without expect() or with a tautology — check real behavior, not existence.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
     for (const sf of files) {

package/src/guard-feature-integration-tests.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env bun
+/**
+ * Guard: every feature in packages/bundled-features/src/<name>/feature.ts
+ * must be imported by at least one *.integration.ts. Otherwise it never ran
+ * through the full stack — exactly the "feature built, never wired up" case
+ * from CLAUDE.md.
+ *
+ * Coverage rule: a feature counts as covered when an integration test
+ * imports anything — relative or via the `@cosmicdrift/kumiko-bundled-features`
+ * package — that resolves into its `packages/bundled-features/src/<name>/`
+ * directory. That's deliberately broader than "imports feature.ts itself":
+ * a test that imports a sibling module of the feature (e.g. its resolver,
+ * its defaults helper) still proves the directory ran, and a barrel import
+ * of the whole package still proves the feature was composed. Since the
+ * `<name>-feature.ts` -> `feature.ts` rename (df3f6b5b) the file basename is
+ * identical for all 56 features — the directory name is the only usable
+ * identifier.
+ *
+ * Usage:
+ *   bun guards/guard-feature-integration-tests.ts
+ */
+
+import * as path from "node:path";
+import { Project, SyntaxKind } from "ts-morph";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import { frameworkPackageTsConfigPath, type RepoRoot } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+
+const ROOT = process.cwd();
+
+const FEATURES_SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  kinds: ["framework"],
+  frameworkWithin: ["packages/bundled-features/src/**/feature.ts"],
+};
+// Both suffixes: `.integration.ts` (legacy) and `.integration.test.ts`
+// (canonical after the bun-test cutover). dev-server covers features
+// indirectly (walkthrough tests that compose real bundled features) — must
+// be scanned too, otherwise those feature references stay invisible.
+const INTEGRATION_SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  kinds: ["framework"],
+  frameworkWithin: [
+    "packages/bundled-features/src/**/*.integration.ts",
+    "packages/bundled-features/src/**/*.integration.test.ts",
+    "packages/framework/src/**/*.integration.ts",
+    "packages/framework/src/**/*.integration.test.ts",
+    "packages/dev-server/src/**/*.integration.ts",
+    "packages/dev-server/src/**/*.integration.test.ts",
+  ],
+};
+
+const BUNDLED_FEATURES_PACKAGE_SPEC = /^@cosmicdrift\/kumiko-bundled-features\/([^/]+)/;
+const BUNDLED_FEATURES_SRC_DIR = /bundled-features\/src\/([^/]+)\//;
+
+/**
+ * Resolves an import specifier to the feature ID it reaches, or `null` if
+ * the import doesn't land inside a bundled feature's directory. Pure —
+ * testable without a Project.
+ */
+export function extractFeatureId(spec: string, importingFilePath: string): string | null {
+  const packageMatch = spec.match(BUNDLED_FEATURES_PACKAGE_SPEC);
+  if (packageMatch) return packageMatch[1] ?? null;
+
+  if (!spec.startsWith(".")) return null;
+  const resolved = path.resolve(path.dirname(importingFilePath), spec);
+  // A relative import that never leaves the __tests__ dir (./helpers,
+  // ./fixtures) doesn't prove the feature itself is imported anywhere —
+  // only that its test has co-located helpers.
+  if (resolved.split(path.sep).includes("__tests__")) return null;
+  const dirMatch = `${resolved}/`.match(BUNDLED_FEATURES_SRC_DIR);
+  return dirMatch?.[1] ?? null;
+}
+
+function collectFeatures(project: Project, paths: readonly string[]): Map<string, string> {
+  const features = new Map<string, string>();
+  for (const p of paths) {
+    const sf = project.getSourceFile(p) ?? project.addSourceFileAtPath(p);
+    const filePath = sf.getFilePath();
+    if (path.basename(filePath) !== "feature.ts") continue;
+    // Same derivation as extractFeatureId (producer/consumer must agree, or
+    // a nested feature dir orphans permanently — no import could ever
+    // satisfy a mismatched ID). Also filters out non-feature `feature.ts`
+    // fixtures (e.g. under __tests__) that don't sit in a bundled-features
+    // src dir.
+    const dirMatch = `${filePath}`.match(BUNDLED_FEATURES_SRC_DIR);
+    const featureId = dirMatch?.[1];
+    if (!featureId) continue;
+    features.set(featureId, path.relative(ROOT, filePath));
+  }
+  return features;
+}
+
+function collectImportedFeatureIds(project: Project, roots: readonly RepoRoot[]): Set<string> {
+  for (const p of scanFiles(INTEGRATION_SCAN, roots)) {
+    if (!project.getSourceFile(p)) project.addSourceFileAtPath(p);
+  }
+  const imported = new Set<string>();
+  for (const sf of project.getSourceFiles()) {
+    if (!/\.integration(\.test)?\.ts$/.test(sf.getFilePath())) continue;
+    for (const imp of sf.getDescendantsOfKind(SyntaxKind.ImportDeclaration)) {
+      const featureId = extractFeatureId(imp.getModuleSpecifierValue(), sf.getFilePath());
+      if (featureId) imported.add(featureId);
+    }
+  }
+  return imported;
+}
+
+/**
+ * Baseline from the infra#436 measurement: features with no integration
+ * test reaching their directory at all — only covered (if at all) by unit
+ * tests (`feature.test.ts`). Pre-existing at the first sharp run, not
+ * introduced by this change. Backfilling is its own scope per feature, not
+ * a sweep.
+ */
+const ALLOWLIST: ReadonlySet<string> = new Set(["step-dispatcher"]);
+
+export function computeOrphans(
+  features: ReadonlyMap<string, string>,
+  imported: ReadonlySet<string>,
+  allowlist: ReadonlySet<string> = ALLOWLIST,
+): Array<{ name: string; file: string }> {
+  const orphans: Array<{ name: string; file: string }> = [];
+  for (const [id, file] of features) {
+    if (!imported.has(id) && !allowlist.has(id)) orphans.push({ name: id, file });
+  }
+  return orphans;
+}
+
+export const check: RepoCheck = {
+  name: "Feature-Integration-Test Guard",
+  hint:
+    "Every feature needs a *.integration.ts that uses it in " +
+    "setupTestStack({ features: [...] }).",
+  run(roots) {
+    if (!roots.some((r) => r.kind === "framework")) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+
+    const project = new Project({
+      tsConfigFilePath: frameworkPackageTsConfigPath("bundled-features"),
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+    });
+
+    const featurePaths = scanFiles(FEATURES_SCAN, roots);
+    const features = collectFeatures(project, featurePaths);
+    const imported = collectImportedFeatureIds(project, roots);
+
+    const violations: GuardViolation[] = [];
+
+    const stale = [...ALLOWLIST].filter((id) => imported.has(id));
+    for (const id of stale) {
+      violations.push({
+        file: features.get(id) ?? id,
+        line: 1,
+        message: `Allowlist entry "${id}" is now covered by an integration test — remove it from ALLOWLIST.`,
+      });
+    }
+
+    for (const orphan of computeOrphans(features, imported)) {
+      violations.push({
+        file: orphan.file,
+        line: 1,
+        message:
+          "Feature without an integration test — needs a *.integration.ts that uses it in setupTestStack({ features: [...] }).",
+      });
+    }
+
+    return { violations, matchedFiles: featurePaths.length, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-html-escape.ts

@@ -325,7 +325,7 @@ function scanFile(sf: SourceFile): UnsafeSite[] {
 export const guard: AstGuard = {
   name: "HTML-Escape Guard",
   scan: SCAN,
-  hint: "Interpolation in HTML-Template-Literal escapen: escapeHtml()/escapeHtmlAttr() aus @cosmicdrift/kumiko-headless. Vorgerendertes HTML per `*Html`-Namen kennzeichnen; statische Copy-Tabellen `as const` typen; bewusste Ausnahme mit `// html-ok: <warum>`.",
+  hint: "Escape interpolation in an HTML template literal: escapeHtml()/escapeHtmlAttr() from @cosmicdrift/kumiko-headless. Mark pre-rendered HTML with a `*Html` name; type static copy tables `as const`; deliberate exception with `// html-ok: <why>`.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
     for (const sf of files) {