@dogsbay/types 0.2.0-beta.17 → 0.2.0-beta.171

package/dist/limits.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Import limits: the RESOURCE limits an import puts on someone else's repo, in one place
+ * (plans/import-limits.md). They exist so a hostile repo cannot make an import read gigabytes or
+ * build a table of a million rows; for the operator's own repo they are only a way for content
+ * to turn into a note, so `trusted` sets none.
+ *
+ * Who may set them: the OPERATOR (CLI flags, a host's `migrate()` options), never the repo being
+ * imported. Safety rules (containment, no repo code run, escaping) are NOT limits and are not
+ * here: they hold whether the repo is trusted or not.
+ *
+ * Each default is measured against the largest real value it guards, with the headroom noted.
+ * A limit that trips is REPORTED (`LIMIT_REACHED`), never silent.
+ */
+export interface ImportLimits {
+    /** One file read as data (bytes). */
+    fileBytes: number;
+    /** Files in one data folder. */
+    folderFiles: number;
+    /** All data read in one import (bytes). */
+    importBytes: number;
+    /** Data one catalogue (a table built from data files) may read (bytes). */
+    catalogueBytes: number;
+    /** Rows in one catalogue. */
+    catalogueRows: number;
+    /** Characters of text in one table cell. */
+    cellChars: number;
+    /** Bytes of one code example the import transforms (TypeScript → JavaScript with prettier). */
+    exampleBytes: number;
+}
+export type LimitName = keyof ImportLimits;
+/**
+ * The defaults, for a repo that is not trusted. Measured on cloudflare-docs (6e85ac29,
+ * 2026-11-03), the largest real use of each today:
+ */
+export declare const DEFAULT_LIMITS: Readonly<ImportLimits>;
+/** What each limit guards, for the report. */
+export declare const LIMIT_DESCRIPTIONS: Readonly<Record<LimitName, string>>;
+/** The ledger code a tripped limit is reported under. */
+export declare const LIMIT_REACHED = "limit-reached";
+/**
+ * The limits an import runs with: the defaults, or none when `trusted`, then each given value.
+ * A given value must be a positive number (or Infinity); anything else throws, naming it — a typo
+ * must not run with a limit the operator did not mean.
+ */
+export declare function resolveLimits(given?: Partial<Record<string, unknown>>, opts?: {
+    trusted?: boolean;
+}): ImportLimits;
+/**
+ * One `--limit name=value` flag: `catalogueBytes=500MB`, `catalogueRows=50000`, `cellChars=none`.
+ * Sizes take `KB`/`MB`/`GB` (powers of 1,000) or `KiB`/`MiB`/`GiB`; `none` is no limit.
+ */
+export declare function parseLimit(flag: string): [LimitName, number];
+/** A limit's value as a person reads it: `256 MB`, `20,000`, `none`. */
+export declare function formatLimit(name: LimitName, value: number): string;
+/**
+ * How an operator raises a limit, by where the import runs: the CLI's flags, `site build`'s config,
+ * a host's options (the playground). The report names the one that works where it is read.
+ */
+export type LimitHost = "cli" | "config" | "host";
+/**
+ * The report for a tripped limit: what was not done, the measured value against the limit, and
+ * how to raise it where the import runs.
+ */
+export declare function limitMessage(what: string, name: LimitName, measured: number | undefined, limit: number, host?: LimitHost): string;
+/** UTF-8 bytes of a string, without encoding it: limits on bytes count bytes, not UTF-16 units. */
+export declare function utf8Bytes(s: string): number;

package/dist/limits.js

@@ -0,0 +1,151 @@
+/**
+ * Import limits: the RESOURCE limits an import puts on someone else's repo, in one place
+ * (plans/import-limits.md). They exist so a hostile repo cannot make an import read gigabytes or
+ * build a table of a million rows; for the operator's own repo they are only a way for content
+ * to turn into a note, so `trusted` sets none.
+ *
+ * Who may set them: the OPERATOR (CLI flags, a host's `migrate()` options), never the repo being
+ * imported. Safety rules (containment, no repo code run, escaping) are NOT limits and are not
+ * here: they hold whether the repo is trusted or not.
+ *
+ * Each default is measured against the largest real value it guards, with the headroom noted.
+ * A limit that trips is REPORTED (`LIMIT_REACHED`), never silent.
+ */
+/**
+ * The defaults, for a repo that is not trusted. Measured on cloudflare-docs (6e85ac29,
+ * 2026-11-03), the largest real use of each today:
+ */
+export const DEFAULT_LIMITS = Object.freeze({
+    // largest model JSON 496 KB → 32×
+    fileBytes: 16_000_000,
+    // catalog-models holds 199 files → 100×
+    folderFiles: 20_000,
+    // all the data files in Cloudflare's src/content (JSON/YAML outside the pages): 15.6 MB → 64×;
+    // the whole src/content, pages included, is 54.7 MB
+    importBytes: 1_000_000_000,
+    // the model catalogue reads 14.1 MB of JSON → 18×
+    catalogueBytes: 256_000_000,
+    // 272 models, 193 fields → 70×
+    catalogueRows: 20_000,
+    // longest model description 611 characters → 16×
+    cellChars: 10_000,
+    // largest <TypeScriptExample> 11.5 KB (median 409 bytes) → 87×; 1 MB is ~1.8 s of prettier
+    exampleBytes: 1_000_000,
+});
+/** What each limit guards, for the report. */
+export const LIMIT_DESCRIPTIONS = Object.freeze({
+    fileBytes: "bytes in one data file",
+    folderFiles: "files in one data folder",
+    importBytes: "data read in one import",
+    catalogueBytes: "data one catalogue reads",
+    catalogueRows: "rows in one catalogue",
+    cellChars: "characters in one table cell",
+    exampleBytes: "bytes in one code example to transform",
+});
+/** The ledger code a tripped limit is reported under. */
+export const LIMIT_REACHED = "limit-reached";
+/** Every limit unset: what `trusted` gives. */
+const NONE = Object.freeze({
+    fileBytes: Infinity,
+    folderFiles: Infinity,
+    importBytes: Infinity,
+    catalogueBytes: Infinity,
+    catalogueRows: Infinity,
+    cellChars: Infinity,
+    exampleBytes: Infinity,
+});
+const isLimitName = (k) => Object.hasOwn(DEFAULT_LIMITS, k);
+/**
+ * The limits an import runs with: the defaults, or none when `trusted`, then each given value.
+ * A given value must be a positive number (or Infinity); anything else throws, naming it — a typo
+ * must not run with a limit the operator did not mean.
+ */
+export function resolveLimits(given, opts = {}) {
+    const out = { ...(opts.trusted ? NONE : DEFAULT_LIMITS) };
+    for (const [k, v] of Object.entries(given ?? {})) {
+        if (v === undefined)
+            continue;
+        if (!isLimitName(k))
+            throw new Error(`No such limit: ${k} (there is ${Object.keys(DEFAULT_LIMITS).join(", ")})`);
+        // a whole number ≥ 1, or Infinity (none): `cellChars=0.5` cut a cell to one character and an ellipsis
+        if (typeof v !== "number" || !(v === Infinity || (Number.isInteger(v) && v >= 1)))
+            throw new Error(`Limit ${k} must be a whole number of at least 1 (or none), not ${JSON.stringify(v)}`);
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * One `--limit name=value` flag: `catalogueBytes=500MB`, `catalogueRows=50000`, `cellChars=none`.
+ * Sizes take `KB`/`MB`/`GB` (powers of 1,000) or `KiB`/`MiB`/`GiB`; `none` is no limit.
+ */
+export function parseLimit(flag) {
+    const m = /^([A-Za-z]+)=(.+)$/.exec(flag.trim());
+    if (!m)
+        throw new Error(`--limit takes name=value, not ${JSON.stringify(flag)}`);
+    const [, name, raw] = m;
+    if (!isLimitName(name))
+        throw new Error(`No such limit: ${name} (there is ${Object.keys(DEFAULT_LIMITS).join(", ")})`);
+    if (/^(none|unlimited|infinity)$/i.test(raw))
+        return [name, Infinity];
+    const v = /^(\d+(?:\.\d+)?)\s*([KMG]i?B)?$/i.exec(raw.replace(/_/g, ""));
+    if (!v)
+        throw new Error(`--limit ${name}: ${JSON.stringify(raw)} is not a number (or 500MB, or none)`);
+    const unit = (v[2] ?? "").toUpperCase();
+    if (unit && !name.endsWith("Bytes"))
+        throw new Error(`--limit ${name} is a count, not a size: ${JSON.stringify(raw)}`);
+    const scale = { "": 1, KB: 1e3, MB: 1e6, GB: 1e9, KIB: 1024, MIB: 1024 ** 2, GIB: 1024 ** 3 };
+    // a size rounds to whole bytes; a count must be whole
+    const n = unit ? Math.round(Number(v[1]) * scale[unit]) : Number(v[1]);
+    // only the word `none` means no limit: 400 digits is a typo, not Infinity
+    if (!Number.isFinite(n) || n > Number.MAX_SAFE_INTEGER)
+        throw new Error(`--limit ${name}: ${JSON.stringify(raw)} is too large (use none for no limit)`);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`--limit ${name} must be a whole number of at least 1, not ${JSON.stringify(raw)}`);
+    return [name, n];
+}
+/** A limit's value as a person reads it: `256 MB`, `20,000`, `none`. */
+export function formatLimit(name, value) {
+    if (!Number.isFinite(value))
+        return "none";
+    if (name.endsWith("Bytes")) {
+        if (value >= 1e9)
+            return `${+(value / 1e9).toFixed(1)} GB`;
+        if (value >= 1e6)
+            return `${+(value / 1e6).toFixed(1)} MB`;
+        if (value >= 1e3)
+            return `${+(value / 1e3).toFixed(1)} KB`;
+        return `${value} bytes`;
+    }
+    return value.toLocaleString("en-US");
+}
+const HOW = {
+    cli: (name) => `--limit ${name}=…, or --trusted for a repo you trust`,
+    config: (name) => `\`limits: { ${name}: … }\` in dogsbay.config.yml, or \`limits: { trusted: true }\``,
+    host: (name) => `the import's \`limits.${name}\` option, or \`trusted\` for a repo you trust`,
+};
+/**
+ * The report for a tripped limit: what was not done, the measured value against the limit, and
+ * how to raise it where the import runs.
+ */
+export function limitMessage(what, name, measured, limit, host = "cli") {
+    const over = measured === undefined ? `over the ${formatLimit(name, limit)} limit` : `${formatLimit(name, measured)}, over the ${formatLimit(name, limit)} limit`;
+    return `${what}: ${LIMIT_DESCRIPTIONS[name]} ${over} (${HOW[host](name)})`;
+}
+/** UTF-8 bytes of a string, without encoding it: limits on bytes count bytes, not UTF-16 units. */
+export function utf8Bytes(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00) {
+            n += 4;
+            i++;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}

package/dist/meta.d.ts

@@ -19,13 +19,19 @@ export interface PageMeta {
     tags?: string[];
     /**
      * Broader grouping. Auto-derived from path when frontmatter
-     * doesn't supply a valid value (`content/guides/auth.md` →
-     * `["guides"]`). Override with `category: foo` or
-     * `category: [foo, bar]`.
+     * doesn't supply a valid value, emitted as **cumulative slash-
+     * paths** so each value uniquely identifies its position in the
+     * hierarchy (`content/guides/oauth/setup.md` →
+     * `["guides", "guides/oauth"]`). The bare top segment is
+     * preserved so simple queries like `category:guides` still match
+     * the whole subtree. Override with `category: foo` or
+     * `category: [foo, bar]` (explicit values pass through
+     * unchanged — no auto-prefix).
      *
      * No first-class "belongs nowhere" sentinel in v1: `category: []`
      * falls through to slug-derived default. See
-     * plans/metadata-and-taxonomies.md.
+     * plans/metadata-and-taxonomies.md and
+     * plans/hierarchical-facets.md.
      */
     category?: string[];
     /**
@@ -41,6 +47,16 @@ export interface PageMeta {
     /** ISO date strings. Consumers parse to Date when needed. */
     updated?: string;
     created?: string;
+    /**
+     * Post authors. Accepts a single string or a list in frontmatter;
+     * always normalized to a list here so consumers have one shape.
+     *
+     * Added for the blog capability (plans/blog-capability.md) — it was
+     * the only field a post needs that PageMeta did not already carry.
+     * Absent means "no byline", never "unknown author": the layout omits
+     * the row entirely rather than rendering a placeholder.
+     */
+    author?: string[];
     /** Sort hint for navigation/list pages. Lower weight first. */
     weight?: number;
     /**
@@ -77,6 +93,12 @@ export interface ParseMetaOptions {
      */
     taxonomyNames?: readonly string[];
 }
+/**
+ * Closed enum for status validation. Exported so the frontmatter CHECKER
+ * (packages/commands) reports exactly the values this parser drops, instead
+ * of restating the list a third time.
+ */
+export declare const STATUS_VALUES: readonly PageStatus[];
 /**
  * Parse and normalize frontmatter into `PageMeta`. Pure function;
  * no I/O. Unknown frontmatter keys are not lifted — they stay in
@@ -97,4 +119,3 @@ export interface ParseMetaOptions {
  *   `meta.taxonomies` as string arrays.
  */
 export declare function parseMeta(frontmatter: Record<string, unknown> | undefined, options?: ParseMetaOptions): PageMeta;
-//# sourceMappingURL=meta.d.ts.map

package/dist/meta.js

@@ -8,8 +8,12 @@
  *
  * See plans/metadata-and-taxonomies.md for the design rationale.
  */
-/** Closed enum for status validation. */
-const STATUS_VALUES = [
+/**
+ * Closed enum for status validation. Exported so the frontmatter CHECKER
+ * (packages/commands) reports exactly the values this parser drops, instead
+ * of restating the list a third time.
+ */
+export const STATUS_VALUES = [
     "draft",
     "preview",
     "stable",
@@ -58,6 +62,9 @@ export function parseMeta(frontmatter, options = {}) {
     const created = coerceIsoDate(fm.created);
     if (created)
         meta.created = created;
+    const author = coerceStringArray(fm.author);
+    if (author)
+        meta.author = author;
     if (typeof fm.weight === "number" && Number.isFinite(fm.weight)) {
         meta.weight = fm.weight;
     }
@@ -71,13 +78,29 @@ export function parseMeta(frontmatter, options = {}) {
 }
 /**
  * Auto-derive `category` from a slug. The leaf segment is treated
- * as the page filename and dropped; remaining segments become the
- * category path.
+ * as the page filename and dropped; remaining segments emit as
+ * **cumulative slash-paths**, so each value uniquely identifies its
+ * position in the document hierarchy.
  *
  * - `"guides/auth"` → `["guides"]`
- * - `"guides/oauth/setup"` → `["guides", "oauth"]`
+ * - `"guides/oauth/setup"` → `["guides", "guides/oauth"]`
+ * - `"installing/installing_aws/ipi/foo"` → `["installing", "installing/installing_aws", "installing/installing_aws/ipi"]`
  * - `"intro"` → undefined (no parent path)
  * - `""` / undefined → undefined
+ *
+ * Why cumulative instead of bare segments: a leaf name like `ipi`
+ * appears at multiple positions across a large corpus (under
+ * `installing/installing_aws/`, `installing/installing_azure/`, …).
+ * Bare segments would collide as Pagefind filter values, so the
+ * search dialog's hierarchical-facet tree can't distinguish
+ * positions and tree-click cascades leak across siblings. Cumulative
+ * paths disambiguate fully and also let the search dialog detect
+ * the slash-encoded shape automatically (no nav.json needed to build
+ * the tree). The containment semantic is preserved — every page
+ * under `installing/` still carries the bare-prefix `"installing"`
+ * value as its top-level entry, so existing filter queries like
+ * `category:installing` continue to match the whole subtree.
+ * See plans/hierarchical-facets.md ("Open follow-ups").
  */
 function deriveCategoryFromSlug(slug) {
     if (!slug)
@@ -85,7 +108,12 @@ function deriveCategoryFromSlug(slug) {
     const parts = slug.split("/").filter((p) => p.length > 0);
     if (parts.length < 2)
         return undefined;
-    return parts.slice(0, -1);
+    const parents = parts.slice(0, -1);
+    const out = [];
+    for (let i = 0; i < parents.length; i++) {
+        out.push(parents.slice(0, i + 1).join("/"));
+    }
+    return out;
 }
 function coerceStringArray(value) {
     if (typeof value === "string") {
@@ -127,4 +155,3 @@ function collectTaxonomies(fm, taxonomyNames) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
-//# sourceMappingURL=meta.js.map

package/dist/plugin.d.ts

@@ -73,9 +73,9 @@ export interface PluginVisibleConfig {
 }
 /**
  * Audit rule contract — re-stated here to avoid a circular dep
- * between `@dogsbay/types` and `@dogsbay/cli` (where the canonical
+ * between `@dogsbay/types` and `@dogsbay/site-check` (where the canonical
  * audit module lives). The shape MUST stay in sync with
- * `packages/cli/src/audit/types.ts` — adapted via a runtime
+ * `@dogsbay/site-check` (`packages/site-check/src/types.ts`) — adapted via a runtime
  * pass-through in the loader.
  */
 export interface PluginRule {
@@ -87,7 +87,7 @@ export interface PluginRule {
     /**
      * The audit runner narrows this on the rule's declared `stage`.
      * Plugins import the concrete context types from
-     * `@dogsbay/cli/audit` if they need typed access.
+     * `@dogsbay/site-check` if they need typed access.
      */
     run(ctx: unknown): PluginIssue[];
 }
@@ -266,4 +266,3 @@ export type PluginConfigEntry = string | {
     /** Options forwarded to the plugin's factory. */
     options?: unknown;
 };
-//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -13,4 +13,3 @@
  * file owns only the shapes — keeping `@dogsbay/types` light.
  */
 export {};
-//# sourceMappingURL=plugin.js.map

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;