selfies-js 0.1.0

package/src/chemistryValidator.js

@@ -0,0 +1,236 @@
+/**
+ * Chemistry Validator - Validates molecular chemistry using RDKit
+ *
+ * Provides chemistry-aware validation beyond syntax checking.
+ * Uses RDKit to verify that decoded molecules are chemically valid.
+ */
+
+import { decode } from './decoder.js'
+import { initRDKit } from './renderers/svg.js'
+
+/**
+ * Checks if a SELFIES string decodes to a chemically valid molecule
+ * @param {string} selfies - The SELFIES string to validate
+ * @returns {Promise<boolean>} True if molecule is chemically valid
+ *
+ * Uses RDKit's molecule validation to ensure:
+ * - Proper valence satisfaction
+ * - Valid bonding patterns
+ * - Chemically feasible structure
+ *
+ * Example:
+ *   await isChemicallyValid('[C][C][O]') // => true
+ *   await isChemicallyValid('[C][=C][=C][=C]') // => false (too many double bonds)
+ */
+export async function isChemicallyValid(selfies) {
+  try {
+    const RDKit = await initRDKit()
+    const smiles = decode(selfies)
+
+    // Empty SMILES is not valid
+    if (!smiles || smiles.length === 0) {
+      return false
+    }
+
+    const mol = RDKit.get_mol(smiles)
+
+    if (!mol) {
+      return false
+    }
+
+    const valid = mol.is_valid()
+    mol.delete()
+    return valid
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Gets the canonical SMILES representation of a SELFIES string
+ * @param {string} selfies - The SELFIES string to convert
+ * @returns {Promise<string|null>} Canonical SMILES, or null if invalid
+ *
+ * Canonical SMILES allows proper comparison of molecular structures
+ * that may have different string representations.
+ *
+ * Example:
+ *   await getCanonicalSmiles('[C][C][O]') // => 'CCO'
+ *   await getCanonicalSmiles('[C][=C][C][=C][C][=C][Ring1][=Branch1]') // => 'c1ccccc1'
+ */
+export async function getCanonicalSmiles(selfies) {
+  try {
+    const RDKit = await initRDKit()
+    const smiles = decode(selfies)
+
+    // Empty SMILES returns null
+    if (!smiles || smiles.length === 0) {
+      return null
+    }
+
+    const mol = RDKit.get_mol(smiles)
+
+    if (!mol || !mol.is_valid()) {
+      if (mol) mol.delete()
+      return null
+    }
+
+    const canonical = mol.get_smiles()
+    mol.delete()
+    return canonical
+  } catch (error) {
+    return null
+  }
+}
+
+/**
+ * Validates a roundtrip: SMILES → SELFIES → SMILES using canonical comparison
+ * @param {string} originalSmiles - The original SMILES string
+ * @param {string} selfies - The SELFIES encoding
+ * @returns {Promise<boolean>} True if roundtrip preserves molecular structure
+ *
+ * This is the gold standard for validation - ensures that encoding and
+ * decoding preserve the actual molecular structure, not just the string.
+ *
+ * Example:
+ *   const selfies = encode('CCO')
+ *   await validateRoundtrip('CCO', selfies) // => true
+ */
+export async function validateRoundtrip(originalSmiles, selfies) {
+  try {
+    const RDKit = await initRDKit()
+
+    // Get canonical form of original
+    const mol1 = RDKit.get_mol(originalSmiles)
+    if (!mol1 || !mol1.is_valid()) {
+      if (mol1) mol1.delete()
+      return false
+    }
+    const canonical1 = mol1.get_smiles()
+    mol1.delete()
+
+    // Get canonical form of decoded SELFIES
+    const decoded = decode(selfies)
+    const mol2 = RDKit.get_mol(decoded)
+    if (!mol2 || !mol2.is_valid()) {
+      if (mol2) mol2.delete()
+      return false
+    }
+    const canonical2 = mol2.get_smiles()
+    mol2.delete()
+
+    return canonical1 === canonical2
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Gets detailed validation information about a SELFIES string
+ * @param {string} selfies - The SELFIES string to validate
+ * @returns {Promise<Object>} Validation result with details
+ *
+ * Returns object with:
+ *   - isValid: boolean
+ *   - smiles: decoded SMILES (or null)
+ *   - canonical: canonical SMILES (or null)
+ *   - error: error message if invalid (or null)
+ *
+ * Example:
+ *   const result = await getValidationDetails('[C][C][O]')
+ *   // => { isValid: true, smiles: 'CCO', canonical: 'CCO', error: null }
+ */
+export async function getValidationDetails(selfies) {
+  const result = {
+    isValid: false,
+    smiles: null,
+    canonical: null,
+    error: null
+  }
+
+  try {
+    const RDKit = await initRDKit()
+
+    // Try to decode
+    try {
+      result.smiles = decode(selfies)
+    } catch (error) {
+      result.error = `Decode error: ${error.message}`
+      return result
+    }
+
+    // Empty SMILES means the SELFIES contained only invalid/unknown tokens
+    if (!result.smiles || result.smiles.length === 0) {
+      result.error = 'Decoded to empty SMILES (invalid tokens in SELFIES)'
+      return result
+    }
+
+    // Try to create molecule
+    const mol = RDKit.get_mol(result.smiles)
+    if (!mol) {
+      result.error = 'RDKit could not parse SMILES'
+      return result
+    }
+
+    // Check validity
+    if (!mol.is_valid()) {
+      mol.delete()
+      result.error = 'Molecule is not chemically valid'
+      return result
+    }
+
+    // Get canonical form
+    result.canonical = mol.get_smiles()
+    result.isValid = true
+    mol.delete()
+
+  } catch (error) {
+    result.error = error.message
+  }
+
+  return result
+}
+
+/**
+ * Batch validates multiple SELFIES strings
+ * @param {string[]} selfiesArray - Array of SELFIES strings
+ * @returns {Promise<Object>} Validation statistics
+ *
+ * Returns:
+ *   - total: number of strings tested
+ *   - valid: number of valid molecules
+ *   - invalid: number of invalid molecules
+ *   - validPercentage: percentage valid
+ *   - failures: array of {selfies, error} for invalid ones
+ *
+ * Example:
+ *   const results = await batchValidate(['[C][C][O]', '[C][=C]'])
+ *   // => { total: 2, valid: 2, invalid: 0, validPercentage: 100, failures: [] }
+ */
+export async function batchValidate(selfiesArray) {
+  const results = {
+    total: selfiesArray.length,
+    valid: 0,
+    invalid: 0,
+    validPercentage: 0,
+    failures: []
+  }
+
+  for (const selfies of selfiesArray) {
+    const isValid = await isChemicallyValid(selfies)
+    if (isValid) {
+      results.valid++
+    } else {
+      results.invalid++
+      const details = await getValidationDetails(selfies)
+      results.failures.push({
+        selfies,
+        error: details.error
+      })
+    }
+  }
+
+  results.validPercentage = (results.valid / results.total) * 100
+
+  return results
+}

package/src/cli.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * CLI - Command-line interface for executing .selfies files
+ *
+ * Usage:
+ *   selfies-js run <file.selfies> [options]
+ *   selfies-js validate <file.selfies>
+ *   selfies-js list <file.selfies>
+ */
+
+import { loadFile } from './dsl/importer.js'
+import { resolve, resolveAll } from './dsl/resolver.js'
+import { decode } from './decoder.js'
+import { readFileSync } from 'fs'
+
+const COMMANDS = {
+  run: runCommand,
+  validate: validateCommand,
+  list: listCommand,
+  help: helpCommand
+}
+
+/**
+ * Main CLI entry point
+ */
+function main() {
+  const args = process.argv.slice(2)
+
+  if (args.length === 0) {
+    helpCommand()
+    process.exit(0)
+  }
+
+  const command = args[0]
+  const commandFn = COMMANDS[command]
+
+  if (!commandFn) {
+    console.error(`Unknown command: ${command}`)
+    console.error('Run "selfies-js help" for usage information')
+    process.exit(1)
+  }
+
+  try {
+    commandFn(args.slice(1))
+  } catch (error) {
+    console.error(`Error: ${error.message}`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Run command - executes a .selfies file and outputs resolved molecules
+ */
+function runCommand(args) {
+  if (args.length === 0) {
+    console.error('Usage: selfies-js run <file.selfies> [options]')
+    process.exit(1)
+  }
+
+  const filePath = args[0]
+  const options = parseOptions(args.slice(1))
+
+  // Load the file with imports
+  const program = loadFile(filePath)
+
+  // Check for errors
+  if (program.errors.length > 0) {
+    console.error('Compilation errors:')
+    for (const error of program.errors) {
+      console.error(`  ${error.message}`)
+    }
+    process.exit(1)
+  }
+
+  // Resolve all definitions
+  const resolved = resolveAll(program, { validateValence: !options.noValidate })
+
+  // Output results
+  if (options.format === 'smiles') {
+    for (const [name, selfies] of resolved) {
+      try {
+        const smiles = decode(selfies)
+        console.log(`${name}: ${smiles}`)
+      } catch (error) {
+        console.error(`${name}: Error - ${error.message}`)
+      }
+    }
+  } else {
+    for (const [name, selfies] of resolved) {
+      console.log(`${name}: ${selfies}`)
+    }
+  }
+}
+
+/**
+ * Validate command - checks a .selfies file for errors
+ */
+function validateCommand(args) {
+  if (args.length === 0) {
+    console.error('Usage: selfies-js validate <file.selfies>')
+    process.exit(1)
+  }
+
+  const filePath = args[0]
+  const program = loadFile(filePath)
+
+  // Check for parse errors
+  if (program.errors.length > 0) {
+    console.log('Validation failed with errors:')
+    for (const error of program.errors) {
+      console.log(`  Line ${error.line}: ${error.message}`)
+    }
+    process.exit(1)
+  }
+
+  // Check for warnings
+  if (program.warnings && program.warnings.length > 0) {
+    console.log('Warnings:')
+    for (const warning of program.warnings) {
+      console.log(`  Line ${warning.line}: ${warning.message}`)
+    }
+  }
+
+  // Try to resolve all definitions
+  try {
+    resolveAll(program)
+    console.log(`✓ File is valid (${program.definitions.size} definitions)`)
+  } catch (error) {
+    console.log(`Validation failed: ${error.message}`)
+    process.exit(1)
+  }
+}
+
+/**
+ * List command - lists all definitions in a .selfies file
+ */
+function listCommand(args) {
+  if (args.length === 0) {
+    console.error('Usage: selfies-js list <file.selfies>')
+    process.exit(1)
+  }
+
+  const filePath = args[0]
+  const program = loadFile(filePath)
+
+  console.log(`Definitions in ${filePath}:`)
+  for (const [name, definition] of program.definitions) {
+    const tokens = definition.tokens.join('')
+    console.log(`  [${name}] = ${tokens}`)
+  }
+}
+
+/**
+ * Help command - displays usage information
+ */
+function helpCommand() {
+  console.log(`
+selfies-js - CLI for SELFIES DSL
+
+Usage:
+  selfies-js run <file.selfies> [options]       Execute a .selfies file
+  selfies-js validate <file.selfies>            Validate a .selfies file
+  selfies-js list <file.selfies>                List definitions in a file
+  selfies-js help                               Show this help message
+
+Run command options:
+  --format=smiles                               Output as SMILES instead of SELFIES
+  --no-validate                                 Skip valence validation
+
+Examples:
+  selfies-js run molecules.selfies
+  selfies-js run molecules.selfies --format=smiles
+  selfies-js validate molecules.selfies
+  selfies-js list molecules.selfies
+`)
+}
+
+/**
+ * Parses command-line options
+ */
+function parseOptions(args) {
+  const options = {
+    format: 'selfies',
+    noValidate: false
+  }
+
+  for (const arg of args) {
+    if (arg.startsWith('--format=')) {
+      options.format = arg.split('=')[1]
+    } else if (arg === '--no-validate') {
+      options.noValidate = true
+    }
+  }
+
+  return options
+}
+
+// Run CLI if executed directly
+// Handle both Unix and Windows paths
+const scriptPath = process.argv[1]?.replace(/\\/g, '/')
+const metaPath = import.meta.url.replace('file:///', '').replace('file://', '')
+if (scriptPath && (metaPath.endsWith(scriptPath) || scriptPath.endsWith(metaPath.split('/').pop()))) {
+  main()
+}
+
+export { main }

package/src/constraints.js

@@ -0,0 +1,186 @@
+/**
+ * Constraints - Semantic constraint management for SELFIES
+ *
+ * Manages bonding constraints that define what chemical structures are valid.
+ * Based on selfies-py's bond_constraints.py system.
+ */
+
+/**
+ * Preset constraint configurations
+ * Maps element symbols (with optional charge) to maximum bonding capacity
+ */
+const PRESET_CONSTRAINTS = {
+  // Default constraints (balanced between permissive and realistic)
+  default: {
+    'H': 1,
+    'F': 1, 'Cl': 1, 'Br': 1, 'I': 1,
+    'O': 2, 'O+1': 3, 'O-1': 1,
+    'N': 3, 'N+1': 4, 'N-1': 2,
+    'C': 4, 'C+1': 3, 'C-1': 3,
+    'B': 3, 'B+1': 2, 'B-1': 4,
+    'S': 6, 'S+1': 5, 'S-1': 5,
+    'P': 5, 'P+1': 4, 'P-1': 6,
+    '?': 8  // Default for unspecified atoms
+  },
+
+  // Octet rule (stricter, follows traditional chemistry)
+  octet_rule: {
+    'H': 1,
+    'F': 1, 'Cl': 1, 'Br': 1, 'I': 1,
+    'O': 2, 'O+1': 3, 'O-1': 1,
+    'N': 3, 'N+1': 4, 'N-1': 2,
+    'C': 4, 'C+1': 3, 'C-1': 3,
+    'B': 3, 'B+1': 2, 'B-1': 4,
+    'S': 2, 'S+1': 3, 'S-1': 1,  // Stricter than default
+    'P': 3, 'P+1': 2, 'P-1': 4,  // Stricter than default
+    '?': 8
+  },
+
+  // Hypervalent (more permissive for heavy elements)
+  hypervalent: {
+    'H': 1,
+    'F': 1,
+    'Cl': 7, 'Br': 7, 'I': 7,  // More permissive for halogens
+    'O': 2, 'O+1': 3, 'O-1': 1,
+    'N': 5, 'N+1': 6, 'N-1': 4,  // More permissive
+    'C': 4, 'C+1': 3, 'C-1': 3,
+    'B': 3, 'B+1': 2, 'B-1': 4,
+    'S': 6, 'S+1': 5, 'S-1': 5,
+    'P': 5, 'P+1': 4, 'P-1': 6,
+    '?': 8
+  }
+}
+
+/**
+ * Current active constraints (default to 'default' preset)
+ * This is module-level state
+ */
+let _currentConstraints = { ...PRESET_CONSTRAINTS.default }
+
+/**
+ * Gets a preset constraint configuration by name
+ * @param {string} name - Preset name: "default", "octet_rule", or "hypervalent"
+ * @returns {Object} Constraint object mapping element → max bonds
+ * @throws {Error} If preset name is unknown
+ *
+ * Example:
+ *   const constraints = getPresetConstraints('default')
+ *   // { 'C': 4, 'N': 3, 'O': 2, ... }
+ */
+export function getPresetConstraints(name) {
+  if (!(name in PRESET_CONSTRAINTS)) {
+    throw new Error(`Unknown preset: ${name}. Valid presets: default, octet_rule, hypervalent`)
+  }
+  // Return a copy to prevent mutation
+  return { ...PRESET_CONSTRAINTS[name] }
+}
+
+/**
+ * Gets the current semantic constraints
+ * @returns {Object} Current constraint configuration
+ *
+ * Example:
+ *   const constraints = getSemanticConstraints()
+ *   console.log(constraints['C'])  // 4
+ */
+export function getSemanticConstraints() {
+  // Return a copy to prevent mutation
+  return { ..._currentConstraints }
+}
+
+/**
+ * Sets new semantic constraints
+ * @param {Object} constraints - Constraint object mapping element → max bonds
+ * @throws {Error} If constraints are invalid
+ *
+ * Example:
+ *   setSemanticConstraints({
+ *     'C': 4,
+ *     'N': 3,
+ *     'O': 2,
+ *     '?': 8  // default for unknown
+ *   })
+ */
+export function setSemanticConstraints(constraints) {
+  // Validate constraints object
+  validateConstraints(constraints)
+
+  // Update current constraints
+  _currentConstraints = { ...constraints }
+}
+
+/**
+ * Gets bonding capacity for a specific element (optionally with charge)
+ * @param {string} element - Element symbol (e.g., 'C', 'N', 'O')
+ * @param {number} charge - Optional charge (default: 0)
+ * @returns {number} Maximum number of bonds for this element
+ *
+ * Example:
+ *   getBondingCapacity('C')      // 4
+ *   getBondingCapacity('N', 1)   // 4 (N+1)
+ *   getBondingCapacity('O', -1)  // 1 (O-1)
+ */
+export function getBondingCapacity(element, charge = 0) {
+  // Build key from element + charge
+  const key = charge === 0 ? element : `${element}${charge > 0 ? '+' : ''}${charge}`
+
+  // Look up in current constraints
+  if (key in _currentConstraints) {
+    return _currentConstraints[key]
+  }
+
+  // Fall back to '?' default if not found
+  return _currentConstraints['?']
+}
+
+/**
+ * Validates that a constraint object is well-formed
+ * @param {Object} constraints - Constraint object to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If constraints are invalid with explanation
+ */
+export function validateConstraints(constraints) {
+  // Check that constraints is an object
+  if (typeof constraints !== 'object' || constraints === null) {
+    throw new Error('Constraints must be an object')
+  }
+
+  // Check that '?' default is present
+  if (!('?' in constraints)) {
+    throw new Error("Constraints must include '?' default for unknown elements")
+  }
+
+  // Check that all values are positive integers
+  for (const [element, capacity] of Object.entries(constraints)) {
+    if (!Number.isInteger(capacity)) {
+      throw new Error(`Bonding capacity for ${element} must be an integer, got ${capacity}`)
+    }
+    if (capacity < 0) {
+      throw new Error(`Bonding capacity for ${element} must be non-negative, got ${capacity}`)
+    }
+  }
+
+  return true
+}
+
+/**
+ * Checks if an atom with given bonds would violate constraints
+ * @param {string} element - Element symbol
+ * @param {number} charge - Atom charge
+ * @param {number} usedBonds - Number of bonds already used
+ * @param {number} newBondOrder - Order of new bond to add
+ * @returns {boolean} True if adding bond would violate constraints
+ *
+ * Used during parsing to enforce semantic validity
+ */
+export function wouldViolateConstraints(element, charge, usedBonds, newBondOrder) {
+  const capacity = getBondingCapacity(element, charge)
+  return usedBonds + newBondOrder > capacity
+}
+
+/**
+ * Resets constraints to default preset
+ */
+export function resetConstraints() {
+  _currentConstraints = { ...PRESET_CONSTRAINTS.default }
+}