Initial Commit

packages/api-stack/api/api-migrations/tests/integration/README.md

@@ -0,0 +1,29 @@
+# Integration tests — deferred
+
+The three dialect roundtrip tests (`sqlite`, `postgres`, `surrealql`) are
+deferred to a follow-up change. Justification:
+
+- **sqlite-wasm** requires a Web Worker and the WASM binary; running it under
+  vitest+Node in `forks` pool needs a non-trivial polyfill layer that does
+  not yet ship in `@suaveplan/testing` and would inflate this change beyond
+  scope. The `MemoryAdapter` in `src/runner/runner.test.ts` exercises the
+  full apply/select/insert/delete roundtrip against a real in-memory store
+  satisfying the same `MigrationAdapter` contract — every spec scenario is
+  covered.
+- **postgres** and **surrealql** roundtrips require Docker testcontainers
+  (`@suaveplan/testing-integration-postgres`, `-surrealdb`) which are
+  available but pull large images on every CI run. They will land in
+  `add-api-migrations-integration-tests` together with the sqlite-wasm worker
+  setup so the env requirements stay coherent.
+
+The shipped unit tests cover:
+
+- DDL emission per dialect (`src/adapters/<dialect>/<dialect>.test.ts`).
+- Row normalisation roundtrip per dialect.
+- Parameterised insert/delete per dialect.
+- Full apply / drift-detect / rollback flow via the in-memory `MemoryAdapter`
+  in `src/runner/runner.test.ts`.
+
+These do not stub crypto, fs, or the adapter contract — every test
+exercises the real `node:crypto` `createHash` and `node:fs/promises`
+`readdir`/`readFile`/`stat` calls.

packages/api-stack/api/api-migrations/tests/integration/global-setup.ts

@@ -0,0 +1,24 @@
+/**
+ * Vitest globalSetup — registers the SurrealDB fixture in the globalSetup
+ * process's module scope, then re-exports the testing-integration
+ * `setup`/`teardown` contract.
+ *
+ * The same module pattern used by `@suaveplan/surrealdb` integration tests:
+ * vitest's `globalSetup` runs in a separate process from the worker pool, so
+ * the fixture must be registered in THIS file (which the globalSetup process
+ * loads) for `createIntegrationSetup`'s registry to be populated when
+ * `setup`/`teardown` run.
+ *
+ * @module
+ */
+import { createIntegrationSetup } from "@suaveplan/testing-integration";
+import { SurrealDBFixture } from "@suaveplan/testing-integration-surrealdb";
+
+createIntegrationSetup({
+    surrealdb: new SurrealDBFixture(),
+});
+
+export {
+    setup,
+    teardown,
+} from "@suaveplan/testing-integration/setup/global-setup";

packages/api-stack/api/api-migrations/tests/integration/integration-setup.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared integration-setup module — exposes the typed `inject` helper and a
+ * `surrealUnavailable` boolean for `describe.skipIf(...)` skip-when-down
+ * behaviour. Fixture registration happens in the sibling `global-setup.ts`
+ * file because vitest runs `globalSetup` in a separate process from the
+ * worker pool.
+ *
+ * @module
+ */
+import { inject as vitestInject } from "@suaveplan/testing/runner";
+import type { SurrealDBConfig } from "@suaveplan/testing-integration-surrealdb";
+
+interface IntegrationConfigs {
+    surrealdb: SurrealDBConfig;
+}
+
+export function inject<K extends keyof IntegrationConfigs>(
+    key: K
+): IntegrationConfigs[K] {
+    const all = (vitestInject as (k: string) => IntegrationConfigs)(
+        "__integration_configs__"
+    );
+    return all[key];
+}
+
+/**
+ * `true` when the SurrealDB fixture failed to start (no Docker, env-bridge
+ * incomplete) or when the test runs outside the integration config (no
+ * globalSetup at all). Test files use this with `describe.skipIf(...)` so
+ * the suite SKIPS rather than FAILS.
+ */
+export const surrealUnavailable: boolean = (() => {
+    try {
+        const failed = (vitestInject as (k: string) => string[] | undefined)(
+            "__integration_failed__"
+        );
+        if (failed === undefined) return true;
+        if (failed.includes("surrealdb")) return true;
+        const configs = (
+            vitestInject as (
+                k: string
+            ) => Record<string, Record<string, unknown>> | undefined
+        )("__integration_configs__");
+        return configs === undefined || configs.surrealdb === undefined;
+    } catch {
+        return true;
+    }
+})();

packages/api-stack/api/api-migrations/tests/integration/surrealql-ledger.integration.test.ts

@@ -0,0 +1,188 @@
+/**
+ * SurrealQL adapter — live SurrealDB v3 ledger regression suite.
+ *
+ * Reproduces the silent-ledger-drop discovered while shipping
+ * `@suaveplan/api-plugin-database`: with the pre-fix code, the runner's
+ * `CREATE ${table}:$name SET ...` form parses cleanly under SurrealDB v3
+ * but records nothing, so the ledger reports zero applied migrations and
+ * every boot re-runs the same migration.
+ *
+ * These tests run against a real `surrealdb:v3.x` testcontainer started by
+ * `tests/integration/global-setup.ts`. No mocks.
+ *
+ * @module
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+} from "@suaveplan/testing/runner";
+import { Surreal } from "surrealdb";
+import {
+    createSurrealqlAdapter,
+    type SurrealqlClient,
+} from "../../src/adapters/surrealql/surrealql.js";
+import { createMigrationRunner } from "../../src/runner/runner.js";
+import { inject, surrealUnavailable } from "./integration-setup.js";
+
+const TABLE = "_migrations";
+
+/**
+ * Thin wrapper that adapts the official `surrealdb` JS SDK to the structural
+ * `SurrealqlClient` shape the migration adapter expects. The SDK's
+ * `query<R extends unknown[]>(sql, bindings)` returns the raw statement-result
+ * array; we flatten the single statement to the rows shape `selectApplied`
+ * consumes.
+ */
+function wrapSurreal(client: Surreal): SurrealqlClient {
+    return {
+        async query<T>(
+            sql: string,
+            vars?: Record<string, unknown>
+        ): Promise<T[]> {
+            const result = (await client.query(sql, vars)) as unknown[];
+            // `query` returns an array of statement results. For multi-
+            // statement SQL we flatten everything that's an array of rows;
+            // single-row results are tolerated.
+            const flat: T[] = [];
+            for (const r of result) {
+                if (Array.isArray(r)) flat.push(...(r as T[]));
+                else if (r !== null && r !== undefined) flat.push(r as T);
+            }
+            return flat;
+        },
+    };
+}
+
+async function connect(): Promise<Surreal> {
+    const cfg = inject("surrealdb");
+    const db = new Surreal();
+    await db.connect(cfg.url);
+    await db.signin({ username: cfg.username, password: cfg.password });
+    await db.use({ namespace: cfg.namespace, database: cfg.database });
+    return db;
+}
+
+describe.skipIf(surrealUnavailable)(
+    "createSurrealqlAdapter — live SurrealDB v3 ledger",
+    () => {
+        let dir: string;
+        let db: Surreal;
+
+        beforeEach(async () => {
+            dir = await mkdtemp(join(tmpdir(), "api-migrations-surreal-"));
+            db = await connect();
+            // Each test gets its own namespace/database for isolation. The
+            // fixture's default ns/db are sufficient because we DROP the
+            // ledger table in afterEach.
+        }, 60000);
+
+        afterEach(async () => {
+            try {
+                await db.query(`REMOVE TABLE ${TABLE};`);
+            } catch {
+                // best-effort cleanup
+            }
+            await db.close();
+            await rm(dir, { recursive: true, force: true });
+        }, 60000);
+
+        it("ledger row is queryable after a migration body succeeds (regression: silent CREATE drop)", async () => {
+            // Arrange: write a single migration body. The body creates a
+            // table whose presence we can independently observe.
+            const fileName = "001_initial.surql";
+            const body = "DEFINE TABLE post_init SCHEMAFULL;";
+            await writeFile(join(dir, fileName), body, "utf-8");
+
+            const client = wrapSurreal(db);
+            const adapter = createSurrealqlAdapter(client);
+            const runner = createMigrationRunner(adapter, {
+                tableName: TABLE,
+                fileExtension: ".surql",
+            });
+
+            // Act
+            const results = await runner.runFromDirectory(dir);
+
+            // Assert 1: runner reports success.
+            expect(results).toHaveLength(1);
+            expect(results[0]!.success).toBe(true);
+            expect(results[0]!.name).toBe("001_initial");
+
+            // Assert 2: migration body actually applied.
+            const bodyApplied = (await db.query("INFO FOR DB;")) as unknown[];
+            expect(JSON.stringify(bodyApplied)).toContain("post_init");
+
+            // Assert 3 (the regression): the ledger row exists in the
+            // SAME live connection. With the pre-fix `${table}:$name`
+            // form this query returns []; the runner re-applies the
+            // migration on every boot.
+            const ledgerRows = (await db.query(
+                `SELECT name, checksum, duration FROM ${TABLE};`
+            )) as Array<
+                Array<{ name: string; checksum: string; duration: number }>
+            >;
+            const rows = ledgerRows[0] ?? [];
+            expect(rows).toHaveLength(1);
+            expect(rows[0]!.name).toBe("001_initial");
+            expect(typeof rows[0]!.checksum).toBe("string");
+            expect(rows[0]!.checksum).toMatch(/^[0-9a-f]{64}$/);
+        }, 60000);
+
+        it("second run sees the ledger and skips already-applied migrations", async () => {
+            const fileName = "001_idempotent.surql";
+            const body = "DEFINE TABLE idempotent_t SCHEMAFULL;";
+            await writeFile(join(dir, fileName), body, "utf-8");
+
+            const adapter = createSurrealqlAdapter(wrapSurreal(db));
+            const runner = createMigrationRunner(adapter, {
+                tableName: TABLE,
+                fileExtension: ".surql",
+            });
+
+            const first = await runner.runFromDirectory(dir);
+            expect(first).toHaveLength(1);
+
+            // Second invocation MUST be a no-op. With the pre-fix bug
+            // the ledger was empty so the runner would re-apply the
+            // migration — which then fails because `DEFINE TABLE` is
+            // idempotent here but in real schemas would crash on
+            // duplicate constraints.
+            const second = await runner.runFromDirectory(dir);
+            expect(second).toEqual([]);
+
+            // Ledger still has exactly one row.
+            const ledgerRows = (await db.query(
+                `SELECT name FROM ${TABLE};`
+            )) as Array<Array<{ name: string }>>;
+            expect(ledgerRows[0] ?? []).toHaveLength(1);
+        }, 60000);
+
+        it("rollback() removes the ledger row written by insertApplied (round-trip)", async () => {
+            const fileName = "001_rollback.surql";
+            const body = "DEFINE TABLE rollback_t SCHEMAFULL;";
+            await writeFile(join(dir, fileName), body, "utf-8");
+
+            const adapter = createSurrealqlAdapter(wrapSurreal(db));
+            const runner = createMigrationRunner(adapter, {
+                tableName: TABLE,
+                fileExtension: ".surql",
+            });
+            await runner.runFromDirectory(dir);
+
+            const result = await runner.rollback();
+            expect(result?.success).toBe(true);
+            expect(result?.name).toBe("001_rollback");
+
+            const ledgerRows = (await db.query(
+                `SELECT name FROM ${TABLE};`
+            )) as Array<Array<{ name: string }>>;
+            expect(ledgerRows[0] ?? []).toHaveLength(0);
+        }, 60000);
+    }
+);