@sqldoc/core 0.0.1

package/src/compiler/config.ts

@@ -0,0 +1,102 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { tsImport } from '../ts-import.ts'
+import { unwrapDefault } from '../utils.ts'
+import type { ProjectConfig, ResolvedConfig, SqldocConfig } from './types.ts'
+
+const CONFIG_FILENAMES = ['sqldoc.config.ts', 'sqldoc.config.js', 'sqldoc.config.mjs']
+
+export interface ConfigResult {
+  config: SqldocConfig
+  configPath: string | null
+}
+
+/**
+ * Helper for creating typed sqldoc config.
+ * Used in sqldoc.config.ts: export default defineConfig({ ... })
+ * Accepts a single ProjectConfig or an array for multi-project.
+ */
+export function defineConfig(config: SqldocConfig): SqldocConfig {
+  return config
+}
+
+/**
+ * Resolve a single project from the config.
+ *
+ * - If config is a single ProjectConfig, returns it directly
+ *   (projectName must be undefined or match config.name)
+ * - If config is an array, requires projectName to select one
+ * - Throws with available project names on mismatch
+ */
+export function resolveProject(config: SqldocConfig, projectName?: string): ResolvedConfig {
+  // Single project config
+  if (!Array.isArray(config)) {
+    if (projectName && config.name && config.name !== projectName) {
+      throw new Error(`Project "${projectName}" not found. Available: ${config.name}`)
+    }
+    return config
+  }
+
+  // Multi-project config
+  const names = config.map((p) => p.name).filter(Boolean)
+
+  if (projectName) {
+    const found = config.find((p) => p.name === projectName)
+    if (!found) {
+      throw new Error(`Project "${projectName}" not found. Available: ${names.join(', ')}`)
+    }
+    return found
+  }
+
+  // No --project specified
+  if (config.length === 1) {
+    return config[0]
+  }
+
+  throw new Error(`Multiple projects configured. Use --project <name> or --all.\nAvailable: ${names.join(', ')}`)
+}
+
+/**
+ * Resolve all projects from the config.
+ * Returns an array regardless of single/multi config.
+ */
+export function resolveAllProjects(config: SqldocConfig): ProjectConfig[] {
+  return Array.isArray(config) ? config : [config]
+}
+
+/**
+ * Load a config file by exact path using tsx.
+ */
+async function loadConfigFile(configPath: string): Promise<ConfigResult> {
+  const abs = path.resolve(configPath)
+  let mod = (await tsImport(abs)) as any
+  // Unwrap ESM default exports (CJS compat can double-wrap)
+  // Detect both single config (has namespaces/dialect/schema) and arrays
+  mod = unwrapDefault(mod, (m: any) => !!m.namespaces || !!m.dialect || !!m.schema || Array.isArray(m))
+  const config: SqldocConfig = mod ?? { dialect: 'postgres' }
+  return { config, configPath: abs }
+}
+
+/**
+ * Load sqldoc config.
+ * If configFile is provided, loads that exact file.
+ * Otherwise searches projectRoot for sqldoc.config.{ts,js,mjs}.
+ * Returns default config if no config file found.
+ */
+export async function loadConfig(projectRoot: string, configFile?: string): Promise<ConfigResult> {
+  if (configFile) {
+    const resolved = path.resolve(configFile)
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Config file not found: ${resolved}`)
+    }
+    return loadConfigFile(resolved)
+  }
+
+  for (const filename of CONFIG_FILENAMES) {
+    const configPath = path.resolve(projectRoot, filename)
+    if (!fs.existsSync(configPath)) continue
+    return loadConfigFile(configPath)
+  }
+
+  return { config: { dialect: 'postgres' } as ProjectConfig, configPath: null }
+}

package/src/compiler/index.ts

@@ -0,0 +1,29 @@
+export type { CompileOptions } from './compile.ts'
+export { compile } from './compile.ts'
+export type { ConfigResult } from './config.ts'
+export { defineConfig, loadConfig, resolveAllProjects, resolveProject } from './config.ts'
+export type {
+  CodeOutput,
+  CompilerContext,
+  CompilerOutput,
+  DocsMeta,
+  LintConfig,
+  LintContext,
+  LintDiagnostic,
+  LintResult,
+  LintRule,
+  LintSeverity,
+  MigrationFormat,
+  MigrationNaming,
+  NamespaceConfig,
+  NamespacePlugin,
+  ProjectCompilerContext,
+  ProjectConfig,
+  ProjectContext,
+  ProjectOutput,
+  ResolvedConfig,
+  SqldocConfig,
+  SqlOutput,
+  TagContext,
+  TagOutput,
+} from './types.ts'

package/src/compiler/types.ts

@@ -0,0 +1,320 @@
+import type { SqlStatement } from '../ast/types.ts'
+import type { SqlTarget, TagNamespace } from '../types.ts'
+
+// ── Project config ──────────────────────────────────────────────────
+
+/** Migration file format — determines how up/down scripts are read and written */
+export type MigrationFormat = 'atlas' | 'golang-migrate' | 'goose' | 'flyway' | 'dbmate' | 'plain'
+
+/** File naming strategy for generated migration files */
+export type MigrationNaming = 'timestamp' | 'sequential' | { provider: 'claude-code' }
+
+/** A single project configuration */
+export interface ProjectConfig {
+  /** Project name (required for multi-project, optional for single) */
+  name?: string
+  /** Schema source: file or directory of SQL files with sqldoc tags */
+  schema?: string
+  /** SQL dialect — mandatory */
+  dialect: 'postgres' | 'mysql' | 'sqlite'
+  /** Dev database URL. Default: pglite */
+  devUrl?: string
+  /** Migration settings */
+  migrations?: {
+    /** Directory containing migration files */
+    dir: string
+    /** Migration file format. Default: 'plain' */
+    format?: MigrationFormat
+    /** File naming strategy. Default: 'timestamp' */
+    naming?: MigrationNaming
+  }
+  /** Namespace plugin configuration */
+  namespaces?: Record<string, unknown>
+  /** Lint configuration */
+  lint?: LintConfig
+
+  // ── Legacy fields (backward compat) ──
+  /** @deprecated Use `schema` instead. Glob patterns for SQL source files */
+  include?: string[]
+  /** Output directory for generated SQL */
+  sqlOutDir?: string
+  /** Output directory for generated code artifacts */
+  codeOutDir?: string
+}
+
+/** Config can be a single project or array of projects */
+export type SqldocConfig = ProjectConfig | ProjectConfig[]
+
+/**
+ * Resolved single-project config — always a single ProjectConfig.
+ * Used internally after resolving --project/--all flags.
+ */
+export type ResolvedConfig = ProjectConfig
+
+/** Generic constraint for per-namespace config */
+export type NamespaceConfig = Record<string, unknown>
+
+// ── Tag context ────────────────────────────────────────────────────
+
+/** Rich context passed to onTag for each tag occurrence */
+export interface TagContext {
+  /** The SQL object this tag is attached to */
+  target: SqlTarget
+  /** Name of the SQL object (table name, function name, etc.) */
+  objectName: string
+  /** Column name when target is 'column' */
+  columnName?: string
+  /** Column data type when target is 'column' */
+  columnType?: string
+  /** The parsed tag that triggered this handler */
+  tag: {
+    name: string | null
+    args: Record<string, unknown> | unknown[]
+  }
+  /** All tags from the same namespace on the same SQL object */
+  namespaceTags: Array<{
+    tag: string | null
+    args: Record<string, unknown> | unknown[]
+  }>
+  /** All tags from ALL namespaces on the same SQL object (sibling introspection) */
+  siblingTags: Array<{
+    namespace: string
+    tag: string | null
+    args: Record<string, unknown> | unknown[]
+  }>
+  /** All tags across the entire file, grouped by SQL object */
+  fileTags: Array<{
+    objectName: string
+    target: SqlTarget
+    tags: Array<{
+      namespace: string
+      tag: string | null
+      args: Record<string, unknown> | unknown[]
+    }>
+  }>
+  /** The full AST statement for the SQL object */
+  astNode: unknown
+  /** All parsed SQL statements in the file */
+  fileStatements: SqlStatement[]
+  /** This namespace's config from sqldoc.config.ts */
+  config: NamespaceConfig
+  /** The source SQL file path */
+  filePath: string
+  /** Atlas-parsed table schema for this object (Tier 2 only, undefined in Tier 1) */
+  atlasTable?: unknown
+  /** Atlas-parsed column info (Tier 2 only, when target is 'column') */
+  atlasColumn?: unknown
+  /** Full Atlas realm with all schemas, tables, views (Tier 2 only) */
+  atlasRealm?: unknown
+}
+
+/** @deprecated Use TagContext instead */
+export type CompilerContext = TagContext
+
+/** Context for afterCompile hook — receives ALL compiled file data */
+export interface ProjectContext {
+  /** All compiled file outputs */
+  outputs: CompilerOutput[]
+  /** The merged SQL from all files combined */
+  mergedSql: string
+  /** All tags across all files, grouped by file then by object */
+  allFileTags: Array<{
+    sourceFile: string
+    objects: Array<{
+      objectName: string
+      target: SqlTarget
+      tags: Array<{
+        namespace: string
+        tag: string | null
+        args: Record<string, unknown> | unknown[]
+      }>
+    }>
+  }>
+  /** Aggregated docs metadata from all plugins across all files */
+  docsMeta: DocsMeta[]
+  /** This namespace's config from sqldoc.config.ts */
+  config: NamespaceConfig
+  /** Project root directory */
+  projectRoot: string
+  /** Atlas-parsed schema realm (Tier 2, when available) */
+  atlasRealm?: unknown
+}
+
+/** @deprecated Use ProjectContext instead */
+export type ProjectCompilerContext = ProjectContext
+
+/** Output from an afterCompile hook */
+export interface ProjectOutput {
+  /** Files to write (path relative to project root + content) */
+  files: Array<{
+    filePath: string
+    content: string
+  }>
+}
+
+// ── Docs metadata ──────────────────────────────────────────────────
+
+/** Documentation metadata that plugins can return alongside SQL from onTag */
+export interface DocsMeta {
+  /** Extra relationships to show in ER diagrams (e.g. audit trail arrows) */
+  relationships?: Array<{
+    from: string
+    to: string
+    label: string
+    style?: 'dashed'
+  }>
+  /** Table-level annotations (e.g. "RLS enabled", "Audited") */
+  annotations?: Array<{
+    object: string
+    text: string
+  }>
+  /**
+   * Extra doc columns contributed by plugins.
+   * If ANY plugin adds a column with a given header, that column appears on ALL tables.
+   * Each entry targets a specific table+column with a cell value.
+   */
+  columns?: Array<{
+    /** Column header name (e.g. "Validation", "RLS", "Anonymization") */
+    header: string
+    /** Table this cell applies to */
+    object: string
+    /** DB column name this cell applies to (omit for table-level row) */
+    column?: string
+    /** Cell value text */
+    value: string
+  }>
+}
+
+/** Return type from onTag — SQL statements + optional docs metadata */
+export interface TagOutput {
+  sql?: SqlOutput[]
+  docs?: DocsMeta
+}
+
+// ── Compiler outputs ────────────────────────────────────────────────
+
+/** A single SQL statement produced by a namespace */
+export interface SqlOutput {
+  /** The SQL statement text (e.g., "ALTER TABLE users ENABLE ROW LEVEL SECURITY;") */
+  sql: string
+  /** Optional comment for clarity in output */
+  comment?: string
+  /** Source tag that produced this output (set by compiler, not by plugins) */
+  sourceTag?: string
+}
+
+/** A non-SQL file produced by a namespace */
+export interface CodeOutput {
+  /** Relative file path for the output (e.g., "types/users.ts") */
+  filePath: string
+  /** File content */
+  content: string
+}
+
+/** Combined output from compiling one file */
+export interface CompilerOutput {
+  /** Source SQL file path */
+  sourceFile: string
+  /** Complete SQL: original source with generated statements appended */
+  mergedSql: string
+  /** Individual SQL statements produced by namespaces (for inspection) */
+  sqlOutputs: SqlOutput[]
+  /** Code files to write */
+  codeOutputs: CodeOutput[]
+  /** Errors encountered during compilation */
+  errors: Array<{ namespace: string; message: string }>
+  /** Documentation metadata collected from all plugins */
+  docsMeta: DocsMeta[]
+  /** Per-file tag summary for project-level aggregation */
+  fileTags: Array<{
+    objectName: string
+    target: SqlTarget
+    tags: Array<{
+      namespace: string
+      tag: string | null
+      args: Record<string, unknown> | unknown[]
+    }>
+  }>
+}
+
+// ── Lint types ──────────────────────────────────────────────────────
+
+/** Severity levels for lint rules */
+export type LintSeverity = 'error' | 'warn' | 'off'
+
+/** A lint rule defined by a namespace plugin */
+export interface LintRule {
+  /** Full rule name: namespace.ruleName (e.g. "audit.require-audit") */
+  name: string
+  /** Human-readable description of what this rule checks */
+  description: string
+  /** Default severity when not overridden in config */
+  default: LintSeverity
+  /** Check function — receives the full lint context and returns diagnostics */
+  check: (ctx: LintContext) => LintDiagnostic[]
+}
+
+/** Context passed to lint rule check functions */
+export interface LintContext {
+  /** All compiled file outputs */
+  outputs: CompilerOutput[]
+  /** All loaded plugins, keyed by namespace name */
+  plugins: Map<string, NamespacePlugin>
+  /** Project config (resolved single project) */
+  config: ResolvedConfig
+}
+
+/** A single lint diagnostic produced by a rule */
+export interface LintDiagnostic {
+  /** The SQL object this diagnostic relates to (table name, etc.) */
+  objectName: string
+  /** Source file path */
+  sourceFile: string
+  /** Human-readable message */
+  message: string
+}
+
+/** A lint result after applying severity and ignore processing */
+export interface LintResult {
+  /** Rule that produced this result */
+  ruleName: string
+  /** Effective severity (after config override, 'skip' if @lint.ignore suppressed) */
+  severity: LintSeverity | 'skip'
+  /** The SQL object name */
+  objectName: string
+  /** Source file path */
+  sourceFile: string
+  /** Human-readable message */
+  message: string
+  /** Ignore reason (when severity is 'skip') */
+  ignoreReason?: string
+}
+
+/** Lint config section in sqldoc.config.ts */
+export interface LintConfig {
+  rules?: Record<string, LintSeverity>
+}
+
+// ── Namespace plugin contract ───────────────────────────────────────
+
+/** Stable type contract for namespace packages. Extends TagNamespace with compiler hooks. */
+export interface NamespacePlugin extends TagNamespace {
+  /** API version for forward compatibility. Must be 1 for v1. */
+  apiVersion: 1
+  /** JSON Schema or Zod-like descriptor for namespace config (optional). Reserved for future validation. */
+  configSchema?: unknown
+  /** Called for each tag occurrence — returns SQL statements and/or docs metadata */
+  onTag?: (ctx: TagContext) => SqlOutput[] | TagOutput | undefined
+  /** Generate non-SQL code artifacts for a tag occurrence */
+  generateCode?: (ctx: TagContext) => CodeOutput[] | undefined
+  /** Runs once after all per-file compilation completes — project-level aggregation */
+  afterCompile?: (ctx: ProjectContext) => Promise<ProjectOutput> | ProjectOutput
+  /** Lint rules defined by this plugin */
+  lintRules?: LintRule[]
+
+  // Deprecated aliases — will be removed in v2
+  /** @deprecated Use onTag instead */
+  generateSQL?: (ctx: TagContext) => SqlOutput[] | TagOutput | undefined
+  /** @deprecated Use afterCompile instead */
+  generateProject?: (ctx: ProjectContext) => Promise<ProjectOutput> | ProjectOutput
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// Types
+
+export type { SqlAstAdapter, SqlColumn, SqlCommentOn, SqlStatement } from './ast/index.ts'
+// AST Adapters
+export { SqlparserTsAdapter } from './ast/index.ts'
+// Blocks
+export { buildBlocks } from './blocks.ts'
+export type {
+  CodeOutput,
+  CompileOptions,
+  CompilerContext,
+  // CompilerContext is deprecated alias for TagContext
+  CompilerOutput,
+  ConfigResult,
+  DocsMeta,
+  LintConfig,
+  LintContext,
+  LintDiagnostic,
+  LintResult,
+  LintRule,
+  LintSeverity,
+  MigrationFormat,
+  MigrationNaming,
+  NamespaceConfig,
+  NamespacePlugin,
+  ProjectCompilerContext, // ProjectCompilerContext is deprecated alias
+  ProjectConfig,
+  ProjectContext,
+  ProjectOutput,
+  ResolvedConfig,
+  SqldocConfig,
+  SqlOutput,
+  TagContext,
+  TagOutput,
+} from './compiler/index.ts'
+// Compiler
+export { compile, defineConfig, loadConfig, resolveAllProjects, resolveProject } from './compiler/index.ts'
+// Lint engine
+export { lint } from './lint.ts'
+export type { ImportError, LoadResult } from './loader.ts'
+// Loader
+export { loadImports, setImportLogger } from './loader.ts'
+export type { ArgValue, ImportStatement, ParsedArgs, ParsedTag, ParseResult } from './parser.ts'
+// Parser
+export { parse, parseArgs } from './parser.ts'
+
+// TS import helper
+export { tsImport } from './ts-import.ts'
+export type {
+  ArgType,
+  ArrayType,
+  BooleanType,
+  EnumType,
+  InferArgType,
+  InferSchema,
+  NamedArgs,
+  NamespaceDef,
+  NoArgs,
+  NumberType,
+  PositionalArgs,
+  SqlTarget,
+  StringType,
+  TagArgs,
+  TagDef,
+  TagNamespace,
+  ValidationContext,
+} from './types.ts'
+// Shared utilities
+export { findSqldocDir, unwrapDefault } from './utils.ts'
+export type { AstInfo, Diagnostic } from './validator.ts'
+// Validator
+export { detectTarget, detectTargetFallback, validate } from './validator.ts'

package/src/lint.ts

@@ -0,0 +1,127 @@
+/**
+ * Lint engine — collects lint rules from all loaded plugins, runs them
+ * against compiled output, respects @lint.ignore tags, and applies
+ * severity overrides from config.
+ */
+
+import type { CompilerOutput, LintContext, LintResult, NamespacePlugin, ResolvedConfig } from './compiler/types.ts'
+
+/** Parsed @lint.ignore tag */
+interface LintIgnore {
+  /** Rule name to ignore (e.g. "audit.require-audit") */
+  ruleName: string
+  /** Mandatory reason for suppression */
+  reason: string
+  /** SQL object name this ignore applies to */
+  objectName: string
+  /** Source file */
+  sourceFile: string
+}
+
+/**
+ * Run all lint rules from loaded plugins against compiled outputs.
+ *
+ * Collects lintRules from every plugin, runs each rule's check function,
+ * applies severity overrides from config.lint.rules, and respects
+ * @lint.ignore tags found in file tags.
+ */
+export function lint(
+  outputs: CompilerOutput[],
+  plugins: Map<string, NamespacePlugin>,
+  config: ResolvedConfig,
+): LintResult[] {
+  const results: LintResult[] = []
+  const lintConfig = config.lint ?? {}
+  const ruleOverrides = lintConfig.rules ?? {}
+
+  // 1. Collect all lint rules from plugins
+  const allRules = collectRules(plugins)
+
+  // 2. Collect all @lint.ignore tags from outputs
+  const ignores = collectIgnores(outputs)
+
+  // 3. Build lint context
+  const ctx: LintContext = { outputs, plugins, config }
+
+  // 4. Run each rule
+  for (const rule of allRules) {
+    // Determine effective severity
+    const effectiveSeverity = ruleOverrides[rule.name] ?? rule.default
+    if (effectiveSeverity === 'off') continue
+
+    // Run the check
+    const diagnostics = rule.check(ctx)
+
+    for (const diag of diagnostics) {
+      // Check if this diagnostic is suppressed by @lint.ignore
+      const ignore = ignores.find(
+        (ig) => ig.ruleName === rule.name && ig.objectName === diag.objectName && ig.sourceFile === diag.sourceFile,
+      )
+
+      if (ignore) {
+        results.push({
+          ruleName: rule.name,
+          severity: 'skip',
+          objectName: diag.objectName,
+          sourceFile: diag.sourceFile,
+          message: diag.message,
+          ignoreReason: ignore.reason,
+        })
+      } else {
+        results.push({
+          ruleName: rule.name,
+          severity: effectiveSeverity,
+          objectName: diag.objectName,
+          sourceFile: diag.sourceFile,
+          message: diag.message,
+        })
+      }
+    }
+  }
+
+  return results
+}
+
+/** Collect all lint rules from all plugins */
+function collectRules(plugins: Map<string, NamespacePlugin>) {
+  const rules = []
+  for (const plugin of plugins.values()) {
+    if (plugin.lintRules) {
+      rules.push(...plugin.lintRules)
+    }
+  }
+  return rules
+}
+
+/** Collect @lint.ignore tags from compiled outputs' fileTags */
+function collectIgnores(outputs: CompilerOutput[]): LintIgnore[] {
+  const ignores: LintIgnore[] = []
+
+  for (const output of outputs) {
+    for (const obj of output.fileTags) {
+      for (const tag of obj.tags) {
+        if (tag.namespace === 'lint' && tag.tag === 'ignore') {
+          const args = tag.args
+          let ruleName: string | undefined
+          let reason: string | undefined
+
+          if (Array.isArray(args)) {
+            ruleName = args[0] as string | undefined
+            reason = args[1] as string | undefined
+          }
+
+          if (ruleName && reason) {
+            ignores.push({
+              ruleName,
+              reason,
+              objectName: obj.objectName,
+              sourceFile: output.sourceFile,
+            })
+          }
+        }
+      }
+    }
+  }
+
+  return ignores
+}