glyphs 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 245c7101b5dad69bf73859eea7a5d7c9027f1573d4e1b4ccbcde2bed3e61266f
-  data.tar.gz: 585c169414705979b1c45bf02ad87de324c5e6a16fb6a8ddb0e631961820e533
+  metadata.gz: 5635cb76266896b0fb2d2e661844d27400be25b6e4a1190271279c7a4331517c
+  data.tar.gz: d8afd8c82d444afd15e951eba3aae5d1daaa0fce73efd7ac86fe725b9ce6dd09
 SHA512:
-  metadata.gz: c5dfa80d58dbf2cc918f7a0ea2b74937156356137abca9c7297f0a974c1ee079176f335b6a5d33599f81f9d6af8f8efe324d9ab841f52126750bc80fb01abb38
-  data.tar.gz: 4a6b23ac1e990068f529e2ad7ed54fa078391256894d59b8a2390b5a9e773fd26a0dc55b11dcd3bfb00e13548791e80bcf1a5659bdd2ca82d26a5db1495893f1
+  metadata.gz: dffab87c9e9862dad15042135dc4c2ef7fb5785dd848210538b6e63c5263b8be6fc4a9b6c5276ac8ee7523fe239e08bb63007aff45af8ba52721fd52d774a946
+  data.tar.gz: 492c537c6ebb87013ec9795406b78cfb6b50e06328e2cc9b8b072a0c359e71d575a6d4853450c66b7d3c526492679ad156ef858a122cf848f4856ae957b14e55

data/CHANGELOG.md

@@ -2,8 +2,43 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- **`Glyphs/IconResolution` no longer fails open on a missing icon directory.**
+  A directory that did not exist produced the same empty list as one that
+  existed with no SVGs, and both were read as "nothing to check" — so a library
+  that was never synced, or a `DefaultVariant` naming a variant the project does
+  not have, silently disabled the cop for every call site of that library. Green
+  cop, green CI, no validation at all, indefinitely. `load_icons` now returns
+  `nil` for an absent directory and `[]` for an empty one; the absent case warns
+  once per library/variant, naming the path. The synced-but-empty case still
+  passes silently. Refs #8
+
+- **Cop options are declared, so RuboCop stops calling them unsupported.**
+  `config/default.yml` documented `Libraries` (`Glyphs/IconResolution`) and
+  `Mappings` (`Glyphs/LegacyIconHelper`) only in comments, and never mentioned
+  `LibraryComponents` (`Glyphs/LegacyIconHelper`, `Glyphs/PreferLibraryComponent`)
+  at all. RuboCop derives its supported-parameter list from the keys actually
+  present in that file, so it warned `does not support <param> parameter` on
+  every run — for four working options, one of which
+  `Glyphs/LegacyIconHelper` itself tells you to add. Each is now declared with an
+  empty default (a no-op merge), so the options are validated instead of
+  reported, with behaviour unchanged. Refs #7
+
+- **Declaration harvest unwraps trailing `.freeze`.** `ICONS = { "x" => :car }.freeze`
+  (and `%i[a b].freeze`) used to yield a Prism `CallNode`, so hash/array values
+  were never collected. Cross-file dynamics (`PhosphorIcon(@icon)` in a shared
+  component + names only in a frozen `ICONS` map) then lost those icons at
+  `glyphs:prune_icons`. `collect_declaration` now unwraps zero-arg `.freeze`
+  (and parentheses) before walking the value.
+
 ### Added
 
+- **`Glyphs/IconResolution` gained a `Strict` option** (default `false`). It
+  escalates the missing-icon-directory warning above to an offence, so projects
+  that depend on this cop can fail closed in CI instead of trusting a warning
+  not to scroll past.
+
 - **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:
@@ -13,7 +48,8 @@
   - _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).
+    `ICON = :bell` constant rendered from a view). Frozen maps
+    (`ICONS = { … }.freeze`) are included — see Fixed above.
 
   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

data/README.md

@@ -133,9 +133,9 @@ The scanner resolves them from source, so you rarely need `keep_icons` at all:
   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.
+  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.
 
 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
@@ -210,6 +210,10 @@ Glyphs/LegacyIconHelper:
   # Mappings replaces the built-in defaults (_lucide/_phosphor/_hero/_heroicon/_tabler):
   # Mappings:
   #   _custom: CustomIcon
+  # LibraryComponents merges over the built-in library => component map, so
+  # `icon("x", library: "customlib")` corrects to `CustomIcon("x")`:
+  # LibraryComponents:
+  #   customlib: CustomIcon
 ```
 
 ### Glyphs/IconResolution
@@ -231,14 +235,38 @@ Glyphs/IconResolution:
   # Libraries merges over the built-in defaults (component => Dir/DefaultVariant):
   Libraries:
     PhosphorIcon: { Dir: phosphor, DefaultVariant: regular }
+  # Escalate a missing icon directory from a warning to an offence:
+  Strict: false
 ```
 
+If the directory a library resolves to does not exist — the library was never synced, or
+`DefaultVariant` names a variant you do not have — the cop cannot validate any of that
+library's call sites. Rather than pass silently, it warns once per library/variant:
+
+```
+[Glyphs/IconResolution] Icon directory `app/assets/svg/icons/phosphor/regular` not found,
+so `PhosphorIcon` names are not validated. Sync the library or fix `IconsPath`/`Libraries`.
+```
+
+Set `Strict: true` to make that an offence instead, so CI fails closed rather than reporting
+green while checking nothing. A directory that exists but ships no SVGs is not a
+misconfiguration and stays silent either way.
+
 ### Glyphs/PreferLibraryComponent
 
 ```ruby
 Icon(:house, library: :lucide) # => LucideIcon(:house)
 ```
 
+```yaml
+Glyphs/PreferLibraryComponent:
+  Include:
+    - app/**/*.rb
+  # LibraryComponents merges over the built-in library => component map:
+  # LibraryComponents:
+  #   customlib: CustomIcon
+```
+
 ## Migrating an app off icon helpers
 
 1. Add `gem "glyphs"`, `include Glyphs` where the helpers used to be included.

data/config/default.yml

@@ -3,10 +3,13 @@ Glyphs/LegacyIconHelper:
   Enabled: true
   VersionAdded: '0.1.0'
   SafeAutoCorrect: true
-  # Mappings replaces the built-in defaults when set:
-  # Mappings:
+  # Replaces the built-in helper => component defaults when set, e.g.
   #   _lucide: LucideIcon
   #   _heroicon: HeroIcon
+  Mappings: {}
+  # Merges over the built-in library => component map, e.g.
+  #   customlib: CustomIcon
+  LibraryComponents: {}
   DefaultLibraryComponent: HeroIcon
 
 Glyphs/IconResolution:
@@ -14,12 +17,18 @@ Glyphs/IconResolution:
   Enabled: true
   VersionAdded: '0.1.0'
   IconsPath: app/assets/svg/icons
-  # Libraries merges over the built-in defaults:
-  # Libraries:
+  # Merges over the built-in component => directory/variant defaults, e.g.
   #   PhosphorIcon: { Dir: phosphor, DefaultVariant: light }
+  Libraries: {}
+  # An icon directory that does not exist warns once per library/variant.
+  # Strict turns that warning into an offence so CI fails closed.
+  Strict: false
 
 Glyphs/PreferLibraryComponent:
   Description: 'Prefer library-specific components over generic Icon(..., library: ...).'
   Enabled: true
   VersionAdded: '0.1.0'
   SafeAutoCorrect: true
+  # Merges over the built-in library => component map, e.g.
+  #   customlib: CustomIcon
+  LibraryComponents: {}

data/lib/glyphs/source_scanner.rb

@@ -346,7 +346,11 @@ module Glyphs
 
       # 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 }`).
+      # Trailing `.freeze` is unwrapped so `ICONS = { … }.freeze` still harvests —
+      # without this, cross-file dynamics (`PhosphorIcon(@icon)` + names only in a
+      # frozen `ICONS` hash) lose those names at prune.
       def collect_declaration(value_node)
+        value_node = unwrap_declaration_wrappers(value_node)
         case value_node
         when Prism::SymbolNode, Prism::StringNode
           collect_literal(@declaration_literals, value_node)
@@ -356,6 +360,37 @@ module Glyphs
           value_node.elements.grep(Prism::AssocNode).each { |assoc| collect_declaration(assoc.value) }
         end
       end
+
+      # Peel zero-arg `.freeze` and parentheses so the underlying Hash/Array/literal
+      # is what declaration harvest walks.
+      def unwrap_declaration_wrappers(value_node)
+        loop do
+          case value_node
+          when Prism::CallNode
+            break unless freeze_call?(value_node)
+
+            value_node = value_node.receiver
+          when Prism::ParenthesesNode
+            value_node = value_node.body
+          when Prism::StatementsNode
+            # `(expr)` → StatementsNode with one child; multi-statement bodies are
+            # not valid constant values, so take the sole statement when present.
+            break unless value_node.body.size == 1
+
+            value_node = value_node.body.first
+          else
+            break
+          end
+        end
+        value_node
+      end
+
+      # `receiver.freeze` with no args — the common immutable-constant pattern.
+      def freeze_call?(node)
+        node.name == :freeze &&
+          node.receiver &&
+          (node.arguments.nil? || node.arguments.arguments.empty?)
+      end
     end
   end
 end

data/lib/glyphs/version.rb

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

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

@@ -11,6 +11,11 @@ module RuboCop
       # calls (`_lucide(:house)`) are validated. A literal `variant:` keyword is
       # honored; calls with dynamic names or variants are skipped.
       #
+      # A directory that does not exist is a configuration error, not "nothing
+      # to check": it warns once per library/variant, or — with `Strict` — adds
+      # an offence, so the cop can never quietly validate nothing. A directory
+      # that exists but ships no SVGs stays silent.
+      #
       # @example
       #   # bad
       #   LucideIcon(:non_existent_icon)
@@ -51,10 +56,14 @@ module RuboCop
 
         ICONIFY_PATTERN = /\biconify\s+(lucide|phosphor|heroicons)--([a-z0-9-]+)/
 
+        DEFAULT_ICONS_PATH = "app/assets/svg/icons"
+
         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}"
+        MISSING_DIR_MSG = "Icon directory `%{path}` not found, so `%{component}` names are not validated. " \
+                          "Sync the library or fix `IconsPath`/`Libraries`."
 
         def on_str(node)
           return if node.parent&.dstr_type?
@@ -97,7 +106,7 @@ module RuboCop
           @libraries ||= DEFAULT_LIBRARIES.merge(cop_config["Libraries"] || {})
         end
 
-        def check_call(node, _component, library)
+        def check_call(node, component, library)
           name = literal_name(node.first_argument)
           return unless name
 
@@ -105,6 +114,7 @@ module RuboCop
           return if variant == :dynamic
 
           available = available_icons(library["Dir"], variant)
+          return report_missing_directory(node, component, library["Dir"], variant) if available.nil?
           return if available.empty?
           return if available.include?(name)
 
@@ -124,6 +134,21 @@ module RuboCop
           end
         end
 
+        # The directory the cop was told to read is missing, so every call for
+        # this library goes unchecked. Report it rather than pass silently.
+        def report_missing_directory(node, component, library_dir, variant)
+          message = format(MISSING_DIR_MSG, path: configured_directory(library_dir, variant), component:)
+          return add_offense(node.first_argument, message:) if cop_config["Strict"]
+
+          self.class.warn_once("[Glyphs/IconResolution] #{message}")
+        end
+
+        # Built from the unexpanded `IconsPath` so the message shows the path as
+        # the project wrote it, not an absolute machine-specific one.
+        def configured_directory(library_dir, variant)
+          self.class.directory_for(cop_config["IconsPath"] || DEFAULT_ICONS_PATH, library_dir, variant)
+        end
+
         def variant_for(node, library)
           pair = variant_pair(node)
           return library["DefaultVariant"] if pair.nil?
@@ -258,7 +283,7 @@ module RuboCop
         end
 
         def icons_base_path
-          @icons_base_path ||= File.expand_path(cop_config["IconsPath"] || "app/assets/svg/icons", Dir.pwd)
+          @icons_base_path ||= File.expand_path(cop_config["IconsPath"] || DEFAULT_ICONS_PATH, Dir.pwd)
         end
 
         def available_icons(library_dir, variant)
@@ -266,16 +291,39 @@ module RuboCop
         end
 
         class << self
+          # nil when the directory is absent, [] when it exists but ships no
+          # SVGs — the caller has to tell those apart. Memoized with `key?` (not
+          # `||=`) so a nil result is not re-probed on every call site.
           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)
+            key = [base_path, library_dir, variant]
+            return @available_icons_cache[key] if @available_icons_cache.key?(key)
+
+            @available_icons_cache[key] = load_icons(directory_for(base_path, library_dir, variant))
+          end
+
+          def directory_for(base_path, library_dir, variant)
+            File.join(*[base_path, library_dir, variant].compact.reject { |part| part.to_s.empty? })
+          end
+
+          # RuboCop builds a fresh cop instance per file, so deduplicating the
+          # missing-directory warning has to outlive the instance.
+          def warn_once(message)
+            @warned_messages ||= {}
+            return if @warned_messages.key?(message)
+
+            @warned_messages[message] = true
+            warn message
+          end
+
+          def reset_warnings!
+            @warned_messages = nil
           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)
+          def load_icons(path)
+            return nil unless Dir.exist?(path)
 
             Dir.children(path).filter_map { |file| File.basename(file, ".svg") if file.end_with?(".svg") }.sort
           end

metadata

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