@dogsbay/site-check 0.0.0-stage → 0.2.0-beta.116

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @dogsbay/site-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The site audit engine behind `dogsbay site check` (the Astro pipeline) and `dogsbay-ssg check`: rules over source pages, the whole corpus and built HTML, a runner, and text and JSON reports.
+
+```ts
+import { filterRules, formatText, registerSharedRules, reportExitCode, runAudit } from "@dogsbay/site-check";
+import { crawlDist, distFileReader } from "@dogsbay/site-check/node";
+
+registerSharedRules();
+const report = runAudit({
+  rules: filterRules({}),
+  pages, nav, config,
+  distFiles: crawlDist("dist"),
+  readFile: distFileReader("dist"),
+});
+console.log(formatText(report));
+process.exit(reportExitCode(report, false));
+```
+
+The main entry is Worker-safe (no `node:` imports) when bundled with the `browser` or `workerd` condition, which selects cheerio's browser build. An in-memory build passes `parseHtmlFile(path, html)` for each page it emits and a `readFile` over its output instead of the `./node` helpers.
+
+Design: [`docs-dev/site-check-architecture.md`](../../docs-dev/site-check-architecture.md).

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export * from "./types.js";
+export { registerRule, listRules, getRule, filterRules, _clearRegistry } from "./registry.js";
+export type { FilterOptions } from "./registry.js";
+export { runAudit, reportExitCode } from "./run.js";
+export type { RunAuditInputs } from "./run.js";
+export { formatJson } from "./output/json.js";
+export { formatText } from "./output/text.js";
+export type { FormatTextOptions } from "./output/text.js";
+export { toReport } from "./run.js";
+export { createAuditSession, slimPage } from "./session.js";
+export type { AuditSession, AuditSessionOptions } from "./session.js";
+export { parseHtmlFile } from "./parse.js";
+export { validateRefs } from "./lib/validate-refs.js";
+export { compareRelease, releasePage, releaseBaseline, normalizeRemoved, signature, similarity, treeText, MOVED_SIMILARITY, MIN_SHINGLES } from "./lib/release.js";
+export type { ReleasePage, ReleaseEntry, ReleaseStatus, CompareReleaseInput, ReleaseComparison } from "./lib/release.js";
+export { formatReleaseText, releaseRedirects, markWritten, releaseOpen, releaseExitCode, formatWriteSummary } from "./output/release.js";
+export { addRedirectsToConfig, redirectsBlock } from "./lib/config-redirects.js";
+export type { ConfigRedirect } from "./lib/config-redirects.js";
+export type { RefIssue, ValidateRefsOptions, ValidateRefsResult } from "./lib/validate-refs.js";
+export { registerSeoRules, _resetSeoRegistration } from "./rules/seo/index.js";
+export { registerStructureRules, _resetStructureRegistration } from "./rules/structure/index.js";
+export { registerFrontmatterRules, _resetFrontmatterRegistration } from "./rules/frontmatter/index.js";
+/** Register every shared rule (SEO, structure and frontmatter). Idempotent. */
+export declare function registerSharedRules(): void;

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @dogsbay/site-check — the site audit engine shared by the Astro
+ * pipeline (`dogsbay site check`) and dogsbay-ssg (`dogsbay-ssg check`).
+ *
+ * This entry is Worker-safe: no `node:` imports. Reading a dist folder
+ * and collecting assets from disk are in `@dogsbay/site-check/node`.
+ */
+import { registerSeoRules } from "./rules/seo/index.js";
+import { registerStructureRules } from "./rules/structure/index.js";
+import { registerFrontmatterRules } from "./rules/frontmatter/index.js";
+export * from "./types.js";
+export { registerRule, listRules, getRule, filterRules, _clearRegistry } from "./registry.js";
+export { runAudit, reportExitCode } from "./run.js";
+export { formatJson } from "./output/json.js";
+export { formatText } from "./output/text.js";
+export { toReport } from "./run.js";
+export { createAuditSession, slimPage } from "./session.js";
+export { parseHtmlFile } from "./parse.js";
+export { validateRefs } from "./lib/validate-refs.js";
+export { compareRelease, releasePage, releaseBaseline, normalizeRemoved, signature, similarity, treeText, MOVED_SIMILARITY, MIN_SHINGLES } from "./lib/release.js";
+export { formatReleaseText, releaseRedirects, markWritten, releaseOpen, releaseExitCode, formatWriteSummary } from "./output/release.js";
+export { addRedirectsToConfig, redirectsBlock } from "./lib/config-redirects.js";
+export { registerSeoRules, _resetSeoRegistration } from "./rules/seo/index.js";
+export { registerStructureRules, _resetStructureRegistration } from "./rules/structure/index.js";
+export { registerFrontmatterRules, _resetFrontmatterRegistration } from "./rules/frontmatter/index.js";
+/** Register every shared rule (SEO, structure and frontmatter). Idempotent. */
+export function registerSharedRules() {
+    registerSeoRules();
+    registerStructureRules();
+    registerFrontmatterRules();
+}

package/dist/lib/config-redirects.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Add redirects to a `dogsbay.config.yml` as text, keeping its comments and
+ * layout: new `"/from": "/to"` lines go at the end of the top-level
+ * `redirects:` block, or in a new block at the end of the file. Both
+ * pipelines read that block the same way (site paths, no base path).
+ *
+ * A `redirects:` written in flow style (`redirects: { … }`) is not edited:
+ * the caller gets an error and prints the lines to paste instead.
+ */
+export interface ConfigRedirect {
+    /** Site paths without a leading slash or base path: `latest/guide/old`. */
+    from: string;
+    to: string;
+}
+export declare function addRedirectsToConfig(text: string, redirects: ConfigRedirect[], 
+/** Sources the config already redirects, as written (`/latest/guide/old`); these are skipped. */
+existing?: Iterable<string>): {
+    text: string;
+    added: ConfigRedirect[];
+};
+/** A block list of the same redirects, to print for pasting. */
+export declare function redirectsBlock(redirects: ConfigRedirect[]): string;

package/dist/lib/config-redirects.js

@@ -0,0 +1,62 @@
+export function addRedirectsToConfig(text, redirects, 
+/** Sources the config already redirects, as written (`/latest/guide/old`); these are skipped. */
+existing = []) {
+    const have = new Set([...existing].map(norm));
+    const added = [];
+    for (const r of redirects) {
+        if (have.has(norm(r.from)))
+            continue;
+        have.add(norm(r.from));
+        added.push(r);
+    }
+    if (!added.length)
+        return { text, added };
+    // Written back with the file's own line ending.
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lines = text.split(/\r?\n/);
+    const key = /^(["']?)redirects\1\s*:/;
+    const at = lines.findIndex((l) => key.test(l));
+    const entries = added.map((r) => entry(r));
+    if (at < 0) {
+        const body = text === "" || /\r?\n$/.test(text) ? text : text + eol;
+        return { text: body + ["redirects:", ...entries.map((e) => "  " + e)].join(eol) + eol, added };
+    }
+    const value = lines[at].replace(key, "").replace(/\s+#.*$/, "").trim();
+    // An empty value (`redirects:`, `~`, `null`, `{}`) becomes a block; any other value on the line is not edited.
+    if (value === "~" || value === "null" || value === "{}") {
+        lines.splice(at, 1, "redirects:", ...entries.map((e) => "  " + e));
+        return { text: lines.join(eol), added };
+    }
+    if (value !== "") {
+        throw new Error("redirects: is not a block mapping (one entry per line), so it is not edited; add these lines to it by hand");
+    }
+    // The block runs to the next line that is not indented, blank or a comment.
+    let indent = "  ";
+    let last = at;
+    for (let i = at + 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (l.trim() === "" || /^\s+#/.test(l))
+            continue;
+        const m = /^(\s+)\S/.exec(l);
+        if (!m)
+            break;
+        if (last === at)
+            indent = m[1];
+        last = i;
+    }
+    lines.splice(last + 1, 0, ...entries.map((e) => indent + e));
+    return { text: lines.join(eol), added };
+}
+/** A block list of the same redirects, to print for pasting. */
+export function redirectsBlock(redirects) {
+    return "redirects:\n" + redirects.map((r) => `  ${entry(r)}\n`).join("");
+}
+function entry(r) {
+    return `${quote("/" + r.from.replace(/^\/+/, ""))}: ${quote("/" + r.to.replace(/^\/+/, ""))}`;
+}
+function quote(s) {
+    return /^[\w/.\-~]+$/.test(s) ? s : JSON.stringify(s);
+}
+function norm(p) {
+    return p.replace(/^\/+|\/+$/g, "").replace(/\.html$/, "");
+}

package/dist/lib/page.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Small helpers shared by the streamed session and the rules.
+ */
+import type { ExportPage } from "@dogsbay/types";
+/** The title a page is shown with: front matter first, then the one the build took from the first H1. */
+export declare function titleOf(page: ExportPage): string;
+/**
+ * A standalone copy of `s`. V8 keeps a slice or a regex match as a view on
+ * its parent string, so a kept href would otherwise pin its whole page.
+ */
+export declare function flat(s: string): string;
+/**
+ * One key per page, whatever form names it: a file path (`guide/x.html`,
+ * `guide/x/index.html`) or a URL (`https://site/base/guide/x/`,
+ * `/guide/x.html`, `…/guide/x` with pretty links). Origin, the site URL's
+ * path, query and hash go; `index.html`, `.html` and slashes at the ends are
+ * dropped, so the forms meet at `guide/x`.
+ */
+export declare function pageKey(pathOrUrl: string, urlBase?: string): string;

package/dist/lib/page.js

@@ -0,0 +1,34 @@
+/** The title a page is shown with: front matter first, then the one the build took from the first H1. */
+export function titleOf(page) {
+    const fm = page.frontmatter?.["title"];
+    return (typeof fm === "string" && fm.trim() ? fm : page.title ?? "").trim();
+}
+/**
+ * A standalone copy of `s`. V8 keeps a slice or a regex match as a view on
+ * its parent string, so a kept href would otherwise pin its whole page.
+ */
+export function flat(s) {
+    return JSON.parse(JSON.stringify(s));
+}
+/**
+ * One key per page, whatever form names it: a file path (`guide/x.html`,
+ * `guide/x/index.html`) or a URL (`https://site/base/guide/x/`,
+ * `/guide/x.html`, `…/guide/x` with pretty links). Origin, the site URL's
+ * path, query and hash go; `index.html`, `.html` and slashes at the ends are
+ * dropped, so the forms meet at `guide/x`.
+ */
+export function pageKey(pathOrUrl, urlBase = "") {
+    let p = pathOrUrl.replace(/[?#].*$/, "");
+    const m = /^[a-z][a-z0-9+.-]*:\/\/[^/]*(.*)$/i.exec(p) ?? /^\/\/[^/]*(.*)$/.exec(p);
+    if (m)
+        p = m[1];
+    p = p.replace(/^\/+/, "");
+    const base = urlBase.replace(/^\/+|\/+$/g, "");
+    if (m && base && (p === base || p.startsWith(base + "/")))
+        p = p.slice(base.length);
+    return p
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/(^|\/)index\.html$/, "")
+        .replace(/\.html$/, "")
+        .replace(/\/+$/, "");
+}

package/dist/lib/release.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What a release moved or removed: the pages of an older version that the
+ * default version no longer has at the same path, each classified as
+ * redirected, recorded as removed, probably moved (with the evidence) or
+ * gone. `dogsbay site release-diff` and `dogsbay-ssg release-diff` print it;
+ * the `structure/release-moves` rule reports the open ones.
+ *
+ * Pipeline-neutral: each pipeline passes its pages as `ReleasePage`s with
+ * paths inside their version (`guide/install`, `index` for the home page)
+ * and the paths its redirects cover. Worker-safe; the git rename signal is
+ * read by the Node adapter (`gitRenames` in `@dogsbay/site-check/node`) and
+ * passed in. See dogsbay-ssg plans/canonical-versions.md, step 3.
+ */
+import type { ExportPage, TreeNode } from "@dogsbay/types";
+/** One page of a version, reduced to what matching needs (small: kept for two versions only). */
+export interface ReleasePage {
+    /** Path inside the version: `guide/install`; `index` for the home page. */
+    path: string;
+    title: string;
+    /** Front matter `id:` (a stable id, such as a DITA topic id), when the page has one. */
+    id?: string;
+    /** The page's source file, relative to the project (reported by `structure/release-moves`). */
+    source?: string;
+    /** The page comes from a folder's index file (`admin/index.md`), so it is served as a folder: its redirect source ends in `/`. */
+    index?: boolean;
+    /** MinHash of the page's word shingles; see `similarity`. */
+    signature: number[];
+    /** How many shingles the signature was taken over; a short page's text is no evidence of a move. */
+    shingles: number;
+}
+export type ReleaseStatus = "redirected" | "removed-ok" | "moved" | "candidate" | "removed";
+export interface ReleaseEntry {
+    /** The page's path in the older version. */
+    path: string;
+    status: ReleaseStatus;
+    /** Where it went (`moved`, `candidate`) or where its redirect points (`redirected`). */
+    to?: string;
+    /** Why it is thought to have moved: `git rename`, `same id`, `same text, 84%`, `same title`, `same file name`. */
+    evidence?: string[];
+    /** The older page's source file, relative to the project, when the pipeline knows it. */
+    source?: string;
+    /** The older page was a folder's index file; see `ReleasePage.index`. */
+    index?: true;
+}
+export interface CompareReleaseInput {
+    /** The older version's pages. */
+    from: ReleasePage[];
+    /** The default version's pages. */
+    to: ReleasePage[];
+    /**
+     * Redirects in the default version, by source path inside the version. The
+     * target is a path inside the version, a site path with a leading slash
+     * when it is outside the version (`/other/x`), or a URL.
+     */
+    redirects?: Map<string, string>;
+    /** Paths recorded as removed on purpose (`versions[].removed` of the default version). */
+    removed?: string[];
+    /** Renames in the default version's source since the older release, from git (old path → new path). */
+    renames?: Map<string, string>;
+}
+/** Estimated text overlap from which a new page counts as the same page, moved. */
+export declare const MOVED_SIMILARITY = 0.6;
+/** Shingles both pages need for their text to count ("Coming soon" stubs all look alike). About a dozen words. */
+export declare const MIN_SHINGLES = 8;
+/**
+ * Classify every page of `from` that `to` does not have at the same path.
+ * Unchanged pages are left out. Order: `from`'s.
+ */
+export declare function compareRelease(input: CompareReleaseInput): ReleaseEntry[];
+/**
+ * A `removed:` entry as a page path: no slashes at the ends, no `.md`,
+ * `.markdown` or `.mdx`, `x/index` → `x`, and the home page `index`.
+ */
+export declare function normalizeRemoved(raw: string): string;
+/**
+ * A page as matching sees it. `path` is its path inside its version;
+ * `source` its source file relative to the project; `index` whether that
+ * file is a folder's index (other than the home page).
+ */
+export declare function releasePage(page: ExportPage, path: string, o?: {
+    source?: string;
+    index?: boolean;
+}): ReleasePage;
+/**
+ * MinHash over the text's 5-word shingles (lowercased words; a text shorter
+ * than one shingle is one shingle): for each of 64 seeded hashes, the
+ * smallest value over the shingles. Two signatures agree in a slot with the
+ * probability that the two shingle sets overlap (their Jaccard index).
+ */
+export declare function signature(text: string): number[];
+/** Estimated Jaccard index of two pages' shingle sets: the share of MinHash slots that agree. Empty pages match nothing. */
+export declare function similarity(a: number[], b: number[]): number;
+/** A page's text: inline text, HTML without its tags, and code, in document order. */
+export declare function treeText(nodes: TreeNode[]): string;
+/**
+ * The version a release is compared against: the first version after the
+ * default one in `versions` order (newest first) that is neither a
+ * pre-release nor `hidden` (the numbered twin of a `latest` alias, the same
+ * pages); with the snapshot routine, the previous release as published.
+ * `from` names one instead.
+ */
+export declare function releaseBaseline(versions: {
+    id: string;
+    prerelease?: boolean;
+    hidden?: boolean;
+}[], defaultVersion: string | undefined, from?: string): string | undefined;
+/** One comparison, as a pipeline hands it to the audit: the versions, the language, and the entries. */
+export interface ReleaseComparison {
+    /** The older version's id. */
+    from: string;
+    /** The default version's id. */
+    to: string;
+    locale?: string;
+    /** Site path prefix of each version's pages (`v3`, `en/v3`; empty when unprefixed). */
+    fromPrefix: string;
+    toPrefix: string;
+    entries: ReleaseEntry[];
+}

package/dist/lib/release.js

@@ -0,0 +1,206 @@
+import { flat, titleOf } from "./page.js";
+/** Estimated text overlap from which a new page counts as the same page, moved. */
+export const MOVED_SIMILARITY = 0.6;
+/** Shingles both pages need for their text to count ("Coming soon" stubs all look alike). About a dozen words. */
+export const MIN_SHINGLES = 8;
+/**
+ * Classify every page of `from` that `to` does not have at the same path.
+ * Unchanged pages are left out. Order: `from`'s.
+ */
+export function compareRelease(input) {
+    const toPaths = new Set(input.to.map((p) => p.path));
+    const fromPaths = new Set(input.from.map((p) => p.path));
+    const removed = new Set((input.removed ?? []).map(normalizeRemoved));
+    // A move lands on a page the older version did not have. Sorted, so a tie goes the same way in every pipeline.
+    const fresh = input.to.filter((p) => !fromPaths.has(p.path)).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const entries = [];
+    for (const page of input.from) {
+        if (toPaths.has(page.path))
+            continue;
+        const about = { ...(page.source !== undefined ? { source: page.source } : {}), ...(page.index ? { index: true } : {}) };
+        const redirect = input.redirects?.get(page.path);
+        if (redirect !== undefined) {
+            entries.push({ path: page.path, status: "redirected", to: redirect, ...about });
+            continue;
+        }
+        if (removed.has(page.path)) {
+            entries.push({ path: page.path, status: "removed-ok", ...about });
+            continue;
+        }
+        entries.push({ ...match(page, fresh, toPaths, input.renames), ...about });
+    }
+    return entries;
+}
+/**
+ * A `removed:` entry as a page path: no slashes at the ends, no `.md`,
+ * `.markdown` or `.mdx`, `x/index` → `x`, and the home page `index`.
+ */
+export function normalizeRemoved(raw) {
+    const p = raw
+        .trim()
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.(md|markdown|mdx)$/i, "")
+        .replace(/(^|\/)index$/, "");
+    return p || "index";
+}
+function match(page, fresh, toPaths, renames) {
+    const renamed = renames?.get(page.path);
+    if (renamed !== undefined && toPaths.has(renamed)) {
+        return { path: page.path, status: "moved", to: renamed, evidence: ["git rename"] };
+    }
+    if (page.id) {
+        const same = fresh.find((p) => p.id === page.id);
+        if (same)
+            return { path: page.path, status: "moved", to: same.path, evidence: ["same id"] };
+    }
+    let best;
+    let bestScore = 0;
+    for (const p of page.shingles >= MIN_SHINGLES ? fresh : []) {
+        if (p.shingles < MIN_SHINGLES)
+            continue;
+        const s = similarity(page.signature, p.signature);
+        if (s > bestScore) {
+            best = p;
+            bestScore = s;
+        }
+    }
+    if (best && bestScore >= MOVED_SIMILARITY) {
+        return { path: page.path, status: "moved", to: best.path, evidence: [`same text, ${Math.round(bestScore * 100)}%`] };
+    }
+    const title = page.title.toLowerCase();
+    const byTitle = title ? fresh.find((p) => p.title.toLowerCase() === title) : undefined;
+    if (byTitle)
+        return { path: page.path, status: "candidate", to: byTitle.path, evidence: ["same title"] };
+    const name = baseName(page.path);
+    const byName = fresh.find((p) => baseName(p.path) === name);
+    if (byName)
+        return { path: page.path, status: "candidate", to: byName.path, evidence: ["same file name"] };
+    return { path: page.path, status: "removed" };
+}
+/** The last segment that names the page: `guide/install` → `install`, `guide/index` → `guide`. */
+function baseName(path) {
+    const parts = path.split("/").filter((s) => s !== "index");
+    return parts[parts.length - 1] ?? "index";
+}
+// ── Page fingerprints ────────────────────────────────────────────
+const HASHES = 64;
+const SHINGLE = 5;
+/**
+ * A page as matching sees it. `path` is its path inside its version;
+ * `source` its source file relative to the project; `index` whether that
+ * file is a folder's index (other than the home page).
+ */
+export function releasePage(page, path, o = {}) {
+    const id = page.frontmatter?.["id"];
+    const text = treeText(page.tree);
+    return {
+        path: flat(path),
+        title: flat(titleOf(page)),
+        ...(typeof id === "string" && id.trim() ? { id: flat(id.trim()) } : {}),
+        ...(o.source !== undefined ? { source: flat(o.source) } : {}),
+        ...(o.index && path !== "index" ? { index: true } : {}),
+        signature: signature(text),
+        shingles: shingleCount(text),
+    };
+}
+function shingleCount(text) {
+    const words = text.match(/[\p{L}\p{N}]+/gu)?.length ?? 0;
+    return words ? Math.max(1, words - SHINGLE + 1) : 0;
+}
+/**
+ * MinHash over the text's 5-word shingles (lowercased words; a text shorter
+ * than one shingle is one shingle): for each of 64 seeded hashes, the
+ * smallest value over the shingles. Two signatures agree in a slot with the
+ * probability that the two shingle sets overlap (their Jaccard index).
+ */
+export function signature(text) {
+    const words = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    const mins = new Array(HASHES).fill(0xffffffff);
+    if (!words.length)
+        return mins;
+    const count = Math.max(1, words.length - SHINGLE + 1);
+    for (let i = 0; i < count; i++) {
+        const h = fnv1a(words.slice(i, i + SHINGLE).join(" "));
+        for (let k = 0; k < HASHES; k++) {
+            const v = mix(h, k);
+            if (v < mins[k])
+                mins[k] = v;
+        }
+    }
+    return mins;
+}
+/** Estimated Jaccard index of two pages' shingle sets: the share of MinHash slots that agree. Empty pages match nothing. */
+export function similarity(a, b) {
+    if (a.length !== b.length || !a.length || a[0] === 0xffffffff || b[0] === 0xffffffff)
+        return 0;
+    let same = 0;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] === b[i])
+            same++;
+    return same / a.length;
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** The k-th hash of `h` (a murmur3 finaliser over h and a per-k seed). */
+function mix(h, k) {
+    let x = (h ^ Math.imul(k + 1, 0x9e3779b9)) >>> 0;
+    x ^= x >>> 16;
+    x = Math.imul(x, 0x85ebca6b);
+    x ^= x >>> 13;
+    x = Math.imul(x, 0xc2b2ae35);
+    x ^= x >>> 16;
+    return x >>> 0;
+}
+/** A page's text: inline text, HTML without its tags, and code, in document order. */
+export function treeText(nodes) {
+    const out = [];
+    const walk = (list) => {
+        for (const node of list) {
+            if (node.inline)
+                out.push(inlineText(node.inline));
+            if (node.html)
+                out.push(node.html.replace(/<[^>]+>/g, " "));
+            if (typeof node.props?.code === "string")
+                out.push(node.props.code);
+            if (node.children)
+                walk(node.children);
+        }
+    };
+    walk(nodes);
+    return out.join(" ");
+}
+function inlineText(nodes) {
+    let s = "";
+    for (const n of nodes) {
+        if (typeof n.text === "string")
+            s += n.text;
+        else if (typeof n.value === "string")
+            s += n.value;
+        if (Array.isArray(n.children))
+            s += inlineText(n.children);
+        s += " ";
+    }
+    return s;
+}
+// ── Which versions to compare ────────────────────────────────────
+/**
+ * The version a release is compared against: the first version after the
+ * default one in `versions` order (newest first) that is neither a
+ * pre-release nor `hidden` (the numbered twin of a `latest` alias, the same
+ * pages); with the snapshot routine, the previous release as published.
+ * `from` names one instead.
+ */
+export function releaseBaseline(versions, defaultVersion, from) {
+    if (from !== undefined)
+        return versions.some((v) => v.id === from) && from !== defaultVersion ? from : undefined;
+    const i = versions.findIndex((v) => v.id === defaultVersion);
+    if (i < 0)
+        return undefined;
+    return versions.slice(i + 1).find((v) => !v.prerelease && !v.hidden)?.id;
+}

package/dist/lib/validate-refs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure validator for internal page links + asset references in
+ * imported content. Walks every `ExportPage`'s tree, collects
+ * every internal `<a href>` and `<img src>`, set-checks against
+ * the page slug set + the asset file set. A relative reference is
+ * resolved against the page's own file (`links.ts`), as the build
+ * resolves it.
+ *
+ * Single source of truth shared between two surfaces:
+ *   - `structure/internal-links` + `structure/asset-refs` audit
+ *     rules (warning-or-error issues from `dogsbay site check`)
+ *   - `dogsbay site build --strict` (throws on first miss)
+ *
+ * See plans/audit-internal-refs.md.
+ */
+import type { ExportPage } from "@dogsbay/types";
+/** One miss found by the validator. */
+export interface RefIssue {
+    /** Slug of the page that contains the broken reference. */
+    pageSlug: string;
+    /** Raw href / src as written by the author. */
+    href: string;
+    /** Whether the validator was looking for a page or an asset. */
+    resolvedAgainst: "page" | "asset";
+}
+export interface ValidateRefsOptions {
+    /** Site basePath (e.g. "/docs", "/" for host-root, "" for root). */
+    basePath: string;
+    /**
+     * Absolute paths under the public asset tree, leading slash,
+     * matching how authors write them. e.g. `"/_assets/foo.png"`.
+     */
+    knownAssets: Set<string>;
+}
+export interface ValidateRefsResult {
+    linkMisses: RefIssue[];
+    assetMisses: RefIssue[];
+}
+export declare function validateRefs(pages: ExportPage[], options: ValidateRefsOptions): ValidateRefsResult;