blume 0.2.0 → 0.3.0

package/src/core/nav-diagnostics.ts

@@ -0,0 +1,205 @@
+import { hasIcon } from "../theme/icons.ts";
+import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
+
+/**
+ * Navigation diagnostics: catch icon typos and structural mistakes (missing
+ * pages, duplicate labels) that otherwise fail silently — a wrong icon just
+ * doesn't render, a bad tab path just 404s. Run over the built navigation so it
+ * covers every source (config, folder meta, frontmatter) at once.
+ */
+
+const IMAGE_ICON =
+  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
+
+/** Whether an icon string is an asset (image/URL/inline SVG), not a set name. */
+const isAssetIcon = (value: string): boolean =>
+  value.startsWith("<") || IMAGE_ICON.test(value);
+
+/** Flatten a sidebar tree to every node, descending into groups. */
+const flattenNodes = (nodes: NavNode[]): NavNode[] =>
+  nodes.flatMap((node) =>
+    node.kind === "group" ? [node, ...flattenNodes(node.children)] : [node]
+  );
+
+/** Every icon string referenced anywhere in the navigation, with a label. */
+const collectIcons = (
+  navigation: Navigation
+): { icon: string; where: string }[] => {
+  const icons: { icon: string; where: string }[] = [];
+  const push = (icon: string | undefined, where: string): void => {
+    if (icon) {
+      icons.push({ icon, where });
+    }
+  };
+  for (const tab of navigation.tabs) {
+    push(tab.icon, `tab "${tab.label}"`);
+    for (const item of tab.items ?? []) {
+      push(item.icon, `tab item "${item.label}"`);
+    }
+  }
+  for (const selector of navigation.selectors) {
+    for (const item of selector.items) {
+      push(item.icon, `selector "${item.label}"`);
+    }
+  }
+  const sidebars = [
+    navigation.sidebar,
+    ...navigation.sidebarVariants.map((variant) => variant.sidebar),
+  ];
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      push(node.icon, `"${node.label}"`);
+    }
+  }
+  return icons;
+};
+
+/** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
+export const validateNavIcons = (navigation: Navigation): Diagnostic[] => {
+  const seen = new Set<string>();
+  const diagnostics: Diagnostic[] = [];
+  for (const { icon, where } of collectIcons(navigation)) {
+    if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
+      continue;
+    }
+    seen.add(icon);
+    diagnostics.push({
+      code: "BLUME_UNKNOWN_ICON",
+      message: `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`,
+      severity: "warning",
+      suggestion:
+        "Use a built-in icon name, an image path/URL, or inline SVG markup.",
+    });
+  }
+  return diagnostics;
+};
+
+/** Whether an internal path resolves to a page or a section that has pages. */
+const resolvesToPages = (routes: Set<string>, path: string): boolean =>
+  routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
+
+/**
+ * Warn when a config-linked tab/selector target has no matching page. `routes`
+ * must be the full set of servable routes — content, custom `.astro` pages, and
+ * generated routes — so this runs where all three are known (`generateRuntime`),
+ * not in the content-only graph build.
+ */
+export const validateNavTargets = (
+  navigation: Navigation,
+  routes: Set<string>
+): Diagnostic[] => {
+  const targets: { label: string; path: string }[] = [
+    ...navigation.tabs.map((tab) => ({ label: tab.label, path: tab.path })),
+    ...navigation.selectors.flatMap((selector) =>
+      selector.items.map((item) => ({ label: item.label, path: item.path }))
+    ),
+  ];
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const { label, path } of targets) {
+    // Only internal, non-anchor paths can be checked against routes.
+    if (!path.startsWith("/") || path.startsWith("/#") || seen.has(path)) {
+      continue;
+    }
+    if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {
+      seen.add(path);
+      diagnostics.push({
+        code: "BLUME_NAV_MISSING_PAGE",
+        message: `Navigation entry "${label}" points to ${path}, but no page matches it.`,
+        severity: "warning",
+        suggestion: "Fix the path, or add a page at that route.",
+      });
+    }
+  }
+  return diagnostics;
+};
+
+/** Warn about two nav items sharing a label at the same sidebar level. */
+const duplicateLabelDiagnostics = (navigation: Navigation): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const checkLevel = (nodes: NavNode[], where: string): void => {
+    const counts = new Map<string, number>();
+    for (const node of nodes) {
+      counts.set(node.label, (counts.get(node.label) ?? 0) + 1);
+    }
+    for (const [label, count] of counts) {
+      if (count > 1) {
+        diagnostics.push({
+          code: "BLUME_NAV_DUPLICATE_LABEL",
+          message: `Duplicate sidebar label "${label}" appears ${count} times ${where}.`,
+          severity: "warning",
+          suggestion: "Give the entries distinct titles.",
+        });
+      }
+    }
+    for (const node of nodes) {
+      if (node.kind === "group") {
+        checkLevel(node.children, `under "${node.label}"`);
+      }
+    }
+  };
+  const sidebars: { nodes: NavNode[]; where: string }[] = [
+    { nodes: navigation.sidebar, where: "at the top level" },
+    ...navigation.sidebarVariants.map((variant) => ({
+      nodes: variant.sidebar,
+      where: `in the "${variant.path}" section`,
+    })),
+  ];
+  for (const { nodes, where } of sidebars) {
+    checkLevel(nodes, where);
+  }
+  return diagnostics;
+};
+
+/** Warn when a page shown in the sidebar is marked hidden (so pagination hits it). */
+const hiddenInSidebarDiagnostics = (
+  navigation: Navigation,
+  pages: PageRecord[]
+): Diagnostic[] => {
+  const hidden = new Set(
+    pages.filter((page) => page.meta.sidebar.hidden).map((page) => page.id)
+  );
+  if (hidden.size === 0) {
+    return [];
+  }
+  const sidebars = [
+    navigation.sidebar,
+    ...navigation.sidebarVariants.map((variant) => variant.sidebar),
+  ];
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      if (
+        node.kind === "page" &&
+        hidden.has(node.pageId) &&
+        !seen.has(node.pageId)
+      ) {
+        seen.add(node.pageId);
+        diagnostics.push({
+          code: "BLUME_NAV_HIDDEN_IN_SIDEBAR",
+          message: `Page "${node.label}" is marked hidden but appears in the sidebar (and its pagination).`,
+          severity: "warning",
+          suggestion:
+            "Remove it from the navigation config, or unset sidebar.hidden.",
+        });
+      }
+    }
+  }
+  return diagnostics;
+};
+
+/**
+ * Structural navigation diagnostics that need only the built navigation +
+ * content pages: duplicate sidebar labels at a level, and hidden pages that
+ * still surface in the sidebar (so pagination lands on them). Target existence
+ * is checked separately by {@link validateNavTargets}, which needs the full
+ * route set.
+ */
+export const validateNavStructure = (
+  navigation: Navigation,
+  pages: PageRecord[]
+): Diagnostic[] => [
+  ...duplicateLabelDiagnostics(navigation),
+  ...hiddenInSidebarDiagnostics(navigation, pages),
+];

package/src/core/project-graph.ts

@@ -24,6 +24,41 @@ import type {
 /** Build mode: drafts are kept in `dev` and dropped in `build`. */
 export type BuildMode = "dev" | "build";
 
+/** CLI-supplied overrides applied over the loaded config (see `scanProject`). */
+export interface ConfigOverrides {
+  /** Override `content.root` (`blume dev --content-dir`). */
+  contentRoot?: string;
+  /** Override `deployment.adapter` (`blume build --adapter`). */
+  adapter?: ResolvedConfig["deployment"]["adapter"];
+  /** Override `deployment.base` (`blume build --base`). */
+  base?: string;
+  /** Override `deployment.output` (`blume build --output`). */
+  output?: ResolvedConfig["deployment"]["output"];
+}
+
+/** Apply CLI config overrides onto a resolved config (returns a new object). */
+const applyConfigOverrides = (
+  config: ResolvedConfig,
+  overrides?: ConfigOverrides
+): ResolvedConfig => {
+  if (!overrides) {
+    return config;
+  }
+  return {
+    ...config,
+    content: {
+      ...config.content,
+      root: overrides.contentRoot ?? config.content.root,
+    },
+    deployment: {
+      ...config.deployment,
+      adapter: overrides.adapter ?? config.deployment.adapter,
+      base: overrides.base ?? config.deployment.base,
+      output: overrides.output ?? config.deployment.output,
+    },
+  };
+};
+
 /** Everything Blume knows about a project after a full scan. */
 export interface BlumeProject {
   mode: BuildMode;
@@ -51,13 +86,17 @@ export const scanProject = async (
     mode?: BuildMode;
     preview?: boolean;
     refresh?: boolean;
+    /** CLI overrides applied over the loaded config (e.g. `--output`). */
+    overrides?: ConfigOverrides;
   } = {}
 ): Promise<BlumeProject> => {
   const mode = options.mode ?? "dev";
   const preview = options.preview ?? false;
-  const { bridge, config } = await loadConfig(root, {
+  const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
+  const { bridge } = configResult;
+  const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config);
 
   // Each source validates itself (e.g. the filesystem source checks its root

package/src/core/schema.ts

@@ -462,38 +462,6 @@ const sidebarVariantSchema = z
   })
   .strict();
 
-const navbarLinkTypeSchema = z.enum(["github", "discord"]);
-
-const navbarLinkSchema = z
-  .object({
-    href: z.string(),
-    icon: iconName.optional(),
-    label: z.string().optional(),
-    type: navbarLinkTypeSchema.optional(),
-  })
-  .strict()
-  .refine((value) => value.label !== undefined || value.type !== undefined, {
-    message: "Navbar links require either label or type.",
-  });
-
-const navbarPrimarySchema = z
-  .object({
-    href: z.string(),
-    label: z.string().optional(),
-    type: z.enum(["button", "github", "discord"]).default("button"),
-  })
-  .strict()
-  .refine((value) => value.label !== undefined || value.type !== "button", {
-    message: "Navbar primary button links require a label.",
-  });
-
-const navbarConfigSchema = z
-  .object({
-    links: z.array(navbarLinkSchema).default([]),
-    primary: navbarPrimarySchema.optional(),
-  })
-  .strict();
-
 const variablesConfigSchema = z
   .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
   .default({});
@@ -528,12 +496,6 @@ const themeConfigSchema = z
   })
   .strict();
 
-const iconsConfigSchema = z
-  .object({
-    library: z.enum(["fontawesome", "lucide", "tabler"]).default("lucide"),
-  })
-  .strict();
-
 /** Public credentials for the Algolia search backend (sync key is an env var). */
 const algoliaSearchSchema = z
   .object({
@@ -661,56 +623,9 @@ const aiConfigSchema = z
   })
   .strict();
 
-const contextualOptionSchema = z.union([
-  z.string(),
-  z
-    .object({
-      description: z.string().optional(),
-      href: z.string().optional(),
-      icon: iconName.optional(),
-      title: z.string(),
-    })
-    .passthrough(),
-]);
-
-const contextualConfigSchema = z
-  .object({
-    display: z.enum(["header", "toc"]).default("header"),
-    options: z.array(contextualOptionSchema).default([]),
-  })
-  .strict();
-
-const footerConfigSchema = z
-  .object({
-    links: z
-      .array(
-        z
-          .object({
-            header: z.string().optional(),
-            items: z
-              .array(
-                z
-                  .object({
-                    href: z.string(),
-                    label: z.string(),
-                  })
-                  .strict()
-              )
-              .default([]),
-          })
-          .strict()
-      )
-      .max(4)
-      .default([]),
-    socials: z.record(z.string(), z.string()).default({}),
-  })
-  .strict();
-
 const chromeVariantSchema = z
   .object({
     banner: bannerConfigSchema.optional(),
-    footer: footerConfigSchema.optional(),
-    navbar: navbarConfigSchema.optional(),
     path: z.string(),
   })
   .strict();
@@ -980,12 +895,6 @@ const markdownConfigSchema = z
   })
   .strict();
 
-const stylingConfigSchema = z
-  .object({
-    eyebrows: z.enum(["breadcrumbs", "section"]).default("section"),
-  })
-  .strict();
-
 /**
  * A single spec rendered by the API reference (Scalar). `spec` is a local path
  * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
@@ -1037,6 +946,33 @@ const asyncapiConfigSchema = z
   .strict();
 
 /** Full user-facing config schema. All fields optional with defaults. */
+/**
+ * Table-of-contents config. `true`/`false` toggles it; an object narrows the
+ * heading range. Normalized to `{ enabled, minLevel, maxLevel }` (default: on,
+ * H2–H3, matching the historical hardcoded range).
+ */
+const tocConfigSchema = z
+  .union([
+    z.boolean(),
+    z
+      .object({
+        maxHeadingLevel: z.number().int().min(1).max(6).optional(),
+        minHeadingLevel: z.number().int().min(1).max(6).optional(),
+      })
+      .strict(),
+  ])
+  .default(true)
+  .transform((value) => {
+    if (typeof value === "boolean") {
+      return { enabled: value, maxLevel: 3, minLevel: 2 };
+    }
+    return {
+      enabled: true,
+      maxLevel: value.maxHeadingLevel ?? 3,
+      minLevel: value.minHeadingLevel ?? 2,
+    };
+  });
+
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1044,7 +980,6 @@ export const blumeConfigSchema = z
     asyncapi: asyncapiConfigSchema.default({}),
     banner: bannerConfigSchema.optional(),
     content: contentConfigSchema.default({}),
-    contextual: contextualConfigSchema.default({}),
     deployment: deploymentConfigSchema.default({}),
     description: z.string().optional(),
     /**
@@ -1064,23 +999,20 @@ export const blumeConfigSchema = z
     export: exportConfigSchema.default(false),
     favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),
-    footer: footerConfigSchema.default({}),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
-    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),
     mcp: mcpConfigSchema.default({}),
-    navbar: navbarConfigSchema.default({}),
     navigation: navigationConfigSchema.default({}),
     openapi: openapiConfigSchema.default({}),
     redirects: z.array(redirectSchema).default([]),
     search: searchConfigSchema.default({}),
     seo: seoConfigSchema.default({}),
-    styling: stylingConfigSchema.default({}),
     theme: themeConfigSchema.default({}),
     title: z.string().default("Documentation"),
+    toc: tocConfigSchema,
     variables: variablesConfigSchema,
   })
   .strict();

package/src/core/sources/normalize.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
@@ -146,6 +148,44 @@ export const extractLinks = (body: string): PageLink[] => {
   return links;
 };
 
+const INLINE_CODE = /`[^`]*`/gu;
+// Double-quoted strings hold JSX attribute values and JSON in `{...}` props; a
+// `<Tag>` written inside prose there (e.g. an "Astro <Font> integration" note)
+// isn't a real usage. Single quotes are left alone so prose apostrophes don't
+// swallow a real tag between two words.
+const DOUBLE_QUOTED = /"[^"]*"/gu;
+const JSX_OPEN = /<(?<tag>[A-Z][A-Za-z0-9]*)/gu;
+
+/**
+ * Capitalized JSX component tags used in an `.mdx` body (`<Callout>`,
+ * `<Tree.File>` → `Tree`). Skips fenced code, inline code, and double-quoted
+ * strings so code samples and prose don't count. Powers the missing-component
+ * diagnostic.
+ */
+export const extractComponentTags = (body: string): string[] => {
+  const tags = new Set<string>();
+  let inFence = false;
+  for (const line of body.split("\n")) {
+    if (CODE_FENCE.test(line.trimStart())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    const clean = line
+      .replaceAll(INLINE_CODE, "")
+      .replaceAll(DOUBLE_QUOTED, "");
+    for (const match of clean.matchAll(JSX_OPEN)) {
+      const tag = match.groups?.tag;
+      if (tag) {
+        tags.add(tag);
+      }
+    }
+  }
+  return [...tags];
+};
+
 const deriveTitle = (
   meta: PageMeta,
   headings: Heading[],
@@ -179,10 +219,19 @@ export const normalizeEntry = (
 
   const result = pageMetaSchema.safeParse(entry.data);
   if (!result.success) {
+    // Source text lets the error carry a line/column into the frontmatter block:
+    // `entry.raw` for non-filesystem sources, else the file itself (read only on
+    // this rare error path, so filesystem entries stay cheap in the happy path).
+    const source =
+      entry.raw ??
+      (entry.sourcePath && existsSync(entry.sourcePath)
+        ? readFileSync(entry.sourcePath, "utf-8")
+        : undefined);
     return {
       diagnostics: diagnosticsFromZod(result.error, {
         code: "BLUME_FRONTMATTER_INVALID",
         file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
+        source,
       }),
       pages: [],
     };
@@ -212,6 +261,8 @@ export const normalizeEntry = (
   const base = {
     body: staged ? { format, text: entry.raw ?? entry.body.text } : undefined,
     collection: staged ? "staged" : undefined,
+    componentsUsed:
+      format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
     contentType: meta.type ?? ctx.defaultType,
     description: meta.description,
     editUrl: entry.editUrl,

package/src/core/types.ts

@@ -113,6 +113,8 @@ export interface PageRecord {
   format: "md" | "mdx";
   /** Internal/asset links discovered in the page (for validation). */
   links: PageLink[];
+  /** Capitalized JSX component tags used in the body (`.mdx` only). */
+  componentsUsed?: string[];
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
 }
@@ -181,8 +183,6 @@ export interface NavSidebarVariant {
 export interface NavChromeVariant {
   path: string;
   banner?: ResolvedConfig["banner"];
-  footer?: ResolvedConfig["footer"];
-  navbar?: ResolvedConfig["navbar"];
 }
 
 /** The complete navigation model derived from the content graph. */

package/src/deploy/redirects.ts

@@ -0,0 +1,43 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * Platform redirect files for a static build. Astro already emits redirect HTML
+ * (meta-refresh) pages for `deployment.output: "static"`, but that's a soft
+ * client redirect. These give the host a real HTTP 3xx: Netlify/Cloudflare read
+ * `_redirects`, Vercel reads `vercel.json`, and `blume-redirects.json` is a
+ * structured manifest for anything else (Apache/nginx rules, an edge worker).
+ */
+
+type Redirect = ResolvedConfig["redirects"][number];
+
+/** `_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). */
+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,
+      })),
+    },
+    null,
+    2
+  )}\n`;
+
+/** Structured manifest for hosts that need manual wiring. */
+export const buildRedirectManifest = (redirects: Redirect[]): string =>
+  `${JSON.stringify(
+    redirects.map((redirect) => ({
+      from: redirect.from,
+      status: redirect.status,
+      to: redirect.to,
+    })),
+    null,
+    2
+  )}\n`;