ruby-structured-data 0.1.1

data/lib/structured_data/node.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "reference"
+require_relative "list"
+require_relative "enum"
+require_relative "values"
+
+module StructuredData
+  class Node
+    attr_reader :type, :id, :attributes
+
+    def initialize(type, id: nil, **attributes, &block)
+      @type = normalize_type(type)
+      @id = id
+      @attributes = {}
+      attributes.each { |key, value| set(key, value) }
+      yield(self) if block_given?
+    end
+
+    def set(property, value)
+      key = to_lower_camel_case(property)
+      if id_key?(property, key)
+        @id = value
+      else
+        @attributes[key] = value
+      end
+      self
+    end
+
+    def [](property)
+      key = to_lower_camel_case(property)
+      return id if id_key?(property, key)
+
+      attributes[key] || attributes[property.to_s] || attributes[property.to_sym]
+    end
+
+    def ref
+      raise ArgumentError, "Cannot create reference without id" unless id_present?
+
+      StructuredData::Reference.new(id)
+    end
+
+    def to_h
+      result = { "@type" => type }
+      result["@id"] = id.to_s if id_present?
+
+      attributes.keys.map(&:to_s).sort.each do |key|
+        result[key] = serialize_value(attributes[key])
+      end
+
+      result
+    end
+
+    def as_json(*)
+      to_h
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    def id_present?
+      !id.nil? && !id.to_s.strip.empty?
+    end
+
+    def id_key?(property, key)
+      key == "id" || property.to_s == "@id"
+    end
+
+    def blank?(val)
+      val.nil? || (val.respond_to?(:to_s) && val.to_s.strip.empty?)
+    end
+
+    def normalize_type(type)
+      raise ArgumentError, "type cannot be blank" if blank?(type)
+
+      clean = type.to_s.strip.sub(%r{\Ahttps?://schema\.org/}, "")
+      parts = clean.split("_").reject(&:empty?)
+      raise ArgumentError, "type cannot be blank" if parts.empty?
+
+      parts.map { |part| part[0].upcase + part[1..] }.join
+    end
+
+    def to_lower_camel_case(prop)
+      str = prop.to_s.strip
+      parts = str.split("_").reject(&:empty?)
+      return str if parts.empty?
+
+      first_lower = parts.first[0].downcase + parts.first[1..]
+      camel_rest(first_lower, parts[1..])
+    end
+
+    def camel_rest(first, rest)
+      tail = rest.map { |part| part[0].upcase + part[1..] }
+      ([first] + tail).join
+    end
+
+    def serialize_value(val)
+      case val
+      when Node, Reference, List, Enum, Values::Url, Values::Text
+        val.to_h
+      when Array
+        val.map { |item| serialize_value(item) }
+      when Hash
+        val.transform_values { |item| serialize_value(item) }
+      when URI::Generic
+        val.to_s
+      else
+        serialize_fallback(val)
+      end
+    end
+
+    def serialize_fallback(val)
+      if val.respond_to?(:to_h)
+        val.to_h
+      else
+        val
+      end
+    end
+  end
+end

data/lib/structured_data/rails/helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StructuredData
+  module Rails
+    module Helper
+      def structured_data_tag(document_or_node = nil)
+        return Renderer.render(document_or_node) if document_or_node
+
+        ctrl_path = structured_data_controller_path
+        act_name = structured_data_action_name
+        return nil unless ctrl_path && act_name
+
+        resolved = Registry.resolve(ctrl_path, act_name, self)
+        return nil if resolved.nil?
+
+        Renderer.render(resolved)
+      end
+
+      private
+
+      def structured_data_controller_path
+        if respond_to?(:controller_path) && controller_path
+          controller_path
+        elsif respond_to?(:controller) && controller.respond_to?(:controller_path)
+          controller.controller_path
+        end
+      end
+
+      def structured_data_action_name
+        if respond_to?(:action_name) && action_name
+          action_name
+        elsif respond_to?(:controller) && controller.respond_to?(:action_name)
+          controller.action_name
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/rails/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module StructuredData
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.structured_data = ActiveSupport::OrderedOptions.new
+
+      initializer "structured_data.setup" do |app|
+        options = app.config.structured_data
+
+        StructuredData.configure do |config|
+          config.validation_mode = options.validation_mode unless options.validation_mode.nil?
+          config.pretty = options.pretty unless options.pretty.nil?
+        end
+
+        ActiveSupport.on_load(:action_view) do
+          include StructuredData::Rails::Helper
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/rails/registry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module StructuredData
+  module Rails
+    class Registry
+      @entries = {}
+      @monitor = Monitor.new
+
+      class << self
+        def register(target_or_controller, action_or_builder = nil, builder = nil, &block)
+          key, actual_builder = normalize_registration(
+            target_or_controller, action_or_builder, builder, block
+          )
+
+          @monitor.synchronize do
+            @entries[key] = actual_builder
+          end
+        end
+
+        def resolve(controller_path, action_name, context = nil)
+          key = normalize_key("#{controller_path}##{action_name}")
+          builder = @monitor.synchronize { @entries[key] }
+          return nil if builder.nil?
+
+          execute(builder, context)
+        end
+
+        def clear!
+          @monitor.synchronize do
+            @entries.clear
+          end
+        end
+        alias reset! clear!
+
+        def registered?(target_or_controller, action = nil)
+          key = if action
+                  normalize_key("#{target_or_controller}##{action}")
+                else
+                  normalize_key(target_or_controller)
+                end
+          @monitor.synchronize { @entries.key?(key) }
+        end
+
+        private
+
+        def normalize_registration(target, action_or_builder, builder, block)
+          if block
+            key = action_or_builder ? normalize_key("#{target}##{action_or_builder}") : normalize_key(target)
+            [key, block]
+          elsif builder
+            [normalize_key("#{target}##{action_or_builder}"), builder]
+          else
+            [normalize_key(target), action_or_builder]
+          end
+        end
+
+        def normalize_key(key)
+          key.to_s.sub(%r{\A/+}, "")
+        end
+
+        def execute(builder, context)
+          if builder.is_a?(Class)
+            execute_class(builder, context)
+          elsif builder.respond_to?(:call)
+            execute_callable(builder, context)
+          elsif builder.respond_to?(:build)
+            execute_object_build(builder, context)
+          else
+            builder
+          end
+        end
+
+        def execute_class(klass, context)
+          if klass.respond_to?(:build)
+            invoke_method(klass.method(:build), context)
+          elsif klass.respond_to?(:call)
+            invoke_method(klass.method(:call), context)
+          else
+            instantiate_and_invoke(klass, context)
+          end
+        end
+
+        def instantiate_and_invoke(klass, context)
+          init_arity = klass.instance_method(:initialize).arity
+          instance = init_arity.zero? ? klass.new : klass.new(context)
+
+          if instance.respond_to?(:build)
+            invoke_method(instance.method(:build), context)
+          elsif instance.respond_to?(:call)
+            invoke_method(instance.method(:call), context)
+          else
+            instance
+          end
+        end
+
+        def execute_callable(callable, context)
+          if callable.respond_to?(:arity) && callable.arity.zero?
+            callable.call
+          else
+            callable.call(context)
+          end
+        end
+
+        def execute_object_build(obj, context)
+          if obj.method(:build).arity.zero?
+            obj.build
+          else
+            obj.build(context)
+          end
+        end
+
+        def invoke_method(method_obj, context)
+          if method_obj.arity.zero?
+            method_obj.call
+          else
+            method_obj.call(context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/rails/renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/output_safety"
+
+module StructuredData
+  module Rails
+    class Renderer
+      class << self
+        def render(document_or_node, pretty: StructuredData.config.pretty)
+          return nil if document_or_node.nil?
+
+          json = StructuredData::Serializer.dump(document_or_node, pretty: pretty)
+          html = %(<script type="application/ld+json">#{json}</script>)
+
+          ActiveSupport::SafeBuffer.new(html)
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "rails/registry"
+require_relative "rails/renderer"
+require_relative "rails/helper"
+require_relative "rails/railtie"

data/lib/structured_data/reference.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module StructuredData
+  class Reference
+    attr_reader :id
+
+    def initialize(id)
+      validate_id!(id)
+      @id = id
+    end
+
+    def to_h
+      { "@id" => id.to_s }
+    end
+
+    def to_s
+      id.to_s
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && id.to_s == other.id.to_s
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, id.to_s].hash
+    end
+
+    private
+
+    def validate_id!(val)
+      raise ArgumentError, "id cannot be blank" if blank?(val)
+      raise ArgumentError, "id must be a String or URI" unless string_or_uri?(val)
+    end
+
+    def blank?(val)
+      val.nil? || (val.respond_to?(:to_s) && val.to_s.strip.empty?)
+    end
+
+    def string_or_uri?(val)
+      val.is_a?(String) || val.is_a?(URI::Generic)
+    end
+  end
+end

data/lib/structured_data/serializer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module StructuredData
+  class Serializer
+    class << self
+      def dump(target, pretty: false)
+        new(pretty: pretty).dump(target)
+      end
+    end
+
+    attr_reader :pretty
+
+    def initialize(pretty: false)
+      @pretty = pretty
+    end
+
+    def dump(target, pretty: @pretty)
+      hash = to_hash(target)
+      json = pretty ? JSON.pretty_generate(hash) : JSON.generate(hash)
+      escape_html_script(json)
+    end
+
+    private
+
+    def to_hash(target)
+      if target.is_a?(Hash)
+        target
+      elsif target.respond_to?(:to_h)
+        target.to_h
+      else
+        raise ArgumentError, "Target cannot be serialized to Hash: #{target.inspect}"
+      end
+    end
+
+    def escape_html_script(json)
+      json.gsub(%r{</script}i) { "<\\/script" }
+          .gsub("<!--") { "<\\!--" }
+          .gsub("\u2028") { "\\u2028" }
+          .gsub("\u2029") { "\\u2029" }
+    end
+  end
+end

data/lib/structured_data/validator/context.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "diagnostic"
+
+module StructuredData
+  class Validator
+    class Context
+      attr_reader :mode, :diagnostics
+
+      def initialize(mode, diagnostics)
+        @mode = mode
+        @diagnostics = diagnostics
+      end
+
+      def severity
+        mode == :strict ? :error : :warning
+      end
+
+      def add(code:, severity:, path:, message:, suggestion: nil)
+        diagnostics << Diagnostic.new(
+          code: code,
+          severity: severity,
+          path: path,
+          message: message,
+          suggestion: suggestion
+        )
+      end
+    end
+  end
+end

data/lib/structured_data/validator/diagnostic.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Validator
+    class Diagnostic
+      attr_reader :code, :severity, :path, :message, :suggestion
+
+      def initialize(code:, severity:, path:, message:, suggestion: nil)
+        @code = code
+        @severity = severity
+        @path = path
+        @message = message
+        @suggestion = suggestion
+      end
+
+      def error?
+        severity == :error
+      end
+
+      def warning?
+        severity == :warning
+      end
+
+      def to_h
+        {
+          code: code,
+          severity: severity,
+          path: path,
+          message: message,
+          suggestion: suggestion
+        }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+  Diagnostic = Validator::Diagnostic
+end

data/lib/structured_data/validator/node_validator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+module StructuredData
+  class Validator
+    class NodeValidator
+      attr_reader :vocabulary, :range_checker
+
+      def initialize(vocabulary, range_checker)
+        @vocabulary = vocabulary
+        @range_checker = range_checker
+      end
+
+      def validate(node, path, context)
+        validate_node_type(node, path, context)
+
+        node.attributes.each do |prop, value|
+          validate_attribute(node, prop, value, path, context)
+        end
+      end
+
+      private
+
+      def validate_node_type(node, path, context)
+        if (replacing = vocabulary.superseded_by(node.type))
+          context.add(
+            code: :superseded_term, severity: context.severity,
+            path: "#{path}.@type", message: "Type '#{node.type}' is superseded by '#{replacing}'",
+            suggestion: replacing
+          )
+        end
+
+        return if vocabulary.type_defined?(node.type) || replacing
+
+        context.add(
+          code: :unknown_type, severity: :error,
+          path: "#{path}.@type", message: "Unknown type '#{node.type}'",
+          suggestion: suggest_type(node.type)
+        )
+      end
+
+      def validate_attribute(node, prop, value, path, context)
+        validate_property_name(node, prop, path, context)
+        return unless vocabulary.property_defined?(prop)
+
+        validate_property_domain(node, prop, path, context)
+        validate_property_range(prop, value, path, context)
+      end
+
+      def validate_property_name(node, prop, path, context)
+        if (replacing = vocabulary.superseded_by(prop))
+          context.add(
+            code: :superseded_term, severity: context.severity,
+            path: "#{path}.#{prop}", message: "Property '#{prop}' is superseded by '#{replacing}'",
+            suggestion: replacing
+          )
+        end
+
+        return if vocabulary.property_defined?(prop) || replacing
+
+        context.add(
+          code: :unknown_property, severity: :error,
+          path: "#{path}.#{prop}", message: "Unknown property '#{prop}' for type '#{node.type}'",
+          suggestion: suggest_property(prop)
+        )
+      end
+
+      def validate_property_domain(node, prop, path, context)
+        return if vocabulary.property_allowed_for?(node.type, prop)
+
+        context.add(
+          code: :domain_mismatch, severity: context.severity,
+          path: "#{path}.#{prop}",
+          message: "Property '#{prop}' is not allowed for type '#{node.type}' or its ancestors"
+        )
+      end
+
+      def validate_property_range(prop, value, path, context)
+        ranges = vocabulary.expected_ranges(prop)
+        case value
+        when Array
+          validate_array_range(prop, value, ranges, path, context)
+        when List
+          validate_list_range(prop, value, ranges, path, context)
+        when Node
+          validate_single_range(prop, value, ranges, "#{path}.#{prop}", context)
+          validate(value, "#{path}.#{prop}", context)
+        else
+          validate_single_range(prop, value, ranges, "#{path}.#{prop}", context)
+        end
+      end
+
+      def validate_array_range(prop, array, ranges, path, context)
+        array.each_with_index do |item, idx|
+          item_path = "#{path}.#{prop}[#{idx}]"
+          validate_single_range(prop, item, ranges, item_path, context)
+          validate(item, item_path, context) if item.is_a?(Node)
+        end
+      end
+
+      def validate_list_range(prop, list, ranges, path, context)
+        list.items.each_with_index do |item, idx|
+          item_path = "#{path}.#{prop}.@list[#{idx}]"
+          validate_single_range(prop, item, ranges, item_path, context)
+          validate(item, item_path, context) if item.is_a?(Node)
+        end
+      end
+
+      def validate_single_range(prop, value, ranges, path, context)
+        return if range_checker.matches?(value, ranges)
+
+        context.add(
+          code: :range_mismatch, severity: context.severity,
+          path: path,
+          message: "Value for property '#{prop}' does not match expected range(s): #{ranges.join(', ')}"
+        )
+      end
+
+      def suggest_type(type)
+        @type_checker ||= DidYouMean::SpellChecker.new(dictionary: vocabulary.all_types)
+        @type_checker.correct(type.to_s).first
+      end
+
+      def suggest_property(prop)
+        @property_checker ||= DidYouMean::SpellChecker.new(dictionary: vocabulary.all_properties)
+        @property_checker.correct(prop.to_s).first
+      end
+    end
+  end
+end