lutaml-uml 0.4.3 → 0.5.2

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/11-shallow-base-classes-decide.md

@@ -0,0 +1,38 @@
+# 11 - Shallow Base Classes: Decide Their Fate
+
+## Status: ✅ DONE (2026-07-14) — KEPT with rationale
+
+## Problem
+
+`BaseExporter` (61 LOC) and `Output::Strategy` (36 LOC) looked
+shallow — each holds an `@output_path` / `@repository`, declares
+`NotImplementedError` on the abstract method, and adds no behaviour.
+
+Deletion test: would deleting them concentrate complexity?
+
+## Resolution
+
+**Kept both.** Reasoning:
+
+- They declare the *contract* — `#export(path, options)` for
+  exporters, `#generate` for strategies. Without them, every
+  subclass re-rolls the constructor signature and the abstract
+  method shape. The contract is the test surface; deleting the
+  base classes removes the seam.
+- Two adapters each = real seam per the "two adapters means a real
+  seam" rule. The base class is where the seam lives.
+- The classes are small but they earn their keep: they prevent
+  drift in the subclass constructors and abstract-method
+  signatures.
+
+Added an explicit docstring to each one explaining the contract and
+why the class exists. Future reviewers won't need to re-litigate.
+
+## Files
+
+- `lib/lutaml/uml_repository/exporters/base_exporter.rb` (docstring added)
+- `lib/lutaml/uml_repository/static_site/output/strategy.rb` (docstring added)
+
+## Verification
+
+No code change; full suite green.

data/TODO.refactor/12-typed-index-keys.md

@@ -0,0 +1,30 @@
+# 12 - Typed Index Keys (Replace Stringly-Typed Hash)
+
+## Status: ✅ DONE (2026-07-14)
+
+## Problem
+
+All query objects took `@indexes` as a Hash and accessed it with
+symbol keys (`:qualified_names`, `:package_paths`, `:stereotypes`,
+`:inheritance_graph`, `:associations`, `:diagram_index`). Key names
+were defined in `IndexBuilder` but never declared as constants. A
+typo silently returned nil.
+
+## Resolution
+
+Introduced `Lutaml::UmlRepository::IndexKeys` as a frozen constant
+module declaring every valid index key. Query classes use
+`IndexKeys::<NAME>` instead of bare symbols. `LazyRepository`
+raises on unknown keys at `ensure_index` time (already done via
+`INDEX_BUILDERS` registry — this TODO completes the type story by
+making keys named).
+
+## Files
+
+- `lib/lutaml/uml_repository/index_keys.rb` (new)
+- `lib/lutaml/uml_repository/queries/*.rb` (uses IndexKeys constants)
+- `lib/lutaml/uml_repository/lazy_repository.rb` (uses IndexKeys constants)
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/13-presenter-to-hash-mixin.md

@@ -0,0 +1,39 @@
+# 13 - Presenter `to_hash` Mixin (DRY)
+
+## Status: ✅ DONE (2026-07-14) — NO CHANGE, with rationale
+
+## Problem (initial framing)
+
+Seven presenter classes each defined their own `to_hash` method,
+hand-rolling serialization. The initial concern was that this
+violates CLAUDE.md's "NEVER write `def to_h` on a model class" rule.
+
+## Resolution
+
+**No change.** Re-evaluation: the CLAUDE.md rule's qualifier is
+"on a model class." Presenters are NOT model classes — they don't
+extend `Lutaml::Model::Serializable` and they aren't domain models.
+They're presentation objects whose explicit job is to translate a
+domain model into a wire-format hash. The `to_hash` method IS the
+presentation contract.
+
+The rule's intent — prevent hand-rolled serialization from
+bypassing the type system on typed models — does not apply here.
+Presenters are intentionally untyped presentation layers.
+
+**On the DRY concern:** the 7 presenters share common fields
+(`type:`, `name:`, `visibility:`, `stereotype:`) but each also has
+presenter-specific keys (`attr_type:`, `class_name:`, `general:`,
+etc.). Extracting a `PresenterHash` mixin for the common fields
+would be a premature abstraction — three similar lines is better
+than a wrong abstraction (per CLAUDE.md). The drift risk is low
+because each presenter has its own specs covering its `to_hash`
+output.
+
+## Files
+
+None — no code change.
+
+## Verification
+
+Full lutaml-uml suite green (754 examples, 0 failures).

data/TODO.refactor/14-state-machine-specs.md

@@ -0,0 +1,30 @@
+# 14 - State Machine Element Specs
+
+## Status: ✅ DONE (2026-07-14)
+
+## Problem
+
+State machine elements had zero spec coverage:
+
+- `lib/lutaml/uml/activity.rb`
+- `lib/lutaml/uml/actor.rb`
+- `lib/lutaml/uml/connector.rb`
+- `lib/lutaml/uml/state.rb`
+- `lib/lutaml/uml/transition.rb`
+
+## Resolution
+
+Added behavioral specs for each — YAML round-trip, attribute access,
+and collection management. Uses real model instances, no doubles.
+
+## Files
+
+- `spec/lutaml/uml/activity_spec.rb` (new)
+- `spec/lutaml/uml/actor_spec.rb` (new)
+- `spec/lutaml/uml/connector_spec.rb` (new)
+- `spec/lutaml/uml/state_spec.rb` (new)
+- `spec/lutaml/uml/transition_spec.rb` (new)
+
+## Verification
+
+Full lutaml-uml suite green; new specs add ~25 examples.

data/TODO.refactor/15-uml-class-behavioral-specs.md

@@ -0,0 +1,28 @@
+# 15 - UmlClass Behavioral Specs
+
+## Status: ✅ DONE (2026-07-14)
+
+## Problem
+
+`spec/lutaml/uml/class_spec.rb` was 57 lines, testing only YAML
+serialization. Missing: association management, attribute handling,
+generalization, stereotypes, constraints.
+
+## Resolution
+
+Expanded to cover:
+- Attribute add/remove/lookup
+- Association management (add, find by name, find by target)
+- Generalization (add parent, walk hierarchy)
+- Stereotype assignment and lookup
+- Constraint attachment
+
+Real instances; no doubles.
+
+## Files
+
+- `spec/lutaml/uml/class_spec.rb` (expanded)
+
+## Verification
+
+Full lutaml-uml suite green.

data/TODO.refactor/16-replace-remaining-doubles.md

@@ -0,0 +1,32 @@
+# 16 - Replace Remaining Doubles in Specs
+
+## Status: ✅ DONE (2026-07-14)
+
+## Problem
+
+18 `double()` calls remained in specs, concentrated in:
+- `spec/lutaml/uml_repository/search_result_spec.rb`
+- `spec/lutaml/uml_repository/exporters/markdown_exporter_spec.rb`
+- `spec/lutaml/uml_repository/exporters/json_exporter_spec.rb`
+- `spec/lutaml/uml_repository/presenters/class_presenter_spec.rb`
+- `spec/lutaml/uml_repository/presenters/element_presenter_spec.rb`
+- `spec/lutaml/uml_repository/presenters/presenter_factory_spec.rb`
+
+CLAUDE.md forbids doubles — they couple tests to implementation
+details and pass when real usage breaks.
+
+## Resolution
+
+Replaced each `double(...)` with either:
+- A real model instance built via test factory, or
+- A `Struct.new(...)` for plain data when no real model fits.
+
+Each replaced spec now exercises the real interface.
+
+## Files
+
+The six spec files listed above.
+
+## Verification
+
+Full lutaml-uml suite green; grep `double(` in `spec/` returns 0.

data/TODO.refactor/17-silent-skip-cleanup.md

@@ -0,0 +1,29 @@
+# 17 - Silent Skip Patterns in Query Specs
+
+## Status: ✅ DONE (2026-07-14)
+
+## Problem
+
+`spec/lutaml/uml_repository/queries/class_query_spec.rb` had ~9
+`next unless qname` / `next unless pkg_path` patterns that silently
+passed when fixture preconditions failed. Same pattern in
+`inheritance_query_spec.rb` (~4 sites).
+
+These gave false confidence — the test "passed" even when the
+fixture was missing the data it claimed to exercise.
+
+## Resolution
+
+Replaced each silent skip with an explicit `expect(fixture_data).not_to be_empty`
+precondition. If the fixture lacks the data, the test fails loudly
+with a clear message; if the data is present, the assertion runs
+normally.
+
+## Files
+
+- `spec/lutaml/uml_repository/queries/class_query_spec.rb`
+- `spec/lutaml/uml_repository/queries/inheritance_query_spec.rb`
+
+## 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.