@heroiclands/package-build 9.0.0 → 10.0.0

package/engine/content-format.mjs

@@ -0,0 +1,253 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Reading `docs/content-format.md` as data (#130).
+ *
+ * The content format — three frontmatter regions, a note vocabulary with its
+ * own `type` and `subType`, and a declared map from each note type onto each
+ * system's document fields — is prose, because that is the only form in which
+ * the *reasons* survive. But two of the things it states are checkable, and
+ * were checked by throwaway scripts while it was being drafted:
+ *
+ * - **every `system.*` target it names** must exist in the naming system's
+ *   published `schema.json`, or the specification and the system disagree; and
+ * - **every authored note** should carry only the keys the format declares for
+ *   its type, which during the migration (#127) is a progress bar as much as a
+ *   check.
+ *
+ * Both need the document as data, and this is the module that supplies it.
+ *
+ * **It reads the document's own tables rather than a transcription of them.**
+ * A hardcoded list of targets and per-type vocabularies would be a second copy
+ * of the specification, free to drift from the first the moment either is
+ * edited — which is exactly the failure the checks exist to prevent, moved one
+ * level up. So the parser knows the *shape* of the tables the document uses and
+ * nothing about their contents: no type name, no field name and no system name
+ * is written here. Editing the document changes what the checks assert.
+ *
+ * **Two table shapes carry everything.**
+ *
+ * | table | recognised by its first header cell | yields |
+ * | --- | --- | --- |
+ * | the per-type vocabulary | `` `data` property `` | the keys that type's `data:` block may carry |
+ * | the per-type mapping | `shared source` | one claim per `system.*` cell |
+ *
+ * A mapping table's remaining header cells name the systems (`→ sohl`,
+ * `→ hm3`), so the system vocabulary comes from the document too. A cell that
+ * names no field — `NA`, `**see above**`, a `flags.*` path — is not a claim,
+ * and is skipped rather than reported: the check is about `system.*` targets,
+ * and a column reading NA is the document saying this type produces no document
+ * there.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The specification this package ships.
+ *
+ * Resolved from this module rather than from the working directory: a consumer
+ * runs `content-build content-format` inside its own repository, and the
+ * document it should be checked against is the one that came with the toolchain
+ * version it resolved — the same rule `--version` follows.
+ *
+ * @type {string}
+ */
+export const CONTENT_FORMAT_PATH = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "docs",
+    "content-format.md",
+);
+
+/**
+ * What one note type's section declares.
+ *
+ * @typedef {object} TypeSpec
+ * @property {string} name - The note type, as the `### type:` heading spells it.
+ * @property {number} line - 1-based line of that heading.
+ * @property {Set<string>} dataKeys - The head segment of each declared `data`
+ *   property — what a note actually writes. `appearance.eye_color` is authored
+ *   as `appearance`, so that is the key recorded.
+ * @property {Set<string>} dataPaths - The declared paths, whole.
+ */
+
+/**
+ * One `system.*` target the specification names for one note type.
+ *
+ * @typedef {object} MappingClaim
+ * @property {string} noteType - The type whose section makes the claim.
+ * @property {string} system - The system column it sits under, from the header.
+ * @property {string} source - The shared source cell, stripped of its backticks.
+ * @property {string} target - The dotted path, `system.` prefix included.
+ * @property {number} line - 1-based line of the row.
+ * @property {number} column - 1-based column of the cell's first character.
+ */
+
+/**
+ * The specification, as data.
+ *
+ * @typedef {object} ContentFormat
+ * @property {string} file - Where it was read from, for diagnostics.
+ * @property {Map<string, TypeSpec>} types - Note type → what its section declares.
+ * @property {MappingClaim[]} claims - Every `system.*` target, in document order.
+ */
+
+/** A table row's cells, or `null` when the line is not a table row. */
+function cellsOf(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) return null;
+    // A trailing `|` closes the row; splitting the interior keeps cell indices
+    // aligned with the header's.
+    const interior = trimmed.replace(/^\|/, "").replace(/\|$/, "");
+    return interior.split("|").map((cell) => cell.trim());
+}
+
+/** Whether a row is the `| --- | --- |` rule under a header. */
+function isRule(cells) {
+    return cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+
+/** The contents of a cell written as a single inline-code span, or `undefined`. */
+function code(cell) {
+    const match = /^`([^`]+)`$/.exec(cell);
+    return match ? match[1] : undefined;
+}
+
+/**
+ * Where a cell starts on its line, 1-based.
+ *
+ * Counted by walking the row's `|` separators rather than searching for the
+ * cell's text, which would land on the wrong column whenever two cells in a row
+ * hold the same string — and `NA` appears twice on plenty of rows.
+ *
+ * @param {string} line - The raw line.
+ * @param {number} index - Which cell, 0-based, counting from after the first `|`.
+ * @returns {number|undefined} The column, or `undefined` when the row has no
+ *   such cell — dropped rather than guessed.
+ */
+function columnOfCell(line, index) {
+    // The separator opening the wanted cell is the (index + 1)-th `|`.
+    let at = -1;
+    for (let i = 0; i <= index; i += 1) {
+        at = line.indexOf("|", at + 1);
+        if (at === -1) return undefined;
+    }
+    const rest = line.slice(at + 1);
+    const lead = rest.length - rest.trimStart().length;
+    return at + lead + 2;
+}
+
+/**
+ * Parse the specification's tables.
+ *
+ * Pure: text in, model out, so a test states a miniature document rather than
+ * asserting against the real one and its 1,100 lines of prose.
+ *
+ * @param {string} text - The document's contents.
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Path recorded on the result, for diagnostics.
+ * @returns {ContentFormat} What the document declares.
+ */
+export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
+    /** @type {Map<string, TypeSpec>} */
+    const types = new Map();
+    /** @type {MappingClaim[]} */
+    const claims = [];
+
+    const lines = String(text ?? "").split("\n");
+    /** @type {TypeSpec|undefined} */
+    let current;
+    /** @type {{kind: "data"|"mapping", systems: string[]}|undefined} */
+    let table;
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+
+        const heading = /^#{2,4}\s+type:\s*(\S+)\s*$/.exec(line);
+        if (heading) {
+            current = {
+                name: heading[1],
+                line: i + 1,
+                dataKeys: new Set(),
+                dataPaths: new Set(),
+            };
+            types.set(current.name, current);
+            table = undefined;
+            continue;
+        }
+
+        const cells = cellsOf(line);
+        if (!cells) {
+            // Any non-table line ends the table. A blank line between two
+            // tables is what keeps a mapping table's rows from being read
+            // under the vocabulary table's header.
+            table = undefined;
+            continue;
+        }
+        if (isRule(cells)) continue;
+
+        // A header row, recognised by its first cell alone.
+        if (cells[0] === "`data` property") {
+            table = { kind: "data", systems: [] };
+            continue;
+        }
+        if (cells[0] === "shared source") {
+            table = {
+                kind: "mapping",
+                systems: cells.slice(1).map((cell) => cell.replace(/^→\s*/, "").trim()),
+            };
+            continue;
+        }
+        if (!table || !current) continue;
+
+        if (table.kind === "data") {
+            const declared = code(cells[0]);
+            if (!declared) continue;
+            current.dataPaths.add(declared);
+            current.dataKeys.add(declared.split(".")[0]);
+            continue;
+        }
+
+        for (let c = 1; c < cells.length; c += 1) {
+            const target = code(cells[c]);
+            if (!target || !target.startsWith("system.")) continue;
+            const system = table.systems[c - 1];
+            if (!system) continue;
+            claims.push({
+                noteType: current.name,
+                system,
+                source: code(cells[0]) ?? cells[0],
+                target,
+                line: i + 1,
+                ...(columnOfCell(line, c) === undefined ? {} : { column: columnOfCell(line, c) }),
+            });
+        }
+    }
+
+    return { file, types, claims };
+}
+
+/**
+ * Read and parse the specification from disk.
+ *
+ * @param {string} [file] - The document. Defaults to {@link CONTENT_FORMAT_PATH}.
+ * @returns {ContentFormat} What it declares.
+ */
+export function loadContentFormat(file = CONTENT_FORMAT_PATH) {
+    return parseContentFormat(fs.readFileSync(file, "utf8"), { file });
+}

package/engine/content-links.mjs

@@ -22,12 +22,20 @@
  *    anchor slug; nothing checks that a heading declaring that slug exists. A
  *    link to an anchor nobody declares compiles cleanly, emits an enricher, and
  *    dead-ends for the reader.
- * 2. **A dead address.** A *qualified* `type-shortcode` target resolving to no
- *    note is a typo. A bare `[[Name]]` that finds nothing is not — that is a
- *    worldbuilding placeholder by long-standing convention, and is left alone.
- * 3. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
+ * 2. **A dead address.** A *piped* target — `[[x|…]]` — is an address, and one
+ *    resolving to no note is a typo. So is one that does not parse as an
+ *    address at all: the pipe says the author meant one.
+ * 3. **A dead alias.** An *unpiped* target — `[[x]]` — names a note of the
+ *    source's own type. One that finds nothing may be a worldbuilding
+ *    placeholder, so it is reported as a warning rather than a failure; it is a
+ *    different problem from a dead address and reads differently.
+ * 4. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
  *    and copy frontmatter through verbatim, so a link written in a
  *    `description` is never resolved and publishes as literal `[[…]]` text.
+ *    Frontmatter is data: a `WikiLink` field is parsed by the address grammar
+ *    and a bracketed link there is a finding naming the note and the field.
+ * 5. **An alias two notes of one type both claim.** It used to be deleted
+ *    silently, so the pair resolved to nothing and nobody was told (#131).
  *
  * **This resolves links the way the builds do**, calling the same
  * {@link readQualifier} and the same {@link parseWikilink} rather than a second
@@ -64,8 +72,9 @@ import {
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
 import { homepageAddresses, isHomepage } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
-import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
+import { parseWikilink, resolvesAsAddress, WIKILINK } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
+import { aliasesOf, aliasKey, indexAliases } from "./alias-index.mjs";
 
 /**
  * Every `{#anchor}` a note declares on a heading.
@@ -125,8 +134,6 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
     }
 
     const byKey = new Map();
-    const byAlias = new Map();
-    const aliasCollide = new Set();
 
     // The one package every note in this tree belongs to. Taken from the
     // configuration, never from a note: `package:` is retired, so there is no
@@ -145,25 +152,23 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
                 byKey.set(canonicalKey(pkg, `doc${type}`, fm.shortcode), note);
             }
         }
-        const aliases = [
-            ...(Array.isArray(fm.aliases) ? fm.aliases : []),
-            ...(Array.isArray(fm.name?.aliases) ? fm.name.aliases : []),
-            fm.name?.full,
-            path.basename(note.file, ".md").replace(/_/g, " "),
-        ].filter((a) => typeof a === "string" && a);
-        for (const a of aliases) {
-            const k = `${type}|${a}`.toLowerCase();
-            if (aliasCollide.has(k)) continue;
-            const cur = byAlias.get(k);
-            if (cur && cur !== note) {
-                byAlias.delete(k);
-                aliasCollide.add(k);
-            } else if (!cur) {
-                byAlias.set(k, note);
-            }
-        }
     }
 
+    // The alias half of the two namespaces, built by the shared rule so the
+    // checker, the pack build and the site build cannot disagree about what a
+    // bare `[[…]]` can name (#131).
+    const {
+        byKey: byAlias,
+        claims: aliasClaims,
+        collisions: aliasCollisions,
+    } = indexAliases(
+        notes.map((note) => ({
+            type: note.type,
+            aliases: aliasesOf(note.fm),
+            value: note,
+        })),
+    );
+
     const types = new Set(notes.map((n) => n.type));
 
     // A foreign package may use a type this tree has never seen, so its types
@@ -195,7 +200,9 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
      *
      * @param {object} note - A note from this index.
      * @returns {Array<{target: string, anchor: string, text: string,
-     *   occurrence: number}>} `target` is `""` for a same-page `[[#anchor]]`.
+     *   occurrence: number, labelled: boolean}>} `target` is `""` for a
+     *   same-page `[[#anchor]]`; `labelled` says which namespace the target
+     *   belongs to (#131).
      */
     function linksOf(note) {
         let body = note.body;
@@ -215,39 +222,52 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
         // Code is verbatim, so a `[[…]]` inside a fence, an indented block or
         // an inline span is not a link — the compilers make none of it either.
         for (const [all, rawInner] of matchAllOutsideCode(body, new RegExp(WIKILINK.source, "g"))) {
-            const { target, anchor } = parseWikilink(rawInner);
+            const parsed = parseWikilink(rawInner);
+            const { target, anchor } = parsed;
             const occurrence = (seen.get(all) ?? 0) + 1;
             seen.set(all, occurrence);
             // `text` is the link exactly as authored, which is what locates it
             // in the file. A link a table generated is not in the file at all,
             // so the search simply fails and a finding names the file.
-            out.push({ target, anchor, text: all, occurrence });
+            out.push({
+                target,
+                anchor,
+                text: all,
+                occurrence,
+                labelled: resolvesAsAddress(parsed),
+            });
         }
         return out;
     }
 
     /**
-     * Resolve a link target the way both builds do, or `undefined`.
+     * The note an **alias** names, or `undefined`.
+     *
+     * Scoped to the *source* note's own type, so one word may be an alias in
+     * several types without colliding. An alias two same-type notes claim is
+     * absent from the index entirely — see {@link indexAliases} — so this can
+     * never resolve to whichever was walked first.
+     *
+     * @param {object} note - The note the link is written in.
+     * @param {string} target - The link target, anchor already removed.
+     * @returns {object|undefined} The note it names.
+     */
+    function resolveAlias(note, target) {
+        return byAlias.get(aliasKey(note.type, target));
+    }
+
+    /**
+     * The note an **address** names, or `undefined`.
      *
      * The qualifier is read with {@link readQualifier} rather than a second
      * copy of the rule, so this cannot drift from what the builds do — the two
-     * separators, the first-hyphen split, and the known-type condition that
-     * keeps a hyphenated *name* an alias.
+     * separators, the first-hyphen split, and the optional leading package
+     * segment.
      *
-     * That condition is why the type-scoped alias index is not enough alone: it
-     * reaches only a target of the source's **own** type, so a cross-type
-     * `[[type-shortcode#anchor]]` would resolve to nothing and its anchor go
-     * unchecked — silently, since an unresolvable target is treated as
-     * external.
-     *
-     * @param {object} note - The note the link is written in.
-     * @param {string} target - The link target.
+     * @param {string} target - The link target, anchor already removed.
      * @returns {object|undefined} The note it addresses.
      */
-    function resolve(note, target) {
-        const direct =
-            byAlias.get(`${note.type}|${target}`.toLowerCase()) ?? byKey.get(target.toLowerCase());
-        if (direct) return direct;
+    function resolveAddress(target) {
         const qualified = readQualifier(target, types, packages);
         if (!qualified || qualified.reason) return undefined;
         return byKey.get(
@@ -257,6 +277,24 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
         );
     }
 
+    /**
+     * Resolve a link target the way both builds do, or `undefined`.
+     *
+     * **The pipe chooses the namespace, and there is no fallback either way**
+     * (#131) — see {@link resolvesAsAddress} for why. The caller therefore has
+     * to say which form was authored; it is a required argument rather than a
+     * defaulted one, because either default would silently resolve half the
+     * corpus through the wrong namespace.
+     *
+     * @param {object} note - The note the link is written in.
+     * @param {string} target - The link target.
+     * @param {boolean} labelled - Whether the link carried a `|`.
+     * @returns {object|undefined} The note it names.
+     */
+    function resolve(note, target, labelled) {
+        return labelled ? resolveAddress(target) : resolveAlias(note, target);
+    }
+
     /**
      * The manifest entry a qualified address names in another package, or null.
      *
@@ -295,8 +333,14 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
         contentPackage: pkg,
         foreign,
         manifests: manifestsComplete(localPackages, foreign.packages),
+        /** Every note claiming each type-scoped alias, colliding ones included. */
+        aliasClaims,
+        /** One entry per alias two or more same-type notes claim (#131). */
+        aliasCollisions,
         linksOf,
         resolve,
+        resolveAlias,
+        resolveAddress,
         manifestHit,
         /** Whether a target reads as a qualified address at all. */
         isAddress: (target) => Boolean(readQualifier(target, types, packages)),
@@ -611,22 +655,35 @@ export function auditHomepageLinks(index) {
 /**
  * Every link in a tree that lands nowhere.
  *
+ * **The two failure modes are separate findings, because they are separate
+ * problems** (#131). A piped target the author declared to be an address, and
+ * which resolves nowhere, is a typo: every package it could name is either
+ * built here or vendored, so there is no third possibility. An unpiped target
+ * naming no note of the source's type may be exactly that typo — or a
+ * worldbuilding placeholder, which is a long-standing convention in the
+ * setting trees. So the first is an error and the second a warning, and the
+ * caller can tell them apart without parsing a message.
+ *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
+ *   deadAliases: object[], aliasCollisions: object[],
  *   frontmatterLinks: object[], homepageLinks: object[],
  *   usedManifest: Set<string>}} The findings, and which addresses a foreign
- *   manifest answered.
+ *   manifest answered. Each `deadAddresses` entry carries a `reason`:
+ *   `"not-an-address"` when the target does not parse as one at all,
+ *   `"unknown-type"` when it is qualified but names no known type, and
+ *   `"unresolved"` when it parses and nothing answers it.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, resolve, manifestHit, isAddress } = index;
 
     const deadAnchors = [];
     for (const note of notes) {
-        for (const { target, anchor, text, occurrence } of linksOf(note)) {
+        for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
             if (!anchor) continue;
-            const dest = target ? resolve(note, target) : note;
-            // An unresolvable target is an external reference, not this
-            // check's business.
+            const dest = target ? resolve(note, target, labelled) : note;
+            // An unresolvable target is reported by the address or alias pass
+            // below; its anchor has nothing to be checked against.
             if (!dest) continue;
             if (!anchors.get(dest).has(slugify(anchor))) {
                 deadAnchors.push({
@@ -641,28 +698,47 @@ export function auditLinks(index) {
     }
 
     const deadAddresses = [];
+    const deadAliases = [];
     const usedManifest = new Set();
     for (const note of notes) {
-        for (const { target, text, occurrence } of linksOf(note)) {
+        for (const { target, text, occurrence, labelled } of linksOf(note)) {
             if (!target) continue; // a same-page `[[#anchor]]`
-            // Only a *qualified* target is an address. A bare `[[Name]]` that
-            // finds nothing is a worldbuilding placeholder by long-standing
-            // convention, and is deliberately left alone.
-            if (!isAddress(target)) continue;
-            if (resolve(note, target)) continue;
+            const at = { note, target, text, occurrence };
+
+            if (!labelled) {
+                if (index.resolveAlias(note, target)) continue;
+                // Kept alongside, so a report can say *why* nothing answered:
+                // an alias claimed twice is absent from the index, and blaming
+                // this note for it would blame the wrong file.
+                const claimants = index.aliasClaims.get(aliasKey(note.type, target)) ?? [];
+                deadAliases.push({ ...at, ambiguous: claimants.length > 1, claimants });
+                continue;
+            }
+
+            if (!isAddress(target)) {
+                deadAddresses.push({ ...at, reason: "not-an-address" });
+                continue;
+            }
+            if (index.resolveAddress(target)) continue;
             // A manifest answers with the target package's own build output
             // rather than a reviewed guess.
             if (manifestHit(target)) {
                 usedManifest.add(target.toLowerCase());
                 continue;
             }
-            deadAddresses.push({ note, target, text, occurrence });
+            const read = readQualifier(target, index.types, index.packages);
+            deadAddresses.push({
+                ...at,
+                reason: read?.reason === "unknown-type" ? "unknown-type" : "unresolved",
+            });
         }
     }
 
     return {
         deadAnchors,
         deadAddresses,
+        deadAliases,
+        aliasCollisions: index.aliasCollisions,
         frontmatterLinks: index.frontmatterLinks,
         homepageLinks: auditHomepageLinks(index),
         usedManifest,
@@ -716,9 +792,9 @@ export function walkReachability(index, { root, scope, stopAt = () => false }) {
     while (queue.length) {
         const note = queue.shift();
         if (stopAt(note)) continue;
-        for (const { target } of index.linksOf(note)) {
+        for (const { target, labelled } of index.linksOf(note)) {
             if (!target) continue;
-            const dest = index.resolve(note, target);
+            const dest = index.resolve(note, target, labelled);
             if (!dest || !scope(dest) || reached.has(dest)) continue;
             reached.add(dest);
             queue.push(dest);

package/engine/content-lint.mjs

@@ -59,6 +59,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { checkHomepageCount, isHomepage } from "./homepage.mjs";
@@ -66,6 +67,12 @@ import { checkHomepageCount, isHomepage } from "./homepage.mjs";
 /**
  * The shape every `shortcode` must match: ASCII letters and digits only.
  *
+ * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
+ * is the last segment of a canonical address, and the rule it is held to is the
+ * rule *every* segment is held to — so the two are one constant rather than two
+ * free to drift apart (#59). The name survives because this is where the rule
+ * is applied to a note.
+ *
  * Case is deliberately **not** constrained: hundreds of authored shortcodes are
  * mixed-case and collide with nothing, so tightening that is a separate
  * decision from this one.
@@ -74,7 +81,7 @@ import { checkHomepageCount, isHomepage } from "./homepage.mjs";
  * import a build-time dependency into shipped code — and is expected to pin the
  * two together with a test rather than trust that they still agree.
  */
-export const SHORTCODE_PATTERN = /^[A-Za-z0-9]+$/;
+export const SHORTCODE_PATTERN = ADDRESS_SEGMENT_PATTERN;
 
 /**
  * Whether a value is a well-formed shortcode.

package/engine/diagnostics.mjs

@@ -363,3 +363,36 @@ export function yamlKeyPath(field) {
     }
     return segments;
 }
+
+/**
+ * Where a key sits **inside a note's frontmatter fence**, addressed by path.
+ *
+ * {@link positionInFrontmatter} searches the fence for a key by name, which is
+ * the right tool while a note's vocabulary is flat: a key appears once and the
+ * first line matching it is the one. It stops being the right tool the moment
+ * the same name is legal in two regions — `data.weight` and a top-level
+ * `weight` are different keys, and a search finds whichever comes first.
+ *
+ * So this is the located form for the closed regions (#128). It reuses
+ * {@link positionOfYamlPath} rather than repeating its parse, which is what
+ * keeps a finding about `data.weight` pointing at `data.weight`.
+ *
+ * @param {string} raw - The note's full contents, frontmatter included.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node, from the
+ *   top of the frontmatter.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when there is no fence or the path resolves to nothing — dropped rather
+ *   than guessed.
+ */
+export function positionOfFrontmatterPath(raw, keyPath, { key = false } = {}) {
+    if (typeof raw !== "string") return {};
+    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!fence) return {};
+    const position = positionOfYamlPath(fence[1], keyPath, { key });
+    // +1: the fence's line 1 is the file's line 2, the opening `---` being the
+    // first. `positionOfYamlPath` already counts from 1 within the block.
+    return position.line === undefined ? {} : { ...position, line: position.line + 1 };
+}