pagetrace 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,61 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 While the version is below 1.0.0, breaking changes ship in a minor release.
 
+## [0.5.0] - 2026-09-06
+
+### Added
+
+- `check --baseline-branch <ref>` reads the baseline lockfile out of a git ref
+  instead of the working tree, so a pull request can diff against `main` without
+  carrying a lockfile of its own. Commit the lockfile on the default branch only
+  and feature branches stop churning it. An unresolvable ref throws rather than
+  reading as an empty baseline, since a typo must not mean "nothing changed"; a
+  ref that simply has no lockfile yet returns nothing, which is an ordinary
+  first run.
+- A composite GitHub Action (`action.yml`). Three lines in a workflow run the
+  check and post the findings as a pull request comment, editing the previous
+  comment on each push rather than stacking new ones. It fetches the baseline ref
+  first, since a shallow CI checkout usually has only the PR head.
+- `snapshotFromGitRef(ref, path)` is exported.
+
+### Fixed
+
+- `formatMarkdown` escapes angle brackets. `The <h1> was removed.` rendered as
+  `The  was removed.` on GitHub, which parses a tag name in a table cell as
+  inline HTML and drops it — losing the part of the message that mattered, in
+  the reporter whose whole purpose is the pull request comment.
+
+## [0.4.0] - 2026-09-06
+
+### Changed
+
+- **Breaking.** A failed run now exits `2` rather than `1`. `1` means findings at
+  or above `--fail-on`; `2` means the run itself failed — invalid flags, an
+  unreadable build directory, an unreachable origin, no pages found. CI could not
+  previously distinguish "the site regressed" from "the tool broke", which are
+  opposite situations: one should fail the build, the other should page someone.
+- The lockfile is only rewritten when the surface actually changed. It carries a
+  `createdAt` timestamp, so every run used to produce a git diff even on an
+  unchanged site — which teaches reviewers to discard lockfile changes without
+  reading them, the one habit this tool cannot afford. `snapshot` and
+  `check --update` now say "already up to date" and leave the file alone.
+- Source maps are no longer published. They were 61% of the package: 715 kB
+  unpacked down to 281 kB. Nobody steps through a built CLI.
+- Build target moved from `node18` to `node20`, matching the engines floor.
+
+### Added
+
+- Failed requests are retried up to three times with backoff, on network errors,
+  429 and 5xx. 0.2.0 made an unreachable page abort the crawl rather than be
+  silently dropped, which is correct but brittle without a retry — one flaky
+  response could end a 200-page crawl. A 4xx is an answer, not a hiccup, and is
+  not retried.
+- `sameSurface(a, b)` is exported: compares two snapshots ignoring when they were
+  taken.
+- The release workflow creates a GitHub Release from each tag, using that
+  version's changelog section as the notes. A tag on its own does not appear in
+  the repo UI, so the project read as unreleased despite being on npm.
+
 ## [0.3.0] - 2026-09-06
 
 ### Changed
@@ -139,6 +194,8 @@ Initial release. `snapshot`, `check` and `audit` commands; filesystem and HTTP
 crawling; diff classified by transition; absolute, cross-page and hreflang audit
 rules; pretty, JSON, markdown, GitHub and HTML reporters.
 
+[0.5.0]: https://github.com/shyamexe/pagetrace/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/shyamexe/pagetrace/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/shyamexe/pagetrace/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/shyamexe/pagetrace/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/shyamexe/pagetrace/releases/tag/v0.1.0

package/README.md

@@ -48,10 +48,12 @@ npx pagetrace check --dir ./out
 5 error, 9 warning, 2 info
 ```
 
-Exit code is `1` when anything at or above `--fail-on` is found. It takes `error` (the default), `warn` or `info`, and rejects anything else rather than quietly letting the build pass.
+Exit codes are `0` for clean, `1` for findings at or above `--fail-on`, and `2` when the run itself failed — bad flags, an unreadable build directory, an unreachable origin. CI can tell "the site regressed" from "the tool broke". `--fail-on` takes `error` (the default), `warn` or `info`, and rejects anything else rather than quietly letting the build pass.
 
 Note that `check` runs the absolute rules as well as the diff, so it can fail on a problem your build did not introduce. Use `--no-audit` for a pure regression gate.
 
+The lockfile is only rewritten when the surface actually changed, so an unchanged site leaves it byte-identical and produces no git diff.
+
 Accept the new state once you've reviewed it:
 
 ```bash
@@ -149,9 +151,30 @@ Every finding has a stable `code`. Set any code to `error`, `warn`, `info`, or `
 
 ## CI
 
+The GitHub Action is the shortest path. It diffs the build against the baseline committed on your default branch and leaves the result as a pull request comment, updating that same comment on each push rather than stacking new ones.
+
+```yaml
+- uses: actions/checkout@v5
+- run: npm ci && npm run build
+- uses: shyamexe/pagetrace@v1
+  with:
+    dir: ./out
+    baseline-branch: main
+```
+
+`baseline-branch` reads the lockfile out of a git ref rather than the working tree, so feature branches never carry one and you get no lockfile churn in pull requests. Commit the lockfile on your default branch only:
+
+```bash
+npx pagetrace snapshot --dir ./out
+git add pagetrace.lock.json
+```
+
+Needs `pull-requests: write` for the comment. Set `comment: false` to skip it, or `audit: false` for a pure regression gate.
+
+Without the Action:
+
 ```yaml
-- run: npm run build
-- run: npx pagetrace check --dir ./out --format github
+- run: npx pagetrace check --dir ./out --baseline-branch origin/main --format github
 ```
 
 `--format` accepts `pretty`, `json`, `markdown` (sized for a PR comment), and `github` (workflow annotations).

package/dist/cli.cjs

@@ -866,7 +866,7 @@ function formatPretty(findings) {
 function formatJson(findings) {
   return JSON.stringify({ schemaVersion: 1, summary: summarize(findings), findings }, null, 2);
 }
-var escapeCell = (value) => value.replace(/\|/g, "\\|");
+var escapeCell = (value) => value.replace(/\|/g, "\\|").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 function formatMarkdown(findings) {
   const s = summarize(findings);
   if (findings.length === 0) return "### pagetrace\n\nNo SEO/AEO changes or issues found.";
@@ -1055,8 +1055,10 @@ ${cards || "<p>No issues found.</p>"}
 }
 
 // src/snapshot.ts
+var import_node_child_process = require("child_process");
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
+var import_node_util = require("util");
 
 // src/extract.ts
 var import_node_html_parser = require("node-html-parser");
@@ -1278,6 +1280,32 @@ function routeFromUrl(url) {
     return url;
   }
 }
+var exec = (0, import_node_util.promisify)(import_node_child_process.execFile);
+async function snapshotFromGitRef(ref, path) {
+  try {
+    await exec("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch (cause) {
+    throw new Error(
+      `Cannot resolve git ref "${ref}". Fetch it first \u2014 a shallow CI checkout often has only the PR head.`,
+      { cause }
+    );
+  }
+  let stdout;
+  try {
+    ({ stdout } = await exec("git", ["show", `${ref}:${path}`], { maxBuffer: 256 * 1024 * 1024 }));
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch (cause) {
+    throw new Error(`${path} at ${ref} is not valid JSON.`, { cause });
+  }
+}
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1296,19 +1324,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1405,6 +1446,15 @@ async function snapshotFromOrigin(origin, options = {}) {
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
+var EXIT_FINDINGS = 1;
+var EXIT_FAILURE = 2;
+async function writeLockfile(path, next) {
+  const previous = await (0, import_promises2.readFile)(path, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
+  if (previous && sameSurface(previous, next)) return false;
+  await (0, import_promises2.writeFile)(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return true;
+}
 var SEVERITIES = ["error", "warn", "info"];
 function parseFailOn(value, allowNever) {
   const expected = [...SEVERITIES, ...allowNever ? ["never"] : []].join(" | ");
@@ -1446,25 +1496,20 @@ var cli = (0, import_cac.cac)("pagetrace");
 cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
-  await (0, import_promises2.writeFile)(flags.out, `${JSON.stringify(snapshot, null, 2)}
-`, "utf8");
+  const written = await writeLockfile(flags.out, snapshot);
   const count = Object.keys(snapshot.pages).length;
-  console.log(import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`));
+  console.log(
+    written ? import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`) : import_picocolors2.default.dim(`${flags.out} is already up to date \u2014 ${count} page${count === 1 ? "" : "s"}.`)
+  );
 });
-cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").action(async (flags) => {
+cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
   const config = await loadConfig(flags.config);
   const next = await build(flags, config);
-  let previous = null;
-  try {
-    previous = JSON.parse(await (0, import_promises2.readFile)(flags.lockfile, "utf8"));
-  } catch {
-    previous = null;
-  }
+  const previous = flags.baselineBranch ? await snapshotFromGitRef(flags.baselineBranch, flags.lockfile) : await (0, import_promises2.readFile)(flags.lockfile, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
   if (!previous) {
-    console.error(
-      import_picocolors2.default.yellow(`No lockfile at ${flags.lockfile}. Run \`pagetrace snapshot\` first to set a baseline.`)
-    );
+    const where = flags.baselineBranch ? `No ${flags.lockfile} at ${flags.baselineBranch}.` : `No lockfile at ${flags.lockfile}.`;
+    console.error(import_picocolors2.default.yellow(`${where} Run \`pagetrace snapshot\` first to set a baseline.`));
   }
   const raw = [
     ...previous ? diffSnapshots(previous, next) : [],
@@ -1473,9 +1518,10 @@ cli.command("check", "Compare the current surface against the lockfile").option(
   const findings = applyConfig(raw, config);
   console.log(render(findings, flags.format));
   if (flags.update) {
-    await (0, import_promises2.writeFile)(flags.lockfile, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    console.error(import_picocolors2.default.dim(`Updated ${flags.lockfile}.`));
+    const written = await writeLockfile(flags.lockfile, next);
+    console.error(
+      import_picocolors2.default.dim(written ? `Updated ${flags.lockfile}.` : `${flags.lockfile} is already up to date.`)
+    );
   }
   const summary = summarize(findings);
   if (previous && shouldFail(findings, failOn)) {
@@ -1483,7 +1529,7 @@ cli.command("check", "Compare the current surface against the lockfile").option(
       import_picocolors2.default.red(`
 Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`)
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
@@ -1497,7 +1543,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
         "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
       )
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
     return;
   }
   const platform = detectPlatform(
@@ -1523,19 +1569,18 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     console.log(output);
   }
   if (failOn !== "never" && shouldFail(findings, failOn)) {
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.help();
-cli.version("0.3.0");
+cli.version("0.5.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(import_picocolors2.default.red(error.message));
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
   }
 }
 void main();
-//# sourceMappingURL=cli.cjs.map

package/dist/cli.js

@@ -843,7 +843,7 @@ function formatPretty(findings) {
 function formatJson(findings) {
   return JSON.stringify({ schemaVersion: 1, summary: summarize(findings), findings }, null, 2);
 }
-var escapeCell = (value) => value.replace(/\|/g, "\\|");
+var escapeCell = (value) => value.replace(/\|/g, "\\|").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 function formatMarkdown(findings) {
   const s = summarize(findings);
   if (findings.length === 0) return "### pagetrace\n\nNo SEO/AEO changes or issues found.";
@@ -1032,8 +1032,10 @@ ${cards || "<p>No issues found.</p>"}
 }
 
 // src/snapshot.ts
+import { execFile } from "child_process";
 import { readdir, readFile } from "fs/promises";
 import { join, relative, sep } from "path";
+import { promisify } from "util";
 
 // src/extract.ts
 import { parse } from "node-html-parser";
@@ -1255,6 +1257,32 @@ function routeFromUrl(url) {
     return url;
   }
 }
+var exec = promisify(execFile);
+async function snapshotFromGitRef(ref, path) {
+  try {
+    await exec("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch (cause) {
+    throw new Error(
+      `Cannot resolve git ref "${ref}". Fetch it first \u2014 a shallow CI checkout often has only the PR head.`,
+      { cause }
+    );
+  }
+  let stdout;
+  try {
+    ({ stdout } = await exec("git", ["show", `${ref}:${path}`], { maxBuffer: 256 * 1024 * 1024 }));
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch (cause) {
+    throw new Error(`${path} at ${ref} is not valid JSON.`, { cause });
+  }
+}
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1273,19 +1301,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1382,6 +1423,15 @@ async function snapshotFromOrigin(origin, options = {}) {
 // src/cli.ts
 var DEFAULT_LOCKFILE = "pagetrace.lock.json";
 var DEFAULT_CONFIG = "pagetrace.config.json";
+var EXIT_FINDINGS = 1;
+var EXIT_FAILURE = 2;
+async function writeLockfile(path, next) {
+  const previous = await readFile2(path, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
+  if (previous && sameSurface(previous, next)) return false;
+  await writeFile(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  return true;
+}
 var SEVERITIES = ["error", "warn", "info"];
 function parseFailOn(value, allowNever) {
   const expected = [...SEVERITIES, ...allowNever ? ["never"] : []].join(" | ");
@@ -1423,25 +1473,20 @@ var cli = cac("pagetrace");
 cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
-  await writeFile(flags.out, `${JSON.stringify(snapshot, null, 2)}
-`, "utf8");
+  const written = await writeLockfile(flags.out, snapshot);
   const count = Object.keys(snapshot.pages).length;
-  console.log(pc2.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`));
+  console.log(
+    written ? pc2.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`) : pc2.dim(`${flags.out} is already up to date \u2014 ${count} page${count === 1 ? "" : "s"}.`)
+  );
 });
-cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").action(async (flags) => {
+cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").option("--baseline-branch <ref>", "Read the baseline lockfile from a git ref instead of disk").action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, false);
   const config = await loadConfig(flags.config);
   const next = await build(flags, config);
-  let previous = null;
-  try {
-    previous = JSON.parse(await readFile2(flags.lockfile, "utf8"));
-  } catch {
-    previous = null;
-  }
+  const previous = flags.baselineBranch ? await snapshotFromGitRef(flags.baselineBranch, flags.lockfile) : await readFile2(flags.lockfile, "utf8").then((text2) => JSON.parse(text2)).catch(() => null);
   if (!previous) {
-    console.error(
-      pc2.yellow(`No lockfile at ${flags.lockfile}. Run \`pagetrace snapshot\` first to set a baseline.`)
-    );
+    const where = flags.baselineBranch ? `No ${flags.lockfile} at ${flags.baselineBranch}.` : `No lockfile at ${flags.lockfile}.`;
+    console.error(pc2.yellow(`${where} Run \`pagetrace snapshot\` first to set a baseline.`));
   }
   const raw = [
     ...previous ? diffSnapshots(previous, next) : [],
@@ -1450,9 +1495,10 @@ cli.command("check", "Compare the current surface against the lockfile").option(
   const findings = applyConfig(raw, config);
   console.log(render(findings, flags.format));
   if (flags.update) {
-    await writeFile(flags.lockfile, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    console.error(pc2.dim(`Updated ${flags.lockfile}.`));
+    const written = await writeLockfile(flags.lockfile, next);
+    console.error(
+      pc2.dim(written ? `Updated ${flags.lockfile}.` : `${flags.lockfile} is already up to date.`)
+    );
   }
   const summary = summarize(findings);
   if (previous && shouldFail(findings, failOn)) {
@@ -1460,7 +1506,7 @@ cli.command("check", "Compare the current surface against the lockfile").option(
       pc2.red(`
 Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`)
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
@@ -1474,7 +1520,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
         "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
       )
     );
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
     return;
   }
   const platform = detectPlatform(
@@ -1500,19 +1546,18 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     console.log(output);
   }
   if (failOn !== "never" && shouldFail(findings, failOn)) {
-    process.exitCode = 1;
+    process.exitCode = EXIT_FINDINGS;
   }
 });
 cli.help();
-cli.version("0.3.0");
+cli.version("0.5.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
     await cli.runMatchedCommand();
   } catch (error) {
     console.error(pc2.red(error.message));
-    process.exitCode = 1;
+    process.exitCode = EXIT_FAILURE;
   }
 }
 void main();
-//# sourceMappingURL=cli.js.map

package/dist/index.cjs

@@ -58,9 +58,11 @@ __export(src_exports, {
   formatPretty: () => formatPretty,
   routeFromFilePath: () => routeFromFilePath,
   routeFromUrl: () => routeFromUrl,
+  sameSurface: () => sameSurface,
   shouldFail: () => shouldFail,
   shouldIgnore: () => shouldIgnore,
   snapshotFromDir: () => snapshotFromDir,
+  snapshotFromGitRef: () => snapshotFromGitRef,
   snapshotFromOrigin: () => snapshotFromOrigin,
   summarize: () => summarize,
   withGuidance: () => withGuidance
@@ -1109,7 +1111,7 @@ function formatPretty(findings) {
 function formatJson(findings) {
   return JSON.stringify({ schemaVersion: 1, summary: summarize(findings), findings }, null, 2);
 }
-var escapeCell = (value) => value.replace(/\|/g, "\\|");
+var escapeCell = (value) => value.replace(/\|/g, "\\|").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 function formatMarkdown(findings) {
   const s = summarize(findings);
   if (findings.length === 0) return "### pagetrace\n\nNo SEO/AEO changes or issues found.";
@@ -1298,8 +1300,10 @@ ${cards || "<p>No issues found.</p>"}
 }
 
 // src/snapshot.ts
+var import_node_child_process = require("child_process");
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
+var import_node_util = require("util");
 function routeFromFilePath(root, filePath) {
   const rel = (0, import_node_path.relative)(root, filePath).split(import_node_path.sep).join("/");
   const withoutExt = rel.replace(/\.html?$/i, "");
@@ -1315,6 +1319,32 @@ function routeFromUrl(url) {
     return url;
   }
 }
+var exec = (0, import_node_util.promisify)(import_node_child_process.execFile);
+async function snapshotFromGitRef(ref, path) {
+  try {
+    await exec("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch (cause) {
+    throw new Error(
+      `Cannot resolve git ref "${ref}". Fetch it first \u2014 a shallow CI checkout often has only the PR head.`,
+      { cause }
+    );
+  }
+  let stdout;
+  try {
+    ({ stdout } = await exec("git", ["show", `${ref}:${path}`], { maxBuffer: 256 * 1024 * 1024 }));
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch (cause) {
+    throw new Error(`${path} at ${ref} is not valid JSON.`, { cause });
+  }
+}
+function sameSurface(a, b) {
+  const strip = (s) => JSON.stringify({ ...s, createdAt: "" });
+  return strip(a) === strip(b);
+}
 function shouldIgnore(route, patterns = []) {
   return patterns.some(
     (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
@@ -1333,19 +1363,32 @@ async function walkHtml(dir, acc = []) {
   return acc;
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
+var MAX_ATTEMPTS = 3;
+var RETRY_BASE_MS = 300;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
 async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
-    });
-  } catch (cause) {
-    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    if (attempt > 1) await sleep(RETRY_BASE_MS * 3 ** (attempt - 2));
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+      });
+    } catch (cause) {
+      lastError = new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+      continue;
+    }
+    if (response.status === 404 || response.status === 410) return null;
+    if (response.ok) return await response.text();
+    lastError = new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+    if (!isTransient(response.status)) break;
   }
-  if (response.status === 404 || response.status === 410) return null;
-  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
-  return await response.text();
+  throw lastError;
 }
 function tryFetchText(url, timeoutMs) {
   return fetchText(url, timeoutMs).catch(() => null);
@@ -1468,11 +1511,12 @@ async function snapshotFromOrigin(origin, options = {}) {
   formatPretty,
   routeFromFilePath,
   routeFromUrl,
+  sameSurface,
   shouldFail,
   shouldIgnore,
   snapshotFromDir,
+  snapshotFromGitRef,
   snapshotFromOrigin,
   summarize,
   withGuidance
 });
-//# sourceMappingURL=index.cjs.map