@sqldoc/cli 0.0.1

package/src/__tests__/pretty-changes.test.ts

@@ -0,0 +1,153 @@
+import type { AtlasChange } from '@sqldoc/atlas'
+import { describe, expect, it } from 'vitest'
+import { renderChanges } from '../utils/pretty-changes.ts'
+
+// Strip ANSI escape sequences for assertion
+function stripAnsi(s: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape sequences
+  return s.replace(/\x1b\[[0-9;]*m/g, '')
+}
+
+describe('renderChanges', () => {
+  it('returns empty array for no changes', () => {
+    expect(renderChanges([])).toEqual([])
+  })
+
+  it('renders add_table', () => {
+    const changes: AtlasChange[] = [{ type: 'add_table', table: 'users' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  + users (new table)')
+  })
+
+  it('renders drop_table', () => {
+    const changes: AtlasChange[] = [{ type: 'drop_table', table: 'old_logs' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  - old_logs (dropped)')
+  })
+
+  it('renders rename_table', () => {
+    const changes: AtlasChange[] = [{ type: 'rename_table', table: 'accounts', detail: 'users -> accounts' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  ~ accounts (renamed from users)')
+  })
+
+  it('renders add_view', () => {
+    const changes: AtlasChange[] = [{ type: 'add_view', table: 'active_posts' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  + active_posts (view)')
+  })
+
+  it('renders drop_view', () => {
+    const changes: AtlasChange[] = [{ type: 'drop_view', table: 'old_view' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  - old_view (view dropped)')
+  })
+
+  it('renders add_function', () => {
+    const changes: AtlasChange[] = [{ type: 'add_function', table: 'calculate_total' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  + calculate_total (function)')
+  })
+
+  it('renders drop_function', () => {
+    const changes: AtlasChange[] = [{ type: 'drop_function', table: 'old_func' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toBe('  - old_func (function dropped)')
+  })
+
+  it('renders column changes nested under table', () => {
+    const changes: AtlasChange[] = [
+      { type: 'add_column', table: 'users', name: 'age', detail: 'integer' },
+      { type: 'drop_column', table: 'users', name: 'legacy_id' },
+    ]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(3)
+    expect(lines[0]).toBe('  users') // table header
+    expect(lines[1]).toBe('    + age (integer)')
+    expect(lines[2]).toBe('    - legacy_id')
+  })
+
+  it('renders rename_column', () => {
+    const changes: AtlasChange[] = [
+      { type: 'rename_column', table: 'users', name: 'email_address', detail: 'email -> email_address' },
+    ]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2) // table header + change
+    expect(lines[1]).toBe('    ~ email -> email_address (renamed)')
+  })
+
+  it('renders modify_column', () => {
+    const changes: AtlasChange[] = [
+      { type: 'modify_column', table: 'users', name: 'email', detail: 'varchar(100) -> varchar(255)' },
+    ]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2) // table header + change
+    expect(lines[1]).toBe('    ~ email (varchar(100) -> varchar(255))')
+  })
+
+  it('renders add_index nested under table', () => {
+    const changes: AtlasChange[] = [{ type: 'add_index', table: 'users', name: 'idx_users_email' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2)
+    expect(lines[1]).toBe('    + idx_users_email (index)')
+  })
+
+  it('renders drop_index nested under table', () => {
+    const changes: AtlasChange[] = [{ type: 'drop_index', table: 'users', name: 'idx_old' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2)
+    expect(lines[1]).toBe('    - idx_old (index)')
+  })
+
+  it('nests sub-changes under table-level change', () => {
+    const changes: AtlasChange[] = [
+      { type: 'add_table', table: 'users' },
+      { type: 'add_column', table: 'users', name: 'id', detail: 'bigint' },
+      { type: 'add_column', table: 'users', name: 'email', detail: 'text' },
+    ]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(3)
+    expect(lines[0]).toBe('  + users (new table)')
+    expect(lines[1]).toBe('    + id (bigint)')
+    expect(lines[2]).toBe('    + email (text)')
+  })
+
+  it('renders mixed table-level and column changes', () => {
+    const changes: AtlasChange[] = [
+      { type: 'add_table', table: 'posts' },
+      { type: 'rename_table', table: 'accounts', detail: 'users -> accounts' },
+      { type: 'add_column', table: 'accounts', name: 'age', detail: 'integer' },
+      { type: 'drop_column', table: 'orders', name: 'legacy_id' },
+      { type: 'drop_table', table: 'old_logs' },
+    ]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(6)
+    expect(lines[0]).toBe('  + posts (new table)')
+    expect(lines[1]).toBe('  ~ accounts (renamed from users)')
+    expect(lines[2]).toBe('    + age (integer)')
+    expect(lines[3]).toBe('  - old_logs (dropped)')
+    expect(lines[4]).toBe('  orders') // table header for sub-changes
+    expect(lines[5]).toBe('    - legacy_id')
+  })
+
+  it('handles add_column without detail', () => {
+    const changes: AtlasChange[] = [{ type: 'add_column', table: 'users', name: 'status' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2)
+    expect(lines[1]).toBe('    + status')
+  })
+
+  it('handles modify_column without detail', () => {
+    const changes: AtlasChange[] = [{ type: 'modify_column', table: 'users', name: 'email' }]
+    const lines = renderChanges(changes).map(stripAnsi)
+    expect(lines).toHaveLength(2)
+    expect(lines[1]).toBe('    ~ email')
+  })
+})

package/src/__tests__/rename-detection.test.ts

@@ -0,0 +1,142 @@
+import type { CompilerOutput } from '@sqldoc/core'
+import { describe, expect, it } from 'vitest'
+import { buildRenamesFromPreviously } from '../commands/migrate.ts'
+
+function makeOutput(
+  fileTags: CompilerOutput['fileTags'] = [],
+  overrides: Partial<CompilerOutput> = {},
+): CompilerOutput {
+  return {
+    sourceFile: 'schema.sql',
+    mergedSql: '',
+    sqlOutputs: [],
+    codeOutputs: [],
+    errors: [],
+    docsMeta: [],
+    fileTags,
+    ...overrides,
+  }
+}
+
+describe('buildRenamesFromPreviously', () => {
+  it('extracts column renames from @docs.previously tags', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'users.email',
+          target: 'column',
+          tags: [{ namespace: 'docs', tag: 'previously', args: ['email_address'] }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(1)
+    expect(renames[0]).toEqual({
+      type: 'column',
+      table: 'users',
+      oldName: 'email_address',
+      newName: 'email',
+    })
+  })
+
+  it('extracts table renames from @docs.previously tags', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'accounts',
+          target: 'table',
+          tags: [{ namespace: 'docs', tag: 'previously', args: ['users'] }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(1)
+    expect(renames[0]).toEqual({
+      type: 'table',
+      table: 'accounts',
+      oldName: 'users',
+      newName: 'accounts',
+    })
+  })
+
+  it('returns empty array when no @docs.previously tags', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'users',
+          target: 'table',
+          tags: [{ namespace: 'audit', tag: 'track', args: { on: ['delete'] } }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(0)
+  })
+
+  it('handles multiple renames across files', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'users.email',
+          target: 'column',
+          tags: [{ namespace: 'docs', tag: 'previously', args: ['email_address'] }],
+        },
+      ]),
+      makeOutput([
+        {
+          objectName: 'posts.title',
+          target: 'column',
+          tags: [{ namespace: 'docs', tag: 'previously', args: ['subject'] }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(2)
+    expect(renames[0].table).toBe('users')
+    expect(renames[0].oldName).toBe('email_address')
+    expect(renames[0].newName).toBe('email')
+    expect(renames[1].table).toBe('posts')
+    expect(renames[1].oldName).toBe('subject')
+    expect(renames[1].newName).toBe('title')
+  })
+
+  it('ignores tags with non-string args', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'users.email',
+          target: 'column',
+          tags: [{ namespace: 'docs', tag: 'previously', args: [] }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(0)
+  })
+
+  it('ignores @docs tags that are not "previously"', () => {
+    const outputs = [
+      makeOutput([
+        {
+          objectName: 'users.email',
+          target: 'column',
+          tags: [{ namespace: 'docs', tag: 'description', args: ['User email'] }],
+        },
+      ]),
+    ]
+
+    const renames = buildRenamesFromPreviously(outputs)
+
+    expect(renames).toHaveLength(0)
+  })
+})

package/src/__tests__/validate.test.ts

@@ -0,0 +1,110 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('validateCommand', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sqldoc-cli-validate-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    process.exitCode = undefined as any
+  })
+
+  it('returns exit code 0 when validation passes', async () => {
+    // Create a valid namespace
+    const nsFile = path.join(tmpDir, 'ns-valid.ts')
+    fs.writeFileSync(
+      nsFile,
+      `
+      export default {
+        name: 'valid',
+        tags: {
+          ok: { description: 'valid tag' },
+        },
+      }
+    `,
+      'utf-8',
+    )
+
+    const sqlFile = path.join(tmpDir, 'good.sql')
+    fs.writeFileSync(
+      sqlFile,
+      `-- @import './ns-valid.ts'
+
+-- @valid.ok
+CREATE TABLE good (
+  id serial PRIMARY KEY
+);
+`,
+      'utf-8',
+    )
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    const { validateCommand } = await import('../commands/validate.ts')
+    process.exitCode = undefined as any
+    await validateCommand(sqlFile, {})
+
+    // No errors = no exitCode set (remains undefined or 0)
+    expect(process.exitCode).not.toBe(1)
+
+    consoleSpy.mockRestore()
+  })
+
+  it('throws CliError when errors found', async () => {
+    // SQL file referencing unknown namespace (no import for it)
+    const sqlFile = path.join(tmpDir, 'bad.sql')
+    fs.writeFileSync(
+      sqlFile,
+      `-- @unknown.tag
+CREATE TABLE bad (
+  id serial PRIMARY KEY
+);
+`,
+      'utf-8',
+    )
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    const { validateCommand } = await import('../commands/validate.ts')
+    const { CliError } = await import('../errors.ts')
+    await expect(validateCommand(sqlFile, {})).rejects.toThrow(CliError)
+
+    consoleSpy.mockRestore()
+  })
+
+  it('formats diagnostics as file:line:col: severity: message', async () => {
+    const sqlFile = path.join(tmpDir, 'diag.sql')
+    fs.writeFileSync(
+      sqlFile,
+      `-- @unknown.tag
+CREATE TABLE diag (
+  id serial PRIMARY KEY
+);
+`,
+      'utf-8',
+    )
+
+    const logOutput: string[] = []
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation((...args: any[]) => {
+      logOutput.push(args.map(String).join(' '))
+    })
+
+    const { validateCommand } = await import('../commands/validate.ts')
+    const { CliError } = await import('../errors.ts')
+    await expect(validateCommand(sqlFile, {})).rejects.toThrow(CliError)
+
+    // Check that at least one output line matches the file:line:col format
+    const diagLine = logOutput.find((l) => l.includes(sqlFile) && l.includes(':1:'))
+    expect(diagLine).toBeDefined()
+    expect(diagLine).toContain('error')
+    expect(diagLine).toContain("Unknown namespace '@unknown'")
+
+    consoleSpy.mockRestore()
+  })
+})

package/src/commands/codegen.ts

@@ -0,0 +1,127 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { createRunner } from '@sqldoc/atlas'
+import type { DocsMeta, ProjectContext, ResolvedConfig } from '@sqldoc/core'
+import { loadConfig, resolveProject } from '@sqldoc/core'
+import pc from 'picocolors'
+import { CliError, formatPipelineError } from '../errors.ts'
+import { generateConfigTypes } from '../utils/generate-config-types.ts'
+import { runCompilePipeline } from '../utils/pipeline.ts'
+
+/**
+ * compile command: reads SQL files, runs the full pipeline
+ * (parse, load namespaces, AST, compile), runs afterCompile hooks,
+ * THEN outputs merged SQL.
+ */
+export async function codegenCommand(
+  inputPath: string | undefined,
+  options: { config?: string; plugins?: string; project?: string },
+): Promise<void> {
+  const configRoot = options.config
+    ? path.dirname(path.resolve(options.config))
+    : process.env.SQLDOC_PROJECT_ROOT || process.cwd()
+  const { config: rawConfig, configPath } = await loadConfig(configRoot, options.config)
+  const config: ResolvedConfig = resolveProject(rawConfig, options.project)
+
+  // Resolve input path: explicit arg > config.schema > error
+  const resolvedInput = inputPath ?? config.schema
+  if (!resolvedInput) {
+    throw new CliError('No input path provided. Specify a path argument or set "schema" in sqldoc.config.ts')
+  }
+
+  // Regenerate .sqldoc/config.d.ts for typed config
+  const sqldocDir = path.join(configRoot, '.sqldoc')
+  if (fs.existsSync(sqldocDir)) {
+    generateConfigTypes(sqldocDir)
+  }
+
+  const pluginFilter = options.plugins ? new Set(options.plugins.split(',').map((s) => s.trim())) : null
+
+  let result
+  try {
+    result = await runCompilePipeline(resolvedInput, config, configRoot)
+  } catch (err: any) {
+    throw formatPipelineError(err, config)
+  }
+
+  const { mergedSql, outputs, plugins, totalErrors } = result
+
+  // Run afterCompile hooks BEFORE outputting SQL
+  const projectPlugins = [...plugins.entries()].filter(
+    ([name, p]) =>
+      (typeof p.afterCompile === 'function' || typeof p.generateProject === 'function') &&
+      (pluginFilter === null || pluginFilter.has(name)),
+  )
+
+  if (projectPlugins.length > 0) {
+    const dialect = config.dialect ?? 'postgres'
+    const allFileTags = outputs.map((o) => ({
+      sourceFile: o.sourceFile,
+      objects: o.fileTags.map((ft) => ({
+        objectName: ft.objectName,
+        target: ft.target,
+        tags: ft.tags,
+      })),
+    }))
+    const allDocsMeta: DocsMeta[] = outputs.flatMap((o) => o.docsMeta)
+
+    // Check if plugins generated any additional SQL
+    const hasGeneratedSql = outputs.some((o) => o.sqlOutputs.length > 0)
+    let postCompileRealm = result.atlasRealm
+
+    if (hasGeneratedSql) {
+      // Re-inspect with the merged SQL (includes generated tables like audit_log)
+      const freshRunner = await createRunner({ dialect, devUrl: config.devUrl, sqlFiles: [mergedSql] })
+      const postCompileResult = await freshRunner.inspect([mergedSql], {
+        schema: dialect === 'postgres' ? 'public' : undefined,
+        dialect,
+      })
+      await freshRunner.close()
+
+      if (postCompileResult.error) {
+        throw new CliError(`Post-compile schema inspect failed: ${postCompileResult.error}`)
+      }
+      postCompileRealm = postCompileResult.schema
+    }
+
+    for (const [nsName, plugin] of projectPlugins) {
+      const hook = plugin.afterCompile ?? plugin.generateProject
+      const ctx: ProjectContext = {
+        outputs,
+        mergedSql,
+        allFileTags,
+        docsMeta: allDocsMeta,
+        config: (config.namespaces?.[nsName] ?? {}) as Record<string, unknown>,
+        projectRoot: configRoot,
+        atlasRealm: postCompileRealm,
+      }
+
+      try {
+        const result = await hook!(ctx)
+        if (result?.files) {
+          for (const file of result.files) {
+            const outPath = path.resolve(configRoot, file.filePath)
+            try {
+              fs.mkdirSync(path.dirname(outPath), { recursive: true })
+              fs.writeFileSync(outPath, file.content, 'utf-8')
+            } catch (writeErr: any) {
+              throw new CliError(`Failed to write ${outPath}: ${writeErr?.message ?? writeErr}`)
+            }
+            const label = (file as any).source ? `${nsName}/${(file as any).source}` : nsName
+            console.error(pc.green(`[${label}] wrote ${path.relative(process.cwd(), outPath)}`))
+          }
+        }
+      } catch (err: any) {
+        if (err instanceof CliError) throw err
+        if (configPath) {
+          console.error(pc.dim(`config: ${configPath}`))
+        }
+        throw new CliError(`[${nsName}] ${err?.message ?? err}`)
+      }
+    }
+  }
+
+  if (totalErrors > 0) {
+    throw new CliError(`${totalErrors} error(s) encountered`)
+  }
+}