maddox-engine 0.3.0 → 0.4.0

package/README.md

@@ -25,6 +25,7 @@ Options:
 - `--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
+- `--apply-fixes` — write near-miss color/font-size/spacing suggestions back into source files (see below); not available with `--url`
 - `--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
 
@@ -68,7 +69,22 @@ Third-party stylesheets (a different origin than the page itself, e.g. a font CD
 
 ### 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.
+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). By default it's advisory text for you to apply yourself; pass `--apply-fixes` to write it back into the file. An `unrecognized` value with no close match, and a `missing`-state finding, never get a suggestion — there's no safe mechanical fix for either.
+
+### Applying fixes automatically
+
+```bash
+npx maddox-engine ./src ./src/app/globals.css --apply-fixes
+```
+
+`--apply-fixes` writes every `color`/`font-size`/`spacing` near-miss suggestion straight into the source file it was found in, replacing the exact literal with `var(--token-name)`. It's scoped deliberately narrow:
+
+- **Motion suggestions are never applied.** `motionTokens.path.to.value` assumes an import named `motionTokens` exists in that file's scope — there's no way to verify that per-file, and applying it blind could silently break the build. Motion findings always stay advisory-only.
+- **State findings never had a suggestion to apply.**
+- If a finding's line no longer contains its reported value (the file changed since the scan ran), it's skipped rather than guessed at.
+- Not available with `--url` — a fetched page has no local file to write to.
+
+This is a real edit to your working tree, not a dry run — review the diff (`git diff`) before committing, same as you would any other automated change.
 
 ### Health score
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maddox-engine",
-  "version": "0.3.0",
+  "version": "0.4.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",

package/src/applyFixes.ts

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding } from "./types.js";
+
+// Only these kinds get a self-contained, always-valid replacement
+// expression (var(--token-name), which needs no import and can't break
+// compilation in any file it lands in). "motion" suggestions read
+// motionTokens.path.to.value — text that assumes an import named
+// motionTokens exists in scope, which suggestFix.ts has no way to verify
+// per-file, so applying it mechanically could silently break the build.
+// "state" findings never get a suggestion at all (see suggestFix.ts).
+const AUTO_APPLIABLE_KINDS = new Set<Finding["kind"]>(["color", "font-size", "spacing"]);
+
+export interface AppliedFix {
+  file: string;
+  line: number;
+  rawValue: string;
+  suggestion: string;
+  occurrences: number;
+}
+
+export interface ApplyFixesResult {
+  applied: AppliedFix[];
+  // Findings that had a suggestion but were skipped — motion (unsafe
+  // import assumption) or a line whose current content no longer
+  // contains rawValue (the file changed since the scan ran; applying
+  // blind here risks touching the wrong text).
+  skipped: Finding[];
+}
+
+/**
+ * Writes suggestFix's suggestions back into source files, for findings
+ * whose kind has a self-contained replacement expression. Never touches
+ * "motion" or "state" findings — see AUTO_APPLIABLE_KINDS.
+ *
+ * Applies per-file: reads once, replaces every exact-value occurrence
+ * on each finding's reported line (same literal repeated on one line —
+ * e.g. `color: #0d0d0d; border-color: #0d0d0d;` — is the same drift
+ * twice, both get fixed), writes once. A finding whose line no longer
+ * contains its rawValue (file changed since the scan that produced this
+ * Finding) is skipped rather than guessed at.
+ *
+ * rootDir is the same directory audit() was called with — Finding.file
+ * is relative to it, matching how scanSource reports paths.
+ */
+export function applyFixes(rootDir: string, findings: Finding[]): ApplyFixesResult {
+  const applied: AppliedFix[] = [];
+  const skipped: Finding[] = [];
+
+  const byFile = new Map<string, Finding[]>();
+  for (const finding of findings) {
+    if (!finding.suggestion || !AUTO_APPLIABLE_KINDS.has(finding.kind)) {
+      if (finding.suggestion) skipped.push(finding);
+      continue;
+    }
+    const existing = byFile.get(finding.file) ?? [];
+    existing.push(finding);
+    byFile.set(finding.file, existing);
+  }
+
+  for (const [file, fileFindings] of byFile) {
+    const fullPath = join(rootDir, file);
+    let content: string;
+    try {
+      content = readFileSync(fullPath, "utf-8");
+    } catch {
+      skipped.push(...fileFindings);
+      continue;
+    }
+
+    const lines = content.split("\n");
+    let changed = false;
+
+    // Dedupe by (line, rawValue): the replace below already handles every
+    // occurrence of a value on its line in one pass, so if the scan
+    // reported the same value on the same line more than once (e.g. two
+    // separate regex matches for one literal repeated in a line), only
+    // the first needs to actually run the replacement — without this, a
+    // second finding for an already-fixed line would find nothing left to
+    // replace and land in `skipped`, misreporting an applied fix as one
+    // that failed.
+    const seen = new Set<string>();
+    const uniqueFindings = fileFindings.filter((f) => {
+      const key = `${f.line}:${f.rawValue}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+    for (const finding of uniqueFindings) {
+      const lineIndex = finding.line - 1;
+      const line = lines[lineIndex];
+      if (line === undefined || !line.includes(finding.rawValue)) {
+        skipped.push(finding);
+        continue;
+      }
+
+      const occurrences = line.split(finding.rawValue).length - 1;
+      lines[lineIndex] = line.split(finding.rawValue).join(finding.suggestion!);
+      changed = true;
+      applied.push({
+        file,
+        line: finding.line,
+        rawValue: finding.rawValue,
+        suggestion: finding.suggestion!,
+        occurrences,
+      });
+    }
+
+    if (changed) {
+      writeFileSync(fullPath, lines.join("\n"));
+    }
+  }
+
+  return { applied, skipped };
+}

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npx tsx
 
 import { readFileSync } from "node:fs";
-import { audit, auditUrl, healthScore, loadGroundTruth, loadStateContract } from "./core.js";
+import { applyFixes, 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) {
@@ -44,10 +44,13 @@ async function main() {
         "[--project <name>] [--motion <path-to-motion-tokens.json>] " +
         "[--states <path-to-state-contract.json>] [--format text|json|markdown] " +
         "[--fail-below <0-100>] [--tokens-studio <path-to-tokens-studio-export.json>] " +
-        "[--url <live-page-url>]\n" +
+        "[--url <live-page-url>] [--apply-fixes]\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."
+        "--states has no effect in --url mode: state-completeness is a source-code check.\n" +
+        "  --apply-fixes writes near-miss color/font-size/spacing suggestions back into " +
+        "source files (color/font-size/spacing only — motion and state findings are " +
+        "never auto-applied). Not available with --url, which has no source to write to."
     );
     process.exit(1);
   }
@@ -73,6 +76,25 @@ async function main() {
   const result = url ? await auditUrl(url, groundTruth) : await audit(targetDir, groundTruth, stateContract);
   const summary = summarize(result.findings, result.filesScanned);
 
+  const applyFixesFlag = process.argv.includes("--apply-fixes");
+  if (applyFixesFlag) {
+    if (url) {
+      console.error("\n--apply-fixes has no effect with --url: there is no local source to write to.");
+    } else {
+      const { applied, skipped } = applyFixes(targetDir, result.findings);
+      if (applied.length > 0) {
+        console.error(`\nApplied ${applied.length} fix${applied.length === 1 ? "" : "es"}:`);
+        for (const fix of applied) {
+          console.error(`  ${fix.file}:${fix.line}  ${fix.rawValue} → ${fix.suggestion}`);
+        }
+      }
+      const motionOrStateSkipped = skipped.filter((f) => f.kind === "motion" || f.kind === "state").length;
+      if (motionOrStateSkipped > 0) {
+        console.error(`\n${motionOrStateSkipped} motion/state finding${motionOrStateSkipped === 1 ? "" : "s"} skipped — not auto-applied (see usage).`);
+      }
+    }
+  }
+
   if (format === "json") {
     console.log(toJson(summary));
   } else if (format === "markdown") {

package/src/core.ts

@@ -7,6 +7,7 @@ export * from "./diff.js";
 export * from "./stateCheck.js";
 export * from "./healthScore.js";
 export * from "./suggestFix.js";
+export * from "./applyFixes.js";
 
 import { scanSource, scanFiles } from "./scan.js";
 import { crawlUrl } from "./crawl.js";