edoxen 0.1.1 → 0.3.0

data/lib/edoxen/schema_validator.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+require "yaml"
+
+module Edoxen
+  # Validates Edoxen YAML files against `schema/edoxen.yaml`.
+  #
+  # The SchemaValidator is intentionally small and only owns one concern:
+  # JSON-Schema validation with line-accurate error reporting. It does not
+  # touch the Ruby model — CLI layers SchemaValidator and
+  # `ResolutionCollection.from_yaml` to catch both schema-level violations
+  # (additionalProperties, required, enum) and structural issues
+  # (numeric/date coercion, missing nested classes) the schema can't express.
+  #
+  # Line tracking is built from indentation heuristics over the source text.
+  # That's a deliberate trade-off: a 30-line heuristic versus introducing a
+  # full line-tracking YAML parser dependency, in exchange for error reports
+  # that are accurate on real-world 2-space-indented fixture files (which is
+  # all we use). The lookup is OCP-compliant (longest-prefix match — no
+  # hard-coded path shapes) so adding new collection fields never requires
+  # touching this class.
+  class SchemaValidator
+    class ValidationError < StandardError
+      attr_reader :file, :line, :column, :pointer, :message_text
+
+      def initialize(file:, line:, column:, pointer:, message_text:)
+        @file = file
+        @line = line
+        @column = column
+        @pointer = pointer
+        @message_text = message_text
+        super(format_line(file, line, column, message_text, pointer))
+      end
+
+      def to_clickable_format
+        format_line(@file, @line, @column, @message_text, @pointer)
+      end
+
+      private
+
+      def format_line(file, line, column, message_text, pointer)
+        suffix = pointer.to_s.empty? ? "" : " at `#{pointer}`"
+        "#{file}:#{line}:#{column}: #{message_text}#{suffix}"
+      end
+    end
+
+    def initialize(schema_path = default_schema_path)
+      @schema_path = schema_path
+      @schemer = load_schemer(schema_path)
+    end
+
+    # Validate a YAML file. Returns an array of ValidationError (empty = ok).
+    def validate_file(file_path)
+      validate_content(File.read(file_path), file_path)
+    rescue Errno::ENOENT
+      [ValidationError.new(
+        file: file_path, line: 1, column: 1,
+        pointer: "", message_text: "File not found"
+      )]
+    end
+
+    # Validate a YAML string. Returns an array of ValidationError.
+    def validate_content(content, file_path)
+      data = normalize_dates(YAML.safe_load(content, permitted_classes: [Date, Time]))
+      line_map = LineMap.build(content)
+
+      @schemer.validate(data).to_a.map do |err|
+        pointer = err.fetch("data_pointer", "")
+        message = format_message(err)
+        line, column = LineMap.locate(pointer, line_map)
+        ValidationError.new(
+          file: file_path, line: line, column: column,
+          pointer: pointer, message_text: message
+        )
+      end
+    rescue Psych::SyntaxError => e
+      [ValidationError.new(
+        file: file_path, line: e.line || 1, column: e.column || 1,
+        pointer: "", message_text: "YAML syntax error: #{e.problem}"
+      )]
+    end
+
+    private
+
+    def default_schema_path
+      File.expand_path("../../schema/edoxen.yaml", __dir__)
+    end
+
+    def load_schemer(path)
+      JSONSchemer.schema(YAML.safe_load(File.read(path), permitted_classes: [Date, Time]))
+    end
+
+    # Coerce Date/Time instances back to ISO strings before handing the
+    # data to json_schemer — the schema declares them as `type: string,
+    # format: date` because that's also the wire form. Walking the hash
+    # here keeps the gem OCP-compliant (no json_schemer plugin/tweak).
+    def normalize_dates(value)
+      case value
+      when Date then value.iso8601
+      when Time then value.iso8601
+      when Hash then value.transform_values { |v| normalize_dates(v) }
+      when Array then value.map { |v| normalize_dates(v) }
+      else value
+      end
+    end
+
+    def format_message(err)
+      type = err["type"]
+      details = err["details"] || {}
+      pointer = err["data_pointer"].to_s
+      case type
+      when "required"
+        missing = Array(details["missing_keys"])
+        if missing.size == 1
+          "object is missing required property: #{missing.first}"
+        else
+          "object is missing required properties: #{missing.join(", ")}"
+        end
+      when "additionalProperties"
+        extra = Array(details["extra_keys"])
+        case extra.size
+        when 0 then "object has disallowed additional properties"
+        when 1 then "object property '#{extra.first}' is a disallowed additional property"
+        else "object properties #{extra.map { |k| "'#{k}'" }.join(", ")} are disallowed additional properties"
+        end
+      when "enum"
+        vals = Array(details["valid_values"])
+        enums = vals.empty? ? "(see schema)" : vals.join(", ")
+        "value #{details["value"].inspect} is not one of: #{enums}"
+      when "type"
+        expected = Array(details["expected_types"])
+        "value is not #{expected.empty? ? "the expected type" : expected.join(" or ")}"
+      when "pattern"
+        "value #{details["value"].inspect} does not match pattern #{details["pattern"].inspect}"
+      when "minItems"
+        "array has fewer than #{details["minimum"]} items"
+      when "maxItems"
+        "array has more than #{details["maximum"]} items"
+      else
+        err["error"] || "validation failed"
+      end
+    end
+
+    # Builds a {path => line_no} map for a YAML source. The path is the
+    # JSON-Schema-style pointer: "/metadata", "/resolutions/0/title", etc.
+    # This is a tag-class is allocated freely — no `instance_variable_set`
+    # ever crosses another object's boundary.
+    module LineMap
+      module_function
+
+      # @return [Hash{String => Integer}]
+      def build(content)
+        map = {}
+        stack = []
+        array_counter = Hash.new(-1)
+        array_path_for = {}
+
+        content.each_line.with_index(1) do |raw, line_no|
+          line = raw.chomp
+          stripped = line.strip
+          next if stripped.empty? || stripped.start_with?("#") || stripped == "---"
+
+          indent = line.index(/\S/) || 0
+          level = indent / 2
+          stack = stack.first(level)
+
+          if stripped.start_with?("- ")
+            parent = stack.empty? ? "" : "/#{stack.join("/")}"
+            parent_key = parent.empty? ? parent : parent.dup
+            array_counter[parent_key] = -1 unless array_counter.key?(parent_key)
+            array_counter[parent_key] += 1
+            array_index = array_counter[parent_key]
+            array_path = "#{parent}/#{array_index}"
+            map[array_path] = line_no
+
+            remainder = stripped[2..].to_s.strip
+            if remainder.match(/\A(.+?):(\s|$)/)
+              key = Regexp.last_match(1).strip.gsub(/["']/, "")
+              map["#{array_path}/#{key}"] = line_no
+              stack = stack.first(level) + [array_index.to_s, key]
+            else
+              stack = stack.first(level) + [array_index.to_s]
+            end
+          elsif (md = stripped.match(/\A(.+?):(\s|$)/))
+            key = md[1].strip.gsub(/["']/, "")
+            stack = stack.first(level) + [key]
+            full = "/#{stack.join("/")}"
+            map[full] = line_no
+            array_counter.delete_if { |p, _| p.start_with?(full) }
+          end
+        end
+        map
+      end
+
+      # @return [Array(Integer, Integer)] [line, column] for the given
+      #   JSON-Schema data pointer. Picks the longest prefix in the line map
+      #   — pure longest-match, no knowledge of specific path shapes.
+      def locate(pointer, line_map)
+        pointer = pointer.to_s
+        return [1, 1] if pointer.empty?
+
+        match_key = line_map.keys
+                            .select { |path| pointer.start_with?(path) || path.start_with?(pointer) }
+                            .max_by(&:length)
+
+        match_key ? [line_map[match_key], 1] : [1, 1]
+      end
+    end
+  end
+end

data/lib/edoxen/source_url.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Per-language canonical source URL (e.g. one PDF per language).
+  # Carries the URL ref, its format, and the ISO 639-3 language_code the URL
+  # is the canonical source for.
+  class SourceUrl < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :format, :string
+    attribute :language_code, :string
+
+    key_value do
+      map "ref", to: :ref
+      map "format", to: :format
+      map "language_code", to: :language_code
+    end
+  end
+end

data/lib/edoxen/structured_identifier.rb

@@ -1,20 +1,17 @@
 # frozen_string_literal: true
 
-# StructuredIdentifier {
-#   number:
-#   prefix:
-# }
-
-require "lutaml/model"
-
 module Edoxen
+  # A structured resolution identifier, e.g. prefix "ISO" + number "2019-01".
+  # A Resolution carries 1..* StructuredIdentifier so a single resolution can
+  # hold its TC number, its SC number, and any cross-cutting reference number
+  # without forcing callers to flatten them into one opaque string.
   class StructuredIdentifier < Lutaml::Model::Serializable
-    attribute :number, :string
     attribute :prefix, :string
+    attribute :number, :string
 
     key_value do
-      map "number", to: :number
       map "prefix", to: :prefix
+      map "number", to: :number
     end
   end
 end

data/lib/edoxen/url.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # URL with a kind (access / report) and an optional format hint (pdf, html).
+  class Url < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::URL_KIND
+    attribute :ref, :string
+    attribute :format, :string
+
+    key_value do
+      map "kind", to: :kind
+      map "ref", to: :ref
+      map "format", to: :format
+    end
+  end
+end

data/lib/edoxen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Edoxen
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/edoxen.rb

@@ -1,27 +1,45 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "edoxen/version"
 
-# Configure lutaml-model for YAML serialization
-Lutaml::Model::Config.configure do |config|
-  config.yaml_adapter_type = :standard_yaml
-  config.json_adapter_type = :standard_json
+# Configure the lutaml-model serialization framework used throughout the
+# Edoxen information-model gem.
+Lutaml::Model::Config.configure do |c|
+  c.yaml_adapter_type = :standard_yaml
+  c.json_adapter_type = :standard_json
 end
 
 module Edoxen
-  class Error < StandardError; end
+  # Autoload every constant defined under the Edoxen namespace from its
+  # native `lib/edoxen/<name>.rb` file. This is the only place where file
+  # paths are tied to constants; everywhere else, models reference each
+  # other by class name (resolved lazily by Ruby).
+  #
+  # There are intentionally NO `require_relative` calls in this gem —
+  # autoload keeps load-order semantics clean and lets us tolerate the
+  # extensive cross-references between model classes
+  # (Resolution <-> Localization, ResolutionMetadata <-> Localization, etc.).
+  autoload :VERSION, "edoxen/version"
+  autoload :Error, "edoxen/error"
+  autoload :Enums, "edoxen/enums"
 
-  # Load all model classes
-  require_relative "edoxen/action"
-  require_relative "edoxen/approval"
-  require_relative "edoxen/consideration"
-  require_relative "edoxen/meeting"
-  require_relative "edoxen/resolution"
-  require_relative "edoxen/resolution_collection"
-  require_relative "edoxen/resolution_date"
-  require_relative "edoxen/resolution_relationship"
-  require_relative "edoxen/structured_identifier"
-  require_relative "edoxen/subject_body"
-  require_relative "edoxen/meeting_identfier"
+  # Information-model classes (one per file, one concept per class).
+  # Names mirror ../edoxen-model/models/*.lutaml.
+  autoload :StructuredIdentifier, "edoxen/structured_identifier"
+  autoload :MeetingIdentifier, "edoxen/meeting_identifier"
+  autoload :ResolutionDate, "edoxen/resolution_date"
+  autoload :Action, "edoxen/action"
+  autoload :Approval, "edoxen/approval"
+  autoload :Consideration, "edoxen/consideration"
+  autoload :SourceUrl, "edoxen/source_url"
+  autoload :Localization, "edoxen/localization"
+  autoload :Url, "edoxen/url"
+  autoload :ResolutionRelation, "edoxen/resolution_relation"
+  autoload :Resolution, "edoxen/resolution"
+  autoload :ResolutionMetadata, "edoxen/resolution_metadata"
+  autoload :ResolutionCollection, "edoxen/resolution_collection"
+
+  # Services.
+  autoload :SchemaValidator, "edoxen/schema_validator"
+  autoload :Cli, "edoxen/cli"
 end