poetry-core 0.0.2

data/lib/poetry/core/css/resolver.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Poetry
+  module Core
+    module CSS
+      # poetry's in-tree server-side class-variants engine - no external
+      # runtime dependency.
+      #
+      # The resolver is a dictionary from a component's style surface to CSS
+      # utility classes:
+      #
+      #   base      "inline-flex items-center"           # the block root
+      #   element   :icon, "size-4 shrink-0"             # BEM elements (block__icon)
+      #   variant   :color, red: "text-red-600", ...     # BEM modifiers (block--color-red)
+      #   compound  ({ color: :red, mode: :dark }, "...") # multi-key combinations
+      #
+      # The resolver deliberately stores **no defaults**: default values
+      # live in exactly one place - the component's `style :attr, default:`
+      # declaration (ActiveModel fills them before render) - which
+      # structurally rules out the duplicated-defaults class of bug. Render
+      # criteria always arrive resolved.
+      #
+      # Merging goes through the shared, FIFO-cached Config merger
+      # (configured once - never a fresh TailwindMerge instance per render).
+      #
+      # @example
+      #   resolver = Poetry::Core::CSS::Resolver.new
+      #   resolver.base("inline-flex items-center")
+      #           .variant(:color, red: "text-red-600", blue: "text-blue-600")
+      #   resolver.render(color: :red) # => "inline-flex items-center text-red-600"
+      #
+      # @api private
+      class Resolver
+        Compound = Struct.new(:criteria, :classes)
+
+        attr_reader :bases, :elements, :variants, :compounds
+
+        def initialize
+          @bases = []
+          @elements = {}
+          @variants = {}
+          @compounds = []
+        end
+
+        # Subclass inheritance: a child Style extends a copy of its parent's
+        # dictionary (dup-on-inherit).
+        def dup
+          self.class.new.tap do |copy|
+            copy.instance_variable_set(:@bases, @bases.dup)
+            copy.instance_variable_set(:@elements, @elements.transform_values(&:dup))
+            copy.instance_variable_set(:@variants, @variants.transform_values(&:dup))
+            copy.instance_variable_set(:@compounds, @compounds.dup)
+          end
+        end
+
+        # -- The dictionary DSL ------------------------------------------------
+
+        def base(classes)
+          @bases << classes.to_s
+          self
+        end
+
+        def element(name, classes)
+          (@elements[name.to_sym] ||= []) << classes.to_s
+          self
+        end
+
+        def variant(attr, mapping)
+          bucket = (@variants[attr.to_sym] ||= {})
+          mapping.each { |value, classes| bucket[value] = classes.to_s }
+          self
+        end
+
+        def compound(criteria, classes)
+          raise ArgumentError, "compound criteria must name at least two variant keys" if criteria.size < 2
+
+          @compounds << Compound.new(criteria.transform_keys(&:to_sym), classes.to_s)
+          self
+        end
+
+        # -- Rendering ---------------------------------------------------------
+
+        # Resolves utility classes for the block root (element: nil) or a
+        # named element. `criteria` are the component's resolved style values;
+        # `extra` is a caller-supplied class string appended last (wins on
+        # Tailwind conflicts via the merger).
+        #
+        # @param element [Symbol, nil] a declared element name, or nil for the root
+        # @param extra [String, nil] caller classes appended after the dictionary's
+        # @param criteria [Hash{Symbol => Object}] resolved style values keyed by variant attr
+        # @return [String, nil] the merged class string, or nil when nothing resolves
+        def render(element = nil, extra: nil, **criteria)
+          classes = element ? @elements.fetch(element.to_sym, []).dup : root_classes(criteria)
+          classes << extra if extra
+          merger.merge(*classes)
+        end
+
+        # The introspection surface (previews, docs, the registry):
+        # { attr => [values] } for the declared variant space.
+        def variant_options
+          @variants.transform_values(&:keys)
+        end
+
+        # The capsule digest: a deterministic content hash of the whole
+        # dictionary. Embedded in the generated :bem reference stylesheet,
+        # so CSS written against an older dictionary is detectable instead
+        # of silently drifting.
+        #
+        # @return [String] a 12-character hex digest
+        def digest
+          Digest::SHA256.hexdigest(canonical_dictionary.inspect)[0, 12]
+        end
+
+        # Every utility class string in the dictionary (bases, elements,
+        # variants, compounds) - the Verifier's and the safelist's input.
+        def all_classes
+          [
+            @bases,
+            @elements.values.flatten,
+            @variants.values.flat_map(&:values),
+            @compounds.map(&:classes)
+          ].flatten.flat_map(&:split).uniq
+        end
+
+        private
+
+        # A stable, order-insensitive serialization of the dictionary for the
+        # capsule digest.
+        def canonical_dictionary
+          {
+            bases: @bases,
+            elements: @elements.sort_by { |name, _| name.to_s }.to_h { |name, v| [name, v] },
+            variants: @variants.sort_by { |attr, _| attr.to_s }
+                               .map { |attr, mapping| [attr, mapping.sort_by { |value, _| value.to_s }] },
+            compounds: @compounds.map { |rule| [rule.criteria.sort_by { |k, _| k.to_s }, rule.classes] }
+          }
+        end
+
+        def root_classes(criteria)
+          classes = @bases.dup
+          @variants.each do |attr, mapping|
+            next unless criteria.key?(attr)
+
+            hit = mapping[criteria[attr]]
+            classes << hit if hit
+          end
+          @compounds.each do |rule|
+            classes << rule.classes if rule.criteria.all? { |attr, value| criteria[attr] == value }
+          end
+          classes
+        end
+
+        def merger
+          Poetry::Core::Config.current.classname_merger
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/safelist.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # Generates the Tailwind safelist: every utility class poetry's Style
+      # dictionaries emit, one per line. This solves the consumer-purge
+      # problem: a host app's Tailwind build can't see classes resolved at
+      # render time in Ruby, so the generated safelist file is added to the
+      # host's `@source` paths and every dictionary class survives the build.
+      #
+      # Template-static classes (from .html.erb sidecars) are extracted via
+      # the Herb AST and included too - see {TemplateClasses}.
+      #
+      # @example
+      #   Poetry::Core::CSS::Safelist.new(style_classes: [MyApp::Button::Style]).text
+      #   # => "# poetry Tailwind safelist ...\nbg-primary\ninline-flex\n..."
+      #
+      # @api private
+      class Safelist
+        HEADER = "# poetry Tailwind safelist - generated by `bin/rake css:safelist`; add to @source. DO NOT EDIT."
+
+        # @param style_classes [Enumerable<Class>] Style subclasses to collect from
+        # @param template_classes [Enumerable<String>] extra (template-static) classes
+        def initialize(style_classes:, template_classes: [])
+          @style_classes = style_classes
+          @template_classes = template_classes
+        end
+
+        def classes
+          dictionary = @style_classes.flat_map { |style| style.resolver.all_classes }
+          (dictionary + @template_classes.to_a).uniq.sort
+        end
+
+        def text
+          "#{([HEADER] + classes).join("\n")}\n"
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/tailwind_merger.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The CSS tooling namespace: class-name merging and the compiled-build gates.
+    module CSS
+      # Intelligently merges Tailwind CSS class names by resolving conflicts and removing duplicates.
+      #
+      # This class provides a convenient wrapper around TailwindMerge::Merger to handle the common
+      # pattern of merging multiple Tailwind CSS class lists while automatically resolving style
+      # conflicts. When multiple classes target the same CSS property, the last one wins.
+      #
+      # @example Basic usage
+      #   merger = Poetry::Core::CSS::Merger.new
+      #   merger.merge('text-red-500', 'text-blue-500')
+      #   # => 'text-blue-500' (conflict resolved - last one wins)
+      #
+      # @example Merging arrays of classes
+      #   merger.merge(['bg-white', 'p-4'], ['bg-gray-100', 'rounded'])
+      #   # => 'p-4 bg-gray-100 rounded' (bg-white replaced by bg-gray-100)
+      #
+      # @example Handling nil and blank values
+      #   merger.merge('p-4', nil, '', 'rounded')
+      #   # => 'p-4 rounded' (nil and blank values are filtered out)
+      #
+      # @example Working with symbols
+      #   merger.merge(:rounded, :'text-center')
+      #   # => 'rounded text-center' (symbols converted to strings)
+      #
+      # @see Poetry::Core::CSS::BemMerger (the css_mode = :bem counterpart)
+      # @api private
+      class TailwindMerger
+        # Bounded FIFO cache over merge results: components render the same
+        # class combinations over and over, so tailwind_merge runs once per
+        # DISTINCT combo instead of once per render.
+        CACHE_LIMIT = 512
+
+        # Initializes a new CSS merger instance.
+        #
+        # Creates an underlying TailwindMerge::Merger instance that handles the
+        # core logic of identifying and resolving Tailwind CSS class conflicts.
+        def initialize
+          @base_merger = TailwindMerge::Merger.new
+          @cache = {}
+          @mutex = Mutex.new
+        end
+
+        # Merges multiple Tailwind CSS class names, resolving any styling conflicts.
+        #
+        # This method intelligently combines CSS classes by:
+        # 1. Flattening nested arrays into a single list
+        # 2. Removing nil and blank values
+        # 3. Converting all values to strings (handles symbols, etc.)
+        # 4. Resolving Tailwind class conflicts (last value wins)
+        # 5. Removing exact duplicates
+        #
+        # When multiple classes affect the same CSS property (e.g., text-red-500 and
+        # text-blue-500), only the last one in the sequence is kept. Non-conflicting
+        # classes are preserved.
+        #
+        # @param classes [Array<String, Symbol, Array, nil>] One or more class names,
+        #   arrays of class names, or nil values to merge
+        # @return [String, nil] A space-separated string of merged class names, or nil
+        #   if the input is empty after normalization
+        #
+        # @example Simple merge
+        #   merge('p-4', 'rounded')
+        #   # => 'p-4 rounded'
+        #
+        # @example Conflict resolution
+        #   merge('text-sm', 'text-lg')
+        #   # => 'text-lg'
+        #
+        # @example Array handling
+        #   merge(['p-4', 'rounded'], ['bg-white', 'shadow'])
+        #   # => 'p-4 rounded bg-white shadow'
+        #
+        # @example Blank value filtering
+        #   merge('p-4', nil, '', 'rounded')
+        #   # => 'p-4 rounded'
+        #
+        # @example Returns nil for empty input
+        #   merge(nil, '', [])
+        #   # => nil
+        def merge(*classes)
+          normalized = classes.flatten.compact_blank.map(&:to_s)
+          return nil if normalized.empty?
+
+          key = normalized.join(" ")
+          @mutex.synchronize do
+            if @cache.key?(key)
+              @cache[key]
+            else
+              @cache.shift if @cache.size >= CACHE_LIMIT # Hash keeps insertion order: shift = FIFO eviction
+              @cache[key] = @base_merger.merge(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/template_classes.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # Herb-AST extraction of the STATIC class attributes in ERB templates:
+      # only the literal chunks of a class attribute are collected;
+      # ERB-dynamic chunks are skipped entirely, so dynamic class logic can
+      # never false-flag. Feeds the Tailwind safelist (template classes
+      # survive the host's purge) and doubles as the herb parse gate -
+      # parse errors are surfaced, not swallowed.
+      #
+      # Herb is loaded lazily: it is a build/CI-time tool, not a runtime
+      # dependency of the gem.
+      #
+      # @example
+      #   result = Poetry::Core::CSS::TemplateClasses.extract('<div class="p-4 <%= extra %>">')
+      #   result.classes # => ["p-4"]
+      #
+      # @api private
+      class TemplateClasses
+        ParseError = Struct.new(:path, :message) do
+          def to_s
+            "#{path}: #{message}"
+          end
+        end
+
+        Result = Struct.new(:classes, :errors)
+
+        class << self
+          # Whether the herb gem is loadable (extraction is optional at
+          # install time in a host app; required in poetry's own CI).
+          def available?
+            herb!
+            true
+          rescue Poetry::Core::Error
+            false
+          end
+
+          # Extracts static classes from one ERB source string.
+          #
+          # @return [Result] classes (Array<String>) + errors (Array<String>)
+          def extract(source)
+            herb!
+            parsed = Herb.parse(source)
+            classes = []
+            walk(parsed.value) do |node|
+              next unless node.is_a?(Herb::AST::HTMLAttributeNode) && class_attribute?(node)
+
+              classes.concat(static_classes(node))
+            end
+            Result.new(classes.uniq, parsed.errors.map(&:message))
+          end
+
+          # Scans every template under root matching the glob.
+          #
+          # @return [Result] unique sorted classes + per-file ParseErrors
+          def scan(root:, glob: "app/components/**/*.html.erb")
+            classes = []
+            errors = []
+            Dir.glob(glob, base: root.to_s).sort.each do |relative|
+              result = extract(File.read(File.join(root, relative)))
+              classes.concat(result.classes)
+              errors.concat(result.errors.map { |message| ParseError.new(relative, message) })
+            end
+            Result.new(classes.uniq.sort, errors)
+          end
+
+          private
+
+          def herb!
+            require "herb"
+          rescue LoadError
+            raise Poetry::Core::Error,
+                  "the herb gem is required for template class extraction - add `gem \"herb\"` to your Gemfile"
+          end
+
+          def walk(node, &block)
+            yield node
+            node.child_nodes.compact.each { |child| walk(child, &block) } if node.respond_to?(:child_nodes)
+          end
+
+          def class_attribute?(attribute)
+            name = attribute.name.child_nodes.compact.first
+            name.respond_to?(:content) && name.content == "class"
+          end
+
+          # Only the LiteralNode chunks of the attribute value - ERB chunks
+          # are dynamic and deliberately ignored.
+          def static_classes(attribute)
+            value = attribute.value
+            return [] unless value
+
+            value.child_nodes.compact.filter_map do |chunk|
+              chunk.content if chunk.is_a?(Herb::AST::LiteralNode)
+            end.flat_map(&:split)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/theme_coverage.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # The theme-layer coverage gate: bidirectional agreement between
+      # the cn-* names Style dictionaries emit and the rules a theme
+      # fragment defines.
+      #
+      #   missing - dictionary cn names with no theme rule (the component
+      #             would render undesigned; css:verify_compiled reddens
+      #             too - this names the culprit precisely)
+      #   orphans - theme cn tokens no dictionary emits (a dead rule, or a
+      #             rename the theme didn't follow). Consumer-facing utility
+      #             classes a theme defines on purpose (cn-font-heading)
+      #             ride the allowlist.
+      #
+      # The parser is deliberately narrow: cn tokens are read from top-level
+      # selectors only (lines that open a rule), never from @apply bodies -
+      # theme fragments are flat by convention (see themes/default.css).
+      #
+      # @example
+      #   coverage = Poetry::Core::CSS::ThemeCoverage.new(
+      #     theme_css: File.read("themes/default.css"),
+      #     style_classes: [MyApp::Button::Style]
+      #   )
+      #   coverage.ok? || [coverage.missing, coverage.orphans]
+      #
+      # @api private
+      class ThemeCoverage
+        SELECTOR_LINE = /^[^@\s{}][^{]*\{/
+        CN_TOKEN = /\.(cn-[a-z0-9-]+)/
+
+        def initialize(theme_css:, style_classes:, allowlist: [])
+          @theme_css = theme_css
+          @style_classes = style_classes
+          @allowlist = allowlist.map(&:to_s)
+        end
+
+        # Every cn-* class any dictionary emits (bases, elements, variants,
+        # compounds), deduplicated across dictionaries.
+        def dictionary_names
+          @dictionary_names ||= @style_classes
+                                .flat_map { |style| style.resolver.all_classes }
+                                .select { |cls| cls.start_with?("cn-") }
+                                .uniq.sort
+        end
+
+        # Every cn-* token appearing in a theme selector (a combined
+        # compound selector like `.cn-x-a.cn-x-b` contributes both).
+        def theme_names
+          @theme_names ||= @theme_css.each_line
+                                     .grep(SELECTOR_LINE)
+                                     .flat_map { |line| line[0...line.index("{")].scan(CN_TOKEN) }
+                                     .flatten.uniq.sort
+        end
+
+        def missing
+          dictionary_names - theme_names
+        end
+
+        def orphans
+          theme_names - dictionary_names - @allowlist
+        end
+
+        def ok?
+          missing.empty? && orphans.empty?
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/var_coverage.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module CSS
+      # The custom-property contract: every `var(--x)` READ in a
+      # compiled build must resolve to a DEFINITION - a declaration or a
+      # CSS `@property` registration in the compiled CSS, or a runtime assignment
+      # (JS setProperty, inline style attributes) that the caller passes in,
+      # since runtime assignments never appear in the build output.
+      #
+      # Derivation over maintenance: the definition set is read from the
+      # artifacts that already exist (the compiled build + the actual JS and
+      # template sources), never a hand-maintained list - so a token rename
+      # or deletion reddens every stale read the moment it lands. A read
+      # WITH a fallback still counts: `var(--x, 4px)` where --x is defined
+      # nowhere is a dead read whose intent lives only in the fallback -
+      # drift by construction, not a feature.
+      #
+      # Dynamic runtime names (`--drawer-swipe-movement-${axis}`) enter as
+      # PREFIXES: a read resolves if it starts with a registered prefix.
+      #
+      # @example
+      #   coverage = Poetry::Core::CSS::VarCoverage.new(
+      #     compiled_css: File.read("app/assets/builds/tailwind.css"),
+      #     extra_definitions: ["--anchor-width"] # assigned from JS at runtime
+      #   )
+      #   coverage.ok? || coverage.dead_reads # => ["--never-defined"]
+      #
+      # @api private
+      class VarCoverage
+        # `--x:` declarations; the lookbehind keeps Stimulus event tokens
+        # (`poetry--core--calendar:change`) and BEM-ish substrings out.
+        DECLARATION = /(?<![\w-])(--[A-Za-z][\w-]*)\s*:/
+        PROPERTY_RULE = /@property\s+(--[A-Za-z][\w-]*)/
+        READ = /var\(\s*(--[A-Za-z][\w-]*)/
+
+        def initialize(compiled_css:, extra_definitions: [], definition_prefixes: [], extra_reads: [])
+          @compiled_css = strip_comments(compiled_css)
+          @extra_definitions = extra_definitions.map(&:to_s)
+          @definition_prefixes = definition_prefixes.map(&:to_s)
+          @extra_reads = extra_reads.map(&:to_s)
+        end
+
+        def definitions
+          @definitions ||= (@compiled_css.scan(DECLARATION).flatten +
+                            @compiled_css.scan(PROPERTY_RULE).flatten +
+                            @extra_definitions).to_set
+        end
+
+        def reads
+          @reads ||= (@compiled_css.scan(READ).flatten + @extra_reads).uniq.sort
+        end
+
+        # Reads that resolve to nothing: not declared in the build, not
+        # registered via CSS `@property`, not runtime-assigned. Each one is a rule
+        # silently falling back (or to nothing at all) - a class of bug
+        # once dug out by hand as a dozen dead reads of renamed vars.
+        def dead_reads
+          reads.reject do |name|
+            definitions.include?(name) || @definition_prefixes.any? { |prefix| name.start_with?(prefix) }
+          end
+        end
+
+        def ok? = dead_reads.empty?
+
+        private
+
+        def strip_comments(css)
+          css.gsub(%r{/\*.*?\*/}m, "")
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/css/verifier.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "did_you_mean/levenshtein"
+
+module Poetry
+  module Core
+    module CSS
+      # The class Verifier: validates that every class a Style dictionary
+      # emits actually exists in the COMPILED Tailwind stylesheet -
+      # catching typos and LLM-hallucinated classes before they ship as
+      # silently-unstyled markup.
+      #
+      # A pure function over (classes, compiled CSS): no Tailwind toolchain
+      # required at verify time, just the build output. Built as a reusable
+      # library on purpose - CI, the agent checks, the editor LSP, and the
+      # host-app `poetry:verify` task all consume this one implementation.
+      #
+      # @example
+      #   verifier = Poetry::Core::CSS::Verifier.new(compiled_css: File.read("builds/tailwind.css"))
+      #   verifier.unknown(["inline-flex", "text-red-510"]).map(&:to_s)
+      #   # => ["text-red-510 (did you mean \"text-red-500\"?)"]
+      #
+      # @api private
+      class Verifier
+        Unknown = Struct.new(:class_name, :suggestion) do
+          def to_s
+            suggestion ? "#{class_name} (did you mean #{suggestion.inspect}?)" : class_name
+          end
+        end
+
+        # Maximum Levenshtein distance for a did-you-mean suggestion.
+        SUGGESTION_DISTANCE = 2
+
+        # Named group/peer MARKER classes (`group/menu-item`, `peer/menu-button`).
+        # Tailwind emits no CSS for the bare marker by design - it only ever
+        # appears inside the selectors of utilities that CONSUME it
+        # (`group-focus/menu-item:*`), so its presence in compiled CSS depends
+        # on which theme is active. A marker is valid markup regardless - a
+        # theme fragment may be the only place its consumers live - so
+        # verification skips them instead of rewarding the coincidence of a
+        # same-theme consumer.
+        MARKER_CLASS = %r{\A(?:group|peer)/[a-z0-9-]+\z}
+
+        # Extracts the set of class names defined by a compiled CSS text.
+        # Selectors are the text runs preceding `{` (which also covers rules
+        # nested in @media etc.); Tailwind's escaping (`\:` `\/` `\[` ...) is
+        # unescaped so names compare in their authored form. Tokens starting
+        # with a digit are rejected (artifacts of dimensions like `.5rem` in
+        # at-rule params - real leading-digit classes are escaped by Tailwind
+        # and survive unescaping).
+        def self.known_classes(compiled_css)
+          selectors = compiled_css.gsub(%r{/\*.*?\*/}m, "").scan(/[^{}]+(?=\{)/)
+          selectors.each_with_object(Set.new) do |selector, known|
+            selector.scan(/\.((?:\\.|[-\w])+)/) do |(token)|
+              name = token.gsub(/\\(.)/, '\1')
+              known << name unless name.match?(/\A\d/)
+            end
+          end
+        end
+
+        attr_reader :known
+
+        def initialize(compiled_css:)
+          @known = self.class.known_classes(compiled_css)
+        end
+
+        # The classes (of those given) that do NOT exist in the compiled CSS,
+        # each with a nearest-known-class suggestion when one is close enough.
+        #
+        # @param classes [Enumerable<String>]
+        # @return [Array<Unknown>]
+        def unknown(classes)
+          classes.uniq.reject { |name| @known.include?(name) || name.match?(MARKER_CLASS) }.map do |name|
+            Unknown.new(name, suggestion_for(name))
+          end
+        end
+
+        # Verifies every class in a Style dictionary (bases, elements,
+        # variants, compounds).
+        #
+        # @param style_class [Class] a Poetry::Core::Style subclass
+        # @return [Array<Unknown>]
+        def verify_style(style_class)
+          unknown(style_class.resolver.all_classes)
+        end
+
+        private
+
+        def suggestion_for(name)
+          best = nil
+          best_distance = SUGGESTION_DISTANCE + 1
+          @known.each do |candidate|
+            next if (candidate.length - name.length).abs > SUGGESTION_DISTANCE
+
+            distance = DidYouMean::Levenshtein.distance(name, candidate)
+            if distance < best_distance
+              best = candidate
+              best_distance = distance
+            end
+          end
+          best
+        end
+      end
+    end
+  end
+end