@cosmicdrift/kumiko-guards 0.1.1 → 0.3.0

package/src/guard-write-handler-qns.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env bun
+/**
+ * Guard: prüft dass `dispatcher.write("qn:literal:...")`-Aufrufe in
+ * Custom-Screens gültige Write-Handler-QNs referenzieren. Tippfehler
+ * im QN fallen sonst erst zur Runtime als 404 auf.
+ *
+ * Validierung in zwei Stufen:
+ *   1. **Strukturell**: jeder QN muss `:write:` enthalten — fängt
+ *      offensichtliche Tippfehler ("feautre:write:create").
+ *   2. **Gegen Manifest**: wenn `feature-manifest.json` im Repo-Root
+ *      liegt und `writeHandlers` enthält, matched der Guard dagegen.
+ *
+ * Usage:
+ *   bun infra/guards/guard-write-handler-qns.ts
+ */
+import { existsSync, readFileSync } from "node:fs";
+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";
+import { toKebab, VALID_QN_RE } from "./_lib/qn";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+
+export { toKebab, VALID_QN_RE };
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["tsx"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+// Tests nutzen absichtlich generische QNs wie dispatcher.write("x", {}).
+const EXCLUDE = /(__tests__|\.test\.tsx$|\.integration\.tsx$|\/node_modules\/|\/dist\/)/;
+
+/**
+ * Reads writeHandlers per manifest found under each repo root, keyed by
+ * the manifest's own directory. Stage-2 matching is subtree-scoped to that
+ * directory — prevents cross-app false positives when a repo hosts several
+ * independent sample apps, each with its own (or no) manifest.
+ */
+interface ManifestEntry {
+  readonly baseDir: string;
+  readonly known: Set<string>;
+}
+
+function loadKnownQnsByRepo(roots: ReadonlyArray<RepoRoot>): Map<string, ManifestEntry[]> {
+  const byRepo = new Map<string, ManifestEntry[]>();
+
+  const manifestCandidates = [
+    "feature-manifest.json",
+    "samples/apps/use-all-bundled/feature-manifest.json",
+  ];
+
+  for (const repo of roots) {
+    const entries: ManifestEntry[] = [];
+    for (const rel of manifestCandidates) {
+      const manifestPath = path.join(repo.absPath, rel);
+      if (!existsSync(manifestPath)) continue;
+      try {
+        const raw = readFileSync(manifestPath, "utf-8");
+        const manifest = JSON.parse(raw) as {
+          readonly features?: ReadonlyArray<{
+            readonly writeHandlers?: readonly string[];
+          }>;
+        };
+        if (!manifest.features) continue;
+        const known = new Set<string>();
+        for (const f of manifest.features) {
+          if (f.writeHandlers) {
+            for (const qn of f.writeHandlers) known.add(qn);
+          }
+        }
+        if (known.size > 0) {
+          entries.push({ baseDir: path.dirname(manifestPath), known });
+        }
+      } catch (err) {
+        console.warn(`[WARN] Manifest ${manifestPath} not readable: ${err}`);
+      }
+    }
+    if (entries.length > 0) byRepo.set(repo.absPath, entries);
+  }
+  return byRepo;
+}
+
+/** Picks the manifest whose base directory is the longest prefix of `filePath`. */
+function findKnownQns(filePath: string, entries: ReadonlyArray<ManifestEntry>): Set<string> {
+  let best: ManifestEntry | undefined;
+  for (const entry of entries) {
+    if (filePath !== entry.baseDir && !filePath.startsWith(`${entry.baseDir}${path.sep}`)) continue;
+    if (!best || entry.baseDir.length > best.baseDir.length) best = entry;
+  }
+  return best?.known ?? new Set<string>();
+}
+
+/**
+ * Extrahiert den Literal-Wert aus einem String-Literal, einem
+ * Backtick-Literal ohne Interpolation (`NoSubstitutionTemplateLiteral`) oder
+ * einem `<literal> as T`-Cast. Backtick-Konstanten (`const QN = \`x:write:y\``)
+ * wurden vorher nur als direktes Argument, nicht als aufgelöste Deklaration
+ * erkannt.
+ */
+function literalValueOf(node: Node): string | undefined {
+  if (
+    node.isKind(SyntaxKind.StringLiteral) ||
+    node.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+  ) {
+    return node.getLiteralValue();
+  }
+  if (node.isKind(SyntaxKind.AsExpression)) {
+    return literalValueOf(node.getExpression());
+  }
+  return undefined;
+}
+
+/** Resolve Handler-constant refs (`Handlers.foo`) to string literals when static. */
+export function resolveWriteQnFromArg(node: Node): string | undefined {
+  const direct = literalValueOf(node);
+  if (direct !== undefined) return direct;
+
+  if (!node.isKind(SyntaxKind.Identifier) && !node.isKind(SyntaxKind.PropertyAccessExpression)) {
+    return undefined;
+  }
+
+  const symbol = node.getSymbol() ?? node.getType().getSymbol();
+  if (!symbol) return undefined;
+
+  for (const decl of symbol.getDeclarations()) {
+    if (decl.isKind(SyntaxKind.PropertyAssignment) || decl.isKind(SyntaxKind.VariableDeclaration)) {
+      const init = decl.getInitializer();
+      const value = init ? literalValueOf(init) : undefined;
+      if (value !== undefined) return value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Scannt eine SourceFile nach `dispatcher.write(<stringLiteral>, ...)`-
+ * oder `<expr>.write(<stringLiteral>, ...)`-Aufrufen.
+ */
+export function scanDispatcherWriteCalls(
+  sf: SourceFile,
+): Array<{ line: number; qn: string; snippet: string }> {
+  const hits: Array<{ line: number; qn: string; snippet: string }> = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const expr = call.getExpression();
+    const exprText = expr.getText();
+
+    // `dispatcher.write(...)` oder irgendein `<obj>.write(...)` (ein
+    // aliaster Dispatcher heißt nicht zwingend "dispatcher").
+    const isDispatcherCall = exprText === "dispatcher.write";
+    if (!isDispatcherCall && !exprText.endsWith(".write")) continue;
+
+    // Erster Parameter muss ein String-Literal sein — dynamische
+    // QNs (Handler-Konstanten, Template-Literale) werden nicht
+    // validiert (sind entweder typ-safe oder nicht prüfbar).
+    const args = call.getArguments();
+    const first = args[0];
+    if (!first) continue;
+
+    const qn = resolveWriteQnFromArg(first);
+    if (qn === undefined) continue;
+
+    // `.endsWith(".write")` matcht auch Nicht-Dispatcher-Writes:
+    // `res.write(...)`, `stream.write(...)`, SSE `res.write("data: …")`.
+    // Deren Argument ist kein QN → würde sonst als "ungültiges QN-Format"
+    // false-positiv gemeldet. Außerhalb eines expliziten `dispatcher.write`
+    // nur prüfen, wenn das Literal ein Write-QN ist (enthält ":write:").
+    if (!isDispatcherCall && !qn.includes(":write:")) continue;
+
+    hits.push({
+      line: call.getStartLineNumber(),
+      qn,
+      snippet: call.getText().slice(0, 120),
+    });
+  }
+  return hits;
+}
+
+export const guard: AstGuard = {
+  name: "Write-Handler-QN Guard",
+  scan: SCAN,
+  hint: "Typo in the write-handler QN? Check feature name + handler name.",
+  run(files) {
+    const roots = resolveRepoRoots();
+    const knownQnsByRepo = loadKnownQnsByRepo(roots);
+
+    const violations: Array<{
+      file: string;
+      line: number;
+      message: string;
+    }> = [];
+
+    for (const sf of files) {
+      const filePath = sf.getFilePath();
+      if (EXCLUDE.test(filePath)) continue;
+
+      const repo = roots.find((r) => filePath.startsWith(`${r.absPath}${path.sep}`));
+      const knownQns = repo
+        ? findKnownQns(filePath, knownQnsByRepo.get(repo.absPath) ?? [])
+        : new Set<string>();
+
+      for (const hit of scanDispatcherWriteCalls(sf)) {
+        // Stufe 1: strukturelle Validierung
+        if (!VALID_QN_RE.test(hit.qn)) {
+          violations.push({
+            file: path.relative(ROOT, filePath),
+            line: hit.line,
+            message: `invalid QN format: "${hit.qn}" — must match "<feature>:write:<handler>"`,
+          });
+          continue;
+        }
+
+        // Stufe 2: gegen Manifest matchen (wenn vorhanden).
+        // QN wird vor dem Match auf kebab-case normalisiert, sodass
+        // camelCase- und kebab-case-Eingaben gleich behandelt werden.
+        const normalizedQn = toKebab(hit.qn);
+        if (knownQns.size > 0 && !knownQns.has(normalizedQn)) {
+          violations.push({
+            file: path.relative(ROOT, filePath),
+            line: hit.line,
+            message: `unknown write handler: "${hit.qn}" — not found in feature-manifest.json`,
+          });
+        }
+      }
+    }
+
+    // Info-Log wenn kein Manifest geladen wurde — kein Fehler, aber
+    // der Guard läuft dann nur mit struktureller Prüfung.
+    if (knownQnsByRepo.size === 0 && violations.length === 0) {
+      console.warn(
+        "  [INFO] No feature-manifest.json with writeHandlers found — structural check only.",
+      );
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/run-guards.ts

@@ -11,27 +11,44 @@ import {
   buildSharedProject,
   explainGuards,
   isSecurityGuard,
+  printGuardKitBanner,
   reportResults,
   runGuards,
 } from "./_lib/guard-kit";
 import { writeSecurityBaselines } from "./_lib/security-baseline-cli";
+import { guard as asCasts } from "./check-as-casts";
+import { guard as complexity } from "./check-complexity";
+import { guard as predicateExtraction } from "./check-predicates";
 import { guard as accessDeniedTest } from "./guard-access-denied-test";
 import { guard as adminApi } from "./guard-admin-api";
+import { guard as appFeatureStructure } from "./guard-app-feature-structure";
+import { guard as brokerSubscribe } from "./guard-broker-subscribe";
 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 errorReasons } from "./guard-error-reasons";
 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 i18nKeys } from "./guard-i18n-keys";
+import { guard as i18nLocaleMount } from "./guard-i18n-locale-mount";
+import { guard as i18nLocaleTerminology } from "./guard-i18n-locale-terminology";
+import { guard as libTestCoverage } from "./guard-lib-test-coverage";
+import { guard as loadallEvents } from "./guard-loadall-events";
 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 piiAnnotations } from "./guard-pii-annotations";
 import { guard as preEsPatterns } from "./guard-pre-es-patterns";
 import { guard as restrictedSymbols } from "./guard-restricted-symbols";
+import { guard as screenConventions } from "./guard-screen-conventions";
 import { guard as silentSkip } from "./guard-silent-skip";
+import { guard as tableDdl } from "./guard-table-ddl";
 import { guard as tenantEscalation } from "./guard-tenant-escalation";
+import { guard as textFieldStance } from "./guard-text-field-stance";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
+import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 
 export const GUARDS = [
   accessDeniedTest,
@@ -51,6 +68,22 @@ export const GUARDS = [
   restrictedSymbols,
   fakeTests,
   noLogicInViews,
+  brokerSubscribe,
+  errorReasons,
+  i18nKeys,
+  i18nLocaleMount,
+  i18nLocaleTerminology,
+  piiAnnotations,
+  textFieldStance,
+  complexity,
+  predicateExtraction,
+  screenConventions,
+  writeHandlerQns,
+  asCasts,
+  loadallEvents,
+  tableDdl,
+  appFeatureStructure,
+  libTestCoverage,
 ];
 
 // Only run on direct invocation — otherwise `import { GUARDS }` would kick
@@ -71,8 +104,8 @@ if (import.meta.main) {
   }
   const strictSecurityBaseline = process.argv.includes("--strict-security-baseline");
   const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
-  const failed = reportResults(
-    runGuards(guards, buildSharedProject(guards), { strictSecurityBaseline }),
-  );
+  const project = buildSharedProject(guards);
+  printGuardKitBanner(guards.length, project);
+  const failed = reportResults(runGuards(guards, project, { strictSecurityBaseline }));
   process.exit(failed > 0 ? 1 : 0);
 }

package/src/run-repo-checks.ts

@@ -1,11 +1,14 @@
 #!/usr/bin/env bun
+import { printGuardKitBanner, reportResults, runRepoChecks } from "./_lib/guard-kit";
 // Standalone-`main()` guards ported as RepoCheck — run in-process, no
 // per-guard subprocess/project.
-import { reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { check as secretLiterals } from "./check-secret-literals";
+import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 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 testStackDrift } from "./guard-test-stack-drift";
 import { check as thinWrappers } from "./guard-thin-wrappers";
 
 export const REPO_CHECKS = [
@@ -14,9 +17,15 @@ export const REPO_CHECKS = [
   rendererBoundaries,
   primitivesDiscipline,
   thinWrappers,
+  secretLiterals,
+  featureIntegrationTests,
+  testStackDrift,
 ];
 
 if (import.meta.main) {
+  // No shared ts-morph Project here — RepoCheck.run() does its own file
+  // walk per check, so the banner omits the "Project: N files" line.
+  printGuardKitBanner(REPO_CHECKS.length);
   const failed = reportResults(await runRepoChecks(REPO_CHECKS));
   process.exit(failed > 0 ? 1 : 0);
 }

package/src/run-ui-guards.ts

@@ -1,7 +1,13 @@
 #!/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 {
+  buildSharedProject,
+  printGuardKitBanner,
+  reportResults,
+  runGuards,
+} from "./_lib/guard-kit";
+import { guard as i18nUiStrings } from "./guard-i18n-ui-strings";
 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";
@@ -16,10 +22,13 @@ export const UI_GUARDS = [
   noRawHooks,
   tailwindScanSurface,
   rawInteractiveElements,
+  i18nUiStrings,
 ];
 
 // Same as run-guards.ts: only run on direct invocation.
 if (import.meta.main) {
-  const failed = reportResults(runGuards(UI_GUARDS));
+  const project = buildSharedProject(UI_GUARDS);
+  printGuardKitBanner(UI_GUARDS.length, project);
+  const failed = reportResults(runGuards(UI_GUARDS, project));
   process.exit(failed > 0 ? 1 : 0);
 }