@cosmicdrift/kumiko-guards 0.365.1 → 0.367.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.365.1",
+  "version": "0.367.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.365.1",
+    "@cosmicdrift/kumiko-repo-manifest": "0.367.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "kumiko-guards gains the api-object-form guard",
+    "detail": "The guard fails on a positional r.writeHandler, r.queryHandler, r.entity, r.requires or r.hook call and on registerEntityCrud, and names the object form to use. It runs with the default kumiko-guards checks. The direct-entity-writes guard now also reads entity registrations written in the object form, including a backingTable override."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

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

@@ -0,0 +1,197 @@
+#!/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$)/;
+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 };
+
+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());
+    const crudNames = crudLocalNames(sf);
+
+    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}`,
+      });
+    }
+
+    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 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-direct-entity-writes.ts

@@ -10,13 +10,13 @@
  *   1. **Collect ES tables.** Two sources:
  *      a) All `createEventStoreExecutor(<tableExpr>, <entity>, ...)` calls;
  *         `<tableExpr>` is the projection table (identifier).
- *      b) All `r.entity(<name>, <entityDef>)` registrations: every `r.entity`
- *         is a rebuildable implicit projection. The corresponding Drizzle
- *         table is linked via the SHARED entity-def identifier, NOT via a
- *         name string — `r.entity("user-session", ent)` and
+ *      b) All `r.entity({ name, ...<entityDef> })` registrations: every
+ *         `r.entity` is a rebuildable implicit projection. The corresponding
+ *         Drizzle table is linked via the SHARED entity-def identifier, NOT via
+ *         a name string — `r.entity({ name: "user-session", ...ent })` and
  *         `buildEntityTable("user_session", ent)` disagree on the name
  *         (dash vs. underscore) but share the `ent` symbol. Plus an explicit
- *         `{ table }` override. Tables that are NOT statically resolvable
+ *         `backingTable` override. Tables that are NOT statically resolvable
  *         are skipped (a miss is preferable to a false block).
  *
  *   2. **Find direct writes.** Two forms:
@@ -44,7 +44,14 @@
  */
 
 import * as path from "node:path";
-import { type CallExpression, type Identifier, Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type CallExpression,
+  type Identifier,
+  Node,
+  type ObjectLiteralExpression,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
@@ -188,16 +195,27 @@ function unwrappedIdentifierDeclId(node: Node | undefined): TableId | undefined
   return identifier ? declIdOf(identifier) : undefined;
 }
 
-// The `{ table }` override of `r.entity(name, def, { table })`.
-function entityTableOverrideId(opts: Node | undefined): TableId | undefined {
-  if (opts?.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
-  const tableProp = opts.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperty("table");
+// The `backingTable` override of `r.entity({ name, ...def, backingTable })`.
+function entityTableOverrideId(definition: ObjectLiteralExpression): TableId | undefined {
+  const tableProp = definition.getProperty("backingTable");
   if (tableProp?.getKind() !== SyntaxKind.PropertyAssignment) return undefined;
   return unwrappedIdentifierDeclId(
     tableProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer(),
   );
 }
 
+// The entity definition spread into `r.entity({ name, ...def })`.
+function spreadEntityDefinitionId(definition: ObjectLiteralExpression): TableId | undefined {
+  for (const property of definition.getProperties()) {
+    if (property.getKind() !== SyntaxKind.SpreadAssignment) continue;
+    const spreadId = unwrappedIdentifierDeclId(
+      property.asKindOrThrow(SyntaxKind.SpreadAssignment).getExpression(),
+    );
+    if (spreadId) return spreadId;
+  }
+  return undefined;
+}
+
 type EntityRegistration = {
   readonly entityDid: TableId | undefined;
   readonly overrideTableDid: TableId | undefined;
@@ -209,11 +227,14 @@ function entityRegistrationOf(call: CallExpression): EntityRegistration | undefi
   if (expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName() !== "entity") {
     return undefined;
   }
-  const args = call.getArguments();
-  if (!args[0] || args[0].getKind() !== SyntaxKind.StringLiteral) return undefined;
+  const definition = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+  const nameProp = definition?.getProperty("name");
+  if (!definition || nameProp?.getKind() !== SyntaxKind.PropertyAssignment) return undefined;
+  const nameValue = nameProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
+  if (nameValue?.getKind() !== SyntaxKind.StringLiteral) return undefined;
   return {
-    entityDid: unwrappedIdentifierDeclId(args[1]),
-    overrideTableDid: entityTableOverrideId(args[2]),
+    entityDid: spreadEntityDefinitionId(definition),
+    overrideTableDid: entityTableOverrideId(definition),
   };
 }
 
@@ -230,7 +251,7 @@ function rebuildableEntityTableDeclId(
   return declIdOf(nameNode.asKindOrThrow(SyntaxKind.Identifier));
 }
 
-// Tables registered via `r.entity(name, entityDef)` as a rebuildable implicit
+// Tables registered via `r.entity({ name, ...entityDef })` as a rebuildable implicit
 // projection, linked entity→table via the shared entity-def symbol (see header), not by name string.
 export function collectEntityProjectionTables(files: readonly SourceFile[]): Set<TableId> {
   const rebuildableEntities = new Set<TableId>();

package/src/run-guards.ts

@@ -24,6 +24,7 @@ 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";
@@ -61,6 +62,7 @@ import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 export const GUARDS = [
   accessDeniedTest,
   adminApi,
+  apiObjectForm,
   directEntityWrites,
   directFetch,
   escapeHatchDeclared,

package/src/runtime-isolation-classify.ts

@@ -44,7 +44,7 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
   const rel = repoRelativePath.replace(/\\/g, "/");
   if (/\/(__tests__|testing)\//.test(rel)) return "test";
   if (/\/testing\.tsx?$/.test(rel)) return "test";
-  if (/\.(test|integration|e2e)\.[tj]sx?$/.test(rel)) return "test";
+  if (/\.(test|integration|e2e|spec)\.[tj]sx?$/.test(rel)) return "test";
   if (/(?:^|\/)scripts\//.test(rel)) return "tooling";
   if (/(?:^|\/)bin\//.test(rel)) return "tooling";
   if (/\/drizzle\/[^/]+\.ts$/.test(rel)) return "tooling";