@motion-proto/live-tokens 0.77.0 → 0.79.0

package/bin/lib/findings.mjs

@@ -20,6 +20,15 @@ export function lineOf(text, index) {
   return line;
 }
 
+/** The line a `"<key>":` sits on. The quote on both sides of the key makes
+ *  this exact by construction — `"--card-default-body"` cannot match inside
+ *  `"--card-default-body-padding"`, unlike a bare substring search. */
+export function findJsonKeyLine(text, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = new RegExp(`"${escaped}"\\s*:`).exec(text);
+  return m ? lineOf(text, m.index) : 1;
+}
+
 export function readChecksConfig(root) {
   const path = join(root, 'live-tokens.config.json');
   if (!existsSync(path)) return {};
@@ -52,7 +61,7 @@ export function isExcluded(relPath, root) {
  * Unrecognised flags are returned in `rest` for the caller to handle.
  */
 export function parseCheckFlags(argv) {
-  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, rest: [] };
+  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, noFix: false, rest: [] };
   for (const arg of argv) {
     const m = arg.match(/^--(off|warn|error)=(.+)$/);
     if (m) {
@@ -60,17 +69,43 @@ export function parseCheckFlags(argv) {
     } else if (arg === '--strict') opts.strict = true;
     else if (arg === '--json') opts.json = true;
     else if (arg === '--tests') opts.tests = true;
+    else if (arg === '--no-fix') opts.noFix = true;
     else opts.rest.push(arg);
   }
   return opts;
 }
 
+/**
+ * One checker's rule table, keyed in `order`, from the modules under
+ * `bin/rules/` that define its rules. An id on one side and not the other
+ * throws when the checker loads.
+ */
+export function assembleRules(order, ...tables) {
+  const defined = Object.assign({}, ...tables);
+  const stray = [...order.filter((id) => !defined[id]), ...Object.keys(defined).filter((id) => !order.includes(id))];
+  if (stray.length > 0) throw new Error(`rule order and rule modules disagree on: ${stray.join(', ')}`);
+  return Object.fromEntries(order.map((id) => [id, defined[id]]));
+}
+
+/**
+ * The config entry that records a deliberate decision to keep a finding.
+ *
+ * A page or CSS file drops out of discovery, which is narrower than turning a
+ * rule off across the project. Everything else steps its rule down one notch,
+ * since a rule already resolved to `warn` is not silenced by `warn`.
+ */
+function exceptionFor(finding, severity, exclude) {
+  return exclude
+    ? { checks: { exclude: [finding.file] } }
+    : { checks: { rules: { [finding.rule]: severity === 'error' ? 'warn' : 'off' } } };
+}
+
 /** The same last-wins resolution `applySeverity` applies per finding, exposed
  *  standalone so coverage (which has no findings to attach a severity to, but
  *  still has to honor `--off`) can ask the same question. */
 export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
   const configured = config.rules ?? {};
-  let severity = rules[ruleId] ?? 'error';
+  let severity = rules[ruleId]?.severity ?? 'error';
   if (SEVERITIES.includes(configured[ruleId])) severity = configured[ruleId];
   if (opts.off?.includes(ruleId)) severity = 'off';
   if (opts.warn?.includes(ruleId)) severity = 'warn';
@@ -80,16 +115,28 @@ export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
 }
 
 /**
- * Resolve each finding's severity and drop the ones turned off.
- * `rules` maps rule id to its default severity.
+ * Resolve each finding's severity and drop the ones turned off, then attach
+ * what a repair needs: how to make it (`guidance`), how far code can take it
+ * (`repair`), and the config entry that records a decision to keep it
+ * (`exception`).
+ *
+ * `rules` maps rule id to `{ severity, repair, guidance }`. A rule's `repair`
+ * is the ceiling: a finding that arrives carrying its own has already lowered
+ * it, because its context is more ambiguous than the rule's.
  */
-export function applySeverity(findings, rules, opts = {}, config = {}, fixes = {}) {
+export function applySeverity(findings, rules, opts = {}, config = {}, { exclude = false } = {}) {
   return findings
-    .map((f) => ({
-      ...f,
-      severity: resolveRuleSeverity(f.rule, rules, opts, config),
-      ...(fixes[f.rule] ? { fix: fixes[f.rule] } : {}),
-    }))
+    .map((f) => {
+      const severity = resolveRuleSeverity(f.rule, rules, opts, config);
+      const rule = rules[f.rule];
+      return {
+        ...f,
+        severity,
+        ...(rule?.guidance ? { guidance: rule.guidance } : {}),
+        repair: f.repair ?? rule?.repair ?? 'authored',
+        exception: exceptionFor(f, severity, exclude),
+      };
+    })
     .filter((f) => f.severity !== 'off');
 }
 
@@ -144,11 +191,55 @@ export function formatFindings(findings, { label, checked = 0 } = {}) {
   return lines.join('\n');
 }
 
-export function toJson(findings, { label, checked = 0, coverage } = {}) {
+export function toJson(findings, { label, checked = 0, coverage, fix } = {}) {
   const { errors, warnings } = countBySeverity(findings);
   return JSON.stringify(
-    { check: label, checked, errors, warnings, findings, ...(coverage ? { coverage } : {}) },
+    { check: label, checked, errors, warnings, ...(fix ? { fix } : {}), findings, ...(coverage ? { coverage } : {}) },
     null,
     2,
   );
 }
+
+/** The unresolved property names a `contract-alias` finding lists, read off the
+ *  first line: a Playwright or Vitest stack follows on the lines after it.
+ *  `assertAliasesResolve` is the only obligation that lists them; every other
+ *  `contract-alias` message (an empty shipped config, say) misses and is left
+ *  alone. */
+const UNRESOLVED_ALIASES = /aliases resolve to nothing at the root: (.+)/;
+
+/** `component-configs/<id>/default.json`, the file both rules name. */
+const CONFIG_FILE = /component-configs[/\\]([^/\\]+)[/\\]default\.json$/;
+
+/**
+ * One broken alias, one finding.
+ *
+ * A `default.json` alias naming something the vocabulary lacks is a
+ * `config-token` finding from plain Node, and the same string makes the
+ * property resolve to nothing at the root, which the browser reports as
+ * `contract-alias`. Under `--tests` both run, so the merge drops the browser's
+ * copy when every name it lists already carries a `config-token` finding for
+ * the same component. A `contract-alias` naming a token the vocabulary knows,
+ * declared, spelled correctly, and still unresolved, is a different defect and
+ * stays.
+ */
+export function dedupeAliasFindings(findings) {
+  const broken = new Map();
+  for (const f of findings) {
+    if (f.rule !== 'config-token') continue;
+    const id = CONFIG_FILE.exec(f.file ?? '')?.[1];
+    const property = f.details?.property;
+    if (!id || !property) continue;
+    if (!broken.has(id)) broken.set(id, new Set());
+    broken.get(id).add(property);
+  }
+  if (broken.size === 0) return findings;
+  return findings.filter((f) => {
+    if (f.rule !== 'contract-alias') return true;
+    const id = CONFIG_FILE.exec(f.file ?? '')?.[1];
+    const known = id ? broken.get(id) : undefined;
+    if (!known) return true;
+    const listed = UNRESOLVED_ALIASES.exec(String(f.message ?? '').split('\n')[0])?.[1];
+    if (!listed) return true;
+    return !listed.split(',').map((name) => name.trim()).filter(Boolean).every((name) => known.has(name));
+  });
+}

package/bin/lib/fixers.mjs

@@ -0,0 +1,64 @@
+// Applies the patches an `auto` finding already computed in its own
+// `details.patch`. This module owns none of the per-rule repair logic — that
+// lives beside each rule, in bin/rules/, pageSource.mjs, geometry.mjs, and
+// catalogue.mjs, since only the rule that found the fault knows its shape.
+// This module only knows how to write one down safely.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The character offset where 1-based `line` begins. The inverse of
+ *  `lineOf` in findings.mjs. */
+function offsetOfLine(text, line) {
+  let n = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (n === line) return i;
+    if (text[i] === '\n') n++;
+  }
+  return text.length;
+}
+
+/**
+ * Writes every `auto` finding's patch, one file at a time.
+ *
+ * A patch applies at the first occurrence of `from` at or after the finding's
+ * own line: the file has moved since the finding was computed, or another
+ * patch in the same file shifted text, so a patch whose `from` cannot be
+ * found there is not applied and comes back in `skipped` instead of guessing
+ * at a different occurrence. Findings within one file apply in line order;
+ * none of the four fixers inserts or removes a newline, so an earlier
+ * patch's line never moves a later one's.
+ */
+export function applyFixes(findings, root) {
+  const byFile = new Map();
+  for (const f of findings) {
+    if (f.repair !== 'auto' || !f.details?.patch) continue;
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+
+  const applied = [];
+  const skipped = [];
+  for (const [file, list] of byFile) {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+      skipped.push(...list);
+      continue;
+    }
+    let text = readFileSync(path, 'utf8');
+    let changed = false;
+    for (const finding of list.sort((a, b) => a.line - b.line)) {
+      const { from, to } = finding.details.patch;
+      const at = text.indexOf(from, offsetOfLine(text, finding.line));
+      if (at === -1) {
+        skipped.push(finding);
+        continue;
+      }
+      text = text.slice(0, at) + to + text.slice(at + from.length);
+      changed = true;
+      applied.push(finding);
+    }
+    if (changed) writeFileSync(path, text);
+  }
+  return { applied, skipped };
+}

package/bin/lib/geometry.mjs

@@ -0,0 +1,92 @@
+// Which token a raw dimension should have been, computed rather than guessed.
+//
+// `dimension-literal` fires on a declaration the checkers already flagged; this
+// module answers the follow-up a repair needs: what the literal measures, which
+// step of its scale sits nearest, and whether that step is unique. A tie is the
+// one case a person has to settle, so it is reported rather than resolved.
+
+import { stripVarFallbacks } from './cssValues.mjs';
+
+const REM_PX = 16;
+
+// The same literals `hasDimensionLiteral` flags: px and rem, no leading sign.
+const LITERAL = /(?<![\w.-])(\d*\.?\d+)(px|rem)\b/g;
+
+const round = (n) => Math.round(n * 1000) / 1000;
+
+/**
+ * A token's value in pixels, or null when it is not a single length. A shadow
+ * step (`1px 1px 2px hsla(...)`) and `--space-full: 100%` both measure nothing
+ * a literal can be matched against, so neither becomes a candidate.
+ */
+function pixelsOf(value) {
+  const m = /^\s*(\d*\.?\d+)(px|rem)?\s*$/.exec(value);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  if (!m[2]) return n === 0 ? 0 : null;
+  return m[2] === 'rem' ? n * REM_PX : n;
+}
+
+/** The token scale a CSS property draws its lengths from, for check-page. */
+export function geometryScaleOfProperty(prop) {
+  if (/-radius$/.test(prop)) return 'radius';
+  if (/shadow$/.test(prop)) return 'shadow';
+  if (/^(border|outline)(-|$)/.test(prop)) return 'border-width';
+  if (/^(padding|margin|gap|row-gap|column-gap|inset|top|right|bottom|left)(-|$)/.test(prop)) return 'space';
+  return null;
+}
+
+/** Each literal in `text` (fallback-stripped, the same text `from` names)
+ *  replaced by its one candidate's token. Only called once every literal is
+ *  unique, so `candidates[0]` is never a guess. A zero-valued match has no
+ *  entry in `literals` (the census skips it too), so it must be recognised
+ *  here and left untouched rather than consuming the next entry.
+ */
+function rewriteLiterals(text, literals) {
+  let i = 0;
+  return text.replace(LITERAL, (match, num, unit) => {
+    const px = round(parseFloat(num) * (unit === 'rem' ? REM_PX : 1));
+    if (px === 0) return match;
+    return `var(${literals[i++].candidates[0].token})`;
+  });
+}
+
+/**
+ * Every literal in a declaration, each with the nearest step of `scale`.
+ *
+ * A term inside `calc()` or a shorthand is measured on its own, so
+ * `padding: 8px 16px` reports two literals and `calc(100% - 20px)` reports the
+ * 20px. `auto` holds only when every one of them lands on a single step and
+ * the declaration carries no var() fallback: a tie, a scale with no
+ * comparable steps, or a fallback beside the literal leaves the choice open.
+ */
+export function resolveGeometryLiteral(value, scale, tokens = []) {
+  const steps = [];
+  for (const token of tokens) {
+    const px = pixelsOf(token.value ?? '');
+    if (px !== null) steps.push({ token: token.name, px });
+  }
+
+  const stripped = stripVarFallbacks(value);
+  const literals = [];
+  for (const m of stripped.matchAll(LITERAL)) {
+    const px = round(parseFloat(m[1]) * (m[2] === 'rem' ? REM_PX : 1));
+    if (px === 0) continue;
+    const nearest = steps.reduce((best, s) => Math.min(best, Math.abs(s.px - px)), Infinity);
+    const candidates = steps
+      .filter((s) => Math.abs(Math.abs(s.px - px) - nearest) < 1e-6)
+      .map((s) => ({ token: s.token, px: s.px, shift: round(s.px - px) }));
+    literals.push({ value: m[0], px, candidates });
+  }
+
+  // A var() fallback beside a flagged literal makes `stripped` text the source
+  // never contains, so no patch could find its site; the choice stays open.
+  const auto =
+    stripped === value && literals.length > 0 && literals.every((l) => l.candidates.length === 1);
+  return {
+    scale,
+    literals,
+    auto,
+    patch: auto ? { from: stripped, to: rewriteLiterals(stripped, literals) } : null,
+  };
+}

package/bin/lib/pageRoutes.mjs

@@ -0,0 +1,309 @@
+// Page targets for `check-page --tests`: a page source file paired with the
+// route that renders it.
+//
+// The route table is the consumer's own `pages` object, found by the file that
+// imports `LiveTokensRouter`, and read statically the way `missing-source`
+// already reads it. A route that object cannot express — one served by
+// `resolve()` — is mapped by hand under `pageRoutes` in the testing settings.
+// Parameter values are never guessed and the app entry point is never imported
+// into Node.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { isExcluded } from './findings.mjs';
+import { walk } from './tokenVocabulary.mjs';
+
+/**
+ * Directories that hold the system rather than pages built on it. Mirrors
+ * `NOT_PAGES` in `check-page.mjs`; duplicated so the static checker can import
+ * this module without an import cycle, and pinned to it by
+ * `pageRoutes.test.ts`.
+ */
+export const SYSTEM_DIRS = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
+
+const SETTINGS_FILES = [
+  'live-tokens.testing.ts',
+  'live-tokens.testing.mts',
+  'live-tokens.testing.js',
+  'live-tokens.testing.mjs',
+];
+
+export function settingsFilePath(root) {
+  for (const name of SETTINGS_FILES) {
+    const path = join(root, name);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+/** Block comments first: a `//` inside one must not seed a second, overlapping
+ *  strip. Same reasoning as `contractRunner.mjs`'s own scraper. */
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+
+function skipString(text, start) {
+  const quote = text[start];
+  for (let i = start + 1; i < text.length; i++) {
+    if (text[i] === '\\') { i++; continue; }
+    if (text[i] === quote) return i;
+  }
+  return text.length;
+}
+
+/** The text between the braces of the object literal opening at `open`. */
+function objectBody(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(text, i); continue; }
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+
+/** The text between the brackets of the array literal opening at `open`.
+ *  Mirrors `objectBody`, bracket-keyed rather than brace-keyed. */
+function arrayBody(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(text, i); continue; }
+    if (ch === '[') depth++;
+    else if (ch === ']') {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+
+/** Top-level comma-separated chunks of an object or array body, respecting
+ *  strings and nested brackets. Shared by `objectEntries` (each chunk is
+ *  `key: value`) and `settingsPageViewports` (each chunk is a `{ width,
+ *  height }` literal). */
+function splitTopLevel(body) {
+  const chunks = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(body, i); continue; }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth--;
+    else if (ch === ',' && depth === 0) {
+      chunks.push(body.slice(start, i));
+      start = i + 1;
+    }
+  }
+  chunks.push(body.slice(start));
+  return chunks;
+}
+
+/** Top-level `key: value` pairs of an object body, values kept as source text. */
+function objectEntries(body) {
+  const entries = [];
+  for (const chunk of splitTopLevel(body)) {
+    const match = /^\s*(?:'([^']*)'|"([^"]*)"|([A-Za-z_$][\w$]*))\s*:([\s\S]*)$/.exec(chunk);
+    if (!match) continue;
+    entries.push({ key: match[1] ?? match[2] ?? match[3], value: match[4].trim() });
+  }
+  return entries;
+}
+
+function namedObject(text, field) {
+  const at = new RegExp(`\\b${field}\\s*[:=]\\s*\\{`).exec(text);
+  if (!at) return null;
+  return objectBody(text, at.index + at[0].length - 1);
+}
+
+const ROUTER_IMPORT = /import\s*\{[^}]*\bLiveTokensRouter\b[^}]*\}\s*from\s*['"]/;
+
+/** Every file under `src/` that mounts the router, sorted so a project with
+ *  more than one entry point resolves the same way on every run. */
+export function routerFiles(root) {
+  const src = join(root, 'src');
+  if (!existsSync(src)) return [];
+  return walk(src, ['.svelte'])
+    .filter((file) => ROUTER_IMPORT.test(stripComments(readFileSync(file, 'utf8'))))
+    .sort();
+}
+
+/** Route path -> page source, from the `pages` object of every router file.
+ *  The first file to claim a route keeps it. */
+export function routeTable(root) {
+  const table = new Map();
+  for (const file of routerFiles(root)) {
+    const body = namedObject(stripComments(readFileSync(file, 'utf8')), 'pages');
+    if (body === null) continue;
+    for (const { key, value } of objectEntries(body)) {
+      const source = /\bsource\s*:\s*['"]([^'"]+)['"]/.exec(value);
+      if (!source || table.has(key)) continue;
+      table.set(key, source[1]);
+    }
+  }
+  return table;
+}
+
+/**
+ * `pageRoutes` from the testing settings: page source -> concrete URL. Read
+ * from the file's source text, like `contractRunner.mjs`'s `dataDir` scrape,
+ * because importing the settings file would fail on its own extensionless
+ * imports. A `pageRoutes` key present in live code that this cannot read as
+ * a plain string map throws rather than falling through to a silent default:
+ * an unread mapping reads as a page with no route.
+ */
+export function settingsPageRoutes(root) {
+  const settings = settingsFilePath(root);
+  if (!settings) return new Map();
+  const live = stripComments(readFileSync(settings, 'utf8'));
+  const body = namedObject(live, 'pageRoutes');
+  if (body === null) {
+    if (/\bpageRoutes\s*:/.test(live)) {
+      throw new Error(
+        `"pageRoutes" in ${settings} is not a plain object literal, so --tests cannot read it statically. `
+        + 'Write it as literal page-path to URL string pairs, or remove the key.',
+      );
+    }
+    return new Map();
+  }
+  const routes = new Map();
+  for (const { key, value } of objectEntries(body)) {
+    const url = /^['"]([^'"]+)['"]$/.exec(value);
+    if (!url) {
+      throw new Error(
+        `"pageRoutes['${key}']" in ${settings} is not a plain string literal, so --tests cannot read it statically.`,
+      );
+    }
+    routes.set(key, url[1]);
+  }
+  return routes;
+}
+
+/** The contract project's own desktop size, and the phone the text styles
+ *  carry media overrides for (decision 4). Mirrors `DEFAULT_PAGE_VIEWPORTS`
+ *  in `src/testing/config.ts`; duplicated for the reason `settingsPageRoutes`
+ *  above reads its own settings statically rather than importing that module. */
+export const DEFAULT_PAGE_VIEWPORTS = [
+  { width: 1280, height: 900 },
+  { width: 390, height: 844 },
+];
+
+/**
+ * `pageViewports` from the testing settings, read the same way
+ * `settingsPageRoutes` reads `pageRoutes`. Falls back to
+ * `DEFAULT_PAGE_VIEWPORTS` when the key is absent, so a caller building the
+ * set of viewports a page run is expected to cover sees the same list the
+ * generated Playwright config resolves at runtime (`src/testing/
+ * playwright.ts`'s own `settings.pageViewports`), rather than a shipped
+ * default that a project replaced. A `pageViewports` present in live code
+ * that this cannot read as a plain array of `{ width, height }` literals
+ * throws rather than falling through to a silent default.
+ */
+export function settingsPageViewports(root) {
+  const settings = settingsFilePath(root);
+  if (!settings) return DEFAULT_PAGE_VIEWPORTS;
+  const live = stripComments(readFileSync(settings, 'utf8'));
+  const at = /\bpageViewports\s*:\s*\[/.exec(live);
+  if (!at) {
+    if (/\bpageViewports\s*:/.test(live)) {
+      throw new Error(
+        `"pageViewports" in ${settings} is not a plain array literal, so --tests cannot read it statically. `
+        + 'Write it as literal { width, height } entries, or remove the key.',
+      );
+    }
+    return DEFAULT_PAGE_VIEWPORTS;
+  }
+  const body = arrayBody(live, at.index + at[0].length - 1) ?? '';
+  const items = splitTopLevel(body).map((item) => item.trim()).filter(Boolean);
+  if (items.length === 0) return DEFAULT_PAGE_VIEWPORTS;
+  return items.map((item) => {
+    const width = /\bwidth\s*:\s*(\d+)/.exec(item);
+    const height = /\bheight\s*:\s*(\d+)/.exec(item);
+    if (!width || !height) {
+      throw new Error(
+        `"pageViewports" in ${settings} has an entry that is not a plain { width, height } literal, so --tests cannot read it statically.`,
+      );
+    }
+    return { width: Number(width[1]), height: Number(height[1]) };
+  });
+}
+
+function isSystemPath(rel) {
+  return SYSTEM_DIRS.some((dir) => rel === dir || rel.startsWith(`${dir}/`));
+}
+
+function toRelative(root, target) {
+  return relative(root, resolve(root, target)).split('\\').join('/');
+}
+
+const NO_ROUTE =
+  'no route renders this page. Give its entry in the pages object a `source` field, '
+  + 'or map the file to a concrete URL under `pageRoutes` in live-tokens.testing.ts.';
+
+/**
+ * The pages `--tests` opens, each with the route that renders it.
+ *
+ * With no paths, every mapped page outside the system directories is a target.
+ * With paths, each one is looked up in the same map; a file no route names
+ * comes back with `route: null` and the `reason` the caller reports as a
+ * `tests-setup` finding.
+ */
+export function resolvePageTargets(paths = [], root = process.cwd()) {
+  const mapped = new Map();
+  for (const [route, source] of routeTable(root)) {
+    const rel = toRelative(root, source);
+    if (!mapped.has(rel)) mapped.set(rel, route);
+  }
+  // An explicit mapping wins: it exists because the route table could not
+  // express the route in the first place.
+  for (const [source, url] of settingsPageRoutes(root)) {
+    mapped.set(toRelative(root, source), url);
+  }
+
+  const pages = [...mapped.entries()]
+    .filter(([source]) => !isSystemPath(source))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([source, route]) => ({ source, route }));
+
+  if (paths.length === 0) return pages;
+
+  const targets = [];
+  for (const path of paths) {
+    const full = resolve(root, path);
+    if (existsSync(full) && statSync(full).isDirectory()) {
+      const prefix = `${toRelative(root, path)}/`;
+      targets.push(...pages.filter((page) => page.source.startsWith(prefix)));
+      continue;
+    }
+    const rel = toRelative(root, path);
+    const route = mapped.get(rel);
+    targets.push(route === undefined ? { source: rel, route: null, reason: NO_ROUTE } : { source: rel, route });
+  }
+  return targets;
+}
+
+/**
+ * `resolvePageTargets`, filtered by `checks.exclude` the same way
+ * `checkPages` (`bin/check-page.mjs`) filters the static half of the same
+ * command: an explicit *file* argument always checks, `isExcluded`'s own
+ * contract, but a directory `checkPages` walks — an explicit directory
+ * argument, or the no-paths-given discovery — drops excluded files. The two
+ * halves of `check-page --tests` have to agree on which pages a directory or
+ * omitted target reaches, or `--tests` fails a page the static half
+ * deliberately skips.
+ */
+export function resolvePageTestTargets(paths = [], root = process.cwd()) {
+  const allTargets = resolvePageTargets(paths, root);
+  const explicitFiles = new Set(
+    paths
+      .map((p) => resolve(root, p))
+      .filter((full) => existsSync(full) && !statSync(full).isDirectory())
+      .map((full) => toRelative(root, full)),
+  );
+  return allTargets.filter((t) => explicitFiles.has(t.source) || !isExcluded(t.source, root));
+}