@dogsbay/types 0.2.0-beta.164 → 0.2.0-beta.166

package/dist/format.d.ts

@@ -24,6 +24,12 @@ export interface ExportPage {
      * Importers that rewrite links to root-absolute leave it unset.
      */
     sourcePath?: string;
+    /**
+     * The file the importer read the page from, as it opened it (absolute): set by the dogsbay-md
+     * loader for a page parsed with a source map (`site dev`'s block records), so a site of several
+     * sources knows which source a page came from (`sourcePath` alone is the same in each).
+     */
+    sourceFile?: string;
     /**
      * The page is its folder's index, served at `/<slug>/` where a leaf is served at `/<slug>`
      * (Docusaurus's category index docs). Written as `<slug>/index.md`, which every Dogsbay MD

package/dist/index.d.ts

@@ -13,3 +13,5 @@ export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-che
 export type { FrontmatterFinding } from "./frontmatter-check.js";
 export type { ImportLimits, LimitName, LimitHost } from "./limits.js";
 export { DEFAULT_LIMITS, LIMIT_DESCRIPTIONS, LIMIT_REACHED, resolveLimits, parseLimit, formatLimit, limitMessage, utf8Bytes } from "./limits.js";
+export type { TextMap, TextSegment, CopySegment, ExprSegment, IncludeSegment, GeneratedSegment, TextCondition, TextOrigin, LineSource } from "./text-map.js";
+export { identityTextMap, textMapLines, sliceTextMap, composeTextMaps, lookupTextLine, lookupTextRange, textLineOrigins, rangeOrigin, textMapOfLines, diffTextMap, offsetIncludeMaps, frontMatterLines } from "./text-map.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export { STATUS_VALUES, parseMeta } from "./meta.js";
 export { WELL_KNOWN_FIELDS, INERT_FIELDS, AGGREGATOR_OWNED, EMPTY_POLICY, typeOf, matchesType, nearMisses, isSafeAutoFix, frontmatterKeyLines, globMatches, contentRelativePath, requiredFieldsFor, } from "./frontmatter-schema.js";
 export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-check.js";
 export { DEFAULT_LIMITS, LIMIT_DESCRIPTIONS, LIMIT_REACHED, resolveLimits, parseLimit, formatLimit, limitMessage, utf8Bytes } from "./limits.js";
+export { identityTextMap, textMapLines, sliceTextMap, composeTextMaps, lookupTextLine, lookupTextRange, textLineOrigins, rangeOrigin, textMapOfLines, diffTextMap, offsetIncludeMaps, frontMatterLines } from "./text-map.js";

package/dist/text-map.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Text maps: where each line of a stage's output came from in that stage's input.
+ *
+ * Several stages rewrite a page's text between its file and the parser (example expansion, minja
+ * templating, includes, data directives; for DITA, the converter). Each returns a map of what it
+ * wrote, and the maps compose, so a block the parser places at a line of the final text can be
+ * traced back to the file and lines that made it (plans/content-source-maps.md).
+ *
+ * Lines are 1-based. A map lists its output in order: every output line is in exactly one segment.
+ */
+/**
+ * A branch of an `{% if %}` or `{% switch %}` the output was rendered under, in the segment's input
+ * (its file): another variant of the page may show other text, or none, there.
+ */
+export interface TextCondition {
+    branch: "if" | "elif" | "else" | "case";
+    /** The condition as written (`product == "acme"`; a case: `subject == value`); none for else */
+    test?: string;
+    /** Lines of the branch's tag */
+    from: number;
+    to: number;
+    /** Lines of the whole block, its opening tag to its end tag */
+    block: {
+        from: number;
+        to: number;
+    };
+}
+/** Output lines copied from the input, one for one: output line k of the segment is input line `from + k - 1`. */
+export interface CopySegment {
+    kind: "copy";
+    lines: number;
+    from: number;
+    /** The branches it was rendered under, outermost first */
+    conditions?: TextCondition[];
+}
+/**
+ * Template output (a variable, a filter, lines whitespace control joined) standing for input lines
+ * `from`–`to`. The rendered words are not the source's: to change them, edit those source lines
+ * (with their `{{ }}` as written), not the output.
+ */
+export interface ExprSegment {
+    kind: "expr";
+    lines: number;
+    from: number;
+    to: number;
+    conditions?: TextCondition[];
+}
+/**
+ * Another file's text, included at input lines `from`–`to`. `map` maps these output lines into
+ * that file's lines (they may have been rewritten there too); without it, only the include is known.
+ */
+export interface IncludeSegment {
+    kind: "include";
+    lines: number;
+    from: number;
+    to: number;
+    file: string;
+    map?: TextMap;
+    /** The branches the include tag was rendered under, in the including text */
+    conditions?: TextCondition[];
+}
+/**
+ * Output with no text of its own to edit: a data table, an example from the examples folder, a
+ * DITA related-links list. `from`–`to` is what asked for it (the directive), when anything did.
+ */
+export interface GeneratedSegment {
+    kind: "generated";
+    lines: number;
+    from?: number;
+    to?: number;
+    conditions?: TextCondition[];
+}
+export type TextSegment = CopySegment | ExprSegment | IncludeSegment | GeneratedSegment;
+export interface TextMap {
+    segments: TextSegment[];
+}
+/** Where one output line came from (`lookupTextLine`). */
+export interface TextOrigin {
+    kind: TextSegment["kind"];
+    /** The file the position is in: undefined for the text the first map was given (the page). */
+    file?: string;
+    /** The line, for a copied line. */
+    line?: number;
+    /** The input lines that made it (a copied line: `line` both times); absent for generated output with no source. */
+    from?: number;
+    to?: number;
+    /** For `include` with no map: the file included. */
+    included?: string;
+    /** The includes it came through, outermost first: each in `file` (undefined: the page) at lines `from`–`to`. */
+    via: Array<{
+        file?: string;
+        from: number;
+        to: number;
+    }>;
+    /**
+     * The `{% if %}` / `{% switch %}` branches it was rendered under, outermost first, each in `file`
+     * (undefined: the page): through an include, the include tag's and then the included file's.
+     */
+    conditions?: Array<TextCondition & {
+        file?: string;
+    }>;
+    /**
+     * For a range (`rangeOrigin`): some source lines between `from` and `to` are not in it (a false
+     * `{% if %}` removed them), so its text is not the source's even where every line is copied.
+     */
+    gaps?: true;
+}
+/** A map of text passed through unchanged. */
+export declare function identityTextMap(lines: number): TextMap;
+/** How many output lines a map covers. */
+export declare function textMapLines(map: TextMap): number;
+/** The segments for output lines `start`–`start + count - 1`, cut to fit; lines past the map's end are generated. */
+export declare function sliceTextMap(map: TextMap, start: number, count: number): TextMap;
+/**
+ * Two stages as one: `first` maps the first stage's output to its input (the file), `second` maps
+ * the second stage's output to ITS input, which is the first stage's output. The result maps the
+ * second stage's output to the file.
+ */
+export declare function composeTextMaps(first: TextMap, second: TextMap): TextMap;
+/** Where output line `line` came from; undefined past the map's end. */
+export declare function lookupTextLine(map: TextMap, line: number): TextOrigin | undefined;
+/**
+ * Every output line's origin, in order: what `lookupTextLine` gives for each, in one walk of the
+ * map (a page's blocks look up ranges of it, so a parse stays linear in the page).
+ */
+export declare function textLineOrigins(map: TextMap): TextOrigin[];
+/**
+ * One origin for several lines (a block): in the deepest file they all share, from the first
+ * line to the last there. Lines that went further into an include count as that include's tag.
+ * The kind is the least editable of the lines': generated, then template output, then an include,
+ * then copied text. Undefined for no lines.
+ */
+export declare function rangeOrigin(origins: readonly TextOrigin[]): TextOrigin | undefined;
+/** Where output lines `from`–`to` came from, as one origin (`rangeOrigin`). */
+export declare function lookupTextRange(map: TextMap, from: number, to: number): TextOrigin | undefined;
+/** Where one output line came from, for `textMapOfLines`: an input line copied, or a span (or nothing) it stands for. */
+export type LineSource = number | {
+    kind: "expr" | "generated";
+    from?: number;
+    to?: number;
+};
+/** The map of an output whose line k came from `sources[k - 1]`: consecutive copies and equal spans become one segment. */
+export declare function textMapOfLines(sources: readonly LineSource[]): TextMap;
+/**
+ * The map of a rewrite nobody recorded (a host's tidy-up pass after templating): lines equal in both
+ * are copies, found by a line diff; a changed run stands for the lines it replaced (`expr`), an
+ * inserted run for nothing (`generated`). Lines are compared as written.
+ */
+export declare function diffTextMap(before: string, after: string): TextMap;
+/**
+ * A map whose include segments counted the lines of text a host's loader changed before the
+ * renderer read it, put back in the files' own lines: each included file's segments (their nested
+ * maps, recursively) move down by `linesBefore(file)`, the lines the loader removed from the top
+ * of that file (its front matter, say). `file` is the name the include segment gives. The page's
+ * own segments are left as they are.
+ */
+export declare function offsetIncludeMaps(map: TextMap, linesBefore: (file: string) => number): TextMap;
+/**
+ * How far a leading YAML front matter block (`---` … `---`) moves the rest of the text down: line 1
+ * of the text after it is line `1 + frontMatterLines(text)` of the text. 0 when there is none. What a
+ * loader stripping it removed from the top, for `offsetIncludeMaps`.
+ */
+export declare function frontMatterLines(text: string): number;

package/dist/text-map.js

@@ -0,0 +1,559 @@
+/**
+ * Text maps: where each line of a stage's output came from in that stage's input.
+ *
+ * Several stages rewrite a page's text between its file and the parser (example expansion, minja
+ * templating, includes, data directives; for DITA, the converter). Each returns a map of what it
+ * wrote, and the maps compose, so a block the parser places at a line of the final text can be
+ * traced back to the file and lines that made it (plans/content-source-maps.md).
+ *
+ * Lines are 1-based. A map lists its output in order: every output line is in exactly one segment.
+ */
+/** A map of text passed through unchanged. */
+export function identityTextMap(lines) {
+    return { segments: lines > 0 ? [{ kind: "copy", lines, from: 1 }] : [] };
+}
+/** How many output lines a map covers. */
+export function textMapLines(map) {
+    let n = 0;
+    for (const s of map.segments)
+        n += s.lines;
+    return n;
+}
+/** The segments for output lines `start`–`start + count - 1`, cut to fit; lines past the map's end are generated. */
+export function sliceTextMap(map, start, count) {
+    const out = [];
+    const end = start + count; // exclusive
+    let at = 1;
+    for (const s of map.segments) {
+        const sEnd = at + s.lines;
+        const a = Math.max(at, start);
+        const b = Math.min(sEnd, end);
+        if (a < b)
+            out.push(cut(s, a - at, b - a));
+        at = sEnd;
+        if (at >= end)
+            break;
+    }
+    // Lines before the first (start < 1) and past the end have nothing to trace them to
+    const before = Math.max(0, Math.min(1, end) - start);
+    if (before > 0)
+        out.unshift({ kind: "generated", lines: before });
+    const covered = Math.max(0, Math.min(at, end) - Math.max(start, 1));
+    if (before + covered < count)
+        out.push({ kind: "generated", lines: count - before - covered });
+    return { segments: merge(out) };
+}
+/** `skip` lines into a segment, `lines` long. */
+function cut(s, skip, lines) {
+    if (s.kind === "copy")
+        return { kind: "copy", lines, from: s.from + skip, ...(s.conditions ? { conditions: s.conditions } : {}) };
+    if (s.kind === "include" && s.map)
+        return { ...s, lines, map: sliceTextMap(s.map, skip + 1, lines) };
+    return { ...s, lines };
+}
+/**
+ * Joins neighbouring copies that continue each other, and neighbouring pieces of one include (the
+ * same file at the same tag, as slicing leaves them), so a range over them stays inside the file.
+ */
+function merge(segments) {
+    const out = [];
+    for (const s of segments) {
+        if (s.lines <= 0)
+            continue;
+        const last = out[out.length - 1];
+        if (last && !sameConditions(last.conditions, s.conditions))
+            out.push(s);
+        else if (last?.kind === "copy" && s.kind === "copy" && last.from + last.lines === s.from) {
+            out[out.length - 1] = { ...last, lines: last.lines + s.lines };
+        }
+        else if (last?.kind === "include" && s.kind === "include" && last.map && s.map && last.file === s.file && last.from === s.from && last.to === s.to) {
+            // Each piece's map cut to its own lines first, so a map longer or shorter than its piece keeps the next piece in place
+            const joined = [...sliceTextMap(last.map, 1, last.lines).segments, ...sliceTextMap(s.map, 1, s.lines).segments];
+            out[out.length - 1] = { ...last, lines: last.lines + s.lines, map: { segments: merge(joined) } };
+        }
+        else
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * Two stages as one: `first` maps the first stage's output to its input (the file), `second` maps
+ * the second stage's output to ITS input, which is the first stage's output. The result maps the
+ * second stage's output to the file.
+ */
+export function composeTextMaps(first, second) {
+    const out = [];
+    for (const s of second.segments) {
+        const { conditions, ...bare } = s;
+        // The second stage's branches are in its input: taken back to the file through `first`
+        const lifted = conditions ? liftConditions(first, conditions) : [];
+        if (bare.kind === "copy") {
+            for (const o of sliceTextMap(first, bare.from, bare.lines).segments)
+                out.push(underAlso(o, lifted));
+        }
+        else {
+            // lift keeps the first stage's branches over the range it stands for (inside an include too)
+            out.push(underAlso(lift(first, bare), lifted));
+        }
+    }
+    return { segments: merge(out) };
+}
+/** `s`, also rendered under `more` (after its own) */
+function underAlso(s, more) {
+    if (more.length === 0)
+        return s;
+    return { ...s, conditions: [...(s.conditions ?? []), ...more] };
+}
+/**
+ * Conditions in `first`'s output, in `first`'s input: kept where their tag and block lines trace
+ * to the input itself (not into an include or generated text), else left out.
+ */
+function liftConditions(first, conditions) {
+    const out = [];
+    const back = (from, to) => {
+        const o = lookupTextRange(first, from, to);
+        return o && o.via.length === 0 && o.file === undefined && o.from !== undefined && (o.kind === "copy" || o.kind === "expr") ? { from: o.from, to: o.to ?? o.from } : undefined;
+    };
+    for (const c of conditions) {
+        const tag = back(c.from, c.to);
+        const block = back(c.block.from, c.block.to);
+        if (tag && block)
+            out.push({ ...c, ...tag, block });
+    }
+    return out;
+}
+function sameCondition(a, b) {
+    return a.branch === b.branch && a.test === b.test && a.from === b.from && a.to === b.to && a.block.from === b.block.from && a.block.to === b.block.to;
+}
+function sameConditions(a, b) {
+    const x = a ?? [];
+    const y = b ?? [];
+    return x.length === y.length && x.every((c, k) => sameCondition(c, y[k]));
+}
+/** A segment's conditions as an origin's, in `file` */
+function inFile(conditions, file) {
+    return (conditions ?? []).map((c) => (file !== undefined ? { ...c, file } : { ...c }));
+}
+/**
+ * A segment whose source range is in `first`'s output, with that range taken back through `first`.
+ * A range inside one segment of `first` is expressed in that segment's input (inside an included
+ * file, through its map); a range over several is the span of their inputs at `first`'s level.
+ */
+function lift(first, s) {
+    if (s.from === undefined)
+        return s;
+    const to = Math.max(s.to ?? s.from, s.from);
+    const pieces = [];
+    let at = 1;
+    for (const o of first.segments) {
+        if (o.lines <= 0)
+            continue;
+        const end = at + o.lines - 1;
+        if (end >= s.from && at <= to)
+            pieces.push({ o, a: Math.max(s.from, at) - at, b: Math.min(to, end) - at });
+        if (end >= to)
+            break;
+        at += o.lines;
+    }
+    // Past the end of `first`: nothing to trace it to
+    if (pieces.length === 0)
+        return { kind: "generated", lines: s.lines };
+    if (pieces.length === 1)
+        return through(pieces[0].o, pieces[0].a, pieces[0].b, s);
+    let from;
+    let last;
+    let generated = s.kind === "generated";
+    const conditions = [];
+    for (const { o } of pieces)
+        for (const c of o.conditions ?? [])
+            if (!conditions.some((x) => sameCondition(x, c)))
+                conditions.push(c);
+    const under = conditions.length ? { conditions } : {};
+    for (const { o, a, b } of pieces) {
+        const range = o.kind === "copy" ? [o.from + a, o.from + b] : o.from !== undefined ? [o.from, o.to ?? o.from] : undefined;
+        if (o.kind === "generated")
+            generated = true;
+        if (!range)
+            continue;
+        from = from === undefined ? range[0] : Math.min(from, range[0]);
+        last = last === undefined ? range[1] : Math.max(last, range[1]);
+    }
+    if (from === undefined || last === undefined)
+        return { kind: "generated", lines: s.lines, ...under };
+    if (s.kind === "include")
+        return { ...s, from, to: last, ...under };
+    return generated ? { kind: "generated", lines: s.lines, from, to: last, ...under } : { kind: "expr", lines: s.lines, from, to: last, ...under };
+}
+/** `s` (its range at offsets `a`–`b` of segment `o`) expressed in `o`'s input. */
+function through(o, a, b, s) {
+    return underAlso(throughBare(o, a, b, s), o.conditions ?? []);
+}
+function throughBare(o, a, b, s) {
+    if (o.kind === "copy")
+        return { ...s, from: o.from + a, to: o.from + b };
+    if (o.kind === "include") {
+        // The range is text of the included file: express it there, inside an include segment
+        if (!o.map) {
+            // Where in that file is not known: an include there keeps its own file and map, at this include's tag
+            if (s.kind === "include")
+                return { ...s, from: o.from, to: o.to };
+            return { kind: "include", lines: s.lines, from: o.from, to: o.to, file: o.file };
+        }
+        return { kind: "include", lines: s.lines, from: o.from, to: o.to, file: o.file, map: { segments: [lift(o.map, { ...s, from: a + 1, to: b + 1 })] } };
+    }
+    // The range was itself template output or generated: what asked for it is the source, if anything did
+    if (o.from === undefined)
+        return { kind: "generated", lines: s.lines };
+    const range = { from: o.from, to: o.to ?? o.from };
+    if (s.kind === "include")
+        return { ...s, ...range };
+    return s.kind === "generated" || o.kind === "generated" ? { kind: "generated", lines: s.lines, ...range } : { kind: "expr", lines: s.lines, ...range };
+}
+/** Where output line `line` came from; undefined past the map's end. */
+export function lookupTextLine(map, line) {
+    const via = [];
+    const conditions = [];
+    const under = () => (conditions.length ? { conditions } : {});
+    let file;
+    let current = map;
+    let target = line;
+    for (;;) {
+        let at = 1;
+        let found;
+        for (const s of current.segments) {
+            if (target < at + s.lines) {
+                found = { s, k: target - at };
+                break;
+            }
+            at += s.lines;
+        }
+        if (!found || target < 1) {
+            // Inside an include whose map is shorter than it: in that file, with nothing more to trace it to
+            return via.length ? { kind: "generated", ...(file !== undefined ? { file } : {}), via, ...under() } : undefined;
+        }
+        const { s, k } = found;
+        conditions.push(...inFile(s.conditions, file));
+        if (s.kind === "copy")
+            return { kind: "copy", ...(file !== undefined ? { file } : {}), line: s.from + k, from: s.from + k, to: s.from + k, via, ...under() };
+        if (s.kind === "include" && s.map) {
+            via.push({ ...(file !== undefined ? { file } : {}), from: s.from, to: s.to });
+            file = s.file;
+            current = s.map;
+            target = k + 1;
+            continue;
+        }
+        return {
+            kind: s.kind,
+            ...(file !== undefined ? { file } : {}),
+            ...(s.from !== undefined ? { from: s.from, to: s.to ?? s.from } : {}),
+            ...(s.kind === "include" ? { included: s.file } : {}),
+            via,
+            ...under(),
+        };
+    }
+}
+/**
+ * Every output line's origin, in order: what `lookupTextLine` gives for each, in one walk of the
+ * map (a page's blocks look up ranges of it, so a parse stays linear in the page).
+ */
+export function textLineOrigins(map) {
+    const out = [];
+    const walk = (m, file, via, limit, outer) => {
+        const start = out.length;
+        const at = () => ({ kind: "generated", ...(file !== undefined ? { file } : {}), via, ...(outer.length ? { conditions: outer } : {}) });
+        for (const s of m.segments) {
+            const room = limit - (out.length - start);
+            if (room <= 0)
+                break;
+            const n = Math.min(s.lines, room);
+            if (n <= 0)
+                continue;
+            const conditions = s.conditions?.length ? [...outer, ...inFile(s.conditions, file)] : outer;
+            const under = conditions.length ? { conditions } : {};
+            if (s.kind === "copy") {
+                for (let k = 0; k < n; k++)
+                    out.push({ kind: "copy", ...(file !== undefined ? { file } : {}), line: s.from + k, from: s.from + k, to: s.from + k, via, ...under });
+            }
+            else if (s.kind === "include" && s.map) {
+                walk(s.map, s.file, [...via, { ...(file !== undefined ? { file } : {}), from: s.from, to: s.to }], n, conditions);
+            }
+            else {
+                const o = {
+                    kind: s.kind,
+                    ...(file !== undefined ? { file } : {}),
+                    ...(s.from !== undefined ? { from: s.from, to: s.to ?? s.from } : {}),
+                    ...(s.kind === "include" ? { included: s.file } : {}),
+                    via,
+                    ...under,
+                };
+                for (let k = 0; k < n; k++)
+                    out.push(o);
+            }
+        }
+        // An include whose map is shorter than it: the rest is in that file, with nothing to trace it to
+        while (via.length > 0 && out.length - start < limit)
+            out.push(at());
+    };
+    walk(map, undefined, [], textMapLines(map), []);
+    return out;
+}
+const RANK = { copy: 0, include: 1, expr: 2, generated: 3 };
+/**
+ * One origin for several lines (a block): in the deepest file they all share, from the first
+ * line to the last there. Lines that went further into an include count as that include's tag.
+ * The kind is the least editable of the lines': generated, then template output, then an include,
+ * then copied text. Undefined for no lines.
+ */
+export function rangeOrigin(origins) {
+    if (origins.length === 0)
+        return undefined;
+    const sameStep = (a, b) => a.file === b.file && a.from === b.from && a.to === b.to;
+    // The includes every line came through
+    let depth = origins[0].via.length;
+    for (const o of origins) {
+        let d = 0;
+        while (d < depth && d < o.via.length && sameStep(o.via[d], origins[0].via[d]))
+            d++;
+        depth = d;
+    }
+    const via = origins[0].via.slice(0, depth);
+    let file;
+    let kind = "copy";
+    let from;
+    let to;
+    const included = new Set();
+    const conditions = [];
+    const covered = [];
+    for (const o of origins) {
+        for (const c of o.conditions ?? [])
+            if (!conditions.some((x) => x.file === c.file && sameCondition(x, c)))
+                conditions.push(c);
+        // At the shared depth: the line itself, or the tag of the include it went into from there
+        const deeper = o.via.length > depth ? o.via[depth] : undefined;
+        const k = deeper ? "include" : o.kind;
+        const f = deeper ? deeper.file : o.file;
+        const a = deeper ? deeper.from : o.from;
+        const b = deeper ? deeper.to : o.to;
+        file = f;
+        if (RANK[k] > RANK[kind])
+            kind = k;
+        if (o.kind === "include" && !deeper && o.included)
+            included.add(o.included);
+        if (a !== undefined)
+            from = from === undefined ? a : Math.min(from, a);
+        if (b !== undefined)
+            to = to === undefined ? b : Math.max(to, b);
+        if (a !== undefined)
+            covered.push([a, b ?? a]);
+    }
+    // Source lines inside the range that none of its lines came from
+    let gaps = false;
+    if (from !== undefined && to !== undefined) {
+        covered.sort((x, y) => x[0] - y[0]);
+        let reach = from - 1;
+        for (const [a, b] of covered) {
+            if (a > reach + 1)
+                gaps = true;
+            reach = Math.max(reach, b);
+        }
+    }
+    return {
+        kind,
+        ...(file !== undefined ? { file } : {}),
+        ...(kind === "copy" && from === to && from !== undefined ? { line: from } : {}),
+        ...(from !== undefined ? { from, to: to ?? from } : {}),
+        ...(kind === "include" && included.size === 1 ? { included: [...included][0] } : {}),
+        via,
+        ...(conditions.length ? { conditions } : {}),
+        ...(gaps ? { gaps: true } : {}),
+    };
+}
+/** Where output lines `from`–`to` came from, as one origin (`rangeOrigin`). */
+export function lookupTextRange(map, from, to) {
+    const origins = [];
+    for (let line = from; line <= to; line++) {
+        const o = lookupTextLine(map, line);
+        if (o)
+            origins.push(o);
+    }
+    return rangeOrigin(origins);
+}
+/** The map of an output whose line k came from `sources[k - 1]`: consecutive copies and equal spans become one segment. */
+export function textMapOfLines(sources) {
+    const segments = [];
+    for (const src of sources) {
+        const last = segments[segments.length - 1];
+        if (typeof src === "number") {
+            if (last?.kind === "copy" && last.from + last.lines === src)
+                last.lines++;
+            else
+                segments.push({ kind: "copy", lines: 1, from: src });
+            continue;
+        }
+        if (src.kind === "expr" && src.from !== undefined) {
+            const to = src.to ?? src.from;
+            if (last?.kind === "expr" && last.from === src.from && last.to === to)
+                last.lines++;
+            else
+                segments.push({ kind: "expr", lines: 1, from: src.from, to });
+        }
+        else {
+            const range = src.from !== undefined ? { from: src.from, to: src.to ?? src.from } : {};
+            if (last?.kind === "generated" && last.from === range.from && last.to === range.to)
+                last.lines++;
+            else
+                segments.push({ kind: "generated", lines: 1, ...range });
+        }
+    }
+    return { segments };
+}
+/** Line differences beyond which `diffTextMap` stops diffing and calls the changed middle one span */
+const MAX_DIFF = 2000;
+/**
+ * The map of a rewrite nobody recorded (a host's tidy-up pass after templating): lines equal in both
+ * are copies, found by a line diff; a changed run stands for the lines it replaced (`expr`), an
+ * inserted run for nothing (`generated`). Lines are compared as written.
+ */
+export function diffTextMap(before, after) {
+    if (before === after)
+        return identityTextMap(before.split("\n").length);
+    const a = before.split("\n");
+    const b = after.split("\n");
+    // Common start and end first: tidy-ups change a few lines of a page
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start++;
+    let end = 0;
+    while (end < a.length - start && end < b.length - start && a[a.length - 1 - end] === b[b.length - 1 - end])
+        end++;
+    const sources = [];
+    for (let k = 0; k < start; k++)
+        sources.push(k + 1);
+    const pairs = diffLines(a.slice(start, a.length - end), b.slice(start, b.length - end));
+    // pairs: for each line of b's middle, the line of a's middle it equals (0-based), else -1
+    if (pairs === undefined) {
+        const from = start + 1;
+        const to = a.length - end;
+        for (let k = start; k < b.length - end; k++)
+            sources.push(to >= from ? { kind: "expr", from, to } : { kind: "generated" });
+    }
+    else {
+        // A run of unmatched lines stands for the a-lines between the matches around it
+        let prevA = -1;
+        for (let k = 0; k < pairs.length;) {
+            if (pairs[k] !== -1) {
+                prevA = pairs[k];
+                sources.push(start + pairs[k] + 1);
+                k++;
+                continue;
+            }
+            let j = k;
+            while (j < pairs.length && pairs[j] === -1)
+                j++;
+            const nextA = j < pairs.length ? pairs[j] : a.length - start - end;
+            const from = start + prevA + 2;
+            const to = start + nextA;
+            for (; k < j; k++)
+                sources.push(to >= from ? { kind: "expr", from, to } : { kind: "generated" });
+        }
+    }
+    for (let k = end; k > 0; k--)
+        sources.push(a.length - k + 1);
+    return textMapOfLines(sources);
+}
+/**
+ * For each line of `b`, the index of the line of `a` it is kept as (a longest common subsequence,
+ * Myers' O((N+M)D)), else -1. Undefined when the two differ in more than MAX_DIFF lines.
+ */
+function diffLines(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = Math.min(n + m, MAX_DIFF);
+    const offset = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    let found = -1;
+    for (let d = 0; d <= max && found < 0; d++) {
+        trace.push(v.slice());
+        for (let k = -d; k <= d; k += 2) {
+            let x = k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]) ? v[offset + k + 1] : v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m) {
+                found = d;
+                break;
+            }
+        }
+    }
+    if (found < 0)
+        return undefined;
+    // Walk back through the trace, recording the diagonal (kept) steps
+    const pairs = new Array(m).fill(-1);
+    let x = n;
+    let y = m;
+    for (let d = found; d > 0; d--) {
+        const vd = trace[d];
+        const k = x - y;
+        const prevK = k === -d || (k !== d && vd[offset + k - 1] < vd[offset + k + 1]) ? k + 1 : k - 1;
+        const prevX = vd[offset + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            x--;
+            y--;
+            pairs[y] = x;
+        }
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        x--;
+        y--;
+        pairs[y] = x;
+    }
+    return pairs;
+}
+/**
+ * A map whose include segments counted the lines of text a host's loader changed before the
+ * renderer read it, put back in the files' own lines: each included file's segments (their nested
+ * maps, recursively) move down by `linesBefore(file)`, the lines the loader removed from the top
+ * of that file (its front matter, say). `file` is the name the include segment gives. The page's
+ * own segments are left as they are.
+ */
+export function offsetIncludeMaps(map, linesBefore) {
+    const shift = (m, by) => ({
+        segments: m.segments.map((seg) => {
+            const moved = { ...seg };
+            if (by) {
+                if (moved.from !== undefined)
+                    moved.from += by;
+                if ("to" in moved && moved.to !== undefined)
+                    moved.to += by;
+                if (moved.conditions)
+                    moved.conditions = moved.conditions.map((c) => ({ ...c, from: c.from + by, to: c.to + by, block: { from: c.block.from + by, to: c.block.to + by } }));
+            }
+            if (moved.kind === "include" && moved.map)
+                moved.map = shift(moved.map, linesBefore(moved.file));
+            return moved;
+        }),
+    });
+    return shift(map, 0);
+}
+/**
+ * How far a leading YAML front matter block (`---` … `---`) moves the rest of the text down: line 1
+ * of the text after it is line `1 + frontMatterLines(text)` of the text. 0 when there is none. What a
+ * loader stripping it removed from the top, for `offsetIncludeMaps`.
+ */
+export function frontMatterLines(text) {
+    if (!text.startsWith("---\n") && !text.startsWith("---\r\n"))
+        return 0;
+    const close = /\r?\n---[ \t]*(\r?\n|$)/.exec(text.slice(3));
+    if (!close)
+        return 0;
+    const end = 3 + close.index + close[0].length;
+    // the newlines it took: line 1 of what is left is that line of the file
+    return text.slice(0, end).split("\n").length - 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/types",
-  "version": "0.2.0-beta.164",
+  "version": "0.2.0-beta.166",
   "description": "Universal document tree model for Dogsbay format loaders and renderers",
   "type": "module",
   "main": "dist/index.js",