blume 1.4.3 → 1.5.0

package/src/deploy/sitemap.ts

@@ -74,6 +74,37 @@ export const buildSitemapFiles = (
   const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   const deployBase = normalizeBasePath(project.config.deployment.base);
+
+  // Archived-version pages leave the sitemap when the version is noindexed,
+  // or when their canonical points at a still-existing latest equivalent —
+  // listing a URL whose canonical says "index the other page" invites the
+  // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
+  // that exists only in an archived version stays listed (self-canonical).
+  const { versions } = project.config;
+  const archivedById = new Map(
+    (versions?.archived ?? []).map((version) => [version.id, version])
+  );
+  const currentKeys = versions
+    ? new Set(
+        project.graph.pages.flatMap((page) =>
+          page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
+        )
+      )
+    : null;
+  const archivedExcluded = (page: (typeof project.graph.pages)[number]) => {
+    if (!page.version) {
+      return false;
+    }
+    // A non-empty version always names a configured archived entry — that is
+    // the only way detection assigns one.
+    const archived = archivedById.get(page.version);
+    return Boolean(
+      archived?.noindex ||
+      (archived?.canonical === "latest" &&
+        currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
+    );
+  };
+
   const seen = new Set<string>();
   const urls: string[] = [];
   const pushUrl = (route: string, lastModified?: string): void => {
@@ -93,7 +124,8 @@ export const buildSitemapFiles = (
       page.meta.draft ||
       page.meta.sidebar.hidden ||
       page.meta.seo.noindex ||
-      ERROR_ROUTES.has(page.route)
+      ERROR_ROUTES.has(page.route) ||
+      archivedExcluded(page)
     ) {
       continue;
     }

package/src/deploy/vercel-negotiation.ts

@@ -24,7 +24,11 @@
 export const ACCEPT_MARKDOWN_HEADER_VALUE =
   "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
 
-/** A Build Output API route — the subset these helpers read and write. */
+/**
+ * A Build Output API route — the subset these helpers read and write. Parsed
+ * routes keep whatever other fields they carry at runtime; only these are
+ * typed.
+ */
 export interface VercelRoute {
   continue?: boolean;
   dest?: string;
@@ -32,9 +36,12 @@ export interface VercelRoute {
   has?: { key?: string; type: string; value?: string }[];
   headers?: Record<string, string>;
   src?: string;
-  [key: string]: unknown;
 }
 
+/** Whether a parsed route field is a real string (the config is raw JSON). */
+const isString = (value: string | undefined): value is string =>
+  typeof value === "string";
+
 const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
   { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
 ];
@@ -171,10 +178,10 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
   ) === true ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
-    typeof route.src === "string" &&
+    isString(route.src) &&
     Object.keys(route).length === 3) ||
   (route.continue === true &&
-    typeof route.headers?.link === "string" &&
+    isString(route.headers?.link) &&
     route.src === HOME_SRC &&
     Object.keys(route).length === 3);
 

package/src/eval/report.ts

@@ -10,19 +10,19 @@ import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
-const GLYPH: Record<QuestionStatus, string> = {
+const GLYPH = {
   error: "!",
   fail: "✖",
   pass: "✔",
   skip: "⊘",
-};
+} satisfies Record<QuestionStatus, string>;
 
-const STATUS_COLOR: Record<QuestionStatus, ColorFunction> = {
+const STATUS_COLOR = {
   error: colors.yellow,
   fail: colors.red,
   pass: colors.green,
   skip: colors.dim,
-};
+} satisfies Record<QuestionStatus, ColorFunction>;
 
 /** Longest id gets the room; everything shorter aligns to it. */
 const ID_PAD = 28;

package/src/eval/run.ts

@@ -263,12 +263,12 @@ export const runEval = async (options: EvalRunOptions): Promise<EvalResult> => {
     });
   }
 
-  const counts: Record<QuestionStatus, number> = {
+  const counts = {
     error: 0,
     fail: 0,
     pass: 0,
     skip: 0,
-  };
+  } satisfies Record<QuestionStatus, number>;
   for (const result of results) {
     counts[result.status] += 1;
   }

package/src/eval/schema.ts

@@ -17,7 +17,7 @@ const questionSchema = z.strictObject({
   routes: z
     .union([z.string(), z.array(z.string())])
     .default([])
-    .transform((value) => (typeof value === "string" ? [value] : value)),
+    .transform((value) => (Array.isArray(value) ? value : [value])),
   severity: z.enum(["error", "warning"]).default("error"),
   skip: z.boolean().default(false),
 });

package/src/markdown/base-links.ts

@@ -11,7 +11,7 @@ interface UrlNode extends MdastNode {
  * `setProperty`, not by mutating the node object.
  */
 interface MdastUrlContext {
-  setProperty: (node: unknown, key: "url", value: string) => void;
+  setProperty: (node: MdastNode, key: "url", value: string) => void;
 }
 
 /**
@@ -26,6 +26,10 @@ const ASSET_PATH = /\.[a-z0-9]+$/iu;
 /** Strip any `#fragment`/`?query` so only the path is extension-tested. */
 const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 
+/** Only a string URL can be rebased; MDAST allows null or absent urls. */
+const isUrl = (url: string | null | undefined): url is string =>
+  typeof url === "string";
+
 /**
  * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
  * layered over the site-wide `basePath` — to root-relative internal page links
@@ -38,11 +42,7 @@ const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 export const baseLinksPlugin = (deployBase: string, basePath: string) => {
   const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
     const { url } = node;
-    if (
-      typeof url === "string" &&
-      isInternalPath(url) &&
-      !ASSET_PATH.test(pathOf(url))
-    ) {
+    if (isUrl(url) && isInternalPath(url) && !ASSET_PATH.test(pathOf(url))) {
       const next = withComposedBasePath(deployBase, basePath, url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);

package/src/markdown/directives.ts

@@ -21,7 +21,11 @@ const CALLOUT_TYPES = new Set([
 ]);
 
 /** Friendly aliases for the canonical Callout types. */
-const ALIASES: Record<string, string> = {
+interface CalloutAliases {
+  [alias: string]: string;
+}
+
+const ALIASES: CalloutAliases = {
   caution: "warning",
   error: "danger",
   important: "note",
@@ -54,6 +58,8 @@ export const directiveToCalloutPlugin = () => ({
     let title = node.attributes?.title ?? undefined;
 
     // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+    // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
+    // other node reads undefined and fails the check.
     const labelIndex = children.findIndex(
       (child) =>
         child.type === "paragraph" &&

package/src/markdown/heading-anchors.ts

@@ -19,11 +19,14 @@
 import { satteriCollectHastText } from "@astrojs/markdown-satteri";
 import GithubSlugger from "github-slugger";
 
+/** A hast property value: an attribute primitive or a token list. */
+type HastPropertyValue = string | number | boolean | (string | number)[];
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
   name?: string;
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;
@@ -31,8 +34,10 @@ interface HastNode {
 
 /** The slice of Satteri's hast visitor context this plugin reads. */
 interface HastContext {
-  data?: { astro?: { frontmatter?: Record<string, unknown> } };
-  setProperty: (node: HastNode, key: string, value: unknown) => void;
+  data?: {
+    astro?: { frontmatter?: Parameters<typeof satteriCollectHastText>[1] };
+  };
+  setProperty: (node: HastNode, key: string, value: HastPropertyValue) => void;
   textContent: (node: HastNode) => string;
 }
 
@@ -63,7 +68,7 @@ const containsAnchor = (node: HastNode): boolean => {
 // page, but slug disambiguation must reset per document; the render-scoped
 // `astro` data object is a stable, unique key for one render (entries are
 // dropped once the render is collected, so this never leaks).
-const FALLBACK_SCOPE: object = {};
+const FALLBACK_SCOPE = {};
 const sluggers = new WeakMap<object, GithubSlugger>();
 
 const sluggerFor = (ctx: HastContext): GithubSlugger => {
@@ -77,6 +82,10 @@ const sluggerFor = (ctx: HastContext): GithubSlugger => {
   return slugger;
 };
 
+/** Whether a heading already carries a usable string `id`. */
+const isStringId = (value: HastPropertyValue | undefined): value is string =>
+  typeof value === "string";
+
 /** The slug for a heading, mirroring Satteri's `heading-ids` exactly. */
 const slugFor = (
   node: HastNode,
@@ -86,6 +95,8 @@ const slugFor = (
   const rawText = ctx.textContent(node);
   // `frontmatter`-interpolated MDX headings (`## {frontmatter.title}`) need the
   // resolved value; the helper is the same one `heading-ids` defers to.
+  // SAFETY: HastNode is a structural subset of the hast element shape the
+  // helper walks (children/type/value), so the visited node always fits.
   const text = rawText.includes("frontmatter")
     ? satteriCollectHastText(
         node as Parameters<typeof satteriCollectHastText>[0],
@@ -93,7 +104,7 @@ const slugFor = (
       )
     : rawText;
   const existingId = node.properties?.id;
-  return typeof existingId === "string" ? existingId : slugger.slug(text);
+  return isStringId(existingId) ? existingId : slugger.slug(text);
 };
 
 /** Build the plugin. Wraps `<h2>`–`<h6>` in self-linking anchors. */
@@ -108,7 +119,7 @@ export const headingAnchorPlugin = (): HeadingAnchorPlugin => ({
       if (!wrap) {
         // Unwrapped headings (h1, an empty slug, or one that already links) still
         // need the id so `heading-ids` adopts it instead of re-slugging.
-        if (typeof node.properties?.id !== "string") {
+        if (!isStringId(node.properties?.id)) {
           ctx.setProperty(node, "id", slug);
         }
         return;

package/src/markdown/index.ts

@@ -52,6 +52,28 @@ type HastPlugin = NonNullable<
   NonNullable<Parameters<typeof satteri>[0]>["hastPlugins"]
 >[number];
 
+/*
+ * Blume's plugins model only the node/context slices they touch (no hast or
+ * Satteri type dependency); these bridges are the single boundary where those
+ * minimal structural shapes meet the host pipeline's full plugin types.
+ */
+
+// SAFETY: Satteri drives plugins through the same visitor protocol Blume's
+// minimal structural shapes model; they narrow the node/context types the
+// visitor hooks receive, never widen them.
+const asHastPlugin = (plugin: { name: string }): HastPlugin =>
+  plugin as HastPlugin;
+
+// SAFETY: the same visitor-protocol bridge as `asHastPlugin`, for the mdast
+// phase's plugins.
+const asMdastPlugin = (plugin: { name: string }): MdastPlugin =>
+  plugin as MdastPlugin;
+
+// SAFETY: Shiki calls only the hooks a transformer declares, and Blume's
+// transformers type their hook parameters as the hast slices they touch.
+const asShikiTransformer = (transformer: { name: string }): ShikiTransformer =>
+  transformer as ShikiTransformer;
+
 /**
  * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
  * always on: it only fires on an explicit trailing `{:lang}` marker, so plain
@@ -62,11 +84,11 @@ type HastPlugin = NonNullable<
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
   const plugins: HastPlugin[] = [
-    inlineCodeHighlightPlugin(options.codeThemes) as unknown as HastPlugin,
-    tableWrapPlugin() as unknown as HastPlugin,
+    asHastPlugin(inlineCodeHighlightPlugin(options.codeThemes)),
+    asHastPlugin(tableWrapPlugin()),
   ];
   if (options.headingAnchors !== false) {
-    plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
+    plugins.push(asHastPlugin(headingAnchorPlugin()));
   }
   return plugins;
 };
@@ -101,29 +123,55 @@ export const blumeShikiTransformers = (
     transformerMetaHighlight(),
   ];
   if (options.icons !== false) {
-    transformers.push(languageIconTransformer() as unknown as ShikiTransformer);
+    transformers.push(asShikiTransformer(languageIconTransformer()));
   }
   // The fence-meta reader (title / line numbers) always runs last.
-  transformers.push(codeTitleTransformer() as unknown as ShikiTransformer);
+  transformers.push(asShikiTransformer(codeTitleTransformer()));
   return transformers;
 };
 
+/** The value space of a hast element property. */
+type HastPropertyValue =
+  | string
+  | number
+  | boolean
+  | (string | number)[]
+  | null
+  | undefined;
+
+/** The `<pre>` slice the class/language transformers touch. */
+interface PreElement {
+  properties: { class?: HastPropertyValue; dataLanguage?: HastPropertyValue };
+}
+
+const isStringProperty = (value: HastPropertyValue): value is string =>
+  typeof value === "string";
+
+/** A Blume-local Shiki transformer: a name plus the `pre` hook it declares. */
+interface PreTransformer {
+  name: string;
+  pre: (node: PreElement) => void;
+}
+
 /**
  * Tag the highlighted `<pre>` with `astro-code` (plus any extra classes) so the
  * theme's code-block styles apply — `codeToHtml`'s bare output is `pre.shiki`,
  * which the theme doesn't style.
  */
-const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
-  ({
+const astroCodeClassTransformer = (extra?: string): ShikiTransformer => {
+  const transformer: PreTransformer = {
     name: "blume:astro-code-class",
-    pre(node: { properties: Record<string, unknown> }) {
-      const existing =
-        typeof node.properties.class === "string" ? node.properties.class : "";
+    pre(node) {
+      const existing = isStringProperty(node.properties.class)
+        ? node.properties.class
+        : "";
       node.properties.class = `astro-code ${extra ?? ""} ${existing}`
         .replaceAll(/\s+/gu, " ")
         .trim();
     },
-  }) as unknown as ShikiTransformer;
+  };
+  return asShikiTransformer(transformer);
+};
 
 /**
  * Tag the `<pre>` with `data-language` — raw `codeToHtml` omits it (unlike
@@ -132,13 +180,15 @@ const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
  * fence would, while header-less panes (e.g. the Component source view) stay
  * untouched.
  */
-const languageAttrTransformer = (lang: string): ShikiTransformer =>
-  ({
+const languageAttrTransformer = (lang: string): ShikiTransformer => {
+  const transformer: PreTransformer = {
     name: "blume:data-language",
-    pre(node: { properties: Record<string, unknown> }) {
+    pre(node) {
       node.properties.dataLanguage ??= lang;
     },
-  }) as unknown as ShikiTransformer;
+  };
+  return asShikiTransformer(transformer);
+};
 
 export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
@@ -235,10 +285,9 @@ const blumeSharedMdastPlugins = (
 ): MdastPlugin[] =>
   options.basePath || options.deployBase
     ? [
-        baseLinksPlugin(
-          options.deployBase ?? "",
-          options.basePath ?? ""
-        ) as unknown as MdastPlugin,
+        asMdastPlugin(
+          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
+        ),
       ]
     : [];
 
@@ -278,10 +327,10 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
     },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
-      packageInstallPlugin(),
-      directiveToCalloutPlugin(),
-      mermaidPlugin(),
-      mathPlugin(),
+      asMdastPlugin(packageInstallPlugin()),
+      asMdastPlugin(directiveToCalloutPlugin()),
+      asMdastPlugin(mermaidPlugin()),
+      asMdastPlugin(mathPlugin()),
       ...blumeSharedMdastPlugins(options),
-    ] as unknown as MdastPlugin[],
+    ],
   });

package/src/markdown/inline-code.ts

@@ -15,10 +15,19 @@
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
+/** The value space of a hast element property (mirrors hast's `Properties`). */
+type HastPropertyValue =
+  | string
+  | number
+  | boolean
+  | (string | number)[]
+  | null
+  | undefined;
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;
@@ -71,7 +80,10 @@ type InlineHighlighter = (
 // `import()` caches the module, so this dedupes Shiki across calls on its own.
 const loadHighlighter = async (): Promise<InlineHighlighter> => {
   const mod = await import("shiki");
-  return mod.codeToHast as unknown as InlineHighlighter;
+  // SAFETY: Shiki accepts arbitrary lang/theme strings at runtime (an unknown
+  // one rejects the promise, which the caller catches); only its bundled types
+  // constrain them to known ids, so the loose signature narrows nothing real.
+  return mod.codeToHast as InlineHighlighter;
 };
 
 /** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */

package/src/markdown/language-icon.ts

@@ -55,7 +55,11 @@ interface SimpleIcon {
 }
 
 /** Fence language (and common aliases) → icon. Unmapped languages get none. */
-const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
+interface LanguageIcons {
+  [language: string]: SimpleIcon;
+}
+
+const LANGUAGE_ICONS: LanguageIcons = {
   astro: siAstro,
   bash: siGnubash,
   c: siC,
@@ -119,7 +123,7 @@ const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, boolean | number | string | string[] | undefined>;
   tagName?: string;
   type: string;
   value?: string;

package/src/markdown/mdast.ts

@@ -5,15 +5,29 @@
  * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
  */
 
+/**
+ * A property value on an MDAST node: primitives, nested nodes, and lists of
+ * either. Covers everything Blume's plugins read or build (positions, data
+ * flags, attribute lists) without admitting functions or class instances.
+ */
+export type MdastValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | MdastValue[]
+  | { [key: string]: MdastValue };
+
 /** The visitor context Blume's plugins use to mutate the tree. */
 export interface MdastVisitorContext {
-  replaceNode: (node: unknown, replacement: unknown) => void;
+  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
 }
 
 /** Any MDAST node, keyed loosely since we build a small subset by hand. */
 export interface MdastNode {
   type: string;
-  [key: string]: unknown;
+  [key: string]: MdastValue;
 }
 
 /** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
@@ -29,14 +43,14 @@ type JsxAttribute = ReturnType<typeof jsxAttribute>;
 export const jsxFlowElement = (
   name: string,
   attributes: JsxAttribute[],
-  children: unknown[]
+  children: MdastValue[]
 ) => ({ attributes, children, name, type: "mdxJsxFlowElement" });
 
 /** Build an inline MDX JSX element (phrasing context). */
 export const jsxTextElement = (
   name: string,
   attributes: JsxAttribute[],
-  children: unknown[] = []
+  children: MdastValue[] = []
 ) => ({ attributes, children, name, type: "mdxJsxTextElement" });
 
 /** Build a fenced code block node. */

package/src/markdown/package-commands.ts

@@ -14,12 +14,12 @@ export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
  * (yarnpkg/berry#821), so global installs on the yarn tab honestly render
  * npm's form, matching `ni`'s table.
  */
-const AGENT_FOR: Record<PackageManager, Agent> = {
+const AGENT_FOR = {
   bun: "bun",
   npm: "npm",
   pnpm: "pnpm",
   yarn: "yarn@berry",
-};
+} satisfies Record<PackageManager, Agent>;
 
 /** Words that mark the input as an explicit command rather than a bare list. */
 const MANAGER_PREFIXES = new Set(["bun", "bunx", "npm", "npx", "pnpm", "yarn"]);
@@ -137,14 +137,14 @@ const parseIntent = (input: string): Intent => {
 };
 
 /** The package-manager-detector command for each non-global operation. */
-const COMMAND_FOR: Record<Exclude<Operation, "create">, Command> = {
+const COMMAND_FOR = {
   add: "add",
   ci: "frozen",
   exec: "execute",
   install: "install",
   remove: "uninstall",
   run: "run",
-};
+} satisfies Record<Exclude<Operation, "create">, Command>;
 
 /**
  * Render one manager's command for the given intent, via
@@ -188,9 +188,7 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
  * manager. Accepts a bare package list (`react`) or a full command
  * (`npm i -D typescript`, `npx astro add react`).
  */
-export const toPackageCommands = (
-  input: string
-): Record<PackageManager, string> => {
+export const toPackageCommands = (input: string) => {
   const intent = parseIntent(input);
   const normalize = (command: string): string =>
     command.replaceAll(WHITESPACE_RUN, " ").trim();
@@ -199,5 +197,5 @@ export const toPackageCommands = (
     npm: normalize(buildCommand("npm", intent)),
     pnpm: normalize(buildCommand("pnpm", intent)),
     yarn: normalize(buildCommand("yarn", intent)),
-  };
+  } satisfies Record<PackageManager, string>;
 };

package/src/markdown/table-wrap.ts

@@ -15,10 +15,13 @@
  * containing any non-text content (an image, an icon) counts as non-empty.
  */
 
+/** The value shapes hast allows on an element's `properties`. */
+type HastPropertyValue = string | number | boolean | (string | number)[];
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;

package/src/markdown/twoslash.ts

@@ -38,6 +38,8 @@ const require = createRequire(import.meta.url);
  * never pays the TypeScript parse cost.
  */
 export const blumeTwoslashTransformer = (): ShikiTransformer => {
+  // SAFETY: this resolves Blume's own pinned `typescript` dependency, whose
+  // CJS entry exports exactly the API namespace `typeof TS` describes.
   const tsModule = require("typescript") as typeof TS;
   const twoslasher = createTwoslasher({
     // Match the stock transformer's default: fence snippets are authored