@quereus/quereus 4.7.0 → 4.9.0

package/dist/src/schema/rename/column-rename.d.ts

@@ -0,0 +1,228 @@
+import type * as AST from '../../parser/ast.js';
+import { type ResolveColumnInSource, type ResolveObjectRef, type RowImageContext } from './shared.js';
+/**
+ * Rewrite column references inside a full statement/expression AST, resolving
+ * unqualified refs against the FROM scopes the walk descends (no implicit seed,
+ * unlike {@link renameColumnInCheckExpression}). The walk descends a select
+ * body's trailing `with defaults (…)` clause ({@link AST.SelectStmt.defaults}),
+ * whose entry exprs evaluate in the body's FROM scope.
+ *
+ * `rowImage` says what a bare, unbound `new.` / `old.` qualifier means in the
+ * walked expression — independent of the (absent) seed; see
+ * {@link RowImageContext} and {@link matchesRowImage}. A view / assertion body
+ * is `'none'` (no written-row context — `new.x` is an ordinary table
+ * reference); another table's CHECK / DEFAULT / generated body is `'foreign'`
+ * (written-row context whose image belongs to that table, so the qualifier
+ * names nothing this walk cares about).
+ *
+ * When `resolveColumnInSource` is supplied, the scope walk consults it at each
+ * inner FROM frame so an unqualified ref that legitimately binds to a like-named
+ * column on a subquery's own FROM source is NOT false-captured by an enclosing
+ * binding (e.g. a `with defaults` expr `cap + (select max(cap) from lim)` under
+ * a `t.cap` rename must leave the inner `lim.cap` untouched). The same callback
+ * infrastructure backs {@link renameColumnInCheckExpression}; both the forward
+ * propagation (live schema lookup) and the differ's inverse reconcile
+ * (declared-side resolver) pass it so the two stay in parity.
+ */
+export declare function renameColumnInAst(node: AST.AstNode | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, rowImage: RowImageContext, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Rewrite a column reference inside a CHECK expression. Unlike
+ * `renameColumnInAst`, this entry point seeds the scope stack with an
+ * implicit unaliased binding to `tableName` so top-level unqualified
+ * `ColumnExpr` nodes resolve to the owning table. CHECK expressions
+ * cannot reference other tables at top level, so the implicit binding
+ * is safe there.
+ *
+ * When `resolveColumnInSource` is supplied, the scope walk consults it at
+ * each inner FROM frame: if any real-table source in that frame exposes
+ * `oldColName`, the unqualified ref binds inside the subquery and the
+ * walk stops before reaching the seed. This stops the rewriter from
+ * false-positively rewriting an inner unqualified ref that legitimately
+ * binds to a like-named column on the subquery's FROM (e.g.
+ * `check ((select min(v) from u) > 0)` when `u` also has a `v` column).
+ *
+ * Limitation: subquery / function-source inner sources are not asked (the
+ * rewriter would need recursive column-set inference on their bodies), so an
+ * unqualified ref binding only through one of those falls through to the seed.
+ * An ALIASED real source is asked like any other — an alias adds a qualifier,
+ * it does not take the source's columns out of scope. `renameColumnInAst`
+ * shares the same callback (passed by the view-body callers) and the same
+ * residual.
+ *
+ * The seed and the `new.` / `old.` **row-image** namespace are INDEPENDENT: the
+ * seed answers how *unqualified* refs bind, while the explicit `rowImage`
+ * argument answers what a bare, unbound `new.` / `old.` qualifier names (see
+ * {@link RowImageContext}). A CHECK / DEFAULT / generated body of the renamed
+ * table itself passes `'own'` — those expressions evaluate against the row
+ * being written, so `check (new.a > 0)` (`docs/sql-ddl.md` § CHECK Constraints)
+ * names the owning table's row image and matches. A partial-index predicate is
+ * seeded too but passes `'none'`: it describes rows already stored, with no
+ * written-row context.
+ *
+ * The `'own'` match is scope-**aware**, not depth-blind, because `new` and `old`
+ * are not reserved words in this parser: `create table "new" (…)` is legal, so a
+ * CHECK may legitimately contain `(select max("new".a) from "new")`. The match
+ * therefore requires that no FROM/WITH frame above the seed rebind the
+ * qualifier — see `matchesRowImage`.
+ */
+export declare function renameColumnInCheckExpression(expr: AST.AstNode | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, rowImage: RowImageContext, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Sentinel rename target for the read-only column probes: the two below, and
+ * the drop verb's republication fixpoint
+ * (`schema/column-republication.ts`), which probes exposure the same way. No
+ * user column can hold this name, and the probe rewrites *to* it, so it can
+ * never collide with anything the walk is looking for.
+ */
+export declare const PROBE_COLUMN_NAME = "__quereus_column_probe__";
+/**
+ * Whether `node` refers to `tableName`.`columnName` — read-only with respect to
+ * the caller's AST; a throwaway {@link spineCloneAst} copy is what gets
+ * rewritten.
+ *
+ * Same equivalence {@link tableReferencedInAst} establishes for the table verb,
+ * and for the same reason: "refers to" must mean "would have been rewritten by
+ * `ALTER TABLE … RENAME COLUMN`", or a DROP guard built on it refuses a
+ * different set of cases than the rename follows. See that function's comment
+ * for why the column verb reaches it by clone+sentinel rather than by `dryRun`.
+ *
+ * `resolveColumnInSource` is **not optional in practice**: without it the walk
+ * has no way to tell that an unqualified ref inside a subquery binds to a
+ * like-named column on the subquery's own FROM source, and a caller asking
+ * "does this body name `t.v`?" gets `true` for a body whose only `v` is
+ * another table's. Every caller should pass the catalog-backed resolver
+ * (`buildColumnSourceResolver`).
+ *
+ * NOTE: one spine clone plus one walk per probe, and the DROP COLUMN guard probes every
+ * live assertion. Trivial at the handful-of-assertions scale schemas have today, and it
+ * only runs on DDL; if a schema ever carries assertions by the hundred, filter by
+ * `tableReferencedInAst` (no clone) before paying for the column probe.
+ */
+export declare function columnReferencedInAst(node: AST.AstNode | undefined, tableName: string, columnName: string, resolve: ResolveObjectRef, targetKey: string, rowImage: RowImageContext, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * {@link columnReferencedInAst} for an expression that resolves unqualified refs
+ * against an implicit binding to `tableName` — a CHECK expression or a
+ * partial-index predicate. Uses {@link renameColumnInCheckExpression}'s seeded
+ * entry point so the probe answers for exactly the scope that expression is
+ * planned in.
+ */
+export declare function columnReferencedInCheckExpression(expr: AST.AstNode | undefined, tableName: string, columnName: string, resolve: ResolveObjectRef, targetKey: string, rowImage: RowImageContext, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Rewrite the renamed column inside every partial-index predicate of `indexes`,
+ * in place. A predicate resolves unqualified refs against the indexed table
+ * itself — the same implicit seed a CHECK expression uses — so
+ * {@link renameColumnInCheckExpression} is the correct entry point here, not
+ * {@link renameColumnInAst}.
+ *
+ * The predicate `Expression` is shared by reference between the catalog's
+ * `TableSchema`, any module-local copy of it, and — for a unique partial index —
+ * the `derivedFromIndex` UNIQUE constraint that carries the same predicate.
+ * Rewriting in place keeps all of them in step; cloning would strand the derived
+ * constraint on the old AST.
+ *
+ * Idempotent: once rewritten, nothing names `oldColName` any more, so a second
+ * call with the same pair returns false without touching the AST.
+ *
+ * The parameter is structurally typed rather than `IndexSchema[]` so this module
+ * stays free of catalog imports; `IndexSchema` satisfies it.
+ *
+ * Row-image mode is `'none'`: a partial-index predicate describes rows already
+ * stored, so it has no written-row context and a bare `new.` / `old.` qualifier
+ * there is an ordinary table reference — the same asymmetry
+ * {@link import('./table-rename.js').renameTableInIndexPredicates} records by
+ * passing no `rowImageContext`. (An indexed table literally named `new` still
+ * matches through the seed binding, so this changes no answer for the case
+ * that plans.)
+ */
+export declare function renameColumnInIndexPredicates(indexes: ReadonlyArray<{
+    readonly predicate?: AST.Expression;
+}> | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Rewrite the renamed column inside every CHECK constraint expression of `checks`
+ * belonging to the renamed table itself, in place. The seeded-scope entry point
+ * applies for the same reason it does for a partial-index predicate: a CHECK
+ * resolves unqualified refs against its owning table.
+ *
+ * Only pass the renamed table's OWN checks — a CHECK on a *different* table that
+ * happens to reference the renamed table needs {@link renameColumnInAst}, whose
+ * walk has no implicit seed. That own-table contract is also why the row-image
+ * mode is hardcoded `'own'` here: a CHECK evaluates against the row being
+ * written, whose image IS the renamed table's.
+ */
+export declare function renameColumnInCheckConstraints(checks: ReadonlyArray<{
+    readonly expr: AST.Expression;
+}> | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Rewrite the renamed column inside the two expressions a `ColumnSchema` can carry —
+ * a column DEFAULT (`b integer default (new.a + 1)`, however authored: inline, or via
+ * `ALTER TABLE … ALTER COLUMN … SET DEFAULT`, which writes the same field) and a
+ * generated column's body (`g integer generated always as (a + 1)`) — in place, for
+ * every column of the renamed table itself.
+ *
+ * The seeded {@link renameColumnInCheckExpression} entry point with row-image mode
+ * `'own'` is correct for both:
+ *
+ * - The implicit unaliased binding to the owning table is what makes a generated
+ *   column's **bare** `a` resolve — it has no FROM clause to bind against, exactly like
+ *   a CHECK.
+ * - The `'own'` mode is what makes a default's `new.a` resolve. A default is evaluated
+ *   against the row being written, so that qualifier names this table's row image, not
+ *   anything a FROM binds.
+ *
+ * Case folding (`NEW.A`) and the shadowing edge (a real table literally named `new`,
+ * reached from a subquery inside the expression) therefore behave exactly as they do for
+ * a CHECK, because the same walk decides all three.
+ *
+ * Only pass the renamed table's OWN columns. A default on a *different* table can reach
+ * this table only through a subquery, so an unqualified ref there must bind inside that
+ * subquery's FROM — that caller wants {@link renameColumnInAst}, whose walk has no seed.
+ *
+ * Same sharing and idempotence story as {@link renameColumnInCheckConstraints}: a
+ * module's rename hook rebuilds only the renamed column's `ColumnSchema` and keeps every
+ * other one by reference, and even the rebuilt one carries the SAME expression nodes
+ * (`buildConstraintsFromColumn` passes them into the reconstructed `ColumnDef` by
+ * reference and `columnDefToSchema` assigns them straight back), so one in-place rewrite
+ * reaches every holder and a second call with the same pair is a no-op.
+ *
+ * The parameter is structurally typed rather than `ColumnSchema[]` so this module stays
+ * free of catalog imports; `ColumnSchema` satisfies it.
+ */
+export declare function renameColumnInColumnExpressions(columns: ReadonlyArray<{
+    readonly defaultValue?: AST.Expression | null;
+    readonly generatedExpr?: AST.Expression;
+}> | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Whether `body`'s top-level result columns publish the renamed column under
+ * `newColName` — i.e. whether rewriting this body shifted the name its readers
+ * see. Call AFTER the body rewrite: the predicate compares against the NEW
+ * name, exactly as the CTE exposure analysis it shares its internals with
+ * ({@link cteExposesRenamedColumn} / `isResultColumnExposure`). An explicit
+ * result-column alias suppresses exposure; a bare projection of the renamed
+ * column, or a `*` / `t.*` / `a.*` whose frame binds the target, exposes it —
+ * a FROM alias is no obstacle, since it only changes which qualifier names the
+ * source.
+ *
+ * An explicit view / materialized-view column list pins the published names
+ * regardless of the body — that guard belongs at the call site
+ * (`ViewSchema.columns` / `TableDerivation.columns` play the role
+ * `cte.columns` plays inside the CTE analysis; this predicate never sees them).
+ */
+export declare function bodyExposesRenamedColumn(body: AST.QueryExpr | undefined, tableName: string, oldColName: string, newColName: string, resolve: ResolveObjectRef, targetKey: string, resolveColumnInSource?: ResolveColumnInSource): boolean;
+/**
+ * Whether `body`'s top-level result columns publish a column named
+ * `columnName`, from ANY origin: an explicit alias, an unaliased bare
+ * projection of a column so named (wherever it binds), or a `*` / `t.*` whose
+ * bound real-table source exposes it (asked through `resolveColumnInSource`).
+ *
+ * The collision half of the rename-cascade pre-flight
+ * (`runtime/emit/column-rename-cascade.ts`): run against the PRISTINE
+ * (pre-rewrite) body with `columnName = newCol` — the rename target cannot
+ * publish `newCol` before the rename, so anything found is necessarily a
+ * DIFFERENT column the shifted name would collide with.
+ *
+ * Shares the walker's scope residual: a `*` over a subquery or function source
+ * has no askable column set, so a publication arriving only that way is not
+ * seen. A `*` over an aliased REAL source is seen — the alias binds like any
+ * other qualifier.
+ */
+export declare function bodyPublishesColumnNamed(body: AST.QueryExpr | undefined, columnName: string, resolve: ResolveObjectRef, resolveColumnInSource?: ResolveColumnInSource): boolean;
+//# sourceMappingURL=column-rename.d.ts.map

package/dist/src/schema/rename/column-rename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-rename.d.ts","sourceRoot":"","sources":["../../../../src/schema/rename/column-rename.ts"],"names":[],"mappings":"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"}