@sqldoc/cli 0.0.1

package/src/utils/destructive.ts

@@ -0,0 +1,99 @@
+/**
+ * Detect destructive SQL statements in migration diff output.
+ *
+ * Scans individual SQL statements for patterns that would destroy data:
+ * - DROP TABLE
+ * - ALTER TABLE ... DROP COLUMN
+ * - DROP INDEX
+ * - DROP VIEW
+ * - DROP FUNCTION
+ * - TRUNCATE
+ */
+
+export interface DestructiveChange {
+  /** Human-readable description of the destructive change */
+  description: string
+  /** The full SQL statement */
+  statement: string
+}
+
+/**
+ * Scan an array of SQL statements for destructive operations.
+ * Returns a list of destructive changes found (empty if none).
+ */
+export function detectDestructiveChanges(statements: string[]): DestructiveChange[] {
+  const changes: DestructiveChange[] = []
+
+  for (const stmt of statements) {
+    // Normalize whitespace but preserve original case for names
+    const normalized = stmt.replace(/\s+/g, ' ').trim()
+
+    // DROP TABLE
+    const dropTable = normalized.match(/DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?("?[\w.]+"?)/i)
+    if (dropTable) {
+      changes.push({
+        description: `DROP TABLE ${unquote(dropTable[1])}`,
+        statement: stmt,
+      })
+      continue
+    }
+
+    // ALTER TABLE ... DROP COLUMN
+    const dropColumn = normalized.match(
+      /ALTER\s+TABLE\s+(?:ONLY\s+)?("?[\w.]+"?)\s+DROP\s+COLUMN\s+(?:IF\s+EXISTS\s+)?("?[\w.]+"?)/i,
+    )
+    if (dropColumn) {
+      changes.push({
+        description: `ALTER TABLE ${unquote(dropColumn[1])} DROP COLUMN ${unquote(dropColumn[2])}`,
+        statement: stmt,
+      })
+      continue
+    }
+
+    // DROP INDEX
+    const dropIndex = normalized.match(/DROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?("?[\w.]+"?)/i)
+    if (dropIndex) {
+      changes.push({
+        description: `DROP INDEX ${unquote(dropIndex[1])}`,
+        statement: stmt,
+      })
+      continue
+    }
+
+    // DROP VIEW
+    const dropView = normalized.match(/DROP\s+VIEW\s+(?:IF\s+EXISTS\s+)?("?[\w.]+"?)/i)
+    if (dropView) {
+      changes.push({
+        description: `DROP VIEW ${unquote(dropView[1])}`,
+        statement: stmt,
+      })
+      continue
+    }
+
+    // DROP FUNCTION
+    const dropFunction = normalized.match(/DROP\s+FUNCTION\s+(?:IF\s+EXISTS\s+)?("?[\w.]+"?)/i)
+    if (dropFunction) {
+      changes.push({
+        description: `DROP FUNCTION ${unquote(dropFunction[1])}`,
+        statement: stmt,
+      })
+      continue
+    }
+
+    // TRUNCATE
+    const truncate = normalized.match(/TRUNCATE\s+(?:TABLE\s+)?("?[\w.]+"?)/i)
+    if (truncate) {
+      changes.push({
+        description: `TRUNCATE ${unquote(truncate[1])}`,
+        statement: stmt,
+      })
+    }
+  }
+
+  return changes
+}
+
+/** Remove surrounding double quotes from an identifier */
+function unquote(name: string): string {
+  return name.replace(/^"(.*)"$/, '$1')
+}

package/src/utils/discover.ts

@@ -0,0 +1,35 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import fg from 'fast-glob'
+
+/**
+ * Discover SQL files from a path. If inputPath is a .sql file, returns it directly.
+ * If a directory, globs for SQL files within it.
+ * Returns absolute paths sorted lexicographically for deterministic ordering.
+ */
+export async function discoverSqlFiles(inputPath: string, includePatterns?: string[]): Promise<string[]> {
+  const resolved = path.resolve(inputPath)
+
+  // Single file
+  if (resolved.endsWith('.sql')) {
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`SQL file not found: ${resolved}`)
+    }
+    return [resolved]
+  }
+
+  // Directory
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(`Path is not a file or directory: ${resolved}`)
+  }
+
+  const patterns = includePatterns ?? ['**/*.sql']
+  const files = await fg(patterns, {
+    cwd: resolved,
+    absolute: true,
+    onlyFiles: true,
+    ignore: ['**/node_modules/**', '**/__tests__/**', '**/test/**', '**/*.test.*', '**/dist/**', '**/.sqldoc/**'],
+  })
+
+  return files.sort()
+}

package/src/utils/format.ts

@@ -0,0 +1,23 @@
+import type { Diagnostic } from '@sqldoc/core'
+import pc from 'picocolors'
+
+/**
+ * Format a diagnostic for terminal display.
+ * Output: filePath:line:col: severity: message
+ * Lines and columns are 1-based for editor compatibility.
+ */
+export function formatDiagnostic(filePath: string, d: Diagnostic): string {
+  const location = `${filePath}:${d.line + 1}:${d.startCol + 1}`
+  const severity =
+    d.severity === 'error' ? pc.red(d.severity) : d.severity === 'warning' ? pc.yellow(d.severity) : pc.blue(d.severity)
+  return `${location}: ${severity}: ${d.message}`
+}
+
+/**
+ * Format a summary line with error and warning counts.
+ */
+export function formatSummary(errorCount: number, warningCount: number): string {
+  const errors = errorCount > 0 ? pc.red(`${errorCount} error(s)`) : `${errorCount} error(s)`
+  const warnings = warningCount > 0 ? pc.yellow(`${warningCount} warning(s)`) : `${warningCount} warning(s)`
+  return `${errors}, ${warnings}`
+}

package/src/utils/generate-config-types.ts

@@ -0,0 +1,73 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/**
+ * Scan .sqldoc/node_modules for installed @sqldoc namespace plugins,
+ * and generate .sqldoc/config.d.ts with a typed SqldocConfig interface.
+ *
+ * Base config fields are imported from @sqldoc/core so they stay in sync.
+ * Only the namespaces block is generated based on installed plugins.
+ */
+export function generateConfigTypes(sqldocDir: string): void {
+  const nodeModules = path.join(sqldocDir, 'node_modules', '@sqldoc')
+  if (!fs.existsSync(nodeModules)) return
+
+  const imports: string[] = ["import type { ProjectConfig as BaseProjectConfig } from '@sqldoc/core'"]
+  const namespaceFields: string[] = []
+
+  const dirs = fs.readdirSync(nodeModules).sort()
+  for (const dir of dirs) {
+    if (!dir.startsWith('ns-')) continue
+
+    const pkgPath = path.join(nodeModules, dir)
+    const pkgJsonPath = path.join(pkgPath, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) continue
+
+    const nsName = dir.replace('ns-', '')
+    const pkgName = `@sqldoc/${dir}`
+
+    const configTypeName = findConfigTypeName(pkgPath, nsName)
+
+    if (configTypeName) {
+      imports.push(`import type { ${configTypeName} } from '${pkgName}'`)
+      namespaceFields.push(`    ${nsName}?: Partial<${configTypeName}>`)
+    } else {
+      namespaceFields.push(`    ${nsName}?: Record<string, unknown>`)
+    }
+  }
+
+  const namespacesBlock =
+    namespaceFields.length > 0
+      ? `  namespaces?: {
+${namespaceFields.join('\n')}
+  }`
+      : `  namespaces?: Record<string, Record<string, unknown>>`
+
+  const content = `// Auto-generated by sqldoc -- DO NOT EDIT
+// Regenerated on: sqldoc init, sqldoc add, sqldoc codegen
+${imports.join('\n')}
+
+interface ProjectConfig extends BaseProjectConfig {
+${namespacesBlock}
+}
+
+export type SqldocConfig = ProjectConfig | ProjectConfig[]
+export type Config = SqldocConfig
+`
+
+  fs.writeFileSync(path.join(sqldocDir, 'config.d.ts'), content)
+}
+
+function findConfigTypeName(pkgPath: string, _nsName: string): string | null {
+  const candidates = ['src/index.ts', 'index.ts', 'src/index.js', 'index.js']
+  for (const candidate of candidates) {
+    const filePath = path.join(pkgPath, candidate)
+    if (!fs.existsSync(filePath)) continue
+
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const match = content.match(/export\s+(?:type\s+)?{\s*[^}]*\b(\w+Config)\b/)
+    if (match) return match[1]
+  }
+
+  return null
+}

package/src/utils/migration-formats.ts

@@ -0,0 +1,347 @@
+/**
+ * Format-aware migration file reading and writing.
+ *
+ * Each format has its own conventions for:
+ * - File naming and patterns
+ * - Up/down script extraction from file content
+ * - Writing new migration files with up+down sections
+ *
+ * Supported formats:
+ * - plain:          NNN_name.sql (entire file = up, no down)
+ * - atlas:          YYYYMMDDHHMMSS_name.sql (entire file = up, no down)
+ * - goose:          NNN_name.sql (-- +goose Up / -- +goose Down markers)
+ * - golang-migrate: NNN_name.up.sql / NNN_name.down.sql (separate files)
+ * - flyway:         V1__name.sql (up), U1__name.sql (down/undo)
+ * - dbmate:         NNN_name.sql (-- migrate:up / -- migrate:down markers)
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { MigrationFormat } from '@sqldoc/core'
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/** A parsed migration with its up and optional down SQL */
+export interface ParsedMigration {
+  /** Filename (primary file, e.g. "001_init.sql" or "001_init.up.sql") */
+  filename: string
+  /** The up (forward) SQL */
+  up: string
+  /** The down (rollback) SQL, if available */
+  down?: string
+  /** Sort key extracted from filename for ordering */
+  sortKey: string
+}
+
+/** Options for writing a new migration file */
+export interface WriteMigrationOptions {
+  /** Directory to write to */
+  dir: string
+  /** Migration name (e.g. "add_users") */
+  name: string
+  /** Up SQL content */
+  up: string
+  /** Down SQL content (optional) */
+  down?: string
+  /** Format to write in */
+  format: MigrationFormat
+  /** Naming strategy */
+  naming: 'timestamp' | 'sequential'
+  /** Existing migrations (for sequential naming) */
+  existing?: ParsedMigration[]
+}
+
+// ── Format-specific parsers ──────────────────────────────────────────
+
+/** Parse a single migration file based on format */
+function parsePlain(filename: string, content: string): ParsedMigration {
+  const sortKey = filename.split('_')[0]
+  return { filename, up: content.trim(), sortKey }
+}
+
+function parseAtlas(filename: string, content: string): ParsedMigration {
+  const sortKey = filename.split('_')[0]
+  return { filename, up: content.trim(), sortKey }
+}
+
+function parseGoose(filename: string, content: string): ParsedMigration {
+  const sortKey = filename.split('_')[0]
+
+  // Find the positions of -- +goose Up and -- +goose Down markers
+  const upIdx = content.search(/^--\s*\+goose\s+Up\s*$/m)
+  const downIdx = content.search(/^--\s*\+goose\s+Down\s*$/m)
+
+  let up: string
+  let down: string | undefined
+
+  if (upIdx !== -1) {
+    // Find end of the Up marker line
+    const afterUp = content.indexOf('\n', upIdx)
+    if (downIdx !== -1) {
+      up = content.substring(afterUp + 1, downIdx).trim()
+      const afterDown = content.indexOf('\n', downIdx)
+      down = content.substring(afterDown + 1).trim() || undefined
+    } else {
+      up = content.substring(afterUp + 1).trim()
+    }
+  } else {
+    up = content.trim()
+  }
+
+  return { filename, up, down, sortKey }
+}
+
+function parseDbmate(filename: string, content: string): ParsedMigration {
+  const sortKey = filename.split('_')[0]
+
+  // Find the positions of -- migrate:up and -- migrate:down markers
+  const upIdx = content.search(/^--\s*migrate:up\s*$/m)
+  const downIdx = content.search(/^--\s*migrate:down\s*$/m)
+
+  let up: string
+  let down: string | undefined
+
+  if (upIdx !== -1) {
+    const afterUp = content.indexOf('\n', upIdx)
+    if (downIdx !== -1) {
+      up = content.substring(afterUp + 1, downIdx).trim()
+      const afterDown = content.indexOf('\n', downIdx)
+      down = content.substring(afterDown + 1).trim() || undefined
+    } else {
+      up = content.substring(afterUp + 1).trim()
+    }
+  } else {
+    up = content.trim()
+  }
+
+  return { filename, up, down, sortKey }
+}
+
+// ── Directory readers ────────────────────────────────────────────────
+
+/**
+ * Read and parse all migrations from a directory in the given format.
+ * Returns migrations sorted by their sort key (chronological order).
+ */
+export function readMigrations(dir: string, format: MigrationFormat): ParsedMigration[] {
+  const absDir = path.resolve(dir)
+  if (!fs.existsSync(absDir)) return []
+
+  const allFiles = fs
+    .readdirSync(absDir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+
+  switch (format) {
+    case 'plain':
+    case 'atlas':
+      return allFiles.map((f) => {
+        const content = fs.readFileSync(path.join(absDir, f), 'utf-8')
+        return format === 'atlas' ? parseAtlas(f, content) : parsePlain(f, content)
+      })
+
+    case 'goose':
+      return allFiles.map((f) => {
+        const content = fs.readFileSync(path.join(absDir, f), 'utf-8')
+        return parseGoose(f, content)
+      })
+
+    case 'golang-migrate':
+      return readGolangMigrate(absDir, allFiles)
+
+    case 'flyway':
+      return readFlyway(absDir, allFiles)
+
+    case 'dbmate':
+      return allFiles.map((f) => {
+        const content = fs.readFileSync(path.join(absDir, f), 'utf-8')
+        return parseDbmate(f, content)
+      })
+  }
+}
+
+/** golang-migrate: pair .up.sql and .down.sql files */
+function readGolangMigrate(absDir: string, files: string[]): ParsedMigration[] {
+  const upFiles = files.filter((f) => f.includes('.up.sql'))
+  return upFiles.map((upFile) => {
+    const downFile = upFile.replace('.up.sql', '.down.sql')
+    const upContent = fs.readFileSync(path.join(absDir, upFile), 'utf-8').trim()
+    const downContent = files.includes(downFile)
+      ? fs.readFileSync(path.join(absDir, downFile), 'utf-8').trim()
+      : undefined
+
+    // Sort key: everything before .up.sql
+    const sortKey = upFile.replace('.up.sql', '').split('_')[0]
+    return { filename: upFile, up: upContent, down: downContent || undefined, sortKey }
+  })
+}
+
+/** flyway: V{n}__{name}.sql (up) and U{n}__{name}.sql (undo/down) */
+function readFlyway(absDir: string, files: string[]): ParsedMigration[] {
+  const vFiles = files.filter((f) => /^V\d+/.test(f))
+  return vFiles.map((vFile) => {
+    const upContent = fs.readFileSync(path.join(absDir, vFile), 'utf-8').trim()
+
+    // Find matching U file: V1__name.sql -> U1__name.sql
+    const versionMatch = vFile.match(/^V(\d+)/)
+    const version = versionMatch ? versionMatch[1] : ''
+    const uFile = files.find((f) => f.startsWith(`U${version}`))
+    const downContent = uFile ? fs.readFileSync(path.join(absDir, uFile), 'utf-8').trim() : undefined
+
+    return { filename: vFile, up: upContent, down: downContent || undefined, sortKey: version.padStart(6, '0') }
+  })
+}
+
+// ── File writers ─────────────────────────────────────────────────────
+
+/**
+ * Write a new migration file in the given format.
+ * Returns the absolute path(s) of written files.
+ */
+export function writeMigration(opts: WriteMigrationOptions): string[] {
+  const absDir = path.resolve(opts.dir)
+  fs.mkdirSync(absDir, { recursive: true })
+
+  const prefix = generatePrefix(opts)
+  const safeName = sanitizeName(opts.name)
+  const written: string[] = []
+
+  switch (opts.format) {
+    case 'plain':
+    case 'atlas': {
+      const filename = `${prefix}_${safeName}.sql`
+      const content = `${opts.up.trim()}\n`
+      const filePath = path.join(absDir, filename)
+      fs.writeFileSync(filePath, content, 'utf-8')
+      written.push(filePath)
+      break
+    }
+
+    case 'goose': {
+      const filename = `${prefix}_${safeName}.sql`
+      let content = `-- +goose Up\n${opts.up.trim()}\n`
+      if (opts.down) {
+        content += `\n-- +goose Down\n${opts.down.trim()}\n`
+      }
+      const filePath = path.join(absDir, filename)
+      fs.writeFileSync(filePath, content, 'utf-8')
+      written.push(filePath)
+      break
+    }
+
+    case 'golang-migrate': {
+      const upFilename = `${prefix}_${safeName}.up.sql`
+      const upPath = path.join(absDir, upFilename)
+      fs.writeFileSync(upPath, `${opts.up.trim()}\n`, 'utf-8')
+      written.push(upPath)
+
+      if (opts.down) {
+        const downFilename = `${prefix}_${safeName}.down.sql`
+        const downPath = path.join(absDir, downFilename)
+        fs.writeFileSync(downPath, `${opts.down.trim()}\n`, 'utf-8')
+        written.push(downPath)
+      }
+      break
+    }
+
+    case 'flyway': {
+      const version = prefix
+      const upFilename = `V${version}__${safeName}.sql`
+      const upPath = path.join(absDir, upFilename)
+      fs.writeFileSync(upPath, `${opts.up.trim()}\n`, 'utf-8')
+      written.push(upPath)
+
+      if (opts.down) {
+        const downFilename = `U${version}__${safeName}.sql`
+        const downPath = path.join(absDir, downFilename)
+        fs.writeFileSync(downPath, `${opts.down.trim()}\n`, 'utf-8')
+        written.push(downPath)
+      }
+      break
+    }
+
+    case 'dbmate': {
+      const filename = `${prefix}_${safeName}.sql`
+      let content = `-- migrate:up\n${opts.up.trim()}\n`
+      if (opts.down) {
+        content += `\n-- migrate:down\n${opts.down.trim()}\n`
+      }
+      const filePath = path.join(absDir, filename)
+      fs.writeFileSync(filePath, content, 'utf-8')
+      written.push(filePath)
+      break
+    }
+  }
+
+  return written
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/** Generate a filename prefix based on naming strategy */
+function generatePrefix(opts: WriteMigrationOptions): string {
+  if (opts.naming === 'sequential') {
+    return nextSequentialPrefix(opts.existing ?? [], opts.format)
+  }
+  return timestampPrefix()
+}
+
+/** Generate a YYYYMMDDHHMMSS timestamp prefix */
+function timestampPrefix(): string {
+  const now = new Date()
+  return [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+    String(now.getHours()).padStart(2, '0'),
+    String(now.getMinutes()).padStart(2, '0'),
+    String(now.getSeconds()).padStart(2, '0'),
+  ].join('')
+}
+
+/** Generate the next sequential prefix based on existing migrations */
+function nextSequentialPrefix(existing: ParsedMigration[], format: MigrationFormat): string {
+  if (format === 'flyway') {
+    // Flyway uses V1, V2, etc. Extract the max version number.
+    let max = 0
+    for (const m of existing) {
+      const match = m.filename.match(/^V(\d+)/)
+      if (match) {
+        const n = parseInt(match[1], 10)
+        if (n > max) max = n
+      }
+    }
+    return String(max + 1)
+  }
+
+  // For other formats, find the highest numeric prefix and increment
+  let max = 0
+  for (const m of existing) {
+    const match = m.sortKey.match(/^(\d+)/)
+    if (match) {
+      const n = parseInt(match[1], 10)
+      if (n > max) max = n
+    }
+  }
+  return String(max + 1).padStart(3, '0')
+}
+
+/** Sanitize a migration name for use in filenames */
+export function sanitizeName(name: string): string {
+  const safe = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+  return safe || 'migration'
+}
+
+/**
+ * Extract all up scripts from parsed migrations and concatenate them.
+ * This gives the "current" schema state from migrations.
+ */
+export function concatUpScripts(migrations: ParsedMigration[]): string {
+  return migrations
+    .map((m) => m.up)
+    .filter(Boolean)
+    .join('\n\n')
+}

package/src/utils/migrations.ts

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/** A migration file read from the migrations directory */
+export interface MigrationFile {
+  /** Filename (e.g. "20260321143000_initial.sql") */
+  filename: string
+  /** Full file content */
+  content: string
+  /** Timestamp prefix extracted from filename (before first underscore) */
+  timestamp: string
+}
+
+/**
+ * Read all migration files from a directory, sorted lexicographically (chronological).
+ * Returns empty array if directory doesn't exist.
+ */
+export function readMigrationDir(dir: string): MigrationFile[] {
+  const absDir = path.resolve(dir)
+  if (!fs.existsSync(absDir)) return []
+
+  const files = fs
+    .readdirSync(absDir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+
+  return files.map((filename) => ({
+    filename,
+    content: fs.readFileSync(path.join(absDir, filename), 'utf-8'),
+    timestamp: filename.split('_')[0],
+  }))
+}
+
+/**
+ * Generate a timestamped migration filename.
+ * Format: YYYYMMDDHHMMSS_name.sql
+ *
+ * Name is sanitized: lowercased, non-alphanumeric replaced with underscore,
+ * leading/trailing underscores stripped. Defaults to "migration" if empty.
+ */
+export function migrationFilename(name: string): string {
+  const now = new Date()
+  const ts = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+    String(now.getHours()).padStart(2, '0'),
+    String(now.getMinutes()).padStart(2, '0'),
+    String(now.getSeconds()).padStart(2, '0'),
+  ].join('')
+
+  const safeName = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+
+  return `${ts}_${safeName || 'migration'}.sql`
+}
+
+/**
+ * Write a migration file to the migrations directory.
+ * Creates the directory recursively if it doesn't exist.
+ * Statements are joined with ";\n" and a trailing ";\n" is appended.
+ * Returns the absolute path of the written file.
+ */
+export function writeMigrationFile(dir: string, filename: string, statements: string[]): string {
+  const absDir = path.resolve(dir)
+  fs.mkdirSync(absDir, { recursive: true })
+
+  const content = `${statements.join(';\n')};\n`
+  const filePath = path.join(absDir, filename)
+  fs.writeFileSync(filePath, content, 'utf-8')
+  return filePath
+}