vagejs 0.0.0-stage → 0.2.0

package/dist/checks/check.js

@@ -0,0 +1,434 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "node-html-parser";
+import { createBuildLoader } from "../core/loader.js";
+import { listedPages, renderSite } from "../core/site.js";
+import { externalHost, hiddenReason, isEmptyLink, LINK_LOCK, linkTarget, outboundHosts, readLinkLock, spamHits } from "./integrity.js";
+const DOCS = {
+    title: "https://developers.google.com/search/docs/appearance/title-link",
+    description: "https://developers.google.com/search/docs/appearance/snippet",
+    canonical: "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls",
+    structuredData: "https://developers.google.com/search/docs/appearance/structured-data/sd-policies",
+    article: "https://developers.google.com/search/docs/appearance/structured-data/article",
+    imgAlt: "https://www.w3.org/WAI/tutorials/images/",
+    lang: "https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html",
+    linkPurpose: "https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html",
+    robots: "https://developers.google.com/search/docs/crawling-indexing/robots/intro",
+    yamlFlow: "https://yaml.org/spec/1.2.2/#74-flow-collection-styles",
+};
+/** Paths of frontmatter values that came out empty (null), e.g. "faq.items[3].Claude and other AI search?". */
+export function emptyValues(value, at = "") {
+    if (value === null)
+        return [at || "(frontmatter)"];
+    if (Array.isArray(value))
+        return value.flatMap((v, i) => emptyValues(v, `${at}[${i}]`));
+    if (typeof value === "object" && value !== undefined) {
+        return Object.entries(value).flatMap(([k, v]) => emptyValues(v, at ? `${at}.${k}` : k));
+    }
+    return [];
+}
+/**
+ * Static checks on the rendered site (nothing is written to disk).
+ * Passing checks mean the output is technically sound; they do not guarantee
+ * indexing, rankings, rich results or AI citations.
+ */
+export async function check(root, options = {}) {
+    root = path.resolve(root);
+    const loader = await createBuildLoader(root);
+    try {
+        const model = await renderSite(root, loader.load, { collectErrors: true });
+        const findings = checkSite(root, model);
+        const errors = findings.filter((f) => f.severity === "error").length;
+        const warnings = findings.length - errors;
+        return {
+            ok: errors === 0 && (!options.strict || warnings === 0),
+            errors,
+            warnings,
+            pagesChecked: model.pages.length + (model.notFound ? 1 : 0) + model.pageErrors.length,
+            findings,
+        };
+    }
+    finally {
+        await loader.close();
+    }
+}
+export function checkSite(root, model) {
+    const findings = model.warnings.map((message) => ({ rule: "config", severity: "warning", message }));
+    for (const e of model.pageErrors)
+        findings.push({ rule: "page-error", severity: "error", message: e.message, source: e.source });
+    const outputs = outputPaths(root, model);
+    // Pages that failed to render are already reported; links to them aren't broken links on top of that.
+    for (const e of model.pageErrors)
+        if (e.route)
+            outputs.add(`${e.route}index.html`);
+    const drafts = new Set(model.draftRoutes);
+    const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
+    for (const page of pages) {
+        const add = (f) => findings.push({ ...f, page: page.route, source: page.source });
+        checkPage(page, parse(page.html), model, outputs, drafts, add);
+    }
+    findings.push(...checkDuplicates(listedPages(model)));
+    findings.push(...checkRobots(model));
+    findings.push(...checkRedirectTargets(model, outputs));
+    findings.push(...checkOutboundLinks(root, model));
+    return findings;
+}
+function checkPage(page, doc, model, outputs, drafts, add) {
+    const indexable = !page.meta.noindex;
+    if (model.site.security.spamPatterns) {
+        const text = `${doc.querySelector("body")?.text ?? ""} ${doc.querySelectorAll("a[href]").map((a) => a.getAttribute("href")).join(" ")}`;
+        const hits = spamHits(text);
+        if (hits.length) {
+            add({
+                rule: "spam-pattern",
+                severity: "warning",
+                message: `Page contains words common in injected spam (${hits.join(", ")}). If you didn't write them, check this page's history. Turn off with security.spamPatterns: false.`,
+            });
+        }
+    }
+    for (const key of emptyValues(page.frontmatter)) {
+        add({
+            rule: "frontmatter-empty",
+            severity: "warning",
+            message: `Frontmatter "${key}" has no value. If you meant to write text there, check for a missing value; inside { } a comma or colon splits the text, so wrap it in quotes.`,
+            docs: DOCS.yamlFlow,
+        });
+    }
+    if (!doc.querySelector("html")?.getAttribute("lang")) {
+        add({ rule: "html-lang", severity: "error", message: "<html> has no lang attribute.", docs: DOCS.lang });
+    }
+    const titles = doc.querySelectorAll("title");
+    if (titles.length !== 1 || !titles[0].text.trim()) {
+        add({ rule: "title", severity: "error", message: `Expected exactly one non-empty <title>, found ${titles.length}.`, docs: DOCS.title });
+    }
+    if (indexable && !doc.querySelector('meta[name="description"]')?.getAttribute("content")) {
+        add({
+            rule: "meta-description",
+            severity: "warning",
+            message: "No meta description. Add `description` to the frontmatter or site config.",
+            docs: DOCS.description,
+        });
+    }
+    if (!doc.querySelector("h1")) {
+        add({ rule: "h1", severity: "warning", message: "Page has no <h1> heading." });
+    }
+    for (const img of doc.querySelectorAll("img")) {
+        const src = img.getAttribute("src") ?? "";
+        if (img.getAttribute("alt") === undefined) {
+            add({ rule: "img-alt", severity: "error", message: `<img src="${src}"> has no alt attribute (use alt="" for decorative images).`, docs: DOCS.imgAlt });
+        }
+        if (!img.getAttribute("width") || !img.getAttribute("height")) {
+            add({ rule: "img-dimensions", severity: "warning", message: `<img src="${src}"> has no width/height; this can cause layout shift.` });
+        }
+    }
+    for (const el of doc.querySelectorAll("[href], [src], [action], [formaction]")) {
+        for (const attr of ["href", "src", "action", "formaction"]) {
+            const value = el.getAttribute(attr);
+            if (value && /^\s*(javascript|vbscript|data:text\/html)/i.test(value.replace(/[\u0000-\u0020]/g, ""))) {
+                add({ rule: "unsafe-url", severity: "error", message: `<${el.tagName.toLowerCase()} ${attr}="${value.slice(0, 60)}"> uses a script URL; this runs code on your site.` });
+            }
+        }
+    }
+    const site = model.site;
+    if (site.deploy.target === "cloudflare-pages" && site.security.headers && site.security.csp === "enforce") {
+        for (const el of doc.querySelectorAll("*")) {
+            const handler = Object.keys(el.attributes).find((a) => /^on[a-z]+$/i.test(a));
+            if (handler) {
+                add({
+                    rule: "csp-inline-handler",
+                    severity: "warning",
+                    message: `<${el.tagName.toLowerCase()} ${handler}="…"> is an inline event handler; the Content Security Policy blocks it. Use addEventListener in a script file.`,
+                });
+            }
+        }
+    }
+    for (const a of doc.querySelectorAll("a[href]")) {
+        const href = a.getAttribute("href");
+        checkHiddenLink(a, href, model, add);
+        if (!a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])")) {
+            add({ rule: "link-text", severity: "warning", message: `Link to "${href}" has no accessible text.`, docs: DOCS.linkPurpose });
+        }
+        const target = internalPath(href, page.route, model.site.site);
+        if (target === undefined)
+            continue;
+        if (target === MALFORMED) {
+            add({ rule: "link-broken", severity: "error", message: `Link to "${href}" is a malformed URL.` });
+            continue;
+        }
+        const resolved = resolveOutput(target, outputs);
+        if (resolved === "missing") {
+            const draft = drafts.has(target.endsWith("/") ? target : `${target}/`);
+            add({
+                rule: "link-broken",
+                severity: "error",
+                message: draft ? `Link to "${href}" points to a draft page, which is not published.` : `Link to "${href}" does not match any page or file.`,
+            });
+        }
+        else if (resolved === "needs-slash") {
+            add({ rule: "link-trailing-slash", severity: "warning", message: `Link to "${href}" redirects; use "${target}/".` });
+        }
+    }
+    // SVG links (a xlink:href) aren't in the loop above; they get the hidden-link check too.
+    for (const a of doc.querySelectorAll("a")) {
+        if (!a.hasAttribute("href") && a.getAttribute("xlink:href"))
+            checkHiddenLink(a, linkTarget(a), model, add);
+    }
+    for (const [selector, attr] of [
+        ["img[src]", "src"],
+        ["script[src]", "src"],
+        ["link[href]:not([rel=canonical]):not([rel=alternate])", "href"],
+    ]) {
+        for (const el of doc.querySelectorAll(selector)) {
+            const value = el.getAttribute(attr);
+            const target = internalPath(value, page.route, model.site.site);
+            if (target !== undefined && (target === MALFORMED || resolveOutput(target, outputs) === "missing")) {
+                add({ rule: "asset-missing", severity: "error", message: `<${el.tagName.toLowerCase()} ${attr}="${value}"> does not exist in the build output.` });
+            }
+        }
+    }
+    const canonicals = doc.querySelectorAll('link[rel="canonical"]');
+    if (canonicals.length > 1) {
+        add({ rule: "canonical", severity: "error", message: `Found ${canonicals.length} canonical links; use one.`, docs: DOCS.canonical });
+    }
+    for (const link of canonicals) {
+        const href = link.getAttribute("href") ?? "";
+        if (!/^https?:\/\//.test(href)) {
+            add({ rule: "canonical", severity: "error", message: `Canonical "${href}" is not an absolute URL.`, docs: DOCS.canonical });
+            continue;
+        }
+        const target = internalPath(href, page.route, model.site.site);
+        if (target === undefined) {
+            add({ rule: "canonical", severity: "warning", message: `Canonical "${href}" points to another site; search engines may credit that site instead of yours.`, docs: DOCS.canonical });
+        }
+        else if (target === MALFORMED || resolveOutput(target, outputs) !== "ok") {
+            add({ rule: "canonical", severity: "error", message: `Canonical "${href}" does not point to a published page.`, docs: DOCS.canonical });
+        }
+    }
+    for (const script of doc.querySelectorAll('script[type="application/ld+json"]')) {
+        checkJsonLd(script.rawText, add);
+    }
+    checkAnalytics(page.html, doc, model, add);
+}
+function checkAnalytics(html, doc, model, add) {
+    const loaders = html.match(/googletagmanager\.com\/(gtag\/js|gtm\.js)/g) ?? [];
+    if (loaders.length > 1) {
+        add({
+            rule: "analytics-duplicate",
+            severity: "error",
+            message: `Page loads Google tags ${loaders.length} times (${loaders.join(", ")}); this double-counts. Remove the layout's tag or the integrations config.`,
+        });
+    }
+    const { ga4, gtm, plausible } = model.site.integrations;
+    // Each provider that receives events must declare them.
+    const receivers = [
+        ga4?.measurementId && { name: "ga4", events: ga4.events },
+        gtm?.containerId && { name: "gtm", events: gtm.events },
+        plausible && { name: "plausible", events: plausible.events },
+    ].filter((r) => Boolean(r));
+    for (const el of doc.querySelectorAll("[data-vage-event]")) {
+        const name = el.getAttribute("data-vage-event");
+        if (!receivers.length) {
+            add({ rule: "analytics-event", severity: "warning", message: `data-vage-event="${name}" is used but no analytics integration is configured.` });
+            continue;
+        }
+        const missing = receivers.filter((r) => !r.events[name]);
+        if (missing.length) {
+            add({
+                rule: "analytics-event",
+                severity: "error",
+                message: `Event "${name}" is not declared. Add it to ${missing.map((r) => `integrations.${r.name}.events`).join(" and ")} in vage.config.ts.`,
+            });
+            continue;
+        }
+        const params = Object.keys(el.attributes)
+            .filter((a) => a.startsWith("data-vage-param-"))
+            .map((a) => a.slice("data-vage-param-".length).replace(/-/g, "_"));
+        for (const param of params.filter((p) => receivers.some((r) => !r.events[name].params.includes(p)))) {
+            add({ rule: "analytics-event", severity: "error", message: `Event "${name}" has undeclared parameter "${param}". Declare it in its params list.` });
+        }
+    }
+}
+function checkJsonLd(raw, add) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        add({ rule: "jsonld", severity: "error", message: `JSON-LD is not valid JSON: ${err.message}`, docs: DOCS.structuredData });
+        return;
+    }
+    const root = data;
+    if (typeof root["@context"] !== "string" || !/^https?:\/\/schema\.org\/?$/.test(root["@context"])) {
+        add({ rule: "jsonld", severity: "error", message: 'JSON-LD needs "@context": "https://schema.org".', docs: DOCS.structuredData });
+    }
+    const items = (Array.isArray(root["@graph"]) ? root["@graph"] : [root]);
+    for (const item of items) {
+        if (typeof item["@type"] !== "string") {
+            add({ rule: "jsonld", severity: "error", message: 'A JSON-LD item has no "@type".', docs: DOCS.structuredData });
+        }
+        else if (item["@type"] === "Article") {
+            const missing = ["author", "datePublished", "image"].filter((k) => item[k] === undefined);
+            if (missing.length) {
+                add({
+                    rule: "jsonld-article",
+                    severity: "warning",
+                    message: `Article JSON-LD lacks properties Google recommends: ${missing.join(", ")}. Add them to the frontmatter only if they are true.`,
+                    docs: DOCS.article,
+                });
+            }
+        }
+    }
+}
+function checkDuplicates(pages) {
+    const findings = [];
+    for (const [rule, get] of [
+        ["title-duplicate", (p) => p.frontmatter.title],
+        ["description-duplicate", (p) => p.frontmatter.description],
+    ]) {
+        const seen = new Map();
+        for (const p of pages) {
+            const value = get(p);
+            if (value)
+                seen.set(value, [...(seen.get(value) ?? []), p.route]);
+        }
+        for (const [value, routes] of seen) {
+            if (routes.length > 1) {
+                findings.push({ rule, severity: "warning", message: `"${value}" is used by ${routes.join(", ")}. Make each page's ${rule.split("-")[0]} unique.` });
+            }
+        }
+    }
+    return findings;
+}
+/** Links visitors can't see but search engines can: the signature of injected spam. */
+function checkHiddenLink(a, href, model, add) {
+    const external = externalHost(href, model.site.site) !== undefined;
+    const hidden = hiddenReason(a) ?? (external && isEmptyLink(a) ? { reason: "empty (no text or image)", strength: "strong" } : undefined);
+    if (!hidden)
+        return;
+    add({
+        rule: "link-hidden",
+        severity: external && hidden.strength === "strong" ? "error" : "warning",
+        message: `Link to "${href}" is ${hidden.reason}: visitors can't see it, but search engines can. Hidden links are a common sign of injected spam. Remove it, or show it.`,
+    });
+}
+/**
+ * Outbound link guard: with security.outboundLinks "lock", every external domain must be
+ * listed in links.lock.json. A domain nobody approved is how injected spam usually shows up.
+ */
+function checkOutboundLinks(root, model) {
+    if (model.site.security.outboundLinks === "off")
+        return [];
+    const hosts = outboundHosts(model);
+    const lock = readLinkLock(root);
+    if (!lock && model.site.security.outboundLinks === "require") {
+        return [{ rule: "links-lock-missing", severity: "error", message: `${LINK_LOCK} is missing, but security.outboundLinks is "require". Restore it from git, or have the site owner recreate it with "npx vage links approve --all" after reviewing "npx vage links".` }];
+    }
+    if (!lock) {
+        return hosts.size
+            ? [{ rule: "links-lock-missing", severity: "warning", message: `The site links to ${hosts.size} external domain(s) and has no ${LINK_LOCK}. The site owner should review them with "npx vage links" and approve them with "npx vage links approve --all"; after that, links to any new domain fail the check.` }]
+            : [];
+    }
+    const approved = new Set(lock.domains);
+    const findings = [];
+    for (const [host, pages] of hosts) {
+        if (approved.has(host))
+            continue;
+        const where = pages.map((p) => p.route);
+        findings.push({
+            rule: "link-unapproved",
+            severity: "error",
+            message: `Links to ${host} (on ${where.slice(0, 3).join(", ")}${where.length > 3 ? ` and ${where.length - 3} more` : ""}) aren't approved in ${LINK_LOCK}. If the site owner added them on purpose, they approve with "npx vage links approve ${host}". Otherwise remove them: unapproved links are how injected spam usually shows up.`,
+            page: pages[0].route,
+            source: pages[0].source,
+        });
+    }
+    return findings;
+}
+/** Redirects to a page on this site must land on something that exists. */
+function checkRedirectTargets(model, outputs) {
+    const findings = [];
+    for (const r of model.redirects) {
+        const target = internalPath(r.to, "/", model.site.site);
+        if (target === undefined)
+            continue;
+        if (target === MALFORMED || resolveOutput(target, outputs) === "missing") {
+            findings.push({ rule: "redirect-target", severity: "error", message: `Redirect from "${r.from}" points to "${r.to}", which isn't a page or file on this site.`, source: "vage.config.ts" });
+        }
+    }
+    return findings;
+}
+function checkRobots(model) {
+    const robots = model.files.get("robots.txt");
+    if (!robots)
+        return [];
+    // Find the "*" group and look for a blanket Disallow.
+    const groups = robots.split(/\n\s*\n/);
+    const star = groups.find((g) => /^User-agent:\s*\*\s*$/im.test(g));
+    if (star && /^Disallow:\s*\/\s*$/im.test(star) && model.pages.some((p) => !p.meta.noindex)) {
+        return [
+            {
+                rule: "robots-blocks-all",
+                severity: "warning",
+                message: "robots.txt disallows all crawlers (User-agent: * / Disallow: /) while pages are indexable.",
+                source: "robots.txt",
+                docs: DOCS.robots,
+            },
+        ];
+    }
+    return [];
+}
+/** Every path the build would write, as "/path" strings. */
+function outputPaths(root, model) {
+    const out = new Set();
+    for (const p of model.pages)
+        out.add(`/${p.outFile}`);
+    if (model.notFound)
+        out.add("/404.html");
+    for (const r of model.redirects)
+        out.add(`/${r.outFile}`);
+    for (const name of model.files.keys())
+        out.add(`/${name}`);
+    const walk = (dir, prefix) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), `${prefix}/${e.name}`);
+            else
+                out.add(`${prefix}/${e.name}`);
+        }
+    };
+    const publicDir = path.join(root, "public");
+    if (fs.existsSync(publicDir))
+        walk(publicDir, "");
+    return out;
+}
+const MALFORMED = "\u0000malformed";
+/** Returns the site-relative path for internal URLs, undefined for external ones, MALFORMED when undecodable. */
+function internalPath(href, base, site) {
+    if (/^(mailto:|tel:|javascript:|vbscript:|data:|#)/i.test(href.trim()) || href === "")
+        return undefined;
+    let url;
+    try {
+        url = new URL(href, `http://internal.invalid${base}`);
+    }
+    catch {
+        return MALFORMED;
+    }
+    const isInternal = url.host === "internal.invalid" || (site !== undefined && url.origin === site);
+    if (!isInternal)
+        return undefined;
+    try {
+        return decodeURIComponent(url.pathname);
+    }
+    catch {
+        return MALFORMED;
+    }
+}
+function resolveOutput(target, outputs) {
+    if (target.endsWith("/"))
+        return outputs.has(`${target}index.html`) ? "ok" : "missing";
+    if (outputs.has(target))
+        return "ok";
+    if (!path.posix.extname(target) && outputs.has(`${target}/index.html`))
+        return "needs-slash";
+    return "missing";
+}

package/dist/checks/integrity.d.ts

@@ -0,0 +1,36 @@
+import { type HTMLElement } from "node-html-parser";
+import type { SiteModel } from "../core/site.js";
+/**
+ * Defenses against injected spam (the classic hacked-site problem): links hidden with
+ * CSS, outbound links nobody approved, and common spam vocabulary. These run in
+ * `vage check` on the final HTML, so they cover page content and layouts alike.
+ */
+export declare const LINK_LOCK = "links.lock.json";
+export interface Hidden {
+    reason: string;
+    /** "strong": a CSS/SVG trick with no legitimate use around a link. "soft": hidden by a mechanism sites also use for menus (hidden, closed <details>). */
+    strength: "strong" | "soft";
+}
+/** Why this element (or an ancestor) is hidden from people, if it is. Only inline signals; stylesheets aren't evaluated. */
+export declare function hiddenReason(el: HTMLElement): Hidden | undefined;
+/** A link with nothing a visitor can see or a screen reader can announce. */
+export declare function isEmptyLink(a: HTMLElement): boolean;
+/** href of <a>/<area>, including SVG's xlink:href. */
+export declare function linkTarget(a: HTMLElement): string | undefined;
+/** Normalized host of an external http(s) link ("www." dropped), or undefined for internal/other links. */
+export declare function externalHost(href: string, site: string | undefined): string | undefined;
+/** Lowercase, punycode, no "www.", no trailing dot: one spelling per host. */
+export declare function normalizeHost(host: string): string;
+/** Every external host the built site links to, with the pages that link there. */
+export declare function outboundHosts(model: SiteModel): Map<string, {
+    route: string;
+    source: string;
+}[]>;
+export interface LinkLock {
+    domains: string[];
+}
+export declare function readLinkLock(root: string): LinkLock | undefined;
+export declare function writeLinkLock(root: string, domains: Iterable<string>): void;
+/** Words that rarely appear on legitimate business sites but are staples of injected spam. Warnings only. */
+export declare const SPAM_PATTERNS: [RegExp, string][];
+export declare function spamHits(text: string): string[];

package/dist/checks/integrity.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "node-html-parser";
+import { VageError } from "../core/errors.js";
+/**
+ * Defenses against injected spam (the classic hacked-site problem): links hidden with
+ * CSS, outbound links nobody approved, and common spam vocabulary. These run in
+ * `vage check` on the final HTML, so they cover page content and layouts alike.
+ */
+export const LINK_LOCK = "links.lock.json";
+// ---------------------------------------------------------------- hidden links
+const HIDING_STYLES = [
+    [/display\s*:\s*none/i, "display:none"],
+    [/visibility\s*:\s*(hidden|collapse)/i, "visibility:hidden"],
+    [/opacity\s*:\s*0(\.0+)?\s*(;|$|!)/i, "opacity:0"],
+    [/font-size\s*:\s*0(\.0+)?(px|em|rem|%)?\s*(;|$|!)/i, "font-size:0"],
+    [/(^|;|\s)(width|height|max-width|max-height)\s*:\s*0(px)?\s*(;|$|!)/i, "zero size"],
+    [/(^|;|\s)(left|top|right|bottom|margin-left|margin-top)\s*:\s*-\s*\d{3,}/i, "positioned off-screen"],
+    [/text-indent\s*:\s*-\s*\d{3,}/i, "text pushed off-screen"],
+    [/clip\s*:\s*rect\(\s*0/i, "clipped away"],
+    [/clip-path\s*:\s*inset\(\s*(50%|100%)/i, "clipped away"],
+];
+/** Why this element (or an ancestor) is hidden from people, if it is. Only inline signals; stylesheets aren't evaluated. */
+export function hiddenReason(el) {
+    for (let node = el; node && node.tagName; node = node.parentNode) {
+        const tag = node.tagName.toLowerCase();
+        const where = node === el ? "" : "inside ";
+        const style = node.getAttribute?.("style");
+        if (style) {
+            const hit = HIDING_STYLES.find(([re]) => re.test(style));
+            if (hit)
+                return { reason: `${where ? "inside an element " : ""}hidden with ${hit[1]}`, strength: "strong" };
+        }
+        if (node.getAttribute?.("aria-hidden") === "true")
+            return { reason: `${where}aria-hidden="true"`, strength: "strong" };
+        if (tag === "svg" && (/^0(px)?$/.test(node.getAttribute("width") ?? "") || /^0(px)?$/.test(node.getAttribute("height") ?? ""))) {
+            return { reason: "inside a zero-size <svg>", strength: "strong" };
+        }
+        if (node.hasAttribute?.("hidden"))
+            return { reason: `inside a hidden <${tag}>`, strength: "soft" };
+        if (tag === "details" && node !== el && !node.hasAttribute("open") && !el.closest?.("summary")) {
+            return { reason: "inside a closed <details>", strength: "soft" };
+        }
+    }
+    return undefined;
+}
+/** A link with nothing a visitor can see or a screen reader can announce. */
+export function isEmptyLink(a) {
+    return !a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])");
+}
+/** href of <a>/<area>, including SVG's xlink:href. */
+export function linkTarget(a) {
+    return a.getAttribute("href") ?? a.getAttribute("xlink:href") ?? undefined;
+}
+// ---------------------------------------------------------------- outbound links
+/** Normalized host of an external http(s) link ("www." dropped), or undefined for internal/other links. */
+export function externalHost(href, site) {
+    let url;
+    try {
+        url = new URL(href.trim(), site ?? "https://site.invalid");
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return undefined;
+    const host = normalizeHost(url.hostname);
+    const own = site ? normalizeHost(new URL(site).hostname) : "site.invalid";
+    return host === own ? undefined : host;
+}
+/** Lowercase, punycode, no "www.", no trailing dot: one spelling per host. */
+export function normalizeHost(host) {
+    return host.toLowerCase().replace(/\.$/, "").replace(/^www\./, "");
+}
+/** Places in a page that send visitors or search engines elsewhere, beyond <a>: all go through the link lock. */
+const OTHER_TARGETS = [
+    ['link[rel="canonical"]', (el) => el.getAttribute("href")],
+    ['meta[property="og:url"]', (el) => el.getAttribute("content")],
+    ["meta[http-equiv]", (el) => (/^refresh$/i.test(el.getAttribute("http-equiv") ?? "") ? /url\s*=\s*['"]?([^'";]+)/i.exec(el.getAttribute("content") ?? "")?.[1] : undefined)],
+    ["iframe[src]", (el) => el.getAttribute("src")],
+    ["form[action]", (el) => el.getAttribute("action")],
+];
+/** Every external host the built site links to, with the pages that link there. */
+export function outboundHosts(model) {
+    const hosts = new Map();
+    const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
+    for (const page of pages) {
+        const seen = new Set();
+        const doc = parse(page.html);
+        const targets = [
+            ...doc.querySelectorAll("a, area").map(linkTarget),
+            ...OTHER_TARGETS.flatMap(([selector, read]) => doc.querySelectorAll(selector).map(read)),
+        ];
+        for (const target of targets) {
+            if (!target)
+                continue;
+            const host = externalHost(target, model.site.site);
+            if (!host || seen.has(host))
+                continue;
+            seen.add(host);
+            hosts.set(host, [...(hosts.get(host) ?? []), { route: page.route, source: page.source }]);
+        }
+    }
+    return new Map([...hosts].sort(([a], [b]) => a.localeCompare(b)));
+}
+export function readLinkLock(root) {
+    const file = path.join(root, LINK_LOCK);
+    if (!fs.existsSync(file))
+        return undefined;
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new VageError(`${LINK_LOCK} is not valid JSON: ${err.message}`, file);
+    }
+    const domains = data?.domains;
+    if (!Array.isArray(domains) || !domains.every((d) => typeof d === "string")) {
+        throw new VageError(`${LINK_LOCK} must look like { "domains": ["example.com"] }.`, file);
+    }
+    return { domains: domains.map(normalizeHost) };
+}
+export function writeLinkLock(root, domains) {
+    const sorted = [...new Set(domains)].sort();
+    const body = {
+        $comment: "External domains this site may link to. vage check fails on links to any other domain. Only the site owner approves new ones: npx vage links approve <domain>",
+        domains: sorted,
+    };
+    fs.writeFileSync(path.join(root, LINK_LOCK), `${JSON.stringify(body, null, 2)}\n`);
+}
+// ---------------------------------------------------------------- spam vocabulary
+/** Words that rarely appear on legitimate business sites but are staples of injected spam. Warnings only. */
+export const SPAM_PATTERNS = [
+    [/\b(online|best|free|top)\s+casinos?\b|\bcasino\s+(bonus|online|games?|sites?)\b/i, "casino"],
+    [/\b(viagra|cialis|levitra|kamagra)\b/i, "pharmacy spam"],
+    [/\bpayday\s+loans?\b/i, "payday loans"],
+    [/\breplica\s+(watches|handbags|bags|rolex)\b/i, "replica goods"],
+    [/\bescort\s+(girls|agency|agencies)\b/i, "escort ads"],
+    [/\bporn\b|\bxxx\s+(videos?|porn|sex)\b/i, "adult content"],
+    [/\bbuy\s+(cheap\s+)?(followers|backlinks|likes)\b/i, "bought followers or backlinks"],
+    [/\bonline\s+slots\b|\bslot\s+gacor\b|\bjudi\s+online\b/i, "online gambling"],
+];
+export function spamHits(text) {
+    return [...new Set(SPAM_PATTERNS.filter(([re]) => re.test(text)).map(([, label]) => label))];
+}

package/dist/checks/links.d.ts

@@ -0,0 +1,18 @@
+import { readLinkLock, writeLinkLock } from "./integrity.js";
+export interface LinkStatus {
+    /** External domains the site links to now, with how many pages link there, and whether they're approved. */
+    domains: {
+        domain: string;
+        pages: string[];
+        approved: boolean;
+    }[];
+    /** Approved domains the site no longer links to. */
+    unused: string[];
+    hasLock: boolean;
+}
+export declare function linkStatus(root: string): Promise<LinkStatus>;
+/** "Bücher.DE." -> "xn--bcher-kva.de"; throws for anything that isn't a bare host (or IP). */
+export declare function parseHost(input: string): string;
+/** The lock file's domains after approving `add` (and, with `prune`, dropping unused ones). */
+export declare function nextLock(status: LinkStatus, current: string[], add: string[], prune: boolean): string[];
+export { readLinkLock, writeLinkLock };