@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/checks/page-weight.js

@@ -0,0 +1,200 @@
+import { resolveLink } from "@avocadostudio-ai/shared";
+/*
+ * How much a page matters, independently of what is wrong with it.
+ *
+ * The checker has always had severity — *how broken* — and no answer at all to
+ * *how much it matters*, so the panel could only be ordered by the one axis a
+ * reader does not have. On the live session that produced a list whose largest
+ * single source of findings was a test page, with the home page third.
+ *
+ * Nothing here needs analytics. A site states what it thinks is important in
+ * the pages it links to and the pages it names in its nav. This reads both.
+ * When traffic data arrives it replaces `weight` with a measured share and
+ * everything downstream is unchanged — which is why this returns one number per
+ * slug rather than exposing its inputs to the rules.
+ */
+/**
+ * The four contributions, summed to 1. Named so the ordering can be argued
+ * with, and deliberately coarse: this is a sort key, not a measurement, and
+ * every extra decimal place is a claim the inputs cannot support.
+ */
+const CONTRIBUTION = {
+    /** Every routed page is a real page someone can land on. */
+    base: 0.25,
+    /** Editorial links from elsewhere on the site — the strongest free signal. */
+    inbound: 0.45,
+    /** Named by hand in the site's nav config. */
+    named: 0.15,
+    /** Clicks from the home page over those links. */
+    depth: 0.15
+};
+/**
+ * Four inbound links and a fifth tells you nothing new. Without a ceiling this
+ * is really a page-count term, and the biggest site wins every time.
+ */
+const INBOUND_SATURATION = 4;
+/**
+ * A link that appears on this fraction of the site is chrome — a footer, a
+ * header, a card grid repeated on every page — not an editorial link.
+ *
+ * Without it the term inverts: put a page in the footer and it collects an
+ * inbound link from all 45 pages, so *every* footer-linked page saturates and
+ * inbound stops discriminating exactly where a real site leans on it most.
+ * Chrome still counts, but as a named page, which is what it is.
+ */
+const CHROME_LINK_FRACTION = 0.8;
+/** The home page is the home page. No combination of the terms should outrank it. */
+const HOME_WEIGHT = 1;
+const HOME_SLUG = "/";
+function depthScore(depth) {
+    if (depth === null)
+        return 0;
+    if (depth <= 0)
+        return 1;
+    if (depth === 1)
+        return 0.7;
+    if (depth === 2)
+        return 0.4;
+    if (depth === 3)
+        return 0.2;
+    return 0;
+}
+/**
+ * Slugs the site config names by hand.
+ *
+ * Read as *deliberately named*, never as *the pages in the nav* — and the
+ * distinction is the whole reason this comment exists. `buildNavItems` in
+ * site-sdk puts **every** draft slug in the header; `navLabels` only relabels
+ * them and `navGroups` only collapses them into dropdowns. So a page absent
+ * from both is still in the site's nav, one click from home.
+ *
+ * An earlier version read these maps as membership and floored anything outside
+ * them at 0.10 as an orphan — "reachable only by someone who already knows the
+ * URL", which is simply false here. On a site with no nav config, which is the
+ * ordinary case, that is every page but the home page, and burying real
+ * findings on real pages is a worse failure than the noise this ordering exists
+ * to fix.
+ *
+ * So a named page gets a small bonus for having been thought about, and an
+ * unnamed one is not accused of anything.
+ */
+function namedSlugs(config) {
+    const out = new Set();
+    for (const slug of Object.keys(config.navLabels ?? {}))
+        out.add(slug);
+    for (const children of Object.values(config.navGroups ?? {})) {
+        for (const slug of children)
+            out.add(slug);
+    }
+    return out;
+}
+/**
+ * Which pages link to which, from every link-ish field on the site.
+ *
+ * Resolution goes through `resolveLink` rather than a local `startsWith("/")`,
+ * for the reason that module was extracted: three places used to answer "is
+ * this a route, and does it exist" their own way and did not agree. It also
+ * matches a page by `meta.path`, so a locale-prefixed site's links land on the
+ * page they mean instead of counting as zero.
+ *
+ * Self-links are dropped — a page is not evidence of its own importance — and
+ * sources are a Set, because four links to `/pricing` in one block have told us
+ * one thing, not four.
+ */
+function buildLinkGraph(fieldsBySlug, pages) {
+    const sourcesByTarget = new Map();
+    for (const [slug, fields] of fieldsBySlug) {
+        for (const field of fields) {
+            if (field.kind !== "link" && field.kind !== "url")
+                continue;
+            const target = resolveLink(field.value, pages).page?.slug;
+            if (!target || target === slug)
+                continue;
+            const sources = sourcesByTarget.get(target);
+            if (sources)
+                sources.add(slug);
+            else
+                sourcesByTarget.set(target, new Set([slug]));
+        }
+    }
+    return sourcesByTarget;
+}
+/**
+ * Breadth-first from the home page over editorial links, plus a hop straight to
+ * anything named in the nav — a named page is one click from wherever you are.
+ *
+ * Returns an empty map for a site with no `/` at all, which a CMS-backed
+ * subtree legitimately is. Every page there scores on links alone.
+ */
+function depthsFromHome(slugs, sourcesByTarget, named) {
+    const outbound = new Map();
+    for (const [target, sources] of sourcesByTarget) {
+        for (const source of sources) {
+            const list = outbound.get(source);
+            if (list)
+                list.push(target);
+            else
+                outbound.set(source, [target]);
+        }
+    }
+    const depths = new Map();
+    if (!slugs.includes(HOME_SLUG))
+        return depths;
+    depths.set(HOME_SLUG, 0);
+    const queue = [HOME_SLUG];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = depths.get(current);
+        const next = [...(outbound.get(current) ?? []), ...(current === HOME_SLUG ? named : [])];
+        for (const target of next) {
+            if (depths.has(target))
+                continue;
+            depths.set(target, depth + 1);
+            queue.push(target);
+        }
+    }
+    return depths;
+}
+export function computePageWeights(args) {
+    const { pages, fieldsBySlug, config } = args;
+    const slugs = pages.map((p) => p.slug);
+    const options = pages.map((p) => ({
+        slug: p.slug,
+        ...(p.meta?.path ? { path: p.meta.path } : {}),
+        ...(p.title ? { title: p.title } : {})
+    }));
+    const sourcesByTarget = buildLinkGraph(fieldsBySlug, options);
+    // A link carried on nearly every page is chrome. Fold it into the named term
+    // rather than letting it saturate inbound for every page in the footer.
+    const chromeThreshold = Math.max(2, Math.ceil(slugs.length * CHROME_LINK_FRACTION));
+    const chrome = new Set();
+    for (const [target, sources] of sourcesByTarget) {
+        if (sources.size >= chromeThreshold)
+            chrome.add(target);
+    }
+    const named = new Set([...namedSlugs(config), ...chrome]);
+    const depths = depthsFromHome(slugs, sourcesByTarget, named);
+    const weights = new Map();
+    for (const slug of slugs) {
+        const isHome = slug === HOME_SLUG;
+        const isNamed = named.has(slug);
+        const inbound = chrome.has(slug) ? 0 : (sourcesByTarget.get(slug)?.size ?? 0);
+        const depth = depths.get(slug) ?? null;
+        const weight = isHome
+            ? HOME_WEIGHT
+            : Math.min(HOME_WEIGHT, CONTRIBUTION.base +
+                CONTRIBUTION.inbound * Math.min(inbound / INBOUND_SATURATION, 1) +
+                (isNamed ? CONTRIBUTION.named : 0) +
+                CONTRIBUTION.depth * depthScore(depth));
+        weights.set(slug, {
+            slug,
+            weight: Math.round(weight * 1000) / 1000,
+            inbound,
+            depth,
+            named: isNamed,
+            isHome,
+            isUnlinked: !isHome && !isNamed && inbound === 0
+        });
+    }
+    return weights;
+}

package/dist/checks/rules-draft.d.ts

@@ -0,0 +1,2 @@
+import type { CheckRule } from "./types.ts";
+export declare const DRAFT_RULES: CheckRule[];

package/dist/checks/rules-draft.js

@@ -0,0 +1,439 @@
+import { IMAGE_PLACEHOLDER, isKnownRoute, normalizeLinkPath, parseLink, toAltPath } from "@avocadostudio-ai/shared";
+import { fieldText, groupByBlock } from "./field-walk.js";
+/*
+ * The eleven-ish draft-tier rules. Each is a pure function; none does IO.
+ *
+ * Severity discipline, because findings fatigue is the failure mode and a panel
+ * with 300 warnings is a panel nobody opens:
+ *   error   — this is broken and a crawler or a screen reader sees it
+ *   warning — this is very likely wrong
+ *   info    — worth a look, and safe to ignore forever
+ */
+const TITLE_MIN = 20;
+const TITLE_MAX = 60;
+const DESCRIPTION_MIN = 70;
+const DESCRIPTION_MAX = 160;
+const THIN_CONTENT_CHARS = 120;
+function effectiveTitle(page) {
+    return (page.meta?.title ?? page.title ?? "").trim();
+}
+function nonEmpty(value) {
+    return fieldText(value).trim().length > 0;
+}
+function textFields(ctx) {
+    return ctx.fields.filter((f) => f.kind === "text" || f.kind === "richtext");
+}
+function evidenceFor(field, excerpt) {
+    return {
+        source: "draft",
+        blockId: field.blockId,
+        blockType: field.blockType,
+        ...(field.blockLabel ? { blockLabel: field.blockLabel } : {}),
+        path: field.path,
+        ...(excerpt ? { excerpt } : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// Page metadata
+// ---------------------------------------------------------------------------
+const titleMissing = {
+    id: "seo.title-missing",
+    agent: "seo",
+    severity: "error",
+    run: (ctx) => effectiveTitle(ctx.page)
+        ? []
+        : [
+            {
+                title: "Page has no title",
+                detail: "Neither meta.title nor the page title is set, so the tab and the search result have nothing to show."
+            }
+        ]
+};
+const titleLength = {
+    id: "seo.title-length",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const title = effectiveTitle(ctx.page);
+        if (!title)
+            return []; // titleMissing owns that case; two findings for one fact is noise
+        if (title.length < TITLE_MIN) {
+            return [{ title: `Title is ${title.length} characters (aim for ${TITLE_MIN}–${TITLE_MAX})` }];
+        }
+        if (title.length > TITLE_MAX) {
+            return [{ title: `Title is ${title.length} characters and will be truncated (aim for ${TITLE_MIN}–${TITLE_MAX})` }];
+        }
+        return [];
+    }
+};
+const titleDuplicate = {
+    id: "seo.title-duplicate",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const title = effectiveTitle(ctx.page);
+        if (!title)
+            return [];
+        const clash = ctx.site.pages.filter((p) => p.slug !== ctx.page.slug &&
+            (p.meta?.title ?? p.title ?? "").trim().toLowerCase() === title.toLowerCase());
+        if (clash.length === 0)
+            return [];
+        return [
+            {
+                title: "Another page has the same title",
+                detail: `Also used by ${clash.map((p) => p.slug).join(", ")}. Search engines pick one and drop the rest.`
+            }
+        ];
+    }
+};
+const descriptionMissing = {
+    id: "seo.description-missing",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => (ctx.page.meta?.description ?? "").trim()
+        ? []
+        : [
+            {
+                title: "Page has no description",
+                // No proposedOps: writing a good one is a judgement-tier job. A
+                // rule that guessed here would ship copy under an approval button
+                // people have learned to click.
+                detail: "Search results and link previews will fall back to whatever text they can scrape."
+            }
+        ]
+};
+const descriptionLength = {
+    id: "seo.description-length",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const description = (ctx.page.meta?.description ?? "").trim();
+        if (!description)
+            return [];
+        if (description.length < DESCRIPTION_MIN) {
+            return [{ title: `Description is ${description.length} characters (aim for ${DESCRIPTION_MIN}–${DESCRIPTION_MAX})` }];
+        }
+        if (description.length > DESCRIPTION_MAX) {
+            return [{ title: `Description is ${description.length} characters and will be truncated (aim for ${DESCRIPTION_MIN}–${DESCRIPTION_MAX})` }];
+        }
+        return [];
+    }
+};
+const ogImageMissing = {
+    id: "seo.og-image-missing",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        if ((ctx.page.meta?.ogImage ?? "").trim())
+            return [];
+        const hasImage = ctx.fields.some((f) => f.kind === "image" && nonEmpty(f.value) && f.value !== IMAGE_PLACEHOLDER);
+        return [
+            {
+                title: "No social preview image",
+                detail: hasImage
+                    ? "The page has images but none is set as meta.ogImage, so shares get no thumbnail."
+                    : "Shared links will render without a thumbnail."
+            }
+        ];
+    }
+};
+const slugQuality = {
+    id: "seo.slug-quality",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const slug = ctx.page.slug;
+        const problems = [];
+        if (/[A-Z]/.test(slug))
+            problems.push("uppercase letters");
+        if (slug.includes("_"))
+            problems.push("underscores instead of hyphens");
+        if (/\s/.test(slug))
+            problems.push("spaces");
+        if (slug.split("/").filter(Boolean).length > 5)
+            problems.push("more than five segments");
+        if (problems.length === 0)
+            return [];
+        return [{ title: `Slug has ${problems.join(", ")}`, detail: slug }];
+    }
+};
+// ---------------------------------------------------------------------------
+// Structure
+// ---------------------------------------------------------------------------
+/** Heading levels in block order, from any field the manifest calls a headingLevel. */
+function headingLevels(ctx) {
+    const out = [];
+    for (const field of ctx.fields) {
+        if (field.kind !== "headingLevel")
+            continue;
+        const level = typeof field.value === "number" ? field.value : Number(field.value);
+        if (Number.isFinite(level) && level >= 1 && level <= 6)
+            out.push({ field, level });
+    }
+    return out;
+}
+const h1Count = {
+    id: "seo.h1-count",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const levels = headingLevels(ctx);
+        // A page whose blocks declare no heading level at all is not making a
+        // claim about its structure — most likely the site's blocks hardcode their
+        // tags. Reporting "no h1" there is a guess dressed as a fact.
+        if (levels.length === 0)
+            return [];
+        const h1s = levels.filter((l) => l.level === 1);
+        if (h1s.length === 1)
+            return [];
+        if (h1s.length === 0) {
+            return [{ title: "Page has no top-level heading", detail: "No block on the page is set to heading level 1." }];
+        }
+        // Keyed by field, not by block: a block may declare more than one heading
+        // level (a two-column with a heading each), and two findings sharing one
+        // key collapse into one — leaving the second heading with no finding and
+        // no proposed fix.
+        return h1s.slice(1).map(({ field }) => ({
+            key: `${field.blockId}:${field.path}`,
+            title: "Page has more than one top-level heading",
+            detail: `${h1s.length} blocks are set to heading level 1.`,
+            evidence: evidenceFor(field),
+            proposedOps: [
+                {
+                    op: "update_props",
+                    pageSlug: ctx.page.slug,
+                    blockId: field.blockId,
+                    patch: { [field.path]: 2 }
+                }
+            ]
+        }));
+    }
+};
+const headingOrder = {
+    id: "seo.heading-order",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const levels = headingLevels(ctx);
+        const out = [];
+        let previous = null;
+        for (const { field, level } of levels) {
+            if (previous !== null && level > previous + 1) {
+                out.push({
+                    key: `${field.blockId}:${field.path}`,
+                    title: `Heading jumps from level ${previous} to ${level}`,
+                    detail: "Screen readers announce the gap as a missing section.",
+                    evidence: evidenceFor(field)
+                });
+            }
+            previous = level;
+        }
+        return out;
+    }
+};
+const thinContent = {
+    id: "seo.thin-content",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const total = textFields(ctx)
+            .map((f) => fieldText(f.value).trim())
+            .join(" ")
+            .trim();
+        if (total.length >= THIN_CONTENT_CHARS)
+            return [];
+        return [
+            {
+                title: `Page has ${total.length} characters of text`,
+                detail: `Under ${THIN_CONTENT_CHARS} characters is usually too little for a page to rank for anything.`
+            }
+        ];
+    }
+};
+// ---------------------------------------------------------------------------
+// Links, images, leftovers
+// ---------------------------------------------------------------------------
+/** A link's evidence, which points at the field the link was written in. */
+function linkEvidence(link) {
+    return {
+        source: "draft",
+        blockId: link.blockId,
+        blockType: link.blockType,
+        ...(link.blockLabel ? { blockLabel: link.blockLabel } : {}),
+        path: link.path,
+        excerpt: link.value
+    };
+}
+/*
+ * One finding per link, and a link written in prose needs a key that separates
+ * it from its neighbours: three PDF links in one body all sit at the same
+ * field path, so keying on the path alone collapses them into one finding and
+ * two broken links go unreported.
+ */
+function linkKey(link) {
+    const base = link.path === "" ? link.blockId : `${link.blockId}:${link.path}`;
+    return link.inProse ? `${base}#${link.value}` : base;
+}
+const internalLinkDead = {
+    id: "seo.internal-link-dead",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const known = new Set(ctx.site.slugs);
+        return ctx.links
+            /*
+             * `ctx.links` already carries both sources — `link`/`url`/`file` props
+             * and hrefs written into prose. It used to read `ctx.fields` and so saw
+             * only the first, which meant the links a content page actually has, the
+             * ones inside its bodies, were never checked.
+             *
+             * `parseLink` screens out mailto/tel/anchors/external, the default "/",
+             * and now documents: a `.pdf` path is `kind: "file"` and is not a route,
+             * so it is not this rule's business. `fileLinkUnknown` below answers the
+             * question that *is* right for a file.
+             */
+            .filter((link) => {
+            const parsed = parseLink(link.value);
+            return parsed.kind === "page" && parsed.path?.startsWith("/") === true;
+        })
+            /*
+             * Absolute routes only, as before. A bare "pricing" is a relative link
+             * and broken from any page but the root, but flagging it is a separate
+             * judgement call from this rule's, and one that would light up existing
+             * sites without warning.
+             */
+            .filter((link) => !isKnownRoute(link.value, known))
+            .map((link) => ({
+            key: linkKey(link),
+            title: `Link points at a page that does not exist`,
+            detail: link.inProse ? `${link.value} — written in ${link.label ?? link.path}` : link.value,
+            evidence: linkEvidence(link)
+        }));
+    }
+};
+/*
+ * A link to a document the site does not have.
+ *
+ * This is the rule that pays for the `file` kind. A menu PDF is linked by
+ * hand-typed path, nothing renders a 404 until a customer clicks it, and the
+ * filename is usually long and often misspelled — one live site links
+ * `/downloads/AadventureArenaBerm-Gruppen-DE.pdf`, and whether that is the real
+ * filename or a typo for it is not a question anyone has been able to ask.
+ *
+ * It runs only when the site can enumerate its documents. `ctx.site.assets`
+ * undefined means it cannot, and then this rule returns nothing rather than
+ * reporting every document on the site as missing — the same discipline as
+ * `resolveLink`, where "we did not check" must not read as "it is not there".
+ */
+const fileLinkUnknown = {
+    id: "content.file-link-unknown",
+    agent: "seo",
+    severity: "error",
+    run: (ctx) => {
+        const assets = ctx.site.assets;
+        if (!assets)
+            return [];
+        const known = new Set(assets.map((a) => normalizeLinkPath(a.path)));
+        return ctx.links
+            .filter((link) => {
+            const parsed = parseLink(link.value);
+            return parsed.kind === "file" && parsed.path?.startsWith("/") === true;
+        })
+            .filter((link) => !known.has(normalizeLinkPath(parseLink(link.value).path ?? "")))
+            .map((link) => ({
+            key: linkKey(link),
+            title: "Link points at a document the site does not have",
+            detail: link.inProse ? `${link.value} — written in ${link.label ?? link.path}` : link.value,
+            evidence: linkEvidence(link)
+        }));
+    }
+};
+const altMissing = {
+    id: "a11y.alt-missing",
+    agent: "a11y",
+    severity: "warning",
+    run: (ctx) => {
+        const out = [];
+        /*
+         * One block at a time. Paths and containers are block-relative, so a
+         * page-wide index of either pairs an image in one block with the alt text
+         * of another — and two blocks of the same type on one page is the ordinary
+         * case, not the exotic one.
+         *
+         * All three ways that went wrong were silent: two heroes where the first
+         * had no alt text reported nothing at all; the mirror image reported the
+         * problem twice, both times pointing "Go to" at the wrong block.
+         */
+        for (const fields of groupByBlock(ctx.fields).values()) {
+            const alts = fields.filter((f) => f.kind === "imageAlt");
+            const altByPath = new Map(alts.map((f) => [f.path, f]));
+            const altsByContainer = new Map();
+            for (const field of alts) {
+                const list = altsByContainer.get(field.container) ?? [];
+                list.push(field);
+                altsByContainer.set(field.container, list);
+            }
+            for (const image of fields) {
+                if (image.kind !== "image" || !nonEmpty(image.value))
+                    continue;
+                // The repo's own naming convention first (`imageUrl` → `imageAlt`,
+                // `.src` → `.alt`), then the structural answer: a lone alt field in the
+                // same container. A container with two images and two alts is ambiguous
+                // and is left alone rather than guessed at.
+                const byConvention = altByPath.get(toAltPath(image.path));
+                const siblings = altsByContainer.get(image.container) ?? [];
+                const alt = byConvention ?? (siblings.length === 1 ? siblings[0] : undefined);
+                if (!alt || nonEmpty(alt.value))
+                    continue;
+                out.push({
+                    key: `${image.blockId}:${image.path}`,
+                    title: `Image has no alt text`,
+                    detail: `${image.label ?? image.path} is set but its alt text is empty.`,
+                    evidence: evidenceFor(alt)
+                });
+            }
+        }
+        return out;
+    }
+};
+const unfinished = {
+    id: "content.unfinished",
+    agent: "content",
+    severity: "warning",
+    run: (ctx) => {
+        const out = [];
+        for (const field of ctx.fields) {
+            // `defaultScalarForField` writes exactly these when a block is scaffolded,
+            // so this is an equality test, not a heuristic — the product is the only
+            // thing that could have produced the string.
+            const isScaffoldText = (field.kind === "text" || field.kind === "richtext" || field.kind === "imageAlt") &&
+                fieldText(field.value).trim() === `New ${field.label ?? field.path}`;
+            const isScaffoldImage = field.kind === "image" && field.value === IMAGE_PLACEHOLDER;
+            if (!isScaffoldText && !isScaffoldImage)
+                continue;
+            out.push({
+                key: `${field.blockId}:${field.path}`,
+                title: `${field.label ?? field.path} was never filled in`,
+                detail: "This is still the placeholder the block was created with.",
+                evidence: evidenceFor(field, fieldText(field.value) || String(field.value))
+            });
+        }
+        return out;
+    }
+};
+export const DRAFT_RULES = [
+    titleMissing,
+    titleLength,
+    titleDuplicate,
+    descriptionMissing,
+    descriptionLength,
+    ogImageMissing,
+    slugQuality,
+    h1Count,
+    headingOrder,
+    thinContent,
+    internalLinkDead,
+    fileLinkUnknown,
+    altMissing,
+    unfinished
+];

package/dist/checks/run-checks.d.ts

@@ -0,0 +1,42 @@
+import type { BlockManifest, PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+import type { CheckRunRecord, CheckRunTrigger, DurableStore } from "../durable/types.ts";
+import type { CheckRule, SiteAsset } from "./types.ts";
+/**
+ * The fingerprint: identity of a problem, not of an occurrence of it.
+ *
+ * It is computed here, from `(scopeKey, slug, ruleId, key)`, and never by a
+ * rule — because the one thing that must not leak into it is the offending
+ * *value*. Include the value and half-fixing a title produces a second finding
+ * instead of an updated one, orphaning the first and silently voiding the
+ * dismissal somebody made last week.
+ */
+export declare function fingerprintFor(scopeKey: string, slug: string, ruleId: string, key?: string): string;
+export type RunChecksArgs = {
+    scopeKey: string;
+    /** Every page in the site — not just the ones being scanned. See below. */
+    pages: PageDoc[];
+    manifest: BlockManifest;
+    siteConfig?: SiteConfig;
+    trigger?: CheckRunTrigger;
+    /**
+     * Restrict the scan to these slugs. Cross-page rules still see the whole
+     * site: an incremental run over one page must not report every *other*
+     * page's title as unique, nor every link into them as dead.
+     */
+    slugs?: string[];
+    /**
+     * The documents the site holds, when the caller could list them.
+     *
+     * Omitted — not `[]` — when it could not. `content.file-link-unknown` is
+     * silent without this, because a site that cannot enumerate its assets has no
+     * grounds to call any of its own document links broken. Filling it is the
+     * caller's job because listing assets is IO, and every rule in this directory
+     * is a pure function by construction.
+     */
+    assets?: SiteAsset[];
+    rules?: CheckRule[];
+    store?: DurableStore;
+    runId?: string;
+    now?: () => number;
+};
+export declare function runDraftChecks(args: RunChecksArgs): Promise<CheckRunRecord>;