@satorio/machinery 0.2.1

package/dist/vitest/port-contracts/transaction-boundary.contract.js

@@ -0,0 +1,64 @@
+import { describe, expect } from '@effect/vitest';
+import { TransactionBoundary } from '@satorio/machinery/ports';
+import { Effect, Ref } from 'effect';
+const WORK_REFUSED = 'the domain said no';
+/**
+ * One contract, every transaction boundary. The same body runs against an
+ * in-memory boundary and a live Postgres transaction, so a difference
+ * between them shows up as a red test, not a surprise in production.
+ * Hand it the port's unavailable stand-in as a fourth argument and it
+ * walks the refusal too: the work never runs, and the failure reaches
+ * the caller.
+ *
+ * What this contract cannot prove: that what the work wrote is what gets
+ * rolled back. An in-memory boundary restores the `Ref`s it was handed as
+ * participants; a Postgres one rolls back a real transaction and knows
+ * nothing about `Ref`s. Both promises are held here through a `Ref` the
+ * work updates and the boundary never sees, so the assertions read the
+ * same on both sides — and the Postgres half, where a row written inside
+ * a failed transaction is gone afterwards, is owned by
+ * `src/postgres/ports.postgres.test.ts`.
+ */
+export const transactionBoundaryContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`TransactionBoundary contract (${implementationName})`, () => {
+        it.effect('work that succeeds answers with its own value', () => run(Effect.gen(function* () {
+            const boundary = yield* TransactionBoundary;
+            const answer = yield* boundary.inTransaction(Effect.succeed('committed'));
+            expect(answer).toBe('committed');
+        })));
+        it.effect("the work's own failure reaches the caller unchanged", () => run(Effect.gen(function* () {
+            const boundary = yield* TransactionBoundary;
+            const failure = yield* Effect.flip(boundary.inTransaction(Effect.fail(WORK_REFUSED)));
+            expect(failure).toBe(WORK_REFUSED);
+        })));
+        it.effect('every step of the work runs inside one boundary', () => run(Effect.gen(function* () {
+            const boundary = yield* TransactionBoundary;
+            const steps = yield* Ref.make([]);
+            yield* boundary.inTransaction(Effect.gen(function* () {
+                yield* Ref.update(steps, (taken) => [...taken, 'first']);
+                yield* Ref.update(steps, (taken) => [...taken, 'second']);
+            }));
+            expect(yield* Ref.get(steps)).toEqual(['first', 'second']);
+        })));
+        it.effect('one boundary nests inside another without deadlocking', () => run(Effect.gen(function* () {
+            const boundary = yield* TransactionBoundary;
+            const answer = yield* boundary.inTransaction(boundary.inTransaction(Effect.succeed('inner')));
+            expect(answer).toBe('inner');
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`TransactionBoundary contract (${implementationName}, not mounted)`, () => {
+        it.effect('the work never runs, and the caller reads the refusal', () => Effect.gen(function* () {
+            const boundary = yield* TransactionBoundary;
+            const ran = yield* Ref.make(false);
+            const failure = yield* Effect.flip(boundary.inTransaction(Ref.set(ran, true)));
+            expect(failure._tag).toBe('TransactionBoundaryUnavailableError');
+            if (failure._tag === 'TransactionBoundaryUnavailableError') {
+                expect(failure.operation).toBe('inTransaction');
+            }
+            expect(yield* Ref.get(ran)).toBe(false);
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/postgres-container.d.ts

@@ -0,0 +1,57 @@
+import { SqlClient } from '@effect/sql';
+import type { PgClient } from '@effect/sql-pg';
+import { type Vitest } from '@effect/vitest';
+import { type PostgresPorts } from '@satorio/machinery/postgres';
+import { Layer } from 'effect';
+/**
+ * The Postgres image every live-stand test starts through testcontainers.
+ * This package ships no `docker-compose.yml` of its own, so nothing here
+ * proves this pin against a compose file. A consumer that also runs a
+ * local docker-compose Postgres (see `onPostgres`'s fallback path) MUST
+ * assert its own compose file's image equals this constant — that
+ * cross-check is the real guard, in that consumer's own
+ * `guards/postgres-image.test.ts`.
+ */
+export declare const POSTGRES_IMAGE = "postgres:16-alpine";
+type SuiteChecks = (it: Vitest.MethodsNonLive<never, true>) => void;
+/**
+ * @internal
+ */
+export interface PostgresSuiteOptions {
+    readonly schema: string;
+    readonly migrationDirectories?: readonly string[];
+}
+/**
+ * The Postgres layer a suite runs on: the configured database when the
+ * environment names one, a fresh container when it does not, migrated either
+ * way.
+ */
+export declare const postgresUnderTestLive: (options: PostgresSuiteOptions) => Layer.Layer<never>;
+/**
+ * Builds the Postgres layer for a suite from a fresh container only,
+ * ignoring any `PG*` environment variables. Use this instead of
+ * `postgresUnderTestLive` when a suite must prove itself against a real
+ * container, not whatever database happens to be configured.
+ */
+export declare const postgresInContainerLive: (options: PostgresSuiteOptions) => Layer.Layer<never>;
+/**
+ * Runs a suite against a real Postgres — the container, or an externally
+ * configured database when `PGHOST` is set. Pass `checks` to declare the
+ * tests.
+ */
+export declare const onPostgres: (options: PostgresSuiteOptions, subject: string, checks: SuiteChecks) => void;
+/**
+ * Runs a suite against a container-only Postgres, ignoring any `PG*`
+ * environment variables. Use this over `onPostgres` when a suite must
+ * prove the container path itself, not whichever database is configured.
+ * Pass `checks` to declare the tests.
+ */
+export declare const onPostgresContainer: (options: PostgresSuiteOptions, subject: string, checks: SuiteChecks) => void;
+/**
+ * The Postgres mechanism's own ports, on the suite's database. A failure to
+ * mount the database client folds into a defect rather than a typed error,
+ * since inside a suite that is a broken harness, not a scenario the test
+ * should handle.
+ */
+export declare const PostgresPortsUnderTestLive: Layer.Layer<PostgresPorts | PgClient.PgClient | SqlClient.SqlClient>;
+export {};

package/dist/vitest/postgres-container.js

@@ -0,0 +1,118 @@
+import { BunFileSystem } from '@effect/platform-bun';
+import { SqlClient } from '@effect/sql';
+import { layer } from '@effect/vitest';
+import { applyMigrations, DEFAULT_POSTGRES_PORT, MACHINERY_MIGRATIONS_DIRECTORY, PostgresClientLive, PostgresPortsOnBunLive, postgresConnectionSettings, } from '@satorio/machinery/postgres';
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+import { Config, ConfigProvider, Duration, Effect, Layer, Logger, Option, } from 'effect';
+import { Wait } from 'testcontainers';
+import { standsMayBeReused } from './container-reuse.js';
+/**
+ * The Postgres image every live-stand test starts through testcontainers.
+ * This package ships no `docker-compose.yml` of its own, so nothing here
+ * proves this pin against a compose file. A consumer that also runs a
+ * local docker-compose Postgres (see `onPostgres`'s fallback path) MUST
+ * assert its own compose file's image equals this constant — that
+ * cross-check is the real guard, in that consumer's own
+ * `guards/postgres-image.test.ts`.
+ */
+export const POSTGRES_IMAGE = 'postgres:16-alpine';
+const CONTAINER_DATABASE = 'app';
+const CONTAINER_USER = 'app';
+const CONTAINER_PASSWORD = 'app';
+const SUITE_STARTUP_BUDGET = Duration.minutes(3);
+const POSTGRES_READY_LOG_MESSAGE = /database system is ready to accept connections/;
+const REUSING_STANDS = standsMayBeReused();
+const startedContainer = Effect.acquireRelease(Effect.promise(() => {
+    const container = new PostgreSqlContainer(POSTGRES_IMAGE)
+        .withDatabase(CONTAINER_DATABASE)
+        .withUsername(CONTAINER_USER)
+        .withPassword(CONTAINER_PASSWORD)
+        .withWaitStrategy(Wait.forLogMessage(POSTGRES_READY_LOG_MESSAGE, 2));
+    return (REUSING_STANDS ? container.withReuse() : container).start();
+}), (container) => REUSING_STANDS ? Effect.void : Effect.promise(() => container.stop()));
+const externallyConfiguredDatabase = Config.all({
+    host: Config.string('PGHOST'),
+    port: Config.integer('PGPORT').pipe(Config.withDefault(DEFAULT_POSTGRES_PORT)),
+    user: Config.string('PGUSER'),
+    password: Config.string('PGPASSWORD'),
+    database: Config.string('PGDATABASE'),
+});
+const containerDatabase = Effect.map(startedContainer, (container) => ({
+    host: container.getHost(),
+    port: container.getPort(),
+    user: container.getUsername(),
+    password: container.getPassword(),
+    database: container.getDatabase(),
+}));
+const databaseUnderTest = Effect.flatMap(Config.option(externallyConfiguredDatabase), Option.match({
+    onSome: (Effect.succeed),
+    onNone: () => containerDatabase,
+}));
+const connectionSettingsOf = (database, schema) => ConfigProvider.fromMap(new Map([
+    ['PGHOST', database.host],
+    ['PGPORT', String(database.port)],
+    ['PGUSER', database.user],
+    ['PGPASSWORD', database.password],
+    ['PGDATABASE', database.database],
+    ['PGSCHEMA', schema],
+    ['AUTH_MODE', 'password'],
+    ['PGSSLMODE', 'disable'],
+]));
+const MIGRATOR_TRACKING_TABLE = 'effect_sql_migrations';
+const truncateEverythingIn = (schema) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const tables = yield* sql `SELECT tablename FROM pg_tables
+       WHERE schemaname = ${schema} AND tablename != ${MIGRATOR_TRACKING_TABLE}`;
+    if (tables.length === 0)
+        return;
+    const quoted = tables
+        .map((table) => `"${schema}"."${table.tablename}"`)
+        .join(', ');
+    yield* sql.unsafe(`TRUNCATE TABLE ${quoted} RESTART IDENTITY CASCADE`);
+});
+const migratedSchema = (migrationDirectories) => Layer.effectDiscard(Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const settings = yield* postgresConnectionSettings;
+    yield* sql.unsafe(`CREATE SCHEMA IF NOT EXISTS "${settings.schema}"`);
+    yield* applyMigrations(migrationDirectories);
+    yield* truncateEverythingIn(settings.schema);
+})).pipe(Layer.provide(PostgresClientLive), Layer.provide(BunFileSystem.layer), Layer.orDie);
+const migratedIn = (database, schema, migrationDirectories) => Layer.unwrapScoped(Effect.map(database, (connection) => migratedSchema(migrationDirectories).pipe(Layer.provideMerge(Layer.setConfigProvider(connectionSettingsOf(connection, schema))), Layer.merge(Logger.remove(Logger.defaultLogger))))).pipe(Layer.orDie);
+const directoriesOf = (options) => options.migrationDirectories ?? [MACHINERY_MIGRATIONS_DIRECTORY];
+/**
+ * The Postgres layer a suite runs on: the configured database when the
+ * environment names one, a fresh container when it does not, migrated either
+ * way.
+ */
+export const postgresUnderTestLive = (options) => migratedIn(databaseUnderTest, options.schema, directoriesOf(options));
+/**
+ * Builds the Postgres layer for a suite from a fresh container only,
+ * ignoring any `PG*` environment variables. Use this instead of
+ * `postgresUnderTestLive` when a suite must prove itself against a real
+ * container, not whatever database happens to be configured.
+ */
+export const postgresInContainerLive = (options) => migratedIn(containerDatabase, options.schema, directoriesOf(options));
+const suiteOn = (postgres) => (subject, checks) => layer(postgres, {
+    excludeTestServices: true,
+    timeout: SUITE_STARTUP_BUDGET,
+})(subject, checks);
+/**
+ * Runs a suite against a real Postgres — the container, or an externally
+ * configured database when `PGHOST` is set. Pass `checks` to declare the
+ * tests.
+ */
+export const onPostgres = (options, subject, checks) => suiteOn(postgresUnderTestLive(options))(subject, checks);
+/**
+ * Runs a suite against a container-only Postgres, ignoring any `PG*`
+ * environment variables. Use this over `onPostgres` when a suite must
+ * prove the container path itself, not whichever database is configured.
+ * Pass `checks` to declare the tests.
+ */
+export const onPostgresContainer = (options, subject, checks) => suiteOn(postgresInContainerLive(options))(subject, checks);
+/**
+ * The Postgres mechanism's own ports, on the suite's database. A failure to
+ * mount the database client folds into a defect rather than a typed error,
+ * since inside a suite that is a broken harness, not a scenario the test
+ * should handle.
+ */
+export const PostgresPortsUnderTestLive = PostgresPortsOnBunLive.pipe(Layer.orDie);

package/dist/vitest/reader-port-contract.d.ts

@@ -0,0 +1,41 @@
+import { Effect } from 'effect';
+import type { PortContractTester } from './port-contract-tester.js';
+/**
+ * What a reader port's own test hands the contract. `read` and
+ * `readWhenUnavailable` come already provided with their layer, so the
+ * contract needs no context type and every implementation hands it the
+ * same shape. `givenTheWorldHolds` is the seam: a reader port never
+ * writes, so whatever put the value there — a seeder, a migration, a
+ * fixture — belongs to the implementation's own test, not to the port.
+ */
+export interface ReaderPortUnderTest<Subject, Value> {
+    readonly portName: string;
+    readonly implementationName: string;
+    readonly known: {
+        readonly subject: Subject;
+        readonly value: Value;
+    };
+    readonly unknown: Subject;
+    readonly givenTheWorldHolds: (subject: Subject, value: Value) => Effect.Effect<unknown>;
+    readonly read: (subject: Subject) => Effect.Effect<Value, {
+        readonly _tag: string;
+    }>;
+    readonly refusalWhenUnknown: string;
+    readonly readWhenUnavailable?: (subject: Subject) => Effect.Effect<Value, {
+        readonly _tag: string;
+    }>;
+    readonly refusalWhenUnavailable?: string;
+}
+/**
+ * One contract for a port that only reads. It asks the port for nothing
+ * it cannot do: no write, no round trip through its own writer. A
+ * projection, a view of another context, a rate source, a table somebody
+ * else fills — each passes this contract with a write side it does not
+ * have.
+ *
+ * What this contract cannot prove: that the world outside really holds
+ * what `givenTheWorldHolds` put there. A fake seeds its own map; a live
+ * implementation seeds the real store, and only that run proves the two
+ * agree on the shape of a row.
+ */
+export declare const readerPortContract: <Subject, Value>(it: PortContractTester, port: ReaderPortUnderTest<Subject, Value>) => void;

package/dist/vitest/reader-port-contract.js

@@ -0,0 +1,43 @@
+import { describe, expect } from '@effect/vitest';
+import { Effect } from 'effect';
+/**
+ * One contract for a port that only reads. It asks the port for nothing
+ * it cannot do: no write, no round trip through its own writer. A
+ * projection, a view of another context, a rate source, a table somebody
+ * else fills — each passes this contract with a write side it does not
+ * have.
+ *
+ * What this contract cannot prove: that the world outside really holds
+ * what `givenTheWorldHolds` put there. A fake seeds its own map; a live
+ * implementation seeds the real store, and only that run proves the two
+ * agree on the shape of a row.
+ */
+export const readerPortContract = (it, port) => {
+    describe(`${port.portName} contract (${port.implementationName})`, () => {
+        it.effect('a subject the world holds reads back what it holds', () => Effect.gen(function* () {
+            yield* port.givenTheWorldHolds(port.known.subject, port.known.value);
+            const read = yield* port.read(port.known.subject);
+            expect(read).toEqual(port.known.value);
+        }));
+        it.effect('reading twice answers twice, and holds nothing back', () => Effect.gen(function* () {
+            yield* port.givenTheWorldHolds(port.known.subject, port.known.value);
+            const first = yield* port.read(port.known.subject);
+            const second = yield* port.read(port.known.subject);
+            expect(second).toEqual(first);
+        }));
+        it.effect('a subject the world does not hold refuses by name', () => Effect.gen(function* () {
+            const refused = yield* Effect.flip(port.read(port.unknown));
+            expect(refused._tag).toBe(port.refusalWhenUnknown);
+        }));
+    });
+    const readWhenUnavailable = port.readWhenUnavailable;
+    const refusalWhenUnavailable = port.refusalWhenUnavailable;
+    if (readWhenUnavailable === undefined || refusalWhenUnavailable === undefined)
+        return;
+    describe(`${port.portName} contract (${port.implementationName}, not mounted)`, () => {
+        it.effect('a port nobody mounted refuses, and the caller reads it', () => Effect.gen(function* () {
+            const refused = yield* Effect.flip(readWhenUnavailable(port.known.subject));
+            expect(refused._tag).toBe(refusalWhenUnavailable);
+        }));
+    });
+};

package/dist/vitest/repo-source-files.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runs one git command in `cwd` with every `GIT_*` variable removed from
+ * its environment, and hands back what it printed. A hook runs with
+ * `GIT_DIR` and `GIT_INDEX_FILE` exported, and git obeys those over the
+ * directory it was given: a read would answer for the hook's repository
+ * instead of `cwd`, and a write would land in the commit that is running.
+ * Every git call this package makes goes through here for that reason.
+ *
+ * @internal
+ */
+export declare const gitOutput: (args: readonly string[], cwd: string) => string;
+/**
+ * Root of the git repository that contains `cwd` (`process.cwd()` by
+ * default). Every guard resolves its own scan root through this call, so
+ * the same guard function scans the package's own tree when the package
+ * runs its own tests, and a consumer's tree when a consumer's test file
+ * calls the guard.
+ */
+export declare const repoRoot: (cwd?: string) => string;
+/**
+ * Every file git would commit as it stands under `root`.
+ *
+ * Every file `git` would commit as-is under `root`: tracked files, plus
+ * untracked files that are not `.gitignore`d, minus tracked files deleted from
+ * the working tree but not yet staged as deleted. A guard that must hold
+ * before a file is ever committed needs this set — `git ls-files` alone misses
+ * a file still untracked, a plain filesystem walk would wrongly pull in
+ * `.gitignore`d local files such as `.env`, and skipping the deleted-file
+ * subtraction hands a guard a path that no longer exists.
+ */
+export declare const repoCommittableFiles: (root?: string) => readonly string[];
+/**
+ * Lists files with `extension` recursively under `directories`, relative
+ * to `root`. Directories are relative to `root`, and so is the result:
+ * relative POSIX paths, the format every guard and file list uses.
+ */
+export declare const repoFilesUnder: (root: string, directories: readonly string[], extension: string) => readonly string[];

package/dist/vitest/repo-source-files.js

@@ -0,0 +1,61 @@
+import { execFileSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+const withoutAmbientGit = () => Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')));
+/**
+ * Runs one git command in `cwd` with every `GIT_*` variable removed from
+ * its environment, and hands back what it printed. A hook runs with
+ * `GIT_DIR` and `GIT_INDEX_FILE` exported, and git obeys those over the
+ * directory it was given: a read would answer for the hook's repository
+ * instead of `cwd`, and a write would land in the commit that is running.
+ * Every git call this package makes goes through here for that reason.
+ *
+ * @internal
+ */
+export const gitOutput = (args, cwd) => execFileSync('git', [...args], {
+    cwd,
+    encoding: 'utf8',
+    env: withoutAmbientGit(),
+});
+/**
+ * Root of the git repository that contains `cwd` (`process.cwd()` by
+ * default). Every guard resolves its own scan root through this call, so
+ * the same guard function scans the package's own tree when the package
+ * runs its own tests, and a consumer's tree when a consumer's test file
+ * calls the guard.
+ */
+export const repoRoot = (cwd = process.cwd()) => gitOutput(['rev-parse', '--show-toplevel'], cwd).trim();
+const toPosixPath = (path) => path.split(sep).join('/');
+const walk = (root, directory, extension) => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory())
+        return walk(root, path, extension);
+    return entry.isFile() && extname(entry.name) === extension
+        ? [toPosixPath(relative(root, path))]
+        : [];
+});
+/**
+ * Every file git would commit as it stands under `root`.
+ *
+ * Every file `git` would commit as-is under `root`: tracked files, plus
+ * untracked files that are not `.gitignore`d, minus tracked files deleted from
+ * the working tree but not yet staged as deleted. A guard that must hold
+ * before a file is ever committed needs this set — `git ls-files` alone misses
+ * a file still untracked, a plain filesystem walk would wrongly pull in
+ * `.gitignore`d local files such as `.env`, and skipping the deleted-file
+ * subtraction hands a guard a path that no longer exists.
+ */
+export const repoCommittableFiles = (root = repoRoot()) => {
+    const deletedFiles = new Set(gitOutput(['ls-files', '--deleted'], root)
+        .split('\n')
+        .filter((line) => line !== ''));
+    return gitOutput(['ls-files', '--cached', '--others', '--exclude-standard'], root)
+        .split('\n')
+        .filter((line) => line !== '' && !deletedFiles.has(line));
+};
+/**
+ * Lists files with `extension` recursively under `directories`, relative
+ * to `root`. Directories are relative to `root`, and so is the result:
+ * relative POSIX paths, the format every guard and file list uses.
+ */
+export const repoFilesUnder = (root, directories, extension) => directories.flatMap((directory) => walk(root, join(root, directory), extension));

package/dist/vitest/reset-tables.d.ts

@@ -0,0 +1,18 @@
+import { SqlClient } from '@effect/sql';
+import type { SqlError } from '@effect/sql/SqlError';
+import { Effect } from 'effect';
+/**
+ * Empties the named tables in one query, for a test that needs a familiar
+ * initial state.
+ *
+ * Empties `tableNames` in one query — for a test that needs a FAMILIAR initial
+ * state, not just its own unique key, typically a race test where the key is
+ * deliberately shared across several parallel calls. This is an exception, not
+ * a habit: the rest of the suite keeps tests independent through different
+ * keys per test (see `stock-ledger-store.contract.ts`), because a TRUNCATE
+ * between every test would serialize parallel test files on a table lock.
+ * Table names go straight into raw SQL, so the format check only guards
+ * against a stray quote or space in a call-site literal escaping the quoting —
+ * a test is not hostile input, so this is not a defense against an attacker.
+ */
+export declare const truncateTables: (tableNames: readonly string[]) => Effect.Effect<void, SqlError, SqlClient.SqlClient>;

package/dist/vitest/reset-tables.js

@@ -0,0 +1,30 @@
+import { SqlClient } from '@effect/sql';
+import { Effect } from 'effect';
+const TABLE_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_]*$/;
+/**
+ * Empties the named tables in one query, for a test that needs a familiar
+ * initial state.
+ *
+ * Empties `tableNames` in one query — for a test that needs a FAMILIAR initial
+ * state, not just its own unique key, typically a race test where the key is
+ * deliberately shared across several parallel calls. This is an exception, not
+ * a habit: the rest of the suite keeps tests independent through different
+ * keys per test (see `stock-ledger-store.contract.ts`), because a TRUNCATE
+ * between every test would serialize parallel test files on a table lock.
+ * Table names go straight into raw SQL, so the format check only guards
+ * against a stray quote or space in a call-site literal escaping the quoting —
+ * a test is not hostile input, so this is not a defense against an attacker.
+ */
+export const truncateTables = (tableNames) => Effect.gen(function* () {
+    if (tableNames.length === 0)
+        return;
+    for (const name of tableNames) {
+        if (!TABLE_IDENTIFIER_PATTERN.test(name)) {
+            return yield* Effect.dieMessage(`truncateTables received a name outside the identifier format: ` +
+                `"${name}". Only call-site SQL literals belong here.`);
+        }
+    }
+    const sql = yield* SqlClient.SqlClient;
+    const quoted = tableNames.map((name) => `"${name}"`).join(', ');
+    yield* sql.unsafe(`TRUNCATE TABLE ${quoted} RESTART IDENTITY CASCADE`);
+});

package/dist/vitest/settings-contract.d.ts

@@ -0,0 +1,38 @@
+import { type EnvironmentEntry } from '@satorio/machinery/core';
+import { type Config } from 'effect';
+/**
+ * The count this contract stands on: how many variables one call was
+ * handed, and how many of them refuse. A contract reads no corpus of
+ * files, so it takes no `minimum*` of its own — the list its caller
+ * hands it is the whole of what it holds, and the count is printed every
+ * run so nobody has to guess how much a green suite covered.
+ *
+ * @internal
+ */
+export declare const contractLineOf: (mechanism: string, environment: readonly EnvironmentEntry[]) => string;
+/**
+ * What an empty list leaves unheld, said in the words the reader of a
+ * red run needs.
+ *
+ * @internal
+ */
+export declare const emptyEnvironmentDetail: (mechanism: string) => string;
+/**
+ * One contract, every adapter that names variables. It reads the whole
+ * settings against an **empty** environment and asserts, word for word,
+ * that each of the three parts of every `refuses` entry reaches the
+ * reader — the sentence that says what happened, the one that says why,
+ * and the one that says what to do. A refusal nobody asserts is a
+ * refusal the next edit rewrites while every test stays green.
+ *
+ * Call it once per adapter, next to that adapter's own tests, with the
+ * `ENVIRONMENT` it exports and the settings it builds. A mechanism whose
+ * variables carry a mount-time prefix passes that prefix too, and the
+ * contract puts it where `<PREFIX>` stands in the entry's text.
+ *
+ * What this contract cannot prove: that the refusal is the one a reader
+ * needed. It holds the three parts to the letter and says nothing about
+ * whether the third part names a step somebody can take — that is read,
+ * not checked.
+ */
+export declare const settingsContract: <A>(mechanism: string, environment: readonly EnvironmentEntry[], settings: Config.Config<A>, variablePrefix?: string) => void;

package/dist/vitest/settings-contract.js

@@ -0,0 +1,77 @@
+import { refusalText, variableNameOf, } from '@satorio/machinery/core';
+import { ConfigProvider, Effect } from 'effect';
+import { describe, expect, it } from 'vitest';
+const readAgainstNothing = (settings) => Effect.runPromise(Effect.either(Effect.withConfigProvider(settings, ConfigProvider.fromMap(new Map()))));
+const PREFIX = '<PREFIX>';
+const refusingIn = (environment) => environment.filter((entry) => entry.state.state === 'refuses');
+/**
+ * The count this contract stands on: how many variables one call was
+ * handed, and how many of them refuse. A contract reads no corpus of
+ * files, so it takes no `minimum*` of its own — the list its caller
+ * hands it is the whole of what it holds, and the count is printed every
+ * run so nobody has to guess how much a green suite covered.
+ *
+ * @internal
+ */
+export const contractLineOf = (mechanism, environment) => `${mechanism} settings contract: read ${environment.length} variable(s), ` +
+    `${refusingIn(environment).length} of them refusing`;
+/**
+ * What an empty list leaves unheld, said in the words the reader of a
+ * red run needs.
+ *
+ * @internal
+ */
+export const emptyEnvironmentDetail = (mechanism) => `${mechanism} handed the settings contract no variables at all. A contract ` +
+    'over an empty list asserts nothing and stays green forever.';
+const textOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * One contract, every adapter that names variables. It reads the whole
+ * settings against an **empty** environment and asserts, word for word,
+ * that each of the three parts of every `refuses` entry reaches the
+ * reader — the sentence that says what happened, the one that says why,
+ * and the one that says what to do. A refusal nobody asserts is a
+ * refusal the next edit rewrites while every test stays green.
+ *
+ * Call it once per adapter, next to that adapter's own tests, with the
+ * `ENVIRONMENT` it exports and the settings it builds. A mechanism whose
+ * variables carry a mount-time prefix passes that prefix too, and the
+ * contract puts it where `<PREFIX>` stands in the entry's text.
+ *
+ * What this contract cannot prove: that the refusal is the one a reader
+ * needed. It holds the three parts to the letter and says nothing about
+ * whether the third part names a step somebody can take — that is read,
+ * not checked.
+ */
+export const settingsContract = (mechanism, environment, settings, variablePrefix = '') => {
+    const refusing = refusingIn(environment);
+    const under = (text) => variablePrefix === '' ? text : text.replaceAll(PREFIX, variablePrefix);
+    describe(`${mechanism} settings: what an empty environment answers`, () => {
+        it('was handed at least one variable to hold', () => {
+            console.log(contractLineOf(mechanism, environment));
+            expect(environment.length, emptyEnvironmentDetail(mechanism)).toBeGreaterThan(0);
+        });
+        it('every entry says what its variable is for', () => {
+            const silent = environment
+                .filter((entry) => entry.what.trim() === '')
+                .map(variableNameOf);
+            expect(silent, silent.join(', ')).toEqual([]);
+        });
+        it(`refuses on ${refusing.length} unset variable(s), or reads clean`, async () => {
+            const read = await readAgainstNothing(settings);
+            expect(read._tag).toBe(refusing.length === 0 ? 'Right' : 'Left');
+        });
+        for (const entry of refusing) {
+            const state = entry.state;
+            if (state.state !== 'refuses')
+                continue;
+            it(`${under(variableNameOf(entry))} refuses in three parts when unset`, async () => {
+                const read = await readAgainstNothing(settings);
+                const answered = read._tag === 'Left' ? textOf(read.left) : '';
+                expect(answered).toContain(under(state.refusal.what));
+                expect(answered).toContain(under(state.refusal.why));
+                expect(answered).toContain(under(state.refusal.whatToDo));
+                expect(answered).toContain(under(refusalText(state.refusal)));
+            });
+        }
+    });
+};

package/dist/vitest/stub-server.d.ts

@@ -0,0 +1,43 @@
+import { Effect, type Scope } from 'effect';
+/**
+ * One answer the stub server gives: the status, the body and content type
+ * where there is one, and the delay before it answers.
+ */
+export interface StubResponse {
+    readonly status: number;
+    readonly body?: string;
+    readonly contentType?: string;
+    readonly delayMillis?: number;
+}
+/**
+ * One route the stub server serves: the method, the path, and the answers it
+ * gives in turn.
+ */
+export interface StubRoute {
+    readonly method: string;
+    readonly path: string;
+    readonly responses: readonly StubResponse[];
+}
+/**
+ * One request the stub server received, as a test reads it back: the method
+ * and the path.
+ */
+export interface RecordedStubRequest {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * @internal
+ */
+export interface StubServerShape {
+    readonly baseUrl: string;
+    readonly requestsReceived: () => readonly RecordedStubRequest[];
+}
+/**
+ * Runs the stub server for the lifetime of a scope.
+ *
+ * Runs the stub server for the lifetime of a Scope: starts on acquire, stops
+ * on release — the same lifecycle as the localstack and Postgres containers in
+ * this mechanism's other files.
+ */
+export declare const scopedStubServer: (routes: readonly StubRoute[]) => Effect.Effect<StubServerShape, never, Scope.Scope>;