@sqldoc/ns-docs 0.0.1

package/src/merge.ts

@@ -0,0 +1,226 @@
+import type { CompilerOutput, DocsMeta, SqlTarget } from '@sqldoc/core'
+import type {
+  AtlasSchema,
+  AtlasTable,
+  DocsAnnotation,
+  DocsColumnEntry,
+  DocsRelationship,
+  MergedColumn,
+  MergedSchema,
+  MergedTable,
+  MergedTag,
+  MergedView,
+} from './types.ts'
+
+interface FileTagData {
+  sourceFile: string
+  objects: Array<{
+    objectName: string
+    target: SqlTarget
+    tags: Array<{
+      namespace: string
+      tag: string | null
+      args: Record<string, unknown> | unknown[]
+    }>
+  }>
+}
+
+/** Normalize SQL identifier for matching: lowercase, strip surrounding quotes */
+function normalizeName(name: string): string {
+  const stripped = name.replace(/^["']|["']$/g, '')
+  return stripped.toLowerCase()
+}
+
+/** Check if an object has docs.emit(false) */
+function isExcluded(tags: MergedTag[]): boolean {
+  return tags.some((t) => t.namespace === 'docs' && t.tag === 'emit' && (t.args as unknown[])[0] === false)
+}
+
+/** Extract docs.description value from tags */
+function getDescription(tags: MergedTag[]): string | undefined {
+  const descTag = tags.find((t) => t.namespace === 'docs' && t.tag === 'description')
+  if (!descTag) return undefined
+  return (descTag.args as unknown[])[0] as string | undefined
+}
+
+/** Extract docs.previously value from tags */
+function getPreviously(tags: MergedTag[]): string | undefined {
+  const prevTag = tags.find((t) => t.namespace === 'docs' && t.tag === 'previously')
+  if (!prevTag) return undefined
+  return (prevTag.args as unknown[])[0] as string | undefined
+}
+
+/** Build a set of generated table names from compiler outputs */
+function buildGeneratedSet(outputs: CompilerOutput[]): Map<string, string> {
+  const generated = new Map<string, string>()
+  for (const output of outputs) {
+    for (const sqlOut of output.sqlOutputs) {
+      // Match CREATE TABLE "name" patterns in generated SQL
+      const match = sqlOut.sql.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?/i)
+      if (match) {
+        const tableName = normalizeName(match[1])
+        const ns = sqlOut.sourceTag?.match(/@(\w+)/)?.[1] ?? 'unknown'
+        generated.set(tableName, ns)
+      }
+    }
+  }
+  return generated
+}
+
+/** Build tag lookup: normalized objectName -> entries with target and tags */
+function buildTagMap(allFileTags: FileTagData[]): Map<string, { target: SqlTarget; tags: MergedTag[] }[]> {
+  const map = new Map<string, { target: SqlTarget; tags: MergedTag[] }[]>()
+  for (const file of allFileTags) {
+    for (const obj of file.objects) {
+      const key = normalizeName(obj.objectName)
+      const existing = map.get(key) ?? []
+      existing.push({
+        target: obj.target,
+        tags: obj.tags.map((t) => ({
+          namespace: t.namespace,
+          tag: t.tag,
+          args: t.args,
+        })),
+      })
+      map.set(key, existing)
+    }
+  }
+  return map
+}
+
+/** Get all tags for an object by normalized name (flatten across files, table/view level only) */
+function getObjectTags(tagMap: Map<string, { target: SqlTarget; tags: MergedTag[] }[]>, name: string): MergedTag[] {
+  const entries = tagMap.get(normalizeName(name)) ?? []
+  return entries.filter((e) => e.target !== 'column').flatMap((e) => e.tags)
+}
+
+/** Get column-level tags — checks both "column" and "table.column" keys */
+function getColumnTags(
+  tagMap: Map<string, { target: SqlTarget; tags: MergedTag[] }[]>,
+  columnName: string,
+  tableName?: string,
+): MergedTag[] {
+  // Try table.column first (Atlas convention), then bare column name
+  const keys = tableName
+    ? [normalizeName(`${tableName}.${columnName}`), normalizeName(columnName)]
+    : [normalizeName(columnName)]
+
+  for (const key of keys) {
+    const entries = tagMap.get(key) ?? []
+    const tags = entries.filter((e) => e.target === 'column').flatMap((e) => e.tags)
+    if (tags.length > 0) return tags
+  }
+  return []
+}
+
+function mergeTable(
+  table: AtlasTable,
+  tagMap: Map<string, { target: SqlTarget; tags: MergedTag[] }[]>,
+  generatedSet: Map<string, string>,
+): MergedTable | null {
+  const tableTags = getObjectTags(tagMap, table.name)
+  if (isExcluded(tableTags)) return null
+
+  const pkColumns = new Set((table.primary_key?.parts ?? []).map((p) => normalizeName(p.column)))
+  const fkColumns = new Set((table.foreign_keys ?? []).flatMap((fk) => fk.columns.map((c) => normalizeName(c))))
+
+  const columns: MergedColumn[] = table.columns.map((col) => {
+    const colTags = getColumnTags(tagMap, col.name, table.name)
+    return {
+      name: col.name,
+      type: col.type,
+      nullable: col.null === true,
+      description: getDescription(colTags),
+      previously: getPreviously(colTags),
+      isPrimaryKey: pkColumns.has(normalizeName(col.name)),
+      isForeignKey: fkColumns.has(normalizeName(col.name)),
+      tags: colTags,
+    }
+  })
+
+  const normalizedName = normalizeName(table.name)
+  const generatedBy = generatedSet.get(normalizedName)
+
+  return {
+    name: table.name,
+    description: getDescription(tableTags),
+    previously: getPreviously(tableTags),
+    isGenerated: !!generatedBy,
+    generatedBy,
+    columns,
+    indexes: table.indexes ?? [],
+    primaryKey: table.primary_key,
+    foreignKeys: table.foreign_keys ?? [],
+    tags: tableTags,
+  }
+}
+
+export function mergeSchemaWithTags(
+  schema: AtlasSchema,
+  mermaid: string,
+  allFileTags: FileTagData[],
+  outputs: CompilerOutput[],
+  title: string,
+  docsMeta: DocsMeta[] = [],
+): MergedSchema {
+  const tagMap = buildTagMap(allFileTags)
+  const generatedSet = buildGeneratedSet(outputs)
+
+  const tables: MergedTable[] = []
+  const views: MergedView[] = []
+
+  for (const s of schema.schemas) {
+    for (const table of s.tables ?? []) {
+      const merged = mergeTable(table, tagMap, generatedSet)
+      if (merged) tables.push(merged)
+    }
+    for (const view of s.views ?? []) {
+      const viewTags = getObjectTags(tagMap, view.name)
+      if (isExcluded(viewTags)) continue
+      views.push({
+        name: view.name,
+        description: getDescription(viewTags),
+        columns: view.columns.map((col) => ({
+          name: col.name,
+          type: col.type,
+          nullable: col.null === true,
+          isPrimaryKey: false,
+          isForeignKey: false,
+          tags: [],
+        })),
+        tags: viewTags,
+      })
+    }
+  }
+
+  // Aggregate docs metadata from plugins
+  const extraRelationships: DocsRelationship[] = docsMeta.flatMap((d) => d.relationships ?? [])
+  const annotations: DocsAnnotation[] = docsMeta.flatMap((d) => d.annotations ?? [])
+
+  // Collect extra column headers and data
+  const allColumnEntries: DocsColumnEntry[] = docsMeta.flatMap((d) => d.columns ?? [])
+  const headerSet = new Set<string>()
+  const extraColumnData = new Map<string, string>()
+  for (const entry of allColumnEntries) {
+    headerSet.add(entry.header)
+    const key = entry.column
+      ? `${entry.object.toLowerCase()}:${entry.column.toLowerCase()}:${entry.header}`
+      : `${entry.object.toLowerCase()}::${entry.header}`
+    // Append if multiple values for same cell
+    const existing = extraColumnData.get(key)
+    extraColumnData.set(key, existing ? `${existing}, ${entry.value}` : entry.value)
+  }
+  const extraColumnHeaders = [...headerSet]
+
+  return {
+    title,
+    generatedAt: new Date().toISOString(),
+    tables,
+    views,
+    mermaidERD: mermaid,
+    extraRelationships,
+    annotations,
+    extraColumnHeaders,
+    extraColumnData,
+  }
+}

package/src/mermaid.ts

@@ -0,0 +1,67 @@
+import type { AtlasRealm } from '@sqldoc/atlas'
+
+/**
+ * Generate a Mermaid erDiagram string from an Atlas schema realm.
+ * Replaces the `{{ mermaid . }}` Atlas Go template.
+ */
+export function generateMermaidERD(realm: AtlasRealm): string {
+  const lines: string[] = ['erDiagram']
+
+  for (const schema of realm.schemas) {
+    // Tables
+    for (const table of schema.tables ?? []) {
+      lines.push(`    ${escapeMermaid(table.name)} {`)
+
+      // Determine PK and FK columns
+      const pkCols = new Set<string>()
+      if (table.primary_key?.parts) {
+        for (const part of table.primary_key.parts) {
+          if (part.column) pkCols.add(part.column)
+        }
+      }
+      const fkCols = new Set<string>()
+      for (const fk of table.foreign_keys ?? []) {
+        for (const col of fk.columns ?? []) {
+          fkCols.add(col)
+        }
+      }
+
+      for (const col of table.columns ?? []) {
+        const typeName = col.type?.raw ?? col.type?.T ?? 'unknown'
+        const constraints: string[] = []
+        if (pkCols.has(col.name)) constraints.push('PK')
+        if (fkCols.has(col.name)) constraints.push('FK')
+        const constraintStr = constraints.length > 0 ? ` ${constraints.join(',')}` : ''
+        lines.push(`        ${escapeMermaid(typeName)} ${escapeMermaid(col.name)}${constraintStr}`)
+      }
+      lines.push('    }')
+    }
+
+    // Views (entity name with columns)
+    for (const view of schema.views ?? []) {
+      lines.push(`    ${escapeMermaid(view.name)} {`)
+      for (const col of view.columns ?? []) {
+        const typeName = col.type?.raw ?? col.type?.T ?? 'unknown'
+        lines.push(`        ${escapeMermaid(typeName)} ${escapeMermaid(col.name)}`)
+      }
+      lines.push('    }')
+    }
+
+    // Foreign key relationships
+    for (const table of schema.tables ?? []) {
+      for (const fk of table.foreign_keys ?? []) {
+        if (fk.ref_table) {
+          // Determine cardinality (default: many-to-one)
+          lines.push(`    ${escapeMermaid(table.name)} }o--|| ${escapeMermaid(fk.ref_table)} : "${fk.symbol ?? 'fk'}"`)
+        }
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function escapeMermaid(name: string): string {
+  // Mermaid entity names can't have special chars; replace quotes, spaces
+  return name.replace(/"/g, '').replace(/\s+/g, '_')
+}

package/src/renderers/html.ts

@@ -0,0 +1,250 @@
+import type { DocsAnnotation, MergedSchema, MergedTable, MergedView } from '../types.ts'
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function getTableAnnotations(annotations: DocsAnnotation[], tableName: string): string[] {
+  return annotations.filter((a) => a.object.toLowerCase() === tableName.toLowerCase()).map((a) => a.text)
+}
+
+function getExtraCell(data: Map<string, string>, tableName: string, colName: string, header: string): string {
+  const key = `${tableName.toLowerCase()}:${colName.toLowerCase()}:${header}`
+  return data.get(key) ?? '-'
+}
+
+function renderAnnotationBadges(annotations: string[]): string {
+  if (annotations.length === 0) return ''
+  const badges = annotations.map((a) => `<span class="annotation">${escapeHtml(a)}</span>`).join('\n      ')
+  return `    <div class="annotations">\n      ${badges}\n    </div>`
+}
+
+function renderTableSection(table: MergedTable, schema: MergedSchema): string {
+  const parts: string[] = []
+  const extras = schema.extraColumnHeaders
+
+  parts.push(`  <section id="${escapeHtml(table.name)}">`)
+
+  let heading = `    <h3>${escapeHtml(table.name)}`
+  if (table.isGenerated && table.generatedBy) {
+    heading += ` <span class="generated-badge">Generated by @${escapeHtml(table.generatedBy)}</span>`
+  }
+  heading += '</h3>'
+  parts.push(heading)
+
+  if (table.previously) {
+    parts.push(`    <p class="previously">formerly: ${escapeHtml(table.previously)}</p>`)
+  }
+
+  if (table.description) {
+    parts.push(`    <p class="description">${escapeHtml(table.description)}</p>`)
+  }
+
+  const tableAnnots = getTableAnnotations(schema.annotations, table.name)
+  const annotBadges = renderAnnotationBadges(tableAnnots)
+  if (annotBadges) parts.push(annotBadges)
+
+  // Column table with extra plugin columns
+  const extraHeaders = extras.map((h) => `          <th>${escapeHtml(h)}</th>`).join('\n')
+  const rows = table.columns
+    .map((col) => {
+      const pk = col.isPrimaryKey ? 'Y' : '-'
+      const fk = col.isForeignKey ? 'Y' : '-'
+      const nullable = col.nullable ? 'Yes' : 'No'
+      let desc = col.description ? escapeHtml(col.description) : '-'
+      if (col.previously) {
+        const formerly = `<em class="previously">formerly: ${escapeHtml(col.previously)}</em>`
+        desc = desc === '-' ? formerly : `${desc} ${formerly}`
+      }
+      const extraCells = extras
+        .map((h) => {
+          const val = getExtraCell(schema.extraColumnData, table.name, col.name, h)
+          return `        <td>${val === '-' ? '-' : escapeHtml(val)}</td>`
+        })
+        .join('\n')
+      return `      <tr>
+        <td>${escapeHtml(col.name)}</td>
+        <td>${escapeHtml(col.type)}</td>
+        <td>${nullable}</td>
+        <td>${pk}</td>
+        <td>${fk}</td>
+        <td>${desc}</td>
+${extraCells}
+      </tr>`
+    })
+    .join('\n')
+
+  parts.push(`    <table>
+      <thead>
+        <tr>
+          <th>Column</th>
+          <th>Type</th>
+          <th>Nullable</th>
+          <th>PK</th>
+          <th>FK</th>
+          <th>Description</th>
+${extraHeaders}
+        </tr>
+      </thead>
+      <tbody>
+${rows}
+      </tbody>
+    </table>`)
+
+  if (table.foreignKeys.length > 0) {
+    parts.push('    <h4>Foreign Keys</h4>')
+    parts.push('    <ul>')
+    for (const fk of table.foreignKeys) {
+      const cols = fk.columns.join(', ')
+      const refCols = fk.references.columns.join(', ')
+      parts.push(
+        `      <li>${escapeHtml(fk.name)}: ${escapeHtml(cols)} -&gt; ${escapeHtml(fk.references.table)}(${escapeHtml(refCols)})</li>`,
+      )
+    }
+    parts.push('    </ul>')
+  }
+
+  if (table.indexes.length > 0) {
+    parts.push('    <h4>Indexes</h4>')
+    parts.push('    <ul>')
+    for (const idx of table.indexes) {
+      const idxParts = idx.parts.map((p) => p.column).join(', ')
+      const unique = idx.unique ? ' UNIQUE' : ''
+      parts.push(`      <li>${escapeHtml(idx.name)} (${escapeHtml(idxParts)})${unique}</li>`)
+    }
+    parts.push('    </ul>')
+  }
+
+  parts.push('  </section>')
+  return parts.join('\n')
+}
+
+function renderViewSection(view: MergedView): string {
+  const parts: string[] = []
+
+  parts.push(`  <section id="${escapeHtml(view.name)}">`)
+  parts.push(`    <h3>${escapeHtml(view.name)}</h3>`)
+
+  if (view.description) {
+    parts.push(`    <p class="description">${escapeHtml(view.description)}</p>`)
+  }
+
+  const rows = view.columns
+    .map((col) => {
+      const desc = col.description ? escapeHtml(col.description) : '-'
+      const nullable = col.nullable ? 'Yes' : 'No'
+      return `      <tr>
+        <td>${escapeHtml(col.name)}</td>
+        <td>${escapeHtml(col.type)}</td>
+        <td>${nullable}</td>
+        <td>-</td>
+        <td>-</td>
+        <td>${desc}</td>
+      </tr>`
+    })
+    .join('\n')
+
+  parts.push(`    <table>
+      <thead>
+        <tr>
+          <th>Column</th>
+          <th>Type</th>
+          <th>Nullable</th>
+          <th>PK</th>
+          <th>FK</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+${rows}
+      </tbody>
+    </table>`)
+
+  parts.push('  </section>')
+  return parts.join('\n')
+}
+
+export function renderHtml(schema: MergedSchema): string {
+  const tableLinks = schema.tables
+    .map((t) => `    <a href="#${escapeHtml(t.name)}">${escapeHtml(t.name)}</a>`)
+    .join('\n')
+
+  const viewLinks = schema.views.map((v) => `    <a href="#${escapeHtml(v.name)}">${escapeHtml(v.name)}</a>`).join('\n')
+
+  const viewsSidebar = schema.views.length > 0 ? `\n    <h2>Views</h2>\n${viewLinks}` : ''
+
+  const tableSections = schema.tables.map((t) => renderTableSection(t, schema)).join('\n')
+  const viewSections = schema.views.map(renderViewSection).join('\n')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(schema.title)}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; display: flex; }
+    .sidebar { width: 260px; height: 100vh; position: fixed; overflow-y: auto; background: #f8f9fa; border-right: 1px solid #dee2e6; padding: 16px; }
+    .sidebar h1 { font-size: 18px; margin-bottom: 16px; }
+    .sidebar h2 { font-size: 14px; text-transform: uppercase; color: #6c757d; margin: 16px 0 8px; }
+    .sidebar a { display: block; padding: 4px 8px; color: #212529; text-decoration: none; font-size: 14px; border-radius: 4px; }
+    .sidebar a:hover { background: #e9ecef; }
+    .sidebar a.active { background: #0d6efd; color: white; }
+    .content { margin-left: 260px; padding: 32px; max-width: 1100px; }
+    table { border-collapse: collapse; width: 100%; margin: 16px 0; }
+    th, td { border: 1px solid #dee2e6; padding: 8px 12px; text-align: left; }
+    th { background: #f8f9fa; }
+    .annotation { display: inline-block; background: #d1ecf1; color: #0c5460; border-radius: 4px; padding: 2px 8px; font-size: 12px; margin: 2px; }
+    .annotations { margin: 8px 0; }
+    .generated-badge { display: inline-block; background: #fff3cd; color: #856404; border-radius: 4px; padding: 2px 6px; font-size: 12px; }
+    .description { color: #495057; margin: 8px 0; }
+    .previously { color: #6c757d; font-style: italic; font-size: 13px; margin: 4px 0; display: block; }
+    h3 { margin-top: 32px; padding-top: 16px; border-top: 1px solid #dee2e6; }
+    .mermaid { margin: 24px 0; padding: 16px; background: #f8f9fa; border-radius: 8px; }
+    .timestamp { color: #6c757d; font-size: 14px; }
+    h4 { margin: 16px 0 8px; font-size: 15px; }
+    ul { margin: 0 0 16px 24px; }
+    li { margin: 4px 0; }
+  </style>
+</head>
+<body>
+  <nav class="sidebar">
+    <h1>${escapeHtml(schema.title)}</h1>
+    <h2>Tables</h2>
+${tableLinks}${viewsSidebar}
+  </nav>
+  <main class="content">
+    <p class="timestamp">Generated: ${escapeHtml(schema.generatedAt)}</p>
+    <section id="er-diagram">
+      <h2>Entity Relationship Diagram</h2>
+      <pre class="mermaid">${escapeHtml(schema.mermaidERD)}${schema.extraRelationships
+        .map((rel) => `\n    ${rel.from} ||..o{ ${rel.to} : "${rel.label}"`)
+        .join('')}</pre>
+    </section>
+${tableSections}
+${viewSections}
+  </main>
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: true });
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          document.querySelectorAll('.sidebar a').forEach(a => a.classList.remove('active'));
+          const link = document.querySelector('.sidebar a[href="#' + entry.target.id + '"]');
+          if (link) link.classList.add('active');
+        }
+      });
+    }, { threshold: 0.3 });
+    document.querySelectorAll('section[id]').forEach(s => observer.observe(s));
+  </script>
+</body>
+</html>`
+}

package/src/renderers/markdown.ts

@@ -0,0 +1,160 @@
+import type { DocsAnnotation, MergedSchema, MergedTable, MergedView } from '../types.ts'
+
+function getTableAnnotations(annotations: DocsAnnotation[], tableName: string): string[] {
+  return annotations.filter((a) => a.object.toLowerCase() === tableName.toLowerCase()).map((a) => a.text)
+}
+
+function getExtraCell(data: Map<string, string>, tableName: string, colName: string, header: string): string {
+  const key = `${tableName.toLowerCase()}:${colName.toLowerCase()}:${header}`
+  return data.get(key) ?? '-'
+}
+
+function renderTableSection(table: MergedTable, schema: MergedSchema): string {
+  const lines: string[] = []
+  const extras = schema.extraColumnHeaders
+
+  let heading = `### ${table.name}`
+  if (table.isGenerated && table.generatedBy) {
+    heading += ` (Generated by @${table.generatedBy})`
+  }
+  lines.push(heading)
+  lines.push('')
+
+  if (table.previously) {
+    lines.push(`*formerly: ${table.previously}*`)
+    lines.push('')
+  }
+
+  if (table.description) {
+    lines.push(table.description)
+    lines.push('')
+  }
+
+  const tableAnnots = getTableAnnotations(schema.annotations, table.name)
+  if (tableAnnots.length > 0) {
+    lines.push(tableAnnots.map((a) => `> ${a}`).join('\n'))
+    lines.push('')
+  }
+
+  // Column table header
+  const baseHeaders = ['Column', 'Type', 'Nullable', 'PK', 'FK', 'Description']
+  const allHeaders = [...baseHeaders, ...extras]
+  lines.push(`| ${allHeaders.join(' | ')} |`)
+  lines.push(`|${allHeaders.map(() => '------').join('|')}|`)
+
+  for (const col of table.columns) {
+    const pk = col.isPrimaryKey ? 'Y' : '-'
+    const fk = col.isForeignKey ? 'Y' : '-'
+    const nullable = col.nullable ? 'Yes' : 'No'
+    let desc = col.description ?? '-'
+    if (col.previously) {
+      const formerly = `*formerly: ${col.previously}*`
+      desc = desc === '-' ? formerly : `${desc} ${formerly}`
+    }
+    const baseCells = [col.name, col.type, nullable, pk, fk, desc]
+    const extraCells = extras.map((h) => getExtraCell(schema.extraColumnData, table.name, col.name, h))
+    lines.push(`| ${[...baseCells, ...extraCells].join(' | ')} |`)
+  }
+  lines.push('')
+
+  if (table.foreignKeys.length > 0) {
+    lines.push('#### Foreign Keys')
+    lines.push('')
+    for (const fk of table.foreignKeys) {
+      const cols = fk.columns.join(', ')
+      const refCols = fk.references.columns.join(', ')
+      lines.push(`- ${fk.name}: ${cols} -> ${fk.references.table}(${refCols})`)
+    }
+    lines.push('')
+  }
+
+  if (table.indexes.length > 0) {
+    lines.push('#### Indexes')
+    lines.push('')
+    for (const idx of table.indexes) {
+      const parts = idx.parts.map((p) => p.column).join(', ')
+      const unique = idx.unique ? ' UNIQUE' : ''
+      lines.push(`- ${idx.name} (${parts})${unique}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+function renderViewSection(view: MergedView): string {
+  const lines: string[] = []
+
+  lines.push(`### ${view.name}`)
+  lines.push('')
+
+  if (view.description) {
+    lines.push(view.description)
+    lines.push('')
+  }
+
+  lines.push('| Column | Type | Nullable | PK | FK | Description |')
+  lines.push('|------|------|----------|----|----|-------------|')
+  for (const col of view.columns) {
+    const desc = col.description ?? '-'
+    const nullable = col.nullable ? 'Yes' : 'No'
+    lines.push(`| ${col.name} | ${col.type} | ${nullable} | - | - | ${desc} |`)
+  }
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+export function renderMarkdown(schema: MergedSchema): string {
+  const lines: string[] = []
+
+  lines.push(`# ${schema.title}`)
+  lines.push('')
+  lines.push(`*Generated: ${schema.generatedAt}*`)
+  lines.push('')
+
+  lines.push('## Contents')
+  lines.push('')
+  if (schema.tables.length > 0) {
+    lines.push('**Tables:**')
+    for (const table of schema.tables) {
+      lines.push(`- [${table.name}](#${table.name})`)
+    }
+    lines.push('')
+  }
+  if (schema.views.length > 0) {
+    lines.push('**Views:**')
+    for (const view of schema.views) {
+      lines.push(`- [${view.name}](#${view.name})`)
+    }
+    lines.push('')
+  }
+
+  lines.push('## Entity Relationship Diagram')
+  lines.push('')
+  lines.push('```mermaid')
+  lines.push(schema.mermaidERD)
+  for (const rel of schema.extraRelationships) {
+    lines.push(`    ${rel.from} ||..o{ ${rel.to} : "${rel.label}"`)
+  }
+  lines.push('```')
+  lines.push('')
+
+  if (schema.tables.length > 0) {
+    lines.push('## Tables')
+    lines.push('')
+    for (const table of schema.tables) {
+      lines.push(renderTableSection(table, schema))
+    }
+  }
+
+  if (schema.views.length > 0) {
+    lines.push('## Views')
+    lines.push('')
+    for (const view of schema.views) {
+      lines.push(renderViewSection(view))
+    }
+  }
+
+  return lines.join('\n')
+}