blume 2.1.3 → 2.2.1

package/src/components/openapi/example-panels.ts

@@ -0,0 +1,110 @@
+import { namedExamples, responseExample } from "./helpers.ts";
+import type {
+  ComponentsLike,
+  MediaLike,
+  SchemaLike,
+  SpecValue,
+} from "./helpers.ts";
+
+/**
+ * The example tabs of an operation's rail (`RequestPanel.astro`): one per
+ * response status, or per webhook payload media type — and one per named
+ * example where its `examples` map names two or more, labeled by the
+ * example's `summary` (else its key) after the status or media type, so
+ * every recorded example shows, under its name. Values are left for the
+ * component to highlight.
+ */
+
+/** One tab before highlighting. */
+export interface ExamplePanel {
+  key: string;
+  label: string;
+  /** The status or media type the tab is under. */
+  name: string;
+  /** The media type the value is an example of. */
+  type: string;
+  /** The example, or `null`/`undefined` when there's none to show. */
+  value: SpecValue;
+  /** What the tab says when there's no example. */
+  text: string;
+}
+
+/** A response: its description and its body's media types. */
+export interface ResponseLike {
+  description?: string;
+  content?: Record<string, MediaLike>;
+}
+
+/** The media entry a body shows: the first JSON-ish one, else the first. */
+export const preferredMedia = (
+  content?: Record<string, MediaLike>
+): [string, MediaLike] | undefined => {
+  const entries = Object.entries(content ?? {});
+  return entries.find(([type]) => type.includes("json")) ?? entries[0];
+};
+
+/**
+ * The tabs for one media type: each named example, or the one example
+ * `responseExample` gives. Webhook payloads and responses both travel from
+ * the API, so both read like a response.
+ */
+const mediaPanels = (
+  name: string,
+  type: string,
+  media: MediaLike | undefined,
+  text: string,
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined
+): ExamplePanel[] => {
+  const named = media
+    ? namedExamples(media, schemas, "response", components)
+    : [];
+  if (named.length > 0) {
+    return named.map((example) => ({
+      key: `${name}-${example.key}`,
+      label: `${name} · ${example.label}`,
+      name,
+      text,
+      type,
+      value: example.value,
+    }));
+  }
+  return [
+    {
+      key: name,
+      label: name,
+      name,
+      text,
+      type,
+      value: media ? responseExample(media, schemas, components) : undefined,
+    },
+  ];
+};
+
+/** The Response tabs: per status, per named example. */
+export const responsePanels = (
+  responses: Record<string, ResponseLike>,
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
+): ExamplePanel[] =>
+  Object.entries(responses).flatMap(([status, response]) => {
+    const [type, media] = preferredMedia(response.content) ?? ["", undefined];
+    return mediaPanels(
+      status,
+      type,
+      media,
+      response.description || "No example response.",
+      schemas,
+      components
+    );
+  });
+
+/** A webhook's Payload tabs: per media type, per named example. */
+export const payloadPanels = (
+  payload: Record<string, MediaLike> | undefined,
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
+): ExamplePanel[] =>
+  Object.entries(payload ?? {}).flatMap(([type, media]) =>
+    mediaPanels(type, type, media, "No example payload.", schemas, components)
+  );

package/src/components/openapi/helpers.ts

@@ -150,7 +150,10 @@ export const soleAllOfMember = (schema: SchemaLike): SchemaLike | undefined =>
 /**
  * Resolve one level of `$ref` against the document's component schemas. A
  * single-member `allOf` wrapper resolves like its member, with the wrapper's
- * own keywords on top: its `description` is about this field.
+ * own keywords on top: its `description` is about this field. So does a
+ * `$ref` with keywords beside it, which OpenAPI 3.1 allows and .NET writes
+ * for every enum-typed property: the `description` beside the `$ref` is the
+ * property's, the referenced one the type's.
  */
 export const resolveSchema = (
   schemas: Record<string, SchemaLike>,
@@ -166,8 +169,10 @@ export const resolveSchema = (
   }
   if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
-    if (name && schemas[name]) {
-      return schemas[name];
+    const target = name ? schemas[name] : undefined;
+    if (target) {
+      const { $ref: _ref, ...own } = schema;
+      return Object.keys(own).length > 0 ? { ...target, ...own } : target;
     }
   }
   return schema;
@@ -325,19 +330,129 @@ export const objectProperties = (
   return { properties: [...properties.entries()], required };
 };
 
+/** Which way an example travels: to the API, or back from it. */
+export type ExampleDirection = "request" | "response";
+
+const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Keywords whose values are data, not schemas, so never rewritten. */
+const DATA_KEYWORDS = new Set([
+  "const",
+  "default",
+  "enum",
+  "example",
+  "examples",
+]);
+
+/** Keywords beside a `$ref` that give the value an example of its own. */
+const VALUE_KEYWORDS = ["const", "default", "example", "examples"];
+
+/**
+ * A schema as openapi-sampler should read it: each `$ref` with an example
+ * value beside it (`example`, `examples`, `default`, `const`) wrapped as a
+ * single-member `allOf`, so the value is used. The sampler follows a `$ref`
+ * before it looks at anything beside it, which OpenAPI 3.1 allows and .NET
+ * writes, so `{ $ref: Status, example: "active" }` sampled the referenced
+ * enum's first member instead.
+ */
+const sampleable = (schema: SpecValue): SpecValue => {
+  if (Array.isArray(schema)) {
+    return schema.map(sampleable);
+  }
+  if (!isRecord(schema)) {
+    return schema;
+  }
+  const out: Record<string, SpecValue> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    out[key] = DATA_KEYWORDS.has(key) ? value : sampleable(value);
+  }
+  const { $ref: ref, ...own } = out;
+  if (!(isString(ref) && VALUE_KEYWORDS.some((key) => key in own))) {
+    return out;
+  }
+  const members = Array.isArray(own.allOf) ? own.allOf : [];
+  return { ...own, allOf: [{ $ref: ref }, ...members] };
+};
+
+/** {@link sampleable} component schemas, once per document. */
+const sampleableSchemas = new WeakMap<
+  Record<string, SchemaLike>,
+  Record<string, SchemaLike>
+>();
+
+const sampleableComponents = (
+  schemas: Record<string, SchemaLike>
+): Record<string, SchemaLike> => {
+  const cached = sampleableSchemas.get(schemas);
+  if (cached) {
+    return cached;
+  }
+  // SAFETY: rewriting a `$ref` node into an `allOf` wrapper keeps every
+  // entry a schema.
+  const rewritten = sampleable(schemas) as Record<string, SchemaLike>;
+  sampleableSchemas.set(schemas, rewritten);
+  return rewritten;
+};
+
+/**
+ * An example value with the properties that don't travel `direction` left
+ * out, at every depth its schema describes: `readOnly` ones from a request,
+ * which the server sets, and `writeOnly` ones from a response, which it
+ * never returns. openapi-sampler skips those only in the values it builds; a
+ * declared example (a model's `example`, which TypeSpec writes, or a media
+ * type's) keeps them, so a request sample would send the model's `id`. A
+ * property the schema doesn't describe stays as written.
+ */
+export const forDirection = (
+  value: SpecValue,
+  schema: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection
+): SpecValue => {
+  if (!schema) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const { items } = resolveSchema(schemas, schema);
+    return items
+      ? value.map((item) => forDirection(item, items, schemas, direction))
+      : value;
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const properties = new Map(objectProperties(schema, schemas).properties);
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+  const out: Record<string, SpecValue> = {};
+  for (const [name, member] of Object.entries(value)) {
+    const property = properties.get(name);
+    if (
+      property?.[omitted] === true ||
+      resolveSchema(schemas, property)[omitted] === true
+    ) {
+      continue;
+    }
+    out[name] = forDirection(member, property, schemas, direction);
+  }
+  return out;
+};
+
 /**
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
- * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * and circular `$ref` chains — which keeping refs intact allows — terminate
- * safely. A request sample skips `readOnly` fields (a server-generated field
- * has no place in one); a response sample skips `writeOnly` fields (a
- * password the client sends never comes back) and keeps the `readOnly` ones.
+ * win, a value beside a `$ref` included, formats produce realistic
+ * placeholders (`email`, `uuid`, `date-time`), and circular `$ref` chains —
+ * which keeping refs intact allows — terminate safely. A request sample
+ * leaves out `readOnly` fields (a server-generated field has no place in
+ * one); a response sample leaves out `writeOnly` fields (a password the
+ * client sends never comes back) and keeps the `readOnly` ones. That holds
+ * inside a declared value the sampler copies too (see {@link forDirection}).
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,
   schemas: Record<string, SchemaLike>,
-  direction: "request" | "response" = "request"
+  direction: ExampleDirection = "request"
 ): SpecValue => {
   if (!schema) {
     return null;
@@ -346,11 +461,12 @@ export const exampleValue = (
   try {
     // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
     // sampler reads, and the sampler only ever assembles JSON values.
-    return sample(
-      schema as Parameters<typeof sample>[0],
+    const value = sample(
+      sampleable(schema) as Parameters<typeof sample>[0],
       { quiet: true, skipReadOnly: !response, skipWriteOnly: response },
-      { components: { schemas } }
+      { components: { schemas: sampleableComponents(schemas) } }
     ) as SpecValue;
+    return forDirection(value, schema, schemas, direction);
   } catch {
     // An unresolvable $ref or malformed schema is a spec problem the schema
     // tables already surface; a sample is best-effort.
@@ -364,9 +480,6 @@ export interface ExampleCarrier {
   examples?: SpecValue;
 }
 
-const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 /**
  * The example a parameter or media type declares: its `example`, else the
  * first `value` in its `examples` map — inline, or behind a `$ref` to
@@ -398,18 +511,80 @@ export const declaredExample = (
   return undefined;
 };
 
+/** A media type: the schema of a body and the examples it declares. */
+export type MediaLike = ExampleCarrier & { schema?: SchemaLike };
+
+/**
+ * A media type's example for a body travelling `direction`: the declared
+ * one, else a sample built from its schema, with the properties that don't
+ * travel that way left out (see {@link forDirection}).
+ */
+export const mediaExample = (
+  media: MediaLike,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection,
+  components?: ComponentsLike
+): SpecValue => {
+  const declared = declaredExample(media, components);
+  return declared === undefined
+    ? exampleValue(media.schema, schemas, direction)
+    : forDirection(declared, media.schema, schemas, direction);
+};
+
 /**
  * A response media type's example for the Response panel: the declared one,
  * else a sample built for the response direction (`readOnly` kept,
- * `writeOnly` skipped).
+ * `writeOnly` left out).
  */
 export const responseExample = (
-  media: ExampleCarrier & { schema?: SchemaLike },
+  media: MediaLike,
   schemas: Record<string, SchemaLike>,
   components?: ComponentsLike
-): SpecValue =>
-  declaredExample(media, components) ??
-  exampleValue(media.schema, schemas, "response");
+): SpecValue => mediaExample(media, schemas, "response", components);
+
+/** One of a media type's named examples, as a tab or the Markdown copy shows it. */
+export interface NamedExample {
+  /** The example's key in the `examples` map. */
+  key: string;
+  /** Its `summary`, else its key. */
+  label: string;
+  value: SpecValue;
+}
+
+/**
+ * Every example a media type's `examples` map names, in order, `$ref`s to
+ * `#/components/examples` resolved, each labeled by its `summary` or else
+ * its key, with the properties that don't travel `direction` left out. Empty
+ * unless the map names two or more: Scalar's upgrade files a 3.0 `example`
+ * as the one entry `default`, which is no name to show, and a lone example
+ * is the one {@link mediaExample} already gives.
+ */
+export const namedExamples = (
+  media: MediaLike,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection,
+  components?: ComponentsLike
+): NamedExample[] => {
+  if (media.example !== undefined || !isRecord(media.examples)) {
+    return [];
+  }
+  const named: NamedExample[] = [];
+  for (const [key, entry] of Object.entries(media.examples)) {
+    const example = isRecord(entry)
+      ? resolveComponentRef(entry, components, "examples")
+      : undefined;
+    if (example?.value === undefined) {
+      continue;
+    }
+    named.push({
+      key,
+      label:
+        isString(example.summary) && example.summary ? example.summary : key,
+      value: forDirection(example.value, media.schema, schemas, direction),
+    });
+  }
+  return named.length > 1 ? named : [];
+};
 
 /** Pretty-print a JSON value for an example/code block. */
 export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

package/src/components/openapi/operation-model.ts

@@ -2,6 +2,7 @@ import { withServerDefaults } from "../../openapi/model.ts";
 import {
   declaredExample,
   exampleValue,
+  mediaExample,
   objectProperties,
   parameterDescription,
   resolveSchema,
@@ -172,7 +173,9 @@ const jsonContentType = (
 /**
  * Typed field inputs when the body schema is a flat object of primitives —
  * anything nested (object/array properties) falls back to the raw JSON editor,
- * where structure is easier to edit than in exploded form fields.
+ * where structure is easier to edit than in exploded form fields. A
+ * `readOnly` property gets no field: the server sets it, so a request
+ * doesn't send it, as the request body's schema table leaves it out.
  */
 const bodyFields = (
   schema: SchemaLike | undefined,
@@ -184,13 +187,13 @@ const bodyFields = (
     return undefined;
   }
   const { properties, required } = objectProperties(resolved, schemas);
-  if (properties.length === 0) {
-    return undefined;
-  }
   const defaults = isExampleObject(example) ? example : undefined;
   const fields: PlaygroundBodyField[] = [];
   for (const [name, property] of properties) {
     const propertySchema = resolveSchema(schemas, property);
+    if (property.readOnly === true || propertySchema.readOnly === true) {
+      continue;
+    }
     const type = scalarType(property, schemas);
     if (
       !(type in PRIMITIVE_TYPES) ||
@@ -203,17 +206,12 @@ const bodyFields = (
       description: propertySchema.description,
       enum: propertySchema.enum?.map(String),
       name,
-      // A `readOnly` property's `required` binds responses only: a request
-      // shouldn't send the server-generated field at all.
-      required:
-        required.has(name) &&
-        property.readOnly !== true &&
-        propertySchema.readOnly !== true,
+      required: required.has(name),
       type,
       value: inputValue(defaults?.[name]),
     });
   }
-  return fields;
+  return fields.length > 0 ? fields : undefined;
 };
 
 /**
@@ -232,9 +230,7 @@ const modelBody = (
     return undefined;
   }
   const [contentType, mediaType] = media;
-  const exampleData =
-    declaredExample(mediaType, components) ??
-    exampleValue(mediaType.schema, schemas);
+  const exampleData = mediaExample(mediaType, schemas, "request", components);
   const encoding = bodyEncoding(contentType);
   const raw = encoding === "raw";
   const body: PlaygroundBody = {
@@ -344,6 +340,37 @@ export const playgroundAuth = (
     return input ? [input] : [];
   });
 
+/** A response, `$ref` resolved: the media types its body comes in. */
+interface ResponseLike {
+  content?: Record<string, MediaTypeLike>;
+}
+
+/**
+ * The `Accept` header a request sends: the first JSON media type among the
+ * operation's responses, success responses first, without its parameters.
+ * A request with none reads as a browser's to frameworks like Laravel, so an
+ * unauthenticated call got a 500 from the login redirect it tried instead
+ * of the 401 the API documents. `undefined` when no response is JSON.
+ */
+export const acceptHeader = (
+  responses?: Record<string, ResponseLike>
+): string | undefined => {
+  const entries = Object.entries(responses ?? {});
+  const success = ([status]: [string, ResponseLike]): boolean =>
+    status.startsWith("2");
+  for (const [, response] of [
+    ...entries.filter(success),
+    ...entries.filter((entry) => !success(entry)),
+  ]) {
+    for (const type of Object.keys(response.content ?? {})) {
+      if (bodyEncoding(type) === "json") {
+        return (type.split(";")[0] ?? type).trim();
+      }
+    }
+  }
+  return undefined;
+};
+
 /** Derive the playground request model for one operation, at build time. */
 export const operationModel = (args: {
   method: string;
@@ -351,21 +378,31 @@ export const operationModel = (args: {
   /** Pre-merged/resolved (`mergeParameters` output). */
   parameters: ParameterLike[];
   requestBody?: { content?: Record<string, MediaTypeLike> };
+  /** The operation's responses, `$ref`s resolved: they set its `Accept`. */
+  responses?: Record<string, ResponseLike>;
   /** The operation's effective servers (`effectiveServers` output). */
   servers: ServerLike[];
   schemas: Record<string, SchemaLike>;
   /** The document's `components`, which `$ref`'d examples resolve against. */
   components?: ComponentsLike;
   security: OperationSecurity;
-}): PlaygroundModel => ({
-  auth: playgroundAuth(args.security),
-  authOptional: args.security.optional,
-  body: modelBody(args.requestBody, args.schemas, args.components),
-  method: args.method.toUpperCase(),
-  params: modelParams(args.parameters, args.schemas, args.components),
-  path: args.path,
-  // Variables resolve to their defaults: the samples and Send need a real URL.
-  servers: args.servers.map((server) =>
-    withServerDefaults(server.url ?? "", server.variables)
-  ),
-});
+}): PlaygroundModel => {
+  const model: PlaygroundModel = {
+    auth: playgroundAuth(args.security),
+    authOptional: args.security.optional,
+    body: modelBody(args.requestBody, args.schemas, args.components),
+    method: args.method.toUpperCase(),
+    params: modelParams(args.parameters, args.schemas, args.components),
+    path: args.path,
+    // Variables resolve to their defaults: the samples and Send need a real
+    // URL.
+    servers: args.servers.map((server) =>
+      withServerDefaults(server.url ?? "", server.variables)
+    ),
+  };
+  const accept = acceptHeader(args.responses);
+  if (accept) {
+    model.accept = accept;
+  }
+  return model;
+};

package/src/components/openapi/request.ts

@@ -108,6 +108,11 @@ export interface PlaygroundModel {
   /** First security alternative (AND set). */
   auth: PlaygroundAuthInput[];
   authOptional: boolean;
+  /**
+   * The `Accept` header every request sends: the operation's first JSON
+   * response media type. Absent when none of its responses is JSON.
+   */
+  accept?: string;
 }
 
 export interface AuthValue {
@@ -431,6 +436,14 @@ export const buildRequest = (
       headers[param.name] = value;
     }
   }
+  // The JSON the operation answers with, unless a header parameter already
+  // names the type it wants.
+  if (
+    model.accept &&
+    !Object.keys(headers).some((name) => name.toLowerCase() === "accept")
+  ) {
+    headers.Accept = model.accept;
+  }
 
   const { body, bodyValue, formData } = model.body
     ? bodyFor(model.body, values.body)

package/src/components/openapi/snippets.ts

@@ -1008,12 +1008,16 @@ const LANGUAGES: SampleLanguage[] = [
 /** Every id `codeSamples` accepts for a generated sample. */
 export const SAMPLE_LANGUAGE_IDS = LANGUAGES.map((language) => language.id);
 
-/** Other spellings of the ids, including every alias Mintlify accepts. */
+/**
+ * Other spellings of the ids, including every alias Mintlify accepts and
+ * ReadMe's ids for the languages Blume generates (`cplusplus`).
+ */
 const ALIASES = new Map([
   [".net", "dotnet"],
   ["bash", "curl"],
   ["c#", "csharp"],
   ["c++", "cpp"],
+  ["cplusplus", "cpp"],
   ["cs", "csharp"],
   ["dot-net", "dotnet"],
   ["flutter", "dart"],
@@ -1056,9 +1060,17 @@ export const sampleLanguageInfo = (raw: string): SampleLanguageInfo | null => {
 /** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
 export const DEFAULT_SAMPLE_LANGUAGES = ["curl", "js", "python"];
 
+/**
+ * The configured ids Blume generates no sample for, as written: the ones
+ * {@link sampleLanguages} drops, which the reference source warns about.
+ */
+export const unknownSampleLanguages = (ids: string[] | false): string[] =>
+  ids === false ? [] : ids.filter((raw) => sampleLanguageInfo(raw) === null);
+
 /**
  * The sample languages to render, resolved from config ids (unknown ids
- * dropped), in order. `false` and an empty list both render none.
+ * dropped, with a warning from the reference source), in order. `false` and
+ * an empty list both render none.
  */
 export const sampleLanguages = (ids: string[] | false): SampleLanguage[] => {
   if (ids === false) {

package/src/core/alert-diagnostics.ts

@@ -0,0 +1,89 @@
+import type { Nodes } from "mdast";
+import { markdownToMdast } from "satteri";
+
+import { MARKDOWN_BODY_FEATURES } from "../markdown/features.ts";
+import { alertMarkerOf } from "../markdown/github-alerts.ts";
+import type { AlertMarker } from "../markdown/github-alerts.ts";
+import { strippedLineOffset } from "./sources/normalize.ts";
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+
+// A quote line that may open with an alert marker.
+const ALERT_LINE = /^[\t >]*>[\t ]*\[![a-z]+\]/imu;
+
+/** An alert quote in an `.md` body: its marker and the quote's line. */
+interface AlertFinding extends AlertMarker {
+  line: number;
+}
+
+/**
+ * The GitHub alerts in an `.md` body, in source order: quotes that open with
+ * `[!NOTE]` and the rest, as `markdown/github-alerts.ts` reads them in `.mdx`
+ * (an escaped marker, or one quoted inside another alert, is no alert there
+ * either). A page is parsed only when a line looks like one.
+ */
+const alertFindings = (text: string): AlertFinding[] => {
+  if (!ALERT_LINE.test(text)) {
+    return [];
+  }
+  const tree: Nodes = markdownToMdast(text, {
+    features: MARKDOWN_BODY_FEATURES,
+  });
+  const found: AlertFinding[] = [];
+  const walk = (node: Nodes): void => {
+    if (node.type === "blockquote") {
+      const [paragraph] = node.children;
+      const first =
+        paragraph?.type === "paragraph" ? paragraph.children[0] : undefined;
+      const escaped = text[first?.position?.start.offset ?? 0] === "\\";
+      const alert =
+        first?.type === "text" && !escaped
+          ? alertMarkerOf(first.value)
+          : undefined;
+      if (alert !== undefined) {
+        found.push({ ...alert, line: node.position?.start.line ?? 1 });
+        // A quote inside an alert stays a quote, alert or not.
+        return;
+      }
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return found;
+};
+
+/**
+ * Warn about GitHub alerts (`> [!NOTE]`) in an `.md` entry, which renders
+ * them as plain quotes that show the marker as text: alerts become callouts
+ * only in `.mdx`, where Blume renders components (see
+ * `markdown/github-alerts.ts`). Lines point into the file the author wrote, a
+ * partial's own file for an alert an `<include>` brought in.
+ */
+export const alertDiagnostics = (
+  entry: SourceEntry,
+  sourceName: string
+): Diagnostic[] => {
+  if (entry.body.format !== "md") {
+    return [];
+  }
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset =
+    entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return alertFindings(entry.expanded?.text ?? entry.body.text).map(
+    ({ callout, line, marker }) => {
+      const origin = entry.expanded?.origins[line - 1];
+      return {
+        code: "BLUME_MD_GITHUB_ALERT",
+        file: origin?.file ?? page,
+        line: origin?.line ?? line + offset,
+        message: `\`${marker}\` makes a quote a callout only in .mdx; in this .md page it renders as a quote that shows \`${marker}\` as text.`,
+        severity: "warning",
+        suggestion: `Rename the page to .mdx to render it as a \`${callout}\` callout, or remove \`${marker}\` to keep a plain quote.`,
+      };
+    }
+  );
+};