@thomasfosterau/effect-drizzle-ext-pg 0.0.0 → 0.1.0

package/dist/testing.js

@@ -0,0 +1,408 @@
+import { pgClientFromUrl } from "./index.js";
+import { applyMigrations } from "./migrations.js";
+import * as PgClient from "@effect/sql-pg/PgClient";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Arr from "effect/Array";
+import * as Schema from "effect/Schema";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Exit from "effect/Exit";
+import * as HashSet from "effect/HashSet";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import * as Schedule from "effect/Schedule";
+import { isSqlError } from "effect/sql/SqlError";
+import * as Redacted from "effect/Redacted";
+// src/provisioning.ts
+/**
+* @copyright Thomas Foster
+*
+* **Ephemeral test-database provisioning** — the half of an integration
+* suite's global setup every consuming application carried as
+* `packages/integration-harness/local-database.ts`. Re-exported from
+* `./testing`; the reference is the preferenceflow application's copy.
+*
+* A suite's database is resolved in this order ({@link resolveDatabaseSource}):
+*
+* 0. **An explicit `DATABASE_URL_TEST` / `DATABASE_URL`** wins and is used
+*    as-is: it must already be migrated — the escape hatch for pointing the
+*    suite at a deployed stage's database or any other prepared server.
+*    Nothing is provisioned and nothing is torn down.
+* 1. **A reachable local server** — a CI service container, a devcontainer's
+*    PostgreSQL, or anything the standard `PG*` variables (`PGHOST`,
+*    `PGPORT`, `PGUSER`, `PGPASSWORD`) point at; the default is a trust-auth
+*    `postgres@127.0.0.1:5432`. Each run gets a **freshly created database**
+*    on it: drop, create, apply every migration.
+* 2. **A Testcontainers-launched container** when nothing is listening and
+*    no `PG*` variable was set explicitly. Needs a Docker daemon and the
+*    optional peer `@testcontainers/postgresql`, which is imported only on
+*    this path. The container is brand new, so migrations apply directly, and
+*    it stops when the provisioning scope closes.
+*
+* Explicit `PG*` config that is unreachable is a hard error
+* ({@link DatabaseUnreachable}), not a silent fallback: if you pointed the
+* suite somewhere, it should not quietly run elsewhere.
+*
+* Either way run N's verdict is independent of run N−1: no state survives
+* between runs. The per-checkout database name
+* `<prefix>_test_<sha256(migrationsDir)[:8]>` keeps parallel worktrees
+* sharing one server from dropping each other's database mid-run — pass the
+* migrations directory as an absolute path, which is per-checkout.
+*
+* What stays with the application: fixture users and seed data (website
+* #1847 keeps the harness → database edge one-way), and the container image
+* and database-name prefix, which are parameters here.
+*
+* @module provisioning
+*/
+/** The variables that count as "explicitly pointed at a server". */
+const SERVER_VARIABLES = [
+	"PGHOST",
+	"PGPORT",
+	"PGUSER",
+	"PGPASSWORD"
+];
+/** How long one connection attempt against the admin database may take. */
+const CONNECT_TIMEOUT = Duration.seconds(10);
+/** Where a local server is expected, honouring the standard `PG*` variables. */
+const serverConfig = (env) => ({
+	host: env.PGHOST ?? "127.0.0.1",
+	port: Number(env.PGPORT ?? "5432"),
+	user: env.PGUSER ?? "postgres",
+	password: env.PGPASSWORD ?? ""
+});
+/** Was a server location explicitly configured (vs. the loopback default)? */
+const serverExplicitlyConfigured = (env) => SERVER_VARIABLES.some((name) => (env[name] ?? "") !== "");
+/** The connection URL for `database` on the configured local server. */
+const connectionUrl = (env, database) => {
+	const { host, port, user, password } = serverConfig(env);
+	const auth = password === "" ? user : `${user}:${encodeURIComponent(password)}`;
+	return Redacted.make(`postgresql://${auth}@${host}:${port}/${database}`);
+};
+/** `user@host:port` — the configured server, printable (no password). */
+const serverLabel = (env) => {
+	const { host, port, user } = serverConfig(env);
+	return `${user}@${host}:${port}`;
+};
+/** A database-name prefix is spliced into DDL unquoted-safe, so it is restricted to an identifier. */
+const DATABASE_PREFIX = /^[a-z_][a-z0-9_]*$/;
+/** The prefix is not a lower-case SQL identifier. */
+var InvalidDatabasePrefix = class extends Schema.TaggedError()("InvalidDatabasePrefix", { prefix: Schema.String }) {
+	get message() {
+		return `database-name prefix '${this.prefix}' must match ${DATABASE_PREFIX.source}`;
+	}
+};
+/**
+* The deterministic per-checkout database name
+* `<prefix>_test_<sha256(migrationsDir)[:8]>`: concurrent runs from different
+* worktrees never collide, and a stale database self-heals on the next run.
+*/
+const testDatabaseName = (options) => Effect.gen(function* () {
+	if (!DATABASE_PREFIX.test(options.prefix)) return yield* new InvalidDatabasePrefix({ prefix: options.prefix });
+	const digest = yield* Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(options.migrationsDir)));
+	const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 8);
+	return `${options.prefix}_test_${hex}`;
+});
+/** One connection attempt against a server's admin database failed. */
+var ServerUnreachable = class extends Schema.TaggedError()("ServerUnreachable", { cause: Schema.Defect() }) {};
+/** A `SELECT 1` over one short-lived connection. */
+const probeServer = (adminUrl) => Effect.gen(function* () {
+	yield* (yield* PgClient.PgClient)`SELECT 1`;
+}).pipe(Effect.provide(PgClient.layer({
+	url: adminUrl,
+	maxConnections: 1,
+	connectTimeout: CONNECT_TIMEOUT
+})), Effect.mapError((cause) => new ServerUnreachable({ cause })));
+/** An explicit but unreachable `PG*` target: this run will not fall back to a container. */
+var DatabaseUnreachable = class extends Schema.TaggedError()("DatabaseUnreachable", {
+	server: Schema.String,
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return [
+			`no PostgreSQL server at ${this.server}.`,
+			"PG* variables are set, so this run will not fall back to Testcontainers —",
+			"fix the PG* target, unset it to let the suite start its own server, or set",
+			"DATABASE_URL_TEST to an already-migrated database."
+		].join("\n");
+	}
+};
+/**
+* Resolve where a run's database comes from, in the order the module doc
+* describes: an explicit URL, then a reachable local server (an explicit but
+* unreachable `PG*` target is a {@link DatabaseUnreachable}), then the
+* Testcontainers fallback. Pure apart from the one probe, which only runs
+* when no explicit URL is set.
+*/
+const resolveDatabaseSource = (options) => Effect.gen(function* () {
+	const { env } = options;
+	const explicit = env.DATABASE_URL_TEST ?? env.DATABASE_URL ?? "";
+	if (explicit !== "") return {
+		_tag: "Explicit",
+		url: Redacted.make(explicit)
+	};
+	const database = yield* testDatabaseName({
+		prefix: options.dbNamePrefix,
+		migrationsDir: options.migrationsDir
+	});
+	const adminUrl = connectionUrl(env, "postgres");
+	if (yield* (options.probe ?? probeServer)(adminUrl).pipe(Effect.as(true), Effect.catchTag("ServerUnreachable", (unreachable) => serverExplicitlyConfigured(env) ? Effect.fail(new DatabaseUnreachable({
+		server: serverLabel(env),
+		cause: unreachable.cause
+	})) : Effect.succeed(false)))) return {
+		_tag: "LocalServer",
+		adminUrl,
+		database,
+		url: connectionUrl(env, database)
+	};
+	return {
+		_tag: "Container",
+		image: options.image
+	};
+});
+/** Starting the Testcontainers fallback failed — most often, no Docker daemon. */
+var ContainerStartFailed = class extends Schema.TaggedError()("ContainerStartFailed", {
+	image: Schema.String,
+	server: Schema.String,
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return [
+			`no PostgreSQL server at ${this.server}, and starting a ${this.image} container via`,
+			"Testcontainers failed — is a Docker daemon available (and `@testcontainers/postgresql`",
+			"installed)? The suite needs one of:",
+			"  - a Docker daemon, or",
+			"  - a local PostgreSQL server, with PGHOST/PGPORT/PGUSER/PGPASSWORD pointing at it, or",
+			"  - DATABASE_URL_TEST set to an already-migrated database to skip provisioning."
+		].join("\n");
+	}
+};
+/** The default {@link MigrationRunner}: `./migrations` over a one-connection client. */
+const defaultRunner = (migrationsDir) => (url) => applyMigrations(migrationsDir).pipe(Effect.provide(PgClient.layer({
+	url,
+	maxConnections: 1
+})));
+/** Drop and recreate this checkout's database on the reachable server. */
+const recreateDatabase = (source) => Effect.gen(function* () {
+	const admin = yield* PgClient.PgClient;
+	yield* admin.unsafe(`DROP DATABASE IF EXISTS "${source.database}" WITH (FORCE)`);
+	yield* admin.unsafe(`CREATE DATABASE "${source.database}"`);
+}).pipe(Effect.provide(PgClient.layer({
+	url: source.adminUrl,
+	maxConnections: 1,
+	connectTimeout: CONNECT_TIMEOUT
+})));
+/**
+* Start a fresh server via Testcontainers, stopped when the scope closes. The
+* import is dynamic so a run that found a reachable server never loads the
+* library or talks to Docker at all.
+*/
+const startContainer = (image, server) => Effect.acquireRelease(Effect.tryPromise({
+	try: async () => {
+		const { PostgreSqlContainer } = await import("@testcontainers/postgresql");
+		return new PostgreSqlContainer(image).start();
+	},
+	catch: (cause) => new ContainerStartFailed({
+		image,
+		server,
+		cause
+	})
+}), (container) => Effect.promise(() => container.stop())).pipe(Effect.map((container) => Redacted.make(container.getConnectionUri())));
+/**
+* Provision a run's fresh, fully-migrated database — resolve the source,
+* then drop / create / migrate on a reachable server, or start and migrate a
+* container — and return its URL. An explicit source is returned as-is.
+*
+* Scoped: a started container stops when the scope closes. From a vitest
+* global setup, hold a `Scope` across the run and close it in the returned
+* teardown:
+*
+* @example
+* ```ts
+* // vitest global setup
+* import * as NodeServices from "@effect/platform-node/NodeServices";
+* import { provisionTestDatabase } from "@thomasfosterau/effect-drizzle-ext-pg/testing";
+* import * as Effect from "effect/Effect";
+* import * as Exit from "effect/Exit";
+* import * as Redacted from "effect/Redacted";
+* import * as Scope from "effect/Scope";
+*
+* const MIGRATIONS_DIR = "packages/database/migrations";
+*
+* export default async function setup() {
+*   const scope = Effect.runSync(Scope.make());
+*   const database = await Effect.runPromise(
+*     provisionTestDatabase({
+*       env: process.env,
+*       migrationsDir: MIGRATIONS_DIR,
+*       dbNamePrefix: "website",
+*       image: "pgvector/pgvector:pg17",
+*     }).pipe(Scope.provide(scope), Effect.provide(NodeServices.layer)),
+*   );
+*   process.env.DATABASE_URL_TEST = Redacted.value(database.url);
+*   return () => Effect.runPromise(Scope.close(scope, Exit.void));
+* }
+* ```
+*/
+const provisionTestDatabase = (options) => Effect.gen(function* () {
+	const source = yield* resolveDatabaseSource(options);
+	if (Predicate.isTagged(source, "Explicit")) return {
+		url: source.url,
+		source
+	};
+	const url = Predicate.isTagged(source, "LocalServer") ? yield* recreateDatabase(source).pipe(Effect.as(source.url)) : yield* startContainer(source.image, serverLabel(options.env));
+	const applied = yield* (options.applyMigrations ?? defaultRunner(options.migrationsDir))(url);
+	yield* Effect.logInfo(`provisioned ${Predicate.isTagged(source, "LocalServer") ? `'${source.database}'` : `a ${source.image} container`} (${applied} migrations)`);
+	return {
+		url,
+		source
+	};
+}).pipe(Effect.withLogSpan("provisionTestDatabase"));
+// src/testing.ts
+/**
+* The `operation` labels `@effect/sql-pg` stamps on a connect/acquire-seam
+* `SqlError` reason. A failure carrying one of these happened while opening a
+* connection, i.e. before any transaction body ran.
+*/
+const CONNECT_SEAM_OPERATIONS = HashSet.make("acquireConnection", "connect");
+/**
+* Whether `error` is a `SqlError` that failed at the connect/acquire seam and
+* so is safe to retry (when the caller has also confirmed no test body ran).
+*
+* Returns `true` for:
+*  - any reason the driver already flags `isRetryable` (`ConnectionError` from
+*    an `08xxx` SQLSTATE, `DeadlockError`, `SerializationError`, the timeout
+*    reasons), and
+*  - a reason whose `operation` is a connect/acquire seam label, which catches
+*    the misclassified `UnknownError` the website #1055 flake surfaces as
+*    (pool "timeout exceeded when trying to connect" / `ECONNRESET`, neither
+*    of which carries an `08` SQLSTATE).
+*
+* Returns `false` for a `UniqueViolation` / `ConstraintError` /
+* `SqlSyntaxError` raised by a test's own query (`operation === "execute"`),
+* so genuine test failures are never retried.
+*/
+const isRetryableConnectFailure = (error) => {
+	if (!isSqlError(error)) return false;
+	if (error.isRetryable) return true;
+	const operation = error.reason.operation;
+	return operation !== void 0 && HashSet.has(CONNECT_SEAM_OPERATIONS, operation);
+};
+/**
+* `maxConnections` is pinned to 1 because a fork runs its tests strictly
+* sequentially and the runner holds exactly one transaction-bound connection
+* at a time (the whole test body runs inside a single `db.transaction`, with
+* the spec's own `transact` nesting a SAVEPOINT on that same connection) — so
+* 1 is the real per-fork demand, not a compromise. It is also what forces an
+* operation-opened transaction to nest as a SAVEPOINT on the same connection
+* (and so see the outer transaction's uncommitted writes) rather than
+* silently acquiring a second connection that cannot.
+*/
+const TEST_POOL_MAX_CONNECTIONS = 1;
+/**
+* How long a single connection attempt may take before the driver gives up.
+*
+* Under fork parallelism all forks race to open their connection at once
+* while each imports the module graph, so at startup the connect handshakes
+* contend. A generous per-attempt timeout costs nothing on the happy path (a
+* healthy connect resolves in milliseconds and never approaches this
+* ceiling), so it stays as cheap insurance for slow CI service-container
+* startup.
+*/
+const TEST_CONNECT_TIMEOUT = Duration.seconds(30);
+/** Sentinel cause used to force the outer test transaction to roll back. */
+const ROLLBACK_TAG = "__effect_test_rollback__";
+const rollback = { _tag: ROLLBACK_TAG };
+const isRollback = (u) => Predicate.isObjectOrArray(u) && Predicate.isTagged(u, ROLLBACK_TAG);
+/**
+* Whether a captured failure cause carries the rollback sentinel.
+*
+* Effect causes are nested objects; this is a structural walk that finds the
+* rollback tag without depending on `Cause` internals.
+*/
+const causeContainsRollback = (cause) => {
+	const seen = /* @__PURE__ */ new Set();
+	const stack = [cause];
+	while (Arr.isReadonlyArrayNonEmpty(stack)) {
+		const node = stack.pop();
+		if (!Predicate.isObjectOrArray(node) || seen.has(node)) continue;
+		seen.add(node);
+		if (isRollback(node)) return true;
+		Arr.forEach(Array.isArray(node) ? node : Record.values(node), (value) => {
+			stack.push(value);
+		});
+	}
+	return false;
+};
+const CONNECT_RETRY_ATTEMPTS = 5;
+const CONNECT_RETRY_BASE_DELAY = Duration.millis(250);
+const connectRetrySchedule = Schedule.max([Schedule.exponential(CONNECT_RETRY_BASE_DELAY), Schedule.recurs(CONNECT_RETRY_ATTEMPTS)]).pipe(Schedule.jittered);
+/**
+* A failure of the runner itself rather than of the spec it ran: the outer
+* transaction failed before the spec's `Exit` was captured, or failed with
+* something other than the rollback sentinel. Thrown (rejecting the runner's
+* Promise), never put in an Effect error channel — the runner is the test
+* harness's boundary.
+*/
+var TestTransactionError = class extends Schema.TaggedError()("TestTransactionError", { message: Schema.String }) {};
+/**
+* Builds the always-rollback test transaction runner for one application's
+* database services.
+*
+* The services carry the key strings and the `transact` boundary, so the
+* runner needs nothing else: a suite calls this once next to its
+* {@link makePgDatabase} call and exports the three helpers.
+*/
+const makeTestTransaction = (database) => {
+	const runInTestTransaction = async (runtime, effect) => {
+		let captured = null;
+		const program = Effect.gen(function* () {
+			return yield* (yield* database.Database).transaction(() => Effect.gen(function* () {
+				captured = yield* Effect.exit(database.transact(effect));
+				return yield* Effect.fail(rollback);
+			}));
+		}).pipe(Effect.retry({
+			schedule: connectRetrySchedule,
+			while: (e) => captured === null && isRetryableConnectFailure(e)
+		}));
+		const outer = await runtime.runPromiseExit(program);
+		const innerExit = captured;
+		if (!innerExit) {
+			if (Exit.isFailure(outer)) throw new TestTransactionError({ message: `runInTestTransaction: outer transaction failed: ${String(outer.cause)}` });
+			throw new TestTransactionError({ message: "runInTestTransaction: inner Exit was never captured" });
+		}
+		if (Exit.isFailure(outer) && !causeContainsRollback(outer.cause)) throw new TestTransactionError({ message: `runInTestTransaction: unexpected outer failure: ${String(outer.cause)}` });
+		if (Exit.isSuccess(innerExit)) return innerExit.value;
+		throw Cause.squash(innerExit.cause);
+	};
+	return {
+		runInTestTransaction,
+		withTestTransaction: (runtime) => (effect) => runInTestTransaction(runtime, effect),
+		attemptInSavepoint: (effect) => Effect.gen(function* () {
+			const tx = yield* database.CurrentTransaction;
+			return yield* Effect.exit(tx.transaction(() => effect));
+		})
+	};
+};
+/**
+* The `Database` layer an integration suite runs against: the application's
+* own {@link PgDatabase.layer} over a `PgClient` built from `url`, with the
+* pool pinned to one connection (see {@link TEST_POOL_MAX_CONNECTIONS}).
+*
+* Built once per process and reused by every spec in it. `url` is the
+* caller's: this library does not read `DATABASE_URL_TEST` or decide how a
+* test database is provisioned.
+*
+* Unlike production, this uses the pinging {@link pgClientFromUrl} on
+* purpose — a suite that cannot reach its database should fail at layer build
+* with one legible `SqlError`, not once per spec on the first query.
+*/
+const testDatabaseLayer = (database, options) => database.layer.pipe(Layer.provide(pgClientFromUrl({
+	url: options.url,
+	maxConnections: TEST_POOL_MAX_CONNECTIONS,
+	connectTimeout: options.connectTimeout ?? TEST_CONNECT_TIMEOUT
+})));
+export { ContainerStartFailed, DatabaseUnreachable, InvalidDatabasePrefix, ServerUnreachable, connectionUrl, isRetryableConnectFailure, makeTestTransaction, probeServer, provisionTestDatabase, resolveDatabaseSource, testDatabaseLayer, testDatabaseName };
+
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":[],"sources":["../src/provisioning.ts","../src/testing.ts"],"mappings":"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"}

package/dist/tooling/index.d.ts

@@ -0,0 +1,217 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
+import { PlatformError } from "effect/PlatformError";
+/**
+ * drizzle-kit's sentinel for "no real parent" (its `originUUID`): the genesis
+ * migration's `prevIds` names this instead of being empty.
+ */
+export declare const ROOT_SENTINEL_ID = "00000000-0000-0000-0000-000000000000";
+/** The identity every snapshot must carry for the DAG checks. */
+interface Snapshot {
+  readonly id: string;
+  readonly prevIds: ReadonlyArray<string>;
+}
+/** One migration directory and its snapshot's identity. */
+interface SnapshotEntry {
+  readonly dir: string;
+  readonly snapshot: Snapshot;
+}
+declare const MalformedSnapshot_base: Schema.Class<MalformedSnapshot, Schema.TaggedStruct<"MalformedSnapshot", {
+  readonly file: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** A snapshot.json could not be read as a drizzle-kit snapshot. */
+export declare class MalformedSnapshot extends MalformedSnapshot_base {
+  get message(): string;
+}
+declare const SchemaDiffError_base: Schema.Class<SchemaDiffError, Schema.TaggedStruct<"SchemaDiffError", {
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * drizzle-kit itself failed while generating or diffing a snapshot — broken
+ * input (a schema module drizzle-kit cannot read) rather than drift.
+ */
+export declare class SchemaDiffError extends SchemaDiffError_base {
+  get message(): string;
+}
+declare const MigrationDriftError_base: Schema.Class<MigrationDriftError, Schema.TaggedStruct<"MigrationDriftError", {
+  readonly issues: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** The gate found problems; `issues` holds one human-readable report per violation. */
+export declare class MigrationDriftError extends MigrationDriftError_base {
+  get message(): string;
+}
+/** Snapshots not named in any other snapshot's `prevIds` — the DAG's tips. */
+export declare const findHeads: (entries: ReadonlyArray<SnapshotEntry>) => ReadonlyArray<SnapshotEntry>;
+/**
+ * Every snapshot id is unique, every `prevIds` reference resolves (or is
+ * {@link ROOT_SENTINEL_ID}), the lineage has exactly one head and no cycle,
+ * and every snapshot is reachable from that head. One human-readable report
+ * per violation; empty when clean.
+ */
+export declare const checkDagIntegrity: (entries: ReadonlyArray<SnapshotEntry>) => ReadonlyArray<string>;
+/** The base branch's migration state: its directory names and its latest-by-name snapshot. */
+interface BaseMigrations {
+  readonly ref: string;
+  readonly dirs: ReadonlyArray<string>;
+  readonly head: Option.Option<SnapshotEntry>;
+}
+/**
+ * Every migration this branch ADDS must descend from the base's current
+ * head. Presence of the base head's snapshot id in this checkout's entries is
+ * sufficient: {@link checkDagIntegrity} separately proves the local DAG has a
+ * single head from which everything is reachable, so containing the base head
+ * means the new tail grew on top of it. A branch that adds no migration
+ * directory passes.
+ */
+export declare const checkBaseAncestry: (entries: ReadonlyArray<SnapshotEntry>, base: BaseMigrations) => ReadonlyArray<string>;
+/** The environment {@link resolveBaseRef} reads — the shape of `process.env`. */
+interface BaseRefEnvironment {
+  readonly [name: string]: string | undefined;
+}
+/**
+ * The base ref for the ancestry check, when one is knowable: an explicit
+ * `MIGRATION_BASE_REF` wins (local use: `MIGRATION_BASE_REF=origin/trunk`),
+ * else `origin/$GITHUB_BASE_REF` — which GitHub Actions sets only on
+ * `pull_request` events, so pushes and local runs skip the check.
+ */
+export declare const resolveBaseRef: (env: BaseRefEnvironment) => Option.Option<string>;
+/** Where the base branch's migrations are read from, through `git`. */
+interface GitBase {
+  /** The base ref, e.g. `origin/trunk` — from {@link resolveBaseRef}. */
+  readonly ref: string;
+  /** The migrations directory relative to the repository root, e.g. `packages/database/migrations`. */
+  readonly migrationsPath: string;
+  /** The repository checkout to run `git` in. */
+  readonly cwd: string;
+}
+/**
+ * The base branch's migration state, read with `git ls-tree` / `git show` so
+ * it reflects the base's CURRENT tip. Fetches the base first when the
+ * checkout lacks it (a shallow pull-request checkout does).
+ */
+export declare const readBaseMigrations: (base: GitBase) => Effect.Effect<BaseMigrations, PlatformError, ChildProcessSpawner>;
+/** The inputs {@link checkMigrationDrift} takes. */
+interface MigrationDriftOptions {
+  /** The schema module (`import * as schema from "./schema.ts"`), as drizzle-kit's `generateDrizzleJson` takes it. */
+  readonly schema: Record<string, unknown>;
+  /** The committed drizzle-kit migrations directory. */
+  readonly migrationsDir: string;
+  /**
+   * The base branch to check ancestry against — `Option.none()` (or absent,
+   * or `undefined`) on pushes and local runs, which is what mapping
+   * {@link resolveBaseRef} gives outside a pull request.
+   */
+  readonly base?: Option.Option<GitBase> | undefined;
+}
+/** What a passing run checked. */
+interface MigrationDriftReport {
+  readonly snapshots: number;
+  readonly baseRef: Option.Option<string>;
+}
+/**
+ * Run the three checks. Succeeds with a {@link MigrationDriftReport};
+ * fails with a {@link MigrationDriftError} carrying every issue found.
+ *
+ * @example
+ * ```ts
+ * // An application's `db:migration-drift` task, run with `NodeRuntime.runMain`.
+ * import * as NodeServices from "@effect/platform-node/NodeServices";
+ * import { checkMigrationDrift, resolveBaseRef } from "@thomasfosterau/effect-drizzle-ext-pg/tooling";
+ * import { integer, pgTable } from "drizzle-orm/pg-core";
+ * import * as Effect from "effect/Effect";
+ * import * as Option from "effect/Option";
+ * import * as path from "node:path";
+ *
+ * const schema = { widget: pgTable("widget", { id: integer().primaryKey() }) };
+ * const repoRoot = process.cwd();
+ * const base = Option.map(resolveBaseRef(process.env), (ref) => ({
+ *   ref,
+ *   migrationsPath: "packages/database/migrations",
+ *   cwd: repoRoot,
+ * }));
+ * export const program = checkMigrationDrift({
+ *   schema,
+ *   migrationsDir: path.join(repoRoot, "packages/database/migrations"),
+ *   base,
+ * }).pipe(Effect.provide(NodeServices.layer));
+ * ```
+ */
+export declare const checkMigrationDrift: (options: MigrationDriftOptions) => Effect.Effect<MigrationDriftReport, MigrationDriftError | MalformedSnapshot | SchemaDiffError | PlatformError, FileSystem.FileSystem | Path.Path | ChildProcessSpawner>;
+/** One view as drizzle-kit would create it. */
+interface ViewDefinition {
+  readonly schema: string;
+  readonly name: string;
+  readonly sql: string;
+}
+/** A view that selects from another view. */
+interface ViewEdge {
+  readonly from: ViewDefinition;
+  readonly to: ViewDefinition;
+}
+/** `schema.name`, the identity used in messages and in reference matching. */
+export declare const viewKey: (view: {
+  readonly schema: string;
+  readonly name: string;
+}) => string;
+/** Every `CREATE VIEW` in a statement list, as {@link ViewDefinition}s. */
+export declare const parseViewDefinitions: (statements: ReadonlyArray<string>) => ReadonlyArray<ViewDefinition>;
+/**
+ * Whether `definition` selects from `target`.
+ *
+ * Matches both spellings a definition can carry: the quoted,
+ * schema-qualified form Drizzle's query builder emits (`"app"."work_view"`),
+ * and the bare form a hand-written `sql.raw` FROM clause may use
+ * (`app.work_view`), guarded so it cannot fire on a longer identifier ending
+ * the same way. A derived table aliased with a view's *unqualified* name is
+ * deliberately not a match — it names no schema, so references no view.
+ * The one blind spot that leaves: a hand-written FROM naming a view
+ * unqualified and leaning on `search_path`.
+ */
+export declare const referencesView: (definition: ViewDefinition, target: ViewDefinition) => boolean;
+/** Every view-on-view edge among `views`. Empty is the passing state. */
+export declare const findViewEdges: (views: ReadonlyArray<ViewDefinition>) => ReadonlyArray<ViewEdge>;
+declare const ViewDependencyError_base: Schema.Class<ViewDependencyError, Schema.TaggedStruct<"ViewDependencyError", {
+  readonly edges: Schema.$Array<Schema.Struct<{
+    readonly from: Schema.String;
+    readonly to: Schema.String;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
+/** The schema has at least one view-on-view edge. */
+export declare class ViewDependencyError extends ViewDependencyError_base {
+  get message(): string;
+}
+/**
+ * Generate the whole schema from an empty snapshot — every view exactly as a
+ * migration would create it — and assert no definition references another
+ * view. Succeeds with the number of views checked.
+ *
+ * @example
+ * ```ts
+ * // An application's `db:view-dependencies` task passes its own schema module.
+ * import { checkViewDependencies } from "@thomasfosterau/effect-drizzle-ext-pg/tooling";
+ * import { integer, pgTable, pgView, text } from "drizzle-orm/pg-core";
+ * import * as Effect from "effect/Effect";
+ *
+ * const article = pgTable("article", { id: integer().primaryKey(), title: text().notNull() });
+ * const articleTitles = pgView("article_titles").as((qb) =>
+ *   qb.select({ title: article.title }).from(article),
+ * );
+ *
+ * const { viewCount } = await Effect.runPromise(
+ *   checkViewDependencies({ schema: { article, articleTitles } }),
+ * );
+ * console.log(viewCount); // 1
+ * ```
+ */
+export declare const checkViewDependencies: (options: {
+  readonly schema: Record<string, unknown>;
+}) => Effect.Effect<{
+  readonly viewCount: number;
+}, ViewDependencyError | SchemaDiffError>;
+export type { BaseMigrations, BaseRefEnvironment, GitBase, MigrationDriftOptions, MigrationDriftReport, Snapshot, SnapshotEntry, ViewDefinition, ViewEdge };
+//# sourceMappingURL=index.d.ts.map

package/dist/tooling/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/tooling/migration-drift.ts","../../src/tooling/view-dependencies.ts"],"mappings":";;;;;;;;;;;qBA+Da;;UAMI;WACN;WACA,SAAS;;;UAIH;WACN;WACA,UAAU;;;;;;;qBAsCR,0BAA0B;MAIxB;;;;;;;;;qBASF,wBAAwB;MAGtB;;;;;;qBAUF,4BAA4B;MAI1B;;;qBAQF,YAAS,SAAa,cAAc,mBAAiB,cAAc;;;;;;;qBA0EnE,oBAAiB,SAAa,cAAc,mBAAiB;;UAiEzD;WACN;WACA,MAAM;WACN,MAAM,OAAO,OAAO;;;;;;;;;;qBAWlB,oBAAiB,SACnB,cAAc,gBAAc,MAC/B,mBACL;;UAiBc;YAEL;;;;;;;;qBASC,iBAAc,KAAS,uBAAqB,OAAO;;UA6E/C;;WAEN;;WAEA;;WAEA;;;;;;;qBAqCE,qBAAkB,MACvB,YACL,OAAO,OAAO,gBAAgB,eAAe;;UA6G/B;;WAGN,QAAQ;;WAER;;;;;;WAOA,OAAO,OAAO,OAAO;;;UAIf;WACN;WACA,SAAS,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA+Bd,sBAAmB,SACrB,0BACR,OAAO,OACR,sBACA,sBAAsB,oBAAoB,kBAAkB,eAC5D,WAAW,aAAa,KAAK,OAAO;;UCxkBrB;WACN;WACA;WACA;;;UAIM;WACN,MAAM;WACN,IAAI;;;qBAUF,UAAO;WAAqB;WAAyB;;;qBAIrD,uBAAoB,YACnB,0BACX,cAAc;;;;;;;;;;;;;qBAyBJ,iBAAc,YAAgB,gBAAc,QAAU;;qBAQtD,gBAAa,OAAW,cAAc,oBAAkB,cAAc;;;;;;;;qBAMtE,4BAA4B;MAM1B;;;;;;;;;;;;;;;;;;;;;;;;;qBA6CF,wBAAqB;WACvB,QAAQ;MACf,OAAO;WAAkB;GAAqB,sBAAsB"}