@zenera/faker 1.1.23 → 1.1.24

package/README.md

@@ -57,8 +57,8 @@ zen faker cache clear                # throw it away
 
 `zen mock` is the same command under a shorter noun.
 
-A path key with a query string on it — `/x/{id}?action=retry`, which VMware NSX
-and others write when they need two `post`s under one path — is read for what
+A path key with a query string on it — `/x/{id}?action=retry`, which some
+vendors write when they need two `post`s under one path — is read for what
 it means rather than taken verbatim: the path is the part before the `?`, and
 each pair after it becomes a required query value that tells those operations
 apart. Call one without it and the 404 says which queries the path answers to.
@@ -75,11 +75,17 @@ for. `GET /users/12324` answering with somebody else's id validates perfectly
 and is still wrong.
 
 If it fails, the diagnostics go back to the model and it tries again, up to
-`--attempts`. If it passes, the generator is kept in this machine's shared cache
-under `~/.zenera/neo/cache/faker-generator/`, keyed by the operation's shape, and
-every later request is just `podman exec python3 gen.py in.json out.json` - no
-model, no tokens. The store is the machine's, so the same document served from
-another directory costs nothing the second time.
+`--attempts` (five by default). A build that does not come good leaves a
+**report** in `<cache>/builds/` - one markdown file per build, every rejected
+attempt in it with its diagnostics and its whole source, and the `501` that the
+request gets links to it, in the log line and in the body. The next attempt
+overwrites `gen.py`, and a generator that merely hung leaves no traceback, so
+the code is the only evidence there is. If it passes, the generator is kept in
+this machine's shared cache under `~/.zenera/neo/cache/faker-generator/`, keyed
+by the operation's shape, and every later request is just
+`podman exec python3 gen.py in.json out.json` - no model, no tokens. The store
+is the machine's, so the same document served from another directory costs
+nothing the second time.
 
 Generators run in a container with **no network**, on an image baked once with
 `faker`, `exrex`, `jsonschema` and `python-dateutil`.

package/dist/cache.d.ts

@@ -27,6 +27,8 @@ export interface CacheEvent {
     operation: Operation;
     attempt?: number;
     diagnostics?: readonly string[];
+    /** where the rejected generator was written down, when it was */
+    dump?: string;
 }
 export interface CacheOptions {
     box: Box;
@@ -46,6 +48,8 @@ export interface CacheOptions {
     ephemeral?: boolean;
     /** keep them somewhere other than the shared store */
     cacheDir?: string;
+    /** where rejected generators are written down. Default `<box root>/builds` */
+    dumpDir?: string;
     onStart?: (e: CacheEvent) => void;
     onAttempt?: (e: CacheEvent) => void;
     onReady?: (e: CacheEvent & {

package/dist/cache.js

@@ -1,5 +1,7 @@
 import { Cache as Store } from '@zenera/cli/lib';
+import { join } from 'node:path';
 import { build, BuildFailed, regenerate } from "./generate.js";
+import { saveBuildDump } from "./logger.js";
 import { GENERATOR_RULES_VERSION } from "./spec.js";
 // ---------------------------------------------------------------------------
 // The cache
@@ -24,6 +26,8 @@ const DEFAULT_CONCURRENCY = 4;
 export class Cache {
     #opts;
     #store;
+    #dumpDir;
+    #records = new Map();
     #live = new Map();
     #settled = new Set();
     #slots;
@@ -32,6 +36,7 @@ export class Cache {
     constructor(opts) {
         this.#opts = opts;
         this.#store = new Store(FAKER_KIND, { dir: opts.cacheDir, mode: 0o600 });
+        this.#dumpDir = opts.dumpDir ?? join(opts.box.root, 'builds');
         this.#slots = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
     }
     /**
@@ -87,7 +92,7 @@ export class Cache {
                 fault: ctx.fault,
                 stderr: ctx.stderr,
                 examples: ctx.examples,
-                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+                onAttempt: (attempt, diagnostics, source, limit) => this.#rejected(operation, attempt, diagnostics, source, limit, true),
             });
             if (!ephemeral) {
                 this.#store.put(operation.key, {
@@ -108,11 +113,13 @@ export class Cache {
             const gen = { key: operation.key, source: built.source, cached: false };
             this.#settled.add(operation.key);
             this.#live.set(operation.key, Promise.resolve(gen));
+            await this.#finished(operation);
             return gen;
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            this.#opts.onFail?.({ operation, error });
+            const dump = await this.#finished(operation, error);
+            this.#opts.onFail?.({ operation, error, dump });
             throw error;
         }
         finally {
@@ -136,7 +143,7 @@ export class Cache {
                 box,
                 checks,
                 attempts: this.#opts.attempts,
-                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+                onAttempt: (attempt, diagnostics, source, limit) => this.#rejected(operation, attempt, diagnostics, source, limit, false),
             });
             if (!ephemeral) {
                 this.#store.put(operation.key, {
@@ -154,17 +161,78 @@ export class Cache {
                 });
             }
             this.#opts.onReady?.({ operation, cached: false, attempts: built.attempts });
+            await this.#finished(operation);
             return { key: operation.key, source: built.source, cached: false };
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            this.#opts.onFail?.({ operation, error });
+            const dump = await this.#finished(operation, error);
+            this.#opts.onFail?.({ operation, error, dump });
             throw error;
         }
         finally {
             this.#leave();
         }
     }
+    /**
+     * An attempt the judge threw out. The report is rewritten with the file
+     * still in it before the next attempt overwrites `gen.py` — for a timeout
+     * that source is the only evidence there will ever be, since a generator
+     * that hangs leaves no traceback behind.
+     */
+    async #rejected(operation, attempt, diagnostics, source, limit, regeneration) {
+        let record = this.#records.get(operation.key);
+        if (!record || attempt === 1) {
+            record = {
+                operation,
+                started: new Date(),
+                limit,
+                regeneration,
+                attempts: [],
+            };
+            this.#records.set(operation.key, record);
+        }
+        record.attempts.push({ attempt, at: new Date(), diagnostics, source });
+        await this.#report(record);
+        this.#opts.onAttempt?.({ operation, attempt, diagnostics, dump: record.path });
+    }
+    /** A report that cannot be written is not worth failing a build over. */
+    async #report(record, gaveUp = false) {
+        try {
+            record.path = await saveBuildDump(this.#dumpDir, {
+                started: record.started,
+                operationId: record.operation.operationId,
+                method: record.operation.method,
+                path: record.operation.path,
+                key: record.operation.key,
+                limit: record.limit,
+                regeneration: record.regeneration,
+                model: this.#opts.model.id,
+                attempts: record.attempts,
+                gaveUp,
+            });
+        }
+        catch {
+            // no report, then — the narration still says what failed
+        }
+    }
+    /**
+     * The end of a build, either way. A failure is stamped as such and its
+     * report handed to the error, so the request that gets the 501 can say
+     * where to read about it.
+     */
+    async #finished(operation, error) {
+        const record = this.#records.get(operation.key);
+        this.#records.delete(operation.key);
+        if (!record) {
+            return undefined;
+        }
+        if (error instanceof BuildFailed) {
+            await this.#report(record, true);
+            error.dump = record.path;
+        }
+        return record.path;
+    }
     /**
      * A hit is written into the box before it is returned. The container runs
      * files under its mount and nothing else, and the mount is scratch that any

package/dist/command.js

@@ -5,6 +5,7 @@ import { join, relative, resolve } from 'node:path';
 import { GENERATORS } from "./box.js";
 import { FAKER_KIND } from "./cache.js";
 import { reason } from "./generate.js";
+import { formatDumpPath } from "./logger.js";
 import { listen } from "./server.js";
 import { chooseModel, MODEL_ENV, open, readSettings, SOURCE_LABELS, writeSettings, } from "./setup.js";
 import { called } from "./spec.js";
@@ -60,7 +61,7 @@ export const command = {
             ['  --image <ref>', dim('Skip the baked image and use this one.')],
             ['  --cache <dir>', dim("The container's workspace. Default ~/.zenera/neo/faker.")],
             ['  --seed <n>', dim('Answer the same request the same way every time.')],
-            ['  --attempts <n>', dim('Tries per generator before giving up. Default 3.')],
+            ['  --attempts <n>', dim('Tries per generator before giving up. Default 5.')],
             ['  --concurrency <n>', dim('Generators written at once. Default 4.')],
             ['  --timeout <s>', dim('Seconds one generator may take. Default 30.')],
             ['  --max-body <n>', dim('Largest request body accepted, in bytes.')],
@@ -125,6 +126,7 @@ async function serve(args, ctx) {
         }
         note(dim(`generators: ${setup.root}/${GENERATORS}`));
         note(dim(`request logs: ${requestsDir ?? `${setup.root}/requests`}`));
+        note(dim(`failed builds: ${setup.root}/builds`));
     }
     // The address is the answer; the rest was narration.
     write(`http://${host}:${listener.port}`);
@@ -385,7 +387,12 @@ async function start(values, specs, ctx, what) {
                     : note(`  ${green('ready')} ${dim(operation.operationId)}`)
                 : undefined,
             onFail: loud
-                ? ({ operation, error }) => note(`  ${red('gave up')} ${dim(operation.operationId)} ${reason(error)}`)
+                ? ({ operation, error, dump }) => {
+                    note(`  ${red('gave up')} ${dim(operation.operationId)} ${reason(error)}`);
+                    if (dump) {
+                        note(formatDumpPath('report', dump));
+                    }
+                }
                 : undefined,
         },
     });

package/dist/generate.d.ts

@@ -10,13 +10,20 @@ export interface BuildOptions {
     checks: Checks;
     /** how many times the model may be asked before giving up */
     attempts?: number;
-    onAttempt?: (attempt: number, diagnostics: readonly string[]) => void;
+    onAttempt?: (attempt: number, diagnostics: readonly string[], source: string, limit: number) => void | Promise<void>;
     signal?: AbortSignal;
 }
 export interface Built {
     source: string;
     attempts: number;
 }
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export declare const DEFAULT_ATTEMPTS = 5;
 export interface RegenerateOptions extends BuildOptions {
     currentSource: string;
     failingInput: GeneratorInput;
@@ -27,6 +34,8 @@ export interface RegenerateOptions extends BuildOptions {
 export declare class BuildFailed extends Error {
     readonly operation: Operation;
     readonly diagnostics: readonly string[];
+    /** the build report on disk, filled in by whoever was writing one */
+    dump?: string;
     constructor(operation: Operation, diagnostics: readonly string[]);
 }
 /**

package/dist/generate.js

@@ -3,9 +3,18 @@ import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
 import { instruction, regenerationInstruction, retry, SYSTEM, } from "./prompt.js";
 import { called } from "./spec.js";
 import { describeIssues, issues } from "./validate.js";
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export const DEFAULT_ATTEMPTS = 5;
 export class BuildFailed extends Error {
     operation;
     diagnostics;
+    /** the build report on disk, filled in by whoever was writing one */
+    dump;
     constructor(operation, diagnostics) {
         super(`could not write a generator for ${operation.method.toUpperCase()} ${called(operation)}`);
         this.name = 'BuildFailed';
@@ -41,7 +50,7 @@ export function reason(err) {
     return parts.join(' — ') || String(err);
 }
 export async function build(operation, opts) {
-    const limit = Math.max(1, opts.attempts ?? 3);
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
     const probes = probesFor(operation);
     const response = opts.checks.for(operation).response;
     const messages = [
@@ -66,13 +75,13 @@ export async function build(operation, opts) {
                 return { source, attempts: attempt };
             }
         }
-        opts.onAttempt?.(attempt, last);
+        await opts.onAttempt?.(attempt, last, source, limit);
         messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
     }
     throw new BuildFailed(operation, last);
 }
 export async function regenerate(operation, opts) {
-    const limit = Math.max(1, opts.attempts ?? 3);
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
     const exampleInputs = opts.examples?.map((e) => e.input) ?? [];
     const probes = [opts.failingInput, ...exampleInputs, ...probesFor(operation)];
     const response = opts.checks.for(operation).response;
@@ -113,7 +122,7 @@ export async function regenerate(operation, opts) {
                 return { source, attempts: attempt };
             }
         }
-        opts.onAttempt?.(attempt, last);
+        await opts.onAttempt?.(attempt, last, source, limit);
         messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
     }
     throw new BuildFailed(operation, last);

package/dist/logger.d.ts

@@ -20,6 +20,8 @@ export interface RequestDumpData {
     errorKind?: ErrorKind;
     errorMessage?: string;
     stderr?: string;
+    /** the build report, when the answer was "there is no generator" */
+    buildDump?: string;
     cacheStatus?: 'hit' | 'miss' | 'regenerated';
     regenerated?: boolean;
     regenAttempts?: number;
@@ -37,6 +39,29 @@ export declare function colorForErrorKind(kind: ErrorKind): (s: string) => strin
  * Returns the absolute path of the generated markdown file.
  */
 export declare function saveRequestDump(dir: string, data: RequestDumpData): Promise<string>;
+export interface BuildAttempt {
+    attempt: number;
+    at: Date;
+    diagnostics: readonly string[];
+    source: string;
+}
+export interface BuildDumpData {
+    started: Date;
+    operationId?: string;
+    method: string;
+    path: string;
+    /** the operation's cache key, which is also its directory in the box */
+    key: string;
+    limit: number;
+    /** rewriting a generator that already existed rather than writing the first */
+    regeneration?: boolean;
+    model?: string;
+    attempts: readonly BuildAttempt[];
+    /** the attempts ran out — no generator was produced */
+    gaveUp?: boolean;
+}
+export declare function saveBuildDump(dir: string, data: BuildDumpData): Promise<string>;
+export declare function formatDumpPath(label: string, path: string): string;
 export declare function formatLogLine(data: RequestDumpData, dumpPath: string): string;
 export declare function formatRegenLimitHit(urlPath: string, limit: number, operationId?: string): string;
 export declare function formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string): string;

package/dist/logger.js

@@ -102,6 +102,9 @@ export async function saveRequestDump(dir, data) {
     if (data.note) {
         lines.push(`- **Note**: ${data.note}`);
     }
+    if (data.buildDump) {
+        lines.push(`- **Build report**: [${data.buildDump}](file://${data.buildDump})`);
+    }
     lines.push('', '---', '', '## Request Info', '');
     lines.push('### URL & Method', '```http', `${data.method.toUpperCase()} ${data.url}`, '```', '');
     lines.push('### Path Parameters');
@@ -176,6 +179,38 @@ export async function saveRequestDump(dir, data) {
     await writeFile(fullPath, lines.join('\n'), 'utf8');
     return resolve(fullPath);
 }
+export async function saveBuildDump(dir, data) {
+    mkdirSync(dir, { recursive: true });
+    const safePath = data.path.replace(/[^a-zA-Z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'root';
+    const isoPrefix = data.started.toISOString().replace(/[:.]/g, '-');
+    const what = data.regeneration ? 'regen' : 'build';
+    const fullPath = join(dir, `${isoPrefix}-${what}-${data.method.toUpperCase()}-${safePath}.md`);
+    const outcome = data.gaveUp
+        ? `gave up after ${data.attempts.length} of ${data.limit}`
+        : `attempt ${data.attempts.length} of ${data.limit} rejected`;
+    const lines = [
+        `# ${data.regeneration ? 'Regeneration' : 'Build'}: ` +
+            `${data.method.toUpperCase()} ${data.path}`,
+        '',
+        `- **Operation ID**: ${data.operationId ? `\`${data.operationId}\`` : '_None_'}`,
+        `- **Key**: \`${data.key}\``,
+        `- **Started**: ${data.started.toISOString()}`,
+        `- **Model**: ${data.model ? `\`${data.model}\`` : '_Unknown_'}`,
+        `- **Outcome**: ${outcome}`,
+        '',
+    ];
+    for (const a of data.attempts) {
+        const elapsed = Math.max(0, a.at.getTime() - data.started.getTime());
+        lines.push('---', '', `## Attempt ${a.attempt} of ${data.limit}`, '', `_Rejected ${a.at.toISOString()}, ${elapsed}ms into the build._`, '', '### Why it was rejected', '', ...(a.diagnostics.length > 0
+            ? a.diagnostics.map((d) => (d.trimStart().startsWith('-') ? d : `- ${d}`))
+            : ['_No diagnostics._']), '', '### Generator', '', '```python', a.source, '```', '');
+    }
+    await writeFile(fullPath, lines.join('\n'), 'utf8');
+    return resolve(fullPath);
+}
+export function formatDumpPath(label, path) {
+    return `  ${dim(`↳ ${label}:`)} ${cyan(`file://${resolve(path)}`)}`;
+}
 // ---------------------------------------------------------------------------
 // Log Line Formatter
 // ---------------------------------------------------------------------------
@@ -206,6 +241,9 @@ export function formatLogLine(data, dumpPath) {
         const fileUrl = `file://${resolve(dumpPath)}`;
         lines.push(`  ${dim('↳ dump:')} ${cyan(fileUrl)}`);
     }
+    if (data.buildDump) {
+        lines.push(formatDumpPath('build', data.buildDump));
+    }
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------

package/dist/probe.js

@@ -12,13 +12,25 @@ import { propertyNames } from "./schema.js";
 // schema allows — a generator that hard-codes the first probe's id passes once
 // and fails the second, which is the mistake this catches.
 // ---------------------------------------------------------------------------
+/**
+ * How many items a probe asks a paged operation for.
+ *
+ * Not the schema's maximum. `bounded` below answers an unbounded want with
+ * `maximum - 1`, so a `page_size` declared `maximum: 1000` used to make every
+ * probe ask for 999 fabricated objects — minutes of Faker inside a container
+ * with a 30s budget, reported as "the file took longer than 30s" and blamed on
+ * a generator that was doing exactly what it was told. A page is judged on its
+ * shape, and three rows show it.
+ */
+const PROBE_PAGE_SIZE = 3;
 export function probesFor(operation) {
+    const size = operation.paging?.size;
     return [0, 1].map((variant) => ({
         operationId: operation.operationId,
         method: operation.method,
         path: operation.path,
-        pathParams: values(operation.params, 'path', variant),
-        query: values(operation.params, 'query', variant),
+        pathParams: values(operation.params, 'path', variant, size),
+        query: values(operation.params, 'query', variant, size),
         headers: {},
         body: operation.requestBody
             ? sample(operation.requestBody.schema, variant, 0, operation.requestBody.schema)
@@ -26,7 +38,7 @@ export function probesFor(operation) {
         seed: variant === 0 ? 1 : 2,
     }));
 }
-function values(params, where, variant) {
+function values(params, where, variant, size) {
     const out = {};
     for (const p of params) {
         if (p.in !== where) {
@@ -37,7 +49,10 @@ function values(params, where, variant) {
         if (!p.required && variant === 1) {
             continue;
         }
-        out[p.name] = sample(p.schema, variant, 0, p.schema);
+        out[p.name] =
+            p.name === size
+                ? bounded(p.schema, PROBE_PAGE_SIZE, true)
+                : sample(p.schema, variant, 0, p.schema);
     }
     return out;
 }

package/dist/server.js

@@ -94,6 +94,7 @@ async function handle(req, res, opts) {
             errorKind: meta.errorKind,
             errorMessage: meta.errorMessage,
             stderr: meta.stderr,
+            buildDump: meta.buildDump,
             cacheStatus: meta.cacheStatus,
             regenerated: meta.regenerated,
             regenAttempts: meta.regenAttempts,
@@ -245,6 +246,7 @@ async function handle(req, res, opts) {
             error: `no generator for ${operation.operationId}`,
             detail,
             diagnostics: err instanceof BuildFailed ? err.diagnostics : undefined,
+            report: err instanceof BuildFailed ? err.dump : undefined,
         };
         const end = prepareSend(res, status, bodyObj);
         await finish(status, {
@@ -254,6 +256,7 @@ async function handle(req, res, opts) {
             requestBody: body,
             errorKind: 'GENERATOR_BUILD_FAILED',
             errorMessage: `no generator: ${detail}`,
+            buildDump: err instanceof BuildFailed ? err.dump : undefined,
             responseBody: bodyObj,
             note: `no generator: ${detail}`,
         });

package/dist/spec.js

@@ -97,7 +97,7 @@ function join(prefix, template) {
 /** The path as it has to be called — what a person needs to see. */
 export const called = (op) => op.fixed ? `${op.path}?${new URLSearchParams(op.fixed).toString()}` : op.path;
 /**
- * A path template has no query string, but VMware, Oracle and others write one
+ * A path template has no query string, but some vendors write one
  * anyway — `/x/{id}?action=retry` — because they need two `post`s under one
  * path and the object model gives them one. Taken verbatim the key matches
  * nothing, since a request path never contains a `?`. So it is read for what

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/faker",
-    "version": "1.1.23",
+    "version": "1.1.24",
     "description": "Mock HTTP server for swagger/OpenAPI documents, with response bodies generated by a model.",
     "keywords": [
         "openapi",
@@ -45,7 +45,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
-        "@zenera/cli": "^1.1.23",
-        "@zenera/neo": "^1.1.23"
+        "@zenera/cli": "^1.1.24",
+        "@zenera/neo": "^1.1.24"
     }
 }