blume 0.2.0 → 0.4.0

package/src/core/diagnostics.ts

@@ -17,10 +17,99 @@ export class BlumeError extends Error {
 export const createDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
   diagnostic;
 
+/** Docs site base; diagnostic help links resolve against it. */
+const DOCS_BASE = "https://useblume.dev";
+
+/** Diagnostic code → the docs page that explains it. */
+const DOCS_PATHS: Record<string, string> = {
+  BLUME_ADAPTER_REQUIRED: "/docs/deployment",
+  BLUME_ASSETS_UNCHECKED: "/docs/reference/cli",
+  BLUME_ASSET_FETCH_FAILED: "/docs/content/sources",
+  BLUME_BROKEN_ANCHOR: "/docs/reference/cli",
+  BLUME_BROKEN_ASSET: "/docs/reference/cli",
+  BLUME_BROKEN_LINK: "/docs/reference/cli",
+  BLUME_CONFIG_INVALID: "/docs/configuration",
+  BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
+  BLUME_CONTENT_ROOT_MISSING: "/docs/content/sources",
+  BLUME_DEAD_LINK: "/docs/reference/cli",
+  BLUME_DUPLICATE_ROUTE: "/docs/content/navigation",
+  BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+  BLUME_META_INVALID: "/docs/content/meta",
+  BLUME_META_LOAD_FAILED: "/docs/content/meta",
+  BLUME_MISSING_SECRET: "/docs/deployment",
+  BLUME_NAV_DUPLICATE_LABEL: "/docs/content/navigation",
+  BLUME_NAV_HIDDEN_IN_SIDEBAR: "/docs/content/navigation",
+  BLUME_NAV_MISSING_PAGE: "/docs/content/navigation",
+  BLUME_NODE_VERSION: "/docs/quickstart",
+  BLUME_SERVER_FEATURE_REQUIRED: "/docs/deployment",
+  BLUME_SOURCE_FETCH_FAILED: "/docs/content/sources",
+  BLUME_SOURCE_MISCONFIGURED: "/docs/content/sources",
+  BLUME_SOURCE_OFFLINE: "/docs/content/sources",
+  BLUME_SOURCE_SDK_MISSING: "/docs/content/sources",
+  BLUME_SOURCE_UNAVAILABLE: "/docs/content/sources",
+  BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+  BLUME_UNKNOWN_ICON: "/docs/content/navigation",
+};
+
+/** The docs URL that explains a diagnostic code, if one is mapped. */
+export const resolveDocsUrl = (code: string): string | undefined => {
+  const path = DOCS_PATHS[code];
+  return path ? `${DOCS_BASE}${path}` : undefined;
+};
+
+/** Fill in `docsUrl` from the code map where a diagnostic doesn't set its own. */
+export const enrichDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
+  diagnostic.docsUrl
+    ? diagnostic
+    : { ...diagnostic, docsUrl: resolveDocsUrl(diagnostic.code) };
+
+const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
+const escapeRegExp = (value: string): string =>
+  value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
+
+/**
+ * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`) in
+ * the raw config / frontmatter text. Narrows key-by-key — finding each string
+ * segment as a `key:`/`key =` at or after the previous match — so a nested key
+ * lands under its parent. Array indices are skipped. Returns 1-based line/column,
+ * or undefined when nothing matches.
+ */
+const locatePath = (
+  source: string,
+  path: readonly (string | number)[]
+): { column: number; line: number } | undefined => {
+  let cursor = 0;
+  let found = -1;
+  for (const segment of path) {
+    if (typeof segment !== "string") {
+      continue;
+    }
+    // The negative lookbehind keeps a segment like `title` from matching the
+    // tail of an unrelated key such as `subtitle:`.
+    const matcher = new RegExp(
+      `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
+      "gu"
+    );
+    matcher.lastIndex = cursor;
+    const match = matcher.exec(source);
+    if (!match) {
+      break;
+    }
+    found = match.index;
+    cursor = matcher.lastIndex;
+  }
+  if (found < 0) {
+    return;
+  }
+  const before = source.slice(0, found);
+  const lastNewline = before.lastIndexOf("\n");
+  return { column: found - lastNewline, line: before.split("\n").length };
+};
+
 /** Convert a ZodError into Blume diagnostics, anchored to a file. */
 export const diagnosticsFromZod = (
   error: ZodError,
-  options: { code: string; file?: string }
+  options: { code: string; file?: string; source?: string }
 ): Diagnostic[] =>
   error.issues.map((issue) => {
     const schemaPath = issue.path.join(".");
@@ -28,9 +117,14 @@ export const diagnosticsFromZod = (
       "received" in issue
         ? ` (received: ${JSON.stringify(issue.received)})`
         : "";
+    const position = options.source
+      ? locatePath(options.source, issue.path)
+      : undefined;
     return {
       code: options.code,
+      column: position?.column,
       file: options.file,
+      line: position?.line,
       message: schemaPath
         ? `${schemaPath}: ${issue.message}${received}`
         : `${issue.message}${received}`,

package/src/core/gitignore.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+/** A `.gitignore` line, normalized for comparison (trailing slashes dropped). */
+const gitignoreKey = (line: string): string => line.trim().replace(/\/+$/u, "");
+
+/**
+ * Ensure `.gitignore` ignores each of `entries`, appending any that are missing
+ * (creating the file when absent). Trailing-slash differences (`dist` vs
+ * `dist/`) count as already present. Returns the entries actually added.
+ */
+export const ensureGitignore = async (
+  root: string,
+  entries: string[]
+): Promise<string[]> => {
+  const path = join(root, ".gitignore");
+  const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
+  const present = new Set(
+    existing.split("\n").map(gitignoreKey).filter(Boolean)
+  );
+  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
+  if (added.length === 0) {
+    return [];
+  }
+  const gap = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await writeFile(path, `${existing}${gap}${added.join("\n")}\n`, "utf-8");
+  return added;
+};

package/src/core/graph.ts

@@ -1,4 +1,5 @@
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
+import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
 import { buildNavigation } from "./navigation.ts";
 import type {
   FolderMeta,
@@ -118,6 +119,12 @@ export const buildContentGraph = (
     });
   }
 
+  // Icon typos, duplicate labels, and hidden-page-in-sidebar are validated on
+  // the built navigation. Missing-target detection needs the full route set
+  // (incl. custom + generated pages), so it runs later in generateRuntime.
+  diagnostics.push(...validateNavIcons(navigation));
+  diagnostics.push(...validateNavStructure(navigation, pages));
+
   return {
     diagnostics,
     navigation,

package/src/core/links.ts

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 
-import { join } from "pathe";
+import { basename, join } from "pathe";
 
+import type { AssetMount } from "./assets.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -37,20 +38,52 @@ interface ExternalRef extends LinkSite {
 /** Lookups derived once from the content graph. */
 interface LinkContext {
   anchors: Map<string, Set<string>>;
+  /** `content.assets` mounts served alongside `public/` (checked in place). */
+  assetMounts: AssetMount[];
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
   routes: Set<string>;
 }
 
+/** Whether a resolved asset path exists under `public/` or an asset mount. */
+const assetIsPresent = (resolved: string, ctx: LinkContext): boolean => {
+  if (ctx.publicDir && existsSync(join(ctx.publicDir, resolved))) {
+    return true;
+  }
+  return ctx.assetMounts.some(
+    (mount) =>
+      (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) &&
+      existsSync(join(mount.dir, resolved.slice(mount.url.length)))
+  );
+};
+
 /** Outcome of classifying one link target. */
 type LinkResult = Diagnostic | "asset-unchecked" | null;
 
+/**
+ * Whether a page is a directory index (`…/index.md(x)`). Its route already *is*
+ * its directory, so a relative link must resolve against the route itself, not
+ * its parent — otherwise `./sibling` from `guides/index.mdx` (route `/guides`)
+ * would resolve to `/sibling` and be falsely flagged as broken.
+ */
+const isIndexPage = (page: PageRecord): boolean => {
+  const ref = page.source?.ref ?? page.sourcePath ?? "";
+  return /^index\.(?:md|mdx)$/iu.test(basename(ref));
+};
+
 /** Resolve a relative link target against the directory of a page route. */
-const resolveRelative = (pageRoute: string, target: string): string => {
+const resolveRelative = (
+  pageRoute: string,
+  target: string,
+  isIndex: boolean
+): string => {
   const segments = pageRoute.split("/").filter(Boolean);
-  // Drop the page's own segment so links resolve against its parent directory.
-  segments.pop();
+  // Drop a leaf page's own segment so links resolve against its parent
+  // directory. An index page's route already is its directory, so keep it.
+  if (!isIndex) {
+    segments.pop();
+  }
   for (const part of target.split("/")) {
     if (part === "" || part === ".") {
       continue;
@@ -114,13 +147,28 @@ const checkPathLink = (
   site: LinkSite,
   ctx: LinkContext
 ): LinkResult => {
+  // A real route always wins over the asset-extension heuristic, so a path
+  // whose last segment merely contains a dot (e.g. a page at `/releases/v1.0`)
+  // isn't misread as a missing asset.
+  const route = toRoute(resolved);
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // Its destination (and any anchor there) is validated on its own page, so we
+  // don't follow the redirect to check the fragment here.
+  if (ctx.redirects.has(route)) {
+    return null;
+  }
+
   if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (ctx.publicDir === null) {
-      return "asset-unchecked";
-    }
-    if (existsSync(join(ctx.publicDir, resolved))) {
+    if (assetIsPresent(resolved, ctx)) {
       return null;
     }
+    // Nowhere to look: no `public/` and no asset mounts configured.
+    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+      return "asset-unchecked";
+    }
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
@@ -130,16 +178,6 @@ const checkPathLink = (
     };
   }
 
-  const route = toRoute(resolved);
-  if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
-  }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
-  // Its destination (and any anchor there) is validated on its own page, so we
-  // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
-    return null;
-  }
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
@@ -295,7 +333,7 @@ const classifyLink = (
 
   const resolved = rawPath.startsWith("/")
     ? rawPath
-    : resolveRelative(page.route, rawPath);
+    : resolveRelative(page.route, rawPath, isIndexPage(page));
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 
@@ -309,12 +347,15 @@ export const validateLinks = async (
   options: {
     publicDir: string | null;
     checkExternal?: boolean;
+    /** `content.assets` mounts served alongside `public/`. */
+    assetMounts?: AssetMount[];
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
 ): Promise<Diagnostic[]> => {
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
+    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) => toRoute(redirect.from))

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