@everystack/cli 0.4.68 → 0.4.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.68",
+  "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

@@ -52,6 +52,18 @@
  * 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
  * drift detail — sees normalized text without holding its own copy of this rule.

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]}.` : '';