@sqldoc/core 0.0.1

package/src/ast/sqlparser-ts.ts

@@ -0,0 +1,218 @@
+import * as sp from '@sqldoc/sqlparser-ts'
+import type { SqlAstAdapter } from './adapter.ts'
+import type { SqlColumn, SqlCommentOn, SqlStatement } from './types.ts'
+
+/**
+ * AST adapter backed by @sqldoc/sqlparser-ts (WASM-based, multi-dialect).
+ * Uses real span info from the parser for line-based matching.
+ */
+export class SqlparserTsAdapter implements SqlAstAdapter {
+  private initialized = false
+  private parseFn!: (sql: string, dialect?: any) => any[]
+
+  async init(): Promise<void> {
+    if (this.initialized) return
+    await sp.init()
+    this.parseFn = sp.parse
+    this.initialized = true
+  }
+
+  parseStatements(sql: string): SqlStatement[] {
+    if (!this.initialized) {
+      throw new Error('SqlparserTsAdapter not initialized. Call init() first.')
+    }
+
+    let ast: any[]
+    try {
+      ast = this.parseFn(sql, 'postgresql')
+    } catch {
+      // Full parse failed — try statement by statement
+      return this.parseStatementByStatement(sql)
+    }
+
+    const results: SqlStatement[] = []
+    for (const stmt of ast) {
+      const mapped = mapStatement(stmt)
+      if (mapped) results.push(mapped)
+    }
+    return results
+  }
+
+  private parseStatementByStatement(sql: string): SqlStatement[] {
+    const results: SqlStatement[] = []
+    const chunks = splitStatements(sql)
+    let charOffset = 0
+    for (const chunk of chunks) {
+      const trimmed = chunk.trim()
+      if (!trimmed) {
+        charOffset += chunk.length + 1 // +1 for semicolon
+        continue
+      }
+      // Count newlines before this chunk to get line offset
+      const lineOffset = sql.substring(0, charOffset + chunk.indexOf(trimmed[0])).split('\n').length - 1
+      try {
+        const ast = this.parseFn(`${trimmed};`, 'postgresql')
+        for (const stmt of ast) {
+          const mapped = mapStatement(stmt)
+          if (mapped) {
+            mapped.line += lineOffset
+            if (mapped.columns) {
+              for (const col of mapped.columns) {
+                col.line += lineOffset
+              }
+            }
+            results.push(mapped)
+          }
+        }
+      } catch {
+        // Skip unparseable statements
+      }
+      charOffset += chunk.length + 1
+    }
+    return results
+  }
+
+  parseComments(sql: string): SqlCommentOn[] {
+    if (!this.initialized) {
+      throw new Error('SqlparserTsAdapter not initialized. Call init() first.')
+    }
+
+    let ast: any[]
+    try {
+      ast = this.parseFn(sql, 'postgresql')
+    } catch {
+      return []
+    }
+
+    const results: SqlCommentOn[] = []
+    for (const stmt of ast) {
+      const key = Object.keys(stmt)[0]
+      if (key !== 'Comment') continue
+
+      const node = stmt.Comment
+      const objectType = node.object_type as string
+      const names = extractNames(node.object_name)
+      const comment = node.comment as string
+
+      let targetKey: string
+      if (objectType === 'Column' && names.length >= 2) {
+        targetKey = `COLUMN "${names[names.length - 2]}"."${names[names.length - 1]}"`
+      } else {
+        targetKey = `${objectType.toUpperCase()} "${names[names.length - 1] ?? ''}"`
+      }
+
+      const line = getSpanLine(node.object_name?.[0])
+      results.push({ targetKey, content: comment, line })
+    }
+
+    return results
+  }
+}
+
+// ── Statement splitting ─────────────────────────────────────────────
+
+/** Split SQL on semicolons, respecting $$ dollar-quoted blocks */
+function splitStatements(sql: string): string[] {
+  const results: string[] = []
+  let current = ''
+  let inDollarQuote = false
+  for (let i = 0; i < sql.length; i++) {
+    if (sql[i] === '$' && sql[i + 1] === '$') {
+      inDollarQuote = !inDollarQuote
+      current += '$$'
+      i++
+      continue
+    }
+    if (sql[i] === ';' && !inDollarQuote) {
+      results.push(current)
+      current = ''
+      continue
+    }
+    current += sql[i]
+  }
+  if (current.trim()) results.push(current)
+  return results
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/** Extract the start line (1-based) from an AST node's span */
+function getSpanLine(node: any): number {
+  if (!node) return 1
+  const span = node.Identifier?.span ?? node.span
+  return span?.start?.line ?? 1
+}
+
+/** Extract names from a name array */
+function extractNames(nameArray: any[]): string[] {
+  if (!nameArray) return []
+  return nameArray.map((n: any) => n.Identifier?.value ?? n?.value).filter(Boolean)
+}
+
+function extractName(nameArray: any[]): string {
+  return extractNames(nameArray).join('.')
+}
+
+/** Map an AST statement node to our SqlStatement type */
+function mapStatement(stmt: any): SqlStatement | null {
+  const key = Object.keys(stmt)[0]
+  const node = stmt[key]
+
+  switch (key) {
+    case 'CreateTable':
+      return {
+        kind: 'table',
+        objectName: extractName(node.name),
+        line: getSpanLine(node.name?.[0]),
+        columns: mapColumns(node.columns ?? []),
+        raw: node,
+      }
+    case 'CreateView':
+      return { kind: 'view', objectName: extractName(node.name), line: getSpanLine(node.name?.[0]), raw: node }
+    case 'CreateIndex':
+      return { kind: 'index', objectName: extractName(node.name), line: getSpanLine(node.name?.[0]), raw: node }
+    case 'CreateType':
+      return { kind: 'type', objectName: extractName(node.name), line: getSpanLine(node.name?.[0]), raw: node }
+    case 'CreateFunction':
+      return { kind: 'function', objectName: extractName(node.name), line: getSpanLine(node.name?.[0]), raw: node }
+    case 'CreateTrigger':
+      return { kind: 'trigger', objectName: extractName(node.name), line: getSpanLine(node.name?.[0]), raw: node }
+    default:
+      return null
+  }
+}
+
+/** Map columns using span info from the AST */
+function mapColumns(columns: any[]): SqlColumn[] {
+  return columns.map((col: any) => ({
+    name: col.name?.value ?? '',
+    dataType: normalizeDataType(col.data_type),
+    line: col.name?.span?.start?.line ?? 1,
+    raw: col,
+  }))
+}
+
+/**
+ * Normalize sqlparser-ts data type representations to lowercase strings.
+ */
+export function normalizeDataType(dt: any): string {
+  if (typeof dt === 'string') return dt.toLowerCase()
+  if (dt?.Varchar != null) {
+    const len = dt.Varchar?.IntegerLength?.length
+    return len != null ? `varchar(${len})` : 'varchar'
+  }
+  if (dt?.Custom) {
+    return dt.Custom[0]
+      ?.map((n: any) => n.Identifier?.value)
+      .filter(Boolean)
+      .join('.')
+      .toLowerCase()
+  }
+  if (dt?.Timestamp != null) {
+    return dt.Timestamp?.With === 'Tz' ? 'timestamptz' : 'timestamp'
+  }
+  // Fallback: use first key name lowercased
+  const keys = Object.keys(dt)
+  if (keys.length === 1) return keys[0].toLowerCase()
+  return JSON.stringify(dt)
+}

package/src/ast/types.ts

@@ -0,0 +1,28 @@
+import type { SqlTarget } from '../types.ts'
+
+export interface SqlColumn {
+  name: string
+  dataType: string
+  /** 1-based line number from AST span */
+  line: number
+  raw: unknown
+}
+
+export interface SqlStatement {
+  kind: SqlTarget
+  objectName: string
+  /** 1-based line number from AST span */
+  line: number
+  columns?: SqlColumn[]
+  raw: unknown
+}
+
+/** A parsed COMMENT ON statement from the source SQL */
+export interface SqlCommentOn {
+  /** e.g. 'TABLE "users"' or 'COLUMN "users"."email"' */
+  targetKey: string
+  /** The comment text */
+  content: string
+  /** 1-based line number */
+  line: number
+}

package/src/blocks.ts

@@ -0,0 +1,242 @@
+/**
+ * Shared block-building logic used by both validator and compiler.
+ * Groups consecutive tag comments into blocks and resolves their SQL target
+ * using span-based line matching from the AST.
+ */
+
+import type { SqlColumn, SqlStatement } from './ast/types.ts'
+import type { ParsedTag } from './parser.ts'
+import type { SqlTarget } from './types.ts'
+
+// ── AST info ────────────────────────────────────────────────────────
+
+export interface AstInfo {
+  target: SqlTarget
+  columnName?: string
+  columnType?: string
+  objectName?: string
+  astNode?: unknown
+}
+
+export interface TagBlock {
+  tags: ParsedTag[]
+  sqlLines: string[]
+  ast: AstInfo
+}
+
+// Re-export for consumers that used to import from validator
+export function detectTarget(sqlLines: string[]): SqlTarget {
+  return detectTargetFallback(sqlLines)
+}
+
+export function detectTargetFallback(sqlLines: string[]): SqlTarget {
+  if (sqlLines.length === 0) return 'unknown'
+  const first = sqlLines[0]
+  const TARGET_PATTERNS: [RegExp, SqlTarget][] = [
+    [/^\s*CREATE\s+(OR\s+REPLACE\s+)?TABLE\b/i, 'table'],
+    [/^\s*CREATE\s+(OR\s+REPLACE\s+)?FUNCTION\b/i, 'function'],
+    [/^\s*CREATE\s+(OR\s+REPLACE\s+)?VIEW\b/i, 'view'],
+    [/^\s*CREATE\s+(UNIQUE\s+)?INDEX\b/i, 'index'],
+    [/^\s*CREATE\s+TYPE\b/i, 'type'],
+    [/^\s*CREATE\s+(OR\s+REPLACE\s+)?TRIGGER\b/i, 'trigger'],
+  ]
+  for (const [re, target] of TARGET_PATTERNS) {
+    if (re.test(first)) return target
+  }
+  if (/^\s+\w+\s+\w+/.test(first) && !first.trim().startsWith('CREATE')) {
+    return 'column'
+  }
+  return 'unknown'
+}
+
+// ── Block building ──────────────────────────────────────────────────
+
+/** Check if a tag is an inline comment (SQL code before the -- on the same line) */
+function isInlineTag(tag: ParsedTag, docLines: string[]): boolean {
+  const line = docLines[tag.line]
+  if (!line) return false
+  const commentIdx = line.indexOf('--')
+  if (commentIdx < 0) return false
+  // If there's non-whitespace before the --, it's inline
+  return line.substring(0, commentIdx).trim().length > 0
+}
+
+export function buildBlocks(
+  tags: ParsedTag[],
+  _docText: string,
+  docLines: string[],
+  stmts: SqlStatement[],
+): TagBlock[] {
+  if (tags.length === 0) return []
+
+  const blocks: TagBlock[] = []
+  let currentTags: ParsedTag[] = []
+  let lastTagLine = -2
+
+  for (const tag of tags) {
+    // Inline tags (comment after SQL on the same line) are always their own block
+    if (isInlineTag(tag, docLines)) {
+      if (currentTags.length > 0) {
+        blocks.push(finalizeBlock(currentTags, docLines, stmts))
+        currentTags = []
+      }
+      blocks.push(finalizeBlock([tag], docLines, stmts, true))
+      lastTagLine = tag.line
+      continue
+    }
+
+    if (currentTags.length > 0 && tag.line !== lastTagLine && tag.line !== lastTagLine + 1) {
+      blocks.push(finalizeBlock(currentTags, docLines, stmts))
+      currentTags = []
+    }
+    if (currentTags.length > 0 && tag.line === lastTagLine) {
+      currentTags.push(tag)
+    } else {
+      if (currentTags.length > 0 && tag.line !== lastTagLine + 1) {
+        blocks.push(finalizeBlock(currentTags, docLines, stmts))
+        currentTags = []
+      }
+      currentTags.push(tag)
+    }
+    lastTagLine = tag.line
+  }
+
+  if (currentTags.length > 0) {
+    blocks.push(finalizeBlock(currentTags, docLines, stmts))
+  }
+
+  return blocks
+}
+
+function finalizeBlock(tags: ParsedTag[], docLines: string[], stmts: SqlStatement[], inline = false): TagBlock {
+  const lastTagLine = tags[tags.length - 1].line
+  const firstTagLine = tags[0].line
+
+  // Collect SQL lines
+  const sqlLines: string[] = []
+  if (inline) {
+    // For inline tags, the SQL is the non-comment portion of the same line
+    const line = docLines[lastTagLine]
+    const commentIdx = line.indexOf('--')
+    if (commentIdx > 0) {
+      sqlLines.push(line.substring(0, commentIdx).trim())
+    }
+  }
+
+  // Also collect SQL lines after the tag block (for non-inline, or as fallback)
+  if (!inline) {
+    for (let i = lastTagLine + 1; i < docLines.length; i++) {
+      const line = docLines[i].trim()
+      if (!line) continue
+      if (line.startsWith('--')) continue
+      sqlLines.push(docLines[i])
+      if (line.endsWith(';') || line.endsWith(',') || line.endsWith(');') || line === ')') break
+      if (/\$\$\s*$/.test(line)) {
+        for (let j = i + 1; j < docLines.length; j++) {
+          sqlLines.push(docLines[j])
+          if (/\$\$/.test(docLines[j]) && j !== i) break
+        }
+        break
+      }
+    }
+  }
+
+  // Tags use 0-based lines, AST uses 1-based lines
+  // A tag on line N (0-based) associates with the AST node on line N+1 or N+2 (1-based)
+  const tagLine1Based = firstTagLine + 1
+
+  const ast = resolveAstByLine(tagLine1Based, lastTagLine + 1, stmts, sqlLines)
+  return { tags, sqlLines, ast }
+}
+
+/**
+ * Match a tag block to an AST node using line numbers.
+ *
+ * Algorithm:
+ * 1. If there's a column/statement on the same line as the tag (inline), use it
+ * 2. Otherwise scan forward from the tag line:
+ *    - Hit a column → related to that column
+ *    - Hit a CREATE statement → related to that statement
+ *    - Hit end-of-table (no more columns, past last column) → related to the table
+ */
+function resolveAstByLine(
+  _firstTagLine: number, // 1-based
+  lastTagLine: number, // 1-based
+  stmts: SqlStatement[],
+  sqlLines: string[],
+): AstInfo {
+  if (stmts.length === 0) {
+    return { target: detectTargetFallback(sqlLines) }
+  }
+
+  // Build a flat list of all AST nodes (statements + columns) sorted by line
+  type AstNode = { type: 'stmt'; stmt: SqlStatement } | { type: 'col'; col: SqlColumn; parentStmt: SqlStatement }
+
+  const nodes: { line: number; node: AstNode }[] = []
+  for (const stmt of stmts) {
+    nodes.push({ line: stmt.line, node: { type: 'stmt', stmt } })
+    if (stmt.columns) {
+      for (const col of stmt.columns) {
+        nodes.push({ line: col.line, node: { type: 'col', col, parentStmt: stmt } })
+      }
+    }
+  }
+  nodes.sort((a, b) => a.line - b.line)
+
+  // 1. Check for inline: a node on the same line as the tag, before it in text
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    if (nodes[i].line === lastTagLine) {
+      return astInfoFromNode(nodes[i].node)
+    }
+    if (nodes[i].line < lastTagLine) break
+  }
+
+  // 2. Scan forward from the tag line — find the first node after the tag
+  for (const entry of nodes) {
+    if (entry.line > lastTagLine) {
+      return astInfoFromNode(entry.node)
+    }
+  }
+
+  // 3. Tag is after all nodes — find the enclosing table (if any)
+  // Walk backwards to find the last table statement
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const n = nodes[i].node
+    if (n.type === 'stmt' && n.stmt.kind === 'table') {
+      return {
+        target: 'table',
+        objectName: n.stmt.objectName,
+        astNode: n.stmt.raw,
+      }
+    }
+    if (n.type === 'col') {
+      // We're after the last column of this table — table-level
+      return {
+        target: 'table',
+        objectName: n.parentStmt.objectName,
+        astNode: n.parentStmt.raw,
+      }
+    }
+  }
+
+  return { target: detectTargetFallback(sqlLines) }
+}
+
+function astInfoFromNode(
+  node: { type: 'stmt'; stmt: SqlStatement } | { type: 'col'; col: SqlColumn; parentStmt: SqlStatement },
+): AstInfo {
+  if (node.type === 'col') {
+    return {
+      target: 'column',
+      columnName: node.col.name,
+      columnType: node.col.dataType,
+      objectName: node.parentStmt.objectName,
+      astNode: node.parentStmt.raw,
+    }
+  }
+  return {
+    target: node.stmt.kind,
+    objectName: node.stmt.objectName,
+    astNode: node.stmt.raw,
+  }
+}