blume 2.1.2 → 2.2.0

package/src/openapi/model.ts

@@ -6,8 +6,9 @@ import type {
   AsyncApiDocument,
   AsyncApiSpecValue,
 } from "./asyncapi.ts";
-// Type-only, so the import can't cycle at runtime (graphql.ts imports the
-// collector from here).
+// Type-only, so the import can't cycle at runtime (checks.ts and graphql.ts
+// import from here).
+import type { SpecIssue } from "./checks.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 import { slugify } from "./references.ts";
@@ -294,6 +295,12 @@ const isText = <Value>(value: Value): value is Value & (string | number) =>
 const specText = <Value>(value: Value): string | undefined =>
   isText(value) ? String(value) : undefined;
 
+/**
+ * A tag's slug before collisions are resolved, its word boundaries hyphenated
+ * the way an operation id's are (`InboxesThreads` -> `inboxes-threads`).
+ */
+const wordSlug = (name: string): string => slugify(splitIdentifier(name));
+
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
  * different names onto one value — any two punctuation-only tags (`!!!`,
@@ -301,9 +308,13 @@ const specText = <Value>(value: Value): string | undefined =>
  * silently merges the tags' routes, sidebar groups, and overview sections.
  * Collisions gain `-2`, `-3`, … in first-seen order. Shared with the AsyncAPI
  * extractor (`asyncapi.ts`), whose untagged fallback groups are channel
- * addresses.
+ * addresses. `slug` is the rule before collisions: the collector also runs
+ * the one earlier releases used (`slugify` alone, so `InboxesThreads` ->
+ * `inboxesthreads`) to redirect the routes they gave.
  */
-export const tagSlugger = (): ((name: string) => string) => {
+export const tagSlugger = (
+  slug: (name: string) => string = wordSlug
+): ((name: string) => string) => {
   const assigned = new Map<string, string>();
   const taken = new Set<string>();
   return (name) => {
@@ -311,17 +322,30 @@ export const tagSlugger = (): ((name: string) => string) => {
     if (existing) {
       return existing;
     }
-    const base = slugify(name) || "operations";
-    let slug = base;
-    for (let suffix = 2; taken.has(slug); suffix += 1) {
-      slug = `${base}-${suffix}`;
+    const base = slug(name) || "operations";
+    let unique = base;
+    for (let suffix = 2; taken.has(unique); suffix += 1) {
+      unique = `${base}-${suffix}`;
     }
-    taken.add(slug);
-    assigned.set(name, slug);
-    return slug;
+    taken.add(unique);
+    assigned.set(name, unique);
+    return unique;
   };
 };
 
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export const operationLabel = (
+  name: string,
+  method: string,
+  webhook: boolean
+): string =>
+  webhook
+    ? `Webhook "${name}" (${method.toUpperCase()})`
+    : `${method.toUpperCase()} ${name}`;
+
 /** One entry of a document's `paths` or `webhooks` map. */
 type PathItemEntry =
   | NonNullable<ApiDocument["paths"]>[string]
@@ -330,15 +354,39 @@ type PathItemEntry =
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
 
+/** What a spec's `tags` list says about one tag. */
+export interface ApiTagMeta {
+  description: string;
+  /**
+   * The tag's label, in place of its name, from Redocly's `x-displayName`
+   * extension. Only the label changes: the tag's slug, and so its routes,
+   * still come from its name.
+   */
+  displayName?: string;
+}
+
+/**
+ * A route an earlier release gave an operation's page, and the route the
+ * page has now: the source turns each into a redirect, so links to the old
+ * URL keep working.
+ */
+export interface MovedRoute {
+  from: string;
+  to: string;
+}
+
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
+  /** Operation routes that moved from what earlier slug rules gave them. */
+  moved: MovedRoute[];
 }
 
 /** The collector handle: feed operations in, read the flattened output out. */
 export interface OperationCollector {
-  add: (entry: CollectedOperation) => void;
+  /** Add an operation, returning it with its key and route assigned. */
+  add: (entry: CollectedOperation) => ApiOperationRef;
   finish: () => CollectedOperations;
 }
 
@@ -353,18 +401,34 @@ export interface ExtractedOperations extends CollectedOperations {
  * (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.
+ *
+ * A key is unique across the spec, since it names the operation in
+ * `<Operation id>`. Its page's URL only has to be unique within its tag's
+ * folder, so the last route segment de-duplicates per tag: `list` in two
+ * tags is `/pets/list` and `/stores/list`, not `/stores/list-get`. Earlier
+ * releases de-duplicated the route like the key, and slugged tags without
+ * splitting their words; each route those rules gave differently is
+ * reported in `moved`.
  */
 export const operationCollector = (
   baseRoute: string,
-  tagMeta: ReadonlyMap<string, string>
+  tagMeta: ReadonlyMap<string, ApiTagMeta>
 ): OperationCollector => {
   const operations: ApiOperationRef[] = [];
+  const moved: MovedRoute[] = [];
   const tagOrder: string[] = [];
   const tagsSeen = new Set<string>();
   const seen = new Set<string>();
+  // Tag slug -> the route segments its operations took.
+  const segments = new Map<string, Set<string>>();
   const slugForTag = tagSlugger();
+  const legacySlugForTag = tagSlugger(slugify);
+  // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
+  const base = baseRoute === "/" ? "" : baseRoute;
+  const label = (name: string): string =>
+    tagMeta.get(name)?.displayName ?? name;
 
-  const add = (entry: CollectedOperation): void => {
+  const add = (entry: CollectedOperation): ApiOperationRef => {
     const tagSlug = slugForTag(entry.tag);
     if (!tagsSeen.has(entry.tag)) {
       tagsSeen.add(entry.tag);
@@ -375,13 +439,27 @@ export const operationCollector = (
       key = `${key}-${entry.method}`;
     }
     seen.add(key);
-    operations.push({
+    const taken = segments.get(tagSlug) ?? new Set<string>();
+    segments.set(tagSlug, taken);
+    let segment = entry.key;
+    while (taken.has(segment)) {
+      segment = `${segment}-${entry.method}`;
+    }
+    taken.add(segment);
+    const route = `${base}/${tagSlug}/${segment}`;
+    const legacy = `${base}/${legacySlugForTag(entry.tag)}/${key}`;
+    if (legacy !== route) {
+      moved.push({ from: legacy, to: route });
+    }
+    const operation: ApiOperationRef = {
       ...entry,
       key,
-      // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
-      route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
+      route,
+      tag: label(entry.tag),
       tagSlug,
-    });
+    };
+    operations.push(operation);
+    return operation;
   };
 
   // Declared tags in the order the spec's `tags` list gives them, then any
@@ -395,12 +473,13 @@ export const operationCollector = (
   };
 
   const finish = (): CollectedOperations => ({
+    moved,
     operations,
     tags: tagOrder
       .toSorted((a, b) => rank(a) - rank(b))
       .map((name) => ({
-        description: tagMeta.get(name) ?? "",
-        name,
+        description: tagMeta.get(name)?.description ?? "",
+        name: label(name),
         // The same slugger instance, so every tag resolves to the slug its
         // operations were routed under.
         slug: slugForTag(name),
@@ -410,25 +489,52 @@ export const operationCollector = (
   return { add, finish };
 };
 
+/** {@link ExtractedOperations} plus the spec mistakes extraction noticed. */
+export interface ExtractedApiOperations extends ExtractedOperations {
+  issues: SpecIssue[];
+}
+
+/** A spec's `tags` as the collector reads them: name -> description and label. */
+const declaredTags = (document: ApiDocument): Map<string, ApiTagMeta> =>
+  new Map(
+    (document.tags ?? []).flatMap((tag): [string, ApiTagMeta][] => {
+      const name = specText(tag.name);
+      if (name === undefined) {
+        return [];
+      }
+      const meta: ApiTagMeta = { description: tag.description ?? "" };
+      const displayName = specText(tag["x-displayName"]);
+      if (displayName) {
+        meta.displayName = displayName;
+      }
+      return [[name, meta]];
+    })
+  );
+
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags, webhooks included. Operations inherit the first tag they declare; keys
- * are de-duplicated so a repeated `operationId` still yields distinct routes.
- * `warnings` reports anything skipped (a `$ref` path item), so missing
- * operations aren't silent.
+ * are de-duplicated so a repeated `operationId` still yields distinct routes,
+ * with an issue naming both operations. `warnings` reports anything skipped (a
+ * `$ref` path item), so missing operations aren't silent.
+ *
+ * Operations come out in the spec's order: paths as listed, and each path's
+ * methods as written. They're keyed in the method order earlier releases
+ * walked (`HTTP_METHODS`), so a repeated id resolves to the same key, and
+ * the same route, it always did.
  */
 export const extractOperations = (
   document: ApiDocument,
   baseRoute: string
-): ExtractedOperations => {
+): ExtractedApiOperations => {
   const warnings: string[] = [];
-  const tagMeta = new Map(
-    (document.tags ?? []).flatMap((tag): [string, string][] => {
-      const name = specText(tag.name);
-      return name === undefined ? [] : [[name, tag.description ?? ""]];
-    })
-  );
-  const collector = operationCollector(baseRoute, tagMeta);
+  const issues: SpecIssue[] = [];
+  const collector = operationCollector(baseRoute, declaredTags(document));
+  // Each operation's place in the spec, and the first operation to declare
+  // each operationId.
+  const position = new Map<ApiOperationRef, number>();
+  const firstWithId = new Map<string, string>();
+  let cursor = 0;
 
   // A path item's operations, filed under `name`: a path for `paths`, the
   // webhook's key for `webhooks`.
@@ -449,6 +555,9 @@ export const extractOperations = (
       );
       return;
     }
+    const written = Object.keys(item);
+    const offset = cursor;
+    cursor += written.length;
     for (const method of HTTP_METHODS) {
       const operation = item[method];
       if (!isOperation(operation)) {
@@ -473,7 +582,28 @@ export const extractOperations = (
           specText(operation.tags?.[0]) ??
           (webhook ? UNTAGGED_WEBHOOKS : UNTAGGED),
       };
-      collector.add(webhook ? { ...entry, webhook: true } : entry);
+      const added = collector.add(
+        webhook ? { ...entry, webhook: true } : entry
+      );
+      position.set(added, offset + written.indexOf(method));
+      if (operationId === undefined) {
+        continue;
+      }
+      const label = operationLabel(name, method, webhook);
+      const first = firstWithId.get(operationId);
+      if (first === undefined) {
+        firstWithId.set(operationId, label);
+        continue;
+      }
+      // The key always gains a suffix; the URL only when the two share a tag.
+      const url = added.route.endsWith(`/${entry.key}`)
+        ? ""
+        : ` and serves its page at ${added.route}`;
+      issues.push({
+        code: "BLUME_OPENAPI_DUPLICATE_OPERATION_ID",
+        message: `${first} and ${label} share the operationId "${operationId}", which must be unique in a spec, so Blume names the second one "${added.key}" in \`<Operation id>\`${url}.`,
+        suggestion: `Give each operation its own operationId.`,
+      });
     }
   };
 
@@ -486,7 +616,16 @@ export const extractOperations = (
     addPathItem(name, item, true);
   }
 
-  return { ...collector.finish(), warnings };
+  const collected = collector.finish();
+  return {
+    ...collected,
+    issues,
+    // `position` holds every operation the collector added.
+    operations: collected.operations.toSorted(
+      (a, b) => (position.get(a) ?? 0) - (position.get(b) ?? 0)
+    ),
+    warnings,
+  };
 };
 
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */

package/src/openapi/parse.ts

@@ -15,11 +15,11 @@ import { nodeRequire } from "../core/node-require.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
-import { operationLabel } from "./checks.ts";
+import { nullableIssues } from "./checks.ts";
 import type { SpecIssue } from "./checks.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
-import { HTTP_METHODS } from "./model.ts";
+import { HTTP_METHODS, operationLabel } from "./model.ts";
 import type { ApiDocument } from "./model.ts";
 import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
@@ -63,7 +63,10 @@ const PROXY_ENV_VARS = [
 
 export interface ParsedSpec {
   document: ApiDocument;
-  /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+  /**
+   * Issues only the spec as written shows: `nullable` in a 3.1 spec, and
+   * `x-codeSamples` entries whose `$ref` couldn't be inlined.
+   */
   issues: SpecIssue[];
   warnings: string[];
 }
@@ -494,6 +497,8 @@ export const parseSpec = async (
     root,
     options
   );
+  // Checked as written: upgrading a 3.0 spec rewrites its `nullable`s.
+  const nullable = isJsonObject(normalized) ? nullableIssues(normalized) : [];
   const { specification } = upgrade(normalized);
   // Reject a non-mapping here so the renderer never sees a non-document.
   if (!isApiDocument(specification)) {
@@ -502,7 +507,11 @@ export const parseSpec = async (
     );
   }
   const issues = await inlineSampleRefs(specification, spec, root, options);
-  return { document: specification, issues, warnings };
+  return {
+    document: specification,
+    issues: [...nullable, ...issues],
+    warnings,
+  };
 };
 
 export interface ParsedAsyncApiSpec {

package/src/openapi/render-mdx.ts

@@ -1,4 +1,4 @@
-import type { List, Nodes, Paragraph, Root } from "mdast";
+import type { Heading, List, Nodes, Paragraph, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
@@ -161,9 +161,55 @@ const closeOpenFence = (text: string): string => {
     : `${text}\n${fence}`;
 };
 
-/** Spec prose as MDX that is safe to follow with a component. */
-const descriptionMdx = (text: string): string =>
-  mdxSafe(closeOpenFence(text.trim()));
+/** The deepest heading Markdown can write. */
+const MAX_HEADING_DEPTH = 6;
+
+/** A line break inside a heading's text, with any quote or list indentation. */
+const HEADING_BREAK = /[ \t]*\r?\n[\s>]*/gu;
+
+/** Every heading in a Markdown tree, in document order. */
+const headingsOf = (node: Nodes): Heading[] => {
+  if (node.type === "heading") {
+    return [node];
+  }
+  return "children" in node ? node.children.flatMap(headingsOf) : [];
+};
+
+/**
+ * Spec prose with every heading `by` levels deeper, written as an ATX
+ * heading (`#` × depth, capped at 6). A spec's `info.description` is often a
+ * whole document under `# Introduction` and `# Authentication` headings, so
+ * on a page whose title is already its `<h1>` it would add more: the
+ * overview's description and an operation's sit under the title (`#` becomes
+ * `##`), and a tag's under its `##` section (`#` becomes `###`). Headings are
+ * found in the same `<`-masked parse as `mdxSafe`'s, since the emitted MDX
+ * has no HTML blocks to hide one in; a setext heading's lines join into one.
+ */
+const demoteHeadings = (text: string, by: number): string => {
+  let out = "";
+  let cursor = 0;
+  for (const heading of headingsOf(
+    fromMarkdown(text.replaceAll("<", HTML_MASK))
+  )) {
+    // fromMarkdown always stamps positions; 0 is an unreachable guard.
+    const start = heading.position?.start.offset ?? 0;
+    const from = heading.children[0]?.position?.start.offset ?? start;
+    const to = heading.children.at(-1)?.position?.end.offset ?? from;
+    const depth = Math.min(heading.depth + by, MAX_HEADING_DEPTH);
+    out += `${text.slice(cursor, start)}${"#".repeat(depth)} ${text
+      .slice(from, to)
+      .replace(HEADING_BREAK, " ")}`.trimEnd();
+    cursor = heading.position?.end.offset ?? start;
+  }
+  return out + text.slice(cursor);
+};
+
+/**
+ * Spec prose as MDX that is safe to follow with a component, its headings
+ * demoted `by` levels under the page's own (see {@link demoteHeadings}).
+ */
+const descriptionMdx = (text: string, by: number): string =>
+  mdxSafe(closeOpenFence(demoteHeadings(text.trim(), by)));
 
 /**
  * Frontmatter emitted for one operation or overview page. Boolean flags are
@@ -349,7 +395,7 @@ const operationDescription = (
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
-    ? `${descriptionMdx(description)}\n\n${component}`
+    ? `${descriptionMdx(description, 1)}\n\n${component}`
     : component;
 
 export const operationMdx = (
@@ -397,9 +443,9 @@ export const operationMdx = (
   if (reference?.noindex) {
     seo.noindex = true;
   }
-  const sidebar: RenderedPageData["sidebar"] = {
-    label: operation.summary || operation.path,
-  };
+  // An operation without a summary is labeled as its page is titled, by its
+  // method and path: the path alone repeats for `GET /pets` and `POST /pets`.
+  const sidebar: RenderedPageData["sidebar"] = { label: title };
   // GraphQL operation kinds badge like HTTP methods, but a type page's kind
   // already heads its sidebar group ("Objects", "Enums", …) — an `OBJECT`
   // badge on every row would only repeat it, so type pages get none. The
@@ -468,7 +514,7 @@ export const overviewMdx = (
       continue;
     }
     const description = tag.description.trim()
-      ? [descriptionMdx(tag.description)]
+      ? [descriptionMdx(tag.description, 2)]
       : [];
     tagSections.push(
       [

package/src/openapi/source.ts

@@ -1,5 +1,10 @@
+import {
+  SAMPLE_LANGUAGE_IDS,
+  unknownSampleLanguages,
+} from "../components/openapi/snippets.ts";
 import { withBasePath } from "../core/base-path.ts";
 import matter from "../core/frontmatter.ts";
+import { stripOrderingPrefix } from "../core/ordering-prefix.ts";
 import type { FolderMeta } from "../core/schema.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type {
@@ -7,6 +12,7 @@ import type {
   SourceContext,
   SourceEntry,
   SourceLoadResult,
+  SourceRedirect,
 } from "../core/sources/types.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { extractAsyncApiOperations } from "./asyncapi.ts";
@@ -21,6 +27,7 @@ import type {
   ApiOperationRef,
   ApiSpecData,
   ApiTagRef,
+  MovedRoute,
   OpenApiData,
 } from "./model.ts";
 import {
@@ -136,6 +143,41 @@ const failureSuggestion = (
   return "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.";
 };
 
+/** The adapter that configures each kind, as a warning names it. */
+const ADAPTER_NAMES = {
+  asyncapi: "asyncapi()",
+  graphql: "graphql()",
+  openapi: "openapi()",
+} satisfies Record<BlumeReferenceSource["kind"], string>;
+
+/**
+ * A warning for the `codeSamples` ids Blume generates no sample for, which
+ * the operation pages would otherwise leave out without a sign. AsyncAPI's
+ * ids name tools, matched against each operation's protocol binding, so only
+ * the HTTP kinds are checked here.
+ */
+const unknownLanguageDiagnostics = (
+  reference: BlumeReferenceSource
+): Diagnostic[] => {
+  if (reference.kind === "asyncapi") {
+    return [];
+  }
+  const unknown = unknownSampleLanguages(reference.display.codeSamples);
+  if (unknown.length === 0) {
+    return [];
+  }
+  const names = unknown.map((id) => `"${id}"`).join(", ");
+  const one = unknown.length === 1;
+  return [
+    {
+      code: `${CODE_PREFIXES[reference.kind]}_UNKNOWN_CODE_SAMPLE`,
+      message: `\`codeSamples\` in ${ADAPTER_NAMES[reference.kind]} lists ${names}, which ${one ? "isn't a language" : "aren't languages"} Blume generates samples in, so ${one ? "it's" : "they're"} left out of every operation page.`,
+      severity: "warning",
+      suggestion: `Use the ids Blume generates (${SAMPLE_LANGUAGE_IDS.join(", ")}) or an alias the reference docs list, or show your own samples with \`x-codeSamples\` in the spec.`,
+    },
+  ];
+};
+
 const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
   const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
   return {
@@ -185,17 +227,31 @@ const specEntries = (
  * not "Github V2"). Keys are the directories under the reference route, the
  * same group paths `meta.ts` files use, so user-authored meta still
  * overrides these.
+ *
+ * Each group lists its operation pages in `operations` order, the spec's own
+ * (see `extractOperations`), as the overview does, rather than letting the
+ * sidebar sort them by label. A page's nav key is its file name without an
+ * ordering prefix, as `meta.ts` `pages` entries are.
  */
 const tagFolderMeta = (
   spec: ApiSpecData,
   tags: { slug: string; name: string }[],
+  operations: ApiOperationRef[],
   groupLabel: string | undefined
 ): Record<string, FolderMeta> => {
   const base = routeToRef(spec.route);
   const meta: Record<string, FolderMeta> = Object.fromEntries(
     tags.map((tag, order) => [
       base ? `${base}/${tag.slug}` : tag.slug,
-      { order, title: tag.name },
+      {
+        order,
+        pages: operations
+          .filter((operation) => operation.tagSlug === tag.slug)
+          .map((operation) =>
+            stripOrderingPrefix(operation.route.split("/").at(-1) ?? "")
+          ),
+        title: tag.name,
+      },
     ])
   );
   // A root-mounted reference has no group of its own to name.
@@ -211,6 +267,8 @@ interface LoadedSpec {
   entries: SourceEntry[];
   /** Sidebar-group labels for the spec's tag directories. */
   folderMeta: Record<string, FolderMeta>;
+  /** Redirects from the routes earlier releases gave its operations. */
+  redirects: SourceRedirect[];
   /** Non-fatal notes from the load (e.g. an offline cache fallback). */
   diagnostics: Diagnostic[];
 }
@@ -221,6 +279,8 @@ interface ParsedReference {
   warnings: string[];
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
+  /** Operation routes earlier releases gave elsewhere (see `operationCollector`). */
+  moved: MovedRoute[];
   extractWarnings: string[];
   /** Spec mistakes that would render silently wrong (OpenAPI only). */
   issues?: SpecIssue[];
@@ -241,6 +301,7 @@ const parseReference = async (
     return {
       document,
       extractWarnings: extracted.warnings,
+      moved: extracted.moved,
       operations: extracted.operations,
       tags: extracted.tags,
       warnings,
@@ -256,6 +317,7 @@ const parseReference = async (
     return {
       document,
       extractWarnings: extracted.warnings,
+      moved: extracted.moved,
       operations: extracted.operations,
       tags: extracted.tags,
       warnings,
@@ -270,7 +332,8 @@ const parseReference = async (
   return {
     document,
     extractWarnings: extracted.warnings,
-    issues: [...issues, ...specIssues(document)],
+    issues: [...issues, ...specIssues(document), ...extracted.issues],
+    moved: extracted.moved,
     operations: extracted.operations,
     tags: extracted.tags,
     warnings,
@@ -291,8 +354,15 @@ export const openApiSource = (
     const kindLabel = KIND_LABELS[reference.kind];
     const codePrefix = CODE_PREFIXES[reference.kind];
     try {
-      const { document, warnings, operations, tags, extractWarnings, issues } =
-        await parseReference(reference, ctx);
+      const {
+        document,
+        warnings,
+        operations,
+        tags,
+        moved,
+        extractWarnings,
+        issues,
+      } = await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
       // The playground proxy resolves here, not client-side: `true` selects
       // the built-in `/_api-proxy` route (mounted under the site `basePath`,
@@ -375,7 +445,8 @@ export const openApiSource = (
             : []),
         ],
         entries: specEntries(spec, operations, reference),
-        folderMeta: tagFolderMeta(spec, tags, reference.groupLabel),
+        folderMeta: tagFolderMeta(spec, tags, operations, reference.groupLabel),
+        redirects: moved,
         slug: reference.slug,
         spec,
       };
@@ -408,8 +479,17 @@ export const openApiSource = (
         severity: "warning" as const,
       }))
     );
+    // Display options belong to the adapter, which every one of its sources
+    // repeats: one warning per distinct message.
+    const languageWarnings = new Map(
+      references
+        .flatMap(unknownLanguageDiagnostics)
+        .map((diagnostic) => [diagnostic.message, diagnostic])
+    );
+    diagnostics.push(...languageWarnings.values());
     const data: OpenApiData = {};
     const folderMeta: Record<string, FolderMeta> = {};
+    const redirects: SourceRedirect[] = [];
     for (const result of results) {
       if ("severity" in result) {
         diagnostics.push(result);
@@ -418,10 +498,11 @@ export const openApiSource = (
       data[result.slug] = result.spec;
       entries.push(...result.entries);
       Object.assign(folderMeta, result.folderMeta);
+      redirects.push(...result.redirects);
       diagnostics.push(...result.diagnostics);
     }
     parsed = data;
-    return { diagnostics, entries, folderMeta };
+    return { diagnostics, entries, folderMeta, redirects };
   };
 
   return {

package/src/registry/eject.ts

@@ -813,7 +813,6 @@ export const eject = async (
     exportEpub,
     exportPdf,
     needsReact,
-    staged: hasStaged,
   });
 
   if (config.seo.og.enabled) {