blume 1.0.4 → 1.1.0

package/src/audit/report.ts

@@ -0,0 +1,278 @@
+import { relative } from "pathe";
+
+import { countBySeverity } from "../core/diagnostics.ts";
+import type { Diagnostic, DiagnosticSeverity } from "../core/types.ts";
+import { CHECKS, checkMeta } from "./catalog.ts";
+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 GLYPH: Record<DiagnosticSeverity, string> = {
+  error: "✖",
+  info: "ℹ",
+  warning: "⚠",
+};
+
+/** 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>",
+};
+
+interface CheckRollup {
+  id: CheckId;
+  count: number;
+  severity: DiagnosticSeverity;
+  category: AuditCategory;
+  title: string;
+  findings: Diagnostic[];
+}
+
+/**
+ * Group findings by check. This is the difference between a report people read
+ * and one they close: 214 pages × 6 findings is an unreadable wall, but "Meta
+ * description missing — 12 pages" is a to-do list.
+ */
+export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
+  const groups = new Map<string, Diagnostic[]>();
+  for (const diagnostic of diagnostics) {
+    const group = groups.get(diagnostic.code);
+    if (group) {
+      group.push(diagnostic);
+    } else {
+      groups.set(diagnostic.code, [diagnostic]);
+    }
+  }
+
+  const order: Record<DiagnosticSeverity, number> = {
+    error: 0,
+    info: 2,
+    warning: 1,
+  };
+  const checks = [...groups.entries()].map(([id, findings]) => {
+    const { category, severity, title } = checkMeta(id as CheckId);
+    return {
+      category,
+      count: findings.length,
+      findings,
+      id: id as CheckId,
+      severity,
+      title,
+    };
+  });
+
+  // Rank each category by the worst thing in it, so the categories that need
+  // attention lead. Sorting on severity alone would interleave the categories
+  // and print "content" three separate times.
+  const worst = new Map<AuditCategory, number>();
+  for (const check of checks) {
+    const rank = order[check.severity];
+    worst.set(
+      check.category,
+      Math.min(worst.get(check.category) ?? rank, rank)
+    );
+  }
+
+  return checks.toSorted(
+    (a, b) =>
+      (worst.get(a.category) ?? 0) - (worst.get(b.category) ?? 0) ||
+      a.category.localeCompare(b.category) ||
+      order[a.severity] - order[b.severity] ||
+      b.count - a.count
+  );
+};
+
+/** 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)${COLORS.reset}`;
+    });
+
+/** How many checks actually ran, i.e. those whose tier was enabled. */
+const activeChecks = (tiers: Record<AuditTier, boolean>): number =>
+  CHECKS.filter((check) => tiers[check.tier]).length;
+
+/**
+ * Individual checks performed: every rule that ran, against every page crawled.
+ * The headline number — it's what makes "39 warnings" legible as a proportion
+ * rather than a bare count.
+ */
+export const auditCount = (result: AuditResult): number =>
+  activeChecks(result.tiers) * result.pages;
+
+const summaryLine = (
+  counts: Record<DiagnosticSeverity, number>,
+  audits: number
+): string =>
+  [
+    `${audits.toLocaleString("en-US")} audit${audits === 1 ? "" : "s"}`,
+    `${counts.error} error${counts.error === 1 ? "" : "s"}`,
+    `${counts.warning} warning${counts.warning === 1 ? "" : "s"}`,
+    `${counts.info} note${counts.info === 1 ? "" : "s"}`,
+  ].join(" · ");
+
+/** One affected page: the URL, and the source file that fixes it. */
+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}`
+    : "";
+  // padEnd alone yields no gap once the URL reaches the column width.
+  return `      ${url.padEnd(34)} ${source}`.trimEnd();
+};
+
+/**
+ * Render the audit as a report grouped by check, with each check's affected
+ * pages, the source file to edit, and the fix.
+ */
+export const formatReport = (
+  result: AuditResult,
+  root: string,
+  options: { verbose?: boolean } = {}
+): string => {
+  const counts = countBySeverity(result.diagnostics);
+  const groups = rollup(result.diagnostics);
+  const lines: string[] = [];
+
+  const where = result.origin
+    ? `${relative(root, result.staticDir) || "dist"} + ${result.origin}`
+    : `${relative(root, result.staticDir) || "dist"} · offline`;
+  lines.push(
+    "",
+    `  ${COLORS.bold}blume audit${COLORS.reset}  ${COLORS.dim}${result.pages} pages · ${where}${COLORS.reset}`,
+    `  ${summaryLine(counts, auditCount(result))}`,
+    ""
+  );
+
+  if (groups.length === 0) {
+    lines.push(`  ${COLORS.green}✔ No issues found.${COLORS.reset}`, "");
+  }
+
+  let category: AuditCategory | null = null;
+  for (const group of groups) {
+    const { category: next } = group;
+    if (next !== category) {
+      category = next;
+      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`, "");
+    }
+
+    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}`
+    );
+
+    const shown = options.verbose
+      ? group.findings
+      : group.findings.slice(0, PREVIEW);
+    for (const diagnostic of shown) {
+      lines.push(findingLine(diagnostic, root));
+    }
+    const hidden = group.count - shown.length;
+    if (hidden > 0) {
+      lines.push(
+        `      ${COLORS.dim}… and ${hidden} more (--verbose)${COLORS.reset}`
+      );
+    }
+
+    // Every finding in a group shares the catalog's fix unless it overrode it,
+    // so showing the first one's is showing the group's.
+    const [first] = group.findings;
+    const fix = first?.suggestion;
+    if (fix) {
+      lines.push(`      ${COLORS.cyan}fix: ${fix}${COLORS.reset}`);
+    }
+    lines.push("");
+  }
+
+  const skipped = skippedTiers(result.tiers);
+  if (skipped.length > 0) {
+    lines.push(...skipped, "");
+  }
+
+  return lines.join("\n");
+};
+
+/**
+ * The machine-readable report. The existing `diagnostics` + `summary` shape is
+ * preserved exactly — anything already parsing `blume validate --json` keeps
+ * working — with the audit-specific rollup added alongside it.
+ */
+export const reportJson = (result: AuditResult, root: string): string => {
+  const diagnostics = result.diagnostics.map((diagnostic) =>
+    diagnostic.file
+      ? { ...diagnostic, file: relative(root, diagnostic.file) }
+      : diagnostic
+  );
+  return `${JSON.stringify(
+    {
+      audit: {
+        /** Checks run × pages crawled — the total number of individual audits. */
+        audits: auditCount(result),
+        checks: rollup(result.diagnostics).map((group) => ({
+          category: group.category,
+          count: group.count,
+          id: group.id,
+          severity: group.severity,
+        })),
+        origin: result.origin,
+        pages: result.pages,
+        staticDir: relative(root, result.staticDir),
+        tiers: result.tiers,
+      },
+      diagnostics,
+      summary: countBySeverity(result.diagnostics),
+    },
+    null,
+    2
+  )}\n`;
+};
+
+/** `--list-checks`: the catalog, which is also the docs' source of truth. */
+export const formatCatalog = (): string => {
+  const lines: string[] = [""];
+  let category: AuditCategory | null = null;
+  for (const check of [...CHECKS].toSorted((a, b) =>
+    a.category.localeCompare(b.category)
+  )) {
+    const { category: next } = check;
+    if (next !== category) {
+      category = next;
+      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`);
+    }
+    const tier =
+      check.tier === "static"
+        ? ""
+        : ` ${COLORS.dim}[${check.tier}]${COLORS.reset}`;
+    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}`
+    );
+  }
+  lines.push("", `  ${CHECKS.length} checks.`, "");
+  return lines.join("\n");
+};

package/src/audit/run.ts

@@ -0,0 +1,198 @@
+import { readFile } from "node:fs/promises";
+
+import { normalizeBasePath } from "../core/base-path.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { Diagnostic } from "../core/types.ts";
+import { deployStaticDir } from "../deploy/adapter-output.ts";
+import { CHECKS } from "./catalog.ts";
+import type { CheckId } from "./catalog.ts";
+import { assetChecks } from "./checks/assets.ts";
+import { contentChecks } from "./checks/content.ts";
+import { duplicateChecks } from "./checks/duplicates.ts";
+import { i18nChecks } from "./checks/i18n.ts";
+import { indexabilityChecks } from "./checks/indexability.ts";
+import { linkChecks } from "./checks/links.ts";
+import { llmsChecks } from "./checks/llms.ts";
+import { externalChecks, networkChecks } from "./checks/network.ts";
+import { ogImageChecks } from "./checks/og-image.ts";
+import { redirectChecks } from "./checks/redirects.ts";
+import { robotsChecks } from "./checks/robots.ts";
+import { sitemapChecks } from "./checks/sitemap.ts";
+import {
+  socialChecks,
+  structuredDataChecks,
+  urlChecks,
+} from "./checks/social.ts";
+import { crawlStaticDir } from "./crawl.ts";
+import { buildGraph } from "./graph.ts";
+import { resolveRedirects } from "./redirects.ts";
+import { DEFAULT_THRESHOLDS } from "./types.ts";
+import type {
+  AuditContext,
+  AuditTier,
+  CheckModule,
+  PageSnapshot,
+} from "./types.ts";
+import { normalizePath, siteOrigin } from "./url.ts";
+
+const MODULES: CheckModule[] = [
+  contentChecks,
+  duplicateChecks,
+  indexabilityChecks,
+  linkChecks,
+  redirectChecks,
+  socialChecks,
+  ogImageChecks,
+  i18nChecks,
+  assetChecks,
+  sitemapChecks,
+  robotsChecks,
+  llmsChecks,
+  structuredDataChecks,
+  urlChecks,
+  networkChecks,
+  externalChecks,
+];
+
+export interface AuditOptions {
+  project: BlumeProject;
+  /** Origin to probe for the network tier (`--url`). */
+  origin?: string;
+  /** Probe outbound links (`--external`). */
+  external?: boolean;
+  /** Only report these check ids or categories. */
+  only?: string[];
+  /** Suppress these check ids or categories. */
+  skip?: string[];
+}
+
+export interface AuditResult {
+  diagnostics: Diagnostic[];
+  staticDir: string;
+  pages: number;
+  origin: string | null;
+  /** Which tiers actually ran. A skipped tier is reported, never hidden. */
+  tiers: Record<AuditTier, boolean>;
+}
+
+/** Thrown when there's no build to audit. */
+export class NoBuildError extends Error {
+  readonly staticDir: string;
+
+  constructor(staticDir: string) {
+    super(`No build found at ${staticDir}.`);
+    this.name = "NoBuildError";
+    this.staticDir = staticDir;
+  }
+}
+
+/** Read every page's source file once, so findings can cite front matter lines. */
+const readSources = async (
+  pages: PageSnapshot[]
+): Promise<Map<string, string>> => {
+  const paths = [
+    ...new Set(pages.flatMap((page) => (page.source ? [page.source] : []))),
+  ];
+  const entries = await Promise.all(
+    paths.map(async (path) => {
+      try {
+        return [path, await readFile(path, "utf-8")] as const;
+      } catch {
+        // A staged (non-filesystem) source may not exist on disk. The finding
+        // still names the URL; it just can't cite a line.
+        return null;
+      }
+    })
+  );
+  return new Map(entries.filter((entry) => entry !== null));
+};
+
+/** Does a check id or its category match one of the user's `--only`/`--skip` terms? */
+const matches = (id: CheckId, terms: string[]): boolean => {
+  const meta = CHECKS.find((check) => check.id === id);
+  const short = id.replace("BLUME_AUDIT_", "").toLowerCase();
+  return terms.some((raw) => {
+    const term = raw.trim().toLowerCase();
+    return (
+      term === short || term === id.toLowerCase() || term === meta?.category
+    );
+  });
+};
+
+/** Audit a built site. */
+export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
+  const { project } = options;
+  const staticDir = deployStaticDir(project.config, project.context);
+
+  const crawl = await crawlStaticDir({
+    basePath: normalizeBasePath(project.config.basePath),
+    manifest: project.manifest,
+    staticDir,
+  });
+  if (crawl.pages.length === 0) {
+    throw new NoBuildError(staticDir);
+  }
+
+  const origin = options.origin ?? null;
+  const byUrl = new Map(crawl.pages.map((page) => [page.url, page]));
+  const context: AuditContext = {
+    byUrl,
+    files: crawl.files,
+    graph: buildGraph(
+      crawl.pages,
+      siteOrigin(project.config.deployment.site),
+      normalizeBasePath(project.config.deployment.base)
+    ),
+    llms: crawl.llms,
+    origin,
+    pages: crawl.pages,
+    project,
+    redirects: resolveRedirects(
+      project.config.redirects,
+      // Pages and static files both: a redirect may legitimately land on a
+      // served asset (`/old-whitepaper` -> `/files/whitepaper.pdf`).
+      new Set(
+        [...byUrl.keys(), ...crawl.files.keys()].map((path) =>
+          normalizePath(path)
+        )
+      )
+    ),
+    robots: crawl.robots,
+    sitemap: crawl.sitemap,
+    sources: await readSources(crawl.pages),
+    staticDir,
+    thresholds: DEFAULT_THRESHOLDS,
+  };
+
+  const tiers: Record<AuditTier, boolean> = {
+    external: Boolean(options.external),
+    network: origin !== null,
+    static: true,
+  };
+
+  const results = await Promise.all(
+    MODULES.filter((module) => tiers[module.tier]).map((module) =>
+      module.run(context)
+    )
+  );
+
+  let diagnostics = results.flat();
+  if (options.only?.length) {
+    diagnostics = diagnostics.filter((d) =>
+      matches(d.code as CheckId, options.only ?? [])
+    );
+  }
+  if (options.skip?.length) {
+    diagnostics = diagnostics.filter(
+      (d) => !matches(d.code as CheckId, options.skip ?? [])
+    );
+  }
+
+  return {
+    diagnostics,
+    origin,
+    pages: crawl.pages.length,
+    staticDir,
+    tiers,
+  };
+};

package/src/audit/snapshot.ts

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+
+import type { RouteManifestEntry } from "../core/types.ts";
+import { attr, metaContents, parseHtml, visibleText } from "./html.ts";
+import type { HtmlDocument } from "./html.ts";
+import type { PageSnapshot, SnapshotAsset, SnapshotLink } from "./types.ts";
+
+/** Site chrome: links here are navigation, not editorial. */
+const CHROME = "nav, aside, header, footer";
+
+/** Where a page's prose lives, in preference order. */
+const CONTENT_ROOTS = ["main", "article", "body"];
+
+/**
+ * The elements holding the page's prose. Falls back through `main` → `article`
+ * → `body` so a custom `.astro` page with no semantic landmark still yields a
+ * word count and a content hash instead of silently measuring as empty.
+ */
+const contentRoot = (document: HtmlDocument) => {
+  for (const selector of CONTENT_ROOTS) {
+    const found = document.querySelector(selector);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+};
+
+/**
+ * The `<a>` elements that sit in the page's prose rather than its chrome.
+ *
+ * This split is what makes the link graph mean anything. Blume renders a sidebar
+ * linking every nav page from every page, so a graph that treats a sidebar link
+ * the same as a body link finds that every page has hundreds of inbound links
+ * and no page is ever an orphan.
+ */
+const contentLinks = (document: HtmlDocument): Set<unknown> => {
+  const root = contentRoot(document);
+  if (!root) {
+    return new Set();
+  }
+  return new Set(
+    root.querySelectorAll("a[href]").filter((anchor) => !anchor.closest(CHROME))
+  );
+};
+
+const collectAssets = (
+  document: HtmlDocument,
+  selector: string,
+  srcAttr: string
+): SnapshotAsset[] =>
+  document
+    .querySelectorAll(selector)
+    .map((element) => ({
+      alt: element.getAttribute("alt") ?? null,
+      height: attr(element, "height"),
+      src: element.getAttribute(srcAttr)?.trim() ?? "",
+      width: attr(element, "width"),
+    }))
+    .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 jsonld: unknown[] = [];
+  const jsonldErrors: string[] = [];
+  for (const script of document.querySelectorAll(
+    'script[type="application/ld+json"]'
+  )) {
+    try {
+      jsonld.push(JSON.parse(script.rawText));
+    } catch (error) {
+      jsonldErrors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { jsonld, jsonldErrors };
+};
+
+/** `meta` tags whose key lives in `property` (Open Graph) or `name` (X). */
+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}"]`
+  )) {
+    const key = element.getAttribute(keyAttr)?.trim();
+    const content = element.getAttribute("content")?.trim();
+    if (key && content) {
+      found[key] = content;
+    }
+  }
+  return found;
+};
+
+/**
+ * Reduce one built HTML page to everything the checks read. Parsed once — every
+ * check works off this record, so a page is never re-parsed per check.
+ */
+export const buildSnapshot = (options: {
+  file: string;
+  url: string;
+  html: string;
+  route?: RouteManifestEntry;
+}): PageSnapshot => {
+  const { file, url, html, route } = options;
+  const document = parseHtml(html);
+
+  const inContent = contentLinks(document);
+  const links: SnapshotLink[] = document
+    .querySelectorAll("a[href]")
+    .map((anchor) => ({
+      content: inContent.has(anchor),
+      href: anchor.getAttribute("href")?.trim() ?? "",
+      rel: attr(anchor, "rel"),
+      text: anchor.text.trim(),
+    }))
+    .filter((link) => link.href.length > 0);
+
+  const root = contentRoot(document);
+  const prose = root ? visibleText(root) : "";
+  const robots = document.querySelector('meta[name="robots"]');
+  const { jsonld, jsonldErrors } = collectJsonLd(document);
+
+  return {
+    bytes: Buffer.byteLength(html, "utf-8"),
+    canonical:
+      document
+        .querySelector('link[rel="canonical"]')
+        ?.getAttribute("href")
+        ?.trim() ?? null,
+    contentHash: createHash("sha256").update(prose).digest("hex").slice(0, 16),
+    descriptions: metaContents(document, 'meta[name="description"]'),
+    file,
+    headings: document
+      .querySelectorAll("h1, h2, h3, h4, h5, h6")
+      .map((heading) => ({
+        depth: Number(heading.tagName.slice(1)),
+        text: heading.text.trim(),
+      })),
+    hreflang: document
+      .querySelectorAll("link[rel=alternate][hreflang]")
+      .map((link) => ({
+        href: link.getAttribute("href")?.trim() ?? "",
+        lang: link.getAttribute("hreflang")?.trim() ?? "",
+      }))
+      .filter((alternate) => alternate.href && alternate.lang),
+    ids: new Set(
+      document
+        .querySelectorAll("[id]")
+        .map((element) => element.getAttribute("id") ?? "")
+        .filter((id) => id.length > 0)
+    ),
+    images: collectAssets(document, "img[src]", "src"),
+    // A page is indexable unless it says otherwise. Blume only ever emits
+    // `noindex` (never `nofollow`), but an ejected layout could emit either.
+    indexable: !robots?.getAttribute("content")?.includes("noindex"),
+    jsonld,
+    jsonldErrors,
+    lang: attr(document.querySelector("html") ?? document, "lang"),
+    links,
+    metaRefresh:
+      document
+        .querySelector('meta[http-equiv="refresh" i]')
+        ?.getAttribute("content")
+        ?.trim() ?? null,
+    og: prefixedMeta(document, "property", "og:"),
+    robots: robots?.getAttribute("content")?.trim() ?? null,
+    route,
+    scripts: collectAssets(document, "script[src]", "src"),
+    source: route?.sourcePath,
+    styles: collectAssets(document, 'link[rel="stylesheet"][href]', "href"),
+    titles: document
+      .querySelectorAll("title")
+      .map((title) => title.text.trim())
+      .filter((text) => text.length > 0),
+    twitter: prefixedMeta(document, "name", "twitter:"),
+    url,
+    viewport:
+      document
+        .querySelector('meta[name="viewport"]')
+        ?.getAttribute("content")
+        ?.trim() ?? null,
+    wordCount: prose ? prose.split(/\s+/u).length : 0,
+  };
+};