@sqldoc/ns-codegen 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-codegen",
+  "version": "0.0.1",
+  "description": "Code generation namespace for sqldoc -- runs configurable templates against compiled Atlas schema",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "@sqldoc/core": "0.0.1",
+    "@sqldoc/atlas": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@sqldoc/core": "0.0.1",
+    "@sqldoc/atlas": "0.0.1"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,232 @@
+import type { ProjectContext } from '@sqldoc/core'
+import { describe, expect, it } from 'vitest'
+import plugin from '../index'
+
+function makeCtx(overrides: Partial<ProjectContext> = {}): ProjectContext {
+  return {
+    outputs: [],
+    mergedSql: '',
+    allFileTags: [],
+    docsMeta: [],
+    config: {},
+    projectRoot: '/tmp/test',
+    atlasRealm: { schemas: [{ name: 'public', tables: [] }] },
+    ...overrides,
+  } as unknown as ProjectContext
+}
+
+describe('ns-codegen plugin', () => {
+  describe('tag definitions', () => {
+    it('defines rename tag targeting table, column, view', () => {
+      expect(plugin.tags.rename).toBeDefined()
+      expect(plugin.tags.rename.targets).toEqual(['table', 'column', 'view'])
+      expect(plugin.tags.rename.args).toEqual([{ type: 'string' }, { type: 'string' }])
+    })
+
+    it('defines skip tag targeting table, column, view', () => {
+      expect(plugin.tags.skip).toBeDefined()
+      expect(plugin.tags.skip.targets).toEqual(['table', 'column', 'view'])
+      expect(plugin.tags.skip.args).toEqual([{ type: 'string' }])
+    })
+
+    it('defines type tag targeting column only', () => {
+      expect(plugin.tags.type).toBeDefined()
+      expect(plugin.tags.type.targets).toEqual(['column'])
+      expect(plugin.tags.type.args).toEqual([{ type: 'string' }, { type: 'string' }])
+    })
+  })
+
+  describe('afterCompile', () => {
+    it('returns empty files when config.templates is empty array', async () => {
+      const ctx = makeCtx({ config: { templates: [] } })
+      const result = await plugin.afterCompile!(ctx)
+      expect(result.files).toEqual([])
+    })
+
+    it('returns empty files when config.templates is undefined', async () => {
+      const ctx = makeCtx({ config: {} })
+      const result = await plugin.afterCompile!(ctx)
+      expect(result.files).toEqual([])
+    })
+
+    it('throws when atlasRealm is not provided', async () => {
+      const ctx = makeCtx({
+        config: { templates: [{ template: 'some-template', output: 'out' }] },
+        atlasRealm: undefined,
+      })
+      await expect(plugin.afterCompile!(ctx)).rejects.toThrow('ns-codegen requires Atlas schema')
+    })
+
+    it('calls template.generate with correct TemplateContext fields', async () => {
+      const recordedCtx: any[] = []
+      const _mockTemplate = {
+        generate: (ctx: any) => {
+          recordedCtx.push(ctx)
+          return { files: [{ path: 'test.ts', content: '// test' }] }
+        },
+      }
+
+      // We create a real file so afterCompile can dynamic-import it.
+      const fs = await import('node:fs')
+      const os = await import('node:os')
+      const path = await import('node:path')
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegen-test-'))
+      const templatePath = path.join(tmpDir, 'mock-template.mjs')
+      fs.writeFileSync(
+        templatePath,
+        `
+        export function generate(ctx) {
+          globalThis.__codegen_test_ctx__ = ctx
+          return { files: [{ path: 'out.ts', content: '// generated' }] }
+        }
+      `,
+      )
+
+      const realm = { schemas: [{ name: 'public', tables: [{ name: 'users' }] }] }
+      const allFileTags = [{ sourceFile: 'test.sql', objects: [] }]
+      const docsMeta = [{ annotations: [{ object: 'users', text: 'test' }] }]
+      const templateConfig = { option1: 'value1' }
+
+      const ctx = makeCtx({
+        config: {
+          templates: [
+            {
+              template: templatePath,
+              output: 'generated',
+              config: templateConfig,
+            },
+          ],
+        },
+        atlasRealm: realm,
+        allFileTags,
+        docsMeta,
+      } as any)
+
+      const _result = await plugin.afterCompile!(ctx)
+
+      const capturedCtx = (globalThis as any).__codegen_test_ctx__
+      expect(capturedCtx).toBeDefined()
+      expect(capturedCtx.realm).toEqual(realm)
+      expect(capturedCtx.allFileTags).toBe(allFileTags)
+      expect(capturedCtx.docsMeta).toBe(docsMeta)
+      expect(capturedCtx.config).toEqual(templateConfig)
+      expect(capturedCtx.output).toBe('generated')
+      expect(capturedCtx.templateName).toBe('mock-template')
+
+      // Clean up
+      fs.rmSync(tmpDir, { recursive: true })
+      delete (globalThis as any).__codegen_test_ctx__
+    })
+
+    it('prefixes file paths with entry.output', async () => {
+      const fs = await import('node:fs')
+      const os = await import('node:os')
+      const pathMod = await import('node:path')
+      const tmpDir = fs.mkdtempSync(pathMod.join(os.tmpdir(), 'codegen-test-'))
+      const templatePath = pathMod.join(tmpDir, 'path-template.mjs')
+      fs.writeFileSync(
+        templatePath,
+        `
+        export function generate(ctx) {
+          return { files: [
+            { path: 'types.ts', content: '// types' },
+            { path: 'queries.ts', content: '// queries' },
+          ] }
+        }
+      `,
+      )
+
+      const ctx = makeCtx({
+        config: {
+          templates: [
+            {
+              template: templatePath,
+              output: 'src/generated',
+              config: {},
+            },
+          ],
+        },
+      } as any)
+
+      const result = await plugin.afterCompile!(ctx)
+      expect(result.files).toHaveLength(2)
+      expect(result.files[0].filePath).toBe('src/generated/types.ts')
+      expect(result.files[1].filePath).toBe('src/generated/queries.ts')
+
+      fs.rmSync(tmpDir, { recursive: true })
+    })
+
+    it('throws when template does not export a generate function', async () => {
+      const fs = await import('node:fs')
+      const os = await import('node:os')
+      const pathMod = await import('node:path')
+      const tmpDir = fs.mkdtempSync(pathMod.join(os.tmpdir(), 'codegen-test-'))
+      const templatePath = pathMod.join(tmpDir, 'bad-template.mjs')
+      fs.writeFileSync(templatePath, `export const name = 'bad'`)
+
+      const ctx = makeCtx({
+        config: {
+          templates: [
+            {
+              template: templatePath,
+              output: 'out',
+            },
+          ],
+        },
+      } as any)
+
+      await expect(plugin.afterCompile!(ctx)).rejects.toThrow('does not export a generate function')
+
+      fs.rmSync(tmpDir, { recursive: true })
+    })
+  })
+
+  describe('extractTemplateName', () => {
+    it('extracts template name from scoped package path', async () => {
+      // We test indirectly via afterCompile setting templateName on context
+      const fs = await import('node:fs')
+      const os = await import('node:os')
+      const pathMod = await import('node:path')
+      const tmpDir = fs.mkdtempSync(pathMod.join(os.tmpdir(), 'codegen-test-'))
+
+      // Simulate a path like @sqldoc/templates/typescript by creating nested dirs
+      const templatePath = pathMod.join(tmpDir, 'typescript.mjs')
+      fs.writeFileSync(
+        templatePath,
+        `
+        export function generate(ctx) {
+          globalThis.__codegen_name_test__ = ctx.templateName
+          return { files: [] }
+        }
+      `,
+      )
+
+      const ctx = makeCtx({
+        config: {
+          templates: [
+            {
+              template: templatePath,
+              output: 'out',
+            },
+          ],
+        },
+      } as any)
+
+      await plugin.afterCompile!(ctx)
+      expect((globalThis as any).__codegen_name_test__).toBe('typescript')
+
+      fs.rmSync(tmpDir, { recursive: true })
+      delete (globalThis as any).__codegen_name_test__
+    })
+  })
+
+  describe('plugin metadata', () => {
+    it('has apiVersion 1', () => {
+      expect(plugin.apiVersion).toBe(1)
+    })
+
+    it('has name codegen', () => {
+      expect(plugin.name).toBe('codegen')
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,112 @@
+import * as path from 'node:path'
+import type { AtlasRealm } from '@sqldoc/atlas'
+import type { NamespacePlugin, ProjectContext, ProjectOutput } from '@sqldoc/core'
+import { findSqldocDir, tsImport, unwrapDefault } from '@sqldoc/core'
+import type { CodegenConfig, TemplateContext } from './types.ts'
+
+/** Extract template name from import path: '@sqldoc/templates/typescript' -> 'typescript', './my.ts' -> 'my' */
+function extractTemplateName(importPath: string): string {
+  const parts = importPath.split('/')
+  const last = parts[parts.length - 1]
+  return last.replace(/\.[^.]+$/, '')
+}
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'codegen',
+  tags: {
+    rename: {
+      description: 'Rename table/column in generated code (optional second arg scopes to a specific template)',
+      targets: ['table', 'column', 'view'],
+      args: [{ type: 'string' }, { type: 'string' }],
+    },
+    skip: {
+      description: 'Exclude from generated code (optional arg scopes to a specific template)',
+      targets: ['table', 'column', 'view'],
+      args: [{ type: 'string' }],
+    },
+    type: {
+      description: 'Override generated type for a column (optional second arg scopes to a specific template)',
+      targets: ['column'],
+      args: [{ type: 'string' }, { type: 'string' }],
+    },
+  },
+
+  async afterCompile(ctx: ProjectContext): Promise<ProjectOutput> {
+    const config = ctx.config as CodegenConfig
+    if (!config.templates || config.templates.length === 0) {
+      return { files: [] }
+    }
+
+    const realm = ctx.atlasRealm as AtlasRealm | undefined
+    if (!realm) {
+      throw new Error('ns-codegen requires Atlas schema. Run with a database connection (devUrl in config).')
+    }
+
+    const allFiles: Array<{ filePath: string; content: string; source: string }> = []
+
+    for (const entry of config.templates) {
+      let template: any
+
+      if (typeof entry.template === 'function' && typeof entry.template.generate === 'function') {
+        // Template object passed directly (typed config path)
+        template = entry.template
+      } else if (typeof entry.template === 'string') {
+        // Import path — resolve and load
+        const isAbsolute = path.isAbsolute(entry.template) || entry.template.startsWith('.')
+        let mod: any
+        if (isAbsolute) {
+          mod = await import(entry.template)
+        } else {
+          const sqldocDir = findSqldocDir()
+          let resolveDir = sqldocDir ? path.join(sqldocDir, 'node_modules') : null
+          if (!resolveDir && process.env.SQLDOC_RESOLVE_FROM_LOCAL_PACKAGE === 'true') {
+            resolveDir = ctx.projectRoot
+          }
+          if (!resolveDir) {
+            throw new Error(
+              `Cannot resolve template '${entry.template}': no .sqldoc/node_modules/ found. Run 'sqldoc init' first.`,
+            )
+          }
+          mod = (await tsImport(entry.template, resolveDir)) as any
+        }
+        template = unwrapDefault(mod, (m: any) => typeof m.generate === 'function')
+      }
+
+      if (!template || typeof template.generate !== 'function') {
+        throw new Error(`Template '${entry.template}' does not export a generate function`)
+      }
+
+      const templateName =
+        typeof entry.template === 'string' ? extractTemplateName(entry.template) : (template.name ?? 'unknown')
+      const templateCtx: TemplateContext = {
+        realm,
+        allFileTags: ctx.allFileTags,
+        docsMeta: ctx.docsMeta,
+        config: entry.config ?? {},
+        output: entry.output,
+        templateName,
+      }
+
+      const result = template.generate(templateCtx)
+      const outputIsFile = path.extname(entry.output) !== ''
+
+      if (outputIsFile && result.files.length > 1) {
+        throw new Error(
+          `Template '${templateName}' generates ${result.files.length} files but output '${entry.output}' is a file path. Use a directory instead.`,
+        )
+      }
+
+      for (const file of result.files) {
+        const filePath = outputIsFile ? entry.output : path.join(entry.output, file.path)
+        allFiles.push({ filePath, content: file.content, source: templateName })
+      }
+    }
+
+    return { files: allFiles }
+  },
+}
+
+export default plugin
+export type { CodegenConfig, Template, TemplateContext, TemplateDef, TemplateEntry, TemplateResult } from './types.ts'
+export { defineTemplate } from './types.ts'

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { AtlasRealm } from '@sqldoc/atlas'
+import type { ArgType, DocsMeta, InferSchema } from '@sqldoc/core'
+
+/** Config for the codegen namespace in sqldoc.config.ts namespaces.codegen */
+export interface CodegenConfig {
+  templates?: TemplateEntry[]
+}
+
+/** A single template entry in the codegen config */
+export interface TemplateEntry {
+  /** The template — either an import path string or a Template object */
+  template: string | Template<any>
+  /** Output path — file path for single-file templates, directory for multi-file templates */
+  output: string
+  /** Template-specific config (typed by each template) */
+  config?: Record<string, unknown>
+}
+
+/** Context passed to each template's generate function */
+export interface TemplateContext<C = Record<string, unknown>> {
+  /** Full post-compile Atlas realm */
+  realm: AtlasRealm
+  /** All tags across all files, grouped by source file then by SQL object */
+  allFileTags: Array<{
+    sourceFile: string
+    objects: Array<{
+      objectName: string
+      target: string
+      tags: Array<{ namespace: string; tag: string | null; args: Record<string, unknown> | unknown[] }>
+    }>
+  }>
+  /** Aggregated docs metadata from all plugins */
+  docsMeta: DocsMeta[]
+  /** Template-specific config from sqldoc.config.ts */
+  config: C
+  /** Output directory path */
+  output: string
+  /** Template name (derived from import path) */
+  templateName: string
+}
+
+/** Result returned from a template's generate function */
+export interface TemplateResult {
+  files: Array<{ path: string; content: string }>
+}
+
+/** Template definition (the object shape) */
+export interface TemplateDef<S extends Record<string, ArgType> = Record<string, ArgType>> {
+  /** Human-readable template name */
+  name: string
+  /** What this template generates */
+  description: string
+  /** Target language/format */
+  language: string
+  /** Config schema using ArgType definitions — use `as const` for type inference */
+  configSchema?: S
+  /** Generate output files from the schema + tags */
+  generate: (ctx: TemplateContext<InferSchema<S>>) => TemplateResult
+}
+
+/** A template is callable (creates a typed TemplateEntry) and has metadata properties */
+export interface Template<S extends Record<string, ArgType> = Record<string, ArgType>> extends TemplateDef<S> {
+  (opts: { output: string } & InferSchema<S>): TemplateEntry
+}
+
+/**
+ * Helper to define a template with full type inference.
+ * Returns a callable: `typescript({ output: '...', dateType: 'temporal' })`
+ */
+export function defineTemplate<const S extends Record<string, ArgType>>(def: TemplateDef<S>): Template<S> {
+  const fn = function (this: void, opts: { output: string } & InferSchema<S>): TemplateEntry {
+    const { output, ...config } = opts
+    return {
+      template: fn as any,
+      output,
+      config: Object.keys(config).length > 0 ? (config as Record<string, unknown>) : undefined,
+    }
+  }
+  // 'name' is read-only on functions — use defineProperty
+  Object.defineProperty(fn, 'name', { value: def.name, writable: false })
+  Object.assign(fn, {
+    description: def.description,
+    language: def.language,
+    configSchema: def.configSchema,
+    generate: def.generate,
+  })
+  return fn as unknown as Template<S>
+}