maddox-engine 0.1.0 → 0.2.0

package/README.md

@@ -23,6 +23,7 @@ Options:
 - `--project <name>` — project name (defaults to the target directory's basename)
 - `--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)
+- `--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
 - `--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 +46,14 @@ 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.
+
+### 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.
@@ -69,6 +78,7 @@ Inputs:
 - `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
+- `tokens-studio` — path to a Tokens Studio / W3C Design Tokens JSON export
 - `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,6 +1,6 @@
 {
   "name": "maddox-engine",
-  "version": "0.1.0",
+  "version": "0.2.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.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -42,7 +42,7 @@ async function main() {
       "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>]"
     );
     process.exit(1);
   }
@@ -62,7 +62,8 @@ async function main() {
   const statesPath = flagValue("--states");
   const stateContract = statesPath ? loadStateContract(statesPath) : undefined;
 
-  const groundTruth = loadGroundTruth(themeCssPath, motionTokens);
+  const tokensStudioPath = flagValue("--tokens-studio");
+  const groundTruth = loadGroundTruth(themeCssPath, motionTokens, tokensStudioPath);
   const result = await audit(targetDir, groundTruth, stateContract);
   const summary = summarize(result.findings, result.filesScanned);
 

package/src/core.ts

@@ -1,13 +1,16 @@
 export * from "./types.js";
 export * from "./groundTruth.js";
+export * from "./tokensStudio.js";
 export * from "./scan.js";
 export * from "./diff.js";
 export * from "./stateCheck.js";
 export * from "./healthScore.js";
+export * from "./suggestFix.js";
 
 import { scanSource, scanFiles } from "./scan.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 +28,7 @@ export async function audit(
     for (const f of files) scannedFiles.add(f.file);
   }
 
+  attachSuggestions(findings);
+
   return { findings, filesScanned: scannedFiles.size };
 }

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 {