@filen/sync 0.2.1 → 0.3.1

package/tests/bench/cycle.bench.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest"
+import { bench } from "./harness/measure"
+import { makeScaleWorld, sceneToVfsSpec, forceLocalRescan } from "./harness/scale-world"
+import { genWideScene, resetIdentity } from "./harness/trees"
+import { SYNC_INTERVAL } from "../../src/constants"
+import { LOCAL_ROOT, type World } from "../harness/world"
+
+/**
+ * End-to-end cycle benchmark — ties the whole pipeline together (scan + deltas + tasks + state.save)
+ * through a real in-memory world. The headline real-world cost is the INCREMENTAL cycle: on a large
+ * synced tree, changing ONE file still forces a full-tree rescan + full delta pass + full state.save,
+ * all O(N). This is what a desktop user pays on every small edit inside a big folder.
+ *
+ * Real timers; the debounce is bypassed by ageing lastDirectoryChangeTimestamp, and the uncontended
+ * in-memory lock acquires instantly, so a cycle never awaits a scheduled timer.
+ */
+
+function ageDebounce(world: World): void {
+	world.sync.localFileSystem.lastDirectoryChangeTimestamp = Date.now() - SYNC_INTERVAL - 1_000
+}
+
+async function runCycle(world: World): Promise<void> {
+	ageDebounce(world)
+
+	await world.sync.runCycle()
+}
+
+async function syncToConvergence(world: World): Promise<void> {
+	// A few cycles settle an initial sync (uploads, then a no-change confirmation).
+	for (let i = 0; i < 3; i++) {
+		await runCycle(world)
+	}
+}
+
+describe("full runCycle", () => {
+	it("initial sync (upload everything)", async () => {
+		for (const nodes of [2_000, 10_000]) {
+			resetIdentity()
+
+			const scene = genWideScene(Math.max(1, Math.round(nodes / 101)), 100)
+
+			await bench({
+				group: "runCycle / initial sync (twoWay)",
+				name: `${scene.length} nodes`,
+				n: scene.length,
+				iterations: 3,
+				// Fresh world each iteration: initial sync mutates cloud + state irreversibly.
+				setup: () => makeScaleWorld({ mode: "twoWay", initialLocal: sceneToVfsSpec(scene) }),
+				run: async world => {
+					await runCycle(world)
+
+					return world.sync.remoteFileSystem.getDirectoryTreeCache.size
+				}
+			})
+		}
+	})
+
+	it("no-change cycle (steady state — engine fixed overhead, network excluded)", async () => {
+		resetIdentity()
+
+		const scene = genWideScene(50, 100)
+		const world = await makeScaleWorld({ mode: "twoWay", initialLocal: sceneToVfsSpec(scene) })
+
+		await syncToConvergence(world)
+
+		await bench({
+			group: "runCycle / no-change steady state",
+			name: `${scene.length} nodes synced`,
+			n: scene.length,
+			iterations: 10,
+			setup: () => world,
+			run: w => w.sync.runCycle()
+		})
+	})
+
+	it("incremental: ONE file changed in a large synced tree (the real per-edit cost)", async () => {
+		// Baseline capped (initial sync uses the O(N²) transfers semaphore); bumped after the fix.
+		for (const nodes of [10_000, 20_000]) {
+			resetIdentity()
+
+			const scene = genWideScene(Math.max(1, Math.round(nodes / 101)), 100)
+			const world = await makeScaleWorld({ mode: "twoWay", initialLocal: sceneToVfsSpec(scene) })
+
+			await syncToConvergence(world)
+
+			const targetPath = `${LOCAL_ROOT}/dir-0/file-0.txt`
+			let counter = 0
+
+			await bench({
+				group: "runCycle / incremental 1-file change (twoWay)",
+				name: `1 of ${scene.length} nodes`,
+				n: scene.length,
+				iterations: 5,
+				setup: async () => {
+					// A growing payload guarantees a size change → detected as a real modify each iteration.
+					counter++
+
+					await world.vfs.fs.writeFile(targetPath, "y".repeat(64 + counter), { encoding: "utf-8" })
+
+					forceLocalRescan(world)
+
+					return world
+				},
+				run: w => runCycle(w)
+			})
+
+			// Sanity: still converged (the one change propagated, nothing else churned).
+			expect(world.sync.remoteFileSystem.getDirectoryTreeCache.size).toBe(scene.length)
+		}
+	})
+})

package/tests/bench/deltas.bench.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest"
+import { bench } from "./harness/measure"
+import { makeDeltas } from "./harness/fake-sync"
+import {
+	genWideScene,
+	buildLocalTree,
+	buildRemoteTree,
+	addFiles,
+	deleteFiles,
+	modifyFiles,
+	renameTopDir,
+	resetIdentity,
+	type Scene
+} from "./harness/trees"
+import { type SyncMode } from "../../src/types"
+import { type LocalTree } from "../../src/lib/filesystems/local"
+import { type RemoteTree } from "../../src/lib/filesystems/remote"
+
+/**
+ * Delta-engine benchmarks — the CPU hot path. `deltas.process` runs every cycle that has changes and is
+ * O(N) over the tree with ~20 passes. We measure it as pure in-memory CPU (synthetic trees, fake Sync),
+ * across the change scenarios the real suite exercises (add / delete / modify / rename / mixed / no-op)
+ * and across all 5 sync modes. Trees are prebuilt once per scenario (process() never mutates its inputs)
+ * so only the algorithm is timed.
+ */
+
+const FILES_PER_DIR = 100
+
+function sceneOf(nodes: number): Scene {
+	resetIdentity()
+
+	return genWideScene(Math.max(1, Math.round(nodes / (FILES_PER_DIR + 1))), FILES_PER_DIR)
+}
+
+type Trees = {
+	prevLocal: LocalTree
+	prevRemote: RemoteTree
+	curLocal: LocalTree
+	curRemote: RemoteTree
+}
+
+async function runProcess(mode: SyncMode, t: Trees): Promise<number> {
+	const deltas = makeDeltas(mode)
+	const result = await deltas.process({
+		currentLocalTree: t.curLocal,
+		currentRemoteTree: t.curRemote,
+		previousLocalTree: t.prevLocal,
+		previousRemoteTree: t.prevRemote,
+		currentLocalTreeErrors: [],
+		currentLocalTreeIgnored: []
+	})
+
+	return result.deltas.length
+}
+
+describe("deltas.process — CPU hot path", () => {
+	it("size sweep: bulk local add (twoWay) — the common incremental case", async () => {
+		for (const nodes of [10_000, 50_000, 200_000, 500_000]) {
+			const base = sceneOf(nodes)
+			const prevLocal = buildLocalTree(base)
+			const prevRemote = buildRemoteTree(base)
+			const addCount = Math.max(1, Math.round(nodes * 0.01))
+			const curLocal = buildLocalTree(addFiles(base, addCount))
+			const t: Trees = { prevLocal, prevRemote, curLocal, curRemote: prevRemote }
+
+			// Correctness sanity: exactly `addCount` uploadFile deltas (plus nothing else).
+			const count = await runProcess("twoWay", t)
+
+			expect(count).toBe(addCount)
+
+			await bench({
+				group: "deltas.process / size sweep (twoWay add 1%)",
+				name: `add ${addCount} into ${nodes} nodes`,
+				n: nodes,
+				iterations: nodes >= 200_000 ? 3 : 6,
+				setup: () => t,
+				run: tr => runProcess("twoWay", tr),
+				extra: () => ({ deltas: addCount })
+			})
+		}
+	})
+
+	it("scenario matrix at 200k nodes (twoWay)", async () => {
+		const nodes = 200_000
+		const base = sceneOf(nodes)
+		const prevLocal = buildLocalTree(base)
+		const prevRemote = buildRemoteTree(base)
+		const k = 2_000
+
+		const scenarios: { name: string; build: () => Trees }[] = [
+			{
+				name: "no-op (huge tree, 0 deltas)",
+				build: () => ({ prevLocal, prevRemote, curLocal: prevLocal, curRemote: prevRemote })
+			},
+			{
+				name: "local add 1%",
+				build: () => ({ prevLocal, prevRemote, curLocal: buildLocalTree(addFiles(base, k)), curRemote: prevRemote })
+			},
+			{
+				name: "local delete 1%",
+				build: () => ({ prevLocal, prevRemote, curLocal: buildLocalTree(deleteFiles(base, k)), curRemote: prevRemote })
+			},
+			{
+				name: "local modify 1%",
+				build: () => ({ prevLocal, prevRemote, curLocal: buildLocalTree(modifyFiles(base, k, "local")), curRemote: prevRemote })
+			},
+			{
+				name: "remote modify 1%",
+				build: () => ({ prevLocal, prevRemote, curLocal: prevLocal, curRemote: buildRemoteTree(modifyFiles(base, k, "remote")) })
+			},
+			{
+				name: "rename top dir (subtree collapse)",
+				build: () => ({ prevLocal, prevRemote, curLocal: buildLocalTree(renameTopDir(base, "/dir-0", "/dir-renamed")), curRemote: prevRemote })
+			}
+		]
+
+		for (const scenario of scenarios) {
+			const t = scenario.build()
+
+			await bench({
+				group: "deltas.process / scenario matrix @200k (twoWay)",
+				name: scenario.name,
+				n: nodes,
+				iterations: 4,
+				setup: () => t,
+				run: tr => runProcess("twoWay", tr)
+			})
+		}
+	})
+
+	it("all 5 modes: local add 1% @100k", async () => {
+		const nodes = 100_000
+		const base = sceneOf(nodes)
+		const prevLocal = buildLocalTree(base)
+		const prevRemote = buildRemoteTree(base)
+		const curLocal = buildLocalTree(addFiles(base, 1_000))
+		const t: Trees = { prevLocal, prevRemote, curLocal, curRemote: prevRemote }
+		const modes: SyncMode[] = ["twoWay", "localToCloud", "localBackup", "cloudToLocal", "cloudBackup"]
+
+		for (const mode of modes) {
+			await bench({
+				group: "deltas.process / all modes (local add 1% @100k)",
+				name: mode,
+				n: nodes,
+				iterations: 5,
+				setup: () => t,
+				run: tr => runProcess(mode, tr)
+			})
+		}
+	})
+})

package/tests/bench/harness/fake-sync.ts

@@ -0,0 +1,32 @@
+import type Sync from "../../../src/lib/sync"
+import Deltas from "../../../src/lib/deltas"
+import { type SyncMode } from "../../../src/types"
+
+/**
+ * The minimal slice of `Sync` that `Deltas.process` actually reads: mode, removed, the cached upload
+ * hashes, a `createFileHash` (only hit on a same-size-mtime-touch modify), the ignorer, and the
+ * dot-file flag. Building this directly avoids constructing a whole memfs world + fake cloud + timers
+ * for what is a pure in-memory CPU benchmark, so tree construction (the thing we are NOT measuring) is
+ * the only setup cost.
+ */
+export function makeDeltaSync(
+	mode: SyncMode,
+	overrides?: { localFileHashes?: Record<string, string>; createFileHash?: () => Promise<string>; ignores?: (path: string) => boolean }
+): Sync {
+	return {
+		mode,
+		removed: false,
+		excludeDotFiles: false,
+		localFileHashes: overrides?.localFileHashes ?? {},
+		localFileSystem: {
+			createFileHash: overrides?.createFileHash ?? (async (): Promise<string> => "benchhash")
+		},
+		ignorer: {
+			ignores: overrides?.ignores ?? ((): boolean => false)
+		}
+	} as unknown as Sync
+}
+
+export function makeDeltas(mode: SyncMode, overrides?: Parameters<typeof makeDeltaSync>[1]): Deltas {
+	return new Deltas(makeDeltaSync(mode, overrides))
+}

package/tests/bench/harness/measure.ts

@@ -0,0 +1,276 @@
+import fs from "fs"
+import os from "os"
+import pathModule from "path"
+
+/**
+ * A single benchmark measurement. Captures the three axes the goal cares about — wall time, CPU time,
+ * and memory — plus the input scale so results are comparable across sizes.
+ */
+export type BenchResult = {
+	group: string
+	name: string
+	/** Input scale (e.g. node count) so ms/op-per-node can be derived. */
+	n: number
+	iterations: number
+	/** Wall-clock ms per iteration (mean / min). */
+	msMean: number
+	msMin: number
+	/** CPU ms per iteration (user+system), via process.cpuUsage. */
+	cpuMsMean: number
+	/** Heap still alive AFTER the run but BEFORE gc (retained result + transient not-yet-collected). MB. */
+	heapLiveMB: number
+	/** Heap retained AFTER gc (the result the run keeps referenced). MB. */
+	heapRetainedMB: number
+	/** Peak RSS growth observed by sampling during the timed loop, relative to pre-run RSS. MB. */
+	peakRssMB: number
+	/** ns per node (msMean / n * 1e6) — the headline efficiency number. */
+	nsPerNode: number
+	extra?: Record<string, number | string>
+}
+
+const results: BenchResult[] = []
+
+function mean(xs: number[]): number {
+	return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length
+}
+
+function min(xs: number[]): number {
+	return xs.length === 0 ? 0 : Math.min(...xs)
+}
+
+function gc(): void {
+	globalThis.gc?.()
+}
+
+const MB = 1024 * 1024
+
+function fmt(n: number, digits = 2): string {
+	if (!Number.isFinite(n)) {
+		return "—"
+	}
+
+	return n.toLocaleString("en-US", { minimumFractionDigits: digits, maximumFractionDigits: digits })
+}
+
+/**
+ * Run one benchmark. `setup` builds a fresh input per iteration (NOT timed — so tree construction never
+ * pollutes the measurement); `run` is the timed body. Time + CPU are averaged over `iterations`; peak RSS
+ * is sampled across the whole timed loop; retained/live heap is measured on a single dedicated run so the
+ * accumulated allocations of the time loop don't inflate it.
+ */
+export async function bench<T>(options: {
+	group: string
+	name: string
+	n: number
+	iterations?: number
+	warmup?: number
+	setup: () => T | Promise<T>
+	run: (input: T) => unknown | Promise<unknown>
+	/** Optional extra columns derived from one input (e.g. delta count). */
+	extra?: (input: T) => Record<string, number | string>
+}): Promise<BenchResult> {
+	const iterations = options.iterations ?? 5
+	const warmup = options.warmup ?? 1
+
+	for (let i = 0; i < warmup; i++) {
+		const input = await options.setup()
+
+		await options.run(input)
+	}
+
+	gc()
+
+	const times: number[] = []
+	let cpuTotalMs = 0
+	let peakRss = 0
+	const rssBase = process.memoryUsage().rss
+	const sampler = setInterval(() => {
+		const rss = process.memoryUsage().rss - rssBase
+
+		if (rss > peakRss) {
+			peakRss = rss
+		}
+	}, 2)
+
+	// Keep the sampler from holding the event loop open / keeping the process alive.
+	if (typeof sampler === "object" && sampler && "unref" in sampler) {
+		;(sampler as { unref: () => void }).unref()
+	}
+
+	let extra: Record<string, number | string> | undefined
+
+	for (let i = 0; i < iterations; i++) {
+		const input = await options.setup()
+
+		if (i === 0 && options.extra) {
+			extra = options.extra(input)
+		}
+
+		const cpu0 = process.cpuUsage()
+		const t0 = performance.now()
+
+		await options.run(input)
+
+		const elapsed = performance.now() - t0
+		const cpu = process.cpuUsage(cpu0)
+
+		times.push(elapsed)
+		cpuTotalMs += (cpu.user + cpu.system) / 1000
+	}
+
+	clearInterval(sampler)
+
+	// Dedicated retained-memory run.
+	gc()
+
+	const heap0 = process.memoryUsage().heapUsed
+	const memInput = await options.setup()
+	const out = await options.run(memInput)
+	const heapLive = process.memoryUsage().heapUsed - heap0
+
+	gc()
+
+	const heapRetained = process.memoryUsage().heapUsed - heap0
+
+	// Hold a reference so the optimizer / gc can't drop the result before we read retained heap.
+	void out
+	void memInput
+
+	const msMean = mean(times)
+	const result: BenchResult = {
+		group: options.group,
+		name: options.name,
+		n: options.n,
+		iterations,
+		msMean,
+		msMin: min(times),
+		cpuMsMean: cpuTotalMs / iterations,
+		heapLiveMB: heapLive / MB,
+		heapRetainedMB: heapRetained / MB,
+		peakRssMB: peakRss / MB,
+		nsPerNode: options.n > 0 ? (msMean / options.n) * 1e6 : 0,
+		...(extra ? { extra } : {})
+	}
+
+	results.push(result)
+	appendResult(result)
+
+	return result
+}
+
+/** JSONL path that EVERY bench process appends to (cleared once at the start of a run by the runner). */
+function jsonlPath(): string {
+	return process.env["BENCH_JSONL"] ?? pathModule.join(process.cwd(), "docs/perf/benchmarks/_results.jsonl")
+}
+
+/**
+ * Persist + print one result immediately. Incremental append (not an exit-time flush) so partial runs
+ * still produce data and results survive across the separate worker processes vitest spawns per file —
+ * vitest workers do not reliably fire `process.on("exit")`.
+ */
+function appendResult(r: BenchResult): void {
+	const extraStr = r.extra
+		? " | " +
+		  Object.entries(r.extra)
+				.map(([k, v]) => `${k}=${typeof v === "number" ? fmt(v, 0) : v}`)
+				.join(" ")
+		: ""
+
+	// process.stdout.write bypasses vitest's console grouping so the line is always visible in the run log.
+	process.stdout.write(
+		`[bench] ${r.group} :: ${r.name} | n=${fmt(r.n, 0)} | ${fmt(r.msMean)}ms (min ${fmt(r.msMin)}) | cpu ${fmt(
+			r.cpuMsMean
+		)}ms | ns/node ${fmt(r.nsPerNode, 1)} | heapRet ${fmt(r.heapRetainedMB)}MB live ${fmt(r.heapLiveMB)}MB | peakRSS ${fmt(
+			r.peakRssMB
+		)}MB${extraStr}\n`
+	)
+
+	try {
+		const path = jsonlPath()
+
+		fs.mkdirSync(pathModule.dirname(path), { recursive: true })
+		fs.appendFileSync(path, JSON.stringify(r) + "\n", "utf-8")
+	} catch {
+		// Best-effort persistence; the stdout line above is the fallback record.
+	}
+}
+
+export function getResults(): BenchResult[] {
+	return results
+}
+
+/**
+ * Record a fully-computed result (for benchmarks like long-run leak detection that measure their own
+ * bespoke metrics rather than a single timed `run`). Missing numeric fields default to 0.
+ */
+export function recordCustom(
+	partial: { group: string; name: string; n: number } & Partial<Omit<BenchResult, "group" | "name" | "n">>
+): void {
+	const result: BenchResult = {
+		iterations: 1,
+		msMean: 0,
+		msMin: 0,
+		cpuMsMean: 0,
+		heapLiveMB: 0,
+		heapRetainedMB: 0,
+		peakRssMB: 0,
+		nsPerNode: 0,
+		...partial
+	}
+
+	results.push(result)
+	appendResult(result)
+}
+
+/**
+ * Render a JSONL results file (produced incrementally by {@link bench}) into a grouped markdown report.
+ * Run as a standalone step after the vitest bench run (see docs/perf/02-benchmarks.md).
+ */
+export function renderReport(inJsonl: string, outMd: string, label: string): void {
+	if (!fs.existsSync(inJsonl)) {
+		throw new Error(`No results file at ${inJsonl}`)
+	}
+
+	const rows: BenchResult[] = fs
+		.readFileSync(inJsonl, "utf-8")
+		.split("\n")
+		.filter(line => line.trim().length > 0)
+		.map(line => JSON.parse(line) as BenchResult)
+
+	const lines: string[] = []
+
+	lines.push(`# Benchmark results — ${label}`)
+	lines.push("")
+	lines.push(`Generated: ${new Date().toISOString()}`)
+	lines.push(`Node: ${process.version} | platform: ${process.platform} | cpus: ${os.cpus().length}`)
+	lines.push("")
+
+	for (const group of [...new Set(rows.map(r => r.group))]) {
+		lines.push(`## ${group}`)
+		lines.push("")
+		lines.push("| scenario | n | ms mean | ms min | cpu ms | ns/node | heap ret MB | heap live MB | peak RSS MB | extra |")
+		lines.push("|---|---:|---:|---:|---:|---:|---:|---:|---:|---|")
+
+		for (const r of rows.filter(x => x.group === group)) {
+			const extraStr = r.extra
+				? Object.entries(r.extra)
+						.map(([k, v]) => `${k}=${typeof v === "number" ? fmt(v as number, 0) : v}`)
+						.join(", ")
+				: ""
+
+			lines.push(
+				`| ${r.name} | ${fmt(r.n, 0)} | ${fmt(r.msMean)} | ${fmt(r.msMin)} | ${fmt(r.cpuMsMean)} | ${fmt(
+					r.nsPerNode,
+					1
+				)} | ${fmt(r.heapRetainedMB)} | ${fmt(r.heapLiveMB)} | ${fmt(r.peakRssMB)} | ${extraStr} |`
+			)
+		}
+
+		lines.push("")
+	}
+
+	fs.mkdirSync(pathModule.dirname(outMd), { recursive: true })
+	fs.writeFileSync(outMd, lines.join("\n"), "utf-8")
+
+	process.stdout.write(`\n[bench] rendered ${rows.length} results -> ${outMd}\n`)
+}