metanorma-plugin-asciichem 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 582411f25fabc8527cec867947b12b663e2e3944724910676c56c562e485de3e
+  data.tar.gz: d49a888d06069c133646bdc2f7e7ecb628662804a508c35858454d27437af862
+SHA512:
+  metadata.gz: d51b92da35d3cf24e9d1da8acca09f8d95abf1f98e6ed9aa3b9e8ada5912c9218f8341b1f7fa4627a16e072bf6d270b2b597d8457ced0d6466082c7298d0650a
+  data.tar.gz: 73213d86ba4cbc8d7c4adbbc91920e55f2a3c67aa3da2989a442c8af26f7c31a3caf7a6a45d0ae56df3f1bf28f6f5738413ed399c2cea56369511f1b8e2cfc52

data/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+      - run: bundle exec rubocop

data/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (must match lib/metanorma/plugin/asciichem/version.rb)"
+        required: true
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC): register the publisher on RubyGems.org
+    # as repository metanorma/metanorma-plugin-asciichem + workflow
+    # release.yml, with no environment — so this job must not claim
+    # one.
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+          persist-credentials: false
+      - name: Verify version matches input
+        run: |
+          actual=$(ruby -e 'require "./lib/metanorma/plugin/asciichem/version"; print Metanorma::Plugin::Asciichem::VERSION')
+          if [ "$actual" != "${{ inputs.version }}" ]; then
+            echo "Version mismatch: input=${{ inputs.version }}, version.rb=$actual"
+            exit 1
+          fi
+          echo "Releasing $actual"
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      # CI never pushes to git (read-only contents). `rake release`
+      # attempts `git push origin main` after publishing unless the
+      # version tag already exists locally — bundler then skips its
+      # git stage entirely (see asciichem-ruby PR 86 for the incident).
+      - name: Pre-create the release tag (skips rake's git stage)
+        run: git tag "v${{ inputs.version }}"
+      # Builds and pushes using the GitHub OIDC identity — no API keys.
+      - uses: rubygems/release-gem@v1
+      - name: Summary
+        run: |
+          echo "Released metanorma-plugin-asciichem ${{ inputs.version }} to RubyGems"
+          echo "https://rubygems.org/gems/metanorma-plugin-asciichem"

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+/ruby/
+/.vscode/
+/.idea/
+*.gem
+Gemfile.lock
+/.html.err.html

data/.rubocop.yml

@@ -0,0 +1,26 @@
+require:
+  - rubocop
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  Exclude:
+    - "pkg/**/*"
+    - "vendor/**/*"
+    - "coverage/**/*"
+
+# The extension rewrites nodes inside Asciidoctor's visitor contract;
+# methods mirror that contract and read top-to-bottom.
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+# Gem-name entry file (require "metanorma-plugin-asciichem"), the
+# plugin-family convention (metanorma-plugin-lutaml does the same).
+Naming/FileName:
+  Exclude:
+    - "lib/metanorma-plugin-asciichem.rb"

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Changed
+
+- Requires asciichem >= 0.29.2 (relaton-bib `< 3`), enabling
+  co-resolution with current metanorma gems; metanorma-standoc is
+  now a development dependency.
+- End-to-end standoc compile wired into the suite
+  (`standoc_spec.rb`): `[chem]` → `<formula><stem type="MathML">`,
+  dataset bibitems verbatim in `<references normative="false">`,
+  InChIKey anchors.
+- Citation anchors are derived from the emitted bibitem XML (works
+  under both relaton-bib major lines) instead of vendor object APIs.
+
+## [0.1.0] - 2026-09-16
+
+### Added
+
+- `[chem]` block: AsciiChem source parses to the semantic model and
+  renders as a MathML stem (`<formula><stem type="MathML">` in
+  Metanorma semantic XML). Block ids and titles carry over; invalid
+  sources log an error and keep the block as sourcecode.
+- `chem:[]` inline macro (target and attribute forms) for inline
+  chemistry.
+- Substance citations: `@cite`-annotated molecules in `[chem]` blocks
+  resolve through `AsciiChem::Citation` to dataset-type Relaton
+  bibitems, one per (source, substance), deduplicated, anchored by
+  InChIKey, appended as a `[bibliography]` section.
+- `:asciichem-cache-dir:` document attribute for offline,
+  reproducible citation resolution.
+
+## [0.1.0-renamed] - 2026-09-17
+### Renamed
+
+- The gem moves to the metanorma org as
+  `metanorma-plugin-asciichem` (from asciichem/metanorma-asciichem),
+  following the plugin-family convention (lutaml, glossarist,
+  plantuml). Namespace is now `Metanorma::Plugin::Asciichem` with
+  lib at `metanorma/plugin/asciichem`; the require-by-name entry is
+  `metanorma-plugin-asciichem`. Per the plugin contract the gem no
+  longer self-registers with Asciidoctor — metanorma-standoc
+  requires and registers it (as it does for lutaml/glossarist).
+  Not released under the previous name, so the rename is invisible
+  to users.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'metanorma-standoc', '~> 3.5'
+  gem 'rake', '~> 13.2'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.66'
+end

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,143 @@
+# metanorma-plugin-asciichem
+
+[AsciiChem](https://www.asciichem.org) chemistry for
+[Metanorma](https://www.metanorma.org) documents: `[chem]` blocks and
+`chem:[]` inline macros render chemistry as MathML, and
+`@cite`-annotated molecules resolve into dataset-type Relaton
+bibitems — one per (source, substance), anchored by InChIKey —
+collected automatically into the document bibliography.
+
+## Installation
+
+```sh
+gem install metanorma-plugin-asciichem
+```
+
+The plugin follows the lutaml/glossarist contract: it exposes the
+extension classes and does not register them itself — the host
+does. [metanorma-standoc](https://github.com/metanorma/metanorma-standoc)
+requires and registers this gem (see its converter), so with the
+gem installed, `[chem]` and `chem:[]` are active in every Metanorma
+compile. Outside Metanorma, register manually:
+
+```ruby
+require "metanorma-plugin-asciichem"
+
+Asciidoctor::Extensions.register do
+  treeprocessor Metanorma::Plugin::Asciichem::Extension::ChemTreeprocessor
+  inline_macro Metanorma::Plugin::Asciichem::Extension::ChemInlineMacro, :chem
+end
+```
+
+## Usage
+
+### Chemistry blocks
+
+```adoc
+[chem]
+----
+2H_2 + O_2 -> 2H_2O
+----
+```
+
+The block's AsciiChem source parses into the semantic model and
+renders as MathML. In the semantic XML this becomes
+`<formula><stem type="MathML">…</stem></formula>` — the same shape
+Metanorma uses for math, so every flavour renders it. Block ids and
+titles carry over (`[chem#reaction,title="Hydrolysis"]`).
+
+Invalid AsciiChem logs an error and keeps the original block as
+sourcecode — the build stays reproducible, the problem stays visible.
+
+### Inline chemistry
+
+```adoc
+Water is chem:H_2O[] in prose, or chem:[2H_2 + O_2 -> 2H_2O] for
+sources with spaces.
+```
+
+Inline macros render; they do not contribute citations (inline
+substitution runs after the document pass that collects them).
+
+### Substance citations
+
+Annotate a molecule with `@cite` naming the source to cite from; the
+molecule's other identifiers say who to resolve it as:
+
+```adoc
+[chem]
+----
+CC(=O)OC1=CC=CC=C1C(=O)O @cas("50-78-2") @cite("pubchem")
+----
+
+The record is <<BSYNRYMUTXBXSQ-UHFFFAOYSA-N>>.
+```
+
+The build resolves the molecule (CAS RN → PubChem) and appends a
+`[bibliography]` section containing one `<bibitem type="dataset">`
+per (source, substance):
+
+- **Same substance cited twice** → one deduplicated entry per source.
+- **Two sources for one substance** → two entries (PubChem and CAS
+  Common Chemistry are different documents), both anchored by the
+  same InChIKey — the cross-document join key.
+- Every identifier the source returned rides along as a `keyword`, so
+  citations stay machine-checkable long after page numbers change.
+
+Resolution goes through `AsciiChem::Citation.for_molecule` — the same
+code path as the `asciichem cite` CLI — so the document pipeline and
+the command line can never drift.
+
+**Offline/reproducible builds.** Results come from the AsciiChem
+resolver cache (user cache directory, TTL'd). Point the document at a
+seeded cache to build without network:
+
+```adoc
+:asciichem-cache-dir: ./.asciichem-cache
+```
+
+Seed it with `asciichem resolve --name aspirin`. Resolution failures
+warn and emit no bibitem; they never break the build.
+
+**Sources and licensing.** PubChem resolves by default. CAS Common
+Chemistry (CC BY-NC 4.0) is opt-in:
+
+```ruby
+AsciiChem::Resolver.register(:common_chemistry,
+                             AsciiChem::Resolver::CommonChemistry)
+```
+
+A worked example document ships in `docs/example.adoc`.
+
+## Compatibility
+
+Runtime dependencies are `asciichem` (>= 0.29.2), `asciidoctor`, and
+`nokogiri` — the extension operates at the Asciidoctor AST level and
+needs no Metanorma gem to run.
+
+The full metanorma-standoc compile is exercised by the suite:
+`spec/metanorma/plugin/asciichem/standoc_spec.rb` compiles a document
+through metanorma-standoc (dev dependency) and asserts the semantic
+XML — `[chem]` → `<formula><stem type="MathML">`, bibitems verbatim
+inside `<references normative="false">` via the
+`formats="metanorma"` passthrough, InChIKey anchors. That became
+possible with asciichem 0.29.2, which widened its relaton-bib
+constraint to `< 3` so asciichem and current metanorma gems
+co-resolve in one bundle. Citation anchors read the emitted wire XML,
+so both relaton-bib major lines (1.x and 2.x keyword nestings) work.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec        # 16 examples, network-free
+bundle exec rubocop
+```
+
+Spec fixtures are real PubChem / CAS Common Chemistry payloads; the
+fetchers are Structs shaped like the asciidoctor HTTP surface — no
+network, no test doubles.
+
+## License
+
+BSD-2-Clause.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/example.adoc

@@ -0,0 +1,42 @@
+= Aspirin monograph (worked example)
+
+This document exercises metanorma-asciichem end to end: chemistry
+rendered from `[chem]` blocks, an inline formula, and a
+`@cite`-annotated molecule whose PubChem record becomes a
+dataset-type bibitem — anchored by InChIKey, so the `<<BSYNRYMUTXBXSQ-UHFFFAOYSA-N>>`
+cross-reference in the body lands on the emitted entry.
+
+Seed the resolver cache first for an offline, reproducible build:
+
+  asciichem resolve --name aspirin
+
+then set `:asciichem-cache-dir:` to your cache directory (or omit the
+attribute to resolve live).
+
+= Aspirin monograph
+Author
+:asciichem-cache-dir: ~/.cache/asciichem
+
+== Synthesis
+
+Aspirin is synthesised from salicylic acid. The overall hydrolysis
+equilibrium:
+
+[chem]
+----
+2H_2 + O_2 -> 2H_2O
+----
+
+Water, inline: chem:H_2O[], appears on both sides of the mechanism.
+
+== Structure and identity
+
+[chem]
+----
+CC(=O)OC1=CC=CC=C1C(=O)O @cas("50-78-2") @cite("pubchem")
+----
+
+The substance record is <<BSYNRYMUTXBXSQ-UHFFFAOYSA-N>>. Citing a
+second source for the same substance (after registering the opt-in
+adapter) yields a second, distinct entry — one bibitem per
+(substance, source).

data/lib/metanorma/plugin/asciichem/citations.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Metanorma
+  module Plugin
+    module Asciichem
+      # Bibliography emission (TODO.impl 49; TODO.v2 08 section 3):
+      # `@cite`-annotated molecules resolve to dataset-type Relaton
+      # bibitems - one per (source, substance), deduplicated, anchored by
+      # InChIKey - collected into a [bibliography] section appended to
+      # the document. Resolution goes through AsciiChem::Citation (the
+      # same code path as the CLI), so the document pipeline and the
+      # `asciichem cite` command can never drift.
+      module Citations
+        include Asciidoctor::Logging
+
+        BIBLIOGRAPHY_TITLE = 'Bibliography'
+        INCHIKEY_PREFIX = 'inchikey='
+        ANCHOR_SANITIZE = /[^A-Za-z0-9-]/
+
+        module_function
+
+        # molecules: parsed AsciiChem model nodes (Model::Molecule) as
+        # harvested from [chem] blocks. cache:/fetch: pass through to
+        # the resolver (same knobs as `asciichem resolve --refresh` and
+        # the asciichem CLI specs). Appends nothing when none of them
+        # carries @cite or none resolves (warns instead - builds stay
+        # green and reproducible via the resolver cache).
+        def append_bibliography(document, molecules, cache: nil, fetch: nil)
+          entries = resolve(molecules, cache: cache, fetch: fetch)
+          return if entries.empty?
+
+          document << bibliography_section(document, entries)
+        end
+
+        def resolve(molecules, cache:, fetch:)
+          entries = {}
+          molecules.each do |molecule|
+            # First-wins: a later identical (source, substance) keeps the
+            # first-mention entry and order.
+            entries.merge!(entries_for(molecule, cache: cache, fetch: fetch)) do |_key, first, _last|
+              first
+            end
+          end
+          entries.values
+        end
+
+        def entries_for(molecule, cache:, fetch:)
+          AsciiChem::Citation.for_molecule(molecule, cache: cache, fetch: fetch)
+                             .map { |source, bibitem| entry(source, bibitem) }
+                             .reduce({}, :merge)
+        rescue AsciiChem::Error => e
+          logger.warn(message_with_context(
+                        "cannot build substance citation: #{e.message} " \
+                        '(no bibitem emitted)',
+                        source_location: nil
+                      ))
+          {}
+        end
+
+        # [source, bibitem] -> { [source, anchor] => [anchor, xml] }:
+        # the compound key dedupes same (source, substance) while the
+        # insertion-ordered hash preserves first-mention order.
+        def entry(source, bibitem)
+          xml = bibitem.to_xml
+          anchor = anchor_for(xml) || fallback_anchor(source, xml)
+          { [source, anchor] => [anchor, with_anchor(xml, anchor)] }
+        end
+
+        # The InChIKey is the cross-source join key: every bibitem for
+        # the same substance carries the same keyword, so two spellings
+        # of one substance (CAS RN vs name) collapse onto one anchor.
+        # Anchors read the emitted wire XML, not vendor object APIs:
+        # relaton-bib 1 writes <keyword>inchikey=...</keyword> and
+        # relaton-bib 2 nests it (<keyword><vocab>...</vocab></keyword>)
+        # — one pattern serves both.
+        def anchor_for(xml)
+          xml[/#{INCHIKEY_PREFIX}([A-Za-z0-9-]+)/, 1]
+        end
+
+        def fallback_anchor(source, xml)
+          docid = xml[%r{<docidentifier[^>]*>([^<]+)</docidentifier>}, 1]
+          slug = docid ? docid.gsub(ANCHOR_SANITIZE, '') : 'substance'
+          "#{source}-#{slug}"
+        end
+
+        # Relaton emits <bibitem id="..."> with an id derived from the
+        # docidentifier; the anchor (InChIKey) replaces it so document
+        # cross-references <<INCHIKEY>> land on the entry.
+        def with_anchor(xml, anchor)
+          root = Nokogiri::XML(xml).root
+          root['id'] = anchor
+          root.to_xml
+        end
+
+        def bibliography_section(document, entries)
+          section = Asciidoctor::Section.new(document, 1, false)
+          section.style = 'bibliography'
+          section.title = BIBLIOGRAPHY_TITLE
+          entries.each { |anchor, xml| section << pass_block(section, anchor, xml) }
+          section
+        end
+
+        # A [pass] block's content reaches the semantic XML unwrapped
+        # (passthrough formats="metanorma"), placing the bibitem
+        # verbatim inside <references>.
+        def pass_block(section, _anchor, xml)
+          Asciidoctor::Block.new(section, :pass, content_model: :raw,
+                                                 source: xml,
+                                                 attributes: { 'style' => 'pass' })
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/asciichem/extension.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Asciichem
+      # Asciidoctor extension surface (TODO.impl 49): one treeprocessor
+      # for block-level chemistry + citation collection, one inline macro
+      # for inline chemistry.
+      #
+      # Block form (citations are collected here - inline macros resolve
+      # at substitution time, after treeprocessors have run):
+      #
+      #   [chem]
+      #   ----
+      #   2H_2 + O_2 -> 2H_2O
+      #   ----
+      #
+      # Inline form (render-only):
+      #
+      #   chem:H_2O[]  or  chem:[2H_2 + O_2 -> 2H_2O]
+      #
+      module Extension
+        # Rewrites every style-"chem" block into a stem block carrying
+        # the formula's MathML, then appends the substance bibliography
+        # built from the harvested molecules.
+        #
+        # Document attributes:
+        #   asciichem-cache-dir - resolve citations from this resolver
+        #                         cache directory (reproducible, offline
+        #                         builds; seed it with `asciichem
+        #                         resolve`).
+        class ChemTreeprocessor < Asciidoctor::Extensions::Treeprocessor
+          include Asciidoctor::Logging
+
+          def process(document)
+            molecules = []
+            document.find_by(style: 'chem').each do |node|
+              next unless node.is_a?(Asciidoctor::Block)
+
+              molecules.concat(rewrite(node))
+            end
+            Citations.append_bibliography(document, molecules,
+                                          cache: cache_for(document))
+            nil
+          end
+
+          private
+
+          def cache_for(document)
+            dir = document.attr('asciichem-cache-dir')
+            dir && AsciiChem::Resolver::Cache.new(dir: dir)
+          end
+
+          # Parses the block source once; replaces the node with a stem
+          # block of its MathML. Returns the formula's molecule nodes
+          # (only molecules can carry @cite annotations), or [] when the
+          # block does not parse.
+          def rewrite(node)
+            formula = parse_or_log(node, '[chem] block', '(block kept as sourcecode)')
+            return [] unless formula
+
+            replace_with_stem(node, formula)
+            formula.nodes.grep(AsciiChem::Model::Molecule)
+          end
+
+          # Parses, or logs the failure and returns nil (the caller
+          # keeps the offending block visible instead of crashing the
+          # build).
+          def parse_or_log(node, where, remedy)
+            Renderer.parse(node.lines.join("\n"))
+          rescue AsciiChem::ParseError => e
+            logger.error(message_with_context(
+                           "invalid AsciiChem in #{where}: #{e.message} #{remedy}",
+                           source_location: node.source_location
+                         ))
+            nil
+          end
+
+          def replace_with_stem(node, formula)
+            stem = Asciidoctor::Block.new(
+              node.parent, :stem,
+              content_model: :verbatim, source: Renderer.mathml(formula),
+              # Standoc reads node.lines (raw); :default subs keep plain
+              # Asciidoctor/HTML5 previews working (escaped text).
+              subs: :default
+            )
+            # Style "asciimath" matches core stem blocks; standoc still
+            # types the stem MathML from the <math> content itself.
+            stem.style = 'asciimath'
+            stem.id = node.id if node.id
+            stem.title = node.title if node.title
+            siblings = node.parent.blocks
+            siblings[siblings.index(node)] = stem
+            stem
+          end
+        end
+
+        # Inline chemistry: chem:H_2O[] (target form, no spaces) or
+        # chem:[source] (attribute form, any single-line source).
+        # Render-only - inline macros resolve after treeprocessors run,
+        # so they cannot contribute bibliography entries.
+        class ChemInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+          include Asciidoctor::Logging
+
+          use_dsl
+          name_positional_attributes 'text'
+
+          def process(parent, target, attrs)
+            source = target.empty? ? attrs['text'] : target
+            return empty_inline(parent) if source.nil? || source.empty?
+
+            formula = Renderer.parse(source)
+            # Context :quoted with type :asciimath is the shape core
+            # stem:[] macros produce; converters dispatch inline_quoted
+            # and type the stem MathML from the <math> content. (A
+            # :asciimath-context node dispatches inline_asciimath,
+            # which metanorma converters do not define.)
+            create_inline(parent, :quoted, Renderer.mathml(formula), type: :asciimath)
+          rescue AsciiChem::ParseError => e
+            logger.error(message_with_context(
+                           "invalid AsciiChem in chem: macro: #{e.message} " \
+                           '(rendered verbatim)',
+                           source_location: parent.source_location
+                         ))
+            create_inline(parent, :quoted, source, type: :monospaced)
+          end
+
+          private
+
+          def empty_inline(parent)
+            logger.error(message_with_context(
+                           'empty chem: macro - provide source ' \
+                           '(chem:H_2O[] or chem:[...])',
+                           source_location: parent.source_location
+                         ))
+            create_inline(parent, :quoted, '')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/asciichem/renderer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Asciichem
+      # The parse/render seam between AsciiDoc and AsciiChem. Parsing is
+      # separated from rendering so the treeprocessor can parse once and
+      # both render MathML and harvest citation molecules from the same
+      # semantic model.
+      module Renderer
+        module_function
+
+        # Parses AsciiChem source into the semantic model. Raises
+        # AsciiChem::ParseError on invalid input.
+        def parse(source)
+          AsciiChem.parse(source)
+        end
+
+        # Renders the parsed model to a MathML <math> document. Standoc's
+        # stem handling detects the <math> root and types the stem
+        # accordingly (type="MathML"), so no converter-side support is
+        # needed. The formatter's XML declaration is stripped: embedded
+        # MathML is a fragment inside the document, not a document.
+        def mathml(formula)
+          formula.to_mathml.sub(/\A<\?xml[^>]*>\s*/, '')
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/asciichem/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Asciichem
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/metanorma/plugin/asciichem.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'asciidoctor' unless defined?(Asciidoctor)
+require 'asciichem'
+
+module Metanorma
+  module Plugin
+    # AsciiChem integration for Metanorma (TODO.impl 49; TODO.v2 08
+    # section 3): chemistry in AsciiDoc documents parses to MathML for
+    # rendering, and `@cite`-annotated molecules resolve to dataset-type
+    # Relaton bibitems collected into the document bibliography - one
+    # bibitem per (source, substance), anchored by InChIKey.
+    #
+    # Following the plugin contract (lutaml, glossarist), this gem
+    # exposes the extension classes and does NOT register them with
+    # Asciidoctor itself; the host converter registers what it needs:
+    #
+    #   Asciidoctor::Extensions.register do
+    #     treeprocessor Metanorma::Plugin::Asciichem::Extension::ChemTreeprocessor
+    #     inline_macro Metanorma::Plugin::Asciichem::Extension::ChemInlineMacro, :chem
+    #   end
+    module Asciichem
+      autoload :Citations, 'metanorma/plugin/asciichem/citations'
+      autoload :Extension, 'metanorma/plugin/asciichem/extension'
+      autoload :Renderer, 'metanorma/plugin/asciichem/renderer'
+    end
+  end
+end

data/lib/metanorma-plugin-asciichem.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'metanorma/plugin/asciichem/version'
+require_relative 'metanorma/plugin/asciichem'

data/metanorma-plugin-asciichem.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'lib/metanorma/plugin/asciichem/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'metanorma-plugin-asciichem'
+  spec.version       = Metanorma::Plugin::Asciichem::VERSION
+  spec.authors       = ['Ribose Inc.']
+  spec.email         = ['open.source@ribose.com']
+
+  spec.summary       = 'AsciiChem chemistry blocks and substance citations for Metanorma documents.'
+  spec.description   = 'Adds [chem] blocks and chem:[] inline macros to Metanorma ' \
+                       'AsciiDoc: chemistry written in AsciiChem parses to MathML ' \
+                       'for rendering, and @cite-annotated molecules resolve to ' \
+                       'dataset-type Relaton bibitems - one per (source, substance), ' \
+                       'anchored by InChIKey - automatically collected into the ' \
+                       "document's bibliography."
+
+  spec.homepage      = 'https://www.asciichem.org'
+  spec.license       = 'BSD-2-Clause'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.3.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/metanorma/metanorma-plugin-asciichem'
+  spec.metadata['changelog_uri'] = 'https://github.com/metanorma/metanorma-plugin-asciichem/blob/main/CHANGELOG.md'
+  spec.metadata['docs_uri'] = 'https://www.asciichem.org'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'asciichem', '>= 0.29.2'
+  spec.add_dependency 'asciidoctor', '~> 2.0'
+  spec.add_dependency 'nokogiri', '~> 1.16'
+
+  # metanorma-standoc lives in the Gemfile dev group: it is the
+  # integration-test backend (spec/metanorma/plugin/asciichem/
+  # standoc_spec.rb), not a runtime requirement — following the
+  # plugin contract, metanorma-standoc requires and registers this
+  # gem, like it does for metanorma-plugin-lutaml.
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: metanorma-plugin-asciichem
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciichem
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.29.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.29.2
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: 'Adds [chem] blocks and chem:[] inline macros to Metanorma AsciiDoc:
+  chemistry written in AsciiChem parses to MathML for rendering, and @cite-annotated
+  molecules resolve to dataset-type Relaton bibitems - one per (source, substance),
+  anchored by InChIKey - automatically collected into the document''s bibliography.'
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- docs/example.adoc
+- lib/metanorma-plugin-asciichem.rb
+- lib/metanorma/plugin/asciichem.rb
+- lib/metanorma/plugin/asciichem/citations.rb
+- lib/metanorma/plugin/asciichem/extension.rb
+- lib/metanorma/plugin/asciichem/renderer.rb
+- lib/metanorma/plugin/asciichem/version.rb
+- metanorma-plugin-asciichem.gemspec
+homepage: https://www.asciichem.org
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://www.asciichem.org
+  source_code_uri: https://github.com/metanorma/metanorma-plugin-asciichem
+  changelog_uri: https://github.com/metanorma/metanorma-plugin-asciichem/blob/main/CHANGELOG.md
+  docs_uri: https://www.asciichem.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: AsciiChem chemistry blocks and substance citations for Metanorma documents.
+test_files: []