asciichem 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a97d83231f84e4dde6c03c18f88ae7c34a30779e2550ca3f859e91bc58365f84
-  data.tar.gz: dbb27614ede6ba6987f09942465624b8d84dda4041444f63326982d84c365bdd
+  metadata.gz: d733aab290b1e54dfd0139d75a92888dfb8fc2af088544a07cc4395e523e583f
+  data.tar.gz: 5dfe21e949307366a6afbcc94bf2c52f9e9cfedb4a1f328996fbde3a20b5ec99
 SHA512:
-  metadata.gz: 47d0e9bf10643d6a7fb24779d1baaaf1382e4c11b1b43375e1543b7cacb5169ea94784db8c1ab70a2f117590966bc96ca4809c994fd83f6295ca63fa56bf3c01
-  data.tar.gz: 84386eb43091bbcde85bf7ed8bc428544865bd87f985e2b986d2578c5cb2e25a11d0ef39b880bcd781a5da6b061e4a6501d18a02bd2cf3016da369dd72afd365
+  metadata.gz: cdeb663f26df5189cd73df0d7c5f6a9ad3918d981d924ec08f1a781728415af474840de566a8d8f1075cb0cdc0d7086f41f92b80250efee6f71ebd11cdc62680
+  data.tar.gz: 371e88363eb2e143b2b8a1b3f1a3cbc339d3eb81d5bcd521fdc00d02fd90e6068c769864185198c8e35e5ae6e2fc95b0088885d760844f527118a50469eaa9fb

data/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.24.0] - 2026-09-13
+
+### Added
+- `AsciiChem::Citation` (TODO.impl 44): one dataset-type Relaton
+  bibitem per (substance, source) — the citation track's core
+  contract. Source-specific fields live in per-source profiles
+  (PubChem, Common Chemistry); every identifier rides along as a
+  keyword so citations are machine-checkable. Runtime dependency:
+  relaton-bib (classic model).
+- `Resolver::CommonChemistry` (TODO.impl 40, maintainer sign-off
+  2026-09-13): CAS RN lookups against CAS Common Chemistry. CC BY-NC
+  4.0 posture is enforced in code — the adapter never self-registers;
+  users opt in explicitly, and every result carries the required
+  attribution.
+
 ## [0.23.0] - 2026-09-12
 
 ### Added
@@ -411,7 +426,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.23.0...HEAD
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...v0.21.0

data/asciichem.gemspec

@@ -38,6 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "lutaml-model", ">= 0.8", "< 2"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
+  spec.add_dependency "relaton-bib", ">= 0.1", "< 2"
   spec.add_dependency "plurimath", "~> 0.8"
   spec.add_dependency "thor", "~> 1.3"
 

data/lib/asciichem/citation.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "relaton_bib"
+
+module AsciiChem
+  # Citation track (TODO.v2 08; TODO.impl 44): a bibitem is a function
+  # of (substance, source) — one dataset-type Relaton bibitem per
+  # source the user chooses to cite, because two databases agreeing on
+  # a substance are still two different documents.
+  #
+  # Source-specific fields (link shape, publisher string, docidentifier
+  # scheme) live in PROFILES; adding a source is one entry (OCP).
+  module Citation
+    # Source-specific citation profile. Default fields fall back to
+    # the substance's provenance.
+    Profile = Struct.new(:publisher, :link_for, :identifier_for, keyword_init: true)
+
+    PROFILES = {
+      "pubchem" => Profile.new(
+        publisher: "PubChem, U.S. National Library of Medicine",
+        link_for: ->(substance) do
+          cid = substance.identifier_value("pubchem-cid")
+          "https://pubchem.ncbi.nlm.nih.gov/compound/#{cid}" if cid
+        end,
+        identifier_for: ->(substance) do
+          cid = substance.identifier_value("pubchem-cid")
+          "PubChem CID #{cid}" if cid
+        end
+      ),
+      "common_chemistry" => Profile.new(
+        publisher: "CAS Common Chemistry",
+        link_for: ->(substance) do
+          cas = substance.identifier_value("cas")
+          "https://commonchemistry.cas.org/detail?cas_rn=#{cas}" if cas
+        end,
+        identifier_for: ->(substance) do
+          cas = substance.identifier_value("cas")
+          "CAS RN #{cas}" if cas
+        end
+      )
+    }.freeze
+
+    DEFAULT_PROFILE = Profile.new(
+      publisher: nil,
+      link_for: ->(_substance) { nil },
+      identifier_for: ->(substance) do
+        key = substance.identifiers.first
+        "#{key.convention}: #{key.value}" if key
+      end
+    ).freeze
+    private_constant :DEFAULT_PROFILE
+
+    class << self
+      # Builds a Relaton dataset-type bibitem for the substance as
+      # cited from its recorded source. Raises when the substance
+      # carries no provenance (hand-built, not resolved).
+      def bibitem(substance)
+        provenance = substance.provenance
+        unless provenance&.source
+          raise Error, "substance has no provenance - resolve it first (AsciiChem::Resolver)"
+        end
+
+        profile = PROFILES.fetch(provenance.source, DEFAULT_PROFILE)
+        RelatonBib::BibliographicItem.new(
+          type: "dataset",
+          title: [{ type: "main",
+                    content: "#{title_base(substance)} - #{profile.publisher || provenance.source} substance record" }],
+          docid: [RelatonBib::DocumentIdentifier.new(
+                    id: profile.identifier_for.call(substance) || "#{provenance.source} substance",
+                    type: provenance.source)],
+          contributor: [{ entity: RelatonBib::Organization.new(name: profile.publisher || provenance.source),
+                          role: [{ type: "publisher" }] }],
+          date: [{ type: "accessed", on: accessed_on(provenance) }],
+          link: [{ type: "src", content: profile.link_for.call(substance) }].compact,
+          keyword: substance.identifiers.map { |i| "#{i.convention}=#{i.value}" }
+        )
+      end
+
+      # Convenience: bibitem XML (what a document pipeline embeds).
+      def to_xml(substance)
+        bibitem(substance).to_xml
+      end
+
+      private
+
+      def title_base(substance)
+        substance.preferred_name || substance.identifier_value("cas") ||
+          substance.identifier_value("inchikey") || "Substance"
+      end
+
+      def accessed_on(provenance)
+        return provenance.retrieved_at[0, 10] if provenance.retrieved_at
+
+        Time.now.utc.strftime("%Y-%m-%d")
+      end
+    end
+  end
+end

data/lib/asciichem/resolver/adapter.rb

@@ -17,11 +17,13 @@ module AsciiChem
         # Declares the source name and registers the adapter (called
         # from the class body — `inherited` fires before the body
         # runs, so it cannot see the subclass configuration).
-        def source_name(name = nil)
+        # `register: false` for opt-in sources (NC-licensed): the
+        # adapter exists but users must register it explicitly.
+        def source_name(name = nil, register: true)
           return @source_name if name.nil?
 
           @source_name = name.to_s
-          AsciiChem::Resolver.register(@source_name, self)
+          AsciiChem::Resolver.register(@source_name, self) if register
         end
 
         def supports(*conventions)

data/lib/asciichem/resolver/common_chemistry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+
+module AsciiChem
+  module Resolver
+    # CAS Common Chemistry source adapter (TODO.impl 40; TODO.v2 07).
+    #
+    # License posture (maintainer sign-off 2026-09-13): Common
+    # Chemistry data is CC BY-NC 4.0 — this adapter is OPT-IN and never
+    # self-registers; users register it explicitly:
+    #
+    #   AsciiChem::Resolver.register(:common_chemistry,
+    #                                 AsciiChem::Resolver::CommonChemistry)
+    #
+    # Every result carries the required attribution.
+    class CommonChemistry < Adapter
+      source_name :common_chemistry, register: false
+      supports "cas"
+
+      BASE = "https://commonchemistry.cas.org/api/detail"
+
+      def fetch_record(value:, convention:, fetch:)
+        body = fetch.get("#{BASE}?cas_rn=#{CGI.escape(value.to_s)}")
+        return nil unless body
+
+        data = JSON.parse(body)
+        return nil if data.empty?
+
+        substance_from(data)
+      rescue JSON::ParserError => e
+        raise Error, "common_chemistry returned malformed JSON: #{e.message}"
+      end
+
+      def attribution
+        "CAS Common Chemistry (CC BY-NC 4.0)"
+      end
+
+      private
+
+      def substance_from(data)
+        provenance = default_provenance
+        identifiers = [Identifier.new(value: data["rn"], convention: "cas",
+                                      provenance: provenance)]
+        add_identifier(identifiers, data, "inchikey", "inchikey", provenance)
+        add_identifier(identifiers, data, "smiles", "canonical-smiles", provenance)
+        add_identifier(identifiers, data, "inchi", "inchi", provenance)
+        add_identifier(identifiers, data, "iupacName", "iupac-name", provenance)
+
+        Substance.new(
+          preferred_name: data["name"],
+          formula: data["formula"],
+          identifiers: identifiers,
+          properties: [
+            Property.new(name: "molecular-formula", value: data["formula"], provenance: provenance),
+            Property.new(name: "molecular-weight", value: data["molecularMass"]&.to_s,
+                         units: "g/mol", provenance: provenance)
+          ].compact,
+          # Best effort within the supported SMILES subset; the SMILES
+          # stays as an identifier when stereo keeps it out.
+          structure: parse_structure(data["smiles"])
+        )
+      end
+
+      def add_identifier(list, data, key, convention, provenance)
+        return unless data[key]
+
+        list << Identifier.new(value: data[key], convention: convention,
+                               provenance: provenance)
+      end
+
+      def parse_structure(smiles)
+        return nil unless smiles
+
+        AsciiChem.parse_smiles(smiles).nodes.first
+      rescue AsciiChem::ParseError
+        nil
+      end
+    end
+  end
+end

data/lib/asciichem/resolver.rb

@@ -17,6 +17,7 @@ module AsciiChem
     autoload :Adapter, "asciichem/resolver/adapter"
     autoload :Cache, "asciichem/resolver/cache"
     autoload :PubChem, "asciichem/resolver/pubchem"
+    autoload :CommonChemistry, "asciichem/resolver/common_chemistry"
     autoload :Substance, "asciichem/resolver/substance"
 
     # Raised when sources disagree on substance identity (cross-check
@@ -69,9 +70,10 @@ module AsciiChem
       end
     end
 
-    # Open, permissive sources register eagerly; opt-in NC sources do
-    # not self-register (registered manually after sign-off).
-    adapters # ensure the registry exists before adapter files load
+    # Open, permissive sources register eagerly. CommonChemistry is
+    # CC BY-NC 4.0: it loads (autoload) but never self-registers —
+    # users opt in explicitly via Resolver.register.
+    adapters
     constants.each { |c| const_get(c) unless c == :Conflict }
   end
 end

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.23.0"
+  VERSION = "0.24.0"
 end

data/lib/asciichem.rb

@@ -10,6 +10,7 @@ require "plurimath"
 #   AsciiChem::Cli.start    # CLI dispatch
 module AsciiChem
   autoload :Cli, "asciichem/cli"
+  autoload :Citation, "asciichem/citation"
   autoload :Cml, "asciichem/cml"
   autoload :Error, "asciichem/errors"
   autoload :ParseError, "asciichem/errors"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -85,6 +85,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: relaton-bib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: plurimath
   requirement: !ruby/object:Gem::Requirement
@@ -156,6 +176,7 @@ files:
 - benchmarks/benchmark.rb
 - exe/asciichem
 - lib/asciichem.rb
+- lib/asciichem/citation.rb
 - lib/asciichem/cli.rb
 - lib/asciichem/cml.rb
 - lib/asciichem/cml/conditions_extensions.rb
@@ -231,6 +252,7 @@ files:
 - lib/asciichem/resolver.rb
 - lib/asciichem/resolver/adapter.rb
 - lib/asciichem/resolver/cache.rb
+- lib/asciichem/resolver/common_chemistry.rb
 - lib/asciichem/resolver/pubchem.rb
 - lib/asciichem/resolver/substance.rb
 - lib/asciichem/ring_bonds.rb