blume 0.4.0 → 0.5.1

package/src/migrate/mintlify/index.ts

@@ -6,7 +6,7 @@ import { glob } from "tinyglobby";
 
 import type { BlumeConfig } from "../../core/schema.ts";
 import { assetSegments } from "./assets.ts";
-import { loadMintlifyConfig } from "./config.ts";
+import { loadMintlifyConfig, partitionMintlifyRedirects } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
 import { transformMintlifyContent } from "./transform.ts";
 
@@ -15,6 +15,72 @@ export interface MintlifyMigrationResult {
   warnings: string[];
 }
 
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+const hasFontFamily = (value: unknown): boolean => {
+  const object = asRecord(value);
+  if (!object) {
+    return false;
+  }
+  const named = (child: unknown): boolean =>
+    typeof asRecord(child)?.family === "string";
+  return (
+    typeof object.family === "string" ||
+    named(object.heading) ||
+    named(object.body)
+  );
+};
+
+/**
+ * Warn about Mintlify site chrome that Blume's config doesn't model, so it isn't
+ * dropped silently: header links (`navbar.links`/`navbar.primary`), footer
+ * socials (`footer.socials`), and fonts outside Blume's curated Google set. The
+ * contextual page menu and last-updated timestamp are covered by Blume defaults
+ * (page actions, git-derived dates), so they need no warning.
+ */
+const droppedChromeWarnings = (
+  spec: Record<string, unknown>,
+  config: BlumeConfig
+): string[] => {
+  const warnings: string[] = [];
+  const navbar = asRecord(spec.navbar);
+  if (navbar && (navbar.links || navbar.primary)) {
+    warnings.push(
+      "Header links (navbar.links/navbar.primary) have no blume.config equivalent and were dropped; re-add them with navigation.tabs or a Header layout override."
+    );
+  }
+  if (asRecord(spec.footer)?.socials) {
+    warnings.push(
+      "Footer social links (footer.socials) have no blume.config equivalent and were dropped; add them with a Footer layout override."
+    );
+  }
+  if (hasFontFamily(spec.fonts ?? spec.font) && !config.theme?.fonts) {
+    warnings.push(
+      "docs.json font family isn't in Blume's curated Google Fonts set; set theme.fonts to a supported slug or add @font-face rules in theme.css."
+    );
+  }
+  return warnings;
+};
+
+/**
+ * Warn about dynamic (wildcard/param) redirects the migrator dropped. Blume
+ * redirects are static path-to-path, so a `:slug*`/`:id` source becomes an
+ * unroutable Astro destination — kept ones crash the build. Point the user at
+ * host-level rules that do support wildcards.
+ */
+const droppedRedirectWarnings = (spec: Record<string, unknown>): string[] => {
+  const { dropped } = partitionMintlifyRedirects(spec);
+  if (dropped.length === 0) {
+    return [];
+  }
+  return [
+    `Dropped ${dropped.length} dynamic redirect(s) Blume can't model as static path-to-path (${dropped.join(", ")}); re-add them as host-level rules (e.g. _redirects or vercel.json).`,
+  ];
+};
+
 /** Recursively drop `undefined`, empty arrays, and empty objects. */
 const prune = (value: unknown): unknown => {
   if (Array.isArray(value)) {
@@ -190,6 +256,14 @@ export const migrateMintlifyProject = async (
         `Mapped ${i18n.locales.length} languages to i18n.locales (default: ${i18n.defaultLocale}); review the locale labels.`
       );
     }
+    const openapiSources = config.openapi?.sources ?? [];
+    if (openapiSources.length > 0) {
+      warnings.push(
+        `Mapped ${openapiSources.length} OpenAPI spec source(s) to openapi.sources (native reference renderer); verify each spec path or URL resolves.`
+      );
+    }
+    warnings.push(...droppedChromeWarnings(spec, config));
+    warnings.push(...droppedRedirectWarnings(spec));
   } else {
     warnings.push("No docs.json or mint.json found; writing a default config.");
     config = { content: { root: "." }, title: "Documentation" };
@@ -263,7 +337,7 @@ export const migrateMintlifyProject = async (
   }
   if (unsupported.size > 0) {
     warnings.push(
-      `Components without a Blume equivalent need manual review (use the OpenAPI reference instead): ${[...unsupported].join(", ")}.`
+      `Components without a Blume equivalent need manual review: ${[...unsupported].join(", ")}.`
     );
   }
   warnings.push(

package/src/migrate/mintlify/transform.ts

@@ -1,6 +1,7 @@
 import matter from "../../core/frontmatter.ts";
 import { stripUnknownPageMeta } from "../shared.ts";
 import {
+  rewriteMintlifyAccordions,
   rewriteMintlifyCallouts,
   rewriteMintlifyExampleBlocks,
   rewriteSnippetImports,
@@ -59,6 +60,7 @@ export const transformMintlifyContent = async (
   text = snippetImports.source;
   text = rewriteMintlifySvgIconProps(text);
   text = rewriteMintlifyExampleBlocks(text);
+  text = rewriteMintlifyAccordions(text);
   text = rewriteMintlifyCallouts(text);
 
   const unsupported = unsupportedMintlifyComponents(text);

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