sts 0.6.8 → 0.6.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd02c307a6e1d5f238e8e05db78958bf73d1bc05c98c170ad89005fb205c7e88
-  data.tar.gz: 0bc64d38cf7f5ffd0151db213b9cc99dd25ca979b9eacabf0fb5b7f78b4b19af
+  metadata.gz: 55257a4c0bd11d4374ea655ffdef2d2a51c1e2fe8761cabbe450188065b85cb6
+  data.tar.gz: afe4c91a2e1b739eeffee4d044e8ea03b28774d43146aafdbd2d744d7577880a
 SHA512:
-  metadata.gz: 421983c008de22adbe0ca5b7e101590d1a025b76582acb6c750d4d7ebad8582abd9bfa12386ed119d11e9ac2e5ccfe6d6f1216f991ce457fc18e98dd5a86ed91
-  data.tar.gz: d0d7b00dbd0c8c53268c561fdb965228e753f90c7cc52c0c9c3fa842ba22d4a105232a2b0b0bec778387e86e1c76e6fd3f95e6bad3f1593e5c566e126f3d8b42
+  metadata.gz: be6961ce1a6581c1fa6d7a51cb80253a99e01d53fabb31cb3d4feff43f8d87f7a2b283b3fbb8aa07ad31a91e4ac0a634e1bbbcbbf5dce733f45ad93bc77fdfc8
+  data.tar.gz: 9c476be12a1c7d51c9552892c2ad0bd677f16677e10587865d5a127ff20cf1be67b9e241a17e90155845ba704b58b404317cd1292bd138ddd00a182b875cb01e

data/.rubocop_todo.yml

@@ -24,6 +24,7 @@ Layout/LineLength:
     - 'lib/sts/tbx_iso_tml/lang_set.rb'
     - 'lib/sts/tbx_iso_tml/term_type.rb'
     - 'spec/elements/new_elements_spec.rb'
+    - 'spec/iso_sts/schema_validation_spec.rb'
     - 'spec/round_trip/reference_docs_spec.rb'
     - 'spec/spec_helper.rb'
 
@@ -73,6 +74,7 @@ RSpec/DescribeClass:
     - 'spec/fn_namespace_spec.rb'
     - 'spec/mathml_version_spec.rb'
     - 'spec/round_trip/reference_docs_spec.rb'
+    - 'spec/iso_sts/schema_validation_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -124,3 +126,4 @@ RSpec/SpecFilePathFormat:
     - 'spec/sts_table_spec.rb'
     - 'spec/iso_sts/iso_sts_spec.rb'
     - 'spec/iso_sts/iso_sts_element_spec.rb'
+    - 'spec/iso_sts/schema_validation_spec.rb'

data/CLAUDE.md

@@ -1,58 +1,84 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) for working with code in this repository.
 
 ## Build and Test Commands
 
 ```bash
-# Run tests
+# Run all tests + rubocop (default task)
+bundle exec rake
+
+# Run tests only
 bundle exec rspec
 
-# Run tests with specific file
-bundle exec rspec spec/sts_spec.rb
+# Run a specific spec file
+bundle exec rspec spec/iso_sts/iso_sts_element_spec.rb
 
-# Run RuboCop linting
+# Run rubocop
 bundle exec rubocop
 
-# Run both (default task)
-bundle exec rake
+# Auto-fix linting offenses
+bundle exec rubocop -a
 ```
 
 ## Architecture
 
-This is a Ruby gem for parsing NISO STS (National Information Standards Organization - Science and Technical Standards) XML documents. It uses `lutaml-model` for XML serialization/deserialization.
+sts-ruby is a Ruby gem for parsing and serialising NISO STS, ISOSTS, and
+TBX-ISO-TML XML documents. It uses `lutaml-model` for declarative
+serialisation.
 
-### Namespace Structure
+### Namespace structure
 
 ```
 Sts
-├── NisoSts        # NISO STS elements (lib/sts/niso_sts/)
-│   ├── MmlContent # MathML content elements (autoloaded)
-│   └── Xi, Ali   # Module elements
-├── TbxIsoTml     # TBX ISO TML elements (lib/sts/tbx_iso_tml/)
-├── Mathml        # MathML namespace wrapper
-└── Namespaces    # XML namespace definitions
+├── IsoSts         # ISOSTS v1.1 (frozen legacy, 2013 DTD)
+├── NisoSts        # NISO STS (evolving: 1.0, 1.2)
+├── TbxIsoTml      # TBX-ISO-TML (ISO 30042, shared)
+├── Namespaces     # XML namespace class declarations (TbxNamespace)
+├── Profiles       # ISO/IEC document profile validator
+└── VERSION
 ```
 
-### Key Implementation Patterns
+### Architectural principle: namespace independence
+
+ISOSTS and NISO STS are independent schemas that genuinely diverge.
+Each `Sts::<Namespace>::<Class>` is modelled from its own schema source
+(`reference-docs/isosts-v1/xsd/ISOSTS.xsd` for IsoSts,
+`reference-docs/NISO-STS-extended-1-MathML3-XSD/` for NisoSts). NEVER:
+
+- Alias `IsoSts::<X> = NisoSts::<X>` (couples the namespaces)
+- Create a shared `Sts::Base::<X>` that both inherit from
+- Reuse NisoSts types inside IsoSts or vice versa
+
+TBX is shared (used by both IsoSts and NisoSts hosts), so cross-references
+to `TbxIsoTml::*` are permitted — but each TbxIsoTml class must be a
+true TBX-ISO-TML element, not a JATS/NISO STS element misplaced.
+
+See `TODO.roadmap/00-overview.md` for the prioritised roadmap of remaining
+work.
+
+### MathML host binding
+
+ISOSTS imports `ncbi-mathml2/mathml2.xsd` (MathML 2). NISO STS uses
+MathML 3. TBX-ISO-TML is hosted under either. Bind per host:
 
-**Element Classes** (in `lib/sts/niso_sts/`):
-- Inherit from `Lutaml::Model::Serializable`
-- Define attributes and XML mapping in `xml do ... end` block
-- Use `map_element` to map child elements, `map_content` for text content
-- Use `mixed_content` for elements that contain both text and child elements
+- `IsoSts::*` math attributes → `Mml::V2::Math`
+- `TbxIsoTml::*` math attributes → `Mml::V2::Math` (TBX-in-ISOSTS only)
+- `NisoSts::*` math attributes → `Mml::V3::Math`
+
+### Element class pattern
 
-**Example element structure:**
 ```ruby
 module Sts
-  module NisoSts
+  module IsoSts
     class SomeElement < Lutaml::Model::Serializable
       attribute :id, :string
-      attribute :content, :string
-      attribute :child, ::Sts::NisoSts::ChildElement
+      attribute :content, :string, collection: true
+      attribute :child, ::Sts::IsoSts::ChildElement, collection: true
 
       xml do
         element "some-element"
+        ordered                 # preserve child order on serialise
         map_attribute "id", to: :id
         map_content to: :content
         map_element "child", to: :child
@@ -62,11 +88,55 @@ module Sts
 end
 ```
 
-**Autoload Pattern**: Elements are autoloaded via `lib/sts/niso_sts.rb`. When adding new elements, add autoloads in alphabetical order.
+### Autoload convention
+
+`lib/sts.rb` autoloads top-level namespaces. `lib/sts/<namespace>.rb`
+autoloads every class in that namespace, organised by category with
+leading comments and alphabetical order within each group.
+
+External gems are eager-required at the top of `lib/sts.rb`
+(`require "lutaml/model"`, `require "mml"`). Internal code never uses
+`require_relative` or `require` with internal paths — autoload only.
+Enforced by `spec/anti_patterns_spec.rb`.
+
+### Anti-patterns (forbidden; enforced by spec)
+
+`spec/anti_patterns_spec.rb` runs 9 per-file checks on every `lib/` file:
+
+- `method_missing`, `respond_to_missing?` — forbidden (hides interfaces)
+- `Object.const_get` — forbidden (runtime string lookup)
+- `.send(` — forbidden (bypasses access control)
+- `instance_variable_set` / `instance_variable_get` — forbidden (breaks encapsulation)
+- `respond_to?` type-checks — forbidden (use `is_a?` or redesign so the check isn't needed)
+- Hand-rolled serialization methods on `Serializable` subclasses:
+  `to_h`, `to_hash`, `from_h`, `from_hash`, `to_json`, `from_json`,
+  `serialize`, `deserialize`, `to_xml`, `from_xml` — forbidden
+  (use `attribute` + `mapping`; framework-generated serialisation is correct)
+- `require_relative` in lib/ — forbidden (use autoload)
+- `require` with internal library path — forbidden (use autoload;
+  external gems like `lutaml/model` are allowlisted)
+
+### Schema authority
+
+For any new IsoSts element, generate the attribute list from
+`reference-docs/isosts-v1/xsd/ISOSTS.xsd` directly. Don't copy from
+NisoSts — the schemas disagree on most elements. Attribute-list
+specifications ("X models its configured attribute set") are the
+project's defence against drift, since round-tripping alone cannot prove
+schema conformance.
+
+### Spec patterns
 
-**Bold/Italic Elements**: These use `::Sts::TbxIsoTml::Bold` and `::Sts::TbxIsoTml::Italic` types (not `:string`), enabling proper round-tripping of nested markup.
+- **Attribute-set assertions** — `expect(Foo.attributes.keys).to match_array(%i[id content_type ...])`
+- **Child-type assertions** — `expect(Bar.attributes[:foo].type).to eq(Baz)`
+- **Round-trip tests** — `expect(Foo.to_xml(Foo.from_xml(xml))).to be_xml_equivalent_to(xml)`
+- **Schema-validation tests** — `spec/schema_validation_spec.rb` validates
+  IsoSts output against ISOSTS.xsd directly via Nokogiri::XML::Schema
 
-### Reference Data
+### Reference data
 
-- XSD schema: `reference-docs/NISO-STS-extended-1-MathML3-XSD/`
+- ISOSTS XSD: `reference-docs/isosts-v1/xsd/ISOSTS.xsd`
+- NISO STS XSD: `reference-docs/NISO-STS-extended-1-MathML3-XSD/`
+- TBX schema (under ISOSTS): `reference-docs/isosts-v1/xsd/tbx.xsd`
 - Test fixtures: `spec/fixtures/`
+- TODO roadmap: `TODO.roadmap/`

data/README.adoc

@@ -140,23 +140,26 @@ sts.class.name # => "Sts::IsoSts::Standard"
 
 ==== ISOSTS MathML 2
 
-ISOSTS uses MathML 2 (not MathML 3+ like NISO STS). A custom Ruby implementation is provided in `Sts::IsoSts::Mathml2::*`:
+ISOSTS uses MathML 2 (not MathML 3 like NISO STS). All MathML is provided
+by the mml gem, bound per host:
+
+* `IsoSts::*` math attributes → `Mml::V2::Math`
+* `TbxIsoTml::*` math attributes → `Mml::V2::Math` (TBX-in-ISOSTS only)
+* `NisoSts::*` math attributes → `Mml::V3::Math`
 
 [source,ruby]
 ----
-# Access MathML 2 content
 disp_formula = sts.body.sec.first.disp_formula
-math = disp_formula.math  # => Sts::IsoSts::Mathml2::Math
-
-# MathML 2 elements
-math.id          # => "mml_1"
-math.display     # => "block" or "inline"
+math = disp_formula.math  # => Mml::V2::Math
 
-# Serialized as mml:math
-math.to_xml      # => <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" ...>
+# Round-trip preserves mml: prefix
+disp_formula.to_xml       # => <disp-formula><mml:math ...>...</mml:math></disp-formula>
 ----
 
-Available MathML 2 elements: `Math`, `Mrow`, `Mi`, `Mn`, `Mo`, `Mtext`, `Mspace`, `Msub`, `Msup`, `Msubsup`, `Mfrac`, `Msqrt`, `Mroot`, `Mstyle`, `Menclose`, `Mpadded`, `Mphantom`, `Mtable`, `Mtr`, `Mtd`, `Mlabeledtr`, `Mfenced`, `Semantics`, `Annotation`, `AnnotationXml`
+MathML 2 and 3 share the same XML namespace (`http://www.w3.org/1998/Math/MathML`),
+so `Mml::Namespace` (the mml gem's top-level namespace class) is used
+directly in both `IsoSts::Standard#namespace_scope` and
+`NisoSts::Standard#namespace_scope`.
 
 ==== ISOSTS TBX Terminology
 
@@ -191,6 +194,42 @@ sts = Sts::NisoSts::Standard.from_xml(xml_with_tbx)
 sts = Sts::IsoSts::Standard.from_xml(xml_with_tbx)
 ----
 
+== Architecture principles
+
+=== Namespace independence
+
+`IsoSts`, `NisoSts`, and `TbxIsoTml` are independent schemas that
+genuinely diverge. Each `Sts::<Namespace>::<Class>` is modelled from its
+own schema source — never aliased across namespaces, never sharing base
+classes. The schemas disagree on most elements (e.g., `IsoSts::Fig` has
+`title`/`alternatives` that `NisoSts::Figure` lacks), so sharing types
+would fight the schemas and violate the Open/Closed principle.
+
+=== Anti-pattern enforcement
+
+`spec/anti_patterns_spec.rb` runs 9 per-file checks across `lib/` to
+forbid: `method_missing`, `respond_to_missing?`, `Object.const_get`,
+`.send(`, `instance_variable_set`/`get`, `respond_to?` type-checks,
+hand-rolled serialization methods on `Serializable` subclasses
+(`to_h`, `to_xml`, `from_xml`, etc.), `require_relative`, and
+internal `require`. See `CLAUDE.md` for the rationale.
+
+=== Schema validation
+
+`spec/schema_validation_spec.rb` validates IsoSts output against the
+canonical `reference-docs/isosts-v1/xsd/ISOSTS.xsd` via
+`Nokogiri::XML::Schema`. Round-tripping alone cannot prove schema
+conformance (a model that invents or drops an attribute still
+round-trips symmetrically); the XSD is the only authoritative check.
+
+=== Autoload convention
+
+`lib/sts.rb` autoloads top-level namespaces. Each namespace's
+`lib/sts/<namespace>.rb` autoloads every class in alphabetical order
+within category groups. External gems (`lutaml/model`, `mml`) are
+eager-required at the top of `lib/sts.rb`; internal code uses autoload
+only — no `require_relative`, no `require "sts/..."`.
+
 == Credits
 
 This gem is developed, maintained and funded by

data/lib/sts/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sts
-  VERSION = "0.6.8"
+  VERSION = "0.6.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sts
 version: !ruby/object:Gem::Version
-  version: 0.6.8
+  version: 0.6.9
 platform: ruby
 authors:
 - Ribose