blume 1.7.3 → 2.0.0

package/src/openapi/references.ts

@@ -1,25 +1,32 @@
 import { normalizeRoute, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
+import type { ScalarOptions } from "../reference/scalar.ts";
+import type { ResolvedReferenceAdapter } from "../reference/schema.ts";
 
 // Re-exported from its home next to the other path helpers; `core/schema.ts`
 // and downstream consumers historically imported it from here.
 export { normalizeRoute } from "../core/base-path.ts";
 
 /**
- * Pure resolution of the configured API reference blocks into concrete routes,
- * labels, and a renderer choice — no file IO, so the content source, the
+ * Pure resolution of the configured `reference` adapters into concrete routes
+ * and labels — no file IO, so the content source, the
  * nav-target validation, the Scalar page generator, and the `blume:openapi`
  * data module all share one source of truth. Kept free of any Astro/template
  * imports so `core` can depend on it without a cycle.
  */
 
-export type ReferenceKind = "openapi" | "asyncapi" | "graphql";
+/**
+ * Which adapter a reference came from. `openapi`, `asyncapi`, and `graphql`
+ * are rendered by Blume into real pages; `scalar` is the embedded Scalar SPA
+ * on a single route.
+ */
+export type ReferenceKind = ResolvedReferenceAdapter["kind"];
 
-/** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
-export type ReferenceRenderer = "blume" | "scalar";
+/** The kinds Blume renders into pages itself — everything but the Scalar embed. */
+export type BlumeReferenceKind = Exclude<ReferenceKind, "scalar">;
 
-/** Per-block display options for the Blume renderer. */
+/** Per-adapter display options for the Blume renderer. */
 export interface ReferenceDisplay {
   /** Code-sample languages shown per operation. */
   codeSamples: string[];
@@ -33,10 +40,9 @@ export interface ReferenceDisplay {
   playground: { enabled: boolean; proxy: string | boolean };
 }
 
-/** A spec source resolved to a concrete route, label, and renderer. */
+/** A spec source resolved to a concrete route and label. */
 export interface ReferenceSource {
   kind: ReferenceKind;
-  renderer: ReferenceRenderer;
   /** Unique token derived from the route; the `<Operation source>` / data key. */
   slug: string;
   /** Normalized route the reference mounts at, e.g. `/reference`. */
@@ -66,14 +72,12 @@ export interface ReferenceSource {
    * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
    */
   endpoint?: string;
-  /** Per-block Scalar theme name override, if any (Scalar renderer only). */
-  theme?: string;
   /**
-   * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
-   * only). Takes precedence over Blume's derived spec/theme config. Typed off
-   * the config schema so the two can never drift.
+   * The `scalar()` adapter's own options (`scalar` kind only): `theme` plus
+   * any Scalar config forwarded verbatim to `<ScalarComponent>`, which takes
+   * precedence over Blume's derived spec/theme config.
    */
-  scalar?: ResolvedConfig["openapi"]["scalar"];
+  scalar?: ScalarOptions;
   /** Display options carried through to the Blume renderer. */
   display: ReferenceDisplay;
   /**
@@ -83,6 +87,14 @@ export interface ReferenceSource {
   collisions?: string[];
 }
 
+/** A reference Blume renders itself: one the content pipeline stages pages for. */
+export type BlumeReferenceSource = ReferenceSource & {
+  kind: BlumeReferenceKind;
+};
+
+const isBlumeReference = (ref: ReferenceSource): ref is BlumeReferenceSource =>
+  ref.kind !== "scalar";
+
 // Keep Unicode letters/marks/numbers so diacritics stay in the slug (ASCII-only
 // stripping turned `Größe` into `gr-e`, which the nav humanizer rendered as
 // `Gr E`); `\p{M}` keeps combining marks attached to their base letter, which
@@ -119,59 +131,95 @@ export const slugify = (text: string): string =>
 const routeSlug = (route: string): string =>
   slugify(trimChar(route, "/")) || "reference";
 
+/** The label a source gets when it names none (numbered when there are several). */
+const DEFAULT_LABELS: Record<ReferenceKind, string> = {
+  asyncapi: "Events",
+  graphql: "GraphQL",
+  openapi: "API Reference",
+  scalar: "API Reference",
+};
+
+/** The Blume renderer has nothing to show for a Scalar embed. */
+const NO_DISPLAY: ReferenceDisplay = {
+  codeSamples: [],
+  expandSchemas: false,
+  playground: { enabled: false, proxy: false },
+};
+
+const displayOf = (adapter: ResolvedReferenceAdapter): ReferenceDisplay => {
+  if (adapter.kind === "scalar") {
+    return NO_DISPLAY;
+  }
+  return {
+    codeSamples: adapter.options.codeSamples,
+    // GraphQL field tables have no nesting, so `graphql()` takes no
+    // `expandSchemas` toggle.
+    expandSchemas:
+      adapter.kind === "graphql" ? false : adapter.options.expandSchemas,
+    playground: adapter.options.playground,
+  };
+};
+
 /**
- * The structural shape all three reference blocks (`openapi`, `asyncapi`,
- * `graphql`) share. `endpoint` exists only on the GraphQL block and its
- * sources; `scalar`/`theme` only on the Scalar-capable kinds — optional here
- * so one resolver serves every block.
+ * A `scalar()` adapter's options minus the ones Blume resolves itself
+ * (`route`, `sources`): `theme` and the verbatim Scalar passthrough, which
+ * the generated page inlines.
  */
-interface Block {
-  enabled: boolean;
+const scalarOptionsOf = (
+  options: Extract<ResolvedReferenceAdapter, { kind: "scalar" }>["options"]
+): ScalarOptions =>
+  Object.fromEntries(
+    Object.entries(options).filter(
+      ([key]) => key !== "route" && key !== "sources"
+    )
+  );
+
+/** A source row with every kind's fields reconciled onto one shape. */
+interface SourceRow {
   endpoint?: string;
-  route: string;
-  scalar?: ResolvedConfig["openapi"]["scalar"];
-  sources: {
-    endpoint?: string;
-    includeInLlms: boolean;
-    includeInSearch: boolean;
-    label?: string;
-    noindex: boolean;
-    route?: string;
-    seoDescriptionSuffix: boolean;
-    spec: string;
-  }[];
-  spec?: string;
-  theme?: string;
+  includeInLlms: boolean;
+  includeInSearch: boolean;
+  label?: string;
+  noindex: boolean;
+  route?: string;
+  seoDescriptionSuffix: boolean;
+  spec: string;
 }
 
-/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
-const sourcesOf = (block: Block): Block["sources"] => {
-  const sources = [...block.sources];
-  if (block.spec) {
-    sources.unshift({
-      includeInLlms: true,
-      includeInSearch: true,
-      noindex: false,
-      seoDescriptionSuffix: true,
-      spec: block.spec,
-    });
+/**
+ * One row per source, with the kind-specific fields already reconciled: a
+ * GraphQL source's `endpoint` falls back to the adapter-wide default (the
+ * common single-schema case pairs it with the `spec` shorthand); the other
+ * kinds have no endpoint at all. A Scalar source carries only `noindex` of
+ * the per-source controls — the embed sits outside search and llms.txt, so
+ * the other two read as off.
+ */
+const sourceRowsOf = (adapter: ResolvedReferenceAdapter): SourceRow[] => {
+  if (adapter.kind === "graphql") {
+    return adapter.options.sources.map((source) => ({
+      ...source,
+      endpoint: source.endpoint ?? adapter.options.endpoint,
+    }));
+  }
+  if (adapter.kind === "scalar") {
+    return adapter.options.sources.map((source) => ({
+      ...source,
+      includeInLlms: false,
+      includeInSearch: false,
+      seoDescriptionSuffix: false,
+    }));
   }
-  return sources;
+  return adapter.options.sources;
 };
 
 const referencesFor = (
-  kind: ReferenceKind,
-  block: Block,
-  defaultLabel: string,
-  renderer: ReferenceRenderer,
-  display: ReferenceDisplay,
+  adapter: ResolvedReferenceAdapter,
   basePath: string
 ): ReferenceSource[] => {
-  if (!block.enabled) {
-    return [];
-  }
-  const sources = sourcesOf(block);
-  const base = normalizeRoute(block.route);
+  const sources = sourceRowsOf(adapter);
+  const base = normalizeRoute(adapter.options.route);
+  const defaultLabel = DEFAULT_LABELS[adapter.kind];
+  const display = displayOf(adapter);
 
   return sources.map((source, index) => {
     const label =
@@ -193,77 +241,36 @@ const referencesFor = (
       display,
       includeInLlms: source.includeInLlms,
       includeInSearch: source.includeInSearch,
-      kind,
+      kind: adapter.kind,
       label,
       noindex: source.noindex,
-      renderer,
       route,
-      scalar: block.scalar,
       seoDescriptionSuffix: source.seoDescriptionSuffix,
       slug: routeSlug(route),
       spec: source.spec,
-      theme: block.theme,
     };
-    // Per-source endpoint wins; the block-level one is the shared default
-    // (the common single-schema case pairs it with the `spec` shorthand).
-    const endpoint = source.endpoint ?? block.endpoint;
-    if (endpoint !== undefined) {
-      reference.endpoint = endpoint;
+    if (adapter.kind === "scalar") {
+      reference.scalar = scalarOptionsOf(adapter.options);
+    }
+    if (source.endpoint !== undefined) {
+      reference.endpoint = source.endpoint;
     }
     return reference;
   });
 };
 
 /**
- * Resolve every enabled reference. Both blocks honor their `renderer` —
- * Blume's own UI by default, with the embedded Scalar SPA as the opt-out.
+ * Resolve every configured reference, in `reference` order: Blume's own pages
+ * for `openapi()`, `asyncapi()`, and `graphql()`, and one embedded Scalar page
+ * per `scalar()` source.
  */
-export const resolveReferences = (
-  config: ResolvedConfig
-): ReferenceSource[] => [
-  ...referencesFor(
-    "openapi",
-    config.openapi,
-    "API Reference",
-    config.openapi.renderer,
-    {
-      codeSamples: config.openapi.codeSamples,
-      expandSchemas: config.openapi.expandSchemas,
-      playground: config.openapi.playground,
-    },
-    config.basePath
-  ),
-  ...referencesFor(
-    "asyncapi",
-    config.asyncapi,
-    "Events",
-    config.asyncapi.renderer,
-    {
-      codeSamples: config.asyncapi.codeSamples,
-      expandSchemas: config.asyncapi.expandSchemas,
-      playground: config.asyncapi.playground,
-    },
-    config.basePath
-  ),
-  // GraphQL is always Blume-rendered — Scalar's embedded SPA reads OpenAPI
-  // documents only, so the block declares no `renderer` opt-out (nor the
-  // schema-row `expandSchemas` toggle; GraphQL field tables have no nesting).
-  ...referencesFor(
-    "graphql",
-    config.graphql,
-    "GraphQL",
-    "blume",
-    {
-      codeSamples: config.graphql.codeSamples,
-      expandSchemas: false,
-      playground: config.graphql.playground,
-    },
-    config.basePath
-  ),
-];
+export const resolveReferences = (config: ResolvedConfig): ReferenceSource[] =>
+  config.reference.flatMap((adapter) =>
+    referencesFor(adapter, config.basePath)
+  );
 
 /**
- * Mounted route for every reference, regardless of renderer. References no
+ * Mounted route for every reference, regardless of kind. References no
  * longer add a header tab automatically — authors point a `navigation.tabs`
  * entry at one of these routes to surface it (and, for Blume-rendered specs, to
  * scope its operations sidebar). These routes are whitelisted as valid nav
@@ -274,9 +281,7 @@ export const referenceRoutes = (config: ResolvedConfig): string[] =>
     // Blume-rendered operation pages flow through the content pipeline and are
     // mounted under `basePath`. Scalar references are a single embedded page
     // injected at the raw `route`, left root-anchored.
-    ref.renderer === "blume"
-      ? withBasePath(config.basePath, ref.route)
-      : ref.route
+    ref.kind === "scalar" ? ref.route : withBasePath(config.basePath, ref.route)
   );
 
 /**
@@ -287,10 +292,10 @@ export const referenceRoutes = (config: ResolvedConfig): string[] =>
  */
 const blumeReferenceOf = (
   ref: ReferenceSource,
-  seen: Map<string, ReferenceSource>,
+  seen: Map<string, BlumeReferenceSource>,
   usedSlugs: Set<string>
-): ReferenceSource | null => {
-  if (ref.renderer !== "blume") {
+): BlumeReferenceSource | null => {
+  if (!isBlumeReference(ref)) {
     return null;
   }
   const kept = seen.get(ref.route);
@@ -318,11 +323,13 @@ const blumeReferenceOf = (
   return accepted;
 };
 
-/** Blume-rendered references (both kinds), deduped by route (first wins). */
-export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
-  const seen = new Map<string, ReferenceSource>();
+/** Blume-rendered references (every kind but Scalar), deduped by route (first wins). */
+export const blumeReferences = (
+  config: ResolvedConfig
+): BlumeReferenceSource[] => {
+  const seen = new Map<string, BlumeReferenceSource>();
   const usedSlugs = new Set<string>();
-  const result: ReferenceSource[] = [];
+  const result: BlumeReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
     const accepted = blumeReferenceOf(ref, seen, usedSlugs);
     if (accepted) {
@@ -332,42 +339,35 @@ export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
   return result;
 };
 
-/** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
+/** Whether any reference is Scalar-rendered (gates the Scalar pages). */
 export const hasScalarReferences = (config: ResolvedConfig): boolean =>
-  resolveReferences(config).some((ref) => ref.renderer === "scalar");
+  resolveReferences(config).some((ref) => ref.kind === "scalar");
 
 /**
- * The reference kinds whose enabled, Blume-rendered playground opted into the
+ * The Blume-rendered references whose enabled playground opted into the
  * built-in CORS proxy with `proxy: true`. A proxy URL string points at an
  * external service, and `false` sends requests directly — neither routes
- * through the endpoint. The generator's per-spec allowlist diagnostics key on
- * this, so it shares one definition with {@link needsPlaygroundProxy}.
+ * through the endpoint. AsyncAPI never does: an event composer's WebSocket
+ * connect is direct, so its `proxy` has nothing to forward. Drawn from the
+ * deduped set so the slugs match the `blume:openapi` data keys; the
+ * generator's per-spec allowlist diagnostics key on this, so it shares one
+ * definition with {@link needsPlaygroundProxy}.
  */
-export const builtinProxyKinds = (config: ResolvedConfig): ReferenceKind[] => {
-  const kinds: ReferenceKind[] = [];
-  if (
-    config.openapi.enabled &&
-    config.openapi.renderer === "blume" &&
-    config.openapi.playground.enabled &&
-    config.openapi.playground.proxy === true
-  ) {
-    kinds.push("openapi");
-  }
-  if (
-    config.graphql.enabled &&
-    config.graphql.playground.enabled &&
-    config.graphql.playground.proxy === true
-  ) {
-    kinds.push("graphql");
-  }
-  return kinds;
-};
+export const builtinProxyReferences = (
+  config: ResolvedConfig
+): BlumeReferenceSource[] =>
+  blumeReferences(config).filter(
+    (ref) =>
+      ref.kind !== "asyncapi" &&
+      ref.display.playground.enabled &&
+      ref.display.playground.proxy === true
+  );
 
 /**
  * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
- * generated: some enabled Blume-rendered block's playground opted into it with
+ * generated: some Blume-rendered reference's playground opted into it with
  * `proxy: true`. Shared by the server feature gate and the generator so the
  * two can never disagree.
  */
 export const needsPlaygroundProxy = (config: ResolvedConfig): boolean =>
-  builtinProxyKinds(config).length > 0;
+  builtinProxyReferences(config).length > 0;

package/src/openapi/render-mdx.ts

@@ -1,14 +1,16 @@
-import type { Nodes } from "mdast";
+import type { Nodes, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
 
 import { apiNamePhrase } from "../core/api-name.ts";
+import { unsafeLinkSpans } from "../core/safe-links.ts";
 import { columnsPrefix } from "../core/text-width.ts";
 import type { GraphqlMember } from "./graphql.ts";
 import { isGraphqlOperationKind } from "./graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
+import { asSentence } from "./sentence.ts";
 import { operationSignature } from "./signature.ts";
 
 /**
@@ -60,7 +62,7 @@ const escapeProse = (text: string): string =>
  * whose braces genuinely need escaping; fence-or-backtick is told apart from
  * indentation by the construct's first character.
  */
-const codeSpans = (text: string): [number, number][] => {
+const codeSpans = (text: string, tree: Root): [number, number][] => {
   const spans: [number, number][] = [];
   const collect = (node: Nodes): void => {
     if (node.type === "inlineCode" || node.type === "code") {
@@ -84,18 +86,33 @@ const codeSpans = (text: string): [number, number][] => {
       }
     }
   };
-  collect(fromMarkdown(text));
+  collect(tree);
   return spans;
 };
 
-/** Escape MDX-special syntax in prose while leaving code verbatim. */
+/**
+ * Escape MDX-special syntax in prose while leaving code verbatim. A spec is
+ * someone else's content, so a link whose destination isn't a web, mail, or
+ * relative address (`javascript:`, `data:`) is reduced to its label rather
+ * than rendered clickable on the docs site (see `core/safe-links.ts`).
+ */
 const mdxSafe = (text: string): string => {
+  const tree = fromMarkdown(text);
+  const unsafe = unsafeLinkSpans(tree);
+  const insideUnsafe = (offset: number): boolean =>
+    unsafe.some((span) => offset >= span.start && offset < span.end);
+  const segments = [
+    ...codeSpans(text, tree)
+      .filter(([start]) => !insideUnsafe(start))
+      .map(([start, end]) => ({ end, start, text: text.slice(start, end) })),
+    ...unsafe,
+  ].toSorted((a, b) => a.start - b.start);
   let out = "";
   let cursor = 0;
-  for (const [start, end] of codeSpans(text)) {
-    out += escapeProse(text.slice(cursor, start));
-    out += text.slice(start, end);
-    cursor = end;
+  for (const segment of segments) {
+    out += escapeProse(text.slice(cursor, segment.start));
+    out += segment.text;
+    cursor = segment.end;
   }
   return out + escapeProse(text.slice(cursor));
 };
@@ -208,11 +225,16 @@ const operationDescription = (
     subject = `${operation.method.toUpperCase()} ${operation.path} endpoint`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
+  // Room for the joining space and the period `asSentence` may add, so a
+  // title-like summary ("Get a flag") ends before the suffix begins.
   const prose = clip(
     plainProse(operation.description || operation.summary),
-    META_DESCRIPTION_MAX - stringWidth(suffix) - 1
+    META_DESCRIPTION_MAX - stringWidth(suffix) - 2
+  );
+  return clip(
+    [asSentence(prose), suffix].filter(Boolean).join(" "),
+    META_DESCRIPTION_MAX
   );
-  return clip([prose, suffix].filter(Boolean).join(" "), META_DESCRIPTION_MAX);
 };
 
 /** Prepend a markdown description (if any) above a component invocation. */

package/src/openapi/scalar.ts

@@ -10,11 +10,10 @@ import { resolveReferences } from "./references.ts";
 import type { ReferenceSource } from "./references.ts";
 
 /**
- * The Scalar renderer: an escape hatch (`openapi.renderer: "scalar"`) and the
- * path AsyncAPI still uses. Each Scalar-rendered spec becomes one self-contained
- * `@scalar/astro` page loaded client-side from Scalar's CDN. Blume's own OpenAPI
- * renderer (the default) lives in `source.ts` / the `components/openapi` set and
- * does not pass through here.
+ * The `scalar()` adapter's pages. Each source becomes one self-contained
+ * `@scalar/astro` page loaded client-side from Scalar's CDN. Blume's own
+ * renderer (`openapi()`, `asyncapi()`, `graphql()`) lives in `source.ts` /
+ * the `components/openapi` set and does not pass through here.
  */
 
 /** A generated Scalar reference page, ready to write under `src/pages`. */
@@ -88,7 +87,7 @@ const acceptScalarReference = (
   contentRoutes: ReadonlySet<string>,
   warnings: string[]
 ): ReferenceSource | null => {
-  if (ref.renderer !== "scalar") {
+  if (ref.kind !== "scalar") {
     return null;
   }
   if (seen.has(ref.route)) {
@@ -108,8 +107,8 @@ const acceptScalarReference = (
 };
 
 /**
- * Build the Scalar reference page(s) for the project. Only Scalar-rendered
- * references are emitted here (Blume-rendered OpenAPI is staged content). Reads
+ * Build the Scalar reference page(s) for the project. Only `scalar()`
+ * references are emitted here (Blume-rendered kinds are staged content). Reads
  * local specs, maps the theme, and skips routes that collide with a content page
  * or another source. Returns the files to write under `src/pages` plus warnings.
  */
@@ -144,15 +143,18 @@ export const buildReferenceFiles = async (options: {
       warnings.push(spec.warning);
     }
     const pagePath = referencePagePath(ref.route);
+    // `theme` is the one option Blume maps (a named theme replaces the
+    // accent/radius layering); every other `scalar()` option is forwarded
+    // verbatim and wins outright — a full escape hatch over Blume's derived
+    // spec/theme config (localization, agent, hideTestRequestButton,
+    // orderSchemaPropertiesBy, customCss, and the rest).
+    const { theme, ...passthrough } = ref.scalar ?? {};
     files.push({
       content: scalarReferenceTemplate({
         configuration: {
           ...spec.config,
-          ...themeConfiguration(config, ref.theme),
-          // Author-supplied Scalar options win outright — a full escape hatch
-          // over Blume's derived spec/theme config (localization, agent,
-          // hideTestRequestButton, orderSchemaPropertiesBy, and the rest).
-          ...ref.scalar,
+          ...themeConfiguration(config, theme),
+          ...passthrough,
         },
         noindex: ref.noindex,
         route: ref.route,

package/src/openapi/sentence.ts

@@ -0,0 +1,14 @@
+/**
+ * A sentence's closing punctuation, allowing trailing closing quotes or
+ * brackets (`…done.")`) and the CJK full-width marks.
+ */
+const TERMINAL_PUNCTUATION = /[.!?…。！？]["'”’)\]]*$/u;
+
+/**
+ * Close a fragment of spec prose as a sentence. OpenAPI `summary` values are
+ * usually title-like ("Get a flag", no period), so prose that runs straight
+ * into the next generated sentence ("Get a flag Reference for …") needs one.
+ * Empty text stays empty.
+ */
+export const asSentence = (text: string): string =>
+  text === "" || TERMINAL_PUNCTUATION.test(text) ? text : `${text}.`;