blume 1.4.3 → 1.5.0

package/src/openapi/model.ts

@@ -1,9 +1,7 @@
-import type {
-  Document,
-  OperationObject,
-  PathItemObject,
-} from "@scalar/openapi-types/3.1";
+import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
 
+import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+import type { ReferenceKind } from "./references.ts";
 import { slugify } from "./references.ts";
 
 // The slug rules live with the reference resolver so operation routes and
@@ -12,8 +10,9 @@ import { slugify } from "./references.ts";
 export { slugify } from "./references.ts";
 
 /**
- * Blume's own OpenAPI model. Specs are parsed and upgraded to 3.1 (see
- * `parse.ts`) with internal `$ref`s left intact — the document stays
+ * Blume's own API reference model, shared by both spec kinds. OpenAPI specs
+ * are parsed and upgraded to 3.1, AsyncAPI specs normalized to 3.x (see
+ * `parse.ts`), with internal `$ref`s left intact — the document stays
  * JSON-serializable (a fully dereferenced graph can be circular), and the schema
  * components resolve refs against `document.components.schemas` at render time.
  * Each operation is flattened into an {@link ApiOperationRef} with a real,
@@ -50,22 +49,26 @@ export const operationKey = (
   return fromId || slugify(`${method}-${path}`);
 };
 
-/** One operation, flattened out of the paths object and mapped to a route. */
+/** One operation, flattened out of its document and mapped to a route. */
 export interface ApiOperationRef {
   /** Stable key, unique within a spec; matches the MDX `<Operation id>`. */
   key: string;
-  method: HttpMethod;
-  /** Templated path, e.g. `/pets/{id}`. */
+  /** HTTP method (OpenAPI) or `send`/`receive` action (AsyncAPI). */
+  method: HttpMethod | AsyncApiAction;
+  /** Templated path, e.g. `/pets/{id}` — or the channel address (AsyncAPI). */
   path: string;
   /** Full site route for this operation's page, e.g. `/reference/pet/add-pet`. */
   route: string;
-  /** Display tag name (first tag, or `Operations` when untagged). */
+  /** Display tag name (first tag; `Operations` or the channel address when untagged). */
   tag: string;
   tagSlug: string;
   summary: string;
   description: string;
+  /** The `operationId` (OpenAPI) or the `operations` map key (AsyncAPI). */
   operationId?: string;
   deprecated: boolean;
+  /** The channel the operation acts on (AsyncAPI only). */
+  channelId?: string;
 }
 
 /** A tag/section, in first-seen order. */
@@ -77,6 +80,8 @@ export interface ApiTagRef {
 
 /** Everything the runtime needs for one spec, serialized into `blume:openapi`. */
 export interface ApiSpecData {
+  /** Which front-end parsed the spec (and which components render it). */
+  kind: ReferenceKind;
   /** Unique token used as the `<Operation source>` and the data-module key. */
   slug: string;
   /** Base route the spec's operations hang off, e.g. `/reference`. */
@@ -85,7 +90,7 @@ export interface ApiSpecData {
   title: string;
   version: string;
   description: string;
-  document: ApiDocument;
+  document: ApiDocument | AsyncApiDocument;
   /** Operations keyed by {@link ApiOperationRef.key}. */
   operations: Record<string, ApiOperationRef>;
   tags: ApiTagRef[];
@@ -98,17 +103,27 @@ export interface ApiSpecData {
 /** The generated `blume:openapi` module: specs keyed by {@link ApiSpecData.slug}. */
 export type OpenApiData = Record<string, ApiSpecData>;
 
-const isOperation = (value: unknown): value is OperationObject =>
-  typeof value === "object" && value !== null;
+// The runtime object check stands guard because the document was parsed from
+// arbitrary YAML/JSON: a spec can put a scalar where the type promises an
+// operation object.
+const isOperation = (
+  value: OperationObject | undefined
+): value is OperationObject => typeof value === "object" && value !== null;
+
+/** A declared tag whose `name` really is a string at runtime, type aside. */
+const hasTagName = (tag: SpecTag): tag is SpecTag =>
+  typeof tag.name === "string";
 
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
  * different names onto one value — any two punctuation-only tags (`!!!`,
  * `???`) both fall through to the `operations` fallback — and a shared slug
  * silently merges the tags' routes, sidebar groups, and overview sections.
- * Collisions gain `-2`, `-3`, … in first-seen order.
+ * Collisions gain `-2`, `-3`, … in first-seen order. Shared with the AsyncAPI
+ * extractor (`asyncapi.ts`), whose untagged fallback groups are channel
+ * addresses.
  */
-const tagSlugger = (): ((name: string) => string) => {
+export const tagSlugger = (): ((name: string) => string) => {
   const assigned = new Map<string, string>();
   const taken = new Set<string>();
   return (name) => {
@@ -127,6 +142,79 @@ const tagSlugger = (): ((name: string) => string) => {
   };
 };
 
+/** An operation before the collector assigns its unique key and route. */
+type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
+
+/** A document's declared tag entry (`tags[n]`). */
+type SpecTag = NonNullable<ApiDocument["tags"]>[number];
+
+/** The flattened output both extractors produce. */
+export interface CollectedOperations {
+  operations: ApiOperationRef[];
+  tags: ApiTagRef[];
+}
+
+/** The collector handle: feed operations in, read the flattened output out. */
+export interface OperationCollector {
+  add: (entry: CollectedOperation) => void;
+  finish: () => CollectedOperations;
+}
+
+/** {@link CollectedOperations} plus anything the extractor had to skip. */
+export interface ExtractedOperations extends CollectedOperations {
+  warnings: string[];
+}
+
+/**
+ * The collector behind both extractors (OpenAPI here, AsyncAPI in
+ * `asyncapi.ts`): first-seen tag ordering, key de-duplication (a repeated key
+ * gains its method/action as a suffix), and the shared route template — so
+ * URL shape and slug rules can never drift between the two spec kinds.
+ */
+export const operationCollector = (
+  baseRoute: string,
+  tagMeta: ReadonlyMap<string, string>
+): OperationCollector => {
+  const operations: ApiOperationRef[] = [];
+  const tagOrder: string[] = [];
+  const tagsSeen = new Set<string>();
+  const seen = new Set<string>();
+  const slugForTag = tagSlugger();
+
+  const add = (entry: CollectedOperation): void => {
+    const tagSlug = slugForTag(entry.tag);
+    if (!tagsSeen.has(entry.tag)) {
+      tagsSeen.add(entry.tag);
+      tagOrder.push(entry.tag);
+    }
+    let { key } = entry;
+    while (seen.has(key)) {
+      key = `${key}-${entry.method}`;
+    }
+    seen.add(key);
+    operations.push({
+      ...entry,
+      key,
+      // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
+      route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
+      tagSlug,
+    });
+  };
+
+  const finish = (): CollectedOperations => ({
+    operations,
+    tags: tagOrder.map((name) => ({
+      description: tagMeta.get(name) ?? "",
+      name,
+      // The same slugger instance, so every tag resolves to the slug its
+      // operations were routed under.
+      slug: slugForTag(name),
+    })),
+  });
+
+  return { add, finish };
+};
+
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
@@ -136,19 +224,17 @@ const tagSlugger = (): ((name: string) => string) => {
 export const extractOperations = (
   document: ApiDocument,
   baseRoute: string
-): { operations: ApiOperationRef[]; tags: ApiTagRef[]; warnings: string[] } => {
-  const operations: ApiOperationRef[] = [];
-  const tagOrder: string[] = [];
-  const tagsSeen = new Set<string>();
+): ExtractedOperations => {
+  const warnings: string[] = [];
   const tagMeta = new Map(
-    (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
+    (document.tags ?? [])
+      .filter(hasTagName)
+      .map((tag) => [tag.name, tag.description ?? ""])
   );
-  const seen = new Set<string>();
-  const warnings: string[] = [];
-  const slugForTag = tagSlugger();
+  const collector = operationCollector(baseRoute, tagMeta);
 
-  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
-    const item = rawItem as PathItemObject | undefined;
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    // A parsed spec can carry a null path item despite the type; skip it.
     if (!item) {
       continue;
     }
@@ -163,52 +249,35 @@ export const extractOperations = (
       if (!isOperation(operation)) {
         continue;
       }
-      const tag = operation.tags?.[0] ?? UNTAGGED;
-      const tagSlug = slugForTag(tag);
-      if (!tagsSeen.has(tag)) {
-        tagsSeen.add(tag);
-        tagOrder.push(tag);
-      }
-      let key = operationKey(method, path, operation.operationId);
-      while (seen.has(key)) {
-        key = `${key}-${method}`;
-      }
-      seen.add(key);
-      operations.push({
+      collector.add({
         deprecated: operation.deprecated ?? false,
         description: operation.description ?? "",
-        key,
+        key: operationKey(method, path, operation.operationId),
         method,
         operationId: operation.operationId,
         path,
-        // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
-        route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
         summary: operation.summary ?? "",
-        tag,
-        tagSlug,
+        tag: operation.tags?.[0] ?? UNTAGGED,
       });
     }
   }
 
-  const tags: ApiTagRef[] = tagOrder.map((name) => ({
-    description: tagMeta.get(name) ?? "",
-    name,
-    // The same slugger instance, so every tag resolves to the slug its
-    // operations were routed under.
-    slug: slugForTag(name),
-  }));
-
-  return { operations, tags, warnings };
+  return { ...collector.finish(), warnings };
 };
 
-/** Resolve the operation object for a ref out of its document. */
+/** Resolve the operation object for a ref out of its (OpenAPI) document. */
 export const operationObject = (
   spec: ApiSpecData,
   ref: ApiOperationRef
 ): OperationObject | undefined => {
-  const item = (spec.document.paths?.[ref.path] ?? undefined) as
-    | PathItemObject
-    | undefined;
-  const operation = item?.[ref.method];
+  // Only OpenAPI refs carry HTTP methods; the AsyncAPI counterpart is
+  // `asyncApiOperationObject` in `asyncapi.ts`.
+  const method = HTTP_METHODS.find((candidate) => candidate === ref.method);
+  // SAFETY: only OpenAPI specs route their refs through this resolver
+  // (AsyncAPI documents go to `asyncApiOperationObject`), so the spec's
+  // document is the OpenAPI shape.
+  const document = spec.document as ApiDocument;
+  const item = document.paths?.[ref.path];
+  const operation = method === undefined ? undefined : item?.[method];
   return isOperation(operation) ? operation : undefined;
 };

package/src/openapi/parse.ts

@@ -1,11 +1,15 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 
+import type { AsyncAPIDocument as ConverterDocument } from "@asyncapi/converter";
+import { convert } from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
 import { isAbsolute, join } from "pathe";
 
 import { hashText } from "../core/sources/cache.ts";
+import type { AsyncApiDocument } from "./asyncapi.ts";
+import { normalizeAsyncApiDocument } from "./asyncapi.ts";
 import type { ApiDocument } from "./model.ts";
 
 /**
@@ -192,6 +196,8 @@ const fetchSpecText = async (spec: string): Promise<string> => {
       // stacking on it: p-retry's own (capped) delay still runs after this
       // hook, so only the difference is slept here.
       onFailedAttempt: async (context) => {
+        // SAFETY: every retryable throw above is a RetryableFetchError; any
+        // other error reaching this hook reads an absent retryAfter.
         const { retryAfter } = context.error as RetryableFetchError;
         if (retryAfter !== undefined && context.retriesLeft > 0) {
           await sleep(
@@ -265,6 +271,8 @@ const readSpecText = async (
     if (cacheFile) {
       const cached = await readCache(cacheFile);
       if (cached !== undefined) {
+        // SAFETY: fetchSpecText throws only Error instances — attemptFetch
+        // wraps every non-Error throw in an Error.
         return {
           text: cached,
           warnings: [
@@ -283,6 +291,14 @@ const readSpecText = async (
  * diagnostic (an error in build, a warning in dev) rather than a hard failure so
  * a broken spec doesn't take down the whole build.
  */
+/**
+ * A parsed mapping is the only shape the renderer can treat as a document:
+ * `normalize` yields undefined for anything that isn't a YAML/JSON mapping
+ * (empty file, scalar, list) and `upgrade(undefined)` a null specification.
+ */
+const isApiDocument = <Value>(value: Value): value is Value & ApiDocument =>
+  typeof value === "object" && value !== null;
+
 export const parseSpec = async (
   spec: string,
   root: string,
@@ -291,13 +307,89 @@ export const parseSpec = async (
   const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize(text);
   const { specification } = upgrade(normalized);
-  // `normalize` yields undefined for anything that isn't a YAML/JSON mapping
-  // (empty file, scalar, list) and `upgrade(undefined)` yields a null
-  // specification — reject it here so the renderer never sees a non-document.
-  if (specification === null || typeof specification !== "object") {
+  // Reject a non-mapping here so the renderer never sees a non-document.
+  if (!isApiDocument(specification)) {
     throw new InvalidSpecError(
       `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
     );
   }
-  return { document: specification as ApiDocument, warnings };
+  return { document: specification, warnings };
+};
+
+export interface ParsedAsyncApiSpec {
+  document: AsyncApiDocument;
+  warnings: string[];
+}
+
+/**
+ * Read and normalize a spec to an AsyncAPI 3.x document — the AsyncAPI mirror
+ * of {@link parseSpec}. 1.x/2.x documents are lifted to 3.0 with the official
+ * `@asyncapi/converter` (channels + operations with `send`/`receive` actions),
+ * so the extractor and components only ever handle one shape; `$ref`s stay
+ * intact, matching the OpenAPI path. Error semantics match `parseSpec`: an
+ * unreadable spec throws, a readable non-AsyncAPI document throws
+ * {@link InvalidSpecError}, and callers lower both into source diagnostics.
+ */
+/**
+ * An object carrying a non-empty `asyncapi` version string — the only input
+ * the converter and extractor can key on. `normalize` yields undefined for
+ * non-mapping input, which fails the object check here.
+ */
+const isAsyncApiDocument = <Value>(
+  value: Value
+): value is Value & AsyncApiDocument & { asyncapi: string } =>
+  typeof value === "object" &&
+  value !== null &&
+  "asyncapi" in value &&
+  typeof value.asyncapi === "string" &&
+  value.asyncapi !== "";
+
+export const parseAsyncApiSpec = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions = {}
+): Promise<ParsedAsyncApiSpec> => {
+  const { text, warnings } = await readSpecText(spec, root, options);
+  const normalized = normalize(text);
+  if (!isAsyncApiDocument(normalized)) {
+    throw new InvalidSpecError(
+      `${spec} is not a valid AsyncAPI document (expected a YAML or JSON object with an \`asyncapi\` version field).`
+    );
+  }
+  const version = normalized.asyncapi;
+  let document: AsyncApiDocument = normalized;
+  if (!version.startsWith("3.")) {
+    // The converter reports lossy conversions (e.g. a 2.x parameter schema
+    // that 3.0 can't express) through console.warn — capture those as spec
+    // warnings instead of letting them leak into CLI output.
+    const captured: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => {
+      captured.push(args.map(String).join(" "));
+    };
+    try {
+      // SAFETY: the converter accepts any pre-3.0 AsyncAPI object and returns
+      // the 3.0 shape the extractor consumes; the two packages just declare
+      // the document type differently.
+      document = convert(
+        document as ConverterDocument,
+        "3.0.0"
+      ) as AsyncApiDocument;
+    } catch (error) {
+      // An unconvertible document (say, an unknown `asyncapi` version) is a
+      // content problem, not a network one — same class as a non-document.
+      // SAFETY: @asyncapi/converter throws Error instances for bad input.
+      throw new InvalidSpecError(
+        `${spec} could not be converted to AsyncAPI 3.0 (${(error as Error).message}).`
+      );
+    } finally {
+      console.warn = originalWarn;
+    }
+    warnings.push(
+      ...captured.map(
+        (message) => `Converting ${spec} to AsyncAPI 3.0: ${message}`
+      )
+    );
+  }
+  return { document: normalizeAsyncApiDocument(document), warnings };
 };

package/src/openapi/references.ts

@@ -54,9 +54,10 @@ export interface ReferenceSource {
   theme?: string;
   /**
    * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
-   * only). Takes precedence over Blume's derived spec/theme config.
+   * only). Takes precedence over Blume's derived spec/theme config. Typed off
+   * the config schema so the two can never drift.
    */
-  scalar?: Record<string, unknown>;
+  scalar?: ResolvedConfig["openapi"]["scalar"];
   /** Display options carried through to the Blume renderer. */
   display: ReferenceDisplay;
   /**
@@ -174,11 +175,9 @@ const referencesFor = (
   });
 };
 
-const NO_DISPLAY: ReferenceDisplay = { codeSamples: [], expandSchemas: false };
-
 /**
- * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
- * by default); AsyncAPI is always rendered by Scalar for now.
+ * Resolve every enabled reference. Both blocks honor their `renderer` —
+ * Blume's own UI by default, with the embedded Scalar SPA as the opt-out.
  */
 export const resolveReferences = (
   config: ResolvedConfig
@@ -198,8 +197,11 @@ export const resolveReferences = (
     "asyncapi",
     config.asyncapi,
     "Events",
-    "scalar",
-    NO_DISPLAY,
+    config.asyncapi.renderer,
+    {
+      codeSamples: config.asyncapi.codeSamples,
+      expandSchemas: config.asyncapi.expandSchemas,
+    },
     config.basePath
   ),
 ];
@@ -232,7 +234,7 @@ const blumeReferenceOf = (
   seen: Map<string, ReferenceSource>,
   usedSlugs: Set<string>
 ): ReferenceSource | null => {
-  if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+  if (ref.renderer !== "blume") {
     return null;
   }
   const kept = seen.get(ref.route);
@@ -260,7 +262,7 @@ const blumeReferenceOf = (
   return accepted;
 };
 
-/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+/** Blume-rendered references (both kinds), deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
   const seen = new Map<string, ReferenceSource>();
   const usedSlugs = new Set<string>();

package/src/openapi/render-mdx.ts

@@ -1,7 +1,9 @@
 import type { Nodes } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
+import stringWidth from "string-width";
 
+import { columnsPrefix } from "../core/text-width.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -22,18 +24,18 @@ import type { ReferenceSource } from "./references.ts";
 // deliberately not escaped: it isn't MDX-special on its own, and escaping it
 // turns a `> Note:` blockquote into literal "> Note:" text.
 const MDX_UNSAFE = /[<{}]/gu;
-const ENTITIES: Record<string, string> = {
-  "<": "&lt;",
-  "{": "&#123;",
-  "}": "&#125;",
-};
+const ENTITIES = new Map([
+  ["<", "&lt;"],
+  ["{", "&#123;"],
+  ["}", "&#125;"],
+]);
 // MDX also parses lines starting with `import`/`export` as ESM ("import the
 // SDK…" is common spec prose). Entity-escape the keyword's first letter so the
 // construct can't match; it still renders as the literal word.
 const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
 const escapeProse = (text: string): string =>
   text
-    .replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char)
+    .replace(MDX_UNSAFE, (char) => ENTITIES.get(char) ?? char)
     .replace(
       MDX_ESM_KEYWORD,
       (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`
@@ -94,9 +96,23 @@ const mdxSafe = (text: string): string => {
   return out + escapeProse(text.slice(cursor));
 };
 
+/**
+ * Frontmatter emitted for one operation or overview page. Boolean flags are
+ * assigned only when set, so absent keys stay absent in the staged MDX.
+ */
+export interface RenderedPageData {
+  ai?: { exclude: boolean };
+  deprecated?: boolean;
+  search?: { exclude?: boolean; tags?: string[] };
+  seo: { description: string; noindex?: boolean };
+  sidebar: { badge?: string; label: string };
+  title: string;
+  type?: string;
+}
+
 /** Frontmatter + body for one operation or overview page. */
 export interface RenderedPage {
-  data: Record<string, unknown>;
+  data: RenderedPageData;
   body: string;
 }
 
@@ -123,19 +139,19 @@ const plainProse = (markdown: string): string => {
   return first ? mdastToString(first).replace(WHITESPACE, " ").trim() : "";
 };
 
-/** Cap `text` at `max` characters, cutting on a word boundary. */
+/** Cap `text` at `max` display columns, cutting on a word boundary. */
 const clip = (text: string, max: number): string => {
   if (max <= 0) {
     return "";
   }
-  if (text.length <= max) {
+  if (stringWidth(text) <= max) {
     return text;
   }
-  const head = text.slice(0, max - 1);
+  const head = columnsPrefix(text, max - 1);
   const onWordBoundary = head.replace(TRAILING_WORD, "");
   // One very long token — an endpoint path has no spaces — would be dropped
   // whole, leaving a stub. Hard-cut it instead of losing it.
-  return `${onWordBoundary.length >= max / 2 ? onWordBoundary : head}…`;
+  return `${stringWidth(onWordBoundary) >= max / 2 ? onWordBoundary : head}…`;
 };
 
 const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
@@ -149,11 +165,14 @@ const operationDescription = (
   spec: ApiSpecData,
   operation: ApiOperationRef
 ): string => {
-  const endpoint = `${operation.method.toUpperCase()} ${operation.path}`;
-  const suffix = `Reference for the ${endpoint} endpoint in the ${apiName(spec)} API.`;
+  // AsyncAPI operations act on a channel, not an HTTP endpoint.
+  const suffix =
+    spec.kind === "asyncapi"
+      ? `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`
+      : `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
   const prose = clip(
     plainProse(operation.description || operation.summary),
-    META_DESCRIPTION_MAX - suffix.length - 1
+    META_DESCRIPTION_MAX - stringWidth(suffix) - 1
   );
   return clip([prose, suffix].filter(Boolean).join(" "), META_DESCRIPTION_MAX);
 };
@@ -180,22 +199,35 @@ export const operationMdx = (
     operation.description.trim() === operation.summary.trim()
       ? ""
       : operation.description;
+  const flags: Pick<RenderedPageData, "ai" | "deprecated"> = {};
+  if (reference?.includeInLlms === false) {
+    flags.ai = { exclude: true };
+  }
+  if (operation.deprecated) {
+    flags.deprecated = true;
+  }
+  const searchFlags: Pick<
+    NonNullable<RenderedPageData["search"]>,
+    "exclude"
+  > = {};
+  if (reference?.includeInSearch === false) {
+    searchFlags.exclude = true;
+  }
+  const seo: RenderedPageData["seo"] = {
+    description: operationDescription(spec, operation),
+  };
+  if (reference?.noindex) {
+    seo.noindex = true;
+  }
   return {
     body: withDescription(
       description,
       `<Operation source="${spec.slug}" id="${operation.key}" />`
     ),
     data: {
-      ...(reference?.includeInLlms === false ? { ai: { exclude: true } } : {}),
-      ...(operation.deprecated ? { deprecated: true } : {}),
-      search: {
-        ...(reference?.includeInSearch === false ? { exclude: true } : {}),
-        tags: [operation.tag, method],
-      },
-      seo: {
-        description: operationDescription(spec, operation),
-        ...(reference?.noindex ? { noindex: true } : {}),
-      },
+      ...flags,
+      search: { ...searchFlags, tags: [operation.tag, method] },
+      seo,
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
@@ -253,6 +285,21 @@ export const overviewMdx = (
       ].join("\n\n")
     );
   }
+  const flags: Pick<RenderedPageData, "ai" | "search"> = {};
+  if (reference?.includeInLlms === false) {
+    flags.ai = { exclude: true };
+  }
+  if (reference?.includeInSearch === false) {
+    flags.search = { exclude: true };
+  }
+  const seo: RenderedPageData["seo"] = {
+    description:
+      clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
+      `${apiName(spec)} API reference.`,
+  };
+  if (reference?.noindex) {
+    seo.noindex = true;
+  }
   return {
     body: [
       withDescription(
@@ -262,16 +309,8 @@ export const overviewMdx = (
       ...tagSections,
     ].join("\n\n"),
     data: {
-      ...(reference?.includeInLlms === false ? { ai: { exclude: true } } : {}),
-      ...(reference?.includeInSearch === false
-        ? { search: { exclude: true } }
-        : {}),
-      seo: {
-        description:
-          clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
-          `${apiName(spec)} API reference.`,
-        ...(reference?.noindex ? { noindex: true } : {}),
-      },
+      ...flags,
+      seo,
       sidebar: { label: "Overview" },
       title: apiName(spec),
     },