blume 0.6.7 → 0.8.0

package/src/openapi/references.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { NavTab } from "../core/types.ts";
 
@@ -30,6 +31,12 @@ export interface ReferenceSource {
   slug: string;
   /** Normalized route the reference mounts at, e.g. `/reference`. */
   route: string;
+  /**
+   * Site-wide `basePath` the rendered pages are mounted under (`""` when
+   * none). Kept separate from `route` — the content pipeline applies it to
+   * staged entries itself — so consumers prefix only the URLs they emit.
+   */
+  basePath: string;
   label: string;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
@@ -37,6 +44,11 @@ export interface ReferenceSource {
   theme?: string;
   /** Display options carried through to the Blume renderer. */
   display: ReferenceDisplay;
+  /**
+   * Warnings recorded while deduping — another source's route collided with
+   * this one and was dropped. Surfaced as diagnostics when the source loads.
+   */
+  collisions?: string[];
 }
 
 const NON_SLUG = /[^a-z0-9]+/gu;
@@ -77,7 +89,8 @@ const referencesFor = (
   block: Block,
   defaultLabel: string,
   renderer: ReferenceRenderer,
-  display: ReferenceDisplay
+  display: ReferenceDisplay,
+  basePath: string
 ): ReferenceSource[] => {
   if (!block.enabled) {
     return [];
@@ -101,6 +114,7 @@ const referencesFor = (
     }
 
     return {
+      basePath,
       display,
       kind,
       label,
@@ -130,41 +144,81 @@ export const resolveReferences = (
     {
       codeSamples: config.openapi.codeSamples,
       expandSchemas: config.openapi.expandSchemas,
-    }
+    },
+    config.basePath
+  ),
+  ...referencesFor(
+    "asyncapi",
+    config.asyncapi,
+    "Events",
+    "scalar",
+    NO_DISPLAY,
+    config.basePath
   ),
-  ...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 operation pages flow through the content pipeline and are
+    // mounted under `basePath`, so their tab must be too. Scalar references are
+    // a single embedded page injected at the raw `route`, left root-anchored.
+    path:
+      ref.renderer === "blume"
+        ? withBasePath(config.basePath, ref.route)
+        : ref.route,
   }));
 
+/**
+ * Accept one resolved reference into the deduped Blume-rendered set, or return
+ * null to skip it. Mutates `seen`/`usedSlugs` so repeated routes/slugs collapse.
+ * A dropped route collision is recorded on the kept reference (mirroring the
+ * Scalar path's warning) — losing a whole spec's pages must not be silent.
+ */
+const blumeReferenceOf = (
+  ref: ReferenceSource,
+  seen: Map<string, ReferenceSource>,
+  usedSlugs: Set<string>
+): ReferenceSource | null => {
+  if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+    return null;
+  }
+  const kept = seen.get(ref.route);
+  if (kept) {
+    (kept.collisions ??= []).push(
+      `Two API reference sources resolve to ${ref.route}; keeping the first.`
+    );
+    return null;
+  }
+  // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
+  // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
+  // collision would let one spec silently overwrite the other while the
+  // loser's pages still point at the shared key — disambiguate.
+  let { slug } = ref;
+  let n = 2;
+  while (usedSlugs.has(slug)) {
+    slug = `${ref.slug}-${n}`;
+    n += 1;
+  }
+  usedSlugs.add(slug);
+  const accepted = slug === ref.slug ? ref : { ...ref, slug };
+  // Keep the accepted object (not the original) so a later collision's warning
+  // lands on the reference the caller actually receives.
+  seen.set(ref.route, accepted);
+  return accepted;
+};
+
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
-  const seen = new Set<string>();
+  const seen = new Map<string, ReferenceSource>();
   const usedSlugs = 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);
-    // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
-    // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
-    // collision would let one spec silently overwrite the other while the
-    // loser's pages still point at the shared key — disambiguate.
-    let { slug } = ref;
-    for (let n = 2; usedSlugs.has(slug); n += 1) {
-      slug = `${ref.slug}-${n}`;
+    const accepted = blumeReferenceOf(ref, seen, usedSlugs);
+    if (accepted) {
+      result.push(accepted);
     }
-    usedSlugs.add(slug);
-    result.push(slug === ref.slug ? ref : { ...ref, slug });
   }
   return result;
 };

package/src/openapi/render-mdx.ts

@@ -119,17 +119,22 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
       });
     }
   }
-  const tagSections = sections
-    .filter((tag) =>
-      operations.some((operation) => operation.tagSlug === tag.slug)
-    )
-    .map((tag) =>
+  const tagSections: string[] = [];
+  for (const tag of sections) {
+    if (!operations.some((operation) => operation.tagSlug === tag.slug)) {
+      continue;
+    }
+    const description = tag.description.trim()
+      ? [mdxSafe(tag.description.trim())]
+      : [];
+    tagSections.push(
       [
         `## ${mdxSafe(tag.name)}`,
-        ...(tag.description.trim() ? [mdxSafe(tag.description.trim())] : []),
+        ...description,
         `<ApiTagOperations source="${spec.slug}" tag="${tag.slug}" />`,
       ].join("\n\n")
     );
+  }
   return {
     body: [
       withDescription(

package/src/openapi/scalar.ts

@@ -87,6 +87,35 @@ const specConfiguration = async (
   }
 };
 
+/**
+ * Accept one resolved reference into the deduped Scalar set, or return null to
+ * skip it (recording a warning for a route collision). Mutates `seen`.
+ */
+const acceptScalarReference = (
+  ref: ReferenceSource,
+  seen: Set<string>,
+  contentRoutes: ReadonlySet<string>,
+  warnings: string[]
+): ReferenceSource | null => {
+  if (ref.renderer !== "scalar") {
+    return null;
+  }
+  if (seen.has(ref.route)) {
+    warnings.push(
+      `Two API reference sources resolve to ${ref.route}; keeping the first.`
+    );
+    return null;
+  }
+  if (contentRoutes.has(ref.route)) {
+    warnings.push(
+      `API reference route ${ref.route} collides with a content page; skipping the reference there.`
+    );
+    return null;
+  }
+  seen.add(ref.route);
+  return ref;
+};
+
 /**
  * Build the Scalar reference page(s) for the project. Only Scalar-rendered
  * references are emitted here (Blume-rendered OpenAPI is staged content). Reads
@@ -105,23 +134,10 @@ 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.`
-      );
-      continue;
-    }
-    if (contentRoutes.has(ref.route)) {
-      warnings.push(
-        `API reference route ${ref.route} collides with a content page; skipping the reference there.`
-      );
-      continue;
+    const next = acceptScalarReference(ref, seen, contentRoutes, warnings);
+    if (next) {
+      accepted.push(next);
     }
-    seen.add(ref.route);
-    accepted.push(ref);
   }
 
   const built = await Promise.all(

package/src/openapi/source.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "../core/base-path.ts";
 import matter from "../core/frontmatter.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type {
@@ -9,7 +10,7 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractOperations } from "./model.ts";
 import type { ApiOperationRef, ApiSpecData, OpenApiData } from "./model.ts";
-import { parseSpec } from "./parse.ts";
+import { InvalidSpecError, parseSpec } from "./parse.ts";
 import type { ReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
@@ -90,7 +91,11 @@ export const openApiSource = (
         ctx.projectRoot,
         { cacheDir: ctx.cacheDir, refresh: ctx.refresh }
       );
-      const { operations, tags } = extractOperations(document, reference.route);
+      const {
+        operations,
+        tags,
+        warnings: extractWarnings,
+      } = extractOperations(document, reference.route);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec: ApiSpecData = {
         codeSamples: reference.display.codeSamples,
@@ -98,8 +103,18 @@ export const openApiSource = (
         document,
         expandSchemas: reference.display.expandSchemas,
         label: reference.label,
+        // Operation pages flow through the content pipeline, which mounts them
+        // under the site-wide `basePath` (staged entry refs below stay
+        // base-less); serialize the served route so components link to the
+        // pages' real URLs.
         operations: Object.fromEntries(
-          operations.map((operation) => [operation.key, operation])
+          operations.map((operation) => [
+            operation.key,
+            {
+              ...operation,
+              route: withBasePath(reference.basePath, operation.route),
+            },
+          ])
         ),
         route: reference.route,
         slug: reference.slug,
@@ -108,11 +123,32 @@ export const openApiSource = (
         version: info.version ?? "",
       };
       return {
-        diagnostics: warnings.map((message) => ({
-          code: "BLUME_OPENAPI_STALE",
-          message,
-          severity: "warning" as const,
-        })),
+        diagnostics: [
+          ...warnings.map((message) => ({
+            code: "BLUME_OPENAPI_STALE",
+            message,
+            severity: "warning" as const,
+          })),
+          ...extractWarnings.map((message) => ({
+            code: "BLUME_OPENAPI_REF_PATH_ITEM",
+            message: `In OpenAPI spec "${reference.spec}": ${message}`,
+            severity: "warning" as const,
+          })),
+          // A document with no operations (say, a config file that happens to
+          // parse as YAML) would otherwise build a nav tab onto an empty
+          // reference with no hint why.
+          ...(operations.length === 0
+            ? [
+                {
+                  code: "BLUME_OPENAPI_EMPTY",
+                  message: `OpenAPI spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
+                  severity: "warning" as const,
+                  suggestion:
+                    "Check the spec points at an OpenAPI document with operations under `paths`.",
+                },
+              ]
+            : []),
+        ],
         entries: specEntries(spec, operations),
         slug: reference.slug,
         spec,
@@ -125,8 +161,12 @@ export const openApiSource = (
         // so fail loudly in build (blocks under --strict) while staying a warning
         // in dev so offline work still runs.
         severity: ctx.mode === "build" ? "error" : "warning",
+        // A readable-but-invalid file is a content problem, not a network one;
+        // only point at reachability for actual fetch/read failures.
         suggestion:
-          "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
+          error instanceof InvalidSpecError
+            ? "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level)."
+            : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
       };
     }
   };
@@ -134,7 +174,16 @@ export const openApiSource = (
   const load = async (): Promise<SourceLoadResult> => {
     const results = await Promise.all(references.map(loadReference));
     const entries: SourceEntry[] = [];
-    const diagnostics: Diagnostic[] = [];
+    // Route collisions recorded while deduping (see `blumeReferences`): a
+    // dropped source loses a whole spec's pages, so warn even when the kept
+    // spec loads cleanly.
+    const diagnostics: Diagnostic[] = references.flatMap((reference) =>
+      (reference.collisions ?? []).map((message) => ({
+        code: "BLUME_OPENAPI_ROUTE_COLLISION",
+        message,
+        severity: "warning" as const,
+      }))
+    );
     const data: OpenApiData = {};
     for (const result of results) {
       if ("severity" in result) {