@cosmicdrift/kumiko-guards 0.362.0 → 0.364.0

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-licenses.ts

@@ -0,0 +1,288 @@
+// Licence check over the installed third-party packages of ONE repo.
+//
+// Single-repo by design: the scanned repo is the one `cwd` sits in (the multi-repo
+// workspace scan of the private infra guard is gone). Installed packages come from
+// node_modules of the repo, its workspace members and every ancestor directory.
+// Exceptions merge the bundled dependency-license-exceptions.json with an optional file of
+// the same name in the repo root and in every ancestor whose node_modules was scanned.
+import { parseDependencyCli } from "./_lib/dependency-cli";
+import {
+  findExpiringSoon,
+  isExceptionValid,
+  loadExceptionEntries,
+  matchesPackageName,
+} from "./_lib/dependency-exceptions";
+import {
+  collectInstalledPackages,
+  type InstalledPackage,
+  installationRoots,
+} from "./_lib/installed-packages";
+
+export const LICENSES_FLAGS: readonly string[] = ["--report"];
+
+const ALLOWLIST = new Set([
+  "MIT",
+  "MIT-0",
+  "ISC",
+  "Apache-2.0",
+  "BSD-2-Clause",
+  "BSD-3-Clause",
+  "BSD-3-Clause-Clear",
+  "0BSD",
+  "Unlicense",
+  "CC0-1.0",
+  "BlueOak-1.0.0",
+  "Python-2.0",
+  "PostgreSQL",
+  "Zlib",
+  "WTFPL",
+  "Artistic-2.0",
+]);
+
+const GRAY_ZONE = new Set([
+  "LGPL-2.0",
+  "LGPL-2.1",
+  "LGPL-2.1-only",
+  "LGPL-2.1-or-later",
+  "LGPL-3.0",
+  "LGPL-3.0-only",
+  "LGPL-3.0-or-later",
+  "MPL-1.0",
+  "MPL-1.1",
+  "MPL-2.0",
+  "CDDL-1.0",
+  "CDDL-1.1",
+  "EPL-1.0",
+  "EPL-2.0",
+]);
+
+const DENYLIST_PATTERNS: RegExp[] = [
+  /^GPL-\d/,
+  /^AGPL-\d/,
+  /^SSPL-/,
+  /^BUSL-/,
+  /Commons[ -]Clause/i,
+  /^UNLICENSED$/i,
+];
+
+export const LICENSE_EXCEPTIONS_FILE = "dependency-license-exceptions.json";
+
+export type LicenseException = {
+  readonly package: string;
+  readonly version: string;
+  readonly license: string;
+  readonly reason: string;
+  readonly reviewedBy: string;
+  readonly expires: string;
+};
+
+type Verdict =
+  | { readonly kind: "ok"; readonly license: string }
+  | { readonly kind: "gray"; readonly license: string; readonly exception?: LicenseException }
+  | { readonly kind: "deny"; readonly license: string; readonly exception?: LicenseException }
+  | {
+      readonly kind: "unknown";
+      readonly raw: string | null;
+      readonly exception?: LicenseException;
+    };
+
+type Judged = { readonly pkg: InstalledPackage; readonly verdict: Verdict };
+
+export function loadLicenseExceptions(
+  roots: readonly string[],
+  bundledDir?: string,
+): LicenseException[] {
+  return loadExceptionEntries({
+    filename: LICENSE_EXCEPTIONS_FILE,
+    roots,
+    bundledDir,
+    parse: (field) => ({
+      package: field("package"),
+      version: field("version"),
+      license: field("license"),
+      reason: field("reason"),
+      reviewedBy: field("reviewedBy"),
+      expires: field("expires"),
+    }),
+  });
+}
+
+function findException(
+  pkg: InstalledPackage,
+  exceptions: readonly LicenseException[],
+): LicenseException | undefined {
+  return exceptions.find((e) => {
+    if (!matchesPackageName(e.package, pkg.name)) return false;
+    return e.version === "*" || e.version === pkg.version || /^[\^~]/.test(e.version);
+  });
+}
+
+function splitExpression(expr: string, operator: "OR" | "AND"): string[] {
+  const stripped = expr.replace(/[()]/g, "").trim();
+  return stripped
+    .split(new RegExp(`\\s+${operator}\\s+`, "i"))
+    .map((p) => p.trim())
+    .filter(Boolean);
+}
+
+function matchesDenylist(license: string): boolean {
+  return DENYLIST_PATTERNS.some((p) => p.test(license));
+}
+
+export function judgeLicense(
+  pkg: InstalledPackage,
+  exceptions: readonly LicenseException[],
+): Verdict {
+  const license = pkg.license;
+  const exception = findException(pkg, exceptions);
+  if (!license) return { kind: "unknown", raw: null, exception };
+
+  const andParts = splitExpression(license, "AND");
+  if (andParts.length > 1) {
+    if (andParts.every((p) => ALLOWLIST.has(p))) return { kind: "ok", license };
+    if (andParts.some(matchesDenylist)) return { kind: "deny", license, exception };
+    if (andParts.every((p) => ALLOWLIST.has(p) || GRAY_ZONE.has(p))) {
+      return { kind: "gray", license, exception };
+    }
+    return { kind: "unknown", raw: license, exception };
+  }
+
+  const orParts = splitExpression(license, "OR");
+  if (orParts.length > 1) {
+    if (orParts.some((p) => ALLOWLIST.has(p))) return { kind: "ok", license };
+    if (orParts.some((p) => GRAY_ZONE.has(p))) return { kind: "gray", license, exception };
+    if (orParts.every(matchesDenylist)) return { kind: "deny", license, exception };
+    return { kind: "unknown", raw: license, exception };
+  }
+
+  const clean = license.replace(/[()]/g, "").trim();
+  if (ALLOWLIST.has(clean)) return { kind: "ok", license: clean };
+  if (GRAY_ZONE.has(clean)) return { kind: "gray", license: clean, exception };
+  if (matchesDenylist(clean)) return { kind: "deny", license: clean, exception };
+  return { kind: "unknown", raw: clean, exception };
+}
+
+function hasValidException(verdict: Verdict, nowMs: number): boolean {
+  return (
+    "exception" in verdict &&
+    verdict.exception !== undefined &&
+    isExceptionValid(verdict.exception.expires, nowMs).valid
+  );
+}
+
+export type LicenseEvaluation = {
+  readonly judged: readonly Judged[];
+  readonly blocked: readonly Judged[];
+  readonly coveredGray: readonly Judged[];
+};
+
+export function evaluateLicenses(
+  packages: readonly InstalledPackage[],
+  exceptions: readonly LicenseException[],
+  nowMs: number = Date.now(),
+): LicenseEvaluation {
+  const judged = packages.map((pkg) => ({ pkg, verdict: judgeLicense(pkg, exceptions) }));
+  const blocked = judged.filter(
+    ({ verdict }) => verdict.kind !== "ok" && !hasValidException(verdict, nowMs),
+  );
+  const coveredGray = judged.filter(
+    ({ verdict }) => verdict.kind === "gray" && hasValidException(verdict, nowMs),
+  );
+  return { judged, blocked, coveredGray };
+}
+
+function verdictLicense(verdict: Verdict): string {
+  return verdict.kind === "unknown" ? String(verdict.raw) : verdict.license;
+}
+
+function describeBlocked({ pkg, verdict }: Judged, nowMs: number): string {
+  const kind =
+    verdict.kind === "deny"
+      ? "DENY"
+      : verdict.kind === "unknown"
+        ? "UNKNOWN"
+        : "GRAY (no valid exception)";
+  const exception = "exception" in verdict ? verdict.exception : undefined;
+  const expiredSuffix =
+    exception && isExceptionValid(exception.expires, nowMs).expired
+      ? ` (exception expired ${exception.expires})`
+      : "";
+  return `    [${kind}]  ${pkg.name}@${pkg.version}  license=${verdictLicense(verdict)}${expiredSuffix}`;
+}
+
+function describeCoveredGray({ pkg, verdict }: Judged): string {
+  const exception = "exception" in verdict ? verdict.exception : undefined;
+  return `    [GRAY/ok]  ${pkg.name}@${pkg.version}  license=${verdictLicense(verdict)}  expires=${exception?.expires ?? "?"}`;
+}
+
+function printReport(evaluation: LicenseEvaluation, nowMs: number): void {
+  const counts = { ok: 0, gray: 0, deny: 0, unknown: 0 };
+  for (const { verdict } of evaluation.judged) counts[verdict.kind]++;
+  console.log(`License check: ${evaluation.judged.length} packages scanned.`);
+  console.log(
+    `  ok: ${counts.ok}  gray: ${counts.gray}  deny: ${counts.deny}  unknown: ${counts.unknown}`,
+  );
+
+  if (evaluation.blocked.length > 0) {
+    console.error("\n  Problematic licenses:\n");
+    for (const judged of evaluation.blocked) console.error(describeBlocked(judged, nowMs));
+  }
+
+  if (evaluation.coveredGray.length > 0) {
+    console.log("\n  Gray zone (covered by exception):");
+    for (const judged of evaluation.coveredGray) console.log(describeCoveredGray(judged));
+  }
+
+  const used = evaluation.judged.flatMap(({ verdict }) =>
+    "exception" in verdict && verdict.exception ? [verdict.exception] : [],
+  );
+  const expiring = findExpiringSoon(used, 30, nowMs);
+  if (expiring.length > 0) {
+    console.log("\n  WARN: exceptions expire within 30 days — re-review:");
+    for (const exception of expiring) {
+      console.log(`    ${exception.package}  expires=${exception.expires}`);
+    }
+  }
+}
+
+export function runLicenseCheck(options: {
+  readonly repoRoot: string;
+  readonly reportOnly: boolean;
+  readonly packages?: readonly InstalledPackage[];
+  readonly exceptions?: readonly LicenseException[];
+  readonly nowMs?: number;
+}): number {
+  const nowMs = options.nowMs ?? Date.now();
+  const packages = options.packages ?? collectInstalledPackages(options.repoRoot);
+  if (packages.length === 0) {
+    console.error(
+      `  licenses: nothing scanned — no installed packages found for ${options.repoRoot} (run \`bun install\`).`,
+    );
+    return 1;
+  }
+  const exceptions =
+    options.exceptions ?? loadLicenseExceptions(installationRoots(options.repoRoot));
+  const evaluation = evaluateLicenses(packages, exceptions, nowMs);
+  printReport(evaluation, nowMs);
+  if (options.reportOnly) return 0;
+
+  if (evaluation.blocked.length > 0) {
+    console.error(
+      `\n  BLOCKED: ${evaluation.blocked.length} package(s) with a problematic license.`,
+    );
+    console.error(
+      `  Remove the dependency or add an exception to ${LICENSE_EXCEPTIONS_FILE} in the repo root.\n`,
+    );
+    return 1;
+  }
+  if (evaluation.coveredGray.length > 0) {
+    console.log(`\n  ${evaluation.coveredGray.length} gray-zone package(s) covered by exceptions.`);
+  }
+  return 0;
+}
+
+export function runLicensesCli(argv: readonly string[], cwd: string = process.cwd()): number {
+  const invocation = parseDependencyCli("licenses", argv, cwd);
+  if (!invocation.ok) return invocation.exitCode;
+  return runLicenseCheck({ repoRoot: invocation.repoRoot, reportOnly: invocation.reportOnly });
+}