@cosmicdrift/kumiko-guards 0.1.1 → 0.281.0

package/src/guard-admin-api.ts

@@ -111,7 +111,7 @@ export const guard: AstGuard = {
   scan: SCAN,
   // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline there too (infra#502).
   security: true,
-  hint: "Admin-API (appendRaw/appendRawBatch) umgeht die Pipeline — erlaubt nur in samples/*/migration/ oder scripts/migrations/. Für Domain-Events: ctx.appendEvent / write-Handler.",
+  hint: "Admin API (appendRaw/appendRawBatch) bypasses the pipeline — only allowed in samples/*/migration/ or scripts/migrations/. For domain events: ctx.appendEvent / write handler.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-app-feature-structure.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env bun
+// App-Features folgen der bundled-features-Konvention (Referenz: tenant/):
+// feature.ts = nur Registrierung, Screens unter web/, Handler unter handlers/.
+// Dieser Guard flaggt die drei teuersten Abweichungen:
+//   1. web.tsx/web.ts-Monolith bzw. JSX-Screens direkt am Feature-Root
+//   2. feature.ts als Logik-Dump (> MAX_FEATURE_TS_LINES Zeilen)
+//   3. r.screen({ type: "custom" }) ohne Allowlist-Tag — deklarative
+//      Screen-Typen (entityList/dashboard/data-table) sind der Default.
+//
+// ponytail: Handler-Datei-Konvention (*.query.ts/*.write.ts unter handlers/)
+// wird noch nicht erzwungen — nachziehen, wenn die Registrierungs-API-Formen
+// stabil inventarisiert sind.
+//
+// Teil von App-Mounting 2.0 (infra#208).
+
+import * as path from "node:path";
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  within: ["features/**"],
+  frameworkWithin: ["packages/bundled-features/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore app-feature-structure";
+
+const MAX_FEATURE_TS_LINES = 300;
+
+// src/features/<name>/<file> bzw. packages/bundled-features/src/<name>/<file>
+// — genau eine Ebene unter dem Feature-Ordner.
+function isFeatureRootFile(filePath: string): boolean {
+  const m = filePath.match(/(src\/features|packages\/bundled-features\/src)\/[^/]+\/[^/]+$/);
+  return m !== null;
+}
+
+export const guard: AstGuard = {
+  name: "App-Feature-Structure Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    "Konvention: feature.ts nur Registrierung, Screens unter web/ (eine Datei pro Screen), Handler unter handlers/, " +
+    `Domain-Logik unter lib/. Custom-Screens brauchen // ${IGNORE_TAG} <Grund> (deklarative Screen-Typen sind der Default).`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      const filePath = sf.getFilePath();
+      if (EXCLUDE.test(filePath)) continue;
+      const base = path.basename(filePath);
+
+      // 1a. web.ts(x)-Monolith am Feature-Root
+      if (isFeatureRootFile(filePath) && (base === "web.tsx" || base === "web.ts")) {
+        if (!hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)) {
+          violations.push({
+            file: filePath,
+            line: 1,
+            message:
+              "web-Monolith am Feature-Root — Screens/Client-Def gehören unter web/ (index.ts + eine Datei pro Screen)",
+          });
+        }
+      }
+
+      // 1b. JSX direkt am Feature-Root (Screens gehören unter web/)
+      if (
+        isFeatureRootFile(filePath) &&
+        filePath.endsWith(".tsx") &&
+        base !== "web.tsx" &&
+        sf.getDescendantsOfKind(SyntaxKind.JsxElement).length +
+          sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).length >
+          0 &&
+        !hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)
+      ) {
+        violations.push({
+          file: filePath,
+          line: 1,
+          message: "JSX-Komponente am Feature-Root — unter web/ verschieben",
+        });
+      }
+
+      // 2. feature.ts als Logik-Dump
+      if (base === "feature.ts" && isFeatureRootFile(filePath)) {
+        const lines = sf.getEndLineNumber();
+        if (lines > MAX_FEATURE_TS_LINES && !hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)) {
+          violations.push({
+            file: filePath,
+            line: 1,
+            message: `feature.ts hat ${lines} Zeilen (max ${MAX_FEATURE_TS_LINES}) — Handler nach handlers/, Schemas nach schema/, Logik nach lib/`,
+          });
+        }
+      }
+
+      // 3. type: "custom" ohne Allowlist-Tag
+      for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+        if (prop.getName() !== "type") continue;
+        const init = prop.getInitializer();
+        if (init === undefined || init.getKind() !== SyntaxKind.StringLiteral) continue;
+        if (init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText() !== "custom") continue;
+        // Nur r.screen-Kontext: das umgebende Call-Target muss auf .screen enden.
+        const call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
+        if (call === undefined || !call.getExpression().getText().endsWith(".screen")) continue;
+        if (hasIgnoreTag(call, IGNORE_TAG) || hasIgnoreTag(prop, IGNORE_TAG)) continue;
+        violations.push({
+          file: filePath,
+          line: prop.getStartLineNumber(),
+          message: `r.screen type:"custom" ohne Allowlist-Tag — deklarativen Screen-Typ nutzen oder // ${IGNORE_TAG} <Grund>`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-broker-subscribe.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+/**
+ * Guard R8: verbietet `broker.subscribe(...)` ausserhalb des Frameworks.
+ *
+ * Feature- und App-Code soll NIE direkt an den Event-Broker subscriben — die
+ * Registrar-API ist der einzige erlaubte Weg, Events zu konsumieren:
+ *   - `r.onEvent("event-name", handler)`
+ *   - `r.job({ trigger: { on: "event-name" }, handler })`
+ *
+ * Ein direktes `broker.subscribe(...)` umgeht Lifecycle, Idempotency, Dedup
+ * und Replay des Dispatchers — genau die Garantien, die die Registrar-API
+ * gibt. Heute gibt es im Kumiko-Code KEINEN solchen Call (der Broker ist
+ * framework-intern, nicht exportiert) — der Guard ist ein Tripwire, der
+ * zuschlägt, sobald jemand eine Broker-Abstraktion einführt und Feature-Code
+ * direkt daran hängt.
+ *
+ * Erkennung (Name-Heuristik, keine Typ-Resolution): `X.subscribe(...)` wo der
+ * terminale Bezeichner von `X` `broker` oder `eventBroker` heisst (case-
+ * insensitive — fängt `broker`, `eventBroker`, `ctx.broker`, `this.eventBroker`).
+ * Store-/Observable-`.subscribe` (RxJS, React `controller.subscribe`) heisst
+ * nicht `broker` → kein Treffer.
+ *
+ * Ausnahme: `packages/framework/src/pipeline/**` — dort lebt das Broker-
+ * Plumbing selbst (framework-intern, erlaubt).
+ *
+ * Usage: bun guards/guard-broker-subscribe.ts
+ * Exit 1 bei Fund, 0 wenn sauber.
+ */
+
+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 || 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);

package/src/guard-error-reasons.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env bun
+/**
+ * Guard: `details.reason` strings and the first arg to UnprocessableError /
+ * failUnprocessable must follow the reason convention:
+ *
+ *    ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
+ *
+ * That is: lowercase ASCII, underscores for word breaks, optional dot
+ * namespaces for feature-scoped reasons (e.g. `order.already_cancelled`).
+ * No spaces, no camelCase, no dashes, no leading digits.
+ *
+ * Why: reason codes survive the wire + logs + i18n lookup. Clients key off
+ * them. Any drift (camelCase, typos like `stale_stat`) means a missed
+ * branch in the SDK. Catching it at commit time is dramatically cheaper
+ * than discovering a client-side dead branch in prod.
+ *
+ * What this checks:
+ *   1. `new UnprocessableError(X, ...)` — X must be a string-literal reason
+ *      that matches the regex, OR a reference to a known Reasons const
+ *      (FrameworkReasons.*, <Anything>Reasons.*, TenantErrors.*, etc.).
+ *   2. `failUnprocessable(X, ...)` — same rule.
+ *   3. Object literals containing `reason: "X"` — same rule for the X.
+ *      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.
+ *
+ * Non-literal reasons (computed, template strings with interpolation,
+ * identifier references) are assumed to be typed-from-a-const and pass.
+ * A stricter version could walk to the declaration; v1 stays pragmatic.
+ *
+ * Usage:
+ *   bun guards/guard-error-reasons.ts
+ */
+
+import * as path from "node:path";
+import { type Node, 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/**"],
+};
+
+// Excluded: test files (they may legitimately fabricate broken reasons to
+// prove the guard catches them) and the classes.ts / reasons.ts definitions
+// themselves (message text in constructor defaults isn't a reason).
+const EXCLUDE =
+  /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|errors\/classes\.ts$|errors\/reasons\.ts$|node_modules)/;
+
+const REASON_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+
+// Calls whose first positional arg is a reason string.
+const UNPROC_CALL_NAMES = new Set(["UnprocessableError", "failUnprocessable"]);
+
+// Property names whose `{ reason: "..." }` is a prose access-declaration
+// justification, not an error-reason code.
+const ACCESS_DECLARATION_NAMES = new Set(["openToAll", "escapeHatch"]);
+
+interface Violation {
+  readonly file: string;
+  readonly line: number;
+  readonly kind: "unproc-arg" | "details-reason";
+  readonly value: string;
+}
+
+function scanFile(sf: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+
+  // ---------- (1) + (2): UnprocessableError / failUnprocessable calls ----------
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    // Strip `new `, drop qualifying module access. We only need the final
+    // identifier for the call name check.
+    const text = callee.getText();
+    const name = text.split(".").pop() ?? text;
+
+    // Also catch `new UnprocessableError(...)` — ts-morph models that as a
+    // NewExpression, but class-ref-as-callable in our codebase is exercised
+    // only in tests/internal, so the NewExpression pass below handles it.
+    if (!UNPROC_CALL_NAMES.has(name)) continue;
+
+    const arg = call.getArguments()[0];
+    const bad = checkReasonNode(arg);
+    if (bad !== null) {
+      violations.push({
+        file: path.relative(ROOT, sf.getFilePath()),
+        line: call.getStartLineNumber(),
+        kind: "unproc-arg",
+        value: bad,
+      });
+    }
+  }
+
+  for (const neu of sf.getDescendantsOfKind(SyntaxKind.NewExpression)) {
+    const callee = neu.getExpression();
+    const text = callee.getText();
+    const name = text.split(".").pop() ?? text;
+    if (name !== "UnprocessableError") continue;
+
+    const arg = neu.getArguments()[0];
+    const bad = checkReasonNode(arg);
+    if (bad !== null) {
+      violations.push({
+        file: path.relative(ROOT, sf.getFilePath()),
+        line: neu.getStartLineNumber(),
+        kind: "unproc-arg",
+        value: bad,
+      });
+    }
+  }
+
+  // ---------- (3): object literals with `reason: "..."` ----------
+  for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+    const name = prop.getName();
+    if (name !== "reason") continue;
+    if (isAccessDeclarationReason(prop)) continue;
+
+    const initializer = prop.getInitializer();
+    const bad = checkReasonNode(initializer);
+    if (bad !== null) {
+      violations.push({
+        file: path.relative(ROOT, sf.getFilePath()),
+        line: prop.getStartLineNumber(),
+        kind: "details-reason",
+        value: bad,
+      });
+    }
+  }
+
+  return violations;
+}
+
+// A `reason` PropertyAssignment whose object literal is the initializer of
+// an `openToAll` / `escapeHatch` PropertyAssignment, or the sole argument
+// object of a bare `declareEscapeHatch(...)` call, is an access-declaration
+// justification, not an error-reason code.
+export function isAccessDeclarationReason(prop: Node): boolean {
+  const objectLiteral = prop.getParent();
+  if (!objectLiteral?.isKind(SyntaxKind.ObjectLiteralExpression)) return false;
+  const owner = objectLiteral.getParent();
+  if (owner?.isKind(SyntaxKind.PropertyAssignment)) {
+    return ACCESS_DECLARATION_NAMES.has(owner.getName());
+  }
+  if (owner?.isKind(SyntaxKind.CallExpression)) {
+    const callee = owner.getExpression();
+    return callee.isKind(SyntaxKind.Identifier) && callee.getText() === "declareEscapeHatch";
+  }
+  return false;
+}
+
+// Returns the offending string if this node is a string literal that does
+// NOT match the reason regex; null otherwise (including for non-literals —
+// those are assumed to come from a typed const and slip through).
+function checkReasonNode(node: Node | undefined): string | null {
+  if (!node) return null;
+  if (node.isKind(SyntaxKind.StringLiteral)) {
+    const lit = node.getLiteralText();
+    return REASON_RE.test(lit) ? null : lit;
+  }
+  if (node.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
+    const lit = node.getLiteralText();
+    return REASON_RE.test(lit) ? null : lit;
+  }
+  return null;
+}
+
+export const guard: AstGuard = {
+  name: "Error-Reasons Guard",
+  scan: SCAN,
+  hint: `reason strings must match ${REASON_RE} (snake_case ASCII, optional dot-namespaced). Reusable? Add a const to FrameworkReasons/<Feature>Reasons.`,
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const v of scanFile(sf)) {
+        const where =
+          v.kind === "unproc-arg" ? "UnprocessableError/failUnprocessable" : "details.reason";
+        violations.push({
+          file: v.file,
+          line: v.line,
+          message: `${where} "${v.value}"`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);