@sqldoc/atlas 0.0.1

package/src/__tests__/types.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { type AtlasAttr, type AtlasCheck, type AtlasComment, type AtlasTag, findTags, isTag } from '../types'
+
+describe('isTag', () => {
+  it('returns true for a valid Tag attr', () => {
+    const tag: AtlasTag = { Name: 'pii.mask', Args: '' }
+    expect(isTag(tag)).toBe(true)
+  })
+
+  it('returns true for a Tag with non-empty Args', () => {
+    const tag: AtlasTag = { Name: 'audit.track', Args: 'on: [delete, update]' }
+    expect(isTag(tag)).toBe(true)
+  })
+
+  it('returns false for a Comment attr', () => {
+    const comment: AtlasComment = { Text: 'User account table' }
+    expect(isTag(comment)).toBe(false)
+  })
+
+  it('returns false for a Check attr (has Name AND Expr)', () => {
+    const check: AtlasCheck = { Name: 'email_check', Expr: "email LIKE '%@%'" }
+    expect(isTag(check)).toBe(false)
+  })
+
+  it('returns false for an unknown Record attr', () => {
+    const unknown: Record<string, unknown> = { Filename: 'schema.sql', Start: { Line: 1 } }
+    expect(isTag(unknown)).toBe(false)
+  })
+
+  it('returns false for null', () => {
+    expect(isTag(null as unknown as AtlasAttr)).toBe(false)
+  })
+
+  it('returns false for a non-object', () => {
+    expect(isTag('string' as unknown as AtlasAttr)).toBe(false)
+  })
+})
+
+describe('findTags', () => {
+  it('returns empty array for undefined attrs', () => {
+    expect(findTags(undefined)).toEqual([])
+  })
+
+  it('returns empty array for empty attrs', () => {
+    expect(findTags([])).toEqual([])
+  })
+
+  it('extracts only Tags from a mixed Attr array', () => {
+    const attrs: AtlasAttr[] = [
+      { Name: 'pii.mask', Args: '' },
+      { Text: 'User email address' },
+      { Name: 'gql.filter', Args: '' },
+      { Name: 'email_check', Expr: "email LIKE '%@%'" },
+      { Filename: 'schema.sql', Start: { Line: 5 } },
+      { Name: 'gql.order', Args: 'asc' },
+    ]
+
+    const tags = findTags(attrs)
+    expect(tags).toHaveLength(3)
+    expect(tags[0]).toEqual({ Name: 'pii.mask', Args: '' })
+    expect(tags[1]).toEqual({ Name: 'gql.filter', Args: '' })
+    expect(tags[2]).toEqual({ Name: 'gql.order', Args: 'asc' })
+  })
+
+  it('returns all items when all are Tags', () => {
+    const attrs: AtlasAttr[] = [
+      { Name: 'ns.a', Args: 'x' },
+      { Name: 'ns.b', Args: '' },
+    ]
+    expect(findTags(attrs)).toHaveLength(2)
+  })
+
+  it('returns empty array when no Tags present', () => {
+    const attrs: AtlasAttr[] = [{ Text: 'A comment' }, { Name: 'chk', Expr: 'id > 0' }]
+    expect(findTags(attrs)).toHaveLength(0)
+  })
+})

package/src/__tests__/wasi-compat.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { getWasiImports } from '../wasi-host'
+
+describe('getWasiImports', () => {
+  it('uses getImportObject when available (Node.js API)', () => {
+    const mockWasi = {
+      getImportObject: () => ({
+        wasi_snapshot_preview1: { fd_write: () => {} },
+      }),
+    }
+    const result = getWasiImports(mockWasi as any)
+    expect(result).toHaveProperty('wasi_snapshot_preview1')
+    expect(result.wasi_snapshot_preview1).toHaveProperty('fd_write')
+  })
+
+  it('uses wasiImport when getImportObject is missing (Bun API)', () => {
+    const mockWasi = {
+      wasiImport: { fd_write: () => {}, fd_read: () => {} },
+    }
+    const result = getWasiImports(mockWasi as any)
+    expect(result).toHaveProperty('wasi_snapshot_preview1')
+    expect(result.wasi_snapshot_preview1).toHaveProperty('fd_write')
+    expect(result.wasi_snapshot_preview1).toHaveProperty('fd_read')
+  })
+
+  it('prefers getImportObject over wasiImport when both exist', () => {
+    const mockWasi = {
+      getImportObject: () => ({
+        wasi_snapshot_preview1: { from_getImportObject: true },
+      }),
+      wasiImport: { from_wasiImport: true },
+    }
+    const result = getWasiImports(mockWasi as any)
+    expect(result.wasi_snapshot_preview1).toHaveProperty('from_getImportObject')
+  })
+
+  it('throws when neither API is available', () => {
+    const mockWasi = {}
+    expect(() => getWasiImports(mockWasi as any)).toThrow('Cannot get WASI imports')
+  })
+})

package/src/bridge.ts

@@ -0,0 +1,152 @@
+/**
+ * Sync/async bridge for atlas_sql host function.
+ *
+ * Architecture:
+ * - Worker thread runs WASI module, calls atlas_sql synchronously
+ * - atlas_sql writes SQL request to shared buffer, signals main thread, blocks via Atomics.wait
+ * - Main thread receives request, runs async DB query, writes response, signals via Atomics.notify
+ *
+ * Control buffer layout (Int32Array over SharedArrayBuffer):
+ *   [0] = signal: 0=idle, 1=request_ready, 2=response_ready, 3=done
+ *   [1] = data length (request or response)
+ */
+
+// Signal constants
+export const SIGNAL_IDLE = 0
+export const SIGNAL_REQUEST = 1
+export const SIGNAL_RESPONSE = 2
+export const SIGNAL_DONE = 3
+
+/**
+ * Shared buffers passed between main and worker thread.
+ */
+export interface BridgeBuffers {
+  /** 8 bytes: signal (Int32) + data length (Int32) */
+  control: SharedArrayBuffer
+  /** Data exchange buffer (default 1MB, resizable) */
+  data: SharedArrayBuffer
+}
+
+/**
+ * Create shared buffers for bridge communication.
+ * @param dataSize Initial data buffer size in bytes (default 1MB)
+ */
+export function createBridgeBuffers(dataSize = 1024 * 1024): BridgeBuffers {
+  return {
+    control: new SharedArrayBuffer(8),
+    data: new SharedArrayBuffer(dataSize),
+  }
+}
+
+// ── Worker-side (synchronous) ───────────────────────────────────────
+
+/**
+ * Write a request to the shared buffer and block until a response is available.
+ * Called from the worker thread inside the atlas_sql host function.
+ *
+ * @returns Response JSON string
+ */
+export function bridgeRequest(buffers: BridgeBuffers, requestJson: string): string {
+  const control = new Int32Array(buffers.control)
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+
+  // Write request to data buffer
+  const encoded = encoder.encode(requestJson)
+  if (encoded.byteLength > buffers.data.byteLength) {
+    throw new Error(`Bridge request too large: ${encoded.byteLength} bytes > ${buffers.data.byteLength} buffer`)
+  }
+  new Uint8Array(buffers.data).set(encoded)
+
+  // Store length and signal request ready
+  Atomics.store(control, 1, encoded.byteLength)
+  Atomics.store(control, 0, SIGNAL_REQUEST)
+  Atomics.notify(control, 0)
+
+  // Block until response is ready (value changes from SIGNAL_REQUEST)
+  Atomics.wait(control, 0, SIGNAL_REQUEST)
+
+  // Read response
+  const signal = Atomics.load(control, 0)
+  if (signal === SIGNAL_DONE) {
+    throw new Error('Bridge terminated while waiting for response')
+  }
+
+  const respLen = Atomics.load(control, 1)
+  const respBytes = new Uint8Array(buffers.data, 0, respLen)
+  const response = decoder.decode(respBytes.slice())
+
+  // Reset signal to idle for next round-trip
+  Atomics.store(control, 0, SIGNAL_IDLE)
+
+  return response
+}
+
+// ── Main-thread side (asynchronous) ─────────────────────────────────
+
+/**
+ * Wait for the worker to post a request. Uses Atomics.waitAsync
+ * (non-blocking on the main thread).
+ *
+ * @returns The current signal value after waking
+ */
+export async function bridgeWaitForSignal(buffers: BridgeBuffers): Promise<number> {
+  const control = new Int32Array(buffers.control)
+
+  // If signal is already non-idle, return immediately
+  const current = Atomics.load(control, 0)
+  if (current !== SIGNAL_IDLE) {
+    return current
+  }
+
+  // Wait asynchronously for signal to change from IDLE
+  const result = Atomics.waitAsync(control, 0, SIGNAL_IDLE)
+  if (result.async) {
+    await result.value
+  }
+  return Atomics.load(control, 0)
+}
+
+/**
+ * Read the request JSON from the shared data buffer.
+ * Call after bridgeWaitForSignal returns SIGNAL_REQUEST.
+ */
+export function bridgeReadRequest(buffers: BridgeBuffers): string {
+  const control = new Int32Array(buffers.control)
+  const reqLen = Atomics.load(control, 1)
+  const reqBytes = new Uint8Array(buffers.data, 0, reqLen)
+  return new TextDecoder().decode(reqBytes.slice())
+}
+
+/**
+ * Write a response to the shared buffer and notify the worker.
+ */
+export function bridgeRespond(buffers: BridgeBuffers, responseJson: string): void {
+  const control = new Int32Array(buffers.control)
+  const encoded = new TextEncoder().encode(responseJson)
+
+  if (encoded.byteLength > buffers.data.byteLength) {
+    // Write an error response instead -- the data buffer is too small
+    const errorResp = JSON.stringify({
+      error: `Response too large: ${encoded.byteLength} bytes exceeds ${buffers.data.byteLength} byte buffer`,
+    })
+    const errorEncoded = new TextEncoder().encode(errorResp)
+    new Uint8Array(buffers.data).set(errorEncoded)
+    Atomics.store(control, 1, errorEncoded.byteLength)
+  } else {
+    new Uint8Array(buffers.data).set(encoded)
+    Atomics.store(control, 1, encoded.byteLength)
+  }
+
+  Atomics.store(control, 0, SIGNAL_RESPONSE)
+  Atomics.notify(control, 0)
+}
+
+/**
+ * Signal the worker that processing is done (no more commands).
+ */
+export function bridgeSignalDone(buffers: BridgeBuffers): void {
+  const control = new Int32Array(buffers.control)
+  Atomics.store(control, 0, SIGNAL_DONE)
+  Atomics.notify(control, 0)
+}

package/src/db/docker.ts

@@ -0,0 +1,91 @@
+import * as path from 'node:path'
+import { PostgreSqlContainer } from '@testcontainers/postgresql'
+import { GenericContainer, Wait } from 'testcontainers'
+import { createPostgresAdapter } from './postgres.ts'
+import type { DatabaseAdapter } from './types.ts'
+
+/**
+ * Create a Docker-based DatabaseAdapter using testcontainers.
+ * Spins up an ephemeral Postgres container, connects via pg, and
+ * automatically cleans up on close() (testcontainers + Ryuk handle
+ * orphan cleanup even on process crash).
+ *
+ * Supports:
+ *   docker://postgres:16        — official or custom image
+ *   dockerfile://path/to/file   — build from Dockerfile
+ */
+export async function createDockerAdapter(devUrl: string): Promise<DatabaseAdapter> {
+  if (devUrl.startsWith('dockerfile://')) {
+    return createFromDockerfile(devUrl.slice('dockerfile://'.length))
+  }
+
+  // docker://image:tag
+  const imageName = devUrl.slice('docker://'.length)
+  const container = await new PostgreSqlContainer(imageName)
+    .withDatabase('sqldoc_dev')
+    .withUsername('sqldoc')
+    .withPassword('sqldoc')
+    .withExposedPorts(5432)
+    .withWaitStrategy(Wait.forLogMessage('database system is ready to accept connections', 2))
+    .start()
+
+  const pgAdapter = await createPostgresAdapter(container.getConnectionUri())
+
+  return {
+    query: pgAdapter.query,
+    exec: pgAdapter.exec,
+    async close() {
+      await pgAdapter.close()
+      await container.stop()
+    },
+  }
+}
+
+async function createFromDockerfile(dockerfilePath: string): Promise<DatabaseAdapter> {
+  const absPath = path.resolve(dockerfilePath)
+  const dir = path.dirname(absPath)
+  const file = path.basename(absPath)
+
+  const image = await GenericContainer.fromDockerfile(dir, file).build()
+
+  const container = await image
+    .withEnvironment({
+      POSTGRES_DB: 'sqldoc_dev',
+      POSTGRES_USER: 'sqldoc',
+      POSTGRES_PASSWORD: 'sqldoc',
+    })
+    .withExposedPorts(5432)
+    .withWaitStrategy(Wait.forLogMessage('database system is ready to accept connections', 2))
+    .withStartupTimeout(30_000)
+    .start()
+
+  // Wait for postgres to accept connections
+  const host = container.getHost()
+  const port = container.getMappedPort(5432)
+  const connectionUri = `postgres://sqldoc:sqldoc@${host}:${port}/sqldoc_dev`
+
+  // Retry connection — container may need a moment after port is mapped
+  let pgAdapter: DatabaseAdapter | undefined
+  for (let i = 0; i < 10; i++) {
+    try {
+      pgAdapter = await createPostgresAdapter(connectionUri)
+      break
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+    }
+  }
+
+  if (!pgAdapter) {
+    await container.stop()
+    throw new Error(`Failed to connect to Docker Postgres at ${connectionUri}`)
+  }
+
+  return {
+    query: pgAdapter.query,
+    exec: pgAdapter.exec,
+    async close() {
+      await pgAdapter.close()
+      await container.stop()
+    },
+  }
+}

package/src/db/pglite.ts

@@ -0,0 +1,77 @@
+import { PGlite } from '@electric-sql/pglite'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize a row value to a type the Go database/sql driver can scan.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Date) return val.toISOString()
+  if (typeof val === 'object') {
+    return JSON.stringify(val, (_k, v) => (typeof v === 'bigint' ? v.toString() : v))
+  }
+  return val
+}
+
+/**
+ * Dynamically load a pglite extension.
+ * Tries @electric-sql/pglite/contrib/{name} first (most extensions),
+ * then @electric-sql/pglite/{name} (built-in extensions like live).
+ * Returns the extension object or null if not available.
+ */
+async function loadPgliteExtension(name: string): Promise<any | null> {
+  // Try contrib first (most extensions live here)
+  try {
+    const mod = await import(`@electric-sql/pglite/contrib/${name}`)
+    return mod.default ?? mod[name] ?? mod
+  } catch {
+    /* not in contrib */
+  }
+
+  // Try top-level (built-in extensions like live, vector)
+  try {
+    const mod = await import(`@electric-sql/pglite/${name}`)
+    return mod.default ?? mod[name] ?? mod
+  } catch {
+    /* not available */
+  }
+
+  return null
+}
+
+/**
+ * Create a pglite-based DatabaseAdapter (in-memory, zero-config).
+ * Optionally loads extensions from @electric-sql/pglite/contrib.
+ */
+export async function createPgliteAdapter(extensions?: string[]): Promise<DatabaseAdapter> {
+  const extModules: Record<string, any> = {}
+  for (const ext of extensions ?? []) {
+    const mod = await loadPgliteExtension(ext)
+    if (mod) {
+      extModules[ext] = mod
+    }
+  }
+
+  const db = await PGlite.create({
+    extensions: Object.keys(extModules).length > 0 ? extModules : undefined,
+  })
+
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      const result = await db.query(sql, args, { rowMode: 'array' })
+      return {
+        columns: result.fields.map((f: { name: string }) => f.name),
+        rows: (result.rows as unknown[][]).map((row) => row.map(normalizeValue)),
+      }
+    },
+    async exec(sql: string): Promise<ExecResult> {
+      const result = await db.exec(sql)
+      const last = result[result.length - 1]
+      return { rowsAffected: last?.affectedRows ?? 0 }
+    },
+    async close(): Promise<void> {
+      await db.close()
+    },
+  }
+}

package/src/db/postgres.ts

@@ -0,0 +1,44 @@
+import { Client } from 'pg'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize row values to types the Go database/sql driver can scan.
+ * The WASI JSON protocol expects strings, numbers, booleans, and null.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Date) return val.toISOString()
+  if (Buffer.isBuffer(val)) return val.toString('hex')
+  if (typeof val === 'object') {
+    return JSON.stringify(val, (_k, v) => (typeof v === 'bigint' ? v.toString() : v))
+  }
+  return val
+}
+
+/**
+ * Create a postgres-based DatabaseAdapter using the pg library.
+ * Connects to an external Postgres instance via connection string.
+ */
+export async function createPostgresAdapter(connectionString: string): Promise<DatabaseAdapter> {
+  const client = new Client({ connectionString })
+  await client.connect()
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      // Use rowMode: 'array' to get positional values, not name-keyed objects.
+      // This handles duplicate column names (e.g. multiple current_setting() calls).
+      const result = await client.query({ text: sql, values: args, rowMode: 'array' })
+      return {
+        columns: result.fields.map((f: { name: string }) => f.name),
+        rows: (result.rows as unknown[][]).map((row) => row.map(normalizeValue)),
+      }
+    },
+    async exec(sql: string): Promise<ExecResult> {
+      const result = await client.query(sql)
+      return { rowsAffected: result.rowCount ?? 0 }
+    },
+    async close(): Promise<void> {
+      await client.end()
+    },
+  }
+}

package/src/db/types.ts

@@ -0,0 +1,26 @@
+/**
+ * DatabaseAdapter abstracts the database connection used by the Atlas WASI host.
+ * Both pglite (in-memory, zero-config) and pg (external Postgres) implement this.
+ */
+export interface DatabaseAdapter {
+  query(sql: string, args?: unknown[]): Promise<QueryResult>
+  exec(sql: string, args?: unknown[]): Promise<ExecResult>
+  close(): Promise<void>
+}
+
+/**
+ * Result of a SELECT-style query.
+ * Matches the WASI protocol Response shape for "query" requests.
+ */
+export interface QueryResult {
+  columns: string[]
+  rows: unknown[][]
+}
+
+/**
+ * Result of a DDL/DML execution.
+ * Matches the WASI protocol Response shape for "exec" requests.
+ */
+export interface ExecResult {
+  rowsAffected: number
+}

package/src/extensions.ts

@@ -0,0 +1,116 @@
+/**
+ * PostgreSQL extension detection and validation.
+ *
+ * Extracts CREATE EXTENSION names from SQL, validates against pglite
+ * or real Postgres, and provides helpful error messages.
+ */
+import { createRequire } from 'node:module'
+import pc from 'picocolors'
+
+/** Regex to extract extension names from CREATE EXTENSION statements */
+const CREATE_EXT_RE = /CREATE\s+EXTENSION\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|(\w[\w-]*))/gi
+
+/**
+ * Extract extension names from SQL strings.
+ * Handles both quoted and unquoted names, and hyphenated names like uuid-ossp.
+ */
+export function extractExtensions(
+  sqlFiles: string[],
+  filePaths?: string[],
+): { extensions: string[]; byFile: Map<string, string[]> } {
+  const all = new Set<string>()
+  const byFile = new Map<string, string[]>()
+  for (let i = 0; i < sqlFiles.length; i++) {
+    const sql = sqlFiles[i]
+    const file = filePaths?.[i] ?? `file${i}`
+    const lines = sql.split('\n')
+    for (const line of lines) {
+      // Skip commented-out lines
+      if (line.trimStart().startsWith('--')) continue
+      let match
+      CREATE_EXT_RE.lastIndex = 0
+      while ((match = CREATE_EXT_RE.exec(line)) !== null) {
+        const name = (match[1] ?? match[2]).toLowerCase().replace(/-/g, '_')
+        all.add(name)
+        const existing = byFile.get(name) ?? []
+        existing.push(file)
+        byFile.set(name, existing)
+      }
+    }
+  }
+  return { extensions: [...all], byFile }
+}
+
+/**
+ * Validate extensions for pglite by attempting to import them.
+ * Returns the list of extensions that are available.
+ * Throws with a pretty error if any are not available.
+ */
+export async function validatePgliteExtensions(requested: string[]): Promise<string[]> {
+  if (requested.length === 0) return []
+
+  // Resolve from this package's directory (pglite is a dep of @sqldoc/atlas)
+  const req = createRequire(import.meta.url)
+
+  const results: Array<{ name: string; available: boolean }> = []
+
+  for (const ext of requested) {
+    let found = false
+    try {
+      req.resolve(`@electric-sql/pglite/contrib/${ext}`)
+      found = true
+    } catch {}
+    if (!found)
+      try {
+        req.resolve(`@electric-sql/pglite/${ext}`)
+        found = true
+      } catch {}
+    results.push({ name: ext, available: found })
+  }
+
+  const unavailable = results.filter((r) => !r.available)
+  if (unavailable.length > 0) {
+    const lines = results.map((r) => (r.available ? pc.green(`  ✓ ${r.name}`) : pc.red(`  ✗ ${r.name}`)))
+
+    throw new Error(
+      `Some extensions are not available for the embedded postgres database:\n${lines.join('\n')}\n\n` +
+        `Use a Docker image with these extensions installed as devUrl:\n` +
+        `  ${pc.cyan('docker://<image>')}        — use an image that includes the extension\n` +
+        `  ${pc.cyan('dockerfile://path')}       — build a custom Dockerfile with the extension`,
+    )
+  }
+
+  return requested
+}
+
+/**
+ * Validate extensions against a real Postgres database.
+ * Queries pg_available_extensions to check availability.
+ */
+export async function validatePostgresExtensions(
+  requested: string[],
+  queryFn: (sql: string) => Promise<{ rows: unknown[][] }>,
+): Promise<void> {
+  if (requested.length === 0) return
+
+  const result = await queryFn(
+    'SELECT name FROM pg_available_extensions WHERE name = ANY(ARRAY[' +
+      requested.map((e) => `'${e}'`).join(',') +
+      '])',
+  )
+
+  const available = new Set(result.rows.map((r) => String(r[0])))
+
+  const missing = requested.filter((e) => !available.has(e))
+  if (missing.length > 0) {
+    const lines = requested.map((ext) => {
+      const ok = available.has(ext)
+      return ok ? pc.green(`  ✓ ${ext}`) : pc.red(`  ✗ ${ext}`)
+    })
+
+    throw new Error(
+      `Some required extensions are not available on this database:\n${lines.join('\n')}\n\n` +
+        `Install the missing extensions or use a Docker image that includes them.`,
+    )
+  }
+}