@zenera/faker 1.1.0

package/dist/prompt.js

@@ -0,0 +1,98 @@
+import { AVAILABLE } from "./image.js";
+// ---------------------------------------------------------------------------
+// What the model is told
+//
+// A contract, not a request. The generator is a program with a fixed calling
+// convention that this package depends on in three places — the entry point,
+// the input shape, the output file — so those are stated as rules rather than
+// as suggestions, and everything discretionary is stated as taste.
+//
+// The one rule worth its own paragraph is the echo: a mock that answers
+// `GET /users/12324` with somebody else's id is worse than useless, because it
+// validates and quietly breaks whatever is being developed against it.
+// ---------------------------------------------------------------------------
+export const SYSTEM = [
+    'You write one Python 3 file that fabricates a plausible HTTP response body.',
+    '',
+    'CALLING CONVENTION',
+    '- `sys.argv[1]` is a path to a JSON file to read; `sys.argv[2]` is a path to write to.',
+    '- Write exactly one JSON document to `sys.argv[2]` and print nothing to stdout.',
+    '- Exit non-zero with a message on stderr if you cannot produce a valid body.',
+    '',
+    'THE INPUT FILE holds:',
+    '  operationId, method, path, pathParams, query, headers, body, seed',
+    '',
+    'ENVIRONMENT',
+    `- These libraries are installed: ${AVAILABLE.join(', ')}, plus the standard library.`,
+    '- There is no network and no pip. Importing anything else fails the file.',
+    '- Seed both `random.seed(seed)` and `Faker.seed(seed)` from the input, first thing.',
+    '',
+    'RULES',
+    '1. The output must validate against the response schema given below. Build the',
+    '   object, then check it with `jsonschema.validate` before writing, and fix it',
+    '   rather than emitting something that fails.',
+    '2. Echo the request. Where a path parameter has the same name as a property',
+    "   in the response schema, that property must carry the request's value,",
+    '   converted to the type the schema declares. `GET /users/{user_id}` called',
+    '   with `user_id=12324` answers with `user_id` 12324, not a random one. Do',
+    '   this generically, by looking the names up at run time. Do the same for a',
+    '   query parameter where it plainly describes the content rather than',
+    '   controlling the call.',
+    '3. Every required property must be present. Optional ones may be omitted',
+    '   sometimes; that is what makes a mock useful.',
+    '4. Values must suit their names, not just their types. Use `faker` for anything',
+    '   a person would recognise — names, emails, addresses, companies, phone',
+    '   numbers, sentences. Use `exrex.getone(pattern)` when a string schema has a',
+    '   `pattern`. Respect `enum`, `format`, `minimum`, `maxLength` and friends.',
+    '5. Arrays get 1 to 5 items unless the schema says otherwise.',
+    '6. The file is run once per request and must be deterministic for a given seed.',
+    '',
+    'ANSWER WITH THE FILE AND NOTHING ELSE. No explanation, no markdown fence.',
+].join('\n');
+export function brief(operation) {
+    const lines = [
+        `OPERATION  ${operation.method.toUpperCase()} ${operation.path}`,
+        `operationId: ${operation.operationId}`,
+    ];
+    if (operation.summary) {
+        lines.push(`summary: ${operation.summary}`);
+    }
+    if (operation.description && operation.description !== operation.summary) {
+        lines.push(`description: ${operation.description.slice(0, 600)}`);
+    }
+    lines.push('', 'PARAMETERS');
+    if (operation.params.length === 0) {
+        lines.push('  (none)');
+    }
+    for (const p of operation.params) {
+        const note = p.description ? `  # ${p.description.split('\n')[0].slice(0, 100)}` : '';
+        lines.push(`  ${p.name} (in ${p.in}${p.required ? ', required' : ''}): ${JSON.stringify(p.schema)}${note}`);
+    }
+    if (operation.requestBody) {
+        lines.push('', 'REQUEST BODY SCHEMA (arrives as `body`)', json(operation.requestBody.schema));
+    }
+    lines.push('', `RESPONSE SCHEMA (status ${operation.success.status})`);
+    lines.push(operation.success.schema ? json(operation.success.schema) : '  (no body)');
+    return lines.join('\n');
+}
+/**
+ * Repeated in the file the model writes, so it is worth spelling out: the
+ * schema it validates against must be the one it was shown, embedded, not
+ * loaded from anywhere.
+ */
+export function instruction(operation) {
+    return [
+        brief(operation),
+        '',
+        'Embed the response schema in the file as a literal and validate against it.',
+    ].join('\n');
+}
+export function retry(diagnostics) {
+    return [
+        'That file did not pass. Fix it and answer with the whole file again.',
+        '',
+        ...diagnostics,
+    ].join('\n');
+}
+const json = (value) => JSON.stringify(value, null, 1);
+//# sourceMappingURL=prompt.js.map

package/dist/router.d.ts

@@ -0,0 +1,14 @@
+import { type Method, type Operation } from './spec.ts';
+export interface Match {
+    operation: Operation;
+    pathParams: Record<string, string>;
+}
+export declare class Router {
+    #private;
+    readonly operations: readonly Operation[];
+    constructor(operations: readonly Operation[]);
+    match(method: string, pathname: string): Match | undefined;
+    /** Whether the path exists under some other method — a 405, not a 404. */
+    allowed(pathname: string): Method[];
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.js

@@ -0,0 +1,83 @@
+import { SpecError } from "./spec.js";
+export class Router {
+    #routes = new Map();
+    operations;
+    constructor(operations) {
+        this.operations = operations;
+        const seen = new Map();
+        for (const operation of operations) {
+            const id = `${operation.method} ${operation.path}`;
+            const clash = seen.get(id);
+            if (clash) {
+                throw new SpecError(`${id} is declared twice`, `${clash.source} and ${operation.source} both define it`);
+            }
+            seen.set(id, operation);
+            const segments = compile(operation.path);
+            const list = this.#routes.get(operation.method) ?? [];
+            list.push({
+                operation,
+                segments,
+                specificity: segments.filter((s) => s.name === undefined).length,
+            });
+            this.#routes.set(operation.method, list);
+        }
+        for (const list of this.#routes.values()) {
+            list.sort((a, b) => b.specificity - a.specificity);
+        }
+    }
+    match(method, pathname) {
+        const parts = split(pathname);
+        for (const route of this.#routes.get(method.toLowerCase()) ?? []) {
+            const pathParams = apply(route.segments, parts);
+            if (pathParams) {
+                return { operation: route.operation, pathParams };
+            }
+        }
+        return undefined;
+    }
+    /** Whether the path exists under some other method — a 405, not a 404. */
+    allowed(pathname) {
+        const parts = split(pathname);
+        const out = [];
+        for (const [method, list] of this.#routes) {
+            if (list.some((r) => apply(r.segments, parts) !== undefined)) {
+                out.push(method);
+            }
+        }
+        return out;
+    }
+}
+function compile(template) {
+    return split(template).map((raw) => {
+        const m = /^\{(.+)\}$/.exec(raw);
+        return m ? { name: m[1] } : { literal: decode(raw) };
+    });
+}
+const split = (path) => path.split('/').filter((s) => s.length > 0);
+function apply(segments, parts) {
+    if (segments.length !== parts.length) {
+        return undefined;
+    }
+    const out = {};
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment.name === undefined) {
+            if (segment.literal !== decode(parts[i])) {
+                return undefined;
+            }
+            continue;
+        }
+        out[segment.name] = decode(parts[i]);
+    }
+    return out;
+}
+/** A malformed escape is the client's problem; take the segment verbatim. */
+function decode(part) {
+    try {
+        return decodeURIComponent(part);
+    }
+    catch {
+        return part;
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/schema.d.ts

@@ -0,0 +1,8 @@
+export type Schema = Record<string, unknown>;
+export type Dialect = 'swagger-2.0' | 'openapi-3.0' | 'openapi-3.1';
+/**
+ * Converts a dereferenced schema into 2020-12, hoisting anything reached more
+ * than once into `$defs`. The result is acyclic and safe to stringify.
+ */
+export declare function normalize(root: unknown, dialect: Dialect): Schema;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -0,0 +1,221 @@
+// ---------------------------------------------------------------------------
+// Schemas, made uniform
+//
+// Three dialects arrive here and one leaves. Swagger 2.0 carries Draft-4,
+// OpenAPI 3.0 carries a Draft-4 derivative with its own `nullable`, and
+// OpenAPI 3.1 is honest 2020-12. Ajv can be asked to speak any of them, but
+// then every consumer downstream — the request check, the response check, the
+// prompt the model reads, the `jsonschema` call inside the generator — has to
+// be told which one it is looking at. So they are converted once, here, into
+// 2020-12, and nothing below this file knows a dialect exists.
+//
+// The other job is cycles. `dereference` replaces every `$ref` with the object
+// it pointed at, so a self-referencing schema comes back as a *cyclic JS
+// object* — which Ajv cannot compile and `JSON.stringify` cannot print. Any
+// node reached more than once is therefore hoisted into `$defs` and referred to
+// by `$ref`, which restores the recursion in the one form every tool here can
+// read. Shared-but-acyclic components take the same route, and the schema the
+// model is shown gets smaller for free.
+// ---------------------------------------------------------------------------
+/** Subschema positions, by the shape of what sits in them. */
+const ONE = [
+    'not',
+    'if',
+    'then',
+    'else',
+    'contains',
+    'propertyNames',
+    'additionalProperties',
+    'unevaluatedProperties',
+    'additionalItems',
+    'unevaluatedItems',
+];
+const MAP = ['properties', 'patternProperties', '$defs', 'definitions'];
+const LIST = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
+/** Annotations that mean nothing to a validator and cost prompt tokens. */
+const DROP = new Set([
+    'example',
+    'externalDocs',
+    'xml',
+    'discriminator',
+    'deprecated',
+    'x-internal',
+]);
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Converts a dereferenced schema into 2020-12, hoisting anything reached more
+ * than once into `$defs`. The result is acyclic and safe to stringify.
+ */
+export function normalize(root, dialect) {
+    if (!isObject(root)) {
+        return {};
+    }
+    const shared = repeated(root);
+    const defs = new Map();
+    const bodies = new Map();
+    const walk = (node) => {
+        if (!isObject(node)) {
+            return node;
+        }
+        const name = defs.get(node);
+        if (name !== undefined) {
+            return { $ref: `#/$defs/${name}` };
+        }
+        if (!shared.has(node)) {
+            return convert(node, dialect, walk);
+        }
+        const id = `def${defs.size}`;
+        // Registered *before* the body is built, so a node that contains
+        // itself refers to the name rather than recursing forever.
+        defs.set(node, id);
+        bodies.set(id, convert(node, dialect, walk));
+        return { $ref: `#/$defs/${id}` };
+    };
+    // A root that is itself recursive comes back as a bare `$ref`; 2020-12
+    // allows siblings on one, so `$defs` and `$schema` still land here.
+    const out = walk(root);
+    if (bodies.size > 0) {
+        out.$defs = Object.fromEntries(bodies);
+    }
+    out.$schema = 'https://json-schema.org/draft/2020-12/schema';
+    return out;
+}
+function convert(node, dialect, walk) {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (DROP.has(key) || value === undefined) {
+            continue;
+        }
+        if (ONE.includes(key)) {
+            out[key] = typeof value === 'boolean' ? value : walk(value);
+        }
+        else if (MAP.includes(key) && isObject(value)) {
+            const target = key === 'definitions' ? '$defs' : key;
+            out[target] = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, typeof v === 'boolean' ? v : walk(v)]));
+        }
+        else if (LIST.includes(key) && Array.isArray(value)) {
+            out[key] = value.map(walk);
+        }
+        else if (key === 'items') {
+            // Draft-4 and Swagger 2.0 spell tuples as an array here; 2020-12
+            // spells them `prefixItems` and keeps `items` for the tail.
+            out[Array.isArray(value) ? 'prefixItems' : 'items'] = Array.isArray(value)
+                ? value.map(walk)
+                : walk(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    if (dialect !== 'openapi-3.1') {
+        widenNullable(node, out);
+        fixExclusive(out);
+    }
+    fixPattern(out);
+    // `type: file` is Swagger 2.0's way of saying "bytes".
+    if (out.type === 'file') {
+        out.type = 'string';
+    }
+    if (Array.isArray(out.required) && out.required.length === 0) {
+        delete out.required;
+    }
+    return out;
+}
+/**
+ * `pattern: /^[_a-z0-9-]+$/` — a JavaScript regex *literal*, delimiters and all
+ * — is written in real documents. JSON Schema wants the body alone, and with
+ * the slashes left on, the expression is unsatisfiable: no string both contains
+ * a slash and begins after it. Left alone it makes the endpoint impossible to
+ * answer rather than merely badly specified, so the delimiters come off, and a
+ * pattern that still will not compile is dropped instead of enforced.
+ */
+function fixPattern(out) {
+    const raw = out.pattern;
+    if (typeof raw !== 'string') {
+        return;
+    }
+    const literal = /^\/(.+)\/[dgimsuvy]*$/s.exec(raw);
+    const body = literal ? literal[1] : raw;
+    try {
+        new RegExp(body);
+        out.pattern = body;
+    }
+    catch {
+        delete out.pattern;
+    }
+}
+/** `nullable: true` is not a 2020-12 keyword; a union type is. */
+function widenNullable(node, out) {
+    if (node.nullable !== true) {
+        return;
+    }
+    delete out.nullable;
+    const type = out.type;
+    if (typeof type === 'string') {
+        out.type = [type, 'null'];
+    }
+    else if (Array.isArray(type)) {
+        out.type = type.includes('null') ? type : [...type, 'null'];
+    }
+    else if (Array.isArray(out.enum) && !out.enum.includes(null)) {
+        out.enum = [...out.enum, null];
+    }
+}
+/**
+ * Draft-4 spells an exclusive bound as a boolean flag on the inclusive one.
+ * Left alone, Ajv reads `exclusiveMinimum: true` as "the minimum is 1".
+ */
+function fixExclusive(out) {
+    for (const [flag, bound] of [
+        ['exclusiveMinimum', 'minimum'],
+        ['exclusiveMaximum', 'maximum'],
+    ]) {
+        if (typeof out[flag] !== 'boolean') {
+            continue;
+        }
+        const value = out[bound];
+        if (out[flag] === true && typeof value === 'number') {
+            out[flag] = value;
+            delete out[bound];
+        }
+        else {
+            delete out[flag];
+        }
+    }
+}
+/** Every schema-position object reached by more than one path, or by itself. */
+function repeated(root) {
+    const seen = new Set();
+    const twice = new Set();
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!isObject(node)) {
+            continue;
+        }
+        if (seen.has(node)) {
+            twice.add(node);
+            continue;
+        }
+        seen.add(node);
+        for (const key of ONE) {
+            stack.push(node[key]);
+        }
+        for (const key of LIST) {
+            const value = node[key];
+            if (Array.isArray(value)) {
+                stack.push(...value);
+            }
+        }
+        for (const key of MAP) {
+            const value = node[key];
+            if (isObject(value)) {
+                stack.push(...Object.values(value));
+            }
+        }
+        const items = node.items;
+        stack.push(...(Array.isArray(items) ? items : [items]));
+    }
+    return twice;
+}
+//# sourceMappingURL=schema.js.map

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from 'node:http';
+import type { Box } from './box.ts';
+import { type Cache } from './cache.ts';
+import type { Router } from './router.ts';
+import { type Checks } from './validate.ts';
+export interface ServerOptions {
+    router: Router;
+    cache: Cache;
+    checks: Checks;
+    box: Box;
+    /** fixed base seed — the same request then answers the same way */
+    seed?: number;
+    maxBody?: number;
+    onRequest?: (line: string) => void;
+}
+export interface Listening {
+    server: Server;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function build(opts: ServerOptions): Server;
+export declare function listen(opts: ServerOptions, host: string, port: number): Promise<Listening>;
+//# sourceMappingURL=server.d.ts.map