@sqldoc/core 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+  "type": "module",
+  "name": "@sqldoc/core",
+  "version": "0.0.1",
+  "description": "Core engine for sqldoc -- parser, loader, validator, types",
+  "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"
+  ],
+  "dependencies": {
+    "bundle-require": "^5.1.0",
+    "@sqldoc/sqlparser-ts": "0.61.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/ast/sqlparser-ts.test.ts

@@ -0,0 +1,117 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { SqlparserTsAdapter } from '../../ast/sqlparser-ts'
+import type { SqlStatement } from '../../ast/types'
+
+const TEST_SQL = `CREATE TABLE users (
+  id BIGSERIAL PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT
+);
+
+CREATE VIEW active_users AS SELECT * FROM users WHERE active = true;
+
+CREATE INDEX idx_users_email ON users (email);
+
+CREATE TYPE user_role AS ENUM ('admin', 'user', 'guest');
+
+CREATE FUNCTION get_user(p_id BIGINT) RETURNS VOID LANGUAGE plpgsql AS $$ BEGIN END; $$;
+
+CREATE TRIGGER user_audit AFTER INSERT ON users FOR EACH ROW EXECUTE FUNCTION audit_fn();`
+
+describe('SqlparserTsAdapter', () => {
+  let adapter: SqlparserTsAdapter
+  let stmts: SqlStatement[]
+
+  beforeAll(async () => {
+    adapter = new SqlparserTsAdapter()
+    await adapter.init()
+    stmts = adapter.parseStatements(TEST_SQL)
+  })
+
+  it('parses CREATE TABLE with kind, objectName, and columns', () => {
+    const table = stmts.find((s) => s.kind === 'table')
+    expect(table).toBeDefined()
+    expect(table!.objectName).toBe('users')
+    expect(table!.columns).toBeDefined()
+    expect(table!.columns!.length).toBe(3)
+
+    const [id, email, name] = table!.columns!
+    expect(id.name).toBe('id')
+    expect(id.dataType).toBe('bigserial')
+    expect(email.name).toBe('email')
+    expect(email.dataType).toBe('text')
+    expect(name.name).toBe('name')
+    expect(name.dataType).toBe('text')
+  })
+
+  it('parses CREATE VIEW with kind and objectName', () => {
+    const view = stmts.find((s) => s.kind === 'view')
+    expect(view).toBeDefined()
+    expect(view!.objectName).toBe('active_users')
+  })
+
+  it('parses CREATE INDEX with kind and objectName', () => {
+    const index = stmts.find((s) => s.kind === 'index')
+    expect(index).toBeDefined()
+    expect(index!.objectName).toBe('idx_users_email')
+  })
+
+  it('parses CREATE TYPE (ENUM) with kind and objectName', () => {
+    const type = stmts.find((s) => s.kind === 'type')
+    expect(type).toBeDefined()
+    expect(type!.objectName).toBe('user_role')
+  })
+
+  it('parses CREATE FUNCTION with kind and objectName', () => {
+    const fn = stmts.find((s) => s.kind === 'function')
+    expect(fn).toBeDefined()
+    expect(fn!.objectName).toBe('get_user')
+  })
+
+  it('parses CREATE TRIGGER with kind and objectName', () => {
+    const trigger = stmts.find((s) => s.kind === 'trigger')
+    expect(trigger).toBeDefined()
+    expect(trigger!.objectName).toBe('user_audit')
+  })
+
+  it('returns multiple statements with correct line numbers', () => {
+    expect(stmts.length).toBe(6)
+    // Each statement should have a different line
+    const lines = stmts.map((s) => s.line)
+    const uniqueLines = new Set(lines)
+    expect(uniqueLines.size).toBe(6)
+    // Lines should be in ascending order
+    for (let i = 1; i < lines.length; i++) {
+      expect(lines[i]).toBeGreaterThan(lines[i - 1])
+    }
+  })
+
+  it('handles RETURNS SETOF gracefully (no crash)', () => {
+    const setofSql = `CREATE FUNCTION list_users() RETURNS SETOF users LANGUAGE plpgsql AS $$ BEGIN RETURN QUERY SELECT * FROM users; END; $$;`
+    // Should not throw
+    const result = adapter.parseStatements(setofSql)
+    // May return empty array (parse failure filtered) or a result -- either is acceptable
+    expect(Array.isArray(result)).toBe(true)
+  })
+
+  it('handles $$ function bodies correctly', () => {
+    const dollarSql = `CREATE TABLE t1 (id INT);
+
+CREATE FUNCTION foo() RETURNS VOID LANGUAGE plpgsql AS $$
+BEGIN
+  INSERT INTO t1 VALUES (1);
+  INSERT INTO t1 VALUES (2);
+END;
+$$;
+
+CREATE TABLE t2 (id INT);`
+
+    const result = adapter.parseStatements(dollarSql)
+    const tableStmts = result.filter((s) => s.kind === 'table')
+    expect(tableStmts.length).toBe(2)
+    expect(tableStmts[0].objectName).toBe('t1')
+    expect(tableStmts[1].objectName).toBe('t2')
+    // t2 should be on a later line than t1
+    expect(tableStmts[1].line).toBeGreaterThan(tableStmts[0].line)
+  })
+})

package/src/__tests__/blocks.test.ts

@@ -0,0 +1,80 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { beforeAll, describe, expect, it } from 'vitest'
+import { SqlparserTsAdapter } from '../ast/sqlparser-ts'
+import type { SqlStatement } from '../ast/types'
+import { buildBlocks } from '../blocks'
+import { parse } from '../parser'
+
+const fixture = fs.readFileSync(path.join(__dirname, 'tags.sql'), 'utf-8')
+
+describe('block resolution from tags.sql', () => {
+  let stmts: SqlStatement[]
+
+  beforeAll(async () => {
+    const adapter = new SqlparserTsAdapter()
+    await adapter.init()
+    stmts = adapter.parseStatements(fixture)
+  })
+
+  function getBlocks() {
+    const { tags } = parse(fixture)
+    const docLines = fixture.split('\n')
+    return buildBlocks(tags, fixture, docLines, stmts)
+  }
+
+  /** Find the block containing a tag with the given rawArgs value */
+  function blockFor(argValue: string) {
+    const blocks = getBlocks()
+    for (const block of blocks) {
+      for (const tag of block.tags) {
+        if (tag.rawArgs?.includes(argValue)) {
+          return { block, tag, ast: block.ast }
+        }
+      }
+    }
+    throw new Error(`No block found for arg "${argValue}"`)
+  }
+
+  it('@for("one") — above CREATE TABLE → table', () => {
+    const { ast } = blockFor('"one"')
+    expect(ast.target).toBe('table')
+    expect(ast.objectName).toBe('one')
+  })
+
+  it('@for("one again") — same line as CREATE TABLE → table', () => {
+    const { ast } = blockFor('"one again"')
+    expect(ast.target).toBe('table')
+    expect(ast.objectName).toBe('one')
+  })
+
+  it('@for("two") — above column two → column', () => {
+    const { ast } = blockFor('"two"')
+    expect(ast.target).toBe('column')
+    expect(ast.columnName).toBe('two')
+  })
+
+  it('@for("two again") — same line as column two → column', () => {
+    const { ast } = blockFor('"two again"')
+    expect(ast.target).toBe('column')
+    expect(ast.columnName).toBe('two')
+  })
+
+  it('@for("three") — same line as column three → column', () => {
+    const { ast } = blockFor('"three"')
+    expect(ast.target).toBe('column')
+    expect(ast.columnName).toBe('three')
+  })
+
+  it('@for("four") — above column four with blank lines → column', () => {
+    const { ast } = blockFor('"four"')
+    expect(ast.target).toBe('column')
+    expect(ast.columnName).toBe('four')
+  })
+
+  it('@for("one yet again") — after all columns → table', () => {
+    const { ast } = blockFor('"one yet again"')
+    expect(ast.target).toBe('table')
+    expect(ast.objectName).toBe('one')
+  })
+})

package/src/__tests__/compile.test.ts

@@ -0,0 +1,407 @@
+import { describe, expect, it } from 'vitest'
+import type { SqlAstAdapter } from '../ast/adapter'
+import { compile } from '../compiler/compile'
+import type { NamespacePlugin, ProjectConfig, SqlOutput, TagContext } from '../compiler/types'
+
+// ── Task 1: Type extension tests ─────────────────────────────────────
+
+describe('ProjectConfig type extensions', () => {
+  it('should accept devUrl field', () => {
+    const config: ProjectConfig = {
+      dialect: 'postgres',
+      devUrl: 'postgres://localhost:5432/test',
+      include: ['**/*.sql'],
+    }
+    expect(config.devUrl).toBe('postgres://localhost:5432/test')
+  })
+
+  it('should require dialect', () => {
+    const config: ProjectConfig = { dialect: 'postgres' }
+    expect(config.devUrl).toBeUndefined()
+  })
+})
+
+describe('TagContext atlas fields', () => {
+  it('should accept atlasTable field', () => {
+    const ctx = { atlasTable: { name: 'users', columns: [] } } as Partial<TagContext>
+    expect(ctx.atlasTable).toBeDefined()
+  })
+
+  it('should accept atlasColumn field', () => {
+    const ctx = { atlasColumn: { name: 'email', type: { raw: 'text' } } } as Partial<TagContext>
+    expect(ctx.atlasColumn).toBeDefined()
+  })
+
+  it('should accept atlasRealm field', () => {
+    const ctx = { atlasRealm: { schemas: [{ name: 'public', tables: [] }] } } as Partial<TagContext>
+    expect(ctx.atlasRealm).toBeDefined()
+  })
+
+  it('should work without atlas fields (Tier 1 backwards compat)', () => {
+    const ctx: Partial<TagContext> = {
+      target: 'table',
+      objectName: 'users',
+      tag: { name: null, args: {} },
+      namespaceTags: [],
+      siblingTags: [],
+      fileTags: [],
+      astNode: null,
+      fileStatements: [],
+      config: {},
+      filePath: 'test.sql',
+    }
+    expect(ctx.atlasTable).toBeUndefined()
+    expect(ctx.atlasColumn).toBeUndefined()
+    expect(ctx.atlasRealm).toBeUndefined()
+  })
+})
+
+// ── Task 2: compile() with Atlas realm ───────────────────────────────
+
+// Mock Atlas realm for testing (lowercase schema fields, PascalCase Attr variants)
+const mockRealm = {
+  schemas: [
+    {
+      name: 'public',
+      tables: [
+        {
+          name: 'users',
+          columns: [
+            {
+              name: 'email',
+              type: { raw: 'text', null: false },
+              attrs: [{ Name: 'pii.mask', Args: '' }],
+            },
+            {
+              name: 'id',
+              type: { raw: 'bigserial', null: false, T: 'bigserial' },
+              attrs: [],
+            },
+          ],
+          attrs: [{ Name: 'audit.track', Args: 'on: [delete, update]' }],
+        },
+      ],
+      views: [
+        {
+          name: 'active_users',
+          columns: [{ name: 'email', type: { raw: 'text' } }],
+          attrs: [{ Name: 'docs', Args: '' }],
+        },
+      ],
+    },
+  ],
+}
+
+// Minimal mock adapter -- Tier 2 doesn't need real SQL parsing
+const mockAdapter: SqlAstAdapter = {
+  init: async () => {},
+  parseStatements: () => [],
+  parseComments: () => [],
+}
+
+function createMockPlugin(onTagFn?: (ctx: TagContext) => SqlOutput[] | undefined): NamespacePlugin {
+  return {
+    name: 'test-plugin',
+    tags: {},
+    apiVersion: 1,
+    onTag: onTagFn ?? (() => undefined),
+  }
+}
+
+describe('splitTagName', () => {
+  // splitTagName is internal, but we test it via compile behavior
+  it('should handle dotted tag name via compile (namespace.tag)', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    // Should have invoked audit plugin with tag="track" from "audit.track"
+    const auditCall = capturedCtx.find((c) => c.tag.name === 'track')
+    expect(auditCall).toBeDefined()
+    expect(auditCall!.objectName).toBe('users')
+    expect(auditCall!.target).toBe('table')
+  })
+
+  it('should handle simple tag name as $self (namespace only)', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['docs', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    // "docs" with no dot -> namespace=docs, tag=null ($self)
+    const docsCall = capturedCtx.find((c) => c.tag.name === null)
+    expect(docsCall).toBeDefined()
+    expect(docsCall!.objectName).toBe('active_users')
+    expect(docsCall!.target).toBe('view')
+  })
+})
+
+describe('compile() Tier 2 (Atlas realm)', () => {
+  it('should invoke plugin onTag with atlasTable in context', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    const _result = compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    expect(capturedCtx.length).toBeGreaterThan(0)
+    const tableCall = capturedCtx.find((c) => c.target === 'table')
+    expect(tableCall).toBeDefined()
+    expect(tableCall!.atlasTable).toBeDefined()
+    expect((tableCall!.atlasTable as any).name).toBe('users')
+    expect(tableCall!.atlasRealm).toBe(mockRealm)
+  })
+
+  it('should set correct columnName, columnType, atlasColumn for column tags', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['pii', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    expect(capturedCtx.length).toBeGreaterThan(0)
+    const colCall = capturedCtx.find((c) => c.target === 'column')
+    expect(colCall).toBeDefined()
+    expect(colCall!.columnName).toBe('email')
+    expect(colCall!.columnType).toBe('text')
+    expect(colCall!.objectName).toBe('users')
+    expect(colCall!.atlasColumn).toBeDefined()
+    expect((colCall!.atlasColumn as any).name).toBe('email')
+    expect(colCall!.atlasTable).toBeDefined()
+    expect(colCall!.atlasRealm).toBe(mockRealm)
+  })
+
+  it('should produce CompilerOutput structure', () => {
+    const plugin = createMockPlugin((ctx) => {
+      return [{ sql: `-- generated for ${ctx.objectName}` }]
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    const result = compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    expect(result.sourceFile).toBe('test.sql')
+    expect(result.sqlOutputs.length).toBeGreaterThan(0)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  it('should build fileTags from Atlas data', () => {
+    const plugin = createMockPlugin(() => undefined)
+
+    const plugins = new Map<string, NamespacePlugin>([
+      ['audit', plugin],
+      ['pii', plugin],
+      ['docs', plugin],
+    ])
+
+    const result = compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    expect(result.fileTags.length).toBeGreaterThan(0)
+    const usersEntry = result.fileTags.find((ft) => ft.objectName === 'users')
+    expect(usersEntry).toBeDefined()
+    expect(usersEntry!.target).toBe('table')
+    expect(usersEntry!.tags.length).toBeGreaterThan(0)
+  })
+
+  it('should pass namespace config from SqldocConfig', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres', namespaces: { audit: { destination: 'audit_log' } } },
+      atlasRealm: mockRealm,
+    })
+
+    const auditCall = capturedCtx.find((c) => c.tag.name === 'track')
+    expect(auditCall).toBeDefined()
+    expect((auditCall!.config as any).destination).toBe('audit_log')
+  })
+
+  it('should handle errors from plugin onTag gracefully', () => {
+    const plugin: NamespacePlugin = {
+      name: 'broken',
+      tags: {},
+      apiVersion: 1,
+      onTag: () => {
+        throw new Error('plugin crashed')
+      },
+    }
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    const result = compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    expect(result.errors.length).toBeGreaterThan(0)
+    expect(result.errors[0].message).toBe('plugin crashed')
+  })
+
+  it('should handle Atlas realm with views', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['docs', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    const viewCall = capturedCtx.find((c) => c.target === 'view')
+    expect(viewCall).toBeDefined()
+    expect(viewCall!.objectName).toBe('active_users')
+    expect(viewCall!.atlasTable).toBeDefined()
+  })
+
+  it('should parse atlas tag args', () => {
+    const capturedCtx: TagContext[] = []
+    const plugin = createMockPlugin((ctx) => {
+      capturedCtx.push(ctx)
+      return undefined
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    compile({
+      source: '',
+      filePath: 'test.sql',
+      plugins,
+      statements: [],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+      atlasRealm: mockRealm,
+    })
+
+    const auditCall = capturedCtx.find((c) => c.tag.name === 'track')
+    expect(auditCall).toBeDefined()
+    // Args should be parsed from the Atlas tag args string
+    expect(auditCall!.tag.args).toBeDefined()
+  })
+})
+
+describe('compile() Tier 1 (no Atlas realm)', () => {
+  it('should still use block resolution when no atlasRealm provided', () => {
+    // Source with tags that block resolution can handle
+    const source = `-- @audit.track
+CREATE TABLE users (id bigserial PRIMARY KEY);`
+
+    const plugin = createMockPlugin((ctx) => {
+      return [{ sql: `-- audited: ${ctx.objectName}` }]
+    })
+
+    const plugins = new Map<string, NamespacePlugin>([['audit', plugin]])
+
+    // No atlasRealm -- Tier 1 mode
+    const result = compile({
+      source,
+      filePath: 'test.sql',
+      plugins,
+      statements: [
+        {
+          objectName: 'users',
+          kind: 'table',
+          line: 2,
+          raw: null,
+          columns: [{ name: 'id', dataType: 'bigserial', line: 2, raw: null }],
+        },
+      ],
+      adapter: mockAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    // Should still produce output via block resolution
+    expect(result.sqlOutputs.length).toBeGreaterThan(0)
+  })
+})