@cosmicdrift/kumiko-guards 0.377.0 → 0.379.0

package/src/guard-pre-es-patterns.ts

@@ -68,6 +68,8 @@ type Pattern = {
 // identifier in the AST (not in strings, not in comments).
 function identifierHits(sf: SourceFile, name: string): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  // Cheap text prefilter: a full descendant walk over every file costs seconds.
+  if (!sf.getFullText().includes(name)) return out;
   for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
     if (id.getText() !== name) continue;
     out.push({
@@ -85,6 +87,7 @@ function stringLiteralHits(
   literal: string,
 ): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  if (!sf.getFullText().includes(literal)) return out;
   for (const lit of sf.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
     if (lit.getLiteralText() !== literal) continue;
     out.push({
@@ -129,6 +132,7 @@ const PATTERNS: readonly Pattern[] = [
       // Match `.postEvent(` property accesses to distinguish from the word
       // "postEvent" in prose. Identifier scan would miss method invocations.
       const out: Array<{ line: number; snippet: string }> = [];
+      if (!sf.getFullText().includes("postEvent")) return out;
       for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
         if (pa.getName() !== "postEvent") continue;
         // Only flag when invoked as a method — a property read named

package/src/guard-renderer-boundaries.ts

@@ -6,9 +6,9 @@
  * belongs in `src/web` instead.
  *
  * `src/web/**` is the browser layer and not scanned at all: it may import
- * everything. `src/headless/**` and `src/live/**` only get the import rules:
- * the apex page builder emits HTML strings and the live dispatcher is a fetch
- * client, so the symbol and JSX-tag rules would be noise there. They stay free
+ * everything. `src/headless/**`, `src/flow-diagram/**` and `src/live/**` only get
+ * the import rules: the apex page builder emits HTML strings, the flow diagram
+ * emits SVG strings and the live dispatcher is a fetch client, so the symbol and JSX-tag rules would be noise there. They stay free
  * of react-dom, jsdom and any import of `src/web`.
  *
  * Deliberately simple: a regex scan over the source text. False positives
@@ -70,7 +70,7 @@ const FORBIDDEN_SYMBOLS = [
 const FORBIDDEN_JSX_TAG = /(^|\s|>|\()<([a-z][a-zA-Z0-9-]*)(?=[\s/>])/g;
 
 // Subtrees of packages/renderer/src that carry only the import rules.
-const IMPORT_RULES_ONLY_DIRS = ["headless", "live"] as const;
+const IMPORT_RULES_ONLY_DIRS = ["headless", "flow-diagram", "live"] as const;
 
 // The browser layer may import anything, so it is not scanned.
 const UNSCANNED_TOP_LEVEL_DIRS = ["web"] as const;

package/src/guard-restricted-symbols.ts

@@ -42,6 +42,10 @@ const RESTRICTED_SYMBOLS = new Set([
   // an audited unsafeRaw escape hatch, so new callers need an explicit allowlist entry.
   "appendEventInTenantDb",
   "getStreamVersionInTenantDb",
+  // Grants the ES-write capability on the tenant being destroyed; only the destroy stage and its definition may use it.
+  "createTenantDataDestroyDb",
+  // Test seam that writes event-fed tables without events; runtime code importing it would be a back door.
+  "withExecutorManagedWritesForTests",
 ]);
 
 const ALLOWLIST = [
@@ -50,6 +54,10 @@ const ALLOWLIST = [
   /^packages\/framework\/src\/event-store\/tenant-db-append\.ts$/,
   /^packages\/bundled-features\/src\/cap-counter\/cap-reservation\.ts$/,
   /^packages\/bundled-features\/src\/user-data-rights-defaults\/hooks\/delivery-attempt\.userdata-hook\.ts$/,
+  /^packages\/framework\/src\/db\/tenant-db\.ts$/,
+  /^packages\/framework\/src\/db\/index\.ts$/,
+  /^packages\/bundled-features\/src\/tenant-lifecycle\/stages\.ts$/,
+  /^packages\/testing\/src\/helpers\/(seed|db-cleanup)\.ts$/,
   /^packages\/bundled-features\/src\/tenant\/seeding\.ts$/,
   /^packages\/bundled-features\/src\/tier-engine\/feature\.ts$/,
 ];
@@ -121,7 +129,7 @@ function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
-  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. createTenantDataDestroyDb grants direct writes on event-fed tables and belongs to the tenant-destroy stage only. withExecutorManagedWritesForTests is the test-seed seam behind seedRow/deleteRows and must not reach runtime code. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
   run(files, roots = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   type ScanSpec,
   type SuiteInventory,
 } from "./_lib/guard-kit";
+export { GUARDS_DOC_REL, renderGuardsDoc, writeGuardsDoc } from "./_lib/guards-doc";
 export { findLocalRepo, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 export { type RootScan, type ScanOptions, scanFiles, scanRoots } from "./_lib/scan-scope";
 export {

package/src/run-guards.ts

@@ -18,6 +18,7 @@ import {
   runGuards,
 } from "./_lib/guard-kit";
 import type { RepoRoot } from "./_lib/roots";
+import { acquireGuardRunSlot } from "./_lib/run-slots";
 import { writeSecurityBaselines } from "./_lib/security-baseline-cli";
 import { guard as asCasts } from "./check-as-casts";
 import { guard as complexity } from "./check-complexity";
@@ -176,9 +177,15 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
   }
   const strictSecurityBaseline = flags.includes("--strict-security-baseline");
   const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
-  const project = buildSharedProject(guards);
-  printGuardKitBanner(guards.length, project);
-  return reportResults(runGuards(guards, project, { strictSecurityBaseline }));
+  // Taken before the ts-morph project is built: that is where the memory goes.
+  const releaseSlot = acquireGuardRunSlot();
+  try {
+    const project = buildSharedProject(guards);
+    printGuardKitBanner(guards.length, project);
+    return reportResults(runGuards(guards, project, { strictSecurityBaseline }));
+  } finally {
+    releaseSlot();
+  }
 }
 
 // Only run on direct invocation — otherwise `import { GUARDS }` would kick

package/src/run-repo-checks.ts

@@ -7,8 +7,10 @@ import { check as realProviderIsolation } from "./check-real-provider-isolation"
 import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
 import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
+import { check as subpathExports } from "./check-subpath-exports";
 import { check as agentDocsDrift } from "./guard-agent-docs-drift";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
+import { check as guardsDocDrift } from "./guard-guards-doc-drift";
 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";
@@ -31,6 +33,8 @@ export const REPO_CHECKS = [
   realProviderIsolation,
   singleRuntimeInstance,
   agentDocsDrift,
+  subpathExports,
+  guardsDocDrift,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];

package/src/runtime-isolation-classify.ts

@@ -49,6 +49,7 @@ const PATH_RULES: readonly (readonly [RegExp, Runtime])[] = [
   // sample and import kumiko-testing/e2e; without this rule they read as
   // runtime code importing the test tier. Deliberately not any nested e2e/.
   [/^(?:e2e|packages\/[^/]+\/e2e|samples\/(?:.+\/)?e2e)\//, "test"],
+  [/(?:^|\/)dev\//, "dev"],
   [/(?:^|\/)scripts\//, "tooling"],
   [/(?:^|\/)bin\//, "tooling"],
   [/\/drizzle\/[^/]+\.ts$/, "tooling"],
@@ -347,7 +348,10 @@ export function classifyByDirective(
   readHead: HeadReader = readFileHead,
 ): Runtime | null {
   const head = readHead(filePath);
-  if (head === null) return null;
+  return head === null ? null : directiveInHead(head);
+}
+
+export function directiveInHead(head: string): Runtime | null {
   for (const line of head.split("\n").slice(0, DIRECTIVE_HEAD_LINES)) {
     const m = line.match(/\/\/\s*@runtime\s+(\w+)/);
     const declared = m?.[1];