@sqldoc/ns-docs 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "type": "module",
+  "name": "@sqldoc/ns-docs",
+  "version": "0.0.1",
+  "description": "Documentation namespace for sqldoc -- generates Markdown/HTML docs with Mermaid ER diagrams via Atlas CLI",
+  "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",
+    "@sqldoc/atlas": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@sqldoc/atlas": "0.0.1",
+    "@sqldoc/core": "0.0.1"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/__tests__/atlas.test.ts

@@ -0,0 +1,134 @@
+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

@@ -0,0 +1,401 @@
+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

@@ -0,0 +1,107 @@
+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')
+  })
+})