quickdbd-cli 0.1.17__tar.gz → 0.1.18__tar.gz

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.17
+Version: 0.1.18
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://github.com/MarkPhamm/quickdbd-cli
 Author: Minh (Mark) Pham
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 <p align="center"><b>Interactive ER diagrams from QuickDBD text or a dbt project, readable at 200+ tables</b></p>
 
 <p align="center">
-  <a href="https://qdbd.dev/">Docs</a> · <a href="https://qdbd.dev/demo/">Live demos</a> · <a href="#quickstart">Quickstart</a> · <a href="https://pypi.org/project/quickdbd-cli/">PyPI</a>
+  <a href="https://qdbd.dev/">Docs</a> · <a href="https://qdbd.dev/demo/">Live demos</a> · <a href="#quickstart">Quickstart</a> · <a href="https://pypi.org/project/quickdbd-cli/">PyPI</a> · <a href="https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd">VS Code Marketplace</a> · <a href="https://open-vsx.org/extension/MarkPhamm/quickdbd">Open VSX</a>
 </p>
 
 <p align="center">
@@ -65,7 +65,7 @@ qdbd is not affiliated with QuickDBD. It reads the same text syntax, so schemas
 - **dbt import**: `qdbd import dbt` reads `manifest.json`. Primary keys come from `unique` + `not_null` tests or constraints, relationships from `relationships` tests, and `--infer-fks` fills the gaps from column names.
 - **Readable at 200+ tables**: automatic layout, search, dbt-style selectors (`+orders+1`, `group:marts`, `tag:fact`), shaded regions per file, collapsed views and a minimap.
 - **Review changes in pull requests**: `qdbd diff` reports what a branch changed, the GitHub Action posts it as a PR comment, and `--diff-base` colours the changes in the diagram.
-- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor ([docs](https://qdbd.dev/vscode/)).
+- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor. Export, share, compare with git and dbt import from the Command Palette, with no terminal: it installs the CLI itself. Get it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) or, for Cursor, Windsurf and VSCodium, [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd) ([docs](https://qdbd.dev/vscode/)).
 - **One schema, many outputs**: an HTML page, PNG, SVG, editable draw.io, or a shareable link. Installs with pip: no Node, Graphviz or browser needed.
 
 ## Demo gallery

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/README.md

@@ -8,7 +8,7 @@
 <p align="center"><b>Interactive ER diagrams from QuickDBD text or a dbt project, readable at 200+ tables</b></p>
 
 <p align="center">
-  <a href="https://qdbd.dev/">Docs</a> · <a href="https://qdbd.dev/demo/">Live demos</a> · <a href="#quickstart">Quickstart</a> · <a href="https://pypi.org/project/quickdbd-cli/">PyPI</a>
+  <a href="https://qdbd.dev/">Docs</a> · <a href="https://qdbd.dev/demo/">Live demos</a> · <a href="#quickstart">Quickstart</a> · <a href="https://pypi.org/project/quickdbd-cli/">PyPI</a> · <a href="https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd">VS Code Marketplace</a> · <a href="https://open-vsx.org/extension/MarkPhamm/quickdbd">Open VSX</a>
 </p>
 
 <p align="center">
@@ -37,7 +37,7 @@ qdbd is not affiliated with QuickDBD. It reads the same text syntax, so schemas
 - **dbt import**: `qdbd import dbt` reads `manifest.json`. Primary keys come from `unique` + `not_null` tests or constraints, relationships from `relationships` tests, and `--infer-fks` fills the gaps from column names.
 - **Readable at 200+ tables**: automatic layout, search, dbt-style selectors (`+orders+1`, `group:marts`, `tag:fact`), shaded regions per file, collapsed views and a minimap.
 - **Review changes in pull requests**: `qdbd diff` reports what a branch changed, the GitHub Action posts it as a PR comment, and `--diff-base` colours the changes in the diagram.
-- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor ([docs](https://qdbd.dev/vscode/)).
+- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor. Export, share, compare with git and dbt import from the Command Palette, with no terminal: it installs the CLI itself. Get it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) or, for Cursor, Windsurf and VSCodium, [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd) ([docs](https://qdbd.dev/vscode/)).
 - **One schema, many outputs**: an HTML page, PNG, SVG, editable draw.io, or a shareable link. Installs with pip: no Node, Graphviz or browser needed.
 
 ## Demo gallery

quickdbd_cli-0.1.18/examples/demo.txt

@@ -0,0 +1,56 @@
+members
+-
+member_sk PK integer
+
+
+machines
+-
+machine_sk PK integer
+
+
+tables
+-
+table_sk PK integer
+
+
+hosts
+-
+host_sk PK integer
+
+
+member_tier
+-
+member_tier_sk PK integer
+
+
+gaming_transactions
+-
+member_sk integer FK >- members.member_sk
+window_code varchar
+snapshot_date date
+
+
+# one_to_one with gaming_transactions on the composite key (member_sk, window_code, snapshot_date)
+gaming_transactions_trend
+-
+member_sk integer FK - gaming_transactions.member_sk
+window_code varchar FK - gaming_transactions.window_code
+snapshot_date date FK - gaming_transactions.snapshot_date
+
+
+gaming_transactions_detail
+-
+member_sk integer NULL FK >- members.member_sk
+machine_sk integer NULL FK >- machines.machine_sk
+table_sk integer NULL FK >- tables.table_sk
+
+
+points_transactions
+-
+member_sk integer NULL FK >- members.member_sk
+
+
+reservations
+-
+host_sk integer NULL FK >- hosts.host_sk
+member_tier_sk integer NULL FK >- member_tier.member_tier_sk

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/examples/quickdbd-sample.layout.json

@@ -9,8 +9,8 @@
       "y": 259
     },
     "Order": {
-      "x": 482,
-      "y": 164
+      "x": 479,
+      "y": 48
     },
     "OrderLine": {
       "x": 735,

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.17"
+version = "0.1.18"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"

quickdbd_cli-0.1.18/src/quickdbd_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.18"

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/src/quickdbd_cli/cli.py

@@ -51,14 +51,20 @@ def _github_annotation(d: Diagnostic, level: str) -> str:
 
 
 def _symbols(schema: Schema) -> dict:
-    """Tables, columns and relationships with their source lines, for editor outlines and go-to-definition."""
+    """Tables, columns and relationships with their source lines, for editor outlines, go-to-definition and the
+    VS Code sidebar (column types and keys, table docs)."""
     tables = []
     for t in schema.tables.values():
-        cols = [{"name": c.name, "line": c.line} for c in t.columns.values() if not c.virtual]
+        cols = [
+            {"name": c.name, "line": c.line, "type": c.type, "pk": c.pk, "fk": c.fk}
+            for c in t.columns.values()
+            if not c.virtual
+        ]
         end = max([t.line + 1] + [c["line"] for c in cols])
-        tables.append(
-            {"name": t.name, "aliases": t.aliases, "file": t.path, "line": t.line, "endLine": end, "columns": cols}
-        )
+        table = {"name": t.name, "aliases": t.aliases, "file": t.path, "line": t.line, "endLine": end, "columns": cols}
+        if t.comments:
+            table["doc"] = "\n".join(t.comments)
+        tables.append(table)
 
     def end(e) -> dict:
         t = schema.tables.get(e.table)

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/tests/test_pipeline.py

@@ -184,6 +184,18 @@ def test_check_symbols_list_tables_columns_and_rels(tmp_path, capsys):
     assert "tables" not in json.loads(capsys.readouterr().out)  # only with --symbols
 
 
+def test_check_symbols_carry_types_keys_and_docs(tmp_path, capsys):
+    f = tmp_path / "shop.txt"
+    f.write_text("# People who buy things\n" + SMALL)
+    assert main(["check", "--format", "json", "--symbols", str(f)]) == 0
+    tables = {t["name"]: t for t in json.loads(capsys.readouterr().out)["tables"]}
+    assert tables["Customer"]["doc"] == "People who buy things"
+    assert "doc" not in tables["Order"]
+    cols = {c["name"]: c for c in tables["Order"]["columns"]}
+    assert {k: cols["OrderId"][k] for k in ("type", "pk", "fk")} == {"type": "int", "pk": True, "fk": False}
+    assert cols["CustomerId"]["fk"] and not cols["CustomerId"]["pk"]
+
+
 def test_check_stdin_file_uses_the_unsaved_text(tmp_path, capsys, monkeypatch):
     import io
 

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/vscode/src/checker.ts

@@ -63,6 +63,24 @@ export class Checker implements vscode.Disposable {
     if (e?.pending) await Promise.race([e.pending, new Promise((r) => setTimeout(r, READY_TIMEOUT))]);
   }
 
+  /** The latest report for a schema, opened in an editor or not. */
+  reportOf(target: Target): Report | undefined {
+    return this.entries.get(targetKey(target))?.report;
+  }
+
+  /** Check a schema from disk (the sidebar's, with no editor open). Skipped while a check of it is due, or while an
+   * editor has unsaved text in it: the editor's checks use that text, and a check from disk would undo them. */
+  async checkTarget(target: Target): Promise<void> {
+    const key = targetKey(target);
+    let e = this.entries.get(key);
+    if (!e) this.entries.set(key, (e = { target, files: new Set(), seq: 0 }));
+    if (e.pending) return e.pending;
+    const dirty = vscode.workspace.textDocuments.some(
+      (d) => d.isDirty && d.languageId === LANGUAGE && d.uri.scheme === "file" && targetKey(this.targetFor(d)) === key,
+    );
+    if (!dirty) await this.run(e, undefined, ++e.seq);
+  }
+
   reports(): { target: Target; report: Report }[] {
     return [...this.entries.values()].flatMap((e) => (e.report ? [{ target: e.target, report: e.report }] : []));
   }
@@ -88,11 +106,11 @@ export class Checker implements vscode.Disposable {
     }, delay);
   }
 
-  private async run(e: Entry, doc: vscode.TextDocument, seq: number): Promise<void> {
+  private async run(e: Entry, doc: vscode.TextDocument | undefined, seq: number): Promise<void> {
     const strict = vscode.workspace.getConfiguration("quickdbd").get<boolean>("strict") ? ["--strict"] : [];
-    const unsaved = doc.isDirty && !doc.isClosed ? ["--stdin-file", relative(e.target, doc.uri.fsPath)] : [];
+    const unsaved = doc?.isDirty && !doc.isClosed ? ["--stdin-file", relative(e.target, doc.uri.fsPath)] : [];
     const args = ["check", "--format", "json", "--symbols", ...strict, ...unsaved, ...e.target.paths];
-    const res = await this.qdbd.run(args, e.target.cwd, unsaved.length ? doc.getText() : undefined);
+    const res = await this.qdbd.run(args, e.target.cwd, unsaved.length ? doc?.getText() : undefined);
     if (!res || seq !== e.seq) return; // no qdbd, or a newer check started
     let report: Report;
     try {

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/vscode/src/cli.ts

@@ -11,9 +11,13 @@ export const MIN_VERSION = [0, 1, 17];
 
 export type RunResult = ExecResult;
 
-interface Found {
+/** Where the qdbd in use came from (resolve's order). */
+export type Source = "setting" | "workspace" | "extension" | "path";
+
+export interface Found {
   exe: string;
   version: number[];
+  source: Source;
 }
 
 export class Qdbd {
@@ -23,6 +27,9 @@ export class Qdbd {
   private readonly installed = new vscode.EventEmitter<void>();
   /** Fires after an install or update, so checks that failed for want of qdbd can run again. */
   readonly onDidInstall = this.installed.event;
+  private readonly resolvedEvent = new vscode.EventEmitter<Found | undefined>();
+  /** Fires each time qdbd is looked up anew (start, setting change, install): the sidebar shows which one. */
+  readonly onDidResolve = this.resolvedEvent.event;
 
   private readonly log: vscode.OutputChannel;
   private readonly venv: string;
@@ -43,8 +50,14 @@ export class Qdbd {
     return this.found().then((f) => f?.exe);
   }
 
-  private found(): Promise<Found | undefined> {
-    this.resolved ??= this.resolve();
+  /** The qdbd in use, with its version and where it came from; undefined if missing or too old. */
+  found(): Promise<Found | undefined> {
+    this.resolved ??= this.resolve().then((f) => {
+      // The sidebar's welcome view offers the install while this is set.
+      void vscode.commands.executeCommand("setContext", "quickdbd.cliMissing", !f);
+      this.resolvedEvent.fire(f);
+      return f;
+    });
     return this.resolved;
   }
 
@@ -55,7 +68,7 @@ export class Qdbd {
    */
   private async resolve(): Promise<Found | undefined> {
     let old: string | undefined;
-    const probe = async (exe: string): Promise<Found | undefined> => {
+    const probe = async (exe: string, source: Source): Promise<Found | undefined> => {
       const out = await version(exe);
       if (out === undefined) return undefined;
       const v = parseVersion(out) ?? MIN_VERSION;
@@ -64,7 +77,7 @@ export class Qdbd {
         old ??= v.join(".");
         return undefined;
       }
-      return { exe, version: v };
+      return { exe, version: v, source };
     };
     const use = (f: Found) => {
       this.log.appendLine(`using ${f.exe} (qdbd ${f.version.join(".")})`);
@@ -72,7 +85,7 @@ export class Qdbd {
     };
     const setting = vscode.workspace.getConfiguration("quickdbd").get<string>("qdbdPath")?.trim();
     if (setting) {
-      const f = await probe(setting);
+      const f = await probe(setting, "setting");
       if (f) return use(f);
       this.tell(
         old
@@ -82,10 +95,11 @@ export class Qdbd {
       return undefined;
     }
     for (const exe of workspaceVenvs()) {
-      const f = await probe(exe);
+      const f = await probe(exe, "workspace");
       if (f) return use(f);
     }
-    const found = (await Promise.all([venvBin(this.venv, "qdbd"), "qdbd"].map(probe))).filter((f) => f !== undefined);
+    const ours = probe(venvBin(this.venv, "qdbd"), "extension");
+    const found = (await Promise.all([ours, probe("qdbd", "path")])).filter((f) => f !== undefined);
     found.sort((a, b) => (atLeast(a.version, b.version) ? -1 : 1));
     if (found[0]) return use(found[0]);
     this.tell(
@@ -169,6 +183,7 @@ export class Qdbd {
 
   dispose(): void {
     this.installed.dispose();
+    this.resolvedEvent.dispose();
   }
 }
 

quickdbd_cli-0.1.18/vscode/src/extension.ts

@@ -0,0 +1,185 @@
+/* QuickDBD for VS Code: highlighting, live diagnostics, outline and go-to-definition, the qdbd diagram as a side
+ * preview, the CLI's other commands (export, share, compare, dbt import), and a sidebar listing every schema, all
+ * without a terminal. Everything schema-aware comes from the `qdbd` CLI, which the extension can install for itself
+ * (cli.ts). */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as vscode from "vscode";
+import { Checker, LANGUAGE } from "./checker.ts";
+import { Qdbd } from "./cli.ts";
+import { pickRef } from "./compare.ts";
+import { importDbt, type ImportOptions } from "./dbt.ts";
+import { exportDiagram, share, type Format } from "./export.ts";
+import { Previews } from "./preview.ts";
+import type { Target } from "./schema.ts";
+import { isSchemaArg, Sidebar, type Node } from "./sidebar.ts";
+import { registerSymbols } from "./symbols.ts";
+import { isSchemaFile, targetTitle } from "./target.ts";
+
+const TYPING_DELAY = 300;
+
+const STARTER = `# Customers: one row per person who has bought something.
+Customer
+-
+CustomerId PK int
+Name string
+Email string UNIQUE
+
+# Orders: each one belongs to a customer.
+Order
+-
+OrderId PK int
+CustomerId int FK >- Customer.CustomerId
+OrderedAt datetime
+Total money
+`;
+
+/** For tests: the sidebar's schemas, with their table counts once checked. */
+export interface Api {
+  schemas(): Promise<{ title: string; tables?: number; target: Target; file: string }[]>;
+}
+
+export function activate(context: vscode.ExtensionContext): Api {
+  const log = vscode.window.createOutputChannel("QuickDBD");
+  const qdbd = new Qdbd(log, context.globalStorageUri.fsPath);
+  const checker = new Checker(qdbd, log);
+  const previews = new Previews(qdbd, checker, log);
+  const sidebar = new Sidebar(checker, qdbd);
+
+  /** The schema a command runs on: a sidebar row, the editor its title-bar button sits on, else the current one
+   * (active editor, sidebar selection, the only schema), else one picked from the list. */
+  async function schemaDoc(arg: unknown): Promise<vscode.TextDocument | undefined> {
+    if (isSchemaArg(arg)) return vscode.workspace.openTextDocument(arg.file);
+    if (arg instanceof vscode.Uri) return vscode.workspace.openTextDocument(arg);
+    const current = await sidebar.current(true);
+    if (current) {
+      const active = vscode.window.activeTextEditor?.document;
+      return active?.uri.fsPath === current.file ? active : vscode.workspace.openTextDocument(current.file);
+    }
+    const all = await sidebar.schemas.all();
+    if (!all.length) {
+      const pick = await vscode.window.showInformationMessage("There's no QuickDBD schema here yet.", "New Schema File");
+      if (pick) void vscode.commands.executeCommand("quickdbd.newSchema");
+      return undefined;
+    }
+    const items = all.map((s) => ({ label: targetTitle(s.target), description: vscode.workspace.asRelativePath(s.file), s }));
+    const pick = await vscode.window.showQuickPick(items, { title: "Which schema?" });
+    return pick && vscode.workspace.openTextDocument(pick.s.file);
+  }
+
+  // `opts` comes from a keybinding's or a test's arguments; sidebar rows and menus pass other things, so it's checked.
+  const withSchema = (fn: (doc: vscode.TextDocument, opts: Record<string, unknown>) => unknown) => async (arg?: unknown) => {
+    const doc = await schemaDoc(arg);
+    const plain = arg && typeof arg === "object" && !isSchemaArg(arg) && !(arg instanceof vscode.Uri);
+    if (doc) return fn(doc, plain ? { ...arg } : {});
+  };
+  const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
+  const exporter = (format: Format) =>
+    withSchema((doc, opts) => exportDiagram(qdbd, checker, doc, format, str(opts.output)));
+
+  context.subscriptions.push(
+    log,
+    qdbd,
+    checker,
+    previews,
+    sidebar,
+    qdbd.onDidInstall(() => vscode.workspace.textDocuments.forEach((d) => checker.schedule(d, 0))),
+    registerSymbols(checker),
+    vscode.workspace.onDidOpenTextDocument((doc) => void opened(doc, checker)),
+    vscode.workspace.onDidChangeTextDocument((e) => checker.schedule(e.document, TYPING_DELAY)),
+    vscode.workspace.onDidSaveTextDocument((doc) => checker.schedule(doc, 0)),
+    vscode.workspace.onDidChangeConfiguration((e) => {
+      if (e.affectsConfiguration("quickdbd.qdbdPath")) qdbd.reset();
+      if (!e.affectsConfiguration("quickdbd")) return;
+      vscode.workspace.textDocuments.forEach((d) => checker.schedule(d, 0));
+      sidebar.schemas.refresh();
+    }),
+    vscode.commands.registerCommand("quickdbd.openPreview", withSchema((doc) => previews.show(doc))),
+    vscode.commands.registerCommand("quickdbd.exportPng", exporter("png")),
+    vscode.commands.registerCommand("quickdbd.exportSvg", exporter("svg")),
+    vscode.commands.registerCommand("quickdbd.exportDrawio", exporter("drawio")),
+    vscode.commands.registerCommand("quickdbd.exportHtml", exporter("html")),
+    vscode.commands.registerCommand(
+      "quickdbd.export",
+      withSchema(async (doc) => {
+        const formats: { label: string; format: Format }[] = [
+          { label: "PNG image", format: "png" },
+          { label: "SVG image", format: "svg" },
+          { label: "draw.io diagram", format: "drawio" },
+          { label: "HTML page", format: "html" },
+        ];
+        const pick = await vscode.window.showQuickPick(formats, { title: "Export as" });
+        if (pick) await exportDiagram(qdbd, checker, doc, pick.format);
+      }),
+    ),
+    vscode.commands.registerCommand("quickdbd.share", withSchema((doc) => share(qdbd, checker, doc))),
+    vscode.commands.registerCommand(
+      "quickdbd.compare",
+      withSchema(async (doc, opts) => {
+        const ref = str(opts.ref) ?? (await pickRef(checker.targetFor(doc).cwd));
+        if (ref) await previews.show(doc, ref);
+      }),
+    ),
+    vscode.commands.registerCommand("quickdbd.importDbt", (opts?: ImportOptions) =>
+      importDbt(qdbd, (doc) => previews.show(doc), {
+        manifest: str(opts?.manifest),
+        output: str(opts?.output),
+      }),
+    ),
+    vscode.commands.registerCommand("quickdbd.installCli", () => qdbd.install()),
+    vscode.commands.registerCommand("quickdbd.refreshSchemas", () => sidebar.schemas.refresh()),
+    vscode.commands.registerCommand("quickdbd.newSchema", (opts?: { output?: string }) => newSchema(previews, str(opts?.output))),
+    // A table's row in the sidebar: open the diagram, then put the cursor in the table, which the diagram follows.
+    vscode.commands.registerCommand("quickdbd.revealTable", async (n?: Node) => {
+      if (n?.kind !== "table") return;
+      const doc = await vscode.workspace.openTextDocument(n.file);
+      const at = new vscode.Position(n.table.line - 1, 0);
+      await vscode.window.showTextDocument(doc, { selection: new vscode.Range(at, at), preserveFocus: true });
+      await previews.show(doc);
+    }),
+  );
+  vscode.workspace.textDocuments.forEach((doc) => void opened(doc, checker));
+
+  return {
+    async schemas() {
+      return (await sidebar.schemas.all()).map((s) => ({
+        ...s,
+        title: targetTitle(s.target),
+        tables: checker.reportOf(s.target)?.tables?.length,
+      }));
+    },
+  };
+}
+
+/** Switch a plain .txt that is a QuickDBD schema to the QuickDBD language, then check it. */
+async function opened(doc: vscode.TextDocument, checker: Checker): Promise<void> {
+  if (doc.languageId === "plaintext" && doc.uri.scheme === "file" && /\.txt$/i.test(doc.uri.fsPath)) {
+    if (!vscode.workspace.getConfiguration("quickdbd").get<boolean>("autoDetect", true)) return;
+    if (!isSchemaFile(doc.uri.fsPath, doc.getText(), true)) return;
+    await vscode.languages.setTextDocumentLanguage(doc, LANGUAGE); // reopens it as QuickDBD, which lands here again
+    return;
+  }
+  checker.schedule(doc, 0);
+}
+
+/** New Schema File: a small starter schema, opened with its diagram. `output` skips the save dialog (tests). */
+async function newSchema(previews: Previews, output?: string): Promise<void> {
+  const folder = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? os.homedir();
+  const out = output
+    ? vscode.Uri.file(path.resolve(folder, output))
+    : await vscode.window.showSaveDialog({
+        title: "New Schema File",
+        defaultUri: vscode.Uri.file(path.join(folder, "schema.txt")),
+        filters: { "QuickDBD schema": ["txt"] },
+      });
+  if (!out) return;
+  fs.mkdirSync(path.dirname(out.fsPath), { recursive: true });
+  fs.writeFileSync(out.fsPath, STARTER); // the save dialog has already asked about replacing a file
+  let doc = await vscode.workspace.openTextDocument(out);
+  if (doc.languageId !== LANGUAGE) doc = await vscode.languages.setTextDocumentLanguage(doc, LANGUAGE);
+  await vscode.window.showTextDocument(doc);
+  await previews.show(doc);
+}
+
+export function deactivate(): void {}

{quickdbd_cli-0.1.17 → quickdbd_cli-0.1.18}/vscode/src/schema.ts

@@ -12,6 +12,10 @@ export interface Diag {
 export interface Column {
   name: string;
   line: number;
+  // qdbd 0.1.18+: shown in the sidebar when present
+  type?: string | null;
+  pk?: boolean;
+  fk?: boolean;
 }
 
 export interface Table {
@@ -21,6 +25,7 @@ export interface Table {
   line: number;
   endLine: number;
   columns: Column[];
+  doc?: string; // qdbd 0.1.18+: the table's `#` comments
 }
 
 export interface Report {
@@ -60,6 +65,20 @@ export function looksLikeQuickdbd(text: string): boolean {
   return text.split(/\r?\n/, 5000).some((l) => !l.trimStart().startsWith("#") && KEYED.test(l));
 }
 
+/** "int · PK" for the sidebar: the type, then the keys. */
+export function columnDetail(c: Column): string {
+  const keys = [c.pk && "PK", c.fk && "FK"].filter(Boolean).join(", ");
+  return [c.type, keys].filter(Boolean).join(" · ");
+}
+
+/** The report's tables grouped by file, files in path order and tables by name. */
+export function tablesByFile(report: Report): { file: string; tables: Table[] }[] {
+  const byFile = new Map<string, Table[]>();
+  for (const t of report.tables ?? []) byFile.set(t.file, [...(byFile.get(t.file) ?? []), t]);
+  const name = (a: Table, b: Table) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+  return [...byFile.keys()].sort().map((file) => ({ file, tables: byFile.get(file)!.sort(name) }));
+}
+
 /** The table whose lines include `line` (1-based) in `file` (a report path). */
 export function tableAt(report: Report, file: string, line: number): Table | undefined {
   return (report.tables ?? []).find((t) => t.file === file && line >= t.line && line <= t.endLine);