@cosmicdrift/kumiko-guards 0.356.0 → 0.358.0

package/src/guard-access-denied-test.ts

@@ -17,7 +17,12 @@
  */
 
 import * as path from "node:path";
-import { type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type CallExpression,
+  type ObjectLiteralExpression,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { findRepoRootFor } from "./_lib/baseline-compare";
 import {
   ALL_REPO_KINDS,
@@ -49,6 +54,47 @@ const OPEN_ROLE_RE = /["'`](?:anonymous|all)["'`]|\baccess\.(?:all|anonymous)\b/
 
 type RoleRestrictedHandler = { name: string; file: string; line: number };
 
+function writeHandlerOptions(call: CallExpression): ObjectLiteralExpression | undefined {
+  const callee = call.getExpression().getText();
+  if (callee !== "defineWriteHandler" && !/\.writeHandler$/.test(callee)) return undefined;
+  const arg = call.getArguments()[0];
+  if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
+  return arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+}
+
+function accessObjectOf(obj: ObjectLiteralExpression): ObjectLiteralExpression | undefined {
+  const accessProp = obj.getProperty("access");
+  if (!accessProp || accessProp.getKind() !== SyntaxKind.PropertyAssignment) return undefined;
+  const accessInit = accessProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
+  if (!accessInit || accessInit.getKind() !== SyntaxKind.ObjectLiteralExpression) return undefined;
+  return accessInit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+}
+
+function restrictsToRoles(accessObj: ObjectLiteralExpression): boolean {
+  if (accessObj.getProperty("openToAll")) return false;
+  const rolesProp = accessObj.getProperty("roles");
+  if (!rolesProp) return false;
+  if (
+    rolesProp.getKind() !== SyntaxKind.PropertyAssignment &&
+    rolesProp.getKind() !== SyntaxKind.ShorthandPropertyAssignment
+  )
+    return false;
+  return !OPEN_ROLE_RE.test(rolesProp.getText());
+}
+
+function roleRestrictedHandlerOf(
+  call: CallExpression,
+  filePath: string,
+): RoleRestrictedHandler | undefined {
+  const obj = writeHandlerOptions(call);
+  if (!obj) return undefined;
+  const name = literalStringOf(obj.getProperty("name"));
+  if (!name) return undefined;
+  const accessObj = accessObjectOf(obj);
+  if (!accessObj || !restrictsToRoles(accessObj)) return undefined;
+  return { name, file: filePath, line: call.getStartLineNumber() };
+}
+
 export function findRoleRestrictedWriteHandlers(
   files: readonly SourceFile[],
 ): RoleRestrictedHandler[] {
@@ -56,28 +102,8 @@ export function findRoleRestrictedWriteHandlers(
   for (const sf of files) {
     if (TEST_FILE_RE.test(sf.getFilePath())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      const callee = call.getExpression().getText();
-      if (callee !== "defineWriteHandler" && !/\.writeHandler$/.test(callee)) continue;
-      const arg = call.getArguments()[0];
-      if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
-      const obj = arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-      const name = literalStringOf(obj.getProperty("name"));
-      if (!name) continue;
-      const accessProp = obj.getProperty("access");
-      if (!accessProp || accessProp.getKind() !== SyntaxKind.PropertyAssignment) continue;
-      const accessInit = accessProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
-      if (!accessInit || accessInit.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
-      const accessObj = accessInit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-      if (accessObj.getProperty("openToAll")) continue;
-      const rolesProp = accessObj.getProperty("roles");
-      if (!rolesProp) continue;
-      if (
-        rolesProp.getKind() !== SyntaxKind.PropertyAssignment &&
-        rolesProp.getKind() !== SyntaxKind.ShorthandPropertyAssignment
-      )
-        continue;
-      if (OPEN_ROLE_RE.test(rolesProp.getText())) continue;
-      out.push({ name, file: sf.getFilePath(), line: call.getStartLineNumber() });
+      const handler = roleRestrictedHandlerOf(call, sf.getFilePath());
+      if (handler) out.push(handler);
     }
   }
   return out;

package/src/guard-app-feature-structure.ts

@@ -1,17 +1,17 @@
 #!/usr/bin/env bun
-// App-Features folgen der bundled-features-Konvention (Referenz: tenant/):
-// feature.ts = nur Registrierung, Screens unter web/, Handler unter handlers/.
-// Dieser Guard flaggt die drei teuersten Abweichungen:
-//   1. web.tsx/web.ts-Monolith bzw. JSX-Screens direkt am Feature-Root
-//   2. feature.ts als Logik-Dump (> MAX_FEATURE_TS_LINES Zeilen)
-//   3. r.screen({ type: "custom" }) ohne Allowlist-Tag — deklarative
-//      Screen-Typen (entityList/dashboard/data-table) sind der Default.
+// App features follow the bundled-features convention (reference: tenant/):
+// feature.ts = registration only, screens under web/, handlers under handlers/.
+// This guard flags the three most expensive deviations:
+//   1. web.tsx/web.ts monolith or JSX screens directly at the feature root
+//   2. feature.ts as a logic dump (> MAX_FEATURE_TS_LINES lines)
+//   3. r.screen({ type: "custom" }) without an allowlist tag — declarative
+//      screen types (entityList/dashboard/data-table) are the default.
 //
-// ponytail: Handler-Datei-Konvention (*.query.ts/*.write.ts unter handlers/)
-// wird noch nicht erzwungen — nachziehen, wenn die Registrierungs-API-Formen
-// stabil inventarisiert sind.
+// ponytail: the handler file convention (*.query.ts/*.write.ts under handlers/)
+// is not enforced yet — add it once the registration API shapes are
+// inventoried and stable.
 //
-// Teil von App-Mounting 2.0 (infra#208).
+// Part of App-Mounting 2.0 (infra#208).
 
 import * as path from "node:path";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -29,13 +29,88 @@ const IGNORE_TAG = "kumiko-lint-ignore app-feature-structure";
 
 const MAX_FEATURE_TS_LINES = 300;
 
-// src/features/<name>/<file> bzw. packages/bundled-features/src/<name>/<file>
-// — genau eine Ebene unter dem Feature-Ordner.
+// src/features/<name>/<file> or packages/bundled-features/src/<name>/<file>
+// — exactly one level below the feature folder.
 function isFeatureRootFile(filePath: string): boolean {
   const m = filePath.match(/(src\/features|packages\/bundled-features\/src)\/[^/]+\/[^/]+$/);
   return m !== null;
 }
 
+function isIgnoredFile(sf: SourceFile): boolean {
+  return hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG);
+}
+
+// 1a. web.ts(x) monolith at the feature root
+function checkWebMonolith(sf: SourceFile, base: string, violations: GuardViolation[]): void {
+  const filePath = sf.getFilePath();
+  if (isFeatureRootFile(filePath) && (base === "web.tsx" || base === "web.ts")) {
+    if (!isIgnoredFile(sf)) {
+      violations.push({
+        file: filePath,
+        line: 1,
+        message:
+          "web monolith at feature root — screens/client def belong under web/ (index.ts + one file per screen)",
+      });
+    }
+  }
+}
+
+// 1b. JSX directly at the feature root (screens belong under web/)
+function checkRootJsx(sf: SourceFile, base: string, violations: GuardViolation[]): void {
+  const filePath = sf.getFilePath();
+  if (
+    isFeatureRootFile(filePath) &&
+    filePath.endsWith(".tsx") &&
+    base !== "web.tsx" &&
+    sf.getDescendantsOfKind(SyntaxKind.JsxElement).length +
+      sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).length >
+      0 &&
+    !isIgnoredFile(sf)
+  ) {
+    violations.push({
+      file: filePath,
+      line: 1,
+      message: "JSX component at feature root — move it under web/",
+    });
+  }
+}
+
+// 2. feature.ts as a logic dump
+function checkFeatureTsSize(sf: SourceFile, base: string, violations: GuardViolation[]): void {
+  const filePath = sf.getFilePath();
+  if (base === "feature.ts" && isFeatureRootFile(filePath)) {
+    const lines = sf.getEndLineNumber();
+    if (lines > MAX_FEATURE_TS_LINES && !isIgnoredFile(sf)) {
+      violations.push({
+        file: filePath,
+        line: 1,
+        message: `feature.ts has ${lines} lines (max ${MAX_FEATURE_TS_LINES}) — move handlers to handlers/, schemas to schema/, logic to lib/`,
+      });
+    }
+  }
+}
+
+// 3. type: "custom" without an allowlist tag
+function checkCustomScreens(sf: SourceFile, violations: GuardViolation[]): void {
+  for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+    if (prop.getName() !== "type") continue;
+    const init = prop.getInitializer();
+    if (init === undefined || init.getKind() !== SyntaxKind.StringLiteral) continue;
+    if (init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText() !== "custom") continue;
+    // r.screen context only: the surrounding call target must end in .screen.
+    const call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
+    if (call === undefined || !call.getExpression().getText().endsWith(".screen")) continue;
+    // Only the screen's own config declares its type; nested `{ type: "custom" }` objects are widget config.
+    if (prop.getParent() !== call.getArguments()[0]) continue;
+    if (hasIgnoreTag(call, IGNORE_TAG) || hasIgnoreTag(prop, IGNORE_TAG)) continue;
+    violations.push({
+      file: sf.getFilePath(),
+      line: prop.getStartLineNumber(),
+      message: `r.screen type:"custom" without allowlist tag — use a declarative screen type or // ${IGNORE_TAG} <reason>`,
+    });
+  }
+}
+
 export const guard: AstGuard = {
   name: "App-Feature-Structure Guard (App-Repos)",
   scan: SCAN,
@@ -48,66 +123,10 @@ export const guard: AstGuard = {
       const filePath = sf.getFilePath();
       if (EXCLUDE.test(filePath)) continue;
       const base = path.basename(filePath);
-
-      // 1a. web.ts(x)-Monolith am Feature-Root
-      if (isFeatureRootFile(filePath) && (base === "web.tsx" || base === "web.ts")) {
-        if (!hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)) {
-          violations.push({
-            file: filePath,
-            line: 1,
-            message:
-              "web monolith at feature root — screens/client def belong under web/ (index.ts + one file per screen)",
-          });
-        }
-      }
-
-      // 1b. JSX direkt am Feature-Root (Screens gehören unter web/)
-      if (
-        isFeatureRootFile(filePath) &&
-        filePath.endsWith(".tsx") &&
-        base !== "web.tsx" &&
-        sf.getDescendantsOfKind(SyntaxKind.JsxElement).length +
-          sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).length >
-          0 &&
-        !hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)
-      ) {
-        violations.push({
-          file: filePath,
-          line: 1,
-          message: "JSX component at feature root — move it under web/",
-        });
-      }
-
-      // 2. feature.ts als Logik-Dump
-      if (base === "feature.ts" && isFeatureRootFile(filePath)) {
-        const lines = sf.getEndLineNumber();
-        if (lines > MAX_FEATURE_TS_LINES && !hasIgnoreTag(sf.getChildren()[0] ?? sf, IGNORE_TAG)) {
-          violations.push({
-            file: filePath,
-            line: 1,
-            message: `feature.ts has ${lines} lines (max ${MAX_FEATURE_TS_LINES}) — move handlers to handlers/, schemas to schema/, logic to lib/`,
-          });
-        }
-      }
-
-      // 3. type: "custom" ohne Allowlist-Tag
-      for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
-        if (prop.getName() !== "type") continue;
-        const init = prop.getInitializer();
-        if (init === undefined || init.getKind() !== SyntaxKind.StringLiteral) continue;
-        if (init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText() !== "custom") continue;
-        // Nur r.screen-Kontext: das umgebende Call-Target muss auf .screen enden.
-        const call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
-        if (call === undefined || !call.getExpression().getText().endsWith(".screen")) continue;
-        // Only the screen's own config declares its type; nested `{ type: "custom" }` objects are widget config.
-        if (prop.getParent() !== call.getArguments()[0]) continue;
-        if (hasIgnoreTag(call, IGNORE_TAG) || hasIgnoreTag(prop, IGNORE_TAG)) continue;
-        violations.push({
-          file: filePath,
-          line: prop.getStartLineNumber(),
-          message: `r.screen type:"custom" without allowlist tag — use a declarative screen type or // ${IGNORE_TAG} <reason>`,
-        });
-      }
+      checkWebMonolith(sf, base, violations);
+      checkRootJsx(sf, base, violations);
+      checkFeatureTsSize(sf, base, violations);
+      checkCustomScreens(sf, violations);
     }
     return { violations };
   },

package/src/guard-broker-subscribe.ts

@@ -1,30 +1,30 @@
 #!/usr/bin/env bun
 /**
- * Guard R8: verbietet `broker.subscribe(...)` ausserhalb des Frameworks.
+ * Guard R8: forbids `broker.subscribe(...)` outside the framework.
  *
- * Feature- und App-Code soll NIE direkt an den Event-Broker subscriben — die
- * Registrar-API ist der einzige erlaubte Weg, Events zu konsumieren:
+ * Feature and app code must NEVER subscribe to the event broker directly — the
+ * registrar API is the only allowed way to consume events:
  *   - `r.onEvent("event-name", handler)`
  *   - `r.job({ trigger: { on: "event-name" }, handler })`
  *
- * Ein direktes `broker.subscribe(...)` umgeht Lifecycle, Idempotency, Dedup
- * und Replay des Dispatchers — genau die Garantien, die die Registrar-API
- * gibt. Heute gibt es im Kumiko-Code KEINEN solchen Call (der Broker ist
- * framework-intern, nicht exportiert) — der Guard ist ein Tripwire, der
- * zuschlägt, sobald jemand eine Broker-Abstraktion einführt und Feature-Code
- * direkt daran hängt.
+ * A direct `broker.subscribe(...)` bypasses lifecycle, idempotency, dedup
+ * and replay of the dispatcher — exactly the guarantees the registrar API
+ * gives. Today there is NO such call in the Kumiko code (the broker is
+ * framework-internal, not exported) — the guard is a tripwire that fires as
+ * soon as someone introduces a broker abstraction and hooks feature code
+ * directly onto it.
  *
- * Erkennung (Name-Heuristik, keine Typ-Resolution): `X.subscribe(...)` wo der
- * terminale Bezeichner von `X` `broker` oder `eventBroker` heisst (case-
- * insensitive — fängt `broker`, `eventBroker`, `ctx.broker`, `this.eventBroker`).
- * Store-/Observable-`.subscribe` (RxJS, React `controller.subscribe`) heisst
- * nicht `broker` → kein Treffer.
+ * Detection (name heuristic, no type resolution): `X.subscribe(...)` where the
+ * terminal identifier of `X` is `broker` or `eventBroker` (case-
+ * insensitive — catches `broker`, `eventBroker`, `ctx.broker`, `this.eventBroker`).
+ * Store/observable `.subscribe` (RxJS, React `controller.subscribe`) is not
+ * named `broker` → no hit.
  *
- * Ausnahme: `packages/framework/src/pipeline/**` — dort lebt das Broker-
- * Plumbing selbst (framework-intern, erlaubt).
+ * Exception: `packages/framework/src/pipeline/**` — the broker plumbing
+ * itself lives there (framework-internal, allowed).
  *
  * Usage: bun guards/guard-broker-subscribe.ts
- * Exit 1 bei Fund, 0 wenn sauber.
+ * Exit 1 on a finding, 0 when clean.
  */
 
 import * as path from "node:path";

package/src/guard-comment-lang.ts

@@ -50,6 +50,32 @@ export type Site = {
   readonly snippet: string;
 };
 
+function germanCommentSite(
+  fullText: string,
+  file: string,
+  start: number,
+  text: string,
+): Site | undefined {
+  if (lineHasIgnoreTag(text, IGNORE_TAG) || !isGermanComment(text)) return undefined;
+  const line = fullText.slice(0, start).split("\n").length;
+  return {
+    file,
+    line,
+    endLine: line + (text.match(/\n/g)?.length ?? 0),
+    snippet: text.length > 80 ? `${text.slice(0, 77)}...` : text,
+  };
+}
+
+function closesTemplateSubstitution(
+  templateBraceDepths: readonly number[],
+  braceDepth: number,
+): boolean {
+  return (
+    templateBraceDepths.length > 0 &&
+    braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
+  );
+}
+
 // Template substitutions can nest braces (object literals, arrow bodies, other
 // templates). The raw scanner tokenizes a `}` as a plain CloseBraceToken and
 // never resumes template mode, so reScanTemplateToken() must run once brace
@@ -71,16 +97,13 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
     switch (kind) {
       case ts.SyntaxKind.SingleLineCommentTrivia:
       case ts.SyntaxKind.MultiLineCommentTrivia: {
-        const text = scanner.getTokenText();
-        if (!lineHasIgnoreTag(text, IGNORE_TAG) && isGermanComment(text)) {
-          const line = fullText.slice(0, scanner.getTokenStart()).split("\n").length;
-          sites.push({
-            file,
-            line,
-            endLine: line + (text.match(/\n/g)?.length ?? 0),
-            snippet: text.length > 80 ? `${text.slice(0, 77)}...` : text,
-          });
-        }
+        const site = germanCommentSite(
+          fullText,
+          file,
+          scanner.getTokenStart(),
+          scanner.getTokenText(),
+        );
+        if (site) sites.push(site);
         break;
       }
       case ts.SyntaxKind.SlashToken:
@@ -99,10 +122,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
         braceDepth++;
         break;
       case ts.SyntaxKind.CloseBraceToken:
-        if (
-          templateBraceDepths.length > 0 &&
-          braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
-        ) {
+        if (closesTemplateSubstitution(templateBraceDepths, braceDepth)) {
           templateBraceDepths.pop();
           kind = scanner.reScanTemplateToken(false);
           continue;
@@ -262,47 +282,71 @@ function sumCounts(counts: Readonly<Record<string, number>>): number {
   return Object.values(counts).reduce((total, count) => total + count, 0);
 }
 
-function runBaselineMode(all: readonly Site[], argv: readonly string[], root: string): number {
-  const baselinePath = path.join(root, BASELINE_FILE);
+function isBaselineCandidate(value: unknown): value is Partial<Baseline> {
+  return typeof value === "object" && value !== null;
+}
+
+function hasPerFileObject(baseline: Partial<Baseline>): baseline is Partial<Baseline> & {
+  readonly perFile: Record<string, number>;
+} {
+  return typeof baseline.perFile === "object" && baseline.perFile !== null;
+}
+
+function countFindingsByFile(all: readonly Site[]): Record<string, number> {
   const countByFile: Record<string, number> = {};
   for (const site of all.filter(isLocalFinding)) {
     countByFile[site.file] = (countByFile[site.file] ?? 0) + 1;
   }
-  const currentTotal = sumCounts(countByFile);
+  return countByFile;
+}
 
-  if (argv.includes("--write-baseline")) {
-    const payload: Baseline = {
-      format: BASELINE_FORMAT_VERSION,
-      generated: new Date().toISOString().slice(0, 10),
-      total: currentTotal,
-      perFile: Object.fromEntries(
-        Object.entries(countByFile).sort(([a], [b]) => a.localeCompare(b)),
-      ),
-    };
-    writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`);
-    console.log(`  Baseline written: ${baselinePath} (total ${currentTotal})`);
-    return 0;
-  }
-  if (argv.includes("--no-baseline")) {
-    console.log("  Baseline comparison skipped (--no-baseline).");
-    return 0;
-  }
-  if (!existsSync(baselinePath)) {
-    console.log("  No baseline found. Freeze one first with `--write-baseline`.");
-    return 1;
-  }
+function writeBaselineFile(
+  baselinePath: string,
+  countByFile: Readonly<Record<string, number>>,
+  currentTotal: number,
+): void {
+  const payload: Baseline = {
+    format: BASELINE_FORMAT_VERSION,
+    generated: Temporal.Now.instant().toString().slice(0, 10),
+    total: currentTotal,
+    perFile: Object.fromEntries(Object.entries(countByFile).sort(([a], [b]) => a.localeCompare(b))),
+  };
+  writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`);
+  console.log(`  Baseline written: ${baselinePath} (total ${currentTotal})`);
+}
+
+type LoadedBaseline = Partial<Baseline> & { readonly perFile: Record<string, number> };
 
-  const rawBaseline: Partial<Baseline> = JSON.parse(readFileSync(baselinePath, "utf-8"));
-  if (rawBaseline.format !== BASELINE_FORMAT_VERSION || rawBaseline.perFile === undefined) {
+// Prints the diagnosis itself and returns undefined when the baseline cannot be used.
+function readBaselineOrReport(baselinePath: string): LoadedBaseline | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(baselinePath, "utf-8"));
+  } catch (error) {
+    console.log(
+      `  Baseline unreadable: ${error instanceof Error ? error.message : String(error)}. Rewrite it once with: kumiko-guards comment-lang --write-baseline`,
+    );
+    return undefined;
+  }
+  // JSON `null`, numbers and strings parse fine but carry no baseline: report them as format drift.
+  const rawBaseline: Partial<Baseline> = isBaselineCandidate(parsed) ? parsed : {};
+  if (rawBaseline.format !== BASELINE_FORMAT_VERSION || !hasPerFileObject(rawBaseline)) {
     console.log(
       `  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, got format=${rawBaseline.format ?? "<missing>"}.`,
     );
     console.log("  Rewrite it once with: kumiko-guards comment-lang --write-baseline");
-    return 1;
+    return undefined;
   }
-  const baselinePerFile = rawBaseline.perFile;
+  return rawBaseline;
+}
 
-  const regressions: Array<{ file: string; baseline: number; current: number }> = [];
+type BaselineRegression = { file: string; baseline: number; current: number };
+
+function compareCountsToBaseline(
+  countByFile: Readonly<Record<string, number>>,
+  baselinePerFile: Readonly<Record<string, number>>,
+): { regressions: BaselineRegression[]; reduced: number } {
+  const regressions: BaselineRegression[] = [];
   let reduced = 0;
   for (const file of new Set([...Object.keys(countByFile), ...Object.keys(baselinePerFile)])) {
     const expected = baselinePerFile[file] ?? 0;
@@ -310,24 +354,52 @@ function runBaselineMode(all: readonly Site[], argv: readonly string[], root: st
     if (current > expected) regressions.push({ file, baseline: expected, current });
     else if (current < expected) reduced += expected - current;
   }
+  return { regressions, reduced };
+}
 
-  if (regressions.length > 0) {
+function printRegressions(all: readonly Site[], regressions: readonly BaselineRegression[]): void {
+  console.log(
+    `\n  REGRESSION: ${regressions.length} file(s) have more German comments than the baseline:`,
+  );
+  for (const regression of regressions) {
     console.log(
-      `\n  REGRESSION: ${regressions.length} file(s) have more German comments than the baseline:`,
+      `    ${regression.file}  baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline})`,
     );
-    for (const regression of regressions) {
-      console.log(
-        `    ${regression.file}  baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline})`,
-      );
-      for (const site of all.filter((candidate) => candidate.file === regression.file)) {
-        console.log(`      :${site.line}  ${site.snippet}`);
-      }
+    for (const site of all.filter((candidate) => candidate.file === regression.file)) {
+      console.log(`      :${site.line}  ${site.snippet}`);
     }
-    console.log(`\n  ${REWRITE_HINT}`);
+  }
+  console.log(`\n  ${REWRITE_HINT}`);
+}
+
+function runBaselineMode(all: readonly Site[], argv: readonly string[], root: string): number {
+  const baselinePath = path.join(root, BASELINE_FILE);
+  const countByFile = countFindingsByFile(all);
+  const currentTotal = sumCounts(countByFile);
+
+  if (argv.includes("--write-baseline")) {
+    writeBaselineFile(baselinePath, countByFile, currentTotal);
+    return 0;
+  }
+  if (argv.includes("--no-baseline")) {
+    console.log("  Baseline comparison skipped (--no-baseline).");
+    return 0;
+  }
+  if (!existsSync(baselinePath)) {
+    console.log("  No baseline found. Freeze one first with `--write-baseline`.");
+    return 1;
+  }
+
+  const baseline = readBaselineOrReport(baselinePath);
+  if (baseline === undefined) return 1;
+
+  const { regressions, reduced } = compareCountsToBaseline(countByFile, baseline.perFile);
+  if (regressions.length > 0) {
+    printRegressions(all, regressions);
     return 1;
   }
 
-  console.log(`  ✓ Baseline (${rawBaseline.total}) — current ${currentTotal}`);
+  console.log(`  ✓ Baseline (${baseline.total}) — current ${currentTotal}`);
   if (reduced > 0) {
     console.log(
       `  ✓ ${reduced} German comment(s) removed since the baseline. Consider \`--write-baseline\`.`,