blume 1.4.3 → 1.5.0

package/src/audit/crawl.ts

@@ -103,6 +103,35 @@ const sitemapParser = new XMLParser({
   removeNSPrefix: true,
 });
 
+/**
+ * What fast-xml-parser produces for a parsed element: a string for text
+ * content (`parseTagValue: false`), an object of child elements, an array for
+ * a repeated element, or null for a self-closed one.
+ */
+type XmlValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | XmlValue[]
+  | { [element: string]: XmlValue };
+
+/**
+ * fast-xml-parser models an element with child elements as an object; a
+ * text-only or self-closed element parses to a string or null instead, which
+ * these guards reject the same way the crawler always has.
+ */
+const isUrlsetElement = (value: XmlValue): value is { url?: XmlValue } =>
+  typeof value === "object" && value !== null;
+
+const isUrlEntry = (
+  value: XmlValue
+): value is { lastmod?: XmlValue; loc?: XmlValue } =>
+  typeof value === "object" && value !== null;
+
+const isText = (value: XmlValue): value is string => typeof value === "string";
+
 /**
  * Parse `sitemap.xml`. Deliberately shallow: the checks only need the `<loc>`
  * list, each loc's `<lastmod>`, and whether the document is a urlset at all.
@@ -113,9 +142,9 @@ export const parseSitemap = (
   bytes: number
 ): SitemapDoc => {
   const doc: SitemapDoc = { bytes, file, lastmod: new Map(), urls: [] };
-  let parsed: Record<string, unknown>;
+  let parsed: { sitemapindex?: XmlValue; urlset?: XmlValue };
   try {
-    parsed = sitemapParser.parse(xml) as Record<string, unknown>;
+    parsed = sitemapParser.parse(xml);
   } catch {
     doc.error = "no <urlset> element";
     return doc;
@@ -126,20 +155,19 @@ export const parseSitemap = (
       : "no <urlset> element";
     return doc;
   }
-  const urlset = parsed.urlset as { url?: unknown } | string | null;
-  const entries =
-    typeof urlset === "object" && urlset !== null ? [urlset.url].flat() : [];
+  const { urlset } = parsed;
+  const entries = isUrlsetElement(urlset) ? [urlset.url].flat() : [];
   for (const entry of entries) {
-    if (typeof entry !== "object" || entry === null) {
+    if (!isUrlEntry(entry)) {
       continue;
     }
-    const { loc, lastmod } = entry as { loc?: unknown; lastmod?: unknown };
-    const locText = typeof loc === "string" ? loc.trim() : "";
+    const { loc, lastmod } = entry;
+    const locText = isText(loc) ? loc.trim() : "";
     if (!locText) {
       continue;
     }
     doc.urls.push(locText);
-    if (typeof lastmod === "string" && lastmod.trim() !== "") {
+    if (isText(lastmod) && lastmod.trim() !== "") {
       doc.lastmod?.set(locText, lastmod.trim());
     }
   }

package/src/audit/report.ts

@@ -9,26 +9,26 @@ import type { CheckId } from "./catalog.ts";
 import type { AuditResult } from "./run.ts";
 import type { AuditCategory, AuditTier } from "./types.ts";
 
-const SEVERITY_COLOR: Record<DiagnosticSeverity, ColorFunction> = {
+const SEVERITY_COLOR = {
   error: colors.red,
   info: colors.blue,
   warning: colors.yellow,
-};
+} satisfies Record<DiagnosticSeverity, ColorFunction>;
 
-const GLYPH: Record<DiagnosticSeverity, string> = {
+const GLYPH = {
   error: "✖",
   info: "ℹ",
   warning: "⚠",
-};
+} satisfies Record<DiagnosticSeverity, string>;
 
 /** How many affected pages to list before collapsing the rest. */
 const PREVIEW = 3;
 
-/** The tier a category belongs to, for the "skipped" line. */
-const TIER_FLAG: Partial<Record<AuditTier, string>> = {
-  external: "--external",
-  network: "--url <origin>",
-};
+/** The skippable tiers, each with the flag that runs it. */
+const TIER_FLAGS: { tier: AuditTier; flag: string }[] = [
+  { flag: "--external", tier: "external" },
+  { flag: "--url <origin>", tier: "network" },
+];
 
 interface CheckRollup {
   id: CheckId;
@@ -55,18 +55,21 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
     }
   }
 
-  const order: Record<DiagnosticSeverity, number> = {
+  const order = {
     error: 0,
     info: 2,
     warning: 1,
-  };
+  } satisfies Record<DiagnosticSeverity, number>;
   const checks = [...groups.entries()].map(([id, findings]) => {
-    const { category, severity, title } = checkMeta(id as CheckId);
+    // SAFETY: audit findings are only ever created through `finding()`, whose
+    // codes are the check catalog's ids.
+    const checkId = id as CheckId;
+    const { category, severity, title } = checkMeta(checkId);
     return {
       category,
       count: findings.length,
       findings,
-      id: id as CheckId,
+      id: checkId,
       severity,
       title,
     };
@@ -95,12 +98,10 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
 
 /** Categories that had no findings but were never run, and the flag that runs them. */
 const skippedTiers = (tiers: Record<AuditTier, boolean>): string[] =>
-  (Object.keys(TIER_FLAG) as AuditTier[])
-    .filter((tier) => !tiers[tier])
-    .map((tier) => {
-      const label = CHECKS.filter((check) => check.tier === tier).length;
-      return `  ${colors.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${TIER_FLAG[tier]} (${label} checks)`)}`;
-    });
+  TIER_FLAGS.filter(({ tier }) => !tiers[tier]).map(({ flag, tier }) => {
+    const label = CHECKS.filter((check) => check.tier === tier).length;
+    return `  ${colors.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${flag} (${label} checks)`)}`;
+  });
 
 /** How many checks actually ran, i.e. those whose tier was enabled. */
 const activeChecks = (tiers: Record<AuditTier, boolean>): number =>

package/src/audit/run.ts

@@ -183,11 +183,11 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
     thresholds: DEFAULT_THRESHOLDS,
   };
 
-  const tiers: Record<AuditTier, boolean> = {
+  const tiers = {
     external: Boolean(options.external),
     network: origin !== null,
     static: true,
-  };
+  } satisfies Record<AuditTier, boolean>;
 
   const results = await Promise.all(
     MODULES.filter((module) => tiers[module.tier]).map((module) =>
@@ -197,11 +197,14 @@ 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 ?? [])
     );

package/src/audit/snapshot.ts

@@ -84,9 +84,7 @@ const collectAssets = (
     .filter((asset) => asset.src.length > 0);
 
 /** Parse each JSON-LD block, keeping the parse failures rather than dropping them. */
-const collectJsonLd = (
-  document: HtmlDocument
-): { jsonld: unknown[]; jsonldErrors: string[] } => {
+const collectJsonLd = (document: HtmlDocument) => {
   const jsonld: unknown[] = [];
   const jsonldErrors: string[] = [];
   for (const script of document.querySelectorAll(
@@ -106,7 +104,7 @@ const prefixedMeta = (
   document: HtmlDocument,
   keyAttr: "property" | "name",
   prefix: string
-): Record<string, string> => {
+) => {
   const found: Record<string, string> = {};
   for (const element of document.querySelectorAll(
     `meta[${keyAttr}^="${prefix}"]`

package/src/audit/types.ts

@@ -161,11 +161,32 @@ export interface LinkGraph {
 /** Astro's reserved error routes. Never indexable, never crawlable — by design. */
 export const ERROR_ROUTES: ReadonlySet<string> = new Set(["/404", "/500"]);
 
-/** Tunable limits. Not yet configurable — CLI-only until the ids settle. */
+/**
+ * Tunable limits. Not yet configurable — CLI-only until the ids settle.
+ *
+ * The title and description limits are measured in **display columns**, where
+ * a fullwidth or wide character counts 2 and everything else 1 — not in
+ * characters. What a search engine truncates is the space the text takes up,
+ * and a character count only stands in for that where every character is one
+ * column wide, which is true of Latin text and of nothing else. Counted in
+ * characters one range cannot serve both scripts: it is at once too strict for
+ * a Japanese description (which says in ~60 characters what English needs ~120
+ * for, and so reads as "too short") and too loose for a Japanese title (60
+ * characters render as wide as 120 Latin ones, and truncate). ASCII and
+ * precomposed (NFC) Latin text score identically either way; a decomposed
+ * (NFD) combining mark counts 0 where a character count saw 1. East-Asian
+ * "ambiguous"-width characters (★ ※ ①) count 1 per `string-width`'s default,
+ * though CJK fonts render them fullwidth — resolving that would need the
+ * page's language, which the audit does not thread through yet.
+ */
 export interface AuditThresholds {
+  /** Display columns, not characters. */
   titleMin: number;
+  /** Display columns, not characters. */
   titleMax: number;
+  /** Display columns, not characters. */
   descriptionMin: number;
+  /** Display columns, not characters. */
   descriptionMax: number;
   minWordCount: number;
   maxHtmlBytes: number;
@@ -174,8 +195,9 @@ export interface AuditThresholds {
 }
 
 export const DEFAULT_THRESHOLDS: AuditThresholds = {
-  // Ahrefs' guidance: 110–160 characters. Under ~110 wastes the snippet
-  // space search results give you; over ~160 gets truncated.
+  // Ahrefs' guidance: 110–160. Under ~110 wastes the snippet space search
+  // results give you; over ~160 gets truncated. Stated there in characters of
+  // English, which is the same number of columns.
   descriptionMax: 160,
   descriptionMin: 110,
   maxAssetBytes: 500 * 1024,

package/src/blume-modules.d.ts

@@ -17,7 +17,10 @@ declare module "blume:search-client" {
 
 declare module "blume:ask" {
   /** The generated Ask trigger (see `askComponentTemplate`); empty when Ask is off. */
-  const Ask: (props: Record<string, unknown>) => unknown;
+  // Mirrors the generated `.blume/src/env.d.ts` declaration: the trigger's type
+  // is the AskAI island the enabled template re-exports.
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const Ask: typeof import("./components/islands/AskAI.astro").default;
   export default Ask;
 }
 
@@ -34,6 +37,7 @@ declare module "blume:data" {
 // `tsc` (where the Astro TS plugin isn't active). Not shipped in `dist/types`, so
 // consumers keep Astro's real `.astro` types and get the true prop shapes.
 declare module "*.astro" {
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type, anti-slop/no-unknown-returns -- a wildcard shim spans every `.astro` component, whose prop shapes and render output only Astro's own TS plugin can type
   const component: (props: Record<string, unknown>) => unknown;
   export default component;
 }

package/src/cli/commands/audit.ts

@@ -53,6 +53,9 @@ const launchAgentCode = async (
   try {
     return await launchAgent(cli.bin, prompt);
   } catch (error) {
+    // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+    // ErrnoException, and any other thrown value fails the comparison and
+    // rethrows unchanged.
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
@@ -123,14 +126,16 @@ export const auditCommand = defineCommand({
     }
 
     const root = process.cwd();
-    const gate = (args["fail-on"] ??
-      (args.strict ? "warning" : "error")) as DiagnosticSeverity;
-    if (!SEVERITIES.includes(gate)) {
+    const gateInput = args["fail-on"] ?? (args.strict ? "warning" : "error");
+    const gate = SEVERITIES.find((severity) => severity === gateInput);
+    if (gate === undefined) {
       logger.error(
-        `Invalid --fail-on "${gate}" (use ${SEVERITIES.join(" | ")}).`
+        `Invalid --fail-on "${gateInput}" (use ${SEVERITIES.join(" | ")}).`
       );
       process.exit(1);
     }
+    // SAFETY: AGENTS is a closed record keyed by AgentKind, so its keys are
+    // exactly the agent kinds.
     const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
       (kind) => args[kind]
     );

package/src/cli/commands/build.ts

@@ -64,6 +64,9 @@ import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+const isAdapter = (value: string): value is (typeof ADAPTERS)[number] =>
+  ADAPTERS.some((adapter) => adapter === value);
+
 const BUDGET_JS = "budget-js";
 const BUDGET_CSS = "budget-css";
 
@@ -295,14 +298,13 @@ const emitVercelNegotiation = async (
   if (!existsSync(configPath)) {
     return;
   }
-  const overrides: Record<string, string> = {
-    ...(hasApiCatalog(config)
-      ? { [API_CATALOG_PATH.slice(1)]: API_CATALOG_TYPE }
-      : {}),
-    ...(config.ai.webBotAuth.keys.length > 0
-      ? { [SIGNATURES_DIRECTORY_PATH.slice(1)]: SIGNATURES_DIRECTORY_TYPE }
-      : {}),
-  };
+  const overrides: Record<string, string> = {};
+  if (hasApiCatalog(config)) {
+    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+  }
+  if (config.ai.webBotAuth.keys.length > 0) {
+    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+  }
   // The homepage rewrite serves `/index.md` from the static layer, so its
   // `x-markdown-tokens` estimate has to ride the routing config; the runtime
   // endpoint stamps it on dev/server-rendered responses itself.
@@ -754,7 +756,7 @@ export const buildCommand = defineCommand({
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
     }
-    if (args.adapter && !ADAPTERS.includes(args.adapter as never)) {
+    if (args.adapter && !isAdapter(args.adapter)) {
       logger.error(
         `Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`
       );
@@ -765,8 +767,12 @@ export const buildCommand = defineCommand({
     const project = await prepareProject({
       mode: "build",
       overrides: {
+        // SAFETY: an invalid --adapter exited above; a set flag is an ADAPTERS
+        // member.
         adapter: args.adapter as (typeof ADAPTERS)[number] | undefined,
         base: args.base,
+        // SAFETY: an invalid --output exited above; a set flag is static or
+        // server.
         output: args.output as "server" | "static" | undefined,
       },
       preview: args.preview,

package/src/cli/commands/dev.ts

@@ -185,6 +185,8 @@ export const devCommand = defineCommand({
         reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {
+        // SAFETY: regeneration failures come from the generator and Astro's
+        // server API, which raise Error instances; only the message is shown.
         logger.error(`Regeneration failed: ${(error as Error).message}`);
       }
     }, 80);

package/src/cli/commands/doctor.ts

@@ -23,6 +23,8 @@ const FALLBACK_NODE_RANGE = ">=22.12.0";
  * doctor can never drift from what the package actually declares. */
 const supportedNodeRange = (): string => {
   try {
+    // SAFETY: this parses blume's own package.json; the optional fields cover
+    // an `engines` block going missing, and a bad read falls to the catch.
     const pkg = JSON.parse(
       readFileSync(join(packageRoot(), "package.json"), "utf-8")
     ) as { engines?: { node?: string } };

package/src/cli/commands/eval.ts

@@ -52,6 +52,9 @@ const launchAgentCode = async (
   try {
     return await launchAgent(AGENTS[agent].bin, prompt);
   } catch (error) {
+    // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+    // ErrnoException, and any other thrown value fails the comparison and
+    // rethrows unchanged.
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
@@ -76,9 +79,7 @@ interface EvalFlags {
 }
 
 /** Validate the flag surface, exiting with a message on the first offense. */
-const parseFlags = (
-  args: EvalFlags
-): { agent: AgentKind; threshold: number; timeoutS: number } => {
+const parseFlags = (args: EvalFlags) => {
   if (!isAgentKind(args.agent)) {
     logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
     process.exit(1);
@@ -237,6 +238,9 @@ export const evalCommand = defineCommand({
         logger.error(error.diagnostic.message);
         process.exit(1);
       }
+      // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+      // ErrnoException, and any other thrown value fails the comparison and
+      // falls through to the internal-error report.
       if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
         notInstalled(agent);
       }

package/src/cli/commands/init.ts

@@ -16,11 +16,7 @@ import {
   TEMPLATES,
   validateContentDir,
 } from "../init/scaffold.ts";
-import type {
-  InitAnswers,
-  PackageManager,
-  Template,
-} from "../init/scaffold.ts";
+import type { InitAnswers } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
 /**
@@ -45,6 +41,8 @@ const ejectScaffold = async (
     const steps = [...cd, commands.install, commands.dev];
     logger.box(`Next steps:\n\n  ${steps.join("\n  ")}\n`);
   } catch (error) {
+    // SAFETY: eject and the script rewrite throw Error instances; only the
+    // message is surfaced in the fallback hint.
     logger.warn(
       `Scaffolded, but eject needs the project's dependencies installed to load blume.config.ts: ${(error as Error).message}`
     );
@@ -93,15 +91,17 @@ export const initCommand = defineCommand({
   async run({ args }) {
     const cwd = process.cwd();
 
-    const template = args.template as Template | undefined;
-    if (template !== undefined && !TEMPLATES.includes(template)) {
+    const template = TEMPLATES.find((candidate) => candidate === args.template);
+    if (args.template !== undefined && template === undefined) {
       logger.error(
         `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
       );
       process.exit(1);
     }
-    const pm = args["package-manager"] as PackageManager | undefined;
-    if (pm !== undefined && !PACKAGE_MANAGERS.includes(pm)) {
+    const pm = PACKAGE_MANAGERS.find(
+      (candidate) => candidate === args["package-manager"]
+    );
+    if (args["package-manager"] !== undefined && pm === undefined) {
       logger.error(
         `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
       );

package/src/cli/commands/mcp-stdio.ts

@@ -23,6 +23,9 @@ export const mcpStdioCommand = defineCommand({
     // must go to stderr or the MCP client chokes on the stray line.
     let data: McpData;
     try {
+      // SAFETY: the snapshot is written by `blume eval` itself as
+      // JSON.stringify of an McpData; a hand-mangled file fails the parse and
+      // lands in the catch below.
       data = JSON.parse(await readFile(args.data, "utf-8")) as McpData;
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);

package/src/cli/commands/translate.ts

@@ -47,10 +47,17 @@ interface TranslateFlags {
   timeout?: string;
 }
 
+/** The validated flag surface `parseFlags` hands the command body. */
+interface ParsedTranslateFlags {
+  agent: AgentKind | undefined;
+  concurrency: number;
+  timeoutS: number;
+}
+
 /** Validate the flag surface, exiting with a message on the first offense. */
-const parseFlags = (
-  args: TranslateFlags
-): { agent: AgentKind | undefined; concurrency: number; timeoutS: number } => {
+const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
+  // SAFETY: Object.keys of the AGENTS table returns exactly its declared
+  // AgentKind keys.
   const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
     (kind) => args[kind]
   );
@@ -227,6 +234,8 @@ export const translateCommand = defineCommand({
         return;
       }
 
+      // SAFETY: parseFlags exits unless --check was passed or exactly one
+      // agent flag was; on this non-check path the agent is therefore set.
       const kind = agent as AgentKind;
       process.stderr.write(
         `${translateHeaderLine(workList.items.length, workList.targetLocales.length, kind)}\n\n`
@@ -290,6 +299,8 @@ export const translateCommand = defineCommand({
         logger.error(error.diagnostic.message);
         process.exit(1);
       }
+      // SAFETY: an ENOENT from spawning the agent CLI is an ErrnoException;
+      // any other thrown shape reads `code` as undefined and falls through.
       if ((error as NodeJS.ErrnoException)?.code === "ENOENT" && agent) {
         notInstalled(agent);
       }

package/src/cli/commands/version.ts

@@ -0,0 +1,85 @@
+import { defineCommand } from "citty";
+
+import { loadConfig } from "../../core/config.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { CutError, cutVersion } from "../../core/version-cut.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger } from "../log.ts";
+
+export const versionCommand = defineCommand({
+  args: {
+    force: {
+      description: "Overwrite an existing snapshot directory.",
+      type: "boolean",
+    },
+    id: {
+      description: 'Version id to cut (e.g. "v1.0").',
+      required: false,
+      type: "positional",
+    },
+  },
+  meta: {
+    description: "Freeze the current docs as an archived version.",
+    name: "version",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+
+    if (!args.id) {
+      const { config } = await loadConfig(root);
+      if (!config.versions) {
+        logger.info(
+          "Versioning is not configured. Cut the first version with `blume version <id>` (e.g. `blume version v1.0`)."
+        );
+        return;
+      }
+      const { current, archived } = config.versions;
+      process.stdout.write(
+        `  ${current.label} (current)${current.badge ? ` — ${current.badge}` : ""}\n`
+      );
+      for (const version of archived) {
+        process.stdout.write(
+          `  ${version.label ?? version.id} — ${version.id}/\n`
+        );
+      }
+      return;
+    }
+
+    try {
+      const result = await cutVersion(root, args.id, { force: args.force });
+      logger.success(
+        `Snapshot ${result.dir} (${result.copied} file(s) copied)`
+      );
+      const totalRewrites = result.rewritten.reduce(
+        (sum, entry) => sum + entry.count,
+        0
+      );
+      if (totalRewrites > 0) {
+        logger.info(
+          `Rewrote root-absolute links in ${result.rewritten.length} page(s) (${totalRewrites} line(s)).`
+        );
+      }
+      if (result.configUpdated) {
+        logger.success(
+          `Added "${args.id}" to versions.archived in blume.config.ts`
+        );
+      } else if (result.configSnippet) {
+        logger.info(result.configSnippet);
+      }
+      logger.info(
+        "Archived versions are frozen — future edits belong in the live tree. Restart `blume dev` to pick up the snapshot."
+      );
+    } catch (error) {
+      if (error instanceof CutError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});