@ultimat3/cli 22.14.0 → 23.0.0

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

@@ -0,0 +1,213 @@
+// The `raw-motion` guard `x new` ships: a duration and an easing curve are `tokens.duration()` and
+// `tokens.easing()`. A literal `300ms` beside the scale's `220ms` is two tempos in one app, and
+// nothing but this reads a stylesheet for it.
+
+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-motion';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-motion: every duration and curve comes off the motion scale, so the app moves at one tempo.
+// \`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.
+//
+// A keyword is not a literal: \`linear\`, \`ease\`, \`infinite\` and \`0s\` are never reported, and a
+// multiple of a token is still the token — \`calc(#{tokens.duration(slower)} * 2)\`.
+
+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}';
+
+/** \`@ultimat3/ui/tokens\`' duration scale, in ms. */
+export const DURATIONS: readonly (readonly [string, number])[] = [
+  ['instant', 0],
+  ['fast', 120],
+  ['base', 220],
+  ['slow', 400],
+  ['slower', 640],
+];
+/** \`@ultimat3/ui/tokens\`' easing curves, as the control points each one is. */
+export const EASINGS: Readonly<Record<string, string>> = {
+  '0.16,1,0.3,1': 'out',
+  '0.5,0,0.75,0': 'in',
+  '0.65,0,0.35,1': 'in-out',
+  '0.34,1.56,0.64,1': 'spring',
+};
+
+export interface StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+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 = (scss: string): string =>
+  scss.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, blank).replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, blank);
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** The \`as <name>\` the token entry point is used under in this sheet; \`tokens\` when it is not. */
+const namespaceOf = (scss: string): string =>
+  /@use\\s+['"][^'"]*tokens[^'"]*['"]\\s+as\\s+([\\w-]+)/.exec(scss)?.[1] ?? 'tokens';
+
+/** A declaration; a Sass \`#{…}\` interpolation is a value that carries braces. */
+const DECLARATION = /(?<![\\w$-])([\\w-]+)\\s*:\\s*((?:#\\{[^}]*\\}|[^;{}])+)/g;
+const MOTION_PROPERTY = /^(?:transition|animation)(?:-|$)/;
+/** A token read, with its argument list: \`tokens.duration(fast)\`, \`var(--duration-fast)\`. */
+const TOKEN_CALL = /(?<![\\w-])(?:var|(?:[\\w-]+\\.)[\\w-]+|duration|easing)\\([^()]*\\)/g;
+const TIME = /(?<![\\w.#-])(\\d*\\.?\\d+)(ms|s)\\b/g;
+const CURVE = /cubic-bezier\\(([^)]*)\\)/g;
+
+/** The step a duration means: exact where it is one, the nearest where it is not. */
+const durationFor = (ms: number): string => {
+  let best: readonly [string, number] | undefined;
+  for (const step of DURATIONS) {
+    // \`instant\` is no motion at all; a time someone wrote is never repaired to nothing.
+    if (step[1] === 0) continue;
+    if (best === undefined || Math.abs(step[1] - ms) < Math.abs(best[1] - ms)) best = step;
+  }
+  return best?.[0] ?? 'base';
+};
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawMotion(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    const ns = namespaceOf(file.scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = match[1] ?? '';
+      if (!MOTION_PROPERTY.test(property)) continue;
+      const value = (match[2] ?? '').trim().replaceAll(/\\s+/g, ' ');
+      const read = value.replaceAll(TOKEN_CALL, (call) => ' '.repeat(call.length));
+      const literals: string[] = [];
+      let written = '';
+      let cursor = 0;
+      const rewrite = (index: number, length: number, replacement: string): void => {
+        written += value.slice(cursor, index) + replacement;
+        cursor = index + length;
+      };
+      // Offsets in \`read\` are offsets in \`value\`: a token call is blanked, never removed.
+      const hits = [
+        ...[...read.matchAll(CURVE)].map((curve) => ({
+          index: curve.index,
+          text: curve[0],
+          token: \`\${ns}.easing(\${EASINGS[(curve[1] ?? '').replaceAll(/\\s+/g, '')] ?? 'out'})\`,
+        })),
+        ...[...read.replaceAll(CURVE, (curve) => ' '.repeat(curve.length)).matchAll(TIME)]
+          .filter((time) => Number(time[1]) !== 0)
+          .map((time) => ({
+            index: time.index,
+            text: time[0],
+            token: \`\${ns}.duration(\${durationFor(Number(time[1]) * (time[2] === 's' ? 1000 : 1))})\`,
+          })),
+      ].sort((a, b) => a.index - b.index);
+      for (const hit of hits) {
+        literals.push(hit.text);
+        rewrite(hit.index, hit.text.length, hit.token);
+      }
+      if (literals.length === 0) continue;
+      written += value.slice(cursor);
+      const line = lineOf(scss, match.index);
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} writes \\\`\${property}: \${value}\\\` — \${literals.join(' and ')} off the motion scale, a tempo of this file's own\`,
+        fix: \`\${property}: \${written} — at \${file.path}:\${line} (durations: \${DURATIONS.map(([name]) => name).join(' ')}; a longer one is calc(#{\${ns}.duration(slower)} * 2)), then: x verify\`,
+        at: \`\${file.path}:\${line}\`,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a duration and an easing curve come off the motion scale, never a literal',
+  async check(_root, sources) {
+    const sheets = await sources.files('{apps,packages}/**/*.scss');
+    return rawMotion(sheets.map((file) => ({ path: file.path, scss: 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 { rawMotion } from './raw-motion';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+const fixes = (scss: string) => rawMotion(sheet(scss)).map((finding) => finding.fix);
+
+unitTest('a duration literal is refused, and the fix is the declaration to write', () => {
+  const findings = rawMotion(sheet('.a {\\n  transition: opacity 120ms ease;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/site/page.module.scss:2');
+  expect(findings[0]?.fix).toStartWith('transition: opacity tokens.duration(fast) ease — ');
+});
+
+unitTest('seconds are read as milliseconds, and a time off the scale gets the nearest step', () => {
+  expect(fixes('.a { animation-duration: 0.4s; }')[0]).toStartWith(
+    'animation-duration: tokens.duration(slow) — ',
+  );
+  expect(fixes('.a { transition-duration: 300ms; }')[0]).toStartWith(
+    'transition-duration: tokens.duration(base) — ',
+  );
+  expect(fixes('.a { animation: spin 2.4s linear infinite; }')[0]).toStartWith(
+    'animation: spin tokens.duration(slower) linear infinite — ',
+  );
+});
+
+unitTest('a cubic-bezier is refused, and one that IS a token is named', () => {
+  expect(
+    fixes('.a { transition: opacity tokens.duration(fast) cubic-bezier(0.16, 1, 0.3, 1); }')[0],
+  ).toStartWith('transition: opacity tokens.duration(fast) tokens.easing(out) — ');
+  expect(
+    rawMotion(sheet('.a { animation-timing-function: cubic-bezier(0.2, 0, 0, 1); }')),
+  ).toHaveLength(1);
+});
+
+unitTest('one declaration is one finding, with every literal in it rewritten', () => {
+  const findings = rawMotion(
+    sheet('.a { transition: color 220ms cubic-bezier(0.65, 0, 0.35, 1), opacity 640ms ease; }'),
+  );
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.fix).toStartWith(
+    'transition: color tokens.duration(base) tokens.easing(in-out), opacity tokens.duration(slower) ease — ',
+  );
+});
+
+unitTest('the fix speaks the namespace the sheet uses the tokens under', () => {
+  const scss = "@use '../shared/tokens' as t;\\n.a { transition-duration: 120ms; }";
+  expect(fixes(scss)[0]).toStartWith('transition-duration: t.duration(fast) — ');
+});
+
+// The legitimate lookalikes — the reason the rule can stay switched on.
+unitTest('a token, a keyword, a zero and a multiple of a token are silent', () => {
+  const silent = [
+    '.a { transition: opacity tokens.duration(fast) tokens.easing(out); }',
+    '.a { transition: opacity var(--duration-fast) var(--easing-out); }',
+    '.a { animation: spin calc(#{tokens.duration(slower)} * 2) linear infinite; }',
+    '.a { transition: none; }',
+    '.a { transition-delay: 0s; animation-delay: 0ms; }',
+    '.a { animation-iteration-count: 3; }',
+    '// transition: opacity 120ms;\\n.a { transition: none; }',
+    '.a { width: 100ms; }',
+    '$tempo: 120ms;',
+  ];
+  for (const scss of silent) expect(rawMotion(sheet(scss))).toEqual([]);
+});
+`;
+
+/** `guards/raw-motion.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawMotionGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];

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

@@ -0,0 +1,187 @@
+// The `raw-shadow` guard `x new` ships: elevation is `tokens.shadow()` or `@include tokens.surface`.
+// The shadow scale is THEMED — dark gets deeper, higher-alpha shadows — so a hand-written offset
+// and blur is the one elevation that does not change when the theme does.
+
+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-shadow';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-shadow: elevation comes off the shadow scale, so dark theme deepens it instead of losing it.
+// \`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.
+//
+// A shadow is RAW when a length in it was written by hand. \`tokens.shadow('md')\`, \`none\`, a
+// hairline ring (\`inset 0 0 0 1px …\`) and a line drawn from tokens (\`inset 0 #{tokens.stroke(thick)} …\`)
+// carry no such length and are never reported.
+
+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 StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+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 = (scss: string): string =>
+  scss.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, blank).replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, blank);
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** The \`as <name>\` the token entry point is used under in this sheet; \`tokens\` when it is not. */
+const namespaceOf = (scss: string): string =>
+  /@use\\s+['"][^'"]*tokens[^'"]*['"]\\s+as\\s+([\\w-]+)/.exec(scss)?.[1] ?? 'tokens';
+
+/** A declaration; a Sass \`#{…}\` interpolation is a value that carries braces. */
+const DECLARATION = /(?<![\\w$-])([\\w-]+)\\s*:\\s*((?:#\\{[^}]*\\}|[^;{}])+)/g;
+const SHADOW_PROPERTY = /^(?:box-shadow|text-shadow)$/;
+
+/** The index just past the \`)\` that closes the \`(\` at \`open\`, or \`undefined\` when none does. */
+const closeOf = (text: string, open: number): number | undefined => {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const character = text.charAt(index);
+    if (character === '(') depth += 1;
+    else if (character === ')') {
+      depth -= 1;
+      if (depth === 0) return index + 1;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * A token read — \`var(--shadow-md)\`, a module call (\`tokens.space(2)\`, \`t.rem(-4px)\`) or the bare
+ * \`shadow(md)\` — with its whole argument list, so the px handed to \`rem()\` is not read as raw.
+ */
+const TOKEN_CALL = /(?<![\\w-])(?:var|(?:[\\w-]+\\.)[\\w-]+|shadow|rem|space|stroke)\\(/g;
+
+const withoutTokens = (value: string): string => {
+  let out = value;
+  for (const match of value.matchAll(TOKEN_CALL)) {
+    const open = match.index + match[0].length - 1;
+    const close = closeOf(out, open);
+    if (close !== undefined) {
+      out = out.slice(0, match.index) + blank(out.slice(match.index, close)) + out.slice(close);
+    }
+  }
+  return out;
+};
+
+/** A hand-written length: any unit, any sign — except \`0\` and the \`1px\` of a hairline ring. */
+const LENGTH = /(?<![\\w.#-])-?(\\d*\\.?\\d+)(px|rem|em|vh|vw|%)/g;
+
+const rawLength = (value: string): string | undefined => {
+  for (const match of withoutTokens(value).matchAll(LENGTH)) {
+    const amount = Number(match[1]);
+    if (amount === 0 || (amount === 1 && match[2] === 'px')) continue;
+    return match[0];
+  }
+  return undefined;
+};
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawShadows(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    const ns = namespaceOf(file.scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = match[1] ?? '';
+      const value = (match[2] ?? '').trim().replaceAll(/\\s+/g, ' ');
+      const dropShadow = /drop-shadow\\(/.test(value);
+      if (!SHADOW_PROPERTY.test(property) && !dropShadow) continue;
+      const literal = rawLength(value);
+      if (literal === undefined) continue;
+      const line = lineOf(scss, match.index);
+      // An inset shadow is a LINE drawn inside the box, not elevation: its repair is the stroke
+      // scale, and telling its author to reach for \`shadow()\` would be telling them to delete it.
+      const written = /\\binset\\b/.test(value)
+        ? \`write each length of this inset line as \${ns}.stroke(thick), \${ns}.space(<step>) or \${ns}.rem(<px>)\`
+        : \`\${property}: \${ns}.shadow('sm') — or 'xs' 'md' 'lg' 'xl'; a card or popover takes @include \${ns}.surface\`;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} writes \\\`\${property}: \${value}\\\` — a shadow with the hand-written length \${literal}, which no theme restates: dark mode keeps the light theme's elevation\`,
+        fix: \`\${written} — at \${file.path}:\${line}, then: x verify\`,
+        at: \`\${file.path}:\${line}\`,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a shadow comes off the shadow scale, never a hand-written offset and blur',
+  async check(_root, sources) {
+    const sheets = await sources.files('{apps,packages}/**/*.scss');
+    return rawShadows(sheets.map((file) => ({ path: file.path, scss: 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 { rawShadows } from './raw-shadow';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+
+unitTest('a hand-written box-shadow is refused, and the fix is the declaration to write', () => {
+  const findings = rawShadows(sheet('.card {\\n  box-shadow: 0 4px 12px rgb(0 0 0 / 0.2);\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/site/page.module.scss:2');
+  expect(findings[0]?.cause).toContain('4px');
+  expect(findings[0]?.fix).toStartWith("box-shadow: tokens.shadow('sm') — ");
+});
+
+unitTest('text-shadow, a rem length and a drop-shadow filter are the same rule', () => {
+  expect(rawShadows(sheet('.a { text-shadow: 0 0.25rem 0 currentcolor; }'))).toHaveLength(1);
+  expect(rawShadows(sheet('.a { filter: drop-shadow(0 2px 4px currentcolor); }'))).toHaveLength(1);
+});
+
+unitTest('an inset line is repaired with the stroke scale, not the elevation scale', () => {
+  const findings = rawShadows(sheet('.tab { box-shadow: inset 0 -2px 0 0 currentcolor; }'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.fix).toContain('tokens.stroke(thick)');
+  expect(findings[0]?.fix).not.toContain('tokens.shadow(');
+});
+
+unitTest('the fix speaks the namespace the sheet uses the tokens under', () => {
+  const scss = "@use '../shared/tokens' as t;\\n.a { box-shadow: 0 2px 6px black; }";
+  expect(rawShadows(sheet(scss))[0]?.fix).toStartWith("box-shadow: t.shadow('sm') — ");
+});
+
+// The legitimate lookalikes — the reason the rule can stay switched on.
+unitTest('a token, none, a hairline ring and a line drawn from tokens are silent', () => {
+  const silent = [
+    ".a { box-shadow: tokens.shadow('md'); }",
+    '.a { box-shadow: var(--shadow-sm); }',
+    '.a { box-shadow: none; }',
+    ".a { box-shadow: inset 0 0 0 1px tokens.role('accent', 0.24); }",
+    '.a { box-shadow: inset 0 calc(-1 * #{tokens.stroke(thick)}) 0 0 currentcolor; }',
+    '.a { box-shadow: inset #{tokens.rem(-4.5px)} #{tokens.rem(-3px)} 0 0 currentcolor; }',
+    ".a { box-shadow: tokens.shadow('sm'), inset 0 0 0 1px currentcolor; }",
+    '// box-shadow: 0 4px 12px black;\\n.a { box-shadow: none; }',
+    '.a { padding: 4px 12px; }',
+  ];
+  for (const scss of silent) expect(rawShadows(sheet(scss))).toEqual([]);
+});
+`;
+
+/** `guards/raw-shadow.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawShadowGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];

package/src/templates/guard-raw-z-index.ts

@@ -0,0 +1,166 @@
+// The `raw-z-index` guard `x new` ships: a `z-index` is a named layer of `@ultimat3/ui/tokens`' z
+// ladder. `_z.scss` has always said "a magic number in a component is a review failure"; this is
+// that sentence as a build error.
+
+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-z-index';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-z-index: a layer is a name on the one z ladder, so "above the dialog" means one thing.
+// \`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.
+//
+// The NEGATIVE of a named layer is still a named layer — \`calc(-1 * #{tokens.z(raised)})\` puts a
+// decoration behind its own stacking context — so a \`-1 *\` beside a token is not a number.
+
+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}';
+
+/** \`@ultimat3/ui/tokens\`' z ladder. */
+export const LAYERS: readonly (readonly [string, number])[] = [
+  ['base', 0],
+  ['raised', 10],
+  ['sticky', 100],
+  ['dropdown', 200],
+  ['drawer', 300],
+  ['dialog', 400],
+  ['popover', 500],
+  ['tooltip', 600],
+  ['toast', 700],
+  ['skip-nav', 800],
+];
+
+export interface StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+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 = (scss: string): string =>
+  scss.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, blank).replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, blank);
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** The \`as <name>\` the token entry point is used under in this sheet; \`tokens\` when it is not. */
+const namespaceOf = (scss: string): string =>
+  /@use\\s+['"][^'"]*tokens[^'"]*['"]\\s+as\\s+([\\w-]+)/.exec(scss)?.[1] ?? 'tokens';
+
+const Z_INDEX = /(?<![\\w$-])z-index\\s*:\\s*((?:#\\{[^}]*\\}|[^;{}])+)/g;
+/** A token read: \`tokens.z(dialog)\`, \`z('dialog')\`, \`var(--z-dialog)\` — and the negation of one. */
+const TOKEN = /(?:[\\w-]+\\.)?z\\([^)]*\\)|var\\(\\s*--z-[\\w-]+\\s*\\)|-1\\s*\\*|\\*\\s*-1/g;
+
+/** The nearest layer to a number. Never \`base\` for a non-zero one: \`-0\` is not behind anything. */
+const layerFor = (value: number): string => {
+  let best: readonly [string, number] | undefined;
+  for (const layer of LAYERS) {
+    if (value !== 0 && layer[1] === 0) continue;
+    if (
+      best === undefined ||
+      Math.abs(layer[1] - Math.abs(value)) < Math.abs(best[1] - Math.abs(value))
+    ) {
+      best = layer;
+    }
+  }
+  return best?.[0] ?? 'raised';
+};
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawZIndexes(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    const ns = namespaceOf(file.scss);
+    for (const match of scss.matchAll(Z_INDEX)) {
+      const value = (match[1] ?? '').trim();
+      const literal = /-?\\d+/.exec(value.replaceAll(TOKEN, ' '))?.[0];
+      if (literal === undefined) continue;
+      const line = lineOf(scss, match.index);
+      const layer = \`\${ns}.z(\${layerFor(Number(literal))})\`;
+      const written = Number(literal) < 0 ? \`calc(-1 * #{\${layer}})\` : layer;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} writes \\\`z-index: \${value}\\\` — a number only this file knows, on no ladder another layer can be placed against\`,
+        fix: \`z-index: \${written} — at \${file.path}:\${line} (layers: \${LAYERS.map(([name]) => name).join(' ')}), then: x verify\`,
+        at: \`\${file.path}:\${line}\`,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a z-index is a named layer, never a number',
+  async check(_root, sources) {
+    const sheets = await sources.files('{apps,packages}/**/*.scss');
+    return rawZIndexes(sheets.map((file) => ({ path: file.path, scss: 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 { rawZIndexes } from './raw-z-index';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+const fixes = (scss: string) => rawZIndexes(sheet(scss)).map((finding) => finding.fix);
+
+unitTest('a numeric z-index is refused, and the fix is the layer it means', () => {
+  const findings = rawZIndexes(sheet('.menu {\\n  z-index: 200;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe('apps/web/site/page.module.scss:2');
+  expect(findings[0]?.fix).toStartWith('z-index: tokens.z(dropdown) — ');
+});
+
+unitTest('a number off the ladder gets the nearest layer', () => {
+  expect(fixes('.a { z-index: 9999; }')[0]).toStartWith('z-index: tokens.z(skip-nav) — ');
+  expect(fixes('.a { z-index: 1; }')[0]).toStartWith('z-index: tokens.z(raised) — ');
+  expect(fixes('.a { z-index: 0; }')[0]).toStartWith('z-index: tokens.z(base) — ');
+});
+
+unitTest('a negative number is the negation of a layer, never of base', () => {
+  expect(fixes('.a { z-index: -1; }')[0]).toStartWith('z-index: calc(-1 * #{tokens.z(raised)}) — ');
+});
+
+unitTest('a number beside a token is still a number', () => {
+  expect(rawZIndexes(sheet('.a { z-index: calc(#{tokens.z(dialog)} + 1); }'))).toHaveLength(1);
+});
+
+unitTest('the fix speaks the namespace the sheet uses the tokens under', () => {
+  const scss = "@use '../shared/tokens' as t;\\n.a { z-index: 400; }";
+  expect(fixes(scss)[0]).toStartWith('z-index: t.z(dialog) — ');
+});
+
+// The legitimate lookalikes — the reason the rule can stay switched on.
+unitTest('a token, its negation and a keyword are silent', () => {
+  const silent = [
+    '.a { z-index: tokens.z(dialog); }',
+    ".a { z-index: tokens.z('skip-nav'); }",
+    '.a { z-index: var(--z-toast); }',
+    '.a { z-index: calc(-1 * #{tokens.z(raised)}); }',
+    '.a { z-index: auto; }',
+    '.a { z-index: inherit; }',
+    '// z-index: 5;\\n.a { z-index: auto; }',
+    '$z-index: 5;',
+  ];
+  for (const scss of silent) expect(rawZIndexes(sheet(scss))).toEqual([]);
+});
+`;
+
+/** `guards/raw-z-index.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawZIndexGuardFiles = (): readonly GeneratedFile[] => [
+  { path: `guards/${NAME}.ts`, contents: source() },
+  { path: `guards/${NAME}.test.ts`, contents: test() },
+];