@cosmicdrift/kumiko-guards 0.381.0 → 0.383.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.381.0",
+  "version": "0.383.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>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.381.0"
+    "@cosmicdrift/kumiko-framework": "0.383.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.381.0"
+    "@cosmicdrift/kumiko-framework": "0.383.0"
   }
 }

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Nine guards are removed because types and boot checks replace them",
+    "detail": "Removed guards and their replacement. Text-Field Personal-Stance: the field factories require `personal`. API-Object-Form: the registrar only has the object form. Table-DDL (warning only), Pre-ES-Patterns and No-Broker-Subscribe (the broker is not exported). Open-To-All-Reason and Escape-Hatch-Declared: boot and runtime reason validation. Loadall-Events: the function is removed. Section-Fields-Raw: EditFieldsSection is a union. Screen-Conventions loses rule R1 (metrics without label), the type enforces it.",
+    "migration": "Delete `.kumiko-text-field-stance-baseline.json` and `.kumiko-section-fields-raw-baseline.json`. In `.kumiko-security-baseline.json` the \"Escape-Hatch-Declared Guard\" and \"Open-To-All-Reason Guard\" entries in `hardFail` can be removed (they are ignored now). Remove leftover `kumiko-lint-ignore section-fields-raw` markers."
+  },
   {
     "version": "0.379.0",
     "type": "improvement",

package/src/guard-error-reasons.ts

@@ -23,7 +23,7 @@
  *      Skips `openToAll: { reason: "..." }` / `escapeHatch: { reason: "..." }`
  *      and `declareEscapeHatch({ reason: "..." })` — those are prose
  *      access-declaration justifications, enforced instead by
- *      guard-open-to-all-reason.ts / guard-escape-hatch-declared.ts.
+ *      the boot validator and the runtime reasonProblem check.
  *
  * Non-literal reasons (computed, template strings with interpolation,
  * identifier references) are assumed to be typed-from-a-const and pass.

package/src/guard-screen-conventions.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env bun
 // Usability mistakes in screen definitions that are statically decidable and
-// otherwise come back screen by screen: a metric without a label, a
-// relatedList section whose rows lead nowhere, a row action labelled "edit"
-// that does something else. Opt-in per app repo via _app-test.yml.
+// otherwise come back screen by screen: a relatedList section whose rows
+// lead nowhere, a row action labelled "edit" that does something else. Opt-in per app repo via _app-test.yml.
 
 import { type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
@@ -56,40 +55,6 @@ function hasDeclaredProperty(obj: ObjectLiteralExpression, name: string): boolea
   return init !== undefined && init.getKind() !== SyntaxKind.UndefinedKeyword;
 }
 
-// R1: MetricSpec's plain-string shorthand carries no label — every metrics
-// entry on a projectionDetail screen must be the object form with `label`.
-function checkMetrics(
-  root: ObjectLiteralExpression,
-  sf: SourceFile,
-  violations: GuardViolation[],
-): void {
-  const metricsProp = root.getProperty("metrics");
-  // skip: screens without a literal metrics array have no entries to check
-  if (!metricsProp?.isKind(SyntaxKind.PropertyAssignment)) return;
-  const init = metricsProp.getInitializer();
-  // skip: a computed metrics value cannot be checked statically
-  if (!init?.isKind(SyntaxKind.ArrayLiteralExpression)) return;
-  for (const el of init.getElements()) {
-    if (hasIgnoreTag(el, IGNORE_TAG)) continue;
-    if (el.isKind(SyntaxKind.StringLiteral)) {
-      violations.push({
-        file: sf.getFilePath(),
-        line: el.getStartLineNumber(),
-        message: `metrics entry "${el.getLiteralValue()}" is a plain string (a number with no meaning) — use the object form with \`label\`.`,
-      });
-      continue;
-    }
-    if (el.isKind(SyntaxKind.ObjectLiteralExpression) && !hasDeclaredProperty(el, "label")) {
-      violations.push({
-        file: sf.getFilePath(),
-        line: el.getStartLineNumber(),
-        message:
-          "metrics entry without `label` (a number with no meaning) — the object form needs a label.",
-      });
-    }
-  }
-}
-
 // R2: a relatedList section with neither rowClick nor rowActions renders a
 // list nobody can act on.
 function checkRelatedListSections(
@@ -142,8 +107,8 @@ export const guard: AstGuard = {
   name: "Screen-Conventions Guard",
   scan: SCAN,
   hint:
-    "metrics entries need the object form with `label`; relatedList sections need " +
-    '`rowClick` or `rowActions`; a rowAction label must not end in ".action.edit" ' +
+    "relatedList sections need `rowClick` or `rowActions`; a rowAction label " +
+    'must not end in ".action.edit" ' +
     'when the `id` is not "edit". ' +
     `Justified exception: // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
@@ -151,7 +116,6 @@ export const guard: AstGuard = {
     for (const sf of files) {
       if (EXCLUDE.test(sf.getFilePath())) continue;
       for (const root of findScreenObjectLiterals(sf)) {
-        checkMetrics(root, sf, violations);
         checkRelatedListSections(root, sf, violations);
         checkRowActions(root, sf, violations);
       }

package/src/run-guards.ts

@@ -25,14 +25,11 @@ import { guard as complexity } from "./check-complexity";
 import { guard as predicateExtraction } from "./check-predicates";
 import { guard as accessDeniedTest } from "./guard-access-denied-test";
 import { guard as adminApi } from "./guard-admin-api";
-import { guard as apiObjectForm } from "./guard-api-object-form";
 import { guard as appFeatureStructure } from "./guard-app-feature-structure";
-import { guard as brokerSubscribe } from "./guard-broker-subscribe";
 import { guard as crossFeatureImports } from "./guard-cross-feature-imports";
 import { guard as directEntityWrites } from "./guard-direct-entity-writes";
 import { guard as directFetch } from "./guard-direct-fetch";
 import { guard as errorReasons } from "./guard-error-reasons";
-import { guard as escapeHatchDeclared } from "./guard-escape-hatch-declared";
 import { guard as eventStoreWrites } from "./guard-event-store-writes";
 import { guard as fakeTests } from "./guard-fake-tests";
 import { guard as htmlEscape } from "./guard-html-escape";
@@ -41,23 +38,17 @@ import { guard as i18nLocaleMount } from "./guard-i18n-locale-mount";
 import { guard as i18nLocaleTerminology } from "./guard-i18n-locale-terminology";
 import { guard as importExtensions } from "./guard-import-extensions";
 import { guard as libTestCoverage } from "./guard-lib-test-coverage";
-import { guard as loadallEvents } from "./guard-loadall-events";
 import { guard as noDateApi } from "./guard-no-date-api";
 import { guard as noDirectFs } from "./guard-no-direct-fs";
 import { guard as noLogicInViews } from "./guard-no-logic-in-views";
 import { guard as noTemporalPolyfillImport } from "./guard-no-temporal-polyfill-import";
-import { guard as openToAllReason } from "./guard-open-to-all-reason";
 import { guard as piiAnnotations } from "./guard-pii-annotations";
-import { guard as preEsPatterns } from "./guard-pre-es-patterns";
 import { guard as restrictedSymbols } from "./guard-restricted-symbols";
 import { guard as screenConventions } from "./guard-screen-conventions";
-import { guard as sectionFieldsRaw } from "./guard-section-fields-raw";
 import { guard as silentSkip } from "./guard-silent-skip";
-import { guard as tableDdl } from "./guard-table-ddl";
 import { guard as tenantEscalation } from "./guard-tenant-escalation";
 import { guard as testTemplateDrift } from "./guard-test-template-drift";
 import { guard as testTimeouts } from "./guard-test-timeouts";
-import { guard as textFieldStance } from "./guard-text-field-stance";
 import { guard as unsafeAppendEvent } from "./guard-unsafe-append-event";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
 import { guard as writeHandlerQns } from "./guard-write-handler-qns";
@@ -65,14 +56,10 @@ import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 export const GUARDS = [
   accessDeniedTest,
   adminApi,
-  apiObjectForm,
   directEntityWrites,
   directFetch,
-  escapeHatchDeclared,
   noDirectFs,
-  openToAllReason,
   tenantEscalation,
-  preEsPatterns,
   unsafeJsonParse,
   silentSkip,
   htmlEscape,
@@ -83,22 +70,17 @@ export const GUARDS = [
   restrictedSymbols,
   fakeTests,
   noLogicInViews,
-  brokerSubscribe,
   errorReasons,
   i18nKeys,
   i18nLocaleMount,
   i18nLocaleTerminology,
   piiAnnotations,
-  textFieldStance,
   complexity,
   predicateExtraction,
   screenConventions,
-  sectionFieldsRaw,
   writeHandlerQns,
   asCasts,
-  loadallEvents,
   eventStoreWrites,
-  tableDdl,
   appFeatureStructure,
   libTestCoverage,
   testTimeouts,

package/src/guard-api-object-form.ts

@@ -1,211 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard: the registrar methods `r.writeHandler`, `r.queryHandler`, `r.entity`,
- * `r.requires` and `r.hook` only take the object form; `registerEntityCrud(r, …)`
- * is replaced by `r.crud(…)`.
- *
- * The positional-shape and receiver rules mirror the object-form codemod in
- * kumiko-framework (scripts/codemod/object-form.ts). This package does not
- * depend on the framework, so the two copies are held together by the parity
- * test in __tests__/guard-api-object-form.test.ts.
- *
- * Usage:
- *   bun guards/guard-api-object-form.ts
- */
-import {
-  type CallExpression,
-  Node,
-  type ParameterDeclaration,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
-import {
-  type AstGuard,
-  type GuardViolation,
-  relativeToCwd,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-
-const SCAN: ScanSpec = {
-  scope: "source+tests",
-  extensions: ["ts", "tsx"],
-  frameworkWithin: ["packages/*/src/**", "samples/**"],
-};
-
-const REGISTRAR_METHODS = ["writeHandler", "queryHandler", "entity", "requires", "hook"] as const;
-type RegistrarMethod = (typeof REGISTRAR_METHODS)[number];
-
-const CRUD_FUNCTION_NAME = "registerEntityCrud";
-const REGISTRAR_TYPE_MARKER = "FeatureRegistrar";
-const FEATURE_FACTORY_NAME = "defineFeature";
-const REGISTRAR_RECEIVER_NAMES: ReadonlySet<string> = new Set(["r", "registrar"]);
-const EXCLUDED_PATH = /(\/__tests__\/fixtures\/|\.d\.ts$)/;
-// Cheap text superset of what positionalCallMethod can match; skips the AST walk for most files.
-const REGISTRAR_METHOD_ACCESS = new RegExp(`\\.\\s*(?:${REGISTRAR_METHODS.join("|")})\\b`);
-const UPGRADE_HINT = "run `bun kumiko-upgrade --apply` (codemod object-form)";
-
-type ReceiverResolution = "registrar" | "other" | "unresolved";
-
-function isRegistrarMethod(name: string): name is RegistrarMethod {
-  return REGISTRAR_METHODS.some((method) => method === name);
-}
-
-function isFeatureFactoryCallee(callee: Node): boolean {
-  if (Node.isIdentifier(callee)) return callee.getText() === FEATURE_FACTORY_NAME;
-  if (Node.isPropertyAccessExpression(callee)) return callee.getName() === FEATURE_FACTORY_NAME;
-  return false;
-}
-
-function isFeatureCallbackParameter(param: ParameterDeclaration): boolean {
-  const fn = param.getParent();
-  if (!Node.isArrowFunction(fn) && !Node.isFunctionExpression(fn)) return false;
-  if (fn.getParameters()[0] !== param) return false;
-  const call = fn.getParentIfKind(SyntaxKind.CallExpression);
-  return (
-    call !== undefined &&
-    call.getArguments()[1] === fn &&
-    isFeatureFactoryCallee(call.getExpression())
-  );
-}
-
-function resolveParameter(param: ParameterDeclaration): ReceiverResolution {
-  if (isFeatureCallbackParameter(param)) return "registrar";
-  const typeNode = param.getTypeNode();
-  if (typeNode === undefined) return "unresolved";
-  return typeNode.getText().includes(REGISTRAR_TYPE_MARKER) ? "registrar" : "other";
-}
-
-function declaredVariableIn(scope: Node, name: string): ReceiverResolution | undefined {
-  if (!Node.isBlock(scope) && !Node.isSourceFile(scope) && !Node.isModuleBlock(scope)) {
-    return undefined;
-  }
-  for (const statement of scope.getStatements()) {
-    if (!Node.isVariableStatement(statement)) continue;
-    for (const declaration of statement.getDeclarations()) {
-      if (declaration.getNameNode().getText() !== name) continue;
-      const typeText = declaration.getTypeNode()?.getText();
-      if (typeText === undefined) return "unresolved";
-      return typeText.includes(REGISTRAR_TYPE_MARKER) ? "registrar" : "other";
-    }
-  }
-  return undefined;
-}
-
-// Nearest binding of the receiver's name decides; no type checker involved.
-function resolveReceiver(receiver: Node): ReceiverResolution {
-  if (!Node.isIdentifier(receiver)) return "other";
-  const name = receiver.getText();
-  for (
-    let scope: Node | undefined = receiver.getParent();
-    scope !== undefined;
-    scope = scope.getParent()
-  ) {
-    if (Node.isParametered(scope)) {
-      const param = scope.getParameters().find((p) => p.getNameNode().getText() === name);
-      if (param !== undefined) return resolveParameter(param);
-    }
-    const variable = declaredVariableIn(scope, name);
-    if (variable !== undefined) return variable;
-  }
-  return "unresolved";
-}
-
-function isRegistrarOrLookalike(receiver: Node): boolean {
-  const resolution = resolveReceiver(receiver);
-  if (resolution === "registrar") return true;
-  return (
-    resolution === "unresolved" &&
-    Node.isIdentifier(receiver) &&
-    REGISTRAR_RECEIVER_NAMES.has(receiver.getText())
-  );
-}
-
-function isPositionalShape(method: RegistrarMethod, args: readonly Node[]): boolean {
-  if (method === "requires") return args.some((arg) => !Node.isObjectLiteralExpression(arg));
-  if (args.some((arg) => Node.isSpreadElement(arg))) return true;
-  return args.length >= (method === "hook" ? 3 : 2);
-}
-
-function crudLocalNames(sf: SourceFile): Set<string> {
-  const names = new Set<string>([CRUD_FUNCTION_NAME]);
-  for (const specifier of sf.getDescendantsOfKind(SyntaxKind.ImportSpecifier)) {
-    if (specifier.getName() !== CRUD_FUNCTION_NAME) continue;
-    names.add(specifier.getAliasNode()?.getText() ?? CRUD_FUNCTION_NAME);
-  }
-  return names;
-}
-
-function positionalCallMethod(call: CallExpression): RegistrarMethod | undefined {
-  const callee = call.getExpression();
-  if (!Node.isPropertyAccessExpression(callee)) return undefined;
-  const method = callee.getName();
-  if (!isRegistrarMethod(method)) return undefined;
-  if (!isPositionalShape(method, call.getArguments())) return undefined;
-  return isRegistrarOrLookalike(callee.getExpression()) ? method : undefined;
-}
-
-export type ObjectFormFinding = { file: string; line: number; message: string };
-
-function positionalCallFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
-  if (!REGISTRAR_METHOD_ACCESS.test(sf.getFullText())) return [];
-  const out: ObjectFormFinding[] = [];
-  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const method = positionalCallMethod(call);
-    if (method === undefined) continue;
-    out.push({
-      file,
-      line: call.getStartLineNumber(),
-      message: `positional r.${method}(…) removed in 0.366 — ${UPGRADE_HINT}`,
-    });
-  }
-  return out;
-}
-
-function crudFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
-  // Every crud local name is CRUD_FUNCTION_NAME itself or an import alias of it.
-  if (!sf.getFullText().includes(CRUD_FUNCTION_NAME)) return [];
-  const crudNames = crudLocalNames(sf);
-  const out: ObjectFormFinding[] = [];
-  for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
-    if (!crudNames.has(id.getText())) continue;
-    const parent = id.getParent();
-    const isCall = Node.isCallExpression(parent) && parent.getExpression() === id;
-    const isImportOrExport =
-      Node.isImportSpecifier(parent) ||
-      Node.isExportSpecifier(parent) ||
-      id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration) !== undefined;
-    if (!isCall && !isImportOrExport) continue;
-    if (Node.isImportSpecifier(parent) && parent.getAliasNode() === id) continue;
-    out.push({
-      file,
-      line: id.getStartLineNumber(),
-      message: `registerEntityCrud removed in 0.366 — use r.crud(…); ${UPGRADE_HINT}`,
-    });
-  }
-  return out;
-}
-
-export function findPositionalRegistrarCalls(files: readonly SourceFile[]): ObjectFormFinding[] {
-  const out: ObjectFormFinding[] = [];
-  for (const sf of files) {
-    if (EXCLUDED_PATH.test(sf.getFilePath())) continue;
-    const file = relativeToCwd(sf.getFilePath());
-    out.push(...positionalCallFindings(sf, file), ...crudFindings(sf, file));
-  }
-  return out;
-}
-
-export const guard: AstGuard = {
-  name: "API-Object-Form Guard",
-  scan: SCAN,
-  hint: "Run `bun kumiko-upgrade --apply` (codemod object-form) or rewrite the call to the object form by hand; registerEntityCrud(r, …) becomes r.crud(…).",
-  run(files) {
-    const violations: GuardViolation[] = findPositionalRegistrarCalls(files);
-    return { violations };
-  },
-};
-
-if (import.meta.main) {
-  runStandalone(guard);
-}

package/src/guard-broker-subscribe.ts

@@ -1,99 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard R8: forbids `broker.subscribe(...)` outside the framework.
- *
- * Feature and app code must NEVER subscribe to the event broker directly — the
- * registrar API is the only allowed way to consume events:
- *   - `r.onEvent("event-name", handler)`
- *   - `r.job({ trigger: { on: "event-name" }, handler })`
- *
- * A direct `broker.subscribe(...)` bypasses lifecycle, idempotency, dedup
- * and replay of the dispatcher — exactly the guarantees the registrar API
- * gives. Today there is NO such call in the Kumiko code (the broker is
- * framework-internal, not exported) — the guard is a tripwire that fires as
- * soon as someone introduces a broker abstraction and hooks feature code
- * directly onto it.
- *
- * Detection (name heuristic, no type resolution): `X.subscribe(...)` where the
- * terminal identifier of `X` is `broker` or `eventBroker` (case-
- * insensitive — catches `broker`, `eventBroker`, `ctx.broker`, `this.eventBroker`).
- * Store/observable `.subscribe` (RxJS, React `controller.subscribe`) is not
- * named `broker` → no hit.
- *
- * Exception: `packages/framework/src/pipeline/**` — the broker plumbing
- * itself lives there (framework-internal, allowed).
- *
- * Usage: bun guards/guard-broker-subscribe.ts
- * Exit 1 on a finding, 0 when clean.
- */
-
-import * as path from "node:path";
-import { type SourceFile, SyntaxKind } from "ts-morph";
-import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
-
-const ROOT = process.cwd();
-
-const SCAN: ScanSpec = {
-  scope: "source",
-  extensions: ["ts"],
-  frameworkWithin: ["packages/*/src/**", "samples/**"],
-};
-
-const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|\.g\.ts$)/;
-
-// Broker-Plumbing selbst — framework-intern, darf subscriben.
-const ALLOW = /(^|\/)packages\/framework\/src\/pipeline\//;
-
-const BROKER_RECEIVER = /^(event)?broker$/i;
-
-export function isAllowed(filePath: string): boolean {
-  return ALLOW.test(path.relative(ROOT, filePath));
-}
-
-/** Terminaler Bezeichner einer Receiver-Expression: `ctx.eventBroker` → "eventBroker". */
-function receiverName(node: import("ts-morph").Node): string | undefined {
-  if (node.getKind() === SyntaxKind.Identifier) return node.getText();
-  const pae = node.asKind(SyntaxKind.PropertyAccessExpression);
-  return pae?.getName();
-}
-
-export function collectBrokerSubscribeViolations(
-  sf: SourceFile,
-): Array<{ line: number; message: string }> {
-  const hits: Array<{ line: number; message: string }> = [];
-  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const callee = call.getExpression();
-    const pae = callee.asKind(SyntaxKind.PropertyAccessExpression);
-    if (pae?.getName() !== "subscribe") continue;
-    const recv = receiverName(pae.getExpression());
-    if (!recv || !BROKER_RECEIVER.test(recv)) continue;
-    hits.push({
-      line: call.getStartLineNumber(),
-      message: `[${recv}.subscribe] ${recv}.subscribe(...) — use r.onEvent(...) or r.job({ trigger: { on } })`,
-    });
-  }
-  return hits;
-}
-
-export const guard: AstGuard = {
-  name: "No-Broker-Subscribe Guard",
-  scan: SCAN,
-  hint: "Consume events through the registrar API (r.onEvent / r.job trigger.on), not directly on the broker — see docs/plans/architecture/lint-rules.md (R8).",
-  run(files) {
-    const violations: Array<{ file: string; line: number; message: string }> = [];
-    for (const sf of files) {
-      const file = sf.getFilePath();
-      if (EXCLUDE.test(file) || isAllowed(file)) continue;
-      for (const hit of collectBrokerSubscribeViolations(sf)) {
-        violations.push({
-          file: path.relative(ROOT, file),
-          line: hit.line,
-          message: hit.message,
-        });
-      }
-    }
-    return { violations };
-  },
-};
-
-if (import.meta.main) runStandalone(guard);