blume 1.0.4 → 1.1.0

package/src/audit/checks/assets.ts

@@ -0,0 +1,177 @@
+import { normalizeBasePath } from "../../core/base-path.ts";
+import type { Diagnostic } from "../../core/types.ts";
+import { finding } from "../catalog.ts";
+import type { CheckId } from "../catalog.ts";
+import { pageSite } from "../locate.ts";
+import type {
+  AuditContext,
+  CheckModule,
+  PageSnapshot,
+  SnapshotAsset,
+} from "../types.ts";
+import { resolveHref, siteOrigin } from "../url.ts";
+
+const formatBytes = (bytes: number): string =>
+  bytes < 1024 * 1024
+    ? `${Math.round(bytes / 1024)} kB`
+    : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+
+/**
+ * Resolve a subresource reference to its file in the build, reporting a missing
+ * file or an insecure (`http://`) reference. Returns the file's size when it
+ * resolves to something real and local.
+ */
+const resolveAsset = (
+  context: AuditContext,
+  page: PageSnapshot,
+  asset: SnapshotAsset,
+  missingId: CheckId,
+  kind: string,
+  found: Diagnostic[]
+): number | null => {
+  if (asset.src.startsWith("http://")) {
+    found.push(
+      finding(
+        "BLUME_AUDIT_MIXED_CONTENT",
+        pageSite(context, page),
+        `Page loads ${kind} over plain HTTP: ${asset.src}`
+      )
+    );
+    return null;
+  }
+  if (asset.src.startsWith("data:")) {
+    return null;
+  }
+
+  const origin = siteOrigin(context.project.config.deployment.site);
+  const resolved = resolveHref(
+    page.url,
+    asset.src,
+    origin,
+    normalizeBasePath(context.project.config.deployment.base)
+  );
+  // A subresource on another origin (a CDN, an analytics script) is outside the
+  // build; we can't check whether it exists without the network.
+  if (resolved.kind === "external" || resolved.kind === "ignored") {
+    return null;
+  }
+
+  const bytes = context.files.get(resolved.path);
+  if (bytes === undefined) {
+    found.push(
+      finding(
+        missingId,
+        pageSite(context, page),
+        `Page references ${asset.src}, which is not in the build.`
+      )
+    );
+    return null;
+  }
+  return bytes;
+};
+
+/**
+ * Images, scripts, and stylesheets: do they exist, are they secure, are they
+ * too heavy, and (for images) are they accessible and layout-stable.
+ *
+ * Ahrefs devotes ~18 rows to this across its Images, JavaScript, and CSS
+ * sections — "JS redirects", "page has redirected CSS", "HTTPS page links to
+ * HTTP JavaScript", and both an asset-scoped and a page-scoped copy of each.
+ * Vite emits content-hashed, existent, non-redirecting bundles, so nearly all of
+ * that is unfireable; what's left is this.
+ */
+export const assetChecks: CheckModule = {
+  category: "assets",
+  run(context) {
+    const found: Diagnostic[] = [];
+    const { maxAssetBytes } = context.thresholds;
+
+    const weigh = (
+      page: PageSnapshot,
+      asset: SnapshotAsset,
+      bytes: number | null,
+      kind: string
+    ): void => {
+      if (bytes !== null && bytes > maxAssetBytes) {
+        found.push(
+          finding(
+            "BLUME_AUDIT_ASSET_TOO_LARGE",
+            pageSite(context, page),
+            `${kind} ${asset.src} is ${formatBytes(bytes)} (over ${formatBytes(maxAssetBytes)}).`
+          )
+        );
+      }
+    };
+
+    for (const page of context.pages) {
+      for (const image of page.images) {
+        const bytes = resolveAsset(
+          context,
+          page,
+          image,
+          "BLUME_AUDIT_IMAGE_BROKEN",
+          "an image",
+          found
+        );
+        weigh(page, image, bytes, "Image");
+
+        // `alt=""` is a deliberate "this image is decorative" and is correct.
+        // A missing `alt` attribute is the finding.
+        if (image.alt === null) {
+          found.push(
+            finding(
+              "BLUME_AUDIT_IMAGE_ALT_MISSING",
+              pageSite(context, page),
+              `Image ${image.src} has no alt attribute.`
+            )
+          );
+        }
+
+        if (!(image.width && image.height)) {
+          found.push(
+            finding(
+              "BLUME_AUDIT_IMAGE_MISSING_DIMENSIONS",
+              pageSite(context, page),
+              `Image ${image.src} has no width/height, so it will shift the layout as it loads.`
+            )
+          );
+        }
+      }
+
+      for (const script of page.scripts) {
+        weigh(
+          page,
+          script,
+          resolveAsset(
+            context,
+            page,
+            script,
+            "BLUME_AUDIT_SUBRESOURCE_MISSING",
+            "a script",
+            found
+          ),
+          "Script"
+        );
+      }
+
+      for (const style of page.styles) {
+        weigh(
+          page,
+          style,
+          resolveAsset(
+            context,
+            page,
+            style,
+            "BLUME_AUDIT_SUBRESOURCE_MISSING",
+            "a stylesheet",
+            found
+          ),
+          "Stylesheet"
+        );
+      }
+    }
+
+    return found;
+  },
+  tier: "static",
+};

package/src/audit/checks/content.ts

@@ -0,0 +1,231 @@
+import matter from "../../core/frontmatter.ts";
+import type { Diagnostic } from "../../core/types.ts";
+import { finding } from "../catalog.ts";
+import { pageSite } from "../locate.ts";
+import { ERROR_ROUTES } from "../types.ts";
+import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
+
+/**
+ * The `date` a source file's front matter declares, when it parses to a real
+ * date. YAML hands back a `Date` for an unquoted `2026-01-01` and a string for
+ * a quoted one, so both spellings are accepted; malformed front matter or an
+ * unparseable value simply yields nothing — `BLUME_FRONTMATTER_INVALID` is the
+ * build's finding, not the audit's.
+ */
+const frontmatterDate = (source: string): Date | null => {
+  try {
+    const { date } = matter(source).data as { date?: unknown };
+    if (typeof date !== "string" && !(date instanceof Date)) {
+      return null;
+    }
+    const parsed = date instanceof Date ? date : new Date(date);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  } catch {
+    return null;
+  }
+};
+
+const titleChecks = (
+  context: AuditContext,
+  page: PageSnapshot
+): Diagnostic[] => {
+  const { titleMin, titleMax } = context.thresholds;
+  const [title] = page.titles;
+
+  if (!title) {
+    return [
+      finding(
+        "BLUME_AUDIT_TITLE_MISSING",
+        pageSite(context, page),
+        "Page has no <title>."
+      ),
+    ];
+  }
+
+  const found: Diagnostic[] = [];
+  if (page.titles.length > 1) {
+    found.push(
+      finding(
+        "BLUME_AUDIT_TITLE_MULTIPLE",
+        pageSite(context, page),
+        `Page has ${page.titles.length} <title> tags; search engines use only the first.`
+      )
+    );
+  }
+  if (title.length > titleMax || title.length < titleMin) {
+    const direction = title.length > titleMax ? "long" : "short";
+    found.push(
+      finding(
+        "BLUME_AUDIT_TITLE_LENGTH",
+        pageSite(context, page, ["title"]),
+        `Title is ${title.length} characters — too ${direction} (aim for ${titleMin}–${titleMax}).`
+      )
+    );
+  }
+  return found;
+};
+
+const descriptionChecks = (
+  context: AuditContext,
+  page: PageSnapshot
+): Diagnostic[] => {
+  // An error route is noindex by design, so its description never renders as
+  // a search snippet — grading it would put a guaranteed finding on every
+  // site whose 404 inherits the site-default description.
+  if (ERROR_ROUTES.has(page.url)) {
+    return [];
+  }
+
+  const { descriptionMin, descriptionMax } = context.thresholds;
+  const [description] = page.descriptions;
+
+  if (!description) {
+    return [
+      finding(
+        "BLUME_AUDIT_DESCRIPTION_MISSING",
+        pageSite(context, page),
+        "Page has no meta description."
+      ),
+    ];
+  }
+
+  const found: Diagnostic[] = [];
+  if (page.descriptions.length > 1) {
+    found.push(
+      finding(
+        "BLUME_AUDIT_DESCRIPTION_MULTIPLE",
+        pageSite(context, page),
+        `Page has ${page.descriptions.length} meta description tags.`
+      )
+    );
+  }
+  if (
+    description.length > descriptionMax ||
+    description.length < descriptionMin
+  ) {
+    const direction = description.length > descriptionMax ? "long" : "short";
+    found.push(
+      finding(
+        "BLUME_AUDIT_DESCRIPTION_LENGTH",
+        pageSite(context, page, ["description"]),
+        `Meta description is ${description.length} characters — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
+      )
+    );
+  }
+  return found;
+};
+
+const headingChecks = (
+  context: AuditContext,
+  page: PageSnapshot
+): Diagnostic[] => {
+  const h1s = page.headings.filter((heading) => heading.depth === 1);
+  if (h1s.length === 0) {
+    return [
+      finding(
+        "BLUME_AUDIT_H1_MISSING",
+        pageSite(context, page),
+        "Page has no <h1>."
+      ),
+    ];
+  }
+  if (h1s.length > 1) {
+    return [
+      finding(
+        "BLUME_AUDIT_H1_MULTIPLE",
+        pageSite(context, page),
+        `Page has ${h1s.length} <h1> tags: ${h1s.map((h) => `"${h.text}"`).join(", ")}.`
+      ),
+    ];
+  }
+
+  // A skipped level (h2 -> h4) breaks table-of-contents nesting and screen-
+  // reader outlines. The first skip is the finding — one wrong heading early
+  // in a page cascades, and listing every knock-on skip buries the fix.
+  let previous: number | null = null;
+  for (const heading of page.headings) {
+    if (previous !== null && heading.depth > previous + 1) {
+      return [
+        finding(
+          "BLUME_AUDIT_HEADING_SKIP",
+          pageSite(context, page),
+          `Headings jump from h${previous} to h${heading.depth} at "${heading.text}".`
+        ),
+      ];
+    }
+    previous = heading.depth;
+  }
+  return [];
+};
+
+/**
+ * A page dated in the future usually means scheduled content that leaked into
+ * the build early. Only the front matter knows — the rendered page looks
+ * perfectly ordinary.
+ */
+const futureDateChecks = (
+  context: AuditContext,
+  page: PageSnapshot
+): Diagnostic[] => {
+  const source = page.source && context.sources.get(page.source);
+  if (!source) {
+    return [];
+  }
+  const date = frontmatterDate(source);
+  if (date && date.getTime() > Date.now()) {
+    return [
+      finding(
+        "BLUME_AUDIT_FUTURE_DATED_PAGE",
+        pageSite(context, page, ["date"]),
+        `Page is dated ${date.toISOString().slice(0, 10)}, which is in the future.`
+      ),
+    ];
+  }
+  return [];
+};
+
+/**
+ * Per-page head and body content: title, description, headings, word count,
+ * viewport.
+ *
+ * Ahrefs reports each of these twice — once for indexable pages and once for
+ * non-indexable ones. That's a crawler artifact: the finding is the same either
+ * way, so it's reported once and the page's indexability rides along on the
+ * snapshot.
+ */
+export const contentChecks: CheckModule = {
+  category: "content",
+  run(context) {
+    const found: Diagnostic[] = [];
+    for (const page of context.pages) {
+      found.push(
+        ...titleChecks(context, page),
+        ...descriptionChecks(context, page),
+        ...headingChecks(context, page),
+        ...futureDateChecks(context, page)
+      );
+
+      if (page.wordCount < context.thresholds.minWordCount && page.indexable) {
+        found.push(
+          finding(
+            "BLUME_AUDIT_LOW_WORD_COUNT",
+            pageSite(context, page),
+            `Page has ${page.wordCount} words of prose (excluding code blocks).`
+          )
+        );
+      }
+
+      if (!page.viewport) {
+        found.push(
+          finding(
+            "BLUME_AUDIT_VIEWPORT_MISSING",
+            pageSite(context, page),
+            "Page has no viewport <meta> — it will not render correctly on mobile."
+          )
+        );
+      }
+    }
+    return found;
+  },
+  tier: "static",
+};

package/src/audit/checks/duplicates.ts

@@ -0,0 +1,131 @@
+import type { Diagnostic } from "../../core/types.ts";
+import { finding } from "../catalog.ts";
+import type { CheckId } from "../catalog.ts";
+import { pageSite } from "../locate.ts";
+import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
+
+const isNonCanonical = (page: PageSnapshot): boolean => {
+  if (!page.canonical) {
+    return false;
+  }
+  try {
+    return (
+      new URL(page.canonical).pathname.replace(/\/$/u, "") !==
+      page.url.replace(/\/$/u, "")
+    );
+  } catch {
+    return false;
+  }
+};
+
+/** Pages that can meaningfully be compared against each other for duplication. */
+const comparable = (context: AuditContext): PageSnapshot[] =>
+  context.pages.filter(
+    (page) =>
+      page.indexable &&
+      // A fallback page renders the default locale's content at a localized URL.
+      // It is *supposed* to be an exact copy, so comparing it would make every
+      // i18n site with an untranslated page a wall of false positives.
+      !page.route?.fallback &&
+      // A page that points its canonical elsewhere has already declared itself a
+      // duplicate; that's the mechanism working, not a finding.
+      !isNonCanonical(page)
+  );
+
+/**
+ * Group pages by a value and report every group with more than one member.
+ * Translations are kept apart by keying on locale as well as the value — two
+ * pages titled "Overview" in different languages are not duplicates.
+ */
+const reportGroups = (
+  context: AuditContext,
+  pages: PageSnapshot[],
+  id: CheckId,
+  key: (page: PageSnapshot) => string | undefined,
+  describe: (value: string, others: PageSnapshot[]) => string,
+  frontmatterKey?: readonly string[]
+): Diagnostic[] => {
+  const groups = new Map<string, PageSnapshot[]>();
+  for (const page of pages) {
+    const value = key(page);
+    if (!value) {
+      continue;
+    }
+    const groupKey = `${page.route?.locale ?? ""}\u0000${value}`;
+    const group = groups.get(groupKey);
+    if (group) {
+      group.push(page);
+    } else {
+      groups.set(groupKey, [page]);
+    }
+  }
+
+  const found: Diagnostic[] = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) {
+      continue;
+    }
+    for (const page of group) {
+      const others = group.filter((other) => other !== page);
+      found.push(
+        finding(
+          id,
+          pageSite(context, page, frontmatterKey),
+          describe(key(page) ?? "", others)
+        )
+      );
+    }
+  }
+  return found;
+};
+
+const list = (pages: PageSnapshot[]): string => {
+  const shown = pages.slice(0, 3).map((page) => page.url);
+  const rest = pages.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
+};
+
+/**
+ * Pages that collide on title, description, or body text.
+ *
+ * Ahrefs only reports "duplicate pages without canonical". Duplicate *titles*
+ * and *descriptions* are the ones that actually bite a docs site — five pages
+ * called "Overview" all compete for the same result headline — so they're
+ * reported too.
+ */
+export const duplicateChecks: CheckModule = {
+  category: "duplicates",
+  run(context) {
+    const pages = comparable(context);
+    return [
+      ...reportGroups(
+        context,
+        pages,
+        "BLUME_AUDIT_DUPLICATE_TITLE",
+        (page) => page.titles[0],
+        (value, others) => `Title "${value}" is also used by ${list(others)}.`,
+        ["title"]
+      ),
+      ...reportGroups(
+        context,
+        pages,
+        "BLUME_AUDIT_DUPLICATE_DESCRIPTION",
+        (page) => page.descriptions[0],
+        (_value, others) => `Meta description is identical to ${list(others)}.`,
+        ["description"]
+      ),
+      ...reportGroups(
+        context,
+        // An empty page (no prose at all) hashes the same as every other empty
+        // page; that's a content problem LOW_WORD_COUNT already reports, not a
+        // duplication one.
+        pages.filter((page) => page.wordCount > 0),
+        "BLUME_AUDIT_DUPLICATE_CONTENT",
+        (page) => page.contentHash,
+        (_value, others) =>
+          `Page content is byte-identical to ${list(others)}, and none declares a canonical.`
+      ),
+    ];
+  },
+  tier: "static",
+};