chemomer 0.1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 142c9b75a559a70f3da42867d5fc666612991c6163592487c3dc62ff60c19c95
+  data.tar.gz: 7e3ee8a8f611b0090ef9bd98c893778dfae022365edeeb7d89c95f55161b9d51
+SHA512:
+  metadata.gz: ac5e6ecbc4797c78a90ed6b7331181ce3d274f7f8b47afa70237faa421561f9055cee5fe3b17c8b814129c3a1c4c080758ddfa136797491a6b8e49dab9e6125e
+  data.tar.gz: d87604de945779f7260cbe29d8cfc950c4d74828e40d353c5d02669da1db8060dd8e212a272738b680bf4654f4f68fd2822be5352c09fb28c56a23098d9b926a

data/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  rspec:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: ["3.3", "3.4"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      # The gem drives the engine through its C ABI — no engine code is
+      # vendored, so CI builds the cdylib from the engine's main (the
+      # shared contract) and points the suite at it. Specs that need
+      # the dylib gate on CHEMOMER_LIB; the rest run everywhere.
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build the chemomer cdylib
+        run: |
+          git clone --depth 1 https://github.com/chemomer/chemomer engine
+          cargo build --release --manifest-path engine/Cargo.toml
+      - name: Point CHEMOMER_LIB at the built dylib
+        run: |
+          lib=$(ls engine/target/release/libchemomer.dylib engine/target/release/libchemomer.so 2>/dev/null | head -1)
+          echo "CHEMOMER_LIB=$PWD/$lib" >> "$GITHUB_ENV"
+      - run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (must match lib/chemomer/version.rb)"
+        required: true
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC): the publisher registered on RubyGems.org
+    # is repository chemomer/chemomer-ruby + 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/chemomer/version"; print Chemomer::VERSION')
+          if [ "$actual" != "${{ inputs.version }}" ]; then
+            echo "Version mismatch: input=${{ inputs.version }}, lib/chemomer/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 prints
+      # "Tag vX has already been created" and skips its git stage
+      # entirely. Pre-create the tag so the gem push is the only
+      # remote operation; tags on the remote remain the maintainer's.
+      - 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 chemomer ${{ inputs.version }} to RubyGems"
+          echo "https://rubygems.org/gems/chemomer"

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "rspec", "~> 3.13"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AsciiChem contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# chemomer
+
+The **Ruby binding for the [chemomer](https://github.com/chemomer/chemomer)
+engine** — molfile in, InChI identifier / InChIKey out, driven through
+the engine's C ABI with [FFI](https://github.com/ffi/ffi).
+
+```ruby
+require "chemomer"
+
+inchi, inchikey = Chemomer.from_molfile(molfile_text)
+aux = Chemomer.aux_from_molfile(molfile_text)
+Chemomer.ffi_version # => 1
+```
+
+A thin wrapper by design: the engine (the byte-exact InChI port, gated
+by the shared oracle corpus
+[inchi-tests](https://github.com/chemomer/inchi-tests)) lives in the
+chemomer repo; this gem owns only the FFI signatures and the packaging
+— no engine code is vendored. The cdylib is a runtime artifact: build
+it once and point the gem at it.
+
+## The library
+
+The gem resolves the cdylib in this order:
+
+1. `CHEMOMER_LIB` — the path to the built cdylib.
+2. The platform default sonames (`libchemomer.dylib` on macOS,
+   `libchemomer.so` on Linux), resolved through the loader's search
+   path — install the dylib on `LD_LIBRARY_PATH` /
+   `DYLD_LIBRARY_PATH` or into a standard lib dir for zero-config use.
+
+Build the cdylib from an engine checkout:
+
+```bash
+cargo build --release   # in the chemomer repo
+export CHEMOMER_LIB=$PWD/target/release/libchemomer.dylib
+```
+
+Errors surface as `Chemomer::Error` — engine failures carry the C
+ABI's thread-local `chemomer_last_error` message, resolution failures
+carry the remedy.
+
+## Versioning
+
+Runtime packages track the engine: `{engine semver}.{runtime version}`
+(the same scheme as chemomer-py). This gem is `0.1.0.1` — engine
+`0.1.0`, runtime `1`. An engine bump resets the counter (`0.2.0.1`);
+a runtime-only fix increments it (`0.1.0.2`).
+
+## AuxInfo
+
+`aux_from_molfile` needs the `chemomer_aux_from_molfile` C export,
+which the engine's 0.1.0 ABI does not ship yet (the Python binding
+reaches AuxInfo through the Rust API directly). The gem attaches the
+symbol on first use: once an engine cdylib exports it, the method
+works with no gem change; against a 0.1.0 cdylib it raises
+`Chemomer::Error` saying exactly that.
+
+## Test
+
+```bash
+bundle install
+CHEMOMER_LIB=$PWD/../chemomer/target/release/libchemomer.dylib bundle exec rspec
+```
+
+Specs that need the cdylib gate on `CHEMOMER_LIB` and skip cleanly
+without it; the rest run everywhere. CI builds the engine's main
+cdylib and runs the full suite on ubuntu + macos.
+
+## Publishing
+
+`release.yml` is dispatch-only: a version input (verified against
+`lib/chemomer/version.rb`), the pre-created-tag trick, then
+`rubygems/release-gem@v1` — trusted publishing (OIDC), no stored
+credentials, no environment.
+
+The first publish of the gem name needs the RubyGems trusted publisher
+registered first — gem `chemomer`, owner `chemomer`, repository
+`chemomer/chemomer-ruby`, workflow `release.yml`, no environment — or
+a local `gem push` for the very first version.
+
+## License
+
+MIT, same as the engine.

data/chemomer.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/chemomer/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "chemomer"
+  spec.version       = Chemomer::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "Ruby bindings for the chemomer InChI engine — molfile in, identifier / InChIKey out."
+  spec.description   = "Chemomer drives the native chemomer engine — the Rust InChI port gated by the " \
+                       "shared oracle corpus — through its C ABI via FFI. from_molfile returns the " \
+                       "InChI identifier and the InChIKey; aux_from_molfile returns the AuxInfo line. " \
+                       "No engine code is vendored: the cdylib is a runtime artifact."
+  spec.homepage      = "https://github.com/chemomer/chemomer-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.3.0")
+
+  spec.metadata["source_code_uri"] = "https://github.com/chemomer/chemomer-ruby"
+  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 "ffi"
+end

data/lib/chemomer/bindings.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Chemomer
+  # The FFI surface of the chemomer cdylib: one anonymous module per
+  # library (attach_function binds the symbols once), cached per
+  # candidate list — the shape of asciichem-ruby's NativeEngine.
+  #
+  # The documented C ABI of chemomer 0.1.0:
+  #
+  #   chemomer_from_molfile  molfile → identifier string (null on error)
+  #   chemomer_inchikey      molfile → InChIKey string (null on error)
+  #   chemomer_string_free   releases a string returned by the ABI
+  #   chemomer_last_error    → the calling thread's last error, or null
+  #   chemomer_ffi_version   → the ABI version (1)
+  module Bindings
+    module_function
+
+    # The main surface: attaches eagerly (every symbol is part of the
+    # documented ABI) and caches per candidate list.
+    def for(*names)
+      bindings[names] ||= attach(names)
+    end
+
+    # AuxInfo: the 0.1.0 ABI does not export chemomer_aux_from_molfile
+    # (the Python binding reaches AuxInfo through the Rust API
+    # directly). The symbol is attached on first use, so the gem
+    # lights up without a change the moment an engine cdylib ships the
+    # export; against a dylib without it, a clear Chemomer::Error
+    # explains the gap.
+    def aux(*names)
+      aux_bindings[names] ||= attach_aux(names)
+    end
+
+    def bindings
+      @bindings ||= {}
+    end
+
+    def aux_bindings
+      @aux_bindings ||= {}
+    end
+
+    def attach(names)
+      guard_readable(names)
+      Module.new do
+        extend FFI::Library
+
+        ffi_lib(*names)
+        attach_function :chemomer_from_molfile, %i[string], :pointer
+        attach_function :chemomer_inchikey, %i[string], :pointer
+        attach_function :chemomer_string_free, %i[pointer], :void
+        attach_function :chemomer_last_error, [], :pointer
+        attach_function :chemomer_ffi_version, [], :uint32
+
+        # The message of the last error on the calling thread, or nil.
+        def self.last_error
+          pointer = chemomer_last_error
+          pointer.null? ? nil : pointer.read_string
+        end
+      end
+    rescue LoadError => e
+      raise Error, load_failure(e)
+    end
+
+    def attach_aux(names)
+      guard_readable(names)
+      Module.new do
+        extend FFI::Library
+
+        ffi_lib(*names)
+        attach_function :chemomer_aux_from_molfile, %i[string], :pointer
+        # The call path needs the companions too — they exist in every
+        # engine ABI version, so attaching them here is version-safe;
+        # only the aux symbol above is the version-sensitive one.
+        attach_function :chemomer_string_free, %i[pointer], :void
+        attach_function :chemomer_last_error, [], :pointer
+
+        def self.last_error
+          pointer = chemomer_last_error
+          pointer.null? ? nil : pointer.read_string
+        end
+      end
+    rescue FFI::NotFoundError
+      raise Error,
+            "chemomer: the cdylib does not export chemomer_aux_from_molfile — " \
+            "AuxInfo needs an engine that ships the export " \
+            "(github.com/chemomer/chemomer, src/ffi.rs)"
+    rescue LoadError => e
+      raise Error, load_failure(e)
+    end
+
+    # An explicit CHEMOMER_LIB path is one candidate; a missing or
+    # unreadable file deserves the direct message rather than the
+    # loader's. The default soname list is searched by the loader
+    # instead — nothing to check here.
+    def guard_readable(names)
+      return unless names.one?
+
+      path = names.first
+      return if File.readable?(path)
+
+      raise Error,
+            "chemomer: #{path} is not readable — set CHEMOMER_LIB to the built " \
+            "cdylib (cargo build --release in the chemomer checkout)"
+    end
+
+    def load_failure(error)
+      "chemomer: could not load the cdylib (#{error.message}). Set CHEMOMER_LIB " \
+        "to the built cdylib (cargo build --release in the chemomer checkout) or " \
+        "install it on the loader path."
+    end
+  end
+end

data/lib/chemomer/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Chemomer
+  # The single error type of the gem: engine failures (raised from the
+  # C ABI's thread-local last_error) and library-resolution failures
+  # alike, so callers rescue one thing.
+  class Error < StandardError; end
+end

data/lib/chemomer/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Chemomer
+  # The {engine semver}.{runtime version} scheme (shared with
+  # chemomer-py): the chemomer engine release this gem wraps (0.1.0)
+  # plus the gem's own runtime counter (1). An engine bump resets the
+  # counter (0.2.0.1); a runtime-only fix increments it (0.1.0.2).
+  VERSION = "0.1.0.1"
+end

data/lib/chemomer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "rbconfig"
+
+# Chemomer drives the native chemomer engine — the Rust InChI port
+# gated by the shared oracle corpus (chemomer/chemomer) — through its
+# C ABI via FFI. A thin wrapper by design: no engine code is vendored,
+# the gem owns only the FFI signatures and the packaging. The cdylib
+# is a runtime artifact: build it once from an engine checkout and
+# point CHEMOMER_LIB at it, or install it on the loader path for the
+# default soname resolution.
+#
+#   Chemomer.from_molfile(molfile)      # => [inchi, inchikey]
+#   Chemomer.aux_from_molfile(molfile)  # => aux line
+#   Chemomer.ffi_version                # => 1
+module Chemomer
+  autoload :VERSION, "chemomer/version"
+  autoload :Bindings, "chemomer/bindings"
+  autoload :Error, "chemomer/error"
+
+  # Fallback sonames tried in order when CHEMOMER_LIB is unset; the
+  # OS loader resolves them from its search path (LD_LIBRARY_PATH /
+  # DYLD_LIBRARY_PATH, /usr/local/lib, ...).
+  DEFAULT_LIB_NAMES = {
+    darwin: %w[libchemomer.dylib chemomer.dylib],
+    linux: %w[libchemomer.so chemomer.so],
+    windows: %w[chemomer.dll libchemomer.dll]
+  }.freeze
+
+  module_function
+
+  # The library candidates to attach: CHEMOMER_LIB when set, else
+  # this platform's default sonames.
+  def lib
+    env = ENV.fetch("CHEMOMER_LIB", nil)
+    env ? [env] : DEFAULT_LIB_NAMES.fetch(platform)
+  end
+
+  # molfile → [InChI identifier, InChIKey].
+  #
+  #   Chemomer.from_molfile(water_molfile)
+  #   # => ["InChI=1S/H2O/h1H2", "XLYOFNOQVPJJNP-UHFFFAOYSA-N"]
+  def from_molfile(molfile)
+    bindings = Bindings.for(*lib)
+    inchi = call(bindings, molfile, :chemomer_from_molfile)
+    inchikey = call(bindings, molfile, :chemomer_inchikey)
+    [inchi, inchikey]
+  end
+
+  # molfile → the AuxInfo line (per-component canonical numbering,
+  # reversibility block). Needs the chemomer_aux_from_molfile export —
+  # attached on first use, so it lights up the moment an engine cdylib
+  # ships it.
+  def aux_from_molfile(molfile)
+    bindings = Bindings.aux(*lib)
+    call(bindings, molfile, :chemomer_aux_from_molfile)
+  end
+
+  # The C ABI version of the attached cdylib (1 today).
+  def ffi_version
+    Bindings.for(*lib).chemomer_ffi_version
+  end
+
+  # The C ABI contract: null return on error (the message sits on the
+  # calling thread's last_error slot), the returned string freed right
+  # after reading it.
+  def call(bindings, molfile, function)
+    pointer = bindings.public_send(function, molfile)
+    # A null return arrives as a non-nil FFI::Pointer whose address is
+    # 0 — the truthiness test would sail past it, so null? is the
+    # guard.
+    if pointer.nil? || pointer.null?
+      raise Error, "chemomer: #{bindings.last_error || 'call failed'}"
+    end
+    value = pointer.read_string
+    bindings.chemomer_string_free(pointer)
+    value
+  end
+  private_class_method :call
+
+  def platform
+    case RbConfig::CONFIG["host_os"]
+    when /darwin/ then :darwin
+    when /linux/ then :linux
+    when /mswin|mingw|cygwin/ then :windows
+    else
+      raise Error,
+            "chemomer: no default soname for #{RbConfig::CONFIG['host_os']} — " \
+            "set CHEMOMER_LIB to the built cdylib"
+    end
+  end
+  private_class_method :platform
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: chemomer
+version: !ruby/object:Gem::Version
+  version: 0.1.0.1
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Chemomer drives the native chemomer engine — the Rust InChI port gated
+  by the shared oracle corpus — through its C ABI via FFI. from_molfile returns the
+  InChI identifier and the InChIKey; aux_from_molfile returns the AuxInfo line. No
+  engine code is vendored: the cdylib is a runtime artifact.'
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- chemomer.gemspec
+- lib/chemomer.rb
+- lib/chemomer/bindings.rb
+- lib/chemomer/error.rb
+- lib/chemomer/version.rb
+homepage: https://github.com/chemomer/chemomer-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/chemomer/chemomer-ruby
+  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: 4.0.23
+specification_version: 4
+summary: Ruby bindings for the chemomer InChI engine — molfile in, identifier / InChIKey
+  out.
+test_files: []