@cosmicdrift/kumiko-guards 0.356.0 → 0.357.0

package/src/guard-thin-wrappers.ts

@@ -32,6 +32,7 @@ import {
   type ArrowFunction,
   type FunctionDeclaration,
   type FunctionExpression,
+  type Node,
   Project,
   type SourceFile,
   SyntaxKind,
@@ -230,6 +231,38 @@ function getFnName(node: FnNode): string | undefined {
   return undefined;
 }
 
+function collectCalleeNames(node: FnNode): Set<string> {
+  const callees = new Set<string>();
+  node.forEachDescendant((n) => {
+    if (n.isKind(SyntaxKind.CallExpression)) {
+      const name = extractCalleeName(n);
+      if (name) callees.add(name);
+    }
+  });
+  return callees;
+}
+
+function wrapperCalleeName(callExpr: Node): string | null {
+  const name = extractCalleeName(callExpr);
+  if (!name) return null;
+  if (BUILTIN_NAMES.has(name)) return null;
+  return name;
+}
+
+// The single call expression a one-statement body consists of, if it has that shape.
+function singleStatementCall(single: Node): Node | null {
+  if (single.isKind(SyntaxKind.ReturnStatement)) {
+    const expr = single.getExpression();
+    // `return () => ...` is a factory, not a delegation
+    return expr?.isKind(SyntaxKind.CallExpression) ? expr : null;
+  }
+  if (single.isKind(SyntaxKind.ExpressionStatement)) {
+    const expr = single.getExpression();
+    return expr.isKind(SyntaxKind.CallExpression) ? expr : null;
+  }
+  return null;
+}
+
 function getSingleDirectCallee(node: FnNode): string | null {
   const rawBody =
     node.isKind(SyntaxKind.ArrowFunction) && !node.getBody().isKind(SyntaxKind.Block)
@@ -241,59 +274,21 @@ function getSingleDirectCallee(node: FnNode): string | null {
     const body = node.getBody();
     if (!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;
+    if (collectCalleeNames(node).size !== 1) return null;
+    return wrapperCalleeName(body);
   }
 
   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;
-  }
+  const callExpr = singleStatementCall(stmts.reduce((only) => only));
+  if (!callExpr) 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;
+  if (collectCalleeNames(node).size !== 1) return null;
 
-  return name;
+  return wrapperCalleeName(callExpr);
 }
 
 function extractCalleeName(callNode: ReturnType<FnNode["getBody"]> | undefined): string | null {
@@ -349,11 +344,13 @@ export function collectFindings(sf: SourceFile): Finding[] {
 
   const check = (node: FnNode) => {
     const fnName = getFnName(node);
+    // skip: anonymous functions cannot be reported by name
     if (!fnName) return;
 
     const callee = getSingleDirectCallee(node);
+    // skip: not a single-callee wrapper
     if (!callee) return;
-    // Self-recursion / delegation false-positive (same name)
+    // skip: self-recursion / same-name delegation is a false positive
     if (callee === fnName) return;
 
     const markerReason = extractMarkerReason(node);

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

@@ -1,14 +1,14 @@
 #!/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.
+ * Guard: checks that `dispatcher.write("qn:literal:...")` calls in
+ * custom screens reference valid write-handler QNs. Typos
+ * in the QN would otherwise only surface at runtime as a 404.
  *
- * 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.
+ * Validation in two stages:
+ *   1. **Structural**: every QN must contain `:write:` — catches
+ *      obvious typos ("feautre:write:create").
+ *   2. **Against manifest**: if `feature-manifest.json` is in the repo root
+ *      and contains `writeHandlers`, the guard matches against it.
  *
  * Usage:
  *   bun infra/guards/guard-write-handler-qns.ts
@@ -94,11 +94,11 @@ function findKnownQns(filePath: string, entries: ReadonlyArray<ManifestEntry>):
 }
 
 /**
- * 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.
+ * Extracts the literal value from a string literal, a backtick literal
+ * without interpolation (`NoSubstitutionTemplateLiteral`) or a
+ * `<literal> as T` cast. Backtick constants (`const QN = \`x:write:y\``)
+ * used to be recognized only as a direct argument, not as a resolved
+ * declaration.
  */
 function literalValueOf(node: Node): string | undefined {
   if (
@@ -137,8 +137,8 @@ export function resolveWriteQnFromArg(node: Node): string | undefined {
 }
 
 /**
- * Scannt eine SourceFile nach `dispatcher.write(<stringLiteral>, ...)`-
- * oder `<expr>.write(<stringLiteral>, ...)`-Aufrufen.
+ * Scans a SourceFile for `dispatcher.write(<stringLiteral>, ...)`
+ * or `<expr>.write(<stringLiteral>, ...)` calls.
  */
 export function scanDispatcherWriteCalls(
   sf: SourceFile,
@@ -148,14 +148,14 @@ export function scanDispatcherWriteCalls(
     const expr = call.getExpression();
     const exprText = expr.getText();
 
-    // `dispatcher.write(...)` oder irgendein `<obj>.write(...)` (ein
-    // aliaster Dispatcher heißt nicht zwingend "dispatcher").
+    // `dispatcher.write(...)` or any `<obj>.write(...)` (an aliased
+    // dispatcher is not necessarily named "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).
+    // The first parameter must be a string literal — dynamic QNs (handler
+    // constants, template literals) are not validated (they are either
+    // type-safe or not checkable).
     const args = call.getArguments();
     const first = args[0];
     if (!first) continue;
@@ -163,11 +163,11 @@ export function scanDispatcherWriteCalls(
     const qn = resolveWriteQnFromArg(first);
     if (qn === undefined) continue;
 
-    // `.endsWith(".write")` matcht auch Nicht-Dispatcher-Writes:
+    // `.endsWith(".write")` also matches non-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:").
+    // Their argument is not a QN → it would otherwise be reported as an
+    // "invalid QN format" false positive. Outside an explicit `dispatcher.write`
+    // only check when the literal is a write QN (contains ":write:").
     if (!isDispatcherCall && !qn.includes(":write:")) continue;
 
     hits.push({
@@ -212,9 +212,9 @@ export const guard: AstGuard = {
           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.
+        // Stage 2: match against the manifest (if present).
+        // The QN is normalized to kebab-case before the match, so that
+        // camelCase and kebab-case inputs are treated the same.
         const normalizedQn = toKebab(hit.qn);
         if (knownQns.size > 0 && !knownQns.has(normalizedQn)) {
           violations.push({
@@ -226,8 +226,8 @@ export const guard: AstGuard = {
       }
     }
 
-    // Info-Log wenn kein Manifest geladen wurde — kein Fehler, aber
-    // der Guard läuft dann nur mit struktureller Prüfung.
+    // Info log when no manifest was loaded — not an error, but
+    // the guard then runs with the structural check only.
     if (knownQnsByRepo.size === 0 && violations.length === 0) {
       console.warn(
         "  [INFO] No feature-manifest.json with writeHandlers found — structural check only.",

package/src/runtime-isolation-classify.ts

@@ -421,9 +421,10 @@ export function findRuntimeIsolationViolations(
   const outsideRoot: string[] = [];
   const seenOutside = new Set<string>();
   const noteOutside = (fp: string) => {
-    if (seenOutside.has(fp)) return;
-    seenOutside.add(fp);
-    outsideRoot.push(fp);
+    if (!seenOutside.has(fp)) {
+      seenOutside.add(fp);
+      outsideRoot.push(fp);
+    }
   };
   const stats: Record<Runtime, number> = {
     runtime: 0,