@nurkamol/seo-audit 1.35.0 → 1.37.0

package/README.md

@@ -205,7 +205,62 @@ brew install --cask seo-audit
 ./mac/build.sh --run
 ```
 
-<p align="center"><img src="docs/shots/app.png" alt="The macOS app showing a report: 25 pages, 171 findings, 55 things to change" width="820"></p>
+<p align="center"><img src="docs/shots/app.png" alt="The macOS app showing a real audit of astro.build: 60 pages, 232 findings, 37 things to change, scored 87 out of 100" width="820"></p>
+
+<p align="center"><em>A real run against astro.build — and the one error at the top is a link to a page that does not exist, which is the bug this tool was written to catch.</em></p>
+
+<p align="center"><img src="docs/shots/compare.png" alt="The compare sheet: docs.astro.build against astro.build, showing the 26 findings that appeared" width="820"></p>
+
+<p align="center"><em>Compare two runs: a site against itself last week, or one property against another. Different hosts are matched by path.</em></p>
+
+#### If you downloaded the zip instead: "SEO Audit is damaged and can't be opened"
+
+It is not damaged. The app is **ad-hoc signed** rather than notarised, because
+notarising needs a paid Apple Developer account this project does not have.
+macOS puts a `com.apple.quarantine` flag on anything a browser downloads, and
+for an app without a notarisation ticket Gatekeeper refuses it — with a message
+that says "damaged" and offers to move it to the Trash, which reads exactly like
+malware and is the single most confusing thing about installing this.
+
+**`brew install --cask seo-audit` does not have this problem.** Homebrew checks
+the download against a checksum written by the build that produced it, then
+clears the flag for you. That is the recommended route, and the rest of this
+section is for people who would rather not use Homebrew.
+
+If you downloaded the zip by hand, verify it first. Every release attaches a
+`SHA256SUMS.txt` covering all four downloads, and lists the same checksums in
+its notes — save it next to the file and:
+
+```bash
+shasum -a 256 --ignore-missing -c SHA256SUMS.txt
+```
+
+`--ignore-missing` because you almost certainly downloaded one of the four, not
+all of them. The same command verifies the `.deb`, the `.AppImage` and the
+`setup.exe`, which matters most on Windows, where the advice for SmartScreen is
+otherwise just "run it anyway".
+
+Then, once it matches, clear the flag:
+
+```bash
+xattr -dr com.apple.quarantine "/Applications/SEO Audit.app"
+```
+
+No `sudo`: the app is yours, in a directory you can write to, and the command
+works as you. If it ever answers `Operation not permitted`, the copy is owned by
+another user — `sudo xattr -dr com.apple.quarantine "/Applications/SEO Audit.app"`
+is the fallback, but reach for it second, not first.
+
+This is exactly what right-click → **Open** does in the Finder, minus the
+dialog. Do it because the checksum matched, not because a README said to — the
+same command on a file you have not checked is how people get hurt.
+
+Or avoid the question entirely and build it yourself, which produces a signature
+your own machine already trusts:
+
+```bash
+./mac/build.sh --run
+```
 
 SwiftUI throughout, Liquid Glass, and the report drawn natively: cause cards
 that expand into the pages they affect, filtering, search, and export as PDF,
@@ -478,6 +533,7 @@ reason.
 |---|---|---|
 | `--md <file>` | — | Write a Markdown report |
 | `--html <file>` | — | Write a self-contained HTML report — one file, no assets |
+| `--reports [date]` | — | List the runs kept on this machine and stop. With a date, only those finished on or after it |
 | `--since <date>` | — | Crawl only URLs the sitemap says changed on or after this date. Refuses when `lastmod` cannot answer it |
 | `--exclude <glob>` | — | Leave URLs out of the crawl. Repeatable; `*` stops at a slash, `**` does not |
 | `--dry-run` | — | Say what would be crawled and stop. A handful of requests instead of hundreds |

package/bin/seo-audit.mjs

@@ -45,6 +45,8 @@ const HELP = `
                        strings the crawl actually read. A page whose trail
                        has an uncrawled step is skipped rather than given a
                        name invented from its slug
+    --reports [date]   list the runs kept on this machine and stop; with a
+                       date, only those finished on or after it
     --since <date>     crawl only URLs the sitemap says changed on or after
                        this date. Refuses when lastmod cannot answer it —
                        absent, or one build stamp on every URL
@@ -152,6 +154,14 @@ function parseArgs(argv) {
     else if (arg === '--verbose') opts.verbose = true;
     else if (arg === '--dry-run') opts.dryRun = true;
     else if (arg === '--since') opts.since = value();
+    // The only flag here whose value is optional: `--reports` lists everything
+    // kept, `--reports 2026-08-01` lists what was kept since. Peeked rather
+    // than consumed, so `--reports` followed by nothing, or by another flag,
+    // does not swallow it.
+    else if (arg === '--reports') {
+      const next = argv[i + 1];
+      opts.reports = next !== undefined && !next.startsWith('-') ? argv[++i] : true;
+    }
     // Repeatable: one pattern per flag reads better than one flag with a
     // comma-separated list, and a URL can contain a comma.
     else if (arg === '--exclude') (opts.exclude ??= []).push(value());
@@ -299,6 +309,43 @@ const live = (origin) =>
 // the config may carry its own overrides, which land on top of the shared ones.
 let sites = resolveSites(cli.targets ?? [], file);
 
+// The runs kept on this machine. Also a different program: it reads the same
+// folder the window and `--serve` read, and crawls nothing.
+if (opts.reports !== undefined) {
+  const { library } = await import('../src/library.mjs');
+  const { sinceWhen, keptSince } = await import('../src/kept.mjs');
+  const asked = sinceWhen(opts.reports === true ? null : opts.reports);
+  if (asked.error) {
+    console.error(`\n  --reports wants ${asked.error}\n`);
+    process.exit(2);
+  }
+
+  const store = library();
+  const all = store.list();
+  const rows = keptSince(all, asked.at);
+
+  if (!all.length) {
+    console.log(`\n  Nothing kept yet. Finished runs are kept in ${store.where()}\n`);
+  } else if (!rows.length) {
+    // Saying how many were skipped, because an empty list and an empty library
+    // read identically and only one of them means "widen the date".
+    console.log(`\n  None of the ${all.length} kept runs finished on or after that date.\n`);
+  } else {
+    const width = Math.max(...rows.map((r) => (r.site ?? '').length));
+    console.log('');
+    for (const row of rows) {
+      const when = String(row.finishedAt ?? '').slice(0, 10);
+      const score = row.score === undefined || row.score === null ? '  —' : String(row.score).padStart(3);
+      console.log(
+        `  ${(row.site ?? '').padEnd(width)}  ${when}  ${String(row.pages ?? '?').padStart(5)} pages  ${score}`,
+      );
+    }
+    const shown = rows.length === all.length ? `${all.length}` : `${rows.length} of ${all.length}`;
+    console.log(`\n  ${shown} kept in ${store.where()}\n`);
+  }
+  process.exit(0);
+}
+
 // The local UI, which is a different program from here on: no target, no
 // report file, and it runs until interrupted.
 // `!== undefined` rather than truthiness: --serve 0 asks the operating system

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurkamol/seo-audit",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Crawl a site's sitemap and check every page for SEO, metadata and structured-data problems that single-page graders miss. Zero dependencies.",
   "type": "module",
   "bin": {

package/src/audit.mjs

@@ -15,6 +15,7 @@ import { applyIgnores, expectationChecks, matchGlob } from './config.mjs';
 import { psiChecks, psiTargets, estimateSeconds } from './psi.mjs';
 import { sectionOf } from './causes.mjs';
 import { rebuild, changedSince } from './sitemap.mjs';
+import { plural } from './text.mjs';
 
 /** Sitemap URLs, following a sitemap index one level down.
  *
@@ -246,7 +247,7 @@ export async function audit(target, opts = {}) {
         ? {
             level: 'error',
             id: 'tls-expired',
-            title: `The TLS certificate expired ${lapsed} day(s) ago`,
+            title: `The TLS certificate expired ${plural(lapsed, 'day')} ago`,
             detail:
               `It ran out on ${new Date(expiresAt).toISOString().slice(0, 10)}, which is why nothing here ` +
               'could be fetched — browsers refuse the site outright. Renew it; nothing else about this ' +
@@ -307,9 +308,9 @@ export async function audit(target, opts = {}) {
       findings.push({
         level: 'info',
         id: 'since',
-        title: `${changed.skipped.length} URL(s) were unchanged since ${opts.since}`,
+        title: `${plural(changed.skipped.length, 'URL')} were unchanged since ${opts.since}`,
         detail:
-          `The sitemap says ${changed.changed.length} page(s) changed on or after ${opts.since}` +
+          `The sitemap says ${plural(changed.changed.length, 'page')} changed on or after ${opts.since}` +
           (changed.unknown.length
             ? `, and ${changed.unknown.length} carry no lastmod and were checked anyway — not knowing ` +
               'when a page changed is not evidence that it did not'
@@ -342,7 +343,7 @@ export async function audit(target, opts = {}) {
     findings.push({
       level: 'info',
       id: 'excluded',
-      title: `${excluded.length} URL(s) were excluded by --exclude`,
+      title: `${plural(excluded.length, 'URL')} were excluded by --exclude`,
       detail:
         `${patterns.join(', ')} matched ${excluded.length} of the ${considered.length} URLs considered, ` +
         `so ${wanted.length} were left to check. This is a fact about the run, not about the site — ` +
@@ -400,7 +401,7 @@ export async function audit(target, opts = {}) {
             detail:
               `Tried: ${tried.join(', ')}. The server answered HTTP 429 — "ask later" — so this run ` +
               'never saw whether a sitemap is there, and followed links from the homepage instead, ' +
-              `reaching ${pages.length} page(s). This is a fact about the crawl, not about the site. ` +
+              `reaching ${plural(pages.length, 'page')}. This is a fact about the crawl, not about the site. ` +
               'Run it again with a lower --concurrency, or pass --sitemap <url>.',
             url: origin,
           }
@@ -504,7 +505,7 @@ export async function audit(target, opts = {}) {
     findings.push(...notes);
     if (targets.length) {
       opts.onNote?.(
-        `measuring ${targets.length} page(s) with PageSpeed Insights — about ` +
+        `measuring ${plural(targets.length, 'page')} with PageSpeed Insights — about ` +
           `${Math.ceil(estimateSeconds(targets.length) / 60)} min …`,
       );
       findings.push(...(await psiChecks(targets, { strategy: opts.psiStrategy, onProgress })));
@@ -521,7 +522,7 @@ export async function audit(target, opts = {}) {
       id: 'rate-limit-slowed',
       title: 'The crawl was slowed down to get through',
       detail:
-        `The server answered HTTP 429 — asking for a slower crawl — ${fetcher.rateLimited} time(s), so ` +
+        `The server answered HTTP 429 — asking for a slower crawl — ${plural(fetcher.rateLimited, 'time')}, so ` +
         `requests were paused and the concurrency came down to ${fetcher.concurrency}. This is not a ` +
         'finding about the site — it explains the elapsed time, and any page reported as rate-limited ' +
         'was not read at all. Pass a lower --concurrency to get through cleanly.',
@@ -602,7 +603,7 @@ export async function audit(target, opts = {}) {
       findings.push({
         level: 'warn',
         id: 'sitemap-not-indexable',
-        title: `${contradictions.length} sitemap URL(s) will not be indexed`,
+        title: `${plural(contradictions.length, 'sitemap URL')} will not be indexed`,
         detail:
           `${contradictions.slice(0, 3).map((p) => `${p.url} (${why(p)})`).join(', ')}` +
           `${contradictions.length > 3 ? `, and ${contradictions.length - 3} more` : ''}. A sitemap is a ` +

package/src/causes.mjs

@@ -13,6 +13,7 @@
 // guesses at severity or invents a score; it groups, counts, and orders.
 
 import { categoryOf } from './areas.mjs';
+import { noun } from './text.mjs';
 
 /** The template a URL belongs to: everything up to its last segment.
  *
@@ -53,16 +54,41 @@ const WORST_FIRST = { error: 0, warn: 1, info: 2 };
  *
  *  Ordered by level, then by how many pages carry it, then by id so two runs of
  *  an unchanged site produce the same report and --baseline stays meaningful. */
-export function byCause(findings) {
+export function byCause(findings, totalPages = 0) {
+  // A check that fires on every page crawled is not a section problem, and
+  // splitting it by section makes the reader do arithmetic to find that out.
+  // gohugo.io produced 200 things to change, and 104 of them were four checks
+  // that each applied to all 150 pages — `canonical-missing` alone arrived as
+  // twenty-six separate pieces of work. One sentence says it better than
+  // twenty-six do.
+  //
+  // Exactly every page, never nearly: on 149 of 150, "every page" is a false
+  // sentence, and this file's whole argument is that a report is worth reading
+  // because its sentences are true.
+  const everywhere = new Set();
+  if (totalPages > 1) {
+    const seenPerCheck = new Map();
+    for (const finding of findings ?? []) {
+      if (!finding.url) continue;
+      if (!seenPerCheck.has(finding.id)) seenPerCheck.set(finding.id, new Set());
+      seenPerCheck.get(finding.id).add(finding.url);
+    }
+    for (const [id, pages] of seenPerCheck) {
+      if (pages.size === totalPages) everywhere.add(id);
+    }
+  }
+
   const causes = new Map();
   for (const finding of findings ?? []) {
-    const section = sectionOf(finding.url);
+    const onEveryPage = everywhere.has(finding.id);
+    const section = onEveryPage ? '*' : sectionOf(finding.url);
     const key = `${finding.id} ${section}`;
     const cause = causes.get(key) ?? {
       id: finding.id,
       title: finding.title,
       level: finding.level,
       section,
+      everywhere: onEveryPage,
       findings: [],
     };
     cause.findings.push(finding);
@@ -135,16 +161,26 @@ export function causeScope(cause, totalPages) {
   const pages = cause.pages.length;
   if (pages <= 1) return cause.section === '/' ? 'once' : `on one page under ${cause.section}`;
 
-  const where = cause.section === '/' ? 'across the site' : `under ${cause.section}`;
+  const where = cause.everywhere
+    ? null
+    : cause.section === '/'
+      ? 'across the site'
+      : `under ${cause.section}`;
   const share =
     totalPages && pages / totalPages >= 0.5 ? `, ${Math.round((pages / totalPages) * 100)}% of the crawl` : '';
   const seen = cause.impressions
-    ? `, ${cause.impressions.toLocaleString()} impressions in 28 days` +
+    ? `, ${cause.impressions.toLocaleString()} ${noun(cause.impressions, 'impression')} in 28 days` +
       (cause.position ? `, best at position ${cause.position}` : '')
     : '';
-  const reach = seen || (cause.inlinks ? `, ${cause.inlinks.toLocaleString()} links in` : '');
+  // "1 links in" — found by running this against a real site, which is the only
+  // way anything here has ever been found.
+  const reach =
+    seen || (cause.inlinks ? `, ${cause.inlinks.toLocaleString()} ${noun(cause.inlinks, 'link')} in` : '');
   const near =
     cause.depth === 0 ? ', starting at the homepage' : cause.depth === 1 ? ', one click from home' : '';
+  // No share for a cause that is on everything: "100% of the crawl" is the
+  // sentence it already just said.
+  if (where === null) return `every page crawled (${pages})${reach}${near}`;
   return `${pages} pages ${where}${share}${reach}${near}`;
 }
 
@@ -159,11 +195,14 @@ export function causeScope(cause, totalPages) {
  *  terminal, the HTML and the app all print, and a second phrasing of it in
  *  another language is exactly the drift this project refuses everywhere else. */
 export function causePayload(findings, totalPages) {
-  return byCause(findings).map((cause) => ({
+  return byCause(findings, totalPages).map((cause) => ({
     id: cause.id,
     title: cause.title,
     level: cause.level,
     section: cause.section,
+    // So a native client can say "every page" in its own words rather than
+    // matching on the sentence this file writes.
+    ...(cause.everywhere ? { everywhere: true } : {}),
     count: cause.count,
     pages: cause.pages,
     scope: causeScope(cause, totalPages),

package/src/checks.mjs

@@ -14,6 +14,7 @@ import { linkGraph, key as graphKey } from './graph.mjs';
 
 import { attr, bodyKind, stripMarkupInAttributes } from './parse.mjs';
 import { cluster } from './dupes.mjs';
+import { plural } from './text.mjs';
 
 // Defaults, overridable per site under `limits` in the config file. A
 // documentation site and a shop disagree about what "thin" means, and the tool
@@ -602,7 +603,7 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
     // An <img> can have no src either — a lazy-loading placeholder, or markup
     // waiting on JavaScript. Saying "First: null" helped nobody find it.
     const where = noAlt[0].src ?? 'an <img> with no src attribute either';
-    out.push(f('error', 'img-alt', `${noAlt.length} image(s) with no alt attribute`,
+    out.push(f('error', 'img-alt', `${plural(noAlt.length, 'image')} with no alt attribute`,
       `First: ${where}. Decorative images need alt="" — the attribute must exist either way.`, url));
   }
   // Alt text that exists but says nothing. alt="" is deliberate and correct for
@@ -613,13 +614,13 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
 
   const filename = described.filter((i) => ALT_FILENAME.test(i.alt.trim()) || ALT_SERIAL.test(i.alt.trim()));
   if (filename.length) {
-    out.push(f('warn', 'img-alt-filename', `${filename.length} image(s) with a filename as alt text`,
+    out.push(f('warn', 'img-alt-filename', `${plural(filename.length, 'image')} with a filename as alt text`,
       `First: alt="${filename[0].alt}" on ${filename[0].src}. That is what a CMS fills in when nobody typed anything — it describes the file, not the picture.`, url));
   }
 
   const placeholder = described.filter((i) => ALT_PLACEHOLDER.has(norm(i)));
   if (placeholder.length) {
-    out.push(f('warn', 'img-alt-placeholder', `${placeholder.length} image(s) with placeholder alt text`,
+    out.push(f('warn', 'img-alt-placeholder', `${plural(placeholder.length, 'image')} with placeholder alt text`,
       `First: alt="${placeholder[0].alt}" on ${placeholder[0].src}. It names the medium, not the content — a screen reader already announces "image" before reading it.`, url));
   }
 
@@ -645,7 +646,7 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
     (i) => i.title && i.alt && i.title.trim() === i.alt.trim(),
   );
   if (titledSameAsAlt.length) {
-    out.push(f('info', 'img-title-duplicates-alt', `${titledSameAsAlt.length} image(s) repeat the alt text as a title`,
+    out.push(f('info', 'img-title-duplicates-alt', `${plural(titledSameAsAlt.length, 'image')} repeat the alt text as a title`,
       `First: "${titledSameAsAlt[0].title}" on ${titledSameAsAlt[0].src}. One field filling both is the usual ` +
         'cause. It adds nothing for a sighted visitor and a screen reader that surfaces both reads it twice.', url));
   }
@@ -654,7 +655,7 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
     (i) => i.title && (i.alt === '' || decorativeByRole(i)),
   );
   if (titledDecorative.length) {
-    out.push(f('info', 'img-title-on-decorative', `${titledDecorative.length} decorative image(s) carry a title`,
+    out.push(f('info', 'img-title-on-decorative', `${plural(titledDecorative.length, 'decorative image')} carry a title`,
       `First: "${titledDecorative[0].title}" on ${titledDecorative[0].src}. The markup declares the image ` +
         'decorative and then attaches a tooltip to it — one of the two is wrong.', url));
   }
@@ -672,7 +673,7 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
     (i) => /^lazy$/i.test(i.loading ?? '') && /^high$/i.test(i.fetchpriority ?? ''),
   );
   if (hurriedAndDeferred.length) {
-    out.push(f('info', 'img-lazy-priority', `${hurriedAndDeferred.length} image(s) are both deferred and prioritised`,
+    out.push(f('info', 'img-lazy-priority', `${plural(hurriedAndDeferred.length, 'image')} are both deferred and prioritised`,
       `First: ${hurriedAndDeferred[0].src}. loading="lazy" and fetchpriority="high" on one element ask ` +
         'for opposite things, and lazy decides when the request happens. If this is the image the page ' +
         'is judged on, drop the lazy; if it is not, drop the priority.', url));
@@ -680,18 +681,18 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
 
   const longAlt = described.filter((i) => i.alt.length > ALT_MAX);
   if (longAlt.length) {
-    out.push(f('info', 'img-alt-long', `${longAlt.length} image(s) with very long alt text`,
+    out.push(f('info', 'img-alt-long', `${plural(longAlt.length, 'image')} with very long alt text`,
       `First: ${longAlt[0].alt.length} chars on ${longAlt[0].src}. Alt is read in one breath, with no way to skim — a description this long belongs in the page text, where everyone gets it.`, url));
   }
 
   const noDim = doc.images.filter((i) => i.src && (!i.width || !i.height));
   if (noDim.length) {
-    out.push(f('warn', 'img-dimensions', `${noDim.length} image(s) without width/height`,
+    out.push(f('warn', 'img-dimensions', `${plural(noDim.length, 'image')} without width/height`,
       `First: ${noDim[0].src}. Without them the page reflows as images arrive (layout shift).`, url));
   }
   const noSrcset = doc.images.filter((i) => i.src && !i.srcset && !i.inPicture && !/\.svg($|\?)/i.test(i.src));
   if (noSrcset.length) {
-    out.push(f('info', 'img-srcset', `${noSrcset.length} image(s) served at one size`,
+    out.push(f('info', 'img-srcset', `${plural(noSrcset.length, 'image')} served at one size`,
       `First: ${noSrcset[0].src}. A phone downloads the desktop file.`, url));
   }
 
@@ -705,7 +706,7 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
   // crawled — so a note, not a complaint.
   const nofollowed = doc.links.nofollowInternal ?? [];
   if (nofollowed.length) {
-    out.push(f('info', 'internal-nofollow', `${nofollowed.length} internal link(s) marked nofollow`,
+    out.push(f('info', 'internal-nofollow', `${plural(nofollowed.length, 'internal link')} marked nofollow`,
       `First: ${nofollowed.slice(0, 3).join(', ')}. Fair for a login or a filter nobody should crawl; ` +
         'on an ordinary page it withholds a path through your own site for no gain.', url));
   }
@@ -874,7 +875,7 @@ export function sitemapChecks(entries, source, now = Date.now(), files = []) {
   });
   if (listedTwice.length) {
     const [loc, inFiles] = listedTwice[0];
-    out.push(f('info', 'sitemap-duplicate-url', `${listedTwice.length} URL(s) are listed more than once`,
+    out.push(f('info', 'sitemap-duplicate-url', `${plural(listedTwice.length, 'URL')} are listed more than once`,
       `First: ${loc}${inFiles.size > 1 ? `, in ${[...inFiles].join(' and ')}` : ' — twice in one file'}. ` +
         'A sitemap is a list of the pages you want indexed, and listing one twice says nothing extra ' +
         'while making the file harder to trust.', source ?? loc));
@@ -897,7 +898,7 @@ export function sitemapChecks(entries, source, now = Date.now(), files = []) {
     return Number.isFinite(at) && at > now + DAY;
   });
   if (future.length) {
-    out.push(f('warn', 'sitemap-lastmod-future', `${future.length} page(s) claim a lastmod in the future`,
+    out.push(f('warn', 'sitemap-lastmod-future', `${plural(future.length, 'page')} claim a lastmod in the future`,
       `First: ${future[0].loc} says ${future[0].lastmod}. A date that has not happened yet is not a ` +
         'signal a crawler can use, and it is usually a timezone or a scheduling bug in the generator.', source));
   }
@@ -975,7 +976,7 @@ export function crossPageChecks(pages, opts = {}) {
   const uncomparable = live.filter((p) => !p.doc.fingerprint).length;
   if (uncomparable > 0 && live.length > 1) {
     out.push(f('info', 'duplicate-content-not-checked',
-      `${uncomparable} page(s) were not compared for duplicate content`,
+      `${plural(uncomparable, 'page')} were not compared for duplicate content`,
       'Content is compared inside <main> or <article>. Without one of those the text of a page is ' +
         'the whole document, navigation and footer included, and every page of a small site would ' +
         'look like a copy of every other. Pages under about a hundred words are skipped for the ' +
@@ -997,7 +998,7 @@ export function crossPageChecks(pages, opts = {}) {
   const unfetched = pages.length - live.length;
   const partial =
     opts.truncated > 0
-      ? `the crawl stopped ${opts.truncated} page(s) short of the whole site`
+      ? `the crawl stopped ${plural(opts.truncated, 'page')} short of the whole site`
       : unfetched > pages.length * 0.1
         ? `${unfetched} of ${pages.length} crawled pages did not load`
         : null;
@@ -1148,7 +1149,7 @@ export function crossPageChecks(pages, opts = {}) {
   for (const [href, pages] of namelessTargets.slice(0, 10)) {
     out.push(f('warn', 'link-no-text', 'Link with nothing to read',
       `${href} is linked with no text, no image alt, no aria-label and no title, from ` +
-        `${pages.length} page(s): ${pages.slice(0, 3).join(', ')}. Google is told the page exists and ` +
+        `${plural(pages.length, 'page')}: ${pages.slice(0, 3).join(', ')}. Google is told the page exists and ` +
         'nothing about it, and a screen reader announces the URL instead of a description.',
       pages[0]));
   }
@@ -1171,7 +1172,7 @@ export function crossPageChecks(pages, opts = {}) {
     const names = inbound.get(withoutSlash(p.url));
     const shown = [...new Set(names.map((n) => `"${n}"`))].slice(0, 3).join(', ');
     out.push(f('info', 'anchor-generic', 'Every link to this page says the same empty thing',
-      `${names.length} link(s) point here and all of them read ${shown}. Anchor text is the one ` +
+      `${plural(names.length, 'link')} point here and all of them read ${shown}. Anchor text is the one ` +
         'description of a page that comes from somewhere other than the page itself, and this one has ' +
         'none — the words say what to do, not what is there.', p.url));
   }

package/src/kept.mjs

@@ -0,0 +1,40 @@
+// Which kept runs a date is asking for.
+//
+// Separate from `library.mjs` on purpose. That module opens files, so it
+// imports `node:fs` — and the Worker, which shows the same list in a browser,
+// has no filesystem and would not survive the import. These two functions are
+// the part both sides need and the part that is pure, so they live where both
+// can reach them. Web-standard only; nothing here may grow a Node built-in.
+
+/** A date on the command line or in a query string, as a timestamp.
+ *
+ *  `2026-08-01` means midnight UTC that day, so `--reports 2026-08-01` includes
+ *  everything from that day. A full ISO timestamp is taken as written.
+ *
+ *  Returns `{ error }` for anything it cannot read, and the callers refuse
+ *  rather than carrying on: listing every run when somebody asked for one week
+ *  is the quiet kind of wrong — it looks like an answer. */
+export function sinceWhen(value) {
+  if (value === undefined || value === null || value === '') return { at: null };
+  const text = String(value).trim();
+  const at = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(text) ? `${text}T00:00:00Z` : text);
+  if (Number.isNaN(at)) {
+    return { error: `a date like 2026-08-01 or a full timestamp, not "${text}"` };
+  }
+  return { at };
+}
+
+/** Kept runs finished on or after `at`, in the order they were given.
+ *
+ *  Pure, and web-standard: the CLI and the hosted list both call it, so the two
+ *  cannot disagree about what "since" means — which is the drift this project
+ *  refuses everywhere else. A run with no readable date is kept rather than
+ *  dropped: an index written by an older version should not vanish from a
+ *  filtered list without saying so. */
+export function keptSince(rows, at) {
+  if (at === null || at === undefined) return rows ?? [];
+  return (rows ?? []).filter((row) => {
+    const when = Date.parse(row?.finishedAt ?? '');
+    return Number.isNaN(when) ? true : when >= at;
+  });
+}

package/src/llms.mjs

@@ -19,6 +19,7 @@
 // need a parser.
 
 import { sectionOf } from './causes.mjs';
+import { plural } from './text.mjs';
 
 /** Markdown's structural characters, inside text that came off a page.
  *
@@ -54,13 +55,13 @@ export function buildLlms(pages, context = {}) {
 
   if (truncated > 0) {
     return refuse(
-      `The crawl stopped at its limit with ${truncated} URL(s) unread, so this file would present a ` +
+      `The crawl stopped at its limit with ${plural(truncated, 'URL')} unread, so this file would present a ` +
         `fraction of the site as the whole of it. Run again with --limit ${pages.length + truncated}.`,
     );
   }
   if (rateLimited > 0) {
     return refuse(
-      `${rateLimited} page(s) were never read because the server was rate limiting, so what belongs ` +
+      `${plural(rateLimited, 'page')} were never read because the server was rate limiting, so what belongs ` +
         'in this file is not known. Run again with a lower --concurrency.',
     );
   }
@@ -154,7 +155,7 @@ const REASONS = {
 /** The summary line for a terminal, and for the note the CLI prints. */
 export function describeLlms(result, path) {
   if (result.refused) return `  Did not write ${path}: ${result.refused}\n`;
-  const out = [`  wrote ${path} — ${result.urls.length} pages in ${result.sections} section(s)`];
+  const out = [`  wrote ${path} — ${result.urls.length} pages in ${plural(result.sections, 'section')}`];
   for (const [reason, count] of Object.entries(result.excluded).sort((a, b) => b[1] - a[1])) {
     out.push(`    dropped ${String(count).padEnd(3)} (${REASONS[reason] ?? reason})`);
   }

package/src/options.mjs

@@ -84,6 +84,7 @@ export const OPTIONS = [
   { flag: '--quiet', query: null, app: 'the crawl log is on screen while it runs' },
   { flag: '--verbose', query: null, app: 'the crawl log is on screen while it runs' },
   { flag: '--serve', query: null, app: 'the window is what --serve serves' },
+  { flag: '--reports', query: null, app: 'the sidebar is this list, and it is always on' },
   { flag: '--fail-on', query: null, app: 'a window has no exit code for a build to read' },
   { flag: '--update-baseline', query: null, app: 'a baseline is a file a repository commits' },
   { flag: '--config', query: null, app: 'a config file is a file a repository commits' },

package/src/redirects.mjs

@@ -16,6 +16,8 @@
 // A rule with a wildcard or a placeholder cannot be tested by asking for it
 // literally, so those are counted and reported rather than guessed at.
 
+import { plural } from './text.mjs';
+
 const HAS_PATTERN = /[*:]/;
 
 /** Rules from a redirect map. `to` and `status` may be null. */
@@ -56,13 +58,13 @@ export async function redirectChecks(rules, fetcher, origin, { limit = 200, onPr
   const checked = testable.slice(0, limit);
 
   if (patterned.length) {
-    out.push(f('info', 'redirect-pattern-skipped', `${patterned.length} wildcard rule(s) were not tested`,
+    out.push(f('info', 'redirect-pattern-skipped', `${plural(patterned.length, 'wildcard rule')} were not tested`,
       `Rules like ${patterned.slice(0, 2).map((r) => r.from).join(', ')} match a shape rather than a URL, ` +
         'so asking for them literally proves nothing. Add a real example of each to the map, or test them by hand.',
       origin));
   }
   if (testable.length > checked.length) {
-    out.push(f('info', 'redirect-map-capped', `${testable.length - checked.length} rule(s) were not tested`,
+    out.push(f('info', 'redirect-map-capped', `${plural(testable.length - checked.length, 'rule')} were not tested`,
       `The map has ${testable.length} testable rules and the limit is ${limit}. Raise it with maxRedirectChecks.`,
       origin));
   }
@@ -128,17 +130,17 @@ export async function redirectChecks(rules, fetcher, origin, { limit = 200, onPr
       `${shown}${lines.length > 3 ? `, and ${lines.length - 3} more` : ''}. ${detail}`, origin));
   };
 
-  say('gone', 'error', 'redirect-dead', (n) => `${n} old URL(s) in the redirect map are simply gone`,
+  say('gone', 'error', 'redirect-dead', (n) => `${plural(n, 'old URL')} in the redirect map are simply gone`,
     'The rule is not in effect, so every link and every ranking pointing at these lands on nothing.');
-  say('broken', 'error', 'redirect-broken', (n) => `${n} redirect(s) land on a page that does not load`,
+  say('broken', 'error', 'redirect-broken', (n) => `${plural(n, 'redirect')} land on a page that does not load`,
     'The rule fires and then arrives nowhere, which is worse than no rule: it looks handled.');
-  say('notRedirecting', 'warn', 'redirect-not-applied', (n) => `${n} old URL(s) answer 200 instead of redirecting`,
+  say('notRedirecting', 'warn', 'redirect-not-applied', (n) => `${plural(n, 'old URL')} answer 200 instead of redirecting`,
     'The map says these moved, and the server disagrees. Either the rule never shipped or something serves the old path.');
-  say('hops', 'warn', 'redirect-hops', (n) => `${n} redirect(s) take more than one hop`,
+  say('hops', 'warn', 'redirect-hops', (n) => `${plural(n, 'redirect')} take more than one hop`,
     'Each hop is a round trip a visitor and a crawler both pay for. Point the first rule at the final URL.');
-  say('elsewhere', 'warn', 'redirect-elsewhere', (n) => `${n} redirect(s) land somewhere the map does not expect`,
+  say('elsewhere', 'warn', 'redirect-elsewhere', (n) => `${plural(n, 'redirect')} land somewhere the map does not expect`,
     'Another rule is probably matching first. The map is no longer describing what the site does.');
-  say('temporary', 'warn', 'redirect-temporary', (n) => `${n} permanent redirect(s) are served as 302`,
+  say('temporary', 'warn', 'redirect-temporary', (n) => `${plural(n, 'permanent redirect')} are served as 302`,
     'A 302 tells Google the move is temporary, so it keeps the old URL indexed and passes less through it.');
 
   return out;

package/src/report.mjs

@@ -22,8 +22,8 @@ const PAINT = { error: red, warn: yellow, info: blue };
  *  know is that they are 62 pieces of work and four of them are most of it.
  *  Shown when there is something to summarise — under a handful of causes the
  *  list below already reads as the summary. */
-export function worstCauses(findings, limit = 8) {
-  const causes = byCause(findings);
+export function worstCauses(findings, totalPages = 0, limit = 8) {
+  const causes = byCause(findings, totalPages);
   return causes.length > limit + 2 ? causes.slice(0, limit) : [];
 }
 
@@ -127,9 +127,9 @@ export function terminal(findings, meta, { score } = {}) {
   }
 
   const costs = costsById(score);
-  const causes = worstCauses(findings);
+  const causes = worstCauses(findings, meta.pages);
   if (causes.length) {
-    const total = byCause(findings).length;
+    const total = byCause(findings, meta.pages).length;
     lines.push(rule('Start here'));
     lines.push('');
     lines.push(dim(`  ${findings.length} findings are ${total} things to change. The widest:`));
@@ -252,11 +252,11 @@ export function markdown(findings, meta, { score } = {}) {
   }
 
   const costs = costsById(score);
-  const causes = worstCauses(findings);
+  const causes = worstCauses(findings, meta.pages);
   if (causes.length) {
     out.push('## Start here');
     out.push('');
-    out.push(`${findings.length} findings are **${byCause(findings).length} things to change**. The widest:`);
+    out.push(`${findings.length} findings are **${byCause(findings, meta.pages).length} things to change**. The widest:`);
     out.push('');
     out.push('| | What to change | Where | Worth |');
     out.push('|:-:|---|---|--:|');
@@ -1193,11 +1193,12 @@ export function reportParts(findings, meta, { backHref, backLabel = 'New audit',
   ${dial()}
 
   ${(() => {
-    const causes = worstCauses(findings);
+    const causes = worstCauses(findings, meta.pages);
     if (!causes.length) return '';
+    const total = byCause(findings, meta.pages).length;
     return `<section class="causes">
-    <h2 id="start-here"><span>Start here</span><span class="rule"></span><span class="tick">${byCause(findings).length}</span></h2>
-    <p class="lede">${findings.length} findings are ${byCause(findings).length} things to change. The widest:</p>
+    <h2 id="start-here"><span>Start here</span><span class="rule"></span><span class="tick">${total}</span></h2>
+    <p class="lede">${findings.length} findings are ${total} things to change. The widest:</p>
     <ol>${causes
       .map((cause) => {
         const points = causeCost(cause, costs);

package/src/schema.mjs

@@ -27,6 +27,7 @@
 //     prettified slug.
 
 import { GENERIC_ANCHORS, anchorPhrase } from './checks.mjs';
+import { plural } from './text.mjs';
 
 const SCHEMA = 'https://schema.org';
 
@@ -163,14 +164,14 @@ export function buildSchema(pages, context = {}) {
 
   if (truncated > 0) {
     return refuse(
-      `The crawl stopped at its limit with ${truncated} URL(s) unread. A breadcrumb trail is only ` +
+      `The crawl stopped at its limit with ${plural(truncated, 'URL')} unread. A breadcrumb trail is only ` +
         'honest when every step of it was fetched, so this would silently describe fewer pages than ' +
         `it looks like. Run again with --limit ${pages.length + truncated}.`,
     );
   }
   if (rateLimited > 0) {
     return refuse(
-      `${rateLimited} page(s) were never read because the server was rate limiting, so the trails ` +
+      `${plural(rateLimited, 'page')} were never read because the server was rate limiting, so the trails ` +
         'through them cannot be built. Run again with a lower --concurrency.',
     );
   }
@@ -313,7 +314,7 @@ export function describeSchema(result, path) {
   for (const entry of result.generated) {
     types[entry.jsonld['@type']] = (types[entry.jsonld['@type']] ?? 0) + 1;
   }
-  const out = [`  wrote ${path} — ${result.generated.length} block(s) for ${new Set(result.generated.map((e) => e.url)).size} page(s)`];
+  const out = [`  wrote ${path} — ${plural(result.generated.length, 'block')} for ${plural(new Set(result.generated.map((e) => e.url)).size, 'page')}`];
   for (const [type, count] of Object.entries(types).sort((a, b) => b[1] - a[1])) {
     out.push(`    ${String(count).padEnd(4)} ${type}`);
   }

package/src/site.mjs

@@ -6,6 +6,7 @@ import { parseRobots, robotsVerdict } from './robots.mjs';
 import { aiAccess, describeAccess } from './agents-ai.mjs';
 import { parseHtml } from './parse.mjs';
 import { schemaNodes, seriesOf, paginatedCanonical } from './checks.mjs';
+import { plural } from './text.mjs';
 
 // Two weeks is enough to renew by hand if the automation has quietly stopped,
 // which is the failure this is for — nobody is short of warning about a
@@ -123,7 +124,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
       if (blocked.length) {
         const shown = blocked.slice(0, 3).map((b) => `${b.listed} (Disallow: ${b.rule.path})`).join(', ');
         out.push(f('error', 'robots-blocks-sitemap-url',
-          `${blocked.length} sitemap URL(s) are disallowed by robots.txt`,
+          `${plural(blocked.length, 'sitemap URL')} are disallowed by robots.txt`,
           `${shown}${blocked.length > 3 ? `, and ${blocked.length - 3} more` : ''}. The sitemap asks Google ` +
             'to index these and robots.txt forbids fetching them, so they land in the index without a ' +
             'description, or not at all. One of the two files is wrong.', robots.url));
@@ -149,7 +150,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
     const shut = describeAccess(access);
     if (shut) {
       out.push(f('info', 'ai-crawler-blocked',
-        `${shut.blocked.length} AI crawler(s) are disallowed by robots.txt`,
+        `${plural(shut.blocked.length, 'AI crawler')} are disallowed by robots.txt`,
         shut.detail, robotsUrl));
 
       // The site contradicting itself. llms.txt exists to tell an AI assistant
@@ -321,11 +322,11 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
       const days = Math.floor((expiresAt - (opts.now ?? Date.now())) / DAY);
       const on = new Date(expiresAt).toISOString().slice(0, 10);
       if (days < 0) {
-        out.push(f('error', 'tls-expired', `The TLS certificate expired ${-days} day(s) ago`,
+        out.push(f('error', 'tls-expired', `The TLS certificate expired ${plural(-days, 'day')} ago`,
           `It ran out on ${on}. Browsers refuse to load the site, so nothing else in this report matters ` +
             'until it is renewed.', origin));
       } else if (days <= CERT_WARN_DAYS) {
-        out.push(f('warn', 'tls-expiring', `The TLS certificate expires in ${days} day(s)`,
+        out.push(f('warn', 'tls-expiring', `The TLS certificate expires in ${plural(days, 'day')}`,
           `On ${on}. Usually this means automatic renewal has stopped without anyone noticing — the ` +
             'certificates that lapse are the ones nobody was worried about.', origin));
       }
@@ -441,7 +442,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
   // is a legitimate reason to have one.
   const redirecting = results.filter((r) => r.status >= 300 && r.status < 400);
   if (redirecting.length) {
-    out.push(f('info', 'link-redirects', `${redirecting.length} internal link(s) point at a redirect`,
+    out.push(f('info', 'link-redirects', `${plural(redirecting.length, 'internal link')} point at a redirect`,
       `First: ${redirecting.slice(0, 3).map((r) => `${r.target} (${r.status})`).join(', ')}. ` +
         'Linking to the final URL saves the hop.', origin));
   }
@@ -545,7 +546,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
       (r) => r.final.status === 404 || r.final.status === 410 || r.final.status === 0,
     );
     if (dead.length) {
-      out.push(f('warn', 'external-broken', `${dead.length} outbound link(s) do not resolve`,
+      out.push(f('warn', 'external-broken', `${plural(dead.length, 'outbound link')} do not resolve`,
         `${dead.slice(0, 3).map((r) => `${r.href} (${r.final.status || r.final.error})`).join(', ')}` +
           `${dead.length > 3 ? `, and ${dead.length - 3} more` : ''}. A link out that goes nowhere is a dead ` +
           'end for a reader. Checked leniently — anything but a 404, a 410 or no answer at all is left alone.',
@@ -554,7 +555,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
 
     const moved = externalResults.filter((r) => r.first >= 300 && r.first < 400 && r.final.ok);
     if (moved.length) {
-      out.push(f('info', 'external-redirects', `${moved.length} outbound link(s) point at a redirect`,
+      out.push(f('info', 'external-redirects', `${plural(moved.length, 'outbound link')} point at a redirect`,
         `${moved.slice(0, 3).map((r) => `${r.href} → ${r.final.url}`).join(', ')}` +
           `${moved.length > 3 ? `, and ${moved.length - 3} more` : ''}. They work; linking to the final ` +
           'URL is tidier and survives the day the redirect is removed.', origin));
@@ -593,7 +594,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
     (r) => r.status === 404 || r.status === 410 || r.status === 0,
   );
   if (deadSchemaImages.length) {
-    out.push(f('warn', 'schema-image-broken', `${deadSchemaImages.length} image(s) named in structured data do not load`,
+    out.push(f('warn', 'schema-image-broken', `${plural(deadSchemaImages.length, 'image')} named in structured data do not load`,
       `${deadSchemaImages.slice(0, 3).map((r) => `${r.href} (${r.status || r.error})`).join(', ')}` +
         `${deadSchemaImages.length > 3 ? `, and ${deadSchemaImages.length - 3} more` : ''}. Google is told to ` +
         'use these for rich results and finds nothing there. The markup is valid, so nothing else reports it.',
@@ -633,7 +634,7 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
   }
   for (const [source, dead] of deadByPage) {
     const shown = dead.slice(0, 3).join(', ');
-    out.push(f('error', 'hreflang-dead', `${dead.length} hreflang target(s) do not load`,
+    out.push(f('error', 'hreflang-dead', `${plural(dead.length, 'hreflang target')} do not load`,
       `${shown}${dead.length > 3 ? `, and ${dead.length - 3} more` : ''} — declared on ${source}. Each ` +
         'version that does not load drops out of the set, and the pages pointing at it lose the annotation.',
       source));

package/src/sitemap.mjs

@@ -11,6 +11,8 @@
 // So this refuses to write anything from a run that did not see the whole site,
 // and says which run would.
 
+import { plural } from './text.mjs';
+
 /** The five characters XML cannot carry raw. `&` first, or the others get
  *  their own ampersands escaped a second time. */
 const escape = (text) =>
@@ -46,13 +48,13 @@ export function rebuild(pages, findings = [], context = {}) {
   // --- when not to write anything ----------------------------------------
   if (truncated > 0) {
     return refuse(
-      `The crawl stopped at its limit with ${truncated} URL(s) unread, so this file would leave ` +
+      `The crawl stopped at its limit with ${plural(truncated, 'URL')} unread, so this file would leave ` +
         `them out of the sitemap entirely. Run again with --limit ${pages.length + truncated}.`,
     );
   }
   if (rateLimited > 0) {
     return refuse(
-      `${rateLimited} page(s) were never read because the server was rate limiting, so whether they ` +
+      `${plural(rateLimited, 'page')} were never read because the server was rate limiting, so whether they ` +
         'belong in a sitemap is not known. Run again with a lower --concurrency.',
     );
   }

package/src/text.mjs

@@ -0,0 +1,21 @@
+// Counting things in a sentence.
+//
+// "1 image(s) without width/height" was the most repeated finding title in a
+// real report — 150 pages of it — and it reads like a form somebody did not
+// finish. A report is worth reading because its sentences are true; a sentence
+// that cannot decide whether it is singular is a smaller version of the same
+// problem.
+//
+// Every plural this project needs is regular, so this stays five lines rather
+// than growing into a library. `many` is there for the first one that is not.
+
+/** `1 image`, `3 images`. Pass `many` where adding an s would be wrong. */
+export function plural(n, one, many = `${one}s`) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** Just the noun, for a count that is formatted separately — a thousands
+ *  separator, say. `${n.toLocaleString()} ${noun(n, 'link')} in`. */
+export function noun(n, one, many = `${one}s`) {
+  return n === 1 ? one : many;
+}