@sqldoc/ns-validate 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-validate",
+  "version": "0.0.1",
+  "description": "Validation namespace for sqldoc -- generates CHECK constraints",
+  "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__/validate.test.ts

@@ -0,0 +1,272 @@
+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: 'username',
+    columnType: 'text',
+    tag: { name: 'check', args: {} },
+    namespaceTags: [],
+    siblingTags: [],
+    fileTags: [],
+    astNode: null,
+    fileStatements: [],
+    config: {},
+    filePath: 'test.sql',
+    ...overrides,
+  }
+}
+
+describe('ns-validate plugin', () => {
+  it('exports apiVersion === 1', () => {
+    expect(plugin.apiVersion).toBe(1)
+  })
+
+  it('exports name === "validate"', () => {
+    expect(plugin.name).toBe('validate')
+  })
+
+  it('has all tag entries', () => {
+    expect(plugin.tags).toHaveProperty('check')
+    expect(plugin.tags).toHaveProperty('notEmpty')
+    expect(plugin.tags).toHaveProperty('range')
+    expect(plugin.tags).toHaveProperty('length')
+    expect(plugin.tags).toHaveProperty('pattern')
+  })
+
+  describe('onTag', () => {
+    it('@validate.check generates ALTER TABLE ADD CONSTRAINT with CHECK', () => {
+      const ctx = makeCtx({
+        tag: { name: 'check', args: ['length(username) >= 3'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_username_check" CHECK (length(username) >= 3);',
+        },
+      ])
+    })
+
+    it('@validate.notEmpty generates CHECK with length(trim(col)) > 0', () => {
+      const ctx = makeCtx({
+        columnName: 'email',
+        tag: { name: 'notEmpty', args: {} },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_email_not_empty" CHECK (length(trim("email")) > 0);',
+        },
+      ])
+    })
+
+    it('@validate.range generates CHECK with min/max bounds', () => {
+      const ctx = makeCtx({
+        columnName: 'age',
+        columnType: 'integer',
+        tag: { name: 'range', args: { min: 0, max: 150 } },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_age_range" CHECK ("age" >= 0 AND "age" <= 150);',
+        },
+      ])
+    })
+
+    it('@validate.length with both min and max generates combined CHECK', () => {
+      const ctx = makeCtx({
+        tag: { name: 'length', args: { min: 3, max: 50 } },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_username_length" CHECK (length("username") >= 3 AND length("username") <= 50);',
+        },
+      ])
+    })
+
+    it('@validate.length with only min generates >= CHECK', () => {
+      const ctx = makeCtx({
+        tag: { name: 'length', args: { min: 3 } },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_username_length" CHECK (length("username") >= 3);',
+        },
+      ])
+    })
+
+    it('@validate.length with only max generates <= CHECK', () => {
+      const ctx = makeCtx({
+        tag: { name: 'length', args: { max: 255 } },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: 'ALTER TABLE "users" ADD CONSTRAINT "users_username_length" CHECK (length("username") <= 255);',
+        },
+      ])
+    })
+
+    it('@validate.pattern generates CHECK with regex operator', () => {
+      const ctx = makeCtx({
+        columnName: 'email',
+        tag: { name: 'pattern', args: ['^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'] },
+      })
+      const result = plugin.onTag!(ctx) as any
+      expect(result.sql).toEqual([
+        {
+          sql: `ALTER TABLE "users" ADD CONSTRAINT "users_email_pattern" CHECK ("email" ~ '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$');`,
+        },
+      ])
+    })
+  })
+
+  describe('validation', () => {
+    it('@validate.notEmpty warns on non-text column', () => {
+      const validate = plugin.tags.notEmpty.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: {},
+        columnName: 'age',
+        columnType: 'integer',
+        objectName: 'users',
+      })
+      expect(result).toEqual({
+        message: 'notEmpty is typically used on text columns',
+        severity: 'warning',
+      })
+    })
+
+    it('@validate.notEmpty does not warn on text column', () => {
+      const validate = plugin.tags.notEmpty.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: {},
+        columnName: 'name',
+        columnType: 'text',
+        objectName: 'users',
+      })
+      expect(result).toBeUndefined()
+    })
+
+    it('@validate.notEmpty does not warn on varchar column', () => {
+      const validate = plugin.tags.notEmpty.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: {},
+        columnName: 'name',
+        columnType: 'varchar(255)',
+        objectName: 'users',
+      })
+      expect(result).toBeUndefined()
+    })
+
+    it('@validate.range errors when min >= max', () => {
+      const validate = plugin.tags.range.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { min: 10, max: 5 },
+        columnName: 'age',
+        columnType: 'integer',
+        objectName: 'users',
+      })
+      expect(result).toBe('min must be less than max')
+    })
+
+    it('@validate.range errors when min equals max', () => {
+      const validate = plugin.tags.range.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { min: 5, max: 5 },
+        columnName: 'age',
+        columnType: 'integer',
+        objectName: 'users',
+      })
+      expect(result).toBe('min must be less than max')
+    })
+
+    it('@validate.range passes with valid min < max', () => {
+      const validate = plugin.tags.range.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { min: 0, max: 100 },
+        columnName: 'age',
+        columnType: 'integer',
+        objectName: 'users',
+      })
+      expect(result).toBeUndefined()
+    })
+
+    it('@validate.length errors when neither min nor max provided', () => {
+      const validate = plugin.tags.length.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: {},
+        columnName: 'name',
+        columnType: 'text',
+        objectName: 'users',
+      })
+      expect(result).toBe('at least one of min or max is required')
+    })
+
+    it('@validate.length errors when min >= max', () => {
+      const validate = plugin.tags.length.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { min: 50, max: 10 },
+        columnName: 'name',
+        columnType: 'text',
+        objectName: 'users',
+      })
+      expect(result).toBe('min must be less than max')
+    })
+
+    it('@validate.length warns on non-text column', () => {
+      const validate = plugin.tags.length.validate!
+      const result = validate({
+        target: 'column',
+        lines: [],
+        siblingTags: [],
+        fileTags: [],
+        argValues: { min: 1, max: 100 },
+        columnName: 'count',
+        columnType: 'integer',
+        objectName: 'users',
+      })
+      expect(result).toEqual({
+        message: 'length check is typically used on text columns',
+        severity: 'warning',
+      })
+    })
+  })
+})

package/src/index.ts

@@ -0,0 +1,217 @@
+import type { NamespacePlugin, TagContext, TagOutput } from '@sqldoc/core'
+
+function isTextType(type: string | undefined): boolean {
+  if (!type) return false
+  const t = type.toLowerCase()
+  return (
+    t === 'text' ||
+    t.startsWith('varchar') ||
+    t.startsWith('character varying') ||
+    t === 'char' ||
+    t.startsWith('character')
+  )
+}
+
+const plugin: NamespacePlugin = {
+  apiVersion: 1,
+  name: 'validate',
+  tags: {
+    check: {
+      description: 'Add a CHECK constraint with a custom expression',
+      targets: ['column'],
+      args: {
+        positional: { type: 'string', required: true },
+      },
+    },
+    notEmpty: {
+      description: 'Add a CHECK constraint ensuring the column is not empty (length(trim(col)) > 0)',
+      targets: ['column'],
+      validate: (ctx) => {
+        if (!isTextType(ctx.columnType)) {
+          return { message: 'notEmpty is typically used on text columns', severity: 'warning' }
+        }
+      },
+    },
+    range: {
+      description: 'Add a CHECK constraint ensuring the column value is within a numeric range',
+      targets: ['column'],
+      args: {
+        min: { type: 'number', required: true },
+        max: { type: 'number', required: true },
+      },
+      validate: (ctx) => {
+        const args = ctx.argValues as Record<string, unknown>
+        const min = args.min as number
+        const max = args.max as number
+        if (min >= max) {
+          return 'min must be less than max'
+        }
+      },
+    },
+    length: {
+      description: 'Add a CHECK constraint on string length',
+      targets: ['column'],
+      args: {
+        min: { type: 'number', required: false },
+        max: { type: 'number', required: false },
+      },
+      validate: (ctx) => {
+        const args = ctx.argValues as Record<string, unknown>
+        if (args.min == null && args.max == null) {
+          return 'at least one of min or max is required'
+        }
+        if (args.min != null && args.max != null && (args.min as number) >= (args.max as number)) {
+          return 'min must be less than max'
+        }
+        if (!isTextType(ctx.columnType)) {
+          return { message: 'length check is typically used on text columns', severity: 'warning' }
+        }
+      },
+    },
+    pattern: {
+      description: 'Add a CHECK constraint using a PostgreSQL regex pattern',
+      targets: ['column'],
+      args: [{ type: 'string' }],
+    },
+  },
+
+  onTag(ctx: TagContext): TagOutput | undefined {
+    const { tag, objectName, columnName } = ctx
+
+    switch (tag.name) {
+      case 'check': {
+        const expression = Array.isArray(tag.args)
+          ? (tag.args[0] as string)
+          : ((tag.args as Record<string, unknown>).positional as string)
+        return {
+          sql: [
+            {
+              sql: `ALTER TABLE "${objectName}" ADD CONSTRAINT "${objectName}_${columnName}_check" CHECK (${expression});`,
+            },
+          ],
+        }
+      }
+
+      case 'notEmpty': {
+        return {
+          sql: [
+            {
+              sql: `ALTER TABLE "${objectName}" ADD CONSTRAINT "${objectName}_${columnName}_not_empty" CHECK (length(trim("${columnName}")) > 0);`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Validation', object: objectName, column: columnName, value: 'Not empty' }],
+          },
+        }
+      }
+
+      case 'range': {
+        const args = tag.args as Record<string, unknown>
+        const min = args.min as number
+        const max = args.max as number
+        return {
+          sql: [
+            {
+              sql: `ALTER TABLE "${objectName}" ADD CONSTRAINT "${objectName}_${columnName}_range" CHECK ("${columnName}" >= ${min} AND "${columnName}" <= ${max});`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Validation', object: objectName, column: columnName, value: `Range: ${min}–${max}` }],
+          },
+        }
+      }
+
+      case 'length': {
+        const args = tag.args as Record<string, unknown>
+        const min = args.min as number | undefined
+        const max = args.max as number | undefined
+        let checkExpr: string
+        let label: string
+        if (min != null && max != null) {
+          checkExpr = `length("${columnName}") >= ${min} AND length("${columnName}") <= ${max}`
+          label = `Length: ${min}–${max}`
+        } else if (min != null) {
+          checkExpr = `length("${columnName}") >= ${min}`
+          label = `Min length: ${min}`
+        } else {
+          checkExpr = `length("${columnName}") <= ${max}`
+          label = `Max length: ${max}`
+        }
+        return {
+          sql: [
+            {
+              sql: `ALTER TABLE "${objectName}" ADD CONSTRAINT "${objectName}_${columnName}_length" CHECK (${checkExpr});`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Validation', object: objectName, column: columnName, value: label }],
+          },
+        }
+      }
+
+      case 'pattern': {
+        const pattern = Array.isArray(tag.args)
+          ? (tag.args[0] as string)
+          : ((tag.args as Record<string, unknown>).positional as string)
+        return {
+          sql: [
+            {
+              sql: `ALTER TABLE "${objectName}" ADD CONSTRAINT "${objectName}_${columnName}_pattern" CHECK ("${columnName}" ~ '${pattern}');`,
+            },
+          ],
+          docs: {
+            columns: [{ header: 'Validation', object: objectName, column: columnName, value: `Pattern: ${pattern}` }],
+          },
+        }
+      }
+
+      default:
+        return undefined
+    }
+  },
+
+  lintRules: [
+    {
+      name: 'validate.require-pk',
+      description: 'Tables should have a primary key',
+      default: 'warn',
+      check(ctx) {
+        const diagnostics = []
+        for (const output of ctx.outputs) {
+          for (const obj of output.fileTags) {
+            if (obj.target !== 'table') continue
+            // Skip objects that look like column-level tags (table.column)
+            if (obj.objectName.includes('.')) continue
+
+            // Check if any tag indicates a primary key exists
+            // We need to check the Atlas realm if available, or inspect the source SQL
+            const hasPk = checkTableHasPk(output, obj.objectName)
+            if (!hasPk) {
+              diagnostics.push({
+                objectName: obj.objectName,
+                sourceFile: output.sourceFile,
+                message: `Table '${obj.objectName}' has no primary key`,
+              })
+            }
+          }
+        }
+        return diagnostics
+      },
+    },
+  ],
+}
+
+/** Check if a table has a primary key by inspecting the source SQL */
+function checkTableHasPk(output: import('@sqldoc/core').CompilerOutput, tableName: string): boolean {
+  const sql = output.mergedSql.toLowerCase()
+  // Look for PRIMARY KEY in the CREATE TABLE statement for this table
+  const tableRegex = new RegExp(
+    `create\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?(?:"${tableName.toLowerCase()}"|${tableName.toLowerCase()})\\s*\\(([^;]*?)\\)`,
+    'is',
+  )
+  const match = sql.match(tableRegex)
+  if (!match) return true // If we can't find the table, don't flag it
+  return match[1].includes('primary key')
+}
+
+export default plugin