blume 0.1.5 → 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

@@ -283,6 +283,31 @@ const notionSourceSchema = z.object({
   type: z.literal("notion"),
 });
 
+/**
+ * A repo's GitHub Releases, materialized as `type: changelog` entries — release
+ * notes become the changelog with no files to maintain. A private repo reads a
+ * token from `GITHUB_TOKEN`; it is never inlined here.
+ */
+const githubReleasesSourceSchema = z
+  .object({
+    /** Include draft releases (needs a token with repo write access). */
+    drafts: z.boolean().optional(),
+    /** Cap the number of releases materialized, newest-first. Default 100. */
+    limit: z.number().positive().optional(),
+    /** Repository owner (user or org). */
+    owner: z.string(),
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval: z.number().positive().optional(),
+    /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+    prefix: z.string().optional(),
+    /** Include prereleases. */
+    prereleases: z.boolean().optional(),
+    /** Repository name. */
+    repo: z.string(),
+    type: z.literal("github-releases"),
+  })
+  .strict();
+
 /**
  * In-place Mintlify content (`docs.json` + MDX). Powers "bridge mode": Blume
  * reads an unconverted Mintlify project, transforming each page to Blume MDX at
@@ -328,6 +353,7 @@ const customSourceSchema = z.object({
 const contentSourceSchema = z.discriminatedUnion("type", [
   filesystemSourceSchema,
   mdxRemoteSourceSchema,
+  githubReleasesSourceSchema,
   sanitySourceSchema,
   notionSourceSchema,
   mintlifySourceSchema,
@@ -436,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({});
@@ -502,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({
@@ -635,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();
@@ -954,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.
@@ -1011,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({}),
@@ -1018,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(),
     /**
@@ -1038,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/github-releases.ts

@@ -0,0 +1,200 @@
+import matter from "../frontmatter.ts";
+import {
+  hashText,
+  loadWithCache,
+  pollingWatch,
+  snapshotCache,
+} from "./cache.ts";
+import type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+  SourceLoadResult,
+} from "./types.ts";
+
+/** Options for the built-in GitHub Releases changelog source. */
+export interface GithubReleasesSourceOptions {
+  /** GitHub REST API base; overridable for GitHub Enterprise / tests. */
+  baseUrl?: string;
+  /** Include draft releases (needs a token with repo write access). Default off. */
+  drafts?: boolean;
+  /** Injected for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Cap the number of releases materialized, newest-first. Default 100. */
+  limit?: number;
+  name: string;
+  /** Repository owner (user or org). */
+  owner: string;
+  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+  pollInterval?: number;
+  /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+  prefix?: string;
+  /** Include prereleases. Default off. */
+  prereleases?: boolean;
+  /** Repository name. */
+  repo: string;
+}
+
+/** The subset of the GitHub release payload the adapter reads. */
+interface GithubRelease {
+  body: string | null;
+  created_at: string;
+  draft: boolean;
+  html_url: string;
+  id: number;
+  name: string | null;
+  prerelease: boolean;
+  published_at: string | null;
+  tag_name: string;
+}
+
+const DEFAULT_BASE_URL = "https://api.github.com";
+const DEFAULT_LIMIT = 100;
+const PER_PAGE = 100;
+
+const LEADING_V = /^v/iu;
+const NON_SLUG = /[^a-z0-9]+/gu;
+const EDGE_DASHES = /^-+|-+$/gu;
+
+/** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
+const slugifyTag = (tag: string): string =>
+  tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
+
+/** Build request headers, reading `GITHUB_TOKEN` fresh at call time. */
+const githubHeaders = (): Headers => {
+  const headers = new Headers({ Accept: "application/vnd.github+json" });
+  const token = process.env.GITHUB_TOKEN;
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+  return headers;
+};
+
+/**
+ * Lower one release to a staged Markdown entry: the notes become the body and
+ * `type: changelog` frontmatter (title/date/version/category) drives the
+ * generated `/changelog` timeline and RSS feed.
+ */
+const releaseToEntry = (release: GithubRelease): SourceEntry => {
+  const version = release.tag_name.replace(LEADING_V, "");
+  const title = release.name?.trim() || release.tag_name;
+  const date = release.published_at ?? release.created_at;
+  const category = release.prerelease ? "Prerelease" : "Release";
+  const body = (release.body ?? "").replaceAll("\r\n", "\n").trim();
+  const data = {
+    changelog: { category, version },
+    date,
+    title,
+    type: "changelog",
+  };
+  const raw = matter.stringify(`${body}\n`, data);
+  const ref = `${slugifyTag(release.tag_name) || `release-${release.id}`}.md`;
+  return {
+    body: { format: "md", text: body },
+    data,
+    editUrl: release.html_url,
+    hash: hashText(raw),
+    lastModified: date,
+    raw,
+    ref,
+  };
+};
+
+/**
+ * GitHub Releases content source. Pulls a repo's releases from the REST API and
+ * materializes each as a `type: changelog` entry, so a project's release notes
+ * become its changelog with no files to maintain. A private repo authenticates
+ * with `GITHUB_TOKEN`. A snapshot under `.blume/cache/<source>/` keeps rebuilds
+ * offline-tolerant.
+ */
+export const githubReleasesSource = (
+  options: GithubReleasesSourceOptions,
+  ctx: SourceContext
+): ContentSource => {
+  const doFetch = options.fetchImpl ?? globalThis.fetch;
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/u, "");
+  const max = options.limit ?? DEFAULT_LIMIT;
+  const cache = snapshotCache(ctx.cacheDir);
+  let snapshot = new Map<string, SourceEntry>();
+
+  const include = (release: GithubRelease): boolean =>
+    (options.drafts || !release.draft) &&
+    (options.prereleases || !release.prerelease);
+
+  const fetchPage = async (page: number): Promise<GithubRelease[]> => {
+    const url = `${base}/repos/${options.owner}/${options.repo}/releases?per_page=${PER_PAGE}&page=${page}`;
+    const res = await doFetch(url, { headers: githubHeaders() });
+    if (!res.ok) {
+      throw new Error(`${url} -> ${res.status}`);
+    }
+    return (await res.json()) as GithubRelease[];
+  };
+
+  const fetchReleases = async (): Promise<GithubRelease[]> => {
+    const collected: GithubRelease[] = [];
+    let page = 1;
+    while (collected.length < max) {
+      // oxlint-disable-next-line no-await-in-loop -- pages are sequential: each page's length decides whether another exists.
+      const batch = await fetchPage(page);
+      collected.push(...batch.filter(include));
+      if (batch.length < PER_PAGE) {
+        break;
+      }
+      page += 1;
+    }
+    return collected.slice(0, max);
+  };
+
+  const load = async (): Promise<SourceLoadResult> => {
+    try {
+      const result = await loadWithCache(
+        options.name,
+        cache,
+        async () => {
+          const releases = await fetchReleases();
+          return releases.map(releaseToEntry);
+        },
+        ctx.refresh ?? true
+      );
+      snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
+      return result;
+    } catch (error) {
+      // A changelog is supplementary. When releases can't be fetched and nothing
+      // is cached (e.g. CI or a deploy without a `GITHUB_TOKEN` for a private
+      // repo), degrade to an empty changelog with a warning rather than failing
+      // the whole build.
+      snapshot = new Map();
+      return {
+        diagnostics: [
+          {
+            code: "BLUME_SOURCE_UNAVAILABLE",
+            message: `Source "${options.name}" could not fetch GitHub releases (${(error as Error).message}); the changelog will be empty. Set GITHUB_TOKEN to include it (required for a private repository).`,
+            severity: "warning",
+          },
+        ],
+        entries: [],
+      };
+    }
+  };
+
+  const read = async (ref: string): Promise<string> => {
+    const cached = snapshot.get(ref);
+    if (cached) {
+      return cached.raw ?? cached.body.text;
+    }
+    const all = await cache.read();
+    const entry = all.find((e) => e.ref === ref);
+    return entry?.raw ?? entry?.body.text ?? "";
+  };
+
+  return {
+    load,
+    name: options.name,
+    prefix: options.prefix,
+    read,
+    staged: true,
+    watch: options.pollInterval
+      ? pollingWatch(load, options.pollInterval)
+      : undefined,
+  };
+};