blume 1.4.2 → 1.5.0

package/src/audit/checks/social.ts

@@ -89,6 +89,18 @@ export const socialChecks: CheckModule = {
   tier: "static",
 };
 
+/** The JSON-LD keywords the audit reads off a parsed block. */
+interface JsonLdNode {
+  "@context"?: unknown;
+  "@graph"?: unknown;
+  "@type"?: unknown;
+}
+
+/** Whether one parsed JSON-LD value is an object the keyword checks can read. */
+const isJsonLdNode = (
+  value: PageSnapshot["jsonld"][number]
+): value is JsonLdNode => typeof value === "object" && value !== null;
+
 /**
  * What's missing from one JSON-LD block.
  *
@@ -98,28 +110,24 @@ export const socialChecks: CheckModule = {
  * and each entry carries its own `@type` — so demanding `@type` on the root, or
  * `@context` on each entry, would flag perfectly valid structured data.
  */
-const jsonLdProblems = (node: unknown): string[] => {
-  if (typeof node !== "object" || node === null) {
+const jsonLdProblems = (node: PageSnapshot["jsonld"][number]): string[] => {
+  if (!isJsonLdNode(node)) {
     return ["it is not an object"];
   }
-  const record = node as Record<string, unknown>;
   const problems: string[] = [];
-  if (!record["@context"]) {
+  if (!node["@context"]) {
     problems.push("@context");
   }
 
-  const graph = record["@graph"];
+  const graph = node["@graph"];
   if (Array.isArray(graph)) {
     const untyped = graph.filter(
-      (entry) =>
-        typeof entry !== "object" ||
-        entry === null ||
-        !(entry as Record<string, unknown>)["@type"]
+      (entry) => !isJsonLdNode(entry) || !entry["@type"]
     ).length;
     if (untyped > 0) {
       problems.push(`@type on ${untyped} of its ${graph.length} @graph nodes`);
     }
-  } else if (!record["@type"]) {
+  } else if (!node["@type"]) {
     problems.push("@type");
   }
 

package/src/audit/crawl.ts

@@ -1,6 +1,9 @@
 import { readFile, stat } from "node:fs/promises";
 
 import { XMLParser } from "fast-xml-parser";
+import type { Nodes } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import pMap from "p-map";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -18,6 +21,13 @@ import type { LlmsDoc, PageSnapshot, RobotsDoc, SitemapDoc } from "./types.ts";
  */
 const EXAMPLES_PREFIX = `${examplesRouteBase("")}/`;
 
+/**
+ * Ceiling on concurrent file reads/stats while crawling. Unbounded fan-out
+ * over a large `dist` risks EMFILE and holds every page's HTML in memory at
+ * once.
+ */
+const CRAWL_CONCURRENCY = 16;
+
 /** Everything read off disk in one pass over the built site. */
 export interface CrawlResult {
   pages: PageSnapshot[];
@@ -45,12 +55,14 @@ export const fileToUrl = (staticDir: string, file: string): string => {
  */
 const indexFiles = async (staticDir: string): Promise<Map<string, number>> => {
   const found = await glob("**/*", { cwd: staticDir, dot: true });
-  const sized = await Promise.all(
-    found.map(async (file) => {
+  const sized = await pMap(
+    found,
+    async (file) => {
       const path = `/${file.replaceAll("\\", "/")}`;
       const info = await stat(join(staticDir, file));
       return [path, info.size] as const;
-    })
+    },
+    { concurrency: CRAWL_CONCURRENCY }
   );
   return new Map(sized);
 };
@@ -91,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.
@@ -101,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;
@@ -114,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());
     }
   }
@@ -135,21 +175,32 @@ export const parseSitemap = (
 };
 
 /**
- * Parse the `llms.txt` index into its Markdown link targets. Deliberately
- * shallow, like {@link parseSitemap}: the checks only need "which pages does
- * this file claim exist", not a Markdown AST.
+ * Parse the `llms.txt` index into its Markdown link targets, with the line
+ * each target sits on so findings can point at it. A real parse rather than a
+ * `](url)` regex: angle-bracket destinations, link titles, reference-style
+ * links (the definition line carries the URL), and autolinks all resolve, and
+ * a link-shaped string inside a fenced code block is no longer reported as a
+ * claim. Blume's own llms.txt only emits inline links, but the file is also
+ * hand-edited.
  */
 export const parseLlms = (file: string, text: string): LlmsDoc => {
   const entries: LlmsDoc["entries"] = [];
-  const link = /\]\((?<url>[^)\s]+)\)/gu;
-  for (const [index, line] of text.split(/\r?\n/u).entries()) {
-    for (const match of line.matchAll(link)) {
-      const url = match.groups?.url;
-      if (url) {
-        entries.push({ line: index + 1, url });
+  const collect = (node: Nodes): void => {
+    if (
+      (node.type === "link" ||
+        node.type === "image" ||
+        node.type === "definition") &&
+      node.url
+    ) {
+      entries.push({ line: node.position?.start.line ?? 1, url: node.url });
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        collect(child);
       }
     }
-  }
+  };
+  collect(fromMarkdown(text));
   return { entries, file };
 };
 
@@ -214,8 +265,9 @@ export const crawlStaticDir = async (options: {
   const routes = routeIndex(manifest, basePath);
 
   const htmlFiles = await glob("**/*.html", { absolute: true, cwd: staticDir });
-  const snapshots = await Promise.all(
-    htmlFiles.toSorted().map(async (file) => {
+  const snapshots = await pMap(
+    htmlFiles.toSorted(),
+    async (file) => {
       const url = fileToUrl(staticDir, file);
       if (stripBasePath(basePath, url).startsWith(EXAMPLES_PREFIX)) {
         return null;
@@ -230,7 +282,8 @@ export const crawlStaticDir = async (options: {
         route: routes.get(url) ?? routes.get(stripBasePath(basePath, url)),
         url,
       });
-    })
+    },
+    { concurrency: CRAWL_CONCURRENCY }
   );
   const pages = snapshots.filter((page) => page !== null);
 

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

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
+
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
@@ -88,6 +90,9 @@ export class NoBuildError extends Error {
   }
 }
 
+/** Ceiling on concurrent source reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 /** Read every page's source file once, so findings can cite front matter lines. */
 const readSources = async (
   pages: PageSnapshot[]
@@ -95,8 +100,9 @@ const readSources = async (
   const paths = [
     ...new Set(pages.flatMap((page) => (page.source ? [page.source] : []))),
   ];
-  const entries = await Promise.all(
-    paths.map(async (path) => {
+  const entries = await pMap(
+    paths,
+    async (path) => {
       try {
         return [path, await readFile(path, "utf-8")] as const;
       } catch {
@@ -104,7 +110,8 @@ const readSources = async (
         // still names the URL; it just can't cite a line.
         return null;
       }
-    })
+    },
+    { concurrency: READ_CONCURRENCY }
   );
   return new Map(entries.filter((entry) => entry !== null));
 };
@@ -176,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) =>
@@ -190,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

@@ -8,6 +8,30 @@ import type { PageSnapshot, SnapshotAsset, SnapshotLink } from "./types.ts";
 /** Site chrome: links here are navigation, not editorial. */
 const CHROME = "nav, aside, header, footer";
 
+/**
+ * Count prose words with `Intl.Segmenter`, seeded with the page's declared
+ * language. The whitespace split this replaces counted a fully written
+ * Japanese or Chinese page — scripts with no interword spaces — as a handful
+ * of "words", tripping BLUME_AUDIT_LOW_WORD_COUNT on every page of a CJK
+ * site. An unparseable `lang` attribute falls back to the default locale
+ * rather than failing the crawl.
+ */
+const countWords = (prose: string, lang: string | null): number => {
+  let segmenter: Intl.Segmenter;
+  try {
+    segmenter = new Intl.Segmenter(lang ?? undefined, { granularity: "word" });
+  } catch {
+    segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  }
+  let count = 0;
+  for (const segment of segmenter.segment(prose)) {
+    if (segment.isWordLike) {
+      count += 1;
+    }
+  }
+  return count;
+};
+
 /** Where a page's prose lives, in preference order. */
 const CONTENT_ROOTS = ["main", "article", "body"];
 
@@ -60,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(
@@ -82,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}"]`
@@ -123,6 +145,7 @@ export const buildSnapshot = (options: {
   const root = contentRoot(document);
   const prose = root ? visibleText(root) : "";
   const robots = document.querySelector('meta[name="robots"]');
+  const lang = attr(document.querySelector("html") ?? document, "lang");
   const { jsonld, jsonldErrors } = collectJsonLd(document);
 
   return {
@@ -160,7 +183,7 @@ export const buildSnapshot = (options: {
     indexable: !robots?.getAttribute("content")?.includes("noindex"),
     jsonld,
     jsonldErrors,
-    lang: attr(document.querySelector("html") ?? document, "lang"),
+    lang,
     links,
     metaRefresh:
       document
@@ -184,6 +207,6 @@ export const buildSnapshot = (options: {
         .querySelector('meta[name="viewport"]')
         ?.getAttribute("content")
         ?.trim() ?? null,
-    wordCount: prose ? prose.split(/\s+/u).length : 0,
+    wordCount: countWords(prose, lang),
   };
 };

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

@@ -4,7 +4,6 @@ import {
   AGENTS,
   fixPrompt,
   launchAgent,
-  WINDOWS_COMMAND_NOT_FOUND,
   writeAgentReport,
 } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
@@ -41,22 +40,29 @@ export const shouldFail = (
 };
 
 /**
- * Launch the agent CLI, translating a missing executable into the Windows
- * not-found sentinel. Only `ENOENT` means "not installed" — any other spawn
- * failure (`EACCES`, `EMFILE`, …) must surface as itself, not be masked by an
- * irrelevant install hint.
+ * Launch the agent CLI, turning a missing executable into the install hint.
+ * Only `ENOENT` means "not installed" — any other spawn failure (`EACCES`,
+ * `EMFILE`, …) must surface as itself, not be masked by an irrelevant
+ * install hint.
  */
 const launchAgentCode = async (
-  bin: string,
+  agent: AgentKind,
   prompt: string
 ): Promise<number> => {
+  const cli = AGENTS[agent];
   try {
-    return await launchAgent(bin, prompt);
+    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;
     }
-    return WINDOWS_COMMAND_NOT_FOUND;
+    logger.error(
+      `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+    );
+    return process.exit(1);
   }
 };
 
@@ -120,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]
     );
@@ -183,15 +191,7 @@ export const auditCommand = defineCommand({
       process.stderr.write(
         `  Handing ${count} finding${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
       );
-      const code = await launchAgentCode(cli.bin, fixPrompt(report));
-      // A POSIX spawn rejects on a missing executable; the Windows shell
-      // launch reports it through cmd.exe's 9009 instead. Same diagnosis.
-      if (code === WINDOWS_COMMAND_NOT_FOUND) {
-        logger.error(
-          `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
-        );
-        process.exit(1);
-      }
+      const code = await launchAgentCode(agent, fixPrompt(report));
       if (code !== 0) {
         process.exit(code);
       }