blume 2.1.3 → 2.2.0

package/src/core/load-module.ts

@@ -1,16 +1,100 @@
+import { readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+
 import { createJiti } from "jiti";
+import type { Jiti, JitiOptions } from "jiti";
+import { join } from "pathe";
+import { z } from "zod";
+
+import { packageRoot } from "./package-root.ts";
+
+/**
+ * Blume's own `exports` map, each entry reduced to the file it runs from: the
+ * target itself, or a conditions object's `default` (its `types` is only for
+ * the consumer's typechecker).
+ */
+const blumeExportsSchema = z.object({
+  exports: z.record(
+    z.string(),
+    z.union([
+      z.string(),
+      z.object({ default: z.string() }).transform((target) => target.default),
+    ])
+  ),
+});
+
+let aliases: Record<string, string> | undefined;
+
+/**
+ * jiti aliases that resolve `blume` and every subpath it exports to the
+ * running Blume package, read from its own `exports` map. Without them a user
+ * module resolves `blume` by walking up from its own folder, so a `meta.ts`
+ * under a content root outside the project (`content.root: "../docs"`, a
+ * sibling workspace package) or a file `blume.config.ts` imports from beside
+ * the project can't find the `blume` installed in the project. A wildcard
+ * export (`./core/*`) becomes a prefix alias (`blume/core/`), which jiti
+ * extends with the rest of the specifier.
+ */
+export const blumeModuleAliases = (): Record<string, string> => {
+  if (!aliases) {
+    const root = packageRoot();
+    const { exports } = blumeExportsSchema.parse(
+      JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))
+    );
+    aliases = Object.fromEntries(
+      Object.entries(exports).map(([subpath, target]) => [
+        join("blume", subpath).replace(/\*$/u, ""),
+        join(root, target).replace(/\*$/u, ""),
+      ])
+    );
+  }
+  return aliases;
+};
+
+/**
+ * An import through one jiti instance for every file a loader is called with,
+ * created on its first call so that importing this module (the `blume` barrel
+ * reaches it through `defineConfig`) reads nothing from disk. `moduleCache:
+ * false` ensures edits are picked up on each load, which is what makes
+ * dev-server regeneration reflect config/meta changes.
+ *
+ * Each import leaves `Error.prepareStackTrace` as it found it. The first file
+ * jiti compiles loads its bundled Babel, which wraps that formatter for the
+ * whole process to hide its own frames. Under Bun the wrapper hands off to
+ * Bun's native formatter, which throws for an object that isn't a native
+ * `Error`, and Vite's bundled follow-redirects captures a stack trace on one
+ * as it loads, so importing Astro or Vite after a compiled config or meta file
+ * would crash.
+ */
+const lazyImport = (
+  options: JitiOptions
+): ((file: string) => Promise<{ default?: unknown }>) => {
+  let jiti: Jiti | undefined;
+  return async (file) => {
+    jiti ??= createJiti(import.meta.url, {
+      ...options,
+      alias: blumeModuleAliases(),
+      moduleCache: false,
+    });
+    const { prepareStackTrace } = Error;
+    try {
+      return await jiti.import<{ default?: unknown }>(file);
+    } finally {
+      Error.prepareStackTrace = prepareStackTrace;
+    }
+  };
+};
 
 /**
  * Create a loader for user-authored ESM/TS modules (`blume.config.ts`,
- * `meta.ts`). One jiti instance is reused across every file the returned loader
- * is called with. `moduleCache: false` ensures edits are picked up on each load,
- * which is what makes dev-server regeneration reflect config/meta changes.
+ * `meta.ts`), in which `blume` resolves to the running package wherever the
+ * module lives (see {@link blumeModuleAliases}).
  */
 // oxlint-disable-next-line anti-slop/no-unknown-returns -- user-authored modules can export anything; callers validate the loaded value at their own boundary
 export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
-  const jiti = createJiti(import.meta.url, { moduleCache: false });
+  const load = lazyImport({});
   return async (file: string) => {
-    const loaded = await jiti.import<{ default?: unknown }>(file);
+    const loaded = await load(file);
     return loaded?.default ?? loaded;
   };
 };
@@ -22,15 +106,20 @@ export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
  * exports `null`/`undefined`, resolves to `undefined` so the caller can say
  * so, instead of validating `{}` (a bare `defineConfig({…})` call) or
  * `{ config }` (a named export). jiti's default interop is off because it
- * throws on `export default null`.
+ * throws on `export default null`. Turning it off changes how jiti compiles
+ * every module the config reaches, Blume's own source included, but jiti keys
+ * its disk cache by file and source alone, so this loader keeps a cache of its
+ * own: sharing one, it would run code compiled for {@link createModuleLoader}
+ * (and that loader, code compiled for this one), whichever loaded the file
+ * first.
  */
 export const createDefaultExportLoader: typeof createModuleLoader = () => {
-  const jiti = createJiti(import.meta.url, {
+  const load = lazyImport({
+    fsCache: join(tmpdir(), "jiti-blume-default-export"),
     interopDefault: false,
-    moduleCache: false,
   });
   return async (file: string) => {
-    const loaded = await jiti.import<{ default?: unknown }>(file);
+    const loaded = await load(file);
     return loaded.default ?? undefined;
   };
 };

package/src/core/manifest.ts

@@ -1,4 +1,5 @@
 import { mountBasePath } from "./base-path.ts";
+import { isHiddenPage } from "./hidden-pages.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type {
@@ -52,10 +53,11 @@ export const MANIFEST_VERSION = 1;
  */
 export const contentIndexable = (
   page: PageRecord,
-  config: ResolvedConfig
+  config: ResolvedConfig,
+  graph: ContentGraph
 ): boolean =>
   !page.meta.search.exclude &&
-  (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
+  (!isHiddenPage(page, graph) || config.search.indexing.includeHiddenPages);
 
 /**
  * Fallback materialization: render the fallback locale's content at the
@@ -66,9 +68,10 @@ export const contentIndexable = (
 /**
  * The description a page's `<head>` emits — `seo.description` over the front
  * matter `description` — mirrored onto its route so the OG card's subtitle
- * matches the page's `og:description`.
+ * matches the page's `og:description`, and the summary page indexes like
+ * `llms.txt` give it.
  */
-const routeDescription = (page: PageRecord): string | undefined =>
+export const metaDescription = (page: PageRecord): string | undefined =>
   page.meta.seo.description ?? page.description;
 
 const buildFallbackRoutes = (
@@ -121,12 +124,12 @@ const buildFallbackRoutes = (
         alternates: alternatesByKey.get(key) ?? [],
         collection: source.collection ?? "docs",
         contentType: source.contentType,
-        description: routeDescription(source),
+        description: metaDescription(source),
         draft: source.meta.draft,
         editUrl: source.editUrl,
         entryId: source.entryId ?? source.source.ref,
         fallback: true,
-        hidden: source.meta.sidebar.hidden,
+        hidden: isHiddenPage(source, graph),
         id: source.id,
         indexable: false,
         lastModified: source.lastModified,
@@ -187,13 +190,13 @@ export const buildManifest = (options: {
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
     contentType: page.contentType,
-    description: routeDescription(page),
+    description: metaDescription(page),
     draft: page.meta.draft,
     editUrl: page.editUrl,
     entryId: page.entryId ?? page.source.ref,
-    hidden: page.meta.sidebar.hidden,
+    hidden: isHiddenPage(page, graph),
     id: page.id,
-    indexable: searchEnabled && contentIndexable(page, config),
+    indexable: searchEnabled && contentIndexable(page, config, graph),
     lastModified: page.lastModified,
     locale: page.locale,
     monolingual: page.monolingual,

package/src/core/markdown-mirrors.ts

@@ -0,0 +1,52 @@
+import { servesRoute } from "./locale-links.ts";
+import type { RouteSet } from "./locale-links.ts";
+
+/**
+ * Where Blume serves each page's raw Markdown: a copy beside the page, named
+ * for its route (`/guide.md`, `/guide.mdx`; see `rawMarkdownEndpointTemplate`).
+ */
+
+/** The extensions every page's Markdown copies are served at. */
+export const MIRROR_EXTENSIONS = [".md", ".mdx"] as const;
+
+/**
+ * The name the root's copies are served under (`/index.md`). They always are:
+ * with no page at `/`, the llms.txt index stands in (see `buildRawMarkdown`).
+ */
+const ROOT_MIRROR = "/index";
+
+/** A path naming a Markdown copy: the name it's served under, then `.md(x)`. */
+const MIRROR_PATH = /^(?<name>\/.+)\.mdx?$/u;
+
+/** The name a page's Markdown copies are served under, from its route. */
+export const mirrorName = (route: string): string =>
+  route === "/" ? ROOT_MIRROR : route;
+
+/**
+ * The page whose Markdown copies are served under `name`, if any are: the
+ * root's under `/index`, and a page's under its own route. `/index` is no
+ * page's route, yet it names the root's copies, so a path that isn't a page
+ * can still name a served copy.
+ */
+export const mirrorOwner = (
+  pages: RouteSet,
+  name: string
+): string | undefined => {
+  if (name === ROOT_MIRROR) {
+    return "/";
+  }
+  return servesRoute(pages, name) ? name : undefined;
+};
+
+/**
+ * The page a served Markdown copy at `path` belongs to (`/guide.md` the page
+ * `/guide`'s, `/index.mdx` the root's), or `undefined` when `path` is no
+ * served copy.
+ */
+export const mirroredPage = (
+  pages: RouteSet,
+  path: string
+): string | undefined => {
+  const name = MIRROR_PATH.exec(path)?.groups?.name;
+  return name === undefined ? undefined : mirrorOwner(pages, name);
+};

package/src/core/mdx-elements.ts

@@ -0,0 +1,153 @@
+import type { Nodes } from "mdast";
+import { mdxToMdast } from "satteri";
+
+import { MDX_BODY_FEATURES } from "../markdown/features.ts";
+import { BUILTIN_CHILD_PROPS } from "./builtin-tags.ts";
+import type { ElementUse } from "./types.ts";
+
+/**
+ * JSX elements in an `.mdx` body whose props don't render as written:
+ *
+ * - `handler`: an HTML element with a JavaScript event handler
+ *   (`<button onClick={() => …}>`). The page is static HTML, so the function
+ *   is written into the attribute as text and never runs. A string handler
+ *   (`onclick="…"`) is inline script the browser does run, and is left alone.
+ * - `prop`: a built-in that shows its children (see `BUILTIN_CHILD_PROPS`),
+ *   used without any, with props it doesn't take. Those are ignored, so the
+ *   element renders without the content they carry.
+ */
+
+type JsxElement = Extract<
+  Nodes,
+  { type: "mdxJsxFlowElement" | "mdxJsxTextElement" }
+>;
+type AttributeValue = Extract<
+  JsxElement["attributes"][number],
+  { type: "mdxJsxAttribute" }
+>["value"];
+type ExpressionValue = Extract<AttributeValue, { type: string }>;
+
+/** Whether an attribute's value is a `{…}` expression, not a string or nothing. */
+export const isExpression = (value: AttributeValue): value is ExpressionValue =>
+  typeof value === "object" && value !== null;
+
+// An `on*` prop, and a body that may hold one with an expression value.
+const EVENT_HANDLER = /^on[A-Z]/u;
+const HANDLER_HINT = /\son[A-Z]\w*\s*=\s*\{/u;
+// An expression that is only a string literal, which renders as that string.
+const STRING_LITERAL = /^\s*(?<quote>["'`])[\s\S]*\k<quote>\s*$/u;
+// An intrinsic element: a lowercase name, not a member like `motion.div`.
+const HTML_ELEMENT = /^[a-z][\w-]*$/u;
+
+// A built-in that shows its children, opened with props and either closed at
+// once or closed with nothing between the tags. Attribute values may hold
+// `>`, so quoted strings and one level of braces are skipped whole.
+const CHILDLESS_HINT = new RegExp(
+  String.raw`<(?<tag>${[...BUILTIN_CHILD_PROPS.keys()].join("|")})\s(?:[^<>"'{}]|"[^"]*"|'[^']*'|\{[^{}]*\})*(?:\/>|>\s*<\/\k<tag>>)`,
+  "u"
+);
+
+/** Whether an element has nothing to show between its tags. */
+const isChildless = (node: JsxElement): boolean =>
+  node.children.every(
+    (child) => child.type === "text" && child.value.trim() === ""
+  );
+
+/** The handler props on an HTML element that hold a JavaScript value. */
+const handlerProps = (node: JsxElement): string[] =>
+  node.attributes.flatMap((attribute) =>
+    attribute.type === "mdxJsxAttribute" &&
+    EVENT_HANDLER.test(attribute.name) &&
+    isExpression(attribute.value) &&
+    !STRING_LITERAL.test(attribute.value.value)
+      ? [attribute.name]
+      : []
+  );
+
+/**
+ * The props a childless built-in gets but doesn't take. A spread
+ * (`{...props}`) could pass anything, so it counts as none; an Astro
+ * directive (`client:load`, `set:html`) isn't a prop.
+ */
+const unknownProps = (node: JsxElement, accepted: readonly string[]) => {
+  if (
+    !isChildless(node) ||
+    node.attributes.some((attribute) => attribute.type !== "mdxJsxAttribute")
+  ) {
+    return [];
+  }
+  return node.attributes.flatMap((attribute) =>
+    attribute.type === "mdxJsxAttribute" &&
+    !attribute.name.includes(":") &&
+    !accepted.includes(attribute.name)
+      ? [attribute.name]
+      : []
+  );
+};
+
+/** What `node` carries that doesn't render as written, if anything. */
+const elementUse = (
+  node: JsxElement,
+  lineOffset: number
+): ElementUse | undefined => {
+  const tag = node.name ?? "";
+  const accepted = BUILTIN_CHILD_PROPS.get(tag);
+  let kind: ElementUse["kind"] = "prop";
+  let props: string[] = [];
+  if (HTML_ELEMENT.test(tag)) {
+    kind = "handler";
+    props = handlerProps(node);
+  } else if (accepted) {
+    props = unknownProps(node, accepted);
+  }
+  const start = node.position?.start;
+  return props.length > 0
+    ? {
+        column: start?.column ?? 1,
+        kind,
+        line: (start?.line ?? 1) + lineOffset,
+        props,
+        tag,
+      }
+    : undefined;
+};
+
+/**
+ * Every element in an `.mdx` body whose props don't render as written (see
+ * the module comment), in source order, its line shifted by `lineOffset`. The
+ * body is parsed only when a cheap test finds a suspect, and a body MDX can't
+ * parse fails to render with its own error, so it yields none.
+ */
+export const extractElementUses = (
+  body: string,
+  lineOffset = 0
+): ElementUse[] => {
+  if (!(HANDLER_HINT.test(body) || CHILDLESS_HINT.test(body))) {
+    return [];
+  }
+  let tree: Nodes;
+  try {
+    tree = mdxToMdast(body, { features: MDX_BODY_FEATURES });
+  } catch {
+    return [];
+  }
+  const uses: ElementUse[] = [];
+  const walk = (node: Nodes): void => {
+    if (
+      node.type === "mdxJsxFlowElement" ||
+      node.type === "mdxJsxTextElement"
+    ) {
+      const use = elementUse(node, lineOffset);
+      if (use) {
+        uses.push(use);
+      }
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return uses;
+};