pagetrace 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,52 @@ 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.6.0] - 2026-09-06
+
+### Changed
+
+- **Breaking.** `duplicate.title`, `duplicate.description` and
+  `duplicate.canonical` now emit one finding per affected route instead of a
+  single finding with `route: null`. Integrations reading `route` on these three
+  codes will see a path where they saw null; the codes themselves are unchanged.
+
+  Found by auditing a real site. The report said "2 pages share the same meta
+  description" and could not say which two, because the routes lived in `after`,
+  which the rollup drops — leaving the only actionable part of the finding
+  invisible. Per-route findings also make the counts truthful and point
+  `--format github` annotations at the pages rather than at "site".
+
+## [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. The comment is
+  skipped for pull requests from a fork, which run with a read-only token and
+  would otherwise fail with a 403 through no fault of the contributor; the
+  findings still reach the step summary and still set the exit code.
+- `snapshotFromGitRef(ref, path)` is exported.
+- `examples/site`, a small deliberately correct site with a committed baseline.
+  The action runs against it on every pull request to this repo, so a change
+  that breaks the action's own wiring fails here rather than in someone else's
+  CI. It doubles as a worked example of what a clean surface looks like.
+
+### 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
@@ -170,6 +216,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.6.0]: https://github.com/shyamexe/pagetrace/compare/v0.5.0...v0.6.0
+[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

package/README.md

@@ -151,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

@@ -266,39 +266,38 @@ function auditCrossPage(snapshot) {
     }
     return map;
   };
-  for (const [title, routes] of group((p) => p.title)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.title",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the title "${title}".`,
-        after: routes
-      });
-    }
-  }
-  for (const [, routes] of group((p) => p.description)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.description",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the same meta description.`,
-        after: routes
-      });
-    }
-  }
-  for (const [canonical, routes] of group((p) => p.canonical)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.canonical",
-        severity: "error",
-        route: null,
-        message: `${routes.length} pages canonicalise to ${canonical}.`,
-        after: routes
-      });
+  const duplicates = (code, severity, keyed, message) => {
+    for (const [value, routes] of keyed) {
+      if (routes.length < 2) continue;
+      for (const route of routes) {
+        findings.push({
+          code,
+          severity,
+          route,
+          message: message(value, routes.length),
+          after: routes
+        });
+      }
     }
-  }
+  };
+  duplicates(
+    "duplicate.title",
+    "warn",
+    group((p) => p.title),
+    (title, n) => `${n} pages share the title "${title}".`
+  );
+  duplicates(
+    "duplicate.description",
+    "warn",
+    group((p) => p.description),
+    (_, n) => `${n} pages share the same meta description.`
+  );
+  duplicates(
+    "duplicate.canonical",
+    "error",
+    group((p) => p.canonical),
+    (canonical, n) => `${n} pages canonicalise to ${canonical}.`
+  );
   const expectedOrigin = snapshot.site.origin ?? null;
   for (const page of pages) {
     if (!page.canonical) continue;
@@ -866,7 +865,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 +1054,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 +1279,28 @@ 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);
@@ -1478,20 +1501,14 @@ cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").opti
     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) : [],
@@ -1555,7 +1572,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.4.0");
+cli.version("0.6.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/cli.js

@@ -243,39 +243,38 @@ function auditCrossPage(snapshot) {
     }
     return map;
   };
-  for (const [title, routes] of group((p) => p.title)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.title",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the title "${title}".`,
-        after: routes
-      });
-    }
-  }
-  for (const [, routes] of group((p) => p.description)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.description",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the same meta description.`,
-        after: routes
-      });
-    }
-  }
-  for (const [canonical, routes] of group((p) => p.canonical)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.canonical",
-        severity: "error",
-        route: null,
-        message: `${routes.length} pages canonicalise to ${canonical}.`,
-        after: routes
-      });
+  const duplicates = (code, severity, keyed, message) => {
+    for (const [value, routes] of keyed) {
+      if (routes.length < 2) continue;
+      for (const route of routes) {
+        findings.push({
+          code,
+          severity,
+          route,
+          message: message(value, routes.length),
+          after: routes
+        });
+      }
     }
-  }
+  };
+  duplicates(
+    "duplicate.title",
+    "warn",
+    group((p) => p.title),
+    (title, n) => `${n} pages share the title "${title}".`
+  );
+  duplicates(
+    "duplicate.description",
+    "warn",
+    group((p) => p.description),
+    (_, n) => `${n} pages share the same meta description.`
+  );
+  duplicates(
+    "duplicate.canonical",
+    "error",
+    group((p) => p.canonical),
+    (canonical, n) => `${n} pages canonicalise to ${canonical}.`
+  );
   const expectedOrigin = snapshot.site.origin ?? null;
   for (const page of pages) {
     if (!page.canonical) continue;
@@ -843,7 +842,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 +1031,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 +1256,28 @@ 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);
@@ -1455,20 +1478,14 @@ cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").opti
     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) : [],
@@ -1532,7 +1549,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.4.0");
+cli.version("0.6.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(src_exports, {
   shouldFail: () => shouldFail,
   shouldIgnore: () => shouldIgnore,
   snapshotFromDir: () => snapshotFromDir,
+  snapshotFromGitRef: () => snapshotFromGitRef,
   snapshotFromOrigin: () => snapshotFromOrigin,
   summarize: () => summarize,
   withGuidance: () => withGuidance
@@ -306,39 +307,38 @@ function auditCrossPage(snapshot) {
     }
     return map;
   };
-  for (const [title, routes] of group((p) => p.title)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.title",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the title "${title}".`,
-        after: routes
-      });
-    }
-  }
-  for (const [, routes] of group((p) => p.description)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.description",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the same meta description.`,
-        after: routes
-      });
-    }
-  }
-  for (const [canonical, routes] of group((p) => p.canonical)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.canonical",
-        severity: "error",
-        route: null,
-        message: `${routes.length} pages canonicalise to ${canonical}.`,
-        after: routes
-      });
+  const duplicates = (code, severity, keyed, message) => {
+    for (const [value, routes] of keyed) {
+      if (routes.length < 2) continue;
+      for (const route of routes) {
+        findings.push({
+          code,
+          severity,
+          route,
+          message: message(value, routes.length),
+          after: routes
+        });
+      }
     }
-  }
+  };
+  duplicates(
+    "duplicate.title",
+    "warn",
+    group((p) => p.title),
+    (title, n) => `${n} pages share the title "${title}".`
+  );
+  duplicates(
+    "duplicate.description",
+    "warn",
+    group((p) => p.description),
+    (_, n) => `${n} pages share the same meta description.`
+  );
+  duplicates(
+    "duplicate.canonical",
+    "error",
+    group((p) => p.canonical),
+    (canonical, n) => `${n} pages canonicalise to ${canonical}.`
+  );
   const expectedOrigin = snapshot.site.origin ?? null;
   for (const page of pages) {
     if (!page.canonical) continue;
@@ -1110,7 +1110,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.";
@@ -1299,8 +1299,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, "");
@@ -1316,6 +1318,28 @@ 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);
@@ -1490,6 +1514,7 @@ async function snapshotFromOrigin(origin, options = {}) {
   shouldFail,
   shouldIgnore,
   snapshotFromDir,
+  snapshotFromGitRef,
   snapshotFromOrigin,
   summarize,
   withGuidance

package/dist/index.d.cts

@@ -215,6 +215,14 @@ declare const DEFAULT_AI_AGENTS: string[];
 
 declare function routeFromFilePath(root: string, filePath: string): string;
 declare function routeFromUrl(url: string): string;
+/**
+ * Read a committed lockfile out of a git ref rather than the working tree, so a
+ * pull request can diff against the baseline on `main` without carrying a
+ * lockfile of its own. Returns null when the ref has no lockfile at that path —
+ * an ordinary first run — but throws when the ref itself is unresolvable, since
+ * a typo in `--baseline-branch` must not read as "nothing to compare".
+ */
+declare function snapshotFromGitRef(ref: string, path: string): Promise<Snapshot | null>;
 /**
  * Whether two snapshots describe the same surface, ignoring when they were
  * taken. The lockfile is meant to be committed, so writing a fresh timestamp on
@@ -237,4 +245,4 @@ interface CrawlOptions extends Config {
 /** Build a snapshot by fetching a live origin, discovering routes via sitemap. */
 declare function snapshotFromOrigin(origin: string, options?: CrawlOptions): Promise<Snapshot>;
 
-export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromOrigin, summarize, withGuidance };
+export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, summarize, withGuidance };

package/dist/index.d.ts

@@ -215,6 +215,14 @@ declare const DEFAULT_AI_AGENTS: string[];
 
 declare function routeFromFilePath(root: string, filePath: string): string;
 declare function routeFromUrl(url: string): string;
+/**
+ * Read a committed lockfile out of a git ref rather than the working tree, so a
+ * pull request can diff against the baseline on `main` without carrying a
+ * lockfile of its own. Returns null when the ref has no lockfile at that path —
+ * an ordinary first run — but throws when the ref itself is unresolvable, since
+ * a typo in `--baseline-branch` must not read as "nothing to compare".
+ */
+declare function snapshotFromGitRef(ref: string, path: string): Promise<Snapshot | null>;
 /**
  * Whether two snapshots describe the same surface, ignoring when they were
  * taken. The lockfile is meant to be committed, so writing a fresh timestamp on
@@ -237,4 +245,4 @@ interface CrawlOptions extends Config {
 /** Build a snapshot by fetching a live origin, discovering routes via sitemap. */
 declare function snapshotFromOrigin(origin: string, options?: CrawlOptions): Promise<Snapshot>;
 
-export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromOrigin, summarize, withGuidance };
+export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, summarize, withGuidance };

package/dist/index.js

@@ -236,39 +236,38 @@ function auditCrossPage(snapshot) {
     }
     return map;
   };
-  for (const [title, routes] of group((p) => p.title)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.title",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the title "${title}".`,
-        after: routes
-      });
-    }
-  }
-  for (const [, routes] of group((p) => p.description)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.description",
-        severity: "warn",
-        route: null,
-        message: `${routes.length} pages share the same meta description.`,
-        after: routes
-      });
-    }
-  }
-  for (const [canonical, routes] of group((p) => p.canonical)) {
-    if (routes.length > 1) {
-      findings.push({
-        code: "duplicate.canonical",
-        severity: "error",
-        route: null,
-        message: `${routes.length} pages canonicalise to ${canonical}.`,
-        after: routes
-      });
+  const duplicates = (code, severity, keyed, message) => {
+    for (const [value, routes] of keyed) {
+      if (routes.length < 2) continue;
+      for (const route of routes) {
+        findings.push({
+          code,
+          severity,
+          route,
+          message: message(value, routes.length),
+          after: routes
+        });
+      }
     }
-  }
+  };
+  duplicates(
+    "duplicate.title",
+    "warn",
+    group((p) => p.title),
+    (title, n) => `${n} pages share the title "${title}".`
+  );
+  duplicates(
+    "duplicate.description",
+    "warn",
+    group((p) => p.description),
+    (_, n) => `${n} pages share the same meta description.`
+  );
+  duplicates(
+    "duplicate.canonical",
+    "error",
+    group((p) => p.canonical),
+    (canonical, n) => `${n} pages canonicalise to ${canonical}.`
+  );
   const expectedOrigin = snapshot.site.origin ?? null;
   for (const page of pages) {
     if (!page.canonical) continue;
@@ -1040,7 +1039,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.";
@@ -1229,8 +1228,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";
 function routeFromFilePath(root, filePath) {
   const rel = relative(root, filePath).split(sep).join("/");
   const withoutExt = rel.replace(/\.html?$/i, "");
@@ -1246,6 +1247,28 @@ 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);
@@ -1419,6 +1442,7 @@ export {
   shouldFail,
   shouldIgnore,
   snapshotFromDir,
+  snapshotFromGitRef,
   snapshotFromOrigin,
   summarize,
   withGuidance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagetrace",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Baseline your site's SEO and AEO surface, diff every build against it, and fail CI on regressions.",
   "main": "./dist/index.cjs",
   "scripts": {