glyphs 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dffbe50e2d6b992be18142abb575887e4b11ee8b26ad2afec2a3d94f0ed418cd
-  data.tar.gz: 59e4a5c55154ae1075f0c4cf0c7a3b2a1f767fc12416dd48b85d39b0bbed119a
+  metadata.gz: 245c7101b5dad69bf73859eea7a5d7c9027f1573d4e1b4ccbcde2bed3e61266f
+  data.tar.gz: 585c169414705979b1c45bf02ad87de324c5e6a16fb6a8ddb0e631961820e533
 SHA512:
-  metadata.gz: ef3a208721a23a5ab7272de80644228046b5f5bc42834d4f2f5f59f7da78bf141775cf6f8a192243abdcfdebdc444eab3bb87df33409fa429cc4571c76c4e0e5
-  data.tar.gz: cdc2a32800aa6c3a503dbccd0c8ee524e120fe1d418ba417bcf905f00e283fcc56c24be29dfec7f2dc4e0a6c57b268d2cb2577d9f5cc9b9b201483a6c0c93f2b
+  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

@@ -114,14 +114,41 @@ 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).
+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|
-  # 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] }

data/lib/glyphs/prune_runner.rb

@@ -47,14 +47,47 @@ module Glyphs
       @pruner ||= IconPruner.new(
         icons_root: @icons_root,
         references:,
-        keep_icons: config.keep_icons,
+        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 ||= SourceScanner.new(root: @root, **scanner_options).call
+      @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

data/lib/glyphs/source_scanner.rb

@@ -50,15 +50,38 @@ module Glyphs
       @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
-      references = Set.new
-      ruby_files.each { |path| scan_ruby(path, references) }
-      (template_files - ruby_files).each { |path| scan_template(path, references) }
-      references
+      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
@@ -73,9 +96,11 @@ module Glyphs
       patterns.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }.uniq
     end
 
-    def scan_ruby(path, references)
+    def scan_ruby(path, references, harvest)
       result = Prism.parse_file(path)
-      CallVisitor.new(references).visit(result.value)
+      visitor = CallVisitor.new(references)
+      visitor.visit(result.value)
+      harvest.absorb(visitor)
     rescue StandardError => e
       warn "[Glyphs::SourceScanner] skipped #{path}: #{e.class}: #{e.message}"
     end
@@ -127,12 +152,71 @@ module Glyphs
       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
 
@@ -146,6 +230,27 @@ module Glyphs
           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
 
@@ -164,7 +269,13 @@ module Glyphs
 
       def record_component(node, library)
         name = literal_string(first_argument(node))
-        return unless name
+        # 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
@@ -222,6 +333,29 @@ module Glyphs
       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.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glyphs
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Mikael Henriksson