blume 2.1.3 → 2.2.1

package/src/core/project-graph.ts

@@ -1,10 +1,15 @@
-import { isAbsolute, relative } from "pathe";
+import { existsSync } from "node:fs";
 
+import { isAbsolute, join, relative } from "pathe";
+
+import { alertDiagnostics } from "./alert-diagnostics.ts";
 import { normalizePath, withBasePath } from "./base-path.ts";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
+import { codeFenceDiagnostics } from "./code-fence-diagnostics.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
-import { unknownDirectiveDiagnostics } from "./directive-diagnostics.ts";
+import { directiveDiagnostics } from "./directive-diagnostics.ts";
+import { formerRouteRedirects } from "./former-routes.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -15,8 +20,13 @@ import {
   realPath,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
+import { routeSetFor } from "./locale-links.ts";
+import type { RouteSet } from "./locale-links.ts";
 import { buildManifest } from "./manifest.ts";
-import { discoverFolderMeta } from "./meta.ts";
+import { mirroredPage } from "./markdown-mirrors.ts";
+import { mdxSyntaxCheck } from "./mdx-syntax.ts";
+import { folderMetaDiagnostics } from "./meta-diagnostics.ts";
+import { discoverFolderMeta, withGeneratedFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
 import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
@@ -29,6 +39,8 @@ import type {
   SourceEntry,
   SourceLoadResult,
 } from "./sources/types.ts";
+import { unmeasurableSvgDiagnostics } from "./svg-images.ts";
+import { indexPageNames, syntaxDiagnostics } from "./syntax-diagnostics.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -96,8 +108,16 @@ export interface BlumeProject {
   graph: ContentGraph;
   manifest: BlumeManifest;
   diagnostics: Diagnostic[];
-  /** Entries excluded from the graph because their frontmatter failed validation. */
+  /**
+   * Entries excluded from the graph because their frontmatter failed
+   * validation, or (in a build) their MDX doesn't parse.
+   */
   droppedPages: number;
+  /**
+   * The local `.mdx` files a build dropped because they don't parse, which
+   * the docs collection leaves out so Astro never compiles them.
+   */
+  unparsable: string[];
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
   /**
@@ -162,11 +182,14 @@ const entryIdDiagnostics = (
  * collecting pages, diagnostics, and the count of entries dropped outright —
  * an entry that yields no pages but did yield diagnostics was rejected for
  * invalid frontmatter, and callers surface that count so a build with missing
- * pages can't read as clean.
+ * pages can't read as clean. With `dropUnparsable`, an `.mdx` page whose own
+ * text doesn't parse is dropped too, and its file listed in `unparsable` so
+ * the docs collection leaves it out.
  */
 const normalizeLoadedEntries = (
   loaded: ({ source: ContentSource } & SourceLoadResult)[],
-  config: ResolvedConfig
+  config: ResolvedConfig,
+  dropUnparsable: boolean
 ) => {
   // Only thread `frontmatter.extend` / `content.types` through when a project
   // opts in, so the known-key split in `normalizeEntry` stays off the default
@@ -187,10 +210,25 @@ const normalizeLoadedEntries = (
 
   const pages: PageRecord[] = [];
   const allDiagnostics: Diagnostic[] = [];
+  const syntaxErrors: Diagnostic[] = [];
+  const unparsable: string[] = [];
+  // Published entries, checked for other tools' syntax once every page is
+  // known: a wiki link is reported when it names one.
+  const published: { entry: SourceEntry; locale: string; source: string }[] =
+    [];
   let droppedPages = 0;
   for (const { source, entries, diagnostics } of loaded) {
     allDiagnostics.push(...diagnostics);
     for (const entry of entries) {
+      const syntax = mdxSyntaxCheck(entry, source.name, config.variables);
+      syntaxErrors.push(...syntax.diagnostics);
+      // A build drops a page whose MDX doesn't parse, as it does one whose
+      // front matter fails: with --no-strict the rest of the site still
+      // builds. Dev keeps it, so opening it shows the error in place.
+      const drop = syntax.unparsable && dropUnparsable;
+      if (drop && entry.sourcePath && !source.staged) {
+        unparsable.push(entry.sourcePath);
+      }
       const normalized = normalizeEntry(entry, {
         basePath: config.basePath,
         defaultType: config.content.defaultType,
@@ -206,17 +244,41 @@ const normalizeLoadedEntries = (
         typeFrontmatter,
         versions: config.versions,
       });
-      if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
+      const [page] = normalized.pages;
+      if (page ? drop : normalized.diagnostics.length > 0) {
         droppedPages += 1;
       }
-      pages.push(...normalized.pages);
+      if (!drop) {
+        pages.push(...normalized.pages);
+      }
       allDiagnostics.push(...normalized.diagnostics);
-      if (normalized.pages.length > 0) {
-        allDiagnostics.push(...unknownDirectiveDiagnostics(entry, source.name));
+      if (page) {
+        allDiagnostics.push(
+          ...directiveDiagnostics(entry, source.name),
+          ...codeFenceDiagnostics(entry, source.name),
+          ...alertDiagnostics(entry, source.name)
+        );
+        published.push({ entry, locale: page.locale, source: source.name });
       }
     }
   }
-  return { diagnostics: allDiagnostics, droppedPages, pages };
+  const names = indexPageNames(pages);
+  for (const { entry, locale, source } of published) {
+    allDiagnostics.push(...syntaxDiagnostics(entry, source, names, locale));
+  }
+  // A parse error gives way to a diagnostic as severe at its line, which
+  // names the cause (`BLUME_MDX_CURLY_ANCHOR` for a `{#id}` heading marker,
+  // `BLUME_MDX_ATTRIBUTE_LIST` in a partial).
+  const covered = (diagnostic: Diagnostic): boolean =>
+    allDiagnostics.some(
+      (other) =>
+        other.file === diagnostic.file &&
+        other.line === diagnostic.line &&
+        (other.severity === "error" ||
+          (other.severity === "warning" && diagnostic.severity === "warning"))
+    );
+  allDiagnostics.push(...syntaxErrors.filter((error) => !covered(error)));
+  return { diagnostics: allDiagnostics, droppedPages, pages, unparsable };
 };
 
 /**
@@ -315,29 +377,45 @@ const substituteLoadedVariables = (
  * 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.
+ * depend on the host. So is one from a page's Markdown copy (`/guide.md`, or
+ * the root's `/index.md`), which it takes over the same way. `mirrored` are
+ * the routes served with copies: the content pages.
  */
 const redirectPageDiagnostics = (
   config: ResolvedConfig,
   pages: readonly string[],
+  mirrored: RouteSet,
   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)
-        ? [
+      if (pages.includes(page)) {
+        return [
+          {
+            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 owner = mirroredPage(mirrored, page);
+      return owner === undefined
+        ? []
+        : [
             {
               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.`,
+              message: `The redirect from ${redirect.from} is also the Markdown copy of the page ${owner}, so that copy 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.",
+                "Remove the redirect: that URL serves the page's Markdown to agents.",
             } satisfies Diagnostic,
-          ]
-        : [];
+          ];
     }
     const matched = pathsUnderPattern(from, pages);
     const [first] = matched;
@@ -357,6 +435,83 @@ const redirectPageDiagnostics = (
     ];
   });
 
+/**
+ * The config with the redirects sources ask for added after its own (see
+ * `SourceLoadResult.redirects`), so every surface that reads
+ * `config.redirects` — Astro's redirect pages, the host files, the link
+ * checker — serves them alike. Each is repeated under every locale prefix
+ * whose copy of the target page is served (a translation, or the fallback
+ * copy), and is kept only where its target is a page and nothing else
+ * answers for its `from`: a page there, or a configured redirect, wins.
+ * `pages` are the served page paths, which carry `basePath`.
+ */
+const withSourceRedirects = (
+  config: ResolvedConfig,
+  loaded: readonly SourceLoadResult[],
+  pages: RouteSet
+): ResolvedConfig => {
+  const requested = loaded.flatMap(({ redirects }) => redirects ?? []);
+  if (requested.length === 0) {
+    return config;
+  }
+  const served = (route: string): string =>
+    normalizePath(withBasePath(config.basePath, route));
+  const prefixes = [
+    "",
+    ...(config.i18n?.locales.map((locale) => `/${locale.code}`) ?? []),
+  ];
+  const taken = new Set(
+    config.redirects.map((redirect) => served(redirect.from))
+  );
+  const added: ResolvedConfig["redirects"] = [];
+  for (const redirect of requested) {
+    for (const prefix of prefixes) {
+      const from = `${prefix}${redirect.from}`;
+      const to = `${prefix}${redirect.to}`;
+      if (
+        !pages.has(served(to)) ||
+        pages.has(served(from)) ||
+        taken.has(served(from))
+      ) {
+        continue;
+      }
+      taken.add(served(from));
+      added.push({ from, status: 301, to });
+    }
+  }
+  return added.length > 0
+    ? { ...config, redirects: [...config.redirects, ...added] }
+    : config;
+};
+
+/**
+ * A `public/openapi.json` is served at `/openapi.json`, where Blume
+ * publishes the OpenAPI description of the site's own JSON docs API: the
+ * build stops generating that description, while the API catalog
+ * (`/.well-known/api-catalog`) still lists `/openapi.json` as the docs API's
+ * `service-desc`, so agents reading it get the project's file instead. Only
+ * when the docs API is on; otherwise Blume publishes nothing there.
+ */
+const publicOpenApiDiagnostics = (
+  config: ResolvedConfig,
+  root: string
+): Diagnostic[] => {
+  const file = join(root, "public", "openapi.json");
+  return config.agents.api && existsSync(file)
+    ? [
+        {
+          code: "BLUME_PUBLIC_OPENAPI_JSON",
+          file,
+          message:
+            "public/openapi.json is served at /openapi.json, where Blume publishes the OpenAPI description of the site's JSON docs API, so that description isn't generated, and /.well-known/api-catalog still lists /openapi.json as the docs API's description.",
+          severity: "warning",
+          suggestion:
+            "Move the file to another path, like public/specs/openapi.json, and update what links to it. A spec an openapi() reference renders can live outside public/ altogether. Or set agents.api to false if the site shouldn't publish the JSON docs API.",
+        },
+      ]
+    : [];
+};
+
 /** The configured banner link target, when the banner has a link. */
 const bannerLinkHref = (
   banner: ResolvedConfig["banner"]
@@ -495,19 +650,30 @@ export const scanProject = async (
   // 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
-  // entries, which are spread last and win.
-  const sharedFolderMeta = new Map([
-    ...loaded.flatMap(({ folderMeta: sourceMeta }) =>
-      Object.entries(sourceMeta ?? {})
+  // entries, whose own fields win while the generated ones fill the rest.
+  const mergedFolderMeta = withGeneratedFolderMeta(
+    folderMeta,
+    new Map(
+      loaded.flatMap(({ folderMeta: sourceMeta }) =>
+        Object.entries(sourceMeta ?? {})
+      )
     ),
-    ...folderMeta.shared,
-  ]);
+    localeDirs
+  );
 
   const {
     diagnostics: contentDiagnostics,
     droppedPages,
     pages: allPages,
-  } = normalizeLoadedEntries(loaded, config);
+    unparsable,
+  } = normalizeLoadedEntries(loaded, config, mode === "build");
+
+  // Checked against every page, drafts included: a `pages` entry naming a
+  // draft still orders it wherever the draft renders.
+  const metaDiagnostics = await folderMetaDiagnostics(folderMeta, allPages, {
+    localeDirs,
+    versionDirs: config.versions?.archived.map((version) => version.id),
+  });
 
   // Drafts render in dev and in preview, but are excluded from production builds.
   const pages =
@@ -573,10 +739,10 @@ export const scanProject = async (
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
     extraRoutes,
-    folderMeta: folderMeta.meta,
+    folderMeta: mergedFolderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
-    sharedFolderMeta,
+    sharedFolderMeta: mergedFolderMeta.shared,
     versions: config.versions,
   });
   const manifest = buildManifest({ config, context, graph });
@@ -584,18 +750,40 @@ export const scanProject = async (
   const i18nWarnings = config.i18n
     ? i18nDiagnostics(pages, config.i18n, config.versions)
     : [];
+  const svgWarnings = await unmeasurableSvgDiagnostics(pages);
   const versionWarnings = config.versions
     ? versionsDiagnostics(pages, config.versions)
     : [];
 
+  const servedPaths = [
+    ...manifest.routes.map((route) => route.path),
+    ...extraRoutes,
+  ];
+  // A date-named page's old URL, from before its name was kept whole,
+  // redirects to its new one, beside the redirects the config lists.
+  const redirects = [
+    ...config.redirects,
+    ...formerRouteRedirects(pages, new Set(servedPaths), config),
+  ];
+
   return {
-    config,
+    // Then the routes the API references served under earlier versions'
+    // rules redirect to where those operations live now.
+    config: withSourceRedirects(
+      redirects.length === config.redirects.length
+        ? config
+        : { ...config, redirects },
+      loaded,
+      new Set([...routeSetFor(manifest.routes), ...extraRoutes])
+    ),
     context,
     diagnostics: [
+      ...configResult.diagnostics,
       ...contentDiagnostics,
       ...includeDiagnostics,
       ...variableDiagnostics,
       ...folderMeta.diagnostics,
+      ...metaDiagnostics,
       ...entryIdDiagnostics(
         pages,
         resolveDocsCollection(config, context.root).base
@@ -604,9 +792,12 @@ export const scanProject = async (
       ...i18nWarnings,
       ...versionWarnings,
       ...lastModifiedWarnings,
+      ...svgWarnings,
+      ...publicOpenApiDiagnostics(config, context.root),
       ...redirectPageDiagnostics(
         config,
-        [...manifest.routes.map((route) => route.path), ...extraRoutes],
+        servedPaths,
+        routeSetFor(manifest.routes),
         context.configFile
       ),
     ],
@@ -616,5 +807,6 @@ export const scanProject = async (
     mode,
     sources,
     themeFontsConfigured: configResult.themeFontsConfigured,
+    unparsable,
   };
 };

package/src/core/redirect-patterns.ts

@@ -184,6 +184,21 @@ const replaceReferences = (
     replace(referenceName(name), match.startsWith("/"))
   );
 
+/**
+ * The literal start of a `to` that reads a capture, up to its first
+ * reference: `/guides/` for `/guides/:slug*`, `/new/article-` for
+ * `/new/article-*`. `undefined` for a `to` that reads none, which is one
+ * exact path.
+ */
+export const destinationPrefix = (to: string): string | undefined => {
+  const at = to.search(REFERENCE);
+  if (at === -1) {
+    return undefined;
+  }
+  // A whole-segment reference starts at its slash, which the prefix keeps.
+  return to.slice(0, to[at] === "/" ? at + 1 : at);
+};
+
 /** Whether a path is a pattern, rather than one exact path. */
 export const isPatternPath = (path: string): boolean => {
   const parsed = parseFrom(path);
@@ -278,6 +293,32 @@ export const expandRedirect = (redirect: RedirectEnds): RedirectRule[] => {
   ];
 };
 
+/**
+ * The bare path a pattern ending in a rest also matches, as the exact
+ * redirect every host is given for it: `/beta/:slug*` (or `/beta/*`) to
+ * `/v2/:slug*` sends `/beta` itself to `/v2`. Null for an exact redirect,
+ * a pattern with no rest, and one whose bare path still holds a capture
+ * (`/:lang/*`), which names no single path.
+ */
+export const bareRedirect = (
+  redirect: RedirectEnds
+): { from: string; to: string } | null => {
+  // A rest expands to two rules, the bare path first (see `expandRedirect`).
+  const rules = expandRedirect(redirect);
+  const [bare] = rules;
+  if (rules.length !== 2 || bare === undefined) {
+    return null;
+  }
+  let from = "";
+  for (const part of bare.parts) {
+    if (part.kind !== "text") {
+      return null;
+    }
+    from += part.text;
+  }
+  return { from, to: bare.to };
+};
+
 /** Put exact redirects ahead of patterns, which hosts try in order. */
 export const exactFirst = <Redirect extends { from: string }>(
   redirects: readonly Redirect[]

package/src/core/relative-files.ts

@@ -0,0 +1,145 @@
+import { readdirSync, statSync } from "node:fs";
+
+import { basename, dirname, extname, normalize, resolve } from "pathe";
+
+/**
+ * The files a page names beside it: an image it embeds (`![](./diagram.png)`)
+ * and any other file it links (`[spec](./spec.pdf)`, `<img src>`). One
+ * reading, shared by everything that handles them: the include expander that
+ * rebases a partial's, the content-asset rewriter that publishes them, the
+ * render plugin that points the built page at them, and link validation.
+ */
+
+// The formats Astro's image pipeline accepts, plus the web-safe pass-throughs;
+// anything else referenced relatively (a `.pdf`, a source file) is left alone.
+const IMAGE_EXTENSIONS = new Set([
+  ".apng",
+  ".avif",
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".svg",
+  ".tiff",
+  ".webp",
+]);
+
+// A link to one of these names a page (see `resolveRelativeHref` in
+// `links.ts`), never a file to publish.
+const PAGE_EXTENSIONS = new Set([".md", ".mdx"]);
+
+/** Whether a link target is a relative filesystem path (not URL/absolute/hash). */
+const isRelativeTarget = (target: string): boolean =>
+  !(target.startsWith("/") || target.startsWith("#")) && !URL.canParse(target);
+
+/** Percent-decode a target; malformed escapes stay verbatim. */
+const decodeTarget = (target: string): string => {
+  try {
+    return decodeURI(target);
+  } catch {
+    return target;
+  }
+};
+
+/**
+ * Whether a target is *shaped* like a colocated image reference: a relative
+ * filesystem path with an image extension. Exported so link validation can
+ * tell "not a colocated candidate" apart from "a candidate that resolves
+ * nowhere" — the former falls through to the public-dir probe, the latter is
+ * a broken reference beside the page source.
+ */
+export const isRelativeImageTarget = (target: string): boolean =>
+  isRelativeTarget(target) &&
+  IMAGE_EXTENSIONS.has(extname(decodeTarget(target)).toLowerCase());
+
+/**
+ * Whether `abs` is a file whose trailing `segments` names match the on-disk
+ * entries exactly. A bare `existsSync` accepts `./Diagram.PNG` for
+ * `diagram.png` (or a directory named like an image) on a case-insensitive
+ * filesystem — the reference then validates and serves locally but breaks on
+ * the case-sensitive Linux build.
+ */
+const existsAsWritten = (abs: string, segments: number): boolean => {
+  let current = abs;
+  for (let i = 0; i < segments; i += 1) {
+    const parent = dirname(current);
+    let entries: string[];
+    try {
+      entries = readdirSync(parent);
+    } catch {
+      return false;
+    }
+    if (!entries.includes(basename(current))) {
+      return false;
+    }
+    current = parent;
+  }
+  const stat = statSync(abs, { throwIfNoEntry: false });
+  return stat !== undefined && stat.isFile();
+};
+
+/**
+ * The file a decoded relative `path` names from `sourceDir`, when it's on
+ * disk as written. Only the segments the author wrote are checked against
+ * on-disk names; `sourceDir`'s own casing is the filesystem's business, not
+ * the target's.
+ */
+const fileAsWritten = (sourceDir: string, path: string): string | null => {
+  const segments = normalize(path)
+    .split("/")
+    .filter((part) => part !== "" && part !== "..").length;
+  const abs = resolve(sourceDir, path);
+  return existsAsWritten(abs, segments) ? abs : null;
+};
+
+/**
+ * Resolve one image target against its page's directory. Returns the absolute
+ * file path when the target is relative, is an image, and exists on disk —
+ * anything else (remote URLs, `public/` absolutes, broken refs, code-block
+ * examples that happen to look like paths) is null and left untouched. Shared
+ * with link validation, so what counts as a colocated image is decided once.
+ */
+export const resolveRelativeImage = (
+  sourceDir: string,
+  target: string
+): string | null =>
+  isRelativeImageTarget(target)
+    ? fileAsWritten(sourceDir, decodeTarget(target))
+    : null;
+
+/** A file a link names beside its page, and the link's `?query#fragment`. */
+export interface RelativeFile {
+  path: string;
+  suffix: string;
+}
+
+/**
+ * Resolve the file a link, an element's `src`, or an `href` names beside its
+ * page (`./spec.pdf`, `../files/data.csv#L2`): a relative path whose name
+ * carries an extension other than a page's (`.md`, `.mdx`), on disk as
+ * written (see `existsAsWritten`). Its `?query` or `#fragment` is set aside,
+ * so `./spec.pdf#page=2` opens the served file at that page. Anything else is
+ * null: a page link, a URL, a root path, a missing file. Shared with link
+ * validation, which accepts what this resolves.
+ */
+export const resolveRelativeFile = (
+  sourceDir: string,
+  target: string
+): RelativeFile | null => {
+  const at = target.search(/[?#]/u);
+  const path = decodeTarget(at === -1 ? target : target.slice(0, at));
+  const extension = extname(path).toLowerCase();
+  if (
+    !isRelativeTarget(target) ||
+    extension === "" ||
+    PAGE_EXTENSIONS.has(extension)
+  ) {
+    return null;
+  }
+  const file = fileAsWritten(sourceDir, path);
+  return file === null
+    ? null
+    : { path: file, suffix: at === -1 ? "" : target.slice(at) };
+};