@sqldoc/ns-deprecated 0.0.1 → 0.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@sqldoc/ns-deprecated",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Deprecation namespace for sqldoc -- marks SQL objects as deprecated with COMMENT ON statements",
   "exports": {
     ".": {
@@ -14,17 +14,19 @@
   "types": "./src/index.ts",
   "files": [
     "src",
+    "!src/__tests__",
     "package.json"
   ],
+  "scripts": {
+    "test": "node --test 'src/__tests__/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
   "peerDependencies": {
-    "@sqldoc/core": "0.0.1"
+    "@sqldoc/core": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0",
-    "@sqldoc/core": "0.0.1"
-  },
-  "scripts": {
-    "test": "vitest run"
+    "@sqldoc/core": "workspace:*",
+    "typescript": "catalog:",
+    "@sqldoc/test-utils": "workspace:*"
   }
-}
+}

package/src/index.ts

@@ -1,32 +1,5 @@
 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}"`
-}
+import { escapeString, quoteIdentifier } from '@sqldoc/core'
 
 const plugin: NamespacePlugin = {
   apiVersion: 1,
@@ -49,45 +22,80 @@ const plugin: NamespacePlugin = {
   },
 
   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 }
+    const { tag, target, objectName, columnName, dialect } = ctx
+    const q = (name: string) => quoteIdentifier(name, dialect)
+    const esc = (s: string) => escapeString(s, dialect)
+
+    const docTarget = target === 'column' ? { object: objectName, column: columnName } : { object: objectName }
 
+    // Determine the deprecation message and docs value
+    let message: string
+    let docsValue: string
     switch (tag.name) {
       case '$self':
-      case null: {
-        return {
-          sql: [{ sql: commentOnSql(keyword, name, 'DEPRECATED') }],
-          docs: {
-            columns: [{ header: 'Status', ...docTarget, value: 'Deprecated' }],
-          },
-        }
-      }
+      case null:
+        message = 'DEPRECATED'
+        docsValue = 'Deprecated'
+        break
       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}` }],
-          },
-        }
+        message = `DEPRECATED: use ${newName} instead`
+        docsValue = `Deprecated \u2192 ${newName}`
+        break
       }
       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}` }],
-          },
-        }
+        message = `DEPRECATED: scheduled for removal after ${date}`
+        docsValue = `Remove after ${date}`
+        break
       }
       default:
         return undefined
     }
+
+    const docs = {
+      columns: [{ header: 'Status', ...docTarget, value: docsValue }],
+    }
+
+    // Generate dialect-specific SQL
+    switch (dialect) {
+      case 'postgres': {
+        const keyword = target.toUpperCase()
+        const name = target === 'column' ? `${q(objectName)}.${q(columnName!)}` : q(objectName)
+        return {
+          sql: [{ sql: `COMMENT ON ${keyword} ${name} IS ${esc(message)};` }],
+          docs,
+        }
+      }
+
+      case 'mysql': {
+        if (target === 'table') {
+          return {
+            sql: [{ sql: `ALTER TABLE ${q(objectName)} COMMENT = ${esc(message)};` }],
+            docs,
+          }
+        }
+        if (target === 'column') {
+          const colType = ctx.columnType ?? 'TEXT'
+          return {
+            sql: [
+              {
+                sql: `ALTER TABLE ${q(objectName)} MODIFY COLUMN ${q(columnName!)} ${colType} COMMENT ${esc(message)};`,
+              },
+            ],
+            docs,
+          }
+        }
+        // MySQL cannot comment on views, functions, or types -- docs-only output
+        return { sql: [], docs }
+      }
+
+      case 'sqlite':
+        // SQLite has no comment support -- docs-only output
+        return { sql: [], docs }
+    }
   },
 }
 

package/src/__tests__/deprecated.test.ts

@@ -1,139 +0,0 @@
-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()
-    })
-  })
-})