edoxen 0.1.2 → 0.3.0

data/lib/edoxen/schema_validator.rb

@@ -2,297 +2,209 @@
 
 require "json_schemer"
 require "yaml"
-require "json"
-require "psych"
 
 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, :message, :data_pointer
+      attr_reader :file, :line, :column, :pointer, :message_text
 
-      def initialize(file, line, column, message, data_pointer = nil)
+      def initialize(file:, line:, column:, pointer:, message_text:)
         @file = file
         @line = line
         @column = column
-        @message = message
-        @data_pointer = data_pointer
-        super("#{file}:#{line}:#{column}: #{message}")
+        @pointer = pointer
+        @message_text = message_text
+        super(format_line(file, line, column, message_text, pointer))
       end
 
       def to_clickable_format
-        "#{file}:#{line}:#{column}: #{message}"
-      end
-    end
-
-    # Custom YAML handler to track line numbers
-    class LineTrackingHandler < Psych::Handler
-      attr_reader :line_map, :path_stack, :array_indices
-
-      def initialize
-        @line_map = {}
-        @path_stack = []
-        @array_indices = {}
-        @current_path = ""
-      end
-
-      def start_document(version, tag_directives, implicit)
-        # Document start
-      end
-
-      def start_mapping(anchor, tag, implicit, style)
-        # Starting a new mapping/object
-      end
-
-      def start_sequence(_anchor, _tag, _implicit, _style)
-        # Starting a new sequence/array
-        parent_path = "/#{@path_stack.join("/")}"
-        parent_path = "" if parent_path == "/"
-        @array_indices[parent_path] = -1
-      end
-
-      def scalar(value, anchor, tag, plain, quoted, style)
-        # This is called for each scalar value
-        # We need to track this in context of the current path
-      end
-
-      def alias(anchor)
-        # Handle YAML aliases
-      end
-
-      def end_sequence
-        # End of sequence/array
+        format_line(@file, @line, @column, @message_text, @pointer)
       end
 
-      def end_mapping
-        # End of mapping/object
-      end
+      private
 
-      def end_document(implicit)
-        # Document end
+      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 = nil)
-      @schema_path = schema_path || File.join(__dir__, "..", "..", "schema", "edoxen.yaml")
-      @schemer = nil
-      load_schema
+    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)
-      return [ValidationError.new(file_path, 1, 1, "File not found")] unless File.exist?(file_path)
-
-      content = File.read(file_path)
-      validate_content(content, 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)
-      errors = []
-
-      begin
-        # Parse YAML and build line map
-        yaml_data, line_map = parse_yaml_with_line_tracking(content)
-
-        # Validate against schema
-        if @schemer
-          schema_errors = @schemer.validate(yaml_data).to_a
-          errors.concat(convert_schema_errors(schema_errors, file_path, line_map))
-        else
-          errors << ValidationError.new(file_path, 1, 1, "Schema not available for validation")
-        end
-      rescue Psych::SyntaxError => e
-        line = e.line || 1
-        column = e.column || 1
-        errors << ValidationError.new(file_path, line, column, "YAML syntax error: #{e.problem}")
-      rescue StandardError => e
-        errors << ValidationError.new(file_path, 1, 1, "Validation error: #{e.message}")
-      end
-
-      errors
+      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 load_schema
-      return unless File.exist?(@schema_path)
-
-      begin
-        schema_content = File.read(@schema_path)
-        schema_data = YAML.safe_load(schema_content)
-        @schemer = JSONSchemer.schema(schema_data)
-      rescue StandardError => e
-        warn "Warning: Could not load schema from #{@schema_path}: #{e.message}"
-        @schemer = nil
-      end
+    def default_schema_path
+      File.expand_path("../../schema/edoxen.yaml", __dir__)
     end
 
-    def parse_yaml_with_line_tracking(content)
-      # Parse YAML normally
-      yaml_data = YAML.safe_load(content)
-
-      # Build line map by parsing the content line by line
-      line_map = build_line_map(content)
-
-      [yaml_data, line_map]
+    def load_schemer(path)
+      JSONSchemer.schema(YAML.safe_load(File.read(path), permitted_classes: [Date, Time]))
     end
 
-    def build_line_map(content)
-      line_map = {}
-      lines = content.split("\n")
-      path_stack = []
-      array_indices = {}
-
-      lines.each_with_index do |line, index|
-        line_number = index + 1
-        stripped = line.strip
-
-        # Skip empty lines and comments
-        next if stripped.empty? || stripped.start_with?("#")
-
-        # Calculate indentation
-        indent = line.length - line.lstrip.length
-        level = indent / 2 # Assuming 2-space indentation
-
-        # Adjust path stack based on indentation level
-        path_stack = path_stack[0, level] if level < path_stack.length
-
-        if stripped.start_with?("- ")
-          # Array item
-          parent_path = path_stack.empty? ? "" : "/#{path_stack.join("/")}"
-          array_indices[parent_path] ||= -1
-          array_indices[parent_path] += 1
-
-          array_index = array_indices[parent_path]
-          current_path = "#{parent_path}/#{array_index}"
-          line_map[current_path] = line_number
-
-          # Check if array item has a key
-          item_content = stripped[2..].strip
-          if item_content.include?(":")
-            key = item_content.split(":").first.strip.gsub(/["']/, "")
-            if key.empty?
-              path_stack = path_stack[0, level] + [array_index.to_s]
-            else
-              key_path = "#{current_path}/#{key}"
-              line_map[key_path] = line_number
-              path_stack = path_stack[0, level] + [array_index.to_s, key]
-            end
-          else
-            path_stack = path_stack[0, level] + [array_index.to_s]
-          end
-        elsif stripped.include?(":")
-          # Regular key-value pair
-          key = stripped.split(":").first.strip.gsub(/["']/, "")
-          next if key.empty?
-
-          path_stack = path_stack[0, level] + [key]
-          current_path = "/#{path_stack.join("/")}"
-          line_map[current_path] = line_number
-
-          # Reset array indices for this path and deeper
-          array_indices.each_key do |path|
-            array_indices.delete(path) if path.start_with?(current_path)
-          end
-        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
-
-      line_map
     end
 
-    def convert_schema_errors(schema_errors, file_path, line_map)
-      schema_errors.map do |error|
-        data_pointer = error["data_pointer"] || ""
-        line = find_line_for_pointer(data_pointer, line_map)
-        column = 1
-
-        message = build_error_message(error)
-
-        ValidationError.new(file_path, line, column, message, data_pointer)
+    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
 
-    def find_line_for_pointer(pointer, line_map)
-      return 1 if pointer.empty?
-
-      # Try exact match first
-      return line_map[pointer] if line_map[pointer]
-
-      # Try progressively shorter paths
-      parts = pointer.split("/").reject(&:empty?)
-      (parts.length - 1).downto(0) do |i|
-        partial_path = "/#{parts[0..i].join("/")}"
-        return line_map[partial_path] if line_map[partial_path]
-      end
-
-      # For paths like /resolutions/0/actions/0/type, try to find the specific action
-      if parts.length >= 4 && parts[0] == "resolutions" && parts[2] == "actions"
-        # Try to find the specific action line
-        resolution_index = parts[1]
-        action_index = parts[3]
-        parts[4] if parts.length > 4
-
-        # Look for patterns like /resolutions/0/actions/0
-        action_path = "/resolutions/#{resolution_index}/actions/#{action_index}"
-        return line_map[action_path] if line_map[action_path]
-
-        # Look for the actions array start
-        actions_path = "/resolutions/#{resolution_index}/actions"
-        return line_map[actions_path] if line_map[actions_path]
-      end
-
-      # Try to find the closest match by looking for the last non-numeric part
-      if parts.any?
-        parts.reverse.each do |part|
-          next if part.match?(/^\d+$/) # Skip array indices
-
-          line_map.each do |path, line|
-            return line if path.end_with?("/#{part}")
+    # 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
 
-      # Default to line 1
-      1
-    end
-
-    def build_error_message(error)
-      type = error["type"]
-      details = error["details"] || {}
-      data_pointer = error["data_pointer"] || ""
+      # @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?
 
-      base_message = case type
-                     when "required"
-                       missing = details["missing_keys"] || []
-                       if missing.length == 1
-                         "object is missing required property: #{missing.first}"
-                       else
-                         "object is missing required properties: #{missing.join(", ")}"
-                       end
-                     when "additionalProperties"
-                       extra = details["extra_keys"] || []
-                       if extra.length == 1
-                         "object property '#{extra.first}' is a disallowed additional property"
-                       else
-                         "object properties #{extra.map do |k|
-                           "'#{k}'"
-                         end.join(", ")} are disallowed additional properties"
-                       end
-                     when "enum"
-                       value = details["value"]
-                       valid_values = details["valid_values"] || []
-                       "value '#{value}' is not one of: #{valid_values}"
-                     when "type"
-                       details["actual_type"]
-                       expected = details["expected_types"] || []
-                       "value is not #{expected.join(" or ")}"
-                     else
-                       error["error"] || "validation failed"
-                     end
+        match_key = line_map.keys
+                            .select { |path| pointer.start_with?(path) || path.start_with?(pointer) }
+                            .max_by(&:length)
 
-      # Add data pointer for debugging if it's not empty
-      if !data_pointer.empty?
-        "#{base_message} at `#{data_pointer}`"
-      else
-        base_message
+        match_key ? [line_map[match_key], 1] : [1, 1]
       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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+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 :prefix, :string
+    attribute :number, :string
+
+    key_value do
+      map "prefix", to: :prefix
+      map "number", to: :number
+    end
+  end
+end

data/lib/edoxen/url.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-
 module Edoxen
+  # URL with a kind (access / report) and an optional format hint (pdf, html).
   class Url < Lutaml::Model::Serializable
-    attribute :kind, :string, values: %w[access report]
+    attribute :kind, :string, values: Enums::URL_KIND
     attribute :ref, :string
     attribute :format, :string
 

data/lib/edoxen/version.rb

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

data/lib/edoxen.rb

@@ -1,23 +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/metadata"
-  require_relative "edoxen/resolution"
-  require_relative "edoxen/resolution_set"
-  require_relative "edoxen/cli"
+  # 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