@nurkamol/seo-audit 1.31.0

package/src/prompt.mjs

@@ -0,0 +1,37 @@
+// The questions asked when someone runs the bare command.
+//
+// This exists to be a friendlier first thirty seconds, not a menu to live in.
+// It asks the minimum, then prints the command it assembled and runs that — so
+// the second use is a one-liner and the flags are learned rather than hidden.
+//
+// The readline interface is passed in rather than created here, so the flow can
+// be tested without a terminal. Whether to ask at all is `isInteractive`, and
+// the answer is no far more often than people expect: a pipe, a CI runner, a
+// `| tee`, an editor's task runner. A prompt that blocks a build waiting for
+// input nobody can type is much worse than the help text it replaced.
+
+export const isInteractive = (streams = process) =>
+  Boolean(streams.stdin?.isTTY && streams.stdout?.isTTY);
+
+/** The one-line command that reproduces this run. */
+export function invocation(url, { html } = {}) {
+  return ['seo-audit', url, html ? `--html ${html}` : ''].filter(Boolean).join(' ');
+}
+
+/**
+ * @param {{question: (q: string) => Promise<string>}} rl
+ * @returns {Promise<{url: string, html?: string}|null>} null if there is no
+ *   usable answer — an empty line, or a stream that closed under us.
+ */
+export async function askForSite(rl) {
+  try {
+    const url = (await rl.question('  Site to audit:            ')).trim();
+    if (!url) return null;
+
+    const html = /^y(es)?$/i.test((await rl.question('  Save an HTML report? [y/N] ')).trim());
+    return html ? { url, html: 'seo-audit.html' } : { url };
+  } catch {
+    // Ctrl-C, or EOF on a stream that looked like a terminal and was not.
+    return null;
+  }
+}

package/src/psi.mjs

@@ -0,0 +1,200 @@
+// PageSpeed Insights.
+//
+// Everywhere else this tool refuses to talk about performance, because a fetch
+// loop cannot see rendering and a plausible-looking wrong number is worse than
+// no number. Asking Google for its own measurement is a different thing: this
+// is Lighthouse, run by Google, on Google's hardware — the same figure the
+// PageSpeed Insights page shows.
+//
+// It is slow (~12s per URL) and rate-limited, so it runs on the pages you name
+// rather than the whole sitemap, and never by default.
+//
+// A key is optional but raises the quota well above the anonymous limit. Set
+// PSI_API_KEY, or put it in ~/.config/seo-audit/.env — never in the repo.
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { matchGlob } from './config.mjs';
+
+const ENDPOINT = 'https://www.googleapis.com/pagespeedonline/v5/runPagespeed';
+
+// Roughly a minute of measuring per section. Enough to tell whether a template
+// is slow — which is the question a section is asked — without turning an audit
+// into a coffee break.
+export const DEFAULT_SAMPLE = 3;
+
+// What one PSI call costs, near enough to warn someone before they wait for it.
+const SECONDS_PER_URL = 12;
+
+// Google's own thresholds for "good" and "poor".
+const CWV = {
+  lcp: { good: 2500, poor: 4000, label: 'Largest Contentful Paint' },
+  cls: { good: 0.1, poor: 0.25, label: 'Cumulative Layout Shift' },
+  inp: { good: 200, poor: 500, label: 'Interaction to Next Paint' },
+};
+
+export function findKey() {
+  if (process.env.PSI_API_KEY) return process.env.PSI_API_KEY;
+  const dotfile = join(homedir(), '.config', 'seo-audit', '.env');
+  if (!existsSync(dotfile)) return null;
+  const match = readFileSync(dotfile, 'utf8').match(/^\s*PSI_API_KEY\s*=\s*(\S+)/m);
+  return match?.[1] ?? null;
+}
+
+async function run(url, strategy, key) {
+  const params = new URLSearchParams({ url, strategy, category: 'performance' });
+  if (key) params.set('key', key);
+  const res = await fetch(`${ENDPOINT}?${params}`);
+  const data = await res.json();
+  if (data.error) throw new Error(data.error.message);
+  return data;
+}
+
+const f = (level, id, title, detail, url) => ({ level, id, title, detail, url });
+
+/** `n` items spread across a list, rather than the first n.
+ *
+ *  Deterministic on purpose. A random sample would measure different pages on
+ *  every run, and --baseline would then report the change as a regression. */
+function spread(list, n) {
+  if (list.length <= n) return list;
+  const step = list.length / n;
+  return Array.from({ length: n }, (_, i) => list[Math.floor(i * step)]);
+}
+
+export const estimateSeconds = (n) => n * SECONDS_PER_URL;
+
+/** Resolve --psi entries against the pages actually crawled.
+ *
+ *  A URL or a path is measured as given. A path glob names a section — every
+ *  crawled page under it, sampled down to `sample`, because a section of forty
+ *  pages measured whole is eight minutes of waiting.
+ *
+ *  Returns { urls, notes }. The notes report what matched but was not measured:
+ *  a sampled section must never read as a clean bill of health for the whole
+ *  section, which is exactly how a silent cap would read. */
+export function psiTargets(entries, pageUrls, { origin, sample = DEFAULT_SAMPLE } = {}) {
+  const urls = [];
+  const notes = [];
+
+  for (const entry of entries) {
+    if (!entry.includes('*')) {
+      try {
+        urls.push(new URL(entry, origin).toString());
+      } catch {
+        notes.push(f('info', 'psi-no-match', `Not a URL or path: ${entry}`,
+          'Pass a full URL, a path, or a path glob such as /journal/**.', origin));
+      }
+      continue;
+    }
+
+    const matched = pageUrls.filter((u) => {
+      try {
+        return matchGlob(entry, new URL(u).pathname);
+      } catch {
+        return false;
+      }
+    });
+
+    if (!matched.length) {
+      notes.push(f('info', 'psi-no-match', `No crawled page matches ${entry}`,
+        'Nothing was measured for this pattern. Globs match URL paths, where `*` stops at a slash and `**` does not.', origin));
+      continue;
+    }
+
+    const picked = spread(matched, sample);
+    urls.push(...picked);
+    if (picked.length < matched.length) {
+      notes.push(f('info', 'psi-sampled', `Measured ${picked.length} of the ${matched.length} pages under ${entry}`,
+        `A sample, spread across the section — at ~${SECONDS_PER_URL}s a page, measuring all ${matched.length} would take ` +
+        `${Math.ceil(estimateSeconds(matched.length) / 60)} minutes. The other ${matched.length - picked.length} were not looked at; ` +
+        'raise the sample with --psi-sample, and expect the wait.', origin));
+    }
+  }
+
+  return { urls: [...new Set(urls)], notes };
+}
+
+/**
+ * @param {string[]} urls pages to measure — a handful, not a sitemap
+ * @param {{strategy?: 'mobile'|'desktop', key?: string|null}} opts
+ */
+export async function psiChecks(urls, { strategy = 'mobile', key = findKey(), onProgress } = {}) {
+  const out = [];
+
+  for (const [i, url] of urls.entries()) {
+    let data;
+    // Announced before rather than after: each call takes about twelve seconds,
+    // which is a long time to sit looking at nothing.
+    onProgress?.({ phase: 'psi', url, detail: `measuring ${i + 1} of ${urls.length} (~12s)` });
+    try {
+      data = await run(url, strategy, key);
+    } catch (err) {
+      out.push(f('info', 'psi-failed', 'PageSpeed Insights could not measure this page',
+        `${err.message}${key ? '' : ' (no PSI_API_KEY set — the anonymous quota is small)'}`, url));
+      continue;
+    }
+
+    const lr = data.lighthouseResult;
+    const audits = lr.audits;
+    const score = Math.round((lr.categories.performance.score ?? 0) * 100);
+
+    if (score < 50) {
+      out.push(f('error', 'psi-score', `Performance ${score}/100 on ${strategy}`,
+        'Google rates this poor. The opportunities below say why.', url));
+    } else if (score < 90) {
+      out.push(f('warn', 'psi-score', `Performance ${score}/100 on ${strategy}`,
+        'Google rates this "needs improvement".', url));
+    }
+
+    // Lab metrics against Google's own good/poor boundaries.
+    const metrics = {
+      lcp: audits['largest-contentful-paint']?.numericValue,
+      cls: audits['cumulative-layout-shift']?.numericValue,
+    };
+    for (const [name, value] of Object.entries(metrics)) {
+      if (value == null) continue;
+      const { good, poor, label } = CWV[name];
+      const shown = audits[name === 'lcp' ? 'largest-contentful-paint' : 'cumulative-layout-shift']
+        .displayValue;
+      if (value > poor) {
+        out.push(f('error', `psi-${name}`, `${label} is poor: ${shown}`,
+          `Google's threshold for "good" is ${name === 'cls' ? good : `${good / 1000}s`}.`, url));
+      } else if (value > good) {
+        out.push(f('warn', `psi-${name}`, `${label} needs improvement: ${shown}`,
+          `Google's threshold for "good" is ${name === 'cls' ? good : `${good / 1000}s`}.`, url));
+      }
+    }
+
+    // Opportunities worth a quarter of a second or more, named by Google.
+    for (const audit of Object.values(audits)) {
+      const saving = audit.details?.overallSavingsMs ?? 0;
+      if (saving >= 250) {
+        out.push(f('warn', 'psi-opportunity', `${audit.title} — ${Math.round(saving)}ms`,
+          (audit.description ?? '').split('. ')[0] + '.', url));
+      }
+    }
+
+    // Field data, when Google has enough real visitors to report it. This is
+    // what actually counts for ranking; the lab numbers above are a rehearsal.
+    const field = data.loadingExperience?.metrics;
+    if (field) {
+      for (const [key_, metric] of Object.entries({
+        LARGEST_CONTENTFUL_PAINT_MS: 'lcp',
+        CUMULATIVE_LAYOUT_SHIFT_SCORE: 'cls',
+        INTERACTION_TO_NEXT_PAINT: 'inp',
+      })) {
+        const entry = field[key_];
+        if (entry && entry.category === 'SLOW') {
+          out.push(f('error', `psi-field-${metric}`, `Real visitors see a poor ${CWV[metric].label}`,
+            `Chrome field data, not a lab test — this is the number Google ranks on.`, url));
+        }
+      }
+    } else {
+      out.push(f('info', 'psi-no-field-data', 'No real-visitor performance data yet',
+        'Chrome reports field data once a site has enough traffic. Lab numbers are all there is for now.', url));
+    }
+  }
+
+  return out;
+}

package/src/redirects.mjs

@@ -0,0 +1,145 @@
+// Redirect maps, checked against the live site.
+//
+// A migration's redirect map is written once, verified once, and then rots
+// quietly: a later change to the destination turns an entry into a hop through
+// a 404, and nothing tells anyone. The old URLs are the ones with the links and
+// the rankings, so this is one of the few SEO failures that is expensive and
+// completely silent.
+//
+// Reads the Netlify `_redirects` shape, which is also the simplest thing
+// anyone writes by hand:
+//
+//   /old-path   /new-path   301
+//   /also-old   /new-path          # status optional
+//   /just-a-list-of-old-urls       # destination optional too
+//
+// 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.
+
+const HAS_PATTERN = /[*:]/;
+
+/** Rules from a redirect map. `to` and `status` may be null. */
+export function parseRedirectMap(text) {
+  const rules = [];
+  for (const raw of (text ?? '').split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const [from, to, status] = line.split(/\s+/);
+    if (!from) continue;
+    rules.push({
+      from,
+      to: to ?? null,
+      // Netlify writes `301!` to force a rule ahead of an existing file.
+      status: status ? Number(status.replace('!', '')) || null : null,
+    });
+  }
+  return rules;
+}
+
+const f = (level, id, title, detail, url) => ({ level, id, title, detail, url });
+
+const bare = (u) => (u ?? '').replace(/\/$/, '');
+
+/**
+ * Ask the live site for every old URL and report what actually happens.
+ *
+ * Findings are aggregated by outcome: a migration map runs to hundreds of
+ * entries, and one finding per entry would be a wall nobody reads. Each one
+ * names the first few and says how many more there are.
+ */
+export async function redirectChecks(rules, fetcher, origin, { limit = 200, onProgress } = {}) {
+  const out = [];
+  if (!rules.length) return out;
+
+  const patterned = rules.filter((r) => HAS_PATTERN.test(r.from));
+  const testable = rules.filter((r) => !HAS_PATTERN.test(r.from));
+  const checked = testable.slice(0, limit);
+
+  if (patterned.length) {
+    out.push(f('info', 'redirect-pattern-skipped', `${patterned.length} wildcard rule(s) 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`,
+      `The map has ${testable.length} testable rules and the limit is ${limit}. Raise it with maxRedirectChecks.`,
+      origin));
+  }
+
+  const results = await Promise.all(
+    checked.map(async (rule) => {
+      let from;
+      try {
+        from = new URL(rule.from, origin).toString();
+      } catch {
+        return null;
+      }
+      const { hops, final } = await fetcher.chain(from);
+      onProgress?.({ phase: 'redirects', status: hops[0]?.status ?? 0, url: rule.from, detail: `→ ${final.url}` });
+      return { rule, from, hops, final, first: hops[0]?.status ?? 0 };
+    }),
+  );
+
+  const buckets = new Map();
+  const add = (key, line) => buckets.set(key, [...(buckets.get(key) ?? []), line]);
+
+  for (const r of results.filter(Boolean)) {
+    const { rule, from, hops, final, first } = r;
+
+    if (first === 404 || first === 410 || first === 0) {
+      add('gone', `${rule.from} → ${first || final.error}`);
+      continue;
+    }
+    if (first >= 200 && first < 300) {
+      add('notRedirecting', `${rule.from} answers ${first}`);
+      continue;
+    }
+    // It redirects. Does it arrive somewhere real, and in one hop?
+    if (!final.ok) {
+      add('broken', `${rule.from} → ${final.url} (${final.status || final.error})`);
+      continue;
+    }
+    // hops includes the final response, so two entries is one redirect.
+    if (hops.length > 2) {
+      add('hops', `${rule.from} takes ${hops.length - 1} hops → ${final.url}`);
+    }
+    if (rule.status === 301 && first === 302) {
+      add('temporary', `${rule.from} answers 302 where the map says 301`);
+    }
+    if (rule.to && !HAS_PATTERN.test(rule.to)) {
+      let expected;
+      try {
+        expected = new URL(rule.to, origin).toString();
+      } catch {
+        expected = null;
+      }
+      if (expected && bare(expected) !== bare(final.url)) {
+        add('elsewhere', `${rule.from} → ${final.url}, map says ${rule.to}`);
+      }
+    }
+  }
+
+  const say = (key, level, id, title, detail) => {
+    const lines = buckets.get(key);
+    if (!lines?.length) return;
+    const shown = lines.slice(0, 3).join('; ');
+    out.push(f(level, id, title(lines.length),
+      `${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`,
+    '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`,
+    '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`,
+    '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`,
+    '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`,
+    '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`,
+    'A 302 tells Google the move is temporary, so it keeps the old URL indexed and passes less through it.');
+
+  return out;
+}