@cosmicdrift/kumiko-guards 0.1.1 → 0.3.0

package/src/guard-pii-annotations.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env bun
+/**
+ * Guard: PII-typische Entity-Feldnamen ohne Annotation, mit Baseline-
+ * Regression-Guard wie check-complexity.ts.
+ *
+ * Mirrors the boot heuristic from validatePiiAndRetention. Authors mark
+ * fields with { pii: true }, { userOwned }, { tenantOwned: true },
+ * { allowPlaintext: "reason" } (legacy) or { personal: ... } (0.210.0
+ * successor to the four legacy subject annotations).
+ *
+ * `.kumiko-pii-annotations-baseline.json` im Repo-Root pinnt pro File die
+ * eingefrorene Fund-Anzahl:
+ *   - aktuell <= baseline pro File: PASS
+ *   - aktuell >  baseline pro File: FAIL (neues unannotiertes PII-Feld)
+ * Reduktionen updaten die Baseline NICHT automatisch — nach Annotations-
+ * Commits `--write-baseline` aufrufen. Ohne Baseline-Datei bleibt der Guard
+ * warning-only (Bootstrap: einmalig `--write-baseline`).
+ *
+ * Usage:
+ *   bun guards/guard-pii-annotations.ts                  # Vergleich gegen Baseline
+ *   bun guards/guard-pii-annotations.ts --write-baseline # Baseline neu schreiben
+ *   bun guards/guard-pii-annotations.ts --no-baseline    # Vergleich überspringen
+ */
+import * as path from "node:path";
+import {
+  type CallExpression,
+  type Node,
+  type ObjectLiteralExpression,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+import {
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  type GuardOutcome,
+  type GuardViolation,
+  isLocalFinding,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+
+// Keep in sync with boot-validator/entity-handler.ts PII_*_NAME_HINTS.
+const PII_DIRECT_NAME_HINTS = new Set([
+  "email",
+  "phone",
+  "phonenumber",
+  "mobile",
+  "address",
+  "street",
+  "postalcode",
+  "zipcode",
+  "zip",
+  "city",
+  "displayname",
+  "firstname",
+  "lastname",
+  "fullname",
+  "birthday",
+  "birthdate",
+  "dateofbirth",
+  "dob",
+  "ssn",
+  "taxid",
+  "vatid",
+  "passport",
+  "iban",
+  "bic",
+]);
+
+const PII_USER_OWNED_NAME_HINTS = new Set([
+  "body",
+  "text",
+  "content",
+  "message",
+  "comment",
+  "description",
+  "note",
+  "notes",
+]);
+
+function relFile(sf: SourceFile): string {
+  return path.relative(ROOT, sf.getFilePath());
+}
+
+function fieldFactoryOptions(call: CallExpression): ObjectLiteralExpression | undefined {
+  const first = call.getArguments()[0];
+  return first?.isKind(SyntaxKind.ObjectLiteralExpression) ? first : undefined;
+}
+
+// Subject annotations answering "is this PII" (kept in sync with the
+// author-facing PersonalAnnotations type, @cosmicdrift/kumiko-types
+// packages/types/src/fields.ts). `personal` (0.210.0) is the successor
+// to the four legacy fields below — every value counts as answered,
+// including `personal: false` (the framework requires a `reason` for
+// it). `find` is NOT a silencer: it resolves to lookupable/searchable/
+// sensitive, which never answered the PII question either. `encrypted`
+// isn't one either — the boot validator checks it only together with
+// `sensitive` (ciphertext-at-rest), never as a substitute.
+function isPiiSilencerAssignment(name: string, init: Node | undefined): boolean {
+  if (name === "personal") {
+    return (
+      init !== undefined &&
+      init.getKind() !== SyntaxKind.UndefinedKeyword &&
+      !(init.isKind(SyntaxKind.Identifier) && init.getText() === "undefined") &&
+      init.getKind() !== SyntaxKind.NullKeyword
+    );
+  }
+  if (name === "allowPlaintext") return init?.isKind(SyntaxKind.StringLiteral) ?? false;
+  if (name === "pii") return init?.getKind() === SyntaxKind.TrueKeyword;
+  if (name === "tenantOwned") return init?.getKind() === SyntaxKind.TrueKeyword;
+  if (name === "userOwned") return init?.isKind(SyntaxKind.ObjectLiteralExpression) ?? false;
+  return false;
+}
+
+function objectHasPiiSilencer(obj: ObjectLiteralExpression): boolean {
+  for (const prop of obj.getProperties()) {
+    if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
+    if (isPiiSilencerAssignment(prop.getName(), prop.getInitializer())) return true;
+  }
+  return false;
+}
+
+function enclosingFieldName(call: CallExpression): string | null {
+  let node = call.getParent();
+  while (node) {
+    if (node.isKind(SyntaxKind.PropertyAssignment)) {
+      return node.getName();
+    }
+    node = node.getParent();
+  }
+  return null;
+}
+
+export interface Finding {
+  file: string;
+  line: number;
+  fieldName: string;
+  hint: string;
+}
+
+function scanFieldFactories(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression().getText();
+    if (callee !== "createTextField" && callee !== "createLongTextField") continue;
+
+    const fieldName = enclosingFieldName(call);
+    if (!fieldName) continue;
+
+    const options = fieldFactoryOptions(call);
+    if (options && objectHasPiiSilencer(options)) continue;
+
+    const lower = fieldName.toLowerCase();
+    let hint: string | null = null;
+    if (PII_DIRECT_NAME_HINTS.has(lower)) {
+      hint = `{ personal: ... } or { pii: true } or { allowPlaintext: "is-business-data" }`;
+    } else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
+      hint = `{ personal: { of: "<authorIdField>" }, find: "exact" } or { userOwned: { ownerField: "<authorIdField>" } } or { allowPlaintext: "..." }`;
+    }
+    if (!hint) continue;
+
+    const line = call.getStartLineNumber();
+    findings.push({ file: relFile(sf), line, fieldName, hint });
+    console.warn(
+      `  [pii-annotations WARN] ${relFile(sf)}:${line}  field "${fieldName}" looks like PII — mark ${hint}`,
+    );
+  }
+  return findings;
+}
+
+function scan(files: readonly SourceFile[]): {
+  findings: Finding[];
+  scanned: number;
+} {
+  const findings: Finding[] = [];
+  let scanned = 0;
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    scanned++;
+    findings.push(...scanFieldFactories(sf));
+  }
+  return { findings, scanned };
+}
+
+function localFindings(findings: readonly Finding[]): readonly Finding[] {
+  return findings.filter(isLocalFinding);
+}
+
+function countByFile(findings: readonly Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const f of findings) counts[f.file] = (counts[f.file] ?? 0) + 1;
+  return counts;
+}
+
+const BASELINE_FILE = ".kumiko-pii-annotations-baseline.json";
+const piiBaseline = baselineRatchet({
+  file: path.join(ROOT, BASELINE_FILE),
+  formatVersion: 1,
+  unit: "PII finding(s)",
+});
+
+// One place for "what goes into the baseline", used by both the compare and
+// the write path — a sibling finding leaking into the written file would turn
+// a foreign checkout's code into a local, unfixable red.
+export function baselineCounts(findings: readonly Finding[]): Record<string, number> {
+  return countByFile(localFindings(findings));
+}
+
+function checkBaseline(findings: readonly Finding[]): GuardViolation[] {
+  const local = localFindings(findings);
+  const resolveLine = (file: string): number => local.find((f) => f.file === file)?.line ?? 1;
+  return piiBaseline.check(
+    baselineCounts(findings),
+    `Annotate the field ({ personal: ... } / { pii: true } / { userOwned: ... } / { tenantOwned: true } / { allowPlaintext: "..." }).`,
+    {
+      formatDriftRemediation: `Run \`bun guards/guard-pii-annotations.ts --write-baseline\` once.`,
+      resolveLine,
+    },
+  );
+}
+
+function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
+  const { findings } = scan(files);
+  if (!compareBaseline) {
+    console.log("  Baseline comparison skipped (--no-baseline).");
+    return { violations: [] };
+  }
+  return { violations: checkBaseline(findings) };
+}
+
+export const guard: AstGuard = {
+  name: "PII-Annotations Guard",
+  scan: SCAN,
+  hint: "after a deliberate annotation: `bun guards/guard-pii-annotations.ts --write-baseline`",
+  run: (files) => analyse(files, true),
+};
+
+// Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
+// (run-guards.ts) faehrt alle Guards mit derselben argv, ein
+// --write-baseline dort duerfte die Baseline nicht stillschweigend
+// neu schreiben.
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    const { findings } = scan(filesForGuard(project, guard));
+    piiBaseline.write(baselineCounts(findings));
+    process.exit(0);
+  }
+  if (args.includes("--no-baseline")) {
+    const project = buildSharedProject([guard]);
+    analyse(filesForGuard(project, guard), false);
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/guard-pre-es-patterns.ts

@@ -188,7 +188,7 @@ export const guard: AstGuard = {
         file: "packages/framework/src/pipeline/event-log.ts",
         line: 0,
         message:
-          "BLOCKED: pipeline/event-log.ts wurde wiederhergestellt. Die Datei gehört gelöscht — ihre Rolle übernimmt die events-Tabelle.",
+          "BLOCKED: pipeline/event-log.ts was restored. The file must be deleted — the events table now takes over its role.",
       });
     }
 

package/src/guard-primitives-discipline.ts

@@ -50,7 +50,7 @@ const FORBIDDEN_TAGS: ReadonlyArray<{
   { tag: "td", counterpart: "<DataTable>" },
   { tag: "th", counterpart: "<DataTable>" },
   { tag: "form", counterpart: "<Form>" },
-  { tag: "input", counterpart: "<Input> (über <Field>)" },
+  { tag: "input", counterpart: "<Input> (via <Field>)" },
   { tag: "button", counterpart: "<Button>" },
   { tag: "select", counterpart: "<ComboboxInput>" },
   { tag: "textarea", counterpart: '<Input kind="textarea">' },
@@ -60,7 +60,7 @@ const FORBIDDEN_TAGS: ReadonlyArray<{
 const FORBIDDEN_CALLS: ReadonlyArray<{
   readonly call: string;
   readonly counterpart: string;
-}> = [{ call: "alert", counterpart: "<DefaultDialog> aus @cosmicdrift/kumiko-renderer-web" }];
+}> = [{ call: "alert", counterpart: "<DefaultDialog> from @cosmicdrift/kumiko-renderer-web" }];
 
 // Forbidden className tokens: an allowed tag (`<div>`), but the class gives
 // away hand-rolled primitive chrome. `bg-card` is the dedicated card-surface
@@ -263,7 +263,7 @@ function violationMessage(v: Violation): string {
 }
 
 const HINT =
-  "Migration: usePrimitives() in eine Custom-Screen-Komponente, oder schema-driven via EntityListScreenDefinition / EntityEditScreenDefinition wo möglich. Override pro Zeile: // kumiko-lint-ignore primitives-discipline <reason>";
+  "Migration: usePrimitives() in a custom screen component, or schema-driven via EntityListScreenDefinition / EntityEditScreenDefinition where possible. Per-line override: // kumiko-lint-ignore primitives-discipline <reason>";
 
 export const check: RepoCheck = {
   name: "Primitives-Discipline Guard",

package/src/guard-raw-classname.ts

@@ -84,8 +84,8 @@ export const guard: AstGuard = {
   name: "Raw-ClassName Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Design-tragende Klassen gehören in Widgets/Theme-Tokens (@cosmicdrift/kumiko-renderer-web widgets/, --color-status-*). " +
-    `Begründete Ausnahme: // ${IGNORE_TAG} <Grund>`,
+    "Design-bearing classes belong in widgets/theme tokens (@cosmicdrift/kumiko-renderer-web widgets/, --color-status-*). " +
+    `Justified exception: // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -99,7 +99,7 @@ export const guard: AstGuard = {
           violations.push({
             file: sf.getFilePath(),
             line: part.line,
-            message: `design-tragende Tailwind-Klassen in App-Code: ${bad.join(", ")}`,
+            message: `design-bearing Tailwind classes in app code: ${bad.join(", ")}`,
           });
         }
       }

package/src/guard-raw-interactive-elements.ts

@@ -104,7 +104,7 @@ const BASELINE_FILE = ".kumiko-raw-interactive-elements-baseline.json";
 const rawInteractiveElementsBaseline = baselineRatchet({
   file: path.join(ROOT, BASELINE_FILE),
   formatVersion: 1,
-  unit: "Fund(e) rohes interaktives HTML",
+  unit: "raw interactive HTML finding(s)",
 });
 
 const REMEDIATION =
@@ -114,14 +114,14 @@ const REMEDIATION =
 function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
   const findings = scan(files);
   if (!compareBaseline) {
-    console.log("  Baseline-Vergleich uebersprungen (--no-baseline).");
+    console.log("  Baseline comparison skipped (--no-baseline).");
     return { violations: [] };
   }
   const resolveLine = (file: string): number => findings.find((f) => f.file === file)?.line ?? 1;
   return {
     violations: rawInteractiveElementsBaseline.check(baselineCounts(findings), REMEDIATION, {
       formatDriftRemediation:
-        "Einmalig `bun guards/guard-raw-interactive-elements.ts --write-baseline` aufrufen.",
+        "Run `bun guards/guard-raw-interactive-elements.ts --write-baseline` once.",
       resolveLine,
     }),
   };

package/src/guard-raw-sql.ts

@@ -62,8 +62,8 @@ export async function collectRawSqlFindings(
 export const check: RepoCheck = {
   name: "guard-raw-sql",
   hint:
-    "Regel: Runtime-SQL nur in db/queries/*, bun-db/query.ts, testing/*, oder mit " +
-    "// kumiko-lint-ignore raw-sql <Grund> auf der Zeile bzw. der Zeile davor.",
+    "Rule: runtime SQL only in db/queries/*, bun-db/query.ts, testing/*, or with " +
+    "// kumiko-lint-ignore raw-sql <reason> on the line or the line above.",
   async run(roots) {
     // kumiko-platform's deliberate empty scan-dir list must not read as vacuous (infra#610).
     const applicableRoots = roots.filter((r) => sqlScanLayoutFor(r) !== "none");

package/src/guard-renderer-boundaries.ts

@@ -128,7 +128,7 @@ export function findViolations(file: string, root: string): Violation[] {
 
 export const check: RepoCheck = {
   name: "Renderer-Boundaries Guard",
-  hint: "@cosmicdrift/kumiko-renderer darf keine DOM-/Browser-/Platform-APIs nutzen. Platform-spezifischer Code gehört nach @cosmicdrift/kumiko-renderer-web (oder renderer-native).",
+  hint: "@cosmicdrift/kumiko-renderer must not use DOM/browser/platform APIs. Platform-specific code belongs in @cosmicdrift/kumiko-renderer-web (or renderer-native).",
   run(roots) {
     const frameworkRoots = roots.filter((r) => r.kind === "framework");
     const scanDirs = frameworkRoots

package/src/guard-restricted-symbols.ts

@@ -112,7 +112,7 @@ function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
-  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} sind ein Existenz-Orakel für fremde Tenants — nur Seed-/System-interner Code darf sie referenzieren. Neuer Caller nötig? Allowlist in guard-restricted-symbols.ts erweitern, mit Begründung. Bekannte Lücke: `export * from "...event-store"` wird nicht erkannt (Named-Imports, Re-Exports und Namespace-Property-Access sind abgedeckt).',
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
     const roots = resolveRepoRoots();

package/src/guard-screen-conventions.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+// Usability mistakes in screen definitions that are statically decidable and
+// otherwise come back screen by screen: a metric without a label, a
+// relatedList section whose rows lead nowhere, a row action labelled "edit"
+// that does something else. Opt-in per app repo via _app-test.yml.
+
+import { type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore screen-conventions";
+
+const SCREEN_TYPE_SUFFIX = "ScreenDefinition";
+
+// Anchor: only object literals that are unambiguously a screen definition —
+// either a `const x: XScreenDefinition = {...}` (the house convention, see
+// solon's screens.ts) or an inline literal passed straight to `r.screen(...)`.
+// Everything else (unrelated object literals with a coincidental `kind`/
+// `metrics` property) is deliberately left unchecked — a missed spot beats a
+// false positive here.
+function findScreenObjectLiterals(sf: SourceFile): ObjectLiteralExpression[] {
+  const roots: ObjectLiteralExpression[] = [];
+  for (const decl of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+    const typeNode = decl.getTypeNode();
+    if (!typeNode?.getText().endsWith(SCREEN_TYPE_SUFFIX)) continue;
+    const init = decl.getInitializer();
+    if (init?.isKind(SyntaxKind.ObjectLiteralExpression)) roots.push(init);
+  }
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const expr = call.getExpression();
+    if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
+    if (expr.getName() !== "screen") continue;
+    const arg = call.getArguments()[0];
+    if (arg?.isKind(SyntaxKind.ObjectLiteralExpression)) roots.push(arg);
+  }
+  return roots;
+}
+
+function stringLiteralValue(obj: ObjectLiteralExpression, name: string): string | undefined {
+  const prop = obj.getProperty(name);
+  if (!prop?.isKind(SyntaxKind.PropertyAssignment)) return undefined;
+  const init = prop.getInitializer();
+  return init?.isKind(SyntaxKind.StringLiteral) ? init.getLiteralValue() : undefined;
+}
+
+function hasDeclaredProperty(obj: ObjectLiteralExpression, name: string): boolean {
+  const prop = obj.getProperty(name);
+  if (!prop?.isKind(SyntaxKind.PropertyAssignment)) return false;
+  const init = prop.getInitializer();
+  return init !== undefined && init.getKind() !== SyntaxKind.UndefinedKeyword;
+}
+
+// R1: MetricSpec's plain-string shorthand carries no label — every metrics
+// entry on a projectionDetail screen must be the object form with `label`.
+function checkMetrics(
+  root: ObjectLiteralExpression,
+  sf: SourceFile,
+  violations: GuardViolation[],
+): void {
+  const metricsProp = root.getProperty("metrics");
+  if (!metricsProp?.isKind(SyntaxKind.PropertyAssignment)) return;
+  const init = metricsProp.getInitializer();
+  if (!init?.isKind(SyntaxKind.ArrayLiteralExpression)) return;
+  for (const el of init.getElements()) {
+    if (hasIgnoreTag(el, IGNORE_TAG)) continue;
+    if (el.isKind(SyntaxKind.StringLiteral)) {
+      violations.push({
+        file: sf.getFilePath(),
+        line: el.getStartLineNumber(),
+        message: `metrics entry "${el.getLiteralValue()}" is a plain string (a number with no meaning) — use the object form with \`label\`.`,
+      });
+      continue;
+    }
+    if (el.isKind(SyntaxKind.ObjectLiteralExpression) && !hasDeclaredProperty(el, "label")) {
+      violations.push({
+        file: sf.getFilePath(),
+        line: el.getStartLineNumber(),
+        message:
+          "metrics entry without `label` (a number with no meaning) — the object form needs a label.",
+      });
+    }
+  }
+}
+
+// R2: a relatedList section with neither rowClick nor rowActions renders a
+// list nobody can act on.
+function checkRelatedListSections(
+  root: ObjectLiteralExpression,
+  sf: SourceFile,
+  violations: GuardViolation[],
+): void {
+  for (const obj of root.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+    if (stringLiteralValue(obj, "kind") !== "relatedList") continue;
+    if (hasIgnoreTag(obj, IGNORE_TAG)) continue;
+    if (hasDeclaredProperty(obj, "rowClick") || hasDeclaredProperty(obj, "rowActions")) continue;
+    violations.push({
+      file: sf.getFilePath(),
+      line: obj.getStartLineNumber(),
+      message: "relatedList section without `rowClick`/`rowActions` — the row leads nowhere.",
+    });
+  }
+}
+
+// R3: a rowAction whose id isn't "edit" but whose label resolves to an
+// ".action.edit" i18n key promises "Bearbeiten" while doing something else.
+function checkRowActions(
+  root: ObjectLiteralExpression,
+  sf: SourceFile,
+  violations: GuardViolation[],
+): void {
+  for (const prop of root.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+    const name = prop.getName();
+    if (name !== "rowActions" && name !== "actions") continue;
+    const init = prop.getInitializer();
+    if (!init?.isKind(SyntaxKind.ArrayLiteralExpression)) continue;
+    for (const el of init.getElements()) {
+      if (!el.isKind(SyntaxKind.ObjectLiteralExpression)) continue;
+      if (hasIgnoreTag(el, IGNORE_TAG)) continue;
+      const id = stringLiteralValue(el, "id");
+      const label = stringLiteralValue(el, "label");
+      if (id === undefined || label === undefined) continue;
+      if (id !== "edit" && label.endsWith(".action.edit")) {
+        violations.push({
+          file: sf.getFilePath(),
+          line: el.getStartLineNumber(),
+          message: `rowAction "${id}" has label "${label}" (sounds like edit), but id is not "edit" — label/action mismatch.`,
+        });
+      }
+    }
+  }
+}
+
+export const guard: AstGuard = {
+  name: "Screen-Conventions Guard",
+  scan: SCAN,
+  hint:
+    "metrics entries need the object form with `label`; relatedList sections need " +
+    '`rowClick` or `rowActions`; a rowAction label must not end in ".action.edit" ' +
+    'when the `id` is not "edit". ' +
+    `Justified exception: // ${IGNORE_TAG} <reason>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const root of findScreenObjectLiterals(sf)) {
+        checkMetrics(root, sf, violations);
+        checkRelatedListSections(root, sf, violations);
+        checkRowActions(root, sf, violations);
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-silent-skip.ts

@@ -158,7 +158,7 @@ function hasLeadingSkipComment(site: SkipSite): boolean {
 export const guard: AstGuard = {
   name: "Silent-Skip Guard",
   scan: SCAN,
-  hint: "Nacktes `return;` braucht davor: Log-Call, `// skip: <grund>`-Kommentar, oder vorangehenden throw.",
+  hint: "A bare `return;` needs one of these before it: a log call, a `// skip: <reason>` comment, or a preceding throw.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];