glyphs 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c8e883474d143ec14502ef27013e1a264c0a89d76b7dd24ef29d2025d96ad5c
-  data.tar.gz: afad4dcca3bda0162be398c66a7a7bb65c36af8facb9c4b5eb13f5d4d29a1d2c
+  metadata.gz: 5635cb76266896b0fb2d2e661844d27400be25b6e4a1190271279c7a4331517c
+  data.tar.gz: d8afd8c82d444afd15e951eba3aae5d1daaa0fce73efd7ac86fe725b9ce6dd09
 SHA512:
-  metadata.gz: a9c94ace100a67479cb24e793dfd7bc9c71238bfd472f2d29be37076410c27e0cc69d48b2952fad4574bac1e5184770d0b19542284c06edb520fece72d6c1526
-  data.tar.gz: 8d2cb2a5ca53b92884b28de6a2813326796b034754d5b6f14ab37b4fb7f54c1d49b6deb61dc53d75c0c668e8908447e9a5fdfd8bb71fbb5440c22a5bd9c15b61
+  metadata.gz: dffab87c9e9862dad15042135dc4c2ef7fb5785dd848210538b6e63c5263b8be6fc4a9b6c5276ac8ee7523fe239e08bb63007aff45af8ba52721fd52d774a946
+  data.tar.gz: 492c537c6ebb87013ec9795406b78cfb6b50e06328e2cc9b8b072a0c359e71d575a6d4853450c66b7d3c526492679ad156ef858a122cf848f4856ae957b14e55

data/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ### 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
@@ -13,6 +34,11 @@
 
 ### 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:

data/README.md

@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Glyphs
-  VERSION = "0.2.3"
+  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.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Mikael Henriksson