@cosmicdrift/kumiko-guards 0.333.0 → 0.335.0

package/src/guard-no-framed-extension-sections.ts

@@ -59,32 +59,65 @@ function isExternalSourceFile(sf: SourceFile): boolean {
   return sf.getFilePath().includes("/node_modules/");
 }
 
+function addRegistryMembers(
+  sf: SourceFile,
+  literal: ObjectLiteralExpression,
+  entries: Map<string, string>,
+  visited: Set<Node>,
+): void {
+  if (visited.has(literal)) return;
+  visited.add(literal);
+  for (const member of literal.getProperties()) {
+    // { NOTES_SECTION_EXTENSION_NAME: NotesSection } (PropertyAssignment,
+    // possibly computed-key) or { NotesSection } (ShorthandPropertyAssignment).
+    if (Node.isPropertyAssignment(member)) {
+      const valueInit = member.getInitializer();
+      if (valueInit === undefined || valueInit.getKind() !== SyntaxKind.Identifier) continue;
+      const nameNode = member.getNameNode();
+      const key = Node.isComputedPropertyName(nameNode)
+        ? nameNode.getExpression().getText()
+        : Node.isStringLiteral(nameNode)
+          ? nameNode.getLiteralValue()
+          : member.getName();
+      entries.set(valueInit.getText(), key);
+    } else if (Node.isShorthandPropertyAssignment(member)) {
+      const name = member.getName();
+      entries.set(name, name);
+    } else if (Node.isSpreadAssignment(member)) {
+      addRegistryFromExpression(sf, member.getExpression(), entries, visited);
+    }
+  }
+}
+
+// The registry may be inline, a same-file variable (`extensionSectionComponents:
+// shared`, `{ extensionSectionComponents }`) or spread in (`{ ...shared }`).
+function addRegistryFromExpression(
+  sf: SourceFile,
+  expression: Node,
+  entries: Map<string, string>,
+  visited: Set<Node>,
+): void {
+  if (Node.isObjectLiteralExpression(expression)) {
+    addRegistryMembers(sf, expression, entries, visited);
+    return;
+  }
+  if (!Node.isIdentifier(expression)) return;
+  const init = sf.getVariableDeclaration(expression.getText())?.getInitializer();
+  if (init !== undefined) addRegistryFromExpression(sf, init, entries, visited);
+}
+
 /** Maps each registered component's identifier to the registry key usage sites reference via `__component: SOME_CONST`. */
 function findExtensionComponentEntries(sf: SourceFile): Map<string, string> {
   const entries = new Map<string, string>();
+  const visited = new Set<Node>();
   for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     if (prop.getName() !== "extensionSectionComponents") continue;
     const init = prop.getInitializer();
-    if (init === undefined || init.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
-    for (const member of init.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperties()) {
-      // { NOTES_SECTION_EXTENSION_NAME: NotesSection } (PropertyAssignment,
-      // possibly computed-key) or { NotesSection } (ShorthandPropertyAssignment).
-      if (member.getKind() === SyntaxKind.PropertyAssignment) {
-        const pa = member.asKindOrThrow(SyntaxKind.PropertyAssignment);
-        const valueInit = pa.getInitializer();
-        if (valueInit === undefined || valueInit.getKind() !== SyntaxKind.Identifier) continue;
-        const nameNode = pa.getNameNode();
-        const key = Node.isComputedPropertyName(nameNode)
-          ? nameNode.getExpression().getText()
-          : Node.isStringLiteral(nameNode)
-            ? nameNode.getLiteralValue()
-            : pa.getName();
-        entries.set(valueInit.getText(), key);
-      } else if (member.getKind() === SyntaxKind.ShorthandPropertyAssignment) {
-        const name = member.asKindOrThrow(SyntaxKind.ShorthandPropertyAssignment).getName();
-        entries.set(name, name);
-      }
-    }
+    if (init !== undefined) addRegistryFromExpression(sf, init, entries, visited);
+  }
+  for (const prop of sf.getDescendantsOfKind(SyntaxKind.ShorthandPropertyAssignment)) {
+    if (prop.getName() !== "extensionSectionComponents") continue;
+    addRegistryFromExpression(sf, prop.getNameNode(), entries, visited);
   }
   return entries;
 }

package/src/guard-open-to-all-reason.ts

@@ -12,7 +12,7 @@
  *
  * Usage:
  *   bun guards/guard-open-to-all-reason.ts
- *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ *   Baseline: kumiko-guards guards --write-security-baseline
  */
 import * as path from "node:path";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -85,7 +85,7 @@ export function createOpenToAllReasonGuard(opts: { root: string }): AstGuard {
     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: `bun guards/run-guards.ts --write-security-baseline`',
+    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) => ({

package/src/guard-raw-sql.ts

@@ -14,7 +14,12 @@
 
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-import { BLOCKING_SQL_KINDS, scanRepo, sqlScanDirsFor } from "./_lib/sql-inventory";
+import {
+  BLOCKING_SQL_KINDS,
+  isSqlScanExcluded,
+  scanRepo,
+  sqlScanDirsFor,
+} from "./_lib/sql-inventory";
 
 export type RawSqlFinding = {
   readonly repo: string;
@@ -65,8 +70,9 @@ export const check: RepoCheck = {
     "Rule: runtime SQL only in db/queries/*, bun-db/query.ts, testing/*, or with " +
     "// kumiko-lint-ignore raw-sql <reason> on the line or the line above.",
   async run(roots) {
-    // kumiko-platform's deliberate empty scan-dir list must not read as vacuous (infra#610).
-    const applicableRoots = roots.filter((r) => sqlScanDirsFor(r).length > 0);
+    // Only the deliberate exclusion is skipped; a repo whose declared source roots
+    // are all missing stays in the scan so 0 files surfaces as vacuous.
+    const applicableRoots = roots.filter((r) => !isSqlScanExcluded(r));
     if (applicableRoots.length === 0) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }

package/src/guard-section-fields-raw.ts

@@ -11,7 +11,9 @@
  * generator in #3042). `sectionFieldSpecs` (engine/screen-helpers.ts) is the
  * one reader that unions both sources.
  *
- * Flagged: for-of, spread and array reads over `<…section…>.fields`.
+ * Flagged: for-of, spread, array reads, indexing, call arguments and
+ * destructuring over the `fields` of a section (by name or by a `groups`
+ * property on its type), also behind `!`, parentheses, `as` and `??`.
  * Known gap: `section.fields.length` is not flagged — the fields-XOR-groups
  * validator itself needs it, and an emptiness check is not the silent-
  * iteration bug.
@@ -35,7 +37,13 @@
  *   bun guards/guard-section-fields-raw.ts --no-baseline    # skip comparison
  */
 import * as path from "node:path";
-import { type Node, type PropertyAccessExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type Node,
+  type PropertyAccessExpression,
+  type SourceFile,
+  SyntaxKind,
+  type VariableDeclaration,
+} from "ts-morph";
 import {
   type AstGuard,
   baselineRatchet,
@@ -68,9 +76,10 @@ const SCAN: ScanSpec = {
 const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
 
 const IGNORE_TAG = "kumiko-lint-ignore section-fields-raw";
-// hasIgnoreTag() from _lib accepts a bare tag; the issue's premise 2 wants a
-// visible reason, so the trailing `\S` is the whole point of not reusing it.
-const REASONED_TAG = new RegExp(`${IGNORE_TAG}\\s+\\S`);
+// hasIgnoreTag() from _lib accepts a bare tag; a visible reason is required, so
+// the reason must start with a real character: the `*` of a closing `*/` (block
+// and JSX comments) must not count as one.
+const REASONED_TAG = new RegExp(`${IGNORE_TAG}\\s+(?!\\*/)[^\\s*]`);
 
 const SECTION_RECEIVER = /section/i;
 
@@ -83,6 +92,7 @@ const ARRAY_READS = new Set([
   "find",
   "findIndex",
   "findLast",
+  "findLastIndex",
   "flat",
   "flatMap",
   "forEach",
@@ -90,6 +100,7 @@ const ARRAY_READS = new Set([
   "indexOf",
   "join",
   "keys",
+  "lastIndexOf",
   "map",
   "reduce",
   "reduceRight",
@@ -99,7 +110,9 @@ const ARRAY_READS = new Set([
   "sort",
   "toReversed",
   "toSorted",
+  "toSpliced",
   "values",
+  "with",
 ]);
 
 function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
@@ -112,19 +125,68 @@ function hasReasonedIgnoreTag(node: Node): boolean {
   return REASONED_TAG.test(lines[line - 1] ?? "") || REASONED_TAG.test(lines[line - 2] ?? "");
 }
 
+// A section is recognised by its name or, when types resolve, by carrying a
+// `groups` property — so `sec.fields` and `layout.sections.map((s) => s.fields)`
+// are caught too. The name regex stays as the fallback for untyped receivers.
+function isSectionReceiver(receiver: Node): boolean {
+  if (SECTION_RECEIVER.test(receiver.getText())) return true;
+  return receiver.getType().getProperty("groups") !== undefined;
+}
+
+// Climbs `x!`, `(x)`, `x as T` and `x ?? y` so a wrapped read is judged by the
+// context it ends up in.
+function unwrapReadContext(access: Node): Node {
+  let current = access;
+  for (;;) {
+    const parent = current.getParent();
+    if (
+      parent !== undefined &&
+      (parent.isKind(SyntaxKind.NonNullExpression) ||
+        parent.isKind(SyntaxKind.ParenthesizedExpression) ||
+        parent.isKind(SyntaxKind.AsExpression) ||
+        (parent.isKind(SyntaxKind.BinaryExpression) &&
+          parent.getOperatorToken().getKind() === SyntaxKind.QuestionQuestionToken &&
+          parent.getLeft() === current))
+    ) {
+      current = parent;
+      continue;
+    }
+    return current;
+  }
+}
+
 function isSequenceRead(access: PropertyAccessExpression): boolean {
-  const parent = access.getParent();
+  const read = unwrapReadContext(access);
+  const parent = read.getParent();
   if (parent === undefined) return false;
-  if (parent.isKind(SyntaxKind.ForOfStatement)) return parent.getExpression() === access;
+  if (parent.isKind(SyntaxKind.ForOfStatement)) return parent.getExpression() === read;
   if (parent.isKind(SyntaxKind.SpreadElement) || parent.isKind(SyntaxKind.SpreadAssignment)) {
     return true;
   }
-  if (parent.isKind(SyntaxKind.PropertyAccessExpression) && ARRAY_READS.has(parent.getName())) {
+  if (parent.isKind(SyntaxKind.ElementAccessExpression)) return parent.getExpression() === read;
+  if (parent.isKind(SyntaxKind.CallExpression)) return parent.getArguments().includes(read);
+  if (
+    parent.isKind(SyntaxKind.PropertyAccessExpression) &&
+    parent.getExpression() === read &&
+    ARRAY_READS.has(parent.getName())
+  ) {
     return parent.getParent()?.isKind(SyntaxKind.CallExpression) === true;
   }
   return false;
 }
 
+function isDestructuredFieldsRead(declaration: VariableDeclaration): boolean {
+  const pattern = declaration.getNameNode();
+  const initializer = declaration.getInitializer();
+  if (!pattern.isKind(SyntaxKind.ObjectBindingPattern) || initializer === undefined) return false;
+  if (!isSectionReceiver(initializer)) return false;
+  return pattern
+    .getElements()
+    .some(
+      (element) => (element.getPropertyNameNode() ?? element.getNameNode()).getText() === "fields",
+    );
+}
+
 export interface Finding {
   file: string;
   line: number;
@@ -138,7 +200,7 @@ export function scanRawSectionFieldReads(
   const findings: Finding[] = [];
   for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
     if (access.getName() !== "fields") continue;
-    if (!SECTION_RECEIVER.test(access.getExpression().getText())) continue;
+    if (!isSectionReceiver(access.getExpression())) continue;
     if (!isSequenceRead(access)) continue;
     if (hasReasonedIgnoreTag(access)) continue;
     const line = access.getStartLineNumber();
@@ -148,6 +210,16 @@ export function scanRawSectionFieldReads(
       `  [section-fields-raw WARN] ${file}:${line}  raw read of ${access.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
     );
   }
+  for (const declaration of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+    if (!isDestructuredFieldsRead(declaration)) continue;
+    if (hasReasonedIgnoreTag(declaration)) continue;
+    const line = declaration.getStartLineNumber();
+    const file = relFile(sf, roots);
+    findings.push({ file, line, snippet: declaration.getText().slice(0, 80) });
+    console.warn(
+      `  [section-fields-raw WARN] ${file}:${line}  destructured fields of ${declaration.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
+    );
+  }
   return findings;
 }
 

package/src/guard-test-stack-drift.ts

@@ -94,8 +94,18 @@ function collectCallNames(sf: SourceFile): Map<string, number[]> {
   return calls;
 }
 
+// Only a marker inside a real comment counts: the same text
+// inside a string/template literal is fixture data, not an opt-out.
 function hasOptOutMarker(sf: SourceFile): boolean {
-  return OPT_OUT_MARKER.test(sf.getFullText());
+  const text = sf.getFullText();
+  const marker = new RegExp(OPT_OUT_MARKER.source, "gi");
+  for (const match of text.matchAll(marker)) {
+    const kind = sf.getDescendantAtPos(match.index)?.getKind();
+    if (kind === SyntaxKind.SingleLineCommentTrivia || kind === SyntaxKind.MultiLineCommentTrivia) {
+      return true;
+    }
+  }
+  return false;
 }
 
 export function scanFile(sf: SourceFile): Violation | null {

package/src/guard-test-template-drift.ts

@@ -74,6 +74,16 @@ const RAW_DEFINE_CONFIG_MODULE = "@playwright/test";
 
 const TEMPLATE_OWNED_KEYS: ReadonlySet<string> = new Set(["viewport", "deviceScaleFactor"]);
 
+// Top-level config keys the template owns; spreading defineAppE2eConfig(...)
+// and then setting one of them re-opens the drift the template closes.
+const TEMPLATE_OWNED_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  "fullyParallel",
+  "retries",
+  "timeout",
+  "workers",
+  "expect",
+]);
+
 export interface Finding {
   file: string;
   line: number;
@@ -148,7 +158,11 @@ function isPlaywrightUseObject(node: Node): boolean {
 function templateOwnedKeyFindings(sf: SourceFile): Finding[] {
   const findings: Finding[] = [];
   const isConfigFile = CONFIG_FILENAME.test(sf.getFilePath());
-  for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+  const props = [
+    ...sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment),
+    ...sf.getDescendantsOfKind(SyntaxKind.ShorthandPropertyAssignment),
+  ];
+  for (const prop of props) {
     const name = prop.getName();
     if (!TEMPLATE_OWNED_KEYS.has(name)) continue;
     // viewport is only drift in the config's own use/project use — a spec's
@@ -170,6 +184,34 @@ function templateOwnedKeyFindings(sf: SourceFile): Finding[] {
   return findings;
 }
 
+function isDefineAppE2eConfigSpread(node: Node): boolean {
+  if (!Node.isSpreadAssignment(node)) return false;
+  const spread = node.getExpression();
+  return (
+    Node.isCallExpression(spread) && spread.getExpression().getText() === DEFINE_APP_E2E_CONFIG
+  );
+}
+
+function configOverrideFindings(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  for (const literal of sf.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+    const properties = literal.getProperties();
+    if (!properties.some(isDefineAppE2eConfigSpread)) continue;
+    for (const prop of properties) {
+      if (!Node.isPropertyAssignment(prop) && !Node.isShorthandPropertyAssignment(prop)) continue;
+      const name = prop.getName();
+      if (!TEMPLATE_OWNED_CONFIG_KEYS.has(name)) continue;
+      const message = withExceptionNote(
+        prop,
+        `Config key "${name}" next to a ...defineAppE2eConfig(...) spread — timeouts, retries, workers and expect belong to the template; pass the supported options to defineAppE2eConfig instead.`,
+      );
+      if (message !== undefined)
+        findings.push({ file: "", line: prop.getStartLineNumber(), message });
+    }
+  }
+  return findings;
+}
+
 function isPageScreenshotCall(call: Node): boolean {
   if (!Node.isCallExpression(call)) return false;
   const callee = call.getExpression();
@@ -202,7 +244,11 @@ export function scanTemplateDrift(
   const findings: Finding[] = [];
   const own = ownConfigFinding(sf);
   if (own !== undefined) findings.push({ ...own, file });
-  for (const f of [...templateOwnedKeyFindings(sf), ...pageScreenshotFindings(sf)]) {
+  for (const f of [
+    ...templateOwnedKeyFindings(sf),
+    ...configOverrideFindings(sf),
+    ...pageScreenshotFindings(sf),
+  ]) {
     findings.push({ ...f, file });
   }
   return findings.sort((a, b) => a.line - b.line);

package/src/guard-upgrade-state.ts

@@ -109,9 +109,12 @@ export function pendingViolations(json: UpgradeJson, markerVersion: string): Gua
   }));
 }
 
-function resolveKumikoUpgradeBin(cwd: string): string | undefined {
-  const which = Bun.which("kumiko-upgrade");
-  if (which) return which;
+export function resolveKumikoUpgradeBin(
+  cwd: string,
+  pathEnv: string | undefined = process.env["PATH"],
+): string | undefined {
+  // Repo-pinned binary wins over PATH so the marker is measured against the
+  // version this checkout actually installs.
   let dir = cwd;
   for (;;) {
     const candidate = join(dir, "node_modules", ".bin", "kumiko-upgrade");
@@ -120,7 +123,7 @@ function resolveKumikoUpgradeBin(cwd: string): string | undefined {
     if (parent === dir) break;
     dir = parent;
   }
-  return undefined;
+  return Bun.which("kumiko-upgrade", { PATH: pathEnv }) ?? undefined;
 }
 
 async function runKumikoUpgrade(

package/src/run-guards.ts

@@ -169,5 +169,6 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
 // 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) {
-  process.exit(runGuardsCli(process.argv.slice(2)));
+  // Exit codes wrap at 256, so a raw failure count could read as success.
+  process.exit(runGuardsCli(process.argv.slice(2)) > 0 ? 1 : 0);
 }

package/src/run-repo-checks.ts

@@ -49,5 +49,5 @@ export async function runRepoChecksCli(argv: readonly string[]): Promise<number>
 }
 
 if (import.meta.main) {
-  process.exit(await runRepoChecksCli(process.argv.slice(2)));
+  process.exit((await runRepoChecksCli(process.argv.slice(2))) > 0 ? 1 : 0);
 }

package/src/run-ui-guards.ts

@@ -47,5 +47,5 @@ export function runUiGuardsCli(argv: readonly string[]): number {
 
 // Same as run-guards.ts: only run on direct invocation.
 if (import.meta.main) {
-  process.exit(runUiGuardsCli(process.argv.slice(2)));
+  process.exit(runUiGuardsCli(process.argv.slice(2)) > 0 ? 1 : 0);
 }