sts 0.5.2 → 0.5.4

data/TODO.sts-refactor/02-type-resolution.md

@@ -0,0 +1,122 @@
+# 02: Type Resolution Anti-Pattern Fix
+
+**Priority**: HIGH
+**Category**: Anti-Pattern Elimination
+**Estimated Effort**: Low
+**Files Affected**: `lib/sts/content_groups/helpers.rb`
+
+## Problem
+
+Current `lib/sts/content_groups/helpers.rb` uses `Object.const_get` for type resolution:
+
+```ruby
+def inject_elements(klass, elements)
+  elements.each do |name, type_name, _, is_collection|
+    type = Object.const_get(type_name)  # Anti-pattern
+    coll = is_collection.nil? || is_collection
+    klass.attribute name, type, collection: coll
+  end
+end
+```
+
+### Why This Is Wrong
+
+1. **`Object.const_get`**: String-based lookup, no compile-time checking, fragile to typos
+2. **Hidden dependency**: No `require` statement indicates the dependency
+3. **Security risk**: Can resolve arbitrary constants if input is user-controlled
+4. **Performance**: Resolved at runtime, not cached efficiently
+
+## Solution
+
+### Option A: Direct Constant Reference
+
+Pass actual class objects instead of strings:
+
+```ruby
+module Sts
+  module ContentGroups
+    module Helpers
+      module_function
+
+      # Elements is now [[:attribute_name, Class, nil, is_collection?], ...]
+      def inject_elements(klass, elements)
+        elements.each do |name, type, _, is_collection|
+          coll = is_collection.nil? || is_collection
+          klass.attribute name, type, collection: coll
+        end
+      end
+
+      def inject_element_mappings(klass, mappings)
+        mappings.each do |xml_name, type, ruby_name|
+          klass.xml { map_element xml_name, to: ruby_name }
+        end
+      end
+    end
+  end
+end
+```
+
+### Option B: Register-Based Resolution
+
+Use lutaml-model's register system:
+
+```ruby
+module Sts
+  module ContentGroups
+    module Helpers
+      module_function
+
+      def resolve_type(type_identifier)
+        case type_identifier
+        when Module then type_identifier
+        when Symbol
+          Lutaml::Model::GlobalRegister.resolve(type_identifier) ||
+            raise(ArgumentError, "Unknown type: #{type_identifier}")
+        else
+          raise(TypeError, "Expected Module or Symbol, got #{type_identifier.class}")
+        end
+      end
+
+      def inject_elements(klass, elements)
+        elements.each do |name, type, _, is_collection|
+          resolved_type = resolve_type(type)
+          coll = is_collection.nil? || is_collection
+          klass.attribute name, resolved_type, collection: coll
+        end
+      end
+    end
+  end
+end
+```
+
+## Files Using This Helper
+
+Need to update all callers to pass class objects:
+
+```bash
+grep -r "inject_elements\|inject_element_mappings" lib/sts/
+```
+
+Expected to find calls in:
+- `lib/sts/iso_sts/content_groups/*.rb`
+- `lib/sts/niso_sts/content_groups/*.rb`
+
+## Verification
+
+1. All callers pass actual class constants, not strings
+2. `bundle exec rubocop lib/sts/content_groups/helpers.rb` passes
+3. All specs pass — types resolved at class definition time
+
+## Dependencies
+
+None — can be done independently.
+
+## TODO Checklist
+
+- [ ] Read `lib/sts/content_groups/helpers.rb`
+- [ ] Find all callers: `grep -r "inject_elements\|inject_element_mappings" lib/sts/`
+- [ ] Choose Option A or B
+- [ ] Update helper methods
+- [ ] Update all callers to pass class objects
+- [ ] Verify no `Object.const_get` remains
+- [ ] Run full test suite

data/TODO.sts-refactor/03-namespace-coupling.md

@@ -0,0 +1,158 @@
+# 03: Namespace Coupling Architecture Fix
+
+**Priority**: HIGH
+**Category**: Architecture
+**Estimated Effort**: High
+**Files Affected**: `lib/sts/iso_sts/content_groups/highlight_elements.rb` (194+ references)
+
+## Problem
+
+`lib/sts/iso_sts/content_groups/highlight_elements.rb` contains 194+ references to `Sts::NisoSts::*` types:
+
+```ruby
+# Examples from highlight_elements.rb
+[:sub, "Sts::NisoSts::Sub", "sub"]
+[:sup, "Sts::NisoSts::Sup", "sup"]
+[:italic, "Sts::NisoSts::Italic", "italic"]
+[:bold, "Sts::NisoSts::Bold", "bold"]
+# ... 190 more
+```
+
+### Why This Is Wrong
+
+1. **Violation of namespace isolation**: IsoSts should not depend on NisoSts implementation
+2. **Shared-namespace ambiguity**: These elements appear in both ISOSTS and NISO STS but with different attribute sets
+3. **Tight coupling**: Changes to NisoSts can break IsoSts
+4. **Schema divergence ignored**: `<p>` in ISOSTS has different attributes than `<p>` in NISO STS Extended
+
+### Root Cause
+
+The schemas ARE different:
+- ISOSTS `<p>`: `@content-type, @id, @specific-use, @xml:lang`
+- NISO STS Extended `<p>`: `@content-type, @id, @originator, @specific-use, @style-type, @xml:base, @xml:lang`
+
+## Solution: Three-Tier Architecture
+
+### Tier 1: Shared Base Types
+
+Create shared types in `Sts::Base` that both namespaces inherit:
+
+```ruby
+# lib/sts/base/text/emphasis.rb
+module Sts
+  module Base
+    module Text
+      class Emphasis < Lutaml::Model::Serializable
+        # Shared attributes/methods
+        attribute :id, :string
+        attribute :base_fontsize, :string
+        attribute :baseline_shift, :string
+        attribute :color, :string
+
+        xml do
+          map_attribute :id, to: :id
+          # ...
+        end
+      end
+
+      class Bold < Emphasis
+        xml { element "bold" }
+      end
+
+      class Italic < Emphasis
+        xml { element "italic" }
+      end
+
+      class Sub < Emphasis
+        xml { element "sub" }
+      end
+
+      class Sup < Emphasis
+        xml { element "sup" }
+      end
+    end
+  end
+end
+```
+
+### Tier 2: IsoSts-Specific Extensions
+
+```ruby
+# lib/sts/iso_sts/text/emphasis.rb
+module Sts
+  module IsoSts
+    module Text
+      class Bold < ::Sts::Base::Text::Bold
+        # Add IsoSts-specific attributes
+        attribute :content_type, :string
+
+        xml do
+          # Override/add IsoSts-specific mapping
+          map_attribute "content-type", to: :content_type
+        end
+      end
+    end
+  end
+end
+```
+
+### Tier 3: NisoSts-Specific Extensions
+
+```ruby
+# lib/sts/niso_sts/text/emphasis.rb
+module Sts
+  module NisoSts
+    module Text
+      class Bold < ::Sts::Base::Text::Bold
+        # Add NisoSts-specific attributes
+        attribute :originator, :string
+        attribute :style_type, :string
+
+        xml do
+          map_attribute "originator", to: :originator
+          map_attribute "style-type", to: :style_type
+        end
+      end
+    end
+  end
+end
+```
+
+## Implementation Strategy
+
+1. **Phase 1**: Identify all shared element types (bold, italic, sub, sup, p, etc.)
+2. **Phase 2**: Create base types with MINIMAL shared attributes
+3. **Phase 3**: Refactor IsoSts to extend bases
+4. **Phase 4**: Refactor NisoSts to extend bases
+5. **Phase 5**: Delete `Sts::NisoSts::*` references from IsoSts content groups
+
+## Files to Refactor
+
+Primary targets:
+- `lib/sts/iso_sts/content_groups/highlight_elements.rb`
+- `lib/sts/iso_sts/content_groups/emphasis_elements.rb` (if exists)
+- `lib/sts/niso_sts/content_groups/highlight_elements.rb`
+
+## Verification
+
+1. No `Sts::NisoSts` references in `lib/sts/iso_sts/`
+2. All round-trip tests pass
+3. Schema validation against both ISOSTS DTD and NISO STS XSD passes
+
+## Dependencies
+
+- `01-mathml-delegation.md` — uses similar patterns
+- `02-type-resolution.md` — must be clean first
+
+## TODO Checklist
+
+- [ ] Audit all IsoSts → NisoSts references
+- [ ] Categorize by shared vs. truly namespace-specific
+- [ ] Design base type hierarchy
+- [ ] Create `lib/sts/base/` directory structure
+- [ ] Implement base types for shared elements
+- [ ] Refactor IsoSts to use base types
+- [ ] Refactor NisoSts to use base types
+- [ ] Remove cross-namespace references
+- [ ] Verify no circular dependencies
+- [ ] Run full test suite

data/TODO.sts-refactor/04-register-versioning.md

@@ -0,0 +1,180 @@
+# 04: Schema Versioning via lutaml-model Registers
+
+**Priority**: HIGH
+**Category**: Architecture
+**Estimated Effort**: Very High
+**Files Affected**: New architecture, all model files
+
+## Problem
+
+Currently sts-ruby uses flat module namespaces (`IsoSts`, `NisoSts`) with no versioning. Real-world standards have multiple schema versions that differ in element sets and attributes:
+
+- **ISOSTS v1.1** (2013, frozen DTD)
+- **NISO STS 1.0** (2017, DTD/XSD/RNG, interchange + extended)
+- **NISO STS 1.2** (2022, backwards compatible with NISO STS 1.0)
+
+Schema differences exist on the same element names (e.g., `<p>` attributes differ between ISOSTS and NISO STS Extended).
+
+## Reference: mml Gem Pattern
+
+The mml gem provides the correct versioning architecture:
+
+```
+mml/
+├── lib/mml.rb                    # Top-level entry, requires version modules
+├── lib/mml/
+│   ├── base/                     # Shared mixins via `included` hook
+│   │   ├── math.rb               # Mml::Base::Math module
+│   │   ├── mi.rb                 # Mml::Base::Mi module
+│   │   └── ...
+│   ├── v2/                       # MathML 2.0 versioned classes
+│   │   ├── math.rb               # Mml::V2::Math < Serializable; includes Mml::Base::Math
+│   │   ├── mi.rb                 # Mml::V2::Mi < Serializable; includes Mml::Base::Mi
+│   │   └── configuration.rb      # Mml::V2::Configuration with CONTEXT_ID = :mml_v2
+│   ├── v3/                       # MathML 3.0 versioned classes
+│   │   ├── math.rb               # Mml::V3::Math < Serializable; includes Mml::Base::Math
+│   │   ├── configuration.rb      # Mml::V3::Configuration with CONTEXT_ID = :mml_v3
+│   │   └── ...
+│   └── configuration.rb          # Mml::Configuration, dispatches to version
+```
+
+### Key Mechanisms
+
+1. **Register per version**: Each version creates a `Lutaml::Model::Register` with unique ID
+2. **`lutaml_default_register`**: Class method on each versioned class points to its register
+3. **Shared modules**: `Mml::Base::*` mixins define shared attributes/behavior via `included` hook
+4. **Version-specific classes**: `Mml::V3::Math` extends shared module with V3-specific attributes
+
+```ruby
+# From mml gem
+module Mml
+  module V3
+    class Configuration
+      CONTEXT_ID = :mml_v3
+
+      def self.register_model(klass, id:)
+        register = Lutaml::Model::Register.new(id: CONTEXT_ID)
+        register.register_model(klass, id: id)
+        klass.define_singleton_method(:lutaml_default_register) { register }
+      end
+    end
+  end
+end
+```
+
+## Proposed Architecture for sts-ruby
+
+```
+lib/sts/
+├── base/                         # Shared element modules (Tier 1)
+│   ├── text/                     # Bold, Italic, Sub, Sup, etc.
+│   ├── struct/                   # Section, Paragraph, List, etc.
+│   ├── meta/                     # Title, Label, Caption, etc.
+│   └── refs/                     # Xref, BiblioRef, etc.
+├── iso_sts/                      # ISOSTS v1.1 (frozen)
+│   ├── v1_1/                     # ISOSTS v1.1 classes
+│   │   ├── standard.rb           # IsoSts::V1_1::Standard
+│   │   ├── paragraph.rb          # IsoSts::V1_1::Paragraph (ISOSTS-specific attributes)
+│   │   └── configuration.rb      # IsoSts::V1_1::Configuration
+│   └── iso_sts.rb
+├── niso_sts/                     # NISO STS (evolving)
+│   ├── v1_0/                     # NISO STS 1.0 classes
+│   │   ├── standard.rb           # NisoSts::V1_0::Standard
+│   │   ├── paragraph.rb          # NisoSts::V1_0::Paragraph
+│   │   └── configuration.rb      # NisoSts::V1_0::Configuration
+│   ├── v1_2/                     # NISO STS 1.2 classes (extends v1_0)
+│   │   ├── processing_meta.rb    # New in 1.2
+│   │   ├── code.rb               # New in 1.2
+│   │   ├── standard.rb           # NisoSts::V1_2::Standard (adds processing-meta)
+│   │   └── configuration.rb      # NisoSts::V1_2::Configuration
+│   └── niso_sts.rb
+├── tbx_iso_tml/                  # TBX (versioned with ISO 30042)
+└── sts.rb                        # Top-level entry point
+```
+
+### Register Registration Pattern
+
+```ruby
+module Sts
+  module NisoSts
+    module V1_0
+      class Configuration
+        CONTEXT_ID = :niso_sts_v1_0
+
+        def self.setup!
+          register = Lutaml::Model::Register.new(id: CONTEXT_ID)
+          # Register all V1_0 models
+          Dir[File.join(__dir__, '*.rb')].sort.each do |f|
+            require f
+          end
+          # Set default register for each class
+          constants.each do |c|
+            klass = const_get(c)
+            next unless klass.is_a?(Class) && klass < Lutaml::Model::Serializable
+            klass.define_singleton_method(:lutaml_default_register) { register }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Migration Strategy
+
+### Phase 1: Create Register Infrastructure
+- Create `Sts::Configuration` with register setup
+- Create base register for `:iso_sts_v1_1` and `:niso_sts_v1_0`
+
+### Phase 2: Create Base Types
+- Extract shared elements from both namespaces into `Sts::Base::*`
+- See `03-namespace-coupling.md` for details
+
+### Phase 3: Version the Models
+- Rename current `Sts::IsoSts::*` → `Sts::IsoSts::V1_1::*`
+- Rename current `Sts::NisoSts::*` → `Sts::NisoSts::V1_0::*`
+- Set `lutaml_default_register` on each versioned class
+
+### Phase 4: Backward Compatibility Shims
+- Provide temporary aliases at current paths:
+  ```ruby
+  module Sts
+    module IsoSts
+      # Temporary backward compat - remove in next major version
+      Standard = V1_1::Standard
+    end
+  end
+  ```
+- Mark for deprecation in next major release
+
+### Phase 5: Add NISO STS 1.2 Support
+- Create `Sts::NisoSts::V1_2` namespace
+- Extend V1_0 models with 1.2 additions
+- See `05-missing-elements.md` for NISO STS 1.2 additions
+
+## Verification
+
+1. `bundle exec rspec` passes with versioned model loading
+2. ISOSTS documents parse with ISOSTS register
+3. NISO STS 1.0 documents parse with NISO STS 1.0 register
+4. No cross-register contamination
+
+## Dependencies
+
+- `01-mathml-delegation.md` — MathML already follows this pattern
+- `02-type-resolution.md` — Register provides type resolution
+- `03-namespace-coupling.md` — Base types needed for versioning
+
+## TODO Checklist
+
+- [ ] Read `lutaml-model` register/global_register source
+- [ ] Read mml gem's versioning pattern fully
+- [ ] Design sts-ruby register architecture
+- [ ] Create `Sts::Configuration` with register setup
+- [ ] Phase 1: Register infrastructure
+- [ ] Phase 2: Base types (coordinated with 03-namespace-coupling)
+- [ ] Phase 3: Version models
+- [ ] Phase 4: Backward compat shims
+- [ ] Phase 5: NISO STS 1.2 support
+- [ ] Update tests for versioned parsing
+- [ ] Document API changes

data/TODO.sts-refactor/05-missing-elements.md

@@ -0,0 +1,195 @@
+# 05: Missing Elements Implementation
+
+**Priority**: HIGH
+**Category**: Feature Gap
+**Estimated Effort**: High
+**Files Affected**: New model files, autoload entries
+
+## Elements Missing from sts-ruby
+
+### Critical (Round-Trip Impact)
+
+#### `<processing-meta>` (NISO STS 1.2)
+- **Parent**: `<standard>` (peer to `<front>`, `<body>`, `<back>`)
+- **Attributes**: `@tagset-family`, `@base-tagset`, `@table-model`, `@mathml`, `@math-representation`, `@terminology-model`
+- **Children**: `<extended-by>`, `<restricted-by>`, `<custom-meta-group>`
+- **Reference**: NISO STS 1.2 comparison doc, Section 3
+
+#### `<code>` (NISO STS 1.2)
+- **Parents**: `<p>`, `<sec>`, `<list-item>`, and many block contexts
+- **Attributes**: `@code-type`, `@code-version`, `@content-type`, `@executable`, `@id`, `@language`, `@language-version`, `@xml:base`, `@xml:lang`
+- **Content**: Mixed (text + inline elements)
+- **Reference**: NISO STS 1.2, Section 4
+
+#### `<inline-code>` (NISO STS 1.2)
+- **Parents**: Inline contexts
+- **Attributes**: Same pattern as `<code>` but for inline usage
+- **Reference**: NISO STS 1.2, Section 4
+
+#### `<legend>` (NISO STS 1.2)
+- **Parents**: `<boxed-text>`, `<chem-struct-wrap>`, `<disp-formula>`, `<disp-formula-group>`, `<fig>`, `<fig-group>`, `<graphic>`, `<media>`, `<supplementary-material>`, `<table-wrap>`, `<table-wrap-group>`
+- **Children**: Mixed content with emphasis elements
+- **Reference**: NISO STS 1.2, Section 4
+
+#### `<inline-media>` (NISO STS 1.2)
+- **Parents**: Inline contexts
+- **Attributes**: Standard media attributes
+- **Reference**: NISO STS 1.2, Section 4
+
+#### `<sub-part-number>` (NISO STS 1.2)
+- **Parent**: `<std-ident>`
+- **Content**: String
+- **Reference**: NISO STS 1.2, Section 4
+
+#### `<index>` Hierarchy
+- `<index>` — container for back matter index
+- `<index-div>` — index division
+- `<index-entry>` — individual index entry
+- `<index-title-group>` — index title
+- `<index-term-range-end>` — range end marker
+- `<see-entry>` — "see" cross-reference
+- `<see-also-entry>` — "see also" cross-reference
+- **Reference**: GAPS.guidelines.schema-xref.md
+
+#### `<toc>` Hierarchy
+- `<toc>` — table of contents container (in `<front>`)
+- `<toc-div>` — TOC division
+- `<toc-entry>` — TOC entry
+- `<toc-title-group>` — TOC title
+- `<toc-group>` — TOC group (in `<sec>`)
+- **Reference**: GAPS.guidelines.schema-xrf.md
+
+#### `<table-wrap-group>`
+- **Parents**: `<sec>`, `<app>`
+- **Children**: `<table-wrap>` collection
+- **Reference**: GAPS.guidelines.schema-xref.md
+
+#### `<sec-meta>`
+- **Parent**: `<sec>`
+- **Content**: Section metadata
+- **Reference**: GAPS.guidelines.schema-xref.md
+
+#### `<std-doc-meta>`
+- **Parent**: `<front>`
+- **Content**: Standard document metadata
+- **Reference**: GAPS.guidelines.schema-xref.md
+
+### Table Model (OASIS CALS) — Lower Priority
+
+| Element | Notes |
+|---------|-------|
+| `<tgroup>` | Table group with column specs |
+| `<colspec>` | Column specification |
+| `<row>` | Table row |
+| `<entry>` | Table cell |
+
+Most modern ISO documents use XHTML tables. OASIS CALS needed for legacy documents.
+
+### Less Critical / Edge Cases
+
+| Element | Notes |
+|---------|-------|
+| `<abbrev>` | Abbreviation display element |
+| `<article-categories>` | JATS legacy — skip for NISO STS |
+| `<article-id>` | JATS legacy — skip |
+| `<article-meta>` | JATS legacy — skip |
+| `<compl-title-wrap>` | Complementary title wrap |
+| `<compound-subject>` | Compound subject |
+| `<compound-subject-part>` | Part of compound subject |
+| `<count>` | Count element |
+| `<fallback>` | Alternatives fallback |
+| `<fixed-case>` | Fixed-case text |
+| `<free_to_read>` | ALI namespace |
+| `<glyph-data>` | Private character glyph data |
+| `<glyph-ref>` | Private character glyph reference |
+| `<include>` | XInclude element |
+| `<intro-title-wrap>` | Introduction title wrap |
+| `<issue-id>` | Journal issue ID — skip |
+| `<issue-part>` | Journal issue part — skip |
+| `<issue-sponsor>` | Journal issue sponsor — skip |
+| `<issue-title>` | Journal issue title — skip |
+| `<journal-id>` | Journal ID — skip |
+| `<license_ref>` | ALI license reference |
+| `<main-title-wrap>` | Main title wrap |
+| `<nav-pointer>` | Navigation pointer |
+| `<nav-pointer-group>` | Navigation pointer group |
+| `<num>` | Number element |
+| `<overline-end>` | Overline end marker |
+| `<overline-start>` | Overline start marker |
+| `<part-title>` | Part title |
+| `<sub-part>` | Sub-part element |
+| `<title-group>` | Title group |
+| `<trans-subtitle>` | Translated subtitle |
+| `<underline-end>` | Underline end marker |
+| `<underline-start>` | Underline start marker |
+| `<term-display-string>` | New in NISO STS 1.2 |
+
+## Implementation Order
+
+1. `<processing-meta>` — needed for schema validation routing
+2. `<code>` and `<inline-code>` — high frequency in real documents
+3. `<legend>` — needed for formula/figure keys
+4. `<inline-media>` — straightforward
+5. `<index>` hierarchy — needed for back matter
+6. `<toc>` hierarchy — needed for front matter
+7. `<table-wrap-group>` — grouped table handling
+8. `<sec-meta>` and `<std-doc-meta>` — structural metadata
+9. OASIS CALS tables — legacy support
+10. Edge case elements — as needed
+
+## File Structure
+
+Each new element follows the established pattern:
+
+```ruby
+# lib/sts/niso_sts/processing_meta.rb
+module Sts
+  module NisoSts
+    class ProcessingMeta < Lutaml::Model::Serializable
+      attribute :tagset_family, :string
+      attribute :base_tagset, :string
+      attribute :table_model, :string
+      attribute :mathml, :string
+      attribute :math_representation, :string
+      attribute :terminology_model, :string
+      attribute :extended_by, ExtendedBy, collection: true
+      attribute :restricted_by, RestrictedBy, collection: true
+      attribute :custom_meta_group, CustomMetaGroup
+
+      xml do
+        element "processing-meta"
+        map_attribute "tagset-family", to: :tagset_family
+        map_attribute "base-tagset", to: :base_tagset
+        map_attribute "table-model", to: :table_model
+        map_attribute "mathml", to: :mathml
+        map_attribute "math-representation", to: :math_representation
+        map_attribute "terminology-model", to: :terminology_model
+        map_element "extended-by", to: :extended_by
+        map_element "restricted-by", to: :restricted_by
+        map_element "custom-meta-group", to: :custom_meta_group
+      end
+    end
+  end
+end
+```
+
+## Dependencies
+
+- `04-register-versioning.md` — new elements should be registered in appropriate version namespace
+
+## TODO Checklist
+
+- [x] `<processing-meta>` with all attributes
+- [x] `<code>` and `<inline-code>`
+- [x] `<legend>`
+- [x] `<inline-media>`
+- [x] `<sub-part-number>` in `<std-ident>`
+- [x] `<index>` hierarchy (7 elements)
+- [x] `<toc>` hierarchy (5 elements)
+- [x] `<table-wrap-group>`
+- [x] `<sec-meta>`
+- [x] `<std-doc-meta>` (expanded to full XSD model)
+- [x] `<term-display-string>` (NISO STS 1.2)
+- [ ] OASIS CALS table elements
+- [x] Update autoload entries for all new elements
+- [x] Add/update round-trip tests for each element