@everystack/cli 0.4.67 → 0.4.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.67",
+  "version": "0.4.69",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/deparse-normal.ts

@@ -24,13 +24,45 @@
  *   for n ≥ 1. PostgreSQL defines an array-to-array cast element-wise (parse_coerce), so
  *   the two expressions denote the same value for every input; wrapping an element in
  *   parentheses is parse-neutral. The empty array is EXCLUDED: `ARRAY[]` without a cast has
- *   no type, so its cast is load-bearing and stays.
+ *   no type, so its cast is load-bearing and stays. (The measured CROSS-VERSION case: two PG
+ *   majors const-fold the same DDL differently.)
+ *
+ *   LITERAL-TEXT-CAST STRIP: `'lit'::text  ==  'lit'`, but ONLY the bare `text` cast applied
+ *   directly to a single-quoted string literal. This is a CROSS-PRODUCER class, present on
+ *   every version: PostgreSQL coerces an unknown-type string literal compared to a text
+ *   column and RECORDS `'lit'::text` in the stored tree, while the author's model source
+ *   writes the un-cast `'lit'`. The two producers' texts never converge without this rule, so
+ *   a `text_col = 'lit'` partial index / CHECK / policy re-diffs DROP+CREATE forever and the
+ *   fingerprint gate cannot MATCH. Safe because `text` takes no typmod and its input function
+ *   is the identity on the literal's bytes — the cast cannot change the value. The rule is
+ *   `text`-ONLY for exactly that reason: `bpchar`/`character(n)` blank-pad or blank-trim,
+ *   `varchar(n)`/`"char"` truncate — those casts CHANGE the value, so stripping one would
+ *   collapse two opposite-truth predicates to equal text (a false match, the disaster). The
+ *   array-type cast `::text[]` is likewise excluded — it carries the element type. See the
+ *   `char(2)` false-match test for why the family is not widened.
  *
  * Anything the scanner does not positively recognize is left byte-for-byte unchanged — an
  * unrecognized spelling is a MISS (drop + create, the pre-existing behavior), never a guess.
- * Escalation is named, not implied: the SECOND cross-version variant found in the field is
+ * Escalation is named, not implied: the SECOND cross-VERSION variant found in the field is
  * the trigger to adopt libpg_query and move identity onto normalized ASTs (Ty, 2026-08-09) —
- * a growing rule table over raw text is where scanning stops being defensible.
+ * a growing rule table over raw text is where scanning stops being defensible. One correction
+ * to that trigger (2026-08-24): libpg_query closes cross-VERSION SYNTAX drift (whitespace,
+ * parens, keyword case), NOT cross-PRODUCER COERCION drift — a raw parse tree carries no type
+ * resolution, so `'lit'` and `'lit'::text` still differ structurally without a catalog, which
+ * the CI-pure `db:diff` lane does not have. That class earns a provable text rewrite here,
+ * verified end-to-end by `db:check`'s from-scratch build on a real database.
+ *
+ * PAREN DRIFT adjudicated 2026-08-24: a COMPOUND predicate deparses fully parenthesized
+ * (`((a) AND (b))`) while the author writes minimal parens — pure cross-PRODUCER syntax drift.
+ * The resolution is NOT a normalization rule here: text identity stays as-is, plus a pg-form
+ * authoring convention (declare the predicate as pg deparses it) and a PAREN-ONLY DETECTOR in
+ * schema-diff.ts (`stripAllParens`) that recognizes the churn and prints the exact live form to
+ * adopt. Do NOT add a precedence- or paren-aware text rule — a safe one needs a real lexer, and
+ * a lexer bug is a FALSE-MATCH vector (`(a OR b) AND c` vs `a OR (b AND c)` collapse equal). The
+ * NEXT syntax-drift class the authoring convention cannot absorb — one where NO author-writable
+ * text round-trips `pg_get_expr` — is the trigger to adopt libpg_query (AST identity); at that
+ * point the coercion rules (`::text`, array-cast distribution) MIGRATE to AST transforms, they
+ * do not disappear. Paren drift is not that class: the convention absorbs it completely.
  *
  * Applied at the PRODUCERS (live introspection's `predicate()`, the compiler's policy
  * assembly), so every downstream comparison — the identity matcher, the canonical hash, the
@@ -121,6 +153,53 @@ function distributeOnce(s: string): string | null {
   return null;
 }
 
+/**
+ * A bare `text` cast token — `::text` or `::pg_catalog.text` — from just past a literal's
+ * closing quote. Whitespace around `::` is tolerated (pg emits none; an author might). The
+ * trailing `\b` rejects `::textfoo`; the caller additionally rejects a following `[` so the
+ * array-type cast `::text[]` is never stripped.
+ */
+const LITERAL_TEXT_CAST = /^\s*::\s*(?:pg_catalog\.)?text\b/;
+
+/**
+ * Strip a bare `text` cast applied directly to a single-quoted string literal, wherever one
+ * appears. One left-to-right pass is complete: removing a cast token cannot create a new
+ * `'literal'::text` pair to its left, and it never forms an `(ARRAY[…])::T[]` for the other
+ * rule. Quoted regions are skipped so a `::text` inside a literal is content, not structure.
+ */
+function stripLiteralTextCast(s: string): string {
+  let out = '';
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (c === "'") {
+      const close = skipQuoted(s, i);
+      if (close < 0) return out + s.slice(i); // unterminated literal — leave the rest alone
+      out += s.slice(i, close + 1); // the literal itself, verbatim
+      i = close + 1;
+      // Drop a bare text cast on the literal, and any stacked `::text::text`, so the result
+      // is a true fixpoint. `::text[]` is the array-type cast (element type, load-bearing),
+      // not a scalar text cast — the look-ahead skips whitespace so `::text []` is kept too.
+      let m = LITERAL_TEXT_CAST.exec(s.slice(i));
+      while (m && !/^\s*\[/.test(s.slice(i + m[0].length))) {
+        i += m[0].length; // drop the cast token
+        m = LITERAL_TEXT_CAST.exec(s.slice(i));
+      }
+      continue;
+    }
+    if (c === '"') {
+      const close = skipQuoted(s, i);
+      if (close < 0) return out + s.slice(i);
+      out += s.slice(i, close + 1); // a quoted identifier — never a string literal, skip whole
+      i = close + 1;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
 /**
  * Normalize one deparsed expression. Idempotent; unrecognized text returns unchanged.
  * Fixpoint-bounded: nesting deeper than the cap returns its progress, which is still
@@ -130,8 +209,8 @@ export function normalizeDeparsedExpr(text: string): string {
   let s = text;
   for (let n = 0; n < 64; n++) {
     const next = distributeOnce(s);
-    if (next === null) return s;
+    if (next === null) break;
     s = next;
   }
-  return s;
+  return stripLiteralTextCast(s);
 }

package/src/cli/schema-diff.ts

@@ -63,7 +63,7 @@ export type SchemaChange =
   | { kind: 'setIdentity'; table: string; column: string; identity: 'always' | 'byDefault' | null; from: 'always' | 'byDefault' | null }
   /** A type change → real `ALTER COLUMN ... TYPE`. `risk` decides USING + a data-loss warning. */
   | { kind: 'alterType'; table: string; column: string; from: string; to: string; risk: TypeChangeRisk }
-  | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec }
+  | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec; note?: string }
   | { kind: 'dropConstraint'; table: string; name: string }
   | { kind: 'addPrimaryKey'; table: string; columns: string[] }
   /** A PK change other than first-time add — a notice (the drop needs its constraint name). */
@@ -97,7 +97,7 @@ export type SchemaChange =
   /** An enum value the DB has but the Model dropped/renamed — Postgres can't drop one in place (a notice). */
   | { kind: 'enumValuesChanged'; name: string; from: string[]; to: string[] }
   /** A standalone index to create → `CREATE [UNIQUE] INDEX … [USING …] (…) [INCLUDE …] [WHERE …]`. */
-  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string; using?: string; include?: string[] }
+  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string; using?: string; include?: string[]; note?: string }
   /** A standalone index present in the DB but no longer declared → `DROP INDEX` (a removal — gated). */
   | { kind: 'dropIndex'; table: string; name: string }
   /** A content-identical index the model names differently → `ALTER INDEX … RENAME TO` (B3). */
@@ -339,6 +339,34 @@ export function normalizeCheck(expr: string): string {
   return s.replace(/\s+/g, ' ');
 }
 
+/**
+ * Strip EVERY parenthesis and collapse whitespace. DIAGNOSTIC-ONLY — never an identity or
+ * matcher input. Blind paren removal is UNSAFE for identity: it crosses operator precedence,
+ * so `(a OR b) AND c` and `a OR (b AND c)` collapse to the same text (a false match, the one
+ * disaster the matcher must avoid). It is safe HERE because it only recognizes that a diff is
+ * paren-only, to explain the churn — a wrong guess at worst suggests adopting the live text,
+ * which always converges. Quote-naive for the same reason (see docs; adjudicated 2026-08-24).
+ */
+export function stripAllParens(expr: string): string {
+  return expr.replace(/[()]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * When a predicate diff is PAREN-ONLY, the churn is not a real change — Postgres stores
+ * predicates fully parenthesized while the model author writes minimal parens. The fix is to
+ * declare the live form; this note hands the operator the exact text to paste. `kind` is
+ * "index"/"check", `name` the declared object, `liveName` the live object, `liveExpr` the
+ * predicate to adopt.
+ */
+function parenOnlyNote(kind: string, name: string, liveName: string, liveExpr: string): string {
+  // Hedged deliberately. The paren-blind match cannot tell redundant parens from a real
+  // PRECEDENCE edit — `a OR (b AND c)` and `(a OR b) AND c` strip to the same text. So the
+  // note must NOT assert "this is not a change": if the operator DID intend a logic change,
+  // adopting the live form would silently revert it. The "if you did not intend" clause is
+  // true in both cases and points the common (redundant-paren) case at the converging fix.
+  return `-- NOTE: ${kind} "${name}" differs from the live ${kind} "${liveName}" by parenthesization. If you did NOT intend a change to the predicate's logic, this is churn — Postgres stores predicates fully parenthesized, so declare the live form to converge:  ${liveExpr}`;
+}
+
 // ---------------------------------------------------------------------------
 // Diff.
 // ---------------------------------------------------------------------------
@@ -532,13 +560,19 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   ];
 }
 
-/** A `createIndex` change from an index spec (the new-table path and the per-table diff share it). */
-function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
+/** A `createIndex` change from an index spec (the new-table path and the per-table diff share it).
+ *  `parenTwin` is a live index that matches this one on everything but parenthesization — when
+ *  present, the create carries an advisory note pointing at the live form to adopt. */
+function createIndexChange(table: string, ix: IndexSchema, parenTwin?: IndexSchema): SchemaChange {
+  const note = parenTwin?.where
+    ? parenOnlyNote('index', ix.name, parenTwin.name, `WHERE ${parenTwin.where}`)
+    : undefined;
   return {
     kind: 'createIndex', table, name: ix.name, columns: ix.columns, unique: ix.unique,
     ...(ix.where ? { where: ix.where } : {}),
     ...(ix.using ? { using: ix.using } : {}),
     ...(ix.include?.length ? { include: ix.include } : {}),
+    ...(note ? { note } : {}),
   };
 }
 
@@ -554,6 +588,14 @@ export function indexKey(ix: IndexSchema): string {
   return `${ix.unique ? 'u' : ''}|${entries}|${normalizeCheck(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
 }
 
+/** The same key with EVERY paren stripped — DIAGNOSTIC-ONLY (see {@link stripAllParens}).
+ *  Two indexes with the same paren-blind key but different {@link indexKey} differ by
+ *  parenthesization alone, which is churn, not a change. Never used for matching/identity. */
+function parenBlindIndexKey(ix: IndexSchema): string {
+  const entries = ix.columns.map((c) => stripAllParens(c)).join(',');
+  return `${ix.unique ? 'u' : ''}|${entries}|${stripAllParens(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
+}
+
 /**
  * Diff standalone indexes by CONTENT — an index with the same key entries, uniqueness, predicate,
  * method and INCLUDE is the same index whatever it is called, so a pulled index re-generates
@@ -580,6 +622,11 @@ function diffIndexes(
 ): void {
   const desiredByKey = new Map(d.indexes.map((ix) => [indexKey(ix), ix]));
   const currentByKey = new Map(c.indexes.map((ix) => [indexKey(ix), ix]));
+  // Paren-blind lookup: a desired index with no exact match may still have a live twin that
+  // differs only by parenthesization (Postgres deparses predicates fully parenthesized). That
+  // is churn, not a change; the create carries a note pointing at the live form. Diagnostic
+  // only — this map never decides identity.
+  const currentByParenBlind = new Map(c.indexes.map((ix) => [parenBlindIndexKey(ix), ix]));
   // A same-NAME index whose CONTENT changed is a redefinition, not a removal, and PostgreSQL has
   // no CREATE OR REPLACE INDEX — it must drop first. Reported by GridironDB: a full unique index
   // became two partial ones, the new partial index derived the SAME generated name as the live
@@ -597,7 +644,11 @@ function diffIndexes(
   for (const [k, ix] of desiredByKey) {
     const live = currentByKey.get(k);
     if (!live) {
-      creates.push(createIndexChange(d.table, ix));
+      const twin = currentByParenBlind.get(parenBlindIndexKey(ix));
+      // Only annotate a twin that is actually being dropped (no exact desired match), so the
+      // note names a live index that is really churning, not one that also round-trips.
+      const churning = twin && !desiredByKey.has(indexKey(twin));
+      creates.push(createIndexChange(d.table, ix, churning ? twin : undefined));
     } else if (ix.nameDeclared && live.name !== ix.name) {
       renames.push({ kind: 'renameIndex', table: d.table, from: live.name, to: ix.name });
     }
@@ -749,11 +800,19 @@ function constraintContentKey(c: ConstraintSpec): string {
 function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
   const desiredByPred = new Map(d.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   const currentByPred = new Map(c.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
+  // Paren-blind lookup, diagnostic only (see diffIndexes): a compound CHECK churns for the
+  // same reason — pg stores `((a) AND (b))`, the model writes `a AND b`.
+  const currentByParenBlind = new Map(c.checks.map((ck) => [stripAllParens(ck.expr), ck]));
   for (const [pred, ck] of currentByPred) {
     if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
   }
   for (const [pred, ck] of desiredByPred) {
-    if (!currentByPred.has(pred)) addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: { type: 'check', name: ck.name, expr: ck.expr } });
+    if (currentByPred.has(pred)) continue;
+    const twin = currentByParenBlind.get(stripAllParens(ck.expr));
+    // Annotate only a twin that is itself being dropped (no exact desired match) — a real churn.
+    const churning = twin && !desiredByPred.has(normalizeCheck(twin.expr));
+    const note = churning ? parenOnlyNote('check', ck.name, twin.name, twin.expr) : undefined;
+    addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: { type: 'check', name: ck.name, expr: ck.expr }, ...(note ? { note } : {}) });
   }
 }
 
@@ -937,7 +996,7 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       return `${warn}\n${ddl}`;
     }
     case 'addConstraint':
-      return addConstraintSql(change.table, change.constraint);
+      return (change.note ? `${change.note}\n` : '') + addConstraintSql(change.table, change.constraint);
     case 'dropConstraint':
       return `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
     case 'addPrimaryKey':
@@ -983,7 +1042,8 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       const entry = (c: string): string => (/^[a-z_][a-z0-9_$]*$/i.test(c) ? quote(c) : c);
       const include = change.include?.length ? ` INCLUDE (${colList(change.include)})` : '';
       const where = change.where ? ` WHERE ${change.where}` : '';
-      return `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table}${using} (${change.columns.map(entry).join(', ')})${include}${where};`;
+      const stmt = `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table}${using} (${change.columns.map(entry).join(', ')})${include}${where};`;
+      return change.note ? `${change.note}\n${stmt}` : stmt;
     }
     case 'dropIndex': {
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';