@ultimat3/cli 29.4.0 → 30.1.0

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

@@ -0,0 +1,263 @@
+// The `error-declared` guard `x new` ships: an app code is declared with `defineError`, never a
+// handwritten `UltimateError` subclass or a literal-coded `new UltimateError`. Those forms take a
+// title, a status and a class in three places, and nothing made the status get written — so the
+// reference app's "post not found" answered 500, hid its cause and paged the error monitor.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/** Derived from the guard's name, never a literal: an `X_*` literal here is a FRAMEWORK code. */
+const NAME = 'error-declared';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// error-declared: an app code is declared once, with defineError — its title, its status and its class.
+// \`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.
+//
+// Known limits, both read by nothing short of a type checker: an alias by assignment
+// (const Base = UltimateError) and a shorthand key whose value is a literal elsewhere
+// (const code = 'X_NOT_FOUND'; new UltimateError({ code, … })).
+
+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}';
+
+/** Every import of core — the barrel or its page subpath: a named list (an alias) or a namespace. */
+const NAMED_IMPORT =
+  /\\bimport\\s+(?:type\\s+)?\\{([^}]*)\\}\\s*from\\s*['"]@ultimat3\\/core(?:\\/page)?['"]/g;
+const NAMESPACE_IMPORT =
+  /\\bimport\\s+\\*\\s+as\\s+([A-Za-z_$][\\w$]*)\\s+from\\s*['"]@ultimat3\\/core(?:\\/page)?['"]/g;
+const ALIAS = /^\\s*UltimateError\\s+as\\s+([A-Za-z_$][\\w$]*)\\s*$/;
+
+/** A literal code as the object's own key — bare or quoted — read where the walk below stands. */
+const LITERAL_CODE = /^(?:code|'code'|"code")\\s*:\\s*['"\`]/;
+
+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;
+
+/** The names UltimateError goes by in this file: its own, an alias, or a namespace's member. */
+const classNames = (text: string): readonly string[] => {
+  const names = ['UltimateError'];
+  for (const match of text.matchAll(NAMED_IMPORT)) {
+    for (const part of (match[1] ?? '').split(',')) {
+      const alias = ALIAS.exec(part)?.[1];
+      if (alias !== undefined) names.push(alias);
+    }
+  }
+  for (const match of text.matchAll(NAMESPACE_IMPORT)) {
+    if (match[1] !== undefined) names.push(\`\${match[1]}.UltimateError\`);
+  }
+  return names;
+};
+
+/** One alternation over those names, a namespace's dot allowed its whitespace. */
+const nameSource = (names: readonly string[]): string =>
+  names.map((name) => name.replaceAll('$', '\\\\$').replaceAll('.', '\\\\s*\\\\.\\\\s*')).join('|');
+
+/** Past the string or template opening at open. */
+const pastQuoted = (text: string, open: number): number => {
+  let index = open + 1;
+  while (index < text.length && text[index] !== text[open]) {
+    index += text[index] === '\\\\' ? 2 : 1;
+  }
+  return index + 1;
+};
+
+/**
+ * Whether the object literal opening at open carries a literal code as its OWN key, or spreads one
+ * in from a nested literal. A key deeper down — meta: { code: 'X_TIMEOUT' } — is a value, not
+ * the error's code.
+ */
+const literalCodeIn = (text: string, open: number): boolean => {
+  let depth = 0;
+  let index = open + 1;
+  while (index < text.length) {
+    const char = text[index] ?? '';
+    // Read before a quote is skipped: a quoted key ('code': …) starts with one.
+    if (depth === 0) {
+      const rest = text.slice(index);
+      if (LITERAL_CODE.test(rest) && !/[\\w$.]/.test(text[index - 1] ?? '')) return true;
+      const spread = /^\\.\\.\\.\\s*\\{/.exec(rest);
+      if (spread !== null && literalCodeIn(text, index + spread[0].length - 1)) return true;
+    }
+    if (char === "'" || char === '"' || char === '\`') {
+      index = pastQuoted(text, index);
+      continue;
+    }
+    if ('{[('.includes(char)) depth += 1;
+    if ('}])'.includes(char)) depth -= 1;
+    if (depth < 0) return false;
+    index += 1;
+  }
+  return false;
+};
+
+const finding = (file: SourceFile, line: number, what: string): Finding => ({
+  code: CODE,
+  cause: \`\${file.path}:\${line} \${what} — the title, the HTTP status and the class are then declared apart, and a code with no status answers 500 and hides its cause\`,
+  fix: \`rewrite it in \${file.path} as defineError({ code, title, status, cause, fix }) from @ultimat3/core (offSocket: true for a code no response carries), then: x verify\`,
+  at: file.path,
+});
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function undeclaredErrors(files: readonly SourceFile[]): readonly Finding[] {
+  const found: { readonly path: string; readonly line: number; readonly finding: Finding }[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    const names = nameSource(classNames(text));
+    const push = (index: number, what: string): void => {
+      const line = lineOf(text, index);
+      found.push({ path: file.path, line, finding: finding(file, line, what) });
+    };
+    for (const match of text.matchAll(new RegExp(\`\\\\bextends\\\\s+(?:\${names})\\\\b\`, 'g'))) {
+      push(match.index, 'subclasses UltimateError by hand');
+    }
+    for (const match of text.matchAll(new RegExp(\`\\\\bnew\\\\s+(?:\${names})\\\\s*\\\\(\\\\s*\`, 'g'))) {
+      const at = match.index + match[0].length;
+      // Anything but an object literal hides its code from this read: a value built elsewhere,
+      // Object.assign over a literal. A re-raise is written as a literal, with code: err.code.
+      if (text[at] !== '{')
+        push(match.index, 'builds new UltimateError from a value this guard cannot read');
+      else if (literalCodeIn(text, at))
+        push(match.index, 'builds new UltimateError with a literal code');
+    }
+  }
+  return found
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : a.line - b.line))
+    .map((entry) => entry.finding);
+}
+
+export const guard: Guard = {
+  summary:
+    'an app error code is declared with defineError — never a handwritten UltimateError subclass',
+  async check(_root, sources) {
+    // A test may build any error it likes as INPUT. The run's ONE read of the source: every guard
+    // asking for this glob shares the walk.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return undeclaredErrors(
+      code
+        .filter((file) => !/\\.(?:test|d)\\.tsx?$/.test(file.path))
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
+  },
+};
+`;
+
+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 { undeclaredErrors } from './error-declared';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/errors.ts', source }];
+
+/** Spelled from parts, so a grep of the app for a handwritten subclass finds only real ones. */
+const EXTENDS = ['extends', 'UltimateError'].join(' ');
+
+unitTest('a handwritten subclass is refused, and the finding names the line', () => {
+  const findings = undeclaredErrors(file(\`const x = 1;\\nexport class PostNotFound \${EXTENDS} {}\`));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('a literal code handed to new UltimateError is refused', () => {
+  expect(
+    undeclaredErrors(
+      file("throw new UltimateError({ code: 'X_NOT_FOUND', cause: 'c', fix: 'x' });"),
+    ),
+  ).toHaveLength(1);
+  expect(
+    undeclaredErrors(file("new UltimateError({ cause: 'c', code: \\"X_NOT_FOUND\\", fix: 'x' });")),
+  ).toHaveLength(1);
+});
+
+unitTest('a re-raise passing err.code is not a declaration', () => {
+  expect(
+    undeclaredErrors(
+      file("new UltimateError({ code: err.code, cause: err.cause, fix: 'x verify' });"),
+    ),
+  ).toEqual([]);
+});
+
+unitTest('defineError is what the rule asks for, and a comment is not code', () => {
+  expect(
+    undeclaredErrors(
+      file(
+        "export const Gone = defineError({ code: 'X_FORBIDDEN', title: 't', status: 410, cause: 'c', fix: 'x' });",
+      ),
+    ),
+  ).toEqual([]);
+  expect(undeclaredErrors(file(\`// class Old \${EXTENDS} {}\`))).toEqual([]);
+});
+
+unitTest('an aliased or namespaced UltimateError is the same class', () => {
+  const aliased = "import { UltimateError as Base } from '@ultimat3/core';\\n";
+  expect(
+    undeclaredErrors(
+      file(\`\${aliased}export class A \${EXTENDS.replace('UltimateError', 'Base')} {}\`),
+    ),
+  ).toHaveLength(1);
+  const namespaced = "import * as core from '@ultimat3/core';\\n";
+  expect(
+    undeclaredErrors(
+      file(
+        \`\${namespaced}throw new core.UltimateError({ code: 'X_NOT_FOUND', cause: 'c', fix: 'x' });\`,
+      ),
+    ),
+  ).toHaveLength(1);
+});
+
+unitTest(
+  'a code spread in, or behind a value, is refused; one nested in meta is not the code',
+  () => {
+    expect(
+      undeclaredErrors(
+        file("throw new UltimateError({ ...{ code: 'X_NOT_FOUND' }, cause: 'c', fix: 'x' });"),
+      ),
+    ).toHaveLength(1);
+    expect(undeclaredErrors(file('throw new UltimateError(init);'))).toHaveLength(1);
+    expect(
+      undeclaredErrors(
+        file(
+          "new UltimateError({ code: err.code, cause: 'c', fix: 'x', meta: { code: 'X_TIMEOUT' } });",
+        ),
+      ),
+    ).toEqual([]);
+  },
+);
+
+unitTest('an alias from the page subpath and a quoted code key are the same rule', () => {
+  const paged = "import { UltimateError as PageError } from '@ultimat3/core/page';\\n";
+  expect(
+    undeclaredErrors(
+      file(\`\${paged}throw new PageError({ code: 'X_NOT_FOUND', cause: 'c', fix: 'x' });\`),
+    ),
+  ).toHaveLength(1);
+  expect(
+    undeclaredErrors(
+      file("throw new UltimateError({ 'code': 'X_INTERNAL', cause: 'c', fix: 'x' });"),
+    ),
+  ).toHaveLength(1);
+});
+`;
+
+/** `guards/error-declared.ts` and its test. No index, no registry — the directory registers it. */
+export const errorDeclaredGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/error-declared.ts', contents: source() },
+  { path: 'guards/error-declared.test.ts', contents: test() },
+];

package/src/templates/guard-native-confirm.ts

@@ -0,0 +1,132 @@
+// The `native-confirm` guard `x new` ships: no app code asks a destructive question through
+// `window.confirm(`. The browser's box holds focus on OK, so a stray Enter confirms; it cannot be
+// styled, translated or refused, and it blocks the page. `ConfirmDialog` from `@ultimat3/ui` is the
+// one way. A `// why:` on the call's line, or the line above it, admits a call that is not that.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/** Derived from the guard's name, never a literal: an `X_*` literal here is a FRAMEWORK code. */
+const NAME = 'native-confirm';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// native-confirm: a destructive question is a ConfirmDialog, never window.confirm(.
+// \`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.
+//
+// Why: the browser's confirm box focuses OK, so the Enter that opened it confirms it; it cannot be
+// translated, styled or refused, and it blocks the page while it is up. \`ConfirmDialog\` from
+// \`@ultimat3/ui\` focuses Cancel, posts natively with scripting off and stays open on a refusal.
+// Read: a bare, \`window.\`, \`self.\` or \`globalThis.\` \`confirm(\` in a \`*.island.tsx\` or anywhere
+// under \`apps/web/\`. Admitted: a \`// why:\` on the call's line or the line above it.
+
+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}';
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+const CALL = /(?<![\\w$.])(?<!function\\s+)(?:(?:globalThis|window|self)\\s*\\.\\s*)?confirm\\s*\\(/g;
+const WHY = /\\/\\/\\s*why:/;
+
+/** Comments and string bodies blanked IN PLACE, so a 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))
+    .replaceAll(/'(?:[^'\\\\\\n]|\\\\.)*'|"(?:[^"\\\\\\n]|\\\\.)*"|\`(?:[^\`\\\\]|\\\\.)*\`/g, (match) =>
+      match.replaceAll(/[^\\n]/g, ' '),
+    );
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function nativeConfirms(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const lines = file.source.split('\\n');
+    const text = blank(file.source);
+    for (const match of text.matchAll(CALL)) {
+      const line = text.slice(0, match.index).split('\\n').length;
+      if (WHY.test(lines[line - 1] ?? '') || WHY.test(lines[line - 2] ?? '')) continue;
+      const at = \`\${file.path}:\${line}\`;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} asks with confirm(), whose OK holds focus — a stray Enter confirms — and which cannot be translated or refused\`,
+        fix: \`replace the confirm() at \${at} with <ConfirmDialog> from '@ultimat3/ui' (action= for a native post, onConfirm= in an island) — or add a // why: comment on that line naming why it is not a destructive question — then: x verify\`,
+        at,
+      });
+    }
+  }
+  return findings;
+}
+
+/** The files the rule reads: islands anywhere, and all of \`apps/web/\`; never a test. */
+export const readsFile = (path: string): boolean =>
+  !/\\.test\\.tsx?$/.test(path) && (path.endsWith('.island.tsx') || path.startsWith('apps/web/'));
+
+export const guard: Guard = {
+  summary: 'a destructive question is a ConfirmDialog, never window.confirm()',
+  async check(_root, sources) {
+    // The run's ONE read of the source: every guard asking for this glob shares the walk.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return nativeConfirms(
+      code
+        .filter((file) => readsFile(file.path))
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
+  },
+};
+`;
+
+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 { nativeConfirms, readsFile } from './native-confirm';
+
+const file = (source: string) => [{ path: 'apps/web/app/posts/delete.island.tsx', source }];
+
+unitTest('a bare confirm( is refused, and the finding names the line', () => {
+  const findings = nativeConfirms(file("const a = 1;\\nif (confirm('Delete?')) remove();"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/app/posts/delete.island.tsx:2');
+});
+
+unitTest('window., self. and globalThis. are the same rule', () => {
+  expect(nativeConfirms(file("window.confirm('Delete?');"))).toHaveLength(1);
+  expect(nativeConfirms(file("self.confirm('Delete?');"))).toHaveLength(1);
+  expect(nativeConfirms(file("globalThis.confirm('Delete?');"))).toHaveLength(1);
+});
+
+unitTest('a why: on the line or the line above admits it', () => {
+  expect(nativeConfirms(file("confirm('Leave?'); // why: an unload prompt"))).toEqual([]);
+  expect(nativeConfirms(file("// why: a dev-only reset\\nconfirm('Reset?');"))).toEqual([]);
+});
+
+unitTest('a comment, a string, a method and a definition are not calls', () => {
+  expect(nativeConfirms(file("// confirm('Delete?');"))).toEqual([]);
+  expect(nativeConfirms(file("const s = 'confirm(x)';"))).toEqual([]);
+  expect(nativeConfirms(file('dialog.confirm(input);'))).toEqual([]);
+  expect(nativeConfirms(file('function confirm(input) { return input; }'))).toEqual([]);
+});
+
+unitTest('islands and apps/web are read; tests and other packages are not', () => {
+  expect(readsFile('apps/web/app/posts/page.tsx')).toBe(true);
+  expect(readsFile('packages/ui/src/delete.island.tsx')).toBe(true);
+  expect(readsFile('apps/web/app/posts/page.test.ts')).toBe(false);
+  expect(readsFile('packages/domain/src/rules.ts')).toBe(false);
+});
+`;
+
+/** `guards/native-confirm.ts` and its test. No index, no registry — the directory registers it. */
+export const nativeConfirmGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];

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

@@ -0,0 +1,151 @@
+// The `raw-fetch` guard `x new` ships: a server `fetch(` carries a signal in its own options, or is
+// `outbound()` from `@ultimat3/core/outbound`. A fetch with no signal outlives the request that made
+// it — a stalled vendor holds the handler, the drain and a socket for as long as it likes. With a
+// signal it stays legal: the guard cannot prove the other properties, and outbound() is the way.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/** Derived from the guard's name, never a literal: an `X_*` literal here is a FRAMEWORK code. */
+const NAME = 'raw-fetch';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-fetch: a server fetch( carries a signal in its own options, or is outbound().
+// \`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.
+//
+// Read: a bare or \`globalThis.\` \`fetch(\` call. Not read: an injected \`deps.fetch(\`, a method
+// DEFINITION (\`fetch(request) {\`, Bun.serve's handler), a test, or an island (a browser has no
+// request to outlive). Options passed as a variable read as unsignalled: spread them and add the key.
+
+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}';
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+const CALL = /(?<![\\w$.])(?:globalThis\\s*\\.\\s*)?fetch\\s*\\(/g;
+const SIGNAL = /(?<![\\w$.])signal\\s*[:,}]/g;
+
+/** Comments and string bodies blanked IN PLACE, so a 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))
+    .replaceAll(/'(?:[^'\\\\\\n]|\\\\.)*'|"(?:[^"\\\\\\n]|\\\\.)*"|\`(?:[^\`\\\\]|\\\\.)*\`/g, (match) =>
+      match.replaceAll(/[^\\n]/g, ' '),
+    );
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** The index of the parenthesis closing the one at \`open\`, or the end of the text. */
+const closeOf = (text: string, open: number): number => {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    if (text[index] === '(') depth += 1;
+    if (text[index] === ')' && --depth === 0) return index;
+  }
+  return text.length;
+};
+
+/** Whether \`signal\` is a key of an object at the arguments' TOP level — never \`{ env: { signal } }\`. */
+const hasSignal = (args: string): boolean => {
+  for (const match of args.matchAll(SIGNAL)) {
+    const opened: string[] = [];
+    for (const char of args.slice(0, match.index)) {
+      if (char === '{' || char === '[' || char === '(') opened.push(char);
+      else if (char === '}' || char === ']' || char === ')') opened.pop();
+    }
+    if (opened.length === 1 && opened[0] === '{') return true;
+  }
+  return false;
+};
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawFetches(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(CALL)) {
+      const open = match.index + match[0].length - 1;
+      const close = closeOf(text, open);
+      const after = text.slice(close + 1).trimStart();
+      // A definition, not a call: a method body or its return type follows the parameter list.
+      if (after.startsWith('{') || after.startsWith(':')) continue;
+      if (/\\bfunction\\s*\\*?\\s*$/.test(text.slice(0, match.index))) continue;
+      if (hasSignal(text.slice(open + 1, close))) continue;
+      const at = \`\${file.path}:\${lineOf(text, match.index)}\`;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} calls fetch with no signal in its own options, so the call outlives the request that made it: a stalled vendor holds the handler, the drain and a socket\`,
+        fix: \`call outbound({ url, vendor, dial: 'public', deadlineMs: 10_000 }) from @ultimat3/core/outbound in place of the fetch at \${at}, or pass { signal: ctx.signal } in its options — then: x verify\`,
+        at,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary:
+    'a server fetch carries a signal, or is outbound() — never a call that outlives its request',
+  async check(_root, sources) {
+    // The run's ONE read of the source: every guard asking for this glob shares the walk.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return rawFetches(
+      code
+        .filter(
+          (file) => !/\\.(?:test|d)\\.tsx?$/.test(file.path) && !file.path.endsWith('.island.tsx'),
+        )
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
+  },
+};
+`;
+
+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 { rawFetches } from './raw-fetch';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/repo.ts', source }];
+
+unitTest('a bare fetch is refused, and the finding names the line', () => {
+  const findings = rawFetches(file('const a = 1;\\nconst r = await fetch(url);'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/app/post/repo.ts:2');
+});
+
+unitTest('globalThis.fetch and a signal nested in another key are the same rule', () => {
+  expect(rawFetches(file('await globalThis.fetch(url, { method: "POST" });'))).toHaveLength(1);
+  expect(rawFetches(file('await fetch(url, { env: { signal } });'))).toHaveLength(1);
+  expect(rawFetches(file('await fetch(url, init);'))).toHaveLength(1);
+});
+
+unitTest('a signal in its own options is what the rule asks for', () => {
+  expect(rawFetches(file('await fetch(url, { signal });'))).toEqual([]);
+  expect(rawFetches(file('await fetch(url, { method: "GET", signal: ctx.signal });'))).toEqual([]);
+});
+
+unitTest('an injected fetch, a handler definition and a comment are not calls', () => {
+  expect(rawFetches(file('await deps.fetch(url);'))).toEqual([]);
+  expect(rawFetches(file('Bun.serve({ fetch(request) { return new Response(); } });'))).toEqual([]);
+  expect(rawFetches(file('// await fetch(url);'))).toEqual([]);
+  expect(rawFetches(file("const s = 'fetch(url)';"))).toEqual([]);
+});
+`;
+
+/** `guards/raw-fetch.ts` and its test. No index, no registry — the directory registers it. */
+export const rawFetchGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];

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

@@ -0,0 +1,121 @@
+// The `raw-interval` guard `x new` ships: an island polls with `visibleInterval()` from
+// `@ultimat3/core/page`, never a bare `setInterval(`. A raw interval keeps asking from a hidden tab
+// and, past the session, asks for a 401 forever — five adopters hand-rolled the gate this replaces.
+// A `// why:` on the call's line, or the line above it, admits a tick that is not a read.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/** Derived from the guard's name, never a literal: an `X_*` literal here is a FRAMEWORK code. */
+const NAME = 'raw-interval';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-interval: an island polls with visibleInterval(), never a bare setInterval(.
+// \`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.
+//
+// Why: a raw interval keeps asking from a background tab, and from a tab past its session it asks
+// for a 401 forever. \`visibleInterval(run, ms)\` from \`@ultimat3/core/page\` makes no call while the
+// tab is hidden, one when it is shown, and stops at the first lost session. Read: a bare,
+// \`window.\`, \`self.\` or \`globalThis.\` \`setInterval(\` in a \`*.island.tsx\`. Admitted: a \`// why:\` on
+// the call's line or the line above it — an animation tick is not a read.
+
+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}';
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+const CALL = /(?<![\\w$.])(?:(?:globalThis|window|self)\\s*\\.\\s*)?setInterval\\s*\\(/g;
+const WHY = /\\/\\/\\s*why:/;
+
+/** Comments and string bodies blanked IN PLACE, so a 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))
+    .replaceAll(/'(?:[^'\\\\\\n]|\\\\.)*'|"(?:[^"\\\\\\n]|\\\\.)*"|\`(?:[^\`\\\\]|\\\\.)*\`/g, (match) =>
+      match.replaceAll(/[^\\n]/g, ' '),
+    );
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawIntervals(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const lines = file.source.split('\\n');
+    const text = blank(file.source);
+    for (const match of text.matchAll(CALL)) {
+      const line = text.slice(0, match.index).split('\\n').length;
+      if (WHY.test(lines[line - 1] ?? '') || WHY.test(lines[line - 2] ?? '')) continue;
+      const at = \`\${file.path}:\${line}\`;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} polls with setInterval, which keeps asking from a hidden tab and asks for a 401 forever once the session is gone\`,
+        fix: \`import { visibleInterval } from '@ultimat3/core/page' and call visibleInterval(run, ms) at \${at}, disposing it on cleanup — or add a // why: comment on that line naming why this interval is not a read — then: x verify\`,
+        at,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'an island polls with visibleInterval(), never a bare setInterval',
+  async check(_root, sources) {
+    // The run's ONE read of the source: every guard asking for this glob shares the walk.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return rawIntervals(
+      code
+        .filter((file) => file.path.endsWith('.island.tsx'))
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
+  },
+};
+`;
+
+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 { rawIntervals } from './raw-interval';
+
+const file = (source: string) => [{ path: 'apps/web/app/feed/ticker.island.tsx', source }];
+
+unitTest('a bare setInterval is refused, and the finding names the line', () => {
+  const findings = rawIntervals(file('const a = 1;\\nconst id = setInterval(poll, 5000);'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/app/feed/ticker.island.tsx:2');
+});
+
+unitTest('window., self. and globalThis. are the same rule', () => {
+  expect(rawIntervals(file('window.setInterval(poll, 5000);'))).toHaveLength(1);
+  expect(rawIntervals(file('self.setInterval(poll, 5000);'))).toHaveLength(1);
+  expect(rawIntervals(file('globalThis.setInterval(poll, 5000);'))).toHaveLength(1);
+});
+
+unitTest('a why: on the line or the line above admits it', () => {
+  expect(rawIntervals(file('setInterval(tick, 16); // why: a frame, not a read'))).toEqual([]);
+  expect(rawIntervals(file('// why: a clock, not a read\\nsetInterval(tick, 1000);'))).toEqual([]);
+});
+
+unitTest('visibleInterval, another object, a comment and a string are not calls', () => {
+  expect(rawIntervals(file('visibleInterval(poll, 5000);'))).toEqual([]);
+  expect(rawIntervals(file('timers.setInterval(poll, 5000);'))).toEqual([]);
+  expect(rawIntervals(file('// setInterval(poll, 5000);'))).toEqual([]);
+  expect(rawIntervals(file("const s = 'setInterval(poll)';"))).toEqual([]);
+});
+`;
+
+/** `guards/raw-interval.ts` and its test. No index, no registry — the directory registers it. */
+export const rawIntervalGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];