pagetrace 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ 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.11.0] - 2026-09-08
+
+### Added
+
+- `pagetrace links`, a command for the one question. It crawls once and reports
+  only broken internal links, exiting 1 if there are any. The rules are the ones
+  `audit` runs, filtered rather than reimplemented, so the two cannot disagree.
+
 ## [0.10.0] - 2026-09-08
 
 ### Added
@@ -330,6 +338,7 @@ 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.11.0]: https://github.com/shyamexe/pagetrace/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/shyamexe/pagetrace/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/shyamexe/pagetrace/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/shyamexe/pagetrace/compare/v0.8.1...v0.9.0

package/README.md

@@ -165,6 +165,15 @@ pagetrace update              # install it globally
 | `og.removed` / `hreflang.removed` | warn | Social or i18n tags dropped |
 | `title.changed` | info | Ordinary copy edit |
 
+Broken links have a command of their own, when that is the only question you have:
+
+```bash
+npx pagetrace links --url https://example.com
+npx pagetrace links --dir ./out --format json
+```
+
+It crawls once, runs the same rules as `audit`, and prints only the link findings — exit 1 if any, or `No broken links found — 42 pages checked.`
+
 Internal links are checked too. Only the broken ones are stored, so a site's navigation never lands in the lockfile: `link.broken` for a link that is already dead, `link.broken.added` for one this build broke. A `--dir` crawl is authoritative — the build directory is the whole site — while a crawl confirms each candidate with a real request first, because a sitemap routinely omits pages that are live. External links are deliberately not checked: a Cloudflare 403 and a rate limit both look like a dead page, and that is where link checkers earn their reputation for false positives.
 
 Redirects are recorded from the response itself, so they cost no extra requests. A redirect that only adds or drops a trailing slash is server configuration rather than drift and is not reported. `canonical.redirects` is only raised when the canonical's target was actually crawled, so a `--limit` run cannot invent it.

package/dist/cli.cjs

@@ -1958,6 +1958,53 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
+cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await build(flags, config);
+  const pages = Object.values(snapshot.pages);
+  if (pages.length === 0) {
+    console.error(
+      import_picocolors2.default.yellow(
+        "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
+      )
+    );
+    process.exitCode = EXIT_FAILURE;
+    return;
+  }
+  const platform = detectPlatform(
+    pages.map((p) => p.generator),
+    pages.flatMap((p) => Object.values(p.og))
+  );
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.code.startsWith("link.")).map((f) => withGuidance(f, platform));
+  const target = flags.url ?? flags.dir ?? "site";
+  if (findings.length === 0 && !flags.out) {
+    console.log(
+      import_picocolors2.default.green(
+        `No broken links found \u2014 ${pages.length} page${pages.length === 1 ? "" : "s"} checked.`
+      )
+    );
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target,
+    platform,
+    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) : formatAuditPretty(groups, meta, process.stdout.columns);
+  if (flags.out) {
+    await (0, import_promises2.writeFile)(flags.out, `${output}
+`, "utf8");
+    console.log(import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${groups.length} broken link${groups.length === 1 ? "" : "s"}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    process.exitCode = EXIT_FINDINGS;
+  }
+});
 cli.command("init", "Write a config file and take the first snapshot").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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const existing = await (0, import_promises2.readFile)(flags.config, "utf8").catch(() => null);
   if (existing === null) {
@@ -1981,11 +2028,11 @@ Commit both files, then run \`pagetrace check ${flags.dir ? `--dir ${flags.dir}`
 });
 cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
   const latest = await latestVersion("pagetrace");
-  if (!isNewer(latest, "0.10.0")) {
-    console.log(import_picocolors2.default.green(`pagetrace ${"0.10.0"} is the latest version.`));
+  if (!isNewer(latest, "0.11.0")) {
+    console.log(import_picocolors2.default.green(`pagetrace ${"0.11.0"} is the latest version.`));
     return;
   }
-  console.log(import_picocolors2.default.yellow(`Update available: ${"0.10.0"} \u2192 ${latest}`));
+  console.log(import_picocolors2.default.yellow(`Update available: ${"0.11.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -2003,7 +2050,7 @@ cli.command("update", "Check npm for a newer pagetrace and install it").option("
   console.log(import_picocolors2.default.green(`Updated to pagetrace ${latest}.`));
 });
 cli.help();
-cli.version("0.10.0");
+cli.version("0.11.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/cli.js

@@ -1935,6 +1935,53 @@ cli.command("audit", "Audit a site as it stands, with explanations and fixes").o
     process.exitCode = EXIT_FINDINGS;
   }
 });
+cli.command("links", "Find internal links that point at no page").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "error" }).action(async (flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await build(flags, config);
+  const pages = Object.values(snapshot.pages);
+  if (pages.length === 0) {
+    console.error(
+      pc2.yellow(
+        "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
+      )
+    );
+    process.exitCode = EXIT_FAILURE;
+    return;
+  }
+  const platform = detectPlatform(
+    pages.map((p) => p.generator),
+    pages.flatMap((p) => Object.values(p.og))
+  );
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.code.startsWith("link.")).map((f) => withGuidance(f, platform));
+  const target = flags.url ?? flags.dir ?? "site";
+  if (findings.length === 0 && !flags.out) {
+    console.log(
+      pc2.green(
+        `No broken links found \u2014 ${pages.length} page${pages.length === 1 ? "" : "s"} checked.`
+      )
+    );
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target,
+    platform,
+    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) : formatAuditPretty(groups, meta, process.stdout.columns);
+  if (flags.out) {
+    await writeFile(flags.out, `${output}
+`, "utf8");
+    console.log(pc2.green(`Wrote ${flags.out} \u2014 ${groups.length} broken link${groups.length === 1 ? "" : "s"}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    process.exitCode = EXIT_FINDINGS;
+  }
+});
 cli.command("init", "Write a config file and take the first snapshot").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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const existing = await readFile2(flags.config, "utf8").catch(() => null);
   if (existing === null) {
@@ -1958,11 +2005,11 @@ Commit both files, then run \`pagetrace check ${flags.dir ? `--dir ${flags.dir}`
 });
 cli.command("update", "Check npm for a newer pagetrace and install it").option("--check", "Only report whether an update exists").action(async (flags) => {
   const latest = await latestVersion("pagetrace");
-  if (!isNewer(latest, "0.10.0")) {
-    console.log(pc2.green(`pagetrace ${"0.10.0"} is the latest version.`));
+  if (!isNewer(latest, "0.11.0")) {
+    console.log(pc2.green(`pagetrace ${"0.11.0"} is the latest version.`));
     return;
   }
-  console.log(pc2.yellow(`Update available: ${"0.10.0"} \u2192 ${latest}`));
+  console.log(pc2.yellow(`Update available: ${"0.11.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -1980,7 +2027,7 @@ cli.command("update", "Check npm for a newer pagetrace and install it").option("
   console.log(pc2.green(`Updated to pagetrace ${latest}.`));
 });
 cli.help();
-cli.version("0.10.0");
+cli.version("0.11.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/package.json

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