chemicalml 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07b63ae96c1ef6187081c9f14ab76722b91f4438516a46c993abadac25f37a8f
-  data.tar.gz: 5130f3b5538741239be68d6632eaeecc0175ecb44f7a85cdf88e9414657c1689
+  metadata.gz: 74eb61f89b283d3263aa4ead18e9b76061700defcc54232002855af6b1291c0a
+  data.tar.gz: 228f8f704086b458a73b3f4cb679b25133cf5ee36aa16d58c688a6439abb1974
 SHA512:
-  metadata.gz: 29433a22bbfd290ce7146fefda2d4e68944bda3098902e3d8c6f282d05c7b99ee95de9097685ed55e9ff365799e17eee785bb3b5414dff39076616c65db87189
-  data.tar.gz: 300c20a1df5cf4cbad657ce97fc0b26b6aec9f2ecb84ac524ab4f30a209636aeebbf6756637ee0e3fc6dec96685f4334aa8ee90e34a1058078ea2ccba4d2f4a8
+  metadata.gz: ba13a979cce6d48bbef181917107ac9ad24291131e8568652a012698c5e3ebe7f43851f908408478e4b4481d270cb9b83371d9c3f19093700df19a97565af2a9
+  data.tar.gz: 8557d650ab706936b25031541e256e840cc638d025d5c4b7308a512aa46e27d4223a050ba27b37c7d9c5408c1b1dd7af4974697699af317fec17a3ecfa262f92

data/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+  repository_dispatch:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: docs
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --verbose --trace --baseurl "${{ steps.pages.outputs.base_path }}"
+        working-directory: docs
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/links.yml

@@ -0,0 +1,99 @@
+name: links
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  link_checker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+        working-directory: docs
+
+    - name: Build site
+      env:
+        JEKYLL_ENV: production
+      run: bundle exec jekyll build --trace
+      working-directory: docs
+
+    - name: Restore lychee cache
+      uses: actions/cache@v4
+      with:
+        path: .lycheecache
+        key: cache-lychee-${{ github.sha }}
+        restore-keys: cache-lychee-
+
+    - name: Check if site was built
+      run: |
+        if [ ! -d "_site" ]; then
+          echo "Error: _site directory not created"
+          exit 1
+        fi
+        echo "Site built successfully"
+        ls -la _site/
+      working-directory: docs
+
+    - name: Link Checker (Built Site)
+      uses: lycheeverse/lychee-action@v2
+      with:
+        # Check the built HTML site for rendered links
+        # Only check https and http schemes, exclude file:// due to path resolution issues
+        args: >-
+          --verbose
+          --no-progress
+          --config lychee.toml
+          --root-dir "$(pwd)/_site"
+          --scheme https,http
+          '_site/**/*.html'
+        fail: true
+        output: link-check-results.md
+        format: markdown
+        workingDirectory: docs
+
+    - name: Upload link check results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: link-check-results
+        path: |
+          docs/link-check-results.md
+        retention-days: 30
+
+    - name: Comment PR with results
+      if: failure() && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          let comment = '## 🔗 Link Check Failed\n\n';
+
+          if (fs.existsSync('docs/link-check-results.md')) {
+            const results = fs.readFileSync('docs/link-check-results.md', 'utf8');
+            comment += '### Built Site Results\n\n' + results + '\n\n';
+          }
+
+          comment += '\n---\n\n*Please fix the broken links and push a new commit.*';
+
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: comment
+          });

data/.github/workflows/opal.yml

@@ -0,0 +1,34 @@
+name: opal
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Opal dependencies
+        run: |
+          bundle config set with opal
+          bundle install
+
+      - name: Run Opal smoke tests
+        run: bundle exec rake spec:opal

data/.github/workflows/performance.yml

@@ -0,0 +1,25 @@
+name: performance
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  performance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Run performance benchmarks
+        run: bundle exec rake performance:compare

data/.github/workflows/rake.yml

@@ -0,0 +1,19 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: rake
+
+permissions:
+  contents: write
+  packages: write
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+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).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        required: true
+        default: 'skip'
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: relaton/support/.github/workflows/release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}

data/CHANGELOG.md

@@ -1,21 +1,61 @@
 # Changelog
 
-All notable changes to ChemML are documented here.
+All notable changes to Chemicalml are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.2.0] - 2026-07-14
 
 ### Added
+
+- Full CML Schema 3 element coverage (121 elements).
+- Dual schema support: Schema 2.4 and Schema 3 wire classes with
+  real class hierarchies, shared declarations via `Base::*` mixins,
+  and `Role::*` type marker modules.
+- `Chemicalml.parse(xml, schema:)` polymorphic entry point with
+  auto-detection of root element (any of the 121 CML elements).
+- `Chemicalml::Cml::Translator` with schema-aware translation:
+  `to_canonical` / `from_canonical` handle both Schema3 and
+  Schema24 wire classes at every nesting level via
+  `WireClassRegistry`.
+- Convention framework: 5 built-in conventions (molecular, compchem,
+  dictionary, unit-dictionary, unitType-dictionary) with 17
+  registered constraint classes.
+- Dictionary model: 8 built-in YAML dictionaries (compchem, cml,
+  cml_name, cml_formula, cif, unit_si, unit_non_si, unit_type)
+  with 193+ entries.
+- Atom coordinate support: 2D (x2/y2), 3D (x3/y3/z3), and
+  fractional (xFract/yFract/zFract) coordinates round-trip through
+  canonical.
+- Stereo support: `AtomParity` and `BondStereo` round-trip through
+  canonical Model.
+- Compchem module support: `<module>`-rooted documents parse and
+  round-trip through canonical.
+- Property/Formula/Label as children of Molecule — no more silent
+  data loss on `<property>` inside `<molecule>`.
+- `Visitable` mixin: uniform interface for constraint walker
+  (`wire_children`, `node_id`, `element_name`).
+- Canon-based semantic XML comparison in specs.
+- Attribution: NOTICES.adoc credits xml-cml.org editors and
+  CC-BY-3.0 license for upstream content.
+
+### Changed
+
+- Namespace renamed from `ChemicalML` to `Chemicalml`.
+- Wire classes load lazily via `autoload` — every file, every
+  constant.
+- Serialization goes through `lutaml-model` only — no hand-rolled
+  XML.
+- Schema 2.4 correctly lacks `<module>` (schema 3 only).
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
 - Initial gem scaffold: autoload tree, version, errors.
-- CML namespace declaration (`Chemicalml::Cml::Namespace`) for the CML
-  default XML namespace.
-- CML model classes for the core CML element set:
-  `Document`, `Molecule`, `AtomArray`, `Atom`, `BondArray`, `Bond`,
-  `Reaction`, `ReactantList`, `Reactant`, `ProductList`, `Product`,
-  `ReactionList`, `Name`, `Identifier`.
-- AsciiChem extension namespace (`Chemicalml::Ext::Namespace`) for
-  attributes CML doesn't natively cover (lone pairs, radical
-  electrons, stereochemistry).
-- Round-trip specs covering canonical CML fragments.
+- CML namespace declaration.
+- CML model classes for the core element set.
+- Round-trip specs.
 
 [Unreleased]: https://github.com/lutaml/chemicalml/commits/main
+[0.2.0]: https://github.com/lutaml/chemicalml/releases/tag/v0.2.0
+[0.1.0]: https://github.com/lutaml/chemicalml/releases/tag/v0.1.0

data/Gemfile

@@ -4,10 +4,11 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "rake", "~> 13.2"
+
 group :development do
   gem "canon"
   gem "nokogiri"
-  gem "rake", "~> 13.2"
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.66", require: false
   gem "simplecov", "~> 0.22", require: false

data/Rakefile

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  task :default do
+    warn "rspec not available — skipping specs"
+  end
+end

data/TODO.align/18-wire-class-registry.md

@@ -0,0 +1,46 @@
+# 18 — WireClassRegistry
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+A central registry that, given a schema symbol and a Role module,
+returns the right wire class. Eliminates the hardcoded `Cml::Foo`
+references in the Translator (which are all Schema3 aliases).
+
+```ruby
+Chemicalml::Cml::WireClassRegistry.for(:schema24, Chemicalml::Cml::Role::Molecule)
+# => Chemicalml::Cml::Schema24::Molecule
+
+Chemicalml::Cml::WireClassRegistry.for(:schema3, Chemicalml::Cml::Role::Atom)
+# => Chemicalml::Cml::Schema3::Atom
+```
+
+## Why
+
+The Translator today hardcodes `Cml::Molecule` (which is an alias for
+`Schema3::Molecule`). When the user asks for a Schema24 document,
+`Translator.from_canonical(doc, schema: :schema24)` returns a
+`Schema24::Document` but its `molecules` collection contains
+`Schema3::Molecule` instances. **This is a correctness bug.**
+
+The registry centralizes the lookup so every helper can resolve the
+right class for the requested schema.
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/wire_class_registry.rb` — module with
+      `for(schema, role)` class method.
+- [ ] Raises `ArgumentError` on unknown schema or role.
+- [ ] Lazily resolves via `Schema3::Foo` / `Schema24::Foo` constants
+      (no eager loading).
+- [ ] Spec coverage.
+
+## Acceptance
+
+- `WireClassRegistry.for(:schema24, Role::Molecule)` returns
+  `Chemicalml::Cml::Schema24::Molecule`.
+- `WireClassRegistry.for(:schema3, Role::Atom)` returns
+  `Chemicalml::Cml::Schema3::Atom`.
+- Unknown schema raises `ArgumentError`.

data/TODO.align/19-schema-aware-translator.md

@@ -0,0 +1,33 @@
+# 19 — Schema-aware translator helpers
+
+**Status:** complete
+**Depends on:** 18
+
+## Goal
+
+Replace every `Cml::Foo.new(...)` in the Translator with
+`WireClassRegistry.for(schema, Role::Foo).new(...)`. Pass the schema
+through every `*_from_canonical` helper.
+
+## Why
+
+Today `Translator.from_canonical(doc, schema: :schema24)` returns a
+Schema24 Document whose children are Schema3 instances — silent
+correctness bug. Fixing it requires the WireClassRegistry (task 18)
+plus threading `schema:` through every helper.
+
+## Deliverables
+
+- [ ] Every `*_from_canonical` helper takes `schema:` keyword.
+- [ ] `from_canonical` itself passes its `schema:` to each helper.
+- [ ] No hardcoded `Cml::Foo` in `lib/chemicalml/cml/translator.rb`
+      or `value_translations.rb`.
+- [ ] Spec verifying `from_canonical(schema: :schema24)` produces
+      Schema24 children at every level (Document, Molecule, Atom,
+      Bond, Name, Identifier, etc.).
+
+## Acceptance
+
+- Round-trip canonical → Schema24 wire → canonical yields equal doc.
+- `wire.molecules.first` is a `Schema24::Molecule` (not Schema3).
+- `wire.molecules.first.atom_array.atoms.first` is a `Schema24::Atom`.

data/TODO.align/20-missing-translator-rules.md

@@ -0,0 +1,44 @@
+# 20 — Missing translator rules
+
+**Status:** complete
+**Depends on:** 19
+
+## Goal
+
+The Translator today handles: Document, Molecule, AtomArray,
+Atom, BondArray, Bond, Name, Identifier, Reaction, ReactionList,
+ReactantList, Reactant, ProductList, Product, Substance, plus
+value containers (Scalar, Array, Matrix, Property, Parameter),
+Label, Metadata, Formula via the ValueTranslations module.
+
+Missing: **Module** (compchem), **PropertyList**, **ParameterList**,
+**MetadataList**, **AtomParity**, **BondStereo**, **Dictionary**,
+**DictionaryEntry**, **Unit**, **UnitList**, **UnitType**,
+**UnitTypeList**, **List**.
+
+Add canonical ↔ wire rules for each so compchem modules and
+dictionaries can round-trip through canonical.
+
+## Why
+
+- Compchem modules can't be translated today — the wire class exists
+  but no canonical mapping does.
+- Dictionary / Unit / UnitType wire classes have no canonical
+  counterpart. They could reuse `Chemicalml::Dictionary::Model` etc.
+  but the Translator doesn't connect them.
+
+## Deliverables
+
+- [ ] `module_to_canonical` / `module_from_canonical` — handles
+      nested modules, parameter_lists, property_lists,
+      metadata_lists, molecules, lists.
+- [ ] `property_list_to_canonical` / `property_list_from_canonical`.
+- [ ] `parameter_list_to_canonical` / `parameter_list_from_canonical`.
+- [ ] `metadata_list_to_canonical` / `metadata_list_from_canonical`.
+- [ ] Specs covering each new rule.
+
+## Acceptance
+
+- Round-trip a compchem module fixture through canonical → wire →
+  canonical yields equal model.
+- Specs green.

data/TODO.align/21-encapsulate-translator.md

@@ -0,0 +1,33 @@
+# 21 — Encapsulate translator internals
+
+**Status:** complete
+**Depends on:** 19, 20
+
+## Goal
+
+The Translator has 17 public class methods today. Only `to_canonical`
+and `from_canonical` are part of the public API. Every helper
+(`molecule_to_canonical`, `atom_from_canonical`, `cml_order_to_kind`,
+etc.) is an implementation detail and should be private.
+
+## Why
+
+- Public API surface = mental load for users. They see 17 methods and
+  wonder which to use.
+- Internal helpers shouldn't be callable from outside — encapsulation
+  violation.
+- Risk: a future refactor (e.g. visitor pattern) would need to keep
+  these as public for backward compat.
+
+## Deliverables
+
+- [ ] Add `private_class_method` for every helper method on
+      `Translator`.
+- [ ] Same for `ValueTranslations::ClassMethods` helpers.
+- [ ] Verify no spec or external code calls the helpers directly.
+
+## Acceptance
+
+- `Chemicalml::Cml::Translator.public_methods(false)` returns only
+  `to_canonical` and `from_canonical`.
+- All specs still pass.

data/TODO.align/22-dry-role-modules.md

@@ -0,0 +1,32 @@
+# 22 — DRY role modules
+
+**Status:** rejected
+**Depends on:** —
+
+## Goal (rejected)
+
+Replace 36 nearly-identical Role module files with a single
+`Elements::ALL.each_key { const_set(class_name, Module.new) }`
+block.
+
+## Why rejected
+
+`const_set(class_name, Module.new)` is **eager** — every role module
+is created when `cml/role.rb` loads. The user's global rule mandates
+**autoload** (lazy file loading), not `const_set`. The two are not
+equivalent:
+
+- `autoload :Foo, "path"` — registers a hook; the file loads only
+  when `Foo` is first referenced. Enables lazy loading, avoids
+  circular dependencies, keeps the load path clean.
+- `const_set(:Foo, Module.new)` — creates the constant eagerly at
+  file-load time. No lazy loading.
+
+The 36 tiny role files are the price of admission for the lazy-load
+guarantee. They stay.
+
+## Acceptance
+
+- Keep the 36 individual role files under `lib/chemicalml/cml/role/`.
+- Keep the autoload declarations in `lib/chemicalml/cml/role.rb`.
+- Do not use `const_set` for role modules.

data/TODO.align/23-final-spec-lint.md

@@ -0,0 +1,25 @@
+# 23 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Goal
+
+Run the full suite, audit forbidden patterns, document final state.
+
+## Deliverables
+
+- [ ] `bundle exec rspec spec/chemicalml/` green.
+- [ ] `Chemicalml::Cml::Translator.public_methods(false)` returns only
+      `to_canonical` and `from_canonical`.
+- [ ] No hardcoded `Cml::Foo.new` in translator files.
+- [ ] `from_canonical(schema: :schema24)` produces Schema24 children
+      at every level (spec verification).
+- [ ] `lib/chemicalml/cml/role/` directory removed.
+- [ ] Zero `require_relative`, `respond_to?`, `instance_variable_set`/`get`,
+      private `send` in lib/.
+- [ ] TODO.align/README.round3.md marked complete.
+
+## Acceptance
+
+All checks pass.