feat(audit): APPLY=1 auto-fixes raw_color violations to var(--token)

Adds Audit::AutoFixer that rewrites source files in place when an
exact-match CSS custom property token exists for a raw_color violation.
Only :raw_color + :css_var combinations qualify — SCSS variables don't
work in HTML attributes, and tailwind_arbitrary fixes need theme-aware
logic that's not in scope here.

Replacements happen right-to-left within a line so column positions
stay valid, and the existing source text is verified at the expected
column before any write so a stale violation list can't corrupt the
file.

When APPLY=1 and SUGGEST=1 are combined, the markdown checklist only
lists violations that weren't auto-fixed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jathayde

lib/guardrails/audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "set"
 require "stringio"
 
 module Guardrails
@@ -22,18 +23,20 @@ class Audit
     CLASS_ATTRIBUTE_SINGLE = /\bclass\s*=\s*'([^']*)'/
     ARBITRARY_VALUE_PATTERN = /\[[^\]]+\]/
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false)
       @root = Pathname(root)
       @output = output
       @suggest = suggest
       @format = format
+      @apply = apply
     end
 
     def run
       violations = collect_files.flat_map { |file| scan_file(file) }
       print_report(violations)
-      write_suggestions(violations) if @suggest
-      violations
+      remaining = @apply ? apply_auto_fixes(violations) : violations
+      write_suggestions(remaining) if @suggest
+      remaining
     end
 
     private
@@ -169,9 +172,25 @@ def snippet(lines, idx)
       lines[idx]&.chomp&.strip
     end
 
+    def apply_auto_fixes(violations)
+      require_relative "audit/auto_fixer"
+      fixer = AutoFixer.new(@root, output: @output, tokens: view_safe_tokens)
+      applied = fixer.apply(violations)
+      fixed_keys = applied.map { |r| [r.violation.file, r.violation.line, r.violation.column] }.to_set
+      violations.reject { |v| fixed_keys.include?([v.file, v.line, v.column]) }
+    end
+
     def write_suggestions(violations)
       require_relative "audit/markdown_writer"
-      MarkdownWriter.new(@root, output: @output, tokens: load_tokens).write(violations)
+      MarkdownWriter.new(@root, output: @output, tokens: view_safe_tokens).write(violations)
+    end
+
+    def view_safe_tokens
+      # Views (HTML/ERB) cannot reference SCSS variables — `$primary` only
+      # exists at SCSS compile time. CSS custom properties (`var(--primary)`)
+      # work in any HTML/CSS context, so those are the only tokens that map
+      # cleanly into a view violation's source.
+      load_tokens.select { |t| t.syntax == :css_var }
     end
 
     def load_tokens

lib/guardrails/audit/auto_fixer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../hex_normalizer"
+
+module Guardrails
+  class Audit
+    class AutoFixer
+      Result = Struct.new(:violation, :token, :replacement, keyword_init: true)
+
+      def initialize(root, output: $stdout, tokens: [])
+        @root = Pathname(root)
+        @output = output
+        @lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
+      end
+
+      def apply(violations)
+        applicable = violations.select { |v| applicable?(v) }
+        return [] if applicable.empty?
+
+        applied = applicable.group_by(&:file).flat_map do |file, file_violations|
+          process_file(@root.join(file), file_violations)
+        end
+
+        report(applied)
+        applied
+      end
+
+      def applicable?(violation)
+        return false unless violation.type == :raw_color
+
+        token = matched_token(violation)
+        !token.nil? && token.syntax == :css_var
+      end
+
+      private
+
+      def matched_token(violation)
+        return nil if violation.value.nil?
+
+        @lookup[HexNormalizer.normalize(violation.value)]
+      end
+
+      def process_file(path, violations)
+        return [] unless path.exist?
+
+        original = File.read(path, encoding: Encoding::UTF_8)
+        lines = original.lines
+        applied = []
+
+        violations.group_by(&:line).each do |line_num, line_violations|
+          line_idx = line_num - 1
+          next unless lines[line_idx]
+
+          line_violations.sort_by { |v| -v.column }.each do |v|
+            token = matched_token(v)
+            next unless token
+
+            current_line = lines[line_idx]
+            start_idx = v.column - 1
+            value_length = v.value.length
+            next unless current_line[start_idx, value_length] == v.value
+
+            replacement = "var(--#{token.name})"
+            lines[line_idx] = current_line[0...start_idx] + replacement + current_line[(start_idx + value_length)..]
+            applied << Result.new(violation: v, token: token, replacement: replacement)
+          end
+        end
+
+        new_content = lines.join
+        File.write(path, new_content, encoding: Encoding::UTF_8) if new_content != original
+        applied
+      end
+
+      def report(applied)
+        return if applied.empty?
+
+        @output.puts ""
+        noun = applied.length == 1 ? "fix" : "fixes"
+        @output.puts "Guardrails audit: applied #{applied.length} auto-#{noun} (raw_color → CSS custom property)"
+        applied.each do |r|
+          @output.puts "  #{r.violation.file}:#{r.violation.line}  #{r.violation.value} → #{r.replacement}"
+        end
+      end
+    end
+  end
+end

lib/tasks/guardrails.rake

@@ -8,14 +8,15 @@ namespace :guardrails do
     Guardrails::Init.new(root: root).run
   end
 
-  desc "Audit views and components for UI drift (SUGGEST=1 writes markdown; FORMAT=json for machine-readable output)"
+  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json)"
   task :audit do
     require "guardrails/audit"
     require "guardrails/stimulus_audit"
     root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
     suggest = %w[1 true yes].include?(ENV["SUGGEST"]&.downcase)
+    apply = %w[1 true yes].include?(ENV["APPLY"]&.downcase)
     format = ENV["FORMAT"]&.downcase == "json" ? :json : :text
-    violations = Guardrails::Audit.new(root: root, suggest: suggest, format: format).run
+    violations = Guardrails::Audit.new(root: root, suggest: suggest, apply: apply, format: format).run
     stimulus = Guardrails::StimulusAudit.new(root: root).run
     exit 1 if violations.any? || stimulus.violations?
   end

spec/guardrails/audit/auto_fixer_spec.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "stringio"
+require "guardrails/audit"
+require "guardrails/audit/auto_fixer"
+require "guardrails/tokens"
+
+RSpec.describe Guardrails::Audit::AutoFixer do
+  let(:root) { Pathname(Dir.mktmpdir) }
+  after { FileUtils.rm_rf(root) }
+
+  def write_view(relative, content)
+    full = root.join(relative)
+    full.dirname.mkpath
+    full.write(content)
+  end
+
+  def view_content(relative)
+    root.join(relative).read(encoding: Encoding::UTF_8)
+  end
+
+  def violation(type:, file:, line:, column:, value:, snippet: "")
+    Guardrails::Audit::Violation.new(
+      type: type, file: file, line: line, column: column, snippet: snippet, value: value
+    )
+  end
+
+  def token(name:, value:, syntax: :css_var)
+    Guardrails::Tokens::Token.new(
+      name: name, value: value, syntax: syntax,
+      file: "tokens.css", line: 1
+    )
+  end
+
+  describe "#apply" do
+    it "rewrites a raw_color hex with var(--token) when an exact CSS-var match exists" do
+      write_view "app/views/x.html.erb", '<svg fill="#0066ff"></svg>'
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#0066ff")
+      tokens = [token(name: "primary-500", value: "#0066ff")]
+
+      described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(view_content("app/views/x.html.erb")).to eq('<svg fill="var(--primary-500)"></svg>')
+    end
+
+    it "matches normalized hex (case + short form)" do
+      write_view "app/views/x.html.erb", '<svg fill="#fa3"></svg>'
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#fa3")
+      tokens = [token(name: "secondary", value: "#FFAA33")]
+
+      described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(view_content("app/views/x.html.erb")).to include("var(--secondary)")
+    end
+
+    it "applies multiple replacements on the same line right-to-left" do
+      write_view "app/views/x.html.erb", '<svg fill="#0066ff" stroke="#fa3"></svg>'
+      vs = [
+        violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#0066ff"),
+        violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 29, value: "#fa3")
+      ]
+      tokens = [
+        token(name: "primary", value: "#0066ff"),
+        token(name: "secondary", value: "#fa3")
+      ]
+
+      described_class.new(root, output: StringIO.new, tokens: tokens).apply(vs)
+
+      content = view_content("app/views/x.html.erb")
+      expect(content).to include("var(--primary)")
+      expect(content).to include("var(--secondary)")
+    end
+
+    it "does not apply for SCSS variable tokens (not valid in views)" do
+      write_view "app/views/x.html.erb", '<svg fill="#0066ff"></svg>'
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#0066ff")
+      tokens = [token(name: "primary", value: "#0066ff", syntax: :scss_var)]
+
+      result = described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(result).to be_empty
+      expect(view_content("app/views/x.html.erb")).to eq('<svg fill="#0066ff"></svg>')
+    end
+
+    it "does not apply when no token matches" do
+      write_view "app/views/x.html.erb", '<svg fill="#abcdef"></svg>'
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#abcdef")
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      result = described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(result).to be_empty
+      expect(view_content("app/views/x.html.erb")).to eq('<svg fill="#abcdef"></svg>')
+    end
+
+    it "skips inline_style violations" do
+      v = violation(type: :inline_style, file: "app/views/x.html.erb", line: 1, column: 1, value: 'style="color: red"')
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      fixer = described_class.new(root, output: StringIO.new, tokens: tokens)
+      expect(fixer.applicable?(v)).to be(false)
+    end
+
+    it "skips tailwind_arbitrary violations" do
+      v = violation(type: :tailwind_arbitrary, file: "app/views/x.html.erb", line: 1, column: 1, value: "#0066ff")
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      fixer = described_class.new(root, output: StringIO.new, tokens: tokens)
+      expect(fixer.applicable?(v)).to be(false)
+    end
+
+    it "verifies the value is at the expected column before replacing" do
+      write_view "app/views/x.html.erb", "<p>different content</p>"
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#0066ff")
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      result = described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(result).to be_empty
+      expect(view_content("app/views/x.html.erb")).to eq("<p>different content</p>")
+    end
+
+    it "returns Result entries with the violation, token, and replacement string" do
+      write_view "app/views/x.html.erb", '<svg fill="#0066ff"></svg>'
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", line: 1, column: 12, value: "#0066ff")
+      tokens = [token(name: "primary-500", value: "#0066ff")]
+
+      result = described_class.new(root, output: StringIO.new, tokens: tokens).apply([v])
+
+      expect(result.length).to eq(1)
+      expect(result.first.token.name).to eq("primary-500")
+      expect(result.first.replacement).to eq("var(--primary-500)")
+    end
+
+    it "applies fixes across multiple files" do
+      write_view "app/views/a.html.erb", '<svg fill="#0066ff"></svg>'
+      write_view "app/views/b.html.erb", '<svg fill="#0066ff"></svg>'
+      vs = [
+        violation(type: :raw_color, file: "app/views/a.html.erb", line: 1, column: 12, value: "#0066ff"),
+        violation(type: :raw_color, file: "app/views/b.html.erb", line: 1, column: 12, value: "#0066ff")
+      ]
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      described_class.new(root, output: StringIO.new, tokens: tokens).apply(vs)
+
+      expect(view_content("app/views/a.html.erb")).to include("var(--primary)")
+      expect(view_content("app/views/b.html.erb")).to include("var(--primary)")
+    end
+  end
+end