chemicalml 0.2.0 → 0.3.0

data/TODO.align/README.round33.md

@@ -0,0 +1,62 @@
+# Round 33 — CLI run(options) signature alignment
+
+This round refactors every CLI command class so the run method
+takes a single `options` hash, matching the user-requested
+invocation pattern exactly:
+
+    MyCommandClass.new.run(options)
+
+## Files
+
+- [134 — CLI run(options) alignment](134-cli-run-options-alignment.md)
+- [135 — Final verification round 33](135-final-verification-round33.md)
+
+## Outcomes
+
+- Every `Chemicalml::Cli::*Command` now implements
+  `def run(options)` (single hash argument). The hash carries both
+  positional args (keyed by name: `:file`, `:element`) and flags
+  (`:json`, etc.).
+
+- `Chemicalml::Cli::Base` (Thor dispatcher) builds the options hash
+  for each command and calls `<Name>Command.new.run(hash)`. Example:
+  ```ruby
+  desc "validate FILE", "..."
+  method_option :json, type: :boolean, aliases: "-j"
+  def validate(file)
+    ValidateCommand.new.run(file: file, json: options[:json])
+  end
+  ```
+
+- Each command supports both invocation styles:
+  - Instance: `MyCommand.new.run(options)` (primary, per user spec)
+  - Class: `MyCommand.run(options)` (convenience, delegates to instance)
+
+- Bug fix: validation guards `return warn(...), 2 unless path`
+  were returning `[warn_result, 2]` (array) instead of integer 2.
+  Rewrote as explicit `warn; return 2` two-line guards.
+
+- CLI spec updated to test both invocation styles. 17 specs covering
+  every command via `MyCommandClass.new.run(options)` direct call.
+
+- **593 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+The single-hash `run(options)` signature is more flexible than the
+prior `(args, options)` split:
+
+- Positional args are named (`file:`, `element:`), not positional.
+  Easier to extend (add a new arg = add a new hash key, no method
+  signature change).
+- Same hash carries flags (`json:`, etc.). One argument, one source
+  of truth.
+- Commands are unit-testable in isolation without Thor:
+  ```ruby
+  Chemicalml::Cli::ValidateCommand.new.run(file: "x.cml", json: true)
+  ```
+
+The Thor dispatcher is now truly just routing — it parses CLI input
+and constructs the options hash. Every command class can be reused
+from Rake tasks, RSpec tests, or web handlers without going through
+Thor at all.

data/TODO.align/README.round34.md

@@ -0,0 +1,70 @@
+# Round 34 — Constraint descriptions, diverse fixtures, perf baseline, BIG perf fix
+
+This round adds constraint-class descriptions, more diverse fixtures,
+a performance baseline spec, and crucially **fixes a 680× performance
+regression** discovered by the baseline spec.
+
+## Files
+
+- [136 — Constraint descriptions](136-constraint-descriptions.md)
+- [137 — More diverse fixtures](137-more-diverse-fixtures.md)
+- [138 — Performance baseline spec](138-performance-baseline-spec.md)
+- [139 — Final verification round 34](139-final-verification-round34.md)
+
+## Outcomes
+
+- **Constraint `description` class method** added to
+  `Convention::Constraint`. Each constraint can now carry a
+  human-readable description of the rule it enforces. Two molecular
+  constraints (`AtomMustHaveId`, `BondMustHaveOrder`) updated as
+  examples. `chemicalml constraints` command now shows descriptions
+  when present.
+
+- **Three new diverse fixtures**:
+  - `molecular/ethylene_with_cis_trans_stereo.cml` — bondStereo with
+    `atomRefs4` (cis/trans case)
+  - `reactions/free_radical_halogenation.cml` — multi-reactant
+    reaction with substanceList catalyst
+  - `spectroscopy/ethanol_nmr.cml` — NMR spectrum with xaxis/yaxis
+    arrays, peakList with multiplicity, metadataList
+
+- **Performance baseline spec** — establishes timing baselines for:
+  - XML/JSON serialisation of a 1000-atom molecule (< 2s)
+  - Molecular validation of a 1000-atom molecule (< 2s)
+  - `atom_count` / `find_atom` queries (< 500ms)
+  - Fixture parsing (< 20ms)
+
+- **MAJOR performance fix**: the `ReferencesShouldResolve` constraint
+  was taking **47.8 seconds** on a 1000-atom document. Root cause:
+  `ReferenceResolver#unresolved_for` called `containing_molecule`
+  for every bond, which walked the entire document every time
+  (O(n²) for n bonds × n molecules × n atoms).
+
+  Fixed by:
+  - Adding lazily-built `atom_index` (id → Atom hash, O(1) lookup)
+  - Removing the `containing_molecule` indirection in
+    `unresolved_for` — the resolver now uses the global atom index
+    directly. CML semantics already enforce that bond refs live in
+    the parent molecule (that's `BondMustReferenceAtomsInSameMolecule`'s
+    job).
+
+  Result: **47.8s → 68ms (680× faster)**.
+
+- **609 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The performance baseline spec paid for itself immediately by catching
+a 47-second regression that I'd introduced in round 22 when adding
+the `ReferencesShouldResolve` constraint. Without the baseline,
+this would have shipped to users.
+
+The fix follows the **build indices once, query many times** pattern.
+The resolver now builds an `atom_index` lazily on first lookup; all
+subsequent `find_atom` calls are O(1). This is a Ruby-native
+performance pattern that fits the existing architecture cleanly.
+
+Lesson: baseline specs aren't just for regression detection — they
+catch bugs that you didn't know you had. Always write the baseline
+before optimising.

data/docs/constraints.md

@@ -0,0 +1,161 @@
+# Registered Convention Constraints
+
+Auto-generated from `Chemicalml::Convention::Registry.each_constraint`.
+Last regenerated: 2026-07-20T09:43:53Z.
+
+Total constraints: **91**
+
+## convention:cascade
+
+- **Namespace**: `http://www.xml-cml.org/convention/cascade`
+- **Constraint count**: 4
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `ReactionSchemeMustHaveContent` | ReactionScheme | A `<reactionScheme>` MUST contain at least one `<reactionStepList>` or `<reaction>` child. An empty scheme carries no cascade information. |
+| `ReactionStepListMustContainSteps` | ReactionStepList | A `<reactionStepList>` MUST contain at least one `<reactionStep>` child. An empty step list breaks the cascade chain. |
+| `ReactionStepMustHaveReactionOrLists` | ReactionStep | A `<reactionStep>` MUST contain either a `<reaction>` child or explicit `<reactantList>` + `<productList>` children. An empty step is a dead-end in the cascade. |
+| `ReactiveCentreAtomRefsShouldBePresent` | ReactiveCentre | A `<reactiveCentre>` SHOULD declare its `atomRefs` attribute. Without atom references the reactive centre is indistinguishable from a placeholder. Warning severity — |
+
+## convention:compchem
+
+- **Namespace**: `http://www.xml-cml.org/convention/compchem`
+- **Constraint count**: 20
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `CompchemModuleMustContainJobList` | _(document-wide)_ | A CompChem module MUST contain at least one jobList module child per the compchem convention. |
+| `JobMustContainInitialization` | Module | A job module MUST contain exactly one initialization module child per the compchem convention. |
+| `JobListModuleMustHaveId` | Module | A jobList module MUST have an `id` unique within the compchem module. |
+| `JobModuleMustHaveId` | Module | A job module MUST have an `id` unique within the compchem module. |
+| `JobModuleAtMostOneFinalization` | Module | A job module MUST contain at most one finalization module. |
+| `JobModuleAtMostOneEnvironment` | Module | A job module MUST contain at most one environment module. |
+| `CalculationRequiresFinalization` | Module | Co-constraint: if a calculation module is present inside a job, a finalization MUST also be present. |
+| `InitializationAtMostOneMolecule` | Module | The initialization module MUST NOT contain more than one molecule child. |
+| `InitializationAtMostOneParameterList` | Module | The initialization module MUST NOT contain more than one parameterList child. |
+| `InitializationMustNotContainProperty` | Module | The initialization module MUST NOT contain property or propertyList children directly. (Properties belong in finalization.) |
+| `FinalizationAtMostOneMolecule` | Module | The finalization module MUST NOT contain more than one molecule child. |
+| `FinalizationAtMostOnePropertyList` | Module | The finalization module MUST NOT contain more than one propertyList child. |
+| `FinalizationMustNotContainParameter` | Module | The finalization module MUST NOT contain parameter or parameterList children directly. (Parameters belong in initialization.) |
+| `EnvironmentAtMostOnePropertyList` | Module | The environment module MUST NOT contain more than one propertyList child. |
+| `EnvironmentMustNotContainParameter` | Module | The environment module MUST NOT contain parameter or parameterList children directly. It MAY contain a propertyList (which itself can hold parameters). |
+| `ScalarUnits` | Scalar | CompChem value-container rules: `scalar` with dataType `xsd:integer` or `xsd:double` MUST have `units`; `scalar` with dataType `xsd:string` MUST NOT have `units`. |
+| `ArrayRules` | Array | CompChem `array` value-container rules: MUST have `size` attribute (≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `MatrixRules` | Matrix | CompChem `matrix` value-container rules: MUST have `rows` and `columns` attributes (each ≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `InitializationMustHaveContent` | Module | An `initialization` module MUST contain at least one of: `molecule`, `parameterList`, or a user-defined module child. Per the compchem convention spec. |
+| `FinalizationMustHaveContent` | Module | A `finalization` module MUST contain at least one of: `molecule`, `propertyList`, or a user-defined module child. Per the compchem convention spec. |
+
+## convention:dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/dictionary`
+- **Constraint count**: 8
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `EntryMustHaveIdAndTerm` | DictionaryEntry | Every entry MUST have an `id` and a `term` attribute per the dictionary convention. |
+| `EntryIdsUniqueWithinDictionary` | Dictionary | Entry ids MUST be unique within the parent dictionary per the dictionary convention. |
+| `DictionaryMustHaveNamespace` | Dictionary | A `<dictionary>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the entry terms are unique. |
+| `DictionaryNamespaceShouldEndWithSlashOrHash` | Dictionary | The `namespace` URI SHOULD end with `/` or `#` so terms can be referenced by appending them to the URI. Warning level. |
+| `EntryMustContainDefinition` | DictionaryEntry | An `<entry>` MUST contain a single `definition` child element. The schema allows it as a string; this constraint enforces presence. |
+| `EntryIdMustMatchPattern` | DictionaryEntry | An `<entry>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*` — start with a letter, followed by letters/digits/dot/hyphen/ underscore. Mirrors the upstream IdStartChar / IdChar BNF. |
+| `EntryMustHaveUnitType` | DictionaryEntry | An `<entry>` MUST have a `unitType` attribute. Entries describing concepts that should not have units (e.g. name of a program) should reference `none` in the standard CML |
+| `EntryUnitsCoConstraints` | DictionaryEntry | Co-constraint between `unitType` and `units`: - If `unitType` is `unknown`, `units` MUST NOT be present. - If `unitType` is `none`, `units` MUST be present and point |
+
+## convention:molecular
+
+- **Namespace**: `http://www.xml-cml.org/convention/molecular`
+- **Constraint count**: 36
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `AtomArrayMustContainAtoms` | Molecule | `atomArray` MUST contain at least one atom. The atoms can be in the child form (`<atom>` elements) or the parallel-array form (`atomID` attribute with whitespace-separated ids). |
+| `AtomIdsUniqueWithinMolecule` | _(document-wide)_ | Atom ids MUST be unique within the eldest containing molecule per the molecular convention. |
+| `BondMustReferenceAtomsInSameMolecule` | _(document-wide)_ | Bonds MUST reference atoms within the same parent molecule per the molecular convention. |
+| `AtomMustHaveId` | Atom | An <atom> inside an atomArray in a molecule MUST have an id attribute. |
+| `AtomMustHaveElementType` | Atom | An <atom> inside an atomArray in a molecule MUST have an elementType attribute. |
+| `BondMustHaveAtomRefs2` | Bond | A <bond> MUST have an atomRefs2 attribute referencing two distinct atoms in the same molecule. |
+| `BondMustHaveOrder` | Bond | A <bond> MUST have an order attribute (S/D/T/A recommended). |
+| `MoleculeMustHaveId` | Molecule | A <molecule> in a molecular document MUST have an id attribute unique within document scope. |
+| `AtomCoordinatesMustBePaired` | Atom | <atom> 2D coordinates (x2, y2) must appear together; 3D coordinates (x3, y3, z3) must appear together. |
+| `PropertyMustHaveDictRef` | Property | A <property> MUST have a dictRef attribute that identifies the property type via a dictionary entry. |
+| `ScalarMustHaveDataType` | Scalar | A <scalar> child of a <property> MUST have a dataType attribute (e.g. xsd:float, xsd:integer). |
+| `BondOrderShouldNotBeNumeric` | Bond | A <bond>'s order attribute SHOULD be one of S/D/T/Q/A or 'other' (numeric values are not recommended). |
+| `AtomIdMustMatchPattern` | Atom | An <atom>'s id attribute SHOULD start with a letter and contain only letters, digits, dot, hyphen, or underscore. |
+| `MoleculeCountMustNotAppearOnTopLevel` | _(document-wide)_ | Molecular convention: `count` MUST NOT appear on top-level molecules (direct children of `<cml>`). It is REQUIRED on molecules nested inside another `<molecule>`. |
+| `MoleculeAtomArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold an `atomArray` OR child `<molecule>` elements, but not both. The two are mutually exclusive ways of describing composition. |
+| `MoleculeBondArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold a `bondArray` OR child `<molecule>` elements, but not both. |
+| `BondStereoWedgeHashMustHaveAtomRefs2` | BondStereo | Molecular convention: `<bondStereo>` value W (wedge) or H (hatch) MUST have `atomRefs2` and MUST NOT have `atomRefs4`. |
+| `BondStereoCisTransMustHaveAtomRefs4` | BondStereo | Molecular convention: `<bondStereo>` value C (cis) or T (trans) MUST have `atomRefs4` and MUST NOT have `atomRefs2`. |
+| `BondStereoOtherMustHaveDictRef` | BondStereo | Molecular convention: `<bondStereo>` with value `other` MUST have a `dictRef` pointing to the convention that defines the stereo semantics. |
+| `BondIdsUniqueWithinMolecule` | _(document-wide)_ | Molecular convention: a `<bond>` `id` MUST be unique within the eldest containing molecule. Mirrors the existing `AtomIdsUniqueWithinMolecule` constraint for bonds. |
+| `BondOrderOtherMustHaveDictRef` | Bond | Molecular convention: `<bond>` with `order="other"` MUST have a `dictRef` pointing to the dictionary that defines the order semantics. The warning-level "should not be |
+| `AtomArrayMustBeChildOfMoleculeOrFormula` | _(document-wide)_ | Molecular convention: `<atomArray>` MUST be a child of `<molecule>` or `<formula>`. Any other parent is invalid. Checked from the parent's perspective during the walk — |
+| `BondArrayMustBeChildOfMolecule` | _(document-wide)_ | Molecular convention: `<bondArray>` MUST be a child of `<molecule>`. Any other parent is invalid. |
+| `BondOrderShouldBeInEnum` | Bond | A `<bond>`'s `order` attribute SHOULD be one of the XSD orderType enum values: S/1/D/2/T/3/A/unknown/other. Warning severity — CML permits extension values via |
+| `BondStereoShouldBeInEnum` | BondStereo | A `<bondStereo>`'s `value` attribute SHOULD be one of the XSD stereoType enum values: C/T/W/H/undefined/other. Warning severity. |
+| `MoleculeChiralityShouldBeInEnum` | Molecule | A `<molecule>`'s `chirality` attribute SHOULD be one of the XSD chiralityType enum values: enantiomer/racemate/unknown/other. Warning severity. |
+| `BondAtomRefs2ShouldBeDistinct` | Bond | A `<bond>`'s `atomRefs2` SHOULD reference two distinct atom ids. A self-bond (`a1 a1`) is chemically meaningless. Warning severity — there are edge cases in non-classical |
+| `ReferencesShouldResolve` | _(document-wide)_ | Walks the document via `Cml::ReferenceResolver` and reports every bond whose `atomRefs2` references atoms that don't exist in the parent molecule. Warning severity — there are |
+| `BondStereoAtomRefs4ShouldBeDistinct` | BondStereo | A `<bondStereo>` with `atomRefs4` (used by C/T stereo) SHOULD reference four distinct atom ids. Duplicate ids make the stereo descriptor meaningless. Warning severity. |
+| `AtomParityAtomRefs4ShouldBeDistinct` | AtomParity | An `<atomParity>` element's `atomRefs4` attribute SHOULD reference four distinct atom ids around a chiral center. Duplicate ids make the parity descriptor meaningless. |
+| `AtomElementTypeShouldBeInPeriodicTable` | Atom | An `<atom>`'s `elementType` attribute SHOULD be one of the XSD elementTypeType enum values (the periodic table plus the special "Du" dummy and "R" group placeholder). Warns |
+| `DictRefShouldResolve` | Atom, Bond, Molecule, Property, Scalar, Array, Matrix, Name, Label | Walks the document and warns on any element whose `dictRef` attribute cannot be resolved against the built-in dictionaries. Catches typos like `dictRef="cml:bpingpoint"`. |
+| `MoleculeIdShouldMatchPattern` | Molecule | A `<molecule>`'s `id` attribute SHOULD match the XSD moleculeIDType pattern (letter/underscore start, alphanumeric body, optional namespace prefix). Warning severity. |
+| `BondIdShouldMatchPattern` | Bond | A `<bond>`'s `id` attribute SHOULD match the XSD idType pattern (letter start, alphanumeric body with dots/dashes). Warning severity. |
+| `AtomParityShouldIncludeParentAtom` | _(document-wide)_ | Walks the document and warns on `<atomParity>` elements whose parent `<atom>`'s id does not appear in atomRefs4. The CML convention requires the parent atom to be one of |
+| `PropertyScalarDataTypeMatchesDictionary` | Property | A `<property>` with a `dictRef` whose dictionary entry declares a `dataType` SHOULD have a child `<scalar>` whose `dataType` attribute matches. Catches inconsistencies like a property |
+
+## convention:simpleUnit
+
+- **Namespace**: `http://www.xml-cml.org/convention/simpleUnit`
+- **Constraint count**: 3
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHavePower` | Unit | A `<unit>` under simpleUnit MUST declare a `power` attribute (integer). Without a power the unit's exponent is undefined. |
+| `UnitMustHaveSymbol` | Unit | A `<unit>` under simpleUnit MUST declare a non-empty `symbol` attribute. Without a symbol the unit cannot be rendered in formulae. |
+| `RootMustBeUnitList` | _(document-wide)_ | The root of a simpleUnit document MUST be a `<unitList>` declaring `convention="convention:simpleUnit"`. Any other root shape is rejected. |
+
+## convention:spectroscopy
+
+- **Namespace**: `http://www.xml-cml.org/convention/spectroscopy`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `SpectrumMustHaveConvention` | Spectrum | A `<spectrum>` MUST declare its own convention attribute so consumers know how to interpret its format and peaks. Per the molecular convention: "spectrum — any number, each MUST |
+| `SpectrumMustHaveFormat` | Spectrum | A `<spectrum>` MUST have a `format` attribute (e.g. "mass", "ir", "nmr", "uv") so consumers know the measurement type. |
+| `SpectrumMustHaveContent` | Spectrum | A `<spectrum>` MUST contain at least one of: `<xaxis>`, `<yaxis>`, `<peakList>`. An empty spectrum carries no data. |
+| `PeakListMustContainPeaks` | PeakList | A `<peakList>` MUST contain at least one `<peak>` or `<peakGroup>` child. An empty peakList carries no data. |
+| `PeakShouldHaveValues` | Peak | A `<peak>` SHOULD declare at least one of `xValue` or `yValue`. A peak with neither carries no position information. Warning severity — there are edge cases |
+
+## convention:unit-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unit-dictionary`
+- **Constraint count**: 10
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHaveSymbolAndUnitType` | Unit | Every unit MUST have `id`, `title`, `symbol`, `parentSI`, at least one of `multiplierToSI`/`constantToSI`, and `unitType` per the unit-dictionary convention. |
+| `UnitMustHaveId` | Unit | A `<unit>` element MUST have an `id` attribute, unique within the unitList. |
+| `UnitMustContainDefinition` | Unit | A `<unit>` element MUST contain a single `<definition>` child element with XHTML content. |
+| `UnitListMustHaveNamespace` | UnitList | A `<unitList>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the unit ids are unique. SHOULD end with `/` or `#`. |
+| `UnitListMustContainAtLeastOneUnit` | UnitList | A `<unitList>` element MUST contain one or more `<unit>` children, and MUST NOT contain any other CML-namespace child elements. |
+| `UnitMustHaveTitle` | Unit | A `<unit>` element MUST have a `title` attribute (the full human-readable name of the unit). Per the unit-dictionary convention spec. |
+| `UnitMustHaveParentSi` | Unit | A `<unit>` element MUST have a `parentSI` attribute — a QName referencing the SI unit it derives from. Per the unit-dictionary convention spec. |
+| `UnitMustHaveMultiplierOrConstantToSi` | Unit | A `<unit>` element MUST have at least one of `multiplierToSI` or `constantToSI` — to define the conversion to the parent SI unit. Per the unit-dictionary convention spec. |
+| `UnitUnitTypeShouldResolve` | Unit | A `<unit>`'s `unitType` attribute SHOULD reference a unitType that exists in a built-in unitType-dictionary. Catches typos like `unitType="unitType:lenght"` (misspelled). |
+| `UnitParentSiShouldResolve` | Unit | A `<unit>`'s `parentSI` attribute SHOULD reference a unit that exists in a built-in dictionary (typically the SI dictionary). Catches typos like `parentSI="si:metr"`. |
+
+## convention:unitType-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unitType-dictionary`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitTypeMustHaveIdAndName` | UnitType | Every unitType MUST have an `id` and a `name` attribute per the unitType-dictionary convention. |
+| `UnitTypeIdMustMatchPattern` | UnitType | A `<unitType>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*`. |
+| `UnitTypeMustContainDefinition` | UnitType | A `<unitType>` MUST contain a single `<definition>` child with XHTML content. |
+| `UnitTypeListMustHaveNamespace` | UnitTypeList | A `<unitTypeList>` MUST have a `namespace` attribute (valid URI, SHOULD end with `/` or `#`). |
+| `UnitTypeListMustContainAtLeastOneUnitType` | UnitTypeList | A `<unitTypeList>` MUST contain one or more `<unitType>` children. |

data/docs/generate_constraint_docs.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "chemicalml"
+
+# Auto-generated documentation of every registered convention
+# constraint. Run via `bundle exec rake docs:constraints` or
+# `bundle exec ruby docs/generate_constraint_docs.rb`.
+#
+# Single source of truth: derived from `Convention::Registry.each_constraint`.
+# Do not edit `docs/constraints.md` by hand — regenerate.
+
+output = []
+output << "# Registered Convention Constraints"
+output << ""
+output << "Auto-generated from `Chemicalml::Convention::Registry.each_constraint`."
+output << "Last regenerated: #{Time.now.utc.iso8601}."
+output << ""
+output << "Total constraints: **#{Chemicalml::Convention::Registry.total_constraint_count}**"
+output << ""
+
+Chemicalml::Convention::Registry.each do |conv|
+  output << "## #{conv.qname}"
+  output << ""
+  output << "- **Namespace**: `#{conv.namespace_uri}`"
+  output << "- **Constraint count**: #{conv.constraint_count}"
+  output << ""
+
+  output << "| Constraint | Applies to | Description |"
+  output << "|---|---|---|"
+  conv.constraints.each do |klass|
+    name = klass.name.split("::").last
+    roles = klass.applies_to_roles
+    applies = roles.nil? ? "_(document-wide)_" : roles.map { |r| r.name.split("::").last }.join(", ")
+    desc = klass.description
+    desc = "" if desc == name
+    desc_escaped = desc.gsub("|", "\\|")
+    output << "| `#{name}` | #{applies} | #{desc_escaped} |"
+  end
+  output << ""
+end
+
+path = File.expand_path("constraints.md", __dir__)
+File.write(path, output.join("\n"))
+puts "Wrote #{path} (#{Chemicalml::Convention::Registry.total_constraint_count} constraints)"

data/exe/chemicalml

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "chemicalml"
+exit Chemicalml::Cli.run(ARGV)

data/lib/chemicalml/cli/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Chemicalml
+  module Cli
+    # Thor-based dispatcher. Each command delegates to a dedicated
+    # `Chemicalml::Cli::*Command` class invoked as
+    # `MyCommand.new.run(options)`, where `options` is a single hash
+    # carrying both positional args (keyed by name) and flags.
+    #
+    # A `Chemicalml::Logger` bridged to Thor's shell is injected into
+    # every command — so info/warn/error get coloured output on the
+    # terminal while remaining loggable for library callers.
+    class Base < Thor
+      private
+
+      # Build a logger bridged to this Thor instance for coloured output.
+      def bridged_logger
+        Chemicalml::Logger.default.tap { |l| l.thor_shell = self }
+      end
+
+      public
+
+      desc 'validate FILE', 'Validate a CML file against its declared convention'
+      method_option :json, type: :boolean, aliases: '-j',
+                           desc: 'Emit machine-readable JSON output'
+      def validate(file)
+        ValidateCommand.new(logger: bridged_logger).run(file: file, json: options[:json])
+      end
+
+      desc 'inspect FILE', 'Print a tree-style summary of the document'
+      def inspect(file)
+        InspectCommand.new(logger: bridged_logger).run(file: file)
+      end
+
+      desc 'conventions', 'List registered conventions'
+      def conventions
+        ConventionsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'dictionaries', 'List built-in dictionaries'
+      def dictionaries
+        DictionariesCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'elements', 'List all CML wire classes'
+      def elements
+        ElementsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'constraints', 'List all registered constraints'
+      def constraints
+        ConstraintsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'enums', 'List all XSD enum constants'
+      def enums
+        EnumsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'info ELEMENT', 'Show details about a CML element'
+      def info(element)
+        InfoCommand.new(logger: bridged_logger).run(element: element)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # Base class for every command. Subclasses implement `#run(options)`.
+    #
+    # Each command receives a `Chemicalml::Logger` in its constructor.
+    # When dispatched via Thor (the normal CLI path), the logger is
+    # bridged to Thor's shell for coloured output. When invoked
+    # directly (MyCommand.new.run(options)), the logger writes plain
+    # text to $stderr.
+    class Command
+      attr_reader :logger
+
+      # @param logger [Chemicalml::Logger] the logger to use. Defaults
+      #   to a plain stderr logger. The Thor dispatcher passes one
+      #   bridged to Thor's shell for colour.
+      def initialize(logger: Chemicalml::Logger.default)
+        @logger = logger
+      end
+
+      class << self
+        def run(options = {}, logger: Chemicalml::Logger.default)
+          new(logger: logger).run(options)
+        end
+      end
+
+      def run(_options = {})
+        raise NotImplementedError, "#{self.class} must implement #run"
+      end
+
+      private
+
+      def puts(*args)
+        $stdout.puts(*args)
+      end
+
+      def stderr(*args)
+        $stderr.puts(*args)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/constraints_command.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml constraints` — list every registered constraint
+    # across every convention with its applies_to roles.
+    class ConstraintsCommand < Command
+      def run(_options = {})
+        current = nil
+        Chemicalml::Convention::Registry.each_constraint do |conv, klass|
+          unless conv.qname == current
+            current = conv.qname
+            puts ''
+            puts "=== #{current} (#{conv.constraint_count}) ==="
+          end
+          name = klass.name.split('::').last
+          applies = klass.applies_to_roles
+          roles_str = applies.nil? ? '' : "  → #{applies.map { |r| r.name.split('::').last }.join(', ')}"
+          puts "  #{name}#{roles_str}"
+          desc = klass.description
+          puts "    #{desc}" unless desc == name
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/conventions_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml conventions` — list every registered convention
+    # by QName, sorted.
+    class ConventionsCommand < Command
+      def run(_options = {})
+        Chemicalml::Convention::Registry.builtin_qnames.sort.each { |q| puts q }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/dictionaries_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml dictionaries` — list built-in YAML dictionaries
+    # by short name.
+    class DictionariesCommand < Command
+      def run(_options = {})
+        Chemicalml::Dictionary::Registry.builtin_names.each { |n| puts n }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/elements_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml elements` — list every CML wire class registered
+    # in Schema3 with its XML element name.
+    class ElementsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        Chemicalml::Cml::Elements::ALL.sort.each do |cls, xml_id|
+          puts "#{cls.to_s.ljust(25)} → <#{xml_id}>"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/enums_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml enums` — list every `Cml::Enums` constant with
+    # its allowed values.
+    class EnumsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Enums.constants(false).sort.each do |name|
+          values = Chemicalml::Cml::Enums.const_get(name)
+          puts "#{name} (#{values.size}): #{values.to_a.sort.first(20).join(', ')}"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/info_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml info <element>` — show details about a CML element
+    # by XML name: Ruby class, role, attributes, applicable constraints.
+    class InfoCommand < Command
+      def run(options)
+        name = options[:element]
+        unless name
+          logger.error 'info requires an <element-name> argument (e.g. "atom")'
+          return 2
+        end
+
+        klass = Chemicalml::Cml.for_xml_name(name)
+        unless klass
+          stderr "unknown element: #{name}"
+          return 2
+        end
+
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        puts "Element: <#{name}>"
+        puts "Class:   #{klass}"
+        role = role_of(klass)
+        puts "Role:    #{role || '(none)'}"
+        puts ''
+        puts "Attributes (#{klass.attributes.size}):"
+        klass.attributes.each_value do |attr|
+          col = attr.collection? ? '[]' : ' '
+          puts "  #{attr.name}#{col}"
+        end
+        applicable = constraints_for_role(role)
+        return 0 if applicable.empty?
+
+        puts ''
+        puts "Applicable constraints (#{applicable.size}):"
+        applicable.each do |(conv, c)|
+          puts "  [#{conv.qname}] #{c.name.split('::').last}"
+        end
+        0
+      end
+
+      private
+
+      def role_of(klass)
+        # Find the most specific Role module included in klass
+        # (the one with the longest name that matches Cml::Role::*).
+        klass.ancestors.find do |a|
+          next false unless a.is_a?(Module)
+          next false unless a.name
+
+          a.name.start_with?('Chemicalml::Cml::Role::')
+        end
+      end
+
+      def constraints_for_role(role)
+        return [] unless role
+
+        Chemicalml::Convention::Registry.each_constraint.with_object([]) do |(conv, c), acc|
+          roles = c.applies_to_roles
+          next if roles.nil?
+
+          matched = roles.any? do |r|
+            role <= r
+          rescue StandardError
+            false
+          end
+          next unless matched
+
+          acc << [conv, c]
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end