edoxen 0.1.2 → 0.3.1

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,11 @@
 # 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 "message", to: :message
-      map "subject", to: :subject
-      map "degree", to: :degree
-      map "dates", to: :dates
-    end
   end
 end

data/lib/edoxen/approval.rb

@@ -1,23 +1,12 @@
 # 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 "message", to: :message
-    end
   end
 end

data/lib/edoxen/cli.rb

@@ -2,172 +2,180 @@
 
 require "thor"
 require "fileutils"
-require_relative "schema_validator"
 
 module Edoxen
   class Cli < Thor
-    desc "validate YAML_FILE_PATTERN", "Validate YAML files against Edoxen schema"
-    def validate(pattern)
-      files = expand_pattern(pattern)
+    # Deep module behind the per-command interface. Owns the
+    # expand/sort/empty/header/loop/tally/summary/exit scaffold so
+    # `validate` and `normalize` collapse to per-file blocks.
+    #
+    # Commands call `Batch.run(self, pattern, header:)` and yield a block
+    # that returns `Result.ok(message)` or `Result.bad(errors)`. The
+    # batch runner prints progress, tallies, prints the summary, and
+    # exits with the right code.
+    #
+    # In-process; no adapter. The seam is the call site in each
+    # command method — internal to the CLI.
+    module Batch
+      # Per-file outcome. `ok` carries an optional message appended to
+      # the success indicator (e.g. "NORMALIZED → /out/path"). `bad`
+      # carries a list of pre-formatted error strings.
+      Result = Struct.new(:status, :message, :errors) do
+        def self.ok(message = nil)
+          new(:ok, message, nil)
+        end
 
-      if files.empty?
-        say "No files found matching pattern: #{pattern}", :red
-        exit 1
+        def self.bad(errors)
+          new(:bad, nil, Array(errors))
+        end
       end
 
-      say "🔍 Validating #{files.size} file(s)...", :blue
-
-      validator = SchemaValidator.new
-      valid_count = 0
-      invalid_count = 0
-
-      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}"
+      module_function
+
+      # Run a batch over every YAML file matching `pattern`.
+      #
+      # Yields each file path to the caller's block. Block must return
+      # a Batch::Result. The batch runner handles progress output,
+      # tallies, summary, and the exit code.
+      def run(cli, pattern, header:, summary_extra: [])
+        files = expand(pattern)
+        if files.empty?
+          cli.say "No files found matching pattern: #{pattern}", :red
+          exit 1
         end
 
-        if schema_errors.empty? && model_errors.empty?
-          say "✅ VALID", :green
-          valid_count += 1
-        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
+        cli.say "#{header} #{files.size} file(s)...", :blue
+
+        ok_count = 0
+        bad_count = 0
 
-          # 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
+        files.each do |file|
+          $stdout.print "  #{File.basename(file)}... "
+          result = yield file
+          if result.status == :ok
+            label = result.message ? "✅ #{result.message}" : "✅"
+            cli.say label, :green
+            ok_count += 1
+          else
+            cli.say "❌ INVALID", :red
+            bad_count += 1
+            Array(result.errors).each { |e| cli.say "    #{e}", :red }
           end
         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
-
-      exit(invalid_count.positive? ? 1 : 0)
-    end
 
-    desc "normalize YAML_FILE_PATTERN", "Normalize YAML files using Edoxen schema"
-    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
-        exit 1
+        print_summary(cli, files.size, ok_count, bad_count, summary_extra)
+        exit(bad_count.positive? ? 1 : 0)
       end
 
-      unless options[:output] || options[:inplace]
-        say "Error: Must specify either --output or --inplace option", :red
-        exit 1
+      def expand(pattern)
+        Dir.glob(pattern).select { |f| File.file?(f) && f.match?(/\.ya?ml\z/i) }.sort
       end
 
-      files = expand_pattern(pattern)
-
-      if files.empty?
-        say "No files found matching pattern: #{pattern}", :red
-        exit 1
+      def print_summary(cli, total, ok_count, bad_count, summary_extra)
+        cli.say "\n📊 Summary:", :blue
+        cli.say "  Total: #{total}", :blue
+        cli.say "  Success: #{ok_count}, Failed: #{bad_count}",
+                bad_count.positive? ? :red : :green
+        rate = total.zero? ? 0 : ((ok_count.to_f / total) * 100).round(1)
+        cli.say "  Success rate: #{rate}%", :blue
+        summary_extra.each { |label, value| cli.say "  #{label}: #{value}", :blue }
       end
+    end
 
-      say "🔄 Normalizing #{files.size} file(s)...", :blue
-
-      success_count = 0
-      error_count = 0
-
-      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)
+    package_name "edoxen"
 
-          resolution_set = Edoxen::ResolutionSet.from_yaml(content)
+    desc "validate YAML_FILE_PATTERN",
+         "Validate one or more Edoxen YAML files against the schema and the model."
 
-          # Normalize by serializing back to YAML
-          normalized_yaml = resolution_set.to_yaml
+    def validate(pattern)
+      validator = SchemaValidator.new
+      Batch.run(self, pattern, header: "🔍 Validating") do |file|
+        schema_errors = validator.validate_file(file)
+        model_errors = collect_model_errors(file)
+        if schema_errors.empty? && model_errors.empty?
+          Batch::Result.ok("VALID")
+        else
+          errors = (schema_errors + model_errors).map(&:to_clickable_format)
+          Batch::Result.bad(errors)
+        end
+      end
+    end
 
-          # Prepend the yaml-language-server comment if it was present
-          normalized_yaml = "#{yaml_language_server_comment}\n#{normalized_yaml}" if yaml_language_server_comment
+    desc "normalize YAML_FILE_PATTERN",
+         "Round-trip YAML file(s) through the Edoxen model (--output DIR or --inplace)."
 
-          if options[:inplace]
-            # Write directly to the original file
-            File.write(file, normalized_yaml)
-            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
-          end
+    option :output, type: :string, desc: "Output directory for normalized files"
+    option :inplace, type: :boolean, desc: "Modify files in place (no backup)"
 
-          success_count += 1
-        rescue StandardError => e
-          say "❌ FAILED", :red
-          say "    Error: #{e.message}", :red
-          error_count += 1
-        end
+    def normalize(pattern)
+      unless valid_normalize_options?
+        say normalize_options_error, :red
+        exit 1
       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
+      summary_extra = [
+        ["  Output directory", options[:output]],
+        ["  Mode", options[:inplace] ? "in place" : "--output"]
+      ].compact
 
-      if options[:output]
-        say "  Output directory: #{options[:output]}", :blue
-      elsif options[:inplace]
-        say "  Files modified in place", :yellow
+      Batch.run(self, pattern, header: "🔄 Normalizing", summary_extra: summary_extra) do |file|
+        Batch::Result.ok(normalize_file(file))
+      rescue StandardError => e
+        Batch::Result.bad(["#{file}:1:1: #{e.message}"])
       end
-
-      exit(error_count.positive? ? 1 : 0)
     end
 
     private
 
-    def expand_pattern(pattern)
-      # Handle glob patterns
-      files = Dir.glob(pattern).select { |f| File.file?(f) }
-
-      # Filter for YAML files
-      files.select { |f| f.match?(/\.(ya?ml)$/i) }.sort
+    def collect_model_errors(file)
+      ResolutionCollection.from_yaml(File.read(file))
+      []
+    rescue StandardError => e
+      [Edoxen::ValidationError.new(
+        file: file, line: 1, column: 1,
+        message_text: "Model parsing failed: #{e.message}",
+        source: Edoxen::ValidationError::SOURCE_MODEL
+      )]
     end
 
     def extract_yaml_language_server_comment(content)
-      lines = content.split("\n")
+      lines = content.split("\n").first(5)
+      lines.find { |l| l.strip.match?(/\A#\s*yaml-language-server:\s*\$schema=/) }&.rstrip
+    end
 
-      # 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
+    def valid_normalize_options?
+      return false if options[:output] && options[:inplace]
+      return false unless options[:output] || options[:inplace]
+
+      true
+    end
+
+    def normalize_options_error
+      if options[:output] && options[:inplace]
+        "Error: Cannot use both --output and --inplace options"
+      else
+        "Error: Must specify either --output or --inplace option"
       end
+    end
 
-      nil
+    # Writes the normalized YAML either to the original file (--inplace)
+    # or under the --output directory. Returns a one-line status message
+    # for the batch runner to print after the ✅.
+    def normalize_file(file)
+      original = File.read(file)
+      yaml_language_server_comment = extract_yaml_language_server_comment(original)
+      normalized = ResolutionCollection.from_yaml(original).to_yaml
+      normalized = "#{yaml_language_server_comment}\n#{normalized}" if yaml_language_server_comment
+
+      if options[:inplace]
+        File.write(file, normalized)
+        "NORMALIZED"
+      else
+        out = File.join(options[:output], File.basename(file))
+        FileUtils.mkdir_p(File.dirname(out))
+        File.write(out, normalized)
+        "NORMALIZED → #{out}"
+      end
     end
   end
 end

data/lib/edoxen/consideration.rb

@@ -1,25 +1,11 @@
 # 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 "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,37 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Base class for any Edoxen-level error. Reserved for raise-on-failure paths.
+  class Error < StandardError; end
+
+  # Unified validation failure shape. Produced by both:
+  #   * SchemaValidator — JSON-Schema violations and YAML syntax errors
+  #     carry source: :schema (or :syntax for Psych::SyntaxError).
+  #   * ResolutionCollection.from_yaml rescues in the CLI — model parse
+  #     failures carry source: :model.
+  #
+  # One type at the seam means callers (CLI, future renderers, tests)
+  # handle one shape instead of N.
+  class ValidationError < Error
+    SOURCE_SCHEMA = :schema
+    SOURCE_MODEL = :model
+    SOURCE_SYNTAX = :syntax
+
+    attr_reader :file, :line, :column, :pointer, :message_text, :source
+
+    def initialize(file:, line:, column:, message_text:, pointer: "", source: SOURCE_SCHEMA)
+      @file = file
+      @line = line
+      @column = column
+      @pointer = pointer.to_s
+      @message_text = message_text
+      @source = source
+      super(to_clickable_format)
+    end
+
+    def to_clickable_format
+      suffix = @pointer.empty? ? "" : " at `#{@pointer}`"
+      "#{@file}:#{@line}:#{@column}: #{@message_text}#{suffix}"
+    end
+  end
+end

data/lib/edoxen/localization.rb

@@ -0,0 +1,18 @@
+# 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
+  end
+end

data/lib/edoxen/meeting_identifier.rb

@@ -1,19 +1,10 @@
 # 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
-
-    key_value do
-      map "venue", to: :venue
-      map "date", to: :date
-    end
   end
 end

data/lib/edoxen/resolution.rb

@@ -1,47 +1,43 @@
 # 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).
+  #
+  # Wire names follow lutaml-model's default convention: each declared
+  # attribute serializes to its snake_case name on the wire. Override
+  # with an explicit `key_value do; map "wire", to: :attr; end` block
+  # only when the wire name differs.
   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
+
+    # Lookup by ISO 639-3 language code. Returns nil when no exact match
+    # exists and `fallback:` is false (the default); returns the first
+    # localization otherwise. Keeps the language-preference policy in
+    # one place so callers stop reimplementing `find { |l| ... }`.
+    def in_language(code, fallback: false)
+      match = localizations&.find { |loc| loc.language_code == code.to_s }
+      return match if match
+
+      fallback ? localizations&.first : nil
+    end
 
-    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 "categories", to: :categories
-      map "urls", to: :urls
+    # The canonical rendering — English when available, else the first
+    # declared localization. Mirrors the glossarist LocalizedConcept
+    # "preferred language" notion.
+    def primary_localization
+      in_language("eng", fallback: true)
     end
   end
 end