@cosmicdrift/kumiko-guards 0.361.0 → 0.363.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.361.0",
+  "version": "0.363.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>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.361.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.363.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/bun-lock-packages.ts

@@ -18,7 +18,7 @@ type ParsedBunLock = { readonly packages?: Record<string, unknown> };
 
 function isParsedBunLock(value: unknown): value is ParsedBunLock {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const packages = (value as Record<string, unknown>)["packages"];
+  const packages = "packages" in value ? value.packages : undefined;
   return (
     packages === undefined ||
     (packages !== null && typeof packages === "object" && !Array.isArray(packages))

package/src/_lib/guard-kit.ts

@@ -583,8 +583,13 @@ function guardKitVersion(): string {
   const pkgPath = resolve(import.meta.dir, "../../package.json");
   // The version only decorates the banner; it must never abort a guard run.
   try {
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
-    return pkg.version ?? "unknown";
+    const pkg: unknown = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return typeof pkg === "object" &&
+      pkg !== null &&
+      "version" in pkg &&
+      typeof pkg.version === "string"
+      ? pkg.version
+      : "unknown";
   } catch {
     return "unknown";
   }

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "As-casts guard fails on baseline regressions",
+    "detail": "check-as-casts now returns violations for more suspect casts per file and target than the baseline, for unknown or missing @cast-boundary reasons in repo-local files (only when a baseline exists), and for a baseline with a drifted format. Repos without a baseline and sibling checkouts under ../ still only warn."
+  },
   {
     "version": "0.361.0",
     "type": "fix",

package/src/check-as-casts.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 /**
- * `as X` cast audit with a baseline regression report (WARNING, no fail).
+ * `as X` cast audit with a baseline regression gate (fails on regressions).
  *
  * Every `as X` cast is a compiler gag. This check shows all casts
  * in production code, categorized as:
@@ -27,10 +27,14 @@
  * Baseline regression report:
  *
  * `.kumiko-cast-baseline.json` in the repo root pins the expected
- * suspect-cast count per file. The audit compares against the baseline and
- * reports increases — per the project coding standards ("Type Assertions")
- * this check is "warning, no fail": it never blocks, not even on
- * unknown @cast-boundary reasons or a baseline regression.
+ * suspect-cast count per file and target type. The audit compares against the
+ * baseline and fails on:
+ *   • a regression (more suspect casts for a file:target than the baseline,
+ *     repo-local files only)
+ *   • an unknown or missing `@cast-boundary` reason in a repo-local file
+ *   • an unreadable or format-drifted baseline
+ * Without a baseline file (e.g. consumer repos) nothing fails: warnings only.
+ * Sibling checkouts (`../`) never fail.
  * Reductions (current < baseline) are allowed but do NOT update the baseline
  * automatically — run `--write-baseline` after cleanup commits.
  *
@@ -227,11 +231,16 @@ export const KNOWN_BOUNDARY_REASONS = [
   "projection-table", // implicit entity-projections set `table`
   // UI / Web
   "visual-tree-args", // TargetRef.args is erased to generic args shape
+  // Brands / third-party gaps
+  "phantom-brand", // TenancyBrand-style phantom marker, or a conditional type keyed on one, with no runtime representation
+  "third-party-type-gap", // a library's type does not know a valid runtime value (e.g. Hono status 499)
+  "dom-event-target", // event.target narrowed to the Element the DOM guarantees
+  "feature-exports", // typeof-checked read-back of a function from untyped feature.exports
 ] as const;
 export type BoundaryReason = (typeof KNOWN_BOUNDARY_REASONS)[number];
 
 export function isKnownBoundaryReason(reason: string): reason is BoundaryReason {
-  return (KNOWN_BOUNDARY_REASONS as readonly string[]).includes(reason);
+  return KNOWN_BOUNDARY_REASONS.some((known) => known === reason);
 }
 
 export function hasBoundaryMarker(cast: AsExpression): boolean {
@@ -338,7 +347,7 @@ export function categorize(cast: AsExpression): Category {
   return "suspect-general";
 }
 
-function collect(sf: SourceFile): Site[] {
+export function collect(sf: SourceFile): Site[] {
   const file = path.relative(ROOT, sf.getFilePath());
   const sites: Site[] = [];
   for (const cast of sf.getDescendantsOfKind(SyntaxKind.AsExpression)) {
@@ -361,7 +370,7 @@ function collect(sf: SourceFile): Site[] {
       line: cast.getStartLineNumber(),
       category,
       source: cast.getExpression().getText().slice(0, 60),
-      target: cast.getTypeNode()?.getText().slice(0, 60) ?? "",
+      target: cast.getTypeNode()?.getText().replace(/\s+/g, " ").slice(0, 60) ?? "",
       full: cast.getText().slice(0, 100),
       ...(reason ? { boundaryReason: reason } : {}),
     });
@@ -467,28 +476,34 @@ function reportCasts(all: readonly Site[], scanned: number): void {
   );
 }
 
-// Reason validation: every legit-boundary cast should have a known reason.
-// Unknown reasons are reported (reason drift like "engine-payload" vs
-// "enginePayload" would otherwise destroy the audit's value in the long
-// run) — extending the whitelist: add an entry to KNOWN_BOUNDARY_REASONS
-// above. Warning, no fail (see module header).
-function reportUnknownReasons(all: readonly Site[]): void {
-  const unknownReasons: Array<{ file: string; line: number; reason: string }> = [];
-  for (const s of all) {
-    if (s.category !== "legit-boundary") continue;
-    const r = s.boundaryReason ?? "";
-    if (r === "" || !isKnownBoundaryReason(r)) {
-      unknownReasons.push({ file: s.file, line: s.line, reason: r || "<missing>" });
-    }
-  }
-  if (unknownReasons.length > 0) {
-    console.log(`\n  UNKNOWN @cast-boundary REASONS (${unknownReasons.length}):`);
-    for (const u of unknownReasons) {
-      console.log(`    ${u.file}:${u.line}  reason=${u.reason}`);
-    }
-    console.log(`\n  Known reasons: ${KNOWN_BOUNDARY_REASONS.join(", ")}`);
-    console.log("  New reason? Add an entry in check-as-casts.ts → KNOWN_BOUNDARY_REASONS.");
+// Reason validation: every legit-boundary cast needs a known reason (reason
+// drift like "engine-payload" vs "enginePayload" would otherwise destroy the
+// audit's value). Extending the whitelist: add an entry to
+// KNOWN_BOUNDARY_REASONS above. Always printed; only repo-local sites fail,
+// and only once a baseline gates the repo (see reportBaseline).
+function findUnknownReasons(all: readonly Site[]): Site[] {
+  return all.filter(
+    (s) =>
+      s.category === "legit-boundary" &&
+      (s.boundaryReason === undefined ||
+        s.boundaryReason === "" ||
+        !isKnownBoundaryReason(s.boundaryReason)),
+  );
+}
+
+function reportUnknownReasons(unknown: readonly Site[]): void {
+  // skip: every reason is known, nothing to report
+  if (unknown.length === 0) return;
+  console.log(`\n  UNKNOWN @cast-boundary REASONS (${unknown.length}):`);
+  for (const u of unknown) {
+    console.log(`    ${u.file}:${u.line}  reason=${u.boundaryReason || "<missing>"}`);
   }
+  console.log(`\n  Known reasons: ${KNOWN_BOUNDARY_REASONS.join(", ")}`);
+  console.log("  New reason? Add an entry in check-as-casts.ts → KNOWN_BOUNDARY_REASONS.");
+}
+
+function isSiblingFile(file: string): boolean {
+  return file.startsWith("../");
 }
 
 const BASELINE_FORMAT_VERSION = 2;
@@ -557,7 +572,7 @@ function writeBaseline(all: readonly Site[]): void {
 
 // Per File:target: aktueller Count gegen baseline. Mehr → Regression.
 // A cast swap (cast A removed, cast B with a different target added) is detected
-// this way although the total stays stable. Report only — warning, no fail.
+// this way although the total stays stable.
 // Merge-conflict markers, truncated writes and hand edits all land here; the
 // file is read once at the boundary so the comparison below can trust its shape.
 function isCountsByFile(value: unknown): value is Record<string, Record<string, number>> {
@@ -635,6 +650,11 @@ function compareCastsToBaseline(
   return { regressions, reduced };
 }
 
+const CAST_OPTIONS_HINT =
+  "New casts need a justification. Options: (1) avoid the cast (TypeGuard, Discriminated Union, typing at the source); " +
+  "(2) a real system boundary: `// @cast-boundary <reason>` with a reason from KNOWN_BOUNDARY_REASONS; " +
+  "(3) re-freeze with `bun packages/guards/src/check-as-casts.ts --write-baseline`, only with a justification in the PR.";
+
 function printCastRegressions(regressions: readonly CastRegression[]): void {
   console.log(
     `\n  REGRESSION: ${regressions.length} (file, target) pair(s) have more suspect casts than the baseline:`,
@@ -644,13 +664,32 @@ function printCastRegressions(regressions: readonly CastRegression[]): void {
       `    ${r.file}: as ${r.target}  baseline=${r.baseline} current=${r.current} (+${r.current - r.baseline})`,
     );
   }
-  console.log(
-    "\n  New casts need a justification. Options:\n" +
-      "    1. Avoid the cast (TypeGuard, Discriminated Union, better typing at the source)\n" +
-      "    2. If a legit system boundary: add a `// @cast-boundary <reason>` marker\n" +
-      "    3. If a cleanup reduction in one file offsets an increase in another: " +
-      "run `bun packages/guards/src/check-as-casts.ts --write-baseline` after committing",
-  );
+  console.log(`\n${CAST_OPTIONS_HINT}`);
+}
+
+function regressionViolation(regression: CastRegression, all: readonly Site[]): GuardViolation {
+  const firstNew = all
+    .filter(
+      (s) =>
+        s.file === regression.file &&
+        s.target === regression.target &&
+        s.category.startsWith("suspect-"),
+    )
+    .sort((a, b) => a.line - b.line)[regression.baseline];
+  return {
+    file: regression.file,
+    line: firstNew?.line ?? 1,
+    message: `Suspect cast regression: \`as ${regression.target}\` baseline=${regression.baseline}, current=${regression.current}. ${CAST_OPTIONS_HINT}`,
+  };
+}
+
+function unknownReasonViolation(site: Site): GuardViolation {
+  const reason = site.boundaryReason || "<missing>";
+  return {
+    file: site.file,
+    line: site.line,
+    message: `Unknown @cast-boundary reason ${reason}. Use one of: ${KNOWN_BOUNDARY_REASONS.join(", ")} (or add a reason to KNOWN_BOUNDARY_REASONS in check-as-casts.ts).`,
+  };
 }
 
 export function reportBaseline(
@@ -678,19 +717,27 @@ export function reportBaseline(
     ];
   }
   if (loaded.kind === "format-drift") {
-    console.log(
-      `\n  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${String(loaded.format ?? "<missing>")}.`,
-    );
-    console.log("  Run `bun packages/guards/src/check-as-casts.ts --write-baseline` once.");
-    return [];
+    // A stale baseline must not silently switch the gate off.
+    return [
+      {
+        file: baselineFile,
+        line: 1,
+        message: `Cast baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${String(loaded.format ?? "<missing>")}. Regenerate it with \`bun packages/guards/src/check-as-casts.ts --write-baseline\`.`,
+      },
+    ];
   }
   const { baseline } = loaded;
 
   const { regressions, reduced } = compareCastsToBaseline(repoLocalSuspects, baseline.perFile);
   if (regressions.length > 0) {
     printCastRegressions(regressions);
-    return [];
   }
+  const unknownReasons = findUnknownReasons(all).filter((s) => !isSiblingFile(s.file));
+  const violations = [
+    ...regressions.map((r) => regressionViolation(r, all)),
+    ...unknownReasons.map(unknownReasonViolation),
+  ];
+  if (violations.length > 0) return violations;
 
   console.log(`\n  ✓ Baseline (${baseline.totalSuspect}) — current ${repoLocalTotal}`);
   if (reduced > 0) {
@@ -704,14 +751,13 @@ export function reportBaseline(
 function analyseCasts(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
   const { all, scanned } = scanCasts(files);
   reportCasts(all, scanned);
-  reportUnknownReasons(all);
+  reportUnknownReasons(findUnknownReasons(all));
   if (!compareBaseline) {
     console.log("\n  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
   }
-  // WARNING, no fail (coding-standards.md → "Type Assertions"): neither
-  // unknown @cast-boundary reasons nor a baseline regression block. Only
-  // an unreadable baseline fails.
+  // 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) };
 }
 

package/src/check-complexity.ts

@@ -145,7 +145,7 @@ export function computeComplexity(fn: Node): number {
   fn.forEachDescendant((node, traversal) => {
     // skip: decision points inside a nested function-like node belong to its
     // own Hotspot entry
-    if (node !== fn && (FUNCTION_KINDS as readonly SyntaxKind[]).includes(node.getKind())) {
+    if (node !== fn && FUNCTION_KINDS.some((kind) => kind === node.getKind())) {
       traversal.skip();
       return;
     }

package/src/check-single-runtime-instance.ts

@@ -37,9 +37,15 @@ function readRuntimeMarker(rootAbsPath: string, packageName: string): string | u
     const pkgPath = join(dir, "node_modules", packageName, "package.json");
     if (existsSync(pkgPath)) {
       try {
-        const marker = (
-          JSON.parse(readFileSync(pkgPath, "utf8")) as { kumiko?: { runtime?: unknown } }
-        ).kumiko?.runtime; // @cast-boundary package-json
+        const manifest: unknown = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const kumikoBlock =
+          typeof manifest === "object" && manifest !== null && "kumiko" in manifest
+            ? manifest.kumiko
+            : undefined;
+        const marker =
+          typeof kumikoBlock === "object" && kumikoBlock !== null && "runtime" in kumikoBlock
+            ? kumikoBlock.runtime
+            : undefined;
         return typeof marker === "string" && ALL_RUNTIMES.has(marker) ? marker : undefined;
       } catch {
         return undefined;

package/src/cli.ts

@@ -34,7 +34,7 @@ const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
 };
 
 function isSubcommand(value: string): value is Subcommand {
-  return (SUBCOMMANDS as readonly string[]).includes(value);
+  return SUBCOMMANDS.some((subcommand) => subcommand === value);
 }
 
 function printHelp(): void {

package/src/guard-admin-api.ts

@@ -20,7 +20,7 @@
  */
 
 import * as path from "node:path";
-import { type CallExpression, type Identifier, type SourceFile, SyntaxKind } from "ts-morph";
+import { type CallExpression, type SourceFile, SyntaxKind } from "ts-morph";
 import { findRepoRootFor } from "./_lib/baseline-compare";
 import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
@@ -84,8 +84,8 @@ function isAllowed(relativePath: string): boolean {
 // references to the known function names.
 function getCalleeName(call: CallExpression): string | null {
   const expr = call.getExpression();
-  if (expr.getKind() === SyntaxKind.Identifier) {
-    return (expr as Identifier).getText();
+  if (expr.isKind(SyntaxKind.Identifier)) {
+    return expr.getText();
   }
   if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
     const name = expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName();

package/src/guard-html-escape.ts

@@ -83,7 +83,7 @@ function templateStaticText(tpl: Node): string {
   if (tpl.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
     return tpl.getLiteralText();
   }
-  const t = tpl as TemplateExpression;
+  const t = tpl.asKindOrThrow(SyntaxKind.TemplateExpression);
   return [
     t.getHead().getLiteralText(),
     ...t.getTemplateSpans().map((s) => s.getLiteral().getLiteralText()),
@@ -172,7 +172,7 @@ type LocalFunction = FunctionDeclaration | ArrowFunction | FunctionExpression;
 
 function localFunctionsOf(callee: Node, sf: SourceFile): LocalFunction[] | undefined {
   if (!callee.isKind(SyntaxKind.Identifier)) return undefined;
-  const decls = localDeclarations(callee as Identifier, sf);
+  const decls = localDeclarations(callee, sf);
   if (decls.length === 0) return undefined;
   const fns: LocalFunction[] = [];
   for (const d of decls) {

package/src/guard-raw-sql.ts

@@ -78,7 +78,7 @@ async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
     for (const hit of report.hits) {
       if (hit.allowed) continue;
       if (hit.file.includes("/__tests__/")) continue;
-      if (!(BLOCKING_SQL_KINDS as readonly string[]).includes(hit.kind)) continue;
+      if (!BLOCKING_SQL_KINDS.some((kind) => kind === hit.kind)) continue;
       if (hit.markerSuppressed) {
         // One line like `asRawClient(db).unsafe(` yields two hits for one marker.
         if (hit.markerReason !== undefined && hit.markerLine !== undefined) {

package/src/guard-thin-wrappers.ts

@@ -36,7 +36,6 @@ import {
   Project,
   type SourceFile,
   SyntaxKind,
-  type VariableDeclaration,
 } from "ts-morph";
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { frameworkTsConfigPath } from "./_lib/roots";
@@ -62,7 +61,7 @@ export const KNOWN_WRAPPER_REASONS = [
 export type WrapperReason = (typeof KNOWN_WRAPPER_REASONS)[number];
 
 function isKnownReason(r: string): r is WrapperReason {
-  return (KNOWN_WRAPPER_REASONS as readonly string[]).includes(r);
+  return KNOWN_WRAPPER_REASONS.some((known) => known === r);
 }
 
 // ── Built-in filter ─────────────────────────────────────────────────────
@@ -222,7 +221,7 @@ function getFnName(node: FnNode): string | undefined {
   if (node.isKind(SyntaxKind.FunctionDeclaration)) return node.getName() ?? undefined;
   const parent = node.getParent();
   if (parent?.isKind(SyntaxKind.VariableDeclaration)) {
-    return (parent as VariableDeclaration).getName();
+    return parent.getName();
   }
   if (parent?.isKind(SyntaxKind.PropertyAssignment)) {
     return parent.getFirstChild()?.getText();

package/src/guard-upgrade-state.ts

@@ -60,44 +60,42 @@ export function resolveInstalledVersion(json: UpgradeJson): string {
   return json.installedVersion ?? json.currentVersion;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 export function isPendingEntry(value: unknown): value is PendingEntry {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
+  if (!isRecord(value)) return false;
   return (
-    typeof v["version"] === "string" &&
-    typeof v["type"] === "string" &&
-    typeof v["title"] === "string"
+    typeof value["version"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["title"] === "string"
   );
 }
 
 export function isUpgradeJson(value: unknown): value is UpgradeJson {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
-  const installed = v["installedVersion"];
+  if (!isRecord(value)) return false;
+  const installed = value["installedVersion"];
   return (
-    typeof v["currentVersion"] === "string" &&
+    typeof value["currentVersion"] === "string" &&
     (installed === undefined || installed === null || typeof installed === "string") &&
-    Array.isArray(v["pending"]) &&
-    v["pending"].every(isPendingEntry)
+    Array.isArray(value["pending"]) &&
+    value["pending"].every(isPendingEntry)
   );
 }
 
 export function isPendingManualStep(value: unknown): value is PendingManualStep {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
+  if (!isRecord(value)) return false;
   return (
-    typeof v["id"] === "string" &&
-    v["id"].length > 0 &&
-    typeof v["version"] === "string" &&
-    typeof v["title"] === "string"
+    typeof value["id"] === "string" &&
+    value["id"].length > 0 &&
+    typeof value["version"] === "string" &&
+    typeof value["title"] === "string"
   );
 }
 
 function readPendingManual(parsed: unknown): readonly PendingManualStep[] {
-  const raw =
-    parsed && typeof parsed === "object"
-      ? (parsed as Record<string, unknown>)["pendingManual"]
-      : undefined;
+  const raw = isRecord(parsed) ? parsed["pendingManual"] : undefined;
   return Array.isArray(raw) ? raw.filter(isPendingManualStep) : [];
 }
 
@@ -114,10 +112,7 @@ export function readMarker(root: string): UpgradeMarker | { error: string } {
   } catch {
     return { error: `${MARKER_REL} is not valid JSON — broken marker file` };
   }
-  const version =
-    parsed && typeof parsed === "object"
-      ? (parsed as Record<string, unknown>)["version"]
-      : undefined;
+  const version = isRecord(parsed) ? parsed["version"] : undefined;
   if (typeof version !== "string" || !SEMVER_RE.test(version)) {
     return {
       error: `${MARKER_REL} is missing a valid "version" field (expected semver x.y.z[-pre][+build]) — broken marker file`,