doc-detective 4.38.0 → 4.41.4

package/dist/core/verification.js

@@ -0,0 +1,850 @@
+import crypto from "node:crypto";
+import { requireYaml } from "./lazyYaml.js";
+// ===========================================================================
+// Verification metadata write-back (ADR 01140).
+//
+// A page opts in by listing a `verified-by` entry with `tool: doc-detective`
+// and a `check` naming a test or spec id, either in its front matter or in an
+// inline `meta` statement. When that check passes, Doc Detective fills the
+// entry's `version` and `passed`, and sets `last-verified` to the oldest
+// `passed` across the entries once every entry has one. Other tools' entries
+// are never touched, and nothing is written on any other result.
+//
+// The keys are manni's shared vocabulary (manni:stewardship 1.2.0, proposal
+// 0098), and the inline form is manni's `meta` statement (proposal 0099). The
+// statement scanner, anchoring and pin below port manni's own rules
+// (src/shared/statements.ts and src/meta/core/statements.ts), so a pin written
+// here is the pin `manni meta derive` writes. test/verification-fixtures/ holds
+// pages pinned by manni, and the tests check this port against them.
+// ===========================================================================
+export const VERIFIED_TOOL = "doc-detective";
+const TOOL = VERIFIED_TOOL;
+// Apply edits made against one text, in order; edits at one offset keep the
+// order they were made in.
+// Precondition: edits never overlap. Every caller edits disjoint node ranges or
+// inserts at a point; an overlapping edit would drop the text between them, so
+// it throws instead, and the writer's per-file guard leaves the file untouched.
+function applyEdits(text, edits) {
+    const sorted = edits.map((e, i) => ({ ...e, i })).sort((a, b) => a.start - b.start || a.i - b.i);
+    let out = "";
+    let pos = 0;
+    for (const e of sorted) {
+        if (e.start < pos)
+            throw new Error(`overlapping edits at offset ${e.start}`);
+        out += text.slice(pos, e.start) + e.text;
+        pos = e.end;
+    }
+    return out + text.slice(pos);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// The oldest of the entries' pass dates, or undefined when any entry has none.
+function oldest(values) {
+    let best;
+    let bestTime = Infinity;
+    for (const value of values) {
+        if (value === undefined)
+            return undefined;
+        const time = Date.parse(value);
+        if (Number.isNaN(time))
+            return undefined;
+        if (time < bestTime) {
+            best = value;
+            bestTime = time;
+        }
+    }
+    return best;
+}
+// Fill every doc-detective entry whose check passed. Returns whether any did,
+// and each entry's pass date afterwards, read through `passedOf`.
+function fillEntries(entries, read, fill, opts) {
+    let any = false;
+    const passed = entries.map((entry) => {
+        const e = read(entry);
+        if (!e)
+            return undefined;
+        if (e.tool !== TOOL || typeof e.check !== "string")
+            return e.passed;
+        const result = opts.resolve(e.check);
+        if (result === null)
+            opts.onUnknown?.(e.check);
+        if (result !== "PASS")
+            return e.passed;
+        fill(entry);
+        any = true;
+        return opts.today;
+    });
+    return { any, passed };
+}
+// --------------------------------------------------------------------------
+// Front matter
+// --------------------------------------------------------------------------
+const FRONT_MATTER = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)^---[ \t]*$/m;
+function frontMatter(content) {
+    const fm = FRONT_MATTER.exec(content);
+    if (!fm || fm.index !== 0)
+        return undefined;
+    const start = fm[0].indexOf("\n") + 1;
+    return { start, src: fm[1], end: fm[0].length };
+}
+// Set `key` on a YAML map as a text edit: replace the value in place (keeping
+// its quotes), or add the key at the end of the map, in its style.
+function setKey(src, map, key, value, eol, edits) {
+    const YAML = requireYaml();
+    const pair = map.items.find((p) => YAML.isScalar(p.key) && p.key.value === key);
+    if (pair) {
+        const v = pair.value;
+        if (!YAML.isScalar(v) || !v.range || String(v.value) === value)
+            return;
+        const quote = src[v.range[0]];
+        const text = quote === '"' || quote === "'" ? `${quote}${value}${quote}` : value;
+        // A key with no value (`passed:`) has a zero-length value range right after
+        // its colon, so the value needs a separating space.
+        const gap = v.range[0] === v.range[1] && !/\s/.test(src[v.range[0] - 1] ?? "") ? " " : "";
+        edits.push({ start: v.range[0], end: v.range[1], text: `${gap}${text}` });
+        return;
+    }
+    if (map.flow) {
+        const close = src.lastIndexOf("}", map.range[1] - 1);
+        edits.push({ start: close, end: close, text: `${map.items.length > 0 ? ", " : ""}${key}: ${value}` });
+        return;
+    }
+    const { at, indent } = blockEnd(src, map);
+    edits.push({ start: at, end: at, text: `${eol}${indent}${key}: ${value}` });
+}
+// Where a block map or sequence's last line ends (past any trailing comment,
+// before its line break), and the indent its items start at. Callers pass only
+// block-style nodes, which always hold an item: an empty one parses as flow
+// (`[]`, `{}`) or null, and both take other paths.
+function blockEnd(src, node) {
+    const YAML = requireYaml();
+    const last = node.items[node.items.length - 1];
+    const tail = YAML.isPair(last) ? (last.value?.range ? last.value : last.key) : last;
+    let end = tail.range[1];
+    while (end > 0 && /\s/.test(src[end - 1]))
+        end--;
+    const nl = src.indexOf("\n", end);
+    const at = nl === -1 ? src.length : src[nl - 1] === "\r" ? nl - 1 : nl;
+    const column = node.range[0] - (src.lastIndexOf("\n", node.range[0] - 1) + 1);
+    return { at, indent: " ".repeat(column) };
+}
+// `verification.write: true`: give a passing page with no Doc Detective entry
+// a `verified-by` entry naming its spec, for the fill to complete in the same
+// run. The entry goes at the end of an existing list, or of the front matter,
+// in its style; a page without front matter gets a block. A page that already
+// names doc-detective, or whose front matter isn't a YAML map, is unchanged.
+export function declarePage(content, specId) {
+    const check = /^[A-Za-z0-9._/-]+$/.test(specId) ? specId : JSON.stringify(specId);
+    const fm = frontMatter(content);
+    const eol = (fm ? content.slice(0, fm.end) : content).includes("\r\n") ? "\r\n" : "\n";
+    const item = (indent) => `${indent}- tool: ${TOOL}${eol}${indent}  check: ${check}`;
+    if (!fm) {
+        const bom = content.charCodeAt(0) === 0xfeff ? "\uFEFF" : "";
+        return `${bom}---${eol}verified-by:${eol}${item("  ")}${eol}---${eol}${content.slice(bom.length)}`;
+    }
+    const YAML = requireYaml();
+    const doc = YAML.parseDocument(fm.src);
+    if (doc.errors.length > 0)
+        return content;
+    const root = doc.contents;
+    const edits = [];
+    if (root === null) {
+        edits.push({ start: 0, end: 0, text: `verified-by:${eol}${item("  ")}${eol}` });
+    }
+    else if (!YAML.isMap(root)) {
+        return content;
+    }
+    else {
+        const list = root.get("verified-by", true);
+        if (list === undefined) {
+            if (root.flow) {
+                const close = fm.src.lastIndexOf("}", root.range[1] - 1);
+                const text = `${root.items.length > 0 ? ", " : ""}verified-by: [{tool: ${TOOL}, check: ${check}}]`;
+                edits.push({ start: close, end: close, text });
+            }
+            else {
+                const { at, indent } = blockEnd(fm.src, root);
+                edits.push({ start: at, end: at, text: `${eol}${indent}verified-by:${eol}${item(`${indent}  `)}` });
+            }
+        }
+        else if (!YAML.isSeq(list)) {
+            return content;
+        }
+        else if (list.items.some((i) => YAML.isMap(i) && i.get("tool") === TOOL)) {
+            return content;
+        }
+        else if (list.flow) {
+            const close = fm.src.lastIndexOf("]", list.range[1] - 1);
+            const text = `${list.items.length > 0 ? ", " : ""}{tool: ${TOOL}, check: ${check}}`;
+            edits.push({ start: close, end: close, text });
+        }
+        else {
+            const { at, indent } = blockEnd(fm.src, list);
+            edits.push({ start: at, end: at, text: `${eol}${item(indent)}` });
+        }
+    }
+    return content.slice(0, fm.start) + applyEdits(fm.src, edits) + content.slice(fm.start + fm.src.length);
+}
+function writeFrontMatter(content, opts) {
+    const fm = frontMatter(content);
+    if (!fm || !fm.src.includes("verified-by"))
+        return content;
+    const YAML = requireYaml();
+    const doc = YAML.parseDocument(fm.src);
+    if (doc.errors.length > 0 || !YAML.isMap(doc.contents))
+        return content;
+    const root = doc.contents;
+    const list = root.get("verified-by", true);
+    if (!YAML.isSeq(list))
+        return content;
+    const eol = fm.src.includes("\r\n") ? "\r\n" : "\n";
+    const edits = [];
+    const { any, passed } = fillEntries(list.items, (item) => {
+        if (!YAML.isMap(item))
+            return undefined;
+        const p = item.get("passed", true);
+        return { tool: item.get("tool"), check: item.get("check"), passed: YAML.isScalar(p) ? String(p.value) : undefined };
+    }, (item) => {
+        // Keys the entry already has go first. An empty `passed:` that ends the
+        // entry shares its offset with the line a new key is appended on, and its
+        // value must land before that line.
+        const values = [
+            ["version", opts.version],
+            ["passed", opts.today],
+        ];
+        values.sort(([a], [b]) => Number(!item.has(a)) - Number(!item.has(b)));
+        for (const [key, value] of values)
+            setKey(fm.src, item, key, value, eol, edits);
+    }, opts);
+    if (!any)
+        return content;
+    const last = oldest(passed);
+    if (last !== undefined)
+        setKey(fm.src, root, "last-verified", last, eol, edits);
+    if (edits.length === 0)
+        return content;
+    return content.slice(0, fm.start) + applyEdits(fm.src, edits) + content.slice(fm.start + fm.src.length);
+}
+// --------------------------------------------------------------------------
+// Inline `meta` statements: a port of manni's scanner, anchoring and pin.
+// --------------------------------------------------------------------------
+// The citations hashing rule: lines joined with LF, one BOM stripped, CRLF
+// folded to LF, no trailing LF, as `sha256-<hex>`.
+export function pinOf(lines) {
+    let text = lines.join("\n");
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    text = text.replace(/\r\n/g, "\n");
+    return `sha256-${crypto.createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+const HTML_COMMENT = { open: "<!--", close: "-->" };
+const JSX_COMMENT = { open: "{/*", close: "*/}" };
+const LINK_REFERENCE = { open: "[comment]: # (", close: ")" };
+const PI_FORM = { open: "<?manni", close: "?>" };
+const FORMS = {
+    markdown: [HTML_COMMENT, JSX_COMMENT, LINK_REFERENCE],
+    html: [HTML_COMMENT],
+    asciidoc: [{ open: "// (", close: ")" }],
+    dita: [PI_FORM, HTML_COMMENT],
+};
+// cite's marker forms, which also count as marker-only lines when anchoring.
+const CITE_FORMS = { ...FORMS, dita: [HTML_COMMENT] };
+const isLineForm = (form) => form.close === ")";
+function lineEnd(content, pos) {
+    const nl = content.indexOf("\n", pos);
+    return nl === -1 ? content.length : nl;
+}
+function lineText(content, pos, end) {
+    const text = content.slice(pos, end);
+    return text.endsWith("\r") ? text.slice(0, -1) : text;
+}
+function beforeCr(content, end) {
+    return end > 0 && content.charCodeAt(end - 1) === 13 ? end - 1 : end;
+}
+function nextLineStart(content, offset) {
+    if (offset === 0 || content.charCodeAt(offset - 1) === 10)
+        return offset;
+    return lineEnd(content, offset) + 1;
+}
+function lineAt(content, offset) {
+    let line = 1;
+    const stop = Math.min(offset, content.length);
+    for (let at = content.indexOf("\n"); at !== -1 && at < stop; at = content.indexOf("\n", at + 1))
+        line++;
+    return line;
+}
+function offsetOfLine(content, line) {
+    let pos = 0;
+    for (let n = 1; n < line; n++) {
+        const nl = content.indexOf("\n", pos);
+        if (nl === -1)
+            return content.length;
+        pos = nl + 1;
+    }
+    return pos;
+}
+const isCite = (inner) => inner === "cite" || (inner.startsWith("cite") && /\s/.test(inner.charAt(4)));
+const isMetaKeyword = (inner) => inner === "meta" || (inner.startsWith("meta") && /\s/.test(inner.charAt(4)));
+function isMarkerLine(line, format) {
+    const text = line.trim();
+    const cite = (CITE_FORMS[format] || []).some((form) => {
+        if (text.length < form.open.length + form.close.length || !text.startsWith(form.open))
+            return false;
+        const closeAt = text.indexOf(form.close, form.open.length);
+        if (closeAt !== text.length - form.close.length)
+            return false;
+        return isCite(text.slice(form.open.length, closeAt).trim());
+    });
+    if (cite)
+        return true;
+    return (FORMS[format] || []).some((form) => {
+        if (text.length < form.open.length + form.close.length)
+            return false;
+        if (!text.startsWith(form.open) || !text.endsWith(form.close))
+            return false;
+        const closeAt = isLineForm(form) ? text.length - form.close.length : text.indexOf(form.close, form.open.length);
+        if (closeAt !== text.length - form.close.length)
+            return false;
+        return isMetaKeyword(text.slice(form.open.length, closeAt).trim());
+    });
+}
+const ATX_HEADING = /^[ \t]*#{1,6}([ \t]|$)/;
+const ASCIIDOC_TITLE = /^={1,6}[ \t]/;
+const ADORNMENT = /^[ \t]*([-=~^"'*+#_:<>])(?:[ \t]*\1){2,}[ \t]*$/;
+const TAG_LINE = /^[ \t]*<\/?[A-Za-z][^<>]*>[ \t]*$/;
+function isBoundLine(line, format) {
+    if (ADORNMENT.test(line))
+        return true;
+    if (format === "markdown")
+        return ATX_HEADING.test(line) || TAG_LINE.test(line);
+    if (format === "html")
+        return TAG_LINE.test(line);
+    if (format === "asciidoc")
+        return ASCIIDOC_TITLE.test(line);
+    return false;
+}
+// manni's one block rule (`src/shared/code-regions.ts`), which anchoring and
+// the code skip both read. A Markdown fence opens after any indent and closes
+// on a bare run of its character at least as long. An AsciiDoc delimited
+// block closes only on an exact repeat of its opener line. Its content is
+// code in a verbatim block (`----`, `....`, `++++`, `////`) and prose in a
+// compound one (`====`, `****`, `____`).
+const ANY_FENCE = /^(?:[ \t]*(?:`{3,}|~{3,})|-{4,})/;
+const FENCE_OPENER = /^[ \t]*(`{3,}|~{3,})/;
+const ASCIIDOC_DELIMITER = /^([-.+/=*_])\1{3,}[ \t]*$/;
+const VERBATIM = new Set(["-", ".", "+", "/"]);
+// A line a two-line title can be, so a `=` line under it is its underline.
+const TITLE_TEXT = /^[^\s./[]/;
+function asciidocBlock(line, above) {
+    const char = ASCIIDOC_DELIMITER.exec(line)?.[1];
+    if (char === undefined)
+        return undefined;
+    if (char === "=" && above !== undefined && TITLE_TEXT.test(above)) {
+        if (Math.abs(above.trimEnd().length - line.trimEnd().length) <= 2)
+            return undefined;
+    }
+    return VERBATIM.has(char) ? "verbatim" : "compound";
+}
+function closesFence(line, open) {
+    const trimmed = line.trim();
+    let n = 0;
+    while (trimmed.charAt(n) === open.charAt(0))
+        n++;
+    return n >= open.length && n === trimmed.length;
+}
+// What closes the block `line` opens, or undefined when it opens none. The
+// code skip reads verbatim blocks only; anchoring passes `compound` to read
+// every block, and `above` to tell a title's `=` underline from a block.
+function blockCloser(line, format, options = {}) {
+    if (format === "markdown") {
+        const run = FENCE_OPENER.exec(line)?.[1];
+        return run === undefined ? undefined : (l) => closesFence(l, run);
+    }
+    if (format === "asciidoc") {
+        const kind = asciidocBlock(line, options.above);
+        if (kind === undefined || (kind === "compound" && options.compound !== true))
+            return undefined;
+        const open = line.trimEnd();
+        return (l) => l.trimEnd() === open;
+    }
+    return undefined;
+}
+// Whether a line ends a paragraph as a fence or a block delimiter.
+function isFenceLine(line, format, above) {
+    return ANY_FENCE.test(line) || (format === "asciidoc" && asciidocBlock(line, above) !== undefined);
+}
+function lineBefore(content, pos) {
+    if (pos === 0)
+        return undefined;
+    const start = content.lastIndexOf("\n", pos - 2) + 1;
+    return lineText(content, start, pos - 1);
+}
+function paragraphAfter(content, offset, format) {
+    let pos = offset;
+    const firstEnd = lineEnd(content, pos);
+    if (lineText(content, pos, firstEnd).trim() === "")
+        pos = firstEnd + 1;
+    while (pos < content.length) {
+        const end = lineEnd(content, pos);
+        const text = lineText(content, pos, end);
+        if (text.trim() === "" || isMarkerLine(text, format)) {
+            pos = end + 1;
+            continue;
+        }
+        if (isFenceLine(text, format, lineBefore(content, pos)))
+            return undefined;
+        const start = pos;
+        let last = end;
+        let cursor = isBoundLine(text, format) ? content.length : end + 1;
+        while (cursor < content.length) {
+            const e = lineEnd(content, cursor);
+            const t = lineText(content, cursor, e);
+            if (t.trim() === "" || isFenceLine(t, format) || isMarkerLine(t, format) || isBoundLine(t, format))
+                break;
+            last = e;
+            cursor = e + 1;
+        }
+        return { end: beforeCr(content, last), line: lineAt(content, start) };
+    }
+    return undefined;
+}
+// The block opening on `line`, delimiters included: a fence at any indent, or
+// any AsciiDoc delimited block. Undefined when it opens none or never closes.
+function fenceSpanAt(content, line, format) {
+    const pos = offsetOfLine(content, line);
+    const above = lineBefore(content, pos);
+    const closes = blockCloser(lineText(content, pos, lineEnd(content, pos)), format, { above, compound: true });
+    if (closes === undefined)
+        return undefined;
+    let cursor = Math.min(lineEnd(content, pos) + 1, content.length);
+    while (cursor < content.length) {
+        const e = lineEnd(content, cursor);
+        if (closes(lineText(content, cursor, e)))
+            return { start: line, end: lineAt(content, cursor) };
+        cursor = e + 1;
+    }
+    return undefined;
+}
+// The lines a statement ending at `after` anchors: the rest of its own line
+// when that carries text, else the paragraph or fenced block that follows.
+function anchoredLines(content, after, format) {
+    const restEnd = lineEnd(content, after);
+    if (content.slice(after, restEnd).trim() !== "") {
+        const line = lineAt(content, after);
+        return { start: line, end: line };
+    }
+    const paragraph = paragraphAfter(content, after, format);
+    if (paragraph !== undefined)
+        return { start: paragraph.line, end: lineAt(content, paragraph.end) };
+    let pos = nextLineStart(content, after);
+    while (pos < content.length) {
+        const end = lineEnd(content, pos);
+        const text = lineText(content, pos, end);
+        if (text.trim() !== "" && !isMarkerLine(text, format))
+            return fenceSpanAt(content, lineAt(content, pos), format);
+        pos = end + 1;
+    }
+    return undefined;
+}
+// Verbatim blocks and backtick spans, where no statement is read.
+function codeRegions(text, format) {
+    const spans = format === "markdown" || format === "asciidoc";
+    const out = [];
+    if (!spans)
+        return out;
+    let open;
+    let pos = 0;
+    while (pos < text.length) {
+        const nl = text.indexOf("\n", pos);
+        const end = nl === -1 ? text.length : nl;
+        const line = lineText(text, pos, end);
+        if (open) {
+            if (open.closes(line)) {
+                out.push({ start: open.start, end });
+                open = undefined;
+            }
+        }
+        else {
+            const closes = blockCloser(line, format);
+            if (closes !== undefined)
+                open = { closes, start: pos };
+            else
+                spanRegions(line, pos, out);
+        }
+        pos = end + 1;
+    }
+    if (open)
+        out.push({ start: open.start, end: text.length });
+    return out;
+}
+function spanRegions(line, lineStart, out) {
+    const run = (i) => {
+        let n = 0;
+        while (line.charCodeAt(i + n) === 96)
+            n++;
+        return n;
+    };
+    let i = 0;
+    while (i < line.length) {
+        const n = run(i);
+        if (n === 0) {
+            i++;
+            continue;
+        }
+        let j = i + n;
+        let closer = -1;
+        while (j < line.length) {
+            const m = run(j);
+            if (m === 0)
+                j++;
+            else if (m === n) {
+                closer = j;
+                break;
+            }
+            else
+                j += m;
+        }
+        if (closer === -1) {
+            i += n;
+            continue;
+        }
+        out.push({ start: lineStart + i, end: lineStart + closer + n });
+        i = closer + n;
+    }
+}
+const PIN_TOKEN = /^sha256-[0-9a-f]{64}$/;
+function parseStatements(content, from, format) {
+    const body = content.slice(from);
+    const code = codeRegions(body, format);
+    const out = [];
+    for (const form of FORMS[format] || []) {
+        let cursor = 0;
+        for (;;) {
+            const at = body.indexOf(form.open, cursor);
+            if (at === -1)
+                break;
+            const region = code.find((r) => at >= r.start && at < r.end);
+            if (region) {
+                cursor = region.end;
+                continue;
+            }
+            const innerStart = at + form.open.length;
+            const closeAt = isLineForm(form) ? body.lastIndexOf(form.close, lineEnd(body, at)) : body.indexOf(form.close, innerStart);
+            if (closeAt === -1 || closeAt < innerStart) {
+                cursor = innerStart;
+                continue;
+            }
+            cursor = closeAt + form.close.length;
+            const inner = body.slice(innerStart, closeAt);
+            if (!isMetaKeyword(inner.trim()))
+                continue;
+            const lead = /^\s*meta\s*/.exec(inner)?.[0] ?? "";
+            const rest = inner.slice(lead.length);
+            const word = /^\S+/.exec(rest)?.[0] ?? "";
+            const pinned = PIN_TOKEN.test(word);
+            const payload = (pinned ? rest.slice(word.length) : rest).trim();
+            out.push({
+                line: lineAt(content, from + at),
+                start: from + at,
+                end: from + cursor,
+                pinAt: from + innerStart + lead.length,
+                closeAt: from + closeAt,
+                pin: pinned ? word : undefined,
+                payload,
+                broken: isLineForm(form) && payload.includes(")")
+                    ? `its line comment ends at the first ")"; use a block comment form`
+                    : format === "dita" && form === HTML_COMMENT && payload.includes("--")
+                        ? `an XML comment can't hold "--"; use <?manni meta …?>`
+                        : "",
+            });
+        }
+    }
+    return out.sort((a, b) => a.start - b.start);
+}
+// DITA's `<data name="manni-meta" value='…'/>` carriers, read as manni's
+// `dataStatement` reads them: the tag's own `name` and `value` attributes,
+// parsed whole so `data-name` or text inside another value never counts, the
+// value's entities decoded, an optional pin, then the payload.
+const ATTRIBUTE = /([^\s=/>"']+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+// A start tag's attributes, first occurrence wins; `at` is the value's first
+// character in `tag`, just past its opening quote.
+function attributesOf(tag) {
+    const out = new Map();
+    const from = /^<[^\s/>]*/.exec(tag)?.[0].length ?? 0;
+    for (const m of tag.slice(from).matchAll(ATTRIBUTE)) {
+        const [whole, name = "", double, single] = m;
+        const value = double ?? single ?? "";
+        if (!out.has(name))
+            out.set(name, { value, at: from + m.index + whole.length - value.length - 1 });
+    }
+    return out;
+}
+const isCarrier = (tag) => attributesOf(tag).get("name")?.value === "manni-meta";
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|quot|apos|lt|gt|amp);/g, (_m, e) => {
+        if (e.startsWith("#x"))
+            return String.fromCodePoint(Number.parseInt(e.slice(2), 16));
+        if (e.startsWith("#"))
+            return String.fromCodePoint(Number.parseInt(e.slice(1), 10));
+        return { quot: '"', apos: "'", lt: "<", gt: ">", amp: "&" }[e] ?? "";
+    });
+}
+function dataStatements(content) {
+    const out = [];
+    for (let at = content.indexOf("<data"); at !== -1; at = content.indexOf("<data", at + 5)) {
+        if (!/[\s/>]/.test(content.charAt(at + 5)))
+            continue; // `<data`, not `<datalist`
+        const tag = startTagEnd(content, at);
+        if (!tag)
+            continue;
+        const attributes = attributesOf(content.slice(at, tag.end));
+        const value = attributes.get("value");
+        if (attributes.get("name")?.value !== "manni-meta" || value === undefined)
+            continue;
+        const open = at + value.at;
+        const close = open + value.value.length;
+        const raw = value.value;
+        const lead = /^\s*/.exec(raw)?.[0] ?? "";
+        const rest = decodeEntities(raw.slice(lead.length));
+        const word = /^\S+/.exec(rest)?.[0] ?? "";
+        const pinned = PIN_TOKEN.test(word);
+        out.push({
+            line: lineAt(content, at),
+            start: at,
+            end: tag.end,
+            pinAt: open + lead.length,
+            closeAt: close,
+            pin: pinned ? word : undefined,
+            payload: (pinned ? rest.slice(word.length) : rest).trim(),
+            broken: "",
+            quote: content.charAt(open - 1),
+        });
+    }
+    return out;
+}
+// Text for an XML attribute value quoted with `quote`.
+function escapeAttribute(text, quote) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(quote === "'" ? /'/g : /"/g, quote === "'" ? "&apos;" : "&quot;");
+}
+function startTagEnd(source, at) {
+    let quote;
+    for (let i = at + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (quote !== undefined) {
+            if (ch === quote)
+                quote = undefined;
+        }
+        else if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === ">")
+            return { end: i + 1, selfClosing: source[i - 1] === "/" };
+    }
+    return undefined;
+}
+function scanXml(content, statements) {
+    const root = { kind: "element", name: "#document", start: 0, end: content.length, children: [] };
+    let current = root;
+    let i = 0;
+    const push = (node) => {
+        node.parent = current;
+        current.children.push(node);
+    };
+    const skipTo = (needle, from) => {
+        const at = content.indexOf(needle, from);
+        return at === -1 ? content.length : at + needle.length;
+    };
+    while (i < content.length) {
+        const lt = content.indexOf("<", i);
+        if (lt === -1 || lt > i) {
+            const end = lt === -1 ? content.length : lt;
+            push({ kind: "text", name: "#text", start: i, end, children: [], blank: content.slice(i, end).trim() === "" });
+            i = end;
+            continue;
+        }
+        let end;
+        if (content.startsWith("<!--", i))
+            end = skipTo("-->", i + 4);
+        else if (content.startsWith("<![CDATA[", i)) {
+            end = skipTo("]]>", i + 9);
+            push({ kind: "text", name: "#cdata", start: i, end, children: [] });
+            i = end;
+            continue;
+        }
+        else if (content.startsWith("<?", i))
+            end = skipTo("?>", i + 2);
+        else if (content.startsWith("<!", i)) {
+            const bracket = content.indexOf("[", i);
+            const gt = content.indexOf(">", i);
+            end = bracket !== -1 && gt !== -1 && bracket < gt ? skipTo(">", skipTo("]", bracket)) : skipTo(">", i);
+        }
+        else if (content.startsWith("</", i)) {
+            end = skipTo(">", i);
+            current.end = end;
+            current = current.parent ?? root;
+            i = end;
+            continue;
+        }
+        else {
+            const tag = startTagEnd(content, i);
+            const name = /^<([^\s/>]+)/.exec(content.slice(i, i + 256))?.[1];
+            if (tag === undefined || name === undefined) {
+                i += 1;
+                continue;
+            }
+            const node = { kind: "element", name, start: i, end: tag.end, children: [] };
+            // DITA's <data name="manni-meta"> carrier is a statement too.
+            if (name === "data" && isCarrier(content.slice(i, tag.end)))
+                node.statement = true;
+            push(node);
+            if (!tag.selfClosing) {
+                node.end = content.length;
+                current = node;
+            }
+            i = tag.end;
+            continue;
+        }
+        push({ kind: "other", name: "#other", start: i, end, children: [], statement: statements.has(i) });
+        i = end;
+    }
+    return root;
+}
+function* walk(node) {
+    yield node;
+    for (const child of node.children)
+        yield* walk(child);
+}
+function xmlAnchors(content, statements) {
+    const byStart = new Map(statements.map((s) => [s.start, s]));
+    const tree = scanXml(content, new Set(byStart.keys()));
+    const spans = [...walk(tree)].filter((n) => n.statement === true).map(({ start, end }) => ({ start, end }));
+    const ignorable = (n) => n.kind === "other" || n.blank === true || n.statement === true;
+    const titleOf = (n) => n.children.find((c) => c.kind === "element" && c.name === "title");
+    const linesOf = (n) => ({ start: lineAt(content, n.start), end: lineAt(content, Math.max(n.start, n.end - 1)) });
+    const out = new Map();
+    for (const node of walk(tree)) {
+        // An instruction or comment statement, or a `<data>` carrier.
+        const s = node.statement ? byStart.get(node.start) : undefined;
+        if (!s)
+            continue;
+        const parent = node.parent ?? tree;
+        const index = parent.children.indexOf(node);
+        const firstChild = parent !== tree && parent.children.slice(0, index).every(ignorable);
+        const next = parent.children.slice(index + 1).find((c) => c.kind === "element" && c.statement !== true);
+        const owner = firstChild ? parent : next?.name === "title" ? parent : undefined;
+        const title = owner === undefined || owner === tree ? undefined : titleOf(owner);
+        if (title)
+            out.set(s, linesOf(title));
+        else if (firstChild)
+            out.set(s, linesOf(parent));
+        else if (next)
+            out.set(s, linesOf(next));
+    }
+    return { anchors: out, spans };
+}
+// The anchored lines as a pin hashes them, by manni's `anchoredText`
+// (proposal 0101). Every statement inside the lines is cut out first, the
+// anchoring one and any other, so a tool writing into a statement never
+// changes a pin over it. `spans` are every statement on the page, in document
+// order. A line that held a statement and is blank after the cut is dropped,
+// so moving a statement onto or off its own line keeps the pin. A line blank
+// before the cut stays.
+function anchoredText(content, anchor, spans) {
+    const from = Math.max(offsetOfLine(content, anchor.start), content.charCodeAt(0) === 0xfeff ? 1 : 0);
+    const nl = content.indexOf("\n", offsetOfLine(content, anchor.end));
+    const to = nl === -1 ? content.length : nl;
+    let text = "";
+    const cuts = [];
+    let at = from;
+    for (const s of spans) {
+        const end = Math.min(s.end, to);
+        if (end <= at || s.start >= to)
+            continue;
+        text += content.slice(at, Math.max(s.start, at));
+        cuts.push(text.length);
+        at = end;
+    }
+    text += content.slice(at, to);
+    const parts = text.split("\n");
+    const out = [];
+    let offset = 0;
+    parts.forEach((part, i) => {
+        const cut = cuts.some((c) => c >= offset && c <= offset + part.length);
+        offset += part.length + 1;
+        // A CR before an LF is folded, as manni's splitLines folds CRLF.
+        const line = (i < parts.length - 1 || to < content.length) && part.endsWith("\r") ? part.slice(0, -1) : part;
+        if (!(cut && line.trim() === ""))
+            out.push(line);
+    });
+    return out;
+}
+function writeStatements(content, format, opts) {
+    if (!FORMS[format])
+        return content;
+    const from = format === "markdown" || format === "asciidoc" ? (frontMatter(content)?.end ?? 0) : 0;
+    const statements = parseStatements(content, from, format);
+    if (format === "dita")
+        statements.push(...dataStatements(content));
+    if (statements.length === 0)
+        return content;
+    const { anchors, spans } = format === "dita"
+        ? xmlAnchors(content, statements)
+        : {
+            anchors: new Map(statements.map((s) => [s, anchoredLines(content, s.end, format)])),
+            spans: statements.map(({ start, end }) => ({ start, end })),
+        };
+    const edits = [];
+    for (const s of statements) {
+        const anchor = anchors.get(s);
+        if (s.broken) {
+            // Only ours is worth a word: another tool's statement isn't ours to fix.
+            if (s.payload.includes(TOOL))
+                opts.onSkipped?.(s.line, s.broken);
+            continue;
+        }
+        if (!anchor) {
+            if (s.payload.includes(TOOL))
+                opts.onSkipped?.(s.line, "it anchors nothing: no paragraph, block or element follows it");
+            continue;
+        }
+        let data;
+        try {
+            data = JSON.parse(s.payload);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(data) || !Array.isArray(data["verified-by"]))
+            continue;
+        const before = JSON.stringify(data);
+        const { any, passed } = fillEntries(data["verified-by"], (e) => (isRecord(e) ? { tool: e.tool, check: e.check, passed: typeof e.passed === "string" ? e.passed : undefined } : undefined), (e) => {
+            const entry = e;
+            entry.version = opts.version;
+            entry.passed = opts.today;
+        }, opts);
+        if (!any)
+            continue;
+        const last = oldest(passed);
+        if (last !== undefined)
+            data["last-verified"] = last;
+        const pin = pinOf(anchoredText(content, anchor, spans));
+        const json = JSON.stringify(data);
+        // A same-day re-run fills the same values over an unchanged block: skip
+        // it, so the file stays byte-identical.
+        if (pin === s.pin && json === before)
+            continue;
+        const trailing = /\s*$/.exec(content.slice(s.pinAt, s.closeAt))?.[0] ?? "";
+        const text = `${pin} ${json}`;
+        edits.push({ start: s.pinAt, end: s.closeAt, text: `${s.quote ? escapeAttribute(text, s.quote) : text}${trailing}` });
+    }
+    return edits.length === 0 ? content : applyEdits(content, edits);
+}
+// Fill Doc Detective's `verified-by` entries in a page's front matter and its
+// inline `meta` statements. Returns the page unchanged when nothing passed.
+export function applyVerification(content, format, opts) {
+    return writeStatements(writeFrontMatter(content, opts), format, opts);
+}
+//# sourceMappingURL=verification.js.map