selfies-js 0.1.0

package/src/dsl/parser.test.js

@@ -0,0 +1,148 @@
+/**
+ * Tests for DSL parser
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { parse } from './parser.js'
+
+describe('parse', () => {
+  // Basic parsing
+  test('parses simple definition', () => {
+    const program = parse('[methyl] = [C]')
+    expect(program.definitions.has('methyl')).toBe(true)
+    expect(program.errors).toEqual([])
+
+    const def = program.definitions.get('methyl')
+    expect(def).toMatchObject({
+      name: 'methyl',
+      tokens: ['[C]'],
+      line: 1
+    })
+  })
+
+  test('parses multiple definitions', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [C][C]'
+    const program = parse(source)
+    expect(program.definitions.size).toBe(2)
+    expect(program.definitions.has('methyl')).toBe(true)
+    expect(program.definitions.has('ethyl')).toBe(true)
+  })
+
+  test('ignores comments', () => {
+    const source = '# Comment\n[methyl] = [C]'
+    const program = parse(source)
+    expect(program.definitions.size).toBe(1)
+    expect(program.definitions.has('methyl')).toBe(true)
+  })
+
+  test('handles inline comments', () => {
+    const source = '[methyl] = [C]  # This is a carbon'
+    const program = parse(source)
+    expect(program.definitions.size).toBe(1)
+    expect(program.errors).toEqual([])
+  })
+
+  test('handles empty lines', () => {
+    const source = '[methyl] = [C]\n\n[ethyl] = [C][C]'
+    const program = parse(source)
+    expect(program.definitions.size).toBe(2)
+  })
+
+  // Error detection
+  test('detects duplicate definitions', () => {
+    const source = '[methyl] = [C]\n[methyl] = [C][C]'
+    const program = parse(source)
+    expect(program.errors.length).toBeGreaterThan(0)
+    expect(program.errors[0].message).toContain('Duplicate')
+  })
+
+  test('detects syntax errors - missing equals', () => {
+    const source = '[methyl] [C]'
+    const program = parse(source)
+    expect(program.errors.length).toBeGreaterThan(0)
+    expect(program.errors[0].message).toContain('=')
+  })
+
+  test('detects syntax errors - missing tokens', () => {
+    const source = '[methyl] ='
+    const program = parse(source)
+    expect(program.errors.length).toBeGreaterThan(0)
+    expect(program.errors[0].message).toContain('at least one token')
+  })
+
+  test('detects syntax errors - unexpected token type', () => {
+    const source = '[methyl] = =  [C]'
+    const program = parse(source)
+    expect(program.errors.length).toBeGreaterThan(0)
+  })
+
+  // Definition structure
+  test('definition includes correct range', () => {
+    const program = parse('[methyl] = [C]')
+    const def = program.definitions.get('methyl')
+    expect(def.range).toBeDefined()
+    expect(Array.isArray(def.range)).toBe(true)
+    expect(def.range.length).toBe(2)
+  })
+
+  test('definition includes line number', () => {
+    const source = '\n\n[methyl] = [C]'
+    const program = parse(source)
+    const def = program.definitions.get('methyl')
+    expect(def.line).toBe(3)
+  })
+
+  // Complex definitions
+  test('parses complex SELFIES tokens', () => {
+    const source = '[alcohol] = [C][=O][Branch1][C][O]'
+    const program = parse(source)
+    const def = program.definitions.get('alcohol')
+    expect(def.tokens).toEqual(['[C]', '[=O]', '[Branch1]', '[C]', '[O]'])
+  })
+
+  test('handles multiple tokens per definition', () => {
+    const source = '[ethanol] = [C][C][O]'
+    const program = parse(source)
+    const def = program.definitions.get('ethanol')
+    expect(def.tokens).toHaveLength(3)
+  })
+
+  // Program structure
+  test('returns program with definitions map', () => {
+    const program = parse('[methyl] = [C]')
+    expect(program).toHaveProperty('definitions')
+    expect(program.definitions).toBeInstanceOf(Map)
+  })
+
+  test('returns program with errors array', () => {
+    const program = parse('[methyl] = [C]')
+    expect(program).toHaveProperty('errors')
+    expect(Array.isArray(program.errors)).toBe(true)
+  })
+
+  test('returns program with warnings array', () => {
+    const program = parse('[methyl] = [C]')
+    expect(program).toHaveProperty('warnings')
+    expect(Array.isArray(program.warnings)).toBe(true)
+  })
+
+  // Diagnostic structure
+  test('diagnostic includes line and column', () => {
+    const source = '[methyl] [C]'  // missing =
+    const program = parse(source)
+    const diag = program.errors[0]
+    expect(diag).toMatchObject({
+      severity: 'error',
+      line: expect.any(Number),
+      column: expect.any(Number)
+    })
+  })
+
+  test('diagnostic includes range', () => {
+    const source = '[methyl] [C]'  // missing =
+    const program = parse(source)
+    const diag = program.errors[0]
+    expect(diag.range).toBeDefined()
+    expect(Array.isArray(diag.range)).toBe(true)
+  })
+})

package/src/dsl/resolver.js

@@ -0,0 +1,136 @@
+/**
+ * Resolver - Expands DSL definitions to primitive SELFIES
+ *
+ * Recursively resolves references to other definitions until only
+ * primitive SELFIES tokens remain.
+ */
+
+import { decode } from '../decoder.js'
+import { validateValence } from './valenceValidator.js'
+
+/**
+ * Custom error for resolution failures
+ */
+export class ResolveError extends Error {
+  constructor(message, name) {
+    super(message)
+    this.name = 'ResolveError'
+    this.definitionName = name
+  }
+}
+
+/**
+ * Resolves a definition name to its primitive SELFIES string
+ * @param {Object} program - Program object from parser
+ * @param {string} name - Name to resolve
+ * @param {Object} options - Resolution options
+ * @param {boolean} options.decode - If true, return SMILES instead of SELFIES
+ * @param {boolean} options.validateValence - If true, validate chemical valence (default: true)
+ * @returns {string} Resolved SELFIES (or SMILES if decode option is true)
+ * @throws {ResolveError} If name is not defined or circular reference detected
+ *
+ * Example:
+ *   const program = parse('[methyl] = [C]\n[ethanol] = [methyl][C][O]')
+ *   resolve(program, 'ethanol') // => '[C][C][O]'
+ *   resolve(program, 'ethanol', { decode: true }) // => 'CCO'
+ */
+export function resolve(program, name, options = {}) {
+  // Look up the definition
+  if (!program.definitions.has(name)) {
+    throw new ResolveError(`Undefined definition: ${name}`, name)
+  }
+
+  // Resolve recursively with cycle detection
+  const visiting = new Set()
+  const resolved = resolveRecursive(program, name, visiting)
+
+  // Join tokens to form SELFIES string
+  const selfies = resolved.join('')
+
+  // Validate valence if requested (default: true)
+  if (options.validateValence !== false) {
+    const valenceErrors = validateValence(selfies, name)
+    if (valenceErrors.length > 0) {
+      throw new ResolveError(valenceErrors[0].message, name)
+    }
+  }
+
+  // Optionally decode to SMILES
+  if (options.decode) {
+    return decode(selfies)
+  }
+
+  return selfies
+}
+
+/**
+ * Resolves all definitions in a program
+ * @param {Object} program - Program object from parser
+ * @param {Object} options - Resolution options
+ * @returns {Map<string, string>} Map of name to resolved SELFIES
+ */
+export function resolveAll(program, options = {}) {
+  const resolved = new Map()
+
+  for (const [name, definition] of program.definitions) {
+    try {
+      resolved.set(name, resolve(program, name, options))
+    } catch (error) {
+      // Skip definitions that can't be resolved (e.g., circular dependencies)
+      // The error will be caught when trying to resolve individually
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Internal recursive resolution with cycle detection
+ * @param {Object} program - Program object
+ * @param {string} name - Name to resolve
+ * @param {Set<string>} visiting - Set of names currently being visited (for cycle detection)
+ * @returns {string[]} Resolved primitive tokens
+ */
+function resolveRecursive(program, name, visiting = new Set()) {
+  // Check for circular dependency
+  if (visiting.has(name)) {
+    throw new ResolveError(`Circular dependency detected involving '${name}'`, name)
+  }
+
+  // Mark as visiting
+  visiting.add(name)
+
+  // Get definition
+  const definition = program.definitions.get(name)
+  const resolvedTokens = []
+
+  // Resolve each token
+  for (const token of definition.tokens) {
+    if (isReference(token, program)) {
+      // It's a reference to another definition - resolve it recursively
+      const refName = token.slice(1, -1) // Remove brackets
+      const refResolved = resolveRecursive(program, refName, visiting)
+      resolvedTokens.push(...refResolved)
+    } else {
+      // It's a primitive token - keep it as is
+      resolvedTokens.push(token)
+    }
+  }
+
+  // Unmark as visiting
+  visiting.delete(name)
+
+  return resolvedTokens
+}
+
+/**
+ * Checks if a token is a reference to another definition
+ * @param {string} token - Token to check
+ * @param {Object} program - Program object
+ * @returns {boolean} True if token is a defined name
+ */
+function isReference(token, program) {
+  // Strip brackets and check if it's a defined name
+  const name = token.slice(1, -1)
+  return program.definitions.has(name)
+}

package/src/dsl/resolver.test.js

@@ -0,0 +1,99 @@
+/**
+ * Tests for resolver
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { parse } from './parser.js'
+import { resolve, resolveAll } from './resolver.js'
+
+describe('resolve', () => {
+  test('resolves simple definition', () => {
+    const program = parse('[methyl] = [C]')
+    expect(resolve(program, 'methyl')).toBe('[C]')
+  })
+
+  test('resolves nested definitions', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]\n[ethanol] = [ethyl][O]'
+    const program = parse(source)
+    expect(resolve(program, 'ethanol')).toBe('[C][C][O]')
+  })
+
+  test('resolves with decode option', () => {
+    const program = parse('[ethanol] = [C][C][O]')
+    expect(resolve(program, 'ethanol', { decode: true })).toBe('CCO')
+  })
+
+  test('handles multiple references in one definition', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][methyl]'
+    const program = parse(source)
+    expect(resolve(program, 'ethyl')).toBe('[C][C]')
+  })
+
+  test('handles deeply nested references', () => {
+    const source = '[a] = [C]\n[b] = [a][a]\n[c] = [b][b]\n[d] = [c][c]'
+    const program = parse(source)
+    expect(resolve(program, 'd')).toBe('[C][C][C][C][C][C][C][C]')
+  })
+
+  test('throws on undefined name', () => {
+    const program = parse('[methyl] = [C]')
+    expect(() => resolve(program, 'undefined')).toThrow(/Undefined definition/)
+  })
+
+  test('detects circular dependencies', () => {
+    const source = '[a] = [b]\n[b] = [a]'
+    const program = parse(source)
+    expect(() => resolve(program, 'a')).toThrow(/Circular dependency/)
+  })
+
+  test('detects self-referential definitions', () => {
+    const source = '[a] = [a]'
+    const program = parse(source)
+    expect(() => resolve(program, 'a')).toThrow(/Circular dependency/)
+  })
+
+  test('detects indirect circular dependencies', () => {
+    const source = '[a] = [b]\n[b] = [c]\n[c] = [a]'
+    const program = parse(source)
+    expect(() => resolve(program, 'a')).toThrow(/Circular dependency/)
+  })
+
+  test('resolves mixed primitive and reference tokens', () => {
+    const source = '[methyl] = [C]\n[ethanol] = [methyl][C][O]'
+    const program = parse(source)
+    expect(resolve(program, 'ethanol')).toBe('[C][C][O]')
+  })
+})
+
+describe('resolveAll', () => {
+  test('resolves all definitions', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]'
+    const program = parse(source)
+    const resolved = resolveAll(program)
+    expect(resolved.get('methyl')).toBe('[C]')
+    expect(resolved.get('ethyl')).toBe('[C][C]')
+  })
+
+  test('skips definitions with circular dependencies', () => {
+    const source = '[a] = [C]\n[b] = [c]\n[c] = [b]'
+    const program = parse(source)
+    const resolved = resolveAll(program)
+    expect(resolved.get('a')).toBe('[C]')
+    expect(resolved.has('b')).toBe(false)
+    expect(resolved.has('c')).toBe(false)
+  })
+
+  test('resolves all with decode option', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]'
+    const program = parse(source)
+    const resolved = resolveAll(program, { decode: true })
+    expect(resolved.get('methyl')).toBe('C')
+    expect(resolved.get('ethyl')).toBe('CC')
+  })
+
+  test('returns empty map for empty program', () => {
+    const program = parse('')
+    const resolved = resolveAll(program)
+    expect(resolved.size).toBe(0)
+  })
+})

package/src/dsl/symbolTable.js

@@ -0,0 +1,56 @@
+/**
+ * Symbol Table - Manages name-to-definition mappings for DSL
+ *
+ * Provides utilities for working with the symbol table in a Program object.
+ */
+
+/**
+ * Creates an empty symbol table
+ * @returns {Map<string, Object>} Empty symbol table
+ */
+export function createSymbolTable() {
+  return new Map()
+}
+
+/**
+ * Adds a definition to the symbol table
+ * @param {Map} symbolTable - Symbol table to update
+ * @param {string} name - Definition name
+ * @param {Object} definition - Definition object
+ * @throws {Error} If name already exists
+ */
+export function addDefinition(symbolTable, name, definition) {
+  if (symbolTable.has(name)) {
+    throw new Error(`Definition '${name}' already exists`)
+  }
+  symbolTable.set(name, definition)
+}
+
+/**
+ * Looks up a definition by name
+ * @param {Map} symbolTable - Symbol table to search
+ * @param {string} name - Name to look up
+ * @returns {Object|undefined} Definition if found, undefined otherwise
+ */
+export function lookup(symbolTable, name) {
+  return symbolTable.get(name)
+}
+
+/**
+ * Checks if a name is defined in the symbol table
+ * @param {Map} symbolTable - Symbol table to check
+ * @param {string} name - Name to check
+ * @returns {boolean} True if name exists
+ */
+export function has(symbolTable, name) {
+  return symbolTable.has(name)
+}
+
+/**
+ * Gets all definition names in the symbol table
+ * @param {Map} symbolTable - Symbol table
+ * @returns {string[]} Array of definition names
+ */
+export function getNames(symbolTable) {
+  return Array.from(symbolTable.keys())
+}

package/src/dsl/symbolTable.test.js

@@ -0,0 +1,68 @@
+/**
+ * Tests for symbol table
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { createSymbolTable, addDefinition, lookup, has, getNames } from './symbolTable.js'
+
+describe('symbolTable', () => {
+  test('createSymbolTable returns empty map', () => {
+    const table = createSymbolTable()
+    expect(table).toBeInstanceOf(Map)
+    expect(table.size).toBe(0)
+  })
+
+  test('addDefinition adds entry', () => {
+    const table = createSymbolTable()
+    const def = { name: 'test', tokens: ['[C]'], line: 1, range: [0, 5] }
+    addDefinition(table, 'test', def)
+    expect(table.size).toBe(1)
+    expect(table.has('test')).toBe(true)
+  })
+
+  test('addDefinition throws on duplicate', () => {
+    const table = createSymbolTable()
+    const def = { name: 'test', tokens: ['[C]'], line: 1, range: [0, 5] }
+    addDefinition(table, 'test', def)
+    expect(() => addDefinition(table, 'test', def)).toThrow(/already exists/)
+  })
+
+  test('lookup returns definition', () => {
+    const table = createSymbolTable()
+    const def = { name: 'test', tokens: ['[C]'], line: 1, range: [0, 5] }
+    addDefinition(table, 'test', def)
+    expect(lookup(table, 'test')).toBe(def)
+  })
+
+  test('lookup returns undefined for missing', () => {
+    const table = createSymbolTable()
+    expect(lookup(table, 'missing')).toBeUndefined()
+  })
+
+  test('has returns true for existing', () => {
+    const table = createSymbolTable()
+    const def = { name: 'test', tokens: ['[C]'], line: 1, range: [0, 5] }
+    addDefinition(table, 'test', def)
+    expect(has(table, 'test')).toBe(true)
+  })
+
+  test('has returns false for missing', () => {
+    const table = createSymbolTable()
+    expect(has(table, 'missing')).toBe(false)
+  })
+
+  test('getNames returns all names', () => {
+    const table = createSymbolTable()
+    addDefinition(table, 'a', { name: 'a', tokens: ['[C]'], line: 1, range: [0, 5] })
+    addDefinition(table, 'b', { name: 'b', tokens: ['[N]'], line: 2, range: [6, 11] })
+    const names = getNames(table)
+    expect(names).toHaveLength(2)
+    expect(names).toContain('a')
+    expect(names).toContain('b')
+  })
+
+  test('getNames returns empty array for empty table', () => {
+    const table = createSymbolTable()
+    expect(getNames(table)).toEqual([])
+  })
+})

package/src/dsl/valenceValidator.js

@@ -0,0 +1,147 @@
+/**
+ * Valence Validator - Validates chemical valence in DSL definitions
+ *
+ * Checks that SELFIES molecules defined in the DSL follow valence rules
+ * and returns compilation errors for invalid structures.
+ */
+
+import { getBondingCapacity } from '../constraints.js'
+import { decode } from '../decoder.js'
+
+/**
+ * Validates valence for a resolved SELFIES string
+ * @param {string} selfies - Resolved SELFIES string
+ * @param {string} defName - Definition name (for error messages)
+ * @returns {Object[]} Array of valence error diagnostics
+ *
+ * Each diagnostic contains:
+ * {
+ *   message: string,
+ *   severity: 'error',
+ *   definitionName: string
+ * }
+ */
+export function validateValence(selfies, defName) {
+  const errors = []
+
+  try {
+    // Try to decode to SMILES - this will catch many structural issues
+    const smiles = decode(selfies)
+
+    // Parse the SELFIES to extract atoms and bonds
+    const tokens = tokenizeSelfies(selfies)
+    const atomBonds = calculateBonds(tokens)
+
+    // Check each atom's valence
+    for (const [atom, bondCount] of Object.entries(atomBonds)) {
+      const { element, charge } = parseAtom(atom)
+      const maxBonds = getBondingCapacity(element, charge)
+
+      if (bondCount > maxBonds) {
+        errors.push({
+          message: `Valence error in '${defName}': ${element} has ${bondCount} bonds but max is ${maxBonds}`,
+          severity: 'error',
+          definitionName: defName
+        })
+      }
+    }
+  } catch (error) {
+    // If decoding fails, it's a structural error
+    errors.push({
+      message: `Invalid structure in '${defName}': ${error.message}`,
+      severity: 'error',
+      definitionName: defName
+    })
+  }
+
+  return errors
+}
+
+/**
+ * Validates valence for all definitions in a program
+ * @param {Object} program - Program object with definitions
+ * @param {Map} resolvedMap - Map of resolved SELFIES strings
+ * @returns {Object[]} Array of all valence errors
+ */
+export function validateProgramValence(program, resolvedMap) {
+  const allErrors = []
+
+  for (const [name, definition] of program.definitions) {
+    if (resolvedMap.has(name)) {
+      const selfies = resolvedMap.get(name)
+      const errors = validateValence(selfies, name)
+      allErrors.push(...errors)
+    }
+  }
+
+  return allErrors
+}
+
+/**
+ * Tokenizes SELFIES string into individual tokens
+ * @param {string} selfies - SELFIES string
+ * @returns {string[]} Array of tokens
+ */
+function tokenizeSelfies(selfies) {
+  const tokens = selfies.match(/\[[^\]]+\]/g) || []
+  return tokens
+}
+
+/**
+ * Calculates bond counts for each atom
+ * @param {string[]} tokens - SELFIES tokens
+ * @returns {Object} Map of atom index to bond count
+ */
+function calculateBonds(tokens) {
+  const atomBonds = {}
+  let atomIndex = 0
+  let currentBondOrder = 1
+
+  for (const token of tokens) {
+    const content = token.slice(1, -1) // Remove brackets
+
+    // Check if it's a bond modifier
+    if (content.startsWith('=')) {
+      currentBondOrder = 2
+      continue
+    } else if (content.startsWith('#')) {
+      currentBondOrder = 3
+      continue
+    }
+
+    // Check if it's a structural token (Branch, Ring)
+    if (content.includes('Branch') || content.includes('Ring')) {
+      continue
+    }
+
+    // It's an atom
+    const atomKey = `${atomIndex}:${content}`
+    atomBonds[atomKey] = (atomBonds[atomKey] || 0) + currentBondOrder
+
+    // Reset bond order for next atom
+    currentBondOrder = 1
+    atomIndex++
+  }
+
+  return atomBonds
+}
+
+/**
+ * Parses atom token to extract element and charge
+ * @param {string} atomKey - Atom key like "0:C" or "1:N+1"
+ * @returns {Object} {element, charge}
+ */
+function parseAtom(atomKey) {
+  const [_, content] = atomKey.split(':')
+
+  // Check for charge
+  const chargeMatch = content.match(/([A-Z][a-z]?)([+-]\d+)?/)
+  if (chargeMatch) {
+    const element = chargeMatch[1]
+    const chargeStr = chargeMatch[2] || '+0'
+    const charge = parseInt(chargeStr)
+    return { element, charge }
+  }
+
+  return { element: content, charge: 0 }
+}