blume 2.1.3 → 2.2.0

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.`,
+      };
+    }
+  );
+};

package/src/core/builtin-tags.ts

@@ -14,6 +14,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Callout",
   "Card",
   "CardGroup",
+  "Changelog",
   "CodeBlock",
   "CodeGroup",
   "Color",
@@ -48,3 +49,78 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Visibility",
   "YouTube",
 ]);
+
+/**
+ * The props each built-in that shows its children takes, keyed by MDX tag. A
+ * childless use with any other prop renders without the content its author
+ * meant it to carry (VitePress writes `<Badge type="tip" text="beta" />`, and
+ * Blume's Badge shows only its children), which the unknown-prop diagnostic
+ * reports. Each list is the component's own `Props` (or what it reads from
+ * `Astro.props`); a test checks them against the `.astro` files.
+ */
+export const BUILTIN_CHILD_PROPS: ReadonlyMap<string, readonly string[]> =
+  new Map([
+    ["Accordion", []],
+    ["AccordionItem", ["defaultOpen", "description", "icon", "id", "title"]],
+    [
+      "Badge",
+      [
+        "class",
+        "className",
+        "color",
+        "disabled",
+        "icon",
+        "shape",
+        "size",
+        "stroke",
+        "tooltip",
+        "variant",
+      ],
+    ],
+    ["Callout", ["color", "icon", "title", "type"]],
+    [
+      "Card",
+      [
+        "arrow",
+        "color",
+        "cta",
+        "horizontal",
+        "href",
+        "icon",
+        "img",
+        "title",
+        "type",
+      ],
+    ],
+    ["CardGroup", ["cols"]],
+    ["CodeBlock", ["code", "icons", "lang", "title"]],
+    ["CodeGroup", ["dropdown"]],
+    ["Column", []],
+    ["Columns", ["cols"]],
+    ["Expandable", ["defaultOpen", "title"]],
+    ["Frame", ["caption", "hint"]],
+    ["Panel", ["title"]],
+    ["Prompt", ["actions", "description"]],
+    ["RequestExample", ["dropdown"]],
+    ["ResponseExample", ["dropdown"]],
+    ["Step", ["icon", "title"]],
+    ["Steps", ["titleSize"]],
+    ["Tab", ["class", "icon", "id", "style", "title"]],
+    [
+      "Tabs",
+      [
+        "borderBottom",
+        "defaultTabIndex",
+        "dropdown",
+        "hash",
+        "inline",
+        "param",
+        "sync",
+        "syncKey",
+      ],
+    ],
+    ["Tile", ["description", "href", "title"]],
+    ["Tooltip", ["cta", "headline", "href", "tip"]],
+    ["View", ["class", "icon", "title"]],
+    ["Visibility", ["for"]],
+  ]);

package/src/core/changelog-list.ts

@@ -0,0 +1,87 @@
+/**
+ * The policy the changelog index lists by, shared by the surfaces that build
+ * it: the `<Changelog />` component (reading Astro collection entries) and
+ * `ai/changelog-markdown.ts` (reading the build-time page graph for the
+ * `/changelog.md` mirror and MCP `get_page`).
+ *
+ * The data sources genuinely differ — a collection entry on the Astro side, a
+ * `PageRecord` on the Node side — so what lives here is the *decisions*, not
+ * the access: which date a row carries, what order rows come in, and how they
+ * fall into year groups. Keeping them in one place is what stops the rendered
+ * page and the Markdown an agent reads from drifting apart.
+ */
+
+/**
+ * A changelog entry's date, from `date` or the `changelog.date` it may live
+ * under instead. Front matter hands either a `Date` (an unquoted YAML date) or
+ * a string, and an unparseable value is treated as no date at all rather than
+ * failing the build — a malformed date costs the row its stamp and its year
+ * group, not the page.
+ */
+export const parseChangelogDate = (
+  value: Date | string | null | undefined
+): Date | null => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/**
+ * Newest first. An undated entry sorts as the epoch, so undated rows collect
+ * at the end of the list (and, through {@link groupChangelogYears}, into a
+ * final group with no year label).
+ */
+export const compareChangelogDates = (a: Date | null, b: Date | null): number =>
+  (b?.getTime() ?? 0) - (a?.getTime() ?? 0);
+
+/** One year's run of rows. `year` is `null` for the undated group. */
+export interface ChangelogYearGroup<T> {
+  items: T[];
+  year: string | null;
+}
+
+/**
+ * Consecutive rows sharing a year, in list order, so the index reads as a year
+ * rail beside its rows. Runs are consecutive rather than keyed, which matters
+ * only for a list that isn't sorted by date: such a list keeps its order and
+ * repeats the year heading instead of silently regrouping around it.
+ *
+ * `yearOf` returns the label the surface wants — a locale-formatted year on the
+ * rendered page, a plain number in Markdown — or `null` for an undated row.
+ */
+export const groupChangelogYears = <T>(
+  items: T[],
+  yearOf: (item: T) => string | null
+): ChangelogYearGroup<T>[] => {
+  const groups: ChangelogYearGroup<T>[] = [];
+  for (const item of items) {
+    const year = yearOf(item);
+    const last = groups.at(-1);
+    if (last && last.year === year) {
+      last.items.push(item);
+    } else {
+      groups.push({ items: [item], year });
+    }
+  }
+  return groups;
+};
+
+/**
+ * Make each row's anchor unique. Repeated labels slug to the same id (two
+ * entries with neither a title nor a version both fall back to "update"), so
+ * the later ones take a `-2`, `-3`, … suffix and the first keeps the plain
+ * slug — every row ends up with its own hash anchor.
+ */
+export const uniqueAnchorIds = (ids: string[]): string[] => {
+  const seen = new Set<string>();
+  return ids.map((id) => {
+    let unique = id;
+    for (let n = 2; seen.has(unique); n += 1) {
+      unique = `${id}-${n}`;
+    }
+    seen.add(unique);
+    return unique;
+  });
+};

package/src/core/closest-match.ts

@@ -0,0 +1,41 @@
+/** Edit distance between two short strings (insertions, deletions, swaps of one letter). */
+const distance = (from: string, to: string): number => {
+  let previous = Array.from({ length: to.length + 1 }, (_, index) => index);
+  for (const [row, fromChar] of [...from].entries()) {
+    const current = [row + 1];
+    for (const [column, toChar] of [...to].entries()) {
+      current.push(
+        Math.min(
+          (previous[column + 1] ?? 0) + 1,
+          (current[column] ?? 0) + 1,
+          (previous[column] ?? 0) + (fromChar === toChar ? 0 : 1)
+        )
+      );
+    }
+    previous = current;
+  }
+  return previous[to.length] ?? 0;
+};
+
+/**
+ * The candidate closest to `name`, when it's close enough to be the likely
+ * intent: at most two edits away, and fewer edits than half the candidate's
+ * length, so a short typo doesn't "suggest" an unrelated short word.
+ */
+export const closestMatch = (
+  name: string,
+  candidates: readonly string[]
+): string | undefined => {
+  let best: { candidate: string; edits: number } | undefined;
+  for (const candidate of candidates) {
+    const edits = distance(name, candidate);
+    if (
+      edits <= 2 &&
+      edits * 2 < candidate.length &&
+      (best === undefined || edits < best.edits)
+    ) {
+      best = { candidate, edits };
+    }
+  }
+  return best?.candidate;
+};