@tetsujs/openapi 0.5.0 → 0.5.2

package/src/operation.ts

@@ -433,20 +433,16 @@ function responses(
       schema === null ? undefined : emitted(schema, "a response", warn);
 
     add(status, {
-      description: describeStatus(status),
-      placeholder: true,
+      placeholder: describeStatus(status),
+      said: described ? wordsOf(described, envelopes) : [],
       schemas: described
-        ? branchesFor(described, Number(status), envelopes, warn)
+        ? branchesFor(unionOnly(described), Number(status), envelopes, warn)
         : [],
     });
   }
 
   if (![...answers.keys()].some((status) => status.startsWith("2"))) {
-    add("200", {
-      description: "Successful response",
-      placeholder: true,
-      schemas: [],
-    });
+    add("200", { placeholder: "Successful response", said: [], schemas: [] });
   }
 
   for (const [status, answer] of failures(
@@ -514,7 +510,12 @@ function failures(
     found.push([
       options.validationStatus,
       {
-        description: "Request failed schema validation",
+        said: [
+          {
+            code: "VALIDATION_FAILED",
+            text: "Request failed schema validation",
+          },
+        ],
         schemas: [
           envelopes.ref(
             options.validationStatus,
@@ -538,9 +539,13 @@ function failures(
     found.push([
       status,
       {
-        description:
-          requirement.description ??
-          `Request did not satisfy ${requirement.name}`,
+        said: [
+          said(
+            requirement.error,
+            requirement.description ??
+              `Request did not satisfy ${requirement.name}`,
+          ),
+        ],
         schemas: [envelopeRef(status, requirement.error, requirement.message)],
       },
     ]);
@@ -554,7 +559,7 @@ function failures(
     found.push([
       response.status,
       {
-        description: response.description,
+        said: [said(response.error, response.description)],
         schemas: described
           ? branchesFor(described, response.status, envelopes, warn)
           : [
@@ -577,7 +582,12 @@ function failures(
       found.push([
         400,
         {
-          description: "Body could not be parsed in the declared shape",
+          said: [
+            said(
+              unparsable.error,
+              "Body could not be parsed in the declared shape",
+            ),
+          ],
           schemas: [envelopeRef(400, unparsable.error, unparsable.message)],
         },
       ]);
@@ -586,7 +596,9 @@ function failures(
     found.push([
       413,
       {
-        description: "Body exceeded the configured size limit",
+        said: [
+          said("BODY_TOO_LARGE", "Body exceeded the configured size limit"),
+        ],
         schemas: [
           envelopeRef(
             413,
@@ -601,7 +613,12 @@ function failures(
   found.push([
     500,
     {
-      description: "The request failed and nothing mapped the failure",
+      said: [
+        said(
+          "INTERNAL_SERVER_ERROR",
+          "The request failed and nothing mapped the failure",
+        ),
+      ],
       schemas: [
         envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error"),
       ],
@@ -619,17 +636,66 @@ function failures(
  * reference to its definition; empty when the answer has no body to
  * describe.
  *
- * A route declares a status by its schema alone and has no words for it,
- * so its description is a `placeholder`: it stands for the status only
- * when nothing else describes it.
+ * `said` is what the answer says about itself, with the code each part is
+ * about when it is known: a hook's description, the framework's, what a
+ * route's schema says. A route whose schema says nothing has only its
+ * `placeholder` — the reason phrase — which stands for the status when
+ * nothing else describes it.
  */
 interface Answer {
-  readonly description: string;
-  readonly placeholder?: boolean;
+  readonly said: readonly Said[];
+  readonly placeholder?: string;
   readonly schemas: readonly Record<string, unknown>[];
   readonly headers?: Readonly<Record<string, HeaderObject>>;
 }
 
+/** One description, and the code it describes when that is known. */
+interface Said {
+  readonly code?: string;
+  readonly text: string;
+}
+
+function said(code: string | undefined, text: string): Said {
+  return code === undefined ? { text } : { code, text };
+}
+
+/**
+ * What a route's schema says about the status it is declared for: its own
+ * `description`, or — for a union that has none — each branch's, with the
+ * branch's code. A schema that says nothing says nothing here either.
+ */
+function wordsOf(schema: JsonSchemaObject, envelopes: Envelopes): Said[] {
+  if (typeof schema.description === "string") {
+    return [said(envelopes.format.code(schema), schema.description)];
+  }
+
+  return branchesOf(unionOnly(schema), envelopes.format.code).flatMap(
+    (branch) =>
+      typeof branch.description === "string"
+        ? [said(envelopes.format.code(branch), branch.description)]
+        : [],
+  );
+}
+
+/**
+ * A union without the `description` it carried as a whole — which says
+ * what the status is, and is used as the status's description — so its
+ * branches can join the status's own alternatives. Anything but a union
+ * is kept as it is, its description included, for its definition.
+ */
+function unionOnly(schema: JsonSchemaObject): JsonSchemaObject {
+  if (
+    typeof schema.description !== "string" ||
+    (!Array.isArray(schema.anyOf) && !Array.isArray(schema.oneOf))
+  ) {
+    return schema;
+  }
+
+  const { description: _, ...union } = schema;
+
+  return union;
+}
+
 /**
  * Folds everything that answers with one status into one response.
  *
@@ -646,12 +712,10 @@ interface Answer {
  * alternative, not two.
  *
  * Headers are gathered the same way, the first description of a name
- * standing for all of them. Descriptions are joined, except a route's
- * placeholder next to one that says something.
+ * standing for all of them; descriptions as {@link wording} words them.
  */
 function merge(list: readonly Answer[], envelopes: Envelopes): ResponseObject {
   const schemas = distinct(list.flatMap((answer) => answer.schemas));
-  const worded = list.filter((answer) => !answer.placeholder);
   const headers: Record<string, HeaderObject> = {};
 
   for (const answer of list) {
@@ -661,9 +725,7 @@ function merge(list: readonly Answer[], envelopes: Envelopes): ResponseObject {
   }
 
   return {
-    description: (worded.length > 0 ? worded : list)
-      .map((answer) => answer.description)
-      .join("; "),
+    description: wording(list),
     ...(Object.keys(headers).length > 0 ? { headers } : {}),
     ...(schemas.length > 0
       ? {
@@ -675,6 +737,49 @@ function merge(list: readonly Answer[], envelopes: Envelopes): ResponseObject {
   };
 }
 
+/**
+ * The description of a status, from everything that answers with it.
+ *
+ * One thing said is the description. Several are a list, each item led
+ * by the code it is about, so a reader sees which description goes with
+ * which code — descriptions are CommonMark, and every renderer draws the
+ * list. The same code said the same way twice, by the route and a hook,
+ * is one item. With nothing said at all, the route's placeholder stands.
+ */
+function wording(list: readonly Answer[]): string {
+  const seen = new Set<string>();
+  const items: Said[] = [];
+
+  for (const answer of list) {
+    for (const item of answer.said) {
+      const key = `${item.code ?? ""}\n${item.text}`;
+
+      if (!seen.has(key)) {
+        seen.add(key);
+        items.push(item);
+      }
+    }
+  }
+
+  const [only] = items;
+
+  if (items.length === 1 && only) {
+    return only.text;
+  }
+
+  if (items.length > 1) {
+    return items
+      .map((item) =>
+        item.code === undefined
+          ? `- ${item.text}`
+          : `- \`${item.code}\`: ${item.text}`,
+      )
+      .join("\n");
+  }
+
+  return list.find((answer) => answer.placeholder)?.placeholder ?? "";
+}
+
 /**
  * The alternatives of a body as one schema.
  *

package/src/testing.ts

@@ -0,0 +1,453 @@
+/**
+ * Checking a response against the document, in a test.
+ *
+ * The document describes what every operation can answer; a test provokes
+ * one answer. `assertDescribed` holds the two together: the status is
+ * declared, the body is one the status describes, a header asked about is
+ * documented. What it catches is what a client generated from the document
+ * would trip over — an error code nobody declared, a field the schema says
+ * is always there and is not.
+ *
+ * It checks only what a test provoked, which is why it can be strict: the
+ * core does not compare a thrown error with the route's response map,
+ * because a guard's refusal would be reported on every route it runs on;
+ * a test that provoked the refusal asks about that one response.
+ *
+ * ```ts
+ * import { assertDescribed } from "@tetsujs/openapi/testing";
+ *
+ * const { document } = openapi(app, { info });
+ *
+ * test("a wrong code is what the document says", async () => {
+ *   const res = await request("/session", { method: "POST", body });
+ *
+ *   await assertDescribed(document, "POST /session", res);
+ * });
+ * ```
+ *
+ * @module
+ */
+
+import type { OpenApiDocument, ResponseObject } from "./document.ts";
+
+/** What `assertDescribed` checks besides the status and the body's shape. */
+export interface AssertDescribedOptions {
+  /**
+   * Checks the body against its schema in full, with the JSON Schema
+   * validator of your choice — this package has none, and without one
+   * only the top level is compared: required fields, fields that are a
+   * `const`. Return `true` when the body is valid, or what is wrong.
+   *
+   * The schema stands on its own: every `$ref` into the document's
+   * components points into its own `$defs`.
+   *
+   * @example
+   * ```ts
+   * const ajv = new Ajv2020();
+   *
+   * await assertDescribed(document, "POST /session", res, {
+   *   validate: (schema, body) => ajv.validate(schema, body) || ajv.errorsText(),
+   * });
+   * ```
+   */
+  readonly validate?: (
+    schema: Record<string, unknown>,
+    body: unknown,
+  ) => true | string;
+
+  /**
+   * Headers the status must declare when the response carries them —
+   * `retry-after`. Only those named: a response carries headers no
+   * document describes, `content-type` and `x-request-id` among them.
+   */
+  readonly headers?: readonly string[];
+}
+
+/**
+ * Throws unless the response is one the document describes for the
+ * operation, listing every way it is not.
+ *
+ * `request` names the operation as the test called it — a method and the
+ * path it requested, `"GET /users/42"` — matched against the document's
+ * path templates. The body is read from a clone, and the test can still
+ * read the response.
+ */
+export async function assertDescribed(
+  document: OpenApiDocument,
+  request: string,
+  response: Response,
+  options: AssertDescribedOptions = {},
+): Promise<void> {
+  const problems = await problemsOf(document, request, response, options);
+
+  if (problems.length > 0) {
+    throw new Error(
+      `${request} answered ${response.status}, which the document does not describe:\n${problems.map((problem) => `- ${problem}`).join("\n")}`,
+    );
+  }
+}
+
+async function problemsOf(
+  document: OpenApiDocument,
+  request: string,
+  response: Response,
+  options: AssertDescribedOptions,
+): Promise<string[]> {
+  const [method = "", target = ""] = request.split(" ");
+  const path = target.split("?")[0] ?? "";
+  const template = templateOf(document, path);
+  const operation =
+    template === undefined
+      ? undefined
+      : document.paths[template]?.[method.toLowerCase()];
+
+  if (operation === undefined) {
+    return [`there is no operation for ${method.toUpperCase()} ${path}`];
+  }
+
+  const status = String(response.status);
+  const described = operation.responses[status];
+
+  if (described === undefined) {
+    return [
+      `${status}, which the operation does not declare: it declares ${Object.keys(operation.responses).join(", ")}`,
+    ];
+  }
+
+  return [
+    ...(await bodyProblems(document, status, described, response, options)),
+    ...headerProblems(status, described, response, options.headers ?? []),
+  ];
+}
+
+/**
+ * The path template a requested path belongs to: the one whose segments
+ * match it, `{param}` matching any one segment. Of several, the one with
+ * the most literal segments, as the router prefers `/users/me` to
+ * `/users/{id}`; a template ending in a parameter also stands for a
+ * wildcard, which matches the rest of the path.
+ */
+function templateOf(
+  document: OpenApiDocument,
+  path: string,
+): string | undefined {
+  const segments = path.split("/").filter(Boolean);
+
+  let best: { template: string; literals: number } | undefined;
+
+  for (const template of Object.keys(document.paths)) {
+    const parts = template.split("/").filter(Boolean);
+    const last = parts.at(-1) ?? "";
+    const rest = isParameter(last) && segments.length > parts.length;
+
+    if (parts.length !== segments.length && !rest) {
+      continue;
+    }
+
+    let literals = 0;
+    let matches = true;
+
+    for (const [index, part] of parts.entries()) {
+      if (isParameter(part)) {
+        continue;
+      }
+
+      if (part !== segments[index]) {
+        matches = false;
+
+        break;
+      }
+
+      literals += 1;
+    }
+
+    if (matches && (best === undefined || literals > best.literals)) {
+      best = { template, literals };
+    }
+  }
+
+  return best?.template;
+}
+
+function isParameter(segment: string): boolean {
+  return segment.startsWith("{") && segment.endsWith("}");
+}
+
+async function bodyProblems(
+  document: OpenApiDocument,
+  status: string,
+  described: ResponseObject,
+  response: Response,
+  options: AssertDescribedOptions,
+): Promise<string[]> {
+  const text = await response.clone().text();
+  const content = described.content ?? {};
+  const mediaTypes = Object.keys(content);
+
+  if (text === "") {
+    return [];
+  }
+
+  if (mediaTypes.length === 0) {
+    return [`a body, where its ${status} describes none`];
+  }
+
+  const mediaType = (response.headers.get("content-type") ?? "")
+    .split(";")[0]
+    ?.trim();
+
+  if (mediaType === undefined || !mediaTypes.includes(mediaType)) {
+    return [
+      `a body of type "${mediaType ?? ""}", where its ${status} describes ${mediaTypes.join(", ")}`,
+    ];
+  }
+
+  const schema = content[mediaType]?.schema;
+
+  if (schema === undefined || !mediaType.endsWith("json")) {
+    return [];
+  }
+
+  let body: unknown;
+
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return [`a body that is not the JSON its ${status} describes`];
+  }
+
+  const problems = shapeProblems(document, status, schema, body);
+
+  if (options.validate) {
+    const verdict = options.validate(standalone(document, schema), body);
+
+    if (verdict !== true) {
+      problems.push(verdict);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * What the top level of a body gets wrong against every alternative its
+ * status describes — nothing, when one of them fits. Named by the field
+ * that tells the alternatives apart, when they have one: the code of an
+ * envelope, compared with the codes the status lists.
+ */
+function shapeProblems(
+  document: OpenApiDocument,
+  status: string,
+  schema: Record<string, unknown>,
+  body: unknown,
+): string[] {
+  const alternatives = alternativesOf(document, schema);
+  const misfits = alternatives.map((alternative) =>
+    misfitOf(alternative, body),
+  );
+
+  if (misfits.some((misfit) => misfit === undefined)) {
+    return [];
+  }
+
+  const field = tellingField(alternatives);
+
+  if (field !== undefined && isRecord(body) && field in body) {
+    const listed: unknown[] = alternatives
+      .map((alternative) => constOf(propertiesOf(alternative)[field]))
+      .filter((value) => value !== undefined);
+
+    if (!listed.includes(body[field])) {
+      return [
+        `${field} ${JSON.stringify(body[field])}, which its ${status} does not list: ${listed.map(String).join(", ")}`,
+      ];
+    }
+  }
+
+  const reasons = [...new Set(misfits)];
+
+  return [
+    reasons.length === 1
+      ? `a body that ${reasons[0]}`
+      : `a body that fits none of the ${alternatives.length} its ${status} describes: ${reasons.join("; ")}`,
+  ];
+}
+
+/** The alternatives a schema stands for, each `$ref` followed. */
+function alternativesOf(
+  document: OpenApiDocument,
+  schema: SchemaView,
+): SchemaView[] {
+  const resolved = resolve(document, schema);
+  const union = resolved.anyOf ?? resolved.oneOf;
+
+  if (Array.isArray(union)) {
+    return union.flatMap((branch) =>
+      isRecord(branch) ? alternativesOf(document, branch) : [],
+    );
+  }
+
+  return [resolved];
+}
+
+function resolve(document: OpenApiDocument, schema: SchemaView): SchemaView {
+  const ref = schema.$ref;
+
+  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
+    return schema;
+  }
+
+  const target =
+    document.components?.schemas?.[ref.slice("#/components/schemas/".length)];
+
+  return isRecord(target) ? target : schema;
+}
+
+/**
+ * How a body fails one alternative at the top level, or `undefined` when
+ * it does not: a required field missing, a `const` field different.
+ */
+function misfitOf(alternative: SchemaView, body: unknown): string | undefined {
+  const properties = propertiesOf(alternative);
+  const required = Array.isArray(alternative.required)
+    ? (alternative.required as string[])
+    : [];
+
+  if (alternative.type === "object" || required.length > 0) {
+    if (!isRecord(body)) {
+      return "is not an object";
+    }
+
+    const missing = required.filter((name) => !(name in body));
+
+    if (missing.length > 0) {
+      return `lacks ${missing.join(", ")}`;
+    }
+
+    for (const [name, property] of Object.entries(properties)) {
+      const expected = constOf(property);
+
+      if (expected !== undefined && name in body && body[name] !== expected) {
+        return `has ${name} ${JSON.stringify(body[name])} where it is ${JSON.stringify(expected)}`;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * The field whose `const` differs from one alternative to the next — the
+ * code of an envelope — or none.
+ */
+function tellingField(alternatives: readonly SchemaView[]): string | undefined {
+  const [first] = alternatives;
+
+  if (first === undefined) {
+    return undefined;
+  }
+
+  return Object.keys(propertiesOf(first)).find(
+    (name) =>
+      name !== "status" &&
+      alternatives.every(
+        (alternative) =>
+          typeof constOf(propertiesOf(alternative)[name]) === "string",
+      ),
+  );
+}
+
+function propertiesOf(schema: SchemaView): Record<string, unknown> {
+  return isRecord(schema.properties) ? schema.properties : {};
+}
+
+function constOf(value: unknown): unknown {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const property: SchemaView = value;
+
+  if ("const" in property) {
+    return property.const;
+  }
+
+  return Array.isArray(property.enum) && property.enum.length === 1
+    ? property.enum[0]
+    : undefined;
+}
+
+/**
+ * A schema that needs nothing but itself: the document's components as its
+ * `$defs`, and every reference into them pointed there — what a validator
+ * that knows JSON Schema and not OpenAPI can compile.
+ */
+function standalone(
+  document: OpenApiDocument,
+  schema: Record<string, unknown>,
+): Record<string, unknown> {
+  const repoint = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      return value.map(repoint);
+    }
+
+    if (!isRecord(value)) {
+      return value;
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, inner]) => [
+        key,
+        key === "$ref" && typeof inner === "string"
+          ? inner.replace("#/components/schemas/", "#/$defs/")
+          : repoint(inner),
+      ]),
+    );
+  };
+
+  return {
+    ...(repoint(schema) as Record<string, unknown>),
+    $defs: repoint(document.components?.schemas ?? {}),
+  };
+}
+
+function headerProblems(
+  status: string,
+  described: ResponseObject,
+  response: Response,
+  names: readonly string[],
+): string[] {
+  const declared = Object.keys(described.headers ?? {}).map((name) =>
+    name.toLowerCase(),
+  );
+
+  return names
+    .filter(
+      (name) =>
+        response.headers.has(name) && !declared.includes(name.toLowerCase()),
+    )
+    .map(
+      (name) => `the header "${name}", which its ${status} does not declare`,
+    );
+}
+
+/**
+ * A schema as this module reads it: any keyword, with the ones it looks
+ * into named, so reading them does not depend on the reader's
+ * `noPropertyAccessFromIndexSignature`.
+ */
+interface SchemaView {
+  readonly $ref?: unknown;
+  readonly anyOf?: unknown;
+  readonly oneOf?: unknown;
+  readonly type?: unknown;
+  readonly required?: unknown;
+  readonly properties?: unknown;
+  readonly const?: unknown;
+  readonly enum?: unknown;
+  readonly [keyword: string]: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}