blume 2.1.2 → 2.2.0

package/src/ai/changelog-components.ts

@@ -0,0 +1,24 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import { changelogIndexBlocks } from "./changelog-markdown.ts";
+import type { ComponentMarkdown } from "./component-markdown.ts";
+
+/**
+ * Downlevel `<Changelog />` to the release list it renders.
+ *
+ * The generated `/changelog` page publishes its list through
+ * `buildChangelogIndexMarkdown`, but a hand-written page that owns the route
+ * instead goes through the component downleveler — which leaves a tag it has
+ * no serializer for exactly as written. Without this, moving to an authored
+ * page would publish a literal `<Changelog />` to `/changelog.md`,
+ * llms-full.txt, MCP `get_page` and the search corpus, and an agent would see
+ * no releases at all.
+ *
+ * The list is the same one the mirror publishes, so both routes to a changelog
+ * index — generated or authored — reach agents identically.
+ */
+export const changelogComponentSerializers = (project: BlumeProject) =>
+  ({
+    // An empty changelog replaces the tag with nothing, so the page's own prose
+    // is all an agent reads. Returning `null` would leave the tag as written.
+    Changelog: () => changelogIndexBlocks(project).join("\n\n"),
+  }) satisfies Record<string, ComponentMarkdown>;

package/src/ai/changelog-markdown.ts

@@ -1,5 +1,10 @@
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import { withChangelogIndexText } from "../core/changelog-index.ts";
+import {
+  compareChangelogDates,
+  groupChangelogYears,
+  parseChangelogDate,
+} from "../core/changelog-list.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -19,14 +24,6 @@ interface IndexRow {
   page: PageRecord;
 }
 
-const parseDate = (value: string | undefined): Date | null => {
-  if (value === undefined) {
-    return null;
-  }
-  const date = new Date(value);
-  return Number.isNaN(date.getTime()) ? null : date;
-};
-
 /** A row's link: absolute under a configured site, like llms.txt. */
 const entryUrl = (project: BlumeProject, route: string): string => {
   const { base, site } = project.config.deployment.options;
@@ -44,18 +41,19 @@ const rowLine = (project: BlumeProject, { date, page }: IndexRow): string => {
   return `- [${title}](${entryUrl(project, page.route)})${tail}`;
 };
 
-export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
+/**
+ * The release list alone, as year headings over linked rows — what
+ * `<Changelog />` renders, in Markdown. Split out of the document below so the
+ * component's serializer publishes exactly the list the generated page's
+ * mirror does: an authored `/changelog` page brings its own heading and prose,
+ * and only the list comes from here.
+ *
+ * Entries are the default locale's, as everywhere else this list is published
+ * — see `components/content/Changelog.astro` for why the rule is the same on
+ * the rendered page.
+ */
+export const changelogIndexBlocks = (project: BlumeProject): string[] => {
   const { i18n } = project.config;
-  const ui = withChangelogIndexText(
-    project.config,
-    i18n
-      ? resolveUIStrings(i18n.defaultLocale, {
-          defaultLocale: i18n.defaultLocale,
-          overrides: i18n.ui,
-        })
-      : EN_UI,
-    i18n?.defaultLocale
-  );
   const rows: IndexRow[] = project.graph.pages
     .filter(
       (page) =>
@@ -67,30 +65,36 @@ export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
         (!i18n || page.locale === i18n.defaultLocale)
     )
     .map((page) => ({
-      date: parseDate(page.meta.date ?? page.meta.changelog?.date),
+      date: parseChangelogDate(page.meta.date ?? page.meta.changelog?.date),
       page,
     }))
-    .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0));
+    .toSorted((a, b) => compareChangelogDates(a.date, b.date));
 
-  const blocks = [`# ${ui.changelog.title}`, ui.changelog.description];
-  let year: number | null | undefined;
-  let lines: string[] = [];
-  const flush = (): void => {
-    if (lines.length > 0) {
-      blocks.push(lines.join("\n"));
-      lines = [];
-    }
-  };
-  for (const row of rows) {
-    const rowYear = row.date ? row.date.getUTCFullYear() : null;
-    if (rowYear !== year) {
-      flush();
-      year = rowYear;
-      // Undated entries sort last, under a heading of their own.
-      blocks.push(rowYear === null ? "## Undated" : `## ${rowYear}`);
-    }
-    lines.push(rowLine(project, row));
-  }
-  flush();
+  // Undated entries sort last, under a heading of their own.
+  return groupChangelogYears(rows, (row) =>
+    row.date ? String(row.date.getUTCFullYear()) : null
+  ).flatMap((group) => [
+    `## ${group.year ?? "Undated"}`,
+    group.items.map((row) => rowLine(project, row)).join("\n"),
+  ]);
+};
+
+export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
+  const { i18n } = project.config;
+  const ui = withChangelogIndexText(
+    project.config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
+  const blocks = [
+    `# ${ui.changelog.title}`,
+    ui.changelog.description,
+    ...changelogIndexBlocks(project),
+  ];
   return `${blocks.join("\n\n")}\n`;
 };

package/src/ai/component-markdown.ts

@@ -2,7 +2,10 @@ import { markdownTable } from "markdown-table";
 import { mdxToMdast } from "satteri";
 
 import { PARAM_LOCATIONS } from "../components/content/api-field.ts";
-import { parseYouTubeId } from "../components/content/youtube.ts";
+import {
+  parseYouTubeId,
+  parseYouTubePlaylist,
+} from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
 import { MDX_FEATURES } from "../markdown/features.ts";
 import { readStaticExpression } from "./static-expression.ts";
@@ -553,18 +556,21 @@ const youtube: ComponentMarkdown = ({ props }) => {
   } else if (isString(props.url)) {
     input = props.url;
   }
+  const title =
+    isString(props.title) && props.title !== ""
+      ? props.title
+      : "Watch on YouTube";
   const videoId = parseYouTubeId(input);
   if (!videoId) {
-    return null;
+    const list = parseYouTubePlaylist(input);
+    return list
+      ? `[${title}](https://www.youtube.com/playlist?list=${list})`
+      : null;
   }
   const start =
     isNumber(props.start) && props.start > 0
       ? `&t=${Math.floor(props.start)}s`
       : "";
-  const title =
-    isString(props.title) && props.title !== ""
-      ? props.title
-      : "Watch on YouTube";
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
 
@@ -732,11 +738,18 @@ const githubInfo: ComponentMarkdown = ({ lossy, props }) => {
   return `[${linkText(`${owner}/${repo}`)}](${linkDestination(`${host}/${owner}/${repo}`)})`;
 };
 
-/** `CodeBlock` is a fenced block, its title kept in the fence's meta. */
-const codeBlock: ComponentMarkdown = ({ lossy, props }) => {
-  if (lossy || !isString(props.code)) {
+/**
+ * `CodeBlock` is a fenced block, its title kept in the fence's meta. Without
+ * `code` it renders its children (a fence wrapped in `<CodeBlock>`), so those
+ * are its Markdown.
+ */
+const codeBlock: ComponentMarkdown = ({ children, lossy, props }) => {
+  if (lossy) {
     return null;
   }
+  if (!isString(props.code)) {
+    return props.code === undefined && children !== "" ? children : null;
+  }
   const lang = textProp(props.lang) || "txt";
   const title = textProp(props.title);
   return fencedBlock(

package/src/ai/llms.ts

@@ -1,8 +1,11 @@
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
-import { rewriteRelativeImages } from "../core/content-assets.ts";
+import { rewriteRelativeAssets } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
+import { isHiddenPage } from "../core/hidden-pages.ts";
+import { metaDescription } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
+import { extractHeadings } from "../core/sources/normalize.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
@@ -121,7 +124,7 @@ const eligiblePages = (
       !(
         page.meta.ai.exclude ||
         page.meta.draft ||
-        page.meta.sidebar.hidden ||
+        isHiddenPage(page, project.graph) ||
         (page.meta.seo.noindex && page.source.name !== "openapi") ||
         (options.versions === "current" && page.version !== "")
       ) &&
@@ -187,7 +190,10 @@ export const buildLlmsIndex = (
 
   const line = (page: PageRecord): string => {
     seen.add(page.route);
-    const summary = page.description ? `: ${page.description}` : "";
+    // The page's meta description, so a page summarized only in
+    // `seo.description` (a generated reference page) still gets one.
+    const description = metaDescription(page);
+    const summary = description ? `: ${description}` : "";
     return `- [${linkText(page.title)}](${pageUrl(page.route, site, base)})${summary}`;
   };
 
@@ -306,6 +312,26 @@ export const buildLlmsIndex = (
   return `${[lead, ...blocks].join("\n\n")}\n`;
 };
 
+// A line an ATX heading opens (`# Title`); any other first line can only open
+// a setext heading, underlined on the line after it.
+const ATX_HEADING = /^ {0,3}#/u;
+
+/**
+ * A page body without the `# Heading` it opens with, when that heading's text
+ * is the page's title. An untitled page takes its title from that heading,
+ * and its `llms-full.txt` section already opens with `# <title>`, so the
+ * heading would show twice; the rendered page drops it the same way (see
+ * `markdown/title-heading.ts`).
+ */
+const withoutTitleHeading = (body: string, title: string): string => {
+  const lines = body.split("\n");
+  const span = ATX_HEADING.test(lines[0] ?? "") ? 1 : 2;
+  const [heading] = extractHeadings(lines.slice(0, span).join("\n"));
+  return heading?.depth === 1 && heading.text === title
+    ? lines.slice(span).join("\n").trimStart()
+    : body;
+};
+
 /** Build `llms-full.txt`: the full Markdown body of every current-docs page. */
 const buildFull = async (project: BlumeProject): Promise<string> => {
   const { config } = project;
@@ -321,7 +347,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       // Colocated `./image.png` references resolve to nothing for a reader of
       // llms-full.txt; point them at the served originals instead.
       if (page.sourcePath) {
-        raw = rewriteRelativeImages({
+        raw = rewriteRelativeAssets({
           deployBase: config.deployment.options.base,
           projectRoot: project.context.root,
           source: raw,
@@ -346,7 +372,12 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
         config.deployment.options.site,
         normalizeBasePath(config.deployment.options.base)
       );
-      return [`# ${page.title}`, `Source: ${url}`, "", body].join("\n");
+      return [
+        `# ${page.title}`,
+        `Source: ${url}`,
+        "",
+        withoutTitleHeading(body, page.title),
+      ].join("\n");
     })
   );
 

package/src/ai/markdown.ts

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 
 import { hasGeneratedChangelog } from "../astro/pages.ts";
 import { CHANGELOG_INDEX_ROUTE } from "../core/changelog-index.ts";
-import { rewriteRelativeImages } from "../core/content-assets.ts";
+import { rewriteRelativeAssets } from "../core/content-assets.ts";
 import { discoverPages, discoverPagesSync } from "../core/custom-pages.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -76,7 +76,7 @@ export const buildRawMarkdown = async (
     project.manifest.routes.map(async (route) => {
       let text = await readRoute(route);
       if (route.sourcePath) {
-        text = rewriteRelativeImages({
+        text = rewriteRelativeAssets({
           deployBase: project.config.deployment.options.base,
           projectRoot: project.context.root,
           source: text,

package/src/ai/openapi-components.ts

@@ -1,6 +1,10 @@
 import { customCodeSamples } from "../components/openapi/code-samples.ts";
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
-import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
+import type {
+  ApiDocument,
+  ApiOperationRef,
+  OpenApiData,
+} from "../openapi/model.ts";
 import {
   operationObject,
   operationOf,
@@ -19,6 +23,8 @@ import {
   isString,
   linkDestination,
 } from "./component-markdown.ts";
+import { operationDetails } from "./operation-details.ts";
+import type { OperationParts } from "./operation-details.ts";
 
 /**
  * Spec-authored prose as one line of inline Markdown. Unlike the props the
@@ -70,13 +76,13 @@ const listItem = (
  * Each serializer emits what its component renders and no more: the endpoint
  * in the spec kind's own notation ({@link operationSignature}), the version and
  * addresses the overview shows ({@link specAddresses}), the linked list a tag
- * section shows. Parameters, schemas and responses are deliberately left out:
- * those are `operation-model.ts` plus each component's own preparation, and a
- * second implementation here would be free to disagree with the page. The
- * endpoint and what it does is the part that was missing altogether. The
- * spec's own `x-codeSamples` do come along, as fenced code: they're text the
- * spec wrote out (often an SDK call no agent could derive from the
- * endpoint), read through the same `customCodeSamples` the page renders.
+ * section shows. The spec's own `x-codeSamples` come along, as fenced code:
+ * they're text the spec wrote out (often an SDK call no agent could derive
+ * from the endpoint), read through the same `customCodeSamples` the page
+ * renders. So do an OpenAPI operation's request body and responses, with
+ * their examples ({@link operationDetails}), built from the helpers the
+ * page's components use so the two can't disagree; parameters and nested
+ * schemas are left to the page.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
  * API reference, in which case every serializer declines. `deployBase` is the
@@ -166,7 +172,17 @@ export const openapiComponentSerializers = (
         (sample) =>
           `**${inlineText(sample.label)}**\n\n${fencedBlock(sample.lang, sample.source)}`
       );
-      return [signature, ...notes, ...samples].join("\n\n");
+      // SAFETY: an operation object only resolves out of an OpenAPI spec,
+      // whose document is the OpenAPI shape; its bodies and responses are
+      // the JSON `OperationParts` views, which the helpers read defensively.
+      const details = object
+        ? operationDetails(
+            data.document as ApiDocument,
+            object as OperationParts,
+            operation.webhook === true
+          )
+        : [];
+      return [signature, ...notes, ...samples, ...details].join("\n\n");
     },
   } satisfies Record<string, ComponentMarkdown>;
 };

package/src/ai/operation-details.ts

@@ -0,0 +1,208 @@
+import {
+  preferredMedia,
+  responsePanels,
+} from "../components/openapi/example-panels.ts";
+import type { ResponseLike } from "../components/openapi/example-panels.ts";
+import {
+  isNullable,
+  mediaExample,
+  namedExamples,
+  objectProperties,
+  resolveComponentRef,
+  resolveSchema,
+  toJson,
+  typeLabel,
+} from "../components/openapi/helpers.ts";
+import type {
+  ComponentsLike,
+  ExampleDirection,
+  MediaLike,
+  SchemaLike,
+  SpecValue,
+} from "../components/openapi/helpers.ts";
+import type { ApiDocument } from "../openapi/model.ts";
+import { fencedBlock, inlineCode } from "./component-markdown.ts";
+
+/**
+ * The body and responses of an OpenAPI operation as compact Markdown, for the
+ * agent-facing copy of its page (`<route>.md`, llms-full.txt, MCP
+ * `get_page`): the request body's media type and top-level properties, its
+ * example (every named one), each response's status and description, and
+ * the examples the spec records. Without these an agent read an endpoint
+ * with no word of what to send or what comes back, though the spec, and the
+ * page, had both. Built from the helpers the page's own components use, so
+ * the two can't disagree: the same JSON-ish media type, the same examples,
+ * `readOnly` and `writeOnly` properties left out the same way.
+ *
+ * Kept compact: properties one level deep (an example shows the rest), and
+ * a sampled response example only for the first success response that
+ * records none, since error bodies often all share one schema.
+ */
+
+/** A request body, `$ref` resolved. */
+interface RequestBodyLike {
+  description?: string;
+  required?: boolean;
+  content?: Record<string, MediaLike>;
+}
+
+/** The operation fields read here. */
+export interface OperationParts {
+  requestBody?: RequestBodyLike & { $ref?: string };
+  responses?: Record<string, ResponseLike & { $ref?: string }>;
+}
+
+/** Spec prose on one line, the characters Markdown reads as markup escaped. */
+const oneLine = (text: string): string =>
+  text
+    .trim()
+    .replaceAll(/\s+/gu, " ")
+    .replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
+
+/** A fenced JSON example, under its label. */
+const exampleBlock = (label: string, value: SpecValue): string =>
+  `${label}:\n\n${fencedBlock("json", toJson(value))}`;
+
+/** One line per top-level property: name, type, required, description. */
+const propertyLines = (
+  schema: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection
+): string[] => {
+  if (!schema) {
+    return [];
+  }
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+  const { properties, required } = objectProperties(schema, schemas);
+  return properties.flatMap(([name, property]) => {
+    const resolved = resolveSchema(schemas, property);
+    if (property[omitted] === true || resolved[omitted] === true) {
+      return [];
+    }
+    const type = `${typeLabel(property)}${isNullable(resolved) ? " | null" : ""}`;
+    const notes = [type, required.has(name) ? "required" : ""]
+      .filter(Boolean)
+      .join(", ");
+    const description = resolved.description?.trim();
+    return [
+      `- ${inlineCode(name)} (${notes})${description ? ` — ${oneLine(description)}` : ""}`,
+    ];
+  });
+};
+
+/** The request body (a webhook's payload): media type, properties, examples. */
+const bodyMarkdown = (
+  body: RequestBodyLike,
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined,
+  webhook: boolean
+): string[] => {
+  const chosen = preferredMedia(body.content);
+  if (!chosen) {
+    return [];
+  }
+  const [type, media] = chosen;
+  // A webhook's payload travels from the API, like a response.
+  const direction = webhook ? "response" : "request";
+  const heading = webhook ? "Payload" : "Request body";
+  const lines = propertyLines(media.schema, schemas, direction);
+  const named = namedExamples(media, schemas, direction, components);
+  const single = mediaExample(media, schemas, direction, components);
+  const examples =
+    named.length > 0
+      ? named.map((example) =>
+          exampleBlock(
+            `${heading} example, ${oneLine(example.label)}`,
+            example.value
+          )
+        )
+      : [
+          single === null || single === undefined
+            ? ""
+            : exampleBlock(`${heading} example`, single),
+        ];
+  return [
+    `**${heading}** (${[inlineCode(type), body.required ? "required" : ""].filter(Boolean).join(", ")})`,
+    body.description?.trim() ? oneLine(body.description) : "",
+    lines.join("\n"),
+    ...examples,
+  ].filter(Boolean);
+};
+
+/** The responses: one line per status, then the examples the spec records. */
+const responsesMarkdown = (
+  responses: Record<string, ResponseLike>,
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined
+): string[] => {
+  const statuses = Object.entries(responses);
+  if (statuses.length === 0) {
+    return [];
+  }
+  const recorded = new Set(
+    statuses.flatMap(([status, response]) => {
+      const media = preferredMedia(response.content)?.[1];
+      return media?.example === undefined && media?.examples === undefined
+        ? []
+        : [status];
+    })
+  );
+  const sampled = statuses.find(
+    ([status]) => status.startsWith("2") && !recorded.has(status)
+  )?.[0];
+  const examples = responsePanels(responses, schemas, components).flatMap(
+    (panel) =>
+      (recorded.has(panel.name) || panel.name === sampled) &&
+      panel.value !== null &&
+      panel.value !== undefined
+        ? [
+            exampleBlock(
+              `Response example, ${oneLine(panel.label)}`,
+              panel.value
+            ),
+          ]
+        : []
+  );
+  return [
+    "**Responses**",
+    statuses
+      .map(
+        ([status, response]) =>
+          `- ${inlineCode(status)}${response.description?.trim() ? ` — ${oneLine(response.description)}` : ""}`
+      )
+      .join("\n"),
+    ...examples,
+  ];
+};
+
+/**
+ * An operation's body and responses as Markdown blocks, `$ref`s to
+ * `components` resolved, ready to join with blank lines.
+ */
+export const operationDetails = (
+  document: ApiDocument,
+  operation: OperationParts,
+  webhook: boolean
+): string[] => {
+  // SAFETY: a parsed document's `components` is the section-keyed table
+  // `ComponentsLike` describes; the helpers guard every entry they read.
+  const components = document.components as ComponentsLike | undefined;
+  // SAFETY: component schemas are the JSON Schema objects `SchemaLike` views.
+  const schemas = (document.components?.schemas ?? {}) as Record<
+    string,
+    SchemaLike
+  >;
+  const body = operation.requestBody
+    ? resolveComponentRef(operation.requestBody, components, "requestBodies")
+    : undefined;
+  const responses = Object.fromEntries(
+    Object.entries(operation.responses ?? {}).map(([status, response]) => [
+      status,
+      resolveComponentRef(response, components, "responses"),
+    ])
+  );
+  return [
+    ...(body ? bodyMarkdown(body, schemas, components, webhook) : []),
+    ...responsesMarkdown(responses, schemas, components),
+  ];
+};