@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/app/docs/screens/docs/http/model.ts

@@ -0,0 +1,604 @@
+import type { SpecDocument } from "../../../api/docs";
+import { DEFAULT_EXTENSION_PREFIXES } from "../../../../../lib/docs/browser/config.ts";
+import { deref, isSchemaObject, refOf, resolveRef } from "../schema/resolve";
+
+/**
+ * The parts of an OpenAPI 3.1 document the HTTP reference renders, read out
+ * of the JSON into plain records. Everything is defensive: the document is
+ * data from the API, and a field of the wrong shape is skipped rather than
+ * trusted.
+ *
+ * The extensions are vendor-neutral: each is named on its node as
+ * `<prefix>-<name>` (`x-bun-jobs-action`, `x-bun-common-csrf`, …) and read
+ * from the first prefix of {@link HttpModelOptions.extensions} that carries
+ * it; one under any other prefix is ignored.
+ */
+
+/** Options of {@link listOperations}. */
+export interface HttpModelOptions {
+  /**
+   * The extension prefixes, first hit winning. Defaults to
+   * `["x-bun-common", "x-bun-jobs"]`.
+   */
+  extensions?: readonly string[];
+}
+
+/** Reads the `<prefix>-<name>` extension of a node from the first prefix carrying it. */
+function extensionOf(
+  node: Record<string, unknown>,
+  name: string,
+  prefixes: readonly string[],
+): unknown {
+  for (const prefix of prefixes) {
+    const key = `${prefix}-${name}`;
+    if (Object.hasOwn(node, key)) {
+      return node[key];
+    }
+  }
+  return undefined;
+}
+
+/** Path item keys that are operations, in the order OpenAPI lists them. */
+const OPERATION_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+] as const;
+
+/** Where a parameter goes. */
+export type ParameterLocation = "path" | "query" | "header" | "cookie";
+
+/** One parameter of an operation. */
+export interface DocParameter {
+  /** Its name. */
+  name: string;
+  /** Where it goes. */
+  in: ParameterLocation;
+  /** Whether it must be sent (path parameters always are). */
+  required: boolean;
+  /** What it means. */
+  description?: string;
+  /** Its schema (possibly a `$ref`). */
+  schema: unknown;
+  /** OpenAPI `style` (`form` for the API's array query parameters). */
+  style?: string;
+  /** OpenAPI `explode`: `true` sends an array as repeated keys. */
+  explode?: boolean;
+  /** Whether it is deprecated. */
+  deprecated: boolean;
+}
+
+/** One media type of a body. */
+export interface DocMediaType {
+  /** E.g. `application/json`. */
+  contentType: string;
+  /** Its schema, when it declares one. */
+  schema: unknown;
+}
+
+/** An operation's request body. */
+export interface DocRequestBody {
+  /** Whether a body must be sent. */
+  required: boolean;
+  /** A note, e.g. that `Content-Type: application/json` is required even when bodiless. */
+  description?: string;
+  /** The media types accepted. */
+  content: DocMediaType[];
+}
+
+/** One documented response. */
+export interface DocResponse {
+  /** `"200"`, `"404"`, `"default"`, `"4XX"`. */
+  status: string;
+  /** What it means (for a problem: the titles of its codes). */
+  description: string;
+  /** Its bodies. */
+  content: DocMediaType[];
+  /** `<prefix>-codes`: the problem codes answered with this status. */
+  codes: string[];
+  /** The `$ref` it came from (`#/components/responses/Problem`), if any. */
+  ref?: string;
+}
+
+/** `<prefix>-csrf`: what a mutation must carry. */
+export interface DocCsrf {
+  /** The header every mutation must carry (any non-empty value), or `null` when none is required. */
+  header: string | null;
+  /** Whether `Content-Type: application/json` is required, even without a body. */
+  requireJson: boolean;
+}
+
+/** One operation, flattened. */
+export interface DocOperation {
+  /** `operationId` (or `METHOD path` when the document gives none). */
+  id: string;
+  /** Upper-case method. */
+  method: string;
+  /** The path template, relative to the server (`/queues/{queue}`). */
+  path: string;
+  /** One line. */
+  summary?: string;
+  /** More. */
+  description?: string;
+  /** Its tags. */
+  tags: string[];
+  /** Whether it is deprecated. */
+  deprecated: boolean;
+  /** Path-item and operation parameters, operation ones winning. */
+  parameters: DocParameter[];
+  /** The body it takes. */
+  requestBody?: DocRequestBody;
+  /** Its responses, in document order. */
+  responses: DocResponse[];
+  /** `<prefix>-action`: the permission the operation needs. */
+  action?: string;
+  /** `<prefix>-mutation`: whether it changes state (CSRF checks, refused when read-only). */
+  mutation: boolean;
+  /** `<prefix>-requires`: the driver methods it needs. */
+  requires: string[];
+  /** `<prefix>-csrf`, on mutations when CSRF checks are on. */
+  csrf?: DocCsrf;
+}
+
+/** One tag, with the operations under it. */
+export interface DocTagGroup {
+  /** The tag's name. */
+  name: string;
+  /** What it covers. */
+  description?: string;
+  /** Its operations, in document order. */
+  operations: DocOperation[];
+}
+
+/** One server entry. */
+export interface DocServer {
+  /** Its URL, often relative (`/jobs-api`). */
+  url: string;
+  /** A note. */
+  description?: string;
+}
+
+/** The document's header. */
+export interface DocInfo {
+  /** `openapi`, e.g. `3.1.0`. */
+  openapi: string;
+  /** The API's title. */
+  title: string;
+  /** Its version. */
+  version: string;
+  /** What it is. */
+  description?: string;
+  /** Where it is served. */
+  servers: DocServer[];
+}
+
+/** A string field, or `undefined`. */
+function text(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** A string array field, or `[]`. */
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+/** Follows a `$ref` to a component (a parameter, a response, a body), one level of indirection at a time. */
+function component(
+  doc: SpecDocument,
+  value: unknown,
+): { node: Record<string, unknown> | undefined; ref?: string } {
+  const ref = refOf(value);
+  if (ref === undefined) {
+    return { node: isSchemaObject(value) ? value : undefined };
+  }
+  const target = deref(value, doc).schema;
+  return { node: isSchemaObject(target) ? target : undefined, ref };
+}
+
+/** The media types of a `content` map. */
+function mediaTypes(value: unknown): DocMediaType[] {
+  if (!isSchemaObject(value)) {
+    return [];
+  }
+  return Object.entries(value).map(([contentType, media]) => ({
+    contentType,
+    schema: isSchemaObject(media) ? media.schema : undefined,
+  }));
+}
+
+/** Reads one parameter. */
+function readParameter(
+  doc: SpecDocument,
+  raw: unknown,
+): DocParameter | undefined {
+  const { node } = component(doc, raw);
+  const name = text(node?.name);
+  const location = text(node?.in);
+  if (
+    !node ||
+    name === undefined ||
+    (location !== "path" &&
+      location !== "query" &&
+      location !== "header" &&
+      location !== "cookie")
+  ) {
+    return undefined;
+  }
+  return {
+    name,
+    in: location,
+    required: location === "path" || node.required === true,
+    description: text(node.description),
+    schema: node.schema,
+    style: text(node.style),
+    explode: typeof node.explode === "boolean" ? node.explode : undefined,
+    deprecated: node.deprecated === true,
+  };
+}
+
+/** Reads the `<prefix>-csrf` extension. */
+function readCsrf(value: unknown): DocCsrf | undefined {
+  if (!isSchemaObject(value)) {
+    return undefined;
+  }
+  return {
+    header: text(value.header) ?? null,
+    requireJson: value.requireJson === true,
+  };
+}
+
+/** Reads one operation of a path item. */
+function readOperation(
+  doc: SpecDocument,
+  path: string,
+  method: string,
+  raw: Record<string, unknown>,
+  shared: unknown[],
+  prefixes: readonly string[],
+): DocOperation {
+  const parameters = new Map<string, DocParameter>();
+  for (const item of [
+    ...shared,
+    ...(Array.isArray(raw.parameters) ? raw.parameters : []),
+  ]) {
+    const parameter = readParameter(doc, item);
+    if (parameter) {
+      parameters.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+  }
+  const body = component(doc, raw.requestBody).node;
+  const responses: DocResponse[] = [];
+  if (isSchemaObject(raw.responses)) {
+    for (const [status, value] of Object.entries(raw.responses)) {
+      const { node, ref } = component(doc, value);
+      responses.push({
+        status,
+        description: text(node?.description) ?? "",
+        content: mediaTypes(node?.content),
+        codes: strings(
+          node === undefined ? undefined : extensionOf(node, "codes", prefixes),
+        ),
+        ...(ref ? { ref } : {}),
+      });
+    }
+  }
+  return {
+    id: text(raw.operationId) ?? `${method.toUpperCase()} ${path}`,
+    method: method.toUpperCase(),
+    path,
+    summary: text(raw.summary),
+    description: text(raw.description),
+    tags: strings(raw.tags),
+    deprecated: raw.deprecated === true,
+    parameters: [...parameters.values()],
+    requestBody: body
+      ? {
+          required: body.required === true,
+          description: text(body.description),
+          content: mediaTypes(body.content),
+        }
+      : undefined,
+    responses,
+    action: text(extensionOf(raw, "action", prefixes)),
+    mutation: extensionOf(raw, "mutation", prefixes) === true,
+    requires: strings(extensionOf(raw, "requires", prefixes)),
+    csrf: readCsrf(extensionOf(raw, "csrf", prefixes)),
+  };
+}
+
+/** Every operation of the document, in path order and, within a path, method order. */
+export function listOperations(
+  doc: SpecDocument,
+  options: HttpModelOptions = {},
+): DocOperation[] {
+  const prefixes = options.extensions ?? DEFAULT_EXTENSION_PREFIXES;
+  const operations: DocOperation[] = [];
+  if (!isSchemaObject(doc.paths)) {
+    return operations;
+  }
+  for (const [path, item] of Object.entries(doc.paths)) {
+    const pathItem = component(doc, item).node;
+    if (!pathItem) {
+      continue;
+    }
+    const shared = Array.isArray(pathItem.parameters)
+      ? pathItem.parameters
+      : [];
+    for (const method of OPERATION_METHODS) {
+      const raw = pathItem[method];
+      if (isSchemaObject(raw)) {
+        operations.push(
+          readOperation(doc, path, method, raw, shared, prefixes),
+        );
+      }
+    }
+  }
+  return operations;
+}
+
+/** The document's header: title, version, description, servers. */
+export function readInfo(doc: SpecDocument): DocInfo {
+  const info = isSchemaObject(doc.info) ? doc.info : {};
+  const servers = Array.isArray(doc.servers)
+    ? doc.servers.flatMap((server): DocServer[] => {
+        const url = isSchemaObject(server) ? text(server.url) : undefined;
+        return url === undefined
+          ? []
+          : [
+              {
+                url,
+                description: text(
+                  (server as Record<string, unknown>).description,
+                ),
+              },
+            ];
+      })
+    : [];
+  return {
+    openapi: text(doc.openapi) ?? "",
+    title: text(info.title) ?? "API",
+    version: text(info.version) ?? "",
+    description: text(info.description),
+    servers: servers.length > 0 ? servers : [{ url: "/" }],
+  };
+}
+
+/**
+ * Operations by tag, in the document's `tags` order; tags an operation uses
+ * but the list omits follow in first-use order, then `Other` for untagged
+ * operations. An operation with two tags is listed under both.
+ */
+export function groupByTag(
+  doc: SpecDocument,
+  operations: readonly DocOperation[],
+): DocTagGroup[] {
+  const groups = new Map<string, DocTagGroup>();
+  if (Array.isArray(doc.tags)) {
+    for (const tag of doc.tags) {
+      const name = isSchemaObject(tag) ? text(tag.name) : undefined;
+      if (name !== undefined && !groups.has(name)) {
+        groups.set(name, {
+          name,
+          description: text((tag as Record<string, unknown>).description),
+          operations: [],
+        });
+      }
+    }
+  }
+  const other: DocOperation[] = [];
+  for (const operation of operations) {
+    if (operation.tags.length === 0) {
+      other.push(operation);
+    }
+    for (const tag of operation.tags) {
+      let group = groups.get(tag);
+      if (!group) {
+        group = { name: tag, operations: [] };
+        groups.set(tag, group);
+      }
+      group.operations.push(operation);
+    }
+  }
+  const result = [...groups.values()].filter(
+    (group) => group.operations.length > 0,
+  );
+  if (other.length > 0) {
+    result.push({ name: "Other", operations: other });
+  }
+  return result;
+}
+
+/** One section of the sidebar: a document's `x-tagGroups` entry, over the tags it names. */
+export interface DocSection {
+  /** The section's name. */
+  name: string;
+  /** Its tags with their operations, in the section's order. */
+  tags: DocTagGroup[];
+}
+
+/** A section with a React key unique among its siblings, and its position. */
+export interface KeyedSection {
+  /** Its name, suffixed `#2`, `#3`… when a hand-written document repeats one. */
+  key: string;
+  /** Its position in the document's order (for heading ids). */
+  index: number;
+  /** The section. */
+  section: DocSection;
+}
+
+/**
+ * Keys `sections` for rendering: two sections may share a name in a
+ * hand-written document, so the name alone is not a key, and a position is
+ * not a stable one (`react/no-array-index-key`).
+ */
+export function keyedSections(sections: readonly DocSection[]): KeyedSection[] {
+  const seen = new Map<string, number>();
+  return sections.map((section, index) => {
+    const count = (seen.get(section.name) ?? 0) + 1;
+    seen.set(section.name, count);
+    return {
+      key: count === 1 ? section.name : `${section.name}#${count}`,
+      index,
+      section,
+    };
+  });
+}
+
+/** The section the tags no `x-tagGroups` entry names go in. */
+const OTHER_SECTION = "Other";
+
+/**
+ * The document's sections (`x-tagGroups`, Redoc's and Scalar's shape: `[{
+ * name, tags }]`, the one bun-common's `generateOpenApi({ tagGroups })`
+ * emits), each over its tags' groups, in the document's order; `undefined`
+ * when the document declares none, so the sidebar stays one level deep. A
+ * malformed entry is skipped, and a list with none well formed reads as none.
+ *
+ * Unlike Redoc, nothing is hidden: a group no section names (`Other`, the
+ * untagged operations, among them) follows in a trailing `Other` section, or
+ * in the document's section of that name when it has one. A tag in two
+ * sections is listed in each; a section with no group (a search left none)
+ * is dropped.
+ */
+export function groupBySection(
+  doc: SpecDocument,
+  groups: readonly DocTagGroup[],
+): DocSection[] | undefined {
+  const raw = doc["x-tagGroups"];
+  if (!Array.isArray(raw)) {
+    return undefined;
+  }
+  const declared = raw.flatMap(
+    (entry: unknown): { name: string; tags: string[] }[] => {
+      if (!isSchemaObject(entry)) {
+        return [];
+      }
+      const name = text(entry.name);
+      return name === undefined || !Array.isArray(entry.tags)
+        ? []
+        : [{ name, tags: strings(entry.tags) }];
+    },
+  );
+  if (declared.length === 0) {
+    return undefined;
+  }
+  const byName = new Map(groups.map((group) => [group.name, group]));
+  const named = new Set<string>();
+  const sections: DocSection[] = [];
+  for (const { name, tags } of declared) {
+    const section: DocSection = { name, tags: [] };
+    for (const tag of tags) {
+      const group = byName.get(tag);
+      if (group && !section.tags.includes(group)) {
+        section.tags.push(group);
+        named.add(tag);
+      }
+    }
+    sections.push(section);
+  }
+  const rest = groups.filter((group) => !named.has(group.name));
+  if (rest.length > 0) {
+    const other = sections.find((section) => section.name === OTHER_SECTION);
+    if (other) {
+      other.tags.push(...rest);
+    } else {
+      sections.push({ name: OTHER_SECTION, tags: rest });
+    }
+  }
+  return sections.filter((section) => section.tags.length > 0);
+}
+
+/**
+ * Whether an operation matches a search: every whitespace-separated term
+ * must appear, ignoring case, in its path, id, summary, method or action.
+ */
+export function matchesSearch(operation: DocOperation, query: string): boolean {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) {
+    return true;
+  }
+  const haystack = [
+    operation.method,
+    operation.path,
+    operation.id,
+    operation.summary ?? "",
+    operation.action ?? "",
+  ]
+    .join(" ")
+    .toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+/** Groups filtered by a search; groups left empty are dropped. */
+export function filterGroups(
+  groups: readonly DocTagGroup[],
+  query: string,
+): DocTagGroup[] {
+  return groups
+    .map((group) => ({
+      ...group,
+      operations: group.operations.filter((operation) =>
+        matchesSearch(operation, query),
+      ),
+    }))
+    .filter((group) => group.operations.length > 0);
+}
+
+/**
+ * A server URL as the reader can use it: a relative one (`/jobs-api`, the
+ * API's default) is resolved against the origin the app talks to — the API
+ * base's own origin when it is absolute, else the page's.
+ */
+export function resolveServerUrl(
+  url: string,
+  apiBase: string,
+  pageOrigin: string,
+): string {
+  const origin = /^https?:\/\//.test(apiBase)
+    ? new URL(apiBase).origin
+    : pageOrigin;
+  try {
+    return new URL(url, `${origin}/`).href.replace(/\/$/, "");
+  } catch {
+    return url;
+  }
+}
+
+/** The named component schemas, sorted as the document lists them. */
+export function componentSchemaNames(doc: SpecDocument): string[] {
+  const schemas = resolveRef(doc, "#/components/schemas");
+  return isSchemaObject(schemas) ? Object.keys(schemas) : [];
+}
+
+/** The tone a method badge takes. */
+export function methodTone(
+  method: string,
+): "info" | "success" | "warning" | "danger" | "neutral" {
+  switch (method) {
+    case "GET":
+      return "info";
+    case "POST":
+      return "success";
+    case "PUT":
+    case "PATCH":
+      return "warning";
+    case "DELETE":
+      return "danger";
+    default:
+      return "neutral";
+  }
+}
+
+/** The success responses (2xx): the note try-it shows when the status it received is not documented. */
+export function successStatuses(operation: DocOperation): string[] {
+  return operation.responses
+    .map((response) => response.status)
+    .filter((status) => /^2\d\d$/.test(status));
+}