edoxen 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5b96952dff52eca74ca77c35534cf68e380e57694eec5f308fe855b306bd3b2
-  data.tar.gz: c19d66b0f115b74562a01d04a19e1416f2ee7414010d7cca991f84ee37c39245
+  metadata.gz: c2fe56ab6ddff9606df4af319cba2d372d7114bce66822968710cb15cf0886cd
+  data.tar.gz: 7e30d4153daaa03d9cab2d10170947b10c646526bcc6b156ef909a5b8557d61d
 SHA512:
-  metadata.gz: d44772650c4943aa5d487969edb49db47a8078ff7544fe68d7d581e238eb4d1d8b1c4268919cbd823b5f7787c2edf81040b7342ae05392ccfe21e1159f5e9e34
-  data.tar.gz: 0e079b28ade73d23191d517fbf676fd22f2a1584670575b1d3ad42bbc18673c02836feba67191d72733aee37be1aa27abb6f5b087aac824fa71132889249cd72
+  metadata.gz: 5665a5650d5ac075b1905095578a188d5ce4e1a94d3fac522133055d14bdc356a5f49382256f9ea3f9b7c159bc7c2d5dc5315b1fa7c5354ec8a016d2cd85f3c3
+  data.tar.gz: 6c269809b5e14f084d1a427a68a7e623466550dde648ffad9add85fae84ae5b1607de77adf70bfa5f0a90a6f04cfd4db842f0287c84d9e6120286a2eb4486d94

data/.rubocop_todo.yml

@@ -1,11 +1,19 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-07-18 13:23:46 UTC using RuboCop version 1.78.0.
+# on 2025-07-20 10:40:54 UTC using RuboCop version 1.78.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: TreatCommentsAsGroupSeparators, ConsiderPunctuation, Include.
+# Include: **/*.gemspec
+Gemspec/OrderedDependencies:
+  Exclude:
+    - 'edoxen.gemspec'
+
 # Offense count: 1
 # Configuration parameters: Severity, Include.
 # Include: **/*.gemspec
@@ -13,30 +21,57 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'edoxen.gemspec'
 
-# Offense count: 13
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Layout/EmptyLineAfterMagicComment:
   Exclude:
-    - 'lib/edoxen/action.rb'
-    - 'lib/edoxen/approval.rb'
-    - 'lib/edoxen/consideration.rb'
-    - 'lib/edoxen/meeting_identfier.rb'
+    - 'test.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
+Layout/EmptyLinesAroundClassBody:
+  Exclude:
     - 'lib/edoxen/resolution.rb'
-    - 'lib/edoxen/resolution_collection.rb'
     - 'lib/edoxen/resolution_date.rb'
-    - 'lib/edoxen/resolution_relationship.rb'
-    - 'lib/edoxen/structured_identifier.rb'
-    - 'lib/edoxen/subject_body.rb'
-    - 'spec/edoxen/action_spec.rb'
-    - 'spec/edoxen/resolution_collection_spec.rb'
-    - 'spec/edoxen/resolution_spec.rb'
+    - 'lib/edoxen/resolution_set.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 123
+Layout/EmptyLinesAroundExceptionHandlingKeywords:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/edoxen/cli.rb'
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
 
 # Offense count: 1
 # Configuration parameters: AllowComments.
@@ -44,13 +79,76 @@ Lint/EmptyFile:
   Exclude:
     - 'lib/edoxen/meeting.rb'
 
-# Offense count: 14
+# Offense count: 1
+# Configuration parameters: AllowedParentClasses.
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect.
+Lint/UselessAssignment:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 8
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 67
+
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 234
+  Max: 146
+
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 167
+
+# Offense count: 6
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 16
 
 # Offense count: 10
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 50
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 6
+
+# Offense count: 6
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 17
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 15
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
@@ -59,38 +157,102 @@ Style/Documentation:
     - 'lib/edoxen.rb'
     - 'lib/edoxen/action.rb'
     - 'lib/edoxen/approval.rb'
+    - 'lib/edoxen/cli.rb'
     - 'lib/edoxen/consideration.rb'
-    - 'lib/edoxen/meeting_identfier.rb'
+    - 'lib/edoxen/meeting_identifier.rb'
+    - 'lib/edoxen/metadata.rb'
     - 'lib/edoxen/resolution.rb'
-    - 'lib/edoxen/resolution_collection.rb'
-    - 'lib/edoxen/resolution_relationship.rb'
-    - 'lib/edoxen/structured_identifier.rb'
-    - 'lib/edoxen/subject_body.rb'
+    - 'lib/edoxen/resolution_date.rb'
+    - 'lib/edoxen/resolution_relation.rb'
+    - 'lib/edoxen/resolution_set.rb'
+    - 'lib/edoxen/schema_validator.rb'
+    - 'lib/edoxen/url.rb'
+    - 'round_trip_test.rb'
 
-# Offense count: 13
+# Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: always, always_true, never
 Style/FrozenStringLiteralComment:
   Exclude:
     - '**/*.arb'
-    - 'lib/edoxen/action.rb'
-    - 'lib/edoxen/approval.rb'
-    - 'lib/edoxen/consideration.rb'
-    - 'lib/edoxen/meeting_identfier.rb'
-    - 'lib/edoxen/resolution.rb'
-    - 'lib/edoxen/resolution_collection.rb'
-    - 'lib/edoxen/resolution_date.rb'
-    - 'lib/edoxen/resolution_relationship.rb'
-    - 'lib/edoxen/structured_identifier.rb'
-    - 'lib/edoxen/subject_body.rb'
-    - 'spec/edoxen/action_spec.rb'
-    - 'spec/edoxen/resolution_collection_spec.rb'
-    - 'spec/edoxen/resolution_spec.rb'
+    - 'test.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowedReceivers.
+# AllowedReceivers: Thread.current
+Style/HashEachMethods:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/edoxen/cli.rb'
+    - 'lib/edoxen/schema_validator.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 5
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/edoxen/cli.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: implicit, explicit
+Style/RescueStandardError:
+  Exclude:
+    - 'lib/edoxen/cli.rb'
+    - 'lib/edoxen/schema_validator.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SlicingWithRange:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
+    - 'round_trip_test.rb'
+
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'round_trip_test.rb'
+
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiteralsInInterpolation:
+  Exclude:
+    - 'round_trip_test.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/UnlessElse:
+  Exclude:
+    - 'lib/edoxen/schema_validator.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
-  Max: 123
+  Max: 122

data/CLAUDE.md

@@ -0,0 +1,220 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem is
+
+`edoxen` is an information model for formal resolutions and decisions
+(ISO/TC 154, CIPM, OIML, etc.). It provides:
+
+- A set of `Lutaml::Model::Serializable` subclasses that mirror the canonical
+  LutaML UML model in `../edoxen-model/models/*.lutaml`.
+- A JSON-Schema (`schema/edoxen.yaml`) used to validate real-world YAML
+  files via `SchemaValidator` (`json_schemer`).
+- A Thor CLI (`edoxen validate`, `edoxen normalize`) that wraps both the
+  schema validator and the Ruby model parser.
+
+## Architecture
+
+### Loading
+
+`lib/edoxen.rb` configures `Lutaml::Model::Config` and `autoload`s every
+constant defined under `Edoxen::...` from its native file. **No
+`require_relative` is used anywhere in this gem.** Cross-references between
+model classes resolve through Ruby autoload (works for circular references
+because autoload is lazy).
+
+If you add a new model class under `lib/edoxen/<name>.rb`, register one
+autoload entry in `lib/edoxen.rb`. The namespace is flat under `Edoxen::`,
+matching the LUTAML naming.
+
+### Three sources of truth that must stay in sync
+
+There are three descriptions of the same data, and they must agree:
+
+1. **`lib/edoxen/*.rb`** — Ruby model. Attribute declarations + `key_value`
+   `map` blocks drive (de)serialization. The model is permissive about
+   field names and tolerant of unknown fields (lutaml-model drops them
+   silently) — the schema is the strict source.
+2. **`schema/edoxen.yaml`** — JSON-Schema (draft-07). Used by
+   `SchemaValidator`. Adds `additionalProperties: false`, `required`,
+   `enum`, `pattern`, and `minItems` constraints the model does not.
+3. **`spec/fixtures/*.yaml`** — real-world samples. Must validate against
+   the schema AND round-trip through the Ruby model.
+
+When you change one, change all three in the same PR. The
+`spec/edoxen/schema_enum_sync_spec.rb` enforces the schema ↔ Ruby enum
+boundary at runtime.
+
+### Enum single source of truth
+
+`lib/edoxen/enums.rb` is the authoritative list for every enum used by
+the gem (`ACTION_TYPE`, `CONSIDERATION_TYPE`, `RESOLUTION_TYPE`,
+`RESOLUTION_RELATION_TYPE`, `RESOLUTION_DATE_TYPE`, `APPROVAL_TYPE`,
+`APPROVAL_DEGREE`, `URL_KIND`). Both the Ruby model
+(`attribute :type, :string, values: Enums::ACTION_TYPE`) and the
+`schema/edoxen.yaml` `$defs/<EnumName>` block reference these constants.
+
+`schema_enum_sync_spec.rb` loads both, walks `$defs` for enum-typed
+definitions, and asserts each value-list matches the corresponding
+`Edoxen::Enums::*` array.
+
+If you add a value (e.g. a new verb), add it to the Ruby constant AND
+the schema enum block in the same commit.
+
+### Glossarist-style localization pattern
+
+Per-language content lives inside `Resolution#localizations[]` (one
+`Localization` per language). `Localization` carries `language_code`
+(ISO 639-3) and `script` (ISO 15924), plus `title`, `subject`, `message`,
+`considering`, `considerations`, `actions`, `approvals`.
+
+Language-agnostic admin fields (`identifier`, `doi`, `urn`,
+`agenda_item`, `dates`, `categories`, `meeting`, `relations`, `urls`)
+live on the parent `Resolution`.
+
+`Metadata#title_localized` and `Metadata#source_urls` mirror this
+pattern for collection-level metadata.
+
+### LUTAML fidelity + LUTAML quirks
+
+The Ruby model is faithful to the LUTAML files. Two LUTAML quirks
+that propagate:
+
+- `empowers` is in both `ConsiderationType` and `ActionType` (upstream
+  duplication). `enums_spec.rb` documents this with an explicit test.
+- LUTAML uses `camelCase` attribute names (e.g. `agendaItem`). Wire names
+  in this gem are `snake_case` (`agenda_item`) for YAML convention;
+  `dateEffective` becomes `date_effective`. This is a deliberate
+  one-way mapping from the LUTAML notation; the LUTAML files remain
+  authoritative for the semantic model.
+
+### SchemaValidator
+
+`lib/edoxen/schema_validator.rb` is intentionally small:
+
+- `SchemaValidator::ValidationError` — rendered as `file:line:col: msg`.
+- `#validate_file(path)` → `Array<ValidationError>`.
+- `#validate_content(content, path)` → `Array<ValidationError>`.
+- `SchemaValidator::LineMap` — builds an indent-heuristic
+  `{json_pointer => line_no}` map and resolves a JSON-Schema data
+  pointer to a line via longest-prefix match. **No path-shape
+  hardcoding.** Adding new collection paths never requires touching this.
+- Date coercion (`normalize_dates`) converts `Date` / `Time` instances
+  back to ISO strings before handing data to `json_schemer` because the
+  schema declares them as `type: string, format: date`.
+
+### CLI
+
+`Edoxen::Cli` (Thor) lives in `lib/edoxen/cli.rb`. Two commands:
+
+- `validate PATTERN` — glob-expands YAML files and runs both
+  `SchemaValidator#validate_file` and `Collection.from_yaml`. The dual
+  check is intentional: the schema catches `additionalProperties` /
+  `enum` / `required` / `pattern` violations that the model silently
+  drops, and the model catches structural issues json_schemer can't
+  express (numeric/date coercion, missing nested classes).
+- `normalize PATTERN (--output DIR | --inplace)` — round-trips each
+  YAML file through `ResolutionCollection.from_yaml` and writes the
+  result back. Preserves any `# yaml-language-server: $schema=...`
+  directive in the first 5 lines.
+
+Exit code is non-zero if any file fails.
+
+## Build, test, lint
+
+```bash
+bundle install                  # first-time setup
+bundle exec rspec               # full test suite
+bundle exec rspec spec/edoxen/schema_validator_spec.rb
+bundle exec rspec spec/edoxen/enums_spec.rb
+bundle exec rspec spec/edoxen/resolution_spec.rb:32      # one example by line
+bundle exec rubocop             # lint (line length 120, double-quoted strings)
+bundle exec rake                # default: spec + rubocop
+bundle exec exe/edoxen validate "spec/fixtures/*.yaml"
+mkdir -p /tmp/out && bundle exec exe/edoxen normalize "spec/fixtures/*.yaml" --output /tmp/out
+```
+
+## Conventions specific to this gem
+
+- **No `double()` in specs** — use real `Edoxen::*` instances and fixture files.
+- **Serialization is framework-only.** Never hand-roll `to_h` / `from_h` /
+  `to_yaml` / `from_yaml` / `to_json` / `from_json` on a model class. Use
+  `attribute` + `key_value do … end` and let lutaml-model do it. Renames
+  are `map "wire_name", to: :attr` — never key-swapping inside a method.
+- **Wire names are `snake_case`.** Even when the LUTAML notation uses
+  camelCase, the YAML wire form is `snake_case` (`agenda_item`, not
+  `agendaItem`). The attribute name on the Ruby side is also `snake_case`;
+  when they match exactly, drop the explicit `map` declaration only after
+  checking lutaml-model supports it. (Today lutaml-model needs an explicit
+  `map` for `key_value`; do not delete them.)
+- **Enums on the model and the schema must agree.** When you add or remove
+  a value to `Enums::*`, also update the matching `enum:` list in
+  `schema/edoxen.yaml` $defs. The `schema_enum_sync_spec` will catch any
+  drift.
+- **Fixtures are load-bearing.** `spec/fixtures/{ciml,cipm,isotc154,...}.yaml`
+  are real-world extracts. If a model change invalidates them, that's a
+  signal to either (a) update the fixture in the same PR, or (b)
+  reconsider the model change. Do not leave them broken.
+- **No backwards-compat shims on `Resolution`.** The flat `#title`,
+  `#subject`, `#considerations`, `#approvals`, `#actions` form is gone.
+  Always go through `localizations[]`.
+- **Branch discipline.** Never commit to `main`, never push tags, all
+  changes via PR. See the global rules.
+- **No AI attribution** in commits, PRs, or code comments.
+
+## Source hygiene — do not violate
+
+- Never hand-roll `to_h` / `from_h` / `to_yaml` / `to_json` on a model.
+- Never use `send` to call private methods.
+- Never use `instance_variable_set` or `instance_variable_get` to cross
+  another object's boundary.
+- Never use `respond_to?` for type checking — design so the type
+  hierarchy makes the check unnecessary, or use `is_a?`.
+- Never use `require_relative` in library code. Use the autoload entries
+  in `lib/edoxen.rb`.
+
+## Adding a new model class (the OCP test)
+
+When you introduce a new concept (e.g. `Subject`):
+
+1. Add `lib/edoxen/subject.rb` declaring
+   `class Subject < Lutaml::Model::Serializable` with attributes and
+   `key_value do … end` mapping.
+2. Add one autoload line in `lib/edoxen.rb`.
+3. Add a `$defs/Subject` block in `schema/edoxen.yaml` and reference
+   it from any parent that uses it.
+4. Add `spec/edoxen/subject_spec.rb` covering round-trip for every
+   field, every enum value, real-instance construction, no doubles.
+5. Add a fixture or update an existing one to exercise the new model.
+6. Run `bundle exec rspec` (full suite passes including
+   `schema_enum_sync_spec`) and `bundle exec rubocop`.
+
+No existing class requires modification. The library grows only by
+extension.
+
+## Adding a new CLI subcommand
+
+1. Add a `desc "name ARGS", "Description"` block in `lib/edoxen/cli.rb`
+   followed by a method. The CLI is intentionally a thin glue layer;
+   put logic in a model or service class and call it from the command.
+2. Add `spec/edoxen/cli_spec.rb` integration-style coverage that spawns
+   the real `exe/edoxen` process via `Open3.capture3` and asserts on
+   stdout/stderr/exit code. Don't shell out to a mocked binary — the
+   CLI is exercised as an end-to-end contract.
+3. Update the README's "Command-line interface" section.
+
+## Audit checklist — run before approving any contribution
+
+1. `bundle exec rspec` passes (currently 136 / 0).
+2. `bundle exec exe/edoxen validate spec/fixtures/*.yaml` is clean
+   (currently 4 / 0).
+3. `bundle exec exe/edoxen normalize --output /tmp/out` round-trips
+   every fixture without data loss (re-parse and assert equality).
+4. Schema and Ruby model agree on: field names, enum values,
+   required vs. optional, collection vs. scalar, `additionalProperties: false`.
+5. No new hand-rolled `to_h` / `from_h` on a model class.
+6. No new `LineMap`-style hardcoded path-shape branches.
+7. README example YAML parses against the schema (currently three
+   real-world fixtures do).
+8. `bundle exec rubocop` clean (target Ruby ≥ 3.0, line length 120).