@sqldoc/db 0.0.3

package/src/types.ts

@@ -0,0 +1,308 @@
+// ── Atlas WASI command/result types ─────────────────────────────────
+// Hand-crafted from atlas/cmd/atlas-wasi/marshal.go (cycle-free flat types).
+// Schema fields use lowercase json tags from the flat marshaler.
+// Attr variants (Tag, Comment, Check) use PascalCase from map[string]string.
+
+/**
+ * A known rename (from @docs.previously tags) to pass to Atlas before diffing.
+ */
+export interface AtlasRename {
+  type: 'column' | 'table'
+  table: string
+  oldName: string
+  newName: string
+}
+
+/**
+ * A potential rename detected by Atlas during diff (drop+add pair with same type).
+ */
+export interface AtlasRenameCandidate {
+  type: 'column' | 'table'
+  table: string
+  oldName: string
+  newName: string
+  colType?: string
+}
+
+/**
+ * Command sent to Atlas WASI module via stdin.
+ */
+export interface AtlasCommand {
+  type: 'inspect' | 'diff' | 'apply'
+  dialect: 'postgres' | 'mysql' | 'sqlite'
+  schema?: string
+  files?: string[]
+  fileNames?: string[]
+  from?: string[]
+  to?: string[]
+  fromConnection?: string
+  toConnection?: string
+  renames?: AtlasRename[]
+}
+
+/**
+ * A structured schema change description returned from Atlas diff.
+ */
+export interface AtlasChange {
+  type:
+    | 'add_table'
+    | 'drop_table'
+    | 'rename_table'
+    | 'add_column'
+    | 'drop_column'
+    | 'rename_column'
+    | 'modify_column'
+    | 'add_index'
+    | 'drop_index'
+    | 'add_view'
+    | 'drop_view'
+    | 'add_function'
+    | 'drop_function'
+  table: string
+  name?: string
+  detail?: string
+}
+
+/**
+ * Result returned from Atlas WASI module via stdout.
+ * Top-level fields use lowercase json tags.
+ */
+export interface AtlasResult {
+  schema?: AtlasRealm
+  statements?: string[]
+  changes?: AtlasChange[]
+  renameCandidates?: AtlasRenameCandidate[]
+  error?: string
+}
+
+// ── Schema types — lowercase (json tags in marshal.go flat types) ───
+
+/**
+ * A Realm describes a domain of schema resources (physical database instance).
+ * Maps to flatRealm in marshal.go.
+ */
+export interface AtlasRealm {
+  schemas: AtlasSchema[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Schema describes a named database schema (e.g. "public").
+ * Maps to flatSchema in marshal.go.
+ */
+export interface AtlasSchema {
+  name: string
+  tables?: AtlasTable[]
+  views?: AtlasView[]
+  funcs?: AtlasFunc[]
+  procs?: AtlasProc[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Table represents a table definition.
+ * Maps to flatTable in marshal.go.
+ */
+export interface AtlasTable {
+  name: string
+  columns?: AtlasColumn[]
+  indexes?: AtlasIndex[]
+  primary_key?: AtlasIndex
+  foreign_keys?: AtlasForeignKey[]
+  attrs?: AtlasAttr[]
+  triggers?: AtlasTrigger[]
+}
+
+/**
+ * A Column represents a column definition.
+ * Maps to flatColumn in marshal.go.
+ */
+export interface AtlasColumn {
+  name: string
+  type?: AtlasColumnType
+  default?: AtlasExpr
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * ColumnType represents a column type.
+ * Maps to flatColumnType in marshal.go.
+ * The `T` field is the type name (e.g., "bigint", "text").
+ */
+export type TypeCategory =
+  | 'string'
+  | 'integer'
+  | 'float'
+  | 'decimal'
+  | 'boolean'
+  | 'time'
+  | 'binary'
+  | 'json'
+  | 'uuid'
+  | 'spatial'
+  | 'enum'
+  | 'composite'
+  | 'array'
+  | 'unknown'
+
+export interface AtlasColumnType {
+  T?: string
+  raw?: string
+  null?: boolean
+  /** Normalized type category — dialect-independent */
+  category?: TypeCategory
+  /** Whether this is a user-defined type (enum, composite, domain) */
+  is_custom?: boolean
+  /** Enum values (when category is 'enum') */
+  enum_values?: string[]
+  /** Composite type fields (when category is 'composite') */
+  composite_fields?: Array<{ name: string; type: string }>
+}
+
+/**
+ * An Index represents an index definition.
+ * Maps to flatIndex in marshal.go.
+ */
+export interface AtlasIndex {
+  name?: string
+  unique?: boolean
+  parts?: AtlasIndexPart[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * An IndexPart represents a single part of an index.
+ * Maps to flatIndexPart in marshal.go.
+ */
+export interface AtlasIndexPart {
+  column?: string
+  desc?: boolean
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A ForeignKey represents a foreign key constraint.
+ * Maps to flatForeignKey in marshal.go.
+ */
+export interface AtlasForeignKey {
+  symbol?: string
+  columns?: string[]
+  ref_columns?: string[]
+  ref_table?: string
+  on_update?: string
+  on_delete?: string
+}
+
+/**
+ * A View represents a view definition.
+ * Maps to flatView in marshal.go.
+ */
+export interface AtlasView {
+  name: string
+  def?: string
+  columns?: AtlasColumn[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Func represents a function definition.
+ * Maps to flatFunc in marshal.go.
+ */
+export interface AtlasFunc {
+  name: string
+  args?: AtlasFuncArg[]
+  ret?: AtlasColumnType
+  lang?: string
+  attrs?: AtlasAttr[]
+}
+
+export interface AtlasFuncArg {
+  name?: string
+  type?: AtlasColumnType
+  mode?: string
+}
+
+/**
+ * A Proc represents a procedure definition.
+ * Maps to flatProc in marshal.go.
+ */
+export interface AtlasProc {
+  name: string
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Trigger represents a trigger definition.
+ * Maps to flatTrigger in marshal.go.
+ */
+export interface AtlasTrigger {
+  name: string
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * An expression in schema DDL.
+ * Go serializes RawExpr as { X: string }, Literal as { V: string }.
+ */
+export type AtlasExpr = { X: string } | { V: string } | unknown
+
+// ── Attr union — PascalCase (map[string]string in Go marshal) ───────
+
+/**
+ * Attrs is a heterogeneous array (Tag, Comment, Check all mixed).
+ * We model the known variants as a discriminated union with a fallback.
+ * Note: Attr fields use PascalCase (serialized via map[string]string in Go).
+ */
+export type AtlasAttr = AtlasTag | AtlasComment | AtlasCheck | Record<string, unknown>
+
+/**
+ * Tag attr. Serialized as { Name: string, Args: string }.
+ * PascalCase because Go marshal uses map[string]string{"Name": ..., "Args": ...}.
+ */
+export interface AtlasTag {
+  Name: string
+  Args: string
+}
+
+/**
+ * Comment attr. Serialized as { Text: string }.
+ */
+export interface AtlasComment {
+  Text: string
+}
+
+/**
+ * Check constraint attr. Serialized as { Name?: string, Expr: string }.
+ */
+export interface AtlasCheck {
+  Name?: string
+  Expr: string
+}
+
+// ── Helper functions ────────────────────────────────────────────────
+
+/**
+ * Type guard: returns true if the given attr is a Tag.
+ * Tags have `Name` and `Args` fields but NOT an `Expr` field
+ * (which would indicate a Check constraint instead).
+ */
+export function isTag(attr: AtlasAttr): attr is AtlasTag {
+  return (
+    typeof attr === 'object' &&
+    attr !== null &&
+    'Name' in attr &&
+    typeof (attr as AtlasTag).Name === 'string' &&
+    'Args' in attr &&
+    typeof (attr as AtlasTag).Args === 'string' &&
+    !('Expr' in attr)
+  )
+}
+
+/**
+ * Extract all Tag attrs from a mixed Attrs array.
+ * Returns an empty array if attrs is undefined or empty.
+ */
+export function findTags(attrs?: AtlasAttr[]): AtlasTag[] {
+  if (!attrs) return []
+  return attrs.filter(isTag)
+}

package/src/wasi-host.ts

@@ -0,0 +1,175 @@
+/**
+ * WASI module instantiation with custom atlas_sql host function import.
+ *
+ * Includes workarounds for Bun's WASI bugs:
+ *   1. FD_MAP ignores stdin/stdout/stderr constructor options
+ *   2. random_get returns byte count instead of errno 0
+ *   3. proc_exit calls process.exit() instead of throwing
+ */
+
+import * as crypto from 'node:crypto'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { WASI } from 'node:wasi'
+
+const isBun = typeof (globalThis as any).Bun !== 'undefined'
+
+/** Sentinel thrown by Bun proc_exit workaround */
+class WASIExitError {
+  code: number
+  constructor(code: number) {
+    this.code = code
+  }
+}
+
+/**
+ * Get WASI imports compatible with both Node.js and Bun.
+ */
+export function getWasiImports(wasi: WASI): Record<string, any> {
+  if (typeof (wasi as any).getImportObject === 'function') {
+    return (wasi as any).getImportObject()
+  }
+  if ((wasi as any).wasiImport) {
+    return { wasi_snapshot_preview1: (wasi as any).wasiImport }
+  }
+  throw new Error('Cannot get WASI imports: neither getImportObject() nor wasiImport available')
+}
+
+export interface WasiRunOptions {
+  stdinData: string
+  wasmPath: string
+  compiledModule?: WebAssembly.Module
+  atlasSqlFn: (reqPtr: number, reqLen: number, respPtr: number, respCap: number) => bigint | number
+  onInstance?: (instance: WebAssembly.Instance) => void
+}
+
+export interface WasiRunResult {
+  stdout: string
+  module: WebAssembly.Module
+}
+
+export async function runWasi(options: WasiRunOptions): Promise<WasiRunResult> {
+  const { stdinData, wasmPath, atlasSqlFn, onInstance } = options
+  const uid = crypto.randomUUID()
+  const tmpDir = os.tmpdir()
+  const stdinPath = path.join(tmpDir, `atlas-stdin-${uid}.json`)
+  const stdoutPath = path.join(tmpDir, `atlas-stdout-${uid}.json`)
+
+  let stdinFd: number | undefined
+  let stdoutFd: number | undefined
+
+  try {
+    fs.writeFileSync(stdinPath, stdinData)
+    fs.writeFileSync(stdoutPath, '')
+
+    stdinFd = fs.openSync(stdinPath, 'r')
+    stdoutFd = fs.openSync(stdoutPath, 'w')
+
+    const wasi = new WASI({
+      version: 'preview1',
+      stdin: stdinFd,
+      stdout: stdoutFd,
+      returnOnExit: true,
+    })
+
+    // Bun bug #1: FD_MAP ignores constructor options
+    if (isBun) {
+      const fdMap: Map<number, any> = (wasi as any).FD_MAP
+      if (fdMap) {
+        const fd0 = fdMap.get(0)
+        if (fd0) fd0.real = stdinFd
+        const fd1 = fdMap.get(1)
+        if (fd1) fd1.real = stdoutFd
+        const fd2 = fdMap.get(2)
+        if (fd2) fd2.real = 2
+      }
+    }
+
+    // Compile module (or reuse cached)
+    let wasmModule = options.compiledModule
+    if (!wasmModule) {
+      const wasmBytes = fs.readFileSync(wasmPath)
+      wasmModule = await WebAssembly.compile(wasmBytes)
+    }
+
+    // Build imports
+    const wasiImports = getWasiImports(wasi)
+    let instanceRef: WebAssembly.Instance | undefined
+
+    if (isBun && wasiImports.wasi_snapshot_preview1) {
+      // Bun bug #2: random_get returns byte count instead of errno 0
+      wasiImports.wasi_snapshot_preview1.random_get = (bufPtr: number, bufLen: number) => {
+        if (instanceRef) {
+          const mem = instanceRef.exports.memory as WebAssembly.Memory
+          const view = new Uint8Array(mem.buffer, bufPtr, bufLen)
+          crypto.getRandomValues(view)
+        }
+        return 0
+      }
+
+      // Bun bug #3: proc_exit calls process.exit()
+      wasiImports.wasi_snapshot_preview1.proc_exit = (code: number) => {
+        throw new WASIExitError(code)
+      }
+    }
+
+    const imports = {
+      ...wasiImports,
+      env: { atlas_sql: atlasSqlFn },
+    }
+
+    // Instantiate
+    const instance = await WebAssembly.instantiate(wasmModule, imports)
+    instanceRef = instance
+
+    if (isBun && typeof (wasi as any).setMemory === 'function') {
+      ;(wasi as any).setMemory(instance.exports.memory)
+    }
+
+    if (onInstance) {
+      onInstance(instance)
+    }
+
+    // Run
+    try {
+      if (isBun) {
+        ;(instance.exports._start as Function)()
+      } else {
+        wasi.start(instance)
+      }
+    } catch (err: unknown) {
+      if (err instanceof WASIExitError) {
+        // Bun sentinel — non-zero exit is fine, we read stdout for error JSON
+      } else {
+        // Node: returnOnExit throws on non-zero exit code
+        const isExitError = err instanceof Error && ('code' in err || err.message.includes('exit'))
+        if (!isExitError) throw err
+      }
+    }
+
+    // Close fds before reading stdout
+    fs.closeSync(stdinFd)
+    stdinFd = undefined
+    fs.closeSync(stdoutFd)
+    stdoutFd = undefined
+
+    const stdout = fs.readFileSync(stdoutPath, 'utf-8')
+    return { stdout, module: wasmModule }
+  } finally {
+    if (stdinFd !== undefined)
+      try {
+        fs.closeSync(stdinFd)
+      } catch {}
+    if (stdoutFd !== undefined)
+      try {
+        fs.closeSync(stdoutFd)
+      } catch {}
+    try {
+      fs.unlinkSync(stdinPath)
+    } catch {}
+    try {
+      fs.unlinkSync(stdoutPath)
+    } catch {}
+  }
+}

package/src/worker.ts

@@ -0,0 +1,106 @@
+/**
+ * Worker thread entry point for Atlas WASI execution.
+ *
+ * This file runs inside a node:worker_threads Worker. It:
+ * 1. Receives initialization data via workerData
+ * 2. Creates the atlas_sql callback using SharedArrayBuffer + Atomics
+ * 3. Runs the WASI module with the stdin data
+ * 4. Posts the stdout result back to the parent
+ *
+ * The atlas_sql callback bridges synchronous WASM calls to the main thread's
+ * async database adapter using Atomics.wait (blocking on the worker thread).
+ */
+
+import { parentPort, workerData } from 'node:worker_threads'
+import { type BridgeBuffers, bridgeRequest, SIGNAL_DONE } from './bridge.ts'
+import { runWasi } from './wasi-host.ts'
+
+interface WorkerInit {
+  wasmPath: string
+  controlBuffer: SharedArrayBuffer
+  dataBuffer: SharedArrayBuffer
+  stdinData: string
+}
+
+const { wasmPath, controlBuffer, dataBuffer, stdinData } = workerData as WorkerInit
+
+const buffers: BridgeBuffers = {
+  control: controlBuffer,
+  data: dataBuffer,
+}
+
+// WASM instance memory -- set via onInstance before wasi.start()
+let wasmMemory: WebAssembly.Memory | null = null
+
+/**
+ * The atlas_sql host function that bridges sync WASM calls
+ * to the main thread via SharedArrayBuffer + Atomics.
+ *
+ * Signature matches Go's //go:wasmimport env atlas_sql:
+ *   (reqPtr, reqLen, respPtr, respCap) => int64
+ *
+ * Negative return = buffer too small (abs value = needed size).
+ * Positive return = actual response length written.
+ */
+function atlasSql(reqPtr: number, reqLen: number, respPtr: number, respCap: number): bigint {
+  if (!wasmMemory) {
+    throw new Error('WASM memory not yet available in atlas_sql callback')
+  }
+
+  // 1. Read request JSON from WASM memory
+  const reqBytes = new Uint8Array(wasmMemory.buffer, reqPtr, reqLen)
+  const requestJson = new TextDecoder().decode(reqBytes.slice())
+
+  // 2. Send request to main thread via bridge and block until response
+  const responseJson = bridgeRequest(buffers, requestJson)
+
+  // 3. Encode response and check capacity
+  const respEncoded = new TextEncoder().encode(responseJson)
+
+  if (respEncoded.byteLength > respCap) {
+    return BigInt(-respEncoded.byteLength)
+  }
+
+  // 4. Copy response into WASM memory
+  const wasmResp = new Uint8Array(wasmMemory.buffer, respPtr, respCap)
+  wasmResp.set(respEncoded)
+
+  return BigInt(respEncoded.byteLength)
+}
+
+async function main(): Promise<void> {
+  if (!parentPort) {
+    throw new Error('worker.ts must run inside a worker thread')
+  }
+
+  try {
+    const result = await runWasi({
+      stdinData,
+      wasmPath,
+      atlasSqlFn: atlasSql,
+      onInstance(instance) {
+        // Capture WASM memory before execution starts.
+        // atlas_sql will use this to read requests from / write responses to WASM memory.
+        wasmMemory = instance.exports.memory as WebAssembly.Memory
+      },
+    })
+
+    // Signal main thread that WASI execution is done
+    const control = new Int32Array(buffers.control)
+    Atomics.store(control, 0, SIGNAL_DONE)
+    Atomics.notify(control, 0)
+
+    // Post result back
+    parentPort.postMessage({ type: 'result', stdout: result.stdout })
+  } catch (err: unknown) {
+    // Signal done even on error
+    const control = new Int32Array(buffers.control)
+    Atomics.store(control, 0, SIGNAL_DONE)
+    Atomics.notify(control, 0)
+
+    const message = err instanceof Error ? err.message : String(err)
+    parentPort.postMessage({ type: 'error', error: message })
+  }
+}
+
+main()