@lovrozagar/oat 0.1.0

package/dist/cli.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+import { createWriteStream, writeFileSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { interpolate, loadConfig } from "./config/load.js";
+import { report } from "./report/console.js";
+import { renderMatrixGraph, renderMatrixHtml } from "./report/matrix.js";
+import { ISSUE_REPRO_DIR, renderConsole, renderJson, renderMarkdown, renderRepros } from "./report/render.js";
+import { createStderrProgress, formatProgressJsonl, formatProgressLine, formatProgressTsv, PROGRESS_GLOSSARY, PROGRESS_TSV_HEADER, } from "./runtime/progress.js";
+import { renderTeardown } from "./runtime/teardown.js";
+import { buildModel } from "./spec/graph.js";
+import { dereference, loadSpec } from "./spec/load.js";
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (token === undefined || !token.startsWith("--"))
+            continue;
+        const key = token.slice(2);
+        const next = rest[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[key] = next;
+            i++;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { command, flags };
+}
+const USAGE = `oat — OpenAPI Tester
+
+  oat run     --config <file>              test a live backend and write a report
+  oat plan    --spec <url|file>            derive and print the test model (offline)
+  oat doctor  --spec <url|file>            report what oat can and cannot test, and why
+  oat serve   [--defects A,B]              run a demo API to point oat at
+  oat conformance                          self-test: injected defects vs detection
+
+Flags
+  --config     oat config module (.ts/.js/.mjs/.json) with a default export
+  --spec       OpenAPI document, http(s) URL or filesystem path
+  --base-url   backend under test, overriding the config
+  --only       comma-separated entity names to restrict the run to
+  --seed       integer seed for fixture generation (default 1)
+  --out        output directory for the report (default ./oat-out)
+  --keep-fixtures  leave created records in place instead of tearing them down
+  --concurrency    entities tested in parallel (default 1)
+  --max-in-flight  requests allowed in flight at once (default 4)
+  --quiet          no live progress on stderr (progress.log still written)
+  --untagged       serve (or test) a document with every x-* tag stripped
+  --backend        conformance storage: memory | sqlite | postgres | d1
+                   (default: all local; d1 is remote and opt-in)
+  --dialect        API shape: postgrest | classic | linked | jsonapi | plain (default: all)
+  --fuzz [n]       inject random defect *combinations* instead of one at a time
+  --precision [n]  vary cohort data against a correct backend; any finding is a false positive
+  --max-defects    most defects per combination (default: 4)
+  --seed           fuzz seed, so a failing combination replays exactly
+  --json       machine-readable output, for plan and doctor
+`;
+function str(flags, key) {
+    const value = flags[key];
+    return typeof value === "string" ? value : undefined;
+}
+async function commandRun(flags) {
+    const configPath = str(flags, "config");
+    if (configPath === undefined) {
+        process.stderr.write("oat: run requires --config\n\n" + USAGE);
+        return 2;
+    }
+    const { run } = await import("./runtime/run.js");
+    const config = interpolate(await loadConfig(configPath));
+    const baseUrl = str(flags, "base-url") ?? config.baseUrl;
+    const seedFlag = str(flags, "seed");
+    const only = str(flags, "only")?.split(",").map((s) => s.trim()).filter(Boolean);
+    /* No cast: the config's principal type *is* the runtime's, so a mistake here is a compile
+     * error in the user's own config rather than a surprise mid-run. */
+    const principals = config.principals ?? [];
+    if (principals.length === 0) {
+        process.stderr.write("oat: config declares no principals. At least one is required so oat can authenticate; " +
+            "a second in a different tenant enables the isolation checks.\n");
+        return 2;
+    }
+    const startedAt = new Date();
+    const began = performance.now();
+    const outDir = resolve(str(flags, "out") ?? config.outDir ?? "oat-out");
+    await mkdir(outDir, { recursive: true });
+    const stderrProgress = flags.quiet === true ? undefined : createStderrProgress(startedAt.getTime());
+    const progressLog = createWriteStream(resolve(outDir, "progress.log"));
+    const progressTsv = createWriteStream(resolve(outDir, "progress.tsv"));
+    const progressJsonl = createWriteStream(resolve(outDir, "progress.jsonl"));
+    progressLog.write(`${PROGRESS_GLOSSARY}\n`);
+    progressTsv.write(`${PROGRESS_TSV_HEADER}\n`);
+    let lastLogKey = "";
+    let lastLogAt = 0;
+    let lastJsonAt = 0;
+    const onProgress = (snap) => {
+        stderrProgress?.emit(snap);
+        const key = `${snap.phase}|${snap.entity ?? ""}|${snap.check ?? ""}|${snap.message ?? ""}`;
+        const due = Date.now() - lastLogAt >= 2_000;
+        if (key !== lastLogKey || due || snap.phase === "done" || snap.phase === "load") {
+            lastLogKey = key;
+            lastLogAt = Date.now();
+            const now = Date.now();
+            progressLog.write(`${formatProgressLine(snap, now)}\n`);
+            progressTsv.write(`${formatProgressTsv(snap, now)}\n`);
+            progressJsonl.write(`${formatProgressJsonl(snap, now)}\n`);
+        }
+        if (Date.now() - lastJsonAt >= 1_000 || snap.phase === "done") {
+            lastJsonAt = Date.now();
+            const payload = {
+                ...snap,
+                lastAgoMs: snap.last === undefined ? null : Date.now() - snap.last.at,
+                updatedAt: new Date().toISOString(),
+            };
+            writeFileSync(resolve(outDir, "progress.json"), `${JSON.stringify(payload, null, 2)}\n`);
+        }
+    };
+    let result;
+    try {
+        result = await run({
+            baseUrl,
+            principals,
+            spec: config.spec,
+            ...(config.globalHeaders === undefined ? {} : { globalHeaders: config.globalHeaders }),
+            ...(config.hooks === undefined ? {} : { hooks: config.hooks }),
+            ...(config.roots === undefined ? {} : { roots: config.roots }),
+            ...(config.cohortSize === undefined ? {} : { cohortSize: config.cohortSize }),
+            ...(only === undefined ? {} : { only }),
+            ...(flags["keep-fixtures"] === true ? { keepFixtures: true } : {}),
+            concurrency: Number.parseInt(str(flags, "concurrency") ?? "", 10) || config.concurrency || 1,
+            maxInFlight: Number.parseInt(str(flags, "max-in-flight") ?? "", 10) || 4,
+            seed: seedFlag === undefined ? (config.seed ?? 1) : Number.parseInt(seedFlag, 10),
+            onProgress,
+        });
+    }
+    finally {
+        stderrProgress?.stop();
+        progressLog.end();
+        progressTsv.end();
+        progressJsonl.end();
+    }
+    const durationMs = performance.now() - began;
+    const input = {
+        baseUrl,
+        checksRun: result.checksRun,
+        checksSkipped: result.checksSkipped,
+        checksSuppressed: result.checksSuppressed,
+        inconclusive: result.inconclusive,
+        client: result.client,
+        durationMs,
+        entitiesTested: result.entitiesTested,
+        findings: result.findings,
+        model: result.model,
+        startedAt,
+    };
+    /* Wipe both the old name and the current one. A leftover script from a previous
+     * finding reads as a current defect. The folder is only created when there is an issue. */
+    await rm(resolve(outDir, "repro"), { force: true, recursive: true });
+    await rm(resolve(outDir, ISSUE_REPRO_DIR), { force: true, recursive: true });
+    await writeFile(resolve(outDir, "oat-report.md"), renderMarkdown(input));
+    await writeFile(resolve(outDir, "oat-report.json"), renderJson(input));
+    await writeFile(resolve(outDir, "matrix.html"), renderMatrixHtml(input));
+    await writeFile(resolve(outDir, "matrix.json"), renderMatrixGraph(input));
+    const scripts = renderRepros(result.findings, baseUrl);
+    if (scripts.length > 0) {
+        const dir = resolve(outDir, ISSUE_REPRO_DIR);
+        await mkdir(dir, { recursive: true });
+        for (const script of scripts) {
+            await writeFile(resolve(dir, script.filename), script.content, { mode: 0o755 });
+        }
+    }
+    process.stdout.write(renderConsole(input));
+    for (const line of renderTeardown(result.teardown ?? { failed: [], removed: 0, unsupported: [] }, result.created)) {
+        process.stdout.write(`${line}\n`);
+    }
+    process.stdout.write(`  report: ${resolve(outDir, "oat-report.md")}\n`);
+    process.stdout.write(`  matrix: ${resolve(outDir, "matrix.html")}\n`);
+    process.stdout.write(`  graph:  ${resolve(outDir, "matrix.json")}\n`);
+    process.stdout.write(`  progress: ${resolve(outDir, "progress.log")} · ${resolve(outDir, "progress.jsonl")}\n\n`);
+    /* Exit code counts root causes, not raw findings: gaps and blocked entries are information,
+     * not failures, and a CI gate should react to defects only. */
+    return result.findings.filter((f) => f.verdict !== "COVERAGE_GAP" && f.verdict !== "BLOCKED")
+        .length > 0
+        ? 1
+        : 0;
+}
+async function main() {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    if (command === "help" || flags.help === true) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (command === "conformance") {
+        const { postgresAvailable, renderParserSuite, renderSuite, runExampleSpecSuite, runTagUnlockSuite, runParserSuite, runCoverageReportSuite, runSuite, sqliteAvailable, d1Available, } = await import("./conformance/suite.js");
+        const parser = renderParserSuite(runParserSuite());
+        process.stdout.write(parser.text);
+        /* The documented example is checked in the same breath: it is the only place a reader
+         * sees where each tag goes, and documentation that drifts teaches a shape that no longer
+         * works. */
+        const example = renderParserSuite(await runExampleSpecSuite());
+        process.stdout.write(example.text);
+        parser.failures += example.failures;
+        const unlocks = renderParserSuite(await runTagUnlockSuite());
+        process.stdout.write(unlocks.text);
+        parser.failures += unlocks.failures;
+        const coverage = renderParserSuite(runCoverageReportSuite());
+        process.stdout.write(coverage.text);
+        parser.failures += coverage.failures;
+        if (flags.parser === true)
+            return parser.failures > 0 ? 1 : 0;
+        if (flags.precision !== undefined) {
+            /* Varies the data rather than the faults, against a backend with nothing wrong with it.
+             * Any finding here is a false positive by construction. */
+            const { renderPrecision, runPrecision } = await import("./conformance/fuzz.js");
+            const n = typeof flags.precision === "string" ? Number.parseInt(flags.precision, 10) : 50;
+            const rendered = renderPrecision(await runPrecision({
+                backend: (str(flags, "backend") ?? "memory"),
+                cases: Number.isFinite(n) && n > 0 ? n : 50,
+                dialect: str(flags, "dialect") ?? "postgrest",
+                seed: Number.parseInt(str(flags, "seed") ?? "1", 10) || 1,
+            }));
+            process.stdout.write(rendered.text);
+            return parser.failures + rendered.failures > 0 ? 1 : 0;
+        }
+        if (flags.fuzz !== undefined) {
+            /* Combination fuzzing is its own question — whether the diagnosis survives several
+             * simultaneous faults — so it replaces the matrix rather than padding it. */
+            const { renderFuzz, runFuzz } = await import("./conformance/fuzz.js");
+            const count = typeof flags.fuzz === "string" ? Number.parseInt(flags.fuzz, 10) : 25;
+            const fuzzBackend = str(flags, "backend");
+            const results = await runFuzz({
+                backend: (fuzzBackend ?? "memory"),
+                cases: Number.isFinite(count) && count > 0 ? count : 25,
+                dialect: str(flags, "dialect") ?? "postgrest",
+                maxDefects: Number.parseInt(str(flags, "max-defects") ?? "4", 10) || 4,
+                seed: Number.parseInt(str(flags, "seed") ?? "1", 10) || 1,
+            });
+            const rendered = renderFuzz(results);
+            process.stdout.write(rendered.text);
+            return parser.failures + rendered.failures > 0 ? 1 : 0;
+        }
+        const only = str(flags, "only")?.split(",");
+        const requested = str(flags, "backend");
+        /* Both by default. A check that passes against the in-memory store but not against real
+         * SQL was relying on JavaScript semantics — NULL ordering, collation, LIKE escaping — that
+         * a database does not share, and running only one backend hides exactly that. */
+        const all = ["memory", "sqlite", "postgres", "d1"];
+        const available = ["memory"];
+        if (await sqliteAvailable())
+            available.push("sqlite");
+        if (await postgresAvailable())
+            available.push("postgres");
+        /* Present but never default: D1 is remote, so a pass costs minutes and consumes someone's
+         * quota. It runs when asked for by name. */
+        const d1Ready = d1Available();
+        const backends = all.includes(requested)
+            ? [requested]
+            : available;
+        const skipped = all.filter((b) => b !== "d1" && !available.includes(b));
+        const dialect = str(flags, "dialect");
+        /* Backends vary the storage engine; dialects vary the API's conventions. Running the full
+         * cross product would be mostly redundant, so every backend is exercised on the default
+         * dialect and one extra pass covers a second dialect that shares no parameter names. */
+        const passes = dialect === undefined && requested === undefined
+            ? [
+                ...backends.map((backend) => ({ backend, dialect: "postgrest" })),
+                /* Two extra shapes on the cheapest backend. `classic` renames everything;
+                 * `linked` changes the pagination *model* — root array, Link header, row
+                 * offsets — which is the stronger test of whether checks read the document
+                 * or the fixture's habits. */
+                { backend: "memory", dialect: "classic" },
+                { backend: "memory", dialect: "linked" },
+                { backend: "memory", dialect: "jsonapi" },
+                { backend: "memory", dialect: "plain" },
+            ]
+            : backends.map((backend) => ({ backend, dialect: dialect ?? "postgrest" }));
+        let failures = parser.failures;
+        for (const pass of passes) {
+            process.stdout.write(`\n  ── ${pass.backend} · ${pass.dialect} ${"─".repeat(46)}\n`);
+            const result = renderSuite(await runSuite(only, pass.backend, pass.dialect), pass.dialect);
+            process.stdout.write(result.text);
+            failures += result.failures;
+        }
+        if (requested === undefined && skipped.length > 0) {
+            for (const backend of skipped) {
+                const why = backend === "sqlite"
+                    ? "node:sqlite unavailable (Node 22 needs --experimental-sqlite)"
+                    : "no Postgres server reachable on the default connection";
+                process.stdout.write(`  note: ${backend} backend skipped — ${why}\n`);
+            }
+            process.stdout.write("\n");
+        }
+        if (requested === undefined && only === undefined) {
+            /* A short combination pass runs as part of the standard self-test. Single-defect recall
+             * says nothing about how the diagnosis holds up when several faults overlap, and every
+             * bug the fuzzer has found so far — silent bail-outs, non-transitive suppression, a
+             * probe writing into a constrained field — was invisible to the one-at-a-time matrix. */
+            const { renderFuzz, runFuzz } = await import("./conformance/fuzz.js");
+            process.stdout.write(`\n  ── combinations ${"─".repeat(46)}\n`);
+            const smoke = renderFuzz(await runFuzz({ backend: "memory", cases: 40, maxDefects: 6, seed: 1 }));
+            process.stdout.write(smoke.text);
+            failures += smoke.failures;
+        }
+        if (requested === undefined) {
+            process.stdout.write(d1Ready
+                ? "  note: d1 backend available — run with --backend d1 (remote, ~2min per defect)\n\n"
+                : "  note: d1 backend needs CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_D1_DATABASE_ID, CLOUDFLARE_API_TOKEN\n\n");
+        }
+        return failures > 0 ? 1 : 0;
+    }
+    if (command === "serve") {
+        /* A built-in demo API so oat can be tried before wiring it to anything real. The
+         * reference backend doubles as the conformance fixture, so this is the same server the
+         * self-test runs against. */
+        const backend = str(flags, "backend") ?? "memory";
+        const defects = str(flags, "defects")?.split(",").filter(Boolean) ?? [];
+        const { createMemoryServer, createPostgresServer, createSqliteServer } = await import("./reference/http.js");
+        const factory = backend === "sqlite"
+            ? createSqliteServer
+            : backend === "postgres"
+                ? createPostgresServer
+                : createMemoryServer;
+        /* `--untagged` serves the same API behind a document stripped of every x-* tag, which is
+         * what `oat doctor` should be pointed at to see what a plain OpenAPI document costs. */
+        const untagged = flags.untagged === true;
+        const dialect = str(flags, "dialect");
+        const server = await factory({
+            defects,
+            untagged,
+            ...(dialect === undefined ? {} : { dialect }),
+        });
+        process.stdout.write(`\n  oat demo API — ${backend}${untagged ? " (untagged spec)" : ""}\n` +
+            `  url      ${server.url}\n` +
+            `  spec     ${server.url}/v1/openapi/spec\n` +
+            `  dialect  ${dialect ?? "postgrest"}\n` +
+            `  defects  ${defects.length > 0 ? defects.join(", ") : "none — a correct backend"}\n` +
+            `  keys     key_alpha (proj_alpha) · key_beta (proj_beta)\n\n` +
+            "  point a config at it:\n" +
+            `    oat run --config labs/local.config.ts --base-url ${server.url}\n\n` +
+            "  ctrl-c to stop\n\n");
+        /* Node buffers stdout when it is not a TTY, so a piped `oat serve` would print nothing
+         * until exit — indistinguishable from a hang. */
+        if (typeof process.stdout.write === "function")
+            process.stdout.uncork?.();
+        /* Resolves only on signal — the process should stay up serving. */
+        await new Promise((resolve) => {
+            process.on("SIGINT", () => resolve());
+            process.on("SIGTERM", () => resolve());
+        });
+        await server.close();
+        return 0;
+    }
+    if (command === "run")
+        return commandRun(flags);
+    const specFlag = str(flags, "spec");
+    const configPath = str(flags, "config");
+    const specSource = specFlag ?? (configPath === undefined ? undefined : (await loadConfig(configPath)).spec);
+    if (specSource === undefined) {
+        process.stderr.write("oat: --spec (or --config) is required\n\n" + USAGE);
+        return 2;
+    }
+    const raw = await loadSpec(specSource, str(flags, "base-url"));
+    const { doc, externalRefs } = dereference(raw);
+    const model = buildModel(doc);
+    switch (command) {
+        case "plan":
+            process.stdout.write(report.plan(model, flags.json === true));
+            return 0;
+        case "doctor": {
+            const output = report.doctor(model, externalRefs, flags.json === true);
+            process.stdout.write(output.text);
+            return output.blocking > 0 ? 1 : 0;
+        }
+        default:
+            process.stderr.write(`oat: unknown command "${command}"\n\n${USAGE}`);
+            return 2;
+    }
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`oat: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/config/define-config.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The public configuration surface — and the single source of truth for its types.
+ *
+ * The runtime imports these definitions rather than declaring its own, so a mistake in a config
+ * is a compile error rather than a surprise at request time. Everything backend-specific lives
+ * here or in `x-*` spec tags; oat itself knows nothing about any particular API.
+ */
+interface StepBase {
+    /**
+     * Binds parts of the response into the flow's scope. Later steps interpolate them as
+     * `{name}`, and `rootsFromFlow` can promote them to path parameters. Values are addressed by
+     * path: `$.access_token`, `$.orgs.0.id`.
+     */
+    saveAs?: Record<string, string>;
+    /**
+     * Binds values out of a JWT's claims. Tenancy commonly rides in the token rather than the
+     * response body, and a principal that can name its own tenant needs no roots configured. The
+     * signature is not verified — oat is reading its own credential, not trusting a third party.
+     */
+    saveClaimsFrom?: {
+        token: string;
+        bind: Record<string, string>;
+    };
+    /** Literal values bound before the step runs, with `{name}` interpolation. */
+    bind?: Record<string, string>;
+    /** Accepted statuses. Defaults to any 2xx. */
+    expect?: number[];
+}
+/** Calls an operation named in the document. Prefer this — it survives the path moving. */
+export interface OperationStep extends StepBase {
+    operationId: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+}
+/** Calls a raw path, for endpoints the document does not describe. */
+export interface RequestStep extends StepBase {
+    method: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+}
+/**
+ * A value that never travels over HTTP — an emailed verification token, an OTP, a magic link.
+ *
+ * oat declares the need and calls `hooks.resolveOutOfBand` to satisfy it, polling with backoff
+ * because such stores are usually eventually consistent. That hook is the entire coupling
+ * surface between oat and one specific backend.
+ */
+export interface OutOfBandStep {
+    outOfBand: {
+        address: string;
+        kind: string;
+        as: string;
+    };
+}
+export type AuthStep = OperationStep | RequestStep | OutOfBandStep;
+export interface AuthFlow {
+    /** Run in order; values flow forward through the scope. */
+    steps: [AuthStep, ...AuthStep[]];
+    /** Where the credential is in the final response, e.g. `$.access_token`. */
+    credentialFrom: string;
+    /** Lifetime in seconds, e.g. `$.expires_in`. Falls back to a JWT `exp`, then `assumeTtlMs`. */
+    expiresInFrom?: string;
+    /** Header the credential is sent in. Defaults to `authorization`. */
+    header?: string;
+    /** Defaults to `Bearer {credential}`. */
+    template?: string;
+    /** Used only when neither the response nor the credential reveals an expiry. */
+    assumeTtlMs?: number;
+}
+export interface Principal {
+    id: string;
+    /** Sent on every request this principal makes — for a long-lived key, this is all you need. */
+    headers?: Record<string, string>;
+    /** How to obtain a credential. Omit for a principal that authenticates by static header. */
+    auth?: AuthFlow;
+    /** Path parameters this principal owns — its tenant. */
+    roots?: Record<string, string>;
+    /**
+     * Path parameters the flow discovers rather than the config supplying them, mapping a
+     * parameter to the scope key the flow bound. A registration that provisions a tenant then
+     * needs no fixture identifiers configured at all.
+     */
+    rootsFromFlow?: Record<string, string>;
+    /**
+     * Name of this principal's role (`owner`, `admin`, `member`, `viewer`, …). Free-form.
+     * Isolation still keys off `roots`, not this name: two `owner`s in different tenants are
+     * peers; an `owner` and a `viewer` sharing roots are a lattice.
+     */
+    role?: string;
+    /**
+     * Position in the authorization lattice. Higher can do everything a lower rank can.
+     * Same rank + different `roots` is today's two-tenant isolation pair. Defaults to 0.
+     */
+    rank?: number;
+    /**
+     * How the owner names this principal when inviting them — an API key, an email, whatever
+     * the invite operation's body field accepts. Required for `auth.invite-grants-then-revokes`.
+     */
+    inviteAs?: string;
+}
+export interface OutOfBandRequest {
+    address: string;
+    kind: string;
+    /** 1-based; oat retries with backoff until a value arrives or the attempts run out. */
+    attempt: number;
+}
+export interface Hooks {
+    /** Return `null` to ask oat to retry — the value may simply not have arrived yet. */
+    resolveOutOfBand?: (request: OutOfBandRequest) => Promise<string | null>;
+    /**
+     * Removes a principal the run provisioned, and everything that principal created with it.
+     * Usually the only handle that works: per-record deletes are typically owner-scoped, and the
+     * credential dies with the run.
+     */
+    teardownPrincipal?: (address: string) => Promise<void>;
+}
+export interface OatConfig {
+    /** OpenAPI document — an http(s) URL or a filesystem path. JSON or YAML. */
+    spec: string;
+    /** Backend under test. */
+    baseUrl: string;
+    /**
+     * At least one principal. Isolation needs a second with different `roots`. A lattice
+     * needs several that share `roots` and differ in `rank`. Extra principals are not ignored.
+     */
+    principals: [Principal, ...Principal[]];
+    hooks?: Hooks;
+    /** Sent on every request. Opaque to oat — bypass headers, API versioning, tracing. */
+    globalHeaders?: Record<string, string>;
+    /** Path parameters oat cannot create. Also declarable in-spec via `x-root`. */
+    roots?: Record<string, string>;
+    /** Fixture generation derives from this, so a failing run is exactly reproducible. */
+    seed?: number;
+    /** Instances seeded per entity. Larger cohorts discriminate more, and cost more. */
+    cohortSize?: number;
+    /** Entities tested in parallel. Checks within one entity always stay ordered. */
+    concurrency?: number;
+    /** Requests allowed in flight at once. Past a server's comfort this makes runs slower. */
+    maxInFlight?: number;
+    /** Restrict the run to these entity names. */
+    only?: string[];
+    /** Leave created records in place instead of tearing them down. */
+    keepFixtures?: boolean;
+    /** Report destination. Defaults to `./oat-out`. */
+    outDir?: string;
+}
+/**
+ * Identity function that gives a config file full type checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig } from "@lovrozagar/oat"
+ *
+ * export default defineConfig({
+ *   spec: "https://api.example.com/openapi.json",
+ *   baseUrl: "https://api.example.com",
+ *   principals: [{ id: "alpha", headers: { authorization: `Bearer ${process.env.TOKEN}` } }],
+ * })
+ * ```
+ */
+export declare function defineConfig(config: OatConfig): OatConfig;
+export {};
+//# sourceMappingURL=define-config.d.ts.map

package/dist/config/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"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"}

package/dist/config/define-config.js

@@ -0,0 +1,24 @@
+/**
+ * The public configuration surface — and the single source of truth for its types.
+ *
+ * The runtime imports these definitions rather than declaring its own, so a mistake in a config
+ * is a compile error rather than a surprise at request time. Everything backend-specific lives
+ * here or in `x-*` spec tags; oat itself knows nothing about any particular API.
+ */
+/**
+ * Identity function that gives a config file full type checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig } from "@lovrozagar/oat"
+ *
+ * export default defineConfig({
+ *   spec: "https://api.example.com/openapi.json",
+ *   baseUrl: "https://api.example.com",
+ *   principals: [{ id: "alpha", headers: { authorization: `Bearer ${process.env.TOKEN}` } }],
+ * })
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=define-config.js.map

package/dist/config/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2JH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}

package/dist/config/load.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Config loading. A config is a `.js`/`.mjs`/`.ts` module with a default export, or a `.json`
+ * file. TypeScript configs load only where the runtime can strip types (Node 22.6+ with
+ * `--experimental-strip-types`, or Node 23+); the error says so rather than failing obscurely.
+ */
+import type { OatConfig } from "./define-config.ts";
+export declare function loadConfig(path: string): Promise<OatConfig>;
+/** Env-var interpolation so configs can carry `${API_TOKEN}` without embedding secrets. */
+export declare function interpolate<T>(value: T, env?: NodeJS.ProcessEnv): T;
+//# sourceMappingURL=load.d.ts.map

package/dist/config/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEnD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA0BjE;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,CAAC,CAmBhF"}

package/dist/config/load.js

@@ -0,0 +1,61 @@
+/**
+ * Config loading. A config is a `.js`/`.mjs`/`.ts` module with a default export, or a `.json`
+ * file. TypeScript configs load only where the runtime can strip types (Node 22.6+ with
+ * `--experimental-strip-types`, or Node 23+); the error says so rather than failing obscurely.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+export async function loadConfig(path) {
+    const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    if (absolute.endsWith(".json")) {
+        return JSON.parse(await readFile(absolute, "utf8"));
+    }
+    try {
+        const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(absolute).href)));
+        const config = module.default ?? module;
+        if (typeof config !== "object" || config === null) {
+            throw new Error("config module has no default export");
+        }
+        return config;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (absolute.endsWith(".ts") && /Unknown file extension|strip-types/.test(message)) {
+            throw new Error(`oat: cannot load ${path} — this Node build will not import TypeScript directly. ` +
+                "Run with `node --experimental-strip-types`, or use a .js/.mjs config.");
+        }
+        throw new Error(`oat: failed to load config ${path}: ${message}`);
+    }
+}
+/** Env-var interpolation so configs can carry `${API_TOKEN}` without embedding secrets. */
+export function interpolate(value, env = process.env) {
+    if (typeof value === "string") {
+        return value.replace(/\$\{([A-Z0-9_]+)\}/gi, (match, name) => {
+            const resolved = env[name];
+            if (resolved === undefined) {
+                throw new Error(`oat: config references \${${name}}, which is not set in the environment`);
+            }
+            return resolved;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((item) => interpolate(item, env));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = interpolate(item, env);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=load.js.map