blume 0.1.5 → 0.3.0

package/src/astro/generate.ts

@@ -14,10 +14,13 @@ import { pathToFileURL } from "node:url";
 import { basename, dirname, join, normalize, relative } from "pathe";
 import { glob } from "tinyglobby";
 
+import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import { validateUsedComponents } from "../core/component-diagnostics.ts";
+import { analyzeComponentOverrides } from "../core/component-overrides.ts";
 import type {
   BlumeBanner,
   BlumeData,
@@ -26,6 +29,7 @@ import type {
 } from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
+import { validateNavTargets } from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
@@ -37,12 +41,15 @@ import {
   hasReferences,
   referenceTabs,
 } from "../openapi/scalar.ts";
+import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import { tailwindEntryTemplate } from "../theme/entry.ts";
 import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
+import { planComponentSlots } from "./component-slots.ts";
+import type { ComponentSlotPlan } from "./component-slots.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
@@ -72,7 +79,6 @@ import {
   searchClientTemplate,
   searchEndpointTemplate,
   stagedContentDir,
-  userComponentsTemplate,
 } from "./templates.ts";
 
 /** Absolute path to the Blume package `src` directory. */
@@ -661,6 +667,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       structuredData: config.seo.structuredData,
       theme: config.theme,
       title: config.title,
+      toc: config.toc,
     },
     feeds: buildRssFeeds(project).map((feed) => ({
       href: feed.path,
@@ -787,6 +794,33 @@ const writeMcpFiles = async (
   ]);
 };
 
+/**
+ * Write the Ask AI endpoint and, unless the backend runs its own retrieval
+ * (Inkeep), the grounding snapshot the endpoint queries at request time. A no-op
+ * when Ask AI is disabled.
+ */
+const writeAskFiles = async (
+  project: BlumeProject,
+  srcDir: string,
+  write: (path: string, content: string) => Promise<boolean>
+): Promise<void> => {
+  const { ask } = project.config.ai;
+  if (!ask?.enabled) {
+    return;
+  }
+  const grounded = ask.provider !== "inkeep";
+  if (grounded) {
+    await write(
+      join(srcDir, "generated", "ask-data.json"),
+      `${JSON.stringify(await buildAskData(project))}\n`
+    );
+  }
+  await write(
+    join(srcDir, "pages", "api", "ask.ts"),
+    askEndpointTemplate(resolveAskBackend(ask), grounded)
+  );
+};
+
 /**
  * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
  * static builds emit `dist/404.html`. Skipped when the project already owns
@@ -813,6 +847,57 @@ export interface GenerateResult {
   warnings: string[];
 }
 
+/**
+ * Whether to generate the default `/changelog` index. Written when there are
+ * `type: changelog` entries — or when a release-backed changelog source is
+ * configured, so its route (and any nav tab pointing at it) still resolves to an
+ * empty timeline on a build where the source could not be fetched (e.g. CI
+ * without a token). Skipped when a user content page already owns `/changelog`.
+ */
+const shouldGenerateChangelog = (project: BlumeProject): boolean => {
+  const hasChangelog = project.graph.pages.some(
+    (page) =>
+      page.contentType === "changelog" &&
+      !(page.meta.draft || page.meta.sidebar.hidden)
+  );
+  const hasChangelogSource = (project.config.content.sources ?? []).some(
+    (source) => source.type === "github-releases"
+  );
+  const changelogRouteTaken = project.graph.pages.some(
+    (page) => page.route === "/changelog"
+  );
+  return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
+};
+
+/**
+ * Statically analyze the user's `components.ts` (never executing it) and plan the
+ * generated `components.ts` module plus any hydration wrappers. Returns the plan
+ * and the analyzer's warnings; a project with no components file gets an empty
+ * plan and no warnings.
+ */
+const buildComponentSlots = async (
+  componentsFile: string | null
+): Promise<{
+  plan: ComponentSlotPlan;
+  /** MDX tags the overrides define (for the unknown-component check). */
+  tags: string[];
+  warnings: string[];
+}> => {
+  const analysis = componentsFile
+    ? analyzeComponentOverrides(
+        await readFile(componentsFile, "utf-8"),
+        componentsFile
+      )
+    : null;
+  return {
+    plan: planComponentSlots(componentsFile, analysis),
+    tags: analysis
+      ? [...analysis.mdx, ...analysis.islands].map((entry) => entry.key)
+      : [],
+    warnings: analysis ? analysis.warnings : [],
+  };
+};
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -851,12 +936,23 @@ export const generateRuntime = async (
       discoverIslands(context.root),
       discoverExamples(context.root, config.examples),
     ]);
+  // Statically analyze `components.ts` overrides (never executed): drives the
+  // `islands` group, hydration on layout/mdx overrides, string-path resolution,
+  // and the "framework component with no client mode" diagnostic.
+  const {
+    plan: slotPlan,
+    tags: overrideTags,
+    warnings: overrideWarnings,
+  } = await buildComponentSlots(context.componentsFile);
+
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
-  // island/example-driven. `.astro` examples need no renderer.
+  // island/example-driven. `.astro` examples need no renderer. Component
+  // overrides referencing a framework component enable its renderer too.
   const frameworks = new Set<string>([
     ...islandDiscovery.islands.map((island) => island.framework),
     ...exampleDiscovery.examples.map((example) => example.framework),
+    ...slotPlan.frameworks,
   ]);
   const needsReact = detectedReact || askEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
@@ -865,7 +961,7 @@ export const generateRuntime = async (
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
   // private and filtered out anyway, but the intent is the user's pages.
-  const ogRoutes = customOgRoutes(pages, config.title, config.description);
+  const ogRoutes = customOgRoutes(pages, config.title);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
@@ -915,12 +1011,10 @@ export const generateRuntime = async (
         exportEpub,
         exportPdf,
         mathEnabled: config.markdown.math,
+        needsReact,
       })
     ),
-    write(
-      join(srcDir, "generated", "components.ts"),
-      userComponentsTemplate(context.componentsFile)
-    ),
+    write(join(srcDir, "generated", "components.ts"), slotPlan.module),
     write(
       join(srcDir, "generated", "islands.ts"),
       islandMapTemplate(islandDiscovery.islands)
@@ -955,6 +1049,18 @@ export const generateRuntime = async (
     )
   );
 
+  // Per-override hydration wrappers for `defineComponents` islands and `client:*`
+  // layout/mdx overrides. The generated `components.ts` (written above) imports
+  // these; orphans from removed overrides are pruned at the end of the pass.
+  await Promise.all(
+    slotPlan.wrappers.map((wrapper) =>
+      write(
+        join(srcDir, "generated", "component-slots", `${wrapper.name}.astro`),
+        wrapper.content
+      )
+    )
+  );
+
   // Per-example live wrappers for the `examples/` convention, resolved by
   // `<Component path>` through the `examples.ts` map (written above, always).
   await Promise.all(
@@ -971,12 +1077,7 @@ export const generateRuntime = async (
     )
   );
 
-  if (askEnabled) {
-    await write(
-      join(srcDir, "pages", "api", "ask.ts"),
-      askEndpointTemplate(resolveAskBackend(config.ai.ask))
-    );
-  }
+  await writeAskFiles(project, srcDir, write);
 
   await writeMcpFiles(project, mcp, write);
 
@@ -987,21 +1088,17 @@ export const generateRuntime = async (
     );
   }
 
-  // Changelog index (`/changelog`): a timeline of every `type: changelog` entry,
-  // rendered through the Update layout. Skipped when there are no entries, or
-  // when a user content page already occupies the `/changelog` route.
-  const hasChangelog = project.graph.pages.some(
-    (page) =>
-      page.contentType === "changelog" &&
-      !(page.meta.draft || page.meta.sidebar.hidden)
-  );
-  const changelogRouteTaken = project.graph.pages.some(
-    (page) => page.route === "/changelog"
-  );
-  if (hasChangelog && !changelogRouteTaken) {
+  // Changelog index (`/changelog`), rendered through the Update timeline layout.
+  if (shouldGenerateChangelog(project)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
-      changelogIndexTemplate({ askEnabled, exportEpub, exportPdf })
+      changelogIndexTemplate({
+        askEnabled,
+        exportEpub,
+        exportPdf,
+        needsReact,
+        staged: hasStaged,
+      })
     );
   }
 
@@ -1075,8 +1172,47 @@ export const generateRuntime = async (
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,
+    ...overrideWarnings,
   ];
 
+  // Missing-navigation-target check, now that every servable route is known:
+  // content routes, custom `.astro` pages, the generated changelog, and any
+  // OpenAPI reference tabs.
+  const navTargetRoutes = new Set<string>([
+    ...project.graph.routes.keys(),
+    ...pages.map((page) => page.pattern),
+    ...referenceTabs(config).map((tab) => tab.path),
+  ]);
+  if (shouldGenerateChangelog(project)) {
+    navTargetRoutes.add("/changelog");
+  }
+  warnings.push(
+    ...validateNavTargets(project.graph.navigation, navTargetRoutes).map(
+      (diagnostic) =>
+        diagnostic.suggestion
+          ? `${diagnostic.message} ${diagnostic.suggestion}`
+          : diagnostic.message
+    )
+  );
+
+  // Unknown-component check: a `<Tag>` in MDX that isn't a built-in, an island,
+  // or a `components.ts` override. Needs the project's own components, known here.
+  const knownComponentTags = new Set<string>([
+    ...islandDiscovery.islands.map((island) => island.name),
+    ...overrideTags,
+  ]);
+  warnings.push(
+    ...validateUsedComponents(
+      project.graph.pages,
+      knownComponentTags,
+      new Set(registry.map((item) => item.name))
+    ).map((diagnostic) =>
+      diagnostic.suggestion
+        ? `${diagnostic.message} ${diagnostic.suggestion}`
+        : diagnostic.message
+    )
+  );
+
   // Provider SDKs are optional peers; warn (rather than fail opaquely in Vite)
   // when the configured provider's package isn't installed. A dep is available
   // if the project installed it (resolves from the root) OR Blume ships it

package/src/astro/integration.ts

@@ -2,8 +2,64 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 
 import type { AstroIntegration } from "astro";
 
+import { enrichDiagnostic } from "../core/diagnostics.ts";
+import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
 
+/** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
+interface OverlayChannel {
+  send: (payload: unknown) => void;
+}
+interface OverlayServer {
+  hot?: OverlayChannel;
+  ws?: OverlayChannel;
+}
+
+// Set on `astro:server:setup`; read by `showBlumeErrorOverlay` so the CLI's
+// regeneration can push Blume diagnostics into Vite's browser error overlay.
+// Same-process module singleton (dev and the integration share the instance).
+let overlayServer: OverlayServer | null = null;
+
+const overlayChannel = (): OverlayChannel | undefined =>
+  overlayServer?.ws ?? overlayServer?.hot;
+
+/**
+ * Surface Blume's own diagnostics (config/frontmatter/content errors) in the
+ * Vite/Astro browser error overlay during `blume dev`, so they don't hide in the
+ * terminal. A no-op when there are no errors or the dev server isn't up. The
+ * overlay clears itself on the next successful HMR update.
+ */
+export const showBlumeErrorOverlay = (diagnostics: Diagnostic[]): void => {
+  const errors = diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(enrichDiagnostic);
+  const channel = overlayChannel();
+  if (errors.length === 0 || !channel) {
+    return;
+  }
+  const body = errors
+    .map((diagnostic) => {
+      const where = diagnostic.file
+        ? `\n  at ${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}` : ""}`
+        : "";
+      const fix = diagnostic.suggestion
+        ? `\n  fix: ${diagnostic.suggestion}`
+        : "";
+      const docs = diagnostic.docsUrl ? `\n  docs: ${diagnostic.docsUrl}` : "";
+      return `[${diagnostic.code}] ${diagnostic.message}${where}${fix}${docs}`;
+    })
+    .join("\n\n");
+  channel.send({
+    err: {
+      id: errors[0]?.file,
+      message: `Blume found ${errors.length} error(s):\n\n${body}`,
+      plugin: "blume",
+      stack: "",
+    },
+    type: "error",
+  });
+};
+
 /** A user page mounted into the generated runtime. */
 export interface BlumePageRoute {
   /** Route pattern, e.g. `/changelog` or `/examples/[slug]`. */
@@ -62,6 +118,9 @@ export const blumeIntegration = (
       }
     },
     "astro:server:setup": ({ server }) => {
+      // Keep a handle on the dev server so Blume diagnostics can be pushed to
+      // its browser error overlay (see `showBlumeErrorOverlay`).
+      overlayServer = server as unknown as OverlayServer;
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({

package/src/astro/pages.ts

@@ -45,10 +45,8 @@ export const routeIsTaken = (
 export interface OgCustomRoute {
   /** `og/<slug>.png` path segment; `index` for the site root. */
   slug: string;
-  /** Card title. */
+  /** Card headline. */
   title: string;
-  /** Small eyebrow line above the title. */
-  eyebrow?: string;
 }
 
 /** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
@@ -68,13 +66,12 @@ const humanizeSegment = (segment: string): string =>
  *
  * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
  * are skipped: they aren't shareable pages. The home is titled with the site
- * title (eyebrow: the site description); a deeper page is titled from its last
- * path segment.
+ * title; a deeper page is titled from its last path segment. The card's brand
+ * lockup, description, and footer come from the resolved config at render time.
  */
 export const customOgRoutes = (
   pages: BlumePageRoute[],
-  siteTitle: string,
-  siteDescription?: string
+  siteTitle: string
 ): OgCustomRoute[] => {
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
@@ -91,11 +88,7 @@ export const customOgRoutes = (
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push(
-      last
-        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
-        : { eyebrow: siteDescription, slug, title: siteTitle }
-    );
+    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
   }
   return routes;
 };