maddox-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Ahmad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# maddox
+
+Scans source code 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.
+
+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.
+
+## Usage
+
+```bash
+npx maddox-engine <target-source-dir> <path-to-globals.css-with-@theme-block> [options]
+```
+
+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)
+- `--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
+
+### Example
+
+```bash
+npx maddox-engine ./src ./src/app/globals.css --project my-app --fail-below 80
+```
+
+### State contract
+
+An optional JSON file mapping a component-name pattern to the state names that component kind must cover:
+
+```json
+{
+  "Button": ["disabled", "loading"],
+  "*Input": ["error", "disabled"]
+}
+```
+
+Ground truth is explicit — nothing is inferred about which states a component "should" have.
+
+### 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.
+
+## Using in CI
+
+This repo is also a GitHub Action — `omrdev1/maddox-cli` — that runs a scan, posts the markdown report as a PR comment (updating the same comment on later pushes rather than piling up new ones), and optionally fails the build via `fail-below`.
+
+```yaml
+- uses: actions/checkout@v4
+- uses: omrdev1/maddox-cli@main
+  with:
+    target-dir: src
+    theme-css: src/app/globals.css
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    fail-below: "80"
+```
+
+Inputs:
+
+- `target-dir` *(required)* — 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
+- `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)
+
+Pin `@main` to a specific commit SHA if you want reproducible CI runs immune to changes on this branch.
+
+## License
+
+MIT

package/fixtures/grafikui-motion-tokens.json

@@ -0,0 +1,24 @@
+{
+  "progress": {
+    "easing": "easeOut",
+    "duration": 0.6
+  },
+  "entrance": {
+    "type": "spring",
+    "stiffness": 120,
+    "damping": 20
+  },
+  "transition": {
+    "ease": "easeOut",
+    "duration": 0.24
+  },
+  "stagger": {
+    "delay": 0.1
+  },
+  "nudge": {
+    "level1": { "opacity": 1, "y": 0, "transition": { "duration": 0.4, "ease": "easeOut" } },
+    "level2": { "opacity": 1, "x": 0, "transition": { "duration": 0.4, "ease": "easeOut" } },
+    "level3": { "opacity": 1, "x": 0, "transition": { "duration": 0.4, "ease": "easeOut" } },
+    "level4": { "opacity": 1, "x": 0, "transition": { "duration": 0.4, "ease": "easeOut" } }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "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.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "maddox": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "fixtures"
+  ],
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "drift",
+    "css",
+    "cli",
+    "ci"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omrdev1/maddox-cli.git"
+  },
+  "homepage": "https://www.maddoxengine.com",
+  "scripts": {
+    "scan": "tsx src/cli.ts",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env -S npx tsx
+
+import { readFileSync } from "node:fs";
+import { audit, 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) {
+  const response = await fetch(`${apiUrl}/api/scans`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Maddox-Api-Key": apiKey,
+    },
+    body: JSON.stringify({
+      projectName,
+      source: "cli",
+      filesScanned: summary.filesScanned,
+      findings: summary.findings,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Upload failed (${response.status}): ${body}`);
+  }
+
+  const result = (await response.json()) as { scanRunId: string };
+  console.error(`\nUploaded. Scan run: ${result.scanRunId}`);
+}
+
+function flagValue(name: string): string | undefined {
+  const i = process.argv.indexOf(name);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+
+async function main() {
+  const targetDir = process.argv[2];
+  const themeCssPath = process.argv[3];
+
+  if (!targetDir || !themeCssPath) {
+    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>]"
+    );
+    process.exit(1);
+  }
+
+  const projectName = flagValue("--project") ?? targetDir.split("/").pop() ?? "unnamed-project";
+  const format = flagValue("--format") ?? "text";
+
+  // Motion tokens are an optional external JSON file (a plain object like
+  // @grafikui/motion's motionTokens export) — the CLI has no opinion on any
+  // one target's motion system, so this stays a vendored/passed-in file
+  // per project rather than a hardcoded import.
+  const motionPath = flagValue("--motion");
+  const motionTokens = motionPath
+    ? (JSON.parse(readFileSync(motionPath, "utf-8")) as Record<string, unknown>)
+    : {};
+
+  const statesPath = flagValue("--states");
+  const stateContract = statesPath ? loadStateContract(statesPath) : undefined;
+
+  const groundTruth = loadGroundTruth(themeCssPath, motionTokens);
+  const result = await audit(targetDir, groundTruth, stateContract);
+  const summary = summarize(result.findings, result.filesScanned);
+
+  if (format === "json") {
+    console.log(toJson(summary));
+  } else if (format === "markdown") {
+    console.log(toMarkdown(summary));
+  } else {
+    console.log(toText(summary));
+  }
+
+  const apiKey = process.env.MADDOX_API_KEY;
+  const apiUrl = process.env.MADDOX_API_URL ?? "http://localhost:3000";
+
+  if (apiKey) {
+    await uploadResult(apiUrl, apiKey, projectName, summary);
+  } else if (format === "text") {
+    console.log("\nSet MADDOX_API_KEY to upload results to the dashboard.");
+  }
+
+  const failBelowRaw = flagValue("--fail-below");
+  if (failBelowRaw !== undefined) {
+    const threshold = Number(failBelowRaw);
+    if (Number.isNaN(threshold)) {
+      console.error(`\n--fail-below expects a number, got "${failBelowRaw}"`);
+      process.exit(1);
+    }
+
+    const score = healthScore(summary.counts);
+    console.error(`\nHealth score: ${score} (threshold: ${threshold})`);
+
+    if (score < threshold) {
+      console.error(`Maddox: drift below threshold — failing build (${score} < ${threshold}).`);
+      process.exit(1);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/core.ts

@@ -0,0 +1,29 @@
+export * from "./types.js";
+export * from "./groundTruth.js";
+export * from "./scan.js";
+export * from "./diff.js";
+export * from "./stateCheck.js";
+export * from "./healthScore.js";
+
+import { scanSource, scanFiles } from "./scan.js";
+import { diffUsages } from "./diff.js";
+import { checkStates } from "./stateCheck.js";
+import type { GroundTruth, ScanResult, StateContract } from "./types.js";
+
+export async function audit(
+  rootDir: string,
+  groundTruth: GroundTruth,
+  stateContract?: StateContract
+): Promise<ScanResult> {
+  const usages = await scanSource(rootDir);
+  const findings = diffUsages(usages, groundTruth);
+  const scannedFiles = new Set(usages.map((u) => u.file));
+
+  if (stateContract) {
+    const files = await scanFiles(rootDir);
+    findings.push(...checkStates(files, stateContract));
+    for (const f of files) scannedFiles.add(f.file);
+  }
+
+  return { findings, filesScanned: scannedFiles.size };
+}

package/src/diff.ts

@@ -0,0 +1,163 @@
+import type { RawUsage } from "./scan.js";
+import type { Finding, GroundTruth } from "./types.js";
+
+const NEAR_MISS_RGB_THRESHOLD = 25;
+const NEAR_MISS_NUMERIC_THRESHOLD = 0.05; // motion durations, e.g. seconds
+const NEAR_MISS_FONT_SIZE_PX_THRESHOLD = 2;
+
+function hexToRgb(hex: string): [number, number, number] | null {
+  // Only ever treat an actual "#..." literal as a color — a bare 3/6-digit
+  // string without the leading # (e.g. a z-index value like "999") is not
+  // a color and must not be matched against the color token pool.
+  if (!hex.startsWith("#")) return null;
+
+  const normalized = hex.replace(
+    /^#([a-f\d])([a-f\d])([a-f\d])$/i,
+    (_m, r, g, b) => `#${r}${r}${g}${g}${b}${b}`
+  );
+  const result = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(normalized);
+  if (!result) return null;
+  return [
+    parseInt(result[1], 16),
+    parseInt(result[2], 16),
+    parseInt(result[3], 16),
+  ];
+}
+
+function colorDistance(a: [number, number, number], b: [number, number, number]): number {
+  return Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+}
+
+function diffColor(usage: RawUsage, tokens: GroundTruth["tokens"]): Finding {
+  const usageRgb = hexToRgb(usage.rawValue);
+  if (!usageRgb) {
+    return { ...usage, severity: "unrecognized" };
+  }
+
+  let nearestToken: string | undefined;
+  let nearestDistance = Infinity;
+
+  for (const [name, value] of Object.entries(tokens)) {
+    const tokenRgb = hexToRgb(value);
+    if (!tokenRgb) continue;
+    const distance = colorDistance(usageRgb, tokenRgb);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestToken = name;
+    }
+  }
+
+  if (nearestDistance === 0) {
+    return { ...usage, severity: "match", nearestToken };
+  }
+  if (nearestDistance <= NEAR_MISS_RGB_THRESHOLD) {
+    return { ...usage, severity: "near-miss", nearestToken };
+  }
+  return { ...usage, severity: "unrecognized", nearestToken };
+}
+
+// Only these leaf names represent a duration in seconds — comparing a
+// scanned `duration: 0.8` against unrelated numeric leaves like `opacity`,
+// `stiffness`, or `damping` produces a nonsensical "nearest" match purely
+// by numeric proximity, since those are different units entirely.
+const DURATION_LEAF_NAMES = new Set(["duration", "delay"]);
+const EASE_LEAF_NAMES = new Set(["ease", "easing"]);
+
+function isDurationLeaf(path: string): boolean {
+  return DURATION_LEAF_NAMES.has(path.split(".").pop() ?? "");
+}
+function isEaseLeaf(path: string): boolean {
+  return EASE_LEAF_NAMES.has(path.split(".").pop() ?? "");
+}
+
+function diffMotion(usage: RawUsage, motion: GroundTruth["motion"]): Finding {
+  const usageNum = Number(usage.rawValue);
+  const isNumeric = !Number.isNaN(usageNum);
+  const candidates = motion.filter((t) => (isNumeric ? isDurationLeaf(t.path) : isEaseLeaf(t.path)));
+
+  let nearestToken: string | undefined;
+  let nearestDistance = Infinity;
+  let exact = false;
+
+  for (const token of candidates) {
+    if (isNumeric && typeof token.value === "number") {
+      const distance = Math.abs(usageNum - token.value);
+      if (distance < nearestDistance) {
+        nearestDistance = distance;
+        nearestToken = token.path;
+        exact = distance === 0;
+      }
+    } else if (!isNumeric && String(token.value) === usage.rawValue) {
+      nearestToken = token.path;
+      nearestDistance = 0;
+      exact = true;
+      break;
+    }
+  }
+
+  if (exact) return { ...usage, severity: "match", nearestToken };
+  if (isNumeric && nearestDistance <= NEAR_MISS_NUMERIC_THRESHOLD) {
+    return { ...usage, severity: "near-miss", nearestToken };
+  }
+  return { ...usage, severity: "unrecognized", nearestToken };
+}
+
+// Root font-size assumption for converting rem/em to px — the standard
+// browser default. Good enough for near-miss comparison purposes; this
+// isn't trying to resolve a page's actual computed root size.
+const ROOT_PX = 16;
+
+function toPx(value: string): number | null {
+  const m = /^([\d.]+)(px|rem|em)$/.exec(value.trim());
+  if (!m) return null;
+  const num = Number(m[1]);
+  if (m[2] === "px") return num;
+  return num * ROOT_PX;
+}
+
+function diffFontSize(usage: RawUsage, tokens: GroundTruth["tokens"]): Finding {
+  const exactMatch = Object.entries(tokens).find(([, value]) => value === usage.rawValue);
+  if (exactMatch) {
+    return { ...usage, severity: "match", nearestToken: exactMatch[0] };
+  }
+
+  const usagePx = toPx(usage.rawValue);
+  if (usagePx === null) {
+    return { ...usage, severity: "unrecognized" };
+  }
+
+  let nearestToken: string | undefined;
+  let nearestDistance = Infinity;
+
+  for (const [name, value] of Object.entries(tokens)) {
+    const tokenPx = toPx(value);
+    if (tokenPx === null) continue;
+    const distance = Math.abs(usagePx - tokenPx);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestToken = name;
+    }
+  }
+
+  if (nearestDistance <= NEAR_MISS_FONT_SIZE_PX_THRESHOLD) {
+    return { ...usage, severity: "near-miss", nearestToken };
+  }
+  return { ...usage, severity: "unrecognized", nearestToken };
+}
+
+export function diffUsages(usages: RawUsage[], groundTruth: GroundTruth): Finding[] {
+  return usages.map((usage) => {
+    if (usage.kind === "color") return diffColor(usage, groundTruth.tokens);
+    if (usage.kind === "motion") return diffMotion(usage, groundTruth.motion);
+    if (usage.kind === "font-size") return diffFontSize(usage, groundTruth.tokens);
+    // spacing: exact-string match against token values for now
+    const match = Object.entries(groundTruth.tokens).find(
+      ([, value]) => value === usage.rawValue
+    );
+    return {
+      ...usage,
+      severity: match ? "match" : "unrecognized",
+      nearestToken: match?.[0],
+    } satisfies Finding;
+  });
+}

package/src/format.ts

@@ -0,0 +1,75 @@
+import type { Finding } from "./core.js";
+
+export interface ScanSummary {
+  filesScanned: number;
+  counts: { match: number; "near-miss": number; unrecognized: number; missing: number };
+  findings: Finding[];
+}
+
+export function summarize(findings: Finding[], filesScanned: number): ScanSummary {
+  const counts = { match: 0, "near-miss": 0, unrecognized: 0, missing: 0 };
+  for (const f of findings) counts[f.severity]++;
+  return { filesScanned, counts, findings };
+}
+
+export function toJson(summary: ScanSummary): string {
+  return JSON.stringify(summary, null, 2);
+}
+
+export function toText(summary: ScanSummary): string {
+  const lines = [
+    `Scanned ${summary.filesScanned} files.`,
+    `  match:        ${summary.counts.match}`,
+    `  near-miss:    ${summary.counts["near-miss"]}`,
+    `  unrecognized: ${summary.counts.unrecognized}`,
+    `  missing:      ${summary.counts.missing}`,
+    "",
+  ];
+  for (const f of summary.findings) {
+    if (f.severity === "match") continue;
+    lines.push(
+      `${f.file}:${f.line}  [${f.kind}] ${f.rawValue}  → ${f.severity}${
+        f.nearestToken ? ` (nearest: ${f.nearestToken})` : ""
+      }`
+    );
+  }
+  return lines.join("\n");
+}
+
+const MARKER = "<!-- maddox-engine-drift-report -->";
+
+export function toMarkdown(summary: ScanSummary): string {
+  const { counts } = summary;
+  const total = counts.match + counts["near-miss"] + counts.unrecognized + counts.missing;
+  const nonMatch = summary.findings.filter((f) => f.severity !== "match");
+
+  const lines = [
+    MARKER,
+    "## Maddox Engine — Drift Report",
+    "",
+    `Scanned **${summary.filesScanned}** files, **${total}** token/motion/state checks.`,
+    "",
+    `| Match | Near-miss | Unrecognized | Missing state |`,
+    `|---|---|---|---|`,
+    `| ${counts.match} | ${counts["near-miss"]} | ${counts.unrecognized} | ${counts.missing} |`,
+    "",
+  ];
+
+  if (nonMatch.length === 0) {
+    lines.push("No drift found. Every checked value matches the design system.");
+    return lines.join("\n");
+  }
+
+  lines.push("<details><summary>Findings</summary>", "", "| Location | Kind | Value | Severity | Nearest token |", "|---|---|---|---|---|");
+  for (const f of nonMatch.slice(0, 100)) {
+    lines.push(
+      `| \`${f.file}:${f.line}\` | ${f.kind} | \`${f.rawValue}\` | ${f.severity} | ${f.nearestToken ? `\`${f.nearestToken}\`` : "—"} |`
+    );
+  }
+  if (nonMatch.length > 100) {
+    lines.push(`| ... | ${nonMatch.length - 100} more findings not shown | | | |`);
+  }
+  lines.push("", "</details>");
+
+  return lines.join("\n");
+}

package/src/groundTruth.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import type { GroundTruth, MotionToken, StateContract, TokenMap } from "./types.js";
+
+/**
+ * Parses a Tailwind v4 `@theme { ... }` block into a flat token map.
+ * Only reads inside the @theme block, not the rest of the CSS file.
+ */
+export function parseThemeTokens(cssFilePath: string): TokenMap {
+  const css = readFileSync(cssFilePath, "utf-8");
+  const themeMatch = css.match(/@theme\s*{([\s\S]*?)}/);
+  if (!themeMatch) return {};
+
+  const themeBlock = themeMatch[1];
+  const tokens: TokenMap = {};
+  const varRegex = /(--[\w-]+):\s*([^;]+);/g;
+  let match: RegExpExecArray | null;
+  while ((match = varRegex.exec(themeBlock)) !== null) {
+    tokens[match[1].trim()] = match[2].trim();
+  }
+  return tokens;
+}
+
+/**
+ * Flattens a nested motion tokens object (e.g. @grafikui/motion's
+ * `motionTokens` export) into dotted-path leaf values.
+ */
+export function flattenMotionTokens(
+  obj: Record<string, unknown>,
+  prefix = ""
+): MotionToken[] {
+  const out: MotionToken[] = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      out.push(...flattenMotionTokens(value as Record<string, unknown>, path));
+    } else if (typeof value === "number" || typeof value === "string") {
+      out.push({ path, value });
+    }
+  }
+  return out;
+}
+
+/**
+ * Loads a user-authored state contract: a JSON file mapping a component-name
+ * pattern to the state names that component kind must cover. There is no
+ * built-in inference of which states a component needs — the contract is
+ * the ground truth, same as the @theme block is for tokens.
+ */
+export function loadStateContract(path: string): StateContract {
+  return JSON.parse(readFileSync(path, "utf-8")) as StateContract;
+}
+
+export function loadGroundTruth(
+  themeCssPath: string,
+  motionTokensObj: Record<string, unknown>
+): GroundTruth {
+  return {
+    tokens: parseThemeTokens(themeCssPath),
+    motion: flattenMotionTokens(motionTokensObj),
+  };
+}

package/src/healthScore.ts

@@ -0,0 +1,20 @@
+// A single 0-100 health score for a scan run, weighted by how close each
+// checked value was to the design system: a full match counts fully, a
+// near-miss counts half (it drifted, but is still recognizably close to a
+// real token), and an unrecognized value counts for nothing. "missing"
+// (a state-completeness failure) is treated the same as unrecognized —
+// there's no partial credit for a component missing a required state.
+export interface SeverityCounts {
+  match: number;
+  "near-miss": number;
+  unrecognized: number;
+  missing?: number;
+}
+
+export function healthScore(counts: SeverityCounts): number {
+  const total = counts.match + counts["near-miss"] + counts.unrecognized + (counts.missing ?? 0);
+  if (total === 0) return 100;
+
+  const weighted = counts.match * 1 + counts["near-miss"] * 0.5;
+  return Math.round((weighted / total) * 100);
+}

package/src/scan.ts

@@ -0,0 +1,135 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export interface RawUsage {
+  file: string;
+  line: number;
+  kind: "color" | "spacing" | "font-size" | "motion";
+  rawValue: string;
+}
+
+const HEX_RE = /#([a-f0-9]{3}|[a-f0-9]{6})\b/gi;
+const FONT_SIZE_RE = /font-size:\s*([\d.]+(?:px|rem|em))/gi;
+const MOTION_DURATION_RE = /duration:\s*([\d.]+)/gi;
+const MOTION_EASE_RE = /ease:\s*['"]([\w-]+)['"]/gi;
+
+function lineNumberAt(content: string, index: number): number {
+  return content.slice(0, index).split("\n").length;
+}
+
+/**
+ * Extracts raw color/font-size/motion literals from a single blob of
+ * content. Exported directly (not just via scanSource's filesystem walk)
+ * so callers with in-memory content — e.g. fetched HTML/CSS from a public
+ * URL, with no local checkout — can run the same extraction.
+ */
+export function extractFromContent(file: string, content: string): RawUsage[] {
+  const usages: RawUsage[] = [];
+
+  for (const re of [HEX_RE]) {
+    re.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(content)) !== null) {
+      usages.push({
+        file,
+        line: lineNumberAt(content, m.index),
+        kind: "color",
+        rawValue: m[0].toLowerCase(),
+      });
+    }
+  }
+
+  FONT_SIZE_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = FONT_SIZE_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "font-size",
+      rawValue: m[1],
+    });
+  }
+
+  MOTION_DURATION_RE.lastIndex = 0;
+  while ((m = MOTION_DURATION_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "motion",
+      rawValue: m[1],
+    });
+  }
+
+  MOTION_EASE_RE.lastIndex = 0;
+  while ((m = MOTION_EASE_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "motion",
+      rawValue: m[1],
+    });
+  }
+
+  return usages;
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".next", ".git", ".turbo", "dist"]);
+const SCAN_EXTENSIONS = new Set([".ts", ".tsx", ".css"]);
+
+function walkDir(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walkDir(join(dir, entry.name), out);
+    } else if (entry.isFile()) {
+      const ext = entry.name.slice(entry.name.lastIndexOf("."));
+      if (SCAN_EXTENSIONS.has(ext)) out.push(join(dir, entry.name));
+    }
+  }
+}
+
+export interface ScannedFile {
+  file: string; // relative to rootDir
+  content: string;
+}
+
+/**
+ * Walks .ts/.tsx/.css files under `rootDir` (skipping node_modules/.next)
+ * and returns each file's relative path and content. Shared by the
+ * token/motion usage scan and the component state-completeness check.
+ */
+function readScannedFiles(rootDir: string): ScannedFile[] {
+  const filePaths: string[] = [];
+  walkDir(rootDir, filePaths);
+
+  const files: ScannedFile[] = [];
+  for (const fullPath of filePaths) {
+    try {
+      files.push({ file: relative(rootDir, fullPath), content: readFileSync(fullPath, "utf-8") });
+    } catch {
+      // unreadable file, skip
+    }
+  }
+  return files;
+}
+
+/**
+ * Walks .ts/.tsx/.css files under `rootDir` (skipping node_modules/.next)
+ * and extracts raw color/font-size/motion literals with file:line.
+ * Source-level scan, not a live-fetched-HTML scan.
+ */
+export async function scanSource(rootDir: string): Promise<RawUsage[]> {
+  const usages: RawUsage[] = [];
+  for (const { file, content } of readScannedFiles(rootDir)) {
+    usages.push(...extractFromContent(file, content));
+  }
+  return usages;
+}
+
+/**
+ * Same file walk as scanSource, but returning raw file contents for the
+ * component state-completeness check rather than token/motion usages.
+ */
+export async function scanFiles(rootDir: string): Promise<ScannedFile[]> {
+  return readScannedFiles(rootDir);
+}

package/src/stateCheck.ts

@@ -0,0 +1,67 @@
+import type { ScannedFile } from "./scan.js";
+import type { Finding, StateContract } from "./types.js";
+
+// Heuristic identifiers that count as "this state is handled" when they
+// appear anywhere in a component's file — a prop name, a CSS pseudo-class,
+// or a status string used in a conditional. This is string-matching, not
+// control-flow analysis: it can't tell whether the branch actually renders
+// correctly, only whether the concept is referenced at all.
+const STATE_IDENTIFIER_PATTERNS: Record<string, RegExp[]> = {
+  disabled: [/\bdisabled\b/i, /:disabled/i],
+  loading: [/\bloading\b/i, /\bisLoading\b/i, /\bpending\b/i],
+  error: [/\berror\b/i, /\bisError\b/i],
+  empty: [/\bempty\b/i, /\bisEmpty\b/i],
+  active: [/\bactive\b/i, /:active/i, /\bisActive\b/i],
+  hover: [/:hover/i, /\bonHover\b/i, /\bisHovered\b/i],
+  focus: [/:focus/i, /\bonFocus\b/i, /\bisFocused\b/i],
+};
+
+function hasState(content: string, state: string): boolean {
+  const patterns = STATE_IDENTIFIER_PATTERNS[state.toLowerCase()];
+  if (patterns) return patterns.some((re) => re.test(content));
+  // No built-in heuristic for this state name — fall back to a plain
+  // word-boundary match on the state name itself.
+  return new RegExp(`\\b${state}\\b`, "i").test(content);
+}
+
+function matchesPattern(fileName: string, pattern: string): boolean {
+  if (pattern.includes("*")) {
+    const re = new RegExp(`^${pattern.split("*").map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "i");
+    return re.test(fileName);
+  }
+  return fileName.toLowerCase().includes(pattern.toLowerCase());
+}
+
+/**
+ * Checks each scanned file against the state contract: if the file's name
+ * matches a contract pattern, every required state for that pattern must
+ * have at least one matching identifier somewhere in the file's content.
+ * Emits one Finding per missing state; matched states are not reported
+ * (kept consistent with diffUsages, which also only ever needs to explain
+ * non-matches — matches are implicit by absence of a finding).
+ */
+export function checkStates(files: ScannedFile[], contract: StateContract): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const { file, content } of files) {
+    const fileName = file.split("/").pop() ?? file;
+
+    for (const [pattern, requiredStates] of Object.entries(contract)) {
+      if (!matchesPattern(fileName, pattern)) continue;
+
+      for (const state of requiredStates) {
+        if (hasState(content, state)) continue;
+        findings.push({
+          file,
+          line: 1,
+          kind: "state",
+          rawValue: state,
+          severity: "missing",
+          nearestToken: pattern,
+        });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export type TokenMap = Record<string, string>;
+
+export interface MotionToken {
+  path: string; // e.g. "progress.duration"
+  value: number | string;
+}
+
+export interface GroundTruth {
+  tokens: TokenMap;
+  motion: MotionToken[];
+}
+
+// Maps a component-name pattern (matched against each scanned file's
+// basename) to the list of state names that component kind must cover,
+// e.g. { "Button": ["disabled", "loading"], "*Input": ["error", "disabled"] }.
+export type StateContract = Record<string, string[]>;
+
+export type Severity = "match" | "near-miss" | "unrecognized" | "missing";
+
+export interface Finding {
+  file: string;
+  line: number;
+  kind: "color" | "spacing" | "font-size" | "motion" | "state";
+  rawValue: string;
+  severity: Severity;
+  nearestToken?: string;
+}
+
+export interface ScanResult {
+  findings: Finding[];
+  filesScanned: number;
+}