@nurkamol/seo-audit 1.31.0

package/action.yml

@@ -0,0 +1,194 @@
+name: Full-site SEO Audit
+description: Crawl a sitemap and check every page for SEO, metadata and structured-data problems that single-page graders miss
+author: nurkamol
+
+branding:
+  icon: search
+  color: orange
+
+inputs:
+  url:
+    description: Site to audit, or a sitemap URL
+    required: true
+  baseline:
+    description: >
+      Path to a committed baseline file. When set, only findings new since that
+      baseline fail the run — the backlog you already know about is tolerated.
+    required: false
+  fail-on:
+    description: 'error | warn | new | never'
+    required: false
+    default: error
+  config:
+    description: Path to seo-audit.config.json
+    required: false
+  limit:
+    description: Maximum pages to crawl
+    required: false
+  psi:
+    description: >
+      Comma-separated pages to measure with PageSpeed Insights. Slow (~12s
+      each). A path glob names a section — /journal/** is every crawled page
+      under it, sampled. Set the PSI_API_KEY env var from a secret to lift the
+      quota.
+    required: false
+  check-external:
+    description: >
+      Also check links pointing off the site. Off by default because other
+      people's servers rate-limit and bot-block; only a 404, a 410 or no answer
+      at all is ever reported. Set to any non-empty value.
+    required: false
+  verbose:
+    description: >
+      Log every request as it happens. Useful when a run is slow or a site
+      stalls and the job log is all you have to go on. Set to any non-empty
+      value.
+    required: false
+  psi-sample:
+    description: >
+      Pages measured per section glob (default 3). The report says how many of
+      the matched pages were left unmeasured, so a sample never reads as a
+      clean bill of health for the whole section.
+    required: false
+  settle:
+    description: >
+      Seconds to wait for a deploy to reach every edge before crawling. A CDN
+      serves a fresh deploy unevenly for a minute or two, and auditing during
+      the rollout produces a snapshot that is wrong in a confusing way.
+    required: false
+  browser:
+    description: >
+      Crawl as a real browser or a search crawler instead of as this tool:
+      chrome, firefox, safari, edge, googlebot, googlebot-desktop, bingbot.
+      Googlebot is what Google is served, which is not always what a person
+      gets; a browser is what a host blocking crawlers will answer at all.
+    required: false
+  os:
+    description: >
+      The system that browser is running on — macos, windows, linux, android,
+      ios. Defaults to the runner's. Ignored for the crawlers, whose user agent
+      names no machine.
+    required: false
+  report:
+    description: Where to write the HTML report
+    required: false
+    default: seo-audit.html
+  json:
+    description: Where to write the JSON report
+    required: false
+    default: seo-audit.json
+  csv:
+    description: >
+      Where to write the findings as a spreadsheet, one row per finding. Off
+      unless a path is given.
+    required: false
+  comment:
+    description: Post the findings as a sticky comment on the pull request
+    required: false
+    default: 'false'
+  github-token:
+    description: Token used to post the PR comment
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  errors:
+    description: Number of error-level findings
+    value: ${{ steps.run.outputs.errors }}
+  warnings:
+    description: Number of warning-level findings
+    value: ${{ steps.run.outputs.warnings }}
+  notes:
+    description: Number of info-level findings
+    value: ${{ steps.run.outputs.notes }}
+  pages:
+    description: Number of pages crawled
+    value: ${{ steps.run.outputs.pages }}
+  report:
+    description: Path to the HTML report
+    value: ${{ inputs.report }}
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - id: run
+      shell: bash
+      env:
+        # Runs the code shipped with *this* version of the action, not whatever
+        # is on main — otherwise pinning @v1 would pin nothing.
+        SEO_AUDIT_BIN: ${{ github.action_path }}/bin/seo-audit.mjs
+        INPUT_URL: ${{ inputs.url }}
+        INPUT_BASELINE: ${{ inputs.baseline }}
+        INPUT_CONFIG: ${{ inputs.config }}
+        INPUT_LIMIT: ${{ inputs.limit }}
+        INPUT_PSI: ${{ inputs.psi }}
+        INPUT_PSI_SAMPLE: ${{ inputs.psi-sample }}
+        INPUT_VERBOSE: ${{ inputs.verbose }}
+        INPUT_CHECK_EXTERNAL: ${{ inputs.check-external }}
+        INPUT_SETTLE: ${{ inputs.settle }}
+        INPUT_BROWSER: ${{ inputs.browser }}
+        INPUT_OS: ${{ inputs.os }}
+        INPUT_FAIL_ON: ${{ inputs.fail-on }}
+        INPUT_REPORT: ${{ inputs.report }}
+        INPUT_JSON: ${{ inputs.json }}
+        INPUT_CSV: ${{ inputs.csv }}
+      run: |
+        args=("$INPUT_URL" --html "$INPUT_REPORT" --json "$INPUT_JSON" --fail-on "$INPUT_FAIL_ON")
+        [ -n "$INPUT_BASELINE" ] && args+=(--baseline "$INPUT_BASELINE")
+        [ -n "$INPUT_CONFIG" ]   && args+=(--config "$INPUT_CONFIG")
+        [ -n "$INPUT_LIMIT" ]    && args+=(--limit "$INPUT_LIMIT")
+        [ -n "$INPUT_PSI" ]      && args+=(--psi "$INPUT_PSI")
+        [ -n "$INPUT_PSI_SAMPLE" ] && args+=(--psi-sample "$INPUT_PSI_SAMPLE")
+        [ -n "$INPUT_VERBOSE" ]  && args+=(--verbose)
+        [ -n "$INPUT_CHECK_EXTERNAL" ] && args+=(--check-external)
+        [ -n "$INPUT_SETTLE" ]   && args+=(--settle "$INPUT_SETTLE")
+        [ -n "$INPUT_BROWSER" ]  && args+=(--browser "$INPUT_BROWSER")
+        [ -n "$INPUT_OS" ]       && args+=(--os "$INPUT_OS")
+        [ -n "$INPUT_CSV" ]      && args+=(--csv "$INPUT_CSV")
+
+        node "$SEO_AUDIT_BIN" "${args[@]}"
+        status=$?
+
+        node -e '
+          const fs = require("fs");
+          const d = JSON.parse(fs.readFileSync(process.env.INPUT_JSON, "utf8"));
+          const n = (l) => d.findings.filter((f) => f.level === l).length;
+          fs.appendFileSync(process.env.GITHUB_OUTPUT,
+            `errors=${n("error")}\nwarnings=${n("warn")}\nnotes=${n("info")}\npages=${d.meta.pages}\n`);
+
+          const icon = { error: "🔴", warn: "🟡", info: "🔵" };
+          const rows = d.findings
+            .map((f) => `| ${icon[f.level]} | ${f.title} | ${f.url ? `<${f.url}>` : ""} |`)
+            .join("\n");
+          const body =
+            `## SEO audit — ${d.meta.origin}\n\n` +
+            `**${n("error")}** errors · **${n("warn")}** warnings · **${n("info")}** notes ` +
+            `across ${d.meta.pages} pages\n\n` +
+            (d.findings.length ? `| | Finding | Page |\n|:-:|---|---|\n${rows}\n` : "Nothing to report. ✅\n");
+
+          fs.writeFileSync("seo-audit-comment.md", body);
+          if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, body);
+        '
+        exit $status
+
+    # Sticky: edits its own previous comment instead of adding one per push.
+    - if: ${{ always() && inputs.comment == 'true' && github.event_name == 'pull_request' }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        PR: ${{ github.event.pull_request.number }}
+        REPO: ${{ github.repository }}
+      run: |
+        marker="<!-- seo-audit -->"
+        body="$marker"$'\n'"$(cat seo-audit-comment.md)"
+        existing=$(gh api "repos/$REPO/issues/$PR/comments" --jq \
+          "[.[] | select(.body | startswith(\"$marker\")) | .id] | first // empty")
+        if [ -n "$existing" ]; then
+          gh api -X PATCH "repos/$REPO/issues/comments/$existing" -f body="$body" >/dev/null
+        else
+          gh api -X POST "repos/$REPO/issues/$PR/comments" -f body="$body" >/dev/null
+        fi

package/bin/seo-audit.mjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { audit, preview } from '../src/audit.mjs';
+import { terminal, markdown, html, csv, diffReport, dryRunReport, counts, portfolio, portfolioMarkdown, portfolioHtml, progressLine } from '../src/report.mjs';
+import { loadConfig, resolveSites, optionsForSite } from '../src/config.mjs';
+import { readFileSync as read } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { serialize, parse, diff } from '../src/baseline.mjs';
+import { parseRedirectMap } from '../src/redirects.mjs';
+import { describe } from '../src/sitemap.mjs';
+import { askForSite, isInteractive, invocation } from '../src/prompt.mjs';
+import { userAgentFor, BROWSER_NAMES, OS_NAMES, thisPlatform } from '../src/agents.mjs';
+
+const HELP = `
+  seo-audit — crawl a site's sitemap and check every page
+
+  Usage
+    npx github:nurkamol/seo-audit <url> [more urls…] [options]
+
+  Name more than one site — or list them under "sites" in the config — and the
+  report becomes a portfolio table, one row per site, worst first.
+
+  Reporting
+    --md <file>        write a Markdown report
+    --html <file>      write a self-contained HTML report (one file, no assets)
+    --json <file>      write a JSON report (also usable as a baseline)
+    --csv <file>       write the findings as a spreadsheet, one row each
+    --quiet            print nothing; rely on the exit code and the files
+    --write-sitemap <file>
+                       write the sitemap this site should have had — every
+                       page that answered 200, is HTML, is indexable and is
+                       its own canonical. Refuses on a crawl that did not
+                       see the whole site, rather than writing a short one
+    --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
+    --exclude <glob>   leave URLs out of the crawl. Repeatable. Globs match
+                       paths, where * stops at a slash and ** does not
+    --dry-run          say what would be crawled and stop. A handful of
+                       requests instead of hundreds, for checking the tool is
+                       pointed at the right site before spending the minutes
+    --verbose          print each request as it happens, to stderr. A long
+                       crawl is otherwise silent from start to finish, and a
+                       slow site looks exactly like a hung one
+
+  Comparing
+    --baseline <file>  compare against a previous --json run and show only
+                       what changed. With --fail-on new, a build fails on a
+                       regression but tolerates findings you already knew about
+    --update-baseline  write the baseline file after comparing
+    --against <url>    compare against another deployment right now — a
+                       preview against production, say. Hosts are ignored, so
+                       only genuine differences show up
+
+  Crawling
+    --settle <seconds> wait until the site serves consistent HTML before
+                       crawling. A CDN rolls a deploy out unevenly, and a crawl
+                       during that window is wrong in a confusing way
+    --limit <n>        maximum pages to check (default 200)
+    --concurrency <n>  parallel requests (default 6)
+    --sitemap <url>    sitemap location, if not declared in robots.txt
+    --redirects <file> a migration's redirect map (Netlify _redirects shape:
+                       "/old /new 301" per line). Every old URL is asked for,
+                       and what actually happens is reported
+    --check-external   also check links pointing off the site. Off by default:
+                       other people's servers rate-limit and bot-block, so only
+                       a 404, a 410 or no answer at all is ever reported
+    --serve [port]     open the same form the hosted version serves, on this
+                       machine (default 4321). No account, no bill, and none of
+                       the limits a Worker has — the crawl is only bounded by
+                       what this computer will do
+    --browser <name>   crawl as a real browser or a search crawler:
+                       ${BROWSER_NAMES.join(', ')}.
+                       Googlebot is what Google is served; a browser is what a
+                       host blocking crawlers will answer
+    --os <name>        the system that browser is running on, default this one:
+                       ${OS_NAMES.join(', ')}
+    --search-console [property]
+                       order findings by what the pages actually do in Google.
+                       Needs GSC_CLIENT_ID, GSC_CLIENT_SECRET and
+                       GSC_REFRESH_TOKEN in the environment or in
+                       ~/.config/seo-audit/.env. A domain property is named
+                       "sc-domain:example.com" rather than by its URL
+    --compare-as <name> fetch a sample of pages a second time as this browser
+                       or crawler and report what changed. A page that differs
+                       with the reader is cloaking, or bot protection misfiring
+    --user-agent <ua>  identify as something else. Some hosts stall clients
+                       that do not look like a browser
+
+  Filtering
+    --config <file>    default: seo-audit.config.json in the working directory
+    --ignore <ids>     comma-separated check ids to silence for this run
+
+  Performance (asks Google, does not guess)
+    --psi <urls>       comma-separated pages to measure with PageSpeed
+                       Insights. Slow (~12s each) and rate-limited, so name a
+                       handful. A path glob names a section — /journal/** is
+                       every crawled page under it, sampled. Uses PSI_API_KEY,
+                       or ~/.config/seo-audit/.env
+    --psi-sample <n>   pages to measure per section glob (default 3). The
+                       report says what was matched but not measured
+    --psi-strategy     mobile (default) | desktop
+
+  Exit code
+    --fail-on <level>  error (default) | warn | new | never
+                       "new" needs --baseline
+
+  Examples
+    npx github:nurkamol/seo-audit https://example.com
+    npx github:nurkamol/seo-audit https://example.com --md audit.md
+    npx github:nurkamol/seo-audit https://example.com \\
+      --baseline seo-baseline.json --fail-on new
+    npx github:nurkamol/seo-audit one.example two.example --html portfolio.html
+
+  Correctness is checked on every page. Performance is never estimated — with
+  --psi it is measured by Google, and otherwise left to pagespeed.web.dev.
+`;
+
+function parseArgs(argv) {
+  const opts = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = () => argv[++i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
+    else if (arg === '--against') opts.against = value();
+    else if (arg === '--settle') opts.settle = Number(value());
+    else if (arg === '--quiet' || arg === '-q') opts.quiet = true;
+    else if (arg === '--verbose') opts.verbose = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--since') opts.since = value();
+    // 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());
+    else if (arg === '--write-sitemap') opts.writeSitemap = value();
+    else if (arg === '--md') opts.md = value();
+    else if (arg === '--html') opts.html = value();
+    else if (arg === '--json') opts.json = value();
+    else if (arg === '--csv') opts.csv = value();
+    else if (arg === '--baseline') opts.baseline = value();
+    else if (arg === '--update-baseline') opts.updateBaseline = true;
+    else if (arg === '--limit') opts.limit = Number(value());
+    else if (arg === '--concurrency') opts.concurrency = Number(value());
+    else if (arg === '--sitemap') opts.sitemap = value();
+    else if (arg === '--redirects') opts.redirects = value();
+    else if (arg === '--check-external') opts.checkExternal = true;
+    else if (arg === '--user-agent') opts.userAgent = value();
+    else if (arg === '--serve') {
+      // The port is optional: --serve on its own, or --serve 8080.
+      const next = argv[i + 1];
+      opts.serve = next && /^\d+$/.test(next) ? Number(argv[++i]) : true;
+    }
+    else if (arg === '--search-console') {
+      // Optionally the property name, since a domain property is not a URL.
+      const next = argv[i + 1];
+      opts.searchConsole = next && !next.startsWith('--') ? argv[++i] : true;
+    }
+    else if (arg === '--compare-as') opts.compareAs = value();
+    else if (arg === '--compare-sample') opts.compareSample = Number(value());
+    else if (arg === '--browser') opts.browser = value();
+    else if (arg === '--os') opts.os = value();
+    else if (arg === '--config') opts.config = value();
+    else if (arg === '--ignore') opts.ignore = value().split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--fail-on') opts.failOn = value();
+    else if (arg === '--psi') opts.psi = value().split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--psi-sample') opts.psiSample = Number(value());
+    else if (arg === '--psi-strategy') opts.psiStrategy = value();
+    else if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(2);
+    } else rest.push(arg);
+  }
+  opts.target = rest[0];
+  opts.targets = rest;
+  return opts;
+}
+
+const cli = parseArgs(process.argv.slice(2));
+
+if (cli.version) {
+  const here = dirname(fileURLToPath(import.meta.url));
+  console.log(JSON.parse(read(join(here, '..', 'package.json'), 'utf8')).version);
+  process.exit(0);
+}
+
+if (cli.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+let file;
+try {
+  file = loadConfig(cli.config);
+} catch (err) {
+  console.error(`  ${err.message}`);
+  process.exit(2);
+}
+
+// A `psi: ["/", "/journal/**"]` in the config is written as paths and globs.
+// Both are resolved against the crawled site later, in src/psi.mjs, which knows
+// the origin the audit actually settled on and can match a glob against the
+// pages that were really found.
+const psiFromConfig = file.psi ?? [];
+
+// CLI wins over the config file; ignore rules from both are combined, since
+// one is "this site always" and the other is "just this run".
+const opts = {
+  ...file,
+  ...Object.fromEntries(Object.entries(cli).filter(([, v]) => v !== undefined)),
+  ignore: [...(file.ignore ?? []), ...(cli.ignore ?? [])],
+  psi: cli.psi ?? (psiFromConfig.length ? psiFromConfig : undefined),
+  failOn: cli.failOn ?? file.failOn ?? 'error',
+};
+
+// A browser or a crawler to present as, resolved once and refused loudly. An
+// impossible pair describes a machine that does not exist, and the whole point
+// of the flag is to be believed by a server.
+if (opts.browser) {
+  const { ua, error, ignoredOs } = userAgentFor(opts.browser, opts.os ?? thisPlatform());
+  if (error) {
+    console.error(`  ${error}`);
+    process.exit(2);
+  }
+  if (ignoredOs) {
+    console.error(`  --os is ignored for ${opts.browser}: a crawler's user agent names no machine.`);
+  }
+  // An explicit --user-agent is a literal string and outranks a preset.
+  opts.userAgent = opts.userAgent ?? ua;
+} else if (opts.os) {
+  console.error('  --os needs --browser: it says which system the browser is running on.');
+  process.exit(2);
+}
+
+// The second reader, resolved the same way as the first and refused as loudly.
+if (opts.compareAs) {
+  const { ua, error } = userAgentFor(opts.compareAs, opts.os ?? thisPlatform());
+  if (error) {
+    console.error(`  ${error}`);
+    process.exit(2);
+  }
+  opts.compareAs = { ua, label: opts.compareAs };
+}
+
+if (opts.failOn === 'new' && !opts.baseline) {
+  console.error('  --fail-on new needs --baseline <file> to compare against.');
+  process.exit(2);
+}
+
+// Read the redirect map once, here, so a portfolio does not re-read it per site
+// and a missing file fails before anything is crawled.
+if (opts.redirects) {
+  if (!existsSync(opts.redirects)) {
+    console.error(`  Redirect map not found: ${opts.redirects}`);
+    process.exit(2);
+  }
+  opts.redirectRules = parseRedirectMap(readFileSync(opts.redirects, 'utf8'));
+  if (!opts.redirectRules.length) {
+    console.error(`  ${opts.redirects} has no rules in it.`);
+    process.exit(2);
+  }
+}
+
+// Live progress, on stderr so it never contaminates a piped report. --quiet
+// wins over --verbose: asking for silence and getting a running commentary
+// would be the more surprising of the two.
+const live = (origin) =>
+  opts.verbose && !opts.quiet
+    ? (event) => process.stderr.write(`${progressLine(event, origin)}\n`)
+    : undefined;
+
+// One site or twenty: the same options, resolved the same way. A site entry in
+// the config may carry its own overrides, which land on top of the shared ones.
+let sites = resolveSites(cli.targets ?? [], file);
+
+// 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
+// to pick a free port, which is what the macOS app does, and zero is falsy.
+// That bug shipped as "the app opens and the engine never starts".
+if (opts.serve !== undefined) {
+  const { serve } = await import('../src/serve.mjs');
+  const { url } = await serve({
+    port: opts.serve === true ? 4321 : opts.serve,
+    maxPages: opts.limit,
+    userAgent: opts.userAgent,
+  });
+  console.log(`\n  seo-audit is serving at ${url}\n  Nothing leaves this machine. Ctrl-C to stop.\n`);
+
+  // Started by something rather than by somebody: when stdin is a *pipe*, its
+  // closing is the parent going away, and a server that outlives the window
+  // that opened it holds the port against the next launch.
+  //
+  // A pipe specifically, not merely "not a terminal". `--serve < /dev/null` is
+  // also not a TTY, and reading it ends at once — which shut the server down
+  // the instant it started, in the CI job added to catch exactly this kind of
+  // thing. A parent that wants to be noticed hands over a pipe.
+  const { fstatSync } = await import('node:fs');
+  const stdinIsPipe = (() => {
+    try {
+      const stdin = fstatSync(0);
+      // A named pipe or a socket: Node hands a child a socketpair rather than a
+      // FIFO, so checking only for one of them makes this fire in a terminal
+      // and not fire where it matters. /dev/null is a character device, which
+      // is neither.
+      return stdin.isFIFO() || stdin.isSocket();
+    } catch {
+      return false;
+    }
+  })();
+  if (stdinIsPipe) {
+    process.stdin.resume();
+    process.stdin.on('end', () => process.exit(0));
+    process.stdin.on('close', () => process.exit(0));
+  }
+} else {
+
+// Nothing to audit. If a person is there to ask, ask; otherwise this is a
+// script or a CI runner and the help text is the right answer.
+if (!sites.length) {
+  let answers = null;
+  if (isInteractive()) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log('');
+    answers = await askForSite(rl);
+    rl.close();
+  }
+
+  if (!answers) {
+    console.log(HELP);
+    process.exit(2);
+  }
+
+  sites = resolveSites([answers.url], file);
+  if (answers.html) opts.html = answers.html;
+  console.log(`\n  Next time, in one line:\n    ${invocation(sites[0].url, answers)}\n`);
+}
+
+for (const site of sites) {
+  try {
+    new URL(site.url);
+  } catch {
+    console.error(`Not a URL: ${site.url}`);
+    process.exit(2);
+  }
+}
+
+// --- A portfolio ---------------------------------------------------------
+if (sites.length > 1) {
+  // Comparing two deployments, or against a stored baseline, is a question
+  // about one site. Rather than half-answer it across twenty, say so.
+  for (const [flag, name] of [['baseline', '--baseline'], ['against', '--against'], ['updateBaseline', '--update-baseline']]) {
+    if (opts[flag]) {
+      console.error(`  ${name} audits one site at a time — it compares a site against itself.`);
+      console.error(`  Run it per site, or drop the flag to get the portfolio table.`);
+      process.exit(2);
+    }
+  }
+
+  const runs = [];
+  for (const [i, site] of sites.entries()) {
+    if (!opts.quiet) process.stderr.write(`  [${i + 1}/${sites.length}] ${site.url} …\n`);
+    const siteOpts = optionsForSite(opts, site.overrides);
+    // Sites run one at a time on purpose: interleaved progress from twenty
+    // hosts is unreadable, and each audit is already parallel internally.
+    const { findings, meta } = await audit(site.url, {
+      ...siteOpts,
+      onNote: (m) => !opts.quiet && process.stderr.write(`      ${m}\n`),
+      onProgress: live(site.url),
+    });
+    runs.push({ findings, meta });
+  }
+
+  if (!opts.quiet) console.log(portfolio(runs));
+  if (opts.md) writeFileSync(opts.md, portfolioMarkdown(runs));
+  if (opts.html) writeFileSync(opts.html, portfolioHtml(runs));
+  if (opts.json) {
+    writeFileSync(
+      opts.json,
+      JSON.stringify(
+        { tool: 'seo-audit', date: runs[0]?.meta.date, sites: runs.map((r) => ({ ...r.meta, findings: r.findings })) },
+        null,
+        2,
+      ),
+    );
+  }
+  if (!opts.quiet && (opts.md || opts.html || opts.json)) {
+    console.log(`  ${[opts.md, opts.html, opts.json].filter(Boolean).join('  ')}\n`);
+  }
+
+  // One bad site fails the run: a portfolio check that passes while a site in
+  // it is broken is a check nobody can trust.
+  const failed = runs.some(({ findings }) => {
+    const n = counts(findings);
+    return (opts.failOn === 'error' && n.error > 0) || (opts.failOn === 'warn' && n.error + n.warn > 0);
+  });
+  process.exit(failed ? 1 : 0);
+}
+
+const target = sites[0].url;
+
+// --- say what would happen, and stop --------------------------------------
+// Before spending minutes and a few hundred requests on somebody else's
+// server, find out whether this is pointed at the right site.
+if (opts.dryRun) {
+  const plan = await preview(target, opts);
+  process.stdout.write(dryRunReport(plan));
+  process.exit(plan.reachable && plan.listed ? 0 : 1);
+}
+
+if (!opts.quiet) {
+  process.stderr.write(`  crawling ${target} …${file.source ? ` (${file.source})` : ''}\n`);
+}
+
+if (!opts.quiet && opts.settle) {
+  process.stderr.write(`  waiting up to ${opts.settle}s for the site to serve consistent HTML …\n`);
+}
+
+const { findings, meta, sitemap } = await audit(target, {
+  ...opts,
+  onNote: (m) => !opts.quiet && process.stderr.write(`  ${m}\n`),
+  onProgress: live(target),
+});
+
+// --- the sitemap this site should have had -------------------------------
+// Written before the report, so a refusal is read rather than scrolled past at
+// the bottom of two hundred findings.
+if (opts.writeSitemap && sitemap) {
+  if (sitemap.xml) writeFileSync(opts.writeSitemap, sitemap.xml);
+  process.stderr.write('\n' + describe(sitemap, opts.writeSitemap));
+}
+
+// --- Compare against another deployment, if asked -----------------------
+let against = null;
+if (opts.against) {
+  const reference = /^https?:\/\//i.test(opts.against) ? opts.against : `https://${opts.against}`;
+  if (!opts.quiet) process.stderr.write(`  crawling ${reference} to compare …\n`);
+  const other = await audit(reference, { ...opts, against: undefined, settle: undefined });
+  against = diff({ findings: other.findings, meta: other.meta }, findings, { ignoreHost: true });
+  against.previousDate = reference;
+}
+
+// --- Compare against a stored baseline, if asked ------------------------
+let comparison = against;
+if (opts.baseline && !against) {
+  if (existsSync(opts.baseline)) {
+    try {
+      comparison = diff(parse(readFileSync(opts.baseline, 'utf8'), opts.baseline), findings);
+    } catch (err) {
+      console.error(`  ${err.message}`);
+      process.exit(2);
+    }
+  } else if (!opts.quiet) {
+    process.stderr.write(`  no baseline at ${opts.baseline} yet — writing one\n`);
+  }
+  if (!existsSync(opts.baseline) || opts.updateBaseline) {
+    writeFileSync(opts.baseline, serialize(findings, meta));
+  }
+}
+
+// --- Report -------------------------------------------------------------
+if (!opts.quiet) {
+  console.log(comparison ? diffReport(comparison) : terminal(findings, meta));
+}
+if (opts.md) writeFileSync(opts.md, markdown(findings, meta));
+if (opts.html) writeFileSync(opts.html, html(findings, meta));
+if (opts.json) writeFileSync(opts.json, serialize(findings, meta, { full: true }));
+if (opts.csv) writeFileSync(opts.csv, csv(findings, meta));
+if (!opts.quiet && (opts.md || opts.html || opts.json)) {
+  console.log(`  ${[opts.md, opts.html, opts.json].filter(Boolean).join('  ')}\n`);
+}
+
+// --- Exit ---------------------------------------------------------------
+const n = counts(findings);
+const failed =
+  (opts.failOn === 'error' && n.error > 0) ||
+  (opts.failOn === 'warn' && n.error + n.warn > 0) ||
+  (opts.failOn === 'new' && (comparison?.added.length ?? 0) > 0);
+process.exit(failed ? 1 : 0);
+
+}