@sqldoc/core 0.0.1

package/src/__tests__/lint.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest'
+import type { CompilerOutput, LintRule, NamespacePlugin, ResolvedConfig } from '../compiler/types'
+import { lint } from '../lint'
+
+/** Helper to create a minimal CompilerOutput */
+function makeOutput(overrides: Partial<CompilerOutput> = {}): CompilerOutput {
+  return {
+    sourceFile: 'test.sql',
+    mergedSql: '',
+    sqlOutputs: [],
+    codeOutputs: [],
+    errors: [],
+    docsMeta: [],
+    fileTags: [],
+    ...overrides,
+  }
+}
+
+/** Helper to create a minimal NamespacePlugin with lint rules */
+function makePlugin(name: string, lintRules: LintRule[]): NamespacePlugin {
+  return {
+    apiVersion: 1,
+    name,
+    tags: {},
+    lintRules,
+  }
+}
+
+describe('lint engine', () => {
+  it('returns empty results when no plugins have lint rules', () => {
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', { apiVersion: 1, name: 'test', tags: {} })
+
+    const results = lint([makeOutput()], plugins, { dialect: 'postgres' })
+    expect(results).toEqual([])
+  })
+
+  it('runs lint rules from plugins and returns diagnostics', () => {
+    const rule: LintRule = {
+      name: 'test.always-fail',
+      description: 'Always produces a diagnostic',
+      default: 'warn',
+      check: () => [{ objectName: 'users', sourceFile: 'test.sql', message: 'Test failure' }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', makePlugin('test', [rule]))
+
+    const results = lint([makeOutput()], plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(1)
+    expect(results[0]).toEqual({
+      ruleName: 'test.always-fail',
+      severity: 'warn',
+      objectName: 'users',
+      sourceFile: 'test.sql',
+      message: 'Test failure',
+    })
+  })
+
+  it('applies severity override from config', () => {
+    const rule: LintRule = {
+      name: 'test.check',
+      description: 'Test rule',
+      default: 'warn',
+      check: () => [{ objectName: 'orders', sourceFile: 'schema.sql', message: 'Missing thing' }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', makePlugin('test', [rule]))
+
+    const config: ResolvedConfig = {
+      dialect: 'postgres',
+      lint: {
+        rules: { 'test.check': 'error' },
+      },
+    }
+
+    const results = lint([makeOutput({ sourceFile: 'schema.sql' })], plugins, config)
+    expect(results).toHaveLength(1)
+    expect(results[0].severity).toBe('error')
+  })
+
+  it('skips rules set to "off" in config', () => {
+    const rule: LintRule = {
+      name: 'test.check',
+      description: 'Test rule',
+      default: 'error',
+      check: () => [{ objectName: 'users', sourceFile: 'test.sql', message: 'Should not appear' }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', makePlugin('test', [rule]))
+
+    const config: ResolvedConfig = {
+      dialect: 'postgres',
+      lint: {
+        rules: { 'test.check': 'off' },
+      },
+    }
+
+    const results = lint([makeOutput()], plugins, config)
+    expect(results).toHaveLength(0)
+  })
+
+  it('respects @lint.ignore tags and marks results as "skip"', () => {
+    const rule: LintRule = {
+      name: 'audit.require-audit',
+      description: 'Tables should have @audit',
+      default: 'warn',
+      check: () => [{ objectName: 'events', sourceFile: 'test.sql', message: "Table 'events' has no @audit tag" }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('audit', makePlugin('audit', [rule]))
+
+    const output = makeOutput({
+      sourceFile: 'test.sql',
+      fileTags: [
+        {
+          objectName: 'events',
+          target: 'table',
+          tags: [{ namespace: 'lint', tag: 'ignore', args: ['audit.require-audit', 'Temporary staging table'] }],
+        },
+      ],
+    })
+
+    const results = lint([output], plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(1)
+    expect(results[0].severity).toBe('skip')
+    expect(results[0].ignoreReason).toBe('Temporary staging table')
+    expect(results[0].message).toBe("Table 'events' has no @audit tag")
+  })
+
+  it('does not ignore when @lint.ignore targets a different rule', () => {
+    const rule: LintRule = {
+      name: 'audit.require-audit',
+      description: 'Tables should have @audit',
+      default: 'warn',
+      check: () => [{ objectName: 'events', sourceFile: 'test.sql', message: "Table 'events' has no @audit tag" }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('audit', makePlugin('audit', [rule]))
+
+    const output = makeOutput({
+      sourceFile: 'test.sql',
+      fileTags: [
+        {
+          objectName: 'events',
+          target: 'table',
+          tags: [{ namespace: 'lint', tag: 'ignore', args: ['rls.require-policy', 'Not needed'] }],
+        },
+      ],
+    })
+
+    const results = lint([output], plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(1)
+    expect(results[0].severity).toBe('warn')
+  })
+
+  it('collects rules from multiple plugins', () => {
+    const rule1: LintRule = {
+      name: 'audit.require-audit',
+      description: 'Need audit',
+      default: 'warn',
+      check: () => [{ objectName: 'users', sourceFile: 'test.sql', message: 'No audit' }],
+    }
+
+    const rule2: LintRule = {
+      name: 'rls.require-policy',
+      description: 'Need RLS',
+      default: 'error',
+      check: () => [{ objectName: 'users', sourceFile: 'test.sql', message: 'No RLS' }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('audit', makePlugin('audit', [rule1]))
+    plugins.set('rls', makePlugin('rls', [rule2]))
+
+    const results = lint([makeOutput()], plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(2)
+    expect(results.map((r) => r.ruleName)).toEqual(['audit.require-audit', 'rls.require-policy'])
+    expect(results[0].severity).toBe('warn')
+    expect(results[1].severity).toBe('error')
+  })
+
+  it('handles multiple outputs (files) correctly', () => {
+    const rule: LintRule = {
+      name: 'test.check',
+      description: 'Test rule',
+      default: 'warn',
+      check: (ctx) => {
+        const diags = []
+        for (const output of ctx.outputs) {
+          for (const obj of output.fileTags) {
+            if (obj.target === 'table' && !obj.objectName.includes('.')) {
+              diags.push({
+                objectName: obj.objectName,
+                sourceFile: output.sourceFile,
+                message: `Missing on ${obj.objectName}`,
+              })
+            }
+          }
+        }
+        return diags
+      },
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', makePlugin('test', [rule]))
+
+    const outputs = [
+      makeOutput({
+        sourceFile: 'a.sql',
+        fileTags: [{ objectName: 'users', target: 'table', tags: [] }],
+      }),
+      makeOutput({
+        sourceFile: 'b.sql',
+        fileTags: [{ objectName: 'orders', target: 'table', tags: [] }],
+      }),
+    ]
+
+    const results = lint(outputs, plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(2)
+    expect(results[0].sourceFile).toBe('a.sql')
+    expect(results[0].objectName).toBe('users')
+    expect(results[1].sourceFile).toBe('b.sql')
+    expect(results[1].objectName).toBe('orders')
+  })
+
+  it('does not match @lint.ignore across different files', () => {
+    const rule: LintRule = {
+      name: 'test.check',
+      description: 'Test rule',
+      default: 'warn',
+      check: () => [{ objectName: 'users', sourceFile: 'b.sql', message: 'Problem in b.sql' }],
+    }
+
+    const plugins = new Map<string, NamespacePlugin>()
+    plugins.set('test', makePlugin('test', [rule]))
+
+    const outputs = [
+      makeOutput({
+        sourceFile: 'a.sql',
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [{ namespace: 'lint', tag: 'ignore', args: ['test.check', 'Reason'] }],
+          },
+        ],
+      }),
+      makeOutput({
+        sourceFile: 'b.sql',
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+        ],
+      }),
+    ]
+
+    const results = lint(outputs, plugins, { dialect: 'postgres' })
+    expect(results).toHaveLength(1)
+    // The ignore is in a.sql but the diagnostic is in b.sql, so it should NOT be skipped
+    expect(results[0].severity).toBe('warn')
+  })
+})

package/src/__tests__/parser.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest'
+import { parse, parseArgs } from '../parser'
+
+describe('parse', () => {
+  it('extracts @import with single-quoted path', () => {
+    const result = parse("-- @import './anon.ts'")
+    expect(result.imports).toHaveLength(1)
+    expect(result.imports[0].path).toBe('./anon.ts')
+    expect(result.imports[0].line).toBe(0)
+  })
+
+  it('extracts @import with double-quoted path', () => {
+    const result = parse('-- @import "./rls.ts"')
+    expect(result.imports).toHaveLength(1)
+    expect(result.imports[0].path).toBe('./rls.ts')
+  })
+
+  it('extracts multiple @import lines with correct line numbers', () => {
+    const doc = `-- @import './anon.ts'\n-- @import './rls.ts'`
+    const result = parse(doc)
+    expect(result.imports).toHaveLength(2)
+    expect(result.imports[0].line).toBe(0)
+    expect(result.imports[0].path).toBe('./anon.ts')
+    expect(result.imports[1].line).toBe(1)
+    expect(result.imports[1].path).toBe('./rls.ts')
+  })
+
+  it('extracts namespace.tag(args) from comment line', () => {
+    const result = parse('-- @anon.mask(type: email)')
+    expect(result.tags).toHaveLength(1)
+    expect(result.tags[0].namespace).toBe('anon')
+    expect(result.tags[0].tag).toBe('mask')
+    expect(result.tags[0].rawArgs).toBe('type: email')
+  })
+
+  it('extracts standalone namespace tag (no dot, no args)', () => {
+    const result = parse('-- @searchable')
+    expect(result.tags).toHaveLength(1)
+    expect(result.tags[0].namespace).toBe('searchable')
+    expect(result.tags[0].tag).toBeNull()
+    expect(result.tags[0].rawArgs).toBeNull()
+  })
+
+  it('extracts namespace.tag with complex named args', () => {
+    const result = parse("-- @rls.policy(name: 'users_read', check: true)")
+    expect(result.tags).toHaveLength(1)
+    expect(result.tags[0].namespace).toBe('rls')
+    expect(result.tags[0].tag).toBe('policy')
+    expect(result.tags[0].rawArgs).toBe("name: 'users_read', check: true")
+  })
+
+  it('ignores tags outside of comment lines', () => {
+    const doc = `@anon.mask(type: email)\nCREATE TABLE users (\n  id BIGSERIAL\n);`
+    const result = parse(doc)
+    expect(result.tags).toHaveLength(0)
+  })
+
+  it('extracts multiple tags on consecutive comment lines with correct line numbers', () => {
+    const doc = `-- @anon.mask(type: email)\n-- @searchable\nCREATE TABLE users (\n  id BIGSERIAL\n);`
+    const result = parse(doc)
+    expect(result.tags).toHaveLength(2)
+    expect(result.tags[0].line).toBe(0)
+    expect(result.tags[0].namespace).toBe('anon')
+    expect(result.tags[1].line).toBe(1)
+    expect(result.tags[1].namespace).toBe('searchable')
+  })
+
+  it('separates imports from tags (import not in tags array)', () => {
+    const doc = `-- @import './foo.ts'\n-- @anon.mask`
+    const result = parse(doc)
+    expect(result.imports).toHaveLength(1)
+    expect(result.tags).toHaveLength(1)
+    expect(result.tags[0].namespace).toBe('anon')
+  })
+
+  it('sets correct position fields for namespace and tag spans', () => {
+    const result = parse('-- @anon.mask(type: email)')
+    const tag = result.tags[0]
+    // "-- @anon.mask(type: email)"
+    //     ^   = index 3 = startCol of full match (@anon.mask(...))
+    //      ^^^^  namespace "anon" starts at 4 (after @)
+    expect(tag.namespaceStart).toBe(4)
+    expect(tag.namespaceEnd).toBe(8) // 4 + "anon".length
+    expect(tag.tagStart).toBe(9) // after the dot
+    expect(tag.tagEnd).toBe(13) // 9 + "mask".length
+  })
+
+  it('correctly handles import startCol and endCol', () => {
+    const result = parse("-- @import './anon.ts'")
+    expect(result.imports[0].startCol).toBe(0)
+    expect(result.imports[0].endCol).toBe("-- @import './anon.ts'".length)
+  })
+
+  it('handles a realistic multi-line SQL document', () => {
+    const doc = `-- @import './anon.ts'
+-- @anon.mask(type: email)
+CREATE TABLE users (
+  id BIGSERIAL PRIMARY KEY,
+  email TEXT NOT NULL
+);`
+    const result = parse(doc)
+    expect(result.imports).toHaveLength(1)
+    expect(result.imports[0].path).toBe('./anon.ts')
+    expect(result.tags).toHaveLength(1)
+    expect(result.tags[0].namespace).toBe('anon')
+    expect(result.tags[0].tag).toBe('mask')
+    expect(result.tags[0].line).toBe(1)
+  })
+
+  it('returns empty results for plain SQL with no tags or imports', () => {
+    const doc = `CREATE TABLE users (\n  id BIGSERIAL\n);`
+    const result = parse(doc)
+    expect(result.imports).toHaveLength(0)
+    expect(result.tags).toHaveLength(0)
+  })
+
+  it('correctly sets argsStart and argsEnd for tag arguments', () => {
+    const result = parse('-- @anon.mask(type: email)')
+    const tag = result.tags[0]
+    expect(tag.rawArgs).toBe('type: email')
+    // argsStart should be the index right after '('
+    // argsEnd should be argsStart + rawArgs.length
+    expect(tag.argsEnd - tag.argsStart).toBe('type: email'.length)
+  })
+})
+
+describe('parseArgs', () => {
+  it('parses named args with string value', () => {
+    const result = parseArgs('type: email')
+    expect(result.type).toBe('named')
+    expect(result.values).toEqual({ type: 'email' })
+  })
+
+  it('parses positional args (comma-separated)', () => {
+    const result = parseArgs('email, name')
+    expect(result.type).toBe('positional')
+    expect(result.values).toEqual(['email', 'name'])
+  })
+
+  it('parses named args with numeric value', () => {
+    const result = parseArgs('count: 42')
+    expect(result.type).toBe('named')
+    expect(result.values).toEqual({ count: 42 })
+  })
+
+  it('parses named args with boolean value', () => {
+    const result = parseArgs('enabled: true')
+    expect(result.type).toBe('named')
+    expect(result.values).toEqual({ enabled: true })
+  })
+
+  it('parses positional array arg', () => {
+    const result = parseArgs('[a, b, c]')
+    expect(result.type).toBe('positional')
+    expect(result.values).toEqual([['a', 'b', 'c']])
+  })
+
+  it('returns empty positional for empty string', () => {
+    const result = parseArgs('')
+    expect(result.type).toBe('positional')
+    expect(result.values).toEqual([])
+  })
+
+  it('strips quotes from quoted string values', () => {
+    const result = parseArgs("'hello'")
+    expect(result.type).toBe('positional')
+    expect(result.values).toEqual(['hello'])
+  })
+})

package/src/__tests__/tags.sql

@@ -0,0 +1,15 @@
+-- @for("one")
+create table one ( -- @for("one again")
+
+    -- @for("two")
+    two text, -- @for("two again")
+    three text, -- @for("three")
+
+    -- @for("four")
+
+
+four numeric
+
+    -- @for("one yet again")
+
+)

package/src/__tests__/validator.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest'
+import { parse } from '../parser'
+import type { TagDef, TagNamespace } from '../types'
+import { detectTargetFallback, validate } from '../validator'
+
+// ── Test namespace fixtures ──────────────────────────────────────────
+
+const maskDef: TagDef = {
+  description: 'Mask column data',
+  targets: ['column'],
+  args: { type: { type: 'string', required: true } },
+}
+
+const policyDef: TagDef = {
+  description: 'RLS policy',
+  targets: ['table'],
+  args: { name: { type: 'string', required: true }, check: { type: 'boolean' } },
+}
+
+const selfDef: TagDef = {
+  description: 'Mark as searchable',
+  targets: ['table', 'column'],
+}
+
+const anonNamespace: TagNamespace = {
+  name: 'anon',
+  tags: { mask: maskDef },
+}
+
+const searchableNamespace: TagNamespace = {
+  name: 'searchable',
+  tags: { $self: selfDef, fulltext: { description: 'Full text search', targets: ['column'] } },
+}
+
+const _rlsNamespace: TagNamespace = {
+  name: 'rls',
+  tags: { policy: policyDef },
+}
+
+function makeNamespaces(...entries: TagNamespace[]): Map<string, TagNamespace> {
+  const map = new Map<string, TagNamespace>()
+  for (const ns of entries) map.set(ns.name, ns)
+  return map
+}
+
+// ── Helper: parse and validate in one call ───────────────────────────
+
+function parseAndValidate(docText: string, namespaces: Map<string, TagNamespace>) {
+  const { tags } = parse(docText)
+  return validate(tags, namespaces, docText)
+}
+
+// ── validate() tests ─────────────────────────────────────────────────
+
+describe('validate', () => {
+  it('reports unknown namespace for unregistered namespace', () => {
+    const doc = `-- @bogus.tag\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces())
+    expect(diags).toHaveLength(1)
+    expect(diags[0].message).toContain("Unknown namespace '@bogus'")
+    expect(diags[0].severity).toBe('error')
+  })
+
+  it('reports unknown tag for tag not in namespace definition', () => {
+    const doc = `-- @anon.bogus\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    expect(diags).toHaveLength(1)
+    expect(diags[0].message).toContain("Unknown tag 'bogus' in namespace 'anon'")
+    expect(diags[0].severity).toBe('error')
+  })
+
+  it('reports error when standalone tag used without $self defined', () => {
+    const doc = `-- @anon\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    expect(diags).toHaveLength(1)
+    expect(diags[0].message).toContain('cannot be used as a standalone tag')
+  })
+
+  it('produces no diagnostic when standalone tag has $self defined', () => {
+    const doc = `-- @searchable\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(searchableNamespace))
+    expect(diags).toHaveLength(0)
+  })
+
+  it('reports target mismatch when tag is used on wrong SQL target', () => {
+    // mask targets=['column'] but placed above CREATE FUNCTION
+    const doc = `-- @anon.mask(type: email)\nCREATE OR REPLACE FUNCTION foo() RETURNS void AS $$ BEGIN END; $$ LANGUAGE plpgsql;`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const targetDiag = diags.find((d) => d.message.includes('cannot be used on a function'))
+    expect(targetDiag).toBeDefined()
+    expect(targetDiag!.severity).toBe('error')
+  })
+
+  it('produces no diagnostics for valid usage', () => {
+    const doc = `-- @anon.mask(type: email)\n  email TEXT NOT NULL`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    expect(diags).toHaveLength(0)
+  })
+
+  it('reports missing required named argument', () => {
+    // mask requires 'type' arg
+    const doc = `-- @anon.mask\n  email TEXT NOT NULL`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const argDiag = diags.find((d) => d.message.includes('Missing required argument'))
+    expect(argDiag).toBeDefined()
+  })
+
+  it('reports error when tag does not accept arguments but args provided', () => {
+    // searchable.$self has no args defined
+    const noArgsNs: TagNamespace = {
+      name: 'noargs',
+      tags: { simple: { description: 'No args tag' } },
+    }
+    const doc = `-- @noargs.simple(foo: bar)\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(noArgsNs))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const argDiag = diags.find((d) => d.message.includes('does not accept arguments'))
+    expect(argDiag).toBeDefined()
+  })
+
+  it('reports error when named args given but positional expected', () => {
+    const posNs: TagNamespace = {
+      name: 'pos',
+      tags: { order: { description: 'Order', args: [{ type: 'string' }] } },
+    }
+    const doc = `-- @pos.order(dir: asc)\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(posNs))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const argDiag = diags.find((d) => d.message.includes('expects positional arguments, not named'))
+    expect(argDiag).toBeDefined()
+  })
+
+  it('reports too many positional arguments', () => {
+    const posNs: TagNamespace = {
+      name: 'pos',
+      tags: { order: { description: 'Order', args: [{ type: 'string' }] } },
+    }
+    const doc = `-- @pos.order(asc, desc, extra)\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(posNs))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const argDiag = diags.find((d) => d.message.includes('Too many arguments'))
+    expect(argDiag).toBeDefined()
+  })
+
+  it('reports wrong arg type when tag expects number but gets string', () => {
+    const numNs: TagNamespace = {
+      name: 'num',
+      tags: { limit: { description: 'Limit', args: { count: { type: 'number', required: true } } } },
+    }
+    const doc = `-- @num.limit(count: abc)\nCREATE TABLE t (id INT);`
+    const diags = parseAndValidate(doc, makeNamespaces(numNs))
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const typeDiag = diags.find((d) => d.message.includes('expected number'))
+    expect(typeDiag).toBeDefined()
+  })
+
+  it('sets correct line numbers on diagnostics', () => {
+    const doc = `CREATE TABLE t (\n  -- @bogus.tag\n  id INT\n);`
+    const diags = parseAndValidate(doc, makeNamespaces())
+    expect(diags).toHaveLength(1)
+    expect(diags[0].line).toBe(1) // zero-indexed, second line
+  })
+
+  it('validates multiple tags in same block independently', () => {
+    const doc = `-- @anon.mask(type: email)\n-- @anon.bogus\n  email TEXT NOT NULL`
+    const diags = parseAndValidate(doc, makeNamespaces(anonNamespace))
+    // mask is valid on column, but bogus is unknown
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+    const unknownDiag = diags.find((d) => d.message.includes("Unknown tag 'bogus'"))
+    expect(unknownDiag).toBeDefined()
+  })
+})
+
+// ── detectTargetFallback() tests ─────────────────────────────────────
+
+describe('detectTargetFallback', () => {
+  it('detects CREATE TABLE', () => {
+    expect(detectTargetFallback(['CREATE TABLE users ('])).toBe('table')
+  })
+
+  it('detects CREATE OR REPLACE FUNCTION', () => {
+    expect(detectTargetFallback(['CREATE OR REPLACE FUNCTION foo()'])).toBe('function')
+  })
+
+  it('detects CREATE VIEW', () => {
+    expect(detectTargetFallback(['CREATE VIEW v AS'])).toBe('view')
+  })
+
+  it('detects CREATE UNIQUE INDEX', () => {
+    expect(detectTargetFallback(['CREATE UNIQUE INDEX idx ON t (c)'])).toBe('index')
+  })
+
+  it('detects CREATE TYPE', () => {
+    expect(detectTargetFallback(['CREATE TYPE mood AS ENUM'])).toBe('type')
+  })
+
+  it('detects CREATE TRIGGER', () => {
+    expect(detectTargetFallback(['CREATE TRIGGER t AFTER INSERT'])).toBe('trigger')
+  })
+
+  it('detects column from indented non-CREATE line', () => {
+    expect(detectTargetFallback(['  email TEXT NOT NULL'])).toBe('column')
+  })
+
+  it('returns unknown for empty array', () => {
+    expect(detectTargetFallback([])).toBe('unknown')
+  })
+})

package/src/ast/adapter.ts

@@ -0,0 +1,10 @@
+import type { SqlCommentOn, SqlStatement } from './types.ts'
+
+export interface SqlAstAdapter {
+  /** Initialize the parser (WASM loading, etc.) */
+  init(): Promise<void>
+  /** Parse SQL text and return normalized statements */
+  parseStatements(sql: string): SqlStatement[]
+  /** Parse COMMENT ON statements from SQL text */
+  parseComments(sql: string): SqlCommentOn[]
+}

package/src/ast/index.ts

@@ -0,0 +1,3 @@
+export type { SqlAstAdapter } from './adapter.ts'
+export { SqlparserTsAdapter } from './sqlparser-ts.ts'
+export type { SqlColumn, SqlCommentOn, SqlStatement } from './types.ts'