blume 1.5.2 → 1.6.0

package/src/openapi/references.ts

@@ -14,7 +14,7 @@ export { normalizeRoute } from "../core/base-path.ts";
  * imports so `core` can depend on it without a cycle.
  */
 
-export type ReferenceKind = "openapi" | "asyncapi";
+export type ReferenceKind = "openapi" | "asyncapi" | "graphql";
 
 /** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
 export type ReferenceRenderer = "blume" | "scalar";
@@ -56,6 +56,11 @@ export interface ReferenceSource {
   noindex: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
+  /**
+   * URL of the live GraphQL endpoint the playground and code samples target
+   * (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;
   /**
@@ -109,19 +114,32 @@ export const slugify = (text: string): string =>
 const routeSlug = (route: string): string =>
   slugify(trimChar(route, "/")) || "reference";
 
-type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
+/**
+ * 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.
+ */
+interface Block {
+  enabled: boolean;
+  endpoint?: string;
+  route: string;
+  scalar?: ResolvedConfig["openapi"]["scalar"];
+  sources: {
+    endpoint?: string;
+    includeInLlms: boolean;
+    includeInSearch: boolean;
+    label?: string;
+    noindex: boolean;
+    route?: string;
+    spec: string;
+  }[];
+  spec?: string;
+  theme?: string;
+}
 
 /** A spec is a single source (`spec` shorthand prepended to any `sources`). */
-const sourcesOf = (
-  block: Block
-): {
-  includeInLlms: boolean;
-  includeInSearch: boolean;
-  label?: string;
-  noindex: boolean;
-  route?: string;
-  spec: string;
-}[] => {
+const sourcesOf = (block: Block): Block["sources"] => {
   const sources = [...block.sources];
   if (block.spec) {
     sources.unshift({
@@ -163,7 +181,7 @@ const referencesFor = (
       route = normalizeRoute(`${base}/${suffix || index + 1}`);
     }
 
-    return {
+    const reference: ReferenceSource = {
       basePath,
       display,
       includeInLlms: source.includeInLlms,
@@ -178,6 +196,13 @@ const referencesFor = (
       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;
+    }
+    return reference;
   });
 };
 
@@ -212,6 +237,21 @@ export const resolveReferences = (
     },
     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
+  ),
 ];
 
 /**
@@ -287,3 +327,39 @@ export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
 /** 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");
+
+/**
+ * The reference kinds whose enabled, Blume-rendered 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}.
+ */
+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;
+};
+
+/**
+ * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
+ * generated: some enabled Blume-rendered block'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;

package/src/openapi/render-mdx.ts

@@ -4,6 +4,8 @@ import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
 
 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";
 
@@ -156,6 +158,19 @@ const clip = (text: string, max: number): string => {
 
 const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
 
+/** Human phrase for each GraphQL page kind, for meta descriptions. */
+const GRAPHQL_MEMBER_PHRASES = {
+  enum: "enum type",
+  input: "input object type",
+  interface: "interface type",
+  mutation: "mutation",
+  object: "object type",
+  query: "query",
+  scalar: "scalar type",
+  subscription: "subscription",
+  union: "union type",
+} satisfies Record<GraphqlMember, string>;
+
 /**
  * The spec's own prose for the operation, followed by the endpoint it documents
  * — so every operation page carries a distinct, self-describing meta
@@ -165,11 +180,18 @@ const operationDescription = (
   spec: ApiSpecData,
   operation: ApiOperationRef
 ): string => {
-  // AsyncAPI operations act on a channel, not an HTTP endpoint.
-  const suffix =
-    spec.kind === "asyncapi"
-      ? `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`
-      : `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+  // AsyncAPI operations act on a channel, not an HTTP endpoint; GraphQL pages
+  // document a root field or a named type.
+  let suffix: string;
+  if (spec.kind === "asyncapi") {
+    suffix = `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`;
+  } else if (spec.kind === "graphql") {
+    // SAFETY: the GraphQL extractor only ever assigns member kinds as the
+    // method (see `extractGraphqlOperations`).
+    suffix = `Reference for the ${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]} in the ${apiName(spec)} API.`;
+  } else {
+    suffix = `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+  }
   const prose = clip(
     plainProse(operation.description || operation.summary),
     META_DESCRIPTION_MAX - stringWidth(suffix) - 1
@@ -192,7 +214,13 @@ export const operationMdx = (
   >
 ): RenderedPage => {
   const method = operation.method.toUpperCase();
-  const title = operation.summary || `${method} ${operation.path}`;
+  const graphql = spec.kind === "graphql";
+  // A GraphQL page IS its field/type — `QUERY pets` would double the badge the
+  // page already renders; the other kinds title an endpoint or channel action.
+  const fallbackTitle = graphql
+    ? operation.path
+    : `${method} ${operation.path}`;
+  const title = operation.summary || fallbackTitle;
   // 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 =
@@ -219,6 +247,18 @@ export const operationMdx = (
   if (reference?.noindex) {
     seo.noindex = true;
   }
+  const sidebar: RenderedPageData["sidebar"] = {
+    label: operation.summary || operation.path,
+  };
+  // GraphQL operation kinds badge like HTTP methods, but a type page's kind
+  // already heads its sidebar group ("Objects", "Enums", …) — an `OBJECT`
+  // badge on every row would only repeat it, so type pages get none. The
+  // uppercased method is likewise an internal token on GraphQL pages, so
+  // their search tags carry only the group name.
+  if (!graphql || isGraphqlOperationKind(operation.method)) {
+    sidebar.badge = method;
+  }
+  const tags = graphql ? [operation.tag] : [operation.tag, method];
   return {
     body: withDescription(
       description,
@@ -226,9 +266,9 @@ export const operationMdx = (
     ),
     data: {
       ...flags,
-      search: { ...searchFlags, tags: [operation.tag, method] },
+      search: { ...searchFlags, tags },
       seo,
-      sidebar: { badge: method, label: operation.summary || operation.path },
+      sidebar,
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
       type: "openapi-operation",

package/src/openapi/scalar.ts

@@ -32,22 +32,16 @@ const referencePagePath = (route: string): string => {
   return `${segments === "" ? "index" : segments}.astro`;
 };
 
-const darkModeConfig = (mode: ResolvedConfig["theme"]["mode"]) => {
-  if (mode === "dark") {
-    return { darkMode: true };
-  }
-  if (mode === "light") {
-    return { darkMode: false };
-  }
-  // "system": leave Scalar to follow the OS preference.
-  return {};
-};
-
 /**
  * Map Blume's theme onto Scalar's. An explicit `theme` name wins; otherwise we
  * keep Scalar's default theme and layer Blume's accent/radius on top via
  * `customCss`. Scalar re-injects `customCss` after its bundled theme, so these
  * variables reliably override the defaults. Best-effort, not pixel-exact.
+ *
+ * Light/dark is not decided here: the page's `data-theme` (stored preference,
+ * else the configured mode, else the OS) is only known in the browser, so
+ * `ReferenceLayout` pins Scalar's color mode to it at mount and keeps the two
+ * in step afterwards (`SCALAR_THEME_INIT_SCRIPT`).
  */
 const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   if (override) {
@@ -57,7 +51,6 @@ const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   const radius = resolveRadius(config.theme);
   return {
     customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent.light};--scalar-radius:${radius};}.dark-mode{--scalar-color-accent:${accent.dark};}`,
-    ...darkModeConfig(config.theme.mode),
   };
 };
 

package/src/openapi/source.ts

@@ -11,6 +11,8 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractAsyncApiOperations } from "./asyncapi.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
+import { extractGraphqlOperations } from "./graphql.ts";
+import type { GraphqlDocument } from "./graphql.ts";
 import { extractOperations } from "./model.ts";
 import type {
   ApiDocument,
@@ -19,7 +21,12 @@ import type {
   ApiTagRef,
   OpenApiData,
 } from "./model.ts";
-import { InvalidSpecError, parseAsyncApiSpec, parseSpec } from "./parse.ts";
+import {
+  InvalidSpecError,
+  parseAsyncApiSpec,
+  parseGraphqlSpec,
+  parseSpec,
+} from "./parse.ts";
 import type { ReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
@@ -51,6 +58,62 @@ export const isOpenApiSource = (
 /** Route (`/reference/pet/add-pet`) to a staged content ref, without extension. */
 const routeToRef = (route: string): string => route.replace(/^\/+/u, "");
 
+/** Human label per spec kind, so one kind's failure never reads as another's. */
+const KIND_LABELS = {
+  asyncapi: "AsyncAPI",
+  graphql: "GraphQL",
+  openapi: "OpenAPI",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** Diagnostic-code prefix per spec kind. */
+const CODE_PREFIXES = {
+  asyncapi: "BLUME_ASYNCAPI",
+  graphql: "BLUME_GRAPHQL",
+  openapi: "BLUME_OPENAPI",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/**
+ * Parse-level warning code per kind: an offline cache fallback for any kind,
+ * plus lossy 2.x→3.0 conversion notes for AsyncAPI — hence the broader codes
+ * there and for GraphQL (OpenAPI keeps its historical one).
+ */
+const SPEC_WARNING_CODES = {
+  asyncapi: "BLUME_ASYNCAPI_SPEC_WARNING",
+  graphql: "BLUME_GRAPHQL_SPEC_WARNING",
+  openapi: "BLUME_OPENAPI_STALE",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/**
+ * Extract-level skip code per kind. OpenAPI keeps its historical code (the
+ * only extract warning it emits is the unresolved $ref path item); the
+ * GraphQL extractor currently skips nothing, so its code is reserved.
+ */
+const SKIPPED_CODES = {
+  asyncapi: "BLUME_ASYNCAPI_SKIPPED_OPERATION",
+  graphql: "BLUME_GRAPHQL_SKIPPED",
+  openapi: "BLUME_OPENAPI_REF_PATH_ITEM",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** `_EMPTY` diagnostic suggestion per kind. */
+const EMPTY_SUGGESTIONS = {
+  asyncapi:
+    "Check the spec points at an AsyncAPI document with `channels` and `operations`.",
+  graphql:
+    "Check the spec points at a GraphQL schema (SDL or introspection JSON) whose root types declare fields.",
+  openapi:
+    "Check the spec points at an OpenAPI document with operations under `paths`.",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** `_UNAVAILABLE` suggestion for a readable-but-invalid spec, per kind. */
+const INVALID_SUGGESTIONS = {
+  asyncapi:
+    "Point the spec at an AsyncAPI document (a YAML or JSON file with an object at the top level).",
+  graphql:
+    "Point the spec at a GraphQL schema — SDL text or an introspection JSON result.",
+  openapi:
+    "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level).",
+} satisfies Record<ReferenceSource["kind"], string>;
+
 const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
   const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
   return {
@@ -122,7 +185,7 @@ interface LoadedSpec {
 
 /** One parsed spec, whichever front-end read it — the kind dispatch seam. */
 interface ParsedReference {
-  document: ApiDocument | AsyncApiDocument;
+  document: ApiDocument | AsyncApiDocument | GraphqlDocument;
   warnings: string[];
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
@@ -149,6 +212,21 @@ const parseReference = async (
       warnings,
     };
   }
+  if (reference.kind === "graphql") {
+    const { document, warnings } = await parseGraphqlSpec(
+      reference.spec,
+      ctx.projectRoot,
+      options
+    );
+    const extracted = extractGraphqlOperations(document, reference.route);
+    return {
+      document,
+      extractWarnings: extracted.warnings,
+      operations: extracted.operations,
+      tags: extracted.tags,
+      warnings,
+    };
+  }
   const { document, warnings } = await parseSpec(
     reference.spec,
     ctx.projectRoot,
@@ -175,9 +253,8 @@ export const openApiSource = (
   ): Promise<LoadedSpec | Diagnostic> => {
     // Human label and diagnostic-code prefix for the spec's kind, so an
     // AsyncAPI failure never reads as an OpenAPI one.
-    const kindLabel = reference.kind === "asyncapi" ? "AsyncAPI" : "OpenAPI";
-    const codePrefix =
-      reference.kind === "asyncapi" ? "BLUME_ASYNCAPI" : "BLUME_OPENAPI";
+    const kindLabel = KIND_LABELS[reference.kind];
+    const codePrefix = CODE_PREFIXES[reference.kind];
     try {
       const { document, warnings, operations, tags, extractWarnings } =
         await parseReference(reference, ctx);
@@ -221,26 +298,20 @@ export const openApiSource = (
         title: info.title ?? reference.label,
         version: info.version ?? "",
       };
+      // Only GraphQL references carry a live endpoint (a schema names no
+      // server); assigned separately so the key stays absent otherwise.
+      if (reference.endpoint !== undefined) {
+        spec.endpoint = reference.endpoint;
+      }
       return {
         diagnostics: [
           ...warnings.map((message) => ({
-            // Parse-level notes: an offline cache fallback for either kind,
-            // plus lossy 2.x→3.0 conversion notes for AsyncAPI — hence the
-            // broader code on that side (OpenAPI keeps its historical one).
-            code:
-              reference.kind === "asyncapi"
-                ? "BLUME_ASYNCAPI_SPEC_WARNING"
-                : "BLUME_OPENAPI_STALE",
+            code: SPEC_WARNING_CODES[reference.kind],
             message,
             severity: "warning" as const,
           })),
           ...extractWarnings.map((message) => ({
-            // OpenAPI keeps its historical code (the only extract warning it
-            // emits is the unresolved $ref path item).
-            code:
-              reference.kind === "asyncapi"
-                ? "BLUME_ASYNCAPI_SKIPPED_OPERATION"
-                : "BLUME_OPENAPI_REF_PATH_ITEM",
+            code: SKIPPED_CODES[reference.kind],
             message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning" as const,
           })),
@@ -253,10 +324,7 @@ export const openApiSource = (
                   code: `${codePrefix}_EMPTY`,
                   message: `${kindLabel} spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
                   severity: "warning" as const,
-                  suggestion:
-                    reference.kind === "asyncapi"
-                      ? "Check the spec points at an AsyncAPI document with `channels` and `operations`."
-                      : "Check the spec points at an OpenAPI document with operations under `paths`.",
+                  suggestion: EMPTY_SUGGESTIONS[reference.kind],
                 },
               ]
             : []),
@@ -280,7 +348,7 @@ export const openApiSource = (
         // only point at reachability for actual fetch/read failures.
         suggestion:
           error instanceof InvalidSpecError
-            ? `Point the spec at ${reference.kind === "asyncapi" ? "an AsyncAPI" : "an OpenAPI"} document (a YAML or JSON file with an object at the top level).`
+            ? INVALID_SUGGESTIONS[reference.kind]
             : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
       };
     }

package/src/registry/eject.ts

@@ -44,6 +44,7 @@ import {
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { buildIncludeGraph } from "../core/includes.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -383,6 +384,7 @@ export const eject = async (
       content: astroConfigTemplate({
         askPath: "./src/generated/Ask.astro",
         config,
+        contentRoot: relContext.contentRoot,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
         dataPath: "./src/generated/data.json",
@@ -485,6 +487,15 @@ export const eject = async (
       content: `${JSON.stringify(rawMarkdown)}\n`,
       path: join(genDir, "raw-markdown.json"),
     },
+    {
+      // The partial → including-pages map behind `includeHmrPlugin`, which the
+      // ejected astro.config wires at this exact path — without the file every
+      // hot update's read would silently no-op and partial edits would serve
+      // stale pages. A snapshot like the rest of `src/generated`: the ejected
+      // app owns (and may regenerate or prune) it.
+      content: `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`,
+      path: join(genDir, "includes.json"),
+    },
     {
       content: rawMarkdownEndpointTemplate("md"),
       path: join(srcDir, "pages", "[...slug].md.ts"),