@everystack/cli 0.4.38 → 0.4.40

package/src/cli/pg-argtypes.ts

@@ -0,0 +1,52 @@
+/**
+ * pg-argtypes — function identity is name + ARGUMENT TYPES.
+ *
+ * PostgreSQL identifies a function by `schema.name(argtypes)`, not by name. The derived
+ * layer keyed on `schema.name` alone, so two overloads collapsed onto one identity: the
+ * generated `DROP FUNCTION IF EXISTS api.get_user` errored ("function name is not
+ * unique"), `derived_provenance` (identity is its PRIMARY KEY) held one row for two live
+ * objects so drift could never see the second, and db:pull rendered duplicate consts.
+ *
+ * The identity spelling is the CATALOG's: `format_type(oid, NULL)` over `proargtypes` —
+ * `integer`, `character varying`, `double precision`, `text[]`. The live side reads it
+ * straight from pg_proc; the DECLARED side has only what the author typed, so
+ * `@everystack/model`'s `normalizeArgType` maps the SQL aliases (`int`, `varchar`,
+ * `timestamptz`) onto the same spelling and drops typmods (a function argument carries
+ * none — PostgreSQL discards length/precision, so `varchar(20)` and `varchar` are ONE
+ * type here).
+ *
+ * Known limit: a custom type outside the search_path prints QUALIFIED (`api.my_enum`)
+ * while a hand-written `arg('x', 'my_enum')` does not, and the two read as different
+ * functions. db:pull-rendered args are already catalog-spelled, so this only reaches a
+ * hand-authored declaration; the reconciler names the pair loudly rather than diffing it
+ * in silence (see planReconcile's spelling-mismatch warning).
+ *
+ * Pure and database-free — the identity must be computable in db:diff's CI-pure path.
+ */
+
+import { normalizeArgType } from '@everystack/model';
+
+// The spelling itself lives in @everystack/model, next to `arg()` — it is part of the
+// DECLARED vocabulary, and defineModule needs it to tell an overload from a duplicate.
+export { normalizeArgType };
+
+/** `api.get_user(integer, text)` — the identity, from the DECLARED argument types. */
+export function functionIdentity(schema: string, name: string, argTypes: readonly string[]): string {
+  return `${schema}.${name}(${argTypes.map(normalizeArgType).join(', ')})`;
+}
+
+/**
+ * Split a function identity into its qualified name and its argument list.
+ * `args` is null for a LEGACY identity that carries no signature (a pre-signature
+ * provenance row) — callers keep the old rendering for those.
+ */
+export function splitFunctionIdentity(identity: string): { qualified: string; args: string | null } {
+  const open = identity.indexOf('(');
+  if (open === -1 || !identity.endsWith(')')) return { qualified: identity, args: null };
+  return { qualified: identity.slice(0, open), args: identity.slice(open + 1, -1) };
+}
+
+/** The pre-signature identity of a function — `schema.name`. The provenance upgrade's lookup key. */
+export function legacyFunctionIdentity(identity: string): string {
+  return splitFunctionIdentity(identity).qualified;
+}