@apimatic/cli 1.4.0 → 2.0.0-beta.1

package/portal-template/src/lib/openapi-section.server.ts

@@ -0,0 +1,280 @@
+import path from 'node:path';
+import type { DistributiveOmit, OperationOutput, PagesBuilder, WebhookOutput } from 'fumadocs-openapi';
+import { createOpenAPI, type OpenAPIPageData } from 'fumadocs-openapi/server';
+import { bundleSpec } from './openapi-bundle.server';
+import { placeCodeSamples, readCodeSamples } from './code-samples.server';
+import { isJsonObject, type JsonObject } from './json';
+import { operationLabels } from './openapi-labels';
+import { withoutInternalOperations } from './openapi-filter';
+import { apiBaseDir } from './shared';
+
+/**
+ * The reference pages of one OpenAPI document, mounted under `api/<slug>`. Shared by the
+ * site and the prerender list so the URLs emitted at build time are the routes that exist.
+ * One server per document, because `staticSource()` emits pages for every schema its server
+ * knows about, so sharing a server across sections duplicates pages.
+ */
+export async function openApiSection(slug: string, file: string, codeSamplesFile: string | null) {
+  const load = async () =>
+    placeCodeSamples(withoutInternalOperations(await bundleSpec(file)), await readCodeSamples(codeSamplesFile));
+  const specName = path.basename(file);
+  const baseDir = `${apiBaseDir}/${slug}`;
+  const unsafe = new Set<string>();
+  const section = await createOpenAPI({ input: { [slug]: load } }).staticSource({
+    baseDir,
+    groupBy: 'tag',
+    meta: true,
+    slugify(tag: string) {
+      const held = unsafeIn(tag);
+      if (held !== undefined) {
+        unsafe.add(`the tag '${tag}' holds ${held}`);
+      }
+      return slugify(tag);
+    },
+    name(this: PagesBuilder, output: PageOutput) {
+      return pageName.call(this, output, unsafe);
+    }
+  });
+  if (unsafe.size > 0) {
+    throw new Error(unsafeNamesMessage([...unsafe], specName));
+  }
+  refuseSharedPages(section.files, specName);
+  refuseSharedFolders(section.files, baseDir, specName);
+  return { files: section.files };
+}
+
+/** What a Windows folder name cannot hold, and what a URL path segment cannot hold unescaped. */
+const UNSAFE_IN_PATH = /[<>:"/\\|?*#%{}[\]^`\p{Cc}]/gu;
+
+/** What in a name the portal cannot put in a folder or a URL, or undefined when there is none. */
+function unsafeIn(name: string): string | undefined {
+  const characters = [...new Set(name.match(UNSAFE_IN_PATH) ?? [])].map((character) =>
+    /\p{Cc}/u.test(character) ? 'a control character' : `'${character}'`
+  );
+  // Windows drops a trailing dot, and '..' climbs out of the folder.
+  const dots = [...(name.startsWith('.') ? ['a leading dot'] : []), ...(name.endsWith('.') ? ['a trailing dot'] : [])];
+  const held = [...characters, ...dots];
+  return held.length > 0 ? held.join(', ') : undefined;
+}
+
+function unsafeNamesMessage(unsafe: string[], specName: string): string {
+  return [
+    `Some names in '${specName}' hold what the portal cannot put in a URL or a folder name:`,
+    ...unsafe.map((line) => `  ${line}`),
+    'Remove it from each name. An operation or webhook named after its path or name needs an operationId instead.'
+  ].join('\n');
+}
+
+/** A tag's folder, and the page of a webhook without an operationId. */
+function slugify(name: string): string {
+  return name.replace(/\s+/g, '-').toLowerCase();
+}
+
+type PageOutput = DistributiveOmit<OperationOutput | WebhookOutput, 'path'>;
+
+/** Fumadocs' own page name with its spaces made hyphens, noting in `unsafe` what else it cannot hold. */
+function pageName(this: PagesBuilder, output: PageOutput, unsafe: Set<string>): string {
+  const found =
+    output.type === 'operation' ? this.fromExtractedOperation(output.item) : this.fromExtractedWebhook(output.item);
+  const operationId = found?.operation.operationId;
+  const method = output.item.method.toUpperCase();
+  if (operationId) {
+    const held = unsafeIn(operationId);
+    const label = output.type === 'operation' ? `${method} ${output.item.path}` : `${method} ${output.item.name} (webhook)`;
+    if (held !== undefined) {
+      unsafe.add(`the operationId '${operationId}' of ${label} holds ${held}`);
+    }
+    return operationId.replace(/\s+/g, '-');
+  }
+  if (output.type === 'webhook') {
+    const held = unsafeIn(output.item.name);
+    if (held !== undefined) {
+      unsafe.add(`the webhook '${output.item.name}' has no operationId, and its name holds ${held}`);
+    }
+    return slugify(output.item.name);
+  }
+  const route = this.routePathToFilePath(output.item.path);
+  const held = route.split('/').flatMap((segment) => unsafeIn(segment) ?? []);
+  if (held.length > 0) {
+    unsafe.add(`${method} ${output.item.path} has no operationId, and its path holds ${held.join(', ')}`);
+  }
+  return path.join(route, output.item.method.toLowerCase());
+}
+
+type SectionFile = Awaited<ReturnType<ReturnType<typeof createOpenAPI>['staticSource']>>['files'][number];
+
+/**
+ * Fumadocs writes a page per tag an operation lists, in the tag's folder and named after the
+ * operationId, so two pages land at one path, and one is left out without a word, when two
+ * operations share an operationId (or have none, and paths that read alike), or when one
+ * operation lists a tag twice, or two tags that differ only in case or spacing.
+ */
+function refuseSharedPages(files: SectionFile[], specName: string): void {
+  const pages = new Map<string, OpenAPIPageData>();
+  for (const file of files) {
+    if (file.type === 'meta') {
+      continue;
+    }
+    const earlier = pages.get(file.path);
+    if (earlier) {
+      const folder = path.basename(path.dirname(file.path));
+      throw new Error(sharedPageMessage(folder, documented(earlier), documented(file.data), specName));
+    }
+    pages.set(file.path, file.data);
+  }
+}
+
+/** The operation or webhook a page documents, and what its page is named after. */
+interface DocumentedOperation {
+  label: string;
+  /** Where it sits in the document: under `paths` or `webhooks`, at a path or name, under a method. */
+  location: { in: 'paths' | 'webhooks'; key: string | undefined; method: string | undefined };
+  operationId: string | undefined;
+  tags: string[];
+}
+
+function documented(page: OpenAPIPageData): DocumentedOperation {
+  const props = page.getOpenAPIPageProps();
+  const document = props.payload.bundled as unknown as JsonObject;
+  const [operation] = props.operations ?? [];
+  const [webhook] = props.webhooks ?? [];
+  const location = operation
+    ? { in: 'paths' as const, key: operation.path, method: operation.method }
+    : { in: 'webhooks' as const, key: webhook?.name, method: webhook?.method };
+  const { operationId, tags } = operationObject(document[location.in], location.key, location.method);
+  return {
+    label: operationLabels(props).join(', '),
+    location,
+    operationId: typeof operationId === 'string' ? operationId : undefined,
+    tags: Array.isArray(tags) ? tags.filter((tag): tag is string => typeof tag === 'string') : []
+  };
+}
+
+function operationObject(items: unknown, key: string | undefined, method: string | undefined): JsonObject {
+  const item = isJsonObject(items) && key !== undefined ? items[key] : undefined;
+  const operation = isJsonObject(item) && method !== undefined ? item[method] : undefined;
+  return isJsonObject(operation) ? operation : {};
+}
+
+function sharedPageMessage(
+  folder: string,
+  earlier: DocumentedOperation,
+  later: DocumentedOperation,
+  specName: string
+): string {
+  if (sameLocation(earlier.location, later.location)) {
+    return sharedTagFolderMessage(folder, earlier, specName);
+  }
+  const labels = [`  ${earlier.label}`, `  ${later.label}`];
+  if (earlier.operationId !== undefined && earlier.operationId === later.operationId) {
+    return [
+      `Two operations in '${specName}' have the same operationId '${earlier.operationId}':`,
+      ...labels,
+      'Give each operation a unique operationId.'
+    ].join('\n');
+  }
+  if (earlier.operationId === undefined && later.operationId === undefined) {
+    return [
+      `Two operations in '${specName}' have no operationId, so they would be documented on the same page:`,
+      ...labels,
+      'Give each operation an operationId.'
+    ].join('\n');
+  }
+  return [
+    `Two operations in '${specName}' would be documented on the same page:`,
+    ...labels,
+    'Give each operation a unique operationId.'
+  ].join('\n');
+}
+
+function sameLocation(a: DocumentedOperation['location'], b: DocumentedOperation['location']): boolean {
+  return a.in === b.in && a.key === b.key && a.method === b.method;
+}
+
+/** One operation lands twice on a page when two of its tags name the page's folder. */
+function sharedTagFolderMessage(folder: string, operation: DocumentedOperation, specName: string): string {
+  const tags = operation.tags.filter((tag) => slugify(tag) === folder);
+  const repeated = tags.find((tag, index) => tags.indexOf(tag) !== index);
+  if (repeated !== undefined) {
+    return [
+      `The operation ${operation.label} in '${specName}' lists the tag '${repeated}' more than once.`,
+      'Remove the repeated tag.'
+    ].join('\n');
+  }
+  if (tags.length >= 2) {
+    return [
+      `The operation ${operation.label} in '${specName}' lists the tags '${tags[0]}' and '${tags[1]}', which the portal shows as one section.`,
+      'Rename one of them so they differ in more than case or spacing.'
+    ].join('\n');
+  }
+  return [
+    `The operation ${operation.label} in '${specName}' would be documented twice on the same page.`,
+    'Give each of its tags a distinct name.'
+  ].join('\n');
+}
+
+/**
+ * Fumadocs groups by a tag's name but names the folder after its slug, so two tags that slugify
+ * alike, on different operations, write two metas into one folder. One replaces the other, and
+ * the operations it listed drop out of the sidebar without a word.
+ */
+function refuseSharedFolders(files: SectionFile[], baseDir: string, specName: string): void {
+  const metas = new Set<string>();
+  for (const file of files) {
+    if (file.type !== 'meta') {
+      continue;
+    }
+    if (metas.has(file.path)) {
+      const folder = path.join(path.relative(baseDir, path.dirname(file.path)));
+      const parents = tagParents(files);
+      const tags = [...parents.keys()].filter((tag) => folderOf(tag, parents) === folder);
+      throw new Error(sharedFolderMessage(folder.split(path.sep).join('/'), tags, specName));
+    }
+    metas.add(file.path);
+  }
+}
+
+/** The tags the document declares, then those its operations list without declaring them, each with its parent. */
+function tagParents(files: SectionFile[]): Map<string, string | undefined> {
+  const pages = files.flatMap((file) => (file.type === 'meta' ? [] : [file.data]));
+  const parents = new Map(pages.flatMap(declaredTags));
+  for (const tag of pages.flatMap((page) => documented(page).tags)) {
+    if (!parents.has(tag)) {
+      parents.set(tag, undefined);
+    }
+  }
+  return parents;
+}
+
+/** The tags a page's document declares, each with its parent. */
+function declaredTags(page: OpenAPIPageData): [string, string | undefined][] {
+  const { tags } = page.getOpenAPIPageProps().payload.bundled as unknown as JsonObject;
+  return (Array.isArray(tags) ? tags : []).flatMap((tag): [string, string | undefined][] =>
+    isJsonObject(tag) && typeof tag.name === 'string'
+      ? [[tag.name, typeof tag.parent === 'string' ? tag.parent : undefined]]
+      : []
+  );
+}
+
+/** Where Fumadocs files a tag: its slug, inside its parent's folder. */
+function folderOf(tag: string, parents: Map<string, string | undefined>, seen = new Set<string>()): string {
+  seen.add(tag);
+  const parent = parents.get(tag);
+  const above = parent !== undefined && !seen.has(parent) ? folderOf(parent, parents, seen) : '';
+  return path.join(above, slugify(tag));
+}
+
+function sharedFolderMessage(folder: string, tags: string[], specName: string): string {
+  const [first, second] = tags;
+  if (second !== undefined) {
+    return [
+      `The tags '${first}' and '${second}' in '${specName}' would share the folder '${folder}', so the portal would show only one of them.`,
+      'Rename one of them so they differ in more than case or spacing.'
+    ].join('\n');
+  }
+  // Fumadocs files the operations that list no tag under 'unknown'.
+  return [
+    `The tag '${first ?? folder}' in '${specName}' would share the folder '${folder}' with the operations that have no tag.`,
+    'Rename the tag, or tag those operations.'
+  ].join('\n');
+}

package/portal-template/src/lib/openapi-slim.ts

@@ -0,0 +1,202 @@
+import type { OpenAPIPageProps_Spec } from 'fumadocs-openapi/ui';
+import { isJsonObject } from './json';
+import { OPERATION_METHODS } from './openapi-methods';
+
+type Document = OpenAPIPageProps_Spec['payload']['bundled'];
+type Components = Record<string, Record<string, unknown>>;
+type Wanted = { key: string; method?: string };
+
+// A reference names a component by kind and name; anything after that addresses a node
+// inside it, which is kept along with the whole component rather than on its own.
+const COMPONENT_REF = /^#\/components\/([^/]+)\/([^/]+)/;
+
+// The bundler embeds every external document under `x-ext` and rewrites file and URL
+// references to point inside it. These never take the `#/components/` shape above.
+const EXTERNAL_REF = /^#\/x-ext\/(.+)$/;
+
+const METHODS = new Set(OPERATION_METHODS);
+
+/**
+ * Cuts the bundled document down to what this page can reach: the operations it renders, the
+ * components and embedded external documents they reference (transitively), and the
+ * document-level fields the client reads. Without this every page carries the whole
+ * specification twice -- inlined in its HTML and again in the server-function cache -- so the
+ * output grows with pages × document size.
+ */
+export function slimOpenAPIPageProps(props: OpenAPIPageProps_Spec): OpenAPIPageProps_Spec {
+  const bundled = props.payload.bundled as Document & {
+    paths?: Record<string, unknown>;
+    webhooks?: Record<string, unknown>;
+    components?: Components;
+    'x-ext'?: Record<string, unknown>;
+    security?: unknown;
+  };
+
+  const { paths, webhooks, components, 'x-ext': external, ...rest } = bundled;
+  const operations: Wanted[] = (props.operations ?? []).map((operation) => ({
+    key: operation.path,
+    method: operation.method
+  }));
+  const hooks: Wanted[] = (props.webhooks ?? []).map((webhook) => ({ key: webhook.name, method: webhook.method }));
+
+  const keptPaths = pick(paths, operations);
+  const keptWebhooks = pick(webhooks, hooks);
+  // `rest` is a root too: it survives into the output whole, so a reference inside it has to
+  // keep resolving. Visiting only collects; nothing is retained for having been looked at.
+  const reached = reachable({ components, external }, [rest, keptPaths, keptWebhooks]);
+
+  return {
+    ...props,
+    payload: {
+      ...props.payload,
+      bundled: {
+        ...rest,
+        ...(keptPaths && { paths: keptPaths }),
+        ...(keptWebhooks && { webhooks: keptWebhooks }),
+        ...(reached.components && { components: reached.components }),
+        ...(reached.external && { 'x-ext': reached.external })
+      } as Document
+    }
+  };
+}
+
+/** Keeps the named path items or webhooks, each cut down to the methods the page renders. */
+function pick(
+  record: Record<string, unknown> | undefined,
+  wanted: Wanted[]
+): Record<string, unknown> | undefined {
+  if (!record) return undefined;
+
+  const methodsByKey = new Map<string, Set<string>>();
+  for (const { key, method } of wanted) {
+    if (!(key in record)) continue;
+    const methods = methodsByKey.get(key) ?? new Set<string>();
+    if (typeof method === 'string') methods.add(method.toLowerCase());
+    methodsByKey.set(key, methods);
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, methods] of methodsByKey) out[key] = narrowToMethods(record[key], methods);
+  return out;
+}
+
+/**
+ * Drops the operations the page does not render. Fumadocs reads only `pathItem[method]`, so
+ * without this a page carries every sibling method and the schema closure each one reaches.
+ * Non-method fields stay: the renderer reads path-level `parameters` and `servers` here too.
+ */
+function narrowToMethods(item: unknown, methods: Set<string>): unknown {
+  if (methods.size === 0 || !isJsonObject(item)) return item;
+
+  const entries = Object.entries(item);
+  // An item that is itself a reference carries no operations to narrow.
+  if (entries.some(([key]) => key === '$ref')) return item;
+
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of entries) {
+    // Fumadocs builds no page for an operation under `additionalOperations`, so a page never renders one.
+    const isOperation = METHODS.has(key.toLowerCase()) || key === 'additionalOperations';
+    if (!isOperation || methods.has(key.toLowerCase())) out[key] = value;
+  }
+  return out;
+}
+
+interface Sections {
+  components?: Components;
+  external?: Record<string, unknown>;
+}
+
+/**
+ * Walks from the roots and keeps everything the page's own items can reach: the named
+ * component behind any `#/components/...` string, and the exact node a `#/x-ext/...` string
+ * addresses, rebuilt at the same path so the reference still resolves. Matching any string,
+ * not only `$ref`, also covers `discriminator.mapping` and vendor extensions.
+ */
+function reachable(sections: Sections, roots: unknown[]): Sections {
+  const { components, external } = sections;
+  const keptComponents: Components = {};
+  const keptExternal: Record<string, unknown> = {};
+
+  const seenExternal = new Set<string>();
+  const queue: unknown[] = [...roots];
+
+  // Security schemes are looked up by name from `security`, never through a reference, so
+  // they are kept whole rather than reached. Still walked, because a scheme in a document
+  // bundled from several files carries `#/x-ext/...` references of its own.
+  if (components?.securitySchemes) {
+    keptComponents.securitySchemes = components.securitySchemes;
+    queue.push(components.securitySchemes);
+  }
+
+  const visitComponent = (kind: string, name: string): void => {
+    const target = components?.[kind]?.[name];
+    if (target === undefined || keptComponents[kind]?.[name] !== undefined) return;
+    keptComponents[kind] ??= {};
+    keptComponents[kind][name] = target;
+    queue.push(target);
+  };
+
+  const visitExternal = (pointer: string): void => {
+    if (seenExternal.has(pointer)) return;
+    seenExternal.add(pointer);
+    const segments = pointer.split('/').map(unescapePointer);
+    const target = resolvePointer(external, segments);
+    if (target === undefined) return;
+    writePointer(keptExternal, segments, target);
+    queue.push(target);
+  };
+
+  const visit = (node: unknown): void => {
+    if (typeof node === 'string') {
+      const component = COMPONENT_REF.exec(node);
+      if (component) {
+        visitComponent(component[1], unescapePointer(component[2]));
+        return;
+      }
+      const embedded = EXTERNAL_REF.exec(node);
+      if (embedded) visitExternal(embedded[1]);
+    } else if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+    } else if (node !== null && typeof node === 'object') {
+      for (const value of Object.values(node)) visit(value);
+    }
+  };
+
+  while (queue.length > 0) visit(queue.pop());
+
+  return {
+    components: components && Object.keys(keptComponents).length > 0 ? keptComponents : undefined,
+    external: external && Object.keys(keptExternal).length > 0 ? keptExternal : undefined
+  };
+}
+
+function resolvePointer(root: unknown, segments: string[]): unknown {
+  let node: unknown = root;
+  for (const segment of segments) {
+    if (node === null || typeof node !== 'object') return undefined;
+    node = (node as Record<string, unknown>)[segment];
+  }
+  return node;
+}
+
+// Rebuilds just enough of the path for the reference to resolve against what is kept.
+function writePointer(root: Record<string, unknown>, segments: string[], value: unknown): void {
+  let node = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = node[segment];
+    if (next === null || typeof next !== 'object') node[segment] = {};
+    node = node[segment] as Record<string, unknown>;
+  }
+  node[segments.at(-1) as string] = value;
+}
+
+/** A component named `a/b` is referenced as `a~1b`, and may also be percent-encoded. */
+function unescapePointer(segment: string): string {
+  let decoded = segment;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    // Not percent-encoded; use it as written.
+  }
+  return decoded.replaceAll('~1', '/').replaceAll('~0', '~');
+}

package/portal-template/src/lib/openapi.server.ts

@@ -0,0 +1,16 @@
+import type { MetaData, StaticSource } from 'fumadocs-core/source';
+import type { OpenAPIPageData } from 'fumadocs-openapi/server';
+import { openApiSection } from './openapi-section.server';
+import { codeSamplesFile, specs } from './portal.server';
+
+export type OpenApiSource = StaticSource<{ pageData: OpenAPIPageData; metaData: MetaData }>;
+
+/**
+ * Every document's reference pages as one source. Merged so a reference page has the same
+ * type whichever document it came from, which is what lets the routes tell it apart from a
+ * Markdown page.
+ */
+export async function openApiSource(): Promise<OpenApiSource> {
+  const sections = await Promise.all(Object.entries(specs).map(([slug, file]) => openApiSection(slug, file, codeSamplesFile)));
+  return { files: sections.flatMap((section) => section.files) };
+}

package/portal-template/src/lib/portal-types.ts

@@ -0,0 +1,36 @@
+// Kept out of `portal.ts`, which imports the generated `portal.identity.json`, so the CLI's tests
+// can compare these with the type the CLI writes that file from, without a prepared project.
+
+export type PortalColorMode = 'light' | 'dark' | 'both';
+
+export interface PortalLink {
+  label: string;
+  url: string;
+  /** Whether it leaves the portal, which opens it in a new tab. */
+  external: boolean;
+}
+
+/** Site-relative, one per colour mode; the same URL twice when one image serves both. */
+export interface PortalLogo {
+  light: string;
+  dark: string;
+}
+
+export interface PortalFavicon {
+  /** Site-relative, and inside the static directory. */
+  url: string;
+  type: string | null;
+}
+
+export interface Portal {
+  name: string;
+  description: string | null;
+  /** Origin only, with no trailing slash. */
+  siteUrl: string | null;
+  logo: PortalLogo | null;
+  favicon: PortalFavicon | null;
+  colorMode: PortalColorMode;
+  links: PortalLink[];
+  /** Whether each page offers to open itself in an external AI assistant. */
+  pageActions: boolean;
+}

package/portal-template/src/lib/portal.server.ts

@@ -0,0 +1,13 @@
+import portalConfig from '../../portal.config.json';
+import type { BuildPaths } from '../../portal-config';
+
+const paths = portalConfig as BuildPaths;
+
+/**
+ * Section slug to the absolute path of its OpenAPI document on the machine running the build.
+ * Behind `.server.` so these paths are never published to a visitor.
+ */
+export const specs = paths.specs;
+
+/** The code samples the CLI placed beside `portal.config.json`, or null for a build without any. */
+export const codeSamplesFile = paths.codeSamples;

package/portal-template/src/lib/portal.ts

@@ -0,0 +1,11 @@
+import identity from '../../portal.identity.json';
+import type { Portal } from './portal-types';
+
+// The CLI writes `portal.identity.json` when it prepares the build, and rewrites it when the
+// `portal` block changes under `portal serve`.
+//
+// This module is imported by the browser bundle, and a retained JSON module is not tree-shaken
+// per property, so the file holds these fields and nothing else: importing `portal.config.json`
+// here would publish the build machine's absolute paths to every visitor. Those live in
+// `portal.server.ts`.
+export const portal = identity as Portal;

package/portal-template/src/lib/rehype-code-titles.ts

@@ -0,0 +1,53 @@
+import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils';
+import { CODE_BLOCK_TITLES } from './code-titles';
+import { bundledLanguage } from './shiki-bundle';
+
+interface HastNode {
+  type: string;
+  tagName?: string;
+  name?: string;
+  properties?: { className?: unknown; metastring?: unknown };
+  data?: { meta?: string | null };
+  children?: HastNode[];
+}
+
+const LANGUAGE_CLASS = 'language-';
+
+/** Where `remarkCodeTab` puts a tabbed block, by its own tabs or an MDX `<Tabs>`: the tab already names it. */
+const CODE_TABS = new Set(['CodeBlockTab', 'Tab', 'TabsContent']);
+
+/** Keeps each fence's meta through `rehype-raw`, which drops `data.meta` and keeps the property `rehypeCode` falls back to. */
+export function rehypeKeepCodeMeta() {
+  const visit = (node: HastNode): void => {
+    const meta = node.tagName === 'code' ? node.data?.meta : null;
+    if (meta) {
+      node.properties = { ...node.properties, metastring: meta };
+    }
+    node.children?.forEach(visit);
+  };
+  return visit;
+}
+
+/** Titles each fence its author left untitled after its language, once `rehype-raw` has made HTML ones elements too. */
+export function rehypeCodeTitles() {
+  const visit = (node: HastNode): void => {
+    if (node.name !== undefined && CODE_TABS.has(node.name)) {
+      return;
+    }
+    const code = node.tagName === 'pre' ? node.children?.[0] : undefined;
+    if (code?.tagName !== 'code') {
+      node.children?.forEach(visit);
+      return;
+    }
+    const classes = Array.isArray(code.properties?.className) ? code.properties.className : [];
+    const languageClass = classes.find((name) => typeof name === 'string' && name.startsWith(LANGUAGE_CLASS));
+    const language = typeof languageClass === 'string' ? bundledLanguage(languageClass.slice(LANGUAGE_CLASS.length)) : null;
+    const meta = typeof code.properties?.metastring === 'string' ? code.properties.metastring : '';
+    // Read as `rehypeCode` reads it, which shows no title for a bare or unquoted one.
+    const { title } = parseCodeBlockAttributes(meta, ['title']).attributes;
+    if (language !== null && (title === undefined || title === null)) {
+      code.properties = { ...code.properties, metastring: `${meta} title="${CODE_BLOCK_TITLES[language]}"`.trim() };
+    }
+  };
+  return visit;
+}