@sqldoc/core 0.0.1

package/src/__tests__/compiler/compile.test.ts

@@ -0,0 +1,363 @@
+import { describe, expect, it } from 'vitest'
+import type { SqlAstAdapter } from '../../ast/adapter'
+import type { SqlStatement } from '../../ast/types'
+import { compile } from '../../compiler/compile'
+import type { NamespacePlugin, ResolvedConfig } from '../../compiler/types'
+
+/** Stub adapter that returns no comments */
+const stubAdapter: SqlAstAdapter = {
+  async init() {},
+  parseStatements() {
+    return []
+  },
+  parseComments() {
+    return []
+  },
+}
+
+// ── Test helpers ─────────────────────────────────────────────────────
+
+function makePlugin(overrides: Partial<NamespacePlugin> & { name: string }): NamespacePlugin {
+  return {
+    apiVersion: 1,
+    tags: {},
+    ...overrides,
+  }
+}
+
+/** Helper to get 1-based line number of a substring in source */
+function lineOf(source: string, search: string): number {
+  const idx = source.indexOf(search)
+  if (idx === -1) return 1
+  return source.substring(0, idx).split('\n').length
+}
+
+function makeStatements(stmts: Partial<SqlStatement>[]): SqlStatement[] {
+  return stmts.map((s, _i) => ({
+    kind: s.kind ?? 'table',
+    objectName: s.objectName ?? 'unknown',
+    line: s.line ?? 1,
+    columns: s.columns,
+    raw: s.raw ?? null,
+  }))
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('compile()', () => {
+  it('returns SqlOutput[] in CompilerOutput.sqlOutputs from generateSQL', () => {
+    const plugin = makePlugin({
+      name: 'test',
+      tags: { label: { args: [{ type: 'string' }] } },
+      generateSQL: (ctx) => [{ sql: `-- generated for ${ctx.objectName}` }],
+    })
+
+    const source = ["-- @test.label('users-table')", 'CREATE TABLE users (', '  id SERIAL PRIMARY KEY', ');'].join('\n')
+
+    const result = compile({
+      source,
+      filePath: 'test.sql',
+      plugins: new Map([['test', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'users', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(result.sqlOutputs).toHaveLength(1)
+    expect(result.sqlOutputs[0].sql).toBe('-- generated for users')
+    expect(result.sourceFile).toBe('test.sql')
+    // mergedSql should contain original source + generated SQL
+    expect(result.mergedSql).toContain('CREATE TABLE users')
+    expect(result.mergedSql).toContain('-- generated for users')
+    expect(result.mergedSql).toContain('-- Generated by sqldoc')
+  })
+
+  it('returns CodeOutput[] in CompilerOutput.codeOutputs from generateCode', () => {
+    const plugin = makePlugin({
+      name: 'codegen',
+      tags: { types: {} },
+      generateCode: (ctx) => [{ filePath: `${ctx.objectName}.ts`, content: `export type ${ctx.objectName} = {}` }],
+    })
+
+    const source = ['-- @codegen.types', 'CREATE TABLE orders (', '  id SERIAL', ');'].join('\n')
+
+    const result = compile({
+      source,
+      filePath: 'orders.sql',
+      plugins: new Map([['codegen', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'orders', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(result.codeOutputs).toHaveLength(1)
+    expect(result.codeOutputs[0].filePath).toBe('orders.ts')
+    expect(result.codeOutputs[0].content).toBe('export type orders = {}')
+  })
+
+  it('populates CompilerContext.siblingTags with tags from other namespaces on same object', () => {
+    let capturedCtx: any = null
+
+    const pluginA = makePlugin({
+      name: 'alpha',
+      tags: { run: {} },
+      generateSQL: (ctx) => {
+        capturedCtx = ctx
+        return []
+      },
+    })
+
+    const pluginB = makePlugin({
+      name: 'beta',
+      tags: { check: { args: [{ type: 'string' }] } },
+    })
+
+    const source = ['-- @alpha.run', "-- @beta.check('strict')", 'CREATE TABLE products (', '  id SERIAL', ');'].join(
+      '\n',
+    )
+
+    compile({
+      source,
+      filePath: 'products.sql',
+      plugins: new Map([
+        ['alpha', pluginA],
+        ['beta', pluginB],
+      ]),
+      statements: makeStatements([{ kind: 'table', objectName: 'products', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(capturedCtx).not.toBeNull()
+    expect(capturedCtx.siblingTags).toEqual(
+      expect.arrayContaining([expect.objectContaining({ namespace: 'beta', tag: 'check' })]),
+    )
+    // siblingTags should include tags from ALL namespaces (including own)
+    expect(capturedCtx.siblingTags).toEqual(
+      expect.arrayContaining([expect.objectContaining({ namespace: 'alpha', tag: 'run' })]),
+    )
+  })
+
+  it('populates CompilerContext.fileTags with all tags across file grouped by object', () => {
+    let capturedCtx: any = null
+
+    const plugin = makePlugin({
+      name: 'ns',
+      tags: { a: {}, b: {} },
+      generateSQL: (ctx) => {
+        capturedCtx = ctx
+        return []
+      },
+    })
+
+    const source = [
+      '-- @ns.a',
+      'CREATE TABLE t1 (',
+      '  id SERIAL',
+      ');',
+      '',
+      '-- @ns.b',
+      'CREATE TABLE t2 (',
+      '  id SERIAL',
+      ');',
+    ].join('\n')
+
+    compile({
+      source,
+      filePath: 'multi.sql',
+      plugins: new Map([['ns', plugin]]),
+      statements: makeStatements([
+        { kind: 'table', objectName: 't1', line: lineOf(source, 'CREATE TABLE t1') },
+        { kind: 'table', objectName: 't2', line: lineOf(source, 'CREATE TABLE t2') },
+      ]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(capturedCtx).not.toBeNull()
+    expect(capturedCtx.fileTags).toHaveLength(2)
+    expect(capturedCtx.fileTags).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ objectName: 't1' }),
+        expect.objectContaining({ objectName: 't2' }),
+      ]),
+    )
+  })
+
+  it('populates CompilerContext.config with namespace-specific config from ProjectConfig', () => {
+    let capturedCtx: any = null
+
+    const plugin = makePlugin({
+      name: 'myns',
+      tags: { go: {} },
+      generateSQL: (ctx) => {
+        capturedCtx = ctx
+        return []
+      },
+    })
+
+    const source = ['-- @myns.go', 'CREATE TABLE cfg_test (id SERIAL);'].join('\n')
+
+    const config: ResolvedConfig = {
+      dialect: 'postgres',
+      namespaces: {
+        myns: { outputFormat: 'json', verbose: true },
+      },
+    }
+
+    compile({
+      source,
+      filePath: 'cfg.sql',
+      plugins: new Map([['myns', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'cfg_test', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config,
+    })
+
+    expect(capturedCtx).not.toBeNull()
+    expect(capturedCtx.config).toEqual({ outputFormat: 'json', verbose: true })
+  })
+
+  it('populates CompilerContext.namespaceTags with same-namespace tags on same object', () => {
+    let capturedCtx: any = null
+
+    const plugin = makePlugin({
+      name: 'multi',
+      tags: { first: {}, second: { args: [{ type: 'number' }] } },
+      generateSQL: (ctx) => {
+        if (ctx.tag.name === 'first') capturedCtx = ctx
+        return []
+      },
+    })
+
+    const source = ['-- @multi.first', '-- @multi.second(42)', 'CREATE TABLE nstags (id SERIAL);'].join('\n')
+
+    compile({
+      source,
+      filePath: 'nstags.sql',
+      plugins: new Map([['multi', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'nstags', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(capturedCtx).not.toBeNull()
+    expect(capturedCtx.namespaceTags).toHaveLength(2)
+    expect(capturedCtx.namespaceTags).toEqual(
+      expect.arrayContaining([expect.objectContaining({ tag: 'first' }), expect.objectContaining({ tag: 'second' })]),
+    )
+  })
+
+  it('correctly matches column tags when blank lines separate columns inside a table', () => {
+    const contexts: any[] = []
+
+    const plugin = makePlugin({
+      name: 'ns',
+      tags: { mark: {} },
+      generateSQL: (ctx) => {
+        contexts.push({ target: ctx.target, objectName: ctx.objectName, columnName: ctx.columnName })
+        return [{ sql: `-- marked ${ctx.columnName ?? ctx.objectName}` }]
+      },
+    })
+
+    const source = [
+      '-- @ns.mark',
+      'CREATE TABLE items (',
+      '    id SERIAL PRIMARY KEY,',
+      '',
+      '    -- @ns.mark',
+      '    name TEXT NOT NULL,',
+      '',
+      '    -- @ns.mark',
+      '    price INTEGER',
+      ');',
+    ].join('\n')
+
+    const _result = compile({
+      source,
+      filePath: 'blank-lines.sql',
+      plugins: new Map([['ns', plugin]]),
+      statements: makeStatements([
+        {
+          kind: 'table',
+          objectName: 'items',
+          line: lineOf(source, 'CREATE TABLE items'),
+          columns: [
+            { name: 'id', dataType: 'serial', line: lineOf(source, 'id SERIAL'), raw: null },
+            { name: 'name', dataType: 'text', line: lineOf(source, 'name TEXT'), raw: null },
+            { name: 'price', dataType: 'integer', line: lineOf(source, 'price INTEGER'), raw: null },
+          ],
+        },
+      ]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    // First tag is above CREATE TABLE — should be table-level
+    expect(contexts[0]).toEqual(expect.objectContaining({ target: 'table', objectName: 'items' }))
+    // Second tag (after blank line) should match 'name' column
+    expect(contexts[1]).toEqual(expect.objectContaining({ target: 'column', columnName: 'name' }))
+    // Third tag (after blank line) should match 'price' column
+    expect(contexts[2]).toEqual(expect.objectContaining({ target: 'column', columnName: 'price' }))
+  })
+
+  it('catches generator errors and reports in CompilerOutput.errors without crashing', () => {
+    const plugin = makePlugin({
+      name: 'err',
+      tags: { boom: {} },
+      generateSQL: () => {
+        throw new Error('generator exploded')
+      },
+      generateCode: () => {
+        throw new Error('codegen failed')
+      },
+    })
+
+    const source = ['-- @err.boom', 'CREATE TABLE broken (id SERIAL);'].join('\n')
+
+    const result = compile({
+      source,
+      filePath: 'err.sql',
+      plugins: new Map([['err', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'broken', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(result.errors.length).toBeGreaterThanOrEqual(1)
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ namespace: 'err', message: expect.stringContaining('generator exploded') }),
+      ]),
+    )
+    // Should not have any outputs from the errored generators
+    expect(result.sqlOutputs).toHaveLength(0)
+    expect(result.codeOutputs).toHaveLength(0)
+  })
+
+  it('returns empty outputs with no crash when plugins have no generators', () => {
+    const plugin = makePlugin({
+      name: 'passive',
+      tags: { info: {} },
+      // No generateSQL or generateCode
+    })
+
+    const source = ['-- @passive.info', 'CREATE TABLE inert (id SERIAL);'].join('\n')
+
+    const result = compile({
+      source,
+      filePath: 'inert.sql',
+      plugins: new Map([['passive', plugin]]),
+      statements: makeStatements([{ kind: 'table', objectName: 'inert', line: lineOf(source, 'CREATE') }]),
+      adapter: stubAdapter,
+      config: { dialect: 'postgres' },
+    })
+
+    expect(result.sqlOutputs).toHaveLength(0)
+    expect(result.codeOutputs).toHaveLength(0)
+    expect(result.errors).toHaveLength(0)
+    expect(result.sourceFile).toBe('inert.sql')
+    // mergedSql should be just the original source when no SQL generated
+    expect(result.mergedSql).toBe(source)
+  })
+})

package/src/__tests__/lint-rules.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it } from 'vitest'
+// Import the actual plugins to test their built-in lint rules
+import auditPlugin from '../../../ns-audit/src/index.ts'
+import rlsPlugin from '../../../ns-rls/src/index'
+import validatePlugin from '../../../ns-validate/src/index'
+import type { CompilerOutput, NamespacePlugin, ResolvedConfig } from '../compiler/types'
+import { lint } from '../lint'
+
+/** Helper to create a minimal CompilerOutput */
+function makeOutput(overrides: Partial<CompilerOutput> = {}): CompilerOutput {
+  return {
+    sourceFile: 'schema.sql',
+    mergedSql: '',
+    sqlOutputs: [],
+    codeOutputs: [],
+    errors: [],
+    docsMeta: [],
+    fileTags: [],
+    ...overrides,
+  }
+}
+
+describe('built-in lint rules', () => {
+  describe('audit.require-audit', () => {
+    it('flags tables without @audit tag', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('audit', auditPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+          {
+            objectName: 'orders',
+            target: 'table',
+            tags: [],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(2)
+      expect(results[0].ruleName).toBe('audit.require-audit')
+      expect(results[0].objectName).toBe('users')
+      expect(results[0].message).toContain('users')
+      expect(results[1].objectName).toBe('orders')
+    })
+
+    it('does not flag tables that have @audit', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('audit', auditPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [{ namespace: 'audit', tag: null, args: {} }],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(0)
+    })
+
+    it('does not flag tables that have @audit with $self tag', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('audit', auditPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [{ namespace: 'audit', tag: '$self', args: {} }],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(0)
+    })
+
+    it('ignores column-level fileTags', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('audit', auditPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users.email',
+            target: 'column',
+            tags: [],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(0)
+    })
+  })
+
+  describe('rls.require-policy', () => {
+    it('flags tables without @rls tag', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('rls', rlsPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(1)
+      expect(results[0].ruleName).toBe('rls.require-policy')
+      expect(results[0].message).toContain('users')
+    })
+
+    it('does not flag tables with @rls', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('rls', rlsPlugin)
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [{ namespace: 'rls', tag: null, args: {} }],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(0)
+    })
+  })
+
+  describe('validate.require-pk', () => {
+    it('flags tables without a primary key in SQL', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('validate', validatePlugin)
+
+      const output = makeOutput({
+        mergedSql: `CREATE TABLE users (
+  name TEXT NOT NULL,
+  email TEXT
+);`,
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(1)
+      expect(results[0].ruleName).toBe('validate.require-pk')
+      expect(results[0].message).toContain('users')
+    })
+
+    it('does not flag tables with a primary key', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('validate', validatePlugin)
+
+      const output = makeOutput({
+        mergedSql: `CREATE TABLE users (
+  id BIGSERIAL PRIMARY KEY,
+  name TEXT NOT NULL
+);`,
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, { dialect: 'postgres' })
+      expect(results).toHaveLength(0)
+    })
+  })
+
+  describe('end-to-end: multiple plugins + config + ignore', () => {
+    it('applies all rules, config overrides, and @lint.ignore together', () => {
+      const plugins = new Map<string, NamespacePlugin>()
+      plugins.set('audit', auditPlugin)
+      plugins.set('rls', rlsPlugin)
+
+      const config: ResolvedConfig = {
+        dialect: 'postgres',
+        lint: {
+          rules: {
+            'audit.require-audit': 'error', // upgrade from warn
+          },
+        },
+      }
+
+      const output = makeOutput({
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [],
+          },
+          {
+            objectName: 'staging_data',
+            target: 'table',
+            tags: [
+              { namespace: 'lint', tag: 'ignore', args: ['audit.require-audit', 'Staging table'] },
+              { namespace: 'lint', tag: 'ignore', args: ['rls.require-policy', 'Internal only'] },
+            ],
+          },
+        ],
+      })
+
+      const results = lint([output], plugins, config)
+
+      // users: audit.require-audit (error), rls.require-policy (warn)
+      // staging_data: audit.require-audit (skip), rls.require-policy (skip)
+      expect(results).toHaveLength(4)
+
+      const usersAudit = results.find((r) => r.objectName === 'users' && r.ruleName === 'audit.require-audit')
+      expect(usersAudit!.severity).toBe('error')
+
+      const usersRls = results.find((r) => r.objectName === 'users' && r.ruleName === 'rls.require-policy')
+      expect(usersRls!.severity).toBe('warn')
+
+      const stagingAudit = results.find((r) => r.objectName === 'staging_data' && r.ruleName === 'audit.require-audit')
+      expect(stagingAudit!.severity).toBe('skip')
+      expect(stagingAudit!.ignoreReason).toBe('Staging table')
+
+      const stagingRls = results.find((r) => r.objectName === 'staging_data' && r.ruleName === 'rls.require-policy')
+      expect(stagingRls!.severity).toBe('skip')
+      expect(stagingRls!.ignoreReason).toBe('Internal only')
+    })
+  })
+})