glyphs 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 977c4ff81bc073f486991e32e6f27418419d440ddf15fc0cd8cb4357091abe8a
-  data.tar.gz: e2f6a73fa1545cae2d0714c9b2528b8b8d65b6474af45e1c73ae0999b5851cde
+  metadata.gz: 245c7101b5dad69bf73859eea7a5d7c9027f1573d4e1b4ccbcde2bed3e61266f
+  data.tar.gz: 585c169414705979b1c45bf02ad87de324c5e6a16fb6a8ddb0e631961820e533
 SHA512:
-  metadata.gz: 3f9570e3186cf64e294a7ca0f4de342d5ef16ba7bd6ac86017737617566bef92caff25ea9f665a2d3044abe76990ec9ed81d020e0cd943bfc3983c4228f86360
-  data.tar.gz: 49bd88b05cc3dfe3370348ade5a9498a26b6b7db12fb25fff63fb1ef0c8be94091cc71ef30728273a10a90be740d3fc0e867e751d5a505add4c1a1e0a0f741ce
+  metadata.gz: c5dfa80d58dbf2cc918f7a0ea2b74937156356137abca9c7297f0a974c1ee079176f335b6a5d33599f81f9d6af8f8efe324d9ab841f52126750bc80fb01abb38
+  data.tar.gz: 4a6b23ac1e990068f529e2ad7ed54fa078391256894d59b8a2390b5a9e773fd26a0dc55b11dcd3bfb00e13548791e80bcf1a5659bdd2ca82d26a5db1495893f1

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- **Dynamic icon calls are now resolved from source.** `SourceScanner` no longer
+  silently skips `LucideIcon(some_var)` / `PhosphorIcon(tile[:icon])` — it harvests
+  the literal name from two places so the pruner keeps it:
+  - _file-scoped_: a file that dynamically renders a library keeps every
+    icon-name-shaped literal in that file for that library (ternaries, `case`,
+    locals);
+  - _declaration-based_: literals in icon-declaration positions anywhere (a hash
+    pair keyed `/icon/i`, or a constant named `/ICON/`) are kept for every
+    dynamically-rendered library, closing the cross-file gap (e.g. a notifier
+    `ICON = :bell` constant rendered from a view).
+
+  This makes `keep_icons` a last-resort escape hatch (DB/ENV/gem-chrome names)
+  rather than the primary mechanism. Only literals are harvested, so the scanner
+  never invents a reference.
+
 ## [0.2.0] - 2026-07-07
 
 ### Changed

data/README.md

@@ -103,6 +103,82 @@ 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 and every
+configured `fallback_icons` (a pruned fallback would 500 on the next missing
+icon).
+
+### Dynamic calls are resolved automatically
+
+Most apps render most icons dynamically — `LucideIcon(tile[:icon])`,
+`PhosphorIcon(notification.icon)` — where the name lives in a `{ icon: :activity }`
+hash, a `CHANNEL_ICONS` map, or an `ICON = :bell` constant, sometimes in a
+different file from the render. A naïve static scan can't read those names and
+would prune the icons they use.
+
+The scanner resolves them from source, so you rarely need `keep_icons` at all:
+
+- **File-scoped** — a file that renders a library dynamically (`LucideIcon(x)`)
+  keeps every icon-name-shaped literal in that file for that library. Catches
+  ternaries (`@open ? "caret-up" : "caret-down"`), `case/when`, and locals.
+- **Declaration-based** — literals in icon-declaration positions *anywhere* — a
+  hash pair keyed like an icon (`icon: :gear`, `menu_icon: "house"`) or a
+  constant named like one (`ICON = :bell`, `STATUS_ICONS = { .. => :warning }`) —
+  are kept for every dynamically-rendered library, so a name declared in one
+  file and rendered from another survives.
+
+Only literals are harvested, so the scanner never invents a reference; the
+worst case is keeping a coincidentally icon-named string, which the post-prune
+verification tolerates.
+
+### `keep_icons` — the last-resort escape hatch
+
+For names a static scan genuinely can't see — read from a database, an ENV var,
+or a gem's own chrome — list them explicitly:
+
+```ruby
+# config/initializers/glyphs.rb
+Glyphs.configure do |config|
+  # 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,136 @@
+# 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: keep_icons,
+        fallback_icons: config.fallback_icons,
+        dry_run: @dry_run
+      )
+    end
+
+    def scanner
+      @scanner ||= SourceScanner.new(root: @root, **scanner_options)
+    end
+
+    def references
+      @references ||= scanner.call
+    end
+
+    # The pruner's keep-set: the configured keep_icons MERGED with the scanner's
+    # advisory per-library dynamic keeps (names harvested from dynamic call
+    # sites). Both are advisory — kept if present, never asserted by verify!.
+    #
+    # With no dynamic keeps, the configured value passes straight through (flat
+    # list or hash — the pruner accepts both). Otherwise everything folds into a
+    # per-library hash; a flat configured list applies to every kept library.
+    def keep_icons
+      dynamic = scanner.dynamic_keeps
+      return config.keep_icons if dynamic.empty?
+
+      merged = Hash.new { |hash, key| hash[key] = [] }
+      dynamic.each { |library, names| merged[library].concat(names.to_a) }
+      merge_configured_keeps(merged)
+      merged.transform_values(&:uniq)
+    end
+
+    # Folds the configured keep_icons into the per-library `merged` hash: a hash
+    # merges per library; a flat list applies to every library already present.
+    def merge_configured_keeps(merged)
+      case config.keep_icons
+      when Hash
+        config.keep_icons.each { |library, names| merged[library.to_sym].concat(Array(names)) }
+      else
+        flat = Array(config.keep_icons)
+        merged.each_key { |library| merged[library].concat(flat) }
+      end
+    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,361 @@
+# 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
+
+    # Confirmed references: icons named by a LITERAL in an icon call (or an
+    # iconify string). These are guaranteed-real — the pruner keeps them AND the
+    # runner asserts every one still resolves on disk after a prune.
+    def call
+      scan
+      @references
+    end
+
+    # Advisory per-library keeps harvested from DYNAMIC call sites (see
+    # DynamicHarvest). `{ library => Set[names] }`. These may include literals
+    # that aren't real icons (a CSS class, a method name), so — like the
+    # configured keep_icons — they are kept if present but NEVER asserted by
+    # verification. Feed them into the pruner's keep path, not the runner's
+    # expected-files set.
+    def dynamic_keeps
+      scan
+      @dynamic_keeps
+    end
+
+    private
+
+    def scan
+      return if @scanned
+
+      @references = Set.new
+      harvest = DynamicHarvest.new
+      ruby_files.each { |path| scan_ruby(path, @references, harvest) }
+      (template_files - ruby_files).each { |path| scan_template(path, @references) }
+      @dynamic_keeps = harvest.to_h
+      @scanned = true
+    end
+
+    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, harvest)
+      result = Prism.parse_file(path)
+      visitor = CallVisitor.new(references)
+      visitor.visit(result.value)
+      harvest.absorb(visitor)
+    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
+
+    # Accumulates the evidence needed to resolve DYNAMIC icon calls — ones whose
+    # name the AST can't read (`LucideIcon(tile[:icon])`) — across every scanned
+    # Ruby file, then turns that evidence into IconReferences.
+    #
+    # Two sources of candidate names, both harvested only from literals so we
+    # never invent a reference:
+    #
+    #   1. file-scoped — a file that dynamically renders library L contributes
+    #      every icon-name-shaped literal in that file as a candidate for L.
+    #      Catches ternaries, case/when, and locals near the call.
+    #   2. declaration-based — literals in icon-declaration positions ANYWHERE
+    #      (a hash pair keyed `/icon/i`, or a constant named `/ICON/`) are
+    #      candidates for EVERY dynamically-rendered library, since a bare
+    #      `ICON = :bell` in one file is often rendered from another.
+    #
+    # Names resolve at the library's default variant: a dynamic call names no
+    # variant in practice, and the pruner keeps per (library, variant).
+    class DynamicHarvest
+      def initialize
+        @dynamic_libraries = Set.new
+        @file_literals = Hash.new { |hash, key| hash[key] = Set.new }
+        @declaration_literals = Set.new
+      end
+
+      # Folds one file's visitor results into the running accumulator.
+      def absorb(visitor)
+        @declaration_literals.merge(visitor.declaration_literals)
+        return if visitor.dynamic_libraries.empty?
+
+        @dynamic_libraries.merge(visitor.dynamic_libraries)
+        visitor.dynamic_libraries.each do |library|
+          @file_literals[library].merge(visitor.file_literals)
+        end
+      end
+
+      # `{ library => Set[candidate names] }` for every dynamically-rendered
+      # library. Advisory: names may not be real icons, so callers keep them but
+      # must not assert they exist.
+      def to_h
+        @dynamic_libraries.to_h do |library|
+          [library, @file_literals[library] | @declaration_literals]
+        end
+      end
+    end
+
+    # Walks the Prism AST collecting icon references from call nodes.
+    class CallVisitor < Prism::Visitor
+      GENERIC_CALLS = %i[Icon icon].freeze
+
+      # A literal that could be an icon name: lowercase, digits, dashes/underscores.
+      # Excludes CSS classes (spaces/slashes), paths, and interpolated strings.
+      ICON_NAME_LITERAL = /\A[a-z][a-z0-9_-]*\z/
+
+      # Libraries this file renders with a dynamic (non-literal) first argument.
+      attr_reader :dynamic_libraries
+      # Icon-name-shaped literals anywhere in this file (file-scoped candidates).
+      attr_reader :file_literals
+      # Literals in icon-declaration positions (`icon:` pairs, `ICON` constants).
+      attr_reader :declaration_literals
+
+      def initialize(references)
+        @references = references
+        @dynamic_libraries = Set.new
+        @file_literals = Set.new
+        @declaration_literals = Set.new
+        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
+        collect_literal(@file_literals, node)
+        super
+      end
+
+      def visit_symbol_node(node)
+        collect_literal(@file_literals, node)
+        super
+      end
+
+      # `ICON = :bell` / `CHANNEL_ICONS = { .. => :whatsapp_logo }` — a constant
+      # named like an icon is a declaration of icon name(s), wherever it lives.
+      def visit_constant_write_node(node)
+        collect_declaration(node.value) if node.name.to_s.match?(/ICON/i)
+        super
+      end
+
+      # `icon: :activity` / `menu_icon: "gear"` — a hash pair keyed like an icon
+      # declares an icon name, wherever it lives.
+      def visit_assoc_node(node)
+        key = node.key
+        collect_declaration(node.value) if key.is_a?(Prism::SymbolNode) && key.unescaped.match?(/icon/i)
+        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))
+        # A dynamic first arg (variable, method call, hash lookup) can't be read
+        # off the call — flag the library so the harvest resolves its name from
+        # file-scoped and declaration literals instead.
+        unless name
+          @dynamic_libraries << library if first_argument(node)
+          return
+        end
+
+        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
+
+      # Adds a single symbol/string literal to `set` when it's shaped like an
+      # icon name (dasherized). Interpolated strings (StringNode with no static
+      # `unescaped`) and non-name-shaped literals are ignored.
+      def collect_literal(set, node)
+        raw = node.unescaped
+        return unless raw.is_a?(String) && raw.match?(ICON_NAME_LITERAL)
+
+        set << raw.tr("_", "-")
+      end
+
+      # Harvests icon names from a declaration value: a bare literal, an array of
+      # literals (`ICON = %i[a b]`), or a hash's values (`{ "sms" => :device }`).
+      def collect_declaration(value_node)
+        case value_node
+        when Prism::SymbolNode, Prism::StringNode
+          collect_literal(@declaration_literals, value_node)
+        when Prism::ArrayNode
+          value_node.elements.each { |element| collect_declaration(element) }
+        when Prism::HashNode
+          value_node.elements.grep(Prism::AssocNode).each { |assoc| collect_declaration(assoc.value) }
+        end
+      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.2"
 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.2
 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:
   - - ">="