@cosmicdrift/kumiko-guards 0.1.0

package/src/guard-renderer-boundaries.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env bun
+/**
+ * Guard: prevents `@cosmicdrift/kumiko-renderer` (shared, platform-neutral)
+ * from touching DOM- or platform-specific APIs. As soon as window/document/
+ * EventSource/react-dom show up, the separation is broken and the code
+ * belongs in `@cosmicdrift/kumiko-renderer-web` (or renderer-native) instead.
+ *
+ * Deliberately simple: a regex scan over the source text. False positives
+ * (e.g. "window" in a string literal) are possible but rare — the guard is a
+ * maintenance alarm, not a semantic proof.
+ *
+ * Checked:
+ *   - Imports:  react-dom/*, jsdom, @cosmicdrift/kumiko-renderer-web, @cosmicdrift/kumiko-renderer-native
+ *   - Symbols:  window., document., location., history., localStorage,
+ *               sessionStorage, navigator., EventSource, fetch
+ *               (bare — unqualified)
+ *
+ * __tests__ folders are excluded — tests mount in jsdom, that's expected.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+
+// Imports that are taboo in the shared layer.
+const FORBIDDEN_IMPORTS = [
+  /from ["']react-dom(?:\/.*)?["']/,
+  /from ["']jsdom["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer-web["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer-native["']/,
+  /from ["']@cosmicdrift\/kumiko-dispatcher-live["']/,
+];
+
+// Runtime symbols that mean DOM/browser. `\b` prevents substring matches
+// (e.g. "origin" not matched as "origin.foo"). This is a coarse guard — a
+// ts-morph-based check would be more precise, but not worth the effort here.
+const FORBIDDEN_SYMBOLS = [
+  /\bwindow\s*\./,
+  /\bdocument\s*\./,
+  /\blocation\s*\./,
+  /\bhistory\s*\./,
+  /\blocalStorage\b/,
+  /\bsessionStorage\b/,
+  /\bnavigator\s*\./,
+  /\bEventSource\b/,
+  /\bHTMLElement\b/,
+  /\bcreateRoot\b/,
+];
+
+// JSX elements with a lowercase name = HTML tags (React convention:
+// lowercase = intrinsic DOM element, Capitalized = component). The shared
+// renderer must not emit DOM tags — everything goes through primitives,
+// which are platform-bound.
+//
+// Match: `<tagname` at the start of a JSX opening, with a lowercase letter.
+// Ignored: fragment `<>`, components `<Capitalized`, attribute values like
+// `<string>` in a type-annotation context (the regex only matches right
+// after whitespace/newline/>, not after an identifier character).
+const FORBIDDEN_JSX_TAG = /(^|\s|>|\()<([a-z][a-zA-Z0-9-]*)[\s/>]/;
+
+type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly rule: string;
+  readonly excerpt: string;
+};
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "__tests__") continue;
+      if (entry.name === "node_modules" || entry.name === "dist") continue;
+      out.push(...walk(full));
+      continue;
+    }
+    if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function findViolations(file: string, root: string): Violation[] {
+  const text = fs.readFileSync(file, "utf-8");
+  const lines = text.split("\n");
+  const violations: Violation[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    // Skip comments. Pure heuristic — multi-line block comments aren't
+    // caught. Good enough for source that doesn't jsdoc-block-paste 'window.*' as prose.
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
+
+    for (const pattern of FORBIDDEN_IMPORTS) {
+      if (pattern.test(line)) {
+        violations.push({
+          file: path.relative(root, file),
+          line: i + 1,
+          rule: "forbidden-import",
+          excerpt: trimmed,
+        });
+      }
+    }
+    for (const pattern of FORBIDDEN_SYMBOLS) {
+      if (pattern.test(line)) {
+        violations.push({
+          file: path.relative(root, file),
+          line: i + 1,
+          rule: "forbidden-symbol",
+          excerpt: trimmed,
+        });
+      }
+    }
+    const jsxMatch = line.match(FORBIDDEN_JSX_TAG);
+    if (jsxMatch !== null) {
+      violations.push({
+        file: path.relative(root, file),
+        line: i + 1,
+        rule: `forbidden-jsx-tag (<${jsxMatch[2]}>)`,
+        excerpt: trimmed,
+      });
+    }
+  }
+  return violations;
+}
+
+export const check: RepoCheck = {
+  name: "Renderer-Boundaries Guard",
+  hint: "@cosmicdrift/kumiko-renderer darf keine DOM-/Browser-/Platform-APIs nutzen. Platform-spezifischer Code gehört nach @cosmicdrift/kumiko-renderer-web (oder renderer-native).",
+  run(roots) {
+    const frameworkRoots = roots.filter((r) => r.kind === "framework");
+    const scanDirs = frameworkRoots
+      .map((r) => path.join(r.absPath, "packages/renderer/src"))
+      .filter((p) => fs.existsSync(p));
+    if (scanDirs.length === 0) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const files: string[] = [];
+    for (const dir of scanDirs) files.push(...walk(dir));
+    const root = frameworkRoots[0]?.absPath ?? process.cwd();
+    const violations = files.flatMap((file) =>
+      findViolations(file, root).map((v) => ({
+        file: v.file,
+        line: v.line,
+        message: `[${v.rule}] ${v.excerpt}`,
+      })),
+    );
+    return { violations, matchedFiles: files.length, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-restricted-symbols.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env bun
+/**
+ * Guard: finds imports/re-exports of the unscoped stream primitives outside
+ * an allowlist.
+ *
+ * `getUnscopedAggregateStreamMaxVersion` / `getUnscopedAggregateStreamTenant`
+ * (packages/framework/src/event-store/event-store.ts) have no tenant
+ * filter — they are an existence oracle for foreign tenants (see
+ * kumiko-framework#1269). Legitimate only for seed-/system-internal code
+ * that deliberately works across tenants.
+ *
+ * Usage:
+ *   bun guards/guard-restricted-symbols.ts
+ *
+ * Exit 1 on violations in non-allowlisted files, 0 when clean.
+ */
+
+import { type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  isAllowlisted,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+const RESTRICTED_SYMBOLS = new Set([
+  "getUnscopedAggregateStreamMaxVersion",
+  "getUnscopedAggregateStreamTenant",
+]);
+
+const ALLOWLIST = [
+  /^packages\/framework\/src\/event-store\/event-store\.ts$/,
+  /^packages\/framework\/src\/event-store\/index\.ts$/,
+  /^packages\/bundled-features\/src\/tenant\/seeding\.ts$/,
+  /^packages\/bundled-features\/src\/tier-engine\/feature\.ts$/,
+];
+
+interface Violation {
+  line: number;
+  symbol: string;
+}
+
+// Namespace import (`import * as es from "...event-store"; es.getUnscoped...()`)
+// doesn't bind a named import declaration, so it slips past
+// findRestrictedSymbolReferences() below — catch `<namespace>.<restrictedSymbol>`
+// property access instead. `export *` re-exports remain an unaddressed gap
+// (see the guard's `hint` for the known limitation).
+function findNamespacedSymbolAccesses(sf: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+
+  const namespaceNames = new Set(
+    sf
+      .getImportDeclarations()
+      .map((d) => d.getNamespaceImport())
+      .filter((ns): ns is NonNullable<typeof ns> => ns !== undefined)
+      .map((ns) => ns.getText()),
+  );
+  if (namespaceNames.size === 0) return violations;
+
+  for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+    const objText = access.getExpression().getText();
+    const propName = access.getNameNode().getText();
+    if (namespaceNames.has(objText) && RESTRICTED_SYMBOLS.has(propName)) {
+      violations.push({ line: access.getStartLineNumber(), symbol: propName });
+    }
+  }
+
+  return violations;
+}
+
+// Named imports (`import { X } from ...`) and re-exports (`export { X } from
+// ...`) both cross a module boundary — either shape counts as an unguarded
+// reference. getName() returns the imported/exported symbol's original name,
+// not a local alias, so `as`-renamed references are still caught.
+function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+
+  for (const importDecl of sf.getImportDeclarations()) {
+    for (const named of importDecl.getNamedImports()) {
+      const name = named.getName();
+      if (RESTRICTED_SYMBOLS.has(name)) {
+        violations.push({ line: named.getStartLineNumber(), symbol: name });
+      }
+    }
+  }
+
+  for (const exportDecl of sf.getExportDeclarations()) {
+    if (!exportDecl.getModuleSpecifier()) continue;
+    for (const named of exportDecl.getNamedExports()) {
+      const name = named.getName();
+      if (RESTRICTED_SYMBOLS.has(name)) {
+        violations.push({ line: named.getStartLineNumber(), symbol: name });
+      }
+    }
+  }
+
+  violations.push(...findNamespacedSymbolAccesses(sf));
+
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "Restricted-Symbols Guard",
+  scan: SCAN,
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} sind ein Existenz-Orakel für fremde Tenants — nur Seed-/System-interner Code darf sie referenzieren. Neuer Caller nötig? Allowlist in guard-restricted-symbols.ts erweitern, mit Begründung. Bekannte Lücke: `export * from "...event-store"` wird nicht erkannt (Named-Imports, Re-Exports und Namespace-Property-Access sind abgedeckt).',
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+    const roots = resolveRepoRoots();
+
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      const rel = relFromRepoRoot(file, roots);
+      if (EXCLUDE.test(rel)) continue;
+      if (isAllowlisted(rel, ALLOWLIST)) continue;
+      for (const v of findRestrictedSymbolReferences(sf)) {
+        violations.push({
+          file: rel,
+          line: v.line,
+          message: `[${v.symbol}] unscoped stream-primitive referenced outside allowlist`,
+        });
+      }
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-silent-skip.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env bun
+/**
+ * Guard: finds "silent skip" spots in production code.
+ *
+ * A "silent skip" is a bare `return;` (no value) in code that skips logic
+ * unnoticed — typical in hooks, handlers, middleware.
+ *
+ * Usage:
+ *   bun guards/guard-silent-skip.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import * as path from "node:path";
+import { type Node, type ReturnStatement, 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/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+export interface SkipSite {
+  file: string;
+  line: number;
+  enclosingFunction: string;
+  enclosingKind: "hook" | "handler" | "middleware" | "function" | "arrow" | "method";
+  precedingText: string;
+  commentsAbove?: string;
+  snippet: string;
+}
+
+/**
+ * Builds the context for a bare return. Pure data extraction — no policy.
+ * The allow/deny decision happens in isAllowed().
+ */
+function describeSite(ret: ReturnStatement, sourceFile: SourceFile): SkipSite {
+  const enclosing = findEnclosingFunction(ret);
+  const fnName = enclosing.name;
+  const kind = classifyEnclosing(ret, enclosing.node);
+
+  const prev = ret.getPreviousSibling();
+  const precedingText = prev?.getText() ?? "";
+
+  // Collect comments from multiple possible locations:
+  //   1. Leading trivia on the return itself (`// skip:` on the line above a standalone return)
+  //   2. Leading trivia on the enclosing IfStatement (`// skip:` before `if (x) return;`)
+  //   3. Trailing comment on the previous sibling statement
+  const comments: string[] = [];
+  comments.push(...ret.getLeadingCommentRanges().map((r) => r.getText()));
+  const enclosingIf = ret.getFirstAncestorByKind(SyntaxKind.IfStatement);
+  if (enclosingIf && enclosingIf.getStartLineNumber() >= ret.getStartLineNumber() - 2) {
+    comments.push(...enclosingIf.getLeadingCommentRanges().map((r) => r.getText()));
+  }
+  if (prev?.getTrailingCommentRanges) {
+    comments.push(...prev.getTrailingCommentRanges().map((r) => r.getText()));
+  }
+
+  return {
+    file: path.relative(ROOT, sourceFile.getFilePath()),
+    line: ret.getStartLineNumber(),
+    enclosingFunction: fnName,
+    enclosingKind: kind,
+    precedingText,
+    commentsAbove: comments.join("\n"),
+    snippet: ret.getText(),
+  };
+}
+
+function findEnclosingFunction(node: Node): { node: Node; name: string } {
+  let cur: Node | undefined = node.getParent();
+  while (cur) {
+    if (
+      cur.isKind(SyntaxKind.FunctionDeclaration) ||
+      cur.isKind(SyntaxKind.FunctionExpression) ||
+      cur.isKind(SyntaxKind.ArrowFunction) ||
+      cur.isKind(SyntaxKind.MethodDeclaration)
+    ) {
+      return { node: cur, name: guessName(cur) };
+    }
+    cur = cur.getParent();
+  }
+  return { node, name: "<top-level>" };
+}
+
+function guessName(fn: Node): string {
+  if (fn.isKind(SyntaxKind.FunctionDeclaration) || fn.isKind(SyntaxKind.MethodDeclaration)) {
+    return fn.getName() ?? "<anonymous>";
+  }
+  const parent = fn.getParent();
+  if (parent?.isKind(SyntaxKind.VariableDeclaration)) return parent.getName();
+  if (parent?.isKind(SyntaxKind.PropertyAssignment)) return parent.getName();
+  const callExpr = parent?.isKind(SyntaxKind.CallExpression) ? parent : undefined;
+  if (callExpr) return `${callExpr.getExpression().getText()}(...)`;
+  return "<anonymous>";
+}
+
+function classifyEnclosing(_ret: ReturnStatement, fn: Node): SkipSite["enclosingKind"] {
+  const text = fn.getParent()?.getText() ?? "";
+  if (/\bhook\s*\(|postSave|preSave|validation/.test(text)) return "hook";
+  if (/Handler\b|writeHandler|queryHandler/.test(text)) return "handler";
+  if (/middleware|Middleware/.test(text)) return "middleware";
+  if (fn.isKind(SyntaxKind.MethodDeclaration)) return "method";
+  if (fn.isKind(SyntaxKind.ArrowFunction)) return "arrow";
+  return "function";
+}
+
+// ---------------------------------------------------------------------------
+// POLICY
+// ---------------------------------------------------------------------------
+
+/**
+ * Policy: a bare `return;` needs one of the following markers right before it
+ * — otherwise it is flagged.
+ *
+ *   (a) Log call:     ctx.log?.debug(...), logger.debug(...), context.log?.info(...)
+ *   (b) Skip comment: // skip: <reason>
+ *   (c) Throw escape: preceded by a throw (the return is dead code, should go)
+ *
+ * (a) is for pipeline code with ctx in scope — the skip is visible at
+ * runtime. (b) is for utils without logger access — documentation in code.
+ * (c) catches the rare cases where TS narrowing leaves a dead return behind.
+ */
+function isAllowed(site: SkipSite): boolean {
+  const preceding = site.precedingText;
+
+  // (a) log call on ctx/context/opts.context or module-level logger
+  if (/\b(?:\w+\.)?(?:log|logger)\??\.(?:debug|info|warn|error|trace)\s*\(/.test(preceding)) {
+    return true;
+  }
+
+  // (b) explicit // skip: marker — check trailing comment on preceding OR leading on return
+  if (/\/\/\s*skip:/i.test(preceding)) return true;
+  if (hasLeadingSkipComment(site)) return true;
+
+  // (c) preceding is a throw
+  if (/^\s*throw\b/.test(preceding)) return true;
+
+  return false;
+}
+
+function hasLeadingSkipComment(site: SkipSite): boolean {
+  // The ts-morph scanner captures the previous sibling as precedingText, but
+  // a `// skip:` comment directly above the return is leading trivia on the
+  // return statement itself — handled by describeSite via `commentsAbove`.
+  return /\/\/\s*skip:/i.test(site.commentsAbove ?? "");
+}
+
+// ---------------------------------------------------------------------------
+// Scanner + reporter
+// ---------------------------------------------------------------------------
+
+export const guard: AstGuard = {
+  name: "Silent-Skip Guard",
+  scan: SCAN,
+  hint: "Nacktes `return;` braucht davor: Log-Call, `// skip: <grund>`-Kommentar, oder vorangehenden throw.",
+  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;
+
+      const returns = sf.getDescendantsOfKind(SyntaxKind.ReturnStatement);
+      for (const ret of returns) {
+        if (ret.getExpression()) continue; // has a value, not "silent"
+        const site = describeSite(ret, sf);
+        if (isAllowed(site)) continue;
+        violations.push({
+          file: site.file,
+          line: site.line,
+          message: `[${site.enclosingKind}] in ${site.enclosingFunction}`,
+        });
+      }
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);