@sqldoc/ns-deprecated 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-deprecated",
+  "version": "0.0.1",
+  "description": "Deprecation namespace for sqldoc -- marks SQL objects as deprecated with COMMENT ON 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__/deprecated.test.ts

@@ -0,0 +1,139 @@
+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-deprecated plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "deprecated"', () => {
+    expect(plugin.name).toBe('deprecated')
+  })
+
+  it('has $self, replace, and remove tag entries', () => {
+    expect(plugin.tags).toHaveProperty('$self')
+    expect(plugin.tags).toHaveProperty('replace')
+    expect(plugin.tags).toHaveProperty('remove')
+  })
+
+  describe('onTag', () => {
+    it('@deprecated on a table generates COMMENT ON TABLE', () => {
+      const ctx = makeCtx({
+        target: 'table',
+        objectName: 'users',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated with null tag name generates COMMENT ON TABLE', () => {
+      const ctx = makeCtx({
+        target: 'table',
+        objectName: 'users',
+        tag: { name: null, args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "users" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated on a column generates COMMENT ON COLUMN with qualified name', () => {
+      const ctx = makeCtx({
+        target: 'column',
+        objectName: 'users',
+        columnName: 'email',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON COLUMN "users"."email" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated on a view generates COMMENT ON VIEW', () => {
+      const ctx = makeCtx({
+        target: 'view',
+        objectName: 'active_users',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON VIEW "active_users" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated on a function generates COMMENT ON FUNCTION', () => {
+      const ctx = makeCtx({
+        target: 'function',
+        objectName: 'get_user',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON FUNCTION "get_user" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated on a type generates COMMENT ON TYPE', () => {
+      const ctx = makeCtx({
+        target: 'type',
+        objectName: 'status_enum',
+        tag: { name: '$self', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TYPE "status_enum" IS 'DEPRECATED';` }])
+    })
+
+    it('@deprecated.replace generates COMMENT with replacement suggestion', () => {
+      const ctx = makeCtx({
+        target: 'table',
+        objectName: 'old_users',
+        tag: { name: 'replace', args: ['accounts'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON TABLE "old_users" IS 'DEPRECATED: use accounts instead';` }])
+    })
+
+    it('@deprecated.remove generates COMMENT with removal date', () => {
+      const ctx = makeCtx({
+        target: 'table',
+        objectName: 'legacy_data',
+        tag: { name: 'remove', args: ['2025-06-01'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        { sql: `COMMENT ON TABLE "legacy_data" IS 'DEPRECATED: scheduled for removal after 2025-06-01';` },
+      ])
+    })
+
+    it('@deprecated.replace on a column generates correct qualified COMMENT', () => {
+      const ctx = makeCtx({
+        target: 'column',
+        objectName: 'users',
+        columnName: 'name',
+        tag: { name: 'replace', args: ['full_name'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([{ sql: `COMMENT ON COLUMN "users"."name" IS 'DEPRECATED: use full_name instead';` }])
+    })
+  })
+
+  describe('validation', () => {
+    it('@deprecated tags have no validate function (metadata only)', () => {
+      expect(plugin.tags.$self!.validate).toBeUndefined()
+      expect(plugin.tags.replace.validate).toBeUndefined()
+      expect(plugin.tags.remove.validate).toBeUndefined()
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,94 @@
+import type { NamespacePlugin, TagContext, TagOutput } from '@sqldoc/core'
+
+function commentOnSql(target: string, qualifiedName: string, message: string): string {
+  return `COMMENT ON ${target} ${qualifiedName} IS '${message}';`
+}
+
+function targetKeyword(target: string): string {
+  switch (target) {
+    case 'table':
+      return 'TABLE'
+    case 'column':
+      return 'COLUMN'
+    case 'view':
+      return 'VIEW'
+    case 'function':
+      return 'FUNCTION'
+    case 'type':
+      return 'TYPE'
+    default:
+      return target.toUpperCase()
+  }
+}
+
+function qualifiedName(ctx: TagContext): string {
+  if (ctx.target === 'column') {
+    return `"${ctx.objectName}"."${ctx.columnName}"`
+  }
+  return `"${ctx.objectName}"`
+}
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'deprecated',
+  tags: {
+    $self: {
+      description: 'Mark this SQL object as deprecated',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+    },
+    replace: {
+      description: 'Mark as deprecated with a replacement suggestion',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+      args: [{ type: 'string' }],
+    },
+    remove: {
+      description: 'Mark as deprecated with a scheduled removal date',
+      targets: ['table', 'column', 'view', 'function', 'type'],
+      args: [{ type: 'string' }],
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag } = ctx
+    const keyword = targetKeyword(ctx.target)
+    const name = qualifiedName(ctx)
+    const docTarget =
+      ctx.target === 'column' ? { object: ctx.objectName, column: ctx.columnName } : { object: ctx.objectName }
+
+    switch (tag.name) {
+      case '$self':
+      case null: {
+        return {
+          sql: [{ sql: commentOnSql(keyword, name, 'DEPRECATED') }],
+          docs: {
+            columns: [{ header: 'Status', ...docTarget, value: 'Deprecated' }],
+          },
+        }
+      }
+      case 'replace': {
+        const args = tag.args as unknown[]
+        const newName = args[0] as string
+        return {
+          sql: [{ sql: commentOnSql(keyword, name, `DEPRECATED: use ${newName} instead`) }],
+          docs: {
+            columns: [{ header: 'Status', ...docTarget, value: `Deprecated → ${newName}` }],
+          },
+        }
+      }
+      case 'remove': {
+        const args = tag.args as unknown[]
+        const date = args[0] as string
+        return {
+          sql: [{ sql: commentOnSql(keyword, name, `DEPRECATED: scheduled for removal after ${date}`) }],
+          docs: {
+            columns: [{ header: 'Status', ...docTarget, value: `Remove after ${date}` }],
+          },
+        }
+      }
+      default:
+        return undefined
+    }
+  },
+}
+
+export default plugin