Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
statSync,
utimesSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
createTargetNamespace,
encodeHrefPath,
LOCAL_DIR,
skillLiveDocName,
} from '@inkeep/open-knowledge-core';
import { beforeEach, describe, expect, test, vi } from 'vitest';
import {
BacklinkIndex,
type BrokenOutboundLink,
computeBrokenOutboundLinks,
type ExtractedWikiLink,
extractJsxSrcRefsFromMarkdown,
extractMarkdownLinksFromMarkdown,
extractWikiLinksFromMarkdown,
resolveMarkdownHref,
} from './backlink-index.ts';
import { _resetDocExtensionsForTests } from './doc-extensions.ts';
import { getLogger } from './logger.ts';
beforeEach(() => {
_resetDocExtensionsForTests();
});
describe('extractWikiLinksFromMarkdown', () => {
test('extracts wiki-link targets with context snippets', () => {
expect(extractWikiLinksFromMarkdown('Alpha links to [[beta]] for deployment notes.\n')).toEqual<
ExtractedWikiLink[]
>([
{
target: 'beta',
anchor: null,
snippet: 'Alpha links to beta for deployment notes.',
line: 0,
column: 15,
},
]);
});
test('ignores wiki-links inside fenced code blocks and inline code', () => {
const markdown = [
'See [[alpha]].',
'',
'```ts',
'const example = "[[beta]]";',
'```',
'',
'Inline `[[gamma]]` should not count.',
].join('\n');
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'alpha',
anchor: null,
snippet: 'See alpha.',
line: 0,
column: 4,
},
]);
});
test('tolerates colon ranges that remark-directive would claim', () => {
const markdown = '**Current (slash-command.ts:108-115):**\n\nSee [[beta]].\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'beta',
anchor: null,
snippet: 'See beta.',
line: 2,
column: 4,
},
]);
});
test('ignores wiki-links inside tilde fenced code blocks', () => {
const markdown = [
'See [[alpha]].',
'',
'~~~js',
'const x = "[[beta]]";',
'~~~',
'',
'And [[gamma]].',
].join('\n');
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{ target: 'alpha', anchor: null, snippet: 'See alpha.', line: 0, column: 4 },
{ target: 'gamma', anchor: null, snippet: 'And gamma.', line: 6, column: 4 },
]);
});
test('fence-length matching: longer closing fence ends a shorter opening fence', () => {
const markdown = [
'Before [[alpha]].',
'````ts',
'[[inside]]',
'```',
'[[also-inside]]',
'````',
'After [[beta]].',
].join('\n');
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{ target: 'alpha', anchor: null, snippet: 'Before alpha.', line: 0, column: 7 },
{ target: 'beta', anchor: null, snippet: 'After beta.', line: 6, column: 6 },
]);
});
test('extracts multiple wiki-links from the same line', () => {
const markdown = 'See [[alpha]] and [[beta]] for more.\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'alpha',
anchor: null,
snippet: 'See alpha and beta for more.',
line: 0,
column: 4,
},
{
target: 'beta',
anchor: null,
snippet: 'See alpha and beta for more.',
line: 0,
column: 14,
},
]);
});
test('handles anchor syntax [[page#heading]]', () => {
const markdown = 'See [[guide#installation]] for setup.\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'guide',
anchor: 'installation',
snippet: 'See guide#installation for setup.',
line: 0,
column: 4,
},
]);
});
test('handles alias syntax [[page|display text]]', () => {
const markdown = 'See [[guide|the guide]] for setup.\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{ target: 'guide', anchor: null, snippet: 'See the guide for setup.', line: 0, column: 4 },
]);
});
test('handles combined anchor and alias syntax [[page#section|display]]', () => {
const markdown = 'See [[API#auth|Auth Docs]] for setup.\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{ target: 'API', anchor: 'auth', snippet: 'See Auth Docs for setup.', line: 0, column: 4 },
]);
});
test('backslash-escaped opening bracket suppresses wiki-link', () => {
const markdown = 'Not a link: \\[[page]] but [[real]] is.\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'real',
anchor: null,
snippet: 'Not a link: [[page]] but real is.',
line: 0,
column: 25,
},
]);
});
test('inline code with multi-backtick delimiter: shorter run does not close span', () => {
const markdown = 'See `foo``bar` and [[target]].\n';
expect(extractWikiLinksFromMarkdown(markdown)).toEqual([
{
target: 'target',
anchor: null,
snippet: 'See foo``bar and target.',
line: 0,
column: 17,
},
]);
});
test('long unclosed backtick run does not trigger quadratic scan', () => {
const prefix = 'prefix ';
const backticks = '`'.repeat(50_000);
const markdown = `${prefix}${backticks}\n\nSee [[target]].\n`;
const start = performance.now();
const links = extractWikiLinksFromMarkdown(markdown);
const elapsed = performance.now() - start;
expect(links).toEqual([
{ target: 'target', anchor: null, snippet: 'See target.', line: 2, column: 4 },
]);
expect(elapsed).toBeLessThan(1000);
});
test('offsets link lines by the caller-supplied lineOffset', () => {
expect(extractWikiLinksFromMarkdown('See [[alpha]].', '', 3)).toEqual([
{ target: 'alpha', anchor: null, snippet: 'See alpha.', line: 3, column: 4 },
]);
});
});
describe('BacklinkIndex', () => {
test('indexes full, collapsed, and shortcut reference links across graph queries', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-reference-links-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(
'source',
[
'See [full label][full-ref], [collapsed-ref][], and [shortcut-ref].',
'',
'[full-ref]: ./full-target.md',
'[collapsed-ref]: ./collapsed-target.md',
'[shortcut-ref]: ./shortcut-target.md',
].join('\n'),
);
const targets = ['collapsed-target', 'full-target', 'shortcut-target'];
expect(index.getForwardLinks('source')).toEqual(targets);
for (const target of targets) {
expect(index.getBacklinks(target)).toEqual([expect.objectContaining({ source: 'source' })]);
}
expect(index.getDeadLinks(['source']).map((entry) => entry.target)).toEqual(targets);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('deleteDocument removes outbound links and incoming backlinks', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-del-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', 'See [[beta]].\n');
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'See beta.' },
]);
index.deleteDocument('alpha');
expect(index.getBacklinks('beta')).toEqual([]);
expect(index.getForwardLinks('alpha')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('skill and template file links resolve to their content docs, not synthetic names', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-artifact-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(
'work-log',
'Touched [the skill](.ok/skills/my-skill/SKILL.md) and [the tpl](notes/.ok/templates/daily.md).\n',
);
expect(index.getBacklinks('.ok/skills/my-skill/SKILL')).toEqual([
expect.objectContaining({ source: 'work-log' }),
]);
expect(index.getBacklinks('notes/.ok/templates/daily')).toEqual([
expect.objectContaining({ source: 'work-log' }),
]);
expect(index.getBacklinks('__skill__/project/my-skill')).toEqual([]);
expect(index.getBacklinks('__template__/notes/daily')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('indexes a managed-artifact doc (skill) own outgoing links', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('__skill__/project/my-skill', 'See [[architecture]].\n');
expect(index.getForwardLinks('__skill__/project/my-skill')).toEqual(['architecture']);
expect(index.getBacklinks('architecture')).toEqual([
expect.objectContaining({ source: '__skill__/project/my-skill' }),
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('renameDocument moves edges from old doc name to new', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-rename-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', 'See [[beta]].\n');
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'See beta.' },
]);
index.renameDocument('alpha', 'gamma', '# Gamma\n\nSee [[beta]].\n');
expect(index.getBacklinks('beta')).toEqual([
{ source: 'gamma', anchor: null, snippet: 'See beta.' },
]);
expect(index.getForwardLinks('alpha')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('switchBranch isolates graph state per branch', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-branch-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', '[[beta]]\n', 'main');
expect(index.getBacklinks('beta', 'main')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'beta' },
]);
index.switchBranch('feature');
expect(index.getBacklinks('beta')).toEqual([]);
index.updateDocumentFromMarkdown('gamma', '[[beta]]\n', 'feature');
expect(index.getBacklinks('beta', 'feature')).toEqual([
{ source: 'gamma', anchor: null, snippet: 'beta' },
]);
index.switchBranch('main');
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'beta' },
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('updateDocument replaces forward links when content changes', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-update-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
const links1: ExtractedWikiLink[] = [{ target: 'beta', anchor: null, snippet: 'one' }];
index.updateDocument('alpha', links1);
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'one' },
]);
const links2: ExtractedWikiLink[] = [{ target: 'gamma', anchor: null, snippet: 'two' }];
index.updateDocument('alpha', links2);
expect(index.getBacklinks('beta')).toEqual([]);
expect(index.getBacklinks('gamma')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'two' },
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks returns missing targets ordered by source count then target', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-links-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(
join(contentDir, 'alpha.md'),
'# Alpha\n\nSee [[missing-target]] and [missing markdown](./missing-markdown.md) plus [[existing]].\n',
'utf-8',
);
writeFileSync(join(contentDir, 'beta.md'), '# Beta\n\nSee [[missing-target]].\n', 'utf-8');
writeFileSync(join(contentDir, 'gamma.md'), '# Gamma\n\nSee [[other-missing]].\n', 'utf-8');
writeFileSync(join(contentDir, 'existing.md'), '# Existing\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
const deadLinks = index.getDeadLinks(['alpha', 'beta', 'gamma', 'existing']);
expect(deadLinks.map((entry) => entry.target)).toEqual([
'missing-target',
'missing-markdown',
'other-missing',
]);
expect(deadLinks[0]?.sources.map((entry) => entry.source)).toEqual(['alpha', 'beta']);
expect(deadLinks[1]?.sources.map((entry) => entry.source)).toEqual(['alpha']);
expect(deadLinks[2]?.sources.map((entry) => entry.source)).toEqual(['gamma']);
expect(
deadLinks.every((entry) => entry.sources.every((source) => source.snippet !== null)),
).toBe(true);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks never reports a link to an existing folder (PRD-7956)', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-links-folder-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'guides', 'deep'), { recursive: true });
try {
writeFileSync(
join(contentDir, 'alpha.md'),
'# Alpha\n\nSee [[guides]] and [markdown-form](./guides/deep) plus [[missing-folder]].\n',
'utf-8',
);
writeFileSync(
join(contentDir, 'guides', 'deep', 'guide-one.md'),
'# Guide one\n\nBody.\n',
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
const deadLinks = index.getDeadLinks(['alpha', 'guides/deep/guide-one']);
expect(deadLinks.map((entry) => entry.target)).toEqual(['missing-folder']);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks accepts a watcher folder inventory for folders with no doc descendants', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-links-watcher-folder-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), '# Alpha\n\nSee [[assets]].\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['alpha']).map((entry) => entry.target)).toEqual(['assets']);
expect(index.getDeadLinks(['alpha'], undefined, undefined, ['assets'])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks returns an empty array when every target exists', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-links-empty-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), '# Alpha\n\nSee [[beta]].\n', 'utf-8');
writeFileSync(join(contentDir, 'beta.md'), '# Beta\n\nReady.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['alpha', 'beta'])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks does not flag a freshly-indexed target missing from the admitted set', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-links-fresh-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocument('report', [
{ target: 'evidence/new-target', anchor: null, snippet: 'see new target' },
]);
index.updateDocument('evidence/new-target', []);
expect(index.getBacklinkCount('evidence/new-target')).toBe(1);
expect(index.getDeadLinks(['report'])).toEqual([]);
index.updateDocument('report', [
{ target: 'evidence/new-target', anchor: null, snippet: 'see new target' },
{ target: 'evidence/ghost', anchor: null, snippet: 'see ghost' },
]);
expect(index.getDeadLinks(['report']).map((entry) => entry.target)).toEqual([
'evidence/ghost',
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a wikilink to a dotted-filename document is recorded and is not reported dead', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dotted-doc-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'notes'), { recursive: true });
try {
writeFileSync(join(contentDir, 'index.md'), '# Index\n\nSee [[acp.daemon]].\n', 'utf-8');
writeFileSync(join(contentDir, 'notes', 'acp.daemon.md'), '# Daemon\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getForwardLinks('index')).toContain('notes/acp.daemon');
expect(index.getDeadLinks(['index', 'notes/acp.daemon'])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('an undecided raw target stays undecided across a cache save/load', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-raw-roundtrip-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'notes'), { recursive: true });
try {
writeFileSync(
join(contentDir, 'index.md'),
'# Index\n\nSee [[acp.daemon]] and ![[diagram.png]].\n',
'utf-8',
);
writeFileSync(join(contentDir, 'notes', 'acp.daemon.md'), '# Daemon\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
await index.saveToDisk();
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
expect(reloaded.getDeadLinks(['index', 'notes/acp.daemon'])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a bare wikilink the editor reaches by basename is not reported dead', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-bare-basename-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'research'), { recursive: true });
try {
writeFileSync(join(contentDir, 'index.md'), '# Index\n\nSee [[analysis]].\n', 'utf-8');
writeFileSync(join(contentDir, 'research', 'analysis.md'), '# A\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['index', 'research/analysis'])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a bare wikilink naming no document is still reported dead', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-bare-missing-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'research'), { recursive: true });
try {
writeFileSync(join(contentDir, 'index.md'), '# Index\n\nSee [[nowhere]].\n', 'utf-8');
writeFileSync(join(contentDir, 'research', 'analysis.md'), '# A\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['index', 'research/analysis']).map((e) => e.target)).toEqual([
'nowhere',
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('the neighborhood view admits the same documents as the whole graph', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-neighborhood-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'notes'), { recursive: true });
try {
writeFileSync(
join(contentDir, 'index.md'),
'# Index\n\n![[diagram.png]] and [[acp.daemon]].\n',
'utf-8',
);
writeFileSync(join(contentDir, 'notes', 'acp.daemon.md'), '# Daemon\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
const neighborhood = index.getLinkGraphNeighborhood('index', 2).nodes.map((n) => n.id);
const whole = index.getLinkGraph().nodes.map((n) => n.id);
expect(neighborhood).not.toContain('diagram.png');
expect(whole).not.toContain('diagram.png');
expect(neighborhood).toContain('notes/acp.daemon');
expect(whole).toContain('notes/acp.daemon');
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a markdown href is not basename-resolved by the dead-link audit', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-md-exact-'));
const contentDir = join(projectDir, 'content');
mkdirSync(join(contentDir, 'research'), { recursive: true });
try {
writeFileSync(join(contentDir, 'index.md'), '# Index\n\n[A](./analysis.md)\n', 'utf-8');
writeFileSync(join(contentDir, 'research', 'analysis.md'), '# A\n\nBody.\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['index', 'research/analysis']).map((e) => e.target)).toEqual([
'analysis',
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a wiki asset embed is neither reported dead nor minted as a graph node', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-asset-embed-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(
join(contentDir, 'notes.md'),
'# Notes\n\n![[diagram.png]]\n\nSee [[report.pdf]].\n',
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getDeadLinks(['notes'])).toEqual([]);
const graph = index.getLinkGraph();
expect(graph.nodes.map((node) => node.id)).toEqual(['notes']);
expect(graph.links).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a dotted target becomes a graph node once its document is indexed', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dotted-late-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocument('index', [
{ target: 'acp.daemon', anchor: null, snippet: null, rawWikiTarget: true },
]);
expect(index.getLinkGraph().nodes.map((node) => node.id)).toEqual(['index']);
index.updateDocument('notes/acp.daemon', []);
expect(index.getLinkGraph().nodes.map((node) => node.id)).toContain('notes/acp.daemon');
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getIndexedDocNames returns one entry per indexed doc and never a referenced-but-missing target', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-indexed-names-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocument('report', [
{ target: 'evidence/new-target', anchor: null, snippet: 'see new target' },
{ target: 'evidence/ghost', anchor: null, snippet: 'see ghost' },
]);
index.updateDocument('evidence/new-target', []);
expect(new Set(index.getIndexedDocNames())).toEqual(
new Set(['report', 'evidence/new-target']),
);
expect(index.getIndexedDocNames()).not.toContain('evidence/ghost');
index.deleteDocument('evidence/new-target');
expect(index.getIndexedDocNames()).toEqual(['report']);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks reports a target as dead again after deleteDocument removes its forward node', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-after-delete-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocument('report', [
{ target: 'evidence/new-target', anchor: null, snippet: 'see new target' },
]);
index.updateDocument('evidence/new-target', []);
expect(index.getDeadLinks(['report'])).toEqual([]);
index.deleteDocument('evidence/new-target');
expect(index.getDeadLinks(['report']).map((entry) => entry.target)).toEqual([
'evidence/new-target',
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getDeadLinks positions each broken link at its 0-based full-doc source line', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-link-lines-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
const markdown = [
'---',
'title: Alpha',
'---',
'# Alpha',
'',
'```ts',
'const decoy = "[[ghost-wiki]] and [gone](./ghost-md.md)";',
'```',
'',
'See [[ghost-wiki]].',
'And [also gone](./ghost-md.md).',
'',
].join('\n');
index.updateDocumentFromMarkdown('alpha', markdown);
const deadLinks = index.getDeadLinks(['alpha']);
expect(deadLinks.map((entry) => entry.target)).toEqual(['ghost-md', 'ghost-wiki']);
const mdSource = deadLinks[0]?.sources[0];
const wikiSource = deadLinks[1]?.sources[0];
expect(wikiSource).toEqual(expect.objectContaining({ source: 'alpha', line: 9 }));
expect(mdSource).toEqual(expect.objectContaining({ source: 'alpha', line: 10 }));
expect(typeof wikiSource?.column).toBe('number');
expect(typeof mdSource?.column).toBe('number');
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a target broken from multiple source docs carries a per-source position', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-link-multi-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', 'See [[ghost]].\n');
index.updateDocumentFromMarkdown('beta', '# Beta\n\nAlso [[ghost]].\n');
const deadLinks = index.getDeadLinks(['alpha', 'beta']);
expect(deadLinks.map((entry) => entry.target)).toEqual(['ghost']);
expect(deadLinks[0]?.sources).toEqual([
expect.objectContaining({ source: 'alpha', line: 0 }),
expect.objectContaining({ source: 'beta', line: 2 }),
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('dead-link positions survive a cache save/load round-trip', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-link-cache-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', '# Alpha\n\nSee [[ghost]].\n');
await index.saveToDisk();
const raw = readFileSync(
join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main', 'backlinks.json'),
'utf-8',
);
expect(raw).toBe(JSON.stringify(JSON.parse(raw)));
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
expect(reloaded.getDeadLinks(['alpha'])[0]?.sources[0]).toEqual(
expect.objectContaining({ source: 'alpha', line: 2 }),
);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a current-version cache with corrupt positions degrades them to "position unknown"', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dead-link-legacy-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const cacheDir = join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main');
mkdirSync(cacheDir, { recursive: true });
writeFileSync(
join(cacheDir, 'backlinks.json'),
JSON.stringify({
version: 4,
backward: {
ghost: [{ source: 'alpha', anchor: null, snippet: 'See ghost.' }],
wraith: [
{ source: 'alpha', anchor: null, snippet: 'See wraith.', line: '7', column: -2 },
],
shade: [{ source: 'alpha', anchor: null, snippet: 'See shade.', line: 1.5 }],
},
forward: { alpha: ['ghost', 'wraith', 'shade'] },
externalForward: {},
sourceLinks: {
alpha: [
{ target: 'ghost', anchor: null, snippet: 'See ghost.', sourceForm: 'wiki' },
{
target: 'wraith',
anchor: null,
snippet: 'See wraith.',
sourceForm: 'wiki',
line: '7',
column: -2,
},
{
target: 'shade',
anchor: null,
snippet: 'See shade.',
sourceForm: 'wiki',
line: 1.5,
},
],
},
}),
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
expect(await index.loadFromDisk()).toBe(true);
expect(index.getBacklinks('ghost')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'See ghost.' },
]);
const legacySource = index.getDeadLinks(['alpha']).find((e) => e.target === 'ghost')
?.sources[0];
expect(legacySource).toEqual(
expect.objectContaining({ source: 'alpha', snippet: 'See ghost.' }),
);
expect(legacySource?.line).toBeUndefined();
expect(legacySource?.column).toBeUndefined();
const corruptSource = index.getDeadLinks(['alpha']).find((e) => e.target === 'wraith')
?.sources[0];
expect(corruptSource?.line).toBeUndefined();
expect(corruptSource?.column).toBeUndefined();
const fractionalSource = index.getDeadLinks(['alpha']).find((e) => e.target === 'shade')
?.sources[0];
expect(fractionalSource?.line).toBeUndefined();
index.updateDocumentFromMarkdown('alpha', 'See [[ghost]].\n');
expect(index.getDeadLinks(['alpha'])[0]?.sources[0]).toEqual(
expect.objectContaining({ source: 'alpha', line: 0 }),
);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a v1 cache is rejected so skill refs are recorded instead of silently missing', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skillrefs-guard-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const analyze = '.agents/skills/analyze/SKILL';
const research = '.agents/skills/research/SKILL';
mkdirSync(join(contentDir, '.agents', 'skills', 'analyze'), { recursive: true });
mkdirSync(join(contentDir, '.agents', 'skills', 'research'), { recursive: true });
writeFileSync(
join(contentDir, '.agents', 'skills', 'analyze', 'SKILL.md'),
'# Analyze\n\nFor reports use /research.\n',
);
writeFileSync(join(contentDir, '.agents', 'skills', 'research', 'SKILL.md'), '# Research\n');
const cacheDir = join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main');
mkdirSync(cacheDir, { recursive: true });
writeFileSync(
join(cacheDir, 'backlinks.json'),
JSON.stringify({
version: 1,
backward: {},
forward: { [analyze]: [], [research]: [] },
externalForward: {},
mtimes: {},
}),
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
expect(await index.loadFromDisk()).toBe(false);
await index.rebuildFromDisk();
expect(index.getForwardLinks(analyze)).toEqual([research]);
expect(index.getBacklinks(research)).toEqual([
{ source: analyze, anchor: null, snippet: null },
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test.each([
{ version: 3, sourceLinks: undefined, expectedWarnings: [], kept: true },
{
version: 4,
sourceLinks: {},
expectedWarnings: [
[{ branch: 'main' }, 'Incomplete backlink cache snapshot for main; rebuilding from disk'],
],
kept: false,
},
{
version: 4,
sourceLinks: { alpha: [], beta: [] },
expectedWarnings: [
[{ branch: 'main' }, 'Incomplete backlink cache snapshot for main; rebuilding from disk'],
],
kept: false,
},
])('rejects incomplete source-link snapshots and rebuilds from disk: $version', async (cache) => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-source-links-guard-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), '[[beta]]');
writeFileSync(join(contentDir, 'beta.md'), '# Beta');
const cacheDir = join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main');
mkdirSync(cacheDir, { recursive: true });
writeFileSync(
join(cacheDir, 'backlinks.json'),
JSON.stringify({
...cache,
backward: { beta: [{ source: 'alpha', anchor: null, snippet: 'beta' }] },
forward: { alpha: ['beta'], beta: [] },
externalForward: {},
}),
);
const index = new BacklinkIndex({ projectDir, contentDir });
const warn = vi.spyOn(getLogger('backlinks'), 'warn');
try {
expect(await index.loadFromDisk()).toBe(false);
expect(warn.mock.calls).toEqual(cache.expectedWarnings);
expect(existsSync(join(cacheDir, 'backlinks.json'))).toBe(cache.kept);
} finally {
warn.mockRestore();
}
await index.rebuildFromDisk();
expect(index.getForwardLinks('alpha')).toEqual(['beta']);
expect(index.getRenameSourceInventory().find((entry) => entry.docName === 'alpha')).toEqual(
expect.objectContaining({ wikiTargets: ['beta'] }),
);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test.each([
{
label: 'truncated JSON',
corrupt: (good: string) => good.slice(0, Math.floor(good.length / 2)),
},
{ label: 'NUL-padded file', corrupt: (good: string) => '\0'.repeat(good.length) },
])(
'a torn cache snapshot ($label) is discarded once and replaced on the next save',
async ({ corrupt }) => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-torn-cache-'));
const contentDir = join(projectDir, 'content');
const cachePath = join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main', 'backlinks.json');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), 'See [[beta]].\n');
writeFileSync(join(contentDir, 'beta.md'), '# Beta\n');
const first = new BacklinkIndex({ projectDir, contentDir });
await first.rebuildFromDisk();
await first.saveToDisk();
writeFileSync(cachePath, corrupt(readFileSync(cachePath, 'utf-8')));
const second = new BacklinkIndex({ projectDir, contentDir });
expect(await second.loadFromDisk()).toBe(false);
expect(existsSync(cachePath)).toBe(false);
await second.rebuildFromDisk();
expect(second.getBacklinks('beta').map((link) => link.source)).toEqual(['alpha']);
await second.saveToDisk();
const third = new BacklinkIndex({ projectDir, contentDir });
expect(await third.loadFromDisk()).toBe(true);
expect(third.getBacklinks('beta').map((link) => link.source)).toEqual(['alpha']);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
},
);
test('a versionless pre-upgrade cache is rejected so boot cold-rebuilds instead of serving stale keys', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-version-guard-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const templateDoc = 'notes/.ok/templates/daily';
mkdirSync(join(contentDir, 'notes', '.ok', 'templates'), { recursive: true });
writeFileSync(
join(contentDir, 'alpha.md'),
'# Alpha\n\nSee [[notes/.ok/templates/daily]].\n',
);
writeFileSync(join(contentDir, 'notes', '.ok', 'templates', 'daily.md'), '# Daily\n');
const cacheDir = join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main');
mkdirSync(cacheDir, { recursive: true });
writeFileSync(
join(cacheDir, 'backlinks.json'),
JSON.stringify({
backward: {
'__template__/notes/daily': [{ source: 'alpha', anchor: null, snippet: 'See daily.' }],
},
forward: { alpha: ['__template__/notes/daily'] },
externalForward: {},
mtimes: {},
}),
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
expect(await index.loadFromDisk()).toBe(false);
await index.rebuildFromDisk();
expect(index.getBacklinks(templateDoc)).toEqual([
expect.objectContaining({ source: 'alpha' }),
]);
expect(index.getDeadLinks(['alpha', templateDoc])).toEqual([]);
expect(index.getOrphans(['alpha', templateDoc])).not.toContain(templateDoc);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('rebuilds from disk and persists cache per branch', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-project-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), '# Alpha\n\nSee [[beta]].\n', 'utf-8');
writeFileSync(
join(contentDir, 'beta.md'),
'# Beta\n\nReferenced by [[alpha]] and [[alpha#details|Alpha details]].\n',
'utf-8',
);
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getBacklinks('beta')).toEqual([
{
source: 'alpha',
anchor: null,
snippet: 'See beta.',
},
]);
expect(index.getForwardLinks('beta')).toEqual(['alpha']);
expect(index.getHubs()).toEqual([
{ docName: 'alpha', count: 1 },
{ docName: 'beta', count: 1 },
]);
expect(index.getOrphans(['alpha', 'beta', 'gamma'])).toEqual(['gamma']);
await index.saveToDisk();
const cacheRaw = readFileSync(
join(projectDir, '.ok', LOCAL_DIR, 'cache', 'main', 'backlinks.json'),
'utf-8',
);
expect(cacheRaw).toContain('"beta"');
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
expect(reloaded.getBacklinks('beta')).toEqual([
{
source: 'alpha',
anchor: null,
snippet: 'See beta.',
},
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('rebuildFromDisk uses raw markdown scanning instead of the full parser', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-rebuild-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(
join(contentDir, 'alpha.md'),
'**Current (slash-command.ts:108-115):**\n\nSee [[beta]].\n',
'utf-8',
);
writeFileSync(join(contentDir, 'beta.md'), '# Beta\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getBacklinks('beta')).toEqual([
{
source: 'alpha',
anchor: null,
snippet: 'See beta.',
},
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('rebuildFromDisk indexes .mdx files at cold-start (empty extension registry)', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-rebuild-mdx-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.mdx'), '# Alpha\n\nSee [[beta]].\n', 'utf-8');
writeFileSync(join(contentDir, 'beta.mdx'), '# Beta\n', 'utf-8');
writeFileSync(join(contentDir, 'gamma.md'), '# Gamma\n\nSee [[beta]].\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'See beta.' },
{ source: 'gamma', anchor: null, snippet: 'See beta.' },
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('rebuildFromDisk first-wins dedup when both .md and .mdx exist for the same docName', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-dedup-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), '# Alpha\n\nSee [[beta]].\n', 'utf-8');
writeFileSync(join(contentDir, 'alpha.mdx'), '# Alpha\n\nSee [[gamma]].\n', 'utf-8');
writeFileSync(join(contentDir, 'beta.md'), '# Beta\n', 'utf-8');
writeFileSync(join(contentDir, 'gamma.md'), '# Gamma\n', 'utf-8');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
const fwd = index.getForwardLinks('alpha');
expect(fwd).toHaveLength(1);
expect(['beta', 'gamma']).toContain(fwd[0]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getOrphans supports incoming, outgoing, and both modes', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-orphan-modes-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', '[[beta]]');
index.updateDocumentFromMarkdown('beta', '# Beta');
index.updateDocumentFromMarkdown('gamma', '# Gamma');
const allDocs = ['alpha', 'beta', 'gamma'];
expect(index.getOrphans(allDocs, 'incoming')).toEqual(['alpha', 'gamma']);
expect(index.getOrphans(allDocs, 'outgoing')).toEqual(['beta', 'gamma']);
expect(index.getOrphans(allDocs, 'both')).toEqual(['gamma']);
expect(index.getOrphans(allDocs)).toEqual(['gamma']);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getLinkGraph returns sorted nodes and directed edges', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-linkgraph-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', '[[beta]] and [[gamma]]');
index.updateDocumentFromMarkdown('beta', '[[gamma]]');
const { nodes, links } = index.getLinkGraph();
expect(nodes).toEqual([
{ kind: 'doc', id: 'alpha', docName: 'alpha', anchor: null },
{ kind: 'doc', id: 'beta', docName: 'beta', anchor: null },
{ kind: 'doc', id: 'gamma', docName: 'gamma', anchor: null },
]);
expect(links).toContainEqual({ source: 'alpha', target: 'beta' });
expect(links).toContainEqual({ source: 'alpha', target: 'gamma' });
expect(links).toContainEqual({ source: 'beta', target: 'gamma' });
expect(links).toHaveLength(3);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getLinkGraphNeighborhood returns an undirected degree-limited neighborhood', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-linkgraph-neighborhood-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', '[[beta]]');
index.updateDocumentFromMarkdown('beta', '[[gamma]] [[delta]]');
index.updateDocumentFromMarkdown('gamma', '[[epsilon]]');
index.updateDocumentFromMarkdown('delta', '');
index.updateDocumentFromMarkdown('epsilon', '');
const oneHop = index.getLinkGraphNeighborhood('beta', 1);
expect(oneHop.nodes).toEqual([
{ kind: 'doc', id: 'alpha', docName: 'alpha', anchor: null },
{ kind: 'doc', id: 'beta', docName: 'beta', anchor: null },
{ kind: 'doc', id: 'delta', docName: 'delta', anchor: null },
{ kind: 'doc', id: 'gamma', docName: 'gamma', anchor: null },
]);
expect(oneHop.links).toContainEqual({ source: 'alpha', target: 'beta' });
expect(oneHop.links).toContainEqual({ source: 'beta', target: 'gamma' });
expect(oneHop.links).toContainEqual({ source: 'beta', target: 'delta' });
expect(oneHop.links).toHaveLength(3);
const twoHop = index.getLinkGraphNeighborhood('beta', 2);
expect(twoHop.nodes).toEqual([
{ kind: 'doc', id: 'alpha', docName: 'alpha', anchor: null },
{ kind: 'doc', id: 'beta', docName: 'beta', anchor: null },
{ kind: 'doc', id: 'delta', docName: 'delta', anchor: null },
{ kind: 'doc', id: 'epsilon', docName: 'epsilon', anchor: null },
{ kind: 'doc', id: 'gamma', docName: 'gamma', anchor: null },
]);
expect(twoHop.links).toContainEqual({ source: 'gamma', target: 'epsilon' });
expect(twoHop.links).toHaveLength(4);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('getLinkGraphNeighborhood includes external neighbors with labels', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-linkgraph-neighborhood-external-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('alpha', 'See [Docs](https://example.com/docs).');
index.updateDocumentFromMarkdown('beta', '[[alpha]]');
const neighborhood = index.getLinkGraphNeighborhood('alpha', 1);
expect(neighborhood.nodes).toEqual([
{ kind: 'doc', id: 'alpha', docName: 'alpha', anchor: null },
{ kind: 'doc', id: 'beta', docName: 'beta', anchor: null },
{
kind: 'external',
id: 'external:https://example.com/docs',
url: 'https://example.com/docs',
label: 'Docs',
},
]);
expect(neighborhood.links).toContainEqual({
source: 'alpha',
target: 'external:https://example.com/docs',
});
expect(neighborhood.links).toContainEqual({ source: 'beta', target: 'alpha' });
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
});
describe('BacklinkIndex structural skill-bundle edges', () => {
const SKILL = '.ok/skills/demo/SKILL';
const REF = '.ok/skills/demo/references/notes';
test('IN-PLACE bundles (editor-dir shapes) draw the same structural edges', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-inplace-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
const skill = '.agents/skills/demo/SKILL';
const ref = '.agents/skills/demo/references/notes';
index.updateDocumentFromMarkdown(skill, 'See `references/notes.md`.\n');
index.updateDocumentFromMarkdown(ref, '# Notes\n\nNo links.\n');
expect(index.getForwardLinks(skill)).toEqual([ref]);
expect(index.getBacklinks(ref)).toEqual([{ source: skill, anchor: null, snippet: null }]);
const otherRef = '.claude/skills/demo/references/other';
index.updateDocumentFromMarkdown(otherRef, 'Standalone.\n');
expect(index.getForwardLinks(skill)).toEqual([ref]);
expect(index.getForwardLinks(otherRef)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('/skill-name refs draw same-scope edges to the referenced SKILL doc, both directions', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-refs-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
const analyze = '.agents/skills/analyze/SKILL';
const research = '.agents/skills/research/SKILL';
index.updateDocumentFromMarkdown(analyze, 'For reports use `/research` or /research.\n');
expect(index.getForwardLinks(analyze)).toEqual([]);
index.updateDocumentFromMarkdown(research, '# Research skill\n');
expect(index.getForwardLinks(analyze)).toEqual([research]);
expect(index.getBacklinks(research)).toEqual([
{ source: analyze, anchor: null, snippet: null },
]);
index.updateDocumentFromMarkdown(analyze, 'Files under /tmp and half/way.\n');
expect(index.getForwardLinks(analyze)).toEqual([]);
index.registerGlobalSkillBundleNode('__skill__/global/deploy/SKILL');
index.updateDocumentFromMarkdown(analyze, 'Use /deploy.\n');
expect(index.getForwardLinks(analyze)).toEqual([]);
index.updateDocumentFromMarkdown(analyze, 'Use /research.\n');
expect(index.getForwardLinks(analyze)).toEqual([research]);
index.deleteDocument(research);
expect(index.getForwardLinks(analyze)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('connects a SKILL doc and its reference with NO authored link between them', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-struct-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(SKILL, 'See `references/notes.md` for detail.\n');
index.updateDocumentFromMarkdown(REF, '# Notes\n\nStandalone body, no links.\n');
expect(index.getBacklinks(REF)).toEqual([{ source: SKILL, anchor: null, snippet: null }]);
expect(index.getBacklinks(SKILL)).toEqual([{ source: REF, anchor: null, snippet: null }]);
expect(index.getForwardLinks(SKILL)).toEqual([REF]);
expect(index.getForwardLinks(REF)).toEqual([SKILL]);
expect(index.getBacklinkCount(REF)).toBe(1);
const neighborhood = index.getLinkGraphNeighborhood(SKILL, 1);
expect(new Set(neighborhood.nodes.map((n) => n.id))).toEqual(new Set([REF, SKILL]));
expect(neighborhood.links).toContainEqual({ source: SKILL, target: REF });
expect(neighborhood.links).toHaveLength(1);
expect(index.getOrphans([SKILL, REF])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('a wiki-link reference still works (no regression, no duplicate edge)', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-wiki-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(SKILL, 'See [[references/notes]].\n');
index.updateDocumentFromMarkdown(REF, '# Notes\n');
expect(index.getForwardLinks(SKILL)).toEqual([REF]);
const backlinks = index.getBacklinks(REF);
expect(backlinks).toHaveLength(1);
expect(backlinks[0]?.source).toBe(SKILL);
expect(backlinks[0]?.snippet).toBe('See references/notes.');
const neighborhood = index.getLinkGraphNeighborhood(SKILL, 1);
expect(neighborhood.links).toEqual([{ source: SKILL, target: REF }]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('NON-skill docs sharing a normal folder are NOT auto-connected (scope control)', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-nonskill-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown('notes/alpha', '# Alpha\n');
index.updateDocumentFromMarkdown('notes/beta', '# Beta\n');
index.updateDocumentFromMarkdown('notes/references/x', '# X\n');
expect(index.getBacklinks('notes/beta')).toEqual([]);
expect(index.getForwardLinks('notes/alpha')).toEqual([]);
expect(index.getBacklinks('notes/references/x')).toEqual([]);
expect(index.getOrphans(['notes/alpha', 'notes/beta', 'notes/references/x'])).toEqual([
'notes/alpha',
'notes/beta',
'notes/references/x',
]);
const neighborhood = index.getLinkGraphNeighborhood('notes/alpha', 2);
expect(neighborhood.links).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('scripts/** and cross-skill refs do not draw structural edges', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-scope2-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(SKILL, '# Demo\n');
index.updateDocumentFromMarkdown('.ok/skills/demo/scripts/run', '# run\n');
index.updateDocumentFromMarkdown('.ok/skills/other/references/notes', '# other\n');
expect(index.getForwardLinks(SKILL)).toEqual([]);
expect(index.getBacklinks(SKILL)).toEqual([]);
expect(index.getBacklinks('.ok/skills/other/references/notes')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('deleting a reference removes the structural edge', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-del-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(SKILL, '# Demo\n');
index.updateDocumentFromMarkdown(REF, '# Notes\n');
expect(index.getForwardLinks(SKILL)).toEqual([REF]);
index.deleteDocument(REF);
expect(index.getForwardLinks(SKILL)).toEqual([]);
expect(index.getBacklinks(SKILL)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('renaming a reference moves the structural edge to the new name', () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-skill-ren-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
const REF2 = '.ok/skills/demo/references/renamed';
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.updateDocumentFromMarkdown(SKILL, '# Demo\n');
index.updateDocumentFromMarkdown(REF, '# Notes\n');
expect(index.getForwardLinks(SKILL)).toEqual([REF]);
index.renameDocument(REF, REF2, '# Notes\n');
expect(index.getForwardLinks(SKILL)).toEqual([REF2]);
expect(index.getBacklinks(REF2)).toEqual([{ source: SKILL, anchor: null, snippet: null }]);
expect(index.getBacklinks(REF)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
});
describe('BacklinkIndex GLOBAL structural skill-bundle edges', () => {
const G_SKILL = '__skill__/global/demo';
const G_REF = '__skill__/global/demo/references/notes';
function makeIndex(): { index: BacklinkIndex; projectDir: string } {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-gskill-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
return { index: new BacklinkIndex({ projectDir, contentDir }), projectDir };
}
test('connects a global SKILL doc and its reference via the structural edge', () => {
const { index, projectDir } = makeIndex();
try {
index.registerGlobalSkillBundleNode(G_SKILL);
index.registerGlobalSkillBundleNode(G_REF);
expect(index.getBacklinks(G_REF)).toEqual([{ source: G_SKILL, anchor: null, snippet: null }]);
expect(index.getBacklinks(G_SKILL)).toEqual([{ source: G_REF, anchor: null, snippet: null }]);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
expect(index.getForwardLinks(G_REF)).toEqual([G_SKILL]);
expect(index.getBacklinkCount(G_REF)).toBe(1);
const { nodes, links } = index.getLinkGraph();
expect(new Set(nodes.map((n) => n.id))).toEqual(new Set([G_SKILL, G_REF]));
expect(links).toContainEqual({ source: G_SKILL, target: G_REF });
expect(links).toHaveLength(1);
const neighborhood = index.getLinkGraphNeighborhood(G_SKILL, 1);
expect(neighborhood.links).toContainEqual({ source: G_SKILL, target: G_REF });
expect(index.getOrphans([G_SKILL, G_REF])).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('NEGATIVE CONTROL: a global reference body NEVER links into the project KB', () => {
const { index, projectDir } = makeIndex();
try {
index.updateDocumentFromMarkdown('architecture', '# Architecture\n');
index.registerGlobalSkillBundleNode(G_SKILL);
index.updateDocumentFromMarkdown(G_REF, 'See [[architecture]] and [[notes2]].\n');
expect(index.getBacklinks('architecture')).toEqual([]);
expect(index.getForwardLinks(G_REF)).toEqual([G_SKILL]);
expect(index.getBacklinks('notes2')).toEqual([]);
index.updateDocumentFromMarkdown(G_SKILL, 'Body links [[architecture]].\n');
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
expect(index.getBacklinks('architecture')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('deleting / renaming a global reference moves the structural edge', () => {
const { index, projectDir } = makeIndex();
const G_REF2 = '__skill__/global/demo/references/renamed';
try {
index.registerGlobalSkillBundleNode(G_SKILL);
index.registerGlobalSkillBundleNode(G_REF);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
index.renameDocument(G_REF, G_REF2, '# Notes\n');
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF2]);
expect(index.getBacklinks(G_REF)).toEqual([]);
index.deleteDocument(G_REF2);
expect(index.getForwardLinks(G_SKILL)).toEqual([]);
expect(index.getBacklinks(G_SKILL)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('global and project bundles of the same name never cross-connect', () => {
const { index, projectDir } = makeIndex();
try {
index.updateDocumentFromMarkdown('.ok/skills/demo/SKILL', '# Project demo\n');
index.updateDocumentFromMarkdown('.ok/skills/demo/references/notes', '# Project notes\n');
index.registerGlobalSkillBundleNode(G_SKILL);
index.registerGlobalSkillBundleNode(G_REF);
expect(index.getForwardLinks('.ok/skills/demo/SKILL')).toEqual([
'.ok/skills/demo/references/notes',
]);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
expect(index.getBacklinks(G_REF)).toEqual([{ source: G_SKILL, anchor: null, snippet: null }]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('ingestGlobalSkillBundles registers SKILL + references from disk (idempotent)', async () => {
const { index, projectDir } = makeIndex();
const homeSkills = join(projectDir, 'home', '.ok', 'skills');
const demoDir = join(homeSkills, 'demo');
mkdirSync(join(demoDir, 'references', 'sub'), { recursive: true });
writeFileSync(join(demoDir, 'SKILL.md'), '---\nname: demo\n---\n# Demo\n');
writeFileSync(join(demoDir, 'references', 'notes.md'), '# Notes\n');
writeFileSync(join(demoDir, 'references', 'sub', 'deep.md'), '# Deep\n');
mkdirSync(join(demoDir, 'scripts'), { recursive: true });
writeFileSync(join(demoDir, 'scripts', 'run.sh'), '#!/bin/sh\n');
try {
await index.ingestGlobalSkillBundles([homeSkills]);
const G_REF_DEEP = '__skill__/global/demo/references/sub/deep';
expect(new Set(index.getForwardLinks(G_SKILL))).toEqual(new Set([G_REF, G_REF_DEEP]));
expect(index.getBacklinks(G_REF)).toEqual([{ source: G_SKILL, anchor: null, snippet: null }]);
expect(index.getBacklinks('__skill__/global/demo/scripts/run')).toEqual([]);
await index.ingestGlobalSkillBundles([homeSkills]);
expect(new Set(index.getForwardLinks(G_SKILL))).toEqual(new Set([G_REF, G_REF_DEEP]));
rmSync(join(demoDir, 'references', 'notes.md'));
await index.ingestGlobalSkillBundles([homeSkills]);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF_DEEP]);
expect(index.getBacklinks(G_REF)).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('global nodes survive a content rebuild/reconcile (re-ingest restores them)', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-gskill-rebuild-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
const homeSkills = join(projectDir, 'home', '.ok', 'skills');
const demoDir = join(homeSkills, 'demo');
mkdirSync(join(demoDir, 'references'), { recursive: true });
writeFileSync(join(demoDir, 'SKILL.md'), '# Demo\n');
writeFileSync(join(demoDir, 'references', 'notes.md'), '# Notes\n');
try {
const index = new BacklinkIndex({ projectDir, contentDir });
index.registerGlobalSkillBundleNode(G_SKILL);
index.registerGlobalSkillBundleNode(G_REF);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
await index.rebuildFromDisk();
expect(index.getForwardLinks(G_SKILL)).toEqual([]);
await index.ingestGlobalSkillBundles([homeSkills]);
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
await index.reconcileWithDisk();
expect(index.getForwardLinks(G_SKILL)).toEqual([G_REF]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
});
describe('resolveMarkdownHref', () => {
test('resolves same-directory relative link', () => {
expect(resolveMarkdownHref('./other', 'notes')).toBe('other');
expect(resolveMarkdownHref('./other.md', 'notes')).toBe('other');
});
test('resolves same-directory link without leading dot', () => {
expect(resolveMarkdownHref('sibling.md', 'notes')).toBe('sibling');
});
test('resolves into a subdirectory', () => {
expect(resolveMarkdownHref('./sub/page.md', 'notes')).toBe('sub/page');
expect(resolveMarkdownHref('sub/page', 'notes')).toBe('sub/page');
});
test('resolves parent-relative links', () => {
expect(resolveMarkdownHref('../overview.md', 'folder/page')).toBe('overview');
expect(resolveMarkdownHref('../sibling/other.md', 'folder/page')).toBe('sibling/other');
});
test('strips fragment and query before resolving', () => {
expect(resolveMarkdownHref('./page.md#section', 'notes')).toBe('page');
expect(resolveMarkdownHref('./page.md?q=1#frag', 'notes')).toBe('page');
});
test('returns null for external http/https links', () => {
expect(resolveMarkdownHref('https://example.com', 'notes')).toBeNull();
expect(resolveMarkdownHref('http://example.com/page', 'notes')).toBeNull();
});
test('returns null for mailto and other URI schemes', () => {
expect(resolveMarkdownHref('mailto:[email protected]', 'notes')).toBeNull();
});
test('returns null for protocol-relative URLs', () => {
expect(resolveMarkdownHref('//example.com/page', 'notes')).toBeNull();
});
test('resolves root-absolute paths from the content root', () => {
expect(resolveMarkdownHref('/absolute/path.md', 'notes')).toBe('absolute/path');
});
test('returns null for anchor-only links', () => {
expect(resolveMarkdownHref('#section', 'notes')).toBeNull();
});
test('returns null when escaping content root', () => {
expect(resolveMarkdownHref('../../escape.md', 'folder/page')).toBeNull();
expect(resolveMarkdownHref('../../../way-out.md', 'deep/a/b')).toBeNull();
});
});
describe('extractMarkdownLinksFromMarkdown', () => {
test('extracts relative inline markdown links', () => {
const md = 'See [related](./other.md) for details.';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual<ExtractedWikiLink[]>([
{ target: 'other', anchor: null, snippet: 'See related for details.', line: 0, column: 4 },
]);
});
test('extracts root-absolute markdown links from the content root', () => {
const md = 'See [the guide](/docs/guide.md) for details.';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual<ExtractedWikiLink[]>([
{
target: 'docs/guide',
anchor: null,
snippet: 'See the guide for details.',
line: 0,
column: 4,
},
]);
});
test('extracts multiple markdown links from the same line', () => {
const md = 'See [page A](./a.md) and [page B](./b.md) for more.';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual<ExtractedWikiLink[]>([
{ target: 'a', anchor: null, snippet: 'See page A and page B for more.', line: 0, column: 4 },
{
target: 'b',
anchor: null,
snippet: 'See page A and page B for more.',
line: 0,
column: 15,
},
]);
});
test('resolves links relative to the source doc directory', () => {
const md = 'See [overview](../overview.md).';
expect(extractMarkdownLinksFromMarkdown(md, 'folder/page')).toEqual([
{ target: 'overview', anchor: null, snippet: 'See overview.', line: 0, column: 4 },
]);
});
test('extracts internal links with optional titles', () => {
const md = 'See [overview](./overview.md "Project overview") for details.';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{
target: 'overview',
anchor: null,
snippet: 'See overview for details.',
line: 0,
column: 4,
},
]);
});
test('extracts markdown link anchors', () => {
const md = 'See [install](./guide.md#install) for details.';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{
target: 'guide',
anchor: 'install',
snippet: 'See install for details.',
line: 0,
column: 4,
},
]);
});
test('ignores external links', () => {
const md = 'Visit [example](https://example.com) and [local](./local.md).';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{ target: 'local', anchor: null, snippet: 'Visit example and local.', line: 0, column: 18 },
]);
});
test('ignores image syntax while still extracting sibling links', () => {
const md = 'See  and [docs](./docs.md).';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{
target: 'docs',
anchor: null,
snippet: expect.any(String) as string,
line: 0,
column: 41,
},
]);
});
test('ignores links inside fenced code blocks', () => {
const md = ['See [page](./page.md).', '', '```', '[ignore](./ignore.md)', '```'].join('\n');
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{ target: 'page', anchor: null, snippet: 'See page.', line: 0, column: 4 },
]);
});
test('ignores links inside inline code spans', () => {
const md = 'Use `[skip](./skip.md)` then [real](./real.md).';
expect(extractMarkdownLinksFromMarkdown(md, 'notes')).toEqual([
{
target: 'real',
anchor: null,
snippet: expect.any(String) as string,
line: 0,
column: 27,
},
]);
});
test('does not double-count wiki-links that precede markdown links', () => {
const md = '[[wiki]] links to [markdown](./other.md).';
const mdLinks = extractMarkdownLinksFromMarkdown(md, 'notes');
expect(mdLinks.map((l) => l.target)).toEqual(['other']);
});
test('returns empty array when no internal links present', () => {
expect(extractMarkdownLinksFromMarkdown('Just text.', 'notes')).toEqual([]);
expect(extractMarkdownLinksFromMarkdown('[ext](https://example.com)', 'notes')).toEqual([]);
});
test('offsets link lines by the caller-supplied lineOffset', () => {
expect(extractMarkdownLinksFromMarkdown('Read [the guide](./guide.md).', 'notes', 4)).toEqual([
{ target: 'guide', anchor: null, snippet: 'Read the guide.', line: 4, column: 5 },
]);
});
test('a .md link with a fragment or query keeps its document edge when a file oracle answers its path', () => {
const files = new Set(['notes/Guide.md', 'notes/Help.mdx']);
const md =
'See [g](./Guide.md#intro) and [h](./Help.mdx?v=1).\n\n[r][ref]\n\n[ref]: ./Guide.md#ref';
const edges = extractMarkdownLinksFromMarkdown(md, 'notes/a', 0, {
hasFile: (path) => files.has(path),
});
expect(edges.map((edge) => edge.target)).toEqual(['notes/Guide', 'notes/Help', 'notes/Guide']);
});
});
describe('BacklinkIndex with markdown links', () => {
test('updateDocumentFromMarkdown indexes markdown links alongside wiki links', () => {
const tmpDir = mkdtempSync(join(tmpdir(), 'backlinks-md-'));
try {
const index = new BacklinkIndex({ projectDir: tmpDir, contentDir: tmpDir });
const md = 'See [[wikiTarget]] and [mdTarget](./md-target.md).';
index.updateDocumentFromMarkdown('source', md);
expect(index.getForwardLinks('source')).toContain('wikiTarget');
expect(index.getForwardLinks('source')).toContain('md-target');
expect(index.getBacklinks('wikiTarget').map((b) => b.source)).toContain('source');
expect(index.getBacklinks('md-target').map((b) => b.source)).toContain('source');
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
});
test('rebuildFromDisk indexes markdown links', async () => {
const tmpDir = mkdtempSync(join(tmpdir(), 'backlinks-rebuild-'));
try {
mkdirSync(join(tmpDir, 'docs'), { recursive: true });
writeFileSync(
join(tmpDir, 'source.md'),
'Links to [target](./target.md) and [guide](/docs/guide.md).\n',
'utf-8',
);
writeFileSync(join(tmpDir, 'target.md'), '# Target\n', 'utf-8');
writeFileSync(join(tmpDir, 'docs', 'guide.md'), '# Guide\n', 'utf-8');
const index = new BacklinkIndex({ projectDir: tmpDir, contentDir: tmpDir });
await index.rebuildFromDisk();
expect(index.getBacklinks('target').map((b) => b.source)).toContain('source');
expect(index.getBacklinks('docs/guide').map((b) => b.source)).toContain('source');
expect(index.getForwardLinks('source')).toContain('target');
expect(index.getForwardLinks('source')).toContain('docs/guide');
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
});
test('rebuildFromDisk indexes full, collapsed, and shortcut reference links', async () => {
const tmpDir = mkdtempSync(join(tmpdir(), 'backlinks-reference-rebuild-'));
try {
writeFileSync(
join(tmpDir, 'source.md'),
[
'See [full label][full-ref], [collapsed-ref][], and [shortcut-ref].',
'',
'[full-ref]: ./full-target.md',
'[collapsed-ref]: ./collapsed-target.md',
'[shortcut-ref]: ./shortcut-target.md',
'',
].join('\n'),
'utf-8',
);
for (const target of ['full-target', 'collapsed-target', 'shortcut-target']) {
writeFileSync(join(tmpDir, `${target}.md`), `# ${target}\n`, 'utf-8');
}
const index = new BacklinkIndex({ projectDir: tmpDir, contentDir: tmpDir });
await index.rebuildFromDisk();
const targets = ['collapsed-target', 'full-target', 'shortcut-target'];
expect(index.getForwardLinks('source')).toEqual(targets);
for (const target of targets) {
expect(index.getBacklinks(target)).toEqual([expect.objectContaining({ source: 'source' })]);
}
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
});
test('wiki link wins for same target when both syntaxes link to the same page', () => {
const tmpDir = mkdtempSync(join(tmpdir(), 'backlinks-dedup-'));
try {
const index = new BacklinkIndex({ projectDir: tmpDir, contentDir: tmpDir });
const md = '[[target]] and [text](./target.md).';
index.updateDocumentFromMarkdown('source', md);
const backlinks = index.getBacklinks('target');
expect(backlinks.filter((b) => b.source === 'source')).toHaveLength(1);
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
});
test('indexes external markdown and wiki links for forward links and graph', () => {
const tmpDir = mkdtempSync(join(tmpdir(), 'backlinks-external-'));
try {
const index = new BacklinkIndex({ projectDir: tmpDir, contentDir: tmpDir });
index.updateDocumentFromMarkdown(
'source',
'See [Docs](https://example.com/docs) and [[https://inkeep.com|Inkeep]].',
);
expect(index.getForwardLinkEntries('source')).toEqual([
{
kind: 'external',
url: 'https://example.com/docs',
label: 'Docs',
snippet: 'See Docs and Inkeep.',
},
{
kind: 'external',
url: 'https://inkeep.com',
label: 'Inkeep',
snippet: '…com/docs) and Inkeep.',
},
]);
const graph = index.getLinkGraph();
expect(graph.nodes).toContainEqual({
kind: 'doc',
id: 'source',
docName: 'source',
anchor: null,
});
expect(graph.nodes).toContainEqual({
kind: 'external',
id: 'external:https://example.com/docs',
url: 'https://example.com/docs',
label: 'Docs',
});
expect(graph.links).toContainEqual({
source: 'source',
target: 'external:https://example.com/docs',
});
} finally {
rmSync(tmpDir, { recursive: true, force: true });
}
});
});
describe('reconcileWithDisk', () => {
test('unchanged snapshot files reuse persisted source links without rereading', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-reconcile-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), 'Links to [[beta]].');
writeFileSync(join(contentDir, 'beta.md'), 'No links here.');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
await index.saveToDisk();
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
const diff = await reloaded.reconcileWithDisk();
expect(diff).toEqual({
added: 0,
updated: 0,
deleted: 0,
deletedDocNames: [],
changedDocs: [],
});
expect(reloaded.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'Links to beta.' },
]);
expect(
reloaded.getRenameSourceInventory().find((entry) => entry.docName === 'alpha'),
).toEqual(expect.objectContaining({ wikiTargets: ['beta'] }));
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('changed file is re-parsed on reconcile', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-reconcile-changed-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), 'Links to [[beta]].');
writeFileSync(join(contentDir, 'beta.md'), 'No links here.');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
await index.saveToDisk();
const alphaPath = join(contentDir, 'alpha.md');
writeFileSync(alphaPath, 'Links to [[gamma]].');
const bumped = new Date(statSync(alphaPath).mtimeMs + 2000);
utimesSync(alphaPath, bumped, bumped);
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
const diff = await reloaded.reconcileWithDisk();
expect(diff.updated).toBe(1);
expect(diff.added).toBe(0);
expect(reloaded.getBacklinks('gamma')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'Links to gamma.' },
]);
expect(reloaded.getBacklinks('beta')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('new file is added and deleted file is removed on reconcile', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-reconcile-newdel-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), 'Links to [[beta]].');
writeFileSync(join(contentDir, 'beta.md'), 'No links here.');
const index = new BacklinkIndex({ projectDir, contentDir });
await index.rebuildFromDisk();
await index.saveToDisk();
writeFileSync(join(contentDir, 'gamma.md'), 'Links to [[alpha]].');
rmSync(join(contentDir, 'beta.md'));
const reloaded = new BacklinkIndex({ projectDir, contentDir });
expect(await reloaded.loadFromDisk()).toBe(true);
const diff = await reloaded.reconcileWithDisk();
expect(diff.added).toBe(1);
expect(diff.deleted).toBe(1);
expect(diff.deletedDocNames).toEqual(['beta']);
expect(reloaded.getBacklinks('alpha')).toEqual([
{ source: 'gamma', anchor: null, snippet: 'Links to alpha.' },
]);
expect(reloaded.getForwardLinks('beta')).toEqual([]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
test('cold start (no cache) falls back to full rebuild', async () => {
const projectDir = mkdtempSync(join(tmpdir(), 'ok-backlinks-coldstart-'));
const contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
try {
writeFileSync(join(contentDir, 'alpha.md'), 'Links to [[beta]].');
const index = new BacklinkIndex({ projectDir, contentDir });
const cacheLoaded = await index.loadFromDisk();
expect(cacheLoaded).toBe(false);
await index.rebuildFromDisk();
expect(index.getBacklinks('beta')).toEqual([
{ source: 'alpha', anchor: null, snippet: 'Links to beta.' },
]);
} finally {
rmSync(projectDir, { recursive: true, force: true });
}
});
});
describe('computeBrokenOutboundLinks', () => {
test('returns [] when every outbound link resolves (AC2.1)', () => {
const md = 'See [sibling](./real.md) and [root](/docs/guide.md) and [[Existing]].';
const admitted = new Set(['notes/real', 'docs/guide', 'Existing']);
expect(computeBrokenOutboundLinks(md, 'notes/a', admitted)).toEqual([]);
});
test('a folder oracle exempts wiki and markdown links to existing folders', () => {
const md = 'See [[assets]] and [dir](./assets) and [[missing-folder]].';
const folderExists = (folderPath: string) => folderPath === 'assets';
expect(computeBrokenOutboundLinks(md, 'notes', new Set(), undefined, folderExists)).toEqual<
BrokenOutboundLink[]
>([{ href: '[[missing-folder]]', resolvedTo: 'missing-folder', reason: 'no-such-doc' }]);
});
test('flags the `./`-onto-content-root doubling footgun as no-such-doc (AC2.2)', () => {
const md = 'See [tasks](./wiki/modules/tasks).';
expect(computeBrokenOutboundLinks(md, 'wiki/OVERVIEW', new Set())).toEqual<
BrokenOutboundLink[]
>([
{
href: './wiki/modules/tasks',
resolvedTo: 'wiki/wiki/modules/tasks',
reason: 'no-such-doc',
},
]);
});
test('flags a root-escaping relative link as unresolvable (AC2.3)', () => {
const md = 'Bad [escape](../escape.md).';
expect(computeBrokenOutboundLinks(md, 'readme', new Set())).toEqual<BrokenOutboundLink[]>([
{ href: '../escape.md', resolvedTo: null, reason: 'unresolvable' },
]);
});
test('flags a relative path that pops past the content root as unresolvable', () => {
const md = 'Deep [out](../../way-out.md).';
expect(computeBrokenOutboundLinks(md, 'a/b', new Set())).toEqual<BrokenOutboundLink[]>([
{ href: '../../way-out.md', resolvedTo: null, reason: 'unresolvable' },
]);
});
test('an empty-href markdown construct `[x]()` is not a link (mirrors the indexer)', () => {
expect(computeBrokenOutboundLinks('See [x]() here.', 'notes/a', new Set())).toEqual([]);
});
test('flags a broken wiki-link with the reconstructed [[…]] href (AC2.4)', () => {
const md = 'Missing [[Ghost Page]] reference, and an [[Existing]] one.';
const admitted = new Set(['Existing']);
expect(computeBrokenOutboundLinks(md, 'notes/a', admitted)).toEqual<BrokenOutboundLink[]>([
{ href: '[[Ghost Page]]', resolvedTo: 'Ghost Page', reason: 'no-such-doc' },
]);
});
test('flags a broken `![[doc]]` embed (validated like the index does)', () => {
const md = 'Embed: ![[missing-doc]] here.';
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual<BrokenOutboundLink[]>([
{ href: '[[missing-doc]]', resolvedTo: 'missing-doc', reason: 'no-such-doc' },
]);
});
test('resolves a path-qualified wiki-link (`[[folder/slug|Alias]]`) vault-root, not source-dir-relative', () => {
const md = 'Met [[people/alice-chen|Alice Chen]]; stub [[people/bob-jones|Bob]].';
const admitted = new Set(['people/alice-chen']);
expect(computeBrokenOutboundLinks(md, 'meetings/2026-01-01', admitted)).toEqual<
BrokenOutboundLink[]
>([{ href: '[[people/bob-jones]]', resolvedTo: 'people/bob-jones', reason: 'no-such-doc' }]);
});
test('a bare-name wiki-link resolving to a subfolder doc is not broken; an unresolvable one is', () => {
const md = 'See [[analysis]] and [[nowhere]].';
const admitted = new Set(['research/analysis', 'notes/a']);
expect(computeBrokenOutboundLinks(md, 'notes/a', admitted)).toEqual<BrokenOutboundLink[]>([
{ href: '[[nowhere]]', resolvedTo: 'nowhere', reason: 'no-such-doc' },
]);
});
test.each(['guide', 'Guide', 'runbook'])(
'does not resolve fuzzy [[%s]] against global skill documents',
(target) => {
const global = skillLiveDocName('global', 'guide');
const admitted = new Set([global, `${global}/references/runbook`]);
expect(computeBrokenOutboundLinks(`[[${target}]]`, 'notes/a', admitted)).toEqual([
{ href: `[[${target}]]`, resolvedTo: target, reason: 'no-such-doc' },
]);
},
);
test('keeps explicit global and fuzzy project skill references admitted', () => {
const global = skillLiveDocName('global', 'guide');
const globalReference = `${global}/references/runbook`;
const projectReference = '.agents/skills/project/references/project-guide';
const markdown = `[[${global}]] [[${globalReference}]] [[Project Guide]]`;
expect(
computeBrokenOutboundLinks(markdown, 'notes/a', [global, globalReference, projectReference]),
).toEqual([]);
});
test('markdown document links stay literal when the wiki target resolves fuzzily', () => {
expect(
computeBrokenOutboundLinks('[[guide]] [guide](./guide.md)', 'notes/a', ['archive/guide']),
).toEqual([{ href: './guide.md', resolvedTo: 'notes/guide', reason: 'no-such-doc' }]);
});
test('a dotted-filename document target is not reported broken', () => {
const md = 'See [[acp.daemon]] here.';
const admitted = new Set(['notes/acp.daemon', 'notes/a']);
expect(computeBrokenOutboundLinks(md, 'notes/a', admitted)).toEqual([]);
});
test('wiki asset embeds and dotted non-doc targets produce no broken links', () => {
const md = [
'Embed ![[diagram.png]] and ![[chart.v2.png]].',
'Link [[meeting.pdf]] and [[report.v3.xlsx]].',
].join('\n');
const admitted = new Set(['meeting.pdf', 'notes/a']);
expect(computeBrokenOutboundLinks(md, 'notes/a', admitted)).toEqual([]);
});
test('resolving many wiki links scans the corpus a bounded number of times', () => {
class ScanCountingSet extends Set<string> {
scans = 0;
[Symbol.iterator](): SetIterator<string> {
this.scans += 1;
return super[Symbol.iterator]();
}
}
const admitted = new ScanCountingSet(['research/analysis', 'archive/summary', 'notes/a']);
const md = Array.from({ length: 12 }, (_, i) => `[[analysis]] [[summary]] [[gone-${i}]]`).join(
'\n',
);
const broken = computeBrokenOutboundLinks(md, 'notes/a', admitted);
expect(broken).toHaveLength(12);
expect(admitted.scans).toBeLessThanOrEqual(2);
});
test('skips external URLs, image embeds, and anchors; file links skipped when no oracle is passed', () => {
const md = [
'Web [site](https://example.com/missing).',
'Mail [me](mailto:[email protected]).',
'Asset [pdf](./missing.pdf) and .',
'Image embed ![[missing.png]].',
'Anchor [top](#section).',
].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual([]);
});
test('does not scan links inside fenced or inline code', () => {
const md = [
'Inline `[x](./missing.md)` stays code.',
'```',
'[fenced](./also-missing.md)',
'[[FencedWiki]]',
'```',
].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual([]);
});
test('does not scan the frontmatter region', () => {
const md = ['---', 'title: Has a [fake](./missing.md) in YAML', '---', 'Body only.'].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual([]);
});
test('dedupes repeated identical broken hrefs', () => {
const md = 'First [a](./missing.md), again [b](./missing.md).';
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual<BrokenOutboundLink[]>([
{ href: './missing.md', resolvedTo: 'notes/missing', reason: 'no-such-doc' },
]);
});
test('the markdown and JSX planes of one href each keep their own resolution', () => {
const md = ['See [x](api-spec).', '<Mirror src="api-spec" anchor="dep" />', ''].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set())).toEqual<BrokenOutboundLink[]>([
{ href: 'api-spec', resolvedTo: 'notes/api-spec', reason: 'no-such-doc' },
{ href: 'api-spec', resolvedTo: 'api-spec', reason: 'no-such-doc', sourceForm: 'jsx' },
]);
});
test('treats a self-link to the admitted source doc as valid', () => {
const md = 'See [self](./a.md).';
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set(['notes/a']))).toEqual([]);
});
const fileOracle = (existing: string[]) => {
const set = new Set(existing);
return (p: string) => set.has(p);
};
test('a correct-depth source-file link that exists on disk is clean', () => {
const md = 'Probe in [jacobian.py](../../microreservoir/entk/jacobian.py).';
expect(
computeBrokenOutboundLinks(
md,
'wiki/modules/entk',
new Set(),
fileOracle(['microreservoir/entk/jacobian.py']),
),
).toEqual([]);
});
test('an over-deep source-file link (one extra `../`) is unresolvable — the wiki bug', () => {
const md = 'Probe in [jacobian.py](../../../microreservoir/entk/jacobian.py).';
expect(
computeBrokenOutboundLinks(
md,
'wiki/modules/entk',
new Set(),
fileOracle(['microreservoir/entk/jacobian.py']),
),
).toEqual<BrokenOutboundLink[]>([
{
href: '../../../microreservoir/entk/jacobian.py',
resolvedTo: null,
reason: 'unresolvable',
},
]);
});
test('an in-root file link to a missing file is no-such-file (resolvedTo = the path)', () => {
const md = 'See [data](../data/missing.json).';
expect(
computeBrokenOutboundLinks(md, 'wiki/OVERVIEW', new Set(), fileOracle([]))[0],
).toEqual<BrokenOutboundLink>({
href: '../data/missing.json',
resolvedTo: 'data/missing.json',
reason: 'no-such-file',
});
});
test('a content-root-absolute file link resolves from the root', () => {
const md = 'Config at [pkg](/package.json) and [gone](/nope.json).';
expect(
computeBrokenOutboundLinks(md, 'wiki/modules/cli', new Set(), fileOracle(['package.json'])),
).toEqual<BrokenOutboundLink[]>([
{ href: '/nope.json', resolvedTo: 'nope.json', reason: 'no-such-file' },
]);
});
test('a Markdown link naming no document but an existing or ignored file is judged as that file', () => {
const md = 'See [make](../Makefile), [notice](../ignored/NOTICE) and [gone](../Nope).';
const excluded = new Set(['ignored/NOTICE']);
expect(
computeBrokenOutboundLinks(
md,
'notes/a',
new Set(),
fileOracle(['Makefile']),
() => false,
(path) => excluded.has(path),
),
).toEqual<BrokenOutboundLink[]>([
{ href: '../ignored/NOTICE', resolvedTo: 'ignored/NOTICE', reason: 'excluded' },
{ href: '../Nope', resolvedTo: 'Nope', reason: 'no-such-doc' },
]);
});
test('a Markdown link to a missing document is never satisfied by a file check on its .md path', () => {
const md = 'See [g](./Guide.md) and [h](./Help.mdx).';
expect(
computeBrokenOutboundLinks(
md,
'notes/a',
new Set(['notes/guide', 'notes/help']),
fileOracle(['notes/Guide.md', 'notes/Help.mdx']),
() => false,
() => false,
),
).toEqual<BrokenOutboundLink[]>([
{ href: './Guide.md', resolvedTo: 'notes/Guide', reason: 'no-such-doc' },
{ href: './Help.mdx', resolvedTo: 'notes/Help', reason: 'no-such-doc' },
]);
});
test('a Markdown link to an existing but ignored .md file reports excluded', () => {
const md = 'See [d](./drafts/plan.md) and [g](./Guide.md).';
const excluded = new Set(['notes/drafts/plan.md']);
expect(
computeBrokenOutboundLinks(
md,
'notes/a',
new Set(['notes/guide']),
fileOracle(['notes/Guide.md']),
() => false,
(path) => excluded.has(path),
),
).toEqual<BrokenOutboundLink[]>([
{ href: './drafts/plan.md', resolvedTo: 'notes/drafts/plan.md', reason: 'excluded' },
{ href: './Guide.md', resolvedTo: 'notes/Guide', reason: 'no-such-doc' },
]);
});
test('external URLs and wiki image embeds are not file-validated even with an oracle', () => {
const md = [
'Web [pdf](https://example.com/x.pdf).',
'Embed ![[diagram.png]].',
'Image .',
].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/a', new Set(), fileOracle([]))).toEqual([]);
});
});
describe('extractJsxSrcRefsFromMarkdown', () => {
test('extracts Mirror and Excalidraw src refs as document targets', () => {
const md = [
'# Doc',
'',
'<Mirror src="api-spec" anchor="dep" />',
'<Excalidraw src="/diagrams/board.excalidraw" />',
'',
].join('\n');
const refs = extractJsxSrcRefsFromMarkdown(md, 'notes/index');
expect(refs.map((r) => r.target)).toEqual(['api-spec', 'diagrams/board.excalidraw']);
expect(refs[0]).toEqual(
expect.objectContaining({
anchor: null,
line: 2,
snippet: '<Mirror src="api-spec" anchor="dep" />',
}),
);
});
test('resolves a doc-relative Excalidraw src against the source doc dir', () => {
const refs = extractJsxSrcRefsFromMarkdown(
'<Excalidraw src="board.excalidraw" />\n',
'notes/index',
);
expect(refs.map((r) => r.target)).toEqual(['notes/board.excalidraw']);
});
test('skips refs inside fenced code and inline code', () => {
const md = [
'```mdx',
'<Excalidraw src="/fenced/board.excalidraw" />',
'```',
'Write `<Mirror src="api-spec" anchor="x" />` to mirror.',
'<Mirror src="live-doc" anchor="x" />',
'',
].join('\n');
expect(extractJsxSrcRefsFromMarkdown(md, 'index').map((r) => r.target)).toEqual(['live-doc']);
});
test('skips empty, external-scheme, and contentDir-escaping values', () => {
const md = [
'<Excalidraw src="" />',
'<Excalidraw src="https://example.com/board.excalidraw" />',
'<Mirror src="https://example.com/x" anchor="a" />',
'<Mirror src="mailto:[email protected]" anchor="b" />',
'<Excalidraw src="../../outside.excalidraw" />',
'',
].join('\n');
expect(extractJsxSrcRefsFromMarkdown(md, 'notes/index')).toEqual([]);
});
test('does not read data-src as src', () => {
expect(
extractJsxSrcRefsFromMarkdown('<Mirror data-src="decoy" anchor="x" src="real" />\n', 'index'),
).toEqual([expect.objectContaining({ target: 'real' })]);
});
test('applies the frontmatter line offset', () => {
const refs = extractJsxSrcRefsFromMarkdown(
'<Mirror src="api-spec" anchor="x" />\n',
'index',
4,
);
expect(refs[0]).toEqual(expect.objectContaining({ line: 4 }));
});
test('a >-free line of repeated tag prefixes completes within the complexity budget', () => {
const line = '<Mirror '.repeat(6400);
const startedAt = performance.now();
expect(extractJsxSrcRefsFromMarkdown(line, 'notes/index')).toEqual([]);
expect(computeBrokenOutboundLinks(line, 'notes/index', new Set())).toEqual([]);
expect(performance.now() - startedAt).toBeLessThan(2000);
});
test('a line whose only > is distant and unmatched completes within the complexity budget', () => {
const line = `${'<Mirror '.repeat(6400)}>`;
const startedAt = performance.now();
expect(extractJsxSrcRefsFromMarkdown(line, 'notes/index')).toEqual([]);
expect(computeBrokenOutboundLinks(line, 'notes/index', new Set())).toEqual([]);
expect(performance.now() - startedAt).toBeLessThan(2000);
});
});
describe('BacklinkIndex with JSX src refs', () => {
test('a JSX-src-only document becomes a backlink source for the board', () => {
const index = new BacklinkIndex({ projectDir: '/tmp/x', contentDir: '/tmp/x' });
index.updateDocumentFromMarkdown(
'notes/embeds-only',
'# Embeds\n\n<Excalidraw src="board.excalidraw" />\n',
);
expect(index.getBacklinks('notes/board.excalidraw')).toEqual([
expect.objectContaining({ source: 'notes/embeds-only' }),
]);
expect(index.getForwardLinks('notes/embeds-only')).toEqual(['notes/board.excalidraw']);
});
test('a Mirror-only document becomes a backlink source for the mirrored doc', () => {
const index = new BacklinkIndex({ projectDir: '/tmp/x', contentDir: '/tmp/x' });
index.updateDocumentFromMarkdown('mirror-only', '<Mirror src="api-spec" anchor="dep" />\n');
expect(index.getBacklinks('api-spec')).toEqual([
expect.objectContaining({ source: 'mirror-only' }),
]);
});
test('dead-links: an existing board is exempt, a missing board reports, no oracle stays silent', () => {
const files = new Set<string>();
const makeIndex = (withOracle: boolean) => {
const index = new BacklinkIndex({
projectDir: '/tmp/x',
contentDir: '/tmp/x',
...(withOracle ? { getFileOracle: () => ({ hasFile: (p: string) => files.has(p) }) } : {}),
});
index.updateDocumentFromMarkdown(
'notes/embeds-only',
'<Excalidraw src="board.excalidraw" />\n',
);
return index;
};
files.add('notes/board.excalidraw');
expect(makeIndex(true).getDeadLinks(['notes/embeds-only'])).toEqual([]);
files.clear();
expect(makeIndex(true).getDeadLinks(['notes/embeds-only'])).toEqual([
expect.objectContaining({ target: 'notes/board.excalidraw' }),
]);
expect(makeIndex(false).getDeadLinks(['notes/embeds-only'])).toEqual([]);
});
test('dead-links: a Mirror src naming a missing doc still reports', () => {
const index = new BacklinkIndex({ projectDir: '/tmp/x', contentDir: '/tmp/x' });
index.updateDocumentFromMarkdown('mirror-only', '<Mirror src="ghost-doc" anchor="x" />\n');
expect(index.getDeadLinks(['mirror-only'])).toEqual([
expect.objectContaining({ target: 'ghost-doc' }),
]);
index.updateDocumentFromMarkdown('ghost-doc', '# Now it exists\n');
expect(index.getDeadLinks(['mirror-only', 'ghost-doc'])).toEqual([]);
});
});
describe('computeBrokenOutboundLinks — JSX src refs', () => {
const fileOracle = (existing: string[]) => {
const set = new Set(existing);
return (p: string) => set.has(p);
};
test('a missing board reports no-such-file; an existing board is clean', () => {
const md = '<Excalidraw src="board.excalidraw" />\n';
expect(computeBrokenOutboundLinks(md, 'notes/index', new Set(), fileOracle([]))).toEqual([
{
href: 'board.excalidraw',
resolvedTo: 'notes/board.excalidraw',
reason: 'no-such-file',
sourceForm: 'jsx',
},
]);
expect(
computeBrokenOutboundLinks(
md,
'notes/index',
new Set(),
fileOracle(['notes/board.excalidraw']),
),
).toEqual([]);
});
test('a Mirror src naming a missing doc reports no-such-doc', () => {
const md = '<Mirror src="ghost-doc" anchor="x" />\n';
expect(computeBrokenOutboundLinks(md, 'index', new Set(['api-spec']))).toEqual([
{ href: 'ghost-doc', resolvedTo: 'ghost-doc', reason: 'no-such-doc', sourceForm: 'jsx' },
]);
expect(
computeBrokenOutboundLinks(
md.replace('ghost-doc', 'api-spec'),
'index',
new Set(['api-spec']),
),
).toEqual([]);
});
test('contentDir-escaping and scheme-valued srcs report unresolvable; empty stays silent', () => {
const md = [
'<Excalidraw src="../../escape.excalidraw" />',
'<Excalidraw src="https://example.com/b.excalidraw" />',
'<Mirror src="mailto:[email protected]" anchor="x" />',
'<Excalidraw src="" />',
'',
].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/index', new Set(), fileOracle([]))).toEqual([
{
href: '../../escape.excalidraw',
resolvedTo: null,
reason: 'unresolvable',
sourceForm: 'jsx',
},
{
href: 'https://example.com/b.excalidraw',
resolvedTo: null,
reason: 'unresolvable',
sourceForm: 'jsx',
},
{
href: 'mailto:[email protected]',
resolvedTo: null,
reason: 'unresolvable',
sourceForm: 'jsx',
},
]);
});
test('without a file oracle, board existence is unknowable and stays silent', () => {
expect(
computeBrokenOutboundLinks(
'<Excalidraw src="board.excalidraw" />\n',
'notes/index',
new Set(),
),
).toEqual([]);
});
test('JSX refs inside fences and inline code are not validated', () => {
const md = [
'```mdx',
'<Excalidraw src="fenced.excalidraw" />',
'```',
'Use `<Mirror src="ghost" anchor="x" />` like this.',
'',
].join('\n');
expect(computeBrokenOutboundLinks(md, 'notes/index', new Set(), fileOracle([]))).toEqual([]);
});
});
describe('link target identity across canonically equivalent spellings', () => {
const RENE_NFC = 'People/René';
const RENE_NFD = 'People/René';
const ZOE_NFC = 'People/Zoë';
const ZOE_NFD = 'People/Zoë';
function markdownLinkTo(docName: string): string {
return `[link](/${encodeHrefPath(docName)}.md)`;
}
function createInMemoryIndex(): BacklinkIndex {
return new BacklinkIndex({ projectDir: '/unused', contentDir: '/unused' });
}
test('an NFC markdown link to an NFD document is not dead and its backlink lands on the NFD node', () => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown(RENE_NFD, '# René\n');
index.updateDocumentFromMarkdown('Probe', `See ${markdownLinkTo(RENE_NFC)}.\n`);
expect(index.getDeadLinks(['Probe', RENE_NFD])).toEqual([]);
expect(index.getBacklinks(RENE_NFD).map((entry) => entry.source)).toEqual(['Probe']);
expect(
index
.getLinkGraph()
.nodes.filter((node) => node.docName.normalize('NFC') === RENE_NFC)
.map((node) => node.docName),
).toEqual([RENE_NFD]);
});
test('deleting the document makes the link dead again and re-adding it heals the link', () => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown(RENE_NFD, '# René\n');
index.updateDocumentFromMarkdown('Probe', `See ${markdownLinkTo(RENE_NFC)}.\n`);
expect(index.getDeadLinks(['Probe', RENE_NFD])).toEqual([]);
index.deleteDocument(RENE_NFD);
expect(index.getDeadLinks(['Probe']).map((entry) => entry.target)).toEqual([RENE_NFC]);
expect(index.getBacklinks(RENE_NFD)).toEqual([]);
index.updateDocumentFromMarkdown(RENE_NFD, '# René again\n');
expect(index.getDeadLinks(['Probe', RENE_NFD])).toEqual([]);
expect(index.getBacklinks(RENE_NFD).map((entry) => entry.source)).toEqual(['Probe']);
});
test('an NFD markdown link to an NFC document resolves the same way', () => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown(ZOE_NFC, '# Zoë\n');
index.updateDocumentFromMarkdown('Probe', `See ${markdownLinkTo(ZOE_NFD)}.\n`);
expect(index.getDeadLinks(['Probe', ZOE_NFC])).toEqual([]);
expect(index.getBacklinks(ZOE_NFC).map((entry) => entry.source)).toEqual(['Probe']);
});
test('backlinks requested under an equivalent spelling answer for the stored document', () => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown(RENE_NFD, '# René\n');
index.updateDocumentFromMarkdown('Probe', `See ${markdownLinkTo(RENE_NFD)}.\n`);
expect(index.getBacklinks(RENE_NFC)).toEqual(index.getBacklinks(RENE_NFD));
expect(index.getBacklinks(RENE_NFC).map((entry) => entry.source)).toEqual(['Probe']);
expect(index.getBacklinkCount(RENE_NFC)).toBe(1);
expect(index.getBacklinks('People/Ghost')).toEqual([]);
});
test('a document that appears after the link was indexed heals the link', () => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown('Probe', `See ${markdownLinkTo(RENE_NFC)}.\n`);
expect(index.getDeadLinks(['Probe']).map((entry) => entry.target)).toEqual([RENE_NFC]);
index.updateDocumentFromMarkdown(RENE_NFD, '# René\n');
expect(index.getDeadLinks(['Probe', RENE_NFD])).toEqual([]);
expect(index.getBacklinks(RENE_NFD).map((entry) => entry.source)).toEqual(['Probe']);
});
test.each([
[
'an NFC wiki link',
'an NFD folder index',
'Café'.normalize('NFC'),
`${'Café'.normalize('NFD')}/index`,
],
[
'an NFD wiki link',
'an NFC folder index',
'Café'.normalize('NFD'),
`${'Café'.normalize('NFC')}/index`,
],
[
'an NFC wiki link',
'an NFD folder note',
'Notes/Café'.normalize('NFC'),
`${'Notes/Café'.normalize('NFD')}/${'Café'.normalize('NFD')}`,
],
[
'an NFC wiki link',
'a folder note whose leaf alone is NFD',
'Notes/Café'.normalize('NFC'),
`${'Notes/Café'.normalize('NFC')}/${'Café'.normalize('NFD')}`,
],
])(
'%s follows %s added and deleted after the link, without a rebuild',
(_link, _doc, target, docName) => {
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown('Probe', `See [[${target}]].\n`);
expect(index.getDeadLinks(['Probe']).map((entry) => entry.target)).toEqual([target]);
index.updateDocumentFromMarkdown(docName, '# Café\n');
expect(index.getDeadLinks(['Probe', docName])).toEqual([]);
expect(index.getBacklinks(docName).map((entry) => entry.source)).toEqual(['Probe']);
index.deleteDocument(docName);
expect(index.getDeadLinks(['Probe']).map((entry) => entry.target)).toEqual([target]);
expect(index.getBacklinks(docName)).toEqual([]);
},
);
test('deleting an NFD folder index that an NFC wiki link already resolved to points the link back at its target', () => {
const target = 'Café'.normalize('NFC');
const docName = `${'Café'.normalize('NFD')}/index`;
const index = createInMemoryIndex();
index.updateDocumentFromMarkdown(docName, '# Café\n');
index.updateDocumentFromMarkdown('Probe', `See [[${target}]].\n`);
expect(index.getBacklinks(docName).map((entry) => entry.source)).toEqual(['Probe']);
index.deleteDocument(docName);
expect(index.getDeadLinks(['Probe']).map((entry) => entry.target)).toEqual([target]);
expect(index.getLinkGraph().links.map((link) => `${link.source} -> ${link.target}`)).toEqual([
`Probe -> ${target}`,
]);
});
const DOC_ALPHABET = [
RENE_NFC,
RENE_NFD,
'People/rené',
ZOE_NFC,
ZOE_NFD,
'Notes/README',
'Notes/readme',
'a/b',
'a-b',
'Café'.normalize('NFC'),
`${'Café'.normalize('NFD')}/index`,
`${'Café'.normalize('NFC')}/${'Café'.normalize('NFD')}`,
];
function seededRandom(seed: number): () => number {
let state = seed >>> 0;
return () => {
state = (state + 0x6d2b79f5) >>> 0;
let t = state;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
function pick<T>(random: () => number, items: readonly T[]): T {
return items[Math.floor(random() * items.length)] as T;
}
function randomMarkdown(random: () => number): string {
const lines: string[] = ['# Doc', ''];
const linkCount = Math.floor(random() * 4);
for (let i = 0; i < linkCount; i++) {
const target = pick(random, DOC_ALPHABET);
lines.push(random() < 0.5 ? markdownLinkTo(target) : `[[${target}]]`);
}
return `${lines.join('\n')}\n`;
}
function graphSnapshot(index: BacklinkIndex, liveDocs: ReadonlyMap<string, string>): string {
const admitted = [...liveDocs.keys()].sort();
const graph = index.getLinkGraph();
return JSON.stringify({
deadLinks: index
.getDeadLinks(admitted)
.map((entry) => ({
target: entry.target,
sources: entry.sources
.map((source) => `${source.source}\0${source.sourceForm}\0${source.line}`)
.sort(),
}))
.sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0)),
nodes: graph.nodes.map((node) => node.id).sort(),
links: graph.links.map((link) => `${link.source} -> ${link.target}`).sort(),
backlinks: admitted.map((docName) => [
docName,
index
.getBacklinks(docName)
.map((entry) => entry.source)
.sort(),
]),
});
}
test('an incrementally maintained graph equals a fresh rebuild over the same documents', () => {
for (let seed = 1; seed <= 40; seed++) {
const random = seededRandom(seed);
const incremental = createInMemoryIndex();
const liveDocs = new Map<string, string>();
for (let step = 0; step < 12; step++) {
const docName = pick(random, DOC_ALPHABET);
if (liveDocs.has(docName) && random() < 0.4) {
liveDocs.delete(docName);
incremental.deleteDocument(docName);
} else {
const markdown = randomMarkdown(random);
liveDocs.set(docName, markdown);
incremental.updateDocumentFromMarkdown(docName, markdown);
}
const fresh = createInMemoryIndex();
for (const name of [...liveDocs.keys()].sort()) {
fresh.updateDocumentFromMarkdown(name, liveDocs.get(name) as string);
}
expect(graphSnapshot(incremental, liveDocs), `seed ${seed} step ${step}`).toBe(
graphSnapshot(fresh, liveDocs),
);
}
}
});
});
describe('computeBrokenOutboundLinks across canonically equivalent spellings', () => {
const RENE_NFC = 'People/René';
const RENE_NFD = 'People/René';
test('a markdown href in either normalization form names the admitted document', () => {
const toNfc = `[x](/${encodeHrefPath(RENE_NFC)}.md)\n`;
const toNfd = `[x](/${encodeHrefPath(RENE_NFD)}.md)\n`;
expect(computeBrokenOutboundLinks(toNfc, 'Probe', new Set([RENE_NFD]))).toEqual([]);
expect(computeBrokenOutboundLinks(toNfd, 'Probe', new Set([RENE_NFC]))).toEqual([]);
expect(
computeBrokenOutboundLinks(toNfc, 'Probe', createTargetNamespace('document', [RENE_NFD])),
).toEqual([]);
expect(computeBrokenOutboundLinks(`[[${RENE_NFC}]]\n`, 'Probe', new Set([RENE_NFD]))).toEqual(
[],
);
expect(
computeBrokenOutboundLinks('[x](/People/Nope.md)\n', 'Probe', new Set([RENE_NFD])),
).toEqual([{ href: '/People/Nope.md', resolvedTo: 'People/Nope', reason: 'no-such-doc' }]);
});
});