edoxen 0.3.1 → 0.7.2

data/TODO.meeting-agenda/05-fixtures.md

@@ -0,0 +1,43 @@
+# Phase 5 — Fixtures
+
+Priority: **P0** for canonical, **P1** for richer ones.
+
+## Goal
+
+Real-world fixture YAMLs in `spec/fixtures/meetings/` that exercise
+every shape the model supports.
+
+## Deliverables
+
+### P0 — required for canonical
+
+- `spec/fixtures/meetings/simple-meeting.yaml` — minimal valid
+  Meeting (identifier, type, date_range, one venue, one localization,
+  one agenda item).
+- `spec/fixtures/meetings/ciml-56-meeting.yaml` — OIML CIML 56th
+  meeting: bilingual (EN/FR), structured identifier, source URLs with
+  kind, resolution_ref URN linking to a ResolutionCollection.
+- `spec/fixtures/meetings/isotc154-plenary-42-meeting.yaml` — ISO/TC
+  154 42nd plenary: multi-day date_range, multi-venue, typed hosts,
+  full schedule with 9 entries, deadlines, chair/secretary.
+
+### P1 — useful coverage
+
+- `spec/fixtures/meetings/virtual-meeting.yaml` — virtual meeting
+  (no venues, country_code empty).
+- `spec/fixtures/meetings/multi-collection.yaml` — a
+  MeetingCollection wrapping multiple meetings.
+
+## Fixture invariants
+
+- All fixtures MUST validate against `schema/meeting.yaml`.
+- All fixtures MUST round-trip through the Ruby model
+  (`Meeting.from_yaml(...).to_yaml` re-parses identically).
+- Real-world fixtures (ciml-56, isotc154-42) MUST reflect actual
+  published data — no fabricated committee names or dates.
+
+## Acceptance criteria
+
+- [ ] At least the three P0 fixtures exist.
+- [ ] `bundle exec exe/edoxen validate-meetings "spec/fixtures/meetings/*.yaml"` passes on all of them.
+- [ ] Each fixture is referenced by at least one round-trip spec.

data/TODO.meeting-agenda/06-specs.md

@@ -0,0 +1,52 @@
+# Phase 6 — Specs
+
+Priority: **P0**
+
+## Goal
+
+Comprehensive spec coverage. One spec file per new model class, plus
+CLI and schema-sync coverage. Real model instances only — no
+`double()`.
+
+## Deliverables — `spec/edoxen/meeting_*_spec.rb` (one per class)
+
+For each of the 13 new classes:
+
+- Construction with explicit attrs.
+- Round-trip YAML serialization.
+- Enum coverage where applicable (one example per enum value).
+- Real-instance types (e.g., `Meeting#agenda` returns an `Edoxen::Agenda`).
+
+## Deliverables — additional specs
+
+- `spec/edoxen/meeting_collection_spec.rb` — top-level container,
+  round-trips, lookup helpers (`find_by_urn`, `find_by_identifier`).
+- `spec/edoxen/meeting_lookup_spec.rb` — `Meeting#in_language`,
+  `Meeting#primary_localization`, `Meeting#find_agenda_item`.
+- `spec/edoxen/schema_meeting_enum_sync_spec.rb` — every enum in
+  `schema/meeting.yaml` `$defs` matches the corresponding
+  `Edoxen::Enums::*` frozen array.
+- `spec/edoxen/schema_meeting_model_sync_spec.rb` — every Ruby
+  Meeting-related class has matching properties/collection flags in
+  `schema/meeting.yaml` `$defs`.
+- `spec/edoxen/cli_meetings_spec.rb` — `validate-meetings` and
+  `normalize-meetings` subcommands, spawned via `Open3.capture3`
+  against the new fixtures.
+- `spec/edoxen/schema_validator_meeting_spec.rb` — SchemaValidator
+  constructed with the meeting schema path; happy path + each error
+  type (additionalProperties, required, enum, pattern, type).
+
+## Style rules
+
+- Real model instances only — no `double()`.
+- Each example ≤ 10 lines.
+- Round-trip examples cover every fixture.
+
+## Acceptance criteria
+
+- [ ] One spec file per new class (13 files).
+- [ ] +5 additional specs (collection, lookup, schema enum sync,
+      schema model sync, CLI).
+- [ ] +1 schema_validator spec for the meeting schema path.
+- [ ] `bundle exec rspec` — 0 failures (existing 197 + new ≈ 80+).
+- [ ] `bundle exec rubocop` clean.

data/TODO.meeting-agenda/07-cli.md

@@ -0,0 +1,55 @@
+# Phase 7 — CLI integration
+
+Priority: **P1**
+
+## Goal
+
+Add `validate-meetings` and `normalize-meetings` subcommands. Reuse
+the existing `Edoxen::Cli::Batch` deep module — no scaffold
+duplication.
+
+## Deliverables
+
+- `lib/edoxen/cli.rb` — two new subcommands:
+
+```ruby
+desc "validate-meetings YAML_FILE_PATTERN",
+     "Validate Meeting/Agenda YAML file(s) against schema/meeting.yaml."
+
+def validate_meetings(pattern)
+  validator = SchemaValidator.new(meeting_schema_path)
+  Batch.run(self, pattern, header: "🔍 Validating meetings") do |file|
+    errors = validator.validate_file(file) + collect_meeting_model_errors(file)
+    errors.empty? ? Batch::Result.ok("VALID") : Batch::Result.bad(errors.map(&:to_clickable_format))
+  end
+end
+
+desc "normalize-meetings YAML_FILE_PATTERN",
+     "Round-trip Meeting YAML file(s) through the model (--output DIR | --inplace)."
+
+option :output, type: :string
+option :inplace, type: :boolean
+
+def normalize_meetings(pattern)
+  # Same shape as normalize — uses Batch.run
+end
+```
+
+- `lib/edoxen/cli.rb` private: `meeting_schema_path`,
+  `collect_meeting_model_errors`.
+
+## Why separate subcommands
+
+- Different root schema, different model parser.
+- `validate` (existing) is for ResolutionCollection; backward
+  compatibility preserved.
+- Future: a `validate-all` that auto-detects via `oneOf` if needed.
+
+## Acceptance criteria
+
+- [ ] `edoxen validate-meetings PATTERN` exits 0 on valid fixtures.
+- [ ] `edoxen validate-meetings PATTERN` exits non-zero + lists
+      errors on invalid input.
+- [ ] `edoxen normalize-meetings PATTERN --output DIR` round-trips.
+- [ ] Existing `validate` and `normalize` (for Resolutions) unchanged.
+- [ ] `edoxen help` lists both pairs of commands.

data/TODO.meeting-agenda/08-docs.md

@@ -0,0 +1,35 @@
+# Phase 8 — Documentation
+
+Priority: **P1**
+
+## Goal
+
+README + CLAUDE.md reflect the Meeting/Agenda model. The canonical
+edoxen-model README documents the new LUTAML files.
+
+## Deliverables — edoxen gem
+
+- `README.adoc`:
+  - New "Meeting & Agenda model" section with ASCII tree.
+  - Quick-start example showing both Resolution and Meeting parsing.
+  - Cross-link to the canonical LUTAML files.
+- `CLAUDE.md`:
+  - Architecture section mentions `Meeting`, `Agenda`, the meeting
+    schema, and the separate CLI subcommands.
+  - Audit checklist extended: schema_model_sync_spec covers both
+    `schema/edoxen.yaml` and `schema/meeting.yaml`.
+
+## Deliverables — edoxen-model
+
+- `README.adoc`:
+  - File index extended with all new `.lutaml` files.
+  - New "Meeting model" section explaining the Meeting/Agenda split,
+    URN linking to Resolutions, and the localization pattern.
+  - Sample meeting YAML mirroring one of the gem's fixtures.
+
+## Acceptance criteria
+
+- [ ] Both READMEs updated.
+- [ ] edoxen CLAUDE.md updated.
+- [ ] Sample YAML in edoxen-model README would pass
+      `edoxen validate-meetings`.

data/TODO.meeting-agenda/09-verify-and-release.md

@@ -0,0 +1,41 @@
+# Phase 9 — Verify, PR, merge, release
+
+Priority: **P0**
+
+## Goal
+
+Land everything via PRs. Verify GHA passes. Merge. Bump edoxen minor
+(new feature) and release.
+
+## Branch / PR plan
+
+| Repo | Branch | PRs against |
+|---|---|---|
+| `edoxen/edoxen-model` | `feat/meeting-agenda-model` | main |
+| `edoxen/edoxen` | `feat/meeting-agenda-model` | main |
+
+Order: edoxen-model first (canonical), then edoxen (mirror).
+
+## Verification gates
+
+Per branch, before pushing:
+
+- [ ] `bundle exec rspec` — 0 failures.
+- [ ] `bundle exec rubocop` — 0 offenses.
+- [ ] `bundle exec exe/edoxen validate-meetings "spec/fixtures/meetings/*.yaml"` — clean.
+- [ ] `bundle exec exe/edoxen normalize-meetings --output /tmp/out` — round-trips.
+- [ ] No AI attribution in any commit.
+- [ ] No TODOs / FIXMEs in committed source.
+- [ ] No transient files (.DS_Store, .bak, .swp).
+
+## Post-merge
+
+- [ ] Trigger `gh workflow run release.yml --ref main -f next_version=minor`
+      on `edoxen/edoxen`.
+- [ ] Confirm new version appears on rubygems.org.
+- [ ] Confirm tag `vX.Y.Z` pushed.
+
+## Why minor (not patch)
+
+The new Meeting/Agenda model is an additive feature. No breaking
+change to existing Resolution APIs. Semver minor on the 0.x line.

data/TODO.meeting-agenda/10-future-enhancements.md

@@ -0,0 +1,72 @@
+# Phase 10 — Future enhancements (not in this release)
+
+Priority: **P2**
+
+These are documented as known-future-work; not executed in this pass.
+Each one would be its own PR.
+
+## P2.1 — Per-schedule-item localization
+
+`ScheduleItemLocalization` carrying per-language `event` and
+`description`. Triggered when a real consumer needs WG meeting titles
+in FR alongside EN.
+
+## P2.2 — Meeting series
+
+`MeetingSeries` carrying `{identifier, name, description}` with
+`Meeting.series_ref: String` (URN). Triggered when navigation across
+ordinals becomes a real use case (ISO/TC 154 plenary history page).
+
+## P2.3 — Contribution model
+
+Replace flat `Person.contributors` with a `Contribution` class
+matching the comment in the original draft (`'contributors should
+defer to Contribution model`). Triggered when we need to distinguish
+"presented" vs "authored" vs "reviewed" contributions per meeting.
+
+## P2.4 — Auto-detect document type in CLI
+
+A single `edoxen validate PATTERN` that auto-detects
+ResolutionCollection vs Meeting via JSON-Schema `oneOf`. Triggered
+when users complain about remembering two subcommand names.
+
+## P2.5 — Cross-document link validation
+
+A spec/assertion that every `Meeting.resolution_refs[*]` URN has a
+matching `ResolutionCollection` somewhere in the data set, and vice
+versa. Triggered when broken links cause real bugs.
+
+## P2.6 — Attendance roster
+
+`Meeting.attendance: Attendance[]` carrying per-person attendance
+records (present/absent/apologies + affiliation). Triggered when a
+consumer needs the full attendance record, not just officers.
+
+## P2.7 — Vote records
+
+`VoteRecord { resolution_ref, person, vote: VoteType }` linked to a
+Meeting. Triggered when ballot-by-ballot transparency becomes a
+requirement.
+
+## P2.8 — Minutes narrative
+
+A `Minutes` class distinct from `Agenda`, capturing the actual
+narrative of what was said (linked Markdown / Asciidoc blocks per
+agenda item). Triggered when the OIML `meetings/` directory starts
+receiving Bulletin scans.
+
+## P2.9 — federation (multi-body)
+
+A `Federation` or `JointMeeting` class for meetings organized by
+multiple bodies (e.g., a JWG with TC 154 + TC 307). Triggered when
+real joint-meeting data lands.
+
+## P2.10 — IANA / ISO 3166-1 / ISO 639-3 / ISO 15924 reference data
+
+Built-in lookup tables to validate `country_code`, `language_code`,
+`script` against the actual standard. Triggered when typo-rate
+becomes painful.
+
+## Acceptance criteria
+
+This file documents intent only; nothing to land in this release.

data/TODO.meeting-agenda/README.md

@@ -0,0 +1,30 @@
+# TODO.meeting-agenda — index
+
+The work to land a canonical Meeting + Agenda + AgendaItem model
+linkable to Resolutions/Decisions across `edoxen` and `edoxen-model`.
+
+## Phases
+
+| # | File | Priority | Status |
+|---|---|---|---|
+| 1 | [01-design-decisions.md](01-design-decisions.md) | P0 | done |
+| 2 | [02-lutaml-canonical.md](02-lutaml-canonical.md) | P0 | pending |
+| 3 | [03-ruby-models.md](03-ruby-models.md) | P0 | pending |
+| 4 | [04-schema.md](04-schema.md) | P0 | pending |
+| 5 | [05-fixtures.md](05-fixtures.md) | P0 | pending |
+| 6 | [06-specs.md](06-specs.md) | P0 | pending |
+| 7 | [07-cli.md](07-cli.md) | P1 | pending |
+| 8 | [08-docs.md](08-docs.md) | P1 | pending |
+| 9 | [09-verify-and-release.md](09-verify-and-release.md) | P0 | pending |
+| 10 | [10-future-enhancements.md](10-future-enhancements.md) | P2 | documented |
+
+## Execution order
+
+Phases 2 → 9 are executed in order. Phase 10 documents known-future-
+work only.
+
+## Branches
+
+- `edoxen/edoxen-model` ← `feat/meeting-agenda-model` (Phase 2)
+- `edoxen/edoxen` ← `feat/meeting-agenda-model` (Phases 3–8)
+- Phase 9 merges both, then releases `edoxen` as a minor bump.

data/edoxen.gemspec

@@ -39,4 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "json_schemer", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.7"
   spec.add_dependency "thor", "~> 1.0"
+  spec.add_dependency "unlocodes", "~> 0.1"
 end

data/lib/edoxen/agenda.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # The business-order document of a Meeting. Distinct from the
+  # timetable (Schedule) — the Agenda orders topics; the Schedule
+  # orders time slots.
+  #
+  # An Agenda may be versioned independently of the Meeting: a draft
+  # agenda circulates weeks before; a final agenda at meeting time;
+  # an amended agenda if items are added during the meeting. The
+  # `status` field captures that lifecycle.
+  class Agenda < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :status, :string, values: Enums::AGENDA_STATUS
+    attribute :source_doc, :string
+    attribute :items, AgendaItem, collection: true
+    attribute :opening_session, ScheduleItem
+    attribute :closing_session, ScheduleItem
+
+    # Find an agenda item by its label (e.g., "5.2"). Returns nil
+    # when no item matches.
+    def find_item(label)
+      items&.find { |item| item.label == label.to_s }
+    end
+  end
+end

data/lib/edoxen/agenda_item.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One entry on an Agenda. `label` is the visible identifier (e.g.,
+  # "5.2"); `kind` discriminates numbered/unnumbered/header/opening/
+  # closing; `outcome` records what happened; `resolution_ref`
+  # optionally links to the URN of the resolution this item produced.
+  class AgendaItem < Lutaml::Model::Serializable
+    attribute :label, :string
+    attribute :kind, :string, values: Enums::AGENDA_ITEM_KIND
+    attribute :title, :string
+    attribute :description, :string
+    attribute :references, Reference, collection: true
+    attribute :outcome, :string, values: Enums::AGENDA_ITEM_OUTCOME
+    attribute :resolution_ref, :string
+  end
+end

data/lib/edoxen/attendance.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One attendance record per person. Mirrors the ParticipationStatus
+  # enum from edoxen-model/models/participation_status.lutaml.
+  # Optional `affiliation` and `notes` fields let callers annotate
+  # proxy representatives and any meeting-specific details.
+  class Attendance < Lutaml::Model::Serializable
+    attribute :person, Person
+    attribute :status, :string, values: Enums::PARTICIPATION_STATUS
+    attribute :affiliation, :string
+    attribute :proxy_for, Person
+    attribute :notes, :string
+
+    key_value do
+      map "person", to: :person
+      map "status", to: :status
+      map "affiliation", to: :affiliation
+      map "proxy_for", to: :proxy_for
+      map "notes", to: :notes
+    end
+  end
+end

data/lib/edoxen/cli.rb

@@ -125,8 +125,71 @@ module Edoxen
       end
     end
 
+    desc "validate-meetings YAML_FILE_PATTERN",
+         "Validate Meeting/Agenda YAML file(s) against schema/meeting.yaml."
+
+    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
+
+    desc "normalize-meetings YAML_FILE_PATTERN",
+         "Round-trip Meeting YAML file(s) through the 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_meetings(pattern)
+      unless valid_normalize_options?
+        say normalize_options_error, :red
+        exit 1
+      end
+
+      summary_extra = [
+        ["  Output directory", options[:output]],
+        ["  Mode", options[:inplace] ? "in place" : "--output"]
+      ].compact
+
+      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
+
+    desc "unlocode CODE", "Resolve a UN/LOCODE via the canonical registry."
+    def unlocode(code)
+      entry = Edoxen::ReferenceData.find_unlocode(code)
+      if entry.nil?
+        say "No entry for #{code.upcase} in the UN/LOCODE registry.", :red
+        exit 1
+      end
+
+      say "UN/LOCODE:  #{entry.code}", :blue
+      say "  Name:      #{entry.name}"
+      say "  Country:   #{entry.country}"
+      say "  Subdiv:    #{entry.subdivision}" if entry.subdivision
+      coords = entry.coordinates
+      say "  Coords:    #{coords}" if coords
+      funcs = entry.functions.compact.map(&:to_s)
+      say "  Functions: #{funcs.join(", ")}" unless funcs.empty?
+    end
+
     private
 
+    def meeting_schema_path
+      File.expand_path("../../schema/meeting.yaml", __dir__)
+    end
+
     def collect_model_errors(file)
       ResolutionCollection.from_yaml(File.read(file))
       []
@@ -138,6 +201,30 @@ module Edoxen
       )]
     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)
       lines = content.split("\n").first(5)
       lines.find { |l| l.strip.match?(/\A#\s*yaml-language-server:\s*\$schema=/) }&.rstrip
@@ -165,6 +252,16 @@ module Edoxen
       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]

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,36 @@ 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
+
+    # P2.6 / P2.7 — Attendance and Vote records.
+    PARTICIPATION_STATUS = %w[present absent apologies observer excused].freeze
+
+    VOTE_TYPE = %w[
+      affirmative negative abstain absent not_applicable
+    ].freeze
   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