slicetest 0.4.0 → 0.5.0

package/dist/drivers/mysql.js

@@ -134,6 +134,44 @@ export class MysqlDriver {
         const conds = Object.keys(where).map((k) => `${this.column(k)} = ?`);
         return this.query(`SELECT * FROM ${this.ident(table)} WHERE ${conds.join(" AND ")}`, Object.values(where));
     }
+    async describe(table) {
+        const [schema, name] = table.includes(".") ? table.split(".", 2) : [null, table];
+        const columns = await this.query(`SELECT COLUMN_NAME AS name, COLUMN_TYPE AS type, IS_NULLABLE AS nullable, COLUMN_DEFAULT AS dflt, EXTRA AS extra,
+              CHARACTER_MAXIMUM_LENGTH AS max
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION`, [schema, name]);
+        if (columns.length === 0)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const keys = await this.query(`SELECT CONSTRAINT_NAME AS id, COLUMN_NAME AS \`column\`, REFERENCED_TABLE_SCHEMA AS \`schema\`,
+              REFERENCED_TABLE_NAME AS \`table\`, REFERENCED_COLUMN_NAME AS ref, DATABASE() AS current
+         FROM information_schema.KEY_COLUMN_USAGE
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL
+        ORDER BY CONSTRAINT_NAME, ORDINAL_POSITION`, [schema, name]);
+        const foreignKeys = new Map();
+        for (const k of keys) {
+            const fk = foreignKeys.get(k.id) ?? { columns: [], table: k.schema === k.current ? k.table : `${k.schema}.${k.table}`, references: [] };
+            fk.columns.push(k.column);
+            fk.references.push(k.ref);
+            foreignKeys.set(k.id, fk);
+        }
+        const checks = await this.query(`SELECT c.CHECK_CLAUSE AS def
+         FROM information_schema.CHECK_CONSTRAINTS c
+         JOIN information_schema.TABLE_CONSTRAINTS t ON t.CONSTRAINT_SCHEMA = c.CONSTRAINT_SCHEMA AND t.CONSTRAINT_NAME = c.CONSTRAINT_NAME
+        WHERE t.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND t.TABLE_NAME = ?`, [schema, name]);
+        return {
+            columns: columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable === "YES",
+                hasDefault: c.dflt !== null || /auto_increment|generated/i.test(c.extra),
+                maxLength: c.max === null ? undefined : Number(c.max),
+                values: /^enum\(/i.test(c.type) ? [...c.type.matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'")) : undefined,
+            })),
+            foreignKeys: [...foreignKeys.values()],
+            checks: checks.map((c) => c.def),
+        };
+    }
     async #primaryKey(table) {
         let key = this.#keys.get(table);
         if (!key) {

package/dist/drivers/postgres.d.ts

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
 export declare class PostgresDriver implements Driver {
     private readonly client;
     private constructor();
@@ -14,6 +14,7 @@ export declare class PostgresDriver implements Driver {
     listTables(schemas: string[], keep: string[]): Promise<Table[]>;
     truncate(tables: Table[]): Promise<void>;
     insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 export declare const postgres: Engine;

package/dist/drivers/postgres.js

@@ -88,6 +88,34 @@ export class PostgresDriver {
             : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.ident(c)).join(", ")}) VALUES (${cols.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING *`;
         return this.query(sql, Object.values(row));
     }
+    async describe(table) {
+        const [{ oid } = { oid: null }] = await this.query("SELECT to_regclass($1)::oid AS oid", [this.ident(table)]);
+        if (oid === null)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const columns = await this.query(`SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type, NOT a.attnotnull AS nullable,
+              (a.atthasdef OR a.attidentity <> '' OR a.attgenerated <> '') AS has_default,
+              information_schema._pg_char_max_length(a.atttypid, a.atttypmod) AS max,
+              (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder) FROM pg_enum e WHERE e.enumtypid = a.atttypid) AS values
+         FROM pg_attribute a
+        WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY a.attnum`, [oid]);
+        const keys = await this.query(`SELECT (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(c.conkey) WITH ORDINALITY k(n, ord)
+                JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.n) AS columns,
+              n.nspname AS schema, r.relname AS table,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(c.confkey) WITH ORDINALITY k(n, ord)
+                JOIN pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.n) AS references
+         FROM pg_constraint c
+         JOIN pg_class r ON r.oid = c.confrelid
+         JOIN pg_namespace n ON n.oid = r.relnamespace
+        WHERE c.contype = 'f' AND c.conrelid = $1
+        ORDER BY c.conname`, [oid]);
+        const checks = await this.query("SELECT pg_get_constraintdef(oid) AS def FROM pg_constraint WHERE contype = 'c' AND conrelid = $1", [oid]);
+        return {
+            columns: columns.map((c) => ({ name: c.name, type: c.type, nullable: c.nullable, hasDefault: c.has_default, maxLength: c.max ?? undefined, values: c.values ?? undefined })),
+            foreignKeys: keys.map((k) => ({ columns: k.columns, table: k.schema === "public" ? k.table : `${k.schema}.${k.table}`, references: k.references })),
+            checks: checks.map((c) => c.def),
+        };
+    }
     async close() {
         await this.client.end();
     }

package/dist/drivers/sqlite.d.ts

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
 /** `sqlite:///tmp/a.db` → `/tmp/a.db`; `sqlite:///C:/x/a.db` → `C:/x/a.db`. Plain paths pass through. */
 export declare function sqlitePath(url: string): string;
 export declare function sqliteUrl(file: string): string;
@@ -18,6 +18,7 @@ export declare class SqliteDriver implements Driver {
     /** DELETE, then forget AUTOINCREMENT counters. Foreign keys are off for this connection only. */
     truncate(tables: Table[]): Promise<void>;
     insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 export declare const sqliteEngine: Engine;

package/dist/drivers/sqlite.js

@@ -35,6 +35,27 @@ export function sqliteUrl(file) {
     return `sqlite://${p.startsWith("/") ? "" : "/"}${p}`;
 }
 /** Values node:sqlite can't bind are stored the way an app would store them. */
+/** The parenthesised bodies of every CHECK in a CREATE TABLE statement. */
+function checkBodies(sql) {
+    const bodies = [];
+    for (const m of sql.matchAll(/\bcheck\s*\(/gi)) {
+        let depth = 1;
+        let i = m.index + m[0].length;
+        const start = i;
+        for (; i < sql.length && depth > 0; i++) {
+            if (sql[i] === "'")
+                i = sql.indexOf("'", i + 1);
+            else if (sql[i] === "(")
+                depth++;
+            else if (sql[i] === ")")
+                depth--;
+            if (i < 0)
+                return bodies;
+        }
+        bodies.push(sql.slice(start, i - 1));
+    }
+    return bodies;
+}
 function bind(v) {
     if (typeof v === "boolean")
         return v ? 1 : 0;
@@ -117,6 +138,37 @@ export class SqliteDriver {
             : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.column(c)).join(", ")}) VALUES (${cols.map((_, i) => `?${i + 1}`).join(", ")}) RETURNING *`;
         return this.query(sql, Object.values(row));
     }
+    async describe(table) {
+        const [master] = await this.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?1", [table]);
+        if (!master)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const columns = await this.query("SELECT name, type, \"notnull\", dflt_value, pk, hidden FROM pragma_table_xinfo(?1) ORDER BY cid", [table]);
+        const pk = columns.filter((c) => c.pk > 0);
+        // An INTEGER PRIMARY KEY is the rowid: SQLite assigns it.
+        const rowid = pk.length === 1 && pk[0].type.toUpperCase() === "INTEGER" ? pk[0].name : undefined;
+        const keys = await this.query('SELECT id, "table", "from", "to" FROM pragma_foreign_key_list(?1) ORDER BY id, seq', [table]);
+        const foreignKeys = new Map();
+        for (const k of keys) {
+            const fk = foreignKeys.get(k.id) ?? { columns: [], table: k.table, references: [] };
+            fk.columns.push(k.from);
+            if (k.to !== null)
+                fk.references.push(k.to);
+            foreignKeys.set(k.id, fk);
+        }
+        return {
+            columns: columns
+                .filter((c) => c.hidden !== 1)
+                .map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.notnull === 0 && c.pk === 0,
+                hasDefault: c.dflt_value !== null || c.hidden > 1 || c.name === rowid,
+                maxLength: Number(/\((\d+)\)/.exec(c.type)?.[1]) || undefined,
+            })),
+            foreignKeys: [...foreignKeys.values()],
+            checks: checkBodies(master.sql),
+        };
+    }
     async close() {
         this.db.close();
     }

package/dist/factory.d.ts

@@ -0,0 +1,21 @@
+import type { Column, Row, TableShape } from "./drivers/driver.js";
+/**
+ * `db.make()`: rows that satisfy the schema without spelling it out. Required
+ * columns the caller doesn't give get a value of their type, enum and
+ * `CHECK (col IN (...))` columns their first allowed value, and required
+ * foreign keys a parent row made the same way. Values are numbered per
+ * scenario, so they are unique and the same on every run.
+ */
+export declare class Factory {
+    #private;
+    private readonly describe;
+    private readonly insert;
+    constructor(describe: (table: string) => Promise<TableShape>, insert: (table: string, row: Row) => Promise<Row[]>);
+    /** Restart numbering; called when the database is reset. */
+    reset(): void;
+    make(table: string, overrides?: Row, path?: string[]): Promise<Row>;
+}
+/** String literals allowed by a CHECK on `column` such as `status IN ('open', 'closed')` or `status = ANY (ARRAY[...])`. */
+export declare function allowedValues(column: string, checks: string[]): string[] | undefined;
+/** A value of `column`'s type, distinct for each `n`. */
+export declare function valueFor(table: string, column: Column, n: number, allowed?: string[]): unknown;

package/dist/factory.js

@@ -0,0 +1,129 @@
+/**
+ * `db.make()`: rows that satisfy the schema without spelling it out. Required
+ * columns the caller doesn't give get a value of their type, enum and
+ * `CHECK (col IN (...))` columns their first allowed value, and required
+ * foreign keys a parent row made the same way. Values are numbered per
+ * scenario, so they are unique and the same on every run.
+ */
+export class Factory {
+    describe;
+    insert;
+    #n = 0;
+    #shapes = new Map();
+    constructor(describe, insert) {
+        this.describe = describe;
+        this.insert = insert;
+    }
+    /** Restart numbering; called when the database is reset. */
+    reset() {
+        this.#n = 0;
+    }
+    async make(table, overrides = {}, path = []) {
+        const shape = await this.#shape(table);
+        for (const col of Object.keys(overrides)) {
+            if (!shape.columns.some((c) => c.name === col)) {
+                throw new Error(`slicetest: db.make("${table}"): there is no column "${col}" (columns: ${shape.columns.map((c) => c.name).join(", ")})`);
+            }
+        }
+        const n = ++this.#n;
+        const row = { ...overrides };
+        const byName = new Map(shape.columns.map((c) => [c.name, c]));
+        const needed = (name) => {
+            const c = byName.get(name);
+            return !!c && !c.nullable && !c.hasDefault && !(name in row);
+        };
+        for (const fk of shape.foreignKeys) {
+            // Only fill keys that must be set and that the caller left entirely to us.
+            if (!fk.columns.some(needed) || fk.columns.some((c) => c in overrides))
+                continue;
+            if (fk.table === table || path.includes(fk.table)) {
+                const chain = [...path, table, fk.table].join(" → ");
+                throw new Error(`slicetest: db.make("${table}") can't create a parent for ${fk.columns.join(", ")}: the foreign keys form a cycle (${chain}). Pass ${fk.columns.join(", ")} yourself.`);
+            }
+            const parent = await this.make(fk.table, {}, [...path, table]);
+            const refs = fk.references.length ? fk.references : (await this.#primaryKey(fk.table, parent));
+            fk.columns.forEach((c, i) => (row[c] = parent[refs[i]]));
+        }
+        for (const c of shape.columns) {
+            if (needed(c.name))
+                row[c.name] = valueFor(table, c, n, allowedValues(c.name, shape.checks));
+        }
+        try {
+            const [stored] = await this.insert(table, row);
+            return stored ?? row;
+        }
+        catch (e) {
+            const generated = Object.fromEntries(Object.entries(row).filter(([k]) => !(k in overrides)));
+            throw new Error(`slicetest: db.make("${table}") failed: ${e.message}\n` +
+                `  generated: ${JSON.stringify(generated)}\n` +
+                `  pass the columns that need specific values, e.g. db.make("${table}", { ${Object.keys(generated)[0] ?? "column"}: ... })`, { cause: e });
+        }
+    }
+    #shape(table) {
+        let shape = this.#shapes.get(table);
+        if (!shape) {
+            shape = this.describe(table);
+            this.#shapes.set(table, shape);
+            shape.catch(() => this.#shapes.delete(table));
+        }
+        return shape;
+    }
+    /** SQLite foreign keys may omit the referenced columns: they mean the parent's primary key, or its rowid. */
+    async #primaryKey(table, parent) {
+        const shape = await this.#shape(table);
+        const key = shape.columns.filter((c) => c.hasDefault && /^integer$/i.test(c.type)).map((c) => c.name);
+        return key.length ? key : Object.keys(parent).slice(0, 1);
+    }
+}
+/** String literals allowed by a CHECK on `column` such as `status IN ('open', 'closed')` or `status = ANY (ARRAY[...])`. */
+export function allowedValues(column, checks) {
+    const esc = column.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const mention = new RegExp(`(^|[^\\w])[\`"]?${esc}[\`"]?\\)?(::\\w+(\\s\\w+)?)?\\s*(in\\s*\\(|=\\s*any\\s*\\()`, "i");
+    for (const check of checks) {
+        if (!mention.test(check))
+            continue;
+        const literals = [...check.matchAll(/(?:_\w+)?'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'"));
+        if (literals.length)
+            return literals;
+    }
+    return undefined;
+}
+const EPOCH = Date.UTC(2026, 0, 1);
+/** A value of `column`'s type, distinct for each `n`. */
+export function valueFor(table, column, n, allowed) {
+    const values = column.values?.length ? column.values : allowed;
+    if (values?.length)
+        return values[0];
+    const t = column.type.toLowerCase();
+    if (/\[\]$/.test(t))
+        return "{}";
+    if (/^bool/.test(t) || t === "tinyint(1)")
+        return false;
+    if (/uuid/.test(t))
+        return `00000000-0000-4000-8000-${n.toString(16).padStart(12, "0")}`;
+    if (/json/.test(t))
+        return "{}";
+    if (/^(timestamp|datetime)/.test(t))
+        return new Date(EPOCH + n * 1000).toISOString().slice(0, 19).replace("T", " ");
+    if (/^date/.test(t))
+        return new Date(EPOCH + (n - 1) * 86_400_000).toISOString().slice(0, 10);
+    if (/^time/.test(t))
+        return "00:00:00";
+    if (/int|serial|numeric|decimal|real|double|float|money|number/.test(t))
+        return n;
+    if (/bytea|blob|binary/.test(t))
+        return Buffer.from(String(n));
+    if (/^inet/.test(t))
+        return `10.0.${Math.floor(n / 256) % 256}.${n % 256}`;
+    if (t === "" || /char|text|clob|string|citext|name/.test(t))
+        return text(table, column, n);
+    throw new Error(`slicetest: db.make("${table}") doesn't know how to make a value for ${column.name} (${column.type}); pass it yourself: db.make("${table}", { ${column.name}: ... })`);
+}
+function text(table, column, n) {
+    const name = column.name.toLowerCase();
+    let s = /e_?mail/.test(name) ? `${table}-${n}@example.test` : /url|website|link/.test(name) ? `https://example.test/${table}/${n}` : `${column.name}-${n}`;
+    const max = column.maxLength;
+    if (max !== undefined && s.length > max)
+        s = String(n).padStart(max, "0").slice(-max);
+    return s;
+}

package/dist/gen.d.ts

@@ -21,4 +21,5 @@ export declare function gen(root: string, opts: GenOptions): Promise<{
     written: string[];
     skipped: string[];
     count: number;
+    needsAuth: boolean;
 }>;

package/dist/gen.js

@@ -58,7 +58,7 @@ export async function gen(root, opts) {
         await writeFile(file, header + stringify({ scenarios }, { lineWidth: 0, aliasDuplicateObjects: false }));
         written.push(rel);
     }
-    return { written, skipped, count };
+    return { written, skipped, count, needsAuth: ops.some((o) => o.bearer) };
 }
 function scenarioFor(op, key, all) {
     const steps = [];
@@ -80,9 +80,11 @@ function scenarioFor(op, key, all) {
     // Two error responses need no arranging: a made-up id is not found, and an empty body is invalid.
     const notFound = status === 404 && Object.keys(op.pathParams).length > 0;
     const invalid = (status === 400 || status === 422) && isFilledObject(op.json);
-    steps.push(requestStep(invalid ? { ...op, json: {} } : op, pathText, { status }));
+    // A protected operation answers 401 to a request without a token, whatever its state.
+    const unauthenticated = status === 401 && !!op.bearer;
+    steps.push(requestStep(invalid ? { ...op, json: {} } : op, pathText, { status }, undefined, unauthenticated));
     const name = `${op.method} ${op.template} → ${key}${op.summary ? ` (${op.summary})` : ""}`;
-    const runnable = success ? !unresolved : notFound || invalid;
+    const runnable = success ? !unresolved : notFound || invalid || unauthenticated;
     return runnable ? { name, steps } : { name: `${name} — TODO: arrange the state that produces this`, skip: true, steps };
 }
 /**
@@ -99,8 +101,11 @@ function creatorFor(op, param, all) {
     const status = post.responses.filter((k) => /^2\d\d$/.test(k)).sort()[0];
     return field && status ? { op: post, field, status } : undefined;
 }
-function requestStep(op, pathText, expect, capture) {
+function requestStep(op, pathText, expect, capture, anonymous = false) {
     const step = { request: `${op.method} ${pathText}` };
+    // Tokens come from the `auth` issuer; scopes the spec requires go into the `scope` claim.
+    if (op.bearer && !anonymous)
+        step.auth = op.bearer.scopes.length ? { scope: op.bearer.scopes.join(" ") } : true;
     if (Object.keys(op.query).length)
         step.query = Object.fromEntries(Object.entries(op.query).map(([k, v]) => [k, String(v)]));
     if (op.json !== undefined)

package/dist/http.d.ts

@@ -1,3 +1,4 @@
+import { type WebhookOptions } from "./webhook.js";
 export interface HttpResponse {
     method: string;
     url: string;
@@ -37,6 +38,12 @@ export declare class HttpClient {
     post(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     put(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     patch(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path: string, payload: unknown, opts: WebhookOptions): Promise<HttpResponse>;
     /**
      * Run `send` `n` times at once and wait for every response, to provoke races
      * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`

package/dist/http.js

@@ -1,3 +1,4 @@
+import { signWebhook, webhookBody } from "./webhook.js";
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 class Session {
     cookies = new Map();
@@ -41,6 +42,15 @@ export class HttpClient {
     patch(path, body, opts) {
         return this.request("PATCH", path, body, opts);
     }
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path, payload, opts) {
+        const { body, type } = webhookBody(payload);
+        return this.request("POST", path, body, { headers: { "content-type": type, ...signWebhook(body, opts), ...opts.headers } });
+    }
     /**
      * Run `send` `n` times at once and wait for every response, to provoke races
      * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`

package/dist/index.d.ts

@@ -3,10 +3,13 @@ export { mask } from "./trace.js";
 export type { Trace, MaskOptions } from "./trace.js";
 export type { ScenarioContext } from "./runtime.js";
 export type { Db, Row, Where, RowsOptions, Changes, TableChanges } from "./db.js";
-export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder } from "./stub.js";
+export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder, ChaosOptions } from "./stub.js";
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
 export type { App } from "./app.js";
 export type { Dependency } from "./containers.js";
 export type { Mailbox, Mail, MailFilter } from "./mail.js";
+export type { Issuer, TokenOptions, AuthOptions } from "./auth.js";
+export { normalizeSql, type Query, type QueryList } from "./query-log.js";
+export { signWebhook, type WebhookOptions, type WebhookProvider, type HmacScheme } from "./webhook.js";
 export type { SlicetestOptions, ContainerOptions } from "./config.js";
 export type {} from "./matchers.js";

package/dist/index.js

@@ -1,2 +1,4 @@
 export { scenario } from "./scenario.js";
 export { mask } from "./trace.js";
+export { normalizeSql } from "./query-log.js";
+export { signWebhook } from "./webhook.js";

package/dist/init.js

@@ -107,6 +107,12 @@ export async function detect(root) {
         env.DATABASE_URL = sqlite.url;
         notes.push(`db: SQLite (${sqlite.why}), no container needed. The app gets DATABASE_URL=${sqlite.url}; {{db.path}} is the plain file path`);
     }
+    const auth = await authFromEnvExample(root, read, env, notes);
+    const jwtDeps = ["jose", "jsonwebtoken", "passport-jwt", "express-oauth2-jwt-bearer", "express-jwt", "jwks-rsa", "@fastify/jwt", "next-auth"].filter((d) => deps[d]);
+    const jwtPython = /\b(pyjwt|python-jose|authlib|fastapi-azure-auth|djangorestframework-simplejwt)\b/i.exec(python)?.[1];
+    if (!auth && (jwtDeps.length || jwtPython)) {
+        notes.push(`auth: ${jwtDeps[0] ?? jwtPython} is a dependency, so the app may verify JWTs. To test with real tokens, add \`auth: true\` and pass {{auth.issuer}} / {{auth.jwks}} / {{auth.audience}} to the variables the app reads`);
+    }
     const stubs = await stubsFromEnvExample(root, read, env, notes);
     const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
     if (!composeDb.engine && mysqlDeps) {
@@ -122,6 +128,7 @@ export async function detect(root) {
         ...(migrate || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
         ...(Object.keys(containers).length ? { containers } : {}),
         ...(mail ? { mail: true } : {}),
+        ...(auth ? { auth: true } : {}),
         stubs,
         ...(openapi ? { openapi } : {}),
     };
@@ -150,6 +157,42 @@ async function detectSqlite(root, read, deps, python, gemfile) {
         return { why: "a SQLite driver is a dependency", url: "{{db.url}}" };
     return undefined;
 }
+/** Variables that tell the app which token issuer to trust, and what slicetest passes instead. */
+const AUTH_VARS = [
+    [/JWKS(_URL|_URI|_ENDPOINT)?$/, "{{auth.jwks}}"],
+    [/(ISSUER|ISSUER_URL|ISSUER_BASE_URL|AUTHORITY)$/, "{{auth.issuer}}"],
+    [/^(AUTH0|OKTA|KEYCLOAK|COGNITO|OIDC|OAUTH2?|AUTH|JWT)_?(DOMAIN|URL|BASE_URL)$/, "{{auth.issuer}}"],
+    [/(AUDIENCE|_AUD)$/, "{{auth.audience}}"],
+];
+/**
+ * `.env.example` variables naming a token issuer (`OIDC_ISSUER`, `AUTH0_DOMAIN`,
+ * `JWKS_URL`, `JWT_AUDIENCE`) turn on `auth`, with the variables pointed at
+ * slicetest's issuer. Returns whether any was found.
+ */
+async function authFromEnvExample(root, read, env, notes) {
+    const file = [".env.example", ".env.sample", ".env.template", ".env.dist"].find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return false;
+    const found = [];
+    for (const line of (await read(file)).split(/\r?\n/)) {
+        const name = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/.exec(line)?.[1];
+        if (!name || name in env)
+            continue;
+        const match = AUTH_VARS.find(([re]) => re.test(name));
+        // AUDIENCE alone doesn't say the app verifies tokens; it comes along with an issuer or JWKS.
+        if (!match)
+            continue;
+        env[name] = match[1];
+        found.push(name);
+    }
+    if (!found.some((n) => env[n] !== "{{auth.audience}}")) {
+        for (const n of found)
+            delete env[n];
+        return false;
+    }
+    notes.push(`auth: ${found.join(", ")} in ${file} point at slicetest's OpenID issuer; scenarios mint tokens with auth.token({ sub, ... }) or \`auth:\` on a YAML request. An issuer the app expects as a bare domain (Auth0) may need the variable reshaped`);
+    return true;
+}
 /** Hosts that are never third-party APIs to stub. */
 const LOCAL_HOST = /^(localhost|127\.|0\.0\.0\.0|\[::1\]|host\.docker\.internal|[\w-]+$)/;
 /**
@@ -164,7 +207,7 @@ async function stubsFromEnvExample(root, read, env, notes) {
     const stubs = [];
     for (const line of (await read(file)).split(/\r?\n/)) {
         const m = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*["']?(https?:\/\/[^\s"'#]+)/.exec(line);
-        if (!m || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
+        if (!m || m[1] in env || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
             continue;
         const url = new URL(m[2]);
         if (LOCAL_HOST.test(url.hostname))

package/dist/openapi.d.ts

@@ -15,6 +15,14 @@ export interface OperationSketch {
     responses: string[];
     /** Top-level properties of the first 2xx JSON response. */
     createdFields: string[];
+    /**
+     * The operation requires a bearer token (an `http: bearer`, `oauth2` or
+     * `openIdConnect` security scheme), with the scopes it lists. Undefined when
+     * it needs no token or accepts other credentials only.
+     */
+    bearer?: {
+        scopes: string[];
+    };
 }
 export interface Message {
     status?: number;

package/dist/openapi.js

@@ -157,9 +157,27 @@ export class OpenApiSpec {
                 json: json ?? undefined,
                 responses,
                 createdFields: okSchema?.properties ? Object.keys(okSchema.properties) : [],
+                bearer: this.#bearer(op.security ?? this.doc.security),
             };
         });
     }
+    #bearer(security) {
+        if (!Array.isArray(security) || security.length === 0)
+            return undefined;
+        // An empty requirement makes credentials optional.
+        if (security.some((req) => Object.keys(req ?? {}).length === 0))
+            return undefined;
+        const schemes = this.doc.components?.securitySchemes ?? {};
+        for (const req of security) {
+            for (const [name, scopes] of Object.entries(req)) {
+                const s = this.#deref(schemes[name]);
+                if (s && ((s.type === "http" && String(s.scheme).toLowerCase() === "bearer") || s.type === "oauth2" || s.type === "openIdConnect")) {
+                    return { scopes: Array.isArray(scopes) ? scopes : [] };
+                }
+            }
+        }
+        return undefined;
+    }
     /** A value that satisfies `schema` (as far as a simple walk can): examples, defaults, enums, then types. */
     #sample(schema, depth = 0) {
         const s = this.#deref(schema);

package/dist/query-log.d.ts

@@ -0,0 +1,49 @@
+export interface Query {
+    sql: string;
+    /** Milliseconds since the log started. */
+    at: number;
+}
+/** A list of queries, with helpers for spotting N+1 patterns. */
+export declare class QueryList extends Array<Query> {
+    /** Statements grouped by shape (literals and parameters replaced by `?`), most frequent first. */
+    shapes(): {
+        sql: string;
+        count: number;
+    }[];
+    /** Without transaction control and session statements (`BEGIN`, `COMMIT`, `SAVEPOINT`, `SET`, …), which some drivers add around every query. */
+    withoutTransactions(): QueryList;
+    /** Shapes run at least `min` times (default 3): the usual signature of an N+1. */
+    repeated(min?: number): {
+        sql: string;
+        count: number;
+    }[];
+}
+export declare function queryList(queries: Query[]): QueryList;
+/** `SELECT * FROM t WHERE id = 7 AND name = 'x'` → `SELECT * FROM t WHERE id = ? AND name = ?`. */
+export declare function normalizeSql(sql: string): string;
+type Engine = "postgres" | "mysql";
+/**
+ * A TCP proxy between the app and its database that reads the wire protocol
+ * and records every statement the app runs, whatever its language or driver.
+ * Postgres: simple queries and extended-protocol executions. MySQL: COM_QUERY
+ * and prepared-statement executions. Connections that switch to TLS are
+ * forwarded but not read.
+ */
+export declare class QueryLog {
+    #private;
+    private readonly server;
+    readonly port: number;
+    private constructor();
+    static start(engine: Engine, upstream: {
+        host: string;
+        port: number;
+    }): Promise<QueryLog>;
+    /** `url` with its host and port pointing at the proxy. */
+    proxyUrl(url: string): string;
+    /** Queries since the last `reset()`, or since `mark` (an index from `mark()`). */
+    queries(since?: number): QueryList;
+    mark(): number;
+    reset(): void;
+    close(): Promise<void>;
+}
+export {};