blume 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -90,23 +90,39 @@
     "ai": "^7.0.42",
     "astro": "^7.0.2",
     "babel-plugin-react-compiler": "^1.0.0",
+    "chokidar": "^5.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
     "dompurify": "^3.4.11",
+    "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
+    "fast-xml-parser": "^5.10.1",
+    "get-tsconfig": "^4.14.1",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
+    "html-escaper": "^3.0.3",
+    "image-size": "^2.0.2",
     "jiti": "^2.4.0",
     "js-yaml": "^4.1.0",
     "katex": "^0.18.1",
+    "markdown-table": "^3.0.4",
     "marked": "^18.0.5",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-string": "^4.0.0",
+    "medium-zoom": "^1.1.0",
     "mermaid": "^11.15.0",
+    "micromark-extension-gfm": "^3.0.0",
     "node-html-parser": "^9.0.0",
+    "openapi-sampler": "^1.7.4",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",
+    "picomatch": "^4.0.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "robots-parser": "^3.0.1",
     "satteri": "^0.9.5",
+    "semver": "^7.8.5",
     "sharp": "^0.35.3",
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
@@ -116,13 +132,18 @@
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",
+    "write-file-atomic": "^8.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/html-escaper": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.0",
+    "@types/picomatch": "^4.0.3",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/semver": "^7.8.0",
+    "@types/write-file-atomic": "^4.0.3",
     "@typescript/native-preview": "^7.0.0-dev.20260626.1",
     "bun-types": "^1.3.14"
   },

package/src/ai/component-markdown.ts

@@ -1,3 +1,4 @@
+import { markdownTable } from "markdown-table";
 import { mdxToMdast } from "satteri";
 
 import { parseYouTubeId } from "../components/content/youtube.ts";
@@ -238,15 +239,15 @@ const typeTable: ComponentMarkdown = ({ children, props }) => {
         .filter((part) => typeof part === "string" && part !== "")
         .join(" ")
     );
-    return `| ${prop} | ${typeCell} | ${defaultCell} | ${description} |`;
+    return [prop, typeCell, defaultCell, description];
   });
   const table =
     rows.length > 0
-      ? [
-          "| Prop | Type | Default | Description |",
-          "| --- | --- | --- | --- |",
-          ...rows,
-        ].join("\n")
+      ? markdownTable([["Prop", "Type", "Default", "Description"], ...rows], {
+          // Unpadded columns: cells hold prose and the output is for model
+          // consumption, so aligned delimiter rows are wasted tokens.
+          alignDelimiters: false,
+        })
       : "";
   // The component renders its slot after the table.
   return [table, children].filter(Boolean).join("\n\n");

package/src/astro/generate.ts

@@ -6,10 +6,8 @@ import {
   readFile,
   readlink,
   realpath,
-  rename,
   rm,
   symlink,
-  writeFile,
 } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
@@ -33,6 +31,7 @@ import type {
   BlumeLogo,
 } from "../core/data.ts";
 import { BlumeError } from "../core/diagnostics.ts";
+import { writeTextAtomic } from "../core/fs-atomic.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
 import {
@@ -762,17 +761,9 @@ const writeIfChanged = async (
   if (existing === content) {
     return false;
   }
-  await mkdir(dirname(path), { recursive: true });
-  // Write to a temp file then atomically rename into place, so a watching dev
-  // server never observes a missing or half-written file mid-regeneration.
-  const tmp = `${path}.${process.pid}.tmp`;
-  await writeFile(tmp, content, "utf-8");
-  try {
-    await rename(tmp, path);
-  } catch (error) {
-    await rm(tmp, { force: true });
-    throw error;
-  }
+  // Atomic temp-write + rename, so a watching dev server never observes a
+  // missing or half-written file mid-regeneration.
+  await writeTextAtomic(path, content);
   return true;
 };
 

package/src/astro/islands.ts

@@ -83,7 +83,10 @@ export const discoverIslands = async (
   root: string
 ): Promise<IslandDiscovery> => {
   const dir = join(root, "islands");
-  const matches = await glob(["**/*.{jsx,svelte,tsx,vue}"], {
+  // Enumerate everything and let ISLAND_FILE do the filtering below, so
+  // unknown extensions take the skip guard instead of relying on a glob
+  // pattern staying in sync with the regex and framework map.
+  const matches = await glob(["**/*"], {
     absolute: true,
     cwd: dir,
     onlyFiles: true,

package/src/astro/templates.ts

@@ -1127,10 +1127,9 @@ export const searchClientTemplate = (config: ResolvedConfig): string => {
   if (search.provider === "orama" || search.provider === "flexsearch") {
     // Only Orama derives a tokenizer from the locale; FlexSearch has no
     // equivalent hook, so its client keeps the bare index URL.
-    return staticSearchClient(
-      search.provider,
-      search.provider === "orama" ? config.i18n?.defaultLocale : undefined
-    );
+    const locale =
+      search.provider === "orama" ? config.i18n?.defaultLocale : undefined;
+    return staticSearchClient(search.provider, locale);
   }
 
   const hosted = hostedSearchOptions(search);

package/src/audit/checks/indexability.ts

@@ -8,12 +8,9 @@ import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { decodePath, normalizePath, siteOrigin } from "../url.ts";
 
 /** The canonical URL parsed, or null when it isn't a usable absolute URL. */
-const parseCanonical = (page: PageSnapshot): URL | null => {
-  if (!page.canonical) {
-    return null;
-  }
+const parseCanonical = (canonical: string): URL | null => {
   try {
-    return new URL(page.canonical);
+    return new URL(canonical);
   } catch {
     return null;
   }
@@ -48,7 +45,7 @@ const canonicalChecks = (
       : [];
   }
 
-  const canonical = parseCanonical(page);
+  const canonical = parseCanonical(page.canonical);
   if (!canonical) {
     return [
       finding(

package/src/audit/checks/robots.ts

@@ -1,40 +1,16 @@
+import robotsParser from "robots-parser";
+
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import type { CheckModule } from "../types.ts";
 import { normalizePath } from "../url.ts";
 
 /**
- * Whether a robots.txt `Disallow` value covers a path. robots.txt matching is
- * prefix-based, with `*` as a wildcard and `$` anchoring the end.
+ * robots-parser needs full URLs on a single origin; the origin itself is
+ * irrelevant to path matching, so a fixed placeholder keeps the check
+ * independent of whether the project configured `deployment.site`.
  */
-export const disallowMatches = (rule: string, path: string): boolean => {
-  const anchored = rule.endsWith("$");
-  const pattern = anchored ? rule.slice(0, -1) : rule;
-  const parts = pattern.split("*");
-
-  let cursor = 0;
-  for (const [index, part] of parts.entries()) {
-    if (part === "") {
-      continue;
-    }
-    // The first segment is anchored to the start of the path (robots.txt rules
-    // are prefix matches); every later segment may appear anywhere after the
-    // previous one, which is what makes `*` a wildcard.
-    let at: number;
-    if (index === 0) {
-      at = path.startsWith(part) ? 0 : -1;
-    } else {
-      at = path.indexOf(part, cursor);
-    }
-    if (at === -1) {
-      return false;
-    }
-    cursor = at + part.length;
-  }
-  // A wildcard just before `$` (`/docs*$`) absorbs the rest of the path, so
-  // the anchor is already satisfied by any prefix match.
-  return anchored && !pattern.endsWith("*") ? cursor === path.length : true;
-};
+const MATCH_ORIGIN = "https://robots-audit.invalid";
 
 /**
  * robots.txt: is it there, is it well-formed, does it point at the sitemap, and
@@ -82,8 +58,13 @@ export const robotsChecks: CheckModule = {
     }
 
     // A page can't be both blocked from crawling and advertised for indexing.
-    // Checking the disallow rules against the sitemap (rather than against every
-    // built file) keeps this to the pages the site actually wants indexed.
+    // Checking the rules against the sitemap (rather than against every built
+    // file) keeps this to the pages the site actually wants indexed.
+    // robots-parser resolves Allow/Disallow by longest match, so the common
+    // `Disallow: /` + `Allow: /docs/` pattern doesn't flag every page, and
+    // consecutive User-agent lines form one group as the spec requires.
+    const parser = robotsParser(`${MATCH_ORIGIN}/robots.txt`, robots.raw);
+    const lines = robots.raw.split(/\r?\n/u);
     for (const loc of context.sitemap?.urls ?? []) {
       let pathname: string;
       try {
@@ -94,15 +75,15 @@ export const robotsChecks: CheckModule = {
       // Match the pathname as served: robots.txt rules are literal prefixes,
       // so `Disallow: /page/` must see the trailing slash to match.
       const path = normalizePath(pathname);
-      const rule = robots.disallow.find((entry) =>
-        disallowMatches(entry, pathname)
-      );
-      if (rule) {
+      const url = `${MATCH_ORIGIN}${pathname}`;
+      if (parser.isDisallowed(url, "*")) {
+        const line = parser.getMatchingLineNumber(url, "*");
+        const rule = line > 0 ? lines[line - 1]?.trim() : undefined;
         found.push(
           finding(
             "BLUME_AUDIT_ROBOTS_DISALLOWS_INDEXABLE",
             { file: robots.file, url: path },
-            `robots.txt "Disallow: ${rule}" blocks ${path}, which sitemap.xml advertises.`
+            `robots.txt "${rule ?? "Disallow"}" blocks ${path}, which sitemap.xml advertises.`
           )
         );
       }

package/src/audit/crawl.ts

@@ -1,5 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 
+import { XMLParser } from "fast-xml-parser";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -74,27 +75,25 @@ const routeIndex = (
   return index;
 };
 
-const SITEMAP_URL = /<url>(?<block>[\s\S]*?)<\/url>/gu;
-const SITEMAP_LOC = /<loc>(?<loc>[\s\S]*?)<\/loc>/gu;
-const SITEMAP_LASTMOD = /<lastmod>(?<date>[\s\S]*?)<\/lastmod>/u;
-const XML_ENTITIES: Record<string, string> = {
-  "&amp;": "&",
-  "&apos;": "'",
-  "&gt;": ">",
-  "&lt;": "<",
-  "&quot;": '"',
-};
-
-const unescapeXml = (value: string): string =>
-  value.replaceAll(
-    /&(?:amp|apos|gt|lt|quot);/gu,
-    (entity) => XML_ENTITIES[entity] ?? entity
-  );
+/**
+ * Sitemaps arrive from arbitrary generators (the audit also fetches remote
+ * ones), so parsing is fast-xml-parser's job: CDATA sections, numeric
+ * entities, and namespace-prefixed elements are all legal there and all
+ * invisible to a regex scan. Values stay strings (`parseTagValue: false`) so
+ * a numeric-looking `<lastmod>` isn't coerced.
+ */
+const sitemapParser = new XMLParser({
+  // htmlEntities adds numeric character references (&#38;) on top of the
+  // default XML five; a sitemap loc legitimately carries either form.
+  htmlEntities: true,
+  ignoreAttributes: true,
+  parseTagValue: false,
+  removeNSPrefix: true,
+});
 
 /**
- * Parse `sitemap.xml`. Deliberately shallow: we only need the `<loc>` list and
- * whether the document is a well-formed urlset, and pulling in an XML parser to
- * learn that would be a dependency for one regex.
+ * 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.
  */
 export const parseSitemap = (
   file: string,
@@ -102,31 +101,34 @@ export const parseSitemap = (
   bytes: number
 ): SitemapDoc => {
   const doc: SitemapDoc = { bytes, file, lastmod: new Map(), urls: [] };
-  if (!xml.includes("<urlset")) {
-    doc.error = xml.includes("<sitemapindex")
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = sitemapParser.parse(xml) as Record<string, unknown>;
+  } catch {
+    doc.error = "no <urlset> element";
+    return doc;
+  }
+  if (!Object.hasOwn(parsed, "urlset")) {
+    doc.error = Object.hasOwn(parsed, "sitemapindex")
       ? "sitemap is an index, not a urlset"
       : "no <urlset> element";
     return doc;
   }
-  for (const match of xml.matchAll(SITEMAP_LOC)) {
-    const loc = unescapeXml((match.groups?.loc ?? "").trim());
-    if (loc) {
-      doc.urls.push(loc);
+  const urlset = parsed.urlset as { url?: unknown } | string | null;
+  const entries =
+    typeof urlset === "object" && urlset !== null ? [urlset.url].flat() : [];
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
     }
-  }
-  // `<lastmod>` is scoped per `<url>` block so it stays attached to its `<loc>`
-  // — the flat loc scan above deliberately isn't, so a sitemap with stray text
-  // between blocks still yields its URL list.
-  for (const match of xml.matchAll(SITEMAP_URL)) {
-    const block = match.groups?.block ?? "";
-    const loc = unescapeXml(
-      (
-        new RegExp(SITEMAP_LOC.source, "u").exec(block)?.groups?.loc ?? ""
-      ).trim()
-    );
-    const lastmod = SITEMAP_LASTMOD.exec(block)?.groups?.date?.trim();
-    if (loc && lastmod) {
-      doc.lastmod?.set(loc, lastmod);
+    const { loc, lastmod } = entry as { loc?: unknown; lastmod?: unknown };
+    const locText = typeof loc === "string" ? loc.trim() : "";
+    if (!locText) {
+      continue;
+    }
+    doc.urls.push(locText);
+    if (typeof lastmod === "string" && lastmod.trim() !== "") {
+      doc.lastmod?.set(locText, lastmod.trim());
     }
   }
   return doc;
@@ -153,12 +155,14 @@ export const parseLlms = (file: string, text: string): LlmsDoc => {
 
 const ROBOTS_DIRECTIVE = /^(?<field>[a-z-]+)\s*:\s*(?<value>.*)$/iu;
 
-/** Parse `robots.txt` into the directives the audit cares about. */
+/**
+ * Parse `robots.txt` into the pieces the audit cares about. Sitemap
+ * declarations and a not-a-directive lint come from a line scan; rule
+ * *matching* is robots-parser's job at check time (see `checks/robots.ts`),
+ * so the raw text rides along instead of a pre-extracted rule list.
+ */
 export const parseRobots = (file: string, text: string): RobotsDoc => {
-  const doc: RobotsDoc = { disallow: [], file, invalid: [], sitemaps: [] };
-  // Only `User-agent: *` rules bind the crawlers we're auditing for; a block
-  // scoped to some other agent isn't a finding about our indexable pages.
-  let appliesToAll = false;
+  const doc: RobotsDoc = { file, invalid: [], raw: text, sitemaps: [] };
   for (const [index, raw] of text.split(/\r?\n/u).entries()) {
     const line = raw.trim();
     if (line === "" || line.startsWith("#")) {
@@ -171,11 +175,7 @@ export const parseRobots = (file: string, text: string): RobotsDoc => {
     }
     const field = (match.groups?.field ?? "").toLowerCase();
     const value = (match.groups?.value ?? "").trim();
-    if (field === "user-agent") {
-      appliesToAll = value === "*";
-    } else if (field === "disallow" && appliesToAll && value) {
-      doc.disallow.push(value);
-    } else if (field === "sitemap" && value) {
+    if (field === "sitemap" && value) {
       doc.sitemaps.push(value);
     }
   }

package/src/audit/image-size.ts

@@ -1,63 +1,23 @@
+import { imageSize as measureImage } from "image-size";
+
 /**
- * Pixel dimensions read straight from a PNG, JPEG, or GIF header. A dedicated
- * image library would be a dependency for three well-documented byte layouts;
- * anything else (SVG, WebP, AVIF) yields null and its checks simply don't run.
+ * Pixel dimensions read from an image header via the image-size package,
+ * which covers the formats a modern pipeline actually emits — WebP and AVIF
+ * included, where the previous hand parser (PNG/JPEG/GIF only) went silent
+ * and the dimension checks never ran. An unrecognized or truncated buffer
+ * yields null and its checks simply don't run.
  */
 export interface ImageSize {
   width: number;
   height: number;
 }
 
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-
-const pngSize = (bytes: Buffer): ImageSize | null => {
-  // Signature, then the IHDR chunk is required to come first: width and height
-  // are big-endian u32s at fixed offsets 16 and 20.
-  if (bytes.length < 24 || !bytes.subarray(0, 4).equals(PNG_SIGNATURE)) {
-    return null;
-  }
-  return { height: bytes.readUInt32BE(20), width: bytes.readUInt32BE(16) };
-};
-
-/** JPEG start-of-frame markers (C0–CF minus DHT C4, JPG C8, DAC CC). */
-const isSof = (marker: number): boolean =>
-  marker >= 0xc0 &&
-  marker <= 0xcf &&
-  marker !== 0xc4 &&
-  marker !== 0xc8 &&
-  marker !== 0xcc;
-
-const jpegSize = (bytes: Buffer): ImageSize | null => {
-  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) {
-    return null;
-  }
-  // Walk the segment list: each is FF <marker> <u16 length> <payload>. The
-  // dimensions live in the first start-of-frame segment's payload, as
-  // big-endian u16s after a one-byte precision field.
-  let offset = 2;
-  while (offset + 9 < bytes.length) {
-    if (bytes[offset] !== 0xff) {
-      return null;
-    }
-    const marker = bytes[offset + 1] ?? 0;
-    if (isSof(marker)) {
-      return {
-        height: bytes.readUInt16BE(offset + 5),
-        width: bytes.readUInt16BE(offset + 7),
-      };
-    }
-    offset += 2 + bytes.readUInt16BE(offset + 2);
-  }
-  return null;
-};
-
-const gifSize = (bytes: Buffer): ImageSize | null => {
-  if (bytes.length < 10 || bytes.subarray(0, 4).toString("latin1") !== "GIF8") {
+/** The image's pixel dimensions, or null when the format isn't recognized. */
+export const imageSize = (bytes: Buffer): ImageSize | null => {
+  try {
+    const { width, height } = measureImage(bytes);
+    return width > 0 && height > 0 ? { height, width } : null;
+  } catch {
     return null;
   }
-  return { height: bytes.readUInt16LE(8), width: bytes.readUInt16LE(6) };
 };
-
-/** The image's pixel dimensions, or null when the format isn't recognized. */
-export const imageSize = (bytes: Buffer): ImageSize | null =>
-  pngSize(bytes) ?? jpegSize(bytes) ?? gifSize(bytes);

package/src/audit/report.ts

@@ -1,3 +1,5 @@
+import { colors } from "consola/utils";
+import type { ColorFunction } from "consola/utils";
 import { relative } from "pathe";
 
 import { countBySeverity } from "../core/diagnostics.ts";
@@ -7,21 +9,10 @@ import type { CheckId } from "./catalog.ts";
 import type { AuditResult } from "./run.ts";
 import type { AuditCategory, AuditTier } from "./types.ts";
 
-const ESC = String.fromCodePoint(27);
-const COLORS = {
-  bold: `${ESC}[1m`,
-  cyan: `${ESC}[36m`,
-  dim: `${ESC}[2m`,
-  green: `${ESC}[32m`,
-  red: `${ESC}[31m`,
-  reset: `${ESC}[0m`,
-  yellow: `${ESC}[33m`,
-};
-
-const SEVERITY_COLOR: Record<DiagnosticSeverity, string> = {
-  error: COLORS.red,
-  info: `${ESC}[34m`,
-  warning: COLORS.yellow,
+const SEVERITY_COLOR: Record<DiagnosticSeverity, ColorFunction> = {
+  error: colors.red,
+  info: colors.blue,
+  warning: colors.yellow,
 };
 
 const GLYPH: Record<DiagnosticSeverity, string> = {
@@ -108,7 +99,7 @@ const skippedTiers = (tiers: Record<AuditTier, boolean>): string[] =>
     .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)${COLORS.reset}`;
+      return `  ${colors.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${TIER_FLAG[tier]} (${label} checks)`)}`;
     });
 
 /** How many checks actually ran, i.e. those whose tier was enabled. */
@@ -138,9 +129,11 @@ const summaryLine = (
 const findingLine = (diagnostic: Diagnostic, root: string): string => {
   const url = diagnostic.url ?? "";
   const source = diagnostic.file
-    ? `${COLORS.dim}${relative(root, diagnostic.file)}${
-        diagnostic.line === undefined ? "" : `:${diagnostic.line}`
-      }${COLORS.reset}`
+    ? colors.dim(
+        `${relative(root, diagnostic.file)}${
+          diagnostic.line === undefined ? "" : `:${diagnostic.line}`
+        }`
+      )
     : "";
   // padEnd alone yields no gap once the URL reaches the column width.
   return `      ${url.padEnd(34)} ${source}`.trimEnd();
@@ -164,13 +157,13 @@ export const formatReport = (
     : `${relative(root, result.staticDir) || "dist"} · offline`;
   lines.push(
     "",
-    `  ${COLORS.bold}blume audit${COLORS.reset}  ${COLORS.dim}${result.pages} pages · ${where}${COLORS.reset}`,
+    `  ${colors.bold("blume audit")}  ${colors.dim(`${result.pages} pages · ${where}`)}`,
     `  ${summaryLine(counts, auditCount(result))}`,
     ""
   );
 
   if (groups.length === 0) {
-    lines.push(`  ${COLORS.green}✔ No issues found.${COLORS.reset}`, "");
+    lines.push(`  ${colors.green("✔ No issues found.")}`, "");
   }
 
   let category: AuditCategory | null = null;
@@ -178,13 +171,13 @@ export const formatReport = (
     const { category: next } = group;
     if (next !== category) {
       category = next;
-      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`, "");
+      lines.push(`  ${colors.bold(category)}`, "");
     }
 
     const color = SEVERITY_COLOR[group.severity];
     const pages = `${group.count} page${group.count === 1 ? "" : "s"}`;
     lines.push(
-      `  ${color}${GLYPH[group.severity]} ${group.title}${COLORS.reset}  ${COLORS.dim}${pages}${COLORS.reset}`
+      `  ${color(`${GLYPH[group.severity]} ${group.title}`)}  ${colors.dim(pages)}`
     );
 
     const shown = options.verbose
@@ -195,14 +188,12 @@ export const formatReport = (
       // The message names the specifics the rolled-up line can't — which target
       // is broken, what the duplicate is — so --verbose prints it per finding.
       if (options.verbose) {
-        lines.push(`        ${COLORS.dim}${diagnostic.message}${COLORS.reset}`);
+        lines.push(`        ${colors.dim(diagnostic.message)}`);
       }
     }
     const hidden = group.count - shown.length;
     if (hidden > 0) {
-      lines.push(
-        `      ${COLORS.dim}… and ${hidden} more (--verbose)${COLORS.reset}`
-      );
+      lines.push(`      ${colors.dim(`… and ${hidden} more (--verbose)`)}`);
     }
 
     // Every finding in a group shares the catalog's fix unless it overrode it,
@@ -210,7 +201,7 @@ export const formatReport = (
     const [first] = group.findings;
     const fix = first?.suggestion;
     if (fix) {
-      lines.push(`      ${COLORS.cyan}fix: ${fix}${COLORS.reset}`);
+      lines.push(`      ${colors.cyan(`fix: ${fix}`)}`);
     }
     lines.push("");
   }
@@ -268,14 +259,12 @@ export const formatCatalog = (): string => {
     const { category: next } = check;
     if (next !== category) {
       category = next;
-      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`);
+      lines.push(`  ${colors.bold(category)}`);
     }
     const tier =
-      check.tier === "static"
-        ? ""
-        : ` ${COLORS.dim}[${check.tier}]${COLORS.reset}`;
+      check.tier === "static" ? "" : ` ${colors.dim(`[${check.tier}]`)}`;
     lines.push(
-      `    ${SEVERITY_COLOR[check.severity]}${GLYPH[check.severity]}${COLORS.reset} ${check.id.replace("BLUME_AUDIT_", "").toLowerCase().padEnd(34)} ${COLORS.dim}${check.title}${COLORS.reset}${tier}`
+      `    ${SEVERITY_COLOR[check.severity](GLYPH[check.severity])} ${check.id.replace("BLUME_AUDIT_", "").toLowerCase().padEnd(34)} ${colors.dim(check.title)}${tier}`
     );
   }
   lines.push("", `  ${CHECKS.length} checks.`, "");

package/src/audit/types.ts

@@ -135,8 +135,12 @@ export interface LlmsDoc {
 /** A parsed `robots.txt`. */
 export interface RobotsDoc {
   file: string;
-  /** `Disallow:` paths for `User-agent: *`. */
-  disallow: string[];
+  /**
+   * The file's full text. Rule matching runs through robots-parser (which
+   * owns longest-match Allow/Disallow semantics), so the raw text is the
+   * source of truth rather than a pre-extracted rule list.
+   */
+  raw: string;
   /** `Sitemap:` declarations. */
   sitemaps: string[];
   /** Lines that aren't a recognized directive, with their 1-based line number. */