Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Recover watcher state after dropped-event notices (#5350)

Nick Gomezecaf862eed14
diff --git a/.changeset/watcher-drop-notice-recovery.md b/.changeset/watcher-drop-notice-recovery.md
new file mode 100644
index 000000000..2bf611db7
--- /dev/null
+++ b/.changeset/watcher-drop-notice-recovery.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Recover external file and branch changes when the file watcher reports dropped events.
diff --git a/packages/server/src/api-extension.test-helper.ts b/packages/server/src/api-extension.test-helper.ts
index c89983e78..61874d62d 100644
--- a/packages/server/src/api-extension.test-helper.ts
+++ b/packages/server/src/api-extension.test-helper.ts
@@ -22,6 +22,8 @@ interface LegacyIndexOptions {
tagIndex?: TagIndex | null;
}
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
type LegacySignalChannel = (
channel: 'files' | 'backlinks' | 'graph' | 'tags' | 'lint-config' | 'comments',
) => void;
@@ -231,7 +233,7 @@ function createLegacyDerivedIndexPort(
}
export function createApiExtension(
- options: Omit<
+ options: DistributiveOmit<
ApiExtensionOptions,
| 'durabilityState'
| 'derivedDocumentIndex'
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 2795a8ff5..d269b5a62 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -233,6 +233,7 @@ import {
} from './external-change.ts';
import { extractActorIdentity } from './extract-actor-identity.ts';
import {
+ type AllFileEntries,
contentHash,
type DiskEvent,
type FileIndexEntry,
@@ -1249,7 +1250,7 @@ export async function renameTrackedPathInGit(
});
}
-export interface ApiExtensionOptions {
+interface ApiExtensionBaseOptions {
declaredGitHubHosts?: ReadonlySet<string>;
ingressPolicy?: IngressPolicy;
hocuspocus: Hocuspocus;
@@ -1262,9 +1263,7 @@ export interface ApiExtensionOptions {
serverInstanceId: string;
getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
getAttachmentFolderPath?: () => string;
- getAllFilesIndex?: () => ReadonlyMap<string, FileIndexEntry>;
getFileIndexGeneration?: () => number;
- mutateFileIndex?: (event: DiskEvent) => void;
getFolderIndex?: () => ReadonlyMap<string, FolderIndexEntry>;
onReferencedAssetsCacheInvalidator?: (invalidate: () => void) => void;
getAliasMap?: () => ReadonlyMap<string, string>;
@@ -1322,6 +1321,18 @@ export interface ApiExtensionOptions {
getProjectConfigEpoch: () => number;
}
+export type ApiExtensionOptions = ApiExtensionBaseOptions &
+ (
+ | {
+ getAllFilesIndex?: () => ReadonlyMap<string, FileIndexEntry>;
+ mutateFileIndex?: (event: DiskEvent) => void;
+ }
+ | {
+ getAllFilesIndex: () => AllFileEntries;
+ mutateFileIndex: (event: DiskEvent) => void;
+ }
+ );
+
export function extractHeadings(content: string): HeadingEntry[] {
const { body } = stripFrontmatter(content);
@@ -1347,12 +1358,10 @@ export function isSafeDocName(docName: string): boolean {
function applyDiskEventToLiveAllFilesIndex(
event: DiskEvent,
- getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry>,
+ getAllFilesIndex: () => AllFileEntries,
): void {
const live = getAllFilesIndex();
- if (live instanceof Map) {
- updateFileIndex(event, live);
- }
+ if (live instanceof Map) updateFileIndex(event, live);
}
export interface CommentDocHooks {
@@ -1523,6 +1532,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension & {
resolveDocPath,
extractHeadings,
getFileIndex,
+ getFileIndexGeneration,
log,
ready,
contentFilter,
diff --git a/packages/server/src/api-file-ops.test.ts b/packages/server/src/api-file-ops.test.ts
index d7cc0b275..98598fc70 100644
--- a/packages/server/src/api-file-ops.test.ts
+++ b/packages/server/src/api-file-ops.test.ts
@@ -2163,6 +2163,121 @@ describe('file operation API routes', () => {
expect(assetPathsFromDocumentList(after)).toContain('docs/bar.png');
});
+ test('cached canonical asset is excluded without a generation change', async () => {
+ const dir = setupTmpDir();
+ const a = join(dir, 'a.csv');
+ const b = join(dir, 'b.csv');
+ const linked = join(dir, 'linked.csv');
+ const source = join(dir, 'source.md');
+ const ignore = join(dir, '.okignore');
+ const sourceContent = '# Source\n\n[A](a.csv)\n\n[Linked](linked.csv)\n';
+ writeFileSync(a, 'a,admitted\n');
+ writeFileSync(b, 'b,admitted\n');
+ symlinkSync(b, linked);
+ writeFileSync(source, sourceContent);
+ writeFileSync(ignore, '');
+ const sourceStat = statSync(source);
+ const bStat = statSync(b);
+ const filter = createContentFilter({ projectDir: dir, contentDir: dir });
+ const fileIndex = new Map(buildFileIndex(dir));
+ const indexedSource = fileIndex.get('source');
+ expect(indexedSource).toBeDefined();
+ expect(fileIndex.has('b.csv')).toBe(false);
+ const api = await createTestApiExtension(dir, {
+ contentFilter: filter,
+ getFileIndex: () => fileIndex,
+ });
+
+ const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
+ expect(before.status).toBe(200);
+ const listed = (response: CapturedResponse) =>
+ (
+ JSON.parse(response.body) as {
+ documents: Array<{
+ kind: string;
+ path?: string;
+ size?: number;
+ modified?: string;
+ referencedBy?: string[];
+ }>;
+ }
+ ).documents;
+ expect(listed(before).filter((row) => row.path === 'a.csv')).toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ expect(listed(before).filter((row) => row.path === 'b.csv')).toEqual([
+ expect.objectContaining({
+ kind: 'asset',
+ path: 'b.csv',
+ size: bStat.size,
+ modified: bStat.mtime.toISOString(),
+ referencedBy: ['source'],
+ }),
+ ]);
+
+ writeFileSync(ignore, 'b.csv\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(true);
+ expect(filter.isPathIgnored('linked.csv')).toBe(false);
+ expect(filter.isPathIgnored('a.csv')).toBe(false);
+ expect(fileIndex.get('source')).toBe(indexedSource);
+ const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
+ expect(after.status).toBe(200);
+ expect.soft(listed(after).filter((row) => row.path === 'b.csv')).toEqual([]);
+ expect
+ .soft(listed(after).filter((row) => row.path === 'a.csv'))
+ .toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).size).toBe(sourceStat.size);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ expect(readFileSync(a, 'utf8')).toBe('a,admitted\n');
+ expect(readFileSync(b, 'utf8')).toBe('b,admitted\n');
+ expect(readFileSync(linked, 'utf8')).toBe('b,admitted\n');
+ expect(statSync(linked).ino).toBe(statSync(b).ino);
+ });
+
+ test('configured filter retains explicit referenced-asset invalidation', async () => {
+ const dir = setupTmpDir();
+ const source = join(dir, 'source.md');
+ const foo = join(dir, 'foo.png');
+ const bar = join(dir, 'bar.png');
+ writeFileSync(source, '![foo](foo.png)\n');
+ writeFileSync(foo, 'foo bytes');
+ writeFileSync(bar, 'bar bytes');
+ writeFileSync(join(dir, '.okignore'), '');
+ const filter = createContentFilter({ projectDir: dir, contentDir: dir });
+ const fileIndex = new Map(buildFileIndex(dir));
+ const indexedSource = fileIndex.get('source');
+ let invalidate: (() => void) | null = null;
+ const api = await createTestApiExtension(dir, {
+ contentFilter: filter,
+ getFileIndex: () => fileIndex,
+ onReferencedAssetsCacheInvalidator: (registered) => {
+ invalidate = registered;
+ },
+ });
+
+ const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
+ expect(before.status).toBe(200);
+ expect(assetPathsFromDocumentList(before)).toEqual(['foo.png']);
+ writeFileSync(source, '![bar](bar.png)\n');
+ expect(fileIndex.get('source')).toBe(indexedSource);
+ expect(filter.isPathIgnored('foo.png')).toBe(false);
+ expect(filter.isPathIgnored('bar.png')).toBe(false);
+ const stale = await callApiExtension(api, '/api/documents', 'GET', undefined);
+ expect(stale.status).toBe(200);
+ expect(assetPathsFromDocumentList(stale)).toEqual(['foo.png']);
+ expect(invalidate).not.toBeNull();
+ invalidate?.();
+ const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
+ expect(after.status).toBe(200);
+ expect(assetPathsFromDocumentList(after)).toEqual(['bar.png']);
+ expect(readFileSync(foo, 'utf8')).toBe('foo bytes');
+ expect(readFileSync(bar, 'utf8')).toBe('bar bytes');
+ });
+
test('asset trash cleanup invalidates the cached document list asset row', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
diff --git a/packages/server/src/api-search.test.ts b/packages/server/src/api-search.test.ts
index 5a6922419..45a6940f5 100644
--- a/packages/server/src/api-search.test.ts
+++ b/packages/server/src/api-search.test.ts
@@ -655,6 +655,72 @@ describe('GET /api/search — symlink alias handling (D16)', () => {
});
});
+test('a no-generation search cache follows only searchable member-name changes', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-search-members-'));
+ try {
+ const representative = join(dir, 'amberpilot.csv');
+ writeFileSync(representative, 'member bytes\n', 'utf-8');
+ const baseline = indexEntry(representative, 'file');
+ const rich = {
+ ...baseline,
+ aliases: [],
+ fileMembers: {
+ regularPaths: ['amberpilot.csv'],
+ symlinks: [{ path: 'linked-indigo.csv', targetPath: 'amberpilot.csv' }],
+ },
+ };
+ const index = new Map<string, FileIndexEntry>([['amberpilot.csv', rich]]);
+ const ext = createApiExtension({
+ hocuspocus: {} as unknown as Parameters<typeof createApiExtension>[0]['hocuspocus'],
+ sessionManager: {} as unknown as Parameters<typeof createApiExtension>[0]['sessionManager'],
+ contentDir: dir,
+ serverInstanceId: 'test-server',
+ getFileIndex: () => new Map<string, FileIndexEntry>(),
+ getAllFilesIndex: () => index,
+ });
+ const fileMatches = async (name: string) => {
+ const req = makeReq('GET', `/api/search?query=${name}&intent=omnibar`);
+ const { res, captured } = makeRes();
+ await (
+ ext as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request: req, response: res });
+ expect(captured.status).toBe(200);
+ return (
+ JSON.parse(captured.body) as { results: Array<{ kind: string; path: string }> }
+ ).results
+ .filter((row) => row.kind === 'file')
+ .map(({ kind, path }) => ({ kind, path }));
+ };
+
+ expect(await fileMatches('amberpilot')).toEqual([{ kind: 'file', path: 'amberpilot.csv' }]);
+ expect(await fileMatches('beaconquartz')).toEqual([]);
+ expect
+ .soft(await fileMatches('linked-indigo'))
+ .toEqual([{ kind: 'file', path: 'amberpilot.csv' }]);
+
+ const withMember = {
+ ...rich,
+ fileMembers: {
+ ...rich.fileMembers,
+ regularPaths: ['amberpilot.csv', 'beaconquartz.csv'],
+ },
+ };
+ index.set('amberpilot.csv', withMember);
+ expect
+ .soft(await fileMatches('beaconquartz'))
+ .toEqual([{ kind: 'file', path: 'amberpilot.csv' }]);
+ expect(await fileMatches('amberpilot')).toEqual([{ kind: 'file', path: 'amberpilot.csv' }]);
+
+ index.set('amberpilot.csv', rich);
+ expect.soft(await fileMatches('beaconquartz')).toEqual([]);
+ expect(await fileMatches('amberpilot')).toEqual([{ kind: 'file', path: 'amberpilot.csv' }]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
describe('GET /api/search — operational budget (D15)', () => {
test('a name-only file entry is searchable without its content being read (AC20)', async () => {
const dir = mkdtempSync(join(tmpdir(), 'ok-search-noread-'));
diff --git a/packages/server/src/content-filter.ts b/packages/server/src/content-filter.ts
index 75d0e51ee..8cfcf5c61 100644
--- a/packages/server/src/content-filter.ts
+++ b/packages/server/src/content-filter.ts
@@ -587,7 +587,7 @@ export interface ContentFilterOptions {
attachmentFolderPath?: string;
inPlaceSkillDirs?: ReadonlySet<string>;
skillRootPaths?: ReadonlySet<string>;
- rescanInPlaceSkillDirs?: () => ReadonlySet<string>;
+ rescanInPlaceSkillDirs?: (priorAdmission: ReadonlySet<string>) => ReadonlySet<string>;
onAfterRebuild?: () => void;
}
@@ -964,7 +964,7 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {
refreshInPlaceSkillDirs(): void {
if (!opts.rescanInPlaceSkillDirs) return;
try {
- inPlaceSkillDirs = opts.rescanInPlaceSkillDirs();
+ inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
} catch (err) {
log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');
}
@@ -977,7 +977,7 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {
peekFreshInPlaceSkillDirsFingerprint(): string {
if (!opts.rescanInPlaceSkillDirs) return [...inPlaceSkillDirs].sort().join('\n');
try {
- return [...opts.rescanInPlaceSkillDirs()].sort().join('\n');
+ return [...opts.rescanInPlaceSkillDirs(inPlaceSkillDirs)].sort().join('\n');
} catch {
return [...inPlaceSkillDirs].sort().join('\n');
}
@@ -994,7 +994,7 @@ export function createContentFilter(opts: ContentFilterOptions): ContentFilter {
descendantProjects.reset();
if (opts.rescanInPlaceSkillDirs) {
try {
- inPlaceSkillDirs = opts.rescanInPlaceSkillDirs();
+ inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
} catch (err) {
log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');
}
@@ -1577,7 +1577,7 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Prom
refreshInPlaceSkillDirs(): void {
if (!opts.rescanInPlaceSkillDirs) return;
try {
- inPlaceSkillDirs = opts.rescanInPlaceSkillDirs();
+ inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
} catch (err) {
log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');
}
@@ -1590,7 +1590,7 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Prom
peekFreshInPlaceSkillDirsFingerprint(): string {
if (!opts.rescanInPlaceSkillDirs) return [...inPlaceSkillDirs].sort().join('\n');
try {
- return [...opts.rescanInPlaceSkillDirs()].sort().join('\n');
+ return [...opts.rescanInPlaceSkillDirs(inPlaceSkillDirs)].sort().join('\n');
} catch {
return [...inPlaceSkillDirs].sort().join('\n');
}
@@ -1607,7 +1607,7 @@ export async function createContentFilterAsync(opts: ContentFilterOptions): Prom
descendantProjects.reset();
if (opts.rescanInPlaceSkillDirs) {
try {
- inPlaceSkillDirs = opts.rescanInPlaceSkillDirs();
+ inPlaceSkillDirs = opts.rescanInPlaceSkillDirs(inPlaceSkillDirs);
} catch (err) {
log.warn({ err }, 'in-place skill re-scan failed — keeping previous allow-list');
}
diff --git a/packages/server/src/derived-document-index-boundary.type-tests.ts b/packages/server/src/derived-document-index-boundary.type-tests.ts
index 2e10599e5..33f5b0ef3 100644
--- a/packages/server/src/derived-document-index-boundary.type-tests.ts
+++ b/packages/server/src/derived-document-index-boundary.type-tests.ts
@@ -1,10 +1,12 @@
import { expectTypeOf } from 'vitest';
+import type { createApiExtension as createTestApiExtension } from './api-extension.test-helper.ts';
import type { ApiExtensionOptions } from './api-extension.ts';
import type {
DerivedDocumentIndexApiPort,
DerivedDocumentIndexLivePort,
DerivedDocumentIndexPersistencePort,
} from './derived-document-index.ts';
+import type { DiskEvent, FileIndexEntry } from './file-watcher.ts';
import type { LiveDerivedIndexOptions } from './live-derived-index.ts';
import type { PersistenceOptions } from './persistence.ts';
import type { ServerOptions } from './server-factory.ts';
@@ -50,3 +52,55 @@ expectTypeOf<Extract<ConsumerPortKey, RawIndexMember>>().toEqualTypeOf<never>();
expectTypeOf<
Extract<keyof ServerOptions, 'backlinkIndex' | 'tagIndex' | 'derivedDocumentIndex'>
>().toEqualTypeOf<never>();
+
+type AllFilesOptionBase = Omit<ApiExtensionOptions, 'getAllFilesIndex' | 'mutateFileIndex'>;
+type GeneralFileEntryIterable = Iterable<readonly [string, FileIndexEntry]>;
+type ExplicitIndexWriter = (event: DiskEvent) => void;
+type AcceptsApiOptions<T> = T extends ApiExtensionOptions ? true : false;
+
+type IterableWithWriter = AllFilesOptionBase & {
+ getAllFilesIndex: () => GeneralFileEntryIterable;
+ mutateFileIndex: ExplicitIndexWriter;
+};
+type IterableWithoutWriter = AllFilesOptionBase & {
+ getAllFilesIndex: () => GeneralFileEntryIterable;
+};
+type LegacyMapGetter = AllFilesOptionBase & {
+ getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry>;
+};
+type WriterWithDefaultGetter = AllFilesOptionBase & {
+ mutateFileIndex: ExplicitIndexWriter;
+};
+
+expectTypeOf<AcceptsApiOptions<IterableWithWriter>>().toEqualTypeOf<true>();
+expectTypeOf<AcceptsApiOptions<IterableWithoutWriter>>().toEqualTypeOf<false>();
+expectTypeOf<AcceptsApiOptions<LegacyMapGetter>>().toEqualTypeOf<true>();
+expectTypeOf<AcceptsApiOptions<AllFilesOptionBase>>().toEqualTypeOf<true>();
+expectTypeOf<AcceptsApiOptions<WriterWithDefaultGetter>>().toEqualTypeOf<true>();
+
+type TestHelperOptions = Parameters<typeof createTestApiExtension>[0];
+type TestHelperOptionBase = Omit<TestHelperOptions, 'getAllFilesIndex' | 'mutateFileIndex'>;
+type AcceptsTestHelperOptions<T> = T extends TestHelperOptions ? true : false;
+
+expectTypeOf<
+ AcceptsTestHelperOptions<
+ TestHelperOptionBase & {
+ getAllFilesIndex: () => GeneralFileEntryIterable;
+ mutateFileIndex: ExplicitIndexWriter;
+ }
+ >
+>().toEqualTypeOf<true>();
+expectTypeOf<
+ AcceptsTestHelperOptions<
+ TestHelperOptionBase & { getAllFilesIndex: () => GeneralFileEntryIterable }
+ >
+>().toEqualTypeOf<false>();
+expectTypeOf<
+ AcceptsTestHelperOptions<
+ TestHelperOptionBase & { getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry> }
+ >
+>().toEqualTypeOf<true>();
+expectTypeOf<AcceptsTestHelperOptions<TestHelperOptionBase>>().toEqualTypeOf<true>();
+expectTypeOf<
+ AcceptsTestHelperOptions<TestHelperOptionBase & { mutateFileIndex: ExplicitIndexWriter }>
+>().toEqualTypeOf<true>();
diff --git a/packages/server/src/derived-document-index.ts b/packages/server/src/derived-document-index.ts
index 329cc23a7..4919be324 100644
--- a/packages/server/src/derived-document-index.ts
+++ b/packages/server/src/derived-document-index.ts
@@ -433,6 +433,13 @@ export class DerivedDocumentIndex
});
}
+ recordInventoryReconciled(): Promise<void> {
+ return this.runCommand(async () => {
+ this.reconcileLocalTargetInventory();
+ this.maybeSignalLocalTargets();
+ });
+ }
+
recordFileTargetUpsert(relativePath: string): Promise<void> {
return this.runCommand(async () => {
const inventory = this.reconcileLocalTargetInventory();
diff --git a/packages/server/src/file-watcher-allfiles.test.ts b/packages/server/src/file-watcher-allfiles.test.ts
index 4857bf691..ddecfa3c4 100644
--- a/packages/server/src/file-watcher-allfiles.test.ts
+++ b/packages/server/src/file-watcher-allfiles.test.ts
@@ -1,10 +1,23 @@
-import { mkdirSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { createContentFilter } from './content-filter.ts';
-import { handleRawEvents, lastKnownHash, startWatcher } from './file-watcher.ts';
+import { type AllFileEntries, lastKnownHash, startWatcher } from './file-watcher.ts';
+import {
+ forgetNativeSubscriptions,
+ nativeSubscriptionOn,
+} from './parcel-watcher-double.test-helper.ts';
+
+vi.mock('@parcel/watcher', async () => {
+ const { parcelWatcherModule } = await import('./parcel-watcher-double.test-helper.ts');
+ return parcelWatcherModule;
+});
+
+function indexedKinds(all: AllFileEntries, name: string) {
+ return [...all].filter(([indexedName]) => indexedName === name).map(([, entry]) => entry.kind);
+}
describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
let tmpDir: string;
@@ -15,6 +28,7 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
contentDir = resolve(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
lastKnownHash.clear();
+ forgetNativeSubscriptions();
});
afterEach(async () => {
@@ -31,15 +45,10 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
const handle = await startWatcher(contentDir, async () => {});
try {
const all = handle.getAllFilesIndex();
- expect(all.has('readme')).toBe(true);
- expect(all.has('data.csv')).toBe(true);
- expect(all.has('config.json')).toBe(true);
- expect(all.has('src/index.ts')).toBe(true);
-
- expect(all.get('readme')?.kind).toBe('markdown');
- expect(all.get('data.csv')?.kind).toBe('file');
- expect(all.get('config.json')?.kind).toBe('file');
- expect(all.get('src/index.ts')?.kind).toBe('file');
+ expect(indexedKinds(all, 'readme')).toEqual(['markdown']);
+ expect(indexedKinds(all, 'data.csv')).toEqual(['file']);
+ expect(indexedKinds(all, 'config.json')).toEqual(['file']);
+ expect(indexedKinds(all, 'src/index.ts')).toEqual(['file']);
} finally {
await handle.unsubscribe();
}
@@ -67,7 +76,7 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
});
expect(collected).toEqual(['note']);
- expect(handle.getAllFilesIndex().size).toBe(3);
+ expect([...handle.getAllFilesIndex()]).toHaveLength(3);
} finally {
await handle.unsubscribe();
}
@@ -93,11 +102,10 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
expect(lastKnownHash.size).toBe(2);
const all = handle.getAllFilesIndex();
- expect(all.has('logo.svg')).toBe(true);
- expect(all.has('data.csv')).toBe(true);
- expect(all.has('binary.bin')).toBe(true);
- expect(all.has('shell.sh')).toBe(true);
- expect(all.get('logo.svg')?.kind).toBe('file');
+ expect(indexedKinds(all, 'logo.svg')).toEqual(['file']);
+ expect(indexedKinds(all, 'data.csv')).toEqual(['file']);
+ expect(indexedKinds(all, 'binary.bin')).toEqual(['file']);
+ expect(indexedKinds(all, 'shell.sh')).toEqual(['file']);
} finally {
await handle.unsubscribe();
}
@@ -114,10 +122,9 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
const handle = await startWatcher(contentDir, async () => {}, filter);
try {
const all = handle.getAllFilesIndex();
- expect(all.has('app.ts')).toBe(true);
- expect(all.get('app.ts')?.kind).toBe('file');
- expect(all.has('readme')).toBe(true);
- expect(all.has('dist/bundle.js')).toBe(false);
+ expect(indexedKinds(all, 'app.ts')).toEqual(['file']);
+ expect(indexedKinds(all, 'readme')).toEqual(['markdown']);
+ expect(indexedKinds(all, 'dist/bundle.js')).toEqual([]);
} finally {
await handle.unsubscribe();
}
@@ -129,20 +136,10 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
try {
const newFile = resolve(contentDir, 'fresh.ts');
writeFileSync(newFile, 'export const fresh = true;');
- await handleRawEvents(
- [{ type: 'create', path: newFile }],
- contentDir,
- undefined,
- // biome-ignore lint/suspicious/noExplicitAny: test reaches the inner map for live admission verification
- handle.getAllFilesIndex() as any,
- // biome-ignore lint/suspicious/noExplicitAny: test reaches the inner map for live admission verification
- handle.getFolderIndex() as any,
- async () => {},
- );
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: newFile }]);
const all = handle.getAllFilesIndex();
- expect(all.has('fresh.ts')).toBe(true);
- expect(all.get('fresh.ts')?.kind).toBe('file');
+ expect(indexedKinds(all, 'fresh.ts')).toEqual(['file']);
expect(lastKnownHash.has(newFile)).toBe(false);
} finally {
await handle.unsubscribe();
@@ -154,23 +151,16 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
writeFileSync(resolve(contentDir, 'old.txt'), 'old');
const handle = await startWatcher(contentDir, async () => {});
try {
- expect(handle.getAllFilesIndex().has('old.txt')).toBe(true);
- expect(handle.getAllFilesIndex().has('doc')).toBe(true);
-
- await handleRawEvents(
- [{ type: 'delete', path: resolve(contentDir, 'old.txt') }],
- contentDir,
- undefined,
- // biome-ignore lint/suspicious/noExplicitAny: see above
- handle.getAllFilesIndex() as any,
- // biome-ignore lint/suspicious/noExplicitAny: see above
- handle.getFolderIndex() as any,
- async () => {},
- );
-
- expect(handle.getAllFilesIndex().has('old.txt')).toBe(false);
- expect(handle.getAllFilesIndex().has('doc')).toBe(true);
- expect(handle.getAllFilesIndex().get('doc')?.kind).toBe('markdown');
+ expect(indexedKinds(handle.getAllFilesIndex(), 'old.txt')).toEqual(['file']);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doc')).toEqual(['markdown']);
+
+ unlinkSync(resolve(contentDir, 'old.txt'));
+ await nativeSubscriptionOn(contentDir).deliver([
+ { type: 'delete', path: resolve(contentDir, 'old.txt') },
+ ]);
+
+ expect(indexedKinds(handle.getAllFilesIndex(), 'old.txt')).toEqual([]);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doc')).toEqual(['markdown']);
} finally {
await handle.unsubscribe();
}
@@ -184,8 +174,8 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
const handle = await startWatcher(contentDir, async () => {});
try {
expect(handle.getFileIndex().has('doomed')).toBe(true);
- expect(handle.getAllFilesIndex().has('doomed')).toBe(true);
- expect(handle.getAllFilesIndex().has('doomed.txt')).toBe(true);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doomed')).toEqual(['markdown']);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doomed.txt')).toEqual(['file']);
handle.mutateFileIndex({
kind: 'delete',
@@ -198,8 +188,8 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
relativePath: 'doomed.txt',
});
- expect(handle.getAllFilesIndex().has('doomed')).toBe(false);
- expect(handle.getAllFilesIndex().has('doomed.txt')).toBe(false);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doomed')).toEqual([]);
+ expect(indexedKinds(handle.getAllFilesIndex(), 'doomed.txt')).toEqual([]);
expect(handle.getFileIndex().has('doomed')).toBe(false);
expect(handle.getFileIndex().has('survives')).toBe(true);
} finally {
@@ -237,12 +227,15 @@ describe('PRD-7117 US-001 — kind discriminator + all-files admission', () => {
const handle = await startWatcher(contentDir, async () => {});
try {
- const all = handle.getAllFilesIndex();
- const hasReal = all.has('real.csv');
- const hasAlias = all.has('alias.csv');
- expect(Number(hasReal) + Number(hasAlias)).toBe(1);
- const present = hasReal ? all.get('real.csv') : all.get('alias.csv');
- expect(present?.kind).toBe('file');
+ const all = [...handle.getAllFilesIndex()];
+ const files = all.filter(([, entry]) => entry.kind === 'file');
+ expect(files).toHaveLength(1);
+ expect(files[0]?.[0]).toBe('real.csv');
+ expect(files[0]?.[1]).toMatchObject({
+ kind: 'file',
+ canonicalPath: resolve(contentDir, 'real.csv'),
+ aliases: ['alias.csv'],
+ });
} finally {
await handle.unsubscribe();
}
diff --git a/packages/server/src/file-watcher-chokidar-fallback.test.ts b/packages/server/src/file-watcher-chokidar-fallback.test.ts
index 5f8eb78a7..f6d6d7243 100644
--- a/packages/server/src/file-watcher-chokidar-fallback.test.ts
+++ b/packages/server/src/file-watcher-chokidar-fallback.test.ts
@@ -1,18 +1,145 @@
-import { lstatSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import {
+ lstatSync,
+ mkdirSync,
+ readFileSync,
+ realpathSync,
+ rmdirSync,
+ statSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import type { FSWatcher } from 'chokidar';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { createContentFilter } from './content-filter.ts';
import {
type DiskEvent,
isChokidarPathIgnored,
lastKnownHash,
startWatcher,
+ type WatcherHandle,
writeTracker,
} from './file-watcher.ts';
import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
+type NativeDeleteKind = 'unlink' | 'unlinkDir';
+
+type NativeDeleteGate = {
+ kind: NativeDeleteKind;
+ path: string;
+ seen: PromiseWithResolvers<void>;
+ released: PromiseWithResolvers<void>;
+ delivered: PromiseWithResolvers<void>;
+ captured: boolean;
+ isReleased: boolean;
+ release: () => void;
+};
+
+const nativeTap = vi.hoisted(() => ({
+ watcher: null as FSWatcher | null,
+ handle: null as WatcherHandle | null,
+ gates: [] as NativeDeleteGate[],
+ observed: [] as Array<{ kind: NativeDeleteKind; path: string }>,
+}));
+
+vi.mock('chokidar', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('chokidar')>();
+ return {
+ ...actual,
+ watch: (...args: Parameters<typeof actual.watch>) => {
+ const watcher = actual.watch(...args);
+ nativeTap.watcher = watcher;
+ const originalEmit = watcher.emit;
+ watcher.emit = ((event: string | symbol, ...args: unknown[]): boolean => {
+ const path = args[0];
+ if ((event === 'unlink' || event === 'unlinkDir') && typeof path === 'string') {
+ nativeTap.observed.push({ kind: event, path });
+ const gate = nativeTap.gates.find(
+ (candidate) => candidate.kind === event && candidate.path === path,
+ );
+ if (gate && !gate.isReleased && !gate.captured) {
+ gate.captured = true;
+ gate.seen.resolve();
+ void gate.released.promise.then(() => {
+ try {
+ Reflect.apply(originalEmit, watcher, [event, ...args]);
+ gate.delivered.resolve();
+ } catch (error) {
+ gate.delivered.reject(error);
+ }
+ });
+ return true;
+ }
+ }
+ return Reflect.apply(originalEmit, watcher, [event, ...args]) as boolean;
+ }) as typeof watcher.emit;
+ return watcher;
+ },
+ };
+});
+
+function holdNativeDeletion(kind: NativeDeleteKind, path: string): NativeDeleteGate {
+ const seen = Promise.withResolvers<void>();
+ const released = Promise.withResolvers<void>();
+ const delivered = Promise.withResolvers<void>();
+ const gate: NativeDeleteGate = {
+ kind,
+ path,
+ seen,
+ released,
+ delivered,
+ captured: false,
+ isReleased: false,
+ release: () => {
+ if (gate.isReleased) return;
+ gate.isReleased = true;
+ released.resolve();
+ },
+ };
+ nativeTap.gates.push(gate);
+ return gate;
+}
+
+async function runNativeDeleteCase(
+ contentDir: string,
+ events: DiskEvent[],
+ batches: string[][],
+ terminal: PromiseWithResolvers<void>,
+ body: (handle: WatcherHandle) => Promise<void>,
+): Promise<void> {
+ let handle: WatcherHandle | undefined;
+ let bodyError: unknown;
+ try {
+ handle = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind === 'file-delete' && event.relativePath === 'tail.png') terminal.resolve();
+ },
+ undefined,
+ { forceBackend: 'chokidar', onRawBatch: (paths) => batches.push([...paths]) },
+ );
+ nativeTap.handle = handle;
+ await body(handle);
+ } catch (error) {
+ bodyError = error;
+ }
+ for (const gate of nativeTap.gates) gate.release();
+ let cleanupError: unknown;
+ try {
+ await handle?.unsubscribe();
+ nativeTap.handle = null;
+ } catch (error) {
+ cleanupError = error;
+ }
+ if (bodyError && cleanupError)
+ throw new AggregateError([bodyError, cleanupError], 'native deletion body and cleanup failed');
+ if (bodyError) throw bodyError;
+ if (cleanupError) throw cleanupError;
+}
+
describe('isChokidarPathIgnored — stats matrix', () => {
let tmpDir: string;
let contentDir: string;
@@ -245,3 +372,146 @@ describe('chokidar backend — templates-as-content watching (forceBackend)', ()
}
});
});
+
+describe('chokidar backend — deletion roles with overlapping indexes', () => {
+ let tmpDir: string;
+ let contentDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-chokidar-kinds-'));
+ contentDir = resolve(tmpDir, 'content');
+ mkdirSync(contentDir);
+ contentDir = realpathSync(contentDir);
+ lastKnownHash.clear();
+ writeTracker.clear();
+ nativeTap.watcher = null;
+ nativeTap.gates = [];
+ nativeTap.observed = [];
+ });
+
+ afterEach(async () => {
+ for (const gate of nativeTap.gates) gate.release();
+ await Promise.resolve();
+ await nativeTap.handle?.unsubscribe();
+ nativeTap.handle = null;
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ test('a real unlinkDir retains a newer document at the same path', async () => {
+ const entry = resolve(contentDir, 'entry.md');
+ const tail = resolve(contentDir, 'tail.png');
+ mkdirSync(entry);
+ writeFileSync(tail, 'tail bytes');
+ const events: DiskEvent[] = [];
+ const batches: string[][] = [];
+ const terminal = Promise.withResolvers<void>();
+ const folderDelete = holdNativeDeletion('unlinkDir', entry);
+ const tailDelete = holdNativeDeletion('unlink', tail);
+
+ await runNativeDeleteCase(contentDir, events, batches, terminal, async (handle) => {
+ expect(nativeTap.watcher).not.toBeNull();
+ expect(handle.getFolderIndex().has('entry.md')).toBe(true);
+ expect(handle.getFileIndex().has('entry')).toBe(false);
+
+ rmdirSync(entry);
+ await folderDelete.seen.promise;
+ expect(nativeTap.observed).toContainEqual({ kind: 'unlinkDir', path: entry });
+ writeFileSync(entry, '# Replacement\n');
+ handle.mutateFileIndex({
+ kind: 'create',
+ path: entry,
+ docName: 'entry',
+ content: '# Replacement\n',
+ });
+ expect(handle.getFolderIndex().has('entry.md')).toBe(true);
+ expect(handle.getFileIndex().get('entry')?.canonicalPath).toBe(entry);
+ expect(readFileSync(entry, 'utf8')).toBe('# Replacement\n');
+
+ unlinkSync(tail);
+ await tailDelete.seen.promise;
+ folderDelete.release();
+ tailDelete.release();
+ await Promise.all([
+ folderDelete.delivered.promise,
+ tailDelete.delivered.promise,
+ terminal.promise,
+ ]);
+
+ expect(batches.some((batch) => batch.includes(entry) && batch.includes(tail))).toBe(true);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'folder-delete', relativePath: 'entry.md' }),
+ );
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-delete', relativePath: 'tail.png' }),
+ );
+ expect
+ .soft(events.some((event) => event.kind === 'delete' && event.docName === 'entry'))
+ .toBe(false);
+ expect(handle.getFolderIndex().has('entry.md')).toBe(false);
+ expect.soft(new Map(handle.getAllFilesIndex()).get('entry')?.canonicalPath).toBe(entry);
+ expect(readFileSync(entry, 'utf8')).toBe('# Replacement\n');
+ });
+ });
+
+ test('a real file unlink retains a newer directory and child at the same path', async () => {
+ const entry = resolve(contentDir, 'entry.md');
+ const child = resolve(entry, 'child.md');
+ const tail = resolve(contentDir, 'tail.png');
+ writeFileSync(entry, '# Prior file\n');
+ writeFileSync(tail, 'tail bytes');
+ const events: DiskEvent[] = [];
+ const batches: string[][] = [];
+ const terminal = Promise.withResolvers<void>();
+ const fileDelete = holdNativeDeletion('unlink', entry);
+ const tailDelete = holdNativeDeletion('unlink', tail);
+
+ await runNativeDeleteCase(contentDir, events, batches, terminal, async (handle) => {
+ expect(nativeTap.watcher).not.toBeNull();
+ expect(handle.getFileIndex().get('entry')?.canonicalPath).toBe(entry);
+ expect(handle.getFolderIndex().has('entry.md')).toBe(false);
+
+ unlinkSync(entry);
+ await fileDelete.seen.promise;
+ expect(nativeTap.observed).toContainEqual({ kind: 'unlink', path: entry });
+ mkdirSync(entry);
+ writeFileSync(child, '# Live child\n');
+ await handle.rescanFromDisk();
+ expect(handle.getFileIndex().get('entry')?.canonicalPath).toBe(entry);
+ expect(handle.getFolderIndex().has('entry.md')).toBe(true);
+ expect(handle.getFileIndex().get('entry.md/child')?.canonicalPath).toBe(child);
+ expect(readFileSync(child, 'utf8')).toBe('# Live child\n');
+
+ unlinkSync(tail);
+ await tailDelete.seen.promise;
+ fileDelete.release();
+ tailDelete.release();
+ await Promise.all([
+ fileDelete.delivered.promise,
+ tailDelete.delivered.promise,
+ terminal.promise,
+ ]);
+
+ expect(batches.some((batch) => batch.includes(entry) && batch.includes(tail))).toBe(true);
+ expect(events).toContainEqual(expect.objectContaining({ kind: 'delete', docName: 'entry' }));
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-delete', relativePath: 'tail.png' }),
+ );
+ expect
+ .soft(
+ events.some(
+ (event) => event.kind === 'folder-delete' && event.relativePath === 'entry.md',
+ ),
+ )
+ .toBe(false);
+ expect
+ .soft(events.some((event) => event.kind === 'delete' && event.docName === 'entry.md/child'))
+ .toBe(false);
+ expect(new Map(handle.getAllFilesIndex()).has('entry')).toBe(false);
+ expect.soft(handle.getFolderIndex().has('entry.md')).toBe(true);
+ expect
+ .soft(new Map(handle.getAllFilesIndex()).get('entry.md/child')?.canonicalPath)
+ .toBe(child);
+ expect(readFileSync(child, 'utf8')).toBe('# Live child\n');
+ });
+ });
+});
diff --git a/packages/server/src/file-watcher.test.ts b/packages/server/src/file-watcher.test.ts
index e74a95fe6..3a10f43ef 100644
--- a/packages/server/src/file-watcher.test.ts
+++ b/packages/server/src/file-watcher.test.ts
@@ -2238,7 +2238,7 @@ describe('file index canonical path after a real rename', () => {
const handle = await startWatcher(contentDir, async () => {});
try {
return {
- fileIndex: new Map(handle.getAllFilesIndex()),
+ fileIndex: new Map(handle.getFileIndex()),
folderIndex: new Map(handle.getFolderIndex()),
aliasMap: new Map(handle.getAliasMap()),
};
diff --git a/packages/server/src/file-watcher.ts b/packages/server/src/file-watcher.ts
index dd57da008..767788723 100644
--- a/packages/server/src/file-watcher.ts
+++ b/packages/server/src/file-watcher.ts
@@ -16,9 +16,11 @@ import { type ContentFilter, WATCHER_STRUCTURAL_IGNORE_DIRS } from './content-fi
import { isWithinContentDir } from './content-path.ts';
import {
forgetDocExtension,
+ getDocExtension,
isSupportedAssetFile,
isSupportedDocFile,
registerDocExtension,
+ SUPPORTED_DOC_EXTENSIONS,
stripDocExtension,
} from './doc-extensions.ts';
import { resolvesIntoPrivateState } from './fs-safety.ts';
@@ -31,6 +33,7 @@ import {
extractPageTitle,
extractPageType,
} from './page-identity.ts';
+import { classifyParcelNotification } from './parcel-recovery.ts';
import { subscribeParcel } from './parcel-subscription.ts';
import { toPosix } from './path-utils.ts';
import { containsConflictMarkers } from './reconciliation.ts';
@@ -104,6 +107,13 @@ export function assertNeverDiskEvent(event: never): never {
throw new Error(`[DiskEvent] unhandled variant: ${JSON.stringify(event)}`);
}
+export type AllFileEntries = Iterable<readonly [string, FileIndexEntry]>;
+
+interface GeneralFileMembers {
+ readonly regularPaths: readonly string[];
+ readonly symlinks: readonly { readonly path: string; readonly targetPath: string }[];
+}
+
export interface FileIndexEntry {
size: number;
modified: string;
@@ -111,12 +121,56 @@ export interface FileIndexEntry {
inode: number;
aliases: string[];
kind: 'markdown' | 'file';
+ fileMembers?: GeneralFileMembers;
title?: string;
icon?: string;
description?: string;
type?: string;
}
+interface FileIndexEntryMember {
+ readonly path: string;
+ readonly role: 'regular' | 'symlink';
+ readonly targetPath: string;
+}
+
+interface FileIndexEntryMembership {
+ readonly resolved: boolean;
+ readonly members: readonly FileIndexEntryMember[];
+}
+
+export function fileIndexEntryMembers(
+ contentDir: string,
+ name: string,
+ entry: FileIndexEntry,
+): FileIndexEntryMembership {
+ if (entry.kind === 'file' && entry.fileMembers) {
+ return {
+ resolved: true,
+ members: [
+ ...entry.fileMembers.regularPaths.map(
+ (path): FileIndexEntryMember => ({ path, role: 'regular', targetPath: path }),
+ ),
+ ...entry.fileMembers.symlinks.map(
+ (relation): FileIndexEntryMember => ({
+ path: relation.path,
+ role: 'symlink',
+ targetPath: relation.targetPath,
+ }),
+ ),
+ ],
+ };
+ }
+ const targetPath = toPosix(relative(contentDir, entry.canonicalPath));
+ return {
+ resolved: false,
+ members: [
+ { path: name, role: 'regular', targetPath },
+ ...entry.aliases.map((path): FileIndexEntryMember => ({ path, role: 'symlink', targetPath })),
+ ],
+ };
+}
+
export interface FolderIndexEntry {
size: 0;
modified: string;
@@ -154,7 +208,7 @@ function markdownIndexView(
export interface WatcherHandle {
unsubscribe: () => Promise<void>;
getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
- getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ getAllFilesIndex: () => AllFileEntries;
getFileIndexGeneration: () => number;
getFolderIndex: () => ReadonlyMap<string, FolderIndexEntry>;
getAliasMap: () => ReadonlyMap<string, string>;
@@ -437,11 +491,34 @@ interface RawFileEvent {
path: string;
}
+type KnownDeletion = {
+ type: 'delete';
+ path: string;
+ entryKind: 'file' | 'folder';
+};
+
+type RecoveredFileEvent = { type: 'create' | 'update'; path: string } | KnownDeletion;
+type InternalRawFileEvent = RawFileEvent | KnownDeletion;
+
export async function classifyEvents(
rawEvents: RawFileEvent[],
contentDir: string,
contentFilter?: ContentFilter,
aliasMap?: Map<string, string>,
+): Promise<MarkdownDiskEvent[]> {
+ return classifyEventsInternal(rawEvents, contentDir, contentFilter, aliasMap);
+}
+
+async function classifyEventsInternal(
+ rawEvents: RawFileEvent[],
+ contentDir: string,
+ contentFilter?: ContentFilter,
+ aliasMap?: Map<string, string>,
+ aliasContext?: {
+ fileIndex: ReadonlyMap<string, FileIndexEntry>;
+ aliasPaths: ReadonlyMap<string, string>;
+ canonicalRecords: Set<RawFileEvent>;
+ },
): Promise<MarkdownDiskEvent[]> {
const deletes: RawFileEvent[] = [];
const creates: RawFileEvent[] = [];
@@ -459,9 +536,24 @@ export async function classifyEvents(
}
switch (event.type) {
- case 'delete':
+ case 'delete': {
+ if (aliasContext) {
+ const name = pathToDocName(event.path, contentDir);
+ const owner = aliasContext.fileIndex.get(name);
+ const canonicalPath = owner?.kind === 'markdown' ? owner.canonicalPath : undefined;
+ const aliasPath = aliasMap?.has(name) ? aliasContext.aliasPaths.get(name) : undefined;
+ if (
+ (canonicalPath !== undefined || aliasPath !== undefined) &&
+ canonicalPath !== event.path &&
+ aliasPath !== event.path
+ ) {
+ removeLastKnownHash(event.path);
+ continue;
+ }
+ }
deletes.push(event);
break;
+ }
case 'create':
if (lastKnownHash.has(event.path)) {
updates.push(event);
@@ -498,7 +590,8 @@ export async function classifyEvents(
}
}
- function resolveDocName(rawPath: string): string {
+ function resolveDocName(event: RawFileEvent): string {
+ const rawPath = event.path;
const raw = pathToDocName(rawPath, contentDir);
if (!aliasMap) return raw;
@@ -518,6 +611,19 @@ export async function classifyEvents(
}
if (!lst.isSymbolicLink()) {
+ const owner = aliasContext?.fileIndex.get(raw);
+ const aliasPath = aliasContext?.aliasPaths.get(raw);
+ if (
+ event.type !== 'delete' &&
+ owner?.kind === 'markdown' &&
+ owner.canonicalPath === rawPath &&
+ aliasMap.has(raw) &&
+ aliasPath !== undefined &&
+ aliasPath !== rawPath
+ ) {
+ aliasContext?.canonicalRecords.add(event);
+ return raw;
+ }
if (aliasMap.has(raw)) aliasMap.delete(raw);
return raw;
}
@@ -540,7 +646,6 @@ export async function classifyEvents(
}
const canonicalDocName = pathToDocName(canonical, contentDir);
- if (canonicalDocName === raw) return raw;
aliasMap.set(raw, canonicalDocName);
return canonicalDocName;
}
@@ -566,8 +671,8 @@ export async function classifyEvents(
kind: 'rename',
oldPath: del.path,
newPath: create.path,
- oldDocName: resolveDocName(del.path),
- newDocName: resolveDocName(create.path),
+ oldDocName: resolveDocName(del),
+ newDocName: resolveDocName(create),
content,
});
break;
@@ -581,7 +686,7 @@ export async function classifyEvents(
results.push({
kind: 'delete',
path: del.path,
- docName: resolveDocName(del.path),
+ docName: resolveDocName(del),
});
}
@@ -596,14 +701,14 @@ export async function classifyEvents(
results.push({
kind: 'conflict',
path: create.path,
- docName: resolveDocName(create.path),
+ docName: resolveDocName(create),
content,
});
} else {
results.push({
kind: 'create',
path: create.path,
- docName: resolveDocName(create.path),
+ docName: resolveDocName(create),
content,
});
}
@@ -619,14 +724,14 @@ export async function classifyEvents(
results.push({
kind: 'conflict',
path: update.path,
- docName: resolveDocName(update.path),
+ docName: resolveDocName(update),
content,
});
} else {
results.push({
kind: 'update',
path: update.path,
- docName: resolveDocName(update.path),
+ docName: resolveDocName(update),
content,
});
}
@@ -648,18 +753,790 @@ export function isSelfWrite(filePath: string, hash: string): boolean {
return true;
}
-async function seedLastKnownHashes(
+interface DiskObservation {
+ fileIndex: Map<string, FileIndexEntry>;
+ generalFileIndex: GeneralFileIndex;
+ folderIndex: Map<string, FolderIndexEntry>;
+ aliasMap: Map<string, string>;
+ aliasPaths: Map<string, string>;
+ folderAliasIndex: Map<string, string>;
+ hashes: Map<string, string>;
+ extensions: Array<{ docName: string; ext: string }>;
+ preferredExtensions: Map<string, string>;
+ structuralIgnoreDirs: Set<string>;
+ paths: Set<string>;
+ complete: boolean;
+}
+
+type GeneralIdentity = { device: number; inode: number };
+type KnownGeneralEntry = FileIndexEntry & { kind: 'file'; fileMembers: GeneralFileMembers };
+type GeneralFileState =
+ | { kind: 'known'; entry: KnownGeneralEntry; identity: GeneralIdentity; sequence: number }
+ | { kind: 'unresolved'; reportedPath: string; sequence: number };
+type GeneralMetadata = { size: number; modified: string };
+
+const generalFileStates = new WeakMap<FileIndexEntry, GeneralFileState>();
+let generalFileSequence = 0;
+
+function knownGeneralState(
+ entry: FileIndexEntry,
+): Extract<GeneralFileState, { kind: 'known' }> | null {
+ const state = generalFileStates.get(entry);
+ return state?.kind === 'known' ? state : null;
+}
+
+function sameGeneralIdentity(left: GeneralIdentity, right: GeneralIdentity): boolean {
+ return left.device === right.device && left.inode === right.inode;
+}
+
+function generalIdentityKey(identity: GeneralIdentity): string {
+ return `${identity.device}:${identity.inode}`;
+}
+
+function addGeneralOwner(owners: Map<string, Set<string>>, key: string, name: string): void {
+ const names = owners.get(key);
+ if (names) names.add(name);
+ else owners.set(key, new Set([name]));
+}
+
+function removeGeneralOwner(owners: Map<string, Set<string>>, key: string, name: string): void {
+ const names = owners.get(key);
+ if (!names) return;
+ names.delete(name);
+ if (names.size === 0) owners.delete(key);
+}
+
+class GeneralFileIndex implements ReadonlyMap<string, FileIndexEntry> {
+ readonly #contentDir: string;
+ readonly #entries = new Map<string, FileIndexEntry>();
+ readonly #linked = new Map<
+ string,
+ { readonly members: readonly string[]; readonly identity: string | null }
+ >();
+ readonly #members = new Map<string, Set<string>>();
+ readonly #identities = new Map<string, Set<string>>();
+
+ constructor(contentDir: string) {
+ this.#contentDir = contentDir;
+ }
+
+ get size(): number {
+ return this.#entries.size;
+ }
+
+ get(name: string): FileIndexEntry | undefined {
+ return this.#entries.get(name);
+ }
+
+ has(name: string): boolean {
+ return this.#entries.has(name);
+ }
+
+ keys(): MapIterator<string> {
+ return this.#entries.keys();
+ }
+
+ values(): MapIterator<FileIndexEntry> {
+ return this.#entries.values();
+ }
+
+ entries(): MapIterator<[string, FileIndexEntry]> {
+ return this.#entries.entries();
+ }
+
+ [Symbol.iterator](): MapIterator<[string, FileIndexEntry]> {
+ return this.#entries[Symbol.iterator]();
+ }
+
+ forEach(
+ callback: (
+ entry: FileIndexEntry,
+ name: string,
+ index: ReadonlyMap<string, FileIndexEntry>,
+ ) => void,
+ thisArg?: unknown,
+ ): void {
+ for (const [name, entry] of this.#entries) callback.call(thisArg, entry, name, this);
+ }
+
+ ownersOfPath(path: string): ReadonlySet<string> | undefined {
+ return this.#members.get(path);
+ }
+
+ ownersOfIdentity(identity: GeneralIdentity): ReadonlySet<string> | undefined {
+ return this.#identities.get(generalIdentityKey(identity));
+ }
+
+ set(name: string, entry: FileIndexEntry): void {
+ Object.freeze(entry.aliases);
+ Object.freeze(entry);
+ this.#unlink(name);
+ this.#entries.set(name, entry);
+ this.#link(name, entry);
+ }
+
+ delete(name: string): void {
+ this.#unlink(name);
+ this.#entries.delete(name);
+ }
+
+ clear(): void {
+ this.#entries.clear();
+ this.#linked.clear();
+ this.#members.clear();
+ this.#identities.clear();
+ }
+
+ #link(name: string, entry: FileIndexEntry): void {
+ const members = fileIndexEntryMembers(this.#contentDir, name, entry).members.map(
+ (member) => member.path,
+ );
+ for (const member of members) addGeneralOwner(this.#members, member, name);
+ const state = knownGeneralState(entry);
+ const identity = state ? generalIdentityKey(state.identity) : null;
+ if (identity !== null) addGeneralOwner(this.#identities, identity, name);
+ this.#linked.set(name, { members, identity });
+ }
+
+ #unlink(name: string): void {
+ const linked = this.#linked.get(name);
+ if (!linked) return;
+ for (const member of linked.members) removeGeneralOwner(this.#members, member, name);
+ if (linked.identity !== null) removeGeneralOwner(this.#identities, linked.identity, name);
+ this.#linked.delete(name);
+ }
+}
+
+function generalOwnerNames(index: GeneralFileIndex, path: string): string[] {
+ return [...(index.ownersOfPath(path) ?? [])];
+}
+
+function generalFactsFor(
+ index: GeneralFileIndex,
+ paths: Iterable<string>,
+): Map<string, GeneralPathFact> {
+ const names = new Set<string>();
+ for (const path of paths) {
+ for (const name of index.ownersOfPath(path) ?? []) names.add(name);
+ }
+ const facts = new Map<string, GeneralPathFact>();
+ for (const name of names) {
+ const entry = index.get(name);
+ if (entry) addGeneralEntryFacts(facts, name, entry);
+ }
+ return facts;
+}
+
+function findKnownGeneralGroup(
+ index: GeneralFileIndex,
+ identity: GeneralIdentity,
+): [string, KnownGeneralEntry] | null {
+ for (const name of index.ownersOfIdentity(identity) ?? []) {
+ const entry = index.get(name);
+ const state = entry && knownGeneralState(entry);
+ if (state && sameGeneralIdentity(state.identity, identity)) return [name, state.entry];
+ }
+ return null;
+}
+
+function storeKnownGeneralGroup(
+ index: GeneralFileIndex,
+ contentDir: string,
+ previousName: string | null,
+ identity: GeneralIdentity,
+ regularPaths: readonly string[],
+ symlinks: GeneralFileMembers['symlinks'],
+ metadata: GeneralMetadata,
+ sequence = ++generalFileSequence,
+): void {
+ const regular = [...new Set(regularPaths)].toSorted();
+ if (previousName !== null) {
+ const current = index.get(previousName);
+ const currentState = current && knownGeneralState(current);
+ if (currentState && sameGeneralIdentity(currentState.identity, identity)) {
+ index.delete(previousName);
+ }
+ }
+ if (regular.length === 0) return;
+ const representative = previousName && regular.includes(previousName) ? previousName : regular[0];
+ const relations = [...new Map(symlinks.map((relation) => [relation.path, relation])).values()]
+ .filter((relation) => !regular.includes(relation.path))
+ .toSorted((left, right) => left.path.localeCompare(right.path));
+ const entry: KnownGeneralEntry = {
+ kind: 'file',
+ canonicalPath: join(contentDir, representative),
+ inode: identity.inode,
+ size: metadata.size,
+ modified: metadata.modified,
+ aliases: relations.map((relation) => relation.path),
+ fileMembers: { regularPaths: regular, symlinks: relations },
+ };
+ generalFileStates.set(entry, { kind: 'known', entry, identity, sequence });
+ index.set(representative, entry);
+}
+
+function storeUnresolvedGeneralEntry(
+ index: GeneralFileIndex,
+ contentDir: string,
+ event: Extract<FileDiskEvent, { kind: 'file-create' | 'file-update' }>,
+): void {
+ const name = toPosix(relative(contentDir, event.path));
+ const prior = index.get(name);
+ const entry: FileIndexEntry = {
+ kind: 'file',
+ canonicalPath: event.path,
+ inode: event.inode || prior?.inode || 0,
+ size: event.size,
+ modified: new Date(event.modifiedTs).toISOString(),
+ aliases:
+ prior?.kind === 'file'
+ ? fileIndexEntryMembers(contentDir, name, prior)
+ .members.filter((member) => member.role === 'symlink')
+ .map((member) => member.path)
+ : [],
+ };
+ generalFileStates.set(entry, {
+ kind: 'unresolved',
+ reportedPath: event.relativePath,
+ sequence: ++generalFileSequence,
+ });
+ index.set(name, entry);
+}
+
+function removeKnownGeneralPath(index: GeneralFileIndex, contentDir: string, path: string): void {
+ for (const name of generalOwnerNames(index, path)) {
+ const entry = index.get(name);
+ if (!entry) continue;
+ const state = knownGeneralState(entry);
+ if (!state) {
+ if (name === path) index.delete(name);
+ else if (entry.kind === 'file' && entry.aliases.includes(path)) {
+ index.set(name, {
+ ...entry,
+ aliases: entry.aliases.filter((alias) => alias !== path),
+ });
+ }
+ continue;
+ }
+ const members = state.entry.fileMembers;
+ const regular = members.regularPaths.filter((member) => member !== path);
+ const symlinks = members.symlinks.filter(
+ (relation) =>
+ relation.path !== path &&
+ (regular.length === members.regularPaths.length || relation.targetPath !== path),
+ );
+ if (
+ regular.length === members.regularPaths.length &&
+ symlinks.length === members.symlinks.length
+ )
+ continue;
+ storeKnownGeneralGroup(
+ index,
+ contentDir,
+ name,
+ state.identity,
+ regular,
+ symlinks,
+ entry,
+ state.sequence,
+ );
+ }
+}
+
+type GeneralRegistrationResult =
+ | { kind: 'applied'; changedPaths: ReadonlySet<string> }
+ | { kind: 'unobserved' };
+
+function registerKnownGeneralPath(
+ index: GeneralFileIndex,
+ contentDir: string,
+ canonicalName: string,
+ lexicalName: string,
+ leafSymlink: boolean,
+ identity: GeneralIdentity,
+ metadata: GeneralMetadata,
+ contentFilter?: ContentFilter,
+ confirmedAbsentFormerPath?: string,
+): GeneralRegistrationResult {
+ const changes = new Map<string, GeneralPathFact | null>();
+ const selectedFact = (path: string): GeneralPathFact | undefined =>
+ changes.has(path) ? (changes.get(path) ?? undefined) : generalFactsFor(index, [path]).get(path);
+ const prior = selectedFact(lexicalName);
+ const priorIdentity =
+ prior?.kind === 'regular' || prior?.kind === 'symlink' ? prior.identity : null;
+ const priorOwner = priorIdentity && findKnownGeneralGroup(index, priorIdentity)?.[1];
+ const roleChanged =
+ prior !== undefined &&
+ prior.kind !== 'unresolved' &&
+ (prior.kind === 'symlink') !== leafSymlink;
+ const targetChanged =
+ prior?.kind === 'symlink' && leafSymlink && prior.targetPath !== canonicalName;
+ const sequence = ++generalFileSequence;
+ const primaryPath = leafSymlink ? lexicalName : canonicalName;
+ const primary: GeneralPathFact = leafSymlink
+ ? {
+ kind: 'symlink',
+ path: lexicalName,
+ targetPath: canonicalName,
+ identity,
+ metadata,
+ sequence,
+ }
+ : { kind: 'regular', path: primaryPath, identity, metadata, sequence };
+
+ if (roleChanged || targetChanged) {
+ for (const relation of priorOwner?.fileMembers.symlinks ?? []) {
+ if (relation.path === lexicalName) continue;
+ const path = join(contentDir, relation.path);
+ try {
+ const actualTarget = realpathSync(path);
+ if (!isWithinContentDir(actualTarget, contentDir)) {
+ changes.set(relation.path, null);
+ continue;
+ }
+ const targetPath = toPosix(relative(contentDir, actualTarget));
+ if (
+ isSystemDoc(targetPath) ||
+ isConfigDoc(targetPath) ||
+ contentFilter?.isPathIgnored(relation.path) ||
+ contentFilter?.isPathIgnored(targetPath)
+ ) {
+ changes.set(relation.path, null);
+ continue;
+ }
+ const targetStat = targetPath === canonicalName ? null : statSync(actualTarget);
+ if (targetStat && !targetStat.isFile()) {
+ changes.set(relation.path, null);
+ continue;
+ }
+ const targetIdentity = targetStat
+ ? { device: targetStat.dev, inode: targetStat.ino }
+ : identity;
+ const targetMetadata = targetStat
+ ? { size: targetStat.size, modified: targetStat.mtime.toISOString() }
+ : metadata;
+ const existingTarget = selectedFact(targetPath);
+ if (
+ existingTarget?.kind !== 'regular' ||
+ !sameGeneralIdentity(existingTarget.identity, targetIdentity)
+ ) {
+ changes.set(targetPath, {
+ kind: 'regular',
+ path: targetPath,
+ identity: targetIdentity,
+ metadata: targetMetadata,
+ sequence,
+ });
+ }
+ changes.set(relation.path, {
+ kind: 'symlink',
+ path: relation.path,
+ targetPath,
+ identity: targetIdentity,
+ metadata: targetMetadata,
+ sequence,
+ });
+ } catch (err) {
+ const code = errnoCode(err);
+ if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'ELOOP') {
+ changes.set(relation.path, null);
+ continue;
+ }
+ log.warn({ path, code, err }, 'dependent symlink target read failed');
+ return { kind: 'unobserved' };
+ }
+ }
+ }
+
+ if (confirmedAbsentFormerPath) changes.set(confirmedAbsentFormerPath, null);
+ if (leafSymlink) {
+ const current = selectedFact(canonicalName);
+ if (current?.kind !== 'regular' || !sameGeneralIdentity(current.identity, identity)) {
+ changes.set(canonicalName, {
+ kind: 'regular',
+ path: canonicalName,
+ identity,
+ metadata,
+ sequence,
+ });
+ }
+ }
+ changes.set(primaryPath, primary);
+
+ const affected = new Set<string>();
+ const include = (names: ReadonlySet<string> | undefined): void => {
+ for (const name of names ?? []) affected.add(name);
+ };
+ include(index.ownersOfIdentity(identity));
+ for (const [path, fact] of changes) {
+ include(index.ownersOfPath(path));
+ if (fact?.kind === 'regular') include(index.ownersOfIdentity(fact.identity));
+ else if (fact?.kind === 'symlink') include(index.ownersOfPath(fact.targetPath));
+ }
+ const previousFacts = new Map<string, GeneralPathFact>();
+ const representatives = new Map<string, string>();
+ for (const name of affected) {
+ const entry = index.get(name);
+ if (!entry) continue;
+ addGeneralEntryFacts(previousFacts, name, entry);
+ const state = knownGeneralState(entry);
+ const key = state && generalIdentityKey(state.identity);
+ if (key && !representatives.has(key)) representatives.set(key, name);
+ }
+ const selected = new Map(previousFacts);
+ for (const [path, fact] of changes) {
+ if (fact) selected.set(path, fact);
+ else selected.delete(path);
+ }
+ const metadataEffects = new Map<string, GeneralMetadataEffect>([
+ [generalIdentityKey(identity), { ...metadata, sequence }],
+ ]);
+ for (const name of affected) index.delete(name);
+ storeGeneralFacts(index, contentDir, selected, representatives, metadataEffects);
+ const comparedPaths = new Set([...previousFacts.keys(), ...selected.keys()]);
+ const nextFacts = generalFactsFor(index, comparedPaths);
+ const changedPaths = new Set<string>();
+ for (const path of comparedPaths) {
+ const before = previousFacts.get(path);
+ const after = nextFacts.get(path);
+ if (before?.kind !== after?.kind) {
+ changedPaths.add(path);
+ } else if (before?.kind === 'symlink' && after?.kind === 'symlink') {
+ if (
+ before.targetPath !== after.targetPath ||
+ !sameGeneralIdentity(before.identity, after.identity)
+ ) {
+ changedPaths.add(path);
+ }
+ } else if (before?.kind === 'regular' && after?.kind === 'regular') {
+ if (!sameGeneralIdentity(before.identity, after.identity)) changedPaths.add(path);
+ }
+ }
+ return { kind: 'applied', changedPaths };
+}
+
+function generalMemberPaths(
+ contentDir: string,
+ index: ReadonlyMap<string, FileIndexEntry>,
+): Set<string> {
+ const paths = new Set<string>();
+ for (const [name, entry] of index) {
+ if (entry.kind !== 'file') continue;
+ for (const member of fileIndexEntryMembers(contentDir, name, entry).members) {
+ paths.add(member.path);
+ }
+ }
+ return paths;
+}
+
+type GeneralPathFact =
+ | {
+ kind: 'regular';
+ path: string;
+ identity: GeneralIdentity;
+ metadata: GeneralMetadata;
+ sequence: number;
+ }
+ | {
+ kind: 'symlink';
+ path: string;
+ targetPath: string;
+ identity: GeneralIdentity;
+ metadata: GeneralMetadata;
+ sequence: number;
+ }
+ | { kind: 'unresolved'; path: string; entry: FileIndexEntry; sequence: number };
+
+type GeneralMetadataEffect = GeneralMetadata & { sequence: number };
+type GeneralMutationRecord = {
+ generalNames: Set<string>;
+ generalEffects: Map<string, GeneralPathFact | null>;
+ generalMetadata: Map<string, GeneralMetadataEffect>;
+};
+
+function addGeneralEntryFacts(
+ facts: Map<string, GeneralPathFact>,
+ name: string,
+ entry: FileIndexEntry,
+): void {
+ if (entry.kind !== 'file') return;
+ const state = knownGeneralState(entry);
+ if (!state) {
+ facts.set(name, {
+ kind: 'unresolved',
+ path: name,
+ entry,
+ sequence: generalFileStates.get(entry)?.sequence ?? 0,
+ });
+ return;
+ }
+ const knownEntry = state.entry;
+ const metadata = { size: knownEntry.size, modified: knownEntry.modified };
+ for (const path of knownEntry.fileMembers.regularPaths) {
+ facts.set(path, {
+ kind: 'regular',
+ path,
+ identity: state.identity,
+ metadata,
+ sequence: state.sequence,
+ });
+ }
+ for (const relation of knownEntry.fileMembers.symlinks) {
+ facts.set(relation.path, {
+ kind: 'symlink',
+ path: relation.path,
+ targetPath: relation.targetPath,
+ identity: state.identity,
+ metadata,
+ sequence: state.sequence,
+ });
+ }
+}
+
+function generalPathFacts(
+ index: ReadonlyMap<string, FileIndexEntry>,
+): Map<string, GeneralPathFact> {
+ const facts = new Map<string, GeneralPathFact>();
+ for (const [name, entry] of index) addGeneralEntryFacts(facts, name, entry);
+ return facts;
+}
+
+function generalRepresentativeNames(
+ index: ReadonlyMap<string, FileIndexEntry>,
+): Map<string, string> {
+ const names = new Map<string, string>();
+ for (const [name, entry] of index) {
+ const state = knownGeneralState(entry);
+ if (!state) continue;
+ const key = generalIdentityKey(state.identity);
+ if (!names.has(key)) names.set(key, name);
+ }
+ return names;
+}
+
+function rebuildGeneralFileIndex(
+ index: GeneralFileIndex,
+ contentDir: string,
+ facts: ReadonlyMap<string, GeneralPathFact>,
+ previousRepresentatives: ReadonlyMap<string, string>,
+ metadataEffects: ReadonlyMap<string, GeneralMetadataEffect> = new Map(),
+): void {
+ index.clear();
+ storeGeneralFacts(index, contentDir, facts, previousRepresentatives, metadataEffects);
+}
+
+function storeGeneralFacts(
+ index: GeneralFileIndex,
+ contentDir: string,
+ facts: ReadonlyMap<string, GeneralPathFact>,
+ previousRepresentatives: ReadonlyMap<string, string>,
+ metadataEffects: ReadonlyMap<string, GeneralMetadataEffect>,
+): void {
+ const grouped = new Map<
+ string,
+ {
+ identity: GeneralIdentity;
+ regularPaths: string[];
+ symlinks: GeneralFileMembers['symlinks'][number][];
+ metadata: GeneralMetadata;
+ sequence: number;
+ }
+ >();
+ for (const fact of facts.values()) {
+ if (fact.kind !== 'regular') continue;
+ const key = generalIdentityKey(fact.identity);
+ const group = grouped.get(key);
+ if (group) {
+ group.regularPaths.push(fact.path);
+ if (fact.sequence >= group.sequence) {
+ group.metadata = fact.metadata;
+ group.sequence = fact.sequence;
+ }
+ } else {
+ grouped.set(key, {
+ identity: fact.identity,
+ regularPaths: [fact.path],
+ symlinks: [],
+ metadata: fact.metadata,
+ sequence: fact.sequence,
+ });
+ }
+ }
+ for (const fact of facts.values()) {
+ if (fact.kind !== 'symlink') continue;
+ const target = facts.get(fact.targetPath);
+ if (target?.kind !== 'regular') continue;
+ grouped.get(generalIdentityKey(target.identity))?.symlinks.push({
+ path: fact.path,
+ targetPath: fact.targetPath,
+ });
+ }
+ for (const [key, group] of grouped) {
+ const priorName = previousRepresentatives.get(key) ?? null;
+ const effect = metadataEffects.get(key);
+ storeKnownGeneralGroup(
+ index,
+ contentDir,
+ priorName,
+ group.identity,
+ group.regularPaths,
+ group.symlinks,
+ effect ?? group.metadata,
+ effect?.sequence ?? group.sequence,
+ );
+ }
+ for (const fact of facts.values()) {
+ if (fact.kind !== 'unresolved' || index.has(fact.path)) continue;
+ index.set(fact.path, fact.entry);
+ }
+}
+
+type GeneralScanAccumulator = {
+ facts: Map<string, GeneralPathFact>;
+ metadataEffects: Map<string, GeneralMetadataEffect>;
+};
+
+function materializeScanGeneralIndex(
+ observation: DiskObservation,
+ contentDir: string,
+ scan: GeneralScanAccumulator,
+): void {
+ const representatives = generalRepresentativeNames(observation.generalFileIndex);
+ for (const fact of scan.facts.values()) {
+ if (fact.kind !== 'regular') continue;
+ const key = generalIdentityKey(fact.identity);
+ if (!representatives.has(key)) representatives.set(key, fact.path);
+ }
+ const next = new GeneralFileIndex(contentDir);
+ rebuildGeneralFileIndex(next, contentDir, scan.facts, representatives, scan.metadataEffects);
+ observation.generalFileIndex = next;
+}
+
+function recordScannedGeneralPath(
+ observation: DiskObservation,
+ scan: GeneralScanAccumulator,
+ contentDir: string,
+ canonicalName: string,
+ lexicalName: string,
+ leafSymlink: boolean,
+ identity: GeneralIdentity,
+ metadata: GeneralMetadata,
+ contentFilter: ContentFilter | undefined,
+): GeneralRegistrationResult['kind'] {
+ const prior = scan.facts.get(lexicalName);
+ const roleChanged =
+ prior !== undefined &&
+ prior.kind !== 'unresolved' &&
+ (prior.kind === 'symlink') !== leafSymlink;
+ const targetChanged =
+ prior?.kind === 'symlink' && leafSymlink && prior.targetPath !== canonicalName;
+ if (roleChanged || targetChanged) {
+ materializeScanGeneralIndex(observation, contentDir, scan);
+ const registered = registerKnownGeneralPath(
+ observation.generalFileIndex,
+ contentDir,
+ canonicalName,
+ lexicalName,
+ leafSymlink,
+ identity,
+ metadata,
+ contentFilter,
+ );
+ scan.facts = generalPathFacts(observation.generalFileIndex);
+ scan.metadataEffects.clear();
+ return registered.kind;
+ }
+
+ const sequence = ++generalFileSequence;
+ if (leafSymlink) {
+ const target = scan.facts.get(canonicalName);
+ if (target?.kind !== 'regular' || !sameGeneralIdentity(target.identity, identity)) {
+ scan.facts.set(canonicalName, {
+ kind: 'regular',
+ path: canonicalName,
+ identity,
+ metadata,
+ sequence,
+ });
+ }
+ scan.facts.set(lexicalName, {
+ kind: 'symlink',
+ path: lexicalName,
+ targetPath: canonicalName,
+ identity,
+ metadata,
+ sequence,
+ });
+ } else {
+ scan.facts.set(canonicalName, {
+ kind: 'regular',
+ path: canonicalName,
+ identity,
+ metadata,
+ sequence,
+ });
+ }
+ scan.metadataEffects.set(generalIdentityKey(identity), { ...metadata, sequence });
+ return 'applied';
+}
+
+function recordGeneralPublicEffect(
+ record: GeneralMutationRecord,
+ index: GeneralFileIndex,
+ contentDir: string,
+ event: FileDiskEvent,
+ changedPaths: ReadonlySet<string> = new Set(),
+): void {
+ const canonicalName = toPosix(relative(contentDir, event.path));
+ const names =
+ event.kind === 'file-delete'
+ ? new Set([event.relativePath])
+ : new Set([canonicalName, event.relativePath]);
+ const recorded = new Set([...names, ...changedPaths]);
+ const facts = generalFactsFor(index, recorded);
+ for (const name of recorded) {
+ record.generalNames.add(name);
+ record.generalEffects.set(name, facts.get(name) ?? null);
+ }
+ if (event.kind === 'file-delete') return;
+ const fact = facts.get(canonicalName) ?? facts.get(event.relativePath);
+ if (fact?.kind !== 'regular' && fact?.kind !== 'symlink') return;
+ record.generalMetadata.set(generalIdentityKey(fact.identity), {
+ size: event.size,
+ modified: new Date(event.modifiedTs).toISOString(),
+ sequence: fact.sequence,
+ });
+}
+
+function recordObservedExtension(
+ observation: DiskObservation,
+ docName: string,
+ ext: string,
+): boolean {
+ observation.extensions.push({ docName, ext });
+ const existing = observation.preferredExtensions.get(docName);
+ const orderedExtensions: readonly string[] = SUPPORTED_DOC_EXTENSIONS;
+ if (
+ !existing ||
+ orderedExtensions.indexOf(ext.toLowerCase()) < orderedExtensions.indexOf(existing.toLowerCase())
+ ) {
+ observation.preferredExtensions.set(docName, ext);
+ return true;
+ }
+ return existing.toLowerCase() === ext.toLowerCase();
+}
+
+async function scanDisk(
dir: string,
contentDir: string,
contentFilter: ContentFilter | undefined,
- fileIndex: Map<string, FileIndexEntry>,
- folderIndex: Map<string, FolderIndexEntry>,
- aliasMap: Map<string, string>,
- folderAliasIndex: Map<string, string>,
+ observation: DiskObservation,
+ generalScan: GeneralScanAccumulator,
visitedInodes?: Set<number>,
- structuralIgnoreDirs?: Set<string>,
+ generalVisitedInodes?: Set<number>,
): Promise<void> {
const visited = visitedInodes ?? new Set<number>();
+ const generalVisited = generalVisitedInodes ?? new Set<number>();
try {
const entries = await readdir(dir, { withFileTypes: true });
for (const entry of entries) {
@@ -670,6 +1547,7 @@ async function seedLastKnownHashes(
} catch (e) {
const code = errnoCode(e);
if (code !== 'ENOENT') {
+ observation.complete = false;
log.warn({ path: fullPath, err: e }, `Failed to lstat ${fullPath}, skipping`);
}
continue;
@@ -684,6 +1562,7 @@ async function seedLastKnownHashes(
if (code === 'ENOENT' || code === 'ELOOP') {
log.warn({ path: fullPath, code }, `Broken/cyclic symlink at ${fullPath}, skipping`);
} else {
+ observation.complete = false;
log.warn({ path: fullPath, err: e }, `Failed to resolve symlink ${fullPath}`);
}
continue;
@@ -702,22 +1581,55 @@ async function seedLastKnownHashes(
try {
const canonStat = await stat(canonical);
+ if (canonStat.isFile() && !isSupportedDocFile(entry.name)) {
+ const canonicalName = toPosix(relative(contentDir, canonical));
+ const lexicalName = toPosix(relative(contentDir, fullPath));
+ if (
+ contentFilter?.isPathIgnored(canonicalName) ||
+ contentFilter?.isPathIgnored(lexicalName) ||
+ isSystemDoc(canonicalName) ||
+ isConfigDoc(canonicalName) ||
+ isSystemDoc(lexicalName) ||
+ isConfigDoc(lexicalName)
+ )
+ continue;
+ if (visited.has(canonStat.ino) && !generalVisited.has(canonStat.ino)) continue;
+ visited.add(canonStat.ino);
+ generalVisited.add(canonStat.ino);
+ const registered = recordScannedGeneralPath(
+ observation,
+ generalScan,
+ contentDir,
+ canonicalName,
+ lexicalName,
+ true,
+ { device: canonStat.dev, inode: canonStat.ino },
+ { size: canonStat.size, modified: canonStat.mtime.toISOString() },
+ contentFilter,
+ );
+ if (registered === 'unobserved') observation.complete = false;
+ observation.paths.add(fullPath);
+ continue;
+ }
if (visited.has(canonStat.ino)) {
if (canonStat.isFile() && isSupportedDocFile(entry.name)) {
const aliasDocName = pathToDocName(fullPath, contentDir);
const canonicalDocName = pathToDocName(canonical, contentDir);
- aliasMap.set(aliasDocName, canonicalDocName);
- const existing = fileIndex.get(canonicalDocName);
+ observation.aliasMap.set(aliasDocName, canonicalDocName);
+ observation.aliasPaths.set(aliasDocName, fullPath);
+ observation.paths.add(fullPath);
+ const existing = observation.fileIndex.get(canonicalDocName);
if (existing && !existing.aliases.includes(aliasDocName)) {
existing.aliases.push(aliasDocName);
}
} else if (canonStat.isDirectory()) {
const relPath = contentRelativePath(contentDir, fullPath);
if (!contentFilter || (relPath && !contentFilter.isDirExcluded(relPath))) {
- folderAliasIndex.set(
- pathToDocName(fullPath, contentDir),
- pathToDocName(canonical, contentDir),
+ observation.folderAliasIndex.set(
+ toPosix(relative(contentDir, fullPath)),
+ toPosix(relative(contentDir, canonical)),
);
+ observation.paths.add(fullPath);
}
}
continue;
@@ -729,20 +1641,19 @@ async function seedLastKnownHashes(
if (contentFilter) {
if (!relPath || contentFilter.isDirExcluded(relPath)) continue;
}
- folderAliasIndex.set(
- pathToDocName(fullPath, contentDir),
- pathToDocName(canonical, contentDir),
+ observation.folderAliasIndex.set(
+ toPosix(relative(contentDir, fullPath)),
+ toPosix(relative(contentDir, canonical)),
);
- await seedLastKnownHashes(
+ observation.paths.add(fullPath);
+ await scanDisk(
canonical,
contentDir,
contentFilter,
- fileIndex,
- folderIndex,
- aliasMap,
- folderAliasIndex,
+ observation,
+ generalScan,
visited,
- structuralIgnoreDirs,
+ generalVisited,
);
} else if (canonStat.isFile() && isSupportedDocFile(entry.name)) {
if (contentFilter) {
@@ -751,24 +1662,18 @@ async function seedLastKnownHashes(
}
const aliasDocName = pathToDocName(fullPath, contentDir);
const canonicalDocName = pathToDocName(canonical, contentDir);
- aliasMap.set(aliasDocName, canonicalDocName);
+ observation.aliasMap.set(aliasDocName, canonicalDocName);
+ observation.aliasPaths.set(aliasDocName, fullPath);
+ observation.paths.add(fullPath);
try {
const content = await readFile(canonical, 'utf-8');
const hash = contentHash(content);
- lastKnownHash.set(canonical, hash);
+ observation.hashes.set(canonical, hash);
+ observation.paths.add(canonical);
const ext = extractDocExtension(canonical);
- if (ext) {
- const reg = registerDocExtension(canonicalDocName, ext);
- if (reg.shadowed) {
- log.warn(
- { docName: canonicalDocName, effective: reg.effective, shadowed: reg.shadowed },
- `docName "${canonicalDocName}" has both "${reg.effective}" and "${reg.shadowed}" on disk; "${reg.effective}" wins (industry convention). Rename or delete one to disambiguate.`,
- );
- if (!reg.changed) continue;
- }
- }
- fileIndex.set(canonicalDocName, {
+ if (ext && !recordObservedExtension(observation, canonicalDocName, ext)) continue;
+ observation.fileIndex.set(canonicalDocName, {
size: canonStat.size,
modified: canonStat.mtime.toISOString(),
canonicalPath: canonical,
@@ -780,26 +1685,16 @@ async function seedLastKnownHashes(
} catch (err) {
const code = errnoCode(err);
if (code !== 'ENOENT') {
+ observation.complete = false;
log.warn({ path: canonical, err }, `Failed to seed hash for ${canonical}`);
}
}
- } else if (canonStat.isFile()) {
- if (contentFilter) {
- const relPath = toPosix(relative(contentDir, canonical));
- if (contentFilter.isPathIgnored(relPath)) continue;
- }
- const docName = pathToDocName(fullPath, contentDir);
- if (isSystemDoc(docName) || isConfigDoc(docName)) continue;
- fileIndex.set(docName, {
- size: canonStat.size,
- modified: canonStat.mtime.toISOString(),
- canonicalPath: canonical,
- inode: canonStat.ino,
- aliases: [],
- kind: 'file',
- });
}
} catch (e) {
+ const code = errnoCode(e);
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+ observation.complete = false;
+ }
log.warn({ path: canonical, err: e }, `Failed to stat symlink target ${canonical}`);
}
} else if (lst.isDirectory()) {
@@ -807,21 +1702,20 @@ async function seedLastKnownHashes(
if (contentFilter) {
if (!relPath || contentFilter.isDirExcluded(relPath)) {
const structural = relPath && structuralIgnoreOccurrence(relPath);
- if (structural) structuralIgnoreDirs?.add(structural);
+ if (structural) observation.structuralIgnoreDirs.add(structural);
continue;
}
}
- upsertFolderIndexEntry(folderIndex, contentDir, fullPath, lst);
- await seedLastKnownHashes(
+ upsertFolderIndexEntry(observation.folderIndex, contentDir, fullPath, lst);
+ observation.paths.add(fullPath);
+ await scanDisk(
fullPath,
contentDir,
contentFilter,
- fileIndex,
- folderIndex,
- aliasMap,
- folderAliasIndex,
+ observation,
+ generalScan,
visited,
- structuralIgnoreDirs,
+ generalVisited,
);
} else if (lst.isFile() && isSupportedDocFile(entry.name)) {
if (visited.has(lst.ino)) continue;
@@ -833,21 +1727,13 @@ async function seedLastKnownHashes(
}
try {
const content = await readFile(fullPath, 'utf-8');
- lastKnownHash.set(fullPath, contentHash(content));
+ observation.hashes.set(fullPath, contentHash(content));
+ observation.paths.add(fullPath);
const docName = pathToDocName(fullPath, contentDir);
const ext = extractDocExtension(fullPath);
- if (ext) {
- const reg = registerDocExtension(docName, ext);
- if (reg.shadowed) {
- log.warn(
- { docName, effective: reg.effective, shadowed: reg.shadowed },
- `docName "${docName}" has both "${reg.effective}" and "${reg.shadowed}" on disk; "${reg.effective}" wins (industry convention). Rename or delete one to disambiguate.`,
- );
- if (!reg.changed) continue;
- }
- }
- fileIndex.set(docName, {
+ if (ext && !recordObservedExtension(observation, docName, ext)) continue;
+ observation.fileIndex.set(docName, {
size: lst.size,
modified: lst.mtime.toISOString(),
canonicalPath: fullPath,
@@ -859,42 +1745,224 @@ async function seedLastKnownHashes(
} catch (err) {
const code = errnoCode(err);
if (code === 'EACCES') {
+ observation.complete = false;
log.warn(
{ path: fullPath, code },
`Permission denied reading ${fullPath}, file excluded from index`,
);
} else if (code !== 'ENOENT') {
+ observation.complete = false;
log.warn({ path: fullPath, err }, `Failed to seed hash for ${fullPath}`);
}
}
} else if (lst.isFile()) {
- if (visited.has(lst.ino)) continue;
- visited.add(lst.ino);
-
if (contentFilter) {
const relPath = toPosix(relative(contentDir, fullPath));
if (contentFilter.isPathIgnored(relPath)) continue;
}
- const docName = pathToDocName(fullPath, contentDir);
- if (isSystemDoc(docName) || isConfigDoc(docName)) continue;
- fileIndex.set(docName, {
- size: lst.size,
- modified: lst.mtime.toISOString(),
- canonicalPath: fullPath,
- inode: lst.ino,
- aliases: [],
- kind: 'file',
- });
+ const relativePath = toPosix(relative(contentDir, fullPath));
+ if (isSystemDoc(relativePath) || isConfigDoc(relativePath)) continue;
+ if (visited.has(lst.ino) && !generalVisited.has(lst.ino)) continue;
+ visited.add(lst.ino);
+ generalVisited.add(lst.ino);
+ const registered = recordScannedGeneralPath(
+ observation,
+ generalScan,
+ contentDir,
+ relativePath,
+ relativePath,
+ false,
+ { device: lst.dev, inode: lst.ino },
+ { size: lst.size, modified: lst.mtime.toISOString() },
+ contentFilter,
+ );
+ if (registered === 'unobserved') observation.complete = false;
+ observation.paths.add(fullPath);
}
}
} catch (err) {
const code = errnoCode(err);
- if (code !== 'ENOENT') {
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+ observation.complete = false;
log.warn({ dir, err }, `Failed to read directory ${dir}`);
}
}
}
+async function observeDisk(
+ contentDir: string,
+ contentFilter: ContentFilter | undefined,
+): Promise<DiskObservation> {
+ const observation: DiskObservation = {
+ fileIndex: new Map(),
+ generalFileIndex: new GeneralFileIndex(contentDir),
+ folderIndex: new Map(),
+ aliasMap: new Map(),
+ aliasPaths: new Map(),
+ folderAliasIndex: new Map(),
+ hashes: new Map(),
+ extensions: [],
+ preferredExtensions: new Map(),
+ structuralIgnoreDirs: new Set(),
+ paths: new Set(),
+ complete: true,
+ };
+ const generalScan: GeneralScanAccumulator = {
+ facts: new Map(),
+ metadataEffects: new Map(),
+ };
+ await scanDisk(contentDir, contentDir, contentFilter, observation, generalScan);
+ materializeScanGeneralIndex(observation, contentDir, generalScan);
+ for (const [name, entry] of new Map(observation.generalFileIndex)) {
+ const state = knownGeneralState(entry);
+ if (!state) continue;
+ const members = state.entry.fileMembers;
+ const first = members.regularPaths.toSorted()[0];
+ if (name === first) continue;
+ observation.generalFileIndex.delete(name);
+ storeKnownGeneralGroup(
+ observation.generalFileIndex,
+ contentDir,
+ null,
+ state.identity,
+ members.regularPaths,
+ members.symlinks,
+ entry,
+ state.sequence,
+ );
+ }
+ for (const [alias, canonical] of observation.aliasMap) {
+ const entry = observation.fileIndex.get(canonical);
+ if (entry && !entry.aliases.includes(alias)) entry.aliases.push(alias);
+ }
+ return observation;
+}
+
+type ObservedInventory = Pick<DiskObservation, 'fileIndex' | 'folderIndex' | 'folderAliasIndex'>;
+
+function generalAliasIsAdmitted(
+ alias: string,
+ targetPath: string,
+ contentFilter: ContentFilter | undefined,
+): boolean {
+ return !contentFilter?.isPathIgnored(alias) && !contentFilter?.isPathIgnored(targetPath);
+}
+
+function selectObservedInventory(
+ observation: DiskObservation,
+ contentDir: string,
+ contentFilter: ContentFilter | undefined,
+): ObservedInventory & { generalFacts: Map<string, GeneralPathFact> } {
+ return {
+ fileIndex: new Map(
+ [...observation.fileIndex].filter(
+ ([, entry]) =>
+ !contentFilter?.isExcluded(toPosix(relative(contentDir, entry.canonicalPath))),
+ ),
+ ),
+ generalFacts: new Map(
+ [...generalPathFacts(observation.generalFileIndex)].filter(([, fact]) =>
+ fact.kind === 'symlink'
+ ? generalAliasIsAdmitted(fact.path, fact.targetPath, contentFilter)
+ : !contentFilter?.isPathIgnored(fact.path),
+ ),
+ ),
+ folderIndex: new Map(
+ [...observation.folderIndex].filter(([path]) => !contentFilter?.isDirExcluded(path)),
+ ),
+ folderAliasIndex: new Map(
+ [...observation.folderAliasIndex].filter(([alias]) => !contentFilter?.isDirExcluded(alias)),
+ ),
+ };
+}
+
+function publishDiskObservation(
+ observation: DiskObservation,
+ inventory: ObservedInventory,
+ fileIndex: Map<string, FileIndexEntry>,
+ generalFileIndex: GeneralFileIndex,
+ folderIndex: Map<string, FolderIndexEntry>,
+ aliasMap: Map<string, string>,
+ folderAliasIndex: Map<string, string>,
+ structuralIgnoreDirs?: Set<string>,
+ publishGeneral = true,
+): void {
+ for (const { docName, ext } of observation.extensions) {
+ const reg = registerDocExtension(docName, ext);
+ if (reg.shadowed) {
+ log.warn(
+ { docName, effective: reg.effective, shadowed: reg.shadowed },
+ `docName "${docName}" has both "${reg.effective}" and "${reg.shadowed}" on disk; "${reg.effective}" wins (industry convention). Rename or delete one to disambiguate.`,
+ );
+ }
+ }
+ for (const [path, hash] of observation.hashes) lastKnownHash.set(path, hash);
+ for (const [docName, entry] of inventory.fileIndex) {
+ if (getDocExtension(docName).toLowerCase() !== extname(entry.canonicalPath).toLowerCase()) {
+ continue;
+ }
+ fileIndex.set(docName, entry);
+ }
+ if (publishGeneral) {
+ for (const [name, entry] of observation.generalFileIndex) {
+ generalFileIndex.set(name, entry);
+ }
+ }
+ for (const [path, entry] of inventory.folderIndex) folderIndex.set(path, entry);
+ for (const [alias, canonical] of observation.aliasMap) aliasMap.set(alias, canonical);
+ for (const [alias, canonical] of inventory.folderAliasIndex) {
+ folderAliasIndex.set(alias, canonical);
+ }
+ for (const path of observation.structuralIgnoreDirs) structuralIgnoreDirs?.add(path);
+}
+
+function updateGeneralFileIndex(
+ event: FileDiskEvent,
+ generalFileIndex: Map<string, FileIndexEntry>,
+ contentDir: string,
+ canonicalPath = event.path,
+): void {
+ if (isSystemDoc(event.relativePath) || isConfigDoc(event.relativePath)) return;
+ if (event.kind === 'file-delete') {
+ const direct = generalFileIndex.get(event.relativePath);
+ if (direct?.kind === 'file') {
+ generalFileIndex.delete(event.relativePath);
+ return;
+ }
+ for (const [name, entry] of generalFileIndex) {
+ if (entry.kind !== 'file' || !entry.aliases.includes(event.relativePath)) continue;
+ generalFileIndex.set(name, {
+ ...entry,
+ aliases: entry.aliases.filter((alias) => alias !== event.relativePath),
+ });
+ return;
+ }
+ return;
+ }
+
+ const canonicalName = toPosix(relative(contentDir, canonicalPath));
+ for (const [name, entry] of generalFileIndex) {
+ if (name === canonicalName || entry.kind !== 'file') continue;
+ if (!entry.aliases.includes(event.relativePath)) continue;
+ generalFileIndex.set(name, {
+ ...entry,
+ aliases: entry.aliases.filter((alias) => alias !== event.relativePath),
+ });
+ }
+ const prior = generalFileIndex.get(canonicalName);
+ const aliases = new Set(prior?.kind === 'file' ? prior.aliases : []);
+ if (event.relativePath !== canonicalName) aliases.add(event.relativePath);
+ aliases.delete(canonicalName);
+ generalFileIndex.set(canonicalName, {
+ size: event.size,
+ modified: new Date(event.modifiedTs).toISOString(),
+ canonicalPath,
+ inode: event.inode || (prior?.kind === 'file' ? prior.inode : 0),
+ aliases: [...aliases],
+ kind: 'file',
+ });
+}
+
export function updateFileIndex(event: DiskEvent, fileIndex: Map<string, FileIndexEntry>): void {
if (
event.kind === 'asset-create' ||
@@ -1121,14 +2189,17 @@ function scanForUntrackedSubfolders(
}
}
-export async function handleRawEvents(
- rawEvents: Array<{ type: 'create' | 'update' | 'delete'; path: string }>,
+async function handleRawEventsInternal(
+ rawEvents: InternalRawFileEvent[],
contentDir: string,
contentFilter: ContentFilter | undefined,
fileIndex: Map<string, FileIndexEntry>,
folderIndex: Map<string, FolderIndexEntry>,
onDiskEvent: (event: DiskEvent) => Promise<void>,
aliasMap?: Map<string, string>,
+ admitEvent?: (event: DiskEvent) => boolean,
+ generalFileIndex?: GeneralFileIndex,
+ aliasPaths?: Map<string, string>,
): Promise<void> {
const declaredBeforeBatch: ReadonlySet<string> = new Set(removalTracker.keys());
const safeEvents = rawEvents.filter((e) => {
@@ -1138,8 +2209,32 @@ export async function handleRawEvents(
return false;
});
+ const folderInputs = safeEvents.filter(
+ (event) => !('entryKind' in event) || event.entryKind !== 'file',
+ );
+ let knownFilePaths: Set<string> | undefined;
+ const fileInputs = safeEvents.filter((event) => {
+ if (event.type !== 'delete') return true;
+ if ('entryKind' in event) return event.entryKind === 'file';
+ const relativePath = contentRelativePath(contentDir, event.path);
+ if (relativePath === null || !folderIndex.has(relativePath)) return true;
+ if (!knownFilePaths) {
+ knownFilePaths = new Set([...fileIndex.values()].map((entry) => entry.canonicalPath));
+ for (const name of generalMemberPaths(contentDir, generalFileIndex ?? fileIndex)) {
+ knownFilePaths.add(join(contentDir, name));
+ }
+ for (const path of aliasPaths?.values() ?? []) knownFilePaths.add(path);
+ }
+ return (
+ knownFilePaths.has(event.path) ||
+ (aliasPaths === undefined &&
+ isSupportedDocFile(event.path) &&
+ aliasMap?.has(pathToDocName(event.path, contentDir)) === true)
+ );
+ });
+
const { events: folderEvents, untrackedFiles } = updateFolderIndexFromRawEvents(
- safeEvents,
+ folderInputs,
contentDir,
contentFilter,
folderIndex,
@@ -1150,6 +2245,9 @@ export async function handleRawEvents(
const batchPaths = new Set(safeEvents.map((e) => e.path));
const knownCanonicalPaths = new Set<string>();
for (const entry of fileIndex.values()) knownCanonicalPaths.add(entry.canonicalPath);
+ for (const name of generalMemberPaths(contentDir, generalFileIndex ?? fileIndex)) {
+ knownCanonicalPaths.add(join(contentDir, name));
+ }
rescuedCreates = untrackedFiles
.filter(
(path) =>
@@ -1181,11 +2279,52 @@ export async function handleRawEvents(
batchPaths.add(entry.canonicalPath);
collapsedDeletes.push({ type: 'delete', path: entry.canonicalPath });
}
+ for (const name of generalMemberPaths(contentDir, generalFileIndex ?? fileIndex)) {
+ if (!name.startsWith(prefix)) continue;
+ const path = join(contentDir, name);
+ if (batchPaths.has(path)) continue;
+ batchPaths.add(path);
+ collapsedDeletes.push({ type: 'delete', path });
+ }
}
- const fileEvents = safeEvents.concat(rescuedCreates, collapsedDeletes);
+ const fileEvents = fileInputs.concat(rescuedCreates, collapsedDeletes);
+ const removedSameNameAliases = new Map<string, { name: string; targetName: string }>();
+ for (const event of fileEvents) {
+ if (event.type !== 'delete' || !isSupportedDocFile(event.path)) continue;
+ const name = pathToDocName(event.path, contentDir);
+ const owner = fileIndex.get(name);
+ const targetName = aliasMap?.get(name);
+ if (
+ aliasPaths?.get(name) === event.path &&
+ targetName !== undefined &&
+ owner?.kind === 'markdown' &&
+ owner.canonicalPath !== event.path &&
+ !contentFilter?.isExcluded(toPosix(relative(contentDir, event.path)))
+ ) {
+ removedSameNameAliases.set(event.path, { name, targetName });
+ }
+ }
+ for (const [path, { name, targetName }] of removedSameNameAliases) {
+ if (admitEvent && !admitEvent({ kind: 'delete', path, docName: name })) continue;
+ aliasMap?.delete(name);
+ aliasPaths?.delete(name);
+ const target = fileIndex.get(targetName);
+ if (target) {
+ fileIndex.set(targetName, {
+ ...target,
+ aliases: target.aliases.filter((alias) => alias !== name),
+ });
+ }
+ removeLastKnownHash(path);
+ isSelfRemoval(path);
+ }
- const mdEvents = fileEvents.filter((e) => isSupportedDocFile(e.path));
+ const mdEvents = fileEvents.filter(
+ (event) =>
+ isSupportedDocFile(event.path) &&
+ !(event.type === 'delete' && removedSameNameAliases.has(event.path)),
+ );
const assetEvents = fileEvents.filter((e) =>
isSupportedAssetFile(e.path, LINKABLE_ASSET_EXTENSIONS),
);
@@ -1199,10 +2338,29 @@ export async function handleRawEvents(
return;
}
+ const canonicalAliasRecords = new Set<RawFileEvent>();
const diskEvents =
- mdEvents.length > 0 ? await classifyEvents(mdEvents, contentDir, contentFilter, aliasMap) : [];
+ mdEvents.length > 0
+ ? await classifyEventsInternal(
+ mdEvents,
+ contentDir,
+ contentFilter,
+ aliasMap,
+ aliasPaths
+ ? { fileIndex, aliasPaths, canonicalRecords: canonicalAliasRecords }
+ : undefined,
+ )
+ : [];
+ const admittedMarkdownPaths = new Set<string>();
for (const event of diskEvents) {
+ if (admitEvent && !admitEvent(event)) continue;
+ if (event.kind === 'rename') {
+ admittedMarkdownPaths.add(event.oldPath);
+ admittedMarkdownPaths.add(event.newPath);
+ } else {
+ admittedMarkdownPaths.add(event.path);
+ }
let isSelf = false;
let indexEvent = event;
@@ -1327,6 +2485,7 @@ export async function handleRawEvents(
}
for (const event of folderEvents) {
+ if (admitEvent && !admitEvent(event)) continue;
log.debug({ kind: event.kind, path: event.path }, `[file-watcher] Dispatching: ${event.kind}`);
_fileWatcherEventsCounter().add(1, { 'disk.kind': event.kind, self: false });
recordWatcherDecision('dispatched', event.kind, event.path);
@@ -1356,6 +2515,7 @@ export async function handleRawEvents(
raw.type === 'delete'
? { kind: 'asset-delete', path: raw.path, relativePath }
: { kind: 'asset-create', path: raw.path, relativePath };
+ if (admitEvent && !admitEvent(event)) continue;
recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
}
@@ -1373,16 +2533,24 @@ export async function handleRawEvents(
if (raw.type === 'delete') {
const event: DiskEvent = { kind: 'file-delete', path: raw.path, relativePath };
- updateFileIndex(event, fileIndex);
+ if (admitEvent && !admitEvent(event)) continue;
+ if (generalFileIndex) removeKnownGeneralPath(generalFileIndex, contentDir, relativePath);
+ else updateGeneralFileIndex(event, fileIndex, contentDir);
recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
continue;
}
let st: ReturnType<typeof lstatSync>;
+ let leafSymlink = false;
+ let canonicalPath: string;
+ let canonicalContentDir: string;
try {
+ canonicalContentDir = realpathSync(contentDir);
st = lstatSync(raw.path);
- if (st.isSymbolicLink()) st = statSync(raw.path);
+ leafSymlink = st.isSymbolicLink();
+ canonicalPath = realpathSync(raw.path);
+ if (leafSymlink) st = statSync(canonicalPath);
} catch (e) {
const code = errnoCode(e);
recordWatcherDecision('drop-stat-failed', raw.type, raw.path);
@@ -1392,8 +2560,22 @@ export async function handleRawEvents(
continue;
}
if (!st.isFile()) continue;
+ if (!isWithinContentDir(canonicalPath, canonicalContentDir)) {
+ recordWatcherDecision('drop-symlink-escape', raw.type, raw.path);
+ log.warn({ path: raw.path, canonicalPath }, `Symlink escape: ${raw.path}, dropping event`);
+ continue;
+ }
+ const canonicalName = toPosix(relative(canonicalContentDir, canonicalPath));
+ if (contentFilter?.isPathIgnored(canonicalName)) {
+ recordWatcherDecision('drop-filter-excluded', raw.type, raw.path);
+ continue;
+ }
+ if (isSystemDoc(canonicalName) || isConfigDoc(canonicalName)) {
+ recordWatcherDecision('drop-reserved-doc', raw.type, raw.path);
+ continue;
+ }
- const event: DiskEvent =
+ const event: FileDiskEvent =
raw.type === 'create'
? {
kind: 'file-create',
@@ -1411,10 +2593,103 @@ export async function handleRawEvents(
modifiedTs: st.mtime.getTime(),
inode: Number(st.ino),
};
- updateFileIndex(event, fileIndex);
+ if (admitEvent && !admitEvent(event)) continue;
+ let formerOwner: [string, FileIndexEntry] | undefined;
+ let formerTarget: string | null = null;
+ if (generalFileIndex) {
+ for (const name of generalOwnerNames(generalFileIndex, relativePath)) {
+ const entry = generalFileIndex.get(name);
+ if (entry?.kind !== 'file') continue;
+ const relation = knownGeneralState(entry)?.entry.fileMembers.symlinks.find(
+ (candidate) => candidate.path === relativePath,
+ );
+ if (!relation || relation.targetPath === canonicalName) continue;
+ formerOwner = [name, entry];
+ formerTarget = join(canonicalContentDir, relation.targetPath);
+ break;
+ }
+ } else {
+ for (const owner of fileIndex) {
+ if (owner[1].kind !== 'file') continue;
+ if (owner[0] !== canonicalName && owner[1].aliases.includes(relativePath)) {
+ formerOwner = owner;
+ formerTarget = owner[1].canonicalPath;
+ break;
+ }
+ }
+ }
+ let confirmedAbsentFormerPath: string | undefined;
+ if (formerOwner && formerTarget) {
+ try {
+ const formerPath = realpathSync(formerTarget);
+ statSync(formerPath);
+ } catch (err) {
+ const code = errnoCode(err);
+ if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'ELOOP') {
+ recordWatcherDecision('drop-stat-failed', raw.type, raw.path);
+ log.warn({ path: formerTarget, code, err }, 'file watcher former target read failed');
+ continue;
+ }
+ if (generalFileIndex) {
+ confirmedAbsentFormerPath = toPosix(relative(canonicalContentDir, formerTarget));
+ } else {
+ fileIndex.delete(formerOwner[0]);
+ }
+ }
+ }
+ if (generalFileIndex) {
+ const registered = registerKnownGeneralPath(
+ generalFileIndex,
+ canonicalContentDir,
+ canonicalName,
+ relativePath,
+ leafSymlink,
+ { device: st.dev, inode: st.ino },
+ { size: event.size, modified: new Date(event.modifiedTs).toISOString() },
+ contentFilter,
+ confirmedAbsentFormerPath,
+ );
+ if (registered.kind === 'unobserved') {
+ recordWatcherDecision('drop-stat-failed', raw.type, raw.path);
+ continue;
+ }
+ } else {
+ updateGeneralFileIndex(event, fileIndex, canonicalContentDir, canonicalPath);
+ }
recordWatcherDecision('dispatched', event.kind, raw.path);
await onDiskEvent(event);
}
+ if (aliasPaths) {
+ for (const event of mdEvents) {
+ if (!admittedMarkdownPaths.has(event.path) || canonicalAliasRecords.has(event)) continue;
+ const name = pathToDocName(event.path, contentDir);
+ if (event.type !== 'delete' && aliasMap?.has(name)) {
+ aliasPaths.set(name, event.path);
+ } else if (aliasPaths.get(name) === event.path) {
+ aliasPaths.delete(name);
+ }
+ }
+ }
+}
+
+export async function handleRawEvents(
+ rawEvents: Array<{ type: 'create' | 'update' | 'delete'; path: string }>,
+ contentDir: string,
+ contentFilter: ContentFilter | undefined,
+ fileIndex: Map<string, FileIndexEntry>,
+ folderIndex: Map<string, FolderIndexEntry>,
+ onDiskEvent: (event: DiskEvent) => Promise<void>,
+ aliasMap?: Map<string, string>,
+): Promise<void> {
+ return handleRawEventsInternal(
+ rawEvents,
+ contentDir,
+ contentFilter,
+ fileIndex,
+ folderIndex,
+ onDiskEvent,
+ aliasMap,
+ );
}
let _fwEventsCounterCache: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
@@ -1442,6 +2717,399 @@ function structuralIgnoreOccurrence(relativePath: string): string | null {
return null;
}
+type RecoveredAliasCandidate =
+ | { kind: 'delete'; alias: string; targetPath: string }
+ | {
+ kind: 'target-update';
+ alias: string;
+ targetPath: string;
+ targetIdentity: GeneralIdentity;
+ };
+
+async function recoverDiskChanges(
+ contentDir: string,
+ contentFilter: ContentFilter | undefined,
+ fileIndex: Map<string, FileIndexEntry>,
+ generalFileIndex: GeneralFileIndex,
+ folderIndex: Map<string, FolderIndexEntry>,
+ aliasMap: Map<string, string>,
+ aliasPaths: Map<string, string>,
+ folderAliasIndex: Map<string, string>,
+ publicMutations: RecoveryPublicMutations,
+ onDiskEvent: (event: DiskEvent) => Promise<void>,
+ onAfterMutation: () => void,
+ getFileIndexGeneration: () => number,
+ onRawBatch?: (absPaths: readonly string[]) => void,
+): Promise<boolean> {
+ const knownPaths = new Set<string>();
+ for (const entry of fileIndex.values()) knownPaths.add(entry.canonicalPath);
+ for (const name of generalMemberPaths(contentDir, generalFileIndex)) {
+ knownPaths.add(join(contentDir, name));
+ }
+ for (const relativePath of folderIndex.keys()) knownPaths.add(join(contentDir, relativePath));
+ for (const path of aliasPaths.values()) knownPaths.add(path);
+ for (const alias of folderAliasIndex.keys()) knownPaths.add(join(contentDir, alias));
+
+ const previousFiles = new Map(fileIndex);
+ const previousGeneralFiles = new Map(generalFileIndex);
+ const previousFolders = new Map(folderIndex);
+ const previousHashes = new Map(lastKnownHash);
+ const previousAliases = new Map(aliasMap);
+ const previousAliasPaths = new Map(aliasPaths);
+ const previousFolderAliases = new Map(folderAliasIndex);
+
+ contentFilter?.refreshInPlaceSkillDirs();
+ const observed = await observeDisk(contentDir, contentFilter);
+ if (!observed.complete) return false;
+
+ const markdownPublicMutationFor = (name: string, entry: FileIndexEntry): boolean => {
+ const names = publicMutations.markdownNames;
+ if (names.has(name)) return true;
+ const canonicalName = pathToDocName(entry.canonicalPath, contentDir);
+ return names.has(canonicalName) || entry.aliases.some((alias) => names.has(alias));
+ };
+ const previousGeneralFacts = generalPathFacts(previousGeneralFiles);
+ const observedGeneralFacts = generalPathFacts(observed.generalFileIndex);
+
+ const rawEvents: RecoveredFileEvent[] = [];
+ for (const [docName, previous] of previousFiles) {
+ const current = observed.fileIndex.get(docName);
+ if (
+ markdownPublicMutationFor(docName, previous) ||
+ (current && markdownPublicMutationFor(docName, current))
+ )
+ continue;
+ if (current?.canonicalPath !== previous.canonicalPath) {
+ rawEvents.push({ type: 'delete', path: previous.canonicalPath, entryKind: 'file' });
+ } else if (
+ previousHashes.get(previous.canonicalPath) !== observed.hashes.get(current.canonicalPath)
+ ) {
+ rawEvents.push({ type: 'update', path: current.canonicalPath });
+ }
+ }
+ for (const [name, previous] of previousGeneralFacts) {
+ if (previous.kind === 'symlink' || publicMutations.generalEffects.has(name)) continue;
+ const current = observedGeneralFacts.get(name);
+ if (current === undefined) {
+ rawEvents.push({ type: 'delete', path: join(contentDir, name), entryKind: 'file' });
+ } else if (
+ current.kind === 'symlink' ||
+ (current.kind === 'regular' &&
+ (previous.kind === 'unresolved' ||
+ !sameGeneralIdentity(previous.identity, current.identity) ||
+ previous.metadata.size !== current.metadata.size ||
+ previous.metadata.modified !== current.metadata.modified))
+ ) {
+ rawEvents.push({ type: 'update', path: join(contentDir, name) });
+ }
+ }
+ for (const [docName, current] of observed.fileIndex) {
+ const previous = previousFiles.get(docName);
+ if (
+ markdownPublicMutationFor(docName, current) ||
+ (previous && markdownPublicMutationFor(docName, previous))
+ )
+ continue;
+ if (current.canonicalPath !== previous?.canonicalPath) {
+ rawEvents.push({ type: 'create', path: current.canonicalPath });
+ }
+ }
+ for (const [name, current] of observedGeneralFacts) {
+ if (current.kind !== 'regular' || publicMutations.generalEffects.has(name)) continue;
+ const previous = previousGeneralFacts.get(name);
+ if (previous === undefined) {
+ rawEvents.push({ type: 'create', path: join(contentDir, name) });
+ } else if (previous.kind === 'symlink') {
+ rawEvents.push({ type: 'update', path: join(contentDir, name) });
+ }
+ }
+ for (const [relativePath, previous] of folderIndex) {
+ if (!observed.folderIndex.has(relativePath)) {
+ rawEvents.push({ type: 'delete', path: join(contentDir, relativePath), entryKind: 'folder' });
+ } else if (observed.folderIndex.get(relativePath)?.canonicalPath !== previous.canonicalPath) {
+ rawEvents.push({ type: 'update', path: join(contentDir, relativePath) });
+ }
+ }
+ for (const [relativePath, current] of observed.folderIndex) {
+ if (!folderIndex.has(relativePath))
+ rawEvents.push({ type: 'create', path: current.canonicalPath });
+ }
+ for (const [alias, path] of aliasPaths) {
+ if (!observed.aliasPaths.has(alias))
+ rawEvents.push({ type: 'delete', path, entryKind: 'file' });
+ }
+
+ const deduplicated = [
+ ...new Map(
+ rawEvents.map((event) => [
+ event.type === 'delete'
+ ? `${event.type}:${event.entryKind}:${event.path}`
+ : `${event.type}:${event.path}`,
+ event,
+ ]),
+ ).values(),
+ ];
+ if (deduplicated.length > 0) {
+ const admitRecoveredEvent = (event: DiskEvent): boolean => {
+ const markdownNames = publicMutations.markdownNames;
+ const generalNames = publicMutations.generalNames;
+ if (markdownNames.size === 0 && generalNames.size === 0) return true;
+ if (event.kind === 'rename') {
+ return !markdownNames.has(event.oldDocName) && !markdownNames.has(event.newDocName);
+ }
+ if (event.kind === 'folder-create' || event.kind === 'folder-delete') {
+ return ![...markdownNames, ...generalNames].some(
+ (name) => name === event.relativePath || name.startsWith(`${event.relativePath}/`),
+ );
+ }
+ if (!('docName' in event)) {
+ const pathName = toPosix(relative(contentDir, event.path));
+ return (
+ !publicMutations.generalEffects.has(event.relativePath) &&
+ !publicMutations.generalEffects.has(pathName)
+ );
+ }
+ if (markdownNames.has(event.docName)) return false;
+ for (const [indexedName, entry] of fileIndex) {
+ if (entry.canonicalPath === event.path && markdownPublicMutationFor(indexedName, entry))
+ return false;
+ }
+ return true;
+ };
+ await handleRawEventsInternal(
+ deduplicated,
+ contentDir,
+ contentFilter,
+ fileIndex,
+ folderIndex,
+ onDiskEvent,
+ aliasMap,
+ admitRecoveredEvent,
+ generalFileIndex,
+ aliasPaths,
+ );
+ }
+
+ for (const [path, prior] of previousHashes) {
+ if (
+ isWithinContentDir(path, contentDir) &&
+ !publicMutations.markdownNames.has(pathToDocName(path, contentDir)) &&
+ !observed.hashes.has(path) &&
+ lastKnownHash.get(path) === prior
+ ) {
+ lastKnownHash.delete(path);
+ }
+ }
+ for (const [path, hash] of observed.hashes) {
+ if (publicMutations.markdownNames.has(pathToDocName(path, contentDir))) continue;
+ const current = lastKnownHash.get(path);
+ if (current === undefined || current === previousHashes.get(path))
+ lastKnownHash.set(path, hash);
+ }
+
+ for (const [name, prior] of previousFiles) {
+ const current = fileIndex.get(name);
+ if (
+ !markdownPublicMutationFor(name, prior) &&
+ !observed.fileIndex.has(name) &&
+ current === prior
+ ) {
+ fileIndex.delete(name);
+ forgetDocExtension(name);
+ }
+ }
+ const inventory = selectObservedInventory(observed, contentDir, contentFilter);
+ for (const [name, entry] of observed.fileIndex) {
+ if (markdownPublicMutationFor(name, entry)) continue;
+ if (inventory.fileIndex.has(name)) fileIndex.set(name, entry);
+ else if (fileIndex.get(name)?.canonicalPath === entry.canonicalPath) fileIndex.delete(name);
+ }
+ const selectedGeneralFacts = inventory.generalFacts;
+ for (const [path, effect] of publicMutations.generalEffects) {
+ if (effect) selectedGeneralFacts.set(path, effect);
+ else selectedGeneralFacts.delete(path);
+ }
+ rebuildGeneralFileIndex(
+ generalFileIndex,
+ contentDir,
+ selectedGeneralFacts,
+ generalRepresentativeNames(previousGeneralFiles),
+ publicMutations.generalMetadata,
+ );
+
+ for (const [path, prior] of previousFolders) {
+ if (!observed.folderIndex.has(path) && folderIndex.get(path) === prior)
+ folderIndex.delete(path);
+ }
+ for (const [path, entry] of inventory.folderIndex) {
+ const current = folderIndex.get(path);
+ if (
+ current === undefined ||
+ current === previousFolders.get(path) ||
+ (current.canonicalPath === entry.canonicalPath &&
+ current.modified === entry.modified &&
+ current.inode === entry.inode)
+ ) {
+ folderIndex.set(path, entry);
+ }
+ }
+ for (const [alias, prior] of previousAliases) {
+ if (!observed.aliasMap.has(alias) && aliasMap.get(alias) === prior) aliasMap.delete(alias);
+ }
+ for (const [alias, canonical] of observed.aliasMap) {
+ const current = aliasMap.get(alias);
+ if (current === undefined || current === previousAliases.get(alias))
+ aliasMap.set(alias, canonical);
+ }
+ for (const [alias, prior] of previousAliasPaths) {
+ if (!observed.aliasPaths.has(alias) && aliasPaths.get(alias) === prior)
+ aliasPaths.delete(alias);
+ }
+ for (const [alias, path] of observed.aliasPaths) {
+ const current = aliasPaths.get(alias);
+ if (current === undefined || current === previousAliasPaths.get(alias))
+ aliasPaths.set(alias, path);
+ }
+ for (const [alias, prior] of previousFolderAliases) {
+ if (!observed.folderAliasIndex.has(alias) && folderAliasIndex.get(alias) === prior) {
+ folderAliasIndex.delete(alias);
+ }
+ }
+ for (const [alias, canonical] of inventory.folderAliasIndex) {
+ const current = folderAliasIndex.get(alias);
+ if (current === undefined || current === previousFolderAliases.get(alias)) {
+ folderAliasIndex.set(alias, canonical);
+ }
+ }
+ const publicParentDirs = new Set<string>();
+ for (const name of [...publicMutations.markdownNames, ...publicMutations.generalNames]) {
+ let parent = dirname(name);
+ while (parent !== '.' && parent !== '') {
+ publicParentDirs.add(parent);
+ const next = dirname(parent);
+ if (next === parent) break;
+ parent = next;
+ }
+ }
+ for (const relativePath of publicParentDirs) {
+ const path = join(contentDir, relativePath);
+ if (contentRelativePath(contentDir, path) !== relativePath) continue;
+ if (contentFilter?.isDirExcluded(relativePath)) {
+ removeFolderIndexEntries(folderIndex, relativePath);
+ folderAliasIndex.delete(relativePath);
+ continue;
+ }
+ let folderStat: ReturnType<typeof statSync>;
+ let canonicalPath = path;
+ try {
+ const lst = lstatSync(path);
+ if (lst.isSymbolicLink()) {
+ canonicalPath = realpathSync(path);
+ if (!isWithinContentDir(canonicalPath, contentDir)) {
+ removeFolderIndexEntries(folderIndex, relativePath);
+ folderAliasIndex.delete(relativePath);
+ continue;
+ }
+ folderStat = statSync(canonicalPath);
+ } else {
+ folderStat = lst;
+ }
+ } catch (err) {
+ const code = errnoCode(err);
+ if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'ELOOP') {
+ removeFolderIndexEntries(folderIndex, relativePath);
+ folderAliasIndex.delete(relativePath);
+ } else {
+ log.warn({ path, err }, `Failed to refresh public mutation folder ${path}`);
+ }
+ continue;
+ }
+ if (!folderStat.isDirectory()) {
+ removeFolderIndexEntries(folderIndex, relativePath);
+ folderAliasIndex.delete(relativePath);
+ continue;
+ }
+ upsertFolderIndexEntry(folderIndex, contentDir, path, folderStat, canonicalPath);
+ if (canonicalPath === path) folderAliasIndex.delete(relativePath);
+ else folderAliasIndex.set(relativePath, toPosix(relative(contentDir, canonicalPath)));
+ }
+ const aliasChanges: RecoveredAliasCandidate[] = [];
+ const finalGeneralFacts = generalPathFacts(generalFileIndex);
+ for (const [alias, previous] of previousGeneralFacts) {
+ if (previous.kind !== 'symlink' || publicMutations.generalEffects.has(alias)) continue;
+ if (finalGeneralFacts.has(alias)) continue;
+ if (!generalAliasIsAdmitted(alias, previous.targetPath, contentFilter)) continue;
+ aliasChanges.push({ kind: 'delete', alias, targetPath: previous.targetPath });
+ }
+ for (const [alias, current] of finalGeneralFacts) {
+ if (current.kind !== 'symlink' || publicMutations.generalEffects.has(alias)) continue;
+ if (!generalAliasIsAdmitted(alias, current.targetPath, contentFilter)) continue;
+ const previous = previousGeneralFacts.get(alias);
+ if (previous?.kind === 'symlink' && previous.targetPath === current.targetPath) continue;
+ const target = finalGeneralFacts.get(current.targetPath);
+ if (target?.kind !== 'regular') continue;
+ aliasChanges.push({
+ kind: 'target-update',
+ alias,
+ targetPath: current.targetPath,
+ targetIdentity: target.identity,
+ });
+ }
+ if (aliasChanges.length > 0) {
+ onAfterMutation();
+ let currentGeneration = getFileIndexGeneration();
+ let currentGeneralFacts = generalPathFacts(generalFileIndex);
+ for (const candidate of aliasChanges) {
+ if (!generalAliasIsAdmitted(candidate.alias, candidate.targetPath, contentFilter)) continue;
+ const generation = getFileIndexGeneration();
+ if (generation !== currentGeneration) {
+ currentGeneralFacts = generalPathFacts(generalFileIndex);
+ currentGeneration = generation;
+ }
+ let event: FileDiskEvent;
+ if (candidate.kind === 'delete') {
+ if (
+ publicMutations.generalEffects.has(candidate.alias) ||
+ currentGeneralFacts.has(candidate.alias)
+ )
+ continue;
+ event = {
+ kind: 'file-delete',
+ path: join(contentDir, candidate.alias),
+ relativePath: candidate.alias,
+ };
+ } else {
+ if (
+ publicMutations.generalEffects.has(candidate.alias) ||
+ publicMutations.generalEffects.has(candidate.targetPath)
+ )
+ continue;
+ const alias = currentGeneralFacts.get(candidate.alias);
+ const target = currentGeneralFacts.get(candidate.targetPath);
+ if (
+ alias?.kind !== 'symlink' ||
+ alias.targetPath !== candidate.targetPath ||
+ target?.kind !== 'regular' ||
+ !sameGeneralIdentity(target.identity, candidate.targetIdentity)
+ )
+ continue;
+ event = {
+ kind: 'file-update',
+ path: join(contentDir, candidate.targetPath),
+ relativePath: candidate.targetPath,
+ size: target.metadata.size,
+ modifiedTs: Date.parse(target.metadata.modified),
+ inode: target.identity.inode,
+ };
+ }
+ recordWatcherDecision('dispatched', event.kind, event.path);
+ await onDiskEvent(event);
+ }
+ }
+ onRawBatch?.([...new Set([...observed.paths, ...knownPaths])]);
+ return true;
+}
+
export function toParcelIgnorePaths(
watcherIgnoreGlobs: readonly string[],
discoveredStructuralDirs: Iterable<string> = [],
@@ -1452,18 +3120,29 @@ export function toParcelIgnorePaths(
return [...entries].filter((entry) => !GLOB_METACHARACTER_RE.test(entry));
}
+type RecoveryPublicMutations = GeneralMutationRecord & {
+ markdownNames: Set<string>;
+ hashEffects: Map<string, string | null>;
+};
+
async function startParcelWatcher(
contentDir: string,
contentFilter: ContentFilter | undefined,
fileIndex: Map<string, FileIndexEntry>,
+ generalFileIndex: GeneralFileIndex,
folderIndex: Map<string, FolderIndexEntry>,
onDiskEvent: (event: DiskEvent) => Promise<void>,
aliasMap: Map<string, string>,
+ aliasPaths: Map<string, string>,
+ folderAliasIndex: Map<string, string>,
+ setActivePublicMutations: (mutations: RecoveryPublicMutations | null) => void,
onAfterMutation: () => void,
+ getFileIndexGeneration: () => number,
platform: NodeJS.Platform,
onRawBatch?: (absPaths: readonly string[]) => void,
discoveredStructuralDirs?: ReadonlySet<string>,
-): Promise<AsyncSubscription | null> {
+ onRecoveryComplete?: () => Promise<void>,
+): Promise<(AsyncSubscription & { runOrdered(work: () => Promise<void>): Promise<void> }) | null> {
let parcel: typeof import('@parcel/watcher');
try {
parcel = await import('@parcel/watcher');
@@ -1485,35 +3164,136 @@ async function startParcelWatcher(
}
: undefined;
+ let closed = false;
+ let workTail = Promise.resolve();
+ const runOrdered = (work: () => Promise<void>): Promise<void> => {
+ if (closed) return Promise.resolve();
+ const next = workTail.then(work);
+ workTail = next.catch((err) => {
+ log.error({ err }, 'parcel batch error');
+ });
+ return next;
+ };
+ let recoveryRunning = false;
+ let nextRecovery: Promise<void> | undefined;
+ let followUpRecovery: PromiseWithResolvers<void> | undefined;
+ const recoverOnce = async (): Promise<void> => {
+ nextRecovery = undefined;
+ if (closed) return;
+ recoveryRunning = true;
+ const recoveryMutations: RecoveryPublicMutations = {
+ markdownNames: new Set(),
+ generalNames: new Set(),
+ generalEffects: new Map(),
+ generalMetadata: new Map(),
+ hashEffects: new Map(),
+ };
+ try {
+ setActivePublicMutations(recoveryMutations);
+ const recovered = await recoverDiskChanges(
+ contentDir,
+ contentFilter,
+ fileIndex,
+ generalFileIndex,
+ folderIndex,
+ aliasMap,
+ aliasPaths,
+ folderAliasIndex,
+ recoveryMutations,
+ onDiskEvent,
+ onAfterMutation,
+ getFileIndexGeneration,
+ onRawBatch,
+ );
+ onAfterMutation();
+ if (recovered) {
+ await onRecoveryComplete?.();
+ log.info({ completed: true }, 'parcel watcher recovery finished');
+ } else {
+ log.warn(
+ { completed: false },
+ 'parcel watcher recovery incomplete; known state retained',
+ );
+ }
+ } catch (handleErr) {
+ log.error({ err: handleErr }, 'parcel batch error');
+ } finally {
+ try {
+ for (const [path, hash] of recoveryMutations.hashEffects) {
+ if (hash === null) removeLastKnownHash(path);
+ else updateLastKnownHash(path, hash);
+ }
+ } finally {
+ setActivePublicMutations(null);
+ recoveryRunning = false;
+ const followUp = followUpRecovery;
+ followUpRecovery = undefined;
+ if (followUp) followUp.resolve(runOrdered(recoverOnce));
+ }
+ }
+ };
+ const requestRecovery = (): Promise<void> => {
+ if (nextRecovery) return nextRecovery;
+ if (recoveryRunning) {
+ followUpRecovery = Promise.withResolvers<void>();
+ nextRecovery = followUpRecovery.promise;
+ } else {
+ nextRecovery = runOrdered(recoverOnce);
+ }
+ return nextRecovery;
+ };
const subscription = await subscribeParcel(
parcel,
contentDir,
- async (err, events) => {
- if (err) {
- log.error({ err }, 'parcel watcher callback error');
+ (err, events) => {
+ if (closed) return;
+ const notification = classifyParcelNotification(err, events);
+ if (notification.kind === 'error') {
+ log.error({ err: notification.error }, 'parcel watcher callback error');
return;
}
- try {
- onRawBatch?.(events.map((e) => e.path));
- await handleRawEvents(
- events.map((e) => ({ type: e.type, path: e.path })),
- contentDir,
- contentFilter,
- fileIndex,
- folderIndex,
- onDiskEvent,
- aliasMap,
+ if (notification.kind === 'rescan') {
+ log.warn(
+ { err: notification.error, eventCount: notification.events.length },
+ 'parcel watcher recovery requested',
);
- onAfterMutation();
- } catch (handleErr) {
- log.error({ err: handleErr }, 'parcel batch error');
}
+ const records = runOrdered(async () => {
+ if (closed) return;
+ try {
+ onRawBatch?.(notification.events.map((event) => event.path));
+ await handleRawEventsInternal(
+ notification.events.map((event) => ({ type: event.type, path: event.path })),
+ contentDir,
+ contentFilter,
+ fileIndex,
+ folderIndex,
+ onDiskEvent,
+ aliasMap,
+ undefined,
+ generalFileIndex,
+ aliasPaths,
+ );
+ onAfterMutation();
+ } catch (handleErr) {
+ log.error({ err: handleErr }, 'parcel batch error');
+ }
+ });
+ if (notification.kind !== 'rescan') return records;
+ return Promise.all([records, requestRecovery()]);
},
subscribeOpts,
platform,
);
- return subscription;
+ return {
+ runOrdered,
+ async unsubscribe() {
+ closed = true;
+ await subscription.unsubscribe();
+ await workTail;
+ },
+ };
} catch (err) {
log.warn({ err }, '@parcel/watcher subscribe failed, falling back to chokidar');
return null;
@@ -1570,9 +3350,11 @@ async function startChokidarWatcher(
contentDir: string,
contentFilter: ContentFilter | undefined,
fileIndex: Map<string, FileIndexEntry>,
+ generalFileIndex: GeneralFileIndex,
folderIndex: Map<string, FolderIndexEntry>,
onDiskEvent: (event: DiskEvent) => Promise<void>,
aliasMap: Map<string, string>,
+ aliasPaths: Map<string, string>,
onAfterMutation: () => void,
platform: NodeJS.Platform,
onRawBatch?: (absPaths: readonly string[]) => void,
@@ -1591,17 +3373,17 @@ async function startChokidarWatcher(
watcher.on('error', (err) => log.error({ err }, 'chokidar error'));
const BATCH_WINDOW_MS = 50;
- let pendingEvents: Array<{ type: 'create' | 'update' | 'delete'; path: string }> = [];
+ let pendingEvents: InternalRawFileEvent[] = [];
let batchTimer: ReturnType<typeof setTimeout> | null = null;
- function queueEvent(type: 'create' | 'update' | 'delete', path: string) {
- pendingEvents.push({ type, path });
+ function queueEvent(event: InternalRawFileEvent) {
+ pendingEvents.push(event);
batchTimer ||= setTimeout(() => {
const batch = pendingEvents;
pendingEvents = [];
batchTimer = null;
onRawBatch?.(batch.map((e) => e.path));
- handleRawEvents(
+ handleRawEventsInternal(
batch,
contentDir,
contentFilter,
@@ -1609,17 +3391,20 @@ async function startChokidarWatcher(
folderIndex,
onDiskEvent,
aliasMap,
+ undefined,
+ generalFileIndex,
+ aliasPaths,
)
.then(onAfterMutation)
.catch((err) => log.error({ err }, 'chokidar batch error'));
}, BATCH_WINDOW_MS);
}
- watcher.on('add', (path) => queueEvent('create', path));
- watcher.on('change', (path) => queueEvent('update', path));
- watcher.on('unlink', (path) => queueEvent('delete', path));
- watcher.on('addDir', (path) => queueEvent('create', path));
- watcher.on('unlinkDir', (path) => queueEvent('delete', path));
+ watcher.on('add', (path) => queueEvent({ type: 'create', path }));
+ watcher.on('change', (path) => queueEvent({ type: 'update', path }));
+ watcher.on('unlink', (path) => queueEvent({ type: 'delete', path, entryKind: 'file' }));
+ watcher.on('addDir', (path) => queueEvent({ type: 'create', path }));
+ watcher.on('unlinkDir', (path) => queueEvent({ type: 'delete', path, entryKind: 'folder' }));
await new Promise<void>((resolveReady) => {
let settled = false;
@@ -1653,10 +3438,11 @@ export async function startWatcher(
opts: {
forceBackend?: 'parcel' | 'chokidar';
onRawBatch?: (absPaths: readonly string[]) => void;
+ onRecoveryComplete?: () => Promise<void>;
platform?: NodeJS.Platform;
} = {},
): Promise<WatcherHandle> {
- const { onRawBatch } = opts;
+ const { onRawBatch, onRecoveryComplete } = opts;
let contentDir: string;
try {
contentDir = realpathSync(contentDirRaw);
@@ -1665,9 +3451,19 @@ export async function startWatcher(
}
const fileIndex = new Map<string, FileIndexEntry>();
+ const generalFileIndex = new GeneralFileIndex(contentDir);
+ const allFileEntries: AllFileEntries = {
+ *[Symbol.iterator]() {
+ yield* fileIndex;
+ yield* generalFileIndex;
+ },
+ };
const folderIndex = new Map<string, FolderIndexEntry>();
const aliasMap = new Map<string, string>();
+ const aliasPaths = new Map<string, string>();
const folderAliasIndex = new Map<string, string>();
+ let activePublicMutations: RecoveryPublicMutations | null = null;
+ let activeReseedMutations: GeneralMutationRecord | null = null;
let fileIndexGeneration = 0;
let cachedMarkdownView: ReadonlyMap<string, FileIndexEntry> | null = null;
@@ -1678,23 +3474,25 @@ export async function startWatcher(
const structuralIgnoreDirs = new Set<string>();
- await seedLastKnownHashes(
- contentDir,
- contentDir,
- contentFilter,
+ const initialObservation = await observeDisk(contentDir, contentFilter);
+ publishDiskObservation(
+ initialObservation,
+ initialObservation,
fileIndex,
+ generalFileIndex,
folderIndex,
aliasMap,
folderAliasIndex,
- undefined,
structuralIgnoreDirs,
);
+ for (const [alias, path] of initialObservation.aliasPaths) aliasPaths.set(alias, path);
bumpFileIndexGeneration();
const evictionInterval = setInterval(evictStaleTrackerEntries, WRITE_TRACKER_TTL_MS);
const dropSummaryInterval = setInterval(logWatcherDropSummary, WATCHER_DROP_SUMMARY_INTERVAL_MS);
let subscription: AsyncSubscription;
+ let runOrderedRescan: ((work: () => Promise<void>) => Promise<void>) | undefined;
let backend: WatcherBackend;
const forceChokidar = process.env.OK_FILE_WATCHER_BACKEND === 'chokidar';
const platform = opts.platform ?? process.platform;
@@ -1706,16 +3504,25 @@ export async function startWatcher(
contentDir,
contentFilter,
fileIndex,
+ generalFileIndex,
folderIndex,
onDiskEvent,
aliasMap,
+ aliasPaths,
+ folderAliasIndex,
+ (mutations) => {
+ activePublicMutations = mutations;
+ },
bumpFileIndexGeneration,
+ () => fileIndexGeneration,
platform,
onRawBatch,
structuralIgnoreDirs,
+ onRecoveryComplete,
);
if (parcelSub) {
subscription = parcelSub;
+ runOrderedRescan = parcelSub.runOrdered;
backend = 'parcel';
} else {
if (opts.forceBackend === 'parcel') {
@@ -1725,9 +3532,11 @@ export async function startWatcher(
contentDir,
contentFilter,
fileIndex,
+ generalFileIndex,
folderIndex,
onDiskEvent,
aliasMap,
+ aliasPaths,
bumpFileIndexGeneration,
platform,
onRawBatch,
@@ -1748,11 +3557,11 @@ export async function startWatcher(
async unsubscribe() {
clearInterval(evictionInterval);
clearInterval(dropSummaryInterval);
+ await originalUnsubscribe();
writeTracker.clear();
removalTracker.clear();
lastKnownHash.clear();
resetWatcherDecisionDiagnostics();
- return originalUnsubscribe();
},
getFileIndex() {
if (cachedMarkdownView && cachedMarkdownViewGeneration === fileIndexGeneration) {
@@ -1763,7 +3572,7 @@ export async function startWatcher(
return cachedMarkdownView;
},
getAllFilesIndex() {
- return fileIndex;
+ return allFileEntries;
},
getFileIndexGeneration() {
return fileIndexGeneration;
@@ -1781,48 +3590,262 @@ export async function startWatcher(
return structuralIgnoreDirs;
},
mutateFileIndex(event) {
- updateFileIndex(event, fileIndex);
+ if (event.kind === 'rename') {
+ activePublicMutations?.markdownNames.add(event.oldDocName);
+ activePublicMutations?.markdownNames.add(event.newDocName);
+ } else if ('docName' in event) {
+ activePublicMutations?.markdownNames.add(event.docName);
+ }
+ if (
+ event.kind === 'file-create' ||
+ event.kind === 'file-update' ||
+ event.kind === 'file-delete'
+ ) {
+ let changedPaths: ReadonlySet<string> = new Set();
+ if (event.kind === 'file-delete') {
+ const before = generalFactsFor(generalFileIndex, [event.relativePath]);
+ removeKnownGeneralPath(generalFileIndex, contentDir, event.relativePath);
+ const after = generalFactsFor(generalFileIndex, before.keys());
+ changedPaths = new Set([...before.keys()].filter((path) => !after.has(path)));
+ } else {
+ try {
+ const lexicalPath = join(contentDir, event.relativePath);
+ const lexicalStat = lstatSync(lexicalPath);
+ const leafSymlink = lexicalStat.isSymbolicLink();
+ const canonicalPath = realpathSync(lexicalPath);
+ if (!isWithinContentDir(canonicalPath, contentDir)) {
+ throw new Error('General file path resolves outside content directory');
+ }
+ const physicalStat = leafSymlink ? statSync(canonicalPath) : lexicalStat;
+ const registered = registerKnownGeneralPath(
+ generalFileIndex,
+ contentDir,
+ toPosix(relative(contentDir, canonicalPath)),
+ event.relativePath,
+ leafSymlink,
+ { device: physicalStat.dev, inode: physicalStat.ino },
+ { size: event.size, modified: new Date(event.modifiedTs).toISOString() },
+ contentFilter,
+ );
+ if (registered.kind === 'unobserved') return;
+ changedPaths = registered.changedPaths;
+ } catch (err) {
+ log.warn({ path: event.path, err }, 'general file identity observation failed');
+ const canonicalName = toPosix(relative(contentDir, event.path));
+ let retained = false;
+ const candidates = new Set([
+ ...generalOwnerNames(generalFileIndex, canonicalName),
+ ...generalOwnerNames(generalFileIndex, event.relativePath),
+ ]);
+ for (const name of candidates) {
+ const entry = generalFileIndex.get(name);
+ const state = entry && knownGeneralState(entry);
+ if (!state) continue;
+ const members = state.entry.fileMembers;
+ if (
+ !members.regularPaths.includes(canonicalName) &&
+ !members.symlinks.some((relation) => relation.path === event.relativePath)
+ )
+ continue;
+ storeKnownGeneralGroup(
+ generalFileIndex,
+ contentDir,
+ name,
+ state.identity,
+ members.regularPaths,
+ members.symlinks,
+ { size: event.size, modified: new Date(event.modifiedTs).toISOString() },
+ );
+ retained = true;
+ break;
+ }
+ if (!retained) storeUnresolvedGeneralEntry(generalFileIndex, contentDir, event);
+ }
+ }
+ if (activePublicMutations) {
+ recordGeneralPublicEffect(
+ activePublicMutations,
+ generalFileIndex,
+ contentDir,
+ event,
+ changedPaths,
+ );
+ }
+ if (activeReseedMutations) {
+ recordGeneralPublicEffect(
+ activeReseedMutations,
+ generalFileIndex,
+ contentDir,
+ event,
+ changedPaths,
+ );
+ }
+ } else {
+ updateFileIndex(event, fileIndex);
+ }
+ const hashEffects = activePublicMutations?.hashEffects;
+ if (hashEffects) {
+ switch (event.kind) {
+ case 'create':
+ case 'update':
+ case 'conflict':
+ if (!isReservedForUserTree(event.docName)) {
+ hashEffects.set(event.path, contentHash(event.content));
+ }
+ break;
+ case 'delete':
+ if (!isReservedForUserTree(event.docName)) hashEffects.set(event.path, null);
+ break;
+ case 'rename':
+ if (!isReservedForUserTree(event.newDocName)) {
+ hashEffects.set(event.oldPath, null);
+ hashEffects.set(event.newPath, contentHash(event.content));
+ }
+ break;
+ case 'asset-create':
+ case 'asset-delete':
+ case 'folder-create':
+ case 'folder-delete':
+ case 'file-create':
+ case 'file-update':
+ case 'file-delete':
+ break;
+ default:
+ assertNeverDiskEvent(event);
+ }
+ }
bumpFileIndexGeneration();
},
pruneFileIndexNowExcluded() {
if (!contentFilter) return 0;
let pruned = 0;
+ let changed = false;
+ const removedGeneralPaths = new Set<string>();
for (const [docName, entry] of fileIndex) {
const relPath = toPosix(relative(contentDir, entry.canonicalPath));
- const excluded =
- entry.kind === 'file'
- ? contentFilter.isPathIgnored(relPath)
- : contentFilter.isExcluded(relPath);
- if (excluded) {
+ if (contentFilter.isExcluded(relPath)) {
fileIndex.delete(docName);
pruned++;
}
}
- if (pruned > 0) bumpFileIndexGeneration();
+ for (const [name, entry] of generalFileIndex) {
+ const state = knownGeneralState(entry);
+ if (!state) {
+ const relPath = toPosix(relative(contentDir, entry.canonicalPath));
+ if (contentFilter.isPathIgnored(relPath)) {
+ generalFileIndex.delete(name);
+ removedGeneralPaths.add(name);
+ pruned++;
+ }
+ continue;
+ }
+ const members = state.entry.fileMembers;
+ const regular = members.regularPaths.filter((path) => !contentFilter.isPathIgnored(path));
+ const symlinks = members.symlinks.filter(
+ (relation) =>
+ !contentFilter.isPathIgnored(relation.path) &&
+ !contentFilter.isPathIgnored(relation.targetPath) &&
+ regular.includes(relation.targetPath),
+ );
+ if (
+ regular.length === members.regularPaths.length &&
+ symlinks.length === members.symlinks.length
+ )
+ continue;
+ const retained = new Set([...regular, ...symlinks.map((relation) => relation.path)]);
+ for (const path of members.regularPaths) {
+ if (!retained.has(path)) removedGeneralPaths.add(path);
+ }
+ for (const relation of members.symlinks) {
+ if (!retained.has(relation.path)) removedGeneralPaths.add(relation.path);
+ }
+ if (regular.length === 0) pruned++;
+ storeKnownGeneralGroup(
+ generalFileIndex,
+ contentDir,
+ name,
+ state.identity,
+ regular,
+ symlinks,
+ entry,
+ state.sequence,
+ );
+ changed = true;
+ }
+ for (const record of [activePublicMutations, activeReseedMutations]) {
+ if (!record) continue;
+ for (const path of removedGeneralPaths) {
+ if (record.generalEffects.get(path)) record.generalEffects.set(path, null);
+ }
+ }
+ if (changed || pruned > 0) bumpFileIndexGeneration();
return pruned;
},
pruneFolderIndexNowExcluded() {
if (!contentFilter) return 0;
let pruned = 0;
+ let aliasesChanged = false;
for (const folderPath of folderIndex.keys()) {
if (contentFilter.isDirExcluded(folderPath)) {
folderIndex.delete(folderPath);
pruned++;
}
}
+ for (const alias of folderAliasIndex.keys()) {
+ if (contentFilter.isDirExcluded(alias)) {
+ folderAliasIndex.delete(alias);
+ aliasesChanged = true;
+ }
+ }
+ if (pruned > 0 || aliasesChanged) bumpFileIndexGeneration();
return pruned;
},
async rescanFromDisk() {
- await seedLastKnownHashes(
- contentDir,
- contentDir,
- contentFilter,
- fileIndex,
- folderIndex,
- aliasMap,
- folderAliasIndex,
- );
- bumpFileIndexGeneration();
+ const reseed = async () => {
+ const mutations: GeneralMutationRecord = {
+ generalNames: new Set(),
+ generalEffects: new Map(),
+ generalMetadata: new Map(),
+ };
+ activeReseedMutations = mutations;
+ try {
+ const observation = await observeDisk(contentDir, contentFilter);
+ const inventory = selectObservedInventory(observation, contentDir, contentFilter);
+ publishDiskObservation(
+ observation,
+ inventory,
+ fileIndex,
+ generalFileIndex,
+ folderIndex,
+ aliasMap,
+ folderAliasIndex,
+ undefined,
+ false,
+ );
+ const previous = new Map(generalFileIndex);
+ const facts = generalPathFacts(generalFileIndex);
+ for (const [path, fact] of inventory.generalFacts) {
+ if (!mutations.generalEffects.has(path)) facts.set(path, fact);
+ }
+ for (const [path, effect] of mutations.generalEffects) {
+ if (effect) facts.set(path, effect);
+ else facts.delete(path);
+ }
+ rebuildGeneralFileIndex(
+ generalFileIndex,
+ contentDir,
+ facts,
+ generalRepresentativeNames(previous),
+ mutations.generalMetadata,
+ );
+ for (const [alias, path] of observation.aliasPaths) aliasPaths.set(alias, path);
+ bumpFileIndexGeneration();
+ } finally {
+ activeReseedMutations = null;
+ }
+ };
+ if (runOrderedRescan) return runOrderedRescan(reseed);
+ return reseed();
},
};
}
diff --git a/packages/server/src/head-watcher.ts b/packages/server/src/head-watcher.ts
index a2e5ecc0c..a8d0637c6 100644
--- a/packages/server/src/head-watcher.ts
+++ b/packages/server/src/head-watcher.ts
@@ -3,6 +3,7 @@ import {
type GitRepository,
} from '@inkeep/open-knowledge-core/git-repository';
import { getLogger } from './logger.ts';
+import { classifyParcelNotification } from './parcel-recovery.ts';
import { subscribeParcel } from './parcel-subscription.ts';
const log = getLogger('head-watcher');
@@ -69,7 +70,8 @@ export function watchedGitFile(rawPath: string): string | null {
async function tryStartParcelHeadWatcher(
gitDir: string,
- dispatch: HeadEventDispatch,
+ dispatch: (rawPath: string) => boolean,
+ recover: () => void,
platform: NodeJS.Platform,
): Promise<(() => Promise<void>) | null> {
let parcel: typeof import('@parcel/watcher');
@@ -87,11 +89,22 @@ async function tryStartParcelHeadWatcher(
parcel,
gitDir,
(err, events) => {
- if (err) {
- log.warn({ err }, '[head-watcher] parcel subscription error');
+ const notification = classifyParcelNotification(err, events);
+ if (notification.kind === 'error') {
+ log.warn({ err: notification.error }, '[head-watcher] parcel subscription error');
return;
}
- for (const event of events) dispatch(event.path);
+ if (notification.kind === 'rescan') {
+ log.warn(
+ { err: notification.error, eventCount: notification.events.length },
+ '[head-watcher] parcel recovery requested',
+ );
+ }
+ let hadWatchedRecord = false;
+ for (const event of notification.events) {
+ if (dispatch(event.path)) hadWatchedRecord = true;
+ }
+ if (notification.kind === 'rescan' && !hadWatchedRecord) recover();
},
undefined,
platform,
@@ -149,6 +162,8 @@ export async function startHeadWatcher(
let oldHead: string | null = null;
let lastKnownBranch: string | null = null;
let batchEndInFlight: Promise<void> | null = null;
+ let headWork = Promise.resolve();
+ let closed = false;
async function emitBatchEnd(timeout: boolean): Promise<void> {
if (beginInFlight) await beginInFlight;
@@ -245,9 +260,28 @@ export async function startHeadWatcher(
resetQuietWindow();
}
- const dispatch: HeadEventDispatch = (rawPath) => {
+ const admitHeadEvent = (trigger: string): Promise<void> => {
+ const work = headWork.then(async () => {
+ try {
+ await handleGitEvent(trigger);
+ } catch (err) {
+ log.error({ err }, 'HEAD event handling failed');
+ }
+ });
+ headWork = work;
+ return work;
+ };
+
+ const dispatch = (rawPath: string): boolean => {
+ if (closed) return false;
const fileName = watchedGitFile(rawPath);
- if (fileName !== null) void handleGitEvent(fileName);
+ if (fileName === null) return false;
+ void admitHeadEvent(fileName);
+ return true;
+ };
+ const recover = (): void => {
+ if (closed) return;
+ void admitHeadEvent('rescan');
};
let resolvedUnsub: (() => Promise<void>) | null = null;
@@ -259,6 +293,7 @@ export async function startHeadWatcher(
resolvedUnsub = await tryStartParcelHeadWatcher(
gitDir,
dispatch,
+ recover,
opts.platform ?? process.platform,
);
if (resolvedUnsub) backend = 'parcel';
@@ -280,12 +315,15 @@ export async function startHeadWatcher(
return {
unsubscribe: async () => {
- if (inBatch) {
- await emitBatchEnd(false);
+ closed = true;
+ try {
+ await unsubscribeFn();
+ } finally {
+ await headWork;
+ if (inBatch) await emitBatchEnd(false);
+ if (quietTimer) clearTimeout(quietTimer);
+ if (timeoutTimer) clearTimeout(timeoutTimer);
}
- if (quietTimer) clearTimeout(quietTimer);
- if (timeoutTimer) clearTimeout(timeoutTimer);
- await unsubscribeFn();
},
getLastKnownBranch: () => lastKnownBranch,
};
diff --git a/packages/server/src/http/document-routes.test.ts b/packages/server/src/http/document-routes.test.ts
index 0da860d95..5e8f79dd4 100644
--- a/packages/server/src/http/document-routes.test.ts
+++ b/packages/server/src/http/document-routes.test.ts
@@ -1,17 +1,45 @@
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import {
+ lstatSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
import { ServerResponse } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Hocuspocus } from '@hocuspocus/server';
import { LOCAL_DIR } from '@inkeep/open-knowledge-core';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { makeCaptureRes, makeSyntheticReq } from '../composition-rig.test-helper.ts';
import { createTestConflictAuthority } from '../conflict-authority.test-helper.ts';
import type { ConflictAuthority } from '../conflict-authority.ts';
import { createContentFilter } from '../content-filter.ts';
+import {
+ type AllFileEntries,
+ type DiskEvent,
+ type FileIndexEntry,
+ type FolderIndexEntry,
+ startWatcher,
+} from '../file-watcher.ts';
+import { localTargetInventoryFromWatcher } from '../local-target-inventory.ts';
import { loggerFactory } from '../logger.ts';
+import {
+ forgetNativeSubscriptions,
+ nativeSubscriptionOn,
+} from '../parcel-watcher-double.test-helper.ts';
import { createDocumentRoutes, type DocumentRouteDeps } from './document-routes.ts';
+vi.mock('@parcel/watcher', async () => {
+ const { parcelWatcherModule } = await import('../parcel-watcher-double.test-helper.ts');
+ return parcelWatcherModule;
+});
+
const DOC_NAME = 'notes/topic';
const DOC_FILE = 'notes/topic.md';
@@ -152,3 +180,303 @@ describe('/api/documents?showAll single-flight walk', () => {
await pending;
});
});
+
+test.each(['repeatable', 'single-pass'] as const)(
+ 'regular group members and true symlinks survive both listing traversals of a %s inventory',
+ async (shape) => {
+ const rich = {
+ kind: 'file' as const,
+ canonicalPath: join(projectDir, 'outside/atlas.csv'),
+ inode: 41,
+ size: 5,
+ modified: '2026-01-01T00:00:00.000Z',
+ aliases: ['linked-atlas.csv', 'linked-beacon.csv'],
+ fileMembers: {
+ regularPaths: ['outside/atlas.csv', 'canonical/beacon.csv'],
+ symlinks: [
+ { path: 'linked-atlas.csv', targetPath: 'outside/atlas.csv' },
+ { path: 'linked-beacon.csv', targetPath: 'canonical/beacon.csv' },
+ ],
+ },
+ };
+ const rows = new Map<string, FileIndexEntry>([['outside/atlas.csv', rich]]);
+ const allFiles: AllFileEntries = {
+ *[Symbol.iterator]() {
+ yield* rows;
+ },
+ };
+ const folders = new Map<string, FolderIndexEntry>([
+ [
+ 'canonical',
+ {
+ size: 0,
+ modified: '2026-01-01T00:00:00.000Z',
+ canonicalPath: join(projectDir, 'canonical'),
+ inode: 42,
+ },
+ ],
+ ]);
+ const resolved = buildGroup(
+ createTestConflictAuthority(projectDir),
+ new Hocuspocus({ quiet: true }),
+ {
+ getAllFilesIndex: () => (shape === 'repeatable' ? allFiles : rows.entries()),
+ getFolderIndex: () => folders,
+ getFolderAliasIndex: () => new Map([['mirror', 'canonical']]),
+ },
+ ).table.resolve('/api/documents');
+ if (!resolved?.dispatch) throw new Error('no dispatch for /api/documents');
+ const readRows = async (url: string) => {
+ const req = makeSyntheticReq({ url });
+ const { res, captured } = makeCaptureRes();
+ await resolved.dispatch(req, res);
+ expect(captured.status).toBe(200);
+ return (
+ JSON.parse(captured.body) as {
+ documents: Array<{
+ kind: string;
+ docName?: string;
+ isSymlink: boolean;
+ targetPath: string | null;
+ }>;
+ }
+ ).documents;
+ };
+
+ for (const _read of [1, 2]) {
+ const all = await readRows('/api/documents');
+ expect
+ .soft(all.filter((row) => row.kind === 'file' && row.docName === 'outside/atlas.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ expect
+ .soft(all.filter((row) => row.kind === 'file' && row.docName === 'canonical/beacon.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ expect
+ .soft(all.filter((row) => row.kind === 'file' && row.docName === 'linked-beacon.csv'))
+ .toEqual([
+ expect.objectContaining({
+ isSymlink: true,
+ canonicalDocName: 'outside/atlas.csv',
+ targetPath: 'canonical/beacon.csv',
+ }),
+ ]);
+ expect
+ .soft(all.filter((row) => row.kind === 'file' && row.docName === 'mirror/beacon.csv'))
+ .toEqual([
+ expect.objectContaining({
+ isSymlink: true,
+ canonicalDocName: 'outside/atlas.csv',
+ targetPath: 'canonical/beacon.csv',
+ }),
+ ]);
+
+ const onlyCanonical = await readRows('/api/documents?dir=canonical');
+ expect
+ .soft(onlyCanonical.filter((row) => row.kind === 'file').map((row) => row.docName))
+ .toEqual(['canonical/beacon.csv']);
+ const onlyMirror = await readRows('/api/documents?dir=mirror');
+ expect
+ .soft(onlyMirror.filter((row) => row.kind === 'file').map((row) => row.docName))
+ .toEqual(['mirror/beacon.csv']);
+ }
+ },
+);
+
+test('a folder alias lists a contained legacy file alias', async () => {
+ const canonicalDir = join(projectDir, 'canonical');
+ mkdirSync(canonicalDir);
+ const target = join(canonicalDir, 'data.csv');
+ writeFileSync(target, 'canonical,bytes\n');
+ const alias = join(canonicalDir, 'y.csv');
+ symlinkSync(target, alias);
+ const mirror = join(projectDir, 'mirror');
+ symlinkSync(canonicalDir, mirror);
+ const targetStat = statSync(target);
+ const folderStat = statSync(canonicalDir);
+ const entry: FileIndexEntry = {
+ kind: 'file',
+ canonicalPath: target,
+ inode: targetStat.ino,
+ size: targetStat.size,
+ modified: targetStat.mtime.toISOString(),
+ aliases: ['canonical/y.csv'],
+ };
+ const allFiles = new Map<string, FileIndexEntry>([['canonical/data.csv', entry]]);
+ const folders = new Map<string, FolderIndexEntry>([
+ [
+ 'canonical',
+ {
+ size: 0,
+ modified: folderStat.mtime.toISOString(),
+ canonicalPath: canonicalDir,
+ inode: folderStat.ino,
+ },
+ ],
+ ]);
+ const resolved = buildGroup(
+ createTestConflictAuthority(projectDir),
+ new Hocuspocus({ quiet: true }),
+ {
+ getAllFilesIndex: () => allFiles,
+ getFolderIndex: () => folders,
+ getFolderAliasIndex: () => new Map([['mirror', 'canonical']]),
+ },
+ ).table.resolve('/api/documents');
+ if (!resolved?.dispatch) throw new Error('no dispatch for /api/documents');
+ const readRows = async (url: string) => {
+ const req = makeSyntheticReq({ url });
+ const { res, captured } = makeCaptureRes();
+ await resolved.dispatch(req, res);
+ expect(captured.status).toBe(200);
+ return (
+ JSON.parse(captured.body) as {
+ documents: Array<{
+ kind: string;
+ docName?: string;
+ path?: string;
+ size?: number;
+ modified?: string;
+ isSymlink: boolean;
+ canonicalDocName?: string | null;
+ targetPath: string | null;
+ }>;
+ }
+ ).documents;
+ };
+
+ const all = await readRows('/api/documents');
+ const onlyMirror = await readRows('/api/documents?dir=mirror');
+ expect(all.filter((row) => row.kind === 'file' && row.docName === 'canonical/y.csv')).toEqual([
+ expect.objectContaining({
+ path: 'canonical/y.csv',
+ size: targetStat.size,
+ modified: targetStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'canonical/data.csv',
+ targetPath: 'canonical/data.csv',
+ }),
+ ]);
+ for (const rows of [all, onlyMirror]) {
+ expect(rows.filter((row) => row.kind === 'file' && row.docName === 'mirror/data.csv')).toEqual([
+ expect.objectContaining({
+ path: 'mirror/data.csv',
+ size: targetStat.size,
+ modified: targetStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'canonical/data.csv',
+ targetPath: 'canonical/data.csv',
+ }),
+ ]);
+ expect
+ .soft(rows.filter((row) => row.kind === 'file' && row.docName === 'mirror/y.csv'))
+ .toEqual([
+ expect.objectContaining({
+ path: 'mirror/y.csv',
+ size: targetStat.size,
+ modified: targetStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'canonical/data.csv',
+ targetPath: 'canonical/data.csv',
+ }),
+ ]);
+ }
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(realpathSync(target));
+ expect(lstatSync(mirror).isSymbolicLink()).toBe(true);
+ expect(realpathSync(mirror)).toBe(realpathSync(canonicalDir));
+ expect(lstatSync(target).isFile()).toBe(true);
+});
+
+test('a public recovery creation preserves its literal folder alias and one listed row', async () => {
+ const root = realpathSync(projectDir);
+ const real = join(root, 'real.md');
+ mkdirSync(real);
+ const known = join(real, 'known.csv');
+ writeFileSync(known, 'known,bytes\n');
+ const first = join(root, 'first.md');
+ writeFileSync(first, '# First\n');
+ const linked = join(root, 'linked.mdx');
+ const created = join(real, 'created.csv');
+ const events: DiskEvent[] = [];
+ let creations = 0;
+ forgetNativeSubscriptions();
+ const watcher = await startWatcher(
+ root,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'first') return;
+ symlinkSync(real, linked);
+ writeFileSync(join(linked, 'created.csv'), 'public,bytes\n');
+ const stat = statSync(created);
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: created,
+ relativePath: 'linked.mdx/created.csv',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ creations++;
+ expect(
+ localTargetInventoryFromWatcher(watcher, root)?.fileTargets.includes('real.md/known.csv'),
+ ).toBe(true);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ try {
+ expect(watcher.getFolderIndex().has('real.md')).toBe(true);
+ expect(watcher.getFolderAliasIndex().size).toBe(0);
+ unlinkSync(first);
+ await nativeSubscriptionOn(root).deliver(
+ [],
+ new Error('Events were dropped by the FSEvents client. File system must be re-scanned.'),
+ );
+ expect(creations).toBe(1);
+ expect(events).toContainEqual({ kind: 'delete', path: first, docName: 'first' });
+ expect.soft([...watcher.getFolderAliasIndex()]).toEqual([['linked.mdx', 'real.md']]);
+ expect
+ .soft(
+ localTargetInventoryFromWatcher(watcher, root)?.fileTargets.includes(
+ 'linked.mdx/known.csv',
+ ),
+ )
+ .toBe(true);
+ const resolved = buildGroup(createTestConflictAuthority(root), hocuspocus, {
+ contentDir: root,
+ getFileIndex: () => watcher.getFileIndex(),
+ getFileIndexGeneration: () => watcher.getFileIndexGeneration(),
+ getAllFilesIndex: () => watcher.getAllFilesIndex(),
+ getFolderIndex: () => watcher.getFolderIndex(),
+ getFolderAliasIndex: () => watcher.getFolderAliasIndex(),
+ }).table.resolve('/api/documents');
+ if (!resolved?.dispatch) throw new Error('no dispatch for /api/documents');
+ for (const url of ['/api/documents', '/api/documents?dir=linked.mdx']) {
+ const req = makeSyntheticReq({ url });
+ const { res, captured } = makeCaptureRes();
+ await resolved.dispatch(req, res);
+ expect(captured.status).toBe(200);
+ const rows = (
+ JSON.parse(captured.body) as { documents: Array<{ kind: string; path?: string }> }
+ ).documents;
+ expect
+ .soft(rows.filter((row) => row.kind === 'folder' && row.path === 'linked.mdx'))
+ .toEqual([
+ expect.objectContaining({
+ isSymlink: true,
+ canonicalDocName: 'real.md',
+ targetPath: 'real.md',
+ }),
+ ]);
+ }
+ expect(lstatSync(real).isDirectory()).toBe(true);
+ expect(lstatSync(linked).isSymbolicLink()).toBe(true);
+ expect(realpathSync(linked)).toBe(real);
+ expect(readFileSync(known, 'utf8')).toBe('known,bytes\n');
+ expect(readFileSync(created, 'utf8')).toBe('public,bytes\n');
+ } finally {
+ await watcher.unsubscribe();
+ expect(nativeSubscriptionOn(root).nativeReleases()).toBe(1);
+ }
+});
diff --git a/packages/server/src/http/document-routes.ts b/packages/server/src/http/document-routes.ts
index 08416f085..47ab4daa3 100644
--- a/packages/server/src/http/document-routes.ts
+++ b/packages/server/src/http/document-routes.ts
@@ -17,7 +17,12 @@ import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import type { ConflictAuthority } from '../conflict-authority.ts';
import type { ContentFilter } from '../content-filter.ts';
import { canonicalDocName, getDocExtension } from '../doc-extensions.ts';
-import type { FileIndexEntry, FolderIndexEntry } from '../file-watcher.ts';
+import {
+ type AllFileEntries,
+ type FileIndexEntry,
+ type FolderIndexEntry,
+ fileIndexEntryMembers,
+} from '../file-watcher.ts';
import type { PinoLogger } from '../logger.ts';
import { extractPageIcon, extractPageTitle } from '../page-identity.ts';
import { toPosix } from '../path-utils.ts';
@@ -52,6 +57,7 @@ export interface DocumentRouteDeps {
resolveDocPath: (docName: string) => string | null;
extractHeadings: (content: string) => HeadingEntry[];
getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ getFileIndexGeneration?: () => number;
log: PinoLogger;
ready: Promise<void> | undefined;
contentFilter: ContentFilter | undefined;
@@ -77,7 +83,7 @@ export interface DocumentRouteDeps {
signal: AbortSignal;
}) => Promise<{ truncated: boolean }>;
synthesizeShowAllAssetExt: (name: string) => string;
- getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ getAllFilesIndex: () => AllFileEntries;
getFolderIndex: (() => ReadonlyMap<string, FolderIndexEntry>) | undefined;
getFolderAliasIndex: (() => ReadonlyMap<string, string>) | undefined;
onReferencedAssetsCacheInvalidator: ((invalidate: () => void) => void) | undefined;
@@ -100,6 +106,7 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
resolveDocPath,
extractHeadings,
getFileIndex,
+ getFileIndexGeneration,
log,
ready,
contentFilter,
@@ -118,6 +125,7 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
let referencedAssetsCache: {
signature: string;
+ generation: number | undefined;
assets: ReturnType<typeof collectReferencedAssets>;
} | null = null;
@@ -413,11 +421,13 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
}
const index = getFileIndex();
- const allFiles = getAllFilesIndex();
+ const allFiles = [...getAllFilesIndex()];
const folderIndex = getFolderIndex?.() ?? new Map<string, FolderIndexEntry>();
+ const folderAliasIndex = getFolderAliasIndex?.() ?? new Map<string, string>();
const documents: DocumentListEntry[] = [];
for (const [folderPath, entry] of folderIndex) {
+ if (folderAliasIndex.has(folderPath)) continue;
if (dir && !folderPath.startsWith(`${dir}/`) && folderPath !== dir) continue;
documents.push({
kind: 'folder',
@@ -434,9 +444,16 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
let assets: ReturnType<typeof collectReferencedAssets> = [];
try {
const assetSignature = referencedAssetsSignature(index);
- if (referencedAssetsCache?.signature !== assetSignature) {
+ const assetGeneration = getFileIndexGeneration?.();
+ if (
+ !referencedAssetsCache ||
+ referencedAssetsCache.signature !== assetSignature ||
+ referencedAssetsCache.generation !== assetGeneration ||
+ referencedAssetsCache.assets.some((asset) => contentFilter?.isPathIgnored(asset.path))
+ ) {
referencedAssetsCache = {
signature: assetSignature,
+ generation: assetGeneration,
assets: collectReferencedAssets({
contentDir,
fileIndex: index,
@@ -479,24 +496,27 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
for (const [docName, entry] of allFiles) {
if (entry.kind === 'markdown') {
- if (dir && !docName.startsWith(`${dir}/`) && docName !== dir) continue;
-
const docExt = getDocExtension(docName);
- documents.push({
- kind: 'document',
- docName,
- docExt,
- size: entry.size,
- modified: entry.modified,
- isSymlink: false,
- canonicalDocName: null,
- targetPath: null,
- });
+ if (!dir || docName.startsWith(`${dir}/`) || docName === dir) {
+ documents.push({
+ kind: 'document',
+ docName,
+ docExt,
+ size: entry.size,
+ modified: entry.modified,
+ isSymlink: false,
+ canonicalDocName: null,
+ targetPath: null,
+ });
+ }
- for (const alias of entry.aliases) {
+ const listed = new Set([docName]);
+ for (const member of fileIndexEntryMembers(contentDir, docName, entry).members) {
+ if (member.role !== 'symlink' || listed.has(member.path)) continue;
+ listed.add(member.path);
+ const alias = member.path;
if (dir && !alias.startsWith(`${dir}/`) && alias !== dir) continue;
- const targetRelPath = toPosix(relative(contentDir, entry.canonicalPath));
documents.push({
kind: 'document',
docName: alias,
@@ -505,49 +525,34 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
modified: entry.modified,
isSymlink: true,
canonicalDocName: docName,
- targetPath: targetRelPath,
+ targetPath: member.targetPath,
});
}
continue;
}
- const passesDir = !dir || docName === dir || docName.startsWith(`${dir}/`);
- if (passesDir && !assetPaths.has(docName)) {
- const assetExt = synthesizeShowAllAssetExt(docName);
+ const addFile = (path: string, targetPath: string | null): void => {
+ if ((dir && path !== dir && !path.startsWith(`${dir}/`)) || assetPaths.has(path))
+ return;
+ const assetExt = synthesizeShowAllAssetExt(path);
documents.push({
kind: 'file',
- docName,
- path: docName,
+ docName: path,
+ path,
docExt: `.${assetExt}`,
assetExt,
size: entry.size,
modified: entry.modified,
- isSymlink: false,
- canonicalDocName: null,
- targetPath: null,
- });
- }
- for (const alias of entry.aliases) {
- const aliasPassesDir = !dir || alias === dir || alias.startsWith(`${dir}/`);
- if (!aliasPassesDir || assetPaths.has(alias)) continue;
- const targetRelPath = toPosix(relative(contentDir, entry.canonicalPath));
- const assetExt = synthesizeShowAllAssetExt(alias);
- documents.push({
- kind: 'file',
- docName: alias,
- path: alias,
- docExt: `.${assetExt}`,
- assetExt,
- size: entry.size,
- modified: entry.modified,
- isSymlink: true,
- canonicalDocName: docName,
- targetPath: targetRelPath,
+ isSymlink: targetPath !== null,
+ canonicalDocName: targetPath === null ? null : docName,
+ targetPath,
});
+ };
+ for (const member of fileIndexEntryMembers(contentDir, docName, entry).members) {
+ addFile(member.path, member.role === 'symlink' ? member.targetPath : null);
}
}
- const folderAliasIndex = getFolderAliasIndex?.() ?? new Map<string, string>();
if (folderAliasIndex.size > 0) {
const passesDirFilter = (p: string): boolean =>
!dir || p === dir || p.startsWith(`${dir}/`);
@@ -606,20 +611,26 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
});
}
for (const [docName, dEntry] of allFiles) {
- projectChild(docName, (aliasName) => {
- const targetRelPath = toPosix(relative(contentDir, dEntry.canonicalPath));
- if (dEntry.kind === 'markdown') {
- documents.push({
- kind: 'document',
- docName: aliasName,
- docExt: getDocExtension(docName),
- size: dEntry.size,
- modified: dEntry.modified,
- isSymlink: true,
- canonicalDocName: docName,
- targetPath: targetRelPath,
- });
- } else {
+ const { resolved, members } = fileIndexEntryMembers(contentDir, docName, dEntry);
+ const projected = resolved
+ ? members
+ : [...new Map(members.map((member) => [member.path, member])).values()];
+ for (const member of projected) {
+ projectChild(member.path, (aliasName) => {
+ if (dEntry.kind === 'markdown') {
+ documents.push({
+ kind: 'document',
+ docName: aliasName,
+ docExt: getDocExtension(docName),
+ size: dEntry.size,
+ modified: dEntry.modified,
+ isSymlink: true,
+ canonicalDocName: docName,
+ targetPath: member.targetPath,
+ });
+ return;
+ }
+ if (resolved && assetPaths.has(aliasName)) return;
const assetExt = synthesizeShowAllAssetExt(aliasName);
documents.push({
kind: 'file',
@@ -631,10 +642,10 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
modified: dEntry.modified,
isSymlink: true,
canonicalDocName: docName,
- targetPath: targetRelPath,
+ targetPath: member.targetPath,
});
- }
- });
+ });
+ }
}
}
diff --git a/packages/server/src/in-place-skills.ts b/packages/server/src/in-place-skills.ts
index 570cb0343..98270a093 100644
--- a/packages/server/src/in-place-skills.ts
+++ b/packages/server/src/in-place-skills.ts
@@ -26,8 +26,8 @@ import {
} from '@inkeep/open-knowledge-core/skills-catalog';
import { isInternalBundleSkillName, isUserGlobalBundleSkillName } from './skill-bundles.ts';
import {
+ observeSkillPlacementInputsForScan,
readKnownSkillPlacementRoots as readPlacementRoots,
- readSkillSourceHostPreferences as readSourceHostPrefs,
} from './skill-placements-store.ts';
function hostRoots(
@@ -67,6 +67,22 @@ interface ScanOccurrence extends LocatedSkillOccurrence {
readonly aliasRooted?: boolean;
}
+type SkillScanFailure =
+ | { readonly scope: 'scan'; readonly error: unknown }
+ | { readonly scope: 'ledger-parse'; readonly error: unknown }
+ | { readonly scope: 'bundle'; readonly dir: string; readonly error: unknown };
+
+interface SkillScanObservation {
+ readonly skills: InPlaceSkill[];
+ readonly occurrences: readonly ScanOccurrence[];
+ readonly failures: readonly SkillScanFailure[];
+}
+
+function isAbsentPath(error: unknown): boolean {
+ const code = (error as NodeJS.ErrnoException).code;
+ return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
export function scanHostRootAliases(base: string, scope: SkillScope): Record<string, string> {
const roots = knownSkillRootsFor(base, scope);
const out: Record<string, string> = {};
@@ -106,15 +122,17 @@ export function globalSkillGraphRoots(home: string): string[] {
export function knownSkillRootsFor(
base: string,
scope: SkillScope,
+): ReadonlyArray<{ editor: string; root: string }> {
+ return skillRootsWithCustom(scope, readPlacementRoots(base));
+}
+
+function skillRootsWithCustom(
+ scope: SkillScope,
+ customRoots: readonly string[],
): ReadonlyArray<{ editor: string; root: string }> {
const std = hostSkillRootsFor(scope);
const seen = new Set(std.map((r) => r.root));
- return [
- ...std,
- ...readPlacementRoots(base)
- .filter((r) => !seen.has(r))
- .map((r) => ({ editor: r, root: r })),
- ];
+ return [...std, ...customRoots.filter((r) => !seen.has(r)).map((r) => ({ editor: r, root: r }))];
}
export function standardSkillRoots(scope: SkillScope): ReadonlySet<string> {
@@ -204,6 +222,12 @@ export function skillHomeCandidateFolders(scope: SkillScope): string[] {
}
function bundleStamp(absDir: string): string | null {
+ try {
+ if (!statSync(join(absDir, 'SKILL.md')).isFile()) return null;
+ } catch (error) {
+ if (isAbsentPath(error)) return null;
+ throw error;
+ }
const parts: string[] = [];
const walk = (dir: string, rel: string): void => {
for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -216,11 +240,7 @@ function bundleStamp(absDir: string): string | null {
}
}
};
- try {
- walk(absDir, '');
- } catch {
- return null;
- }
+ walk(absDir, '');
return parts.sort().join('|');
}
@@ -250,34 +270,66 @@ function parseSkillDirCached(
return entry;
}
-function scanBase(base: string, scope: SkillScope): InPlaceSkill[] {
+function scanBase(base: string, scope: SkillScope): SkillScanObservation {
const occurrences: ScanOccurrence[] = [];
- const sourcePrefs = readSourceHostPrefs(base);
- const allRoots = knownSkillRootsFor(base, scope);
+ const failures: SkillScanFailure[] = [];
+ const recordFailure = (error: unknown): void => {
+ failures.push({ scope: 'scan', error });
+ };
+ let sourcePrefs: Record<string, string> = {};
+ let customRoots: string[] = [];
+ try {
+ const inputs = observeSkillPlacementInputsForScan(base);
+ sourcePrefs = inputs.sources;
+ customRoots = inputs.roots;
+ if (inputs.kind === 'incomplete') recordFailure(inputs.error);
+ if (inputs.kind === 'unparsable') failures.push({ scope: 'ledger-parse', error: inputs.error });
+ } catch (error) {
+ recordFailure(error);
+ }
+ const allRoots = skillRootsWithCustom(scope, customRoots);
let baseReal: string | null = null;
try {
baseReal = realpathSync(base);
- } catch {
- baseReal = null;
+ } catch (error) {
+ if (!isAbsentPath(error)) recordFailure(error);
}
for (const { editor, root } of allRoots) {
const absRoot = join(base, root);
let entries: string[];
let rootAliased = false;
try {
- if (!existsSync(absRoot)) continue;
+ const rootStat = statSync(absRoot);
+ if (!rootStat.isDirectory()) continue;
+ } catch (error) {
+ if (!isAbsentPath(error)) recordFailure(error);
+ continue;
+ }
+ try {
rootAliased = baseReal !== null && realpathSync(absRoot) !== join(baseReal, root);
entries = readdirSync(absRoot);
- } catch {
+ } catch (error) {
+ recordFailure(error);
continue;
}
for (const entry of entries) {
const absDir = join(absRoot, entry);
try {
if (!statSync(absDir).isDirectory()) continue;
- const parsed = parseSkillDirCached(absDir);
- if (!parsed) continue;
+ } catch (error) {
+ if (!isAbsentPath(error)) recordFailure(error);
+ continue;
+ }
+ let parsed: ReturnType<typeof parseSkillDirCached>;
+ try {
+ parsed = parseSkillDirCached(absDir);
+ } catch (error) {
+ failures.push({ scope: 'bundle', dir: `${root}/${entry}`, error });
+ continue;
+ }
+ if (!parsed) continue;
+ try {
occurrences.push({
name: entry,
scope,
@@ -291,13 +343,15 @@ function scanBase(base: string, scope: SkillScope): InPlaceSkill[] {
...(rootAliased ? { aliasRooted: true } : {}),
...(sourcePrefs[entry] === editor ? { preferredSource: true } : {}),
});
- } catch {}
+ } catch (error) {
+ recordFailure(error);
+ }
}
}
const { admittedDirs, canonicalDir } = buildSkillRegistry(occurrences);
const byNameDefaults = new Set(canonicalDir.values());
- return groupSkillsByIdentity(occurrences)
+ const skills = groupSkillsByIdentity(occurrences)
.filter((g) => admittedDirs.has(g.canonical.dir))
.filter((g) => byNameDefaults.has(g.canonical.dir) || !isInternalBundleSkillName(g.name))
.sort(
@@ -342,14 +396,19 @@ function scanBase(base: string, scope: SkillScope): InPlaceSkill[] {
...(g.canonical.pack !== undefined ? { pack: g.canonical.pack } : {}),
};
});
+ return { skills, occurrences, failures };
+}
+
+function projectInPlaceSkills(skills: readonly InPlaceSkill[]): InPlaceSkill[] {
+ return skills.filter((skill) => !isUserGlobalBundleSkillName(skill.name));
}
export function scanInPlaceSkills(contentDir: string): InPlaceSkill[] {
- return scanBase(contentDir, 'project').filter((s) => !isUserGlobalBundleSkillName(s.name));
+ return projectInPlaceSkills(scanBase(contentDir, 'project').skills);
}
export function scanGlobalInPlaceSkills(home: string): InPlaceSkill[] {
- return scanBase(home, 'global');
+ return scanBase(home, 'global').skills;
}
const USER_ROOTS_BY_PRECEDENCE = [...USER_SKILL_ROOTS].sort((a, b) => {
@@ -374,6 +433,54 @@ export function skillRootPathsFor(contentDir: string): ReadonlySet<string> {
return new Set(knownSkillRootsFor(contentDir, 'project').map((r) => r.root));
}
-export function scanInPlaceSkillDirs(contentDir: string): ReadonlySet<string> {
- return new Set(scanInPlaceSkills(contentDir).map((s) => s.dir));
+function skillNameOfDir(dir: string): string {
+ return dir.slice(dir.lastIndexOf('/') + 1);
+}
+
+function skillRootOfDir(dir: string): string {
+ return dir.slice(0, dir.lastIndexOf('/'));
+}
+
+function retainUndecidedAdmissions(
+ prior: ReadonlySet<string>,
+ observed: ReadonlySet<string>,
+ observation: SkillScanObservation,
+): ReadonlySet<string> {
+ const ledgerUnparsable = observation.failures.some((f) => f.scope === 'ledger-parse');
+ const failedBundles = new Set(
+ observation.failures.flatMap((f) => (f.scope === 'bundle' ? [f.dir] : [])),
+ );
+ const occurrenceDirs = new Set(observation.occurrences.map((o) => o.dir));
+ const occurrencesByName = new Map<string, number>();
+ for (const { name } of observation.occurrences) {
+ occurrencesByName.set(name, (occurrencesByName.get(name) ?? 0) + 1);
+ }
+ const standardRoots = standardSkillRoots('project');
+ const undecided = (dir: string): boolean =>
+ failedBundles.has(dir) ||
+ (ledgerUnparsable &&
+ (!standardRoots.has(skillRootOfDir(dir)) ||
+ (occurrenceDirs.has(dir) && (occurrencesByName.get(skillNameOfDir(dir)) ?? 0) >= 2)));
+ const retainedNames = new Set([...prior].filter(undecided).map(skillNameOfDir));
+ return new Set([
+ ...[...prior].filter(
+ (dir) =>
+ retainedNames.has(skillNameOfDir(dir)) && (undecided(dir) || occurrenceDirs.has(dir)),
+ ),
+ ...[...observed].filter((dir) => !retainedNames.has(skillNameOfDir(dir))),
+ ]);
+}
+
+export function scanInPlaceSkillDirs(
+ contentDir: string,
+ priorAdmission?: ReadonlySet<string>,
+): ReadonlySet<string> {
+ const observation = scanBase(contentDir, 'project');
+ const observed = new Set(projectInPlaceSkills(observation.skills).map((skill) => skill.dir));
+ const [firstFailure] = observation.failures;
+ if (firstFailure === undefined) return observed;
+ if (priorAdmission === undefined || observation.failures.some((f) => f.scope === 'scan')) {
+ throw firstFailure.error;
+ }
+ return retainUndecidedAdmissions(priorAdmission, observed, observation);
}
diff --git a/packages/server/src/local-target-inventory.test.ts b/packages/server/src/local-target-inventory.test.ts
index d49ce3a3a..8c54c0f37 100644
--- a/packages/server/src/local-target-inventory.test.ts
+++ b/packages/server/src/local-target-inventory.test.ts
@@ -1,6 +1,6 @@
import { join } from 'node:path';
import { describe, expect, test } from 'vitest';
-import type { FileIndexEntry } from './file-watcher.ts';
+import type { AllFileEntries, FileIndexEntry, FolderIndexEntry } from './file-watcher.ts';
import {
localTargetInventoryFromIndexes,
localTargetInventoryFromWatcher,
@@ -22,6 +22,53 @@ function entry(
}
describe('localTargetInventoryFromIndexes', () => {
+ test.each(['markdown-first', 'file-first'] as const)(
+ 'keeps same-name document and file targets separate with %s input',
+ (order) => {
+ const contentDir = '/project/content';
+ const document: readonly [string, FileIndexEntry] = [
+ 'canonical/real.csv',
+ entry('markdown', join(contentDir, 'canonical/real.csv.md'), ['document-link']),
+ ];
+ const file: readonly [string, FileIndexEntry] = [
+ 'canonical/real.csv',
+ entry('file', join(contentDir, 'canonical/real.csv'), ['asset-link.csv']),
+ ];
+ const allFiles: AllFileEntries =
+ order === 'markdown-first' ? [document, file] : [file, document];
+ const folderAliases = new Map([['mirror', 'canonical']]);
+ const folderIndex = new Map<string, FolderIndexEntry>([
+ [
+ 'canonical',
+ {
+ size: 0,
+ modified: '2026-01-01T00:00:00.000Z',
+ canonicalPath: join(contentDir, 'canonical'),
+ inode: 1,
+ },
+ ],
+ ]);
+
+ const inventory = localTargetInventoryFromIndexes(
+ allFiles,
+ folderAliases,
+ contentDir,
+ folderIndex,
+ );
+
+ expect(inventory.documentTargets.toSorted()).toEqual(
+ ['canonical/real.csv', 'document-link', 'mirror/real.csv'].toSorted(),
+ );
+ expect(inventory.fileTargets.toSorted()).toEqual(
+ ['asset-link.csv', 'canonical/real.csv', 'mirror/real.csv'].toSorted(),
+ );
+ expect(inventory.folderTargets.toSorted()).toEqual(['canonical', 'mirror']);
+ expect(
+ localTargetInventoryFromIndexes(allFiles, folderAliases, contentDir, folderIndex),
+ ).toEqual(inventory);
+ },
+ );
+
test('includes indexed, canonical, direct-alias, and folder-alias identities by kind', () => {
const contentDir = '/project/content';
const allFiles = new Map<string, FileIndexEntry>([
@@ -98,4 +145,67 @@ describe('localTargetInventoryFromIndexes', () => {
generation++;
expect(localTargetInventoryFromWatcher(watcher, contentDir)).not.toBe(first);
});
+
+ test('projects every regular member and actual symlink through folder aliases as generation changes', () => {
+ const contentDir = '/project/content';
+ const rich = {
+ ...entry('file', join(contentDir, 'outside/atlas.csv')),
+ aliases: ['linked-atlas.csv', 'linked-beacon.csv'],
+ fileMembers: {
+ regularPaths: ['outside/atlas.csv', 'canonical/beacon.csv'],
+ symlinks: [
+ { path: 'linked-atlas.csv', targetPath: 'outside/atlas.csv' },
+ { path: 'linked-beacon.csv', targetPath: 'canonical/beacon.csv' },
+ ],
+ },
+ };
+ const allFiles = new Map<string, FileIndexEntry>([['outside/atlas.csv', rich]]);
+ let generation = 1;
+ const watcher = {
+ getAllFilesIndex: () => allFiles,
+ getFileIndexGeneration: () => generation,
+ getFolderAliasIndex: () => new Map([['mirror', 'canonical']]),
+ };
+
+ const first = localTargetInventoryFromWatcher(watcher, contentDir);
+ expect
+ .soft(first?.fileTargets.toSorted())
+ .toEqual(
+ [
+ 'outside/atlas.csv',
+ 'canonical/beacon.csv',
+ 'mirror/beacon.csv',
+ 'linked-atlas.csv',
+ 'linked-beacon.csv',
+ ].toSorted(),
+ );
+ expect(localTargetInventoryFromWatcher(watcher, contentDir)).toBe(first);
+
+ const changedRich = {
+ ...rich,
+ fileMembers: {
+ ...rich.fileMembers,
+ regularPaths: ['outside/atlas.csv', 'canonical/beacon.csv', 'canonical/comet.csv'],
+ },
+ };
+ allFiles.set('outside/atlas.csv', changedRich);
+ expect(localTargetInventoryFromWatcher(watcher, contentDir)).toBe(first);
+ generation++;
+ const changed = localTargetInventoryFromWatcher(watcher, contentDir);
+ expect(changed).not.toBe(first);
+ expect
+ .soft(changed?.fileTargets.toSorted())
+ .toEqual(
+ [
+ 'outside/atlas.csv',
+ 'canonical/beacon.csv',
+ 'canonical/comet.csv',
+ 'mirror/beacon.csv',
+ 'mirror/comet.csv',
+ 'linked-atlas.csv',
+ 'linked-beacon.csv',
+ ].toSorted(),
+ );
+ expect(changed?.documentTargets).toEqual([]);
+ });
});
diff --git a/packages/server/src/local-target-inventory.ts b/packages/server/src/local-target-inventory.ts
index 3117e3807..93afb85c2 100644
--- a/packages/server/src/local-target-inventory.ts
+++ b/packages/server/src/local-target-inventory.ts
@@ -1,6 +1,11 @@
import { isAbsolute, relative } from 'node:path';
import { stripDocExtension } from './doc-extensions.ts';
-import type { FileIndexEntry, FolderIndexEntry, WatcherHandle } from './file-watcher.ts';
+import {
+ type AllFileEntries,
+ type FolderIndexEntry,
+ fileIndexEntryMembers,
+ type WatcherHandle,
+} from './file-watcher.ts';
import { toPosix } from './path-utils.ts';
export interface WatcherLocalTargetInventory {
@@ -75,7 +80,7 @@ export function localTargetInventoryFromWatcher(
}
export function localTargetInventoryFromIndexes(
- allFiles: ReadonlyMap<string, FileIndexEntry>,
+ allFiles: AllFileEntries,
folderAliases: ReadonlyMap<string, string>,
contentDir: string,
folderIndex?: ReadonlyMap<string, FolderIndexEntry>,
@@ -85,8 +90,9 @@ export function localTargetInventoryFromIndexes(
const folderTargets = new Set<string>(folderIndex?.keys() ?? []);
for (const [indexedIdentity, entry] of allFiles) {
const targets = entry.kind === 'markdown' ? documentTargets : fileTargets;
- targets.add(indexedIdentity);
- for (const alias of entry.aliases) targets.add(alias);
+ const { resolved, members } = fileIndexEntryMembers(contentDir, indexedIdentity, entry);
+ for (const member of members) targets.add(member.path);
+ if (resolved) continue;
const canonicalPath = canonicalRelativePath(contentDir, entry.canonicalPath);
if (canonicalPath) {
diff --git a/packages/server/src/parcel-drop-notice.test.ts b/packages/server/src/parcel-drop-notice.test.ts
new file mode 100644
index 000000000..b479bb9d1
--- /dev/null
+++ b/packages/server/src/parcel-drop-notice.test.ts
@@ -0,0 +1,11231 @@
+import { execFileSync } from 'node:child_process';
+import {
+ existsSync,
+ linkSync,
+ lstatSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ realpathSync,
+ renameSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ unlinkSync,
+ utimesSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import type { Event } from '@parcel/watcher';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import {
+ type ContentFilter,
+ type ContentFilterOptions,
+ createContentFilter,
+ createContentFilterAsync,
+} from './content-filter.ts';
+import { _resetDocExtensionsForTests, getDocExtension } from './doc-extensions.ts';
+import {
+ classifyEvents,
+ contentHash,
+ type DiskEvent,
+ getWatcherDecisionRingSnapshot,
+ handleRawEvents,
+ lastKnownHash,
+ reconcileFileIndexAfterFilterRebuild,
+ registerRemoval,
+ registerWrite,
+ removalTracker,
+ startWatcher,
+ updateFileIndex,
+ type WatcherHandle,
+ writeTracker,
+} from './file-watcher.ts';
+import { type HeadWatcherHandle, startHeadWatcher } from './head-watcher.ts';
+import {
+ scanGlobalInPlaceSkills,
+ scanInPlaceSkillDirs,
+ scanInPlaceSkills,
+ skillRootPathsFor,
+} from './in-place-skills.ts';
+import { localTargetInventoryFromWatcher } from './local-target-inventory.ts';
+import { getLogger } from './logger.ts';
+import {
+ forgetNativeSubscriptions,
+ nativeSubscriptionDirs,
+ nativeSubscriptionOn,
+} from './parcel-watcher-double.test-helper.ts';
+import { createServer, type ServerInstance } from './server-factory.ts';
+import { mutateSkillPlacementsStore, readSkillPlacementsStore } from './skill-placements-store.ts';
+
+vi.mock('@parcel/watcher', async () => {
+ const { parcelWatcherModule } = await import('./parcel-watcher-double.test-helper.ts');
+ return parcelWatcherModule;
+});
+
+const headBatchSchedule = vi.hoisted(() => ({
+ armed: false,
+ hold: null as Promise<void> | null,
+ begun: null as (() => void) | null,
+ ended: null as (() => void) | null,
+ begins: [] as unknown[],
+ ends: [] as unknown[],
+}));
+
+vi.mock('./head-watcher.ts', async (importOriginal) => {
+ const original = await importOriginal<typeof import('./head-watcher.ts')>();
+ const startHeadWatcher: typeof original.startHeadWatcher = (
+ projectRoot,
+ onBatchBegin,
+ onBatchEnd,
+ opts,
+ ) =>
+ headBatchSchedule.armed
+ ? original.startHeadWatcher(
+ projectRoot,
+ async (info) => {
+ try {
+ await onBatchBegin(info);
+ } finally {
+ headBatchSchedule.begins.push(info);
+ headBatchSchedule.begun?.();
+ }
+ await headBatchSchedule.hold;
+ },
+ async (info) => {
+ try {
+ await onBatchEnd(info);
+ } finally {
+ headBatchSchedule.ends.push(info);
+ headBatchSchedule.ended?.();
+ }
+ },
+ opts,
+ )
+ : original.startHeadWatcher(projectRoot, onBatchBegin, onBatchEnd, opts);
+ return { ...original, startHeadWatcher };
+});
+
+const deniedSkillRootRead = vi.hoisted(() => ({
+ path: null as string | null,
+ observed: false,
+ error: null as Error | null,
+}));
+const admissionFault = vi.hoisted(() => ({
+ operation: null as 'exists' | 'stat' | 'lstat' | 'realpath' | 'read' | 'readdir' | null,
+ path: null as string | null,
+ observed: false,
+ maskedAncestor: null as string | null,
+ descendantPath: null as string | null,
+ descendantShape: null as 'missing' | 'directory' | null,
+ descendantObserved: false,
+ descendantError: null as NodeJS.ErrnoException | null,
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+ const fs = await importOriginal<typeof import('node:fs')>();
+ const fail = (operation: Exclude<typeof admissionFault.operation, null>, path: unknown): void => {
+ if (admissionFault.operation !== operation || String(path) !== admissionFault.path) return;
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path });
+ };
+ return {
+ ...fs,
+ existsSync: ((...args: Parameters<typeof fs.existsSync>) => {
+ if (String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ return false;
+ }
+ fail('exists', args[0]);
+ return fs.existsSync(...args);
+ }) as typeof fs.existsSync,
+ statSync: ((...args: Parameters<typeof fs.statSync>) => {
+ fail('stat', args[0]);
+ if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
+ }
+ return fs.statSync(...args);
+ }) as typeof fs.statSync,
+ lstatSync: ((...args: Parameters<typeof fs.lstatSync>) => {
+ fail('lstat', args[0]);
+ if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
+ }
+ return fs.lstatSync(...args);
+ }) as typeof fs.lstatSync,
+ realpathSync: ((...args: Parameters<typeof fs.realpathSync>) => {
+ fail('realpath', args[0]);
+ if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
+ }
+ return fs.realpathSync(...args);
+ }) as typeof fs.realpathSync,
+ readFileSync: ((...args: Parameters<typeof fs.readFileSync>) => {
+ fail('read', args[0]);
+ if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
+ }
+ if (String(args[0]) === admissionFault.descendantPath && !admissionFault.descendantObserved) {
+ admissionFault.descendantObserved = true;
+ fs.unlinkSync(String(args[0]));
+ if (admissionFault.descendantShape === 'directory') fs.mkdirSync(String(args[0]));
+ }
+ try {
+ return fs.readFileSync(...args);
+ } catch (error) {
+ if (String(args[0]) === admissionFault.descendantPath) {
+ admissionFault.descendantError = error as NodeJS.ErrnoException;
+ }
+ throw error;
+ }
+ }) as typeof fs.readFileSync,
+ readdirSync: ((...args: Parameters<typeof fs.readdirSync>) => {
+ fail('readdir', args[0]);
+ if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
+ }
+ if (String(args[0]) === deniedSkillRootRead.path) {
+ deniedSkillRootRead.observed = true;
+ throw (
+ deniedSkillRootRead.error ??
+ Object.assign(new Error('directory read denied'), { code: 'EACCES' })
+ );
+ }
+ return fs.readdirSync(...args);
+ }) as typeof fs.readdirSync,
+ };
+});
+
+const deniedDirectoryRead = vi.hoisted(() => ({ path: null as string | null }));
+const deviceContrast = vi.hoisted(() => ({
+ path: null as string | null,
+ device: null as number | null,
+ inode: null as number | null,
+ observed: false,
+}));
+const memberStatSchedule = vi.hoisted(() => ({
+ path: null as string | null,
+ entered: null as (() => void) | null,
+ resume: null as Promise<void> | null,
+ seen: [] as string[],
+}));
+const scanSchedule = vi.hoisted(() => ({
+ holdPath: null as string | null,
+ entered: null as (() => void) | null,
+ resume: null as Promise<void> | null,
+ firstEntry: null as string | null,
+ orderedEntries: null as readonly string[] | null,
+ orderedPath: null as string | null,
+}));
+const classificationReadSchedule = vi.hoisted(() => ({
+ path: null as string | null,
+ holdRead: 0,
+ seen: [] as string[],
+ captured: null as string | null,
+ entered: null as (() => void) | null,
+ resume: null as Promise<void> | null,
+}));
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+ const fs = await importOriginal<typeof import('node:fs/promises')>();
+ return {
+ ...fs,
+ lstat: (async (...args: Parameters<typeof fs.lstat>) => {
+ const result = await fs.lstat(...args);
+ memberStatSchedule.seen.push(String(args[0]));
+ if (String(args[0]) === memberStatSchedule.path) {
+ memberStatSchedule.path = null;
+ memberStatSchedule.entered?.();
+ await memberStatSchedule.resume;
+ }
+ if (String(args[0]) !== deviceContrast.path) return result;
+ deviceContrast.observed = true;
+ if (deviceContrast.device === null || deviceContrast.inode === null) return result;
+ return Object.assign(result, { dev: deviceContrast.device, ino: deviceContrast.inode });
+ }) as typeof fs.lstat,
+ readFile: (async (...args: Parameters<typeof fs.readFile>) => {
+ const content = await fs.readFile(...args);
+ if (String(args[0]) === classificationReadSchedule.path && typeof content === 'string') {
+ classificationReadSchedule.seen.push(content);
+ if (classificationReadSchedule.seen.length === classificationReadSchedule.holdRead) {
+ classificationReadSchedule.captured = content;
+ classificationReadSchedule.entered?.();
+ await classificationReadSchedule.resume;
+ }
+ }
+ return content;
+ }) as typeof fs.readFile,
+ readdir: (async (...args: Parameters<typeof fs.readdir>) => {
+ if (String(args[0]) === deniedDirectoryRead.path) {
+ deniedDirectoryRead.path = null;
+ return Promise.reject(
+ Object.assign(new Error('directory read denied'), { code: 'EACCES' }),
+ );
+ }
+ const entries = await fs.readdir(...args);
+ if (String(args[0]) === scanSchedule.orderedPath) {
+ entries.sort((left, right) => {
+ const leftName = typeof left === 'string' ? left : left.name;
+ const rightName = typeof right === 'string' ? right : right.name;
+ if (scanSchedule.orderedEntries) {
+ const leftIndex = scanSchedule.orderedEntries.indexOf(leftName);
+ const rightIndex = scanSchedule.orderedEntries.indexOf(rightName);
+ if (leftIndex !== -1 || rightIndex !== -1) {
+ if (leftIndex === -1) return 1;
+ if (rightIndex === -1) return -1;
+ return leftIndex - rightIndex;
+ }
+ }
+ return (
+ Number(rightName === scanSchedule.firstEntry) -
+ Number(leftName === scanSchedule.firstEntry)
+ );
+ });
+ }
+ if (String(args[0]) === scanSchedule.holdPath) {
+ scanSchedule.holdPath = null;
+ scanSchedule.entered?.();
+ await scanSchedule.resume;
+ }
+ return entries;
+ }) as typeof fs.readdir,
+ };
+});
+
+const notices = [
+ 'Events were dropped by the FSEvents client. File system must be re-scanned.',
+ 'Too many events. File system must be re-scanned.',
+ 'Events were dropped by the kernel. File system must be re-scanned.',
+];
+
+const oldOid = '1'.repeat(40);
+const newOid = '2'.repeat(40);
+const handles: Array<WatcherHandle | HeadWatcherHandle> = [];
+const cleanupDirs: string[] = [];
+const releaseLatches: Array<() => void> = [];
+let contentDir: string;
+
+beforeEach(() => {
+ headBatchSchedule.armed = false;
+ headBatchSchedule.hold = null;
+ headBatchSchedule.begun = null;
+ headBatchSchedule.ended = null;
+ headBatchSchedule.begins = [];
+ headBatchSchedule.ends = [];
+ scanSchedule.holdPath = null;
+ scanSchedule.entered = null;
+ scanSchedule.resume = null;
+ scanSchedule.firstEntry = null;
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ classificationReadSchedule.path = null;
+ classificationReadSchedule.holdRead = 0;
+ classificationReadSchedule.seen = [];
+ classificationReadSchedule.captured = null;
+ classificationReadSchedule.entered = null;
+ classificationReadSchedule.resume = null;
+ admissionFault.operation = null;
+ admissionFault.path = null;
+ admissionFault.observed = false;
+ admissionFault.maskedAncestor = null;
+ admissionFault.descendantPath = null;
+ admissionFault.descendantShape = null;
+ admissionFault.descendantObserved = false;
+ admissionFault.descendantError = null;
+ deniedSkillRootRead.path = null;
+ deniedSkillRootRead.observed = false;
+ deniedSkillRootRead.error = null;
+ deniedDirectoryRead.path = null;
+ deviceContrast.path = null;
+ deviceContrast.device = null;
+ deviceContrast.inode = null;
+ deviceContrast.observed = false;
+ memberStatSchedule.path = null;
+ memberStatSchedule.entered = null;
+ memberStatSchedule.resume = null;
+ memberStatSchedule.seen = [];
+ forgetNativeSubscriptions();
+ _resetDocExtensionsForTests();
+ lastKnownHash.clear();
+ writeTracker.clear();
+ removalTracker.clear();
+ contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-parcel-notice-')));
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+});
+
+afterEach(async () => {
+ headBatchSchedule.armed = false;
+ headBatchSchedule.hold = null;
+ headBatchSchedule.begun = null;
+ headBatchSchedule.ended = null;
+ admissionFault.operation = null;
+ admissionFault.path = null;
+ admissionFault.maskedAncestor = null;
+ admissionFault.descendantPath = null;
+ admissionFault.descendantShape = null;
+ admissionFault.descendantError = null;
+ deniedSkillRootRead.path = null;
+ deniedSkillRootRead.error = null;
+ deniedDirectoryRead.path = null;
+ deviceContrast.path = null;
+ deviceContrast.device = null;
+ deviceContrast.inode = null;
+ memberStatSchedule.path = null;
+ memberStatSchedule.entered = null;
+ memberStatSchedule.resume = null;
+ memberStatSchedule.seen = [];
+ for (const release of releaseLatches.splice(0)) release();
+ for (const handle of handles.splice(0)) await handle.unsubscribe();
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ rmSync(contentDir, { recursive: true, force: true });
+ for (const path of cleanupDirs.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+async function deliver(dir: string, events: Event[], error: Error | null = null): Promise<void> {
+ await nativeSubscriptionOn(dir).deliver(events, error);
+ await vi.runAllTimersAsync();
+}
+
+async function watchContent(
+ filter?: ContentFilter,
+ onEvent?: (event: DiskEvent) => Promise<void>,
+): Promise<{
+ watcher: WatcherHandle;
+ events: DiskEvent[];
+ rawBatches: string[][];
+}> {
+ const events: DiskEvent[] = [];
+ const rawBatches: string[][] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ await onEvent?.(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRawBatch: (paths) => {
+ rawBatches.push([...paths]);
+ },
+ },
+ );
+ handles.push(watcher);
+ return { watcher, events, rawBatches };
+}
+
+function deferred(): { promise: Promise<void>; release: () => void } {
+ let release!: () => void;
+ const promise = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ releaseLatches.push(release);
+ return { promise, release };
+}
+
+async function deliverNotice(dir: string, events: Event[] = []): Promise<void> {
+ await deliver(dir, events, new Error(notices[0]));
+}
+
+function writeDoc(name: string, content: string): string {
+ const path = join(contentDir, name);
+ writeFileSync(path, content);
+ return path;
+}
+
+function writeSkillFixture(relativeDir: string, body = '# Fixture\n'): string {
+ const path = join(contentDir, relativeDir, 'SKILL.md');
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(
+ path,
+ `---\nname: ${relativeDir.split('/').at(-1)}\ndescription: Fixture\n---\n\n${body}`,
+ );
+ return path;
+}
+
+function dynamicSkillFilter(): ContentFilter {
+ return createContentFilter({
+ projectDir: contentDir,
+ contentDir,
+ inPlaceSkillDirs: scanInPlaceSkillDirs(contentDir),
+ rescanInPlaceSkillDirs: () => scanInPlaceSkillDirs(contentDir),
+ skillRootPaths: skillRootPathsFor(contentDir),
+ });
+}
+
+function writeSkillLedger(value: unknown): string {
+ const path = join(contentDir, '.ok', 'local', 'skill-placements.json');
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, typeof value === 'string' ? value : JSON.stringify(value));
+ return path;
+}
+
+function denyAdmission(
+ operation: Exclude<typeof admissionFault.operation, null>,
+ path: string,
+): void {
+ admissionFault.operation = operation;
+ admissionFault.path = path;
+ admissionFault.observed = false;
+}
+
+function clearAdmissionDenial(): void {
+ admissionFault.operation = null;
+ admissionFault.path = null;
+ admissionFault.maskedAncestor = null;
+}
+
+function createGitDir(): string {
+ const gitDir = join(contentDir, '.git');
+ mkdirSync(join(gitDir, 'refs', 'heads'), { recursive: true });
+ writeFileSync(join(gitDir, 'HEAD'), 'ref: refs/heads/main\n');
+ writeFileSync(join(gitDir, 'refs', 'heads', 'main'), `${oldOid}\n`);
+ writeFileSync(join(gitDir, 'refs', 'heads', 'feature'), `${newOid}\n`);
+ return gitDir;
+}
+
+async function watchHead(
+ onBegin?: Parameters<typeof startHeadWatcher>[1],
+ onEnd?: Parameters<typeof startHeadWatcher>[2],
+): Promise<{
+ watcher: HeadWatcherHandle;
+ begins: unknown[];
+ ends: unknown[];
+}> {
+ const begins: unknown[] = [];
+ const ends: unknown[] = [];
+ const watcher = await startHeadWatcher(
+ contentDir,
+ async (info) => {
+ begins.push(info);
+ await onBegin?.(info);
+ },
+ async (info) => {
+ ends.push(info);
+ await onEnd?.(info);
+ },
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getLastKnownBranch()).toBe('main');
+ return { watcher, begins, ends };
+}
+
+function expectHeadSettled(watched: {
+ watcher: HeadWatcherHandle;
+ begins: unknown[];
+ ends: unknown[];
+}): void {
+ expect(watched.begins).toHaveLength(1);
+ expect(watched.ends).toEqual([
+ {
+ headMoved: true,
+ oldHead: oldOid,
+ newHead: newOid,
+ timeout: false,
+ batchKind: 'cross-branch',
+ oldBranch: 'main',
+ newBranch: 'feature',
+ },
+ ]);
+ expect(watched.watcher.getLastKnownBranch()).toBe('feature');
+}
+
+test('a regular content batch still reaches the disk watcher', async () => {
+ const { watcher, events, rawBatches } = await watchContent();
+ const path = writeDoc('announced.md', '# Announced\n');
+ await deliver(contentDir, [{ type: 'create', path }]);
+
+ expect(events).toContainEqual({
+ kind: 'create',
+ path,
+ docName: 'announced',
+ content: '# Announced\n',
+ });
+ expect(watcher.getFileIndex().has('announced')).toBe(true);
+ expect(rawBatches).toContainEqual([path]);
+});
+
+test.each(notices)(
+ 'content notice processes its batch and restores missing disk changes: %s',
+ async (notice) => {
+ const changed = writeDoc('changed.md', '# Before\n');
+ const removed = writeDoc('removed.md', '# Removed\n');
+ const { watcher, events, rawBatches } = await watchContent();
+ expect([...watcher.getFileIndex().keys()].sort()).toEqual(['changed', 'removed']);
+
+ const announced = writeDoc('announced.md', '# Announced\n');
+ const hidden = writeDoc('hidden.md', '# Hidden\n');
+ writeFileSync(changed, '# After\n');
+ unlinkSync(removed);
+ await deliver(contentDir, [{ type: 'create', path: announced }], new Error(notice));
+
+ expect.soft(rawBatches).toContainEqual([announced]);
+ expect.soft(events).toContainEqual({
+ kind: 'create',
+ path: announced,
+ docName: 'announced',
+ content: '# Announced\n',
+ });
+ expect.soft(events).toContainEqual({
+ kind: 'create',
+ path: hidden,
+ docName: 'hidden',
+ content: '# Hidden\n',
+ });
+ expect.soft(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: changed,
+ docName: 'changed',
+ content: '# After\n',
+ }),
+ );
+ expect.soft(events).toContainEqual({ kind: 'delete', path: removed, docName: 'removed' });
+ expect([...watcher.getFileIndex().keys()].sort()).toEqual(['announced', 'changed', 'hidden']);
+ },
+);
+
+test.each(notices)('empty content notice restores an omitted disk change: %s', async (notice) => {
+ const { watcher, events } = await watchContent();
+ const hidden = writeDoc('hidden.md', '# Hidden\n');
+ await deliver(contentDir, [], new Error(notice));
+
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: hidden,
+ docName: 'hidden',
+ content: '# Hidden\n',
+ });
+ expect(watcher.getFileIndex().has('hidden')).toBe(true);
+});
+
+test('a regular HEAD batch settles the disk branch', async () => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ const path = join(gitDir, 'HEAD');
+ writeFileSync(path, 'ref: refs/heads/feature\n');
+ await deliver(gitDir, [{ type: 'update', path }]);
+
+ expectHeadSettled(watched);
+ expect(watched.begins).toEqual([{ trigger: 'HEAD' }]);
+});
+
+test('a rejected HEAD unsubscribe still ends the open batch and clears its timers', async () => {
+ const gitDir = createGitDir();
+ const ends: unknown[] = [];
+ const failure = new Error('native unsubscribe failed');
+ let dispatchHead: ((rawPath: string) => void) | undefined;
+ const watcher = await startHeadWatcher(
+ contentDir,
+ async () => {},
+ async (info) => {
+ ends.push(info);
+ },
+ {
+ subscribeForTest: async (_gitDir, dispatch) => {
+ dispatchHead = dispatch;
+ return async () => {
+ throw failure;
+ };
+ },
+ },
+ );
+ if (!dispatchHead) throw new Error('HEAD dispatch was not registered');
+ dispatchHead(join(gitDir, 'HEAD'));
+ await vi.advanceTimersByTimeAsync(1);
+ expect(ends).toEqual([]);
+ expect(vi.getTimerCount()).toBe(2);
+
+ await expect(watcher.unsubscribe()).rejects.toBe(failure);
+
+ expect(ends).toEqual([
+ {
+ headMoved: false,
+ oldHead: oldOid,
+ newHead: oldOid,
+ timeout: false,
+ batchKind: 'within-branch',
+ oldBranch: 'main',
+ newBranch: 'main',
+ },
+ ]);
+ expect(vi.getTimerCount()).toBe(0);
+});
+
+test.each(notices)('HEAD notice processes its delivered HEAD event: %s', async (notice) => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ const path = join(gitDir, 'HEAD');
+ writeFileSync(path, 'ref: refs/heads/feature\n');
+ await deliver(gitDir, [{ type: 'update', path }], new Error(notice));
+
+ expectHeadSettled(watched);
+ expect(watched.begins).toEqual([{ trigger: 'HEAD' }]);
+});
+
+test.each(notices)(
+ 'HEAD notice restores a branch change omitted from a nonempty batch: %s',
+ async (notice) => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ writeFileSync(join(gitDir, 'HEAD'), 'ref: refs/heads/feature\n');
+ const configPath = join(gitDir, 'config');
+ writeFileSync(configPath, '[core]\n');
+ await deliver(gitDir, [{ type: 'update', path: configPath }], new Error(notice));
+
+ expectHeadSettled(watched);
+ },
+);
+
+test.each(notices)('empty HEAD notice restores an omitted branch change: %s', async (notice) => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ writeFileSync(join(gitDir, 'HEAD'), 'ref: refs/heads/feature\n');
+ await deliver(gitDir, [], new Error(notice));
+
+ expectHeadSettled(watched);
+});
+
+test('fatal Parcel errors remain observable for both watchers', async () => {
+ const diagnostics: Array<{ name: string; err: unknown }> = [];
+ for (const name of ['file-watcher', 'head-watcher']) {
+ const logger = getLogger(name);
+ for (const method of ['error', 'warn'] as const) {
+ vi.spyOn(logger, method).mockImplementation((data) => {
+ diagnostics.push({ name, err: data.err });
+ });
+ }
+ }
+
+ const { watcher, events, rawBatches } = await watchContent();
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ const announced = writeDoc('announced.md', '# Announced\n');
+ writeDoc('hidden.md', '# Hidden\n');
+ const headPath = join(gitDir, 'HEAD');
+ writeFileSync(headPath, 'ref: refs/heads/feature\n');
+ const fatal = new Error('Failed to read changes');
+ await deliver(contentDir, [{ type: 'create', path: announced }], fatal);
+ await deliver(gitDir, [{ type: 'update', path: headPath }], fatal);
+
+ for (const name of ['file-watcher', 'head-watcher']) {
+ expect(diagnostics).toContainEqual({ name, err: fatal });
+ }
+ expect(events).toEqual([]);
+ expect(rawBatches).toEqual([]);
+ expect([...watcher.getFileIndex().keys()]).toEqual([]);
+ expect(watched.begins).toEqual([]);
+ expect(watched.ends).toEqual([]);
+ expect(watched.watcher.getLastKnownBranch()).toBe('main');
+});
+
+test('repeated content notices do not repeat effects already applied from a supplied batch and disk scan', async () => {
+ const { watcher, events, rawBatches } = await watchContent();
+ const announced = writeDoc('announced.md', '# Announced\n');
+ writeDoc('hidden.md', '# Hidden\n');
+ const general = join(contentDir, 'data.csv');
+ writeFileSync(general, 'a,b\n');
+ const emptyFolder = join(contentDir, 'empty-folder');
+ mkdirSync(emptyFolder);
+
+ await deliverNotice(contentDir, [{ type: 'create', path: announced }]);
+ expect
+ .soft(events.filter((event) => event.kind === 'create' && event.docName === 'announced'))
+ .toHaveLength(1);
+ expect
+ .soft(events.filter((event) => event.kind === 'create' && event.docName === 'hidden'))
+ .toHaveLength(1);
+ expect.soft(rawBatches).toContainEqual([announced]);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: general, relativePath: 'data.csv' }),
+ );
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'folder-create', path: emptyFolder, relativePath: 'empty-folder' });
+ expect.soft(indexedRow(watcher, 'data.csv', 'file')?.kind).toBe('file');
+ expect.soft(watcher.getFolderIndex().has('empty-folder')).toBe(true);
+
+ const settledEvents = [...events];
+ const settledIndex = [...watcher.getFileIndex().keys()].sort();
+ await deliverNotice(contentDir);
+
+ expect(events).toEqual(settledEvents);
+ expect([...watcher.getFileIndex().keys()].sort()).toEqual(settledIndex);
+ expect(watcher.getFileIndex().has('hidden')).toBe(true);
+ expect(Boolean(indexedRow(watcher, 'data.csv', 'file'))).toBe(true);
+ expect(watcher.getFolderIndex().has('empty-folder')).toBe(true);
+});
+
+test('a notice recovers an omitted rename through the established rename event', async () => {
+ const oldPath = writeDoc('old-name.md', '# Same Content\n');
+ const { watcher, events } = await watchContent();
+ const newPath = join(contentDir, 'new-name.md');
+ renameSync(oldPath, newPath);
+
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual({
+ kind: 'rename',
+ oldPath,
+ newPath,
+ oldDocName: 'old-name',
+ newDocName: 'new-name',
+ content: '# Same Content\n',
+ });
+ expect([...watcher.getFileIndex().keys()]).toEqual(['new-name']);
+});
+
+test('a notice recovers conflict-marked bytes as a conflict event', async () => {
+ const path = writeDoc('conflicted.md', '# Before\n');
+ const { watcher, events } = await watchContent();
+ const conflict = '<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n';
+ writeFileSync(path, conflict);
+
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual({
+ kind: 'conflict',
+ path,
+ docName: 'conflicted',
+ content: conflict,
+ });
+ expect(events.some((event) => event.kind === 'update' && event.docName === 'conflicted')).toBe(
+ false,
+ );
+ expect(watcher.getFileIndex().has('conflicted')).toBe(true);
+});
+
+test('notice recovery keeps self-write and self-removal suppression while applying an external sibling', async () => {
+ const ownPath = writeDoc('own.md', '# Before\n');
+ const removedPath = writeDoc('removed.md', '# Removed\n');
+ const { watcher, events } = await watchContent();
+ const ownContent = '# After\n';
+ writeFileSync(ownPath, ownContent);
+ registerWrite(ownPath, contentHash(ownContent));
+ registerRemoval(removedPath);
+ unlinkSync(removedPath);
+ const externalPath = writeDoc('external.md', '# External\n');
+
+ await deliverNotice(contentDir);
+
+ expect.soft(events).toContainEqual({
+ kind: 'create',
+ path: externalPath,
+ docName: 'external',
+ content: '# External\n',
+ });
+ expect(
+ events.some((event) => 'docName' in event && ['own', 'removed'].includes(event.docName)),
+ ).toBe(false);
+ expect(watcher.getFileIndex().get('own')?.title).toBe('After');
+ expect(watcher.getFileIndex().has('removed')).toBe(false);
+ expect(lastKnownHash.get(ownPath)).toBe(contentHash(ownContent));
+ expect(lastKnownHash.has(removedPath)).toBe(false);
+});
+
+test('notice recovery respects markdown, general-file and directory filters while admitting a sibling asset', async () => {
+ writeFileSync(join(contentDir, '.okignore'), 'ignored.md\nignored.csv\ndist/\n');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ const { watcher, events } = await watchContent(filter);
+ const freshDir = join(contentDir, 'fresh');
+ mkdirSync(freshDir);
+ const notePath = join(freshDir, 'note.md');
+ const assetPath = join(freshDir, 'pic.png');
+ writeFileSync(notePath, '# Note\n');
+ writeFileSync(assetPath, 'fake-png-bytes');
+ writeDoc('ignored.md', '# Ignored\n');
+ writeFileSync(join(contentDir, 'ignored.csv'), 'ignore,me\n');
+ mkdirSync(join(contentDir, 'dist'));
+ writeFileSync(join(contentDir, 'dist', 'hidden.md'), '# Hidden\n');
+
+ await deliverNotice(contentDir);
+
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'create', path: notePath, docName: 'fresh/note', content: '# Note\n' });
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'asset-create', path: assetPath, relativePath: 'fresh/pic.png' });
+ expect(watcher.getFileIndex().has('fresh/note')).toBe(true);
+ expect(Boolean(indexedRow(watcher, 'fresh/pic.png', 'file'))).toBe(true);
+ expect(watcher.getFileIndex().has('ignored')).toBe(false);
+ expect(Boolean(indexedRow(watcher, 'ignored.csv', 'file'))).toBe(false);
+ expect(watcher.getFolderIndex().has('dist')).toBe(false);
+ expect(watcher.getFileIndex().has('dist/hidden')).toBe(false);
+ expect(
+ events.some(
+ (event) =>
+ 'path' in event && (event.path.includes('ignored') || event.path.includes('/dist/')),
+ ),
+ ).toBe(false);
+ const noteIndex = events.findIndex(
+ (event) => event.kind === 'create' && event.docName === 'fresh/note',
+ );
+ const assetIndex = events.findIndex(
+ (event) => event.kind === 'asset-create' && event.relativePath === 'fresh/pic.png',
+ );
+ expect(noteIndex).toBeLessThan(assetIndex);
+ expect(filter.isExcluded('fresh/pic.png')).toBe(false);
+});
+
+test('notice recovery without a filter still admits ordinary markdown and general files', async () => {
+ const { watcher, events } = await watchContent();
+ const regular = writeDoc('regular.md', '# Regular\n');
+ await deliver(contentDir, [{ type: 'create', path: regular }]);
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: regular,
+ docName: 'regular',
+ content: '# Regular\n',
+ });
+
+ const general = join(contentDir, 'ordinary.csv');
+ writeFileSync(general, 'a,b\n');
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: general, relativePath: 'ordinary.csv' }),
+ );
+ expect(indexedRow(watcher, 'ordinary.csv', 'file')?.kind).toBe('file');
+});
+
+test('notice recovery refreshes in-place bundle admission and notifies raw observers of unchanged and removed paths', async () => {
+ const filter = createContentFilter({
+ projectDir: contentDir,
+ contentDir,
+ inPlaceSkillDirs: scanInPlaceSkillDirs(contentDir),
+ rescanInPlaceSkillDirs: () => scanInPlaceSkillDirs(contentDir),
+ skillRootPaths: skillRootPathsFor(contentDir),
+ });
+ const { watcher, events, rawBatches } = await watchContent(filter);
+ const bundleDir = join(contentDir, '.claude', 'skills', 'fresh-fixture');
+ mkdirSync(bundleDir, { recursive: true });
+ const skillPath = join(bundleDir, 'SKILL.md');
+ const skillContent = '---\nname: fresh-fixture\ndescription: fixture\n---\n\n# Fresh fixture\n';
+ writeFileSync(skillPath, skillContent);
+ const hostPath = join(contentDir, '.claude', 'plugins', 'settings.md');
+ mkdirSync(join(contentDir, '.claude', 'plugins'), { recursive: true });
+ writeFileSync(hostPath, '# Host settings\n');
+ expect(filter.isExcluded('.claude/skills/fresh-fixture/SKILL.md')).toBe(true);
+
+ await deliverNotice(contentDir);
+
+ expect.soft(events).toContainEqual({
+ kind: 'create',
+ path: skillPath,
+ docName: '.claude/skills/fresh-fixture/SKILL',
+ content: skillContent,
+ });
+ expect.soft(watcher.getFileIndex().has('.claude/skills/fresh-fixture/SKILL')).toBe(true);
+ expect.soft(rawBatches[0]).toEqual([]);
+ expect.soft(rawBatches.slice(1).some((paths) => paths.includes(skillPath))).toBe(true);
+ expect(watcher.getFileIndex().has('.claude/plugins/settings')).toBe(false);
+ expect(filter.isExcluded('.claude/plugins/settings.md')).toBe(true);
+
+ const settledEvents = [...events];
+ const beforeUnchanged = rawBatches.length;
+ await deliverNotice(contentDir);
+ expect(events).toEqual(settledEvents);
+ expect
+ .soft(rawBatches.slice(beforeUnchanged).some((paths) => paths.includes(skillPath)))
+ .toBe(true);
+
+ rmSync(bundleDir, { recursive: true, force: true });
+ const beforeRemoval = rawBatches.length;
+ await deliverNotice(contentDir);
+ expect.soft(watcher.getFileIndex().has('.claude/skills/fresh-fixture/SKILL')).toBe(false);
+ expect.soft(watcher.getFolderIndex().has('.claude/skills/fresh-fixture')).toBe(false);
+ expect(rawBatches.slice(beforeRemoval).some((paths) => paths.includes(skillPath))).toBe(true);
+ expect(watcher.getFileIndex().has('.claude/plugins/settings')).toBe(false);
+});
+
+test.each([
+ { factory: 'sync', surface: 'notice' },
+ { factory: 'sync', surface: 'normal rebuild' },
+ { factory: 'async', surface: 'notice' },
+ { factory: 'async', surface: 'normal rebuild' },
+] as const)(
+ '$factory admission keeps a known skill when its root cannot be read during $surface',
+ async ({ factory, surface }) => {
+ const skillDir = '.claude/skills/fixture';
+ const docName = `${skillDir}/SKILL`;
+ const skillPath = join(contentDir, skillDir, 'SKILL.md');
+ const skillRoot = join(contentDir, '.claude', 'skills');
+ const before = '---\nname: fixture\ndescription: Fixture\n---\n\n# Before\n';
+ const after = '---\nname: fixture\ndescription: Fixture\n---\n\n# After\n';
+ mkdirSync(join(contentDir, skillDir), { recursive: true });
+ writeFileSync(skillPath, before);
+
+ const options: ContentFilterOptions = {
+ projectDir: contentDir,
+ contentDir,
+ inPlaceSkillDirs: scanInPlaceSkillDirs(contentDir),
+ rescanInPlaceSkillDirs: () => scanInPlaceSkillDirs(contentDir),
+ skillRootPaths: skillRootPathsFor(contentDir),
+ };
+ const filter =
+ factory === 'sync' ? createContentFilter(options) : await createContentFilterAsync(options);
+ const { watcher, events } = await watchContent(filter);
+ const knownFolders = ['.claude', '.claude/skills', skillDir];
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(watcher.getFileIndex().has(docName)).toBe(true);
+ for (const folder of knownFolders) expect(watcher.getFolderIndex().has(folder)).toBe(true);
+
+ const warningErrors: unknown[] = [];
+ const logger = getLogger('content-filter');
+ const originalWarn = logger.warn.bind(logger);
+ vi.spyOn(logger, 'warn').mockImplementation((data, message) => {
+ warningErrors.push(data.err);
+ originalWarn(data, message);
+ });
+ const priorFingerprint = filter.inPlaceSkillDirsFingerprint();
+ const failure = Object.assign(new Error('skill root read denied'), { code: 'EACCES' });
+ deniedSkillRootRead.path = skillRoot;
+ deniedSkillRootRead.observed = false;
+ deniedSkillRootRead.error = failure;
+ try {
+ expect.soft(filter.peekFreshInPlaceSkillDirsFingerprint()).toBe(priorFingerprint);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(priorFingerprint);
+ if (surface === 'notice') {
+ await deliverNotice(contentDir);
+ } else {
+ await filter.rebuildIgnorePatterns();
+ const pruned = await reconcileFileIndexAfterFilterRebuild(watcher);
+ expect.soft(pruned).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ }
+ } finally {
+ deniedSkillRootRead.path = null;
+ }
+
+ expect(deniedSkillRootRead.observed).toBe(true);
+ expect.soft(warningErrors).toContain(failure);
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(watcher.getFileIndex().has(docName)).toBe(true);
+ for (const folder of knownFolders) {
+ expect.soft(watcher.getFolderIndex().has(folder)).toBe(true);
+ }
+ expect
+ .soft(
+ events.some(
+ (event) =>
+ (event.kind === 'delete' && event.docName === docName) ||
+ (event.kind === 'folder-delete' && knownFolders.includes(event.relativePath)),
+ ),
+ )
+ .toBe(false);
+
+ expect(readFileSync(skillPath, 'utf8')).toBe(before);
+ writeFileSync(skillPath, after);
+ if (surface === 'notice') {
+ await deliverNotice(contentDir);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: skillPath,
+ docName,
+ content: after,
+ }),
+ );
+ } else {
+ await filter.rebuildIgnorePatterns();
+ await reconcileFileIndexAfterFilterRebuild(watcher);
+ }
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(watcher.getFileIndex().has(docName)).toBe(true);
+ expect(watcher.getFileIndex().get(docName)?.title).toBe('After');
+ for (const folder of knownFolders) expect(watcher.getFolderIndex().has(folder)).toBe(true);
+
+ const laterDir = '.claude/skills/later';
+ writeSkillFixture(laterDir);
+ const currentFingerprint = filter.inPlaceSkillDirsFingerprint();
+ expect(filter.peekFreshInPlaceSkillDirsFingerprint()).toContain(laterDir);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(currentFingerprint);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+ },
+);
+
+test('an unreadable skill-root ancestor cannot masquerade as a missing root', async () => {
+ const skillDir = '.claude/skills/fixture';
+ const path = writeSkillFixture(skillDir);
+ const filter = dynamicSkillFilter();
+ const { watcher, events } = await watchContent(filter);
+ const root = join(contentDir, '.claude', 'skills');
+ expect(watcher.getFileIndex().has(`${skillDir}/SKILL`)).toBe(true);
+
+ admissionFault.maskedAncestor = root;
+ admissionFault.observed = false;
+ try {
+ expect(existsSync(root)).toBe(false);
+ expect(() => statSync(root)).toThrow(expect.objectContaining({ code: 'EACCES' }));
+ expect(() => realpathSync(root)).toThrow(expect.objectContaining({ code: 'EACCES' }));
+ expect(() => readdirSync(root)).toThrow(expect.objectContaining({ code: 'EACCES' }));
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(watcher.getFileIndex().has(`${skillDir}/SKILL`)).toBe(true);
+ expect.soft(watcher.getFolderIndex().has(skillDir)).toBe(true);
+ expect(events).toEqual([]);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(path, 'utf8')).toContain('# Fixture');
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+});
+
+test.each(['missing', 'empty', 'non-directory'] as const)(
+ 'a $0 skill root is a complete empty inventory',
+ (shape) => {
+ const root = join(contentDir, '.claude', 'skills');
+ if (shape === 'empty') mkdirSync(root, { recursive: true });
+ if (shape === 'non-directory') {
+ mkdirSync(dirname(root), { recursive: true });
+ writeFileSync(root, 'not a directory');
+ }
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([]);
+ expect(scanInPlaceSkills(contentDir)).toEqual([]);
+ },
+);
+
+test.each(['missing manifest', 'non-file manifest', 'removed bundle'] as const)(
+ '$0 is ordinary non-admission',
+ (shape) => {
+ const skillDir = '.claude/skills/fixture';
+ const bundle = join(contentDir, skillDir);
+ if (shape === 'removed bundle') {
+ writeSkillFixture(skillDir);
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ rmSync(bundle, { recursive: true, force: true });
+ } else {
+ mkdirSync(bundle, { recursive: true });
+ if (shape === 'non-file manifest') mkdirSync(join(bundle, 'SKILL.md'));
+ }
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([]);
+ },
+);
+
+test('a manifest directory link withdraws admission and a file link restores it', () => {
+ const skillDir = '.claude/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const manifestBytes = readFileSync(manifest, 'utf8');
+ const filter = dynamicSkillFilter();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ const directoryTarget = join(contentDir, 'manifest-directory');
+ mkdirSync(directoryTarget);
+ unlinkSync(manifest);
+ symlinkSync(directoryTarget, manifest);
+ expect(statSync(manifest).isDirectory()).toBe(true);
+ expect(scanInPlaceSkills(contentDir)).toEqual([]);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe('');
+
+ const fileTarget = join(contentDir, 'linked-manifest.md');
+ writeFileSync(fileTarget, manifestBytes);
+ unlinkSync(manifest);
+ symlinkSync(fileTarget, manifest);
+ expect(statSync(manifest).isFile()).toBe(true);
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(skillDir);
+});
+
+test('a case-mismatched manifest directory withdraws admission until restoration', () => {
+ const skillDir = '.claude/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const manifestBytes = readFileSync(manifest, 'utf8');
+ const filter = dynamicSkillFilter();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ unlinkSync(manifest);
+ const alternateCase = join(dirname(manifest), 'skill.md');
+ mkdirSync(alternateCase);
+ expect(readdirSync(dirname(manifest))).toContain('skill.md');
+ expect(scanInPlaceSkills(contentDir)).toEqual([]);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe('');
+
+ rmSync(alternateCase, { recursive: true, force: true });
+ writeFileSync(manifest, manifestBytes);
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(skillDir);
+});
+
+test('an unreadable skill root does not replace a complete nonempty admission with its readable remainder', async () => {
+ const deniedDir = '.claude/skills/denied-fixture';
+ const readableDir = '.codex/skills/readable-fixture';
+ writeSkillFixture(deniedDir);
+ writeSkillFixture(readableDir);
+ const filter = dynamicSkillFilter();
+ const before = [...scanInPlaceSkillDirs(contentDir)].sort();
+ expect(before).toEqual([deniedDir, readableDir].sort());
+ const deniedRoot = join(contentDir, '.claude', 'skills');
+
+ denyAdmission('readdir', deniedRoot);
+ try {
+ expect(scanInPlaceSkills(contentDir).map((skill) => skill.dir)).toEqual([readableDir]);
+ expect(scanGlobalInPlaceSkills(contentDir).map((skill) => skill.dir)).toEqual([readableDir]);
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${deniedDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${readableDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(before.join('\n'));
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ const laterDir = '.claude/skills/later-fixture';
+ writeSkillFixture(laterDir);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${deniedDir}/SKILL.md`)).toBe(false);
+ expect(filter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+ expect(filter.isExcluded(`${readableDir}/SKILL.md`)).toBe(false);
+});
+
+test.each([
+ { fault: 'candidate stat', operation: 'stat', target: 'bundle' },
+ { fault: 'candidate lstat', operation: 'lstat', target: 'bundle' },
+ { fault: 'bundle listing', operation: 'readdir', target: 'bundle' },
+ { fault: 'nested reference listing', operation: 'readdir', target: 'references' },
+ { fault: 'manifest stat', operation: 'stat', target: 'manifest' },
+ { fault: 'changed manifest read', operation: 'read', target: 'manifest' },
+ { fault: 'changed reference read', operation: 'read', target: 'reference' },
+] as const)('$fault cannot withdraw an admitted skill', ({ operation, target }) => {
+ const skillDir = '.claude/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const bundle = dirname(manifest);
+ const references = join(bundle, 'references');
+ mkdirSync(references);
+ const reference = join(references, 'context.md');
+ writeFileSync(reference, '# Before reference\n');
+ const beforeCatalog = scanInPlaceSkills(contentDir);
+ expect(beforeCatalog.map((skill) => skill.dir)).toEqual([skillDir]);
+ const filter = dynamicSkillFilter();
+
+ if (target === 'manifest')
+ writeFileSync(manifest, `${readFileSync(manifest, 'utf8')}# Changed manifest bytes\n`);
+ if (target === 'reference') writeFileSync(reference, '# Changed reference with more bytes\n');
+ const path = {
+ bundle,
+ references,
+ manifest,
+ reference,
+ }[target];
+ denyAdmission(operation, path);
+ try {
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(skillDir);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(scanInPlaceSkills(contentDir).map((skill) => skill.dir)).toEqual([skillDir]);
+ if (target === 'manifest' || target === 'reference') {
+ expect(scanInPlaceSkills(contentDir)[0].contentHash).not.toBe(beforeCatalog[0].contentHash);
+ }
+});
+
+test.each(['missing', 'directory'] as const)(
+ 'a reference becoming %s during its real read retains the known skill',
+ (shape) => {
+ const skillDir = '.claude/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const references = join(dirname(manifest), 'references');
+ mkdirSync(references);
+ const reference = join(references, 'context.md');
+ writeFileSync(reference, '# Reference\n');
+ const filter = dynamicSkillFilter();
+ const priorFingerprint = filter.inPlaceSkillDirsFingerprint();
+ expect(priorFingerprint).toBe(skillDir);
+ writeFileSync(manifest, `${readFileSync(manifest, 'utf8')}# Changed manifest bytes\n`);
+
+ admissionFault.descendantPath = reference;
+ admissionFault.descendantShape = shape;
+ try {
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.descendantObserved).toBe(true);
+ expect(admissionFault.descendantError?.code).toBe(shape === 'missing' ? 'ENOENT' : 'EISDIR');
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(priorFingerprint);
+ } finally {
+ admissionFault.descendantPath = null;
+ }
+
+ expect(readFileSync(manifest, 'utf8')).toContain('# Changed manifest bytes');
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ },
+);
+
+test.each([
+ { fault: 'ledger read denied' },
+ { fault: 'ledger ancestor hidden' },
+ { fault: 'ledger invalid JSON' },
+ { fault: 'configured path resolution denied' },
+] as const)('$fault cannot withdraw an admitted custom root', ({ fault }) => {
+ const skillDir = 'extra/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const validLedger = JSON.stringify({ schema: 1, skills: {}, roots: ['extra/skills'] });
+ const ledger = writeSkillLedger(validLedger);
+ const filter = dynamicSkillFilter();
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ if (fault === 'ledger read denied') denyAdmission('read', ledger);
+ if (fault === 'ledger ancestor hidden') admissionFault.maskedAncestor = ledger;
+ if (fault === 'configured path resolution denied') denyAdmission('realpath', contentDir);
+ if (fault === 'ledger invalid JSON') writeFileSync(ledger, '{ invalid JSON');
+ try {
+ if (fault === 'ledger ancestor hidden') {
+ expect(existsSync(ledger)).toBe(false);
+ expect(() => readFileSync(ledger, 'utf8')).toThrow(
+ expect.objectContaining({ code: 'EACCES' }),
+ );
+ }
+ if (fault === 'ledger read denied' || fault === 'ledger invalid JSON') {
+ expect(readSkillPlacementsStore(contentDir).roots).toBeUndefined();
+ }
+ filter.refreshInPlaceSkillDirs();
+ if (fault !== 'ledger invalid JSON') expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(skillDir);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(manifest, 'utf8')).toContain('# Fixture');
+ expect(readFileSync(ledger, 'utf8')).toBe(
+ fault === 'ledger invalid JSON' ? '{ invalid JSON' : validLedger,
+ );
+ writeFileSync(ledger, validLedger);
+ const laterDir = 'extra/skills/later';
+ writeSkillFixture(laterDir);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(filter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+});
+
+const customRootSkillDir = 'extra/skills/fixture';
+const standardCopyOfCustomRootSkillDir = '.claude/skills/fixture';
+const refreshedStandardSkillDir = '.claude/skills/refresh-fixture';
+const rawStandardSkillDir = '.claude/skills/raw-fixture';
+const duplicateSkillName = 'duplicate';
+const defaultDuplicateSkillDir = `.agents/skills/${duplicateSkillName}`;
+const preferredDuplicateSkillDir = `.claude/skills/${duplicateSkillName}`;
+const cursorDuplicateSkillDir = `.cursor/skills/${duplicateSkillName}`;
+const unreadableForkSkillDir = '.claude/skills/fork';
+const readableForkSkillDir = '.codex/skills/fork';
+
+function fingerprintOf(...dirs: string[]): string {
+ return [...dirs].sort().join('\n');
+}
+
+function prepareSkillServerProject(ledgerValue: unknown): { home: string; ledger: string } {
+ const home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-admission-home-')));
+ cleanupDirs.push(home);
+ const ledger = writeSkillLedger(ledgerValue);
+ writeFileSync(join(contentDir, '.ok', 'config.yml'), '');
+ writeFileSync(join(contentDir, '.ok', '.gitignore'), '');
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ return { home, ledger };
+}
+
+function writeReferencedSkillFixture(relativeDir: string): string {
+ const manifest = writeSkillFixture(relativeDir);
+ const references = join(dirname(manifest), 'references');
+ mkdirSync(references);
+ writeFileSync(join(references, 'context.md'), '# Reference\n');
+ return references;
+}
+
+function prepareCustomRootSkillProject(): { home: string; ledger: string; references: string } {
+ const references = writeReferencedSkillFixture(customRootSkillDir);
+ const project = prepareSkillServerProject({ schema: 1, skills: {}, roots: ['extra/skills'] });
+ return { ...project, references };
+}
+
+function preparePreferredDuplicateSkillProject(): { home: string; ledger: string } {
+ writeSkillFixture(defaultDuplicateSkillDir);
+ writeSkillFixture(preferredDuplicateSkillDir);
+ expect(readFileSync(join(contentDir, preferredDuplicateSkillDir, 'SKILL.md'), 'utf8')).toBe(
+ readFileSync(join(contentDir, defaultDuplicateSkillDir, 'SKILL.md'), 'utf8'),
+ );
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([defaultDuplicateSkillDir]);
+ return prepareSkillServerProject({
+ schema: 1,
+ skills: {},
+ sources: { [duplicateSkillName]: 'claude' },
+ });
+}
+
+function startSkillServer(home: string): ServerInstance {
+ return createServer({
+ contentDir,
+ projectDir: contentDir,
+ configHomedirOverride: home,
+ quiet: true,
+ port: 0,
+ gitEnabled: false,
+ });
+}
+
+async function deliverRawSkillCreate(path: string): Promise<void> {
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path }]);
+ await vi.runAllTimersAsync();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+test.each([{ fault: 'ledger invalid JSON' }, { fault: 'bundle subdirectory unreadable' }] as const)(
+ '$fault keeps the admitted custom root while server refreshes admit new standard-root skills',
+ async ({ fault }) => {
+ vi.useRealTimers();
+ const { home, ledger, references } = prepareCustomRootSkillProject();
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+ expect(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+
+ if (fault === 'ledger invalid JSON') {
+ writeFileSync(ledger, '{ invalid JSON');
+ expect(readSkillPlacementsStore(contentDir).roots).toBeUndefined();
+ } else {
+ denyAdmission('readdir', references);
+ }
+
+ writeSkillFixture(refreshedStandardSkillDir);
+ expect(filter.isExcluded(`${refreshedStandardSkillDir}/SKILL.md`)).toBe(true);
+ filter.refreshInPlaceSkillDirs();
+ if (fault !== 'ledger invalid JSON') expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${refreshedStandardSkillDir}/SKILL.md`)).toBe(false);
+
+ admissionFault.observed = false;
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ await deliverRawSkillCreate(writeSkillFixture(rawStandardSkillDir));
+ if (fault !== 'ledger invalid JSON') expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${rawStandardSkillDir}/SKILL.md`)).toBe(false);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ [customRootSkillDir, refreshedStandardSkillDir, rawStandardSkillDir].sort().join('\n'),
+ );
+ } finally {
+ clearAdmissionDenial();
+ vi.useRealTimers();
+ await server?.destroy();
+ }
+ },
+);
+
+test.each([
+ { factory: 'sync', surface: 'refresh' },
+ { factory: 'sync', surface: 'fingerprint peek' },
+ { factory: 'sync', surface: 'rebuild' },
+ { factory: 'async', surface: 'refresh' },
+ { factory: 'async', surface: 'fingerprint peek' },
+ { factory: 'async', surface: 'rebuild' },
+] as const)(
+ 'an invalid-JSON ledger keeps the admitted custom root while $surface on the $factory filter admits a new standard-root skill',
+ async ({ factory, surface }) => {
+ const { ledger } = prepareCustomRootSkillProject();
+ const options: ContentFilterOptions = {
+ projectDir: contentDir,
+ contentDir,
+ inPlaceSkillDirs: scanInPlaceSkillDirs(contentDir),
+ rescanInPlaceSkillDirs: (priorAdmission) => scanInPlaceSkillDirs(contentDir, priorAdmission),
+ skillRootPaths: skillRootPathsFor(contentDir),
+ };
+ const filter =
+ factory === 'sync' ? createContentFilter(options) : await createContentFilterAsync(options);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+ expect(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+
+ writeFileSync(ledger, '{ invalid JSON');
+ expect(readSkillPlacementsStore(contentDir).roots).toBeUndefined();
+ writeSkillFixture(refreshedStandardSkillDir);
+ expect(filter.isExcluded(`${refreshedStandardSkillDir}/SKILL.md`)).toBe(true);
+
+ const refreshedAdmission = fingerprintOf(customRootSkillDir, refreshedStandardSkillDir);
+ if (surface === 'fingerprint peek') {
+ expect(filter.peekFreshInPlaceSkillDirsFingerprint()).toBe(refreshedAdmission);
+ } else {
+ if (surface === 'refresh') {
+ filter.refreshInPlaceSkillDirs();
+ } else {
+ expect.soft(await filter.rebuildIgnorePatterns()).toMatchObject({ ok: true });
+ }
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${refreshedStandardSkillDir}/SKILL.md`)).toBe(false);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(refreshedAdmission);
+ }
+ },
+);
+
+test('a denied ledger read keeps the prior admission until server refreshes can read it', async () => {
+ vi.useRealTimers();
+ const { home, ledger } = prepareCustomRootSkillProject();
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+
+ denyAdmission('read', ledger);
+ writeSkillFixture(refreshedStandardSkillDir);
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+
+ admissionFault.observed = false;
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const rawPath = writeSkillFixture(rawStandardSkillDir);
+ await deliverRawSkillCreate(rawPath);
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+
+ clearAdmissionDenial();
+ await deliverRawSkillCreate(rawPath);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ [customRootSkillDir, refreshedStandardSkillDir, rawStandardSkillDir].sort().join('\n'),
+ );
+ } finally {
+ clearAdmissionDenial();
+ vi.useRealTimers();
+ await server?.destroy();
+ }
+});
+
+test('an invalid-JSON ledger keeps the preferred copy of a duplicate skill while server refreshes admit new standard-root skills', async () => {
+ vi.useRealTimers();
+ const { home, ledger } = preparePreferredDuplicateSkillProject();
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(preferredDuplicateSkillDir);
+ expect(filter.isExcluded(`${defaultDuplicateSkillDir}/SKILL.md`)).toBe(true);
+
+ writeFileSync(ledger, '{ invalid JSON');
+ expect(readSkillPlacementsStore(contentDir).sources).toBeUndefined();
+ writeSkillFixture(refreshedStandardSkillDir);
+ expect(filter.isExcluded(`${refreshedStandardSkillDir}/SKILL.md`)).toBe(true);
+ filter.refreshInPlaceSkillDirs();
+ expect.soft(filter.isExcluded(`${preferredDuplicateSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${defaultDuplicateSkillDir}/SKILL.md`)).toBe(true);
+ expect
+ .soft(filter.inPlaceSkillDirsFingerprint())
+ .toBe(fingerprintOf(preferredDuplicateSkillDir, refreshedStandardSkillDir));
+
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ await deliverRawSkillCreate(writeSkillFixture(rawStandardSkillDir));
+ expect.soft(filter.isExcluded(`${defaultDuplicateSkillDir}/SKILL.md`)).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ fingerprintOf(preferredDuplicateSkillDir, refreshedStandardSkillDir, rawStandardSkillDir),
+ );
+ } finally {
+ vi.useRealTimers();
+ await server?.destroy();
+ }
+});
+
+test.each([
+ { remaining: 'one copy', extraCopies: [] },
+ { remaining: 'two copies', extraCopies: [cursorDuplicateSkillDir] },
+] as const)(
+ 'an invalid-JSON ledger does not retain a preferred duplicate copy that left the disk with $remaining still present',
+ async ({ extraCopies }) => {
+ vi.useRealTimers();
+ const { home, ledger } = preparePreferredDuplicateSkillProject();
+ for (const dir of extraCopies) writeSkillFixture(dir);
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(preferredDuplicateSkillDir);
+
+ writeFileSync(ledger, '{ invalid JSON');
+ rmSync(join(contentDir, preferredDuplicateSkillDir), { recursive: true, force: true });
+ expect(existsSync(join(contentDir, preferredDuplicateSkillDir))).toBe(false);
+ expect(existsSync(join(contentDir, defaultDuplicateSkillDir, 'SKILL.md'))).toBe(true);
+ for (const dir of extraCopies)
+ expect(existsSync(join(contentDir, dir, 'SKILL.md'))).toBe(true);
+ filter.refreshInPlaceSkillDirs();
+ expect.soft(filter.isExcluded(`${defaultDuplicateSkillDir}/SKILL.md`)).toBe(false);
+ for (const dir of extraCopies) expect.soft(filter.isExcluded(`${dir}/SKILL.md`)).toBe(true);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(defaultDuplicateSkillDir);
+
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ await deliverRawSkillCreate(writeSkillFixture(rawStandardSkillDir));
+ for (const dir of extraCopies) expect.soft(filter.isExcluded(`${dir}/SKILL.md`)).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ fingerprintOf(defaultDuplicateSkillDir, rawStandardSkillDir),
+ );
+ } finally {
+ vi.useRealTimers();
+ await server?.destroy();
+ }
+ },
+);
+
+test('an unreadable skill bundle keeps a same-name fork admitted while it remains on disk and withdraws it once it leaves', async () => {
+ vi.useRealTimers();
+ const references = writeReferencedSkillFixture(unreadableForkSkillDir);
+ writeSkillFixture(readableForkSkillDir, '# Fork variant\n');
+ const { home } = prepareSkillServerProject({ schema: 1, skills: {} });
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ fingerprintOf(unreadableForkSkillDir, readableForkSkillDir),
+ );
+
+ denyAdmission('readdir', references);
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${unreadableForkSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${readableForkSkillDir}/SKILL.md`)).toBe(false);
+ expect
+ .soft(filter.inPlaceSkillDirsFingerprint())
+ .toBe(fingerprintOf(unreadableForkSkillDir, readableForkSkillDir));
+
+ rmSync(join(contentDir, readableForkSkillDir), { recursive: true, force: true });
+ expect(existsSync(join(contentDir, readableForkSkillDir))).toBe(false);
+ admissionFault.observed = false;
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${unreadableForkSkillDir}/SKILL.md`)).toBe(false);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(unreadableForkSkillDir);
+ } finally {
+ clearAdmissionDenial();
+ await server?.destroy();
+ }
+});
+
+test('an invalid-JSON ledger never admits a standard-root copy beside its retained custom-root skill', async () => {
+ vi.useRealTimers();
+ const { home, ledger } = prepareCustomRootSkillProject();
+ let server: ServerInstance | undefined;
+ try {
+ server = startSkillServer(home);
+ await server.ready;
+ const filter = server.contentFilter;
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(customRootSkillDir);
+
+ writeFileSync(ledger, '{ invalid JSON');
+ writeReferencedSkillFixture(standardCopyOfCustomRootSkillDir);
+ for (const file of ['SKILL.md', 'references/context.md']) {
+ expect(readFileSync(join(contentDir, standardCopyOfCustomRootSkillDir, file), 'utf8')).toBe(
+ readFileSync(join(contentDir, customRootSkillDir, file), 'utf8'),
+ );
+ }
+ writeSkillFixture(refreshedStandardSkillDir);
+ filter.refreshInPlaceSkillDirs();
+ expect.soft(filter.isExcluded(`${customRootSkillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${standardCopyOfCustomRootSkillDir}/SKILL.md`)).toBe(true);
+ expect
+ .soft(filter.inPlaceSkillDirsFingerprint())
+ .toBe(fingerprintOf(customRootSkillDir, refreshedStandardSkillDir));
+
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ await deliverRawSkillCreate(writeSkillFixture(rawStandardSkillDir));
+ expect.soft(filter.isExcluded(`${standardCopyOfCustomRootSkillDir}/SKILL.md`)).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(
+ fingerprintOf(customRootSkillDir, refreshedStandardSkillDir, rawStandardSkillDir),
+ );
+ } finally {
+ vi.useRealTimers();
+ await server?.destroy();
+ }
+});
+
+test('an unreadable configured skill root retains its admitted custom bundle', () => {
+ const skillDir = 'extra/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const manifestBytes = readFileSync(manifest, 'utf8');
+ const ledgerBytes = JSON.stringify({ schema: 1, skills: {}, roots: ['extra/skills'] });
+ const ledger = writeSkillLedger(ledgerBytes);
+ const filter = dynamicSkillFilter();
+ const priorFingerprint = filter.inPlaceSkillDirsFingerprint();
+ expect(priorFingerprint).toBe(skillDir);
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ const configuredRoot = join(contentDir, 'extra', 'skills');
+ denyAdmission('realpath', configuredRoot);
+ try {
+ expect(realpathSync(contentDir)).toBe(contentDir);
+ expect(readFileSync(ledger, 'utf8')).toBe(ledgerBytes);
+ expect(realpathSync(manifest)).toBe(manifest);
+ expect(admissionFault.observed).toBe(false);
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.inPlaceSkillDirsFingerprint()).toBe(priorFingerprint);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(manifest, 'utf8')).toBe(manifestBytes);
+ expect(readFileSync(ledger, 'utf8')).toBe(ledgerBytes);
+ const laterDir = 'extra/skills/later';
+ writeSkillFixture(laterDir);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(filter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+});
+
+test('a failed configured root preserves readable catalogs and prior admission', () => {
+ const deniedDir = 'extra/skills/denied-fixture';
+ const readableDir = 'other/skills/readable-fixture';
+ writeSkillFixture(deniedDir);
+ writeSkillFixture(readableDir);
+ const ledgerBytes = JSON.stringify({
+ schema: 1,
+ skills: {},
+ roots: ['extra/skills', 'other/skills'],
+ });
+ const ledger = writeSkillLedger(ledgerBytes);
+ const filter = dynamicSkillFilter();
+ const priorFingerprint = filter.inPlaceSkillDirsFingerprint();
+ expect(priorFingerprint).toBe([deniedDir, readableDir].join('\n'));
+
+ denyAdmission('realpath', join(contentDir, 'extra', 'skills'));
+ try {
+ expect(readSkillPlacementsStore(contentDir).roots).toEqual(['other/skills']);
+ admissionFault.observed = false;
+ expect(scanInPlaceSkills(contentDir).map((skill) => skill.dir)).toEqual([readableDir]);
+ expect(scanGlobalInPlaceSkills(contentDir).map((skill) => skill.dir)).toEqual([readableDir]);
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect(filter.inPlaceSkillDirsFingerprint()).toBe(priorFingerprint);
+ expect(filter.isExcluded(`${deniedDir}/SKILL.md`)).toBe(false);
+ expect(filter.isExcluded(`${readableDir}/SKILL.md`)).toBe(false);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(ledger, 'utf8')).toBe(ledgerBytes);
+ const laterDir = 'extra/skills/later-fixture';
+ writeSkillFixture(laterDir);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+});
+
+test('a denied child ancestor preserves public ledger reads and no-op writes', async () => {
+ const skillDir = 'extra/skills/fixture';
+ const manifest = writeSkillFixture(skillDir);
+ const manifestBytes = readFileSync(manifest, 'utf8');
+ const stored = {
+ schema: 1,
+ skills: { fixture: [{ path: skillDir, mode: 'copy', hash: 'fixture-hash' }] },
+ roots: ['extra/skills'],
+ };
+ const ledgerBytes = `${JSON.stringify(stored, null, 2)}\n`;
+ const ledger = writeSkillLedger(ledgerBytes);
+ admissionFault.maskedAncestor = join(contentDir, skillDir);
+ try {
+ const before = readSkillPlacementsStore(contentDir);
+ expect(admissionFault.observed).toBe(true);
+ expect(before.roots).toEqual(stored.roots);
+ expect(before.skills.fixture).toEqual(stored.skills.fixture);
+
+ admissionFault.observed = false;
+ await mutateSkillPlacementsStore(contentDir, () => {});
+ expect(admissionFault.observed).toBe(true);
+ const after = readSkillPlacementsStore(contentDir);
+ expect(after.roots).toEqual(stored.roots);
+ expect(after.skills.fixture).toEqual(stored.skills.fixture);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(ledger, 'utf8')).toBe(ledgerBytes);
+ expect(readFileSync(manifest, 'utf8')).toBe(manifestBytes);
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+});
+
+test('an unreadable source-preference ledger cannot change the canonical skill copy', () => {
+ const agentDir = '.agents/skills/fixture';
+ const preferredDir = '.claude/skills/fixture';
+ writeSkillFixture(agentDir);
+ writeSkillFixture(preferredDir);
+ const ledgerBytes = JSON.stringify({ schema: 1, skills: {}, sources: { fixture: 'claude' } });
+ const ledger = writeSkillLedger(ledgerBytes);
+ expect(scanInPlaceSkills(contentDir).find((skill) => skill.name === 'fixture')?.dir).toBe(
+ preferredDir,
+ );
+ const filter = dynamicSkillFilter();
+
+ denyAdmission('read', ledger);
+ try {
+ filter.refreshInPlaceSkillDirs();
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(filter.isExcluded(`${preferredDir}/SKILL.md`)).toBe(false);
+ expect.soft(filter.isExcluded(`${agentDir}/SKILL.md`)).toBe(true);
+ } finally {
+ clearAdmissionDenial();
+ }
+
+ expect(readFileSync(ledger, 'utf8')).toBe(ledgerBytes);
+ filter.refreshInPlaceSkillDirs();
+ expect(filter.isExcluded(`${preferredDir}/SKILL.md`)).toBe(false);
+ expect(scanInPlaceSkills(contentDir).find((skill) => skill.name === 'fixture')?.dir).toBe(
+ preferredDir,
+ );
+});
+
+test('missing and rejected ledger paths leave a valid in-root skill selectable', () => {
+ const skillDir = '.claude/skills/fixture';
+ writeSkillFixture(skillDir);
+ expect([...scanInPlaceSkillDirs(contentDir)]).toEqual([skillDir]);
+ const outside = realpathSync(mkdtempSync(join(tmpdir(), 'ok-admission-outside-')));
+ cleanupDirs.push(outside);
+ const outsideSkill = join(outside, 'skills', 'escaped');
+ mkdirSync(outsideSkill, { recursive: true });
+ writeFileSync(
+ join(outsideSkill, 'SKILL.md'),
+ '---\nname: escaped\ndescription: Fixture\n---\n\n# Escaped\n',
+ );
+ symlinkSync(outside, join(contentDir, 'linked'));
+ const ledger = writeSkillLedger({
+ schema: 1,
+ skills: {},
+ roots: ['../outside/skills', '/absolute/skills', 'linked/skills', 'extra/skills'],
+ });
+ writeSkillFixture('extra/skills/accepted');
+ expect([...scanInPlaceSkillDirs(contentDir)].sort()).toEqual(
+ [skillDir, 'extra/skills/accepted'].sort(),
+ );
+ expect(readFileSync(ledger, 'utf8')).toContain('../outside/skills');
+ expect(scanInPlaceSkills(contentDir).some((skill) => skill.dir === 'linked/skills/escaped')).toBe(
+ false,
+ );
+});
+
+test('server startup and raw skill refresh retain admission across an unreadable root', async () => {
+ vi.useRealTimers();
+ const home = realpathSync(mkdtempSync(join(tmpdir(), 'ok-admission-home-')));
+ cleanupDirs.push(home);
+ const skillDir = '.claude/skills/fixture';
+ const skillPath = writeSkillFixture(skillDir);
+ const skillRoot = join(contentDir, '.claude', 'skills');
+ const visiblePath = writeDoc('visible.md', '# Before\n');
+ mkdirSync(join(contentDir, '.ok'), { recursive: true });
+ writeFileSync(join(contentDir, '.ok', 'config.yml'), '');
+ writeFileSync(join(contentDir, '.ok', '.gitignore'), '');
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+
+ let server: ServerInstance | undefined;
+ let connection:
+ | Awaited<ReturnType<ServerInstance['hocuspocus']['openDirectConnection']>>
+ | undefined;
+ denyAdmission('readdir', skillRoot);
+ try {
+ server = createServer({
+ contentDir,
+ projectDir: contentDir,
+ configHomedirOverride: home,
+ quiet: true,
+ port: 0,
+ gitEnabled: false,
+ });
+ await server.ready;
+ expect(admissionFault.observed).toBe(true);
+ expect(server.contentFilter.isExcluded('visible.md')).toBe(false);
+ const subscription = nativeSubscriptionOn(contentDir);
+ connection = await server.hocuspocus.openDirectConnection('visible');
+ expect(server.hocuspocus.documents.get('visible')?.getText('source').toString()).toBe(
+ '# Before\n',
+ );
+ writeFileSync(visiblePath, '# After\n');
+ await subscription.deliver([{ type: 'update', path: visiblePath }]);
+ expect(server.hocuspocus.documents.get('visible')?.getText('source').toString()).toBe(
+ '# After\n',
+ );
+
+ clearAdmissionDenial();
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ await subscription.deliver([{ type: 'update', path: skillPath }]);
+ await vi.runAllTimersAsync();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(server.contentFilter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ denyAdmission('readdir', skillRoot);
+ await subscription.deliver([{ type: 'update', path: skillPath }]);
+ await vi.runAllTimersAsync();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(admissionFault.observed).toBe(true);
+ expect.soft(server.contentFilter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+
+ clearAdmissionDenial();
+ const laterDir = '.claude/skills/later';
+ const laterPath = writeSkillFixture(laterDir);
+ await subscription.deliver([{ type: 'create', path: laterPath }]);
+ await vi.runAllTimersAsync();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(server.contentFilter.isExcluded(`${skillDir}/SKILL.md`)).toBe(false);
+ expect(server.contentFilter.isExcluded(`${laterDir}/SKILL.md`)).toBe(false);
+ } finally {
+ clearAdmissionDenial();
+ vi.useRealTimers();
+ await connection?.disconnect();
+ await server?.destroy();
+ }
+});
+
+test('notice recovery finds nested markdown, general files and empty folders', async () => {
+ const { watcher, events } = await watchContent();
+ const nested = join(contentDir, 'outer', 'inner');
+ mkdirSync(join(nested, 'empty'), { recursive: true });
+ const notePath = join(nested, 'note.md');
+ const dataPath = join(contentDir, 'outer', 'data.json');
+ writeFileSync(notePath, '# Nested\n');
+ writeFileSync(dataPath, '{}\n');
+
+ await deliverNotice(contentDir);
+
+ expect.soft(watcher.getFolderIndex().has('outer')).toBe(true);
+ expect.soft(watcher.getFolderIndex().has('outer/inner')).toBe(true);
+ expect.soft(watcher.getFolderIndex().has('outer/inner/empty')).toBe(true);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'folder-create', relativePath: 'outer/inner/empty' }),
+ );
+ expect.soft(events).toContainEqual({
+ kind: 'create',
+ path: notePath,
+ docName: 'outer/inner/note',
+ content: '# Nested\n',
+ });
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'file-create',
+ path: dataPath,
+ relativePath: 'outer/data.json',
+ }),
+ );
+ expect(watcher.getFileIndex().has('outer/inner/note')).toBe(true);
+ expect(Boolean(indexedRow(watcher, 'outer/data.json', 'file'))).toBe(true);
+});
+
+test('notice recovery removes a collapsed directory and its indexed descendants', async () => {
+ const nested = join(contentDir, 'outer', 'inner');
+ mkdirSync(nested, { recursive: true });
+ const notePath = join(nested, 'note.md');
+ const generalPath = join(nested, 'data.csv');
+ writeFileSync(notePath, '# Nested\n');
+ writeFileSync(generalPath, 'gone\n');
+ const { watcher, events } = await watchContent();
+ expect(watcher.getFileIndex().has('outer/inner/note')).toBe(true);
+ rmSync(join(contentDir, 'outer'), { recursive: true, force: true });
+
+ await deliverNotice(contentDir);
+
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'delete', path: notePath, docName: 'outer/inner/note' });
+ expect.soft(events).toContainEqual({
+ kind: 'file-delete',
+ path: generalPath,
+ relativePath: 'outer/inner/data.csv',
+ });
+ expect
+ .soft(events)
+ .toContainEqual(expect.objectContaining({ kind: 'folder-delete', relativePath: 'outer' }));
+ expect(watcher.getFolderIndex().has('outer')).toBe(false);
+ expect(watcher.getFolderIndex().has('outer/inner')).toBe(false);
+ expect(watcher.getFileIndex().has('outer/inner/note')).toBe(false);
+ expect(Boolean(indexedRow(watcher, 'outer/inner/data.csv', 'file'))).toBe(false);
+});
+
+test('notice recovery tracks general-file changes and asset notifications outside the markdown view', async () => {
+ const changed = join(contentDir, 'changed.csv');
+ const removed = join(contentDir, 'removed.csv');
+ const removedAsset = join(contentDir, 'removed.png');
+ writeFileSync(changed, 'old\n');
+ writeFileSync(removed, 'gone\n');
+ writeFileSync(removedAsset, 'old-asset');
+ const { watcher, events } = await watchContent();
+ const created = join(contentDir, 'created.csv');
+ const asset = join(contentDir, 'pic.png');
+ writeFileSync(created, 'new\n');
+ writeFileSync(asset, 'fake-png-bytes');
+ writeFileSync(changed, 'new,more,bytes\n');
+ const changedStat = statSync(changed);
+ unlinkSync(removed);
+ unlinkSync(removedAsset);
+
+ await deliverNotice(contentDir);
+
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: created, relativePath: 'created.csv' }),
+ );
+ expect.soft(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'file-update',
+ path: changed,
+ relativePath: 'changed.csv',
+ size: Buffer.byteLength('new,more,bytes\n'),
+ modifiedTs: changedStat.mtime.getTime(),
+ inode: Number(changedStat.ino),
+ }),
+ );
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'file-delete', path: removed, relativePath: 'removed.csv' });
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'asset-create', path: asset, relativePath: 'pic.png' });
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'asset-delete', path: removedAsset, relativePath: 'removed.png' });
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'file-delete', path: removedAsset, relativePath: 'removed.png' });
+ expect.soft(Boolean(indexedRow(watcher, 'created.csv', 'file'))).toBe(true);
+ expect.soft(Boolean(indexedRow(watcher, 'removed.csv', 'file'))).toBe(false);
+ expect.soft(Boolean(indexedRow(watcher, 'removed.png', 'file'))).toBe(false);
+ expect.soft(indexedRow(watcher, 'changed.csv', 'file')?.size).toBe(changedStat.size);
+ expect
+ .soft(indexedRow(watcher, 'changed.csv', 'file')?.modified)
+ .toBe(changedStat.mtime.toISOString());
+ expect(watcher.getFileIndex().has('created.csv')).toBe(false);
+ expect(lastKnownHash.has(created)).toBe(false);
+ expect(lastKnownHash.has(asset)).toBe(false);
+});
+
+test('notice recovery updates and removes a lexical file alias without deleting its target', async () => {
+ const firstTarget = writeDoc('first.md', '# First\n');
+ const secondTarget = writeDoc('second.md', '# Second\n');
+ const aliasPath = join(contentDir, 'linked.MdX');
+ symlinkSync(firstTarget, aliasPath);
+ const { watcher, events } = await watchContent();
+ expect(watcher.getAliasMap().get('linked')).toBe('first');
+
+ unlinkSync(aliasPath);
+ symlinkSync(secondTarget, aliasPath);
+ await deliverNotice(contentDir);
+
+ expect.soft(watcher.getAliasMap().get('linked')).toBe('second');
+ expect.soft(watcher.getFileIndex().get('first')?.aliases).not.toContain('linked');
+ expect.soft(watcher.getFileIndex().get('second')?.aliases).toContain('linked');
+ expect.soft([...watcher.getFileIndex().keys()].sort()).toEqual(['first', 'second']);
+
+ unlinkSync(aliasPath);
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual({ kind: 'delete', path: aliasPath, docName: 'linked' });
+ expect(watcher.getAliasMap().has('linked')).toBe(false);
+ expect(watcher.getFileIndex().get('second')?.aliases).not.toContain('linked');
+ expect(watcher.getFileIndex().has('second')).toBe(true);
+ expect(events.some((event) => event.kind === 'delete' && event.docName === 'second')).toBe(false);
+});
+
+test('an ordinary alias record retains its lexical path for an omitted deletion', async () => {
+ const target = writeDoc('ordinary-target.md', '# Target\n');
+ const { watcher, events } = await watchContent();
+ const alias = join(contentDir, 'ordinary-alias.MdX');
+ symlinkSync(target, alias);
+ await deliver(contentDir, [{ type: 'create', path: alias }]);
+ unlinkSync(alias);
+
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual({ kind: 'delete', path: alias, docName: 'ordinary-alias' });
+ expect(watcher.getFileIndex().has('ordinary-target')).toBe(true);
+});
+
+test('notice recovery preserves canonical folder identity and rejects broken, cyclic and out-of-root links', async () => {
+ const canonicalDir = join(contentDir, 'canonical');
+ mkdirSync(canonicalDir);
+ const canonicalNote = join(canonicalDir, 'note.md');
+ writeFileSync(canonicalNote, '# Canonical\n');
+ const outsideDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-parcel-outside-')));
+ cleanupDirs.push(outsideDir);
+ const outsideNote = join(outsideDir, 'outside.md');
+ writeFileSync(outsideNote, '# Outside\n');
+ const { watcher, events } = await watchContent();
+
+ symlinkSync(canonicalDir, join(contentDir, 'linked-folder'));
+ symlinkSync(canonicalDir, join(canonicalDir, 'cycle'));
+ symlinkSync(join(contentDir, 'missing.md'), join(contentDir, 'broken.md'));
+ symlinkSync(outsideNote, join(contentDir, 'escape.md'));
+ await deliverNotice(contentDir);
+
+ expect(watcher.getFolderAliasIndex().get('linked-folder')).toBe('canonical');
+ expect(watcher.getFolderIndex().has('linked-folder')).toBe(false);
+ expect(watcher.getFileIndex().has('canonical/note')).toBe(true);
+ expect(watcher.getFileIndex().has('linked-folder/note')).toBe(false);
+ expect(watcher.getFileIndex().has('broken')).toBe(false);
+ expect(watcher.getFileIndex().has('escape')).toBe(false);
+ expect(events.some((event) => 'docName' in event && event.docName === 'escape')).toBe(false);
+ expect([...watcher.getFileIndex().keys()]).toEqual(['canonical/note']);
+
+ unlinkSync(join(contentDir, 'linked-folder'));
+ await deliverNotice(contentDir);
+ expect(watcher.getFolderAliasIndex().has('linked-folder')).toBe(false);
+ expect(watcher.getFolderIndex().has('canonical')).toBe(true);
+ expect(watcher.getFileIndex().has('canonical/note')).toBe(true);
+});
+
+test('startup and index-only reseeding retain extension and metadata contracts during later notice recovery', async () => {
+ const metaPath = writeDoc('CaseEntry.MD', '---\ntitle: Before\n---\n\n# Ignored\n');
+ const binaryPath = join(contentDir, 'payload.bin');
+ writeFileSync(binaryPath, Buffer.alloc(32, 0xff));
+ const { watcher, events } = await watchContent();
+ expect(watcher.getFileIndex().get('CaseEntry')?.title).toBe('Before');
+ expect(getDocExtension('CaseEntry')).toBe('.MD');
+ expect(indexedRow(watcher, 'payload.bin', 'file')?.kind).toBe('file');
+ expect(lastKnownHash.has(binaryPath)).toBe(false);
+
+ writeDoc('Rebuilt.mdx', '# Rebuilt\n');
+ await watcher.rescanFromDisk();
+ expect(watcher.getFileIndex().has('Rebuilt')).toBe(true);
+ expect(getDocExtension('Rebuilt')).toBe('.mdx');
+ expect(events).toEqual([]);
+
+ const beforeGeneration = watcher.getFileIndexGeneration();
+ writeFileSync(metaPath, '---\ntitle: After\n---\n\n# Ignored\n');
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: metaPath,
+ docName: 'CaseEntry',
+ previousIndexedFields: { title: 'Before', description: undefined, type: undefined },
+ }),
+ );
+ expect(watcher.getFileIndex().get('CaseEntry')?.title).toBe('After');
+ expect(watcher.getFileIndexGeneration()).toBeGreaterThan(beforeGeneration);
+ expect(lastKnownHash.has(binaryPath)).toBe(false);
+});
+
+test('index-only reseeding retains the registered preferred file after it disappears', async () => {
+ writeDoc('reseed-priority.md', '# Shadowed\n');
+ const preferredPath = writeDoc('reseed-priority.mdx', '# Preferred\n');
+ const { watcher, events } = await watchContent();
+ expect(watcher.getFileIndex().get('reseed-priority')?.canonicalPath).toBe(preferredPath);
+ expect(getDocExtension('reseed-priority')).toBe('.mdx');
+
+ unlinkSync(preferredPath);
+ await watcher.rescanFromDisk();
+
+ expect(watcher.getFileIndex().get('reseed-priority')?.canonicalPath).toBe(preferredPath);
+ expect(getDocExtension('reseed-priority')).toBe('.mdx');
+ expect(events).toEqual([]);
+});
+
+test('an index-only reseed started by a raw notice observer preserves omitted recovery', async () => {
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle | undefined;
+ let reseed: Promise<void> | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRawBatch: () => {
+ if (reseed === undefined && watcher !== undefined) reseed = watcher.rescanFromDisk();
+ },
+ },
+ );
+ handles.push(watcher);
+ const hidden = writeDoc('hidden-reseed.md', '# Hidden\n');
+
+ await deliverNotice(contentDir);
+ await reseed;
+
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: hidden,
+ docName: 'hidden-reseed',
+ content: '# Hidden\n',
+ });
+ expect(watcher.getFileIndex().has('hidden-reseed')).toBe(true);
+});
+
+test('a public content callback index update survives notice publication', async () => {
+ let watcher: WatcherHandle | undefined;
+ const sidePath = join(contentDir, 'side.md');
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ if (event.kind !== 'create' || event.docName !== 'first') return;
+ writeFileSync(sidePath, '# Side\n');
+ watcher?.mutateFileIndex({
+ kind: 'create',
+ path: sidePath,
+ docName: 'side',
+ content: '# Side\n',
+ });
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ writeDoc('first.md', '# First\n');
+
+ await deliverNotice(contentDir);
+
+ expect(watcher.getFileIndex().has('first')).toBe(true);
+ expect(watcher.getFileIndex().get('side')?.canonicalPath).toBe(sidePath);
+ expect(watcher.getFileIndex().get('side')?.title).toBe('Side');
+});
+
+test.each(['markdown', 'general'] as const)(
+ 'a public %s creation during directory observation remains indexed',
+ async (kind) => {
+ const { watcher, events } = await watchContent();
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = deliverNotice(contentDir);
+ try {
+ await entered.promise;
+ const name = kind === 'markdown' ? 'fresh.md' : 'fresh.csv';
+ const path = writeDoc(name, '# Fresh\n');
+ const key = kind === 'markdown' ? 'fresh' : name;
+ const stat = statSync(path);
+ watcher.mutateFileIndex(
+ kind === 'markdown'
+ ? { kind: 'create', path, docName: key, content: '# Fresh\n' }
+ : {
+ kind: 'file-create',
+ path,
+ relativePath: key,
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: stat.ino,
+ },
+ );
+ expect(Boolean(indexedRow(watcher, key, kind === 'markdown' ? 'markdown' : 'file'))).toBe(
+ true,
+ );
+ resume.release();
+ await pending;
+ expect(readFileSync(path, 'utf8')).toBe('# Fresh\n');
+ expect.soft(events).toEqual([]);
+ expect(Boolean(indexedRow(watcher, key, kind === 'markdown' ? 'markdown' : 'file'))).toBe(
+ true,
+ );
+ } finally {
+ resume.release();
+ await pending;
+ }
+ },
+);
+
+test('notices during a running recovery scan share one follow-up scan and keep delivered records in order', async () => {
+ const sentinel = writeDoc('sentinel.md', '# Sentinel\n');
+ const delivered = ['second', 'third', 'fourth'];
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = [
+ 'sentinel.md',
+ ...delivered.map((name) => `${name}.md`),
+ 'omitted.md',
+ ];
+ const { watcher, events, rawBatches } = await watchContent();
+ memberStatSchedule.seen = [];
+ rawBatches.length = 0;
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const subscription = nativeSubscriptionOn(contentDir);
+ const pending = [subscription.deliver([], new Error(notices[0]))];
+ const deliveredPaths: string[] = [];
+ try {
+ await entered.promise;
+ writeDoc('omitted.md', '# Omitted\n');
+ for (const [index, name] of delivered.entries()) {
+ const path = writeDoc(`${name}.md`, `# ${name}\n`);
+ deliveredPaths.push(path);
+ pending.push(
+ subscription.deliver(
+ [{ type: 'create', path }],
+ new Error(notices[(index + 1) % notices.length]),
+ ),
+ );
+ }
+ resume.release();
+ await Promise.all(pending);
+ await vi.runAllTimersAsync();
+
+ expect(rawBatches.filter((batch) => batch.length > 0 && !batch.includes(sentinel))).toEqual(
+ deliveredPaths.map((path) => [path]),
+ );
+ const created = events.flatMap((event) => (event.kind === 'create' ? [event.docName] : []));
+ expect(created.filter((name) => delivered.includes(name))).toEqual(delivered);
+ expect(created).toContain('omitted');
+ for (const name of ['sentinel', ...delivered, 'omitted']) {
+ expect(watcher.getFileIndex().has(name)).toBe(true);
+ }
+ expect(memberStatSchedule.seen.filter((path) => path === sentinel)).toHaveLength(2);
+ } finally {
+ resume.release();
+ await Promise.all(pending);
+ }
+});
+
+test.each(['alias.csv', 'real.csv'])(
+ 'general-file recovery keeps a single target when %s is enumerated first',
+ async (firstEntry) => {
+ const real = writeDoc('real.csv', 'before\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = firstEntry;
+ const { watcher, events } = await watchContent();
+ expect(indexedIdentityRows(watcher).filter((entry) => entry.kind === 'file')).toEqual([
+ expect.objectContaining({
+ name: 'real.csv',
+ canonicalPath: real,
+ aliases: ['alias.csv'],
+ }),
+ ]);
+ writeFileSync(real, 'after,more,bytes\n');
+ await deliverNotice(contentDir);
+ expect.soft(indexedIdentityRows(watcher)).toHaveLength(1);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: real, relativePath: 'real.csv' }),
+ );
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect.soft(events).toEqual([]);
+ unlinkSync(alias);
+ await deliverNotice(contentDir);
+ expect
+ .soft(events.some((event) => event.kind === 'file-delete' && event.path === real))
+ .toBe(false);
+ const other = writeDoc('other.csv', 'other\n');
+ symlinkSync(other, alias);
+ await deliverNotice(contentDir);
+ const entries = indexedIdentityRows(watcher);
+ expect.soft(entries.filter((entry) => entry.canonicalPath === real)).toHaveLength(1);
+ expect.soft(entries.filter((entry) => entry.canonicalPath === other)).toHaveLength(1);
+ expect(readFileSync(real, 'utf8')).toBe('after,more,bytes\n');
+ events.length = 0;
+ unlinkSync(real);
+ await deliverNotice(contentDir);
+ expect(events).toContainEqual({
+ kind: 'file-delete',
+ path: real,
+ relativePath: 'real.csv',
+ });
+ expect(indexedIdentityRows(watcher).some((entry) => entry.canonicalPath === real)).toBe(false);
+ },
+);
+
+test.each(['markdown', 'general'] as const)(
+ 'a public %s recreation during recovery supersedes a pending deletion',
+ async (kind) => {
+ const first = writeDoc('first.md', '# First\n');
+ const name = kind === 'markdown' ? 'later.md' : 'later.csv';
+ const later = writeDoc(name, '# Before\n');
+ const key = kind === 'markdown' ? 'later' : name;
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'first.md';
+ const watched = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'delete' || event.docName !== 'first') return;
+ writeFileSync(later, '# Recreated\n');
+ const stat = statSync(later);
+ watched.watcher.mutateFileIndex(
+ kind === 'markdown'
+ ? { kind: 'create', path: later, docName: key, content: '# Recreated\n' }
+ : {
+ kind: 'file-create',
+ path: later,
+ relativePath: key,
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: stat.ino,
+ },
+ );
+ });
+ expect(
+ Boolean(indexedRow(watched.watcher, key, kind === 'markdown' ? 'markdown' : 'file')),
+ ).toBe(true);
+ unlinkSync(first);
+ unlinkSync(later);
+
+ await deliverNotice(contentDir);
+
+ expect(watched.events).toContainEqual({ kind: 'delete', path: first, docName: 'first' });
+ expect(readFileSync(later, 'utf8')).toBe('# Recreated\n');
+ expect
+ .soft(watched.events.filter((event) => 'path' in event && event.path === later))
+ .toEqual([]);
+ expect(indexedRow(watched.watcher, key, kind === 'markdown' ? 'markdown' : 'file')?.size).toBe(
+ Buffer.byteLength('# Recreated\n'),
+ );
+ },
+);
+
+test('a public recreation during recovery retains its restored parent directory', async () => {
+ const first = writeDoc('first.md', '# First\n');
+ const folder = join(contentDir, 'nested');
+ mkdirSync(folder);
+ const later = writeDoc('nested/later.md', '# Before\n');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'first.md';
+ const watched = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'delete' || event.docName !== 'first') return;
+ mkdirSync(folder);
+ writeFileSync(later, '# Recreated\n');
+ watched.watcher.mutateFileIndex({
+ kind: 'create',
+ path: later,
+ docName: 'nested/later',
+ content: '# Recreated\n',
+ });
+ });
+ expect(watched.watcher.getFolderIndex().has('nested')).toBe(true);
+ unlinkSync(first);
+ rmSync(folder, { recursive: true });
+
+ await deliverNotice(contentDir);
+
+ expect(watched.events).toContainEqual({ kind: 'delete', path: first, docName: 'first' });
+ expect(readFileSync(later, 'utf8')).toBe('# Recreated\n');
+ expect.soft(Boolean(indexedRow(watched.watcher, 'nested/later', 'markdown'))).toBe(true);
+ expect.soft(watched.events).not.toContainEqual({
+ kind: 'folder-delete',
+ path: folder,
+ relativePath: 'nested',
+ });
+ expect(watched.watcher.getFolderIndex().has('nested')).toBe(true);
+});
+
+test('a delivered general-file alias record stays one identity after recovery', async () => {
+ const real = writeDoc('real.csv', 'one\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ const { watcher, events } = await watchContent();
+ await deliverNotice(contentDir);
+ expect(indexedIdentityRows(watcher)).toHaveLength(1);
+ await deliver(contentDir, [{ type: 'update', path: alias }]);
+ events.length = 0;
+
+ await deliverNotice(contentDir);
+
+ expect(readFileSync(alias, 'utf8')).toBe('one\n');
+ expect.soft(events.filter((event) => 'path' in event && event.path === alias)).toEqual([]);
+ expect(indexedIdentityRows(watcher)).toHaveLength(1);
+});
+
+test.each(['create', 'update'] as const)(
+ 'a delivered alias %s preserves its former general-file target',
+ async (type) => {
+ const real = writeDoc('real.csv', 'first\n');
+ const other = writeDoc('other.csv', 'second\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ expect(indexedAliasOwner(watcher, 'alias.csv')?.canonicalPath).toBe(real);
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+
+ await deliver(contentDir, [{ type, path: alias }]);
+
+ expect(readFileSync(real, 'utf8')).toBe('first\n');
+ expect(readFileSync(alias, 'utf8')).toBe('second\n');
+ const entries = indexedIdentityRows(watcher);
+ expect.soft(entries.filter((entry) => entry.canonicalPath === real)).toHaveLength(1);
+ expect.soft(entries.filter((entry) => entry.canonicalPath === other)).toHaveLength(1);
+ events.length = 0;
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+ expect.soft(events.filter((event) => event.kind === 'file-delete')).toEqual([]);
+ const recovered = indexedIdentityRows(watcher);
+ expect(recovered.filter((entry) => entry.canonicalPath === real)).toHaveLength(1);
+ expect(recovered.filter((entry) => entry.canonicalPath === other)).toHaveLength(1);
+ },
+);
+
+test('a delivered alias retarget keeps sibling aliases on their original target', async () => {
+ const real = writeDoc('real.csv', 'first\n');
+ const alias = join(contentDir, 'alias.csv');
+ const sibling = join(contentDir, 'sibling.csv');
+ symlinkSync(real, alias);
+ symlinkSync(real, sibling);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher } = await watchContent();
+ expect(indexedAliasOwner(watcher, 'alias.csv')?.aliases).toContain('sibling.csv');
+ const other = writeDoc('other.csv', 'second\n');
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+
+ await deliver(contentDir, [{ type: 'update', path: alias }]);
+
+ expect(readFileSync(sibling, 'utf8')).toBe('first\n');
+ expect(readFileSync(alias, 'utf8')).toBe('second\n');
+ const owners = indexedIdentityRows(watcher).filter((entry) =>
+ entry.aliases.includes('sibling.csv'),
+ );
+ expect.soft(owners).toHaveLength(1);
+ expect.soft(owners.map((entry) => entry.canonicalPath)).toEqual([real]);
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+ const recovered = indexedIdentityRows(watcher);
+ expect(recovered.filter((entry) => entry.canonicalPath === real)).toHaveLength(1);
+ expect(recovered.filter((entry) => entry.canonicalPath === other)).toHaveLength(1);
+});
+
+test('an ordinary canonical file update retains its aliases beside a same-stem document', async () => {
+ const real = writeDoc('real.csv', 'first\n');
+ const document = writeDoc('real.csv.md', '# Document\n');
+ const alias = join(contentDir, 'alias.csv');
+ const sibling = join(contentDir, 'sibling.csv');
+ symlinkSync(real, alias);
+ symlinkSync(real, sibling);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ expect(indexedRow(watcher, 'real.csv', 'file')?.aliases).toEqual(['alias.csv', 'sibling.csv']);
+ expect(indexedRow(watcher, 'real.csv', 'markdown')?.canonicalPath).toBe(document);
+ writeFileSync(real, 'changed,longer,bytes\n');
+
+ await deliver(contentDir, [{ type: 'update', path: real }]);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: real, relativePath: 'real.csv' }),
+ );
+ const rows = indexedIdentityRows(watcher);
+ expect(
+ rows.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ expect(rows.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)).toMatchObject(
+ {
+ name: 'real.csv',
+ aliases: ['alias.csv', 'sibling.csv'],
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ modified: statSync(real).mtime.toISOString(),
+ },
+ );
+ expect(
+ rows.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ expect(readFileSync(alias, 'utf8')).toBe('changed,longer,bytes\n');
+ expect(readFileSync(sibling, 'utf8')).toBe('changed,longer,bytes\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Document\n');
+});
+
+test('an ordinary alias retarget retains aliases already owned by its new target', async () => {
+ const real = writeDoc('real.csv', 'first\n');
+ const other = writeDoc('other.csv', 'second,longer\n');
+ const document = writeDoc('real.csv.md', '# Document\n');
+ const alias = join(contentDir, 'alias.csv');
+ const oldSibling = join(contentDir, 'old-sibling.csv');
+ const newSibling = join(contentDir, 'new-sibling.csv');
+ symlinkSync(real, alias);
+ symlinkSync(real, oldSibling);
+ symlinkSync(other, newSibling);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ expect(indexedRow(watcher, 'real.csv', 'file')?.aliases).toEqual([
+ 'alias.csv',
+ 'old-sibling.csv',
+ ]);
+ expect(indexedRow(watcher, 'other.csv', 'file')?.aliases).toEqual(['new-sibling.csv']);
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+
+ await deliver(contentDir, [{ type: 'update', path: alias }]);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: alias, relativePath: 'alias.csv' }),
+ );
+ const rows = indexedIdentityRows(watcher);
+ expect(
+ rows.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ expect(
+ rows.filter((entry) => entry.kind === 'file' && entry.canonicalPath === other),
+ ).toHaveLength(1);
+ expect(rows.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)).toMatchObject(
+ {
+ aliases: ['old-sibling.csv'],
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ },
+ );
+ expect(
+ rows.find((entry) => entry.kind === 'file' && entry.canonicalPath === other),
+ ).toMatchObject({
+ name: 'other.csv',
+ aliases: expect.arrayContaining(['alias.csv', 'new-sibling.csv']),
+ size: statSync(other).size,
+ inode: Number(statSync(other).ino),
+ });
+ expect(
+ rows.find((entry) => entry.kind === 'file' && entry.canonicalPath === other)?.aliases,
+ ).toHaveLength(2);
+ expect(
+ rows.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ expect(readFileSync(alias, 'utf8')).toBe('second,longer\n');
+ expect(readFileSync(oldSibling, 'utf8')).toBe('first\n');
+ expect(readFileSync(newSibling, 'utf8')).toBe('second,longer\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Document\n');
+});
+
+test('a general-file alias retarget does not discard later delivered records', async () => {
+ const real = writeDoc('real.csv', 'first\n');
+ const document = writeDoc('real.csv.md', '# Document\n');
+ const other = writeDoc('other.csv', 'second\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ expect(indexedAliasOwner(watcher, 'alias.csv')?.canonicalPath).toBe(real);
+ expect(watcher.getFileIndex().get('real.csv')?.canonicalPath).toBe(document);
+ const later = writeDoc('later.csv', 'later\n');
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+
+ await deliver(contentDir, [
+ { type: 'update', path: alias },
+ { type: 'create', path: later },
+ ]);
+
+ expect(readFileSync(real, 'utf8')).toBe('first\n');
+ expect(watcher.getFileIndex().get('real.csv')?.canonicalPath).toBe(document);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: later, relativePath: 'later.csv' }),
+ );
+ expect(indexedRow(watcher, 'later.csv', 'file')?.canonicalPath).toBe(later);
+});
+
+test('notice recovery retains a general-file alias beside a matching document stem', async () => {
+ const real = writeDoc('real.csv', 'first\n');
+ const document = writeDoc('real.csv.md', '# Document\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ expect(indexedAliasOwner(watcher, 'alias.csv')?.canonicalPath).toBe(real);
+ expect(watcher.getFileIndex().get('real.csv')?.canonicalPath).toBe(document);
+
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+
+ expect(readFileSync(real, 'utf8')).toBe('first\n');
+ expect(readFileSync(alias, 'utf8')).toBe('first\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Document\n');
+ expect.soft(events).toEqual([]);
+ const entries = indexedIdentityRows(watcher);
+ expect.soft(entries.filter((entry) => entry.canonicalPath === real)).toHaveLength(1);
+ expect(entries.filter((entry) => entry.canonicalPath === document)).toHaveLength(1);
+});
+
+test('notice recovery keeps file links exact beside a matching document stem', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = writeDoc('real.csv', 'first\n');
+ writeDoc('real.csv.md', '# Document\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ writeDoc('source.md', '# Source\n\n[Target](real.csv)\n\n[Alias](alias.csv)\n');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ const statuses = async () => {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/forward-links?docName=source`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ localTargets: Array<{ href: string; status: string }>;
+ };
+ return Object.fromEntries(body.localTargets.map((target) => [target.href, target.status]));
+ };
+ const expected = { 'real.csv': 'exact', 'alias.csv': 'exact' };
+ expect(await statuses()).toEqual(expected);
+ const subscription = nativeSubscriptionOn(contentDir);
+
+ await subscription.deliver([], new Error(notices[0]));
+ await subscription.deliver([], new Error(notices[0]));
+
+ expect(readFileSync(real, 'utf8')).toBe('first\n');
+ expect(readFileSync(alias, 'utf8')).toBe('first\n');
+ expect(await statuses()).toEqual(expected);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('a delivered alias retarget preserves both real link targets', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = writeDoc('real.csv', 'first\n');
+ const other = writeDoc('other.csv', 'second\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ writeDoc(
+ 'source.md',
+ '# Source\n\n[First](real.csv)\n\n[Second](other.csv)\n\n[Alias](alias.csv)\n',
+ );
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ const statuses = async () => {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/forward-links?docName=source`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ localTargets: Array<{ href: string; status: string }>;
+ };
+ return Object.fromEntries(body.localTargets.map((target) => [target.href, target.status]));
+ };
+ const expected = { 'real.csv': 'exact', 'other.csv': 'exact', 'alias.csv': 'exact' };
+ expect(await statuses()).toEqual(expected);
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ const subscription = nativeSubscriptionOn(contentDir);
+
+ await subscription.deliver([{ type: 'update', path: alias }]);
+
+ expect(readFileSync(real, 'utf8')).toBe('first\n');
+ expect(readFileSync(alias, 'utf8')).toBe('second\n');
+ expect.soft(await statuses()).toEqual(expected);
+ await subscription.deliver([], new Error(notices[0]));
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await statuses()).toEqual(expected);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('a delivered general-file alias retains both link targets after recovery', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = writeDoc('real.csv', 'one\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ writeDoc('source.md', '# Source\n\n[Target](real.csv)\n\n[Alias](alias.csv)\n');
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ const statuses = async () => {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/forward-links?docName=source`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ localTargets: Array<{ href: string; status: string }>;
+ };
+ return Object.fromEntries(body.localTargets.map((target) => [target.href, target.status]));
+ };
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ await subscription.deliver([{ type: 'update', path: alias }]);
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+
+ await subscription.deliver([], new Error(notices[0]));
+
+ expect(readFileSync(alias, 'utf8')).toBe('one\n');
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ } finally {
+ await server.destroy();
+ }
+});
+
+test.each(['alias.csv', 'real.csv'])(
+ 'general-file links retain their disk status with %s enumerated first',
+ async (firstEntry) => {
+ vi.useRealTimers();
+ const real = writeDoc('real.csv', 'before\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ writeDoc('source.md', '# Source\n\n[Target](real.csv)\n\n[Alias](alias.csv)\n');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = firstEntry;
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ const statuses = async () => {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/forward-links?docName=source`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ localTargets: Array<{ href: string; status: string }>;
+ };
+ return Object.fromEntries(body.localTargets.map((target) => [target.href, target.status]));
+ };
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ writeFileSync(real, 'after,more,bytes\n');
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ await subscription.deliver([], new Error(notices[0]));
+ expect.soft(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ unlinkSync(alias);
+ await subscription.deliver([], new Error(notices[0]));
+ expect.soft(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'missing' });
+ const other = writeDoc('other.csv', 'other\n');
+ symlinkSync(other, alias);
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'exact' });
+ expect(readFileSync(real, 'utf8')).toBe('after,more,bytes\n');
+ unlinkSync(other);
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await statuses()).toEqual({ 'real.csv': 'exact', 'alias.csv': 'missing' });
+ } finally {
+ await server.destroy();
+ }
+ },
+);
+
+test('a public content callback can remove an observed entry before notice publication', async () => {
+ let watcher: WatcherHandle | undefined;
+ const path = join(contentDir, 'first.md');
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ if (event.kind === 'create' && event.docName === 'first') {
+ watcher?.mutateFileIndex({ kind: 'delete', path, docName: 'first' });
+ }
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ writeFileSync(path, '# First\n');
+
+ await deliverNotice(contentDir);
+
+ expect(watcher.getFileIndex().has('first')).toBe(false);
+});
+
+test('a public content callback keeps a newer same-title index update', async () => {
+ let watcher: WatcherHandle | undefined;
+ const path = join(contentDir, 'first.md');
+ const newer = '# First\n\n';
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ if (event.kind === 'create' && event.docName === 'first') {
+ writeFileSync(path, newer);
+ watcher?.mutateFileIndex({ kind: 'update', path, docName: 'first', content: newer });
+ }
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ writeFileSync(path, '# First\n');
+
+ await deliverNotice(contentDir);
+
+ expect(watcher.getFileIndex().get('first')?.size).toBe(Buffer.byteLength(newer));
+});
+
+test('notice recovery keeps the preferred mdx file for a shared document stem', async () => {
+ const mdPath = writeDoc('priority-fixture.md', '# Shadowed\n');
+ const mdxPath = writeDoc('priority-fixture.mdx', '# Preferred\n');
+ const { watcher, events } = await watchContent();
+ expect([...watcher.getFileIndex().keys()]).toEqual(['priority-fixture']);
+ expect(watcher.getFileIndex().get('priority-fixture')?.canonicalPath).toBe(mdxPath);
+ expect(watcher.getFileIndex().get('priority-fixture')?.title).toBe('Preferred');
+ expect(getDocExtension('priority-fixture')).toBe('.mdx');
+
+ writeFileSync(mdxPath, '# Updated preferred\n');
+ await deliverNotice(contentDir);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: mdxPath,
+ docName: 'priority-fixture',
+ content: '# Updated preferred\n',
+ }),
+ );
+ expect([...watcher.getFileIndex().keys()]).toEqual(['priority-fixture']);
+ expect(watcher.getFileIndex().get('priority-fixture')?.canonicalPath).toBe(mdxPath);
+ expect(watcher.getFileIndex().get('priority-fixture')?.title).toBe('Updated preferred');
+ expect(getDocExtension('priority-fixture')).toBe('.mdx');
+ expect(events.some((event) => 'path' in event && event.path === mdPath)).toBe(false);
+});
+
+test('a denied external directory read preserves known content and permits the next real recovery', async () => {
+ const guardedDir = join(contentDir, 'guarded');
+ mkdirSync(guardedDir);
+ const guardedPath = join(guardedDir, 'keep.md');
+ writeFileSync(guardedPath, '# Before\n');
+ const { watcher, events } = await watchContent();
+ expect(watcher.getFileIndex().has('guarded/keep')).toBe(true);
+ const diagnostics: unknown[] = [];
+ for (const method of ['error', 'warn'] as const) {
+ vi.spyOn(getLogger('file-watcher'), method).mockImplementation((data) => {
+ diagnostics.push(data);
+ });
+ }
+
+ deniedDirectoryRead.path = guardedDir;
+ try {
+ await deliverNotice(contentDir);
+ } finally {
+ deniedDirectoryRead.path = null;
+ }
+
+ expect.soft(watcher.getFileIndex().has('guarded/keep')).toBe(true);
+ expect
+ .soft(events.some((event) => event.kind === 'delete' && event.docName === 'guarded/keep'))
+ .toBe(false);
+ expect
+ .soft(
+ diagnostics.some((data) => {
+ if (typeof data !== 'object' || data === null) return false;
+ const record = data as { err?: unknown; code?: unknown };
+ return (
+ record.code === 'EACCES' ||
+ (record.err instanceof Error && 'code' in record.err && record.err.code === 'EACCES')
+ );
+ }),
+ )
+ .toBe(true);
+
+ writeFileSync(guardedPath, '# After\n');
+ await deliverNotice(contentDir);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: guardedPath,
+ docName: 'guarded/keep',
+ content: '# After\n',
+ }),
+ );
+ expect(watcher.getFileIndex().get('guarded/keep')?.title).toBe('After');
+});
+
+test('an overlapping notice follows an admitted content callback and preserves later disk state', async () => {
+ const entered = deferred();
+ const resume = deferred();
+ const completed: string[] = [];
+ const { watcher, events } = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'create') return;
+ if (event.docName === 'first') {
+ entered.release();
+ await resume.promise;
+ }
+ completed.push(event.docName);
+ });
+ const subscription = nativeSubscriptionOn(contentDir);
+ const firstPath = writeDoc('first.md', '# First\n');
+ const firstDelivery = subscription.deliver([{ type: 'create', path: firstPath }]);
+ await entered.promise;
+
+ const secondPath = writeDoc('second.md', '# Second\n');
+ writeDoc('third.md', '# Third\n');
+ const noticeDelivery = subscription.deliver(
+ [{ type: 'create', path: secondPath }],
+ new Error(notices[0]),
+ );
+ expect(events.filter((event) => event.kind === 'create').map((event) => event.docName)).toEqual([
+ 'first',
+ ]);
+
+ resume.release();
+ await Promise.all([firstDelivery, noticeDelivery]);
+ await vi.runAllTimersAsync();
+
+ expect(events.filter((event) => event.kind === 'create').map((event) => event.docName)).toEqual([
+ 'first',
+ 'second',
+ 'third',
+ ]);
+ expect(completed).toEqual(['first', 'second', 'third']);
+ expect([...watcher.getFileIndex().keys()].sort()).toEqual(['first', 'second', 'third']);
+});
+
+test('a supplied notice delete cannot overtake a held content callback', async () => {
+ const removed = writeDoc('removed.md', '# Removed\n');
+ const entered = deferred();
+ const resume = deferred();
+ const entries: string[] = [];
+ const completed: string[] = [];
+ const { watcher } = await watchContent(undefined, async (event) => {
+ const label =
+ event.kind === 'create' || event.kind === 'delete'
+ ? `${event.kind}:${event.docName}`
+ : event.kind;
+ entries.push(label);
+ if (label === 'create:first') {
+ entered.release();
+ await resume.promise;
+ }
+ completed.push(label);
+ });
+ const subscription = nativeSubscriptionOn(contentDir);
+ const first = writeDoc('first.md', '# First\n');
+ const firstDelivery = subscription.deliver([{ type: 'create', path: first }]);
+ await entered.promise;
+
+ unlinkSync(removed);
+ writeDoc('omitted.md', '# Omitted\n');
+ const laterDelivery = subscription.deliver(
+ [{ type: 'delete', path: removed }],
+ new Error(notices[0]),
+ );
+ await Promise.resolve();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(entries).toEqual(['create:first']);
+ expect(completed).toEqual([]);
+
+ resume.release();
+ await Promise.all([firstDelivery, laterDelivery]);
+ await vi.runAllTimersAsync();
+ expect(entries).toContain('delete:removed');
+ expect(entries).toContain('create:omitted');
+ expect(completed[0]).toBe('create:first');
+ expect(completed).toContain('delete:removed');
+ expect(completed).toContain('create:omitted');
+ expect(watcher.getFileIndex().has('removed')).toBe(false);
+ expect(watcher.getFileIndex().has('omitted')).toBe(true);
+});
+
+test('a rejected content consumer stays observable and does not poison later notice recovery', async () => {
+ const failed = new Error('content consumer rejected');
+ const diagnostics: unknown[] = [];
+ vi.spyOn(getLogger('file-watcher'), 'error').mockImplementation((data) => {
+ diagnostics.push(data.err);
+ });
+ const { watcher, events } = await watchContent(undefined, async (event) => {
+ if (event.kind === 'create' && event.docName === 'first') throw failed;
+ });
+ const firstPath = writeDoc('first.md', '# First\n');
+ await deliver(contentDir, [{ type: 'create', path: firstPath }]);
+
+ const secondPath = writeDoc('second.md', '# Second\n');
+ const thirdPath = writeDoc('third.md', '# Third\n');
+ await deliverNotice(contentDir, [{ type: 'create', path: secondPath }]);
+
+ expect.soft(diagnostics).toContain(failed);
+ expect
+ .soft(events)
+ .toContainEqual({ kind: 'create', path: secondPath, docName: 'second', content: '# Second\n' });
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: thirdPath,
+ docName: 'third',
+ content: '# Third\n',
+ });
+ expect([...watcher.getFileIndex().keys()].sort()).toEqual(['first', 'second', 'third']);
+});
+
+test('release drains an admitted notice and closes delivery before later or native-release callbacks', async () => {
+ const entered = deferred();
+ const resume = deferred();
+ const lifecycle: string[] = [];
+ const { watcher, events } = await watchContent(undefined, async (event) => {
+ if (event.kind === 'create' && event.docName === 'announced') {
+ entered.release();
+ await resume.promise;
+ lifecycle.push('consumer-completed');
+ }
+ });
+ const subscription = nativeSubscriptionOn(contentDir);
+ const announced = writeDoc('announced.md', '# Announced\n');
+ const delivery = subscription.deliver(
+ [{ type: 'create', path: announced }],
+ new Error(notices[0]),
+ );
+ const enteredBeforeDeliveryEnded = await Promise.race([
+ entered.promise.then(() => true),
+ delivery.then(() => false),
+ ]);
+ expect(enteredBeforeDeliveryEnded).toBe(true);
+
+ const queuedPath = writeDoc('queued.md', '# Queued\n');
+ const queuedDelivery = subscription.deliver(
+ [{ type: 'create', path: queuedPath }],
+ new Error(notices[0]),
+ );
+ expect(events.filter((event) => event.kind === 'create').map((event) => event.docName)).toEqual([
+ 'announced',
+ ]);
+ const duringPath = writeDoc('during.md', '# During\n');
+ subscription.deliverWhileReleasing([{ type: 'create', path: duringPath }], new Error(notices[0]));
+ const releaseSettled = vi.fn();
+ const releasing = watcher.unsubscribe().then(() => {
+ lifecycle.push('release-resolved');
+ releaseSettled();
+ });
+ await Promise.resolve();
+ expect(releaseSettled).not.toHaveBeenCalled();
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(releaseSettled).not.toHaveBeenCalled();
+ expect(lifecycle).toEqual([]);
+ resume.release();
+ await Promise.all([delivery, queuedDelivery, releasing]);
+ expect(lifecycle).toEqual(['consumer-completed', 'release-resolved']);
+
+ const settledEvents = [...events];
+ const settledIndex = [...watcher.getFileIndex().keys()];
+ const afterPath = writeDoc('after.md', '# After\n');
+ await subscription.deliver([{ type: 'create', path: afterPath }], new Error(notices[0]));
+ await vi.runAllTimersAsync();
+
+ expect(events).toEqual(settledEvents);
+ expect([...watcher.getFileIndex().keys()]).toEqual(settledIndex);
+ expect(watcher.getFileIndex().has('queued')).toBe(
+ events.some((event) => event.kind === 'create' && event.docName === 'queued'),
+ );
+ expect(
+ events.some((event) => 'docName' in event && ['during', 'after'].includes(event.docName)),
+ ).toBe(false);
+ expect(subscription.nativeReleases()).toBe(1);
+});
+
+test('Windows release closes admission without native unsubscribe after a notice', async () => {
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'win32' },
+ );
+ handles.push(watcher);
+ const subscription = nativeSubscriptionOn(contentDir);
+ await watcher.unsubscribe();
+ const late = writeDoc('late.md', '# Late\n');
+ await subscription.deliver([{ type: 'create', path: late }], new Error(notices[0]));
+
+ expect(events).toEqual([]);
+ expect(watcher.getFileIndex().has('late')).toBe(false);
+ expect(subscription.nativeReleases()).toBe(0);
+});
+
+test('an empty HEAD notice settles a same-branch OID movement', async () => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ writeFileSync(join(gitDir, 'refs', 'heads', 'main'), `${newOid}\n`);
+ await deliverNotice(gitDir);
+
+ expect(watched.ends).toEqual([
+ {
+ headMoved: true,
+ oldHead: oldOid,
+ newHead: newOid,
+ timeout: false,
+ batchKind: 'within-branch',
+ oldBranch: 'main',
+ newBranch: 'main',
+ },
+ ]);
+ expect(watched.watcher.getLastKnownBranch()).toBe('main');
+});
+
+test('an empty HEAD notice settles a detached HEAD', async () => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ writeFileSync(join(gitDir, 'HEAD'), `${newOid}\n`);
+ await deliverNotice(gitDir);
+
+ expect(watched.ends).toEqual([
+ {
+ headMoved: true,
+ oldHead: oldOid,
+ newHead: newOid,
+ timeout: false,
+ batchKind: 'detached-head',
+ oldBranch: 'main',
+ newBranch: `detached-${newOid.slice(0, 12)}`,
+ },
+ ]);
+ expect(watched.watcher.getLastKnownBranch()).toBe(`detached-${newOid.slice(0, 12)}`);
+});
+
+test('an empty HEAD notice settles an unchanged HEAD without claiming movement', async () => {
+ const gitDir = createGitDir();
+ const watched = await watchHead();
+ await deliverNotice(gitDir);
+
+ expect(watched.ends).toEqual([
+ {
+ headMoved: false,
+ oldHead: oldOid,
+ newHead: oldOid,
+ timeout: false,
+ batchKind: 'within-branch',
+ oldBranch: 'main',
+ newBranch: 'main',
+ },
+ ]);
+ expect(watched.watcher.getLastKnownBranch()).toBe('main');
+});
+
+test('repeated HEAD notices during an async begin settle one open batch before release', async () => {
+ const gitDir = createGitDir();
+ const entered = deferred();
+ const resume = deferred();
+ const watched = await watchHead(async () => {
+ entered.release();
+ await resume.promise;
+ });
+ const subscription = nativeSubscriptionOn(gitDir);
+ const headPath = join(gitDir, 'HEAD');
+ writeFileSync(headPath, 'ref: refs/heads/feature\n');
+ const firstDelivery = subscription.deliver(
+ [{ type: 'update', path: headPath }],
+ new Error(notices[0]),
+ );
+ const enteredBeforeDeliveryEnded = await Promise.race([
+ entered.promise.then(() => true),
+ firstDelivery.then(() => false),
+ ]);
+ expect(enteredBeforeDeliveryEnded).toBe(true);
+
+ const secondDelivery = subscription.deliver([], new Error(notices[0]));
+ resume.release();
+ await Promise.all([firstDelivery, secondDelivery]);
+ await vi.runAllTimersAsync();
+
+ expect(watched.begins).toEqual([{ trigger: 'HEAD' }]);
+ expect(watched.ends).toHaveLength(1);
+ expect(watched.watcher.getLastKnownBranch()).toBe('feature');
+ await watched.watcher.unsubscribe();
+ await subscription.deliver([], new Error(notices[0]));
+ await vi.runAllTimersAsync();
+ expect(watched.begins).toHaveLength(1);
+});
+
+test('a HEAD notice arriving during async settlement schedules the next disk observation', async () => {
+ const gitDir = createGitDir();
+ const endEntered = deferred();
+ const resumeEnd = deferred();
+ let endCalls = 0;
+ const completed: string[] = [];
+ const watched = await watchHead(
+ async () => {
+ completed.push('begin-completed');
+ },
+ async () => {
+ endCalls++;
+ if (endCalls === 1) {
+ endEntered.release();
+ await resumeEnd.promise;
+ }
+ completed.push('end-completed');
+ },
+ );
+ const subscription = nativeSubscriptionOn(gitDir);
+ const headPath = join(gitDir, 'HEAD');
+ writeFileSync(headPath, 'ref: refs/heads/feature\n');
+ await subscription.deliver([{ type: 'update', path: headPath }]);
+ const settlingFirst = vi.advanceTimersToNextTimerAsync();
+ await endEntered.promise;
+
+ writeFileSync(headPath, 'ref: refs/heads/main\n');
+ const noticeDelivery = subscription.deliver([], new Error(notices[0]));
+ let atRelease:
+ | {
+ begins: unknown[];
+ ends: unknown[];
+ completed: string[];
+ branch: string | null;
+ }
+ | undefined;
+ const releasing = watched.watcher.unsubscribe().then(() => {
+ atRelease = {
+ begins: [...watched.begins],
+ ends: [...watched.ends],
+ completed: [...completed],
+ branch: watched.watcher.getLastKnownBranch(),
+ };
+ });
+ resumeEnd.release();
+ await Promise.all([settlingFirst, noticeDelivery, releasing]);
+
+ expect(atRelease?.begins).toHaveLength(2);
+ expect(atRelease?.ends).toHaveLength(2);
+ expect(atRelease?.ends[1]).toEqual({
+ headMoved: true,
+ oldHead: newOid,
+ newHead: oldOid,
+ timeout: false,
+ batchKind: 'cross-branch',
+ oldBranch: 'feature',
+ newBranch: 'main',
+ });
+ expect(atRelease?.completed).toEqual([
+ 'begin-completed',
+ 'end-completed',
+ 'begin-completed',
+ 'end-completed',
+ ]);
+ expect(atRelease?.branch).toBe('main');
+ await vi.runAllTimersAsync();
+ expect({
+ begins: watched.begins,
+ ends: watched.ends,
+ completed,
+ branch: watched.watcher.getLastKnownBranch(),
+ }).toEqual(atRelease);
+ await subscription.deliver([], new Error(notices[0]));
+ await vi.runAllTimersAsync();
+ expect({
+ begins: watched.begins,
+ ends: watched.ends,
+ completed,
+ branch: watched.watcher.getLastKnownBranch(),
+ }).toEqual(atRelease);
+});
+
+async function inventoryAuditBroken(port: number, href: string): Promise<boolean> {
+ const response = await fetch(`http://127.0.0.1:${port}/api/audit`);
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ files: Array<{ diagnostics: Array<{ localTarget?: { href: string } }> }>;
+ };
+ return body.files
+ .flatMap((file) => file.diagnostics)
+ .some((diagnostic) => diagnostic.localTarget?.href === href);
+}
+
+async function inventoryForwardStatuses(port: number): Promise<Record<string, string>> {
+ const response = await fetch(`http://127.0.0.1:${port}/api/forward-links?docName=source`);
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ localTargets: Array<{ href: string; status: string }>;
+ };
+ return Object.fromEntries(body.localTargets.map((target) => [target.href, target.status]));
+}
+
+async function bootInventoryServer() {
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const server = await bootCompositionRig(contentDir);
+ await server.ready;
+ return server;
+}
+
+test.each([
+ { kind: 'markdown', action: 'add' },
+ { kind: 'markdown', action: 'remove' },
+ { kind: 'markdown', action: 'retarget' },
+ { kind: 'folder', action: 'add' },
+ { kind: 'folder', action: 'remove' },
+ { kind: 'folder', action: 'retarget' },
+ { kind: 'empty-folder', action: 'add' },
+ { kind: 'empty-folder', action: 'remove' },
+ { kind: 'empty-folder', action: 'retarget' },
+] as const)(
+ 'a completed notice reconciles a $kind alias $action in real HTTP views',
+ async ({ kind, action }) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const canonical = join(contentDir, 'canonical');
+ mkdirSync(canonical);
+ const target = kind === 'markdown' ? join(canonical, 'note.md') : canonical;
+ if (kind !== 'empty-folder') writeFileSync(join(canonical, 'note.md'), '# Note\n');
+ if (kind === 'folder') writeFileSync(join(canonical, 'data.csv'), 'data\n');
+ writeDoc('asset.csv', 'control\n');
+ const alias = join(contentDir, kind === 'markdown' ? 'linked.md' : 'linked-folder');
+ const href =
+ kind === 'markdown'
+ ? 'linked.md'
+ : kind === 'folder'
+ ? 'linked-folder/note.md'
+ : 'linked-folder/';
+ const source = `# Source\n\n[Link](${href})\n\n[Control](asset.csv)\n${kind === 'folder' ? '\n[Data](linked-folder/data.csv)\n' : ''}`;
+ const sourcePath = writeDoc('source.md', source);
+ if (action !== 'add') symlinkSync(target, alias);
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ if (kind === 'empty-folder' && action !== 'add') {
+ writeFileSync(sourcePath, source.replace('# Source', '# Source ready'));
+ await subscription.deliver([{ type: 'update', path: sourcePath }]);
+ }
+ expect(await inventoryAuditBroken(server.port, href)).toBe(action === 'add');
+ const beforeFiles = await inventoryForwardStatuses(server.port);
+ expect(beforeFiles['asset.csv']).toBe('exact');
+ if (kind === 'folder') {
+ expect(beforeFiles['linked-folder/data.csv']).toBe(action === 'add' ? 'missing' : 'exact');
+ }
+
+ if (action === 'add') {
+ symlinkSync(target, alias);
+ } else {
+ unlinkSync(alias);
+ if (action === 'retarget') {
+ const replacement = join(contentDir, 'replacement');
+ if (kind === 'folder') {
+ mkdirSync(replacement);
+ writeFileSync(join(replacement, 'data.csv'), 'replacement\n');
+ symlinkSync(replacement, alias);
+ } else {
+ symlinkSync(replacement, alias);
+ }
+ }
+ }
+
+ for (const _notice of [1, 2]) {
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await inventoryAuditBroken(server.port, href)).toBe(action !== 'add');
+ const files = await inventoryForwardStatuses(server.port);
+ expect(files['asset.csv']).toBe('exact');
+ if (kind === 'folder') {
+ expect(files['linked-folder/data.csv']).toBe(action === 'remove' ? 'missing' : 'exact');
+ }
+ }
+ if (kind !== 'empty-folder')
+ expect(readFileSync(join(canonical, 'note.md'), 'utf8')).toBe('# Note\n');
+ } finally {
+ await server.destroy();
+ }
+ },
+);
+
+test('completed recovery observes final alias maps and generation on repeated notices', async () => {
+ const canonical = writeDoc('canonical.md', '# Canonical\n');
+ const folder = join(contentDir, 'canonical-folder');
+ mkdirSync(folder);
+ writeFileSync(join(folder, 'note.md'), '# Note\n');
+ let watcher: WatcherHandle | undefined;
+ const completed: Array<{
+ generation: number;
+ markdownAlias: string | undefined;
+ folderAlias: string | undefined;
+ fileAliases: string[];
+ }> = [];
+ const options = {
+ forceBackend: 'parcel' as const,
+ platform: 'darwin' as const,
+ onRecoveryComplete: async () => {
+ if (!watcher) throw new Error('watcher not ready');
+ completed.push({
+ generation: watcher.getFileIndexGeneration(),
+ markdownAlias: watcher.getAliasMap().get('linked'),
+ folderAlias: watcher.getFolderAliasIndex().get('linked-folder'),
+ fileAliases: watcher.getFileIndex().get('canonical')?.aliases ?? [],
+ });
+ },
+ };
+ watcher = await startWatcher(contentDir, async () => {}, undefined, options);
+ handles.push(watcher);
+ const initialGeneration = watcher.getFileIndexGeneration();
+ const markdownAlias = join(contentDir, 'linked.md');
+ const folderAlias = join(contentDir, 'linked-folder');
+ symlinkSync(canonical, markdownAlias);
+ symlinkSync(folder, folderAlias);
+
+ await deliverNotice(contentDir);
+ expect(completed).toHaveLength(1);
+ expect(completed[0]).toMatchObject({
+ markdownAlias: 'canonical',
+ folderAlias: 'canonical-folder',
+ fileAliases: expect.arrayContaining(['linked']),
+ });
+ expect(completed[0].generation).toBeGreaterThan(initialGeneration);
+ expect.soft(completed[0].generation).toBe(watcher.getFileIndexGeneration());
+
+ await deliverNotice(contentDir);
+ expect(completed).toHaveLength(2);
+ expect(completed[1].generation).toBeGreaterThan(completed[0].generation);
+ expect.soft(completed[1].generation).toBe(watcher.getFileIndexGeneration());
+ expect(completed[1]).toMatchObject({
+ markdownAlias: 'canonical',
+ folderAlias: 'canonical-folder',
+ });
+
+ const other = writeDoc('other.md', '# Other\n');
+ const otherFolder = join(contentDir, 'other-folder');
+ mkdirSync(otherFolder);
+ unlinkSync(markdownAlias);
+ symlinkSync(other, markdownAlias);
+ unlinkSync(folderAlias);
+ symlinkSync(otherFolder, folderAlias);
+ await deliverNotice(contentDir);
+ expect(completed).toHaveLength(3);
+ expect(completed[2]).toMatchObject({ markdownAlias: 'other', folderAlias: 'other-folder' });
+
+ unlinkSync(markdownAlias);
+ unlinkSync(folderAlias);
+ await deliverNotice(contentDir);
+ expect(completed).toHaveLength(4);
+ expect(completed[3]).toMatchObject({ markdownAlias: undefined, folderAlias: undefined });
+ expect(readFileSync(canonical, 'utf8')).toBe('# Canonical\n');
+ expect(readFileSync(other, 'utf8')).toBe('# Other\n');
+});
+
+test('an incomplete directory observation does not report inventory completion', async () => {
+ const target = writeDoc('canonical.md', '# Canonical\n');
+ const completed: string[] = [];
+ const options = {
+ forceBackend: 'parcel' as const,
+ platform: 'darwin' as const,
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ };
+ const watcher = await startWatcher(contentDir, async () => {}, undefined, options);
+ handles.push(watcher);
+ symlinkSync(target, join(contentDir, 'linked.md'));
+ deniedDirectoryRead.path = contentDir;
+
+ await deliverNotice(contentDir);
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect(completed).toEqual([]);
+ expect(watcher.getAliasMap().has('linked')).toBe(false);
+
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect(watcher.getAliasMap().get('linked')).toBe('canonical');
+});
+
+test('notice delivery and release wait for the completed-inventory callback', async () => {
+ const target = writeDoc('canonical.md', '# Canonical\n');
+ const entered = deferred();
+ const resume = deferred();
+ const completed: string[] = [];
+ const options = {
+ forceBackend: 'parcel' as const,
+ platform: 'darwin' as const,
+ onRecoveryComplete: async () => {
+ entered.release();
+ await resume.promise;
+ completed.push('callback');
+ },
+ };
+ const watcher = await startWatcher(contentDir, async () => {}, undefined, options);
+ handles.push(watcher);
+ symlinkSync(target, join(contentDir, 'linked.md'));
+ const delivery = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ let deliverySettled = false;
+ void delivery.then(() => {
+ deliverySettled = true;
+ });
+ try {
+ const first = await Promise.race([
+ entered.promise.then(() => 'callback-entered'),
+ delivery.then(() => 'delivery-settled'),
+ ]);
+ expect(first).toBe('callback-entered');
+ expect(deliverySettled).toBe(false);
+ let releaseSettled = false;
+ const releasing = watcher.unsubscribe().then(() => {
+ releaseSettled = true;
+ });
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ expect(releaseSettled).toBe(false);
+ resume.release();
+ await Promise.all([delivery, releasing]);
+ expect(completed).toEqual(['callback']);
+ expect(deliverySettled).toBe(true);
+ expect(releaseSettled).toBe(true);
+ expect(nativeSubscriptionOn(contentDir).nativeReleases()).toBeGreaterThan(0);
+ } finally {
+ resume.release();
+ await delivery;
+ }
+});
+
+test('alias-only recovery publishes a local-targets stateless frame from the real server', async () => {
+ vi.useRealTimers();
+ mkdirSync(join(contentDir, 'canonical'));
+ const target = join(contentDir, 'canonical', 'note.md');
+ writeFileSync(target, '# Note\n');
+ writeDoc('source.md', '# Source\n\n[Link](linked.md)\n');
+ const server = await bootInventoryServer();
+ try {
+ expect(await inventoryAuditBroken(server.port, 'linked.md')).toBe(true);
+ const systemDoc = server.serverInstance.hocuspocus.documents.get('__system__');
+ expect(systemDoc).toBeDefined();
+ if (!systemDoc) throw new Error('system document unavailable');
+ const originalBroadcast = systemDoc.broadcastStateless.bind(systemDoc);
+ let resolveFrame!: () => void;
+ const frame = new Promise<void>((resolve) => {
+ resolveFrame = resolve;
+ });
+ let observingNotice = false;
+ const outbound = vi.spyOn(systemDoc, 'broadcastStateless').mockImplementation((payload) => {
+ const result = originalBroadcast(payload);
+ try {
+ if (observingNotice && (JSON.parse(payload) as { ch?: string }).ch === 'local-targets') {
+ resolveFrame();
+ }
+ } catch {
+ return result;
+ }
+ return result;
+ });
+ const signal = vi.spyOn(server.serverInstance.cc1Broadcaster, 'signal');
+ const localFrames = () =>
+ outbound.mock.calls.filter(([payload]) => {
+ try {
+ return (JSON.parse(payload) as { ch?: string }).ch === 'local-targets';
+ } catch {
+ return false;
+ }
+ }).length;
+ const previousFrames = localFrames();
+ const previousSignals = signal.mock.calls.filter(
+ ([channel]) => channel === 'local-targets',
+ ).length;
+ observingNotice = true;
+ symlinkSync(target, join(contentDir, 'linked.md'));
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(
+ signal.mock.calls.filter(([channel]) => channel === 'local-targets').length,
+ ).toBeGreaterThan(previousSignals);
+ await frame;
+ expect(localFrames()).toBeGreaterThan(previousFrames);
+ expect(await inventoryAuditBroken(server.port, 'linked.md')).toBe(false);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test.each(['markdown', 'empty-folder'] as const)(
+ 'a valid %s alias retarget keeps its real HTTP assessment exact',
+ async (kind) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const first = join(contentDir, 'first');
+ const second = join(contentDir, 'second');
+ mkdirSync(first);
+ mkdirSync(second);
+ const targetA = kind === 'markdown' ? join(first, 'note.md') : first;
+ const targetB = kind === 'markdown' ? join(second, 'note.md') : second;
+ if (kind === 'markdown') {
+ writeFileSync(targetA, '# First\n');
+ writeFileSync(targetB, '# Second\n');
+ }
+ const alias = join(contentDir, kind === 'markdown' ? 'linked.md' : 'linked-folder');
+ const href = kind === 'markdown' ? 'linked.md' : 'linked-folder/';
+ symlinkSync(targetA, alias);
+ const source = `# Source\n\n[Link](${href})\n\n[Control](asset.csv)\n`;
+ const sourcePath = writeDoc('source.md', source);
+ writeDoc('asset.csv', 'control\n');
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ if (kind === 'empty-folder') {
+ writeFileSync(sourcePath, source.replace('# Source', '# Source ready'));
+ await subscription.deliver([{ type: 'update', path: sourcePath }]);
+ }
+ expect(await inventoryAuditBroken(server.port, href)).toBe(false);
+ expect((await inventoryForwardStatuses(server.port))['asset.csv']).toBe('exact');
+ unlinkSync(alias);
+ symlinkSync(targetB, alias);
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await inventoryAuditBroken(server.port, href)).toBe(false);
+ expect((await inventoryForwardStatuses(server.port))['asset.csv']).toBe('exact');
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await inventoryAuditBroken(server.port, href)).toBe(false);
+ if (kind === 'markdown') expect(readFileSync(targetB, 'utf8')).toBe('# Second\n');
+ } finally {
+ await server.destroy();
+ }
+ },
+);
+
+test('overlapping content and HEAD notices settle the owned Git branch and alias assessment', async () => {
+ vi.useRealTimers();
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ const git = (args: string[]) =>
+ execFileSync('git', args, { cwd: contentDir, env: gitEnv, encoding: 'utf8' }).trim();
+ git(['init', '--quiet', '--initial-branch=main']);
+ git(['config', 'user.email', '[email protected]']);
+ git(['config', 'user.name', 'Notice Test']);
+ const canonical = join(contentDir, 'canonical');
+ mkdirSync(canonical);
+ writeFileSync(join(canonical, 'note.md'), '# Note\n');
+ const sourcePath = writeDoc('source.md', '# Main\n\n[Link](linked.md)\n');
+ git(['add', '-A']);
+ git(['commit', '--quiet', '-m', 'main state']);
+ git(['checkout', '--quiet', '-b', 'feature']);
+ writeFileSync(sourcePath, '# Feature\n\n[Link](linked.md)\n');
+ git(['add', '-A']);
+ git(['commit', '--quiet', '-m', 'feature state']);
+ git(['checkout', '--quiet', 'main']);
+ const server = await bootCompositionRig(contentDir);
+ const entered = deferred();
+ const resume = deferred();
+ let contentNotice: Promise<void> | undefined;
+ let headNotice: Promise<void> | undefined;
+ try {
+ await server.ready;
+ expect(await inventoryAuditBroken(server.port, 'linked.md')).toBe(true);
+ const broadcaster = server.serverInstance.cc1Broadcaster;
+ const originalEmit = broadcaster.emitBranchSwitched.bind(broadcaster);
+ let resolveBranch!: (branch: string) => void;
+ const branchSettled = new Promise<string>((resolve) => {
+ resolveBranch = resolve;
+ });
+ vi.spyOn(broadcaster, 'emitBranchSwitched').mockImplementation((branch) => {
+ originalEmit(branch);
+ resolveBranch(branch);
+ });
+
+ symlinkSync(join(canonical, 'note.md'), join(contentDir, 'linked.md'));
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ contentNotice = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const scanEntered = await Promise.race([
+ entered.promise.then(() => true),
+ contentNotice.then(() => false),
+ ]);
+ expect(scanEntered).toBe(true);
+ git(['checkout', '--quiet', 'feature']);
+ headNotice = nativeSubscriptionOn(join(contentDir, '.git')).deliver([], new Error(notices[0]));
+ resume.release();
+ await Promise.all([contentNotice, headNotice]);
+ expect(await branchSettled).toBe('feature');
+ expect(git(['branch', '--show-current'])).toBe('feature');
+ expect(readFileSync(sourcePath, 'utf8')).toContain('# Feature');
+ const documentResponse = await fetch(
+ `http://127.0.0.1:${server.port}/api/document?docName=source`,
+ );
+ expect(documentResponse.status).toBe(200);
+ const document = (await documentResponse.json()) as { content: string };
+ expect(document.content).toContain('# Feature');
+ expect(await inventoryAuditBroken(server.port, 'linked.md')).toBe(false);
+ } finally {
+ resume.release();
+ await Promise.allSettled([contentNotice, headNotice].filter((value) => value !== undefined));
+ await server.destroy();
+ }
+});
+
+test.each(['realpath', 'stat'] as const)(
+ 'an unreadable former alias target during %s preserves later records and known state',
+ async (operation) => {
+ const blocked = join(contentDir, 'blocked');
+ mkdirSync(blocked);
+ const prior = writeDoc('blocked/real.csv', 'prior\n');
+ const other = writeDoc('other.csv', 'other,more\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(prior, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const priorStat = statSync(prior);
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const logger = getLogger('file-watcher');
+ const warnings = vi.spyOn(logger, 'warn');
+ const errors = vi.spyOn(logger, 'error');
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(indexedAliasOwner(watcher, 'alias.csv')?.canonicalPath).toBe(prior);
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ const later = writeDoc('later.csv', 'later\n');
+ denyAdmission(operation, prior);
+ deniedDirectoryRead.path = blocked;
+
+ await deliverNotice(contentDir, [
+ { type: 'update', path: alias },
+ { type: 'create', path: later },
+ ]);
+
+ expect(admissionFault.observed).toBe(true);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: later, relativePath: 'later.csv' }),
+ );
+ expect.soft(Boolean(indexedRow(watcher, 'later.csv', 'file'))).toBe(true);
+ expect.soft(deniedDirectoryRead.path).toBeNull();
+ expect(completed).toEqual([]);
+ const priorEntries = indexedIdentityRows(watcher).filter(
+ (entry) => entry.canonicalPath === prior,
+ );
+ expect(priorEntries).toHaveLength(1);
+ expect(priorEntries[0]).toMatchObject({
+ size: priorStat.size,
+ modified: priorStat.mtime.toISOString(),
+ inode: Number(priorStat.ino),
+ });
+ const diagnostic = JSON.stringify([...warnings.mock.calls, ...errors.mock.calls]);
+ expect(diagnostic).toContain('EACCES');
+ expect(diagnostic).toContain(JSON.stringify(prior).slice(1, -1));
+ expect(
+ events.filter((event) => event.kind === 'file-delete' || event.kind === 'delete'),
+ ).toEqual([]);
+
+ clearAdmissionDenial();
+ deniedDirectoryRead.path = null;
+ writeFileSync(prior, 'restored,prior,content\n');
+ await deliverNotice(contentDir);
+
+ expect(completed).toEqual(['complete']);
+ const entries = indexedIdentityRows(watcher);
+ expect(entries.filter((entry) => entry.canonicalPath === prior)).toHaveLength(1);
+ expect(entries.find((entry) => entry.canonicalPath === prior)?.size).toBe(
+ Buffer.byteLength('restored,prior,content\n'),
+ );
+ expect(entries.filter((entry) => entry.canonicalPath === other)).toHaveLength(1);
+ expect(entries.find((entry) => entry.canonicalPath === other)?.aliases).toContain('alias.csv');
+ expect(Boolean(indexedRow(watcher, 'later.csv', 'file'))).toBe(true);
+ expect(
+ events.filter(
+ (event) => event.kind === 'file-delete' && [prior, other, later].includes(event.path),
+ ),
+ ).toEqual([]);
+ },
+);
+
+test('an unreadable former alias target retains readable sibling HTTP links', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const blocked = join(contentDir, 'blocked');
+ mkdirSync(blocked);
+ const prior = writeDoc('blocked/real.csv', 'prior\n');
+ const other = writeDoc('other.csv', 'other\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(prior, alias);
+ writeDoc(
+ 'source.md',
+ '# Source\n\n[Former](blocked/real.csv)\n\n[Alias](alias.csv)\n\n[Later](later.csv)\n',
+ );
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const server = await bootInventoryServer();
+ try {
+ expect(await inventoryForwardStatuses(server.port)).toEqual({
+ 'blocked/real.csv': 'exact',
+ 'alias.csv': 'exact',
+ 'later.csv': 'missing',
+ });
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ const later = writeDoc('later.csv', 'later\n');
+ denyAdmission('realpath', prior);
+ deniedDirectoryRead.path = blocked;
+ const subscription = nativeSubscriptionOn(contentDir);
+
+ await subscription.deliver(
+ [
+ { type: 'update', path: alias },
+ { type: 'create', path: later },
+ ],
+ new Error(notices[0]),
+ );
+
+ expect(admissionFault.observed).toBe(true);
+ expect(readFileSync(later, 'utf8')).toBe('later\n');
+ expect.soft(await inventoryForwardStatuses(server.port)).toEqual({
+ 'blocked/real.csv': 'exact',
+ 'alias.csv': 'exact',
+ 'later.csv': 'exact',
+ });
+ clearAdmissionDenial();
+ deniedDirectoryRead.path = null;
+ await subscription.deliver([], new Error(notices[0]));
+ expect(await inventoryForwardStatuses(server.port)).toEqual({
+ 'blocked/real.csv': 'exact',
+ 'alias.csv': 'exact',
+ 'later.csv': 'exact',
+ });
+ } finally {
+ clearAdmissionDenial();
+ deniedDirectoryRead.path = null;
+ await server.destroy();
+ }
+});
+
+test.each([
+ ['before', 'original'],
+ ['during', 'original'],
+ ['before', 'changed'],
+ ['during', 'changed'],
+] as const)(
+ 'public recreation %s recovery with %s bytes preserves the next rename lifecycle',
+ async (timing, bytes) => {
+ vi.useRealTimers();
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const originalBytes = '# Original\n\nEarlier bytes.\n';
+ const recreatedBytes =
+ bytes === 'original' ? originalBytes : '# Recreated\n\nDifferent bytes now.\n';
+ mkdirSync(join(contentDir, '.ok', 'templates'), { recursive: true });
+ writeFileSync(join(contentDir, '.ok', 'templates', 'recreated.md'), recreatedBytes);
+ const first = writeDoc('first.md', '# First\n\nSeparate content.\n');
+ const later = writeDoc('later.md', originalBytes);
+ const moved = join(contentDir, 'moved.md');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'first.md';
+ let server: Awaited<ReturnType<typeof bootCompositionRig>> | undefined;
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ let armed = false;
+ let hookCount = 0;
+ let recreationCount = 0;
+ try {
+ server = await bootCompositionRig(contentDir);
+ await server.ready;
+ const active = server;
+ const firstConnection = await active.serverInstance.hocuspocus.openDirectConnection('first');
+ connections.push(firstConnection);
+ const laterConnection = await active.serverInstance.hocuspocus.openDirectConnection('later');
+ connections.push(laterConnection);
+ const lifecycle = laterConnection.document.getMap('lifecycle');
+ expect(laterConnection.document.getText('source').toString()).toBe(originalBytes);
+ const recreate = async () => {
+ const response = await fetch(`http://127.0.0.1:${active.port}/api/create-page`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ path: 'later.md', template: 'recreated' }),
+ });
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ docName: 'later' });
+ expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);
+ recreationCount += 1;
+ };
+ active.serverInstance.hocuspocus.configuration.extensions.push({
+ async afterUnloadDocument({ documentName }: { documentName: string }) {
+ if (!armed || documentName !== 'first') return;
+ hookCount += 1;
+ if (timing === 'during') await recreate();
+ },
+ });
+ const subscription = nativeSubscriptionOn(contentDir);
+ unlinkSync(first);
+ unlinkSync(later);
+ expect(existsSync(first)).toBe(false);
+ expect(existsSync(later)).toBe(false);
+ if (timing === 'before') await recreate();
+ armed = true;
+ await subscription.deliver([], new Error(notices[0]));
+ armed = false;
+ expect(hookCount).toBe(1);
+ expect(recreationCount).toBe(1);
+ expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);
+ expect(lifecycle.get('status')).toBeUndefined();
+ expect(lifecycle.get('newPath')).toBeUndefined();
+ const ringPath = (name: string) => `.../${basename(contentDir)}/${name}`;
+ expect(
+ getWatcherDecisionRingSnapshot().filter(
+ (entry) => entry.decision === 'dispatched' && entry.path === ringPath('later.md'),
+ ),
+ ).toEqual([]);
+ const afterRecoveryResponse = await fetch(`http://127.0.0.1:${active.port}/api/documents`);
+ expect(afterRecoveryResponse.status).toBe(200);
+ const afterRecovery = (await afterRecoveryResponse.json()) as {
+ documents: Array<{ docName: string }>;
+ };
+ expect(afterRecovery.documents.map((document) => document.docName)).toContain('later');
+ expect(afterRecovery.documents.map((document) => document.docName)).not.toContain('first');
+
+ const beforeMove = readFileSync(later, 'utf8');
+ renameSync(later, moved);
+ expect(existsSync(later)).toBe(false);
+ expect(readFileSync(moved, 'utf8')).toBe(beforeMove);
+ await subscription.deliver([
+ { type: 'delete', path: later },
+ { type: 'create', path: moved },
+ ]);
+ const dispatched = getWatcherDecisionRingSnapshot()
+ .filter(
+ (entry) =>
+ entry.decision === 'dispatched' &&
+ (entry.path === ringPath('later.md') || entry.path === ringPath('moved.md')),
+ )
+ .map((entry) => entry.kind);
+ const inventoryResponse = await fetch(`http://127.0.0.1:${active.port}/api/documents`);
+ const movedResponse = await fetch(
+ `http://127.0.0.1:${active.port}/api/document?docName=moved`,
+ );
+ expect.soft(inventoryResponse.status).toBe(200);
+ const inventory = (await inventoryResponse.json()) as {
+ documents: Array<{ docName: string }>;
+ };
+ expect.soft(inventory.documents.map((document) => document.docName)).toContain('moved');
+ expect.soft(inventory.documents.map((document) => document.docName)).not.toContain('later');
+ expect.soft(movedResponse.status).toBe(200);
+ const movedDocument = (await movedResponse.json()) as { content: string };
+ expect.soft(movedDocument.content).toBe(recreatedBytes);
+ expect.soft(dispatched).toEqual(['rename']);
+ expect.soft(lifecycle.get('status')).toBe('renamed');
+ expect.soft(lifecycle.get('newPath')).toBe('moved');
+ } finally {
+ armed = false;
+ try {
+ await Promise.all(connections.map((connection) => connection.disconnect()));
+ } finally {
+ try {
+ await server?.destroy();
+ } finally {
+ const dirs = nativeSubscriptionDirs();
+ const releases = dirs.map((dir) => nativeSubscriptionOn(dir).nativeReleases());
+ rmSync(contentDir, { recursive: true, force: true });
+ expect(existsSync(contentDir)).toBe(false);
+ expect(dirs).toHaveLength(2);
+ expect(releases).toEqual([1, 1]);
+ }
+ }
+ }
+ },
+);
+
+test.each(['before', 'during'] as const)(
+ 'a supplied later delete follows %s-notice public recreation and the completed scan restores inventory',
+ async (timing) => {
+ vi.useRealTimers();
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ execFileSync('git', ['init', '--quiet', '--initial-branch=main'], {
+ cwd: contentDir,
+ env: gitEnv,
+ });
+ const recreatedBytes = '# Recreated\n\nContent after the supplied deletes.\n';
+ mkdirSync(join(contentDir, '.ok', 'templates'), { recursive: true });
+ writeFileSync(join(contentDir, '.ok', 'templates', 'recreated.md'), recreatedBytes);
+ const first = writeDoc('first.md', '# First\n');
+ const later = writeDoc('later.md', '# Earlier later\n');
+ let server: Awaited<ReturnType<typeof bootCompositionRig>> | undefined;
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ const phases: string[] = [];
+ let armed = false;
+ let recreations = 0;
+ try {
+ server = await bootCompositionRig(contentDir);
+ await server.ready;
+ const active = server;
+ connections.push(await active.serverInstance.hocuspocus.openDirectConnection('first'));
+ connections.push(await active.serverInstance.hocuspocus.openDirectConnection('later'));
+ const recreate = async () => {
+ const response = await fetch(`http://127.0.0.1:${active.port}/api/create-page`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ path: 'later.md', template: 'recreated' }),
+ });
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ docName: 'later' });
+ expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);
+ recreations += 1;
+ phases.push('recreated');
+ };
+ active.serverInstance.hocuspocus.configuration.extensions.push({
+ async afterUnloadDocument({ documentName }: { documentName: string }) {
+ if (!armed) return;
+ if (documentName === 'first') {
+ phases.push('first-unloaded');
+ if (timing === 'during') await recreate();
+ } else if (documentName === 'later') {
+ phases.push('later-unloaded');
+ }
+ },
+ });
+ unlinkSync(first);
+ unlinkSync(later);
+ expect(existsSync(first)).toBe(false);
+ expect(existsSync(later)).toBe(false);
+ if (timing === 'before') await recreate();
+ armed = true;
+ await nativeSubscriptionOn(contentDir).deliver(
+ [
+ { type: 'delete', path: first },
+ { type: 'delete', path: later },
+ ],
+ new Error(notices[0]),
+ );
+ armed = false;
+ expect(phases).toEqual(
+ timing === 'before'
+ ? ['recreated', 'first-unloaded', 'later-unloaded']
+ : ['first-unloaded', 'recreated', 'later-unloaded'],
+ );
+ expect(recreations).toBe(1);
+ expect(readFileSync(later, 'utf8')).toBe(recreatedBytes);
+ const inventoryResponse = await fetch(`http://127.0.0.1:${active.port}/api/documents`);
+ expect(inventoryResponse.status).toBe(200);
+ const inventory = (await inventoryResponse.json()) as {
+ documents: Array<{ docName: string }>;
+ };
+ expect.soft(inventory.documents.map((document) => document.docName)).toContain('later');
+ const contentResponse = await fetch(
+ `http://127.0.0.1:${active.port}/api/document?docName=later`,
+ );
+ expect.soft(contentResponse.status).toBe(200);
+ const content = (await contentResponse.json()) as { content: string };
+ expect.soft(content.content).toBe(recreatedBytes);
+ } finally {
+ armed = false;
+ try {
+ await Promise.all(connections.map((connection) => connection.disconnect()));
+ } finally {
+ try {
+ await server?.destroy();
+ } finally {
+ const dirs = nativeSubscriptionDirs();
+ const releases = dirs.map((dir) => nativeSubscriptionOn(dir).nativeReleases());
+ rmSync(contentDir, { recursive: true, force: true });
+ expect(existsSync(contentDir)).toBe(false);
+ expect(dirs).toHaveLength(2);
+ expect(releases).toEqual([1, 1]);
+ }
+ }
+ }
+ },
+);
+
+test('a public file created during directory observation keeps its next rename identity', async () => {
+ const { watcher, events } = await watchContent();
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ const created = writeDoc('observed-later.md', '# Created during observation\n');
+ watcher.mutateFileIndex({
+ kind: 'create',
+ path: created,
+ docName: 'observed-later',
+ content: '# Created during observation\n',
+ });
+ expect(watcher.getFileIndex().get('observed-later')?.canonicalPath).toBe(created);
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(events).toEqual([]);
+ expect(readFileSync(created, 'utf8')).toBe('# Created during observation\n');
+ expect(watcher.getFileIndex().get('observed-later')?.canonicalPath).toBe(created);
+
+ const moved = join(contentDir, 'observed-moved.md');
+ renameSync(created, moved);
+ expect(readFileSync(moved, 'utf8')).toBe('# Created during observation\n');
+ await deliver(contentDir, [
+ { type: 'delete', path: created },
+ { type: 'create', path: moved },
+ ]);
+ expect(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: created,
+ newPath: moved,
+ oldDocName: 'observed-later',
+ newDocName: 'observed-moved',
+ content: '# Created during observation\n',
+ },
+ ]);
+ expect(watcher.getFileIndex().has('observed-later')).toBe(false);
+ expect(watcher.getFileIndex().get('observed-moved')?.canonicalPath).toBe(moved);
+ } finally {
+ resume.release();
+ await pending;
+ }
+});
+
+test('two public updates during a captured classification read keep the latest rename identity', async () => {
+ const path = writeDoc('changing.md', '# Initial\n');
+ const { watcher, events } = await watchContent();
+ const entered = deferred();
+ const resume = deferred();
+ const observed = '# Observed externally\n';
+ const newer = '# Newer publicly\n';
+ const latest = '# Latest publicly\n';
+ classificationReadSchedule.path = path;
+ classificationReadSchedule.holdRead = 2;
+ classificationReadSchedule.entered = entered.release;
+ classificationReadSchedule.resume = resume.promise;
+ writeFileSync(path, observed);
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ expect(classificationReadSchedule.seen).toEqual([observed, observed]);
+ expect(classificationReadSchedule.captured).toBe(observed);
+ writeFileSync(path, newer);
+ watcher.mutateFileIndex({ kind: 'update', path, docName: 'changing', content: newer });
+ writeFileSync(path, latest);
+ watcher.mutateFileIndex({ kind: 'update', path, docName: 'changing', content: latest });
+ expect(watcher.getFileIndex().get('changing')?.size).toBe(Buffer.byteLength(latest));
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(readFileSync(path, 'utf8')).toBe(latest);
+ expect(watcher.getFileIndex().get('changing')?.size).toBe(Buffer.byteLength(latest));
+ expect(events).toEqual([]);
+
+ const moved = join(contentDir, 'changed-moved.md');
+ renameSync(path, moved);
+ expect(readFileSync(moved, 'utf8')).toBe(latest);
+ await deliver(contentDir, [
+ { type: 'delete', path },
+ { type: 'create', path: moved },
+ ]);
+ expect(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: path,
+ newPath: moved,
+ oldDocName: 'changing',
+ newDocName: 'changed-moved',
+ content: latest,
+ },
+ ]);
+ expect(watcher.getFileIndex().get('changed-moved')?.canonicalPath).toBe(moved);
+ } finally {
+ resume.release();
+ await pending;
+ }
+});
+
+test.each(['before', 'during'] as const)(
+ 'a public rename %s recovery preserves both old-path creation and destination rename',
+ async (timing) => {
+ const trigger = writeDoc('rename-trigger.md', '# Trigger\n');
+ const source = writeDoc('rename-source.md', '# Moved publicly\n');
+ const destination = join(contentDir, 'rename-destination.md');
+ const third = join(contentDir, 'rename-third.md');
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle | undefined;
+ let publicRenames = 0;
+ const publiclyRename = () => {
+ renameSync(source, destination);
+ watcher?.mutateFileIndex({
+ kind: 'rename',
+ oldPath: source,
+ newPath: destination,
+ oldDocName: 'rename-source',
+ newDocName: 'rename-destination',
+ content: '# Moved publicly\n',
+ });
+ publicRenames += 1;
+ };
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (timing === 'during' && event.kind === 'delete' && event.docName === 'rename-trigger') {
+ publiclyRename();
+ }
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ if (timing === 'before') publiclyRename();
+ unlinkSync(trigger);
+ await deliverNotice(contentDir);
+ expect(publicRenames).toBe(1);
+ expect(existsSync(source)).toBe(false);
+ expect(readFileSync(destination, 'utf8')).toBe('# Moved publicly\n');
+ expect(watcher.getFileIndex().has('rename-source')).toBe(false);
+ expect(watcher.getFileIndex().get('rename-destination')?.canonicalPath).toBe(destination);
+ events.length = 0;
+
+ writeFileSync(source, '# Distinct recreated source\n');
+ renameSync(destination, third);
+ expect(readFileSync(source, 'utf8')).toBe('# Distinct recreated source\n');
+ expect(readFileSync(third, 'utf8')).toBe('# Moved publicly\n');
+ await deliver(contentDir, [
+ { type: 'create', path: source },
+ { type: 'delete', path: destination },
+ { type: 'create', path: third },
+ ]);
+ expect(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: destination,
+ newPath: third,
+ oldDocName: 'rename-destination',
+ newDocName: 'rename-third',
+ content: '# Moved publicly\n',
+ },
+ {
+ kind: 'create',
+ path: source,
+ docName: 'rename-source',
+ content: '# Distinct recreated source\n',
+ },
+ ]);
+ expect(watcher.getFileIndex().get('rename-source')?.canonicalPath).toBe(source);
+ expect(watcher.getFileIndex().get('rename-third')?.canonicalPath).toBe(third);
+ },
+);
+
+test('a public delete after a recovery-time upsert leaves the next external create new', async () => {
+ const { watcher, events } = await watchContent();
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ const path = writeDoc('transient.md', '# Public transient\n');
+ watcher.mutateFileIndex({
+ kind: 'create',
+ path,
+ docName: 'transient',
+ content: '# Public transient\n',
+ });
+ expect(watcher.getFileIndex().has('transient')).toBe(true);
+ unlinkSync(path);
+ watcher.mutateFileIndex({ kind: 'delete', path, docName: 'transient' });
+ expect(existsSync(path)).toBe(false);
+ expect(watcher.getFileIndex().has('transient')).toBe(false);
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(events).toEqual([]);
+ expect(watcher.getFileIndex().has('transient')).toBe(false);
+ expect(existsSync(path)).toBe(false);
+
+ writeFileSync(path, '# Externally new and different\n');
+ await deliver(contentDir, [{ type: 'create', path }]);
+ expect(events).toEqual([
+ {
+ kind: 'create',
+ path,
+ docName: 'transient',
+ content: '# Externally new and different\n',
+ },
+ ]);
+ expect(watcher.getFileIndex().get('transient')?.canonicalPath).toBe(path);
+ } finally {
+ resume.release();
+ await pending;
+ }
+});
+
+test('a public recreation survives a rejected recovery consumer and later notices still run', async () => {
+ const first = writeDoc('failed-first.md', '# First\n');
+ const later = writeDoc('failed-later.md', '# Original\n');
+ const moved = join(contentDir, 'failed-moved.md');
+ const failure = new Error('public recreation consumer rejected');
+ const errors = vi.spyOn(getLogger('file-watcher'), 'error');
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ let watcher: WatcherHandle | undefined;
+ let recreated = false;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'failed-first') return;
+ writeFileSync(later, '# Publicly recreated after failure\n');
+ watcher?.mutateFileIndex({
+ kind: 'create',
+ path: later,
+ docName: 'failed-later',
+ content: '# Publicly recreated after failure\n',
+ });
+ recreated = true;
+ throw failure;
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ unlinkSync(first);
+ unlinkSync(later);
+ await deliverNotice(contentDir);
+ expect(recreated).toBe(true);
+ expect(errors.mock.calls.some(([detail]) => detail.err === failure)).toBe(true);
+ expect(completed).toEqual([]);
+ expect(readFileSync(later, 'utf8')).toBe('# Publicly recreated after failure\n');
+ expect(watcher.getFileIndex().get('failed-later')?.canonicalPath).toBe(later);
+ events.length = 0;
+
+ renameSync(later, moved);
+ expect(readFileSync(moved, 'utf8')).toBe('# Publicly recreated after failure\n');
+ await deliver(contentDir, [
+ { type: 'delete', path: later },
+ { type: 'create', path: moved },
+ ]);
+ expect.soft(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: later,
+ newPath: moved,
+ oldDocName: 'failed-later',
+ newDocName: 'failed-moved',
+ content: '# Publicly recreated after failure\n',
+ },
+ ]);
+ const omitted = writeDoc('failure-omitted.md', '# Omitted after failure\n');
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: omitted,
+ docName: 'failure-omitted',
+ content: '# Omitted after failure\n',
+ });
+ expect(watcher.getFileIndex().get('failure-omitted')?.canonicalPath).toBe(omitted);
+});
+
+test('an incomplete directory observation retains a concurrent public write for its next rename', async () => {
+ const blocked = join(contentDir, 'blocked');
+ mkdirSync(blocked);
+ writeDoc('blocked/known.md', '# Known\n');
+ const completed: string[] = [];
+ const events: DiskEvent[] = [];
+ const logger = getLogger('file-watcher');
+ const warnings = vi.spyOn(logger, 'warn');
+ const errors = vi.spyOn(logger, 'error');
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ const created = writeDoc('incomplete-public.md', '# Public during incomplete scan\n');
+ watcher.mutateFileIndex({
+ kind: 'create',
+ path: created,
+ docName: 'incomplete-public',
+ content: '# Public during incomplete scan\n',
+ });
+ deniedDirectoryRead.path = blocked;
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect(JSON.stringify([...warnings.mock.calls, ...errors.mock.calls])).toContain('EACCES');
+ expect(completed).toEqual([]);
+ expect(readFileSync(created, 'utf8')).toBe('# Public during incomplete scan\n');
+ expect(watcher.getFileIndex().get('incomplete-public')?.canonicalPath).toBe(created);
+ expect(watcher.getFileIndex().has('blocked/known')).toBe(true);
+ expect(events).toEqual([]);
+
+ const moved = join(contentDir, 'incomplete-moved.md');
+ renameSync(created, moved);
+ expect(readFileSync(moved, 'utf8')).toBe('# Public during incomplete scan\n');
+ await deliver(contentDir, [
+ { type: 'delete', path: created },
+ { type: 'create', path: moved },
+ ]);
+ expect.soft(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: created,
+ newPath: moved,
+ oldDocName: 'incomplete-public',
+ newDocName: 'incomplete-moved',
+ content: '# Public during incomplete scan\n',
+ },
+ ]);
+ const omitted = writeDoc('after-incomplete.md', '# Later complete scan\n');
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect(watcher.getFileIndex().get('after-incomplete')?.canonicalPath).toBe(omitted);
+ } finally {
+ deniedDirectoryRead.path = null;
+ resume.release();
+ await pending;
+ }
+});
+
+test('a public write in the awaited recovery-complete callback keeps its next rename identity', async () => {
+ const entered = deferred();
+ const resume = deferred();
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const created = join(contentDir, 'completed-public.md');
+ let watcher: WatcherHandle | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ entered.release();
+ await resume.promise;
+ writeFileSync(created, '# Written at completion\n');
+ watcher?.mutateFileIndex({
+ kind: 'create',
+ path: created,
+ docName: 'completed-public',
+ content: '# Written at completion\n',
+ });
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ expect(completed).toEqual([]);
+ expect(existsSync(created)).toBe(false);
+ expect(watcher.getFileIndex().has('completed-public')).toBe(false);
+ const deliveryEndedBeforeRelease = await Promise.race([
+ pending.then(() => true),
+ new Promise<boolean>((resolve) => setImmediate(() => resolve(false))),
+ ]);
+ expect(deliveryEndedBeforeRelease).toBe(false);
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(completed).toEqual(['complete']);
+ expect(readFileSync(created, 'utf8')).toBe('# Written at completion\n');
+ expect(watcher.getFileIndex().get('completed-public')?.canonicalPath).toBe(created);
+ expect(events).toEqual([]);
+
+ const moved = join(contentDir, 'completed-moved.md');
+ renameSync(created, moved);
+ expect(readFileSync(moved, 'utf8')).toBe('# Written at completion\n');
+ await deliver(contentDir, [
+ { type: 'delete', path: created },
+ { type: 'create', path: moved },
+ ]);
+ expect(events).toEqual([
+ {
+ kind: 'rename',
+ oldPath: created,
+ newPath: moved,
+ oldDocName: 'completed-public',
+ newDocName: 'completed-moved',
+ content: '# Written at completion\n',
+ },
+ ]);
+ expect(watcher.getFileIndex().get('completed-moved')?.canonicalPath).toBe(moved);
+ } finally {
+ resume.release();
+ await pending;
+ }
+});
+
+test.each(['outside', 'after-complete', 'after-failed'] as const)(
+ 'a public index-only write %s recovery remains a first ordinary create',
+ async (phase) => {
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ let failedCallbacks = 0;
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (
+ phase === 'after-failed' &&
+ event.kind === 'create' &&
+ event.docName === 'failure-trigger'
+ ) {
+ failedCallbacks += 1;
+ throw new Error('ordinary control failed notice');
+ }
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ if (phase === 'after-complete') {
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ } else if (phase === 'after-failed') {
+ writeDoc('failure-trigger.md', '# Trigger\n');
+ await deliverNotice(contentDir);
+ expect(failedCallbacks).toBe(1);
+ expect(completed).toEqual([]);
+ }
+ events.length = 0;
+ const path = writeDoc('ordinary-public.md', '# Public index only\n');
+ watcher.mutateFileIndex({
+ kind: 'create',
+ path,
+ docName: 'ordinary-public',
+ content: '# Public index only\n',
+ });
+ expect(watcher.getFileIndex().get('ordinary-public')?.canonicalPath).toBe(path);
+ await deliver(contentDir, [{ type: 'create', path }]);
+ expect(events).toEqual([
+ {
+ kind: 'create',
+ path,
+ docName: 'ordinary-public',
+ content: '# Public index only\n',
+ },
+ ]);
+ },
+);
+
+test('a rejected reserved public mutation during recovery leaves its first classification new', async () => {
+ const { watcher, events } = await watchContent();
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ const reserved = writeDoc('__system__.md', '# Reserved on disk\n');
+ watcher.mutateFileIndex({
+ kind: 'create',
+ path: reserved,
+ docName: '__system__',
+ content: '# Reserved on disk\n',
+ });
+ expect(watcher.getFileIndex().has('__system__')).toBe(false);
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(events).toEqual([]);
+ expect(watcher.getFileIndex().has('__system__')).toBe(false);
+ expect(readFileSync(reserved, 'utf8')).toBe('# Reserved on disk\n');
+ expect(await classifyEvents([{ type: 'create', path: reserved }], contentDir)).toEqual([
+ {
+ kind: 'create',
+ path: reserved,
+ docName: '__system__',
+ content: '# Reserved on disk\n',
+ },
+ ]);
+ } finally {
+ resume.release();
+ await pending;
+ }
+});
+
+test('a public index-only write inside an ordinary consumer keeps its first create ordinary', async () => {
+ const events: DiskEvent[] = [];
+ const created = join(contentDir, 'ordinary-callback-public.md');
+ let watcher: WatcherHandle | undefined;
+ let callbacks = 0;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'create' || event.docName !== 'ordinary-callback-trigger') return;
+ callbacks += 1;
+ writeFileSync(created, '# Public from ordinary callback\n');
+ watcher?.mutateFileIndex({
+ kind: 'create',
+ path: created,
+ docName: 'ordinary-callback-public',
+ content: '# Public from ordinary callback\n',
+ });
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ const trigger = writeDoc('ordinary-callback-trigger.md', '# Trigger\n');
+ await deliver(contentDir, [{ type: 'create', path: trigger }]);
+ expect(callbacks).toBe(1);
+ expect(readFileSync(created, 'utf8')).toBe('# Public from ordinary callback\n');
+ expect(watcher.getFileIndex().get('ordinary-callback-public')?.canonicalPath).toBe(created);
+ events.length = 0;
+
+ await deliver(contentDir, [{ type: 'create', path: created }]);
+ expect(events).toEqual([
+ {
+ kind: 'create',
+ path: created,
+ docName: 'ordinary-callback-public',
+ content: '# Public from ordinary callback\n',
+ },
+ ]);
+});
+
+test('a public delete during recovery removes a previously indexed file identity', async () => {
+ const target = writeDoc('known-delete-target.md', '# Known at startup\n');
+ const trigger = writeDoc('known-delete-trigger.md', '# Trigger\n');
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const phases: string[] = [];
+ let callbackCount = 0;
+ let watcher: WatcherHandle | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'known-delete-trigger') return;
+ callbackCount += 1;
+ writeFileSync(target, '# Public update before deletion\n');
+ watcher?.mutateFileIndex({
+ kind: 'update',
+ path: target,
+ docName: 'known-delete-target',
+ content: '# Public update before deletion\n',
+ });
+ expect(readFileSync(target, 'utf8')).toBe('# Public update before deletion\n');
+ phases.push('updated');
+ unlinkSync(target);
+ watcher?.mutateFileIndex({ kind: 'delete', path: target, docName: 'known-delete-target' });
+ phases.push('deleted');
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(readFileSync(target, 'utf8')).toBe('# Known at startup\n');
+ expect(watcher.getFileIndex().get('known-delete-target')?.canonicalPath).toBe(target);
+ unlinkSync(trigger);
+
+ await deliverNotice(contentDir);
+
+ expect(callbackCount).toBe(1);
+ expect(phases).toEqual(['updated', 'deleted']);
+ expect(completed).toEqual(['complete']);
+ expect(existsSync(target)).toBe(false);
+ expect(watcher.getFileIndex().has('known-delete-target')).toBe(false);
+ expect(
+ events.filter((event) => 'docName' in event && event.docName === 'known-delete-target'),
+ ).toEqual([]);
+ events.length = 0;
+
+ writeFileSync(target, '# Externally recreated with distinct bytes\n');
+ expect(readFileSync(target, 'utf8')).toBe('# Externally recreated with distinct bytes\n');
+ await deliver(contentDir, [{ type: 'create', path: target }]);
+
+ expect.soft(events).toEqual([
+ {
+ kind: 'create',
+ path: target,
+ docName: 'known-delete-target',
+ content: '# Externally recreated with distinct bytes\n',
+ },
+ ]);
+ expect(watcher.getFileIndex().get('known-delete-target')?.canonicalPath).toBe(target);
+ expect(readFileSync(target, 'utf8')).toBe('# Externally recreated with distinct bytes\n');
+});
+
+function indexedRow(watcher: WatcherHandle, name: string, kind: 'markdown' | 'file') {
+ return indexedIdentityRows(watcher).find((entry) => entry.name === name && entry.kind === kind);
+}
+
+function indexedAliasOwner(watcher: WatcherHandle, alias: string) {
+ return indexedIdentityRows(watcher).find(
+ (entry) => entry.kind === 'file' && entry.aliases.includes(alias),
+ );
+}
+
+function indexedIdentityRows(watcher: WatcherHandle) {
+ return [...watcher.getAllFilesIndex()].map(([name, entry]) => ({
+ name,
+ kind: entry.kind,
+ canonicalPath: entry.canonicalPath,
+ aliases: [...entry.aliases],
+ size: entry.size,
+ modified: entry.modified,
+ inode: entry.inode,
+ }));
+}
+
+function indexedGeneralRows(watcher: WatcherHandle) {
+ return indexedIdentityRows(watcher).filter((entry) => entry.kind === 'file');
+}
+
+function indexedFileTargets(watcher: WatcherHandle): string[] {
+ return localTargetInventoryFromWatcher(watcher, contentDir)?.fileTargets.toSorted() ?? [];
+}
+
+async function listedEntries(port: number) {
+ const response = await fetch(`http://127.0.0.1:${port}/api/documents`);
+ expect(response.status).toBe(200);
+ return (
+ (await response.json()) as {
+ documents: Array<{
+ kind: string;
+ docName?: string;
+ size?: number;
+ modified?: string;
+ isSymlink?: boolean;
+ targetPath?: string | null;
+ }>;
+ }
+ ).documents;
+}
+
+async function searchedFiles(port: number, query: string): Promise<string[]> {
+ const response = await fetch(
+ `http://127.0.0.1:${port}/api/search?query=${encodeURIComponent(query)}&intent=omnibar`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as { results: Array<{ kind: string; path: string }> };
+ return body.results.filter((result) => result.kind === 'file').map((result) => result.path);
+}
+
+test.each([
+ ['alias.csv', true, 'update'],
+ ['alias.csv', true, 'create'],
+ ['real.csv', true, 'update'],
+ ['real.csv', true, 'create'],
+ ['real.csv', false, 'none'],
+] as const)(
+ 'same-stem watcher inventory retains both kinds with %s first, alias %s and retarget %s',
+ async (firstEntry, withAlias, retargetRecord) => {
+ const real = writeDoc('real.csv', 'first,short\n');
+ const other = writeDoc('other.csv', 'second,longer,bytes\n');
+ const document = writeDoc('real.csv.md', '# Real CSV document\n');
+ const alias = join(contentDir, 'alias.csv');
+ const sibling = join(contentDir, 'sibling.csv');
+ if (withAlias) {
+ symlinkSync(real, alias);
+ symlinkSync(real, sibling);
+ }
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = firstEntry;
+ const { watcher, events } = await watchContent();
+ const initial = indexedIdentityRows(watcher);
+ expect(watcher.getFileIndex().get('real.csv')?.canonicalPath).toBe(document);
+ expect
+ .soft(initial.filter((entry) => entry.name === 'real.csv' && entry.kind === 'markdown'))
+ .toHaveLength(1);
+ expect
+ .soft(initial.filter((entry) => entry.name === 'real.csv' && entry.kind === 'file'))
+ .toHaveLength(1);
+ expect
+ .soft(initial.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect
+ .soft(initial.find((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toMatchObject({
+ name: 'real.csv',
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ aliases: withAlias ? expect.arrayContaining(['alias.csv', 'sibling.csv']) : [],
+ });
+ if (withAlias) {
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ const later = writeDoc('later.csv', 'later\n');
+ await deliver(contentDir, [
+ { type: retargetRecord === 'create' ? 'create' : 'update', path: alias },
+ { type: 'create', path: later },
+ ]);
+ expect(readFileSync(alias, 'utf8')).toBe('second,longer,bytes\n');
+ expect(readFileSync(sibling, 'utf8')).toBe('first,short\n');
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: later, relativePath: 'later.csv' }),
+ );
+ const afterRetarget = indexedIdentityRows(watcher);
+ expect
+ .soft(
+ afterRetarget.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ afterRetarget.filter((entry) => entry.kind === 'file' && entry.canonicalPath === other),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(afterRetarget.find((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toMatchObject({
+ name: 'real.csv',
+ aliases: ['sibling.csv'],
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ });
+ expect
+ .soft(afterRetarget.find((entry) => entry.kind === 'file' && entry.canonicalPath === other))
+ .toMatchObject({
+ name: 'other.csv',
+ aliases: ['alias.csv'],
+ size: statSync(other).size,
+ inode: Number(statSync(other).ino),
+ });
+ events.length = 0;
+ }
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+ expect(readFileSync(real, 'utf8')).toBe('first,short\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Real CSV document\n');
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === real))
+ .toEqual([]);
+ const settled = indexedIdentityRows(watcher);
+ expect
+ .soft(settled.filter((entry) => entry.name === 'real.csv' && entry.kind === 'markdown'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.filter((entry) => entry.name === 'real.csv' && entry.kind === 'file'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ if (withAlias) {
+ expect
+ .soft(
+ settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === other)?.aliases,
+ )
+ .toEqual(['alias.csv']);
+ expect
+ .soft(
+ settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.aliases,
+ )
+ .toEqual(['sibling.csv']);
+ }
+ },
+);
+
+test.each([
+ ['alias.csv', 'retarget', true],
+ ['real.csv', 'retarget', true],
+ ['alias.csv', 'unchanged', true],
+ ['alias.csv', 'retarget', false],
+] as const)(
+ 'same-stem HTTP identity with %s first, %s alias and document %s follows disk truth',
+ async (firstEntry, action, withDocument) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = writeDoc('real.csv', 'first,short\n');
+ const other = writeDoc('other.csv', 'second,longer,bytes\n');
+ const alias = join(contentDir, 'alias.csv');
+ const listingAlias = join(contentDir, 'listing-only.csv');
+ symlinkSync(real, alias);
+ symlinkSync(other, listingAlias);
+ if (withDocument) {
+ writeDoc('real.csv.md', '# Real CSV document\n');
+ writeDoc('inventory.csv', 'unreferenced,file\n');
+ writeDoc('inventory.csv.md', '# Unreferenced document\n');
+ }
+ writeDoc(
+ 'source.md',
+ '# Source\n\n[Target](real.csv)\n\n[Other](other.csv)\n\n[Alias](alias.csv)\n\n[Document](real.csv.md)\n\n[Absent](missing.csv)\n',
+ );
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = firstEntry;
+ const server = await bootInventoryServer();
+ try {
+ const expected = {
+ 'real.csv': 'exact',
+ 'other.csv': 'exact',
+ 'alias.csv': 'exact',
+ 'missing.csv': 'missing',
+ };
+ const before = await inventoryForwardStatuses(server.port);
+ if (firstEntry === 'real.csv' && withDocument) expect.soft(before).toEqual(expected);
+ else expect(before).toEqual(expected);
+ const subscription = nativeSubscriptionOn(contentDir);
+ if (action === 'retarget') {
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ await subscription.deliver([{ type: 'update', path: alias }]);
+ const afterOrdinaryRetarget = await inventoryForwardStatuses(server.port);
+ if (firstEntry === 'real.csv' && withDocument) {
+ expect.soft(afterOrdinaryRetarget).toEqual(expected);
+ } else {
+ expect(afterOrdinaryRetarget).toEqual(expected);
+ }
+ }
+ const currentTarget = action === 'retarget' ? other : real;
+ expect(realpathSync(alias)).toBe(currentTarget);
+ expect(readFileSync(alias, 'utf8')).toBe(
+ action === 'retarget' ? 'second,longer,bytes\n' : 'first,short\n',
+ );
+ await subscription.deliver([], new Error(notices[0]));
+ await subscription.deliver([], new Error(notices[0]));
+ expect(readFileSync(real, 'utf8')).toBe('first,short\n');
+ expect(readFileSync(other, 'utf8')).toBe('second,longer,bytes\n');
+ expect.soft(await inventoryForwardStatuses(server.port)).toEqual(expected);
+ expect.soft(await inventoryAuditBroken(server.port, 'real.csv')).toBe(false);
+ expect.soft(await inventoryAuditBroken(server.port, 'alias.csv')).toBe(false);
+ expect(await inventoryAuditBroken(server.port, 'missing.csv')).toBe(true);
+ if (action === 'retarget' && withDocument) {
+ expect
+ .soft(
+ getWatcherDecisionRingSnapshot().filter(
+ (entry) =>
+ entry.decision === 'dispatched' &&
+ entry.path === `.../${basename(contentDir)}/real.csv` &&
+ (entry.kind === 'file-delete' || entry.kind === 'asset-delete'),
+ ),
+ )
+ .toEqual([]);
+ }
+ const realAsset = await fetch(`http://127.0.0.1:${server.port}/api/asset-text?path=real.csv`);
+ const otherAsset = await fetch(
+ `http://127.0.0.1:${server.port}/api/asset-text?path=other.csv`,
+ );
+ const aliasAsset = await fetch(
+ `http://127.0.0.1:${server.port}/api/asset-text?path=alias.csv`,
+ );
+ expect(realAsset.status).toBe(200);
+ expect(await realAsset.text()).toBe('first,short\n');
+ expect(otherAsset.status).toBe(200);
+ expect(await otherAsset.text()).toBe('second,longer,bytes\n');
+ expect(aliasAsset.status).toBe(400);
+ if (withDocument) {
+ const documentResponse = await fetch(
+ `http://127.0.0.1:${server.port}/api/document?docName=real.csv`,
+ );
+ expect(documentResponse.status).toBe(200);
+ const page = (await documentResponse.json()) as { content: string };
+ expect(page.content).toBe('# Real CSV document\n');
+ }
+ const listingResponse = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
+ expect(listingResponse.status).toBe(200);
+ const listing = (await listingResponse.json()) as {
+ documents: Array<{
+ kind: string;
+ docName: string;
+ targetPath?: string | null;
+ isSymlink?: boolean;
+ }>;
+ };
+ if (action === 'retarget' && withDocument) {
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) => entry.kind === 'document' && entry.docName === 'real.csv',
+ ),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) => entry.kind === 'asset' && entry.docName === 'real.csv',
+ ),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) => entry.kind === 'document' && entry.docName === 'inventory.csv',
+ ),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) => entry.kind === 'file' && entry.docName === 'inventory.csv',
+ ),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ listing.documents.find(
+ (entry) => entry.kind === 'file' && entry.docName === 'listing-only.csv',
+ ),
+ )
+ .toMatchObject({
+ targetPath: 'other.csv',
+ isSymlink: true,
+ });
+ const searchResponse = await fetch(
+ `http://127.0.0.1:${server.port}/api/search?query=real.csv&intent=omnibar&limit=100`,
+ );
+ expect(searchResponse.status).toBe(200);
+ const search = (await searchResponse.json()) as {
+ results: Array<{ kind: string; path: string }>;
+ };
+ expect
+ .soft(
+ search.results
+ .filter((entry) => entry.path === 'real.csv')
+ .map((entry) => entry.kind)
+ .sort(),
+ )
+ .toEqual(['file', 'page']);
+ }
+ } finally {
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['old-target', 'new-target', 'alias', 'markdown'] as const)(
+ 'same-stem retarget then remove %s preserves the surviving HTTP identity',
+ async (removed) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = writeDoc('real.csv', 'first,short\n');
+ const other = writeDoc('other.csv', 'second,longer,bytes\n');
+ const document = writeDoc('real.csv.md', '# Real CSV document\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ writeDoc(
+ 'source.md',
+ '# Source\n\n[Target](real.csv)\n\n[Other](other.csv)\n\n[Alias](alias.csv)\n',
+ );
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ expect(await inventoryForwardStatuses(server.port)).toEqual({
+ 'real.csv': 'exact',
+ 'other.csv': 'exact',
+ 'alias.csv': 'exact',
+ });
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ await subscription.deliver([{ type: 'update', path: alias }]);
+ await subscription.deliver([], new Error(notices[0]));
+ const beforeRemoval = await inventoryForwardStatuses(server.port);
+ expect.soft(beforeRemoval).toEqual({
+ 'real.csv': 'exact',
+ 'other.csv': 'exact',
+ 'alias.csv': 'exact',
+ });
+ const path =
+ removed === 'old-target'
+ ? real
+ : removed === 'new-target'
+ ? other
+ : removed === 'alias'
+ ? alias
+ : document;
+ unlinkSync(path);
+ await subscription.deliver([{ type: 'delete', path }]);
+ await subscription.deliver([], new Error(notices[0]));
+ const expected = {
+ 'real.csv': removed === 'old-target' ? 'missing' : 'exact',
+ 'other.csv': removed === 'new-target' ? 'missing' : 'exact',
+ 'alias.csv': removed === 'new-target' || removed === 'alias' ? 'missing' : 'exact',
+ };
+ expect.soft(await inventoryForwardStatuses(server.port)).toEqual(expected);
+ for (const [href, status] of Object.entries(expected)) {
+ expect.soft(await inventoryAuditBroken(server.port, href)).toBe(status === 'missing');
+ }
+ expect(existsSync(real)).toBe(removed !== 'old-target');
+ expect(existsSync(other)).toBe(removed !== 'new-target');
+ expect(existsSync(document)).toBe(removed !== 'markdown');
+ if (removed !== 'alias' && removed !== 'new-target') {
+ expect(realpathSync(alias)).toBe(other);
+ expect(readFileSync(alias, 'utf8')).toBe('second,longer,bytes\n');
+ }
+ const listingResponse = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
+ expect(listingResponse.status).toBe(200);
+ const listing = (await listingResponse.json()) as {
+ documents: Array<{ kind: string; docName: string }>;
+ };
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) => entry.kind === 'document' && entry.docName === 'real.csv',
+ ),
+ )
+ .toHaveLength(removed === 'markdown' ? 0 : 1);
+ expect
+ .soft(
+ listing.documents.filter(
+ (entry) =>
+ (entry.kind === 'asset' || entry.kind === 'file') && entry.docName === 'real.csv',
+ ),
+ )
+ .toHaveLength(removed === 'old-target' ? 0 : 1);
+ } finally {
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['file', 'markdown'] as const)(
+ 'same-spelling public %s mutation preserves the other domain and its recovery change',
+ async (publicDomain) => {
+ const real = writeDoc('real.csv', 'original,file\n');
+ const document = writeDoc('real.csv.md', '# Original document\n');
+ const trigger = writeDoc('identity-trigger.md', '# Trigger\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ let watcher: WatcherHandle | undefined;
+ let publicCallbacks = 0;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'identity-trigger') return;
+ publicCallbacks += 1;
+ if (publicDomain === 'file') {
+ writeFileSync(real, 'public,file,updated\n');
+ const stat = statSync(real);
+ watcher?.mutateFileIndex({
+ kind: 'file-update',
+ path: real,
+ relativePath: 'real.csv',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ } else {
+ writeFileSync(document, '# Public document update\n');
+ watcher?.mutateFileIndex({
+ kind: 'update',
+ path: document,
+ docName: 'real.csv',
+ content: '# Public document update\n',
+ });
+ }
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ const before = indexedIdentityRows(watcher);
+ expect(
+ before.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ expect(
+ before.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ if (publicDomain === 'file') writeFileSync(document, '# External document update\n');
+ else writeFileSync(real, 'external,file,updated\n');
+ unlinkSync(trigger);
+
+ await deliverNotice(contentDir);
+
+ expect(publicCallbacks).toBe(1);
+ expect(completed).toEqual(['complete']);
+ const expectedExternalKind = publicDomain === 'file' ? 'update' : 'file-update';
+ const externalPath = publicDomain === 'file' ? document : real;
+ expect
+ .soft(events)
+ .toContainEqual(expect.objectContaining({ kind: expectedExternalKind, path: externalPath }));
+ expect(readFileSync(real, 'utf8')).toBe(
+ publicDomain === 'file' ? 'public,file,updated\n' : 'external,file,updated\n',
+ );
+ expect(readFileSync(document, 'utf8')).toBe(
+ publicDomain === 'file' ? '# External document update\n' : '# Public document update\n',
+ );
+ const after = indexedIdentityRows(watcher);
+ expect
+ .soft(after.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document))
+ .toHaveLength(1);
+ expect
+ .soft(after.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect
+ .soft(after.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.size)
+ .toBe(statSync(real).size);
+ expect.soft(watcher.getFileIndex().get('real.csv')?.size).toBe(statSync(document).size);
+
+ if (publicDomain === 'file') {
+ unlinkSync(real);
+ watcher.mutateFileIndex({ kind: 'file-delete', path: real, relativePath: 'real.csv' });
+ } else {
+ unlinkSync(document);
+ watcher.mutateFileIndex({ kind: 'delete', path: document, docName: 'real.csv' });
+ }
+ const surviving = indexedIdentityRows(watcher);
+ expect
+ .soft(
+ surviving.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(publicDomain === 'file' ? 1 : 0);
+ expect
+ .soft(surviving.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(publicDomain === 'markdown' ? 1 : 0);
+ },
+);
+
+test.each(['incomplete', 'consumer-error'] as const)(
+ 'same-stem alias identity survives %s recovery and the next complete notice',
+ async (exit) => {
+ const real = writeDoc('real.csv', 'first,short\n');
+ const other = writeDoc('other.csv', 'second,longer,bytes\n');
+ const document = writeDoc('real.csv.md', '# Real CSV document\n');
+ const alias = join(contentDir, 'alias.csv');
+ const trigger = writeDoc('identity-error-trigger.md', '# Trigger\n');
+ const blocked = join(contentDir, 'blocked');
+ mkdirSync(blocked);
+ writeDoc('blocked/known.md', '# Known\n');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const failure = new Error('identity recovery consumer rejected');
+ const logger = getLogger('file-watcher');
+ const warnings = vi.spyOn(logger, 'warn');
+ const errors = vi.spyOn(logger, 'error');
+ let rejected = 0;
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (
+ exit === 'consumer-error' &&
+ event.kind === 'delete' &&
+ event.docName === 'identity-error-trigger' &&
+ rejected === 0
+ ) {
+ rejected += 1;
+ throw failure;
+ }
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ await deliver(contentDir, [{ type: 'update', path: alias }]);
+ events.length = 0;
+ unlinkSync(trigger);
+ if (exit === 'incomplete') deniedDirectoryRead.path = blocked;
+ try {
+ await deliverNotice(contentDir);
+ expect(completed).toEqual([]);
+ if (exit === 'incomplete') {
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect(JSON.stringify([...warnings.mock.calls, ...errors.mock.calls])).toContain('EACCES');
+ } else {
+ expect(rejected).toBe(1);
+ expect(errors.mock.calls.some(([detail]) => detail.err === failure)).toBe(true);
+ }
+ deniedDirectoryRead.path = null;
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect(readFileSync(real, 'utf8')).toBe('first,short\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Real CSV document\n');
+ expect(realpathSync(alias)).toBe(other);
+ expect(readFileSync(alias, 'utf8')).toBe('second,longer,bytes\n');
+ const settled = indexedIdentityRows(watcher);
+ expect
+ .soft(settled.filter((entry) => entry.kind === 'markdown' && entry.name === 'real.csv'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.filter((entry) => entry.kind === 'file' && entry.name === 'real.csv'))
+ .toHaveLength(1);
+ expect
+ .soft(
+ settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.aliases,
+ )
+ .toEqual([]);
+ expect
+ .soft(
+ settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === other)?.aliases,
+ )
+ .toEqual(['alias.csv']);
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === real))
+ .toEqual([]);
+ } finally {
+ deniedDirectoryRead.path = null;
+ }
+ },
+);
+
+test.each(['add', 'remove', 'retarget'] as const)(
+ 'same-stem file alias %s retains canonical file and document identities',
+ async (action) => {
+ const real = writeDoc('real.csv', 'first,short\n');
+ const other = writeDoc('other.csv', 'second,longer,bytes\n');
+ const document = writeDoc('real.csv.md', '# Real CSV document\n');
+ const alias = join(contentDir, 'alias.csv');
+ if (action !== 'add') symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = action === 'add' ? 'real.csv' : 'alias.csv';
+ const { watcher, events } = await watchContent();
+ if (action === 'add') {
+ symlinkSync(real, alias);
+ await deliver(contentDir, [{ type: 'create', path: alias }]);
+ } else if (action === 'remove') {
+ unlinkSync(alias);
+ await deliver(contentDir, [{ type: 'delete', path: alias }]);
+ } else {
+ unlinkSync(alias);
+ symlinkSync(other, alias);
+ await deliver(contentDir, [{ type: 'update', path: alias }]);
+ }
+ await deliverNotice(contentDir);
+ expect(readFileSync(real, 'utf8')).toBe('first,short\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Real CSV document\n');
+ const settled = indexedIdentityRows(watcher);
+ expect
+ .soft(settled.filter((entry) => entry.name === 'real.csv' && entry.kind === 'markdown'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.filter((entry) => entry.name === 'real.csv' && entry.kind === 'file'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toMatchObject({
+ name: 'real.csv',
+ aliases: action === 'add' ? ['alias.csv'] : [],
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ });
+ expect
+ .soft(
+ settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === other)?.aliases,
+ )
+ .toEqual(action === 'retarget' ? ['alias.csv'] : []);
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === real))
+ .toEqual([]);
+ if (action !== 'remove') {
+ expect(realpathSync(alias)).toBe(action === 'retarget' ? other : real);
+ } else {
+ expect(existsSync(alias)).toBe(false);
+ }
+ },
+);
+
+test('same-stem folder alias listing retains both child kinds on repeated inventory reads', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const canonical = join(contentDir, 'canonical');
+ mkdirSync(canonical);
+ writeFileSync(join(canonical, 'real.csv'), 'physical,file\n');
+ writeFileSync(join(canonical, 'real.csv.md'), '# Logical document\n');
+ symlinkSync(canonical, join(contentDir, 'linked-folder'));
+ const server = await bootInventoryServer();
+ try {
+ const readRows = async () => {
+ const response = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as {
+ documents: Array<{ kind: string; docName: string; targetPath?: string | null }>;
+ };
+ return body.documents;
+ };
+ const verify = (rows: Awaited<ReturnType<typeof readRows>>) => {
+ expect
+ .soft(
+ rows.filter(
+ (entry) => entry.docName === 'canonical/real.csv' && entry.kind === 'document',
+ ),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ rows.filter((entry) => entry.docName === 'canonical/real.csv' && entry.kind === 'file'),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(
+ rows.filter(
+ (entry) => entry.docName === 'linked-folder/real.csv' && entry.kind === 'document',
+ ),
+ )
+ .toEqual([expect.objectContaining({ targetPath: 'canonical/real.csv.md' })]);
+ expect
+ .soft(
+ rows.filter(
+ (entry) => entry.docName === 'linked-folder/real.csv' && entry.kind === 'file',
+ ),
+ )
+ .toEqual([expect.objectContaining({ targetPath: 'canonical/real.csv' })]);
+ };
+ verify(await readRows());
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ verify(await readRows());
+ expect(readFileSync(join(canonical, 'real.csv'), 'utf8')).toBe('physical,file\n');
+ expect(readFileSync(join(canonical, 'real.csv.md'), 'utf8')).toBe('# Logical document\n');
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('ordinary same-stem alias removal drops only that alias before notice recovery', async () => {
+ const real = writeDoc('real.csv', 'canonical,file\n');
+ const document = writeDoc('real.csv.md', '# Same-stem document\n');
+ const alias = join(contentDir, 'alias.csv');
+ const sibling = join(contentDir, 'sibling.csv');
+ symlinkSync(real, alias);
+ symlinkSync(real, sibling);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const { watcher, events } = await watchContent();
+ const initial = indexedIdentityRows(watcher);
+ expect(
+ initial.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ expect(
+ initial.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ const originalFile = initial.find(
+ (entry) => entry.kind === 'file' && entry.canonicalPath === real,
+ );
+ expect(originalFile?.size).toBe(statSync(real).size);
+ expect(originalFile?.inode).toBe(Number(statSync(real).ino));
+ unlinkSync(alias);
+
+ await deliver(contentDir, [{ type: 'delete', path: alias }]);
+
+ const immediate = indexedIdentityRows(watcher);
+ expect
+ .soft(immediate.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect.soft(immediate.flatMap((entry) => entry.aliases)).not.toContain('alias.csv');
+ expect
+ .soft(
+ immediate.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.aliases ??
+ [],
+ )
+ .toContain('sibling.csv');
+ expect
+ .soft(immediate.find((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toMatchObject({
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ });
+ expect
+ .soft(
+ immediate.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(1);
+ expect(readFileSync(real, 'utf8')).toBe('canonical,file\n');
+ expect(readFileSync(sibling, 'utf8')).toBe('canonical,file\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Same-stem document\n');
+ events.length = 0;
+
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+
+ const recovered = indexedIdentityRows(watcher);
+ expect
+ .soft(recovered.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect.soft(recovered.flatMap((entry) => entry.aliases)).not.toContain('alias.csv');
+ expect
+ .soft(
+ recovered.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.aliases ??
+ [],
+ )
+ .toContain('sibling.csv');
+ expect
+ .soft(
+ recovered.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(1);
+ expect(events.filter((event) => event.kind === 'file-delete' && event.path === real)).toEqual([]);
+});
+
+test('a public general-file recreation during recovery retains its restored parent', async () => {
+ const first = writeDoc('first.md', '# First\n');
+ const folder = join(contentDir, 'nested');
+ mkdirSync(folder);
+ const later = writeDoc('nested/later.csv', 'before,bytes\n');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'first.md';
+ let recreations = 0;
+ const watched = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'delete' || event.docName !== 'first') return;
+ mkdirSync(folder);
+ writeFileSync(later, 'recreated,general,bytes\n');
+ const stat = statSync(later);
+ watched.watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: later,
+ relativePath: 'nested/later.csv',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ recreations += 1;
+ });
+ expect(watched.watcher.getFolderIndex().has('nested')).toBe(true);
+ expect(
+ indexedIdentityRows(watched.watcher).filter(
+ (entry) => entry.kind === 'file' && entry.canonicalPath === later,
+ ),
+ ).toHaveLength(1);
+ unlinkSync(first);
+ rmSync(folder, { recursive: true });
+
+ await deliverNotice(contentDir);
+
+ expect(recreations).toBe(1);
+ expect(watched.events).toContainEqual({ kind: 'delete', path: first, docName: 'first' });
+ expect(readFileSync(later, 'utf8')).toBe('recreated,general,bytes\n');
+ expect(watched.watcher.getFolderIndex().has('nested')).toBe(true);
+ expect
+ .soft(
+ indexedIdentityRows(watched.watcher).filter(
+ (entry) => entry.kind === 'file' && entry.canonicalPath === later,
+ ),
+ )
+ .toEqual([
+ expect.objectContaining({
+ name: 'nested/later.csv',
+ size: statSync(later).size,
+ inode: Number(statSync(later).ino),
+ }),
+ ]);
+ expect
+ .soft(
+ watched.events.filter(
+ (event) =>
+ 'path' in event &&
+ event.path === later &&
+ (event.kind === 'file-delete' || event.kind === 'asset-delete'),
+ ),
+ )
+ .toEqual([]);
+ expect.soft(watched.events).not.toContainEqual({
+ kind: 'folder-delete',
+ path: folder,
+ relativePath: 'nested',
+ });
+ expect(watched.watcher.getFileIndex().has('first')).toBe(false);
+});
+
+test.each(['general', 'markdown'] as const)(
+ 'same-stem %s ignore rebuild prunes and reseeds only its own identity',
+ async (excludedDomain) => {
+ const real = writeDoc('real.csv', 'canonical,file\n');
+ const document = writeDoc('real.csv.md', '# Same-stem document\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const ignore = join(contentDir, '.okignore');
+ writeFileSync(ignore, '');
+ const filter = dynamicSkillFilter();
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ const initial = indexedIdentityRows(watcher);
+ expect(
+ initial.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ expect(
+ initial.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ expect(watcher.getFileIndex().has('real.csv')).toBe(true);
+ const initialView = watcher.getFileIndex();
+ const beforeGeneration = watcher.getFileIndexGeneration();
+ writeFileSync(ignore, excludedDomain === 'general' ? 'real.csv\n' : 'real.csv.md\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+
+ const pruned = await reconcileFileIndexAfterFilterRebuild(watcher);
+
+ expect(pruned).toEqual({ prunedFiles: 1, prunedFolders: 0 });
+ expect(watcher.getFileIndexGeneration()).toBeGreaterThan(beforeGeneration);
+ expect(watcher.getFileIndex()).not.toBe(initialView);
+ const excluded = indexedIdentityRows(watcher);
+ expect
+ .soft(excluded.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(excludedDomain === 'general' ? 0 : 1);
+ expect
+ .soft(
+ excluded.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(excludedDomain === 'markdown' ? 0 : 1);
+ expect.soft(watcher.getFileIndex().has('real.csv')).toBe(excludedDomain === 'general');
+ if (excludedDomain === 'general') {
+ expect.soft(excluded.flatMap((entry) => entry.aliases)).not.toContain('alias.csv');
+ } else {
+ expect
+ .soft(
+ excluded.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)
+ ?.aliases ?? [],
+ )
+ .toContain('alias.csv');
+ }
+ expect(events).toEqual([]);
+ const excludedGeneration = watcher.getFileIndexGeneration();
+ const excludedView = watcher.getFileIndex();
+ writeFileSync(ignore, '');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+
+ const restoredCounts = await reconcileFileIndexAfterFilterRebuild(watcher);
+
+ expect(restoredCounts).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ expect(watcher.getFileIndexGeneration()).toBeGreaterThan(excludedGeneration);
+ expect(watcher.getFileIndex()).not.toBe(excludedView);
+ const restored = indexedIdentityRows(watcher);
+ expect
+ .soft(restored.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect
+ .soft(
+ restored.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(restored.find((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toMatchObject({
+ size: statSync(real).size,
+ inode: Number(statSync(real).ino),
+ aliases: ['alias.csv'],
+ });
+ expect(watcher.getFileIndex().get('real.csv')?.canonicalPath).toBe(document);
+ expect(readFileSync(real, 'utf8')).toBe('canonical,file\n');
+ expect(readFileSync(document, 'utf8')).toBe('# Same-stem document\n');
+ expect(events).toEqual([]);
+ },
+);
+
+test.each(['file', 'markdown'] as const)(
+ 'same-spelling public %s update during observation preserves the external counterpart',
+ async (publicDomain) => {
+ const real = writeDoc('real.csv', 'original,file\n');
+ const document = writeDoc('real.csv.md', '# Original document\n');
+ const alias = join(contentDir, 'alias.csv');
+ symlinkSync(real, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.firstEntry = 'alias.csv';
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ const initial = indexedIdentityRows(watcher);
+ expect(
+ initial.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real),
+ ).toHaveLength(1);
+ expect(
+ initial.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ ).toHaveLength(1);
+ if (publicDomain === 'file') writeFileSync(document, '# External document update\n');
+ else writeFileSync(real, 'external,file,updated\n');
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ if (publicDomain === 'file') {
+ writeFileSync(real, 'public,file,updated\n');
+ const stat = statSync(real);
+ watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: real,
+ relativePath: 'real.csv',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ } else {
+ writeFileSync(document, '# Public document update\n');
+ watcher.mutateFileIndex({
+ kind: 'update',
+ path: document,
+ docName: 'real.csv',
+ content: '# Public document update\n',
+ });
+ }
+ resume.release();
+ await pending;
+ await vi.runAllTimersAsync();
+ expect(completed).toEqual(['complete']);
+ const externalPath = publicDomain === 'file' ? document : real;
+ const externalKind = publicDomain === 'file' ? 'update' : 'file-update';
+ expect
+ .soft(events)
+ .toContainEqual(expect.objectContaining({ kind: externalKind, path: externalPath }));
+ expect(readFileSync(real, 'utf8')).toBe(
+ publicDomain === 'file' ? 'public,file,updated\n' : 'external,file,updated\n',
+ );
+ expect(readFileSync(document, 'utf8')).toBe(
+ publicDomain === 'file' ? '# External document update\n' : '# Public document update\n',
+ );
+ const settled = indexedIdentityRows(watcher);
+ expect
+ .soft(settled.filter((entry) => entry.kind === 'file' && entry.canonicalPath === real))
+ .toHaveLength(1);
+ expect
+ .soft(
+ settled.filter((entry) => entry.kind === 'markdown' && entry.canonicalPath === document),
+ )
+ .toHaveLength(1);
+ expect
+ .soft(settled.find((entry) => entry.kind === 'file' && entry.canonicalPath === real)?.size)
+ .toBe(statSync(real).size);
+ expect.soft(watcher.getFileIndex().get('real.csv')?.size).toBe(statSync(document).size);
+ } finally {
+ resume.release();
+ await pending;
+ }
+ },
+);
+
+test.each(['a.csv', 'b.csv'] as const)(
+ 'general inode dedup retains a later symlink alias resolving to %s',
+ async (targetName) => {
+ const first = writeDoc('a.csv', 'same,inode,content\n');
+ const hardlink = join(contentDir, 'b.csv');
+ const alias = join(contentDir, 'z-alias.csv');
+ linkSync(first, hardlink);
+ symlinkSync(join(contentDir, targetName), alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'z-alias.csv'];
+ let watcher: WatcherHandle | undefined;
+ try {
+ expect(statSync(first).ino).toBe(statSync(hardlink).ino);
+ expect(realpathSync(alias)).toBe(join(contentDir, targetName));
+ watcher = await startWatcher(contentDir, async () => {}, undefined, {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ });
+ const rows = indexedIdentityRows(watcher).filter((entry) => entry.kind === 'file');
+ expect(rows).toHaveLength(1);
+ expect(rows[0]).toMatchObject({
+ name: 'a.csv',
+ canonicalPath: first,
+ inode: Number(statSync(first).ino),
+ });
+ expect(readFileSync(alias, 'utf8')).toBe('same,inode,content\n');
+ expect.soft(rows[0]?.aliases).toContain('z-alias.csv');
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await watcher?.unsubscribe();
+ if (watcher) expect(nativeSubscriptionOn(contentDir).nativeReleases()).toBe(1);
+ rmSync(contentDir, { recursive: true, force: true });
+ expect(existsSync(contentDir)).toBe(false);
+ }
+ },
+);
+
+test.each([
+ { name: 'alias create to a', action: 'alias', record: 'create', target: 'a.csv', first: 'a.csv' },
+ { name: 'alias create to b', action: 'alias', record: 'create', target: 'b.csv', first: 'a.csv' },
+ { name: 'alias update to a', action: 'alias', record: 'update', target: 'a.csv', first: 'a.csv' },
+ { name: 'alias update to b', action: 'alias', record: 'update', target: 'b.csv', first: 'a.csv' },
+ { name: 'direct update a', action: 'direct', record: 'update', target: 'a.csv', first: 'a.csv' },
+ { name: 'direct update b', action: 'direct', record: 'update', target: 'b.csv', first: 'a.csv' },
+ { name: 'public update a', action: 'public', record: null, target: 'a.csv', first: 'a.csv' },
+ { name: 'public update b', action: 'public', record: null, target: 'b.csv', first: 'a.csv' },
+ { name: 'order a to b', action: 'order', record: null, target: 'a.csv', first: 'a.csv' },
+ { name: 'order b to a', action: 'order', record: null, target: 'a.csv', first: 'b.csv' },
+] as const)(
+ 'an inode-linked general file remains present through $name and repeated notices',
+ async ({ action, record, target, first }) => {
+ const bytes = 'same,inode,content\n';
+ const a = writeDoc('a.csv', bytes);
+ const b = join(contentDir, 'b.csv');
+ const alias = join(contentDir, 'z-alias.csv');
+ linkSync(a, b);
+ symlinkSync(join(contentDir, target), alias);
+ const second = first === 'a.csv' ? 'b.csv' : 'a.csv';
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = [first, second, 'z-alias.csv'];
+ const disk = () => ({
+ a: {
+ inode: Number(statSync(a).ino),
+ links: statSync(a).nlink,
+ regular: lstatSync(a).isFile(),
+ canonicalPath: realpathSync(a),
+ bytes: readFileSync(a, 'utf8'),
+ },
+ b: {
+ inode: Number(statSync(b).ino),
+ links: statSync(b).nlink,
+ regular: lstatSync(b).isFile(),
+ canonicalPath: realpathSync(b),
+ bytes: readFileSync(b, 'utf8'),
+ },
+ alias: {
+ inode: Number(statSync(alias).ino),
+ symlink: lstatSync(alias).isSymbolicLink(),
+ canonicalPath: realpathSync(alias),
+ bytes: readFileSync(alias, 'utf8'),
+ },
+ });
+ const initialDisk = disk();
+ expect(initialDisk.a.inode).toBe(initialDisk.b.inode);
+ expect(initialDisk.a.links).toBe(2);
+ expect(initialDisk.b.links).toBe(2);
+ expect(initialDisk.a.regular).toBe(true);
+ expect(initialDisk.b.regular).toBe(true);
+ expect(initialDisk.a.canonicalPath).toBe(a);
+ expect(initialDisk.b.canonicalPath).toBe(b);
+ expect(initialDisk.alias.symlink).toBe(true);
+ expect(initialDisk.alias.canonicalPath).toBe(join(contentDir, target));
+ expect([initialDisk.a.bytes, initialDisk.b.bytes, initialDisk.alias.bytes]).toEqual([
+ bytes,
+ bytes,
+ bytes,
+ ]);
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle | undefined;
+ try {
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ const active = watcher;
+ const indexedPhysical = () =>
+ indexedIdentityRows(active).filter(
+ (entry) =>
+ entry.kind === 'file' &&
+ entry.inode === initialDisk.a.inode &&
+ entry.size === statSync(a).size,
+ );
+ expect(indexedPhysical().length).toBeGreaterThan(0);
+ const initialRepresentative = indexedPhysical()[0]?.name;
+ if (action === 'order') {
+ scanSchedule.orderedEntries = [second, first, 'z-alias.csv'];
+ expect(events).toEqual([]);
+ } else if (action === 'public') {
+ const path = join(contentDir, target);
+ const stat = statSync(path);
+ const generation = active.getFileIndexGeneration();
+ active.mutateFileIndex({
+ kind: 'file-update',
+ path,
+ relativePath: target,
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ expect(active.getFileIndexGeneration()).toBeGreaterThan(generation);
+ } else {
+ const path = action === 'alias' ? alias : join(contentDir, target);
+ await deliver(contentDir, [{ type: record, path }]);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: record === 'create' ? 'file-create' : 'file-update',
+ path,
+ }),
+ );
+ }
+ expect(disk()).toEqual(initialDisk);
+ expect.soft(indexedPhysical().length).toBeGreaterThan(0);
+ expect.soft(indexedPhysical()).toHaveLength(1);
+ expect.soft(indexedPhysical()[0]?.name).toBe(initialRepresentative);
+ expect.soft(indexedFileTargets(active)).toEqual(['a.csv', 'b.csv', 'z-alias.csv'].toSorted());
+ events.length = 0;
+
+ await deliverNotice(contentDir);
+ const firstNoticeEvents = [...events];
+ const firstNoticeRows = indexedPhysical();
+ const firstNoticeTargets = indexedFileTargets(active);
+ events.length = 0;
+ await deliverNotice(contentDir);
+ const repeatedNoticeEvents = [...events];
+
+ expect(disk()).toEqual(initialDisk);
+ expect.soft(indexedPhysical().length).toBeGreaterThan(0);
+ expect.soft(firstNoticeRows).toHaveLength(1);
+ expect.soft(firstNoticeRows[0]?.name).toBe(initialRepresentative);
+ expect.soft(firstNoticeTargets).toEqual(['a.csv', 'b.csv', 'z-alias.csv'].toSorted());
+ expect.soft(indexedPhysical()).toHaveLength(1);
+ expect.soft(indexedPhysical()[0]?.name).toBe(initialRepresentative);
+ expect.soft(indexedFileTargets(active)).toEqual(['a.csv', 'b.csv', 'z-alias.csv'].toSorted());
+ expect
+ .soft(
+ firstNoticeEvents.filter(
+ (event) =>
+ (event.kind === 'asset-delete' || event.kind === 'file-delete') &&
+ (event.path === a || event.path === b),
+ ),
+ )
+ .toEqual([]);
+ expect.soft(repeatedNoticeEvents).toEqual([]);
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await watcher?.unsubscribe();
+ if (watcher) expect(nativeSubscriptionOn(contentDir).nativeReleases()).toBe(1);
+ rmSync(contentDir, { recursive: true, force: true });
+ expect(existsSync(contentDir)).toBe(false);
+ }
+ },
+);
+
+test.each(['direct b update', 'order a to b'] as const)(
+ 'an admitted hardlink and actual symlink stay truthful in HTTP after $0',
+ async (arm) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const bytes = 'same,inode,content\n';
+ const a = writeDoc('a.csv', bytes);
+ const b = join(contentDir, 'b.csv');
+ const z = join(contentDir, 'z-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(a, z);
+ symlinkSync(b, y);
+ writeDoc('source.md', '# Source\n\n[A](a.csv)\n\n[B](b.csv)\n\n[Z](z-alias.csv)\n');
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv', 'source.md'];
+ const physical = () => ({
+ a: {
+ inode: Number(statSync(a).ino),
+ links: statSync(a).nlink,
+ regular: lstatSync(a).isFile(),
+ canonicalPath: realpathSync(a),
+ bytes: readFileSync(a, 'utf8'),
+ },
+ b: {
+ inode: Number(statSync(b).ino),
+ links: statSync(b).nlink,
+ regular: lstatSync(b).isFile(),
+ canonicalPath: realpathSync(b),
+ bytes: readFileSync(b, 'utf8'),
+ },
+ z: { symlink: lstatSync(z).isSymbolicLink(), target: realpathSync(z) },
+ y: { symlink: lstatSync(y).isSymbolicLink(), target: realpathSync(y) },
+ });
+ const initialDisk = physical();
+ expect(initialDisk.a.inode).toBe(initialDisk.b.inode);
+ expect(initialDisk.a.links).toBe(2);
+ expect(initialDisk.b.links).toBe(2);
+ expect(initialDisk.a.regular).toBe(true);
+ expect(initialDisk.b.regular).toBe(true);
+ expect(initialDisk.a.canonicalPath).toBe(a);
+ expect(initialDisk.b.canonicalPath).toBe(b);
+ expect(initialDisk.z).toEqual({ symlink: true, target: a });
+ expect(initialDisk.y).toEqual({ symlink: true, target: b });
+ expect([initialDisk.a.bytes, initialDisk.b.bytes]).toEqual([bytes, bytes]);
+ let server: Awaited<ReturnType<typeof bootInventoryServer>> | undefined;
+ try {
+ server = await bootInventoryServer();
+ const active = server;
+ const snapshot = async () => {
+ const statuses = await inventoryForwardStatuses(active.port);
+ const audit = {
+ a: await inventoryAuditBroken(active.port, 'a.csv'),
+ b: await inventoryAuditBroken(active.port, 'b.csv'),
+ };
+ const listingResponse = await fetch(`http://127.0.0.1:${active.port}/api/documents`);
+ expect(listingResponse.status).toBe(200);
+ const listing = (await listingResponse.json()) as {
+ documents: Array<{
+ kind: string;
+ docName: string;
+ isSymlink?: boolean;
+ targetPath?: string | null;
+ }>;
+ };
+ for (const path of ['a.csv', 'b.csv'] as const) {
+ const response = await fetch(
+ `http://127.0.0.1:${active.port}/api/asset-text?path=${path}`,
+ );
+ expect(response.status).toBe(200);
+ expect(await response.text()).toBe(bytes);
+ }
+ const aliasAsset = await fetch(
+ `http://127.0.0.1:${active.port}/api/asset-text?path=z-alias.csv`,
+ );
+ expect(aliasAsset.status).toBe(400);
+ expect(physical()).toEqual(initialDisk);
+ return {
+ statuses,
+ audit,
+ unreferenced: listing.documents.find(
+ (entry) => entry.kind === 'file' && entry.docName === 'y-alias.csv',
+ ),
+ };
+ };
+ const initial = await snapshot();
+ expect(initial.statuses['a.csv']).toBe('exact');
+ expect(initial.statuses['z-alias.csv']).toBe('exact');
+ expect(initial.audit.a).toBe(false);
+ if (arm === 'direct b update') {
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: b }]);
+ } else {
+ scanSchedule.orderedEntries = ['b.csv', 'a.csv', 'y-alias.csv', 'z-alias.csv', 'source.md'];
+ }
+ const beforeNotice = await snapshot();
+ const retained = arm === 'direct b update' ? 'b.csv' : 'a.csv';
+ expect(beforeNotice.statuses['a.csv']).toBe('exact');
+ expect(beforeNotice.statuses['z-alias.csv']).toBe('exact');
+ expect(beforeNotice.statuses[retained]).toBe('exact');
+ expect(beforeNotice.audit[retained === 'a.csv' ? 'a' : 'b']).toBe(false);
+
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const afterNotice = await snapshot();
+
+ for (const [href, status] of Object.entries(beforeNotice.statuses)) {
+ if (status === 'exact') expect.soft(afterNotice.statuses[href]).toBe('exact');
+ }
+ expect.soft(afterNotice.statuses[retained]).toBe('exact');
+ expect.soft(afterNotice.audit[retained === 'a.csv' ? 'a' : 'b']).toBe(false);
+ expect.soft(await inventoryAuditBroken(active.port, retained)).toBe(false);
+ expect.soft(afterNotice.statuses['z-alias.csv']).toBe('exact');
+ expect
+ .soft([
+ initial.unreferenced?.isSymlink,
+ beforeNotice.unreferenced?.isSymlink,
+ afterNotice.unreferenced?.isSymlink,
+ ])
+ .toEqual([true, true, true]);
+ expect
+ .soft([
+ initial.unreferenced?.targetPath,
+ beforeNotice.unreferenced?.targetPath,
+ afterNotice.unreferenced?.targetPath,
+ ])
+ .toEqual(['b.csv', 'b.csv', 'b.csv']);
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await server?.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+ },
+);
+
+test.each(['regular-first', 'alias-first'] as const)(
+ 'startup $0 admits every real hardlink name into one searchable group',
+ async (order) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const bytes = 'shared,hardlink,bytes\n';
+ const aName = 'a-amberpilot.csv';
+ const bName = 'b-beaconquartz.csv';
+ const zName = 'z-aliasindigo.csv';
+ const a = writeDoc(aName, bytes);
+ const b = join(contentDir, bName);
+ const z = join(contentDir, zName);
+ linkSync(a, b);
+ symlinkSync(b, z);
+ writeDoc('source.md', `# Source\n\n[A](${aName})\n\n[B](${bName})\n\n[Z](${zName})\n`);
+ const aStat = statSync(a);
+ const bStat = statSync(b);
+ expect(lstatSync(a).isFile()).toBe(true);
+ expect(lstatSync(b).isFile()).toBe(true);
+ expect(lstatSync(z).isSymbolicLink()).toBe(true);
+ expect([aStat.dev, aStat.ino]).toEqual([bStat.dev, bStat.ino]);
+ expect(realpathSync(a)).toBe(a);
+ expect(realpathSync(b)).toBe(b);
+ expect(realpathSync(z)).toBe(b);
+ expect([readFileSync(a, 'utf8'), readFileSync(b, 'utf8'), readFileSync(z, 'utf8')]).toEqual([
+ bytes,
+ bytes,
+ bytes,
+ ]);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries =
+ order === 'alias-first'
+ ? [zName, aName, bName, 'source.md']
+ : [aName, bName, zName, 'source.md'];
+ const server = await bootInventoryServer();
+ try {
+ const statuses = await inventoryForwardStatuses(server.port);
+ expect.soft(statuses).toEqual({
+ [aName]: 'exact',
+ [bName]: 'exact',
+ [zName]: 'exact',
+ });
+ const listed = await listedEntries(server.port);
+ for (const name of [aName, bName]) {
+ expect
+ .soft(listed.filter((row) => row.kind === 'asset' && row.docName === name))
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ expect
+ .soft(listed.filter((row) => row.kind === 'file' && row.docName === name))
+ .toEqual([]);
+ }
+ expect
+ .soft(listed.filter((row) => row.kind === 'file' && row.docName === zName))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+ const byA = await searchedFiles(server.port, 'a-amberpilot');
+ const byB = await searchedFiles(server.port, 'b-beaconquartz');
+ const byZ = await searchedFiles(server.port, 'z-aliasindigo');
+ expect.soft(byA).toHaveLength(1);
+ expect.soft(byB).toEqual(byA);
+ expect.soft(byZ).toEqual(byA);
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+ },
+);
+
+test.each(['rescued-folder-create', 'public-file-create', 'alias-before-member'] as const)(
+ 'a newly admitted hardlink joins its known physical group through $0',
+ async (input) => {
+ const bytes = 'known,member\n';
+ const a = writeDoc('a.csv', bytes);
+ const folder = join(contentDir, 'new-folder');
+ const bName =
+ input === 'rescued-folder-create'
+ ? 'new-folder/b.csv'
+ : input === 'public-file-create'
+ ? '0-before/b.csv'
+ : 'b.csv';
+ const b = join(contentDir, bName);
+ const z = join(contentDir, 'z-alias.csv');
+ const { watcher, events } = await watchContent();
+ const initialRepresentative = indexedGeneralRows(watcher)[0]?.name;
+ expect(initialRepresentative).toBe('a.csv');
+ if (input === 'rescued-folder-create' || input === 'public-file-create') mkdirSync(dirname(b));
+ linkSync(a, b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(realpathSync(b)).toBe(b);
+
+ if (input === 'rescued-folder-create') {
+ await deliver(contentDir, [{ type: 'create', path: folder }]);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: b, relativePath: bName }),
+ );
+ } else if (input === 'public-file-create') {
+ expect(bName.localeCompare('a.csv')).toBeLessThan(0);
+ const st = statSync(b);
+ const generation = watcher.getFileIndexGeneration();
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: b,
+ relativePath: bName,
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ });
+ expect(watcher.getFileIndexGeneration()).toBeGreaterThan(generation);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedGeneralRows(watcher)[0]?.name).toBe(initialRepresentative);
+ await deliver(contentDir, [{ type: 'create', path: dirname(b) }]);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'folder-create',
+ path: dirname(b),
+ relativePath: '0-before',
+ }),
+ );
+ expect
+ .soft(
+ events.filter(
+ (event) => event.kind === 'file-create' && (event.path === a || event.path === b),
+ ),
+ )
+ .toEqual([]);
+ } else {
+ symlinkSync(b, z);
+ expect(lstatSync(z).isSymbolicLink()).toBe(true);
+ expect(realpathSync(z)).toBe(b);
+ await deliver(contentDir, [{ type: 'create', path: z }]);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: z, relativePath: 'z-alias.csv' }),
+ );
+ }
+ expect(readFileSync(a, 'utf8')).toBe(bytes);
+ expect(readFileSync(b, 'utf8')).toBe(bytes);
+ expect(events.filter((event) => event.kind === 'file-create' && event.path === a)).toEqual([]);
+ const expectedTargets = [
+ 'a.csv',
+ bName,
+ ...(input === 'alias-before-member' ? ['z-alias.csv'] : []),
+ ].toSorted();
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedGeneralRows(watcher)[0]?.name).toBe(initialRepresentative);
+ expect.soft(indexedFileTargets(watcher)).toEqual(expectedTargets);
+
+ if (input === 'alias-before-member') {
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ }
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedGeneralRows(watcher)[0]?.name).toBe(initialRepresentative);
+ expect.soft(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect
+ .soft(
+ events.filter(
+ (event) => event.kind === 'file-delete' && (event.path === a || event.path === b),
+ ),
+ )
+ .toEqual([]);
+ },
+);
+
+test('a generation-backed search query learns a new hardlink name in the existing group', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const a = writeDoc('amberpilot.csv', 'searchable,hardlink\n');
+ const b = join(contentDir, 'beaconquartz.csv');
+ const z = join(contentDir, 'linked-indigo.csv');
+ const server = await bootInventoryServer();
+ try {
+ expect(await searchedFiles(server.port, 'beaconquartz')).toEqual([]);
+ expect(await searchedFiles(server.port, 'amberpilot')).toEqual(['amberpilot.csv']);
+ linkSync(a, b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: b }]);
+ expect.soft(await searchedFiles(server.port, 'beaconquartz')).toEqual(['amberpilot.csv']);
+ symlinkSync(b, z);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: z }]);
+ expect.soft(await searchedFiles(server.port, 'linked-indigo')).toEqual(['amberpilot.csv']);
+ expect.soft(await searchedFiles(server.port, 'amberpilot')).toEqual(['amberpilot.csv']);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect.soft(await searchedFiles(server.port, 'beaconquartz')).toEqual(['amberpilot.csv']);
+ } finally {
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+});
+
+test('a public canonical path with a lexical symlink name joins the existing hardlink group', async () => {
+ const a = writeDoc('a.csv', 'writer,shared\n');
+ const { watcher } = await watchContent();
+ const b = join(contentDir, 'b.csv');
+ const z = join(contentDir, 'z-alias.csv');
+ linkSync(a, b);
+ symlinkSync(b, z);
+ expect(lstatSync(b).isFile()).toBe(true);
+ expect(lstatSync(z).isSymbolicLink()).toBe(true);
+ expect(realpathSync(z)).toBe(b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ const st = statSync(b);
+ const generation = watcher.getFileIndexGeneration();
+ watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'z-alias.csv',
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ });
+ expect(watcher.getFileIndexGeneration()).toBeGreaterThan(generation);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'z-alias.csv']);
+ expect.soft(indexedGeneralRows(watcher)[0]?.aliases).toEqual(['z-alias.csv']);
+ await deliverNotice(contentDir);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'z-alias.csv']);
+ expect(readFileSync(a, 'utf8')).toBe('writer,shared\n');
+ expect(readFileSync(b, 'utf8')).toBe('writer,shared\n');
+});
+
+test('different devices do not merge equal reported inode numbers during external observation', async () => {
+ const a = writeDoc('atlas.csv', 'atlas\n');
+ const b = writeDoc('beacon.csv', 'beacon\n');
+ const aPhysical = statSync(a);
+ const bPhysical = statSync(b);
+ expect(aPhysical.ino).not.toBe(bPhysical.ino);
+ expect(aPhysical.dev).toBe(bPhysical.dev);
+ deviceContrast.path = b;
+ deviceContrast.device = aPhysical.dev + 1;
+ deviceContrast.inode = aPhysical.ino;
+ const { watcher } = await watchContent();
+ expect(deviceContrast.observed).toBe(true);
+ expect(readFileSync(a, 'utf8')).toBe('atlas\n');
+ expect(readFileSync(b, 'utf8')).toBe('beacon\n');
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(2);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['atlas.csv', 'beacon.csv']);
+ deviceContrast.path = null;
+});
+
+test.each(['nonrepresentative', 'representative'] as const)(
+ 'deleting the $0 hardlink removes only that member and its dependent alias',
+ async (removedRole) => {
+ const a = writeDoc('a.csv', 'shared,bytes\n');
+ const b = join(contentDir, 'b.csv');
+ const document = writeDoc('a.csv.md', '# Same spelling\n');
+ const z = join(contentDir, 'z-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(a, z);
+ symlinkSync(b, y);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv', 'a.csv.md'];
+ const { watcher, events } = await watchContent();
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ const removed = removedRole === 'representative' ? a : b;
+ const survivor = removed === a ? b : a;
+ const survivingAlias = survivor === a ? 'z-alias.csv' : 'y-alias.csv';
+ const lostAlias = survivor === a ? 'y-alias.csv' : 'z-alias.csv';
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual(['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv'].toSorted());
+
+ events.length = 0;
+ unlinkSync(removed);
+ expect(existsSync(removed)).toBe(false);
+ expect(readFileSync(survivor, 'utf8')).toBe('shared,bytes\n');
+ await deliver(contentDir, [{ type: 'delete', path: removed }]);
+ expect(events).toContainEqual(expect.objectContaining({ kind: 'file-delete', path: removed }));
+ expect(
+ events.filter((event) => event.kind === 'file-delete' && event.path === survivor),
+ ).toEqual([]);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedGeneralRows(watcher)[0]?.name).toBe(survivor === a ? 'a.csv' : 'b.csv');
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual([survivor === a ? 'a.csv' : 'b.csv', survivingAlias].toSorted());
+ expect.soft(indexedFileTargets(watcher)).not.toContain(lostAlias);
+ expect(watcher.getFileIndex().get('a.csv')?.canonicalPath).toBe(document);
+ await deliverNotice(contentDir);
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual([survivor === a ? 'a.csv' : 'b.csv', survivingAlias].toSorted());
+
+ events.length = 0;
+ unlinkSync(survivor);
+ await deliver(contentDir, [{ type: 'delete', path: survivor }]);
+ expect(events).toContainEqual(expect.objectContaining({ kind: 'file-delete', path: survivor }));
+ expect.soft(indexedGeneralRows(watcher)).toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual([]);
+ await deliverNotice(contentDir);
+ await deliverNotice(contentDir);
+ expect.soft(indexedGeneralRows(watcher)).toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual([]);
+ expect(watcher.getFileIndex().get('a.csv')?.canonicalPath).toBe(document);
+ expect(readFileSync(document, 'utf8')).toBe('# Same spelling\n');
+ },
+);
+
+test('a collapsed directory delete removes its member and alias but retains the outside hardlink', async () => {
+ const a = writeDoc('a.csv', 'cross,directory\n');
+ const nested = join(contentDir, 'nested');
+ mkdirSync(nested);
+ const b = join(nested, 'b.csv');
+ const y = join(nested, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ const { watcher, events } = await watchContent();
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ events.length = 0;
+ rmSync(nested, { recursive: true });
+ expect(existsSync(nested)).toBe(false);
+ expect(readFileSync(a, 'utf8')).toBe('cross,directory\n');
+ await deliver(contentDir, [{ type: 'delete', path: nested }]);
+ expect.soft(events).toContainEqual(expect.objectContaining({ kind: 'file-delete', path: b }));
+ expect(events.filter((event) => event.kind === 'file-delete' && event.path === a)).toEqual([]);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv']);
+ await deliverNotice(contentDir);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv']);
+});
+
+test.each(['ordinary-nonrepresentative', 'notice-representative'] as const)(
+ 'replacing the $0 hardlink moves only that pathname to its new physical group',
+ async (input) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const aName = 'a-amberpilot.csv';
+ const bName = 'b-beaconquartz.csv';
+ const a = writeDoc(aName, 'old,shared\n');
+ const b = join(contentDir, bName);
+ const z = join(contentDir, 'z-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(a, z);
+ symlinkSync(b, y);
+ writeDoc('source.md', `# Source\n\n[A](${aName})\n\n[B](${bName})\n\n[Z](z-alias.csv)\n`);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = [aName, bName, 'y-alias.csv', 'z-alias.csv', 'source.md'];
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const before = await inventoryForwardStatuses(server.port);
+ expect(before[aName]).toBe('exact');
+ expect(before[bName]).toBe('exact');
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ const replaced = input === 'ordinary-nonrepresentative' ? b : a;
+ const survivor = replaced === a ? b : a;
+ const temporary = writeDoc('replacement-temporary.csv', 'new,independent,bytes\n');
+ renameSync(temporary, replaced);
+ expect(statSync(replaced).ino).not.toBe(statSync(survivor).ino);
+ expect(readFileSync(replaced, 'utf8')).toBe('new,independent,bytes\n');
+ expect(readFileSync(survivor, 'utf8')).toBe('old,shared\n');
+ expect(realpathSync(y)).toBe(b);
+ expect(realpathSync(z)).toBe(a);
+ if (input === 'ordinary-nonrepresentative') {
+ await subscription.deliver([{ type: 'update', path: replaced }]);
+ } else {
+ await subscription.deliver([], new Error(notices[0]));
+ }
+ const statuses = await inventoryForwardStatuses(server.port);
+ expect.soft(statuses[aName]).toBe('exact');
+ expect.soft(statuses[bName]).toBe('exact');
+ expect.soft(statuses['z-alias.csv']).toBe('exact');
+ expect.soft(await inventoryAuditBroken(server.port, aName)).toBe(false);
+ expect.soft(await inventoryAuditBroken(server.port, bName)).toBe(false);
+ const listing = await listedEntries(server.port);
+ expect
+ .soft(listing.filter((row) => row.kind === 'file' && row.docName === 'y-alias.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+ expect
+ .soft(listing.filter((row) => row.kind === 'file' && row.docName === 'z-alias.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: aName })]);
+ const byA = await searchedFiles(server.port, 'a-amberpilot');
+ const byB = await searchedFiles(server.port, 'b-beaconquartz');
+ expect.soft(byA).toHaveLength(1);
+ expect.soft(byB).toHaveLength(1);
+ expect.soft(byA[0]).not.toBe(byB[0]);
+ await subscription.deliver([], new Error(notices[0]));
+ expect.soft(await searchedFiles(server.port, 'a-amberpilot')).toEqual(byA);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual(byB);
+ expect
+ .soft(
+ (await listedEntries(server.port)).filter(
+ (row) => row.kind === 'file' && row.docName === 'z-alias.csv',
+ ),
+ )
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: aName })]);
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+ },
+);
+
+test('a regular hardlink converted to a real symlink and back changes its listed role once', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const aName = 'a-amberpilot.csv';
+ const bName = 'b-beaconquartz.csv';
+ const cName = 'c-cometnova.csv';
+ const a = writeDoc(aName, 'same,role\n');
+ const b = join(contentDir, bName);
+ const c = writeDoc(cName, 'separate,role,target\n');
+ const dependentName = 'y-dependentindigo.csv';
+ const dependent = join(contentDir, dependentName);
+ const siblingName = 'z-independentviolet.csv';
+ const sibling = join(contentDir, siblingName);
+ linkSync(a, b);
+ symlinkSync(b, dependent);
+ symlinkSync(a, sibling);
+ writeDoc('source.md', `# Source\n\n[A](${aName})\n`);
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const role = async () =>
+ (await listedEntries(server.port)).filter(
+ (row) => row.kind === 'file' && row.docName === bName,
+ );
+ const dependentRole = async (targetPath: string, owner = aName) => {
+ expect(lstatSync(dependent).isSymbolicLink()).toBe(true);
+ expect(realpathSync(dependent)).toBe(join(contentDir, targetPath));
+ expect
+ .soft((await listedEntries(server.port)).filter((row) => row.docName === dependentName))
+ .toEqual([expect.objectContaining({ kind: 'file', isSymlink: true, targetPath })]);
+ expect.soft(await searchedFiles(server.port, 'y-dependentindigo')).toEqual([owner]);
+ };
+ expect(lstatSync(b).isFile()).toBe(true);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+
+ await dependentRole(bName);
+ const priorSize = statSync(b).size;
+ writeFileSync(b, 'same,role,updated,ordinary\n');
+ const metadataStat = statSync(b);
+ expect(metadataStat.size).not.toBe(priorSize);
+ denyAdmission('realpath', dependent);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const metadataRows = await listedEntries(server.port);
+ expect.soft(metadataRows.find((row) => row.docName === bName)?.size).toBe(metadataStat.size);
+ expect
+ .soft(metadataRows.find((row) => row.docName === dependentName)?.size)
+ .toBe(metadataStat.size);
+ expect
+ .soft(metadataRows.find((row) => row.docName === siblingName)?.size)
+ .toBe(metadataStat.size);
+ clearAdmissionDenial();
+ writeFileSync(b, 'same,role\n');
+ await subscription.deliver([{ type: 'update', path: b }]);
+ await dependentRole(bName);
+ const priorRoleRows = (await listedEntries(server.port)).filter(
+ (row) => row.docName === bName || row.docName === dependentName,
+ );
+ expect(priorRoleRows).toHaveLength(2);
+ unlinkSync(b);
+ symlinkSync(a, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(a);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ const later = writeDoc('later-role.csv', 'later,independent\n');
+ denyAdmission('realpath', dependent);
+ await subscription.deliver([
+ { type: 'update', path: b },
+ { type: 'create', path: later },
+ ]);
+ expect(admissionFault.observed).toBe(true);
+ expect
+ .soft(
+ (await listedEntries(server.port)).filter(
+ (row) => row.docName === bName || row.docName === dependentName,
+ ),
+ )
+ .toEqual(priorRoleRows);
+ expect(
+ (await listedEntries(server.port)).filter((row) => row.docName === 'later-role.csv'),
+ ).toEqual([expect.objectContaining({ kind: 'file', isSymlink: false, targetPath: null })]);
+ expect(readFileSync(later, 'utf8')).toBe('later,independent\n');
+ clearAdmissionDenial();
+ await subscription.deliver([], new Error(notices[0]));
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: aName })]);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+ await dependentRole(aName);
+
+ const dName = 'd-deltaorbit.csv';
+ const d = join(contentDir, dName);
+ linkSync(a, d);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(d).dev, statSync(d).ino]);
+ await subscription.deliver([{ type: 'create', path: d }]);
+ expect.soft(await searchedFiles(server.port, 'd-deltaorbit')).toEqual([aName]);
+
+ unlinkSync(b);
+ symlinkSync(d, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(d);
+ expect(realpathSync(dependent)).toBe(d);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: dName })]);
+ await dependentRole(dName);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(c);
+ expect(realpathSync(dependent)).toBe(c);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: cName })]);
+ await dependentRole(cName, cName);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([cName]);
+ expect.soft(await searchedFiles(server.port, 'a-amberpilot')).toEqual([aName]);
+
+ unlinkSync(b);
+ linkSync(a, b);
+ expect(lstatSync(b).isFile()).toBe(true);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+ await dependentRole(bName);
+ await subscription.deliver([], new Error(notices[0]));
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ await dependentRole(bName);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect(realpathSync(b)).toBe(c);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: cName })]);
+ await dependentRole(cName, cName);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([cName]);
+ expect.soft(await searchedFiles(server.port, 'a-amberpilot')).toEqual([aName]);
+ unlinkSync(b);
+ linkSync(a, b);
+ expect(lstatSync(b).isFile()).toBe(true);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ expect
+ .soft(await role())
+ .toEqual([expect.objectContaining({ isSymlink: false, targetPath: null })]);
+ await dependentRole(bName);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+ expect.soft(await searchedFiles(server.port, 'c-cometnova')).toEqual([cName]);
+ await subscription.deliver([], new Error(notices[0]));
+ await dependentRole(bName);
+ expect(readFileSync(c, 'utf8')).toBe('separate,role,target\n');
+ expect(readFileSync(a, 'utf8')).toBe('same,role\n');
+ } finally {
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+});
+
+test('an absent former target and a later denied dependent read leave the prior group intact', async () => {
+ const a = writeDoc('a.csv', 'a,group\n');
+ const b = join(contentDir, 'b.csv');
+ const c = writeDoc('c.csv', 'c,group\n');
+ const survivor = join(contentDir, 'c-survivor.csv');
+ const dependent = join(contentDir, 'y-dependent.csv');
+ const survivorAlias = join(contentDir, 'z-survivor.csv');
+ symlinkSync(c, b);
+ linkSync(c, survivor);
+ symlinkSync(b, dependent);
+ symlinkSync(survivor, survivorAlias);
+ const { watcher, events } = await watchContent();
+ expect(realpathSync(dependent)).toBe(c);
+ expect(realpathSync(survivorAlias)).toBe(survivor);
+ const prior = indexedAliasOwner(watcher, 'b.csv');
+ expect(prior).toBeDefined();
+ expect(prior?.aliases).toEqual(
+ expect.arrayContaining(['b.csv', 'y-dependent.csv', 'z-survivor.csv']),
+ );
+ unlinkSync(c);
+ expect(existsSync(c)).toBe(false);
+ expect(readFileSync(survivor, 'utf8')).toBe('c,group\n');
+ unlinkSync(b);
+ linkSync(a, b);
+ expect(realpathSync(dependent)).toBe(b);
+ const later = writeDoc('later.csv', 'later\n');
+ denyAdmission('realpath', survivorAlias);
+ events.length = 0;
+ await deliver(contentDir, [
+ { type: 'update', path: b },
+ { type: 'create', path: later },
+ ]);
+ expect.soft(admissionFault.observed).toBe(true);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: later, relativePath: 'later.csv' }),
+ );
+ expect.soft(indexedAliasOwner(watcher, 'b.csv')).toEqual(prior);
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual(
+ [
+ 'a.csv',
+ 'b.csv',
+ 'c.csv',
+ 'c-survivor.csv',
+ 'later.csv',
+ 'y-dependent.csv',
+ 'z-survivor.csv',
+ ].toSorted(),
+ );
+ clearAdmissionDenial();
+ await deliverNotice(contentDir);
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual(
+ [
+ 'a.csv',
+ 'b.csv',
+ 'c-survivor.csv',
+ 'later.csv',
+ 'y-dependent.csv',
+ 'z-survivor.csv',
+ ].toSorted(),
+ );
+ expect(readFileSync(a, 'utf8')).toBe('a,group\n');
+ expect(readFileSync(survivor, 'utf8')).toBe('c,group\n');
+});
+
+test.each(['startup', 'recovery'] as const)(
+ 'a role change observed during a %s scan keeps ignored dependent targets out of the index',
+ async (scan) => {
+ const x = writeDoc('x.csv', 'x,bytes\n');
+ const c = writeDoc('c.csv', 'c,bytes\n');
+ const blocked = writeDoc('blocked.csv', 'ignored,bytes\n');
+ const r = join(contentDir, 'r.csv');
+ const l = join(contentDir, 'l.csv');
+ symlinkSync(x, r);
+ symlinkSync(x, l);
+ writeDoc('.okignore', 'blocked.csv\n');
+ const filter = dynamicSkillFilter();
+ expect(filter.isPathIgnored('blocked.csv')).toBe(true);
+ const entered = deferred();
+ const resume = deferred();
+ const holdScan = () => {
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['r.csv', 'l.csv', 'x.csv'];
+ memberStatSchedule.path = l;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ };
+ if (scan === 'startup') holdScan();
+ const started = watchContent(filter);
+ let pending: Promise<unknown> = started;
+ if (scan === 'recovery') {
+ const { watcher } = await started;
+ expect(
+ [...(localTargetInventoryFromWatcher(watcher, contentDir)?.fileTargets ?? [])].toSorted(),
+ ).toEqual(['.okignore', 'c.csv', 'l.csv', 'r.csv', 'x.csv']);
+ holdScan();
+ pending = deliverNotice(contentDir);
+ }
+ try {
+ await entered.promise;
+ unlinkSync(x);
+ symlinkSync(c, x);
+ unlinkSync(r);
+ symlinkSync(blocked, r);
+ expect(realpathSync(x)).toBe(c);
+ expect(realpathSync(r)).toBe(blocked);
+ } finally {
+ resume.release();
+ await pending;
+ }
+ const { watcher } = await started;
+ const generalMembers = [...watcher.getAllFilesIndex()].flatMap(([name, entry]) =>
+ entry.kind === 'file'
+ ? [
+ name,
+ ...(entry.fileMembers?.regularPaths ?? []),
+ ...(entry.fileMembers?.symlinks.map((relation) => relation.path) ?? []),
+ ]
+ : [],
+ );
+ expect([...new Set(generalMembers)].toSorted()).toEqual([
+ '.okignore',
+ 'c.csv',
+ 'l.csv',
+ 'x.csv',
+ ]);
+ expect(generalMembers).not.toContain('blocked.csv');
+ expect(generalMembers).not.toContain('r.csv');
+ },
+);
+
+test('a role change removes absent and ignored dependents while retaining accepted relations', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const a = writeDoc('a.csv', 'old,group\n');
+ const b = join(contentDir, 'b.csv');
+ const c = writeDoc('c.csv', 'new,group\n');
+ const ignored = writeDoc('blocked.csv', 'ignored,group\n');
+ const y = join(contentDir, 'y-alias.csv');
+ const missing = join(contentDir, 'm-removed.csv');
+ const rejected = join(contentDir, 'q-rejected.csv');
+ const z = join(contentDir, 'z-unrelated.csv');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ symlinkSync(a, missing);
+ symlinkSync(b, rejected);
+ symlinkSync(a, z);
+ writeDoc('.okignore', 'blocked.csv\n');
+ const filter = dynamicSkillFilter();
+ expect(filter.isPathIgnored('blocked.csv')).toBe(true);
+ expect(filter.isPathIgnored('q-rejected.csv')).toBe(false);
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const initial = await listedEntries(server.port);
+ for (const name of ['y-alias.csv', 'm-removed.csv', 'q-rejected.csv', 'z-unrelated.csv']) {
+ expect(initial.filter((row) => row.kind === 'file' && row.docName === name)).toHaveLength(1);
+ }
+ expect(realpathSync(missing)).toBe(a);
+ unlinkSync(missing);
+ unlinkSync(rejected);
+ symlinkSync(ignored, rejected);
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect(existsSync(missing)).toBe(false);
+ expect(realpathSync(rejected)).toBe(ignored);
+ expect(realpathSync(y)).toBe(c);
+ expect(realpathSync(z)).toBe(a);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const settled = await listedEntries(server.port);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'b.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: 'c.csv' })]);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'y-alias.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: 'c.csv' })]);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'm-removed.csv'))
+ .toEqual([]);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'q-rejected.csv'))
+ .toEqual([]);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'a.csv'))
+ .toHaveLength(1);
+ expect
+ .soft(settled.filter((row) => row.kind === 'file' && row.docName === 'z-unrelated.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: 'a.csv' })]);
+ expect.soft(await searchedFiles(server.port, 'y-alias')).toEqual(['c.csv']);
+ expect.soft(await searchedFiles(server.port, 'q-rejected')).toEqual([]);
+ await subscription.deliver([], new Error(notices[0]));
+ const afterNotice = await listedEntries(server.port);
+ expect
+ .soft(afterNotice.filter((row) => row.kind === 'file' && row.docName === 'y-alias.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: 'c.csv' })]);
+ expect
+ .soft(afterNotice.filter((row) => row.kind === 'file' && row.docName === 'q-rejected.csv'))
+ .toEqual([]);
+ expect(readFileSync(a, 'utf8')).toBe('old,group\n');
+ expect(readFileSync(c, 'utf8')).toBe('new,group\n');
+ } finally {
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+});
+
+test('an actual alias retargets across member names and physical groups without moving its siblings', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const aName = 'a-amberpilot.csv';
+ const bName = 'b-beaconquartz.csv';
+ const cName = 'c-cometnova.csv';
+ const a = writeDoc(aName, 'same,group\n');
+ const b = join(contentDir, bName);
+ const c = writeDoc(cName, 'other,group\n');
+ const y = join(contentDir, 'y-aliasindigo.csv');
+ const z = join(contentDir, 'z-aliasviolet.csv');
+ linkSync(a, b);
+ symlinkSync(a, y);
+ symlinkSync(b, z);
+ const server = await bootInventoryServer();
+ try {
+ const subscription = nativeSubscriptionOn(contentDir);
+ await subscription.deliver([{ type: 'update', path: b }]);
+ const aliasRows = async (name: string) =>
+ (await listedEntries(server.port)).filter(
+ (row) => row.kind === 'file' && row.docName === name,
+ );
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ expect(realpathSync(y)).toBe(a);
+ expect(realpathSync(z)).toBe(b);
+
+ unlinkSync(y);
+ symlinkSync(b, y);
+ await subscription.deliver([{ type: 'update', path: y }]);
+ expect
+ .soft(await aliasRows('y-aliasindigo.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+ expect
+ .soft(await aliasRows('z-aliasviolet.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+ expect.soft(await searchedFiles(server.port, 'y-aliasindigo')).toEqual([aName]);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+
+ unlinkSync(y);
+ symlinkSync(c, y);
+ await subscription.deliver([], new Error(notices[0]));
+ expect
+ .soft(await aliasRows('y-aliasindigo.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: cName })]);
+ expect.soft(await searchedFiles(server.port, 'y-aliasindigo')).toEqual([cName]);
+ expect.soft(await searchedFiles(server.port, 'b-beaconquartz')).toEqual([aName]);
+ expect
+ .soft(await aliasRows('z-aliasviolet.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+
+ unlinkSync(y);
+ await subscription.deliver([{ type: 'delete', path: y }]);
+ expect.soft(await aliasRows('y-aliasindigo.csv')).toEqual([]);
+ expect.soft(await searchedFiles(server.port, 'y-aliasindigo')).toEqual([]);
+ await subscription.deliver([], new Error(notices[0]));
+ expect.soft(await aliasRows('y-aliasindigo.csv')).toEqual([]);
+ expect
+ .soft(await aliasRows('z-aliasviolet.csv'))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: bName })]);
+ expect(readFileSync(a, 'utf8')).toBe('same,group\n');
+ expect(readFileSync(b, 'utf8')).toBe('same,group\n');
+ expect(readFileSync(c, 'utf8')).toBe('other,group\n');
+ } finally {
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+});
+
+test('a denied actual former target preserves its hardlink group and later record until recovery', async () => {
+ const a = writeDoc('a.csv', 'prior,shared\n');
+ const blocked = join(contentDir, 'blocked');
+ mkdirSync(blocked);
+ const b = join(blocked, 'b.csv');
+ const c = writeDoc('other.csv', 'other,content\n');
+ const y = join(contentDir, 'y-alias.csv');
+ const z = join(contentDir, 'z-alias.csv');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ symlinkSync(a, z);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'blocked', 'other.csv', 'y-alias.csv', 'z-alias.csv'];
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(realpathSync(y)).toBe(b);
+ expect
+ .soft(indexedFileTargets(watcher))
+ .toEqual(['a.csv', 'blocked/b.csv', 'other.csv', 'y-alias.csv', 'z-alias.csv'].toSorted());
+ const formerOwner = indexedAliasOwner(watcher, 'y-alias.csv');
+ expect(formerOwner).toMatchObject({
+ canonicalPath: a,
+ size: statSync(a).size,
+ modified: statSync(a).mtime.toISOString(),
+ inode: Number(statSync(a).ino),
+ aliases: expect.arrayContaining(['y-alias.csv', 'z-alias.csv']),
+ });
+
+ unlinkSync(y);
+ symlinkSync(c, y);
+ const later = writeDoc('later.csv', 'later,record\n');
+ denyAdmission('realpath', b);
+ deniedDirectoryRead.path = blocked;
+ await deliverNotice(contentDir, [
+ { type: 'update', path: y },
+ { type: 'create', path: later },
+ ]);
+ expect.soft(admissionFault.observed).toBe(true);
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', path: later, relativePath: 'later.csv' }),
+ );
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect(completed).toEqual([]);
+ expect(readFileSync(a, 'utf8')).toBe('prior,shared\n');
+ expect(readFileSync(b, 'utf8')).toBe('prior,shared\n');
+ expect.soft(indexedFileTargets(watcher)).toContain('blocked/b.csv');
+ expect.soft(indexedFileTargets(watcher)).toContain('z-alias.csv');
+ expect.soft(indexedFileTargets(watcher)).toContain('later.csv');
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')).toMatchObject({
+ canonicalPath: a,
+ size: formerOwner?.size,
+ modified: formerOwner?.modified,
+ inode: formerOwner?.inode,
+ aliases: expect.arrayContaining(['y-alias.csv', 'z-alias.csv']),
+ });
+ expect.soft(indexedAliasOwner(watcher, 'z-alias.csv')?.canonicalPath).toBe(a);
+
+ clearAdmissionDenial();
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect.soft(indexedFileTargets(watcher)).toContain('a.csv');
+ expect.soft(indexedFileTargets(watcher)).toContain('blocked/b.csv');
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.canonicalPath).toBe(c);
+});
+
+test('filter rebuild prunes individual hardlink paths and aliases before positive reseeding', async () => {
+ const a = writeDoc('a.csv', 'filter,shared\n');
+ const b = join(contentDir, 'b.csv');
+ const document = writeDoc('a.csv.md', '# Document stays\n');
+ const z = join(contentDir, 'z-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(a, z);
+ symlinkSync(b, y);
+ const ignore = writeDoc('.okignore', 'a.csv\n');
+ const filter = dynamicSkillFilter();
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv', 'a.csv.md'];
+ const { watcher, events } = await watchContent(filter);
+ const memberRows = () =>
+ indexedGeneralRows(watcher).filter((row) => row.inode === statSync(a).ino);
+ const memberTargets = () => indexedFileTargets(watcher).filter((name) => name !== '.okignore');
+ expect(filter.isPathIgnored('a.csv')).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(false);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect.soft(memberRows()).toHaveLength(1);
+ expect.soft(memberTargets()).toEqual(['b.csv', 'y-alias.csv']);
+ expect(watcher.getFileIndex().get('a.csv')?.canonicalPath).toBe(document);
+
+ writeFileSync(ignore, '');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ await reconcileFileIndexAfterFilterRebuild(watcher);
+ expect.soft(memberRows()).toHaveLength(1);
+ expect.soft(memberTargets()).toEqual(['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv'].toSorted());
+
+ for (const phase of [
+ {
+ ignored: 'y-alias.csv\n',
+ expected: ['a.csv', 'b.csv', 'z-alias.csv'],
+ removedGroups: 0,
+ },
+ {
+ ignored: 'b.csv\n',
+ expected: ['a.csv', 'z-alias.csv'],
+ removedGroups: 0,
+ },
+ { ignored: 'b.csv\na.csv\n', expected: [], removedGroups: 1 },
+ ]) {
+ if (phase.ignored === 'b.csv\n') {
+ writeFileSync(ignore, '');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ await reconcileFileIndexAfterFilterRebuild(watcher);
+ expect(filter.isPathIgnored('y-alias.csv')).toBe(false);
+ expect.soft(memberTargets()).toContain('y-alias.csv');
+ expect.soft(memberTargets()).toContain('b.csv');
+ }
+ writeFileSync(ignore, phase.ignored);
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ const generation = watcher.getFileIndexGeneration();
+ const cached = localTargetInventoryFromWatcher(watcher, contentDir);
+ const removed = watcher.pruneFileIndexNowExcluded();
+ expect.soft(removed).toBe(phase.removedGroups);
+ expect.soft(watcher.getFileIndexGeneration()).toBeGreaterThan(generation);
+ expect.soft(localTargetInventoryFromWatcher(watcher, contentDir)).not.toBe(cached);
+ expect.soft(memberTargets()).toEqual(phase.expected.toSorted());
+ await watcher.rescanFromDisk();
+ expect.soft(memberTargets()).toEqual(phase.expected.toSorted());
+ expect(watcher.getFileIndex().get('a.csv')?.canonicalPath).toBe(document);
+ }
+
+ writeFileSync(ignore, '');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ await reconcileFileIndexAfterFilterRebuild(watcher);
+ expect.soft(memberRows()).toHaveLength(1);
+ expect.soft(memberTargets()).toEqual(['a.csv', 'b.csv', 'y-alias.csv', 'z-alias.csv'].toSorted());
+ expect(events).toEqual([]);
+ expect(readFileSync(document, 'utf8')).toBe('# Document stays\n');
+});
+
+test('a positive reseed retains unseen members and an incomplete notice defers their removal', async () => {
+ const a = writeDoc('a.csv', 'partial,shared\n');
+ const nested = join(contentDir, 'nested');
+ mkdirSync(nested);
+ const b = join(nested, 'b.csv');
+ linkSync(a, b);
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ const c = join(contentDir, 'c.csv');
+ linkSync(a, c);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(c).dev, statSync(c).ino]);
+ const beforeReseed = [...events];
+ deniedDirectoryRead.path = nested;
+ await watcher.rescanFromDisk();
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect.soft(events).toEqual(beforeReseed);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'c.csv', 'nested/b.csv'].toSorted());
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: b, relativePath: 'nested/b.csv' }),
+ );
+
+ unlinkSync(b);
+ deniedDirectoryRead.path = nested;
+ const before = [...events];
+ await deliverNotice(contentDir);
+ expect(deniedDirectoryRead.path).toBeNull();
+ expect(completed).toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toContain('nested/b.csv');
+ expect(events).toEqual(before);
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-delete', path: b, relativePath: 'nested/b.csv' }),
+ );
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'c.csv']);
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === a))
+ .toEqual([]);
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === c))
+ .toEqual([]);
+ expect(readFileSync(a, 'utf8')).toBe('partial,shared\n');
+ expect(readFileSync(c, 'utf8')).toBe('partial,shared\n');
+});
+
+test('a public update to one member before synthesis does not suppress another member deletion', async () => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ const z = join(contentDir, 'z-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ linkSync(a, b);
+ symlinkSync(a, z);
+ symlinkSync(b, y);
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ events.length = 0;
+ unlinkSync(a);
+ expect(existsSync(a)).toBe(false);
+ expect(readFileSync(b, 'utf8')).toBe('old,shared\n');
+ const entered = deferred();
+ const resume = deferred();
+ scanSchedule.holdPath = contentDir;
+ scanSchedule.entered = entered.release;
+ scanSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ let publicStat: ReturnType<typeof statSync> | undefined;
+ try {
+ await entered.promise;
+ writeFileSync(b, 'newer,public,metadata\n');
+ publicStat = statSync(b);
+ watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: publicStat.size,
+ modifiedTs: publicStat.mtimeMs,
+ inode: Number(publicStat.ino),
+ });
+ } finally {
+ resume.release();
+ await pending;
+ }
+ expect(publicStat).toBeDefined();
+ expect(completed).toEqual(['complete']);
+ expect(readFileSync(b, 'utf8')).toBe('newer,public,metadata\n');
+ expect.soft(events).toContainEqual(expect.objectContaining({ kind: 'file-delete', path: a }));
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === b))
+ .toEqual([]);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['b.csv', 'y-alias.csv']);
+ expect.soft(indexedGeneralRows(watcher)[0]?.size).toBe(publicStat?.size);
+ expect.soft(indexedFileTargets(watcher)).not.toContain('z-alias.csv');
+});
+
+test('a public symlink transfer during recovery keeps its dependent without protecting another member', async () => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ const c = writeDoc('c.csv', 'new,target\n');
+ const y = join(contentDir, 'y-alias.csv');
+ const trigger = writeDoc('trigger.md', '# Trigger\n');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ let callbackCount = 0;
+ let watcher: WatcherHandle | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'trigger') return;
+ callbackCount++;
+ unlinkSync(b);
+ symlinkSync(c, b);
+ const st = statSync(b);
+ watcher?.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ });
+ expect(realpathSync(y)).toBe(c);
+ const active = watcher;
+ if (!active) throw new Error('watcher not ready');
+ expect.soft(indexedAliasOwner(active, 'y-alias.csv')?.canonicalPath).toBe(c);
+ expect.soft(indexedFileTargets(active)).toContain('y-alias.csv');
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(realpathSync(y)).toBe(b);
+ events.length = 0;
+ unlinkSync(a);
+ unlinkSync(trigger);
+ expect(existsSync(a)).toBe(false);
+ expect(readFileSync(b, 'utf8')).toBe('old,shared\n');
+ await deliverNotice(contentDir);
+ expect(callbackCount).toBe(1);
+ expect(completed).toEqual(['complete']);
+ expect.soft(events).toContainEqual(expect.objectContaining({ kind: 'file-delete', path: a }));
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedGeneralRows(watcher)[0]?.canonicalPath).toBe(c);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['b.csv', 'c.csv', 'y-alias.csv']);
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.canonicalPath).toBe(c);
+ expect.soft(indexedFileTargets(watcher)).not.toContain('a.csv');
+ await deliverNotice(contentDir);
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.canonicalPath).toBe(c);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['b.csv', 'c.csv', 'y-alias.csv']);
+ expect(readFileSync(c, 'utf8')).toBe('new,target\n');
+});
+
+test('a public update after synthesis retains an unrelated member replacement', async () => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ const trigger = writeDoc('trigger.md', '# Trigger\n');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ let callbackCount = 0;
+ let publicBModifiedTs: number | undefined;
+ let watcher: WatcherHandle | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'trigger') return;
+ callbackCount++;
+ writeFileSync(b, 'newer,old,group\n');
+ const st = statSync(b);
+ publicBModifiedTs = st.mtimeMs;
+ watcher?.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ });
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ events.length = 0;
+ const temporary = writeDoc('replacement-temporary.csv', 'new,a,identity\n');
+ renameSync(temporary, a);
+ expect(statSync(a).ino).not.toBe(statSync(b).ino);
+ unlinkSync(trigger);
+ await deliverNotice(contentDir);
+ expect(callbackCount).toBe(1);
+ if (publicBModifiedTs === undefined) throw new Error('public b update was not observed');
+ expect(completed).toEqual(['complete']);
+ expect(readFileSync(a, 'utf8')).toBe('new,a,identity\n');
+ expect(readFileSync(b, 'utf8')).toBe('newer,old,group\n');
+ expect.soft(events).toContainEqual(expect.objectContaining({ kind: 'file-update', path: a }));
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(2);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'y-alias.csv']);
+ expect.soft(indexedGeneralRows(watcher).find((row) => row.name === 'a.csv')).toMatchObject({
+ canonicalPath: a,
+ inode: Number(statSync(a).ino),
+ size: statSync(a).size,
+ modified: statSync(a).mtime.toISOString(),
+ });
+ expect.soft(indexedGeneralRows(watcher).find((row) => row.name === 'b.csv')).toMatchObject({
+ canonicalPath: b,
+ inode: Number(statSync(b).ino),
+ size: statSync(b).size,
+ modified: new Date(publicBModifiedTs).toISOString(),
+ });
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.canonicalPath).toBe(b);
+ expect
+ .soft(indexedGeneralRows(watcher).find((row) => row.name === 'b.csv')?.size)
+ .toBe(statSync(b).size);
+});
+
+test('the latest public member tombstone survives an older scan without rolling back group metadata', async () => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ const trigger = writeDoc('trigger.md', '# Trigger\n');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ const events: DiskEvent[] = [];
+ let callbackCount = 0;
+ let sharedPublicModifiedTs: number | undefined;
+ let watcher: WatcherHandle | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'delete' || event.docName !== 'trigger') return;
+ callbackCount++;
+ writeFileSync(b, 'newer,shared,content\n');
+ const sharedStat = statSync(b);
+ sharedPublicModifiedTs = sharedStat.mtimeMs;
+ watcher?.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: sharedStat.size,
+ modifiedTs: sharedStat.mtimeMs,
+ inode: Number(sharedStat.ino),
+ });
+ const temporary = writeDoc('replacement-temporary.csv', 'replacement\n');
+ renameSync(temporary, b);
+ const replacementStat = statSync(b);
+ watcher?.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: replacementStat.size,
+ modifiedTs: replacementStat.mtimeMs,
+ inode: Number(replacementStat.ino),
+ });
+ unlinkSync(b);
+ watcher?.mutateFileIndex({ kind: 'file-delete', path: b, relativePath: 'b.csv' });
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ events.length = 0;
+ unlinkSync(trigger);
+ await deliverNotice(contentDir);
+ expect(callbackCount).toBe(1);
+ if (sharedPublicModifiedTs === undefined)
+ throw new Error('shared public update was not observed');
+ expect(existsSync(b)).toBe(false);
+ expect(readFileSync(a, 'utf8')).toBe('newer,shared,content\n');
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv']);
+ expect.soft(indexedGeneralRows(watcher)[0]?.size).toBe(statSync(a).size);
+ expect
+ .soft(indexedGeneralRows(watcher)[0]?.modified)
+ .toBe(new Date(sharedPublicModifiedTs).toISOString());
+ expect.soft(indexedFileTargets(watcher)).not.toContain('y-alias.csv');
+ expect(lastKnownHash.has(a)).toBe(false);
+ expect(lastKnownHash.has(b)).toBe(false);
+});
+
+test('index-only reseed merges an observed sibling with a newer public hardlink update', async () => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ linkSync(a, b);
+ const { watcher, events } = await watchContent();
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ events.length = 0;
+ const c = join(contentDir, 'c.csv');
+ linkSync(a, c);
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.path = b;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending = watcher.rescanFromDisk();
+ let publicStat: ReturnType<typeof statSync> | undefined;
+ try {
+ await entered.promise;
+ writeFileSync(b, 'newer,public,shared\n');
+ publicStat = statSync(b);
+ watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: publicStat.size,
+ modifiedTs: publicStat.mtimeMs,
+ inode: Number(publicStat.ino),
+ });
+ } finally {
+ resume.release();
+ await pending;
+ }
+ expect(publicStat).toBeDefined();
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(c).dev, statSync(c).ino]);
+ expect(readFileSync(a, 'utf8')).toBe('newer,public,shared\n');
+ expect(readFileSync(c, 'utf8')).toBe('newer,public,shared\n');
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'c.csv']);
+ expect.soft(indexedGeneralRows(watcher)[0]?.size).toBe(publicStat?.size);
+ expect(events).toEqual([]);
+ expect(lastKnownHash.has(a)).toBe(false);
+ expect(lastKnownHash.has(b)).toBe(false);
+});
+
+test.each(['known-member', 'new-member'] as const)(
+ 'a public $0 registration remains nonthrowing when physical enrichment is denied',
+ async (input) => {
+ const a = writeDoc('a.csv', 'public,shared\n');
+ const b = join(contentDir, 'b.csv');
+ if (input === 'known-member') linkSync(a, b);
+ const { watcher } = await watchContent();
+ if (input === 'known-member') {
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+ } else {
+ linkSync(a, b);
+ }
+ const y = join(contentDir, 'y-alias.csv');
+ symlinkSync(b, y);
+ if (input === 'known-member') await deliver(contentDir, [{ type: 'create', path: y }]);
+ let expectedBytes = 'public,shared\n';
+ let priorIndexedSize: number | undefined;
+ if (input === 'known-member') {
+ priorIndexedSize = indexedAliasOwner(watcher, 'y-alias.csv')?.size;
+ expect(priorIndexedSize).toBeDefined();
+ expectedBytes = 'public,updated,member,metadata\n';
+ writeFileSync(b, expectedBytes);
+ }
+ const st = statSync(b);
+ if (input === 'known-member') expect(st.size).not.toBe(priorIndexedSize);
+ denyAdmission('lstat', b);
+ expect(() =>
+ watcher.mutateFileIndex({
+ kind: input === 'known-member' ? 'file-update' : 'file-create',
+ path: b,
+ relativePath: 'b.csv',
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ }),
+ ).not.toThrow();
+ expect.soft(admissionFault.observed).toBe(true);
+ expect.soft(indexedFileTargets(watcher)).toContain('a.csv');
+ expect.soft(indexedFileTargets(watcher)).toContain('b.csv');
+ if (input === 'known-member') {
+ expect.soft(indexedFileTargets(watcher)).toContain('y-alias.csv');
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.size).toBe(st.size);
+ expect
+ .soft(indexedAliasOwner(watcher, 'y-alias.csv')?.modified)
+ .toBe(new Date(st.mtimeMs).toISOString());
+ expect.soft(indexedAliasOwner(watcher, 'y-alias.csv')?.aliases).toContain('y-alias.csv');
+ }
+ expect(readFileSync(a, 'utf8')).toBe(expectedBytes);
+ expect(readFileSync(b, 'utf8')).toBe(expectedBytes);
+ clearAdmissionDenial();
+ await deliverNotice(contentDir);
+ expect.soft(indexedGeneralRows(watcher)).toHaveLength(1);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'y-alias.csv']);
+ },
+);
+
+test('a stale public file-create still registers without a new read failure and then reconciles', async () => {
+ const a = writeDoc('a.csv', 'present\n');
+ const { watcher } = await watchContent();
+ const stale = writeDoc('stale.csv', 'gone\n');
+ const st = statSync(stale);
+ unlinkSync(stale);
+ expect(existsSync(stale)).toBe(false);
+ expect(() =>
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: stale,
+ relativePath: 'stale.csv',
+ size: st.size,
+ modifiedTs: st.mtimeMs,
+ inode: Number(st.ino),
+ }),
+ ).not.toThrow();
+ expect.soft(indexedFileTargets(watcher)).toContain('stale.csv');
+ await deliverNotice(contentDir);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv']);
+ expect(readFileSync(a, 'utf8')).toBe('present\n');
+});
+
+test('legacy mixed-Map helpers expose general mutation before their public callback', async () => {
+ const file = writeDoc('legacy.csv', 'first\n');
+ const index = new Map<string, import('./file-watcher.ts').FileIndexEntry>();
+ const folders = new Map<string, import('./file-watcher.ts').FolderIndexEntry>();
+ const observed: Array<{ kind: string; present: boolean; size?: number }> = [];
+ const dispatch = async (type: 'create' | 'update' | 'delete') =>
+ handleRawEvents(
+ [{ type, path: file }],
+ contentDir,
+ undefined,
+ index,
+ folders,
+ async (event) => {
+ observed.push({
+ kind: event.kind,
+ present: index.has('legacy.csv'),
+ size: index.get('legacy.csv')?.size,
+ });
+ },
+ );
+ await dispatch('create');
+ expect(observed.at(-1)).toMatchObject({ kind: 'file-create', present: true, size: 6 });
+ writeFileSync(file, 'second,longer\n');
+ await dispatch('update');
+ expect(observed.at(-1)).toMatchObject({
+ kind: 'file-update',
+ present: true,
+ size: Buffer.byteLength('second,longer\n'),
+ });
+ unlinkSync(file);
+ await dispatch('delete');
+ expect(observed.at(-1)).toMatchObject({ kind: 'file-delete', present: false });
+ updateFileIndex(
+ {
+ kind: 'file-create',
+ path: file,
+ relativePath: 'legacy.csv',
+ size: 3,
+ modifiedTs: 0,
+ inode: 7,
+ },
+ index,
+ );
+ expect(index.get('legacy.csv')).toMatchObject({ kind: 'file', size: 3, inode: 7 });
+ updateFileIndex({ kind: 'file-delete', path: file, relativePath: 'legacy.csv' }, index);
+ expect(index.has('legacy.csv')).toBe(false);
+});
+
+test.each([
+ ['symlink-to-regular', 'ordinary'],
+ ['symlink-to-regular', 'notice'],
+ ['regular-to-symlink', 'ordinary'],
+ ['regular-to-symlink', 'notice'],
+] as const)(
+ 'a surviving general pathname changes from %s after %s delivery without a deletion',
+ async (transition, delivery) => {
+ const a = writeDoc('a.csv', 'same,physical,bytes\n');
+ const y = join(contentDir, 'y.csv');
+ if (transition === 'symlink-to-regular') symlinkSync(a, y);
+ else linkSync(a, y);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'y.csv'];
+ const { watcher, events } = await watchContent();
+ expect(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+ expect(lstatSync(y).isSymbolicLink()).toBe(transition === 'symlink-to-regular');
+ expect(readFileSync(y, 'utf8')).toBe('same,physical,bytes\n');
+ unlinkSync(y);
+ if (transition === 'symlink-to-regular') linkSync(a, y);
+ else symlinkSync(a, y);
+ expect(existsSync(y)).toBe(true);
+ expect(lstatSync(y).isSymbolicLink()).toBe(transition === 'regular-to-symlink');
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(y).dev, statSync(y).ino]);
+ expect(readFileSync(y, 'utf8')).toBe('same,physical,bytes\n');
+
+ if (delivery === 'ordinary') await deliver(contentDir, [{ type: 'update', path: y }]);
+ else await deliverNotice(contentDir);
+
+ expect(
+ events.some((event) => event.kind === 'file-create' || event.kind === 'file-update'),
+ ).toBe(true);
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ (event.kind === 'file-delete' || event.kind === 'asset-delete') && event.path === y,
+ ),
+ )
+ .toEqual([]);
+ expect
+ .soft(events)
+ .toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: y, relativePath: 'y.csv' }),
+ );
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect.soft(events).toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+ expect(readFileSync(y, 'utf8')).toBe('same,physical,bytes\n');
+ },
+);
+
+test('a public recreation during the first alias deletion cancels the pending second alias deletion', async () => {
+ const a = writeDoc('a.csv', 'same,alias,target\n');
+ const x = join(contentDir, 'x.csv');
+ const y = join(contentDir, 'y.csv');
+ symlinkSync(a, x);
+ symlinkSync(a, y);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'x.csv', 'y.csv'];
+ const entered = deferred();
+ const resume = deferred();
+ const { watcher, events } = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'file-delete' || event.path !== x) return;
+ entered.release();
+ await resume.promise;
+ });
+ expect(indexedFileTargets(watcher)).toEqual(['a.csv', 'x.csv', 'y.csv']);
+ expect(lstatSync(x).isSymbolicLink()).toBe(true);
+ expect(lstatSync(y).isSymbolicLink()).toBe(true);
+ unlinkSync(x);
+ unlinkSync(y);
+ expect(existsSync(x)).toBe(false);
+ expect(existsSync(y)).toBe(false);
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ symlinkSync(a, y);
+ const stat = statSync(y);
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: y,
+ relativePath: 'y.csv',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ expect(lstatSync(y).isSymbolicLink()).toBe(true);
+ expect(realpathSync(y)).toBe(a);
+ expect(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+ } finally {
+ resume.release();
+ await pending;
+ }
+ await vi.runAllTimersAsync();
+ expect(events).toContainEqual({ kind: 'file-delete', path: x, relativePath: 'x.csv' });
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ (event.kind === 'file-delete' || event.kind === 'asset-delete') && event.path === y,
+ ),
+ )
+ .toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+ expect(readFileSync(y, 'utf8')).toBe('same,alias,target\n');
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ 'path' in event &&
+ (event.path === x ||
+ event.path === y ||
+ ((event.kind === 'file-delete' || event.kind === 'asset-delete') && event.path === a)),
+ ),
+ )
+ .toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual(['a.csv', 'y.csv']);
+});
+
+test('removing a second retargeted alias during the first alias callback cancels its pending target update', async () => {
+ const a = writeDoc('a.csv', 'first,target\n');
+ const b = writeDoc('b.csv', 'second,target\n');
+ const x = join(contentDir, 'x.csv');
+ const y = join(contentDir, 'y.csv');
+ symlinkSync(a, x);
+ symlinkSync(b, y);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'x.csv', 'y.csv'];
+ const entered = deferred();
+ const resume = deferred();
+ let firstTarget: string | undefined;
+ let pendingTarget: string | undefined;
+ let pendingAlias: string | undefined;
+ let pendingAlreadyEmitted = false;
+ const { watcher, events } = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'file-update' || (event.path !== a && event.path !== b)) return;
+ if (firstTarget !== undefined) return;
+ firstTarget = event.path;
+ pendingTarget = event.path === a ? b : a;
+ pendingAlias = event.path === a ? x : y;
+ pendingAlreadyEmitted = events.some(
+ (emitted) => emitted.kind === 'file-update' && emitted.path === pendingTarget,
+ );
+ entered.release();
+ await resume.promise;
+ });
+ expect(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'x.csv', 'y.csv']);
+ expect(realpathSync(x)).toBe(a);
+ expect(realpathSync(y)).toBe(b);
+ unlinkSync(x);
+ unlinkSync(y);
+ symlinkSync(b, x);
+ symlinkSync(a, y);
+ expect(realpathSync(x)).toBe(b);
+ expect(realpathSync(y)).toBe(a);
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ const aliasToRemove = pendingAlias;
+ const targetStillPending = pendingTarget;
+ if (aliasToRemove === undefined || targetStillPending === undefined) {
+ throw new Error('first target update did not identify a pending alias');
+ }
+ expect(pendingAlreadyEmitted).toBe(false);
+ expect(
+ events.filter((event) => event.kind === 'file-update' && event.path === targetStillPending),
+ ).toEqual([]);
+ unlinkSync(aliasToRemove);
+ watcher.mutateFileIndex({
+ kind: 'file-delete',
+ path: aliasToRemove,
+ relativePath: basename(aliasToRemove),
+ });
+ expect(existsSync(aliasToRemove)).toBe(false);
+ expect(indexedFileTargets(watcher)).toEqual(
+ ['a.csv', 'b.csv', basename(aliasToRemove === x ? y : x)].toSorted(),
+ );
+ } finally {
+ resume.release();
+ await pending;
+ }
+ await vi.runAllTimersAsync();
+ const emittedFirst = firstTarget;
+ const targetStillPending = pendingTarget;
+ const removedAlias = pendingAlias;
+ if (
+ emittedFirst === undefined ||
+ targetStillPending === undefined ||
+ removedAlias === undefined
+ ) {
+ throw new Error('alias notification ordering was not observed');
+ }
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: emittedFirst }),
+ );
+ expect
+ .soft(
+ events.filter((event) => event.kind === 'file-update' && event.path === targetStillPending),
+ )
+ .toEqual([]);
+ const expectedTargets = ['a.csv', 'b.csv', basename(removedAlias === x ? y : x)].toSorted();
+ expect.soft(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ events.length = 0;
+ await deliverNotice(contentDir);
+ expect.soft(events).toEqual([]);
+ expect.soft(indexedFileTargets(watcher)).toEqual(expectedTargets);
+});
+
+test('a completed within-branch notice remains exact after its buffered target events drain', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const gitEnv = {
+ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+ GIT_CONFIG_GLOBAL: '/dev/null',
+ GIT_CONFIG_NOSYSTEM: '1',
+ };
+ const git = (args: string[]) =>
+ execFileSync('git', args, { cwd: contentDir, env: gitEnv, encoding: 'utf8' }).trim();
+ git(['init', '--quiet', '--initial-branch=main']);
+ git(['config', 'user.email', '[email protected]']);
+ git(['config', 'user.name', 'Notice Test']);
+ const a = writeDoc('a.csv', 'same,physical,bytes\n');
+ const y = join(contentDir, 'y.csv');
+ symlinkSync(a, y);
+ writeDoc('source.md', '# Source\n\n[File](y.csv)\n');
+ git(['add', '-A']);
+ git(['commit', '--quiet', '-m', 'initial files']);
+ const batchBegun = deferred();
+ const batchHold = deferred();
+ const batchEnded = deferred();
+ headBatchSchedule.begun = batchBegun.release;
+ headBatchSchedule.hold = batchHold.promise;
+ headBatchSchedule.ended = batchEnded.release;
+ headBatchSchedule.armed = true;
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ expect(await inventoryForwardStatuses(server.port)).toMatchObject({ 'y.csv': 'exact' });
+ expect(server.serverInstance.durabilityState.isBatchInProgress()).toBe(false);
+ expect(headBatchSchedule.begins).toEqual([]);
+ await nativeSubscriptionOn(join(contentDir, '.git')).deliver([], new Error(notices[0]));
+ await batchBegun.promise;
+ expect(headBatchSchedule.begins).toEqual([{ trigger: 'rescan' }]);
+ expect(server.serverInstance.durabilityState.isBatchInProgress()).toBe(true);
+ unlinkSync(y);
+ linkSync(a, y);
+ expect(lstatSync(y).isFile()).toBe(true);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(y).dev, statSync(y).ino]);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(server.serverInstance.durabilityState.isBatchInProgress()).toBe(true);
+ expect(await inventoryForwardStatuses(server.port)).toMatchObject({ 'y.csv': 'exact' });
+ expect(headBatchSchedule.ends).toEqual([]);
+ batchHold.release();
+ await batchEnded.promise;
+ expect(headBatchSchedule.ends).toEqual([
+ expect.objectContaining({ batchKind: 'within-branch', headMoved: false, timeout: false }),
+ ]);
+ expect(server.serverInstance.durabilityState.isBatchInProgress()).toBe(false);
+ const asset = await fetch(`http://127.0.0.1:${server.port}/api/asset-text?path=y.csv`);
+ expect(asset.status).toBe(200);
+ expect(await asset.text()).toBe('same,physical,bytes\n');
+ expect.soft(await inventoryForwardStatuses(server.port)).toMatchObject({ 'y.csv': 'exact' });
+ expect(readFileSync(y, 'utf8')).toBe('same,physical,bytes\n');
+ } finally {
+ batchHold.release();
+ vi.useRealTimers();
+ await server.destroy();
+ }
+});
+
+test.each(['notice recovery', 'index-only rescan', 'idle reconcile'] as const)(
+ 'an ignore rebuild keeps excluded targets absent after $0',
+ async (surface) => {
+ const b = writeDoc('b.csv', 'b,kept,on,disk\n');
+ const note = writeDoc('note.md', '# Kept on disk\n');
+ const latch = writeDoc('z-latch.csv', 'z,admitted\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['b.csv', 'note.md', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let afterObservation: { documentTargets: string[]; fileTargets: string[] } | undefined;
+ let watcher: WatcherHandle;
+ const inventory = () => {
+ const current = localTargetInventoryFromWatcher(watcher, contentDir);
+ if (!current) throw new Error('watcher inventory unavailable');
+ return {
+ documentTargets: [...current.documentTargets].toSorted(),
+ fileTargets: [...current.fileTargets].toSorted(),
+ };
+ };
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = inventory();
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(inventory()).toEqual({
+ documentTargets: ['note'],
+ fileTargets: ['.okignore', 'b.csv', 'z-latch.csv'],
+ });
+
+ const entered = deferred();
+ const resume = deferred();
+ let pending: Promise<void> | undefined;
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ let reconciled: Awaited<ReturnType<typeof reconcileFileIndexAfterFilterRebuild>> | undefined;
+ let afterPrune: { documentTargets: string[]; fileTargets: string[] } | undefined;
+ try {
+ if (surface !== 'idle reconcile') {
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ pending =
+ surface === 'notice recovery'
+ ? nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]))
+ : watcher.rescanFromDisk().then(() => {
+ afterObservation = inventory();
+ });
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter((path) => path === b || path === note || path === latch),
+ ).toEqual([b, note, latch]);
+ expect(inventory()).toEqual({
+ documentTargets: ['note'],
+ fileTargets: ['.okignore', 'b.csv', 'z-latch.csv'],
+ });
+ }
+
+ writeFileSync(ignore, 'b.csv\nnote.md\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(true);
+ expect(filter.isExcluded('note.md')).toBe(true);
+ expect(filter.isPathIgnored('z-latch.csv')).toBe(false);
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = inventory();
+ expect(afterPrune).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ });
+ } finally {
+ resume.release();
+ if (pending) await pending;
+ if (reconcile) reconciled = await reconcile;
+ }
+
+ expect(reconciled).toEqual({ prunedFiles: 2, prunedFolders: 0 });
+ expect(afterPrune).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ });
+ if (surface !== 'idle reconcile') {
+ expect.soft(afterObservation).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ });
+ }
+ expect.soft(inventory()).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ });
+ expect
+ .soft(events.filter((event) => 'path' in event && (event.path === b || event.path === note)))
+ .toEqual([]);
+ if (surface === 'notice recovery') {
+ expect(events).toContainEqual(expect.objectContaining({ kind: 'file-update', path: ignore }));
+ } else {
+ expect(events).toEqual([]);
+ }
+ expect(readFileSync(b, 'utf8')).toBe('b,kept,on,disk\n');
+ expect(readFileSync(note, 'utf8')).toBe('# Kept on disk\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,admitted\n');
+ },
+);
+
+function sortedTargetInventory(watcher: WatcherHandle) {
+ const current = localTargetInventoryFromWatcher(watcher, contentDir);
+ if (!current) throw new Error('watcher inventory unavailable');
+ return {
+ documentTargets: [...current.documentTargets].toSorted(),
+ fileTargets: [...current.fileTargets].toSorted(),
+ folderTargets: [...current.folderTargets].toSorted(),
+ };
+}
+
+test.each(['notice recovery', 'index-only rescan'] as const)(
+ '%s does not publish newly captured files excluded before publication',
+ async (surface) => {
+ const latch = writeDoc('z-latch.csv', 'z,admitted\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['b.csv', 'note.md', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let afterObservation: ReturnType<typeof sortedTargetInventory> | undefined;
+ let watcher: WatcherHandle;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = sortedTargetInventory(watcher);
+ },
+ },
+ );
+ handles.push(watcher);
+ const initial = {
+ documentTargets: [],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ folderTargets: [],
+ };
+ expect(sortedTargetInventory(watcher)).toEqual(initial);
+
+ const b = writeDoc('b.csv', 'b,new,on,disk\n');
+ const note = writeDoc('note.md', '# New on disk\n');
+ expect(sortedTargetInventory(watcher)).toEqual(initial);
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending =
+ surface === 'notice recovery'
+ ? nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]))
+ : watcher.rescanFromDisk().then(() => {
+ afterObservation = sortedTargetInventory(watcher);
+ });
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ let reconciled: Awaited<ReturnType<typeof reconcileFileIndexAfterFilterRebuild>> | undefined;
+ let afterPrune: ReturnType<typeof sortedTargetInventory> | undefined;
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter((path) => path === b || path === note || path === latch),
+ ).toEqual([b, note, latch]);
+ expect(sortedTargetInventory(watcher)).toEqual(initial);
+ writeFileSync(ignore, 'b.csv\nnote.md\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(true);
+ expect(filter.isExcluded('note.md')).toBe(true);
+ expect(filter.isPathIgnored('z-latch.csv')).toBe(false);
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = sortedTargetInventory(watcher);
+ expect(afterPrune).toEqual(initial);
+ } finally {
+ resume.release();
+ await pending;
+ if (reconcile) reconciled = await reconcile;
+ }
+ expect(reconciled).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ expect(afterPrune).toEqual(initial);
+ expect.soft(afterObservation).toEqual(initial);
+ expect.soft(sortedTargetInventory(watcher)).toEqual(initial);
+ expect
+ .soft(events.filter((event) => 'path' in event && (event.path === b || event.path === note)))
+ .toEqual([]);
+ expect(readFileSync(b, 'utf8')).toBe('b,new,on,disk\n');
+ expect(readFileSync(note, 'utf8')).toBe('# New on disk\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,admitted\n');
+ },
+);
+
+test.each(['notice recovery', 'index-only rescan'] as const)(
+ '%s keeps a newly excluded empty folder and file alias out of public inventory',
+ async (surface) => {
+ const target = writeDoc('a.csv', 'a,survives\n');
+ const folder = join(contentDir, 'empty-folder');
+ mkdirSync(folder);
+ const alias = join(contentDir, 'y-alias.csv');
+ symlinkSync(target, alias);
+ const latch = writeDoc('z-latch.csv', 'z,survives\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'empty-folder', 'y-alias.csv', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let afterObservation: ReturnType<typeof sortedTargetInventory> | undefined;
+ let watcher: WatcherHandle;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = sortedTargetInventory(watcher);
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(watcher.getFolderIndex().has('empty-folder')).toBe(true);
+ expect(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'y-alias.csv', 'z-latch.csv'],
+ folderTargets: ['empty-folder'],
+ });
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending =
+ surface === 'notice recovery'
+ ? nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]))
+ : watcher.rescanFromDisk().then(() => {
+ afterObservation = sortedTargetInventory(watcher);
+ });
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ let reconciled: Awaited<ReturnType<typeof reconcileFileIndexAfterFilterRebuild>> | undefined;
+ let afterPrune: ReturnType<typeof sortedTargetInventory> | undefined;
+ const excluded = {
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'z-latch.csv'],
+ folderTargets: [],
+ };
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter(
+ (path) => path === target || path === folder || path === alias || path === latch,
+ ),
+ ).toEqual([target, folder, alias, latch]);
+ writeFileSync(ignore, 'empty-folder/\ny-alias.csv\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isDirExcluded('empty-folder')).toBe(true);
+ expect(filter.isPathIgnored('y-alias.csv')).toBe(true);
+ expect(filter.isPathIgnored('a.csv')).toBe(false);
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = sortedTargetInventory(watcher);
+ expect(watcher.getFolderIndex().has('empty-folder')).toBe(false);
+ expect(afterPrune).toEqual(excluded);
+ } finally {
+ resume.release();
+ await pending;
+ if (reconcile) reconciled = await reconcile;
+ }
+ expect(reconciled).toEqual({ prunedFiles: 0, prunedFolders: 1 });
+ expect(afterPrune).toEqual(excluded);
+ expect.soft(afterObservation).toEqual(excluded);
+ expect.soft(sortedTargetInventory(watcher)).toEqual(excluded);
+ expect.soft(watcher.getFolderIndex().has('empty-folder')).toBe(false);
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ ['file-delete', 'asset-delete', 'folder-delete', 'delete'].includes(event.kind) &&
+ 'path' in event &&
+ (event.path === alias || event.path === folder),
+ ),
+ )
+ .toEqual([]);
+ expect(lstatSync(folder).isDirectory()).toBe(true);
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(target);
+ expect(readFileSync(target, 'utf8')).toBe('a,survives\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,survives\n');
+ },
+);
+
+test('a recovered callback cannot restore entries pruned after observation completed', async () => {
+ const b = writeDoc('b.csv', 'b,unchanged\n');
+ const note = writeDoc('note.md', '# Unchanged\n');
+ const trigger = writeDoc('trigger.md', '# Before\n');
+ const latch = writeDoc('z-latch.csv', 'z,unchanged\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['b.csv', 'note.md', 'trigger.md', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle;
+ let afterObservation: ReturnType<typeof sortedTargetInventory> | undefined;
+ let afterPrune: ReturnType<typeof sortedTargetInventory> | undefined;
+ let rebuildSucceeded = false;
+ let callbackCount = 0;
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'update' || event.docName !== 'trigger') return;
+ callbackCount++;
+ writeFileSync(ignore, 'b.csv\nnote.md\n');
+ rebuildSucceeded = (await filter.rebuildIgnorePatterns()).ok;
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = sortedTargetInventory(watcher);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = sortedTargetInventory(watcher);
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: ['note', 'trigger'],
+ fileTargets: ['.okignore', 'b.csv', 'z-latch.csv'],
+ folderTargets: [],
+ });
+ writeFileSync(trigger, '# After\n');
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter(
+ (path) => path === b || path === note || path === trigger || path === latch,
+ ),
+ ).toEqual([b, note, trigger, latch]);
+ } finally {
+ resume.release();
+ await pending;
+ }
+ const reconciled = await reconcile;
+ expect(callbackCount).toBe(1);
+ expect(rebuildSucceeded).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(true);
+ expect(filter.isExcluded('note.md')).toBe(true);
+ expect(filter.isPathIgnored('z-latch.csv')).toBe(false);
+ const excluded = {
+ documentTargets: ['trigger'],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ folderTargets: [],
+ };
+ expect(reconciled).toEqual({ prunedFiles: 2, prunedFolders: 0 });
+ expect(afterPrune).toEqual(excluded);
+ expect.soft(afterObservation).toEqual(excluded);
+ expect.soft(sortedTargetInventory(watcher)).toEqual(excluded);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: trigger,
+ docName: 'trigger',
+ content: '# After\n',
+ }),
+ );
+ expect
+ .soft(events.filter((event) => 'path' in event && (event.path === b || event.path === note)))
+ .toEqual([]);
+ expect(readFileSync(b, 'utf8')).toBe('b,unchanged\n');
+ expect(readFileSync(note, 'utf8')).toBe('# Unchanged\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,unchanged\n');
+});
+
+test.each(['folder alias', 'ordinary folder'] as const)(
+ 'idle reconcile removes an excluded %s from cached public inventory',
+ async (excludedKind) => {
+ const canonical = join(contentDir, 'canonical-folder');
+ const ordinary = join(contentDir, 'ordinary-folder');
+ mkdirSync(canonical);
+ mkdirSync(ordinary);
+ const alias = join(contentDir, 'linked-folder');
+ symlinkSync(canonical, alias);
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['canonical-folder', 'linked-folder', 'ordinary-folder'];
+ const { watcher, events } = await watchContent(filter);
+ expect(watcher.getFolderIndex().has('canonical-folder')).toBe(true);
+ expect(watcher.getFolderIndex().has('ordinary-folder')).toBe(true);
+ expect(watcher.getFolderAliasIndex().get('linked-folder')).toBe('canonical-folder');
+ const initial = sortedTargetInventory(watcher);
+ expect(initial).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore'],
+ folderTargets: ['canonical-folder', 'linked-folder', 'ordinary-folder'],
+ });
+
+ const excludedName = excludedKind === 'folder alias' ? 'linked-folder' : 'ordinary-folder';
+ const retainedName = excludedKind === 'folder alias' ? 'ordinary-folder' : 'linked-folder';
+ const expectedAlias = excludedKind !== 'folder alias';
+ const expectedOrdinary = excludedKind !== 'ordinary folder';
+ const expectedFolders = ['canonical-folder', retainedName].toSorted();
+ const generationBefore = watcher.getFileIndexGeneration();
+ writeFileSync(ignore, `${excludedName}/\n`);
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isDirExcluded(excludedName)).toBe(true);
+ expect(filter.isDirExcluded(retainedName)).toBe(false);
+ expect(filter.isDirExcluded('canonical-folder')).toBe(false);
+
+ const pending = reconcileFileIndexAfterFilterRebuild(watcher);
+ const immediateGeneration = watcher.getFileIndexGeneration();
+ const immediateAlias = watcher.getFolderAliasIndex().has('linked-folder');
+ const immediateOrdinary = watcher.getFolderIndex().has('ordinary-folder');
+ const immediateCanonical = watcher.getFolderIndex().has('canonical-folder');
+ const immediateInventory = sortedTargetInventory(watcher);
+ const reconciled = await pending;
+
+ expect(reconciled).toEqual({
+ prunedFiles: 0,
+ prunedFolders: excludedKind === 'ordinary folder' ? 1 : 0,
+ });
+ expect.soft(immediateAlias).toBe(expectedAlias);
+ expect.soft(immediateOrdinary).toBe(expectedOrdinary);
+ expect.soft(immediateCanonical).toBe(true);
+ expect.soft(immediateInventory).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore'],
+ folderTargets: expectedFolders,
+ });
+ expect.soft(immediateGeneration).toBeGreaterThan(generationBefore);
+ expect.soft(watcher.getFolderAliasIndex().has('linked-folder')).toBe(expectedAlias);
+ expect.soft(watcher.getFolderIndex().has('ordinary-folder')).toBe(expectedOrdinary);
+ expect.soft(watcher.getFolderIndex().has('canonical-folder')).toBe(true);
+ expect.soft(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore'],
+ folderTargets: expectedFolders,
+ });
+ expect(events).toEqual([]);
+ expect(lstatSync(canonical).isDirectory()).toBe(true);
+ expect(lstatSync(ordinary).isDirectory()).toBe(true);
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(canonical);
+ },
+);
+
+test.each(['notice recovery', 'index-only rescan'] as const)(
+ '%s does not publish a newly captured excluded folder alias',
+ async (surface) => {
+ const canonical = join(contentDir, 'canonical-folder');
+ mkdirSync(canonical);
+ const document = writeDoc('canonical-folder/inside.md', '# Inside\n');
+ const data = writeDoc('canonical-folder/data.csv', 'inside,data\n');
+ const latch = writeDoc('z-latch.csv', 'z,admitted\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['canonical-folder', 'linked-folder', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle;
+ let afterObservation:
+ | { inventory: ReturnType<typeof sortedTargetInventory>; alias: string | undefined }
+ | undefined;
+ const capture = () => ({
+ inventory: sortedTargetInventory(watcher),
+ alias: watcher.getFolderAliasIndex().get('linked-folder'),
+ });
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = capture();
+ },
+ },
+ );
+ handles.push(watcher);
+ const admitted = {
+ documentTargets: ['canonical-folder/inside'],
+ fileTargets: ['.okignore', 'canonical-folder/data.csv', 'z-latch.csv'],
+ folderTargets: ['canonical-folder'],
+ };
+ expect(watcher.getFolderIndex().has('canonical-folder')).toBe(true);
+ expect(watcher.getFolderAliasIndex().has('linked-folder')).toBe(false);
+ expect(sortedTargetInventory(watcher)).toEqual(admitted);
+
+ const alias = join(contentDir, 'linked-folder');
+ symlinkSync(canonical, alias);
+ expect(watcher.getFolderAliasIndex().has('linked-folder')).toBe(false);
+ expect(sortedTargetInventory(watcher)).toEqual(admitted);
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending =
+ surface === 'notice recovery'
+ ? nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]))
+ : watcher.rescanFromDisk().then(() => {
+ afterObservation = capture();
+ });
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ let reconciled: Awaited<ReturnType<typeof reconcileFileIndexAfterFilterRebuild>> | undefined;
+ let afterPrune: ReturnType<typeof capture> | undefined;
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter(
+ (path) => path === canonical || path === alias || path === latch,
+ ),
+ ).toEqual([canonical, alias, latch]);
+ expect(watcher.getFolderAliasIndex().has('linked-folder')).toBe(false);
+ writeFileSync(ignore, 'linked-folder/\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isDirExcluded('linked-folder')).toBe(true);
+ expect(filter.isDirExcluded('canonical-folder')).toBe(false);
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = capture();
+ expect(afterPrune).toEqual({ inventory: admitted, alias: undefined });
+ } finally {
+ resume.release();
+ await pending;
+ if (reconcile) reconciled = await reconcile;
+ }
+ expect(reconciled).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ expect(afterPrune).toEqual({ inventory: admitted, alias: undefined });
+ expect.soft(afterObservation).toEqual({ inventory: admitted, alias: undefined });
+ expect.soft(capture()).toEqual({ inventory: admitted, alias: undefined });
+ expect
+ .soft(events.filter((event) => event.kind === 'folder-delete' && event.path === alias))
+ .toEqual([]);
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(readFileSync(document, 'utf8')).toBe('# Inside\n');
+ expect(readFileSync(data, 'utf8')).toBe('inside,data\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,admitted\n');
+ },
+);
+
+test.each(['notice recovery', 'index-only rescan'] as const)(
+ '%s keeps a newer public file effect only until its member is pruned',
+ async (surface) => {
+ const a = writeDoc('a.csv', 'old,shared\n');
+ const b = join(contentDir, 'b.csv');
+ linkSync(a, b);
+ const alias = join(contentDir, 'y-alias.csv');
+ symlinkSync(b, alias);
+ const latch = writeDoc('z-latch.csv', 'z,admitted\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'y-alias.csv', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle;
+ const capture = () => ({
+ inventory: sortedTargetInventory(watcher),
+ aSize: indexedRow(watcher, 'a.csv', 'file')?.size,
+ aModified: indexedRow(watcher, 'a.csv', 'file')?.modified,
+ });
+ let afterObservation: ReturnType<typeof capture> | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = capture();
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'b.csv', 'y-alias.csv', 'z-latch.csv'],
+ folderTargets: [],
+ });
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending =
+ surface === 'notice recovery'
+ ? nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]))
+ : watcher.rescanFromDisk().then(() => {
+ afterObservation = capture();
+ });
+ const c = join(contentDir, 'c.csv');
+ let publicStat: ReturnType<typeof statSync> | undefined;
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ let reconciled: Awaited<ReturnType<typeof reconcileFileIndexAfterFilterRebuild>> | undefined;
+ let afterPrune: ReturnType<typeof capture> | undefined;
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter(
+ (path) => path === a || path === b || path === alias || path === latch,
+ ),
+ ).toEqual([a, b, alias, latch]);
+ writeFileSync(b, 'newer,public,shared,metadata\n');
+ publicStat = statSync(b);
+ watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: b,
+ relativePath: 'b.csv',
+ size: publicStat.size,
+ modifiedTs: publicStat.mtimeMs,
+ inode: Number(publicStat.ino),
+ });
+ writeFileSync(c, 'c,unrelated,public\n');
+ const cStat = statSync(c);
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path: c,
+ relativePath: 'c.csv',
+ size: cStat.size,
+ modifiedTs: cStat.mtimeMs,
+ inode: Number(cStat.ino),
+ });
+ expect(sortedTargetInventory(watcher).fileTargets).toEqual([
+ '.okignore',
+ 'a.csv',
+ 'b.csv',
+ 'c.csv',
+ 'y-alias.csv',
+ 'z-latch.csv',
+ ]);
+ expect(indexedRow(watcher, 'a.csv', 'file')?.size).toBe(publicStat.size);
+ writeFileSync(ignore, 'b.csv\n');
+ expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(filter.isPathIgnored('b.csv')).toBe(true);
+ expect(filter.isPathIgnored('y-alias.csv')).toBe(false);
+ expect(filter.isPathIgnored('a.csv')).toBe(false);
+ expect(filter.isPathIgnored('c.csv')).toBe(false);
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = capture();
+ expect(afterPrune.inventory).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'c.csv', 'z-latch.csv'],
+ folderTargets: [],
+ });
+ } finally {
+ resume.release();
+ await pending;
+ if (reconcile) reconciled = await reconcile;
+ }
+ if (!publicStat) throw new Error('accepted public file update was not observed');
+ const expectedModified = new Date(publicStat.mtimeMs).toISOString();
+ expect(reconciled).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ expect(afterPrune?.aSize).toBe(publicStat.size);
+ expect(afterPrune?.aModified).toBe(expectedModified);
+ const expectedTargets = ['.okignore', 'a.csv', 'c.csv', 'z-latch.csv'];
+ expect.soft(afterObservation?.inventory.fileTargets).toEqual(expectedTargets);
+ expect.soft(sortedTargetInventory(watcher).fileTargets).toEqual(expectedTargets);
+ expect.soft(afterObservation?.aSize).toBe(publicStat.size);
+ expect.soft(indexedRow(watcher, 'a.csv', 'file')?.size).toBe(publicStat.size);
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ (event.kind === 'file-delete' || event.kind === 'asset-delete') &&
+ (event.path === b || event.path === alias),
+ ),
+ )
+ .toEqual([]);
+ expect(lstatSync(b).isFile()).toBe(true);
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ expect(readFileSync(a, 'utf8')).toBe('newer,public,shared,metadata\n');
+ expect(readFileSync(b, 'utf8')).toBe('newer,public,shared,metadata\n');
+ expect(readFileSync(alias, 'utf8')).toBe('newer,public,shared,metadata\n');
+ expect(readFileSync(c, 'utf8')).toBe('c,unrelated,public\n');
+ },
+);
+
+test('a recovered Markdown callback excludes a second changed document before publication', async () => {
+ const a = writeDoc('a.md', '# Before A\n');
+ const b = writeDoc('b.md', '# Before B\n');
+ const latch = writeDoc('z-latch.csv', 'z,admitted\n');
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.md', 'b.md', 'z-latch.csv'];
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle;
+ let firstName: 'a' | 'b' | undefined;
+ let pendingName: 'a' | 'b' | undefined;
+ let pendingAlreadyEmitted: boolean | undefined;
+ let callbackCount = 0;
+ let rebuildSucceeded = false;
+ let afterPrune: ReturnType<typeof sortedTargetInventory> | undefined;
+ let afterObservation: ReturnType<typeof sortedTargetInventory> | undefined;
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'update' || (event.docName !== 'a' && event.docName !== 'b')) return;
+ callbackCount++;
+ if (firstName !== undefined) return;
+ firstName = event.docName;
+ pendingName = event.docName === 'a' ? 'b' : 'a';
+ pendingAlreadyEmitted = events.some(
+ (emitted) =>
+ emitted.kind === 'update' && 'docName' in emitted && emitted.docName === pendingName,
+ );
+ writeFileSync(ignore, `${pendingName}.md\n`);
+ rebuildSucceeded = (await filter.rebuildIgnorePatterns()).ok;
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterPrune = sortedTargetInventory(watcher);
+ },
+ filter,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ afterObservation = sortedTargetInventory(watcher);
+ },
+ },
+ );
+ handles.push(watcher);
+ expect(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: ['a', 'b'],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ folderTargets: [],
+ });
+ writeFileSync(a, '# After A\n');
+ writeFileSync(b, '# After B\n');
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.seen = [];
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ await entered.promise;
+ expect(
+ memberStatSchedule.seen.filter((path) => path === a || path === b || path === latch),
+ ).toEqual([a, b, latch]);
+ } finally {
+ resume.release();
+ await pending;
+ }
+ const reconciled = await reconcile;
+ if (!firstName || !pendingName) throw new Error('changed Markdown callback was not observed');
+ const first = firstName;
+ const excluded = pendingName;
+ const firstPath = first === 'a' ? a : b;
+ const firstContent = first === 'a' ? '# After A\n' : '# After B\n';
+ expect(callbackCount).toBeGreaterThan(0);
+ expect(pendingAlreadyEmitted).toBe(false);
+ expect(rebuildSucceeded).toBe(true);
+ expect(filter.isExcluded(`${excluded}.md`)).toBe(true);
+ expect(filter.isExcluded(`${first}.md`)).toBe(false);
+ expect(reconciled).toEqual({ prunedFiles: 1, prunedFolders: 0 });
+ const expected = {
+ documentTargets: [first],
+ fileTargets: ['.okignore', 'z-latch.csv'],
+ folderTargets: [],
+ };
+ expect(afterPrune).toEqual(expected);
+ expect.soft(afterObservation).toEqual(expected);
+ expect.soft(sortedTargetInventory(watcher)).toEqual(expected);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'update',
+ path: firstPath,
+ docName: first,
+ content: firstContent,
+ }),
+ );
+ expect(readFileSync(a, 'utf8')).toBe('# After A\n');
+ expect(readFileSync(b, 'utf8')).toBe('# After B\n');
+ expect(readFileSync(latch, 'utf8')).toBe('z,admitted\n');
+});
+
+test('a pending alias deletion is rejected after the first alias callback excludes it', async () => {
+ const a = writeDoc('a.csv', 'a,target\n');
+ const b = writeDoc('b.csv', 'b,target\n');
+ const x = join(contentDir, 'x-alias.csv');
+ const y = join(contentDir, 'y-alias.csv');
+ symlinkSync(a, x);
+ symlinkSync(b, y);
+ const ignore = writeDoc('.okignore', '');
+ const filter = createContentFilter({ projectDir: contentDir, contentDir });
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'x-alias.csv', 'y-alias.csv'];
+ const events: DiskEvent[] = [];
+ let watcher: WatcherHandle;
+ let firstAlias: string | undefined;
+ let pendingAlias: string | undefined;
+ let pendingAlreadyEmitted: boolean | undefined;
+ let rebuildSucceeded = false;
+ let afterCallback: ReturnType<typeof sortedTargetInventory> | undefined;
+ let reconcile: ReturnType<typeof reconcileFileIndexAfterFilterRebuild> | undefined;
+ watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ if (event.kind !== 'file-delete' || (event.path !== x && event.path !== y)) return;
+ if (firstAlias !== undefined) return;
+ firstAlias = event.path;
+ pendingAlias = event.path === x ? y : x;
+ pendingAlreadyEmitted = events.some(
+ (emitted) => emitted.kind === 'file-delete' && emitted.path === pendingAlias,
+ );
+ writeFileSync(ignore, `${basename(pendingAlias)}\n`);
+ rebuildSucceeded = (await filter.rebuildIgnorePatterns()).ok;
+ reconcile = reconcileFileIndexAfterFilterRebuild(watcher);
+ afterCallback = sortedTargetInventory(watcher);
+ },
+ filter,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'b.csv', 'x-alias.csv', 'y-alias.csv'],
+ folderTargets: [],
+ });
+ unlinkSync(x);
+ unlinkSync(y);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const reconciled = await reconcile;
+ if (!firstAlias || !pendingAlias) throw new Error('first alias deletion was not observed');
+ expect(pendingAlreadyEmitted).toBe(false);
+ expect(rebuildSucceeded).toBe(true);
+ expect(filter.isPathIgnored(basename(pendingAlias))).toBe(true);
+ expect(filter.isPathIgnored(basename(firstAlias))).toBe(false);
+ expect(filter.isPathIgnored('a.csv')).toBe(false);
+ expect(filter.isPathIgnored('b.csv')).toBe(false);
+ expect(reconciled).toEqual({ prunedFiles: 0, prunedFolders: 0 });
+ expect(afterCallback).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'b.csv'],
+ folderTargets: [],
+ });
+ expect(
+ events.filter((event) => event.kind === 'file-delete' && event.path === firstAlias),
+ ).toEqual([{ kind: 'file-delete', path: firstAlias, relativePath: basename(firstAlias) }]);
+ expect
+ .soft(events.filter((event) => event.kind === 'file-delete' && event.path === pendingAlias))
+ .toEqual([]);
+ expect.soft(sortedTargetInventory(watcher)).toEqual({
+ documentTargets: [],
+ fileTargets: ['.okignore', 'a.csv', 'b.csv'],
+ folderTargets: [],
+ });
+ expect(existsSync(x)).toBe(false);
+ expect(existsSync(y)).toBe(false);
+ expect(readFileSync(a, 'utf8')).toBe('a,target\n');
+ expect(readFileSync(b, 'utf8')).toBe('b,target\n');
+});
+
+test('the final symlink target stat supplies shared metadata after earlier hardlink members were scanned', async () => {
+ const a = writeDoc('a.csv', 'old\n');
+ const b = join(contentDir, 'b.csv');
+ const z = join(contentDir, 'z.csv');
+ linkSync(a, b);
+ symlinkSync(b, z);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(lstatSync(z).isSymbolicLink()).toBe(true);
+ expect(realpathSync(z)).toBe(b);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'z.csv'];
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.path = z;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const started = watchContent();
+ let lastStat: ReturnType<typeof statSync> | undefined;
+ try {
+ const paused = await Promise.race([
+ entered.promise.then(() => true),
+ started.then(() => false),
+ ]);
+ expect(paused).toBe(true);
+ writeFileSync(b, 'new,shared,metadata\n');
+ lastStat = statSync(b);
+ expect(readFileSync(a, 'utf8')).toBe('new,shared,metadata\n');
+ expect(readFileSync(z, 'utf8')).toBe('new,shared,metadata\n');
+ } finally {
+ resume.release();
+ await started;
+ }
+ const { watcher, events } = await started;
+ expect(lastStat).toBeDefined();
+ expect(events).toEqual([]);
+ expect(indexedFileTargets(watcher)).toEqual(['a.csv', 'b.csv', 'z.csv']);
+ expect([...watcher.getAllFilesIndex()][0]?.[1].fileMembers).toEqual({
+ regularPaths: ['a.csv', 'b.csv'],
+ symlinks: [{ path: 'z.csv', targetPath: 'b.csv' }],
+ });
+ expect(indexedGeneralRows(watcher)).toEqual([
+ expect.objectContaining({
+ name: 'a.csv',
+ canonicalPath: a,
+ aliases: ['z.csv'],
+ size: lastStat?.size,
+ modified: lastStat?.mtime.toISOString(),
+ inode: Number(lastStat?.ino),
+ }),
+ ]);
+});
+
+test('stable scan order preserves the bounded HTTP file-search result', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const bytes = 'invoice,shared\n';
+ const fixedMtime = new Date('2020-01-02T03:04:05.000Z');
+ const names: string[] = [];
+ const identities = new Set<string>();
+ for (let index = 0; index < 41; index++) {
+ const suffix = String(index).padStart(2, '0');
+ const aName = `invoice-${suffix}.csv`;
+ const zName = `z-invoice-${suffix}.csv`;
+ const a = writeDoc(aName, bytes);
+ const z = join(contentDir, zName);
+ linkSync(a, z);
+ utimesSync(a, fixedMtime, fixedMtime);
+ const aStat = lstatSync(a);
+ const zStat = lstatSync(z);
+ expect(aStat.isFile()).toBe(true);
+ expect(zStat.isFile()).toBe(true);
+ expect([aStat.dev, aStat.ino]).toEqual([zStat.dev, zStat.ino]);
+ expect(realpathSync(a)).toBe(a);
+ expect(realpathSync(z)).toBe(z);
+ expect([readFileSync(a, 'utf8'), readFileSync(z, 'utf8')]).toEqual([bytes, bytes]);
+ expect([aStat.size, zStat.size]).toEqual([Buffer.byteLength(bytes), Buffer.byteLength(bytes)]);
+ expect([aStat.mtimeMs, zStat.mtimeMs]).toEqual([fixedMtime.getTime(), fixedMtime.getTime()]);
+ identities.add(`${aStat.dev}:${aStat.ino}`);
+ if (index === 0) names.push(zName, aName);
+ else names.push(aName, zName);
+ }
+ expect(identities.size).toBe(41);
+ expect(names).toHaveLength(82);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = names;
+ const server = await bootInventoryServer();
+ try {
+ const listed = (await listedEntries(server.port)).filter(
+ (entry) => entry.kind === 'file' && entry.docName?.includes('invoice'),
+ );
+ expect(listed).toHaveLength(82);
+ expect(listed.map((entry) => entry.docName).toSorted()).toEqual(names.toSorted());
+ for (const entry of listed) {
+ expect(entry).toMatchObject({
+ size: Buffer.byteLength(bytes),
+ modified: fixedMtime.toISOString(),
+ isSymlink: false,
+ targetPath: null,
+ });
+ }
+ const search = async (query: string, limit: number) => {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/search?query=${query}&intent=omnibar&scope=file&ranking=relevance&limit=${limit}&semantic=false`,
+ );
+ expect(response.status).toBe(200);
+ return (await response.json()) as {
+ ready: boolean;
+ truncated?: boolean;
+ results: Array<{ kind: string; path: string; score?: number }>;
+ };
+ };
+ const all = await search('invoice', 100);
+ expect(all.ready).toBe(true);
+ expect(all.truncated).not.toBe(true);
+ expect(all.results).toHaveLength(41);
+ expect(all.results.map((result) => result.path).toSorted()).toEqual(
+ Array.from({ length: 41 }, (_, index) => `invoice-${String(index).padStart(2, '0')}.csv`),
+ );
+ const bounded = await search('invoice', 5);
+ const empty = await search('', 5);
+ expect(bounded.ready).toBe(true);
+ expect(bounded.truncated).not.toBe(true);
+ expect(bounded.results).toHaveLength(5);
+ expect(bounded.results.every((result) => result.kind === 'file')).toBe(true);
+ expect(empty.ready).toBe(true);
+ expect(empty.truncated).not.toBe(true);
+ expect(empty.results.map((result) => result.path)).toEqual([
+ 'invoice-00.csv',
+ 'invoice-01.csv',
+ 'invoice-02.csv',
+ 'invoice-03.csv',
+ 'invoice-04.csv',
+ ]);
+ expect(bounded.results.map((result) => result.path)).toEqual([
+ 'invoice-01.csv',
+ 'invoice-02.csv',
+ 'invoice-03.csv',
+ 'invoice-04.csv',
+ 'invoice-05.csv',
+ ]);
+ } finally {
+ scanSchedule.orderedEntries = null;
+ scanSchedule.orderedPath = null;
+ await server.destroy();
+ for (const dir of nativeSubscriptionDirs()) {
+ expect(nativeSubscriptionOn(dir).nativeReleases()).toBe(1);
+ }
+ }
+});
+
+test('a live dependent cohort selects the minimum name for a new physical group', async () => {
+ const a = writeDoc('a.csv', 'old,group\n');
+ const b = join(contentDir, 'b.csv');
+ const c = writeDoc('c.csv', 'known,group\n');
+ const first = join(contentDir, 'dep-first.csv');
+ const second = join(contentDir, 'dep-second.csv');
+ linkSync(a, b);
+ symlinkSync(b, first);
+ symlinkSync(b, second);
+ const { watcher } = await watchContent();
+ expect(
+ indexedGeneralRows(watcher)
+ .map((row) => row.name)
+ .toSorted(),
+ ).toEqual(['a.csv', 'c.csv']);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ expect(realpathSync(first)).toBe(b);
+ expect(realpathSync(second)).toBe(b);
+ expect(indexedAliasOwner(watcher, 'dep-first.csv')?.aliases).toContain('dep-second.csv');
+ expect(indexedFileTargets(watcher)).toEqual([
+ 'a.csv',
+ 'b.csv',
+ 'c.csv',
+ 'dep-first.csv',
+ 'dep-second.csv',
+ ]);
+ const zNew = writeDoc('z-new-orbit.csv', 'new,orbit\n');
+ const aNew = join(contentDir, 'a-new-orbit.csv');
+ linkSync(zNew, aNew);
+ unlinkSync(first);
+ symlinkSync(zNew, first);
+ unlinkSync(second);
+ symlinkSync(aNew, second);
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect([statSync(zNew).dev, statSync(zNew).ino]).toEqual([
+ statSync(aNew).dev,
+ statSync(aNew).ino,
+ ]);
+ expect(statSync(zNew).ino).not.toBe(statSync(a).ino);
+ expect(statSync(zNew).ino).not.toBe(statSync(c).ino);
+ expect([realpathSync(first), realpathSync(second), realpathSync(b)]).toEqual([zNew, aNew, c]);
+ expect([first, second, b].every((path) => lstatSync(path).isSymbolicLink())).toBe(true);
+ expect(lstatSync(zNew).isFile()).toBe(true);
+ expect(lstatSync(aNew).isFile()).toBe(true);
+ expect(indexedFileTargets(watcher)).not.toContain('a-new-orbit.csv');
+ expect(indexedFileTargets(watcher)).not.toContain('z-new-orbit.csv');
+
+ await deliver(contentDir, [{ type: 'update', path: b }]);
+
+ const newGroups = [...watcher.getAllFilesIndex()].filter(
+ ([, entry]) =>
+ entry.kind === 'file' && entry.fileMembers?.regularPaths.includes('a-new-orbit.csv'),
+ );
+ expect(newGroups).toHaveLength(1);
+ expect(newGroups[0]?.[0]).toBe('a-new-orbit.csv');
+ expect(newGroups[0]?.[1]).toMatchObject({
+ canonicalPath: aNew,
+ fileMembers: {
+ regularPaths: ['a-new-orbit.csv', 'z-new-orbit.csv'],
+ symlinks: [
+ { path: 'dep-first.csv', targetPath: 'z-new-orbit.csv' },
+ { path: 'dep-second.csv', targetPath: 'a-new-orbit.csv' },
+ ],
+ },
+ });
+ expect(
+ indexedGeneralRows(watcher)
+ .map((row) => row.name)
+ .toSorted(),
+ ).toEqual(['a-new-orbit.csv', 'a.csv', 'c.csv']);
+ expect(indexedAliasOwner(watcher, 'b.csv')?.canonicalPath).toBe(c);
+ expect(indexedFileTargets(watcher)).toEqual([
+ 'a-new-orbit.csv',
+ 'a.csv',
+ 'b.csv',
+ 'c.csv',
+ 'dep-first.csv',
+ 'dep-second.csv',
+ 'z-new-orbit.csv',
+ ]);
+});
+
+test('a repeated directory observation defers denied dependent changes and later settles both role directions', async () => {
+ const c = writeDoc('c.csv', 'distinct,target\n');
+ const folder = join(contentDir, 'z-dir');
+ mkdirSync(folder);
+ const a = writeDoc('z-dir/a.csv', 'shared,target\n');
+ const b = join(folder, 'b.csv');
+ const y = join(folder, 'y.csv');
+ const folderAlias = join(contentDir, '0-dir-alias');
+ const latch = writeDoc('m-latch.csv', 'latch\n');
+ linkSync(a, b);
+ symlinkSync(b, y);
+ symlinkSync(folder, folderAlias);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(statSync(c).ino).not.toBe(statSync(a).ino);
+ expect(lstatSync(y).isSymbolicLink()).toBe(true);
+ expect(realpathSync(y)).toBe(b);
+ expect(lstatSync(folderAlias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(folderAlias)).toBe(folder);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['c.csv', '0-dir-alias', 'm-latch.csv', 'z-dir'];
+ const events: DiskEvent[] = [];
+ const completed: string[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ {
+ forceBackend: 'parcel',
+ platform: 'darwin',
+ onRecoveryComplete: async () => {
+ completed.push('complete');
+ },
+ },
+ );
+ handles.push(watcher);
+ const expectedTargets = [
+ '0-dir-alias/a.csv',
+ '0-dir-alias/b.csv',
+ '0-dir-alias/y.csv',
+ 'c.csv',
+ 'm-latch.csv',
+ 'z-dir/a.csv',
+ 'z-dir/b.csv',
+ 'z-dir/y.csv',
+ ].toSorted();
+ expect(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect(indexedAliasOwner(watcher, 'z-dir/y.csv')?.canonicalPath).toBe(a);
+ const before = {
+ groups: structuredClone([...watcher.getAllFilesIndex()]),
+ targets: indexedFileTargets(watcher),
+ };
+ const revisit = async (replace: () => void, denyDependent: boolean) => {
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['c.csv', '0-dir-alias', 'm-latch.csv', 'z-dir'];
+ const entered = deferred();
+ const resume = deferred();
+ memberStatSchedule.path = latch;
+ memberStatSchedule.entered = entered.release;
+ memberStatSchedule.resume = resume.promise;
+ const pending = nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ try {
+ const firstWalkFinished = await Promise.race([
+ entered.promise.then(() => true),
+ pending.then(() => false),
+ ]);
+ expect(firstWalkFinished).toBe(true);
+ replace();
+ scanSchedule.orderedPath = folder;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'y.csv'];
+ if (denyDependent) denyAdmission('realpath', y);
+ } finally {
+ resume.release();
+ try {
+ await pending;
+ } finally {
+ clearAdmissionDenial();
+ }
+ }
+ await vi.runAllTimersAsync();
+ };
+
+ await revisit(() => {
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(c);
+ expect(realpathSync(y)).toBe(c);
+ }, true);
+ expect(admissionFault.observed).toBe(true);
+ expect(completed).toEqual([]);
+ expect(events).toEqual([]);
+ expect({
+ groups: structuredClone([...watcher.getAllFilesIndex()]),
+ targets: indexedFileTargets(watcher),
+ }).toEqual(before);
+
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete']);
+ expect(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect(indexedAliasOwner(watcher, 'z-dir/b.csv')?.canonicalPath).toBe(c);
+ expect(indexedAliasOwner(watcher, 'z-dir/y.csv')?.canonicalPath).toBe(c);
+ expect(indexedRow(watcher, 'z-dir/a.csv', 'file')?.canonicalPath).toBe(a);
+ expect(readFileSync(a, 'utf8')).toBe('shared,target\n');
+ expect(readFileSync(c, 'utf8')).toBe('distinct,target\n');
+
+ const acceptedIntoC = {
+ groups: structuredClone([...watcher.getAllFilesIndex()]),
+ targets: indexedFileTargets(watcher),
+ };
+ events.length = 0;
+ await revisit(() => {
+ unlinkSync(b);
+ symlinkSync(a, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(a);
+ expect(realpathSync(y)).toBe(a);
+ }, true);
+ expect(admissionFault.observed).toBe(true);
+ expect(completed).toEqual(['complete']);
+ expect(events).toEqual([]);
+ expect({
+ groups: structuredClone([...watcher.getAllFilesIndex()]),
+ targets: indexedFileTargets(watcher),
+ }).toEqual(acceptedIntoC);
+
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete', 'complete']);
+ expect(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect(indexedAliasOwner(watcher, 'z-dir/b.csv')?.canonicalPath).toBe(a);
+ expect(indexedAliasOwner(watcher, 'z-dir/y.csv')?.canonicalPath).toBe(a);
+ expect(indexedRow(watcher, 'c.csv', 'file')?.canonicalPath).toBe(c);
+
+ unlinkSync(b);
+ symlinkSync(c, b);
+ expect(lstatSync(b).isSymbolicLink()).toBe(true);
+ expect(realpathSync(b)).toBe(c);
+ expect(realpathSync(y)).toBe(c);
+ await deliverNotice(contentDir);
+ expect(completed).toEqual(['complete', 'complete', 'complete']);
+ expect(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect(indexedAliasOwner(watcher, 'z-dir/b.csv')?.canonicalPath).toBe(c);
+ expect(indexedAliasOwner(watcher, 'z-dir/y.csv')?.canonicalPath).toBe(c);
+
+ await revisit(() => {
+ unlinkSync(b);
+ linkSync(a, b);
+ expect(lstatSync(b).isFile()).toBe(true);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ expect(realpathSync(y)).toBe(b);
+ }, false);
+ expect(completed).toEqual(['complete', 'complete', 'complete', 'complete']);
+ expect(indexedFileTargets(watcher)).toEqual(expectedTargets);
+ expect(
+ [...watcher.getAllFilesIndex()].find(([name]) => name === 'z-dir/a.csv')?.[1].fileMembers,
+ ).toEqual({
+ regularPaths: ['z-dir/a.csv', 'z-dir/b.csv'],
+ symlinks: [{ path: 'z-dir/y.csv', targetPath: 'z-dir/b.csv' }],
+ });
+ expect(indexedRow(watcher, 'c.csv', 'file')?.canonicalPath).toBe(c);
+});
+
+test.each(['origin', 'target'] as const)(
+ 'pruning the pending $0 during the first alias callback cancels its target update',
+ async (pruned) => {
+ const a = writeDoc('a.csv', 'first,target\n');
+ const b = writeDoc('b.csv', 'second,target\n');
+ const x = join(contentDir, 'x.csv');
+ const y = join(contentDir, 'y.csv');
+ const ignore = writeDoc('.okignore', '');
+ symlinkSync(a, x);
+ symlinkSync(b, y);
+ const filter = dynamicSkillFilter();
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'b.csv', 'x.csv', 'y.csv'];
+ let callbackCount = 0;
+ let firstTarget: string | undefined;
+ let pendingTarget: string | undefined;
+ let pendingAlias: string | undefined;
+ let retainedAlias: string | undefined;
+ let ignoredName: string | undefined;
+ let pendingAlreadyEmitted = false;
+ let rebuildSucceeded = false;
+ let ignoredPath = false;
+ let generationAdvanced = false;
+ let physicalRetained = false;
+ let callbackTargets: string[] = [];
+ const targetNames = (watcher: WatcherHandle) =>
+ indexedFileTargets(watcher).filter((name) => name !== '.okignore');
+ const watched = await watchContent(filter, async (event) => {
+ if (event.kind !== 'file-update' || (event.path !== a && event.path !== b)) return;
+ if (firstTarget !== undefined) return;
+ callbackCount++;
+ firstTarget = event.path;
+ pendingTarget = event.path === a ? b : a;
+ pendingAlias = event.path === a ? x : y;
+ retainedAlias = event.path === a ? y : x;
+ pendingAlreadyEmitted = watched.events.some(
+ (emitted) => emitted.kind === 'file-update' && emitted.path === pendingTarget,
+ );
+ ignoredName = basename(pruned === 'origin' ? pendingAlias : pendingTarget);
+ const generation = watched.watcher.getFileIndexGeneration();
+ writeFileSync(ignore, `${ignoredName}\n`);
+ rebuildSucceeded = (await filter.rebuildIgnorePatterns()).ok;
+ ignoredPath = filter.isPathIgnored(ignoredName);
+ watched.watcher.pruneFileIndexNowExcluded();
+ generationAdvanced = watched.watcher.getFileIndexGeneration() > generation;
+ callbackTargets = targetNames(watched.watcher);
+ physicalRetained = [a, b, x, y].every((path) => existsSync(path));
+ });
+ expect(targetNames(watched.watcher)).toEqual(['a.csv', 'b.csv', 'x.csv', 'y.csv']);
+ expect(realpathSync(x)).toBe(a);
+ expect(realpathSync(y)).toBe(b);
+ unlinkSync(x);
+ unlinkSync(y);
+ symlinkSync(b, x);
+ symlinkSync(a, y);
+ expect(realpathSync(x)).toBe(b);
+ expect(realpathSync(y)).toBe(a);
+
+ await deliverNotice(contentDir);
+
+ const emittedFirst = firstTarget;
+ const targetStillPending = pendingTarget;
+ const originStillPending = pendingAlias;
+ const originRetained = retainedAlias;
+ if (
+ emittedFirst === undefined ||
+ targetStillPending === undefined ||
+ originStillPending === undefined ||
+ originRetained === undefined ||
+ ignoredName === undefined
+ ) {
+ throw new Error('first target update did not identify a pending relation');
+ }
+ const expected =
+ pruned === 'origin'
+ ? ['a.csv', 'b.csv', basename(originRetained)].toSorted()
+ : [basename(emittedFirst), basename(originRetained)].toSorted();
+ expect(callbackCount).toBe(1);
+ expect(pendingAlreadyEmitted).toBe(false);
+ expect(rebuildSucceeded).toBe(true);
+ expect(ignoredPath).toBe(true);
+ expect(generationAdvanced).toBe(true);
+ expect(physicalRetained).toBe(true);
+ expect(ignoredName).toBe(
+ basename(pruned === 'origin' ? originStillPending : targetStillPending),
+ );
+ expect(callbackTargets).toEqual(expected);
+ expect(watched.events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: emittedFirst }),
+ );
+ expect
+ .soft(
+ watched.events.filter(
+ (event) => event.kind === 'file-update' && event.path === targetStillPending,
+ ),
+ )
+ .toEqual([]);
+ expect.soft(targetNames(watched.watcher)).toEqual(expected);
+ watched.events.length = 0;
+ await deliverNotice(contentDir);
+ expect
+ .soft(
+ watched.events.filter(
+ (event) => event.kind === 'file-update' && event.path === targetStillPending,
+ ),
+ )
+ .toEqual([]);
+ expect.soft(targetNames(watched.watcher)).toEqual(expected);
+ },
+);
+
+test('a pending alias update carries newer shared metadata from another accepted hardlink', async () => {
+ const a = writeDoc('a.csv', 'old,target\n');
+ const aPeer = join(contentDir, 'a-peer.csv');
+ const b = writeDoc('b.csv', 'other,target\n');
+ const bPeer = join(contentDir, 'b-peer.csv');
+ const x = join(contentDir, 'x.csv');
+ const y = join(contentDir, 'y.csv');
+ linkSync(a, aPeer);
+ linkSync(b, bPeer);
+ symlinkSync(a, x);
+ symlinkSync(b, y);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(aPeer).dev, statSync(aPeer).ino]);
+ expect([statSync(b).dev, statSync(b).ino]).toEqual([statSync(bPeer).dev, statSync(bPeer).ino]);
+ expect(statSync(a).ino).not.toBe(statSync(b).ino);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries = ['a.csv', 'a-peer.csv', 'b.csv', 'b-peer.csv', 'x.csv', 'y.csv'];
+ let callbackCount = 0;
+ let firstTarget: string | undefined;
+ let pendingTarget: string | undefined;
+ let pendingPeer: string | undefined;
+ let pendingAlreadyEmitted = false;
+ let expectedSize: number | undefined;
+ let expectedModifiedTs: number | undefined;
+ let callbackGroupSize: number | undefined;
+ let callbackTargets: string[] = [];
+ let callbackBytes: string | undefined;
+ const watched = await watchContent(undefined, async (event) => {
+ if (event.kind !== 'file-update' || (event.path !== a && event.path !== b)) return;
+ if (firstTarget !== undefined) return;
+ callbackCount++;
+ firstTarget = event.path;
+ pendingTarget = event.path === a ? b : a;
+ pendingPeer = event.path === a ? bPeer : aPeer;
+ pendingAlreadyEmitted = watched.events.some(
+ (emitted) => emitted.kind === 'file-update' && emitted.path === pendingTarget,
+ );
+ writeFileSync(pendingPeer, 'new,longer,shared,metadata\n');
+ const stat = statSync(pendingPeer);
+ expectedSize = stat.size;
+ expectedModifiedTs = new Date(stat.mtimeMs).getTime();
+ watched.watcher.mutateFileIndex({
+ kind: 'file-update',
+ path: pendingPeer,
+ relativePath: basename(pendingPeer),
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ inode: Number(stat.ino),
+ });
+ callbackBytes = readFileSync(pendingTarget, 'utf8');
+ callbackGroupSize = [...watched.watcher.getAllFilesIndex()].find(
+ ([, entry]) =>
+ entry.kind === 'file' && entry.fileMembers?.regularPaths.includes(basename(pendingTarget)),
+ )?.[1].size;
+ callbackTargets = indexedFileTargets(watched.watcher);
+ });
+ const expectedTargets = ['a-peer.csv', 'a.csv', 'b-peer.csv', 'b.csv', 'x.csv', 'y.csv'];
+ expect(indexedFileTargets(watched.watcher)).toEqual(expectedTargets);
+ expect(realpathSync(x)).toBe(a);
+ expect(realpathSync(y)).toBe(b);
+ unlinkSync(x);
+ unlinkSync(y);
+ symlinkSync(b, x);
+ symlinkSync(a, y);
+ expect(realpathSync(x)).toBe(b);
+ expect(realpathSync(y)).toBe(a);
+ const priorSizes = { a: statSync(a).size, b: statSync(b).size };
+
+ await deliverNotice(contentDir);
+
+ const emittedFirst = firstTarget;
+ const targetStillPending = pendingTarget;
+ const updatedPeer = pendingPeer;
+ if (emittedFirst === undefined || targetStillPending === undefined || updatedPeer === undefined) {
+ throw new Error('first target update did not identify a pending hardlink group');
+ }
+ expect(callbackCount).toBe(1);
+ expect(pendingAlreadyEmitted).toBe(false);
+ expect(expectedSize).toBeDefined();
+ expect(expectedModifiedTs).toBeDefined();
+ expect(expectedSize).not.toBe(targetStillPending === a ? priorSizes.a : priorSizes.b);
+ expect(callbackBytes).toBe('new,longer,shared,metadata\n');
+ expect(callbackGroupSize).toBe(expectedSize);
+ expect(callbackTargets).toEqual(expectedTargets);
+ expect(watched.events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', path: emittedFirst }),
+ );
+ const later = watched.events.filter(
+ (event) => event.kind === 'file-update' && event.path === targetStillPending,
+ );
+ expect(later).toHaveLength(1);
+ expect.soft(later[0]).toMatchObject({
+ size: expectedSize,
+ modifiedTs: expectedModifiedTs,
+ });
+ expect.soft(indexedFileTargets(watched.watcher)).toEqual(expectedTargets);
+ expect(readFileSync(targetStillPending, 'utf8')).toBe('new,longer,shared,metadata\n');
+ expect(readFileSync(updatedPeer, 'utf8')).toBe('new,longer,shared,metadata\n');
+});
+
+async function listedReferencedAssetEntries(port: number) {
+ const response = await fetch(`http://127.0.0.1:${port}/api/documents`);
+ expect(response.status).toBe(200);
+ return (
+ (await response.json()) as {
+ documents: Array<{
+ kind: string;
+ docName?: string;
+ path?: string;
+ size?: number;
+ modified?: string;
+ referencedBy?: string[];
+ }>;
+ }
+ ).documents;
+}
+
+test('a warmed referenced asset leaves the document listing after a filter rebuild', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const a = writeDoc('a.csv', 'same,referenced,bytes\n');
+ const b = join(contentDir, 'b.csv');
+ linkSync(a, b);
+ const sourceContent = '# Source\n\n[A](a.csv)\n\n[B](b.csv)\n';
+ const source = writeDoc('source.md', sourceContent);
+ const ignore = writeDoc('.okignore', '');
+ const sourceStat = statSync(source);
+ const bStat = statSync(b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([bStat.dev, bStat.ino]);
+ const server = await bootInventoryServer();
+ try {
+ const before = await listedReferencedAssetEntries(server.port);
+ expect(before.filter((row) => row.docName === 'b.csv')).toEqual([
+ expect.objectContaining({
+ kind: 'asset',
+ path: 'b.csv',
+ size: bStat.size,
+ modified: bStat.mtime.toISOString(),
+ referencedBy: ['source'],
+ }),
+ ]);
+ expect(before.filter((row) => row.docName === 'a.csv')).toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ const beforeLinks = await inventoryForwardStatuses(server.port);
+ expect(beforeLinks).toMatchObject({ 'a.csv': 'exact', 'b.csv': 'exact' });
+
+ writeFileSync(ignore, 'b.csv\n');
+ expect((await server.serverInstance.contentFilter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(server.serverInstance.contentFilter.isPathIgnored('b.csv')).toBe(true);
+ expect(server.serverInstance.contentFilter.isPathIgnored('a.csv')).toBe(false);
+ const afterRebuild = await listedReferencedAssetEntries(server.port);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const afterNotice = await listedReferencedAssetEntries(server.port);
+
+ expect.soft(afterRebuild.filter((row) => row.docName === 'b.csv')).toEqual([]);
+ expect.soft(afterNotice.filter((row) => row.docName === 'b.csv')).toEqual([]);
+ for (const listing of [afterRebuild, afterNotice]) {
+ expect
+ .soft(listing.filter((row) => row.docName === 'a.csv'))
+ .toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ }
+ expect.soft(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'a.csv': 'exact',
+ 'b.csv': 'missing',
+ });
+ const asset = await fetch(`http://127.0.0.1:${server.port}/api/asset-text?path=a.csv`);
+ expect(asset.status).toBe(200);
+ expect(await asset.text()).toBe('same,referenced,bytes\n');
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).size).toBe(sourceStat.size);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ expect(readFileSync(b, 'utf8')).toBe('same,referenced,bytes\n');
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('a warmed exclusion yields a referenced asset after rebuild and completed notice', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const a = writeDoc('a.csv', 'same,referenced,bytes\n');
+ const b = join(contentDir, 'b.csv');
+ linkSync(a, b);
+ const sourceContent = '# Source\n\n[A](a.csv)\n\n[B](b.csv)\n';
+ const source = writeDoc('source.md', sourceContent);
+ const ignore = writeDoc('.okignore', 'b.csv\n');
+ const sourceStat = statSync(source);
+ const bStat = statSync(b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([bStat.dev, bStat.ino]);
+ const server = await bootInventoryServer();
+ try {
+ expect(server.serverInstance.contentFilter.isPathIgnored('b.csv')).toBe(true);
+ const before = await listedReferencedAssetEntries(server.port);
+ expect(before.filter((row) => row.docName === 'b.csv')).toEqual([]);
+ expect(before.filter((row) => row.docName === 'a.csv')).toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ expect(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'a.csv': 'exact',
+ 'b.csv': 'missing',
+ });
+
+ writeFileSync(ignore, '');
+ expect((await server.serverInstance.contentFilter.rebuildIgnorePatterns()).ok).toBe(true);
+ expect(server.serverInstance.contentFilter.isPathIgnored('b.csv')).toBe(false);
+ const beforeNotice = await listedReferencedAssetEntries(server.port);
+ expect(beforeNotice.filter((row) => row.docName === 'a.csv')).toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const afterNotice = await listedReferencedAssetEntries(server.port);
+
+ expect.soft(afterNotice.filter((row) => row.docName === 'b.csv')).toEqual([
+ expect.objectContaining({
+ kind: 'asset',
+ path: 'b.csv',
+ size: bStat.size,
+ modified: bStat.mtime.toISOString(),
+ referencedBy: ['source'],
+ }),
+ ]);
+ expect
+ .soft(afterNotice.filter((row) => row.docName === 'a.csv'))
+ .toEqual([
+ expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
+ ]);
+ expect.soft(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'a.csv': 'exact',
+ 'b.csv': 'exact',
+ });
+ const asset = await fetch(`http://127.0.0.1:${server.port}/api/asset-text?path=a.csv`);
+ expect(asset.status).toBe(200);
+ expect(await asset.text()).toBe('same,referenced,bytes\n');
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).size).toBe(sourceStat.size);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ expect(readFileSync(b, 'utf8')).toBe('same,referenced,bytes\n');
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([statSync(b).dev, statSync(b).ino]);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('a warmed folder alias reference follows its retarget after notice', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const first = join(contentDir, 'first');
+ const second = join(contentDir, 'second');
+ mkdirSync(first);
+ mkdirSync(second);
+ const firstData = writeDoc('first/data.csv', 'first,referenced,bytes\n');
+ const secondData = writeDoc('second/data.csv', 'second,other,bytes\n');
+ const linked = join(contentDir, 'linked');
+ symlinkSync(first, linked);
+ const sourceContent = '# Source\n\n[Data](linked/data.csv)\n';
+ const source = writeDoc('source.md', sourceContent);
+ const sourceStat = statSync(source);
+ const firstStat = statSync(firstData);
+ const secondStat = statSync(secondData);
+ expect(lstatSync(linked).isSymbolicLink()).toBe(true);
+ expect(realpathSync(linked)).toBe(first);
+ const server = await bootInventoryServer();
+ try {
+ const before = await listedReferencedAssetEntries(server.port);
+ expect(before.filter((row) => row.docName === 'first/data.csv')).toEqual([
+ expect.objectContaining({
+ kind: 'asset',
+ path: 'first/data.csv',
+ size: firstStat.size,
+ modified: firstStat.mtime.toISOString(),
+ referencedBy: ['source'],
+ }),
+ ]);
+ expect(before.filter((row) => row.docName === 'second/data.csv')).toEqual([
+ expect.objectContaining({ kind: 'file', path: 'second/data.csv' }),
+ ]);
+ expect(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'linked/data.csv': 'exact',
+ });
+
+ unlinkSync(linked);
+ symlinkSync(second, linked);
+ expect(realpathSync(linked)).toBe(second);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const after = await listedReferencedAssetEntries(server.port);
+
+ expect.soft(after.filter((row) => row.docName === 'second/data.csv')).toEqual([
+ expect.objectContaining({
+ kind: 'asset',
+ path: 'second/data.csv',
+ size: secondStat.size,
+ modified: secondStat.mtime.toISOString(),
+ referencedBy: ['source'],
+ }),
+ ]);
+ expect
+ .soft(after.filter((row) => row.docName === 'first/data.csv'))
+ .toEqual([expect.objectContaining({ kind: 'file', path: 'first/data.csv' })]);
+ expect.soft(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'linked/data.csv': 'exact',
+ });
+ const asset = await fetch(
+ `http://127.0.0.1:${server.port}/api/asset-text?path=second/data.csv`,
+ );
+ expect(asset.status).toBe(200);
+ expect(await asset.text()).toBe('second,other,bytes\n');
+ const aliasAsset = await fetch(
+ `http://127.0.0.1:${server.port}/api/asset-text?path=linked/data.csv`,
+ );
+ expect(aliasAsset.status).toBe(400);
+ expect(readFileSync(firstData, 'utf8')).toBe('first,referenced,bytes\n');
+ expect(readFileSync(secondData, 'utf8')).toBe('second,other,bytes\n');
+ expect(lstatSync(linked).isSymbolicLink()).toBe(true);
+ expect(realpathSync(linked)).toBe(second);
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).size).toBe(sourceStat.size);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ } finally {
+ await server.destroy();
+ }
+});
+
+async function listedProjectedEntries(port: number, dir?: string) {
+ const suffix = dir ? `?dir=${encodeURIComponent(dir)}` : '';
+ const response = await fetch(`http://127.0.0.1:${port}/api/documents${suffix}`);
+ expect(response.status).toBe(200);
+ return (
+ (await response.json()) as {
+ documents: Array<{
+ kind: string;
+ docName?: string;
+ path?: string;
+ docExt?: string;
+ size?: number;
+ modified?: string;
+ isSymlink?: boolean;
+ canonicalDocName?: string | null;
+ targetPath?: string | null;
+ }>;
+ }
+ ).documents;
+}
+
+test('a folder alias lists a general symlink member beside projected regular members', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = join(contentDir, 'real');
+ mkdirSync(real);
+ const a = writeDoc('real/a.csv', 'shared,physical,bytes\n');
+ const b = join(real, 'b.csv');
+ linkSync(a, b);
+ const y = join(real, 'y.csv');
+ symlinkSync(b, y);
+ const linked = join(contentDir, 'linked');
+ symlinkSync(real, linked);
+ const sourceContent = '# Source\n\n[File](linked/y.csv)\n';
+ const source = writeDoc('source.md', sourceContent);
+ const sourceStat = statSync(source);
+ const bStat = statSync(b);
+ expect([statSync(a).dev, statSync(a).ino]).toEqual([bStat.dev, bStat.ino]);
+ const server = await bootInventoryServer();
+ try {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const all = await listedProjectedEntries(server.port);
+ const onlyLinked = await listedProjectedEntries(server.port, 'linked');
+ const direct = all.filter((row) => row.kind === 'file' && row.docName === 'real/y.csv');
+ expect(direct).toEqual([
+ expect.objectContaining({
+ path: 'real/y.csv',
+ size: bStat.size,
+ modified: bStat.mtime.toISOString(),
+ isSymlink: true,
+ targetPath: 'real/b.csv',
+ }),
+ ]);
+ const representative = direct[0]?.canonicalDocName;
+ expect(['real/a.csv', 'real/b.csv']).toContain(representative);
+ for (const rows of [all, onlyLinked]) {
+ expect(rows.filter((row) => row.kind === 'file' && row.docName === 'linked/a.csv')).toEqual([
+ expect.objectContaining({
+ path: 'linked/a.csv',
+ isSymlink: true,
+ canonicalDocName: representative,
+ targetPath: 'real/a.csv',
+ }),
+ ]);
+ expect(rows.filter((row) => row.kind === 'file' && row.docName === 'linked/b.csv')).toEqual([
+ expect.objectContaining({
+ path: 'linked/b.csv',
+ isSymlink: true,
+ canonicalDocName: representative,
+ targetPath: 'real/b.csv',
+ }),
+ ]);
+ expect
+ .soft(rows.filter((row) => row.kind === 'file' && row.docName === 'linked/y.csv'))
+ .toEqual([
+ expect.objectContaining({
+ path: 'linked/y.csv',
+ size: bStat.size,
+ modified: bStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: representative,
+ targetPath: 'real/b.csv',
+ }),
+ ]);
+ }
+ expect(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'linked/y.csv': 'exact',
+ });
+ expect(lstatSync(y).isSymbolicLink()).toBe(true);
+ expect(realpathSync(y)).toBe(b);
+ expect(lstatSync(linked).isSymbolicLink()).toBe(true);
+ expect(realpathSync(linked)).toBe(real);
+ expect(readFileSync(a, 'utf8')).toBe('shared,physical,bytes\n');
+ expect(readFileSync(b, 'utf8')).toBe('shared,physical,bytes\n');
+ expect(readFileSync(y, 'utf8')).toBe('shared,physical,bytes\n');
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test('a folder alias lists a contained Markdown alias beside its canonical document', async () => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = join(contentDir, 'real');
+ const other = join(contentDir, 'other');
+ mkdirSync(real);
+ mkdirSync(other);
+ const canonical = writeDoc('other/a.mdx', '# Canonical\n');
+ const alias = join(real, 'y.md');
+ symlinkSync(canonical, alias);
+ const linked = join(contentDir, 'linked');
+ symlinkSync(real, linked);
+ const sourceContent = '# Source\n\n[Document](linked/y.md)\n';
+ const source = writeDoc('source.md', sourceContent);
+ const sourceStat = statSync(source);
+ const canonicalStat = statSync(canonical);
+ const server = await bootInventoryServer();
+ try {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const all = await listedProjectedEntries(server.port);
+ const onlyReal = await listedProjectedEntries(server.port, 'real');
+ const onlyLinked = await listedProjectedEntries(server.port, 'linked');
+ expect(all.filter((row) => row.kind === 'document' && row.docName === 'other/a')).toEqual([
+ expect.objectContaining({ docExt: '.mdx', size: canonicalStat.size }),
+ ]);
+ expect
+ .soft(onlyReal.filter((row) => row.kind === 'document').map((row) => row.docName))
+ .toEqual(['real/y']);
+ expect
+ .soft(onlyLinked.filter((row) => row.kind === 'document').map((row) => row.docName))
+ .toEqual(['linked/y']);
+ expect(all.filter((row) => row.kind === 'document' && row.docName === 'real/y')).toEqual([
+ expect.objectContaining({
+ docExt: '.mdx',
+ size: canonicalStat.size,
+ modified: canonicalStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'other/a',
+ targetPath: 'other/a.mdx',
+ }),
+ ]);
+ expect
+ .soft(onlyReal.filter((row) => row.kind === 'document' && row.docName === 'real/y'))
+ .toEqual([
+ expect.objectContaining({
+ docExt: '.mdx',
+ canonicalDocName: 'other/a',
+ targetPath: 'other/a.mdx',
+ }),
+ ]);
+ for (const rows of [all, onlyLinked]) {
+ expect
+ .soft(rows.filter((row) => row.kind === 'document' && row.docName === 'linked/y'))
+ .toEqual([
+ expect.objectContaining({
+ docExt: '.mdx',
+ size: canonicalStat.size,
+ modified: canonicalStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'other/a',
+ targetPath: 'other/a.mdx',
+ }),
+ ]);
+ }
+ const projectedRead = await fetch(
+ `http://127.0.0.1:${server.port}/api/document?docName=linked/y`,
+ );
+ expect.soft(projectedRead.status).toBe(200);
+ const projectedBody = (await projectedRead.json()) as { content?: string };
+ expect.soft(projectedBody.content).toBe('# Canonical\n');
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(realpathSync(linked)).toBe(real);
+ expect(readFileSync(canonical, 'utf8')).toBe('# Canonical\n');
+ expect(readFileSync(alias, 'utf8')).toBe('# Canonical\n');
+ expect(readFileSync(source, 'utf8')).toBe(sourceContent);
+ expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
+ } finally {
+ await server.destroy();
+ }
+});
+
+test.each([
+ { order: 'canonical-first', delivery: 'notice' },
+ { order: 'alias-first', delivery: 'notice' },
+ { order: 'canonical-first', delivery: 'ordinary' },
+ { order: 'alias-first', delivery: 'ordinary' },
+] as const)(
+ 'same-name Markdown alias lists one document identity with $order scanning and $delivery removal',
+ async ({ order, delivery }) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = join(contentDir, 'real');
+ mkdirSync(real);
+ const content = '# One logical page\n';
+ const canonical = writeDoc('real/note.mdx', content);
+ const alias = join(real, 'note.md');
+ symlinkSync(canonical, alias);
+ const linked = join(contentDir, 'linked');
+ symlinkSync(real, linked);
+ const canonicalStat = statSync(canonical);
+ scanSchedule.orderedPath = real;
+ scanSchedule.orderedEntries =
+ order === 'canonical-first' ? ['note.mdx', 'note.md'] : ['note.md', 'note.mdx'];
+ const server = await bootInventoryServer();
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ try {
+ const held = await server.serverInstance.hocuspocus.openDirectConnection('real/note');
+ connections.push(held);
+ const document = held.document;
+ const lifecycle = document.getMap('lifecycle');
+ expect(document.getText('source').toString()).toBe(content);
+ expect(lifecycle.get('status')).not.toBe('deleted-upstream');
+ const verify = async () => {
+ const all = await listedProjectedEntries(server.port);
+ const onlyReal = await listedProjectedEntries(server.port, 'real');
+ const onlyLinked = await listedProjectedEntries(server.port, 'linked');
+ for (const rows of [all, onlyReal]) {
+ expect
+ .soft(rows.filter((row) => row.kind === 'document' && row.docName === 'real/note'))
+ .toEqual([
+ expect.objectContaining({
+ docExt: '.mdx',
+ size: canonicalStat.size,
+ modified: canonicalStat.mtime.toISOString(),
+ isSymlink: false,
+ canonicalDocName: null,
+ targetPath: null,
+ }),
+ ]);
+ }
+ for (const rows of [all, onlyLinked]) {
+ expect
+ .soft(rows.filter((row) => row.kind === 'document' && row.docName === 'linked/note'))
+ .toEqual([
+ expect.objectContaining({
+ docExt: '.mdx',
+ size: canonicalStat.size,
+ modified: canonicalStat.mtime.toISOString(),
+ isSymlink: true,
+ canonicalDocName: 'real/note',
+ targetPath: 'real/note.mdx',
+ }),
+ ]);
+ }
+ for (const name of ['real/note', 'linked/note']) {
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/document?docName=${name}`,
+ );
+ expect(response.status).toBe(200);
+ const body = (await response.json()) as { content?: string };
+ expect(body.content).toBe(content);
+ }
+ };
+ await verify();
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ await verify();
+ expect(lstatSync(canonical).isFile()).toBe(true);
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(realpathSync(linked)).toBe(real);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ expect(readFileSync(alias, 'utf8')).toBe(content);
+ unlinkSync(alias);
+ if (delivery === 'notice') {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ } else {
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: alias }]);
+ }
+ expect.soft(lifecycle.get('status')).not.toBe('deleted-upstream');
+ expect
+ .soft(server.serverInstance.hocuspocus.documents.get('real/note') === document)
+ .toBe(true);
+ expect(document.getText('source').toString()).toBe(content);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ expect(existsSync(alias)).toBe(false);
+ await verify();
+ unlinkSync(canonical);
+ if (delivery === 'notice') {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ } else {
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: canonical }]);
+ }
+ expect(lifecycle.get('status')).toBe('deleted-upstream');
+ expect(server.serverInstance.hocuspocus.documents.has('real/note')).toBe(false);
+ expect(
+ (await listedProjectedEntries(server.port)).filter((row) => row.kind === 'document'),
+ ).toEqual([]);
+ const gone = await fetch(`http://127.0.0.1:${server.port}/api/document?docName=real/note`);
+ expect(gone.status).toBe(404);
+ expect(existsSync(canonical)).toBe(false);
+ } finally {
+ scanSchedule.orderedPath = null;
+ scanSchedule.orderedEntries = null;
+ for (const connection of connections) await connection.disconnect();
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['canonical-first', 'alias-first'] as const)(
+ 'folder aliases preserve document suffixes with $0 scanning',
+ async (order) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const real = join(contentDir, 'real.md');
+ mkdirSync(real);
+ const bytes = 'directory,member\n';
+ const file = writeDoc('real.md/data.csv', bytes);
+ const aliases = ['linked.mdx', 'mirror.md'];
+ for (const alias of aliases) symlinkSync(real, join(contentDir, alias));
+ writeDoc(
+ 'source.md',
+ '# Source\n\n[Data](linked.mdx/data.csv)\n\n[Mirror](mirror.md/data.csv)\n',
+ );
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries =
+ order === 'canonical-first'
+ ? ['real.md', 'linked.mdx', 'mirror.md', 'source.md']
+ : ['mirror.md', 'linked.mdx', 'real.md', 'source.md'];
+ const server = await bootInventoryServer();
+ try {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ const all = await listedProjectedEntries(server.port);
+ expect(all.filter((row) => row.kind === 'folder' && row.path === 'real.md')).toHaveLength(1);
+ for (const alias of aliases) {
+ const scoped = await listedProjectedEntries(server.port, alias);
+ for (const rows of [all, scoped]) {
+ expect
+ .soft(rows.filter((row) => row.kind === 'folder' && row.path === alias))
+ .toEqual([expect.objectContaining({ isSymlink: true, targetPath: 'real.md' })]);
+ expect
+ .soft(rows.filter((row) => row.kind === 'file' && row.path === `${alias}/data.csv`))
+ .toEqual([
+ expect.objectContaining({ isSymlink: true, targetPath: 'real.md/data.csv' }),
+ ]);
+ }
+ }
+ expect.soft(await inventoryForwardStatuses(server.port)).toMatchObject({
+ 'linked.mdx/data.csv': 'exact',
+ 'mirror.md/data.csv': 'exact',
+ });
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/asset-text?path=${encodeURIComponent('real.md/data.csv')}`,
+ );
+ expect(response.status).toBe(200);
+ expect(await response.text()).toBe(bytes);
+ expect(lstatSync(real).isDirectory()).toBe(true);
+ expect(readFileSync(file, 'utf8')).toBe(bytes);
+ for (const alias of aliases) {
+ const linked = join(contentDir, alias);
+ expect(lstatSync(linked).isSymbolicLink()).toBe(true);
+ expect(realpathSync(linked)).toBe(real);
+ expect(readFileSync(join(linked, 'data.csv'), 'utf8')).toBe(bytes);
+ }
+ } finally {
+ scanSchedule.orderedPath = null;
+ scanSchedule.orderedEntries = null;
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['notice', 'ordinary'] as const)(
+ '$0 removal of a document-suffixed folder recovers only its actual file deletions',
+ async (delivery) => {
+ const folder = join(contentDir, 'notes.md');
+ mkdirSync(folder);
+ const assetFolder = join(contentDir, 'images.png');
+ mkdirSync(assetFolder);
+ const asset = writeDoc('gone.png', 'asset bytes\n');
+ const survivor = writeDoc('notes.mdx', '# Surviving page\n');
+ const child = writeDoc('notes.md/child.md', '# Removed child\n');
+ const data = writeDoc('notes.md/data.csv', 'removed,child\n');
+ const gone = writeDoc('gone.md', '# Removed page\n');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFolderIndex().has('notes.md')).toBe(true);
+ expect(watcher.getFolderIndex().has('images.png')).toBe(true);
+ expect(indexedFileTargets(watcher)).toContain('gone.png');
+ expect(watcher.getFileIndex().get('notes')?.canonicalPath).toBe(survivor);
+ expect(watcher.getFileIndex().has('notes.md/child')).toBe(true);
+ expect(watcher.getFileIndex().has('gone')).toBe(true);
+ expect(getDocExtension('notes')).toBe('.mdx');
+ rmSync(folder, { recursive: true });
+ rmSync(assetFolder, { recursive: true });
+ unlinkSync(gone);
+ unlinkSync(asset);
+ if (delivery === 'notice') {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ } else {
+ await nativeSubscriptionOn(contentDir).deliver([
+ { type: 'delete', path: folder },
+ { type: 'delete', path: assetFolder },
+ { type: 'delete', path: gone },
+ { type: 'delete', path: asset },
+ ]);
+ }
+ expect(events).toContainEqual({
+ kind: 'folder-delete',
+ path: folder,
+ relativePath: 'notes.md',
+ });
+ expect(events).toContainEqual({
+ kind: 'folder-delete',
+ path: assetFolder,
+ relativePath: 'images.png',
+ });
+ expect(events).toContainEqual({ kind: 'asset-delete', path: asset, relativePath: 'gone.png' });
+ expect(events).toContainEqual({ kind: 'file-delete', path: asset, relativePath: 'gone.png' });
+ expect
+ .soft(
+ events.filter(
+ (event) =>
+ 'path' in event &&
+ event.path === assetFolder &&
+ (event.kind === 'asset-delete' || event.kind === 'file-delete'),
+ ),
+ )
+ .toEqual([]);
+ expect(events).toContainEqual({ kind: 'delete', path: child, docName: 'notes.md/child' });
+ expect(events).toContainEqual({ kind: 'delete', path: gone, docName: 'gone' });
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ kind: 'file-delete',
+ path: data,
+ relativePath: 'notes.md/data.csv',
+ }),
+ );
+ expect
+ .soft(events.filter((event) => 'docName' in event && event.docName === 'notes'))
+ .toEqual([]);
+ expect.soft(getDocExtension('notes')).toBe('.mdx');
+ expect(watcher.getFolderIndex().has('notes.md')).toBe(false);
+ expect(watcher.getFolderIndex().has('images.png')).toBe(false);
+ expect(indexedFileTargets(watcher)).not.toContain('gone.png');
+ expect.soft(watcher.getFileIndex().get('notes')?.canonicalPath).toBe(survivor);
+ expect(watcher.getFileIndex().has('notes.md/child')).toBe(false);
+ expect(watcher.getFileIndex().has('gone')).toBe(false);
+ expect(readFileSync(survivor, 'utf8')).toBe('# Surviving page\n');
+ events.length = 0;
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(events).toEqual([]);
+ },
+);
+
+test.each([
+ { folderExt: '.md', docExt: '.mdx' },
+ { folderExt: '.mdx', docExt: '.md' },
+] as const)(
+ 'removing a $folderExt folder keeps its same-stem $docExt page loaded',
+ async ({ folderExt, docExt }) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const folderName = `notes${folderExt}`;
+ const folder = join(contentDir, folderName);
+ mkdirSync(folder);
+ const content = '# Still here\n\nSurviving document bytes.\n';
+ const survivor = writeDoc(`notes${docExt}`, content);
+ const gone = writeDoc('gone.md', '# Really removed\n');
+ const server = await bootInventoryServer();
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ try {
+ expect(getDocExtension('notes')).toBe(docExt);
+ const held = await server.serverInstance.hocuspocus.openDirectConnection('notes');
+ connections.push(held);
+ const removed = await server.serverInstance.hocuspocus.openDirectConnection('gone');
+ connections.push(removed);
+ const document = held.document;
+ const lifecycle = document.getMap('lifecycle');
+ const removedLifecycle = removed.document.getMap('lifecycle');
+ expect(document.getText('source').toString()).toBe(content);
+ expect(server.serverInstance.hocuspocus.documents.get('notes')).toBe(document);
+ expect(lifecycle.get('status')).not.toBe('deleted-upstream');
+ expect(removed.document.getText('source').toString()).toBe('# Really removed\n');
+ const before = await listedProjectedEntries(server.port);
+ expect(before.filter((row) => row.kind === 'folder' && row.path === folderName)).toHaveLength(
+ 1,
+ );
+ expect(
+ before.filter((row) => row.kind === 'document' && row.docName === 'notes'),
+ ).toHaveLength(1);
+ rmSync(folder, { recursive: true });
+ unlinkSync(gone);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect.soft(lifecycle.get('status')).not.toBe('deleted-upstream');
+ expect.soft(server.serverInstance.hocuspocus.documents.get('notes') === document).toBe(true);
+ expect.soft(getDocExtension('notes')).toBe(docExt);
+ expect.soft(document.getText('source').toString()).toBe(content);
+ expect(removedLifecycle.get('status')).toBe('deleted-upstream');
+ const after = await listedProjectedEntries(server.port);
+ expect(after.filter((row) => row.kind === 'folder' && row.path === folderName)).toEqual([]);
+ expect(after.filter((row) => row.kind === 'document' && row.docName === 'gone')).toEqual([]);
+ expect
+ .soft(after.filter((row) => row.kind === 'document' && row.docName === 'notes'))
+ .toEqual([expect.objectContaining({ docExt, isSymlink: false, targetPath: null })]);
+ const response = await fetch(`http://127.0.0.1:${server.port}/api/document?docName=notes`);
+ expect.soft(response.status).toBe(200);
+ const body = (await response.json()) as { content?: string };
+ expect.soft(body.content).toBe(content);
+ expect(readFileSync(survivor, 'utf8')).toBe(content);
+ expect(existsSync(gone)).toBe(false);
+ expect(existsSync(folder)).toBe(false);
+ } finally {
+ for (const connection of connections) await connection.disconnect();
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['folder to file', 'file to folder'] as const)(
+ 'notice recovery preserves the actual kinds during a $0 transition',
+ async (transition) => {
+ const path = join(contentDir, 'entry.md');
+ const content = '# Actual page\n';
+ if (transition === 'folder to file') mkdirSync(path);
+ else writeFileSync(path, content);
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFolderIndex().has('entry.md')).toBe(transition === 'folder to file');
+ expect(watcher.getFileIndex().has('entry')).toBe(transition === 'file to folder');
+ rmSync(path, { recursive: true });
+ if (transition === 'folder to file') writeFileSync(path, content);
+ else mkdirSync(path);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ if (transition === 'folder to file') {
+ expect(events).toContainEqual({ kind: 'folder-delete', path, relativePath: 'entry.md' });
+ expect(events).toContainEqual({ kind: 'create', path, docName: 'entry', content });
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect(watcher.getFileIndex().get('entry')?.canonicalPath).toBe(path);
+ expect(watcher.getFolderIndex().has('entry.md')).toBe(false);
+ expect(readFileSync(path, 'utf8')).toBe(content);
+ } else {
+ expect(events).toContainEqual({ kind: 'delete', path, docName: 'entry' });
+ expect(events).toContainEqual({ kind: 'folder-create', path, relativePath: 'entry.md' });
+ expect(events.filter((event) => event.kind === 'create')).toEqual([]);
+ expect(watcher.getFileIndex().has('entry')).toBe(false);
+ expect(watcher.getFolderIndex().has('entry.md')).toBe(true);
+ expect(lstatSync(path).isDirectory()).toBe(true);
+ }
+ },
+);
+
+test.each([
+ { state: 'retained', delivery: 'notice' },
+ { state: 'deleted', delivery: 'notice' },
+ { state: 'deleted', delivery: 'ordinary' },
+] as const)(
+ 'a $delivery batch preserves a public file replacement that is $state',
+ async ({ state, delivery }) => {
+ const path = join(contentDir, 'public.md');
+ mkdirSync(path);
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFolderIndex().has('public.md')).toBe(true);
+ rmSync(path, { recursive: true });
+ const content = '# Public replacement\n';
+ writeFileSync(path, content);
+ registerWrite(path, contentHash(content));
+ watcher.mutateFileIndex({ kind: 'create', path, docName: 'public', content });
+ expect(watcher.getFileIndex().get('public')?.canonicalPath).toBe(path);
+ expect(readFileSync(path, 'utf8')).toBe(content);
+ if (state === 'deleted') unlinkSync(path);
+ if (delivery === 'notice') {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ } else {
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path }]);
+ }
+ if (state === 'deleted') {
+ expect.soft(events).toContainEqual({ kind: 'delete', path, docName: 'public' });
+ expect(watcher.getFileIndex().has('public')).toBe(false);
+ expect(existsSync(path)).toBe(false);
+ } else {
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect(watcher.getFileIndex().get('public')?.canonicalPath).toBe(path);
+ expect(readFileSync(path, 'utf8')).toBe(content);
+ }
+ expect(watcher.getFolderIndex().has('public.md')).toBe(false);
+ },
+);
+
+test('a notice after index-only reseeding keeps a replacement directory and its children', async () => {
+ const path = writeDoc('reseed.md', '# Former document\n');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFileIndex().has('reseed')).toBe(true);
+ expect(watcher.getFolderIndex().has('reseed.md')).toBe(false);
+ unlinkSync(path);
+ mkdirSync(path);
+ const child = writeDoc('reseed.md/child.mdx', '# Current child\n');
+ const data = writeDoc('reseed.md/data.csv', 'current,child\n');
+ await watcher.rescanFromDisk();
+ expect(events).toEqual([]);
+ expect(watcher.getFileIndex().has('reseed')).toBe(true);
+ expect(watcher.getFolderIndex().has('reseed.md')).toBe(true);
+ expect(watcher.getFileIndex().get('reseed.md/child')?.canonicalPath).toBe(child);
+ expect(indexedFileTargets(watcher)).toContain('reseed.md/data.csv');
+ expect(getDocExtension('reseed.md/child')).toBe('.mdx');
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(events).toContainEqual({ kind: 'delete', path, docName: 'reseed' });
+ expect.soft(events.filter((event) => event.kind === 'folder-delete')).toEqual([]);
+ expect
+ .soft(
+ events.filter((event) => 'path' in event && (event.path === child || event.path === data)),
+ )
+ .toEqual([]);
+ expect(watcher.getFileIndex().has('reseed')).toBe(false);
+ expect(watcher.getFolderIndex().has('reseed.md')).toBe(true);
+ expect(watcher.getFileIndex().get('reseed.md/child')?.canonicalPath).toBe(child);
+ expect(indexedFileTargets(watcher)).toContain('reseed.md/data.csv');
+ expect.soft(getDocExtension('reseed.md/child')).toBe('.mdx');
+ expect(lstatSync(path).isDirectory()).toBe(true);
+ expect(readFileSync(child, 'utf8')).toBe('# Current child\n');
+ expect(readFileSync(data, 'utf8')).toBe('current,child\n');
+});
+
+test('ordinary deletion removes a nonrepresentative file member that replaced a directory', async () => {
+ const path = join(contentDir, 'member.png');
+ mkdirSync(path);
+ const outside = writeDoc('outside.png', 'shared image bytes');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ rmSync(path, { recursive: true });
+ linkSync(outside, path);
+ const stat = statSync(path);
+ watcher.mutateFileIndex({
+ kind: 'file-create',
+ path,
+ relativePath: 'member.png',
+ size: stat.size,
+ modifiedTs: stat.mtimeMs,
+ });
+ const rows = [...watcher.getAllFilesIndex()].filter(([, entry]) => entry.kind === 'file');
+ expect(rows).toHaveLength(1);
+ expect(rows[0]?.[0]).toBe('outside.png');
+ expect(rows[0]?.[1].fileMembers?.regularPaths).toEqual(
+ expect.arrayContaining(['member.png', 'outside.png']),
+ );
+ expect(watcher.getFolderIndex().has('member.png')).toBe(true);
+ expect(statSync(outside).ino).toBe(stat.ino);
+ unlinkSync(path);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path }]);
+ expect.soft(events).toContainEqual({ kind: 'file-delete', path, relativePath: 'member.png' });
+ expect.soft(events).toContainEqual({ kind: 'asset-delete', path, relativePath: 'member.png' });
+ expect(events).toContainEqual({ kind: 'folder-delete', path, relativePath: 'member.png' });
+ expect.soft(indexedFileTargets(watcher)).toEqual(['outside.png']);
+ expect(watcher.getFolderIndex().has('member.png')).toBe(false);
+ expect(events.filter((event) => 'path' in event && event.path === outside)).toEqual([]);
+ expect(readFileSync(outside, 'utf8')).toBe('shared image bytes');
+ expect(existsSync(path)).toBe(false);
+});
+
+test('ordinary deletion removes a physical Markdown alias that replaced a directory', async () => {
+ const path = join(contentDir, 'linked.md');
+ mkdirSync(path);
+ const canonical = writeDoc('canonical.mdx', '# Canonical survives\n');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ rmSync(path, { recursive: true });
+ symlinkSync(canonical, path);
+ await watcher.rescanFromDisk();
+ expect(watcher.getFolderIndex().has('linked.md')).toBe(true);
+ expect(watcher.getAliasMap().get('linked')).toBe('canonical');
+ expect(realpathSync(path)).toBe(canonical);
+ expect(events).toEqual([]);
+ unlinkSync(path);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path }]);
+ expect.soft(events).toContainEqual({ kind: 'delete', path, docName: 'linked' });
+ expect(events).toContainEqual({ kind: 'folder-delete', path, relativePath: 'linked.md' });
+ expect(watcher.getAliasMap().has('linked')).toBe(false);
+ expect(watcher.getFileIndex().get('canonical')?.canonicalPath).toBe(canonical);
+ expect(watcher.getFolderIndex().has('linked.md')).toBe(false);
+ expect(getDocExtension('canonical')).toBe('.mdx');
+ expect(readFileSync(canonical, 'utf8')).toBe('# Canonical survives\n');
+});
+
+test('ordinary folder deletion keeps a Markdown alias with the same normalized name', async () => {
+ const path = join(contentDir, 'linked.mdx');
+ mkdirSync(path);
+ const canonical = writeDoc('canonical.md', '# Alias target\n');
+ const alias = join(contentDir, 'linked.md');
+ symlinkSync(canonical, alias);
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFolderIndex().has('linked.mdx')).toBe(true);
+ expect(watcher.getAliasMap().get('linked')).toBe('canonical');
+ rmSync(path, { recursive: true });
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path }]);
+ expect(events).toContainEqual({ kind: 'folder-delete', path, relativePath: 'linked.mdx' });
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect.soft(watcher.getAliasMap().get('linked')).toBe('canonical');
+ expect(watcher.getFileIndex().get('canonical')?.canonicalPath).toBe(canonical);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(readFileSync(alias, 'utf8')).toBe('# Alias target\n');
+ events.length = 0;
+ unlinkSync(alias);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect.soft(events).toContainEqual({ kind: 'delete', path: alias, docName: 'linked' });
+ expect(events.some((event) => 'path' in event && event.path === path)).toBe(false);
+ expect(watcher.getAliasMap().has('linked')).toBe(false);
+ expect(watcher.getFileIndex().get('canonical')?.canonicalPath).toBe(canonical);
+ expect(readFileSync(canonical, 'utf8')).toBe('# Alias target\n');
+});
+
+test('legacy raw-event handling retains deletion of a logical alias beside a prior folder row', async () => {
+ const path = join(contentDir, 'linked.md');
+ mkdirSync(path);
+ const canonical = writeDoc('canonical.mdx', '# Legacy target\n');
+ const files: Parameters<typeof handleRawEvents>[3] = new Map();
+ const folders: Parameters<typeof handleRawEvents>[4] = new Map();
+ const aliases = new Map<string, string>();
+ const events: DiskEvent[] = [];
+ const deliver = (raw: Parameters<typeof handleRawEvents>[0]) =>
+ handleRawEvents(
+ raw,
+ contentDir,
+ undefined,
+ files,
+ folders,
+ async (event) => {
+ events.push(event);
+ },
+ aliases,
+ );
+ await deliver([
+ { type: 'create', path },
+ { type: 'create', path: canonical },
+ ]);
+ rmSync(path, { recursive: true });
+ symlinkSync(canonical, path);
+ await deliver([{ type: 'create', path }]);
+ expect(folders.has('linked.md')).toBe(true);
+ expect(aliases.get('linked')).toBe('canonical');
+ expect(files.get('canonical')?.canonicalPath).toBe(canonical);
+ events.length = 0;
+ unlinkSync(path);
+ await deliver([{ type: 'delete', path }]);
+ expect.soft(events).toContainEqual({ kind: 'delete', path, docName: 'linked' });
+ expect(events).toContainEqual({ kind: 'folder-delete', path, relativePath: 'linked.md' });
+ expect.soft(aliases.has('linked')).toBe(false);
+ expect(files.get('canonical')?.canonicalPath).toBe(canonical);
+ expect(folders.has('linked.md')).toBe(false);
+ expect(readFileSync(canonical, 'utf8')).toBe('# Legacy target\n');
+});
+
+test.each([
+ { delivery: 'notice', preparation: 'initial scan' },
+ { delivery: 'ordinary', preparation: 'initial scan' },
+ { delivery: 'notice', preparation: 'canonical update' },
+ { delivery: 'ordinary', preparation: 'canonical update' },
+] as const)(
+ '$delivery removal retires only same-name Markdown alias membership after $preparation',
+ async ({ delivery, preparation }) => {
+ let content = '# Membership target\n';
+ const canonical = writeDoc('member.mdx', content);
+ const alias = join(contentDir, 'member.md');
+ symlinkSync(canonical, alias);
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(watcher.getFileIndex().get('member')?.aliases).toContain('member');
+ expect(watcher.getAliasMap().get('member')).toBe('member');
+ expect(lastKnownHash.get(canonical)).toBe(contentHash(content));
+ expect(getDocExtension('member')).toBe('.mdx');
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: alias }]);
+ expect(lastKnownHash.get(alias)).toBe(contentHash(content));
+ events.length = 0;
+ if (preparation === 'canonical update') {
+ content = '# Updated membership target\n';
+ writeFileSync(canonical, content);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: canonical }]);
+ expect(events).toContainEqual({
+ kind: 'update',
+ path: canonical,
+ docName: 'member',
+ content,
+ previousIndexedFields: expect.any(Object),
+ });
+ expect.soft(watcher.getAliasMap().get('member')).toBe('member');
+ expect(watcher.getFileIndex().get('member')?.aliases).toContain('member');
+ events.length = 0;
+ }
+ const deliverDelete = async (path: string) => {
+ if (delivery === 'notice') {
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ } else {
+ const deletion = { type: 'delete' as const, path };
+ await nativeSubscriptionOn(contentDir).deliver(
+ path === alias ? [deletion, { ...deletion }] : [deletion],
+ );
+ }
+ };
+ unlinkSync(alias);
+ await deliverDelete(alias);
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect.soft(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect.soft(watcher.getFileIndex().get('member')?.aliases).toEqual([]);
+ expect.soft(watcher.getAliasMap().has('member')).toBe(false);
+ expect.soft(lastKnownHash.get(canonical)).toBe(contentHash(content));
+ expect.soft(lastKnownHash.has(alias)).toBe(false);
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ events.length = 0;
+ unlinkSync(canonical);
+ await deliverDelete(canonical);
+ expect.soft(events).toContainEqual({ kind: 'delete', path: canonical, docName: 'member' });
+ expect(watcher.getFileIndex().has('member')).toBe(false);
+ expect(lastKnownHash.has(canonical)).toBe(false);
+ expect(existsSync(canonical)).toBe(false);
+ },
+);
+
+test('ordinary replacement of a Markdown alias admits the new regular document', async () => {
+ const canonical = writeDoc('canonical.mdx', '# Original target\n');
+ const alias = join(contentDir, 'linked.md');
+ symlinkSync(canonical, alias);
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getAliasMap().get('linked')).toBe('canonical');
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ unlinkSync(alias);
+ const content = '# New regular document\n';
+ writeFileSync(alias, content);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: alias }]);
+ expect(events).toContainEqual({ kind: 'update', path: alias, docName: 'linked', content });
+ expect(watcher.getAliasMap().has('linked')).toBe(false);
+ expect(watcher.getFileIndex().get('linked')?.canonicalPath).toBe(alias);
+ expect(watcher.getFileIndex().get('canonical')?.canonicalPath).toBe(canonical);
+ expect(lstatSync(alias).isFile()).toBe(true);
+ expect(readFileSync(alias, 'utf8')).toBe(content);
+ expect(readFileSync(canonical, 'utf8')).toBe('# Original target\n');
+ events.length = 0;
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect(watcher.getFileIndex().get('linked')?.canonicalPath).toBe(alias);
+ expect(watcher.getFileIndex().get('canonical')?.aliases).toEqual([]);
+});
+
+test.each([
+ { intake: 'create', delivery: 'ordinary' },
+ { intake: 'create', delivery: 'notice batch' },
+ { intake: 'retarget', delivery: 'ordinary' },
+ { intake: 'retarget', delivery: 'notice batch' },
+] as const)(
+ 'same-name alias $intake after startup preserves its target on $delivery removal',
+ async ({ intake, delivery }) => {
+ const content = '# Canonical stays\n';
+ const canonical = writeDoc('member.mdx', content);
+ const other = writeDoc('other.mdx', '# Other stays\n');
+ const alias = join(contentDir, 'member.md');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getAliasMap().has('member')).toBe(false);
+ if (intake === 'retarget') {
+ symlinkSync(other, alias);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: alias }]);
+ expect(watcher.getAliasMap().get('member')).toBe('other');
+ unlinkSync(alias);
+ }
+ symlinkSync(canonical, alias);
+ await nativeSubscriptionOn(contentDir).deliver([
+ { type: intake === 'create' ? 'create' : 'update', path: alias },
+ ]);
+ expect.soft(watcher.getAliasMap().get('member')).toBe('member');
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(lastKnownHash.get(alias)).toBe(contentHash(content));
+ events.length = 0;
+ unlinkSync(alias);
+ const batch: Event[] = [{ type: 'delete', path: alias }];
+ if (delivery === 'notice batch') {
+ await nativeSubscriptionOn(contentDir).deliver(batch, new Error(notices[0]));
+ } else {
+ await nativeSubscriptionOn(contentDir).deliver(batch);
+ }
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect.soft(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect.soft(lastKnownHash.get(canonical)).toBe(contentHash(content));
+ expect(lastKnownHash.has(alias)).toBe(false);
+ expect(watcher.getAliasMap().has('member')).toBe(false);
+ expect(watcher.getFileIndex().get('other')?.canonicalPath).toBe(other);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ expect(readFileSync(other, 'utf8')).toBe('# Other stays\n');
+ },
+);
+
+test.each(['ordinary', 'notice batch'] as const)(
+ 'a same-name alias added to a running server leaves its canonical page loaded after $0 removal',
+ async (delivery) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const content = '# Canonical page\n';
+ const canonical = writeDoc('member.mdx', content);
+ const alias = join(contentDir, 'member.md');
+ const server = await bootInventoryServer();
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ try {
+ const held = await server.serverInstance.hocuspocus.openDirectConnection('member');
+ connections.push(held);
+ const document = held.document;
+ const lifecycle = document.getMap('lifecycle');
+ expect(document.getText('source').toString()).toBe(content);
+ symlinkSync(canonical, alias);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: alias }]);
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(server.serverInstance.hocuspocus.documents.get('member')).toBe(document);
+ unlinkSync(alias);
+ const batch: Event[] = [{ type: 'delete', path: alias }];
+ await nativeSubscriptionOn(contentDir).deliver(
+ batch,
+ delivery === 'notice batch' ? new Error(notices[0]) : undefined,
+ );
+ expect.soft(lifecycle.get('status')).not.toBe('deleted-upstream');
+ expect.soft(server.serverInstance.hocuspocus.documents.get('member') === document).toBe(true);
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect(document.getText('source').toString()).toBe(content);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ const rows = await listedProjectedEntries(server.port);
+ expect
+ .soft(rows.filter((row) => row.kind === 'document' && row.docName === 'member'))
+ .toEqual([expect.objectContaining({ docExt: '.mdx', isSymlink: false })]);
+ const response = await fetch(`http://127.0.0.1:${server.port}/api/document?docName=member`);
+ expect.soft(response.status).toBe(200);
+ const body = (await response.json()) as { content?: string };
+ expect.soft(body.content).toBe(content);
+ } finally {
+ for (const connection of connections) await connection.disconnect();
+ await server.destroy();
+ }
+ },
+);
+
+test.each(['alias', 'directory'] as const)(
+ 'a notice retains the canonical page when a removed same-name $0 was never observed',
+ async (kind) => {
+ const content = '# Always present\n';
+ const canonical = writeDoc('member.mdx', content);
+ const transient = join(contentDir, 'member.md');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(watcher.getAliasMap().has('member')).toBe(false);
+ expect(watcher.getFolderIndex().has('member.md')).toBe(false);
+ const identity = statSync(canonical).ino;
+ if (kind === 'alias') {
+ symlinkSync(canonical, transient);
+ expect(realpathSync(transient)).toBe(canonical);
+ unlinkSync(transient);
+ } else {
+ mkdirSync(transient);
+ expect(lstatSync(transient).isDirectory()).toBe(true);
+ rmSync(transient, { recursive: true });
+ }
+ const untracked = writeDoc('untracked.md', '# Actual removed page\n');
+ unlinkSync(untracked);
+ const recovered = writeDoc('recovered.md', '# Omitted create\n');
+ await nativeSubscriptionOn(contentDir).deliver(
+ [
+ { type: 'delete', path: transient },
+ { type: 'delete', path: untracked },
+ ],
+ new Error(notices[0]),
+ );
+ expect
+ .soft(events.filter((event) => 'docName' in event && event.docName === 'member'))
+ .toEqual([]);
+ expect(events).toContainEqual({
+ kind: 'create',
+ path: recovered,
+ docName: 'recovered',
+ content: '# Omitted create\n',
+ });
+ expect(events).toContainEqual({ kind: 'delete', path: untracked, docName: 'untracked' });
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(watcher.getFileIndex().has('recovered')).toBe(true);
+ expect(getDocExtension('member')).toBe('.mdx');
+ expect(lastKnownHash.get(canonical)).toBe(contentHash(content));
+ expect(statSync(canonical).ino).toBe(identity);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ expect(existsSync(transient)).toBe(false);
+ events.length = 0;
+ unlinkSync(canonical);
+ await nativeSubscriptionOn(contentDir).deliver([], new Error(notices[0]));
+ expect(events).toContainEqual({ kind: 'delete', path: canonical, docName: 'member' });
+ expect(watcher.getFileIndex().has('member')).toBe(false);
+ },
+);
+
+test('a notice retains a live alias when a same-name directory was never observed', async () => {
+ const content = '# Aliased target\n';
+ const canonical = writeDoc('target.mdx', content);
+ const alias = join(contentDir, 'member.md');
+ symlinkSync(canonical, alias);
+ const transient = join(contentDir, 'member.mdx');
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ { forceBackend: 'parcel', platform: 'darwin' },
+ );
+ handles.push(watcher);
+ expect(watcher.getAliasMap().get('member')).toBe('target');
+ expect(watcher.getFolderIndex().has('member.mdx')).toBe(false);
+ mkdirSync(transient);
+ expect(lstatSync(transient).isDirectory()).toBe(true);
+ rmSync(transient, { recursive: true });
+ await nativeSubscriptionOn(contentDir).deliver(
+ [{ type: 'delete', path: transient }],
+ new Error(notices[0]),
+ );
+ expect.soft(events.filter((event) => event.kind === 'delete')).toEqual([]);
+ expect(watcher.getAliasMap().get('member')).toBe('target');
+ expect(watcher.getFileIndex().get('target')?.canonicalPath).toBe(canonical);
+ expect(watcher.getFileIndex().get('target')?.aliases).toContain('member');
+ expect(realpathSync(alias)).toBe(canonical);
+ expect(readFileSync(alias, 'utf8')).toBe(content);
+ events.length = 0;
+ unlinkSync(alias);
+ await nativeSubscriptionOn(contentDir).deliver(
+ [{ type: 'delete', path: alias }],
+ new Error(notices[0]),
+ );
+ expect(events).toContainEqual({ kind: 'delete', path: alias, docName: 'member' });
+ expect(watcher.getAliasMap().has('member')).toBe(false);
+ expect(watcher.getFileIndex().get('target')?.canonicalPath).toBe(canonical);
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+});
+
+test('a stale physical deletion cannot rename the current same-name page', async () => {
+ const oldContent = '# Former spelling\n';
+ const currentContent = '# Current spelling\n';
+ const former = writeDoc('member.md', oldContent);
+ const { watcher, events } = await watchContent();
+ const canonical = join(contentDir, 'member.mdx');
+ renameSync(former, canonical);
+ watcher.mutateFileIndex({
+ kind: 'rename',
+ oldPath: former,
+ newPath: canonical,
+ oldDocName: 'member',
+ newDocName: 'member',
+ content: oldContent,
+ });
+ writeFileSync(canonical, currentContent);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: canonical }]);
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(lastKnownHash.get(former)).toBe(contentHash(oldContent));
+ expect(lastKnownHash.get(canonical)).toBe(contentHash(currentContent));
+ const identity = statSync(canonical).ino;
+ const created = writeDoc('new-page.md', oldContent);
+ events.length = 0;
+ await nativeSubscriptionOn(contentDir).deliver([
+ { type: 'delete', path: former },
+ { type: 'create', path: created },
+ ]);
+ expect
+ .soft(events)
+ .toEqual([{ kind: 'create', path: created, docName: 'new-page', content: oldContent }]);
+ expect.soft(lastKnownHash.has(former)).toBe(false);
+ expect.soft(lastKnownHash.get(canonical)).toBe(contentHash(currentContent));
+ expect.soft(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect.soft(watcher.getFileIndex().get('new-page')?.canonicalPath).toBe(created);
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect(statSync(canonical).ino).toBe(identity);
+ expect(readFileSync(canonical, 'utf8')).toBe(currentContent);
+ expect(existsSync(former)).toBe(false);
+});
+
+test.each([
+ { intake: 'alias-first', delivery: 'ordinary', preparation: 'initial' },
+ { intake: 'canonical-first', delivery: 'ordinary', preparation: 'initial' },
+ { intake: 'live', delivery: 'ordinary', preparation: 'initial' },
+ { intake: 'alias-first', delivery: 'notice batch', preparation: 'initial' },
+ { intake: 'canonical-first', delivery: 'notice batch', preparation: 'initial' },
+ { intake: 'live', delivery: 'notice batch', preparation: 'initial' },
+ { intake: 'alias-first', delivery: 'ordinary', preparation: 'canonical update' },
+ { intake: 'live', delivery: 'notice batch', preparation: 'canonical update' },
+] as const)(
+ 'removing an alias to another page preserves its same-name canonical document after $intake intake, $preparation and $delivery',
+ async ({ intake, delivery, preparation }) => {
+ let memberContent = '# Separate canonical page\n';
+ const targetContent = '# Alias target page\n';
+ const canonical = writeDoc('member.mdx', memberContent);
+ const target = writeDoc('other.mdx', targetContent);
+ const alias = join(contentDir, 'member.md');
+ if (intake !== 'live') {
+ symlinkSync(target, alias);
+ scanSchedule.orderedPath = contentDir;
+ scanSchedule.orderedEntries =
+ intake === 'alias-first'
+ ? ['member.md', 'member.mdx', 'other.mdx']
+ : ['member.mdx', 'other.mdx', 'member.md'];
+ }
+ const { watcher, events } = await watchContent();
+ if (intake === 'live') {
+ symlinkSync(target, alias);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: alias }]);
+ }
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: alias }]);
+ expect(watcher.getAliasMap().get('member')).toBe('other');
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(watcher.getFileIndex().get('other')?.canonicalPath).toBe(target);
+ expect(lastKnownHash.get(alias)).toBe(contentHash(targetContent));
+ expect(realpathSync(alias)).toBe(target);
+ if (preparation === 'canonical update') {
+ memberContent = '# Updated separate canonical page\n';
+ writeFileSync(canonical, memberContent);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: canonical }]);
+ expect.soft(watcher.getAliasMap().get('member')).toBe('other');
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(lastKnownHash.get(canonical)).toBe(contentHash(memberContent));
+ expect(realpathSync(alias)).toBe(target);
+ }
+ const memberInode = statSync(canonical).ino;
+ const targetInode = statSync(target).ino;
+ events.length = 0;
+ unlinkSync(alias);
+ await nativeSubscriptionOn(contentDir).deliver(
+ [
+ { type: 'delete', path: alias },
+ { type: 'delete', path: alias },
+ ],
+ delivery === 'notice batch' ? new Error(notices[0]) : undefined,
+ );
+ expect
+ .soft(events.filter((event) => event.kind === 'delete' || event.kind === 'rename'))
+ .toEqual([]);
+ expect.soft(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect.soft(watcher.getFileIndex().get('other')?.canonicalPath).toBe(target);
+ expect.soft(watcher.getFileIndex().get('other')?.aliases).not.toContain('member');
+ expect.soft(watcher.getAliasMap().has('member')).toBe(false);
+ expect.soft(lastKnownHash.has(alias)).toBe(false);
+ expect.soft(lastKnownHash.get(canonical)).toBe(contentHash(memberContent));
+ expect.soft(lastKnownHash.get(target)).toBe(contentHash(targetContent));
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect(statSync(canonical).ino).toBe(memberInode);
+ expect(statSync(target).ino).toBe(targetInode);
+ expect(readFileSync(canonical, 'utf8')).toBe(memberContent);
+ expect(readFileSync(target, 'utf8')).toBe(targetContent);
+ events.length = 0;
+ unlinkSync(canonical);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: canonical }]);
+ expect(events).toContainEqual({ kind: 'delete', path: canonical, docName: 'member' });
+ expect(watcher.getFileIndex().has('member')).toBe(false);
+ expect(watcher.getFileIndex().get('other')?.canonicalPath).toBe(target);
+ events.length = 0;
+ unlinkSync(target);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: target }]);
+ expect(events).toContainEqual({ kind: 'delete', path: target, docName: 'other' });
+ expect(watcher.getFileIndex().has('other')).toBe(false);
+ },
+);
+
+test.each(['ordinary', 'notice batch'] as const)(
+ 'removing an alias to another loaded page preserves both real documents through $0 delivery',
+ async (delivery) => {
+ vi.useRealTimers();
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const canonical = writeDoc('member.mdx', '# Separate canonical page\n');
+ const target = writeDoc('other.mdx', '# Alias target page\n');
+ const alias = join(contentDir, 'member.md');
+ const server = await bootInventoryServer();
+ const connections: Array<{ disconnect(): Promise<void> }> = [];
+ try {
+ const member = await server.serverInstance.hocuspocus.openDirectConnection('member');
+ connections.push(member);
+ const other = await server.serverInstance.hocuspocus.openDirectConnection('other');
+ connections.push(other);
+ symlinkSync(target, alias);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'create', path: alias }]);
+ expect(realpathSync(alias)).toBe(target);
+ unlinkSync(alias);
+ await nativeSubscriptionOn(contentDir).deliver(
+ [{ type: 'delete', path: alias }],
+ delivery === 'notice batch' ? new Error(notices[0]) : undefined,
+ );
+ for (const [name, held, path] of [
+ ['member', member, canonical],
+ ['other', other, target],
+ ] as const) {
+ expect.soft(held.document.getMap('lifecycle').get('status')).not.toBe('deleted-upstream');
+ expect
+ .soft(server.serverInstance.hocuspocus.documents.get(name) === held.document)
+ .toBe(true);
+ expect.soft(held.document.getText('source').toString()).toBe(readFileSync(path, 'utf8'));
+ }
+ const rows = await listedProjectedEntries(server.port);
+ for (const [name, path] of [
+ ['member', canonical],
+ ['other', target],
+ ] as const) {
+ expect
+ .soft(rows.filter((row) => row.kind === 'document' && row.docName === name))
+ .toHaveLength(1);
+ const response = await fetch(
+ `http://127.0.0.1:${server.port}/api/document?docName=${name}`,
+ );
+ expect.soft(response.status).toBe(200);
+ const body = (await response.json()) as { content?: string };
+ expect.soft(body.content).toBe(readFileSync(path, 'utf8'));
+ }
+ } finally {
+ for (const connection of connections) await connection.disconnect();
+ await server.destroy();
+ }
+ },
+);
+
+test('alias retirement preserves its namesake after the recorded target was already removed', async () => {
+ const content = '# Remaining namesake\n';
+ const canonical = writeDoc('member.mdx', content);
+ const target = writeDoc('other.mdx', '# Removed target\n');
+ const alias = join(contentDir, 'member.md');
+ symlinkSync(target, alias);
+ const { watcher, events } = await watchContent();
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'update', path: alias }]);
+ unlinkSync(target);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: target }]);
+ expect(events).toContainEqual({ kind: 'delete', path: target, docName: 'other' });
+ expect(watcher.getFileIndex().has('other')).toBe(false);
+ expect(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect(watcher.getAliasMap().get('member')).toBe('other');
+ expect(lstatSync(alias).isSymbolicLink()).toBe(true);
+ expect(lastKnownHash.has(alias)).toBe(true);
+ events.length = 0;
+ unlinkSync(alias);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: alias }]);
+ expect.soft(events).toEqual([]);
+ expect.soft(watcher.getFileIndex().get('member')?.canonicalPath).toBe(canonical);
+ expect.soft(watcher.getFileIndex().has('other')).toBe(false);
+ expect.soft(watcher.getAliasMap().has('member')).toBe(false);
+ expect.soft(lastKnownHash.has(alias)).toBe(false);
+ expect.soft(lastKnownHash.has(target)).toBe(false);
+ expect.soft(lastKnownHash.get(canonical)).toBe(contentHash(content));
+ expect.soft(getDocExtension('member')).toBe('.mdx');
+ expect(readFileSync(canonical, 'utf8')).toBe(content);
+ events.length = 0;
+ unlinkSync(canonical);
+ await nativeSubscriptionOn(contentDir).deliver([{ type: 'delete', path: canonical }]);
+ expect(events).toContainEqual({ kind: 'delete', path: canonical, docName: 'member' });
+ expect(watcher.getFileIndex().has('member')).toBe(false);
+});
+
+function generalEntries(watcher: WatcherHandle) {
+ return new Map([...watcher.getAllFilesIndex()].filter(([, entry]) => entry.kind === 'file'));
+}
+
+async function watchSeparateGeneralGroups() {
+ writeDoc('pair-1.csv', 'pair\n');
+ linkSync(join(contentDir, 'pair-1.csv'), join(contentDir, 'pair-2.csv'));
+ writeDoc('shared.csv', 'shared\n');
+ symlinkSync(join(contentDir, 'shared.csv'), join(contentDir, 'shared-link.csv'));
+ writeDoc('solo.csv', 'solo\n');
+ writeDoc('report.csv', 'report\n');
+ const watched = await watchContent();
+ const before = generalEntries(watched.watcher);
+ expect(
+ [...before]
+ .map(([name, entry]) => [name, entry.fileMembers])
+ .toSorted(([a], [b]) => String(a).localeCompare(String(b))),
+ ).toEqual([
+ ['pair-1.csv', { regularPaths: ['pair-1.csv', 'pair-2.csv'], symlinks: [] }],
+ ['report.csv', { regularPaths: ['report.csv'], symlinks: [] }],
+ [
+ 'shared.csv',
+ {
+ regularPaths: ['shared.csv'],
+ symlinks: [{ path: 'shared-link.csv', targetPath: 'shared.csv' }],
+ },
+ ],
+ ['solo.csv', { regularPaths: ['solo.csv'], symlinks: [] }],
+ ]);
+ return { ...watched, before };
+}
+
+const unaffectedGeneralGroups = ['pair-1.csv', 'shared.csv', 'solo.csv'];
+
+test('a general-file update leaves the index entries of other inode groups unchanged', async () => {
+ const { watcher, events, before } = await watchSeparateGeneralGroups();
+ const report = join(contentDir, 'report.csv');
+ writeFileSync(report, 'region,total\nnorth,42\nsouth,17\n');
+ const size = statSync(report).size;
+ expect(size).not.toBe(before.get('report.csv')?.size);
+
+ await deliver(contentDir, [{ type: 'update', path: report }]);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-update', relativePath: 'report.csv', size }),
+ );
+ const after = generalEntries(watcher);
+ expect(after.get('report.csv')?.size).toBe(size);
+ for (const name of unaffectedGeneralGroups) {
+ expect(after.get(name), name).toBe(before.get(name));
+ }
+});
+
+test('a general-file create leaves the index entries of other inode groups unchanged', async () => {
+ const { watcher, events, before } = await watchSeparateGeneralGroups();
+ const added = writeDoc('added.csv', 'added,rows\n1,2\n');
+ const size = statSync(added).size;
+
+ await deliver(contentDir, [{ type: 'create', path: added }]);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-create', relativePath: 'added.csv', size }),
+ );
+ const after = generalEntries(watcher);
+ expect(after.get('added.csv')).toEqual(
+ expect.objectContaining({
+ size,
+ fileMembers: { regularPaths: ['added.csv'], symlinks: [] },
+ }),
+ );
+ for (const name of [...unaffectedGeneralGroups, 'report.csv']) {
+ expect(after.get(name), name).toBe(before.get(name));
+ }
+});
+
+test('a general-file delete leaves the index entries of other inode groups unchanged', async () => {
+ const { watcher, events, before } = await watchSeparateGeneralGroups();
+ const report = join(contentDir, 'report.csv');
+ unlinkSync(report);
+
+ await deliver(contentDir, [{ type: 'delete', path: report }]);
+
+ expect(events).toContainEqual(
+ expect.objectContaining({ kind: 'file-delete', relativePath: 'report.csv' }),
+ );
+ const after = generalEntries(watcher);
+ expect(after.has('report.csv')).toBe(false);
+ for (const name of unaffectedGeneralGroups) {
+ expect(after.get(name), name).toBe(before.get(name));
+ }
+});
diff --git a/packages/server/src/parcel-recovery.ts b/packages/server/src/parcel-recovery.ts
new file mode 100644
index 000000000..d28bfbed8
--- /dev/null
+++ b/packages/server/src/parcel-recovery.ts
@@ -0,0 +1,18 @@
+import type { Event } from '@parcel/watcher';
+
+const RESCAN_NOTICES = new Set([
+ 'Events were dropped by the FSEvents client. File system must be re-scanned.',
+ 'Too many events. File system must be re-scanned.',
+ 'Events were dropped by the kernel. File system must be re-scanned.',
+]);
+
+export type ParcelNotification =
+ | { kind: 'batch'; events: Event[] }
+ | { kind: 'rescan'; events: Event[]; error: Error }
+ | { kind: 'error'; error: Error };
+
+export function classifyParcelNotification(err: Error | null, events: Event[]): ParcelNotification {
+ if (err === null) return { kind: 'batch', events };
+ if (RESCAN_NOTICES.has(err.message)) return { kind: 'rescan', events, error: err };
+ return { kind: 'error', error: err };
+}
diff --git a/packages/server/src/parcel-watcher-double.test-helper.ts b/packages/server/src/parcel-watcher-double.test-helper.ts
index 346d95312..0f89cc683 100644
--- a/packages/server/src/parcel-watcher-double.test-helper.ts
+++ b/packages/server/src/parcel-watcher-double.test-helper.ts
@@ -4,8 +4,8 @@ import type { AsyncSubscription, Event, Options, SubscribeCallback } from '@parc
export interface NativeSubscriptionDouble {
readonly dir: string;
nativeReleases(): number;
- deliver(events: Event[]): Promise<void>;
- deliverWhileReleasing(events: Event[]): void;
+ deliver(events: Event[], error?: Error | null): Promise<void>;
+ deliverWhileReleasing(events: Event[], error?: Error | null): void;
}
interface Registration extends NativeSubscriptionDouble {
@@ -17,9 +17,9 @@ const registrations: Registration[] = [];
function register(dir: string, callback: SubscribeCallback): Registration {
let releases = 0;
- const queuedForRelease: Event[][] = [];
- const deliver = async (events: Event[]): Promise<void> => {
- await callback(null, events);
+ const queuedForRelease: Array<{ events: Event[]; error: Error | null }> = [];
+ const deliver = async (events: Event[], error: Error | null = null): Promise<void> => {
+ await callback(error, events);
await new Promise<void>((settle) => setImmediate(settle));
};
return {
@@ -27,12 +27,12 @@ function register(dir: string, callback: SubscribeCallback): Registration {
callback,
nativeReleases: () => releases,
deliver,
- deliverWhileReleasing: (events) => {
- queuedForRelease.push(events);
+ deliverWhileReleasing: (events, error = null) => {
+ queuedForRelease.push({ events, error });
},
release: async () => {
releases += 1;
- for (const events of queuedForRelease.splice(0)) await deliver(events);
+ for (const { events, error } of queuedForRelease.splice(0)) await deliver(events, error);
},
};
}
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 3e89680d6..6cb56a406 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -178,6 +178,7 @@ import type { GeneratedIndexSettingsStatus } from './http/workspace-tools-routes
import {
scanGlobalInPlaceSkills,
scanInPlaceSkillDirs,
+ scanInPlaceSkills,
skillRootPathsFor,
} from './in-place-skills.ts';
import {
@@ -1704,8 +1705,8 @@ export function createServer(options: ServerOptions): ServerInstance {
contentDir,
singleDocRelPath,
attachmentFolderPath: initialAttachmentFolderPath,
- inPlaceSkillDirs: scanInPlaceSkillDirs(contentDir),
- rescanInPlaceSkillDirs: () => scanInPlaceSkillDirs(contentDir),
+ inPlaceSkillDirs: new Set(scanInPlaceSkills(contentDir).map((skill) => skill.dir)),
+ rescanInPlaceSkillDirs: (priorAdmission) => scanInPlaceSkillDirs(contentDir, priorAdmission),
skillRootPaths: skillRootPathsFor(contentDir),
onAfterRebuild: () => {
void derivedDocumentIndex.refreshContentScope().catch((err) => {
@@ -3952,7 +3953,9 @@ export function createServer(options: ServerOptions): ServerInstance {
}
const seedWalkStartMono = performance.now();
const HOST_SKILLS_EVENT_RE = /^\.(?!ok\/)[A-Za-z0-9_-]+\/skills\//;
- let lastInPlaceDirs = contentFilter ? scanInPlaceSkillDirs(contentDir) : new Set<string>();
+ let lastInPlaceDirs: ReadonlySet<string> = contentFilter
+ ? new Set(scanInPlaceSkills(contentDir).map((skill) => skill.dir))
+ : new Set<string>();
const onRawBatch = (absPaths: readonly string[]): void => {
if (
!absPaths.some((p) =>
@@ -3973,7 +3976,7 @@ export function createServer(options: ServerOptions): ServerInstance {
}
})
.catch((err) => log.warn({ err }, '[in-place-skills] copy re-sync failed'));
- const next = scanInPlaceSkillDirs(contentDir);
+ const next = scanInPlaceSkillDirs(contentDir, lastInPlaceDirs);
const changed =
next.size !== lastInPlaceDirs.size ||
[...next].some((d) => !lastInPlaceDirs.has(d));
@@ -4002,7 +4005,10 @@ export function createServer(options: ServerOptions): ServerInstance {
}, IN_PLACE_RESCAN_DEBOUNCE_MS);
};
watcher = await withSpan('ok.boot.seed-walk', undefined, async () =>
- startWatcher(contentDir, onDiskEvent, contentFilter, { onRawBatch }),
+ startWatcher(contentDir, onDiskEvent, contentFilter, {
+ onRawBatch,
+ onRecoveryComplete: () => derivedDocumentIndex.recordInventoryReconciled(),
+ }),
);
void resyncRecordedSkillCopies(projectDir, contentDir)
.then((n) => {
diff --git a/packages/server/src/services/search.ts b/packages/server/src/services/search.ts
index d5da9a93e..abf06e65c 100644
--- a/packages/server/src/services/search.ts
+++ b/packages/server/src/services/search.ts
@@ -27,7 +27,11 @@ import {
import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import { recordSemanticQuery } from '../embeddings/embeddings-telemetry.ts';
import { SEMANTIC_MIN_QUERY_LENGTH, type SemanticSearchService } from '../embeddings/index.ts';
-import type { FileIndexEntry } from '../file-watcher.ts';
+import {
+ type AllFileEntries,
+ type FileIndexEntry,
+ fileIndexEntryMembers,
+} from '../file-watcher.ts';
import { scanInPlaceSkills } from '../in-place-skills.ts';
import { getLogger } from '../logger.ts';
import { extractPageTitle } from '../page-identity.ts';
@@ -125,8 +129,23 @@ function toSearchResultEntry(
};
}
-function entrySearchKey(entry: FileIndexEntry): string {
- return `${entry.modified}\0${entry.size}\0${entry.canonicalPath}\0${entry.inode}\0${entry.aliases.join('\0')}`;
+function entrySearchKey(contentDir: string, name: string, entry: FileIndexEntry): string {
+ const { resolved, members } = fileIndexEntryMembers(contentDir, name, entry);
+ const symlinks = members
+ .filter((member) => member.role === 'symlink')
+ .map((member) => member.path)
+ .join('\0');
+ const memberPaths = resolved
+ ? members
+ .map((member) => member.path)
+ .toSorted()
+ .join('\0')
+ : '';
+ return `${entry.modified}\0${entry.size}\0${entry.canonicalPath}\0${entry.inode}\0${symlinks}\0${memberPaths}`;
+}
+
+function entrySearchAliases(contentDir: string, name: string, entry: FileIndexEntry): string[] {
+ return fileIndexEntryMembers(contentDir, name, entry).members.map((member) => member.path);
}
interface SemanticResolution {
@@ -140,7 +159,7 @@ interface SemanticResolution {
export interface SearchServiceDeps {
contentDir: string;
projectDir?: string;
- getAllFilesIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ getAllFilesIndex: () => AllFileEntries;
getFileIndexGeneration?: () => number;
getSearchMaxEntries: () => number;
semanticSearch?: SemanticSearchService;
@@ -330,13 +349,13 @@ export function createSearchService(deps: SearchServiceDeps): SearchService {
kind: 'file',
path: docName,
modifiedTs: Date.parse(entry.modified),
- aliases: entry.aliases,
+ aliases: entrySearchAliases(contentDir, docName, entry),
}),
);
continue;
}
seenPages.add(docName);
- const entryKey = entrySearchKey(entry);
+ const entryKey = entrySearchKey(contentDir, docName, entry);
const cached = pageDocCache.get(docName);
if (cached && cached.key === entryKey) {
pages.push(cached.doc);
@@ -364,7 +383,7 @@ export function createSearchService(deps: SearchServiceDeps): SearchService {
title,
content,
modifiedTs: Date.parse(entry.modified),
- aliases: entry.aliases,
+ aliases: entrySearchAliases(contentDir, docName, entry),
});
if (!readFailed) pageDocCache.set(docName, { key: entryKey, doc });
pages.push(doc);
@@ -416,7 +435,7 @@ export function createSearchService(deps: SearchServiceDeps): SearchService {
return `${[...getAllFilesIndex()]
.filter(([docName]) => !isSystemDoc(docName) && !isConfigDoc(docName))
.sort(([a], [b]) => a.localeCompare(b))
- .map(([docName, entry]) => `${docName}\0${entrySearchKey(entry)}`)
+ .map(([docName, entry]) => `${docName}\0${entrySearchKey(contentDir, docName, entry)}`)
.join('')}|skills${skillStatFingerprint()}`;
}
diff --git a/packages/server/src/skill-placements-store.ts b/packages/server/src/skill-placements-store.ts
index 93cde5370..b41156c86 100644
--- a/packages/server/src/skill-placements-store.ts
+++ b/packages/server/src/skill-placements-store.ts
@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
import { LOCAL_DIR, OK_DIR, SKILL_PLACEMENTS_FILENAME } from '@inkeep/open-knowledge-core';
import { atomicWriteFile } from '@inkeep/open-knowledge-core/server';
@@ -30,7 +30,37 @@ function skillPlacementsPath(base: string): string {
return join(base, ...PLACEMENTS_REL);
}
-export function resolveSkillPlacementPath(base: string, relPath: string): string | null {
+function findExistingAncestor(candidate: string): string | null {
+ let ancestor = candidate;
+ while (!existsSync(ancestor)) {
+ const parent = dirname(ancestor);
+ if (parent === ancestor) return null;
+ ancestor = parent;
+ }
+ return ancestor;
+}
+
+function findObservedAncestor(candidate: string): string | null {
+ let ancestor = candidate;
+ while (true) {
+ try {
+ statSync(ancestor);
+ return ancestor;
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException).code;
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+ const parent = dirname(ancestor);
+ if (parent === ancestor) return null;
+ ancestor = parent;
+ }
+ }
+}
+
+function resolveSkillPlacementPathWithAncestor(
+ base: string,
+ relPath: string,
+ findAncestor: (candidate: string) => string | null,
+): string | null {
if (
relPath.length === 0 ||
relPath.includes('\0') ||
@@ -43,37 +73,42 @@ export function resolveSkillPlacementPath(base: string, relPath: string): string
const candidate = resolve(baseAbs, relPath);
if (candidate === baseAbs || !candidate.startsWith(`${baseAbs}${sep}`)) return null;
- let baseReal: string;
- try {
- baseReal = realpathSync(baseAbs);
- } catch {
- return null;
- }
- let ancestor = candidate;
- while (!existsSync(ancestor)) {
- const parent = dirname(ancestor);
- if (parent === ancestor) return null;
- ancestor = parent;
- }
+ const baseReal = realpathSync(baseAbs);
+ const ancestor = findAncestor(candidate);
+ if (ancestor === null) return null;
+ const ancestorReal = realpathSync(ancestor);
+ if (ancestorReal !== baseReal && !ancestorReal.startsWith(`${baseReal}${sep}`)) return null;
+ return candidate;
+}
+
+function resolveSkillPlacementPathChecked(base: string, relPath: string): string | null {
+ return resolveSkillPlacementPathWithAncestor(base, relPath, findObservedAncestor);
+}
+
+export function resolveSkillPlacementPath(base: string, relPath: string): string | null {
try {
- const ancestorReal = realpathSync(ancestor);
- if (ancestorReal !== baseReal && !ancestorReal.startsWith(`${baseReal}${sep}`)) return null;
+ return resolveSkillPlacementPathWithAncestor(base, relPath, findExistingAncestor);
} catch {
return null;
}
- return candidate;
}
function emptyStore(): SkillPlacementsStore {
return { schema: SCHEMA_VERSION, skills: {} };
}
-function isPlacement(base: string, value: unknown): value is SkillPlacement {
+type PlacementResolver = (base: string, relPath: string) => string | null;
+
+function isPlacement(
+ base: string,
+ value: unknown,
+ resolvePath: PlacementResolver,
+): value is SkillPlacement {
if (!value || typeof value !== 'object') return false;
const placement = value as Partial<SkillPlacement>;
return (
typeof placement.path === 'string' &&
- resolveSkillPlacementPath(base, placement.path) !== null &&
+ resolvePath(base, placement.path) !== null &&
(placement.mode === 'copy' || placement.mode === 'link') &&
(placement.hash === undefined || typeof placement.hash === 'string')
);
@@ -95,15 +130,15 @@ function parseSources(value: unknown): Record<string, string> | undefined {
return entries.length > 0 ? Object.fromEntries(entries) : undefined;
}
-function parseFolders(base: string, value: unknown): Record<string, FolderExpectation> | undefined {
+function parseFolders(
+ base: string,
+ value: unknown,
+ resolvePath: PlacementResolver,
+): Record<string, FolderExpectation> | undefined {
if (!value || typeof value !== 'object') return undefined;
const entries: Array<[string, FolderExpectation]> = [];
for (const [root, expectation] of Object.entries(value)) {
- if (
- resolveSkillPlacementPath(base, root) === null ||
- !expectation ||
- typeof expectation !== 'object'
- ) {
+ if (resolvePath(base, root) === null || !expectation || typeof expectation !== 'object') {
continue;
}
const candidate = expectation as Partial<FolderExpectation> & { target?: unknown };
@@ -112,7 +147,7 @@ function parseFolders(base: string, value: unknown): Record<string, FolderExpect
} else if (
candidate.expect === 'link' &&
typeof candidate.target === 'string' &&
- resolveSkillPlacementPath(base, candidate.target) !== null
+ resolvePath(base, candidate.target) !== null
) {
entries.push([root, { expect: 'link', target: candidate.target }]);
}
@@ -120,24 +155,27 @@ function parseFolders(base: string, value: unknown): Record<string, FolderExpect
return entries.length > 0 ? Object.fromEntries(entries) : undefined;
}
-function normalizePlacements(base: string, parsed: Record<string, unknown>): SkillPlacementsStore {
+function normalizePlacements(
+ base: string,
+ parsed: Record<string, unknown>,
+ resolvePath: PlacementResolver = resolveSkillPlacementPath,
+): SkillPlacementsStore {
const skills: Record<string, SkillPlacement[]> = {};
if (parsed.skills && typeof parsed.skills === 'object') {
for (const [name, list] of Object.entries(parsed.skills)) {
if (!Array.isArray(list)) continue;
- const valid = list.filter((placement) => isPlacement(base, placement));
+ const valid = list.filter((placement) => isPlacement(base, placement, resolvePath));
if (valid.length > 0) skills[name] = valid;
}
}
const roots = Array.isArray(parsed.roots)
? parsed.roots.filter(
- (root): root is string =>
- typeof root === 'string' && resolveSkillPlacementPath(base, root) !== null,
+ (root): root is string => typeof root === 'string' && resolvePath(base, root) !== null,
)
: [];
const preferences = parsePreferences(parsed.preferences);
const sources = parseSources(parsed.sources);
- const folders = parseFolders(base, parsed.folders);
+ const folders = parseFolders(base, parsed.folders, resolvePath);
return {
schema: SCHEMA_VERSION,
skills,
@@ -164,6 +202,37 @@ export function readSkillPlacementsStore(base: string): SkillPlacementsStore {
}
}
+type PlacementsScanRead =
+ | { kind: 'read'; store: SkillPlacementsStore }
+ | { kind: 'unparsable'; error: unknown };
+
+function readSkillPlacementsForScan(
+ base: string,
+ resolvePath: PlacementResolver,
+): PlacementsScanRead {
+ const path = skillPlacementsPath(base);
+ try {
+ statSync(path);
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException).code;
+ if (code === 'ENOENT' || code === 'ENOTDIR') return { kind: 'read', store: emptyStore() };
+ throw err;
+ }
+ const raw = readFileSync(path, 'utf-8');
+ let parsed: Record<string, unknown> | null;
+ try {
+ parsed = JSON.parse(raw) as Record<string, unknown> | null;
+ } catch (error) {
+ getLogger('skill-placements').warn(
+ { err: error, path },
+ 'skill-placements.json is not valid JSON; skill scans read no recorded roots or sources from it, and in-place skill refreshes keep the prior admission of the skills it decides',
+ );
+ return { kind: 'unparsable', error };
+ }
+ if (!parsed || typeof parsed !== 'object') return { kind: 'read', store: emptyStore() };
+ return { kind: 'read', store: normalizePlacements(base, parsed, resolvePath) };
+}
+
type PlacementsRead =
| { ok: true; store: SkillPlacementsStore }
| { ok: false; reason: string; cause?: unknown };
@@ -235,18 +304,61 @@ async function writeSkillPlacementsStore(base: string, store: SkillPlacementsSto
});
}
-export function readKnownSkillPlacementRoots(base: string): string[] {
- const store = readSkillPlacementsStore(base);
+function knownSkillPlacementRoots(
+ base: string,
+ store: SkillPlacementsStore,
+ resolvePath: PlacementResolver,
+): string[] {
const roots = new Set(store.roots ?? []);
for (const list of Object.values(store.skills)) {
for (const placement of list) {
const root = placement.path.split('/').slice(0, -1).join('/');
- if (root !== '' && resolveSkillPlacementPath(base, root) !== null) roots.add(root);
+ if (root !== '' && resolvePath(base, root) !== null) roots.add(root);
}
}
return [...roots].sort();
}
+export function readKnownSkillPlacementRoots(base: string): string[] {
+ return knownSkillPlacementRoots(base, readSkillPlacementsStore(base), resolveSkillPlacementPath);
+}
+
+type SkillPlacementScanInputs =
+ | { kind: 'complete'; roots: string[]; sources: Record<string, string> }
+ | { kind: 'unparsable'; roots: string[]; sources: Record<string, string>; error: unknown }
+ | { kind: 'incomplete'; roots: string[]; sources: Record<string, string>; error: unknown };
+
+export function observeSkillPlacementInputsForScan(base: string): SkillPlacementScanInputs {
+ const errors: unknown[] = [];
+ const resolvePath: PlacementResolver = (pathBase, relPath) => {
+ try {
+ return resolveSkillPlacementPathChecked(pathBase, relPath);
+ } catch (error) {
+ errors.push(error);
+ return null;
+ }
+ };
+ let read: PlacementsScanRead;
+ try {
+ read = readSkillPlacementsForScan(base, resolvePath);
+ } catch (error) {
+ getLogger('skill-placements').warn(
+ { err: error, path: skillPlacementsPath(base) },
+ 'skill-placements.json could not be read; skill scans read no recorded roots or sources from it, and in-place skill refreshes keep their prior admission',
+ );
+ return { kind: 'incomplete', roots: [], sources: {}, error };
+ }
+ if (read.kind === 'unparsable') {
+ return { kind: 'unparsable', roots: [], sources: {}, error: read.error };
+ }
+ const { store } = read;
+ const roots = knownSkillPlacementRoots(base, store, resolvePath);
+ const sources = store.sources ?? {};
+ return errors.length === 0
+ ? { kind: 'complete', roots, sources }
+ : { kind: 'incomplete', roots, sources, error: errors[0] };
+}
+
export function readSkillSourceHostPreferences(base: string): Record<string, string> {
return readSkillPlacementsStore(base).sources ?? {};
}