edoxen 0.1.2 → 0.3.0

data/lib/edoxen/_metadata.rb.deprecated

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "resolution_date"
+require_relative "url"
+require_relative "localization"
+
+module Edoxen
+  # A per-language source-URL record. Carries the URL ref, its format
+  # (pdf, html, ...), and the language_code (ISO 639-3) for which the
+  # URL is the canonical source.
+  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
+
+  class Metadata < Lutaml::Model::Serializable
+    attribute :title, :string
+    attribute :identifier, :string
+    attribute :dates, ResolutionDate, collection: true
+    attribute :source, :string
+    attribute :venue, :string
+    attribute :chair, :string
+    attribute :urls, Url, collection: true
+
+    # OIML extensions — see TODO.complete/14 for the glossarist-style
+    # i18n model. `title_localized` carries the per-language title
+    # parallel to Resolution#localizations. `source_urls` carries the
+    # per-language PDF URLs. `city`/`country_code` carry the IATA /
+    # ISO 3166-1 alpha-2 codes for the host venue.
+    attribute :title_localized, Localization, collection: true
+    attribute :source_urls, SourceUrl, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+
+    key_value do
+      map "title", to: :title
+      map "identifier", to: :identifier
+      map "dates", to: :dates
+      map "source", to: :source
+      map "venue", to: :venue
+      map "chair", to: :chair
+      map "urls", to: :urls
+      map "title_localized", to: :title_localized
+      map "source_urls", to: :source_urls
+      map "city", to: :city
+      map "country_code", to: :country_code
+    end
+  end
+end

data/lib/edoxen/action.rb

@@ -1,32 +1,17 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-require_relative "resolution_date"
-
 module Edoxen
+  # Verb + one effective date + human-readable message. Used inside a
+  # Localization to express the multilingual part of an action.
   class Action < Lutaml::Model::Serializable
-    ACTION_TYPE_ENUM = %w[
-      accepts acknowledges adoption adopts agrees allocates appoints appreciates
-      appreciation approves asks assigns chairs communicating confirms consults considers
-      creates decides defines delegates delivering directs disbands drafting elects
-      empowers encourages endorses estabilishes establishes gathering identifies
-      instructs investigates notes notifies recognises nominates
-      recognizes recommends registers regrets request requests resolves restates reminds replaces
-      scopes secures sends supports thanks welcomes withdraws
-    ].freeze
-
-    attribute :type, :string, values: ACTION_TYPE_ENUM
-    attribute :dates, ResolutionDate, collection: true
+    attribute :type, :string, values: Enums::ACTION_TYPE
+    attribute :date_effective, ResolutionDate
     attribute :message, :string
-    attribute :subject, :string
-    attribute :degree, :string
 
     key_value do
       map "type", to: :type
+      map "date_effective", to: :date_effective
       map "message", to: :message
-      map "subject", to: :subject
-      map "degree", to: :degree
-      map "dates", to: :dates
     end
   end
 end

data/lib/edoxen/approval.rb

@@ -1,22 +1,18 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-require_relative "resolution_date"
-
 module Edoxen
+  # Approval record: type (affirmative / negative), degree (consensus level),
+  # date of the approval event, and a human-readable elaboration.
   class Approval < Lutaml::Model::Serializable
-    APPROVAL_TYPE_ENUM = %w[affirmative negative].freeze
-    APPROVAL_DEGREE_ENUM = %w[unanimous majority minority].freeze
-
-    attribute :type, :string, values: APPROVAL_TYPE_ENUM
-    attribute :degree, :string, values: APPROVAL_DEGREE_ENUM
-    attribute :dates, ResolutionDate, collection: true
+    attribute :type, :string, values: Enums::APPROVAL_TYPE
+    attribute :degree, :string, values: Enums::APPROVAL_DEGREE
+    attribute :date, ResolutionDate
     attribute :message, :string
 
     key_value do
       map "type", to: :type
       map "degree", to: :degree
-      map "dates", to: :dates
+      map "date", to: :date
       map "message", to: :message
     end
   end

data/lib/edoxen/cli.rb

@@ -2,14 +2,26 @@
 
 require "thor"
 require "fileutils"
-require_relative "schema_validator"
 
 module Edoxen
+  # Thor command-line surface for the gem. Two responsibilities:
+  #   * `validate PATTERN` — runs both JSON-Schema validation and the
+  #     Ruby model parser against each matching YAML file.
+  #   * `normalize PATTERN (--output DIR | --inplace)` — round-trips each
+  #     matching YAML file through the Ruby model, preserving any
+  #     `# yaml-language-server: $schema=...` directive on the first line.
+  #
+  # The CLI deliberately does NOT own schema-or-model decisions — those
+  # live in `SchemaValidator` and `Lutaml::Model` respectively. It only
+  # glues them together and formats output.
   class Cli < Thor
-    desc "validate YAML_FILE_PATTERN", "Validate YAML files against Edoxen schema"
-    def validate(pattern)
-      files = expand_pattern(pattern)
+    package_name "edoxen"
+
+    desc "validate YAML_FILE_PATTERN",
+         "Validate one or more Edoxen YAML files against the schema and the model."
 
+    def validate(pattern)
+      files = expand_yaml_pattern(pattern)
       if files.empty?
         say "No files found matching pattern: #{pattern}", :red
         exit 1
@@ -24,17 +36,8 @@ module Edoxen
       files.each do |file|
         print "  #{File.basename(file)}... "
 
-        # Schema validation
         schema_errors = validator.validate_file(file)
-
-        # Model parsing validation
-        model_errors = []
-        begin
-          content = File.read(file)
-          Edoxen::ResolutionSet.from_yaml(content)
-        rescue StandardError => e
-          model_errors << "Model parsing failed: #{e.message}"
-        end
+        model_errors = collect_model_errors(file)
 
         if schema_errors.empty? && model_errors.empty?
           say "✅ VALID", :green
@@ -42,36 +45,21 @@ module Edoxen
         else
           say "❌ INVALID", :red
           invalid_count += 1
-
-          # Show schema validation errors with clickable links
-          unless schema_errors.empty?
-            say "    Schema Validation Errors:", :red
-            schema_errors.each do |error|
-              say "      #{error.to_clickable_format}", :red
-            end
-          end
-
-          # Show model parsing errors
-          unless model_errors.empty?
-            say "    Model Parsing Errors:", :red
-            model_errors.each do |error|
-              say "      #{file}:1:1: #{error}", :red
-            end
-          end
+          schema_errors.each { |e| say "    #{e.to_clickable_format}", :red }
+          model_errors.each { |m| say "    #{file}:1:1: #{m}", :red }
         end
       end
 
-      say "\n📊 Validation Summary:", :blue
-      say "  Valid files: #{valid_count}", :green
-      say "  Invalid files: #{invalid_count}", invalid_count.positive? ? :red : :green
-      say "  Success rate: #{((valid_count.to_f / files.size) * 100).round(1)}%", :blue
-
+      print_summary(files.size, valid_count, invalid_count, validator_type: :binary)
       exit(invalid_count.positive? ? 1 : 0)
     end
 
-    desc "normalize YAML_FILE_PATTERN", "Normalize YAML files using Edoxen schema"
+    desc "normalize YAML_FILE_PATTERN",
+         "Round-trip YAML file(s) through the Edoxen model (--output DIR or --inplace)."
+
     option :output, type: :string, desc: "Output directory for normalized files"
     option :inplace, type: :boolean, desc: "Modify files in place (no backup)"
+
     def normalize(pattern)
       if options[:output] && options[:inplace]
         say "Error: Cannot use both --output and --inplace options", :red
@@ -83,8 +71,7 @@ module Edoxen
         exit 1
       end
 
-      files = expand_pattern(pattern)
-
+      files = expand_yaml_pattern(pattern)
       if files.empty?
         say "No files found matching pattern: #{pattern}", :red
         exit 1
@@ -97,77 +84,73 @@ module Edoxen
 
       files.each do |file|
         print "  #{File.basename(file)}... "
-
         begin
-          # Load and parse the file
-          content = File.read(file)
-
-          # Extract yaml-language-server comment if present
-          yaml_language_server_comment = extract_yaml_language_server_comment(content)
-
-          resolution_set = Edoxen::ResolutionSet.from_yaml(content)
-
-          # Normalize by serializing back to YAML
-          normalized_yaml = resolution_set.to_yaml
-
-          # Prepend the yaml-language-server comment if it was present
-          normalized_yaml = "#{yaml_language_server_comment}\n#{normalized_yaml}" if yaml_language_server_comment
+          yaml_language_server_comment = extract_yaml_language_server_comment(File.read(file))
+          normalized = ResolutionCollection.from_yaml(File.read(file)).to_yaml
+          normalized = "#{yaml_language_server_comment}\n#{normalized}" if yaml_language_server_comment
 
           if options[:inplace]
-            # Write directly to the original file
-            File.write(file, normalized_yaml)
+            File.write(file, normalized)
             say "✅ NORMALIZED", :green
           else
-            # Write to output directory
-            output_file = File.join(options[:output], File.basename(file))
-            FileUtils.mkdir_p(File.dirname(output_file))
-            File.write(output_file, normalized_yaml)
-            say "✅ NORMALIZED → #{output_file}", :green
+            out = File.join(options[:output], File.basename(file))
+            FileUtils.mkdir_p(File.dirname(out))
+            File.write(out, normalized)
+            say "✅ NORMALIZED → #{out}", :green
           end
-
           success_count += 1
         rescue StandardError => e
-          say "❌ FAILED", :red
-          say "    Error: #{e.message}", :red
+          say "❌ FAILED — #{e.message}", :red
           error_count += 1
         end
       end
 
-      say "\n📊 Normalization Summary:", :blue
-      say "  Successful: #{success_count}", :green
-      say "  Failed: #{error_count}", error_count.positive? ? :red : :green
-      say "  Success rate: #{((success_count.to_f / files.size) * 100).round(1)}%", :blue
-
-      if options[:output]
-        say "  Output directory: #{options[:output]}", :blue
-      elsif options[:inplace]
-        say "  Files modified in place", :yellow
-      end
-
+      print_summary(files.size, success_count, error_count, validator_type: :lax,
+                                                            extra: [
+                                                              ["  Output directory", options[:output]],
+                                                              ["  Mode", options[:inplace] ? "in place" : "--output"]
+                                                            ].compact)
       exit(error_count.positive? ? 1 : 0)
     end
 
+    no_commands do
+      # Reserved for private Thor plumbing if we add it later.
+    end
+
     private
 
-    def expand_pattern(pattern)
-      # Handle glob patterns
-      files = Dir.glob(pattern).select { |f| File.file?(f) }
+    def expand_yaml_pattern(pattern)
+      Dir.glob(pattern).select { |f| File.file?(f) && f.match?(/\.ya?ml\z/i) }.sort
+    end
 
-      # Filter for YAML files
-      files.select { |f| f.match?(/\.(ya?ml)$/i) }.sort
+    # Round-trip the file through the model to catch structural issues
+    # (missing nested classes, type mismatches) that the JSON-Schema can't
+    # express. The model is permissive about field names — schema is the
+    # strict source.
+    def collect_model_errors(file)
+      ResolutionCollection.from_yaml(File.read(file))
+      []
+    rescue StandardError => e
+      ["Model parsing failed: #{e.message}"]
     end
 
     def extract_yaml_language_server_comment(content)
-      lines = content.split("\n")
-
-      # Look for yaml-language-server comment in the first few lines
-      lines.first(5).each do |line|
-        if line.strip.match?(/^#\s*yaml-language-server:\s*\$schema=/)
-          return line.rstrip # Only strip trailing whitespace, keep the #
-        end
-      end
+      lines = content.split("\n").first(5)
+      lines.find { |l| l.strip.match?(/\A#\s*yaml-language-server:\s*\$schema=/) }&.rstrip
+    end
 
-      nil
+    def print_summary(total, ok_count, bad_count, validator_type:, extra: [])
+      say "\n📊 Summary:", :blue
+      say "  Total: #{total}", :blue
+      label_text = if validator_type == :binary
+                     "  Valid: #{ok_count}, Invalid: #{bad_count}"
+                   else
+                     "  Success: #{ok_count}, Failed: #{bad_count}"
+                   end
+      say label_text, bad_count.positive? ? :red : :green
+      success_rate = total.zero? ? 0 : ((ok_count.to_f / total) * 100).round(1)
+      say "  Success rate: #{success_rate}%", :blue
+      extra.each { |label, value| say "  #{label}: #{value}", :blue }
     end
   end
 end

data/lib/edoxen/consideration.rb

@@ -1,25 +1,17 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-require_relative "resolution_date"
-
 module Edoxen
+  # Basis for a resolution: a verb (having, noting, considering, ...) plus
+  # one effective date and the elaborated reasoning.
   class Consideration < Lutaml::Model::Serializable
-    CONSIDERATION_TYPE_ENUM = %w[
-      acknowledging basing considering identifying noting recalling recognises according following
-      recognising recognizing
-    ].freeze
-
-    attribute :type, :string, values: CONSIDERATION_TYPE_ENUM
-    attribute :dates, ResolutionDate, collection: true
+    attribute :type, :string, values: Enums::CONSIDERATION_TYPE
+    attribute :date_effective, ResolutionDate
     attribute :message, :string
-    attribute :subject, :string
 
     key_value do
       map "type", to: :type
-      map "dates", to: :dates
+      map "date_effective", to: :date_effective
       map "message", to: :message
-      map "subject", to: :subject
     end
   end
 end

data/lib/edoxen/enums.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Single source of truth for every enum used by the Edoxen information model.
+  #
+  # Mirrors ../edoxen-model/models/*.lutaml, deduped.
+  # Both:
+  #   * Ruby model attribute declarations (`attribute :type, :string, values: Enums::ACTION_TYPE`)
+  #   * JSON-Schema (`schema/edoxen.yaml`)
+  # reference these constants.
+  #
+  # The schema <-> Ruby enum-sync spec asserts the YAML schema's enum arrays
+  # equal these arrays. If you change a constant here, change the schema in
+  # the same PR.
+  module Enums
+    ACTION_TYPE = %w[
+      adopts thanks approves decides declares asks invites
+      resolves confirms welcomes recommends requests congratulates
+      instructs urges appoints calls-upon encourages affirms elects
+      authorizes charges states remarks judges sanctions abrogates empowers
+    ].freeze
+
+    CONSIDERATION_TYPE = %w[
+      having noting recognizing acknowledging recalling reaffirming
+      considering taking-into-account pursuant-to bearing-in-mind
+      emphasizing concerned accepts observing referring acting empowers
+    ].freeze
+
+    RESOLUTION_TYPE = %w[resolution recommendation decision declaration].freeze
+
+    RESOLUTION_RELATION_TYPE = %w[
+      annexOf hasAnnex updates refines replaces considers
+    ].freeze
+
+    RESOLUTION_DATE_TYPE = %w[adoption drafted discussed].freeze
+
+    APPROVAL_TYPE = %w[affirmative negative].freeze
+
+    APPROVAL_DEGREE = %w[unanimous majority minority].freeze
+
+    URL_KIND = %w[access report].freeze
+  end
+end

data/lib/edoxen/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Base class for any Edoxen-level error. Reserved for raise-on-failure paths;
+  # schema validation errors live under SchemaValidator::ValidationError.
+  class Error < StandardError; end
+end

data/lib/edoxen/localization.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A monolingual rendering of a Resolution. Mirrors the glossarist
+  # LocalizedConcept pattern: language-agnostic fields live on the
+  # parent Resolution; per-language content lives here.
+  class Localization < Lutaml::Model::Serializable
+    attribute :language_code, :string
+    attribute :script, :string
+    attribute :title, :string
+    attribute :subject, :string
+    attribute :message, :string
+    attribute :considering, :string
+    attribute :considerations, Consideration, collection: true
+    attribute :approvals, Approval, collection: true
+    attribute :actions, Action, collection: true
+
+    key_value do
+      map "language_code", to: :language_code
+      map "script", to: :script
+      map "title", to: :title
+      map "subject", to: :subject
+      map "message", to: :message
+      map "considering", to: :considering
+      map "considerations", to: :considerations
+      map "approvals", to: :approvals
+      map "actions", to: :actions
+    end
+  end
+end

data/lib/edoxen/meeting_identifier.rb

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 
-# MeetingIdentifier {
-#   venue: String
-#   date: DateTime
-# }
-require "lutaml/model"
-
 module Edoxen
+  # Identifier of a meeting (venue + date). Singular — the meeting a
+  # particular Resolution belongs to.
   class MeetingIdentifier < Lutaml::Model::Serializable
     attribute :venue, :string
     attribute :date, :date

data/lib/edoxen/resolution.rb

@@ -1,47 +1,34 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-require_relative "resolution_date"
-require_relative "consideration"
-require_relative "approval"
-require_relative "action"
-require_relative "meeting_identifier"
-require_relative "resolution_relation"
-
 module Edoxen
+  # A formal Resolution. Language-agnostic admin fields live here; every
+  # translatable field is wrapped inside `localizations[]` (one entry per
+  # available language; at least one is required by the schema).
   class Resolution < Lutaml::Model::Serializable
-    RESOLUTION_TYPE_ENUM = %w[resolution recommendation decision declaration].freeze
-
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :type, :string, values: Enums::RESOLUTION_TYPE
+    attribute :doi, :string
+    attribute :urn, :string
+    attribute :agenda_item, :string
     attribute :dates, ResolutionDate, collection: true
-    attribute :subject, :string
-    attribute :title, :string
-    attribute :type, :string, values: RESOLUTION_TYPE_ENUM
-    attribute :identifier, :string
-    attribute :message, :string
-    attribute :considering, :string
-    attribute :considerations, Consideration, collection: true
-    attribute :approvals, Approval, collection: true
-    attribute :actions, Action, collection: true
-    attribute :meeting_identifier, MeetingIdentifier
-    attribute :relations, ResolutionRelation, collection: true
     attribute :categories, :string, collection: true
+    attribute :meeting, MeetingIdentifier
+    attribute :relations, ResolutionRelation, collection: true
     attribute :urls, Url, collection: true
+    attribute :localizations, Localization, collection: true
 
     key_value do
-      map "dates", to: :dates
-      map "subject", to: :subject
-      map "title", to: :title
-      map "type", to: :type
       map "identifier", to: :identifier
-      map "message", to: :message
-      map "considering", to: :considering
-      map "considerations", to: :considerations
-      map "approvals", to: :approvals
-      map "actions", to: :actions
-      map "meeting_identifier", to: :meeting_identifier
-      map "relations", to: :relations
+      map "type", to: :type
+      map "doi", to: :doi
+      map "urn", to: :urn
+      map "agenda_item", to: :agenda_item
+      map "dates", to: :dates
       map "categories", to: :categories
+      map "meeting", to: :meeting
+      map "relations", to: :relations
       map "urls", to: :urls
+      map "localizations", to: :localizations
     end
   end
 end

data/lib/edoxen/resolution_collection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Top-level container for a published resolution collection: metadata
+  # plus the list of resolutions.
+  class ResolutionCollection < Lutaml::Model::Serializable
+    attribute :metadata, ResolutionMetadata
+    attribute :resolutions, Resolution, collection: true
+
+    key_value do
+      map "metadata", to: :metadata
+      map "resolutions", to: :resolutions
+    end
+  end
+end

data/lib/edoxen/resolution_date.rb

@@ -1,17 +1,16 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-
 module Edoxen
+  # Date with semantic kind (adoption, drafted, discussed).
+  # ResolutionDate is the only carrier of a *typed* date in the model —
+  # plain `Date` in lutaml-model has no semantic context.
   class ResolutionDate < Lutaml::Model::Serializable
-    attribute :start, :date
-    attribute :end, :date
-    attribute :kind, :string, values: %w[ballot enactment effective decision meeting]
+    attribute :date, :date
+    attribute :type, :string, values: Enums::RESOLUTION_DATE_TYPE
 
     key_value do
-      map "start", to: :start
-      map "end", to: :end
-      map "kind", to: :kind
+      map "date", to: :date
+      map "type", to: :type
     end
   end
 end

data/lib/edoxen/resolution_metadata.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Collection-level metadata: the title (string for default / single-language
+  # collections, or `title_localized[]` for multilingual), the meeting date,
+  # the source secretariat, per-language source PDFs, and the host venue.
+  class ResolutionMetadata < Lutaml::Model::Serializable
+    attribute :title, :string
+    attribute :title_localized, Localization, collection: true
+    attribute :date, :date
+    attribute :source, :string
+    attribute :source_urls, SourceUrl, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+
+    key_value do
+      map "title", to: :title
+      map "title_localized", to: :title_localized
+      map "date", to: :date
+      map "source", to: :source
+      map "source_urls", to: :source_urls
+      map "city", to: :city
+      map "country_code", to: :country_code
+    end
+  end
+end

data/lib/edoxen/resolution_relation.rb

@@ -1,46 +1,12 @@
 # frozen_string_literal: true
 
-# class ResolutionRelation {
-#   source: StructuredIdentifier (Resolution)
-#   destination: StructuredIdentifier (Resolution)
-#   type: ResolutionRelationType
-# }
-
-# enum ResolutionRelationType {
-#   annexOf {
-#     This resolution is an annex to the target resolution.
-#   }
-
-#   hasAnnex {
-#     The target resolution is an annex of the source resolution.
-#   }
-
-#   updates {
-#     This resolution updates the target resolution.
-#   }
-
-#   refines {
-#     This resolution refines the target resolution.
-#   }
-
-#   replaces/obsoletes {
-#     This resolution replaces/obsoletes the target resolution.
-#   }
-
-#   considers {
-#     This resolution is made in consideration of the target resolution.
-#   }
-# }
-
-require "lutaml/model"
-
 module Edoxen
+  # Directed relation between two resolutions, identified by their
+  # StructuredIdentifier (prefix + number).
   class ResolutionRelation < Lutaml::Model::Serializable
-    RESOLUTION_RELATIONSHIP_ENUM = %w[annexOf hasAnnex updates refines replaces obsoletes considers].freeze
-
-    attribute :source, :string
-    attribute :destination, :string
-    attribute :type, :string, values: RESOLUTION_RELATIONSHIP_ENUM
+    attribute :source, StructuredIdentifier
+    attribute :destination, StructuredIdentifier
+    attribute :type, :string, values: Enums::RESOLUTION_RELATION_TYPE
 
     key_value do
       map "source", to: :source