pagetrace 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,42 @@ 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.7.0] - 2026-09-06
+
+### Changed
+
+- The terminal audit report is laid out rather than printed. Findings sit under a
+  rule per severity, prose wraps to the terminal instead of running off the right
+  edge, the affected routes get their own line, and the page count is right
+  aligned against the headline. The old output put explanation, fix and routes at
+  the same indent with no wrapping, so on a real site the useful part was the
+  hardest part to find.
+- `formatAuditPretty(groups, meta, columns?)` takes an optional terminal width,
+  defaulting to 80. The CLI passes `process.stdout.columns`, which keeps
+  `report.ts` free of environment reads. Piped output falls back to 80 and drops
+  colour, so it stays readable in a CI log.
+
+### Fixed
+
+- A word longer than the terminal is hard-broken instead of overflowing. A
+  canonical URL is a single word and is routinely longer than 80 characters, so
+  `duplicate.canonical` could push a line well past the edge.
+
+## [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
@@ -20,8 +56,15 @@ While the version is below 1.0.0, breaking changes ship in a minor release.
 - 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.
+  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
 
@@ -194,6 +237,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.7.0]: https://github.com/shyamexe/pagetrace/compare/v0.6.0...v0.7.0
+[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

package/README.md

@@ -72,16 +72,27 @@ npx pagetrace audit --url https://example.com --format html --out audit.html
 Findings are rolled up by issue rather than by page, so one template defect reads as a single row affecting 43 pages instead of 43 separate lines. Each row carries why it matters and how to fix it, and the fix is platform-aware — `pagetrace` reads the generator tag and asset paths, so a WordPress site gets Yoast and Rank Math instructions rather than generic advice.
 
 ```
-ERROR 2 pages canonicalise to https://acme.test/shop.                          (1)
+pagetrace · https://acme.test
+43 pages · WordPress · 2026-09-06
+
+ERRORS ─────────────────────────────────────────────────────────────────────── 2
+
+✗ 2 pages canonicalise to https://acme.test/shop.                        2 pages
   Several pages pointing at one canonical means those pages are declaring
   themselves duplicates and will not rank independently.
-  Fix: A common symptom of a plugin canonicalising every archive page to the parent.
+  → A common symptom of a plugin canonicalising every archive page to the
+    parent.
+  /shop/page/2, /shop/page/3
 
-ERROR Page has no <h1>.                                                        (1)
+✗ Page has no <h1>.                                                       1 page
   The h1 anchors the document outline used for passage extraction.
-  Fix: Many themes render the post title as h2 inside archive templates.
-       Check single.php or the block template for this post type.
+  → Many themes render the post title as h2 inside archive templates. Check
+    single.php or the block template for this post type.
   /tag/widgets
+
+────────────────────────────────────────────────────────────────────────────────
+2 issues  2 errors
+3 findings across 43 pages
 ```
 
 Auditing runs cross-page rules the per-page checks cannot see: duplicate titles and descriptions, several pages canonicalising to one URL, canonicals pointing away from their own path or at another host entirely, and a full hreflang check. Paginated archives and AMP variants are left alone, since canonicalising those to their parent is correct.

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;
@@ -941,33 +940,102 @@ function sampleRoutes(routes, limit = 5) {
   const shown = routes.slice(0, limit).join(", ");
   return routes.length > limit ? `${shown} +${routes.length - limit} more` : shown;
 }
-function formatAuditPretty(groups, meta) {
+var GLYPH = { error: "\u2717", warn: "\u25B2", info: "\xB7" };
+var PLURAL = { error: "errors", warn: "warnings", info: "notes" };
+var SINGULAR = { error: "error", warn: "warning", info: "note" };
+function wrapText(text2, width) {
+  const lines = [];
+  let line = "";
+  const flush = () => {
+    if (line) lines.push(line);
+    line = "";
+  };
+  for (const word of text2.split(/\s+/)) {
+    if (word.length > width) {
+      flush();
+      for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+      continue;
+    }
+    if (line && line.length + 1 + word.length > width) {
+      flush();
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  flush();
+  return lines;
+}
+function sectionRule(severity, count, width) {
+  const label = PLURAL[severity].toUpperCase();
+  const tail = String(count);
+  const dashes = Math.max(3, width - label.length - tail.length - 2);
+  return `${BADGE[severity](import_picocolors.default.bold(label))} ${import_picocolors.default.dim("\u2500".repeat(dashes))} ${import_picocolors.default.dim(tail)}`;
+}
+function formatAuditPretty(groups, meta, columns = 80) {
+  const width = Math.min(Math.max(columns, 48), 96);
+  const indent = "  ";
+  const body = width - indent.length;
   const lines = [
-    import_picocolors.default.bold(meta.target),
-    import_picocolors.default.dim(`${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages \xB7 ${meta.generatedAt}`),
+    `${import_picocolors.default.bold("pagetrace")} ${import_picocolors.default.dim("\xB7")} ${meta.target}`,
+    import_picocolors.default.dim(
+      [
+        `${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`,
+        meta.platform === "unknown" ? null : PLATFORM_LABEL[meta.platform],
+        meta.generatedAt
+      ].filter(Boolean).join(" \xB7 ")
+    ),
     ""
   ];
   if (groups.length === 0) {
-    lines.push(import_picocolors.default.green("No issues found."));
+    lines.push(import_picocolors.default.green(`\u2713 No issues found across ${meta.pageCount} pages.`), "");
     return lines.join("\n");
   }
-  for (const group of groups) {
-    const scope = isTemplateWide(group, meta.pageCount) ? import_picocolors.default.dim(`(${group.count} pages \u2014 one template fix)`) : import_picocolors.default.dim(`(${group.count})`);
-    lines.push(`${BADGE[group.severity](group.severity.toUpperCase())} ${import_picocolors.default.bold(group.message)} ${scope}`);
-    if (group.detail) lines.push(`  ${group.detail}`);
-    if (group.fix) lines.push(`  ${import_picocolors.default.cyan("Fix:")} ${group.fix}`);
-    if (group.routes.length > 0) lines.push(`  ${import_picocolors.default.dim(sampleRoutes(group.routes))}`);
-    lines.push("");
+  for (const severity of ["error", "warn", "info"]) {
+    const inSeverity = groups.filter((g) => g.severity === severity);
+    if (inSeverity.length === 0) continue;
+    lines.push(sectionRule(severity, inSeverity.length, width), "");
+    for (const group of inSeverity) {
+      const scope = isTemplateWide(group, meta.pageCount) ? `${group.count} pages \xB7 one template fix` : `${group.count} page${group.count === 1 ? "" : "s"}`;
+      const headline = group.message;
+      const room = width - 2 - scope.length - 1;
+      if (headline.length <= room) {
+        const pad = " ".repeat(Math.max(1, room - headline.length + 1));
+        lines.push(
+          `${BADGE[severity](GLYPH[severity])} ${import_picocolors.default.bold(headline)}${pad}${import_picocolors.default.dim(scope)}`
+        );
+      } else {
+        for (const [i, line] of wrapText(headline, width - 2).entries()) {
+          lines.push(i === 0 ? `${BADGE[severity](GLYPH[severity])} ${import_picocolors.default.bold(line)}` : `${indent}${import_picocolors.default.bold(line)}`);
+        }
+        lines.push(`${indent}${import_picocolors.default.dim(scope)}`);
+      }
+      if (group.detail) {
+        for (const line of wrapText(group.detail, body)) lines.push(`${indent}${import_picocolors.default.dim(line)}`);
+      }
+      if (group.fix) {
+        const [first, ...rest] = wrapText(group.fix, body - 2);
+        lines.push(`${indent}${import_picocolors.default.cyan("\u2192")} ${first}`);
+        for (const line of rest) lines.push(`${indent}  ${line}`);
+      }
+      if (group.routes.length > 0) {
+        for (const line of wrapText(sampleRoutes(group.routes), body)) {
+          lines.push(`${indent}${import_picocolors.default.dim(line)}`);
+        }
+      }
+      lines.push("");
+    }
   }
   const { issues, instances, total } = countIssues(groups);
-  lines.push(
-    `${total} issue${total === 1 ? "" : "s"}: ${issues.error} error, ${issues.warn} warning, ${issues.info} info`
-  );
+  const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(import_picocolors.default.dim(" \xB7 "));
+  lines.push(import_picocolors.default.dim("\u2500".repeat(width)));
+  lines.push(`${import_picocolors.default.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
   lines.push(
     import_picocolors.default.dim(
-      `across ${instances.error + instances.warn + instances.info} page findings on ${meta.pageCount} pages`
+      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
     )
   );
+  lines.push("");
   return lines.join("\n");
 }
 function formatAuditMarkdown(groups, meta) {
@@ -1560,7 +1628,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     pageCount: pages.length,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
   };
-  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : flags.format === "html" ? formatAuditHtml(groups, meta) : formatAuditPretty(groups, meta);
+  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : flags.format === "html" ? formatAuditHtml(groups, meta) : formatAuditPretty(groups, meta, process.stdout.columns);
   if (flags.out) {
     await (0, import_promises2.writeFile)(flags.out, `${output}
 `, "utf8");
@@ -1573,7 +1641,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.5.0");
+cli.version("0.7.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;
@@ -918,33 +917,102 @@ function sampleRoutes(routes, limit = 5) {
   const shown = routes.slice(0, limit).join(", ");
   return routes.length > limit ? `${shown} +${routes.length - limit} more` : shown;
 }
-function formatAuditPretty(groups, meta) {
+var GLYPH = { error: "\u2717", warn: "\u25B2", info: "\xB7" };
+var PLURAL = { error: "errors", warn: "warnings", info: "notes" };
+var SINGULAR = { error: "error", warn: "warning", info: "note" };
+function wrapText(text2, width) {
+  const lines = [];
+  let line = "";
+  const flush = () => {
+    if (line) lines.push(line);
+    line = "";
+  };
+  for (const word of text2.split(/\s+/)) {
+    if (word.length > width) {
+      flush();
+      for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+      continue;
+    }
+    if (line && line.length + 1 + word.length > width) {
+      flush();
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  flush();
+  return lines;
+}
+function sectionRule(severity, count, width) {
+  const label = PLURAL[severity].toUpperCase();
+  const tail = String(count);
+  const dashes = Math.max(3, width - label.length - tail.length - 2);
+  return `${BADGE[severity](pc.bold(label))} ${pc.dim("\u2500".repeat(dashes))} ${pc.dim(tail)}`;
+}
+function formatAuditPretty(groups, meta, columns = 80) {
+  const width = Math.min(Math.max(columns, 48), 96);
+  const indent = "  ";
+  const body = width - indent.length;
   const lines = [
-    pc.bold(meta.target),
-    pc.dim(`${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages \xB7 ${meta.generatedAt}`),
+    `${pc.bold("pagetrace")} ${pc.dim("\xB7")} ${meta.target}`,
+    pc.dim(
+      [
+        `${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`,
+        meta.platform === "unknown" ? null : PLATFORM_LABEL[meta.platform],
+        meta.generatedAt
+      ].filter(Boolean).join(" \xB7 ")
+    ),
     ""
   ];
   if (groups.length === 0) {
-    lines.push(pc.green("No issues found."));
+    lines.push(pc.green(`\u2713 No issues found across ${meta.pageCount} pages.`), "");
     return lines.join("\n");
   }
-  for (const group of groups) {
-    const scope = isTemplateWide(group, meta.pageCount) ? pc.dim(`(${group.count} pages \u2014 one template fix)`) : pc.dim(`(${group.count})`);
-    lines.push(`${BADGE[group.severity](group.severity.toUpperCase())} ${pc.bold(group.message)} ${scope}`);
-    if (group.detail) lines.push(`  ${group.detail}`);
-    if (group.fix) lines.push(`  ${pc.cyan("Fix:")} ${group.fix}`);
-    if (group.routes.length > 0) lines.push(`  ${pc.dim(sampleRoutes(group.routes))}`);
-    lines.push("");
+  for (const severity of ["error", "warn", "info"]) {
+    const inSeverity = groups.filter((g) => g.severity === severity);
+    if (inSeverity.length === 0) continue;
+    lines.push(sectionRule(severity, inSeverity.length, width), "");
+    for (const group of inSeverity) {
+      const scope = isTemplateWide(group, meta.pageCount) ? `${group.count} pages \xB7 one template fix` : `${group.count} page${group.count === 1 ? "" : "s"}`;
+      const headline = group.message;
+      const room = width - 2 - scope.length - 1;
+      if (headline.length <= room) {
+        const pad = " ".repeat(Math.max(1, room - headline.length + 1));
+        lines.push(
+          `${BADGE[severity](GLYPH[severity])} ${pc.bold(headline)}${pad}${pc.dim(scope)}`
+        );
+      } else {
+        for (const [i, line] of wrapText(headline, width - 2).entries()) {
+          lines.push(i === 0 ? `${BADGE[severity](GLYPH[severity])} ${pc.bold(line)}` : `${indent}${pc.bold(line)}`);
+        }
+        lines.push(`${indent}${pc.dim(scope)}`);
+      }
+      if (group.detail) {
+        for (const line of wrapText(group.detail, body)) lines.push(`${indent}${pc.dim(line)}`);
+      }
+      if (group.fix) {
+        const [first, ...rest] = wrapText(group.fix, body - 2);
+        lines.push(`${indent}${pc.cyan("\u2192")} ${first}`);
+        for (const line of rest) lines.push(`${indent}  ${line}`);
+      }
+      if (group.routes.length > 0) {
+        for (const line of wrapText(sampleRoutes(group.routes), body)) {
+          lines.push(`${indent}${pc.dim(line)}`);
+        }
+      }
+      lines.push("");
+    }
   }
   const { issues, instances, total } = countIssues(groups);
-  lines.push(
-    `${total} issue${total === 1 ? "" : "s"}: ${issues.error} error, ${issues.warn} warning, ${issues.info} info`
-  );
+  const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(pc.dim(" \xB7 "));
+  lines.push(pc.dim("\u2500".repeat(width)));
+  lines.push(`${pc.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
   lines.push(
     pc.dim(
-      `across ${instances.error + instances.warn + instances.info} page findings on ${meta.pageCount} pages`
+      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
     )
   );
+  lines.push("");
   return lines.join("\n");
 }
 function formatAuditMarkdown(groups, meta) {
@@ -1537,7 +1605,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     pageCount: pages.length,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
   };
-  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : flags.format === "html" ? formatAuditHtml(groups, meta) : formatAuditPretty(groups, meta);
+  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : flags.format === "html" ? formatAuditHtml(groups, meta) : formatAuditPretty(groups, meta, process.stdout.columns);
   if (flags.out) {
     await writeFile(flags.out, `${output}
 `, "utf8");
@@ -1550,7 +1618,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.5.0");
+cli.version("0.7.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/index.cjs

@@ -307,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;
@@ -1186,33 +1185,102 @@ function sampleRoutes(routes, limit = 5) {
   const shown = routes.slice(0, limit).join(", ");
   return routes.length > limit ? `${shown} +${routes.length - limit} more` : shown;
 }
-function formatAuditPretty(groups, meta) {
+var GLYPH = { error: "\u2717", warn: "\u25B2", info: "\xB7" };
+var PLURAL = { error: "errors", warn: "warnings", info: "notes" };
+var SINGULAR = { error: "error", warn: "warning", info: "note" };
+function wrapText(text2, width) {
+  const lines = [];
+  let line = "";
+  const flush = () => {
+    if (line) lines.push(line);
+    line = "";
+  };
+  for (const word of text2.split(/\s+/)) {
+    if (word.length > width) {
+      flush();
+      for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+      continue;
+    }
+    if (line && line.length + 1 + word.length > width) {
+      flush();
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  flush();
+  return lines;
+}
+function sectionRule(severity, count, width) {
+  const label = PLURAL[severity].toUpperCase();
+  const tail = String(count);
+  const dashes = Math.max(3, width - label.length - tail.length - 2);
+  return `${BADGE[severity](import_picocolors.default.bold(label))} ${import_picocolors.default.dim("\u2500".repeat(dashes))} ${import_picocolors.default.dim(tail)}`;
+}
+function formatAuditPretty(groups, meta, columns = 80) {
+  const width = Math.min(Math.max(columns, 48), 96);
+  const indent = "  ";
+  const body = width - indent.length;
   const lines = [
-    import_picocolors.default.bold(meta.target),
-    import_picocolors.default.dim(`${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages \xB7 ${meta.generatedAt}`),
+    `${import_picocolors.default.bold("pagetrace")} ${import_picocolors.default.dim("\xB7")} ${meta.target}`,
+    import_picocolors.default.dim(
+      [
+        `${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`,
+        meta.platform === "unknown" ? null : PLATFORM_LABEL[meta.platform],
+        meta.generatedAt
+      ].filter(Boolean).join(" \xB7 ")
+    ),
     ""
   ];
   if (groups.length === 0) {
-    lines.push(import_picocolors.default.green("No issues found."));
+    lines.push(import_picocolors.default.green(`\u2713 No issues found across ${meta.pageCount} pages.`), "");
     return lines.join("\n");
   }
-  for (const group of groups) {
-    const scope = isTemplateWide(group, meta.pageCount) ? import_picocolors.default.dim(`(${group.count} pages \u2014 one template fix)`) : import_picocolors.default.dim(`(${group.count})`);
-    lines.push(`${BADGE[group.severity](group.severity.toUpperCase())} ${import_picocolors.default.bold(group.message)} ${scope}`);
-    if (group.detail) lines.push(`  ${group.detail}`);
-    if (group.fix) lines.push(`  ${import_picocolors.default.cyan("Fix:")} ${group.fix}`);
-    if (group.routes.length > 0) lines.push(`  ${import_picocolors.default.dim(sampleRoutes(group.routes))}`);
-    lines.push("");
+  for (const severity of ["error", "warn", "info"]) {
+    const inSeverity = groups.filter((g) => g.severity === severity);
+    if (inSeverity.length === 0) continue;
+    lines.push(sectionRule(severity, inSeverity.length, width), "");
+    for (const group of inSeverity) {
+      const scope = isTemplateWide(group, meta.pageCount) ? `${group.count} pages \xB7 one template fix` : `${group.count} page${group.count === 1 ? "" : "s"}`;
+      const headline = group.message;
+      const room = width - 2 - scope.length - 1;
+      if (headline.length <= room) {
+        const pad = " ".repeat(Math.max(1, room - headline.length + 1));
+        lines.push(
+          `${BADGE[severity](GLYPH[severity])} ${import_picocolors.default.bold(headline)}${pad}${import_picocolors.default.dim(scope)}`
+        );
+      } else {
+        for (const [i, line] of wrapText(headline, width - 2).entries()) {
+          lines.push(i === 0 ? `${BADGE[severity](GLYPH[severity])} ${import_picocolors.default.bold(line)}` : `${indent}${import_picocolors.default.bold(line)}`);
+        }
+        lines.push(`${indent}${import_picocolors.default.dim(scope)}`);
+      }
+      if (group.detail) {
+        for (const line of wrapText(group.detail, body)) lines.push(`${indent}${import_picocolors.default.dim(line)}`);
+      }
+      if (group.fix) {
+        const [first, ...rest] = wrapText(group.fix, body - 2);
+        lines.push(`${indent}${import_picocolors.default.cyan("\u2192")} ${first}`);
+        for (const line of rest) lines.push(`${indent}  ${line}`);
+      }
+      if (group.routes.length > 0) {
+        for (const line of wrapText(sampleRoutes(group.routes), body)) {
+          lines.push(`${indent}${import_picocolors.default.dim(line)}`);
+        }
+      }
+      lines.push("");
+    }
   }
   const { issues, instances, total } = countIssues(groups);
-  lines.push(
-    `${total} issue${total === 1 ? "" : "s"}: ${issues.error} error, ${issues.warn} warning, ${issues.info} info`
-  );
+  const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(import_picocolors.default.dim(" \xB7 "));
+  lines.push(import_picocolors.default.dim("\u2500".repeat(width)));
+  lines.push(`${import_picocolors.default.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
   lines.push(
     import_picocolors.default.dim(
-      `across ${instances.error + instances.warn + instances.info} page findings on ${meta.pageCount} pages`
+      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
     )
   );
+  lines.push("");
   return lines.join("\n");
 }
 function formatAuditMarkdown(groups, meta) {

package/dist/index.d.cts

@@ -192,7 +192,13 @@ interface AuditMeta {
     pageCount: number;
     generatedAt: string;
 }
-declare function formatAuditPretty(groups: Aggregate[], meta: AuditMeta): string;
+/**
+ * The terminal report. Findings are grouped under a rule per severity, prose is
+ * wrapped to the terminal rather than running off it, and the affected routes
+ * sit on their own line — they are the part you act on, and they used to blend
+ * into the surrounding text.
+ */
+declare function formatAuditPretty(groups: Aggregate[], meta: AuditMeta, columns?: number): string;
 declare function formatAuditMarkdown(groups: Aggregate[], meta: AuditMeta): string;
 /** Self-contained HTML report, suitable for handing to a client. */
 declare function formatAuditHtml(groups: Aggregate[], meta: AuditMeta): string;

package/dist/index.d.ts

@@ -192,7 +192,13 @@ interface AuditMeta {
     pageCount: number;
     generatedAt: string;
 }
-declare function formatAuditPretty(groups: Aggregate[], meta: AuditMeta): string;
+/**
+ * The terminal report. Findings are grouped under a rule per severity, prose is
+ * wrapped to the terminal rather than running off it, and the affected routes
+ * sit on their own line — they are the part you act on, and they used to blend
+ * into the surrounding text.
+ */
+declare function formatAuditPretty(groups: Aggregate[], meta: AuditMeta, columns?: number): string;
 declare function formatAuditMarkdown(groups: Aggregate[], meta: AuditMeta): string;
 /** Self-contained HTML report, suitable for handing to a client. */
 declare function formatAuditHtml(groups: Aggregate[], meta: AuditMeta): string;

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;
@@ -1115,33 +1114,102 @@ function sampleRoutes(routes, limit = 5) {
   const shown = routes.slice(0, limit).join(", ");
   return routes.length > limit ? `${shown} +${routes.length - limit} more` : shown;
 }
-function formatAuditPretty(groups, meta) {
+var GLYPH = { error: "\u2717", warn: "\u25B2", info: "\xB7" };
+var PLURAL = { error: "errors", warn: "warnings", info: "notes" };
+var SINGULAR = { error: "error", warn: "warning", info: "note" };
+function wrapText(text2, width) {
+  const lines = [];
+  let line = "";
+  const flush = () => {
+    if (line) lines.push(line);
+    line = "";
+  };
+  for (const word of text2.split(/\s+/)) {
+    if (word.length > width) {
+      flush();
+      for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+      continue;
+    }
+    if (line && line.length + 1 + word.length > width) {
+      flush();
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  flush();
+  return lines;
+}
+function sectionRule(severity, count, width) {
+  const label = PLURAL[severity].toUpperCase();
+  const tail = String(count);
+  const dashes = Math.max(3, width - label.length - tail.length - 2);
+  return `${BADGE[severity](pc.bold(label))} ${pc.dim("\u2500".repeat(dashes))} ${pc.dim(tail)}`;
+}
+function formatAuditPretty(groups, meta, columns = 80) {
+  const width = Math.min(Math.max(columns, 48), 96);
+  const indent = "  ";
+  const body = width - indent.length;
   const lines = [
-    pc.bold(meta.target),
-    pc.dim(`${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages \xB7 ${meta.generatedAt}`),
+    `${pc.bold("pagetrace")} ${pc.dim("\xB7")} ${meta.target}`,
+    pc.dim(
+      [
+        `${meta.pageCount} page${meta.pageCount === 1 ? "" : "s"}`,
+        meta.platform === "unknown" ? null : PLATFORM_LABEL[meta.platform],
+        meta.generatedAt
+      ].filter(Boolean).join(" \xB7 ")
+    ),
     ""
   ];
   if (groups.length === 0) {
-    lines.push(pc.green("No issues found."));
+    lines.push(pc.green(`\u2713 No issues found across ${meta.pageCount} pages.`), "");
     return lines.join("\n");
   }
-  for (const group of groups) {
-    const scope = isTemplateWide(group, meta.pageCount) ? pc.dim(`(${group.count} pages \u2014 one template fix)`) : pc.dim(`(${group.count})`);
-    lines.push(`${BADGE[group.severity](group.severity.toUpperCase())} ${pc.bold(group.message)} ${scope}`);
-    if (group.detail) lines.push(`  ${group.detail}`);
-    if (group.fix) lines.push(`  ${pc.cyan("Fix:")} ${group.fix}`);
-    if (group.routes.length > 0) lines.push(`  ${pc.dim(sampleRoutes(group.routes))}`);
-    lines.push("");
+  for (const severity of ["error", "warn", "info"]) {
+    const inSeverity = groups.filter((g) => g.severity === severity);
+    if (inSeverity.length === 0) continue;
+    lines.push(sectionRule(severity, inSeverity.length, width), "");
+    for (const group of inSeverity) {
+      const scope = isTemplateWide(group, meta.pageCount) ? `${group.count} pages \xB7 one template fix` : `${group.count} page${group.count === 1 ? "" : "s"}`;
+      const headline = group.message;
+      const room = width - 2 - scope.length - 1;
+      if (headline.length <= room) {
+        const pad = " ".repeat(Math.max(1, room - headline.length + 1));
+        lines.push(
+          `${BADGE[severity](GLYPH[severity])} ${pc.bold(headline)}${pad}${pc.dim(scope)}`
+        );
+      } else {
+        for (const [i, line] of wrapText(headline, width - 2).entries()) {
+          lines.push(i === 0 ? `${BADGE[severity](GLYPH[severity])} ${pc.bold(line)}` : `${indent}${pc.bold(line)}`);
+        }
+        lines.push(`${indent}${pc.dim(scope)}`);
+      }
+      if (group.detail) {
+        for (const line of wrapText(group.detail, body)) lines.push(`${indent}${pc.dim(line)}`);
+      }
+      if (group.fix) {
+        const [first, ...rest] = wrapText(group.fix, body - 2);
+        lines.push(`${indent}${pc.cyan("\u2192")} ${first}`);
+        for (const line of rest) lines.push(`${indent}  ${line}`);
+      }
+      if (group.routes.length > 0) {
+        for (const line of wrapText(sampleRoutes(group.routes), body)) {
+          lines.push(`${indent}${pc.dim(line)}`);
+        }
+      }
+      lines.push("");
+    }
   }
   const { issues, instances, total } = countIssues(groups);
-  lines.push(
-    `${total} issue${total === 1 ? "" : "s"}: ${issues.error} error, ${issues.warn} warning, ${issues.info} info`
-  );
+  const counted = ["error", "warn", "info"].filter((s) => issues[s] > 0).map((s) => BADGE[s](`${issues[s]} ${issues[s] === 1 ? SINGULAR[s] : PLURAL[s]}`)).join(pc.dim(" \xB7 "));
+  lines.push(pc.dim("\u2500".repeat(width)));
+  lines.push(`${pc.bold(`${total} issue${total === 1 ? "" : "s"}`)}  ${counted}`);
   lines.push(
     pc.dim(
-      `across ${instances.error + instances.warn + instances.info} page findings on ${meta.pageCount} pages`
+      `${instances.error + instances.warn + instances.info} findings across ${meta.pageCount} pages`
     )
   );
+  lines.push("");
   return lines.join("\n");
 }
 function formatAuditMarkdown(groups, meta) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagetrace",
-  "version": "0.5.0",
+  "version": "0.7.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": {