@sqldoc/core 0.0.1

package/src/loader.ts

@@ -0,0 +1,102 @@
+/**
+ * Resolves @import paths and loads TagNamespace definitions.
+ * Uses tsx to handle TypeScript files without pre-compilation.
+ */
+
+import * as path from 'node:path'
+import { tsImport } from './ts-import.ts'
+import type { TagNamespace } from './types.ts'
+import { findSqldocDir, unwrapDefault } from './utils.ts'
+
+/** Pluggable logger — extension sets this to OutputChannel, CLI can set to console */
+let log: (msg: string) => void = () => {}
+export function setImportLogger(logger: (msg: string) => void) {
+  log = logger
+}
+
+export interface LoadResult {
+  namespaces: Map<string, TagNamespace>
+  errors: ImportError[]
+}
+
+export interface ImportError {
+  importPath: string
+  message: string
+}
+
+/**
+ * Load all imported tag namespaces for a SQL file.
+ *
+ * Resolution order:
+ * - Relative paths (./foo.ts): resolved from the SQL file's directory
+ * - Package names (@sqldoc/ns-audit): resolved from .sqldoc/node_modules/
+ */
+export async function loadImports(importPaths: string[], sqlFilePath: string | undefined): Promise<LoadResult> {
+  const namespaces = new Map<string, TagNamespace>()
+  const errors: ImportError[] = []
+
+  if (!sqlFilePath) {
+    errors.push({ importPath: '*', message: 'Cannot resolve imports for unsaved files' })
+    return { namespaces, errors }
+  }
+
+  const sqlDir = path.dirname(sqlFilePath)
+  log(`loadImports: sqlDir=${sqlDir}, paths=[${importPaths.join(', ')}]`)
+
+  // Find .sqldoc/ for package resolution
+  const sqldocDir = findSqldocDir(sqlDir)
+  log(`loadImports: sqldocDir=${sqldocDir ?? 'null'}`)
+
+  for (const importPath of importPaths) {
+    try {
+      let resolved: string
+      let resolveDir: string
+
+      if (importPath.startsWith('.')) {
+        // Relative path — resolve from the SQL file's directory
+        resolved = path.resolve(sqlDir, importPath)
+        resolveDir = sqlDir
+      } else if (sqldocDir) {
+        // Package name — resolve from .sqldoc/node_modules/
+        resolved = importPath
+        resolveDir = path.join(sqldocDir, 'node_modules')
+      } else if (process.env.SQLDOC_RESOLVE_FROM_LOCAL_PACKAGE === 'true') {
+        // Explicit fallback — resolve from the SQL file's directory (monorepo/development)
+        resolved = importPath
+        resolveDir = sqlDir
+      } else {
+        throw new Error(
+          `Cannot resolve '${importPath}': no .sqldoc/node_modules/ found. Run 'sqldoc init' first, or set SQLDOC_RESOLVE_FROM_LOCAL_PACKAGE=true for monorepo development.`,
+        )
+      }
+
+      log(`loadImports: importing '${importPath}' resolved='${resolved}' resolveDir='${resolveDir}'`)
+      let mod = (await tsImport(resolved, resolveDir)) as any
+      log(`loadImports: loaded '${importPath}' ok`)
+      // Unwrap ESM default exports (CJS compat can double-wrap: { default: { default: plugin } })
+      mod = unwrapDefault(mod, (m: any) => !!m.name)
+      const ns = mod as TagNamespace | undefined
+
+      if (!ns || !ns.name || !ns.tags) {
+        errors.push({
+          importPath,
+          message: `Module does not export a valid TagNamespace (expected { name, tags })`,
+        })
+        continue
+      }
+
+      namespaces.set(ns.name, ns)
+    } catch (err: any) {
+      log(`loadImports: FAILED '${importPath}': ${err?.message ?? String(err)}`)
+      if (err?.message?.includes('no .sqldoc/node_modules/')) {
+        throw err
+      }
+      errors.push({
+        importPath,
+        message: err?.message ?? String(err),
+      })
+    }
+  }
+
+  return { namespaces, errors }
+}

package/src/parser.ts

@@ -0,0 +1,202 @@
+/**
+ * Parses SQL files for @import statements and @tags in comments.
+ */
+
+export interface ImportStatement {
+  path: string
+  line: number
+  startCol: number
+  endCol: number
+}
+
+export interface ParsedTag {
+  namespace: string
+  tag: string | null // null when namespace used as standalone (e.g. @searchable)
+  rawArgs: string | null // raw string inside parens, null if no parens
+  line: number
+  startCol: number
+  endCol: number
+  // sub-ranges for precise squiggles
+  namespaceStart: number
+  namespaceEnd: number
+  tagStart: number
+  tagEnd: number
+  argsStart: number
+  argsEnd: number
+}
+
+export interface ParseResult {
+  imports: ImportStatement[]
+  tags: ParsedTag[]
+}
+
+const IMPORT_RE = /--\s*@import\s+(['"])([^'"]+)\1/g
+const TAG_RE = /@(\w+)(?:\.(\w+))?(?:\(([^()]*(?:\([^()]*\)[^()]*)*)\))?/g
+
+export function parse(text: string): ParseResult {
+  const imports: ImportStatement[] = []
+  const tags: ParsedTag[] = []
+  const lines = text.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Parse imports
+    IMPORT_RE.lastIndex = 0
+    let m: RegExpExecArray | null
+    let isImportLine = false
+    while ((m = IMPORT_RE.exec(line)) !== null) {
+      imports.push({
+        path: m[2],
+        line: i,
+        startCol: m.index,
+        endCol: m.index + m[0].length,
+      })
+      isImportLine = true
+    }
+    if (isImportLine) continue
+
+    // Find the comment portion of the line (if any)
+    // Supports both full comment lines (-- ...) and inline comments (SQL -- ...)
+    const commentIdx = line.indexOf('--')
+    if (commentIdx < 0) continue
+
+    TAG_RE.lastIndex = 0
+    while ((m = TAG_RE.exec(line)) !== null) {
+      const fullMatch = m[0]
+      const namespace = m[1]
+      const tag = m[2] || null
+      const rawArgs = m[3] !== undefined ? m[3] : null
+
+      // Skip @import — handled separately
+      if (namespace === 'import') continue
+
+      const nsStart = m.index + 1 // after @
+      const nsEnd = nsStart + namespace.length
+
+      let tStart = nsEnd
+      let tEnd = nsEnd
+      if (tag) {
+        tStart = nsEnd + 1 // after .
+        tEnd = tStart + tag.length
+      }
+
+      let aStart = 0
+      let aEnd = 0
+      if (rawArgs !== null) {
+        aStart = m.index + fullMatch.indexOf('(') + 1
+        aEnd = aStart + rawArgs.length
+      }
+
+      tags.push({
+        namespace,
+        tag,
+        rawArgs,
+        line: i,
+        startCol: m.index,
+        endCol: m.index + fullMatch.length,
+        namespaceStart: nsStart,
+        namespaceEnd: nsEnd,
+        tagStart: tStart,
+        tagEnd: tEnd,
+        argsStart: aStart,
+        argsEnd: aEnd,
+      })
+    }
+  }
+
+  return { imports, tags }
+}
+
+// ── Arg value parser ─────────────────────────────────────────────────
+
+export type ArgValue = string | number | boolean | ArgValue[]
+
+export interface NamedArgValues {
+  type: 'named'
+  values: Record<string, ArgValue>
+}
+
+export interface PositionalArgValues {
+  type: 'positional'
+  values: ArgValue[]
+}
+
+export type ParsedArgs = NamedArgValues | PositionalArgValues
+
+/**
+ * Parse the raw arg string from inside parens.
+ * Detects whether args are named (key: value) or positional.
+ */
+export function parseArgs(raw: string): ParsedArgs {
+  const trimmed = raw.trim()
+  if (!trimmed) return { type: 'positional', values: [] }
+
+  // Check if it looks like named args (contains "key:")
+  if (/^\w+\s*:/.test(trimmed)) {
+    return { type: 'named', values: parseNamedArgs(trimmed) }
+  }
+
+  // Positional
+  return { type: 'positional', values: parsePositionalArgs(trimmed) }
+}
+
+function parseNamedArgs(raw: string): Record<string, ArgValue> {
+  const result: Record<string, ArgValue> = {}
+  // Match key: value pairs, where value can be a string, array, or bare word
+  const NAMED_RE = /(\w+)\s*:\s*(\[(?:[^\]]*)\]|'[^']*'|"[^"]*"|\w+)/g
+  let m: RegExpExecArray | null
+  while ((m = NAMED_RE.exec(raw)) !== null) {
+    result[m[1]] = parseValue(m[2])
+  }
+  return result
+}
+
+function parsePositionalArgs(raw: string): ArgValue[] {
+  // Split by comma, respecting brackets and quoted strings
+  const parts: string[] = []
+  let depth = 0
+  let inSingleQuote = false
+  let inDoubleQuote = false
+  let current = ''
+  for (const ch of raw) {
+    if (!inSingleQuote && !inDoubleQuote) {
+      if (ch === '[') depth++
+      else if (ch === ']') depth--
+      else if (ch === "'") inSingleQuote = true
+      else if (ch === '"') inDoubleQuote = true
+      else if (ch === ',' && depth === 0) {
+        parts.push(current.trim())
+        current = ''
+        continue
+      }
+    } else if (inSingleQuote && ch === "'") {
+      inSingleQuote = false
+    } else if (inDoubleQuote && ch === '"') {
+      inDoubleQuote = false
+    }
+    current += ch
+  }
+  if (current.trim()) parts.push(current.trim())
+  return parts.map((s) => parseValue(s))
+}
+
+function parseValue(raw: string): ArgValue {
+  // Array
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1).trim()
+    if (!inner) return []
+    return inner.split(',').map((s) => parseValue(s.trim()))
+  }
+  // Quoted string
+  if ((raw.startsWith("'") && raw.endsWith("'")) || (raw.startsWith('"') && raw.endsWith('"'))) {
+    return raw.slice(1, -1)
+  }
+  // Number
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  // Boolean
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  // Bare word (treated as string, e.g. enum value)
+  return raw
+}

package/src/ts-import.ts

@@ -0,0 +1,70 @@
+/**
+ * Load a TypeScript or JavaScript module at runtime.
+ *
+ * - Bun (compiled binary or bun dev): native import() for .ts files.
+ * - Node.js: bundle-require (esbuild under the hood) for .ts files.
+ * - Plain JS/npm packages: native import() on both runtimes.
+ *
+ * In the VSCode extension, esbuild is aliased to esbuild-wasm.
+ *
+ * IMPORTANT: bundle-require is dynamically imported so it is NOT loaded
+ * when running in Bun. This prevents the compiled binary from needing esbuild.
+ */
+
+import { createRequire } from 'node:module'
+import * as path from 'node:path'
+
+const TS_EXTENSIONS = new Set(['.ts', '.mts', '.cts'])
+
+/**
+ * Detect if the runtime can natively import .ts files.
+ * - Bun: always
+ * - Node with tsx: tsx registers a loader that handles .ts
+ * - Node 23.6+: --experimental-strip-types (unflagged)
+ */
+function canNativelyImportTs(): boolean {
+  // Bun
+  if (typeof process.versions?.bun === 'string') return true
+  // tsx registers itself via --require or --loader
+  if (process.execArgv?.some((a) => a.includes('tsx'))) return true
+  // Node with amaro/strip-types flag
+  if (process.execArgv?.some((a) => a.includes('strip-types'))) return true
+  // Node 22.6+ supports --experimental-strip-types, 23.6+ unflagged
+  // Node 22.21+ runs .ts natively without any flags
+  const nodeVersion = process.versions?.node
+  if (nodeVersion) {
+    const [major, minor] = nodeVersion.split('.').map(Number)
+    if (major > 22 || (major === 22 && minor >= 21)) return true
+  }
+  return false
+}
+
+/**
+ * Import a TypeScript or JavaScript module by specifier.
+ * Handles npm packages (via require.resolve), relative paths, and absolute paths.
+ */
+export async function tsImport(specifier: string, fromDir?: string): Promise<any> {
+  const abs = resolveSpecifier(specifier, fromDir)
+
+  if (TS_EXTENSIONS.has(path.extname(abs))) {
+    if (canNativelyImportTs()) {
+      // Bun runs TypeScript natively -- no bundler needed
+      return import(abs)
+    }
+    // Node: use bundle-require (esbuild) to transpile .ts at runtime
+    const { bundleRequire } = await import('bundle-require')
+    return (await bundleRequire({ filepath: abs })).mod
+  }
+
+  return import(abs)
+}
+
+function resolveSpecifier(specifier: string, fromDir?: string): string {
+  if (path.isAbsolute(specifier)) return specifier
+  if (specifier.startsWith('.')) return path.resolve(specifier)
+
+  // npm package — resolve from caller's directory (or cwd as fallback)
+  const base = fromDir || process.cwd()
+  const req = createRequire(path.join(base, 'noop.js'))
+  return req.resolve(specifier)
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+// ── Arg type primitives ──────────────────────────────────────────────
+
+export type StringType = { type: 'string'; description?: string }
+export type NumberType = { type: 'number'; description?: string }
+export type BooleanType = { type: 'boolean'; description?: string }
+export type EnumType<V extends string = string> = { type: 'enum'; values: readonly V[]; description?: string }
+export type ArgType = StringType | NumberType | BooleanType | EnumType | ArrayType<any>
+export type ArrayType<U extends ArgType> = { type: 'array'; items: U; description?: string }
+
+// ── Type inference from schema definitions ──────────────────────────
+
+/** Infer the TypeScript type from a single ArgType schema field */
+export type InferArgType<T extends ArgType> = T extends { type: 'string' }
+  ? string
+  : T extends { type: 'number' }
+    ? number
+    : T extends { type: 'boolean' }
+      ? boolean
+      : T extends { type: 'enum'; values: readonly (infer V)[] }
+        ? V
+        : T extends { type: 'array'; items: infer U extends ArgType }
+          ? InferArgType<U>[]
+          : never
+
+/** Infer a full config/args object type from a schema definition used with `as const` */
+export type InferSchema<T extends Record<string, ArgType>> = {
+  [K in keyof T]?: InferArgType<T[K]>
+}
+
+// ── Tag arg shapes ───────────────────────────────────────────────────
+
+/** Tag takes no arguments: `@audit.tracked` */
+export interface NoArgs {
+  args?: undefined
+}
+
+/** Tag takes positional (unnamed) arguments: `@gql.order(asc)` */
+export interface PositionalArgs {
+  args: ArgType[]
+}
+
+/** Tag takes named properties: `@audit.log(on: [...], destination: '...')` */
+export interface NamedArgs {
+  args: Record<string, ArgType & { required?: boolean }>
+}
+
+export type TagArgs = NoArgs | PositionalArgs | NamedArgs
+
+// ── Tag definition ───────────────────────────────────────────────────
+
+export type SqlTarget = 'table' | 'column' | 'function' | 'view' | 'index' | 'type' | 'trigger' | 'unknown'
+
+export type ValidationContext = {
+  /** What kind of SQL construct this tag is attached to */
+  target: SqlTarget
+  /** The raw SQL lines this tag is attached to (the non-comment lines following the tag comments) */
+  lines: string[]
+  /** Other tags on the same target (siblings in the same comment block) */
+  siblingTags: { namespace: string; tag: string | null; rawArgs: string | null }[]
+  /** All tags across the entire file, grouped by SQL object */
+  fileTags: Array<{
+    objectName: string
+    target: SqlTarget
+    tags: { namespace: string; tag: string | null; rawArgs: string | null }[]
+  }>
+  /** Parsed argument values */
+  argValues: Record<string, unknown> | unknown[]
+  /** Column name (when target is 'column') */
+  columnName?: string
+  /** Column type (when target is 'column'), e.g. "text", "bigserial" */
+  columnType?: string
+  /** Table/view/type/function name */
+  objectName?: string
+  /** The raw AST node from the SQL parser, for advanced validation */
+  astNode?: unknown
+}
+
+export type TagDef = TagArgs & {
+  description?: string
+  /** Which SQL targets this tag can be placed on. If omitted, allowed on any target. */
+  targets?: SqlTarget[]
+  validate?: (
+    ctx: ValidationContext,
+  ) => string | { message: string; severity?: 'error' | 'warning' | 'info' } | undefined
+}
+
+// ── Namespace definition ─────────────────────────────────────────────
+
+/**
+ * A namespace is a collection of tags.
+ * Use `$self` for when the namespace name is used as a standalone tag
+ * (e.g. `@searchable` where `searchable` is also a namespace for `@searchable.fulltext`).
+ */
+export type NamespaceDef = {
+  $self?: TagDef
+} & {
+  [tagName: string]: TagDef
+}
+
+// ── Top-level export shape ───────────────────────────────────────────
+
+/**
+ * Each tag definition file exports a single namespace.
+ * The SQL file imports it:
+ *   -- @import './audit.ts'
+ *   -- @import '@elliots/sqldoc/gql'
+ */
+export type TagNamespace = {
+  name: string
+  tags: NamespaceDef
+}

package/src/utils.ts

@@ -0,0 +1,31 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/**
+ * Walk up from startDir looking for a .sqldoc/ directory.
+ * Returns the absolute path to .sqldoc/ or null if not found.
+ */
+export function findSqldocDir(startDir: string = process.cwd()): string | null {
+  let current = path.resolve(startDir)
+  while (true) {
+    const candidate = path.join(current, '.sqldoc')
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+/**
+ * Unwrap nested ESM default exports.
+ *
+ * CJS interop can double-wrap: `{ default: { default: actualExport } }`.
+ * Keeps unwrapping `mod.default` until `isTarget(mod)` returns true
+ * (meaning we've reached the real export) or there's nothing left to unwrap.
+ */
+export function unwrapDefault<T>(mod: any, isTarget: (m: any) => boolean): T {
+  while (mod && typeof mod === 'object' && 'default' in mod && !isTarget(mod)) {
+    mod = mod.default
+  }
+  return mod as T
+}