@josueavalosjim/taste-check 0.1.0

package/src/config.mjs

@@ -0,0 +1,175 @@
+/**
+ * Config loading and validation.
+ *
+ * Validation is strict on purpose, including rejecting keys it does not know.
+ * A misspelled `pairs` key leaves the contrast check with nothing to measure
+ * while the run still goes green, and the config still looks correct on the
+ * page. The same goes for a pair naming a theme that does not exist: it would
+ * match no themes and never be measured.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+function stringArray(value, where, errors, { required = true } = {}) {
+  if (value === undefined) {
+    if (required) errors.push(`${where} is required`);
+    return [];
+  }
+  if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+    errors.push(`${where} must be an array of strings`);
+    return [];
+  }
+  if (required && !value.length) {
+    errors.push(`${where} must not be empty. An empty list narrows the run to nothing.`);
+  }
+  return value;
+}
+
+function rejectUnknown(object, allowed, where, errors) {
+  for (const key of Object.keys(object)) {
+    if (!allowed.includes(key)) {
+      errors.push(`${where} has an unknown key "${key}". Allowed: ${allowed.join(', ')}.`);
+    }
+  }
+}
+
+function validateContrast(contrast, errors) {
+  rejectUnknown(contrast, ['tokens', 'themes', 'pairs'], 'contrast', errors);
+  stringArray(contrast.tokens, 'contrast.tokens', errors);
+
+  const names = new Set();
+  if (!Array.isArray(contrast.themes) || !contrast.themes.length) {
+    errors.push('contrast.themes must be a non-empty array');
+  } else {
+    contrast.themes.forEach((theme, i) => {
+      const where = `contrast.themes[${i}]`;
+      if (!isPlainObject(theme)) {
+        errors.push(`${where} must be an object`);
+        return;
+      }
+      rejectUnknown(theme, ['name', 'scopes'], where, errors);
+      if (typeof theme.name !== 'string' || !theme.name) errors.push(`${where}.name must be a string`);
+      else if (names.has(theme.name)) errors.push(`${where}.name "${theme.name}" is used twice`);
+      else names.add(theme.name);
+
+      if (!Array.isArray(theme.scopes) || !theme.scopes.length) {
+        errors.push(`${where}.scopes must be a non-empty array`);
+        return;
+      }
+      theme.scopes.forEach((scope, j) => {
+        if (typeof scope === 'string') return;
+        if (!isPlainObject(scope)) {
+          errors.push(`${where}.scopes[${j}] must be a selector string or an object`);
+          return;
+        }
+        rejectUnknown(scope, ['selector', 'atRule'], `${where}.scopes[${j}]`, errors);
+        if (typeof scope.selector !== 'string' || !scope.selector) {
+          errors.push(`${where}.scopes[${j}].selector must be a string`);
+        }
+        if (scope.atRule !== undefined && typeof scope.atRule !== 'string') {
+          errors.push(`${where}.scopes[${j}].atRule must be a string`);
+        }
+      });
+    });
+  }
+
+  if (!Array.isArray(contrast.pairs) || !contrast.pairs.length) {
+    errors.push('contrast.pairs must be a non-empty array. With no pairs there is nothing to measure.');
+    return;
+  }
+  contrast.pairs.forEach((pair, i) => {
+    const where = `contrast.pairs[${i}]`;
+    if (!isPlainObject(pair)) {
+      errors.push(`${where} must be an object`);
+      return;
+    }
+    rejectUnknown(pair, ['fg', 'bg', 'min', 'label', 'themes'], where, errors);
+    for (const key of ['fg', 'bg']) {
+      if (typeof pair[key] !== 'string' || !pair[key]) {
+        errors.push(`${where}.${key} must be a token name or a colour`);
+      }
+    }
+    if (typeof pair.min !== 'number' || !Number.isFinite(pair.min) || pair.min <= 0) {
+      errors.push(
+        `${where}.min must be a positive number. There is no default: WCAG's 4.5 and 3.0 are ` +
+          `documented in the README, never assumed here.`,
+      );
+    }
+    if (pair.label !== undefined && typeof pair.label !== 'string') {
+      errors.push(`${where}.label must be a string`);
+    }
+    if (pair.themes !== undefined) {
+      const listed = stringArray(pair.themes, `${where}.themes`, errors);
+      for (const name of listed) {
+        if (names.size && !names.has(name)) {
+          errors.push(
+            `${where}.themes names "${name}", which is not a theme in contrast.themes. ` +
+              `A pair scoped to a theme that does not exist is never measured.`,
+          );
+        }
+      }
+    }
+  });
+}
+
+function validateTreatments(treatments, errors) {
+  rejectUnknown(
+    treatments,
+    ['files', 'elements', 'approvedClasses', 'allowPrefixes', 'approvedValues'],
+    'treatments',
+    errors,
+  );
+  stringArray(treatments.files, 'treatments.files', errors);
+  stringArray(treatments.elements, 'treatments.elements', errors, { required: false });
+  stringArray(treatments.approvedClasses, 'treatments.approvedClasses', errors, { required: false });
+  stringArray(treatments.allowPrefixes, 'treatments.allowPrefixes', errors, { required: false });
+  stringArray(treatments.approvedValues, 'treatments.approvedValues', errors, { required: false });
+  if (treatments.elements !== undefined && Array.isArray(treatments.elements) && !treatments.elements.length) {
+    errors.push('treatments.elements must not be empty. Omit it to scan every element.');
+  }
+}
+
+/** Validate a parsed config, returning a list of human-readable problems. */
+export function validate(config) {
+  const errors = [];
+  if (!isPlainObject(config)) return ['the config must be a JSON object'];
+  rejectUnknown(config, ['$schema', 'contrast', 'treatments'], 'the config', errors);
+
+  if (config.contrast === undefined && config.treatments === undefined) {
+    errors.push('the config must define "contrast", "treatments", or both');
+  }
+  if (config.contrast !== undefined) {
+    if (isPlainObject(config.contrast)) validateContrast(config.contrast, errors);
+    else errors.push('contrast must be an object');
+  }
+  if (config.treatments !== undefined) {
+    if (isPlainObject(config.treatments)) validateTreatments(config.treatments, errors);
+    else errors.push('treatments must be an object');
+  }
+  return errors;
+}
+
+/**
+ * Read and validate a config file. Paths inside it resolve against the file's
+ * own directory, so a config is portable and can be run from anywhere.
+ */
+export function load(path) {
+  const file = resolve(path);
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    return { ok: false, errors: [`cannot read ${path}`] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { ok: false, errors: [`${path} is not valid JSON: ${error.message}`] };
+  }
+  const errors = validate(parsed);
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, config: parsed, dir: dirname(file), file };
+}

package/src/contrast.mjs

@@ -0,0 +1,110 @@
+/**
+ * WCAG contrast, measured over your own tokens.
+ *
+ * The technique this ports was originally a Playwright test that read colours
+ * off a running page with getComputedStyle, for a good reason: a token file
+ * cannot tell you what is actually painted behind an element. That check
+ * existed because a comment in a stylesheet claimed a grey "clears 4.5:1 on
+ * white" while the page shipped on an off-white, and nothing re-checked it.
+ * The value passed by a fifth of a point, by memory, with no test to say so
+ * when the background moved.
+ *
+ * This module is the static half of that idea: it re-derives the ratio from
+ * the tokens, which is exactly what the original warned against, and is the
+ * honest trade for a tool that runs anywhere with no browser. What it keeps is
+ * the arithmetic, the alpha compositing, and the rule that a pair naming a
+ * token which does not exist is a failure rather than a skip. See "What this
+ * does not do" in the README before trusting a pass.
+ */
+import { readFileSync } from 'node:fs';
+import { contrastRatio, isOpaque, parseColor } from './color.mjs';
+import { parseDeclarations, resolveScopes, resolveValue } from './css.mjs';
+import { expand, label } from './files.mjs';
+
+/** A token name, or a literal colour, resolved to rgba for one theme. */
+function side(spec, table, theme) {
+  if (spec.startsWith('--')) {
+    const resolved = resolveValue(table, spec);
+    if (!resolved.ok) return { ok: false, reason: `theme "${theme}": ${resolved.reason}` };
+    const color = parseColor(resolved.value);
+    if (!color.ok) return { ok: false, reason: `theme "${theme}": ${spec} is ${color.reason}` };
+    return { ok: true, rgba: color.rgba };
+  }
+  const color = parseColor(spec);
+  if (!color.ok) return { ok: false, reason: `theme "${theme}": ${color.reason}` };
+  return { ok: true, rgba: color.rgba };
+}
+
+export function runContrast(config, cwd) {
+  const samples = [];
+  const problems = [];
+  const { tokens, themes, pairs } = config;
+
+  const files = expand(tokens, cwd);
+  if (!files.length) {
+    problems.push(`no token files matched ${tokens.map((t) => `"${t}"`).join(', ')}`);
+    return { name: 'contrast', samples, problems, summary: '' };
+  }
+
+  // One declaration list across every token file, in the order they were
+  // listed, so a later file overriding an earlier one behaves like a later
+  // @import would.
+  const decls = files.flatMap((file) => parseDeclarations(readFileSync(file, 'utf8')));
+
+  for (const theme of themes) {
+    const table = resolveScopes(decls, theme.scopes);
+    if (!table.size) {
+      problems.push(
+        `theme "${theme.name}" resolved zero tokens. Check its scopes (${theme.scopes
+          .map((s) => (typeof s === 'string' ? s : s.selector))
+          .join(', ')}) against ${files.map((f) => label(f, cwd)).join(', ')}.`,
+      );
+      continue;
+    }
+
+    for (const pair of pairs) {
+      if (pair.themes && !pair.themes.includes(theme.name)) continue;
+      const where = `${pair.fg} on ${pair.bg}`;
+
+      const bg = side(pair.bg, table, theme.name);
+      if (!bg.ok) {
+        problems.push(`${where}: ${bg.reason}`);
+        continue;
+      }
+      // A ground with alpha is not a ground. The original walked up the DOM to
+      // the first opaque ancestor; there is no DOM here, so the config has to
+      // name a surface that is actually opaque.
+      if (!isOpaque(bg.rgba)) {
+        problems.push(
+          `${where}: theme "${theme.name}": ${pair.bg} is translucent, so there is nothing ` +
+            `definite to measure against. Name the opaque surface behind it instead.`,
+        );
+        continue;
+      }
+
+      const fg = side(pair.fg, table, theme.name);
+      if (!fg.ok) {
+        problems.push(`${where}: ${fg.reason}`);
+        continue;
+      }
+
+      const ratio = contrastRatio(fg.rgba, bg.rgba);
+      samples.push({
+        theme: theme.name,
+        fg: pair.fg,
+        bg: pair.bg,
+        note: pair.label ?? '',
+        ratio,
+        min: pair.min,
+        pass: ratio >= pair.min,
+      });
+    }
+  }
+
+  return {
+    name: 'contrast',
+    samples,
+    problems,
+    summary: `${samples.length} pairs across ${themes.length} ${themes.length === 1 ? 'theme' : 'themes'}`,
+  };
+}

package/src/css.mjs

@@ -0,0 +1,149 @@
+/**
+ * Custom-property extraction from a stylesheet, and theme resolution.
+ *
+ * This is not a CSS parser. It is a walker that tracks brace depth and quote
+ * state well enough to answer one question: for a given theme, what is the
+ * final value of each `--token`? A regex over a stylesheet works right up
+ * until a value contains a brace or a selector contains a quote, at which
+ * point it stops seeing declarations and reports the file as fine.
+ *
+ * The cascade model is deliberately small and written down rather than
+ * implied. Scopes are applied in the order the config lists them and the last
+ * declaration wins. There is no specificity resolution: if your token file
+ * relies on `.a.b` beating `.b`, list the scopes in the order you want them
+ * applied and the result is the one you asked for.
+ *
+ * Declarations inside an at-rule are ignored unless a scope opts into that
+ * at-rule by name. Without that rule, a `@media (prefers-color-scheme: dark)`
+ * block containing `:root` would silently overwrite the light theme, and the
+ * light theme would be checked against colours it never paints.
+ */
+
+/** Blank out comments, keeping every offset and newline so lines stay true. */
+function blankComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+}
+
+const normalize = (selector) => selector.replace(/\s+/g, ' ').replace(/'/g, '"').trim();
+
+/**
+ * Every custom-property declaration in the source, with the selector it sits
+ * under and the at-rules it is nested inside.
+ */
+export function parseDeclarations(css) {
+  const source = blankComments(css);
+  const decls = [];
+  const stack = [];
+  let buffer = '';
+  let bufferStart = 0;
+  let quote = null;
+
+  const flush = (end) => {
+    const text = buffer.trim();
+    buffer = '';
+    if (!text) return;
+    const colon = text.indexOf(':');
+    if (colon === -1) return;
+    const prop = text.slice(0, colon).trim();
+    if (!prop.startsWith('--')) return;
+    const selector = [...stack].reverse().find((s) => !s.startsWith('@')) ?? '';
+    decls.push({
+      prop,
+      value: text.slice(colon + 1).trim(),
+      selector,
+      atRules: stack.filter((s) => s.startsWith('@')),
+      index: bufferStart + (source.slice(bufferStart, end).length - source.slice(bufferStart, end).trimStart().length),
+    });
+  };
+
+  for (let i = 0; i < source.length; i += 1) {
+    const c = source[i];
+    if (quote) {
+      buffer += c;
+      if (c === '\\') {
+        buffer += source[i + 1] ?? '';
+        i += 1;
+      } else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      quote = c;
+      buffer += c;
+      continue;
+    }
+    if (c === '{') {
+      stack.push(buffer.trim().replace(/\s+/g, ' '));
+      buffer = '';
+      bufferStart = i + 1;
+      continue;
+    }
+    if (c === '}') {
+      flush(i);
+      stack.pop();
+      bufferStart = i + 1;
+      continue;
+    }
+    if (c === ';') {
+      flush(i);
+      bufferStart = i + 1;
+      continue;
+    }
+    if (!buffer) bufferStart = i;
+    buffer += c;
+  }
+  return decls;
+}
+
+/** Does a declaration's selector list contain this exact scope selector? */
+function selectorMatches(list, scope) {
+  const want = normalize(scope);
+  return list.split(',').some((part) => normalize(part) === want);
+}
+
+/**
+ * The token table for one theme: a Map of `--name` to { value, selector }.
+ * Scopes are applied in order, later winning.
+ */
+export function resolveScopes(decls, scopes) {
+  const table = new Map();
+  for (const scope of scopes) {
+    const selector = typeof scope === 'string' ? scope : scope.selector;
+    const atRule = typeof scope === 'string' ? null : (scope.atRule ?? null);
+    for (const d of decls) {
+      if (!selectorMatches(d.selector, selector)) continue;
+      if (atRule === null) {
+        if (d.atRules.length) continue;
+      } else if (!d.atRules.some((a) => a.includes(atRule))) continue;
+      table.set(d.prop, d);
+    }
+  }
+  return table;
+}
+
+/**
+ * Follow `var(--other)` indirection to a concrete value.
+ *
+ * A cycle, or a var() pointing at a token this theme does not define, returns
+ * an error rather than the unresolved text: an unresolved value would reach
+ * the colour parser and fail there with a worse message.
+ */
+export function resolveValue(table, name, seen = new Set()) {
+  if (seen.has(name)) {
+    return { ok: false, reason: `${name} resolves in a circle (${[...seen, name].join(' -> ')})` };
+  }
+  const decl = table.get(name);
+  if (!decl) return { ok: false, reason: `${name} is not defined in this theme` };
+
+  const match = decl.value.match(/^var\(\s*(--[\w-]+)\s*(?:,([\s\S]*))?\)$/);
+  if (!match) return { ok: true, value: decl.value, decl };
+
+  const target = match[1];
+  const fallback = match[2]?.trim();
+  const next = resolveValue(table, target, new Set([...seen, name]));
+  if (next.ok) return next;
+  if (fallback) return { ok: true, value: fallback, decl };
+  return { ok: false, reason: `${name} points at ${target}, which ${next.reason.replace(/^.*? /, '')}` };
+}
+
+/** 1-indexed line of a source offset, for error messages. */
+export const lineAt = (source, index) => source.slice(0, index).split('\n').length;

package/src/files.mjs

@@ -0,0 +1,81 @@
+/**
+ * A small glob, so the tool keeps zero dependencies and behaves the same on
+ * every Node it claims to support.
+ *
+ * Supports the shapes a config actually uses: a literal path, a single-star
+ * pattern like `dir/*.ext`, and a double-star pattern matching any depth.
+ * Brace expansion is not supported. List the patterns separately.
+ *
+ * A pattern that matches nothing returns an empty list. Every caller treats
+ * that as a failure rather than a clean run, so a typo in a path is reported
+ * where it happened instead of showing up as zero findings.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+const ESCAPE = /[.+^${}()|[\]\\]/g;
+
+function toRegExp(pattern) {
+  let out = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern.slice(i, i + 3) === '**/') {
+        out += '(?:[^/]*/)*';
+        i += 2;
+      } else if (pattern.slice(i, i + 2) === '**') {
+        out += '.*';
+        i += 1;
+      } else out += '[^/]*';
+      continue;
+    }
+    if (c === '?') {
+      out += '[^/]';
+      continue;
+    }
+    out += c.replace(ESCAPE, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** The longest wildcard-free directory prefix, so we only walk what we must. */
+function baseOf(pattern) {
+  const parts = pattern.split('/');
+  const stop = parts.findIndex((p) => p.includes('*') || p.includes('?'));
+  return (stop === -1 ? parts.slice(0, -1) : parts.slice(0, stop)).join('/');
+}
+
+function walk(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walk(path, out);
+    else out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Absolute paths matching the patterns, relative to `cwd`, sorted and
+ * de-duplicated so a run is reproducible and a report is diffable.
+ */
+export function expand(patterns, cwd) {
+  const found = new Set();
+  for (const pattern of patterns) {
+    const absolute = isAbsolute(pattern) ? pattern : resolve(cwd, pattern);
+    if (!/[*?]/.test(pattern)) {
+      if (existsSync(absolute) && statSync(absolute).isFile()) found.add(absolute);
+      continue;
+    }
+    const base = resolve(cwd, baseOf(pattern));
+    if (!existsSync(base) || !statSync(base).isDirectory()) continue;
+    const test = toRegExp(isAbsolute(pattern) ? pattern : resolve(cwd, pattern).split(sep).join('/'));
+    for (const file of walk(base, [])) {
+      if (test.test(file.split(sep).join('/'))) found.add(file);
+    }
+  }
+  return [...found].sort();
+}
+
+/** A path as you would paste it into an editor. */
+export const label = (path, cwd) => relative(cwd, path).split(sep).join('/') || path;

package/src/index.mjs

@@ -0,0 +1,29 @@
+/**
+ * The programmatic entry point, for wiring the checks into a test runner or a
+ * CI script without going through the CLI.
+ */
+export { runContrast } from './contrast.mjs';
+export { runTreatments } from './treatments.mjs';
+export { load, validate } from './config.mjs';
+export { toText, toJson, failed } from './report.mjs';
+export { parseColor, contrastRatio, composite, luminance } from './color.mjs';
+export { parseDeclarations, resolveScopes, resolveValue } from './css.mjs';
+export { openTags, classesOf } from './treatments.mjs';
+
+import { runContrast } from './contrast.mjs';
+import { runTreatments } from './treatments.mjs';
+
+/**
+ * Run the checks a config asks for. `only` narrows to one check by name.
+ * Returns the raw results; formatting and exit codes are the caller's.
+ */
+export function run(config, cwd, { only = null } = {}) {
+  const results = [];
+  if (config.contrast && (!only || only === 'contrast')) {
+    results.push(runContrast(config.contrast, cwd));
+  }
+  if (config.treatments && (!only || only === 'treatments')) {
+    results.push(runTreatments(config.treatments, cwd));
+  }
+  return results;
+}

package/src/report.mjs

@@ -0,0 +1,80 @@
+/**
+ * Reporting.
+ *
+ * Passing samples are printed too, with their ratios. Knowing a pair cleared
+ * 4.52 against a floor of 4.5 is worth more than knowing it cleared, because
+ * the next change to the background takes it under.
+ */
+
+const pad = (text, width) => String(text).padStart(width);
+
+// Always show a decimal, so a floor of 3 reads as 3.0 next to a 4.5 and the
+// column stays scannable. Never round: 4.55 must not print as 4.6.
+const showMin = (min) => (Number.isInteger(min) ? min.toFixed(1) : String(min));
+
+function contrastLines(result) {
+  const lines = [];
+  const widest = Math.max(0, ...result.samples.map((s) => s.ratio.toFixed(2).length));
+  for (const s of result.samples) {
+    const note = s.note ? `  ${s.note}` : '';
+    lines.push({
+      level: s.pass ? 'ok' : 'fail',
+      text: `${pad(s.ratio.toFixed(2), widest)}:1  needs ${showMin(s.min)}  ${s.theme}  ${s.fg} on ${s.bg}${note}`,
+    });
+  }
+  for (const p of result.problems) lines.push({ level: 'error', text: p });
+  return lines;
+}
+
+function treatmentLines(result) {
+  return [
+    ...result.failures.map((text) => ({ level: 'fail', text })),
+    ...result.problems.map((text) => ({ level: 'error', text })),
+  ];
+}
+
+export const linesFor = (result) =>
+  result.name === 'contrast' ? contrastLines(result) : treatmentLines(result);
+
+const MARK = { ok: '  ok  ', ' fail': 'FAIL  ', fail: 'FAIL  ', error: 'ERROR ' };
+
+export function toText(results) {
+  const out = [];
+  for (const result of results) {
+    const lines = linesFor(result);
+    const bad = lines.filter((l) => l.level !== 'ok');
+    if (!bad.length) {
+      out.push(`${result.name} ok, ${result.summary}`);
+      // A clean contrast run still shows its margins. Nothing else in the
+      // report tells you which pair is one nudge away from failing.
+      if (result.name === 'contrast') for (const l of lines) out.push(`  ${MARK.ok}${l.text}`);
+      out.push('');
+      continue;
+    }
+    out.push(`${result.name} FAILED`);
+    for (const l of lines) out.push(`  ${MARK[l.level]}${l.text}`);
+    out.push('');
+  }
+  return out.join('\n').trimEnd();
+}
+
+export const failed = (results) =>
+  results.some((r) => linesFor(r).some((l) => l.level !== 'ok'));
+
+export function toJson(results) {
+  return JSON.stringify(
+    {
+      ok: !failed(results),
+      checks: results.map((r) => ({
+        name: r.name,
+        summary: r.summary,
+        ok: !linesFor(r).some((l) => l.level !== 'ok'),
+        samples: r.samples ?? [],
+        failures: r.failures ?? [],
+        problems: r.problems ?? [],
+      })),
+    },
+    null,
+    2,
+  );
+}