@ultimat3/cli 19.4.0 → 20.0.0

package/src/templates/guard-image-dimensions.ts

@@ -0,0 +1,225 @@
+// The `image-dimensions` guard `x new` ships: an image reserves its box before its bytes arrive.
+// An unsized `<img>` is the largest single contributor to Cumulative Layout Shift — the page reflows
+// under the reader's finger the moment the bytes land — and the second half is its mirror image: a
+// `loading="lazy"` on the image the page is judged by is a deliberate delay on the one paint the
+// metric measures. Both are decidable from the attributes and nothing in the gate could see either.
+
+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 = 'image-dimensions';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// image-dimensions: an image reserves its box before its bytes arrive.
+// \`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}';
+
+/** The raw element and the framework's wrapper. A background-image reserves nothing and is not one. */
+const IMAGES = new Set(['img', 'Image']);
+
+/** \`(?<![\\w-])\` on every one: \`maxWidth\` is not \`width\`, and \`data-loading\` is not \`loading\`. */
+const WIDTH = /(?<![\\w-])width\\s*=/;
+const HEIGHT = /(?<![\\w-])height\\s*=/;
+const ASPECT = /aspect-ratio/i;
+const LAZY = /(?<![\\w-])loading\\s*=\\s*['"{]?\\s*['"]?lazy/i;
+/** A bare JSX boolean (\`priority\`), \`priority={true}\`, or the HTML attribute spelled either way. */
+const PRIORITY = /(?<![\\w-])(priority|fetch[Pp]riority\\s*=\\s*['"{]?\\s*['"]?high)/;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+interface Tag {
+  readonly name: string;
+  readonly attrs: string;
+  readonly index: number;
+}
+
+/** 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;
+
+const NAME_AT = /^([A-Za-z][\\w.-]*)/;
+
+/**
+ * Every opening tag, with its attribute text. The tag ends at the first \`>\` OUTSIDE braces and
+ * quotes: \`srcset={widths.map((w) => …)}\` holds a \`>\` that closes nothing, so a pattern reading to
+ * the next \`>\` would cut the element in half and read half an attribute list as the whole one.
+ *
+ * The scanner is spelled out again here rather than shared, and that is the mechanism's doing:
+ * every file in \`guards/\` is a guard, so a helper module beside this one would be discovered and
+ * refused as a guard with no rule (\`X_GUARD_INVALID\`). One file per rule, deletable on its own.
+ */
+function openingTags(text: string): readonly Tag[] {
+  const tags: Tag[] = [];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== '<') continue;
+    const name = NAME_AT.exec(text.slice(i + 1, i + 64))?.[1];
+    if (name === undefined) continue;
+    const from = i + 1 + name.length;
+    let depth = 0;
+    let quote = '';
+    let end = from;
+    for (; end < text.length; end += 1) {
+      const ch = text[end];
+      if (quote !== '') {
+        if (ch === quote) quote = '';
+        continue;
+      }
+      if (ch === '"' || ch === "'" || ch === '\`') quote = ch;
+      else if (ch === '{') depth += 1;
+      else if (ch === '}') depth -= 1;
+      else if (depth === 0 && (ch === '>' || ch === '<')) break;
+    }
+    tags.push({ name, attrs: text.slice(from, end), index: i });
+    i = from - 1;
+  }
+  return tags;
+}
+
+/**
+ * \`<template>…</template>\` holds markup the browser never lays out, so nothing inside one can
+ * shift anything. Reported, it would be a finding an author cannot act on.
+ */
+function templateRanges(text: string): readonly (readonly [number, number])[] {
+  const ranges: (readonly [number, number])[] = [];
+  for (const match of text.matchAll(/<template\\b[\\s\\S]*?<\\/template>/gi)) {
+    ranges.push([match.index, match.index + match[0].length]);
+  }
+  return ranges;
+}
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function unsizedImages(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    const inert = templateRanges(text);
+    for (const tag of openingTags(text)) {
+      if (!IMAGES.has(tag.name)) continue;
+      if (inert.some(([from, to]) => tag.index > from && tag.index < to)) continue;
+      const at = \`\${file.path}:\${lineOf(text, tag.index)}\`;
+      if (!ASPECT.test(tag.attrs) && !(WIDTH.test(tag.attrs) && HEIGHT.test(tag.attrs))) {
+        findings.push({
+          code: CODE,
+          cause: \`\${at} renders <\${tag.name}> with no width and height pair and no aspect-ratio — the browser reserves no box for it, so every element under it jumps the moment the bytes land\`,
+          fix: \`add width and height to the <\${tag.name}> at \${at} — the intrinsic pixel size, since CSS still decides what it is drawn at — or an aspect-ratio, then: x verify\`,
+          at: file.path,
+        });
+      }
+      // A second finding on the same tag, deliberately: it is a different mistake with a different
+      // edit, and folding the two would hand the reader one of the repairs it needs.
+      if (!LAZY.test(tag.attrs) || !PRIORITY.test(tag.attrs)) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} marks <\${tag.name}> as the priority image AND loading="lazy" — a lazy image is fetched after layout, and this is the one the page's largest paint is measured on, so the attribute delays the metric it is the subject of\`,
+        fix: \`delete loading="lazy" from the <\${tag.name}> at \${at}, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'an image declares its box, and the priority one is never lazy',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
+    // 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:
+    // \`{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() });
+      }
+    }
+    return unsizedImages(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 { unsizedImages } from './image-dimensions';
+
+const file = (source: string) => [{ path: 'apps/web/site/page.tsx', source }];
+
+unitTest('an img with no dimensions is refused, and the finding names the line', () => {
+  const findings = unsizedImages(file('<main>\\n  <img src="/hero.png" alt="" />\\n</main>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+  expect(findings[0]?.fix).toContain('aspect-ratio');
+});
+
+unitTest('a width without a height is half a box, and half is none', () => {
+  expect(unsizedImages(file('<img src="/a.png" width={800} alt="" />'))).toHaveLength(1);
+});
+
+unitTest('the pair satisfies it, and so does an aspect-ratio on its own', () => {
+  expect(unsizedImages(file('<img src="/a.png" width={800} height={600} alt="" />'))).toEqual([]);
+  const styled = '<img src="/a.png" style={{ "aspect-ratio": "16 / 9" }} alt="" />';
+  expect(unsizedImages(file(styled))).toEqual([]);
+});
+
+unitTest('the framework wrapper is the same element for this purpose', () => {
+  expect(unsizedImages(file('<Image src="/a.png" alt="" />'))).toHaveLength(1);
+});
+
+unitTest('a lazy priority image is its own finding, with its own edit', () => {
+  const source = '<img src="/hero.png" width={800} height={600} priority loading="lazy" alt="" />';
+  const findings = unsizedImages(file(source));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.fix).toContain('delete loading="lazy"');
+});
+
+unitTest('lazy without priority is the right thing to write', () => {
+  const source = '<img src="/thumb.png" width={80} height={80} loading="lazy" alt="" />';
+  expect(unsizedImages(file(source))).toEqual([]);
+});
+
+// Nothing inside a <template> is laid out, so nothing inside one can shift anything.
+unitTest('an img inside a template shifts nothing and is not reported', () => {
+  const source = '<template><img src="/a.png" alt="" /></template>';
+  expect(unsizedImages(file(source))).toEqual([]);
+});
+
+unitTest('maxWidth is not width, and a commented-out img is not an element', () => {
+  expect(unsizedImages(file('<img src="/a.png" maxWidth={8} height={6} alt="" />'))).toHaveLength(
+    1,
+  );
+  expect(unsizedImages(file('// <img src="/a.png" alt="" />\\nconst a = 1;'))).toEqual([]);
+});
+`;
+
+/** `guards/image-dimensions.ts` and its test. The directory is the registration. */
+export const imageDimensionsGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/image-dimensions.ts', contents: source() },
+  { path: 'guards/image-dimensions.test.ts', contents: test() },
+];

package/src/templates/guard-island-without-states.ts

@@ -0,0 +1,128 @@
+// The `island-without-states` guard `x new` ships, and it closes a loop the framework already built
+// half of. `x shot --island <name>` photographs an island in every state its sibling
+// `<name>.island.states.ts` declares — including the ones nobody can reach by clicking: a save the
+// server refused, a read that came back empty, a label three times as long in the next locale. An
+// island with no states file has never been seen in any of them, by a reviewer or by a model.
+
+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 = 'island-without-states';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// island-without-states: every island declares the states it can be photographed in.
+// \`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}';
+
+const ISLAND_SUFFIX = '.island.tsx';
+const STATES_SUFFIX = '.island.states.ts';
+
+/** The one file that answers for an island, derived rather than searched for. */
+export const statesPathFor = (island: string): string =>
+  \`\${island.slice(0, -ISLAND_SUFFIX.length)}\${STATES_SUFFIX}\`;
+
+/** \`apps/web/app/post/post-form.island.tsx\` → \`post-form\`: what \`x shot --island\` is given. */
+const islandName = (island: string): string => {
+  const base = island.split('/').pop() ?? island;
+  return (base.split('.')[0] ?? base).toLowerCase();
+};
+
+/**
+ * Pure — the caller does the I/O — so the rule is testable without a filesystem. Both lists come
+ * out of one directory walk, which is what keeps the answer to "is there a states file" a set
+ * lookup rather than a second stat per island.
+ */
+export function islandsWithoutStates(
+  islands: readonly string[],
+  states: readonly string[],
+): readonly Finding[] {
+  const declared = new Set(states);
+  const findings: Finding[] = [];
+  for (const island of islands) {
+    const path = statesPathFor(island);
+    if (declared.has(path)) continue;
+    findings.push({
+      code: CODE,
+      cause: \`\${island} declares no states — x shot --island photographs an island in every state its states file names, so nothing has ever seen this component with a refused save, an empty read or a translated label three times as long as the one it was written against\`,
+      fix: \`write \${path} — defineIslandStates({ island: '\${island}', states: [{ id: 'idle', title: 'the first paint', props: {} }] }) — then: x shot --island \${islandName(island)} --json\`,
+      at: island,
+    });
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'an island declares the states it can be photographed in',
+  async check(root) {
+    const islands: string[] = [];
+    const states: string[] = [];
+    // Two patterns, one per root. These two CAN fold — \`{apps,packages}/**/*.island.*\` matches the
+    // same 12 files on Bun 1.4.0, because a LEADING brace group is fine. What does not work is a
+    // brace ALTERNATIVE containing a \`/\`: \`{apps/web,packages/ui}/**/*.tsx\` matches ZERO files in
+    // \`examples/dummy\` where \`apps/*/{site,app}/**/*.tsx\` matches 17, which is why the guards
+    // scanning \`site\`/\`app\` keep the loop — and this one keeps its shape to match them.
+    for (const pattern of ['apps/**/*.island.*', 'packages/**/*.island.*']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || path.includes('/dist/')) continue;
+        if (path.endsWith(ISLAND_SUFFIX)) islands.push(path);
+        else if (path.endsWith(STATES_SUFFIX)) states.push(path);
+      }
+    }
+    return islandsWithoutStates(islands.sort(), states);
+  },
+};
+`;
+
+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 { islandsWithoutStates, statesPathFor } from './island-without-states';
+
+const ISLAND = 'apps/web/app/post/post-form.island.tsx';
+
+unitTest('an island with no states file is refused, and the fix names the file to write', () => {
+  const findings = islandsWithoutStates([ISLAND], []);
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.at).toBe(ISLAND);
+  expect(findings[0]?.fix).toContain('apps/web/app/post/post-form.island.states.ts');
+  // The name \`x shot --island\` is given, not the path: a fix is pasted and run verbatim.
+  expect(findings[0]?.fix).toContain('x shot --island post-form');
+});
+
+unitTest('the sibling states file satisfies it', () => {
+  expect(islandsWithoutStates([ISLAND], [statesPathFor(ISLAND)])).toEqual([]);
+});
+
+// The states file is found by DERIVING its path, never by name: a states file for another island
+// in the same directory answers for that island and not for this one.
+unitTest('a states file for a different island in the same folder is not this one', () => {
+  const other = 'apps/web/app/post/comment-box.island.states.ts';
+  expect(islandsWithoutStates([ISLAND], [other])).toHaveLength(1);
+});
+
+unitTest('the derived path swaps the island suffix and nothing else', () => {
+  expect(statesPathFor(ISLAND)).toBe('apps/web/app/post/post-form.island.states.ts');
+});
+`;
+
+/** `guards/island-without-states.ts` and its test. The directory is the registration. */
+export const islandWithoutStatesGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/island-without-states.ts', contents: source() },
+  { path: 'guards/island-without-states.test.ts', contents: test() },
+];

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

@@ -27,16 +27,24 @@ const CODE = '${CODE}';
 
 /** A hex literal. \`#{$x}\` is Sass interpolation, not a colour, and \`{\` is not a hex digit. */
 const HEX = /#[0-9a-fA-F]{3,8}\\b/;
-const CHANNEL_FUNCTION = /\\b(?:rgba?|hsla?|lab|lch|oklab|oklch|color)\\(/i;
+/**
+ * A channel function OPENS a colour; it does not make one raw. \`rgb(var(--color-bg) / 1)\` is what
+ * a semantic token compiles to, so the argument list decides — see \`literalChannelCall\`.
+ * \`color-mix(\` is not one of these: \`color\` is followed by \`-\`, never \`(\`.
+ */
+const CHANNEL_FUNCTION = /\\b(rgba?|hsla?|lab|lch|oklab|oklch|color)\\(/gi;
 /** The named colours a human actually types. The full CSS list would report \`.item\` selectors. */
 const NAMED =
   /\\b(?:white|black|red|green|blue|yellow|orange|purple|pink|brown|gray|grey|silver|navy|teal|olive|lime|aqua|maroon|fuchsia|gold|beige|coral|crimson|indigo|violet|khaki|salmon|tan|turquoise|wheat)\\b/i;
 
 /**
  * A DECLARATION, never a whole line: a selector carries no colon, so \`#hero { … }\` is not a value
- * and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ * and is never reported. The value stops at the first \`;\`, \`{\` or \`}\` — except a Sass \`#{…}\`
+ * interpolation, which is a VALUE carrying braces. Without that alternative,
+ * \`color: rgb(var(--color-fg) / #{\\$alpha});\` — what \`@ultimat3/ui\`'s own \`role()\` emits — reads as
+ * the truncated \`rgb(var(--color-fg) / #\`, so the rule skips it instead of deciding it.
  */
-const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+const DECLARATION = /([\\w-]+)\\s*:\\s*((?:#\\{[^}]*\\}|[^;{}])+)/g;
 
 export interface StyleFile {
   /** App-root-relative POSIX path, so the finding names the file an author opens. */
@@ -58,6 +66,70 @@ const unquote = (value: string): string => value.replaceAll(/'[^']*'|"[^"]*"/g,
 
 const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
 
+/**
+ * The BALANCED argument list of the call whose \`(\` sits at \`open\`. \`var(--x)\` nests, so reading
+ * to the first \`)\` cuts \`rgb(var(--color-bg) / 1)\` in half and every rule below reads the wrong
+ * text. \`undefined\` when the call is never closed — a value the declaration scan truncated.
+ */
+const argumentsAt = (value: string, open: number): string | undefined => {
+  let depth = 0;
+  for (let index = open; index < value.length; index += 1) {
+    const character = value.charAt(index);
+    if (character === '(') depth += 1;
+    else if (character === ')') {
+      depth -= 1;
+      if (depth === 0) return value.slice(open + 1, index);
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Every \`var(…)\` reference and every Sass \`#{…}\` interpolation removed — a slot a theme restates,
+ * which is the whole point of a token. What is LEFT is what the author wrote by hand.
+ */
+const maskReferences = (args: string): string => {
+  let out = '';
+  let index = 0;
+  while (index < args.length) {
+    if (args.startsWith('#{', index)) {
+      const end = args.indexOf('}', index);
+      if (end === -1) break;
+      index = end + 1;
+      continue;
+    }
+    if (args.startsWith('var(', index)) {
+      const group = argumentsAt(args, index + 3);
+      if (group === undefined) break;
+      index += group.length + 5;
+      continue;
+    }
+    out += args.charAt(index);
+    index += 1;
+  }
+  return out + args.slice(index);
+};
+
+/**
+ * What may remain once the references are gone: separators, and — introduced by \`/\` or \`,\` and
+ * LAST — one numeric alpha, because \`rgb(var(--color-fg) / 0.5)\` and the legacy
+ * \`rgba(var(--color-fg), 0.5)\` are both the token form. The number may not be removed in general:
+ * \`rgb(var(--x) 2 3)\` is two hand-written channels wearing one reference, and stays reported.
+ * The optional leading identifier is \`color()\`'s colourspace — \`color(display-p3 var(--r) …)\`.
+ */
+const RESTATABLE = /^[\\s,/]*(?:[a-z][a-z0-9-]*\\s+)?[\\s,/]*(?:[/,]\\s*\\.?\\d+(?:\\.\\d+)?%?)?\\s*$/i;
+
+/** The first channel function written with a literal channel, rendered whole for the finding. */
+const literalChannelCall = (value: string): string | undefined => {
+  for (const match of value.matchAll(CHANNEL_FUNCTION)) {
+    const args = argumentsAt(value, match.index + match[0].length - 1);
+    if (args === undefined) continue;
+    if (RESTATABLE.test(maskReferences(args))) continue;
+    return \`\${match[1] ?? ''}(\${args})\`;
+  }
+  return undefined;
+};
+
 /** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
 export function rawColours(files: readonly StyleFile[]): readonly Finding[] {
   const findings: Finding[] = [];
@@ -66,12 +138,12 @@ export function rawColours(files: readonly StyleFile[]): readonly Finding[] {
     for (const match of scss.matchAll(DECLARATION)) {
       const property = match[1] ?? '';
       const value = unquote(match[2] ?? '');
-      const literal = HEX.exec(value) ?? CHANNEL_FUNCTION.exec(value) ?? NAMED.exec(value);
-      if (literal === null) continue;
+      const literal = HEX.exec(value)?.[0] ?? literalChannelCall(value) ?? NAMED.exec(value)?.[0];
+      if (literal === undefined) continue;
       findings.push({
         code: CODE,
-        cause: \`\${file.path}:\${lineOf(scss, match.index)} sets \${property} to the raw colour \${literal[0]} — a value no theme can restate, so dark theme renders it unchanged\`,
-        fix: \`replace \${literal[0]} in \${file.path} with tokens.role('fg'), tokens.role('bg') or the role this element means, then: x verify\`,
+        cause: \`\${file.path}:\${lineOf(scss, match.index)} sets \${property} to the raw colour \${literal} — a value no theme can restate, so dark theme renders it unchanged\`,
+        fix: \`replace \${literal} in \${file.path} with tokens.role('fg'), tokens.role('bg') or the role this element means, then: x verify\`,
         at: file.path,
       });
     }
@@ -114,11 +186,43 @@ unitTest('a hex literal in a declaration is refused', () => {
 });
 
 unitTest('rgb(), hsl() and a named colour are the same rule', () => {
-  expect(rawColours(sheet('.a { background: rgb(1 2 3); }'))).toHaveLength(1);
+  const channels = rawColours(sheet('.a { background: rgb(1 2 3); }'));
+  expect(channels).toHaveLength(1);
+  // The whole call, never the bare \`rgb(\` — a fix line telling an author to replace \`rgb(\` names
+  // nothing they can find in the file.
+  expect(channels[0]?.cause).toContain('rgb(1 2 3)');
   expect(rawColours(sheet('.a { background: hsl(1 2% 3%); }'))).toHaveLength(1);
   expect(rawColours(sheet('.a { border-color: white; }'))).toHaveLength(1);
 });
 
+// The legitimate lookalike, and the one this rule got wrong: a channel function OVER TOKENS is the
+// token form. \`tokens.role('bg')\` compiles to \`rgb(var(--color-bg) / 1)\`, so reading \`rgb(\` as a
+// raw colour reports the idiom the rule exists to require — and a rule that noisy gets deleted.
+unitTest('a channel function over var(--…) references is the token form', () => {
+  expect(rawColours(sheet('.a { color: rgb(var(--color-fg) / 1); }'))).toEqual([]);
+  expect(rawColours(sheet('.a { background-color: rgb(var(--color-bg-soft)); }'))).toEqual([]);
+  expect(rawColours(sheet('.a { border: 1px solid rgb(var(--color-line)); }'))).toEqual([]);
+  expect(rawColours(sheet('.a { outline-color: rgba(var(--color-accent), 0.5); }'))).toEqual([]);
+  expect(rawColours(sheet('.a { color: color(display-p3 var(--r) var(--g) var(--b)); }'))).toEqual(
+    [],
+  );
+});
+
+// The other direction: one reference does not launder the literals beside it, or every raw colour
+// gains a one-token disguise.
+unitTest('a literal channel beside a reference is still refused', () => {
+  expect(rawColours(sheet('.a { color: rgb(var(--color-fg-r) 2 3); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { color: rgb(var(--color-fg-x, #ff0000)); }'))).toHaveLength(1);
+});
+
+// A Sass \`#{…}\` interpolation is a value that carries braces, and the declaration scan has to read
+// PAST it: \`role($name, $alpha)\` emits exactly this, so a value stopping at the \`{\` leaves the
+// commonest token form of all undecided rather than accepted.
+unitTest('an interpolated alpha is still the token form, and is read whole', () => {
+  expect(rawColours(sheet('.a { color: rgb(var(--color-fg) / #{$alpha}); }'))).toEqual([]);
+  expect(rawColours(sheet('.a { color: rgb(1 2 3 / #{$alpha}); }'))).toHaveLength(1);
+});
+
 unitTest('a token, a selector and a quoted filename are not colours', () => {
   expect(rawColours(sheet(".a { background: tokens.role('bg'); }"))).toEqual([]);
   expect(rawColours(sheet('#hero { padding: 0; }'))).toEqual([]);