@ultimat3/cli 19.4.0 → 20.0.0

package/src/templates/guard-animated-layout-property.ts

@@ -0,0 +1,269 @@
+// The `animated-layout-property` guard `x new` ships: only `transform` and `opacity` animate for
+// free. Everything else — a `top`, a `width`, a `margin`, a `box-shadow` — costs the browser a
+// layout or a paint on EVERY frame, on the same main thread the app's own JavaScript is on, and
+// feeds the layout-shift metric while it does it. `transition: all` is worse than any single one of
+// them: it animates properties nobody chose, including the ones that have not been written yet.
+
+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 = 'animated-layout-property';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// animated-layout-property: an animation moves \`transform\` and \`opacity\`, never the layout.
+// \`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}';
+
+/**
+ * What each layout property should have been, so the fix is an edit and not a category. A property
+ * with no obvious equivalent takes the default below rather than an invented one.
+ */
+const INSTEAD = new Map([
+  ['top', 'transform: translateY(…)'],
+  ['bottom', 'transform: translateY(…)'],
+  ['left', 'transform: translateX(…)'],
+  ['right', 'transform: translateX(…)'],
+  ['inset', 'transform: translate(…)'],
+  ['width', 'transform: scaleX(…)'],
+  ['height', 'transform: scaleY(…)'],
+  ['box-shadow', 'opacity on a shadow layer that is already painted'],
+]);
+
+/** A property whose change the browser cannot composite: it re-lays-out or re-paints the frame. */
+const isLayoutProperty = (property: string): boolean =>
+  INSTEAD.has(property) ||
+  property.startsWith('margin') ||
+  property.startsWith('padding') ||
+  /^(?:min|max)-(?:width|height)$/.test(property);
+
+/**
+ * A DECLARATION, never a whole line: a selector carries no colon, so \`.transition { … }\` is not a
+ * value and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ */
+const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+
+/** A CSS identifier that could name a property. \`200ms\`, \`0.2s\` and \`cubic-bezier(…)\` cannot. */
+const IDENTIFIER = /^-?[a-z][a-z-]*$/i;
+/**
+ * Identifiers that appear in a \`transition\` and are never the property being animated —
+ * \`none\` included, which is what makes the \`transition: none\` branch below load-bearing rather
+ * than decorative: without \`none\` here it reads as a property name, and with it the declaration
+ * that turns every transition OFF would be reported as one that animates everything.
+ */
+const TIMING = new Set([
+  'ease',
+  'ease-in',
+  'ease-out',
+  'ease-in-out',
+  'linear',
+  'none',
+  'step-start',
+  'step-end',
+  'normal',
+  'infinite',
+  'alternate',
+  'forwards',
+  'backwards',
+  'both',
+]);
+
+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));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Which \`@keyframes\` block an index sits in, so an animated property can be named with its rule. */
+function keyframeRanges(scss: string): ReadonlyMap<string, readonly [number, number]> {
+  const ranges = new Map<string, readonly [number, number]>();
+  for (const match of scss.matchAll(/@keyframes\\s+([\\w-]+)[^{]*\\{/g)) {
+    const from = match.index + match[0].length;
+    let depth = 0;
+    let to = scss.length;
+    for (let i = from; i < scss.length; i += 1) {
+      const ch = scss[i];
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        if (depth === 0) {
+          to = i;
+          break;
+        }
+        depth -= 1;
+      }
+    }
+    ranges.set(match[1] ?? 'the animation', [from, to]);
+  }
+  return ranges;
+}
+
+/**
+ * The property each comma-separated part of a \`transition\` names, or \`undefined\` where the part
+ * names none — which is not "nothing to animate": an omitted property IS \`all\`, so
+ * \`transition: 200ms ease\` animates every property this element will ever have.
+ */
+function transitionProperties(value: string): readonly (string | undefined)[] {
+  return value.split(',').map((part) => {
+    const tokens = part.trim().split(/\\s+/);
+    return tokens
+      .find((token) => IDENTIFIER.test(token) && !TIMING.has(token.toLowerCase()))
+      ?.toLowerCase();
+  });
+}
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function animatedLayoutProperties(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    const keyframes = keyframeRanges(scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = (match[1] ?? '').toLowerCase();
+      const value = (match[2] ?? '').trim();
+      const at = \`\${file.path}:\${lineOf(scss, match.index)}\`;
+      const animation = [...keyframes].find(
+        ([, [from, to]]) => match.index > from && match.index < to,
+      );
+      if (animation !== undefined) {
+        if (!isLayoutProperty(property)) continue;
+        findings.push(layoutFinding(file.path, at, property, \`@keyframes \${animation[0]}\`));
+        continue;
+      }
+      if (property !== 'transition' && property !== 'transition-property') continue;
+      // \`transition: none\` turns transitions OFF. It is the one value that names no property and
+      // animates nothing, so reading it as the implicit \`all\` below would report the opposite.
+      if (value.toLowerCase() === 'none') continue;
+      for (const animated of transitionProperties(value)) {
+        if (animated === undefined || animated === 'all') {
+          findings.push({
+            code: CODE,
+            cause: \`\${at} transitions every property of this element — \${animated === undefined ? \`\\\`\${property}: \${value}\\\` names none, and an omitted property is \\\`all\\\`\` : 'written out as \`all\`'} — so it animates properties nobody chose, the ones that cost a layout pass included, and no part of it can be composited\`,
+            fix: \`name the properties in \${at} — \\\`transition: transform tokens.duration('fast') tokens.easing('out')\\\` — then: x verify\`,
+            at: file.path,
+          });
+          continue;
+        }
+        if (!isLayoutProperty(animated)) continue;
+        findings.push(layoutFinding(file.path, at, animated, 'this transition'));
+      }
+    }
+  }
+  return findings;
+}
+
+function layoutFinding(path: string, at: string, property: string, where: string): Finding {
+  const instead = INSTEAD.get(property) ?? 'transform or opacity, which the compositor owns';
+  return {
+    code: CODE,
+    cause: \`\${at} animates \${property} in \${where} — only transform and opacity are compositor-only, so every frame of this costs a full layout or paint pass on the same main thread the app runs on, and a moving box feeds the layout-shift metric while it does it\`,
+    fix: \`animate \${instead} instead of \${property} at \${at}, then: x verify\`,
+    at: path,
+  };
+}
+
+export const guard: Guard = {
+  summary: 'an animation moves transform and opacity, never the layout',
+  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 animatedLayoutProperties(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 { animatedLayoutProperties } from './animated-layout-property';
+
+const sheet = (scss: string) => [{ path: 'apps/web/app/post/ui.module.scss', scss }];
+
+unitTest('transitioning a layout property is refused, and the fix names the equivalent', () => {
+  const findings = animatedLayoutProperties(sheet('.panel {\\n  transition: left 200ms ease;\\n}'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+  expect(findings[0]?.fix).toContain('translateX');
+});
+
+unitTest('transition: all is refused outright', () => {
+  const findings = animatedLayoutProperties(sheet('.panel { transition: all 200ms ease; }'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('every property');
+});
+
+// An omitted property IS \`all\` — the same defect, one word shorter, and the one an author does
+// not read as a choice.
+unitTest('a transition naming no property at all is the same rule', () => {
+  const findings = animatedLayoutProperties(sheet('.panel { transition: 200ms ease; }'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('an omitted property');
+});
+
+unitTest('a layout property inside @keyframes is animated too', () => {
+  const scss = '@keyframes slide {\\n  from { margin-left: 0; }\\n  to { margin-left: 40px; }\\n}';
+  const findings = animatedLayoutProperties(sheet(scss));
+  expect(findings).toHaveLength(2);
+  expect(findings[0]?.cause).toContain('@keyframes slide');
+});
+
+unitTest('transform and opacity are what this rule exists to leave alone', () => {
+  const scss = '.panel { transition: transform tokens.duration("fast"), opacity 120ms linear; }';
+  expect(animatedLayoutProperties(sheet(scss))).toEqual([]);
+  const frames = '@keyframes fade { from { opacity: 0; } to { opacity: 1; transform: none; } }';
+  expect(animatedLayoutProperties(sheet(frames))).toEqual([]);
+});
+
+// The one value that names no property and still animates nothing. Read as the implicit \`all\`
+// above, it would report the declaration that turns the whole thing off.
+unitTest('transition: none turns transitions off and is not one', () => {
+  expect(animatedLayoutProperties(sheet('.panel { transition: none; }'))).toEqual([]);
+});
+
+unitTest('a plain layout declaration outside an animation is just layout', () => {
+  expect(animatedLayoutProperties(sheet('.panel { margin-left: 40px; width: 100%; }'))).toEqual([]);
+});
+
+unitTest('a commented-out transition is a note, not a declaration', () => {
+  expect(
+    animatedLayoutProperties(sheet('// transition: all 200ms;\\n.panel { padding: 0; }')),
+  ).toEqual([]);
+});
+`;
+
+/** `guards/animated-layout-property.ts` and its test. The directory is the registration. */
+export const animatedLayoutPropertyGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/animated-layout-property.ts', contents: source() },
+  { path: 'guards/animated-layout-property.test.ts', contents: test() },
+];

package/src/templates/guard-focus-visible.ts

@@ -0,0 +1,240 @@
+// The `focus-visible` guard `x new` ships: a stylesheet never takes the focus ring away and leaves
+// nothing in its place. `outline: none` is the single most-copied line on the web and it deletes
+// the only thing telling a keyboard user where they are — WCAG 2.2 SC 2.4.11 and 2.4.13 ask for an
+// indicator at least 2px around the control at 3:1 against what is behind it. Nothing in the gate
+// could see it: `x verify`'s `seo` and `i18n` steps read pages, and lint reads TypeScript.
+
+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 = 'focus-visible';
+const CODE = guardCode(NAME);
+
+const source = (): string => `// focus-visible: the focus ring is replaced, never only removed.
+// \`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 DECLARATION, never a whole line: a selector carries no colon, so \`.outline { … }\` is not a
+ * value and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ */
+const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+
+/** The three spellings that take the ring away. \`outline-offset\` moves it and is not one. */
+const REMOVES = new Set(['outline', 'outline-style', 'outline-width']);
+const NOTHING = /^(?:none|0(?:px|em|rem)?)$/i;
+
+/**
+ * What counts as painting one back, and its shape is load-bearing twice over. The lookahead reads
+ * the WHOLE value, not its first token: anchored on a prefix, \`box-shadow: 0 0 0 2px …\` — the
+ * canonical focus ring — read as the removal spelled again. And it sits directly after the \`:\`
+ * rather than after the space that follows it, because a \`\\s*\` OUTSIDE a negative lookahead
+ * backtracks to zero width and hands the lookahead a space to fail against: measured,
+ * \`outline: none\` then counted as an indicator and every removal in the tree read as replaced.
+ */
+const INDICATOR =
+  /(?<![\\w-])(?:box-shadow|outline)\\s*:(?!\\s*(?:none|0(?:px|em|rem)?)\\s*[;}])\\s*[^;{}]+/;
+const FOCUS_VISIBLE = /:focus-visible\\b/;
+/** \`@include tokens.focus-ring\` emits the whole rule, and no text scan can see inside a mixin. */
+const FOCUS_MIXIN = /@include\\s+[\\w.-]*focus[\\w-]*/i;
+/**
+ * \`&:focus:not(:focus-visible) { outline: none }\` is the CORRECT idiom, not the defect: it removes
+ * the ring for a mouse press and leaves the keyboard one alone. Reported, it would teach an author
+ * to switch this guard off — which is how a rule stops existing.
+ */
+const MOUSE_ONLY = /:not\\(\\s*:focus-visible\\s*\\)/;
+
+/**
+ * How far past a rule a replacement still counts as beside it. A sibling \`:focus-visible\` rule is
+ * the second of the two shapes authors write; further than this it is a different component, and a
+ * rule that searched the whole file would be satisfied by one focus style anywhere in it.
+ */
+const ADJACENT_CHARS = 600;
+
+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));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/**
+ * The innermost \`{ … }\` the index sits inside — back to the nearest unmatched \`{\`, forward to the
+ * \`}\` that closes it. Nested rules are INSIDE the answer, which is what makes the common Sass
+ * shape (\`.btn { outline: none; &:focus-visible { box-shadow: … } }\`) read as one scope.
+ */
+function blockAround(
+  text: string,
+  index: number,
+): { readonly start: number; readonly end: number } {
+  let depth = 0;
+  let start = 0;
+  for (let i = index; i >= 0; i -= 1) {
+    const ch = text[i];
+    if (ch === '}') depth += 1;
+    else if (ch === '{') {
+      if (depth === 0) {
+        start = i;
+        break;
+      }
+      depth -= 1;
+    }
+  }
+  depth = 0;
+  let end = text.length;
+  for (let i = start + 1; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+      depth -= 1;
+    }
+  }
+  return { start, end };
+}
+
+/** The selector this block belongs to: back to whatever ended the statement before it. */
+function selectorBefore(text: string, start: number): string {
+  let from = 0;
+  for (let i = start - 1; i >= 0; i -= 1) {
+    const ch = text[i];
+    if (ch === '{' || ch === '}' || ch === ';') {
+      from = i + 1;
+      break;
+    }
+  }
+  return text.slice(from, start);
+}
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function unreplacedFocusRings(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] ?? '').toLowerCase();
+      const value = (match[2] ?? '').trim();
+      if (!REMOVES.has(property) || !NOTHING.test(value)) continue;
+      const block = blockAround(scss, match.index);
+      const selector = selectorBefore(scss, block.start);
+      if (MOUSE_ONLY.test(selector)) continue;
+      // The rule itself, its own selector, and what sits directly after it — the two shapes an
+      // author writes a replacement in, and nothing wider, so a finding never has to be argued with.
+      const scope =
+        selector + scss.slice(block.start, Math.min(block.end + ADJACENT_CHARS, scss.length));
+      if (FOCUS_MIXIN.test(scope)) continue;
+      if (FOCUS_VISIBLE.test(scope) && INDICATOR.test(scope)) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(scss, match.index)} removes the focus ring with \${property}: \${value} and nothing in the rule or beside it paints one back — a keyboard user loses every trace of where they are, and WCAG 2.2 asks for an indicator at least 2px around the control at 3:1 against what is behind it\`,
+        fix: \`add \\\`@include tokens.focus-ring;\\\` to the rule at \${file.path}:\${lineOf(scss, match.index)}, or a sibling \\\`:focus-visible\\\` rule with a box-shadow — which follows the border radius where an outline does not — then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a stylesheet replaces the focus ring, never only removes it',
+  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 unreplacedFocusRings(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 { unreplacedFocusRings } from './focus-visible';
+
+const sheet = (scss: string) => [{ path: 'apps/web/app/post/ui.module.scss', scss }];
+
+unitTest('outline: none with nothing in its place is refused', () => {
+  const findings = unreplacedFocusRings(sheet('.trigger {\\n  outline: none;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+  expect(findings[0]?.fix).toContain('focus-ring');
+});
+
+unitTest('outline: 0 is the same removal spelled differently', () => {
+  expect(unreplacedFocusRings(sheet('.trigger { outline: 0; }'))).toHaveLength(1);
+  expect(unreplacedFocusRings(sheet('.trigger { outline-style: none; }'))).toHaveLength(1);
+});
+
+unitTest('a nested :focus-visible that paints one back satisfies it', () => {
+  const scss =
+    '.trigger {\\n  outline: none;\\n  &:focus-visible { box-shadow: 0 0 0 2px tokens.role("accent"); }\\n}';
+  expect(unreplacedFocusRings(sheet(scss))).toEqual([]);
+});
+
+unitTest('a sibling :focus-visible rule beside it counts too', () => {
+  const scss =
+    '.trigger { outline: none; }\\n.trigger:focus-visible { outline: 2px solid tokens.role("accent"); }';
+  expect(unreplacedFocusRings(sheet(scss))).toEqual([]);
+});
+
+// The idiom this rule must never report: removing the ring for a MOUSE press and leaving the
+// keyboard one alone is the correct thing to write, and reporting it teaches an author to delete
+// the guard.
+unitTest(':focus:not(:focus-visible) is the correct removal, not the defect', () => {
+  expect(
+    unreplacedFocusRings(sheet('.trigger:focus:not(:focus-visible) { outline: none; }')),
+  ).toEqual([]);
+});
+
+unitTest('a focus mixin emits the rule no text scan can read into', () => {
+  const scss = '.trigger {\\n  @include tokens.focus-ring;\\n  outline: none;\\n}';
+  expect(unreplacedFocusRings(sheet(scss))).toEqual([]);
+});
+
+unitTest('outline-offset moves the ring and does not remove it', () => {
+  expect(unreplacedFocusRings(sheet('.trigger { outline-offset: 0; }'))).toEqual([]);
+});
+
+unitTest('a commented-out removal is a note, not a declaration', () => {
+  expect(unreplacedFocusRings(sheet('// outline: none;\\n.trigger { padding: 0; }'))).toEqual([]);
+});
+`;
+
+/** `guards/focus-visible.ts` and its test. The directory is the registration. */
+export const focusVisibleGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/focus-visible.ts', contents: source() },
+  { path: 'guards/focus-visible.test.ts', contents: test() },
+];