@ultimat3/cli 22.15.0 → 23.0.0

package/src/templates/guard-undefined-style-class.ts

@@ -0,0 +1,215 @@
+// The `undefined-style-class` guard `x new` ships: `styles.<name>` is a class its `.module.scss`
+// COMPILES. `cx` drops an `undefined`, so a dead class renders nothing wrong and says nothing —
+// the deployed demo carried one (`styles.wordmark`) through every gate until this guard read it.
+// The class list is the build's own (`GuardSources.compiled`), so a mixin-generated class counts.
+
+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 = 'undefined-style-class';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// undefined-style-class: a class a component asks its stylesheet for is a class the sheet compiles.
+// \`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 from the COMPILED sheet, so a class a mixin generates or \`&-suffix\` nests is one, and a
+// class inside \`:global()\` is not. A computed member (\`styles[name]\`) is out of scope: its key is
+// only known when the component runs. A sheet that does not compile is the build's refusal.
+
+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 MarkupFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly tsx: string;
+}
+
+/** The classes a stylesheet compiles, by app-root-relative path; \`undefined\` when it does not. */
+export type CompiledClasses = (sheet: string) => Promise<readonly string[] | undefined>;
+
+const blank = (text: string): string => text.replaceAll(/[^\\n]/g, ' ');
+
+/** Comments blanked rather than removed, so a reported line number still points at the source. */
+const blankComments = (tsx: string): string =>
+  tsx.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, blank).replaceAll(/(?<![:\\w'"\`])\\/\\/[^\\n]*/g, blank);
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** \`import styles from './page.module.scss'\` — the binding, and the sheet it reads. */
+const SHEET_IMPORT =
+  /import\\s+([A-Za-z_$][\\w$]*)\\s+from\\s+['"](\\.{1,2}\\/[^'"]+\\.module\\.s?css)['"]/g;
+
+/** \`a/b/page.tsx\` + \`../x.module.scss\` → \`a/x.module.scss\`. */
+const resolve = (from: string, specifier: string): string => {
+  const parts = from.split('/').slice(0, -1);
+  for (const segment of specifier.split('/')) {
+    if (segment === '..') parts.pop();
+    else if (segment !== '.') parts.push(segment);
+  }
+  return parts.join('/');
+};
+
+/** The declared class a misspelt one most likely meant: one edit away, or the same letters. */
+const nearest = (name: string, declared: readonly string[]): string | undefined => {
+  const fold = (text: string): string => text.toLowerCase().replaceAll(/[-_]/g, '');
+  return (
+    declared.find((candidate) => fold(candidate) === fold(name)) ??
+    declared.find(
+      (candidate) =>
+        Math.abs(candidate.length - name.length) <= 1 &&
+        (candidate.startsWith(name.slice(0, -1)) || name.startsWith(candidate.slice(0, -1))),
+    )
+  );
+};
+
+/** Pure but for \`classesOf\`, which the caller supplies — so the rule is testable without Sass. */
+export async function undefinedStyleClasses(
+  files: readonly MarkupFile[],
+  classesOf: CompiledClasses,
+): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const tsx = blankComments(file.tsx);
+    for (const imported of tsx.matchAll(SHEET_IMPORT)) {
+      const binding = imported[1] ?? '';
+      const sheet = resolve(file.path, imported[2] ?? '');
+      const declared = await classesOf(sheet);
+      if (declared === undefined) continue;
+      // \`styles.hero\` and \`styles['hero-title']\` — a static key either way. \`styles[name]\` has no
+      // quote after the bracket and is not matched. A path is not a read: \`'./shell.module.scss'\`
+      // holds \`shell.module\`, so a name that follows a slash, a quote or a dash is skipped.
+      const read = new RegExp(
+        \`(?<![\\\\w$./'"-])\${binding.replaceAll('$', '\\\\$')}(?:\\\\.([A-Za-z_$][\\\\w$]*)|\\\\[\\\\s*(['"])([^'"]+)\\\\2\\\\s*\\\\])\`,
+        'g',
+      );
+      const reported = new Set<string>();
+      for (const use of tsx.matchAll(read)) {
+        const name = use[1] ?? use[3] ?? '';
+        if (declared.includes(name) || reported.has(name)) continue;
+        reported.add(name);
+        const line = lineOf(tsx, use.index);
+        const meant = nearest(name, declared);
+        findings.push({
+          code: CODE,
+          cause: \`\${file.path}:\${line} reads \${binding}.\${name}, and \${sheet} compiles no class \\\`\${name}\\\` — the element renders with no class, and nothing says so\`,
+          fix:
+            meant === undefined
+              ? \`add \\\`.\${name} { … }\\\` to \${sheet}, or delete the read at \${file.path}:\${line}, then: x verify\`
+              : \`\${binding}\${/^[A-Za-z_$][\\w$]*$/.test(meant) ? \`.\${meant}\` : \`['\${meant}']\`} — at \${file.path}:\${line}; \${sheet} declares \\\`.\${meant}\\\`, then: x verify\`,
+          at: \`\${file.path}:\${line}\`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a class a component reads off its stylesheet is a class that sheet compiles',
+  async check(_root, sources) {
+    const markup = await sources.files('{apps,packages}/**/*.tsx');
+    return undefinedStyleClasses(
+      markup.map((file) => ({ path: file.path, tsx: file.text })),
+      async (sheet) => {
+        const compiled = await sources.compiled(sheet);
+        return compiled === undefined ? undefined : Object.keys(compiled.classes);
+      },
+    );
+  },
+};
+`;
+
+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 { undefinedStyleClasses } from './undefined-style-class';
+
+const SHEETS: Readonly<Record<string, readonly string[]>> = {
+  'apps/web/site/page.module.scss': ['hero', 'hero-title', 'tone-accent'],
+  'apps/web/shared/shell.module.scss': ['shell'],
+};
+const classesOf = async (sheet: string) => SHEETS[sheet];
+
+const page = (body: string, imports = "import styles from './page.module.scss';") => [
+  { path: 'apps/web/site/page.tsx', tsx: \`\${imports}\\n\${body}\\n\` },
+];
+const check = (body: string, imports?: string) =>
+  undefinedStyleClasses(page(body, imports), classesOf);
+
+unitTest('a class the sheet does not compile is refused, with the line it is read on', async () => {
+  const findings = await check('export const Page = () => <h1 class={styles.missing} />;');
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/site/page.tsx:2');
+  expect(findings[0]?.cause).toContain(
+    'apps/web/site/page.module.scss compiles no class \`missing\`',
+  );
+  expect(findings[0]?.fix).toStartWith('add \`.missing { … }\` to apps/web/site/page.module.scss');
+});
+
+unitTest('a near miss is repaired with the class the sheet does declare', async () => {
+  const dot = await check('export const Page = () => <h1 class={styles.heroo} />;');
+  expect(dot[0]?.fix).toStartWith('styles.hero — at ');
+  const bracket = await check("export const Page = () => <h1 class={styles['heroTitle']} />;");
+  expect(bracket[0]?.fix).toStartWith("styles['hero-title'] — at ");
+});
+
+unitTest('a bracket read, a classList key and a second binding are all reads', async () => {
+  expect(await check("export const Page = () => <h1 class={styles['nope']} />;")).toHaveLength(1);
+  expect(
+    await check('export const Page = () => <h1 classList={{ [styles.nope]: on() }} />;'),
+  ).toHaveLength(1);
+  const two =
+    "import styles from './page.module.scss';\\nimport shell from '../shared/shell.module.scss';";
+  const findings = await check('export const Page = () => <h1 class={shell.hero} />;', two);
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('apps/web/shared/shell.module.scss');
+});
+
+unitTest('one missing class read five times is one finding', async () => {
+  const body = 'const a = [styles.gone, styles.gone, styles.gone, styles.gone, styles.gone];';
+  expect(await check(body)).toHaveLength(1);
+});
+
+// The legitimate lookalikes — the reason the rule can stay switched on.
+unitTest('a compiled class, however it is read, is silent', async () => {
+  const silent = [
+    'export const Page = () => <h1 class={styles.hero} />;',
+    "export const Page = () => <h1 class={styles['hero-title']} />;",
+    'export const Page = () => <h1 classList={{ [styles.hero]: on() }} />;',
+    // Generated by a mixin: only the compiled sheet knows it exists.
+    "export const Page = () => <h1 class={styles['tone-accent']} />;",
+  ];
+  for (const body of silent) expect(await check(body)).toEqual([]);
+});
+
+unitTest('a computed key, a comment and another object are out of scope', async () => {
+  const silent = [
+    'export const Page = (p) => <h1 class={styles[p.tone]} />;',
+    \`export const Page = (p) => <h1 class={styles[\\\`tone-\\\${p.tone}\\\`]} />;\`,
+    '// styles.missing\\nexport const Page = () => <h1 class={styles.hero} />;',
+    'export const Page = (p) => <h1 class={p.styles.missing} />;',
+    'export const Page = () => <h1 class={mystyles.missing} />;',
+  ];
+  for (const body of silent) expect(await check(body)).toEqual([]);
+});
+
+unitTest("a sheet that does not compile is the build's finding, not this guard's", async () => {
+  const imports = "import styles from './broken.module.scss';";
+  expect(await check('export const Page = () => <h1 class={styles.any} />;', imports)).toEqual([]);
+});
+`;
+
+/** `guards/undefined-style-class.ts` and its test. No index, no registry — the directory is the registration. */
+export const undefinedStyleClassGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];

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

@@ -104,7 +104,7 @@ export function untranslatedStrings(files: readonly SourceFile[]): readonly Find
 
 export const guard: Guard = {
   summary: 'a rendered string comes from t(), never typed into the page',
-  async check(root) {
+  async check(_root, sources) {
     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
@@ -115,13 +115,13 @@ export const guard: Guard = {
     // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
     // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
     // matches 17 — so folding these into one line silently turns the guard off, which is worse than
-    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // the hole it closes. A LEADING group is fine and the stylesheet guards here rely on it:
     // \`{apps,packages}/**/*.scss\` matches all 15.
     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() });
+      // The run's ONE read: every guard asking for these two globs shares the walk.
+      for (const file of await sources.files(pattern)) {
+        if (/\\.test\\.tsx?$/.test(file.path)) continue;
+        files.push({ path: file.path, source: file.text });
       }
     }
     return untranslatedStrings(files);

package/src/templates/guard-unzoned-date.ts

@@ -94,19 +94,15 @@ export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
 
 export const guard: Guard = {
   summary: 'a date is never formatted without an explicit IANA time zone',
-  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's subject is often the wrong shape on purpose, and \`node_modules\` is not this
-      // app's source. Neither exclusion hides a rendered date from a user.
-      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
-      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
-    }
-    return unzonedDates(files);
+  async check(_root, sources) {
+    // A test's subject is often the wrong shape on purpose; excluding it hides no rendered date
+    // from a user. The run's ONE read of the source: every guard asking for this glob shares it.
+    const code = await sources.files('{apps,packages}/**/*.{ts,tsx}');
+    return unzonedDates(
+      code
+        .filter((file) => !/\\.(?:test|d)\\.tsx?$/.test(file.path))
+        .map((file) => ({ path: file.path, source: file.text })),
+    );
   },
 };
 `;

package/src/templates/index.ts

@@ -43,8 +43,9 @@ export { dashboardFiles } from './scaffold-dashboard';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { entryFiles } from './scaffold-entries';
 export { errorPageFiles, PWA_COLORS } from './scaffold-errors';
-// The nine guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
-export { scaffoldGuardFiles } from './scaffold-guards';
+// The guards `x new` ships — `SHIPPED_GUARD_NAMES` is the list — distinct from `guardFiles` above,
+// which is the blank template `x g guard <name>` writes for a name that is not one of them.
+export { SHIPPED_GUARD_NAMES, scaffoldGuardFiles, shippedGuardFiles } from './scaffold-guards';
 export { i18nIndex, localeEntry, localeImport } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
 export { shellFiles } from './scaffold-shell';

package/src/templates/island.ts

@@ -73,8 +73,8 @@ function ${Name}(props: ${Name}Props): JSX.Element {
  */
 export function mount(el: HTMLElement, props: ${Name}Props): () => void {
   el.textContent = '';
-  // Solid's \`render\` answers its disposer; returning it is what lets \`mountIsland\` in
-  // \`@ultimat3/testing\` stop this island — its timers included — when a test is done with it.
+  // Solid's \`render\` answers its disposer; returning it is what lets \`@ultimat3/testing\`
+  // stop this island — its timers included — when a test is done with it.
   return render(() => <${Name} {...props} />, el);
 }
 `;
@@ -102,9 +102,9 @@ const islandStyle =
 const islandTest = (
   name: string,
   dir: string,
-): string => `// The island the browser actually runs. \`mountIsland\` builds this entry with the same
-// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
-// runtime does, and drives \`mount\` against a DOM small enough to read.
+): string => `// The island the browser actually runs, in every state its manifest declares: built once for
+// this file with the same \`buildIslands\` that \`x build\` and \`x dev\` use, imported the way the
+// hydration runtime imports it, and driven against a DOM small enough to read.
 //
 // Importing the module and asserting \`typeof mount === 'function'\` proves the file exists, and a
 // file that exists is exactly what ships dead: a renamed export, a dropped handler and a signal
@@ -112,60 +112,43 @@ const islandTest = (
 
 import { join } from 'node:path';
 import { buildIslands } from '@ultimat3/cli';
-import {
-  afterAll,
-  beforeAll,
-  describe,
-  expect,
-  type MountedIsland,
-  mountIsland,
-  test,
-} from '@ultimat3/testing';
-
-const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
-const ISLAND = '${dir}/${name}.island.tsx';
-
-let mounted: MountedIsland;
-
-// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
-// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
-// per case, so the slow work goes where it can be given one and every case shares the result.
-beforeAll(async () => {
-  mounted = await mountIsland({
-    build: buildIslands,
-    root: APP_ROOT,
-    file: ISLAND,
-    props: { label: 'Open' },
-    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
-    shell: '<span>Open</span>',
-  });
-}, 60_000);
-
-// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
-//
-// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
-// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
-// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
-// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
-// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
-afterAll(() => {
-  mounted?.[Symbol.dispose]();
-});
+import { describeIslandState, expect, test } from '@ultimat3/testing';
+import { ${camel(name)}States } from './${name}.island.states';
+
+// One block per declared state: \`describeIslandState\` mounts it before the block's first test
+// and disposes it after the last. The props are the manifest's own — what
+// \`x shot --island ${name}\` photographs — so the picture and the test are of one component.
+const island = {
+  build: buildIslands,
+  root: join(import.meta.dir, ${upToAppRoot(dir)}),
+  // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+  shell: '<span>shell</span>',
+};
 
-describe('the ${name} island', () => {
-  test('mount replaces the server shell', () => {
-    expect(mounted.find('span')).toBeNull();
+describeIslandState(${camel(name)}States, 'idle', island, (mounted) => {
+  test('mount replaces the server shell with the labelled control', () => {
+    expect(mounted().find('span')).toBeNull();
+    expect(mounted().text('button')).toBe('Open');
     // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
     // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
-    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+    expect(mounted().code).not.toMatch(/\\bReact\\b/);
   });
 
   test('a click reaches the DOM through the signal', () => {
-    expect(mounted.text('[data-role="count"]')).toBe('0');
+    expect(mounted().text('[data-role="count"]')).toBe('0');
     // \`false\` means no handler ran — an island whose onClick never reached the DOM looks identical
     // to a selector typo otherwise.
-    expect(mounted.fire('button', 'click')).toBe(true);
-    expect(mounted.text('[data-role="count"]')).toBe('1');
+    expect(mounted().fire('button', 'click')).toBe(true);
+    expect(mounted().text('[data-role="count"]')).toBe('1');
+  });
+});
+
+describeIslandState(${camel(name)}States, 'long-label', island, (mounted) => {
+  test('the label arrives whole, and the control still counts from zero', () => {
+    // Whether it FITS is a picture's question — \`x shot --island ${name} --state long-label\`.
+    // What a test can say is that the island was handed this state's own text, not the idle one's.
+    expect(mounted().text('button')).toBe('Abrechnungseinstellungen anzeigen');
+    expect(mounted().text('[data-role="count"]')).toBe('0');
   });
 });
 `;

package/src/templates/job-body-test.ts

@@ -0,0 +1,121 @@
+// The UNIT tests `x g job` / `x g task` write beside the `.job.test.ts`: the body, run by an
+// in-process worker (`runJobs`) against the in-memory queue and the in-memory driver. Split from
+// `job.ts`, which owns the declarations and the job-suite tests — an app's coverage floor counts
+// the unit suite alone, so a body only the `job` step runs is uncovered source.
+
+import { sortedImports } from './imports';
+import type { NameSet } from './naming';
+
+const ID = '00000000-0000-4000-8000-000000000001';
+const ORG = '00000000-0000-4000-8000-000000000002';
+
+/** The steps one run of the tenant-scoped body may take, and which test proves each. */
+export interface JobBodyShape {
+  /** The body reads `../repo` under the org its input names. */
+  readonly scoped: boolean;
+  /** The slice still takes the row `x g entity` scaffolds, so a test may store one. */
+  readonly storesRow: boolean;
+  readonly dbModule: string;
+}
+
+const HEADER = (
+  name: NameSet,
+): string => `// ${name.camel}'s BODY, run by a worker in this process: \`runJobs\` enqueues, claims and executes
+// against an in-memory queue, so what this pins is which steps one run takes and what the body
+// answers. The durable guarantees — the idempotency key, the dedupe, the retry policy — are the
+// job suite's, next door.`;
+
+const storedRowTest = (name: NameSet): string => `
+unitTest('a stored row is loaded, then processed, once each', async ({ runJobs }) => {
+  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
+  const row = await runWithContext(createContext({ actor: member }), () => repo.insert(draft));
+  const trace = await runJobs(${name.camel}, { id: row.id, orgId });
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(trace.executions[0]?.result).toEqual({ skipped: false });
+  expect(trace.steps.load?.executions).toBe(1);
+  expect(trace.steps.process?.executions).toBe(1);
+});
+`;
+
+const scopedBodyTest = (name: NameSet, shape: JobBodyShape): string => `${HEADER(name)}
+${sortedImports([
+  ...(shape.storesRow
+    ? [
+        "import { createContext, runWithContext } from '@ultimat3/core';",
+        "import { testActor } from '@ultimat3/policy';",
+        "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
+        `import { driver } from '${shape.dbModule}';`,
+      ]
+    : ["import { expect, unitTest } from '@ultimat3/testing';"]),
+])}${shape.storesRow ? "\nimport * as repo from '../repo';" : ''}
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+const orgId = '${ORG}';
+${
+  shape.storesRow
+    ? `
+// Who stores the row the job then reads: the body itself runs as the org its input names.
+const member = testActor('member', { orgId }).actor;
+
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+`
+    : ''
+}
+unitTest('an id nothing holds stops after the load: nothing is processed', async ({ runJobs }) => {
+  // The refusal branch first. \`completed\`, not failed: a row deleted between the enqueue and
+  // the run is not an error to retry five times — and the body says which of the two it was.
+  const trace = await runJobs(${name.camel}, { id, orgId });
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(trace.executions[0]?.result).toEqual({ skipped: true });
+  expect(Object.keys(trace.steps)).toEqual(['load']);
+});
+${shape.storesRow ? storedRowTest(name) : ''}`;
+
+const neutralBodyTest = (name: NameSet): string => `${HEADER(name)}
+import { expect, unitTest } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+
+unitTest('one run takes its one step, once, and completes', async ({ runJobs }) => {
+  const trace = await runJobs(${name.camel}, { id });
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(trace.executions[0]?.result).toEqual({ processed: true });
+  expect(Object.keys(trace.steps)).toEqual(['process']);
+  expect(trace.steps.process?.executions).toBe(1);
+});
+`;
+
+/** `<name>.test.ts` for a job: its body, in the shape the slice earns. */
+export const jobBodyTest = (name: NameSet, shape: JobBodyShape): string =>
+  shape.scoped ? scopedBodyTest(name, shape) : neutralBodyTest(name);
+
+/**
+ * `<name>.test.ts` for a task: firing it, which is the one thing its `enqueue` function is for.
+ * The payload it declares is run to completion by the same worker, so a payload the job's own
+ * input schema refuses fails here rather than at 03:00.
+ */
+export const taskBodyTest = (
+  name: NameSet,
+  jobName: NameSet,
+): string => `// ${name.camel}, fired: the job it queues and the payload it queues it with, run to completion by a
+// worker in this process. The schedule — the cron and its time zone — is the job suite's, next door.
+import { expect, unitTest } from '@ultimat3/testing';
+import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
+import { ${name.camel} } from './${name.kebab}';
+
+unitTest('firing it queues its one job, and that payload completes', async ({ runJobs }) => {
+  const queued = await ${name.camel}.enqueue();
+  const jobs = queued.map((result) => result.job);
+  expect(jobs).toEqual([${jobName.camel}.name]);
+  expect(await runJobs.depth(${jobName.camel})).toBe(1);
+  // A payload the job's input schema refuses fails the run, here rather than on the schedule.
+  const trace = await runJobs.drain();
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(await runJobs.depth(${jobName.camel})).toBe(0);
+});
+`;

package/src/templates/job.ts

@@ -5,9 +5,11 @@
 
 import { stripComments } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
+import { jobBodyTest, taskBodyTest } from './job-body-test';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceExports, sliceFoundation } from './slice-foundation';
+import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
+import { sliceExports, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
 import { wrapList } from './wrap';
 
 const jobSource = (
@@ -34,7 +36,7 @@ export const ${name.camel} = job({
     const row = await step.run('load', () => repo.byId(input.id));
     if (row === undefined) return { skipped: true };
     await step.run('process', async () => {
-      await repo.listByOrg(row.orgId, 1);
+      await repo.list(1);
     });
     return { skipped: false };
   },
@@ -43,7 +45,7 @@ export const ${name.camel} = job({
 
 /**
  * The other shape: this feature's own `entity.ts` names no tenant column (or names `'none'`), or
- * its `repo.ts` does not export the `byId`/`listByOrg` pair the tenant-scoped body above calls —
+ * its `repo.ts` does not export the `byId`/`list` pair the tenant-scoped body above calls —
  * checked by `isTenantScopedSlice` against what is actually on the app's disk, never assumed. The
  * body imports neither `../entity` nor `../repo`, so it compiles whether this feature has an
  * entity yet or has one with no tenant, and `tenant: 'none'` is stated rather than defaulted so a
@@ -63,7 +65,7 @@ export const ${name.camel} = job({
   // entity names none. \`tenant: 'none'\` STRIPS the org from the run rather than leaving one
   // behind, so a tenant-scoped read added later fails closed with X_TENANCY_ACTOR_ORG_REQUIRED
   // instead of reading whichever org the enqueuer happened to hold. Once this feature's entity
-  // declares \`tenant: 'orgId'\` and its repo exports \`byId\`/\`listByOrg\`, the next \`x g job\` in
+  // declares \`tenant: 'orgId'\` and its repo exports \`byId\`/\`list\`, the next \`x g job\` in
   // this slice scaffolds the tenant-scoped shape above instead.
   tenant: 'none',
   idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
@@ -283,7 +285,7 @@ export interface JobOptions extends FeatureTarget {
    * This feature's own `entity.ts` as it stands on disk, or absent when the feature has none yet.
    * Supplied by `run` for the same reason `ActionOptions.sliceErrors` is: whether the slice is
    * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
-   * `repo.byId`/`repo.listByOrg` calls into a feature whose repo never declared them —
+   * `repo.byId`/`repo.list` calls into a feature whose repo never declared them —
    * `x g task purgeOrphans --feature links` on a `links` slice with no `orgId` produced files that
    * did not compile.
    */
@@ -297,9 +299,9 @@ export interface JobOptions extends FeatureTarget {
  * NOT: only `x g entity` and `x g resource` create a feature's data, and counting absent as scoped
  * made `x g task nightly` lay down an `entity('nightlies', { title, price })` that the `drift` step
  * then demanded a migration for. One that exists is trusted: it declares
- * a real, non-`'none'` `tenant`, AND its `repo.ts` actually exports the `byId`/`listByOrg` pair the
+ * a real, non-`'none'` `tenant`, AND its `repo.ts` actually exports the `byId`/`list` pair the
  * tenant-scoped body calls. Both have to hold — an entity that still names `tenant: 'orgId'` after
- * an author trimmed `listByOrg` out of `repo.ts` (or never generated one) is not a slice this job
+ * an author trimmed `list` out of `repo.ts` (or never generated one) is not a slice this job
  * can read through either.
  */
 export function isTenantScopedSlice(
@@ -310,7 +312,7 @@ export function isTenantScopedSlice(
   const declaresTenant = /\btenant\s*:\s*'(?!none')[^']+'/.test(stripComments(sliceEntity));
   if (!declaresTenant) return false;
   if (sliceRepo === undefined) return true;
-  return sliceExports(sliceRepo, 'byId') && sliceExports(sliceRepo, 'listByOrg');
+  return sliceExports(sliceRepo, 'byId') && sliceExports(sliceRepo, 'list');
 }
 
 export function jobFiles(rawName: string, target: JobOptions): readonly GeneratedFile[] {
@@ -335,6 +337,16 @@ export function jobFiles(rawName: string, target: JobOptions): readonly Generate
       path: `${dir}/${name.kebab}.job.test.ts`,
       contents: scoped ? jobTest(name) : neutralJobTest(name),
     },
+    // And the plain `<name>.test.ts`: the BODY, on the `unit` step. The suite above pins what a
+    // queue guarantees; an app's coverage floor counts the unit suite alone (`job-body-test.ts`).
+    {
+      path: `${dir}/${name.kebab}.test.ts`,
+      contents: jobBodyTest(name, {
+        scoped,
+        storesRow: scoped && sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
+        dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
+      }),
+    },
   ];
 }
 
@@ -350,6 +362,9 @@ export function taskFiles(rawName: string, target: JobOptions): readonly Generat
     },
     // A task's test is a `jobTest` too — it drives a queue — so it takes the same suffix.
     { path: `${dir}/${name.kebab}.job.test.ts`, contents: taskTest(name, jobName) },
+    // The task FIRED, on the `unit` step: its `enqueue` function is otherwise run by nothing the
+    // coverage floor counts.
+    { path: `${dir}/${name.kebab}.test.ts`, contents: taskBodyTest(name, jobName) },
     ...jobFiles(`${rawName}-job`, target),
   ];
 }