@cosmicdrift/kumiko-guards 0.1.1 → 0.3.0

package/src/guard-lib-test-coverage.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env bun
+// lib/ ist die Heimat der extrahierten Logik (Berechnung, Parsing, Mapping) —
+// der no-logic-in-views-Guard schiebt sie dorthin, dieser Guard sorgt dafür,
+// dass sie an der neuen Stelle auch GETESTET ist. Für jede lib-Datei mit
+// mindestens einer exportierten Funktion muss ein Test existieren, der aus dem
+// Modul importiert, und jede exportierte Funktion muss dort namentlich
+// vorkommen.
+//
+// Warum statisch (ts-morph) statt Coverage-Threshold: Coverage lügt zweifach —
+// sie sieht nie-importierte Module gar nicht, und "ausgeführt" heißt nicht
+// "sinnvoll geprüft" (ein Integrationstest, der die Funktion transitiv über
+// HTTP streift, färbt sie grün ohne eine einzige Assertion auf ihr Verhalten).
+// Der Guard ist der strukturelle Gegenpart: er koppelt Test↔Modul über den
+// echten Import und zählt namentliche Referenzen, nicht Zeilen. Der
+// Coverage-Threshold in bunfig.toml bleibt daneben bestehen — beide zusammen,
+// nie der Threshold allein.
+//
+// Ausgenommen: Dateien ohne exportierte Funktion (reine Typen/Konstanten wie
+// eine Farb-Map — ein Test dafür wäre ein Fake-Test). IO-Loader, die bereits
+// durch einen Integrationstest über HTTP gedeckt sind, tragen den ignore-Tag
+// mit wahrheitsgemäßer Begründung.
+//
+// Bewusst out-of-scope: Re-Exports (`export { foo } from "./bar"`) zählen
+// nicht als eigene Callable — die Quelldatei "./bar" trägt ihre eigene
+// Coverage-Pflicht. Kommt lib/ je re-exportierte Funktionen ohne eigene
+// Quelldatei im Scope vor, ist das ein stiller Blindspot; bisher (Stand
+// dieser Fix-Runde) kommt das Pattern in keinem App-Repo vor.
+
+import { dirname, resolve } from "node:path";
+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";
+
+// isTestFile() classifies by regex on the file's own path, not by which within-glob matched it, so lib/ vs. test classification stays correct regardless of scan-scope resolution.
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  kinds: ["library", "app"],
+  within: ["lib/**/*.ts", "features/*/lib/**/*.ts", "**/*.test.ts", "**/*.test.tsx"],
+};
+const IGNORE_TAG = "kumiko-lint-ignore lib-test-coverage";
+
+type Export = { readonly name: string; readonly node: Node };
+
+function isTestFile(path: string): boolean {
+  return /\.test\.tsx?$/.test(path) || /\/__tests__\//.test(path);
+}
+
+// Exportierte Callables: `export function f` und `export const f = () => …` /
+// `= function () {}`. Reine Werte (`export const X = 5`), Typen und Interfaces
+// zählen nicht — sie tragen keine Logik, die ein Verhaltenstest prüfen könnte.
+function exportedCallables(sf: SourceFile): Export[] {
+  const out: Export[] = [];
+  for (const fd of sf.getFunctions()) {
+    const name = fd.getName();
+    if (name !== undefined && (fd.isExported() || fd.isDefaultExport()))
+      out.push({ name, node: fd });
+  }
+  for (const vs of sf.getVariableStatements()) {
+    if (!vs.isExported()) continue;
+    for (const decl of vs.getDeclarations()) {
+      const init = decl.getInitializer();
+      if (init !== undefined && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+        out.push({ name: decl.getName(), node: decl });
+      }
+    }
+  }
+  return out;
+}
+
+function stripExt(path: string): string {
+  return path.replace(/\.tsx?$/, "");
+}
+
+// Ein Test ist mit einer lib-Datei verknüpft, wenn er relativ aus genau dieser
+// Datei importiert — nicht per Pfad-Konvention. Das erlaubt Tests eine Ebene
+// über lib/ (features/<x>/__tests__/foo.test.ts → "../lib/foo") und verhindert,
+// dass generische Namen (fieldText, targetForRow) in fremden Tests fälschlich
+// als Referenz zählen.
+function testImportsLib(testSf: SourceFile, libPathNoExt: string): boolean {
+  const testDir = dirname(testSf.getFilePath());
+  for (const imp of testSf.getImportDeclarations()) {
+    const spec = imp.getModuleSpecifierValue();
+    if (!spec.startsWith(".")) continue;
+    if (stripExt(resolve(testDir, spec)) === libPathNoExt) return true;
+  }
+  return false;
+}
+
+// Import-Deklarationen ausklammern: ein benannter Import ohne jede Nutzung
+// (`import { addFees, subFees } from "../calc"`, nur addFees aufgerufen)
+// erfuellte den Guard fuer subFees schon durch den Import-Text allein —
+// der per-Funktions-Check war fuer named imports quasi tautologisch.
+function bodyTextWithoutImports(testSf: SourceFile): string {
+  const importRanges = testSf
+    .getDescendantsOfKind(SyntaxKind.ImportDeclaration)
+    .map((d) => [d.getStart(), d.getEnd()] as const);
+  const full = testSf.getFullText();
+  let out = "";
+  let cursor = 0;
+  for (const [start, end] of importRanges) {
+    out += full.slice(cursor, start);
+    cursor = end;
+  }
+  out += full.slice(cursor);
+  return out;
+}
+
+function referencesName(testSf: SourceFile, name: string): boolean {
+  return new RegExp(`\\b${name}\\b`).test(bodyTextWithoutImports(testSf));
+}
+
+export const guard: AstGuard = {
+  name: "Lib-Test-Coverage Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    "Jede lib-Datei mit exportierter Funktion braucht einen Test, der aus dem " +
+    "Modul importiert und jede Funktion namentlich referenziert. IO-Loader, die " +
+    `ein Integrationstest deckt: // ${IGNORE_TAG} <Grund, z.B. integration-covered via …>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    const testFiles: SourceFile[] = [];
+    const libFiles: SourceFile[] = [];
+    for (const sf of files) {
+      if (isTestFile(sf.getFilePath())) testFiles.push(sf);
+      else if (!sf.getFilePath().endsWith(".d.ts")) libFiles.push(sf);
+    }
+    for (const sf of libFiles) {
+      const relevant = exportedCallables(sf).filter((e) => !hasIgnoreTag(e.node, IGNORE_TAG));
+      if (relevant.length === 0) continue;
+
+      const libPathNoExt = stripExt(sf.getFilePath());
+      const linked = testFiles.filter((t) => testImportsLib(t, libPathNoExt));
+      if (linked.length === 0) {
+        violations.push({
+          file: sf.getFilePath(),
+          line: 1,
+          message: `Kein Test importiert dieses lib-Modul (${relevant.length} exportierte Funktion(en) ungetestet)`,
+        });
+        continue;
+      }
+
+      for (const e of relevant) {
+        if (linked.some((t) => referencesName(t, e.name))) continue;
+        violations.push({
+          file: sf.getFilePath(),
+          line: e.node.getStartLineNumber(),
+          message: `Exportierte Funktion "${e.name}" wird in keinem verknüpften Test namentlich referenziert`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-loadall-events.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env bun
+/**
+ * Guard: blockt Aufrufe von `loadAllEventsByType()` ausserhalb von Tests,
+ * Ops-Scripts und der Definition selbst.
+ *
+ * `loadAllEventsByType` buffert ALLE Events eines aggregate_type in den
+ * Speicher (ein `SELECT … ORDER BY` ohne Limit). Jenseits ~100k Events pro
+ * Typ ist das ein OOM-Cliff, der erst unter Prod-Last auffällt — genau die
+ * Art still-und-spät-Fehler, die ein Guard fängt bevor sie ausgeliefert wird.
+ *
+ * Der memory-bounded Ersatz ist `streamAllEventsByType` (yield't batchweise,
+ * nie mehr als batchSize Rows resident). Production-Projection-Rebuild geht
+ * bereits über diesen Streaming-Pfad. `loadAllEventsByType` bleibt legitim
+ * für Tests (kleine, kontrollierte Stores) und Ops-Scripts auf bekannt
+ * kleinen aggregate_types — daher die Allowlist statt einer Entfernung.
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-loadall-events.ts
+ */
+
+import * as path from "node:path";
+import { type CallExpression, type Identifier, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  kinds: ["framework", "library"],
+};
+
+// Test-Dateien dürfen die API frei benutzen — sie sind die primären
+// Verifizierer und laufen gegen kleine, kontrollierte Stores.
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+// Erlaubte Aufrufer: die Definition selbst + Ops-/Migration-Scripts (laufen
+// auf bekannt kleinen aggregate_types, nicht im Prod-Hot-Path).
+// ROOT ist gegen process.cwd() (Repo-Root) verankert, `^`-Anker matcht nur
+// echte Top-Level-scripts/, nicht packages/.../scripts/*.
+const ALLOWLIST: readonly RegExp[] = [
+  /^packages\/framework\/src\/event-store\/event-store\.ts$/,
+  /^scripts\//,
+];
+
+const GUARDED_CALLS = new Set(["loadAllEventsByType"]);
+
+export interface Violation {
+  file: string;
+  line: number;
+  functionName: string;
+  enclosingFunction: string;
+}
+
+export function isAllowed(relativePath: string): boolean {
+  return ALLOWLIST.some((re) => re.test(relativePath));
+}
+
+export function collectViolations(sourceFile: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+  const relativePath = path.relative(ROOT, sourceFile.getFilePath());
+  if (isAllowed(relativePath)) return violations;
+
+  const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+  for (const call of calls) {
+    const fnName = getCalleeName(call);
+    if (!fnName || !GUARDED_CALLS.has(fnName)) continue;
+    violations.push({
+      file: relativePath,
+      line: call.getStartLineNumber(),
+      functionName: fnName,
+      enclosingFunction: findEnclosingName(call),
+    });
+  }
+  return violations;
+}
+
+// Extract the called name. Handles:
+//   loadAllEventsByType(...)        → "loadAllEventsByType"  (Identifier)
+//   someNamespace.loadAllEventsByType(...) → "loadAllEventsByType"  (PropertyAccess)
+// Any other callee shape returns null.
+function getCalleeName(call: CallExpression): string | null {
+  const expr = call.getExpression();
+  if (expr.getKind() === SyntaxKind.Identifier) {
+    return (expr as Identifier).getText();
+  }
+  if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
+    return expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName();
+  }
+  return null;
+}
+
+function findEnclosingName(call: CallExpression): string {
+  let cur = call.getParent();
+  while (cur) {
+    if (cur.isKind(SyntaxKind.FunctionDeclaration) || cur.isKind(SyntaxKind.MethodDeclaration)) {
+      return cur.getName() ?? "<anonymous>";
+    }
+    if (cur.isKind(SyntaxKind.FunctionExpression) || cur.isKind(SyntaxKind.ArrowFunction)) {
+      const parent = cur.getParent();
+      if (parent?.isKind(SyntaxKind.VariableDeclaration)) return parent.getName();
+      if (parent?.isKind(SyntaxKind.PropertyAssignment)) return parent.getName();
+      return "<anonymous>";
+    }
+    cur = cur.getParent();
+  }
+  return "<top-level>";
+}
+
+export const guard: AstGuard = {
+  name: "loadAllEventsByType Guard",
+  scan: SCAN,
+  hint:
+    "loadAllEventsByType buffers ALL events of an aggregate_type in memory (OOM cliff > ~100k events). " +
+    "Use streamAllEventsByType (batched, memory-bounded) in production code. " +
+    "Allowed only in tests, scripts/, and the event-store definition.",
+  run(files) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const v of collectViolations(sf)) {
+        violations.push({
+          file: v.file,
+          line: v.line,
+          message: `${v.functionName}(...) in ${v.enclosingFunction}`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-no-custom-primitives.ts

@@ -85,11 +85,11 @@ const BASELINE_PATH = path.join(ROOT, BASELINE_FILE);
 const rawFormHtmlBaseline = baselineRatchet({
   file: BASELINE_PATH,
   formatVersion: 1,
-  unit: "Fund(e) rohes Formular-HTML",
+  unit: "raw form HTML finding(s)",
 });
 const RAW_FORM_HTML_REMEDIATION =
-  "Framework-Widget nutzen (@cosmicdrift/kumiko-renderer-web: Field/Input, ComboboxInput, …) " +
-  `oder usePrimitives(). Echte Ausnahme: // ${IGNORE_TAG} <Grund>`;
+  "Use a framework widget (@cosmicdrift/kumiko-renderer-web: Field/Input, ComboboxInput, …) " +
+  `or usePrimitives(). Real exception: // ${IGNORE_TAG} <reason>`;
 
 // The rule is new: measured backlog is 0 in every locally checked repo
 // (infra#748). Without a baseline file, check fail-closed against an empty
@@ -105,12 +105,11 @@ function checkRawFormHtmlBaseline(findings: readonly RawFormFinding[]): GuardVio
     return regressions.map((r) => ({
       file: r.file,
       line: resolveLine(r.file),
-      message: `${r.current} Fund(e) rohes Formular-HTML (keine Baseline — Altbestand ist 0). ${RAW_FORM_HTML_REMEDIATION}`,
+      message: `${r.current} raw form HTML finding(s) (no baseline — existing backlog is 0). ${RAW_FORM_HTML_REMEDIATION}`,
     }));
   }
   return rawFormHtmlBaseline.check(current, RAW_FORM_HTML_REMEDIATION, {
-    formatDriftRemediation:
-      "Einmalig `bun guards/guard-no-custom-primitives.ts --write-baseline` aufrufen.",
+    formatDriftRemediation: "Run `bun guards/guard-no-custom-primitives.ts --write-baseline` once.",
     resolveLine,
   });
 }
@@ -149,13 +148,13 @@ function analyse(
       violations.push({
         file: sf.getFilePath(),
         line: c.line,
-        message: `App-lokales UI-Primitive "${c.name}" — Framework-Widget/Primitive nutzen`,
+        message: `App-local UI primitive "${c.name}" — use a framework widget/primitive`,
       });
     }
     rawFormFindings.push(...collectRawFormHtml(sf));
   }
   if (!compareBaseline) {
-    console.log("  Baseline-Vergleich uebersprungen (--no-baseline).");
+    console.log("  Baseline comparison skipped (--no-baseline).");
   } else {
     violations.push(...checkRawFormHtmlBaseline(rawFormFindings));
   }
@@ -166,8 +165,8 @@ export const guard: AstGuard = {
   name: "No-Custom-Primitives Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Framework-Widget nutzen (@cosmicdrift/kumiko-renderer-web: StatCard, SectionCard, StatusBadge, QueryTable, Charts, …) " +
-    `oder usePrimitives(). Echte Domain-Komponente ohne Framework-Pendant: // ${IGNORE_TAG} <Grund>`,
+    "Use a framework widget (@cosmicdrift/kumiko-renderer-web: StatCard, SectionCard, StatusBadge, QueryTable, Charts, …) " +
+    `or usePrimitives(). Real domain component without a framework equivalent: // ${IGNORE_TAG} <reason>`,
   run: (files: readonly SourceFile[]) => analyse(files, true),
 };
 

package/src/guard-no-date-api.ts

@@ -162,7 +162,7 @@ function findDateApiUsages(sf: SourceFile): Omit<Violation, "file">[] {
 export const guard: AstGuard = {
   name: "No-Date-API Guard",
   scan: SCAN,
-  hint: "Ersetze mit Temporal.Now.instant() / Temporal.Instant.from / .toString() / .epochMilliseconds — siehe docs/plans/architecture/timezones.md.",
+  hint: "Replace with Temporal.Now.instant() / Temporal.Instant.from / .toString() / .epochMilliseconds — see docs/plans/architecture/timezones.md.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-no-direct-fs.ts

@@ -203,7 +203,7 @@ export const guard: AstGuard = {
   name: "No-Direct-Fs Guard",
   scan: SCAN,
   security: true,
-  hint: "Direkter node:fs-Import außerhalb der Allowlist — nutze FileStorageProvider (packages/framework/src/files/) statt fs selbst zu verdrahten. Path-Traversal-Guard existiert nur dort (resolveContainedPath). Legitimer neuer Tooling-Caller? Allowlist in guard-no-direct-fs.ts erweitern, mit Begründung + repo-Scope.",
+  hint: "Direct node:fs import outside the allowlist — use FileStorageProvider (packages/framework/src/files/) instead of wiring fs yourself. The path-traversal guard (resolveContainedPath) only exists there. Legitimate new tooling caller? Extend the allowlist in guard-no-direct-fs.ts, with a reason + repo scope.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
     const roots = resolveRepoRoots();

package/src/guard-no-inline-styles.ts

@@ -20,8 +20,8 @@ export const guard: AstGuard = {
   name: "No-Inline-Styles Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "style=/CSSProperties in App-Code durch Widgets + Theme-Tokens ersetzen. " +
-    `Begründete Ausnahme (z.B. dynamische Breite aus Daten): // ${IGNORE_TAG} <Grund>`,
+    "Replace style=/CSSProperties in app code with widgets + theme tokens. " +
+    `Justified exception (e.g. dynamic width from data): // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -32,7 +32,7 @@ export const guard: AstGuard = {
         violations.push({
           file: sf.getFilePath(),
           line: attr.getStartLineNumber(),
-          message: "style=-Prop in App-Code (Theme-Tokens/Widgets nutzen)",
+          message: "style= prop in app code (use theme tokens/widgets)",
         });
       }
       // ponytail: name-text comparison doesn't tolerate aliased imports
@@ -47,7 +47,7 @@ export const guard: AstGuard = {
         violations.push({
           file: sf.getFilePath(),
           line: ref.getStartLineNumber(),
-          message: "CSSProperties-Style-Objekt in App-Code (Theme-Tokens/Widgets nutzen)",
+          message: "CSSProperties style object in app code (use theme tokens/widgets)",
         });
       }
     }

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

@@ -124,8 +124,8 @@ 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>`,
+    "Computation/parsing/aggregation belongs in lib/ (with a test) — web/ holds only " +
+    `components and hooks. Justified exception: // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -136,7 +136,7 @@ export const guard: AstGuard = {
         violations.push({
           file: sf.getFilePath(),
           line: fn.getStartLineNumber(),
-          message: `View-Logik "${name}" gehört nach lib/ (mit Test) — web/ nur Komponenten/Hooks`,
+          message: `View logic "${name}" belongs in lib/ (with a test) — web/ only components/hooks`,
         });
       }
     }

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

@@ -40,8 +40,8 @@ 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>`,
+    "Use the framework hook set: useQuery (live: true for SSE), useMutation, useDisclosure. " +
+    `Real special case (DOM integration or similar): // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -54,7 +54,7 @@ export const guard: AstGuard = {
           violations.push({
             file: sf.getFilePath(),
             line: call.getStartLineNumber(),
-            message: `${name} in App-Screen — Framework-Hooks nutzen (useQuery/useMutation/useDisclosure)`,
+            message: `${name} in App-Screen — use framework hooks (useQuery/useMutation/useDisclosure)`,
           });
           continue;
         }
@@ -63,8 +63,7 @@ export const guard: AstGuard = {
           violations.push({
             file: sf.getFilePath(),
             line: call.getStartLineNumber(),
-            message:
-              "fetch() in App-Screen — useQuery/useMutation bzw. einen Api-Client (*.ts) nutzen",
+            message: "fetch() in App-Screen — use useQuery/useMutation or an API client (*.ts)",
           });
         }
       }

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

@@ -85,7 +85,7 @@ export function createOpenToAllReasonGuard(opts: { root: string }): AstGuard {
     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`',
+    hint: 'Provide openToAll: { reason: "<why any authenticated user may call this>" } (+ personalData: "tenant-members" for write handlers with unbound personal data). Baseline after a deliberate reduction: `bun guards/run-guards.ts --write-security-baseline`',
     run(files) {
       const violations: GuardViolation[] = [
         ...findGenericOpenToAllReasons(files, opts.root).map((f) => ({