blume 2.0.3 → 2.1.1

package/src/core/page-modes.ts

@@ -0,0 +1,56 @@
+/**
+ * Page layout modes (`mode` frontmatter), Mintlify's names for what a page
+ * shows around its content:
+ *
+ * - `default`: the sidebar, the page's title and table of contents, and the
+ *   page-end links, around the prose column.
+ * - `wide`: no table of contents; the content takes its width.
+ * - `center`: no sidebar or table of contents; a wider column, centered.
+ *   For changelogs and other pages read top to bottom.
+ * - `custom`: only the header. No sidebar, title, breadcrumbs, table of
+ *   contents, page-end links, or site footer, and the content spans the
+ *   page, for a landing page written in MDX.
+ * - `frame`: `custom`, keeping the sidebar.
+ *
+ * Mintlify's `assistant` mode, a full-page chat, has no equivalent.
+ */
+export const PAGE_MODES = [
+  "default",
+  "wide",
+  "center",
+  "custom",
+  "frame",
+] as const;
+
+export type PageMode = (typeof PAGE_MODES)[number];
+
+/** What a page shows around its content, and how wide the content runs. */
+export interface PageModeLayout {
+  /** The page's own chrome: title, description, breadcrumbs, page-end links, and the site footer. */
+  chrome: boolean;
+  sidebar: boolean;
+  toc: boolean;
+  /** `content` is the prose measure, `center` a wider centered column, `full` the whole column. */
+  width: "content" | "center" | "full";
+}
+
+/** The layout a mode gives a page. */
+export const pageModeLayout = (mode: PageMode = "default"): PageModeLayout => {
+  switch (mode) {
+    case "wide": {
+      return { chrome: true, sidebar: true, toc: false, width: "full" };
+    }
+    case "center": {
+      return { chrome: true, sidebar: false, toc: false, width: "center" };
+    }
+    case "custom": {
+      return { chrome: false, sidebar: false, toc: false, width: "full" };
+    }
+    case "frame": {
+      return { chrome: false, sidebar: true, toc: false, width: "full" };
+    }
+    default: {
+      return { chrome: true, sidebar: true, toc: true, width: "content" };
+    }
+  }
+};

package/src/core/probe.ts

@@ -16,6 +16,8 @@ export interface ProbeResult {
   status?: number;
   timedOut?: boolean;
   error?: string;
+  /** The system error code behind a request that got no response (`ENOTFOUND`). */
+  code?: string;
   /** Whether the request was redirected before landing on `status`. */
   redirected?: boolean;
   /** The URL finally landed on, after following redirects. */
@@ -28,6 +30,18 @@ export interface ProbeResult {
   robotsTag?: string | null;
 }
 
+/**
+ * The reason a request got no response. Node's fetch rejects with a bare
+ * "fetch failed" and puts the system error (`getaddrinfo ENOTFOUND …`, with
+ * its `code`) on `cause`; Bun's rejects with the system error itself.
+ */
+const failure = (error: Error): Pick<ProbeResult, "code" | "error"> => {
+  const reason = error.cause instanceof Error ? error.cause : error;
+  return "code" in reason
+    ? { code: String(reason.code), error: reason.message }
+    : { error: reason.message };
+};
+
 /** Probe a URL with the given method, normalizing failures to a result. */
 const request = async (
   url: string,
@@ -56,10 +70,9 @@ const request = async (
     if (error instanceof Error && error.name === "AbortError") {
       return { ok: false, timedOut: true };
     }
-    return {
-      error: error instanceof Error ? error.message : String(error),
-      ok: false,
-    };
+    const reason =
+      error instanceof Error ? failure(error) : { error: String(error) };
+    return { ...reason, ok: false };
   } finally {
     clearTimeout(timer);
   }
@@ -95,10 +108,17 @@ export const gradeExternal = (
   if (result.timedOut) {
     return { detail: "request timed out", severity: "warning" };
   }
+  // No response at all. A host name that doesn't resolve is as dead as a 404;
+  // a refused, reset, or failed connection is more often someone else's outage
+  // or the runner's own network, so it's graded like a timeout.
   if (result.status === undefined) {
-    return { detail: result.error ?? "unreachable", severity: "error" };
+    return {
+      detail: result.error ?? "unreachable",
+      severity: result.code === "ENOTFOUND" ? "error" : "warning",
+    };
   }
-  // A 404/410 is definitively dead. A 403/429/5xx may well be rate limiting or a
+  // A 404/410 is definitively dead. Any other status — a 401/403 from a site
+  // that turns bots away, a 429, a 5xx — may well be rate limiting or a
   // transient blip, which is not the author's bug to fix.
   if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
     return { detail: `HTTP ${result.status}`, severity: "error" };

package/src/core/project-graph.ts

@@ -1,5 +1,6 @@
 import { isAbsolute, relative } from "pathe";
 
+import { normalizePath, withBasePath } from "./base-path.ts";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
@@ -18,10 +19,16 @@ import { buildManifest } from "./manifest.ts";
 import { discoverFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
+import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
 import type { ResolvedConfig } from "./schema.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 { SourceRuntime } from "./sources/resolve.ts";
+import type {
+  ContentSource,
+  SourceEntry,
+  SourceLoadResult,
+} from "./sources/types.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -30,6 +37,12 @@ import type {
   PageRecord,
   ProjectContext,
 } from "./types.ts";
+import {
+  hasVariables,
+  substituteVariables,
+  undefinedVariables,
+} from "./variables.ts";
+import type { ContentVariables } from "./variables.ts";
 import { versionsDiagnostics } from "./versions.ts";
 
 /** Build mode: drafts are kept in `dev` and dropped in `build`. */
@@ -246,6 +259,104 @@ const isBannerShorthand = (
   banner: NonNullable<ResolvedConfig["banner"]>
 ): banner is string => typeof banner === "string";
 
+/**
+ * Report an entry's undefined content variables at their source lines, then
+ * replace the defined ones in the text the scan extracts from: the expanded
+ * text when includes were spliced (its `origins` map lines back to the file
+ * each came from), else the body.
+ */
+const substituteEntryVariables = (
+  entry: SourceEntry,
+  variables: ContentVariables
+): Diagnostic[] => {
+  const { expanded } = entry;
+  const text = expanded?.text ?? entry.body.text;
+  const offset = expanded ? 0 : strippedLineOffset(entry.raw, entry.body.text);
+  const diagnostics = undefinedVariables(text, variables).map(
+    ({ line, name }): Diagnostic => {
+      const origin = expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNDEFINED_VARIABLE",
+        file: origin?.file ?? entry.sourcePath,
+        line: origin?.line ?? line + offset,
+        message: `{{${name}}} isn't a defined variable, so it would show as written.`,
+        severity: "error",
+        suggestion: `Define "${name}" under variables in blume.config.ts, or put it in inline code to show it as written.`,
+      };
+    }
+  );
+  if (expanded) {
+    expanded.text = substituteVariables(expanded.text, variables);
+  } else {
+    entry.body.text = substituteVariables(entry.body.text, variables);
+  }
+  return diagnostics;
+};
+
+/** {@link substituteEntryVariables} over every loaded entry, when any are defined. */
+const substituteLoadedVariables = (
+  loaded: readonly SourceLoadResult[],
+  variables: ContentVariables
+): Diagnostic[] =>
+  hasVariables(variables)
+    ? loaded.flatMap(({ entries }) =>
+        entries.flatMap((entry) => substituteEntryVariables(entry, variables))
+      )
+    : [];
+
+/**
+ * A pattern redirect that also matches a page. Hosts disagree on which
+ * answers (Vercel and Cloudflare apply the rule ahead of the page, Netlify
+ * and the Node server serve the page), so the pattern is rejected rather than
+ * let the answer depend on the host. `pages` are the served page paths, which
+ * carry `basePath`, as the based `from` does.
+ *
+ * An exact redirect from a page's own URL answers the same way everywhere:
+ * Astro ranks its route above the page's catch-all, in dev and build alike,
+ * and writes the redirect page where the page would go, so the page never
+ * publishes. That's a warning rather than an error, since the outcome doesn't
+ * depend on the host.
+ */
+const redirectPageDiagnostics = (
+  config: ResolvedConfig,
+  pages: readonly string[],
+  configFile: string | null
+): Diagnostic[] =>
+  config.redirects.flatMap((redirect): Diagnostic[] => {
+    const from = withBasePath(config.basePath, redirect.from);
+    if (!isPatternPath(redirect.from)) {
+      const page = normalizePath(from);
+      return pages.includes(page)
+        ? [
+            {
+              code: "BLUME_REDIRECT_MATCHES_PAGE",
+              file: configFile ?? undefined,
+              message: `The redirect from ${redirect.from} is also the page ${page}, which never publishes: its URL redirects to ${redirect.to} instead.`,
+              severity: "warning",
+              suggestion:
+                "If the page moved, delete it or give it a new slug; otherwise remove the redirect.",
+            } satisfies Diagnostic,
+          ]
+        : [];
+    }
+    const matched = pathsUnderPattern(from, pages);
+    const [first] = matched;
+    if (first === undefined) {
+      return [];
+    }
+    const more = matched.length > 1 ? ` and ${matched.length - 1} more` : "";
+    return [
+      {
+        code: "BLUME_REDIRECT_MATCHES_PAGE",
+        file: configFile ?? undefined,
+        message: `The redirect from ${redirect.from} also matches the page ${first}${more}, which some hosts would redirect and others would serve.`,
+        severity: "error",
+        suggestion:
+          "Narrow the pattern to the paths that moved, or move the pages out from under it.",
+      } satisfies Diagnostic,
+    ];
+  });
+
 /** The configured banner link target, when the banner has a link. */
 const bannerLinkHref = (
   banner: ResolvedConfig["banner"]
@@ -254,6 +365,26 @@ const bannerLinkHref = (
     ? undefined
     : banner.link?.href;
 
+/**
+ * The project's sources, before any of them loads: `beforeSources` sees the
+ * config first, then each source validates itself (e.g. the filesystem
+ * source checks its root exists), replacing the single hard `contentRoot`
+ * check.
+ */
+const validatedSources = (
+  config: ResolvedConfig,
+  context: ProjectContext,
+  runtime: SourceRuntime,
+  beforeSources?: (config: ResolvedConfig) => void
+): ContentSource[] => {
+  beforeSources?.(config);
+  const sources = resolveSources(config, context, runtime);
+  for (const source of sources) {
+    source.validate?.();
+  }
+  return sources;
+};
+
 export const scanProject = async (
   root: string,
   options: {
@@ -265,6 +396,12 @@ export const scanProject = async (
     overrides?: ConfigOverrides;
     /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
     runtimeDir?: string;
+    /**
+     * Called with the resolved config before any source loads, so a command
+     * can report an unset secret ahead of a fetch that fails without it: a
+     * source that can't load fails the scan, and nothing after it runs.
+     */
+    beforeSources?: (config: ResolvedConfig) => void;
   } = {}
 ): Promise<BlumeProject> => {
   const mode = options.mode ?? "dev";
@@ -276,17 +413,12 @@ export const scanProject = async (
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
-
-  // Each source validates itself (e.g. the filesystem source checks its root
-  // exists), replacing the single hard `contentRoot` check.
-  const sources = resolveSources(config, context, {
-    mode,
-    preview,
-    refresh: options.refresh,
-  });
-  for (const source of sources) {
-    source.validate?.();
-  }
+  const sources = validatedSources(
+    config,
+    context,
+    { mode, preview, refresh: options.refresh },
+    options.beforeSources
+  );
 
   // Folder meta is discovered per filesystem source, under each source's own
   // root and keyed by its route prefix, so a prefixed/root-differing source's
@@ -352,6 +484,14 @@ export const scanProject = async (
     })
   );
 
+  // Content variables: an undefined name in prose is an error at its source
+  // line, and every defined one is replaced in the text headings, links, and
+  // components are extracted from, so they match the rendered page.
+  const variableDiagnostics = substituteLoadedVariables(
+    loaded,
+    config.variables
+  );
+
   // 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
@@ -424,14 +564,15 @@ export const scanProject = async (
   const customPages = context.pagesRoot
     ? await discoverPages(context.pagesRoot)
     : [];
+  const extraRoutes = new Set([
+    ...customStaticRoutes(customPages),
+    ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
+  ]);
   const graph = buildContentGraph(pages, {
     bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
-    extraRoutes: new Set([
-      ...customStaticRoutes(customPages),
-      ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
-    ]),
+    extraRoutes,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -453,6 +594,7 @@ export const scanProject = async (
     diagnostics: [
       ...contentDiagnostics,
       ...includeDiagnostics,
+      ...variableDiagnostics,
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(
         pages,
@@ -462,6 +604,11 @@ export const scanProject = async (
       ...i18nWarnings,
       ...versionWarnings,
       ...lastModifiedWarnings,
+      ...redirectPageDiagnostics(
+        config,
+        [...manifest.routes.map((route) => route.path), ...extraRoutes],
+        context.configFile
+      ),
     ],
     droppedPages,
     graph,