@cosmicdrift/kumiko-guards 0.364.0 → 0.365.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.364.0",
+  "version": "0.365.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.364.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.365.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/push-root.ts

@@ -1,11 +1,13 @@
 import { basename } from "node:path";
 import { findLocalRepo, localRepoDirName } from "./roots";
 
-// A worktree's folder name proves nothing (`kumiko-*` siblings share prefixes), so it is judged by its canonical checkout's directory name.
+// A worktree's folder name proves nothing (`kumiko-*` siblings share prefixes), so a path that
+// resolves to a repo is judged by its canonical checkout's directory name; the folder name only
+// counts for paths that are not a repo (yet).
 function pushRootMatchesCliScope(pushRepoRoot: string, cliScope: string): boolean {
-  if (basename(pushRepoRoot) === cliScope) return true;
   const local = findLocalRepo(pushRepoRoot);
-  return local !== undefined && (local.name === cliScope || localRepoDirName(local) === cliScope);
+  if (local === undefined) return basename(pushRepoRoot) === cliScope;
+  return local.name === cliScope || localRepoDirName(local) === cliScope;
 }
 
 // A push root left over from an earlier hook run or a debug session must not redirect a guard at the wrong repo, so it only counts when KUMIKO_CLI_SCOPE names it.

package/src/_lib/security-baseline.ts

@@ -27,7 +27,13 @@ export type SecurityBaselineLoad =
       readonly findings: SecurityBaseline["findings"];
       readonly hardFail: readonly string[];
     }
-  | { readonly kind: "invalid"; readonly file: string; readonly reason: string };
+  | {
+      readonly kind: "invalid";
+      readonly file: string;
+      readonly reason: string;
+      /** Prose shown after the reason when the reason alone is only a code. */
+      readonly detail?: string;
+    };
 
 // Compared only against the baseline file's `repo` field — a scoped npm
 // package name (`@x/y`) is no longer a path segment, so it needs no
@@ -127,7 +133,12 @@ export function loadSecurityBaseline(repo: string, repoDir: string): SecurityBas
   }
   const parsed = parseSecurityBaseline(raw);
   if (!parsed) {
-    return { kind: "invalid", file, reason: "unexpected_baseline_shape" };
+    return {
+      kind: "invalid",
+      file,
+      reason: "unexpected_baseline_shape",
+      detail: "expected format/repo/generated/total/findings and a valid hardFail",
+    };
   }
   if (parsed.repo !== repo) {
     return {
@@ -202,7 +213,7 @@ function invalidBaselineViolation(
   return {
     file: baseline.file,
     line: 1,
-    message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
+    message: `Security baseline unreadable or invalid: ${baseline.reason}${baseline.detail === undefined ? "" : ` (${baseline.detail})`}. Fix the file; a broken baseline must not release any findings.`,
   };
 }
 

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "public-exports-changelog --base=<ref> checks drops against the baseline of the merge-base and matches exported names as whole identifiers",
+    "detail": "Check mode with --base=<ref> reads .kumiko-public-exports-baseline.json from the merge-base and sends every drop against it through the changelog/changeset ratchet, so a PR can no longer hide a removal by editing or deleting the baseline. An unknown ref is an error; a base without a baseline is a bootstrap. A changelog entry or open changeset covers a drop only when every dropped name appears in it as a whole identifier (getUserById no longer covers getUser). An unparsable changes.json is reported on stderr with its path. check-wt.sh, the worktree pre-push branch and the legacy check step pass the base."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "guard-test-timeouts ignores identifier test bodies and timeout-free options; push-root no longer trusts a lookalike folder name",
+    "detail": "An identifier passed as a test argument only counts as a timeout when its type is a number or has a timeout property, so Playwright's test(title, details, body) and options like { retry: 2 } pass. A push root that resolves to a git repo is judged by its canonical checkout name, not by its folder name. An unexpected security baseline shape keeps the reason unexpected_baseline_shape and adds a readable detail."
+  },
   {
     "version": "0.364.0",
     "type": "fix",

package/src/cli.ts

@@ -36,7 +36,7 @@ const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
   ui: UI_GUARD_FLAGS,
   checks: REPO_CHECK_FLAGS,
   "comment-lang": [...COMMENT_LANG_FLAGS, "--base=<ref>"],
-  "public-exports-changelog": PUBLIC_EXPORTS_CHANGELOG_FLAGS,
+  "public-exports-changelog": [...PUBLIC_EXPORTS_CHANGELOG_FLAGS, "--base=<ref>"],
   licenses: DEPENDENCY_CHECK_FLAGS,
   security: DEPENDENCY_CHECK_FLAGS,
   outdated: DEPENDENCY_CHECK_FLAGS,

package/src/guard-lib-test-coverage.ts

@@ -74,7 +74,7 @@ function exportedCallables(sf: SourceFile): Export[] {
   return out;
 }
 
-// NodeNext-Importe schreiben ".js"/".jsx", obwohl die Quelle ".ts"/".tsx" ist
+// NodeNext imports write ".js"/".jsx" although the source is ".ts"/".tsx"
 // (and likewise .mjs/.cjs for .mts/.cts) — the extension must therefore be
 // stripped for all four pair variants when comparing module paths, otherwise
 // the link breaks.

package/src/guard-no-direct-fs.ts

@@ -121,7 +121,6 @@ const ALLOWLIST: readonly AllowEntry[] = [
   { repo: "kumiko-framework", pattern: /^packages\/create-kumiko-app\/src\/manifest\.ts$/ },
 
   // Sample apps: codegen/screenshot-mount helper, no request input.
-  { repo: "kumiko-framework", pattern: /^samples\/apps\/use-all-bundled\/schema\/generate\.ts$/ },
   {
     repo: "kumiko-framework",
     pattern: /^samples\/apps\/showcase\/src\/app\/mount-public-screenshots\.ts$/,

package/src/guard-public-exports-changelog.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -19,6 +20,12 @@ import { frameworkTsConfigPath, resolveRepoRoots } from "./_lib/roots";
 // write is refused.
 // Without an old baseline, `--write-baseline` is a bootstrap freeze.
 //
+// The committed baseline is a file the PR itself can edit (or delete and
+// bootstrap-freeze), so check mode with `--base=<ref>` additionally reads the
+// baseline from the merge-base with <ref> and runs every drop against THAT
+// baseline through the same ratchet gate as `--write-baseline`. Only when the
+// base has no baseline either is there nothing to protect.
+//
 // Scope: only the two packages with a changes.json home. packages/framework
 // has ONE changelog (src/changes.json); packages/bundled-features has one PER
 // FEATURE (src/<feature>/changes.json, feature = first export-key segment).
@@ -48,6 +55,7 @@ const OUT_OF_SCOPE_PACKAGES = [
   "renderer",
 ] as const;
 
+const BASE_FLAG_PREFIX = "--base=";
 const BASELINE_FILE = ".kumiko-public-exports-baseline.json";
 const REFREEZE_COMMAND = "bun packages/guards/src/cli.ts public-exports-changelog --write-baseline";
 const BASELINE_FORMAT_VERSION = 1;
@@ -204,6 +212,19 @@ export function compareVersionsLocal(a: string, b: string): number {
   return 0;
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Identifier boundaries, not substrings: `getUserById` must not cover a dropped `getUser`.
+export function mentionsExportName(text: string, name: string): boolean {
+  return new RegExp(`(?<![A-Za-z0-9_$])${escapeRegExp(name)}(?![A-Za-z0-9_$])`).test(text);
+}
+
+function everyNameMentioned(texts: readonly string[], names: readonly string[]): boolean {
+  return names.every((name) => texts.some((text) => mentionsExportName(text, name)));
+}
+
 export function isCoveredByChangelog(
   entries: readonly ChangelogEntryShape[],
   asOfVersion: string,
@@ -211,15 +232,16 @@ export function isCoveredByChangelog(
 ): boolean {
   // >= not >: package.json only bumps at release, so the entry `kumiko changes
   // add` writes in the removing PR carries the SAME version as asOfVersion.
-  // With exportNames, the entry must also name at least one dropped export, so
-  // a single breaking entry cannot blanket-cover unrelated drops.
-  return entries.some((e) => {
-    if (e.type !== "breaking") return false;
-    if (compareVersionsLocal(e.version, asOfVersion) < 0) return false;
-    if (exportNames.length === 0) return true;
-    const haystack = `${e.title ?? ""} ${e.detail ?? ""}`;
-    return exportNames.some((name) => haystack.includes(name));
-  });
+  // With exportNames, every dropped export must be named by some qualifying
+  // entry, so a single breaking entry cannot blanket-cover unrelated drops.
+  const qualifying = entries.filter(
+    (e) => e.type === "breaking" && compareVersionsLocal(e.version, asOfVersion) >= 0,
+  );
+  if (qualifying.length === 0) return false;
+  return everyNameMentioned(
+    qualifying.map((e) => `${e.title ?? ""} ${e.detail ?? ""}`),
+    exportNames,
+  );
 }
 
 function toChangelogEntry(e: unknown): ChangelogEntryShape[] {
@@ -241,7 +263,10 @@ function readChangelogEntries(absChangelogPath: string): ChangelogEntryShape[] {
   let raw: unknown;
   try {
     raw = JSON.parse(readFileSync(absChangelogPath, "utf-8"));
-  } catch {
+  } catch (e) {
+    console.error(
+      `  ${absChangelogPath}: changelog unreadable (${e instanceof Error ? e.message : String(e)}); its entries cannot cover a dropped export until the JSON is fixed.`,
+    );
     return [];
   }
   return Array.isArray(raw) ? raw.flatMap(toChangelogEntry) : [];
@@ -395,6 +420,9 @@ export function evaluatePublicExportsChangelog(args: {
   readonly mode: EvaluateMode;
   /** Tests pass an explicit path; production resolves `<framework root>/.kumiko-public-exports-baseline.json`. */
   readonly baselinePath?: string;
+  /** Baseline as committed on the PR's merge-base; its drops go through the ratchet gate. */
+  readonly baseBaseline?: BaselinePayload;
+  readonly pendingBreakingChanges?: PendingBreakingChanges;
 }): EvaluateResult {
   logOutOfScopeNotice();
   const scans = scanAllPackages(args.cwd, args.project);
@@ -427,9 +455,74 @@ export function evaluatePublicExportsChangelog(args: {
   }
 
   const findings = findingsAgainstBaseline(parsed.baseline, scans);
+  if (args.baseBaseline) {
+    const alreadyReported = new Set(findings.map(findingIdentity));
+    const ratchet = uncoveredDrops(
+      args.cwd,
+      scans,
+      args.baseBaseline,
+      args.pendingBreakingChanges ?? new Map(),
+    );
+    findings.push(...ratchet.filter((f) => !alreadyReported.has(findingIdentity(f))));
+  }
   return { scans, baselineStatus: "ok", findings };
 }
 
+function findingIdentity(f: UncoveredFinding): string {
+  return `${f.pkg}|${f.key}|${f.names.join(",")}`;
+}
+
+// ── Baseline of the merge-base ───────────────────────────────────────────
+
+export type BaseBaselineRead =
+  | { readonly kind: "absent" }
+  | { readonly kind: "ok"; readonly baseline: BaselinePayload }
+  | { readonly kind: "error"; readonly detail: string };
+
+function git(args: readonly string[], cwd: string): { ok: true; out: string } | { ok: false } {
+  const res = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return res.status === 0 ? { ok: true, out: res.stdout } : { ok: false };
+}
+
+export function readBaseBaseline(cwd: string, baseRef: string): BaseBaselineRead {
+  if (baseRef === "" || baseRef.startsWith("-")) {
+    return {
+      kind: "error",
+      detail: `--base must be a ref name such as origin/main (got "${baseRef}"); an empty value or a leading "-" would be read as a git option.`,
+    };
+  }
+  const mergeBase = git(["merge-base", baseRef, "HEAD"], cwd);
+  if (!mergeBase.ok) {
+    return {
+      kind: "error",
+      detail: `git merge-base ${baseRef} HEAD failed — is ${baseRef} known locally? On shallow checkouts fetch the full history or the ref.`,
+    };
+  }
+  const commit = mergeBase.out.trim();
+  const listed = git(["ls-tree", "--name-only", commit, "--", BASELINE_FILE], cwd);
+  if (!listed.ok) return { kind: "error", detail: `git ls-tree ${commit} failed.` };
+  if (listed.out.trim() === "") return { kind: "absent" };
+  const shown = git(["show", `${commit}:./${BASELINE_FILE}`], cwd);
+  if (!shown.ok) return { kind: "error", detail: `git show ${commit}:${BASELINE_FILE} failed.` };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(shown.out);
+  } catch (e) {
+    console.error(
+      `  Baseline on ${baseRef} unreadable (${e instanceof Error ? e.message : String(e)}); nothing to ratchet against.`,
+    );
+    return { kind: "absent" };
+  }
+  const parsed = parseBaseline(raw);
+  if (parsed.kind !== "ok") {
+    console.error(
+      `  Baseline on ${baseRef} is ${parsed.kind} (${parsed.detail}); nothing to ratchet against.`,
+    );
+    return { kind: "absent" };
+  }
+  return { kind: "ok", baseline: parsed.baseline };
+}
+
 // ── Open changesets ───────────────────────────────────────────────────────
 
 type ChangesetParser = (markdown: string, source: string) => readonly unknown[];
@@ -502,15 +595,15 @@ export async function loadPendingBreakingChanges(
   return pendingBreakingChangesIn(join(frameworkRootAbsPath, ".changeset"), parse);
 }
 
-// A feature-wide breaking block must not cover unrelated drops: the block has
-// to name at least one of the dropped exports.
+// A feature-wide breaking block must not cover unrelated drops: every dropped
+// export has to be named by some block of the feature.
 export function isCoveredByPendingChangeset(
   pending: PendingBreakingChanges,
   feature: string,
   droppedNames: readonly string[],
 ): boolean {
   const texts = pending.get(feature) ?? [];
-  return texts.some((text) => droppedNames.some((name) => text.includes(name)));
+  return texts.length > 0 && everyNameMentioned(texts, droppedNames);
 }
 
 // ── Write baseline ────────────────────────────────────────────────────────
@@ -653,13 +746,40 @@ function reportViolations(violations: readonly GuardViolation[]): void {
   ]);
 }
 
+// undefined = the ratchet inputs could not be read; the diagnosis is printed already.
+async function baseRatchetFor(
+  scanCwd: string,
+  mode: EvaluateMode,
+  baseRef: string | undefined,
+): Promise<
+  { baseBaseline?: BaselinePayload; pendingBreakingChanges?: PendingBreakingChanges } | undefined
+> {
+  if (baseRef === undefined || mode !== "check") return {};
+  const base = readBaseBaseline(scanCwd, baseRef);
+  if (base.kind === "error") {
+    console.error(`  ${base.detail}`);
+    return undefined;
+  }
+  if (base.kind === "absent") return {};
+  try {
+    const pendingBreakingChanges = await loadPendingBreakingChanges(scanCwd);
+    return { baseBaseline: base.baseline, pendingBreakingChanges };
+  } catch (e) {
+    console.error(
+      `  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}. Fix the changeset file named above.`,
+    );
+    return undefined;
+  }
+}
+
 export async function runPublicExportsChangelogCli(
   argv: readonly string[],
   cwd: string = process.cwd(),
 ): Promise<number> {
+  const baseArg = argv.find((arg) => arg.startsWith(BASE_FLAG_PREFIX));
   const flagsError = cliFlagsError(
     "public-exports-changelog",
-    argv,
+    argv.filter((arg) => !arg.startsWith(BASE_FLAG_PREFIX)),
     PUBLIC_EXPORTS_CHANGELOG_FLAGS,
   );
   if (flagsError !== undefined) {
@@ -696,7 +816,9 @@ export async function runPublicExportsChangelogCli(
   }
 
   const mode: EvaluateMode = argv.includes("--no-baseline") ? "no-baseline" : "check";
-  const result = evaluatePublicExportsChangelog({ cwd: scanCwd, project, mode });
+  const ratchet = await baseRatchetFor(scanCwd, mode, baseArg?.slice(BASE_FLAG_PREFIX.length));
+  if (ratchet === undefined) return 1;
+  const result = evaluatePublicExportsChangelog({ cwd: scanCwd, project, mode, ...ratchet });
   report(result);
   const baselineBroken =
     result.baselineStatus === "format-drift" || result.baselineStatus === "missing";

package/src/guard-test-timeouts.ts

@@ -177,9 +177,13 @@ function declarationBaseCallee(callee: Node): Node {
   return Node.isCallExpression(callee) ? declarationBaseCallee(callee.getExpression()) : callee;
 }
 
+// An identifier can be the Playwright test body (`test(title, details, body)`) or an options
+// variable like `{ retry: 2 }`, so it only counts when its type is a number or carries `timeout`.
 function isTimeoutArgument(arg: Node): boolean {
   if (Node.isObjectLiteralExpression(arg)) return hasTimeoutProperty(arg);
-  return !Node.isArrowFunction(arg) && !Node.isFunctionExpression(arg);
+  if (Node.isArrowFunction(arg) || Node.isFunctionExpression(arg)) return false;
+  const type = arg.getType();
+  return type.isNumber() || type.isNumberLiteral() || type.getProperty("timeout") !== undefined;
 }
 
 function declarationTimeoutReason(

package/src/pre-push.sh

@@ -195,6 +195,7 @@ if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ]
   run_guard_bin guards kumiko-guards guards
   run_guard_bin checks kumiko-guards checks
   run_guard_bin comment-lang kumiko-guards comment-lang --touched --base=origin/main
+  run_guard_bin public-exports-changelog kumiko-guards public-exports-changelog --base=origin/main
   if [ -n "$FAILED" ]; then
     echo "[pre-push] worktree check failed:$FAILED" >&2
     exit 1