blume 1.4.2 → 1.5.0

package/src/openapi/parse.ts

@@ -1,10 +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";
 
 /**
@@ -95,13 +100,23 @@ const ensureProxyDispatcher = async (): Promise<void> => {
   }
 };
 
-/** `Retry-After` in ms when the server sent a sane one, else undefined. */
+/**
+ * `Retry-After` in ms when the server sent a sane one, else undefined. RFC
+ * 9110 allows both forms: delta-seconds (`120`) and an HTTP-date (`Wed, 21
+ * Oct 2015 07:28:00 GMT`); the date form arrives from CDN rate limiters and
+ * was previously ignored.
+ */
 const retryAfterMs = (response: Response): number | undefined => {
   const header = response.headers.get("retry-after");
-  const seconds = header ? Number(header) : Number.NaN;
-  return Number.isFinite(seconds) && seconds > 0
-    ? seconds * SECOND_MS
-    : undefined;
+  if (!header) {
+    return undefined;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) {
+    return seconds > 0 ? seconds * SECOND_MS : undefined;
+  }
+  const delta = Date.parse(header) - Date.now();
+  return Number.isFinite(delta) && delta > 0 ? delta : undefined;
 };
 
 /** One fetch attempt, normalized: the body text, or a (maybe-retryable) error. */
@@ -137,33 +152,65 @@ const attemptFetch = async (spec: string): Promise<Attempt> => {
   }
 };
 
+/**
+ * A retryable failure, wrapped in a plain Error p-retry never special-cases:
+ * it refuses to retry a non-network `TypeError`, and the underlying error's
+ * type is the server's choice, not ours. The message is the underlying
+ * error's, so the exhaustion throw still reads `spec -> 503 Service
+ * Unavailable`.
+ */
+type RetryableFetchError = Error & { retryAfter?: number };
+
+const retryableFetchError = (
+  error: Error,
+  retryAfter?: number
+): RetryableFetchError => {
+  const wrapper: RetryableFetchError = new Error(error.message, {
+    cause: error,
+  });
+  wrapper.name = "RetryableFetchError";
+  wrapper.retryAfter = retryAfter;
+  return wrapper;
+};
+
 /** Fetch a remote spec's text, retrying transient failures with backoff. */
 const fetchSpecText = async (spec: string): Promise<string> => {
   await ensureProxyDispatcher();
-  let last: Attempt = {
-    error: new Error(`Could not fetch ${spec}`),
-    retryable: false,
-  };
-  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-    // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
-    last = await attemptFetch(spec);
-    if ("text" in last) {
-      return last.text;
-    }
-    if (!last.retryable) {
-      break;
-    }
-    if (attempt < MAX_ATTEMPTS - 1) {
-      // oxlint-disable-next-line no-await-in-loop -- back off before retrying
-      await sleep(
-        Math.min(
-          last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
-          MAX_RETRY_WAIT_MS
-        )
-      );
+  return await pRetry(
+    async () => {
+      const attempt = await attemptFetch(spec);
+      if ("text" in attempt) {
+        return attempt.text;
+      }
+      if (!attempt.retryable) {
+        // AbortError stops retrying and rethrows the original untouched.
+        throw new AbortError(attempt.error);
+      }
+      throw retryableFetchError(attempt.error, attempt.retryAfter);
+    },
+    {
+      factor: 2,
+      maxTimeout: MAX_RETRY_WAIT_MS,
+      minTimeout: BASE_BACKOFF_MS,
+      // A sane `Retry-After` replaces the exponential backoff rather than
+      // 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(
+            Math.max(
+              0,
+              Math.min(retryAfter, MAX_RETRY_WAIT_MS) - context.retryDelay
+            )
+          );
+        }
+      },
+      retries: MAX_ATTEMPTS - 1,
     }
-  }
-  throw last.error;
+  );
 };
 
 const cacheFileFor = (cacheDir: string, spec: string): string =>
@@ -224,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: [
@@ -242,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,
@@ -250,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

@@ -1,6 +1,10 @@
-import { withBasePath } from "../core/base-path.ts";
+import { normalizeRoute, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import { trimChar, trimEnd } from "../core/trim.ts";
+import { trimChar } from "../core/trim.ts";
+
+// Re-exported from its home next to the other path helpers; `core/schema.ts`
+// and downstream consumers historically imported it from here.
+export { normalizeRoute } from "../core/base-path.ts";
 
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
@@ -50,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;
   /**
@@ -62,18 +67,37 @@ export interface ReferenceSource {
   collisions?: string[];
 }
 
-const NON_SLUG = /[^a-z0-9]+/gu;
+// Keep Unicode letters/marks/numbers so diacritics stay in the slug (ASCII-only
+// stripping turned `Größe` into `gr-e`, which the nav humanizer rendered as
+// `Gr E`); `\p{M}` keeps combining marks attached to their base letter, which
+// NFC cannot always compose away (Devanagari vowel signs, Turkish `İ`'s
+// lowercased combining dot).
+const NON_SLUG = /[^\p{L}\p{M}\p{N}]+/gu;
+// Format characters (ZWNJ, ZWJ, bidi controls) separate no words — hyphenating
+// them would split Persian/Indic compounds the way ASCII stripping split
+// `Größe` — so they are dropped, not replaced.
+const FORMAT_CHARS = /\p{Cf}/gu;
+// A combining mark at the start of the slug has no base letter to attach to
+// (it would glue onto the preceding `/` in a URL), and a marks-only slug must
+// come out empty so callers' fallbacks (`operations`, `reference`) fire.
+const LEADING_MARKS = /^\p{M}+/u;
 
+/**
+ * Lowercase, hyphen-separated slug: `Add a Pet!` -> `add-a-pet`. Unicode
+ * letters are kept (`Größe` -> `größe`), NFC-normalized so canonically
+ * equivalent spellings (NFD input from macOS tooling) land on one slug.
+ * Non-ASCII slugs rely on the emitter percent-encoding the URL where a raw
+ * URI is required (sitemap, canonical).
+ */
 export const slugify = (text: string): string =>
-  trimChar(text.toLowerCase().replace(NON_SLUG, "-"), "-");
-
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-export const normalizeRoute = (route: string): string => {
-  const trimmed = route.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = trimEnd(withSlash, "/");
-  return noTrailing === "" ? "/" : noTrailing;
-};
+  trimChar(
+    text
+      .normalize("NFC")
+      .toLowerCase()
+      .replace(FORMAT_CHARS, "")
+      .replace(NON_SLUG, "-"),
+    "-"
+  ).replace(LEADING_MARKS, "");
 
 /** A stable per-reference token from its route: `/api/events` -> `api-events`. */
 const routeSlug = (route: string): string =>
@@ -151,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
@@ -175,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
   ),
 ];
@@ -209,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);
@@ -237,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,3 +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";
 
@@ -18,49 +24,95 @@ 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;
-// Backtick code — inline spans and fences alike — is already literal in MDX,
-// and entities are NOT decoded inside it, so escaping there would render the
-// entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
-// backtick run covers `code`, ``code``, and ```fences``` in one shot. Both
-// runs are pinned by the backtick lookarounds: CommonMark pairs a span only
-// with an *equal-length* run, so without them a lone backtick would "close" on
-// the first backtick of a longer fence run — leaving `{` in the real prose
-// unescaped (a compile error) and escaping entities into the fence body.
-const BACKTICK_CODE = /(?<!`)(?<bt>`+)(?!`)[\s\S]*?(?<!`)\k<bt>(?!`)/gu;
-
 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)}`
     );
 
-/** Escape MDX-special syntax in prose while leaving backtick code verbatim. */
+/**
+ * The source offset ranges of code constructs — inline spans and fences —
+ * that MDX treats as literal (entities are NOT decoded inside them, so
+ * escaping there would render `/pets/&#123;petId&#125;` verbatim). The ranges
+ * come from a CommonMark parse rather than fence-emulating regexes: the
+ * parser is the authority on equal-length backtick pairing, longer tilde
+ * closers, unclosed fences running to EOF, and fences nested in blockquotes —
+ * each of which the replaced regexes had to re-derive (two with a recorded
+ * bug history in this file).
+ *
+ * One CommonMark construct is deliberately *not* masked: indented code. MDX
+ * disables indented code blocks, so a 4-space-indented sample is a paragraph
+ * whose braces genuinely need escaping; fence-or-backtick is told apart from
+ * indentation by the construct's first character.
+ */
+const codeSpans = (text: string): [number, number][] => {
+  const spans: [number, number][] = [];
+  const collect = (node: Nodes): void => {
+    if (node.type === "inlineCode" || node.type === "code") {
+      // fromMarkdown always stamps positions; -1 is an unreachable guard.
+      const start = node.position?.start.offset ?? -1;
+      const end = node.position?.end.offset ?? -1;
+      const head = text.slice(Math.max(start, 0), Math.max(end, 0)).trimStart();
+      if (
+        start >= 0 &&
+        (node.type === "inlineCode" ||
+          head.startsWith("`") ||
+          head.startsWith("~"))
+      ) {
+        spans.push([start, end]);
+      }
+      return;
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        collect(child);
+      }
+    }
+  };
+  collect(fromMarkdown(text));
+  return spans;
+};
+
+/** Escape MDX-special syntax in prose while leaving code verbatim. */
 const mdxSafe = (text: string): string => {
   let out = "";
   let cursor = 0;
-  for (const match of text.matchAll(BACKTICK_CODE)) {
-    const start = match.index ?? 0;
+  for (const [start, end] of codeSpans(text)) {
     out += escapeProse(text.slice(cursor, start));
-    out += match[0];
-    cursor = start + match[0].length;
+    out += text.slice(start, end);
+    cursor = end;
   }
   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;
 }
 
@@ -70,33 +122,36 @@ export interface RenderedPage {
 // `description`: the prose already renders in the body, and a `description`
 // frontmatter field would print it a second time as the page subtitle.
 const META_DESCRIPTION_MAX = 160;
-const PARAGRAPH_BREAK = /\n\s*\n/u;
-const MARKDOWN_LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
-const MARKDOWN_MARKS = /[*_`#>]/gu;
 const WHITESPACE = /\s+/gu;
 const TRAILING_WORD = /\s+\S*$/u;
 
-/** Flatten markdown prose to its first paragraph as single-line plain text. */
-const plainProse = (markdown: string): string =>
-  (markdown.trim().split(PARAGRAPH_BREAK).at(0) ?? "")
-    .replace(MARKDOWN_LINK, "$<text>")
-    .replace(MARKDOWN_MARKS, "")
-    .replace(WHITESPACE, " ")
-    .trim();
+/**
+ * Flatten markdown prose to its first paragraph as single-line plain text,
+ * via a real parse (`mdast-util-to-string`). The regex strip this replaces
+ * was lossy on literal prose — `snake_case` → `snakecase`, `C#` → `C` — and
+ * these strings ship as `seo.description` meta tags. A description with no
+ * paragraph (say, only a heading or list) falls back to its first block.
+ */
+const plainProse = (markdown: string): string => {
+  const tree = fromMarkdown(markdown);
+  const first =
+    tree.children.find((node) => node.type === "paragraph") ?? tree.children[0];
+  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;
@@ -110,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);
 };
@@ -141,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).
@@ -214,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(
@@ -223,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),
     },