@cosmicdrift/kumiko-guards 0.1.0

package/src/guard-thin-wrappers.ts

@@ -0,0 +1,422 @@
+#!/usr/bin/env bun
+/**
+ * Thin-Wrapper Guard (warning, never fails).
+ *
+ * Finds functions that only call another function (1 statement, direct
+ * delegation) and are not marked as a deliberate wrapper.
+ *
+ * Such wrappers often appear as compatibility shims after refactorings —
+ * this guard keeps the list visible so they can be deliberately removed.
+ *
+ * === Setting a marker ===
+ *
+ * When a wrapper is deliberate and permanent, right above the function:
+ *
+ *   // @wrapper-known semantic-alias
+ *   export function signDeletionToken(dek: Buffer): string {
+ *     return signToken(dek);
+ *   }
+ *
+ * Known reasons:
+ *   semantic-alias   — deliberate rename for domain clarity
+ *   error-helper     — named error constructor (delegates to writeFailure or similar)
+ *   uuid-domain      — domain-specific UUID generator
+ *   test-helper      — test-utility alias
+ *   monitoring       — monitoring/metrics alias
+ *   health-check     — health-check wrapper
+ *   entry-point      — entry-point-specific configuration
+ */
+
+import * as path from "node:path";
+import {
+  type ArrowFunction,
+  type FunctionDeclaration,
+  type FunctionExpression,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+  type VariableDeclaration,
+} from "ts-morph";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { frameworkTsConfigPath } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+
+const ROOT = process.cwd();
+
+const EXCLUDE =
+  /(__tests__|\.test\.(ts|tsx)$|\.integration\.(ts|tsx)$|\.d\.(ts|tsx)$|\.spec\.(ts|tsx)$|node_modules)/;
+
+// ── Known reasons ─────────────────────────────────────────────────────────
+
+export const KNOWN_WRAPPER_REASONS = [
+  "semantic-alias", // deliberate rename for domain clarity
+  "error-helper", // named error constructor
+  "uuid-domain", // domain-specific UUID generator
+  "test-helper", // test-utility alias
+  "monitoring", // monitoring/metrics alias
+  "health-check", // health-check wrapper
+  "entry-point", // entry-point-specific configuration
+] as const;
+
+export type WrapperReason = (typeof KNOWN_WRAPPER_REASONS)[number];
+
+function isKnownReason(r: string): r is WrapperReason {
+  return (KNOWN_WRAPPER_REASONS as readonly string[]).includes(r);
+}
+
+// ── Built-in filter ─────────────────────────────────────────────────────
+
+const BUILTIN_NAMES = new Set([
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "map",
+  "filter",
+  "reduce",
+  "reduceRight",
+  "forEach",
+  "find",
+  "findIndex",
+  "findLast",
+  "findLastIndex",
+  "some",
+  "every",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  "slice",
+  "splice",
+  "concat",
+  "flat",
+  "flatMap",
+  "join",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin",
+  "at",
+  "entries",
+  "keys",
+  "values",
+  "from",
+  "isArray",
+  "of",
+  "assign",
+  "create",
+  "fromEntries",
+  "defineProperty",
+  "getOwnPropertyNames",
+  "getOwnPropertyDescriptor",
+  "hasOwn",
+  "freeze",
+  "seal",
+  "replace",
+  "replaceAll",
+  "split",
+  "trim",
+  "trimStart",
+  "trimEnd",
+  "trimLeft",
+  "trimRight",
+  "startsWith",
+  "endsWith",
+  "substring",
+  "padStart",
+  "padEnd",
+  "repeat",
+  "match",
+  "matchAll",
+  "search",
+  "charAt",
+  "charCodeAt",
+  "toUpperCase",
+  "toLowerCase",
+  "normalize",
+  "toString",
+  "valueOf",
+  "stringify",
+  "parse",
+  "log",
+  "error",
+  "warn",
+  "info",
+  "debug",
+  "trace",
+  "table",
+  "group",
+  "groupEnd",
+  "time",
+  "timeEnd",
+  "min",
+  "max",
+  "floor",
+  "ceil",
+  "round",
+  "abs",
+  "sqrt",
+  "pow",
+  "random",
+  "sign",
+  "trunc",
+  "then",
+  "catch",
+  "finally",
+  "resolve",
+  "reject",
+  "all",
+  "allSettled",
+  "race",
+  "any",
+  "get",
+  "set",
+  "has",
+  "delete",
+  "clear",
+  "call",
+  "apply",
+  "bind",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval",
+  "String",
+  "Number",
+  "Boolean",
+  "Symbol",
+  "BigInt",
+  "Array",
+  "Object",
+  "Promise",
+  "Map",
+  "Set",
+  "send",
+  "emit",
+  "on",
+  "off",
+  "once",
+  "next",
+  "done",
+  "throw",
+  "return",
+]);
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+type FnNode = FunctionDeclaration | ArrowFunction | FunctionExpression;
+
+export interface Finding {
+  file: string;
+  line: number;
+  fnName: string;
+  callee: string;
+  markerReason: string | null; // null = no marker, string = reason (unknown reasons included)
+}
+
+// ── AST helpers ───────────────────────────────────────────────────────────
+
+function getFnName(node: FnNode): string | undefined {
+  if (node.isKind(SyntaxKind.FunctionDeclaration)) return node.getName() ?? undefined;
+  const parent = node.getParent();
+  if (parent?.isKind(SyntaxKind.VariableDeclaration)) {
+    return (parent as VariableDeclaration).getName();
+  }
+  if (parent?.isKind(SyntaxKind.PropertyAssignment)) {
+    return parent.getFirstChild()?.getText();
+  }
+  // ponytail: MethodDeclaration dropped — getFirstChild() returns the modifier keyword, not the name.
+  return undefined;
+}
+
+function getSingleDirectCallee(node: FnNode): string | null {
+  const rawBody =
+    node.isKind(SyntaxKind.ArrowFunction) && !node.getBody().isKind(SyntaxKind.Block)
+      ? null
+      : node.getBody();
+
+  // Concise arrow: `x => someCall(x)` — body IS the expression
+  if (!rawBody || !rawBody.isKind(SyntaxKind.Block)) {
+    const body = node.getBody();
+    if (!body || !body.isKind(SyntaxKind.CallExpression)) return null;
+    // Method chains (A.from(x).toMethod(y)) have 2 call expressions — not a thin wrapper
+    const conciseCallees = new Set<string>();
+    node.forEachDescendant((n) => {
+      if (!n.isKind(SyntaxKind.CallExpression)) return;
+      const cName = extractCalleeName(n);
+      if (cName) conciseCallees.add(cName);
+    });
+    if (conciseCallees.size !== 1) return null;
+    const name = extractCalleeName(body);
+    if (!name || BUILTIN_NAMES.has(name)) return null;
+    return name;
+  }
+
+  const stmts = rawBody.getStatements();
+  if (stmts.length !== 1) return null;
+
+  const single = stmts.reduce((only) => only);
+  // switch → not a wrapper
+  if (single.isKind(SyntaxKind.SwitchStatement)) return null;
+
+  let callExpr = null;
+
+  if (single.isKind(SyntaxKind.ReturnStatement)) {
+    const expr = single.getExpression();
+    if (!expr) return null;
+    // factory: return () => ... → not a wrapper
+    if (expr.isKind(SyntaxKind.ArrowFunction) || expr.isKind(SyntaxKind.FunctionExpression))
+      return null;
+    // direct delegation: return someCall(...)
+    if (!expr.isKind(SyntaxKind.CallExpression)) return null;
+    callExpr = expr;
+  } else if (single.isKind(SyntaxKind.ExpressionStatement)) {
+    const expr = single.getExpression();
+    if (!expr.isKind(SyntaxKind.CallExpression)) return null;
+    callExpr = expr;
+  } else {
+    return null;
+  }
+
+  // Ensure the call isn't part of a larger nested-call tree: a direct call
+  // has exactly 1 unique callee name across the whole body.
+  const allCallees = new Set<string>();
+  node.forEachDescendant((n) => {
+    if (!n.isKind(SyntaxKind.CallExpression)) return;
+    const name = extractCalleeName(n);
+    if (name) allCallees.add(name);
+  });
+  if (allCallees.size !== 1) return null;
+
+  const name = extractCalleeName(callExpr);
+  if (!name) return null;
+  if (BUILTIN_NAMES.has(name)) return null;
+
+  return name;
+}
+
+function extractCalleeName(callNode: ReturnType<FnNode["getBody"]> | undefined): string | null {
+  if (!callNode) return null;
+  const expr = callNode.isKind(SyntaxKind.CallExpression) ? callNode.getExpression() : null;
+  if (!expr) return null;
+  if (expr.isKind(SyntaxKind.Identifier)) return expr.getText();
+  if (expr.isKind(SyntaxKind.PropertyAccessExpression)) return expr.getName();
+  return null;
+}
+
+// ── Marker detection ──────────────────────────────────────────────────────
+
+const MARKER_RE = /\/[/*]\s*@wrapper-known(?:\s+([\w-]+))?/;
+
+function extractMarkerReason(node: FnNode): string | null {
+  const fullText = node.getSourceFile().getFullText();
+
+  // Anchor node for leading comments:
+  //   VariableStatement  → const foo = () => ...
+  //   PropertyAssignment → { foo: () => ... }  (marker above the property)
+  //   FunctionDeclaration → function foo() { ... }
+  const parentNode = node.getParent();
+  const anchor =
+    node.getFirstAncestorByKind(SyntaxKind.VariableStatement) ??
+    (parentNode?.isKind(SyntaxKind.PropertyAssignment) ? parentNode : null) ??
+    (node.isKind(SyntaxKind.FunctionDeclaration) ? node : null);
+
+  if (anchor) {
+    for (const r of anchor.getLeadingCommentRanges()) {
+      const m = MARKER_RE.exec(r.getText());
+      if (m) return m[1] ?? "";
+    }
+  }
+
+  // Trailing comment on the same line
+  const end = node.getEnd();
+  const eol = fullText.indexOf("\n", end);
+  const trailing = fullText.slice(end, eol === -1 ? fullText.length : eol);
+  const m = MARKER_RE.exec(trailing);
+  if (m) return m[1] ?? "";
+
+  return null;
+}
+
+// ── Scan ──────────────────────────────────────────────────────────────────
+
+export function collectFindings(sf: SourceFile): Finding[] {
+  const file = path.relative(ROOT, sf.getFilePath());
+  const findings: Finding[] = [];
+
+  const check = (node: FnNode) => {
+    const fnName = getFnName(node);
+    if (!fnName) return;
+
+    const callee = getSingleDirectCallee(node);
+    if (!callee) return;
+    // Self-recursion / delegation false-positive (same name)
+    if (callee === fnName) return;
+
+    const markerReason = extractMarkerReason(node);
+    findings.push({
+      file,
+      line: node.getStartLineNumber(),
+      fnName,
+      callee,
+      markerReason,
+    });
+  };
+
+  sf.getFunctions().forEach(check);
+  sf.getDescendantsOfKind(SyntaxKind.ArrowFunction).forEach(check);
+  sf.getDescendantsOfKind(SyntaxKind.FunctionExpression).forEach(check);
+
+  return findings;
+}
+
+// ── RepoCheck ─────────────────────────────────────────────────────────────
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+export const check: RepoCheck = {
+  name: "Thin-Wrappers Guard",
+  run(roots) {
+    const project = new Project({
+      tsConfigFilePath: frameworkTsConfigPath(),
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+    });
+
+    const paths = scanFiles(SCAN, roots);
+    for (const p of paths) project.addSourceFileAtPath(p);
+
+    let scanned = 0;
+    const warnings: { file: string; line: number; message: string }[] = [];
+    for (const sf of project.getSourceFiles()) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      scanned++;
+      for (const f of collectFindings(sf)) {
+        if (f.markerReason === null) {
+          warnings.push({ file: f.file, line: f.line, message: `${f.fnName} → ${f.callee}` });
+        } else if (!isKnownReason(f.markerReason)) {
+          warnings.push({
+            file: f.file,
+            line: f.line,
+            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}")`,
+          });
+        }
+      }
+    }
+
+    return {
+      violations: [],
+      warnings: warnings.length > 0 ? warnings : undefined,
+      matchedFiles: scanned,
+      notApplicable: roots.length === 0,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-unsafe-json-parse.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+/**
+ * Guard: JSON.parse calls must be inside a try/catch OR routed through the
+ * safe-json helpers (parseJsonSafe / parseJsonOrThrow). Bare JSON.parse on
+ * data from external systems (Redis, DB, HTTP) crashes the pipeline silently
+ * with a SyntaxError when input is corrupt.
+ *
+ * Usage:
+ *   bun guards/guard-unsafe-json-parse.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/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|safe-json\.ts$)/;
+
+interface UnsafeSite {
+  file: string;
+  line: number;
+  snippet: string;
+}
+
+function isInsideTry(node: Node): boolean {
+  let cur: Node | undefined = node.getParent();
+  while (cur) {
+    if (cur.isKind(SyntaxKind.TryStatement)) {
+      const tryBlock = cur.asKindOrThrow(SyntaxKind.TryStatement).getTryBlock();
+      if (
+        tryBlock &&
+        node.getStart() >= tryBlock.getStart() &&
+        node.getEnd() <= tryBlock.getEnd()
+      ) {
+        return true;
+      }
+    }
+    cur = cur.getParent();
+  }
+  return false;
+}
+
+function scanFile(sf: SourceFile): UnsafeSite[] {
+  const sites: UnsafeSite[] = [];
+  const calls = sf.getDescendantsOfKind(SyntaxKind.CallExpression);
+  for (const call of calls) {
+    const expr = call.getExpression();
+    if (expr.getText() !== "JSON.parse") continue;
+    if (isInsideTry(call)) continue;
+    sites.push({
+      file: path.relative(ROOT, sf.getFilePath()),
+      line: call.getStartLineNumber(),
+      snippet: call.getText().slice(0, 80),
+    });
+  }
+  return sites;
+}
+
+export const guard: AstGuard = {
+  name: "Unsafe-JSON-Parse Guard",
+  scan: SCAN,
+  hint: "Nutze parseJsonSafe (Cache-Semantik) oder parseJsonOrThrow (Boundary-Semantik) aus utils/safe-json.",
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const site of scanFile(sf)) {
+        violations.push({
+          file: site.file,
+          line: site.line,
+          message: `unguarded JSON.parse — ${site.snippet}`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/index.ts

@@ -0,0 +1,29 @@
+export {
+  type AstGuard,
+  buildSharedProject,
+  explainGuards,
+  filesForGuard,
+  type GuardOutcome,
+  type GuardViolation,
+  isSecurityGuard,
+  type RepoCheck,
+  type RepoCheckOutcome,
+  type RunGuardsDeps,
+  type RunResult,
+  reportResults,
+  runGuards,
+  runRepoChecks,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+export { findLocalRepo, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+export {
+  loadSecurityBaseline,
+  parseSecurityBaseline,
+  SECURITY_BASELINE_FILE,
+  type SecurityBaseline,
+  type SecurityBaselineLoad,
+} from "./_lib/security-baseline";
+export { writeSecurityBaselines } from "./_lib/security-baseline-cli";
+export { GUARDS } from "./run-guards";
+export { REPO_CHECKS } from "./run-repo-checks";
+export { UI_GUARDS } from "./run-ui-guards";

package/src/run-guards.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+// Shared-project guard runner. Loads ONE ts-morph project and runs all
+// registered AST guards serially in-process over it — instead of N
+// subprocesses each with their own project (memory thrashing at pool=6).
+//
+// `--explain` prints the root, scan scope, and file count per guard without checking.
+// `--strict-security-baseline` also fails on security-baseline headroom; only for
+// the maintenance run that rewrites the committed baseline. It runs only the
+// security guards.
+import {
+  buildSharedProject,
+  explainGuards,
+  isSecurityGuard,
+  reportResults,
+  runGuards,
+} from "./_lib/guard-kit";
+import { writeSecurityBaselines } from "./_lib/security-baseline-cli";
+import { guard as accessDeniedTest } from "./guard-access-denied-test";
+import { guard as adminApi } from "./guard-admin-api";
+import { guard as crossFeatureImports } from "./guard-cross-feature-imports";
+import { guard as directEntityWrites } from "./guard-direct-entity-writes";
+import { guard as directFetch } from "./guard-direct-fetch";
+import { guard as escapeHatchDeclared } from "./guard-escape-hatch-declared";
+import { guard as fakeTests } from "./guard-fake-tests";
+import { guard as htmlEscape } from "./guard-html-escape";
+import { guard as noDateApi } from "./guard-no-date-api";
+import { guard as noDirectFs } from "./guard-no-direct-fs";
+import { guard as noLogicInViews } from "./guard-no-logic-in-views";
+import { guard as openToAllReason } from "./guard-open-to-all-reason";
+import { guard as preEsPatterns } from "./guard-pre-es-patterns";
+import { guard as restrictedSymbols } from "./guard-restricted-symbols";
+import { guard as silentSkip } from "./guard-silent-skip";
+import { guard as tenantEscalation } from "./guard-tenant-escalation";
+import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
+
+export const GUARDS = [
+  accessDeniedTest,
+  adminApi,
+  directEntityWrites,
+  directFetch,
+  escapeHatchDeclared,
+  noDirectFs,
+  openToAllReason,
+  tenantEscalation,
+  preEsPatterns,
+  unsafeJsonParse,
+  silentSkip,
+  htmlEscape,
+  crossFeatureImports,
+  noDateApi,
+  restrictedSymbols,
+  fakeTests,
+  noLogicInViews,
+];
+
+// Only run on direct invocation — otherwise `import { GUARDS }` would kick
+// off the whole suite and the list wouldn't be testable.
+if (import.meta.main) {
+  if (process.argv.includes("--explain")) {
+    for (const line of explainGuards(GUARDS, buildSharedProject(GUARDS))) {
+      console.log(line);
+    }
+    process.exit(0);
+  }
+  if (process.argv.includes("--write-security-baseline")) {
+    writeSecurityBaselines(
+      GUARDS.filter(isSecurityGuard),
+      buildSharedProject(GUARDS.filter(isSecurityGuard)),
+    );
+    process.exit(0);
+  }
+  const strictSecurityBaseline = process.argv.includes("--strict-security-baseline");
+  const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
+  const failed = reportResults(
+    runGuards(guards, buildSharedProject(guards), { strictSecurityBaseline }),
+  );
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/run-repo-checks.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env bun
+// Standalone-`main()` guards ported as RepoCheck — run in-process, no
+// per-guard subprocess/project.
+import { reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
+import { check as primitivesDiscipline } from "./guard-primitives-discipline";
+import { check as rawSql } from "./guard-raw-sql";
+import { check as rendererBoundaries } from "./guard-renderer-boundaries";
+import { check as thinWrappers } from "./guard-thin-wrappers";
+
+export const REPO_CHECKS = [
+  rawSql,
+  noDirectProcessEnv,
+  rendererBoundaries,
+  primitivesDiscipline,
+  thinWrappers,
+];
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks(REPO_CHECKS));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/run-ui-guards.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+// UI-guard bundle (App-Mounting 2.0, infra#208): one process, shared ts-morph
+// Project over the UI enforcement guards.
+import { reportResults, runGuards } from "./_lib/guard-kit";
+import { guard as noCustomPrimitives } from "./guard-no-custom-primitives";
+import { guard as noInlineStyles } from "./guard-no-inline-styles";
+import { guard as noRawHooks } from "./guard-no-raw-hooks";
+import { guard as rawClassname } from "./guard-raw-classname";
+import { guard as rawInteractiveElements } from "./guard-raw-interactive-elements";
+import { guard as tailwindScanSurface } from "./guard-tailwind-scan-surface";
+
+export const UI_GUARDS = [
+  rawClassname,
+  noInlineStyles,
+  noCustomPrimitives,
+  noRawHooks,
+  tailwindScanSurface,
+  rawInteractiveElements,
+];
+
+// Same as run-guards.ts: only run on direct invocation.
+if (import.meta.main) {
+  const failed = reportResults(runGuards(UI_GUARDS));
+  process.exit(failed > 0 ? 1 : 0);
+}