supaschema 0.1.0-rc.1

package/config-schema.json

@@ -0,0 +1,208 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "supaschema configuration",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "adapter": {
+      "default": "supabase-auto",
+      "type": "string",
+      "enum": [
+        "supabase-auto",
+        "postgres"
+      ]
+    },
+    "cascade": {
+      "default": "never",
+      "type": "string",
+      "const": "never"
+    },
+    "destructiveChanges": {
+      "default": "hint-required",
+      "type": "string",
+      "enum": [
+        "hint-required",
+        "block",
+        "allow"
+      ]
+    },
+    "environments": {
+      "default": {},
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "databaseUrl": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "databaseUrl"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "excludedGrantRoles": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "hints": {
+      "default": {
+        "destructive": [],
+        "renames": []
+      },
+      "type": "object",
+      "properties": {
+        "destructive": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "renames": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from": {
+                "type": "string"
+              },
+              "to": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "from",
+              "to"
+            ],
+            "additionalProperties": false
+          }
+        }
+      }
+    },
+    "idempotency": {
+      "default": "required",
+      "type": "string",
+      "const": "required"
+    },
+    "lockTimeout": {
+      "default": "5s",
+      "type": "string"
+    },
+    "migrationsDir": {
+      "default": "supabase/migrations",
+      "type": "string"
+    },
+    "typesFile": {
+      "default": "database.types.ts",
+      "type": "string"
+    },
+    "zodFile": {
+      "default": "database.zod.ts",
+      "type": "string"
+    },
+    "normalize": {
+      "default": "deparse",
+      "type": "string",
+      "enum": [
+        "off",
+        "deparse"
+      ]
+    },
+    "managedSchemas": {
+      "default": [
+        "auth",
+        "storage",
+        "realtime",
+        "vault",
+        "extensions",
+        "cron",
+        "net",
+        "supabase_functions",
+        "graphql",
+        "graphql_public"
+      ],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "postgresVersion": {
+      "default": "15+",
+      "type": "string"
+    },
+    "renameDetection": {
+      "default": "hints-only",
+      "type": "string",
+      "enum": [
+        "hints-only",
+        "off"
+      ]
+    },
+    "schemaPaths": {
+      "default": [
+        "supabase/schemas"
+      ],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "schemas": {
+      "default": {
+        "exclude": [],
+        "include": []
+      },
+      "type": "object",
+      "properties": {
+        "exclude": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "include": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "statementTimeout": {
+      "default": "60s",
+      "type": "string"
+    },
+    "transactionMode": {
+      "default": "per-migration",
+      "type": "string",
+      "enum": [
+        "per-migration",
+        "per-statement"
+      ]
+    },
+    "validators": {
+      "default": [
+        "internal-parser"
+      ],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/corpus/supabase-style/corpus.json

@@ -0,0 +1,6 @@
+{
+  "adapter": "postgres",
+  "schemas": { "exclude": [], "include": ["app"] },
+  "excludedGrantRoles": [],
+  "hints": { "destructive": [], "renames": [] }
+}

package/corpus/supabase-style/migrations/20260101000000_init.sql

@@ -0,0 +1,28 @@
+CREATE SCHEMA app;
+GRANT USAGE ON SCHEMA app TO authenticated, anon;
+
+CREATE FUNCTION app.current_tenant() RETURNS uuid
+  LANGUAGE sql STABLE
+  SET search_path = ''
+  AS $$ SELECT nullif(current_setting('app.tenant_id', true), '')::uuid $$;
+
+CREATE TABLE app.accounts (
+  id bigint NOT NULL,
+  tenant_id uuid NOT NULL,
+  balance numeric NOT NULL,
+  status text NOT NULL
+);
+
+CREATE SEQUENCE app.accounts_id_seq;
+ALTER SEQUENCE app.accounts_id_seq OWNED BY app.accounts.id;
+ALTER TABLE app.accounts ALTER COLUMN id SET DEFAULT nextval('"app"."accounts_id_seq"');
+
+ALTER TABLE app.accounts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE ONLY app.accounts FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY accounts_select ON app.accounts
+  FOR SELECT
+  TO authenticated
+  USING (tenant_id = (SELECT app.current_tenant()) AND balance >= 0);
+
+GRANT SELECT ON app.accounts TO authenticated;

package/corpus/supabase-style/migrations/20260102000000_noise.sql

@@ -0,0 +1,13 @@
+GRANT EXECUTE ON FUNCTION app.current_tenant() TO authenticated;
+
+REVOKE ALL ON SCHEMA app FROM PUBLIC;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA app REVOKE SELECT ON TABLES FROM anon;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA app GRANT SELECT ON TABLES TO service_role;
+
+CREATE TYPE app.account_status AS ENUM ('active', 'closed');
+GRANT USAGE ON TYPE app.account_status TO authenticated;
+
+COMMENT ON TABLE app.accounts IS 'Customer accounts';
+COMMENT ON FUNCTION app.current_tenant() IS 'Tenant resolver';

package/corpus/supabase-style/migrations/20260103000000_churn.sql

@@ -0,0 +1,4 @@
+GRANT INSERT ON app.accounts TO anon;
+REVOKE INSERT ON app.accounts FROM anon;
+
+REVOKE EXECUTE ON FUNCTION app.current_tenant() FROM PUBLIC;

package/corpus/supabase-style/migrations/20260104000000_triggers.sql

@@ -0,0 +1,17 @@
+CREATE FUNCTION app.touch_account_audit()
+ RETURNS trigger
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+BEGIN
+  IF NEW.status IS DISTINCT FROM OLD.status THEN
+    NEW.status := lower(NEW.status);
+  END IF;
+  RETURN NEW;
+END;
+$function$;
+COMMENT ON FUNCTION app.touch_account_audit() IS 'Normalizes status on update';
+REVOKE ALL ON FUNCTION app.touch_account_audit() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION app.touch_account_audit() TO service_role;
+CREATE OR REPLACE TRIGGER accounts_touch_audit BEFORE UPDATE ON app.accounts FOR EACH ROW EXECUTE FUNCTION app.touch_account_audit();

package/corpus/supabase-style/roles.sql

@@ -0,0 +1,13 @@
+DO $supaschema$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'anon') THEN
+    CREATE ROLE anon NOLOGIN NOINHERIT;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'authenticated') THEN
+    CREATE ROLE authenticated NOLOGIN NOINHERIT;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'service_role') THEN
+    CREATE ROLE service_role NOLOGIN NOINHERIT BYPASSRLS;
+  END IF;
+END
+$supaschema$;

package/corpus/supabase-style/tree/functions.sql

@@ -0,0 +1,26 @@
+create function app.current_tenant() returns uuid
+  language sql stable
+  set search_path = ''
+  as $$ select nullif(current_setting('app.tenant_id', true), '')::uuid $$;
+
+revoke execute on function app.current_tenant() from public;
+grant execute on function app.current_tenant() to authenticated;
+
+comment on function app.current_tenant() is 'Tenant resolver';
+
+create function app.touch_account_audit() returns trigger
+  language plpgsql security definer
+  set search_path = ''
+  as $$
+begin
+  if NEW.status is distinct from OLD.status then
+    NEW.status := lower(NEW.status);
+  end if;
+  return NEW;
+end;
+$$;
+
+revoke all on function app.touch_account_audit() from public;
+grant execute on function app.touch_account_audit() to service_role;
+
+comment on function app.touch_account_audit() is 'Normalizes status on update';

package/corpus/supabase-style/tree/policies.sql

@@ -0,0 +1,4 @@
+create policy accounts_select on app.accounts
+  for select
+  to authenticated
+  using (tenant_id = (select app.current_tenant()) and balance >= 0);

package/corpus/supabase-style/tree/schema.sql

@@ -0,0 +1,4 @@
+create schema app;
+grant usage on schema app to authenticated, anon;
+
+alter default privileges in schema app grant select on tables to service_role;

package/corpus/supabase-style/tree/tables.sql

@@ -0,0 +1,20 @@
+create sequence app.accounts_id_seq;
+
+create table app.accounts (
+  id BIGINT not null default nextval('app.accounts_id_seq'),
+  tenant_id uuid not null,
+  balance numeric not null,
+  status text not null,
+  note text
+);
+
+alter sequence app.accounts_id_seq owned by app.accounts.id;
+
+alter table app.accounts enable row level security;
+alter table only app.accounts force row level security;
+
+create index accounts_tenant_id_idx on app.accounts (tenant_id);
+
+grant select on app.accounts to authenticated;
+
+comment on table app.accounts is 'Customer accounts';

package/corpus/supabase-style/tree/triggers.sql

@@ -0,0 +1,3 @@
+create or replace trigger accounts_touch_audit
+  before update on app.accounts
+  for each row execute function app.touch_account_audit();

package/corpus/supabase-style/tree/types.sql

@@ -0,0 +1,2 @@
+create type app.account_status as enum ('active', 'closed');
+grant usage on type app.account_status to authenticated;

package/corpus/supabase-style/tree/views.sql

@@ -0,0 +1,6 @@
+create view app.account_summary as
+  select tenant_id, count(*) as account_count, sum(balance) as total_balance
+  from app.accounts
+  group by tenant_id;
+
+grant select on app.account_summary to authenticated;

package/dist/audit.d.ts

@@ -0,0 +1,20 @@
+import type { SchemaModel } from "./core.js";
+export interface AuditFinding {
+    code: string;
+    count: number;
+    message: string;
+    samples: string[];
+    severity: string;
+}
+export interface AuditReport {
+    errorStatements: number;
+    findings: AuditFinding[];
+    objectsByKind: Record<string, number>;
+    objectsBySchema: Record<string, number>;
+    source: string;
+    supported: boolean;
+    totalObjects: number;
+}
+export declare function auditModel(model: SchemaModel): AuditReport;
+export declare function renderAuditReport(report: AuditReport): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,WAAW,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA0C1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA0B7D"}

package/dist/audit.js

@@ -0,0 +1,68 @@
+const sampleLimit = 5;
+const sampleLength = 120;
+export function auditModel(model) {
+    const objectsByKind = {};
+    const objectsBySchema = {};
+    for (const object of model.objects) {
+        objectsByKind[object.ref.kind] = (objectsByKind[object.ref.kind] ?? 0) + 1;
+        const schema = object.ref.schema ?? (object.ref.kind === "schema" ? object.ref.name : "-");
+        objectsBySchema[schema] = (objectsBySchema[schema] ?? 0) + 1;
+    }
+    const groups = new Map();
+    for (const item of model.diagnostics) {
+        if (item.severity !== "error" && item.severity !== "warning") {
+            continue;
+        }
+        const group = groups.get(item.code) ?? { diagnostics: [], severity: item.severity };
+        group.diagnostics.push(item);
+        groups.set(item.code, group);
+    }
+    const findings = [...groups.entries()]
+        .map(([code, group]) => ({
+        code,
+        count: group.diagnostics.length,
+        message: group.diagnostics[0]?.message ?? "",
+        samples: group.diagnostics
+            .map((item) => item.statement ?? item.hint ?? "")
+            .filter(Boolean)
+            .slice(0, sampleLimit)
+            .map((sample) => sample.replaceAll(/\s+/gu, " ").slice(0, sampleLength)),
+        severity: group.severity,
+    }))
+        .sort((left, right) => right.count - left.count || left.code.localeCompare(right.code));
+    const errorStatements = findings
+        .filter((finding) => finding.severity === "error")
+        .reduce((total, finding) => total + finding.count, 0);
+    return {
+        errorStatements,
+        findings,
+        objectsByKind,
+        objectsBySchema,
+        source: model.source,
+        supported: errorStatements === 0,
+        totalObjects: model.objects.length,
+    };
+}
+export function renderAuditReport(report) {
+    const lines = [];
+    lines.push(`supaschema audit: ${report.source}`);
+    lines.push(`objects modeled: ${report.totalObjects} across ${Object.keys(report.objectsBySchema).length} schema(s)`);
+    const kinds = Object.entries(report.objectsByKind)
+        .sort((left, right) => right[1] - left[1])
+        .map(([kind, count]) => `${kind}=${count}`)
+        .join(" ");
+    lines.push(`by kind: ${kinds || "none"}`);
+    if (report.findings.length === 0) {
+        lines.push("contract coverage: full — no findings");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`contract coverage: ${report.errorStatements} statement(s) outside the contract, ${report.findings.length} finding class(es)`);
+    for (const finding of report.findings) {
+        lines.push(`  ${finding.severity.toUpperCase()} ${finding.code} ×${finding.count}`);
+        for (const sample of finding.samples) {
+            lines.push(`    ${sample}`);
+        }
+    }
+    lines.push("run `supaschema explain <CODE>` for remediation guidance per code");
+    return `${lines.join("\n")}\n`;
+}

package/dist/benchmark-db.d.ts

@@ -0,0 +1,5 @@
+export declare function withTemporaryDatabases<T>(databaseUrl: string, count: number, callback: (databaseUrls: string[]) => Promise<T>): Promise<T>;
+export declare function applySql(databaseUrl: string, sql: string): Promise<void>;
+export declare function applyMigrationSql(databaseUrl: string, sql: string): Promise<void>;
+export declare function databasePair(databaseUrls: string[]): [string, string];
+//# sourceMappingURL=benchmark-db.d.ts.map

package/dist/benchmark-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-db.d.ts","sourceRoot":"","sources":["../src/benchmark-db.ts"],"names":[],"mappings":"AAIA,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9E;AAID,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvF;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrE"}

package/dist/benchmark-db.js

@@ -0,0 +1,71 @@
+import { Client } from "pg";
+import { quoteIdent } from "./sql/identifiers.js";
+import { splitSqlStatements } from "./sql/split.js";
+export async function withTemporaryDatabases(databaseUrl, count, callback) {
+    const admin = new Client({ connectionString: databaseUrl });
+    const created = [];
+    try {
+        await admin.connect();
+        for (let index = 0; index < count; index += 1) {
+            const databaseName = tempDatabaseName(index);
+            await admin.query(`CREATE DATABASE ${quoteIdent(databaseName)}`);
+            created.push(databaseName);
+        }
+        return await callback(created.map((databaseName) => databaseUrlWithDatabase(databaseUrl, databaseName)));
+    }
+    finally {
+        for (const databaseName of created.reverse()) {
+            await admin
+                .query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()`, [databaseName])
+                .catch(() => undefined);
+            await admin
+                .query(`DROP DATABASE IF EXISTS ${quoteIdent(databaseName)} WITH (FORCE)`)
+                .catch(() => undefined);
+        }
+        await admin.end().catch(() => undefined);
+    }
+}
+export async function applySql(databaseUrl, sql) {
+    const client = new Client({ connectionString: databaseUrl });
+    try {
+        await client.connect();
+        for (const statement of splitSqlStatements(sql)) {
+            await client.query(statement);
+        }
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+// One transaction per migration mirrors runners like `supabase db push`; an
+// error leaves the transaction uncommitted and ending the connection aborts it.
+export async function applyMigrationSql(databaseUrl, sql) {
+    const client = new Client({ connectionString: databaseUrl });
+    try {
+        await client.connect();
+        await client.query("BEGIN");
+        for (const statement of splitSqlStatements(sql)) {
+            await client.query(statement);
+        }
+        await client.query("COMMIT");
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+export function databasePair(databaseUrls) {
+    const [fromUrl, toUrl] = databaseUrls;
+    if (!fromUrl || !toUrl) {
+        throw new Error("expected two temporary benchmark databases");
+    }
+    return [fromUrl, toUrl];
+}
+function databaseUrlWithDatabase(databaseUrl, databaseName) {
+    const url = new URL(databaseUrl);
+    url.pathname = `/${databaseName}`;
+    return url.toString();
+}
+function tempDatabaseName(index) {
+    const suffix = `${process.pid}_${Date.now()}_${index}_${Math.random().toString(16).slice(2)}`;
+    return `pg_diverge_benchmark_${suffix}`.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 60);
+}

package/dist/benchmark-fixtures.d.ts

@@ -0,0 +1,10 @@
+export interface FixtureManifestEntry {
+    change: "create" | "change";
+    key: string;
+}
+export declare function realisticFixtureManifest(tableCount: number): FixtureManifestEntry[];
+export declare function makeRealisticSqlFixture(tableCount: number): {
+    from: string;
+    to: string;
+};
+//# sourceMappingURL=benchmark-fixtures.d.ts.map

package/dist/benchmark-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-fixtures.d.ts","sourceRoot":"","sources":["../src/benchmark-fixtures.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAwFnF;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAgDxF"}