@vxnsin/inkan 0.0.0-stage → 0.1.0

package/dist/app.js

@@ -0,0 +1,487 @@
+import { createServer } from "node:http";
+import { HttpProblem, problem } from "./problem.js";
+import { Router } from "./router.js";
+import { t } from "./schema.js";
+import { buildOpenAPI } from "./openapi.js";
+import { docsPage, inspectorPage } from "./pages.js";
+import { runChecks } from "./check.js";
+export class Reply {
+    status;
+    body;
+    headers;
+    constructor(status, body, headers = {}) {
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+    }
+}
+/** Answers with a status that is not the default one, or with extra headers. */
+export const reply = (status, body, headers) => new Reply(status, body, headers);
+// ---------- route tables ----------
+const joinPath = (a, b) => "/" + [a, b].join("/").split("/").filter(Boolean).join("/");
+/** A set of routes that can be mounted under a prefix. */
+export class Routes {
+    /** @internal */
+    _records = [];
+    /** @internal */
+    _use = [];
+    /** For a group, middleware that every route in it gets. Add it before mounting. */
+    use(...mw) {
+        this._use.push(...mw);
+        return this;
+    }
+    define(method, path, a, b) {
+        const [spec, handler] = typeof a === "function" ? [{}, a] : [a, b];
+        const s = spec;
+        this.add({ method, path, spec: s, handler: handler, use: s.use ?? [] });
+        return this;
+    }
+    /** @internal */
+    add(r) {
+        this._records.push({ ...r, use: [...this._use, ...r.use] });
+    }
+    get = ((p, a, b) => this.define("GET", p, a, b));
+    post = ((p, a, b) => this.define("POST", p, a, b));
+    put = ((p, a, b) => this.define("PUT", p, a, b));
+    patch = ((p, a, b) => this.define("PATCH", p, a, b));
+    delete = ((p, a, b) => this.define("DELETE", p, a, b));
+    mount(prefix, group) {
+        for (const r of group._records)
+            this.add({ ...r, path: joinPath(prefix, r.path) });
+        return this;
+    }
+}
+export const routes = () => new Routes();
+const REDACT = new Set(["authorization", "cookie", "set-cookie", "proxy-authorization", "x-api-key"]);
+const clip = (s, n = 4096) => (s.length > n ? s.slice(0, n) + `… (${s.length - n} more)` : s);
+const isLoopback = (addr) => !addr || addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
+export class App extends Routes {
+    options;
+    dev;
+    router = new Router();
+    global = [];
+    log = [];
+    logId = 0;
+    spec;
+    constructor(options = {}) {
+        super();
+        this.dev = options.dev ?? process.env.NODE_ENV !== "production";
+        this.options = {
+            docs: "/docs",
+            openapi: "/openapi.json",
+            inspector: this.dev ? "/_inkan" : false,
+            validateResponses: this.dev,
+            bodyLimit: 1024 * 1024,
+            log: this.dev,
+            gracefulShutdown: true,
+            ...options,
+        };
+    }
+    /** Middleware for every request, before routing. */
+    use(...mw) {
+        this.global.push(...mw);
+        return this;
+    }
+    /** @internal */
+    add(r) {
+        this.router.add(r.method, r.path, r);
+        this._records.push(r);
+        this.spec = undefined;
+    }
+    routes() {
+        return [...this._records];
+    }
+    openapi() {
+        return (this.spec ??= buildOpenAPI(this._records, this.options));
+    }
+    /** Runs every route's examples against the app, without a socket. */
+    check(opts) {
+        return runChecks(this, opts);
+    }
+    /** Sends a request straight into the app. Good for tests: no port, no network. */
+    async inject(opts) {
+        const headers = {};
+        for (const [k, v] of Object.entries(opts.headers ?? {}))
+            headers[k.toLowerCase()] = v;
+        let body;
+        if (opts.body !== undefined) {
+            if (Buffer.isBuffer(opts.body))
+                body = opts.body;
+            else if (typeof opts.body === "string")
+                body = Buffer.from(opts.body);
+            else {
+                body = Buffer.from(JSON.stringify(opts.body));
+                headers["content-type"] ??= "application/json";
+            }
+        }
+        const res = await this.handle({ method: (opts.method ?? "GET").toUpperCase(), url: opts.url, headers, body });
+        const text = res.body === undefined ? "" : res.body.toString();
+        const json = /json/.test(res.headers["content-type"] ?? "");
+        return { status: res.status, headers: res.headers, text, body: json && text ? JSON.parse(text) : text };
+    }
+    // ----- the request path -----
+    /** @internal */
+    async handle(raw) {
+        const started = performance.now();
+        const url = new URL(raw.url, "http://inkan.local");
+        const own = this.builtin(raw, url);
+        if (own)
+            return own;
+        const headers = {};
+        for (const [k, v] of Object.entries(raw.headers)) {
+            if (v !== undefined)
+                headers[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : v;
+        }
+        const out = { status: 0, headers: {} };
+        const notes = [];
+        let result;
+        const ctx = {
+            method: raw.method,
+            path: url.pathname,
+            url,
+            params: {},
+            query: queryObject(url.searchParams),
+            headers,
+            body: undefined,
+            state: {},
+            status: (code) => void (out.status = code),
+            header: (name, value) => void (out.headers[name.toLowerCase()] = value),
+            reply: (status, body, h) => new Reply(status, body, h),
+            req: raw.req,
+            res: raw.res,
+        };
+        let route;
+        const dispatch = async () => {
+            const m = this.router.match(raw.method, url.pathname);
+            if (m.kind === "none")
+                throw problem(404, "not-found", `No route for ${raw.method} ${url.pathname}`);
+            if (m.kind === "method") {
+                const p = problem(405, "method-not-allowed", `${url.pathname} does not take ${raw.method}`);
+                p.headers.allow = m.allow.join(", ");
+                throw p;
+            }
+            const r = m.route;
+            route = r;
+            ctx.route = { method: r.method, path: r.path };
+            validateInput(ctx, r, m.params, raw);
+            await compose(r.use, async () => {
+                result = await r.handler(ctx);
+            })(ctx);
+        };
+        let res;
+        try {
+            await compose(this.global, dispatch)(ctx);
+            res = this.respond(result, out, route, notes);
+        }
+        catch (err) {
+            res = this.fail(err, ctx, url.pathname, notes);
+        }
+        if (raw.method === "HEAD")
+            res.body = undefined;
+        const ms = Math.round((performance.now() - started) * 10) / 10;
+        if (this.options.log) {
+            const flag = notes.length ? `  ! ${notes.join("; ")}` : "";
+            console.log(`  ${raw.method.padEnd(6)} ${url.pathname}${url.search}  ${res.status}  ${ms}ms${flag}`);
+        }
+        if (this.options.inspector)
+            this.remember(raw, url, res, route, ms, notes, headers);
+        return res;
+    }
+    respond(result, out, route, notes) {
+        const responses = route?.spec.response ?? {};
+        let status = out.status;
+        let body = result;
+        let headers = { ...out.headers };
+        if (result instanceof Reply) {
+            status = result.status;
+            body = result.body;
+            headers = { ...headers, ...lower(result.headers) };
+        }
+        if (!status) {
+            // No body means 204. Otherwise the first 2xx the contract lists, or 200.
+            const declared = Object.keys(responses).map(Number).filter((s) => s >= 200 && s < 300 && s !== 204).sort();
+            status = body === undefined ? 204 : (declared[0] ?? 200);
+        }
+        if (route && Object.keys(responses).length && status !== 204) {
+            const schema = contractFor(route, status);
+            if (!schema)
+                notes.push(`status ${status} is not in the contract`);
+            else if (this.options.validateResponses) {
+                const r = schema.safeParse(body);
+                if (!r.ok) {
+                    notes.push("response broke the contract");
+                    const lines = r.issues.map((i) => `${i.path || "(body)"} ${i.message}`).join("\n  ");
+                    console.error(`inkan: ${route.method} ${route.path} answered ${status} with a body that breaks its contract:\n  ${lines}`);
+                    throw problem(500, "response-contract", "The handler answered with a body that does not match its contract", {
+                        errors: r.issues.map((i) => ({ in: "response", path: i.path, message: i.message })),
+                    });
+                }
+                body = r.value; // this also drops keys the contract does not list, so nothing leaks by accident
+            }
+        }
+        return encode(status, body, headers);
+    }
+    fail(err, ctx, path, notes) {
+        let p;
+        if (err instanceof HttpProblem)
+            p = err;
+        else {
+            if (this.options.onError)
+                this.options.onError(err, ctx);
+            else
+                console.error(err);
+            const detail = this.dev && err instanceof Error ? err.message : "Something went wrong on our side";
+            p = problem(500, "internal", detail);
+        }
+        if (p.type === "validation")
+            notes.push("input broke the contract");
+        const body = { ...p.toJSON(), instance: path };
+        return {
+            status: p.status,
+            headers: { "content-type": "application/problem+json", ...lower(p.headers) },
+            body: JSON.stringify(body),
+        };
+    }
+    builtin(raw, url) {
+        if (raw.method !== "GET" && raw.method !== "HEAD")
+            return;
+        const { docs, openapi, inspector } = this.options;
+        const p = url.pathname;
+        if (openapi && p === openapi)
+            return encode(200, this.openapi(), {});
+        if (docs && (p === docs || p === docs + "/")) {
+            const page = docsPage({ title: this.options.title ?? "API", specUrl: openapi || "", inspector: inspector || "" });
+            return encode(200, page, {
+                "content-type": "text/html; charset=utf-8",
+            });
+        }
+        if (inspector && (p === inspector || p.startsWith(inspector + "/"))) {
+            if (!isLoopback(raw.remote))
+                return; // a plain 404 for everybody else
+            if (p === inspector + "/log.json") {
+                const since = Number(url.searchParams.get("since") ?? 0);
+                return encode(200, this.log.filter((e) => e.id > since), { "cache-control": "no-store" });
+            }
+            return encode(200, inspectorPage({ title: this.options.title ?? "API", base: inspector, docs: docs || "" }), {
+                "content-type": "text/html; charset=utf-8",
+            });
+        }
+    }
+    remember(raw, url, res, route, ms, notes, headers) {
+        const shown = {};
+        for (const [k, v] of Object.entries(headers))
+            shown[k] = REDACT.has(k) ? "•••" : v;
+        this.log.push({
+            id: ++this.logId,
+            at: new Date().toISOString(),
+            method: raw.method,
+            path: url.pathname + url.search,
+            route: route?.path,
+            status: res.status,
+            ms,
+            notes,
+            request: { headers: shown, body: raw.body?.length ? clip(raw.body.toString()) : undefined },
+            response: { body: res.body === undefined ? undefined : clip(res.body.toString()) },
+        });
+        if (this.log.length > 200)
+            this.log.shift();
+    }
+    // ----- the socket -----
+    /** A plain Node request listener, for `http.createServer` or anything that takes one. */
+    get listener() {
+        return (req, res) => void this.serve(req, res);
+    }
+    async serve(req, res) {
+        const limit = this.options.bodyLimit;
+        const chunks = [];
+        let size = 0;
+        let tooLarge = Number(req.headers["content-length"] ?? 0) > limit;
+        if (!tooLarge && req.method !== "GET" && req.method !== "HEAD") {
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > limit) {
+                    tooLarge = true;
+                    break;
+                }
+                chunks.push(chunk);
+            }
+        }
+        let out;
+        if (tooLarge) {
+            const p = problem(413, "body-too-large", `Request bodies may be at most ${limit} bytes`);
+            out = {
+                status: 413,
+                headers: { "content-type": "application/problem+json", connection: "close" },
+                body: JSON.stringify({ ...p.toJSON(), instance: req.url }),
+            };
+        }
+        else {
+            out = await this.handle({
+                method: req.method ?? "GET",
+                url: req.url ?? "/",
+                headers: req.headers,
+                body: chunks.length ? Buffer.concat(chunks) : undefined,
+                remote: req.socket.remoteAddress,
+                req,
+                res,
+            });
+        }
+        if (res.headersSent || res.writableEnded)
+            return; // a handler wrote to `res` itself
+        res.writeHead(out.status, out.headers);
+        res.end(out.body);
+    }
+    /**
+     * Starts listening. The port comes from the argument, then $PORT, then 3000,
+     * so it runs under warden, a PaaS or a container without changes.
+     */
+    listen(port, host) {
+        const server = createServer(this.listener);
+        if (process.env.INKAN_NO_LISTEN)
+            return Promise.resolve(server); // the CLI loads the app only to read it
+        const p = port ?? (process.env.PORT ? Number(process.env.PORT) : 3000);
+        const h = host ?? process.env.HOST;
+        return new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(p, h, () => {
+                server.off("error", reject);
+                if (this.options.log)
+                    this.banner(server);
+                if (this.options.gracefulShutdown)
+                    shutdownOnSignal(server);
+                resolve(server);
+            });
+        });
+    }
+    banner(server) {
+        const addr = server.address();
+        const port = typeof addr === "object" && addr ? addr.port : addr;
+        const base = `http://localhost:${port}`;
+        const n = this._records.length;
+        const ex = this._records.reduce((s, r) => s + (r.spec.examples?.length ?? 0), 0);
+        const name = [this.options.title, this.options.version].filter(Boolean).join(" ");
+        const lines = [`  印 inkan${name ? "  ·  " + name : ""}`, `  ├ ${base}`];
+        if (this.options.docs)
+            lines.push(`  ├ docs       ${base}${this.options.docs}`);
+        if (this.options.inspector)
+            lines.push(`  ├ inspector  ${base}${this.options.inspector}`);
+        lines.push(`  └ ${n} route${n === 1 ? "" : "s"}, ${ex} example${ex === 1 ? "" : "s"}`);
+        console.log("\n" + lines.join("\n") + "\n");
+    }
+}
+export const inkan = (options) => new App(options);
+/**
+ * The schema a status answers with. A route that takes input also promises
+ * a 400 problem for input that breaks the contract, without saying so.
+ */
+export function contractFor(route, status) {
+    const { spec } = route;
+    const declared = spec.response?.[status];
+    if (declared)
+        return declared;
+    if (status === 400 && (spec.params || spec.query || spec.headers || spec.body))
+        return t.problem();
+}
+// ---------- helpers ----------
+function compose(mw, last) {
+    return async (ctx) => {
+        let index = -1;
+        const run = async (i) => {
+            if (i <= index)
+                throw new Error("next() was called twice in one middleware");
+            index = i;
+            if (i === mw.length)
+                return last();
+            await mw[i](ctx, () => run(i + 1));
+        };
+        await run(0);
+    };
+}
+function queryObject(sp) {
+    const o = {};
+    for (const [k, v] of sp) {
+        const prev = o[k];
+        o[k] = prev === undefined ? v : Array.isArray(prev) ? [...prev, v] : [prev, v];
+    }
+    return o;
+}
+const lower = (h) => Object.fromEntries(Object.entries(h).map(([k, v]) => [k.toLowerCase(), v]));
+function readBody(raw, contentType) {
+    if (!raw.body?.length)
+        return { kind: "none", value: undefined };
+    const ct = contentType.split(";")[0].trim().toLowerCase();
+    const text = () => raw.body.toString("utf8");
+    if (ct === "application/json" || ct.endsWith("+json")) {
+        try {
+            return { kind: "json", value: JSON.parse(text()) };
+        }
+        catch (e) {
+            throw problem(400, "invalid-json", `The body is not valid JSON: ${e.message}`);
+        }
+    }
+    if (ct === "application/x-www-form-urlencoded")
+        return { kind: "form", value: queryObject(new URLSearchParams(text())) };
+    if (ct.startsWith("text/") || ct === "")
+        return { kind: "text", value: text() };
+    return { kind: "binary", value: raw.body };
+}
+function validateInput(ctx, route, params, raw) {
+    const { spec } = route;
+    const errors = [];
+    const take = (where, schema, value, coerce) => {
+        if (!schema)
+            return value;
+        const r = schema.safeParse(value, { coerce });
+        if (r.ok)
+            return r.value;
+        errors.push(...r.issues.map((i) => ({ in: where, path: i.path, message: i.message })));
+        return value;
+    };
+    // read before a header schema strips the headers it does not list
+    const contentType = ctx.headers["content-type"] ?? "";
+    ctx.params = take("params", spec.params, params, true);
+    ctx.query = take("query", spec.query, ctx.query, true);
+    ctx.headers = take("headers", spec.headers, ctx.headers, true);
+    const body = readBody(raw, contentType);
+    if (spec.body && (body.kind === "binary" || body.kind === "text")) {
+        throw problem(415, "unsupported-media-type", "Send the body as application/json or application/x-www-form-urlencoded");
+    }
+    ctx.body = take("body", spec.body, body.value, body.kind === "form");
+    if (errors.length) {
+        const where = [...new Set(errors.map((e) => e.in))].join(" and ");
+        throw new HttpProblem(400, "validation", `The ${where} does not match the contract`, { errors });
+    }
+}
+function encode(status, body, headers) {
+    const h = { ...headers };
+    if (body === undefined || body === null || status === 204 || status === 304) {
+        return { status, headers: h, body: undefined };
+    }
+    if (typeof body === "string") {
+        h["content-type"] ??= "text/plain; charset=utf-8";
+        return { status, headers: h, body };
+    }
+    if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+        h["content-type"] ??= "application/octet-stream";
+        return { status, headers: h, body: Buffer.from(body) };
+    }
+    h["content-type"] ??= "application/json; charset=utf-8";
+    return { status, headers: h, body: JSON.stringify(body) };
+}
+let shuttingDown = false;
+function shutdownOnSignal(server) {
+    const stop = (signal) => {
+        if (shuttingDown)
+            process.exit(1); // a second ctrl+c means now
+        shuttingDown = true;
+        console.log(`\n  ${signal}: finishing open requests…`);
+        server.close(() => process.exit(0));
+        server.closeIdleConnections();
+        setTimeout(() => {
+            server.closeAllConnections();
+            process.exit(0);
+        }, 10_000).unref();
+    };
+    process.once("SIGINT", () => stop("SIGINT"));
+    process.once("SIGTERM", () => stop("SIGTERM"));
+}

package/dist/check.d.ts

@@ -0,0 +1,28 @@
+import { type App } from "./app.ts";
+export type CheckOptions = {
+    /** Runs before every example, e.g. to reset an in-memory store. */
+    beforeEach?: () => unknown;
+    /** Only routes whose `METHOD /path` contains this text. */
+    only?: string;
+};
+export type CheckResult = {
+    method: string;
+    path: string;
+    example: string;
+    ok: boolean;
+    status: number;
+    ms: number;
+    problems: string[];
+};
+export type CheckReport = {
+    ok: boolean;
+    passed: number;
+    failed: number;
+    results: CheckResult[];
+    /** Routes without a single example: nothing holds them to their contract. */
+    unchecked: string[];
+};
+/** Is everything in `expected` also in `actual`? Returns where it is not. */
+export declare function partialMatch(expected: unknown, actual: unknown, path?: string): string | undefined;
+export declare function runChecks(app: App, opts?: CheckOptions): Promise<CheckReport>;
+export declare function formatReport(report: CheckReport, title?: string, color?: boolean): string;

package/dist/check.js

@@ -0,0 +1,166 @@
+// Every example in a route is also a test. `check` sends each one into the
+// app and holds the answer against the contract: the status, the response
+// schema and whatever the example says it `expect`s.
+import { contractFor } from "./app.js";
+function fill(path, params = {}) {
+    return path
+        .split("/")
+        .map((seg) => {
+        if (!seg.startsWith(":") && !seg.startsWith("*"))
+            return seg;
+        const name = seg.slice(1) || "rest";
+        const v = params[name];
+        if (v === undefined)
+            throw new Error(`the example has no value for ${seg}`);
+        return seg.startsWith("*") ? String(v) : encodeURIComponent(String(v));
+    })
+        .join("/");
+}
+function queryString(q = {}) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(q)) {
+        for (const x of Array.isArray(v) ? v : [v])
+            if (x !== undefined)
+                sp.append(k, String(x));
+    }
+    const s = sp.toString();
+    return s ? `?${s}` : "";
+}
+/** Is everything in `expected` also in `actual`? Returns where it is not. */
+export function partialMatch(expected, actual, path = "body") {
+    if (expected !== null && typeof expected === "object") {
+        if (Array.isArray(expected)) {
+            if (!Array.isArray(actual))
+                return `${path}: expected an array, got ${JSON.stringify(actual)}`;
+            if (expected.length !== actual.length)
+                return `${path}: expected ${expected.length} items, got ${actual.length}`;
+            for (const [i, x] of expected.entries()) {
+                const miss = partialMatch(x, actual[i], `${path}[${i}]`);
+                if (miss)
+                    return miss;
+            }
+            return;
+        }
+        if (actual === null || typeof actual !== "object")
+            return `${path}: expected an object, got ${JSON.stringify(actual)}`;
+        for (const [k, x] of Object.entries(expected)) {
+            const miss = partialMatch(x, actual[k], `${path}.${k}`);
+            if (miss)
+                return miss;
+        }
+        return;
+    }
+    if (!Object.is(expected, actual))
+        return `${path}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+}
+function expectedStatus(r, ex) {
+    if (ex.status !== undefined)
+        return ex.status;
+    const ok = Object.keys(r.spec.response ?? {}).map(Number).filter((s) => s >= 200 && s < 300).sort();
+    return ok[0];
+}
+async function runOne(app, r, ex, i) {
+    const name = ex.name ?? `example ${i + 1}`;
+    const started = performance.now();
+    const problems = [];
+    let status = 0;
+    try {
+        const res = await app.inject({
+            method: r.method,
+            url: fill(r.path, ex.params) + queryString(ex.query),
+            headers: ex.headers,
+            body: ex.body,
+        });
+        status = res.status;
+        const want = expectedStatus(r, ex);
+        if (want !== undefined ? status !== want : status >= 300) {
+            problems.push(`answered ${status}, expected ${want ?? "a 2xx"}`);
+            if (res.body?.detail)
+                problems.push(`  ${res.body.type}: ${res.body.detail}`);
+            for (const e of res.body?.errors ?? [])
+                problems.push(`  ${e.in} ${e.path || ""} ${e.message}`.replace(/\s+/g, " "));
+        }
+        else {
+            const declared = Object.keys(r.spec.response ?? {}).length > 0;
+            const schema = contractFor(r, status);
+            if (status === 204) {
+                if (res.text)
+                    problems.push("answered 204 with a body");
+            }
+            else if (schema) {
+                const v = schema.safeParse(res.body === "" ? undefined : res.body);
+                if (!v.ok)
+                    for (const issue of v.issues)
+                        problems.push(`response ${issue.path || "(body)"} ${issue.message}`);
+            }
+            else if (declared) {
+                problems.push(`status ${status} is not in the contract`);
+            }
+            if (ex.expect !== undefined) {
+                const miss = partialMatch(ex.expect, res.body);
+                if (miss)
+                    problems.push(miss);
+            }
+        }
+    }
+    catch (err) {
+        problems.push(err.message);
+    }
+    const ms = Math.round((performance.now() - started) * 10) / 10;
+    return { method: r.method, path: r.path, example: name, ok: problems.length === 0, status, ms, problems };
+}
+export async function runChecks(app, opts = {}) {
+    const results = [];
+    const unchecked = [];
+    const log = app.options.log;
+    app.options.log = false;
+    try {
+        for (const r of app.routes()) {
+            const label = `${r.method} ${r.path}`;
+            if (opts.only && !label.includes(opts.only))
+                continue;
+            const examples = r.spec.examples ?? [];
+            if (!examples.length)
+                unchecked.push(label);
+            for (const [i, ex] of examples.entries()) {
+                await opts.beforeEach?.();
+                results.push(await runOne(app, r, ex, i));
+            }
+        }
+    }
+    finally {
+        app.options.log = log;
+    }
+    const failed = results.filter((r) => !r.ok).length;
+    return { ok: failed === 0, passed: results.length - failed, failed, results, unchecked };
+}
+export function formatReport(report, title = "", color = false) {
+    const c = (code, s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+    const lines = ["", `  ${c("31", "印")} inkan check${title ? "  ·  " + title : ""}`, ""];
+    let last = "";
+    for (const r of report.results) {
+        const route = `${r.method} ${r.path}`;
+        if (route !== last) {
+            lines.push(`  ${c("1", r.method.padEnd(6))} ${r.path}`);
+            last = route;
+        }
+        const mark = r.ok ? c("32", "✓") : c("31", "✗");
+        lines.push(`    ${mark} ${r.example.padEnd(34)} ${String(r.status || "---").padEnd(4)} ${c("2", r.ms + "ms")}`);
+        for (const p of r.problems)
+            lines.push(`        ${c("31", p)}`);
+    }
+    if (report.unchecked.length) {
+        lines.push("", `  ${c("33", "no examples, so nothing holds them to their contract:")}`);
+        for (const u of report.unchecked)
+            lines.push(`    · ${u}`);
+    }
+    const total = report.results.length;
+    const summary = [
+        `${total} example${total === 1 ? "" : "s"}`,
+        c("32", `${report.passed} sealed`),
+        report.failed ? c("31", `${report.failed} broken`) : "",
+        report.unchecked.length ? c("33", `${report.unchecked.length} unchecked`) : "",
+    ].filter(Boolean);
+    lines.push("", "  " + summary.join(" · "), "");
+    return lines.join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};