maddox-engine 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,16 @@
 # maddox
 
-Scans source code for design-token, motion, and component-state drift against your own design system.
+Scans source code — or a live deployed page — for design-token, motion, and component-state drift against your own design system.
 
 This is the open-source scanning engine behind [Maddox Engine](https://www.maddoxengine.com) — the same code the hosted dashboard and GitHub Action run, extracted so you can run it locally or in CI with no account required.
 
 ## What it checks
 
-- **Colors** — every hex literal in your source, matched against your `@theme` tokens by exact value, then by RGB distance for near-misses.
-- **Motion** — durations and easings used in code, checked against your real motion tokens (duration against duration, ease against ease — never cross-compared).
-- **Component states** — an explicit contract you write yourself (a JSON file naming which states each kind of component must cover: `disabled`, `loading`, `error`, and so on). Confirms the state is referenced in the file; it doesn't verify it renders correctly — that's a static source check, not a visual one.
+- **Colors** — every hex literal in your source (or a live page's rendered HTML/CSS), matched against your `@theme` tokens by exact value, then by RGB distance for near-misses.
+- **Motion** — durations and easings used in code, checked against your real motion tokens (duration against duration, ease against ease — never cross-compared). Source-scan only; see `--url` below.
+- **Component states** — an explicit contract you write yourself (a JSON file naming which states each kind of component must cover: `disabled`, `loading`, `error`, and so on). Confirms the state is referenced in the file; it doesn't verify it renders correctly — that's a static source check, not a visual one. Source-scan only.
 
-This is a static source-code scanner, not a pixel/DOM visual-regression tool. It checks the values developers actually wrote against the tokens that are supposed to govern them, so it catches drift that renders identically to a real token (and so produces zero visual diff) but was never written as one.
+This is a source-code and rendered-output scanner, not a pixel/DOM visual-regression tool. It checks the values a page actually ships against the tokens that are supposed to govern them, so it catches drift that renders identically to a real token (and so produces zero visual diff) but was never written as one.
 
 ## Usage
 
@@ -20,9 +20,11 @@ npx maddox-engine <target-source-dir> <path-to-globals.css-with-@theme-block> [o
 
 Options:
 
-- `--project <name>` — project name (defaults to the target directory's basename)
+- `--project <name>` — project name (defaults to the target directory's basename, or the URL's hostname in `--url` mode)
 - `--motion <path>` — path to a JSON file of motion tokens (e.g. a vendored copy of your motion-tokens export)
-- `--states <path>` — path to a state-contract JSON file (see below)
+- `--states <path>` — path to a state-contract JSON file (see below). No effect in `--url` mode.
+- `--tokens-studio <path>` — path to a Tokens Studio / W3C Design Tokens JSON export (see below); merged with, and taking precedence over, `@theme` on any path both define
+- `--url <page-url>` — scan a deployed page instead of local source (see below); pass a placeholder like `-` for `<target-source-dir>` when using this alone
 - `--format text|json|markdown` — output format (default: `text`)
 - `--fail-below <0-100>` — exit non-zero if the drift health score falls below this threshold; omit to never fail
 
@@ -45,6 +47,29 @@ An optional JSON file mapping a component-name pattern to the state names that c
 
 Ground truth is explicit — nothing is inferred about which states a component "should" have.
 
+### Tokens Studio ground truth
+
+If your tokens live in Figma via the Tokens Studio plugin rather than (or alongside) a Tailwind `@theme` block, export them to JSON and point `--tokens-studio` at the file. A single-set export (the whole file is one token tree) and a multi-set export (top-level keys are set names, e.g. `global`, `dark`) are both supported — for a multi-set export, every set is merged, later sets overriding earlier ones by path. `{alias}` references are resolved automatically. Only token types that resolve to a single comparable value (`color`, `spacing`, `sizing`, `fontSizes`, `borderRadius`, `dimension`) are used — composite types like `typography` or `boxShadow` describe a bundle of properties, not one value to diff against, and are skipped rather than misclassified.
+
+### Scanning a live page
+
+```bash
+npx maddox-engine - ./src/app/globals.css --url https://example.com --format text
+```
+
+`--url` fetches the page's rendered HTML plus every same-origin `<link rel="stylesheet">` it links to, and runs the same color/font-size extraction against what's actually shipped — not what's in the repo at scan time. This is the difference between a source-linter and a production check: a stale CDN cache, a build step that silently drops a token, or a config typo can all make the deployed page diverge from what the source says, and only a live-URL scan catches that.
+
+Two things don't carry over to `--url` mode:
+
+- **Motion** — durations/eases only ever appear in rendered HTML/CSS as static literals if a component hardcodes them there, which real motion libraries don't do (they animate via the JS runtime). Motion findings are dropped from every `--url` scan rather than surfaced as noise from unrelated CSS.
+- **Component states** — state-completeness is a "is this identifier referenced in this file's source" check; a fetched, already-rendered page has no source to check. `--states` is accepted but has no effect in `--url` mode.
+
+Third-party stylesheets (a different origin than the page itself, e.g. a font CDN) are never fetched — only same-origin CSS, so findings only ever point at code the project actually owns.
+
+### Suggested fixes
+
+Every `near-miss` finding with a resolved nearest token gets a `suggestion` — the concrete replacement text (`var(--token-name)` for a CSS value, or `motionTokens.path.to.value` for a motion token). It's advisory text for a human to apply, not an automatic edit: nothing in this package rewrites your source files. An `unrecognized` value with no close match, and a `missing`-state finding, never get one — there's no safe mechanical fix for either.
+
 ### Health score
 
 `match` counts fully, `near-miss` counts half (it drifted, but is still recognizably close to a real token), `unrecognized` and a missing required state count for nothing. A scan with zero checks scores 100.
@@ -65,10 +90,12 @@ This repo is also a GitHub Action — `omrdev1/maddox-cli` — that runs a scan,
 
 Inputs:
 
-- `target-dir` *(required)* — directory to scan
+- `target-dir` *(required unless `url` is set)* — directory to scan
 - `theme-css` *(required)* — path to the CSS file containing the `@theme` block
 - `motion-tokens` — path to a motion-tokens JSON file
-- `states` — path to a state-contract JSON file
+- `states` — path to a state-contract JSON file. No effect when `url` is set.
+- `tokens-studio` — path to a Tokens Studio / W3C Design Tokens JSON export
+- `url` — a deployed page URL to scan instead of local source
 - `github-token` *(required)* — for posting the PR comment, usually `${{ secrets.GITHUB_TOKEN }}`
 - `fail-below` — fail the build below this health score; omit for comment-only
 - `api-key` / `api-url` — optional, upload results to a [Maddox Engine](https://www.maddoxengine.com) dashboard account for scan history and drift trends across projects (a separate hosted product, not required to use the Action itself)

package/fixtures/tokens-studio-export.json

@@ -0,0 +1,30 @@
+{
+  "global": {
+    "color": {
+      "brand": {
+        "500": { "value": "#4f46e5", "type": "color" },
+        "600": { "value": "{color.brand.500}", "type": "color" }
+      },
+      "neutral": {
+        "900": { "value": "#0a0a0b", "type": "color" }
+      }
+    },
+    "spacing": {
+      "sm": { "value": "8px", "type": "spacing" },
+      "md": { "value": "16px", "type": "spacing" }
+    },
+    "typography": {
+      "heading": {
+        "value": { "fontFamily": "Inter", "fontSize": "32px" },
+        "type": "typography"
+      }
+    }
+  },
+  "dark": {
+    "color": {
+      "neutral": {
+        "900": { "value": "#000000", "type": "color" }
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "maddox-engine",
-  "version": "0.1.0",
-  "description": "Scans source code for design-token, motion, and component-state drift against your own design system — the same engine behind Maddox Engine's CI checks.",
+  "version": "0.3.0",
+  "description": "Scans source code or a live deployed page for design-token, motion, and component-state drift against your own design system — the same engine behind Maddox Engine's CI checks.",
   "license": "MIT",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npx tsx
 
 import { readFileSync } from "node:fs";
-import { audit, healthScore, loadGroundTruth, loadStateContract } from "./core.js";
+import { audit, auditUrl, healthScore, loadGroundTruth, loadStateContract } from "./core.js";
 import { summarize, toJson, toMarkdown, toText, type ScanSummary } from "./format.js";
 
 async function uploadResult(apiUrl: string, apiKey: string, projectName: string, summary: ScanSummary) {
@@ -36,18 +36,23 @@ function flagValue(name: string): string | undefined {
 async function main() {
   const targetDir = process.argv[2];
   const themeCssPath = process.argv[3];
+  const url = flagValue("--url");
 
-  if (!targetDir || !themeCssPath) {
+  if (!themeCssPath || (!targetDir && !url)) {
     console.error(
       "Usage: pnpm scan <target-source-dir> <path-to-globals.css-with-@theme-block> " +
         "[--project <name>] [--motion <path-to-motion-tokens.json>] " +
         "[--states <path-to-state-contract.json>] [--format text|json|markdown] " +
-        "[--fail-below <0-100>]"
+        "[--fail-below <0-100>] [--tokens-studio <path-to-tokens-studio-export.json>] " +
+        "[--url <live-page-url>]\n" +
+        "  --url scans a deployed page's rendered HTML/CSS instead of local source " +
+        "(pass a placeholder for <target-source-dir>, e.g. '-', when using --url alone). " +
+        "--states has no effect in --url mode: state-completeness is a source-code check."
     );
     process.exit(1);
   }
 
-  const projectName = flagValue("--project") ?? targetDir.split("/").pop() ?? "unnamed-project";
+  const projectName = flagValue("--project") ?? (url ? new URL(url).hostname : targetDir.split("/").pop()) ?? "unnamed-project";
   const format = flagValue("--format") ?? "text";
 
   // Motion tokens are an optional external JSON file (a plain object like
@@ -62,8 +67,10 @@ async function main() {
   const statesPath = flagValue("--states");
   const stateContract = statesPath ? loadStateContract(statesPath) : undefined;
 
-  const groundTruth = loadGroundTruth(themeCssPath, motionTokens);
-  const result = await audit(targetDir, groundTruth, stateContract);
+  const tokensStudioPath = flagValue("--tokens-studio");
+  const groundTruth = loadGroundTruth(themeCssPath, motionTokens, tokensStudioPath);
+
+  const result = url ? await auditUrl(url, groundTruth) : await audit(targetDir, groundTruth, stateContract);
   const summary = summarize(result.findings, result.filesScanned);
 
   if (format === "json") {

package/src/core.ts

@@ -1,13 +1,18 @@
 export * from "./types.js";
 export * from "./groundTruth.js";
+export * from "./tokensStudio.js";
 export * from "./scan.js";
+export * from "./crawl.js";
 export * from "./diff.js";
 export * from "./stateCheck.js";
 export * from "./healthScore.js";
+export * from "./suggestFix.js";
 
 import { scanSource, scanFiles } from "./scan.js";
+import { crawlUrl } from "./crawl.js";
 import { diffUsages } from "./diff.js";
 import { checkStates } from "./stateCheck.js";
+import { attachSuggestions } from "./suggestFix.js";
 import type { GroundTruth, ScanResult, StateContract } from "./types.js";
 
 export async function audit(
@@ -25,5 +30,22 @@ export async function audit(
     for (const f of files) scannedFiles.add(f.file);
   }
 
+  attachSuggestions(findings);
+
   return { findings, filesScanned: scannedFiles.size };
 }
+
+/**
+ * The production-aware counterpart to audit(): fetches a live page (plus
+ * its same-origin stylesheets) instead of walking local source files, and
+ * diffs what's actually shipped against the same ground truth. No state
+ * contract here — component-state completeness is a source-code question
+ * (is the state referenced anywhere in this file's source), which has no
+ * equivalent for a fetched, already-rendered page.
+ */
+export async function auditUrl(pageUrl: string, groundTruth: GroundTruth): Promise<ScanResult> {
+  const { usages, sourcesScanned } = await crawlUrl(pageUrl);
+  const findings = diffUsages(usages, groundTruth);
+  attachSuggestions(findings);
+  return { findings, filesScanned: sourcesScanned.length };
+}

package/src/crawl.ts

@@ -0,0 +1,92 @@
+import { extractFromContent, type RawUsage } from "./scan.js";
+
+// Only ever follow relative/absolute-path stylesheet links resolved
+// against the page's own origin — never a third-party CDN's CSS, since
+// that's not the project's own design system and would only add noise
+// (and, worse, false "unrecognized" findings for code the project never
+// wrote).
+function isSameOrigin(href: string, pageUrl: URL): boolean {
+  try {
+    const resolved = new URL(href, pageUrl);
+    return resolved.origin === pageUrl.origin;
+  } catch {
+    return false;
+  }
+}
+
+// Matches <link ... rel="stylesheet" ... href="..."> and the reverse
+// attribute order, case-insensitively, without a full HTML parser —
+// good enough for the handful of <link> tags a real page head has.
+const STYLESHEET_LINK_RE =
+  /<link\b[^>]*\brel=["']stylesheet["'][^>]*\bhref=["']([^"']+)["'][^>]*>|<link\b[^>]*\bhref=["']([^"']+)["'][^>]*\brel=["']stylesheet["'][^>]*>/gi;
+
+function findStylesheetHrefs(html: string): string[] {
+  const hrefs: string[] = [];
+  STYLESHEET_LINK_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = STYLESHEET_LINK_RE.exec(html)) !== null) {
+    hrefs.push(m[1] ?? m[2]);
+  }
+  return hrefs;
+}
+
+export interface CrawlResult {
+  usages: RawUsage[];
+  // The page URL plus every stylesheet URL actually fetched — reported
+  // back so a caller (or the CLI's own output) can show what was scanned,
+  // the live-URL equivalent of scanSource's file count.
+  sourcesScanned: string[];
+}
+
+/**
+ * Fetches a live page's rendered HTML plus every same-origin linked
+ * stylesheet, and runs the same color/font-size/motion literal
+ * extraction scanSource runs over local source files. This is what makes
+ * Maddox "production-aware" rather than local-source-only: it checks
+ * what a real deployed page actually ships, not just what's in the repo
+ * at scan time (a config typo, a stale CDN cache, or a build step that
+ * silently drops a token could all cause the two to diverge).
+ *
+ * Framer Motion / GSAP usage is deliberately dropped from the result.
+ * Real motion libraries set durations/eases via the JS animation runtime,
+ * not static markup, so they never legitimately appear in rendered
+ * HTML/CSS — but framework-compiled CSS reliably DOES contain unrelated
+ * matches for the same shared regex (confirmed against a real deploy:
+ * Tailwind's own `--default-transition-duration:.15s` custom property
+ * matches the duration pattern, `transition-timing-function` matches the
+ * ease pattern). Rather than surface those as noisy false "unrecognized"
+ * findings, motion usages are filtered out of every crawl result before
+ * it's returned — motion checking stays a source-scan-only capability.
+ */
+export async function crawlUrl(pageUrl: string): Promise<CrawlResult> {
+  const url = new URL(pageUrl);
+  const usages: RawUsage[] = [];
+  const sourcesScanned: string[] = [];
+
+  const pageResponse = await fetch(url, { redirect: "follow" });
+  if (!pageResponse.ok) {
+    throw new Error(`Failed to fetch ${url}: ${pageResponse.status} ${pageResponse.statusText}`);
+  }
+  const html = await pageResponse.text();
+  usages.push(...extractFromContent(url.toString(), html));
+  sourcesScanned.push(url.toString());
+
+  const stylesheetHrefs = findStylesheetHrefs(html).filter((href) => isSameOrigin(href, url));
+
+  for (const href of stylesheetHrefs) {
+    const cssUrl = new URL(href, url).toString();
+    try {
+      const cssResponse = await fetch(cssUrl);
+      if (!cssResponse.ok) continue;
+      const css = await cssResponse.text();
+      usages.push(...extractFromContent(cssUrl, css));
+      sourcesScanned.push(cssUrl);
+    } catch {
+      // A single unreachable stylesheet shouldn't fail the whole crawl —
+      // same tolerance readScannedFiles already has for an unreadable
+      // local file.
+    }
+  }
+
+  return { usages: usages.filter((u) => u.kind !== "motion"), sourcesScanned };
+}

package/src/format.ts

@@ -30,7 +30,7 @@ export function toText(summary: ScanSummary): string {
     lines.push(
       `${f.file}:${f.line}  [${f.kind}] ${f.rawValue}  → ${f.severity}${
         f.nearestToken ? ` (nearest: ${f.nearestToken})` : ""
-      }`
+      }${f.suggestion ? `  fix: ${f.suggestion}` : ""}`
     );
   }
   return lines.join("\n");
@@ -60,10 +60,10 @@ export function toMarkdown(summary: ScanSummary): string {
     return lines.join("\n");
   }
 
-  lines.push("<details><summary>Findings</summary>", "", "| Location | Kind | Value | Severity | Nearest token |", "|---|---|---|---|---|");
+  lines.push("<details><summary>Findings</summary>", "", "| Location | Kind | Value | Severity | Nearest token | Suggested fix |", "|---|---|---|---|---|---|");
   for (const f of nonMatch.slice(0, 100)) {
     lines.push(
-      `| \`${f.file}:${f.line}\` | ${f.kind} | \`${f.rawValue}\` | ${f.severity} | ${f.nearestToken ? `\`${f.nearestToken}\`` : "—"} |`
+      `| \`${f.file}:${f.line}\` | ${f.kind} | \`${f.rawValue}\` | ${f.severity} | ${f.nearestToken ? `\`${f.nearestToken}\`` : "—"} | ${f.suggestion ? `\`${f.suggestion}\`` : "—"} |`
     );
   }
   if (nonMatch.length > 100) {

package/src/groundTruth.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { loadTokensStudioFile } from "./tokensStudio.js";
 import type { GroundTruth, MotionToken, StateContract, TokenMap } from "./types.js";
 
 /**
@@ -52,10 +53,21 @@ export function loadStateContract(path: string): StateContract {
 
 export function loadGroundTruth(
   themeCssPath: string,
-  motionTokensObj: Record<string, unknown>
+  motionTokensObj: Record<string, unknown>,
+  tokensStudioPath?: string
 ): GroundTruth {
+  // When both a @theme CSS file and a Tokens Studio export are given, the
+  // Tokens Studio export (the design tool's source of truth) wins on any
+  // path both define — the CSS file is usually the codegen'd output of
+  // the same tokens, so a conflict means the CSS is stale, not that the
+  // design tokens are wrong.
+  const tokens = {
+    ...parseThemeTokens(themeCssPath),
+    ...(tokensStudioPath ? loadTokensStudioFile(tokensStudioPath) : {}),
+  };
+
   return {
-    tokens: parseThemeTokens(themeCssPath),
+    tokens,
     motion: flattenMotionTokens(motionTokensObj),
   };
 }

package/src/suggestFix.ts

@@ -0,0 +1,61 @@
+import type { Finding } from "./types.js";
+
+/**
+ * Builds the suggested source replacement for a single Finding's raw
+ * value, given the token/motion-path name diff.ts already matched it
+ * against (`nearestToken`). Returns undefined when no safe mechanical
+ * suggestion exists — either there's no nearestToken to point at, or the
+ * finding kind isn't a value swap at all (state completeness).
+ *
+ * Deliberately conservative: this only ever proposes replacing the exact
+ * literal Maddox found with a reference to the token it's closest to. It
+ * never tries to rewrite surrounding code, infer intent for an
+ * "unrecognized" value with no near match, or auto-apply anything — the
+ * suggestion is text for a human (or a future codemod) to review, not an
+ * automatic edit.
+ */
+export function suggestFix(finding: Finding): string | undefined {
+  if (!finding.nearestToken) return undefined;
+  if (finding.severity !== "near-miss" && finding.severity !== "match") return undefined;
+
+  switch (finding.kind) {
+    case "color":
+    case "font-size":
+    case "spacing":
+      // nearestToken is a "--token-name" CSS custom property name — the
+      // replacement is how that token is actually consumed in Tailwind
+      // v4 / plain CSS: var(--token-name).
+      return `var(${finding.nearestToken})`;
+
+    case "motion": {
+      // nearestToken is a dotted motion-token path, e.g.
+      // "transition.duration" — how it's actually referenced depends on
+      // the project's own motion tokens object import, which Maddox has
+      // no fixed name for, so this suggests the access path relative to
+      // a generic `motionTokens` import rather than guessing a project's
+      // real variable name.
+      return `motionTokens.${finding.nearestToken}`;
+    }
+
+    case "state":
+      // No mechanical value swap exists for a missing state — this needs
+      // a human to add real handling.
+      return undefined;
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Applies suggestFix to every finding in place, populating `.suggestion`
+ * where a safe suggestion exists. Mutates and returns the same array —
+ * matches diffUsages' existing per-finding transform style rather than
+ * introducing a different pattern for one more derived field.
+ */
+export function attachSuggestions(findings: Finding[]): Finding[] {
+  for (const finding of findings) {
+    finding.suggestion = suggestFix(finding);
+  }
+  return findings;
+}

package/src/tokensStudio.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from "node:fs";
+import type { TokenMap } from "./types.js";
+
+// A single node in a Tokens Studio / W3C Design Tokens export: either a
+// leaf token ({ value, type }) or a group of further-nested nodes. Groups
+// and leaves are told apart by the presence of a "value" key, per the W3C
+// Design Tokens Community Group format Tokens Studio exports.
+interface TokenNode {
+  value?: string | number;
+  type?: string;
+  [key: string]: unknown;
+}
+
+type TokenTree = { [key: string]: TokenNode | TokenTree };
+
+// Only these Tokens Studio types resolve to the single raw CSS value that
+// Maddox's TokenMap expects (a color hex, or a px/rem/em length) — the
+// others (typography, boxShadow, border, composite tokens) describe a
+// bundle of properties, not one comparable value, and are skipped rather
+// than half-mapped into a shape that would silently misclassify usages.
+const SUPPORTED_TYPES = new Set(["color", "fontSizes", "spacing", "sizing", "borderRadius", "dimension"]);
+
+function isLeaf(node: TokenNode | TokenTree): node is TokenNode {
+  return typeof (node as TokenNode).value !== "undefined";
+}
+
+/**
+ * Resolves a Tokens Studio alias reference, e.g. "{color.brand.500}", by
+ * looking up the dotted path in the flattened token map already built so
+ * far. Aliases must point at a token defined earlier in traversal order;
+ * circular or forward references are left unresolved (returned as-is)
+ * rather than causing an infinite loop.
+ */
+function resolveAlias(raw: string, resolved: Map<string, string>, depth = 0): string {
+  const match = /^\{([^}]+)\}$/.exec(raw.trim());
+  if (!match || depth > 10) return raw;
+
+  const target = resolved.get(match[1]);
+  if (target === undefined) return raw;
+  return resolveAlias(target, resolved, depth + 1);
+}
+
+/**
+ * Flattens a Tokens Studio JSON tree (single set, e.g. the "global" set
+ * from a multi-set export, or the whole file for a single-set export)
+ * into a flat `path.to.token` -> raw-css-value map, resolving `{alias}`
+ * references along the way. Unsupported token types are skipped, not
+ * coerced.
+ */
+export function flattenTokensStudioTree(tree: TokenTree): TokenMap {
+  const resolved = new Map<string, string>();
+
+  function walk(node: TokenNode | TokenTree, path: string): void {
+    if (isLeaf(node)) {
+      if (node.type && !SUPPORTED_TYPES.has(node.type)) return;
+      const raw = String(node.value);
+      const value = raw.startsWith("{") ? resolveAlias(raw, resolved) : raw;
+      resolved.set(path, value);
+      return;
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key.startsWith("$")) continue; // Tokens Studio metadata keys, e.g. $themes, $metadata
+      walk(child as TokenNode | TokenTree, path ? `${path}.${key}` : key);
+    }
+  }
+
+  walk(tree, "");
+
+  const tokens: TokenMap = {};
+  for (const [path, value] of resolved) {
+    // Drop any alias that never resolved to a raw value (dangling/forward
+    // reference) — an unresolved "{...}" string is not a comparable CSS
+    // value and would never match a scanned usage anyway.
+    if (value.startsWith("{")) continue;
+    tokens[`--${path.replace(/\./g, "-")}`] = value;
+  }
+  return tokens;
+}
+
+/**
+ * Loads a Tokens Studio JSON export from disk and flattens it into a
+ * TokenMap. Handles both a single-set export (the whole file is one
+ * token tree) and a multi-set export (top-level keys are set names, e.g.
+ * "global", "dark" — every non-$-prefixed top-level key is merged, later
+ * sets overriding earlier ones by path, since Maddox compares against one
+ * flat ground truth rather than a per-theme one).
+ */
+export function loadTokensStudioFile(path: string): TokenMap {
+  const raw = JSON.parse(readFileSync(path, "utf-8")) as TokenTree;
+
+  const topLevelKeys = Object.keys(raw).filter((k) => !k.startsWith("$"));
+  const looksLikeMultiSet = topLevelKeys.every(
+    (k) => typeof raw[k] === "object" && raw[k] !== null && !isLeaf(raw[k] as TokenNode)
+      && Object.values(raw[k] as TokenTree).some((v) => typeof v === "object")
+  );
+
+  if (!looksLikeMultiSet) {
+    return flattenTokensStudioTree(raw);
+  }
+
+  const merged: TokenMap = {};
+  for (const key of topLevelKeys) {
+    Object.assign(merged, flattenTokensStudioTree(raw[key] as TokenTree));
+  }
+  return merged;
+}

package/src/types.ts

@@ -24,6 +24,13 @@ export interface Finding {
   rawValue: string;
   severity: Severity;
   nearestToken?: string;
+  // A suggested source replacement for `rawValue`, only ever set for
+  // "near-miss" or "match"-adjacent findings with a resolvable
+  // nearestToken — see suggestFix.ts. Left undefined (never an empty
+  // string) when no safe mechanical suggestion exists, e.g. a "missing"
+  // state finding, which needs a human to add real handling, not a
+  // value swap.
+  suggestion?: string;
 }
 
 export interface ScanResult {