ruby-structured-data 0.1.1

data/lib/generators/structured_data/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module StructuredData
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies StructuredData initializer to your application."
+
+      def copy_initializer
+        copy_file "structured_data.rb", "config/initializers/structured_data.rb"
+      end
+    end
+  end
+end

data/lib/generators/structured_data/install/templates/structured_data.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+StructuredData.configure do |config|
+  # Validation mode: :strict, :schema_org (default), or :none
+  config.validation_mode = :schema_org
+
+  # Output pretty formatted JSON-LD
+  config.pretty = Rails.env.development?
+end
+
+# Register controller/action structured data builders:
+# StructuredData::Rails::Registry.register("landing#index", LandingPageBuilder)
+# StructuredData::Rails::Registry.register("products#show") do |context|
+#   StructuredData.node("Product", name: context.product.name)
+# end

data/lib/ruby-structured-data.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ruby_structured_data"

data/lib/ruby_structured_data.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "structured_data/version"
+require_relative "structured_data"

data/lib/structured_data/compiler/parser.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "terms"
+require_relative "uri_helper"
+
+module StructuredData
+  class Compiler
+    class Parser
+      include UriHelper
+
+      LINE_PATTERN = Regexp.new(
+        "\\A(?<subject><(?>(?:[^>\\\\]|\\\\.)+)>|_:[a-zA-Z0-9_.-]+)\\s+" \
+        "(?<predicate><(?>(?:[^>\\\\]|\\\\.)+)>)\\s+" \
+        "(?<object><(?>(?:[^>\\\\]|\\\\.)+)>|_:[a-zA-Z0-9_.-]+|" \
+        "\"(?>(?:[^\"\\\\]|\\\\.)*)\"(?:@[\\w-]+|\\^\\^<(?>(?:[^>\\\\]|\\\\.)+)>)?)" \
+        "\\s*\\.\\s*(?:#.*)?\\z"
+      )
+
+      def initialize(vocab)
+        @vocab = vocab
+      end
+
+      def parse(lines)
+        lines.each_with_index do |line, index|
+          parse_line(line, index + 1)
+        end
+      end
+
+      def parse_line(line, line_number)
+        stripped = line.strip
+        return if stripped.empty? || stripped.start_with?("#")
+
+        match = LINE_PATTERN.match(stripped)
+        raise_syntax_error(line, line_number, stripped) unless match
+
+        process_match(match)
+      end
+
+      private
+
+      def raise_syntax_error(line, line_number, stripped)
+        raise ParseError.new(
+          "Invalid N-Triples syntax at line #{line_number}: #{stripped}",
+          line_number: line_number,
+          line: line
+        )
+      end
+
+      def process_match(match)
+        subject_raw = match[:subject]
+        object_raw = match[:object]
+        return if subject_raw.start_with?("_:") || object_raw.start_with?("_:")
+
+        subject_term = extract_schema_term(extract_uri(subject_raw))
+        predicate_uri = extract_uri(match[:predicate])
+        return unless subject_term && predicate_uri
+
+        dispatch_predicate(subject_term, predicate_uri, object_raw)
+      end
+
+      def dispatch_predicate(subject_term, predicate_uri, object_raw)
+        case predicate_uri
+        when Terms::PREDICATES[:subclass_of] then handle_subclass_of(subject_term, object_raw)
+        when Terms::PREDICATES[:domain_includes] then handle_domain_includes(subject_term, object_raw)
+        when Terms::PREDICATES[:range_includes] then handle_range_includes(subject_term, object_raw)
+        when Terms::PREDICATES[:type] then handle_rdf_type(subject_term, object_raw)
+        when Terms::PREDICATES[:superseded_by] then handle_superseded_by(subject_term, object_raw)
+        when Terms::PREDICATES[:is_part_of] then handle_is_part_of(subject_term, object_raw)
+        end
+      end
+
+      def handle_subclass_of(subject_term, object_raw)
+        @vocab.add_class(subject_term)
+        parent_term = extract_schema_term(extract_uri(object_raw))
+        @vocab.add_subclass(subject_term, parent_term) if parent_term
+      end
+
+      def handle_domain_includes(subject_term, object_raw)
+        @vocab.add_property(subject_term)
+        domain_term = extract_schema_term(extract_uri(object_raw))
+        @vocab.add_domain(subject_term, domain_term) if domain_term
+      end
+
+      def handle_range_includes(subject_term, object_raw)
+        @vocab.add_property(subject_term)
+        range_term = extract_schema_term(extract_uri(object_raw))
+        @vocab.add_range(subject_term, range_term) if range_term
+      end
+
+      def handle_rdf_type(subject_term, object_raw)
+        object_uri = extract_uri(object_raw)
+        return unless object_uri
+
+        case object_uri
+        when Terms::TYPES[:rdfs_class], Terms::TYPES[:rdf_class]
+          @vocab.add_class(subject_term)
+        when Terms::TYPES[:rdf_property]
+          @vocab.add_property(subject_term)
+        else
+          handle_enum_type(subject_term, object_uri)
+        end
+      end
+
+      def handle_enum_type(subject_term, object_uri)
+        enum_type = extract_schema_term(object_uri)
+        @vocab.add_enum_member(enum_type, subject_term) if enum_type
+      end
+
+      def handle_superseded_by(subject_term, object_raw)
+        replacement = extract_schema_term(extract_uri(object_raw))
+        @vocab.add_superseded(subject_term, replacement) if replacement
+      end
+
+      def handle_is_part_of(subject_term, object_raw)
+        section = extract_section(object_raw)
+        @vocab.set_section(subject_term, section)
+      end
+    end
+  end
+end

data/lib/structured_data/compiler/terms.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Compiler
+    module Terms
+      PREDICATES = {
+        subclass_of: "http://www.w3.org/2000/01/rdf-schema#subClassOf",
+        type: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+        domain_includes: "https://schema.org/domainIncludes",
+        range_includes: "https://schema.org/rangeIncludes",
+        superseded_by: "https://schema.org/supersededBy",
+        is_part_of: "https://schema.org/isPartOf"
+      }.freeze
+
+      TYPES = {
+        rdfs_class: "http://www.w3.org/2000/01/rdf-schema#Class",
+        rdf_class: "http://www.w3.org/1999/02/22-rdf-syntax-ns#Class",
+        rdf_property: "http://www.w3.org/1999/02/22-rdf-syntax-ns#Property"
+      }.freeze
+
+      SCHEMA_PREFIX = "https://schema.org/"
+    end
+  end
+end

data/lib/structured_data/compiler/uri_helper.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Compiler
+    module UriHelper
+      ESCAPE_CHARS = {
+        "t" => "\t",
+        "b" => "\b",
+        "n" => "\n",
+        "r" => "\r",
+        "f" => "\f",
+        "\"" => "\"",
+        "'" => "'",
+        "\\" => "\\"
+      }.freeze
+
+      def extract_uri(raw)
+        return unless raw.start_with?("<")
+
+        normalize_uri(unescape(raw[1..-2]))
+      end
+
+      def normalize_uri(uri)
+        normalized = uri.sub(%r{\Ahttp://schema\.org(/|\z)}, "https://schema.org\\1")
+        normalized.sub(%r{\Ahttps://www\.w3\.org/}, "http://www.w3.org/")
+      end
+
+      def extract_schema_term(uri)
+        return unless uri =~ %r{\Ahttps://schema\.org/([^/]+)\z}
+
+        Regexp.last_match(1)
+      end
+
+      def extract_section(object_raw)
+        return object_raw[1..-2] if object_raw.start_with?('"') && object_raw.end_with?('"')
+
+        uri = unescape(object_raw.delete_prefix("<").delete_suffix(">"))
+        section_from_subdomain(uri) || section_from_path(uri) || Vocabulary::CORE_SECTION
+      end
+
+      def section_from_subdomain(uri)
+        return unless uri =~ %r{\Ahttps?://([a-zA-Z0-9_-]+)\.schema\.org}
+
+        subdomain = Regexp.last_match(1)
+        subdomain unless subdomain == "www"
+      end
+
+      def section_from_path(uri)
+        return unless uri =~ %r{\Ahttps?://(?:www\.)?schema\.org/(.+?)/?\z}
+
+        Regexp.last_match(1)
+      end
+
+      def unescape(str)
+        str.gsub(/\\(?:([tbnrf"'\\])|u([0-9A-Fa-f]{4})|U([0-9A-Fa-f]{8}))/) do
+          if (char = Regexp.last_match(1))
+            ESCAPE_CHARS[char]
+          else
+            hex = Regexp.last_match(2) || Regexp.last_match(3)
+            [hex.hex].pack("U*")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/compiler/vocabulary.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Compiler
+    class Vocabulary
+      CORE_SECTION = "core"
+
+      def initialize(version)
+        @version = version
+        @data = {
+          classes: Set.new,
+          properties: Set.new,
+          parents: {},
+          domains: {},
+          ranges: {},
+          enums: {},
+          superseded: {},
+          sections: {}
+        }
+      end
+
+      def add_class(name)
+        @data[:classes].add(name)
+      end
+
+      def add_subclass(child, parent)
+        @data[:classes].add(child)
+        (@data[:parents][child] ||= []) << parent
+      end
+
+      def add_property(name)
+        @data[:properties].add(name)
+      end
+
+      def add_domain(property, domain)
+        @data[:properties].add(property)
+        (@data[:domains][property] ||= []) << domain
+      end
+
+      def add_range(property, range)
+        @data[:properties].add(property)
+        (@data[:ranges][property] ||= []) << range
+      end
+
+      def add_enum_member(enum_type, member)
+        (@data[:enums][enum_type] ||= []) << member
+      end
+
+      def add_superseded(old_term, new_term)
+        @data[:superseded][old_term] = new_term
+      end
+
+      def set_section(term, section)
+        @data[:sections][term] = section
+      end
+
+      def to_h
+        {
+          "version" => @version,
+          "types" => build_types,
+          "properties" => build_properties,
+          "enums" => build_enums,
+          "superseded" => build_superseded
+        }
+      end
+
+      private
+
+      def build_types
+        @data[:classes].to_a.sort.to_h do |type_name|
+          [
+            type_name,
+            {
+              "parents" => (@data[:parents][type_name] || []).sort.uniq,
+              "section" => @data[:sections][type_name] || CORE_SECTION
+            }
+          ]
+        end
+      end
+
+      def build_properties
+        @data[:properties].to_a.sort.to_h do |prop_name|
+          [
+            prop_name,
+            {
+              "domains" => (@data[:domains][prop_name] || []).sort.uniq,
+              "ranges" => (@data[:ranges][prop_name] || []).sort.uniq
+            }
+          ]
+        end
+      end
+
+      def build_enums
+        result = {}
+        @data[:enums].keys.sort.each do |enum_type|
+          members = clean_enum_members(@data[:enums][enum_type])
+          result[enum_type] = members unless members.empty?
+        end
+        result
+      end
+
+      def clean_enum_members(members)
+        classes = @data[:classes]
+        properties = @data[:properties]
+        members.reject { |m| classes.include?(m) || properties.include?(m) }.sort.uniq
+      end
+
+      def build_superseded
+        @data[:superseded].keys.sort.to_h do |term|
+          [term, @data[:superseded][term]]
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/compiler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "compiler/vocabulary"
+require_relative "compiler/parser"
+
+module StructuredData
+  class Compiler
+    class ParseError < StandardError
+      attr_reader :line_number, :line
+
+      def initialize(message, line_number: nil, line: nil)
+        @line_number = line_number
+        @line = line
+        super(message)
+      end
+    end
+
+    class << self
+      def compile(source, version: "30.0")
+        new(source, version: version).compile
+      end
+
+      def compile_to_file(source_path, target_path, version: "30.0")
+        new(source_path, version: version).compile_to_file(target_path)
+      end
+    end
+
+    def initialize(source, version: "30.0")
+      @source = source
+      @version = version
+    end
+
+    def compile
+      @compile ||= begin
+        vocab = Vocabulary.new(@version)
+        Parser.new(vocab).parse(source_lines)
+        vocab.to_h
+      end
+    end
+
+    def compile_to_file(target_path)
+      result = compile
+      File.write(target_path, "#{JSON.pretty_generate(result)}\n")
+      result
+    end
+
+    private
+
+    def source_lines
+      if @source.respond_to?(:each_line) && !@source.is_a?(String)
+        @source.each_line
+      elsif @source.is_a?(String)
+        string_source_lines
+      else
+        raise ArgumentError, "Unsupported source: #{@source.inspect}"
+      end
+    end
+
+    def string_source_lines
+      if !@source.include?("\n") && File.file?(@source)
+        File.foreach(@source)
+      else
+        @source.each_line
+      end
+    end
+  end
+end

data/lib/structured_data/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Configuration
+    DEFAULT_VALIDATION_MODE = :schema_org
+    DEFAULT_PRETTY = false
+
+    attr_accessor :validation_mode, :pretty
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      @validation_mode = DEFAULT_VALIDATION_MODE
+      @pretty = DEFAULT_PRETTY
+    end
+  end
+end

data/lib/structured_data/document.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "error"
+
+module StructuredData
+  class Document
+    class DuplicateIdError < StructuredData::Error; end
+
+    DEFAULT_CONTEXT = "https://schema.org"
+
+    attr_reader :context
+
+    def initialize(*nodes, context: DEFAULT_CONTEXT, graph: nil)
+      @context = context
+      @graph = graph
+      @nodes = []
+      nodes.flatten.each { |node| add(node) }
+    end
+
+    def nodes
+      @nodes.dup.freeze
+    end
+
+    def graph?
+      @nodes.size != 1 || @graph == true
+    end
+
+    def add(node)
+      if node.is_a?(Array)
+        node.each { |item| add(item) }
+      else
+        validate_node!(node)
+        check_duplicate_id!(node)
+        @nodes << node
+      end
+      self
+    end
+    alias << add
+
+    def to_h
+      if graph?
+        {
+          "@context" => context,
+          "@graph" => @nodes.map(&:to_h)
+        }
+      else
+        { "@context" => context }.merge(@nodes.first.to_h)
+      end
+    end
+
+    def as_json(*)
+      to_h
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        context == other.context &&
+        graph? == other.graph? &&
+        nodes == other.nodes
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, context, graph?, nodes].hash
+    end
+
+    private
+
+    def validate_node!(node)
+      raise ArgumentError, "Node cannot be nil" if node.nil?
+      raise ArgumentError, "Node must respond to #to_h" unless node.respond_to?(:to_h)
+    end
+
+    def check_duplicate_id!(node)
+      id = explicit_id(node)
+      return unless id
+
+      existing = @nodes.find { |n| explicit_id(n) == id }
+      return unless existing && existing != node
+
+      raise DuplicateIdError, "Conflicting duplicate @id detected: #{id}"
+    end
+
+    def explicit_id(node)
+      return nil unless node.respond_to?(:id)
+
+      raw_id = node.id
+      return nil if raw_id.nil?
+
+      str_id = raw_id.to_s.strip
+      str_id.empty? ? nil : str_id
+    end
+  end
+end

data/lib/structured_data/enum.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module StructuredData
+  class Enum
+    SCHEMA_ORG_URI_PREFIX = "https://schema.org/"
+
+    attr_reader :name, :type, :uri
+
+    def initialize(name, type = nil)
+      raise ArgumentError, "name cannot be blank" if name.nil? || name.to_s.strip.empty?
+
+      @name = normalize_term(name)
+      @type = blank?(type) ? nil : normalize_term(type)
+      @uri = "#{SCHEMA_ORG_URI_PREFIX}#{@name}"
+    end
+
+    def to_s
+      uri
+    end
+    alias to_str to_s
+
+    def to_h
+      uri
+    end
+
+    def as_json(*)
+      uri
+    end
+
+    def to_json(*)
+      uri.to_json(*)
+    end
+
+    def ==(other)
+      if other.is_a?(self.class)
+        uri == other.uri
+      elsif other.is_a?(String)
+        uri == other
+      else
+        false
+      end
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) && uri == other.uri
+    end
+
+    def hash
+      [self.class, uri].hash
+    end
+
+    private
+
+    def blank?(val)
+      val.nil? || (val.respond_to?(:to_s) && val.to_s.strip.empty?)
+    end
+
+    def normalize_term(term)
+      term.to_s.strip.sub(%r{\Ahttps?://schema\.org/}, "")
+    end
+  end
+end

data/lib/structured_data/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    attr_reader :result
+
+    def initialize(result_or_message = nil)
+      if result_or_message.respond_to?(:errors)
+        @result = result_or_message
+        errors_str = @result.errors.map { |e| "#{e.path}: #{e.message}" }.join("; ")
+        super("Validation failed: #{errors_str}")
+      else
+        super(result_or_message || "Validation failed")
+      end
+    end
+  end
+end

data/lib/structured_data/list.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class List
+    include Enumerable
+
+    attr_reader :items
+
+    def initialize(items = [])
+      raise ArgumentError, "items must be Enumerable" unless items.is_a?(Enumerable) || items.respond_to?(:to_a)
+
+      @items = items.to_a
+    end
+
+    def each(&)
+      items.each(&)
+    end
+
+    def to_h
+      {
+        "@list" => items.map { |item| serialize_item(item) }
+      }
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && items == other.items
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, items].hash
+    end
+
+    private
+
+    def serialize_item(item)
+      if item.is_a?(Array)
+        item.map { |nested| serialize_item(nested) }
+      elsif item.respond_to?(:to_h)
+        item.to_h
+      else
+        item
+      end
+    end
+  end
+end