@sqldoc/ns-docs 0.0.1 → 0.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@sqldoc/ns-docs",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Documentation namespace for sqldoc -- generates Markdown/HTML docs with Mermaid ER diagrams via Atlas CLI",
   "exports": {
     ".": {
@@ -14,17 +14,18 @@
   "types": "./src/index.ts",
   "files": [
     "src",
+    "!src/__tests__",
     "package.json"
   ],
   "peerDependencies": {
-    "@sqldoc/core": "0.0.1",
-    "@sqldoc/atlas": "0.0.1"
+    "@sqldoc/core": "0.0.2",
+    "@sqldoc/atlas": "0.0.2"
   },
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@sqldoc/atlas": "0.0.1",
-    "@sqldoc/core": "0.0.1"
+    "@sqldoc/core": "0.0.2",
+    "@sqldoc/atlas": "0.0.2"
   },
   "scripts": {
     "test": "vitest run"

package/src/__tests__/atlas.test.ts

@@ -1,134 +0,0 @@
-import type { AtlasRealm } from '@sqldoc/atlas'
-import { describe, expect, it } from 'vitest'
-import { realmToDocsSchema } from '../atlas'
-
-const sampleRealm: AtlasRealm = {
-  schemas: [
-    {
-      name: 'public',
-      tables: [
-        {
-          name: 'users',
-          columns: [
-            { name: 'id', type: { raw: 'bigserial', T: 'bigserial', null: false } },
-            { name: 'email', type: { raw: 'text', T: 'text', null: false } },
-            { name: 'bio', type: { raw: 'text', T: 'text', null: true } },
-          ],
-          indexes: [
-            {
-              name: 'users_email_idx',
-              unique: true,
-              parts: [{ column: 'email' }],
-            },
-          ],
-          primary_key: { parts: [{ column: 'id' }] },
-          foreign_keys: [],
-        },
-        {
-          name: 'posts',
-          columns: [
-            { name: 'id', type: { raw: 'bigserial', T: 'bigserial', null: false } },
-            { name: 'user_id', type: { raw: 'bigint', T: 'bigint', null: false } },
-          ],
-          primary_key: { parts: [{ column: 'id' }] },
-          foreign_keys: [
-            {
-              symbol: 'posts_user_id_fkey',
-              columns: ['user_id'],
-              ref_table: 'users',
-              ref_columns: ['id'],
-            },
-          ],
-        },
-      ],
-      views: [
-        {
-          name: 'active_users',
-          columns: [{ name: 'email', type: { raw: 'text', T: 'text' } }],
-        },
-      ],
-    },
-  ],
-}
-
-describe('realmToDocsSchema', () => {
-  it('converts Atlas WASI realm to ns-docs AtlasSchema format', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    expect(result.schemas).toHaveLength(1)
-    expect(result.schemas[0].name).toBe('public')
-  })
-
-  it('maps tables with columns', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const tables = result.schemas[0].tables!
-    expect(tables).toHaveLength(2)
-    expect(tables[0].name).toBe('users')
-    expect(tables[0].columns).toHaveLength(3)
-    expect(tables[0].columns[0].name).toBe('id')
-    expect(tables[0].columns[0].type).toBe('bigserial')
-  })
-
-  it('maps nullable columns', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const bio = result.schemas[0].tables![0].columns[2]
-    expect(bio.name).toBe('bio')
-    expect(bio.null).toBe(true)
-  })
-
-  it('maps primary key', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const pk = result.schemas[0].tables![0].primary_key
-    expect(pk).toBeDefined()
-    expect(pk!.parts[0].column).toBe('id')
-  })
-
-  it('maps indexes', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const indexes = result.schemas[0].tables![0].indexes!
-    expect(indexes).toHaveLength(1)
-    expect(indexes[0].name).toBe('users_email_idx')
-    expect(indexes[0].unique).toBe(true)
-    expect(indexes[0].parts[0].column).toBe('email')
-  })
-
-  it('maps foreign keys with references', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const fks = result.schemas[0].tables![1].foreign_keys!
-    expect(fks).toHaveLength(1)
-    expect(fks[0].name).toBe('posts_user_id_fkey')
-    expect(fks[0].columns).toEqual(['user_id'])
-    expect(fks[0].references.table).toBe('users')
-    expect(fks[0].references.columns).toEqual(['id'])
-  })
-
-  it('maps views', () => {
-    const result = realmToDocsSchema(sampleRealm)
-    const views = result.schemas[0].views!
-    expect(views).toHaveLength(1)
-    expect(views[0].name).toBe('active_users')
-    expect(views[0].columns[0].name).toBe('email')
-  })
-
-  it('handles empty realm', () => {
-    const result = realmToDocsSchema({ schemas: [] })
-    expect(result.schemas).toHaveLength(0)
-  })
-
-  it('falls back to T when raw is undefined', () => {
-    const realm: AtlasRealm = {
-      schemas: [
-        {
-          name: 'test',
-          tables: [
-            {
-              name: 't',
-              columns: [{ name: 'x', type: { T: 'integer' } }],
-            },
-          ],
-        },
-      ],
-    }
-    const result = realmToDocsSchema(realm)
-    expect(result.schemas[0].tables![0].columns[0].type).toBe('integer')
-  })
-})

package/src/__tests__/merge.test.ts

@@ -1,401 +0,0 @@
-import type { CompilerOutput } from '@sqldoc/core'
-import { describe, expect, it } from 'vitest'
-import { mergeSchemaWithTags } from '../merge'
-import type { AtlasSchema } from '../types'
-
-// ── Fixtures ─────────────────────────────────────────────────────────
-
-function makeAtlasSchema(overrides: Partial<AtlasSchema> = {}): AtlasSchema {
-  return {
-    schemas: [
-      {
-        name: 'public',
-        tables: [
-          {
-            name: 'users',
-            columns: [
-              { name: 'id', type: 'bigserial' },
-              { name: 'email', type: 'text', null: true },
-              { name: 'name', type: 'text' },
-            ],
-            primary_key: { parts: [{ column: 'id' }] },
-            indexes: [{ name: 'users_email_idx', unique: true, parts: [{ column: 'email' }] }],
-            foreign_keys: [],
-          },
-        ],
-        ...overrides.schemas?.[0],
-      },
-    ],
-    ...overrides,
-  }
-}
-
-function makeFileTags(
-  objects: Array<{
-    objectName: string
-    target: 'table' | 'column' | 'view' | 'function' | 'type' | 'index' | 'trigger'
-    tags: Array<{ namespace: string; tag: string | null; args: Record<string, unknown> | unknown[] }>
-  }> = [],
-) {
-  return [
-    {
-      sourceFile: 'schema.sql',
-      objects,
-    },
-  ]
-}
-
-function makeOutput(overrides: Partial<CompilerOutput> = {}): CompilerOutput {
-  return {
-    sourceFile: 'schema.sql',
-    mergedSql: '',
-    sqlOutputs: [],
-    codeOutputs: [],
-    errors: [],
-    docsMeta: [],
-    fileTags: [],
-    ...overrides,
-  }
-}
-
-// ── Tests ────────────────────────────────────────────────────────────
-
-describe('mergeSchemaWithTags', () => {
-  it('merges Atlas table with matching sqldoc tags by normalized name', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'description', args: ['User accounts table'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, 'erDiagram', fileTags, [], 'Test')
-
-    expect(result.tables).toHaveLength(1)
-    expect(result.tables[0].name).toBe('users')
-    expect(result.tables[0].description).toBe('User accounts table')
-  })
-
-  it('docs.emit(false) excludes table from output', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'emit', args: [false] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, 'erDiagram', fileTags, [], 'Test')
-
-    expect(result.tables).toHaveLength(0)
-  })
-
-  it('docs.emit(true) or no emit tag includes table (default include)', () => {
-    const schema = makeAtlasSchema()
-    // No tags at all -- default include
-    const result1 = mergeSchemaWithTags(schema, 'erDiagram', [], [], 'Test')
-    expect(result1.tables).toHaveLength(1)
-
-    // Explicit emit(true)
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'emit', args: [true] }],
-      },
-    ])
-    const result2 = mergeSchemaWithTags(schema, 'erDiagram', fileTags, [], 'Test')
-    expect(result2.tables).toHaveLength(1)
-  })
-
-  it('docs.description on table sets MergedTable.description', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'description', args: ['Core user accounts'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    expect(result.tables[0].description).toBe('Core user accounts')
-  })
-
-  it('docs.description on column sets MergedColumn.description', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'email',
-        target: 'column',
-        tags: [{ namespace: 'docs', tag: 'description', args: ['Primary email address'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    const emailCol = result.tables[0].columns.find((c) => c.name === 'email')
-    expect(emailCol?.description).toBe('Primary email address')
-  })
-
-  it('tags from ALL namespaces (not just docs) are included on MergedTable.tags', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [
-          { namespace: 'docs', tag: 'description', args: ['User accounts'] },
-          { namespace: 'audit', tag: 'track', args: { operations: ['INSERT', 'UPDATE'] } },
-          { namespace: 'rls', tag: 'policy', args: ['admin_only'] },
-        ],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    expect(result.tables[0].tags).toHaveLength(3)
-    expect(result.tables[0].tags.map((t) => t.namespace)).toEqual(['docs', 'audit', 'rls'])
-  })
-
-  it('PK columns flagged isPrimaryKey: true', () => {
-    const schema = makeAtlasSchema()
-
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    const idCol = result.tables[0].columns.find((c) => c.name === 'id')
-    expect(idCol?.isPrimaryKey).toBe(true)
-
-    const emailCol = result.tables[0].columns.find((c) => c.name === 'email')
-    expect(emailCol?.isPrimaryKey).toBe(false)
-  })
-
-  it('FK columns flagged isForeignKey: true', () => {
-    const schema: AtlasSchema = {
-      schemas: [
-        {
-          name: 'public',
-          tables: [
-            {
-              name: 'posts',
-              columns: [
-                { name: 'id', type: 'bigserial' },
-                { name: 'user_id', type: 'bigint' },
-                { name: 'title', type: 'text' },
-              ],
-              primary_key: { parts: [{ column: 'id' }] },
-              foreign_keys: [
-                {
-                  name: 'posts_user_id_fkey',
-                  columns: ['user_id'],
-                  references: { table: 'users', columns: ['id'] },
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    }
-
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    const userIdCol = result.tables[0].columns.find((c) => c.name === 'user_id')
-    expect(userIdCol?.isForeignKey).toBe(true)
-
-    const titleCol = result.tables[0].columns.find((c) => c.name === 'title')
-    expect(titleCol?.isForeignKey).toBe(false)
-  })
-
-  it('column nullable reflects Atlas null field', () => {
-    const schema = makeAtlasSchema()
-
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    const emailCol = result.tables[0].columns.find((c) => c.name === 'email')
-    expect(emailCol?.nullable).toBe(true) // email has null: true
-
-    const nameCol = result.tables[0].columns.find((c) => c.name === 'name')
-    expect(nameCol?.nullable).toBe(false) // name has no null field
-  })
-
-  it('generated tables (from sqlOutputs) marked isGenerated: true with generatedBy', () => {
-    const schema: AtlasSchema = {
-      schemas: [
-        {
-          name: 'public',
-          tables: [
-            {
-              name: 'users',
-              columns: [{ name: 'id', type: 'bigserial' }],
-            },
-            {
-              name: 'users_audit',
-              columns: [
-                { name: 'id', type: 'bigserial' },
-                { name: 'action', type: 'text' },
-              ],
-            },
-          ],
-        },
-      ],
-    }
-
-    const outputs: CompilerOutput[] = [
-      makeOutput({
-        sqlOutputs: [
-          {
-            sql: 'CREATE TABLE "users_audit" (id bigserial, action text);',
-            sourceTag: '@audit.track',
-          },
-        ],
-      }),
-    ]
-
-    const result = mergeSchemaWithTags(schema, '', [], outputs, 'Test')
-
-    const usersTable = result.tables.find((t) => t.name === 'users')!
-    expect(usersTable.isGenerated).toBe(false)
-    expect(usersTable.generatedBy).toBeUndefined()
-
-    const auditTable = result.tables.find((t) => t.name === 'users_audit')!
-    expect(auditTable.isGenerated).toBe(true)
-    expect(auditTable.generatedBy).toBe('audit')
-  })
-
-  it('views from Atlas are included in merged output', () => {
-    const schema: AtlasSchema = {
-      schemas: [
-        {
-          name: 'public',
-          tables: [],
-          views: [
-            {
-              name: 'active_users',
-              columns: [
-                { name: 'id', type: 'bigserial' },
-                { name: 'email', type: 'text', null: true },
-              ],
-            },
-          ],
-        },
-      ],
-    }
-
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    expect(result.views).toHaveLength(1)
-    expect(result.views[0].name).toBe('active_users')
-    expect(result.views[0].columns).toHaveLength(2)
-    expect(result.views[0].columns[0].nullable).toBe(false) // no null field
-    expect(result.views[0].columns[1].nullable).toBe(true) // null: true
-  })
-
-  it('case-insensitive name matching between Atlas and sqldoc tags', () => {
-    const schema = makeAtlasSchema()
-    // Use quoted uppercase name in tags
-    const fileTags = makeFileTags([
-      {
-        objectName: '"Users"',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'description', args: ['Matched despite case'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    expect(result.tables[0].description).toBe('Matched despite case')
-  })
-
-  it('mermaidERD is passed through to MergedSchema', () => {
-    const schema = makeAtlasSchema()
-    const mermaid = 'erDiagram\n    users {\n      bigserial id PK\n    }'
-
-    const result = mergeSchemaWithTags(schema, mermaid, [], [], 'Test')
-
-    expect(result.mermaidERD).toBe(mermaid)
-  })
-
-  it('generatedAt is a valid ISO date string', () => {
-    const schema = makeAtlasSchema()
-
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    expect(result.generatedAt).toBeDefined()
-    const date = new Date(result.generatedAt)
-    expect(date.getTime()).not.toBeNaN()
-    expect(result.generatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/)
-  })
-
-  it('docs.emit(false) on view excludes it from output', () => {
-    const schema: AtlasSchema = {
-      schemas: [
-        {
-          name: 'public',
-          tables: [],
-          views: [
-            {
-              name: 'hidden_view',
-              columns: [{ name: 'id', type: 'int' }],
-            },
-          ],
-        },
-      ],
-    }
-    const fileTags = makeFileTags([
-      {
-        objectName: 'hidden_view',
-        target: 'view',
-        tags: [{ namespace: 'docs', tag: 'emit', args: [false] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    expect(result.views).toHaveLength(0)
-  })
-
-  it('docs.previously on table sets MergedTable.previously', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'users',
-        target: 'table',
-        tags: [{ namespace: 'docs', tag: 'previously', args: ['old_users'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    expect(result.tables[0].previously).toBe('old_users')
-  })
-
-  it('docs.previously on column sets MergedColumn.previously', () => {
-    const schema = makeAtlasSchema()
-    const fileTags = makeFileTags([
-      {
-        objectName: 'email',
-        target: 'column',
-        tags: [{ namespace: 'docs', tag: 'previously', args: ['email_address'] }],
-      },
-    ])
-
-    const result = mergeSchemaWithTags(schema, '', fileTags, [], 'Test')
-
-    const emailCol = result.tables[0].columns.find((c) => c.name === 'email')
-    expect(emailCol?.previously).toBe('email_address')
-  })
-
-  it('previously is undefined when no @docs.previously tag', () => {
-    const schema = makeAtlasSchema()
-    const result = mergeSchemaWithTags(schema, '', [], [], 'Test')
-
-    expect(result.tables[0].previously).toBeUndefined()
-    for (const col of result.tables[0].columns) {
-      expect(col.previously).toBeUndefined()
-    }
-  })
-})

package/src/__tests__/mermaid.test.ts

@@ -1,107 +0,0 @@
-import type { AtlasRealm } from '@sqldoc/atlas'
-import { describe, expect, it } from 'vitest'
-import { generateMermaidERD } from '../mermaid'
-
-// Minimal mock AtlasRealm matching the actual lowercase JSON from marshal.go
-const realm: AtlasRealm = {
-  schemas: [
-    {
-      name: 'public',
-      tables: [
-        {
-          name: 'users',
-          columns: [
-            { name: 'id', type: { raw: 'bigint', T: 'bigint', null: false } },
-            { name: 'email', type: { raw: 'text', T: 'text', null: false } },
-          ],
-          primary_key: { parts: [{ column: 'id' }] },
-          foreign_keys: [],
-        },
-        {
-          name: 'posts',
-          columns: [
-            { name: 'id', type: { raw: 'bigint', T: 'bigint', null: false } },
-            { name: 'user_id', type: { raw: 'bigint', T: 'bigint', null: false } },
-            { name: 'title', type: { raw: 'text', T: 'text', null: true } },
-          ],
-          primary_key: { parts: [{ column: 'id' }] },
-          foreign_keys: [
-            {
-              symbol: 'posts_user_id_fkey',
-              columns: ['user_id'],
-              ref_table: 'users',
-              ref_columns: ['id'],
-            },
-          ],
-        },
-      ],
-      views: [
-        {
-          name: 'active_users',
-          columns: [{ name: 'email', type: { raw: 'text', T: 'text' } }],
-        },
-      ],
-    },
-  ],
-}
-
-describe('generateMermaidERD', () => {
-  it('generates valid erDiagram header', () => {
-    const result = generateMermaidERD(realm)
-    expect(result).toMatch(/^erDiagram/)
-  })
-
-  it('table with columns produces entity block with types', () => {
-    const result = generateMermaidERD(realm)
-    expect(result).toContain('users {')
-    expect(result).toContain('bigint id')
-    expect(result).toContain('text email')
-  })
-
-  it('PK column marked with PK constraint', () => {
-    const result = generateMermaidERD(realm)
-    // users.id is PK
-    expect(result).toMatch(/bigint id PK/)
-  })
-
-  it('FK column marked with FK constraint and produces relationship line', () => {
-    const result = generateMermaidERD(realm)
-    // posts.user_id is FK
-    expect(result).toMatch(/bigint user_id FK/)
-    // Relationship line
-    expect(result).toMatch(/posts\s+\}o--\|\|\s+users/)
-  })
-
-  it('view produces entity block', () => {
-    const result = generateMermaidERD(realm)
-    expect(result).toContain('active_users {')
-    expect(result).toContain('text email')
-  })
-
-  it('empty realm produces just "erDiagram"', () => {
-    const emptyRealm: AtlasRealm = { schemas: [] }
-    const result = generateMermaidERD(emptyRealm)
-    expect(result).toBe('erDiagram')
-  })
-
-  it('posts.id is both PK (not FK)', () => {
-    const result = generateMermaidERD(realm)
-    // posts.id should be PK only, not FK
-    const lines = result.split('\n')
-    const _postIdLine = lines.find((l) => l.includes('posts') || l.trim().startsWith('bigint id'))
-    // Within the posts entity, id should have PK
-    // Grab lines between "posts {" and the closing "}"
-    const postsStart = lines.findIndex((l) => l.includes('posts {'))
-    const postsEnd = lines.findIndex((l, i) => i > postsStart && l.trim() === '}')
-    const postsLines = lines.slice(postsStart + 1, postsEnd)
-    const idLine = postsLines.find((l) => l.trim().startsWith('bigint id'))
-    expect(idLine).toBeDefined()
-    expect(idLine).toContain('PK')
-    expect(idLine).not.toContain('FK')
-  })
-
-  it('FK relationship includes foreign key symbol as label', () => {
-    const result = generateMermaidERD(realm)
-    expect(result).toContain('posts_user_id_fkey')
-  })
-})

package/src/__tests__/renderers/fixture.ts

@@ -1,109 +0,0 @@
-import type { MergedSchema } from '../../types'
-
-/**
- * Shared test fixture: 2 tables (one generated, one not), 1 view,
- * a mermaid ERD string, and various tags.
- */
-export function makeTestSchema(): MergedSchema {
-  return {
-    title: 'Test Schema Docs',
-    generatedAt: '2026-03-19T00:00:00.000Z',
-    mermaidERD: `erDiagram
-    users {
-      bigserial id PK
-      text email
-      text name
-    }
-    posts {
-      bigserial id PK
-      bigint user_id FK
-      text title
-    }
-    posts }o--o| users : posts_user_id_fkey`,
-    tables: [
-      {
-        name: 'users',
-        description: 'User accounts table',
-        previously: 'old_users',
-        isGenerated: false,
-        columns: [
-          { name: 'id', type: 'bigserial', nullable: false, isPrimaryKey: true, isForeignKey: false, tags: [] },
-          {
-            name: 'email',
-            type: 'text',
-            nullable: true,
-            description: 'Primary email',
-            previously: 'email_address',
-            isPrimaryKey: false,
-            isForeignKey: false,
-            tags: [],
-          },
-          { name: 'name', type: 'text', nullable: false, isPrimaryKey: false, isForeignKey: false, tags: [] },
-        ],
-        indexes: [{ name: 'users_email_idx', unique: true, parts: [{ column: 'email' }] }],
-        primaryKey: { parts: [{ column: 'id' }] },
-        foreignKeys: [],
-        tags: [
-          { namespace: 'docs', tag: 'description', args: ['User accounts table'] },
-          { namespace: 'audit', tag: 'track', args: { operations: ['INSERT', 'UPDATE'] } },
-          { namespace: 'rls', tag: null, args: ['admin_only'] },
-        ],
-      },
-      {
-        name: 'posts',
-        isGenerated: true,
-        generatedBy: 'audit',
-        columns: [
-          { name: 'id', type: 'bigserial', nullable: false, isPrimaryKey: true, isForeignKey: false, tags: [] },
-          { name: 'user_id', type: 'bigint', nullable: false, isPrimaryKey: false, isForeignKey: true, tags: [] },
-          { name: 'title', type: 'text', nullable: true, isPrimaryKey: false, isForeignKey: false, tags: [] },
-        ],
-        indexes: [],
-        primaryKey: { parts: [{ column: 'id' }] },
-        foreignKeys: [
-          {
-            name: 'posts_user_id_fkey',
-            columns: ['user_id'],
-            references: { table: 'users', columns: ['id'] },
-          },
-        ],
-        tags: [],
-      },
-    ],
-    views: [
-      {
-        name: 'active_users',
-        description: 'Active users view',
-        columns: [
-          { name: 'id', type: 'bigserial', nullable: false, isPrimaryKey: false, isForeignKey: false, tags: [] },
-          { name: 'email', type: 'text', nullable: true, isPrimaryKey: false, isForeignKey: false, tags: [] },
-        ],
-        tags: [{ namespace: 'docs', tag: 'description', args: ['Active users view'] }],
-      },
-    ],
-    extraRelationships: [],
-    annotations: [
-      { object: 'users', text: 'Audited (insert, update)' },
-      { object: 'users', text: 'RLS enabled' },
-    ],
-    extraColumnHeaders: ['Anonymization'],
-    extraColumnData: new Map([['users:email:Anonymization', 'Masked: anon.fake_email()']]),
-  }
-}
-
-/**
- * Minimal schema with no tables, no views -- for edge case testing.
- */
-export function makeMinimalSchema(): MergedSchema {
-  return {
-    title: 'Empty Schema',
-    generatedAt: '2026-03-19T00:00:00.000Z',
-    mermaidERD: 'erDiagram',
-    tables: [],
-    views: [],
-    extraRelationships: [],
-    annotations: [],
-    extraColumnHeaders: [],
-    extraColumnData: new Map(),
-  }
-}

package/src/__tests__/renderers/html.test.ts

@@ -1,122 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { renderHtml } from '../../renderers/html'
-import { makeMinimalSchema, makeTestSchema } from './fixture'
-
-describe('renderHtml', () => {
-  const schema = makeTestSchema()
-
-  it('output starts with <!DOCTYPE html>', () => {
-    const result = renderHtml(schema)
-    expect(result.trimStart()).toMatch(/^<!DOCTYPE html>/)
-  })
-
-  it('output contains <title> with schema title', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<title>Test Schema Docs</title>')
-  })
-
-  it('output contains sidebar nav with table links', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('class="sidebar"')
-    expect(result).toContain('<a href="#users">users</a>')
-    expect(result).toContain('<a href="#posts">posts</a>')
-  })
-
-  it('output contains sidebar Views section with view links', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<h2>Views</h2>')
-    expect(result).toContain('<a href="#active_users">active_users</a>')
-  })
-
-  it('output contains <pre class="mermaid"> with ERD content', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<pre class="mermaid">')
-    expect(result).toContain('erDiagram')
-  })
-
-  it('output contains <section id="{tableName}"> for each table', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<section id="users">')
-    expect(result).toContain('<section id="posts">')
-    expect(result).toContain('<section id="active_users">')
-  })
-
-  it('generated tables have generated-badge span', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('class="generated-badge"')
-    expect(result).toContain('Generated by @audit')
-  })
-
-  it('columns rendered in HTML table', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<th>Column</th>')
-    expect(result).toContain('<th>Type</th>')
-    expect(result).toContain('<td>bigserial</td>')
-  })
-
-  it('annotations rendered as <span class="annotation">', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<span class="annotation">')
-    expect(result).toContain('Audited (insert, update)')
-    expect(result).toContain('RLS enabled')
-  })
-
-  it('HTML-escaped content (no raw < or > in user strings)', () => {
-    // Create schema with potentially dangerous content
-    const dangerousSchema = makeTestSchema()
-    dangerousSchema.tables[0].description = '<script>alert("xss")</script>'
-    dangerousSchema.title = 'Test <b>bold</b> title'
-
-    const result = renderHtml(dangerousSchema)
-    expect(result).not.toContain('<script>alert')
-    expect(result).toContain('&lt;script&gt;')
-    expect(result).toContain('&lt;b&gt;bold&lt;/b&gt;')
-  })
-
-  it('script tag contains IntersectionObserver', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<script type="module">')
-    expect(result).toContain('IntersectionObserver')
-  })
-
-  it('embedded CSS contains sidebar and content styles', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('<style>')
-    expect(result).toContain('.sidebar')
-    expect(result).toContain('.content')
-    expect(result).toContain('.annotation')
-    expect(result).toContain('.generated-badge')
-  })
-
-  it('no Views sidebar section when no views present', () => {
-    const minimal = makeMinimalSchema()
-    const result = renderHtml(minimal)
-    // Should not have the Views heading in sidebar
-    // The sidebar should not contain Views h2 since no views
-    const sidebarMatch = result.match(/<nav class="sidebar">([\s\S]*?)<\/nav>/)
-    expect(sidebarMatch).toBeTruthy()
-    expect(sidebarMatch![1]).not.toContain('<h2>Views</h2>')
-  })
-
-  it('table with previously shows "formerly" paragraph', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('class="previously"')
-    expect(result).toContain('formerly: old_users')
-  })
-
-  it('column with previously shows "formerly" in description cell', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('formerly: email_address')
-  })
-
-  it('description paragraph has class "description"', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('class="description"')
-  })
-
-  it('timestamp paragraph has class "timestamp"', () => {
-    const result = renderHtml(schema)
-    expect(result).toContain('class="timestamp"')
-    expect(result).toContain('Generated:')
-  })
-})

package/src/__tests__/renderers/markdown.test.ts

@@ -1,121 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { renderMarkdown } from '../../renderers/markdown'
-import { makeMinimalSchema, makeTestSchema } from './fixture'
-
-describe('renderMarkdown', () => {
-  // Reuse the shared fixture for most tests
-  const schema = makeTestSchema()
-
-  // Generate once for all tests
-  const _output = renderMarkdown(schema)
-
-  it('output contains title as H1', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('# Test Schema Docs')
-  })
-
-  it('output contains mermaid code block with erDiagram content', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('```mermaid')
-    expect(result).toContain('erDiagram')
-    expect(result).toContain('bigserial id PK')
-    expect(result).toContain('```')
-  })
-
-  it('output contains table of contents with anchor links', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('## Contents')
-    expect(result).toMatch(/\[users\]\(#users\)/)
-    expect(result).toMatch(/\[posts\]\(#posts\)/)
-    expect(result).toMatch(/\[active_users\]\(#active_users\)/)
-  })
-
-  it('each table has columns table with correct headers', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('| Column | Type | Nullable | PK | FK | Description |')
-  })
-
-  it('generated tables have "(Generated by @namespace)" annotation', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('(Generated by @audit)')
-  })
-
-  it('non-generated tables do not have generated annotation', () => {
-    const result = renderMarkdown(schema)
-    // "users" section should NOT have "Generated by"
-    const usersIdx = result.indexOf('### users')
-    const postsIdx = result.indexOf('### posts')
-    const between = result.slice(usersIdx, postsIdx)
-    expect(between).not.toContain('Generated by')
-  })
-
-  it('table with previously shows "formerly" line', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('*formerly: old_users*')
-  })
-
-  it('column with previously shows "formerly" in description cell', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('*formerly: email_address*')
-  })
-
-  it('annotations rendered as blockquotes', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('> Audited (insert, update)')
-    expect(result).toContain('> RLS enabled')
-  })
-
-  it('extra column headers appear in column table', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('Anonymization')
-    expect(result).toContain('Masked: anon.fake_email()')
-  })
-
-  it('FK section rendered when foreignKeys present', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('#### Foreign Keys')
-    expect(result).toContain('posts_user_id_fkey')
-    expect(result).toContain('users(id)')
-  })
-
-  it('indexes section rendered when indexes present', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('#### Indexes')
-    expect(result).toContain('users_email_idx')
-    expect(result).toContain('UNIQUE')
-  })
-
-  it('views section rendered when views present', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('## Views')
-    expect(result).toContain('### active_users')
-  })
-
-  it('empty schema produces minimal output (title + empty sections)', () => {
-    const minimal = makeMinimalSchema()
-    const result = renderMarkdown(minimal)
-    expect(result).toContain('# Empty Schema')
-    expect(result).toContain('```mermaid')
-    expect(result).not.toContain('## Views')
-  })
-
-  it('column rows contain correct PK/FK markers', () => {
-    const result = renderMarkdown(schema)
-    // The "id" column in users should have PK=Y
-    // We need to find the users columns table and check the id row
-    const lines = result.split('\n')
-    const idLine = lines.find((l) => l.includes('| id |') && l.includes('bigserial'))
-    expect(idLine).toBeDefined()
-    expect(idLine).toContain('| Y |')
-
-    // user_id in posts should have FK=Y
-    const fkLine = lines.find((l) => l.includes('| user_id |'))
-    expect(fkLine).toBeDefined()
-    expect(fkLine).toMatch(/\|\s*Y\s*\|/)
-  })
-
-  it('generated timestamp is present', () => {
-    const result = renderMarkdown(schema)
-    expect(result).toContain('*Generated:')
-  })
-})