conjure-js 0.0.12 → 0.0.13

package/src/core/registry.ts

@@ -0,0 +1,209 @@
+import { isKeyword, isSymbol, isVector } from './assertions'
+import { makeEnv, makeNamespace } from './env'
+import { EvaluationError } from './errors'
+import type { CljValue, Env } from './types'
+
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+export type NamespaceRegistry = Map<string, Env>
+
+// ---------------------------------------------------------------------------
+// Clone helpers — used by snapshot / restoreRuntime
+// ---------------------------------------------------------------------------
+
+function cloneBindings(bindings: Map<string, CljValue>): Map<string, CljValue> {
+  const out = new Map<string, CljValue>()
+  for (const [k, v] of bindings) {
+    out.set(k, v.kind === 'var' ? { ...v } : v)
+  }
+  return out
+}
+
+function cloneEnv(env: Env, memo: Map<Env, Env>): Env {
+  if (memo.has(env)) return memo.get(env)!
+  const cloned: Env = {
+    bindings: cloneBindings(env.bindings),
+    outer: null,
+  }
+  if (env.ns) {
+    cloned.ns = {
+      kind: 'namespace',
+      name: env.ns.name,
+      vars: new Map([...env.ns.vars].map(([k, v]) => [k, { ...v }])),
+      aliases: new Map(), // wired in cloneRegistry pass 2
+      readerAliases: new Map(env.ns.readerAliases),
+    }
+  }
+  memo.set(env, cloned)
+  if (env.outer) cloned.outer = cloneEnv(env.outer, memo)
+  return cloned
+}
+
+export function cloneRegistry(registry: NamespaceRegistry): NamespaceRegistry {
+  const memo = new Map<Env, Env>()
+  const next = new Map<string, Env>()
+  // Pass 1: clone all envs (ns.aliases left empty)
+  for (const [name, env] of registry) {
+    next.set(name, cloneEnv(env, memo))
+  }
+  // Pass 2: wire ns.aliases to the cloned CljNamespace objects
+  for (const [name, env] of registry) {
+    const clonedEnv = next.get(name)!
+    if (env.ns && clonedEnv.ns) {
+      for (const [alias, origNs] of env.ns.aliases) {
+        const targetCloned = next.get(origNs.name)
+        if (targetCloned?.ns) clonedEnv.ns.aliases.set(alias, targetCloned.ns)
+      }
+    }
+  }
+  return next
+}
+
+// ---------------------------------------------------------------------------
+// ensureNamespaceInRegistry — creates namespace env if it doesn't exist yet
+// ---------------------------------------------------------------------------
+
+export function ensureNamespaceInRegistry(
+  registry: NamespaceRegistry,
+  coreEnv: Env,
+  name: string
+): Env {
+  if (!registry.has(name)) {
+    const nsEnv = makeEnv(coreEnv)
+    nsEnv.ns = makeNamespace(name)
+    registry.set(name, nsEnv)
+  }
+  return registry.get(name)!
+}
+
+// ---------------------------------------------------------------------------
+// processRequireSpec — processes a single [ns.name :as alias :refer [...]] spec.
+// resolveNs is called when the target namespace isn't yet loaded.
+// ---------------------------------------------------------------------------
+
+export function processRequireSpec(
+  spec: CljValue,
+  currentEnv: Env,
+  registry: NamespaceRegistry,
+  resolveNs?: (nsName: string) => boolean
+): void {
+  if (!isVector(spec)) {
+    throw new EvaluationError(
+      'require spec must be a vector, e.g. [my.ns :as alias]',
+      { spec }
+    )
+  }
+
+  const elements = spec.value
+  if (elements.length === 0 || !isSymbol(elements[0])) {
+    throw new EvaluationError(
+      'First element of require spec must be a namespace symbol',
+      { spec }
+    )
+  }
+
+  const nsName = elements[0].name
+
+  const hasAsAlias = elements.some(
+    (el) => isKeyword(el) && el.name === ':as-alias'
+  )
+  if (hasAsAlias) {
+    let i = 1
+    while (i < elements.length) {
+      const kw = elements[i]
+      if (!isKeyword(kw)) {
+        throw new EvaluationError(
+          `Expected keyword in require spec, got ${kw.kind}`,
+          { spec, position: i }
+        )
+      }
+      if (kw.name === ':as-alias') {
+        i++
+        const alias = elements[i]
+        if (!alias || !isSymbol(alias)) {
+          throw new EvaluationError(':as-alias expects a symbol alias', {
+            spec,
+            position: i,
+          })
+        }
+        currentEnv.ns!.readerAliases.set(alias.name, nsName)
+        i++
+      } else {
+        throw new EvaluationError(
+          `:as-alias specs only support :as-alias, got ${kw.name}`,
+          { spec }
+        )
+      }
+    }
+    return
+  }
+
+  let targetEnv = registry.get(nsName)
+  if (!targetEnv && resolveNs) {
+    resolveNs(nsName)
+    targetEnv = registry.get(nsName)
+  }
+  if (!targetEnv) {
+    throw new EvaluationError(
+      `Namespace ${nsName} not found. Only already-loaded namespaces can be required.`,
+      { nsName }
+    )
+  }
+
+  let i = 1
+  while (i < elements.length) {
+    const kw = elements[i]
+    if (!isKeyword(kw)) {
+      throw new EvaluationError(
+        `Expected keyword in require spec, got ${kw.kind}`,
+        { spec, position: i }
+      )
+    }
+
+    if (kw.name === ':as') {
+      i++
+      const alias = elements[i]
+      if (!alias || !isSymbol(alias)) {
+        throw new EvaluationError(':as expects a symbol alias', {
+          spec,
+          position: i,
+        })
+      }
+      currentEnv.ns!.aliases.set(alias.name, targetEnv.ns!)
+      i++
+    } else if (kw.name === ':refer') {
+      i++
+      const symsVec = elements[i]
+      if (!symsVec || !isVector(symsVec)) {
+        throw new EvaluationError(':refer expects a vector of symbols', {
+          spec,
+          position: i,
+        })
+      }
+      for (const sym of symsVec.value) {
+        if (!isSymbol(sym)) {
+          throw new EvaluationError(':refer vector must contain only symbols', {
+            spec,
+            sym,
+          })
+        }
+        const v = targetEnv.ns!.vars.get(sym.name)
+        if (v === undefined) {
+          throw new EvaluationError(
+            `Symbol ${sym.name} not found in namespace ${nsName}`,
+            { nsName, symbol: sym.name }
+          )
+        }
+        currentEnv.ns!.vars.set(sym.name, v)
+      }
+      i++
+    } else {
+      throw new EvaluationError(
+        `Unknown require option ${kw.name}. Supported: :as, :refer`,
+        { spec, keyword: kw.name }
+      )
+    }
+  }
+}

package/src/core/runtime.ts

@@ -0,0 +1,376 @@
+import { isKeyword, isString, isSymbol, isVector } from './assertions'
+import {
+  resolveModuleOrder,
+  type RuntimeModule,
+  type ModuleContext,
+} from './module'
+import { internVar, makeEnv, makeNamespace } from './env'
+import { EvaluationError } from './errors'
+import { v } from './factories'
+import { readForms } from './reader'
+import { tokenize } from './tokenizer'
+import type { CljNamespace, CljValue, Env, EvaluationContext } from './types'
+import { builtInNamespaceSources } from '../clojure/generated/builtin-namespace-registry'
+import { makeCoreModule } from './core-module'
+import { makeJsModule } from './stdlib/js-namespace'
+import {
+  cloneRegistry,
+  ensureNamespaceInRegistry,
+  processRequireSpec,
+} from './registry'
+import type { NamespaceRegistry } from './registry'
+import {
+  extractAliasMapFromTokens,
+  extractNsNameFromTokens,
+  extractRequireClauses,
+} from './ns-forms'
+import { wireIdeStubs, wireNsCore } from './bootstrap'
+
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+export type { NamespaceRegistry }
+
+export type RuntimeSnapshot = {
+  registry: NamespaceRegistry
+}
+
+export type RuntimeOptions = {
+  sourceRoots?: string[]
+  readFile?: (filePath: string) => string
+}
+
+export type Runtime = {
+  readonly registry: NamespaceRegistry
+
+  // Namespace management
+  ensureNamespace(name: string): Env
+  getNamespaceEnv(name: string): Env | null
+  getNs(name: string): CljNamespace | null
+  /** Updates the *ns* var root to reflect the named namespace. Called by session.setNs. */
+  syncNsVar(name: string): void
+  addSourceRoot(path: string): void
+
+  // Require mechanics — ctx is threaded through so lazy namespace loading works
+  processRequireSpec(spec: CljValue, fromEnv: Env, ctx: EvaluationContext): void
+  processNsRequires(
+    forms: CljValue[],
+    fromEnv: Env,
+    ctx: EvaluationContext
+  ): void
+  /**
+   * Async variant of processNsRequires.
+   * Handles both symbol specs (sync) and string specs (async via ctx.importModule).
+   * Must be used when the ns form contains string (:require ["module" :as Alias]) entries.
+   */
+  processNsRequiresAsync(
+    forms: CljValue[],
+    fromEnv: Env,
+    ctx: EvaluationContext
+  ): Promise<void>
+
+  // File loading — ctx comes from the owning session
+  loadFile(
+    source: string,
+    nsName: string | undefined,
+    filePath: string | undefined,
+    ctx: EvaluationContext
+  ): string
+
+  // Snapshot
+  snapshot(): RuntimeSnapshot
+
+  // Module installation — declarative capability extension
+  installModules(modules: RuntimeModule[]): void
+}
+
+// ---------------------------------------------------------------------------
+// buildRuntime — shared factory used by createRuntime and restoreRuntime.
+// Orchestrates registry wiring and native fn installation via bootstrap.ts.
+// Does NOT load clojure.core source — that's the session's bootstrap job.
+// ---------------------------------------------------------------------------
+
+function buildRuntime(
+  registry: NamespaceRegistry,
+  coreEnv: Env,
+  options: RuntimeOptions | undefined
+): Runtime {
+  const sourceRoots = new Set<string>(options?.sourceRoots ?? [])
+
+  // varOwners tracks which module installed each var, keyed by "ns/varName".
+  // Prevents two modules from declaring the same var in the same namespace.
+  const varOwners = new Map<string, string>()
+
+  // currentNsRef mirrors the owning session's currentNs for require/resolve.
+  // Updated via runtime.syncNsVar() which session.setNs calls.
+  let currentNsRef = 'user'
+
+  // resolveNamespace: loads a namespace by name if not already in the registry.
+  // ctx is passed explicitly — this is the active EvaluationContext at the
+  // call site. For loadFile calls, it's the file's ctx. For runtime require
+  // native fn calls, it comes from the evaluator via cljNativeFunctionWithContext.
+  function resolveNamespace(nsName: string, ctx: EvaluationContext): boolean {
+    const builtInLoader = builtInNamespaceSources[nsName]
+    if (builtInLoader) {
+      runtime.loadFile(builtInLoader(), nsName, undefined, ctx)
+      return true
+    }
+    if (!options?.readFile || sourceRoots.size === 0) return false
+    for (const root of sourceRoots) {
+      const filePath = `${root.replace(/\/$/, '')}/${nsName.replace(/\./g, '/')}.clj`
+      try {
+        const source = options.readFile(filePath)
+        if (source) {
+          runtime.loadFile(source, undefined, undefined, ctx)
+          return true
+        }
+      } catch {
+        continue
+      }
+    }
+    return false
+  }
+
+  wireNsCore(registry, coreEnv, () => currentNsRef, resolveNamespace)
+  wireIdeStubs(registry, coreEnv)
+
+  const runtime: Runtime = {
+    get registry() {
+      return registry
+    },
+
+    ensureNamespace(name: string): Env {
+      return ensureNamespaceInRegistry(registry, coreEnv, name)
+    },
+
+    getNamespaceEnv(name: string): Env | null {
+      return registry.get(name) ?? null
+    },
+
+    getNs(name: string): CljNamespace | null {
+      return registry.get(name)?.ns ?? null
+    },
+
+    syncNsVar(name: string): void {
+      currentNsRef = name
+      const nsVarInner = coreEnv.ns?.vars.get('*ns*')
+      if (nsVarInner) {
+        const nsObj = registry.get(name)?.ns
+        if (nsObj) nsVarInner.value = nsObj
+      }
+    },
+
+    addSourceRoot(path: string): void {
+      sourceRoots.add(path)
+    },
+
+    processRequireSpec(
+      spec: CljValue,
+      fromEnv: Env,
+      ctx: EvaluationContext
+    ): void {
+      processRequireSpec(spec, fromEnv, registry, (nsName) =>
+        resolveNamespace(nsName, ctx)
+      )
+    },
+
+    processNsRequires(
+      forms: CljValue[],
+      fromEnv: Env,
+      ctx: EvaluationContext
+    ): void {
+      const requireClauses = extractRequireClauses(forms)
+      for (const specs of requireClauses) {
+        for (const spec of specs) {
+          if (
+            isVector(spec) &&
+            spec.value.length > 0 &&
+            isString(spec.value[0])
+          ) {
+            const specifier = spec.value[0].value
+            throw new EvaluationError(
+              `String module require ["${specifier}" :as ...] is async — use evaluateAsync() instead of evaluate()`,
+              { specifier }
+            )
+          }
+          processRequireSpec(spec, fromEnv, registry, (nsName) =>
+            resolveNamespace(nsName, ctx)
+          )
+        }
+      }
+    },
+
+    async processNsRequiresAsync(
+      forms: CljValue[],
+      fromEnv: Env,
+      ctx: EvaluationContext
+    ): Promise<void> {
+      const requireClauses = extractRequireClauses(forms)
+      for (const specs of requireClauses) {
+        for (const spec of specs) {
+          if (
+            isVector(spec) &&
+            spec.value.length > 0 &&
+            isString(spec.value[0])
+          ) {
+            // String module require — calls importModule and interns result as a var
+            const specifier = spec.value[0].value
+            if (!ctx.importModule) {
+              throw new EvaluationError(
+                `importModule is not configured; cannot require "${specifier}". Pass importModule to createSession().`,
+                { specifier }
+              )
+            }
+            const elements = spec.value
+            let aliasName: string | null = null
+            for (let i = 1; i < elements.length; i++) {
+              if (
+                isKeyword(elements[i]) &&
+                (elements[i] as { name: string }).name === ':as'
+              ) {
+                i++
+                const aliasSym = elements[i]
+                if (!aliasSym || !isSymbol(aliasSym)) {
+                  throw new EvaluationError(':as expects a symbol alias', {
+                    spec,
+                  })
+                }
+                aliasName = aliasSym.name
+                break
+              }
+            }
+            if (aliasName === null) {
+              throw new EvaluationError(
+                `String require spec must have an :as alias: ["${specifier}" :as Alias]`,
+                { spec }
+              )
+            }
+            const rawModule = await ctx.importModule(specifier)
+            internVar(aliasName, v.jsValue(rawModule), fromEnv)
+          } else {
+            // Symbol require spec — sync path
+            processRequireSpec(spec, fromEnv, registry, (nsName) =>
+              resolveNamespace(nsName, ctx)
+            )
+          }
+        }
+      }
+    },
+
+    loadFile(
+      source: string,
+      nsName: string | undefined,
+      filePath: string | undefined,
+      ctx: EvaluationContext
+    ): string {
+      const tokens = tokenize(source)
+      const targetNs = extractNsNameFromTokens(tokens) ?? nsName ?? 'user'
+      const aliasMap = extractAliasMapFromTokens(tokens)
+      const forms = readForms(tokens, targetNs, aliasMap)
+      const env = this.ensureNamespace(targetNs)
+      ctx.currentSource = source
+      ctx.currentFile = filePath
+      ctx.currentLineOffset = 0
+      ctx.currentColOffset = 0
+      this.processNsRequires(forms, env, ctx)
+      try {
+        for (const form of forms) {
+          const expanded = ctx.expandAll(form, env)
+          ctx.evaluate(expanded, env)
+        }
+      } finally {
+        ctx.currentSource = undefined
+        ctx.currentFile = undefined
+      }
+      return targetNs
+    },
+
+    installModules(modules: RuntimeModule[]): void {
+      const ordered = resolveModuleOrder(modules, new Set(registry.keys()))
+
+      for (const mod of ordered) {
+        for (const decl of mod.declareNs) {
+          const nsEnv = ensureNamespaceInRegistry(registry, coreEnv, decl.name)
+
+          const ctx: ModuleContext = {
+            getVar(ns, name) {
+              const nsEnv = registry.get(ns)
+              const v = nsEnv?.ns?.vars.get(name)
+              return v ?? null
+            },
+            getNamespace(name) {
+              return registry.get(name)?.ns ?? null
+            },
+          }
+
+          const varMap = decl.vars(ctx)
+
+          for (const [varName, decl] of varMap) {
+            const key = `${nsEnv.ns!.name}/${varName}`
+            const existing = varOwners.get(key)
+            if (existing !== undefined) {
+              throw new Error(
+                `var '${varName}' in '${nsEnv.ns!.name}' already declared by module '${existing}'`
+              )
+            }
+            internVar(varName, decl.value, nsEnv, decl.meta)
+            if (decl.dynamic) {
+              const v = nsEnv.ns!.vars.get(varName)!
+              v.dynamic = true
+            }
+            varOwners.set(key, mod.id)
+          }
+        }
+      }
+    },
+
+    snapshot(): RuntimeSnapshot {
+      return { registry: cloneRegistry(registry) }
+    },
+  }
+
+  return runtime
+}
+
+// ---------------------------------------------------------------------------
+// createRuntime — builds a fresh runtime with bootstrapped core + user envs.
+// Does NOT load clojure.core source — that's the session's bootstrap job.
+// ---------------------------------------------------------------------------
+
+export function createRuntime(options?: RuntimeOptions): Runtime {
+  const registry: NamespaceRegistry = new Map()
+
+  // Bootstrap: clojure.core env
+  const coreEnv = makeEnv()
+  coreEnv.ns = makeNamespace('clojure.core')
+  registry.set('clojure.core', coreEnv)
+
+  // Bootstrap: user env (outer = coreEnv for implicit core access)
+  const userEnv = makeEnv(coreEnv)
+  userEnv.ns = makeNamespace('user')
+  registry.set('user', userEnv)
+
+  const runtime = buildRuntime(registry, coreEnv, options)
+  runtime.installModules([makeCoreModule(), makeJsModule()])
+  return runtime
+}
+
+// ---------------------------------------------------------------------------
+// restoreRuntime — re-wires a runtime from a snapshot.
+// The cloned registry already contains fully-evaluated namespaces (including
+// clojure.core), so no source bootstrap is needed. Only wiring is re-applied.
+// ---------------------------------------------------------------------------
+
+export function restoreRuntime(
+  snapshot: RuntimeSnapshot,
+  options?: RuntimeOptions
+): Runtime {
+  const registry = cloneRegistry(snapshot.registry)
+  const coreEnv = registry.get('clojure.core')!
+  const runtime = buildRuntime(registry, coreEnv, options)
+  // No module reinstallation needed — IO functions (println, print, etc.) read
+  // ctx.io.stdout at call time, so the snapshot's native functions automatically
+  // use the session's output channel without any rewiring.
+  return runtime
+}