chemicalml 0.2.0 → 0.2.1

data/TODO.align/50-validation-report.md

@@ -0,0 +1,29 @@
+# 50 — ValidationReport with severity filtering
+
+## Why
+
+`Convention.validate` returns a flat array of `Violation`s. Callers
+that want only errors or only warnings have to filter manually. Add
+a `ValidationReport` value object that wraps the array and exposes
+severity-based views.
+
+## API
+
+```ruby
+report = Chemicalml::Convention::ValidationReport.new(violations)
+report.errors      # [Violation] with severity == :error
+report.warnings    # [Violation] with severity == :warning
+report.ok?         # errors.empty?
+report.has_warnings? # warnings.any?
+report.violations  # raw array (backward compat)
+```
+
+Also add `Convention.validate_report(doc)` returning a
+`ValidationReport` instead of an array. Existing `validate` keeps its
+array return shape (backward compatible).
+
+## Acceptance
+
+- New spec covers all 5 helpers.
+- Existing validate specs unchanged.
+- Full suite green.

data/TODO.align/51-convention-auto-detection.md

@@ -0,0 +1,30 @@
+# 51 — Convention auto-detection
+
+## Why
+
+Currently a caller has to know the convention QName and pass it to
+`Convention::Registry.validate(doc, qname: "convention:molecular")`.
+The document itself declares its convention via the `convention`
+attribute on its root element — the gem should be able to detect and
+dispatch automatically.
+
+## API
+
+```ruby
+Chemicalml::Convention::Registry.detect_and_validate(doc)
+# → [Violation, ...] (or ValidationReport)
+```
+
+Internally:
+1. Find the root element (Document or Molecule or Module).
+2. Read its `convention` attribute.
+3. Look up in `Registry`.
+4. If found → run `convention.validate(doc)`.
+5. If not found → raise ArgumentError naming the convention.
+
+## Acceptance
+
+- Spec: a doc with `convention="convention:molecular"` auto-validates.
+- Spec: unknown convention raises ArgumentError.
+- Spec: doc without convention raises ArgumentError.
+- Full suite green.

data/TODO.align/52-schema24-legacy-elements.md

@@ -0,0 +1,28 @@
+# 52 — Schema24 legacy elements (selective)
+
+## Why
+
+Schema 2.4 XSD declares 17 elements not in Schema 3. Three of them
+are useful enough to model: `annotation` (documentation wrapper),
+`appinfo` (application info), `enumeration` (dictionary enum, used
+by entries that predate the schema3 enum attribute).
+
+The other 14 (`alternative`, `arg`, `complexObject`, `expression`,
+`float`, `floatArray`, `integer`, `integerArray`, `operator`,
+`relatedEntry`, `string`, `stringArray`, `tcell`, `trow`) are either
+redundant with Schema 3's unified `scalar`/`array`/`table` or relate
+to legacy expression machinery. Out of scope for now.
+
+## Implementation
+
+- Add `Base::Annotation`, `Base::Appinfo`, `Base::Enumeration`.
+- Add `Role::Annotation`, `Role::Appinfo`, `Role::Enumeration`.
+- Add `Schema24::Annotation`, `Schema24::Appinfo`, `Schema24::Enumeration`.
+- Add to `Elements::ALL` with new `SCHEMA24_ONLY` list.
+- Schema3 skips these; Schema24 registers them.
+
+## Acceptance
+
+- Three new wire classes registered for Schema24 only.
+- Schema3 lookup raises ArgumentError for these (not in Schema 3).
+- Full suite green.

data/TODO.align/53-round-trip-integration-specs.md

@@ -0,0 +1,30 @@
+# 53 — Round-trip integration specs
+
+## Why
+
+Per-element translator specs cover individual `*_to_canonical` /
+`*_from_canonical` calls. They miss integration issues — wire-format
+mismatches, attribute renames, namespace leaks — that only surface
+when you go XML → canonical → XML → canonical and compare.
+
+## Specs
+
+A new `spec/chemicalml/integration/round_trip_spec.rb` that, for each
+fixture under `spec/fixtures/schema3/`:
+
+1. Parse the CML XML → wire tree.
+2. Translate wire → canonical Model.
+3. Translate canonical → wire.
+4. Serialize wire → XML.
+5. Re-parse → second wire tree.
+6. Compare first and second wire trees via `value_attributes`.
+
+Uses real wire instances throughout (no doubles per project rule).
+Also includes synthetic minimal docs for: crystal-bearing molecule,
+spectrum-bearing molecule, zMatrix molecule, isotopeList molecule.
+
+## Acceptance
+
+- Every fixture round-trips.
+- Synthetic minimal docs round-trip.
+- Full suite green.

data/TODO.align/54-document-versioned-parser-shim.md

@@ -0,0 +1,38 @@
+# 54 — Document VersionedParser namespace shim
+
+## Why
+
+`lib/chemicalml/versioned_parser.rb` uses regex for two pre-processing
+steps before delegating to `lutaml-model`:
+
+1. `root_element_of(xml)` — peeks the XML for the root element local
+   name so the parser can dispatch to the right wire class.
+2. `inject_namespace(xml, uri, root)` — when the caller passes
+   `namespace_exist: false`, injects `xmlns="..."` into the root
+   start tag.
+
+Both are pre-processing shims. The actual parse goes through
+`Lutaml::Model::Serializable.from_xml` (line 45). Neither function
+serializes, deserializes, or constructs XML nodes — they're string
+pre-processing for input normalization.
+
+The user asked to confirm this. The answer:
+
+- All actual XML parsing and serialization goes through lutaml-model.
+- 242 wire classes extend `Lutaml::Model::Serializable`.
+- Zero `def to_xml`/`from_xml`/`to_h`/`from_h` on any model class.
+- Zero Nokogiri/REXML references in `lib/`.
+- The two regex helpers in `versioned_parser.rb` are pre-processing
+  for input normalization, not serialization. They are explicitly
+  documented as such.
+
+## Action
+
+- Add a clear comment block at the top of `versioned_parser.rb`
+  explaining the boundary.
+- No code change.
+
+## Acceptance
+
+- Comment added.
+- Full suite green.

data/TODO.align/55-molecule-missing-attributes.md

@@ -0,0 +1,20 @@
+# 55 — Fix Model::Molecule missing attributes (correctness)
+
+## Why
+
+`Base::Molecule` declares `spin_multiplicity`, `dict_ref`,
+`convention`, `chirality` attributes, but `Model::Molecule` doesn't
+have them and the translator drops them silently. These are
+chemically important (chirality in particular).
+
+## Fix
+
+Add `spin_multiplicity`, `dict_ref`, `convention`, `chirality` to
+`Model::Molecule`. Update translator molecule_to_canonical and
+molecule_from_canonical to map them.
+
+## Acceptance
+
+- All 4 attributes round-trip through translator.
+- Existing specs unchanged.
+- Full suite green.

data/TODO.align/56-geometry-models.md

@@ -0,0 +1,24 @@
+# 56 — Geometry Model classes
+
+## Why
+
+CML declares 6 geometry primitives (`point3`, `vector3`, `line3`,
+`plane3`, `sphere3`, `transform3`) plus `cellParameter` and
+`dimension` — all share the same shape (id/title/dictRef/convention +
+content). They're used as children of `atom`, `molecule`, `crystal`,
+etc. Without canonical Models, callers must use wire classes directly.
+
+## Implementation
+
+One Model class per element. Each carries `id`, `title`, `dict_ref`,
+`convention`, `content` (the geometry string). Identical shape, so
+specs can be parametrized.
+
+For `cellParameter`: also `cellType` attribute (per Schema 3 XSD).
+For `dimension`: also `name` attribute.
+
+## Acceptance
+
+- 8 new Model classes registered.
+- Per-class spec.
+- Full suite green.

data/TODO.align/57-compchem-models.md

@@ -0,0 +1,26 @@
+# 57 — Compchem Model classes
+
+## Why
+
+Schema 3 declares 10 compchem-specific elements not yet modeled:
+`gradient`, `eigen`, `kpoint`, `kpointList`, `band`, `bandList`,
+`basisSet`, `atomicBasisFunction`, `particle`, `electron`. All
+are common in computational chemistry output.
+
+## Implementation
+
+- `Model::Gradient` — id/title/dictRef/convention/units/content
+- `Model::Eigen` — id/title/dictRef/convention/units/type/content
+- `Model::Kpoint` / `Model::KpointList`
+- `Model::Band` / `Model::BandList`
+- `Model::BasisSet` / `Model::AtomicBasisFunction`
+- `Model::Particle` / `Model::Electron`
+
+Each follows the Node pattern: attr_accessor, initialize, children,
+value_attributes.
+
+## Acceptance
+
+- 10 new Model classes.
+- Per-class spec.
+- Full suite green.

data/TODO.align/58-remaining-models.md

@@ -0,0 +1,24 @@
+# 58 — Remaining Model classes for full element coverage
+
+## Why
+
+Several wire elements still lack canonical Models, breaking the "all
+adapters speak canonical" invariant for these element types.
+
+## New Model classes (25)
+
+- **Documentation**: Definition, Description, Documentation, Link
+- **Chemistry**: Symmetry (pointGroup/spaceGroup), System
+  (atomArray/molecules), Stmml
+- **Containers**: ArrayList, ConditionList, SubstanceList
+- **Sets**: AtomSet, BondSet
+- **Typing**: AtomType, AtomTypeList, BondType, BondTypeList
+- **Mechanism**: Mechanism, MechanismComponent, Join
+- **Other**: Object, Observation, PeakStructure, Potential,
+  PotentialForm, PotentialList
+
+## Acceptance
+
+- 25 new Model classes.
+- Per-class spec (lightweight — just instantiation + value_attributes).
+- Full suite green.

data/TODO.align/59-wire-new-models-translator.md

@@ -0,0 +1,18 @@
+# 59 — Wire new Models through translator
+
+## Why
+
+Models added in TODOs 56-58 are inert without translator mappings.
+Add `*_to_canonical` / `*_from_canonical` for each.
+
+## Implementation
+
+Most share the geometry-simple shape (id/title/dictRef/convention +
+content). Factor a shared helper to avoid copy-paste.
+
+## Acceptance
+
+- Translator spec for each new Model class.
+- Round-trip integration test covers a synthetic doc using one new
+  Model class end-to-end.
+- Full suite green.

data/TODO.align/60-docs-and-final-verification.md

@@ -0,0 +1,19 @@
+# 60 — Update CLAUDE.md and final verification
+
+## Why
+
+Counts in CLAUDE.md and project docs are stale after TODOs 36-59.
+
+## Updates
+
+- CLAUDE.md model count (was 43, now ~100).
+- Constraint count (was 17, now 60).
+- Note ValidationReport, detect_and_validate APIs.
+- Note Schema24 legacy elements.
+- Verify `bundle exec rspec` fully green.
+- Verify zero forbidden patterns.
+
+## Acceptance
+
+- Docs reflect current state.
+- Full suite green.

data/lib/chemicalml/cml/base/abundance.rb

@@ -12,6 +12,9 @@ module Chemicalml
             attribute :dict_ref, :string
             attribute :convention, :string
 
+            attribute :min, :string
+            attribute :max, :string
+            attribute :units, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "abundance"
@@ -19,6 +22,9 @@ module Chemicalml
               map_attribute "title", to: :title
               map_attribute "dictRef", to: :dict_ref
               map_attribute "convention", to: :convention
+              map_attribute "min", to: :min
+              map_attribute "max", to: :max
+              map_attribute "units", to: :units
             end
           end
         end

data/lib/chemicalml/cml/base/action.rb

@@ -13,6 +13,16 @@ module Chemicalml
             attribute :convention, :string
             attribute :order, :string
 
+            attribute :units, :string
+            attribute :start, :string
+            attribute :start_condition, :string
+            attribute :duration, :string
+            attribute :end, :string
+            attribute :end_condition, :string
+            attribute :type, :string
+            attribute :action_order, :string
+            attribute :count, :string
+            attribute :ref, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "action"
@@ -21,6 +31,16 @@ module Chemicalml
               map_attribute "dictRef", to: :dict_ref
               map_attribute "convention", to: :convention
               map_attribute "order", to: :order
+              map_attribute "units", to: :units
+              map_attribute "start", to: :start
+              map_attribute "startCondition", to: :start_condition
+              map_attribute "duration", to: :duration
+              map_attribute "end", to: :end
+              map_attribute "endCondition", to: :end_condition
+              map_attribute "type", to: :type
+              map_attribute "actionOrder", to: :action_order
+              map_attribute "count", to: :count
+              map_attribute "ref", to: :ref
             end
           end
         end

data/lib/chemicalml/cml/base/action_list.rb

@@ -15,6 +15,15 @@ module Chemicalml
 
                         attribute :actions, :action, collection: true
 
+            attribute :start, :string
+            attribute :start_condition, :string
+            attribute :duration, :string
+            attribute :end, :string
+            attribute :end_condition, :string
+            attribute :units, :string
+            attribute :count, :string
+            attribute :type, :string
+            attribute :action_order, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               map_element "action", to: :actions
@@ -24,6 +33,15 @@ module Chemicalml
               map_attribute "dictRef", to: :dict_ref
               map_attribute "convention", to: :convention
               map_attribute "order", to: :order
+              map_attribute "start", to: :start
+              map_attribute "startCondition", to: :start_condition
+              map_attribute "duration", to: :duration
+              map_attribute "end", to: :end
+              map_attribute "endCondition", to: :end_condition
+              map_attribute "units", to: :units
+              map_attribute "count", to: :count
+              map_attribute "type", to: :type
+              map_attribute "actionOrder", to: :action_order
             end
           end
         end

data/lib/chemicalml/cml/base/alternative.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    module Base
+      module Alternative
+        def self.included(klass)
+          klass.class_eval do
+            include Chemicalml::Cml::Role::Alternative
+            attribute :id, :string
+            attribute :convention, :string
+            attribute :alternative_type, :string
+            attribute :content, :string
+
+            xml do
+              namespace Chemicalml::Cml::Namespace
+              root "alternative"
+              map_attribute "id", to: :id
+              map_attribute "convention", to: :convention
+              map_attribute "alternativeType", to: :alternative_type
+              map_content to: :content
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/cml/base/amount.rb

@@ -12,6 +12,7 @@ module Chemicalml
             attribute :dict_ref, :string
             attribute :convention, :string
 
+            attribute :units, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "amount"
@@ -19,6 +20,7 @@ module Chemicalml
               map_attribute "title", to: :title
               map_attribute "dictRef", to: :dict_ref
               map_attribute "convention", to: :convention
+              map_attribute "units", to: :units
             end
           end
         end

data/lib/chemicalml/cml/base/angle.rb

@@ -14,6 +14,12 @@ module Chemicalml
             attribute :atomRefs3, :string
             attribute :units, :string
 
+            attribute :angle_units, :string
+            attribute :error_value, :string
+            attribute :error_basis, :string
+            attribute :min, :string
+            attribute :max, :string
+            attribute :ref, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "angle"
@@ -23,6 +29,12 @@ module Chemicalml
               map_attribute "convention", to: :convention
               map_attribute "atomRefs3", to: :atomRefs3
               map_attribute "units", to: :units
+              map_attribute "angleUnits", to: :angle_units
+              map_attribute "errorValue", to: :error_value
+              map_attribute "errorBasis", to: :error_basis
+              map_attribute "min", to: :min
+              map_attribute "max", to: :max
+              map_attribute "ref", to: :ref
             end
           end
         end

data/lib/chemicalml/cml/base/annotation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    module Base
+      module Annotation
+        def self.included(klass)
+          klass.class_eval do
+            include Chemicalml::Cml::Role::Annotation
+            attribute :id, :string
+            attribute :title, :string
+            attribute :dict_ref, :string
+            attribute :convention, :string
+            attribute :documentation, :documentation
+
+            xml do
+              namespace Chemicalml::Cml::Namespace
+              root "annotation"
+              map_attribute "id", to: :id
+              map_attribute "title", to: :title
+              map_attribute "dictRef", to: :dict_ref
+              map_attribute "convention", to: :convention
+              map_element "documentation", to: :documentation
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/cml/base/appinfo.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    module Base
+      module Appinfo
+        def self.included(klass)
+          klass.class_eval do
+            include Chemicalml::Cml::Role::Appinfo
+            attribute :id, :string
+            attribute :title, :string
+            attribute :dict_ref, :string
+            attribute :convention, :string
+            attribute :content, :string
+
+            attribute :role, :string
+            xml do
+              namespace Chemicalml::Cml::Namespace
+              root "appinfo"
+              map_attribute "id", to: :id
+              map_attribute "title", to: :title
+              map_attribute "dictRef", to: :dict_ref
+              map_attribute "convention", to: :convention
+              map_content to: :content
+              map_attribute "role", to: :role
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/cml/base/arg.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cml
+    module Base
+      module Arg
+        def self.included(klass)
+          klass.class_eval do
+            include Chemicalml::Cml::Role::Arg
+            attribute :title, :string
+            attribute :id, :string
+            attribute :convention, :string
+            attribute :dict_ref, :string
+            attribute :ref, :string
+            attribute :name, :string
+            attribute :data_type, :string
+            attribute :substitute, :string
+            attribute :parameter_name, :string
+            attribute :parent_attribute, :string
+            attribute :delete, :string
+            attribute :eval, :string
+            attribute :content, :string
+
+            xml do
+              namespace Chemicalml::Cml::Namespace
+              root "arg"
+              map_attribute "title", to: :title
+              map_attribute "id", to: :id
+              map_attribute "convention", to: :convention
+              map_attribute "dictRef", to: :dict_ref
+              map_attribute "ref", to: :ref
+              map_attribute "name", to: :name
+              map_attribute "dataType", to: :data_type
+              map_attribute "substitute", to: :substitute
+              map_attribute "parameterName", to: :parameter_name
+              map_attribute "parentAttribute", to: :parent_attribute
+              map_attribute "delete", to: :delete
+              map_attribute "eval", to: :eval
+              map_content to: :content
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/cml/base/array.rb

@@ -16,6 +16,17 @@ module Chemicalml
             attribute :delimiter, :string
             attribute :content, :string
 
+            attribute :convention, :string
+            attribute :error_value_array, :string
+            attribute :error_basis, :string
+            attribute :min_value_array, :string
+            attribute :max_value_array, :string
+            attribute :start, :string
+            attribute :end, :string
+            attribute :ref, :string
+            attribute :constant_to_s_i, :string
+            attribute :multiplier_to_s_i, :string
+            attribute :unit_type, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "array"
@@ -27,6 +38,17 @@ module Chemicalml
               map_attribute "size", to: :size
               map_attribute "delimiter", to: :delimiter
               map_content to: :content
+              map_attribute "convention", to: :convention
+              map_attribute "errorValueArray", to: :error_value_array
+              map_attribute "errorBasis", to: :error_basis
+              map_attribute "minValueArray", to: :min_value_array
+              map_attribute "maxValueArray", to: :max_value_array
+              map_attribute "start", to: :start
+              map_attribute "end", to: :end
+              map_attribute "ref", to: :ref
+              map_attribute "constantToSI", to: :constant_to_s_i
+              map_attribute "multiplierToSI", to: :multiplier_to_s_i
+              map_attribute "unitType", to: :unit_type
             end
           end
         end

data/lib/chemicalml/cml/base/array_list.rb

@@ -12,6 +12,7 @@ module Chemicalml
             attribute :dict_ref, :string
             attribute :convention, :string
 
+            attribute :shape, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "arrayList"
@@ -19,6 +20,7 @@ module Chemicalml
               map_attribute "title", to: :title
               map_attribute "dictRef", to: :dict_ref
               map_attribute "convention", to: :convention
+              map_attribute "shape", to: :shape
             end
           end
         end

data/lib/chemicalml/cml/base/atom.rb

@@ -26,6 +26,15 @@ module Chemicalml
             attribute :zFract, :string
             attribute :atom_parity, :atomParity
 
+            attribute :convention, :string
+            attribute :dict_ref, :string
+            attribute :ref, :string
+            attribute :isotope_ref, :string
+            attribute :isotope_list_ref, :string
+            attribute :occupancy, :string
+            attribute :role, :string
+            attribute :space_group_multiplicity, :string
+            attribute :point_group_multiplicity, :string
             xml do
               namespace Chemicalml::Cml::Namespace
               root "atom"
@@ -47,6 +56,15 @@ module Chemicalml
               map_attribute "yFract", to: :yFract
               map_attribute "zFract", to: :zFract
               map_element "atomParity", to: :atom_parity
+              map_attribute "convention", to: :convention
+              map_attribute "dictRef", to: :dict_ref
+              map_attribute "ref", to: :ref
+              map_attribute "isotopeRef", to: :isotope_ref
+              map_attribute "isotopeListRef", to: :isotope_list_ref
+              map_attribute "occupancy", to: :occupancy
+              map_attribute "role", to: :role
+              map_attribute "spaceGroupMultiplicity", to: :space_group_multiplicity
+              map_attribute "pointGroupMultiplicity", to: :point_group_multiplicity
             end
           end
         end