@cosmicdrift/kumiko-guards 0.384.0 → 0.385.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.384.0",
+  "version": "0.385.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",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.384.0"
+    "@cosmicdrift/kumiko-framework": "0.385.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.384.0"
+    "@cosmicdrift/kumiko-framework": "0.385.0"
   }
 }

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.385.0",
+    "type": "improvement",
+    "title": "File Size guard and per-package ratchet for legit casts",
+    "detail": "The File Size guard freezes production files above 2000 lines in `.kumiko-file-size-baseline.json` and fails when a file grows or a new one crosses the limit. The As-Casts Audit additionally caps legit-bridge and legit-boundary casts per package in `.kumiko-cast-legit-baseline.json`. Without the baseline files both only warn.",
+    "migration": "Optional. Freeze both with `kumiko-guards guards --write-baseline --guard=\"File Size\"` and `--guard=\"As-Casts Audit\"`."
+  },
   {
     "version": "0.384.0",
     "type": "improvement",

package/src/check-as-casts.ts

@@ -35,6 +35,12 @@
  *   • an unreadable or format-drifted baseline
  * Without a baseline file (e.g. consumer repos) nothing fails: warnings only.
  * Sibling checkouts (`../`) never fail.
+ * `.kumiko-cast-legit-baseline.json` additionally caps legit-bridge and
+ * legit-boundary casts per package (`<package-dir>:<category>`), so a new
+ * double cast or boundary marker cannot slip in unnoticed. Per package rather
+ * than per file, so moving a cast between files does not trip it. Same
+ * missing-file behavior (warning only) as the suspect baseline.
+ *
  * Reductions (current < baseline) are allowed but do NOT update the baseline
  * automatically — run `--write-baseline` after cleanup commits.
  *
@@ -49,6 +55,7 @@ import * as path from "node:path";
 import { type AsExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import {
   type AstGuard,
+  baselineRatchet,
   buildSharedProject,
   filesForGuard,
   type GuardOutcome,
@@ -550,6 +557,33 @@ function totalOf(byFileAndTarget: Record<string, Record<string, number>>): numbe
 
 const baselinePath = path.join(ROOT, ".kumiko-cast-baseline.json");
 
+const LEGIT_BASELINE_FORMAT_VERSION = 1;
+const LEGIT_CAPPED_CATEGORIES: readonly Category[] = ["legit-bridge", "legit-boundary"];
+
+const legitRatchet = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-cast-legit-baseline.json"),
+  formatVersion: LEGIT_BASELINE_FORMAT_VERSION,
+  unit: "legit cast(s)",
+});
+
+function packageDirOf(file: string): string {
+  return /^(?:packages|samples)\/[^/]+/.exec(file)?.[0] ?? file.split("/")[0] ?? file;
+}
+
+export function legitCountsByPackage(all: readonly Site[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const site of all) {
+    if (isSiblingFile(site.file)) continue;
+    if (!LEGIT_CAPPED_CATEGORIES.includes(site.category)) continue;
+    const key = `${packageDirOf(site.file)}:${site.category}`;
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+const LEGIT_REMEDIATION =
+  'Avoid the cast (type guard, discriminated union, typing at the source). Only if it is a real system boundary or deliberate bridge: re-freeze with `bun packages/guards/src/cli.ts guards --write-baseline --guard="As-Casts Audit"` and justify it in the PR.';
+
 function writeBaseline(all: readonly Site[]): void {
   const repoLocalSuspects = repoLocal(suspectByFileAndTarget(all));
   const payload: Baseline = {
@@ -568,6 +602,7 @@ function writeBaseline(all: readonly Site[]): void {
   writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`);
   console.log(`\n  Baseline written: ${baselinePath}`);
   console.log(`  Total suspect: ${payload.totalSuspect} (repo-local)`);
+  legitRatchet.write(legitCountsByPackage(all));
 }
 
 // Per File:target: aktueller Count gegen baseline. Mehr → Regression.
@@ -758,13 +793,23 @@ function analyseCasts(files: readonly SourceFile[], compareBaseline: boolean): G
   }
   // Fails on regressions, repo-local unknown reasons (both only with a valid
   // baseline) and an unreadable or drifted baseline; see the module header.
-  return { violations: reportBaseline(all) };
+  return {
+    violations: [
+      ...reportBaseline(all),
+      ...legitRatchet.check(legitCountsByPackage(all), LEGIT_REMEDIATION),
+    ],
+  };
 }
 
 export const guard: AstGuard = {
   name: "As-Casts Audit",
   scan: SCAN,
   run: (files) => analyseCasts(files, true),
+  writeBaseline: (files) => {
+    const { all, scanned } = scanCasts(files);
+    reportCasts(all, scanned);
+    writeBaseline(all);
+  },
 };
 
 if (import.meta.main) {

package/src/guard-file-size.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+/**
+ * File Size Guard — production files above 2000 lines are frozen in
+ * `.kumiko-file-size-baseline.json` (key = file, value = line count) and may
+ * not grow; a new file above the threshold is a violation. Without a baseline
+ * file (consumer repos) it only warns.
+ *
+ * Excluded: tests, declaration files, generated files and the translation
+ * data in the locale packages' `src/strings.ts`.
+ */
+
+import path from "node:path";
+import type { SourceFile } from "ts-morph";
+import {
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+export const MAX_FILE_LINES = 2000;
+
+const EXCLUDE =
+  /(__tests__|\.test\.(ts|tsx)$|\.integration\.(ts|tsx)$|\.d\.(ts|tsx)$|\.generated\.(ts|tsx)$|\/generated\/|\/locale-[^/]+\/src\/strings\.ts$)/;
+
+const fileSizeBaseline = baselineRatchet({
+  file: path.join(ROOT, ".kumiko-file-size-baseline.json"),
+  formatVersion: 1,
+  unit: "oversized file(s)",
+});
+
+function lineCountOf(text: string): number {
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+
+export function oversizedFileLines(
+  files: readonly SourceFile[],
+  roots: ReadonlyArray<{ readonly absPath: string }> = resolveRepoRoots(),
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    const lines = lineCountOf(sf.getFullText());
+    if (lines <= MAX_FILE_LINES) continue;
+    counts[relFromRepoRoot(sf.getFilePath(), roots)] = lines;
+  }
+  return counts;
+}
+
+function localOnly(counts: Readonly<Record<string, number>>): Record<string, number> {
+  return Object.fromEntries(Object.entries(counts).filter(([file]) => isLocalFinding({ file })));
+}
+
+const REMEDIATION = `Split the file below ${MAX_FILE_LINES + 1} lines (cut along a responsibility seam), do not grow a frozen one.`;
+
+export const guard: AstGuard = {
+  name: "File Size",
+  scan: SCAN,
+  hint: 'after a deliberate change: `kumiko-guards guards --write-baseline --guard="File Size"`',
+  run: (files, roots = resolveRepoRoots()) => {
+    const counts = localOnly(oversizedFileLines(files, roots));
+    return {
+      violations: fileSizeBaseline.check(counts, REMEDIATION, {
+        formatDriftRemediation: `Run \`kumiko-guards guards --write-baseline --guard="File Size"\` once.`,
+      }),
+    };
+  },
+  writeBaseline: (files, roots = resolveRepoRoots()) => {
+    fileSizeBaseline.write(localOnly(oversizedFileLines(files, roots)));
+  },
+};
+
+if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    guard.writeBaseline?.(filesForGuard(project, guard));
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/guard-no-date-api.ts

@@ -107,7 +107,7 @@ const ALLOWLIST = [
   // HTTP Last-Modified/ETag header: Bun/Node Response API expects a native
   // Date object from fs.Stats.mtimeMs — wire boundary, not a Temporal format.
   /packages\/server-runtime\/src\/run-prod-app-static-files\.ts$/,
-  // Bun.SQL timestamptz columns arrive as native Date (driver wire format,
+  // postgres-js timestamptz columns arrive as native Date (driver wire format,
   // same reason as packages/framework/src/db/ above).
   /packages\/publish\/src\/rollback\.ts$/,
 ];

package/src/run-guards.ts

@@ -31,6 +31,7 @@ import { guard as directFetch } from "./guard-direct-fetch";
 import { guard as errorReasons } from "./guard-error-reasons";
 import { guard as eventStoreWrites } from "./guard-event-store-writes";
 import { guard as fakeTests } from "./guard-fake-tests";
+import { guard as fileSize } from "./guard-file-size";
 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";
@@ -80,6 +81,7 @@ export const GUARDS = [
   libTestCoverage,
   testTimeouts,
   testTemplateDrift,
+  fileSize,
 ];
 
 export const GUARD_FLAGS = [