asciichem 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49f3af36729edc3293bb97099d74298533a509ae26aa3c14151a7cef743f654f
-  data.tar.gz: 24f5d0778e9f7dce477423b27b1ec5ebcab08472452389f126473234e8500a19
+  metadata.gz: 2dee0024c277879fed3b5695a76e336067660467724663c4a67f71ec87215e80
+  data.tar.gz: 50d5a53fd8d4f64a0d3969c586e81552faed9221a8f209932cd6823a2a966327
 SHA512:
-  metadata.gz: 599beaeb33d3bf776076632c83d2c92c16a08571088f3bb272163f61a9082e250af150b3300a80821fc3bb6ab5ffa8d65cc8b5007b4860f0dace0a94b70aaf83
-  data.tar.gz: 6fbc557626b9767110bc142c54ae6858b644d563af73f431bd48d8dbd7dabdfeeb79b7ecbb498474d791b35f1717b9ae28689ee1630f352fa48a3e0abcf966a6
+  metadata.gz: 3afdd1db8e99729ca9a1a49be7a748fd56d1fdb666b5bfe10bb03a08c6d7db440ca82b3c900b6f22f09ac66901d7c086913a2a3e8c142bc6c7d776f21959c629
+  data.tar.gz: ba3091db4ea3a3d7ba8dcd28f9689df323b135e1e1e4f0a3f3573f14350448461f9f3ade4e20fe4e7af9408d0ce40c1764bba4d609a05bd770705be431ca497b

data/.github/workflows/ci.yml

@@ -14,8 +14,17 @@ jobs:
         ruby: ["3.3", "3.4"]
     steps:
       - uses: actions/checkout@v4
+      - name: Clone conformance corpus (asciichem-tests)
+        run: git clone --depth 1 https://github.com/asciichem/asciichem-tests.git ../asciichem-tests
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
       - run: bundle exec rspec
+      - name: Publish conformance report
+        if: matrix.ruby == '3.4'
+        uses: actions/upload-artifact@v4
+        with:
+          name: conformance
+          path: conformance.json
+          if-no-files-found: warn

data/.github/workflows/release.yml

@@ -11,14 +11,17 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
-    environment: release
+    # Trusted publishing (OIDC): the publisher registered on RubyGems.org
+    # is repository asciichem/asciichem-ruby + workflow release.yml, with
+    # no environment — so this job must not claim one.
     permissions:
       contents: read
-      packages: write
+      id-token: write
     steps:
       - uses: actions/checkout@v4
         with:
           ref: main
+          persist-credentials: false
       - name: Verify version matches input
         run: |
           actual=$(ruby -e 'require "./lib/asciichem/version"; print AsciiChem::VERSION')
@@ -31,21 +34,8 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler-cache: true
-      - name: Build gem
-        run: bundle exec rake build
-      - name: Set up RubyGems credentials
-        env:
-          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
-        run: |
-          mkdir -p $HOME/.gem
-          cat > $HOME/.gem/credentials <<EOF
-          ---
-          :rubygems_api_key: ${RUBYGEMS_API_KEY}
-          EOF
-          chmod 0600 $HOME/.gem/credentials
-      - name: Push to RubyGems
-        run: |
-          gem push pkg/asciichem-${{ inputs.version }}.gem
+      # Builds and pushes using the GitHub OIDC identity — no API keys.
+      - uses: rubygems/release-gem@v1
       - name: Summary
         run: |
           echo "Released asciichem ${{ inputs.version }} to RubyGems"

data/.gitignore

@@ -12,3 +12,4 @@
 /.vscode/
 /.idea/
 *.gem
+conformance.json

data/CHANGELOG.md

@@ -3,6 +3,45 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.21.0] - 2026-09-12
+
+### Added
+- Structure interchange (TODO.v2 09, TODO.impl 57): SMILES and
+  molfile (CTfile V2000) ingestion and emission as modules of the one
+  semantic model — `AsciiChem.parse_smiles` / `parse_molfile`,
+  `to_smiles` / `to_molfile`. Ingested molecules are ordinary
+  `Model::Molecule`s: graphs linearise into atoms + bond tokens +
+  ring-closure digits (`Structure::Linearizer`), so every existing
+  renderer, linter, and wire form works unchanged. The SMILES writer
+  is deterministic (DFS, single-bond continuations, order-independent
+  tie-breaks); aspirin and naphthalene round-trip exactly. v1
+  deferrals, each with an actionable `ParseError`: chirality `@`/`@@`,
+  E/Z directions `/` `\`, wildcard atoms, bonded ring closures.
+- `Model::Atom#aromatic` / `#hydrogens` and an `aromatic` bond kind
+  (asciichem-model 0.4.0 fields): lowercase SMILES atoms, bracket
+  H-counts, molfile type-4 bonds (aromatic atoms marked from bonds).
+- `AsciiChem::Structure` — shared graph walk + adjacency linearizer
+  for the interchange formats; `StructuralSvg` renders aromatic bonds
+  dashed; wire form carries the new fields both ways.
+- Corpus levels: asciichem-tests v0.3.0 `structure/smiles/*` and
+  `structure/molfile/*` fixtures at 100% (37 + 6 cases).
+
+## [0.20.0] - 2026-09-12
+
+### Added
+- Canonical JSON wire form (`to_model_json` / `AsciiChem.from_model_json`)
+  per asciichem-model v1: `AsciiChem::Wire` (lutaml-model Serializable
+  classes, json mappings only - no hand-rolled serialization) bridged by
+  `AsciiChem::WireAdapter` (model-to-model conversion, same pattern as
+  the CML ModelAdapter). Emission covers every node type; ingestion
+  covers the lossless core set (beyond-formulas nodes are emission-only
+  until their corpus round-trip acceptance lands).
+- Conformance runner over the shared corpus (asciichem-tests): L0
+  emission + schema validation, L1 Text round-trip, L3 CML round-trip,
+  L4 linter diagnostics, plus the ParseError contract for rejects.
+  Emits conformance.json; CI clones the corpus and publishes the report
+  as an artifact. Current claim: L0 149/149, L1 16/16, L3 23/23, L4 6/6.
+
 ## [0.19.0] - 2026-09-09
 
 ### Added
@@ -347,7 +386,9 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/commits/main
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...v0.21.0
+[0.20.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.19.0...v0.20.0
 [0.18.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.18.0...v0.18.1
 [0.18.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.16.0...v0.17.0

data/RELEASING.md

@@ -83,10 +83,15 @@ tag.
 
 == Publish to RubyGems
 
-[source,sh]
-----
-gem push pkg/asciichem-0.X.Y.gem
-----
+The Release workflow (`.github/workflows/release.yml`) publishes via
+https://guides.rubygems.org/trusted-publishing/[RubyGems trusted publishing]
+(OIDC) — there are no API keys. Its trusted publisher is registered on
+https://rubygems.org (repository `asciichem/asciichem-ruby`, workflow
+`release.yml`, no environment).
+
+On the repository's Actions tab, run the "Release" workflow with the
+version number. It verifies the version matches `version.rb`, builds
+the gem, and pushes it using the workflow's GitHub OIDC identity.
 
 Verify at https://rubygems.org/gems/asciichem.
 

data/asciichem.gemspec

@@ -35,8 +35,11 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "chemicalml", "~> 0.3.0"
   spec.add_dependency "elkrb", "~> 1.0"
+  spec.add_dependency "lutaml-model", ">= 0.8", "< 2"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
   spec.add_dependency "plurimath", "~> 0.8"
   spec.add_dependency "thor", "~> 1.3"
+
+  spec.add_development_dependency "asciichem-model", "~> 0.3.4"
 end

data/lib/asciichem/formatter/structural_svg.rb

@@ -258,6 +258,14 @@ module AsciiChem
         RENDERERS = {
           single: ->(r) { [r.base_line] },
 
+          # Aromatic bonds render as dashed lines (the inner-ring
+          # circle is a renderer nicety left for a later iteration).
+          aromatic: lambda do |r|
+            line = r.base_line
+            line['stroke-dasharray'] = '4 2.5'
+            [line]
+          end,
+
           double: ->(r) { [-SPACING, 0, SPACING].map { |d| r.offset_line(d) }.compact },
 
           triple: ->(r) { [0, -SPACING * 1.5, SPACING * 1.5].map { |d| r.offset_line(d) }.compact },

data/lib/asciichem/model/atom.rb

@@ -34,7 +34,7 @@ module AsciiChem
       attr_accessor :element, :isotope, :subscript, :superscript,
                     :charge, :oxidation_state,
                     :lone_pairs, :radical_electrons,
-                    :ring_closures,
+                    :ring_closures, :aromatic, :hydrogens,
                     :x2, :y2, :z2, :atom_parity,
                     :spin_multiplicity, :atom_title,
                     :x_fract, :y_fract, :z_fract
@@ -58,7 +58,7 @@ module AsciiChem
       def initialize(element:, isotope: nil, subscript: nil,
                      superscript: nil, charge: nil, oxidation_state: nil,
                      lone_pairs: nil, radical_electrons: nil,
-                     ring_closures: nil,
+                     ring_closures: nil, aromatic: nil, hydrogens: nil,
                      x2: nil, y2: nil, z2: nil, atom_parity: nil,
                      spin_multiplicity: nil, atom_title: nil,
                      x_fract: nil, y_fract: nil, z_fract: nil)
@@ -71,6 +71,8 @@ module AsciiChem
         @lone_pairs = lone_pairs
         @radical_electrons = radical_electrons
         @ring_closures = ring_closures
+        @aromatic = aromatic
+        @hydrogens = hydrogens
         @x2 = x2
         @y2 = y2
         @z2 = z2
@@ -87,7 +89,8 @@ module AsciiChem
           superscript: superscript, charge: charge,
           oxidation_state: oxidation_state,
           lone_pairs: lone_pairs, radical_electrons: radical_electrons,
-          ring_closures: ring_closures,
+          ring_closures: ring_closures, aromatic: aromatic,
+          hydrogens: hydrogens,
           x2: x2, y2: y2, z2: z2, atom_parity: atom_parity,
           spin_multiplicity: spin_multiplicity, atom_title: atom_title,
           x_fract: x_fract, y_fract: y_fract, z_fract: z_fract }
@@ -108,6 +111,8 @@ module AsciiChem
         parts << "^(#{oxidation_state})" if oxidation_state
         parts << ".#{radical_electrons}" if radical_electrons
         parts << ring_closures.to_s if ring_closures
+        parts << "aromatic" if aromatic
+        parts << "H#{hydrogens}" if hydrogens
         "Atom(#{parts.join})"
       end
     end

data/lib/asciichem/model/bond.rb

@@ -14,7 +14,8 @@ module AsciiChem
         wedge:     { ascii: ">-", mathml_entity: "↑" },
         hash:      { ascii: "-<", mathml_entity: "↓" },
         dative:    { ascii: "~>", mathml_entity: "→" },
-        wavy:      { ascii: "~~", mathml_entity: "∼" }
+        wavy:      { ascii: "~~", mathml_entity: "∼" },
+        aromatic:  { ascii: ":",  mathml_entity: ":" }
       }.freeze
 
       # CML wire order codes per bond kind. Single source of truth

data/lib/asciichem/model/node.rb

@@ -62,6 +62,26 @@ module AsciiChem
         AsciiChem::Cml.from_asciichem(self)
       end
 
+      # Canonical JSON wire form (asciichem-model v1). The Text
+      # formatter canonicalises AsciiChem text; this canonicalises
+      # the semantic model itself — the interchange format every
+      # implementation must parse and emit.
+      def to_model_json
+        AsciiChem::WireAdapter.to_model_json(self)
+      end
+
+      # Deterministic SMILES for a Molecule (or dot-joined components
+      # for a Formula). Raises for constructs with no SMILES form.
+      def to_smiles
+        AsciiChem::Smiles.write(self)
+      end
+
+      # Molfile V2000 for a Molecule. Authored coordinates win; a
+      # deterministic 2D layout is computed otherwise.
+      def to_molfile(name: nil)
+        AsciiChem::Molfile.write(self, name: name)
+      end
+
       # Subclasses override to expose the attributes that participate in
       # equality. Default: empty (so two bare Nodes are equal).
       def value_attributes

data/lib/asciichem/molfile/parser.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Molfile
+    # V2000 molfile → Model::Molecule. Fixed-format blocks: header
+    # (3 lines), counts line, atom block, bond block, property block.
+    # Charges come from `M  CHG`, isotopes from the mass-difference
+    # field or `M  ISO`, bond stereo codes 1/6 become wedge/hash.
+    class Parser
+      def initialize(text)
+        @lines = text.lines.map(&:chomp)
+      end
+
+      def parse
+        raise ParseError, "molfile too short" if @lines.length < 5
+
+        atom_field = field(3, 0, 3)
+        bond_field = field(3, 3, 3)
+        unless atom_field.match?(/\A\d+\z/) && bond_field.match?(/\A\d+\z/)
+          raise ParseError, "malformed counts line: #{@lines[3].inspect}"
+        end
+        atom_count = atom_field.to_i
+        bond_count = bond_field.to_i
+
+        atoms = parse_atoms(atom_count)
+        bonds = parse_bonds(bond_count)
+        properties = parse_properties
+
+        apply_legacy_charge!(atoms)
+        apply_charges!(atoms, properties[:charges])
+        apply_isotopes!(atoms, properties[:isotopes])
+
+        adjacency = Array.new(atoms.length) { {} }
+        bonds.each do |bond|
+          adjacency[bond[:from]][bond[:to]] = bond[:kind]
+          adjacency[bond[:to]][bond[:from]] = bond[:kind]
+        end
+
+        # V2000 carries aromaticity on bonds (type 4); the model
+        # carries it on atoms and bonds, so atoms touching an
+        # aromatic bond are marked aromatic.
+        bonds.each do |bond|
+          next unless bond[:kind] == :aromatic
+
+          atoms[bond[:from]].aromatic = true
+          atoms[bond[:to]].aromatic = true
+        end
+
+        Model::Molecule.new(
+          nodes: Structure::Linearizer.new(atoms: atoms, edges: adjacency_to_edges(adjacency)).nodes
+        )
+      end
+
+      private
+
+      def field(line_index, start, length)
+        (@lines[line_index] || "")[start, length].to_s.strip
+      end
+
+      def parse_atoms(count)
+        (1..count).map do |i|
+          line_index = 3 + i
+          line = @lines[line_index]
+          raise ParseError, "truncated atom block (expected #{count} atoms)" if line.nil?
+
+          x = line[0, 10].to_f
+          y = line[10, 10].to_f
+          z = line[20, 10].to_f
+          element = line[31, 3].to_s.strip
+          mass_diff = line[34, 2].to_i
+          raise ParseError, "atom #{i} has no element symbol" if element.empty?
+
+          Model::Atom.new(
+            element: element,
+            x2: x, y2: y, z2: z,
+            isotope: isotope_from_mass_diff(element, mass_diff)
+          )
+        end
+      end
+
+      def parse_bonds(count)
+        (1..count).map do |i|
+          line = @lines[3 + atoms_count + i]
+          raise ParseError, "truncated bond block (expected #{count} bonds)" if line.nil?
+
+          from = line[0, 3].to_i - 1
+          to = line[3, 3].to_i - 1
+          type = line[6, 3].to_i
+          stereo = line[9, 3].to_i
+          raise ParseError, "bond #{i} has out-of-range atom indexes" if from.negative? || to.negative?
+
+          { from: from, to: to, kind: bond_kind(type, stereo) }
+        end
+      end
+
+      def parse_properties
+        charges = {}
+        isotopes = {}
+        @lines.each do |line|
+          if line.start_with?("M  CHG")
+            parts = line[6..].split
+            _count = parts[0].to_i
+            parts[1..].each_slice(2) do |idx, charge|
+              charges[idx.to_i - 1] = charge.to_i if idx && charge
+            end
+          elsif line.start_with?("M  ISO")
+            parts = line[6..].split
+            parts[1..].each_slice(2) do |idx, mass|
+              isotopes[idx.to_i - 1] = mass.to_i if idx && mass
+            end
+          end
+        end
+        { charges: charges, isotopes: isotopes }
+      end
+
+      def bond_kind(type, stereo)
+        return :wedge if stereo == 1
+        return :hash if stereo == 6
+
+        { 1 => :single, 2 => :double, 3 => :triple, 4 => :aromatic }[type] ||
+          raise(ParseError, "unsupported molfile bond type #{type}")
+      end
+
+      # Pre-CHG charge column (0-based 36, 3): nonzero values 1..4
+      # mean +1..+4, 5..7 mean -1..-3. `M  CHG` overrides.
+      def apply_legacy_charge!(atoms)
+        (1..field(3, 0, 3).to_i).each do |i|
+          code = field(3 + i, 36, 3).to_i
+          next if code.zero?
+
+          charge = code <= 4 ? code : 4 - code
+          sign = charge.negative? ? "-" : "+"
+          atoms[i - 1].charge = charge.abs == 1 ? sign : "#{charge.abs}#{sign}"
+        end
+      end
+
+      def apply_charges!(atoms, charges)
+        charges.each do |index, value|
+          sign = value.negative? ? "-" : "+"
+          atoms[index].charge = value.abs == 1 ? sign : "#{value.abs}#{sign}"
+        end
+      end
+
+      def apply_isotopes!(atoms, isotopes)
+        isotopes.each do |index, mass|
+          atoms[index].isotope = mass.to_s
+        end
+      end
+
+      # Mass difference encodes isotopes relative to the rounded
+      # average mass; mapping it unambiguously requires isotope
+      # tables, so v1 defers isotopes to the explicit `M  ISO` block.
+      def isotope_from_mass_diff(_element, mass_diff)
+        nil
+      end
+      def atoms_count
+        field(3, 0, 3).to_i
+      end
+
+      def adjacency_to_edges(adjacency)
+        edges = []
+        adjacency.each_with_index do |neighbors, index|
+          neighbors.each { |to, kind| edges << Structure::Graph::Edge.new(from: index, to: to, kind: kind) if to > index }
+        end
+        edges
+      end
+    end
+  end
+end

data/lib/asciichem/molfile/writer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Molfile
+    # Model molecule → V2000 molfile. Authored x2/y2 coordinates are
+    # used when present; otherwise a deterministic 2D layout is
+    # computed (Layout walks atoms in the same order as
+    # Structure::Graph, so positions map by index). Charges and
+    # isotopes are emitted as `M  CHG` / `M  ISO` property lines.
+    class Writer
+      BOND_TYPES = {
+        single: 1, double: 2, triple: 3, aromatic: 4,
+        wedge: 1, hash: 1
+      }.freeze
+      BOND_STEREO = { wedge: 1, hash: 6 }.freeze
+
+      def initialize(molecule, name: nil)
+        @molecule = molecule
+        @name = name
+      end
+
+      def write
+        atoms, edges = Structure::Graph.build(@molecule)
+        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty?
+
+        lines = []
+        lines << @name.to_s
+        lines << "  AsciiChem"
+        lines << ""
+        lines << format("%3d%3d  0  0  0  0  0  0  0  0999 V2000", atoms.length, edges.length)
+
+        layout = nil
+        atoms.each_with_index do |atom, index|
+          x, y = coordinates(atom, index, atoms)
+          lines << format("%10.4f%10.4f%10.4f %-3s 0  0  0  0  0  0  0  0  0  0  0  0",
+                          x, y, atom.z2 || 0.0, atom.element)
+        end
+
+        edges.each do |edge|
+          type = BOND_TYPES.fetch(edge.kind) do
+            raise ParseError, "#{edge.kind} bonds have no molfile V2000 type"
+          end
+          stereo = BOND_STEREO.fetch(edge.kind, 0)
+          lines << format("%3d%3d%3d%3d  0  0  0  0  0  0  0",
+                          edge.from + 1, edge.to + 1, type, stereo)
+        end
+
+        lines << property_line("M  CHG", charge_pairs(atoms))
+        lines << property_line("M  ISO", isotope_pairs(atoms))
+        lines << "M  END"
+        lines.compact.join("\n") << "\n"
+      end
+
+      private
+
+      # Authored coordinates win; otherwise positions from the
+      # deterministic 2D layout (same walk order as the graph).
+      def coordinates(atom, index, atoms)
+        return [atom.x2, atom.y2] if atom.x2 && atom.y2
+
+        @layout ||= AsciiChem::Layout.layout(@molecule)
+        placed = @layout.atoms[index]
+        placed ? [placed.x, placed.y] : [0.0, 0.0]
+      end
+
+      def charge_pairs(atoms)
+        atoms.each_with_index
+             .filter_map { |atom, i| [i + 1, charge_value(atom.charge)] if atom.charge }
+      end
+
+      def isotope_pairs(atoms)
+        atoms.each_with_index
+             .filter_map { |atom, i| [i + 1, atom.isotope.to_i] if atom.isotope }
+      end
+
+      # The model's number-then-sign charge ("2+") → signed integer.
+      def charge_value(charge)
+        count = charge[/\A\d+/]&.to_i || 1
+        charge.end_with?("-") ? -count : count
+      end
+
+      def property_line(prefix, pairs)
+        return nil if pairs.empty?
+
+        pairs.reduce(+"#{prefix}%3d" % pairs.length) do |line, (idx, value)|
+          line << format("%4d%4d", idx, value)
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/molfile.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Molfile (CTfile V2000) ingestion and emission (TODO.v2 09;
+  # TODO.impl 57). Molfile is the highest-fidelity structure path:
+  # atom coordinates are preserved on the model (x2/y2/z2), charges
+  # via the CHG property block, isotopes via mass difference or the
+  # ISO block, bond stereo codes 1/6 map to wedge/hash bonds.
+  module Molfile
+    autoload :Parser, "asciichem/molfile/parser"
+    autoload :Writer, "asciichem/molfile/writer"
+
+    class << self
+      # Parses a V2000 molfile into a Model::Molecule.
+      def parse(text)
+        Parser.new(text).parse
+      end
+
+      # Emits a V2000 molfile. Uses authored x2/y2 coordinates;
+      # computes a 2D layout otherwise.
+      def write(molecule, name: nil)
+        Writer.new(molecule, name: name).write
+      end
+    end
+  end
+end