@designesy/score 0.7.0 → 0.7.1

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.

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.
@@ -3735,7 +3736,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 +3754,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 +4108,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;

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.1",
+  "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"