@elench/testkit 0.1.69 → 0.1.71

package/lib/{setup → config-api}/index.mjs

@@ -1,24 +1,24 @@
 import {
-  clearRepoSetup,
+  clearRepoConfig,
   clearRuntimeContext,
-  getRepoSetup,
+  getRepoConfig,
   getRuntimeContext,
   getRuntimeEnv,
-  registerRepoSetup,
+  registerRepoConfig,
   registerRuntimeContext,
   runtimeHttp,
   runtimeJson,
 } from "./runtime.mjs";
 
-export function defineTestkitSetup(setup) {
-  return setup || {};
+export function defineConfig(config) {
+  return config || {};
 }
 
 export function defineHttpProfile(profile) {
   return profile || {};
 }
 
-export function defineTestkitFile(metadata) {
+export function defineFile(metadata) {
   return metadata || {};
 }
 
@@ -364,11 +364,11 @@ export function jsonSessionProfile(options = {}) {
 }
 
 export {
-  clearRepoSetup,
+  clearRepoConfig,
   clearRuntimeContext,
-  getRepoSetup,
+  getRepoConfig,
   getRuntimeContext,
-  registerRepoSetup,
+  registerRepoConfig,
   registerRuntimeContext,
   runtimeHttp,
   runtimeJson,
@@ -413,7 +413,7 @@ function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];
   if (!value) {
-    throw new Error(`Missing required env var "${name}" for testkit setup`);
+    throw new Error(`Missing required env var "${name}" for testkit config`);
   }
   return value;
 }

package/lib/{setup → config-api}/index.test.mjs

@@ -1,7 +1,9 @@
 import { describe, expect, it } from "vitest";
 import {
   databaseServiceEnv,
-  defineTestkitFile,
+  defineConfig,
+  defineFile,
+  defineHttpProfile,
   nextApp,
   nextBuild,
   nodeToolchain,
@@ -18,9 +20,20 @@ import {
   verifyModule,
 } from "./index.mjs";
 
-describe("setup helpers", () => {
+describe("config helpers", () => {
+  it("defines repo config plainly", () => {
+    expect(defineConfig({ execution: { workers: 4 } })).toEqual({
+      execution: { workers: 4 },
+    });
+  });
+
+  it("defines HTTP profiles plainly", () => {
+    const profile = defineHttpProfile({ headers: () => ({ Authorization: "Bearer token" }) });
+    expect(typeof profile.headers).toBe("function");
+  });
+
   it("defines file-local metadata plainly", () => {
-    expect(defineTestkitFile({ skip: "Auth is stubbed", locks: ["background-workers"] })).toEqual({
+    expect(defineFile({ skip: "Auth is stubbed", locks: ["background-workers"] })).toEqual({
       skip: "Auth is stubbed",
       locks: ["background-workers"],
     });

package/lib/{setup → config-api}/runtime.mjs

@@ -1,16 +1,16 @@
-let activeSetup = null;
+let activeConfig = null;
 let activeRuntimeContext = null;
 
-export function registerRepoSetup(setup) {
-  activeSetup = setup || null;
+export function registerRepoConfig(config) {
+  activeConfig = config || null;
 }
 
-export function getRepoSetup() {
-  return activeSetup;
+export function getRepoConfig() {
+  return activeConfig;
 }
 
-export function clearRepoSetup() {
-  activeSetup = null;
+export function clearRepoConfig() {
+  activeConfig = null;
 }
 
 export function registerRuntimeContext(context) {
@@ -48,9 +48,9 @@ export function runtimeJson(response) {
 export function resolveHttpProfile(name) {
   if (!name) return null;
 
-  const setup = getRepoSetup();
-  if (!setup) return null;
-  const profile = setup?.profiles?.http?.[name];
+  const config = getRepoConfig();
+  if (!config) return null;
+  const profile = config?.profiles?.http?.[name];
   if (!profile) {
     throw new Error(`Unknown testkit HTTP profile "${name}"`);
   }

package/lib/coverage/index.test.mjs

@@ -17,11 +17,11 @@ describe("coverage graph builder", () => {
     const productDir = createProduct();
     writeFile(
       productDir,
-      "testkit.setup.ts",
+      "testkit.config.ts",
       `
-        import { defineTestkitSetup, nextApp } from "@elench/testkit/setup";
+        import { defineConfig, nextApp } from "@elench/testkit/config";
 
-        export default defineTestkitSetup({
+        export default defineConfig({
           services: {
             web: nextApp({
               cwd: ".",

package/lib/discovery/file-metadata.mjs

@@ -44,7 +44,7 @@ function parseMetadataInitializer(initializer) {
   if (!initializer) return null;
   if (ts.isCallExpression(initializer)) {
     const callee = getCallIdentifier(initializer.expression);
-    if (callee === "defineTestkitFile" && initializer.arguments[0] && ts.isObjectLiteralExpression(initializer.arguments[0])) {
+    if (callee === "defineFile" && initializer.arguments[0] && ts.isObjectLiteralExpression(initializer.arguments[0])) {
       return parseMetadataObject(initializer.arguments[0]);
     }
     return null;

package/lib/discovery/file-metadata.test.mjs

@@ -20,8 +20,8 @@ describe("test file metadata", () => {
     fs.writeFileSync(
       path.join(productDir, "__testkit__", "billing.int.testkit.ts"),
       [
-        'import { defineTestkitFile } from "@elench/testkit/setup";',
-        'export const testkit = defineTestkitFile({',
+        'import { defineFile } from "@elench/testkit/config";',
+        'export const testkit = defineFile({',
         '  skip: "Billing is stubbed locally",',
         '  locks: ["background-workers", "background-workers"],',
         "});",

package/lib/discovery/index.d.ts

@@ -76,7 +76,7 @@ export interface DiscoveryResult {
     name: string;
     directory: string;
   };
-  setupFile: string | null;
+  configFile: string | null;
   filters: {
     service: string | null;
     types: DiscoverySelectionType[] | ["all"];

package/lib/discovery/index.mjs

@@ -1,7 +1,7 @@
 import path from "path";
 import { loadConfigContext, resolveProductDir } from "../config/index.mjs";
 import { discoverProject } from "../config/discovery.mjs";
-import { loadTestkitSetup } from "../config/setup-loader.mjs";
+import { loadTestkitConfig } from "../config/config-loader.mjs";
 import { buildCoverageGraph } from "../coverage/index.mjs";
 import { historyFilePath, loadHistory, summarizeHistoryForFiles } from "../history/index.mjs";
 import {
@@ -12,12 +12,12 @@ import {
   suiteSelectionType,
 } from "../runner/suite-selection.mjs";
 
-const DISCOVERY_SCHEMA_VERSION = 3;
+const DISCOVERY_SCHEMA_VERSION = 4;
 
 export async function discoverTests(options = {}) {
   const productDir = resolveProductDir(process.cwd(), options.dir);
   const filters = normalizeDiscoveryFilters(options);
-  const setupContext = await loadSetupContext(productDir, filters.diagnosticsMode);
+  const configContext = await loadConfigDiscoveryContext(productDir, filters.diagnosticsMode);
   const baseResult = {
     schemaVersion: DISCOVERY_SCHEMA_VERSION,
     source: "testkit-discovery",
@@ -25,7 +25,7 @@ export async function discoverTests(options = {}) {
       name: path.basename(productDir),
       directory: productDir,
     },
-    setupFile: setupContext.setupFile ? path.relative(productDir, setupContext.setupFile) || path.basename(setupContext.setupFile) : null,
+    configFile: configContext.configFile ? path.relative(productDir, configContext.configFile) || path.basename(configContext.configFile) : null,
     filters: {
       service: filters.serviceFilter,
       types: filters.typeValues,
@@ -38,7 +38,7 @@ export async function discoverTests(options = {}) {
     suites: [],
     files: [],
     coverageGraph: null,
-    diagnostics: [...setupContext.diagnostics],
+    diagnostics: [...configContext.diagnostics],
     summary: emptySummary(),
     history: {
       available: false,
@@ -46,24 +46,24 @@ export async function discoverTests(options = {}) {
     },
   };
 
-  if (!setupContext.setup) {
+  if (!configContext.config) {
     return finalizeDiscoveryResult(baseResult, productDir);
   }
 
-  const rawDiscovery = discoverProject(productDir, setupContext.setup.services || {}, {
+  const rawDiscovery = discoverProject(productDir, configContext.config.services || {}, {
     strict: filters.diagnosticsMode === "error",
-    discovery: setupContext.setup.discovery || {},
+    discovery: configContext.config.discovery || {},
   });
   baseResult.diagnostics.push(...rawDiscovery.diagnostics);
-  validateRequestedService(filters.serviceFilter, setupContext.setup.services || {}, rawDiscovery);
+  validateRequestedService(filters.serviceFilter, configContext.config.services || {}, rawDiscovery);
 
-  let configContext = null;
+  let normalizedConfigContext = null;
   try {
-    configContext = await loadConfigContext({
+    normalizedConfigContext = await loadConfigContext({
       dir: productDir,
-      setupContext: {
-        setup: setupContext.setup,
-        setupFile: setupContext.setupFile,
+      configContext: {
+        config: configContext.config,
+        configFile: configContext.configFile,
       },
       discoveryOptions: {
         strict: filters.diagnosticsMode === "error",
@@ -78,9 +78,9 @@ export async function discoverTests(options = {}) {
     });
   }
 
-  if (configContext) {
+  if (normalizedConfigContext) {
     const resolved = buildResolvedDiscovery({
-      configs: configContext.configs,
+      configs: normalizedConfigContext.configs,
       filters,
     });
     return finalizeDiscoveryResult(
@@ -91,8 +91,8 @@ export async function discoverTests(options = {}) {
       files: resolved.files,
       coverageGraph: buildCoverageGraph({
         productDir,
-        repoDiscovery: setupContext.setup.discovery || {},
-        services: setupContext.setup.services || {},
+        repoDiscovery: configContext.config.discovery || {},
+        services: configContext.config.services || {},
         discoveryFiles: rawDiscovery.files || [],
       }),
       },
@@ -102,7 +102,7 @@ export async function discoverTests(options = {}) {
 
   const rawOnly = buildRawDiscovery({
     rawDiscovery,
-    explicitServices: setupContext.setup.services || {},
+    explicitServices: configContext.config.services || {},
     filters,
   });
   return finalizeDiscoveryResult(
@@ -113,8 +113,8 @@ export async function discoverTests(options = {}) {
     files: rawOnly.files,
     coverageGraph: buildCoverageGraph({
       productDir,
-      repoDiscovery: setupContext.setup.discovery || {},
-      services: setupContext.setup.services || {},
+      repoDiscovery: configContext.config.discovery || {},
+      services: configContext.config.services || {},
       discoveryFiles: rawDiscovery.files || [],
     }),
     },
@@ -140,22 +140,22 @@ export function formatDisplayName(value) {
     .join(" ");
 }
 
-async function loadSetupContext(productDir, diagnosticsMode) {
+async function loadConfigDiscoveryContext(productDir, diagnosticsMode) {
   try {
-    const { setup, setupFile } = await loadTestkitSetup(productDir);
+    const { config, configFile } = await loadTestkitConfig(productDir);
     return {
-      setup,
-      setupFile,
+      config,
+      configFile,
       diagnostics: [],
     };
   } catch (error) {
     if (diagnosticsMode === "error") throw error;
     return {
-      setup: null,
-      setupFile: null,
+      config: null,
+      configFile: null,
       diagnostics: [
         {
-          code: "setup_invalid",
+          code: "config_invalid",
           severity: "error",
           message: formatErrorMessage(error),
         },

package/lib/discovery/index.test.mjs

@@ -18,11 +18,11 @@ describe("public discovery", () => {
     const productDir = createProduct();
     writeFile(
       productDir,
-      "testkit.setup.ts",
+      "testkit.config.ts",
       `
-        import { defineTestkitSetup } from "@elench/testkit/setup";
+        import { defineConfig } from "@elench/testkit/config";
 
-        export default defineTestkitSetup({
+        export default defineConfig({
           services: {
             api: {
               local: {
@@ -49,8 +49,8 @@ describe("public discovery", () => {
       productDir,
       "src/api/routes/__testkit__/agent-configs-auth-gate.int.testkit.ts",
       [
-        'import { defineTestkitFile } from "@elench/testkit/setup";',
-        'export const testkit = defineTestkitFile({ locks: ["route-lock"] });',
+        'import { defineFile } from "@elench/testkit/config";',
+        'export const testkit = defineFile({ locks: ["route-lock"] });',
         "export {};",
       ].join("\n")
     );
@@ -58,8 +58,8 @@ describe("public discovery", () => {
       productDir,
       "frontend/src/app/login/__testkit__/auth.pw.testkit.ts",
       [
-        'import { defineTestkitFile } from "@elench/testkit/setup";',
-        'export const testkit = defineTestkitFile({ skip: "Auth is stubbed locally" });',
+        'import { defineFile } from "@elench/testkit/config";',
+        'export const testkit = defineFile({ skip: "Auth is stubbed locally" });',
         "export {};",
       ].join("\n")
     );
@@ -135,11 +135,11 @@ describe("public discovery", () => {
     const productDir = createProduct();
     writeFile(
       productDir,
-      "testkit.setup.ts",
+      "testkit.config.ts",
       `
-        import { defineTestkitSetup } from "@elench/testkit/setup";
+        import { defineConfig } from "@elench/testkit/config";
 
-        export default defineTestkitSetup({
+        export default defineConfig({
           services: {
             api: {
               local: {

package/lib/drizzle/index.d.ts

@@ -0,0 +1,14 @@
+export interface DrizzleConfigOptions {
+  consumer?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  files?: string[];
+  onlyWhenAllowed?: boolean;
+  override?: boolean;
+  requireLocalDatabase?: boolean;
+}
+
+export declare function defineConfig<T extends Record<string, unknown>>(
+  config: T,
+  options?: DrizzleConfigOptions
+): T;

package/lib/drizzle/index.mjs

@@ -0,0 +1,15 @@
+import { assertLocalDatabaseUrl, loadDotenvFiles } from "../env/index.mjs";
+
+export function defineConfig(config = {}, options = {}) {
+  loadDotenvFiles({
+    cwd: options.cwd,
+    env: options.env,
+    files: options.files,
+    onlyWhenAllowed: options.onlyWhenAllowed,
+    override: options.override,
+  });
+  if (options.requireLocalDatabase !== false) {
+    assertLocalDatabaseUrl(options.env || process.env, options.consumer || "drizzle.config.ts");
+  }
+  return config;
+}

package/lib/drizzle/index.test.mjs

@@ -0,0 +1,33 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { defineConfig } from "./index.mjs";
+
+describe("testkit drizzle defineConfig", () => {
+  it("loads dotenv files before returning config", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-drizzle-"));
+    fs.writeFileSync(path.join(tmpDir, ".env"), "DATABASE_URL=postgres://user:pass@127.0.0.1:5432/app\n");
+    const env = {};
+
+    const config = defineConfig({ dialect: "postgresql" }, { cwd: tmpDir, env });
+
+    expect(config).toEqual({ dialect: "postgresql" });
+    expect(env.DATABASE_URL).toContain("127.0.0.1");
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("enforces local database urls during managed runs by default", () => {
+    expect(() =>
+      defineConfig(
+        { dialect: "postgresql" },
+        {
+          env: {
+            TESTKIT_ACTIVE: "1",
+            DATABASE_URL: "postgres://user:pass@db.example.com:5432/app",
+          },
+        }
+      )
+    ).toThrow("testkit runs require a local PostgreSQL DATABASE_URL");
+  });
+});

package/lib/env/index.d.ts

@@ -0,0 +1,17 @@
+export interface LoadDotenvFilesOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  files?: string[];
+  onlyWhenAllowed?: boolean;
+  override?: boolean;
+}
+
+export declare function isManagedRuntime(env?: NodeJS.ProcessEnv): boolean;
+export declare function shouldLoadDotenv(env?: NodeJS.ProcessEnv): boolean;
+export declare function loadDotenvFiles(options?: LoadDotenvFilesOptions): {
+  loaded: string[];
+};
+export declare function assertLocalDatabaseUrl(
+  env?: NodeJS.ProcessEnv,
+  consumer?: string
+): void;

package/lib/env/index.mjs

@@ -0,0 +1,65 @@
+import fs from "fs";
+import path from "path";
+import { parseDotenvString } from "../config/env.mjs";
+
+const LOCAL_DATABASE_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+const LOCAL_DATABASE_PROTOCOLS = new Set(["postgres:", "postgresql:"]);
+
+export function isManagedRuntime(env = process.env) {
+  return env?.TESTKIT_ACTIVE === "1";
+}
+
+export function shouldLoadDotenv(env = process.env) {
+  return env?.NODE_ENV !== "production" && !isManagedRuntime(env);
+}
+
+export function loadDotenvFiles(options = {}) {
+  const env = options.env || process.env;
+  if (options.onlyWhenAllowed !== false && !shouldLoadDotenv(env)) {
+    return { loaded: [] };
+  }
+
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const override = options.override !== false;
+  const files = Array.isArray(options.files) && options.files.length > 0
+    ? options.files
+    : [".env", ".env.local"];
+  const loaded = [];
+
+  for (const file of files) {
+    const absolutePath = path.resolve(cwd, file);
+    if (!fs.existsSync(absolutePath)) continue;
+    const parsed = parseDotenvString(fs.readFileSync(absolutePath, "utf8"));
+    for (const [key, value] of Object.entries(parsed)) {
+      if (override || env[key] == null) {
+        env[key] = value;
+      }
+    }
+    loaded.push(absolutePath);
+  }
+
+  return { loaded };
+}
+
+export function assertLocalDatabaseUrl(env = process.env, consumer = "This command") {
+  if (!isManagedRuntime(env)) return;
+
+  const databaseUrl = env?.DATABASE_URL;
+  if (!databaseUrl) {
+    throw new Error(`${consumer} requires DATABASE_URL when TESTKIT_ACTIVE=1.`);
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(databaseUrl);
+  } catch {
+    throw new Error(`${consumer} requires a valid DATABASE_URL when TESTKIT_ACTIVE=1.`);
+  }
+
+  if (!LOCAL_DATABASE_PROTOCOLS.has(parsed.protocol) || !LOCAL_DATABASE_HOSTS.has(parsed.hostname)) {
+    const location = `${parsed.protocol}//${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}`;
+    throw new Error(
+      `${consumer} testkit runs require a local PostgreSQL DATABASE_URL. Refusing ${location}.`
+    );
+  }
+}

package/lib/env/index.test.mjs

@@ -0,0 +1,82 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { describe, expect, it } from "vitest";
+import {
+  assertLocalDatabaseUrl,
+  isManagedRuntime,
+  loadDotenvFiles,
+  shouldLoadDotenv,
+} from "./index.mjs";
+
+describe("testkit env helpers", () => {
+  it("detects managed runtimes", () => {
+    expect(isManagedRuntime({ TESTKIT_ACTIVE: "1" })).toBe(true);
+    expect(isManagedRuntime({ TESTKIT_ACTIVE: "0" })).toBe(false);
+  });
+
+  it("only loads dotenv when not production and not managed", () => {
+    expect(shouldLoadDotenv({ NODE_ENV: "development" })).toBe(true);
+    expect(shouldLoadDotenv({ NODE_ENV: "production" })).toBe(false);
+    expect(shouldLoadDotenv({ NODE_ENV: "development", TESTKIT_ACTIVE: "1" })).toBe(false);
+  });
+
+  it("loads dotenv files in order and respects override by default", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-env-"));
+    fs.writeFileSync(path.join(tmpDir, ".env"), "FOO=base\nBAR=base\n");
+    fs.writeFileSync(path.join(tmpDir, ".env.local"), "BAR=local\nBAZ=local\n");
+    const env = {};
+
+    const result = loadDotenvFiles({ cwd: tmpDir, env });
+
+    expect(result.loaded).toHaveLength(2);
+    expect(env).toEqual({
+      FOO: "base",
+      BAR: "local",
+      BAZ: "local",
+    });
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("supports non-overriding dotenv loads", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-env-"));
+    fs.writeFileSync(path.join(tmpDir, ".env"), "FOO=base\n");
+    const env = { FOO: "preset" };
+
+    loadDotenvFiles({ cwd: tmpDir, env, override: false });
+
+    expect(env.FOO).toBe("preset");
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("skips dotenv loading when managed unless explicitly overridden", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-env-"));
+    fs.writeFileSync(path.join(tmpDir, ".env"), "FOO=base\n");
+    const env = { TESTKIT_ACTIVE: "1" };
+
+    const skipped = loadDotenvFiles({ cwd: tmpDir, env });
+    expect(skipped.loaded).toEqual([]);
+    expect(env.FOO).toBeUndefined();
+
+    const forced = loadDotenvFiles({ cwd: tmpDir, env, onlyWhenAllowed: false });
+    expect(forced.loaded).toHaveLength(1);
+    expect(env.FOO).toBe("base");
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("enforces local postgres urls during managed runs", () => {
+    expect(() =>
+      assertLocalDatabaseUrl(
+        { TESTKIT_ACTIVE: "1", DATABASE_URL: "postgres://user:pass@db.example.com:5432/app" },
+        "drizzle.config.ts"
+      )
+    ).toThrow("drizzle.config.ts testkit runs require a local PostgreSQL DATABASE_URL.");
+
+    expect(() =>
+      assertLocalDatabaseUrl(
+        { TESTKIT_ACTIVE: "1", DATABASE_URL: "postgres://user:pass@127.0.0.1:5432/app" },
+        "drizzle.config.ts"
+      )
+    ).not.toThrow();
+  });
+});

package/lib/known-failures/github.mjs

@@ -21,18 +21,18 @@ const MODES = new Set(["off", "warn", "error"]);
 export function normalizeKnownFailureIssueValidationConfig(value) {
   if (value == null) return null;
   if (!value || typeof value !== "object") {
-    throw new Error("testkit.setup.ts reporting.issueValidation must be an object");
+    throw new Error("testkit.config.ts reporting.issueValidation must be an object");
   }
 
   const provider = normalizeOptionalString(value.provider) || "github";
   if (provider !== "github") {
-    throw new Error('testkit.setup.ts reporting.issueValidation.provider must be "github"');
+    throw new Error('testkit.config.ts reporting.issueValidation.provider must be "github"');
   }
 
   const mode = normalizeOptionalString(value.mode) || "warn";
   if (!MODES.has(mode)) {
     throw new Error(
-      'testkit.setup.ts reporting.issueValidation.mode must be one of: off, warn, error'
+      'testkit.config.ts reporting.issueValidation.mode must be one of: off, warn, error'
     );
   }
 
@@ -41,7 +41,7 @@ export function normalizeKnownFailureIssueValidationConfig(value) {
       ? DEFAULT_CACHE_TTL_SECONDS
       : normalizePositiveInteger(
           value.cacheTtlSeconds,
-          "testkit.setup.ts reporting.issueValidation.cacheTtlSeconds"
+          "testkit.config.ts reporting.issueValidation.cacheTtlSeconds"
         );
 
   return {