blume 2.1.3 → 2.2.1

package/src/audit/run.ts

@@ -8,7 +8,6 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { deployStaticDir } from "../deploy/adapter-output.ts";
 import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
-import { CHECKS } from "./catalog.ts";
 import type { CheckId } from "./catalog.ts";
 import { assetChecks } from "./checks/assets.ts";
 import { contentChecks } from "./checks/content.ts";
@@ -32,7 +31,7 @@ import {
 import { crawlStaticDir } from "./crawl.ts";
 import { buildGraph } from "./graph.ts";
 import { resolveRedirects } from "./redirects.ts";
-import { shortId } from "./terms.ts";
+import { checkSelected } from "./terms.ts";
 import { DEFAULT_THRESHOLDS } from "./types.ts";
 import type {
   AuditContext,
@@ -84,6 +83,10 @@ export interface AuditResult {
   origin: string | null;
   /** Which tiers actually ran. A skipped tier is reported, never hidden. */
   tiers: Record<AuditTier, boolean>;
+  /** The `--only` terms the findings were filtered to, if any. */
+  only?: string[];
+  /** The `--skip` terms the findings were filtered by, if any. */
+  skip?: string[];
 }
 
 /** Thrown when there's no build to audit. */
@@ -123,18 +126,6 @@ const readSources = async (
   return new Map(entries.filter((entry) => entry !== null));
 };
 
-/** Does a check id or its category match one of the user's `--only`/`--skip` terms? */
-const matches = (id: CheckId, terms: string[]): boolean => {
-  const meta = CHECKS.find((check) => check.id === id);
-  const short = shortId(id);
-  return terms.some((raw) => {
-    const term = raw.trim().toLowerCase();
-    return (
-      term === short || term === id.toLowerCase() || term === meta?.category
-    );
-  });
-};
-
 /** Audit a built site. */
 export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
   const { project } = options;
@@ -203,25 +194,18 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
     )
   );
 
-  let diagnostics = results.flat();
-  if (options.only?.length) {
-    // SAFETY: audit diagnostics are created through `finding()`, whose codes
-    // all come from the check catalog's `CheckId` set.
-    diagnostics = diagnostics.filter((d) =>
-      matches(d.code as CheckId, options.only ?? [])
-    );
-  }
-  if (options.skip?.length) {
-    // SAFETY: same invariant — every audit diagnostic code is a catalog `CheckId`.
-    diagnostics = diagnostics.filter(
-      (d) => !matches(d.code as CheckId, options.skip ?? [])
-    );
-  }
+  // SAFETY: audit diagnostics are created through `finding()`, whose codes
+  // all come from the check catalog's `CheckId` set.
+  const diagnostics = results
+    .flat()
+    .filter((d) => checkSelected(d.code as CheckId, options));
 
   return {
     diagnostics,
+    only: options.only,
     origin,
     pages: crawl.pages.length,
+    skip: options.skip,
     staticDir,
     tiers,
   };

package/src/audit/terms.ts

@@ -5,6 +5,29 @@ import type { CheckId } from "./catalog.ts";
 export const shortId = (id: CheckId): string =>
   id.replace("BLUME_AUDIT_", "").toLowerCase();
 
+/** Does a check id or its category match one of the user's `--only`/`--skip` terms? */
+const matchesTerms = (id: CheckId, terms: readonly string[]): boolean => {
+  const meta = CHECKS.find((check) => check.id === id);
+  const short = shortId(id);
+  return terms.some((raw) => {
+    const term = raw.trim().toLowerCase();
+    return (
+      term === short || term === id.toLowerCase() || term === meta?.category
+    );
+  });
+};
+
+/**
+ * Whether `--only` and `--skip` leave a check in: it matches an `--only`
+ * term, when any are given, and no `--skip` term.
+ */
+export const checkSelected = (
+  id: CheckId,
+  filter: { only?: readonly string[]; skip?: readonly string[] }
+): boolean =>
+  (!filter.only?.length || matchesTerms(id, filter.only)) &&
+  !matchesTerms(id, filter.skip ?? []);
+
 /**
  * Every term `--only`/`--skip` accept, as the audit's filter compares them:
  * each check's short id and each category. The full `BLUME_AUDIT_…` id is

package/src/audit/url.ts

@@ -158,8 +158,8 @@ export const resolveHref = (
   // A relative href resolves the way a browser resolves it from the page's
   // canonical URL. `URL` needs an origin to do that, so borrow a placeholder
   // one and keep only the path. The canonical URL is slashless — the generated
-  // config sets `trailingSlash: "never"`, Vercel redirects `/docs/api/` onto
-  // `/docs/api`, and the dev server 404s the slashed form — so `./auth` there
+  // config sets `trailingSlash: "never"`, and Vercel and the dev server
+  // redirect `/docs/api/` onto `/docs/api` — so `./auth` there
   // means `/docs/auth`, exactly where a reader's click lands. Content links
   // never hit this: the Markdown pipeline rewrites them root-relative (see
   // `resolveRelativeHref`); what's left is hand-written HTML, which a browser

package/src/cli/build-failure.ts

@@ -1,5 +1,12 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { basename, dirname, isAbsolute, join, relative, resolve } from "pathe";
+import ts from "typescript";
 import { z } from "zod";
 
+import { locateMdxFailure } from "../core/mdx-syntax.ts";
+import type { MdxFailure, MdxFailureSite } from "../core/mdx-syntax.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
 
 /**
@@ -39,22 +46,231 @@ const blumeErrorSchema = z.looseObject({
   }),
 });
 
+/**
+ * Finds where in an `.mdx` page's files a failure Astro reported with no line
+ * happened (see `locateMdxFailure`).
+ */
+export type MdxFailureLocator = (
+  file: string,
+  failure: MdxFailure
+) => Promise<MdxFailureSite | null>;
+
+/** What the report reads besides the error. */
+export interface BuildFailureContext {
+  locate?: MdxFailureLocator;
+  /** The project root, where the build reads `tsconfig.json`. */
+  root?: string;
+}
+
+// The message for a name nothing defines, in V8 (Node) and JavaScriptCore (Bun).
+const UNDEFINED_NAME = [
+  /^(?<name>[\w$]+) is not defined$/u,
+  /^Can't find variable: (?<name>[\w$]+)$/u,
+];
+// A compiler message that opens with where it failed.
+const POSITIONED = /^\d+:\d+: /u;
+
+/**
+ * A `{…}` expression in an `.mdx` page that reads a name nothing defines: the
+ * page compiles, then throws while it renders. Placed at the expression when
+ * the page (or a partial it includes) shows where.
+ */
+const undefinedNameDiagnostic = (
+  name: string,
+  file: string,
+  site: MdxFailureSite | null
+): Diagnostic => {
+  const escape =
+    "show the braces as text: escape each opening brace (`\\{`) or put it in inline code";
+  // `{{name}}` is a Blume variable the site doesn't define.
+  const variable = site?.expression === `{{${name}}}`;
+  return {
+    code: "BLUME_MDX_UNDEFINED_NAME",
+    column: site?.column,
+    file: site?.file ?? file,
+    line: site?.line,
+    message: site?.expression
+      ? `\`${site.expression}\` reads \`${name}\`, which isn't defined, so the page fails to render. In .mdx, \`{…}\` is a JavaScript expression.`
+      : `\`${name}\` isn't defined, so the page fails to render. In .mdx, \`{…}\` is a JavaScript expression, and one reads it.`,
+    severity: "error",
+    suggestion: variable
+      ? `Define \`${name}\` under \`variables\` in blume.config.ts, or ${escape}.`
+      : `To ${escape}. For a value every page shares, define a variable in blume.config.ts and write \`{{name}}\`.`,
+  };
+};
+
+// Vite's message for an `extends` or `references` entry it can't resolve. It
+// names an `extends` package as written, and a path resolved.
+const TSCONFIG_NOT_FOUND = /Tsconfig not found (?<target>\S+?)\.?$/mu;
+
+const tsconfigLinksSchema = z.object({
+  extends: z.union([z.string(), z.array(z.string())]).optional(),
+  references: z.array(z.object({ path: z.string() })).optional(),
+});
+
+/** An entry in a tsconfig's `extends` or `references`, as written. */
+interface TsconfigLink {
+  key: "extends" | "references";
+  written: string;
+}
+
+/**
+ * The `extends` or `references` entry in the tsconfig at `path` that names
+ * `target`: written as is, or resolved from the tsconfig's folder (a
+ * reference can name a folder, which means its `tsconfig.json`).
+ */
+const linkTo = (path: string, target: string): TsconfigLink | undefined => {
+  const parsed = tsconfigLinksSchema.safeParse(
+    ts.readConfigFile(path, ts.sys.readFile).config
+  );
+  if (!parsed.success) {
+    return undefined;
+  }
+  const names = (written: string): boolean => {
+    const resolved = resolve(dirname(path), written);
+    return (
+      written === target ||
+      resolved === target ||
+      join(resolved, "tsconfig.json") === target
+    );
+  };
+  const extended = [parsed.data.extends ?? []].flat().find(names);
+  if (extended !== undefined) {
+    return { key: "extends", written: extended };
+  }
+  const referenced = (parsed.data.references ?? [])
+    .map((reference) => reference.path)
+    .find(names);
+  return referenced === undefined
+    ? undefined
+    : { key: "references", written: referenced };
+};
+
+/** How to fix a tsconfig entry that doesn't resolve. */
+const tsconfigFix = ({ key, written }: TsconfigLink, name: string): string => {
+  if (key === "references") {
+    return `Create \`${written}\` (a framework's generated tsconfig appears once its prepare or build step runs), or remove it from \`references\` in ${name}.`;
+  }
+  if (written.startsWith(".") || isAbsolute(written)) {
+    return `Restore \`${written}\`, or remove it from \`extends\` in ${name}.`;
+  }
+  const packageName = written
+    .split("/")
+    .slice(0, written.startsWith("@") ? 2 : 1)
+    .join("/");
+  return `Install the package that provides it (\`${packageName}\`), or remove it from \`extends\` in ${name}.`;
+};
+
+/**
+ * An `extends` or `references` entry in the project's `tsconfig.json` that
+ * doesn't resolve: Vite reads that file while it builds the site, so the
+ * build fails in `astro sync` before any page compiles. Placed at the entry's
+ * line when the project's own tsconfig names the target.
+ */
+const tsconfigExtendsDiagnostic = (
+  target: string,
+  root: string | undefined
+): Diagnostic => {
+  const found = root
+    ? ["tsconfig.json", "jsconfig.json"]
+        .map((name) => join(root, name))
+        .filter((path) => existsSync(path))
+        .map((path) => ({ link: linkTo(path, target), path }))
+        .find(({ link }) => link !== undefined)
+    : undefined;
+  const file = found?.path;
+  const { key, written } = found?.link ?? { key: "extends", written: target };
+  const line = file
+    ? readFileSync(file, "utf-8")
+        .split("\n")
+        .findIndex((text) => text.includes(JSON.stringify(written))) + 1
+    : 0;
+  const name = file ? basename(file) : "tsconfig.json";
+  return {
+    code: "BLUME_TSCONFIG_EXTENDS",
+    file,
+    line: line > 0 ? line : undefined,
+    message: `${file ? name : "A tsconfig.json in the project"} ${key} \`${written}\`, which can't be found. The build reads the project's ${name} to resolve imports, so it stops here.`,
+    severity: "error",
+    suggestion: tsconfigFix({ key, written }, name),
+  };
+};
+
+/** The `extends` target an unresolvable tsconfig names, if `error` is that. */
+const missingTsconfig = (error: Error): string | undefined =>
+  (
+    TSCONFIG_NOT_FOUND.exec(error.message) ??
+    // `astro sync` wraps the resolver's error in its own.
+    (error.cause instanceof Error
+      ? TSCONFIG_NOT_FOUND.exec(error.cause.message)
+      : null)
+  )?.groups?.target;
+
+/** The name a render error says nothing defines, if it says that. */
+const undefinedName = (error: Error): string | undefined =>
+  error.name === "ReferenceError"
+    ? UNDEFINED_NAME.map((pattern) => pattern.exec(error.message)).find(Boolean)
+        ?.groups?.name
+    : undefined;
+
+/**
+ * Where in an `.mdx` page's files a failure the compiler didn't place
+ * happened: a render error the page threw, or a compile error in a partial it
+ * includes, which the compiler pins on the page with no `line:column:` in its
+ * message. (Bun stamps a `line` of its own on every error, so `loc` can't
+ * tell.)
+ */
+const locateFailure = async (
+  error: Error,
+  page: string,
+  name: string | undefined,
+  locate: MdxFailureLocator | undefined
+): Promise<MdxFailureSite | null> => {
+  if (!locate) {
+    return null;
+  }
+  if (name) {
+    return await locate(page, { kind: "undefined-name", name });
+  }
+  return error.name === "MDXError" && !POSITIONED.test(error.message)
+    ? await locate(page, { kind: "syntax" })
+    : null;
+};
+
 /** One failure as a diagnostic at the file (and position) it names. */
-const failureDiagnostic = (error: Error): Diagnostic => {
+const failureDiagnostic = async (
+  error: Error,
+  context: BuildFailureContext
+): Promise<Diagnostic> => {
   const raised = blumeErrorSchema.safeParse(error);
   if (raised.success) {
     return raised.data.diagnostic;
   }
+  const tsconfig = missingTsconfig(error);
+  if (tsconfig) {
+    return tsconfigExtendsDiagnostic(tsconfig, context.root);
+  }
   const parsed = buildErrorSchema.safeParse(error);
   const { id, loc } = parsed.success ? parsed.data : {};
+  const file = loc?.file ?? id;
+  const name = undefinedName(error);
+  const site = file?.endsWith(".mdx")
+    ? await locateFailure(error, file, name, context.locate)
+    : null;
+  if (file?.endsWith(".mdx") && name) {
+    return undefinedNameDiagnostic(name, file, site);
+  }
+  if (site?.diagnostic) {
+    return site.diagnostic;
+  }
   // A named error (`MDXError`, `CompilerError`) says which step failed.
-  const name = error.name === "Error" ? "" : `${error.name}: `;
+  const label = error.name === "Error" ? "" : `${error.name}: `;
   return {
     code: "BLUME_BUILD_FAILED",
     column: loc?.column,
-    file: loc?.file ?? id,
+    file,
     line: loc?.line,
-    message: `${name}${error.message}`,
+    message: `${label}${error.message}`,
     severity: "error",
   };
 };
@@ -66,8 +282,41 @@ const failureDiagnostic = (error: Error): Diagnostic => {
  * is a problem in the site, reported at its file, rather than an internal
  * error blaming Blume.
  */
-export const astroBuildDiagnostics = (error: Error): Diagnostic[] => {
-  const parsed = buildErrorSchema.safeParse(error);
+export const astroBuildDiagnostics = async (
+  rejection: Error,
+  context: BuildFailureContext = {}
+): Promise<Diagnostic[]> => {
+  const parsed = buildErrorSchema.safeParse(rejection);
   const failures = parsed.success ? (parsed.data.errors ?? []) : [];
-  return (failures.length > 0 ? failures : [error]).map(failureDiagnostic);
+  return await Promise.all(
+    (failures.length > 0 ? failures : [rejection]).map(
+      async (failure) => await failureDiagnostic(failure, context)
+    )
+  );
 };
+
+/**
+ * The locator a build uses: the failing page's source, read with the includes
+ * and variables the scan resolved for it.
+ */
+export const buildFailureLocator =
+  (
+    project: Pick<BlumeProject, "config" | "context" | "graph" | "sources">
+  ): MdxFailureLocator =>
+  (file, failure) => {
+    const page = project.graph.pages.find(
+      (candidate) => candidate.sourcePath === file
+    );
+    const source = project.sources.find(
+      (candidate) => candidate.name === page?.source.name
+    );
+    return locateMdxFailure(
+      {
+        contentRoot: source?.staged ? undefined : source?.contentRoot,
+        name: relative(project.context.root, file),
+        sourcePath: file,
+        variables: project.config.variables,
+      },
+      failure
+    );
+  };

package/src/cli/command-meta.ts

@@ -55,7 +55,7 @@ export const commandMeta = {
   },
   migrate: {
     description:
-      "Migrate a docs site from Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra with a coding agent.",
+      "Migrate a docs site from Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, or another framework with a coding agent.",
     name: "migrate",
   },
   preview: {

package/src/cli/commands/audit.ts

@@ -12,6 +12,7 @@ import { NoBuildError, runAudit } from "../../audit/run.ts";
 import type { AuditResult } from "../../audit/run.ts";
 import { checkTerms, unknownCheckTerms } from "../../audit/terms.ts";
 import { isHttpUrl } from "../../audit/url.ts";
+import { closestMatch } from "../../core/closest-match.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
@@ -19,7 +20,6 @@ import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
-import { closestMatch } from "../unknown-flags.ts";
 
 const SEVERITIES: DiagnosticSeverity[] = ["error", "warning", "info"];
 

package/src/cli/commands/build.ts

@@ -22,7 +22,10 @@ import {
   removedBuildFlags,
   removedBuildFlagsAdvice,
 } from "../../upgrade/upgrade.ts";
-import { astroBuildDiagnostics } from "../build-failure.ts";
+import {
+  astroBuildDiagnostics,
+  buildFailureLocator,
+} from "../build-failure.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { refuseIfEjected } from "../eject-scripts.ts";
@@ -248,7 +251,7 @@ const reportBuild = async (
   // count next to the success banner so it can't scroll away unseen.
   if (project.droppedPages > 0) {
     logger.warn(
-      `${project.droppedPages} page(s) failed frontmatter validation and are missing from this build.`
+      `${project.droppedPages} page(s) failed validation and are missing from this build.`
     );
   }
   logger.success(`Built to ${distDir}`);
@@ -348,7 +351,13 @@ export const buildCommand = defineCommand({
       if (error instanceof BlumeError || !(error instanceof Error)) {
         throw error;
       }
-      reportDiagnostics(astroBuildDiagnostics(error), root);
+      reportDiagnostics(
+        await astroBuildDiagnostics(error, {
+          locate: buildFailureLocator(project),
+          root,
+        }),
+        root
+      );
       process.exit(1);
     }
 

package/src/cli/commands/check.ts

@@ -6,10 +6,11 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { ensureGitignore } from "../../core/gitignore.ts";
+import { astroBuildDiagnostics } from "../build-failure.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { refuseIfEjected } from "../eject-scripts.ts";
-import { logger } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 export const checkCommand = defineCommand({
@@ -57,7 +58,17 @@ export const checkCommand = defineCommand({
 
     // Generate Astro's content/collection and font types into `.blume/.astro`
     // so `astro:*` virtual modules resolve during the check.
-    await sync({ logLevel: "warn", root: outDir });
+    try {
+      await sync({ logLevel: "warn", root: outDir });
+    } catch (error) {
+      // A sync that rejects on the site (a tsconfig `extends` that doesn't
+      // resolve, a page Astro can't load) is reported as `blume build` does.
+      if (!(error instanceof Error)) {
+        throw error;
+      }
+      reportDiagnostics(await astroBuildDiagnostics(error, { root }), root);
+      process.exit(1);
+    }
 
     // The project-root tsconfig is what covers the authored `pages/` and config;
     // without it astro check only sees the generated `.blume` project. Falls back

package/src/cli/commands/dev.ts

@@ -152,7 +152,7 @@ export const devCommand = defineCommand({
       if (error instanceof BlumeError || !(error instanceof Error)) {
         throw error;
       }
-      reportDiagnostics(astroBuildDiagnostics(error), root);
+      reportDiagnostics(await astroBuildDiagnostics(error, { root }), root);
       process.exit(1);
     }
 

package/src/cli/commands/doctor.ts

@@ -22,6 +22,7 @@ import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { unregisteredSnapshotDiagnostics } from "../../core/version-cut.ts";
+import { servedFiles } from "../../deploy/generated-files.ts";
 import { commandMeta } from "../command-meta.ts";
 import { loadEnvFiles } from "../env.ts";
 import { reportInternalError } from "../internal-error.ts";
@@ -33,7 +34,7 @@ import {
 } from "../log.ts";
 import { checkRequiredSecrets } from "../required-secrets.ts";
 
-const FALLBACK_NODE_RANGE = ">=22.12.0";
+const FALLBACK_NODE_RANGE = ">=22.19.0";
 
 /**
  * Plan `components.ts` the way `blume dev`/`build` do, reporting each override
@@ -142,7 +143,8 @@ export const doctorCommand = defineCommand({
         ...unregisteredSnapshotDiagnostics(project),
         ...validateNavTargets(
           project.graph.navigation,
-          navTargetRoutes(project, userPages)
+          navTargetRoutes(project, userPages),
+          servedFiles(project)
         )
       );
 

package/src/cli/commands/init.ts

@@ -75,9 +75,9 @@ const installScaffold = async (
 /**
  * Eject the freshly scaffolded project, or print the install-then-eject path.
  * Eject jiti-loads the scaffolded blume.config.ts, whose `import { defineConfig }
- * from "blume"` only resolves once dependencies are installed (or blume is
- * hoisted from an ancestor node_modules, as in a monorepo) — so the fallback
- * below is the common path when the install step was skipped.
+ * from "blume"` resolves to the running Blume package even before an install
+ * (see `blumeModuleAliases`). When eject still fails after a skipped install,
+ * the fallback below names the install as the likely fix.
  */
 const ejectScaffold = async (
   root: string,

package/src/cli/commands/preview.ts

@@ -4,15 +4,19 @@ import { preview } from "astro";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { normalizeBasePath } from "../../core/base-path.ts";
 import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
+import { publicFolder } from "../../core/static-host.ts";
 import { deployOutputDir } from "../../deploy/adapter-output.ts";
 import { deployPlatform } from "../../deploy/platforms/index.ts";
+import { distDir } from "../../deploy/platforms/paths.ts";
 import { parsePort } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfEjected } from "../eject-scripts.ts";
 import { normalizeHost } from "../host-args.ts";
 import { logger } from "../log.ts";
+import { previewRedirects, servePreview } from "../preview-pages.ts";
 
 export const previewCommand = defineCommand({
   args: {
@@ -48,7 +52,7 @@ export const previewCommand = defineCommand({
       process.exit(1);
     }
 
-    await preview({
+    const server = await preview({
       logLevel: "info",
       root: context.outDir,
       server: {
@@ -58,5 +62,17 @@ export const previewCommand = defineCommand({
         port: parsePort(args.port),
       },
     });
+    // A static build is served by Vite, which knows nothing of the host's
+    // redirect rules or trailing-slash handling, and whose HTML fallback
+    // would answer a page with the redirect page of a redirect from its
+    // `.html` URL.
+    if (deployment.options.output === "static") {
+      servePreview(server, {
+        base: normalizeBasePath(deployment.options.base),
+        distDir: distDir(context),
+        isPublicFolder: publicFolder(join(context.root, "public")),
+        redirects: previewRedirects(config, context.outDir),
+      });
+    }
   },
 });