@decohere/devkit 0.0.1-dev.125 → 0.0.1-dev.5

package/src/io/watch.ts

@@ -0,0 +1,290 @@
+import { type FSWatcher, watch as nativeWatch, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import picomatch from "picomatch";
+import { type File, FileEx, type Watcher } from "@decohere/core/io";
+
+export type WatchOptions = {
+	include?: string[];
+	ignore?: string[];
+	cwd?: string;
+	ignoreInitial?: boolean;
+};
+
+export type WatchEventName = "add" | "change" | "addDir" | "unlink" | "unlinkDir";
+export const WatchEvents = {
+	add: "add",
+	change: "change",
+	addDir: "addDir",
+	unlink: "unlink",
+	unlinkDir: "unlinkDir",
+} satisfies Record<string, WatchEventName>;
+export function watch(directory: string, options: WatchOptions = { cwd: "." }) {
+	const { include, ignore, ignoreInitial = false } = options;
+
+	const changeCoalesceMs = 25;
+
+	const handlers = {
+		ready: new Set<() => unknown>(),
+		add: new Set<(file: File) => unknown>(),
+		change: new Set<(file: File) => unknown>(),
+		addDir: new Set<(file: File) => unknown>(),
+		unlink: new Set<(file: File) => unknown>(),
+		unlinkDir: new Set<(file: File) => unknown>(),
+	};
+
+	let resolveReady: (() => void) | undefined;
+	const ready = new Promise<void>((resolve) => {
+		resolveReady = resolve;
+	});
+
+	const snapshot = buildSnapshot(directory);
+
+	const isFiltered = (relativePath: string) => {
+		const posixRelativePath = toPosixPath(relativePath);
+		const posixFullPath = toPosixPath(path.resolve(directory, relativePath));
+		const matchesEitherPath = (patterns: string[]) =>
+			picomatch.isMatch(posixRelativePath, patterns) ||
+			picomatch.isMatch(posixFullPath, patterns);
+
+		if (include && include.length > 0) {
+			return !matchesEitherPath(include);
+		}
+
+		if (ignore && ignore.length > 0) {
+			return matchesEitherPath(ignore);
+		}
+
+		return false;
+	};
+
+	const emit = (event: WatchEventName, relativePath: string) => {
+		if (isFiltered(relativePath)) {
+			return;
+		}
+
+		const fullPath = path.resolve(directory, relativePath);
+		for (const handler of handlers[event]) {
+			handler(new FileEx({ fullPath, relativePath }));
+		}
+	};
+
+	const pendingChangeTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+	const emitChange = (relativePath: string) => {
+		const existing = pendingChangeTimers.get(relativePath);
+		if (existing != null) {
+			clearTimeout(existing);
+		}
+
+		const timer = setTimeout(() => {
+			pendingChangeTimers.delete(relativePath);
+			emit("change", relativePath);
+		}, changeCoalesceMs);
+
+		pendingChangeTimers.set(relativePath, timer);
+	};
+
+	const emitReady = () => {
+		for (const handler of handlers.ready) {
+			handler();
+		}
+	};
+
+	queueMicrotask(() => {
+		if (!ignoreInitial) {
+			for (const [relativePath, entry] of snapshot) {
+				emit(entry.isDirectory ? "addDir" : "add", relativePath);
+			}
+		}
+
+		emitReady();
+		resolveReady?.();
+		resolveReady = undefined;
+	});
+
+	// One non-recursive watcher per directory. Node's recursive mode on Linux tracks files
+	// individually and goes silent for a file once an editor replaces it with an atomic save
+	// (write temp file, rename over the original); directory watchers keep seeing it (#505).
+	const directoryWatchers = new Map<string, FSWatcher>();
+
+	const watchDirectory = (relativeDir: string) => {
+		if (directoryWatchers.has(relativeDir)) {
+			return;
+		}
+		try {
+			const watcher = nativeWatch(
+				path.resolve(directory, relativeDir),
+				(_eventType, fileName) => {
+					if (fileName != null) {
+						onFsEvent(path.posix.join(relativeDir, toPosixPath(fileName.toString())));
+					}
+				},
+			);
+			watcher.on("error", () => unwatchDirectory(relativeDir));
+			directoryWatchers.set(relativeDir, watcher);
+		} catch {
+			// The directory vanished before we could watch it; its unlink event covers it.
+		}
+	};
+
+	const unwatchDirectory = (relativeDir: string) => {
+		for (const [watchedDir, watcher] of directoryWatchers) {
+			if (watchedDir === relativeDir || watchedDir.startsWith(`${relativeDir}/`)) {
+				watcher.close();
+				directoryWatchers.delete(watchedDir);
+			}
+		}
+	};
+
+	/** A directory appeared: watch it, and report what was created in it before we were watching. */
+	const addDirectory = (relativeDir: string) => {
+		watchDirectory(relativeDir);
+		const found = new Map<string, { isDirectory: boolean; fingerprint: string }>();
+		try {
+			collectSnapshotEntries(directory, path.resolve(directory, relativeDir), found);
+		} catch {
+			return;
+		}
+		for (const [relativePath, entry] of found) {
+			if (snapshot.has(relativePath)) continue;
+			snapshot.set(relativePath, entry);
+			if (entry.isDirectory) watchDirectory(relativePath);
+			emit(entry.isDirectory ? "addDir" : "add", relativePath);
+		}
+	};
+
+	/** A directory went away: stop watching it and forget everything that was under it. */
+	const removeDirectoryContents = (relativeDir: string) => {
+		unwatchDirectory(relativeDir);
+		// oxlint-disable-next-line unicorn/no-useless-spread -- iterate a copy: the loop deletes from the snapshot
+		for (const [relativePath, entry] of [...snapshot]) {
+			if (relativePath.startsWith(`${relativeDir}/`)) {
+				snapshot.delete(relativePath);
+				emit(entry.isDirectory ? "unlinkDir" : "unlink", relativePath);
+			}
+		}
+	};
+
+	const onFsEvent = (eventPath: string) => {
+		const relativePath = eventPath === "." ? "" : eventPath;
+		if (relativePath.length === 0) {
+			return;
+		}
+
+		const fullPath = path.resolve(directory, relativePath);
+		const previous = snapshot.get(relativePath);
+
+		try {
+			const stat = statSync(fullPath);
+			const current = toSnapshotEntry(stat);
+			snapshot.set(relativePath, current);
+
+			if (previous == null) {
+				emit(current.isDirectory ? "addDir" : "add", relativePath);
+				if (current.isDirectory) addDirectory(relativePath);
+				return;
+			}
+
+			if (previous.isDirectory !== current.isDirectory) {
+				if (previous.isDirectory) removeDirectoryContents(relativePath);
+				emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+				emit(current.isDirectory ? "addDir" : "add", relativePath);
+				return;
+			}
+
+			if (!current.isDirectory && previous.fingerprint !== current.fingerprint) {
+				emitChange(relativePath);
+			}
+		} catch {
+			if (previous == null) {
+				return;
+			}
+
+			snapshot.delete(relativePath);
+			const pending = pendingChangeTimers.get(relativePath);
+			if (pending != null) {
+				clearTimeout(pending);
+				pendingChangeTimers.delete(relativePath);
+			}
+			emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+		}
+	};
+
+	watchDirectory("");
+	for (const [relativePath, entry] of snapshot) {
+		if (entry.isDirectory) watchDirectory(relativePath);
+	}
+
+	const watchApi: Watcher = {
+		ready,
+		on(event: "ready" | WatchEventName, handler: ((file: File) => unknown) | (() => unknown)) {
+			if (event === "ready") {
+				handlers.ready.add(handler as () => unknown);
+				return watchApi;
+			}
+
+			handlers[event].add(handler as (file: File) => unknown);
+			return watchApi;
+		},
+		close: () => {
+			for (const pending of pendingChangeTimers.values()) {
+				clearTimeout(pending);
+			}
+			pendingChangeTimers.clear();
+			for (const watcher of directoryWatchers.values()) {
+				watcher.close();
+			}
+			directoryWatchers.clear();
+		},
+	};
+
+	return watchApi;
+}
+
+function buildSnapshot(
+	directoryPath: string,
+): Map<string, { isDirectory: boolean; fingerprint: string }> {
+	const snapshot = new Map<string, { isDirectory: boolean; fingerprint: string }>();
+	collectSnapshotEntries(directoryPath, directoryPath, snapshot);
+	return snapshot;
+}
+
+/** Never source, and huge: watching every folder inside them could exhaust OS watch limits. */
+const UNWATCHED_DIRECTORIES = new Set(["node_modules", ".git"]);
+
+function collectSnapshotEntries(
+	rootDirectoryPath: string,
+	currentDirectoryPath: string,
+	snapshot: Map<string, { isDirectory: boolean; fingerprint: string }>,
+) {
+	for (const entry of readdirSync(currentDirectoryPath, { encoding: "utf8" })) {
+		const name = typeof entry === "string" ? entry : String(entry);
+		const fullPath = path.join(currentDirectoryPath, name);
+		if (UNWATCHED_DIRECTORIES.has(name)) {
+			continue;
+		}
+		const relativePath = toPosixPath(path.relative(rootDirectoryPath, fullPath));
+		const stat = statSync(fullPath);
+		const snapshotEntry = toSnapshotEntry(stat);
+
+		snapshot.set(relativePath, snapshotEntry);
+
+		if (!snapshotEntry.isDirectory) {
+			continue;
+		}
+
+		collectSnapshotEntries(rootDirectoryPath, fullPath, snapshot);
+	}
+}
+
+function toSnapshotEntry(stat: { isDirectory(): boolean; mtimeMs: number; size: number }) {
+	const isDirectory = stat.isDirectory();
+	return {
+		isDirectory,
+		fingerprint: isDirectory ? `dir:${stat.mtimeMs}` : `file:${stat.mtimeMs}:${stat.size}`,
+	};
+}
+
+function toPosixPath(filePath: string) {
+	return filePath.split(path.sep).join(path.posix.sep);
+}

package/tests/cli/command.model.spec.ts

@@ -0,0 +1,91 @@
+import type { OptionValues } from "commander";
+import { expect, it, vi } from "vitest";
+import type { Action } from "../../src/cli/index.js";
+import { ActionResponse, DecohereCommand } from "../../src/cli/index.js";
+
+type TestActions = {
+	a: Action;
+	b: Action;
+};
+
+class AAction implements Action {
+	public constructor(
+		private readonly response: ActionResponse = ActionResponse.Success("a"),
+	) {}
+
+	public async run(): Promise<ActionResponse> {
+		return this.response;
+	}
+}
+
+class BAction implements Action {
+	public constructor(
+		private readonly response: ActionResponse = ActionResponse.Success("b"),
+	) {}
+
+	public async run(): Promise<ActionResponse> {
+		return this.response;
+	}
+}
+
+class TestCommand extends DecohereCommand<TestActions> {
+	public override get actions() {
+		return [AAction, BAction] as const;
+	}
+
+	public constructor() {
+		super("test");
+	}
+}
+
+it("does not throw when an action is skipped", async () => {
+	const command = new TestCommand();
+	const actions: TestActions = {
+		a: new AAction(ActionResponse.Skipped("a")),
+		b: new BAction(ActionResponse.Success("b")),
+	};
+	const runA = vi.spyOn(actions.a, "run");
+	const runB = vi.spyOn(actions.b, "run");
+
+	const response = await command.run(actions, {} as OptionValues);
+	expect(runA).toHaveBeenCalledTimes(1);
+	expect(runB).toHaveBeenCalledTimes(1);
+	expect(response.a?.skipped).toBe(true);
+	expect(response.b?.succeeded).toBe(true);
+});
+
+it("throws when an action returns a non-skipped error", async () => {
+	const command = new TestCommand();
+	const actions: TestActions = {
+		a: new AAction(ActionResponse.Error("a", "a failed")),
+		b: new BAction(ActionResponse.Skipped("b")),
+	};
+
+	await expect(command.run(actions, {} as OptionValues)).rejects.toThrow(
+		"test command failed",
+	);
+});
+
+it("throws when mapped action constructor is missing", async () => {
+	class MissingBCommand extends DecohereCommand<TestActions> {
+		public override get actions() {
+			return [AAction, BAction] as const;
+		}
+
+		public constructor() {
+			super("test");
+		}
+	}
+
+	const command = new MissingBCommand();
+	const actions: TestActions = {
+		a: new AAction(),
+		b: {
+			run: async () => ActionResponse.Success("b"),
+		},
+	};
+
+	await expect(command.run(actions, {} as OptionValues)).rejects.toThrow(
+		"missing action instance for BAction",
+	);
+});

package/tests/diagnostics/trace.spec.ts

@@ -0,0 +1,319 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// vi.resetModules() clears Vitest's module registry so that the next dynamic
+// import() re-evaluates trace.ts, picking up process.env.FORGE_TRACE into the
+// module-level `const isTraceEnabled` at load time.
+// vi.spyOn is set up after import — trace.ts calls scribe.logger() only when
+// the decorator is applied (inside the test body), not at module evaluation time.
+const importTrace = async () => {
+	const [decorators, { scribe }] = await Promise.all([
+		import("@decohere/devkit/diagnostics") as Promise<
+			typeof import("@decohere/devkit/diagnostics")
+		>,
+		import("@decohere/scribe"),
+	]);
+	// Spy on the shared scribe object — same reference trace.ts holds.
+	const loggerSpy = vi.spyOn(scribe, "logger").mockReturnValue({
+		trace: vi.fn(),
+		info: vi.fn(),
+	} as never);
+	return { ...decorators, loggerSpy };
+};
+
+describe("@timed decorator", () => {
+	beforeEach(() => {
+		vi.resetModules();
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.restoreAllMocks();
+	});
+
+	it("wraps the method when FORGE_TRACE is not set", async () => {
+		const { timed } = await importTrace();
+		class Subject {
+			public myMethod() {
+				return "result";
+			}
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+		const original = descriptor.value;
+		timed(Subject.prototype, "myMethod", descriptor);
+		expect(descriptor.value).not.toBe(original);
+		expect(descriptor.value.call(new Subject())).toBe("result");
+	});
+
+	it("logs timing at info for sync methods", async () => {
+		const { timed, loggerSpy } = await importTrace();
+		const infoFn = vi.fn();
+		const traceFn = vi.fn();
+		loggerSpy.mockReturnValue({ info: infoFn, trace: traceFn } as never);
+		class Subject {
+			public myMethod() {
+				return "result";
+			}
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+		timed(Subject.prototype, "myMethod", descriptor);
+		descriptor.value.call(new Subject());
+		expect(infoFn).toHaveBeenCalledWith(expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/));
+		expect(traceFn).not.toHaveBeenCalled();
+	});
+
+	it("logs timing at info after async method resolves", async () => {
+		const { timed, loggerSpy } = await importTrace();
+		const infoFn = vi.fn();
+		loggerSpy.mockReturnValue({ info: infoFn, trace: vi.fn() } as never);
+		class Subject {
+			public async myMethod() {
+				return "result";
+			}
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+		timed(Subject.prototype, "myMethod", descriptor);
+		expect(await descriptor.value.call(new Subject())).toBe("result");
+		expect(infoFn).toHaveBeenCalledWith(expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/));
+	});
+
+	it("logs timing at info even when async method rejects", async () => {
+		const { timed, loggerSpy } = await importTrace();
+		const infoFn = vi.fn();
+		loggerSpy.mockReturnValue({ info: infoFn, trace: vi.fn() } as never);
+		class Subject {
+			public async myMethod() {
+				throw new Error("boom");
+			}
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+		timed(Subject.prototype, "myMethod", descriptor);
+		await expect(descriptor.value.call(new Subject())).rejects.toThrow("boom");
+		expect(infoFn).toHaveBeenCalledWith(expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/));
+	});
+});
+
+describe("@trace / @Trace decorators", () => {
+	beforeEach(() => {
+		vi.resetModules();
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.restoreAllMocks();
+	});
+
+	describe("when FORGE_TRACE is not set", () => {
+		it("trace: returns descriptor unchanged (no wrapping)", async () => {
+			const { trace } = await importTrace();
+			const fn = vi.fn().mockReturnValue("result");
+			const descriptor = { value: fn };
+			trace({} as object, "myMethod", descriptor as PropertyDescriptor);
+			expect(descriptor.value).toBe(fn);
+		});
+
+		it("Trace: does not wrap class methods", async () => {
+			const { Trace } = await importTrace();
+			class Subject {
+				public greet() {
+					return "hi";
+				}
+			}
+			const original = Subject.prototype.greet;
+			Trace(Subject);
+			expect(Subject.prototype.greet).toBe(original);
+		});
+	});
+
+	describe("when FORGE_TRACE is set", () => {
+		beforeEach(() => {
+			vi.stubEnv("FORGE_TRACE", "1");
+		});
+
+		describe("trace (method decorator)", () => {
+			it("replaces the descriptor value with a wrapper", async () => {
+				const { trace } = await importTrace();
+				const fn = vi.fn().mockReturnValue("result");
+				class Subject {
+					public myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				expect(descriptor.value).not.toBe(fn);
+			});
+
+			it("preserves sync return value", async () => {
+				const { trace } = await importTrace();
+				const fn = vi.fn().mockReturnValue("result");
+				class Subject {
+					public myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				expect(descriptor.value.call(new Subject())).toBe("result");
+			});
+
+			it("logs timing for sync methods", async () => {
+				const { trace, loggerSpy } = await importTrace();
+				const traceFn = vi.fn();
+				loggerSpy.mockReturnValue({ trace: traceFn } as never);
+				const fn = vi.fn().mockReturnValue("result");
+				class Subject {
+					public myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				descriptor.value.call(new Subject());
+				expect(traceFn).toHaveBeenCalledWith(
+					expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/),
+				);
+			});
+
+			it("preserves async return value", async () => {
+				const { trace } = await importTrace();
+				const fn = vi.fn().mockResolvedValue("async-result");
+				class Subject {
+					public async myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				expect(await descriptor.value.call(new Subject())).toBe("async-result");
+			});
+
+			it("logs timing after async method resolves", async () => {
+				const { trace, loggerSpy } = await importTrace();
+				const traceFn = vi.fn();
+				loggerSpy.mockReturnValue({ trace: traceFn } as never);
+				const fn = vi.fn().mockResolvedValue("result");
+				class Subject {
+					public async myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				await descriptor.value.call(new Subject());
+				expect(traceFn).toHaveBeenCalledWith(
+					expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/),
+				);
+			});
+
+			it("logs timing even when async method rejects", async () => {
+				const { trace, loggerSpy } = await importTrace();
+				const traceFn = vi.fn();
+				loggerSpy.mockReturnValue({ trace: traceFn } as never);
+				const fn = vi.fn().mockRejectedValue(new Error("boom"));
+				class Subject {
+					public async myMethod() {
+						return fn();
+					}
+				}
+				const descriptor = Object.getOwnPropertyDescriptor(Subject.prototype, "myMethod")!;
+				trace(Subject.prototype, "myMethod", descriptor);
+				await expect(descriptor.value.call(new Subject())).rejects.toThrow("boom");
+				expect(traceFn).toHaveBeenCalledWith(
+					expect.stringMatching(/^myMethod\(.*\): [\d.]+ms$/),
+				);
+			});
+		});
+
+		describe("Trace (class decorator)", () => {
+			it("wraps all methods on the prototype", async () => {
+				const { Trace } = await importTrace();
+				class Subject {
+					public methodA() {
+						return "a";
+					}
+					public methodB() {
+						return "b";
+					}
+				}
+				const originalA = Subject.prototype.methodA;
+				const originalB = Subject.prototype.methodB;
+				Trace(Subject);
+				expect(Subject.prototype.methodA).not.toBe(originalA);
+				expect(Subject.prototype.methodB).not.toBe(originalB);
+			});
+
+			it("does not wrap the constructor", async () => {
+				const { Trace } = await importTrace();
+				const ctorSpy = vi.fn();
+				class Subject {
+					public constructor() {
+						ctorSpy();
+					}
+				}
+				expect(() => Trace(Subject)).not.toThrow();
+				new Subject();
+				expect(ctorSpy).toHaveBeenCalledOnce();
+			});
+
+			it("preserves method return values after wrapping", async () => {
+				const { Trace } = await importTrace();
+				class Subject {
+					public greet(name: string) {
+						return `hello ${name}`;
+					}
+				}
+				Trace(Subject);
+				expect(new Subject().greet("world")).toBe("hello world");
+			});
+
+			it("logs timing for each method call", async () => {
+				const { Trace, loggerSpy } = await importTrace();
+				const traceFn = vi.fn();
+				loggerSpy.mockReturnValue({ trace: traceFn } as never);
+				class Subject {
+					public methodA() {
+						return "a";
+					}
+					public methodB() {
+						return "b";
+					}
+				}
+				Trace(Subject);
+				const instance = new Subject();
+				instance.methodA();
+				instance.methodB();
+				expect(traceFn.mock.calls).toHaveLength(2);
+			});
+		});
+	});
+});
+
+describe("importing @decohere/devkit/diagnostics (#524)", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.restoreAllMocks();
+	});
+
+	it("leaves scribe alone even with FORGE_TRACE set: a library has no side effects on import", async () => {
+		vi.resetModules();
+		vi.stubEnv("FORGE_TRACE", "1");
+		const { scribe } = await import("@decohere/scribe");
+		const configure = vi.spyOn(scribe, "configure");
+
+		await import("@decohere/devkit/diagnostics");
+
+		expect(configure).not.toHaveBeenCalled();
+	});
+
+	it("reads FORGE_TRACE when a method is decorated, not when the module loads", async () => {
+		vi.resetModules();
+		const { trace } = await importTrace();
+		vi.stubEnv("FORGE_TRACE", "1");
+		const fn = vi.fn();
+		const descriptor = { value: fn };
+
+		trace({} as object, "myMethod", descriptor as PropertyDescriptor);
+
+		expect(descriptor.value).not.toBe(fn);
+	});
+});