blume 0.6.7 → 0.8.0

package/src/deploy/redirects.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 
 /**
@@ -10,20 +11,42 @@ import type { ResolvedConfig } from "../core/schema.ts";
 
 type Redirect = ResolvedConfig["redirects"][number];
 
+/**
+ * Prepend the site-wide `basePath` to each redirect's internal `from`/`to`
+ * (both are authored as if mounted at root); external `to` URLs pass through.
+ * Idempotent, so re-basing an already-based redirect is safe.
+ */
+export const applyBaseToRedirects = (
+  redirects: Redirect[],
+  basePath: string
+): Redirect[] =>
+  basePath
+    ? redirects.map((redirect) => ({
+        ...redirect,
+        from: withBasePath(basePath, redirect.from),
+        to: withBasePath(basePath, redirect.to),
+      }))
+    : redirects;
+
 /** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
 export const buildNetlifyRedirects = (redirects: Redirect[]): string =>
   `${redirects
     .map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`)
     .join("\n")}\n`;
 
-/** `vercel.json` contents with a `redirects` array (permanent = 301/308). */
+/**
+ * `vercel.json` contents with a `redirects` array. Uses `statusCode` (Vercel's
+ * alternative to the boolean `permanent`) so the configured code ships exactly:
+ * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
+ * from the `_redirects` file, which preserves exact codes.
+ */
 export const buildVercelConfig = (redirects: Redirect[]): string =>
   `${JSON.stringify(
     {
       redirects: redirects.map((redirect) => ({
         destination: redirect.to,
-        permanent: redirect.status === 301 || redirect.status === 308,
         source: redirect.from,
+        statusCode: redirect.status,
       })),
     },
     null,

package/src/deploy/robots.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 
@@ -47,7 +48,11 @@ export const buildRobots = (project: BlumeProject): string | null => {
 
   const { site } = config.deployment;
   if (site && config.seo.sitemap) {
-    lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}/sitemap.xml`);
+    const sitemapPath = withBasePath(
+      normalizeBasePath(config.deployment.base),
+      "/sitemap.xml"
+    );
+    lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}${sitemapPath}`);
   }
   return `${lines.join("\n")}\n`;
 };

package/src/deploy/rss.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { PageRecord } from "../core/types.ts";
 import { escapeXml } from "./xml.ts";
@@ -52,6 +53,11 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     return [];
   }
   const base = site.replace(/\/$/u, "");
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  // The feed's own `link`/self URL points at the docs root under that base, while
+  // `path` stays base-less (it's also the on-disk output location).
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const rootLink = `${base}${deployBase}`;
 
   const feeds: RssFeed[] = [];
   for (const type of rss.types) {
@@ -70,7 +76,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
         description: page.description,
         // Encode like the sitemap does: a route with spaces or non-ASCII
         // must still yield a valid <link>/<guid> URL after XML decoding.
-        link: encodeURI(`${base}${page.route}`),
+        link: encodeURI(`${base}${withBasePath(deployBase, page.route)}`),
         title: page.title,
       }))
       .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))
@@ -79,7 +85,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     feeds.push({
       description: config.description,
       items,
-      link: base,
+      link: rootLink,
       path: `/${type}/rss.xml`,
       title: `${config.title} — ${capitalize(type)}`,
       type,
@@ -105,11 +111,12 @@ const renderItem = (item: RssItem): string => {
 
 /** Serialize a resolved feed into an RSS 2.0 XML document. */
 export const renderRssFeed = (feed: RssFeed): string => {
+  const feedSelfHref = `${feed.link}${feed.path}`;
   const channel = [
     `  <title>${escapeXml(feed.title)}</title>`,
     `  <link>${escapeXml(feed.link)}</link>`,
     `  <description>${escapeXml(feed.description ?? feed.title)}</description>`,
-    `  <atom:link href="${escapeXml(`${feed.link}${feed.path}`)}" rel="self" type="application/rss+xml" />`,
+    `  <atom:link href="${escapeXml(feedSelfHref)}" rel="self" type="application/rss+xml" />`,
   ];
   const items = feed.items.map(renderItem).join("\n");
   return `<?xml version="1.0" encoding="UTF-8"?>

package/src/deploy/sitemap.ts

@@ -1,6 +1,21 @@
+import {
+  customStaticRoutes,
+  discoverPagesSync,
+  hasGeneratedChangelog,
+} from "../astro/pages.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { escapeXml } from "./xml.ts";
 
+/**
+ * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
+ * `pages/500.astro`, or a `404.md` content page — see `writeNotFoundPage` in
+ * `astro/generate.ts`) is neither dynamic nor private, so it would otherwise
+ * be emitted — but error pages aren't crawlable destinations and must stay out
+ * of the sitemap.
+ */
+const ERROR_ROUTES = new Set(["/404", "/500"]);
+
 /** A `<lastmod>` element (W3C date) when the page has a valid modified date. */
 const lastmodTag = (value: string | undefined): string => {
   if (!value) {
@@ -13,9 +28,11 @@ const lastmodTag = (value: string | undefined): string => {
 };
 
 /**
- * Build a sitemap.xml from the route manifest. Returns null when the sitemap is
- * disabled or no `site` is configured (absolute URLs are required for a valid
- * sitemap). Drafts, hidden, and `noindex` pages are excluded.
+ * Build a sitemap.xml from the route manifest plus the routes the manifest
+ * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
+ * the generated `/changelog` index. Returns null when the sitemap is disabled
+ * or no `site` is configured (absolute URLs are required for a valid sitemap).
+ * Drafts, hidden, and `noindex` pages are excluded.
  */
 export const buildSitemap = (project: BlumeProject): string | null => {
   const { site } = project.config.deployment;
@@ -24,20 +41,49 @@ export const buildSitemap = (project: BlumeProject): string | null => {
   }
 
   const base = site.replace(/\/$/u, "");
-  const urls = project.graph.pages
-    .filter(
-      (page) =>
-        !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)
-    )
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  const deployBase = normalizeBasePath(project.config.deployment.base);
+  const seen = new Set<string>();
+  const urls: string[] = [];
+  const pushUrl = (route: string, lastModified?: string): void => {
     // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
     // then escape XML metacharacters (notably `&`) so a route like
     // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
     // rejected.
-    .map(
-      (page) =>
-        `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`
-    )
-    .toSorted();
+    const loc = escapeXml(encodeURI(`${base}${route}`));
+    if (seen.has(loc)) {
+      return;
+    }
+    seen.add(loc);
+    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
+  };
+  for (const page of project.graph.pages) {
+    if (
+      page.meta.draft ||
+      page.meta.sidebar.hidden ||
+      page.meta.seo.noindex ||
+      ERROR_ROUTES.has(page.route)
+    ) {
+      continue;
+    }
+    pushUrl(withBasePath(deployBase, page.route), page.lastModified);
+  }
+  // Custom `.astro` pages and the generated changelog index mount outside
+  // `basePath` (they're injected at their pattern — see `blumeIntegration`), so
+  // only the deployment base layers onto their URLs.
+  const userPages = project.context.pagesRoot
+    ? discoverPagesSync(project.context.pagesRoot)
+    : [];
+  const extraRoutes = customStaticRoutes(userPages).filter(
+    (route) => !ERROR_ROUTES.has(route)
+  );
+  if (hasGeneratedChangelog(project, userPages)) {
+    extraRoutes.push("/changelog");
+  }
+  for (const route of extraRoutes) {
+    pushUrl(withBasePath(deployBase, route));
+  }
+  urls.sort();
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

package/src/index.ts

@@ -1,3 +1,8 @@
+export type {
+  ComponentMarkdown,
+  ComponentMarkdownChild,
+  ComponentMarkdownContext,
+} from "./ai/component-markdown.ts";
 export { defineConfig } from "./core/config.ts";
 export type {
   BlumeBanner,

package/src/markdown/base-links.ts

@@ -0,0 +1,60 @@
+import { isInternalPath, withComposedBasePath } from "../core/base-path.ts";
+import type { MdastNode } from "./mdast.ts";
+
+interface UrlNode extends MdastNode {
+  url?: string | null;
+}
+
+/**
+ * The slice of Satteri's MDAST visitor context this plugin needs. Nodes are
+ * read-only (the tree compiles to an op-stream), so a URL edit is recorded via
+ * `setProperty`, not by mutating the node object.
+ */
+interface MdastUrlContext {
+  setProperty: (node: unknown, key: "url", value: string) => void;
+}
+
+/**
+ * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
+ * — treated as a public asset, which Blume serves from `public/` at the site
+ * root and does *not* move under `basePath`. Bare page links (`/guide`) have no
+ * extension. The rare dotted route (`/releases/v1.0`) is left un-based here; the
+ * build-time link checker still resolves it against the route set.
+ */
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
+const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
+
+/**
+ * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
+ * layered over the site-wide `basePath` — to root-relative internal page links
+ * (`[x](/guide)` -> `/base/docs/guide`), so authors write links as if mounted
+ * at root. Idempotent per layer (via `withComposedBasePath`, so a hand-written
+ * `/docs/x` isn't double-prefixed) and inert for external URLs, fragments,
+ * relative paths, images, and asset links. Only constructed when a base is set
+ * (see `markdown/index.ts`).
+ */
+export const baseLinksPlugin = (deployBase: string, basePath: string) => {
+  const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
+    const { url } = node;
+    if (
+      typeof url === "string" &&
+      isInternalPath(url) &&
+      !ASSET_PATH.test(pathOf(url))
+    ) {
+      const next = withComposedBasePath(deployBase, basePath, url);
+      if (next !== url) {
+        ctx.setProperty(node, "url", next);
+      }
+    }
+  };
+  // `link` covers inline links; `definition` covers reference-style link
+  // definitions (`[x]: /guide`). `image` is intentionally excluded — images are
+  // public assets served at the site root, unaffected by `basePath`.
+  return {
+    definition: rebase,
+    link: rebase,
+    name: "blume-base-links",
+  };
+};

package/src/markdown/code-title.ts

@@ -37,6 +37,16 @@ const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
 const withoutQuotedAttrs = (raw: string): string =>
   raw.replace(QUOTED_ATTR, " ");
 
+// The first bare token is the title (```ts blume.config.ts): a non-empty token
+// that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
+// `lineNumbers`/`twoslash` keyword.
+const isTitleToken = (token: string): boolean => {
+  if (token.length === 0 || token.startsWith("{") || token.includes("=")) {
+    return false;
+  }
+  return token !== "lineNumbers" && token !== "twoslash";
+};
+
 const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
@@ -46,20 +56,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (attrTitle) {
     return attrTitle;
   }
-  // The first bare token is the title (```ts blume.config.ts), skipping Shiki
-  // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`
-  // and `twoslash` keywords.
-  return withoutQuotedAttrs(raw)
-    .trim()
-    .split(/\s+/u)
-    .find(
-      (token) =>
-        token.length > 0 &&
-        token !== "lineNumbers" &&
-        token !== "twoslash" &&
-        !token.startsWith("{") &&
-        !token.includes("=")
-    );
+  return withoutQuotedAttrs(raw).trim().split(/\s+/u).find(isTitleToken);
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>

package/src/markdown/index.ts

@@ -8,6 +8,7 @@ import {
 } from "@shikijs/transformers";
 import { codeToHtml } from "shiki";
 
+import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
@@ -16,6 +17,8 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { DEFAULT_CODE_THEMES } from "./themes.ts";
+import type { CodeThemes } from "./themes.ts";
 
 /** A Shiki transformer, derived from the upstream factories' return type. */
 type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
@@ -54,7 +57,7 @@ type HastPlugin = NonNullable<
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
   const plugins: HastPlugin[] = [
-    inlineCodeHighlightPlugin() as unknown as HastPlugin,
+    inlineCodeHighlightPlugin(options.codeThemes) as unknown as HastPlugin,
   ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
@@ -99,13 +102,6 @@ export const blumeShikiTransformers = (
   return transformers;
 };
 
-/**
- * The light/dark Shiki themes Blume highlights with. Kept in lockstep with the
- * generated Astro config's `shikiConfig.themes` so code highlighted outside the
- * Markdown pipeline (via {@link highlightCode}) matches fenced code exactly.
- */
-const CODE_THEMES = { dark: "github-dark", light: "github-light" } as const;
-
 const escapeHtml = (value: string): string =>
   value
     .replaceAll("&", "&amp;")
@@ -147,6 +143,11 @@ const languageAttrTransformer = (lang: string): ShikiTransformer =>
 export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
   className?: string;
+  /**
+   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * github pair fenced code uses, so out-of-pipeline code stays in lockstep.
+   */
+  themes?: CodeThemes;
   /** Header title (a filename), matching a fence's `title="..."` meta. */
   title?: string;
 }
@@ -176,7 +177,7 @@ export const highlightCode = async (
       meta: options.title
         ? { __raw: `title="${options.title.replaceAll('"', "")}"` }
         : undefined,
-      themes: CODE_THEMES,
+      themes: options.themes ?? DEFAULT_CODE_THEMES,
       transformers: [
         ...blumeShikiTransformers({ icons: options.icons }),
         astroCodeClassTransformer(options.className),
@@ -200,18 +201,53 @@ const FEATURES = { subscript: true, superscript: true };
 
 /** Options shared by both processors. */
 export interface BlumeMarkdownOptions {
+  /**
+   * Light/dark Shiki themes for inline `` `code`{:lang} `` highlighting
+   * (`markdown.codeBlocks.theme`). Defaults to the github pair fenced code uses.
+   */
+  codeThemes?: CodeThemes;
   /**
    * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
    * On unless explicitly `false`.
    */
   headingAnchors?: boolean;
+  /**
+   * Site-wide route mount point (`""` or `/seg`). When set, root-relative
+   * internal page links in content are rewritten under it, so authors write
+   * links as if mounted at root.
+   */
+  basePath?: string;
+  /**
+   * Astro's `deployment.base` subdirectory (`""` or `/seg`), layered on top of
+   * `basePath` when links are rewritten. Kept separate so a hand-written
+   * `basePath` link isn't double-prefixed (see `withComposedBasePath`).
+   */
+  deployBase?: string;
 }
 
+/**
+ * MDAST plugins that apply to both `.md` and `.mdx`. Currently just the
+ * base-path link rewrite, added only when a `basePath` or `deployBase` is
+ * configured.
+ */
+const blumeSharedMdastPlugins = (
+  options: BlumeMarkdownOptions
+): MdastPlugin[] =>
+  options.basePath || options.deployBase
+    ? [
+        baseLinksPlugin(
+          options.deployBase ?? "",
+          options.basePath ?? ""
+        ) as unknown as MdastPlugin,
+      ]
+    : [];
+
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
   satteri({
     features: { ...FEATURES },
     hastPlugins: blumeHastPlugins(options),
+    mdastPlugins: blumeSharedMdastPlugins(options),
   });
 
 export type BlumeMdxOptions = BlumeMarkdownOptions;
@@ -246,5 +282,6 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
       directiveToCalloutPlugin(),
       mermaidPlugin(),
       mathPlugin(),
+      ...blumeSharedMdastPlugins(options),
     ] as unknown as MdastPlugin[],
   });

package/src/markdown/inline-code.ts

@@ -12,6 +12,9 @@
  * added to the pipeline at all).
  */
 
+import { DEFAULT_CODE_THEMES } from "./themes.ts";
+import type { CodeThemes } from "./themes.ts";
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
@@ -72,7 +75,9 @@ const loadHighlighter = async (): Promise<InlineHighlighter> => {
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
-export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
+export const inlineCodeHighlightPlugin = (
+  themes: CodeThemes = DEFAULT_CODE_THEMES
+): InlineCodePlugin => ({
   element: {
     filter: ["code"],
     async visit(node, ctx) {
@@ -90,7 +95,7 @@ export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
           defaultColor: false,
           lang: parsed.lang,
           structure: "inline",
-          themes: { dark: "github-dark", light: "github-light" },
+          themes,
         });
         return {
           children: root.children,
@@ -99,8 +104,13 @@ export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
           type: "element",
         };
       } catch {
-        // Unknown language or load failure: leave the code unhighlighted
-        // (falling through returns undefined, so the node is left as-is).
+        // Unknown language or load failure: still strip the marker — the
+        // literal `{:lang}` must not ship in the page — and fall back to
+        // plain, unhighlighted inline code.
+        return {
+          ...node,
+          children: [{ type: "text", value: parsed.code }],
+        };
       }
     },
   },

package/src/markdown/package-commands.ts

@@ -149,10 +149,16 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
       return `${manager} dlx ${args}`;
     }
     case "ci": {
-      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere.
-      return manager === "npm"
-        ? "npm ci"
-        : `${manager} install --frozen-lockfile`;
+      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere. Yarn
+      // Berry's flag is `--immutable` (`--frozen-lockfile` was removed in
+      // Yarn 4), matching the Berry-only `yarn dlx` the `exec` case emits.
+      if (manager === "npm") {
+        return "npm ci";
+      }
+      if (manager === "yarn") {
+        return "yarn install --immutable";
+      }
+      return `${manager} install --frozen-lockfile`;
     }
     case "remove": {
       if (manager === "npm") {

package/src/markdown/themes.ts

@@ -0,0 +1,24 @@
+/**
+ * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
+ * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
+ * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
+ * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * single home for the github fallback used when nothing is configured.
+ */
+
+/**
+ * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * `interface`) so it keeps the implicit index signature Shiki's `themes`
+ * parameter (`Partial<Record<string, …>>`) expects.
+ */
+// oxlint-disable-next-line typescript/consistent-type-definitions -- interface loses the implicit index signature Shiki's `themes` param needs
+export type CodeThemes = {
+  dark: string;
+  light: string;
+};
+
+/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+export const DEFAULT_CODE_THEMES: CodeThemes = {
+  dark: "github-dark",
+  light: "github-light",
+};

package/src/openapi/model.ts

@@ -104,22 +104,31 @@ const isOperation = (value: unknown): value is OperationObject =>
 /**
  * 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.
+ * a repeated `operationId` still yields distinct routes. `warnings` reports
+ * anything skipped (a `$ref` path item), so missing operations aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
   baseRoute: string
-): { operations: ApiOperationRef[]; tags: ApiTagRef[] } => {
+): { operations: ApiOperationRef[]; tags: ApiTagRef[]; warnings: string[] } => {
   const operations: ApiOperationRef[] = [];
   const tagOrder: string[] = [];
+  const tagsSeen = new Set<string>();
   const tagMeta = new Map(
     (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
   );
   const seen = new Set<string>();
+  const warnings: string[] = [];
 
   for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
     const item = rawItem as PathItemObject | undefined;
-    if (!item || "$ref" in item) {
+    if (!item) {
+      continue;
+    }
+    if ("$ref" in item) {
+      warnings.push(
+        `Path "${path}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
+      );
       continue;
     }
     for (const method of HTTP_METHODS) {
@@ -129,7 +138,8 @@ export const extractOperations = (
       }
       const tag = operation.tags?.[0] ?? UNTAGGED;
       const tagSlug = slugify(tag) || "operations";
-      if (!tagOrder.includes(tag)) {
+      if (!tagsSeen.has(tag)) {
+        tagsSeen.add(tag);
         tagOrder.push(tag);
       }
       let key = operationKey(method, path, operation.operationId);
@@ -159,7 +169,7 @@ export const extractOperations = (
     slug: slugify(name) || "operations",
   }));
 
-  return { operations, tags };
+  return { operations, tags, warnings };
 };
 
 /** Resolve the operation object for a ref out of its document. */

package/src/openapi/parse.ts

@@ -47,6 +47,19 @@ export interface ParsedSpec {
   warnings: string[];
 }
 
+/**
+ * The spec was read successfully but its contents aren't an OpenAPI document
+ * (an empty file, or YAML that parses to a scalar or list — say, a README
+ * pointed at by mistake). Kept distinct from read/fetch failures so callers
+ * can suggest fixing the file instead of checking reachability.
+ */
+export class InvalidSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidSpecError";
+  }
+}
+
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
   /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
@@ -235,5 +248,13 @@ export const parseSpec = async (
   const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize(text);
   const { specification } = upgrade(normalized);
+  // `normalize` yields undefined for anything that isn't a YAML/JSON mapping
+  // (empty file, scalar, list) and `upgrade(undefined)` yields a null
+  // specification — reject it here so the renderer never sees a non-document.
+  if (specification === null || typeof specification !== "object") {
+    throw new InvalidSpecError(
+      `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
+    );
+  }
   return { document: specification as ApiDocument, warnings };
 };