@elench/testkit 0.1.115 → 0.1.116

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) {

package/lib/database/schema-source.mjs

@@ -0,0 +1,295 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { execa } from "execa";
+import { resolveServiceCwd } from "../config/paths.mjs";
+import { buildExecutionEnv } from "../runner/template.mjs";
+import { dumpPostgresSchemaToFile, captureTemplateSnapshotText, runTemplateStep, sanitizeSnapshotText } from "./template-steps.mjs";
+
+const SOURCE_SCHEMA_DIR = path.join(".testkit", "db");
+const SOURCE_SCHEMA_FILE = "source-schema.sql";
+const SOURCE_SCHEMA_META_FILE = "source-schema.meta.json";
+
+export function getSourceSchemaCachePath(config) {
+  const configured = config.testkit.database?.sourceSchema?.cachePath || null;
+  return configured
+    ? resolveServiceCwd(config.productDir, configured)
+    : path.join(config.productDir, SOURCE_SCHEMA_DIR, config.name, SOURCE_SCHEMA_FILE);
+}
+
+export function getSourceSchemaMetadataPath(config) {
+  const cachePath = getSourceSchemaCachePath(config);
+  return path.join(path.dirname(cachePath), SOURCE_SCHEMA_META_FILE);
+}
+
+export function resolveSourceSchemaState(config, options = {}) {
+  const sourceSchema = config.testkit.database?.sourceSchema || null;
+  if (!sourceSchema) return { active: false };
+
+  const cachePath = getSourceSchemaCachePath(config);
+  const cacheExists = fs.existsSync(cachePath);
+  const env = buildExecutionEnv(config, {}, options.env || process.env);
+  const envNames = sourceSchema.kind === "env"
+    ? [sourceSchema.env]
+    : [serviceSourceSchemaEnvName(config.name), "TESTKIT_SCHEMA_SOURCE_DATABASE_URL"];
+  const envName = envNames.find((name) => typeof env[name] === "string" && env[name].trim().length > 0) || null;
+  const sourceUrl = envName ? env[envName].trim() : null;
+  const explicit = sourceSchema.kind === "env";
+  const active = explicit || Boolean(sourceUrl) || cacheExists;
+  if (!active) return { active: false, cachePath };
+
+  return {
+    active: true,
+    cachePath,
+    metadataPath: getSourceSchemaMetadataPath(config),
+    envName,
+    sourceUrl,
+    sourceSchema,
+    cacheExists,
+    refreshed: false,
+    unavailableMode: resolveUnavailableMode(sourceSchema.unavailable, options.env || process.env),
+  };
+}
+
+export async function prepareSourceSchemaCache(config, options = {}) {
+  const state = resolveSourceSchemaState(config, options);
+  if (!state.active) return state;
+
+  if (state.sourceUrl) {
+    if (shouldRefreshSourceSchema(state)) {
+      await refreshSourceSchemaCache(config, state, options);
+      return { ...state, refreshed: true, cacheExists: true };
+    }
+    options.setupRegistry?.recordCached({
+      config,
+      stage: "source-schema",
+      kind: "database-source-schema",
+      summary: "source schema cache hit",
+    });
+    return state;
+  }
+
+  if (state.cacheExists && state.unavailableMode === "warn-cache") {
+    options.setupRegistry?.recordCached({
+      config,
+      stage: "source-schema",
+      kind: "database-source-schema",
+      summary: "source unavailable; using cached source schema",
+    });
+    return state;
+  }
+
+  const envLabel = state.sourceSchema.kind === "env"
+    ? state.sourceSchema.env
+    : `${serviceSourceSchemaEnvName(config.name)} or TESTKIT_SCHEMA_SOURCE_DATABASE_URL`;
+  throw new Error(
+    `Source schema database URL is unavailable for service "${config.name}". Set ${envLabel}.`
+  );
+}
+
+export async function forceRefreshSourceSchemaCache(config, previousState, options = {}) {
+  const state = resolveSourceSchemaState(config, options);
+  if (!state.active || !state.sourceUrl) {
+    const envLabel = previousState?.envName || previousState?.sourceSchema?.env || "source schema env";
+    throw new Error(`Cannot refresh source schema for service "${config.name}" because ${envLabel} is unavailable.`);
+  }
+  await refreshSourceSchemaCache(config, state, options);
+  return { ...state, refreshed: true, cacheExists: true };
+}
+
+export async function applySourceSchemaCache(config, databaseUrl, state, options = {}) {
+  if (!state?.active) return false;
+  if (!fs.existsSync(state.cachePath)) {
+    throw new Error(`Missing source schema cache for service "${config.name}": ${state.cachePath}`);
+  }
+  await runTemplateStep(
+    config,
+    "source-schema",
+    {
+      kind: "sql-file",
+      path: path.relative(config.productDir, state.cachePath).split(path.sep).join("/"),
+      cwd: null,
+      inputs: [],
+    },
+    0,
+    databaseUrl,
+    options
+  );
+  return true;
+}
+
+export async function verifyLocalSchemaMatchesSource(config, databaseUrl, state, options = {}) {
+  if (!state?.active) return { status: "disabled" };
+  if (state.sourceSchema.verify === false || options.skipSchemaSourceVerify) {
+    options.setupRegistry?.recordCached({
+      config,
+      stage: "source-schema:verify",
+      kind: "database-source-schema",
+      summary: "source schema verification skipped",
+    });
+    return { status: "skipped" };
+  }
+
+  const sourceSchema = readSourceSchemaCacheText(state.cachePath);
+  const localSchema = await captureTemplateSnapshotText(config, databaseUrl, {
+    reporter: options.reporter || null,
+  });
+  if (localSchema === sourceSchema) {
+    return { status: "matched" };
+  }
+
+  const diagnostics = await writeSchemaMismatchDiagnostics(config, state.cachePath, sourceSchema, localSchema);
+  return {
+    status: "mismatch",
+    diagnostics,
+  };
+}
+
+export function createSourceSchemaMismatchError(config, state, verification) {
+  const parts = [
+    `Local schema replay does not match source schema for service "${config.name}".`,
+    `Source cache: ${path.relative(config.productDir, state.cachePath)}`,
+  ];
+  if (verification?.diagnostics?.diffPath) {
+    parts.push(`Diff: ${path.relative(config.productDir, verification.diagnostics.diffPath)}`);
+  }
+  return new Error(parts.join("\n"));
+}
+
+export function appendSourceSchemaCacheToHash(hash, config) {
+  const sourceSchema = config.testkit.database?.sourceSchema || null;
+  if (!sourceSchema) return;
+  const cachePath = getSourceSchemaCachePath(config);
+  hash.update(`source-schema-cache:${path.relative(config.productDir, cachePath)}`);
+  if (!fs.existsSync(cachePath)) {
+    hash.update(":missing");
+    return;
+  }
+  const stat = fs.statSync(cachePath);
+  hash.update(`:${stat.size}:${stat.mtimeMs}`);
+  hash.update(fs.readFileSync(cachePath));
+}
+
+async function refreshSourceSchemaCache(config, state, options = {}) {
+  const operation = options.setupRegistry?.start({
+    config,
+    stage: "source-schema:refresh",
+    kind: "database-source-schema",
+    summary: `source schema refresh: ${path.relative(config.productDir, state.cachePath)}`,
+  });
+  try {
+    await writeSourceSchemaCacheFromUrl(config, state.sourceUrl, state.cachePath, {
+      reporter: options.reporter || null,
+      logRecord: operation?._logRecord || null,
+    });
+    writeSourceSchemaMetadata(state.metadataPath, {
+      refreshedAt: new Date().toISOString(),
+      serviceName: config.name,
+      envName: state.envName,
+      cachePath: path.relative(config.productDir, state.cachePath),
+    });
+    const finished = operation
+      ? options.setupRegistry.finish(operation, {
+          status: "passed",
+          summary: `source schema refresh: ${path.relative(config.productDir, state.cachePath)}`,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+  } catch (error) {
+    const finished = operation
+      ? options.setupRegistry.finish(operation, {
+          status: "failed",
+          summary: `source schema refresh: ${path.relative(config.productDir, state.cachePath)}`,
+          error: error?.message || error,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    throw error;
+  }
+}
+
+async function writeSourceSchemaCacheFromUrl(config, sourceUrl, cachePath, options = {}) {
+  fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+  const tempDir = fs.mkdtempSync(path.join(path.dirname(cachePath), ".source-schema-"));
+  const tempPath = path.join(tempDir, path.basename(cachePath));
+  try {
+    await dumpPostgresSchemaToFile(config, tempPath, sourceUrl, options);
+    fs.renameSync(tempPath, cachePath);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function readSourceSchemaCacheText(cachePath) {
+  return sanitizeSnapshotText(fs.readFileSync(cachePath, "utf8"));
+}
+
+function shouldRefreshSourceSchema(state) {
+  if (!state.cacheExists) return true;
+  if (state.sourceSchema.refresh?.mode === "ttl") {
+    const meta = readJson(state.metadataPath);
+    const refreshedAt = meta?.refreshedAt ? Date.parse(meta.refreshedAt) : 0;
+    if (!Number.isFinite(refreshedAt) || refreshedAt <= 0) return true;
+    return Date.now() - refreshedAt >= state.sourceSchema.refresh.ttlSeconds * 1000;
+  }
+  return true;
+}
+
+function writeSourceSchemaMetadata(metadataPath, metadata) {
+  fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
+  fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+function readJson(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeSchemaMismatchDiagnostics(config, sourceCachePath, sourceSchema, localSchema) {
+  const dir = path.join(config.productDir, ".testkit", "results", "schema");
+  fs.mkdirSync(dir, { recursive: true });
+  const prefix = `${sanitizePathSegment(config.runtimeLabel || config.name)}__${sanitizePathSegment(config.name)}`;
+  const sourcePath = path.join(dir, `${prefix}__source-schema.sql`);
+  const localPath = path.join(dir, `${prefix}__local-replay-schema.sql`);
+  const diffPath = path.join(dir, `${prefix}__schema.diff`);
+  fs.writeFileSync(sourcePath, sourceSchema);
+  fs.writeFileSync(localPath, localSchema);
+  fs.writeFileSync(diffPath, await buildUnifiedDiff(sourcePath, localPath));
+  return {
+    sourceCachePath,
+    sourcePath,
+    localPath,
+    diffPath,
+  };
+}
+
+async function buildUnifiedDiff(sourcePath, localPath) {
+  const result = await execa("diff", ["-u", sourcePath, localPath], {
+    reject: false,
+    stdout: "pipe",
+    stderr: "pipe",
+  }).catch((error) => ({ exitCode: 2, stdout: "", stderr: error.message }));
+  if (result.exitCode === 0 || result.exitCode === 1) return result.stdout || "";
+  return `Could not generate diff: ${result.stderr || "diff failed"}\n`;
+}
+
+function resolveUnavailableMode(value, env) {
+  if (value === "fail" || value === "warn-cache") return value;
+  return env.CI === "true" ? "fail" : "warn-cache";
+}
+
+function serviceSourceSchemaEnvName(serviceName) {
+  return `TESTKIT_${String(serviceName).toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_SCHEMA_SOURCE_DATABASE_URL`;
+}
+
+function sanitizePathSegment(value) {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "schema";
+}