blume 0.3.0 → 0.5.0

package/src/openapi/model.ts

@@ -0,0 +1,174 @@
+import type {
+  Document,
+  OperationObject,
+  PathItemObject,
+} from "@scalar/openapi-types/3.1";
+
+/**
+ * Blume's own OpenAPI model. Specs are parsed and upgraded to 3.1 (see
+ * `parse.ts`) with internal `$ref`s left intact — the document stays
+ * JSON-serializable (a fully dereferenced graph can be circular), and the schema
+ * components resolve refs against `document.components.schemas` at render time.
+ * Each operation is flattened into an {@link ApiOperationRef} with a real,
+ * per-operation route so it becomes a first-class Blume page.
+ */
+
+/** A normalized OpenAPI 3.1 document, internal `$ref`s intact. */
+export type ApiDocument = Document;
+
+const NON_SLUG = /[^a-z0-9]+/gu;
+const SLUG_EDGES = /^-+|-+$/gu;
+
+/** Lowercase, URL-safe slug: `Add a Pet!` -> `add-a-pet`. */
+export const slugify = (text: string): string =>
+  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+
+/** The HTTP methods an OpenAPI path item may declare, in spec order. */
+export const HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+] as const;
+
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+
+/** Group used for operations that declare no tag. */
+const UNTAGGED = "Operations";
+
+/** A stable, URL-safe key for an operation: its `operationId`, else method+path. */
+export const operationKey = (
+  method: string,
+  path: string,
+  operationId?: string
+): string => {
+  const fromId = operationId ? slugify(operationId) : "";
+  return fromId || slugify(`${method}-${path}`);
+};
+
+/** One operation, flattened out of the paths object and mapped to a route. */
+export interface ApiOperationRef {
+  /** Stable key, unique within a spec; matches the MDX `<Operation id>`. */
+  key: string;
+  method: HttpMethod;
+  /** Templated path, e.g. `/pets/{id}`. */
+  path: string;
+  /** Full site route for this operation's page, e.g. `/reference/pet/add-pet`. */
+  route: string;
+  /** Display tag name (first tag, or `Operations` when untagged). */
+  tag: string;
+  tagSlug: string;
+  summary: string;
+  description: string;
+  operationId?: string;
+  deprecated: boolean;
+}
+
+/** A tag/section, in first-seen order. */
+export interface ApiTagRef {
+  slug: string;
+  name: string;
+  description: string;
+}
+
+/** Everything the runtime needs for one spec, serialized into `blume:openapi`. */
+export interface ApiSpecData {
+  /** Unique token used as the `<Operation source>` and the data-module key. */
+  slug: string;
+  /** Base route the spec's operations hang off, e.g. `/reference`. */
+  route: string;
+  label: string;
+  title: string;
+  version: string;
+  description: string;
+  document: ApiDocument;
+  /** Operations keyed by {@link ApiOperationRef.key}. */
+  operations: Record<string, ApiOperationRef>;
+  tags: ApiTagRef[];
+  /** Code-sample languages to render per operation. */
+  codeSamples: string[];
+  /** Whether nested schema rows start expanded. */
+  expandSchemas: boolean;
+}
+
+/** The generated `blume:openapi` module: specs keyed by {@link ApiSpecData.slug}. */
+export type OpenApiData = Record<string, ApiSpecData>;
+
+const isOperation = (value: unknown): value is OperationObject =>
+  typeof value === "object" && value !== null;
+
+/**
+ * Flatten a 3.1 document into a route-mapped operation list and its ordered
+ * tags. Operations inherit the first tag they declare; keys are de-duplicated so
+ * a repeated `operationId` still yields distinct routes.
+ */
+export const extractOperations = (
+  document: ApiDocument,
+  baseRoute: string
+): { operations: ApiOperationRef[]; tags: ApiTagRef[] } => {
+  const operations: ApiOperationRef[] = [];
+  const tagOrder: string[] = [];
+  const tagMeta = new Map(
+    (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
+  );
+  const seen = new Set<string>();
+
+  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
+    const item = rawItem as PathItemObject | undefined;
+    if (!item || "$ref" in item) {
+      continue;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      if (!isOperation(operation)) {
+        continue;
+      }
+      const tag = operation.tags?.[0] ?? UNTAGGED;
+      const tagSlug = slugify(tag) || "operations";
+      if (!tagOrder.includes(tag)) {
+        tagOrder.push(tag);
+      }
+      let key = operationKey(method, path, operation.operationId);
+      while (seen.has(key)) {
+        key = `${key}-${method}`;
+      }
+      seen.add(key);
+      operations.push({
+        deprecated: operation.deprecated ?? false,
+        description: operation.description ?? "",
+        key,
+        method,
+        operationId: operation.operationId,
+        path,
+        route: `${baseRoute}/${tagSlug}/${key}`,
+        summary: operation.summary ?? "",
+        tag,
+        tagSlug,
+      });
+    }
+  }
+
+  const tags: ApiTagRef[] = tagOrder.map((name) => ({
+    description: tagMeta.get(name) ?? "",
+    name,
+    slug: slugify(name) || "operations",
+  }));
+
+  return { operations, tags };
+};
+
+/** Resolve the operation object for a ref out of its document. */
+export const operationObject = (
+  spec: ApiSpecData,
+  ref: ApiOperationRef
+): OperationObject | undefined => {
+  const item = (spec.document.paths?.[ref.path] ?? undefined) as
+    | PathItemObject
+    | undefined;
+  const operation = item?.[ref.method];
+  return isOperation(operation) ? operation : undefined;
+};

package/src/openapi/parse.ts

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+
+import { normalize, upgrade } from "@scalar/openapi-parser";
+import { isAbsolute, join } from "pathe";
+
+import type { ApiDocument } from "./model.ts";
+
+/**
+ * Spec loading and normalization. Blume reuses Scalar's parser
+ * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
+ * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
+ * Internal `$ref`s are deliberately left in place (see `model.ts`).
+ */
+
+const URL_SPEC = /^https?:\/\//u;
+
+export interface ParsedSpec {
+  document: ApiDocument;
+  warnings: string[];
+}
+
+/** Read a spec's raw text from an `http(s)` URL or a local (project-relative) path. */
+const readSpecText = async (spec: string, root: string): Promise<string> => {
+  if (URL_SPEC.test(spec)) {
+    const response = await fetch(spec);
+    if (!response.ok) {
+      throw new Error(`${spec} -> ${response.status} ${response.statusText}`);
+    }
+    return await response.text();
+  }
+  const absolute = isAbsolute(spec) ? spec : join(root, spec);
+  return await readFile(absolute, "utf-8");
+};
+
+/**
+ * Read, normalize, and upgrade a spec to an OpenAPI 3.1 document. Throws when the
+ * spec can't be read; callers turn that into a source diagnostic rather than a
+ * hard failure so a broken spec doesn't take down the whole build.
+ */
+export const parseSpec = async (
+  spec: string,
+  root: string
+): Promise<ParsedSpec> => {
+  const text = await readSpecText(spec, root);
+  const normalized = normalize(text);
+  const { specification } = upgrade(normalized);
+  return { document: specification as ApiDocument, warnings: [] };
+};

package/src/openapi/references.ts

@@ -0,0 +1,164 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { NavTab } from "../core/types.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 nav
+ * tabs, 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";
+
+/** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
+export type ReferenceRenderer = "blume" | "scalar";
+
+/** Per-block display options for the Blume renderer. */
+export interface ReferenceDisplay {
+  /** Code-sample languages shown per operation. */
+  codeSamples: string[];
+  /** Whether nested schema rows start expanded. */
+  expandSchemas: boolean;
+}
+
+/** A spec source resolved to a concrete route, label, and renderer. */
+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`. */
+  route: string;
+  label: string;
+  /** Local path or `http(s)` URL, verbatim from config. */
+  spec: string;
+  /** Per-block Scalar theme name override, if any (Scalar renderer only). */
+  theme?: string;
+  /** Display options carried through to the Blume renderer. */
+  display: ReferenceDisplay;
+}
+
+const NON_SLUG = /[^a-z0-9]+/gu;
+const SLUG_EDGES = /^-+|-+$/gu;
+const ROUTE_EDGES = /^\/+|\/+$/gu;
+const TRAILING_SLASH = /\/+$/u;
+
+export const slugify = (text: string): string =>
+  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+
+/** Normalize a configured route to a single leading slash, no trailing slash. */
+export const normalizeRoute = (route: string): string => {
+  const trimmed = route.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
+  return noTrailing === "" ? "/" : noTrailing;
+};
+
+/** A stable per-reference token from its route: `/api/events` -> `api-events`. */
+const routeSlug = (route: string): string =>
+  slugify(route.replace(ROUTE_EDGES, "")) || "reference";
+
+type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
+
+/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
+const sourcesOf = (
+  block: Block
+): { label?: string; route?: string; spec: string }[] => {
+  const sources = [...block.sources];
+  if (block.spec) {
+    sources.unshift({ spec: block.spec });
+  }
+  return sources;
+};
+
+const referencesFor = (
+  kind: ReferenceKind,
+  block: Block,
+  defaultLabel: string,
+  renderer: ReferenceRenderer,
+  display: ReferenceDisplay
+): ReferenceSource[] => {
+  if (!block.enabled) {
+    return [];
+  }
+  const sources = sourcesOf(block);
+  const base = normalizeRoute(block.route);
+
+  return sources.map((source, index) => {
+    const label =
+      source.label ??
+      (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
+
+    let route: string;
+    if (source.route) {
+      route = normalizeRoute(source.route);
+    } else if (sources.length === 1) {
+      route = base;
+    } else {
+      const suffix = source.label ? slugify(source.label) : "";
+      route = normalizeRoute(`${base}/${suffix || index + 1}`);
+    }
+
+    return {
+      display,
+      kind,
+      label,
+      renderer,
+      route,
+      slug: routeSlug(route),
+      spec: source.spec,
+      theme: block.theme,
+    };
+  });
+};
+
+const NO_DISPLAY: ReferenceDisplay = { codeSamples: [], expandSchemas: false };
+
+/**
+ * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
+ * by default); AsyncAPI is always rendered by Scalar for now.
+ */
+export const resolveReferences = (
+  config: ResolvedConfig
+): ReferenceSource[] => [
+  ...referencesFor(
+    "openapi",
+    config.openapi,
+    "API Reference",
+    config.openapi.renderer,
+    {
+      codeSamples: config.openapi.codeSamples,
+      expandSchemas: config.openapi.expandSchemas,
+    }
+  ),
+  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY),
+];
+
+/** Nav tabs (header links) for every reference, regardless of renderer. */
+export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
+  resolveReferences(config).map((ref) => ({
+    label: ref.label,
+    path: ref.route,
+  }));
+
+/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
+  const seen = new Set<string>();
+  const result: ReferenceSource[] = [];
+  for (const ref of resolveReferences(config)) {
+    if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+      continue;
+    }
+    if (seen.has(ref.route)) {
+      continue;
+    }
+    seen.add(ref.route);
+    result.push(ref);
+  }
+  return result;
+};
+
+/** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
+export const hasScalarReferences = (config: ResolvedConfig): boolean =>
+  resolveReferences(config).some((ref) => ref.renderer === "scalar");

package/src/openapi/render-mdx.ts

@@ -0,0 +1,76 @@
+import type { ApiOperationRef, ApiSpecData } from "./model.ts";
+
+/**
+ * Lower a parsed spec into MDX for the staged content source. Each operation and
+ * the spec overview become a thin MDX page: the frontmatter carries the
+ * searchable `title` (so operations flow into Blume's search, OG, and llms.txt),
+ * the operation/overview **description is emitted as markdown in the body** so it
+ * renders parsed (links, formatting) and is indexed, and the structured UI is
+ * deferred to a Blume-owned component (`<Operation>` / `<ApiOverview>`). The
+ * catch-all renders the frontmatter title as the page `<h1>`, so the components
+ * omit their own top heading.
+ */
+
+// Neutralize the few characters MDX treats specially (`{` expressions, `<` JSX)
+// so an arbitrary spec description can be embedded in the body verbatim without
+// breaking compilation. They render as their literal selves.
+const MDX_UNSAFE = /[<>{}]/gu;
+const ENTITIES: Record<string, string> = {
+  "<": "&lt;",
+  ">": "&gt;",
+  "{": "&#123;",
+  "}": "&#125;",
+};
+const mdxSafe = (text: string): string =>
+  text.replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char);
+
+/** Frontmatter + body for one operation or overview page. */
+export interface RenderedPage {
+  data: Record<string, unknown>;
+  body: string;
+}
+
+/** Prepend a markdown description (if any) above a component invocation. */
+const withDescription = (description: string, component: string): string =>
+  description.trim()
+    ? `${mdxSafe(description.trim())}\n\n${component}`
+    : component;
+
+export const operationMdx = (
+  spec: ApiSpecData,
+  operation: ApiOperationRef
+): RenderedPage => {
+  const method = operation.method.toUpperCase();
+  const title = operation.summary || `${method} ${operation.path}`;
+  // Skip the body description when it only repeats the summary (the `<h1>`) —
+  // common in specs that set summary and description to the same string.
+  const description =
+    operation.description.trim() === operation.summary.trim()
+      ? ""
+      : operation.description;
+  return {
+    body: withDescription(
+      description,
+      `<Operation source="${spec.slug}" id="${operation.key}" />`
+    ),
+    data: {
+      ...(operation.deprecated ? { deprecated: true } : {}),
+      search: { tags: [operation.tag, method] },
+      sidebar: { badge: method, label: operation.summary || operation.path },
+      title,
+      // Signals the two-column API layout (request panel instead of the TOC).
+      type: "openapi-operation",
+    },
+  };
+};
+
+export const overviewMdx = (spec: ApiSpecData): RenderedPage => ({
+  body: withDescription(
+    spec.description,
+    `<ApiOverview source="${spec.slug}" />`
+  ),
+  data: {
+    sidebar: { label: "Overview" },
+    title: spec.title || spec.label,
+  },
+});

package/src/openapi/scalar.ts

@@ -4,32 +4,19 @@ import { isAbsolute, join } from "pathe";
 
 import { scalarReferenceTemplate } from "../astro/templates.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import type { NavTab } from "../core/types.ts";
 import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+import { resolveReferences } from "./references.ts";
+import type { ReferenceSource } from "./references.ts";
 
 /**
- * API reference support, delegated wholesale to Scalar (`@scalar/astro`). Blume
- * resolves the configured spec sources into routes, generates one self-contained
- * Scalar page per source, and adds a nav tab. OpenAPI and AsyncAPI share this
- * exact path — Scalar auto-detects the document type — so the only difference
- * between the two config blocks is their default route and nav label.
+ * 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.
  */
 
-type ReferenceKind = "openapi" | "asyncapi";
-
-/** A spec source resolved to a concrete route and nav label. */
-export interface ReferenceSource {
-  kind: ReferenceKind;
-  /** Normalized route the reference mounts at, e.g. `/reference`. */
-  route: string;
-  label: string;
-  /** Local path or `http(s)` URL, verbatim from config. */
-  spec: string;
-  /** Per-block Scalar theme name override, if any. */
-  theme?: string;
-}
-
-/** A generated reference page, ready to write under `src/pages`. */
+/** A generated Scalar reference page, ready to write under `src/pages`. */
 export interface ReferenceFile {
   /** Path relative to `src/pages`, e.g. `reference.astro`, `api/events.astro`. */
   pagePath: string;
@@ -37,21 +24,7 @@ export interface ReferenceFile {
 }
 
 const URL_SPEC = /^https?:\/\//u;
-const NON_SLUG = /[^a-z0-9]+/gu;
-const SLUG_EDGES = /^-+|-+$/gu;
 const ROUTE_EDGES = /^\/+|\/+$/gu;
-const TRAILING_SLASH = /\/+$/u;
-
-const slugify = (text: string): string =>
-  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
-
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-const normalizeRoute = (route: string): string => {
-  const trimmed = route.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
-  return noTrailing === "" ? "/" : noTrailing;
-};
 
 /** The `src/pages`-relative file path for a reference route. */
 const referencePagePath = (route: string): string => {
@@ -59,71 +32,6 @@ const referencePagePath = (route: string): string => {
   return `${segments === "" ? "index" : segments}.astro`;
 };
 
-/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
-type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
-
-const sourcesOf = (
-  block: Block
-): { label?: string; route?: string; spec: string }[] => {
-  const sources = [...block.sources];
-  if (block.spec) {
-    sources.unshift({ spec: block.spec });
-  }
-  return sources;
-};
-
-const referencesFor = (
-  kind: ReferenceKind,
-  block: Block,
-  defaultLabel: string
-): ReferenceSource[] => {
-  if (!block.enabled) {
-    return [];
-  }
-  const sources = sourcesOf(block);
-  const base = normalizeRoute(block.route);
-
-  return sources.map((source, index) => {
-    const label =
-      source.label ??
-      (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
-
-    let route: string;
-    if (source.route) {
-      route = normalizeRoute(source.route);
-    } else if (sources.length === 1) {
-      route = base;
-    } else {
-      const suffix = source.label ? slugify(source.label) : "";
-      route = normalizeRoute(`${base}/${suffix || index + 1}`);
-    }
-
-    return { kind, label, route, spec: source.spec, theme: block.theme };
-  });
-};
-
-/**
- * Resolve every enabled reference source into its route and label. Pure (no file
- * IO), so the nav and the page generator stay in sync from one source of truth.
- */
-export const resolveReferences = (
-  config: ResolvedConfig
-): ReferenceSource[] => [
-  ...referencesFor("openapi", config.openapi, "API Reference"),
-  ...referencesFor("asyncapi", config.asyncapi, "Events"),
-];
-
-/** Nav tabs (header links) for the configured references. */
-export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
-  resolveReferences(config).map((ref) => ({
-    label: ref.label,
-    path: ref.route,
-  }));
-
-/** Whether any reference block is enabled (gates dependency + page wiring). */
-export const hasReferences = (config: ResolvedConfig): boolean =>
-  config.openapi.enabled || config.asyncapi.enabled;
-
 const darkModeConfig = (
   mode: ResolvedConfig["theme"]["mode"]
 ): Record<string, boolean> => {
@@ -180,9 +88,10 @@ const specConfiguration = async (
 };
 
 /**
- * Build the Scalar reference page(s) for the project. 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 any warnings.
+ * Build the Scalar reference page(s) for the project. Only Scalar-rendered
+ * references are emitted here (Blume-rendered OpenAPI is 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.
  */
 export const buildReferenceFiles = async (options: {
   config: ResolvedConfig;
@@ -196,6 +105,9 @@ export const buildReferenceFiles = async (options: {
   const seen = new Set<string>();
   const accepted: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
+    if (ref.renderer !== "scalar") {
+      continue;
+    }
     if (seen.has(ref.route)) {
       warnings.push(
         `Two API reference sources resolve to ${ref.route}; keeping the first.`