npm - framewatch-mcp-server - Versions diffs - 0.1.0 → 0.2.0 - Mend

framewatch-mcp-server 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (133) hide show

package/README.md +895 -15
package/dist/constants.d.ts +274 -0
package/dist/constants.js +279 -0
package/dist/constants.js.map +1 -1
package/dist/engine/browser.d.ts +20 -4
package/dist/engine/browser.js +26 -9
package/dist/engine/browser.js.map +1 -1
package/dist/engine/clicks.d.ts +221 -0
package/dist/engine/clicks.js +801 -0
package/dist/engine/clicks.js.map +1 -0
package/dist/engine/forms.d.ts +137 -0
package/dist/engine/forms.js +474 -0
package/dist/engine/forms.js.map +1 -0
package/dist/engine/hmr.d.ts +41 -0
package/dist/engine/hmr.js +91 -0
package/dist/engine/hmr.js.map +1 -0
package/dist/engine/inspect.d.ts +31 -0
package/dist/engine/inspect.js +383 -0
package/dist/engine/inspect.js.map +1 -0
package/dist/engine/interaction.d.ts +12 -7
package/dist/engine/interaction.js +110 -18
package/dist/engine/interaction.js.map +1 -1
package/dist/engine/links.d.ts +134 -0
package/dist/engine/links.js +384 -0
package/dist/engine/links.js.map +1 -0
package/dist/engine/mocks.d.ts +53 -0
package/dist/engine/mocks.js +148 -0
package/dist/engine/mocks.js.map +1 -0
package/dist/engine/rtl.d.ts +129 -0
package/dist/engine/rtl.js +540 -0
package/dist/engine/rtl.js.map +1 -0
package/dist/engine/seo.d.ts +189 -0
package/dist/engine/seo.js +398 -0
package/dist/engine/seo.js.map +1 -0
package/dist/engine/snapshot.d.ts +29 -0
package/dist/engine/snapshot.js +10 -0
package/dist/engine/snapshot.js.map +1 -0
package/dist/engine/vue.d.ts +54 -0
package/dist/engine/vue.js +419 -0
package/dist/engine/vue.js.map +1 -0
package/dist/index.js +45 -1
package/dist/index.js.map +1 -1
package/dist/tools/accessibility.d.ts +4 -0
package/dist/tools/accessibility.js +9 -2
package/dist/tools/accessibility.js.map +1 -1
package/dist/tools/api-mock.d.ts +405 -0
package/dist/tools/api-mock.js +186 -0
package/dist/tools/api-mock.js.map +1 -0
package/dist/tools/capture.d.ts +90 -26
package/dist/tools/capture.js +109 -58
package/dist/tools/capture.js.map +1 -1
package/dist/tools/compare.d.ts +4 -0
package/dist/tools/compare.js +16 -5
package/dist/tools/compare.js.map +1 -1
package/dist/tools/dead-clicks.d.ts +128 -0
package/dist/tools/dead-clicks.js +570 -0
package/dist/tools/dead-clicks.js.map +1 -0
package/dist/tools/form-test.d.ts +112 -0
package/dist/tools/form-test.js +477 -0
package/dist/tools/form-test.js.map +1 -0
package/dist/tools/index.d.ts +17 -1
package/dist/tools/index.js +45 -1
package/dist/tools/index.js.map +1 -1
package/dist/tools/inspect.d.ts +78 -0
package/dist/tools/inspect.js +136 -0
package/dist/tools/inspect.js.map +1 -0
package/dist/tools/interact.d.ts +37 -18
package/dist/tools/interact.js +113 -13
package/dist/tools/interact.js.map +1 -1
package/dist/tools/links.d.ts +129 -0
package/dist/tools/links.js +640 -0
package/dist/tools/links.js.map +1 -0
package/dist/tools/responsive.d.ts +10 -6
package/dist/tools/responsive.js +21 -4
package/dist/tools/responsive.js.map +1 -1
package/dist/tools/rtl.d.ts +241 -0
package/dist/tools/rtl.js +410 -0
package/dist/tools/rtl.js.map +1 -0
package/dist/tools/save-auth.d.ts +263 -0
package/dist/tools/save-auth.js +253 -0
package/dist/tools/save-auth.js.map +1 -0
package/dist/tools/screenshot.d.ts +4 -0
package/dist/tools/screenshot.js +15 -4
package/dist/tools/screenshot.js.map +1 -1
package/dist/tools/seo.d.ts +113 -0
package/dist/tools/seo.js +281 -0
package/dist/tools/seo.js.map +1 -0
package/dist/tools/snapshot.d.ts +122 -0
package/dist/tools/snapshot.js +183 -0
package/dist/tools/snapshot.js.map +1 -0
package/dist/tools/wait-for.d.ts +107 -0
package/dist/tools/wait-for.js +167 -0
package/dist/tools/wait-for.js.map +1 -0
package/dist/utils/arabic-text.d.ts +14 -0
package/dist/utils/arabic-text.js +193 -0
package/dist/utils/arabic-text.js.map +1 -0
package/dist/utils/budget.d.ts +41 -0
package/dist/utils/budget.js +182 -0
package/dist/utils/budget.js.map +1 -0
package/dist/utils/format.d.ts +11 -1
package/dist/utils/format.js +27 -4
package/dist/utils/format.js.map +1 -1
package/dist/utils/highlight.d.ts +69 -0
package/dist/utils/highlight.js +181 -0
package/dist/utils/highlight.js.map +1 -0
package/dist/utils/link-rules.d.ts +100 -0
package/dist/utils/link-rules.js +284 -0
package/dist/utils/link-rules.js.map +1 -0
package/dist/utils/mock-rules.d.ts +144 -0
package/dist/utils/mock-rules.js +224 -0
package/dist/utils/mock-rules.js.map +1 -0
package/dist/utils/rtl-rules.d.ts +142 -0
package/dist/utils/rtl-rules.js +296 -0
package/dist/utils/rtl-rules.js.map +1 -0
package/dist/utils/seo-rules.d.ts +129 -0
package/dist/utils/seo-rules.js +726 -0
package/dist/utils/seo-rules.js.map +1 -0
package/dist/utils/snapshot-rules.d.ts +33 -0
package/dist/utils/snapshot-rules.js +111 -0
package/dist/utils/snapshot-rules.js.map +1 -0
package/dist/utils/storage-state.d.ts +76 -0
package/dist/utils/storage-state.js +195 -0
package/dist/utils/storage-state.js.map +1 -0
package/dist/utils/style-rules.d.ts +107 -0
package/dist/utils/style-rules.js +223 -0
package/dist/utils/style-rules.js.map +1 -0
package/dist/utils/test-data.d.ts +75 -0
package/dist/utils/test-data.js +294 -0
package/dist/utils/test-data.js.map +1 -0
package/dist/utils/vue-rules.d.ts +72 -0
package/dist/utils/vue-rules.js +108 -0
package/dist/utils/vue-rules.js.map +1 -0
package/package.json +6 -4

package/dist/utils/highlight.d.ts ADDED Viewed

@@ -0,0 +1,69 @@
+import type { Page } from "playwright";
+import type { BoundingBox } from "../types.js";
+/**
+ * Element highlight overlay.
+ *
+ * A selector like `.nav > button:nth-of-type(3)` says nothing about where the
+ * problem is on screen. This draws a labelled box over each named element and
+ * leaves it there until the screenshot has been taken, so a report about
+ * elements comes with a picture of those elements.
+ *
+ * The boxes are drawn in *document* coordinates and appended to `<body>`, so
+ * one full-page screenshot shows every highlight, including the ones below the
+ * fold. They are `pointer-events: none` and are removed again by
+ * `clearHighlights`, so nothing here changes what the page does — but the
+ * overlay is still a DOM mutation, which is why callers that watch for
+ * mutations (framewatch_dead_clicks) draw it only once everything has been
+ * measured.
+ *
+ * Every style is set through the CSSOM rather than as a `style` attribute or a
+ * `<style>` block: a page with a strict Content-Security-Policy blocks both of
+ * those, and the pages most worth auditing are the ones that lock themselves
+ * down.
+ */
+/** The id of the container every highlight lives in, so `clearHighlights` can find it. */
+export declare const HIGHLIGHT_CONTAINER_ID = "__framewatch_highlights";
+export interface Highlight {
+    /**
+     * CSS selector for the element to draw over — or, when `box` is given, just
+     * the name this highlight is reported under in `drawn` / `missing`.
+     */
+    selector: string;
+    /**
+     * Draw here instead of looking `selector` up, in viewport pixels. For an
+     * element that was resolved some other way (an aria ref, a handle) and has
+     * already been measured.
+     */
+    box?: BoundingBox;
+    /**
+     * Which match of `selector` to draw over, when the selector is not unique.
+     * Defaults to the first.
+     */
+    match_index?: number;
+    /** Drawn in the corner of the box — a number, or a short phrase. */
+    label?: string;
+    /** Any CSS colour. The box is outlined in it, and the label badge is painted with it. */
+    colour?: string;
+    /**
+     * The translucent fill inside the box. Give it a low alpha: what is under
+     * the box is the thing being reported on, and it has to stay readable.
+     */
+    wash?: string;
+}
+export interface HighlightResult {
+    /** Selectors that were drawn. */
+    drawn: string[];
+    /** Selectors that matched nothing, or matched something with no box to draw. */
+    missing: string[];
+}
+/**
+ * Draw a box over each element in `highlights` and return which ones landed.
+ *
+ * An element that is gone, or that has no size, is reported in `missing`
+ * rather than being an error: by the time a report is drawn the page may have
+ * re-rendered, and a screenshot missing one box is far better than no
+ * screenshot at all.
+ */
+export declare function highlightElements(page: Page, highlights: readonly Highlight[], max?: number): Promise<HighlightResult>;
+/** Remove every box this module drew. Safe to call when there are none. */
+export declare function clearHighlights(page: Page): Promise<void>;

package/dist/utils/highlight.js ADDED Viewed

@@ -0,0 +1,181 @@
+import { MAX_HIGHLIGHTS } from "../constants.js";
+/**
+ * Element highlight overlay.
+ *
+ * A selector like `.nav > button:nth-of-type(3)` says nothing about where the
+ * problem is on screen. This draws a labelled box over each named element and
+ * leaves it there until the screenshot has been taken, so a report about
+ * elements comes with a picture of those elements.
+ *
+ * The boxes are drawn in *document* coordinates and appended to `<body>`, so
+ * one full-page screenshot shows every highlight, including the ones below the
+ * fold. They are `pointer-events: none` and are removed again by
+ * `clearHighlights`, so nothing here changes what the page does — but the
+ * overlay is still a DOM mutation, which is why callers that watch for
+ * mutations (framewatch_dead_clicks) draw it only once everything has been
+ * measured.
+ *
+ * Every style is set through the CSSOM rather than as a `style` attribute or a
+ * `<style>` block: a page with a strict Content-Security-Policy blocks both of
+ * those, and the pages most worth auditing are the ones that lock themselves
+ * down.
+ */
+/** The id of the container every highlight lives in, so `clearHighlights` can find it. */
+export const HIGHLIGHT_CONTAINER_ID = "__framewatch_highlights";
+/**
+ * Draw a box over each element in `highlights` and return which ones landed.
+ *
+ * An element that is gone, or that has no size, is reported in `missing`
+ * rather than being an error: by the time a report is drawn the page may have
+ * re-rendered, and a screenshot missing one box is far better than no
+ * screenshot at all.
+ */
+export async function highlightElements(page, highlights, max = MAX_HIGHLIGHTS) {
+    const wanted = highlights.slice(0, Math.max(0, max));
+    if (wanted.length === 0)
+        return { drawn: [], missing: [] };
+    try {
+        return await page.evaluate(drawHighlights, {
+            container_id: HIGHLIGHT_CONTAINER_ID,
+            items: wanted.map((item) => ({
+                selector: item.selector,
+                ...(item.box ? { box: item.box } : {}),
+                match_index: item.match_index ?? 0,
+                label: item.label ?? "",
+                colour: item.colour ?? "#e5194b",
+                wash: item.wash ?? "rgba(229, 25, 75, 0.16)",
+            })),
+        });
+    }
+    catch {
+        // A page that will not run script (torn down, mid-navigation) simply gets
+        // no overlay. The caller still has its screenshot.
+        return { drawn: [], missing: wanted.map((item) => item.selector) };
+    }
+}
+/** Remove every box this module drew. Safe to call when there are none. */
+export async function clearHighlights(page) {
+    await page
+        .evaluate((id) => {
+        const node = globalThis.document?.getElementById(id);
+        if (node && node.parentNode)
+            node.parentNode.removeChild(node);
+    }, HIGHLIGHT_CONTAINER_ID)
+        .catch(() => { });
+}
+function drawHighlights(options) {
+    const doc = globalThis.document;
+    const drawn = [];
+    const missing = [];
+    if (!doc || !doc.body)
+        return { drawn, missing: options.items.map((item) => item.selector) };
+    const existing = doc.getElementById(options.container_id);
+    if (existing && existing.parentNode)
+        existing.parentNode.removeChild(existing);
+    const container = doc.createElement("div");
+    container.id = options.container_id;
+    const style = (node, rules) => {
+        for (const name in rules) {
+            try {
+                node.style.setProperty(name, rules[name], "important");
+            }
+            catch {
+                // A patched CSSOM; the box may look wrong but the screenshot survives.
+            }
+        }
+    };
+    style(container, {
+        position: "absolute",
+        left: "0",
+        top: "0",
+        width: "0",
+        height: "0",
+        margin: "0",
+        padding: "0",
+        border: "0",
+        "pointer-events": "none",
+        // Above anything the page itself can stack.
+        "z-index": "2147483647",
+    });
+    // The container goes in empty and is measured, so every box below can be
+    // positioned relative to it. Absolute coordinates would be wrong the moment
+    // the page gives <body> a `position` or a `transform` of its own, which is
+    // exactly the kind of page worth auditing.
+    doc.body.appendChild(container);
+    let originLeft = 0;
+    let originTop = 0;
+    try {
+        const origin = container.getBoundingClientRect();
+        originLeft = origin.left;
+        originTop = origin.top;
+    }
+    catch {
+        // No rect to correct against; boxes land in document coordinates.
+    }
+    for (const item of options.items) {
+        let rect = null;
+        if (item.box) {
+            // Already measured, in viewport pixels — the same space as
+            // getBoundingClientRect, so it corrects against the origin the same way.
+            rect = { left: item.box.x, top: item.box.y, width: item.box.width, height: item.box.height };
+        }
+        else {
+            let element = null;
+            try {
+                const matches = doc.querySelectorAll(item.selector);
+                element = matches[item.match_index] ?? matches[0] ?? null;
+            }
+            catch {
+                element = null;
+            }
+            rect = element && element.getBoundingClientRect ? element.getBoundingClientRect() : null;
+        }
+        if (!rect || rect.width <= 0 || rect.height <= 0) {
+            missing.push(item.selector);
+            continue;
+        }
+        const left = rect.left - originLeft;
+        const top = rect.top - originTop;
+        const box = doc.createElement("div");
+        style(box, {
+            position: "absolute",
+            // Laid out against the container, which sits at the document origin —
+            // so one full-page screenshot catches every box, including the ones
+            // below the fold.
+            left: `${Math.round(left)}px`,
+            top: `${Math.round(top)}px`,
+            width: `${Math.round(rect.width)}px`,
+            height: `${Math.round(rect.height)}px`,
+            "box-sizing": "border-box",
+            border: `3px solid ${item.colour}`,
+            "border-radius": "3px",
+            // A wash rather than a fill: what is under the box is the thing being
+            // reported on, and it has to stay readable.
+            "background-color": item.wash,
+            "box-shadow": "0 0 0 2px rgba(255, 255, 255, 0.85)",
+            "pointer-events": "none",
+        });
+        if (item.label !== "") {
+            const tag = doc.createElement("div");
+            tag.textContent = item.label;
+            style(tag, {
+                position: "absolute",
+                left: "-3px",
+                // Above the box, unless that would fall off the top of the document.
+                top: top >= 20 ? "-20px" : `${Math.round(rect.height)}px`,
+                padding: "1px 6px",
+                "background-color": item.colour,
+                color: "#ffffff",
+                font: "700 12px/16px ui-monospace, SFMono-Regular, Menlo, monospace",
+                "white-space": "nowrap",
+                "border-radius": "3px",
+                "pointer-events": "none",
+            });
+            box.appendChild(tag);
+        }
+        container.appendChild(box);
+        drawn.push(item.selector);
+    }
+    return { drawn, missing };
+}
+//# sourceMappingURL=highlight.js.map

package/dist/utils/highlight.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"highlight.js","sourceRoot":"","sources":["../../src/utils/highlight.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAqChE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAU,EACV,UAAgC,EAChC,MAAc,cAAc;IAE5B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAE3D,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE;YACzC,YAAY,EAAE,sBAAsB;YACpC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC;gBAClC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;gBACvB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS;gBAChC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,yBAAyB;aAC7C,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,mDAAmD;QACnD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACrE,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,MAAM,IAAI;SACP,QAAQ,CAAC,CAAC,EAAU,EAAE,EAAE;QACvB,MAAM,IAAI,GAAI,UAAkB,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;QAC9D,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC,EAAE,sBAAsB,CAAC;SACzB,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACrB,CAAC;AAoBD,SAAS,cAAc,CAAC,OAAoB;IAC1C,MAAM,GAAG,GAAI,UAAkB,CAAC,QAAQ,CAAC;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAE7F,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1D,IAAI,QAAQ,IAAI,QAAQ,CAAC,UAAU;QAAE,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE/E,MAAM,SAAS,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3C,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,IAAS,EAAE,KAA6B,EAAQ,EAAE;QAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,CAAC,SAAS,EAAE;QACf,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,GAAG;QACT,GAAG,EAAE,GAAG;QACR,KAAK,EAAE,GAAG;QACV,MAAM,EAAE,GAAG;QACX,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,GAAG;QACZ,MAAM,EAAE,GAAG;QACX,gBAAgB,EAAE,MAAM;QACxB,4CAA4C;QAC5C,SAAS,EAAE,YAAY;KACxB,CAAC,CAAC;IAEH,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,2CAA2C;IAC3C,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,qBAAqB,EAAE,CAAC;QACjD,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;IACpE,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,GAAwE,IAAI,CAAC;QACrF,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,2DAA2D;YAC3D,yEAAyE;YACzE,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/F,CAAC;aAAM,CAAC;YACN,IAAI,OAAO,GAAQ,IAAI,CAAC;YACxB,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACpD,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;YAC5D,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3F,CAAC;QACD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACjD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACrC,KAAK,CAAC,GAAG,EAAE;YACT,QAAQ,EAAE,UAAU;YACpB,sEAAsE;YACtE,oEAAoE;YACpE,kBAAkB;YAClB,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI;YAC7B,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI;YAC3B,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;YACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI;YACtC,YAAY,EAAE,YAAY;YAC1B,MAAM,EAAE,aAAa,IAAI,CAAC,MAAM,EAAE;YAClC,eAAe,EAAE,KAAK;YACtB,sEAAsE;YACtE,4CAA4C;YAC5C,kBAAkB,EAAE,IAAI,CAAC,IAAI;YAC7B,YAAY,EAAE,qCAAqC;YACnD,gBAAgB,EAAE,MAAM;SACzB,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YACrC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;YAC7B,KAAK,CAAC,GAAG,EAAE;gBACT,QAAQ,EAAE,UAAU;gBACpB,IAAI,EAAE,MAAM;gBACZ,qEAAqE;gBACrE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI;gBACzD,OAAO,EAAE,SAAS;gBAClB,kBAAkB,EAAE,IAAI,CAAC,MAAM;gBAC/B,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,8DAA8D;gBACpE,aAAa,EAAE,QAAQ;gBACvB,eAAe,EAAE,KAAK;gBACtB,gBAAgB,EAAE,MAAM;aACzB,CAAC,CAAC;YACH,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC","sourcesContent":["import type { Page } from \"playwright\";\nimport { MAX_HIGHLIGHTS } from \"../constants.js\";\nimport type { BoundingBox } from \"../types.js\";\n\n/**\n * Element highlight overlay.\n *\n * A selector like `.nav > button:nth-of-type(3)` says nothing about where the\n * problem is on screen. This draws a labelled box over each named element and\n * leaves it there until the screenshot has been taken, so a report about\n * elements comes with a picture of those elements.\n *\n * The boxes are drawn in *document* coordinates and appended to `<body>`, so\n * one full-page screenshot shows every highlight, including the ones below the\n * fold. They are `pointer-events: none` and are removed again by\n * `clearHighlights`, so nothing here changes what the page does — but the\n * overlay is still a DOM mutation, which is why callers that watch for\n * mutations (framewatch_dead_clicks) draw it only once everything has been\n * measured.\n *\n * Every style is set through the CSSOM rather than as a `style` attribute or a\n * `<style>` block: a page with a strict Content-Security-Policy blocks both of\n * those, and the pages most worth auditing are the ones that lock themselves\n * down.\n */\n\n/** The id of the container every highlight lives in, so `clearHighlights` can find it. */\nexport const HIGHLIGHT_CONTAINER_ID = \"__framewatch_highlights\";\n\nexport interface Highlight {\n /**\n * CSS selector for the element to draw over — or, when `box` is given, just\n * the name this highlight is reported under in `drawn` / `missing`.\n */\n selector: string;\n /**\n * Draw here instead of looking `selector` up, in viewport pixels. For an\n * element that was resolved some other way (an aria ref, a handle) and has\n * already been measured.\n */\n box?: BoundingBox;\n /**\n * Which match of `selector` to draw over, when the selector is not unique.\n * Defaults to the first.\n */\n match_index?: number;\n /** Drawn in the corner of the box — a number, or a short phrase. */\n label?: string;\n /** Any CSS colour. The box is outlined in it, and the label badge is painted with it. */\n colour?: string;\n /**\n * The translucent fill inside the box. Give it a low alpha: what is under\n * the box is the thing being reported on, and it has to stay readable.\n */\n wash?: string;\n}\n\nexport interface HighlightResult {\n /** Selectors that were drawn. */\n drawn: string[];\n /** Selectors that matched nothing, or matched something with no box to draw. */\n missing: string[];\n}\n\n/**\n * Draw a box over each element in `highlights` and return which ones landed.\n *\n * An element that is gone, or that has no size, is reported in `missing`\n * rather than being an error: by the time a report is drawn the page may have\n * re-rendered, and a screenshot missing one box is far better than no\n * screenshot at all.\n */\nexport async function highlightElements(\n page: Page,\n highlights: readonly Highlight[],\n max: number = MAX_HIGHLIGHTS,\n): Promise<HighlightResult> {\n const wanted = highlights.slice(0, Math.max(0, max));\n if (wanted.length === 0) return { drawn: [], missing: [] };\n\n try {\n return await page.evaluate(drawHighlights, {\n container_id: HIGHLIGHT_CONTAINER_ID,\n items: wanted.map((item) => ({\n selector: item.selector,\n ...(item.box ? { box: item.box } : {}),\n match_index: item.match_index ?? 0,\n label: item.label ?? \"\",\n colour: item.colour ?? \"#e5194b\",\n wash: item.wash ?? \"rgba(229, 25, 75, 0.16)\",\n })),\n });\n } catch {\n // A page that will not run script (torn down, mid-navigation) simply gets\n // no overlay. The caller still has its screenshot.\n return { drawn: [], missing: wanted.map((item) => item.selector) };\n }\n}\n\n/** Remove every box this module drew. Safe to call when there are none. */\nexport async function clearHighlights(page: Page): Promise<void> {\n await page\n .evaluate((id: string) => {\n const node = (globalThis as any).document?.getElementById(id);\n if (node && node.parentNode) node.parentNode.removeChild(node);\n }, HIGHLIGHT_CONTAINER_ID)\n .catch(() => {});\n}\n\n/* ── In-page ──────────────────────────────────────────────────────────────\n * Everything below runs inside Chromium, so it is written against\n * `globalThis` and untyped nodes: this package is compiled with the Node lib\n * only, and the page it lands in may have patched half of these properties.\n */\n\ninterface DrawOptions {\n container_id: string;\n items: Array<{\n selector: string;\n box?: { x: number; y: number; width: number; height: number };\n match_index: number;\n label: string;\n colour: string;\n wash: string;\n }>;\n}\n\nfunction drawHighlights(options: DrawOptions): { drawn: string[]; missing: string[] } {\n const doc = (globalThis as any).document;\n const drawn: string[] = [];\n const missing: string[] = [];\n if (!doc || !doc.body) return { drawn, missing: options.items.map((item) => item.selector) };\n\n const existing = doc.getElementById(options.container_id);\n if (existing && existing.parentNode) existing.parentNode.removeChild(existing);\n\n const container = doc.createElement(\"div\");\n container.id = options.container_id;\n const style = (node: any, rules: Record<string, string>): void => {\n for (const name in rules) {\n try {\n node.style.setProperty(name, rules[name], \"important\");\n } catch {\n // A patched CSSOM; the box may look wrong but the screenshot survives.\n }\n }\n };\n\n style(container, {\n position: \"absolute\",\n left: \"0\",\n top: \"0\",\n width: \"0\",\n height: \"0\",\n margin: \"0\",\n padding: \"0\",\n border: \"0\",\n \"pointer-events\": \"none\",\n // Above anything the page itself can stack.\n \"z-index\": \"2147483647\",\n });\n\n // The container goes in empty and is measured, so every box below can be\n // positioned relative to it. Absolute coordinates would be wrong the moment\n // the page gives <body> a `position` or a `transform` of its own, which is\n // exactly the kind of page worth auditing.\n doc.body.appendChild(container);\n let originLeft = 0;\n let originTop = 0;\n try {\n const origin = container.getBoundingClientRect();\n originLeft = origin.left;\n originTop = origin.top;\n } catch {\n // No rect to correct against; boxes land in document coordinates.\n }\n\n for (const item of options.items) {\n let rect: { left: number; top: number; width: number; height: number } | null = null;\n if (item.box) {\n // Already measured, in viewport pixels — the same space as\n // getBoundingClientRect, so it corrects against the origin the same way.\n rect = { left: item.box.x, top: item.box.y, width: item.box.width, height: item.box.height };\n } else {\n let element: any = null;\n try {\n const matches = doc.querySelectorAll(item.selector);\n element = matches[item.match_index] ?? matches[0] ?? null;\n } catch {\n element = null;\n }\n rect = element && element.getBoundingClientRect ? element.getBoundingClientRect() : null;\n }\n if (!rect || rect.width <= 0 || rect.height <= 0) {\n missing.push(item.selector);\n continue;\n }\n\n const left = rect.left - originLeft;\n const top = rect.top - originTop;\n const box = doc.createElement(\"div\");\n style(box, {\n position: \"absolute\",\n // Laid out against the container, which sits at the document origin —\n // so one full-page screenshot catches every box, including the ones\n // below the fold.\n left: `${Math.round(left)}px`,\n top: `${Math.round(top)}px`,\n width: `${Math.round(rect.width)}px`,\n height: `${Math.round(rect.height)}px`,\n \"box-sizing\": \"border-box\",\n border: `3px solid ${item.colour}`,\n \"border-radius\": \"3px\",\n // A wash rather than a fill: what is under the box is the thing being\n // reported on, and it has to stay readable.\n \"background-color\": item.wash,\n \"box-shadow\": \"0 0 0 2px rgba(255, 255, 255, 0.85)\",\n \"pointer-events\": \"none\",\n });\n\n if (item.label !== \"\") {\n const tag = doc.createElement(\"div\");\n tag.textContent = item.label;\n style(tag, {\n position: \"absolute\",\n left: \"-3px\",\n // Above the box, unless that would fall off the top of the document.\n top: top >= 20 ? \"-20px\" : `${Math.round(rect.height)}px`,\n padding: \"1px 6px\",\n \"background-color\": item.colour,\n color: \"#ffffff\",\n font: \"700 12px/16px ui-monospace, SFMono-Regular, Menlo, monospace\",\n \"white-space\": \"nowrap\",\n \"border-radius\": \"3px\",\n \"pointer-events\": \"none\",\n });\n box.appendChild(tag);\n }\n\n container.appendChild(box);\n drawn.push(item.selector);\n }\n\n return { drawn, missing };\n}\n"]}

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

@@ -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 ADDED Viewed

@@ -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