blume 1.0.3 → 1.1.0

package/src/audit/types.ts

@@ -0,0 +1,214 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type {
+  Diagnostic,
+  DiagnosticSeverity,
+  RouteManifestEntry,
+} from "../core/types.ts";
+
+/**
+ * What a check needs in order to run. Anything above `static` is opt-in, and a
+ * skipped tier is reported rather than silently omitted — a crawler that
+ * quietly doesn't check something is worse than one that says it didn't.
+ */
+export type AuditTier = "static" | "network" | "external";
+
+export type AuditCategory =
+  | "content"
+  | "duplicates"
+  | "indexability"
+  | "links"
+  | "redirects"
+  | "social"
+  | "i18n"
+  | "assets"
+  | "sitemap"
+  | "robots"
+  | "structured-data"
+  | "ai"
+  | "network";
+
+/** A check's static metadata. The catalog is the source of truth for all of it. */
+export interface CheckMeta {
+  readonly id: string;
+  readonly category: AuditCategory;
+  readonly severity: DiagnosticSeverity;
+  /** Human title used as the report's group header, e.g. "Title too long". */
+  readonly title: string;
+  readonly tier: AuditTier;
+  /** Default remediation, used as the finding's `suggestion`. */
+  readonly fix?: string;
+}
+
+/** A `<link>`/`<a>` discovered in built HTML. */
+export interface SnapshotLink {
+  href: string;
+  rel: string | null;
+  text: string;
+  /**
+   * Whether the link sits in the page's prose (`<main>`/`<article>`) rather
+   * than site chrome (nav/sidebar/header/footer). Load-bearing: Blume's sidebar
+   * links every page from every page, so a link graph that can't tell the two
+   * apart reports zero orphans, forever.
+   */
+  content: boolean;
+}
+
+/** An image/script/stylesheet referenced by a built page. */
+export interface SnapshotAsset {
+  src: string;
+  alt?: string | null;
+  width?: string | null;
+  height?: string | null;
+  /** Absolute path in the static dir, when the ref resolves to a local file. */
+  file?: string;
+  bytes?: number;
+}
+
+/** Everything one built HTML page contributes to the audit. */
+export interface PageSnapshot {
+  /** Absolute path of the built `.html`. */
+  file: string;
+  /** Site-root-relative URL, e.g. `/docs/getting-started`. */
+  url: string;
+  bytes: number;
+  /** The manifest entry this page renders, when it maps to authored content. */
+  route?: RouteManifestEntry;
+  /** `route.sourcePath` — the `.mdx` a finding should point the user at. */
+  source?: string;
+  indexable: boolean;
+
+  lang: string | null;
+  /** Every `<title>`; more than one is itself a finding. */
+  titles: string[];
+  descriptions: string[];
+  canonical: string | null;
+  robots: string | null;
+  viewport: string | null;
+  metaRefresh: string | null;
+  headings: { depth: number; text: string }[];
+  og: Record<string, string>;
+  twitter: Record<string, string>;
+  hreflang: { lang: string; href: string }[];
+  jsonld: unknown[];
+  /** JSON-LD blocks that failed to parse, with the parser's message. */
+  jsonldErrors: string[];
+  links: SnapshotLink[];
+  images: SnapshotAsset[];
+  scripts: SnapshotAsset[];
+  styles: SnapshotAsset[];
+  wordCount: number;
+  /** Hash of the normalized prose, for exact-duplicate detection. */
+  contentHash: string;
+  /** Every element `id` on the page — the targets `#fragment` links can hit. */
+  ids: Set<string>;
+}
+
+/** A configured redirect resolved through to its final destination. */
+export interface RedirectResolution {
+  from: string;
+  to: string;
+  status: number;
+  /** Every hop from `from` to the final target, inclusive. */
+  chain: string[];
+  outcome: "ok" | "loop" | "broken" | "chain";
+}
+
+/** A parsed `sitemap.xml`. */
+export interface SitemapDoc {
+  file: string;
+  bytes: number;
+  /** Absolute `<loc>` URLs, in document order. */
+  urls: string[];
+  /** Each `<url>` block's `<lastmod>`, keyed by its `<loc>`. */
+  lastmod?: Map<string, string>;
+  /** Parse failure, when the document isn't usable. */
+  error?: string;
+}
+
+/** A parsed `llms.txt` index. */
+export interface LlmsDoc {
+  file: string;
+  /** Markdown link targets in document order, with their 1-based line. */
+  entries: { url: string; line: number }[];
+}
+
+/** A parsed `robots.txt`. */
+export interface RobotsDoc {
+  file: string;
+  /** `Disallow:` paths for `User-agent: *`. */
+  disallow: string[];
+  /** `Sitemap:` declarations. */
+  sitemaps: string[];
+  /** Lines that aren't a recognized directive, with their 1-based line number. */
+  invalid: { line: number; text: string }[];
+}
+
+/** Incoming/outgoing internal-link edges, split by where the link sits. */
+export interface LinkGraph {
+  /** url -> urls it links to from its prose. */
+  contentOut: Map<string, Set<string>>;
+  /** url -> urls whose prose links to it. */
+  contentIn: Map<string, Set<string>>;
+  /** url -> urls it links to from chrome (nav/sidebar/footer). */
+  chromeOut: Map<string, Set<string>>;
+  chromeIn: Map<string, Set<string>>;
+}
+
+/** 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. */
+export interface AuditThresholds {
+  titleMin: number;
+  titleMax: number;
+  descriptionMin: number;
+  descriptionMax: number;
+  minWordCount: number;
+  maxHtmlBytes: number;
+  maxAssetBytes: number;
+  maxRedirectHops: number;
+}
+
+export const DEFAULT_THRESHOLDS: AuditThresholds = {
+  // Ahrefs' guidance: 110–160 characters. Under ~110 wastes the snippet
+  // space search results give you; over ~160 gets truncated.
+  descriptionMax: 160,
+  descriptionMin: 110,
+  maxAssetBytes: 500 * 1024,
+  // Googlebot stops reading an HTML document at 2 MB.
+  maxHtmlBytes: 2 * 1024 * 1024,
+  maxRedirectHops: 3,
+  minWordCount: 50,
+  titleMax: 60,
+  titleMin: 10,
+};
+
+/** Everything the check modules read. Assembled once per run. */
+export interface AuditContext {
+  project: BlumeProject;
+  staticDir: string;
+  /** Origin passed via `--url`, for the network tier. */
+  origin: string | null;
+  pages: PageSnapshot[];
+  byUrl: Map<string, PageSnapshot>;
+  /** Every file in the static dir: URL path -> size in bytes. */
+  files: Map<string, number>;
+  /**
+   * Raw text of every page's source file, keyed by absolute path. Read once so
+   * findings can be anchored to the exact front matter line that fixes them.
+   */
+  sources: Map<string, string>;
+  graph: LinkGraph;
+  redirects: RedirectResolution[];
+  sitemap: SitemapDoc | null;
+  robots: RobotsDoc | null;
+  llms: LlmsDoc | null;
+  thresholds: AuditThresholds;
+}
+
+/** One category's checks. Modules, not per-check closures — see catalog.ts. */
+export interface CheckModule {
+  readonly category: AuditCategory;
+  readonly tier: AuditTier;
+  readonly run: (context: AuditContext) => Diagnostic[] | Promise<Diagnostic[]>;
+}

package/src/audit/url.ts

@@ -0,0 +1,103 @@
+import { stripBasePath } from "../core/base-path.ts";
+
+/** What an `href` in built HTML turned out to point at. */
+export type ResolvedHref =
+  /** A path on this site. */
+  | { kind: "internal"; path: string; hash: string }
+  /** An absolute URL that resolves back to this site — should have been a path. */
+  | { kind: "self-origin"; path: string; hash: string }
+  /** An absolute URL on another origin. */
+  | { kind: "external"; url: string }
+  /** In-page anchor, `mailto:`, `tel:`, `javascript:`, data URI — not a page link. */
+  | { kind: "ignored" };
+
+const NON_HTTP_SCHEME = /^(?!https?:)[a-z][a-z0-9+.-]*:/iu;
+
+/**
+ * Normalize a site path for comparison: drop the trailing slash (Astro serves
+ * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
+ */
+export const normalizePath = (path: string): string => {
+  const trimmed = path.replace(/\/+$/u, "");
+  return trimmed === "" ? "/" : trimmed;
+};
+
+/** The origin of `deployment.site`, or null when no site is configured. */
+export const siteOrigin = (site?: string): string | null => {
+  if (!site) {
+    return null;
+  }
+  try {
+    return new URL(site).origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Resolve an `href` found on `pageUrl` into something the link graph can use.
+ *
+ * An absolute URL pointing back at our own origin is reported separately from a
+ * genuine external link: it's an internal link that hardcoded the production
+ * domain, which silently breaks on preview deploys and under `basePath`.
+ *
+ * `deployBase` is the normalized `deployment.base`: emitted hrefs carry it, but
+ * the built file tree (and so every page URL and file-index key) does not, so it
+ * is stripped here to keep resolved paths comparable. `basePath` is different —
+ * Blume mounts it as a real directory in the build, so it stays.
+ */
+export const resolveHref = (
+  pageUrl: string,
+  href: string,
+  origin: string | null,
+  deployBase = ""
+): ResolvedHref => {
+  const target = href.trim();
+  if (target === "" || target.startsWith("#")) {
+    return { kind: "ignored" };
+  }
+  if (NON_HTTP_SCHEME.test(target)) {
+    return { kind: "ignored" };
+  }
+
+  // Protocol-relative (`//host/x`) is an absolute URL with the page's scheme.
+  const absolute = /^https?:\/\//iu.test(target) || target.startsWith("//");
+  if (absolute) {
+    let parsed: URL;
+    try {
+      parsed = new URL(target.startsWith("//") ? `https:${target}` : target);
+    } catch {
+      return { kind: "ignored" };
+    }
+    if (origin && parsed.origin === origin) {
+      return {
+        hash: parsed.hash.slice(1),
+        kind: "self-origin",
+        path: normalizePath(stripBasePath(deployBase, parsed.pathname)),
+      };
+    }
+    return { kind: "external", url: parsed.toString() };
+  }
+
+  // A relative href resolves against the page's own URL. `URL` needs an origin
+  // to do that, so borrow a placeholder one and keep only the path. The base
+  // carries a trailing slash because Astro's directory build serves `/docs/api`
+  // at `/docs/api/` — so in a browser `./auth` there means `/docs/api/auth`, not
+  // `/docs/auth`. Resolving against the slashless form would silently mis-target
+  // every relative link on the site by one directory level.
+  const base =
+    pageUrl === "/"
+      ? "https://blume.invalid/"
+      : `https://blume.invalid${pageUrl}/`;
+  let resolved: URL;
+  try {
+    resolved = new URL(target, base);
+  } catch {
+    return { kind: "ignored" };
+  }
+  return {
+    hash: resolved.hash.slice(1),
+    kind: "internal",
+    path: normalizePath(stripBasePath(deployBase, resolved.pathname)),
+  };
+};

package/src/cli/commands/audit.ts

@@ -0,0 +1,205 @@
+import { defineCommand } from "citty";
+
+import {
+  AGENTS,
+  fixPrompt,
+  launchAgent,
+  WINDOWS_COMMAND_NOT_FOUND,
+  writeAgentReport,
+} from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { formatCatalog, formatReport, reportJson } from "../../audit/report.ts";
+import { NoBuildError, runAudit } from "../../audit/run.ts";
+import type { AuditResult } from "../../audit/run.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import type { DiagnosticSeverity } from "../../core/types.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { flushStdout, logger } from "../log.ts";
+
+const SEVERITIES: DiagnosticSeverity[] = ["error", "warning", "info"];
+
+/** Severities at or above the gate, e.g. `warning` -> error + warning. */
+const failingSeverities = (gate: DiagnosticSeverity): Set<DiagnosticSeverity> =>
+  new Set(SEVERITIES.slice(0, SEVERITIES.indexOf(gate) + 1));
+
+const splitTerms = (value: string | undefined): string[] =>
+  value
+    ? value
+        .split(",")
+        .map((term) => term.trim())
+        .filter(Boolean)
+    : [];
+
+/** Whether the run should exit non-zero, given the gate. */
+export const shouldFail = (
+  result: AuditResult,
+  gate: DiagnosticSeverity
+): boolean => {
+  const failing = failingSeverities(gate);
+  return result.diagnostics.some((d) => failing.has(d.severity));
+};
+
+export const auditCommand = defineCommand({
+  args: {
+    claude: {
+      description: "Hand the findings to Claude Code to fix interactively.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Hand the findings to Codex to fix interactively.",
+      type: "boolean",
+    },
+    external: {
+      description: "Probe outbound links over the network.",
+      type: "boolean",
+    },
+    "fail-on": {
+      description:
+        "Exit non-zero at this severity or above: error | warning | info. Defaults to error.",
+      type: "string",
+    },
+    json: {
+      description: "Emit the report as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
+    "list-checks": {
+      description: "Print every check the audit can report, then exit.",
+      type: "boolean",
+    },
+    only: {
+      description: "Only report these checks or categories (comma-separated).",
+      type: "string",
+    },
+    skip: {
+      description: "Suppress these checks or categories (comma-separated).",
+      type: "string",
+    },
+    strict: {
+      description: "Alias for --fail-on warning.",
+      type: "boolean",
+    },
+    url: {
+      description:
+        "Also probe a live deployment (e.g. https://docs.example.com) for status codes, headers, and redirects.",
+      type: "string",
+    },
+    verbose: {
+      description: "List every affected page instead of the first few.",
+      type: "boolean",
+    },
+  },
+  meta: {
+    description: "Audit the built site for SEO and site-health issues.",
+    name: "audit",
+  },
+  async run({ args }) {
+    if (args["list-checks"]) {
+      process.stdout.write(formatCatalog());
+      return;
+    }
+
+    const root = process.cwd();
+    const gate = (args["fail-on"] ??
+      (args.strict ? "warning" : "error")) as DiagnosticSeverity;
+    if (!SEVERITIES.includes(gate)) {
+      logger.error(
+        `Invalid --fail-on "${gate}" (use ${SEVERITIES.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+    const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
+      (kind) => args[kind]
+    );
+    if (agents.length > 1) {
+      logger.error("Pass at most one of --claude or --codex.");
+      process.exit(1);
+    }
+    const [agent] = agents;
+    if (agent && args.json) {
+      logger.error(`--json and --${agent} are mutually exclusive.`);
+      process.exit(1);
+    }
+    let result: AuditResult;
+    try {
+      // `scanProject`, not `prepareProject`: the audit reads the *existing*
+      // build and never regenerates the runtime, so it doesn't contend with a
+      // running dev server. Same reasoning as `blume validate`.
+      const project = await scanProject(root, { mode: "build" });
+      result = await runAudit({
+        external: args.external,
+        only: splitTerms(args.only),
+        origin: args.url,
+        project,
+        skip: splitTerms(args.skip),
+      });
+    } catch (error) {
+      if (error instanceof NoBuildError) {
+        logger.error(`${error.message} Run \`blume build\` first.`);
+        process.exit(1);
+      }
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+
+    if (agent) {
+      // Show the same report a plain run would, so the terminal records what
+      // was handed off before the agent's own UI takes over the screen.
+      process.stderr.write(
+        formatReport(result, root, { verbose: args.verbose })
+      );
+      if (result.diagnostics.length === 0) {
+        return;
+      }
+      const cli = AGENTS[agent];
+      const report = await writeAgentReport(result, root);
+      const count = result.diagnostics.length;
+      // Straight to stderr like the report above it, not `logger.info` —
+      // consola drops info-level lines in test and CI environments.
+      process.stderr.write(
+        `  Handing ${count} finding${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
+      );
+      let code: number;
+      try {
+        code = await launchAgent(cli.bin, fixPrompt(report));
+      } catch {
+        code = WINDOWS_COMMAND_NOT_FOUND;
+      }
+      // 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);
+      }
+      if (code !== 0) {
+        process.exit(code);
+      }
+      // The gate is a CI concern; a handoff run succeeds when the agent
+      // session does, not when the pre-fix site was already clean.
+      return;
+    }
+
+    if (args.json) {
+      process.stdout.write(reportJson(result, root));
+      if (shouldFail(result, gate)) {
+        // `process.exit` doesn't flush a piped stdout — without this the JSON is
+        // truncated mid-write in exactly the CI setups that consume it.
+        await flushStdout();
+        process.exit(1);
+      }
+      return;
+    }
+
+    process.stderr.write(formatReport(result, root, { verbose: args.verbose }));
+
+    if (shouldFail(result, gate)) {
+      process.exit(1);
+    }
+  },
+});

package/src/cli/commands/build.ts

@@ -13,11 +13,13 @@ import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { ProjectContext } from "../../core/types.ts";
 import {
+  ADAPTER_IGNORE_DIRS,
   deployStaticDir,
   surfaceAdapterOutput,
 } from "../../deploy/adapter-output.ts";
+import { buildNetlifyHeaders } from "../../deploy/headers.ts";
 import {
-  applyBaseToRedirects,
+  applyBaseToPlatformRedirects,
   buildNetlifyRedirects,
   buildRedirectManifest,
   buildVercelConfig,
@@ -73,7 +75,11 @@ const emitRedirectFiles = async (
   config: ResolvedConfig,
   distDir: string
 ): Promise<void> => {
-  const redirects = applyBaseToRedirects(config.redirects, config.basePath);
+  const redirects = applyBaseToPlatformRedirects(
+    config.redirects,
+    config.basePath,
+    config.deployment.base ?? ""
+  );
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
@@ -96,6 +102,33 @@ const emitRedirectFiles = async (
   logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 
+/**
+ * Emit a `_headers` file for a static build so Netlify / Cloudflare static
+ * hosts serve the raw AI-ready endpoints (`*.md`, `*.mdx`, `*.txt`) with an
+ * explicit `charset=utf-8`. Without it those hosts send `text/markdown` /
+ * `text/plain` with no charset and browsers fall back to Windows-1252, garbling
+ * any non-ASCII docs (#82). A `_headers` shipped in `public/` (copied into dist
+ * by Astro before this runs) wins, exactly like `_redirects`. Server adapters
+ * set the Content-Type on the Response directly, so this is static-only.
+ */
+const emitHeaderFiles = async (
+  config: ResolvedConfig,
+  distDir: string
+): Promise<void> => {
+  if (
+    config.deployment.output !== "static" ||
+    existsSync(join(distDir, "_headers"))
+  ) {
+    return;
+  }
+  await writeFile(
+    join(distDir, "_headers"),
+    buildNetlifyHeaders(config),
+    "utf-8"
+  );
+  logger.success("Emitted _headers (UTF-8 Content-Type for raw endpoints)");
+};
+
 const formatBytes = (bytes: number): string => {
   if (bytes < 1024) {
     return `${bytes} B`;
@@ -343,6 +376,7 @@ const publishBuildArtifacts = async (
   }
 
   await emitRedirectFiles(project.config, distDir);
+  await emitHeaderFiles(project.config, distDir);
 
   const { config } = project;
   const features = serverFeatures(config);
@@ -479,21 +513,26 @@ export const buildCommand = defineCommand({
       return;
     }
 
-    // A server adapter (Vercel/Netlify) writes its deploy bundle relative to the
-    // Astro root — which Blume points at the hidden `.blume` runtime — so the
-    // bundle lands where the deploy platform never looks. Surface it up to the
-    // project root before publishing artifacts into the served static dir.
+    // A server adapter's deploy bundle is a build artifact — keep it out of
+    // version control (Vercel's own CLI ignores `.vercel/` for the same reason).
+    // Ignoring it is independent of whether the bundle had to be moved below:
+    // Vercel writes straight to the project root, Netlify does not.
+    const { adapter } = project.config.deployment;
+    const ignoreDir = adapter ? ADAPTER_IGNORE_DIRS[adapter] : undefined;
+    if (project.config.deployment.output === "server" && ignoreDir) {
+      await ensureGitignore(root, [ignoreDir]);
+    }
+
+    // Netlify writes its deploy bundle relative to the Astro root — which Blume
+    // points at the hidden `.blume` runtime — so the bundle lands where the
+    // deploy platform never looks. Surface it up to the project root before
+    // publishing artifacts into the served static dir.
     const surfaced = await surfaceAdapterOutput(
       project.config,
       project.context
     );
     if (surfaced.moved) {
-      logger.success(
-        `Surfaced ${project.config.deployment.adapter} output to ${surfaced.to}`
-      );
-      // The surfaced bundle is a build artifact — keep it out of version control
-      // (Vercel's own CLI ignores `.vercel/` for the same reason).
-      await ensureGitignore(root, [surfaced.ignore]);
+      logger.success(`Surfaced ${adapter} output to ${surfaced.to}`);
     }
 
     await publishBuildArtifacts(

package/src/cli/index.ts

@@ -2,6 +2,7 @@ import { defineCommand, runMain } from "citty";
 
 import { getBlumeVersion } from "../core/version.ts";
 import { addCommand } from "./commands/add.ts";
+import { auditCommand } from "./commands/audit.ts";
 import { buildCommand } from "./commands/build.ts";
 import { checkCommand } from "./commands/check.ts";
 import { devCommand } from "./commands/dev.ts";
@@ -22,6 +23,7 @@ const main = defineCommand({
   },
   subCommands: {
     add: addCommand,
+    audit: auditCommand,
     build: buildCommand,
     check: checkCommand,
     dev: devCommand,

package/src/components/content/Callout.astro

@@ -60,8 +60,14 @@ const iconClass: Record<CalloutType, string> = {
   <span class:list={["mt-0.5 shrink-0", color ? "" : iconClass[type]]}>
     <Icon color={color} icon={icon ?? iconByType[type]} size={16} />
   </span>
-  <div class="flex-1 [&>:first-child]:mt-0! [&>:last-child]:mb-0!">
-    {title && <p class="mb-1 font-semibold text-foreground">{title}</p>}
+  {/* The global prose rule leaks a 1rem margin onto these paragraphs/lists even
+      though the callout is not-prose; with a title the body isn't the first
+      child, so that margin stacks under the title's own gap and reads as too
+      much space. Override it here for a uniform, compact gap (important beats
+      the unlayered prose rule): every child a small top margin, none on the
+      first, and no trailing bottom margin. */}
+  <div class="flex-1 [&>*]:mt-2! [&>*]:mb-0! [&>:first-child]:mt-0!">
+    {title && <p class="font-semibold text-foreground">{title}</p>}
     <slot />
   </div>
 </aside>