blume 1.5.2 → 1.6.0

package/src/core/links.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 
-import { basename, dirname, join } from "pathe";
+import { basename, dirname, join, relative, resolve } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
 import {
@@ -37,6 +37,34 @@ interface LinkSite {
   line: number;
 }
 
+/**
+ * Message context for a link written inside an included partial whose verdict
+ * depends on *which* page splices it (relative paths resolve against the
+ * including page's route; bare anchors against its headings). Without it the
+ * same partial line can be reported broken while being valid from another
+ * includer — with no way to tell the reports apart.
+ */
+const includedBySuffix = (link: PageLink, page: PageRecord): string =>
+  link.file ? ` (included by ${basename(page.sourcePath ?? page.id)})` : "";
+
+/**
+ * Invert the include image rebase for display: expansion rewrote a partial's
+ * relative image target into the including page's directory so it resolves,
+ * but the diagnostic points at the partial — report the path the author
+ * actually wrote there, not the rebased one they never typed.
+ */
+const authoredImageTarget = (
+  target: string,
+  pagePath: string,
+  partialPath: string
+): string => {
+  const authored = relative(
+    dirname(partialPath),
+    resolve(dirname(pagePath), target)
+  );
+  return authored.startsWith(".") ? authored : `./${authored}`;
+};
+
 /** An external link occurrence queued for a network probe. */
 interface ExternalRef extends LinkSite {
   url: string;
@@ -130,7 +158,10 @@ const buildAnchorIndex = (pages: PageRecord[]): Map<string, Set<string>> => {
   for (const page of pages) {
     anchors.set(
       page.route,
-      new Set(page.headings.map((heading) => heading.slug))
+      new Set([
+        ...page.headings.map((heading) => heading.slug),
+        ...page.anchors,
+      ])
     );
   }
   return anchors;
@@ -141,15 +172,19 @@ const checkAnchor = (
   route: string,
   fragment: string,
   site: LinkSite,
-  ctx: LinkContext
+  ctx: LinkContext,
+  via = ""
 ): Diagnostic | null => {
-  if (ctx.anchors.get(route)?.has(fragment.toLowerCase())) {
+  const anchors = ctx.anchors.get(route);
+  // Exact first: a `[#custom-id]` pin may contain uppercase, which the
+  // lowercase fallback (lenient matching for slugger-generated ids) would miss.
+  if (anchors?.has(fragment) || anchors?.has(fragment.toLowerCase())) {
     return null;
   }
   return {
     ...site,
     code: "BLUME_BROKEN_ANCHOR",
-    message: `No heading on ${route} matches anchor #${fragment}.`,
+    message: `No anchor target on ${route} matches #${fragment}${via}.`,
     severity: "warning",
   };
 };
@@ -161,7 +196,8 @@ const checkPathLink = (
   page: PageRecord,
   link: PageLink,
   site: LinkSite,
-  ctx: LinkContext
+  ctx: LinkContext,
+  via = ""
 ): LinkResult => {
   // Page routes carry the site-wide base; an absolute author path is written
   // as if mounted at root, so base it for the route lookup (idempotent — a
@@ -170,7 +206,7 @@ const checkPathLink = (
   // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
   const route = toRoute(withBasePath(ctx.basePath, resolved));
   if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+    return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
   }
   // A custom `.astro` page or generated route serves this path, but its
   // headings aren't indexed — accept any fragment rather than false-flag it.
@@ -203,10 +239,16 @@ const checkPathLink = (
       if (resolveRelativeImage(dirname(page.sourcePath), link.target)) {
         return null;
       }
+      // A partial-origin image was rebased into the page's directory for
+      // resolution but reports against the partial — cite the path as
+      // authored there, so file, path, and "next to" agree.
+      const authored = link.file
+        ? authoredImageTarget(link.target, page.sourcePath, link.file)
+        : link.target;
       return {
         ...site,
         code: "BLUME_BROKEN_ASSET",
-        message: `Image ${link.target} was not found next to ${basename(page.sourcePath)}.`,
+        message: `Image ${authored} was not found next to ${basename(link.file ?? page.sourcePath)}.`,
         severity: "warning",
         suggestion:
           "Add the file next to the page source or fix the reference.",
@@ -228,7 +270,7 @@ const checkPathLink = (
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
-    message: `Broken link to ${link.target}: no page resolves to ${route}.`,
+    message: `Broken link to ${link.target}${via}: no page resolves to ${route}.`,
     severity: "error",
     suggestion: "Check the path, or create the target page.",
   };
@@ -268,7 +310,9 @@ const classifyLink = (
   const { target } = link;
   const site: LinkSite = {
     column: link.column,
-    file: page.sourcePath ?? page.id,
+    // A link written inside an included partial reports against the partial
+    // file, so the author fixes it where it lives.
+    file: link.file ?? page.sourcePath ?? page.id,
     line: link.line,
   };
 
@@ -298,14 +342,19 @@ const classifyLink = (
   }
   rawPath = decodePercent(rawPath);
 
+  // A relative path (or a bare anchor) means something different from every
+  // including page; an absolute path means the same thing everywhere — so
+  // only includer-dependent targets carry the "included by" context, and
+  // identical absolute-target reports collapse in the final dedupe.
+  const via = rawPath.startsWith("/") ? "" : includedBySuffix(link, page);
   if (rawPath === "") {
-    return fragment ? checkAnchor(page.route, fragment, site, ctx) : null;
+    return fragment ? checkAnchor(page.route, fragment, site, ctx, via) : null;
   }
 
   const resolved = rawPath.startsWith("/")
     ? rawPath
     : resolveRelative(page.route, rawPath, isIndexPage(page));
-  return checkPathLink(resolved, fragment, page, link, site, ctx);
+  return checkPathLink(resolved, fragment, page, link, site, ctx, via);
 };
 
 /**
@@ -371,5 +420,22 @@ export const validateLinks = async (
     diagnostics.push(...(await checkExternalLinks(external)));
   }
 
-  return diagnostics;
+  // A partial spliced into several pages (or every locale of one) yields the
+  // same diagnostic once per including page record; byte-identical reports
+  // add noise without information, so only the first of each survives.
+  const seen = new Set<string>();
+  return diagnostics.filter((diagnostic) => {
+    const key = [
+      diagnostic.code,
+      diagnostic.file ?? "",
+      diagnostic.line ?? "",
+      diagnostic.column ?? "",
+      diagnostic.message,
+    ].join("\n");
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
 };

package/src/core/meta.ts

@@ -5,6 +5,7 @@ import { diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
 import { folderMetaSchema } from "./schema.ts";
 import type { FolderMeta } from "./schema.ts";
+import { trimChar } from "./trim.ts";
 import type { Diagnostic } from "./types.ts";
 
 const META_FILES = [
@@ -50,7 +51,7 @@ export interface FolderMetaSource {
  * source keys to `docs/provider`, exactly the group path navigation builds.
  */
 const metaKeyFor = (prefix: string | undefined, dir: string): string => {
-  const clean = prefix ? prefix.replaceAll(/^\/+|\/+$/gu, "") : "";
+  const clean = prefix ? trimChar(prefix, "/") : "";
   if (!clean) {
     return dir;
   }

package/src/core/nav-diagnostics.ts

@@ -1,5 +1,6 @@
 import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
+import { isInternalPath } from "./base-path.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
 
 /**
@@ -120,12 +121,20 @@ export const validateNavTargets = (
       label: link.label,
       path: link.href,
     })),
+    ...(navigation.actions ?? []).map((action) => ({
+      label: action.label,
+      path: action.href,
+    })),
+    ...(navigation.cta
+      ? [{ label: navigation.cta.label, path: navigation.cta.href }]
+      : []),
   ];
   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)) {
+    // Only internal, non-anchor paths can be checked against routes. A
+    // protocol-relative `//host/path` is external despite its leading slash.
+    if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
       continue;
     }
     if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {

package/src/core/navigation.ts

@@ -9,6 +9,7 @@ import type {
 import type {
   Diagnostic,
   FeaturedLink,
+  HeaderAction,
   NavNode,
   Navigation,
   NavSelector,
@@ -788,6 +789,8 @@ const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
  * their exact authored shape.
  */
 interface NavChrome {
+  actions: HeaderAction[];
+  cta: HeaderAction | null;
   featured: FeaturedLink[];
   selectors: NavSelector[];
   tabs: NavTab[];
@@ -796,26 +799,33 @@ interface NavChrome {
 const rebaseNavChrome = (
   basePath: string,
   options: {
+    actions?: HeaderAction[];
+    cta?: HeaderAction | null;
     featured?: FeaturedLink[];
     selectors?: NavSelector[];
     tabs?: NavTab[];
   }
 ): NavChrome => {
+  const actions = options.actions ?? [];
+  const cta = options.cta ?? null;
   const featured = options.featured ?? [];
   const selectors = options.selectors ?? [];
   const tabs = options.tabs ?? [];
   if (!basePath) {
-    return { featured, selectors, tabs };
+    return { actions, cta, featured, selectors, tabs };
   }
+  const rebaseHref = <T extends { href: string }>(item: T): T => ({
+    ...item,
+    href: withBasePath(basePath, item.href),
+  });
   const rebasePath = <T extends { path: string }>(item: T): T => ({
     ...item,
     path: withBasePath(basePath, item.path),
   });
   return {
-    featured: featured.map((link) => ({
-      ...link,
-      href: withBasePath(basePath, link.href),
-    })),
+    actions: actions.map(rebaseHref),
+    cta: cta ? rebaseHref(cta) : null,
+    featured: featured.map(rebaseHref),
     selectors: selectors.map((selector) => ({
       ...selector,
       items: selector.items.map(rebasePath),
@@ -838,8 +848,12 @@ const rebaseNavChrome = (
 export const buildNavigation = (
   pages: PageRecord[],
   options: {
+    /** Plain links in the header, left of the icon buttons. */
+    actions?: HeaderAction[];
     /** Site-wide route mount point (`""` or `/seg`); applied to config paths. */
     basePath?: string;
+    /** The single primary call to action in the header. */
+    cta?: HeaderAction | null;
     folderMeta: Map<string, FolderMeta>;
     /** Global display mode for every sidebar group (default `flat`). */
     display?: SidebarDisplay;
@@ -891,7 +905,10 @@ export const buildNavigation = (
   // Content-derived sidebar routes are already based via `page.route`; the
   // based tab paths also feed tab-scoping below, so they must agree with the
   // based content routes.
-  const { featured, selectors, tabs } = rebaseNavChrome(basePath, options);
+  const { actions, cta, featured, selectors, tabs } = rebaseNavChrome(
+    basePath,
+    options
+  );
   const byRoute = new Map(
     pages.map((page) => [
       options.refByLogical ? page.translationKey : page.route,
@@ -939,6 +956,8 @@ export const buildNavigation = (
       basePath
     );
     return {
+      actions,
+      cta,
       featured,
       root: rootTabPath,
       selectors,
@@ -960,6 +979,8 @@ export const buildNavigation = (
     diagnostics
   );
   return {
+    actions,
+    cta,
     featured,
     root: rootTabPath,
     selectors,

package/src/core/project-graph.ts

@@ -1,11 +1,13 @@
-import { relative } from "pathe";
+import { isAbsolute, relative } from "pathe";
 
 import { loadConfig } from "./config.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
+import { expandIncludes, hasIncludeStatements } from "./includes.ts";
 import {
   gitLastModifiedTimes,
+  gitRepositoryRoot,
   lastModifiedShallowWarning,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
@@ -14,7 +16,7 @@ import { discoverFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
 import type { ResolvedConfig } from "./schema.ts";
-import { normalizeEntry } from "./sources/normalize.ts";
+import { normalizeEntry, strippedLineOffset } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
 import type { ContentSource, SourceLoadResult } from "./sources/types.ts";
 import type {
@@ -42,6 +44,15 @@ export interface ConfigOverrides {
   output?: ResolvedConfig["deployment"]["output"];
 }
 
+/**
+ * Whether `path` sits at or under `dir`. A relative result that is itself
+ * absolute means a different drive root on Windows, which is outside too.
+ */
+export const isWithin = (dir: string, path: string): boolean => {
+  const rel = relative(dir, path);
+  return !(rel.startsWith("..") || isAbsolute(rel));
+};
+
 /** Apply CLI config overrides onto a resolved config (returns a new object). */
 const applyConfigOverrides = (
   config: ResolvedConfig,
@@ -268,6 +279,32 @@ export const scanProject = async (
     }),
   ]);
 
+  // Expand `<include>` statements before normalization, so heading/link/
+  // component extraction sees the spliced content every render surface shows.
+  // Filesystem entries only: includes resolve as filesystem paths bounded by
+  // the owning source's content root. Unresolvable statements stay verbatim
+  // and surface as error diagnostics here.
+  const includeDiagnostics: Diagnostic[] = [];
+  await Promise.all(
+    loaded.flatMap(({ source, entries }) => {
+      if (source.staged || !source.contentRoot) {
+        return [];
+      }
+      return entries.map(async (entry) => {
+        if (!entry.sourcePath || !hasIncludeStatements(entry.body.text)) {
+          return;
+        }
+        const expansion = await expandIncludes(entry.body.text, {
+          contentRoot: source.contentRoot,
+          lineOffset: strippedLineOffset(entry.raw, entry.body.text),
+          sourcePath: entry.sourcePath,
+        });
+        entry.expanded = expansion;
+        includeDiagnostics.push(...expansion.errors);
+      });
+    })
+  );
+
   // Folder meta contributed by the sources themselves (the OpenAPI source
   // labels each tag directory with the spec's own tag name). It applies to
   // every locale, so it merges into the shared map — beneath user-authored
@@ -300,13 +337,21 @@ export const scanProject = async (
     const fsPaths = pages
       .map((page) => page.sourcePath)
       .filter((path): path is string => path !== undefined);
-    // The git pathspecs must cover where the pages actually live: each
-    // filesystem source's own root, which diverges from the global
-    // `content.root` when a source configures a non-default `root`.
-    const contentRoots = sources.flatMap((source) =>
-      source.staged || !source.contentRoot ? [] : [source.contentRoot]
+    // The git pathspecs must cover where the pages actually live: each local
+    // source's own on-disk root — a filesystem source's `root`, or a staged
+    // local source's tree (an Obsidian vault) — which diverges from the global
+    // `content.root`. A root outside the repository would fail the log outright
+    // and can never yield dates, so those are dropped up front.
+    const gitRoot = gitRepositoryRoot(context.root);
+    const contentRoots = sources
+      .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
+      .filter((dir) => gitRoot !== null && isWithin(gitRoot, dir));
+    const gitTimes = gitLastModifiedTimes(
+      context.root,
+      contentRoots,
+      fsPaths,
+      gitRoot
     );
-    const gitTimes = gitLastModifiedTimes(context.root, contentRoots, fsPaths);
     for (const page of pages) {
       if (!page.lastModified && page.sourcePath) {
         page.lastModified = gitTimes.get(page.sourcePath);
@@ -314,8 +359,14 @@ export const scanProject = async (
     }
     // A shallow CI clone (Vercel, actions/checkout) silently drops most dates;
     // surface that instead of letting production diverge from local builds.
+    // Only pages the log could have dated count — a page outside every covered
+    // root stays undated no matter how deep the clone is, and the warning's
+    // suggested fix cannot help it.
     const undated = pages.filter(
-      (page) => page.sourcePath && !page.lastModified
+      (page) =>
+        page.sourcePath &&
+        !page.lastModified &&
+        contentRoots.some((dir) => isWithin(dir, page.sourcePath ?? ""))
     ).length;
     lastModifiedWarnings.push(
       ...lastModifiedShallowWarning(context.root, undated)
@@ -344,6 +395,7 @@ export const scanProject = async (
     context,
     diagnostics: [
       ...contentDiagnostics,
+      ...includeDiagnostics,
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
       ...graph.diagnostics,