edoxen 0.3.0 → 0.5.0

data/lib/edoxen/cli.rb

@@ -4,54 +4,101 @@ require "thor"
 require "fileutils"
 
 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
-    package_name "edoxen"
+    # 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
 
-    desc "validate YAML_FILE_PATTERN",
-         "Validate one or more Edoxen YAML files against the schema and the model."
+        def self.bad(errors)
+          new(:bad, nil, Array(errors))
+        end
+      end
 
-    def validate(pattern)
-      files = expand_yaml_pattern(pattern)
-      if files.empty?
-        say "No files found matching pattern: #{pattern}", :red
-        exit 1
+      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
+
+        cli.say "#{header} #{files.size} file(s)...", :blue
+
+        ok_count = 0
+        bad_count = 0
+
+        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
+
+        print_summary(cli, files.size, ok_count, bad_count, summary_extra)
+        exit(bad_count.positive? ? 1 : 0)
       end
 
-      say "🔍 Validating #{files.size} file(s)...", :blue
+      def expand(pattern)
+        Dir.glob(pattern).select { |f| File.file?(f) && f.match?(/\.ya?ml\z/i) }.sort
+      end
 
-      validator = SchemaValidator.new
-      valid_count = 0
-      invalid_count = 0
+      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
 
-      files.each do |file|
-        print "  #{File.basename(file)}... "
+    package_name "edoxen"
 
+    desc "validate YAML_FILE_PATTERN",
+         "Validate one or more Edoxen YAML files against the schema and the model."
+
+    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?
-          say "✅ VALID", :green
-          valid_count += 1
+          Batch::Result.ok("VALID")
         else
-          say "❌ INVALID", :red
-          invalid_count += 1
-          schema_errors.each { |e| say "    #{e.to_clickable_format}", :red }
-          model_errors.each { |m| say "    #{file}:1:1: #{m}", :red }
+          errors = (schema_errors + model_errors).map(&:to_clickable_format)
+          Batch::Result.bad(errors)
         end
       end
-
-      print_summary(files.size, valid_count, invalid_count, validator_type: :binary)
-      exit(invalid_count.positive? ? 1 : 0)
     end
 
     desc "normalize YAML_FILE_PATTERN",
@@ -61,77 +108,103 @@ module Edoxen
     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
+      unless valid_normalize_options?
+        say normalize_options_error, :red
         exit 1
       end
 
-      unless options[:output] || options[:inplace]
-        say "Error: Must specify either --output or --inplace option", :red
-        exit 1
-      end
+      summary_extra = [
+        ["  Output directory", options[:output]],
+        ["  Mode", options[:inplace] ? "in place" : "--output"]
+      ].compact
 
-      files = expand_yaml_pattern(pattern)
-      if files.empty?
-        say "No files found matching pattern: #{pattern}", :red
-        exit 1
+      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
+    end
 
-      say "🔄 Normalizing #{files.size} file(s)...", :blue
+    desc "validate-meetings YAML_FILE_PATTERN",
+         "Validate Meeting/Agenda YAML file(s) against schema/meeting.yaml."
 
-      success_count = 0
-      error_count = 0
+    def validate_meetings(pattern)
+      validator = SchemaValidator.new(meeting_schema_path)
+      Batch.run(self, pattern, header: "🔍 Validating meetings") do |file|
+        schema_errors = validator.validate_file(file)
+        model_errors = collect_meeting_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
 
-      files.each do |file|
-        print "  #{File.basename(file)}... "
-        begin
-          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
+    desc "normalize-meetings YAML_FILE_PATTERN",
+         "Round-trip Meeting YAML file(s) through the model (--output DIR or --inplace)."
 
-          if options[:inplace]
-            File.write(file, normalized)
-            say "✅ NORMALIZED", :green
-          else
-            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 — #{e.message}", :red
-          error_count += 1
-        end
+    option :output, type: :string, desc: "Output directory for normalized files"
+    option :inplace, type: :boolean, desc: "Modify files in place (no backup)"
+
+    def normalize_meetings(pattern)
+      unless valid_normalize_options?
+        say normalize_options_error, :red
+        exit 1
       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
+      summary_extra = [
+        ["  Output directory", options[:output]],
+        ["  Mode", options[:inplace] ? "in place" : "--output"]
+      ].compact
 
-    no_commands do
-      # Reserved for private Thor plumbing if we add it later.
+      Batch.run(self, pattern, header: "🔄 Normalizing meetings", summary_extra: summary_extra) do |file|
+        Batch::Result.ok(normalize_meeting_file(file))
+      rescue StandardError => e
+        Batch::Result.bad(["#{file}:1:1: #{e.message}"])
+      end
     end
 
     private
 
-    def expand_yaml_pattern(pattern)
-      Dir.glob(pattern).select { |f| File.file?(f) && f.match?(/\.ya?ml\z/i) }.sort
+    def meeting_schema_path
+      File.expand_path("../../schema/meeting.yaml", __dir__)
     end
 
-    # 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}"]
+      [Edoxen::ValidationError.new(
+        file: file, line: 1, column: 1,
+        message_text: "Model parsing failed: #{e.message}",
+        source: Edoxen::ValidationError::SOURCE_MODEL
+      )]
+    end
+
+    def collect_meeting_model_errors(file)
+      load_meeting_document(file)
+      []
+    rescue StandardError => e
+      [Edoxen::ValidationError.new(
+        file: file, line: 1, column: 1,
+        message_text: "Meeting model parsing failed: #{e.message}",
+        source: Edoxen::ValidationError::SOURCE_MODEL
+      )]
+    end
+
+    # A meeting YAML may be either a single Meeting or a
+    # MeetingCollection. Detect by the presence of a top-level
+    # `meetings:` key and parse accordingly. Returns whichever
+    # model object was successfully constructed.
+    def load_meeting_document(file)
+      data = YAML.safe_load(File.read(file), permitted_classes: [Date, Time])
+      if data.is_a?(Hash) && data.key?("meetings")
+        MeetingCollection.from_yaml(File.read(file))
+      else
+        Meeting.from_yaml(File.read(file))
+      end
     end
 
     def extract_yaml_language_server_comment(content)
@@ -139,18 +212,49 @@ module Edoxen
       lines.find { |l| l.strip.match?(/\A#\s*yaml-language-server:\s*\$schema=/) }&.rstrip
     end
 
-    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 }
+    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
+
+    # 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
+      write_normalized(file, normalized, yaml_language_server_comment)
+    end
+
+    def normalize_meeting_file(file)
+      yaml_language_server_comment = extract_yaml_language_server_comment(File.read(file))
+      normalized = load_meeting_document(file).to_yaml
+      write_normalized(file, normalized, yaml_language_server_comment)
+    end
+
+    def write_normalized(file, normalized, yaml_language_server_comment)
+      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

@@ -7,11 +7,5 @@ module Edoxen
     attribute :type, :string, values: Enums::CONSIDERATION_TYPE
     attribute :date_effective, ResolutionDate
     attribute :message, :string
-
-    key_value do
-      map "type", to: :type
-      map "date_effective", to: :date_effective
-      map "message", to: :message
-    end
   end
 end

data/lib/edoxen/date_range.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Start + end pair for multi-day meetings. Both endpoints are Date.
+  # Either may be nil for one-sided ranges (theoretically), though the
+  # schema enforces both required when DateRange is present.
+  class DateRange < Lutaml::Model::Serializable
+    attribute :start, :date
+    attribute :end, :date
+  end
+end

data/lib/edoxen/deadline.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A time-bound requirement leading up to (or following) a meeting —
+  # registration cutoff, report-submission deadline, etc.
+  class Deadline < Lutaml::Model::Serializable
+    attribute :date, :date
+    attribute :description, :string
+  end
+end

data/lib/edoxen/enums.rb

@@ -39,5 +39,29 @@ module Edoxen
     APPROVAL_DEGREE = %w[unanimous majority minority].freeze
 
     URL_KIND = %w[access report].freeze
+
+    # --- Meeting/Agenda side ----------------------------------------------
+    # Mirrors edoxen-model/models/{meeting,agenda,...}_*.lutaml.
+    # schema/meeting.yaml references these via $defs/<EnumName>.enum.
+
+    MEETING_TYPE = %w[plenary working_group task_group ad_hoc joint conference_session].freeze
+
+    MEETING_STATUS = %w[upcoming completed cancelled].freeze
+
+    AGENDA_STATUS = %w[draft final amended cancelled superseded].freeze
+
+    AGENDA_ITEM_KIND = %w[numbered unnumbered header opening closing].freeze
+
+    AGENDA_ITEM_OUTCOME = %w[discussed resolved deferred adopted withdrawn].freeze
+
+    HOST_TYPE = %w[national_body liaison associate organizer].freeze
+
+    MEETING_RELATION_TYPE = %w[
+      continues_from continues_to joint_with supersedes superseded_by rescheduled_from rescheduled_to
+    ].freeze
+
+    SOURCE_URL_KIND = %w[
+      agenda_pdf minutes_pdf resolutions_pdf report_pdf register_url landing_page
+    ].freeze
   end
 end

data/lib/edoxen/error.rb

@@ -1,7 +1,37 @@
 # 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.
+  # 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/host_ref.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Typed reference to an organization that hosts or co-organizes a
+  # meeting. `ref` is a stable identifier into an external registry
+  # (national_bodies.yml, liaisons.yml, associates.yml in ISO/TC 154);
+  # `type` discriminates which registry.
+  class HostRef < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :type, :string, values: Enums::HOST_TYPE
+    attribute :role, :string
+    attribute :contact, Person
+  end
+end

data/lib/edoxen/localization.rb

@@ -14,17 +14,5 @@ module Edoxen
     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/location.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Venue geography. Multi-venue meetings (e.g., a plenary week with
+  # different hotels) carry one Location per venue.
+  class Location < Lutaml::Model::Serializable
+    attribute :name, :string
+    attribute :address, :string
+    attribute :link, :string
+    attribute :phone, :string
+    attribute :note, :string
+    attribute :lat, :float
+    attribute :lon, :float
+  end
+end

data/lib/edoxen/meeting.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A single Meeting — the event that produces Resolutions. Carries
+  # identity, time, venue, officers, agenda, schedule, deadlines, and
+  # URN links to one or more ResolutionCollection documents.
+  #
+  # Meetings and ResolutionCollections are kept as separate documents
+  # and joined by URN (Meeting.resolution_refs ↔
+  # ResolutionCollection.metadata.meeting_urn) because they have
+  # different lifetimes: agendas exist weeks before a meeting;
+  # resolutions only after adoption.
+  class Meeting < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :urn, :string
+    attribute :ordinal, :integer
+    attribute :type, :string, values: Enums::MEETING_TYPE
+    attribute :status, :string, values: Enums::MEETING_STATUS
+    attribute :year, :integer
+
+    attribute :date_range, DateRange
+
+    attribute :committee, :string
+    attribute :committee_group, :string
+
+    attribute :venues, Location, collection: true
+    attribute :general_area, :string
+    attribute :city, :string
+    attribute :country_code, :string
+    attribute :virtual, :boolean
+
+    attribute :chair, Person
+    attribute :secretary, Person
+    attribute :host, :string
+    attribute :hosts, HostRef, collection: true
+
+    attribute :source_urls, SourceUrl, collection: true
+    attribute :landing_url, :string
+    attribute :registration_url, :string
+
+    attribute :agenda, Agenda
+    attribute :schedule, ScheduleItem, collection: true
+    attribute :deadlines, Deadline, collection: true
+
+    attribute :localizations, MeetingLocalization, collection: true
+    attribute :relations, MeetingRelation, collection: true
+    attribute :resolution_refs, :string, collection: true
+
+    # Lookup by ISO 639-3 language code. Mirrors Resolution#in_language.
+    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
+
+    # English when available, else the first declared localization.
+    def primary_localization
+      in_language("eng", fallback: true)
+    end
+
+    # Find an agenda item by label. Returns nil when no agenda or no
+    # matching label.
+    def find_agenda_item(label)
+      agenda&.find_item(label)
+    end
+  end
+end

data/lib/edoxen/meeting_collection.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Top-level container for many Meetings. Parallel to
+  # ResolutionCollection.
+  class MeetingCollection < Lutaml::Model::Serializable
+    attribute :metadata, MeetingCollectionMetadata
+    attribute :meetings, Meeting, collection: true
+
+    # Find a meeting by URN. Returns nil when no meeting matches.
+    def find_by_urn(urn)
+      meetings&.find { |m| m.urn == urn.to_s }
+    end
+
+    # Find a meeting by StructuredIdentifier components.
+    # Returns the first meeting whose any identifier matches both
+    # prefix and number.
+    def find_by_identifier(prefix:, number:)
+      meetings&.find do |meeting|
+        meeting.identifier&.any? do |id|
+          id.prefix == prefix.to_s && id.number == number.to_s
+        end
+      end
+    end
+  end
+end

data/lib/edoxen/meeting_collection_metadata.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Top-level wrapper for many Meetings in a single YAML file. Parallel
+  # to ResolutionCollection. The metadata block carries display-level
+  # info (title, source); per-meeting identity lives on each Meeting.
+  class MeetingCollectionMetadata < Lutaml::Model::Serializable
+    attribute :title, :string
+    attribute :source, :string
+  end
+end

data/lib/edoxen/meeting_identifier.rb

@@ -6,10 +6,5 @@ module Edoxen
   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/meeting_localization.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Per-language content for a Meeting. Mirrors the glossarist
+  # pattern used by `Localization` for Resolutions: language-agnostic
+  # admin fields live on the parent Meeting; per-language content
+  # lives here.
+  class MeetingLocalization < Lutaml::Model::Serializable
+    attribute :language_code, :string
+    attribute :script, :string
+    attribute :title, :string
+    attribute :general_area, :string
+    attribute :practical_info, :string
+  end
+end

data/lib/edoxen/meeting_relation.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Directed link between two meetings, identified by their
+  # StructuredIdentifier. Reuses the same relation-type vocabulary
+  # pattern as ResolutionRelation.
+  class MeetingRelation < Lutaml::Model::Serializable
+    attribute :source, StructuredIdentifier
+    attribute :destination, StructuredIdentifier
+    attribute :type, :string, values: Enums::MEETING_RELATION_TYPE
+  end
+end