@cosmicdrift/kumiko-guards 0.382.0 → 0.383.1

package/src/guard-loadall-events.ts

@@ -1,139 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Guard: blocks calls of `loadAllEventsByType()` outside tests,
- * ops scripts and the definition itself.
- *
- * `loadAllEventsByType` buffers ALL events of an aggregate_type in
- * memory (a `SELECT … ORDER BY` without a limit). Beyond ~100k events per
- * type that is an OOM cliff that only shows under prod load — exactly the
- * kind of silent-and-late failure a guard catches before it ships.
- *
- * The memory-bounded replacement is `streamAllEventsByType` (yields in
- * batches, never more than batchSize rows resident). Production projection
- * rebuild already goes through this streaming path. `loadAllEventsByType` stays legitimate
- * for tests (small, controlled stores) and ops scripts on known
- * small aggregate_types — hence the allowlist instead of a removal.
- *
- * Usage:
- *   bun packages/guards/src/guard-loadall-events.ts
- */
-
-import * as path from "node:path";
-import { type CallExpression, type SourceFile, SyntaxKind } from "ts-morph";
-import {
-  type AstGuard,
-  type GuardViolation,
-  isLocalFinding,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-
-const ROOT = process.cwd();
-
-const SCAN: ScanSpec = {
-  scope: "source",
-  extensions: ["ts"],
-  kinds: ["framework", "library"],
-};
-
-// Test files may use the API freely — they are the primary verifiers and
-// run against small, controlled stores.
-const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
-
-// Allowed callers: the definition itself + ops/migration scripts (run
-// on known small aggregate_types, not in the prod hot path).
-// ROOT is anchored to process.cwd() (repo root), the `^` anchor only matches
-// real top-level scripts/, not 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.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).filter(isLocalFinding)) {
-        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-open-to-all-reason.ts

@@ -1,119 +0,0 @@
-#!/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: kumiko-guards guards --write-security-baseline
- */
-import * as path from "node:path";
-import { type SourceFile, SyntaxKind } from "ts-morph";
-import { isGenericReason, literalReasonText } from "./_lib/generic-reason";
-import {
-  ALL_REPO_KINDS,
-  type AstGuard,
-  type GuardViolation,
-  runStandalone,
-  type ScanSpec,
-} from "./_lib/guard-kit";
-
-const SCAN: ScanSpec = {
-  kinds: ALL_REPO_KINDS,
-  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: '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: `kumiko-guards guards --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

@@ -1,206 +0,0 @@
-#!/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 }> = [];
-  // Cheap text prefilter: a full descendant walk over every file costs seconds.
-  if (!sf.getFullText().includes(name)) return out;
-  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 }> = [];
-  if (!sf.getFullText().includes(literal)) return out;
-  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 }> = [];
-      if (!sf.getFullText().includes("postEvent")) return out;
-      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,
-  hint:
-    "These APIs were removed with the event-sourcing migration. Use the events table with ctx.loadAggregate / queryProjection, ctx.appendEvent on aggregate streams, " +
-    'r.multiStreamProjection for cross-aggregate consumers, and configValue.created/updated/deleted events (aggregateType: "configValue") for config changes.',
-  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 was restored. The file must be deleted — the events table now takes over its role.",
-      });
-    }
-
-    return { violations };
-  },
-};
-
-if (import.meta.main) runStandalone(guard);