shopify_product_taxonomy 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5cec4d780841db87dfa606e3b36510bbcb2398f03a6cf091f1a1867e0b88b8b0
+  data.tar.gz: 3142307e81c2049fedf3fcf38d7ba87bb2594b4a88185aadfb1cb7dceac6c2b3
+SHA512:
+  metadata.gz: fb4fbe719cd799f493b7da19f6be9e2c12f776a136a3062a776645fb680cc96fbf4eef2add7eb6ea939c6a76b1c30af90888ce00f23e5633d71cfd571720ae35
+  data.tar.gz: 1a272445bdd6bb760cae6e4ac2538a58de1f8588a857ab291a32ab450661fde810e1c26223eeb1b28bf105dd2a2f182655fba1372d6e79ba6d0f41e6dc2374b3

data/lib/product_taxonomy/alphanumeric_sorter.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module AlphanumericSorter
+    class << self
+      def sort(values, other_last: false)
+        values.sort_by.with_index do |value, idx|
+          [
+            other_last && value.to_s.downcase == "other" ? 1 : 0,
+            *normalize_value(value),
+            idx,
+          ]
+        end
+      end
+
+      def normalize_value(value)
+        @normalized_values ||= {}
+        @normalized_values[value] ||= if (numerical = value.match(RegexPattern::NUMERIC_PATTERN))
+          [0, *normalize_numerical(numerical)]
+        elsif (sequential = value.match(RegexPattern::SEQUENTIAL_TEXT_PATTERN))
+          [1, *normalize_sequential(sequential)]
+        else
+          [1, normalize_text(value)]
+        end
+      end
+
+      private
+
+      def normalize_numerical(match)
+        [
+          normalize_text(match[:primary_unit] || match[:secondary_unit]) || "",
+          normalize_text(match[:seperator]) || "-",
+          normalize_single_number(match[:primary_number]),
+          normalize_single_number(match[:secondary_number]),
+        ]
+      end
+
+      def normalize_sequential(match)
+        [
+          normalize_text(match[:primary_text]),
+          normalize_single_number(match[:primary_step]),
+          normalize_text(match[:primary_unit] || match[:secondary_unit]) || "",
+          normalize_text(match[:seperator]) || "-",
+          normalize_text(match[:secondary_text]),
+          normalize_single_number(match[:secondary_step]),
+          normalize_text(match[:trailing_text]),
+        ]
+      end
+
+      def normalize_single_number(value)
+        value = value.split.sum(&:to_r) if value&.include?("/")
+        value.to_f
+      end
+
+      def normalize_text(value)
+        return if value.nil?
+
+        ActiveSupport::Inflector.transliterate(value.strip.downcase)
+      end
+    end
+
+    module RegexPattern
+      # matches numbers like -1, 5, 10.5, 3/4, 2 5/8
+      SINGLE_NUMBER = %r{
+        -?                          # Optional negative sign
+        (?:
+          \d+\.?\d*                 # Easy numbers like 5, 10.5
+          |
+          (?:\d+\s)?\d+/[1-9]+\d*   # Fractions like 3/4, 2 5/8
+        )
+      }x
+
+      # matches units like sq.ft, km/h
+      UNITS_OF_MEASURE = %r{
+        [^\d\./\-]  # Matches any character not a digit, dot, slash or dash
+        [^\-\d]*    # Matches any character not a dash or digit
+      }x
+
+      # String capturing is simple
+      BASIC_TEXT = /\D+/
+      SEPERATOR  = /[\p{Pd}x~]/
+
+      # NUMERIC_PATTERN matches a primary number with optional units, and an optional range or dimension
+      # with a secondary number and its optional units.
+      NUMERIC_PATTERN = %r{
+        ^\s*(?<primary_number>#{SINGLE_NUMBER})   # 1. Primary number
+        \s*(?<primary_unit>#{UNITS_OF_MEASURE})?  # 2. Optional units for primary number
+        (?:                                       # Optional range or dimension
+          \s*(?<seperator>#{SEPERATOR})               # 3. Separator
+          \s*(?<secondary_number>#{SINGLE_NUMBER})    # 4. Secondary number
+          \s*(?<secondary_unit>#{UNITS_OF_MEASURE})?  # 5. Optional units for secondary number
+        )?
+        \s*$
+      }x
+
+      # SEQUENTIAL_TEXT_PATTERN matches a primary non-number string, an optional step, and optional units,
+      # followed by an optional range or dimension with a secondary non-number string, an optional step,
+      # and optional units, and finally an optional trailing text.
+      SEQUENTIAL_TEXT_PATTERN = %r{
+        ^\s*(?<primary_text>#{BASIC_TEXT})            # 1. Primary non-number string
+        \s*(?<primary_step>#{SINGLE_NUMBER})?         # 2. Optional step
+        \s*(?<primary_unit>#{UNITS_OF_MEASURE})?      # 3. Optional units for primary number
+        (?:                                           # Optional range or dimension
+          \s*(?<seperator>#{SEPERATOR})                 # 4. Separator -- capturing allows us to group ranges and dimensions
+          \s*(?<secondary_text>#{BASIC_TEXT})?          # 5. Optional secondary non-number string
+          \s*(?<secondary_step>#{SINGLE_NUMBER})        # 6. Secondary step
+          \s*(?<secondary_unit>#{UNITS_OF_MEASURE})?    # 7. Optional units for secondary number
+        )?
+        \s*(?<trailing_text>.*)?$                     # 8. Optional trailing text
+      }x
+    end
+  end
+end

data/lib/product_taxonomy/identifier_formatter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module IdentifierFormatter
+    class << self
+      def format_friendly_id(text)
+        I18n.transliterate(text)
+          .downcase
+          .gsub(%r{[^a-z0-9\s\-_/\.\+#]}, "")
+          .gsub(/[\s\-\.]+/, "_")
+      end
+
+      def format_handle(text)
+        I18n.transliterate(text)
+          .downcase
+          .gsub(%r{[^a-z0-9\s\-_/\+#]}, "")
+          .gsub("+", "-plus-")
+          .gsub("#", "-hashtag-")
+          .gsub("/", "-")
+          .gsub(/[\s\.]+/, "-")
+          .gsub("_-_", "-")
+          .gsub(/(?<!_)_(?!_)/, "-")
+          .gsub(/--+/, "-")
+          .gsub(/\A-+|-+\z/, "")
+      end
+    end
+  end
+end

data/lib/product_taxonomy/loader.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ProductTaxonomy
+  class Loader
+    class << self
+      def load(values_path:, attributes_path:, categories_glob:)
+        return if ProductTaxonomy::Category.all.any?
+
+        begin
+          ProductTaxonomy::Value.load_from_source(YAML.load_file(values_path))
+          ProductTaxonomy::Attribute.load_from_source(YAML.load_file(attributes_path))
+
+          categories_source_data = categories_glob.each_with_object([]) do |file, array|
+            array.concat(YAML.safe_load_file(file))
+          end
+          ProductTaxonomy::Category.load_from_source(categories_source_data)
+        rescue Errno::ENOENT => e
+          raise ArgumentError, "File not found: #{e.message}"
+        rescue Psych::SyntaxError => e
+          raise ArgumentError, "Invalid YAML: #{e.message}"
+        end
+
+        # Run validations that can only be run after the taxonomy has been loaded.
+        ProductTaxonomy::Value.all.each { |model| model.validate!(:taxonomy_loaded) }
+      end
+    end
+  end
+end
+

data/lib/product_taxonomy/localizations_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module LocalizationsValidator
+    class << self
+      # Validate that all localizations are present for the given locales. If no locales are provided, all locales
+      # will be validated and the consistency of locales across models will be checked.
+      #
+      # @param locales [Array<String>, nil] The locales to validate. If nil, all locales will be validated.
+      def validate!(locales = nil)
+        Category.validate_localizations!(locales)
+        Attribute.validate_localizations!(locales)
+        Value.validate_localizations!(locales)
+
+        validate_locales_are_consistent! if locales.nil?
+      end
+
+      private
+
+      def validate_locales_are_consistent!
+        categories_locales = Category.localizations.keys
+        attributes_locales = Attribute.localizations.keys
+        values_locales = Value.localizations.keys
+
+        error_message = "Not all model localizations have the same set of locales"
+        raise ArgumentError,
+          error_message unless categories_locales == attributes_locales && attributes_locales == values_locales
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/attribute.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  class Attribute
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    class << self
+      # Load attributes from source data. By default, this data is deserialized from a YAML file in the `data` directory.
+      #
+      # @param source_data [Array<Hash>] The source data to load attributes from.
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be a hash" unless source_data.is_a?(Hash)
+        raise ArgumentError, "source_data must contain keys \"base_attributes\" and \"extended_attributes\"" unless
+          source_data.keys.sort == ["base_attributes", "extended_attributes"]
+
+        source_data.each do |type, attributes|
+          attributes.each do |attribute_data|
+            raise ArgumentError, "source_data must contain hashes" unless attribute_data.is_a?(Hash)
+
+            attribute = case type
+            when "base_attributes" then attribute_from(attribute_data)
+            when "extended_attributes" then extended_attribute_from(attribute_data)
+            end
+            Attribute.add(attribute)
+            attribute.validate!(:create)
+          end
+        end
+      end
+
+      # Reset all class-level state
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+      end
+
+      # Get base attributes only, sorted by name.
+      #
+      # @return [Array<Attribute>] The sorted base attributes.
+      def sorted_base_attributes
+        all.reject(&:extended?).sort_by(&:name)
+      end
+
+      # Get the next ID for a newly created attribute.
+      #
+      # @return [Integer] The next ID.
+      def next_id = (all.max_by(&:id)&.id || 0) + 1
+
+      private
+
+      def attribute_from(attribute_data)
+        values_by_friendly_id = attribute_data["values"]&.map { Value.find_by(friendly_id: _1) || _1 }
+        Attribute.new(
+          id: attribute_data["id"],
+          name: attribute_data["name"],
+          description: attribute_data["description"],
+          friendly_id: attribute_data["friendly_id"],
+          handle: attribute_data["handle"],
+          values: values_by_friendly_id,
+          is_manually_sorted: attribute_data["sorting"] == "custom",
+        )
+      end
+
+      def extended_attribute_from(attribute_data)
+        value_friendly_id = attribute_data["values_from"]
+        ExtendedAttribute.new(
+          name: attribute_data["name"],
+          handle: attribute_data["handle"],
+          description: attribute_data["description"],
+          friendly_id: attribute_data["friendly_id"],
+          values_from: Attribute.find_by(friendly_id: value_friendly_id) || value_friendly_id,
+        )
+      end
+    end
+
+    validates :id, presence: true, numericality: { only_integer: true }, if: -> { self.class == Attribute }, on: :create
+    validates :name, presence: true, on: :create
+    validates :friendly_id, presence: true, on: :create
+    validates :handle, presence: true, on: :create
+    validates :description, presence: true, on: :create
+    validates :values, presence: true, if: -> { self.class == Attribute }, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:friendly_id], on: :create
+    validate :values_valid?, on: :create
+
+    localized_attr_reader :name, :description
+
+    attr_reader :id, :friendly_id, :handle, :values, :extended_attributes
+
+    # @param id [Integer] The ID of the attribute.
+    # @param name [String] The name of the attribute.
+    # @param description [String] The description of the attribute.
+    # @param friendly_id [String] The friendly ID of the attribute.
+    # @param handle [String] The handle of the attribute.
+    # @param values [Array<Value, String>] An array of resolved {Value} objects. When resolving fails, use the friendly
+    # ID instead.
+    def initialize(id:, name:, description:, friendly_id:, handle:, values:, is_manually_sorted: false)
+      @id = id
+      @name = name
+      @description = description
+      @friendly_id = friendly_id
+      @handle = handle
+      @values = values
+      @extended_attributes = []
+      @is_manually_sorted = is_manually_sorted
+    end
+
+    # Add an extended attribute to the attribute.
+    #
+    # @param extended_attribute [ExtendedAttribute] The extended attribute to add.
+    def add_extended_attribute(extended_attribute)
+      @extended_attributes << extended_attribute
+    end
+
+    # Add a value to the attribute.
+    #
+    # @param value [Value] The value to add.
+    def add_value(value)
+      @values << value
+    end
+
+    # The global ID of the attribute
+    #
+    # @return [String]
+    def gid
+      "gid://shopify/TaxonomyAttribute/#{id}"
+    end
+
+    # Whether the attribute is an extended attribute.
+    #
+    # @return [Boolean]
+    def extended?
+      is_a?(ExtendedAttribute)
+    end
+
+    # Whether the attribute is manually sorted.
+    #
+    # @return [Boolean]
+    def manually_sorted?
+      @is_manually_sorted
+    end
+
+    # Get the sorted values of the attribute.
+    #
+    # @param locale [String] The locale to sort by.
+    # @return [Array<Value>] The sorted values.
+    def sorted_values(locale: "en")
+      if manually_sorted?
+        values
+      else
+        Value.sort_by_localized_name(values, locale:)
+      end
+    end
+
+    private
+
+    def values_valid?
+      values&.each do |value|
+        next if value.is_a?(Value)
+
+        errors.add(
+          :values,
+          :not_found,
+          message: "not found for friendly ID \"#{value}\"",
+        )
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/category.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  class Category
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    class << self
+      attr_reader :verticals
+
+      # Load categories from source data.
+      #
+      # @param source_data [Array<Hash>] The source data to load categories from.
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be an array" unless source_data.is_a?(Array)
+
+        # First pass: Create all nodes and add to index
+        source_data.each do |item|
+          Category.create_validate_and_add!(
+            id: item["id"],
+            name: item["name"],
+            attributes: Array(item["attributes"]).map { Attribute.find_by(friendly_id: _1) || _1 },
+          )
+        end
+
+        # Second pass: Build relationships
+        source_data.each do |item|
+          parent = Category.find_by(id: item["id"])
+          add_children(type: "children", item:, parent:)
+          add_children(type: "secondary_children", item:, parent:)
+        end
+
+        # Third pass: Validate all nodes, sort contents, and collect root nodes for verticals
+        @verticals = Category.all.each_with_object([]) do |node, root_nodes|
+          node.validate!(:category_tree_loaded)
+          node.children.sort_by!(&:name)
+          node.attributes.sort_by!(&:name)
+          root_nodes << node if node.root?
+        end
+        @verticals.sort_by!(&:name)
+      end
+
+      # Reset all class-level state
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+        @verticals = nil
+      end
+
+      # Get all categories in depth-first order.
+      #
+      # @return [Array<Category>] The categories in depth-first order.
+      def all_depth_first
+        verticals.flat_map(&:descendants_and_self)
+      end
+
+      private
+
+      def add_children(type:, item:, parent:)
+        item[type]&.each do |child_id|
+          child = Category.find_by(id: child_id) || child_id
+
+          case type
+          when "children" then parent.add_child(child)
+          when "secondary_children" then parent.add_secondary_child(child)
+          end
+        end
+      end
+    end
+
+    # Validations that can be performed as soon as the category is created.
+    validates :id, format: { with: /\A[a-z]{2}(-\d+)*\z/ }, on: :create
+    validates :name, presence: true, on: :create
+    validate :attributes_found?, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:id], on: :create
+
+    # Validations that can only be performed after the category tree has been loaded.
+    validate :id_matches_depth, on: :category_tree_loaded
+    validate :id_starts_with_parent_id, unless: :root?, on: :category_tree_loaded
+    validate :children_found?, on: :category_tree_loaded
+    validate :secondary_children_found?, on: :category_tree_loaded
+
+    localized_attr_reader :name, keyed_by: :id
+
+    attr_reader :id, :children, :secondary_children, :attributes
+    attr_accessor :parent, :secondary_parents
+
+    # @param id [String] The ID of the category.
+    # @param name [String] The name of the category.
+    # @param attributes [Array<Attribute>] The attributes of the category.
+    # @param parent [Category] The parent category of the category.
+    def initialize(id:, name:, attributes: [], parent: nil)
+      @id = id
+      @name = name
+      @children = []
+      @secondary_children = []
+      @attributes = attributes
+      @parent = parent
+      @secondary_parents = []
+    end
+
+    #
+    # Manipulation
+    #
+
+    # Add a child to the category
+    #
+    # @param [Category|String] child node, or the friendly ID if the node was not found.
+    def add_child(child)
+      @children << child
+
+      return unless child.is_a?(Category)
+
+      child.parent = self
+    end
+
+    # Add a secondary child to the category
+    #
+    # @param [Category|String] child node, or the friendly ID if the node was not found.
+    def add_secondary_child(child)
+      @secondary_children << child
+
+      return unless child.is_a?(Category)
+
+      child.secondary_parents << self
+    end
+
+    # Add an attribute to the category
+    #
+    # @param [Attribute] attribute
+    def add_attribute(attribute)
+      @attributes << attribute
+    end
+
+    #
+    # Information
+    #
+    def inspect
+      "#<#{self.class.name} id=#{id} name=#{name}>"
+    end
+
+    # Whether the category is the root category
+    #
+    # @return [Boolean]
+    def root?
+      parent.nil?
+    end
+
+    # Whether the category is a leaf category
+    #
+    # @return [Boolean]
+    def leaf?
+      children.empty?
+    end
+
+    # The level of the category
+    #
+    # @return [Integer]
+    def level
+      ancestors.size
+    end
+
+    # The root category in this category's tree
+    #
+    # @return [Category]
+    def root
+      ancestors.last || self
+    end
+
+    # The ancestors of the category
+    #
+    # @return [Array<Category>]
+    def ancestors
+      return [] if root?
+
+      [parent] + parent.ancestors
+    end
+
+    # The full name of the category
+    #
+    # @return [String]
+    def full_name(locale: "en")
+      return name(locale:) if root?
+
+      parent.full_name(locale:) + " > " + name(locale:)
+    end
+
+    # The global ID of the category
+    #
+    # @return [String]
+    def gid
+      "gid://shopify/TaxonomyCategory/#{id}"
+    end
+
+    # Split an ID into its parts.
+    #
+    # @return [Array<String, Integer>] The parts of the ID.
+    def id_parts
+      parts = id.split("-")
+      [parts.first] + parts[1..].map(&:to_i)
+    end
+
+    # Whether the category is a descendant of another category
+    #
+    # @param [Category] category
+    # @return [Boolean]
+    def descendant_of?(category)
+      ancestors.include?(category)
+    end
+
+    # Iterate over the category and all its descendants
+    #
+    # @yield [Category]
+    def traverse(&block)
+      yield self
+      children.each { _1.traverse(&block) }
+    end
+
+    # The descendants of the category
+    def descendants
+      children.flat_map { |child| [child] + child.descendants }
+    end
+
+    # The descendants of the category and the category itself
+    #
+    # @return [Array<Category>]
+    def descendants_and_self
+      [self] + descendants
+    end
+
+    # The friendly name of the category
+    #
+    # @return [String]
+    def friendly_name
+      "#{id}_#{IdentifierFormatter.format_friendly_id(name)}"
+    end
+
+    # The next child ID for the category
+    #
+    # @return [String]
+    def next_child_id
+      largest_child_id = children.map { _1.id.split("-").last.to_i }.max || 0
+
+      "#{id}-#{largest_child_id + 1}"
+    end
+
+    private
+
+    #
+    # Validation
+    #
+    def id_matches_depth
+      parts_count = id.split("-").size
+
+      return if parts_count == level + 1
+
+      if level.zero?
+        # In this case, the most likely mistake was not adding the category to the parent's `children` field.
+        errors.add(:base, :orphan, message: "\"#{id}\" does not appear in the children of any category")
+      else
+        errors.add(
+          :id,
+          :depth_mismatch,
+          message: "\"#{id}\" has #{parts_count} #{"part".pluralize(parts_count)} but is at level #{level + 1}",
+        )
+      end
+    end
+
+    def id_starts_with_parent_id
+      return if id.start_with?(parent.id)
+
+      errors.add(:id, :prefix_mismatch, message: "\"#{id}\" must be prefixed by \"#{parent.id}\"")
+    end
+
+    def attributes_found?
+      attributes&.each do |attribute|
+        next if attribute.is_a?(Attribute)
+
+        errors.add(
+          :attributes,
+          :not_found,
+          message: "not found for friendly ID \"#{attribute}\"",
+        )
+      end
+    end
+
+    def children_found?
+      children&.each do |child|
+        next if child.is_a?(Category)
+
+        errors.add(
+          :children,
+          :not_found,
+          message: "not found for friendly ID \"#{child}\"",
+        )
+      end
+    end
+
+    def secondary_children_found?
+      secondary_children&.each do |child|
+        next if child.is_a?(Category)
+
+        errors.add(
+          :secondary_children,
+          :not_found,
+          message: "not found for friendly ID \"#{child}\"",
+        )
+      end
+    end
+  end
+end