@cosmicdrift/kumiko-guards 0.1.0

package/src/guard-no-logic-in-views.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+// web/ contains components and hooks — computation, parsing and aggregation
+// belong in lib/ (with a test). This guard flags top-level functions in
+// web/**/*.tsx that "compute" (control flow, local bindings, or a domain
+// call in the return) but are NEITHER a component (JSX return) NOR a hook
+// (use*) NOR a type guard (x is T). Pure single-return predicates stay
+// allowed (typeof/comparisons without a call).
+//
+// Motivation: coverage thresholds don't see web/ (lib-only), and that's
+// exactly where untested computation logic hides in 400-line screens. This
+// guard is the structural counterpart — it makes logic-in-views visible and
+// forces extraction into lib/.
+
+import {
+  type ArrowFunction,
+  type FunctionDeclaration,
+  type FunctionExpression,
+  Node,
+  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: ["tsx"],
+  within: ["**/web/**"],
+  frameworkWithin: ["samples/apps/*/src/**/web/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore no-logic-in-views";
+
+type Callable = FunctionDeclaration | ArrowFunction | FunctionExpression;
+
+function containsJsx(fn: Callable): boolean {
+  return (
+    fn.getDescendantsOfKind(SyntaxKind.JsxElement).length > 0 ||
+    fn.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).length > 0 ||
+    fn.getDescendantsOfKind(SyntaxKind.JsxFragment).length > 0
+  );
+}
+
+function isHookName(name: string): boolean {
+  return /^use[A-Z0-9]/.test(name);
+}
+
+// React convention: PascalCase = component. In web/ these are render
+// functions (including cell renderers that return a formatted string
+// instead of a JSX element) — not an extraction candidate. camelCase
+// functions are helpers/logic.
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+// Type guard (x is T) or boolean return → predicate/guard, not an
+// extraction candidate. The boolean case covers predicates that use
+// primitive methods (d.name.trim().length > 0) without having to
+// distinguish method calls from domain calls — the return semantics
+// "decision" is the signal.
+function isPredicate(fn: Callable): boolean {
+  const rt = fn.getReturnTypeNode();
+  if (rt?.getKind() === SyntaxKind.TypePredicate) return true;
+  if (rt?.getKind() === SyntaxKind.BooleanKeyword) return true;
+  // No explicit `: boolean` — check the inferred return type instead,
+  // otherwise unannotated predicates with a primitive method in the return
+  // (e.g. `function isReady(d) { return d.name.trim().length > 0 }`) fall
+  // through and get flagged as view logic incorrectly.
+  if (rt === undefined) return fn.getReturnType().isBoolean();
+  return false;
+}
+
+// A call in the return distinguishes the delegator/computation (summarize →
+// summarizeScenario(...)) from the pure predicate (typeof x === "number" && …).
+function hasCall(node: Node): boolean {
+  return (
+    node.getKind() === SyntaxKind.CallExpression ||
+    node.getDescendantsOfKind(SyntaxKind.CallExpression).length > 0
+  );
+}
+
+// Trivial = a single `return <expr>` without a call. Multiple statements,
+// local bindings and control flow are per se not a single-return form and
+// therefore automatically fall through (→ logic).
+function isTrivialPredicate(fn: Callable): boolean {
+  const body = fn.getBody();
+  if (body === undefined) return true;
+  if (Node.isBlock(body)) {
+    const stmts = body.getStatements();
+    if (stmts.length !== 1) return false;
+    const only = stmts[0];
+    if (only === undefined || !Node.isReturnStatement(only)) return false;
+    const expr = only.getExpression();
+    return expr === undefined || !hasCall(expr);
+  }
+  // Expression-bodied arrow: const isX = (v) => v > 0
+  return !hasCall(body);
+}
+
+function isViewLogic(name: string, fn: Callable): boolean {
+  if (isHookName(name)) return false;
+  if (isComponentName(name) || containsJsx(fn)) return false;
+  if (isPredicate(fn)) return false;
+  return !isTrivialPredicate(fn);
+}
+
+function topLevelCallables(sf: SourceFile): { name: string; fn: Callable }[] {
+  const out: { name: string; fn: Callable }[] = [];
+  for (const fd of sf.getFunctions()) {
+    out.push({ name: fd.getName() ?? "", fn: fd });
+  }
+  for (const vs of sf.getVariableStatements()) {
+    for (const decl of vs.getDeclarations()) {
+      const init = decl.getInitializer();
+      if (init !== undefined && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+        out.push({ name: decl.getName(), fn: init });
+      }
+    }
+  }
+  return out;
+}
+
+export const guard: AstGuard = {
+  name: "No-Logic-in-Views Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    "Berechnung/Parsing/Aggregation gehört nach lib/ (mit Test) — web/ enthält nur " +
+    `Komponenten und Hooks. Begründete Ausnahme: // ${IGNORE_TAG} <Grund>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const { name, fn } of topLevelCallables(sf)) {
+        if (name === "" || !isViewLogic(name, fn)) continue;
+        if (hasIgnoreTag(fn, IGNORE_TAG)) continue;
+        violations.push({
+          file: sf.getFilePath(),
+          line: fn.getStartLineNumber(),
+          message: `View-Logik "${name}" gehört nach lib/ (mit Test) — web/ nur Komponenten/Hooks`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-no-raw-hooks.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env bun
+// Rerender protection: raw useEffect/useLayoutEffect + fetch() in app
+// screens are the source of the endless-rerender class (unstable deps,
+// setState-in-effect) and bypass the framework hook set (useQuery/
+// useMutation/useDisclosure — useQuery can go live via SSE). Endless
+// rerenders aren't reliably detectable statically; the guard eliminates the
+// pattern that produces them.
+//
+// Local UI state via useState stays allowed.
+//
+// Part of App-Mounting 2.0 (infra#208).
+
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+// Match property/identifier names instead of call text — otherwise
+// namespace-/alias-qualified calls (`React.useEffect(...)`, a renamed
+// import `useEffect as useFx`) slip through, because getText() returns the
+// full expression ("React.useEffect") instead of just the banned name.
+function calleeName(expr: import("ts-morph").Node): string {
+  if (Node.isPropertyAccessExpression(expr)) return expr.getName();
+  return expr.getText();
+}
+
+// Only component files in web/public code. API clients (*.ts) stay out of
+// scope — they encapsulate fetch deliberately in one place.
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["tsx"],
+  within: ["**/web/**", "public/**"],
+  frameworkWithin: ["packages/bundled-features/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore no-raw-hooks";
+
+const BANNED_HOOKS = new Set(["useEffect", "useLayoutEffect"]);
+
+export const guard: AstGuard = {
+  name: "No-Raw-Hooks Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    "Framework-Hook-Satz nutzen: useQuery (live: true für SSE), useMutation, useDisclosure. " +
+    `Echter Sonderfall (DOM-Integration o.ä.): // ${IGNORE_TAG} <Grund>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        const name = calleeName(callee);
+        if (BANNED_HOOKS.has(name)) {
+          if (hasIgnoreTag(call, IGNORE_TAG)) continue;
+          violations.push({
+            file: sf.getFilePath(),
+            line: call.getStartLineNumber(),
+            message: `${name} in App-Screen — Framework-Hooks nutzen (useQuery/useMutation/useDisclosure)`,
+          });
+          continue;
+        }
+        if (name === "fetch") {
+          if (hasIgnoreTag(call, IGNORE_TAG)) continue;
+          violations.push({
+            file: sf.getFilePath(),
+            line: call.getStartLineNumber(),
+            message:
+              "fetch() in App-Screen — useQuery/useMutation bzw. einen Api-Client (*.ts) nutzen",
+          });
+        }
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-open-to-all-reason.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+/**
+ * Guard: `openToAll` access declarations need a real reason.
+ *
+ * The framework boot validator (access-declarations.ts) already rejects an
+ * empty `reason`, and separately checks `openToAll.personalData` on
+ * query/stream handlers and a PII write that is neither owner-bound nor
+ * declares `personalData` — none of that is this
+ * guard's job. This guard only catches what the boot validator can't: a
+ * `reason` string that IS non-empty but is a placeholder (`"todo"`,
+ * `"legacy"`, ...), plus the deprecated bare `openToAll: true` shape.
+ *
+ * Usage:
+ *   bun guards/guard-open-to-all-reason.ts
+ *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ */
+import * as path from "node:path";
+import { 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";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+const EXCLUDE = /(__tests__\/|\.test\.tsx?$|\.d\.ts$)/;
+
+function scannableFiles(files: readonly SourceFile[]): SourceFile[] {
+  return files.filter((sf) => !EXCLUDE.test(sf.getFilePath()));
+}
+
+function openToAllPropertyAssignments(sf: SourceFile) {
+  return sf
+    .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
+    .filter((pa) => pa.getName() === "openToAll");
+}
+
+export function findDeprecatedOpenToAll(
+  files: readonly SourceFile[],
+  root: string,
+): { file: string; line: number; message: string }[] {
+  const out: { file: string; line: number; message: string }[] = [];
+  for (const sf of scannableFiles(files)) {
+    for (const pa of openToAllPropertyAssignments(sf)) {
+      if (pa.getInitializer()?.getKind() !== SyntaxKind.TrueKeyword) continue;
+      out.push({
+        file: path.relative(root, sf.getFilePath()),
+        line: pa.getStartLineNumber(),
+        message:
+          'openToAll: true is deprecated — replace with openToAll: { reason: "<why any authenticated user may call this>" } (+ personalData: "tenant-members" for write handlers with unbound personal data).',
+      });
+    }
+  }
+  return out;
+}
+
+export function findGenericOpenToAllReasons(
+  files: readonly SourceFile[],
+  root: string,
+): { file: string; line: number; message: string }[] {
+  const out: { file: string; line: number; message: string }[] = [];
+  for (const sf of scannableFiles(files)) {
+    for (const pa of openToAllPropertyAssignments(sf)) {
+      const init = pa.getInitializer();
+      if (!init?.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
+      const reasonProp = init.getProperty("reason");
+      if (!reasonProp?.isKind(SyntaxKind.PropertyAssignment)) continue;
+      const reasonText = literalReasonText(reasonProp.getInitializer());
+      if (reasonText === undefined) continue;
+      if (reasonText.trim() === "") continue;
+      if (!isGenericReason(reasonText)) continue;
+      out.push({
+        file: path.relative(root, sf.getFilePath()),
+        line: pa.getStartLineNumber(),
+        message: `openToAll: { reason: "${reasonText}" } uses a placeholder reason — give a concrete justification for why any authenticated user may call this.`,
+      });
+    }
+  }
+  return out;
+}
+
+export function createOpenToAllReasonGuard(opts: { root: string }): AstGuard {
+  return {
+    name: "Open-To-All-Reason Guard",
+    scan: SCAN,
+    security: true,
+    hint: 'openToAll: { reason: "<why any authenticated user may call this>" } angeben (+ personalData: "tenant-members" bei Write-Handlern mit nicht gebundenen Personendaten). Baseline nach bewusster Reduktion: `bun guards/run-guards.ts --write-security-baseline`',
+    run(files) {
+      const violations: GuardViolation[] = [
+        ...findGenericOpenToAllReasons(files, opts.root).map((f) => ({
+          file: f.file,
+          line: f.line,
+          message: f.message,
+          neverFrozen: true,
+        })),
+        ...findDeprecatedOpenToAll(files, opts.root).map((f) => ({
+          file: f.file,
+          line: f.line,
+          message: f.message,
+        })),
+      ];
+      return { violations };
+    },
+  };
+}
+
+export const guard = createOpenToAllReasonGuard({ root: process.cwd() });
+
+if (import.meta.main) {
+  runStandalone(guard);
+}

package/src/guard-pre-es-patterns.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env bun
+/**
+ * Guard: finds pre-ES patterns that were removed with the event-sourcing
+ * pivot and must not return.
+ *
+ * Checked patterns:
+ *
+ *   1. `createEventLog` / `EventLog` / `EventLogEntry`
+ *      The Redis-stream-based activity log was replaced by the `events`
+ *      table (postgres). A new import of this symbol is always a mistake —
+ *      the file no longer exists.
+ *
+ *   2. `ctx.emit` / `r.postEvent`
+ *      Before sprint E.2 these were the pubsub-event APIs. Replaced by
+ *      `ctx.appendEvent` (domain event on an aggregate stream) +
+ *      `r.multiStreamProjection` (async cross-aggregate consumers). The
+ *      symbols are gone; a use points at unmigrated code or an old
+ *      copy-paste from an orphaned sample.
+ *
+ *   3. `aggregateType: "configChanges"` as a string literal
+ *      Pre-ES stream from before the config→configValue refactor
+ *      (2026-04-24). Consumers now filter on
+ *      `configValue.created/updated/deleted`. A remaining string literal
+ *      would be a dead subscriber.
+ *
+ *   4. `CONFIG_CHANGED_EVENT_NAME` / `"config:event:config-changed"`
+ *      The pre-ES "config-changed" event was replaced by auto lifecycle
+ *      events.
+ *
+ * Exclude: markdown docs + this guard itself + commit messages. Comments in
+ * TS code are deliberately scanned too — a "this is ok as a reference"
+ * comment allowlist would open the door to revivals. Anyone who genuinely
+ * needs to write about this in a comment uses backticks (`EventLog`) to
+ * avoid the exact symbol, or a different spelling.
+ *
+ * Usage:
+ *   bun guards/guard-pre-es-patterns.ts        (standalone)
+ *   via _lib/guard-kit shared runner            (kumiko check)
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import * as fs from "node:fs";
+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/**"],
+};
+
+// Files that are NOT checked.
+// - dist/ — build output
+// - this guard itself (contains the pattern names in code)
+const EXCLUDE = /(^|\/)(dist|node_modules)\/|guard-pre-es-patterns\.ts$/;
+
+type Pattern = {
+  readonly name: string;
+  readonly description: string;
+  readonly check: (sf: SourceFile) => Array<{ line: number; snippet: string }>;
+};
+
+// Identifier scan: checks whether a given name is used anywhere as an
+// identifier in the AST (not in strings, not in comments).
+function identifierHits(sf: SourceFile, name: string): Array<{ line: number; snippet: string }> {
+  const out: Array<{ line: number; snippet: string }> = [];
+  for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
+    if (id.getText() !== name) continue;
+    out.push({
+      line: id.getStartLineNumber(),
+      snippet: id.getParent()?.getText().slice(0, 120) ?? name,
+    });
+  }
+  return out;
+}
+
+// String-literal scan: checks whether a given string appears as a literal
+// value (e.g. in map lookups, SQL filters, event-match blocks).
+function stringLiteralHits(
+  sf: SourceFile,
+  literal: string,
+): Array<{ line: number; snippet: string }> {
+  const out: Array<{ line: number; snippet: string }> = [];
+  for (const lit of sf.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
+    if (lit.getLiteralText() !== literal) continue;
+    out.push({
+      line: lit.getStartLineNumber(),
+      snippet: lit.getParent()?.getText().slice(0, 120) ?? literal,
+    });
+  }
+  for (const lit of sf.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
+    if (lit.getLiteralText() !== literal) continue;
+    out.push({
+      line: lit.getStartLineNumber(),
+      snippet: lit.getParent()?.getText().slice(0, 120) ?? literal,
+    });
+  }
+  return out;
+}
+
+const PATTERNS: readonly Pattern[] = [
+  {
+    name: "createEventLog",
+    description:
+      "Pre-ES Redis-Stream-Activity-Log. Ersetzt durch die events-Tabelle + ctx.loadAggregate / queryProjection.",
+    check: (sf) => identifierHits(sf, "createEventLog"),
+  },
+  {
+    name: "EventLog / EventLogEntry (Type-Import)",
+    description:
+      "Type-Imports aus dem entfernten pipeline/event-log.ts. Ersetzt durch StoredEvent + getAllProjectionProgress.",
+    check: (sf) => [...identifierHits(sf, "EventLog"), ...identifierHits(sf, "EventLogEntry")],
+  },
+  {
+    name: "ctx.emit / emitEvent(ctx, …) pre-E.2",
+    description:
+      "Sprint-E.2 entfernte ctx.emit + PUBSUB_AGGREGATE_TYPE. Domain-Events gehen via ctx.appendEvent auf Aggregate-Streams.",
+    check: (sf) => identifierHits(sf, "PUBSUB_AGGREGATE_TYPE"),
+  },
+  {
+    name: "r.postEvent",
+    description:
+      "Sprint-E.2 entfernte r.postEvent als Registrar-API. Ersatz: r.multiStreamProjection für Cross-Aggregate-Konsumenten.",
+    check: (sf) => {
+      // Match `.postEvent(` property accesses to distinguish from the word
+      // "postEvent" in prose. Identifier scan would miss method invocations.
+      const out: Array<{ line: number; snippet: string }> = [];
+      for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+        if (pa.getName() !== "postEvent") continue;
+        // Only flag when invoked as a method — a property read named
+        // postEvent on foreign types (theoretical) isn't the registrar API.
+        const parent = pa.getParent();
+        if (parent?.getKind() !== SyntaxKind.CallExpression) continue;
+        out.push({
+          line: pa.getStartLineNumber(),
+          snippet: pa.getParent()?.getText().slice(0, 120) ?? ".postEvent",
+        });
+      }
+      return out;
+    },
+  },
+  {
+    name: 'aggregateType: "configChanges"',
+    description:
+      'Pre-ES-Stream-Name. Konsumenten filtern auf aggregateType: "configValue" + Event-Types configValue.created/updated/deleted.',
+    check: (sf) => stringLiteralHits(sf, "configChanges"),
+  },
+  {
+    name: "config:event:config-changed Event-Name",
+    description:
+      "Pre-ES-Event. Ersetzt durch auto-Lifecycle-Events (configValue.created / .updated / .deleted).",
+    check: (sf) => [
+      ...stringLiteralHits(sf, "config:event:config-changed"),
+      ...identifierHits(sf, "CONFIG_CHANGED_EVENT_NAME"),
+    ],
+  },
+];
+
+export const guard: AstGuard = {
+  name: "Pre-ES-Patterns Guard",
+  scan: SCAN,
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      if (EXCLUDE.test(file)) continue;
+
+      for (const pat of PATTERNS) {
+        for (const hit of pat.check(sf)) {
+          violations.push({
+            file: path.relative(ROOT, file),
+            line: hit.line,
+            message: `[${pat.name}] ${hit.snippet}`,
+          });
+        }
+      }
+    }
+
+    // Sanity assertion: pipeline/event-log.ts must not exist.
+    const eventLogPath = path.join(ROOT, "packages/framework/src/pipeline/event-log.ts");
+    if (fs.existsSync(eventLogPath)) {
+      violations.push({
+        file: "packages/framework/src/pipeline/event-log.ts",
+        line: 0,
+        message:
+          "BLOCKED: pipeline/event-log.ts wurde wiederhergestellt. Die Datei gehört gelöscht — ihre Rolle übernimmt die events-Tabelle.",
+      });
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);