@suluk/hono 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@suluk/hono",
+  "version": "0.1.0",
+  "description": "The Suluk derivation engine: minimal Hono+Zod RouteContracts in; v4 doc (dynamic per principal+time), validation, contract tests, and doc-coverage audit out. CANDIDATE tooling.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+  "@suluk/core": "0.1.0",
+  "@suluk/zod": "0.1.0",
+  "ajv": "^8.20.0",
+  "ajv-formats": "^3.0.1"
+},
+"peerDependencies": {
+  "zod": "^4.0.0",
+  "hono": "^4.0.0",
+  "@hono/zod-validator": "^0.4.0 || ^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0"
+},
+"devDependencies": {
+  "@types/bun": "latest",
+  "@suluk/openapi-compat": "0.1.0",
+  "zod": "^4.4.3",
+  "hono": "^4.0.0",
+  "@hono/zod-validator": "^0.8.0"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/audit.ts

@@ -0,0 +1,88 @@
+/**
+ * audit — documentation-coverage detection over a v4 document. This is the *ceiling* side of the
+ * Conformance Grade: an under-documented route indicts the producer. Findings are advisory (never a gate),
+ * mirroring the honest-loss pattern of compat diagnostics / zod warnings. autofill() supplies sane defaults.
+ */
+import type { OpenAPIv4Document, PathItem, Request } from "@suluk/core";
+import { responseList } from "./contract";
+
+export interface Finding {
+  /** "missing-doc" | "no-success-schema" | "response-no-description" | "no-examples" */
+  code: string;
+  severity: "warn" | "info";
+  path: string;
+  operation: string;
+  message: string;
+}
+
+function isSuccess(status: string): boolean {
+  return /^2/.test(status) || status === "2XX";
+}
+
+/** Walk every operation and report documentation gaps. */
+export function audit(doc: OpenAPIv4Document): Finding[] {
+  const findings: Finding[] = [];
+  for (const [path, piRaw] of Object.entries(doc.paths ?? {})) {
+    const pi = piRaw as PathItem;
+    for (const [name, reqRaw] of Object.entries(pi.requests ?? {})) {
+      const req = reqRaw as Request;
+      const add = (code: string, severity: Finding["severity"], message: string) =>
+        findings.push({ code, severity, path, operation: name, message });
+
+      if (!req.summary && !req.description) add("missing-doc", "warn", "operation has neither summary nor description");
+
+      const responses = Object.entries(req.responses ?? {});
+      const hasSuccessSchema = responses.some(([status, r]) => isSuccess(String((r as { status?: unknown }).status ?? status)) && (r as { contentSchema?: unknown }).contentSchema);
+      if (!hasSuccessSchema) add("no-success-schema", "info", "no 2xx response declares a content schema");
+
+      for (const [status, r] of responses) {
+        if (!(r as { description?: string }).description) add("response-no-description", "info", `response ${status} has no description`);
+      }
+    }
+  }
+  return findings;
+}
+
+/** A coarse coverage score in [0,1]: 1 = fully documented (no findings), lower = more gaps. */
+export function coverage(doc: OpenAPIv4Document): number {
+  let ops = 0;
+  for (const pi of Object.values(doc.paths ?? {})) ops += Object.keys((pi as PathItem).requests ?? {}).length;
+  if (ops === 0) return 1;
+  const warns = audit(doc).filter((f) => f.severity === "warn").length;
+  return Math.max(0, 1 - warns / ops);
+}
+
+/**
+ * Fill obvious documentation gaps in-place-safe (returns a new doc): synthesize a summary from the
+ * operation name + method/path, and a description for undescribed responses. Conservative — never
+ * overwrites authored text. This is the "automatically document under-documented routes" lever.
+ */
+export function autofill(doc: OpenAPIv4Document): OpenAPIv4Document {
+  const out: OpenAPIv4Document = structuredClone(doc);
+  for (const [path, piRaw] of Object.entries(out.paths ?? {})) {
+    const pi = piRaw as PathItem;
+    for (const [name, reqRaw] of Object.entries(pi.requests ?? {})) {
+      const req = reqRaw as Request;
+      if (!req.summary && !req.description) req.summary = humanize(name, req.method, path);
+      for (const r of Object.values(req.responses ?? {})) {
+        const resp = r as { status: string | number; description?: string };
+        if (!resp.description) resp.description = defaultStatusText(String(resp.status));
+      }
+    }
+  }
+  return out;
+}
+
+function humanize(name: string, method: string, path: string): string {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/_/g, " ");
+  return `${spaced.charAt(0).toUpperCase()}${spaced.slice(1)} (${method.toUpperCase()} ${path})`;
+}
+
+function defaultStatusText(status: string): string {
+  const map: Record<string, string> = {
+    "200": "OK", "201": "Created", "204": "No Content", "400": "Bad Request",
+    "401": "Unauthorized", "403": "Forbidden", "404": "Not Found", "409": "Conflict",
+    "422": "Unprocessable Entity", "500": "Internal Server Error",
+  };
+  return map[status] ?? (/^5/.test(status) ? "Server Error" : /^4/.test(status) ? "Client Error" : "Response");
+}

package/src/checks.ts

@@ -0,0 +1,97 @@
+/**
+ * contractChecks — auto-generated tests that act as checks for mistakes (the doc/contract as an executable
+ * verification). Each check is a pure function returning a verdict, so they run in CI, in the vscode
+ * extension, or as bun tests (toBunTest emits source). They catch the mistakes a contract can encode:
+ *   - a request/response schema that isn't valid JSON Schema 2020-12
+ *   - a provided example that does NOT satisfy its own schema
+ *   - the emitted v4 document failing the v4 meta-schema
+ *   - two routes whose ADA signatures provably collide (ambiguous routing)
+ */
+import { validateDocument, buildAda } from "@suluk/core";
+import { validateSchema2020 } from "./schema-check";
+import { responseList, type RouteContract } from "./contract";
+import { emitV4 } from "./emit";
+import { zodToV4 } from "@suluk/zod";
+import type * as z from "zod";
+
+export interface Check {
+  name: string;
+  run(): { pass: boolean; message?: string };
+}
+
+function schemaValid(label: string, schema: z.ZodType): Check {
+  return {
+    name: `schema valid 2020-12: ${label}`,
+    run() {
+      const { schema: js } = zodToV4(schema as Parameters<typeof zodToV4>[0]);
+      const r = validateSchema2020(js);
+      return { pass: r.valid, message: r.valid ? undefined : r.errors.map((e) => `${e.path} ${e.message}`).join("; ") };
+    },
+  };
+}
+
+function exampleConforms(label: string, schema: z.ZodType, example: unknown, shouldPass = true): Check {
+  return {
+    name: `example ${shouldPass ? "⊨" : "⊭"} schema: ${label}`,
+    run() {
+      const ok = (schema as { safeParse(v: unknown): { success: boolean } }).safeParse(example).success;
+      return { pass: ok === shouldPass, message: ok === shouldPass ? undefined : `example ${ok ? "unexpectedly passed" : "failed"} its schema` };
+    },
+  };
+}
+
+/** Build the full check suite for a set of route contracts. */
+export function contractChecks(routes: readonly RouteContract[]): Check[] {
+  const checks: Check[] = [];
+
+  for (const route of routes) {
+    const id = `${route.method.toUpperCase()} ${route.path}`;
+    const req = route.request;
+    for (const [slot, schema] of [["json", req?.json], ["query", req?.query], ["params", req?.params], ["header", req?.header]] as const) {
+      if (schema) checks.push(schemaValid(`${id} ${slot}`, schema));
+    }
+    for (const ex of req?.examples ?? []) if (req?.json) checks.push(exampleConforms(`${id} request example`, req.json, ex));
+    for (const r of responseList(route.responses)) {
+      if (r.schema) {
+        checks.push(schemaValid(`${id} ${r.status}`, r.schema));
+        for (const ex of r.examples ?? []) checks.push(exampleConforms(`${id} ${r.status} example`, r.schema, ex));
+      }
+    }
+  }
+
+  // whole-document checks
+  checks.push({
+    name: "emitted v4 document validates against the meta-schema",
+    run() {
+      const { document } = emitV4(routes);
+      const r = validateDocument(document);
+      return { pass: r.valid, message: r.valid ? undefined : r.errors.slice(0, 3).map((e) => `${e.path} ${e.message}`).join("; ") };
+    },
+  });
+  checks.push({
+    name: "no two routes provably collide (unambiguous routing)",
+    run() {
+      const { document } = emitV4(routes);
+      const bad = buildAda(document).collisions.filter((c) => c.verdict === "provable-collision");
+      return { pass: bad.length === 0, message: bad.length ? bad.map((c) => `${c.a.name} vs ${c.b.name}`).join("; ") : undefined };
+    },
+  });
+  return checks;
+}
+
+export interface CheckRun {
+  total: number;
+  passed: number;
+  failures: { name: string; message?: string }[];
+}
+
+/** Run every check and summarize. */
+export function runContractChecks(routes: readonly RouteContract[]): CheckRun {
+  const checks = contractChecks(routes);
+  const failures: CheckRun["failures"] = [];
+  for (const c of checks) {
+    const v = c.run();
+    if (!v.pass) failures.push({ name: c.name, message: v.message });
+  }
+  return { total: checks.length, passed: checks.length - failures.length, failures };
+}

package/src/contract.ts

@@ -0,0 +1,70 @@
+/**
+ * The RouteContract — the single source of truth a user authors (minimally), from which every Derivation
+ * (the v4 doc, Scalar/Swagger, validation, tests, audit) is projected. It is plain data + Zod schemas, so
+ * the pure derivations (emitV4 / audit / contractChecks) need no running server — only mount() touches Hono.
+ */
+import type * as z from "zod";
+import type { SecurityRequirement } from "@suluk/core";
+
+export type Method = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+
+export interface RouteRequest {
+  /** Path params (Hono `:name`), as a Zod object. */
+  params?: z.ZodType;
+  /** Query string, as a Zod object. */
+  query?: z.ZodType;
+  /** Request headers that participate in the contract, as a Zod object. */
+  header?: z.ZodType;
+  /** Request body (defaults to application/json). */
+  json?: z.ZodType;
+  /** Override the body media type. */
+  contentType?: string;
+  /** Optional concrete example bodies — used by contractChecks to assert example⊨schema. */
+  examples?: unknown[];
+}
+
+export interface RouteResponse {
+  status: number;
+  description?: string;
+  schema?: z.ZodType;
+  /** Defaults to application/json when a schema is present. */
+  contentType?: string;
+  /** Optional concrete example responses — used by contractChecks. */
+  examples?: unknown[];
+}
+
+export interface RouteContract {
+  method: Method;
+  /** Hono-style path, e.g. "/pet/:petId" or "/files/*". Converted to a v4 uriTemplate on emit. */
+  path: string;
+  /** The operation's v4 by-name handle (C009). Derived from method+path if omitted. */
+  name?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated?: boolean;
+  /** ISO date; with EmitContext.now, the operation is marked deprecated once now ≥ this. */
+  deprecatedSince?: string;
+  /** ISO date; with EmitContext.now, the operation is HIDDEN once now ≥ this (the "when" axis). */
+  removedSince?: string;
+  /** Explicit by-name security requirements (C014). */
+  security?: SecurityRequirement[];
+  /** Required scopes. Drives BOTH the per-principal filter (the "who") and synthesized security. */
+  scopes?: string[];
+  request?: RouteRequest;
+  /** Responses, as a list (each carries its own status) or a status-keyed map. */
+  responses?: RouteResponse[] | Record<string, RouteResponse>;
+  /** Optional live handler, used only by mount(). */
+  handler?: (c: unknown) => unknown | Promise<unknown>;
+}
+
+/** Identity helper that preserves literal inference when authoring a contract array. */
+export function contract<const T extends readonly RouteContract[]>(routes: T): T {
+  return routes;
+}
+
+/** Normalize responses (list or map) to a list. */
+export function responseList(r: RouteContract["responses"]): RouteResponse[] {
+  if (!r) return [];
+  return Array.isArray(r) ? r : Object.values(r);
+}

package/src/emit.ts

@@ -0,0 +1,165 @@
+/**
+ * emitV4 — the keystone Derivation: render(contracts, principal, now) -> v4 Document.
+ *
+ * NOT a static file: the document is a pure function of the contracts × the requesting principal (scopes,
+ * the "who") × time (now, the "when"). A public export is just emitV4(routes) with no principal/now.
+ */
+import { buildAda } from "@suluk/core";
+import type {
+  OpenAPIv4Document, PathItem, Request, Response, ParameterSchema, SecurityRequirement, Server, Info, SecurityScheme,
+} from "@suluk/core";
+import { zodToV4 } from "@suluk/zod";
+import { responseList, type RouteContract, type Method } from "./contract";
+
+export interface EmitContext {
+  info?: Partial<Info>;
+  servers?: Server[];
+  /** The "who": include only operations whose required scopes the principal holds. Omit ⇒ full public doc. */
+  principal?: { scopes?: string[] };
+  /** The "when": ISO date / Date. Drives deprecatedSince + removedSince. Omit ⇒ no time filtering. */
+  now?: string | Date;
+  /** Name of the security scheme that `scopes` map onto (e.g. "bearerAuth"). Enables scopes→security. */
+  securityScheme?: string;
+  /** Declared security schemes for components (C014). */
+  securitySchemes?: Record<string, SecurityScheme>;
+  /** Include operations flagged deprecated (default true; they are marked, not hidden). */
+  includeDeprecated?: boolean;
+}
+
+export interface EmitDiagnostic {
+  kind: "collision" | "filtered" | "note";
+  operation?: string;
+  message: string;
+}
+
+export interface EmitResult {
+  document: OpenAPIv4Document;
+  diagnostics: EmitDiagnostic[];
+}
+
+function pascal(s: string): string {
+  return s.replace(/(^|[-_])(\w)/g, (_, __, c: string) => c.toUpperCase());
+}
+
+/** Hono path "/pet/:petId" / "/files/*" → v4 uriTemplate "pet/{petId}" / "files/{+wildcard}" (no leading slash). */
+function toUriTemplate(honoPath: string): { template: string; segments: string[] } {
+  const segs = honoPath.replace(/^\//, "").split("/").filter(Boolean).map((s) => {
+    if (s === "*") return "{+wildcard}";
+    if (s.startsWith(":")) return `{${s.slice(1).replace(/\{.*$/, "")}}`; // strip Hono regex constraints
+    return s;
+  });
+  return { template: segs.join("/"), segments: segs };
+}
+
+function deriveName(method: Method, segments: string[]): string {
+  const parts = segments.map((s) =>
+    s.startsWith("{+") ? "By" + pascal(s.slice(2, -1)) : s.startsWith("{") ? "By" + pascal(s.slice(1, -1)) : pascal(s),
+  );
+  return method + parts.join("");
+}
+
+function zParam(schema: unknown): Record<string, unknown> | undefined {
+  if (!schema) return undefined;
+  return zodToV4(schema as Parameters<typeof zodToV4>[0]).schema;
+}
+
+function toMs(d: string | Date): number {
+  return (typeof d === "string" ? new Date(d) : d).getTime();
+}
+
+/** Build one v4 Request from a route contract. */
+function buildRequest(route: RouteContract, deprecated: boolean, ctx: EmitContext): Request {
+  const req: Request = { method: route.method, responses: {} };
+  if (route.summary) req.summary = route.summary;
+  if (route.description) req.description = route.description;
+  if (route.tags) req.tags = route.tags;
+  if (deprecated) req.deprecated = true;
+
+  if (route.request?.json) {
+    req.contentType = route.request.contentType ?? "application/json";
+    req.contentSchema = zodToV4(route.request.json as Parameters<typeof zodToV4>[0]).schema;
+  }
+
+  const ps: ParameterSchema = {};
+  const q = zParam(route.request?.query); if (q) ps.query = q;
+  const p = zParam(route.request?.params); if (p) ps.path = p;
+  const h = zParam(route.request?.header); if (h) ps.header = h;
+  if (Object.keys(ps).length) req.parameterSchema = ps;
+
+  const responses: Record<string, Response> = {};
+  for (const r of responseList(route.responses)) {
+    const resp: Response = { status: r.status };
+    if (r.description) resp.description = r.description;
+    if (r.schema) {
+      resp.contentType = r.contentType ?? "application/json";
+      resp.contentSchema = zodToV4(r.schema as Parameters<typeof zodToV4>[0]).schema;
+    }
+    responses[String(r.status)] = resp;
+  }
+  if (Object.keys(responses).length === 0) responses["200"] = { status: 200 };
+  req.responses = responses;
+
+  // security: explicit wins; else synthesize from scopes if a scheme name is configured.
+  const security: SecurityRequirement[] | undefined =
+    route.security ?? (route.scopes && ctx.securityScheme ? [{ [ctx.securityScheme]: route.scopes }] : undefined);
+  if (security) req.security = security;
+  return req;
+}
+
+/**
+ * Project a list of route contracts into a v4 document for a given principal + time.
+ * - WHEN: removedSince ≤ now ⇒ hidden; deprecatedSince ≤ now ⇒ marked deprecated.
+ * - WHO: if a principal is supplied, an operation requiring scopes the principal lacks is omitted.
+ */
+export function emitV4(routes: readonly RouteContract[], ctx: EmitContext = {}): EmitResult {
+  const diagnostics: EmitDiagnostic[] = [];
+  const nowMs = ctx.now != null ? toMs(ctx.now) : undefined;
+  const principalScopes = ctx.principal ? new Set(ctx.principal.scopes ?? []) : undefined;
+
+  const paths: Record<string, PathItem> = {};
+  for (const route of routes) {
+    const { template, segments } = toUriTemplate(route.path);
+    const name = route.name ?? deriveName(route.method, segments);
+
+    // WHEN filter
+    if (nowMs != null && route.removedSince && toMs(route.removedSince) <= nowMs) {
+      diagnostics.push({ kind: "filtered", operation: name, message: `hidden: removed since ${route.removedSince}` });
+      continue;
+    }
+    // WHO filter
+    if (principalScopes && route.scopes && !route.scopes.every((s) => principalScopes.has(s))) {
+      diagnostics.push({ kind: "filtered", operation: name, message: `hidden: principal lacks scope(s) ${route.scopes.join(", ")}` });
+      continue;
+    }
+    const deprecated =
+      !!route.deprecated || (nowMs != null && !!route.deprecatedSince && toMs(route.deprecatedSince) <= nowMs);
+    if (deprecated && ctx.includeDeprecated === false) {
+      diagnostics.push({ kind: "filtered", operation: name, message: "hidden: deprecated (includeDeprecated=false)" });
+      continue;
+    }
+
+    const pi = (paths[template] ??= { requests: {} });
+    if (pi.requests[name]) {
+      diagnostics.push({ kind: "collision", operation: name, message: `duplicate operation name '${name}' at '${template}'` });
+      pi.requests[`${name}_${route.method}`] = buildRequest(route, deprecated, ctx);
+    } else {
+      pi.requests[name] = buildRequest(route, deprecated, ctx);
+    }
+  }
+
+  const document: OpenAPIv4Document = {
+    openapi: "4.0.0-candidate",
+    info: { title: ctx.info?.title ?? "API", version: ctx.info?.version ?? "0.0.0", ...ctx.info },
+    paths,
+  };
+  if (ctx.servers) document.servers = ctx.servers;
+  if (ctx.securitySchemes) document.components = { securitySchemes: ctx.securitySchemes };
+
+  // static collision audit over the ADA (detect-and-tolerate; surfaced as diagnostics, never a gate).
+  for (const c of buildAda(document).collisions) {
+    if (c.verdict === "provable-collision") {
+      diagnostics.push({ kind: "collision", operation: `${c.a.name} / ${c.b.name}`, message: `provable signature collision at '${c.a.pathTemplate}'` });
+    }
+  }
+  return { document, diagnostics };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @suluk/hono — the derivation engine. The user authors minimal RouteContracts (Hono + Zod); everything
+ * else is derived: the v4 document (dynamic per principal + time), request validation, contract tests, and
+ * a documentation-coverage audit. See tooling/ARCHITECTURE.md. CANDIDATE tooling.
+ */
+export { contract, responseList, type RouteContract, type RouteRequest, type RouteResponse, type Method } from "./contract";
+export { emitV4, type EmitContext, type EmitResult, type EmitDiagnostic } from "./emit";
+export { audit, coverage, autofill, type Finding } from "./audit";
+export { contractChecks, runContractChecks, type Check, type CheckRun } from "./checks";
+export { validateSchema2020, type SchemaCheck } from "./schema-check";
+export { mount } from "./mount";

package/src/mount.ts

@@ -0,0 +1,26 @@
+/**
+ * mount — the thin Hono adapter. Wires the SAME RouteContract list that emitV4 reads onto a live Hono app,
+ * using @hono/zod-validator with the contract's own Zod schemas. Because the doc and the running app are
+ * projected from one source, they cannot drift. This is the only file that imports Hono.
+ */
+import type { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import type { RouteContract } from "./contract";
+
+type Registrar = Record<string, (path: string, ...rest: unknown[]) => unknown>;
+
+/** Mount each contract's handler (with request validation derived from its Zod schemas) onto `app`. */
+export function mount<T extends Hono>(app: T, routes: readonly RouteContract[]): T {
+  const registrar = app as unknown as Registrar;
+  for (const route of routes) {
+    const middlewares: unknown[] = [];
+    const req = route.request;
+    if (req?.json) middlewares.push(zValidator("json", req.json as Parameters<typeof zValidator>[1]));
+    if (req?.query) middlewares.push(zValidator("query", req.query as Parameters<typeof zValidator>[1]));
+    if (req?.params) middlewares.push(zValidator("param", req.params as Parameters<typeof zValidator>[1]));
+    if (req?.header) middlewares.push(zValidator("header", req.header as Parameters<typeof zValidator>[1]));
+    const handler = route.handler ?? ((c: { json: (b: unknown, s?: number) => unknown }) => c.json({ message: "not implemented" }, 501));
+    registrar[route.method](route.path, ...middlewares, handler);
+  }
+  return app;
+}

package/src/schema-check.ts

@@ -0,0 +1,29 @@
+/**
+ * Validate that a value is a well-formed JSON Schema 2020-12 (the dialect v4 Schema Objects must use).
+ * Used by contractChecks to catch a Zod→v4 conversion that produced a malformed schema.
+ */
+import Ajv2020 from "ajv/dist/2020";
+import addFormats from "ajv-formats";
+
+export interface SchemaCheck {
+  valid: boolean;
+  errors: { path: string; message: string }[];
+}
+
+function build() {
+  const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+  addFormats(ajv);
+  return ajv.getSchema("https://json-schema.org/draft/2020-12/schema")!;
+}
+
+let metaFn: ReturnType<typeof build> | undefined;
+
+export function validateSchema2020(schema: unknown): SchemaCheck {
+  if (!metaFn) metaFn = build();
+  const valid = metaFn(schema) as boolean;
+  const errors = (metaFn.errors ?? []).map((e: { instancePath?: string; message?: string }) => ({
+    path: e.instancePath || "/",
+    message: e.message ?? "invalid",
+  }));
+  return { valid, errors };
+}

package/test/hono.test.ts

@@ -0,0 +1,131 @@
+import { test, expect, describe } from "bun:test";
+import * as z from "zod";
+import { Hono } from "hono";
+import { validateDocument, buildAda, matchRequest } from "@suluk/core";
+import { validate31, downgrade } from "@suluk/openapi-compat";
+import { contract, emitV4, audit, coverage, autofill, runContractChecks, mount } from "../src/index";
+
+const Pet = z.object({ id: z.number().int().optional(), name: z.string().min(1), tags: z.array(z.string()) });
+
+const routes = contract([
+  {
+    method: "get", path: "/pet", name: "listPets",
+    summary: "List pets", tags: ["pets"],
+    responses: [{ status: 200, description: "ok", schema: z.array(Pet) }],
+  },
+  {
+    method: "post", path: "/pet", name: "createPet",
+    summary: "Create a pet", tags: ["pets"], scopes: ["write:pets"],
+    request: { json: Pet, examples: [{ name: "Rex", tags: [] }] },
+    responses: [{ status: 201, description: "created", schema: Pet }],
+    handler: (c: any) => c.json({ name: "Rex", tags: [] }, 201),
+  },
+  {
+    method: "get", path: "/pet/:petId", name: "getPet",
+    summary: "Get a pet by id",
+    request: { params: z.object({ petId: z.string() }) },
+    responses: [{ status: 200, description: "ok", schema: Pet }, { status: 404, description: "not found" }],
+    handler: (c: any) => c.json({ name: "Rex", tags: [] }),
+  },
+  {
+    // an undocumented + deprecated-since route, to exercise audit + the time axis
+    method: "get", path: "/legacy", name: "legacyThing",
+    deprecatedSince: "2020-01-01", removedSince: "2030-01-01",
+    responses: [{ status: 200 }],
+  },
+]);
+
+describe("emitV4 — the keystone derivation", () => {
+  test("produces a v4 document that validates against the meta-schema", () => {
+    const { document } = emitV4(routes, { info: { title: "Pets", version: "1.0.0" } });
+    const r = validateDocument(document);
+    if (!r.valid) console.error(r.errors);
+    expect(r.valid).toBe(true);
+  });
+
+  test("Hono path :petId becomes a v4 uriTemplate {petId}, indexed in the ADA", () => {
+    const { document } = emitV4(routes);
+    expect(Object.keys(document.paths)).toContain("pet/{petId}");
+    const ada = buildAda(document);
+    expect(matchRequest(ada, "GET", "/pet/123")!.operation.name).toBe("getPet");
+  });
+
+  test("downgrades to valid OpenAPI 3.1 (Scalar/Swagger-ready)", () => {
+    const { document } = emitV4(routes, { info: { title: "Pets", version: "1" } });
+    expect(validate31(downgrade(document).document).valid).toBe(true);
+  });
+});
+
+describe("the document is a FUNCTION of who + when (dynamic projection)", () => {
+  test("WHO: a principal without write:pets does not see createPet", () => {
+    const reader = emitV4(routes, { principal: { scopes: [] } });
+    const names = Object.values(reader.document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(names).toContain("listPets");
+    expect(names).not.toContain("createPet"); // requires write:pets
+  });
+  test("WHO: a principal WITH write:pets sees createPet", () => {
+    const writer = emitV4(routes, { principal: { scopes: ["write:pets"] } });
+    const names = Object.values(writer.document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(names).toContain("createPet");
+  });
+  test("WHO: no principal ⇒ full public doc (no filtering)", () => {
+    const full = emitV4(routes);
+    const names = Object.values(full.document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(names).toContain("createPet");
+  });
+  test("WHEN: after removedSince the legacy route is hidden", () => {
+    const future = emitV4(routes, { now: "2031-06-01" });
+    const names = Object.values(future.document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(names).not.toContain("legacyThing");
+  });
+  test("WHEN: before removedSince but after deprecatedSince it is shown, marked deprecated", () => {
+    const now = emitV4(routes, { now: "2026-06-10" });
+    const legacy = now.document.paths["legacy"].requests["legacyThing"];
+    expect(legacy.deprecated).toBe(true);
+  });
+});
+
+describe("audit — under-documented route detection (Conformance-Grade ceiling)", () => {
+  test("flags the undocumented legacy route, not the documented ones", () => {
+    const { document } = emitV4(routes);
+    const findings = audit(document);
+    const undocumented = findings.filter((f) => f.code === "missing-doc").map((f) => f.operation);
+    expect(undocumented).toContain("legacyThing");
+    expect(undocumented).not.toContain("getPet");
+  });
+  test("coverage is < 1 when a route is undocumented, and autofill raises it to 1", () => {
+    const { document } = emitV4(routes);
+    expect(coverage(document)).toBeLessThan(1);
+    expect(coverage(autofill(document))).toBe(1);
+  });
+});
+
+describe("contractChecks — auto-generated tests that catch mistakes", () => {
+  test("all checks pass for a well-formed contract set", () => {
+    const run = runContractChecks(routes);
+    if (run.failures.length) console.error(run.failures);
+    expect(run.failures).toEqual([]);
+    expect(run.total).toBeGreaterThan(5);
+  });
+  test("a request example that violates its schema is caught", () => {
+    const bad = contract([{
+      method: "post", path: "/x", name: "x",
+      request: { json: z.object({ n: z.number() }), examples: [{ n: "not a number" }] },
+      responses: [{ status: 200 }],
+    }]);
+    expect(runContractChecks(bad).failures.length).toBeGreaterThan(0);
+  });
+});
+
+describe("mount — one source feeds both the doc and the live app", () => {
+  const app = mount(new Hono(), routes);
+  test("validation derived from the same contracts rejects bad input, accepts good", async () => {
+    const bad = await app.request("/pet", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ name: "" }) });
+    const good = await app.request("/pet", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ name: "Rex", tags: [] }) });
+    expect(bad.status).toBe(400);   // name.min(1) fails
+    expect(good.status).toBe(201);
+  });
+  test("a GET route responds", async () => {
+    expect((await app.request("/pet/9")).status).toBe(200);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "types": ["bun"], "resolveJsonModule": true },
+  "include": ["src", "test"]
+}