glyphs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a379bf83aad5e7a6adfc47f2f8cced12baa7ce0e970b0b675747445f8ab9f99
+  data.tar.gz: d134dcee770ac2629575ef80b020b9e61982e55bd8affd0e944ce5316ad22e4d
+SHA512:
+  metadata.gz: 8d0a4346f8b888f8be02ec3403b46262dfa5593276d767cc37215e5eb03d2c2a7261d7f9709ddb2fad1d1715220dfcecfd6c5dbb928818810cf5442c62320c2e
+  data.tar.gz: 444366fd42ba9ba2a8b422a0b2ad8ec8674bc737e477fc10e91cc7f7890b9cdc52bb76eb8b5056fd87c80123a959f2fe919e25f1e95be2f09abfcb2746494961

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-07-07
+
+### Added
+
+- `Glyphs::Icon` base Phlex component rendering SVGs through the `icons` gem (rails_icons).
+- Library components exposed via `Phlex::Kit`: `LucideIcon`, `PhosphorIcon`, `HeroIcon`, `TablerIcon`,
+  `FeatherIcon`, `BoxIcon`, `FlagIcon`, `HugeIcon`, `LinearIcon`, `RadixIcon`, `SidekickIcon`,
+  `WeatherIcon`, `AnimatedIcon`.
+- `Glyphs.register_library` for custom icon libraries.
+- Configurable missing-icon policy (`raise_on_missing_icon`, `on_missing_icon` hook, `fallback_icons`)
+  and per-process SVG render cache (`cache_svgs`).
+- RuboCop plugin (lint_roller) with `Glyphs/LegacyIconHelper`, `Glyphs/IconResolution`, and
+  `Glyphs/PreferLibraryComponent`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 David Alejandro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Glyphs
+
+Phlex icon components for every [rails_icons](https://github.com/rails-designer/rails_icons) library —
+plus bundled RuboCop cops that validate icon names at lint time and autocorrect legacy icon helpers.
+
+```ruby
+class ApplicationComponent < Phlex::HTML
+  include Glyphs
+end
+
+LucideIcon(:house, class: "size-4")
+PhosphorIcon("lock", variant: :bold)
+HeroIcon(:check, class: "size-5 text-success")
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "glyphs"
+```
+
+Glyphs renders the SVG files that rails_icons syncs into your app. If you haven't already:
+
+```bash
+rails generate rails_icons:install --libraries=lucide heroicons
+rails generate rails_icons:sync --libraries=lucide heroicons
+```
+
+Outside Rails, configure the [icons](https://rubygems.org/gems/icons) gem directly:
+
+```ruby
+Icons.configure do |config|
+  config.base_path = File.expand_path(__dir__)
+  config.icons_path = "svg/icons"
+end
+```
+
+## Components
+
+`include Glyphs` (a `Phlex::Kit`) into your component base class and call icons as capitalized methods:
+
+| Component | rails_icons library |
+|---|---|
+| `LucideIcon` | lucide |
+| `PhosphorIcon` | phosphor |
+| `HeroIcon` | heroicons |
+| `TablerIcon` | tabler |
+| `FeatherIcon` | feather |
+| `BoxIcon` | boxicons |
+| `FlagIcon` | flags |
+| `HugeIcon` | hugeicons |
+| `LinearIcon` | linear |
+| `RadixIcon` | radix |
+| `SidekickIcon` | sidekickicons |
+| `WeatherIcon` | weather |
+| `AnimatedIcon` | animated (bundled spinners: `faded-spinner`, `bouncing-dots`, ...) |
+
+Names can be symbols or strings; underscores are dasherized (`:circle_check` → `circle-check.svg`).
+`variant:` selects the library variant (default comes from your rails_icons/icons configuration);
+every other keyword (`class:`, `data:`, `stroke_width:`, ...) is forwarded onto the `<svg>` tag.
+
+The generic component requires an explicit library:
+
+```ruby
+Icon(:house, library: :lucide) # flagged by Glyphs/PreferLibraryComponent, prefer LucideIcon(:house)
+```
+
+Custom libraries get first-class components too:
+
+```ruby
+Glyphs.register_library(:brand, component: :BrandIcon)
+BrandIcon(:logo)
+```
+
+(The SVG location for a custom library is configured through rails_icons/icons custom-library config.)
+
+## Missing-icon policy
+
+```ruby
+# config/initializers/glyphs.rb
+Glyphs.configure do |config|
+  # Re-raise Icons::IconNotFound? Default: true locally (dev/test), never blind in production.
+  config.raise_on_missing_icon = -> { Rails.env.local? }
+
+  # Instrumentation hook, called before the fallback renders.
+  config.on_missing_icon = lambda do |error, name:, library:, variant:|
+    Rails.logger.error("Icon missing: #{library}/#{variant}/#{name} (#{error.message})")
+  end
+
+  # Rendered instead of the missing icon (per library). nil/absent => re-raise.
+  config.fallback_icons = {
+    lucide: "circle-question-mark",
+    phosphor: "question",
+    heroicons: "question-mark-circle"
+  }
+
+  # Memoize rendered SVG strings per [library, variant, name, attributes]. Default: true.
+  # Note: fallback renders are cached under the original name, so on_missing_icon
+  # fires once per process per missing icon rather than on every render.
+  config.cache_svgs = true
+end
+```
+
+## RuboCop cops
+
+Add the plugin (RuboCop >= 1.72):
+
+```yaml
+# .rubocop.yml
+plugins:
+  - glyphs
+```
+
+(Classic `require: [glyphs/rubocop]` also works, but you must enable the cops yourself.)
+
+### Glyphs/LegacyIconHelper
+
+Autocorrects legacy helper calls to Glyphs components:
+
+```ruby
+_lucide(:house, class: "size-4")   # => LucideIcon(:house, class: "size-4")
+_heroicon(:check)                  # => HeroIcon(:check)
+icon("check", library: "lucide")   # => LucideIcon("check")
+icon("check")                      # => HeroIcon("check")  (DefaultLibraryComponent)
+```
+
+```yaml
+Glyphs/LegacyIconHelper:
+  Include:
+    - app/**/*.rb
+  DefaultLibraryComponent: HeroIcon
+  # Mappings replaces the built-in defaults (_lucide/_phosphor/_hero/_heroicon/_tabler):
+  # Mappings:
+  #   _custom: CustomIcon
+```
+
+### Glyphs/IconResolution
+
+Validates statically-known icon names against your synced SVG directories, honors literal
+`variant:` keywords, suggests close matches (with autocorrect for unambiguous typos and the
+Lucide v1 renames), and flags raw `iconify` class strings:
+
+```ruby
+LucideIcon(:alert_triangle)                 # => corrected to LucideIcon(:triangle_alert)
+span(class: "iconify lucide--house size-4") # => corrected to LucideIcon(:house, class: "size-4")
+```
+
+```yaml
+Glyphs/IconResolution:
+  Include:
+    - app/**/*.rb
+  IconsPath: app/assets/svg/icons
+  # Libraries merges over the built-in defaults (component => Dir/DefaultVariant):
+  Libraries:
+    PhosphorIcon: { Dir: phosphor, DefaultVariant: regular }
+```
+
+### Glyphs/PreferLibraryComponent
+
+```ruby
+Icon(:house, library: :lucide) # => LucideIcon(:house)
+```
+
+## Migrating an app off icon helpers
+
+1. Add `gem "glyphs"`, `include Glyphs` where the helpers used to be included.
+2. Add the plugin and cop config above to `.rubocop.yml`.
+3. Delete your local icon helper, then run:
+
+```bash
+bundle exec rubocop -A --only Glyphs/LegacyIconHelper,Glyphs/PreferLibraryComponent
+```
+
+4. Wire your old missing-icon logging into `Glyphs.configure` (see above).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/config/default.yml

@@ -0,0 +1,25 @@
+Glyphs/LegacyIconHelper:
+  Description: 'Replace legacy icon helpers (_lucide, _hero, icon(), ...) with Glyphs components.'
+  Enabled: true
+  VersionAdded: '0.1.0'
+  SafeAutoCorrect: true
+  # Mappings replaces the built-in defaults when set:
+  # Mappings:
+  #   _lucide: LucideIcon
+  #   _heroicon: HeroIcon
+  DefaultLibraryComponent: HeroIcon
+
+Glyphs/IconResolution:
+  Description: 'Validate that statically-known icon names exist in the synced SVG directories.'
+  Enabled: true
+  VersionAdded: '0.1.0'
+  IconsPath: app/assets/svg/icons
+  # Libraries merges over the built-in defaults:
+  # Libraries:
+  #   PhosphorIcon: { Dir: phosphor, DefaultVariant: light }
+
+Glyphs/PreferLibraryComponent:
+  Description: 'Prefer library-specific components over generic Icon(..., library: ...).'
+  Enabled: true
+  VersionAdded: '0.1.0'
+  SafeAutoCorrect: true

data/lib/glyphs/animated_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class AnimatedIcon < Icon
+    LIBRARY = :animated
+  end
+end

data/lib/glyphs/box_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class BoxIcon < Icon
+    LIBRARY = :boxicons
+  end
+end

data/lib/glyphs/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class Configuration
+    DEFAULT_FALLBACK_ICONS = {
+      lucide: "circle-question-mark",
+      phosphor: "question",
+      heroicons: "question-mark-circle"
+    }.freeze
+
+    # raise_on_missing_icon: callable -> bool; when true, Icons::IconNotFound is re-raised.
+    # on_missing_icon: callable(error, name:, library:, variant:) instrumentation hook.
+    # 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_icon, :on_missing_icon, :fallback_icons, :cache_svgs
+
+    def initialize
+      @raise_on_missing_icon = -> { defined?(Rails) ? Rails.env.local? : true }
+      @on_missing_icon = ->(error, name:, library:, variant:) {}
+      @fallback_icons = DEFAULT_FALLBACK_ICONS.dup
+      @cache_svgs = true
+    end
+  end
+end

data/lib/glyphs/feather_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class FeatherIcon < Icon
+    LIBRARY = :feather
+  end
+end

data/lib/glyphs/flag_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class FlagIcon < Icon
+    LIBRARY = :flags
+  end
+end

data/lib/glyphs/hero_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class HeroIcon < Icon
+    LIBRARY = :heroicons
+  end
+end

data/lib/glyphs/huge_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class HugeIcon < Icon
+    LIBRARY = :hugeicons
+  end
+end

data/lib/glyphs/icon.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Base icon component. Prefer the library-specific subclasses (LucideIcon,
+  # HeroIcon, ...); the generic form requires an explicit library:
+  #
+  #   Icon(:house, library: :lucide)
+  class Icon < Phlex::HTML
+    LIBRARY = nil
+
+    def initialize(name, variant: nil, library: self.class::LIBRARY, **attributes)
+      if library.nil?
+        raise ArgumentError,
+          "library is required — use a library component (LucideIcon, HeroIcon, ...) or pass library:"
+      end
+
+      @name = name.to_s.tr("_", "-")
+      @library = library.to_sym
+      @variant = variant&.to_sym
+      @attributes = attributes
+
+      super()
+    end
+
+    def view_template
+      raw safe(svg_markup)
+    end
+
+    private
+
+    def svg_markup
+      Glyphs.svg_for(name: @name, library: @library, variant: @variant, attributes: @attributes)
+    end
+  end
+end

data/lib/glyphs/linear_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class LinearIcon < Icon
+    LIBRARY = :linear
+  end
+end

data/lib/glyphs/lucide_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class LucideIcon < Icon
+    LIBRARY = :lucide
+  end
+end

data/lib/glyphs/phosphor_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class PhosphorIcon < Icon
+    LIBRARY = :phosphor
+  end
+end

data/lib/glyphs/radix_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class RadixIcon < Icon
+    LIBRARY = :radix
+  end
+end

data/lib/glyphs/rubocop.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require "lint_roller"
+require "pathname"
+require "yaml"
+
+require_relative "version"
+require_relative "../rubocop/cop/glyphs/library_call_helpers"
+require_relative "../rubocop/cop/glyphs/legacy_icon_helper"
+require_relative "../rubocop/cop/glyphs/icon_resolution"
+require_relative "../rubocop/cop/glyphs/prefer_library_component"
+
+module Glyphs
+  module RuboCop
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: "glyphs",
+          version: Glyphs::VERSION,
+          homepage: "https://github.com/mhenrixon/glyphs",
+          description: "Icon-name validation and legacy icon-helper autocorrection for Glyphs components."
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: Pathname.new(__dir__).join("../../config/default.yml")
+        )
+      end
+    end
+  end
+end

data/lib/glyphs/sidekick_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class SidekickIcon < Icon
+    LIBRARY = :sidekickicons
+  end
+end

data/lib/glyphs/tabler_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class TablerIcon < Icon
+    LIBRARY = :tabler
+  end
+end

data/lib/glyphs/version.rb

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

data/lib/glyphs/weather_icon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glyphs
+  class WeatherIcon < Icon
+    LIBRARY = :weather
+  end
+end

data/lib/glyphs.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "phlex"
+require "icons"
+require "zeitwerk"
+require_relative "glyphs/version"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/glyphs/version.rb")
+# The RuboCop plugin lives in a foreign namespace and is only loaded inside a
+# RuboCop process (see the bottom of this file).
+loader.ignore("#{__dir__}/glyphs/rubocop.rb")
+loader.ignore("#{__dir__}/rubocop")
+loader.setup
+
+# 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.
+Icons.config
+
+# Phlex icon components for every rails_icons library, exposed as a Phlex::Kit:
+#
+#   include Glyphs
+#   LucideIcon(:house, class: "size-4")
+module Glyphs
+  extend Phlex::Kit
+
+  @svg_cache = {}
+  @svg_cache_mutex = Mutex.new
+
+  class << self
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Defines a `Glyphs::Icon` subclass for a custom icon library and exposes it
+    # as a kit method. The library's SVG location itself is configured through
+    # the icons/rails_icons custom-library configuration.
+    #
+    #   Glyphs.register_library(:brand, component: :BrandIcon)
+    #   # => BrandIcon(:logo, class: "size-4")
+    def register_library(library, component:)
+      library = library.to_sym
+      name = component.to_sym
+
+      if const_defined?(name, false)
+        existing = const_get(name, false)
+        return existing if existing < Icon && library == existing::LIBRARY
+
+        raise ArgumentError, "Glyphs::#{name} is already defined and does not render the #{library} library"
+      end
+
+      klass = Class.new(Icon)
+      klass.const_set(:LIBRARY, library)
+      const_set(name, klass)
+    end
+
+    # Returns the SVG markup for an icon, applying the configured missing-icon
+    # policy (raise / instrument / fallback) and an optional per-process cache.
+    def svg_for(name:, library:, variant:, attributes:)
+      return render_svg(name:, library:, variant:, attributes:) unless configuration.cache_svgs
+
+      key = [library, variant, name, attributes]
+      @svg_cache_mutex.synchronize do
+        @svg_cache[key] ||= render_svg(name:, library:, variant:, attributes:)
+      end
+    end
+
+    def reset_cache!
+      @svg_cache_mutex.synchronize { @svg_cache = {} }
+    end
+
+    private
+
+    def render_svg(name:, library:, variant:, attributes:)
+      build_svg(name:, library:, variant:, attributes:)
+    rescue Icons::IconNotFound => e
+      handle_missing_icon(e, name:, library:, variant:, attributes:)
+    end
+
+    def build_svg(name:, library:, variant:, attributes:)
+      Icons::Icon.new(name:, library:, variant:, arguments: attributes).svg
+    end
+
+    def handle_missing_icon(error, name:, library:, variant:, attributes:)
+      raise error if configuration.raise_on_missing_icon.call
+
+      configuration.on_missing_icon.call(error, name:, library:, variant:)
+
+      fallback = configuration.fallback_icons[library.to_sym]
+      raise error if fallback.nil?
+
+      begin
+        build_svg(name: fallback, library:, variant:, attributes:)
+      rescue Icons::IconNotFound
+        raise error
+      end
+    end
+  end
+end
+
+# Make the RuboCop plugin resolvable lazily: RuboCop constantizes
+# Glyphs::RuboCop::Plugin (from the gemspec's default_lint_roller_plugin
+# metadata) when it loads plugins, which can happen long after this gem was
+# required — e.g. app boots first, cop specs load RuboCop later.
+Glyphs.autoload :RuboCop, File.expand_path("glyphs/rubocop", __dir__)

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

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Glyphs
+      # Validates that statically-known icon names exist in the synced SVG
+      # directories (`IconsPath`), suggests close matches for typos, and flags
+      # raw `iconify` class strings.
+      #
+      # Both Glyphs component calls (`LucideIcon(:house)`) and legacy helper
+      # calls (`_lucide(:house)`) are validated. A literal `variant:` keyword is
+      # honored; calls with dynamic names or variants are skipped.
+      #
+      # @example
+      #   # bad
+      #   LucideIcon(:non_existent_icon)
+      #   span(class: "iconify lucide--house size-4")
+      #
+      #   # good
+      #   LucideIcon(:house, class: "size-4")
+      class IconResolution < Base
+        extend AutoCorrector
+
+        DEFAULT_LIBRARIES = {
+          "LucideIcon" => { "Dir" => "lucide", "DefaultVariant" => "outline" },
+          "PhosphorIcon" => { "Dir" => "phosphor", "DefaultVariant" => "regular" },
+          "HeroIcon" => { "Dir" => "heroicons", "DefaultVariant" => "outline" },
+          "TablerIcon" => { "Dir" => "tabler", "DefaultVariant" => "outline" },
+          "SidekickIcon" => { "Dir" => "sidekickicons", "DefaultVariant" => "outline" }
+        }.freeze
+
+        LEGACY_HELPERS = {
+          "_lucide" => "LucideIcon",
+          "_phosphor" => "PhosphorIcon",
+          "_hero" => "HeroIcon",
+          "_heroicon" => "HeroIcon",
+          "_tabler" => "TablerIcon"
+        }.freeze
+
+        ICONIFY_PREFIX_TO_COMPONENT = {
+          "lucide" => "LucideIcon",
+          "phosphor" => "PhosphorIcon",
+          "heroicons" => "HeroIcon"
+        }.freeze
+
+        KNOWN_LUCIDE_RENAMES = {
+          "alert-triangle" => "triangle-alert",
+          "alert-circle" => "circle-alert",
+          "x-circle" => "circle-x"
+        }.freeze
+
+        ICONIFY_PATTERN = /\biconify\s+(lucide|phosphor|heroicons)--([a-z0-9-]+)/
+
+        RAW_MSG = "Use `%{component}(:%{symbol}, class: \"%{rest}\")` instead of raw `iconify %{library}--…` class."
+        RAW_DSTR_MSG = "Use `LucideIcon(name, class: ...)` etc. instead of building a raw " \
+                       "`iconify <library>--…` class string."
+        MISSING_MSG = "Icon `%{name}` not found in %{library}/%{variant}. %{suggestion}"
+
+        def on_str(node)
+          return if node.parent&.dstr_type?
+
+          check_iconify_string(node, node.value)
+        end
+
+        def on_dstr(node)
+          combined = node.children.filter_map { |child| child.str_type? ? child.value : "INTERPOLATED" }.join
+          return unless combined.include?("iconify ")
+
+          add_offense(node, message: RAW_DSTR_MSG)
+        end
+
+        def on_send(node)
+          return unless node.receiver.nil?
+
+          component = component_for(node.method_name)
+          return unless component
+
+          library = libraries[component]
+          return unless library
+
+          check_call(node, component, library)
+        rescue StandardError => e
+          source = node.location.expression.source_buffer.name
+          warn "[Glyphs/IconResolution] suppressed #{e.class}: #{e.message} at #{source}:#{node.first_line}"
+        end
+
+        private
+
+        def component_for(method_name)
+          name = method_name.to_s
+          return name if libraries.key?(name)
+
+          LEGACY_HELPERS[name]
+        end
+
+        def libraries
+          @libraries ||= DEFAULT_LIBRARIES.merge(cop_config["Libraries"] || {})
+        end
+
+        def check_call(node, _component, library)
+          name = literal_name(node.first_argument)
+          return unless name
+
+          variant = variant_for(node, library)
+          return if variant == :dynamic
+
+          available = available_icons(library["Dir"], variant)
+          return if available.empty?
+          return if available.include?(name)
+
+          suggestion = build_suggestion(name, available, library["Dir"])
+          add_offense(node.first_argument,
+            message: format(MISSING_MSG, name:, library: library["Dir"], variant:,
+              suggestion: suggestion[:msg])) do |corrector|
+            next unless suggestion[:autocorrect]
+
+            replacement =
+              if node.first_argument.sym_type?
+                ":#{suggestion[:name].tr('-', '_')}"
+              else
+                %("#{suggestion[:name]}")
+              end
+            corrector.replace(node.first_argument, replacement)
+          end
+        end
+
+        def variant_for(node, library)
+          pair = variant_pair(node)
+          return library["DefaultVariant"] if pair.nil?
+          return :dynamic unless pair.value.str_type? || pair.value.sym_type?
+
+          pair.value.value.to_s
+        end
+
+        def variant_pair(node)
+          hash = node.arguments.last
+          return nil unless hash&.hash_type?
+
+          hash.pairs.find { |pair| pair.key.sym_type? && pair.key.value == :variant }
+        end
+
+        def literal_name(node)
+          return unless node && (node.sym_type? || node.str_type?)
+
+          node.value.to_s.tr("_", "-")
+        end
+
+        def check_iconify_string(node, value)
+          return unless value.include?("iconify ")
+          return unless (match = ICONIFY_PATTERN.match(value))
+
+          iconify_prefix = match[1]
+          icon_name = match[2]
+          rest = remaining_classes(value, iconify_prefix, icon_name)
+          symbol = icon_name.tr("-", "_")
+          component = ICONIFY_PREFIX_TO_COMPONENT.fetch(iconify_prefix)
+
+          add_offense(node,
+            message: format(RAW_MSG, component:, library: iconify_prefix, symbol:, rest:)) do |corrector|
+            replacement = if rest.empty?
+              "#{component}(:#{symbol})"
+            else
+              "#{component}(:#{symbol}, class: \"#{rest}\")"
+            end
+
+            span_node = enclosing_span_call(node)
+            corrector.replace(span_node, replacement) if span_node
+          end
+        end
+
+        def enclosing_span_call(str_node)
+          pair = str_node.parent
+          return nil unless pair&.pair_type?
+          return nil unless pair.key.sym_type? && pair.key.value == :class
+
+          hash = pair.parent
+          return nil unless hash&.hash_type?
+          return nil if hash.pairs.size != 1
+
+          send_node = hash.parent
+          return nil unless send_node&.send_type?
+          return nil unless send_node.method_name == :span
+          return nil unless send_node.arguments.size == 1
+
+          send_node
+        end
+
+        def remaining_classes(value, library, icon_name)
+          value.sub(/iconify\s+#{library}--#{Regexp.escape(icon_name)}\s*/, "").strip
+        end
+
+        def build_suggestion(name, available, library_dir)
+          if library_dir == "lucide" && (renamed = KNOWN_LUCIDE_RENAMES[name]) && available.include?(renamed)
+            return { msg: "Did you mean `:#{renamed.tr('-', '_')}`? (Lucide v1 reordered prefix and suffix.)",
+                     autocorrect: true,
+                     name: renamed }
+          end
+
+          matches = fuzzy_match(name, available)
+          if matches.size == 1
+            { msg: "Did you mean `:#{matches.first.tr('-', '_')}`?", autocorrect: true, name: matches.first }
+          elsif matches.any?
+            list = matches.first(5).map { |match| "`:#{match.tr('-', '_')}`" }.join(", ")
+            { msg: "Did you mean one of: #{list}?", autocorrect: false, name: nil }
+          else
+            { msg: "No similar icons found.", autocorrect: false, name: nil }
+          end
+        end
+
+        def fuzzy_match(name, available)
+          name_parts = name.split("-")
+
+          scored = available.filter_map do |candidate|
+            score = part_score(name_parts, candidate.split("-"))
+            distance = damerau_levenshtein(name, candidate)
+            score += [3 - distance, 0].max if distance <= 2
+            score += 2 if name.length >= 3 && candidate.include?(name)
+            score += 2 if name.length >= 3 && candidate.split("-").any? { |part| part.start_with?(name[0..2]) }
+
+            [candidate, score] if score >= 3
+          end
+
+          scored.sort_by { |_, score| -score }.map(&:first).take(5)
+        end
+
+        def part_score(name_parts, candidate_parts)
+          score = 0
+          score += 5 if name_parts.sort == candidate_parts.sort
+          score += (name_parts & candidate_parts).size * 2
+          score += 4 if name_parts.size == 2 && candidate_parts.size == 2 && name_parts.reverse == candidate_parts
+          score
+        end
+
+        def damerau_levenshtein(left, right)
+          return right.length if left.empty?
+          return left.length if right.empty?
+          return 99 if (left.length - right.length).abs > 3
+
+          rows = Array.new(left.length + 1) { Array.new(right.length + 1, 0) }
+          (0..left.length).each { |i| rows[i][0] = i }
+          (0..right.length).each { |j| rows[0][j] = j }
+
+          (1..left.length).each do |i|
+            (1..right.length).each do |j|
+              cost = left[i - 1] == right[j - 1] ? 0 : 1
+              rows[i][j] = [
+                rows[i - 1][j] + 1,
+                rows[i][j - 1] + 1,
+                rows[i - 1][j - 1] + cost
+              ].min
+              if i > 1 && j > 1 && left[i - 1] == right[j - 2] && left[i - 2] == right[j - 1]
+                rows[i][j] = [rows[i][j], rows[i - 2][j - 2] + 1].min
+              end
+            end
+          end
+
+          rows[left.length][right.length]
+        end
+
+        def icons_base_path
+          @icons_base_path ||= File.expand_path(cop_config["IconsPath"] || "app/assets/svg/icons", Dir.pwd)
+        end
+
+        def available_icons(library_dir, variant)
+          self.class.available_icons_for(icons_base_path, library_dir, variant)
+        end
+
+        class << self
+          def available_icons_for(base_path, library_dir, variant)
+            @available_icons_cache ||= {}
+            @available_icons_cache[[base_path, library_dir, variant]] ||= load_icons(base_path, library_dir, variant)
+          end
+
+          private
+
+          def load_icons(base_path, library_dir, variant)
+            path = File.join(*[base_path, library_dir, variant].compact.reject { |part| part.to_s.empty? })
+            return [] unless Dir.exist?(path)
+
+            Dir.children(path).filter_map { |file| File.basename(file, ".svg") if file.end_with?(".svg") }.sort
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Glyphs
+      # Replaces legacy icon helper calls with Glyphs kit components.
+      #
+      # @example
+      #   # bad
+      #   _lucide(:house, class: "size-4")
+      #   icon("check", library: "lucide")
+      #   icon("check")
+      #
+      #   # good
+      #   LucideIcon(:house, class: "size-4")
+      #   LucideIcon("check")
+      #   HeroIcon("check") # `DefaultLibraryComponent` when no library: is given
+      class LegacyIconHelper < Base
+        include RangeHelp
+        include LibraryCallHelpers
+        extend AutoCorrector
+
+        MSG = "Use `%{component}(...)` instead of `%{helper}(...)`."
+        MSG_DYNAMIC = "Use a Glyphs component (e.g. `LucideIcon(...)`) instead of `icon(...)` with a dynamic library."
+        MSG_UNKNOWN = "Use a Glyphs component instead of `icon(...)`; add a `LibraryComponents` mapping " \
+                      "for library `%{library}`."
+
+        DEFAULT_MAPPINGS = {
+          _lucide: "LucideIcon",
+          _phosphor: "PhosphorIcon",
+          _hero: "HeroIcon",
+          _heroicon: "HeroIcon",
+          _tabler: "TablerIcon"
+        }.freeze
+
+        def on_send(node)
+          return unless node.receiver.nil?
+
+          if (component = mappings[node.method_name])
+            rename_offense(node, component)
+          elsif node.method_name == :icon && node.arguments.any?
+            correct_icon_call(node)
+          end
+        end
+
+        private
+
+        def rename_offense(node, component)
+          message = format(MSG, component:, helper: node.method_name)
+          add_offense(node.loc.selector, message:) do |corrector|
+            corrector.replace(node.loc.selector, component)
+          end
+        end
+
+        def correct_icon_call(node)
+          return if node.first_argument.hash_type? # no name argument; not an icon render call
+
+          pair = library_pair(node)
+          if pair.nil?
+            rename_offense(node, default_component)
+          elsif literal_pair?(pair)
+            correct_icon_with_library(node, pair)
+          else
+            add_offense(node.loc.selector, message: MSG_DYNAMIC)
+          end
+        end
+
+        def correct_icon_with_library(node, pair)
+          library = pair.value.value.to_s
+          component = library_components[library]
+
+          if component.nil?
+            add_offense(node.loc.selector, message: format(MSG_UNKNOWN, library:))
+            return
+          end
+
+          message = format(MSG, component:, helper: :icon)
+          add_offense(node.loc.selector, message:) do |corrector|
+            corrector.replace(node.loc.selector, component)
+            remove_library_pair(corrector, pair)
+          end
+        end
+
+        def mappings
+          @mappings ||= begin
+            configured = cop_config["Mappings"] || {}
+            configured.empty? ? DEFAULT_MAPPINGS : configured.to_h { |key, value| [key.to_sym, value.to_s] }
+          end
+        end
+
+        def default_component
+          cop_config["DefaultLibraryComponent"] || "HeroIcon"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Glyphs
+      # Shared logic for cops that rewrite icon calls: locating a literal
+      # `library:`/`from:` pair, mapping libraries to Glyphs components, and
+      # removing the pair without leaving dangling commas.
+      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
+
+        private
+
+        def library_pair(node)
+          hash = node.arguments.last
+          return nil unless hash&.hash_type?
+
+          hash.pairs.find { |pair| pair.key.sym_type? && LIBRARY_KEYS.include?(pair.key.value) }
+        end
+
+        def literal_pair?(pair)
+          pair.value.str_type? || pair.value.sym_type?
+        end
+
+        def library_components
+          @library_components ||= LIBRARY_TO_COMPONENT.merge(cop_config["LibraryComponents"] || {})
+        end
+
+        def remove_library_pair(corrector, pair)
+          hash = pair.parent
+          range = hash.pairs.one? ? hash.source_range : pair.source_range
+          corrector.remove(
+            range_with_surrounding_comma(range_with_surrounding_space(range, side: :left), :left)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Glyphs
+      # Prefers library-specific components over the generic `Icon(...)` kit
+      # call with a `library:` argument.
+      #
+      # @example
+      #   # bad
+      #   Icon(:house, library: :lucide)
+      #
+      #   # good
+      #   LucideIcon(:house)
+      class PreferLibraryComponent < Base
+        include RangeHelp
+        include LibraryCallHelpers
+        extend AutoCorrector
+
+        MSG = "Use `%{component}(...)` instead of `Icon(..., library: ...)`."
+        MSG_DYNAMIC = "Prefer a library-specific Glyphs component over `Icon(...)` with a dynamic library."
+
+        def on_send(node)
+          return unless node.receiver.nil? && node.method_name == :Icon && node.arguments.any?
+
+          pair = library_pair(node)
+          return unless pair
+
+          unless literal_pair?(pair)
+            add_offense(node.loc.selector, message: MSG_DYNAMIC)
+            return
+          end
+
+          component = library_components[pair.value.value.to_s]
+          return unless component
+
+          message = format(MSG, component:)
+          add_offense(node.loc.selector, message:) do |corrector|
+            corrector.replace(node.loc.selector, component)
+            remove_library_pair(corrector, pair)
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: glyphs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mikael Henriksson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails_icons
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Glyphs renders SVG icons as Phlex components (LucideIcon, PhosphorIcon,
+  HeroIcon, ...) from rails_icons-synced icon sets, with configurable missing-icon
+  handling and bundled RuboCop cops that validate icon names and autocorrect legacy
+  icon helpers.
+email: mikael@zoolutions.llc
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/default.yml
+- lib/glyphs.rb
+- lib/glyphs/animated_icon.rb
+- lib/glyphs/box_icon.rb
+- lib/glyphs/configuration.rb
+- lib/glyphs/feather_icon.rb
+- lib/glyphs/flag_icon.rb
+- lib/glyphs/hero_icon.rb
+- lib/glyphs/huge_icon.rb
+- lib/glyphs/icon.rb
+- lib/glyphs/linear_icon.rb
+- lib/glyphs/lucide_icon.rb
+- lib/glyphs/phosphor_icon.rb
+- lib/glyphs/radix_icon.rb
+- lib/glyphs/rubocop.rb
+- lib/glyphs/sidekick_icon.rb
+- lib/glyphs/tabler_icon.rb
+- lib/glyphs/version.rb
+- lib/glyphs/weather_icon.rb
+- lib/rubocop/cop/glyphs/icon_resolution.rb
+- lib/rubocop/cop/glyphs/legacy_icon_helper.rb
+- lib/rubocop/cop/glyphs/library_call_helpers.rb
+- lib/rubocop/cop/glyphs/prefer_library_component.rb
+homepage: https://github.com/mhenrixon/glyphs
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mhenrixon/glyphs
+  changelog_uri: https://github.com/mhenrixon/glyphs/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mhenrixon/glyphs/issues
+  default_lint_roller_plugin: Glyphs::RuboCop::Plugin
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Phlex icon components for every rails_icons library
+test_files: []