@fro.bot/wiki-write-core 0.1.3 → 0.2.0

package/README.md

@@ -15,7 +15,13 @@ pnpm add @fro.bot/wiki-write-core
 - Node `>=24`.
 - **ESM-only.** The exports declare `import` and `types` conditions, with no `require` condition and no CommonJS build. CommonJS consumers fail at package resolution by design.
 
-The package ships unbundled ESM JavaScript with declaration files from the committed `dist/` directory. No install-time build step is required. CI rebuilds `dist/` in a temporary directory and fails when the committed output differs from `src/`.
+The published package ships unbundled ESM JavaScript with declaration files in `dist/`. No install-time build step is required.
+
+In the repository the package resolves to its TypeScript source: `exports` maps every subpath to `./src/<name>.ts`, and the only file committed under `dist/` is `gate-contract.json`. The release build compiles `dist/` and stages a manifest that differs from the committed one in `exports` alone, pointing each subpath at `./dist/<name>.js` with `./dist/<name>.d.ts` as its types. `npm pack` and `npm publish` run from that staged directory, so the committed manifest is never rewritten.
+
+`bun run check:wiki-write-core-package` is the local and CI check: it builds the package, fails when the committed `dist/gate-contract.json` differs from the fresh build, packs the staged package, unpacks the tarball into a scratch `node_modules`, then resolves and imports every `exports` subpath under Node and type-checks a consumer module that imports them all. `bun run build` rewrites the committed marker after a change under `src/`, `tsconfig.build.json` or the manifest's `exports` or `files`.
+
+`--stage <dir>` replaces whatever is at `<dir>`, so it refuses anything but a target that resolves (through symlinks) to somewhere strictly under the OS temp directory or `RUNNER_TEMP`, and it replaces an existing directory only when a previous stage left its `wiki-write-core-stage.marker` there. A root must be absolute and must not resolve to a filesystem root (so `RUNNER_TEMP=/` is refused), and a stage that contains a hidden file or directory is refused, because `upload-artifact` drops them and the publish job's digest would no longer match. The target is judged before anything is built or written, so a refused run leaves the committed `dist/gate-contract.json` alone, and again just before the replacement. Refusals happen before anything is created, moved or removed. If a replacement fails and the original cannot be restored either, the original is kept in a `.wiki-write-core-dist-backup-*` sibling and the error names it.
 
 ## Fro Bot defaults
 
@@ -27,9 +33,9 @@ The package targets the Fro Bot control plane and carries its coordinates as def
 
 When a call receives no Octokit client (`params.octokit`), it reads `GITHUB_TOKEN` from the environment and fails with a remediation message if the variable is unset.
 
-The build also emits `dist/gate-contract.json` with `version` from `GATE_CONTRACT_VERSION` and `sourceTreeHash` from the same computed source hash embedded in `gate-contract.js`. Downstream writers can fetch this marker through the repository contents API; the same distribution drift check verifies the committed marker. `version` is the gate criterion: a mismatch means a deliberate contract break and refuses writes. `sourceTreeHash` is diagnostic only: it moves with ordinary source changes and reports drift in the pinned copy, but must never block writes.
+The build also emits `dist/gate-contract.json` with `version` from `GATE_CONTRACT_VERSION` and `sourceTreeHash` from the same computed source hash embedded in `gate-contract.js`. This is the one file committed under `dist/`: downstream writers fetch it from `main`, so it stays at that path. `bun run check:wiki-write-core-package` verifies the committed marker against a fresh build, and the same marker ships in the tarball. `version` is the gate criterion: a mismatch means a deliberate contract break and refuses writes. `sourceTreeHash` is diagnostic only: it moves with ordinary source changes and reports drift in the pinned copy, but must never block writes.
 
-The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its root entrypoint. The build embeds a deterministic hash covering every non-test TypeScript file under `src/`, the resolved `tsconfig.build.json` configuration including inherited settings, and canonicalized `exports` and `files` values from `package.json`. Object-key order and `files` array order do not affect the hash. The hash does not cover tests, this README, other manifest fields such as dependencies or version, or runtime dependencies. Because it hashes the _resolved_ compiler configuration, a TypeScript upgrade that changes an inherited default or the `--showConfig` serialization moves the hash with no semantic change to the shipped code; a hash that shifts across a compiler bump is expected and does not by itself indicate gate drift.
+The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its root entrypoint. In the repository that entrypoint is source, so `GATE_SOURCE_TREE_HASH` is the placeholder `__SOURCE_TREE_HASH__`; only the built `dist/gate-contract.js` in the tarball carries the hash. The build embeds a deterministic hash covering every non-test TypeScript file under `src/`, the resolved `tsconfig.build.json` configuration including inherited settings, and canonicalized `exports` and `files` values of the published manifest (`exports` in its `dist` form). Object-key order and `files` array order do not affect the hash. The hash does not cover tests, this README, other manifest fields such as dependencies or version, or runtime dependencies. Because it hashes the _resolved_ compiler configuration, a TypeScript upgrade that changes an inherited default or the `--showConfig` serialization moves the hash with no semantic change to the shipped code; a hash that shifts across a compiler bump is expected and does not by itself indicate gate drift.
 
 `GATE_SOURCE_TREE_HASH` is the automatic drift detector: compare it when you need to know whether the shipped gate inputs changed. `GATE_CONTRACT_VERSION` is a deliberate, human-set marker for an intentional consumer-visible contract break; it is not expected to change for every source edit. Neither value proves that dependencies or the runtime behave identically. Consumers should compare the source hash for ordinary gate-input drift and the contract version when deciding whether an intentional contract migration is required.
 
@@ -39,6 +45,28 @@ The package exports `GATE_CONTRACT_VERSION` and `GATE_SOURCE_TREE_HASH` from its
 
 `WikiLintFindingKind` includes `correction-eroded` for a blocking active-correction failure and `correction-needs-reconfirmation` for an advisory lifecycle or formatting-only change. Both retain the existing `{kind, path, message, target?}` runtime shape and fingerprint derivation. Consumers with exhaustive matches must handle both kinds.
 
+A page that opens a frontmatter block and never closes it is reported as `invalid-frontmatter`; it was reported as `missing-frontmatter` while the block was read as no block. Wiki repair counts such a page as out of scope, as it does for any `invalid-frontmatter` finding.
+
+## Frontmatter block
+
+`splitFrontmatterBlock(content)` (exported from the root entry and from `@fro.bot/wiki-write-core/frontmatter`) finds the YAML frontmatter block at the start of a document. It does not parse YAML. The root entry already exports the wiki page reader as `splitFrontmatter`, so the splitter has another name.
+
+- The block opens only when the content starts with a line that is exactly `---`. A trailing space, a byte-order mark or a blank line before it means there is no block.
+- A line ending is LF or CRLF; a lone CR is part of its line.
+- The block closes at the first later line that is `---` followed only by spaces or tabs. `---x`, `----` and `--- text` are content of the block.
+- The result is `{kind: 'none'}`, `{kind: 'malformed'}` (opened and never closed, which includes a file that is only `---`) or `{kind: 'block', opening, text, textEnding, closing, body}`. A block carries the pieces that put the document back: `opening + text + textEnding + closing + body` is the original content. `text` is what a YAML parser reads (it is `''` for an empty block); `textEnding` is the line ending of the last line of `text`, or `''` for a block with no lines; `closing` is the closing line with its spaces, tabs and line ending. A caller that rewrites a line of `text` rebuilds the file from the result alone and keeps every other byte.
+- The scan visits each line once, so its running time grows linearly with the content, an unclosed block included.
+
+The package's own readers (`parseFrontmatterDocument`, `splitFrontmatter`, the ingest's page parser and the repo-page move) all use it. Each keeps its error texts and its body handling. An empty block is an empty mapping for the document reader and the ingest parser; a block that parses to `null` (whitespace, comments, `null`, `...`) is not a mapping and gets each reader's rule for a non-mapping. The wiki page reader reports an unclosed block as `Invalid frontmatter: missing closing --- delimiter`.
+
+## Target page sources
+
+When the ingest writes the page of the `repo:` target and that page lists no sources (no `sources` key, or an empty list), the page lists `{url, accessed}` with the target's `https://github.com/<owner>/<name>` URL and the date of the ingest's timestamp. When the page on the branch already has an entry for the target, its whole `sources` list is carried over as it is, so a repeat write changes nothing, a repeat after a migration included. The stamp applies only when the owner and name are plain GitHub names (ASCII letters, digits, `.`, `_` and `-`, not `.` or `..`); for any other target the page is written without one. A page that lists any source is never changed, and neither is a `sources` value that is not a list. When the ingest migrates a page to the target's slug by a trusted node ID, the merged page also gains the target's URL if no entry matches it, and keeps its other entries. No other repo page in the write is stamped, and a write whose target is a page path (the dashboard's case) is never stamped. Whether an entry matches the target uses the privacy gate's URL rule: `https`, host `github.com`, no port, owner and name equal without case, any path after them.
+
+## Gate contract version
+
+`GATE_CONTRACT_VERSION` stays at 1 for the splitter and the reader changes. A bump makes every dashboard save fail until the dashboard ships a release that carries the same version, and the changes here do not need that: no page on `data` changes meaning, the dashboard already has a message for both lint finding kinds, and the dashboard writes with its own installed copy of this package. `dist/gate-contract.json` still changes, because its `sourceTreeHash` follows the source.
+
 ## Releasing
 
 A merge to `main` that changes `packages/wiki-write-core/` releases the package through `.github/workflows/release-wiki-write-core.yaml`. Versions are the `wiki-write-core-v<version>` tags (for example `wiki-write-core-v0.1.1`), and each tag has a GitHub release.
@@ -55,10 +83,13 @@ Only commits that touch `packages/wiki-write-core/` are analyzed. The commit typ
 - A scoped suppression wins over a breaking marker: `build(dev)!:` releases nothing.
 - While the package is 0.x it never releases a major version; a breaking change is a minor bump.
 - A commit containing `[skip release]` (or `[release skip]`) is ignored by the release analysis.
+- Pull requests are squash-merged with `squash_merge_commit_title: PR_TITLE` (`common-settings.yaml`), so the PR title is the commit header the analysis reads. Pick the title type for the release you want.
+- A PR that changes only tests, docs other than the README, or other files under `packages/wiki-write-core/` that should not ship needs a non-releasing title (`test:`, `docs:`, `chore:`, `refactor:` or `build(dev):`). A `fix:` or `build:` title there publishes a patch.
+- A PR that changes nothing under `packages/wiki-write-core/` does not count toward the release type, whatever its own type. The release runs on every push to `main` and reads every package commit since the last release tag, so such a merge can still publish an earlier package change that has not been released yet.
 
 ### Publishing
 
-The `publish` job uses npm trusted publishing (OIDC) from `release-wiki-write-core.yaml` in the `release` environment, and publishes with provenance. There is no npm token. It publishes the committed `dist/`, which the `build` job proves equals a fresh build.
+The `publish` job uses npm trusted publishing (OIDC) from `release-wiki-write-core.yaml` in the `release` environment, and publishes with provenance. There is no npm token. It publishes the package the `build` job staged: the compiled `dist/` and a manifest whose `exports` point at it. The `build` job proves the packed tarball resolves, imports and type-checks every export. The `publish` job runs no repository script. The `build` job exposes a digest of the staged tree (sha256 over the `<sha256>  <path>` listing of every file, in byte order of the path) as a job output, which comes from the runner that built the package and not from the artifact store. The `publish` job recomputes it over what it downloaded and refuses unless the two are equal, before it reads or installs anything. It then checks that the staged manifest is the committed one with `exports` rewritten (each `./src/<name>.ts` becomes `./dist/<name>.js` with `./dist/<name>.d.ts` as its types, and no target has a `.`, `..` or empty segment) and replaces the checkout's `package.json` and `dist/` with the staged files. semantic-release then changes only the manifest's `version` (`npm version`, which the digest does not cover because it is checked first), and `npm publish` packs the same files the `build` job's tarball check proved.
 
 Verify a release:
 

package/dist/code-regions.js

@@ -88,6 +88,8 @@ export function findRegionAt(regions, offset) {
 }
 function findInlineSpans(line) {
     const spans = [];
+    // Where each length of backtick run starts on this line, built when the first opener needs it.
+    let runStartsByLength;
     let index = 0;
     while (index < line.length) {
         const character = line[index];
@@ -101,30 +103,47 @@ function findInlineSpans(line) {
         }
         const openEnd = skipBackticks(line, index);
         const runLength = openEnd - index;
-        let searchFrom = openEnd;
-        let closeEnd = -1;
-        while (searchFrom < line.length) {
-            const closeStart = line.indexOf('`', searchFrom);
-            if (closeStart === -1) {
-                break;
-            }
-            const candidateEnd = skipBackticks(line, closeStart);
-            if (candidateEnd - closeStart === runLength) {
-                closeEnd = candidateEnd;
-                break;
-            }
-            searchFrom = candidateEnd;
-        }
-        if (closeEnd === -1) {
+        runStartsByLength ??= indexBacktickRuns(line);
+        // The closer is the first later run of exactly the opener's length. Openers only move forward, so each
+        // length's cursor does too, and every run is passed over at most once.
+        const closeStart = nextRunAtOrAfter(runStartsByLength.get(runLength), openEnd);
+        if (closeStart === undefined) {
             index = openEnd;
         }
         else {
+            const closeEnd = closeStart + runLength;
             spans.push({ start: index, end: closeEnd });
             index = closeEnd;
         }
     }
     return spans;
 }
+/** The start offsets of the maximal backtick runs of `line`, grouped by the length of the run. */
+function indexBacktickRuns(line) {
+    const runStartsByLength = new Map();
+    for (let start = line.indexOf('`'); start !== -1;) {
+        const end = skipBackticks(line, start);
+        const runs = runStartsByLength.get(end - start);
+        if (runs === undefined) {
+            runStartsByLength.set(end - start, { starts: [start], next: 0 });
+        }
+        else {
+            runs.starts.push(start);
+        }
+        start = line.indexOf('`', end);
+    }
+    return runStartsByLength;
+}
+/** The first run start at least `minimum`. Callers ask with increasing `minimum`, so the cursor only advances. */
+function nextRunAtOrAfter(runs, minimum) {
+    if (runs === undefined) {
+        return undefined;
+    }
+    while (runs.next < runs.starts.length && (runs.starts[runs.next] ?? minimum) < minimum) {
+        runs.next += 1;
+    }
+    return runs.starts[runs.next];
+}
 function skipBackticks(line, from) {
     let index = from;
     while (line[index] === '`') {

package/dist/corrections-survival.d.ts

@@ -30,6 +30,12 @@ export declare function normalizeFormattingText(value: string): string;
  * Masks markdown inline links `[label](url)` to spaces so exact prose matching ignores link
  * targets; wiki links `[[...]]` are left untouched (module docstring). A regex port was proven
  * non-equivalent by exhaustive differential testing (corrections-survival.test.ts), so this
- * scanner stays; its directived lines are deterministic hangs under mutation, not timing noise.
+ * stays a scanner.
+ *
+ * At each `]` that is followed by `(` and preceded by a `[`, the link runs from the last `[` to the
+ * `)` that closes that `(`, counting nested parentheses. A `(` with no closing `)` is not a link,
+ * and the scan goes on from the next character. After a link, the scan resumes past its `)` with no
+ * `[` open. The closing `)` of every `(` is found once, up front, so the scan is linear in the
+ * length of the content.
  */
 export declare function maskMarkdownLinks(content: string): string;

package/dist/corrections-survival.js

@@ -1,5 +1,6 @@
 import { normalizeCorrectionText } from "./correction-text.js";
 import { assertCorrectionsFile, getCorrectionLifecycle, } from "./corrections.js";
+import { replaceLinkLabels } from "./link-labels.js";
 import { maskNonProseContent } from "./rendering-policy.js";
 import { collectWikiPages } from "./wiki-utils.js";
 /**
@@ -94,21 +95,18 @@ export function verifyCorrectionSurvival(files, corrections, fallbackFiles = {})
  * the pre-refactor reference implementation.
  */
 export function normalizeFormattingText(value) {
-    const markdownLinkPattern = /!?(?:\[([^\]]*)\]\([^)]*\)|\[\[([^\]|]+)(?:\|([^\]]+))?\]\])/gu;
-    return (value
-        .normalize('NFKC')
-        .replaceAll(markdownLinkPattern, renderVisibleLinkText)
+    return (replaceLinkLabels(value.normalize('NFKC'), renderVisibleLinkText)
         // `\s+` below absorbs any run this leaves; a `+` here would be unobservable.
         .replaceAll(/[^\p{L}\p{N}]/gu, ' ')
         .trim()
         .replaceAll(/\s+/gu, ' ')
         .toLowerCase());
 }
-function renderVisibleLinkText(_match, markdownText, wikiTarget, wikiLabel) {
-    // markdownLinkPattern's outer alternation guarantees exactly one branch matched whenever this
-    // callback runs: the markdown branch always captures markdownText (possibly '', never
-    // undefined), and the wiki branch always captures wikiTarget (required, 1+ chars). A final
-    // '' fallback covering "neither captured" is unreachable -- asserted, not defaulted.
+function renderVisibleLinkText({ markdownText, wikiTarget, wikiLabel }) {
+    // replaceLinkLabels calls this with exactly one branch matched: the markdown branch always has
+    // markdownText (possibly '', never undefined), and the wiki branch always has wikiTarget
+    // (required, 1+ chars). A final '' fallback covering "neither captured" is unreachable --
+    // asserted, not defaulted.
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see comment above
     return (markdownText ?? wikiLabel ?? wikiTarget);
 }
@@ -116,45 +114,54 @@ function renderVisibleLinkText(_match, markdownText, wikiTarget, wikiLabel) {
  * Masks markdown inline links `[label](url)` to spaces so exact prose matching ignores link
  * targets; wiki links `[[...]]` are left untouched (module docstring). A regex port was proven
  * non-equivalent by exhaustive differential testing (corrections-survival.test.ts), so this
- * scanner stays; its directived lines are deterministic hangs under mutation, not timing noise.
+ * stays a scanner.
+ *
+ * At each `]` that is followed by `(` and preceded by a `[`, the link runs from the last `[` to the
+ * `)` that closes that `(`, counting nested parentheses. A `(` with no closing `)` is not a link,
+ * and the scan goes on from the next character. After a link, the scan resumes past its `)` with no
+ * `[` open. The closing `)` of every `(` is found once, up front, so the scan is linear in the
+ * length of the content.
  */
 export function maskMarkdownLinks(content) {
-    const masked = content.split('');
+    const characters = content.split('');
+    const closers = findClosingParentheses(characters);
+    const masked = [...characters];
     let open = -1;
-    let index = 0;
-    // Stryker disable next-line BlockStatement,EqualityOperator: BlockStatement mutation destroys mandatory loop progress (deterministic hang, not a timing artifact); EqualityOperator's >= variant hangs on empty content (0 >= 0 is true, index only grows, so it never becomes false again) and its <= variant only extends the loop to content[content.length], which is always undefined and has no side effect on open/masked/depth
-    while (index < content.length) {
-        if (content[index] === '[')
+    let resumeAt = 0;
+    for (const [index, character] of characters.entries()) {
+        if (index < resumeAt)
+            continue;
+        if (character === '[')
             open = index;
-        if (content[index] === ']' && content[index + 1] === '(' && open !== -1) {
-            let close = index + 2;
-            let depth = 1;
-            // Split from the original `close < content.length && depth > 0` combined condition so
-            // each half's mutants land on their own line; the `depth <= 0` check below is bounded by
-            // this while's own `close < content.length`, so its mutants are not a hang, just wrong
-            // output, and are killed by the differential test like any other behavior change.
-            // Stryker disable next-line BlockStatement,EqualityOperator: BlockStatement mutation destroys mandatory loop progress (deterministic hang, not a timing artifact); EqualityOperator's >= variant hangs when close starts at or past content.length (a link's `](` at the very end of the string) for the same reason as the outer loop above, and its <= variant only extends the loop to content[content.length], which is always undefined and has no side effect on open/masked/depth
-            while (close < content.length) {
-                if (depth <= 0)
-                    break;
-                if (content[close] === '(')
-                    depth += 1;
-                else if (content[close] === ')')
-                    depth -= 1;
-                // Stryker disable next-line AssignmentOperator: mutation destroys mandatory loop progress; deterministic hang, not a timing artifact
-                close += 1;
-            }
-            if (depth === 0) {
-                // Stryker disable next-line AssignmentOperator: mutation destroys mandatory loop progress; deterministic hang, not a timing artifact
-                for (let maskIndex = open; maskIndex < close; maskIndex += 1)
-                    masked[maskIndex] = ' ';
-                index = close;
+        if (character === ']' && open !== -1) {
+            // `closers` has an entry only for a `(`, so the next character is a `(` with a closer or there is no link.
+            const close = closers.get(index + 1);
+            if (close !== undefined) {
+                masked.fill(' ', open, close + 1);
+                resumeAt = close + 1;
                 open = -1;
-                continue;
             }
         }
-        // Stryker disable next-line AssignmentOperator: mutation destroys mandatory loop progress; deterministic hang, not a timing artifact
-        index += 1;
     }
     return masked.join('');
 }
+/**
+ * Maps the index of each `(` to the index of the `)` that closes it, counting nested parentheses,
+ * or to `undefined` when nothing closes it. Read from the right, each `(` takes the nearest `)`
+ * that no `(` between them has taken, which pairs the same parentheses as counting depth to the
+ * right of each `(`. A `)` with no `(` before it is left unpaired and never looked up.
+ */
+function findClosingParentheses(characters) {
+    const closers = new Map();
+    const unpaired = [];
+    for (const [reversedIndex, character] of characters.toReversed().entries()) {
+        const index = characters.length - 1 - reversedIndex;
+        if (character === ')') {
+            unpaired.push(index);
+        }
+        else if (character === '(') {
+            closers.set(index, unpaired.pop());
+        }
+    }
+    return closers;
+}

package/dist/frontmatter-block.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What `splitFrontmatterBlock` found at the start of a document.
+ *
+ * - `none`: the content does not open a block.
+ * - `malformed`: the content opens a block and never closes it. It carries no content, so a caller cannot read
+ *   the pieces of a block that was not closed.
+ * - `block`: the content opens and closes a block. The five strings put the content back byte for byte:
+ *   `opening + text + textEnding + closing + body` is the original content.
+ *
+ * The pieces are strings, not offsets, so an editor that rewrites a line of the block rebuilds the file from the
+ * result alone, with the line endings, trailing spaces and body it found.
+ */
+export type FrontmatterBlockSplit = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'malformed';
+} | {
+    readonly kind: 'block';
+    /** The opening line with its line ending: `---` and LF or CRLF. */
+    readonly opening: string;
+    /**
+     * The lines between the opening and the closing line, each with the line ending it has, except the last line,
+     * whose ending is `textEnding`. It is what a YAML parser reads. It is `''` for a block with no lines and for
+     * a block of one blank line, which `textEnding` tells apart.
+     */
+    readonly text: string;
+    /** The line ending of the last line of `text`: `\n`, `\r\n`, or `''` when the block has no lines. */
+    readonly textEnding: string;
+    /** The closing line: `---`, any spaces or tabs after it, and its line ending. It has none at the end of the content. */
+    readonly closing: string;
+    /** Everything after the closing line, untouched. */
+    readonly body: string;
+};
+/**
+ * Finds the YAML frontmatter block at the start of `content`. It does not parse the YAML.
+ *
+ * The block rule:
+ * - The content starts with a line that is exactly `---`. A space, a byte-order mark, a blank line or any other
+ *   character before it or after it, on that line, means there is no block.
+ * - A line ending is LF or CRLF. A lone CR is part of its line.
+ * - The block ends at the first later line that is `---` followed only by spaces or tabs. A line such as `---x`,
+ *   `----` or `--- text` is part of the block.
+ * - A block can be empty: `---` directly followed by `---` gives empty text.
+ * - A block that is opened and never closed is malformed, and so is a file that is only `---`.
+ *
+ * The content is cut at its line feeds once and each piece is visited once, so the running time is linear in the
+ * length of the content, and the loop is bounded by the number of pieces.
+ */
+export declare function splitFrontmatterBlock(content: string): FrontmatterBlockSplit;

package/dist/frontmatter-block.js

@@ -0,0 +1,62 @@
+/**
+ * Finds the YAML frontmatter block at the start of `content`. It does not parse the YAML.
+ *
+ * The block rule:
+ * - The content starts with a line that is exactly `---`. A space, a byte-order mark, a blank line or any other
+ *   character before it or after it, on that line, means there is no block.
+ * - A line ending is LF or CRLF. A lone CR is part of its line.
+ * - The block ends at the first later line that is `---` followed only by spaces or tabs. A line such as `---x`,
+ *   `----` or `--- text` is part of the block.
+ * - A block can be empty: `---` directly followed by `---` gives empty text.
+ * - A block that is opened and never closed is malformed, and so is a file that is only `---`.
+ *
+ * The content is cut at its line feeds once and each piece is visited once, so the running time is linear in the
+ * length of the content, and the loop is bounded by the number of pieces.
+ */
+export function splitFrontmatterBlock(content) {
+    const pieces = content.split('\n');
+    const lastIndex = pieces.length - 1;
+    // `offset` is where the piece being read starts. `openingLength` is the length of the opening line with its line
+    // feed, and `textEnd` is where the lines before the piece end, before their line ending.
+    let offset = 0;
+    let openingLength = 0;
+    let textEnd = 0;
+    for (const [index, piece] of pieces.entries()) {
+        // A piece that ends with a carriage return has a CRLF ending when a line feed followed it, that is, unless it is
+        // the last piece.
+        const line = index < lastIndex && piece.endsWith('\r') ? piece.slice(0, -1) : piece;
+        if (index === 0) {
+            if (line !== '---')
+                return { kind: 'none' };
+            openingLength = piece.length + 1;
+            textEnd = openingLength;
+        }
+        else if (isCloseLine(line)) {
+            const lineEnd = offset + piece.length + 1;
+            return {
+                kind: 'block',
+                opening: content.slice(0, openingLength),
+                text: content.slice(openingLength, textEnd),
+                textEnding: content.slice(textEnd, offset),
+                closing: content.slice(offset, lineEnd),
+                body: content.slice(lineEnd),
+            };
+        }
+        else {
+            textEnd = offset + line.length;
+        }
+        offset += piece.length + 1;
+    }
+    return { kind: 'malformed' };
+}
+/** Whether `line` is `---` followed only by spaces and tabs. */
+function isCloseLine(line) {
+    if (!line.startsWith('---'))
+        return false;
+    for (let at = 3; at < line.length; at += 1) {
+        const character = line.charAt(at);
+        if (character !== ' ' && character !== '\t')
+            return false;
+    }
+    return true;
+}

package/dist/frontmatter.d.ts

@@ -1,8 +1,12 @@
+export { splitFrontmatterBlock, type FrontmatterBlockSplit } from './frontmatter-block.js';
 export interface FrontmatterDocument {
     readonly values: Record<string, unknown>;
     readonly body: string;
 }
-/** Parse a validated wiki document while retaining its raw body. */
+/**
+ * Parse a validated wiki document while retaining its raw body. A document with no block, or with a block that is
+ * never closed, is missing its frontmatter. A block with no lines is an empty mapping; any other block must parse to one.
+ */
 export declare function parseFrontmatterDocument(content: string): FrontmatterDocument;
 /** Reconstruct a wiki document with system-owned frontmatter and normalized body. */
 export declare function renderFrontmatterDocument(values: Record<string, unknown>, body: string): string;

package/dist/frontmatter.js

@@ -1,14 +1,20 @@
 import { parse, stringify } from 'yaml';
-/** Parse a validated wiki document while retaining its raw body. */
+import { splitFrontmatterBlock } from "./frontmatter-block.js";
+export { splitFrontmatterBlock } from "./frontmatter-block.js";
+/**
+ * Parse a validated wiki document while retaining its raw body. A document with no block, or with a block that is
+ * never closed, is missing its frontmatter. A block with no lines is an empty mapping; any other block must parse to one.
+ */
 export function parseFrontmatterDocument(content) {
-    const match = /^---\n([\s\S]+?)\n---\n?/u.exec(content);
-    if (match === null || match[1] === undefined) {
+    const split = splitFrontmatterBlock(content);
+    if (split.kind !== 'block') {
         throw new Error('validated wiki page is missing frontmatter');
     }
-    const parsed = parse(match[1]);
+    // Only a block with no lines is an empty mapping. A block of one blank line parses to null, like any blank text.
+    const parsed = split.text === '' && split.textEnding === '' ? {} : parse(split.text);
     if (!isRecord(parsed))
         throw new Error('validated wiki page frontmatter is not an object');
-    return { values: parsed, body: content.slice(match[0].length) };
+    return { values: parsed, body: split.body };
 }
 /** Reconstruct a wiki document with system-owned frontmatter and normalized body. */
 export function renderFrontmatterDocument(values, body) {

package/dist/gate-contract.js

@@ -1,4 +1,4 @@
 // Bump deliberately when an intentional consumer-visible gate contract break ships.
 export const GATE_CONTRACT_VERSION = 1;
 // Replaced with the deterministic source-tree hash by the package build.
-export const GATE_SOURCE_TREE_HASH = '4c87f6366faeed604a910d0da221bd2d4a9661e9b83ec230c9345829bc0406f2';
+export const GATE_SOURCE_TREE_HASH = '637b237dc25880625d73dde771514ff4ff64fd845cb6dd1a07c61184570de419';

package/dist/gate-contract.json

@@ -1 +1 @@
-{"version":1,"sourceTreeHash":"4c87f6366faeed604a910d0da221bd2d4a9661e9b83ec230c9345829bc0406f2"}
+{"version":1,"sourceTreeHash":"637b237dc25880625d73dde771514ff4ff64fd845cb6dd1a07c61184570de419"}

package/dist/inline-links.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The inline-link scanner behind `resolveMarkdownLinks`. It is an internal module: the package does not
+ * export it, so the only way to reach it is through `markdown-links`.
+ */
+export interface InlineLink {
+    /** Offset of the opening `[` in the line. */
+    readonly index: number;
+    /** Length of the whole `[text](destination "title")` span. */
+    readonly length: number;
+    /** The destination as written: `<angle>` with its brackets, or the bare run. */
+    readonly target: string;
+}
+/** The characters `\s` matches: ASCII spaces and controls, then the Unicode space separators. */
+export declare function isWhitespaceCode(code: number): boolean;
+/** For every offset `i` up to the line length plus one: the first offset at or after `i` whose character stops a run, or the line length. */
+export declare function buildStopTable(line: string, stops: (code: number) => boolean): Int32Array;
+/**
+ * Builds a function that finds the inline links of one line, `[text](destination "title")`, left to right.
+ * `find(from)` returns the leftmost link that starts at or after `from`, or `undefined`.
+ *
+ * The grammar, over the characters of the line:
+ * - `[`, a non-empty text with no `]` or newline, then `](`;
+ * - optional whitespace, then the destination: `<` with a non-empty run of no `>` or newline and `>`, or else
+ *   a non-empty run of no `)` or whitespace; the angle form is tried first and the bare run is the fallback
+ *   when the angle form is not followed by a valid ending;
+ * - an optional title, set off by whitespace, in double quotes, in single quotes or in parentheses, each with
+ *   no newline inside and no closing delimiter before its end;
+ * - optional whitespace, then `)`. A title that is present but does not lead to `)` is dropped, and the
+ *   destination alone must then be followed by whitespace and `)`.
+ *
+ * Every run in the grammar ends at the first character that cannot continue it, so a run is read once from
+ * a table of stop offsets built right to left, and every start offset is decided in constant time. The
+ * tables are built on first use and only for a line that holds `](`.
+ */
+export declare function createInlineLinkFinder(line: string): (from: number) => InlineLink | undefined;

package/dist/inline-links.js

@@ -0,0 +1,120 @@
+/**
+ * The inline-link scanner behind `resolveMarkdownLinks`. It is an internal module: the package does not
+ * export it, so the only way to reach it is through `markdown-links`.
+ */
+/** The character codes the grammar tests for. */
+const CLOSE_BRACKET = 0x5d;
+const OPEN_PAREN = 0x28;
+const CLOSE_PAREN = 0x29;
+const LESS_THAN = 0x3c;
+const GREATER_THAN = 0x3e;
+const DOUBLE_QUOTE = 0x22;
+const SINGLE_QUOTE = 0x27;
+const NEWLINE = 0x0a;
+/** The characters `\s` matches: ASCII spaces and controls, then the Unicode space separators. */
+export function isWhitespaceCode(code) {
+    if (code <= 0x20)
+        return code === 0x20 || (code >= 0x09 && code <= 0x0d);
+    if (code < 0xa0)
+        return false;
+    return (code === 0xa0 ||
+        code === 0x1680 ||
+        (code >= 0x2000 && code <= 0x200a) ||
+        code === 0x2028 ||
+        code === 0x2029 ||
+        code === 0x202f ||
+        code === 0x205f ||
+        code === 0x3000 ||
+        code === 0xfeff);
+}
+/** For every offset `i` up to the line length plus one: the first offset at or after `i` whose character stops a run, or the line length. */
+export function buildStopTable(line, stops) {
+    const table = new Int32Array(line.length + 2).fill(line.length);
+    for (let index = line.length - 1; index >= 0; index -= 1) {
+        table[index] = stops(line.charCodeAt(index)) ? index : (table[index + 1] ?? line.length);
+    }
+    return table;
+}
+/**
+ * Builds a function that finds the inline links of one line, `[text](destination "title")`, left to right.
+ * `find(from)` returns the leftmost link that starts at or after `from`, or `undefined`.
+ *
+ * The grammar, over the characters of the line:
+ * - `[`, a non-empty text with no `]` or newline, then `](`;
+ * - optional whitespace, then the destination: `<` with a non-empty run of no `>` or newline and `>`, or else
+ *   a non-empty run of no `)` or whitespace; the angle form is tried first and the bare run is the fallback
+ *   when the angle form is not followed by a valid ending;
+ * - an optional title, set off by whitespace, in double quotes, in single quotes or in parentheses, each with
+ *   no newline inside and no closing delimiter before its end;
+ * - optional whitespace, then `)`. A title that is present but does not lead to `)` is dropped, and the
+ *   destination alone must then be followed by whitespace and `)`.
+ *
+ * Every run in the grammar ends at the first character that cannot continue it, so a run is read once from
+ * a table of stop offsets built right to left, and every start offset is decided in constant time. The
+ * tables are built on first use and only for a line that holds `](`.
+ */
+export function createInlineLinkFinder(line) {
+    if (!line.includes(']('))
+        return () => undefined;
+    const tables = new Map();
+    const stopTable = (name, stops) => {
+        let table = tables.get(name);
+        if (table === undefined) {
+            table = buildStopTable(line, stops);
+            tables.set(name, table);
+        }
+        return table;
+    };
+    const stopAt = (name, from, stops) => stopTable(name, stops)[from] ?? line.length;
+    /** Offset of the `)` that ends a link whose destination ends at `destinationEnd`, plus one; -1 when there is none. */
+    const endOfLink = (destinationEnd) => {
+        const afterSpace = stopAt('nonSpace', destinationEnd, code => !isWhitespaceCode(code));
+        if (afterSpace > destinationEnd) {
+            const opener = line.charCodeAt(afterSpace);
+            const closer = opener === OPEN_PAREN ? CLOSE_PAREN : opener;
+            if (opener === DOUBLE_QUOTE || opener === SINGLE_QUOTE || opener === OPEN_PAREN) {
+                const stop = stopAt(`title${closer}`, afterSpace + 1, code => code === closer || code === NEWLINE);
+                if (line.charCodeAt(stop) === closer) {
+                    const closeAt = stopAt('nonSpace', stop + 1, code => !isWhitespaceCode(code));
+                    if (line.charCodeAt(closeAt) === CLOSE_PAREN)
+                        return closeAt + 1;
+                }
+            }
+        }
+        return line.charCodeAt(afterSpace) === CLOSE_PAREN ? afterSpace + 1 : -1;
+    };
+    const linkAt = (start) => {
+        const textEnd = stopAt('text', start + 1, code => code === CLOSE_BRACKET || code === NEWLINE);
+        if (textEnd === start + 1 ||
+            line.charCodeAt(textEnd) !== CLOSE_BRACKET ||
+            line.charCodeAt(textEnd + 1) !== OPEN_PAREN) {
+            return undefined;
+        }
+        const destinationStart = stopAt('nonSpace', textEnd + 2, code => !isWhitespaceCode(code));
+        if (line.charCodeAt(destinationStart) === LESS_THAN) {
+            const angleClose = stopAt('angle', destinationStart + 1, code => code === GREATER_THAN || code === NEWLINE);
+            if (angleClose > destinationStart + 1 && line.charCodeAt(angleClose) === GREATER_THAN) {
+                const end = endOfLink(angleClose + 1);
+                if (end !== -1) {
+                    return { index: start, length: end - start, target: line.slice(destinationStart, angleClose + 1) };
+                }
+            }
+        }
+        const bareEnd = stopAt('bare', destinationStart, code => code === CLOSE_PAREN || isWhitespaceCode(code));
+        if (bareEnd > destinationStart) {
+            const end = endOfLink(bareEnd);
+            if (end !== -1) {
+                return { index: start, length: end - start, target: line.slice(destinationStart, bareEnd) };
+            }
+        }
+        return undefined;
+    };
+    return from => {
+        for (let start = line.indexOf('[', from); start !== -1; start = line.indexOf('[', start + 1)) {
+            const link = linkAt(start);
+            if (link !== undefined)
+                return link;
+        }
+        return undefined;
+    };
+}