dbml-metaquery 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Types for the DBML Path Finder.
+ */
+export interface PathStep {
+    from: {
+        table: string;
+        column: string;
+    };
+    to: {
+        table: string;
+        column: string;
+    };
+}
+export interface Relationship {
+    childTable: string;
+    childColumn: string;
+    parentTable: string;
+    parentColumn: string;
+}
+export interface TableInfo {
+    name: string;
+    note?: string;
+    columns: ColumnInfo[];
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    note?: string;
+    fk?: {
+        table: string;
+        column: string;
+    };
+}
+export interface GroupInfo {
+    name: string;
+    tables: string[];
+}
+export interface ReferencingTable {
+    table: string;
+    column: string;
+    myColumn: string;
+}
+export interface Neighbors {
+    parents: {
+        table: string;
+        via: string;
+    }[];
+    children: {
+        table: string;
+        via: string;
+    }[];
+}
+export interface GroupSummary {
+    name: string;
+    tableCount: number;
+    tables: string[];
+}
+export interface SearchResult {
+    table: string;
+    match: "table_name" | "table_note" | "column_name" | "column_note";
+    column?: string;
+    text: string;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dbml-metaquery",
+  "version": "0.1.0",
+  "description": "Parse DBML into a navigable graph with rich metadata -- FK path finding, table info, groups, and schema search.",
+  "type": "module",
+  "bin": {
+    "dbml-metaquery": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --format esm --sourcemap=linked && printf '#!/usr/bin/env node\\n' | cat - dist/cli.js > dist/cli.tmp && mv dist/cli.tmp dist/cli.js && bunx tsc --project tsconfig.build.json",
+    "cli": "bun run src/cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "src/cli.ts"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@dbml/parse": "^7.0.0-alpha.0",
+    "graphology": "^0.25.4",
+    "graphology-shortest-path": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
+  "keywords": ["dbml", "database", "schema", "graph", "path-finding", "metadata"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ada-lovecraft/dbml-metaquery.git"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,271 @@
+/**
+ * CLI for dbml-metaquery.
+ *
+ * Usage:
+ *   dbml-metaquery <dbml-path> find-path <from> <to>
+ *   dbml-metaquery <dbml-path> info <table>
+ *   dbml-metaquery <dbml-path> neighbors <table>
+ *   dbml-metaquery <dbml-path> refs-to <table>
+ *   dbml-metaquery <dbml-path> rels <table>
+ *   dbml-metaquery <dbml-path> search <query>
+ *   dbml-metaquery <dbml-path> summary
+ *   dbml-metaquery <dbml-path> tables
+ */
+
+import { readFileSync, existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { DbmlGraph } from "./graph"
+
+const args = process.argv.slice(2)
+
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+  console.log("Usage: dbml-metaquery <dbml-path> <command> [args]")
+  console.log()
+  console.log("Parse DBML into a navigable graph with rich metadata.")
+  console.log()
+  console.log("Commands:")
+  console.log("  find-path <from> <to>  Find shortest FK path between tables")
+  console.log("  info <table>           Show table metadata (note, columns, group)")
+  console.log("  neighbors <table>      Show tables directly connected via FK")
+  console.log("  refs-to <table>        Show tables that reference this table")
+  console.log("  rels <table>           Show all FK relationships for a table")
+  console.log("  search <query>         Search table/column names and notes")
+  console.log("  summary                Show schema overview (groups and table counts)")
+  console.log("  tables                 List all table names")
+  process.exit(0)
+}
+
+const dbmlPath = resolve(args[0]!)
+if (!existsSync(dbmlPath)) {
+  console.error(`DBML file not found: ${dbmlPath}`)
+  process.exit(1)
+}
+
+const command = args[1]
+if (!command) {
+  console.error("No command provided. Use --help for usage.")
+  process.exit(1)
+}
+
+const dbml = readFileSync(dbmlPath, "utf-8")
+const graph = new DbmlGraph(dbml)
+const cmdArgs = args.slice(2)
+
+switch (command) {
+  case "tables": {
+    const tables = graph.getTables()
+    console.log(`${tables.length} tables:\n`)
+    for (const t of tables) {
+      console.log(`  ${t}`)
+    }
+    break
+  }
+
+  case "summary": {
+    const summary = graph.getSummary()
+    const total = summary.reduce((n, g) => n + g.tableCount, 0)
+    console.log(`${total} tables in ${summary.length} groups:\n`)
+    for (const group of summary) {
+      const color = graph.getGroupColor(group.name)
+      const colorStr = color ? ` \x1b[2m${color}\x1b[0m` : ""
+      console.log(`  \x1b[1m${group.name}\x1b[0m (${group.tableCount})${colorStr}`)
+      for (const t of group.tables) {
+        console.log(`    ${t}`)
+      }
+      console.log()
+    }
+    break
+  }
+
+  case "info": {
+    if (!cmdArgs[0]) {
+      console.error("Usage: dbml-metaquery <dbml-path> info <table>")
+      process.exit(1)
+    }
+    const table = graph.getTable(cmdArgs[0])
+    if (!table) {
+      console.error(`Table "${cmdArgs[0]}" not found`)
+      process.exit(1)
+    }
+
+    console.log(`\x1b[1m${table.name}\x1b[0m`)
+    if (table.note) {
+      console.log(`  ${table.note}`)
+    }
+    const color = graph.getTableColor(table.name)
+    if (color) {
+      console.log(`  \x1b[2mcolor:\x1b[0m ${color}`)
+    }
+    const group = graph.getGroup(table.name)
+    if (group) {
+      console.log(`  \x1b[2mgroup:\x1b[0m ${group.name} (${group.tables.length} tables)`)
+    }
+    console.log()
+    console.log(`  \x1b[2mColumns:\x1b[0m`)
+    for (const col of table.columns) {
+      let line = `    ${col.name} \x1b[2m${col.type}\x1b[0m`
+      if (col.fk) {
+        line += ` \x1b[33m-> ${col.fk.table}.${col.fk.column}\x1b[0m`
+      }
+      if (col.note) {
+        line += `\n      \x1b[2m${col.note}\x1b[0m`
+      }
+      console.log(line)
+    }
+    break
+  }
+
+  case "neighbors": {
+    if (!cmdArgs[0]) {
+      console.error("Usage: dbml-metaquery <dbml-path> neighbors <table>")
+      process.exit(1)
+    }
+    if (!graph.getTable(cmdArgs[0])) {
+      console.error(`Table "${cmdArgs[0]}" not found`)
+      process.exit(1)
+    }
+
+    const n = graph.getNeighbors(cmdArgs[0])
+    console.log(`\x1b[1m${cmdArgs[0]}\x1b[0m\n`)
+
+    if (n.parents.length > 0) {
+      console.log(`  \x1b[2mParents (tables I reference):\x1b[0m`)
+      for (const p of n.parents) {
+        console.log(`    \x1b[33m${p.via}\x1b[0m -> ${p.table}`)
+      }
+      console.log()
+    }
+
+    if (n.children.length > 0) {
+      console.log(`  \x1b[2mChildren (tables that reference me):\x1b[0m`)
+      for (const c of n.children) {
+        console.log(`    ${c.table}.\x1b[33m${c.via}\x1b[0m`)
+      }
+      console.log()
+    }
+
+    if (n.parents.length === 0 && n.children.length === 0) {
+      console.log("  No FK connections.")
+    }
+    break
+  }
+
+  case "refs-to": {
+    if (!cmdArgs[0]) {
+      console.error("Usage: dbml-metaquery <dbml-path> refs-to <table>")
+      process.exit(1)
+    }
+    const refs = graph.getReferencingTables(cmdArgs[0])
+
+    if (refs.length === 0) {
+      console.log(`No tables reference "${cmdArgs[0]}"`)
+    } else {
+      console.log(`${refs.length} tables reference \x1b[1m${cmdArgs[0]}\x1b[0m:\n`)
+      for (const r of refs) {
+        console.log(`  ${r.table}.\x1b[33m${r.column}\x1b[0m -> ${cmdArgs[0]}.\x1b[33m${r.myColumn}\x1b[0m`)
+      }
+    }
+    break
+  }
+
+  case "rels": {
+    if (!cmdArgs[0]) {
+      console.error("Usage: dbml-metaquery <dbml-path> rels <table>")
+      process.exit(1)
+    }
+    const rels = graph.getRelationships(cmdArgs[0])
+    if (rels.length === 0) {
+      console.log(`No relationships found for "${cmdArgs[0]}"`)
+    } else {
+      console.log(`${rels.length} relationships for "${cmdArgs[0]}":\n`)
+      for (const r of rels) {
+        const direction =
+          r.childTable === cmdArgs[0]
+            ? `  ${r.childTable}.${r.childColumn} -> ${r.parentTable}.${r.parentColumn}`
+            : `  ${r.parentTable}.${r.parentColumn} <- ${r.childTable}.${r.childColumn}`
+        console.log(direction)
+      }
+    }
+    break
+  }
+
+  case "search": {
+    if (!cmdArgs[0]) {
+      console.error("Usage: dbml-metaquery <dbml-path> search <query>")
+      process.exit(1)
+    }
+    const results = graph.searchSchema(cmdArgs[0])
+
+    if (results.length === 0) {
+      console.log(`No matches for "${cmdArgs[0]}"`)
+    } else {
+      console.log(`${results.length} matches for "\x1b[1m${cmdArgs[0]}\x1b[0m":\n`)
+      for (const r of results) {
+        switch (r.match) {
+          case "table_name":
+            console.log(`  \x1b[1m${r.table}\x1b[0m \x1b[2m(table)\x1b[0m`)
+            break
+          case "table_note":
+            console.log(`  \x1b[1m${r.table}\x1b[0m \x1b[2m(note: ${r.text})\x1b[0m`)
+            break
+          case "column_name":
+            console.log(`  ${r.table}.\x1b[33m${r.column}\x1b[0m \x1b[2m(column)\x1b[0m`)
+            break
+          case "column_note":
+            console.log(`  ${r.table}.\x1b[33m${r.column}\x1b[0m \x1b[2m(note: ${r.text})\x1b[0m`)
+            break
+        }
+      }
+    }
+    break
+  }
+
+  case "find-path": {
+    const [fromTable, toTable] = cmdArgs
+    if (!fromTable || !toTable) {
+      console.error("Usage: dbml-metaquery <dbml-path> find-path <from> <to>")
+      process.exit(1)
+    }
+
+    try {
+      const path = graph.findPath(fromTable, toTable)
+
+      if (path === null) {
+        console.log(`No path found from "${fromTable}" to "${toTable}"`)
+        process.exit(1)
+      }
+
+      if (path.length === 0) {
+        console.log(`"${fromTable}" and "${toTable}" are the same table.`)
+        break
+      }
+
+      console.log(
+        `Path from \x1b[1m${fromTable}\x1b[0m to \x1b[1m${toTable}\x1b[0m (${path.length} hop${path.length > 1 ? "s" : ""}):\n`,
+      )
+
+      for (const step of path) {
+        console.log(
+          `  ${step.from.table}.\x1b[33m${step.from.column}\x1b[0m -> ${step.to.table}.\x1b[33m${step.to.column}\x1b[0m`,
+        )
+      }
+
+      console.log()
+      console.log("\x1b[2mSQL:\x1b[0m")
+      console.log(`  \x1b[2mFROM\x1b[0m ${fromTable}`)
+      for (const step of path) {
+        console.log(
+          `  \x1b[2mJOIN\x1b[0m ${step.to.table} \x1b[2mON\x1b[0m ${step.from.table}.${step.from.column} = ${step.to.table}.${step.to.column}`,
+        )
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exit(1)
+    }
+    break
+  }
+
+  default:
+    console.error(`Unknown command: ${command}. Use --help for usage.`)
+    process.exit(1)
+}