@sqldoc/ns-rls 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-rls",
+  "version": "0.0.1",
+  "description": "Row-Level Security namespace for sqldoc -- generates CREATE POLICY and ALTER TABLE 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__/rls.test.ts

@@ -0,0 +1,119 @@
+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-rls plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "rls"', () => {
+    expect(plugin.name).toBe('rls')
+  })
+
+  it('has policy and $self tag entries', () => {
+    expect(plugin.tags).toHaveProperty('policy')
+    expect(plugin.tags).toHaveProperty('$self')
+  })
+
+  describe('onTag', () => {
+    it('@rls.$self produces ALTER TABLE ENABLE ROW LEVEL SECURITY', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: 'ALTER TABLE "users" ENABLE ROW LEVEL SECURITY;' }])
+    })
+
+    it('@rls with null tag name produces ALTER TABLE ENABLE ROW LEVEL SECURITY', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        tag: { name: null, args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: 'ALTER TABLE "users" ENABLE ROW LEVEL SECURITY;' }])
+    })
+
+    it('@rls.policy with for/to/using produces CREATE POLICY', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        tag: {
+          name: 'policy',
+          args: { for: 'select', to: 'viewer_role', using: 'true' },
+        },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toHaveLength(1)
+      expect(result.sql[0].sql).toContain('CREATE POLICY')
+      expect(result.sql[0].sql).toContain('"users_viewer_role_select"')
+      expect(result.sql[0].sql).toContain('ON "users"')
+      expect(result.sql[0].sql).toContain('FOR SELECT')
+      expect(result.sql[0].sql).toContain('TO viewer_role')
+      expect(result.sql[0].sql).toContain('USING (true)')
+    })
+
+    it('@rls.policy with using and check produces both clauses', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        tag: {
+          name: 'policy',
+          args: {
+            for: 'all',
+            to: 'authenticated',
+            using: 'user_id = current_user_id()',
+            check: 'user_id = current_user_id()',
+          },
+        },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toHaveLength(1)
+      expect(result.sql[0].sql).toContain('"users_authenticated_all"')
+      expect(result.sql[0].sql).toContain('FOR ALL')
+      expect(result.sql[0].sql).toContain('TO authenticated')
+      expect(result.sql[0].sql).toContain('USING (user_id = current_user_id())')
+      expect(result.sql[0].sql).toContain('WITH CHECK (user_id = current_user_id())')
+    })
+
+    it('policy name is auto-generated from table + role + command', () => {
+      const ctx = makeCtx({
+        objectName: 'orders',
+        tag: {
+          name: 'policy',
+          args: { for: 'insert', to: 'admin_role', using: 'true' },
+        },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql[0].sql).toContain('"orders_admin_role_insert"')
+    })
+
+    it('@rls.policy with missing to arg defaults to PUBLIC', () => {
+      const ctx = makeCtx({
+        objectName: 'users',
+        tag: {
+          name: 'policy',
+          args: { for: 'select', using: 'true' },
+        },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql[0].sql).toContain('TO PUBLIC')
+      expect(result.sql[0].sql).toContain('"users_public_select"')
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,100 @@
+import type { NamespacePlugin, TagContext, TagOutput } from '@sqldoc/core'
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'rls',
+  tags: {
+    policy: {
+      description: 'Create a row-level security policy (requires @rls on the table)',
+      targets: ['table'],
+      args: {
+        for: { type: 'string', required: false },
+        to: { type: 'string', required: false },
+        using: { type: 'string', required: false },
+        check: { type: 'string', required: false },
+      },
+      validate: (ctx) => {
+        const hasRlsSelf = ctx.siblingTags.some((t) => t.namespace === 'rls' && (t.tag === null || t.tag === '$self'))
+        if (!hasRlsSelf) {
+          return '@rls.policy requires @rls on the same table'
+        }
+      },
+    },
+    $self: {
+      description: 'Enable row-level security on this table',
+      targets: ['table'],
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag, objectName } = ctx
+
+    switch (tag.name) {
+      case '$self':
+      case null: {
+        return {
+          sql: [{ sql: `ALTER TABLE "${objectName}" ENABLE ROW LEVEL SECURITY;` }],
+          docs: {
+            annotations: [
+              {
+                object: objectName,
+                text: 'RLS enabled',
+              },
+            ],
+          },
+        }
+      }
+      case 'policy': {
+        const args = tag.args as Record<string, unknown>
+        const forCmd = (args.for as string) || 'ALL'
+        const toRole = (args.to as string) || 'PUBLIC'
+        const using = args.using as string | undefined
+        const check = args.check as string | undefined
+
+        const policyName = `${objectName}_${toRole.toLowerCase().replace(/\s+/g, '_')}_${forCmd.toLowerCase()}`
+
+        let policySql = `CREATE POLICY "${policyName}" ON "${objectName}"\n  FOR ${forCmd.toUpperCase()}\n  TO ${toRole}`
+        if (using) {
+          policySql += `\n  USING (${using})`
+        }
+        if (check) {
+          policySql += `\n  WITH CHECK (${check})`
+        }
+        policySql += ';'
+
+        return { sql: [{ sql: policySql }] }
+      }
+      default:
+        return undefined
+    }
+  },
+
+  lintRules: [
+    {
+      name: 'rls.require-policy',
+      description: 'Public tables should have RLS enabled',
+      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 hasRls = obj.tags.some((t) => t.namespace === 'rls' && (t.tag === null || t.tag === '$self'))
+            if (!hasRls) {
+              diagnostics.push({
+                objectName: obj.objectName,
+                sourceFile: output.sourceFile,
+                message: `Table '${obj.objectName}' has no RLS policy`,
+              })
+            }
+          }
+        }
+        return diagnostics
+      },
+    },
+  ],
+}
+
+export default plugin