lutaml-uml 0.4.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d7db5a90a481773906ffcd2985d36777ba62f2c79a1de83390c7890a4c9f7c4
-  data.tar.gz: 7d9229702c7b58d2a2d0c8f2261230eb941f7fd76a0f17c784d48da01a22c5c0
+  metadata.gz: aacf10e874c4c7f4231804cfd3d9893f396cc822f8fc9fa7e8659a65f6c6c98b
+  data.tar.gz: 397bb118c072767eb92019fef01b910b2347bbeb4920d9b42c140cb863d78e5e
 SHA512:
-  metadata.gz: ec111d11c2354621c95c3708296356906977f9c949f96a07c8e1ee71928733ff68089b5339bb2017f824fa76274fe2e043693ca48b7cbd1305c85756791097a0
-  data.tar.gz: 81de391a9fc9a1d546d82dcfde50b802a67e4bc28ffee88f08699faa6f54b3e7052107e2824c77dfd2b5cd40f3c78518757e7e1955c2715584225508f543389d
+  metadata.gz: 2504a3f5e075518691fa4fb31a2f97b7ba85f9ef91030b72b81257b6895af6fa53f33ebf12c0286c5dfa6c6b54a2ffa792f20dfc047c722e7b867068eb3105a7
+  data.tar.gz: 56009d73018c61a5eac9d168dba558fe9617dc6f854e364ef5166f6b59e2b55a407089e5bef37d82571efa5487ffef94b231665f2bf9dc98f1ee9745f02065af

data/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
+        required: true
+        default: "skip"
+      acknowledge_breaking_in_patch:
+        description: "Skip the release-breaking-check guard"
+        required: false
+        default: "true"
+  repository_dispatch:
+    types: [do-release]
+
+jobs:
+  release:
+    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 }}
+      pat_token: ${{ secrets.GITHUB_TOKEN }}

data/.gitignore

@@ -1,12 +1,8 @@
 /.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
+/vendor/
 /pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status
+*.gem
 Gemfile.lock
+.rspec_status
+node_modules/
+frontend/node_modules/

data/.rspec

@@ -1,3 +1,3 @@
+--require spec_helper
 --format documentation
 --color
---require spec_helper

data/CLAUDE.md

@@ -0,0 +1,54 @@
+# 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.
+
+## Testing Constraints
+
+**CRITICAL: Do NOT run the full test suite at once.** It will crash due to memory. Run targeted subsets:
+- `bundle exec rspec spec/lutaml/uml/` — UML model specs
+- `bundle exec rspec spec/lutaml/uml_repository/` — Repository, presenters, queries, SPA specs
+- Combine at most 2-3 suites at a time for targeted verification.
+
+## Code Quality Rules
+- Never use `send` (breaks encapsulation). Use `public_send` only when dynamic dispatch is truly necessary.
+- Never use `respond_to?` (poor typing). Use `is_a?` for type checks.
+- Extract god methods into focused helpers.
+- Keep files under ~300 lines. Extract into modules/classes when growing.
+- DRY: consolidate duplicated patterns.
+- Never commit TODO tracking files to git.
+
+## Spec Require Rules
+
+In this repo, specs should use `require` since the gem's lib is on the load path via bundler:
+```ruby
+require "spec_helper"
+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
+
+## SPA Static Site Generator
+The SPA generator uses typed models + strategy pattern:
+- `DataTransformer` builds a `SpaDocument` from a repository
+- `Output::Strategy` subclasses render HTML (single-file or multi-file)
+- `Output::VueInlinedStrategy` embeds Vue IIFE + JSON data in single HTML
+- Frontend built with Vue 3 + Vite + TypeScript in `frontend/`
+
+## CI Notes
+- Ignore Ruby 3.4 ubuntu failures (performance-related, not code issues)
+- Ignore macOS job slowness (GitHub Actions is slow for macOS)

data/Gemfile

@@ -2,7 +2,19 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in lutaml-uml.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
+gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
+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/README.adoc

@@ -1,44 +1,33 @@
-# Lutaml::Uml
+= lutaml-uml
 
-image:https://badge.fury.io/rb/lutaml-uml.svg["Gem Version", link="https://badge.fury.io/rb/lutaml-uml"]
+UML domain models, repository pattern, format converters, and SPA generator for LutaML.
 
-image:https://github.com/lutaml/lutaml-uml/actions/workflows/macos.yml/badge.svg["macos", link="https://github.com/lutaml/lutaml-uml/actions/workflows/macos.yml"]
-image:https://github.com/lutaml/lutaml-uml/actions/workflows/ubuntu.yml/badge.svg["ubuntu", link="https://github.com/lutaml/lutaml-uml/actions/workflows/ubuntu.yml"]
-image:https://github.com/lutaml/lutaml-uml/actions/workflows/windows.yml/badge.svg["windows", link="https://github.com/lutaml/lutaml-uml/actions/workflows/windows.yml"]
+== Overview
 
-Lutaml is a language for specifying UML class diagrams and a tool for converting it into various different formats.
+This gem provides:
 
-## Install
+* `Lutaml::Uml` — UML domain model classes (Class, Association, Package, DataType, Enum, etc.)
+* `Lutaml::UmlRepository` — Repository pattern for querying and presenting UML documents
+* `Lutaml::Converter` — Format converters (XMI to UML, DSL to UML)
+* `Lutaml::Ea` — Enterprise Architect diagram SVG rendering
+* SPA static site generator with Vue.js frontend
 
-### Bundler: `gem "lutaml-uml"`
+== Installation
 
-### RubyGems: `gem install lutaml-uml`
+Add to your Gemfile:
 
-## Language
+[source,ruby]
+gem "lutaml-uml"
 
-See link:LUTAML.adoc[LUTAML.adoc]
+== Usage
 
-## Usage
+[source,ruby]
+require "lutaml/uml"
 
-Converter executables are available:
+== Architecture
 
-* PlantUML WSD to LutaML UML: `lutaml-wsd2uml`
-* LutaML YAML to LutaML UML: `lutaml-yaml2uml`
-
-EXAMPLE: `lutaml-wsd2uml mn/metanorma-model-standoc/models/StandardDoc_Blocks_New.wsd`
-
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lutaml-uml. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/lutaml-uml/blob/master/CODE_OF_CONDUCT.md).
-
-
-## Code of Conduct
-
-Everyone interacting in the Lutaml::Uml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/lutaml-uml/blob/master/CODE_OF_CONDUCT.md).
+* `lib/lutaml/uml/` — UML domain models
+* `lib/lutaml/uml_repository/` — Repository, queries, presenters, exporters, SPA
+* `lib/lutaml/converter/` — XMI→UML and DSL→UML converters
+* `lib/lutaml/ea/` — EA diagram SVG rendering
+* `frontend/` — Vue 3 SPA frontend (pre-built dist included)

data/Rakefile

@@ -4,5 +4,4 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
-
 task default: :spec

data/TODO.next/01-remove-repository-enhanced.md

@@ -0,0 +1,26 @@
+# 01 - Remove Dead `RepositoryEnhanced` From lutaml-uml
+
+## Status: ✅ DONE (2026-06-27)
+
+## What was done
+
+1. Removed `autoload :RepositoryEnhanced, ...` from
+   `lib/lutaml/uml_repository.rb` (line 24).
+2. Renamed the source file to
+   `lib/lutaml/uml_repository/repository_enhanced.rb.disabled` — preserves the
+   source per the "never delete source" rule while preventing autoload.
+
+## Verification
+
+```bash
+grep -rn 'RepositoryEnhanced' lib/ spec/
+# → only the .disabled file (not loadable as Ruby)
+bundle exec rspec  # → still green
+```
+
+## Why disabled, not deleted
+
+The class body still references `ModelTransformations::*` constants (now in
+`ea`). If re-enabled, callers would trigger `NameError` unless `ea` is also
+loaded. Keeping it as `.disabled` lets a future caller (if any legitimate use
+emerges) explicitly opt in by renaming back, after restoring the references.

data/TODO.next/02-drop-fontname-autoload.md

@@ -0,0 +1,32 @@
+# 02 - Drop `Fontname` Autoload (Dead Code)
+
+## Status: ✅ DONE (2026-06-27)
+
+## What was done
+
+1. Removed `autoload :Fontname, "lutaml/uml/fontname"` from
+   `lib/lutaml/uml.rb`.
+2. Added deprecation header to `lib/lutaml/uml/fontname.rb`.
+3. **Kept** `autoload :Group` — `Document` uses it
+   (`attribute :groups, Group, collection: true`). The original TODO.namespace
+   audit was incorrect.
+
+## Source file (kept, not deleted)
+
+- `lib/lutaml/uml/fontname.rb` — deprecated header added; file retained per
+  never-delete-source rule.
+
+## Verification
+
+```bash
+grep -n 'Fontname' lib/lutaml/uml.rb  # → no autoload
+grep -n 'Group' lib/lutaml/uml.rb     # → autoload still present (used by Document)
+bundle exec rspec  # → 754 examples, 0 failures, 103 pending
+```
+
+## Lesson
+
+The audit "Group is unused" was based on grepping for `:Group,` as a type.
+The actual usage is `Group, collection: true` (no leading colon) in
+`lib/lutaml/uml/document.rb:11`. Future dead-code audits must check both
+`:Symbol` and bare constant forms.

data/TODO.next/03-add-missing-behavioral-specs.md

@@ -0,0 +1,56 @@
+# 03 - Add Missing Behavioral Specs
+
+## Status: NOT YET APPLIED
+
+## Problem
+
+Critical behavioral coverage gaps in `lutaml-uml`:
+
+### High-priority gaps
+1. `spec/lutaml/uml/uml_class_spec.rb` — only 57 lines, tests YAML
+   serialization only. Missing: association management, attribute handling,
+   generalization, stereotypes, constraints.
+2. `spec/lutaml/uml_repository/static_site/serializers/inheritance_resolver_spec.rb`
+   — only tests "returns empty for no generalization." Missing: actual
+   multi-level inheritance attribute/association flow.
+3. No spec for circular inheritance detection with actual circular graphs.
+4. `spec/lutaml/uml_repository/validators/repository_validator_spec.rb` —
+   private method tests only assert `result.is_a?(Array)`, never assert
+   specific errors found.
+5. No spec for `Repository#from_file_cached` cache invalidation behavior.
+
+### Edge cases missing
+- Self-referential associations
+- Diamond inheritance
+- Special regex characters in search
+
+### Silent skip patterns to fix
+These patterns silently pass tests when their precondition fails. They should
+either use `skip` with a reason, or guarantee the test data:
+
+- `spec/lutaml/uml_repository/queries/class_query_spec.rb` — `next unless`
+  silently passes ~9 tests
+- `spec/lutaml/uml_repository/queries/inheritance_query_spec.rb` — `next unless`
+  silently passes ~4 tests
+- `spec/lutaml/uml_repository/parsing/full_parsing_spec.rb` — `next if ...`
+  silently passes ~7 tests
+
+## Source
+
+Migrated from `TODO.refactor/12-add-missing-behavioral-specs.md`.
+
+## Fix
+
+1. Expand `uml_class_spec.rb` to cover the metamodel API surface
+   (associations, attributes, generalization, stereotypes).
+2. Replace `next unless` patterns with either:
+   - `skip "reason"` if the data is sometimes unavailable, OR
+   - A guaranteed fixture (programmatic document via `create_simple_test_document`)
+3. Add circular inheritance fixture (programmatic).
+4. Add cache invalidation spec for `from_file_cached` using `sleep` + `touch`
+   to control mtimes.
+5. Assert specific validator errors, not just result types.
+
+## Out of scope (deferred)
+
+Regenerating `.lur` fixtures via the `ea` gem — those are tracked separately.

data/TODO.next/04-finish-double-elimination.md

@@ -0,0 +1,34 @@
+# 04 - Finish Replacing Double-Based Specs
+
+## Status: LOW PRIORITY — residue only
+
+## Problem
+
+The bulk of the double-elimination work is done (see
+`TODO.refactor/11-rewrite-double-based-specs.md` history). What remains:
+
+- `spec/lutaml/uml_repository/presenters/diagram_presenter_spec.rb` lines 7-27:
+  top-level repository/diagram doubles shared by many tests. Complex to
+  replace without rewriting the SVG-rendering assertions.
+- 18 total `double()` calls remain in lutaml-uml specs.
+
+These don't cause failures and aren't blocking.
+
+## Source
+
+Migrated from `TODO.refactor/11-rewrite-double-based-specs.md`.
+
+## Fix
+
+For each remaining double:
+1. If the doubled interface is a real UML model — instantiate the real model
+   with the needed attributes.
+2. If the doubled interface is a struct/DTO — replace with
+   `Struct.new(:attr1, :attr2).new(val1, val2)`.
+3. Test behavior, not interactions.
+
+## Verification
+
+```bash
+grep -rn 'double(' spec/ | wc -l  # target: 0
+```

data/TODO.next/05-remove-dead-umlrepository-autoloads.md

@@ -0,0 +1,31 @@
+# 05 - Remove Dead Autoload Modules in UmlRepository
+
+## Status: DONE (2026-06-27)
+
+## Problem
+`lib/lutaml/uml_repository.rb` had two pieces of dead code:
+
+1. `module UmlRepositoryComponents` — autoloaded `IndexBuilder`,
+   `StatisticsCalculator`, `PackageExporter`, `PackageLoader` from the
+   same paths as the top-level autoloads already declared above it.
+   Pure DRY violation: no caller ever referenced
+   `Lutaml::UmlRepository::UmlRepositoryComponents::*`. The classes are
+   accessed via the top-level `Lutaml::UmlRepository::IndexBuilder` etc.
+
+2. `module WebUi` with `autoload :App,
+   "lutaml/uml_repository/web_ui/app"` — the target file does not
+   exist. Any attempt to access `Lutaml::UmlRepository::WebUi::App`
+   would raise `LoadError` at runtime. No spec or lib code references
+   this module.
+
+## Fix
+Deleted both module blocks from `lib/lutaml/uml_repository.rb`. No
+behavior change (the autoloads were never triggered). The real
+IndexBuilder/StatisticsCalculator/PackageExporter/PackageLoader
+autoloads at the top of the file are unchanged.
+
+## Verification
+- `bundle exec rspec` in lutaml-uml: 754 examples, 0 failures, 103
+  pending (unchanged from baseline)
+- `grep -rn UmlRepositoryComponents lib/ spec/` → no results
+- `grep -rn "WebUi\b" lib/ spec/` → no results

data/TODO.next/06-cleanup-phantom-requires.md

@@ -0,0 +1,46 @@
+# 06 - Clean Up Phantom Requires and Unused gemspec Dependencies
+
+## Status: DONE (2026-06-29)
+
+## Problem
+`lib/lutaml/uml_repository.rb` declared two top-level requires for gems
+that no code in `lib/` actually uses:
+
+```ruby
+require "liquid"       # no Liquid:: namespace reference anywhere in lib/
+require "lutaml/path"  # no Lutaml::Path usage anywhere in lib/
+```
+
+The gemspec mirrored this with two corresponding runtime dependencies:
+
+```ruby
+spec.add_dependency "liquid"
+spec.add_dependency "lutaml-path"
+```
+
+Both were residue from a Liquid-based rendering pipeline that was
+replaced by the Vue IIFE strategy (`Output::VueInlinedStrategy`). The
+`templates/static_site/*.liquid` files themselves remain on disk but
+nothing loads them at runtime — see [[07-unused-liquid-templates]].
+
+## Fix
+- Removed `require "liquid"` and `require "lutaml/path"` from the top
+  of `lib/lutaml/uml_repository.rb`.
+- Removed `spec.add_dependency "liquid"` and
+  `spec.add_dependency "lutaml-path"` from `lutaml-uml.gemspec`.
+
+No behavior change. Both gems were load-time phantom requires with no
+runtime callers.
+
+## Verification
+- `find lib -name '*.rb' -print0 | xargs -0 grep -l 'Liquid::'` → no results
+- `find lib -name '*.rb' -print0 | xargs -0 grep -l 'Lutaml::Path'` → no results
+- `bundle exec rspec` in lutaml-uml: 754 examples, 0 failures, 103 pending
+  (unchanged from baseline)
+
+## Lesson
+A `require` at the top of a file is a load-time dependency commitment.
+When the code that used the required library is removed or replaced,
+the require statement is often left behind, silently pulling in gems
+that no caller actually needs. Audit requires the same way you audit
+method calls.

data/TODO.next/07-unused-liquid-templates.md

@@ -0,0 +1,42 @@
+# 07 - Unused Liquid Templates (Flag, Don't Delete)
+
+## Status: FLAGGED — preserved per never-delete-source rule
+
+## What
+`templates/static_site/` contains 248K of `.liquid` template files:
+
+```
+templates/static_site/multi_file.liquid
+templates/static_site/single_file.liquid
+templates/static_site/components/{tree_node,diagram_viewer,diagram_list,
+  content,header,package_details,sidebar,class_details,...}.liquid
+```
+
+These were the rendering templates for a Liquid-based static site
+generator. That pipeline was replaced by the Vue 3 IIFE strategy
+(`lib/lutaml/uml_repository/static_site/output/vue_inlined_strategy.rb`).
+The current generator (`static_site/generator.rb`) does not load any
+`.liquid` files and does not reference `Liquid::` anywhere.
+
+`grep -rln 'static_site.*liquid\|\.liquid' lib/` → no results.
+
+## Why not delete
+Per the global rule "NEVER DELETE source files. ANY source file." The
+templates were authored source; their derived output (the Vue strategy)
+existing does not make them disposable. They may be repurposed for a
+future Liquid-rendered export path, kept as reference for templating
+patterns, or moved to a separate gem.
+
+## Suggested resolution (user decision required)
+Three options, none taken yet:
+
+1. **Keep in place** — accept that `templates/` ships unused source.
+   Zero code change; just document.
+2. **Exclude from gem package** — add to gemspec's `spec.files` reject
+   list. Source files stay in git but `gem install` no longer ships
+   them. Minimal blast radius.
+3. **Move to `archive/templates/`** — preserves source on disk, removes
+   from primary tree. Requires a small `spec.files` adjustment.
+
+Until the user picks one, leave the files untouched and the gemspec
+unchanged.

data/TODO.next/08-broken-executables.md

@@ -0,0 +1,60 @@
+# 08 - Broken / Misplaced Executables (Flag, Don't Delete)
+
+## Status: FLAGGED — gemspec ships broken scripts
+
+## What
+The gemspec declares `bindir = "exe"` and
+`spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }`,
+which picks up all four files in `exe/`. Two are broken; two are
+unrelated to lutaml-uml's actual purpose.
+
+| File | Status | Issue |
+|---|---|---|
+| `exe/lutaml` | BROKEN | `require "lutaml"` — no `lib/lutaml.rb` exists. `require "lutaml/cli"` — `lib/lutaml/cli.rb` was removed in commit `e7b5e68` (the EA-extraction refactor) because it was incorrectly classified as EA-specific. |
+| `exe/lutaml-sysml` | BROKEN | `require "reeper"` (long-orphaned gem), plus same `lutaml/cli` issue. |
+| `exe/lutaml-wsd2uml` | UNRELATED | Standalone PlantUML→LutaML converter. No `lutaml/uml` or `lutaml/uml_repository` deps. Belongs in a separate `lutaml-wsd2uml` gem or in `lutaml-lml`. |
+| `exe/lutaml-yaml2uml` | UNRELATED | Standalone YAML→LutaML converter. Same — no lib deps, wrong gem. |
+
+## Why this matters
+`gem install lutaml-uml` currently installs four commands onto the
+user's PATH. Two of them crash immediately on invocation. The other
+two work but are misleading — they suggest the gem does PlantUML and
+YAML conversion, which it does not.
+
+## Root cause
+Commit `e7b5e68` (refactor: remove EA-specific code from lutaml-uml)
+removed `lib/lutaml/cli.rb` along with `lib/lutaml/cli/` because the
+CLI was thought to be EA-flavored. In fact the CLI was a UML/Repository
+CLI (`thor`-based, drove `Lutaml::UmlRepository::Repository`). It should
+have stayed in `lutaml-uml`, or been moved to `lutaml-lml`. The exes
+that called it were left in place, leaving the gem half-gutted.
+
+## Why not delete
+- **Never-delete-source rule** — these exes are source files; deleting
+  them is destructive and irreversible.
+- **Scope uncertainty** — the right fix depends on user intent:
+  - Restore the CLI to lutaml-uml (revert part of e7b5e68)?
+  - Move the CLI to lutaml-lml?
+  - Replace with a new minimal `lutaml-uml` CLI?
+  - Just remove the broken exes from the gemspec (keep files in git)?
+
+## Suggested resolution (user decision required)
+Minimal safe option until user picks a path:
+
+1. Update gemspec to NOT ship the broken/unrelated executables:
+   ```ruby
+   spec.executables = []   # none of the existing exes are functional
+   ```
+   Files stay in git; `gem install` no longer puts broken scripts on PATH.
+
+OR
+
+2. Restore `lib/lutaml/cli.rb` from `git show e7b5e68^:lib/lutaml/cli.rb`
+   and re-wire `exe/lutaml` to drive it. (The CLI uses `lutaml/converter`
+   which would also need to be restored — non-trivial.)
+
+Either way, the standalone `exe/lutaml-wsd2uml` and `exe/lutaml-yaml2uml`
+scripts don't belong in this gem. They should move to `lutaml-lml` or a
+dedicated converter gem, regardless of which CLI option is chosen.
+
+No action taken yet — waiting on user direction.

data/config/package_metadata.example.yml

@@ -0,0 +1,58 @@
+# Package Metadata Configuration Example
+#
+# This file demonstrates how to configure package metadata for use with
+# LutaML's PackageMetadata system.
+#
+# Package metadata enables external configuration of:
+# - XSD generation: xmlns, targetNamespace, schemaLocation
+# - Documentation: Package descriptions
+# - Styling: Package-specific styling rules
+# - Validation: Package constraints
+#
+# Format: YAML with "packages" root key
+
+packages:
+  # Exact package path match
+  "ModelRoot::i-UR::Urban Planning ADE 3.2::uro":
+    xmlns: "http://www.kantei.go.jp/jp/singi/tiiki/toshisaisei/itoshisaisei/iur/uro/2.0"
+    targetNamespace: "http://www.kantei.go.jp/jp/singi/tiiki/toshisaisei/itoshisaisei/iur/uro/2.0"
+    schemaLocation: "../../schemas/uro/2.0/urbanObject.xsd"
+    prefix: "uro"
+    documentation: |
+      Urban Object package containing classes for urban planning and
+      infrastructure modeling in PLATEAU i-UR standard.
+    version: "2.0"
+
+  # Another exact match
+  "ModelRoot::CityGML2.0::Core":
+    xmlns: "http://www.opengis.net/citygml/2.0"
+    targetNamespace: "http://www.opengis.net/citygml/2.0/core"
+    schemaLocation: "http://schemas.opengis.net/citygml/2.0/cityGMLBase.xsd"
+    prefix: "core"
+    documentation: "CityGML 2.0 Core module - fundamental city model classes"
+
+  # Wildcard pattern: matches any direct child of ModelRoot::CityGML2.0
+  "ModelRoot::CityGML2.0::*":
+    xmlns: "http://www.opengis.net/citygml/2.0"
+    prefix: "citygml"
+    documentation: "Default CityGML 2.0 namespace"
+
+  # Multi-level wildcard: matches ModelRoot::<anything>::Common
+  "ModelRoot::*::Common":
+    documentation: "Common elements package"
+    category: "utilities"
+
+  # Package with custom metadata
+  "ModelRoot::CustomPackage":
+    xmlns: "http://example.com/custom/1.0"
+    prefix: "custom"
+    author: "Your Organization"
+    license: "Apache-2.0"
+    contact: "info@example.com"
+
+# Notes:
+# 1. Exact matches take precedence over wildcard patterns
+# 2. Multiple wildcards can match the same package path
+# 3. Metadata from all matches is merged (exact match wins)
+# 4. Any custom keys are supported beyond the standard ones
+# 5. Package paths use "::" as separator (UML qualified name format)