@ultimat3/cli 6.0.0 → 8.0.0

package/src/sync-authenticator.ts

@@ -4,7 +4,8 @@
 // per-tenant subscription cap all decided against an anonymous actor. Realtime was single-tenant
 // by wiring, not by design.
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -12,7 +13,37 @@ import {
   defineHttpConfig,
   UltimateRequest,
 } from '@ultimat3/http';
-import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime';
+import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime/server';
+
+/**
+ * How long one grant stands before the node re-decides it.
+ *
+ * A grant with no expiry never appears in `GrantBook.expired()`, so `sweepGrants` — the only path
+ * to `hub.onActorChange` and `registry.reauthorize` — never fired for a socket this adapter opened.
+ * `logout`, `revokeSession`, `disableUser` and `updatePrivileges` closed the HTTP session and never
+ * the websocket, and the client's 15s heartbeat beats the 120s idle sweep, so the socket stayed up
+ * with the revoked actor's authority for as long as the tab was open.
+ *
+ * Five minutes, against `DEFAULT_REAUTH_INTERVAL_MS` (30s): the window a revoked actor keeps its
+ * socket is this plus one sweep, and the cost is one resolver call per socket per window — 167/s
+ * on the 50,000-socket node this repo has measured, against 1,667/s at a 30s TTL. A deployment
+ * whose credential has a shorter real lifetime passes `runtime.syncAuthenticate` and states it.
+ */
+export const SYNC_GRANT_TTL_MS = 5 * 60_000;
+
+/**
+ * The credential this adapter retains per socket, and nothing else.
+ *
+ * `sync-auth.ts` says the seam is a closure precisely so a node does not hold one `Request` per
+ * connection for the life of that connection: `SyncSocket`'s budget is ~1KB and the grant sits
+ * beside it. Two header values is what an app that closes over a token string would hold.
+ *
+ * Dropping the rest can only make a refresh MORE restrictive, never more permissive: an app that
+ * resolves identity from some other header sees its refresh answer `null`, which closes the socket
+ * with `1008` and the client re-dials carrying that header again. One reconnect per window, not an
+ * escalation — and `runtime.syncAuthenticate` is the declared seam for stating something else.
+ */
+const CREDENTIAL_HEADERS = ['cookie', 'authorization'] as const;
 
 /**
  * The upgrade request, dressed as the request an `Authenticator` reads.
@@ -27,33 +58,74 @@ function upgradeConfig(buildId: string): HttpConfig {
   return defineHttpConfig({ buildId, rateLimit: { enabled: false, scope: 'process' } });
 }
 
+/** What the closure keeps: enough to ask the app's resolver the same question a second time. */
+interface Credential {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+}
+
+function credentialOf(request: Request): Credential {
+  const headers = new Headers();
+  for (const name of CREDENTIAL_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+  return { url: request.url, method: request.method, headers };
+}
+
+export interface SyncAuthenticatorOptions {
+  /** The clock a grant's window is measured on. Injected so a re-auth is provable without sleeping. */
+  readonly clock?: Clock;
+  /** Overrides `SYNC_GRANT_TTL_MS`. A test names its own window; nothing in the boot passes one. */
+  readonly ttlMs?: number;
+}
+
 /**
  * What the sync node is given when the app configured an authenticator, and `undefined` when it
  * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
  * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
  *
- * The grant carries **no `expiresAt` and no `refresh`**, and that is the honest limit of this
- * adapter rather than an omission: `configureAuthenticator()` resolves an `Actor` and says nothing
- * about how long it stays true, so inventing a window here would either close live sockets that
- * are still authorized or claim a lifetime the app never promised. A deployment whose credential
- * has a real expiry passes `runtime.syncAuthenticate` and gets re-authorization; the timer for it
- * already lives in `createSyncNode.start()`.
+ * The grant carries an `expiresAt` and a `refresh`, and both are the app's own resolver asked
+ * again: `configureAuthenticator` says who is dialling, and the only honest way to learn that it
+ * has stopped being true is to ask. A `null` second answer is a revocation the node turns into a
+ * `1008`; a THROW is a backend failure, and `sweepGrants` keeps the grant and retries — the
+ * adapter must not collapse those two, here or on the refresh path.
  */
-export function syncAuthenticator(buildId: string): SyncAuthenticator | undefined {
+export function syncAuthenticator(
+  buildId: string,
+  options: SyncAuthenticatorOptions = {},
+): SyncAuthenticator | undefined {
   const authenticate = configuredAuthenticator();
   if (authenticate === undefined) return undefined;
   // Once per node, not once per upgrade: resolving a config is pure and a 50k-socket node pays
   // this per connection otherwise.
   const config = upgradeConfig(buildId);
-  return async (request: Request): Promise<SyncGrant | null> => {
+  const clock = options.clock ?? systemClock;
+  const ttlMs = options.ttlMs ?? SYNC_GRANT_TTL_MS;
+
+  const resolve = async (credential: Credential): Promise<SyncGrant | null> => {
+    const request = new Request(credential.url, {
+      method: credential.method,
+      headers: credential.headers,
+    });
     const ctx = createRequestContext({
-      url: new URL(request.url),
-      method: request.method,
+      url: new URL(credential.url),
+      method: credential.method,
       role: 'sync',
       config,
-      requestHeaders: request.headers,
+      requestHeaders: credential.headers,
     });
     const actor: Actor | null = await authenticate(new UltimateRequest(request, ctx), ctx);
-    return actor === null ? null : { actor };
+    if (actor === null) return null;
+    return {
+      // The window is measured from the answer, not from the upgrade: a refreshed grant that
+      // returned its original instant would be expired again on the very next pass.
+      actor,
+      expiresAt: clock.now().getTime() + ttlMs,
+      refresh: () => resolve(credential),
+    };
   };
+
+  return async (request: Request): Promise<SyncGrant | null> => resolve(credentialOf(request));
 }

package/src/templates/guard-bare-error.ts

@@ -0,0 +1,122 @@
+// The `bare-error` guard `x new` ships: no shipped module throws a bare `Error`.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `throw new Error(...)` in a
+// scaffolded `repo.ts` was green on `x verify`, and it reaches an agent as a stack trace with no
+// code, no cause and nothing to run.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'bare-error';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// bare-error: a failure this app raises carries a code, a cause and an executable fix.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * A THROW, never a construction. \`new Error(…)\` handed to something as INPUT is legitimate — a
+ * test fixture, an \`AbortSignal\` reason, a rejection this module is passing along — and only the
+ * throw is this module stating its own verdict.
+ */
+const BARE_THROW = /\\bthrow\\s+new\\s+(Error|TypeError|RangeError|SyntaxError)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function bareThrows(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(BARE_THROW)) {
+      const line = lineOf(text, match.index);
+      const thrown = match[1] ?? 'Error';
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} throws a bare \${thrown} — it reaches its reader as a stack trace with no code, no cause and nothing to run\`,
+        fix: \`subclass UltimateError in \${file.path} with an X_SCREAMING_SNAKE code, a cause and a fix naming a command, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a failure carries a code, a cause and an executable fix — never a bare Error',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test states its verdict with \`expect.unreachable()\`, which the suite reports on its own
+      // terms; \`node_modules\` is not this app's source.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return bareThrows(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { bareThrows } from './bare-error';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/repo.ts', source }];
+
+unitTest('a bare throw is refused, and the finding names the line', () => {
+  const findings = bareThrows(file("const x = 1;\\nthrow new Error('no post');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('TypeError and RangeError are the same rule', () => {
+  expect(bareThrows(file("throw new TypeError('x');"))).toHaveLength(1);
+  expect(bareThrows(file("throw new RangeError('x');"))).toHaveLength(1);
+});
+
+unitTest('an UltimateError subclass is what the rule asks for', () => {
+  expect(bareThrows(file('throw new PostError(missingPost(id));'))).toEqual([]);
+});
+
+unitTest('a bare Error that is INPUT is not a verdict', () => {
+  expect(bareThrows(file("controller.abort(new Error('cancelled'));"))).toEqual([]);
+  expect(bareThrows(file("// throw new Error('x');"))).toEqual([]);
+});
+`;
+
+/** `guards/bare-error.ts` and its test. No index, no registry — the directory registers it. */
+export const bareErrorGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/bare-error.ts', contents: source() },
+  { path: 'guards/bare-error.test.ts', contents: test() },
+];

package/src/templates/guard-raw-colour.ts

@@ -0,0 +1,138 @@
+// The `raw-colour` guard `x new` ships: no stylesheet in this app names a colour.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `verify-checks.ts` said it rode
+// on `packages/ui/src/tokens/tokens.test.ts`, which covers the framework's stylesheets and never
+// the app's, so `color: #ff0000` in a scaffolded `page.module.scss` was green on `x verify`.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'raw-colour';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-colour: every colour in this app is a semantic token, so dark theme is not a later project.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to. Delete it to drop the rule.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/** A hex literal. \`#{$x}\` is Sass interpolation, not a colour, and \`{\` is not a hex digit. */
+const HEX = /#[0-9a-fA-F]{3,8}\\b/;
+const CHANNEL_FUNCTION = /\\b(?:rgba?|hsla?|lab|lch|oklab|oklch|color)\\(/i;
+/** The named colours a human actually types. The full CSS list would report \`.item\` selectors. */
+const NAMED =
+  /\\b(?:white|black|red|green|blue|yellow|orange|purple|pink|brown|gray|grey|silver|navy|teal|olive|lime|aqua|maroon|fuchsia|gold|beige|coral|crimson|indigo|violet|khaki|salmon|tan|turquoise|wheat)\\b/i;
+
+/**
+ * A DECLARATION, never a whole line: a selector carries no colon, so \`#hero { … }\` is not a value
+ * and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ */
+const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+
+export interface StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+/**
+ * Comments blanked rather than removed, so the reported line number still points at the source
+ * line. \`//\` is skipped when a \`:\` precedes it — \`url(https://…)\` is a value, not a comment.
+ */
+const blankComments = (scss: string): string =>
+  scss
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/** Quoted text is a filename or a token name, never a colour: \`url('red.png')\`, \`role('bg')\`. */
+const unquote = (value: string): string => value.replaceAll(/'[^']*'|"[^"]*"/g, ' ');
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawColours(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = match[1] ?? '';
+      const value = unquote(match[2] ?? '');
+      const literal = HEX.exec(value) ?? CHANNEL_FUNCTION.exec(value) ?? NAMED.exec(value);
+      if (literal === null) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(scss, match.index)} sets \${property} to the raw colour \${literal[0]} — a value no theme can restate, so dark theme renders it unchanged\`,
+        fix: \`replace \${literal[0]} in \${file.path} with tokens.role('fg'), tokens.role('bg') or the role this element means, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a stylesheet names a semantic token, never a colour',
+  async check(root) {
+    const files: StyleFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.scss').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      if (path.includes('node_modules/')) continue;
+      files.push({ path, scss: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return rawColours(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { rawColours } from './raw-colour';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+
+unitTest('a hex literal in a declaration is refused', () => {
+  const findings = rawColours(sheet('.hero {\\n  color: #ff0000;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('#ff0000');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('rgb(), hsl() and a named colour are the same rule', () => {
+  expect(rawColours(sheet('.a { background: rgb(1 2 3); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { background: hsl(1 2% 3%); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { border-color: white; }'))).toHaveLength(1);
+});
+
+unitTest('a token, a selector and a quoted filename are not colours', () => {
+  expect(rawColours(sheet(".a { background: tokens.role('bg'); }"))).toEqual([]);
+  expect(rawColours(sheet('#hero { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet(".a { background: url('red-hero.png'); }"))).toEqual([]);
+});
+
+unitTest('a commented-out colour is a note, not a declaration', () => {
+  expect(rawColours(sheet('// color: #ff0000;\\n.a { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet('/* color: #ff0000; */\\n.a { padding: 0; }'))).toEqual([]);
+});
+`;
+
+/** `guards/raw-colour.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawColourGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/raw-colour.ts', contents: source() },
+  { path: 'guards/raw-colour.test.ts', contents: test() },
+];

package/src/templates/guard-untranslated-string.ts

@@ -0,0 +1,138 @@
+// The `untranslated-string` guard `x new` ships: no user-facing string is typed into a page.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — a hardcoded JSX string sitting
+// beside a `t()` call in a scaffolded page was green on `x verify`, and `x i18n check` cannot see
+// it either: a literal that is in no catalog is a literal the catalog audit has no key for.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'untranslated-string';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// untranslated-string: every user-facing string on a rendered surface goes through \`t()\`.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * \`<tag …>text</tag>\`, matched on the CLOSING tag rather than on the next \`<\`.
+ *
+ * That is the whole reason this rule can run over TypeScript at all: \`createSignal<State>('idle')\`
+ * is a \`>\` followed by prose-shaped source, and a pattern reading to the next \`<\` reports every
+ * generic in the file. A closing tag that names the same element cannot be a type argument.
+ *
+ * Only the INNERMOST element matches — the content class excludes \`<\` and \`>\` — which is what the
+ * rule wants: a parent whose children are elements has no text of its own.
+ */
+const ELEMENT = /<([A-Za-z][\\w.:-]*)(?:\\s[^<>]*)?>([^<>]*?)<\\/\\1>/g;
+/** A \`{…}\` child is an expression — \`{t('key')}\`, \`{props.row.title}\` — never typed prose. */
+const EXPRESSION = /\\{[^{}]*\\}/g;
+/** Two word characters in a row. One is \`&\`, \`×\`, an initial — never a sentence. */
+const PROSE = /[\\p{L}\\p{N}]{2,}/u;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function untranslatedStrings(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(ELEMENT)) {
+      const typed = (match[2] ?? '').replaceAll(EXPRESSION, ' ').trim();
+      if (!PROSE.test(typed)) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(text, match.index)} renders the typed string "\${typed}" inside <\${match[1] ?? 'element'}> — it is in no catalog, so every locale but the one it was typed in reads it verbatim\`,
+        fix: \`add a key for "\${typed}" to packages/i18n/catalogs/en.json, render it as {t('…')} in \${file.path}, then: x i18n check\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a rendered string comes from t(), never typed into the page',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // Every rendered surface: an app's \`site/\` and \`app/\`, and the shared components under
+    // \`packages/*/src\` — \`x new\` scaffolds a \`packages/ui\` whose components render to a user, so
+    // a hardcoded string there used to be green. \`api/\` renders nothing and \`shared/\` is a leaf of
+    // helpers; \`packages/*/dist\` is a build output, not source.
+    //
+    // TWO globs, never one with a leading \`{a,b}\` group: \`Bun.Glob.scan()\` matches nothing at all
+    // for a pattern that starts with a brace group — measured — so folding these into one line
+    // silently turns the guard off, which is worse than the hole it closes.
+    for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
+        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      }
+    }
+    return untranslatedStrings(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { untranslatedStrings } from './untranslated-string';
+
+const file = (source: string) => [{ path: 'apps/web/site/page.tsx', source }];
+
+unitTest('a typed JSX string is refused, and the finding quotes it', () => {
+  const findings = untranslatedStrings(file('<h1>Welcome back</h1>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('Welcome back');
+});
+
+unitTest('a t() child satisfies it, and so does any other expression', () => {
+  expect(untranslatedStrings(file("<h1>{t('site.home.title')}</h1>"))).toEqual([]);
+  expect(untranslatedStrings(file('<li class={styles.item}>{row.title}</li>'))).toEqual([]);
+});
+
+// The reason the rule reads a CLOSING tag: a generic type argument is a > followed by source that
+// looks exactly like prose, and a pattern reading to the next < reports every one of them.
+unitTest('a generic type argument is not a JSX text node', () => {
+  const generic = "const [state, setState] = createSignal<SaveState>('idle');\\nconst n = 1;";
+  expect(untranslatedStrings(file(generic))).toEqual([]);
+});
+
+unitTest('one word character is a symbol, not a sentence', () => {
+  expect(untranslatedStrings(file('<span>&</span>'))).toEqual([]);
+});
+`;
+
+/** `guards/untranslated-string.ts` and its test. The directory is the registration. */
+export const untranslatedStringGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/untranslated-string.ts', contents: source() },
+  { path: 'guards/untranslated-string.test.ts', contents: test() },
+];