@sqldoc/ns-audit 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-audit",
+  "version": "0.0.1",
+  "description": "Audit namespace for sqldoc -- generates audit trigger functions and triggers",
+  "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"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@sqldoc/core": "0.0.1"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/__tests__/audit.test.ts

@@ -0,0 +1,156 @@
+import type { TagContext } from '@sqldoc/core'
+import { describe, expect, it } from 'vitest'
+import plugin from '../index'
+
+function makeCtx(overrides: Partial<TagContext> = {}): TagContext {
+  return {
+    target: 'table',
+    objectName: 'users',
+    tag: { name: '$self', args: {} },
+    namespaceTags: [],
+    siblingTags: [],
+    fileTags: [],
+    astNode: null,
+    fileStatements: [],
+    config: {},
+    filePath: 'test.sql',
+    ...overrides,
+  }
+}
+
+describe('ns-audit plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "audit"', () => {
+    expect(plugin.name).toBe('audit')
+  })
+
+  it('has $self and redact tag definitions', () => {
+    expect(plugin.tags).toHaveProperty('$self')
+    expect(plugin.tags).toHaveProperty('redact')
+  })
+
+  describe('onTag', () => {
+    it('@audit produces table + function + trigger (all ops by default)', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'orders',
+          tag: { name: null, args: {} },
+        }),
+      )
+      const sql = (result as any).sql
+      expect(sql).toHaveLength(3)
+
+      expect(sql[0].sql).toContain('CREATE TABLE IF NOT EXISTS "orders_audit_log"')
+      expect(sql[1].sql).toContain('CREATE OR REPLACE FUNCTION "orders_audit_fn"()')
+      expect(sql[1].sql).toContain('INSERT INTO "orders_audit_log"')
+      expect(sql[2].sql).toContain('AFTER INSERT OR UPDATE OR DELETE ON "orders"')
+    })
+
+    it('@audit(on: [update, delete]) uses specific operations', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'products',
+          tag: { name: null, args: { on: ['update', 'delete'] } },
+        }),
+      )
+      const sql = (result as any).sql
+
+      expect(sql[2].sql).toContain('AFTER UPDATE OR DELETE ON "products"')
+      expect(sql[2].sql).not.toContain('INSERT')
+    })
+
+    it('@audit(on: [insert]) handles NULL OLD', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'events',
+          tag: { name: null, args: { on: ['insert'] } },
+        }),
+      )
+      const sql = (result as any).sql
+
+      expect(sql[1].sql).toContain("CASE WHEN TG_OP = 'INSERT' THEN NULL ELSE row_to_json(OLD) END")
+    })
+
+    it('@audit(on: [delete]) handles NULL NEW', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'events',
+          tag: { name: null, args: { on: ['delete'] } },
+        }),
+      )
+      const sql = (result as any).sql
+
+      expect(sql[1].sql).toContain("CASE WHEN TG_OP = 'DELETE' THEN NULL ELSE row_to_json(NEW) END")
+    })
+
+    it('defaults destination to {objectName}_audit_log', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'users',
+          tag: { name: null, args: {} },
+        }),
+      )
+      const sql = (result as any).sql
+
+      expect(sql[0].sql).toContain('CREATE TABLE IF NOT EXISTS "users_audit_log"')
+      expect(sql[1].sql).toContain('INSERT INTO "users_audit_log"')
+    })
+
+    it('uses explicit destination', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          objectName: 'users',
+          tag: { name: null, args: { destination: 'custom_log' } },
+        }),
+      )
+      const sql = (result as any).sql
+
+      expect(sql[0].sql).toContain('CREATE TABLE IF NOT EXISTS "custom_log"')
+    })
+
+    it('@audit.redact produces no SQL', () => {
+      const result = plugin.onTag!(
+        makeCtx({
+          target: 'column',
+          tag: { name: 'redact', args: { strategy: 'hash' } },
+        }),
+      )
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('validation', () => {
+    it('@audit.redact without @audit errors', () => {
+      const result = plugin.tags!.redact.validate!({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { strategy: 'hash' },
+        objectName: 'users',
+      })
+      expect(result).toBe('@audit.redact requires @audit on the same table')
+    })
+
+    it('@audit.redact with @audit passes', () => {
+      const result = plugin.tags!.redact.validate!({
+        target: 'column',
+        lines: [],
+        siblingTags: [{ namespace: 'audit', tag: null, rawArgs: null }],
+        fileTags: [
+          {
+            objectName: 'users',
+            target: 'table',
+            tags: [{ namespace: 'audit', tag: null, rawArgs: null }],
+          },
+        ],
+        argValues: { strategy: 'hash' },
+        objectName: 'users',
+      })
+      expect(result).toBeUndefined()
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,140 @@
+import type { NamespacePlugin, SqlOutput, TagContext, TagOutput } from '@sqldoc/core'
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'audit',
+  tags: {
+    $self: {
+      description: 'Enable audit logging on this table',
+      targets: ['table'],
+      args: {
+        on: { type: 'array', items: { type: 'enum', values: ['insert', 'update', 'delete'] } },
+        destination: { type: 'string' },
+      },
+    },
+    redact: {
+      description: 'Mark this column for redaction in audit logs',
+      targets: ['column'],
+      args: {
+        strategy: { type: 'enum', values: ['hash', 'mask', 'omit'], required: true },
+      },
+      validate: (ctx) => {
+        // Check the parent table for @audit across the whole file
+        const objName = ctx.objectName?.toLowerCase()
+        const hasAudit = ctx.fileTags.some(
+          (ft) =>
+            ft.objectName.toLowerCase() === objName &&
+            ft.target === 'table' &&
+            ft.tags.some((t) => t.namespace === 'audit' && (t.tag === null || t.tag === '$self')),
+        )
+        if (!hasAudit) {
+          return '@audit.redact requires @audit on the same table'
+        }
+      },
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag, objectName } = ctx
+
+    if (tag.name === 'redact') return undefined
+    if (tag.name !== '$self' && tag.name !== null) return undefined
+
+    const args = tag.args as Record<string, unknown>
+    const operations = (args.on as string[] | undefined) ?? ['insert', 'update', 'delete']
+    const destination = (args.destination as string) || (ctx.config.destination as string) || `${objectName}_audit_log`
+
+    const ops = operations.map((op) => op.toUpperCase())
+    const triggerEvents = ops.join(' OR ')
+
+    const hasInsert = ops.includes('INSERT')
+    const hasDelete = ops.includes('DELETE')
+
+    let oldExpr = 'row_to_json(OLD)'
+    let newExpr = 'row_to_json(NEW)'
+    let returnExpr = 'RETURN NEW;'
+
+    if (hasInsert && !hasDelete) {
+      oldExpr = "CASE WHEN TG_OP = 'INSERT' THEN NULL ELSE row_to_json(OLD) END"
+    } else if (hasDelete && !hasInsert) {
+      newExpr = "CASE WHEN TG_OP = 'DELETE' THEN NULL ELSE row_to_json(NEW) END"
+      returnExpr = "RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;"
+    } else if (hasInsert && hasDelete) {
+      oldExpr = "CASE WHEN TG_OP = 'INSERT' THEN NULL ELSE row_to_json(OLD) END"
+      newExpr = "CASE WHEN TG_OP = 'DELETE' THEN NULL ELSE row_to_json(NEW) END"
+      returnExpr = "RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;"
+    }
+
+    const tableSql = `CREATE TABLE IF NOT EXISTS "${destination}" (
+  id BIGSERIAL PRIMARY KEY,
+  table_name TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  old_data JSONB,
+  new_data JSONB,
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);`
+
+    const fnSql = `CREATE OR REPLACE FUNCTION "${objectName}_audit_fn"() RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO "${destination}" (table_name, operation, old_data, new_data, changed_at)
+  VALUES (TG_TABLE_NAME, TG_OP, ${oldExpr}, ${newExpr}, now());
+  ${returnExpr}
+END;
+$$ LANGUAGE plpgsql;`
+
+    const triggerSql = `CREATE TRIGGER "${objectName}_audit_trigger"
+  AFTER ${triggerEvents} ON "${objectName}"
+  FOR EACH ROW EXECUTE FUNCTION "${objectName}_audit_fn"();`
+
+    const sql: SqlOutput[] = [{ sql: tableSql }, { sql: fnSql }, { sql: triggerSql }]
+
+    return {
+      sql,
+      docs: {
+        relationships: [
+          {
+            from: objectName,
+            to: destination,
+            label: 'audit events',
+            style: 'dashed',
+          },
+        ],
+        annotations: [
+          {
+            object: objectName,
+            text: `Audited (${operations.join(', ')})`,
+          },
+        ],
+      },
+    }
+  },
+
+  lintRules: [
+    {
+      name: 'audit.require-audit',
+      description: 'Tables should have an @audit tag',
+      default: 'warn',
+      check(ctx) {
+        const diagnostics = []
+        for (const output of ctx.outputs) {
+          // Collect all table-level objects
+          const tableObjects = output.fileTags.filter((obj) => obj.target === 'table' && !obj.objectName.includes('.'))
+
+          for (const obj of tableObjects) {
+            const hasAudit = obj.tags.some((t) => t.namespace === 'audit' && (t.tag === null || t.tag === '$self'))
+            if (!hasAudit) {
+              diagnostics.push({
+                objectName: obj.objectName,
+                sourceFile: output.sourceFile,
+                message: `Table '${obj.objectName}' has no @audit tag`,
+              })
+            }
+          }
+        }
+        return diagnostics
+      },
+    },
+  ],
+}
+
+export default plugin