framewatch-mcp-server 0.1.1 → 0.2.0

package/dist/utils/link-rules.d.ts

@@ -0,0 +1,100 @@
+import type { CheckOutcome } from "../engine/links.js";
+/**
+ * What counts as a broken link.
+ *
+ * Everything here is pure: it takes an href and a base, or the outcome of one
+ * HTTP check, and returns a verdict. Nothing in this file opens a browser or a
+ * socket, which is the point — "is this href even a request?", "did that chain
+ * of redirects end somewhere real?" and "is a 403 a broken link?" are all
+ * judgements with edge cases, and judgements need unit tests that run in
+ * milliseconds.
+ *
+ * The bias throughout is against false alarms. A report that calls a working
+ * link broken is worse than one that says nothing: it sends somebody to look
+ * at a page that is fine, and the next real finding gets ignored. So a status
+ * that means "I would not answer that" is separated from one that means "there
+ * is nothing here", and anything unrecognised is quoted rather than judged.
+ */
+/**
+ * What kind of thing an href is.
+ *
+ * Only `http` is a request. `same_page` is answered by the DOM, the scheme
+ * kinds are handed to something that is not a browser, and `malformed` never
+ * leaves the page at all.
+ */
+export type HrefKind = "http" | "same_page" | "empty" | "mailto" | "tel" | "javascript" | "data" | "scheme" | "malformed";
+export interface ClassifiedHref {
+    kind: HrefKind;
+    /** The absolute URL, for `http` and `same_page`. */
+    resolved?: string;
+    /** The `#…` part, decoded and without its hash, when there is one. */
+    fragment?: string;
+    /** The scheme, for `scheme` — `ftp`, `chrome-extension`, whatever the page used. */
+    scheme?: string;
+    /** Why this one cannot be checked, or is suspect. */
+    reason?: string;
+}
+/**
+ * Work out what an href points at, resolved against the page it was found on.
+ *
+ * Order matters. An empty href and a bare `#` both resolve to the current
+ * document, so they are recognised from the raw text before the URL parser
+ * gets a chance to turn them into the page's own address and hide what the
+ * author actually wrote — and `<a href="#">` is the single most common dead
+ * link there is.
+ */
+export declare function classifyHref(rawHref: string, base: string): ClassifiedHref;
+/**
+ * The identity of a request.
+ *
+ * The fragment is dropped: it never reaches the server, so `/help#returns` and
+ * `/help#shipping` are one request and must not be checked twice. Everything
+ * else is kept, including the trailing slash — `/a` and `/a/` are different
+ * URLs and routinely redirect differently, so collapsing them would hide a
+ * redirect the tool exists to report.
+ */
+export declare function dedupeKey(url: string): string;
+/** Same scheme, host and port — the only definition a crawl can safely act on. */
+export declare function isInternal(url: string, origin: string): boolean;
+/**
+ * The two fragments every browser resolves without an element to scroll to:
+ * an empty one (the top of the document, which is what `href="#"` means) and
+ * `#top`, which HTML defines as the same thing.
+ */
+export declare function isAlwaysValidFragment(fragment: string): boolean;
+/** Where a checked link ended up. */
+export type LinkCategory = "ok" | "redirect" | "broken" | "blocked" | "timeout" | "error";
+export interface LinkVerdict {
+    category: LinkCategory;
+    /** What happened, in one phrase: "404 Not Found", "redirected to … (2 hops)". */
+    detail: string;
+    /** What to do about it. Only where there is something to do. */
+    fix?: string;
+    /** Redirects followed. */
+    hops: number;
+    /** Where the chain actually ended, when that is not where it started. */
+    final_url?: string;
+}
+/**
+ * Decide what one check means.
+ *
+ * The order is the order the failures shadow each other: a loop makes the
+ * final status meaningless, a chain that ran out of hops never got one, a
+ * transport error means there is no status at all, and only then is the status
+ * itself worth reading.
+ */
+export declare function judgeCheck(outcome: CheckOutcome): LinkVerdict;
+/**
+ * Turn a transport failure into something a reader can act on.
+ *
+ * These are the five that a link check actually hits. Anything else is quoted
+ * verbatim rather than guessed at — an error nobody predicted is still useful,
+ * and a wrong paraphrase of it is not.
+ */
+export declare function classifyFailure(message: string): {
+    category: LinkCategory;
+    detail: string;
+    fix?: string;
+};
+/** The registered name of a status code, or "" for the ones nobody standardised. */
+export declare function statusText(status: number): string;

package/dist/utils/link-rules.js

@@ -0,0 +1,284 @@
+import { STATUS_CODES } from "node:http";
+import { MAX_LINK_REDIRECTS } from "../constants.js";
+/**
+ * Work out what an href points at, resolved against the page it was found on.
+ *
+ * Order matters. An empty href and a bare `#` both resolve to the current
+ * document, so they are recognised from the raw text before the URL parser
+ * gets a chance to turn them into the page's own address and hide what the
+ * author actually wrote — and `<a href="#">` is the single most common dead
+ * link there is.
+ */
+export function classifyHref(rawHref, base) {
+    const href = String(rawHref ?? "").trim();
+    // Per RFC 3986 an empty reference is the current document. Browsers reload
+    // the page; it is almost never what the author meant.
+    if (href === "") {
+        return { kind: "empty", reason: "an empty href reloads the current page" };
+    }
+    // A fragment-only reference never leaves the document, whatever the base is.
+    if (href.startsWith("#")) {
+        return { kind: "same_page", fragment: decodeFragment(href.slice(1)) };
+    }
+    let url;
+    try {
+        url = new URL(href, base);
+    }
+    catch {
+        return { kind: "malformed", reason: `"${href}" is not a URL a browser can resolve` };
+    }
+    const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+    switch (scheme) {
+        case "http":
+        case "https":
+            break;
+        case "mailto":
+            return {
+                kind: "mailto",
+                ...(url.pathname.trim() === "" ? { reason: "a mailto: with no address after it" } : {}),
+            };
+        case "tel":
+            return {
+                kind: "tel",
+                ...(url.pathname.trim() === "" ? { reason: "a tel: with no number after it" } : {}),
+            };
+        case "javascript":
+            return { kind: "javascript", reason: "runs a script instead of going anywhere" };
+        case "data":
+            return { kind: "data" };
+        default:
+            return { kind: "scheme", scheme, reason: `${scheme}: is handed to the operating system, not fetched` };
+    }
+    const fragment = url.hash ? decodeFragment(url.hash.slice(1)) : undefined;
+    const kind = dedupeKey(url.href) === dedupeKey(base) ? "same_page" : "http";
+    return {
+        kind,
+        resolved: url.href,
+        ...(fragment !== undefined ? { fragment } : {}),
+    };
+}
+/** `%C3%A9` in an href is `é` in an id — browsers match the decoded form. */
+function decodeFragment(fragment) {
+    try {
+        return decodeURIComponent(fragment);
+    }
+    catch {
+        return fragment;
+    }
+}
+/**
+ * The identity of a request.
+ *
+ * The fragment is dropped: it never reaches the server, so `/help#returns` and
+ * `/help#shipping` are one request and must not be checked twice. Everything
+ * else is kept, including the trailing slash — `/a` and `/a/` are different
+ * URLs and routinely redirect differently, so collapsing them would hide a
+ * redirect the tool exists to report.
+ */
+export function dedupeKey(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.hash = "";
+        return parsed.href;
+    }
+    catch {
+        return url;
+    }
+}
+/** Same scheme, host and port — the only definition a crawl can safely act on. */
+export function isInternal(url, origin) {
+    try {
+        return new URL(url).origin === new URL(origin).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The two fragments every browser resolves without an element to scroll to:
+ * an empty one (the top of the document, which is what `href="#"` means) and
+ * `#top`, which HTML defines as the same thing.
+ */
+export function isAlwaysValidFragment(fragment) {
+    return fragment === "" || fragment.toLowerCase() === "top";
+}
+/**
+ * Statuses that mean "I will not answer that", not "there is nothing here".
+ *
+ * A link behind a login answers 401, a WAF answers 403 to anything without a
+ * browser's fingerprint, a rate limiter answers 429, and LinkedIn answers 999
+ * to automated checks. Every one of those links works perfectly for a person
+ * with a browser, and reporting them as broken is how a link report gets
+ * ignored. 405 is here for the same reason from the other direction: the
+ * server refused the *method*, so the check failed, not the link.
+ */
+const REFUSED = {
+    401: "the server wants credentials before it will answer — the link is likely fine for a signed-in visitor",
+    403: "the server refused the check (bot protection usually answers this) — the link may well work in a browser",
+    405: "the server refused the request method",
+    429: "the check was rate-limited, not the link broken",
+    999: "a non-standard status some sites return to automated checks — not a broken link",
+};
+/**
+ * Decide what one check means.
+ *
+ * The order is the order the failures shadow each other: a loop makes the
+ * final status meaningless, a chain that ran out of hops never got one, a
+ * transport error means there is no status at all, and only then is the status
+ * itself worth reading.
+ */
+export function judgeCheck(outcome) {
+    const chain = outcome.chain.length > 0 ? outcome.chain : [""];
+    const hops = chain.length - 1;
+    const final = chain[chain.length - 1];
+    const landed = hops > 0 ? { final_url: final } : {};
+    const repeat = firstRepeat(chain);
+    if (repeat !== undefined) {
+        return {
+            category: "error",
+            detail: `the redirects loop — ${repeat} is visited twice`,
+            fix: "Follow the chain by hand: a redirect loop is a page nobody can reach.",
+            hops,
+            ...landed,
+        };
+    }
+    if (outcome.hops_exceeded) {
+        return {
+            category: "error",
+            detail: `still redirecting after ${MAX_LINK_REDIRECTS} redirects, last at ${final}`,
+            fix: "A chain this long is a configuration bug — most crawlers give up after five.",
+            hops,
+            ...landed,
+        };
+    }
+    if (outcome.error !== undefined) {
+        const failure = classifyFailure(outcome.error);
+        return { ...failure, hops, ...landed };
+    }
+    const status = outcome.status;
+    if (status === undefined) {
+        return { category: "error", detail: "the check produced no answer at all", hops, ...landed };
+    }
+    const named = label(status);
+    // A 3xx that is still a 3xx after the chain was followed had nowhere to go.
+    if (status >= 300 && status < 400) {
+        return {
+            category: "broken",
+            detail: `${named} — a redirect with no Location header to follow`,
+            fix: "Give the redirect a Location, or serve the page directly.",
+            hops,
+            ...landed,
+        };
+    }
+    if (status >= 400) {
+        const refused = REFUSED[status];
+        if (refused !== undefined) {
+            const method = status === 405 ? ` (${outcome.method} was refused too)` : "";
+            return {
+                category: "blocked",
+                detail: `${named} — ${refused}${method}`,
+                ...(status === 429
+                    ? { fix: "Lower `concurrency` or raise `timeout_ms` and check this one again." }
+                    : {}),
+                hops,
+                ...landed,
+            };
+        }
+        return {
+            category: "broken",
+            detail: hops > 0
+                ? `${named} — after ${plural(hops, "redirect")}, ending at ${final}`
+                : named,
+            fix: status === 404
+                ? "Point the link somewhere that exists, or restore the page."
+                : "This link answers an error to every visitor.",
+            hops,
+            ...landed,
+        };
+    }
+    if (hops === 0) {
+        return { category: "ok", detail: named, hops };
+    }
+    const upgraded = isUpgrade(chain);
+    return {
+        category: "redirect",
+        detail: `redirected to ${final} (${plural(hops, "hop")}), which answered ${named}`,
+        ...(hops > 1
+            ? { fix: "Link straight to the final address — every hop in the chain is another round trip." }
+            : upgraded
+                ? { fix: "Write the link as https:// — the http:// form costs an extra round trip on every visit." }
+                : {}),
+        hops,
+        final_url: final,
+    };
+}
+/** Did this chain exist only to swap http for https? */
+function isUpgrade(chain) {
+    try {
+        return new URL(chain[0]).protocol === "http:" && new URL(chain[chain.length - 1]).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** The first URL that appears twice, which is a loop however long the chain is. */
+function firstRepeat(chain) {
+    const seen = new Set();
+    for (const url of chain) {
+        if (seen.has(url))
+            return url;
+        seen.add(url);
+    }
+    return undefined;
+}
+/**
+ * Turn a transport failure into something a reader can act on.
+ *
+ * These are the five that a link check actually hits. Anything else is quoted
+ * verbatim rather than guessed at — an error nobody predicted is still useful,
+ * and a wrong paraphrase of it is not.
+ */
+export function classifyFailure(message) {
+    const line = String(message).split("\n")[0];
+    if (/Timeout\s+\d+\s*ms\s+exceeded|timed?\s?out|ETIMEDOUT/i.test(line)) {
+        return {
+            category: "timeout",
+            detail: "no answer within the timeout",
+            fix: "Raise `timeout_ms` if the host is simply slow; a link nobody's browser will wait for is broken in practice.",
+        };
+    }
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo|NAME_NOT_RESOLVED|ERR_NAME/i.test(line)) {
+        return {
+            category: "error",
+            detail: "the host name does not resolve",
+            fix: "Check the domain for a typo, and that it has not expired.",
+        };
+    }
+    if (/ECONNREFUSED|CONNECTION_REFUSED/i.test(line)) {
+        return { category: "error", detail: "nothing is listening on that address — the connection was refused" };
+    }
+    if (/ECONNRESET|socket hang up|EPIPE/i.test(line)) {
+        return { category: "error", detail: "the connection was closed before an answer arrived (socket hang up)" };
+    }
+    if (/certificate|CERT_|ERR_CERT|SSL|TLS|self-signed/i.test(line)) {
+        return {
+            category: "error",
+            detail: "the TLS certificate was rejected",
+            fix: "A browser shows an interstitial for this — to a visitor it is a broken link.",
+        };
+    }
+    return { category: "error", detail: line };
+}
+/** The registered name of a status code, or "" for the ones nobody standardised. */
+export function statusText(status) {
+    return STATUS_CODES[status] ?? "";
+}
+/** `404 Not Found`, or just `999` where inventing a name would be worse than having none. */
+function label(status) {
+    const name = statusText(status);
+    return name === "" ? String(status) : `${status} ${name}`;
+}
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=link-rules.js.map

package/dist/utils/link-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-rules.js","sourceRoot":"","sources":["../../src/utils/link-rules.ts"],"names":[],"mappings":"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","sourcesContent":["import { STATUS_CODES } from \"node:http\";\nimport { MAX_LINK_REDIRECTS } from \"../constants.js\";\nimport type { CheckOutcome } from \"../engine/links.js\";\n\n/**\n * What counts as a broken link.\n *\n * Everything here is pure: it takes an href and a base, or the outcome of one\n * HTTP check, and returns a verdict. Nothing in this file opens a browser or a\n * socket, which is the point — \"is this href even a request?\", \"did that chain\n * of redirects end somewhere real?\" and \"is a 403 a broken link?\" are all\n * judgements with edge cases, and judgements need unit tests that run in\n * milliseconds.\n *\n * The bias throughout is against false alarms. A report that calls a working\n * link broken is worse than one that says nothing: it sends somebody to look\n * at a page that is fine, and the next real finding gets ignored. So a status\n * that means \"I would not answer that\" is separated from one that means \"there\n * is nothing here\", and anything unrecognised is quoted rather than judged.\n */\n\n/* ── Classifying an href ──────────────────────────────────────────────── */\n\n/**\n * What kind of thing an href is.\n *\n * Only `http` is a request. `same_page` is answered by the DOM, the scheme\n * kinds are handed to something that is not a browser, and `malformed` never\n * leaves the page at all.\n */\nexport type HrefKind =\n  | \"http\"\n  | \"same_page\"\n  | \"empty\"\n  | \"mailto\"\n  | \"tel\"\n  | \"javascript\"\n  | \"data\"\n  | \"scheme\"\n  | \"malformed\";\n\nexport interface ClassifiedHref {\n  kind: HrefKind;\n  /** The absolute URL, for `http` and `same_page`. */\n  resolved?: string;\n  /** The `#…` part, decoded and without its hash, when there is one. */\n  fragment?: string;\n  /** The scheme, for `scheme` — `ftp`, `chrome-extension`, whatever the page used. */\n  scheme?: string;\n  /** Why this one cannot be checked, or is suspect. */\n  reason?: string;\n}\n\n/**\n * Work out what an href points at, resolved against the page it was found on.\n *\n * Order matters. An empty href and a bare `#` both resolve to the current\n * document, so they are recognised from the raw text before the URL parser\n * gets a chance to turn them into the page's own address and hide what the\n * author actually wrote — and `<a href=\"#\">` is the single most common dead\n * link there is.\n */\nexport function classifyHref(rawHref: string, base: string): ClassifiedHref {\n  const href = String(rawHref ?? \"\").trim();\n\n  // Per RFC 3986 an empty reference is the current document. Browsers reload\n  // the page; it is almost never what the author meant.\n  if (href === \"\") {\n    return { kind: \"empty\", reason: \"an empty href reloads the current page\" };\n  }\n\n  // A fragment-only reference never leaves the document, whatever the base is.\n  if (href.startsWith(\"#\")) {\n    return { kind: \"same_page\", fragment: decodeFragment(href.slice(1)) };\n  }\n\n  let url: URL;\n  try {\n    url = new URL(href, base);\n  } catch {\n    return { kind: \"malformed\", reason: `\"${href}\" is not a URL a browser can resolve` };\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  switch (scheme) {\n    case \"http\":\n    case \"https\":\n      break;\n    case \"mailto\":\n      return {\n        kind: \"mailto\",\n        ...(url.pathname.trim() === \"\" ? { reason: \"a mailto: with no address after it\" } : {}),\n      };\n    case \"tel\":\n      return {\n        kind: \"tel\",\n        ...(url.pathname.trim() === \"\" ? { reason: \"a tel: with no number after it\" } : {}),\n      };\n    case \"javascript\":\n      return { kind: \"javascript\", reason: \"runs a script instead of going anywhere\" };\n    case \"data\":\n      return { kind: \"data\" };\n    default:\n      return { kind: \"scheme\", scheme, reason: `${scheme}: is handed to the operating system, not fetched` };\n  }\n\n  const fragment = url.hash ? decodeFragment(url.hash.slice(1)) : undefined;\n  const kind: HrefKind = dedupeKey(url.href) === dedupeKey(base) ? \"same_page\" : \"http\";\n  return {\n    kind,\n    resolved: url.href,\n    ...(fragment !== undefined ? { fragment } : {}),\n  };\n}\n\n/** `%C3%A9` in an href is `é` in an id — browsers match the decoded form. */\nfunction decodeFragment(fragment: string): string {\n  try {\n    return decodeURIComponent(fragment);\n  } catch {\n    return fragment;\n  }\n}\n\n/**\n * The identity of a request.\n *\n * The fragment is dropped: it never reaches the server, so `/help#returns` and\n * `/help#shipping` are one request and must not be checked twice. Everything\n * else is kept, including the trailing slash — `/a` and `/a/` are different\n * URLs and routinely redirect differently, so collapsing them would hide a\n * redirect the tool exists to report.\n */\nexport function dedupeKey(url: string): string {\n  try {\n    const parsed = new URL(url);\n    parsed.hash = \"\";\n    return parsed.href;\n  } catch {\n    return url;\n  }\n}\n\n/** Same scheme, host and port — the only definition a crawl can safely act on. */\nexport function isInternal(url: string, origin: string): boolean {\n  try {\n    return new URL(url).origin === new URL(origin).origin;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The two fragments every browser resolves without an element to scroll to:\n * an empty one (the top of the document, which is what `href=\"#\"` means) and\n * `#top`, which HTML defines as the same thing.\n */\nexport function isAlwaysValidFragment(fragment: string): boolean {\n  return fragment === \"\" || fragment.toLowerCase() === \"top\";\n}\n\n/* ── Judging the answer ───────────────────────────────────────────────── */\n\n/** Where a checked link ended up. */\nexport type LinkCategory = \"ok\" | \"redirect\" | \"broken\" | \"blocked\" | \"timeout\" | \"error\";\n\nexport interface LinkVerdict {\n  category: LinkCategory;\n  /** What happened, in one phrase: \"404 Not Found\", \"redirected to … (2 hops)\". */\n  detail: string;\n  /** What to do about it. Only where there is something to do. */\n  fix?: string;\n  /** Redirects followed. */\n  hops: number;\n  /** Where the chain actually ended, when that is not where it started. */\n  final_url?: string;\n}\n\n/**\n * Statuses that mean \"I will not answer that\", not \"there is nothing here\".\n *\n * A link behind a login answers 401, a WAF answers 403 to anything without a\n * browser's fingerprint, a rate limiter answers 429, and LinkedIn answers 999\n * to automated checks. Every one of those links works perfectly for a person\n * with a browser, and reporting them as broken is how a link report gets\n * ignored. 405 is here for the same reason from the other direction: the\n * server refused the *method*, so the check failed, not the link.\n */\nconst REFUSED: Readonly<Record<number, string>> = {\n  401: \"the server wants credentials before it will answer — the link is likely fine for a signed-in visitor\",\n  403: \"the server refused the check (bot protection usually answers this) — the link may well work in a browser\",\n  405: \"the server refused the request method\",\n  429: \"the check was rate-limited, not the link broken\",\n  999: \"a non-standard status some sites return to automated checks — not a broken link\",\n};\n\n/**\n * Decide what one check means.\n *\n * The order is the order the failures shadow each other: a loop makes the\n * final status meaningless, a chain that ran out of hops never got one, a\n * transport error means there is no status at all, and only then is the status\n * itself worth reading.\n */\nexport function judgeCheck(outcome: CheckOutcome): LinkVerdict {\n  const chain = outcome.chain.length > 0 ? outcome.chain : [\"\"];\n  const hops = chain.length - 1;\n  const final = chain[chain.length - 1];\n  const landed = hops > 0 ? { final_url: final } : {};\n\n  const repeat = firstRepeat(chain);\n  if (repeat !== undefined) {\n    return {\n      category: \"error\",\n      detail: `the redirects loop — ${repeat} is visited twice`,\n      fix: \"Follow the chain by hand: a redirect loop is a page nobody can reach.\",\n      hops,\n      ...landed,\n    };\n  }\n\n  if (outcome.hops_exceeded) {\n    return {\n      category: \"error\",\n      detail: `still redirecting after ${MAX_LINK_REDIRECTS} redirects, last at ${final}`,\n      fix: \"A chain this long is a configuration bug — most crawlers give up after five.\",\n      hops,\n      ...landed,\n    };\n  }\n\n  if (outcome.error !== undefined) {\n    const failure = classifyFailure(outcome.error);\n    return { ...failure, hops, ...landed };\n  }\n\n  const status = outcome.status;\n  if (status === undefined) {\n    return { category: \"error\", detail: \"the check produced no answer at all\", hops, ...landed };\n  }\n\n  const named = label(status);\n\n  // A 3xx that is still a 3xx after the chain was followed had nowhere to go.\n  if (status >= 300 && status < 400) {\n    return {\n      category: \"broken\",\n      detail: `${named} — a redirect with no Location header to follow`,\n      fix: \"Give the redirect a Location, or serve the page directly.\",\n      hops,\n      ...landed,\n    };\n  }\n\n  if (status >= 400) {\n    const refused = REFUSED[status];\n    if (refused !== undefined) {\n      const method = status === 405 ? ` (${outcome.method} was refused too)` : \"\";\n      return {\n        category: \"blocked\",\n        detail: `${named} — ${refused}${method}`,\n        ...(status === 429\n          ? { fix: \"Lower `concurrency` or raise `timeout_ms` and check this one again.\" }\n          : {}),\n        hops,\n        ...landed,\n      };\n    }\n    return {\n      category: \"broken\",\n      detail:\n        hops > 0\n          ? `${named} — after ${plural(hops, \"redirect\")}, ending at ${final}`\n          : named,\n      fix:\n        status === 404\n          ? \"Point the link somewhere that exists, or restore the page.\"\n          : \"This link answers an error to every visitor.\",\n      hops,\n      ...landed,\n    };\n  }\n\n  if (hops === 0) {\n    return { category: \"ok\", detail: named, hops };\n  }\n\n  const upgraded = isUpgrade(chain);\n  return {\n    category: \"redirect\",\n    detail: `redirected to ${final} (${plural(hops, \"hop\")}), which answered ${named}`,\n    ...(hops > 1\n      ? { fix: \"Link straight to the final address — every hop in the chain is another round trip.\" }\n      : upgraded\n        ? { fix: \"Write the link as https:// — the http:// form costs an extra round trip on every visit.\" }\n        : {}),\n    hops,\n    final_url: final,\n  };\n}\n\n/** Did this chain exist only to swap http for https? */\nfunction isUpgrade(chain: string[]): boolean {\n  try {\n    return new URL(chain[0]).protocol === \"http:\" && new URL(chain[chain.length - 1]).protocol === \"https:\";\n  } catch {\n    return false;\n  }\n}\n\n/** The first URL that appears twice, which is a loop however long the chain is. */\nfunction firstRepeat(chain: string[]): string | undefined {\n  const seen = new Set<string>();\n  for (const url of chain) {\n    if (seen.has(url)) return url;\n    seen.add(url);\n  }\n  return undefined;\n}\n\n/**\n * Turn a transport failure into something a reader can act on.\n *\n * These are the five that a link check actually hits. Anything else is quoted\n * verbatim rather than guessed at — an error nobody predicted is still useful,\n * and a wrong paraphrase of it is not.\n */\nexport function classifyFailure(message: string): { category: LinkCategory; detail: string; fix?: string } {\n  const line = String(message).split(\"\\n\")[0];\n\n  if (/Timeout\\s+\\d+\\s*ms\\s+exceeded|timed?\\s?out|ETIMEDOUT/i.test(line)) {\n    return {\n      category: \"timeout\",\n      detail: \"no answer within the timeout\",\n      fix: \"Raise `timeout_ms` if the host is simply slow; a link nobody's browser will wait for is broken in practice.\",\n    };\n  }\n  if (/ENOTFOUND|EAI_AGAIN|getaddrinfo|NAME_NOT_RESOLVED|ERR_NAME/i.test(line)) {\n    return {\n      category: \"error\",\n      detail: \"the host name does not resolve\",\n      fix: \"Check the domain for a typo, and that it has not expired.\",\n    };\n  }\n  if (/ECONNREFUSED|CONNECTION_REFUSED/i.test(line)) {\n    return { category: \"error\", detail: \"nothing is listening on that address — the connection was refused\" };\n  }\n  if (/ECONNRESET|socket hang up|EPIPE/i.test(line)) {\n    return { category: \"error\", detail: \"the connection was closed before an answer arrived (socket hang up)\" };\n  }\n  if (/certificate|CERT_|ERR_CERT|SSL|TLS|self-signed/i.test(line)) {\n    return {\n      category: \"error\",\n      detail: \"the TLS certificate was rejected\",\n      fix: \"A browser shows an interstitial for this — to a visitor it is a broken link.\",\n    };\n  }\n  return { category: \"error\", detail: line };\n}\n\n/** The registered name of a status code, or \"\" for the ones nobody standardised. */\nexport function statusText(status: number): string {\n  return STATUS_CODES[status] ?? \"\";\n}\n\n/** `404 Not Found`, or just `999` where inventing a name would be worse than having none. */\nfunction label(status: number): string {\n  const name = statusText(status);\n  return name === \"\" ? String(status) : `${status} ${name}`;\n}\n\nfunction plural(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n"]}

package/dist/utils/mock-rules.d.ts

@@ -0,0 +1,144 @@
+/**
+ * What a mock means, and what one run of them is worth reporting.
+ *
+ * Everything here is pure: no Playwright, no page, no socket. The engine turns
+ * a `ResolvedMock` into a real route and counts what happened; this file
+ * decides what a scenario expands to, how a body is encoded, which mock wins
+ * when two patterns match, and how the result reads.
+ */
+/**
+ * The shorthands. Each expands to a response the caller can then override
+ * field by field, which is what makes them worth having: `slow` with your own
+ * body is one word plus a body, not a hand-written response.
+ */
+export declare const MOCK_SCENARIOS: readonly ["empty", "error", "unauthorized", "not_found", "slow", "malformed", "offline"];
+export type MockScenario = (typeof MOCK_SCENARIOS)[number];
+/**
+ * Failures the browser can be told to report. These four are the ones a
+ * developer actually means: the request failed, it hung, nothing was
+ * listening, or there is no network at all.
+ */
+export declare const ABORT_REASONS: readonly ["failed", "timedout", "connectionrefused", "internetdisconnected"];
+export type AbortReason = (typeof ABORT_REASONS)[number];
+/** One mock exactly as the caller wrote it. */
+export interface MockSpec {
+    url_pattern?: string;
+    scenario?: MockScenario;
+    response?: {
+        status?: number;
+        body?: unknown;
+        delay_ms?: number;
+        headers?: Record<string, string>;
+    };
+    abort?: AbortReason;
+    times?: number;
+}
+/** A mock with every question answered, ready for the engine to install. */
+export type ResolvedMock = {
+    kind: "abort";
+    url_pattern: string;
+    reason: AbortReason;
+    times?: number;
+    scenario?: MockScenario;
+} | {
+    kind: "fulfill";
+    url_pattern: string;
+    status: number;
+    /** Already encoded — the exact bytes the page will receive. */
+    body: string;
+    /** Header names lower-cased, so `content-type` can only be set once. */
+    headers: Record<string, string>;
+    delay_ms: number;
+    times?: number;
+    scenario?: MockScenario;
+};
+/**
+ * Turn one written mock into one the engine can install.
+ *
+ * The scenario supplies defaults and the caller's own fields win one at a
+ * time, so `{ scenario: "slow", response: { body } }` keeps the delay and takes
+ * the body. An explicit `abort` beats a scenario that would have answered: a
+ * caller who asked for a dead request means it.
+ */
+export declare function resolveMock(spec: MockSpec): ResolvedMock;
+/**
+ * Encode a body into the bytes the page will actually receive.
+ *
+ * A string is sent verbatim. This is the whole reason the malformed scenario
+ * works: `JSON.stringify("not json")` is `"not json"`, which parses perfectly,
+ * so encoding a string would make a broken API impossible to simulate. It goes
+ * out as `application/json` because these stand in for API responses — anyone
+ * mocking a page or a script says so in `headers`.
+ *
+ * Anything else is JSON, including `null`. Only an absent body means "no body",
+ * and it carries no content type at all.
+ */
+export declare function encodeBody(body: unknown): {
+    body: string;
+    content_type?: string;
+};
+/**
+ * The order to hand mocks to Playwright.
+ *
+ * Playwright checks routes last-registered-first; a caller reads their list
+ * top-down and expects the first pattern that matches to win. Reversing on the
+ * way in is what reconciles the two, and is the only reason this is not just a
+ * loop in the engine.
+ */
+export declare function installOrder<T>(mocks: readonly T[]): T[];
+/**
+ * The advice for a pattern that matched nothing, when the pattern itself looks
+ * like the reason.
+ *
+ * Patterns are matched against the whole URL, so `/api/orders` matches nothing
+ * on a page served from `http://localhost:3000` — by far the most common way
+ * to write a mock that silently does nothing. A pattern that already starts
+ * with a wildcard, or that is a full URL, is left alone: a wrong guess here is
+ * worse than no guess.
+ */
+export declare function patternHint(pattern: string): string | undefined;
+/** What one mock did during a run. */
+export interface MockActivity {
+    mock: ResolvedMock;
+    /** Requests this mock intercepted. */
+    hits: number;
+    /**
+     * Requests it actually answered. Lower than `hits` when a delayed response
+     * outlived the recording — the request was caught but the page never got a
+     * reply, which is a finding rather than a bug in the count.
+     */
+    answered: number;
+    /** The first few URLs it intercepted, for the report. */
+    urls: string[];
+}
+/** A request no mock matched. */
+export interface UnmatchedRequest {
+    method: string;
+    url: string;
+    /** What the real server answered, when it was allowed to. */
+    status?: number;
+    /** Set when `block_unmatched` killed it before it left the browser. */
+    blocked?: boolean;
+}
+export interface MockReportInput {
+    activity: MockActivity[];
+    unmatched: UnmatchedRequest[];
+    block_unmatched: boolean;
+    /** The recording length, so a delay that outlives it can be named. */
+    duration_ms: number;
+}
+/**
+ * The mock report, as lines for the capture summary.
+ *
+ * A mock that never matched leads, because it is the finding this tool exists
+ * to surface: mock the products endpoint, watch the app call `/api/product-list`,
+ * see a page that looks perfectly fine, and learn nothing at all. The same
+ * reasoning puts the unmatched requests in — a run that quietly used the real
+ * backend for half its data is not the test anybody thought they ran.
+ */
+export declare function formatMockReport(input: MockReportInput): string[];
+/**
+ * What a mock serves, in a few words. Names the scenario when there was one —
+ * "200 empty" says more than "200" and is what the caller wrote.
+ */
+export declare function describeMock(mock: ResolvedMock): string;