@sqldoc/ns-anon 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-anon",
+  "version": "0.0.1",
+  "description": "PostgreSQL Anonymizer namespace for sqldoc -- generates SECURITY LABEL statements",
+  "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__/anon.test.ts

@@ -0,0 +1,94 @@
+import type { TagContext } from '@sqldoc/core'
+import { describe, expect, it } from 'vitest'
+import plugin from '../index'
+
+function makeCtx(overrides: Partial<TagContext> = {}): TagContext {
+  return {
+    target: 'column',
+    objectName: 'users',
+    columnName: 'email',
+    tag: { name: 'mask', args: ['anon.fake_email()'] },
+    namespaceTags: [],
+    siblingTags: [],
+    fileTags: [],
+    astNode: null,
+    fileStatements: [],
+    config: {},
+    filePath: 'test.sql',
+    ...overrides,
+  }
+}
+
+describe('ns-anon plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "anon"', () => {
+    expect(plugin.name).toBe('anon')
+  })
+
+  it('has mask, fake, and $self tag entries', () => {
+    expect(plugin.tags).toHaveProperty('mask')
+    expect(plugin.tags).toHaveProperty('fake')
+    expect(plugin.tags).toHaveProperty('$self')
+  })
+
+  describe('onTag', () => {
+    it('@anon.mask produces SECURITY LABEL statement', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        columnName: 'last_name',
+        tag: { name: 'mask', args: ['anon.fake_last_name()'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: `SECURITY LABEL FOR anon ON COLUMN "users"."last_name" IS 'MASKED WITH FUNCTION anon.fake_last_name()';`,
+        },
+      ])
+    })
+
+    it('@anon.fake produces SECURITY LABEL statement', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        columnName: 'email',
+        tag: { name: 'fake', args: ['anon.fake_email()'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: `SECURITY LABEL FOR anon ON COLUMN "users"."email" IS 'MASKED WITH FUNCTION anon.fake_email()';`,
+        },
+      ])
+    })
+
+    it('@anon.$self with no args on table returns undefined', () => {
+      const ctx = makeCtx({
+        target: 'table',
+        columnName: undefined,
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx)
+      expect(result).toBeUndefined()
+    })
+
+    it('mask with missing columnName returns undefined', () => {
+      const ctx = makeCtx({
+        columnName: undefined,
+        tag: { name: 'mask', args: ['anon.fake_last_name()'] },
+      })
+      const result = plugin.onTag!(ctx)
+      expect(result).toBeUndefined()
+    })
+
+    it('fake with missing columnName returns undefined', () => {
+      const ctx = makeCtx({
+        columnName: undefined,
+        tag: { name: 'fake', args: ['anon.fake_email()'] },
+      })
+      const result = plugin.onTag!(ctx)
+      expect(result).toBeUndefined()
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,63 @@
+import type { NamespacePlugin, TagContext, TagOutput } from '@sqldoc/core'
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'anon',
+  tags: {
+    mask: {
+      description: 'Mask this column using a PostgreSQL Anonymizer function',
+      targets: ['column'],
+      args: [{ type: 'string' }],
+    },
+    fake: {
+      description: 'Generate fake data for this column using a PostgreSQL Anonymizer function',
+      targets: ['column'],
+      args: [{ type: 'string' }],
+    },
+    $self: {
+      description: 'Mark this table as containing anonymizable data',
+      targets: ['table'],
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag, objectName, columnName } = ctx
+
+    switch (tag.name) {
+      case 'mask': {
+        if (!columnName) return undefined
+        const fnExpr = Array.isArray(tag.args) ? tag.args[0] : undefined
+        if (!fnExpr) return undefined
+        return {
+          sql: [
+            {
+              sql: `SECURITY LABEL FOR anon ON COLUMN "${objectName}"."${columnName}" IS 'MASKED WITH FUNCTION ${fnExpr}';`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Anonymization', object: objectName, column: columnName, value: `Masked: ${fnExpr}` }],
+          },
+        }
+      }
+      case 'fake': {
+        if (!columnName) return undefined
+        const fnExpr = Array.isArray(tag.args) ? tag.args[0] : undefined
+        if (!fnExpr) return undefined
+        return {
+          sql: [
+            {
+              sql: `SECURITY LABEL FOR anon ON COLUMN "${objectName}"."${columnName}" IS 'MASKED WITH FUNCTION ${fnExpr}';`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Anonymization', object: objectName, column: columnName, value: `Fake: ${fnExpr}` }],
+          },
+        }
+      }
+      default:
+        return undefined
+    }
+  },
+}
+
+export default plugin