@bounded-systems/conformance-kit 0.6.0 → 0.8.0

package/gates/likeness-gate.mjs

@@ -99,8 +99,16 @@ export function evaluateLikeness({ tokenMap = {}, groups = [], thresholds = DEFA
   });
   const collapseCount = categorical.reduce((n, c) => n + c.count, 0);
 
+  // Identical-value pairs (ΔE 0) are intentional ALIASES — two semantic tokens
+  // deliberately mapped to one value (e.g. `card`/`white` → one #FFFFFF). The single
+  // value is defined once; the alias is by design, NOT redundancy. Only NEAR-but-
+  // DISTINCT pairs (0 < ΔE < dupDeltaE) are real redundancy: two almost-the-same
+  // colours defined separately, which probably should be one.
+  const aliasPairs = near.duplicates.filter((d) => d.identical).length;
+  const redundantTokens = near.count - aliasPairs;
+
   const dupIsError = t.dupSeverity === "error";
-  const errors = (dupIsError ? near.count : 0) + collapseCount;
+  const errors = (dupIsError ? redundantTokens : 0) + collapseCount;
 
   return {
     passed: errors === 0,
@@ -108,7 +116,8 @@ export function evaluateLikeness({ tokenMap = {}, groups = [], thresholds = DEFA
     summary: {
       tokens: Object.keys(tokenMap).length,
       nearDuplicates: near.count,
-      identicalPairs: near.duplicates.filter((d) => d.identical).length,
+      identicalPairs: aliasPairs,
+      redundantTokens,
       categoricalGroups: categorical.length,
       categoricalCollapses: collapseCount,
     },
@@ -117,7 +126,8 @@ export function evaluateLikeness({ tokenMap = {}, groups = [], thresholds = DEFA
     // Envelope a future lone `likeness.*` criterion can consume.
     likeness: {
       distinctCategoricals: collapseCount === 0,
-      noRedundantTokens: near.count === 0,
+      // Intentional identical-value aliases don't count — only near-but-distinct dups.
+      noRedundantTokens: redundantTokens === 0,
     },
   };
 }
@@ -156,8 +166,8 @@ async function main() {
   if (process.env.LIKENESS_REPORT) await writeFile(resolve(process.env.LIKENESS_REPORT), JSON.stringify(report, null, 2) + "\n");
 
   const s = report.summary;
-  const line = `likeness-gate: ${s.tokens} token(s) — ${s.nearDuplicates} near-duplicate(s) (${s.identicalPairs} identical), ${s.categoricalCollapses} categorical collapse(s)`;
-  const dupLine = (d) => `  · ${d.identical ? "identical" : "near-dup"}: ${d.a} ≈ ${d.b} (${d.aHex}/${d.bHex}) ΔE ${d.deltaE}`;
+  const line = `likeness-gate: ${s.tokens} token(s) — ${s.redundantTokens} redundant near-dup(s) + ${s.identicalPairs} intentional alias(es), ${s.categoricalCollapses} categorical collapse(s)`;
+  const dupLine = (d) => `  · ${d.identical ? "alias (identical, ok)" : "near-dup"}: ${d.a} ≈ ${d.b} (${d.aHex}/${d.bHex}) ΔE ${d.deltaE}`;
   const colLine = (c) => `  · collapse: ${c.a} vs ${c.b} (${c.aHex}/${c.bHex}) under ${c.condition} — ΔE ${c.deltaE} < ${c.min}`;
   if (!report.passed) {
     console.error(`✗ ${line}`);

package/gates/pairing-extractor.mjs

@@ -37,6 +37,9 @@
 //
 // INPUTS / ENV:
 //   $PAIRING_DECLARED   optional pairings.json to UNION in (declared ∪ extracted).
+//   --allowlist | $PAIRING_ALLOWLIST=1   CLOSED-WORLD: `declared` is the opt-in
+//                       allowlist — every extracted pairing must be declared (else an
+//                       `undeclared` violation) and every declared pairing must pass.
 //   $PAIRING_MATRIX     write the Markdown matrix here (else stdout).
 //   $PAIRING_REPORT     write the full JSON report here.
 //   $PAIRING_GATE       "1" → also run the palette gate over the union and exit 1 on
@@ -197,13 +200,68 @@ export function renderMatrixMarkdown(matrix) {
 // 4. Full run
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Load tokens + stylesheets → extract ∪ declared → matrix + palette evaluation. */
-export async function runPairingExtractor({ tokens, css = [], declared = null, defaultBackground = null }) {
+/** Resolve a declared spec's pairings to {fg,bg,fgHex,bgHex,kind,name,key}. */
+function resolveDeclared(map, spec) {
+  const out = [];
+  for (const d of spec.pairings || []) {
+    try {
+      const fgHex = resolveColor(map, d.fg), bgHex = resolveColor(map, d.bg), kind = d.kind || "text";
+      const key = `${toHex(parseHex(fgHex)).toLowerCase()}|${toHex(parseHex(bgHex)).toLowerCase()}|${kind}`;
+      out.push({ fg: d.fg, bg: d.bg, fgHex, bgHex, kind, name: d.name, key, source: "declared", confidence: "declared" });
+    } catch { /* unresolvable token → skip */ }
+  }
+  return out;
+}
+const pairKey = (p) => `${toHex(parseHex(p.fgHex)).toLowerCase()}|${toHex(parseHex(p.bgHex)).toLowerCase()}|${p.kind}`;
+
+/**
+ * Load tokens + stylesheets → extract ∪ declared → matrix + palette evaluation.
+ *
+ * `allowlist:true` switches to CLOSED-WORLD: the `declared` set is the opt-in
+ * allowlist and the gate enforces BOTH directions —
+ *   1. every DECLARED pairing must pass contrast, and
+ *   2. every pairing the CSS actually produces must be DECLARED; any extracted
+ *      pairing absent from the allowlist is an `undeclared` violation.
+ * The palette envelope is evaluated over the declared (vetted) set, so surface
+ * mis-extractions can't poison it — they surface as `undeclared` to either
+ * declare (and pass) or fix in the CSS.
+ */
+export async function runPairingExtractor({ tokens, css = [], declared = null, defaultBackground = null, allowlist = false }) {
   const map = typeof tokens === "string" ? await loadTokens(tokens) : tokens;
   const cssTexts = await Promise.all((Array.isArray(css) ? css : [css]).map((c) => (c.includes("{") ? c : readFile(c, "utf8"))));
   const rules = cssTexts.flatMap((t) => parseRules(t));
   const ext = extractPairings(rules, map, { defaultBackground });
 
+  if (allowlist) {
+    const spec = declared
+      ? (typeof declared === "string" ? JSON.parse(await readFile(declared, "utf8")) : declared)
+      : { pairings: [] };
+    const declaredPairs = resolveDeclared(map, spec);
+    const allowed = new Set(declaredPairs.map((p) => p.key));
+    const undeclared = ext.pairings.filter((p) => !allowed.has(pairKey(p)));
+    const matrix = buildMatrix(declaredPairs);
+    const palette = evaluatePalette({ pairings: declaredPairs.map((p) => ({ ...p })) });
+    const failingDeclared = matrix.filter((m) => !m.passed);
+    return {
+      passed: palette.passed && undeclared.length === 0,
+      mode: "allowlist",
+      summary: {
+        declared: declaredPairs.length,
+        extracted: ext.pairings.length,
+        undeclared: undeclared.length,
+        failingDeclared: failingDeclared.length,
+        surfaces: ext.surfaces.length,
+        total: declaredPairs.length,
+        failing: failingDeclared.length + undeclared.length,
+      },
+      undeclared,
+      defaultSurface: ext.defaultSurface,
+      pairings: declaredPairs,
+      matrix,
+      palette,
+    };
+  }
+
   // Union declared pairings (resolved) in.
   const extractedCount = ext.pairings.length;
   let union = ext.pairings;
@@ -245,7 +303,8 @@ async function main() {
     console.error("✗ pairing-extractor: usage: pairing-extractor.mjs <tokens.(json|css)> <style1.css> [style2.css …]");
     process.exit(2);
   }
-  const report = await runPairingExtractor({ tokens, css, declared: process.env.PAIRING_DECLARED || null });
+  const allowlist = process.argv.includes("--allowlist") || process.env.PAIRING_ALLOWLIST === "1";
+  const report = await runPairingExtractor({ tokens, css, declared: process.env.PAIRING_DECLARED || null, allowlist });
   if (process.env.PAIRING_REPORT) await writeFile(resolve(process.env.PAIRING_REPORT), JSON.stringify(report, null, 2) + "\n");
 
   const md = renderMatrixMarkdown(report.matrix);
@@ -253,6 +312,18 @@ async function main() {
   else console.log(md);
 
   const s = report.summary;
+  if (allowlist) {
+    // Closed-world: fail on undeclared OR failing declared pairings.
+    const line = `pairing-extractor [allowlist]: ${s.declared} declared, ${s.undeclared} undeclared, ${s.failingDeclared} failing declared`;
+    if (!report.passed) {
+      console.error(`✗ ${line}`);
+      for (const u of report.undeclared) console.error(`  · UNDECLARED: ${u.fg}/${u.bg} [${u.kind}] — declare it or fix the CSS`);
+      for (const m of report.matrix) if (!m.passed) console.error(`  · FAILS: ${m.fg}/${m.bg} [${m.kind}] WCAG ${m.wcag}:1`);
+      process.exit(1);
+    }
+    console.error(`✓ ${line}`);
+    return;
+  }
   const line = `pairing-extractor: ${s.total} pair(s) (${s.extracted} extracted + ${s.declaredAdded} declared) — ${s.failing} failing`;
   if (process.env.PAIRING_GATE === "1" && !report.passed) {
     console.error(`✗ ${line}`);

package/gates/token-a11y.mjs

@@ -17,7 +17,11 @@
 // CONFIG (every member is OPTIONAL — only declared members run):
 //   { "tokens": "brand/tokens/tokens.css",          // default token map (path or map)
 //     "palette":   { "pairings":[…], "categorical":[…], "thresholds":{…} } | "pairings.json",
-//     "pairing":   { "css":["a.css","b.css"], "declared":"pairings.json", "gate":true },
+//     "pairing":   { "css":["a.css","b.css"], "declared":"pairings.json", "gate":true,
+//                    "allowlist":true },  // closed-world: `declared` is the opt-in
+//                    // allowlist; any pairing the CSS produces that ISN'T declared is a
+//                    // violation, and declared pairings must pass. Palette envelope is
+//                    // evaluated over the vetted declared set (no surface false-positives).
 //     "typography":{ "tokens":"…", "body":["body"], "thresholds":{…} } | "typo.json",
 //     "targetSize":{ "targets":[…], "thresholds":{…} } | "targets.json",
 //     "opacity":   { "usages":[…], "opacityTokens":{…} } | "usages.json",
@@ -60,9 +64,11 @@ export async function runTokenA11y(config, base = ".") {
       const r = await runPairingExtractor({
         tokens: tokens(m), css: (m.css || []).map((c) => rel(base, c)),
         declared: m.declared ? rel(base, m.declared) : null,
+        allowlist: m.allowlist || false,
       });
-      // Report-only unless `gate:true`.
-      return m.gate ? r : { ...r, passed: true, gated: false };
+      // Allowlist (closed-world) gates by default — undeclared pairings are
+      // violations. Extraction-only mode is report-only unless `gate:true`.
+      return (m.allowlist || m.gate) ? r : { ...r, passed: true, gated: false };
     });
   }
   if (config.typography) {
@@ -97,7 +103,9 @@ function memberLine(name, m) {
   const s = m.summary || {};
   const tail =
     name === "palette" ? `${s.pairs} pair(s), ${s.failingPairs} failing, ${s.categoricalCollapses} collapse(s)`
-    : name === "pairing" ? `${s.total} pair(s), ${s.failing} failing${m.gated === false ? " (report-only)" : ""}`
+    : name === "pairing" ? (m.mode === "allowlist"
+        ? `${s.declared} declared, ${s.undeclared} undeclared, ${s.failingDeclared} failing`
+        : `${s.total} pair(s), ${s.failing} failing${m.gated === false ? " (report-only)" : ""}`)
     : name === "typography" ? `${s.styles} style(s), ${s.errors} error(s), ${s.warnings} warn(s)`
     : name === "targetSize" ? `${s.targets} target(s), ${s.belowAA} below AA${m.coverage === "none" ? " (none declared)" : ""}`
     : name === "opacity" ? `${s.usages} usage(s), ${s.failing} failing`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bounded-systems/conformance-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Standalone, site-agnostic web-conformance toolkit: integrity tooling + build gates + provenance generators, all parameterized so a site vendors one kit instead of duplicating scripts.",
   "type": "module",
   "license": "MIT",