Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { describe, expect, test } from 'vitest';
import {
extractLocalTargetOccurrences,
type LocalTargetOccurrence,
} from './local-target-occurrences.ts';
function assertByteExact(source: string, occurrences: LocalTargetOccurrence[]): void {
for (const occ of occurrences) {
const slice = source.slice(occ.range.start, occ.range.end);
expect(slice.length).toBeGreaterThan(0);
if (occ.sourceForm !== 'markdown-reference') {
expect(slice).toContain(occ.href);
}
switch (occ.sourceForm) {
case 'markdown-inline':
case 'markdown-reference':
expect(slice.startsWith('[') || slice.startsWith(' now.';
const [occ, ...rest] = extractLocalTargetOccurrences(md);
expect(rest).toEqual([]);
expect(occ).toMatchObject({ role: 'link', sourceForm: 'markdown-inline', href: './guide.md' });
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('[the doc](./guide.md)');
expect(occ?.line).toBe(0);
expect(occ?.column).toBe(4);
});
test('inline markdown image', () => {
const md = '';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ).toMatchObject({
role: 'image',
sourceForm: 'markdown-inline',
href: './diagram.png',
});
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('');
expect(occ?.column).toBe(0);
});
test('angle-wrapped destination is unwrapped in href but the range covers the angles', () => {
const md = '[doc](<./my file.md>)';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ?.href).toBe('./my file.md');
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('[doc](<./my file.md>)');
});
test('root-relative and parent-relative paths are admitted', () => {
const md = '[a](/root/file.md) and [b](../sibling/file.md)';
const occ = extractLocalTargetOccurrences(md);
expect(occ.map((o) => o.href)).toEqual(['/root/file.md', '../sibling/file.md']);
});
test('a badge link emits both the outer link and nested image with exact ranges', () => {
const md = '[](./target.md)';
const occurrences = extractLocalTargetOccurrences(md);
expect(occurrences.map(({ role, href }) => [role, href])).toEqual([
['link', './target.md'],
['image', './badge.png'],
]);
expect(md.slice(occurrences[0]?.range.start, occurrences[0]?.range.end)).toBe(md);
expect(md.slice(occurrences[1]?.range.start, occurrences[1]?.range.end)).toBe(
'',
);
});
});
describe('admitted HTML img forms', () => {
test('bare void HTML img', () => {
const md = 'Before <img src="./photo.png"> after';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ).toMatchObject({ role: 'image', sourceForm: 'html-img', href: './photo.png' });
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('<img src="./photo.png">');
});
test('self-closing HTML img', () => {
const md = '<img src="./photo.png" alt="p" />';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ).toMatchObject({ role: 'image', sourceForm: 'html-img', href: './photo.png' });
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('<img src="./photo.png" alt="p" />');
});
});
describe('admitted wiki forms', () => {
test('wiki link and wiki embed', () => {
const md = 'A [[Some Page]] and an embed ![[photo.png]] here';
const occ = extractLocalTargetOccurrences(md);
expect(occ.map((o) => [o.role, o.sourceForm, o.href])).toEqual([
['link', 'wiki-link', 'Some Page'],
['image', 'wiki-embed', 'photo.png'],
]);
expect(md.slice(occ[0]?.range.start, occ[0]?.range.end)).toBe('[[Some Page]]');
expect(md.slice(occ[1]?.range.start, occ[1]?.range.end)).toBe('![[photo.png]]');
});
});
describe('reference-style forms map every use to one definition', () => {
test('full, collapsed, and shortcut uses resolve to the shared definition', () => {
const md = [
'Full [see one][doc].',
'Collapsed [doc][].',
'Shortcut [doc].',
'',
'[doc]: ./manual.pdf',
].join('\n');
const occ = extractLocalTargetOccurrences(md);
expect(occ.map((o) => o.reference?.kind)).toEqual(['full', 'collapsed', 'shortcut']);
expect(occ.every((o) => o.href === './manual.pdf')).toBe(true);
const defs = new Set(occ.map((o) => o.reference?.definition));
expect(defs.size).toBe(1);
});
test('the shared definition repair range bounds the destination token', () => {
const md = '[a][doc]\n\n[doc]: ./manual.pdf';
const [occ] = extractLocalTargetOccurrences(md);
const repair = occ?.reference?.definition.repairRange;
expect(md.slice(repair?.start, repair?.end)).toBe('./manual.pdf');
});
test('every authored use keeps its own occurrence range', () => {
const md = '[first][doc] then [second][doc]\n\n[doc]: ./x.pdf';
const occ = extractLocalTargetOccurrences(md);
expect(md.slice(occ[0]?.range.start, occ[0]?.range.end)).toBe('[first][doc]');
expect(md.slice(occ[1]?.range.start, occ[1]?.range.end)).toBe('[second][doc]');
expect(occ[0]?.reference?.definition).toBe(occ[1]?.reference?.definition);
});
test('reference resolution is case-insensitive and whitespace-collapsed', () => {
const md = '[link][My Ref]\n\n[my ref]: ./target.md';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ?.href).toBe('./target.md');
expect(occ?.reference?.label).toBe('my ref');
});
test('reference resolution applies CommonMark Unicode case folding', () => {
const [occ] = extractLocalTargetOccurrences('[link][ẞ]\n\n[SS]: ./target.md');
expect(occ?.href).toBe('./target.md');
});
test('reference-style image', () => {
const md = '![alt][img]\n\n[img]: ./picture.png';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ).toMatchObject({
role: 'image',
sourceForm: 'markdown-reference',
href: './picture.png',
});
});
test('a reference use with no matching definition is not a link and is not emitted', () => {
expect(extractLocalTargetOccurrences('[text][missing] and [alsoMissing].')).toEqual([]);
});
test('the definition line itself yields no occurrence', () => {
expect(extractLocalTargetOccurrences('[doc]: ./only-a-definition.pdf')).toEqual([]);
});
test('an external definition destination is not emitted as a local target', () => {
expect(extractLocalTargetOccurrences('[x][ext]\n\n[ext]: https://example.com')).toEqual([]);
});
test('a destination continued onto the next line is recognized with an exact repair range', () => {
const md = '[manual][ref]\n\n[ref]:\n <./manual file.pdf>\n';
const [occurrence] = extractLocalTargetOccurrences(md);
expect(occurrence?.href).toBe('./manual file.pdf');
expect(occurrence?.reference?.definition.line).toBe(2);
const repairRange = occurrence?.reference?.definition.repairRange;
expect(md.slice(repairRange?.start, repairRange?.end)).toBe('<./manual file.pdf>');
});
test('a title continued onto the next line remains part of one definition block', () => {
const md = '[manual][ref]\n\n[ref]: ./manual.pdf\n "Manual"\n';
const occurrences = extractLocalTargetOccurrences(md);
expect(occurrences).toHaveLength(1);
expect(occurrences[0]?.href).toBe('./manual.pdf');
});
});
describe('context exclusions produce no false local targets', () => {
test('frontmatter is excluded', () => {
const md = ['---', 'cover: [x](./in-frontmatter.md)', '---', '[real](./body.md)'].join('\n');
const occ = extractLocalTargetOccurrences(md);
expect(occ.map((o) => o.href)).toEqual(['./body.md']);
});
test('fenced code blocks are excluded (backtick and tilde)', () => {
const md = [
'```',
'[x](./in-backtick-fence.md)',
'```',
'~~~',
'[y](./in-tilde-fence.md)',
'~~~',
'[real](./body.md)',
].join('\n');
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
test('inline code is excluded', () => {
const md = 'Type `[x](./in-code.md)` but link [real](./body.md).';
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
test('a backslash-escaped opener is excluded', () => {
const md = '\\[not a link](./escaped.md) but [real](./body.md)';
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
test('indented code is excluded', () => {
const md = ' \n\t[x](./tabbed.pdf)\n[real](./body.md)';
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
test('HTML comments are excluded across and within lines', () => {
const md = [
'<!--  --> [real](./body.md)',
'<!--',
'[ref]: ./comment.pdf',
'',
'-->',
'[ref]',
].join('\n');
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
test('an HTML opener inside inline code does not mask a trailing real link', () => {
const md = '`<!--` [real](./body.md) and `<pre>` [also](./other.md)';
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual([
'./body.md',
'./other.md',
]);
});
test('raw pre and code regions are excluded, including inline regions', () => {
const md = [
'<pre></pre> [real](./body.md)',
'<code>',
'[code](./code.pdf)',
'</code>',
].join('\n');
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./body.md']);
});
});
describe('href classification excludes non-local targets', () => {
test('external URLs (any scheme, protocol-relative) are excluded', () => {
const md = [
'[a](https://example.com)',
'[b](http://example.com/x)',
'[c](mailto:[email protected])',
'[d](//cdn.example.com/x.png)',
'<img src="https://example.com/x.png">',
'[[https://example.com]]',
'[keep](./local.md)',
].join('\n');
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./local.md']);
});
test('bare anchors are excluded', () => {
const md = '[section](#heading) but [doc](./page.md#heading) is local';
expect(extractLocalTargetOccurrences(md).map((o) => o.href)).toEqual(['./page.md#heading']);
});
test('a traversal-escaping path is still captured for downstream assessment, not silently dropped', () => {
const md = '[x](../../../../etc/passwd)';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ?.href).toBe('../../../../etc/passwd');
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('[x](../../../../etc/passwd)');
});
});
describe('positions fold in frontmatter and CRLF exactly', () => {
test('line numbers count frontmatter lines and ranges stay byte-exact', () => {
const md = ['---', 'title: x', '---', '', 'Body [doc](./guide.md).'].join('\n');
const [occ] = extractLocalTargetOccurrences(md);
expect(occ?.line).toBe(4);
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('[doc](./guide.md)');
});
test('CRLF documents keep exact byte ranges', () => {
const md = 'Line one\r\n\r\nLine three';
const [occ] = extractLocalTargetOccurrences(md);
expect(occ?.line).toBe(1);
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('');
});
test('a CRLF frontmatter block offsets the body range correctly', () => {
const md = '---\r\ntitle: x\r\n---\r\n[doc](./guide.md)';
const [occ] = extractLocalTargetOccurrences(md);
expect(md.slice(occ?.range.start, occ?.range.end)).toBe('[doc](./guide.md)');
});
});
describe('mixed corpus byte-preservation invariant', () => {
test('every emitted occurrence and repair range reproduces its authored bytes', () => {
const md = [
'---',
'title: Mixed',
'---',
'# Heading',
'',
'An inline [link](./a.md) and image .',
'HTML <img src="./c.png"> and self-closing <img src="./d.png"/>.',
'Wiki [[Some Doc]] and embed ![[e.png]].',
'Reference [use][ref] and [ref][] and [ref] shortcut.',
'',
'[ref]: ./f.pdf "a title"',
'',
'```',
'[ignored](./g.md)',
'```',
].join('\n');
const occurrences = extractLocalTargetOccurrences(md);
expect(occurrences).toHaveLength(9);
assertByteExact(md, occurrences);
for (const occ of occurrences) {
if (occ.reference) {
const { start, end } = occ.reference.definition.repairRange;
expect(md.slice(start, end)).toBe('./f.pdf');
}
}
expect(occurrences.some((o) => o.href.includes('g.md'))).toBe(false);
});
});