@intentius/chant-lexicon-sql 0.124.14 → 0.124.16

package/src/composites/tenant-table.ts

@@ -11,6 +11,8 @@
 
 import { Composite } from "@intentius/chant/composite";
 import { index, table, type PostgresIndex, type PostgresSchema, type PostgresTable } from "../postgres/entities";
+import type { PostgresMemberName } from "../core/typed";
+import type { Instance, TypedComposite } from "./typed";
 
 export interface TenantTableProps {
   /** The table's name, unqualified. The index is `<name>_tenant_idx`. */
@@ -29,13 +31,18 @@ export interface TenantTableProps {
   tenantType?: string;
 }
 
-export type TenantTableMembers = {
-  table: PostgresTable;
+/** `Table` is the table's qualified name, when the call's props give it (chant#3787). */
+export type TenantTableMembers<Table extends string = string> = {
+  table: PostgresTable<Table>;
   index: PostgresIndex;
 };
 
+type TenantTableCall = <const N extends string, const S extends PostgresSchema | string = "public">(
+  props: TenantTableProps & { name: N; schema?: S },
+) => Instance<TenantTableMembers<PostgresMemberName<S, N>>>;
+
 /** A multi-tenant table with the tenant key first in its primary key and its index. */
-export const TenantTable = Composite<TenantTableProps, TenantTableMembers>((props) => {
+export const TenantTable = Composite<TenantTableProps, TenantTableMembers, TypedComposite<TenantTableProps, TenantTableMembers, TenantTableCall>>((props) => {
   const schema = props.schema ?? "public";
   const tenant = props.tenant ?? "tenant_id";
   const rows = table`

package/src/composites/typed.ts

@@ -0,0 +1,15 @@
+/**
+ * chant#3787 — the call signature a composite is typed with, so a member's
+ * `.columns` are the generated `SqlSchema` entry for the name its props give
+ * it. `users.table.columns.emial` then fails tsc as `table<"app.users">`'s
+ * would. The definition is unchanged at run time: `Composite`'s third type
+ * argument carries this signature in front of the plain one.
+ */
+
+import type { CompositeDefinition, CompositeFactoryMembers, CompositeInstance } from "@intentius/chant/composite";
+
+/** What a typed composite call returns: the instance, with its members' types. */
+export type Instance<M extends CompositeFactoryMembers> = CompositeInstance<M> & M;
+
+/** A composite definition whose precise, generic `Call` signature is tried before the plain `(props: P) => M`. */
+export type TypedComposite<P, M extends CompositeFactoryMembers, Call> = Call & CompositeDefinition<P, M>;

package/src/core/typed.ts

@@ -109,6 +109,46 @@ export type RowIn<Registry, T> = T extends string
   ? RowFromColumns<ColumnsIn<Registry, T>>
   : T extends Named<infer N> ? RowFromColumns<ColumnsIn<Registry, N>> : never;
 
+// ── Composite members ───────────────────────────────────────────────────
+
+/** Whether `S` is a name the type system knows: a literal, not `string` and not {@link Unnamed}. */
+type Known<S> = [S] extends [Unnamed] ? false : string extends S ? false : true;
+
+/** A piece of a name a composite's props give: the literal, the name a {@link Named} entity carries, or {@link Unnamed}. */
+type NamePiece<V> = [V] extends [string]
+  ? Known<V> extends true ? V : Unnamed
+  : [V] extends [Named<infer N>] ? (Known<N> extends true ? N : Unnamed) : Unnamed;
+
+/**
+ * chant#3787 — the qualified name of a relation a Postgres composite declares
+ * as `${schema}.${name}${suffix}`: `schema` is the composite's `schema` prop (a
+ * string, or a schema whose tag was given its name, `schema<"app">`), `name`
+ * its `name` prop. Postgres folds both, as the build does. {@link Unnamed},
+ * so the columns stay unchecked, when either piece is not a known literal.
+ */
+export type PostgresMemberName<Schema, Name, Suffix extends string = ""> = [NamePiece<Schema>, NamePiece<Name>] extends [
+  infer S extends string,
+  infer N extends string,
+]
+  ? Known<S> extends true
+    ? Known<N> extends true
+      ? `${Lowercase<S>}.${Lowercase<N>}${Suffix}`
+      : Unnamed
+    : Unnamed
+  : Unnamed;
+
+/**
+ * chant#3787 — the name of a relation a ClickHouse composite declares,
+ * `${name}${suffix}`, where `name` is its `name` prop as written (`events` or
+ * `analytics.events`). ClickHouse does not fold names. {@link Unnamed} when
+ * the name is not a known literal.
+ */
+export type ClickHouseMemberName<Name, Suffix extends string = ""> = NamePiece<Name> extends infer N extends string
+  ? Known<N> extends true
+    ? `${N}${Suffix}`
+    : Unnamed
+  : Unnamed;
+
 // ── The slot record ─────────────────────────────────────────────────────
 
 /**

package/src/lint/rules/sqlpg005.ts

@@ -1,7 +1,7 @@
 import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
 import { parseStatements, SqlSyntaxError } from "../../postgres/parser";
 import { findPostgresTemplates, postgresTokensOf } from "./postgres-templates";
-import { declaredText, generatedNamesFor, nameAgrees, normalizedName, SQL_TYPES_FILE, typeArgumentName } from "./typed-names";
+import { declaredText, generatedNamesFor, nameAgrees, normalizedName, splitQualified, SQL_TYPES_FILE, typeArgumentName } from "./typed-names";
 
 const MODULE = "@intentius/chant-lexicon-sql/postgres";
 
@@ -19,6 +19,11 @@ const MODULE = "@intentius/chant-lexicon-sql/postgres";
  * generated file, only the first check runs. A name missing from the file is
  * a warning, since a table added since the last `chant sql types` is stale
  * and `chant sql types --check` is what fails on it.
+ *
+ * chant#3787: `schema<"app">\`CREATE SCHEMA app\`` is read too, since a
+ * composite placed in the schema builds its members' qualified names from
+ * that argument. A schema is not in the generated file, so only the name
+ * comparison runs, and the argument is the schema's own name, one piece.
  */
 export const sqlpg005: LintRule = {
   id: "SQLPG005",
@@ -31,7 +36,7 @@ export const sqlpg005: LintRule = {
     const out: LintDiagnostic[] = [];
     let listed: Set<string> | undefined | null = null;
     for (const found of findPostgresTemplates(source)) {
-      if (found.tag !== "table" && found.tag !== "view") continue;
+      if (found.tag !== "table" && found.tag !== "view" && found.tag !== "schema") continue;
       const arg = typeArgumentName(found.node);
       if (!arg) continue;
       const at = (() => {
@@ -42,12 +47,14 @@ export const sqlpg005: LintRule = {
       try {
         const node = parseStatements(postgresTokensOf(found))[0];
         if (node && (node.statement === "table" || node.statement === "view")) declared = node.name.pieces;
+        else if (node && node.statement === "schema" && found.tag === "schema") declared = node.name?.pieces;
       } catch (err) {
         if (err instanceof SqlSyntaxError) continue; // SQLPG001 reports it
         throw err;
       }
       if (!declared) continue; // SQLPG001: the tag holds another statement
-      if (!nameAgrees(declared, arg.name)) {
+      const agrees = found.tag === "schema" ? splitQualified(arg.name).length === 1 && nameAgrees(declared, arg.name) : nameAgrees(declared, arg.name);
+      if (!agrees) {
         out.push({
           ruleId: "SQLPG005",
           severity: "error",
@@ -57,6 +64,7 @@ export const sqlpg005: LintRule = {
         });
         continue;
       }
+      if (found.tag === "schema") continue;
       if (listed === null) listed = generatedNamesFor(context.filePath, MODULE);
       if (listed && !listed.has(normalizedName(arg.name))) {
         out.push({

package/src/lint/rules/typed-names.test.ts

@@ -113,6 +113,18 @@ describe("SQLPG005: a typed Postgres tag's type argument", () => {
     const code = `${PGX}export const o = table<"shop.orders">\`CREATE TABLE shop.orders (id bigint)\`;`;
     expect(sqlpg005.check(ctx(code, file))).toEqual([]);
   });
+
+  // chant#3787 — a composite builds its members' names from the schema's type argument.
+  test("a schema's type argument must be its name, and is not looked for in the generated file", () => {
+    const SCX = `import { schema } from "${PG}";\n`;
+    const file = project(PG, ["shop.orders"]);
+    expect(sqlpg005.check(ctx(`${SCX}export const s = schema<"shop">\`CREATE SCHEMA Shop\`;`, file))).toEqual([]);
+    const [d, ...rest] = sqlpg005.check(ctx(`${SCX}export const s = schema<"shp">\`CREATE SCHEMA shop\`;`, file));
+    expect(rest).toEqual([]);
+    expect(d).toMatchObject({ ruleId: "SQLPG005", severity: "error", line: 2 });
+    expect(sqlpg005.check(ctx(`${SCX}export const s = schema<"x.shop">\`CREATE SCHEMA shop\`;`))).toHaveLength(1);
+    expect(sqlpg005.check(ctx(`${SCX}export const s = schema\`CREATE SCHEMA shop\`;`))).toEqual([]);
+  });
 });
 
 describe("SQLCH004: a typed ClickHouse tag's type argument", () => {

package/src/op/activities/clickhouse-rebuild.ts

@@ -34,6 +34,9 @@ import type { ClickHouseRebuildArgs } from "../../clickhouse/rebuild/op";
 import { CLASSIFIER_RULES } from "../../clickhouse/plan/rules";
 import { clusterSharding } from "../../clickhouse/rebuild/shards";
 import { resolveMarker } from "./clickhouse-apply";
+import { statementChange, type StatementChange } from "../../core/statements";
+import { clickhouseRebuildPart } from "../../change-set";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
 
 export type { ClickHouseRebuildArgs } from "../../clickhouse/rebuild/op";
 
@@ -104,6 +107,10 @@ export interface RebuildPlanResult {
   planDigest?: string;
   /** Each classified change, as `<rule> <field>: <before> -> <after>`. */
   changes: string[];
+  /** The same changes, structured. */
+  classified: StatementChange[];
+  /** The plan as a change-set part (#3767), member the table: what `composeChangeSet` takes, and a gate's Cedar `context.plan`. */
+  part: ChangeSetPart;
   summary: string;
 }
 
@@ -125,7 +132,10 @@ async function plan(args: ClickHouseRebuildArgs, signal: AbortSignal | undefined
         : `${o.names.key} holds its declaration; nothing to rebuild`;
   run.log(`-- ${summary}`);
   for (const c of changes) run.log(`--   ${c}`);
-  return { state: o.state, table: o.names.key, ...(o.state === "rebuild" ? { planDigest: rebuildPlanDigest(o, run.dualWrite) } : {}), changes, summary };
+  const classified = o.changes.map(statementChange);
+  const result = { state: o.state, table: o.names.key, ...(o.state === "rebuild" ? { planDigest: rebuildPlanDigest(o, run.dualWrite) } : {}), changes, classified };
+  const part = clickhouseRebuildPart({ member: o.names.key, plan: result, ...(args.environment !== undefined ? { environment: args.environment } : {}) });
+  return { ...result, part, summary };
 }
 
 export async function clickhouseRebuildCreate(args: ClickHouseRebuildArgs, signal?: AbortSignal, deps: ClickHouseRebuildDeps = {}): Promise<CreateResult> {

package/src/op/activities/postgres-migration.ts

@@ -39,6 +39,9 @@ import {
 import { DEFAULT_REPLICATION_LAG } from "../../postgres/migrate/replication";
 import type { PostgresMigrationArgs } from "../../postgres/migrate/op";
 import { buildMajor } from "./postgres-apply";
+import { statementChange, type StatementChange } from "../../core/statements";
+import { postgresMigrationPart } from "../../change-set";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
 
 export type { PostgresMigrationArgs } from "../../postgres/migrate/op";
 
@@ -137,6 +140,10 @@ export interface MigrationPlanResult {
   planDigest?: string;
   /** Each classified change, as `<rule> <field>: <before> -> <after>`. */
   changes: string[];
+  /** The same changes, structured. */
+  classified: StatementChange[];
+  /** The plan as a change-set part (#3767), member the migration (`schema.table.column`): what `composeChangeSet` takes, and a gate's Cedar `context.plan`. */
+  part: ChangeSetPart;
   summary: string;
 }
 
@@ -164,7 +171,10 @@ export async function postgresMigrationPlan(args: PostgresMigrationArgs, signal?
           : `${n.key} holds its declaration; nothing to migrate`;
     run.log(`-- ${summary}`);
     for (const c of changes) run.log(`--   ${c}`);
-    return { state: o.state, migration: n.key, change: n.change, ...(o.state === "migrate" ? { planDigest: migrationPlanDigest(o) } : {}), changes, summary };
+    const classified = o.changes.map(statementChange);
+    const result = { state: o.state, migration: n.key, change: n.change, ...(o.state === "migrate" ? { planDigest: migrationPlanDigest(o) } : {}), changes, classified };
+    const part = postgresMigrationPart({ member: n.key, plan: result, ...(args.environment !== undefined ? { environment: args.environment } : {}) });
+    return { ...result, part, summary };
   });
 }
 

package/src/op/activity-contracts.ts

@@ -39,12 +39,16 @@ const rebuildArgs = z.strictObject({
 });
 
 const state = z.enum(["rebuild", "swapped", "done"]);
+
+/** A plan step's structured changes and its change-set part (#3767), as `../change-set.ts` makes it. */
+const classified = z.array(z.object({ rule: z.string(), class: z.string(), field: z.string() }).passthrough());
+const part = z.object({ member: z.object({ member: z.string(), planner: z.literal("sql"), planDigest: z.string().nullable() }).passthrough(), entries: z.array(z.unknown()) });
 const tableEntity = { entities: ["table"] };
 
 export const clickhouseRebuildPlanContract = activityContract(
   "clickhouseRebuildPlan",
   rebuildArgs,
-  z.object({ state, table: z.string(), planDigest: z.string().optional(), changes: z.array(z.string()), summary: z.string() }),
+  z.object({ state, table: z.string(), planDigest: z.string().optional(), changes: z.array(z.string()), classified, part, summary: z.string() }),
   tableEntity,
 );
 
@@ -136,7 +140,7 @@ const migrationState = z.enum(["migrate", "switched", "done"]);
 export const postgresMigrationPlanContract = activityContract(
   "postgresMigrationPlan",
   migrationArgs,
-  z.object({ state: migrationState, migration: z.string(), change: z.enum(["rename", "type"]), planDigest: z.string().optional(), changes: z.array(z.string()), summary: z.string() }),
+  z.object({ state: migrationState, migration: z.string(), change: z.enum(["rename", "type"]), planDigest: z.string().optional(), changes: z.array(z.string()), classified, part, summary: z.string() }),
   tableEntity,
 );
 

package/src/postgres/entities.ts

@@ -434,7 +434,12 @@ export abstract class PostgresObject extends SqlObject {
   declare readonly sqlName: string;
 }
 
-export interface PostgresSchema extends PostgresObject {
+/**
+ * A schema. `N` is its name when its tag was given one
+ * (`` schema<"shop">`CREATE SCHEMA shop` ``), which is how a composite placed
+ * in it knows its members' qualified names (chant#3787).
+ */
+export interface PostgresSchema<N extends string = string> extends PostgresObject, Named<N> {
   readonly entityType: "Postgres::Schema";
   readonly props: SchemaProps;
 }
@@ -1601,9 +1606,13 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
   }
 }
 
-/** `` schema`CREATE SCHEMA ...` ``: one Postgres schema, parsed at build time. */
-export function schema(strings: TemplateStringsArray, ...values: unknown[]): PostgresSchema {
-  return build("schema", strings, values) as PostgresSchema;
+/**
+ * `` schema`CREATE SCHEMA ...` ``: one Postgres schema, parsed at build time.
+ * Given its name as the type argument (`` schema<"shop">`...` ``), a composite
+ * placed in it types its members' columns (chant#3787).
+ */
+export function schema<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: unknown[]): PostgresSchema<N> {
+  return build("schema", strings, values) as PostgresSchema<N>;
 }
 
 /**

package/src/typed-columns.e2e.test.ts

@@ -89,4 +89,21 @@ describe("chant sql types, through tsc", () => {
       expect.stringMatching(/^src\/by-country\.ts\(7\): TS2345 Argument of type 'Column<"Nullable\(String\)", .*' is not assignable to parameter of type 'NotNullColumn'/),
     ]);
   }, 120_000);
+
+  // chant#3787 — a composite's members are typed from the names its props give
+  // them: `schema<"app">` or a schema by name, and the `name` prop, Postgres
+  // folding both. A name or schema the type system cannot read stays unchecked.
+  test("Postgres composites: a misspelled column on a member fails; every member's row is its generated entry's", async () => {
+    const dir = join(fixtures, "postgres-composites");
+    expect(await rendered(dir)).toBe(readFileSync(join(dir, "src", SQL_TYPES_FILE), "utf8"));
+    expect(tscErrors(dir)).toEqual([
+      expect.stringMatching(/^checks\/misspelled\.ts\(4\): TS2551 Property 'emial' does not exist .* Did you mean 'email'\?$/),
+    ]);
+  }, 120_000);
+
+  test("ClickHouse composites: a misspelled column on a member fails; every member's row is its generated entry's", async () => {
+    const dir = join(fixtures, "clickhouse-composites");
+    expect(await rendered(dir)).toBe(readFileSync(join(dir, "src", SQL_TYPES_FILE), "utf8"));
+    expect(tscErrors(dir)).toEqual([expect.stringMatching(/^checks\/rows\.ts\(12\): TS2339 Property 'knid' does not exist on type/)]);
+  }, 120_000);
 });