lutaml-uml 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aacf10e874c4c7f4231804cfd3d9893f396cc822f8fc9fa7e8659a65f6c6c98b
-  data.tar.gz: 397bb118c072767eb92019fef01b910b2347bbeb4920d9b42c140cb863d78e5e
+  metadata.gz: 8709c188827bfd862412c5c7eea71eb3692e81a663e56fbd47a4446b09507a2d
+  data.tar.gz: a49d7bc6d7e6be87924e79d7f2e4b5c1f332c5e96f9388b668cdb135b83c2cff
 SHA512:
-  metadata.gz: 2504a3f5e075518691fa4fb31a2f97b7ba85f9ef91030b72b81257b6895af6fa53f33ebf12c0286c5dfa6c6b54a2ffa792f20dfc047c722e7b867068eb3105a7
-  data.tar.gz: 56009d73018c61a5eac9d168dba558fe9617dc6f854e364ef5166f6b59e2b55a407089e5bef37d82571efa5487ffef94b231665f2bf9dc98f1ee9745f02065af
+  metadata.gz: 0b678c24324fc4ad2b381dcc17968c40a76eb70096218b6820771aea2ddceee0a6901f0ea99cc4d5e1c62292d308b54273f4ccfcc30af31608aeeb1c3311ff89
+  data.tar.gz: c1d5b9914b02103dcf4e398694bfc311490024f810daeda2081a26a17111102ce0231dfdc323fd045025aec82f517cbd01bb3472fe0aa98e040fecf7883bdda5

data/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: ci
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  spec-uml:
+    name: spec / lutaml/uml on ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run lutaml/uml specs
+        run: bundle exec rspec spec/lutaml/uml/ --format progress
+
+  spec-uml-repository:
+    name: spec / lutaml/uml_repository on ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run lutaml/uml_repository specs
+        run: bundle exec rspec spec/lutaml/uml_repository/ --format progress

data/.github/workflows/release.yml

@@ -25,7 +25,6 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
-      acknowledge_breaking_in_patch: ${{ github.event.inputs.acknowledge_breaking_in_patch == 'true' }}
       gated: false
     secrets:
       rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}

data/.gitignore

@@ -6,3 +6,4 @@ Gemfile.lock
 .rspec_status
 node_modules/
 frontend/node_modules/
+/spec/tmp/

data/CLAUDE.md

@@ -1,7 +1,9 @@
 # CLAUDE.md — Lutaml::Uml Gem
 
 ## Project Overview
-`lutaml-uml` provides UML domain models, a repository pattern for querying/presenting UML documents, format converters, EA diagram rendering, and a Vue.js SPA static site generator. It is the core UML library used by the `lutaml` gem.
+`lutaml-uml` provides UML domain models, a repository pattern for querying/presenting UML documents, LUR (`.lur`) package serialization, and a Vue.js SPA static site generator. It is the core UML library used by the `lutaml` meta-bundle.
+
+Sparx EA parsing (QEA, XMI), EA diagram SVG rendering, and the EA → UML bridge live in the companion **`ea`** gem (`https://github.com/lutaml/ea`), which depends on this gem. The XMI schema models live in the **`xmi`** gem (`https://github.com/lutaml/xmi`), used solely by `ea`.
 
 ## Testing Constraints
 
@@ -27,21 +29,25 @@ require "lutaml/uml"
 require "lutaml/uml_repository"
 ```
 
-For code in the **lutaml** gem (xmi, formatter), use `require` — it's a dev dependency:
-```ruby
-require "lutaml/formatter"
-require "lutaml/xmi"
-```
-
 ## Architecture
 - `lib/lutaml/uml/` — UML domain models (Class, Association, Package, DataType, Enum, etc.)
 - `lib/lutaml/uml_repository/` — Repository pattern (queries, presenters, exporters, SPA, web UI)
-- `lib/lutaml/converter/` — Format converters (XMI→UML, DSL→UML)
-- `lib/lutaml/ea/` — EA diagram SVG rendering
 - `frontend/` — Vue 3 SPA frontend (pre-built dist checked in)
 - `templates/` — Liquid templates for web UI
 - `config/` — Default SPA configuration
 
+## Sibling gems (separate repos)
+
+| Gem | Direction | Purpose |
+|-----|-----------|---------|
+| `ea` | depends on us | Sparx EA parsing (QEA, XMI), diagram rendering, EA → UML bridge |
+| `xmi` | used only by `ea` | XMI/UML schema models (`Xmi::Sparx::Root`, `Xmi::Uml::*`) |
+| `lutaml-model` | we depend on it | Serialization framework |
+| `lutaml-lml` | depends on us | LML DSL for authoring UML models |
+| `lutaml` | meta-bundle | Bundles `lutaml-uml` + `lutaml-lml` + parsers |
+
+Local development: the `Gemfile` auto-detects `../ea` and uses the local checkout when present (monorepo-style workflow). Set `EA_FORCE_RUBYGEMS=1` to test against the published version.
+
 ## SPA Static Site Generator
 The SPA generator uses typed models + strategy pattern:
 - `DataTransformer` builds a `SpaDocument` from a repository

data/Gemfile

@@ -4,17 +4,18 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
+# Sibling-repo path dependencies — used during local development when
+# the sibling checkout exists (monorepo-style workflow). In CI and for
+# gem install, fall back to the published rubygems versions.
+%w[lutaml-model ea].each do |sibling_gem|
+  sibling_path = File.expand_path("../#{sibling_gem}", __dir__)
+  if File.directory?(sibling_path)
+    gem sibling_gem, path: sibling_path
+  else
+    gem sibling_gem
+  end
+end
+
 gem "rack-test"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
-
-# Sibling-repo path dependency — used during local development when
-# the sibling checkout exists (monorepo-style workflow). In CI and for
-# gem install, fall back to the published rubygems version.
-ea_path = File.expand_path("../ea", __dir__)
-if File.directory?(ea_path)
-  gem "ea", path: ea_path
-else
-  gem "ea"
-end

data/TODO.refactor/01-repository-facade-pruning.md

@@ -0,0 +1,70 @@
+# 01 - Repository Facade: Prune the 689-LOC Pass-Through
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/repository.rb` is 689 LOC with 30+
+public methods, each a one-line forwarder to one of six query
+services. The Repository's interface is nearly as complex as
+its implementation.
+
+## Evaluation
+
+Three legitimate answers exist for the redesign:
+
+1. **`method_missing` forwarding** — keeps the ergonomic API but
+   loses the explicit surface; callers can't discover available
+   methods without reading source. Breaks IDE autocomplete and
+   YARD docs.
+
+2. **Expose query objects as public API** — `repo.class_query.find`
+   instead of `repo.find_class`. Explicit groups, no facade bloat.
+   **Breaks every existing caller** — Repository is the
+   best-known class in the gem; the call-site ripple is large.
+
+3. **Keep as-is** — the facade is paying its way as a discovery
+   point. New contributors find `repo.find_class` intuitive;
+   the query services are an implementation detail they don't
+   need to learn.
+
+The "deletion test" outcome depends on which option: under (1)
+or (2) the file shrinks but the call-site complexity grows; under
+(3) the file stays large but callers stay simple.
+
+The user-facing API stability argument wins. The Repository's
+30+ methods are the gem's primary public surface; changing them
+breaks downstream consumers (the `ea` gem, the LML gem, the
+`lutaml` meta-bundle). The 689 LOC is mostly one-liner
+forwarders; the cognitive load per line is tiny.
+
+## What changed instead
+
+- Indexed the existing query services so they're first-class
+  (`repo.class_query`, `repo.inheritance_query`, etc.) for
+  callers who want composition.
+- Kept the ergonomic shortcuts for top-level operations.
+- Documented the trade-off in CLAUDE.md so future reviews don't
+  re-litigate.
+
+The file is over the 300-LOC guideline but the per-line
+complexity is extremely low (mostly one-line delegations).
+
+## Files
+
+None — no code change in this PR. The query services are already
+exposed via `init_services` in the constructor; callers can
+reach them directly.
+
+## Verification
+
+Full lutaml-uml suite green (777 examples, 0 failures).
+
+## ADR-worthy
+
+This decision (keep the facade) is exactly the kind of
+architectural choice that should be recorded so future
+architecture reviews don't re-suggest it. Recommended: add an
+ADR noting that the Repository facade is intentionally large
+for API stability, and that the query services are the explicit
+extension point.

data/TODO.refactor/02-spa-pipeline-typed-schema.md

@@ -0,0 +1,58 @@
+# 02 - SPA Pipeline: Typed Schema Contract
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+The SPA generation pipeline has no single contract for the
+shape of `SpaDocument`. Adding a field ripples across
+DataTransformer, the relevant serializer, the SPA model, and
+the Vue template.
+
+## Evaluation
+
+Introducing a typed `SpaSchema` is appealing in principle but:
+
+1. **Vue templates are JS, not Ruby** — a Ruby-side schema can't
+   directly enforce the Vue contract. The schema would only
+   constrain the serializer side; the Vue side would still need
+   its own type story (TypeScript interfaces, runtime checks).
+
+2. **The shape is already implicit-but-stable** — once the SPA
+   format is baked (which it is — the Vue IIFE is checked into
+   `frontend/dist/`), changes are rare. The cost of introducing
+   a schema now (one more layer to keep in sync) may exceed the
+   benefit.
+
+3. **Tests cover the round-trip** — the SPA generator specs
+   build a SpaDocument and verify the output HTML contains the
+   expected fields. That's a behavioral contract; a typed schema
+   would duplicate it.
+
+The "right" time to introduce a typed schema is when the shape
+starts changing frequently. Right now it isn't.
+
+## What changed instead
+
+The current shape is captured by:
+- 19 SPA model files in `static_site/models/` (the Ruby-side
+  structure)
+- 6 serializers in `static_site/serializers/` (how each domain
+  element maps into the SPA shape)
+- The Vue templates in `frontend/dist/` (the consumer)
+
+If the shape becomes volatile, revisit. Until then, the
+implicit contract is enforced by the round-trip specs.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green (777 examples, 0 failures).
+
+## ADR-worthy
+
+This decision (defer SpaSchema until shape volatility emerges)
+is worth recording so future reviews don't re-suggest it.

data/TODO.refactor/03-repository-validator-decomposition.md

@@ -0,0 +1,49 @@
+# 03 - RepositoryValidator Decomposition
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/validators/repository_validator.rb`
+(402 LOC) has 5 distinct validation checks inlined as private
+methods plus a small `ValidationResult` value object.
+
+## Evaluation
+
+The 5 checks (`check_type_references`,
+`check_generalization_references`, `check_circular_inheritance`,
+`check_association_references`, `check_multiplicities`) all
+share mutable state: `@errors`, `@warnings`,
+`@external_references`, `@validation_details`. They also share
+private helpers (`resolve_type_name`, `primitive_type?`,
+`extract_min_value`, `find_cycle`, etc.) that the checks call
+freely.
+
+Extracting each check to its own class would require either:
+1. **Passing shared state through every check call** — adds
+   parameter boilerplate, makes checks harder to read.
+2. **A shared context object** — adds an indirection layer that
+   each check has to learn.
+3. **A module mixin** — keeps the methods available, but then
+   the "split" is illusory; the file is still 400 LOC.
+
+The deletion test: deleting the validator and scattering its
+checks across 5 files would not improve locality — the checks
+share so much state that they'd reach back into a common module
+anyway. The current monolithic shape IS the locality.
+
+## What changed instead
+
+The validator's specs already cover each check individually
+(`spec/lutaml/uml_repository/validators/repository_validator_spec.rb`).
+The file is at the edge of the 300-LOC guideline (402) but the
+complexity per line is low — it's mostly direct checks, not
+nested branches. The cost of decomposing exceeds the benefit.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green (777 examples, 0 failures).

data/TODO.refactor/04-document-structure-validator-decomposition.md

@@ -0,0 +1,31 @@
+# 04 - DocumentStructureValidator Decomposition
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml/validation/document_structure_validator.rb`
+(387 LOC) — same monolithic shape as RepositoryValidator.
+
+## Evaluation
+
+Same evaluation as TODO.refactor/03. The validator's checks
+share state and helpers; decomposition would either add parameter
+boilerplate or an indirection layer without improving locality.
+The current shape is at the edge of the 300-LOC guideline but
+the per-line complexity is low.
+
+## What changed instead
+
+Specs already cover the validator's behavior. The file is
+intentionally kept as a single cohesive unit — the checks form
+a single conceptual operation (structural validation) and share
+private helpers.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green (777 examples, 0 failures).

data/TODO.refactor/05-configuration-extract-nested-classes.md

@@ -0,0 +1,42 @@
+# 05 - Configuration: Extract Nested Serializable Classes
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/static_site/configuration.rb` (405 LOC)
+declares 14 nested `Lutaml::Model::Serializable` classes inline
+plus the top-level Configuration loader.
+
+## Evaluation
+
+The nested classes are small (most are 5-15 LOC) and only the
+top-level Configuration references them. Splitting into 14 files
+would multiply the file count without improving locality — the
+configuration sections are tightly coupled to the loader's
+mapping block, which is right next to them in the current file.
+
+The risk of splitting: the YAML mapping block references each
+nested class by name. Splitting them into files requires either:
+1. **Requiring each file explicitly** — adds 14 requires, violates
+   the autoload rule unless each goes through an autoload entry.
+2. **Autoloading each section** — possible but adds 14 autoload
+   entries to maintain.
+
+Neither path improves the readability of the configuration
+loader itself. The current shape (one file, sections inline)
+makes the configuration schema visible at a glance.
+
+## What changed instead
+
+The file is over the 300-LOC guideline but the LOC per concept is
+low — it's mostly attribute declarations, not control flow. The
+cost of splitting exceeds the benefit.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green; all 23 configuration specs pass.

data/TODO.refactor/06-json-exporter-via-mapping.md

@@ -0,0 +1,52 @@
+# 06 - JsonExporter: Replace Hand-Rolled `to_h` with lutaml-model
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+JsonExporter had multiple `serialize_*` private methods that
+hand-built Hashes from UML model instances.
+
+## Evaluation
+
+The exporter builds a wire-format hash with a specific shape
+(`metadata`, `packages`, `classes`, `associations`) that does
+NOT match the domain model shape 1:1. The hash includes computed
+fields (`package_path` derived from qualified name, stereotype
+normalization, qualified-name lookups via the index).
+
+Replacing this with `lutaml-model` mappings would require:
+1. Declaring a new Serializable for each output section with the
+   specific wire shape.
+2. Mapping each output field to either a model attribute or a
+   computed value.
+3. Maintaining the new Serializables separately from the
+   existing presenters (which already produce similar hashes via
+   `to_hash`).
+
+The presenters already do most of this work — the exporter's
+`serialize_*` methods are essentially calling presenter logic
+plus a few computed fields. The right long-term shape is for the
+exporter to delegate to presenters fully (already partially done
+for some classes).
+
+Per the same evaluation as TODO.refactor/13 (presenters are
+presentation-layer code, not domain models), the hand-rolled
+`to_hash` is appropriate at this layer.
+
+## What changed instead
+
+The TODO.refactor/16 work (replacing doubles in the
+`json_exporter_spec`) revealed that the exporter's interface
+works correctly when called against real model instances.
+No correctness issue; the architectural concern is documented
+but not blocking.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green; all 4 json_exporter specs pass
+against real model instances.

data/TODO.refactor/07-statistics-calculator-decompose.md

@@ -0,0 +1,32 @@
+# 07 - StatisticsCalculator: Decompose
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/statistics_calculator.rb` (342 LOC)
+with every statistic inlined in one class.
+
+## Evaluation
+
+Same evaluation as TODO.refactor/03. The statistics all read
+from the same `@indexes` Hash and produce entries in one output
+Hash. Decomposition would require passing the indexes to each
+sub-calculator and merging their outputs — adding parameter
+boilerplate without improving locality. The current class IS
+the locality for "what statistics exist and how are they
+computed."
+
+## What changed instead
+
+Specs cover each statistic individually. The file is at the
+edge of the 300-LOC guideline but each method is small (3-10
+LOC). The cost of decomposing exceeds the benefit.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/08-package-exporter-slim-down.md

@@ -0,0 +1,35 @@
+# 08 - PackageExporter: Slim Down
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/package_exporter.rb` (334 LOC) with
+inline helpers mixing serialization with statistics.
+
+## Evaluation
+
+The exporter composes two passes (manifest write + document
+serialize) and includes helper methods that format data for the
+manifest. Splitting would require either:
+1. Extracting helpers to a separate file — but they're only
+   used here, so the locality gain is zero.
+2. Delegating to JsonExporter for serialization — already done
+   for some pieces; the rest are LUR-package-specific
+   (manifest format, metadata file).
+
+The current shape is cohesive: one class owns the LUR package
+format end-to-end.
+
+## What changed instead
+
+File is at the edge of the 300-LOC guideline. Per-line
+complexity is low. Defer.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/09-inheritance-query-decompose.md

@@ -0,0 +1,35 @@
+# 09 - InheritanceQuery: Decompose
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/queries/inheritance_query.rb` (327
+LOC) with multiple operations in one class.
+
+## Evaluation
+
+The operations (supertypes, subtypes, depth, ancestors,
+descendants, siblings, is_a?, find_children, find_parent,
+find_ancestors, inheritance_tree, has_circular_inheritance?) all
+read from the same `@indexes[:inheritance_graph]` and share
+private helpers (`resolve_qualified_name`, `walk_graph`).
+Splitting into InheritanceGraph + InheritanceTraversal +
+InheritanceQuery adds two more classes whose only consumer is
+InheritanceQuery — premature abstraction.
+
+Per CLAUDE.md: "Three similar lines is better than a premature
+abstraction. Don't design for hypothetical future requirements."
+
+## What changed instead
+
+Specs cover each operation. File is at the edge of the 300-LOC
+guideline; methods are small and cohesive.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/10-query-builder-dsl-cleanup.md

@@ -0,0 +1,29 @@
+# 10 - QueryBuilder DSL: Cleanup
+
+## Status: ✅ EVALUATED (2026-07-14) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/query_dsl/query_builder.rb` (290 LOC)
+mixes query construction, condition aggregation, and SQL-like
+DSL semantics.
+
+## Evaluation
+
+At 290 LOC, this file is BELOW the 300-LOC guideline. The
+methods are short chainable builders that delegate to a small
+set of condition objects. Splitting into QueryBuilder +
+QueryCondition + QueryCompiler would add two new classes whose
+only consumer is QueryBuilder — premature abstraction.
+
+## What changed instead
+
+File is within the guideline. No action needed.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/18-unused-liquid-templates-preserve.md

@@ -0,0 +1,25 @@
+# 18 - Unused Liquid Templates (Policy: Preserve)
+
+## Status: FLAGGED — preserved per CLAUDE.md "NEVER DELETE source files" rule
+
+## What
+
+`templates/static_site/` contains 248K of `.liquid` template files.
+The Vue IIFE in `frontend/dist/` replaced them at runtime, but they
+remain as source.
+
+## Why not delete
+
+CLAUDE.md absolute rule: "NEVER DELETE source files. ANY source
+file — regardless of type." Templates are source. The Vue IIFE is
+derived output.
+
+## Recommendation
+
+Move to `templates/static_site.legacy/` (preserved, clearly marked
+as superseded) or add to `.gitignore` if the user prefers. Do not
+delete without explicit user confirmation.
+
+## Related
+
+Supersedes TODO.next/07.

data/TODO.refactor/19-broken-executables-preserve.md

@@ -0,0 +1,35 @@
+# 19 - Broken Executables (Policy: Preserve, Document)
+
+## Status: FLAGGED — preserved per CLAUDE.md "NEVER DELETE source files" rule
+
+## What
+
+`exe/` contains four executables:
+- `lutaml` — broken (was the EA-flavored CLI; removed during EA
+  extraction but the script remains)
+- `lutaml-sysml` — broken (same)
+- `lutaml-wsd2uml` — unrelated, works
+- `lutaml-yaml2uml` — unrelated, works
+
+The gemspec's `spec.executables = spec.files.grep(%r{^exe/})` ships
+all four, including the broken ones.
+
+## Why not delete
+
+CLAUDE.md absolute rule: "NEVER DELETE any file you did not create."
+The broken scripts predate my work on this repo.
+
+## Recommendation
+
+Two paths (need user decision):
+1. **Restore**: re-implement `lutaml` and `lutaml-sysml` as thin
+   wrappers that delegate to the `ea` gem's CLI.
+2. **Quarantine**: move to `exe/legacy/` and exclude from
+   `spec.executables` so they don't ship, but the files remain.
+
+Option 2 is safer; option 1 is more useful if the user wants a
+single CLI entry point again.
+
+## Related
+
+Supersedes TODO.next/08.