@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/wiki/document-urls.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Resolve a wiki page's own references to the wiki pages and assets they name.
+ *
+ * A wiki page is not a chat message: `[v1.6.0](change_logs/v1.6.0)` means that
+ * page of the wiki, and `![](images/schema.png)` means the image in the wiki's
+ * own repository — not in the project's. Neither resolves on its own: the panel
+ * is an app route, so a relative URL would be requested from the server's own
+ * origin (`/images/schema.png` → 404), and a wiki's images are not on the
+ * project host at all.
+ *
+ * So each reference is rewritten to the endpoint that can serve it — through
+ * `/api/wiki/asset`, which reads the blob out of the wiki's tree — and a LINK to
+ * a page additionally carries the resolved wiki path in `data-wiki-path`, which
+ * is what the panel turns back into in-panel navigation. A reference that is not
+ * in the wiki's tree is left exactly as written, and the renderer's click
+ * handler classifies it from the raw `href` — so a relative path that named no
+ * page of this wiki stays inert instead of being mistaken for an external URL
+ * (which is what opened a browser tab for every one of them).
+ *
+ * Only plain relative references are touched. Anything with a scheme
+ * (`https:`, `mailto:`, `data:`), a protocol-relative `//host`, or a bare
+ * `#anchor` is the page's own business.
+ */
+
+import { isWikiMarkdownPath, resolveWikiReference, wikiEntryLookup, wikiHeadingSlug } from '@/shared/lib/wiki/pages';
+import type { WikiEntry } from '@/shared/types/wiki';
+
+export interface WikiRenderScope {
+  /** Path of the page being rendered, inside the wiki tree. */
+  path: string;
+  /** Every path in the wiki, for reference resolution. */
+  entries: readonly WikiEntry[];
+  /** Workspace scope, so an asset URL names the same wiki the page came from. */
+  root?: string;
+  repo?: string;
+}
+
+/** URL of one file's bytes through `/api/wiki/asset`, carrying the same scope. */
+export function buildWikiAssetUrl(assetPath: string, scope: { root?: string; repo?: string } = {}): string {
+  const params = new URLSearchParams({ path: assetPath });
+  if (scope.root) params.set('root', scope.root);
+  if (scope.repo && scope.repo !== '.') params.set('repo', scope.repo);
+  return `/api/wiki/asset?${params.toString()}`;
+}
+
+/** Attribute values are injected as HTML, so `&` and `"` must be entities. */
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, '&').replace(/"/g, '"');
+}
+
+/** The heading's own text, with inline markup and entities flattened. */
+function headingText(inner: string): string {
+  return inner
+    .replace(/<[^>]*>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+const HEADING_RE = /<h([1-6])([^>]*)>([\s\S]*?)<\/h\1>/g;
+const ID_ATTR_RE = /\sid="[^"]*"/;
+
+/**
+ * Give every heading the id the page's own `#anchor` links name.
+ *
+ * See {@link wikiHeadingSlug} for why the renderer's own id is not usable: the
+ * emoji in `## 🎯 Overview` survives into it, while the TOC the author wrote
+ * says `#overview`.
+ */
+function rewriteHeadingIds(html: string): string {
+  return html.replace(HEADING_RE, (match, level: string, attrs: string, inner: string) => {
+    const slug = wikiHeadingSlug(headingText(inner));
+    if (!slug) return match;
+    const id = ` id="${escapeAttribute(slug)}"`;
+    return `<h${level}${ID_ATTR_RE.test(attrs) ? attrs.replace(ID_ATTR_RE, id) : `${attrs}${id}`}>${inner}</h${level}>`;
+  });
+}
+
+/**
+ * Rewrite the relative `src`/`href` attributes of rendered wiki HTML, and give
+ * its headings the ids its own anchors point at.
+ *
+ * Fenced code is already escaped by the renderer, so a literal `src="` inside a
+ * code block cannot be mistaken for an attribute, and a `#` comment inside a
+ * fence is inside `<pre>`, never a heading.
+ */
+export function rewriteWikiReferences(html: string, scope: WikiRenderScope): string {
+  const lookup = wikiEntryLookup(scope.entries);
+  const rewritten = html.replace(/(\s(?:src|href))="([^"]*)"/g, (match, attribute: string, value: string) => {
+    const resolved = resolveWikiReference(value, scope.path, lookup);
+    if (!resolved) return match;
+    const isLink = attribute.trim() === 'href';
+    const url = ` ${isLink ? 'href' : 'src'}="${escapeAttribute(buildWikiAssetUrl(resolved, scope))}"`;
+    // Only a page gets the navigation marker: a link to any other file in the
+    // wiki keeps its asset URL (copyable, middle-clickable) and stays inert on
+    // a plain click, because the panel is a reader, not a file browser.
+    return isLink && isWikiMarkdownPath(resolved)
+      ? `${url} data-wiki-path="${escapeAttribute(resolved)}"`
+      : url;
+  });
+  return rewriteHeadingIds(rewritten);
+}

package/src/shared/lib/wiki/pages.test.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wiki's page list and its reference resolution.
+ *
+ * The cases pinned here are the ones a real wiki produced and a naive
+ * implementation got wrong: gollum's `[[Embed Diagrams]]` naming a file called
+ * `Embed-Diagrams.md`, GitLab's `[v1.6.0](change_logs/v1.6.0)` omitting the
+ * extension, both hosts' chrome fragments (`_Sidebar`) landing in the nav, and
+ * GitLab's `.gitlab/redirects.yml` being provider metadata rather than a page.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  buildWikiEntries,
+  expandGollumLinks,
+  resolveWikiReference,
+  wikiEntryLookup,
+  wikiHeadingSlug,
+} from '@/shared/lib/wiki/pages';
+import {
+  findWikiSidebarPath,
+  parseWikiSidebar,
+  sectionsFromEntries,
+  withRemainingPages,
+} from '@/shared/lib/wiki/sidebar';
+
+const DRAWIO_TREE = [
+  'Home.md',
+  'deploying.md',
+  'Embed-Diagrams.md',
+  'Getting-Support.md',
+  'self-help-resources.md',
+  'Setting-up-a-OneDrive-project-to-use-with-diagrams.net.md',
+  'Stale-bot-FAQ.md',
+  'Translations.md',
+  'images/app_branding.png',
+  'images/schema.svg',
+  '_Sidebar.md',
+  '_Footer.md',
+];
+
+const GITLAB_TREE = [
+  'Home.md',
+  'Testing.md',
+  '_sidebar.md',
+  'change_logs/v1.4.1.md',
+  'change_logs/v1.6.0.md',
+  // The nested layout a real GitLab wiki uses, and the reason a bare path is
+  // resolved from the root: `trd/v1.3.2/home.md` links to `trd/v1.3.3/home`.
+  'trd/v1.3.2/home.md',
+  'trd/v1.3.2/HLD.md',
+  'trd/v1.3.3/home.md',
+  '.gitlab/redirects.yml',
+];
+
+describe('buildWikiEntries', () => {
+  test('lists markdown pages before assets, Home first', () => {
+    const entries = buildWikiEntries(DRAWIO_TREE);
+    expect(entries[0].path).toBe('Home.md');
+    expect(entries.map((entry) => entry.isMarkdown)).toEqual([
+      true, true, true, true, true, true, true, true, false, false,
+    ]);
+    expect(entries.filter((entry) => !entry.isMarkdown).map((entry) => entry.path)).toEqual([
+      'images/app_branding.png',
+      'images/schema.svg',
+    ]);
+  });
+
+  test('keeps assets in the tree so a page reference can resolve', () => {
+    const entries = buildWikiEntries(GITLAB_TREE);
+    expect(entries.some((entry) => entry.path === 'change_logs/v1.6.0.md')).toBe(true);
+    expect(entries.some((entry) => entry.path === '.gitlab/redirects.yml')).toBe(false);
+  });
+
+  test('drops both hosts’ chrome fragments, whatever their case', () => {
+    const paths = buildWikiEntries([...DRAWIO_TREE, ...GITLAB_TREE]).map((entry) => entry.path);
+    expect(paths).not.toContain('_Sidebar.md');
+    expect(paths).not.toContain('_Footer.md');
+    expect(paths).not.toContain('_sidebar.md');
+  });
+
+  test('groups a folder and strips the extension from the title', () => {
+    const entries = buildWikiEntries(GITLAB_TREE);
+    const changelog = entries.find((entry) => entry.path === 'change_logs/v1.6.0.md');
+    expect(changelog).toMatchObject({ title: 'v1.6.0', folder: 'change_logs', isMarkdown: true });
+  });
+});
+
+describe('resolveWikiReference', () => {
+  const lookup = wikiEntryLookup(buildWikiEntries([...DRAWIO_TREE, ...GITLAB_TREE]));
+
+  test('resolves a bare path from the wiki root, not the page folder', () => {
+    // The shape a real GitLab wiki writes: from `trd/v1.3.2/home.md`, a link to
+    // `trd/v1.3.3/home` is rooted at the wiki, while page-relative resolution
+    // looked for `trd/v1.3.2/trd/v1.3.3/home` and found nothing — 25 of that
+    // wiki's 41 links then opened a browser tab instead of a page.
+    expect(resolveWikiReference('trd/v1.3.3/home', 'trd/v1.3.2/home.md', lookup)).toBe('trd/v1.3.3/home.md');
+    expect(resolveWikiReference('trd/v1.3.2/HLD', 'trd/v1.3.2/home.md', lookup)).toBe('trd/v1.3.2/HLD.md');
+  });
+
+  test('still resolves a bare sibling name beside the page', () => {
+    // `Home.md` has no folder of its own, so both bases are the root here.
+    expect(resolveWikiReference('change_logs/v1.6.0', 'Home.md', lookup)).toBe('change_logs/v1.6.0.md');
+  });
+
+  test('an explicit ./ or ../ asks for the page folder', () => {
+    expect(resolveWikiReference('./v1.4.1', 'change_logs/v1.6.0.md', lookup)).toBe('change_logs/v1.4.1.md');
+    expect(resolveWikiReference('../Home', 'change_logs/v1.6.0.md', lookup)).toBe('Home.md');
+    // `../trd/v1.3.3/home` from a nested page is the root form written the other way.
+    expect(resolveWikiReference('../trd/v1.3.3/home', 'trd/v1.3.2/home.md', lookup)).toBe('trd/v1.3.3/home.md');
+  });
+
+  test('a root-relative path is the same as a bare one', () => {
+    expect(resolveWikiReference('/change_logs/v1.6.0', 'Home.md', lookup)).toBe('change_logs/v1.6.0.md');
+  });
+
+  test('resolves case-insensitively', () => {
+    expect(resolveWikiReference('translations', 'Home.md', lookup)).toBe('Translations.md');
+    expect(resolveWikiReference('HOMEs.md', 'Home.md', lookup)).toBe(null);
+  });
+
+  test('leaves anything that is not an in-wiki reference alone', () => {
+    for (const reference of [
+      'https://x.test/a',
+      'mailto:a@b.c',
+      '//cdn.test/a',
+      '#section',
+      'missing-page',
+      '',
+    ]) {
+      expect(resolveWikiReference(reference, 'Home.md', lookup)).toBe(null);
+    }
+  });
+
+  test('cannot climb out of the wiki with ..', () => {
+    expect(resolveWikiReference('../../../../etc/passwd', 'Home.md', lookup)).toBe(null);
+  });
+});
+
+describe('findWikiSidebarPath', () => {
+  test('finds the sidebar whatever its case or extension', () => {
+    expect(findWikiSidebarPath(['Home.md', '_sidebar.md'])).toBe('_sidebar.md');
+    expect(findWikiSidebarPath(['Home.md', '_Sidebar.md'])).toBe('_Sidebar.md');
+    expect(findWikiSidebarPath(['Home.md'])).toBe(null);
+  });
+
+  test('prefers the root sidebar over a nested one', () => {
+    expect(findWikiSidebarPath(['guides/_Sidebar.md', '_sidebar.md'])).toBe('_sidebar.md');
+    expect(findWikiSidebarPath(['guides/_Sidebar.md'])).toBe('guides/_Sidebar.md');
+  });
+});
+
+describe('parseWikiSidebar', () => {
+  // The exact shape this repo's own GitLab wiki writes.
+  const SIDEBAR = `### 📚 Navigation
+
+- [🏠 Home](Home)
+- [🧪 Testing Guide](Testing)
+
+---
+
+### 📋 Changelogs
+
+- [v1.6.0](change_logs/v1.6.0)
+- [v1.4.1](change_logs/v1.4.1)
+
+---
+
+### 📊 Info
+
+**Version**: 1.6.0
+**Java**: 1.8
+`;
+
+  const entries = buildWikiEntries(['Home.md', 'Testing.md', 'change_logs/v1.6.0.md', 'change_logs/v1.4.1.md', 'Orphan.md']);
+  const sections = parseWikiSidebar(SIDEBAR, '_sidebar.md', entries);
+
+  test('keeps the author’s groups and labels', () => {
+    expect(sections.map((section) => section.title)).toEqual(['📚 Navigation', '📋 Changelogs', '📊 Info']);
+    expect(sections[0].links.map((link) => link.label)).toEqual(['🏠 Home', '🧪 Testing Guide']);
+    expect(sections[1].links.map((link) => link.label)).toEqual(['v1.6.0', 'v1.4.1']);
+  });
+
+  test('resolves each link to the page it names', () => {
+    expect(sections[1].links[0].path).toBe('change_logs/v1.6.0.md');
+  });
+
+  test('keeps a non-link block as the section’s notes', () => {
+    expect(sections[2].links).toEqual([]);
+    expect(sections[2].notes).toEqual(['Version: 1.6.0', 'Java: 1.8']);
+  });
+
+  test('classifies an external link and a dangling one', () => {
+    const parsed = parseWikiSidebar('- [Repo](https://github.com/o/n)\n- [Gone](nowhere)\n', '_sidebar.md', entries);
+    expect(parsed[0].links[0]).toMatchObject({ url: 'https://github.com/o/n', path: null });
+    expect(parsed[0].links[1]).toMatchObject({ url: null, path: null, target: 'nowhere' });
+  });
+
+  test('reads a nested bullet and a link carrying a title', () => {
+    const parsed = parseWikiSidebar('  - [Deep](change_logs/v1.6.0 "the title")\n', '_sidebar.md', entries);
+    expect(parsed[0].links[0]).toMatchObject({ label: 'Deep', path: 'change_logs/v1.6.0.md' });
+  });
+});
+
+describe('withRemainingPages', () => {
+  const entries = buildWikiEntries(['Home.md', 'Orphan.md', 'change_logs/v1.0.0.md']);
+  const sidebar = parseWikiSidebar('- [Home](Home)\n', '_sidebar.md', entries);
+
+  test('appends a page the sidebar never mentions', () => {
+    // A sidebar is the author's navigation, not an index — the panel has no
+    // address bar, so an unlisted page would be unreachable.
+    const merged = withRemainingPages(sidebar, entries);
+    expect(merged.at(-1)?.title).toBe('Other pages');
+    expect(merged.at(-1)?.links.map((link) => link.path)).toEqual(['Orphan.md', 'change_logs/v1.0.0.md']);
+  });
+
+  test('adds nothing when the sidebar lists every page', () => {
+    const full = parseWikiSidebar('- [Home](Home)\n- [Orphan](Orphan)\n- [v1](change_logs/v1.0.0)\n', '_sidebar.md', entries);
+    expect(withRemainingPages(full, entries)).toHaveLength(1);
+  });
+});
+
+describe('sectionsFromEntries', () => {
+  test('groups a sidebar-less wiki by folder, markdown pages only', () => {
+    const entries = buildWikiEntries(['Home.md', 'guides/A.md', 'guides/B.md', 'images/x.png']);
+    expect(sectionsFromEntries(entries).map((section) => [section.title, section.links.length])).toEqual([
+      ['Pages', 1],
+      ['guides', 2],
+    ]);
+  });
+});
+
+describe('wikiHeadingSlug', () => {
+  test('drops an emoji but keeps the variation selector after it', () => {
+    // The two shapes a real wiki produced: a symbol is not a letter and is
+    // dropped, while the U+FE0F mark that follows it survives — which is why the
+    // anchor GitLab writes for `## ⚠️ Migration Queries` starts with `%EF%B8%8F`.
+    expect(wikiHeadingSlug('🎯 Overview')).toBe('overview');
+    expect(wikiHeadingSlug('⚠️ Migration Queries')).toBe('\ufe0f-migration-queries');
+    expect(wikiHeadingSlug('Test Count Summary')).toBe('test-count-summary');
+    expect(wikiHeadingSlug('C++ & Rust: a/b')).toBe('c-rust-ab');
+  });
+});
+
+describe('expandGollumLinks', () => {
+  test('turns a bare page link into a markdown link, encoding the space', () => {
+    // `[x](Embed Diagrams)` is not a link — a destination cannot hold a space —
+    // so the target is percent-encoded and resolved back to the dashed page.
+    expect(expandGollumLinks('see [[Embed Diagrams]]')).toBe('see [Embed Diagrams](Embed%20Diagrams)');
+  });
+
+  test('keeps the label and the target of a piped link', () => {
+    expect(expandGollumLinks('[[Deploying|deploying]]')).toBe('[Deploying](deploying)');
+    expect(expandGollumLinks('[[Deploying|deploying|anchor]]')).toBe('[Deploying](deploying#anchor)');
+  });
+
+  test('leaves fenced blocks and inline code as written', () => {
+    const source = '```\n[[not a link]]\n```\n\ninline `[[x]]` and [[real]]';
+    expect(expandGollumLinks(source)).toBe('```\n[[not a link]]\n```\n\ninline `[[x]]` and [real](real)');
+  });
+});

package/src/shared/lib/wiki/pages.ts

@@ -0,0 +1,242 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Wiki tree → page list, and wiki reference → page path.
+ *
+ * Shared by the server (which builds the list out of `git ls-tree`) and the
+ * panel (which resolves a page's own links and images against that list), so
+ * the two can never disagree about what a wiki contains or what
+ * `[x](change_logs/v1.6.0)` points at.
+ *
+ * Three provider conventions are encoded here because each is load-bearing for
+ * a reader and none is visible in the raw markdown:
+ *
+ *   - **Chrome files are not pages.** GitHub and GitLab both treat
+ *     `_Sidebar`/`_Footer`/`_Header` as fragments the host renders around every
+ *     page. Listing them as pages puts a nav fragment in the middle of the nav.
+ *   - **References are case- and space-insensitive.** GitHub's own wiki
+ *     resolves `/wiki/eMbEd-Diagrams` as readily as `/wiki/Embed-Diagrams`
+ *     (verified), and its `[[Embed Diagrams]]` link targets `Embed-Diagrams.md`
+ *     — gollum turns spaces into dashes. GitLab's `[v1.6.0](change_logs/v1.6.0)`
+ *     omits the `.md` entirely. Resolution therefore tries the written path, the
+ *     path with the extension, the dash form of both, and matches them
+ *     case-insensitively.
+ *   - **Assets are entries too.** A page's `![](images/schema.png)` resolves
+ *     against the same tree the pages do, so the listing keeps them and only
+ *     the reader filters on `isMarkdown`.
+ */
+
+import type { WikiEntry } from '@/shared/types/wiki';
+
+/** Wiki chrome: navigation/footer/header fragments, not pages. */
+const WIKI_CHROME: Record<string, true> = {
+  _sidebar: true,
+  _footer: true,
+  _header: true,
+};
+
+/** Extension stripped from a path's basename. */
+const MARKDOWN_EXT_RE = /\.(md|markdown)$/i;
+
+export function isWikiMarkdownPath(path: string): boolean {
+  return MARKDOWN_EXT_RE.test(path);
+}
+
+/**
+ * The wiki tree as a list: markdown pages first (Home, then root pages, then
+ * folder groups, alphabetical within each), assets after them.
+ */
+export function buildWikiEntries(paths: readonly string[]): WikiEntry[] {
+  const entries: WikiEntry[] = [];
+  const seen = new Set<string>();
+  for (const path of paths) {
+    if (!path || seen.has(path)) continue;
+    const segments = path.split('/');
+    // GitLab keeps its redirect map in `.gitlab/redirects.yml`; a dot-segment
+    // is provider metadata on either host, never a page.
+    if (segments.some((segment) => segment.startsWith('.'))) continue;
+    const base = segments[segments.length - 1] ?? path;
+    if (WIKI_CHROME[base.replace(MARKDOWN_EXT_RE, '').toLowerCase()]) continue;
+    seen.add(path);
+    const slash = path.lastIndexOf('/');
+    entries.push({
+      path,
+      title: base.replace(MARKDOWN_EXT_RE, ''),
+      folder: slash < 0 ? '' : path.slice(0, slash),
+      isMarkdown: MARKDOWN_EXT_RE.test(path),
+    });
+  }
+
+  return entries.sort((a, b) => {
+    if (a.isMarkdown !== b.isMarkdown) return a.isMarkdown ? -1 : 1;
+    if (!a.isMarkdown) return a.path.localeCompare(b.path);
+    const aHome = a.title.toLowerCase() === 'home';
+    const bHome = b.title.toLowerCase() === 'home';
+    if (aHome !== bHome) return aHome ? -1 : 1;
+    if (a.folder !== b.folder) {
+      if (!a.folder) return -1;
+      if (!b.folder) return 1;
+      return a.folder.localeCompare(b.folder);
+    }
+    return a.title.localeCompare(b.title);
+  });
+}
+
+/** Lower-cased path → the path as stored, for case-insensitive resolution. */
+export function wikiEntryLookup(entries: readonly WikiEntry[]): Map<string, string> {
+  const lookup = new Map<string, string>();
+  for (const entry of entries) {
+    const key = entry.path.toLowerCase();
+    if (!lookup.has(key)) lookup.set(key, entry.path);
+  }
+  return lookup;
+}
+
+/** Collapse `.`/`..` segments; climbing above the wiki root is dropped. */
+export function normalizeWikiSegments(segments: readonly string[]): string {
+  const out: string[] = [];
+  for (const segment of segments) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join('/');
+}
+
+/** A scheme (`https:`), protocol-relative host, in-page fragment, or empty. */
+const NON_WIKI_REFERENCE_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|$)/i;
+
+/** Whether a reference is an explicit relative path (`./x`, `../x`). */
+const EXPLICIT_RELATIVE_RE = /^\.{1,2}[/\\]/;
+
+/**
+ * The wiki path a reference written inside `fromPath` names, or null when the
+ * reference is not an in-wiki one (leave those exactly as written).
+ *
+ * **A bare path is resolved from the wiki ROOT first, then from the page's own
+ * folder.** That order is not a coin flip: it is what both hosts do, and it is
+ * the difference between a working link and an inert one on a nested wiki. A
+ * real GitLab wiki writes `[TRD v1.3.3](trd/v1.3.3/home)` from
+ * `trd/v1.3.2/home.md` — from the root, while page-relative resolution looks
+ * for `trd/v1.3.2/trd/v1.3.3/home` and finds nothing (measured: 25 of the 41
+ * links on that wiki failed to resolve, and every one of them then opened a
+ * browser tab instead of a page). An explicitly relative reference (`./x`,
+ * `../x`) is the author asking for the page's own folder, so it is tried there
+ * first; `../trd/v1.3.3/home` from `change_logs/v1.3.3.md` is the same target
+ * written the other way.
+ *
+ * `lookup` is the wiki's own path map, so a hit is proof the target exists —
+ * which is what lets the caller turn a link into in-panel navigation.
+ */
+export function resolveWikiReference(
+  reference: string,
+  fromPath: string,
+  lookup: Map<string, string>,
+): string | null {
+  const raw = reference.trim();
+  if (NON_WIKI_REFERENCE_RE.test(raw)) return null;
+
+  // `?v=1` and `#section` address the page, not the file in the tree. A leading
+  // `/` is the wiki's own root, which is the same thing as a bare path here.
+  const withoutQuery = raw.replace(/^[/\\]+/, '').split(/[?#]/)[0];
+  let decoded = withoutQuery;
+  try {
+    decoded = decodeURIComponent(withoutQuery);
+  } catch {
+    // A malformed escape is the reference's own problem; use it verbatim.
+  }
+  if (!decoded) return null;
+
+  const segments = decoded.split(/[\\/]+/);
+  const pageDir = fromPath.split('/').slice(0, -1);
+  const bases = EXPLICIT_RELATIVE_RE.test(decoded) ? [pageDir, []] : [[], pageDir];
+  for (const base of bases) {
+    const path = normalizeWikiSegments([...base, ...segments]);
+    if (!path) continue;
+    // The written path, the extension both providers omit, and gollum's
+    // space→dash form of each.
+    const dashed = path.replace(/ /g, '-');
+    for (const candidate of [path, `${path}.md`, dashed, `${dashed}.md`]) {
+      const hit = lookup.get(candidate.toLowerCase());
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+/**
+ * The id a wiki heading gets, which is what the page's own `#anchor` links name.
+ *
+ * Both hosts slug a heading by lowercasing it and dropping everything that is
+ * not a letter, a digit, a combining mark, a space, a hyphen or an underscore,
+ * then turning spaces into hyphens. The mark matters: `## ⚠️ Migration Queries`
+ * is `#%EF%B8%8F-migration-queries` — the warning sign (a symbol) is dropped
+ * while the variation selector after it (a mark, U+FE0F) survives. Verified
+ * against `git-rbi.jatismobile.com/jns6_5/drrealhandler`, whose changelog pages
+ * link exactly that anchor.
+ *
+ * That is not cosmetic: a wiki's table of contents is written as
+ * `[Overview](#overview)`, and with the renderer's own id (which keeps the
+ * emoji) every entry pointed at an element that did not exist, so clicking a
+ * TOC link did nothing at all.
+ */
+export function wikiHeadingSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+/**
+ * One `[[Label|Target]]` link, converted to the markdown link both hosts render.
+ *
+ * The destination is percent-encoded because a gollum page name holds spaces
+ * (`[[Embed Diagrams]]`) and a markdown destination cannot: `[x](Embed Diagrams)`
+ * is not a link at all, so marked emits the brackets as literal text. Encoding
+ * the space keeps the target resolvable by {@link resolveWikiReference}, which
+ * decodes it before matching.
+ */
+function expandGollumLink(inner: string): string {
+  const parts = inner.split('|').map((part) => part.trim());
+  if (parts.length === 1) {
+    const target = encodeURI(parts[0]);
+    return `[${parts[0]}](${target})`;
+  }
+  const anchor = parts[2] ? `#${encodeURI(parts[2])}` : '';
+  return `[${parts[0]}](${encodeURI(parts[1])}${anchor})`;
+}
+
+/**
+ * Expand gollum's `[[Page]]` / `[[Label|Page]]` wiki links into markdown links.
+ *
+ * GitHub wikis are gollum, and a `[[Page]]` is invisible to a markdown parser —
+ * it would render as literal brackets. Fenced blocks and inline code are left
+ * alone, so a page that documents the syntax does not get its example rewritten.
+ */
+export function expandGollumLinks(markdown: string): string {
+  let fenced = false;
+  return markdown
+    .split('\n')
+    .map((line) => {
+      if (/^\s*(?:```|~~~)/.test(line)) {
+        fenced = !fenced;
+        return line;
+      }
+      if (fenced) return line;
+      // Odd segments are inline code: `[[x]]` inside backticks is an example.
+      return line
+        .split('`')
+        .map((part, index) =>
+          index % 2 === 1 ? part : part.replace(/\[\[([^[\]]+)\]\]/g, (_, inner: string) => expandGollumLink(inner)),
+        )
+        .join('`');
+    })
+    .join('\n');
+}