@elench/testkit 0.1.114 → 0.1.116

package/lib/config-api/index.mjs

@@ -34,19 +34,36 @@ function postgresDatabase(options = {}) {
 }
 
 function buildDatabaseTemplateConfig(options = {}) {
+  for (const legacyKey of ["schema"]) {
+    if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
+      throw new Error(
+        `database.postgres({ template }) no longer accepts "${legacyKey}". Use database.postgres({ sourceSchema: database.schema.fromEnv(...) }) instead.`
+      );
+    }
+  }
   const migrate = normalizeTemplateStepList(options.migrate);
   const seed = normalizeTemplateStepList(options.seed);
   const verify = normalizeTemplateStepList(options.verify);
-  const schema = normalizeSchemaStep(options.schema);
 
   return {
     inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
-    migrate: schema ? [schema, ...migrate] : migrate,
+    migrate,
     seed,
     verify,
   };
 }
 
+function sourceSchemaFromEnv(envName, options = {}) {
+  if (typeof envName !== "string" || envName.trim().length === 0) {
+    throw new Error("database.schema.fromEnv(...) requires a non-empty env var name");
+  }
+  return {
+    kind: "env",
+    env: envName.trim(),
+    ...options,
+  };
+}
+
 function postgresFixture(options = {}) {
   const { discovery, envFiles, template, ...databaseOptions } = options;
   for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
@@ -241,8 +258,11 @@ export const app = {
 };
 
 export const database = {
+  schema: {
+    fromEnv: sourceSchemaFromEnv,
+  },
   postgres(options = {}) {
-    const { template, ...databaseOptions } = options;
+    const { template, sourceSchema, ...databaseOptions } = options;
     for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
       if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
         throw new Error(
@@ -250,13 +270,19 @@ export const database = {
         );
       }
     }
+    const normalizedDatabaseOptions = sourceSchema === undefined
+      ? databaseOptions
+      : {
+          ...databaseOptions,
+          sourceSchema,
+        };
     return postgresDatabase(
       template
         ? {
-            ...databaseOptions,
+            ...normalizedDatabaseOptions,
             template: buildDatabaseTemplateConfig(template),
           }
-        : databaseOptions
+        : normalizedDatabaseOptions
     );
   },
   fixture: postgresFixture,
@@ -365,17 +391,6 @@ function normalizeTemplateStepList(value) {
   return Array.isArray(value) ? [...value] : [value];
 }
 
-function normalizeSchemaStep(value) {
-  if (value == null) return null;
-  if (typeof value === "string") {
-    return {
-      kind: "sql-file",
-      path: value,
-    };
-  }
-  return value;
-}
-
 function compiledEntryFromSource(entry, outDir) {
   const normalized = String(entry || "src/index.ts").replaceAll("\\", "/");
   const compiled = normalized.replace(/\.[cm]?[jt]sx?$/i, ".js");

package/lib/database/fingerprint.mjs

@@ -3,6 +3,7 @@ import fs from "fs";
 import path from "path";
 import { resolveServiceCwd } from "../config/paths.mjs";
 import { collectTemplateInputs } from "./template-steps.mjs";
+import { appendSourceSchemaCacheToHash } from "./schema-source.mjs";
 
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
 const LOCAL_USER = "testkit";
@@ -24,6 +25,7 @@ export async function computeTemplateFingerprint(config) {
   for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
     appendResolvedInputToHash(hash, config.productDir, input);
   }
+  appendSourceSchemaCacheToHash(hash, config);
 
   return hash.digest("hex");
 }

package/lib/database/index.mjs

@@ -25,7 +25,17 @@ import {
   readStateValue as readStateValueModel,
   visitDirs as visitDirsModel,
 } from "./state.mjs";
-import { captureTemplateSnapshot, runTemplateStage } from "./template-steps.mjs";
+import {
+  runTemplateStage,
+  runTemplateStep,
+} from "./template-steps.mjs";
+import {
+  applySourceSchemaCache,
+  createSourceSchemaMismatchError,
+  forceRefreshSourceSchemaCache,
+  prepareSourceSchemaCache,
+  verifyLocalSchemaMatchesSource,
+} from "./schema-source.mjs";
 import { collectStateDirLines } from "../runner/state-io.mjs";
 
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
@@ -50,60 +60,6 @@ export async function prepareDatabaseRuntime(config, options = {}) {
   throw new Error(`Unsupported database provider "${db.provider}"`);
 }
 
-export async function captureDatabaseTemplateSnapshot(config, outputPath, options = {}) {
-  if (!config.testkit.database || config.testkit.database.provider !== "local") {
-    throw new Error(`Service "${config.name}" does not use a local testkit database`);
-  }
-
-  await prepareDatabaseRuntime(config, options);
-  const cacheDir = getLocalServiceCacheDir(config.productDir, config.name);
-  const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
-  if (!templateDbName) {
-    throw new Error(`Missing template database for service "${config.name}"`);
-  }
-
-  const infra = await loadExistingLocalContainer(config.productDir);
-  if (!infra) {
-    throw new Error(`Missing local database container for service "${config.name}"`);
-  }
-
-  const snapshotOperation = options.setupRegistry?.start({
-    config,
-    stage: "template:snapshot",
-    kind: "database-snapshot",
-    summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
-  });
-  try {
-    const output = await captureTemplateSnapshot(
-      config,
-      outputPath,
-      buildDatabaseUrl(infra, templateDbName),
-      {
-        reporter: options.reporter || null,
-        logRecord: snapshotOperation?._logRecord || null,
-      }
-    );
-    const finished = snapshotOperation
-      ? options.setupRegistry.finish(snapshotOperation, {
-          status: "passed",
-          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
-        })
-      : null;
-    if (finished) options.reporter?.setupOperationFinished?.(finished);
-    return output;
-  } catch (error) {
-    const finished = snapshotOperation
-      ? options.setupRegistry.finish(snapshotOperation, {
-          status: "failed",
-          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
-          error: error?.message || error,
-        })
-      : null;
-    if (finished) options.reporter?.setupOperationFinished?.(finished);
-    throw error;
-  }
-}
-
 export async function destroyRuntimeDatabase({ productDir, stateDir }) {
   const backend = readStateValue(path.join(stateDir, "database_backend"));
   if (backend === "local") {
@@ -184,13 +140,24 @@ async function prepareLocalDatabase(config, options = {}) {
   fs.mkdirSync(lockDir, { recursive: true });
   fs.mkdirSync(cacheDir, { recursive: true });
 
-  const templateFingerprint = await computeTemplateFingerprint(config);
+  let templateFingerprint = null;
   const infra = await withLock(path.join(lockDir, "container.lock"), () =>
     ensureLocalContainer(productDir, db)
   );
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
-    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options);
+    const sourceSchemaState = await prepareSourceSchemaCache(config, options);
+    templateFingerprint = await computeTemplateFingerprint(config);
+    templateFingerprint = await ensureTemplateDatabase(
+      config,
+      infra,
+      cacheDir,
+      templateFingerprint,
+      {
+        ...options,
+        sourceSchemaState,
+      }
+    );
   });
 
   await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
@@ -200,34 +167,58 @@ async function prepareLocalDatabase(config, options = {}) {
 
 async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options = {}) {
   const serviceName = config.name;
-  const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
-  const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
-  const desiredDbName = buildTemplateDatabaseName(serviceName, templateFingerprint);
-
-  if (
-    existingFingerprint === templateFingerprint &&
-    existingDbName &&
-    (await databaseExists(infra, existingDbName))
-  ) {
-    options.setupRegistry?.recordCached({
-      config,
-      stage: "template",
-      kind: "database-template",
-      summary: "template cache hit",
+  let activeFingerprint = templateFingerprint;
+  let sourceSchemaState = options.sourceSchemaState || null;
+  let refreshedSourceAfterMismatch = false;
+
+  while (true) {
+    const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
+    const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+    const desiredDbName = buildTemplateDatabaseName(serviceName, activeFingerprint);
+
+    if (
+      existingFingerprint === activeFingerprint &&
+      existingDbName &&
+      (await databaseExists(infra, existingDbName))
+    ) {
+      options.setupRegistry?.recordCached({
+        config,
+        stage: "template",
+        kind: "database-template",
+        summary: "template cache hit",
+      });
+      writeLocalCacheState(cacheDir, infra, existingDbName, activeFingerprint);
+      return activeFingerprint;
+    }
+
+    if (existingDbName && existingDbName !== desiredDbName) {
+      await dropDatabaseIfExists(infra, existingDbName);
+    }
+    if (await databaseExists(infra, desiredDbName)) {
+      await dropDatabaseIfExists(infra, desiredDbName);
+    }
+
+    const templateUrl = buildDatabaseUrl(infra, desiredDbName);
+    await createEmptyDatabase(infra, desiredDbName);
+    const buildResult = await rebuildTemplateDatabase(config, infra, desiredDbName, templateUrl, {
+      ...options,
+      sourceSchemaState,
+      refreshedSourceAfterMismatch,
     });
-    writeLocalCacheState(cacheDir, infra, existingDbName, templateFingerprint);
-    return;
-  }
+    if (buildResult.refreshSourceSchema) {
+      await dropDatabaseIfExists(infra, desiredDbName);
+      sourceSchemaState = await forceRefreshSourceSchemaCache(config, sourceSchemaState, options);
+      refreshedSourceAfterMismatch = true;
+      activeFingerprint = await computeTemplateFingerprint(config);
+      continue;
+    }
 
-  if (existingDbName && existingDbName !== desiredDbName) {
-    await dropDatabaseIfExists(infra, existingDbName);
-  }
-  if (await databaseExists(infra, desiredDbName)) {
-    await dropDatabaseIfExists(infra, desiredDbName);
+    writeLocalCacheState(cacheDir, infra, desiredDbName, activeFingerprint);
+    return activeFingerprint;
   }
+}
 
-  const templateUrl = buildDatabaseUrl(infra, desiredDbName);
-  await createEmptyDatabase(infra, desiredDbName);
+async function rebuildTemplateDatabase(config, infra, templateDbName, templateUrl, options = {}) {
   const templateOperation = options.setupRegistry?.start({
     config,
     stage: "template",
@@ -236,42 +227,89 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
     recordLog: false,
   });
   try {
-    await runTemplateStage(config, "migrate", templateUrl, {
-      reporter: options.reporter || null,
-      setupRegistry: options.setupRegistry || null,
-      parentOperation: templateOperation,
-    });
-    await runTemplateStage(config, "seed", templateUrl, {
+    await applySourceSchemaCache(config, templateUrl, options.sourceSchemaState, {
       reporter: options.reporter || null,
       setupRegistry: options.setupRegistry || null,
       parentOperation: templateOperation,
     });
+
+    const verifySchema = async () => {
+      const verification = await verifyLocalSchemaMatchesSource(
+        config,
+        templateUrl,
+        options.sourceSchemaState,
+        {
+          reporter: options.reporter || null,
+          setupRegistry: options.setupRegistry || null,
+          skipSchemaSourceVerify: options.skipSchemaSourceVerify,
+        }
+      );
+      if (verification.status !== "mismatch") return null;
+      if (options.refreshedSourceAfterMismatch) {
+        throw createSourceSchemaMismatchError(config, options.sourceSchemaState, verification);
+      }
+      return verification;
+    };
+
+    const runStageWithDriftChecks = async (stageName) => {
+      const steps = config.testkit.database?.template?.[stageName] || [];
+      for (const [index, step] of steps.entries()) {
+        await runTemplateStep(config, stageName, step, index, templateUrl, {
+          reporter: options.reporter || null,
+          setupRegistry: options.setupRegistry || null,
+          parentOperation: templateOperation,
+        });
+        if (await verifySchema()) return true;
+      }
+      return false;
+    };
+
+    if (await runStageWithDriftChecks("migrate")) {
+      finishTemplateOperation(templateOperation, options, {
+        status: "passed",
+        summary: "source schema refresh requested",
+      });
+      return { refreshSourceSchema: true };
+    }
+    if (await runStageWithDriftChecks("seed")) {
+      finishTemplateOperation(templateOperation, options, {
+        status: "passed",
+        summary: "source schema refresh requested",
+      });
+      return { refreshSourceSchema: true };
+    }
+    if (await verifySchema()) {
+      finishTemplateOperation(templateOperation, options, {
+        status: "passed",
+        summary: "source schema refresh requested",
+      });
+      return { refreshSourceSchema: true };
+    }
+
     await runTemplateStage(config, "verify", templateUrl, {
       reporter: options.reporter || null,
       setupRegistry: options.setupRegistry || null,
       parentOperation: templateOperation,
     });
-    const finished = templateOperation
-      ? options.setupRegistry.finish(templateOperation, {
-          status: "passed",
-          summary: "template rebuild",
-        })
-      : null;
-    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    finishTemplateOperation(templateOperation, options, {
+      status: "passed",
+      summary: "template rebuild",
+    });
+    return { refreshSourceSchema: false };
   } catch (error) {
-    const finished = templateOperation
-      ? options.setupRegistry.finish(templateOperation, {
-          status: "failed",
-          summary: "template rebuild",
-          error: error?.message || error,
-        })
-      : null;
-    if (finished) options.reporter?.setupOperationFinished?.(finished);
-    await dropDatabaseIfExists(infra, desiredDbName);
+    finishTemplateOperation(templateOperation, options, {
+      status: "failed",
+      summary: "template rebuild",
+      error: error?.message || error,
+    });
+    await dropDatabaseIfExists(infra, templateDbName);
     throw error;
   }
+}
 
-  writeLocalCacheState(cacheDir, infra, desiredDbName, templateFingerprint);
+function finishTemplateOperation(templateOperation, options, result) {
+  const finished = templateOperation ? options.setupRegistry.finish(templateOperation, result) : null;
+  if (finished) options.reporter?.setupOperationFinished?.(finished);
 }
 
 async function ensureRuntimeClone(config, infra, cacheDir, templateFingerprint, bindingKey) {