@sqldoc/ns-postgraphile 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-postgraphile",
+  "version": "0.0.1",
+  "description": "PostGraphile smart comments namespace for sqldoc -- generates COMMENT ON statements with @tag syntax",
+  "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__/postgraphile.test.ts

@@ -0,0 +1,187 @@
+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: 'omit', args: {} },
+    namespaceTags: [{ tag: 'omit', args: {} }],
+    siblingTags: [],
+    fileTags: [],
+    astNode: null,
+    fileStatements: [],
+    config: {},
+    filePath: 'test.sql',
+    ...overrides,
+  }
+}
+
+describe('ns-postgraphile plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "pg"', () => {
+    expect(plugin.name).toBe('pg')
+  })
+
+  it('has all expected tag entries', () => {
+    expect(plugin.tags).toHaveProperty('omit')
+    expect(plugin.tags).toHaveProperty(['omit.operations'])
+    expect(plugin.tags).toHaveProperty('name')
+    expect(plugin.tags).toHaveProperty('deprecated')
+    expect(plugin.tags).toHaveProperty('simpleCollections')
+    expect(plugin.tags).toHaveProperty('behavior')
+  })
+
+  describe('onTag', () => {
+    it('@pg.omit on a table', () => {
+      const ctx = makeCtx()
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@omit';` }])
+    })
+
+    it('@pg.omit on a column', () => {
+      const ctx = makeCtx({
+        target: 'column',
+        objectName: 'users',
+        columnName: 'secret',
+        tag: { name: 'omit', args: {} },
+        namespaceTags: [{ tag: 'omit', args: {} }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON COLUMN "users"."secret" IS E'@omit';` }])
+    })
+
+    it('@pg.omit on a view', () => {
+      const ctx = makeCtx({
+        target: 'view',
+        objectName: 'active_users',
+        tag: { name: 'omit', args: {} },
+        namespaceTags: [{ tag: 'omit', args: {} }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON VIEW "active_users" IS E'@omit';` }])
+    })
+
+    it('@pg.omit on a function', () => {
+      const ctx = makeCtx({
+        target: 'function',
+        objectName: 'my_func',
+        tag: { name: 'omit', args: {} },
+        namespaceTags: [{ tag: 'omit', args: {} }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON FUNCTION "my_func" IS E'@omit';` }])
+    })
+
+    it('@pg.omit.operations with specific ops', () => {
+      const ctx = makeCtx({
+        tag: { name: 'omit.operations', args: { ops: ['create', 'update'] } },
+        namespaceTags: [{ tag: 'omit.operations', args: { ops: ['create', 'update'] } }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@omit create,update';` }])
+    })
+
+    it('@pg.name renames in GraphQL', () => {
+      const ctx = makeCtx({
+        tag: { name: 'name', args: ['Person'] },
+        namespaceTags: [{ tag: 'name', args: ['Person'] }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@name Person';` }])
+    })
+
+    it('@pg.name on a type', () => {
+      const ctx = makeCtx({
+        target: 'type',
+        objectName: 'user_role',
+        tag: { name: 'name', args: ['UserRole'] },
+        namespaceTags: [{ tag: 'name', args: ['UserRole'] }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TYPE "user_role" IS E'@name UserRole';` }])
+    })
+
+    it('@pg.deprecated with reason', () => {
+      const ctx = makeCtx({
+        tag: { name: 'deprecated', args: ['Use accounts instead'] },
+        namespaceTags: [{ tag: 'deprecated', args: ['Use accounts instead'] }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@deprecated Use accounts instead';` }])
+    })
+
+    it('@pg.deprecated with default reason', () => {
+      const ctx = makeCtx({
+        tag: { name: 'deprecated', args: [] },
+        namespaceTags: [{ tag: 'deprecated', args: [] }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@deprecated Deprecated';` }])
+    })
+
+    it('@pg.simpleCollections on a table', () => {
+      const ctx = makeCtx({
+        tag: { name: 'simpleCollections', args: {} },
+        namespaceTags: [{ tag: 'simpleCollections', args: {} }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@simpleCollections only';` }])
+    })
+
+    it('@pg.behavior with custom string', () => {
+      const ctx = makeCtx({
+        tag: { name: 'behavior', args: ['-query:resource:list'] },
+        namespaceTags: [{ tag: 'behavior', args: ['-query:resource:list'] }],
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@behavior -query:resource:list';` }])
+    })
+
+    describe('multiple tags combined into one COMMENT ON', () => {
+      it('combines @pg.omit.operations and @pg.name into one statement', () => {
+        const namespaceTags = [
+          { tag: 'omit.operations', args: { ops: ['create', 'delete'] } },
+          { tag: 'name', args: ['Person'] },
+        ]
+        // First tag generates the combined SQL
+        const ctx1 = makeCtx({
+          tag: { name: 'omit.operations', args: { ops: ['create', 'delete'] } },
+          namespaceTags,
+        })
+        const result1 = plugin.onTag!(ctx1) as any
+        expect(result1.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS E'@omit create,delete\\n@name Person';` }])
+
+        // Second tag is skipped (returns undefined)
+        const ctx2 = makeCtx({
+          tag: { name: 'name', args: ['Person'] },
+          namespaceTags,
+        })
+        const result2 = plugin.onTag!(ctx2)
+        expect(result2).toBeUndefined()
+      })
+
+      it('combines three tags: omit + deprecated + simpleCollections', () => {
+        const namespaceTags = [
+          { tag: 'omit', args: {} },
+          { tag: 'deprecated', args: ['Will be removed in v2'] },
+          { tag: 'simpleCollections', args: {} },
+        ]
+        const ctx = makeCtx({
+          tag: { name: 'omit', args: {} },
+          namespaceTags,
+        })
+        const result = plugin.onTag!(ctx) as any
+        expect(result.sql).toEqual([
+          {
+            sql: `COMMENT ON TABLE "users" IS E'@omit\\n@deprecated Will be removed in v2\\n@simpleCollections only';`,
+          },
+        ])
+      })
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,166 @@
+import type { NamespacePlugin, SqlOutput, TagContext, TagOutput } from '@sqldoc/core'
+
+function commentTarget(target: string, objectName: string, columnName?: string): string {
+  switch (target) {
+    case 'column':
+      return `COLUMN "${objectName}"."${columnName}"`
+    case 'table':
+      return `TABLE "${objectName}"`
+    case 'view':
+      return `VIEW "${objectName}"`
+    case 'function':
+      return `FUNCTION "${objectName}"`
+    case 'type':
+      return `TYPE "${objectName}"`
+    default:
+      return `TABLE "${objectName}"`
+  }
+}
+
+function tagLine(entry: { tag: string | null; args: Record<string, unknown> | unknown[] }): string {
+  const name = entry.tag
+  const args = entry.args
+
+  switch (name) {
+    case '$self':
+    case null:
+      return ''
+    case 'omit':
+      return '@omit'
+    case 'omit.operations': {
+      const namedArgs = args as Record<string, unknown>
+      const ops = namedArgs.ops as string[]
+      return `@omit ${ops.join(',')}`
+    }
+    case 'name': {
+      const positional = args as unknown[]
+      return `@name ${positional[0]}`
+    }
+    case 'deprecated': {
+      const positional = args as unknown[]
+      const reason = positional.length > 0 ? positional[0] : 'Deprecated'
+      return `@deprecated ${reason}`
+    }
+    case 'simpleCollections':
+      return '@simpleCollections only'
+    case 'behavior': {
+      const positional = args as unknown[]
+      return `@behavior ${positional[0]}`
+    }
+    default:
+      return ''
+  }
+}
+
+/** Build a human-readable GraphQL doc label from all pg tags on this object */
+function buildGraphqlLabel(
+  namespaceTags: Array<{ tag: string | null; args: Record<string, unknown> | unknown[] }>,
+): string | undefined {
+  const parts: string[] = []
+  for (const entry of namespaceTags) {
+    switch (entry.tag) {
+      case 'omit':
+        parts.push('Omitted')
+        break
+      case 'omit.operations': {
+        const ops = (entry.args as Record<string, unknown>).ops as string[]
+        parts.push(`Omit: ${ops.join(', ')}`)
+        break
+      }
+      case 'name': {
+        const name = (entry.args as unknown[])[0]
+        parts.push(`→ ${name}`)
+        break
+      }
+      case 'simpleCollections':
+        parts.push('Simple collections')
+        break
+      case 'behavior': {
+        const b = (entry.args as unknown[])[0]
+        parts.push(`Behavior: ${b}`)
+        break
+      }
+    }
+  }
+  return parts.length > 0 ? parts.join(', ') : undefined
+}
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'pg',
+  tags: {
+    omit: {
+      description: 'Omit this object from the PostGraphile GraphQL schema',
+      targets: ['table', 'column', 'view', 'function'],
+      args: {},
+    },
+    'omit.operations': {
+      description: 'Omit specific operations from the PostGraphile GraphQL schema',
+      targets: ['table', 'column', 'view', 'function'],
+      args: {
+        ops: {
+          type: 'array',
+          items: { type: 'enum', values: ['create', 'read', 'update', 'delete', 'all', 'many'] },
+          required: true,
+        },
+      },
+    },
+    name: {
+      description: 'Rename this object in the PostGraphile GraphQL schema',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+      args: [{ type: 'string' }],
+    },
+    deprecated: {
+      description: 'Mark this object as deprecated in the PostGraphile GraphQL schema',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+      args: [{ type: 'string' }],
+    },
+    simpleCollections: {
+      description: 'Enable simple collections on this table or view in PostGraphile',
+      targets: ['table', 'view'],
+      args: {},
+    },
+    behavior: {
+      description: 'Set a custom behavior string (PostGraphile V5)',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+      args: [{ type: 'string' }],
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag, objectName, columnName, target, namespaceTags } = ctx
+
+    // Only generate on the FIRST pg tag — combines all into one COMMENT ON
+    const firstTag = namespaceTags[0]
+    if (firstTag.tag !== tag.name || JSON.stringify(firstTag.args) !== JSON.stringify(tag.args)) {
+      return undefined
+    }
+
+    const lines: string[] = []
+    for (const entry of namespaceTags) {
+      const line = tagLine(entry)
+      if (line) lines.push(line)
+    }
+
+    if (lines.length === 0) return undefined
+
+    const commentBody = lines.join('\\n')
+    const targetStr = commentTarget(target, objectName, columnName)
+    const sql: SqlOutput[] = [{ sql: `COMMENT ON ${targetStr} IS E'${commentBody}';` }]
+
+    // Build docs column entry
+    const label = buildGraphqlLabel(namespaceTags)
+    const docTarget = target === 'column' ? { object: objectName, column: columnName } : { object: objectName }
+
+    return {
+      sql,
+      docs: label
+        ? {
+            columns: [{ header: 'GraphQL', ...docTarget, value: label }],
+          }
+        : undefined,
+    }
+  },
+}
+
+export default plugin