selfies-js 0.1.0

package/src/dsl/analyzer.js

@@ -0,0 +1,170 @@
+/**
+ * Analyzer - Static analysis for DSL programs
+ *
+ * Detects forward references, circular dependencies, unused definitions,
+ * and other semantic issues.
+ */
+
+/**
+ * Gets the names that a definition depends on
+ * @param {Object} program - Program object
+ * @param {string} name - Name of definition to analyze
+ * @returns {string[]} Array of dependency names
+ *
+ * Example:
+ *   // [methyl] = [C]
+ *   // [ethanol] = [methyl][C][O]
+ *   getDependencies(program, 'ethanol') // => ['methyl']
+ *   getDependencies(program, 'methyl') // => []
+ */
+export function getDependencies(program, name) {
+  const definition = program.definitions.get(name)
+  if (!definition) {
+    return []
+  }
+
+  const dependencies = []
+  for (const token of definition.tokens) {
+    const tokenName = token.slice(1, -1) // Remove brackets
+    if (program.definitions.has(tokenName)) {
+      if (!dependencies.includes(tokenName)) {
+        dependencies.push(tokenName)
+      }
+    }
+  }
+
+  return dependencies
+}
+
+/**
+ * Gets the names that depend on a definition
+ * @param {Object} program - Program object
+ * @param {string} name - Name to find dependents of
+ * @returns {string[]} Array of dependent names
+ *
+ * Example:
+ *   // [methyl] = [C]
+ *   // [ethyl] = [methyl][C]
+ *   // [ethanol] = [ethyl][O]
+ *   getDependents(program, 'methyl') // => ['ethyl', 'ethanol']
+ */
+export function getDependents(program, name) {
+  const dependents = []
+
+  // Build a set of all transitive dependents
+  const visited = new Set()
+
+  function findDirectDependents(targetName) {
+    for (const [defName, definition] of program.definitions) {
+      if (visited.has(defName)) continue
+
+      const deps = getDependencies(program, defName)
+      if (deps.includes(targetName)) {
+        visited.add(defName)
+        dependents.push(defName)
+        // Recursively find dependents of this dependent
+        findDirectDependents(defName)
+      }
+    }
+  }
+
+  findDirectDependents(name)
+  return dependents
+}
+
+/**
+ * Detects circular dependencies in a program
+ * @param {Object} program - Program object
+ * @returns {Object[]} Array of cycle diagnostics
+ *
+ * Each diagnostic contains:
+ * {
+ *   message: string,
+ *   severity: 'error',
+ *   cycle: string[],  // Names forming the cycle
+ *   ...location info
+ * }
+ */
+export function detectCycles(program) {
+  const diagnostics = []
+  const visited = new Set()
+  const visiting = new Set()
+  const cyclesFound = new Set()
+
+  function dfs(name, path = []) {
+    if (visiting.has(name)) {
+      // Found a cycle
+      const cycleStart = path.indexOf(name)
+      const cycle = [...path.slice(cycleStart), name]
+      const cycleKey = cycle.sort().join(',')
+
+      // Only report each unique cycle once
+      if (!cyclesFound.has(cycleKey)) {
+        cyclesFound.add(cycleKey)
+        const definition = program.definitions.get(name)
+        diagnostics.push({
+          message: `Circular dependency: ${cycle.join(' -> ')}`,
+          severity: 'error',
+          cycle,
+          line: definition?.line || 1,
+          column: 1,
+          range: definition?.range || [0, 0]
+        })
+      }
+      return
+    }
+
+    if (visited.has(name)) {
+      return
+    }
+
+    visiting.add(name)
+    path.push(name)
+
+    const deps = getDependencies(program, name)
+    for (const dep of deps) {
+      dfs(dep, [...path])
+    }
+
+    path.pop()
+    visiting.delete(name)
+    visited.add(name)
+  }
+
+  for (const name of program.definitions.keys()) {
+    if (!visited.has(name)) {
+      dfs(name)
+    }
+  }
+
+  return diagnostics
+}
+
+/**
+ * Finds unused definitions (not referenced by any other definition)
+ * @param {Object} program - Program object
+ * @returns {string[]} Array of unused definition names
+ */
+export function findUnused(program) {
+  const referenced = new Set()
+
+  // Find all referenced names
+  for (const [name, definition] of program.definitions) {
+    for (const token of definition.tokens) {
+      const tokenName = token.slice(1, -1)
+      if (program.definitions.has(tokenName)) {
+        referenced.add(tokenName)
+      }
+    }
+  }
+
+  // Find definitions that are not referenced
+  const unused = []
+  for (const name of program.definitions.keys()) {
+    if (!referenced.has(name)) {
+      unused.push(name)
+    }
+  }
+
+  return unused
+}

package/src/dsl/analyzer.test.js

@@ -0,0 +1,139 @@
+/**
+ * Tests for analyzer
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { parse } from './parser.js'
+import { getDependencies, getDependents, detectCycles, findUnused } from './analyzer.js'
+
+describe('getDependencies', () => {
+  test('gets direct dependencies', () => {
+    const source = '[methyl] = [C]\n[ethanol] = [methyl][C][O]'
+    const program = parse(source)
+    expect(getDependencies(program, 'ethanol')).toContain('methyl')
+  })
+
+  test('returns empty for primitive definitions', () => {
+    const program = parse('[methyl] = [C]')
+    expect(getDependencies(program, 'methyl')).toEqual([])
+  })
+
+  test('returns empty for undefined name', () => {
+    const program = parse('[methyl] = [C]')
+    expect(getDependencies(program, 'undefined')).toEqual([])
+  })
+
+  test('handles multiple dependencies', () => {
+    const source = '[a] = [C]\n[b] = [N]\n[c] = [a][b][O]'
+    const program = parse(source)
+    const deps = getDependencies(program, 'c')
+    expect(deps).toContain('a')
+    expect(deps).toContain('b')
+    expect(deps).toHaveLength(2)
+  })
+
+  test('deduplicates dependencies', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][methyl]'
+    const program = parse(source)
+    const deps = getDependencies(program, 'ethyl')
+    expect(deps).toEqual(['methyl'])
+  })
+})
+
+describe('getDependents', () => {
+  test('gets dependents', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]\n[ethanol] = [ethyl][O]'
+    const program = parse(source)
+    const dependents = getDependents(program, 'methyl')
+    expect(dependents).toContain('ethyl')
+    expect(dependents).toContain('ethanol')
+  })
+
+  test('returns empty for unused definitions', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [C][C]'
+    const program = parse(source)
+    expect(getDependents(program, 'methyl')).toEqual([])
+  })
+
+  test('returns empty for undefined name', () => {
+    const program = parse('[methyl] = [C]')
+    expect(getDependents(program, 'undefined')).toEqual([])
+  })
+
+  test('includes transitive dependents', () => {
+    const source = '[a] = [C]\n[b] = [a]\n[c] = [b]'
+    const program = parse(source)
+    const dependents = getDependents(program, 'a')
+    expect(dependents).toContain('b')
+    expect(dependents).toContain('c')
+  })
+})
+
+describe('detectCycles', () => {
+  test('detects simple cycle', () => {
+    const source = '[a] = [b]\n[b] = [a]'
+    const program = parse(source)
+    const cycles = detectCycles(program)
+    expect(cycles.length).toBeGreaterThan(0)
+    expect(cycles[0].message).toContain('Circular dependency')
+    expect(cycles[0].cycle).toBeDefined()
+  })
+
+  test('detects self-reference', () => {
+    const source = '[a] = [a]'
+    const program = parse(source)
+    const cycles = detectCycles(program)
+    expect(cycles.length).toBeGreaterThan(0)
+  })
+
+  test('detects longer cycles', () => {
+    const source = '[a] = [b]\n[b] = [c]\n[c] = [a]'
+    const program = parse(source)
+    const cycles = detectCycles(program)
+    expect(cycles.length).toBeGreaterThan(0)
+  })
+
+  test('returns empty for acyclic graph', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]'
+    const program = parse(source)
+    const cycles = detectCycles(program)
+    expect(cycles).toEqual([])
+  })
+
+  test('diagnostics include severity and location', () => {
+    const source = '[a] = [b]\n[b] = [a]'
+    const program = parse(source)
+    const cycles = detectCycles(program)
+    expect(cycles[0]).toMatchObject({
+      severity: 'error',
+      line: expect.any(Number),
+      column: expect.any(Number),
+      range: expect.any(Array)
+    })
+  })
+})
+
+describe('findUnused', () => {
+  test('finds unused definitions', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [C][C]\n[ethanol] = [ethyl][O]'
+    const program = parse(source)
+    const unused = findUnused(program)
+    expect(unused).toContain('methyl')
+    expect(unused).toContain('ethanol')
+    expect(unused).not.toContain('ethyl')
+  })
+
+  test('returns empty when all used', () => {
+    const source = '[methyl] = [C]\n[ethyl] = [methyl][C]'
+    const program = parse(source)
+    const unused = findUnused(program)
+    expect(unused).toEqual(['ethyl'])
+  })
+
+  test('returns all for single definition', () => {
+    const source = '[methyl] = [C]'
+    const program = parse(source)
+    const unused = findUnused(program)
+    expect(unused).toEqual(['methyl'])
+  })
+})

package/src/dsl/dsl.test.js

@@ -0,0 +1,146 @@
+/**
+ * Integration tests for DSL parsing and resolution
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { parse } from './parser.js'
+import { resolve, resolveAll } from './resolver.js'
+import { getDependencies, getDependents } from './analyzer.js'
+
+describe('DSL Integration', () => {
+  test('complete workflow: parse -> resolve', () => {
+    const source = `
+# Simple definitions
+[methyl] = [C]
+[ethyl] = [C][C]
+[hydroxyl] = [O]
+
+# Composition
+[ethanol] = [ethyl][hydroxyl]
+`
+    const program = parse(source)
+    expect(program.errors).toEqual([])
+    expect(program.definitions.size).toBe(4)
+
+    expect(resolve(program, 'methyl')).toBe('[C]')
+    expect(resolve(program, 'ethyl')).toBe('[C][C]')
+    expect(resolve(program, 'hydroxyl')).toBe('[O]')
+    expect(resolve(program, 'ethanol')).toBe('[C][C][O]')
+  })
+
+  test('resolves with decode option', () => {
+    const source = `
+[methyl] = [C]
+[ethanol] = [methyl][C][O]
+`
+    const program = parse(source)
+    expect(resolve(program, 'ethanol', { decode: true })).toBe('CCO')
+  })
+
+  test('handles complex molecule definitions', () => {
+    const source = `
+[carbonyl] = [=O]
+[methyl] = [C]
+[acetone] = [methyl][C][carbonyl][methyl]
+`
+    const program = parse(source)
+    expect(resolve(program, 'acetone')).toBe('[C][C][=O][C]')
+  })
+
+  test('resolveAll returns all definitions', () => {
+    const source = `
+[methyl] = [C]
+[ethyl] = [methyl][C]
+[propyl] = [ethyl][C]
+`
+    const program = parse(source)
+    const all = resolveAll(program)
+    expect(all.size).toBe(3)
+    expect(all.get('methyl')).toBe('[C]')
+    expect(all.get('ethyl')).toBe('[C][C]')
+    expect(all.get('propyl')).toBe('[C][C][C]')
+  })
+
+  test('dependency analysis', () => {
+    const source = `
+[methyl] = [C]
+[ethyl] = [methyl][C]
+[ethanol] = [ethyl][O]
+`
+    const program = parse(source)
+
+    expect(getDependencies(program, 'ethanol')).toEqual(['ethyl'])
+    expect(getDependencies(program, 'ethyl')).toEqual(['methyl'])
+    expect(getDependencies(program, 'methyl')).toEqual([])
+
+    const dependents = getDependents(program, 'methyl')
+    expect(dependents).toContain('ethyl')
+    expect(dependents).toContain('ethanol')
+  })
+
+  test('handles branching structures', () => {
+    const source = `
+[methyl] = [C]
+[isobutane] = [C][C][Branch1][C][methyl][methyl]
+`
+    const program = parse(source)
+    expect(resolve(program, 'isobutane')).toBe('[C][C][Branch1][C][C][C]')
+  })
+
+  test('handles ring structures', () => {
+    const source = `
+[benzene] = [C][=C][C][=C][C][=C][Ring1][=Branch1]
+`
+    const program = parse(source)
+    expect(resolve(program, 'benzene')).toBe('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+  })
+
+  test('empty program', () => {
+    const program = parse('')
+    expect(program.definitions.size).toBe(0)
+    expect(program.errors).toEqual([])
+  })
+
+  test('program with only comments', () => {
+    const program = parse('# Just a comment\n# Another comment')
+    expect(program.definitions.size).toBe(0)
+    expect(program.errors).toEqual([])
+  })
+
+  test('error recovery allows parsing multiple definitions', () => {
+    const source = `
+[valid] = [C]
+[invalid] [C]
+[another_valid] = [N]
+`
+    const program = parse(source)
+    expect(program.definitions.has('valid')).toBe(true)
+    expect(program.definitions.has('another_valid')).toBe(true)
+    expect(program.errors.length).toBeGreaterThan(0)
+  })
+
+  test('real-world example: amino acid fragments', () => {
+    const source = `
+# Basic building blocks
+[amino] = [N]
+[carboxyl] = [C][=O][O]
+[methyl] = [C]
+[ethyl] = [methyl][C]
+
+# Amino acid backbone
+[backbone] = [amino][C][carboxyl]
+
+# Side chains
+[alanine_side] = [methyl]
+[valine_side] = [ethyl][Branch1][C][methyl][methyl]
+
+# Complete amino acids
+[alanine] = [amino][C][Branch1][C][alanine_side][carboxyl]
+`
+    const program = parse(source)
+    expect(program.errors).toEqual([])
+
+    const alanine = resolve(program, 'alanine')
+    expect(alanine).toBe('[N][C][Branch1][C][C][C][=O][O]')
+  })
+})

package/src/dsl/importer.js

@@ -0,0 +1,238 @@
+/**
+ * Importer - Handles importing definitions from other .selfies files
+ *
+ * Supports import syntax like:
+ *   import "./fragments.selfies"                       # Import all definitions
+ *   import * from "./common.selfies"                  # Import all (alternative syntax)
+ *   import [methyl, ethyl] from "./fragments.selfies" # Import specific definitions
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { resolve as resolvePath, dirname, join, isAbsolute } from 'path'
+import { parse } from './parser.js'
+
+/**
+ * Parses import statements from DSL source
+ * @param {string} source - DSL source code
+ * @param {string} currentFilePath - Path to current file (for relative imports)
+ * @returns {Object} {imports: Import[], sourceWithoutImports: string}
+ *
+ * Import structure:
+ * {
+ *   names: string[] | '*',  // Array of names or '*' for all
+ *   filePath: string,       // Resolved absolute path
+ *   originalPath: string    // Original path from import statement
+ * }
+ */
+export function parseImports(source, currentFilePath) {
+  const imports = []
+  const lines = source.split('\n')
+  const nonImportLines = []
+
+  // Match: import [names] from "path"  OR  import * from "path"  OR  import "path"
+  const importWithNamesRegex = /^import\s+\[([^\]]+)\]\s+from\s+['"]([^'"]+)['"]/
+  const importAllFromRegex = /^import\s+\*\s+from\s+['"]([^'"]+)['"]/
+  const importSimpleRegex = /^import\s+['"]([^'"]+)['"]/
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    // Skip empty lines and comments for import matching
+    if (!trimmed.startsWith('import')) {
+      nonImportLines.push(line)
+      continue
+    }
+
+    let match
+    let names
+    let relativeFilePath
+
+    // Try matching different import patterns
+    if ((match = trimmed.match(importWithNamesRegex))) {
+      // import [name1, name2] from "path"
+      names = match[1].split(',').map(n => n.trim())
+      relativeFilePath = match[2]
+    } else if ((match = trimmed.match(importAllFromRegex))) {
+      // import * from "path"
+      names = '*'
+      relativeFilePath = match[1]
+    } else if ((match = trimmed.match(importSimpleRegex))) {
+      // import "path" (shorthand for import all)
+      names = '*'
+      relativeFilePath = match[1]
+    } else {
+      // Not a valid import line, keep it
+      nonImportLines.push(line)
+      continue
+    }
+
+    // Resolve file path relative to current file
+    const currentDir = currentFilePath ? dirname(resolvePath(currentFilePath)) : process.cwd()
+    const absoluteFilePath = isAbsolute(relativeFilePath)
+      ? relativeFilePath
+      : join(currentDir, relativeFilePath)
+
+    imports.push({
+      names,
+      filePath: absoluteFilePath,
+      originalPath: relativeFilePath
+    })
+  }
+
+  return {
+    imports,
+    sourceWithoutImports: nonImportLines.join('\n')
+  }
+}
+
+/**
+ * Loads and merges imported definitions into a program
+ * Handles recursive imports with cycle detection
+ * @param {string} source - DSL source code
+ * @param {string} filePath - Path to current file
+ * @param {Set<string>} visited - Set of already visited file paths (for cycle detection)
+ * @returns {Object} Merged program with all imported definitions
+ */
+export function loadWithImports(source, filePath, visited = new Set()) {
+  // Normalize the file path for cycle detection
+  const normalizedPath = filePath ? resolvePath(filePath) : null
+
+  // Check for circular imports
+  if (normalizedPath && visited.has(normalizedPath)) {
+    return {
+      definitions: new Map(),
+      errors: [{
+        message: `Circular import detected: ${filePath}`,
+        severity: 'error',
+        line: 1,
+        column: 1,
+        range: [0, 0]
+      }],
+      warnings: []
+    }
+  }
+
+  // Add current file to visited set
+  if (normalizedPath) {
+    visited.add(normalizedPath)
+  }
+
+  // Parse imports from source
+  const { imports, sourceWithoutImports } = parseImports(source, filePath)
+
+  // Parse the main file (without import statements)
+  const mainProgram = parse(sourceWithoutImports)
+
+  // Load each import and merge definitions
+  for (const importSpec of imports) {
+    // Check if file exists
+    if (!existsSync(importSpec.filePath)) {
+      mainProgram.errors.push({
+        message: `Import file not found: ${importSpec.originalPath} (resolved to ${importSpec.filePath})`,
+        severity: 'error',
+        line: 1,
+        column: 1,
+        range: [0, 0]
+      })
+      continue
+    }
+
+    try {
+      const importedSource = readFileSync(importSpec.filePath, 'utf-8')
+
+      // Recursively load with imports (pass visited set for cycle detection)
+      const importedProgram = loadWithImports(importedSource, importSpec.filePath, visited)
+
+      // Propagate errors from imported file
+      if (importedProgram.errors.length > 0) {
+        for (const error of importedProgram.errors) {
+          mainProgram.errors.push({
+            ...error,
+            message: `In ${importSpec.originalPath}: ${error.message}`
+          })
+        }
+      }
+
+      // Merge definitions based on import specification
+      if (importSpec.names === '*') {
+        // Import all definitions
+        for (const [name, definition] of importedProgram.definitions) {
+          if (!mainProgram.definitions.has(name)) {
+            // Mark definition as imported
+            mainProgram.definitions.set(name, {
+              ...definition,
+              importedFrom: importSpec.originalPath
+            })
+          }
+        }
+      } else {
+        // Import specific definitions
+        for (const name of importSpec.names) {
+          if (importedProgram.definitions.has(name)) {
+            if (!mainProgram.definitions.has(name)) {
+              mainProgram.definitions.set(name, {
+                ...importedProgram.definitions.get(name),
+                importedFrom: importSpec.originalPath
+              })
+            }
+          } else {
+            mainProgram.errors.push({
+              message: `Cannot import '${name}': not found in ${importSpec.originalPath}`,
+              severity: 'error',
+              line: 1,
+              column: 1,
+              range: [0, 0]
+            })
+          }
+        }
+      }
+    } catch (error) {
+      mainProgram.errors.push({
+        message: `Failed to import from ${importSpec.originalPath}: ${error.message}`,
+        severity: 'error',
+        line: 1,
+        column: 1,
+        range: [0, 0]
+      })
+    }
+  }
+
+  return mainProgram
+}
+
+/**
+ * Recursively loads a file with all its transitive imports
+ * @param {string} filePath - Path to .selfies file
+ * @returns {Object} Merged program with all definitions
+ */
+export function loadFile(filePath) {
+  const absolutePath = resolvePath(filePath)
+
+  if (!existsSync(absolutePath)) {
+    return {
+      definitions: new Map(),
+      errors: [{
+        message: `File not found: ${filePath}`,
+        severity: 'error',
+        line: 1,
+        column: 1,
+        range: [0, 0]
+      }],
+      warnings: []
+    }
+  }
+
+  const source = readFileSync(absolutePath, 'utf-8')
+  return loadWithImports(source, absolutePath)
+}
+
+/**
+ * Gets the list of imports from a source file without loading them
+ * @param {string} source - DSL source code
+ * @param {string} currentFilePath - Path to current file
+ * @returns {Object[]} Array of import specifications
+ */
+export function getImports(source, currentFilePath) {
+  const { imports } = parseImports(source, currentFilePath)
+  return imports
+}