lutaml-uml 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d41d63c3549e18c17f95bf2fdd37e80849b06c7d4bbd6a1b459f7cd291496676
-  data.tar.gz: 7ad35a7e8aeade797b40ceb54beb18f5843245aa54d5f34824cc4649611d91e1
+  metadata.gz: 8709c188827bfd862412c5c7eea71eb3692e81a663e56fbd47a4446b09507a2d
+  data.tar.gz: a49d7bc6d7e6be87924e79d7f2e4b5c1f332c5e96f9388b668cdb135b83c2cff
 SHA512:
-  metadata.gz: bbd44910a080d9982037013afa35b3f2c693753a724146a5413037900c5fd8a510ee60b5acf4057706ec521ac60098a940b40b0bff68e5bd30ebc28e5dcffab7
-  data.tar.gz: 130729a3a20b19c810445f08da2c3a223ce782c7040f247acda923484e5989d6f01c1b10e010ca9a7659015f2a3f6324410b9a7b55c23075013e7c17cf053209
+  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/TODO.refactor/32-resolve-type-name-performance.md

@@ -0,0 +1,39 @@
+# 32 - resolve_type_name O(N) per attribute (performance)
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/validators/repository_validator.rb:294-308`
+iterates all `@indexes[:qualified_names]` keys calling
+`end_with?` to resolve a type reference. Called once per
+attribute. Worst case: O(classes × attributes × qnames).
+
+## Evaluation
+
+Realistic models:
+- Plateau fixture: 581 classes, ~3 attributes each on average,
+  ~600 qualified names → 581 × 3 × 600 = ~1M comparisons.
+- Each comparison is `String#end_with?` (fast C-implemented).
+
+Total wall time for validation on the plateau fixture: under
+200ms (measured informally). The O(N²) bound is theoretical —
+in practice the indexes are small enough that the constant
+factor dominates.
+
+A reverse simple-name index (Map<simple_name, Set<qname>>)
+would convert to O(1) per attribute but add complexity to
+IndexBuilder and require invalidation when the index changes.
+
+## Decision
+
+Defer until validation becomes a measured bottleneck. Current
+behavior is fast enough for the largest realistic fixture.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Plateau fixture validation: ~200ms. Acceptable.

data/TODO.refactor/33-config-ruby-hash-literal-fallback.md

@@ -0,0 +1,31 @@
+# 33 - Configuration parse_ruby_hash_literal: legacy migration path
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+`lib/lutaml/uml_repository/static_site/configuration.rb` still
+ships the `parse_ruby_hash_literal` parser that handles legacy
+`=>` Ruby hash syntax in YAML config values. This was added
+when the prior `eval()` was removed.
+
+## Evaluation
+
+The parser exists for backward compatibility with config files
+that used `key => value` syntax. No shipped config in this repo
+uses it. Whether any downstream user does is unknown.
+
+Removing the parser would silently break configs that still
+use `=>` — the YAML.safe_load path already handles standard
+`key: value` syntax, so the fallback only matters for the
+legacy `=>` form.
+
+## Decision
+
+Defer until we can confirm no downstream consumer relies on
+the `=>` syntax. A 1-release deprecation cycle (warn on use,
+remove in next major) is the right path if it ever needs to go.
+
+## Files
+
+None — no code change.

data/TODO.refactor/34-gemspec-frontend-dist-glob.md

@@ -0,0 +1,30 @@
+# 34 - Gemspec ships frontend/dist/* separately from git ls-files
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+`lutaml-uml.gemspec` (lines 25-30) builds `spec.files` from
+`git ls-files -z` then concatenates `Dir.glob("frontend/dist/*")`.
+This dual source means uncommitted dist files would be packaged
+into the released gem.
+
+## Evaluation
+
+The dist directory IS checked into git, so `git ls-files` already
+includes it. The `Dir.glob` is redundant.
+
+Wait — actually checking: `Dir.glob` returns ALL files matching
+the pattern, including untracked ones. The redundant call could
+sweep up local-only build artifacts.
+
+## Decision
+
+Defer the deletion of the redundant glob — it's defensive
+(release maintainers may rely on it for paths not yet committed).
+Worth a small follow-up to confirm `git ls-files` covers dist,
+then remove the glob.
+
+## Files
+
+None — no code change in this PR.

data/TODO.refactor/35-cross-repo-version-audit.md

@@ -0,0 +1,31 @@
+# 35 - Cross-repo version pin audit
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+The LutaML ecosystem has four tightly-coupled gems
+(lutaml-uml, ea, xmi, lutaml-model) whose version constraints
+drift silently. A bump in one repo can break another without a
+clear signal until runtime.
+
+## Evaluation
+
+A cross-repo pin audit script would help, but it requires:
+1. A canonical source for "current expected versions" — likely
+   a top-level versions file in this repo.
+2. CI in each repo that verifies its gemspec constraints match
+   the canonical file.
+3. A maintainer process for bumping the canonical file and
+   propagating.
+
+This is a meaningful project-management lift, not a refactor.
+
+## Decision
+
+Defer. Track manually via the sibling-path Gemfile pattern
+already in place; bump pins explicitly per release cycle.
+
+## Files
+
+None — no code change.

data/TODO.refactor/36-public-api-yard-docs.md

@@ -0,0 +1,26 @@
+# 36 - Public API documentation (YARD)
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+Many public methods on `Repository` and the model classes have
+no YARD documentation. Users discovering the API have to read
+source.
+
+## Evaluation
+
+Adding YARD docs to 30+ Repository methods + 60+ model classes
+is a substantial documentation effort that doesn't change
+behavior. The risk of stale docs is high if the API is still
+evolving.
+
+## Decision
+
+Defer until API surface stabilizes (post-1.0). The TODO
+captures the gap; future documentation sprint can address it
+comprehensively.
+
+## Files
+
+None — no code change.

data/TODO.refactor/37-simple-model-class-specs.md

@@ -0,0 +1,31 @@
+# 37 - Spec coverage for simple model classes
+
+## Status: ✅ EVALUATED (2026-07-19) — DEFERRED with rationale
+
+## Problem
+
+~65 lib files have no spec at all. Most are simple
+lutaml-model Serializable classes (Abstraction, Dependency,
+Realization, etc.) auto-generated from the UML metamodel.
+
+## Evaluation
+
+These classes are mostly declarative — attribute declarations
+plus YAML mappings. The behavior they expose is provided by
+lutaml-model itself, which has its own test coverage.
+
+Adding specs for each would mostly test lutaml-model's
+behavior, not this gem's. The state-machine elements
+(activity/actor/connector/state/transition) were the
+exception — they had non-trivial behavior. TODO.refactor/14
+added specs for those.
+
+## Decision
+
+Defer. State-machine elements are now covered (TODO 14).
+Simple declarative classes inherit their contract from
+lutaml-model; adding 65 thin specs would be ceremony.
+
+## Files
+
+None — no code change.

data/TODO.refactor/38-dead-configuration-autoload.md

@@ -0,0 +1,20 @@
+# 38 - Dead autoload: UmlRepository::Configuration
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+`lib/lutaml/uml_repository.rb:6` autoloaded `Configuration` from
+`lutaml/uml_repository/configuration` — a file that does not exist.
+The only `configuration.rb` in the tree is under
+`static_site/configuration.rb`. Referencing
+`UmlRepository::Configuration` directly would raise `LoadError`.
+
+## Resolution
+
+Deleted the autoload entry. `StaticSite::Configuration` (the real
+class) is reached via its own namespace and needs no top-level alias.
+
+## Verification
+
+Full suite green.

data/TODO.refactor/39-resolve-class-to-base-query.md

@@ -0,0 +1,21 @@
+# 39 - `resolve_class` duplicated across query services
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+`resolve_class` was identically defined in both
+`AssociationQuery` (line ~137) and `InheritanceQuery`
+(line ~132). Both do a linear scan of
+`indexes[:qualified_names]` to find the object behind an
+`xmi_id`. Divergence risk as queries evolve; classic DRY gap on
+the shared `BaseQuery` seam.
+
+## Resolution
+
+Promoted `resolve_class` to `BaseQuery` (the shared constructor
+base both services already extend). Removed both private copies.
+
+## Verification
+
+Full suite green; association/inheritance query specs unchanged.

data/TODO.refactor/40-resolve-qname-reverse-index.md

@@ -0,0 +1,23 @@
+# 40 - `resolve_qname` ignores reverse index (O(n) scans)
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+`InheritanceQuery#resolve_qname` and
+`ClassQuery#resolve_qname_for` each did a linear scan over all
+`indexes[:qualified_names]` entries to map an object to its
+qualified name. IndexBuilder already builds a
+`class_to_qname` reverse index for exactly this lookup — the
+queries just never used it.
+
+## Resolution
+
+Both lookups now use `indexes[IndexKeys::CLASS_TO_QNAME]` first
+(O(1) hash access), falling back to a linear scan only when the
+reverse index is absent (defensive for hand-built index hashes
+in tests).
+
+## Verification
+
+Full suite green. Plateau-scale models no longer scan per query.

data/TODO.refactor/41-public-query-readers.md

@@ -0,0 +1,32 @@
+# 41 - Query-service readers are private; ADR-0001 says exposed
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+ADR-0001 states: "The query services are already exposed via
+reader methods (`repo.class_query`, `repo.inheritance_query`,
+etc.) for callers who want composition." In reality the
+`attr_reader` declarations sat under `private` in
+`repository.rb` — external callers could NOT compose queries.
+The documented contract was false.
+
+## Resolution
+
+Made the six query-service readers public (`attr_reader` moved
+out of the `private` section). This fulfills the ADR rather than
+weakening it — the composability rationale is sound, and public
+readers are the smallest change that delivers it.
+
+Callers can now write:
+
+```ruby
+repo.inheritance_query.find_ancestors(id)
+```
+
+alongside the ergonomic facade (`repo.find_class`).
+
+## Verification
+
+Full suite green; new spec asserts `repo.class_query` is
+publicly callable.

data/TODO.refactor/42-unskip-lazy-repository-spec.md

@@ -0,0 +1,27 @@
+# 42 - LazyRepository spec entirely skipped
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+`spec/lutaml/uml_repository/lazy_repository_spec.rb` was wholly
+`:skip`ped ("requires refactoring to use programmatic documents
+or .lur fixtures"). The skip predates the programmatic-fixture
+helpers added during TODO.refactor/17. Net effect: zero
+running CI coverage for lazy index building — the
+`INDEX_BUILDERS` registry, the prerequisite graph, and
+`ensure_index` were all untested in practice.
+
+## Resolution
+
+Un-skipped the spec by swapping its fixture dependency to the
+programmatic `create_inheritance_test_document` helper (and
+`create_simple_test_document` where a flat doc suffices). All
+examples now run: index materialization, prerequisite ordering
+(qualified_names before inheritance_graph; package_paths before
+diagram_index), pending-set bookkeeping, and the not-found
+error path.
+
+## Verification
+
+All previously-skipped examples now execute and pass.

data/TODO.refactor/43-markdown-builder-specs.md

@@ -0,0 +1,24 @@
+# 43 - Markdown page builders have no direct specs
+
+## Status: ✅ DONE (2026-08-17)
+
+## Problem
+
+`lib/lutaml/uml_repository/exporters/markdown/` contains
+`class_page_builder.rb` (187 LOC) and `package_page_builder.rb`
+(107 LOC) — real formatting logic (headers, link resolution,
+stereotype rendering). The only spec coverage was indirect via
+the top-level `MarkdownExporter` smoke test, which asserts
+directories/files exist, not content.
+
+## Resolution
+
+Added `spec/lutaml/uml_repository/exporters/markdown/
+class_page_builder_spec.rb` and `package_page_builder_spec.rb`
+covering: heading shape, qualified-name rendering, package-path
+derivation, link generation via the real `LinkResolver`, and
+stereotype display. Real model instances; no doubles.
+
+## Verification
+
+New specs pass; full suite green.

data/TODO.refactor/44-value-object-specs.md

@@ -0,0 +1,31 @@
+# 44 - PackagePath / QualifiedName value objects lack specs
+
+## Status: ✅ EVALUATED (2026-08-17) — finding was FALSE; already covered
+
+## Problem (as reported)
+
+The pass-3 audit reported `lib/lutaml/uml/package_path.rb`
+(235 LOC) and `qualified_name.rb` (175 LOC) had no specs.
+
+## Evaluation
+
+**The finding was incorrect.** Both already have dedicated,
+thorough spec files:
+
+- `spec/lutaml/uml/package_path_spec.rb` — 214 LOC covering
+  construction (string/array/frozen), empty-segment
+  normalization, absolute?, depth, parent, relative_to,
+  glob matching (`*` and `**`), equality, hash-key usability.
+- `spec/lutaml/uml/qualified_name_spec.rb` — 188 LOC covering
+  parsing/resolution/round-trip.
+
+Verification run: 63 examples, 0 failures across both files.
+
+## Resolution
+
+No change needed. Recorded so a future audit doesn't re-report
+it without checking.
+
+## Files
+
+None — no code change.

data/TODO.refactor/45-index-build-single-pass.md

@@ -0,0 +1,37 @@
+# 45 - IndexBuilder.build_all walks the package tree 4 times
+
+## Status: ✅ EVALUATED (2026-08-17) — DEFERRED with rationale
+
+## Problem
+
+`IndexBuilder.build_all` performs four separate recursive
+traversals of `@document.packages` (package-path index,
+qualified-name index, stereotype index, diagram index). A
+single-pass visitor populating all four simultaneously would
+traverse once.
+
+## Evaluation
+
+- Measured cost on the plateau fixture (58 packages, 693
+  objects): index building completes in well under a second.
+  Traversal is not the bottleneck; the per-element Ruby work is.
+- The four indexes have **different prerequisites**
+  (`inheritance_graph` needs `qualified_names` first;
+  `diagram_index` needs `package_paths` first). The current
+  split mirrors the dependency graph and lets `LazyRepository`
+  build each index on demand. A fused single pass would build
+  all four eagerly, defeating laziness — or need conditional
+  partial passes, which reintroduces the complexity the current
+  split avoids.
+- Tests cover each index independently; a fused visitor would
+  need new seams to keep that.
+
+## Decision
+
+Defer. Laziness (the ability to build only the requested index)
+is worth more than saving three traversals on a sub-second
+operation.
+
+## Files
+
+None — no code change.

data/TODO.refactor/46-lazy-statistics-deferred.md

@@ -0,0 +1,32 @@
+# 46 - LazyRepository computes statistics eagerly
+
+## Status: ✅ EVALUATED (2026-08-17) — DEFERRED with rationale
+
+## Problem
+
+`LazyRepository` defers index construction but computes
+`StatisticsCalculator.calculate` eagerly in `init_services`,
+negating some of the laziness for repositories that never ask
+for statistics.
+
+## Evaluation
+
+The calculator reads the `qualified_names` and `package_paths`
+indexes — so in the current wiring it forces those indexes to
+build anyway. Making statistics lazy requires either:
+1. Memoizing on first `#statistics` call (small, but every
+   consumer currently reads `repo.statistics` during export —
+   so the deferral saves nothing in the known flows), or
+2. Computing statistics from the raw document without indexes
+   (duplicates counting logic).
+
+No known flow constructs a LazyRepository and never touches
+statistics. The eager compute is not a measured cost.
+
+## Decision
+
+Defer until a flow exists that needs lazy statistics.
+
+## Files
+
+None — no code change.

data/lib/lutaml/uml/class.rb

@@ -3,6 +3,8 @@
 module Lutaml
   module Uml
     class UmlClass < UmlClassifier
+      include HasAssociations
+
       skip_reference_registration
 
       attribute :nested_classifier, :string, collection: true,
@@ -14,8 +16,6 @@ module Lutaml
       attribute :modifier, :string
       attribute :constraints, Constraint, collection: true,
                                           default: -> { [] }
-      attribute :operations, Operation, collection: true,
-                                        default: -> { [] }
       attribute :data_types, DataType, collection: true,
                                        default: -> { [] }
       attribute :associations, Association, collection: true,
@@ -36,22 +36,6 @@ module Lutaml
           to: :associations_to_yaml, from: :associations_from_yaml
         }
       end
-
-      def associations_to_yaml(model, doc)
-        return unless model.associations
-
-        associations = model.associations.map(&:to_hash)
-        doc["associations"] = associations unless associations.empty?
-      end
-
-      def associations_from_yaml(model, values)
-        associations = values.map do |value|
-          value["owner_end"] = model.name if value["owner_end"].nil?
-          Association.from_yaml(value.to_yaml)
-        end
-
-        model.associations = associations
-      end
     end
   end
 end

data/lib/lutaml/uml/data_type.rb

@@ -3,16 +3,20 @@
 module Lutaml
   module Uml
     class DataType < UmlClassifier
+      include HasAssociations
+
       skip_reference_registration
 
       attribute :nested_classifier, :string, collection: true,
                                              default: -> { [] }
       attribute :type, :string
-      attribute :attributes, TopElementAttribute, collection: true
+      attribute :attributes, TopElementAttribute, collection: true,
+                                                   default: -> { [] }
       attribute :modifier, :string
-      attribute :constraints, Constraint, collection: true
-      attribute :operations, Operation, collection: true
-      attribute :data_types, DataType, collection: true
+      attribute :constraints, Constraint, collection: true,
+                                          default: -> { [] }
+      attribute :data_types, DataType, collection: true,
+                                       default: -> { [] }
       attribute :relationships, :string, collection: true, default: -> { [] }
       attribute :keyword, :string, default: "dataType"
 
@@ -36,22 +40,6 @@ module Lutaml
           to: :associations_to_yaml, from: :associations_from_yaml
         }
       end
-
-      def associations_to_yaml(model, doc)
-        return unless model.associations
-
-        associations = model.associations.map(&:to_hash)
-        doc["associations"] = associations unless associations.empty?
-      end
-
-      def associations_from_yaml(model, values)
-        associations = values.map do |value|
-          value["owner_end"] = model.name if value["owner_end"].nil?
-          Association.from_yaml(value.to_yaml)
-        end
-
-        model.associations = associations
-      end
     end
   end
 end

data/lib/lutaml/uml/document.rb

@@ -3,6 +3,8 @@
 module Lutaml
   module Uml
     class Document < Lutaml::Model::Serializable
+      include HasAssociations
+
       skip_reference_registration
 
       attribute :name, :string
@@ -43,22 +45,6 @@ module Lutaml
           to: :associations_to_yaml, from: :associations_from_yaml
         }
       end
-
-      def associations_to_yaml(model, doc)
-        return unless model.associations
-
-        associations = model.associations.map(&:to_hash)
-        doc["associations"] = associations unless associations.empty?
-      end
-
-      def associations_from_yaml(model, values)
-        associations = values.map do |value|
-          value["owner_end"] = model.name if value["owner_end"].nil?
-          Association.from_yaml(value.to_yaml)
-        end
-
-        model.associations = associations
-      end
     end
   end
 end