Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
mkdirSync,
readFileSync,
realpathSync,
renameSync,
statSync,
symlinkSync,
unlinkSync,
writeFileSync,
} from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { statMtime } from '@inkeep/open-knowledge-core/server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { createContentFilter } from './content-filter.ts';
import type { DiskEvent } from './file-watcher';
import {
classifyEvents,
contentHash,
evictStaleTrackerEntries,
type FileIndexEntry,
getWatcherDecisionRingSnapshot,
handleRawEvents,
isSelfRemoval,
isSelfWrite,
lastKnownHash,
pathToDocName,
reconcileFileIndexAfterFilterRebuild,
registerRemoval,
registerWrite,
removalTracker,
resetWatcherDecisionDiagnostics,
retractRemoval,
startWatcher,
toParcelIgnorePaths,
updateFileIndex,
updateLastKnownHash,
writeTracker,
} from './file-watcher';
import { getLogger } from './logger.ts';
describe('writeTracker', () => {
beforeEach(() => {
writeTracker.clear();
});
test('skips self-writes with matching hash', () => {
const filePath = '/content/test-fixture.md';
const content = '# Hello\n\nWorld\n';
const hash = contentHash(content);
registerWrite(filePath, hash);
const queue = writeTracker.get(filePath);
expect(queue).toBeTruthy();
expect(queue?.some((e) => e.hash === hash)).toBe(true);
});
test('does not skip external writes with different hash', () => {
const filePath = '/content/test-fixture.md';
const ourContent = '# Hello\n\nWorld\n';
const externalContent = '# Hello\n\nExternal edit\n';
registerWrite(filePath, contentHash(ourContent));
const externalHash = contentHash(externalContent);
const queue = writeTracker.get(filePath);
expect(queue?.some((e) => e.hash === externalHash)).toBe(false);
});
test('does not skip writes when no tracked entry exists', () => {
const filePath = '/content/new-file.md';
expect(writeTracker.has(filePath)).toBe(false);
});
test('queue handles multiple rapid writes — each event consumes only its own entry', () => {
const filePath = '/content/test-fixture.md';
const hash1 = contentHash('write 1');
const hash2 = contentHash('write 2');
registerWrite(filePath, hash1);
registerWrite(filePath, hash2);
const queue = writeTracker.get(filePath);
expect(queue).toHaveLength(2);
const idx1 = queue?.findIndex((e) => e.hash === hash1) ?? -1;
expect(idx1).toBeGreaterThanOrEqual(0);
queue?.splice(idx1, 1);
expect(queue).toHaveLength(1);
expect(queue?.[0].hash).toBe(hash2);
});
});
describe('TTL eviction', () => {
beforeEach(() => {
writeTracker.clear();
});
test('evicts entries older than TTL (10s)', () => {
const filePath = '/content/stale.md';
writeTracker.set(filePath, [{ hash: 'abc123', timestamp: Date.now() - 11_000 }]);
evictStaleTrackerEntries();
expect(writeTracker.has(filePath)).toBe(false);
});
test('keeps entries within TTL', () => {
const filePath = '/content/fresh.md';
writeTracker.set(filePath, [{ hash: 'abc123', timestamp: Date.now() - 5_000 }]);
evictStaleTrackerEntries();
expect(writeTracker.has(filePath)).toBe(true);
});
test('mixed: evicts stale, keeps fresh', () => {
writeTracker.set('/content/stale.md', [{ hash: 'old', timestamp: Date.now() - 15_000 }]);
writeTracker.set('/content/fresh.md', [{ hash: 'new', timestamp: Date.now() - 2_000 }]);
evictStaleTrackerEntries();
expect(writeTracker.has('/content/stale.md')).toBe(false);
expect(writeTracker.has('/content/fresh.md')).toBe(true);
});
test('evicts stale entries within a queue while keeping fresh ones', () => {
writeTracker.set('/content/mixed.md', [
{ hash: 'old', timestamp: Date.now() - 15_000 },
{ hash: 'new', timestamp: Date.now() - 2_000 },
]);
evictStaleTrackerEntries();
const queue = writeTracker.get('/content/mixed.md');
expect(queue).toHaveLength(1);
expect(queue?.[0].hash).toBe('new');
});
});
describe('pathToDocName', () => {
test('maps absolute path to document name', () => {
expect(pathToDocName('/app/content/test-fixture.md', '/app/content')).toBe('test-fixture');
});
test('handles nested paths', () => {
expect(pathToDocName('/app/content/docs/guide.md', '/app/content')).toBe('docs/guide');
});
test('strips .mdx extension', () => {
expect(pathToDocName('/app/content/component.mdx', '/app/content')).toBe('component');
});
test('strips .mdx from nested paths', () => {
expect(pathToDocName('/app/content/docs/guide.mdx', '/app/content')).toBe('docs/guide');
});
});
describe('contentHash', () => {
test('produces consistent SHA-256 hex digest', () => {
const hash1 = contentHash('hello');
const hash2 = contentHash('hello');
expect(hash1).toBe(hash2);
expect(hash1).toHaveLength(64);
});
test('different content produces different hashes', () => {
expect(contentHash('hello')).not.toBe(contentHash('world'));
});
});
describe('isSelfWrite', () => {
beforeEach(() => {
writeTracker.clear();
});
test('returns true and consumes entry for matching hash', () => {
const path = '/content/test.md';
const hash = contentHash('hello');
registerWrite(path, hash);
expect(isSelfWrite(path, hash)).toBe(true);
expect(writeTracker.has(path)).toBe(false);
});
test('returns false for non-matching hash', () => {
const path = '/content/test.md';
registerWrite(path, contentHash('hello'));
expect(isSelfWrite(path, contentHash('world'))).toBe(false);
expect(writeTracker.has(path)).toBe(false);
});
test('a later matching write consumes coalesced registrations before it', () => {
const path = '/content/test.md';
const first = contentHash('first');
const second = contentHash('second');
const third = contentHash('third');
registerWrite(path, first);
registerWrite(path, second);
registerWrite(path, third);
expect(isSelfWrite(path, second)).toBe(true);
expect(writeTracker.get(path)?.map((entry) => entry.hash)).toEqual([third]);
});
});
describe('isSelfRemoval', () => {
let removalDir: string;
beforeEach(async () => {
removalTracker.clear();
removalDir = await mkdtemp(resolve(tmpdir(), 'ok-removal-test-'));
});
afterEach(async () => {
await rm(removalDir, { recursive: true, force: true });
});
test('returns true and consumes the entry for a declared removal', () => {
const filePath = resolve(realpathSync(removalDir), 'declared.md');
writeFileSync(filePath, 'body\n', 'utf-8');
registerRemoval(filePath);
expect(isSelfRemoval(filePath)).toBe(true);
expect(isSelfRemoval(filePath)).toBe(false);
expect(removalTracker.has(filePath)).toBe(false);
});
test('returns false for a path that was never declared', () => {
expect(isSelfRemoval(resolve(realpathSync(removalDir), 'undeclared.md'))).toBe(false);
});
test('keys an aliased doc at the alias the watcher reports, not at its target', () => {
const canonicalDir = realpathSync(removalDir);
const target = resolve(canonicalDir, 'alias-target.md');
const alias = resolve(canonicalDir, 'alias.md');
writeFileSync(target, 'body\n', 'utf-8');
symlinkSync(target, alias);
registerRemoval(alias);
expect(isSelfRemoval(target)).toBe(false);
expect(isSelfRemoval(alias)).toBe(true);
});
test('canonicalises the declared directory so an uncanonical parent still matches', () => {
const filePath = resolve(removalDir, 'uncanonical.md');
writeFileSync(filePath, 'body\n', 'utf-8');
registerRemoval(filePath);
expect(isSelfRemoval(resolve(realpathSync(removalDir), 'uncanonical.md'))).toBe(true);
});
test('returns false once the declaration has aged past the TTL', () => {
const filePath = resolve(realpathSync(removalDir), 'stale.md');
removalTracker.set(filePath, Date.now() - 31_000);
expect(isSelfRemoval(filePath)).toBe(false);
expect(removalTracker.has(filePath)).toBe(false);
});
test('evicts a declaration older than the TTL and keeps a fresh one', () => {
removalTracker.set('/content/stale-removal.md', Date.now() - 31_000);
removalTracker.set('/content/fresh-removal.md', Date.now() - 2_000);
evictStaleTrackerEntries();
expect(removalTracker.has('/content/stale-removal.md')).toBe(false);
expect(removalTracker.has('/content/fresh-removal.md')).toBe(true);
});
test('a declaration still suppresses at an age the watcher is known to deliver at', () => {
const filePath = resolve(realpathSync(removalDir), 'late-delivery.md');
removalTracker.set(filePath, Date.now() - 12_000);
expect(isSelfRemoval(filePath)).toBe(true);
});
test('the eviction sweep keeps a removal declaration the write sweep would drop', () => {
removalTracker.set('/content/late-removal.md', Date.now() - 12_000);
writeTracker.set('/content/late-write.md', [{ hash: 'h', timestamp: Date.now() - 12_000 }]);
evictStaleTrackerEntries();
expect(removalTracker.has('/content/late-removal.md')).toBe(true);
expect(writeTracker.has('/content/late-write.md')).toBe(false);
});
test('a retracted declaration no longer consumes a deletion at that path', () => {
const filePath = resolve(realpathSync(removalDir), 'retracted.md');
writeFileSync(filePath, 'body\n', 'utf-8');
const declaration = registerRemoval(filePath);
retractRemoval(declaration);
expect(isSelfRemoval(filePath)).toBe(false);
});
test('retracting an uncanonical declaration removes the key the watcher would hit', () => {
const filePath = resolve(removalDir, 'retracted-uncanonical.md');
writeFileSync(filePath, 'body\n', 'utf-8');
retractRemoval(registerRemoval(filePath));
expect(isSelfRemoval(resolve(realpathSync(removalDir), 'retracted-uncanonical.md'))).toBe(
false,
);
});
test('an unresolvable removal key is surfaced with its errno instead of being swallowed', () => {
const canonicalDir = realpathSync(removalDir);
const loopA = resolve(canonicalDir, 'loop-a');
const loopB = resolve(canonicalDir, 'loop-b');
symlinkSync(loopB, loopA);
symlinkSync(loopA, loopB);
const underLoop = resolve(loopA, 'note.md');
const warnSpy = vi.spyOn(getLogger('file-watcher'), 'warn');
warnSpy.mockClear();
try {
registerRemoval(resolve(canonicalDir, 'unrelated.md'));
expect(isSelfRemoval(underLoop)).toBe(false);
expect(warnSpy).toHaveBeenCalledWith(
expect.objectContaining({ path: underLoop, code: 'ELOOP' }),
expect.stringContaining('ELOOP'),
);
} finally {
warnSpy.mockRestore();
}
});
test('a declaration keyed by the raw fallback is not matched once the directory resolves again', () => {
const canonicalDir = realpathSync(removalDir);
const loopA = resolve(canonicalDir, 'loop-a');
const loopB = resolve(canonicalDir, 'loop-b');
symlinkSync(loopB, loopA);
symlinkSync(loopA, loopB);
const underLoop = resolve(loopA, 'note.md');
registerRemoval(underLoop);
expect(removalTracker.has(underLoop)).toBe(true);
const realTarget = resolve(canonicalDir, 'real-target');
mkdirSync(realTarget);
unlinkSync(loopA);
symlinkSync(realTarget, loopA);
expect(isSelfRemoval(underLoop)).toBe(false);
});
test('a declared removal is recognised when the watcher reports it through an uncanonical parent', async () => {
const root = realpathSync(removalDir);
const realContent = resolve(root, 'content');
mkdirSync(realContent);
const aliasContent = resolve(root, 'alias');
symlinkSync(realContent, aliasContent);
const filePath = resolve(realContent, 'note.md');
writeFileSync(filePath, '# Note\n', 'utf-8');
registerRemoval(filePath);
await rm(filePath);
const dispatched: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'delete', path: resolve(aliasContent, 'note.md') }],
aliasContent,
undefined,
new Map(),
new Map(),
async (event) => {
dispatched.push(event);
},
);
expect(dispatched).toEqual([]);
});
test('a create batch already in flight cannot void a declaration made after it arrived', async () => {
const contentDir = realpathSync(removalDir);
const filePath = resolve(contentDir, 'in-flight.md');
writeFileSync(filePath, '# In flight\n', 'utf-8');
const inFlight = handleRawEvents(
[{ type: 'create', path: filePath }],
contentDir,
undefined,
new Map(),
new Map(),
async () => {},
);
registerRemoval(filePath);
await inFlight;
unlinkSync(filePath);
const afterOwnRemoval: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'delete', path: filePath }],
contentDir,
undefined,
new Map(),
new Map(),
async (event) => {
afterOwnRemoval.push(event);
},
);
expect(afterOwnRemoval).toEqual([]);
});
test('a declaration whose delete is paired into a rename cannot be spent on a later deletion', async () => {
const contentDir = realpathSync(removalDir);
const source = resolve(contentDir, 'paired-source.md');
const copy = resolve(contentDir, 'paired-copy.md');
const body = '# Paired\n\nBody the copy also carries.\n';
lastKnownHash.clear();
writeFileSync(source, body, 'utf-8');
updateLastKnownHash(source, contentHash(body));
registerRemoval(source);
unlinkSync(source);
writeFileSync(copy, body, 'utf-8');
const paired: DiskEvent[] = [];
await handleRawEvents(
[
{ type: 'delete', path: source },
{ type: 'create', path: copy },
],
contentDir,
undefined,
new Map(),
new Map(),
async (event) => {
paired.push(event);
},
);
expect(paired.map((event) => event.kind)).toEqual(['rename']);
writeFileSync(source, '# Paired\n\nBody the user typed back.\n', 'utf-8');
unlinkSync(source);
const later: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'delete', path: source }],
contentDir,
undefined,
new Map(),
new Map(),
async (event) => {
later.push(event);
},
);
expect(later.map((event) => event.kind)).toEqual(['delete']);
});
});
describe('an outside write in the same batch as an own save', () => {
let batchDir: string;
beforeEach(async () => {
writeTracker.clear();
lastKnownHash.clear();
resetWatcherDecisionDiagnostics();
batchDir = realpathSync(await mkdtemp(resolve(tmpdir(), 'ok-merged-batch-test-')));
});
afterEach(async () => {
await rm(batchDir, { recursive: true, force: true });
});
test('reaches the server as an update carrying the outside bytes when the batch reads as a create', async () => {
const filePath = resolve(batchDir, 'merged.md');
const saved = '# Merged\n\nIntro paragraph.\n';
const outside = '# Merged\n\nIntro paragraph, edited out of band.\n';
writeFileSync(filePath, saved, 'utf-8');
registerWrite(filePath, contentHash(saved));
writeFileSync(filePath, outside, 'utf-8');
const dispatched: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: filePath }],
batchDir,
undefined,
new Map(),
new Map(),
async (event) => {
dispatched.push(event);
},
);
expect(dispatched).toHaveLength(1);
expect(dispatched[0]).toMatchObject({ kind: 'update', docName: 'merged', content: outside });
expect(
getWatcherDecisionRingSnapshot().filter(
(record) => record.decision === 'outside-write-over-own-write',
),
).toMatchObject([{ kind: 'create' }]);
});
test('stays a create when the file was deleted after the own save', async () => {
const filePath = resolve(batchDir, 'recreated.md');
const saved = '# Recreated\n\nIntro paragraph.\n';
const outside = '# Recreated\n\nIntro paragraph, saved again out of band.\n';
writeFileSync(filePath, saved, 'utf-8');
registerWrite(filePath, contentHash(saved));
unlinkSync(filePath);
const dispatched: DiskEvent[] = [];
const dispatch = async (event: DiskEvent) => {
dispatched.push(event);
};
await handleRawEvents(
[{ type: 'delete', path: filePath }],
batchDir,
undefined,
new Map(),
new Map(),
dispatch,
);
writeFileSync(filePath, outside, 'utf-8');
await handleRawEvents(
[{ type: 'create', path: filePath }],
batchDir,
undefined,
new Map(),
new Map(),
dispatch,
);
expect(dispatched.at(-1)).toMatchObject({
kind: 'create',
docName: 'recreated',
content: outside,
});
expect(
getWatcherDecisionRingSnapshot().some(
(record) => record.decision === 'outside-write-over-own-write',
),
).toBe(false);
});
});
describe('classifyEvents', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-watcher-test-'));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('emits update event for modified file', async () => {
const filePath = resolve(contentDir, 'doc.md');
writeFileSync(filePath, '# Updated\n');
const events = await classifyEvents([{ type: 'update', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('update');
if (events[0].kind === 'update') {
expect(events[0].docName).toBe('doc');
expect(events[0].content).toBe('# Updated\n');
}
});
test('emits create event for new file', async () => {
const filePath = resolve(contentDir, 'new.md');
writeFileSync(filePath, '# New\n');
const events = await classifyEvents([{ type: 'create', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('create');
});
test('emits create event for new empty file', async () => {
const filePath = resolve(contentDir, 'empty.md');
writeFileSync(filePath, '');
const events = await classifyEvents([{ type: 'create', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('create');
if (events[0].kind === 'create') {
expect(events[0].docName).toBe('empty');
expect(events[0].content).toBe('');
}
});
test('emits update event when existing file becomes empty', async () => {
const filePath = resolve(contentDir, 'cleared.md');
writeFileSync(filePath, '');
const events = await classifyEvents([{ type: 'update', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('update');
if (events[0].kind === 'update') {
expect(events[0].docName).toBe('cleared');
expect(events[0].content).toBe('');
}
});
test('emits delete event for removed file', async () => {
const filePath = resolve(contentDir, 'gone.md');
const events = await classifyEvents([{ type: 'delete', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('delete');
if (events[0].kind === 'delete') {
expect(events[0].docName).toBe('gone');
}
});
test('emits rename for delete+create with matching content hash', async () => {
const oldPath = resolve(contentDir, 'old-name.md');
const newPath = resolve(contentDir, 'new-name.md');
const content = '# Same Content\n';
updateLastKnownHash(oldPath, contentHash(content));
writeFileSync(newPath, content);
const events = await classifyEvents(
[
{ type: 'delete', path: oldPath },
{ type: 'create', path: newPath },
],
contentDir,
);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('rename');
if (events[0].kind === 'rename') {
expect(events[0].oldDocName).toBe('old-name');
expect(events[0].newDocName).toBe('new-name');
expect(events[0].content).toBe(content);
}
});
test("a new file that reuses a removed file's inode number is not a rename unless its size and time match", async () => {
const removed = resolve(contentDir, 'removed.md');
const external = resolve(contentDir, 'external.md');
updateLastKnownHash(removed, contentHash('# Removed\n'));
writeFileSync(external, '# External, a different file\n');
const reused = statSync(external, { bigint: true });
const indexWith = (size: number, modified: string) =>
new Map<string, FileIndexEntry>([
[
'removed',
{
kind: 'markdown',
canonicalPath: removed,
inode: `${reused.dev}:${reused.ino}`,
size,
modified,
aliases: [],
},
],
]);
const classify = async (index: Map<string, FileIndexEntry>) => {
const collected: DiskEvent[] = [];
await handleRawEvents(
[
{ type: 'delete', path: removed },
{ type: 'create', path: external },
],
contentDir,
undefined,
index,
new Map(),
async (event) => {
collected.push(event);
},
);
return collected.map((event) => event.kind).sort();
};
expect(await classify(indexWith(9, '2020-01-01T00:00:00.000Z'))).toEqual(['create', 'delete']);
updateLastKnownHash(removed, contentHash('# Removed\n'));
lastKnownHash.delete(external);
expect(await classify(indexWith(Number(reused.size), statMtime(reused).toISOString()))).toEqual(
['rename'],
);
});
test('emits separate delete+create when content hashes differ', async () => {
const oldPath = resolve(contentDir, 'old.md');
const newPath = resolve(contentDir, 'new.md');
updateLastKnownHash(oldPath, contentHash('old content'));
writeFileSync(newPath, 'different content');
const events = await classifyEvents(
[
{ type: 'delete', path: oldPath },
{ type: 'create', path: newPath },
],
contentDir,
);
expect(events).toHaveLength(2);
expect(events.some((e) => e.kind === 'delete')).toBe(true);
expect(events.some((e) => e.kind === 'create')).toBe(true);
});
test('emits conflict event when file contains conflict markers', async () => {
const filePath = resolve(contentDir, 'conflicted.md');
writeFileSync(filePath, '<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n');
const events = await classifyEvents([{ type: 'update', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('conflict');
});
test('emits conflict event for create with conflict markers', async () => {
const filePath = resolve(contentDir, 'new-conflicted.md');
writeFileSync(filePath, '<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n');
const events = await classifyEvents([{ type: 'create', path: filePath }], contentDir);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('conflict');
});
test('ignores non-.md files', async () => {
const filePath = resolve(contentDir, 'readme.txt');
writeFileSync(filePath, 'hello');
const events = await classifyEvents([{ type: 'update', path: filePath }], contentDir);
expect(events).toHaveLength(0);
});
test('filters events through ContentFilter when provided', async () => {
writeFileSync(resolve(tmpDir, '.gitignore'), 'dist/\n');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
mkdirSync(resolve(contentDir, 'dist'), { recursive: true });
mkdirSync(resolve(contentDir, 'docs'), { recursive: true });
writeFileSync(resolve(contentDir, 'dist', 'output.md'), '# Build Output\n');
writeFileSync(resolve(contentDir, 'docs', 'guide.md'), '# Guide\n');
const events = await classifyEvents(
[
{ type: 'create', path: resolve(contentDir, 'dist', 'output.md') },
{ type: 'create', path: resolve(contentDir, 'docs', 'guide.md') },
],
contentDir,
filter,
);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('create');
if (events[0].kind === 'create') {
expect(events[0].docName).toBe('docs/guide');
}
});
});
describe('startWatcher file index', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-watcher-index-'));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('initial scan populates file index with .md files', async () => {
writeFileSync(resolve(contentDir, 'readme.md'), '# README\n');
mkdirSync(resolve(contentDir, 'docs'));
writeFileSync(resolve(contentDir, 'docs', 'guide.md'), '# Guide\n');
writeFileSync(resolve(contentDir, 'script.js'), 'console.log("hi")');
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
expect(index.size).toBe(2);
expect(index.has('readme')).toBe(true);
expect(index.has('docs/guide')).toBe(true);
expect(index.has('script')).toBe(false);
const entry = index.get('readme');
expect(entry).toBeTruthy();
expect(entry?.size).toBeGreaterThan(0);
expect(entry?.modified).toBeTruthy();
} finally {
await handle.unsubscribe();
}
});
test('initial scan caches page title + icon on each markdown entry', async () => {
writeFileSync(
resolve(contentDir, 'with-meta.md'),
'---\ntitle: Meta Title\nicon: 📝\n---\n\n# Heading Ignored\n',
);
writeFileSync(resolve(contentDir, 'heading-only.md'), '# Heading Title\n');
writeFileSync(resolve(contentDir, 'plain.md'), 'just body text, no heading\n');
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
expect(index.get('with-meta')?.title).toBe('Meta Title');
expect(index.get('with-meta')?.icon).toBe('📝');
expect(index.get('heading-only')?.title).toBe('Heading Title');
expect(index.get('heading-only')?.icon).toBeUndefined();
expect(index.get('plain')?.title).toBe('plain');
} finally {
await handle.unsubscribe();
}
});
test('initial scan preserves uppercase .MD/.MDX extension casing', async () => {
writeFileSync(resolve(contentDir, 'Upper.MD'), '# Upper\n');
writeFileSync(resolve(contentDir, 'Mixed.MdX'), '# Mixed\n');
const handle = await startWatcher(contentDir, async () => {});
try {
const { getDocExtension } = await import('./doc-extensions.ts');
const { safeContentPath } = await import('./content-path.ts');
expect(getDocExtension('Upper')).toBe('.MD');
expect(getDocExtension('Mixed')).toBe('.MdX');
const upperPath = safeContentPath('Upper', contentDir);
expect(upperPath.endsWith('/Upper.MD')).toBe(true);
const mixedPath = safeContentPath('Mixed', contentDir);
expect(mixedPath.endsWith('/Mixed.MdX')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('file index excludes files filtered by ContentFilter', async () => {
writeFileSync(resolve(tmpDir, '.gitignore'), 'dist/\n');
mkdirSync(resolve(contentDir, 'dist'), { recursive: true });
mkdirSync(resolve(contentDir, 'docs'), { recursive: true });
writeFileSync(resolve(contentDir, 'dist', 'output.md'), '# Build\n');
writeFileSync(resolve(contentDir, 'docs', 'guide.md'), '# Guide\n');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
const index = handle.getFileIndex();
expect(index.size).toBe(1);
expect(index.has('docs/guide')).toBe(true);
expect(index.has('dist/output')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('file index excludes files matching .okignore patterns', async () => {
mkdirSync(resolve(contentDir, 'archive'), { recursive: true });
writeFileSync(resolve(contentDir, 'readme.md'), '# README\n');
writeFileSync(resolve(contentDir, 'archive', 'old.md'), '# Old\n');
writeFileSync(resolve(tmpDir, '.okignore'), 'content/archive/\n');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
const index = handle.getFileIndex();
expect(index.size).toBe(1);
expect(index.has('readme')).toBe(true);
expect(index.has('archive/old')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('file index updates on create event', () => {
const index = new Map();
const event = {
kind: 'create' as const,
path: resolve(contentDir, 'new-file.md'),
docName: 'new-file',
content: '# New File\n',
};
updateFileIndex(event, index);
expect(index.has('new-file')).toBe(true);
expect(index.get('new-file')?.size).toBe(Buffer.byteLength('# New File\n', 'utf-8'));
expect(index.get('new-file')?.modified).toBeTruthy();
});
test('file index removes entry on delete event', () => {
const index = new Map([['existing', { size: 10, modified: new Date().toISOString() }]]);
const event = {
kind: 'delete' as const,
path: resolve(contentDir, 'existing.md'),
docName: 'existing',
};
updateFileIndex(event, index);
expect(index.has('existing')).toBe(false);
});
test('file index updates size/modified on update event', () => {
const oldModified = '2020-01-01T00:00:00.000Z';
const index = new Map([['doc', { size: 5, modified: oldModified }]]);
const event = {
kind: 'update' as const,
path: resolve(contentDir, 'doc.md'),
docName: 'doc',
content: '# Updated content with more text\n',
};
updateFileIndex(event, index);
expect(index.get('doc')?.size).toBe(
Buffer.byteLength('# Updated content with more text\n', 'utf-8'),
);
expect(index.get('doc')?.modified).not.toBe(oldModified);
});
test('file index handles rename event', () => {
const index = new Map([['old-name', { size: 10, modified: new Date().toISOString() }]]);
const event = {
kind: 'rename' as const,
oldPath: resolve(contentDir, 'old-name.md'),
newPath: resolve(contentDir, 'new-name.md'),
oldDocName: 'old-name',
newDocName: 'new-name',
content: '# Renamed\n',
};
updateFileIndex(event, index);
expect(index.has('old-name')).toBe(false);
expect(index.has('new-name')).toBe(true);
expect(index.get('new-name')?.size).toBe(Buffer.byteLength('# Renamed\n', 'utf-8'));
});
test('file index caches title + icon on create/update/rename/conflict events', () => {
const index = new Map();
updateFileIndex(
{
kind: 'create' as const,
path: resolve(contentDir, 'doc.md'),
docName: 'doc',
content: '---\ntitle: Created\nicon: 🚀\n---\n\nBody\n',
},
index,
);
expect(index.get('doc')?.title).toBe('Created');
expect(index.get('doc')?.icon).toBe('🚀');
updateFileIndex(
{
kind: 'update' as const,
path: resolve(contentDir, 'doc.md'),
docName: 'doc',
content: '# Edited Title\n',
},
index,
);
expect(index.get('doc')?.title).toBe('Edited Title');
expect(index.get('doc')?.icon).toBeUndefined();
updateFileIndex(
{
kind: 'rename' as const,
oldPath: resolve(contentDir, 'doc.md'),
newPath: resolve(contentDir, 'renamed.md'),
oldDocName: 'doc',
newDocName: 'renamed',
content: '---\ntitle: Renamed Title\nicon: 🔖\n---\n\nBody\n',
},
index,
);
expect(index.get('renamed')?.title).toBe('Renamed Title');
expect(index.get('renamed')?.icon).toBe('🔖');
updateFileIndex(
{
kind: 'conflict' as const,
path: resolve(contentDir, 'renamed.md'),
docName: 'renamed',
content: '---\ntitle: Conflicted\nicon: ⚠️\n---\n<<<<<<< HEAD\na\n=======\nb\n>>>>>>> x\n',
},
index,
);
expect(index.get('renamed')?.title).toBe('Conflicted');
expect(index.get('renamed')?.icon).toBe('⚠️');
});
test('getFileIndex returns empty map when no .md files exist', async () => {
const handle = await startWatcher(contentDir, async () => {});
try {
expect(handle.getFileIndex().size).toBe(0);
} finally {
await handle.unsubscribe();
}
});
test('pruneFileIndexNowExcluded removes entries that became excluded after rebuild', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(contentDir, 'hide-me.md'), '# Hide me\n');
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFileIndex().has('keep')).toBe(true);
expect(handle.getFileIndex().has('hide-me')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), 'hide-me.md\n');
await filter.rebuildIgnorePatterns();
const pruned = handle.pruneFileIndexNowExcluded();
expect(pruned).toBe(1);
expect(handle.getFileIndex().has('keep')).toBe(true);
expect(handle.getFileIndex().has('hide-me')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('pruneFolderIndexNowExcluded removes folders that became excluded after rebuild', async () => {
mkdirSync(resolve(contentDir, 'archive', 'sub'), { recursive: true });
writeFileSync(resolve(contentDir, 'archive', 'sub', 'old.md'), '# Old\n');
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFolderIndex().has('archive')).toBe(true);
expect(handle.getFolderIndex().has('archive/sub')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), 'content/archive/\n');
await filter.rebuildIgnorePatterns();
const pruned = handle.pruneFolderIndexNowExcluded();
expect(pruned).toBe(2);
expect(handle.getFolderIndex().has('archive')).toBe(false);
expect(handle.getFolderIndex().has('archive/sub')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('pruneFileIndexNowExcluded is a no-op when nothing is now-excluded', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFileIndex().has('keep')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), 'something-else.md\n');
await filter.rebuildIgnorePatterns();
expect(handle.pruneFileIndexNowExcluded()).toBe(0);
expect(handle.getFileIndex().has('keep')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('pruneFolderIndexNowExcluded is a no-op when nothing is now-excluded', async () => {
mkdirSync(resolve(contentDir, 'keep'), { recursive: true });
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFolderIndex().has('keep')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), 'content/something-else/\n');
await filter.rebuildIgnorePatterns();
expect(handle.pruneFolderIndexNowExcluded()).toBe(0);
expect(handle.getFolderIndex().has('keep')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('pruneFileIndexNowExcluded returns 0 when no ContentFilter is set', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
const handle = await startWatcher(contentDir, async () => {});
try {
expect(handle.pruneFileIndexNowExcluded()).toBe(0);
} finally {
await handle.unsubscribe();
}
});
test('pruneFolderIndexNowExcluded returns 0 when no ContentFilter is set', async () => {
mkdirSync(resolve(contentDir, 'archive'), { recursive: true });
const handle = await startWatcher(contentDir, async () => {});
try {
expect(handle.getFolderIndex().has('archive')).toBe(true);
expect(handle.pruneFolderIndexNowExcluded()).toBe(0);
expect(handle.getFolderIndex().has('archive')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('initial scan populates folderIndex with empty subdirectories', async () => {
mkdirSync(resolve(contentDir, 'empty-folder'));
mkdirSync(resolve(contentDir, 'nested', 'empty-child'), { recursive: true });
const handle = await startWatcher(contentDir, async () => {});
try {
const folderIndex = handle.getFolderIndex();
expect(folderIndex.has('empty-folder')).toBe(true);
expect(folderIndex.has('nested')).toBe(true);
expect(folderIndex.has('nested/empty-child')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('folderIndex detects externally-created empty directory via live watcher', async ({
onTestFinished,
}) => {
const liveContentDir = await mkdtemp(resolve(tmpdir(), 'ok-watcher-live-empty-'));
onTestFinished(() => rm(liveContentDir, { recursive: true, force: true }));
const events: DiskEvent[] = [];
const folderCreated = Promise.withResolvers<void>();
const handle = await startWatcher(liveContentDir, async (e) => {
events.push(e);
if (e.kind === 'folder-create' && e.relativePath === 'live-empty') {
folderCreated.resolve();
}
});
onTestFinished(() => handle.unsubscribe());
mkdirSync(resolve(liveContentDir, 'live-empty'));
await folderCreated.promise;
expect(handle.getFolderIndex().has('live-empty')).toBe(true);
expect(events.some((e) => e.kind === 'folder-create' && e.relativePath === 'live-empty')).toBe(
true,
);
});
});
describe('reconcileFileIndexAfterFilterRebuild', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-reconcile-'));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('re-includes files previously excluded after pattern removal (start-with-pattern → remove)', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(contentDir, 'hide-me.md'), '# Hide me\n');
writeFileSync(resolve(tmpDir, '.okignore'), 'hide-me.md\n');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFileIndex().has('keep')).toBe(true);
expect(handle.getFileIndex().has('hide-me')).toBe(false);
writeFileSync(resolve(tmpDir, '.okignore'), '');
const result = await filter.rebuildIgnorePatterns();
expect(result.ok).toBe(true);
const { prunedFiles, prunedFolders } = await reconcileFileIndexAfterFilterRebuild(handle);
expect(prunedFiles).toBe(0);
expect(prunedFolders).toBe(0);
expect(handle.getFileIndex().has('hide-me')).toBe(true);
expect(handle.getFileIndex().has('keep')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('still prunes now-excluded files after pattern addition (other direction)', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(contentDir, 'will-hide.md'), '# Will hide\n');
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFileIndex().has('keep')).toBe(true);
expect(handle.getFileIndex().has('will-hide')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), 'will-hide.md\n');
const result = await filter.rebuildIgnorePatterns();
expect(result.ok).toBe(true);
const { prunedFiles, prunedFolders } = await reconcileFileIndexAfterFilterRebuild(handle);
expect(prunedFiles).toBe(1);
expect(prunedFolders).toBe(0);
expect(handle.getFileIndex().has('will-hide')).toBe(false);
expect(handle.getFileIndex().has('keep')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('re-includes a previously-excluded folder + its files after pattern removal', async () => {
mkdirSync(resolve(contentDir, 'archive', 'sub'), { recursive: true });
writeFileSync(resolve(contentDir, 'archive', 'sub', 'old.md'), '# Old\n');
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(tmpDir, '.okignore'), 'archive/\n');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFolderIndex().has('archive')).toBe(false);
expect(handle.getFolderIndex().has('archive/sub')).toBe(false);
expect(handle.getFileIndex().has('archive/sub/old')).toBe(false);
expect(handle.getFileIndex().has('keep')).toBe(true);
writeFileSync(resolve(tmpDir, '.okignore'), '');
const result = await filter.rebuildIgnorePatterns();
expect(result.ok).toBe(true);
await reconcileFileIndexAfterFilterRebuild(handle);
expect(handle.getFolderIndex().has('archive')).toBe(true);
expect(handle.getFolderIndex().has('archive/sub')).toBe(true);
expect(handle.getFileIndex().has('archive/sub/old')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('returns zero counts when no pattern matches existing entries', async () => {
writeFileSync(resolve(contentDir, 'keep.md'), '# Keep\n');
writeFileSync(resolve(tmpDir, '.okignore'), '');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
writeFileSync(resolve(tmpDir, '.okignore'), 'unrelated.md\n');
await filter.rebuildIgnorePatterns();
const { prunedFiles, prunedFolders } = await reconcileFileIndexAfterFilterRebuild(handle);
expect(prunedFiles).toBe(0);
expect(prunedFolders).toBe(0);
expect(handle.getFileIndex().has('keep')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('prunes one file while re-including another in the same reconcile (pattern swap)', async () => {
writeFileSync(resolve(contentDir, 'will-hide.md'), '# Will hide\n');
writeFileSync(resolve(contentDir, 'was-hidden.md'), '# Was hidden\n');
writeFileSync(resolve(tmpDir, '.okignore'), 'was-hidden.md\n');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
expect(handle.getFileIndex().has('will-hide')).toBe(true);
expect(handle.getFileIndex().has('was-hidden')).toBe(false);
writeFileSync(resolve(tmpDir, '.okignore'), 'will-hide.md\n');
const result = await filter.rebuildIgnorePatterns();
expect(result.ok).toBe(true);
const { prunedFiles } = await reconcileFileIndexAfterFilterRebuild(handle);
expect(prunedFiles).toBe(1);
expect(handle.getFileIndex().has('will-hide')).toBe(false);
expect(handle.getFileIndex().has('was-hidden')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('returns zero counts when watcher is undefined (defensive guard)', async () => {
const { prunedFiles, prunedFolders } = await reconcileFileIndexAfterFilterRebuild(undefined);
expect(prunedFiles).toBe(0);
expect(prunedFolders).toBe(0);
});
});
describe('file-watcher ContentFilter refcount hooks', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-watcher-refcount-'));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('.md rename across directories triggers decrement on old dir and increment on new dir', async () => {
mkdirSync(resolve(contentDir, 'old-dir'));
mkdirSync(resolve(contentDir, 'new-dir'));
writeFileSync(resolve(contentDir, 'old-dir', 'doc.md'), '# Doc\n');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
expect(filter.isExcluded('old-dir/img.png')).toBe(false);
expect(filter.isExcluded('new-dir/img.png')).toBe(true);
const oldPath = resolve(contentDir, 'old-dir', 'doc.md');
const newPath = resolve(contentDir, 'new-dir', 'doc.md');
updateLastKnownHash(oldPath, contentHash('# Doc\n'));
writeFileSync(newPath, '# Doc\n');
const events = await classifyEvents(
[
{ type: 'delete', path: oldPath },
{ type: 'create', path: newPath },
],
contentDir,
filter,
);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('rename');
if (events[0].kind === 'rename') {
const { dirname } = await import('node:path');
filter.decrementMdDir(dirname(events[0].oldDocName));
filter.incrementMdDir(dirname(events[0].newDocName));
}
expect(filter.isExcluded('old-dir/img.png')).toBe(true);
expect(filter.isExcluded('new-dir/img.png')).toBe(false);
});
test('same-batch md+asset create in a brand-new directory: asset is dispatched (md-first ordering)', async () => {
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
expect(filter.isExcluded('fresh/pic.png')).toBe(true);
const newDir = resolve(contentDir, 'fresh');
mkdirSync(newDir);
const mdPath = resolve(newDir, 'note.md');
const assetPath = resolve(newDir, 'pic.png');
writeFileSync(mdPath, '# Note\n');
writeFileSync(assetPath, 'fake-png-bytes');
const collected: DiskEvent[] = [];
await handleRawEvents(
[
{ type: 'create', path: mdPath },
{ type: 'create', path: assetPath },
],
contentDir,
filter,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
const kinds = collected.map((e) => e.kind).sort();
expect(kinds).toEqual(['asset-create', 'create', 'file-create']);
const asset = collected.find((e) => e.kind === 'asset-create');
expect(asset?.kind).toBe('asset-create');
if (asset?.kind === 'asset-create') {
expect(asset.relativePath).toBe('fresh/pic.png');
}
expect(filter.isExcluded('fresh/pic.png')).toBe(false);
});
test('asset create in a directory with no markdown document dispatches asset-create', async () => {
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const newDir = resolve(contentDir, 'media');
mkdirSync(newDir);
const assetPath = resolve(newDir, 'pic.png');
writeFileSync(assetPath, 'fake-png-bytes');
expect(filter.isExcluded('media/pic.png')).toBe(true);
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: assetPath }],
contentDir,
filter,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
expect(collected.map((e) => e.kind).sort()).toEqual(['asset-create', 'file-create']);
const asset = collected.find((e) => e.kind === 'asset-create');
expect(asset?.kind).toBe('asset-create');
if (asset?.kind === 'asset-create') {
expect(asset.relativePath).toBe('media/pic.png');
}
});
test('LINKABLE_ASSET_EXTENSIONS: .base file alongside .md dispatches asset-create event', async () => {
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const newDir = resolve(contentDir, 'canvas-test');
mkdirSync(newDir);
const mdPath = resolve(newDir, 'note.md');
const assetPath = resolve(newDir, 'board.base');
writeFileSync(mdPath, '# Note\n');
writeFileSync(assetPath, '{}');
const collected: DiskEvent[] = [];
await handleRawEvents(
[
{ type: 'create', path: mdPath },
{ type: 'create', path: assetPath },
],
contentDir,
filter,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
const kinds = collected.map((e) => e.kind).sort();
expect(kinds).toEqual(['asset-create', 'create', 'file-create']);
const asset = collected.find((e) => e.kind === 'asset-create');
if (asset?.kind === 'asset-create') {
expect(asset.relativePath).toBe('canvas-test/board.base');
}
});
test('folder create/delete events update the folder index', async () => {
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const notesDir = resolve(contentDir, 'notes');
const nestedDir = resolve(notesDir, 'nested');
mkdirSync(nestedDir, { recursive: true });
await handleRawEvents(
[
{ type: 'create', path: notesDir },
{ type: 'create', path: nestedDir },
],
contentDir,
undefined,
new Map(),
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(folderIndex.has('notes')).toBe(true);
expect(folderIndex.has('notes/nested')).toBe(true);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-create', relativePath: 'notes' }),
);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-create', relativePath: 'notes/nested' }),
);
await rm(notesDir, { recursive: true, force: true });
await handleRawEvents(
[{ type: 'delete', path: notesDir }],
contentDir,
undefined,
new Map(),
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(folderIndex.has('notes')).toBe(false);
expect(folderIndex.has('notes/nested')).toBe(false);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-delete', relativePath: 'notes' }),
);
});
test('a collapsed folder delete synthesizes deletes for indexed descendants', async () => {
const folderIndex = new Map();
const fileIndex = new Map();
const collected: DiskEvent[] = [];
const notesDir = resolve(contentDir, 'notes');
const nestedDir = resolve(notesDir, 'nested');
const notePath = resolve(nestedDir, 'note.md');
mkdirSync(nestedDir, { recursive: true });
writeFileSync(notePath, '# Note\n');
await handleRawEvents(
[
{ type: 'create', path: notesDir },
{ type: 'create', path: nestedDir },
{ type: 'create', path: notePath },
],
contentDir,
undefined,
fileIndex,
folderIndex,
async (event) => {
collected.push(event);
},
);
expect(fileIndex.has('notes/nested/note')).toBe(true);
collected.length = 0;
await rm(notesDir, { recursive: true, force: true });
await handleRawEvents(
[{ type: 'delete', path: notesDir }],
contentDir,
undefined,
fileIndex,
folderIndex,
async (event) => {
collected.push(event);
},
);
expect(fileIndex.has('notes/nested/note')).toBe(false);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'delete', docName: 'notes/nested/note' }),
);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-delete', relativePath: 'notes' }),
);
});
test('mkdir -p race: single create event for parent surfaces folder-create for all pre-existing subdirs', async () => {
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const deepDir = resolve(contentDir, 'deep');
const nestedDir = resolve(deepDir, 'nested');
const emptyDir = resolve(nestedDir, 'empty');
mkdirSync(emptyDir, { recursive: true });
await handleRawEvents(
[{ type: 'create', path: deepDir }],
contentDir,
undefined,
new Map(),
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(folderIndex.has('deep')).toBe(true);
expect(folderIndex.has('deep/nested')).toBe(true);
expect(folderIndex.has('deep/nested/empty')).toBe(true);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-create', relativePath: 'deep' }),
);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-create', relativePath: 'deep/nested' }),
);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'folder-create', relativePath: 'deep/nested/empty' }),
);
const folderEvents = collected
.filter((e) => e.kind === 'folder-create')
.map((e) => e.relativePath);
expect(folderEvents.indexOf('deep')).toBeLessThan(folderEvents.indexOf('deep/nested'));
expect(folderEvents.indexOf('deep/nested')).toBeLessThan(
folderEvents.indexOf('deep/nested/empty'),
);
});
test('rescan does not double-emit when an inner folder already arrived as its own raw event', async () => {
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const deepDir = resolve(contentDir, 'deep');
const nestedDir = resolve(deepDir, 'nested');
mkdirSync(nestedDir, { recursive: true });
await handleRawEvents(
[
{ type: 'create', path: deepDir },
{ type: 'create', path: nestedDir },
],
contentDir,
undefined,
new Map(),
folderIndex,
async (e) => {
collected.push(e);
},
);
const nestedCreates = collected.filter(
(e) => e.kind === 'folder-create' && e.relativePath === 'deep/nested',
);
expect(nestedCreates).toHaveLength(1);
});
test('dropped file-create rescue: folder event alone surfaces a markdown file already inside', async () => {
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const scratchDir = resolve(contentDir, '.scratch-notes');
mkdirSync(scratchDir, { recursive: true });
writeFileSync(resolve(scratchDir, 'hidden-note.md'), '# Hidden note\n', 'utf-8');
await handleRawEvents(
[{ type: 'create', path: scratchDir }],
contentDir,
undefined,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(folderIndex.has('.scratch-notes')).toBe(true);
expect(fileIndex.has('.scratch-notes/hidden-note')).toBe(true);
expect(collected).toContainEqual(
expect.objectContaining({
kind: 'create',
docName: '.scratch-notes/hidden-note',
content: '# Hidden note\n',
}),
);
});
test('dropped file-create rescue reaches files in rescued subfolders and non-markdown files', async () => {
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const outerDir = resolve(contentDir, 'outer');
const innerDir = resolve(outerDir, 'inner');
mkdirSync(innerDir, { recursive: true });
writeFileSync(resolve(innerDir, 'deep-note.md'), '# Deep\n', 'utf-8');
writeFileSync(resolve(outerDir, 'data.json'), '{}', 'utf-8');
await handleRawEvents(
[{ type: 'create', path: outerDir }],
contentDir,
undefined,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(fileIndex.has('outer/inner/deep-note')).toBe(true);
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'create', docName: 'outer/inner/deep-note' }),
);
expect(fileIndex.get('outer/data.json')?.kind).toBe('file');
expect(collected).toContainEqual(
expect.objectContaining({ kind: 'file-create', relativePath: 'outer/data.json' }),
);
});
test('file rescue does not double-emit when the file event arrived in the same batch', async () => {
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const notesDir = resolve(contentDir, 'batch-notes');
const notePath = resolve(notesDir, 'note.md');
mkdirSync(notesDir, { recursive: true });
writeFileSync(notePath, '# Note\n', 'utf-8');
await handleRawEvents(
[
{ type: 'create', path: notesDir },
{ type: 'create', path: notePath },
],
contentDir,
undefined,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
const creates = collected.filter(
(e) => e.kind === 'create' && e.docName === 'batch-notes/note',
);
expect(creates).toHaveLength(1);
});
test('file rescue respects self-write tracking: rescued own write is indexed but not dispatched', async () => {
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const selfDir = resolve(contentDir, 'self-notes');
const selfPath = resolve(selfDir, 'own-write.md');
const content = '# Ours\n';
mkdirSync(selfDir, { recursive: true });
writeFileSync(selfPath, content, 'utf-8');
registerWrite(realpathSync(selfPath), contentHash(content));
await handleRawEvents(
[{ type: 'create', path: selfDir }],
contentDir,
undefined,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(fileIndex.has('self-notes/own-write')).toBe(true);
expect(collected.filter((e) => e.kind === 'create')).toHaveLength(0);
});
test('file rescue suppresses files under a ContentFilter-excluded subfolder', async () => {
writeFileSync(resolve(tmpDir, '.gitignore'), 'vendor/\n');
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const packDir = resolve(contentDir, 'pack');
const vendorDir = resolve(packDir, 'vendor');
mkdirSync(vendorDir, { recursive: true });
writeFileSync(resolve(packDir, 'note.md'), '# Note\n', 'utf-8');
writeFileSync(resolve(vendorDir, 'data.json'), '{}', 'utf-8');
writeFileSync(resolve(vendorDir, 'hidden.md'), '# Hidden\n', 'utf-8');
await handleRawEvents(
[{ type: 'create', path: packDir }],
contentDir,
filter,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(fileIndex.has('pack/note')).toBe(true);
expect(fileIndex.has('pack/vendor/data.json')).toBe(false);
expect(fileIndex.has('pack/vendor/hidden')).toBe(false);
expect(collected.some((e) => e.kind === 'file-create')).toBe(false);
expect(collected.filter((e) => e.kind === 'create').map((e) => e.docName)).toEqual([
'pack/note',
]);
});
test('file rescue skips symlinked files in a freshly created directory', async () => {
const fileIndex = new Map();
const folderIndex = new Map();
const collected: DiskEvent[] = [];
const targetPath = resolve(contentDir, 'link-target.md');
writeFileSync(targetPath, '# Target\n', 'utf-8');
const linkedDir = resolve(contentDir, 'linked');
mkdirSync(linkedDir, { recursive: true });
writeFileSync(resolve(linkedDir, 'real.md'), '# Real\n', 'utf-8');
symlinkSync(targetPath, resolve(linkedDir, 'alias.md'));
await handleRawEvents(
[{ type: 'create', path: linkedDir }],
contentDir,
undefined,
fileIndex,
folderIndex,
async (e) => {
collected.push(e);
},
);
expect(fileIndex.has('linked/real')).toBe(true);
expect(fileIndex.has('linked/alias')).toBe(false);
expect(collected.filter((e) => e.kind === 'create').map((e) => e.docName)).toEqual([
'linked/real',
]);
});
});
describe('startWatcher symlink handling', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = realpathSync(await mkdtemp(resolve(tmpdir(), 'ok-watcher-symlink-')));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('indexes symlinked file with canonical docName and registers alias', async () => {
const targetPath = resolve(contentDir, 'target.md');
const linkPath = resolve(contentDir, 'link.md');
writeFileSync(targetPath, '# Target\n');
symlinkSync(targetPath, linkPath);
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
const aliasMap = handle.getAliasMap();
expect(index.has('target')).toBe(true);
expect(aliasMap.get('link')).toBe('target');
const entry = index.get('target');
expect(entry).toBeTruthy();
expect(entry?.canonicalPath).toBe(targetPath);
expect(entry?.inode).toMatch(/^\d+:[1-9]\d*$/);
expect(entry?.aliases).toContain('link');
} finally {
await handle.unsubscribe();
}
});
test('records a folder-alias edge for a symlinked directory without materializing its subtree', async () => {
const canonicalDir = resolve(contentDir, 'canonical');
mkdirSync(canonicalDir, { recursive: true });
writeFileSync(resolve(canonicalDir, 'note.md'), '# Note\n');
mkdirSync(resolve(canonicalDir, 'sub'), { recursive: true });
writeFileSync(resolve(canonicalDir, 'sub', 'deep.md'), '# Deep\n');
symlinkSync(canonicalDir, resolve(contentDir, 'aliasA'));
symlinkSync(canonicalDir, resolve(contentDir, 'aliasB'));
const handle = await startWatcher(contentDir, async () => {});
try {
const folderAliasIndex = handle.getFolderAliasIndex();
expect(folderAliasIndex.get('aliasA')).toBe('canonical');
expect(folderAliasIndex.get('aliasB')).toBe('canonical');
const index = handle.getFileIndex();
expect(index.has('canonical/note')).toBe(true);
expect(index.has('canonical/sub/deep')).toBe(true);
expect(index.has('aliasA/note')).toBe(false);
expect(index.has('aliasB/sub/deep')).toBe(false);
const folderIndex = handle.getFolderIndex();
expect(folderIndex.has('canonical')).toBe(true);
expect(folderIndex.has('canonical/sub')).toBe(true);
expect(folderIndex.has('aliasA')).toBe(false);
expect(folderIndex.has('aliasB')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('skips broken symlinks during startup walk', async () => {
const linkPath = resolve(contentDir, 'broken.md');
symlinkSync(resolve(contentDir, 'nonexistent.md'), linkPath);
writeFileSync(resolve(contentDir, 'good.md'), '# Good\n');
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
expect(index.has('good')).toBe(true);
expect(index.has('broken')).toBe(false);
expect(index.has('nonexistent')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('skips symlinks escaping contentDir during startup walk', async () => {
const outsideDir = resolve(tmpDir, 'outside');
mkdirSync(outsideDir, { recursive: true });
const outsideFile = resolve(outsideDir, 'secret.md');
writeFileSync(outsideFile, '# Secret\n');
const escapePath = resolve(contentDir, 'escape.md');
symlinkSync(outsideFile, escapePath);
writeFileSync(resolve(contentDir, 'safe.md'), '# Safe\n');
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
expect(index.has('safe')).toBe(true);
expect(index.has('escape')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('drops runtime events for symlinks whose target escapes contentDir', async () => {
const outsideDir = resolve(tmpDir, 'outside');
mkdirSync(outsideDir, { recursive: true });
const outsideFile = resolve(outsideDir, 'secret.md');
writeFileSync(outsideFile, '# external secrets\n');
const escapePath = resolve(contentDir, 'escape.md');
symlinkSync(outsideFile, escapePath);
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: escapePath }],
contentDir,
undefined,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
expect(collected).toHaveLength(0);
});
test('drops runtime events for asset symlinks whose target escapes contentDir', async () => {
const outsideDir = resolve(tmpDir, 'outside');
mkdirSync(outsideDir, { recursive: true });
const outsideAsset = resolve(outsideDir, 'leak.png');
writeFileSync(outsideAsset, 'fake-png');
const escapePath = resolve(contentDir, 'leak.png');
symlinkSync(outsideAsset, escapePath);
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: escapePath }],
contentDir,
undefined,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
expect(collected).toHaveLength(0);
});
describe('links into private repository state', () => {
const SECRET = '# machine-local-secret\n';
beforeEach(() => {
mkdirSync(resolve(contentDir, '.ok', 'local'), { recursive: true });
writeFileSync(resolve(contentDir, '.ok', 'local', 'secret.md'), SECRET);
mkdirSync(resolve(contentDir, '.git'), { recursive: true });
writeFileSync(resolve(contentDir, '.git', 'config'), '[core]\n');
writeFileSync(resolve(contentDir, '.ok', 'config.yml'), '');
});
const filterFor = () => createContentFilter({ projectDir: contentDir, contentDir });
test('the startup walk does not follow a directory link into .git', async () => {
writeFileSync(resolve(contentDir, '.git', 'notes.md'), SECRET);
symlinkSync('.git', resolve(contentDir, 'repo'));
const handle = await startWatcher(contentDir, async () => {}, filterFor());
try {
expect(handle.getFolderAliasIndex().has('repo')).toBe(false);
for (const docName of handle.getFileIndex().keys()) {
expect(docName.startsWith('.git/')).toBe(false);
}
} finally {
await handle.unsubscribe();
}
});
test('runtime events for a doc linked into machine-local state are dropped', async () => {
const linkPath = resolve(contentDir, 'leak.md');
symlinkSync('.ok/local/secret.md', linkPath);
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: linkPath }],
contentDir,
filterFor(),
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
new Map(),
);
expect(collected).toHaveLength(0);
});
test('runtime events for an asset linked to the git config are dropped', async () => {
const linkPath = resolve(contentDir, 'leak.png');
symlinkSync('.git/config', linkPath);
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: linkPath }],
contentDir,
filterFor(),
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
);
expect(collected).toHaveLength(0);
});
});
test('preserves runtime events for symlinks pointing inside contentDir', async () => {
const targetPath = resolve(contentDir, 'real-target.md');
const aliasPath = resolve(contentDir, 'alias.md');
writeFileSync(targetPath, '# real\n');
symlinkSync(targetPath, aliasPath);
const aliasMap = new Map<string, string>();
const collected: DiskEvent[] = [];
await handleRawEvents(
[{ type: 'create', path: aliasPath }],
contentDir,
undefined,
new Map(),
new Map(),
async (e) => {
collected.push(e);
},
aliasMap,
);
expect(collected).toHaveLength(1);
expect(collected[0].kind).toBe('create');
if (collected[0].kind === 'create') {
expect(collected[0].docName).toBe('real-target');
}
expect(aliasMap.get('alias')).toBe('real-target');
});
test('skips symlink-to-excluded-dir (node_modules inside contentDir) during startup walk', async () => {
const realNm = resolve(contentDir, 'node_modules');
mkdirSync(realNm, { recursive: true });
symlinkSync(resolve(realNm, 'nonexistent'), resolve(realNm, 'broken-pkg'));
writeFileSync(resolve(realNm, 'README.md'), '# Pkg\n');
const subPkg = resolve(contentDir, 'packages', 'foo');
mkdirSync(subPkg, { recursive: true });
symlinkSync(realNm, resolve(subPkg, 'node_modules'));
writeFileSync(resolve(contentDir, 'docs.md'), '# Docs\n');
const filter = createContentFilter({
projectDir: tmpDir,
contentDir,
});
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
const index = handle.getFileIndex();
expect(index.has('docs')).toBe(true);
expect(index.has('node_modules/README')).toBe(false);
expect(index.has('packages/foo/node_modules/README')).toBe(false);
} finally {
await handle.unsubscribe();
}
});
test('handles cyclic symlink directories without infinite loop', async () => {
const dirA = resolve(contentDir, 'dir-a');
const dirB = resolve(contentDir, 'dir-b');
mkdirSync(dirA, { recursive: true });
mkdirSync(dirB, { recursive: true });
writeFileSync(resolve(dirA, 'file.md'), '# File A\n');
symlinkSync(dirB, resolve(dirA, 'link-to-b'));
symlinkSync(dirA, resolve(dirB, 'link-to-a'));
const handle = await startWatcher(contentDir, async () => {});
try {
const index = handle.getFileIndex();
expect(index.has('dir-a/file')).toBe(true);
} finally {
await handle.unsubscribe();
}
});
test('FileIndexEntry has canonicalPath, inode, and aliases fields', async () => {
writeFileSync(resolve(contentDir, 'regular.md'), '# Regular\n');
const handle = await startWatcher(contentDir, async () => {});
try {
const entry = handle.getFileIndex().get('regular');
expect(entry).toBeTruthy();
expect(entry?.canonicalPath).toBe(resolve(contentDir, 'regular.md'));
expect(entry?.inode).toMatch(/^\d+:[1-9]\d*$/);
expect(entry?.aliases).toEqual([]);
} finally {
await handle.unsubscribe();
}
});
test('classifyEvents resolves alias docName to canonical', async () => {
const targetPath = resolve(contentDir, 'target.md');
const linkPath = resolve(contentDir, 'link.md');
writeFileSync(targetPath, '# Target\n');
symlinkSync(targetPath, linkPath);
const aliasMap = new Map([['link', 'target']]);
updateLastKnownHash(linkPath, contentHash('# Target\n'));
writeFileSync(targetPath, '# Updated\n');
const events = await classifyEvents(
[{ type: 'update', path: linkPath }],
contentDir,
undefined,
aliasMap,
);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('update');
if (events[0].kind === 'update') {
expect(events[0].docName).toBe('target');
}
});
test('self-write detection works with canonical path after symlink resolution', async () => {
const targetPath = resolve(contentDir, 'target.md');
const linkPath = resolve(contentDir, 'link.md');
writeFileSync(targetPath, '# Original\n');
symlinkSync(targetPath, linkPath);
const markdown = '# Updated via symlink\n';
const hash = contentHash(markdown);
registerWrite(targetPath, hash);
expect(isSelfWrite(targetPath, hash)).toBe(true);
});
test('classifyEvents live-resolves symlink created post-startup and updates aliasMap', async () => {
const targetPath = resolve(contentDir, 'new-target.md');
const linkPath = resolve(contentDir, 'new-link.md');
writeFileSync(targetPath, '# Target\n');
symlinkSync(targetPath, linkPath);
const aliasMap = new Map<string, string>();
const events = await classifyEvents(
[{ type: 'create', path: linkPath }],
contentDir,
undefined,
aliasMap,
);
expect(events).toHaveLength(1);
expect(events[0].kind).toBe('create');
if (events[0].kind === 'create') {
expect(events[0].docName).toBe('new-target');
}
expect(aliasMap.get('new-link')).toBe('new-target');
});
test('classifyEvents re-resolves a repointed symlink and updates aliasMap', async () => {
const oldTargetPath = resolve(contentDir, 'old-target.md');
const newTargetPath = resolve(contentDir, 'fresh-target.md');
const aliasPath = resolve(contentDir, 'alias.md');
writeFileSync(oldTargetPath, '# Old\n');
writeFileSync(newTargetPath, '# Fresh\n');
symlinkSync(newTargetPath, aliasPath);
const aliasMap = new Map<string, string>([['alias', 'old-target']]);
const events = await classifyEvents(
[{ type: 'update', path: aliasPath }],
contentDir,
undefined,
aliasMap,
);
expect(events).toHaveLength(1);
if (events[0].kind === 'update') {
expect(events[0].docName).toBe('fresh-target');
}
expect(aliasMap.get('alias')).toBe('fresh-target');
});
});
describe('toParcelIgnorePaths', () => {
let projectDir: string;
beforeEach(async () => {
projectDir = await mkdtemp(resolve(tmpdir(), 'ok-parcel-ignore-'));
});
afterEach(async () => {
await rm(projectDir, { recursive: true, force: true });
});
test('keeps the structural roots a prefix match can stand in for', () => {
const filter = createContentFilter({ projectDir, contentDir: projectDir });
expect(toParcelIgnorePaths(filter.getWatcherIgnoreGlobs()).sort()).toEqual([
'.git',
'.ok/local',
'.ok/worktrees',
'node_modules',
]);
});
test('drops the recursive and children forms of those same roots', () => {
expect(
toParcelIgnorePaths([
'.git',
'.git/**',
'**/.git',
'**/.git/**',
'node_modules',
'node_modules/**',
'**/node_modules',
'**/node_modules/**',
]),
).toEqual(['.git', 'node_modules']);
});
test('drops ordinary user exclusions, whose subtrees can still admit content', () => {
writeFileSync(resolve(projectDir, '.gitignore'), 'dist/\ntmp/\n');
writeFileSync(resolve(projectDir, '.okignore'), 'drafts/\n');
const filter = createContentFilter({ projectDir, contentDir: projectDir });
const ignorePaths = toParcelIgnorePaths(filter.getWatcherIgnoreGlobs());
expect(filter.getWatcherIgnoreGlobs()).toEqual(
expect.arrayContaining(['dist/', 'tmp/', 'drafts/']),
);
expect(ignorePaths).not.toContain('dist/');
expect(ignorePaths).not.toContain('tmp/');
expect(ignorePaths).not.toContain('drafts/');
});
test('never hands @parcel/watcher an entry its native matcher reads as a glob', () => {
writeFileSync(
resolve(projectDir, '.gitignore'),
['dist/', '*.log', 'build/**', 'coverage', '**/*.tmp', 'a[0-9]/', 'x{1,2}/'].join('\n'),
);
const filter = createContentFilter({ projectDir, contentDir: projectDir });
const ignorePaths = toParcelIgnorePaths(filter.getWatcherIgnoreGlobs());
expect(ignorePaths.length).toBeGreaterThan(0);
for (const entry of ignorePaths) {
expect(entry).not.toMatch(/[*?[\]{}()!+@|\\]/);
}
});
});
describe('structural-ignore discovery feeds the parcel prefix list', () => {
let contentDir: string;
beforeEach(async () => {
contentDir = await mkdtemp(resolve(tmpdir(), 'ok-structural-discovery-'));
});
afterEach(async () => {
await rm(contentDir, { recursive: true, force: true });
});
test('merges discovered nested occurrences with the structural roots', () => {
const merged = toParcelIgnorePaths(
['.git', 'node_modules', '.ok/local', '.ok/worktrees', '**/node_modules/**', 'dist/'],
['packages/app/node_modules', 'vendor/lib/.git', 'sub/.ok/local'],
);
expect(merged).toEqual(
expect.arrayContaining([
'.git',
'node_modules',
'packages/app/node_modules',
'vendor/lib/.git',
'sub/.ok/local',
]),
);
expect(merged).not.toContain('**/node_modules/**');
expect(merged).not.toContain('dist/');
});
test('drops a discovered directory whose real name contains a glob metacharacter', () => {
const merged = toParcelIgnorePaths(
['.git', 'node_modules'],
['a[0-9]/node_modules', 'ok-dir/node_modules'],
);
expect(merged).toContain('ok-dir/node_modules');
expect(merged).not.toContain('a[0-9]/node_modules');
});
test('the seed walk records nested structural dirs it prunes', async () => {
mkdirSync(resolve(contentDir, 'packages/app/node_modules/pkg'), { recursive: true });
mkdirSync(resolve(contentDir, 'docs/lib/.git/objects'), { recursive: true });
mkdirSync(resolve(contentDir, 'notes'), { recursive: true });
writeFileSync(resolve(contentDir, 'notes/keep.md'), '# keep\n');
writeFileSync(resolve(contentDir, 'packages/app/node_modules/pkg/index.md'), 'dep\n');
const filter = createContentFilter({ projectDir: contentDir, contentDir });
const watcher = await startWatcher(contentDir, async () => {}, filter, {
forceBackend: 'chokidar',
});
try {
expect([...watcher.getFileIndex().keys()]).toContain('notes/keep');
expect([...watcher.getFileIndex().keys()]).not.toContain(
'packages/app/node_modules/pkg/index',
);
expect([...watcher.getStructuralIgnoreDirs()].sort()).toEqual([
'docs/lib/.git',
'packages/app/node_modules',
]);
} finally {
await watcher.unsubscribe();
}
});
test('records a nested two-segment root, whose match is a suffix not a segment', async () => {
mkdirSync(resolve(contentDir, 'packages/sub/.ok/local/logs'), { recursive: true });
mkdirSync(resolve(contentDir, 'packages/sub/.ok/templates'), { recursive: true });
writeFileSync(resolve(contentDir, 'packages/sub/.ok/templates/note.md'), '# tmpl\n');
const filter = createContentFilter({ projectDir: contentDir, contentDir });
const watcher = await startWatcher(contentDir, async () => {}, filter, {
forceBackend: 'chokidar',
});
try {
const discovered = [...watcher.getStructuralIgnoreDirs()];
expect(discovered).toContain('packages/sub/.ok/local');
expect(discovered).not.toContain('packages/sub/.ok');
} finally {
await watcher.unsubscribe();
}
});
test('discovery stops at a non-structural excluded directory', async () => {
mkdirSync(resolve(contentDir, 'vendor/lib/node_modules/pkg'), { recursive: true });
mkdirSync(resolve(contentDir, 'app/node_modules'), { recursive: true });
const filter = createContentFilter({ projectDir: contentDir, contentDir });
const watcher = await startWatcher(contentDir, async () => {}, filter, {
forceBackend: 'chokidar',
});
try {
expect([...watcher.getStructuralIgnoreDirs()]).toEqual(['app/node_modules']);
} finally {
await watcher.unsubscribe();
}
});
});
describe('file index canonical path after a real rename', () => {
let tmpDir: string;
let contentDir: string;
beforeEach(async () => {
tmpDir = realpathSync(await mkdtemp(resolve(tmpdir(), 'ok-watcher-rename-')));
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
});
afterEach(async () => {
lastKnownHash.clear();
await rm(tmpDir, { recursive: true, force: true });
});
async function seedIndexFromStartupWalk() {
const handle = await startWatcher(contentDir, async () => {});
try {
return {
fileIndex: new Map(handle.getFileIndex()),
folderIndex: new Map(handle.getFolderIndex()),
aliasMap: new Map(handle.getAliasMap()),
};
} finally {
await handle.unsubscribe();
}
}
function declareLastKnownContent(filePath: string): void {
updateLastKnownHash(filePath, contentHash(readFileSync(filePath, 'utf-8')));
}
function readOrErrnoCode(filePath: string): string {
try {
return readFileSync(filePath, 'utf-8');
} catch (e) {
return `<${(e as { code?: string }).code}: ${filePath}>`;
}
}
async function applyRawEvents(
seeded: Awaited<ReturnType<typeof seedIndexFromStartupWalk>>,
rawEvents: Array<{ type: 'create' | 'update' | 'delete'; path: string }>,
): Promise<DiskEvent[]> {
const dispatched: DiskEvent[] = [];
await handleRawEvents(
rawEvents,
contentDir,
undefined,
seeded.fileIndex,
seeded.folderIndex,
async (event) => {
dispatched.push(event);
},
seeded.aliasMap,
);
return dispatched;
}
test.each([
{ ext: '.md', stem: 'md-target', body: '# Unique real md rename target\n' },
{ ext: '.mdx', stem: 'mdx-target', body: '# Unique real mdx rename target\n' },
])(
'a real $ext rename publishes a path that reads the moved file',
async ({ ext, stem, body }) => {
mkdirSync(resolve(contentDir, 'z'), { recursive: true });
mkdirSync(resolve(contentDir, 'f'), { recursive: true });
const oldPath = resolve(contentDir, 'z', `${stem}${ext}`);
const newPath = resolve(contentDir, 'f', `${stem}${ext}`);
writeFileSync(oldPath, body, 'utf-8');
const seeded = await seedIndexFromStartupWalk();
expect(seeded.fileIndex.get(`z/${stem}`)?.canonicalPath).toBe(oldPath);
declareLastKnownContent(oldPath);
renameSync(oldPath, newPath);
const dispatched = await applyRawEvents(seeded, [
{ type: 'delete', path: oldPath },
{ type: 'create', path: newPath },
]);
expect(dispatched.filter((event) => event.kind === 'rename')).toHaveLength(1);
expect(seeded.fileIndex.has(`z/${stem}`)).toBe(false);
const entry = seeded.fileIndex.get(`f/${stem}`);
expect(entry).toBeDefined();
expect(readOrErrnoCode(entry?.canonicalPath ?? '')).toBe(body);
expect(entry?.canonicalPath).toBe(newPath);
},
);
test('a rename landing on a symlink publishes the canonical target, not the alias path', async () => {
mkdirSync(resolve(contentDir, 'real'), { recursive: true });
mkdirSync(resolve(contentDir, 'z'), { recursive: true });
const body = '# Shared body carried by the alias\n';
const keeperPath = resolve(contentDir, 'real', 'keeper.md');
const originPath = resolve(contentDir, 'z', 'origin.md');
const aliasPath = resolve(contentDir, 'alias.md');
writeFileSync(keeperPath, body, 'utf-8');
writeFileSync(originPath, body, 'utf-8');
const seeded = await seedIndexFromStartupWalk();
expect(seeded.fileIndex.get('real/keeper')?.canonicalPath).toBe(keeperPath);
declareLastKnownContent(originPath);
unlinkSync(originPath);
symlinkSync(keeperPath, aliasPath);
const dispatched = await applyRawEvents(seeded, [
{ type: 'delete', path: originPath },
{ type: 'create', path: aliasPath },
]);
expect(dispatched.filter((event) => event.kind === 'rename')).toHaveLength(1);
const entry = seeded.fileIndex.get('real/keeper');
expect(entry).toBeDefined();
expect(readOrErrnoCode(entry?.canonicalPath ?? '')).toBe(body);
expect(entry?.canonicalPath).toBe(keeperPath);
});
});