@cosmicdrift/kumiko-guards 0.1.1 → 0.3.0

package/src/guard-i18n-locale-mount.ts

@@ -0,0 +1,317 @@
+#!/usr/bin/env bun
+/**
+ * Guard: App-Mount-Punkte muessen das deutsche Locale-Feature registrieren,
+ * wenn das Repo von @cosmicdrift/kumiko-locale-de abhaengt.
+ *
+ * guard-i18n-keys.ts prueft nur, ob ein verwendeter t()-Key definiert ist —
+ * und kennt kein Konzept von "Mount-Punkt". Ein Mount, der localeDeClient()
+ * (Client) bzw. localeDe() (Server) nie aufruft, faellt dort komplett durch
+ * (kumiko-studio#191, publicstatus#365, infra#533).
+ *
+ * Scope-Gate: das package.json am naechsten zur Datei muss auf
+ * kumiko-locale-de zeigen (aktuell kumiko-studio, publicstatus, solon,
+ * offlot-app) — ein Node-Resolution-Walk ueber ts-morphs FileSystemHost statt guards/_lib/
+ * roots.ts' Sibling-Repo-Liste, damit der Gate auch im In-Memory-Test der
+ * Guard-Suite (kein echter Sibling-Checkout) feuert.
+ *
+ * Usage:
+ *   bun guards/guard-i18n-locale-mount.ts
+ */
+
+import { dirname, join, relative as pathRelative } from "node:path";
+import {
+  type FileSystemHost,
+  type Identifier,
+  type Node,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+import {
+  type AstGuard,
+  type GuardViolation,
+  isLocalFinding,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+const LOCALE_DE_DEP = "@cosmicdrift/kumiko-locale-de";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  kinds: ["library", "app"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+
+const MOUNT_FACTORY_NAMES = new Set(["createKumikoApp", "createPublicSurface"]);
+
+export function nearestPackageJson(fs: FileSystemHost, fromDir: string): string | undefined {
+  let dir = fromDir;
+  for (let i = 0; i < 40; i++) {
+    const candidate = join(dir, "package.json");
+    if (fs.fileExistsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+export function hasLocaleDeDependency(fs: FileSystemHost, pkgPath: string): boolean {
+  let pkg: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return false;
+  }
+  return LOCALE_DE_DEP in (pkg.dependencies ?? {}) || LOCALE_DE_DEP in (pkg.devDependencies ?? {});
+}
+
+type Gate = { readonly pkgPath: string; readonly gated: boolean };
+
+function gateFor(sf: SourceFile, cache: Map<string, Gate>): Gate | undefined {
+  const fs = sf.getProject().getFileSystem();
+  const pkgPath = nearestPackageJson(fs, dirname(sf.getFilePath()));
+  if (pkgPath === undefined) return undefined;
+  const cached = cache.get(pkgPath);
+  if (cached !== undefined) return cached;
+  const gate: Gate = { pkgPath, gated: hasLocaleDeDependency(fs, pkgPath) };
+  cache.set(pkgPath, gate);
+  return gate;
+}
+
+// localeDeClient() (clientFeatures) matcht per Call-Text; `{ de: ... }` deckt
+// die rohe <LocaleProvider fallbackBundles={[{ de: bundle }, ...]}>-Komposition
+// ab, die keinen localeDeClient()-Call verwendet.
+function localeDeClientRef(node: Node): boolean {
+  if (node.isKind(SyntaxKind.Identifier) && node.getText() === "localeDeClient") return true;
+  if (node.isKind(SyntaxKind.CallExpression)) return localeDeClientRef(node.getExpression());
+  if (node.isKind(SyntaxKind.PropertyAccessExpression))
+    return localeDeClientRef(node.getExpression());
+  return false;
+}
+
+// Go-to-definition resolves an import binding all the way to its real
+// VariableDeclaration in one hop — except a ShorthandPropertyAssignment's name
+// node, which resolves only to the ImportSpecifier and needs a second hop
+// through the specifier's own name to get there.
+function resolveDeclaration(identifier: Identifier, depth = 0): Node | undefined {
+  if (depth > 3) return undefined;
+  const def = identifier.getDefinitionNodes()[0];
+  if (def === undefined) return undefined;
+  if (def.isKind(SyntaxKind.VariableDeclaration)) return def;
+  if (def.isKind(SyntaxKind.ImportSpecifier)) {
+    const specName = def.getNameNode();
+    return specName.isKind(SyntaxKind.Identifier)
+      ? resolveDeclaration(specName, depth + 1)
+      : undefined;
+  }
+  return undefined;
+}
+
+// `as const` and `as const satisfies T[]` (both in active use, e.g.
+// kumiko-studio's run-config.ts) wrap the array literal in an AsExpression
+// and/or SatisfiesExpression — unwrap either so callers see the literal underneath.
+function unwrapAsExpression(node: Node): Node {
+  if (node.isKind(SyntaxKind.AsExpression) || node.isKind(SyntaxKind.SatisfiesExpression)) {
+    return unwrapAsExpression(node.getExpression());
+  }
+  return node;
+}
+
+// Scoped to the mount's own repo: in the shared multi-repo ts-morph Project
+// the aggregate runner builds, a resolved declaration is only trusted when it
+// lives under the same package.json root as the spreading/referencing file —
+// never a same-named declaration from a different repo. Shared by array
+// (`[...CONST]`) and object (`{ ...CONST }`) spread resolution alike.
+function resolveSameRepoInitializer(identifier: Identifier): Node | undefined {
+  const decl = resolveDeclaration(identifier);
+  if (decl === undefined || !decl.isKind(SyntaxKind.VariableDeclaration)) return undefined;
+  const fs = identifier.getSourceFile().getProject().getFileSystem();
+  const originPkg = nearestPackageJson(fs, dirname(identifier.getSourceFile().getFilePath()));
+  const targetPkg = nearestPackageJson(fs, dirname(decl.getSourceFile().getFilePath()));
+  if (originPkg === undefined || originPkg !== targetPkg) return undefined;
+  const init = decl.getInitializer();
+  return init === undefined ? undefined : unwrapAsExpression(init);
+}
+
+// Resolves an array-shaped value node down to its elements, whether it's a
+// literal right there or an identifier pointing at a same-repo constant
+// (`const CONST = [...]`, `... as const` included).
+function arrayElementsOf(value: Node | undefined): Node[] | undefined {
+  if (value === undefined) return undefined;
+  if (value.isKind(SyntaxKind.ArrayLiteralExpression)) return value.getElements();
+  if (value.isKind(SyntaxKind.Identifier)) {
+    return arrayElementsOf(resolveSameRepoInitializer(value));
+  }
+  return undefined;
+}
+
+function elementRegistersGerman(el: Node): boolean {
+  if (el.isKind(SyntaxKind.SpreadElement)) {
+    const expr = el.getExpression();
+    if (expr.isKind(SyntaxKind.Identifier)) {
+      const init = resolveSameRepoInitializer(expr);
+      if (init !== undefined) return elementRegistersGerman(init);
+      // Unresolvable or cross-repo identifier spread — fail-open rather than risk a false alarm.
+      // Safe here: clientFeatures is already known to exist as an array, this only concerns
+      // one of its elements — other elements are still checked.
+      return true;
+    }
+    return elementRegistersGerman(expr);
+  }
+  if (el.isKind(SyntaxKind.ArrayLiteralExpression)) {
+    return el.getElements().some(elementRegistersGerman);
+  }
+  // localeDeClient().translations (kumiko-studio auth-mount shape)
+  if (el.isKind(SyntaxKind.PropertyAccessExpression)) {
+    return localeDeClientRef(el) || elementRegistersGerman(el.getExpression());
+  }
+  if (el.isKind(SyntaxKind.CallExpression)) {
+    return localeDeClientRef(el.getExpression());
+  }
+  if (el.isKind(SyntaxKind.ObjectLiteralExpression)) {
+    return el
+      .getProperties()
+      .some((p) => p.isKind(SyntaxKind.PropertyAssignment) && p.getNameNode().getText() === "de");
+  }
+  return false;
+}
+
+function jsxTagNameOf(attr: Node): string | undefined {
+  const el = attr.getParent()?.getParent();
+  if (el?.isKind(SyntaxKind.JsxOpeningElement)) return el.getTagNameNode().getText();
+  if (el?.isKind(SyntaxKind.JsxSelfClosingElement)) return el.getTagNameNode().getText();
+  return undefined;
+}
+
+// `clientFeatures: [...]`, `clientFeatures,` (shorthand) and `clientFeatures: clientFeatures`
+// all reference the same array — resolve the value node down to its elements either way.
+function clientFeaturesElements(prop: Node | undefined): Node[] | undefined {
+  const value = prop?.isKind(SyntaxKind.PropertyAssignment)
+    ? prop.getInitializer()
+    : prop?.isKind(SyntaxKind.ShorthandPropertyAssignment)
+      ? prop.getNameNode()
+      : undefined;
+  return arrayElementsOf(value);
+}
+
+const MAX_OPTIONS_SPREAD_DEPTH = 5;
+
+// Determines whether the mount call's options object — a literal right there,
+// or an identifier pointing at a same-repo constant (offlot's `APP_OPTIONS`
+// shape) — carries a `clientFeatures` property that registers German. Follows
+// `{ ...OTHER_OPTIONS, clientFeatures: [...] }` object spreads the same way
+// arrayElementsOf follows array spreads, so `clientFeatures` no longer has to
+// stay a literal at the call site to satisfy this guard (infra#734).
+//
+// Fail-closed (not fail-open) on an unresolvable/cross-repo spread source:
+// unlike a single array element, a whole unresolved options object could be
+// the only place `clientFeatures` lives — silently passing it would make the
+// guard blind again, exactly the risk infra#734 called out.
+function objectRegistersGermanClientFeatures(value: Node | undefined, depth = 0): boolean {
+  if (value === undefined || depth > MAX_OPTIONS_SPREAD_DEPTH) return false;
+  if (value.isKind(SyntaxKind.Identifier)) {
+    return objectRegistersGermanClientFeatures(resolveSameRepoInitializer(value), depth + 1);
+  }
+  if (!value.isKind(SyntaxKind.ObjectLiteralExpression)) return false;
+  const direct = value
+    .getProperties()
+    .find(
+      (p) =>
+        (p.isKind(SyntaxKind.PropertyAssignment) ||
+          p.isKind(SyntaxKind.ShorthandPropertyAssignment)) &&
+        p.getNameNode().getText() === "clientFeatures",
+    );
+  if (direct !== undefined)
+    return clientFeaturesElements(direct)?.some(elementRegistersGerman) ?? false;
+  return value
+    .getProperties()
+    .some(
+      (p) =>
+        p.isKind(SyntaxKind.SpreadAssignment) &&
+        objectRegistersGermanClientFeatures(p.getExpression(), depth + 1),
+    );
+}
+
+function clientMountViolations(sf: SourceFile): GuardViolation[] {
+  const violations: GuardViolation[] = [];
+
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (!MOUNT_FACTORY_NAMES.has(call.getExpression().getText())) continue;
+    const arg = call.getArguments()[0];
+    const registered = objectRegistersGermanClientFeatures(arg);
+    if (!registered) {
+      violations.push({
+        file: sf.getFilePath(),
+        line: call.getStartLineNumber(),
+        message: `Mount point "${call.getExpression().getText()}(...)" does not register a German locale feature (localeDeClient() missing in clientFeatures) — repo depends on ${LOCALE_DE_DEP}.`,
+      });
+    }
+  }
+
+  for (const attr of sf.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+    if (attr.getNameNode().getText() !== "fallbackBundles") continue;
+    if (jsxTagNameOf(attr) !== "LocaleProvider") continue;
+    const init = attr.getInitializer();
+    const expr = init?.isKind(SyntaxKind.JsxExpression) ? init.getExpression() : undefined;
+    const elements = arrayElementsOf(expr);
+    const registered = elements?.some(elementRegistersGerman) ?? false;
+    if (!registered) {
+      violations.push({
+        file: sf.getFilePath(),
+        line: attr.getStartLineNumber(),
+        message: `<LocaleProvider fallbackBundles={...}> does not register a German locale bundle ({ de: ... }) — repo depends on ${LOCALE_DE_DEP}.`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+function hasServerLocaleCall(sf: SourceFile): boolean {
+  return sf
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .some((c) => c.getExpression().getText() === "localeDe");
+}
+
+export function findViolations(files: readonly SourceFile[]): GuardViolation[] {
+  const relevant = files.filter((sf) => !EXCLUDE.test(sf.getFilePath()));
+  const cache = new Map<string, Gate>();
+  const serverCallSeen = new Set<string>();
+
+  const violations: GuardViolation[] = [];
+  for (const sf of relevant) {
+    const gate = gateFor(sf, cache);
+    if (gate === undefined || !gate.gated) continue;
+    violations.push(...clientMountViolations(sf));
+    if (hasServerLocaleCall(sf)) serverCallSeen.add(gate.pkgPath);
+  }
+
+  const gatedPkgPaths = new Set([...cache.values()].filter((g) => g.gated).map((g) => g.pkgPath));
+  for (const pkgPath of gatedPkgPaths) {
+    if (serverCallSeen.has(pkgPath)) continue;
+    violations.push({
+      file: pkgPath,
+      line: 1,
+      message: `Repo depends on ${LOCALE_DE_DEP}, but no server-side localeDe() call was found — German mail templates (registerMailTranslations) are not registered.`,
+    });
+  }
+
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "i18n-Locale-Mount Guard",
+  scan: SCAN,
+  hint: "Mount point (createKumikoApp/createPublicSurface/LocaleProvider) without a German locale feature — add localeDeClient() to clientFeatures, or localeDe() to the server feature list.",
+  run(files) {
+    const violations = findViolations(files)
+      .map((v) => ({ ...v, file: pathRelative(ROOT, v.file) }))
+      .filter(isLocalFinding);
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-i18n-locale-terminology.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+/**
+ * Guard: locale bundle values must follow Mandant/Organización terminology (#2200, fw#2355).
+ *
+ * German UI copy always says "Mandant" (never "Tenant"/"Organisation"); Spanish always
+ * says "Organización" (never the "tenant" loanword). Only translation *values* are
+ * checked — JSON key names like `tenant.members.*` are ignored. Role identifiers
+ * such as TenantAdmin/SystemAdmin in prose are allowed.
+ *
+ * Usage:
+ *   bun guards/guard-i18n-locale-terminology.ts
+ *
+ * Ignore: // kumiko-lint-ignore i18n-locale-terminology
+ */
+
+import { relative as pathRelative } from "node:path";
+import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  type GuardViolation,
+  isLocalFinding,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  kinds: ["framework"],
+  frameworkWithin: ["packages/locale-de/src/strings.ts", "packages/locale-es/src/strings.ts"],
+};
+const IGNORE_TAG = "kumiko-lint-ignore i18n-locale-terminology";
+
+type LocaleRule = {
+  readonly preferred: string;
+  readonly forbidden: readonly RegExp[];
+};
+
+const RULES: Record<"de" | "es", LocaleRule> = {
+  de: {
+    preferred: "Mandant",
+    // Tenants? covers plural; Organisation(en|s)? without trailing \b so
+    // compounds like Organisations-ID / Organisationsstruktur still match
+    // (infra#603). TenantAdmin stays safe: \b after Tenant fails on 'A'.
+    forbidden: [/\bTenants?\b/i, /\bOrganisation(en|s)?/],
+  },
+  es: {
+    preferred: "Organización",
+    forbidden: [/\btenants?\b/i],
+  },
+};
+
+function localeFromPath(filePath: string): "de" | "es" | undefined {
+  if (filePath.includes("locale-de/src/strings.ts")) return "de";
+  if (filePath.includes("locale-es/src/strings.ts")) return "es";
+  return undefined;
+}
+
+function stringLiteralText(node: Node): string | undefined {
+  if (node.isKind(SyntaxKind.StringLiteral)) return node.getLiteralText();
+  if (node.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) return node.getLiteralValue();
+  return undefined;
+}
+
+function forbiddenTerm(text: string, rule: LocaleRule): string | undefined {
+  for (const re of rule.forbidden) {
+    const match = text.match(re);
+    if (match !== null) return match[0];
+  }
+  return undefined;
+}
+
+export function findViolations(files: readonly SourceFile[]): GuardViolation[] {
+  const violations: GuardViolation[] = [];
+
+  for (const sf of files) {
+    const locale = localeFromPath(sf.getFilePath());
+    if (locale === undefined) continue;
+    const rule = RULES[locale];
+
+    for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+      if (hasIgnoreTag(prop, IGNORE_TAG)) continue;
+      const init = prop.getInitializer();
+      if (init === undefined) continue;
+      const text = stringLiteralText(init);
+      if (text === undefined) continue;
+
+      const hit = forbiddenTerm(text, rule);
+      if (hit !== undefined) {
+        violations.push({
+          file: sf.getFilePath(),
+          line: prop.getStartLineNumber(),
+          message: `[${locale}] verbotener Begriff "${hit}" in Übersetzungswert — nutze "${rule.preferred}" (fw#2200).`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "i18n-Locale-Terminology Guard",
+  scan: SCAN,
+  hint: "DE: Mandant statt Tenant/Organisation; ES: Organización statt tenant-Loanword. Rollen wie TenantAdmin sind OK.",
+  run(files) {
+    const violations = findViolations(files)
+      .map((v) => ({ ...v, file: pathRelative(ROOT, v.file) }))
+      .filter(isLocalFinding);
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-i18n-ui-strings.ts

@@ -0,0 +1,248 @@
+#!/usr/bin/env bun
+// Kein hardcodeter UI-Text in App-Web-Code: JSX-Textknoten und Label-artige
+// String-Props müssen über t("…")-Keys laufen (guard-i18n-keys prüft dann,
+// dass die Keys definiert sind — dieser Guard schließt die Lücke davor:
+// Strings, die nie zu Keys wurden, z.B. "Lade Tenants…").
+//
+// Teil von App-Mounting 2.0 (infra#208).
+
+import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+// Nur Web-/Public-Code — Server-Code (Handler-Fehlertexte) läuft über die
+// Error-i18n-Pipeline und hat eigene Guards.
+//
+// samples/ deliberately NOT scanned (tried in infra#478, rolled back): the
+// showcase/gallery pages are dev docs about the framework API itself
+// ("Form.title / toolbarTitle", "children — auto from schema.navs"), not
+// app UI text a real user sees. 354 hits in the trial run, almost all such
+// API annotations. guard-i18n-keys covers samples/ (t() calls +
+// r.translations definitions); this guard stays scoped to app repos.
+//
+// src/features/**/feature.ts covers feature.ts registrar calls (r.nav/r.screen
+// object-literal arguments) — infra#504: those sit outside JSX and were a
+// blind spot. Other server code (handlers/, lib/) has its own i18n pipeline
+// and is filtered out below by requiring an r.*-call ancestor.
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  within: [
+    "**/web/**/*.tsx",
+    "public/**/*.tsx",
+    "features/**/feature.ts",
+    "features/**/register/**/*.ts",
+  ],
+  frameworkWithin: ["packages/bundled-features/src/**"],
+};
+const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
+const IGNORE_TAG = "kumiko-lint-ignore i18n-ui-strings";
+
+// Mindestens zwei Buchstaben in Folge = menschenlesbarer Text (lässt "—",
+// Zahlen, Interpunktion und Einzel-Zeichen durch).
+const HUMAN_TEXT = /\p{L}{2,}/u;
+
+// i18n-Key-Shape (e.g. "tenant.nav.members", "money-horse:nav.scenarioCompare"):
+// alphanumeric/dash segments (camelCase allowed) joined by "." or ":", at
+// least one separator — real keys have no spaces and no bare single word.
+// r.nav/r.screen label props are keys, not raw text, unlike JSX props.
+const I18N_KEY_SHAPE =
+  /^[a-zA-Z0-9_]+(?:-[a-zA-Z0-9_]+)*(?:[:.][a-zA-Z0-9_]+(?:-[a-zA-Z0-9_]+)*)+$/;
+
+const LABEL_PROPS = new Set([
+  "label",
+  "title",
+  "subtitle",
+  "placeholder",
+  "description",
+  "confirm",
+  "confirmLabel",
+  "emptyLabel",
+  "ariaLabel",
+  "aria-label",
+  "startLabel",
+  "endLabel",
+]);
+
+// projectionDetail screens: `header: { title, subtitle, status }` names
+// columns from the query row (RecordHeaderSpec, packages/types/src/screen.ts),
+// not UI text — analogous to `metrics: [...]`, which stays out of LABEL_PROPS
+// for the same reason. Only exempt when directly nested under a `header:`
+// property so a section/column `title` elsewhere stays flagged.
+const HEADER_SPEC_PROPS = new Set(["title", "subtitle", "status"]);
+
+const REGISTRAR_CALL = /^r\.[a-zA-Z]+$/;
+
+const LOGICAL_OPERATORS = new Set([SyntaxKind.AmpersandAmpersandToken, SyntaxKind.BarBarToken]);
+
+function isTernaryOrLogical(node: Node): boolean {
+  if (node.isKind(SyntaxKind.ConditionalExpression)) return true;
+  return (
+    node.isKind(SyntaxKind.BinaryExpression) &&
+    LOGICAL_OPERATORS.has(node.getOperatorToken().getKind())
+  );
+}
+
+type TextPiece = { readonly text: string; readonly node: Node };
+
+// Leaf strings a ternary/logical branch can bottom out on: a plain string, or
+// a template literal's static spans (interpolated `${…}` values are skipped —
+// only the literal text around them is human-authored copy, e.g. "Apply " /
+// " change(s)" in `Apply ${n} change(s)`).
+function textPieces(node: Node): TextPiece[] {
+  if (
+    node.isKind(SyntaxKind.StringLiteral) ||
+    node.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+  ) {
+    return [{ text: node.getLiteralText(), node }];
+  }
+  if (node.isKind(SyntaxKind.TemplateExpression)) {
+    const pieces: TextPiece[] = [{ text: node.getHead().getLiteralText(), node }];
+    for (const span of node.getTemplateSpans()) {
+      pieces.push({
+        text: span.getLiteral().getLiteralText(),
+        node: span.getLiteral(),
+      });
+    }
+    return pieces;
+  }
+  return [];
+}
+
+// Only descends through ternary/logical branches — a literal reached through
+// any other expression (function call, member access, …) is out of scope, so
+// e.g. `formatLabel("Save")` inside a ternary branch is not flattened into it.
+function collectTernaryLogicText(node: Node): TextPiece[] {
+  if (node.isKind(SyntaxKind.ConditionalExpression)) {
+    return [
+      ...collectTernaryLogicText(node.getWhenTrue()),
+      ...collectTernaryLogicText(node.getWhenFalse()),
+    ];
+  }
+  if (
+    node.isKind(SyntaxKind.BinaryExpression) &&
+    LOGICAL_OPERATORS.has(node.getOperatorToken().getKind())
+  ) {
+    return [
+      ...collectTernaryLogicText(node.getLeft()),
+      ...collectTernaryLogicText(node.getRight()),
+    ];
+  }
+  return textPieces(node);
+}
+
+// infra#711: a hop out of a helper is only taken while that helper call is
+// itself an argument of the next call — a call nested deeper (inside an object
+// or array, e.g. `createTextField({ label })` under `createEntity({ fields })`)
+// builds a value instead of forwarding the registrar's argument. The full chain
+// comes back so the line-anchored ignore tag also works above the helper.
+function registrarCallChain(prop: Node): CallExpression[] | undefined {
+  const chain: CallExpression[] = [];
+  let call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
+  while (call !== undefined) {
+    chain.push(call);
+    if (REGISTRAR_CALL.test(call.getExpression().getText())) return chain;
+    call = call.getParentIfKind(SyntaxKind.CallExpression);
+  }
+  return undefined;
+}
+
+export const guard: AstGuard = {
+  name: "i18n-UI-Strings Guard (App-Repos)",
+  scan: SCAN,
+  hint:
+    'UI text belongs in i18n bundles + t("feature:key") — not as a literal in JSX. ' +
+    `Justified exception (e.g. proper noun/brand): // ${IGNORE_TAG} <reason>`,
+  run(files: readonly SourceFile[]) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      for (const textNode of sf.getDescendantsOfKind(SyntaxKind.JsxText)) {
+        const text = textNode.getText().trim();
+        if (!HUMAN_TEXT.test(text)) continue;
+        if (hasIgnoreTag(textNode, IGNORE_TAG)) continue;
+        violations.push({
+          file: sf.getFilePath(),
+          line: textNode.getStartLineNumber(),
+          message: `hardcoded JSX text: "${text.slice(0, 40)}${text.length > 40 ? "…" : ""}"`,
+        });
+      }
+      for (const attr of sf.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+        if (!LABEL_PROPS.has(attr.getNameNode().getText())) continue;
+        const init = attr.getInitializer();
+        if (init === undefined || init.getKind() !== SyntaxKind.StringLiteral) continue;
+        const value = init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText();
+        if (!HUMAN_TEXT.test(value)) continue;
+        if (hasIgnoreTag(attr, IGNORE_TAG)) continue;
+        violations.push({
+          file: sf.getFilePath(),
+          line: attr.getStartLineNumber(),
+          message: `hardcoded label prop ${attr.getNameNode().getText()}="${value.slice(0, 40)}"`,
+        });
+      }
+      // Ternary/logical JSX expressions: `{saving ? "Saving…" : "Save"}` as a
+      // child, or `title={busy ? "…" : "Send"}` on a label prop — a string
+      // literal reachable only via getDescendantsOfKind(JsxText/JsxAttribute)
+      // above never fires here since the literal sits one level deeper,
+      // inside the {…} expression.
+      for (const jsxExpr of sf.getDescendantsOfKind(SyntaxKind.JsxExpression)) {
+        const inner = jsxExpr.getExpression();
+        if (inner === undefined || !isTernaryOrLogical(inner)) continue;
+        const attr = jsxExpr.getParentIfKind(SyntaxKind.JsxAttribute);
+        if (attr !== undefined && !LABEL_PROPS.has(attr.getNameNode().getText())) continue;
+        if (hasIgnoreTag(jsxExpr, IGNORE_TAG)) continue;
+        for (const piece of collectTernaryLogicText(inner)) {
+          if (!HUMAN_TEXT.test(piece.text)) continue;
+          const shown = `${piece.text.slice(0, 40)}${piece.text.length > 40 ? "…" : ""}`;
+          violations.push({
+            file: sf.getFilePath(),
+            line: piece.node.getStartLineNumber(),
+            message:
+              attr !== undefined
+                ? `hardcoded label prop ${attr.getNameNode().getText()} in ternary/logical expression: "${shown}"`
+                : `hardcoded JSX text in ternary/logical expression: "${shown}"`,
+          });
+        }
+      }
+      // r.nav({ label: "..." }) etc.: registrar param is conventionally
+      // named "r" across framework/bundled-features/app repos (verified,
+      // no exceptions found) — see the samples/ scan-boundary note above.
+      for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+        if (!LABEL_PROPS.has(prop.getName())) continue;
+        if (HEADER_SPEC_PROPS.has(prop.getName())) {
+          const enclosingObject = prop.getParentIfKind(SyntaxKind.ObjectLiteralExpression);
+          const enclosingProp = enclosingObject?.getParentIfKind(SyntaxKind.PropertyAssignment);
+          if (enclosingProp?.getName() === "header") continue;
+        }
+        const init = prop.getInitializer();
+        if (init === undefined || init.getKind() !== SyntaxKind.StringLiteral) continue;
+        const value = init.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralText();
+        if (!HUMAN_TEXT.test(value) || I18N_KEY_SHAPE.test(value)) continue;
+        const callChain = registrarCallChain(prop);
+        if (callChain === undefined) continue;
+        // The agent-doc slot (kumiko-framework#2615) is LLM metadata for the
+        // AI tool catalog: English by design, never rendered as UI text. The
+        // slot is the options object handed to a call on the registrar
+        // argument chain, so forwarding it through a `defineEntity*Handler`
+        // helper is the same slot and stays exempt.
+        if (
+          prop.getName() === "description" &&
+          prop
+            .getParentIfKind(SyntaxKind.ObjectLiteralExpression)
+            ?.getParentIfKind(SyntaxKind.CallExpression) !== undefined
+        )
+          continue;
+        if (callChain.some((c) => hasIgnoreTag(c, IGNORE_TAG)) || hasIgnoreTag(prop, IGNORE_TAG))
+          continue;
+        violations.push({
+          file: sf.getFilePath(),
+          line: prop.getStartLineNumber(),
+          message: `hardcoded label property ${prop.getName()}="${value.slice(0, 40)}" in r.* call — use an i18n key instead of plain text`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);