@intentius/chant-lexicon-sql 0.124.22 → 0.124.23

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "261d72f2373ca341b6c922bcabe436354b7e3a6f34807b9da0d37df974d53599",
+    "manifest.json": "6ff9ade6841fa9bd2bc93e37a99a7f62be197241e6f265497ec9835e71d4a3cb",
     "meta.json": "59ca03876cce0d293e15a7f0a90ef7f250d133e46773c73fedede4a2ec792119",
     "types/index.d.ts": "0286ebb367773e84c76818b0f69cb14cff8328fd2f8c65ed87563c8d5815458c",
     "rules/postgres-templates.ts": "082da542239ab9f9627026972281102a61ca269cb79e2514f402dfc400ccdcde",
@@ -79,5 +79,5 @@
     "rules/sqlpg125.ts": "cc7411c57c525613dc720ba00e986bbc4e5a84b8b0bcfa7a6ce0d058f039f025",
     "rules/sqlpg126.ts": "d57b82a5842273876510131d67bf4418cbd61eff821e245edebc644dafd502bb"
   },
-  "composite": "8d8fa52bd659ced8ca17a0962c03331590c1775e4f8989a2c684598487598df7"
+  "composite": "74fc50b802b5f7130fc4443a7b892d34776926c9da75827355ceec10529b4ba0"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "sql",
-  "version": "0.124.22",
+  "version": "0.124.23",
   "chantVersion": ">=0.1.0",
   "namespace": "SQL",
   "intrinsics": [],

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAwB5E,eAAO,MAAM,SAAS,EAAE,aAqPvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAyB5E,eAAO,MAAM,SAAS,EAAE,aA+PvB,CAAC"}

package/dist/workspace-outputs.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The workspace outputs a sql member exposes (#3931): each table and view,
+ * and each of their columns, as names another member's link may target.
+ *
+ * | Dialect | Relation | Column |
+ * |---|---|---|
+ * | Postgres | `<schema>.<table>` | `<schema>.<table>.<column>` |
+ * | ClickHouse | `<database>.<table>` | `<database>.<table>.<column>` |
+ *
+ * The schema is `public` when the DDL does not qualify the name, and the
+ * database `default`. Views and materialized views are relations too.
+ *
+ * Names are the declared ones, read from the entities the member's source
+ * folds to, never an environment's or a profile's rendering: a member that
+ * renames its database per environment or tenant at deploy time exposes the
+ * same outputs everywhere.
+ *
+ * Identifiers are written unquoted, in the case the dialect keeps:
+ *
+ * - Postgres folds an unquoted identifier to lower case and keeps a quoted
+ *   one exactly, so `CREATE TABLE Orders` is `public.orders` and `CREATE
+ *   TABLE "Orders"` is `public.Orders`, a different output;
+ * - ClickHouse is case-sensitive, so a name is kept as written, quoted or not.
+ *
+ * A link's near-name hint compares names case-insensitively, so a link to
+ * `public.orders` when only `public.Orders` exists is pointed at it.
+ *
+ * A view's columns are its declared column list, or else the names of its
+ * select list (an alias, or the column a bare reference reads). A select
+ * list item with no name chant can derive, or a `*`, leaves the view's
+ * columns incomplete: that is a gap, so a link to one of them is unresolved
+ * rather than missing.
+ *
+ * A `-- previously: <old>` rename hint, on a column's line or before the
+ * CREATE, is reported as the output's previous name, so a link to the old
+ * name says where it went.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { LexiconUnreadSource, LexiconWorkspaceOutputs } from "@intentius/chant/graph-ir";
+/** The schema an unqualified Postgres name is created in. */
+export declare const POSTGRES_DEFAULT_SCHEMA = "public";
+/** The database an unqualified ClickHouse name is created in. */
+export declare const CLICKHOUSE_DEFAULT_DATABASE = "default";
+/**
+ * The `workspaceOutputs` hook: every table and view the entities declare,
+ * and their columns. `unread` names the member's files that did not fold;
+ * one that imports the sql lexicon may declare tables, so it is a gap.
+ */
+export declare function sqlWorkspaceOutputs(entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]): LexiconWorkspaceOutputs | undefined;
+//# sourceMappingURL=workspace-outputs.d.ts.map

package/dist/workspace-outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-outputs.d.ts","sourceRoot":"","sources":["../src/workspace-outputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAA0B,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAOtH,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAChD,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,YAAY,CAAC;AA4HrD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAE,SAAS,mBAAmB,EAAO,GAAG,uBAAuB,GAAG,SAAS,CAoB/J"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.124.22",
+  "version": "0.124.23",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -24,7 +24,8 @@
   "type": "module",
   "files": [
     "src/",
-    "dist/"
+    "dist/",
+    "workspace-kinds.json"
   ],
   "exports": {
     ".": {
@@ -32,6 +33,7 @@
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
     },
+    "./workspace-kinds": "./workspace-kinds.json",
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
@@ -70,6 +72,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.22"
+    "@intentius/chant": "^0.124.23"
   }
 }

package/src/plugin.ts

@@ -29,6 +29,7 @@ import { CLICKHOUSE_EMULATOR } from "./op/activities/clickhouse-emulator";
 import { POSTGRES_EMULATOR } from "./op/activities/postgres-emulator";
 import { sqlSkills } from "./skill-defs";
 import { detectTemplate } from "./detect";
+import { sqlWorkspaceOutputs } from "./workspace-outputs";
 import { CDC_TEMPLATE, DEFAULT_TEMPLATE, EVENTS_TEMPLATE, POSTGRES_EVENTS_TEMPLATE, POSTGRES_TEMPLATE, POSTGRES_TENANT_TEMPLATE } from "./init-templates";
 import { compositeCatalog } from "./composites/catalog";
 
@@ -192,6 +193,16 @@ export const sqlPlugin: LexiconPlugin = {
     return sqlFilesBuildRoot(ctx);
   },
 
+  /**
+   * Each table and view, and each of their columns, as workspace outputs
+   * (`./workspace-outputs.ts`, #3931): `public.orders`,
+   * `public.orders.customer_id`. Another member's link to a dropped or
+   * renamed column then fails `chant workspace check`.
+   */
+  workspaceOutputs(entities, unread) {
+    return sqlWorkspaceOutputs(entities, unread);
+  },
+
   /** One generator for both dialects: each IR resource's type says whose declarations it is. */
   templateGenerator() {
     return sqlTemplateGenerator;

package/src/workspace-kinds.test.ts

@@ -0,0 +1,21 @@
+/**
+ * The dbt member kind this lexicon supplies to a chant workspace (#3932). It
+ * is data in `workspace-kinds.json` at the package root, exported at
+ * `./workspace-kinds`; chant reads it without importing the lexicon. A dbt
+ * project's sources read the tables a sql member declares.
+ */
+import { join } from "node:path";
+import { describeWorkspaceKindConformance } from "@intentius/chant-test-utils";
+
+const project = "name: analytics\nversion: '1.0'\nprofile: analytics\n";
+
+describeWorkspaceKindConformance({
+  packageDir: join(import.meta.dirname, ".."),
+  scenarios: [
+    { name: "a dbt project", kind: "dbt", files: { "dbt_project.yml": project, "models/sources.yml": "version: 2\n" }, claims: true },
+    // chant's own precedence (500) outranks dbt's (300): no tie.
+    { name: "a chant project beside a dbt_project.yml", kind: "dbt", files: { "dbt_project.yml": project, "chant.config.ts": "" }, claims: true },
+    { name: "a directory whose dbt project sits one level down", kind: "dbt", files: { "analytics/dbt_project.yml": project }, claims: false },
+    { name: "models without a project file", kind: "dbt", files: { "models/sources.yml": "version: 2\n" }, claims: false },
+  ],
+});

package/src/workspace-outputs.e2e.test.ts

@@ -0,0 +1,222 @@
+/**
+ * A sql member's tables and columns as workspace outputs (#3931), end to end:
+ * a workspace with a sql member and an app member that links to one column.
+ * `chant workspace check` reads the sql member's declarations by folding its
+ * source, never running it, so dropping or renaming the column fails the
+ * check and names the consumer. Once for Postgres, once for ClickHouse.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, afterEach, describe, expect, test, vi } from "vitest";
+import { runDeclarationChecks } from "@intentius/chant/workspace/checks";
+import { runWorkspaceCheck } from "@intentius/chant/workspace/lineage-check";
+import { parseArgs } from "@intentius/chant/cli/main";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3931-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const workspace = (output: string) =>
+  JSON.stringify(
+    {
+      name: "shop",
+      schema: 1,
+      members: [
+        { name: "db", dir: "db", kind: "chant" },
+        { name: "app", dir: "app", kind: "other", because: "the service that reads the database", links: [{ member: "db", output }] },
+      ],
+    },
+    null,
+    2,
+  );
+
+const config = (dialect: string) => `import type { ChantConfig } from "@intentius/chant";\nexport default { lexicons: ["sql"], sql: { dialect: "${dialect}" } } satisfies ChantConfig;\n`;
+
+const postgresOrders = (columns: string) =>
+  [
+    `import { table } from "@intentius/chant-lexicon-sql/postgres";`,
+    ``,
+    `export const orders = table\``,
+    `  CREATE TABLE orders (`,
+    `    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,`,
+    columns,
+    `    amount numeric(12, 2) NOT NULL`,
+    `  )\`;`,
+    ``,
+  ].join("\n");
+
+const clickhouseEvents = (columns: string) =>
+  [
+    `import { database, table } from "@intentius/chant-lexicon-sql/clickhouse";`,
+    ``,
+    `export const analytics = database\`CREATE DATABASE analytics\`;`,
+    `export const events = table\``,
+    `  CREATE TABLE \${analytics}.events (`,
+    `    ts DateTime,`,
+    columns,
+    `    kind LowCardinality(String)`,
+    `  )`,
+    `  ENGINE = MergeTree`,
+    `  ORDER BY ts\`;`,
+    ``,
+  ].join("\n");
+
+function shop(dialect: "postgres" | "clickhouse", output: string, source: string): string {
+  return repo({
+    "chant.workspace.json": workspace(output),
+    "db/chant.config.ts": config(dialect),
+    [`db/src/${dialect === "postgres" ? "orders" : "events"}.ts`]: source,
+    "app/README.md": "reads the database\n",
+  });
+}
+
+/** Every member of kind other gets WSP009; the app member here is one on purpose. */
+async function check(root: string) {
+  const report = await runDeclarationChecks(root);
+  return { ...report, diagnostics: report.diagnostics.filter((d) => d.ruleId !== "WSP009") };
+}
+
+async function checkExit(root: string): Promise<{ code: number; out: string }> {
+  vi.spyOn(process, "cwd").mockReturnValue(root);
+  let out = "";
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => {
+    out += String(chunk);
+    return true;
+  });
+  vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    out += `${args.join(" ")}\n`;
+  });
+  vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    out += `${args.join(" ")}\n`;
+  });
+  const code = await runWorkspaceCheck({ args: parseArgs(["workspace", "check"]), plugins: [] } as never);
+  return { code, out };
+}
+
+describe("a sql member's columns are outputs a link can name (#3931)", () => {
+  test("Postgres: a link to public.orders.customer_id resolves, and fails check naming the consumer once the column is dropped", async () => {
+    const kept = shop("postgres", "public.orders.customer_id", postgresOrders(`    customer_id bigint NOT NULL,`));
+    const ok = await check(kept);
+    expect(ok.diagnostics).toEqual([]);
+    expect(ok.links.filter((r) => r.origin === "declared")).toMatchObject([{ consumer: "app", producer: "db", output: "public.orders.customer_id", status: "resolved" }]);
+    expect((await checkExit(kept)).code).toBe(0);
+
+    const dropped = shop("postgres", "public.orders.customer_id", postgresOrders(``));
+    const report = await check(dropped);
+    expect(report.ok).toBe(false);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.entity}`)).toEqual(["WSP093:app"]);
+    expect(report.diagnostics[0]!.message).toBe(
+      "app's link to db output public.orders.customer_id does not resolve: db has no output public.orders.customer_id; its outputs: public.orders, public.orders.amount, public.orders.id",
+    );
+    const cli = await checkExit(dropped);
+    expect(cli.code).not.toBe(0);
+    expect(cli.out).toContain("app's link to db output public.orders.customer_id does not resolve");
+  });
+
+  test("Postgres: a renamed column points the old name at the new one", async () => {
+    const root = shop("postgres", "public.orders.customer_id", postgresOrders(`    buyer_id bigint NOT NULL, -- previously: customer_id`));
+    const [d] = (await check(root)).diagnostics;
+    expect(d?.ruleId).toBe("WSP093");
+    expect(d?.message).toContain("db has no output public.orders.customer_id; it was renamed to public.orders.buyer_id, so link to that instead");
+  });
+
+  test("Postgres: a quoted mixed-case table is a different output, and the hint names it", async () => {
+    const root = shop(
+      "postgres",
+      "public.orders.customer_id",
+      [`import { table } from "@intentius/chant-lexicon-sql/postgres";`, `export const orders = table\`CREATE TABLE "Orders" (customer_id bigint)\`;`, ``].join("\n"),
+    );
+    const [d] = (await check(root)).diagnostics;
+    expect(d?.message).toContain("db has no output public.orders.customer_id; did you mean public.Orders.customer_id? Links match exactly");
+  });
+
+  test("Postgres: a file of tables that does not fold leaves the link unresolved, not missing, and is never run", async () => {
+    const root = shop(
+      "postgres",
+      "public.orders.customer_id",
+      [
+        `import { table } from "@intentius/chant-lexicon-sql/postgres";`,
+        `const name = process.env.ORDERS_TABLE ?? "orders";`,
+        `throw new Error("member code ran");`,
+        `export const orders = table\`CREATE TABLE \${name} (customer_id bigint)\`;`,
+        ``,
+      ].join("\n"),
+    );
+    const report = await check(root);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.map((d) => d.ruleId)).toEqual(["WSP094"]);
+    expect(report.diagnostics[0]!.message).toContain("db/src/orders.ts imports the sql lexicon and does not fold");
+  });
+
+  test("ClickHouse: a link to analytics.events.user_id resolves, and fails check naming the consumer once the column is dropped", async () => {
+    const kept = shop("clickhouse", "analytics.events.user_id", clickhouseEvents(`    user_id UUID,`));
+    const ok = await check(kept);
+    expect(ok.diagnostics).toEqual([]);
+    expect(ok.links.filter((r) => r.origin === "declared")).toMatchObject([{ consumer: "app", producer: "db", output: "analytics.events.user_id", status: "resolved" }]);
+
+    const dropped = shop("clickhouse", "analytics.events.user_id", clickhouseEvents(``));
+    const report = await check(dropped);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.entity}`)).toEqual(["WSP093:app"]);
+    expect(report.diagnostics[0]!.message).toBe(
+      "app's link to db output analytics.events.user_id does not resolve: db has no output analytics.events.user_id; its outputs: analytics.events, analytics.events.kind, analytics.events.ts",
+    );
+    const cli = await checkExit(dropped);
+    expect(cli.code).not.toBe(0);
+    expect(cli.out).toContain("app's link to db output analytics.events.user_id does not resolve");
+  });
+});
+
+describe("files that aren't the member's tables don't hide them (#3941)", () => {
+  const op = (name: string) =>
+    [
+      `import { Op, activity, phase } from "@intentius/chant/op";`,
+      ``,
+      `export const op = Op({ name: "${name}", overview: "${name}", phases: [phase("Run", [activity("run", {})])] });`,
+      ``,
+    ].join("\n");
+
+  test("several Ops exporting `op` in one directory leave the table outputs readable", async () => {
+    const root = repo({
+      "chant.workspace.json": workspace("public.orders.customer_id"),
+      "db/chant.config.ts": config("postgres"),
+      "db/src/orders.ts": postgresOrders(`    customer_id bigint NOT NULL,`),
+      "db/ops/backfill.op.ts": op("backfill"),
+      "db/ops/reindex.op.ts": op("reindex"),
+      "app/README.md": "reads the database\n",
+    });
+    const report = await check(root);
+    expect(report.diagnostics).toEqual([]);
+    expect(report.links.filter((r) => r.origin === "declared")).toMatchObject([{ output: "public.orders.customer_id", status: "resolved" }]);
+  });
+
+  test("with sourceDir set, a sql file outside it that doesn't fold is not read, so a dropped column is missing, not unresolved", async () => {
+    const root = repo({
+      "chant.workspace.json": workspace("public.orders.customer_id"),
+      "db/chant.config.ts": `import type { ChantConfig } from "@intentius/chant";\nexport default { lexicons: ["sql"], sourceDir: "src", sql: { dialect: "postgres" } } satisfies ChantConfig;\n`,
+      "db/src/orders.ts": postgresOrders(""),
+      "db/scripts/seed.ts": `import { readFileSync } from "node:fs";\nimport { table } from "@intentius/chant-lexicon-sql/postgres";\nexport const seeded = table([readFileSync("seed.sql", "utf8")] as unknown as TemplateStringsArray);\n`,
+      "app/README.md": "reads the database\n",
+    });
+    const report = await check(root);
+    expect(report.diagnostics).toMatchObject([{ ruleId: "WSP093" }]);
+    expect(report.links.filter((r) => r.origin === "declared")).toMatchObject([{ output: "public.orders.customer_id", status: "missing" }]);
+  });
+});

package/src/workspace-outputs.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "vitest";
+import { database, table as chTable, view as chView } from "./clickhouse/entities";
+import { schema, table, view } from "./postgres/entities";
+import { sqlWorkspaceOutputs } from "./workspace-outputs";
+
+const names = (entities: Record<string, unknown>) => sqlWorkspaceOutputs(new Map(Object.entries(entities)) as never)?.outputs.map((o) => o.name);
+
+describe("sqlWorkspaceOutputs: Postgres (#3931)", () => {
+  test("an unqualified table is in public, and an unquoted name folds to lower case", () => {
+    expect(names({ orders: table`CREATE TABLE Orders (Customer_ID bigint, amount numeric)` })).toEqual([
+      "public.orders",
+      "public.orders.amount",
+      "public.orders.customer_id",
+    ]);
+  });
+
+  test("a quoted name keeps its case and is a different output", () => {
+    expect(names({ orders: table`CREATE TABLE "Orders" ("CustomerId" bigint)` })).toEqual(["public.Orders", "public.Orders.CustomerId"]);
+  });
+
+  test("a declared schema qualifies the name", () => {
+    const app = schema`CREATE SCHEMA app`;
+    expect(names({ app, users: table`CREATE TABLE ${app}.users (id bigint)` })).toEqual(["app.users", "app.users.id"]);
+  });
+
+  test("a view's columns come from its select list; a * is a gap", () => {
+    const orders = table`CREATE TABLE orders (id bigint, customer_id bigint, amount numeric)`;
+    const totals = view`CREATE VIEW totals AS SELECT customer_id, sum(amount) AS total FROM ${orders} GROUP BY customer_id`;
+    expect(names({ orders, totals })).toContain("public.totals.total");
+    expect(names({ orders, totals })).toContain("public.totals.customer_id");
+
+    const all = view`CREATE MATERIALIZED VIEW everything AS SELECT * FROM ${orders}`;
+    const report = sqlWorkspaceOutputs(new Map<string, unknown>([["orders", orders], ["all", all]]) as never)!;
+    expect(report.outputs.map((o) => o.name)).toContain("public.everything");
+    expect(report.gaps?.join("\n")).toContain("view public.everything (all)");
+  });
+
+  test("a renamed column reports its old name", () => {
+    const report = sqlWorkspaceOutputs(new Map([["orders", table`CREATE TABLE orders (
+      buyer_id bigint -- previously: customer_id
+    )`]]) as never)!;
+    expect(report.outputs.find((o) => o.name === "public.orders.buyer_id")?.previously).toEqual(["public.orders.customer_id"]);
+  });
+
+  test("a file importing the lexicon that did not fold is a gap; other files are not", () => {
+    const report = sqlWorkspaceOutputs(new Map(), [
+      { file: "db/src/a.ts", text: `import { table } from "@intentius/chant-lexicon-sql/postgres";`, reason: "it reads process.env" },
+      { file: "db/src/b.ts", text: `export const x = 1;`, reason: "it does not fold" },
+    ])!;
+    expect(report.outputs).toEqual([]);
+    expect(report.gaps).toEqual(["db/src/a.ts imports the sql lexicon and does not fold, so the tables it declares were not read: it reads process.env"]);
+    expect(sqlWorkspaceOutputs(new Map(), [{ file: "b.ts", text: "", reason: "x" }])).toBeUndefined();
+  });
+});
+
+describe("sqlWorkspaceOutputs: ClickHouse (#3931)", () => {
+  test("an unqualified table is in default, and names keep their case", () => {
+    expect(names({ events: chTable`CREATE TABLE Events (UserId UUID) ENGINE = MergeTree ORDER BY UserId` })).toEqual(["default.Events", "default.Events.UserId"]);
+  });
+
+  test("a declared database qualifies the name; an aliased view's columns are read", () => {
+    const analytics = database`CREATE DATABASE analytics`;
+    const events = chTable`CREATE TABLE ${analytics}.events (ts DateTime, user_id UUID) ENGINE = MergeTree ORDER BY ts`;
+    const daily = chView`CREATE VIEW ${analytics}.daily AS SELECT toDate(ts) AS day, count() AS n FROM ${events} GROUP BY day`;
+    expect(names({ analytics, events, daily })).toEqual([
+      "analytics.daily",
+      "analytics.daily.day",
+      "analytics.daily.n",
+      "analytics.events",
+      "analytics.events.ts",
+      "analytics.events.user_id",
+    ]);
+  });
+
+  test("an unaliased expression in a view's select list is a gap", () => {
+    const events = chTable`CREATE TABLE events (ts DateTime) ENGINE = MergeTree ORDER BY ts`;
+    const mv = chView`CREATE MATERIALIZED VIEW counts ENGINE = MergeTree ORDER BY tuple() AS SELECT count() FROM ${events}`;
+    const report = sqlWorkspaceOutputs(new Map<string, unknown>([["events", events], ["mv", mv]]) as never)!;
+    expect(report.outputs.map((o) => o.name)).toContain("default.counts");
+    expect(report.gaps?.join("\n")).toContain("view default.counts (mv)");
+  });
+});

package/src/workspace-outputs.ts

@@ -0,0 +1,199 @@
+/**
+ * The workspace outputs a sql member exposes (#3931): each table and view,
+ * and each of their columns, as names another member's link may target.
+ *
+ * | Dialect | Relation | Column |
+ * |---|---|---|
+ * | Postgres | `<schema>.<table>` | `<schema>.<table>.<column>` |
+ * | ClickHouse | `<database>.<table>` | `<database>.<table>.<column>` |
+ *
+ * The schema is `public` when the DDL does not qualify the name, and the
+ * database `default`. Views and materialized views are relations too.
+ *
+ * Names are the declared ones, read from the entities the member's source
+ * folds to, never an environment's or a profile's rendering: a member that
+ * renames its database per environment or tenant at deploy time exposes the
+ * same outputs everywhere.
+ *
+ * Identifiers are written unquoted, in the case the dialect keeps:
+ *
+ * - Postgres folds an unquoted identifier to lower case and keeps a quoted
+ *   one exactly, so `CREATE TABLE Orders` is `public.orders` and `CREATE
+ *   TABLE "Orders"` is `public.Orders`, a different output;
+ * - ClickHouse is case-sensitive, so a name is kept as written, quoted or not.
+ *
+ * A link's near-name hint compares names case-insensitively, so a link to
+ * `public.orders` when only `public.Orders` exists is pointed at it.
+ *
+ * A view's columns are its declared column list, or else the names of its
+ * select list (an alias, or the column a bare reference reads). A select
+ * list item with no name chant can derive, or a `*`, leaves the view's
+ * columns incomplete: that is a gap, so a link to one of them is unresolved
+ * rather than missing.
+ *
+ * A `-- previously: <old>` rename hint, on a column's line or before the
+ * CREATE, is reported as the output's previous name, so a link to the old
+ * name says where it went.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { LexiconUnreadSource, LexiconWorkspaceOutput, LexiconWorkspaceOutputs } from "@intentius/chant/graph-ir";
+import { CLICKHOUSE_ENTITY_TYPES, isClickHouseObject, type ColumnDef as ClickHouseColumnDef, type TableProps as ClickHouseTableProps, type ViewProps as ClickHouseViewProps } from "./clickhouse/entities";
+import { canonicalObject } from "./clickhouse/plan/normalize";
+import { isPostgresObject, POSTGRES_ENTITY_TYPES, type TableProps as PostgresTableProps, type ViewProps as PostgresViewProps } from "./postgres/entities";
+import { renameHints } from "./postgres/plan/schema";
+import type { LineageEdge } from "./core/references";
+
+/** The schema an unqualified Postgres name is created in. */
+export const POSTGRES_DEFAULT_SCHEMA = "public";
+/** The database an unqualified ClickHouse name is created in. */
+export const CLICKHOUSE_DEFAULT_DATABASE = "default";
+
+/** A module the sql lexicon's declarations import from. */
+const SQL_MODULE = /from\s+["']@intentius\/chant-lexicon-sql(\/(postgres|clickhouse|sql-files))?["']/;
+
+interface Collected {
+  outputs: Map<string, LexiconWorkspaceOutput>;
+  gaps: string[];
+}
+
+function add(c: Collected, name: string, entity: string, previously: readonly string[] = []): void {
+  const prev = c.outputs.get(name);
+  const before = [...new Set([...(prev?.previously ?? []), ...previously.filter((p) => p !== name)])].sort();
+  c.outputs.set(name, { name, entity: prev?.entity ?? entity, ...(before.length ? { previously: before } : {}) });
+}
+
+/** A relation and its columns, with the rename hints that apply. */
+function addRelation(
+  c: Collected,
+  key: string,
+  qualifier: string,
+  name: string,
+  columns: readonly string[],
+  hints: { previously?: string; columns: Record<string, string> },
+): void {
+  const relation = `${qualifier}.${name}`;
+  // A relation's hint names its old name, bare or qualified.
+  const oldRelation = hints.previously ? (hints.previously.includes(".") ? hints.previously : `${qualifier}.${hints.previously}`) : undefined;
+  add(c, relation, key, oldRelation ? [oldRelation] : []);
+  for (const col of columns) {
+    const prevCol = hints.columns[col];
+    const previously = [
+      ...(prevCol ? [`${relation}.${prevCol}`] : []),
+      ...(oldRelation ? [`${oldRelation}.${col}`, ...(prevCol ? [`${oldRelation}.${prevCol}`] : [])] : []),
+    ];
+    add(c, `${relation}.${col}`, key, previously);
+  }
+}
+
+/** A view's output columns from its select list, and whether they are all known. */
+function lineageColumns(lineage: readonly LineageEdge[], unnamed: (output: string, index: number) => boolean): { columns: string[]; complete: boolean } {
+  const columns: string[] = [];
+  let complete = true;
+  lineage.forEach((e, i) => {
+    if (/(^|\.)\s*\*$/.test(e.expr.trim()) || unnamed(e.output, i + 1)) complete = false;
+    else columns.push(e.output);
+  });
+  return { columns, complete };
+}
+
+function postgres(c: Collected, key: string, e: Declarable): void {
+  const type = e.entityType;
+  if (type === POSTGRES_ENTITY_TYPES.table) {
+    const props = (e as unknown as { props: PostgresTableProps }).props;
+    const schema = props.schema ?? POSTGRES_DEFAULT_SCHEMA;
+    const columns = props.columns.map((col) => col.name);
+    const inherited = (parent: unknown): string[] | undefined =>
+      isPostgresObject(parent) && parent.entityType === POSTGRES_ENTITY_TYPES.table ? (parent.props as PostgresTableProps).columns.map((col) => col.name) : undefined;
+    // A partition takes its parent's columns; INHERITS adds the parents'.
+    if (props.partitionOf !== undefined) {
+      const fromParent = inherited(props.partitionOf);
+      if (fromParent) columns.push(...fromParent.filter((n) => !columns.includes(n)));
+      else c.gaps.push(`table ${schema}.${props.name} (${key}) is a partition of ${String(props.partitionOf)}, which this member does not declare, so its columns are not known`);
+    }
+    for (const parent of props.inherits) {
+      const fromParent = inherited(parent);
+      if (fromParent) columns.push(...fromParent.filter((n) => !columns.includes(n)));
+      else c.gaps.push(`table ${schema}.${props.name} (${key}) inherits ${String(parent)}, which this member does not declare, so its columns are not all known`);
+    }
+    if (props.ofType !== undefined) {
+      const attrs = isPostgresObject(props.ofType) ? (props.ofType.props as { attributes?: { name: string }[] }).attributes : undefined;
+      if (attrs) columns.push(...attrs.map((a) => a.name).filter((n) => !columns.includes(n)));
+      else c.gaps.push(`table ${schema}.${props.name} (${key}) is OF ${String(props.ofType)}, which this member does not declare, so its columns are not known`);
+    }
+    if (props.like.length > 0) c.gaps.push(`table ${schema}.${props.name} (${key}) copies columns with LIKE, which are not read`);
+    addRelation(c, key, schema, props.name, columns, renameHints(props.ddl));
+    return;
+  }
+  if (type === POSTGRES_ENTITY_TYPES.view || type === POSTGRES_ENTITY_TYPES.materializedView) {
+    const props = (e as unknown as { props: PostgresViewProps }).props;
+    const schema = props.schema ?? POSTGRES_DEFAULT_SCHEMA;
+    let columns = [...props.columns];
+    if (columns.length === 0) {
+      const derived = lineageColumns(props.lineage, (output) => output === "?column?");
+      columns = derived.columns;
+      if (!derived.complete) c.gaps.push(`view ${schema}.${props.name} (${key}) has a select list item whose name can't be read without a server (a * or an unnamed expression), so its columns are not all known`);
+    }
+    addRelation(c, key, schema, props.name, columns, renameHints(props.ddl));
+  }
+}
+
+function clickhouseHints(ddl: string): { previously?: string; columns: Record<string, string> } {
+  try {
+    const o = canonicalObject(ddl, CLICKHOUSE_DEFAULT_DATABASE);
+    const columns: Record<string, string> = {};
+    for (const col of o.columns) if (col.previously) columns[col.name] = col.previously;
+    return { ...(o.previously ? { previously: o.previously } : {}), columns };
+  } catch {
+    return { columns: {} };
+  }
+}
+
+function clickhouse(c: Collected, key: string, e: Declarable): void {
+  const type = e.entityType;
+  if (type === CLICKHOUSE_ENTITY_TYPES.table) {
+    const props = (e as unknown as { props: ClickHouseTableProps }).props;
+    const database = props.database ?? CLICKHOUSE_DEFAULT_DATABASE;
+    if (props.columns.length === 0) c.gaps.push(`table ${database}.${props.name} (${key}) declares no columns, so the server's are not known`);
+    addRelation(c, key, database, props.name, props.columns.map((col: ClickHouseColumnDef) => col.name), clickhouseHints(props.ddl));
+    return;
+  }
+  if (type === CLICKHOUSE_ENTITY_TYPES.view || type === CLICKHOUSE_ENTITY_TYPES.materializedView) {
+    const props = (e as unknown as { props: ClickHouseViewProps }).props;
+    const database = props.database ?? CLICKHOUSE_DEFAULT_DATABASE;
+    let columns = props.columns.map((col: ClickHouseColumnDef) => col.name);
+    if (columns.length === 0) {
+      const derived = lineageColumns(props.lineage, (output, n) => output === `_${n}`);
+      columns = derived.columns;
+      if (!derived.complete) c.gaps.push(`view ${database}.${props.name} (${key}) has a select list item whose name can't be read without a server (a * or an unaliased expression), so its columns are not all known`);
+    }
+    addRelation(c, key, database, props.name, columns, clickhouseHints(props.ddl));
+  }
+}
+
+/**
+ * The `workspaceOutputs` hook: every table and view the entities declare,
+ * and their columns. `unread` names the member's files that did not fold;
+ * one that imports the sql lexicon may declare tables, so it is a gap.
+ */
+export function sqlWorkspaceOutputs(entities: ReadonlyMap<string, Declarable>, unread: readonly LexiconUnreadSource[] = []): LexiconWorkspaceOutputs | undefined {
+  const c: Collected = { outputs: new Map(), gaps: [] };
+  let any = false;
+  for (const [key, e] of entities) {
+    if (isPostgresObject(e)) {
+      any = true;
+      postgres(c, key, e);
+    } else if (isClickHouseObject(e)) {
+      any = true;
+      clickhouse(c, key, e);
+    }
+  }
+  for (const u of unread) {
+    if (!SQL_MODULE.test(u.text)) continue;
+    any = true;
+    c.gaps.push(`${u.file} imports the sql lexicon and does not fold, so the tables it declares were not read: ${u.reason}`);
+  }
+  if (!any) return undefined;
+  const outputs = [...c.outputs.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { outputs, ...(c.gaps.length ? { gaps: c.gaps } : {}) };
+}

package/workspace-kinds.json

@@ -0,0 +1,30 @@
+{
+  "$comment": "Member kinds this lexicon supplies to a chant workspace (#3932). chant reads this file as data and never imports the lexicon. A dbt project reads the tables a sql member declares, so its kind ships beside them. Its reader, dbt-project, is chant's own code: it parses dbt_project.yml and the sources YAML under the model paths, never runs dbt, never renders Jinja and never reads profiles.yml, and turns each source table and column into a link to the sql member's <schema>.<table> and <schema>.<table>.<column> outputs (#3931).",
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "dbt",
+      "description": "a dbt project, with a dbt_project.yml in its directory; its sources link to the tables and columns a sql member declares, and dbt is never run",
+      "precedence": 300,
+      "probe": {
+        "anyFile": [
+          "dbt_project.yml"
+        ]
+      },
+      "reader": "dbt-project",
+      "fields": {
+        "sqlMember": {
+          "type": "string",
+          "description": "The member whose tables the project's sources read. Unset, each source table links to the one member that exposes it, and a table two members expose is ambiguous (WSP095).",
+          "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
+        },
+        "dialect": {
+          "type": "string",
+          "description": "How source names are cased before they are matched: postgres folds an unquoted name to lowercase and keeps a quoted one as written, the way dbt-postgres quotes a source's schema and identifier unless quoting turns it off; clickhouse keeps every name as written.",
+          "default": "postgres",
+          "pattern": "^(postgres|clickhouse)$"
+        }
+      }
+    }
+  ]
+}