@dogsbay/commands 0.2.0-beta.101

package/dist/commands/validate.js

@@ -0,0 +1,753 @@
+/**
+ * `validate` — the workspace health gate.
+ *
+ * Every check is an index lookup: broken relative links, missing link
+ * anchors, missing include targets, undefined keys, conflicting key
+ * definitions, malformed keys files, topic-map parse errors, and
+ * topic-map entries pointing at missing files. Docs that fail to parse
+ * are surfaced too — a doc the indexer can't read can hide any of the
+ * above.
+ */
+import { z } from "zod";
+import { dirname as dirnameOf, joinPath } from "@dogsbay/format-topicmap";
+import { defineCommand } from "../engine.js";
+import { anchorAliases, anchorAliasTargets } from "../indexes.js";
+import { WELL_KNOWN_FIELDS, matchesType, isSafeAutoFix, nearMisses, contentRelativePath, requiredFieldsFor, typeOf, AGGREGATOR_OWNED, } from "../frontmatter-schema.js";
+import { dirname as dirOf, relative as relPath } from "node:path/posix";
+import { load as loadYaml } from "js-yaml";
+const input = z.object({}).strict();
+async function siteLayout(storage) {
+    const out = { roots: [""], prefixes: [], checkable: true };
+    for (const name of ["dogsbay.config.yml", "dogsbay.config.yaml", "dogsbay.config.json"]) {
+        if (!(await storage.exists(name)))
+            continue;
+        try {
+            const text = await storage.read(name);
+            const cfg = (name.endsWith(".json") ? JSON.parse(text) : loadYaml(text));
+            if (!cfg || typeof cfg !== "object")
+                return out;
+            const site = (cfg.site ?? {});
+            if (typeof site.basePath === "string" && site.basePath.replace(/\//g, ""))
+                out.prefixes.push(site.basePath.replace(/^\/+|\/+$/g, ""));
+            if (typeof site.url === "string") {
+                try {
+                    const u = new URL(site.url);
+                    const pth = u.pathname.replace(/^\/+|\/+$/g, "");
+                    if (pth)
+                        out.prefixes.push(pth);
+                }
+                catch { /* not a URL */ }
+            }
+            const content = (cfg.content ?? {});
+            const sources = Array.isArray(content.sources) ? content.sources : [];
+            const roots = [];
+            for (const src of sources) {
+                if (!src || typeof src !== "object")
+                    continue;
+                const rec = src;
+                if (typeof rec.git === "string" || typeof rec.repo === "string") {
+                    out.checkable = false;
+                    continue;
+                }
+                if (typeof rec.namespace === "string" || typeof rec.version === "string" || typeof rec.locale === "string")
+                    out.checkable = false;
+                if (typeof rec.path === "string") {
+                    const root = rec.path.replace(/^\.\/+/, "").replace(/^\/+|\/+$/g, "");
+                    if (root.startsWith("..")) {
+                        out.checkable = false;
+                        continue;
+                    } // above the workspace: unknowable
+                    roots.push(root);
+                }
+            }
+            if (typeof content.path === "string")
+                roots.push(content.path.replace(/^\.\/+/, "").replace(/^\/+|\/+$/g, ""));
+            if (roots.length)
+                out.roots = [...new Set(roots)];
+        }
+        catch {
+            /* unreadable config: resolve against the workspace root */
+        }
+        break;
+    }
+    return out;
+}
+/** js-yaml's own complaint about the frontmatter block, with the line it points at. */
+function yamlErrorOf(source) {
+    const lines = source.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return undefined;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++)
+        if (/^(---|\.\.\.)[ \t]*\r?$/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    if (end === -1)
+        return undefined;
+    try {
+        loadYaml(lines.slice(1, end).join("\n"));
+        return undefined;
+    }
+    catch (err) {
+        const e = err;
+        const message = String(e.message ?? err).split("\n")[0];
+        return { message, line: (e.mark?.line ?? 0) + 2 }; // +1 for the opener, +1 for 1-based
+    }
+}
+/**
+ * The frontmatter policy, read from the same config file as the site layout:
+ * declared `taxonomies:` (their `values`/`hierarchical` ARE the check) plus
+ * the opt-in `content.frontmatter` strictness. Absent config → the
+ * well-known-field type checks only.
+ */
+async function frontmatterPolicy(storage, layout) {
+    const out = { taxonomies: {}, propSchema: {}, required: [], unknown: "ignore", roots: layout.roots };
+    for (const name of ["dogsbay.config.yml", "dogsbay.config.yaml", "dogsbay.config.json"]) {
+        if (!(await storage.exists(name)))
+            continue;
+        try {
+            const text = await storage.read(name);
+            const cfg = (name.endsWith(".json") ? JSON.parse(text) : loadYaml(text));
+            if (!cfg || typeof cfg !== "object")
+                return out;
+            const taxonomies = (cfg.taxonomies ?? {});
+            for (const [field, raw] of Object.entries(taxonomies)) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const rec = raw;
+                out.taxonomies[field] = {
+                    values: Array.isArray(rec.values) ? rec.values.filter((v) => typeof v === "string") : undefined,
+                    hierarchical: rec.hierarchical === true,
+                };
+            }
+            // `propSchema` shorthand is a bare type name; the long form adds an enum
+            const propSchema = (cfg.propSchema ?? {});
+            for (const [key, raw] of Object.entries(propSchema)) {
+                if (typeof raw === "string" && ["string", "number", "boolean"].includes(raw)) {
+                    out.propSchema[key] = { type: raw };
+                }
+                else if (raw && typeof raw === "object") {
+                    const rec = raw;
+                    if (typeof rec.type === "string" && ["string", "number", "boolean"].includes(rec.type)) {
+                        out.propSchema[key] = {
+                            type: rec.type,
+                            enum: Array.isArray(rec.enum) ? rec.enum.map((v) => String(v)) : undefined,
+                        };
+                    }
+                }
+            }
+            const content = (cfg.content ?? {});
+            const fm = (content.frontmatter ?? {});
+            if (fm.unknown === "warn" || fm.unknown === "error")
+                out.unknown = fm.unknown;
+            else if (fm.unknown !== undefined && fm.unknown !== "ignore") {
+                // the CLI throws on this; the IDE reads the config directly, so say so rather than
+                // silently applying no policy at all
+                out.invalid = `content.frontmatter.unknown must be "ignore" | "warn" | "error"; got ${JSON.stringify(fm.unknown)}`;
+            }
+            const required = fm.required;
+            if (required && typeof required === "object") {
+                for (const [glob, fields] of Object.entries(required)) {
+                    const list = Array.isArray(fields) ? fields.filter((f) => typeof f === "string") : typeof fields === "string" ? [fields] : [];
+                    if (list.length)
+                        out.required.push({ glob, fields: list });
+                }
+            }
+        }
+        catch {
+            /* unreadable config: no policy rather than a guessed one */
+        }
+        break;
+    }
+    return out;
+}
+/**
+ * Frontmatter findings for one document. Pure: the caller supplies the raw
+ * source (for key lines) and the policy.
+ */
+function frontmatterIssues(doc, keyLines, policy) {
+    const out = [];
+    const fm = doc.frontmatter ?? {};
+    const at = (key) => (keyLines.has(key) ? { line: keyLines.get(key) } : {});
+    // the fix is the EXISTING props-set verb (span-aware, re-parses what it wrote, expect-gated) —
+    // `expect` is the hash of the bytes this finding was computed from
+    const setFix = (key, value, label) => ({
+        fix: { verb: "props-set", args: { file: doc.path, set: { [key]: value }, expect: doc.hash }, label },
+    });
+    for (const [key, value] of Object.entries(fm)) {
+        const taxonomy = policy.taxonomies[key];
+        const spec = WELL_KNOWN_FIELDS[key];
+        if (AGGREGATOR_OWNED.includes(key))
+            continue; // reported below, once, whatever its type
+        if (!spec && !taxonomy) {
+            // an unknown-key policy applies to CONTENT only: a README or a plan in the same
+            // workspace is not a page, and reporting its keys is noise
+            if (policy.unknown !== "ignore" && contentRelativePath(policy, doc.path) !== null) {
+                out.push({
+                    severity: policy.unknown === "error" ? "error" : "warning",
+                    code: "frontmatter-unknown",
+                    message: `unknown frontmatter key "${key}" (not a well-known field or a declared taxonomy)`,
+                    file: doc.path,
+                    ...at(key),
+                });
+            }
+            continue;
+        }
+        if (value === null || value === undefined)
+            continue; // an empty key is a stub, not a wrong type
+        // A DECLARED taxonomy wins over the built-in field spec: taxonomy terms are strings (the
+        // collector drops anything else), so `product: 3` must be reported even though the chunker's
+        // own `product` facet would have taken a number.
+        const effective = taxonomy ? { type: "string|string[]" } : spec;
+        if (effective && !matchesType(value, effective.type)) {
+            out.push({
+                severity: "error",
+                code: "frontmatter-type",
+                message: `"${key}" should be ${effective.type}, got ${typeOf(value)}`,
+                file: doc.path,
+                ...at(key),
+            });
+            continue;
+        }
+        if (spec && !matchesType(value, spec.type)) {
+            out.push({
+                severity: "error",
+                code: "frontmatter-type",
+                message: `"${key}" should be ${spec.type}, got ${typeOf(value)}`,
+                file: doc.path,
+                ...at(key),
+            });
+            continue; // an enum check on the wrong type says nothing useful
+        }
+        // `tags: api, guides` is ONE tag called "api, guides" — the coercion wraps the scalar, it
+        // does not split it, so the writer silently gets a tag nobody will ever match
+        // ONLY where the coercion wraps rather than splits: the taxonomy/meta fields. The chunker's
+        // facet axes split a string themselves, so a comma there is fine.
+        const wrapsScalar = taxonomy !== undefined || key === "tags" || key === "audience" || key === "category";
+        if (typeof value === "string" && /,\s*\S/.test(value) && wrapsScalar) {
+            out.push({
+                severity: "warning",
+                code: "frontmatter-comma-scalar",
+                message: `"${key}: ${value}" is ONE value containing a comma, not a list — write it as a YAML list (\`[a, b]\`) if you meant several`,
+                file: doc.path,
+                ...at(key),
+            });
+        }
+        // a value the pipeline discards: an empty string or an empty list is not "no value", it is a
+        // value that silently disappears (parseMeta drops both)
+        if ((typeof value === "string" && value.trim() === "") || (Array.isArray(value) && value.length === 0)) {
+            out.push({
+                severity: "warning",
+                code: "frontmatter-empty",
+                message: `"${key}" is empty, so it is dropped — remove the key or give it a value`,
+                file: doc.path,
+                ...at(key),
+            });
+            continue;
+        }
+        // a closed set: the well-known `status`, or a taxonomy that declared `values`
+        const allowed = spec?.values ?? taxonomy?.values;
+        const terms = typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+        if (allowed) {
+            for (const term of terms) {
+                const head = taxonomy?.hierarchical ? term.split("/")[0] : term;
+                if (allowed.includes(term) || (taxonomy?.hierarchical && allowed.includes(head)))
+                    continue;
+                // a hierarchical taxonomy declares its HEAD terms, so `apu/rest` is a near miss of `api`
+                const probe = taxonomy?.hierarchical ? head : term;
+                const near = nearMisses(probe, allowed);
+                // a hierarchical fix keeps the sub-term: `apu/rest` → `api/rest`, never `api`
+                const replacement = near.length === 1
+                    ? (taxonomy?.hierarchical && term !== head ? `${near[0]}${term.slice(head.length)}` : near[0])
+                    : undefined;
+                out.push({
+                    severity: "error",
+                    code: "frontmatter-enum",
+                    message: taxonomy?.hierarchical && term !== head
+                        ? `"${key}: ${term}" starts with "${head}", which is not one of ${allowed.join(", ")}`
+                        : `"${key}: ${term}" is not one of ${allowed.join(", ")}`,
+                    file: doc.path,
+                    ...at(key),
+                    ...(near.length ? { candidates: near } : {}),
+                    // ONLY a case slip is applied with one click: at edit distance 2 the single
+                    // candidate for `unstable` is `stable`, and inverting a writer's meaning on a
+                    // click is worse than making them choose
+                    ...(replacement && typeof value === "string" && isSafeAutoFix(probe, near[0])
+                        ? setFix(key, replacement, `Use "${replacement}"`)
+                        : {}),
+                });
+            }
+        }
+        if (taxonomy && !taxonomy.hierarchical) {
+            for (const term of terms) {
+                if (!term.includes("/"))
+                    continue;
+                out.push({
+                    severity: "warning",
+                    code: "frontmatter-nesting",
+                    message: `"${key}: ${term}" uses slash nesting, but the ${key} taxonomy is not hierarchical — it will be one flat term`,
+                    file: doc.path,
+                    ...at(key),
+                });
+            }
+        }
+    }
+    // the free-form `props:` bag, against the config's `propSchema`
+    const props = fm.props;
+    if (props && typeof props === "object" && !Array.isArray(props)) {
+        for (const [key, value] of Object.entries(props)) {
+            const spec = policy.propSchema[key];
+            if (!spec || value === null || value === undefined)
+                continue;
+            if (typeof value !== spec.type) {
+                out.push({
+                    severity: "error",
+                    code: "frontmatter-prop-type",
+                    message: `"props.${key}" should be ${spec.type}, got ${typeOf(value)}`,
+                    file: doc.path,
+                    ...at("props"),
+                });
+                continue;
+            }
+            if (spec.enum && !spec.enum.includes(String(value))) {
+                const near = nearMisses(String(value), spec.enum);
+                out.push({
+                    severity: "error",
+                    code: "frontmatter-prop-enum",
+                    message: `"props.${key}: ${String(value)}" is not one of ${spec.enum.join(", ")}`,
+                    file: doc.path,
+                    ...at("props"),
+                    ...(near.length ? { candidates: near } : {}),
+                });
+            }
+        }
+    }
+    // keys the multi-source build writes: a writer setting one by hand routes the page wrong
+    for (const key of AGGREGATOR_OWNED) {
+        if (fm[key] === undefined)
+            continue;
+        out.push({
+            severity: "warning",
+            code: "frontmatter-aggregator-owned",
+            message: `"${key}" is written by the multi-source build, not by hand — the build overwrites it, so setting it here has no effect`,
+            file: doc.path,
+            ...at(key),
+        });
+    }
+    for (const field of requiredFieldsFor(policy, doc.path)) {
+        const value = fm[field];
+        if (value === undefined || value === null || value === "") {
+            out.push({
+                severity: "error",
+                code: "frontmatter-required",
+                message: `"${field}" is required here but is ${value === undefined ? "missing" : "empty"}`,
+                file: doc.path,
+                ...at(field),
+            });
+        }
+    }
+    return out;
+}
+/** A site path is a page when a content root has it as `x.md`, `x/index.md`, `x.mdx` — or an existing FILE (an asset); `_`-prefixed segments are never routed (except `_assets`). */
+function resolveSitePath(index, layout, sitePath) {
+    const candidates = [];
+    let p = sitePath;
+    for (const pre of layout.prefixes)
+        if (p === pre || p.startsWith(pre + "/")) {
+            p = p.slice(pre.length).replace(/^\/+/, "");
+            break;
+        }
+    // `_`-prefixed segments are never routed by the build (fragments, includes) — except under `_assets/`, which is served
+    const hidden = (path) => {
+        if (path.startsWith("_assets/") || path.includes("/_assets/"))
+            return false;
+        return path.split("/").some((seg) => seg.startsWith("_"));
+    };
+    for (const root of layout.roots) {
+        const base = root ? `${root}/${p}` : p;
+        for (const c of [`${base}.md`, `${base}/index.md`, `${base}.mdx`]) {
+            candidates.push(c);
+            if (!hidden(c) && (index.docs.has(c) || index.maps.has(c)))
+                return { doc: index.docs.has(c) ? c : undefined, file: c, candidates };
+        }
+        candidates.push(base);
+        if (!hidden(base) && index.files.has(base))
+            return { file: base, candidates };
+    }
+    return { candidates };
+}
+export const validateCommand = defineCommand({
+    name: "validate",
+    writes: "none",
+    description: "Validate the workspace: links, anchors, includes, keys, and topic maps",
+    input,
+    async run(ctx) {
+        const index = await ctx.workspace.index();
+        const issues = [];
+        const layout = await siteLayout(ctx.workspace.storage);
+        const policy = await frontmatterPolicy(ctx.workspace.storage, layout);
+        // basename → workspace files with that name (a moved target is usually the same file elsewhere)
+        const byBase = new Map();
+        for (const f of index.files) {
+            const b = f.slice(f.lastIndexOf("/") + 1);
+            const list = byBase.get(b) ?? [];
+            list.push(f);
+            byBase.set(b, list);
+        }
+        // Basenames that say nothing about WHICH file was meant: a dead `old/index.md` must not be
+        // auto-pointed at whatever single other index.md exists. Listed as candidates, never fixed.
+        const GENERIC = new Set(["index.md", "_index.md", "readme.md", "overview.md", "introduction.md", "intro.md", "getting-started.md", "changelog.md"]);
+        const candidatesFor = (target, fromDoc) => (byBase.get(target.slice(target.lastIndexOf("/") + 1)) ?? []).filter((f) => f !== target && f !== fromDoc);
+        const autoFixable = (target, cands) => cands.length === 1 && !GENERIC.has(target.slice(target.lastIndexOf("/") + 1).toLowerCase());
+        /** A fix that rewrites one destination in `docPath`, when exactly one candidate exists. */
+        // `expect` = the hash of the bytes the problem was computed from: the verb refuses (stale-expect)
+        // if the file changed since, instead of retargeting whatever is there now
+        const retargetFix = (doc, href, line, newDest, label) => ({
+            fix: { verb: "link-retarget", args: { file: doc.path, from: href, to: newDest, ...(line !== undefined ? { line } : {}), expect: doc.hash }, label },
+        });
+        // The candidate is a REAL file name (decoded); a bare `](…)` destination cannot hold whitespace,
+        // parens or angle brackets, so the rewritten destination is percent-encoded the way the source
+        // href was (or, if the file name needs it, regardless) — a raw space would un-link the reference.
+        const destEncode = (dest, likeHref) => {
+            const needs = /[\s()<>]/.test(dest);
+            if (!needs && !/%[0-9A-Fa-f]{2}/.test(likeHref))
+                return dest;
+            return dest.split("/").map((seg) => encodeURIComponent(seg).replace(/%2F/g, "/")).join("/");
+        };
+        const relDest = (fromDoc, toFile, likeHref = "") => destEncode(relPath(dirOf(fromDoc) || ".", toFile), likeHref);
+        if (policy.invalid) {
+            issues.push({ severity: "error", code: "frontmatter-policy-invalid", message: policy.invalid, file: "dogsbay.config.yml" });
+        }
+        for (const doc of index.docs.values()) {
+            if (doc.parseError) {
+                issues.push({
+                    severity: "error",
+                    code: "doc-parse-failed",
+                    message: `cannot parse: ${doc.parseError}`,
+                    file: doc.path,
+                });
+                continue;
+            }
+            {
+                const fm = doc.frontmatter;
+                const isMapping = !!fm && typeof fm === "object" && !Array.isArray(fm);
+                const hasKeys = isMapping && Object.keys(fm).length > 0;
+                // no second read: the index carries the block's shape and key lines from its own pass
+                // A block that is not a MAPPING — a list, a scalar, tab-indented YAML — yields an array or
+                // `{}`, and EVERY field on the page is then ignored with no other symptom.
+                if (doc.frontmatterBlock === "unterminated") {
+                    // the parser treats the whole file as an unterminated block: no tree, no headings,
+                    // no links — the page renders EMPTY, and nothing else would report it
+                    issues.push({
+                        severity: "error",
+                        code: "frontmatter-unterminated",
+                        message: "the frontmatter block is never closed (`---` on its own line), so the entire page is read as frontmatter and renders empty",
+                        file: doc.path,
+                        line: 1,
+                    });
+                }
+                else if (!isMapping || (!hasKeys && !doc.frontmatterEmpty)) {
+                    // a YAML SYNTAX error (duplicate key, bad quoting) also lands here with `{}` —
+                    // the parser's own message and line say far more than "it is not a mapping"
+                    const yamlError = yamlErrorOf(await ctx.workspace.storage.read(doc.path).catch(() => ""));
+                    if (yamlError) {
+                        issues.push({
+                            severity: "error",
+                            code: "frontmatter-yaml-error",
+                            message: `the frontmatter is not valid YAML: ${yamlError.message}`,
+                            file: doc.path,
+                            line: yamlError.line,
+                        });
+                    }
+                    else
+                        issues.push({
+                            severity: "error",
+                            code: "frontmatter-not-a-mapping",
+                            message: `the frontmatter block is ${Array.isArray(fm) ? "a list" : "not a YAML mapping"} (it must be \`key: value\` pairs), so every field on this page is ignored`,
+                            file: doc.path,
+                            line: 1,
+                        });
+                }
+                else if (hasKeys || requiredFieldsFor(policy, doc.path).length) {
+                    issues.push(...frontmatterIssues(doc, doc.frontmatterKeyLines, policy));
+                }
+            }
+            for (const link of doc.links) {
+                const at = link.line !== undefined ? { line: link.line } : {};
+                if (link.siteAbsolute) {
+                    // `/guides/x` is resolved the way the SITE BUILD routes it: under the content roots
+                    // (dogsbay.config `content.sources[].path`, else the workspace root), basePath stripped,
+                    // as `x.md` / `x/index.md` / `x.mdx` or an existing asset file — the other half of link
+                    // checking (validate used to skip these; native corpora write every link this way)
+                    if (!layout.checkable)
+                        continue;
+                    const sitePath = link.sitePath ?? "";
+                    if (!sitePath)
+                        continue; // "/" — the home page
+                    const hit = resolveSitePath(index, layout, sitePath);
+                    if (!hit.file) {
+                        const cands = candidatesFor(`${sitePath}.md`);
+                        issues.push({
+                            severity: "warning",
+                            code: "link-site-absolute-unresolved",
+                            message: `${link.kind} "${link.href}" — no page or file at ${hit.candidates.slice(0, 3).join(", ")}${layout.roots[0] ? "" : " (workspace root taken as the content root)"}${cands.length ? ` (same name at: ${cands.slice(0, 3).join(", ")})` : ""}`,
+                            file: doc.path,
+                            ...at,
+                            ...(cands.length ? { candidates: cands } : {}),
+                        });
+                        continue;
+                    }
+                    const foundDoc = hit.doc ? index.docs.get(hit.doc) : undefined;
+                    if (link.fragment && foundDoc && !foundDoc.anchors.includes(link.fragment)) {
+                        const mismatch = anchorAliases(foundDoc.headings).has(link.fragment);
+                        const want = mismatch ? anchorAliasTargets(foundDoc.headings, foundDoc.anchors).get(link.fragment) : undefined;
+                        const pathPart = link.href.split("#")[0] ?? "";
+                        issues.push({
+                            severity: "warning",
+                            code: mismatch ? "link-anchor-rule-mismatch" : "link-anchor-missing",
+                            message: mismatch
+                                ? `link "${link.href}" — #${link.fragment} exists under another tool's heading-slug rule, but Dogsbay renders ${want ? `#${want}` : "a different anchor"} in ${hit.doc}`
+                                : `link "${link.href}" — no anchor #${link.fragment} in ${hit.doc}`,
+                            file: doc.path,
+                            ...at,
+                            ...(want ? retargetFix(doc, link.href, link.line, `${pathPart}#${want}`, `Use #${want}`) : {}),
+                        });
+                    }
+                    continue;
+                }
+                if (!link.target)
+                    continue; // external: not ours to check
+                if (link.escapes) {
+                    // it may well exist one level up — that is a different fact from "missing",
+                    // and the right fix (open the parent as the project, or move the file) differs
+                    issues.push({
+                        severity: "warning",
+                        code: "link-escapes-workspace",
+                        message: `${link.kind} "${link.href}" resolves outside the workspace root (${link.target}) — not checked`,
+                        file: doc.path,
+                        ...at,
+                    });
+                    continue;
+                }
+                const targetDoc = index.docs.get(link.target);
+                const targetExists = targetDoc !== undefined ||
+                    index.maps.has(link.target) ||
+                    (await ctx.workspace.storage.exists(link.target));
+                if (!targetExists) {
+                    const cands = candidatesFor(link.target, doc.path);
+                    const fragment = link.fragment ? `#${link.fragment}` : "";
+                    issues.push({
+                        severity: "error",
+                        code: link.kind === "image" ? "image-target-missing" : "link-target-missing",
+                        message: `${link.kind} "${link.href}" → ${link.target} does not exist${cands.length ? ` (same name at: ${cands.slice(0, 3).join(", ")})` : ""}`,
+                        file: doc.path,
+                        ...at,
+                        ...(cands.length ? { candidates: cands } : {}),
+                        ...(autoFixable(link.target, cands) ? retargetFix(doc, link.href, link.line, relDest(doc.path, cands[0], link.href) + fragment, `Point at ${cands[0]}`) : {}),
+                    });
+                    continue;
+                }
+                if (link.fragment && targetDoc && !targetDoc.anchors.includes(link.fragment)) {
+                    // the anchor may exist under ANOTHER renderer's slug rule (GitHub, mkdocs): a
+                    // migration-era mismatch the author's old toolchain accepted — say so, rather
+                    // than reporting a dead link that is not dead in their tool
+                    const aliases = anchorAliases(targetDoc.headings);
+                    if (aliases.has(link.fragment)) {
+                        const want = anchorAliasTargets(targetDoc.headings, targetDoc.anchors).get(link.fragment);
+                        const pathPart = link.href.split("#")[0] ?? "";
+                        issues.push({
+                            severity: "warning",
+                            code: "link-anchor-rule-mismatch",
+                            message: `link "${link.href}" — #${link.fragment} exists under another tool's heading-slug rule, but Dogsbay renders ${want ? `#${want}` : "a different anchor"} in ${link.target}`,
+                            file: doc.path,
+                            ...at,
+                            ...(want ? retargetFix(doc, link.href, link.line, `${pathPart}#${want}`, `Use #${want}`) : {}),
+                        });
+                    }
+                    else {
+                        issues.push({
+                            severity: "warning",
+                            code: "link-anchor-missing",
+                            message: `link "${link.href}" — no anchor #${link.fragment} in ${link.target}`,
+                            file: doc.path,
+                            ...at,
+                        });
+                    }
+                }
+            }
+            for (const include of doc.includes) {
+                // Out-of-root include (#027): the build's Minja pass REFUSES these
+                // (path containment), so flag them here where the failure is cheap
+                // to see — before a build dies on it. `..`-escapes keep their
+                // leading segments through normalizePath; absolute raws never
+                // resolve workspace-relative at all. Deliberately CONSERVATIVE:
+                // every absolute raw is flagged, including one whose filesystem
+                // path happens to sit inside the build root (which the build
+                // would allow) — validate has no filesystem-root context, and an
+                // absolute include is non-portable anyway. `..\`-style raws are
+                // caught for Windows-authored corpora (normalizePath splits on
+                // `/` only, so they never surface in `target`).
+                if (include.target.startsWith("../") || include.raw.startsWith("/") ||
+                    /^[A-Za-z]:[\\/]/.test(include.raw) || include.raw.startsWith("..\\")) {
+                    issues.push({
+                        severity: "error",
+                        code: "include-escapes-workspace",
+                        message: `{% include "${include.raw}" %} resolves outside the workspace — the build refuses out-of-root includes`,
+                        file: doc.path,
+                        ...(include.line !== undefined ? { line: include.line } : {}),
+                    });
+                    continue;
+                }
+                if (!(await ctx.workspace.storage.exists(include.target))) {
+                    const cands = candidatesFor(include.target, doc.path);
+                    issues.push({
+                        severity: "error",
+                        code: "include-target-missing",
+                        message: `{% include "${include.raw}" %} → ${include.target} does not exist${cands.length ? ` (same name at: ${cands.slice(0, 3).join(", ")})` : ""}`,
+                        file: doc.path,
+                        ...(include.line !== undefined ? { line: include.line } : {}),
+                        ...(cands.length ? { candidates: cands } : {}),
+                        ...(autoFixable(include.target, cands) ? retargetFix(doc, include.raw, include.line, relDest(doc.path, cands[0], include.raw), `Point at ${cands[0]}`) : {}),
+                    });
+                }
+            }
+            for (const name of doc.keyUses) {
+                if (!index.keys.has(name)) {
+                    issues.push({
+                        severity: "error",
+                        code: "key-undefined",
+                        message: `key "${name}" is referenced but defined in no keys file`,
+                        file: doc.path,
+                    });
+                }
+            }
+        }
+        for (const [name, defs] of index.keys) {
+            if (defs.length > 1) {
+                issues.push({
+                    severity: "warning",
+                    code: "key-conflict",
+                    message: `key "${name}" defined ${defs.length} times (${defs.map((d) => d.file).join(", ")}) — first wins`,
+                    file: defs[0].file,
+                });
+            }
+        }
+        for (const err of index.keyFileErrors) {
+            issues.push({
+                severity: "error",
+                code: "keys-file-invalid",
+                message: err.message,
+                file: err.file,
+            });
+        }
+        for (const map of index.maps.values()) {
+            for (const err of map.errors) {
+                issues.push({
+                    severity: "error",
+                    code: `topicmap-${err.code}`,
+                    message: err.message,
+                    file: err.mapPath || map.path,
+                });
+            }
+        }
+        // Root-aware walk over the map include graph. "/"-rooted hrefs
+        // resolve against the ROOT map's directory (the topicmap loader
+        // convention), so target-existence and cycle checks must carry the
+        // root dir through the graph — a per-map loop can't see them.
+        // Maps unreachable from any root still get their RELATIVE refs
+        // checked; their "/"-rooted refs are skipped (no root, no meaning).
+        const includedByRelative = new Set();
+        for (const map of index.maps.values()) {
+            for (const ref of map.refs) {
+                if (ref.isMap && ref.target)
+                    includedByRelative.add(ref.target);
+            }
+        }
+        const roots = [...index.maps.keys()].filter((path) => !includedByRelative.has(path));
+        const visited = new Set();
+        const reportedCycles = new Set();
+        const reportedMissing = new Set();
+        const walkMaps = async (path, rootDir, trail, resolveRootRelative) => {
+            if (trail.includes(path)) {
+                const cycle = [...trail.slice(trail.indexOf(path)), path];
+                const key = [...cycle].sort().join("→");
+                if (!reportedCycles.has(key)) {
+                    reportedCycles.add(key);
+                    issues.push({
+                        severity: "error",
+                        code: "topicmap-cycle",
+                        message: `circular topic map include: ${cycle.join(" → ")}`,
+                        file: path,
+                    });
+                }
+                return;
+            }
+            const wasVisited = visited.has(path);
+            visited.add(path);
+            const entry = index.maps.get(path);
+            for (const ref of entry?.refs ?? []) {
+                let target = ref.target;
+                if (!target && ref.rootRelative && resolveRootRelative) {
+                    target = joinPath(rootDir, ref.href.replace(/^\/+/, ""));
+                }
+                if (!target)
+                    continue; // external, or root-relative with no known root
+                if (!wasVisited) {
+                    const missingKey = `${path}|${ref.href}`;
+                    if (!reportedMissing.has(missingKey) &&
+                        !(await ctx.workspace.storage.exists(target))) {
+                        reportedMissing.add(missingKey);
+                        issues.push({
+                            severity: "error",
+                            code: "topicmap-target-missing",
+                            message: `entry "${ref.href}" → ${target} does not exist`,
+                            file: path,
+                        });
+                    }
+                }
+                // Recurse into unvisited maps; ALSO re-enter a map already on
+                // the current trail so the cycle gets reported (visited alone
+                // would skip it — that's only correct for diamonds)
+                if (ref.isMap &&
+                    index.maps.has(target) &&
+                    (!visited.has(target) || trail.includes(target))) {
+                    await walkMaps(target, rootDir, [...trail, path], resolveRootRelative);
+                }
+            }
+        };
+        for (const root of roots) {
+            await walkMaps(root, dirnameOf(root), [], true);
+        }
+        for (const path of index.maps.keys()) {
+            if (!visited.has(path))
+                await walkMaps(path, dirnameOf(path), [], false);
+        }
+        // the same href twice in one file is one finding (70% of rows on a real corpus were duplicates)
+        const seen = new Set();
+        const unique = issues.filter((i) => {
+            const k = `${i.severity}|${i.code}|${i.file ?? ""}|${i.line ?? ""}|${i.message}`;
+            if (seen.has(k))
+                return false;
+            seen.add(k);
+            return true;
+        });
+        issues.length = 0;
+        issues.push(...unique);
+        const errors = issues.filter((issue) => issue.severity === "error").length;
+        const warnings = issues.length - errors;
+        return {
+            data: {
+                checked: index.stats,
+                errors,
+                warnings,
+                issues,
+            },
+            issues,
+            summary: issues.length === 0
+                ? `workspace clean — ${index.stats.docs} doc(s), ${index.stats.maps} map(s), ${index.stats.keys} key(s)`
+                : `${errors} error(s), ${warnings} warning(s) across ${index.stats.docs} doc(s)`,
+        };
+    },
+});
+//# sourceMappingURL=validate.js.map