selfies-js 0.1.0

package/src/dsl/index.js

@@ -0,0 +1,32 @@
+/**
+ * DSL Module - Public API exports
+ *
+ * This module provides the complete DSL functionality for defining
+ * named SELFIES molecules.
+ */
+
+export { lex, TokenType } from './lexer.js'
+export { parse } from './parser.js'
+export { resolve, resolveAll, ResolveError } from './resolver.js'
+export {
+  getDependencies,
+  getDependents,
+  detectCycles,
+  findUnused
+} from './analyzer.js'
+export {
+  createSymbolTable,
+  addDefinition,
+  lookup,
+  has,
+  getNames
+} from './symbolTable.js'
+export {
+  validateValence,
+  validateProgramValence
+} from './valenceValidator.js'
+export {
+  parseImports,
+  loadWithImports,
+  loadFile
+} from './importer.js'

package/src/dsl/lexer.js

@@ -0,0 +1,264 @@
+/**
+ * DSL Lexer - Tokenizes .selfies DSL source code
+ *
+ * The DSL allows defining named SELFIES molecules:
+ *   [methyl] = [C]
+ *   [ethanol] = [methyl][C][O]
+ */
+
+/**
+ * Token types for DSL
+ */
+export const TokenType = {
+  NAME: 'NAME',           // [identifier]
+  EQUALS: 'EQUALS',       // =
+  SELFIES_TOKEN: 'SELFIES_TOKEN', // [C], [=O], etc.
+  COMMENT: 'COMMENT',     // # comment
+  NEWLINE: 'NEWLINE',     // \n
+  EOF: 'EOF',             // end of file
+
+  // Import-related tokens
+  IMPORT: 'IMPORT',       // import keyword
+  FROM: 'FROM',           // from keyword
+  STRING: 'STRING',       // "path/to/file.selfies"
+  STAR: 'STAR',           // * (wildcard import)
+  COMMA: 'COMMA',         // , (separator in selective imports)
+  LBRACKET: 'LBRACKET',   // [ (for selective import list)
+  RBRACKET: 'RBRACKET',   // ] (for selective import list)
+}
+
+/**
+ * Lexes DSL source code into tokens
+ * @param {string} source - DSL source code
+ * @returns {Object[]} Array of tokens with type, value, line, column
+ *
+ * Token structure:
+ * {
+ *   type: TokenType,
+ *   value: string,
+ *   line: number,
+ *   column: number,
+ *   range: [number, number]  // character offsets
+ * }
+ */
+export function lex(source) {
+  const tokens = []
+  let line = 1
+  let column = 1
+  let i = 0
+
+  while (i < source.length) {
+    const char = source[i]
+    const startColumn = column
+    const startOffset = i
+
+    // Skip whitespace (except newlines)
+    if (char === ' ' || char === '\t' || char === '\r') {
+      i++
+      column++
+      continue
+    }
+
+    // Newline
+    if (char === '\n') {
+      tokens.push({
+        type: TokenType.NEWLINE,
+        value: '\n',
+        line,
+        column,
+        range: [i, i + 1]
+      })
+      i++
+      line++
+      column = 1
+      continue
+    }
+
+    // Comment
+    if (char === '#') {
+      const commentStart = i
+      let commentValue = ''
+      while (i < source.length && source[i] !== '\n') {
+        commentValue += source[i]
+        i++
+      }
+      tokens.push({
+        type: TokenType.COMMENT,
+        value: commentValue,
+        line,
+        column: startColumn,
+        range: [commentStart, i]
+      })
+      column += commentValue.length
+      continue
+    }
+
+    // Equals
+    if (char === '=') {
+      tokens.push({
+        type: TokenType.EQUALS,
+        value: '=',
+        line,
+        column,
+        range: [i, i + 1]
+      })
+      i++
+      column++
+      continue
+    }
+
+    // Star (for wildcard imports)
+    if (char === '*') {
+      tokens.push({
+        type: TokenType.STAR,
+        value: '*',
+        line,
+        column,
+        range: [i, i + 1]
+      })
+      i++
+      column++
+      continue
+    }
+
+    // Comma (for selective imports)
+    if (char === ',') {
+      tokens.push({
+        type: TokenType.COMMA,
+        value: ',',
+        line,
+        column,
+        range: [i, i + 1]
+      })
+      i++
+      column++
+      continue
+    }
+
+    // String literal (for import paths)
+    if (char === '"') {
+      const stringStart = i
+      let stringValue = '"'
+      i++
+      column++
+
+      while (i < source.length && source[i] !== '"' && source[i] !== '\n') {
+        stringValue += source[i]
+        i++
+        column++
+      }
+
+      if (i >= source.length || source[i] === '\n') {
+        throw new Error(`Unclosed string at line ${line}, column ${startColumn}`)
+      }
+
+      stringValue += '"'
+      i++
+      column++
+
+      tokens.push({
+        type: TokenType.STRING,
+        value: stringValue,
+        line,
+        column: startColumn,
+        range: [stringStart, i]
+      })
+      continue
+    }
+
+    // Keywords and identifiers (import, from)
+    if (isAlpha(char)) {
+      const wordStart = i
+      let wordValue = ''
+
+      while (i < source.length && isAlphaNumeric(source[i])) {
+        wordValue += source[i]
+        i++
+        column++
+      }
+
+      let type = TokenType.NAME
+      if (wordValue === 'import') {
+        type = TokenType.IMPORT
+      } else if (wordValue === 'from') {
+        type = TokenType.FROM
+      }
+
+      tokens.push({
+        type,
+        value: wordValue,
+        line,
+        column: startColumn,
+        range: [wordStart, i]
+      })
+      continue
+    }
+
+    // Bracketed token (could be NAME or SELFIES_TOKEN)
+    if (char === '[') {
+      const tokenStart = i
+      let tokenValue = '['
+      i++
+      column++
+
+      // Read until closing bracket
+      while (i < source.length && source[i] !== ']') {
+        tokenValue += source[i]
+        i++
+        column++
+      }
+
+      if (i >= source.length) {
+        throw new Error(`Unclosed bracket at line ${line}, column ${startColumn}`)
+      }
+
+      tokenValue += ']'
+      i++
+      column++
+
+      // Determine if this is a NAME or SELFIES_TOKEN
+      // We'll initially mark all as SELFIES_TOKEN
+      // The parser will determine context
+      tokens.push({
+        type: TokenType.SELFIES_TOKEN,
+        value: tokenValue,
+        line,
+        column: startColumn,
+        range: [tokenStart, i]
+      })
+      continue
+    }
+
+    // Unknown character
+    throw new Error(`Unexpected character '${char}' at line ${line}, column ${column}`)
+  }
+
+  // Add EOF token
+  tokens.push({
+    type: TokenType.EOF,
+    value: '',
+    line,
+    column,
+    range: [i, i]
+  })
+
+  return tokens
+}
+
+/**
+ * Checks if character is alphabetic
+ * @param {string} char - Single character
+ * @returns {boolean}
+ */
+function isAlpha(char) {
+  return (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z')
+}
+
+/**
+ * Checks if character is alphanumeric
+ * @param {string} char - Single character
+ * @returns {boolean}
+ */
+function isAlphaNumeric(char) {
+  return isAlpha(char) || (char >= '0' && char <= '9') || char === '_'
+}

package/src/dsl/lexer.test.js

@@ -0,0 +1,115 @@
+/**
+ * Tests for DSL lexer
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { lex, TokenType } from './lexer.js'
+
+describe('lex', () => {
+  // Basic lexing
+  test('lexes simple definition', () => {
+    const tokens = lex('[methyl] = [C]')
+    expect(tokens).toHaveLength(4)  // SELFIES_TOKEN EQUALS SELFIES_TOKEN EOF
+    expect(tokens[0].type).toBe(TokenType.SELFIES_TOKEN)
+    expect(tokens[0].value).toBe('[methyl]')
+    expect(tokens[1].type).toBe(TokenType.EQUALS)
+    expect(tokens[2].type).toBe(TokenType.SELFIES_TOKEN)
+    expect(tokens[2].value).toBe('[C]')
+    expect(tokens[3].type).toBe(TokenType.EOF)
+  })
+
+  test('lexes multiple tokens', () => {
+    const tokens = lex('[ethanol] = [C][C][O]')
+    const selfiesTokens = tokens.filter(t => t.type === TokenType.SELFIES_TOKEN)
+    expect(selfiesTokens).toHaveLength(4)  // [ethanol], [C], [C], [O]
+    expect(selfiesTokens[1].value).toBe('[C]')
+    expect(selfiesTokens[2].value).toBe('[C]')
+    expect(selfiesTokens[3].value).toBe('[O]')
+  })
+
+  test('handles comments', () => {
+    const tokens = lex('# This is a comment\n[methyl] = [C]')
+    const comment = tokens.find(t => t.type === TokenType.COMMENT)
+    expect(comment).toBeDefined()
+    expect(comment.value).toBe('# This is a comment')
+  })
+
+  test('handles newlines', () => {
+    const tokens = lex('[a] = [C]\n[b] = [N]')
+    const newlines = tokens.filter(t => t.type === TokenType.NEWLINE)
+    expect(newlines.length).toBe(1)  // Only the explicit \n, not at EOF
+  })
+
+  // Token properties
+  test('includes line and column info', () => {
+    const tokens = lex('[methyl] = [C]')
+    expect(tokens[0]).toHaveProperty('line')
+    expect(tokens[0]).toHaveProperty('column')
+    expect(tokens[0].line).toBe(1)
+    expect(tokens[0].column).toBe(1)
+  })
+
+  test('includes character range', () => {
+    const tokens = lex('[methyl] = [C]')
+    expect(tokens[0]).toHaveProperty('range')
+    expect(Array.isArray(tokens[0].range)).toBe(true)
+    expect(tokens[0].range).toEqual([0, 8])  // '[methyl]'
+  })
+
+  // Edge cases
+  test('handles empty string', () => {
+    const tokens = lex('')
+    expect(tokens).toHaveLength(1)  // just EOF
+    expect(tokens[0].type).toBe(TokenType.EOF)
+  })
+
+  test('handles whitespace', () => {
+    const tokens = lex('[a]  =  [C]')  // extra spaces
+    const nonEof = tokens.filter(t => t.type !== TokenType.EOF)
+    expect(nonEof).toHaveLength(3)  // [a], =, [C]
+    expect(nonEof[0].value).toBe('[a]')
+    expect(nonEof[1].value).toBe('=')
+    expect(nonEof[2].value).toBe('[C]')
+  })
+
+  test('tracks line numbers correctly', () => {
+    const tokens = lex('[a] = [C]\n[b] = [N]\n[c] = [O]')
+    const selfiesTokens = tokens.filter(t => t.type === TokenType.SELFIES_TOKEN)
+    expect(selfiesTokens[0].line).toBe(1)  // [a]
+    expect(selfiesTokens[2].line).toBe(2)  // [b]
+    expect(selfiesTokens[4].line).toBe(3)  // [c]
+  })
+
+  test('throws on unclosed bracket', () => {
+    expect(() => lex('[methyl')).toThrow(/Unclosed bracket/)
+  })
+
+  test('throws on unexpected character', () => {
+    expect(() => lex('[a] = [C] @')).toThrow(/Unexpected character/)
+  })
+
+  test('handles bond modifiers in tokens', () => {
+    const tokens = lex('[alcohol] = [C][=O]')
+    const selfiesTokens = tokens.filter(t => t.type === TokenType.SELFIES_TOKEN)
+    expect(selfiesTokens[1].value).toBe('[C]')
+    expect(selfiesTokens[2].value).toBe('[=O]')
+  })
+
+  test('handles inline comments', () => {
+    const tokens = lex('[methyl] = [C]  # carbon atom')
+    const comment = tokens.find(t => t.type === TokenType.COMMENT)
+    expect(comment).toBeDefined()
+    expect(comment.value).toContain('carbon atom')
+  })
+})
+
+describe('TokenType', () => {
+  test('exports all token types', () => {
+    expect(TokenType.NAME).toBeDefined()
+    expect(TokenType.EQUALS).toBeDefined()
+    expect(TokenType.SELFIES_TOKEN).toBeDefined()
+    expect(TokenType.COMMENT).toBeDefined()
+    expect(TokenType.NEWLINE).toBeDefined()
+    expect(TokenType.EOF).toBeDefined()
+  })
+})

package/src/dsl/parser.js

@@ -0,0 +1,201 @@
+/**
+ * DSL Parser - Parses DSL tokens into AST and symbol table
+ *
+ * Converts lexer tokens into a structured Program object with
+ * definitions, errors, and warnings.
+ */
+
+import { lex, TokenType } from './lexer.js'
+
+/**
+ * Parses DSL source code into a Program object
+ * @param {string} source - DSL source code
+ * @returns {Object} Program object
+ *
+ * Program structure:
+ * {
+ *   definitions: Map<string, Definition>,
+ *   errors: Diagnostic[],
+ *   warnings: Diagnostic[]
+ * }
+ *
+ * Definition structure:
+ * {
+ *   name: string,
+ *   tokens: Token[],      // SELFIES tokens in the definition
+ *   line: number,
+ *   range: [number, number]
+ * }
+ *
+ * Diagnostic structure:
+ * {
+ *   message: string,
+ *   severity: 'error' | 'warning',
+ *   line: number,
+ *   column: number,
+ *   range: [number, number]
+ * }
+ */
+export function parse(source) {
+  const tokens = lex(source)
+  const program = {
+    definitions: new Map(),
+    errors: [],
+    warnings: []
+  }
+
+  let i = 0
+
+  while (i < tokens.length && tokens[i].type !== TokenType.EOF) {
+    const token = tokens[i]
+
+    // Skip comments and newlines
+    if (token.type === TokenType.COMMENT || token.type === TokenType.NEWLINE) {
+      i++
+      continue
+    }
+
+    // Parse definition line
+    const { definition, errors, nextIndex } = parseDefinition(tokens, i)
+
+    if (definition) {
+      // Check for duplicate definitions
+      if (program.definitions.has(definition.name)) {
+        program.errors.push({
+          message: `Duplicate definition of '${definition.name}'`,
+          severity: 'error',
+          line: definition.line,
+          column: 1,
+          range: definition.range
+        })
+      } else {
+        program.definitions.set(definition.name, definition)
+      }
+    }
+
+    if (errors && errors.length > 0) {
+      program.errors.push(...errors)
+    }
+
+    i = nextIndex
+  }
+
+  return program
+}
+
+/**
+ * Parses a single definition line
+ * @param {Object[]} tokens - Tokens for the line
+ * @param {number} startIndex - Index to start parsing
+ * @returns {{definition: Object, errors: Object[], nextIndex: number}} Parsed definition and any errors
+ */
+function parseDefinition(tokens, startIndex) {
+  const errors = []
+  let i = startIndex
+  const lineStart = tokens[i].line
+
+  // Expected pattern: [name] = [token] [token] ... NEWLINE|EOF
+
+  // 1. Expect NAME (SELFIES_TOKEN that acts as name)
+  if (tokens[i].type !== TokenType.SELFIES_TOKEN) {
+    errors.push(createDiagnostic(
+      `Expected definition name, got ${tokens[i].type}`,
+      'error',
+      tokens[i]
+    ))
+    // Skip to next line
+    while (i < tokens.length && tokens[i].type !== TokenType.NEWLINE && tokens[i].type !== TokenType.EOF) {
+      i++
+    }
+    if (tokens[i].type === TokenType.NEWLINE) i++
+    return { definition: null, errors, nextIndex: i }
+  }
+
+  const nameToken = tokens[i]
+  const name = nameToken.value.slice(1, -1) // Remove brackets
+  i++
+
+  // 2. Expect EQUALS
+  if (i >= tokens.length || tokens[i].type !== TokenType.EQUALS) {
+    errors.push(createDiagnostic(
+      `Expected '=' after definition name`,
+      'error',
+      tokens[i] || nameToken
+    ))
+    // Skip to next line
+    while (i < tokens.length && tokens[i].type !== TokenType.NEWLINE && tokens[i].type !== TokenType.EOF) {
+      i++
+    }
+    if (i < tokens.length && tokens[i].type === TokenType.NEWLINE) i++
+    return { definition: null, errors, nextIndex: i }
+  }
+  i++
+
+  // 3. Collect SELFIES_TOKENs until NEWLINE or EOF
+  const definitionTokens = []
+  const tokenStart = nameToken.range[0]
+  let tokenEnd = tokens[i - 1].range[1]
+
+  while (i < tokens.length &&
+         tokens[i].type !== TokenType.NEWLINE &&
+         tokens[i].type !== TokenType.EOF &&
+         tokens[i].type !== TokenType.COMMENT) {
+    if (tokens[i].type === TokenType.SELFIES_TOKEN) {
+      definitionTokens.push(tokens[i].value)
+      tokenEnd = tokens[i].range[1]
+      i++
+    } else {
+      errors.push(createDiagnostic(
+        `Unexpected token in definition body: ${tokens[i].type}`,
+        'error',
+        tokens[i]
+      ))
+      i++
+    }
+  }
+
+  // 4. Check if we have at least one token
+  if (definitionTokens.length === 0) {
+    errors.push(createDiagnostic(
+      `Definition must have at least one token`,
+      'error',
+      nameToken
+    ))
+  }
+
+  // Skip trailing comment if present
+  if (i < tokens.length && tokens[i].type === TokenType.COMMENT) {
+    i++
+  }
+
+  // Skip newline
+  if (i < tokens.length && tokens[i].type === TokenType.NEWLINE) {
+    i++
+  }
+
+  const definition = {
+    name,
+    tokens: definitionTokens,
+    line: lineStart,
+    range: [tokenStart, tokenEnd]
+  }
+
+  return { definition, errors, nextIndex: i }
+}
+
+/**
+ * Creates a diagnostic object
+ * @param {string} message - Error/warning message
+ * @param {string} severity - 'error' or 'warning'
+ * @param {Object} token - Token where diagnostic occurred
+ * @returns {Object} Diagnostic object
+ */
+function createDiagnostic(message, severity, token) {
+  return {
+    message,
+    severity,
+    line: token.line,
+    column: token.column,
+    range: token.range
+  }
+}