glyphs 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83fd5e39450d1ac698d0add8d4344ecbd9001783695ac15f48f7276aba89a05f
-  data.tar.gz: a1c570feaf9d4e623958a626d1a5ffe42fc55d0e4347cd659539e00335a8af3d
+  metadata.gz: 0e0ed91cb2af5c3414aa3db654c772ec9c3ad506f4f7d9998223b76144897d33
+  data.tar.gz: 37a81b162e603e83060c7adfd395cef55f1d20c4896d9bb4d4b0ec96e3e83908
 SHA512:
-  metadata.gz: b077d3f979ffcd2a41244c48fa6bba440400f44fb48d6033d35208661bfbfc434b65b22a44ee4548771bcac6ac87a97622e14dd6bb4303768066ae61a272ddb4
-  data.tar.gz: a0b9a383c8197cc0079ecea51e3c9879fcb884b12e852aecf6f8a21dd8b0a06e9624bfb753f6a2faf02eec9043c90f4570e2ff40717ed2a648c9b93b52888b62
+  metadata.gz: 82eb60a70f7fd553e38130cf57025834ca8daf9c02c54c315df9900c07346138eb1230d48783204509ab897791203434db38cf62ed1035337bf3ded8aee7b2ed
+  data.tar.gz: 188c29bbe5a8a8f6dbae785e39af4a6b49ee4c660a302bf8fd032525012c47ce7b6559e45c342f5b6544f06994162ab443b4e4fc8e51eb81b2c0bbc6ceb38152

data/CHANGELOG.md

@@ -15,6 +15,23 @@
   `Glyphs::MainRactor::Unavailable` naming the icon, and `Glyphs.preload_svg`
   still seeds a Ractor's cache. glyphs does not depend on ractor-dispatch: add
   it outside Rails 8.2. Refs zoolutions/phlex-reactive#363
+- **`config.raise_on_prunable` fails a render the prune would delete.** Off by
+  default. With it on, typically in the test environment, rendering such an icon
+  raises `Glyphs::PrunableIconError`, naming the library, variant and name, so a
+  test fails instead of production. The guard asks the pruner, so under one
+  configuration the two agree. The first uncached render scans the source, once
+  per process; with the setting off nothing is scanned. Enabling it may fail specs, and each such
+  failure is an icon that would have gone missing in production. Refs #35
+
+### Fixed
+
+- **`glyphs:prune_icons` no longer deletes icons forwarded through a wrapper
+  component.** A file that passes a non-literal under a key like an icon
+  (`Badge(icon:)`, `Badge(icon: row.first)`) now keeps its icon-name-shaped
+  literals for every dynamically-rendered library. They were dropped when the
+  file itself had no dynamic icon call, so the icon raised
+  `Icons::IconNotFound` in production only. Pruning can only keep a little more
+  than before. Refs #35
 
 ## [0.3.0] - 2026-10-15
 

data/README.md

@@ -180,11 +180,48 @@ The scanner resolves them from source, so you rarely need `keep_icons` at all:
   constant named like one (`ICON = :bell`, `STATUS_ICONS = { .. => :warning }`,
   including trailing `.freeze`) — are kept for every dynamically-rendered
   library, so a name declared in one file and rendered from another survives.
+- **Forwarded** — a file that passes a non-literal under a key like an icon
+  (`Badge(icon:)`, `Badge(icon: row.first)`) hands a name on to a wrapper
+  component, so every icon-name-shaped literal in that file is kept for every
+  dynamically-rendered library. `ROWS = [[:bell, 1]]` survives when the row
+  reaches `Badge(icon:)`, and `Badge`'s `LucideIcon(@icon)` lives in another file.
 
 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.
 
+A static scan can't follow every value. A literal passed positionally to a
+wrapper (`m.row("Alerts", :anchor)`) is still pruned, and so is a forwarded
+keyword in a template, which is text-scanned. Nothing fails until production:
+development and test keep every SVG, and the post-prune verification doesn't
+assert harvested names. `raise_on_prunable` closes that gap.
+
+### `raise_on_prunable` — fail the test that renders a prunable icon
+
+```ruby
+# config/environments/test.rb, or an initializer guarded by Rails.env.test?
+Glyphs.configure do |config|
+  config.raise_on_prunable = true
+end
+```
+
+With it on, rendering an icon the prune would delete raises
+`Glyphs::PrunableIconError`, naming the library, variant and name. Every page a
+test renders becomes a check, and each failure is a production bug: name the icon
+in an icon position (`icon: :anchor`, an `ICON` constant) or list it in
+`keep_icons`.
+
+The guard asks the pruner itself, so the two agree, including on `keep_icons`
+globs and on the libraries a prune leaves alone. That holds for the configuration
+the test runs with: a `keep_icons`, `fallback_icons` or `prune_source_globs` that
+differs by `Rails.env` makes the guard answer for a different keep-set than your
+image build prunes with. The first uncached render scans
+your source, once per process (a parallel test worker scans for itself), and
+cache hits never reach the check. A name that doesn't exist at all still meets
+the missing-icon policy. The default is `false`, which scans nothing, and
+source changed after the scan isn't seen until the process restarts, so keep this
+in the test environment.
+
 ### `keep_icons` — the last-resort escape hatch
 
 For names a static scan genuinely can't see — read from a database, an ENV var,

data/lib/glyphs/configuration.rb

@@ -24,8 +24,11 @@ module Glyphs
     # 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).
+    # raise_on_prunable: boolean; when true, rendering an icon glyphs:prune_icons
+    #   would delete raises Glyphs::PrunableIconError. For the test environment:
+    #   the first uncached render scans the source, once per process.
     attr_accessor :raise_on_missing, :on_missing_icon, :fallback_icons, :cache_svgs,
-      :keep_icons, :prune_source_globs
+      :keep_icons, :prune_source_globs, :raise_on_prunable
     attr_reader :svg_cache_size
 
     def initialize
@@ -36,6 +39,7 @@ module Glyphs
       @svg_cache_size = DEFAULT_SVG_CACHE_SIZE
       @keep_icons = []
       @prune_source_globs = nil
+      @raise_on_prunable = false
     end
 
     def svg_cache_size=(size)

data/lib/glyphs/icon_pruner.rb

@@ -38,14 +38,23 @@ module Glyphs
           next
         end
 
-        keep = keep_names_for(library, variant)
-        stat = prune_group(library, variant, files, keep, deleted_names)
-        stats << stat
+        stats << prune_group(library, variant, files, unkept_files(library, variant, files), deleted_names)
       end
 
       PruneReport.new(stats:, deleted_names:, dry_run: @dry_run)
     end
 
+    # The Set of IconReferences #call would delete: same files, same keep-sets.
+    # Deletes nothing and warns about nothing.
+    def prunable
+      groups = grouped_files.select { |(library, _), _| library_used?(library) }
+      groups.each_with_object(Set.new) do |((library, variant), files), references|
+        unkept_files(library, variant, files).each do |path|
+          references << IconReference.new(library:, variant:, name: File.basename(path, ".svg"))
+        end
+      end
+    end
+
     private
 
     # { [library, variant] => [absolute svg paths] }, excluding the animated lib.
@@ -69,25 +78,19 @@ module Glyphs
       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
+    # The one decision of what goes, shared by #call and #prunable.
+    def unkept_files(library, variant, files)
+      keep = keep_names_for(library, variant)
+      files.reject { |path| keep_file?(File.basename(path, ".svg"), keep) }
+    end
 
-        deleted += 1
-        bytes_freed += File.size(path)
-        deleted_names << name
-        File.delete(path) unless @dry_run
-      end
+    def prune_group(library, variant, files, unkept, deleted_names)
+      bytes_freed = unkept.sum { |path| File.size(path) }
+      deleted_names.concat(unkept.map { |path| File.basename(path, ".svg") })
+      unkept.each { |path| File.delete(path) } unless @dry_run
 
-      PruneReport::LibraryStat.new(library:, variant:, kept:, deleted:, bytes_freed:)
+      PruneReport::LibraryStat.new(library:, variant:, kept: files.size - unkept.size, deleted: unkept.size,
+        bytes_freed:)
     end
 
     def keep_file?(name, keep)

data/lib/glyphs/prunable_icon_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Raised on render, with Configuration#raise_on_prunable on, for an icon that
+  # exists now and that glyphs:prune_icons would delete from the image. Not an
+  # Icons::IconNotFound: the missing-icon policy must not turn it into a fallback.
+  class PrunableIconError < StandardError; end
+end

data/lib/glyphs/prune_guard.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Backs Configuration#raise_on_prunable: a render of an icon the prune would
+  # delete fails in the test suite instead of in production, where development's
+  # full SVG tree no longer hides it. Dynamic keeps are advisory, so
+  # PruneRunner#verify! cannot catch this; a render names a real icon, so here
+  # it is safe to fail.
+  #
+  # It asks the pruner, so under one configuration the two agree, and it asks
+  # once: the scan runs in the constructor and #check! only reads the result. It
+  # deletes nothing. Glyphs keeps one per process, replacing it when #current?
+  # says the settings behind that answer changed.
+  class PruneGuard
+    def initialize(config: Glyphs.configuration, runner: PruneRunner.new(config:))
+      @keep_settings = keep_settings(config)
+      @prunable = runner.prunable
+    end
+
+    def current?(config)
+      @keep_settings == keep_settings(config)
+    end
+
+    def check!(name:, library:, variant:)
+      library = library.to_sym
+      variant = variant.nil? ? IconReference.default_variant_for(library) : IconReference.normalize_variant(variant)
+      reference = IconReference.new(library:, variant:, name: name.to_s)
+      raise PrunableIconError, message(reference) if @prunable.include?(reference)
+    end
+
+    private
+
+    # A hash of the values, so a list changed in place reads as a change.
+    def keep_settings(config)
+      [config.keep_icons, config.fallback_icons, config.prune_source_globs].hash
+    end
+
+    def message(reference)
+      icon = [reference.library, reference.variant, reference.name].compact.join("/")
+      "glyphs:prune_icons would delete #{icon}, so this render would fail in production. " \
+        "Name it in an icon position (`icon: :#{reference.name.tr('-', '_')}`, an `ICON` constant) " \
+        "or list it in keep_icons."
+    end
+  end
+end

data/lib/glyphs/prune_runner.rb

@@ -28,6 +28,12 @@ module Glyphs
       report
     end
 
+    # The IconReferences a prune would delete, deleting nothing: the pruner's own
+    # answer over the same scan and keep-sets #call uses.
+    def prunable
+      pruner.prunable
+    end
+
     # Asserts every kept icon resolves to a file on disk. Raises
     # VerificationError listing the first few misses.
     def verify!

data/lib/glyphs/source_scanner.rb

@@ -156,7 +156,7 @@ module Glyphs
     # 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
+    # Three sources of candidate names, all harvested only from literals so we
     # never invent a reference:
     #
     #   1. file-scoped — a file that dynamically renders library L contributes
@@ -166,6 +166,10 @@ module Glyphs
     #      (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.
+    #   3. forwarded — a file passing a non-literal under a key like an icon
+    #      (`Badge(icon:)`, `Badge(icon: row.first)`) hands a name on to a wrapper
+    #      that renders it elsewhere, so ALL its literals are candidates for
+    #      every dynamically-rendered library, as declarations are.
     #
     # Names resolve at the library's default variant: a dynamic call names no
     # variant in practice, and the pruner keeps per (library, variant).
@@ -179,6 +183,7 @@ module Glyphs
       # Folds one file's visitor results into the running accumulator.
       def absorb(visitor)
         @declaration_literals.merge(visitor.declaration_literals)
+        @declaration_literals.merge(visitor.file_literals) if visitor.forwards_icon
         return if visitor.dynamic_libraries.empty?
 
         @dynamic_libraries.merge(visitor.dynamic_libraries)
@@ -205,18 +210,28 @@ module Glyphs
       # Excludes CSS classes (spaces/slashes), paths, and interpolated strings.
       ICON_NAME_LITERAL = /\A[a-z][a-z0-9_-]*\z/
 
+      # Values of an icon-keyed pair that forward nothing: a declaration harvest
+      # reads the names, and `icon: nil` or `icon_size: 16` names no icon at all.
+      LITERAL_VALUES = [
+        Prism::SymbolNode, Prism::StringNode, Prism::NilNode, Prism::TrueNode, Prism::FalseNode,
+        Prism::IntegerNode, Prism::FloatNode
+      ].freeze
+
       # 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
+      # Whether this file passes a non-literal under a key like an icon.
+      attr_reader :forwards_icon
 
       def initialize(references)
         @references = references
         @dynamic_libraries = Set.new
         @file_literals = Set.new
         @declaration_literals = Set.new
+        @forwards_icon = false
         super()
       end
 
@@ -247,10 +262,14 @@ module Glyphs
       end
 
       # `icon: :activity` / `menu_icon: "gear"` — a hash pair keyed like an icon
-      # declares an icon name, wherever it lives.
+      # declares an icon name, wherever it lives. A non-literal value there
+      # (`icon:`, `icon: row.first`) forwards a name instead.
       def visit_assoc_node(node)
         key = node.key
-        collect_declaration(node.value) if key.is_a?(Prism::SymbolNode) && key.unescaped.match?(/icon/i)
+        if key.is_a?(Prism::SymbolNode) && key.unescaped.match?(/icon/i)
+          collect_declaration(node.value)
+          @forwards_icon ||= forwarded_value?(node.value)
+        end
         super
       end
 
@@ -258,6 +277,20 @@ module Glyphs
 
       attr_reader :references
 
+      # A container forwards when anything inside it does: `icon: [:a, pick]`.
+      def forwarded_value?(value_node)
+        value_node = unwrap_declaration_wrappers(value_node)
+        case value_node
+        when Prism::ArrayNode then value_node.elements.any? { |element| forwarded_value?(element) }
+        when Prism::HashNode then value_node.elements.any? { |element| forwarded_pair?(element) }
+        else LITERAL_VALUES.none? { |literal| value_node.is_a?(literal) }
+        end
+      end
+
+      def forwarded_pair?(element)
+        !element.is_a?(Prism::AssocNode) || forwarded_value?(element.value)
+      end
+
       def record(node)
         method = node.name.to_s
         if GENERIC_CALLS.include?(node.name)

data/lib/glyphs/version.rb

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

data/lib/glyphs.rb

@@ -38,6 +38,8 @@ module Glyphs
   # readers never take it, so svg_for runs in any Ractor once finalized.
   @lock = Monitor.new
   @configuration = Configuration.new
+  @prune_guard = nil
+  @prune_guard_lock = Mutex.new
 
   class << self
     # The current configuration: a plain read, shareable after finalize!.
@@ -49,6 +51,7 @@ module Glyphs
     end
 
     def reset_configuration!
+      @prune_guard_lock.synchronize { @prune_guard = nil }
       @lock.synchronize { @configuration = Configuration.new }
     end
 
@@ -128,12 +131,28 @@ module Glyphs
       resolve_svg(name:, library:, variant:, attributes:)
     end
 
+    # Only a miss gets here, and only on the main Ractor. A name with no file is
+    # never prunable, so it passes the guard and meets the missing-icon policy.
     def resolve_svg(name:, library:, variant:, attributes:)
+      prune_guard&.check!(name:, library:, variant:)
       build_svg(name:, library:, variant:, attributes:)
     rescue Icons::IconNotFound => e
       handle_missing_icon(e, name:, library:, variant:, attributes:)
     end
 
+    # nil while raise_on_prunable is off, so that path reads nothing. A racing
+    # thread waits for the first scan rather than repeating it. Not @lock: this
+    # runs under the SvgCache mutex, and a configure block holding @lock may render.
+    def prune_guard
+      config = configuration
+      return unless config.raise_on_prunable
+
+      @prune_guard_lock.synchronize do
+        @prune_guard = PruneGuard.new(config:) unless @prune_guard&.current?(config)
+        @prune_guard
+      end
+    end
+
     def build_svg(name:, library:, variant:, attributes:)
       Icons::Icon.new(name:, library:, variant:, arguments: attributes).svg
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glyphs
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -79,6 +79,8 @@ files:
 - lib/glyphs/lucide_icon.rb
 - lib/glyphs/main_ractor.rb
 - lib/glyphs/phosphor_icon.rb
+- lib/glyphs/prunable_icon_error.rb
+- lib/glyphs/prune_guard.rb
 - lib/glyphs/prune_report.rb
 - lib/glyphs/prune_runner.rb
 - lib/glyphs/radix_icon.rb