glyphs 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb4ffc81dcfd96faf6a0f23e3f57780340db27348666e520c7bbc747af04065e
-  data.tar.gz: 48e331ff55405e3c054fd0464a50a38ccf75df6d3e837e2a0edf3e3a18894de8
+  metadata.gz: 0e0ed91cb2af5c3414aa3db654c772ec9c3ad506f4f7d9998223b76144897d33
+  data.tar.gz: 37a81b162e603e83060c7adfd395cef55f1d20c4896d9bb4d4b0ec96e3e83908
 SHA512:
-  metadata.gz: 382ddd08e2e3cd53ce5164bbb6104bfc46b2c1caf48ac5d39b24e08f3a7594cbd0fa95424793d746c616bc7e4e8621ded6c0af1c5bf4357fa309ded75c49c79a
-  data.tar.gz: 1205d90f3d975f3a0880e3768d68c0daf12664c98efb01f715296fd1230dd24fb2af4981e74bd689f98ddf3b7b962c29dc7e3e4dd0125024c49944b312ba8995
+  metadata.gz: 82eb60a70f7fd553e38130cf57025834ca8daf9c02c54c315df9900c07346138eb1230d48783204509ab897791203434db38cf62ed1035337bf3ded8aee7b2ed
+  data.tar.gz: 188c29bbe5a8a8f6dbae785e39af4a6b49ee4c660a302bf8fd032525012c47ce7b6559e45c342f5b6544f06994162ab443b4e4fc8e51eb81b2c0bbc6ceb38152

data/CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 
-## [0.3.0]
+## [Unreleased]
+
+### Added
+
+- **A non-main Ractor renders icons it has not cached.** A miss there used to
+  raise `Ractor::IsolationError` (`@configuration from Icons`), because the
+  icons gem reads an unshareable module ivar and parses with Nokogiri, which
+  only the main Ractor can run. `Glyphs::MainRactor` now renders the miss on
+  the main Ractor through [ractor-dispatch](https://github.com/jhawthorn/ractor-dispatch)
+  (Ruby 4.0+, a dependency of Rails 8.2's Active Support) and that Ractor's
+  cache keeps the markup, byte for byte the main Ractor's. The missing-icon
+  policy runs on the main Ractor too. Without ractor-dispatch the miss raises
+  `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
 
 ### Changed
 
@@ -136,6 +169,23 @@
   rather than the primary mechanism. Only literals are harvested, so the scanner
   never invents a reference.
 
+## [0.2.1] - 2026-07-11
+
+### Added
+
+- **`glyphs:prune_icons` prunes unused icons for smaller Docker images.**
+  `Glyphs::SourceScanner` finds the icons an app references and the task deletes
+  every other synced SVG in the Docker build, keeping `config.keep_icons` (new,
+  for dynamic or data-driven names) and every `fallback_icons` entry, then
+  verifies each kept icon still resolves. Dry-run by default; it deletes only
+  with `PRUNE=1 GLYPHS_PRUNE_ICONS=1`. `config.prune_source_globs` adds paths to
+  scan. Refs #2
+
+### Changed
+
+- **Breaking:** `required_ruby_version` is now `>= 3.4` (CI runs 3.4 and 4.0).
+  Refs #2
+
 ## [0.2.0] - 2026-07-07
 
 ### Changed

data/README.md

@@ -130,11 +130,17 @@ readable on the main Ractor only, which is all an app without Ractors needs; ano
 object with a `#call` method that `Ractor.shareable?` accepts (frozen, with nothing unshareable inside) or
 `Ractor.shareable_proc` (Ruby 4.0+).
 
-The icons gem cannot render inside a non-main Ractor today (its configuration is unshareable module
-state, and Nokogiri is Ractor-unsafe), so each Ractor's cache starts empty and a miss there raises.
-Render on the main Ractor and hand the markup over with `Glyphs.preload_svg`; cache hits then work in that
-Ractor for calls without `data:` whose attributes the cache can apply (a `data:` call, or one with an attribute
-that renders uncached, still needs the icons gem):
+The icons gem cannot render inside a non-main Ractor (its configuration is unshareable module state, and
+Nokogiri is not marked Ractor-safe), so a miss in one renders on the main Ractor instead, through
+[ractor-dispatch](https://github.com/jhawthorn/ractor-dispatch) (Ruby 4.0+). Rails 8.2 apps have it through
+Active Support; elsewhere, add `gem "ractor-dispatch"`. The markup is the main Ractor's, byte for byte, and
+the calling Ractor's cache keeps it, so each icon crosses once per cache entry; cache hits never leave the
+Ractor. The missing-icon policy runs on the main Ractor too, `on_missing_icon` included. A call with an
+attribute that renders uncached, or any call with `cache_svgs = false`, goes to the main Ractor every time.
+
+Without ractor-dispatch, a miss in a non-main Ractor raises `Glyphs::MainRactor::Unavailable`, naming the
+icon. You can still render on the main Ractor and hand the markup over with `Glyphs.preload_svg`; cache hits
+then work in that Ractor for calls without `data:` whose attributes the cache can apply:
 
 ```ruby
 svg = Glyphs.svg_for(name: "house", library: :lucide, variant: nil, attributes: {}) # main Ractor
@@ -174,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/main_ractor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Renders an icon on the main Ractor for a non-main one. The icons gem reads
+  # Icons.configuration (an unshareable module ivar) and parses with Nokogiri
+  # (a C extension not marked Ractor-safe), so only the main Ractor can run it.
+  # ractor-dispatch (Ruby 4.0+, a dependency of Rails 8.2's Active Support)
+  # runs the render there and sends the markup back, where the calling Ractor's
+  # own cache keeps it: each icon crosses once per Ractor, not once per render.
+  module MainRactor
+    # Raised in a non-main Ractor that cannot reach the main one.
+    class Unavailable < StandardError; end
+
+    class << self
+      # Whether this Ractor runs the icons gem itself: the main Ractor, or any
+      # code on an engine without Ractors.
+      def current?
+        defined?(::Ractor) ? ::Ractor.main? : true
+      end
+
+      # Glyphs' render (missing-icon policy included) of these arguments, run
+      # on the main Ractor; an Icons::IconNotFound it raises is raised here.
+      def render(**arguments)
+        dispatcher = main_dispatcher(arguments)
+        shared = ::Ractor.make_shareable(arguments, copy: true) # a shareable block captures only shareable values
+        dispatcher.run { Glyphs.__send__(:render_svg, **shared) }
+      end
+
+      private
+
+      def main_dispatcher(arguments)
+        icon = "#{arguments[:library]}/#{arguments[:name]}"
+        unless defined?(::Ractor::Port)
+          raise Unavailable, "#{icon} isn't cached in this Ractor, and rendering it on the main Ractor " \
+                             "needs ractor-dispatch, which needs Ruby 4.0+. Seed the cache with Glyphs.preload_svg."
+        end
+
+        require "ractor/dispatch"
+        ::Ractor::Dispatch.main
+      rescue LoadError
+        raise Unavailable, "#{icon} isn't cached in this Ractor, and rendering it on the main Ractor " \
+                           "needs the ractor-dispatch gem (Rails 8.2 apps have it): add gem \"ractor-dispatch\"."
+      end
+    end
+  end
+end

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.3.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
 
@@ -120,12 +123,36 @@ module Glyphs
 
     private
 
+    # A non-main Ractor cannot run the icons gem, so it renders on the main
+    # Ractor (see MainRactor); the missing-icon policy runs there too.
     def render_svg(name:, library:, variant:, attributes:)
+      return MainRactor.render(name:, library:, variant:, attributes:) unless MainRactor.current?
+
+      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.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -77,7 +77,10 @@ files:
 - lib/glyphs/icon_reference.rb
 - lib/glyphs/linear_icon.rb
 - 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