glyphs 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 977c4ff81bc073f486991e32e6f27418419d440ddf15fc0cd8cb4357091abe8a
-  data.tar.gz: e2f6a73fa1545cae2d0714c9b2528b8b8d65b6474af45e1c73ae0999b5851cde
+  metadata.gz: dffbe50e2d6b992be18142abb575887e4b11ee8b26ad2afec2a3d94f0ed418cd
+  data.tar.gz: 59e4a5c55154ae1075f0c4cf0c7a3b2a1f767fc12416dd48b85d39b0bbed119a
 SHA512:
-  metadata.gz: 3f9570e3186cf64e294a7ca0f4de342d5ef16ba7bd6ac86017737617566bef92caff25ea9f665a2d3044abe76990ec9ed81d020e0cd943bfc3983c4228f86360
-  data.tar.gz: 49bd88b05cc3dfe3370348ade5a9498a26b6b7db12fb25fff63fb1ef0c8be94091cc71ef30728273a10a90be740d3fc0e867e751d5a505add4c1a1e0a0f741ce
+  metadata.gz: ef3a208721a23a5ab7272de80644228046b5f5bc42834d4f2f5f59f7da78bf141775cf6f8a192243abdcfdebdc444eab3bb87df33409fa429cc4571c76c4e0e5
+  data.tar.gz: cdc2a32800aa6c3a503dbccd0c8ee524e120fe1d418ba417bcf905f00e283fcc56c24be29dfec7f2dc4e0a6c57b268d2cb2577d9f5cc9b9b201483a6c0c93f2b

data/README.md

@@ -103,6 +103,55 @@ Glyphs.configure do |config|
 end
 ```
 
+## Shrinking icons in Docker
+
+`rails g rails_icons:sync` copies a library's **entire** icon set into
+`app/assets/svg/icons/<library>/<variant>/` — often thousands of SVGs, of which
+an app uses a handful. `glyphs:prune_icons` deletes the unreferenced ones so a
+Docker image ships only what it renders, while the committed repo keeps the full
+set for development.
+
+It scans your source (`app/**/*.rb`, `lib/**/*.rb` with a real parser, plus
+`.erb/.haml/.slim` text) for `LucideIcon(:house)`, legacy helpers, generic
+`Icon(:x, library: :lucide)`, and `iconify lucide--house` class strings, then
+keeps that set **plus** two safety nets: the `keep_icons` allowlist (for
+dynamic/data-driven names a static scan can't see) and every configured
+`fallback_icons` (a pruned fallback would 500 on the next missing icon).
+
+```ruby
+# config/initializers/glyphs.rb
+Glyphs.configure do |config|
+  # Icons referenced dynamically (names from config, a DB, or a gem's chrome).
+  # Flat list or per-library hash; names or fnmatch globs.
+  config.keep_icons = %w[menu palette search circle-*]
+  # config.keep_icons = { lucide: %w[menu palette], phosphor: %w[lock] }
+end
+```
+
+```bash
+# Preview (dry run — deletes nothing):
+bin/rails glyphs:prune_icons
+
+# Delete (both env vars required — a deliberate opt-in so it never fires
+# accidentally on a developer's working tree):
+PRUNE=1 GLYPHS_PRUNE_ICONS=1 bin/rails glyphs:prune_icons
+```
+
+Run it in the image build, **after** `assets:precompile` and before the final
+stage copies the app — so the deletions land in the image but never in a
+developer's checkout:
+
+```dockerfile
+RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile
+RUN SECRET_KEY_BASE_DUMMY=1 PRUNE=1 GLYPHS_PRUNE_ICONS=1 ./bin/rails glyphs:prune_icons
+```
+
+After deleting, the task **verifies** every kept icon still resolves and exits
+non-zero if not — a bad prune (e.g. a missing allowlist entry) fails the build
+instead of shipping broken icons. The bundled `animated` library and any
+`custom_path` library are left untouched, and it refuses to empty a library
+whose keep-set is empty.
+
 ## RuboCop cops
 
 Add the plugin (RuboCop >= 1.72):

data/lib/glyphs/configuration.rb

@@ -14,13 +14,22 @@ module Glyphs
     #   invoked before the fallback renders when not raising.
     # fallback_icons: { library => icon_name } rendered instead of a missing icon.
     # cache_svgs: memoize rendered SVG strings per [library, variant, name, attributes].
-    attr_accessor :raise_on_missing, :on_missing_icon, :fallback_icons, :cache_svgs
+    # keep_icons: icons the pruner must keep despite no static reference
+    #   (dynamic / data-driven names). A flat list of names/globs, or a
+    #   { library => [names/globs] } hash. fallback_icons are always kept.
+    # prune_source_globs: extra locations the pruner's scanner text-scans IN
+    #   ADDITION to the built-in Ruby/template defaults — e.g. a config file that
+    #   names icons. Never replaces the defaults (nil = defaults only).
+    attr_accessor :raise_on_missing, :on_missing_icon, :fallback_icons, :cache_svgs,
+      :keep_icons, :prune_source_globs
 
     def initialize
       @raise_on_missing = defined?(Rails) ? Rails.env.local? : true
       @on_missing_icon = nil
       @fallback_icons = DEFAULT_FALLBACK_ICONS.dup
       @cache_svgs = true
+      @keep_icons = []
+      @prune_source_globs = nil
     end
   end
 end

data/lib/glyphs/icon_pruner.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Glyphs
+  # Deletes synced SVG icons that no source references, keeping the union of:
+  # scanned references, the configured keep_icons allowlist (names or globs,
+  # flat or per-library), and the configured fallback_icons (always — a pruned
+  # fallback would make every future missing-icon 500).
+  #
+  # Operates only on `icons_root` (`app/assets/svg/icons`), skips the bundled
+  # `animated` library, never deletes non-.svg files, and refuses to empty a
+  # library whose computed keep-set is empty (guards against a mis-scan wiping a
+  # whole library). Returns a PruneReport.
+  class IconPruner
+    ANIMATED = :animated
+
+    def initialize(icons_root:, references:, keep_icons: [], fallback_icons: {}, dry_run: false)
+      @icons_root = icons_root
+      @references = references
+      @keep_icons = keep_icons
+      @fallback_icons = fallback_icons
+      @dry_run = dry_run
+    end
+
+    def call
+      stats = []
+      deleted_names = []
+
+      grouped_files.each do |(library, variant), files|
+        # Guard on library-specific evidence of use, NOT on the merged keep-set:
+        # a flat keep_icons list is non-empty for every library, so keying the
+        # guard off keep.empty? would let it wipe an entirely-unreferenced
+        # library down to whatever the flat list happens to match.
+        unless library_used?(library)
+          warn "[Glyphs::IconPruner] refusing to prune #{library}/#{variant || '.'} — " \
+               "no references, fallback, or per-library keep_icons for #{library}"
+          next
+        end
+
+        keep = keep_names_for(library, variant)
+        stat = prune_group(library, variant, files, keep, deleted_names)
+        stats << stat
+      end
+
+      PruneReport.new(stats:, deleted_names:, dry_run: @dry_run)
+    end
+
+    private
+
+    # { [library, variant] => [absolute svg paths] }, excluding the animated lib.
+    def grouped_files
+      svg_files.group_by { |path| library_and_variant(path) }.reject { |(library, _), _| library == ANIMATED }
+    end
+
+    def svg_files
+      Dir.glob([File.join(@icons_root, "*", "*", "*.svg"), File.join(@icons_root, "*", "*.svg")]).uniq
+    end
+
+    # Derives [library_sym, variant_or_nil] from an svg path under icons_root.
+    # Two dirs deep => library/variant/name.svg; one dir deep => library/name.svg.
+    def library_and_variant(path)
+      relative = path.delete_prefix("#{@icons_root}/")
+      parts = relative.split("/")
+      if parts.size >= 3
+        [parts[0].to_sym, parts[1]]
+      else
+        [parts[0].to_sym, nil]
+      end
+    end
+
+    def prune_group(library, variant, files, keep, deleted_names)
+      kept = 0
+      deleted = 0
+      bytes_freed = 0
+
+      files.each do |path|
+        name = File.basename(path, ".svg")
+        if keep_file?(name, keep)
+          kept += 1
+          next
+        end
+
+        deleted += 1
+        bytes_freed += File.size(path)
+        deleted_names << name
+        File.delete(path) unless @dry_run
+      end
+
+      PruneReport::LibraryStat.new(library:, variant:, kept:, deleted:, bytes_freed:)
+    end
+
+    def keep_file?(name, keep)
+      keep.any? { |pattern| pattern == name || File.fnmatch?(pattern, name) }
+    end
+
+    # The set of names/globs to keep for a (library, variant): references for
+    # this exact library+variant, the library's keep_icons entries, and the
+    # library's fallback icon.
+    def keep_names_for(library, variant)
+      names = Set.new
+      @references.each do |reference|
+        names << reference.name if reference.library == library && reference.variant == variant
+      end
+      names.merge(keep_icons_for(library))
+      fallback = @fallback_icons[library]
+      names << fallback if fallback
+      names
+    end
+
+    def keep_icons_for(library)
+      case @keep_icons
+      when Hash then Array(@keep_icons[library] || @keep_icons[library.to_s])
+      else Array(@keep_icons)
+      end
+    end
+
+    # Whether a library has library-specific evidence it's in use: any scanned
+    # reference, a configured fallback, or a per-library keep_icons entry. A flat
+    # keep_icons list is deliberately NOT evidence — it applies to every library,
+    # so counting it would defeat the wipe guard for unreferenced libraries.
+    def library_used?(library)
+      return true if @references.any? { |reference| reference.library == library }
+      return true if @fallback_icons[library]
+
+      # A per-library keep_icons entry counts only if it actually lists icons —
+      # an empty array (`{ tabler: [] }`) is not evidence of use.
+      @keep_icons.is_a?(Hash) && keep_icons_for(library).any?
+    end
+  end
+end

data/lib/glyphs/icon_reference.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # A single (library, variant, name) icon reference discovered in source, with
+  # the shared library/variant resolution tables the scanner and the RuboCop
+  # cops both rely on.
+  #
+  # `library` is an icons-gem library symbol (`:lucide`), `variant` is a string
+  # or nil (variant-less libraries), and `name` is dasherized (`"circle-check"`).
+  #
+  # The library/variant tables are sourced from the `icons` gem wherever
+  # possible (`default_variant_for`) so they never drift from what actually
+  # resolves at render time.
+  class IconReference < Data.define(:library, :variant, :name) # rubocop:disable Style/DataInheritance
+    # Subclassed (not the block form) so the constants below are namespaced under
+    # IconReference — constants defined inside a `Data.define do…end` block leak
+    # to the enclosing scope instead of nesting under the class.
+    #
+    # Maps every Glyphs library component to its icons-gem library symbol. This
+    # is the canonical map; `RuboCop::Cop::Glyphs::LibraryCallHelpers` reads it
+    # so the cops and the pruner agree on the full set of libraries.
+    LIBRARY_TO_COMPONENT = {
+      lucide: "LucideIcon",
+      phosphor: "PhosphorIcon",
+      heroicons: "HeroIcon",
+      tabler: "TablerIcon",
+      feather: "FeatherIcon",
+      boxicons: "BoxIcon",
+      flags: "FlagIcon",
+      hugeicons: "HugeIcon",
+      linear: "LinearIcon",
+      radix: "RadixIcon",
+      sidekickicons: "SidekickIcon",
+      weather: "WeatherIcon",
+      animated: "AnimatedIcon"
+    }.freeze
+
+    # Legacy icon helpers (`_lucide(:house)`) the scanner also recognizes.
+    LEGACY_HELPERS = {
+      "_lucide" => :lucide,
+      "_phosphor" => :phosphor,
+      "_hero" => :heroicons,
+      "_heroicon" => :heroicons,
+      "_tabler" => :tabler
+    }.freeze
+
+    # Raw `iconify lucide--house` class strings.
+    ICONIFY_PATTERN = /\biconify\s+(lucide|phosphor|heroicons)--([a-z0-9-]+)/
+
+    class << self
+      # Component name (`"LucideIcon"`) => library symbol (`:lucide`).
+      def component_to_library
+        @component_to_library ||= LIBRARY_TO_COMPONENT.to_h { |library, component| [component, library] }.freeze
+      end
+
+      def legacy_helpers
+        LEGACY_HELPERS
+      end
+
+      # Resolves a called method name (component or legacy helper) to a library
+      # symbol, or nil when the method isn't an icon call.
+      def library_for(method_name)
+        name = method_name.to_s
+        component_to_library[name] || LEGACY_HELPERS[name]
+      end
+
+      # The library's default variant, as configured in the icons gem. Returns a
+      # string (`"outline"`), or nil for variant-less libraries.
+      def default_variant_for(library)
+        options = Icons.config.libraries[library.to_sym]
+        normalize_variant(options&.default_variant)
+      rescue StandardError
+        nil
+      end
+
+      # Mirrors the icons gem's variant→path handling so a scanned reference
+      # points at the same file that renders: an empty string (a documented
+      # rails_icons override) and `"."` (the variant-less convention) both mean
+      # "no variant subdirectory" and normalize to nil. See the icons gem's
+      # Icons::Icon::Configurable#set_variant and Icons::Icon::FilePath#parts.
+      def normalize_variant(variant)
+        return if variant.nil?
+
+        string = variant.to_s
+        return if string.empty? || string == "."
+
+        string
+      end
+    end
+  end
+end

data/lib/glyphs/prune_report.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # The result of an IconPruner run: per-(library, variant) counts, a sample of
+  # deleted names, and a human-readable summary. Value object, no side effects.
+  class PruneReport
+    LibraryStat = Data.define(:library, :variant, :kept, :deleted, :bytes_freed)
+
+    SAMPLE_LIMIT = 20
+
+    attr_reader :stats, :deleted_names, :dry_run
+
+    def initialize(stats:, deleted_names:, dry_run:)
+      @stats = stats
+      @deleted_names = deleted_names
+      @dry_run = dry_run
+    end
+
+    def deleted_count = stats.sum(&:deleted)
+    def kept_count = stats.sum(&:kept)
+    def bytes_freed = stats.sum(&:bytes_freed)
+
+    def to_s
+      lines = [headline, *stat_lines]
+      lines << sample_line if deleted_names.any?
+      lines << "  Re-run with PRUNE=1 GLYPHS_PRUNE_ICONS=1 to delete." if dry_run
+      lines.join("\n")
+    end
+
+    private
+
+    def headline
+      prefix = dry_run ? "[dry-run] " : ""
+      verb = dry_run ? "Would prune" : "Pruned"
+      "#{prefix}#{verb} #{deleted_count} icons, kept #{kept_count}, freed #{human_bytes(bytes_freed)}"
+    end
+
+    def stat_lines
+      stats.sort_by { |stat| [stat.library.to_s, stat.variant.to_s] }.map do |stat|
+        "  #{stat.library}/#{stat.variant || '.'}: #{stat.deleted} deleted, #{stat.kept} kept"
+      end
+    end
+
+    def sample_line
+      shown = deleted_names.first(SAMPLE_LIMIT).join(", ")
+      extra = deleted_names.size - SAMPLE_LIMIT
+      extra.positive? ? "  e.g. #{shown} … and #{extra} more" : "  e.g. #{shown}"
+    end
+
+    def human_bytes(bytes)
+      units = %w[B KB MB GB]
+      size = bytes.to_f
+      unit = units.shift
+      while size >= 1024 && units.any?
+        size /= 1024
+        unit = units.shift
+      end
+      unit == "B" ? "#{bytes} B" : format("%.2f %s", size, unit)
+    end
+  end
+end

data/lib/glyphs/prune_runner.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Wires configuration → SourceScanner → IconPruner and (when deleting) verifies
+  # every kept icon still resolves on disk. Thin orchestrator so the rake task is
+  # a one-liner and the whole flow is unit-testable.
+  #
+  #   Glyphs::PruneRunner.call(dry_run: false)   # scans Rails.root, prunes, verifies
+  class PruneRunner
+    # Raised when a kept icon (static ref, keep_icons, or fallback) is missing
+    # after a prune — turns a bad prune into a failed build, never a 500.
+    class VerificationError < StandardError; end
+
+    def self.call(**)
+      new(**).call
+    end
+
+    def initialize(root: default_root, icons_root: default_icons_root, dry_run: true, config: Glyphs.configuration)
+      @root = root
+      @icons_root = icons_root
+      @dry_run = dry_run
+      @config = config
+    end
+
+    def call
+      report = pruner.call
+      verify! unless @dry_run
+      report
+    end
+
+    # Asserts every kept icon resolves to a file on disk. Raises
+    # VerificationError listing the first few misses.
+    def verify!
+      missing = expected_files.reject { |path| File.exist?(path) }
+      return if missing.empty?
+
+      names = missing.first(10).map { |path| relative(path) }
+      raise VerificationError,
+        "#{missing.size} kept icon(s) missing after prune: #{names.join(', ')}"
+    end
+
+    private
+
+    attr_reader :config
+
+    def pruner
+      @pruner ||= IconPruner.new(
+        icons_root: @icons_root,
+        references:,
+        keep_icons: config.keep_icons,
+        fallback_icons: config.fallback_icons,
+        dry_run: @dry_run
+      )
+    end
+
+    def references
+      @references ||= SourceScanner.new(root: @root, **scanner_options).call
+    end
+
+    def scanner_options
+      globs = config.prune_source_globs
+      globs ? { extra_globs: Array(globs) } : {}
+    end
+
+    # Files that MUST exist after a prune: every scanned reference and every
+    # configured fallback icon, restricted to libraries actually synced under
+    # icons_root (the pruner only touches those — a fallback for an un-synced
+    # library is irrelevant and must not fail the build). keep_icons globs are
+    # advisory (they may match nothing), so they're not asserted here.
+    def expected_files
+      fallback_refs = config.fallback_icons.map do |library, name|
+        IconReference.new(library:, variant: IconReference.default_variant_for(library), name:)
+      end
+
+      (references.to_a + fallback_refs)
+        .select { |reference| library_present?(reference.library) }
+        .map { |reference| file_for(reference) }
+        .uniq
+    end
+
+    def library_present?(library)
+      Dir.exist?(File.join(@icons_root, library.to_s))
+    end
+
+    def file_for(reference)
+      parts = [reference.library.to_s, reference.variant, "#{reference.name}.svg"].compact
+      File.join(@icons_root, *parts)
+    end
+
+    def relative(path)
+      path.delete_prefix("#{@icons_root}/")
+    end
+
+    def default_root
+      defined?(Rails) ? Rails.root.to_s : Dir.pwd
+    end
+
+    def default_icons_root
+      base = Icons.config.base_path
+      File.join(base.to_s, Icons.config.icons_path.to_s)
+    end
+  end
+end

data/lib/glyphs/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Loaded only when Rails is present (see the guard in lib/glyphs.rb). Its sole
+  # job is to expose the icon-pruning rake task to consuming apps. Kept a
+  # Railtie, not an Engine: glyphs contributes no routes, views, or migrations.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/glyphs.rake", __dir__)
+    end
+  end
+end

data/lib/glyphs/source_scanner.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Glyphs
+  # Scans an application's source for statically-known icon references and
+  # returns a Set of IconReference. Ruby/Phlex files are parsed with Prism (a
+  # real AST); templates (.erb/.haml/.slim) are text-scanned for icon calls and
+  # `iconify` class strings.
+  #
+  # Dynamic names/variants/libraries are silently skipped — they can't be known
+  # statically and are covered by the pruner's keep-list. A file that fails to
+  # parse warns and is skipped rather than aborting the scan.
+  class SourceScanner
+    DEFAULT_RUBY_GLOBS = ["app/**/*.rb", "lib/**/*.rb"].freeze
+    DEFAULT_TEMPLATE_GLOBS = ["app/**/*.erb", "app/**/*.haml", "app/**/*.slim"].freeze
+
+    # Template (.erb/.haml/.slim) text scanning. Prism can't parse these, so we
+    # match icon calls textually: the method, the literal first-argument name,
+    # and the argument tail (to pull out `variant:` and, for the generic
+    # `icon`/`Icon` helper, `library:`/`from:`). `Icon`/`icon` are included here
+    # (they're handled by the AST visitor for .rb files) so the generic
+    # rails_icons view helper is caught in templates too.
+    TEMPLATE_CALL_NAMES = (
+      IconReference::LIBRARY_TO_COMPONENT.values +
+        IconReference::LEGACY_HELPERS.keys +
+        %w[Icon icon]
+    ).freeze
+    # The tail runs to the end of the line or the ERB/Slim tag close (`%>`,
+    # `-%>`) — NOT to the first `)`, which would truncate `variant:`/`from:` sitting
+    # after a nested call like `class: cn("a")`. Over-capturing the tail only ever
+    # ADDS a keep (never drops a reference), so it errs safe.
+    TEMPLATE_CALL_PATTERN = /
+      \b(#{Regexp.union(TEMPLATE_CALL_NAMES)})
+      \(?\s*[:"']([a-z0-9_-]+)['"]?      # first arg is a literal symbol or string
+      ([^\n]*?)                          # argument tail (rest of the logical line)
+      (?=-?%>|\n|\z)
+    /x
+    TEMPLATE_VARIANT_PATTERN = /\bvariant:\s*[:"']?([a-z0-9_.-]*)/
+    TEMPLATE_LIBRARY_PATTERN = /\b(?:library|from):\s*[:"']([a-z0-9_-]+)/
+    GENERIC_TEMPLATE_CALLS = %w[Icon icon].freeze
+
+    # `extra_globs` are additional locations to text-scan on top of the built-in
+    # Ruby and template defaults (never replacing them) — e.g. a config file that
+    # names icons. They're scanned like templates (regex, not AST).
+    def initialize(root:, ruby_globs: DEFAULT_RUBY_GLOBS, template_globs: DEFAULT_TEMPLATE_GLOBS, extra_globs: [])
+      @root = root
+      @ruby_globs = ruby_globs
+      @template_globs = template_globs
+      @extra_globs = Array(extra_globs)
+    end
+
+    def call
+      references = Set.new
+      ruby_files.each { |path| scan_ruby(path, references) }
+      (template_files - ruby_files).each { |path| scan_template(path, references) }
+      references
+    end
+
+    private
+
+    attr_reader :root
+
+    def ruby_files
+      glob(@ruby_globs)
+    end
+
+    def template_files
+      glob(@template_globs + @extra_globs)
+    end
+
+    def glob(patterns)
+      patterns.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }.uniq
+    end
+
+    def scan_ruby(path, references)
+      result = Prism.parse_file(path)
+      CallVisitor.new(references).visit(result.value)
+    rescue StandardError => e
+      warn "[Glyphs::SourceScanner] skipped #{path}: #{e.class}: #{e.message}"
+    end
+
+    def scan_template(path, references)
+      text = File.read(path)
+      scan_iconify(text, references)
+      text.scan(TEMPLATE_CALL_PATTERN) do |method_name, name, tail|
+        add_template_call(references, method_name, name, tail)
+      end
+    rescue StandardError => e
+      warn "[Glyphs::SourceScanner] skipped #{path}: #{e.class}: #{e.message}"
+    end
+
+    # Records a template icon call, reading `variant:` (and, for the generic
+    # icon/Icon helper, `library:`/`from:`) out of the captured argument tail so
+    # a variant-bearing template call resolves to the same file it renders.
+    def add_template_call(references, method_name, name, tail)
+      library = template_library(method_name, tail)
+      return unless library
+
+      references << IconReference.new(
+        library:,
+        variant: template_variant(tail, library),
+        name: name.to_s.tr("_", "-")
+      )
+    end
+
+    # A present-but-empty `variant:` (`variant: ""` / `variant: :"."`) means
+    # no-variant — mirror the AST path: default ONLY when the keyword is absent.
+    def template_variant(tail, library)
+      match = tail.match(TEMPLATE_VARIANT_PATTERN)
+      return IconReference.default_variant_for(library) unless match
+
+      IconReference.normalize_variant(match[1])
+    end
+
+    def template_library(method_name, tail)
+      return IconReference.library_for(method_name) unless GENERIC_TEMPLATE_CALLS.include?(method_name)
+
+      match = tail.match(TEMPLATE_LIBRARY_PATTERN)
+      match && match[1].to_sym
+    end
+
+    def scan_iconify(text, references)
+      text.scan(IconReference::ICONIFY_PATTERN) do |library, name|
+        library = library.to_sym
+        references << IconReference.new(library:, variant: IconReference.default_variant_for(library), name:)
+      end
+    end
+
+    # Walks the Prism AST collecting icon references from call nodes.
+    class CallVisitor < Prism::Visitor
+      GENERIC_CALLS = %i[Icon icon].freeze
+
+      def initialize(references)
+        @references = references
+        super()
+      end
+
+      def visit_call_node(node)
+        record(node) if node.receiver.nil?
+        super
+      end
+
+      def visit_string_node(node)
+        node.unescaped.scan(IconReference::ICONIFY_PATTERN) do |library, name|
+          library = library.to_sym
+          references << IconReference.new(library:, variant: IconReference.default_variant_for(library), name:)
+        end
+        super
+      end
+
+      private
+
+      attr_reader :references
+
+      def record(node)
+        method = node.name.to_s
+        if GENERIC_CALLS.include?(node.name)
+          record_generic(node)
+        elsif IconReference.library_for(method)
+          record_component(node, IconReference.library_for(method))
+        end
+      end
+
+      def record_component(node, library)
+        name = literal_string(first_argument(node))
+        return unless name
+
+        variant = variant_for(node, library)
+        return if variant == :dynamic
+
+        references << IconReference.new(library:, variant:, name:)
+      end
+
+      def record_generic(node)
+        library = literal_symbol_or_string(keyword_argument(node, %i[library from]))
+        return unless library
+
+        name = literal_string(first_argument(node))
+        return unless name
+
+        variant = variant_for(node, library.to_sym)
+        return if variant == :dynamic
+
+        references << IconReference.new(library: library.to_sym, variant:, name:)
+      end
+
+      def variant_for(node, library)
+        value_node = keyword_argument(node, [:variant])
+        return IconReference.default_variant_for(library) unless value_node
+
+        value = literal_symbol_or_string(value_node)
+        return :dynamic unless value
+
+        IconReference.normalize_variant(value)
+      end
+
+      def first_argument(node)
+        node.arguments&.arguments&.first
+      end
+
+      # Returns the value node for the first matching keyword, or nil.
+      def keyword_argument(node, keys)
+        pair = keyword_pairs(node).find do |element|
+          element.key.is_a?(Prism::SymbolNode) && keys.include?(element.key.unescaped.to_sym)
+        end
+        pair&.value
+      end
+
+      def keyword_pairs(node)
+        args = node.arguments&.arguments || []
+        hash = args.find { |arg| arg.is_a?(Prism::KeywordHashNode) || arg.is_a?(Prism::HashNode) }
+        hash ? hash.elements.grep(Prism::AssocNode) : []
+      end
+
+      def literal_string(value_node)
+        literal_symbol_or_string(value_node)&.tr("_", "-")
+      end
+
+      # Returns the literal String for a symbol/string node, or nil when the
+      # node is dynamic (a variable, method call, interpolation, ...).
+      def literal_symbol_or_string(value_node)
+        value_node.unescaped if value_node.is_a?(Prism::SymbolNode) || value_node.is_a?(Prism::StringNode)
+      end
+    end
+  end
+end

data/lib/glyphs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Glyphs
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/glyphs.rb

@@ -11,8 +11,15 @@ loader.ignore("#{__dir__}/glyphs/version.rb")
 # RuboCop process (see the bottom of this file).
 loader.ignore("#{__dir__}/glyphs/rubocop.rb")
 loader.ignore("#{__dir__}/rubocop")
+# The Railtie is required conditionally below (only under Rails), and the rake
+# tasks aren't Ruby constants — keep both out of Zeitwerk's managed set.
+loader.ignore("#{__dir__}/glyphs/railtie.rb")
+loader.ignore("#{__dir__}/tasks")
 loader.setup
 
+# Expose the icon-pruning rake task to consuming Rails apps.
+require_relative "glyphs/railtie" if defined?(Rails::Railtie)
+
 # Ensure the icons gem is configured even outside Rails. Inside Rails the
 # rails_icons engine calls `Icons.configure` with the app's settings; the
 # configuration is memoized, so this never clobbers app configuration.

data/lib/rubocop/cop/glyphs/library_call_helpers.rb

@@ -9,21 +9,10 @@ module RuboCop
       module LibraryCallHelpers
         LIBRARY_KEYS = %i[library from].freeze
 
-        LIBRARY_TO_COMPONENT = {
-          "lucide" => "LucideIcon",
-          "phosphor" => "PhosphorIcon",
-          "heroicons" => "HeroIcon",
-          "tabler" => "TablerIcon",
-          "feather" => "FeatherIcon",
-          "boxicons" => "BoxIcon",
-          "flags" => "FlagIcon",
-          "hugeicons" => "HugeIcon",
-          "linear" => "LinearIcon",
-          "radix" => "RadixIcon",
-          "sidekickicons" => "SidekickIcon",
-          "weather" => "WeatherIcon",
-          "animated" => "AnimatedIcon"
-        }.freeze
+        # Library name string => component name, keyed by the icons-gem library
+        # name (`"lucide"`). Derived from the canonical map in
+        # `Glyphs::IconReference` so the cops and the icon pruner never drift.
+        LIBRARY_TO_COMPONENT = ::Glyphs::IconReference::LIBRARY_TO_COMPONENT.transform_keys(&:to_s).freeze
 
         private
 

data/lib/tasks/glyphs.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+namespace :glyphs do
+  desc "Prune synced icons not referenced in source. Dry-run unless PRUNE=1 GLYPHS_PRUNE_ICONS=1."
+  task prune_icons: :environment do
+    commit = ENV["PRUNE"] == "1" && ENV["GLYPHS_PRUNE_ICONS"] == "1"
+
+    begin
+      report = Glyphs::PruneRunner.call(dry_run: !commit)
+    rescue Glyphs::PruneRunner::VerificationError => e
+      warn "[glyphs:prune_icons] #{e.message}"
+      abort "[glyphs:prune_icons] prune verification failed — aborting."
+    end
+
+    puts report
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glyphs
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -73,12 +73,18 @@ files:
 - lib/glyphs/hero_icon.rb
 - lib/glyphs/huge_icon.rb
 - lib/glyphs/icon.rb
+- lib/glyphs/icon_pruner.rb
+- lib/glyphs/icon_reference.rb
 - lib/glyphs/linear_icon.rb
 - lib/glyphs/lucide_icon.rb
 - lib/glyphs/phosphor_icon.rb
+- lib/glyphs/prune_report.rb
+- lib/glyphs/prune_runner.rb
 - lib/glyphs/radix_icon.rb
+- lib/glyphs/railtie.rb
 - lib/glyphs/rubocop.rb
 - lib/glyphs/sidekick_icon.rb
+- lib/glyphs/source_scanner.rb
 - lib/glyphs/tabler_icon.rb
 - lib/glyphs/version.rb
 - lib/glyphs/weather_icon.rb
@@ -86,6 +92,7 @@ files:
 - lib/rubocop/cop/glyphs/legacy_icon_helper.rb
 - lib/rubocop/cop/glyphs/library_call_helpers.rb
 - lib/rubocop/cop/glyphs/prefer_library_component.rb
+- lib/tasks/glyphs.rake
 homepage: https://github.com/mhenrixon/glyphs
 licenses:
 - MIT
@@ -102,7 +109,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="