@cosmicdrift/kumiko-guards 0.363.0 → 0.365.0

package/src/guard-comment-lang.ts

@@ -36,12 +36,16 @@ const SCAN: ScanSpec = {
 
 const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
 
+// Case-sensitive lower case: an upper-case licence name or a capitalised name
+// must not count, and a single short marker that is also an English word is
+// not enough.
 const DE_MARKER_RE =
-  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/i;
+  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/g;
+const MIN_DE_MARKER_HITS = 2;
 const UMLAUT_RE = /[äöüÄÖÜß]/;
 
 export function isGermanComment(text: string): boolean {
-  return DE_MARKER_RE.test(text) || UMLAUT_RE.test(text);
+  return UMLAUT_RE.test(text) || (text.match(DE_MARKER_RE)?.length ?? 0) >= MIN_DE_MARKER_HITS;
 }
 
 export type Site = {
@@ -68,13 +72,8 @@ function germanCommentSite(
   };
 }
 
-// After these tokens a `/` is division, not the start of a regex literal.
-const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
-  ts.SyntaxKind.Identifier,
-  ts.SyntaxKind.ThisKeyword,
-  ts.SyntaxKind.TrueKeyword,
-  ts.SyntaxKind.FalseKeyword,
-  ts.SyntaxKind.NullKeyword,
+// Tokens that end an operand without being identifiers or keywords.
+const OPERAND_END_PUNCTUATION_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.NumericLiteral,
   ts.SyntaxKind.BigIntLiteral,
   ts.SyntaxKind.StringLiteral,
@@ -88,6 +87,42 @@ const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.MinusMinusToken,
 ]);
 
+// Reserved words after which an expression (so possibly a regex) starts.
+const EXPRESSION_INTRODUCING_KEYWORDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.ReturnKeyword,
+  ts.SyntaxKind.TypeOfKeyword,
+  ts.SyntaxKind.InstanceOfKeyword,
+  ts.SyntaxKind.InKeyword,
+  ts.SyntaxKind.CaseKeyword,
+  ts.SyntaxKind.VoidKeyword,
+  ts.SyntaxKind.DeleteKeyword,
+  ts.SyntaxKind.ThrowKeyword,
+  ts.SyntaxKind.NewKeyword,
+  ts.SyntaxKind.YieldKeyword,
+  ts.SyntaxKind.AwaitKeyword,
+  ts.SyntaxKind.ElseKeyword,
+  ts.SyntaxKind.DoKeyword,
+  ts.SyntaxKind.ExtendsKeyword,
+  ts.SyntaxKind.DefaultKeyword,
+]);
+
+function isIdentifierOrKeyword(kind: ts.SyntaxKind): boolean {
+  return (
+    kind === ts.SyntaxKind.Identifier ||
+    (kind >= ts.SyntaxKind.FirstKeyword && kind <= ts.SyntaxKind.LastKeyword)
+  );
+}
+
+// After an operand end a `/` is division, not the start of a regex literal.
+// Contextual keywords (`from`, `type`, `of`, ...) scan as keyword kinds but are
+// valid member and variable names, so every non-introducing keyword counts. A `!`
+// is the non-null postfix only when the token before it ended an operand.
+function isOperandEnd(kind: ts.SyntaxKind, previousEndedOperand: boolean): boolean {
+  if (kind === ts.SyntaxKind.ExclamationToken) return previousEndedOperand;
+  if (OPERAND_END_PUNCTUATION_KINDS.has(kind)) return true;
+  return isIdentifierOrKeyword(kind) && !EXPRESSION_INTRODUCING_KEYWORDS.has(kind);
+}
+
 const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.SingleLineCommentTrivia,
   ts.SyntaxKind.MultiLineCommentTrivia,
@@ -101,11 +136,9 @@ const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
 function rescanSlashAsRegex(
   scanner: ts.Scanner,
   kind: ts.SyntaxKind,
-  previousSignificant: ts.SyntaxKind | undefined,
+  previousEndedOperand: boolean,
 ): ts.SyntaxKind {
-  if (previousSignificant !== undefined && DIVISION_PRECEDING_KINDS.has(previousSignificant)) {
-    return kind;
-  }
+  if (previousEndedOperand) return kind;
   const reScanned = scanner.reScanSlashToken();
   return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
 }
@@ -135,7 +168,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
 
   const templateBraceDepths: number[] = [];
   let braceDepth = 0;
-  let previousSignificant: ts.SyntaxKind | undefined;
+  let previousEndedOperand = false;
 
   let kind = scanner.scan();
   while (kind !== ts.SyntaxKind.EndOfFileToken) {
@@ -153,7 +186,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       }
       case ts.SyntaxKind.SlashToken:
       case ts.SyntaxKind.SlashEqualsToken:
-        kind = rescanSlashAsRegex(scanner, kind, previousSignificant);
+        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
         break;
       case ts.SyntaxKind.TemplateHead:
       case ts.SyntaxKind.TemplateMiddle:
@@ -173,7 +206,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       default:
         break;
     }
-    if (!TRIVIA_KINDS.has(kind)) previousSignificant = kind;
+    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
     kind = scanner.scan();
   }
   return sites;
@@ -234,21 +267,20 @@ function gitOrFail(args: readonly string[], cwd: string, message: string): strin
 const REWRITE_HINT = `Translate new German comments to English (why, not what), or if deliberate:\n    // ${IGNORE_TAG} <reason>`;
 
 function runTouchedMode(
-  all: readonly Site[],
   argv: readonly string[],
   root: string,
-  repoLocalScannedFiles: number,
+  repoLocalScannedFiles: ReadonlySet<string>,
 ): number {
   const baseArg = argv.find((arg) => arg.startsWith(BASE_FLAG_PREFIX));
   const baseRef = baseArg ? baseArg.slice(BASE_FLAG_PREFIX.length) : "origin/main";
   if (baseRef.startsWith("-")) {
     throw new CommentLangFailure(
-      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref.`,
+      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref. Pass a ref name such as origin/main.`,
     );
   }
 
   // No repo-local file scanned at all must not read as clean (vacuous pass).
-  if (repoLocalScannedFiles === 0) {
+  if (repoLocalScannedFiles.size === 0) {
     console.log("  Touched mode: 0 repo-local files scanned — not applicable, no failure.");
     return 0;
   }
@@ -256,7 +288,7 @@ function runTouchedMode(
   const gitToplevel = gitOrFail(
     ["rev-parse", "--show-toplevel"],
     root,
-    "Touched mode: no git repository found.",
+    "Touched mode: no git repository found. Run it inside a git checkout.",
   ).trim();
   const mergeBase = gitOrFail(
     ["merge-base", baseRef, "HEAD"],
@@ -265,35 +297,37 @@ function runTouchedMode(
   ).trim();
   // -z: NUL-terminated and unquoted, so non-ASCII paths still match the lookup below.
   const touchedFiles = gitOrFail(
-    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase],
+    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase, "HEAD"],
     gitToplevel,
-    "Touched mode: git diff --name-only failed.",
+    "Touched mode: git diff --name-only failed. Check the git error below and that the base ref is reachable.",
   )
     .split("\0")
     .filter(Boolean);
 
-  // Sites are keyed relative to root, git output relative to the toplevel;
-  // a silent mismatch would read as "no violations".
-  const sitesByGitFile = new Map<string, Site[]>();
-  for (const site of all.filter(isLocalFinding)) {
-    const gitRelPath = path.relative(gitToplevel, path.resolve(root, site.file));
-    sitesByGitFile.set(gitRelPath, [...(sitesByGitFile.get(gitRelPath) ?? []), site]);
-  }
-
+  // The commits being pushed are checked, not the working tree: contents come from
+  // HEAD so line numbers match the `mergeBase..HEAD` diff. Scan scope is keyed
+  // relative to root, git output relative to the toplevel.
   const violations: Array<{ file: string; sites: Site[] }> = [];
   for (const file of touchedFiles) {
-    const candidates = sitesByGitFile.get(file);
-    if (!candidates || candidates.length === 0) continue;
+    const rootRelFile = path.relative(root, path.resolve(gitToplevel, file));
+    if (!repoLocalScannedFiles.has(rootRelFile)) continue;
     // --literal-pathspecs: filenames with glob magic must match themselves.
+    const headContent = gitOrFail(
+      ["--literal-pathspecs", "show", `HEAD:${file}`],
+      gitToplevel,
+      `Touched mode: git show HEAD:${file} failed. Check the git error below.`,
+    );
+    const candidates = scanGermanComments(headContent, rootRelFile);
+    if (candidates.length === 0) continue;
     const addedLines = parseAddedLineRanges(
       gitOrFail(
-        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "--", file],
+        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "HEAD", "--", file],
         gitToplevel,
-        `Touched mode: git diff --unified=0 failed for ${file}.`,
+        `Touched mode: git diff --unified=0 failed for ${file}. Check the git error below.`,
       ),
     );
     const touchedSites = sitesTouchedByAddedLines(candidates, addedLines);
-    if (touchedSites.length > 0) violations.push({ file, sites: touchedSites });
+    if (touchedSites.length > 0) violations.push({ file: rootRelFile, sites: touchedSites });
   }
 
   if (violations.length === 0) {
@@ -470,25 +504,27 @@ export function runCommentLangCli(
   try {
     const all: Site[] = [];
     let scanned = 0;
-    let repoLocalScanned = 0;
+    const repoLocalScanned = new Set<string>();
     for (const absPath of scanFiles(SCAN, resolveRepoRoots(root))) {
       if (EXCLUDE.test(absPath)) continue;
       scanned++;
       const file = path.relative(root, absPath);
-      if (isLocalFinding({ file })) repoLocalScanned++;
+      if (isLocalFinding({ file })) repoLocalScanned.add(file);
       all.push(...scanGermanComments(readFileSync(absPath, "utf-8"), file));
     }
 
     // Zero scanned files must not read as a clean pass (misresolved root, empty scope).
     if (scanned === 0) {
-      throw new CommentLangFailure("Scanned 0 files — repo root or scan scope did not resolve.");
+      throw new CommentLangFailure(
+        "Scanned 0 files — repo root or scan scope did not resolve. Run it from inside a repo checkout whose kumiko.json declares the source roots.",
+      );
     }
 
     console.log(
       `Comment-Language Audit: ${scanned} files checked, ${all.length} German comment(s) found.`,
     );
 
-    if (argv.includes("--touched")) return runTouchedMode(all, argv, root, repoLocalScanned);
+    if (argv.includes("--touched")) return runTouchedMode(argv, root, repoLocalScanned);
     if (argv.includes("--list")) {
       for (const site of all.slice(0, LIST_LIMIT)) {
         console.log(`  ${site.file}:${site.line}  ${site.snippet}`);

package/src/guard-direct-entity-writes.ts

@@ -461,6 +461,9 @@ export const guard: AstGuard = {
   name: "Direct-Entity-Writes Guard",
   scan: SCAN,
   security: true,
+  hint:
+    "Write ES-entity tables through the entity write handlers / event-store executor or inside an r.projection apply (tx receiver); a direct insert/update/delete lets the projection row drift from the event stream. " +
+    "For a BLOCKED scan, check that the scan still covers the files declaring r.entity / createEventStoreExecutor.",
   run(files) {
     // Merge both collections BEFORE the empty-set check — otherwise a repo
     // that only uses r.entity (no createEventStoreExecutor anymore) would

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-pre-es-patterns.ts

@@ -163,6 +163,9 @@ const PATTERNS: readonly Pattern[] = [
 export const guard: AstGuard = {
   name: "Pre-ES-Patterns Guard",
   scan: SCAN,
+  hint:
+    "These APIs were removed with the event-sourcing migration. Use the events table with ctx.loadAggregate / queryProjection, ctx.appendEvent on aggregate streams, " +
+    'r.multiStreamProjection for cross-aggregate consumers, and configValue.created/updated/deleted events (aggregateType: "configValue") for config changes.',
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

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) : [];
@@ -270,7 +295,7 @@ function scanPackage(cwd: string, project: Project, pkg: PackageName): PackageSc
     pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
   } catch (e) {
     console.error(
-      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}).`,
+      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}). Fix the file so it is valid JSON.`,
     );
     return null;
   }
@@ -320,7 +345,9 @@ export type EvaluateResult = {
 
 function buildFinding(missing: MissingExport, version: string): UncoveredFinding {
   if (!isPackageName(missing.pkg)) {
-    throw new Error(`baseline package key not in scope: ${missing.pkg}`);
+    throw new Error(
+      `baseline package key not in scope: ${missing.pkg}. Remove the key from the baseline or re-freeze it with --write-baseline.`,
+    );
   }
   const pkg = missing.pkg;
   const changelogPath = owningChangelogPath(pkg, missing.key);
@@ -370,7 +397,7 @@ function findingsAgainstBaseline(
   for (const [pkg, keys] of Object.entries(baseline.packages)) {
     if (!isPackageName(pkg)) {
       console.error(
-        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features).`,
+        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features). Remove the key from the baseline or re-freeze it with --write-baseline.`,
       );
       continue;
     }
@@ -393,11 +420,16 @@ 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);
   if (scans.length === 0 && args.mode === "check") {
-    console.error("  No package scanned: the guard would pass vacuously.");
+    console.error(
+      "  No package scanned: the guard would pass vacuously. Run it from a kumiko-framework checkout that contains the framework package.",
+    );
     return { scans, baselineStatus: "ok", findings: [vacuousFinding()] };
   }
 
@@ -423,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[];
@@ -441,11 +538,16 @@ export async function loadChangesetParser(frameworkRootAbsPath: string): Promise
     frameworkRootAbsPath,
     "packages/framework/src/engine/changeset-changes.ts",
   );
-  if (!existsSync(parserPath)) throw new Error(`changeset parser not found: ${parserPath}`);
+  if (!existsSync(parserPath))
+    throw new Error(
+      `changeset parser not found: ${parserPath}. Run the guard from a complete kumiko-framework checkout.`,
+    );
   const loaded: unknown = await import(pathToFileURL(parserPath).href);
   const parse = isRecord(loaded) ? loaded["parseChangesetChanges"] : undefined;
   if (!isChangesetParser(parse)) {
-    throw new Error(`${parserPath} does not export parseChangesetChanges as a function`);
+    throw new Error(
+      `${parserPath} does not export parseChangesetChanges as a function. Export it from that file.`,
+    );
   }
   return parse;
 }
@@ -493,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 ────────────────────────────────────────────────────────
@@ -560,7 +662,7 @@ export function writeBaseline(
   const frameworkScan = scans.find((s) => s.pkg === "framework");
   if (!frameworkScan) {
     console.error(
-      "  framework package.json missing: asOfVersion undetermined, baseline not written.",
+      "  framework package.json missing: asOfVersion undetermined, baseline not written. Run it from a kumiko-framework checkout.",
     );
     return 1;
   }
@@ -644,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) {
@@ -665,7 +794,9 @@ export async function runPublicExportsChangelogCli(
   }
   const tsConfigFilePath = frameworkTsConfigPath(cwd);
   if (tsConfigFilePath === undefined) {
-    console.error("  public-exports-changelog: framework tsconfig.json not found.");
+    console.error(
+      "  public-exports-changelog: framework tsconfig.json not found. Run it from a complete kumiko-framework checkout.",
+    );
     return 1;
   }
   const project = new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: true });
@@ -676,14 +807,18 @@ export async function runPublicExportsChangelogCli(
     try {
       pending = await loadPendingBreakingChanges(scanCwd);
     } catch (e) {
-      console.error(`  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}`);
+      console.error(
+        `  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}. Fix the changeset file named above.`,
+      );
       return 1;
     }
     return writeBaseline(scanCwd, project, join(scanCwd, BASELINE_FILE), pending);
   }
 
   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/guard-thin-wrappers.ts

@@ -377,6 +377,9 @@ const SCAN: ScanSpec = {
   frameworkWithin: ["packages/*/src/**"],
 };
 
+const WRAPPER_FIX =
+  "call the delegate directly, or mark a deliberate wrapper with // @wrapper-known <reason>";
+
 export const check: RepoCheck = {
   name: "Thin-Wrappers Guard",
   run(roots) {
@@ -403,12 +406,16 @@ export const check: RepoCheck = {
       scanned++;
       for (const f of collectFindings(sf)) {
         if (f.markerReason === null) {
-          warnings.push({ file: f.file, line: f.line, message: `${f.fnName} → ${f.callee}` });
+          warnings.push({
+            file: f.file,
+            line: f.line,
+            message: `${f.fnName} → ${f.callee}  (${WRAPPER_FIX})`,
+          });
         } else if (!isKnownReason(f.markerReason)) {
           warnings.push({
             file: f.file,
             line: f.line,
-            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}")`,
+            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}"; use a known reason from the list in this guard)`,
           });
         }
       }