pagetrace 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ 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.14.0] - 2026-09-08
+
+### Added
+
+- `--verify-all` also checks links to assets — PDFs, images, archives. They are
+  never crawled as pages, so they were skipped entirely: a link to a deleted
+  whitepaper reported nothing. A `--dir` run checks them against the filesystem;
+  a crawl spends a request each, which is why it is opt-in.
+
+### Changed
+
+- Link verification now runs in parallel at `--concurrency`, and the cap rose
+  from 100 to 1000 unique targets. Hitting the cap now says so on stderr rather
+  than silently under-reporting, which read as a clean site.
+
+## [0.13.0] - 2026-09-08
+
+### Added
+
+- `pagetrace page <url>` checks a single page: every link on it confirmed with a
+  real request, external ones included by default, plus that page's own rules.
+  A crawl trusts its route set and only verifies what is missing from it; with
+  one page there is no route set to trust, so everything is checked. Passing a
+  deep URL to `--url` had crawled the whole site from its origin and ignored the
+  path, which is not what it looked like it did.
+
 ## [0.12.0] - 2026-09-08
 
 ### Added
@@ -359,6 +385,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.14.0]: https://github.com/shyamexe/pagetrace/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/shyamexe/pagetrace/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/shyamexe/pagetrace/compare/v0.11.0...v0.12.0
 [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

package/README.md

@@ -19,6 +19,33 @@ npm install -D pagetrace
 
 Requires Node 20.19 or newer. No native modules, three small dependencies.
 
+## Commands
+
+| Command | Answers | Crawls | Exit 1 when |
+| --- | --- | --- | --- |
+| `init` | "get me set up" | once, to write the first lockfile | never |
+| `snapshot` | "record what the site looks like now" | whole site | never |
+| `check` | "what did this deploy change?" | whole site | findings at or above `--fail-on` (default `error`) |
+| `audit` | "what is wrong with this site?" | whole site | `--fail-on` (default `never`) |
+| `links` | "are any links dead?" | whole site, links only in the report | any broken link |
+| `page <url>` | "is this one page sound?" | that URL alone | `--fail-on` (default `error`) |
+| `update` | "am I on the latest pagetrace?" | nothing | never |
+
+Every crawling command takes `--dir <build>` or `--url <origin>`, plus:
+
+| Flag | Default | Effect |
+| --- | --- | --- |
+| `--limit <n>` | 200 | Stop after this many pages |
+| `--concurrency <n>` | 5 | Parallel requests |
+| `--external` | off (on for `page`) | Also check links that leave the site |
+| `--verify-all` | off | Also check links to assets — PDFs, images, archives |
+| `--ignore-robots` | off | Crawl paths `robots.txt` disallows |
+| `--fail-on <severity>` | varies | `error`, `warn`, `info` or `never` |
+| `--format <format>` | `pretty` | `pretty`, `json`, `markdown`; `github` and `sarif` on `check` |
+| `--config <file>` | `pagetrace.config.json` | Config file |
+
+Exit codes are the same everywhere: `0` clean, `1` findings at or above `--fail-on`, `2` the run itself failed — bad flags, an unreadable build, an unreachable origin. CI can tell "the site regressed" from "the tool broke".
+
 ## Use
 
 Set up a config file and the first baseline in one step:
@@ -56,7 +83,7 @@ npx pagetrace check --dir ./out
 5 error, 9 warning, 2 info
 ```
 
-Exit codes are `0` for clean, `1` for findings at or above `--fail-on`, and `2` when the run itself failed — bad flags, an unreadable build directory, an unreachable origin. CI can tell "the site regressed" from "the tool broke". `--fail-on` takes `error` (the default), `warn` or `info`, and rejects anything else rather than quietly letting the build pass.
+`--fail-on` rejects an unrecognised value rather than quietly letting the build pass.
 
 Note that `check` runs the absolute rules as well as the diff, so it can fail on a problem your build did not introduce. Use `--no-audit` for a pure regression gate.
 
@@ -166,6 +193,14 @@ pagetrace update              # install it globally
 | `og.removed` / `hreflang.removed` | warn | Social or i18n tags dropped |
 | `title.changed` | info | Ordinary copy edit |
 
+One page, checked on its own:
+
+```bash
+npx pagetrace page https://example.com/blog/my-post
+```
+
+No sitemap, no crawl: it fetches that URL and confirms every link on it with a real request, external links included by default (`--no-external` to skip them). Site-wide rules are left to `audit` — a single-page check never looks at robots.txt, so it does not get to say whether one exists.
+
 Broken links have a command of their own, when that is the only question you have:
 
 ```bash
@@ -185,7 +220,7 @@ Only `404` and `410` count as dead. A `403` from a bot wall, a `429`, a timeout
 
 Think twice before putting `--external` in `check`. A third party's bad afternoon becomes a diff in your repository and a red build you cannot fix.
 
-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 checked only with `--external`, and only a 404 or 410 counts.
+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 checked only with `--external`, and only a 404 or 410 counts. Links to assets — PDFs, images, archives — are skipped unless `--verify-all`, since each one costs a request on a crawl (a `--dir` run checks them against the filesystem instead).
 
 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

@@ -1698,12 +1698,20 @@ async function snapshotFromDir(dir, config = {}) {
   const llms = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
   const origin = site.origin ?? "https://pagetrace.invalid";
-  await resolveBrokenLinks(pages, links, origin);
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: config.verifyAll,
+    // The HTML route set is authoritative here, so a missing page is simply
+    // broken. An asset is a file this crawl never walked, so it gets a stat.
+    verify: config.verifyAll ? async (target) => ASSET_PATH.test(target) ? !await (0, import_promises.access)((0, import_node_path.join)(dir, target)).then(
+      () => true,
+      () => false
+    ) : true : void 0
+  });
   if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
-function linkTarget(href, from, origin) {
+function linkTarget(href, from, origin, includeAssets = false) {
   let url;
   try {
     url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
@@ -1711,27 +1719,39 @@ function linkTarget(href, from, origin) {
     return null;
   }
   if (url.origin !== origin) return null;
-  if (ASSET_PATH.test(url.pathname)) return null;
-  return routeFromUrl(url.href);
+  if (!includeAssets && ASSET_PATH.test(url.pathname)) return null;
+  return ASSET_PATH.test(url.pathname) ? url.pathname : routeFromUrl(url.href);
 }
-var MAX_LINK_CHECKS = 100;
-async function resolveBrokenLinks(pages, links, origin, verify) {
+var MAX_LINK_CHECKS = 1e3;
+async function resolveBrokenLinks(pages, links, origin, options = {}) {
+  const { includeAssets = false, verify, concurrency = 5 } = options;
   const known = new Set(Object.keys(pages));
   const candidates = /* @__PURE__ */ new Map();
   for (const [route, hrefs] of Object.entries(links)) {
     const missing = [
       ...new Set(
-        hrefs.map((href) => linkTarget(href, route, origin)).filter((target) => target !== null && !known.has(target))
+        hrefs.map((href) => linkTarget(href, route, origin, includeAssets)).filter((target) => target !== null && !known.has(target))
       )
     ];
     if (missing.length > 0) candidates.set(route, missing);
   }
   const broken = /* @__PURE__ */ new Set();
   if (verify) {
-    const targets = [...new Set([...candidates.values()].flat())].slice(0, MAX_LINK_CHECKS);
-    for (const target of targets) {
-      if (await verify(target)) broken.add(target);
+    const unique = [...new Set([...candidates.values()].flat())];
+    const queue = unique.slice(0, MAX_LINK_CHECKS);
+    if (unique.length > queue.length) {
+      console.error(
+        `pagetrace: ${unique.length} link targets to confirm, checking the first ${MAX_LINK_CHECKS}.`
+      );
     }
+    await Promise.all(
+      Array.from({ length: Math.min(Math.max(1, concurrency), queue.length) }, async () => {
+        while (queue.length > 0) {
+          const target = queue.shift();
+          if (await verify(target)) broken.add(target);
+        }
+      })
+    );
   }
   for (const [route, missing] of candidates) {
     const confirmed = verify ? missing.filter((target) => broken.has(target)) : missing;
@@ -1795,6 +1815,39 @@ async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs)
     if (found.length > 0) pages[route].deadExternal = found;
   }
 }
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: options.verifyAll,
+    concurrency: options.concurrency,
+    verify: async (candidate) => {
+      try {
+        return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+      } catch {
+        return false;
+      }
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1876,11 +1929,15 @@ async function snapshotFromOrigin(origin, options = {}) {
       }
     })
   );
-  await resolveBrokenLinks(pages, links, base.origin, async (route) => {
-    try {
-      return await fetchDoc(new URL(route, base).href, timeout) === null;
-    } catch {
-      return false;
+  await resolveBrokenLinks(pages, links, base.origin, {
+    includeAssets: options.verifyAll,
+    concurrency,
+    verify: async (route) => {
+      try {
+        return await fetchDoc(new URL(route, base).href, timeout) === null;
+      } catch {
+        return false;
+      }
     }
   });
   if (options.checkExternal) {
@@ -1939,14 +1996,16 @@ async function loadConfig(path = DEFAULT_CONFIG) {
 }
 async function build(flags, config) {
   const checkExternal = flags.external ?? config.checkExternal;
-  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal });
+  const verifyAll = flags.verifyAll ?? config.verifyAll;
+  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal, verifyAll });
   if (flags.url)
     return snapshotFromOrigin(flags.url, {
       ...config,
       limit: flags.limit,
       concurrency: flags.concurrency,
       ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots,
-      checkExternal
+      checkExternal,
+      verifyAll
     });
   throw new Error("Provide a source: --dir <build directory> or --url <origin>.");
 }
@@ -1965,7 +2024,7 @@ function render(findings, format) {
   }
 }
 var cli = (0, import_cac.cac)("pagetrace");
-cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
   const written = await writeLockfile(flags.out, snapshot);
@@ -1974,7 +2033,7 @@ 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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { 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) => {
+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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { 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);
@@ -2004,7 +2063,7 @@ Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
+cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -2044,7 +2103,44 @@ 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("--external", "Also check links that leave the site").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) => {
+cli.command("page <url>", "Check one page: every link on it, and its own surface").option("--external", "Check links that leave the site", { default: true }).option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--concurrency <n>", "Parallel requests", { default: 5 }).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 (url, flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await snapshotFromPage(url, {
+    ...config,
+    concurrency: flags.concurrency,
+    checkExternal: flags.external,
+    verifyAll: flags.verifyAll ?? config.verifyAll
+  });
+  const [page] = Object.values(snapshot.pages);
+  const platform = detectPlatform([page.generator], Object.values(page.og));
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.route !== null).map((f) => withGuidance(f, platform));
+  if (findings.length === 0 && !flags.out) {
+    const checked = (page.brokenLinks?.length ?? 0) + (page.deadExternal?.length ?? 0);
+    console.log(import_picocolors2.default.green(`${url} looks sound \u2014 no findings, no dead links.`));
+    if (checked > 0) console.log(import_picocolors2.default.dim("(unreachable links were treated as unknown, not dead)"));
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target: url,
+    platform,
+    pageCount: 1,
+    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}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    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("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").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);
@@ -2091,7 +2187,7 @@ cli.command("links", "Find internal links that point at no page").option("--url
     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("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+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("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").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) {
     const config = flags.url ? { siteUrl: new URL(flags.url).origin } : {};
@@ -2114,11 +2210,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.12.0")) {
-    console.log(import_picocolors2.default.green(`pagetrace ${"0.12.0"} is the latest version.`));
+  if (!isNewer(latest, "0.14.0")) {
+    console.log(import_picocolors2.default.green(`pagetrace ${"0.14.0"} is the latest version.`));
     return;
   }
-  console.log(import_picocolors2.default.yellow(`Update available: ${"0.12.0"} \u2192 ${latest}`));
+  console.log(import_picocolors2.default.yellow(`Update available: ${"0.14.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -2136,7 +2232,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.12.0");
+cli.version("0.14.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/cli.js

@@ -1304,7 +1304,7 @@ ${cards || "<p>No issues found.</p>"}
 
 // src/snapshot.ts
 import { execFile } from "child_process";
-import { readdir, readFile } from "fs/promises";
+import { access, readdir, readFile } from "fs/promises";
 import { join, relative, sep } from "path";
 import { promisify } from "util";
 
@@ -1675,12 +1675,20 @@ async function snapshotFromDir(dir, config = {}) {
   const llms = await readFile(join(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
   const origin = site.origin ?? "https://pagetrace.invalid";
-  await resolveBrokenLinks(pages, links, origin);
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: config.verifyAll,
+    // The HTML route set is authoritative here, so a missing page is simply
+    // broken. An asset is a file this crawl never walked, so it gets a stat.
+    verify: config.verifyAll ? async (target) => ASSET_PATH.test(target) ? !await access(join(dir, target)).then(
+      () => true,
+      () => false
+    ) : true : void 0
+  });
   if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
-function linkTarget(href, from, origin) {
+function linkTarget(href, from, origin, includeAssets = false) {
   let url;
   try {
     url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
@@ -1688,27 +1696,39 @@ function linkTarget(href, from, origin) {
     return null;
   }
   if (url.origin !== origin) return null;
-  if (ASSET_PATH.test(url.pathname)) return null;
-  return routeFromUrl(url.href);
+  if (!includeAssets && ASSET_PATH.test(url.pathname)) return null;
+  return ASSET_PATH.test(url.pathname) ? url.pathname : routeFromUrl(url.href);
 }
-var MAX_LINK_CHECKS = 100;
-async function resolveBrokenLinks(pages, links, origin, verify) {
+var MAX_LINK_CHECKS = 1e3;
+async function resolveBrokenLinks(pages, links, origin, options = {}) {
+  const { includeAssets = false, verify, concurrency = 5 } = options;
   const known = new Set(Object.keys(pages));
   const candidates = /* @__PURE__ */ new Map();
   for (const [route, hrefs] of Object.entries(links)) {
     const missing = [
       ...new Set(
-        hrefs.map((href) => linkTarget(href, route, origin)).filter((target) => target !== null && !known.has(target))
+        hrefs.map((href) => linkTarget(href, route, origin, includeAssets)).filter((target) => target !== null && !known.has(target))
       )
     ];
     if (missing.length > 0) candidates.set(route, missing);
   }
   const broken = /* @__PURE__ */ new Set();
   if (verify) {
-    const targets = [...new Set([...candidates.values()].flat())].slice(0, MAX_LINK_CHECKS);
-    for (const target of targets) {
-      if (await verify(target)) broken.add(target);
+    const unique = [...new Set([...candidates.values()].flat())];
+    const queue = unique.slice(0, MAX_LINK_CHECKS);
+    if (unique.length > queue.length) {
+      console.error(
+        `pagetrace: ${unique.length} link targets to confirm, checking the first ${MAX_LINK_CHECKS}.`
+      );
     }
+    await Promise.all(
+      Array.from({ length: Math.min(Math.max(1, concurrency), queue.length) }, async () => {
+        while (queue.length > 0) {
+          const target = queue.shift();
+          if (await verify(target)) broken.add(target);
+        }
+      })
+    );
   }
   for (const [route, missing] of candidates) {
     const confirmed = verify ? missing.filter((target) => broken.has(target)) : missing;
@@ -1772,6 +1792,39 @@ async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs)
     if (found.length > 0) pages[route].deadExternal = found;
   }
 }
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: options.verifyAll,
+    concurrency: options.concurrency,
+    verify: async (candidate) => {
+      try {
+        return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+      } catch {
+        return false;
+      }
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1853,11 +1906,15 @@ async function snapshotFromOrigin(origin, options = {}) {
       }
     })
   );
-  await resolveBrokenLinks(pages, links, base.origin, async (route) => {
-    try {
-      return await fetchDoc(new URL(route, base).href, timeout) === null;
-    } catch {
-      return false;
+  await resolveBrokenLinks(pages, links, base.origin, {
+    includeAssets: options.verifyAll,
+    concurrency,
+    verify: async (route) => {
+      try {
+        return await fetchDoc(new URL(route, base).href, timeout) === null;
+      } catch {
+        return false;
+      }
     }
   });
   if (options.checkExternal) {
@@ -1916,14 +1973,16 @@ async function loadConfig(path = DEFAULT_CONFIG) {
 }
 async function build(flags, config) {
   const checkExternal = flags.external ?? config.checkExternal;
-  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal });
+  const verifyAll = flags.verifyAll ?? config.verifyAll;
+  if (flags.dir) return snapshotFromDir(flags.dir, { ...config, checkExternal, verifyAll });
   if (flags.url)
     return snapshotFromOrigin(flags.url, {
       ...config,
       limit: flags.limit,
       concurrency: flags.concurrency,
       ignoreRobots: flags.ignoreRobots ?? config.ignoreRobots,
-      checkExternal
+      checkExternal,
+      verifyAll
     });
   throw new Error("Provide a source: --dir <build directory> or --url <origin>.");
 }
@@ -1942,7 +2001,7 @@ function render(findings, format) {
   }
 }
 var cli = cac("pagetrace");
-cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
   const written = await writeLockfile(flags.out, snapshot);
@@ -1951,7 +2010,7 @@ 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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { 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) => {
+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("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github | sarif", { 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);
@@ -1981,7 +2040,7 @@ Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`
     process.exitCode = EXIT_FINDINGS;
   }
 });
-cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
+cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--ignore-robots", "Crawl paths that robots.txt disallows").option("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
   const failOn = parseFailOn(flags.failOn, true);
   const config = await loadConfig(flags.config);
   const snapshot = await build(flags, config);
@@ -2021,7 +2080,44 @@ 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("--external", "Also check links that leave the site").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) => {
+cli.command("page <url>", "Check one page: every link on it, and its own surface").option("--external", "Check links that leave the site", { default: true }).option("--verify-all", "Also check links to assets (PDFs, images, archives)").option("--concurrency <n>", "Parallel requests", { default: 5 }).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 (url, flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await snapshotFromPage(url, {
+    ...config,
+    concurrency: flags.concurrency,
+    checkExternal: flags.external,
+    verifyAll: flags.verifyAll ?? config.verifyAll
+  });
+  const [page] = Object.values(snapshot.pages);
+  const platform = detectPlatform([page.generator], Object.values(page.og));
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).filter((f) => f.route !== null).map((f) => withGuidance(f, platform));
+  if (findings.length === 0 && !flags.out) {
+    const checked = (page.brokenLinks?.length ?? 0) + (page.deadExternal?.length ?? 0);
+    console.log(pc2.green(`${url} looks sound \u2014 no findings, no dead links.`));
+    if (checked > 0) console.log(pc2.dim("(unreachable links were treated as unknown, not dead)"));
+    return;
+  }
+  const groups = aggregate(findings);
+  const meta = {
+    target: url,
+    platform,
+    pageCount: 1,
+    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}.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    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("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").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);
@@ -2068,7 +2164,7 @@ cli.command("links", "Find internal links that point at no page").option("--url
     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("--external", "Also check links that leave the site").option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+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("--external", "Also check links that leave the site").option("--verify-all", "Also check links to assets (PDFs, images, archives)").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) {
     const config = flags.url ? { siteUrl: new URL(flags.url).origin } : {};
@@ -2091,11 +2187,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.12.0")) {
-    console.log(pc2.green(`pagetrace ${"0.12.0"} is the latest version.`));
+  if (!isNewer(latest, "0.14.0")) {
+    console.log(pc2.green(`pagetrace ${"0.14.0"} is the latest version.`));
     return;
   }
-  console.log(pc2.yellow(`Update available: ${"0.12.0"} \u2192 ${latest}`));
+  console.log(pc2.yellow(`Update available: ${"0.14.0"} \u2192 ${latest}`));
   if (flags.check) return;
   if (process.argv[1]?.startsWith(process.cwd())) {
     console.log(
@@ -2113,7 +2209,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.12.0");
+cli.version("0.14.0");
 async function main() {
   try {
     cli.parse(process.argv, { run: false });

package/dist/index.cjs

@@ -67,6 +67,7 @@ __export(src_exports, {
   snapshotFromDir: () => snapshotFromDir,
   snapshotFromGitRef: () => snapshotFromGitRef,
   snapshotFromOrigin: () => snapshotFromOrigin,
+  snapshotFromPage: () => snapshotFromPage,
   summarize: () => summarize,
   withGuidance: () => withGuidance
 });
@@ -1739,12 +1740,20 @@ async function snapshotFromDir(dir, config = {}) {
   const llms = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
   const origin = site.origin ?? "https://pagetrace.invalid";
-  await resolveBrokenLinks(pages, links, origin);
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: config.verifyAll,
+    // The HTML route set is authoritative here, so a missing page is simply
+    // broken. An asset is a file this crawl never walked, so it gets a stat.
+    verify: config.verifyAll ? async (target) => ASSET_PATH.test(target) ? !await (0, import_promises.access)((0, import_node_path.join)(dir, target)).then(
+      () => true,
+      () => false
+    ) : true : void 0
+  });
   if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
-function linkTarget(href, from, origin) {
+function linkTarget(href, from, origin, includeAssets = false) {
   let url;
   try {
     url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
@@ -1752,27 +1761,39 @@ function linkTarget(href, from, origin) {
     return null;
   }
   if (url.origin !== origin) return null;
-  if (ASSET_PATH.test(url.pathname)) return null;
-  return routeFromUrl(url.href);
+  if (!includeAssets && ASSET_PATH.test(url.pathname)) return null;
+  return ASSET_PATH.test(url.pathname) ? url.pathname : routeFromUrl(url.href);
 }
-var MAX_LINK_CHECKS = 100;
-async function resolveBrokenLinks(pages, links, origin, verify) {
+var MAX_LINK_CHECKS = 1e3;
+async function resolveBrokenLinks(pages, links, origin, options = {}) {
+  const { includeAssets = false, verify, concurrency = 5 } = options;
   const known = new Set(Object.keys(pages));
   const candidates = /* @__PURE__ */ new Map();
   for (const [route, hrefs] of Object.entries(links)) {
     const missing = [
       ...new Set(
-        hrefs.map((href) => linkTarget(href, route, origin)).filter((target) => target !== null && !known.has(target))
+        hrefs.map((href) => linkTarget(href, route, origin, includeAssets)).filter((target) => target !== null && !known.has(target))
       )
     ];
     if (missing.length > 0) candidates.set(route, missing);
   }
   const broken = /* @__PURE__ */ new Set();
   if (verify) {
-    const targets = [...new Set([...candidates.values()].flat())].slice(0, MAX_LINK_CHECKS);
-    for (const target of targets) {
-      if (await verify(target)) broken.add(target);
+    const unique = [...new Set([...candidates.values()].flat())];
+    const queue = unique.slice(0, MAX_LINK_CHECKS);
+    if (unique.length > queue.length) {
+      console.error(
+        `pagetrace: ${unique.length} link targets to confirm, checking the first ${MAX_LINK_CHECKS}.`
+      );
     }
+    await Promise.all(
+      Array.from({ length: Math.min(Math.max(1, concurrency), queue.length) }, async () => {
+        while (queue.length > 0) {
+          const target = queue.shift();
+          if (await verify(target)) broken.add(target);
+        }
+      })
+    );
   }
   for (const [route, missing] of candidates) {
     const confirmed = verify ? missing.filter((target) => broken.has(target)) : missing;
@@ -1836,6 +1857,39 @@ async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs)
     if (found.length > 0) pages[route].deadExternal = found;
   }
 }
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: options.verifyAll,
+    concurrency: options.concurrency,
+    verify: async (candidate) => {
+      try {
+        return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+      } catch {
+        return false;
+      }
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1917,11 +1971,15 @@ async function snapshotFromOrigin(origin, options = {}) {
       }
     })
   );
-  await resolveBrokenLinks(pages, links, base.origin, async (route) => {
-    try {
-      return await fetchDoc(new URL(route, base).href, timeout) === null;
-    } catch {
-      return false;
+  await resolveBrokenLinks(pages, links, base.origin, {
+    includeAssets: options.verifyAll,
+    concurrency,
+    verify: async (route) => {
+      try {
+        return await fetchDoc(new URL(route, base).href, timeout) === null;
+      } catch {
+        return false;
+      }
     }
   });
   if (options.checkExternal) {
@@ -1968,6 +2026,7 @@ async function snapshotFromOrigin(origin, options = {}) {
   snapshotFromDir,
   snapshotFromGitRef,
   snapshotFromOrigin,
+  snapshotFromPage,
   summarize,
   withGuidance
 });

package/dist/index.d.cts

@@ -151,6 +151,11 @@ interface Config {
      * third party's bad afternoon into a diff in your repository.
      */
     checkExternal?: boolean;
+    /**
+     * Also check links to assets — PDFs, images, archives. They are never crawled
+     * as pages, so each one costs a request (or a filesystem check for --dir).
+     */
+    verifyAll?: boolean;
 }
 
 /**
@@ -317,6 +322,14 @@ declare function sameSurface(a: Snapshot, b: Snapshot): boolean;
 declare function shouldIgnore(route: string, patterns?: string[]): boolean;
 /** Build a snapshot from a directory of pre-rendered HTML (next export, dist, out). */
 declare function snapshotFromDir(dir: string, config?: Config): Promise<Snapshot>;
+/**
+ * One page, checked properly. No sitemap, no route discovery: the snapshot
+ * holds a single page, so every link on it is a candidate and every candidate
+ * is confirmed with a real request. That is the opposite trade from a crawl,
+ * and the right one here — one page's worth of links is a bounded cost, and
+ * "is this page's linking sound" is a question a crawl answers slowly.
+ */
+declare function snapshotFromPage(pageUrl: string, options?: CrawlOptions): Promise<Snapshot>;
 interface CrawlOptions extends Config {
     /** Cap the number of pages fetched. */
     limit?: number;
@@ -328,4 +341,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, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, 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, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, snapshotFromPage, summarize, withGuidance };

package/dist/index.d.ts

@@ -151,6 +151,11 @@ interface Config {
      * third party's bad afternoon into a diff in your repository.
      */
     checkExternal?: boolean;
+    /**
+     * Also check links to assets — PDFs, images, archives. They are never crawled
+     * as pages, so each one costs a request (or a filesystem check for --dir).
+     */
+    verifyAll?: boolean;
 }
 
 /**
@@ -317,6 +322,14 @@ declare function sameSurface(a: Snapshot, b: Snapshot): boolean;
 declare function shouldIgnore(route: string, patterns?: string[]): boolean;
 /** Build a snapshot from a directory of pre-rendered HTML (next export, dist, out). */
 declare function snapshotFromDir(dir: string, config?: Config): Promise<Snapshot>;
+/**
+ * One page, checked properly. No sitemap, no route discovery: the snapshot
+ * holds a single page, so every link on it is a candidate and every candidate
+ * is confirmed with a real request. That is the opposite trade from a crawl,
+ * and the right one here — one page's worth of links is a bounded cost, and
+ * "is this page's linking sound" is a question a crawl answers slowly.
+ */
+declare function snapshotFromPage(pageUrl: string, options?: CrawlOptions): Promise<Snapshot>;
 interface CrawlOptions extends Config {
     /** Cap the number of pages fetched. */
     limit?: number;
@@ -328,4 +341,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, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, 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, extractLinks, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, formatSarif, isCrawlable, routeFromFilePath, routeFromUrl, sameSurface, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromGitRef, snapshotFromOrigin, snapshotFromPage, summarize, withGuidance };

package/dist/index.js

@@ -1535,7 +1535,7 @@ ${cards || "<p>No issues found.</p>"}
 
 // src/snapshot.ts
 import { execFile } from "child_process";
-import { readdir, readFile } from "fs/promises";
+import { access, readdir, readFile } from "fs/promises";
 import { join, relative, sep } from "path";
 import { promisify } from "util";
 function routeFromFilePath(root, filePath) {
@@ -1665,12 +1665,20 @@ async function snapshotFromDir(dir, config = {}) {
   const llms = await readFile(join(dir, "llms.txt"), "utf8").catch(() => null);
   if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
   const origin = site.origin ?? "https://pagetrace.invalid";
-  await resolveBrokenLinks(pages, links, origin);
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: config.verifyAll,
+    // The HTML route set is authoritative here, so a missing page is simply
+    // broken. An asset is a file this crawl never walked, so it gets a stat.
+    verify: config.verifyAll ? async (target) => ASSET_PATH.test(target) ? !await access(join(dir, target)).then(
+      () => true,
+      () => false
+    ) : true : void 0
+  });
   if (config.checkExternal) await resolveDeadExternal(pages, links, origin, 5);
   return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
 }
 var ASSET_PATH = /\.(?!html?$)[a-z0-9]+$/i;
-function linkTarget(href, from, origin) {
+function linkTarget(href, from, origin, includeAssets = false) {
   let url;
   try {
     url = new URL(href, `${origin}${from === "/" ? "" : from}/`);
@@ -1678,27 +1686,39 @@ function linkTarget(href, from, origin) {
     return null;
   }
   if (url.origin !== origin) return null;
-  if (ASSET_PATH.test(url.pathname)) return null;
-  return routeFromUrl(url.href);
+  if (!includeAssets && ASSET_PATH.test(url.pathname)) return null;
+  return ASSET_PATH.test(url.pathname) ? url.pathname : routeFromUrl(url.href);
 }
-var MAX_LINK_CHECKS = 100;
-async function resolveBrokenLinks(pages, links, origin, verify) {
+var MAX_LINK_CHECKS = 1e3;
+async function resolveBrokenLinks(pages, links, origin, options = {}) {
+  const { includeAssets = false, verify, concurrency = 5 } = options;
   const known = new Set(Object.keys(pages));
   const candidates = /* @__PURE__ */ new Map();
   for (const [route, hrefs] of Object.entries(links)) {
     const missing = [
       ...new Set(
-        hrefs.map((href) => linkTarget(href, route, origin)).filter((target) => target !== null && !known.has(target))
+        hrefs.map((href) => linkTarget(href, route, origin, includeAssets)).filter((target) => target !== null && !known.has(target))
       )
     ];
     if (missing.length > 0) candidates.set(route, missing);
   }
   const broken = /* @__PURE__ */ new Set();
   if (verify) {
-    const targets = [...new Set([...candidates.values()].flat())].slice(0, MAX_LINK_CHECKS);
-    for (const target of targets) {
-      if (await verify(target)) broken.add(target);
+    const unique = [...new Set([...candidates.values()].flat())];
+    const queue = unique.slice(0, MAX_LINK_CHECKS);
+    if (unique.length > queue.length) {
+      console.error(
+        `pagetrace: ${unique.length} link targets to confirm, checking the first ${MAX_LINK_CHECKS}.`
+      );
     }
+    await Promise.all(
+      Array.from({ length: Math.min(Math.max(1, concurrency), queue.length) }, async () => {
+        while (queue.length > 0) {
+          const target = queue.shift();
+          if (await verify(target)) broken.add(target);
+        }
+      })
+    );
   }
   for (const [route, missing] of candidates) {
     const confirmed = verify ? missing.filter((target) => broken.has(target)) : missing;
@@ -1762,6 +1782,39 @@ async function resolveDeadExternal(pages, links, origin, concurrency, timeoutMs)
     if (found.length > 0) pages[route].deadExternal = found;
   }
 }
+async function snapshotFromPage(pageUrl, options = {}) {
+  const target = new URL(pageUrl);
+  const site = {
+    origin: options.siteUrl ? new URL(options.siteUrl).origin : target.origin,
+    robotsTxt: null,
+    llmsTxt: null,
+    sitemap: null
+  };
+  const doc = await fetchDoc(target.href, options.timeout);
+  if (doc === null) throw new Error(`${target.href} answered 404 \u2014 nothing to check.`);
+  const route = routeFromUrl(target.href);
+  const page = extractPage(doc.text, route);
+  const landed = !doc.url ? route : originOf2(doc.url) === target.origin ? routeFromUrl(doc.url) : doc.url;
+  page.redirectsTo = landed === route ? null : landed;
+  const pages = { [route]: page };
+  const links = { [route]: extractLinks(doc.text) };
+  const origin = site.origin ?? target.origin;
+  await resolveBrokenLinks(pages, links, origin, {
+    includeAssets: options.verifyAll,
+    concurrency: options.concurrency,
+    verify: async (candidate) => {
+      try {
+        return await fetchDoc(new URL(candidate, target.origin).href, options.timeout) === null;
+      } catch {
+        return false;
+      }
+    }
+  });
+  if (options.checkExternal) {
+    await resolveDeadExternal(pages, links, origin, Math.max(1, options.concurrency ?? 5), options.timeout);
+  }
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
 var MAX_NESTED_SITEMAPS = 50;
 async function snapshotFromOrigin(origin, options = {}) {
   const base = new URL(origin);
@@ -1843,11 +1896,15 @@ async function snapshotFromOrigin(origin, options = {}) {
       }
     })
   );
-  await resolveBrokenLinks(pages, links, base.origin, async (route) => {
-    try {
-      return await fetchDoc(new URL(route, base).href, timeout) === null;
-    } catch {
-      return false;
+  await resolveBrokenLinks(pages, links, base.origin, {
+    includeAssets: options.verifyAll,
+    concurrency,
+    verify: async (route) => {
+      try {
+        return await fetchDoc(new URL(route, base).href, timeout) === null;
+      } catch {
+        return false;
+      }
     }
   });
   if (options.checkExternal) {
@@ -1893,6 +1950,7 @@ export {
   snapshotFromDir,
   snapshotFromGitRef,
   snapshotFromOrigin,
+  snapshotFromPage,
   summarize,
   withGuidance
 };

package/package.json

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