ui_guardrails 1.0.0

data/lib/guardrails/icons.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Guardrails
+  class Icons
+    Violation = Struct.new(:type, :file, :line, :column, :snippet, keyword_init: true)
+
+    DEFAULT_SOURCE = "app/assets/images/icons"
+    DEFAULT_SPRITE_OUTPUT = "app/assets/images/icons/sprite.svg"
+    DEFAULT_VIEWBOX = "0 0 24 24"
+
+    VIEW_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb"
+    ].freeze
+
+    SVG_OPEN_TAG = /<svg\b([^>]*)>/m
+    SVG_INNER = /<svg\b[^>]*>([\s\S]*?)<\/svg>/m
+    SVG_BLOCK_PATTERN = /<svg\b[^>]*>[\s\S]*?<\/svg>/m
+    VIEWBOX_ATTR = /\bviewBox\s*=\s*["']([^"']+)["']/i
+    ERB_BLOCK_PATTERN = /<%[\s\S]*?%>/
+
+    # Patterns that indicate an icon is in use. We're conservative on this
+    # side — false negatives (saying "alive" when actually dead) just
+    # leave dead icons in source; false positives (saying "dead" when
+    # actually used) cause the user to delete files they need.
+    #
+    # Each pattern allows an optional directory prefix before the basename
+    # (e.g. `image_tag "icons/check.svg"` for files under
+    # `app/assets/images/icons/`) and captures only the bare name so it
+    # matches against icons collected from disk.
+    USAGE_PATTERNS = [
+      # Sprite reference: <use href="#icon-foo">
+      /#icon-([\w-]+)/,
+      # Rails image_tag "foo.svg" / image_tag "icons/foo.svg"
+      /\bimage_tag\s*\(?\s*["'](?:[^"']*\/)?([\w-]+)\.(?:svg|png|gif|jpe?g|webp)["']/,
+      # Rails asset_path / asset_url / image_path / image_url with optional path
+      /\b(?:asset_path|asset_url|image_path|image_url)\s*\(?\s*["'](?:[^"']*\/)?([\w-]+)\.(?:svg|png|gif|jpe?g|webp)["']/,
+      # CSS url() references in stylesheets and inline style attributes
+      /url\s*\(\s*["']?(?:[^"')]*\/)?([\w-]+)\.(?:svg|png|gif|jpe?g|webp)/i
+    ].freeze
+
+    USAGE_SCAN_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb",
+      "app/components/**/*.rb",
+      "app/assets/stylesheets/**/*.{css,scss,sass}",
+      "app/javascript/**/*.{js,ts,jsx,tsx}"
+    ].freeze
+
+    def initialize(root:, output: $stdout, source: nil, sprite_output: nil)
+      @root = Pathname(root)
+      @output = output
+      config = load_config
+
+      @source = resolve_path(source || config.dig("guardrails", "icons", "source") || DEFAULT_SOURCE)
+      @sprite_output = resolve_path(sprite_output || config.dig("guardrails", "icons", "sprite_output") || DEFAULT_SPRITE_OUTPUT)
+    end
+
+    def run
+      generate_sprite
+      violations = audit_inline_svgs
+      report_inline_svgs(violations)
+      dead_report = report_dead_icons
+      print_dead_report(dead_report)
+      { inline_svgs: violations, dead_icons: dead_report[:dead], unknown_refs: dead_report[:unknown] }
+    end
+
+    def audit_inline_svgs
+      view_files.flat_map { |file| scan_view_for_inline_svgs(file) }
+    end
+
+    def report_dead_icons
+      icon_names = collect_icon_names
+      used_names = collect_used_icon_names
+      {
+        dead: (icon_names - used_names).sort,
+        unknown: (used_names - icon_names).sort
+      }
+    end
+
+    def generate_sprite
+      svgs = collect_svgs
+      if svgs.empty?
+        @output.puts "No SVGs found in #{relative(@source)}"
+        return nil
+      end
+
+      symbols = svgs.filter_map { |file| build_symbol(file) }
+      sprite = wrap_sprite(symbols)
+
+      @sprite_output.dirname.mkpath
+      File.write(@sprite_output, sprite, encoding: Encoding::UTF_8)
+      @output.puts "Wrote sprite with #{symbols.length} icons to #{relative(@sprite_output)}"
+      @sprite_output
+    end
+
+    private
+
+    def load_config
+      path = @root.join("guardrails.yml")
+      return {} unless path.exist?
+
+      YAML.safe_load_file(path) || {}
+    end
+
+    def resolve_path(path)
+      pathname = Pathname(path)
+      pathname.absolute? ? pathname : @root.join(pathname)
+    end
+
+    def collect_svgs
+      return [] unless @source.exist?
+
+      Dir.glob(@source.join("*.svg"))
+        .map { |path| Pathname(path) }
+        .reject { |path| path == @sprite_output }
+        .sort_by { |path| path.basename.to_s }
+    end
+
+    def build_symbol(file)
+      content = File.read(file, encoding: Encoding::UTF_8)
+      open_tag = content.match(SVG_OPEN_TAG)
+      inner_match = content.match(SVG_INNER)
+      return nil unless open_tag && inner_match
+
+      viewbox = open_tag[1].match(VIEWBOX_ATTR)&.[](1) || DEFAULT_VIEWBOX
+      inner = inner_match[1].strip
+      return nil if inner.empty?
+
+      name = file.basename(".svg").to_s
+      %(  <symbol id="icon-#{name}" viewBox="#{viewbox}">#{inner}</symbol>)
+    end
+
+    def wrap_sprite(symbols)
+      <<~SVG
+        <svg xmlns="http://www.w3.org/2000/svg" style="display: none">
+        #{symbols.join("\n")}
+        </svg>
+      SVG
+    end
+
+    def relative(path)
+      path.relative_path_from(@root).to_s
+    rescue ArgumentError
+      path.to_s
+    end
+
+    def view_files
+      VIEW_PATTERNS
+        .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .map { |path| Pathname(path) }
+        .uniq
+    end
+
+    def scan_view_for_inline_svgs(file)
+      content = File.read(file, encoding: Encoding::UTF_8)
+      masked = mask_erb(content)
+
+      violations = []
+      masked.scan(SVG_BLOCK_PATTERN) do
+        match = Regexp.last_match
+        block = match[0]
+        next if block.include?("<use")
+
+        offset = match.begin(0)
+        line_num = masked[0...offset].count("\n") + 1
+
+        violations << Violation.new(
+          type: :inline_svg,
+          file: file.relative_path_from(@root).to_s,
+          line: line_num,
+          column: 1,
+          snippet: block.lines.first&.chomp&.strip
+        )
+      end
+      violations
+    end
+
+    def mask_erb(content)
+      content.gsub(ERB_BLOCK_PATTERN) do |match|
+        newline_count = match.count("\n")
+        "\n" * newline_count + " " * (match.length - newline_count)
+      end
+    end
+
+    def collect_icon_names
+      collect_svgs.map { |path| path.basename(".svg").to_s }
+    end
+
+    def collect_used_icon_names
+      usage_files.flat_map do |file|
+        content = File.read(file, encoding: Encoding::UTF_8)
+        USAGE_PATTERNS.flat_map { |pattern| content.scan(pattern).flatten }
+      end.uniq
+    end
+
+    def usage_files
+      USAGE_SCAN_PATTERNS
+        .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .map { |path| Pathname(path) }
+        .uniq
+    end
+
+    def print_dead_report(report)
+      return if report[:dead].empty? && report[:unknown].empty?
+
+      @output.puts ""
+      unless report[:dead].empty?
+        @output.puts "Guardrails icons: #{report[:dead].length} unused icon#{'s' if report[:dead].length != 1} in source"
+        report[:dead].each { |name| @output.puts "  - #{name}" }
+      end
+      unless report[:unknown].empty?
+        @output.puts "Guardrails icons: #{report[:unknown].length} reference#{'s' if report[:unknown].length != 1} to icons not in source"
+        report[:unknown].each { |name| @output.puts "  - #{name}" }
+      end
+    end
+
+    def report_inline_svgs(violations)
+      return if violations.empty?
+
+      noun = violations.length == 1 ? "inline SVG" : "inline SVGs"
+      @output.puts ""
+      @output.puts "Guardrails icons: #{violations.length} #{noun} found in views (should reference the sprite via <use>)"
+      violations.each do |v|
+        @output.puts "  [#{v.type}] #{v.file}:#{v.line}"
+        @output.puts "    #{v.snippet}"
+      end
+    end
+  end
+end

data/lib/guardrails/init/config_writer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Guardrails
+  class Init
+    class ConfigWriter
+      CONFIG_FILENAME = "guardrails.yml"
+
+      DEFAULT_TOKEN_PATHS = {
+        css_custom_properties: {
+          "colors_file" => "app/assets/stylesheets/tokens/_colors.css",
+          "type_scale_file" => "app/assets/stylesheets/tokens/_type.css"
+        },
+        scss_variables: {
+          "colors_file" => "app/assets/stylesheets/tokens/_colors.scss",
+          "type_scale_file" => "app/assets/stylesheets/tokens/_type.scss"
+        },
+        raw_hex: {
+          "colors_file" => nil,
+          "type_scale_file" => nil
+        },
+        none: {
+          "colors_file" => nil,
+          "type_scale_file" => nil
+        }
+      }.freeze
+
+      def initialize(root, output: $stdout, now: Time.now)
+        @root = Pathname(root)
+        @output = output
+        @now = now
+      end
+
+      def write(detection_result, overrides: {}, force: false)
+        path = @root.join(CONFIG_FILENAME)
+        existed = path.exist?
+        if existed && !force
+          @output.puts "#{CONFIG_FILENAME} already exists — refusing to overwrite."
+          @output.puts "Delete or rename it, or set FORCE=1 to re-run init."
+          return false
+        end
+
+        path.write(yaml_for(detection_result, overrides))
+        @output.puts(existed ? "Overwrote #{CONFIG_FILENAME}" : "Wrote #{CONFIG_FILENAME}")
+        true
+      end
+
+      private
+
+      def yaml_for(result, overrides)
+        token_paths = DEFAULT_TOKEN_PATHS.fetch(result.strategy)
+        config = {
+          "guardrails" => {
+            "audit" => {
+              "scan_paths" => overrides.fetch(:scan_paths, ["app/views", "app/components"]),
+              "ignore" => overrides.fetch(:ignore, ["app/views/layouts"])
+            },
+            "icons" => {
+              "source" => "app/assets/images/icons",
+              "sprite_output" => "app/assets/images/icons/sprite.svg"
+            },
+            "tokens" => {
+              "strategy" => result.strategy.to_s,
+              "colors_file" => token_paths["colors_file"],
+              "type_scale_file" => token_paths["type_scale_file"],
+              "near_match_policy" => overrides.fetch(:near_match_policy, "notify"),
+              "near_match_threshold" => overrides.fetch(:near_match_threshold, 4)
+            }
+          }
+        }
+
+        header(result) + config.to_yaml(line_width: -1) + threshold_footer
+      end
+
+      def threshold_footer
+        <<~YAML
+
+          # near_match_threshold scale (max per-channel R/G/B difference, 0..255):
+          #   0  = exact match only — no near-match suggestions ever fire
+          #   1  = nearly identical (probably a typo in the hex)
+          #   4  = visually similar (default)
+          #   10 = loose — same color family
+          #   20+ = very loose, expect false matches
+        YAML
+      end
+
+      def header(result)
+        unset_paths = result.strategy == :raw_hex || result.strategy == :none
+        comment = +"# Generated by `rails guardrails:init` on #{@now.strftime('%Y-%m-%d')}\n"
+        comment << "# Detected stylesheet strategy: #{result.strategy}\n"
+        if unset_paths
+          comment << "# No token system detected — colors_file and type_scale_file are unset.\n"
+          comment << "# Create a token file and update tokens.colors_file before running guardrails:tokens.\n"
+        end
+        comment << "\n"
+      end
+    end
+  end
+end

data/lib/guardrails/init/media_query_scaffolder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Guardrails
+  class Init
+    class MediaQueryScaffolder
+      DARK_MODE_PATTERN = /@media\s*\(\s*prefers-color-scheme\s*:\s*dark\s*\)/
+      HIGH_CONTRAST_PATTERN = /@media\s*\(\s*prefers-contrast\s*:\s*more\s*\)/
+
+      DARK_MODE_STUB = <<~CSS
+        @media (prefers-color-scheme: dark) {
+          /* TODO: fill this in — define dark-mode token overrides here */
+        }
+      CSS
+
+      HIGH_CONTRAST_STUB = <<~CSS
+        @media (prefers-contrast: more) {
+          /* TODO: fill this in — define high-contrast token overrides here */
+        }
+      CSS
+
+      def initialize(file, output: $stdout)
+        @file = file ? Pathname(file) : nil
+        @output = output
+      end
+
+      def scaffold
+        return [:skipped, "no colors_file configured — add prefers-color-scheme / prefers-contrast blocks to your token file manually"] if @file.nil?
+        return [:skipped, "configured colors_file does not exist (#{@file.basename}) — skipping media-query scaffold"] unless @file.exist?
+
+        content = File.read(@file, encoding: Encoding::UTF_8)
+        additions = []
+
+        unless content.match?(DARK_MODE_PATTERN)
+          content = ensure_trailing_newline(content) + "\n" + DARK_MODE_STUB
+          additions << "prefers-color-scheme: dark"
+        end
+
+        unless content.match?(HIGH_CONTRAST_PATTERN)
+          content = ensure_trailing_newline(content) + "\n" + HIGH_CONTRAST_STUB
+          additions << "prefers-contrast: more"
+        end
+
+        if additions.empty?
+          [:already_present, "media-query stubs already present in #{@file.basename}"]
+        else
+          File.write(@file, content, encoding: Encoding::UTF_8)
+          [:appended, "appended stubs (#{additions.join(', ')}) to #{@file.basename}"]
+        end
+      end
+
+      private
+
+      def ensure_trailing_newline(content)
+        content.end_with?("\n") ? content : content + "\n"
+      end
+    end
+  end
+end

data/lib/guardrails/init/prompter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Guardrails
+  class Init
+    # Minimal stdin/stdout prompter for guardrails:init. When the input
+    # stream isn't a TTY (CI, piped invocations) every method short-circuits
+    # to the configured default — no blocking reads, no surprises.
+    class Prompter
+      def initialize(input: $stdin, output: $stdout)
+        @input = input
+        @output = output
+      end
+
+      # Free-text prompt. Empty input accepts the default.
+      def ask(question, default:)
+        return default unless interactive?
+
+        @output.print "#{question} [#{default}]: "
+        @output.flush if @output.respond_to?(:flush)
+        line = @input.gets
+        return default if line.nil?
+
+        answer = line.chomp.strip
+        answer.empty? ? default : answer
+      end
+
+      # Choose one of `choices` (Strings). Accepts the choice name itself or
+      # its 1-based index. Re-prompts on bad input. Empty input accepts
+      # `default`.
+      def choose(question, choices:, default:)
+        return default unless interactive?
+
+        loop do
+          @output.puts question
+          choices.each_with_index do |c, i|
+            marker = c == default ? "*" : " "
+            @output.puts "  #{i + 1}) #{c}#{marker == '*' ? ' (default)' : ''}"
+          end
+          @output.print "> "
+          @output.flush if @output.respond_to?(:flush)
+          line = @input.gets
+          return default if line.nil?
+
+          raw = line.chomp.strip
+          return default if raw.empty?
+          return choices[raw.to_i - 1] if raw.match?(/\A\d+\z/) && (1..choices.length).cover?(raw.to_i)
+          return raw if choices.include?(raw)
+
+          @output.puts "  -> '#{raw}' isn't one of #{choices.join(', ')}; try again."
+        end
+      end
+
+      private
+
+      def interactive?
+        @input.respond_to?(:tty?) && @input.tty?
+      end
+    end
+  end
+end

data/lib/guardrails/init/stack_detector.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Guardrails
+  class Init
+    class StackDetector
+      Result = Struct.new(:strategy, :stylesheets, :evidence, keyword_init: true)
+
+      STYLESHEET_PATTERNS = [
+        "app/assets/stylesheets/**/*.{css,scss}",
+        "app/assets/tailwind/**/*.css"
+      ].freeze
+
+      # Skip third-party / generated subtrees even when they're nested
+      # inside an `app/assets/stylesheets/` tree (common Sprockets
+      # convention). Match on path components, not prefix.
+      IMPLICIT_IGNORE_SEGMENTS = %w[vendor node_modules tmp public log].freeze
+
+      CUSTOM_PROPERTY_PATTERN = /--[a-z][\w-]*:\s*[^;]+;/
+      SCSS_VARIABLE_PATTERN = /^\s*\$[a-z][\w-]*:/
+      HEX_LITERAL_PATTERN = /#[0-9a-fA-F]{3,8}\b/
+
+      def initialize(root)
+        @root = Pathname(root)
+      end
+
+      def detect
+        files = collect_stylesheets
+        return Result.new(strategy: :none, stylesheets: [], evidence: empty_evidence) if files.empty?
+
+        evidence = analyze(files)
+        Result.new(
+          strategy: choose_strategy(evidence),
+          stylesheets: files,
+          evidence: evidence
+        )
+      end
+
+      private
+
+      def collect_stylesheets
+        STYLESHEET_PATTERNS
+          .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+          .map { |path| Pathname(path) }
+          .uniq
+          .reject { |path| ignored_segment?(path) }
+      end
+
+      def ignored_segment?(path)
+        segments = path.relative_path_from(@root).to_s.split("/")
+        (IMPLICIT_IGNORE_SEGMENTS & segments).any?
+      end
+
+      def empty_evidence
+        {
+          files_scanned: 0,
+          custom_property_files: 0,
+          scss_variable_files: 0,
+          raw_hex_files: 0
+        }
+      end
+
+      def analyze(files)
+        evidence = empty_evidence
+        evidence[:files_scanned] = files.length
+
+        files.each do |file|
+          # Force UTF-8 — real-world stylesheets routinely contain
+          # multi-byte chars (em-dashes in comments, smart quotes in
+          # string values, etc.) and Pathname#read uses the default
+          # external encoding which can be US-ASCII on some systems.
+          content = File.read(file, encoding: Encoding::UTF_8)
+          has_custom_props = content.match?(CUSTOM_PROPERTY_PATTERN)
+          has_scss_vars = content.match?(SCSS_VARIABLE_PATTERN)
+          has_hex = content.match?(HEX_LITERAL_PATTERN)
+
+          evidence[:custom_property_files] += 1 if has_custom_props
+          evidence[:scss_variable_files] += 1 if has_scss_vars
+          evidence[:raw_hex_files] += 1 if has_hex && !has_custom_props && !has_scss_vars
+        end
+
+        evidence
+      end
+
+      # Pick the dominant strategy by file count, but with a strong
+      # preference for actual token systems over raw_hex. If any token
+      # files exist (CSS custom properties or SCSS variables), choose
+      # whichever has more — even if raw_hex has more files than either.
+      # raw_hex only wins when no token system is present at all.
+      def choose_strategy(evidence)
+        css_count = evidence[:custom_property_files]
+        scss_count = evidence[:scss_variable_files]
+        hex_count = evidence[:raw_hex_files]
+
+        return :none if css_count.zero? && scss_count.zero? && hex_count.zero?
+
+        # If any token system exists, pick the dominant one — never fall
+        # back to raw_hex when SCSS / CSS-vars are in play.
+        if css_count.positive? || scss_count.positive?
+          return css_count >= scss_count ? :css_custom_properties : :scss_variables
+        end
+
+        :raw_hex
+      end
+    end
+  end
+end

data/lib/guardrails/init.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require_relative "init/stack_detector"
+require_relative "init/config_writer"
+require_relative "init/media_query_scaffolder"
+require_relative "init/prompter"
+
+module Guardrails
+  class Init
+    NEAR_MATCH_POLICY_CHOICES = %w[notify fix leave].freeze
+    DEFAULT_SCAN_PATHS = %w[app/views app/components].freeze
+    DEFAULT_IGNORE = %w[app/views/layouts].freeze
+
+    STRATEGY_LABELS = {
+      css_custom_properties: "CSS custom properties",
+      scss_variables: "SCSS variables",
+      raw_hex: "Raw hex literals (no token system detected)",
+      none: "No stylesheets found"
+    }.freeze
+
+    def initialize(root:, output: $stdout, input: $stdin, force: false)
+      @root = Pathname(root)
+      @output = output
+      @input = input
+      @force = force
+    end
+
+    def run
+      result = StackDetector.new(@root).detect
+      print_summary(result)
+
+      # Don't prompt the user if we know we won't write — keeps reruns from
+      # asking questions whose answers will be discarded.
+      overrides = config_writeable? ? collect_overrides : {}
+
+      written = ConfigWriter.new(@root, output: @output).write(result, overrides: overrides, force: @force)
+      if written
+        scaffold_media_queries
+      else
+        @output.puts "Media queries: skipped (delete guardrails.yml or set FORCE=1 to re-run init)"
+      end
+      result
+    end
+
+    private
+
+    def config_writeable?
+      @force || !@root.join("guardrails.yml").exist?
+    end
+
+    def collect_overrides
+      prompter = Prompter.new(input: @input, output: @output)
+      {
+        near_match_policy: prompter.choose(
+          "Near-match auto-fix policy:",
+          choices: NEAR_MATCH_POLICY_CHOICES,
+          default: "notify"
+        ),
+        near_match_threshold: parse_int(
+          prompter.ask(
+            "Near-match threshold (per-channel R/G/B, 0=exact only, 4=default, 10+=loose):",
+            default: "4"
+          ),
+          default: 4
+        ),
+        scan_paths: csv(prompter.ask(
+          "Audit scan paths (comma-separated):",
+          default: DEFAULT_SCAN_PATHS.join(",")
+        )),
+        ignore: csv(prompter.ask(
+          "Audit ignore paths (comma-separated; matched as path prefixes, not globs):",
+          default: DEFAULT_IGNORE.join(",")
+        ))
+      }
+    end
+
+    def parse_int(value, default:)
+      Integer(value)
+    rescue ArgumentError, TypeError
+      default
+    end
+
+    def csv(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def scaffold_media_queries
+      file = configured_colors_file
+      status, message = MediaQueryScaffolder.new(file, output: @output).scaffold
+      @output.puts "Media queries: #{message}"
+      status
+    end
+
+    def configured_colors_file
+      config_path = @root.join("guardrails.yml")
+      return nil unless config_path.exist?
+
+      config = YAML.safe_load_file(config_path) || {}
+      relative = config.dig("guardrails", "tokens", "colors_file")
+      relative ? @root.join(relative) : nil
+    end
+
+    def print_summary(result)
+      @output.puts "Guardrails — stack detection"
+      @output.puts "Root: #{@root}"
+      @output.puts "Strategy: #{STRATEGY_LABELS.fetch(result.strategy)} (#{result.strategy})"
+      @output.puts "Stylesheets scanned: #{result.evidence[:files_scanned]}"
+      @output.puts "  custom-property files: #{result.evidence[:custom_property_files]}"
+      @output.puts "  SCSS-variable files:   #{result.evidence[:scss_variable_files]}"
+      @output.puts "  raw-hex files:         #{result.evidence[:raw_hex_files]}"
+    end
+  end
+end