@designesy/score 0.7.0 → 0.7.2

package/README.md

@@ -1,6 +1,6 @@
 # @designesy/score
 
-Standalone 44-check design-contract scoring engine. Fetches a URL, extracts CSS + `:root` tokens, runs all checks locally, with **no server required**. Zero dependencies.
+Standalone 44-check design-contract scoring engine. Fetches a URL, extracts CSS + `:root` tokens, runs all checks locally, with **no server required**. No required dependencies.
 
 ## Install
 
@@ -90,12 +90,14 @@ Plus 12 anti-slop deductions (S1 to S12) and 7 originality lifts (O1 to O7).
 
 Auto-detect: `designesy.org` → contract, everything else → universal.
 
-## Zero dependencies
+## Dependencies
 
-Uses only Node.js built-ins:
+The engine uses only Node.js built-ins:
 - `node:https` for URL fetching (avoids the Windows libuv/undici crash)
 - `node:dns` for SSRF guard (DNS resolution validation)
-- No `ipaddr.js`, no `undici`, no `fetch()`, no external packages
+- No `ipaddr.js`, no `undici`, no `fetch()`
+
+One optional dependency: Google's [`@google/design.md`](https://github.com/google-labs-code/design.md) linter (Apache-2.0), the version the hosted engine runs. v37 uses it to lint a site's `/DESIGN.md`. npm installs it by default, `npx` included. Installed without it (`npm install --omit=optional`), v37 reports MANUAL (not run, weight 0) for a site that serves a DESIGN.md, and every other check is unchanged.
 
 ## SSRF guard
 

package/dist/engine.d.ts

@@ -6,8 +6,9 @@
  * browser), computes a weighted score (0-100), assigns a letter grade (A-F),
  * and applies anti-slop deductions + originality lifts.
  *
- * Zero dependencies. Uses node:https (not fetch/undici) to avoid the Windows
- * libuv crash during process exit.
+ * No required dependencies. Uses node:https (not fetch/undici) to avoid the
+ * Windows libuv crash during process exit. One optional dependency,
+ * @google/design.md, lints /DESIGN.md for v37; without it v37 is MANUAL.
  *
  * Extracted from apps/site/app/api/score/route.ts — same engine, same checks,
  * same scoring math. The API route wraps this module; the CLI calls it directly.
@@ -158,7 +159,7 @@ export declare function scoreFromParts(input: ScorePartsInput): Promise<ScoreRes
  * the site served v0.4.3; test/engine-1-2-0.test.mjs now reads the site's
  * contract source and fails when the two differ.
  */
-export declare const CONTRACT_VERSION = "v0.4.3";
+export declare const CONTRACT_VERSION = "v0.4.4";
 /**
  * The one verdict rule, shared by every emission format.
  *

package/dist/engine.js

@@ -6,8 +6,9 @@
  * browser), computes a weighted score (0-100), assigns a letter grade (A-F),
  * and applies anti-slop deductions + originality lifts.
  *
- * Zero dependencies. Uses node:https (not fetch/undici) to avoid the Windows
- * libuv crash during process exit.
+ * No required dependencies. Uses node:https (not fetch/undici) to avoid the
+ * Windows libuv crash during process exit. One optional dependency,
+ * @google/design.md, lints /DESIGN.md for v37; without it v37 is MANUAL.
  *
  * Extracted from apps/site/app/api/score/route.ts — same engine, same checks,
  * same scoring math. The API route wraps this module; the CLI calls it directly.
@@ -499,12 +500,32 @@ function checkPaperToken(tokens) {
     return { id: 'v01', item: 'Token values match live site :root foundation', category: 'tokens', status: 'FAIL', detail: '--paper background token not declared in :root' };
 }
 function checkContrastSignal(tokens) {
-    // v22 — REAL WCAG 2.1 contrast between --signal (button fill) and the text
-    // on top of it. Contracts typically put --paper or --ink text on --signal.
-    // We test both --paper-on-signal and --ink-on-signal; the better ratio wins
-    // (designers choose the higher-contrast pairing). AA threshold: 4.5:1 for
-    // body text, 3:1 for large/UI — buttons are large text, but we hold the 4.5:1
-    // bar because button labels are often small (12-14px).
+    // v22 — REAL WCAG 2.1 contrast between the primary button's fill and its
+    // label. AA threshold: 4.5:1 for body text, 3:1 for large/UI — buttons are
+    // large text, but we hold the 4.5:1 bar because button labels are often
+    // small (12-14px).
+    //
+    // A contract that names its primary action pair (--action, the fill, and
+    // --on-action, the label) is measured on exactly that pair: it is what the
+    // button paints, so a better-contrast token elsewhere cannot stand in for a
+    // label that fails. Without both tokens the check reads the convention most
+    // contracts use: --paper or --ink text on --signal, the better ratio winning
+    // (designers choose the higher-contrast pairing).
+    const actionVal = tokens['--action'];
+    const onActionVal = tokens['--on-action'];
+    if (actionVal && onActionVal) {
+        const fillRgb = resolveColor(actionVal, tokens);
+        const labelRgb = resolveColor(onActionVal, tokens);
+        if (!fillRgb || !labelRgb)
+            return { id: 'v22', item: 'Primary button text passes WCAG AA contrast against --signal fill', category: 'accessibility', status: 'SKIP', detail: `--action ${actionVal} or --on-action ${onActionVal} unresolvable to RGB` };
+        const pairRatio = contrastRatio(labelRgb, fillRgb);
+        const pairStr = `${pairRatio.toFixed(2)}:1`;
+        if (pairRatio >= 4.5)
+            return { id: 'v22', item: 'Primary button text passes WCAG AA contrast against --signal fill', category: 'accessibility', status: 'PASS', detail: `--on-action on --action = ${pairStr} (≥ 4.5:1 AA)` };
+        if (pairRatio >= 3)
+            return { id: 'v22', item: 'Primary button text passes WCAG AA contrast against --signal fill', category: 'accessibility', status: 'WARN', detail: `--on-action on --action = ${pairStr} (passes 3:1 large-text, fails 4.5:1 body)` };
+        return { id: 'v22', item: 'Primary button text passes WCAG AA contrast against --signal fill', category: 'accessibility', status: 'FAIL', detail: `--on-action on --action = ${pairStr} (below 3:1, illegible)` };
+    }
     const signalVal = tokens['--signal'];
     if (!signalVal)
         return { id: 'v22', item: 'Primary button text passes WCAG AA contrast against --signal fill', category: 'accessibility', status: 'WARN', detail: '--signal accent token not declared' };
@@ -3735,7 +3756,7 @@ async function checkDesignMdSpec(targetUrl) {
         // package missing from THIS runtime, so the same page scored lower from the
         // npm CLI than from the API. Unverified-here is what MANUAL means (v02,
         // v04, v21): weight 0, resolved by a run that has the linter.
-        const msg = e instanceof Error ? e.message : 'unknown error';
+        const msg = sanitizeErrorText(e instanceof Error ? e.message : 'unknown error');
         return { id: 'v37', item: ITEM, category: CATEGORY, status: 'MANUAL', detail: `/DESIGN.md fetched but linter unavailable: ${msg}. The @google/design.md package may not be installed in this runtime; run the full audit to resolve.` };
     }
     try {
@@ -3753,10 +3774,35 @@ async function checkDesignMdSpec(targetUrl) {
         // Distinct from the branch above: the linter LOADED and then threw, so the
         // file's format is unsupported rather than the runtime being incomplete.
         // Both WARN, but the messages point at different fixes.
-        const msg = e instanceof Error ? e.message : 'unknown error';
+        const msg = sanitizeErrorText(e instanceof Error ? e.message : 'unknown error');
         return { id: 'v37', item: ITEM, category: CATEGORY, status: 'WARN', detail: `/DESIGN.md fetched but lint failed: ${msg}. The file may use a format version the linter doesn't support yet.` };
     }
 }
+// ── Error text in a result, shared by both engine copies ───────────────────
+// A caught error's message carries the file system of the machine that ran
+// the engine: Node's "Cannot find package '@google/design.md' imported from
+// <path>" gives the full path of the npm cache the CLI ran from, under the
+// Users folder of the account that ran it, and a result is read by people
+// other than that account. Every check detail passes through
+// sanitizeErrorText before it is returned. It replaces absolute paths (a
+// drive letter, a UNC share, a POSIX home, temp or system root), file:// URLs
+// and npm cache segments, and keeps the clause that says what failed
+// ("Cannot find package '@google/design.md'"). A path segment may hold spaces
+// (an account name often does); the last one may not, so the sentence after
+// a path survives, and trailing punctuation is kept.
+function sanitizeErrorText(text) {
+    const keep = (label) => (m) => `${label}${/[.,;:!?)]+$/.exec(m)?.[0] ?? ''}`;
+    return text
+        .replace(/\bfile:\/\/[^\s'"<>`|]*/gi, keep('a local file'))
+        .replace(/\\\\[^\\\s'"<>`|]+\\(?:[^\\\r\n'"<>`|*?]+\\)*[^\\\s'"<>`|*?]*/g, keep('a local path'))
+        .replace(/(?<![\w\\/])[A-Za-z]:([\\/])(?:[^\\/\r\n'"<>`|*?]+\1)*[^\\/\s'"<>`|*?]*/g, keep('a local path'))
+        .replace(/(^|[\s'"`(=,:[])\/(?:home|Users|root|tmp|var|private|opt|usr|srv|mnt|Volumes|Library|app|vercel|workspace|workspaces|github|runner|nix|snap)(?:\/[^/\r\n'"<>`|]+(?=\/))*\/[^/\s'"<>`|]+/g, (m, lead) => `${lead}${keep('a local path')(m.slice(lead.length))}`)
+        .replace(/[^\s'"<>`|]*(?:npm-cache|[\\/]_npx[\\/]|[\\/]\.npm[\\/])[^\s'"<>`|]*/gi, keep('the npm cache'));
+}
+/** The checks with every detail passed through sanitizeErrorText. */
+function sanitizeCheckDetails(checks) {
+    return checks.map((c) => (typeof c.detail === 'string' ? { ...c, detail: sanitizeErrorText(c.detail) } : c));
+}
 // ── Score arithmetic, shared by both engine copies ─────────────────────────
 // Everything between the check verdicts and the grade: category weights, the
 // weighted score, the slop deduction, the originality lift, the per-category
@@ -4082,7 +4128,7 @@ export async function scoreFromParts(input) {
             detail: 'not probed: offline fixture run (no network); excluded from the score',
         }
         : await checkDesignMdSpec(targetUrl));
-    checks = applyScopeFilter(checks, effectiveScope);
+    checks = sanitizeCheckDetails(applyScopeFilter(checks, effectiveScope));
     const pass = checks.filter((c) => c.status === 'PASS').length;
     const fail = checks.filter((c) => c.status === 'FAIL').length;
     const warn = checks.filter((c) => c.status === 'WARN').length;
@@ -4560,7 +4606,7 @@ export async function scoreFromParts(input) {
  * the site served v0.4.3; test/engine-1-2-0.test.mjs now reads the site's
  * contract source and fails when the two differ.
  */
-export const CONTRACT_VERSION = 'v0.4.3';
+export const CONTRACT_VERSION = 'v0.4.4';
 /**
  * The one verdict rule, shared by every emission format.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@designesy/score",
-  "version": "0.7.0",
-  "description": "Standalone 44-check design-contract scoring engine: fetches a URL, extracts CSS + tokens, and runs all checks locally. Zero dependencies.",
+  "version": "0.7.2",
+  "description": "Standalone 44-check design-contract scoring engine: fetches a URL, extracts CSS + tokens, and runs all checks locally. No required dependencies.",
   "license": "MIT",
   "author": "Designesy <hello@designesy.org>",
   "homepage": "https://www.designesy.org/score",
@@ -43,6 +43,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "optionalDependencies": {
+    "@google/design.md": "0.4.0"
+  },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "typescript": "^5.7.0"