@fro.bot/wiki-write-core 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+# The MIT License (MIT)
+
+Copyright (c) 2023 Marcus R. Brown <<git@mrbro.dev>>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# `@fro.bot/wiki-write-core`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared validation and commit primitives for Fro Bot wiki writes: snapshot lint, wiki ingest, privacy-core seams, frontmatter helpers, and rendering-policy validation.
+
+## Install
+
+```bash
+pnpm add @fro.bot/wiki-write-core
+# or: npm install @fro.bot/wiki-write-core
+# or: bun add @fro.bot/wiki-write-core
+```
+
+## Runtime requirements
+
+- 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/`.
+
+## Fro Bot defaults
+
+The package targets the Fro Bot control plane and carries its coordinates as defaults. Each is overridable through the call's parameters.
+
+- `owner` defaults to `fro-bot` (`DEFAULT_OWNER`), and `repo` to `.github`.
+- The canonical write target is the `fro-bot/.github@data` tuple: `branch` defaults to `data`.
+- Tracked-repository metadata is read from `metadata/repos.yaml`.
+
+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 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.
+
+`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.
+
+`gate-contract.json` is intentionally not exposed through the package `exports` map. Consumers must fetch the control plane's current marker through the contents API while loading their pinned package copy locally; resolving the bundled marker would defeat that comparison.
+
+## Finding kinds
+
+`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.
+
+## 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.
+
+Only commits that touch `packages/wiki-write-core/` are analyzed. The commit type decides the release:
+
+| Commit                                                                                          | Release |
+| ----------------------------------------------------------------------------------------------- | ------- |
+| Breaking change (`!` or a `BREAKING CHANGE:` footer)                                            | minor   |
+| `feat`                                                                                          | minor   |
+| `fix`, `build`, `docs(readme)`                                                                  | patch   |
+| `build(dev)`, other `docs`, `chore`, `ci`, `test`, `refactor`, `skip`, non-conventional commits | none    |
+
+- 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.
+
+### 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.
+
+Verify a release:
+
+- `npm view @fro.bot/wiki-write-core dist-tags.latest` returns the released version.
+- `npm view @fro.bot/wiki-write-core@<version> --json` lists the provenance attestation under `dist.attestations`.
+- The version page on npmjs.com shows the provenance badge, linking to `fro-bot/.github` and `release-wiki-write-core.yaml`.
+
+### Failure recovery
+
+Start from the registry and tag state, not from the run's conclusion: a green run can release nothing.
+
+| State | Recovery |
+| --- | --- |
+| No tag, no npm version | Fix the cause, then run the workflow with `workflow_dispatch` on `main` |
+| Green run, package commits since the last tag, no release (`main` moved past the checkout, or the push run was skipped by `[skip ci]`) | `workflow_dispatch` on `main` |
+| Tag present, version neither live nor staged on npm | Delete the tag and its GitHub release if one exists, then `workflow_dispatch` on `main`. Do this before merging any other package change |
+| Tag and GitHub release present, npm skipped the publish (for example `private` in the manifest) | Fix the manifest, delete the tag and GitHub release, then `workflow_dispatch` on `main` |
+| Version staged on npm instead of live | Promote it on npm, then set the trusted publisher to allow `npm publish` |
+| OIDC publish fails (expired, misconfigured or stage-only trusted publisher) | Delete and recreate the trusted publisher: owner `fro-bot`, repo `.github`, workflow `release-wiki-write-core.yaml`, environment `release`, allowed action `npm publish`. Then resolve the tag as in the third row |
+| Tag and version live, no GitHub release | Create the GitHub release from the tag. Never delete the tag |
+| Bad version published | Deprecate it and ship a fix release. Never delete the tag |

package/dist/branch-safety.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The one branch-safety rule shared by every writer that commits to `fro-bot/.github`.
+ *
+ * - Never `main`: writers target `data`, and `main` only receives it through a promotion PR.
+ * - Never a protected branch, except the canonical `fro-bot/.github@data`: its ruleset reports it as
+ *   protected while bypassing the App by actor, so the App writer is the one intended to write there.
+ *
+ * Each writer reports a refusal in its own error type, so this function takes a `refuse` callback
+ * instead of throwing: the rule lives here once, and the error shape stays with the caller.
+ */
+/** Why a branch was refused. */
+export type BranchRefusal = 'main' | 'protected';
+/** The one call the rule needs. The real Octokit satisfies it structurally. */
+export interface BranchProtectionClient {
+    rest: {
+        repos: {
+            getBranch: (params: {
+                owner: string;
+                repo: string;
+                branch: string;
+            }) => Promise<{
+                data: {
+                    protected?: boolean;
+                    protection?: {
+                        enabled?: boolean;
+                    } | null;
+                };
+            }>;
+        };
+    };
+}
+/**
+ * Resolve if `owner/repo@branch` may be written, otherwise call `refuse` (which must throw).
+ *
+ * `main` is refused without a network call. Otherwise GitHub is asked, and both the top-level
+ * `protected` flag and the nested `protection.enabled` are checked: the REST API surfaces branch
+ * protection through both, and older clients that read only the latter miss repos configured
+ * through rulesets.
+ */
+export declare function assertBranchWritable(client: BranchProtectionClient, owner: string, repo: string, branch: string, refuse: (reason: BranchRefusal) => never): Promise<void>;

package/dist/branch-safety.js

@@ -0,0 +1,31 @@
+/**
+ * The one branch-safety rule shared by every writer that commits to `fro-bot/.github`.
+ *
+ * - Never `main`: writers target `data`, and `main` only receives it through a promotion PR.
+ * - Never a protected branch, except the canonical `fro-bot/.github@data`: its ruleset reports it as
+ *   protected while bypassing the App by actor, so the App writer is the one intended to write there.
+ *
+ * Each writer reports a refusal in its own error type, so this function takes a `refuse` callback
+ * instead of throwing: the rule lives here once, and the error shape stays with the caller.
+ */
+const CANONICAL_OWNER = 'fro-bot';
+const CANONICAL_REPO = '.github';
+const CANONICAL_BRANCH = 'data';
+const MAIN_BRANCH = 'main';
+/**
+ * Resolve if `owner/repo@branch` may be written, otherwise call `refuse` (which must throw).
+ *
+ * `main` is refused without a network call. Otherwise GitHub is asked, and both the top-level
+ * `protected` flag and the nested `protection.enabled` are checked: the REST API surfaces branch
+ * protection through both, and older clients that read only the latter miss repos configured
+ * through rulesets.
+ */
+export async function assertBranchWritable(client, owner, repo, branch, refuse) {
+    if (branch === MAIN_BRANCH)
+        return refuse('main');
+    const response = await client.rest.repos.getBranch({ owner, repo, branch });
+    const isProtected = response.data.protected === true || response.data.protection?.enabled === true;
+    const isCanonical = owner === CANONICAL_OWNER && repo === CANONICAL_REPO && branch === CANONICAL_BRANCH;
+    if (isProtected && !isCanonical)
+        return refuse('protected');
+}

package/dist/code-regions.d.ts

@@ -0,0 +1,24 @@
+/** A half-open `[start, end)` range of offsets in a string that holds literal code, not markdown. */
+export interface CodeRegion {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Locate fenced code blocks and inline code spans in markdown, as sorted, non-overlapping regions.
+ * Link extractors use it so link-shaped text inside code stays literal.
+ *
+ * - A fence opens at a line with up to three spaces of indentation, then three or more backticks
+ *   or tildes. A backtick fence's info string may not contain a backtick; a line that breaks that
+ *   rule is not a fence and is parsed for inline spans instead. A tilde fence's info string may
+ *   contain anything.
+ * - A fence closes at a line of the same character, at least as long as the opener and followed
+ *   only by spaces or tabs. An unclosed fence runs to the end of the content. The fence lines
+ *   themselves are part of the region.
+ * - Outside a fence, a run of N backticks opens an inline span that closes at the next run of
+ *   exactly N backticks on the same line (CommonMark, minus spans that cross a line break). A run
+ *   with no matching closer is literal text. A backslash outside a span escapes the next
+ *   character, so an escaped backtick never opens a span.
+ */
+export declare function findCodeRegions(content: string): CodeRegion[];
+/** The region that contains `offset`, if any. `regions` must come from {@link findCodeRegions}. */
+export declare function findRegionAt(regions: readonly CodeRegion[], offset: number): CodeRegion | undefined;

package/dist/code-regions.js

@@ -0,0 +1,134 @@
+// Up to three spaces of indentation, then a run of three or more backticks or tildes and an info string.
+const FENCE_OPENER = /^ {0,3}(`{3,}|~{3,})/u;
+// A closing fence carries nothing but spaces or tabs after the marker.
+const FENCE_CLOSER = /^ {0,3}(`{3,}|~{3,})[ \t]*$/u;
+/**
+ * Locate fenced code blocks and inline code spans in markdown, as sorted, non-overlapping regions.
+ * Link extractors use it so link-shaped text inside code stays literal.
+ *
+ * - A fence opens at a line with up to three spaces of indentation, then three or more backticks
+ *   or tildes. A backtick fence's info string may not contain a backtick; a line that breaks that
+ *   rule is not a fence and is parsed for inline spans instead. A tilde fence's info string may
+ *   contain anything.
+ * - A fence closes at a line of the same character, at least as long as the opener and followed
+ *   only by spaces or tabs. An unclosed fence runs to the end of the content. The fence lines
+ *   themselves are part of the region.
+ * - Outside a fence, a run of N backticks opens an inline span that closes at the next run of
+ *   exactly N backticks on the same line (CommonMark, minus spans that cross a line break). A run
+ *   with no matching closer is literal text. A backslash outside a span escapes the next
+ *   character, so an escaped backtick never opens a span.
+ */
+export function findCodeRegions(content) {
+    const regions = [];
+    let fence;
+    let lineStart = 0;
+    while (lineStart <= content.length) {
+        const newline = content.indexOf('\n', lineStart);
+        const lineEnd = newline === -1 ? content.length : newline;
+        const line = content.slice(lineStart, lineEnd);
+        // A CRLF line ending is a line ending, not part of the line.
+        const text = line.endsWith('\r') ? line.slice(0, -1) : line;
+        if (fence === undefined) {
+            const opener = parseFenceOpener(text);
+            if (opener === undefined) {
+                for (const span of findInlineSpans(line)) {
+                    regions.push({ start: lineStart + span.start, end: lineStart + span.end });
+                }
+            }
+            else {
+                fence = { ...opener, start: lineStart };
+            }
+        }
+        else if (closesFence(text, fence)) {
+            regions.push({ start: fence.start, end: lineEnd });
+            fence = undefined;
+        }
+        lineStart = lineEnd + 1;
+    }
+    if (fence !== undefined) {
+        regions.push({ start: fence.start, end: content.length });
+    }
+    return regions;
+}
+function parseFenceOpener(text) {
+    const match = FENCE_OPENER.exec(text);
+    const marker = match?.[1];
+    if (match === null || marker === undefined) {
+        return undefined;
+    }
+    const character = marker.charAt(0);
+    const info = text.slice(match[0].length);
+    return character === '`' && info.includes('`') ? undefined : { character, length: marker.length };
+}
+function closesFence(text, fence) {
+    const marker = FENCE_CLOSER.exec(text)?.[1];
+    return marker !== undefined && marker.startsWith(fence.character) && marker.length >= fence.length;
+}
+/** The region that contains `offset`, if any. `regions` must come from {@link findCodeRegions}. */
+export function findRegionAt(regions, offset) {
+    let low = 0;
+    let high = regions.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const region = regions[middle];
+        if (region === undefined) {
+            return undefined;
+        }
+        if (offset < region.start) {
+            high = middle - 1;
+        }
+        else if (offset >= region.end) {
+            low = middle + 1;
+        }
+        else {
+            return region;
+        }
+    }
+    return undefined;
+}
+function findInlineSpans(line) {
+    const spans = [];
+    let index = 0;
+    while (index < line.length) {
+        const character = line[index];
+        if (character === '\\') {
+            index += 2;
+            continue;
+        }
+        if (character !== '`') {
+            index += 1;
+            continue;
+        }
+        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) {
+            index = openEnd;
+        }
+        else {
+            spans.push({ start: index, end: closeEnd });
+            index = closeEnd;
+        }
+    }
+    return spans;
+}
+function skipBackticks(line, from) {
+    let index = from;
+    while (line[index] === '`') {
+        index += 1;
+    }
+    return index;
+}

package/dist/correction-text.d.ts

@@ -0,0 +1,2 @@
+/** Normalize the exact survival text used by both storage validation and ingest checks. */
+export declare function normalizeCorrectionText(value: string): string;

package/dist/correction-text.js

@@ -0,0 +1,4 @@
+/** Normalize the exact survival text used by both storage validation and ingest checks. */
+export function normalizeCorrectionText(value) {
+    return value.trim().replaceAll(/\s+/gu, ' ');
+}

package/dist/corrections-survival.d.ts

@@ -0,0 +1,35 @@
+import { type CorrectionsFile, type CorrectionSurvivalResult } from './corrections.js';
+/**
+ * Verify marked spans mechanically after ingest regeneration.
+ *
+ * Matching trims the span and collapses every whitespace run to one space, then
+ * performs an exact substring search in prose only. Markdown inline links are
+ * excluded from that exact search; wiki links remain in it because their target
+ * text is page prose for this purpose. Fenced code, indented code, and blockquotes
+ * are excluded because quoted material is not evidence that the correction survived
+ * in the page's actual prose.
+ *
+ * If exact prose matching fails, a second conservative comparison replaces
+ * Markdown links with their visible text, removes Markdown emphasis/code markers,
+ * converts punctuation to whitespace, collapses whitespace, and lowercases text.
+ * A match under that rule is formatting-only drift and emits an advisory
+ * `correction-needs-reconfirmation`; any other miss is erosion and blocks ingest.
+ */
+export declare function verifyCorrectionSurvival(files: Record<string, string>, corrections: CorrectionsFile | undefined, fallbackFiles?: Record<string, string>): CorrectionSurvivalResult;
+/**
+ * Substitutes each link's visible label (markdown or wiki, labeled or bare) before the generic
+ * punctuation strip below. A single combined alternation, scanned once left to right: a
+ * two-pass split (markdown pattern, then wiki pattern) lets the first pass's substitution text
+ * form a NEW `[[...|...]]`-shaped string the second pass then matches, re-interpreting already-
+ * substituted output as if it were original content (see corrections-survival.test.ts's
+ * `[[[]()a|b]]` counterexample). Exported only for the exhaustive differential test against
+ * the pre-refactor reference implementation.
+ */
+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.
+ */
+export declare function maskMarkdownLinks(content: string): string;

package/dist/corrections-survival.js

@@ -0,0 +1,160 @@
+import { normalizeCorrectionText } from "./correction-text.js";
+import { assertCorrectionsFile, getCorrectionLifecycle, } from "./corrections.js";
+import { maskNonProseContent } from "./rendering-policy.js";
+import { collectWikiPages } from "./wiki-utils.js";
+/**
+ * Verify marked spans mechanically after ingest regeneration.
+ *
+ * Matching trims the span and collapses every whitespace run to one space, then
+ * performs an exact substring search in prose only. Markdown inline links are
+ * excluded from that exact search; wiki links remain in it because their target
+ * text is page prose for this purpose. Fenced code, indented code, and blockquotes
+ * are excluded because quoted material is not evidence that the correction survived
+ * in the page's actual prose.
+ *
+ * If exact prose matching fails, a second conservative comparison replaces
+ * Markdown links with their visible text, removes Markdown emphasis/code markers,
+ * converts punctuation to whitespace, collapses whitespace, and lowercases text.
+ * A match under that rule is formatting-only drift and emits an advisory
+ * `correction-needs-reconfirmation`; any other miss is erosion and blocks ingest.
+ */
+export function verifyCorrectionSurvival(files, corrections, fallbackFiles = {}) {
+    if (corrections === undefined)
+        return { ok: true, deterministicFindings: [], advisoryFindings: [] };
+    assertCorrectionsFile(corrections);
+    const pages = collectWikiPages(files);
+    const fallbackPages = collectWikiPages(fallbackFiles);
+    // Keyed by `unknown`: correction.page_node_id is a validated non-empty string
+    // (corrections.ts parseLooseCorrectionRecord), so unkeyable pages are never looked up.
+    const pagesByNodeId = new Map();
+    const fallbackPagesByNodeId = new Map();
+    for (const page of pages)
+        pagesByNodeId.set(page.frontmatter.node_id, page);
+    for (const page of fallbackPages)
+        fallbackPagesByNodeId.set(page.frontmatter.node_id, page);
+    const deterministicFindings = [];
+    const advisoryFindings = [];
+    for (const correction of corrections.corrections) {
+        const state = getCorrectionLifecycle(correction);
+        if (state === 'superseded' || state === 'retired')
+            continue;
+        const page = pagesByNodeId.get(correction.page_node_id);
+        const fallbackPage = fallbackPagesByNodeId.get(correction.page_node_id);
+        const path = page?.path ?? fallbackPage?.path ?? 'knowledge/corrections.yaml';
+        if (state === 'needs-reconfirmation') {
+            advisoryFindings.push({
+                kind: 'correction-needs-reconfirmation',
+                path,
+                target: correction.id,
+                recovery: { lifecycle: 'needs-reconfirmation', action: 'reconfirm-correction' },
+                message: `Correction ${correction.id} needs operator reconfirmation before it is enforced.`,
+            });
+            continue;
+        }
+        // normalizedSpan is never '' (assertCorrectionSpan, corrections.ts:185); page === undefined
+        // forces proseBody '', and '' can never include a non-empty span, so that disjunct is dead.
+        const normalizedSpan = normalizeCorrectionText(correction.span.text);
+        const proseBody = page === undefined ? '' : maskNonProseContent(page.body);
+        const normalizedBody = normalizeCorrectionText(maskMarkdownLinks(proseBody));
+        if (!normalizedBody.includes(normalizedSpan)) {
+            const formattingSpan = normalizeFormattingText(correction.span.text);
+            const formattingBody = normalizeFormattingText(proseBody);
+            if (formattingSpan !== '' && formattingBody.includes(formattingSpan)) {
+                advisoryFindings.push({
+                    kind: 'correction-needs-reconfirmation',
+                    path,
+                    target: correction.id,
+                    recovery: { lifecycle: 'needs-reconfirmation', action: 'reconfirm-correction' },
+                    message: `Correction ${correction.id} appears preserved with formatting-only changes and needs operator reconfirmation.`,
+                });
+                continue;
+            }
+            deterministicFindings.push({
+                kind: 'correction-eroded',
+                path,
+                target: correction.id,
+                recovery: { lifecycle: 'active', action: 'restore-span' },
+                message: `Active correction ${correction.id} was not found in the regenerated page.`,
+            });
+        }
+    }
+    return {
+        ok: deterministicFindings.length === 0,
+        deterministicFindings,
+        advisoryFindings,
+    };
+}
+/**
+ * Substitutes each link's visible label (markdown or wiki, labeled or bare) before the generic
+ * punctuation strip below. A single combined alternation, scanned once left to right: a
+ * two-pass split (markdown pattern, then wiki pattern) lets the first pass's substitution text
+ * form a NEW `[[...|...]]`-shaped string the second pass then matches, re-interpreting already-
+ * substituted output as if it were original content (see corrections-survival.test.ts's
+ * `[[[]()a|b]]` counterexample). Exported only for the exhaustive differential test against
+ * the pre-refactor reference implementation.
+ */
+export function normalizeFormattingText(value) {
+    const markdownLinkPattern = /!?(?:\[([^\]]*)\]\([^)]*\)|\[\[([^\]|]+)(?:\|([^\]]+))?\]\])/gu;
+    return (value
+        .normalize('NFKC')
+        .replaceAll(markdownLinkPattern, 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.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see comment above
+    return (markdownText ?? wikiLabel ?? wikiTarget);
+}
+/**
+ * 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.
+ */
+export function maskMarkdownLinks(content) {
+    const masked = content.split('');
+    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] === '[')
+            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;
+                open = -1;
+                continue;
+            }
+        }
+        // Stryker disable next-line AssignmentOperator: mutation destroys mandatory loop progress; deterministic hang, not a timing artifact
+        index += 1;
+    }
+    return masked.join('');
+}