pagetrace 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ 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.8.0] - 2026-09-06
+
+### Fixed
+
+- `siteUrl` now overrides the crawled origin for an origin crawl, not just a
+  `--dir` crawl. Checking a local build or a preview deployment means crawling
+  `http://localhost:3000` while every page's canonical points at production, so
+  `canonical.offsite` fired on every page and made the check useless in exactly
+  the setup it is most wanted. Where you crawl and what the site calls itself are
+  separate things; `siteUrl` is now the authority on the latter. Without it the
+  crawled origin is still used, so nothing changes for a plain production crawl.
+
+## [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
@@ -216,6 +249,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.8.0]: https://github.com/shyamexe/pagetrace/compare/v0.7.0...v0.8.0
+[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

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.
@@ -145,7 +156,7 @@ Alongside the diff, `check` runs absolute rules: missing title, canonical, `h1`,
 }
 ```
 
-`siteUrl` is only needed for a `--dir` crawl, and only to detect canonicals pointing at another host — a staging hostname leaking into production canonicals. A `--url` crawl infers it.
+`siteUrl` is what the site calls itself, which is not always where you are crawling it. It is what `canonical.offsite` compares against, so set it when checking a `--dir` build, and when crawling a local build or a preview deployment whose pages carry production canonicals. A plain crawl of production infers it.
 
 Every finding has a stable `code`. Set any code to `error`, `warn`, `info`, or `off`.
 

package/dist/cli.cjs

@@ -940,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) {
@@ -1382,7 +1451,11 @@ async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
   const agents = options.aiAgents ?? DEFAULT_AI_AGENTS;
   const timeout = options.timeout;
-  const site = { origin: base.origin, robotsTxt: null, llmsTxt: null };
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : base.origin,
+    robotsTxt: null,
+    llmsTxt: null
+  };
   const limit = options.limit ?? 200;
   const robots = await fetchText(new URL("/robots.txt", base).href, timeout);
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
@@ -1559,7 +1632,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");
@@ -1572,7 +1645,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.6.0");
+cli.version("0.8.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/cli.js

@@ -917,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) {
@@ -1359,7 +1428,11 @@ async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
   const agents = options.aiAgents ?? DEFAULT_AI_AGENTS;
   const timeout = options.timeout;
-  const site = { origin: base.origin, robotsTxt: null, llmsTxt: null };
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : base.origin,
+    robotsTxt: null,
+    llmsTxt: null
+  };
   const limit = options.limit ?? 200;
   const robots = await fetchText(new URL("/robots.txt", base).href, timeout);
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
@@ -1536,7 +1609,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");
@@ -1549,7 +1622,7 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
   }
 });
 cli.help();
-cli.version("0.6.0");
+cli.version("0.8.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/index.cjs

@@ -1185,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) {
@@ -1421,7 +1490,11 @@ async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
   const agents = options.aiAgents ?? DEFAULT_AI_AGENTS;
   const timeout = options.timeout;
-  const site = { origin: base.origin, robotsTxt: null, llmsTxt: null };
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : base.origin,
+    robotsTxt: null,
+    llmsTxt: null
+  };
   const limit = options.limit ?? 200;
   const robots = await fetchText(new URL("/robots.txt", base).href, timeout);
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);

package/dist/index.d.cts

@@ -94,8 +94,10 @@ interface Config {
     /** Minimum word count before a page is flagged as thin. */
     minWordCount?: number;
     /**
-     * The site's own origin, e.g. "https://example.com". Lets a --dir crawl detect
-     * canonicals pointing at another host; an origin crawl infers it.
+     * The site's own origin, e.g. "https://example.com". Used to detect canonicals
+     * pointing at another host. A --dir crawl has no other source for it, and an
+     * origin crawl of a local build or preview deployment needs it to override the
+     * URL being crawled, since those serve production canonicals.
      */
     siteUrl?: string;
 }
@@ -192,7 +194,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

@@ -94,8 +94,10 @@ interface Config {
     /** Minimum word count before a page is flagged as thin. */
     minWordCount?: number;
     /**
-     * The site's own origin, e.g. "https://example.com". Lets a --dir crawl detect
-     * canonicals pointing at another host; an origin crawl infers it.
+     * The site's own origin, e.g. "https://example.com". Used to detect canonicals
+     * pointing at another host. A --dir crawl has no other source for it, and an
+     * origin crawl of a local build or preview deployment needs it to override the
+     * URL being crawled, since those serve production canonicals.
      */
     siteUrl?: string;
 }
@@ -192,7 +194,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

@@ -1114,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) {
@@ -1350,7 +1419,11 @@ async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
   const agents = options.aiAgents ?? DEFAULT_AI_AGENTS;
   const timeout = options.timeout;
-  const site = { origin: base.origin, robotsTxt: null, llmsTxt: null };
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : base.origin,
+    robotsTxt: null,
+    llmsTxt: null
+  };
   const limit = options.limit ?? 200;
   const robots = await fetchText(new URL("/robots.txt", base).href, timeout);
   if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);

package/package.json

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