@cosmicdrift/kumiko-guards 0.386.0 → 0.388.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-guards
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.386.0",
+  "version": "0.388.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.386.0"
+    "@cosmicdrift/kumiko-framework": "0.388.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.386.0"
+    "@cosmicdrift/kumiko-framework": "0.388.0"
   }
 }

package/src/_lib/agent-docs.ts

@@ -336,14 +336,21 @@ function renderExamplesIndex(recipes: readonly Recipe[]): string {
   );
 }
 
+const RECIPE_SKIPPED_DIRS = new Set(["node_modules", "screenshots", "dist"]);
+const GENERATED_FILE = /\.generated\./;
+
 function listSourceFiles(dir: string, prefix = ""): string[] {
   if (!existsSync(dir)) return [];
   const found: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
     if (entry.isDirectory()) {
-      found.push(...listSourceFiles(join(dir, entry.name), rel));
-    } else if (SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) {
+      if (!RECIPE_SKIPPED_DIRS.has(entry.name))
+        found.push(...listSourceFiles(join(dir, entry.name), rel));
+    } else if (
+      SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension)) &&
+      !GENERATED_FILE.test(entry.name)
+    ) {
       found.push(rel);
     }
   }
@@ -362,13 +369,11 @@ function renderRecipe(recipe: Recipe): string {
   if (existsSync(readmePath)) {
     parts.push(`## README\n\n${readFileSync(readmePath, "utf-8").replace(/\r\n/g, "\n").trim()}`);
   }
-  const sourceBlocks = listSourceFiles(join(recipe.dir, "src")).map((rel) => {
-    const content = readFileSync(join(recipe.dir, "src", rel), "utf-8")
-      .replace(/\r\n/g, "\n")
-      .trimEnd();
+  const sourceBlocks = listSourceFiles(recipe.dir).map((rel) => {
+    const content = readFileSync(join(recipe.dir, rel), "utf-8").replace(/\r\n/g, "\n").trimEnd();
     const fence = fenceFor(content);
     const language = rel.endsWith(".tsx") ? "tsx" : "ts";
-    return `### src/${rel}\n\n${fence}${language}\n${content}\n${fence}`;
+    return `### ${rel}\n\n${fence}${language}\n${content}\n${fence}`;
   });
   if (sourceBlocks.length > 0) parts.push(`## Source files\n\n${sourceBlocks.join("\n\n")}`);
   return finishFile(`${RECIPES_REL}/${recipe.slug}`, parts.join("\n\n"));

package/src/_lib/comment-trivia.ts

@@ -0,0 +1,148 @@
+import { ts } from "ts-morph";
+
+export const COMMENT_KIND_LINE = "line";
+export const COMMENT_KIND_BLOCK = "block";
+
+export type CommentTrivia = {
+  readonly start: number;
+  readonly kind: typeof COMMENT_KIND_LINE | typeof COMMENT_KIND_BLOCK;
+  readonly text: string;
+};
+
+// Tokens that end an operand without being identifiers or keywords.
+const OPERAND_END_PUNCTUATION_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.NumericLiteral,
+  ts.SyntaxKind.BigIntLiteral,
+  ts.SyntaxKind.StringLiteral,
+  ts.SyntaxKind.NoSubstitutionTemplateLiteral,
+  ts.SyntaxKind.TemplateTail,
+  ts.SyntaxKind.RegularExpressionLiteral,
+  ts.SyntaxKind.CloseParenToken,
+  ts.SyntaxKind.CloseBracketToken,
+  ts.SyntaxKind.CloseBraceToken,
+  ts.SyntaxKind.PlusPlusToken,
+  ts.SyntaxKind.MinusMinusToken,
+]);
+
+// Reserved words after which an expression (so possibly a regex) starts.
+const EXPRESSION_INTRODUCING_KEYWORDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.ReturnKeyword,
+  ts.SyntaxKind.TypeOfKeyword,
+  ts.SyntaxKind.InstanceOfKeyword,
+  ts.SyntaxKind.InKeyword,
+  ts.SyntaxKind.CaseKeyword,
+  ts.SyntaxKind.VoidKeyword,
+  ts.SyntaxKind.DeleteKeyword,
+  ts.SyntaxKind.ThrowKeyword,
+  ts.SyntaxKind.NewKeyword,
+  ts.SyntaxKind.YieldKeyword,
+  ts.SyntaxKind.AwaitKeyword,
+  ts.SyntaxKind.ElseKeyword,
+  ts.SyntaxKind.DoKeyword,
+  ts.SyntaxKind.ExtendsKeyword,
+  ts.SyntaxKind.DefaultKeyword,
+]);
+
+function isIdentifierOrKeyword(kind: ts.SyntaxKind): boolean {
+  return (
+    kind === ts.SyntaxKind.Identifier ||
+    (kind >= ts.SyntaxKind.FirstKeyword && kind <= ts.SyntaxKind.LastKeyword)
+  );
+}
+
+// After an operand end a `/` is division, not the start of a regex literal.
+// Contextual keywords (`from`, `type`, `of`, ...) scan as keyword kinds but are
+// valid member and variable names, so every non-introducing keyword counts. A `!`
+// is the non-null postfix only when the token before it ended an operand.
+function isOperandEnd(kind: ts.SyntaxKind, previousEndedOperand: boolean): boolean {
+  if (kind === ts.SyntaxKind.ExclamationToken) return previousEndedOperand;
+  if (OPERAND_END_PUNCTUATION_KINDS.has(kind)) return true;
+  return isIdentifierOrKeyword(kind) && !EXPRESSION_INTRODUCING_KEYWORDS.has(kind);
+}
+
+const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.SingleLineCommentTrivia,
+  ts.SyntaxKind.MultiLineCommentTrivia,
+  ts.SyntaxKind.WhitespaceTrivia,
+  ts.SyntaxKind.NewLineTrivia,
+]);
+
+// The raw scanner always yields SlashToken for `/`; without the rescan a regex
+// body like /\{/ would shift braceDepth and end a template early. After an
+// operand the rescan would instead swallow `/ 2; // {` as a regex and hide the comment.
+function rescanSlashAsRegex(
+  scanner: ts.Scanner,
+  kind: ts.SyntaxKind,
+  previousEndedOperand: boolean,
+): ts.SyntaxKind {
+  if (previousEndedOperand) return kind;
+  const reScanned = scanner.reScanSlashToken();
+  return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
+}
+
+function closesTemplateSubstitution(
+  templateBraceDepths: readonly number[],
+  braceDepth: number,
+): boolean {
+  return (
+    templateBraceDepths.length > 0 &&
+    braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
+  );
+}
+
+// Template substitutions can nest braces (object literals, arrow bodies, other
+// templates). The raw scanner tokenizes a `}` as a plain CloseBraceToken and
+// never resumes template mode, so reScanTemplateToken() must run once brace
+// depth returns to the level the substitution opened at.
+export function scanCommentTrivia(fullText: string): CommentTrivia[] {
+  const comments: CommentTrivia[] = [];
+  const scanner = ts.createScanner(
+    ts.ScriptTarget.Latest,
+    /* skipTrivia */ false,
+    ts.LanguageVariant.Standard,
+    fullText,
+  );
+
+  const templateBraceDepths: number[] = [];
+  let braceDepth = 0;
+  let previousEndedOperand = false;
+
+  let kind = scanner.scan();
+  while (kind !== ts.SyntaxKind.EndOfFileToken) {
+    switch (kind) {
+      case ts.SyntaxKind.SingleLineCommentTrivia:
+      case ts.SyntaxKind.MultiLineCommentTrivia:
+        comments.push({
+          start: scanner.getTokenStart(),
+          kind:
+            kind === ts.SyntaxKind.SingleLineCommentTrivia ? COMMENT_KIND_LINE : COMMENT_KIND_BLOCK,
+          text: scanner.getTokenText(),
+        });
+        break;
+      case ts.SyntaxKind.SlashToken:
+      case ts.SyntaxKind.SlashEqualsToken:
+        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
+        break;
+      case ts.SyntaxKind.TemplateHead:
+      case ts.SyntaxKind.TemplateMiddle:
+        templateBraceDepths.push(braceDepth);
+        break;
+      case ts.SyntaxKind.OpenBraceToken:
+        braceDepth++;
+        break;
+      case ts.SyntaxKind.CloseBraceToken:
+        if (closesTemplateSubstitution(templateBraceDepths, braceDepth)) {
+          templateBraceDepths.pop();
+          kind = scanner.reScanTemplateToken(false);
+          continue;
+        }
+        if (braceDepth > 0) braceDepth--;
+        break;
+      default:
+        break;
+    }
+    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
+    kind = scanner.scan();
+  }
+  return comments;
+}

package/src/_lib/guard-kit.ts

@@ -339,7 +339,7 @@ export type RunResult = {
   readonly scanKinds?: readonly string[];
   /** Files the scan matched — the runner's own count, basis of the floor. */
   readonly matchedFiles?: number;
-  /** Roots whose declared sourceRoots hold no .ts/.tsx at all (D4, infra#427). */
+  /** Roots whose declared sourceRoots hold no .ts/.tsx at all. */
   readonly violatingRoots?: readonly string[];
   /** Violations excused by the per-repo security baseline — security guards only. */
   readonly frozenFindings?: number;
@@ -597,7 +597,7 @@ function guardKitVersion(): string {
 
 /**
  * Pure preflight verdict, injectable for tests: which of the two globally
- * silent-green cases (infra#2863) applies, if any. Not to be confused with a
+ * silent-green cases applies, if any. Not to be confused with a
  * single guard finding no target repos — that stays a per-guard `skipped`
  * line in `reportResults`.
  */

package/src/_lib/guards-doc.ts

@@ -34,10 +34,13 @@ function headerComment(source: string): string {
   return body.join("\n");
 }
 
+// Abbreviations that end in a period but not the sentence.
+const SENTENCE_END_RE = /(?<!\be\.g|\bi\.e|\bresp|\bz\. B|\bvs|\betc)\.(\s|$)/;
+
 function purposeOf(source: string): string {
   const paragraph = headerComment(source).split(/\n\s*\n/)[0] ?? "";
   const flat = paragraph.replace(/\s+/g, " ").trim();
-  const sentenceEnd = flat.search(/\.(\s|$)/);
+  const sentenceEnd = flat.search(SENTENCE_END_RE);
   const sentence = sentenceEnd === -1 ? flat : flat.slice(0, sentenceEnd + 1);
   return sentence.replace(/\|/g, "\\|") || "-";
 }

package/src/_lib/roots.ts

@@ -183,14 +183,18 @@ function isDerivedAppFallback(root: RepoRoot): boolean {
   return root.manifestSource === "derived" && root.kind === "app";
 }
 
-/** The repo of the nearest `kumiko.json` at or above `start`, which is the app root in a git tree that holds several. */
-function nearestManifestRepo(start: string): RepoRoot | undefined {
+/**
+ * The repo of the nearest `kumiko.json` at or above `start`, which is the app root in a git tree
+ * that holds several. The walk stops at the git toplevel, so a foreign `kumiko.json` further up
+ * (workspace parent, home dir) never captures a repo that has none of its own.
+ */
+function nearestManifestRepo(start: string, stopAt: string | undefined): RepoRoot | undefined {
   for (let curr = start; ; curr = dirname(curr)) {
     if (existsSync(join(curr, REPO_MANIFEST_FILE))) {
       const repo = repoAt(curr);
       if (repo) return repo;
     }
-    if (curr === dirname(curr)) return undefined;
+    if (curr === stopAt || curr === dirname(curr)) return undefined;
   }
 }
 
@@ -210,9 +214,9 @@ function nearestManifestRepo(start: string): RepoRoot | undefined {
  */
 export function findLocalRepo(cwd: string = process.cwd()): RepoRoot | undefined {
   const start = resolve(cwd);
-  const fromManifest = nearestManifestRepo(start);
-  if (fromManifest) return fromManifest;
   const toplevel = gitToplevelOf(start);
+  const fromManifest = nearestManifestRepo(start, toplevel);
+  if (fromManifest) return fromManifest;
   const fromGit = toplevel !== undefined ? repoAt(toplevel) : undefined;
   if (fromGit) return fromGit;
   let fallback: RepoRoot | undefined;

package/src/_lib/run-slots.ts

@@ -1,11 +1,20 @@
-import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 const DEFAULT_SLOTS = 2;
 const POLL_INTERVAL_MS = 1000;
 const PIDLESS_ORPHAN_AGE_MS = 60_000;
 // Upper bound against pid reuse after SIGKILL/OOM: a reused pid would otherwise hold the slot forever.
-const MAX_SLOT_AGE_MS = 15 * 60_000;
+// The slot mtime is never refreshed, so this must exceed the longest legitimate guard run.
+const MAX_SLOT_AGE_MS = 2 * 60 * 60_000;
 const PID_FILE = "pid";
 
 type Environment = Readonly<Record<string, string | undefined>>;
@@ -31,13 +40,19 @@ export function resolveGuardSlotCount(environment: Environment): number {
   return Number(raw);
 }
 
+function errorCode(error: unknown): string {
+  return error instanceof Error && "code" in error && typeof error.code === "string"
+    ? error.code
+    : "unknown";
+}
+
 function defaultIsPidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
   } catch (error) {
     // EPERM means the process exists but belongs to another user.
-    return error instanceof Error && "code" in error && error.code === "EPERM";
+    return errorCode(error) === "EPERM";
   }
 }
 
@@ -73,12 +88,6 @@ function isOrphanedSlot(
   return ageMs > PIDLESS_ORPHAN_AGE_MS;
 }
 
-function errorCode(error: unknown): string {
-  return error instanceof Error && "code" in error && typeof error.code === "string"
-    ? error.code
-    : "unknown";
-}
-
 function tryClaimSlot(slotPath: string, pid: number): boolean {
   try {
     mkdirSync(slotPath);
@@ -148,6 +157,25 @@ function defaultSlotsDir(): string {
   return uid === undefined ? "/tmp/kumiko-guard-slots" : `/tmp/kumiko-guard-slots-${uid}`;
 }
 
+// The default dir lives in a shared /tmp: another local user could pre-create it (or swap in a
+// symlink) to hold slots forever or redirect the pid write.
+function assertPrivateOwnDirectory(dir: string): void {
+  const uid = process.getuid?.();
+  // skip: no uid to compare against on this platform.
+  if (uid === undefined) return;
+  const stats = lstatSync(dir);
+  if (
+    stats.isSymbolicLink() ||
+    !stats.isDirectory() ||
+    stats.uid !== uid ||
+    (stats.mode & 0o077) !== 0
+  ) {
+    throw Object.assign(new Error(`${dir} is not a private directory owned by the current user`), {
+      code: "EUNSAFE",
+    });
+  }
+}
+
 export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => void {
   const slotCount = resolveGuardSlotCount(options.environment ?? process.env);
   if (slotCount === 0) return () => {};
@@ -164,7 +192,8 @@ export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => vo
   for (;;) {
     let slotPath: string | undefined;
     try {
-      mkdirSync(slotsDir, { recursive: true });
+      mkdirSync(slotsDir, { recursive: true, mode: 0o700 });
+      assertPrivateOwnDirectory(slotsDir);
       slotPath = claimFreeSlot(slotsDir, slotCount, pid, isPidAlive, now);
     } catch (error) {
       // A throttle must never block the push: fail open.

package/src/_lib/scan-scope.ts

@@ -35,7 +35,7 @@ export type RootScan = {
   readonly root: RepoRoot;
   /** Absolute paths handed to the guard, sorted. */
   readonly files: readonly string[];
-  /** All .ts/.tsx under the declared sourceRoots minus excludes, before extension/within filters — the D4 floor input. */
+  /** All .ts/.tsx under the declared sourceRoots minus excludes, before extension/within filters — the floor input. */
   readonly sourceSurface: number;
 };
 

package/src/_lib/security-audit.ts

@@ -35,6 +35,7 @@ export type SecurityEvaluation = {
   readonly blocking: AuditAdvisory[];
   readonly warnings: AuditAdvisory[];
   readonly suppressed: AuditAdvisory[];
+  readonly usedExceptions: SecurityException[];
   readonly counts: Record<Severity, number>;
 };
 
@@ -90,12 +91,20 @@ function matchesAdvisory(exceptionAdvisory: string, advisoryId: string, url: str
 function findSecurityException(
   advisory: AuditAdvisory,
   exceptions: readonly SecurityException[],
+  nowMs: number,
 ): SecurityException | undefined {
-  return exceptions.find(
+  const matching = exceptions.filter(
     (ex) =>
       matchesAdvisory(ex.advisory, advisory.advisoryId, advisory.url) &&
       (ex.package === "*" || matchesPackageName(ex.package, advisory.package)),
   );
+  // An expired earlier entry (e.g. bundled) must not shadow a valid later one (e.g. repo-level).
+  return matching.find((ex) => isSecurityExceptionActive(ex, nowMs)) ?? matching[0];
+}
+
+// isExceptionValid() treats a missing expiry as "forever valid", which is wrong for security: such an exception would suppress a critical permanently.
+function isSecurityExceptionActive(exception: SecurityException, nowMs: number): boolean {
+  return Boolean(exception.expires) && isExceptionValid(exception.expires, nowMs).valid;
 }
 
 export function evaluateSecurity(
@@ -107,18 +116,16 @@ export function evaluateSecurity(
   const blocking: AuditAdvisory[] = [];
   const warnings: AuditAdvisory[] = [];
   const suppressed: AuditAdvisory[] = [];
+  const usedExceptions = new Set<SecurityException>();
 
   for (const advisory of advisories) {
     counts[advisory.severity] += 1;
-    const exception = findSecurityException(advisory, exceptions);
-    // isExceptionValid() treats a missing expiry as "forever valid", which is wrong for security: such an exception would suppress a critical permanently.
-    const covered =
-      exception !== undefined &&
-      Boolean(exception.expires) &&
-      isExceptionValid(exception.expires, nowMs).valid;
+    const exception = findSecurityException(advisory, exceptions, nowMs);
+    const covered = exception !== undefined && isSecurityExceptionActive(exception, nowMs);
 
     if (covered) {
       suppressed.push(advisory);
+      usedExceptions.add(exception);
     } else if (FAIL_SEVERITIES.has(advisory.severity)) {
       blocking.push(advisory);
     } else if (advisory.severity === "moderate") {
@@ -126,7 +133,7 @@ export function evaluateSecurity(
     }
   }
 
-  return { blocking, warnings, suppressed, counts };
+  return { blocking, warnings, suppressed, usedExceptions: [...usedExceptions], counts };
 }
 
 /** True when `bytes` starts with the gzip magic header (1f 8b). */

package/src/_lib/sql-inventory.ts

@@ -58,7 +58,7 @@ export type SqlInventoryReport = {
   };
 };
 
-/** Paths where `.unsafe()` / `asRawClient()` are permitted (Phase 5 guard). */
+/** Paths where `.unsafe()` / `asRawClient()` are permitted. */
 export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   // Layout-agnostic: framework packages/... AND flat app src/... AND enterprise packages/<pkg>/...
   /(^|\/)(packages\/[^/]+\/)?src\/db\/queries\//,
@@ -107,7 +107,7 @@ const PATTERNS: ReadonlyArray<{
   { kind: "execute", re: /\.execute\s*\(/ },
 ];
 
-/** Only these kinds fail CI; delete_from/execute stay inventory-only (infra#610). */
+/** Only these kinds fail CI; delete_from/execute stay inventory-only. */
 export const BLOCKING_SQL_KINDS: ReadonlyArray<SqlInventoryKind> = ["unsafe", "asRawClient"];
 
 const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");

package/src/changes.json

@@ -1,4 +1,49 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Complexity hard cap 40, thin-wrapper guard skips typed table slots",
+    "detail": "A function above complexity 40 in the repo's own files fails the complexity guard, independent of the complexity baseline and of the complexity-budget tag, also with --no-baseline. The thin-wrapper guard skips a function that is a value of an object literal with a declared type or a satisfies check, inline or referenced by name, because the table fixes its signature.",
+    "migration": "Split every function above complexity 40 before the bump; the complexity-budget tag and the baseline do not cover it. `bun check-complexity.ts --all --no-baseline` lists them under \"Above hard cap\"."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Complexity hard cap, --all, file-size threshold 1200",
+    "detail": "Functions with complexity above 60 are a violation in the repo's own files, independent of the complexity baseline and of the complexity-budget tag, also with --no-baseline. The report lists them in their own section. `bun check-complexity.ts --all` prints all hotspots in the standalone run, --write-baseline and --no-baseline. The file-size guard now freezes files above 1200 lines instead of 2000.",
+    "migration": "Consumer repos without a complexity baseline get a hard error for functions above complexity 60; split them. File size stays a warning there without a baseline; with one, files between 1200 and 2000 lines count as new hits until `--write-baseline` is run."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Harden guards infrastructure (pre-push scan range, slot dir, root walk)",
+    "detail": "The pre-push secret scan covers every pushed ref instead of HEAD. The guard slot directory is created 0700 and ignored when not private; slot max age is 2 h. findLocalRepo no longer picks up a kumiko.json above the git root. Runtime-isolation keeps web/dev/ files as client."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Guards report fewer false results",
+    "detail": "The import-extensions guard now also checks import types, mock.module and template-literal specifiers. The comment-issue-ref-only guard no longer treats file names like round2.ts as plan labels. The direct-entity-writes guard recognises r.entity registrations with a constant or shorthand name, reports direct writes on package catalog tables even when the scope has no own ES tables, keeps receiver text on one line and names the installed kumiko-guards bin in its catalog rewrite hint. The app-feature-structure guard no longer tells dev/ and scripts/ files to move under web/, and the bundled license exceptions drop the stale first-party and create-kumiko-app entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Dependency exceptions, timeout and boundary guards no longer miss or invent findings",
+    "detail": "A renewed license or security exception now wins over an expired earlier one, license exceptions must match the package license and a real semver range, and only exceptions that suppressed an advisory block on near expiry. The test-timeouts guard also flags union-typed and untyped timeout arguments, the renderer-boundaries guard covers headless and live imports, import-extensions ignores real .js files without a .ts sibling, and the generated agent examples now include bin, e2e, seeds and scripts files."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Guards --explain uses the injectable project builder",
+    "detail": "runGuardsCli builds the explain project through the same buildProject dependency as the check run, which lets tests assert that --explain takes no guard run slot without parsing the whole repository."
+  },
+  {
+    "version": "0.387.0",
+    "type": "improvement",
+    "title": "Comment Issue-Ref guard",
+    "detail": "The comment-issue-ref-only guard flags comments that consist only of an issue or PR reference or a planning label (`#1234`, `fw#1234`, `Phase 3`, `S2.H1`) with no explanatory word besides it. Consecutive own-line `//` comments count as one paragraph, so a reference at the end of an explaining paragraph passes. Hits are frozen per file in `.kumiko-comment-issue-ref-baseline.json` and may not grow; without the baseline file the guard only warns. Deliberate exceptions take `// kumiko-lint-ignore comment-issue-ref-only <reason>`.",
+    "migration": "Optional. Freeze existing hits with `kumiko-guards guards --write-baseline --guard=comment-issue-ref-only`."
+  },
   {
     "version": "0.385.0",
     "type": "improvement",

package/src/check-as-casts.ts

@@ -117,7 +117,7 @@ export function isConstAssertion(cast: AsExpression): boolean {
 // optional ParenthesizedExpression in between (depending on parenthesisation):
 //   `x as unknown as Y`     → AsExpr(target=Y) → AsExpr(target=unknown) → x
 //   `(x as unknown) as Y`   → AsExpr(target=Y) → ParenExpr → AsExpr(target=unknown) → x
-// Wir gehen durch Parens transparent durch.
+// Traverse parentheses transparently.
 function unwrapParens(node: Node | undefined): Node | undefined {
   while (node?.getKind() === SyntaxKind.ParenthesizedExpression) {
     node = node.asKindOrThrow(SyntaxKind.ParenthesizedExpression).getExpression();
@@ -277,7 +277,7 @@ function restOfLine(fullText: string, from: number): string {
 export function extractBoundaryReason(cast: AsExpression): string | null {
   const fullText = cast.getSourceFile().getFullText();
 
-  // (1) Leading comments des enclosing statement
+  // (1) Leading comments of the enclosing statement
   const stmt =
     cast.getFirstAncestorByKind(SyntaxKind.VariableStatement) ??
     cast.getFirstAncestorByKind(SyntaxKind.ExpressionStatement) ??
@@ -288,7 +288,7 @@ export function extractBoundaryReason(cast: AsExpression): string | null {
     if (reason !== null) return reason;
   }
 
-  // (2) Cast-Range selbst (multi-line casts, inline comments innerhalb)
+  // (2) Cast range itself (multi-line casts, inline comments inside)
   const inlineReason = boundaryReasonIn(fullText.slice(cast.getStart(), cast.getEnd()));
   if (inlineReason !== null) return inlineReason;
 
@@ -327,9 +327,8 @@ const FILE_DEFAULT_REASONS: ReadonlyArray<{
   boundaryReason: BoundaryReason;
 }> = [
   {
-    // feature-AST extractors: alle Casts gehen vom erased ts-morph-Parse-
-    // Result zu typed feature-Definitionen (EntityDefinition, RelationDef,
-    // NavDef, ConfigKeys, …). Per Konstruktion ein schema-walk.
+    // Feature-AST extractors cast erased ts-morph parse results to typed feature definitions
+    // (EntityDefinition, RelationDef, NavDef, ConfigKeys, …), so every cast is a schema walk.
     pattern: /\/engine\/feature-ast\//,
     boundaryReason: "schema-walk",
   },
@@ -605,7 +604,7 @@ function writeBaseline(all: readonly Site[]): void {
   legitRatchet.write(legitCountsByPackage(all));
 }
 
-// Per File:target: aktueller Count gegen baseline. Mehr → Regression.
+// Per file:target: current count against the baseline. More → regression.
 // A cast swap (cast A removed, cast B with a different target added) is detected
 // this way although the total stays stable.
 // Merge-conflict markers, truncated writes and hand edits all land here; the