typescript-virtual-container 1.5.3 → 1.5.5

package/src/utils/vfsDiff.ts

@@ -1,275 +0,0 @@
-/**
- * vfsDiff.ts
- *
- * Snapshot diff tooling for `VirtualFileSystem`.
- *
- * Compares two VFS snapshots and returns structured diff results suitable
- * for test assertions, audit logging, and deployment verification.
- *
- * @example
- * ```ts
- * import { diffSnapshots, formatDiff } from "typescript-virtual-container/utils/vfsDiff";
- *
- * const before = shell.vfs.toSnapshot();
- * await client.exec("npm install && mkdir -p /app");
- * const after = shell.vfs.toSnapshot();
- *
- * const diff = diffSnapshots(before, after);
- * console.log(formatDiff(diff));
- *
- * // Test assertions
- * expect(diff.added).toContain("/app");
- * expect(diff.modified).toContain("/etc/hosts");
- * expect(diff.removed).not.toContain("/tmp/needed-file");
- * ```
- */
-
-import type {
-	VfsSnapshot,
-	VfsSnapshotNode,
-	VfsSnapshotFileNode,
-	VfsSnapshotDirectoryNode,
-} from "../types/vfs";
-
-// ─── types ────────────────────────────────────────────────────────────────────
-
-/** A single changed file entry in a diff result. */
-export interface VfsDiffEntry {
-	/** Absolute VFS path of the changed node. */
-	path: string;
-	/** Node type — `"file"` or `"directory"`. */
-	type: "file" | "directory";
-}
-
-/** A modified file entry — includes before/after content for files. */
-export interface VfsDiffModified extends VfsDiffEntry {
-	type: "file";
-	/** Content before the change (decoded from base64). */
-	before: string;
-	/** Content after the change (decoded from base64). */
-	after: string;
-}
-
-/** Full result of a snapshot diff operation. */
-export interface VfsDiff {
-	/** Paths present in `after` but not in `before`. */
-	added: VfsDiffEntry[];
-	/** Paths present in `before` but not in `after`. */
-	removed: VfsDiffEntry[];
-	/** Files whose content or mode changed between snapshots. */
-	modified: VfsDiffModified[];
-	/** True when there are no differences. */
-	clean: boolean;
-}
-
-// ─── internal helpers ─────────────────────────────────────────────────────────
-
-function flattenSnapshot(
-	node: VfsSnapshotNode,
-	prefix: string,
-	out: Map<string, VfsSnapshotNode>,
-): void {
-	const path = prefix === "" ? "/" : prefix;
-	out.set(path, node);
-	if (node.type === "directory") {
-		for (const child of (node as VfsSnapshotDirectoryNode).children ?? []) {
-			flattenSnapshot(child, `${prefix}/${child.name}`, out);
-		}
-	}
-}
-
-function decodeContent(node: VfsSnapshotFileNode): string {
-	try {
-		return Buffer.from(node.contentBase64, "base64").toString("utf8");
-	} catch {
-		return node.contentBase64;
-	}
-}
-
-// ─── public API ───────────────────────────────────────────────────────────────
-
-/**
- * Compute the diff between two VFS snapshots.
- *
- * @param before  Snapshot taken before the operation.
- * @param after   Snapshot taken after the operation.
- * @param options Optional filtering options.
- * @returns A structured `VfsDiff` result.
- */
-export function diffSnapshots(
-	before: VfsSnapshot,
-	after: VfsSnapshot,
-	options: {
-		/** Glob-style path prefixes to ignore (e.g. `["/proc", "/var/log"]`). */
-		ignore?: string[];
-	} = {},
-): VfsDiff {
-	const ignorePrefixes = options.ignore ?? [];
-
-	const shouldIgnore = (path: string): boolean =>
-		ignorePrefixes.some(
-			(prefix) => path === prefix || path.startsWith(`${prefix}/`),
-		);
-
-	const beforeMap = new Map<string, VfsSnapshotNode>();
-	const afterMap = new Map<string, VfsSnapshotNode>();
-
-	flattenSnapshot(before.root, "", beforeMap);
-	flattenSnapshot(after.root, "", afterMap);
-
-	const added: VfsDiffEntry[] = [];
-	const removed: VfsDiffEntry[] = [];
-	const modified: VfsDiffModified[] = [];
-
-	// Added — in after, not in before
-	for (const [path, node] of afterMap) {
-		if (shouldIgnore(path)) continue;
-		if (!beforeMap.has(path)) {
-			added.push({ path, type: node.type });
-		}
-	}
-
-	// Removed — in before, not in after
-	for (const [path, node] of beforeMap) {
-		if (shouldIgnore(path)) continue;
-		if (!afterMap.has(path)) {
-			removed.push({ path, type: node.type });
-		}
-	}
-
-	// Modified — in both, but content or mode changed
-	for (const [path, afterNode] of afterMap) {
-		if (shouldIgnore(path)) continue;
-		const beforeNode = beforeMap.get(path);
-		if (!beforeNode) continue; // already in added
-		if (afterNode.type !== beforeNode.type) continue; // type change = add+remove
-
-		if (afterNode.type === "file" && beforeNode.type === "file") {
-			const beforeContent = decodeContent(beforeNode as VfsSnapshotFileNode);
-			const afterContent = decodeContent(afterNode as VfsSnapshotFileNode);
-			const modeChanged = afterNode.mode !== beforeNode.mode;
-			if (beforeContent !== afterContent || modeChanged) {
-				modified.push({
-					path,
-					type: "file",
-					before: beforeContent,
-					after: afterContent,
-				});
-			}
-		}
-	}
-
-	// Sort all arrays for determinism
-	const sortByPath = (a: VfsDiffEntry, b: VfsDiffEntry) =>
-		a.path.localeCompare(b.path);
-
-	added.sort(sortByPath);
-	removed.sort(sortByPath);
-	modified.sort(sortByPath);
-
-	return {
-		added,
-		removed,
-		modified,
-		clean: added.length === 0 && removed.length === 0 && modified.length === 0,
-	};
-}
-
-/**
- * Format a `VfsDiff` as a human-readable string similar to `git diff --stat`.
- *
- * @param diff    Result from `diffSnapshots`.
- * @param options Formatting options.
- */
-export function formatDiff(
-	diff: VfsDiff,
-	options: {
-		/** Show file content changes inline. Default: false. */
-		showContent?: boolean;
-		/** Max chars of content to show per change. Default: 120. */
-		maxContentChars?: number;
-	} = {},
-): string {
-	if (diff.clean) return "(no changes)";
-
-	const { showContent = false, maxContentChars = 120 } = options;
-	const lines: string[] = [];
-
-	for (const entry of diff.added) {
-		lines.push(`+ ${entry.path}  [${entry.type}]`);
-	}
-
-	for (const entry of diff.removed) {
-		lines.push(`- ${entry.path}  [${entry.type}]`);
-	}
-
-	for (const entry of diff.modified) {
-		lines.push(`~ ${entry.path}  [modified]`);
-		if (showContent) {
-			const before = entry.before.slice(0, maxContentChars);
-			const after = entry.after.slice(0, maxContentChars);
-			lines.push(
-				`  before: ${JSON.stringify(before)}${entry.before.length > maxContentChars ? "…" : ""}`,
-			);
-			lines.push(
-				`  after:  ${JSON.stringify(after)}${entry.after.length > maxContentChars ? "…" : ""}`,
-			);
-		}
-	}
-
-	const summary = [
-		diff.added.length > 0 ? `${diff.added.length} added` : "",
-		diff.removed.length > 0 ? `${diff.removed.length} removed` : "",
-		diff.modified.length > 0 ? `${diff.modified.length} modified` : "",
-	]
-		.filter(Boolean)
-		.join(", ");
-
-	lines.push(`\n${summary}`);
-	return lines.join("\n");
-}
-
-/**
- * Assert that a diff contains specific paths, throwing on mismatch.
- * Designed for use in test suites.
- *
- * @param diff    Result from `diffSnapshots`.
- * @param expect  Expected paths in each category.
- * @throws When any expectation is not met.
- */
-export function assertDiff(
-	diff: VfsDiff,
-	expect: {
-		added?: string[];
-		removed?: string[];
-		modified?: string[];
-	},
-): void {
-	const addedPaths = diff.added.map((e) => e.path);
-	const removedPaths = diff.removed.map((e) => e.path);
-	const modifiedPaths = diff.modified.map((e) => e.path);
-
-	for (const path of expect.added ?? []) {
-		if (!addedPaths.includes(path)) {
-			throw new Error(
-				`assertDiff: expected "${path}" to be added, but it was not.\nAdded: ${JSON.stringify(addedPaths)}`,
-			);
-		}
-	}
-
-	for (const path of expect.removed ?? []) {
-		if (!removedPaths.includes(path)) {
-			throw new Error(
-				`assertDiff: expected "${path}" to be removed, but it was not.\nRemoved: ${JSON.stringify(removedPaths)}`,
-			);
-		}
-	}
-
-	for (const path of expect.modified ?? []) {
-		if (!modifiedPaths.includes(path)) {
-			throw new Error(
-				`assertDiff: expected "${path}" to be modified, but it was not.\nModified: ${JSON.stringify(modifiedPaths)}`,
-			);
-		}
-	}
-}

package/tests/command-helpers.test.ts

@@ -1,116 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { getArg, getFlag, ifFlag } from "../src/commands/command-helpers";
-
-describe("command-helpers", () => {
-	test("ifFlag detects plain and inline flag forms", () => {
-		expect(ifFlag(["-l", "docs"], ["-l", "--long"])).toBe(true);
-		expect(ifFlag(["--user=root", "whoami"], "--user")).toBe(true);
-		expect(ifFlag(["docs"], ["-l", "--long"])).toBe(false);
-	});
-
-	test("ifFlag with multiple flags checks all", () => {
-		expect(ifFlag(["-l", "-h"], ["-l", "--long"])).toBe(true);
-		expect(ifFlag(["-h"], ["-l", "--long"])).toBe(false);
-		expect(ifFlag(["-l"], ["-l", "--long"])).toBe(true);
-	});
-
-	test("ifFlag empty args returns false", () => {
-		expect(ifFlag([], ["-l", "--long"])).toBe(false);
-	});
-
-	test("ifFlag single flag array", () => {
-		expect(ifFlag(["-n"], "-n")).toBe(true);
-		expect(ifFlag(["-m"], "-n")).toBe(false);
-	});
-
-	test("getFlag returns value for adjacent and inline forms", () => {
-		expect(getFlag(["-u", "root", "id"], ["-u", "--user"])).toBe("root");
-		expect(getFlag(["--user=alice", "id"], ["-u", "--user"])).toBe("alice");
-		expect(getFlag(["-i", "whoami"], "-i")).toBe("whoami");
-		expect(getFlag(["-o"], "-o")).toBe(true);
-		expect(getFlag(["pwd"], ["-u", "--user"])).toBeUndefined();
-	});
-
-	test("getFlag with multiple flag aliases", () => {
-		expect(getFlag(["-u", "john"], ["-u", "--user", "-U"])).toBe("john");
-		expect(getFlag(["--user=mary"], ["-u", "--user"])).toBe("mary");
-		expect(getFlag(["-U", "admin"], ["-u", "--user", "-U"])).toBe("admin");
-	});
-
-	test("getFlag inline with equals", () => {
-		expect(getFlag(["--option=value"], "--option")).toBe("value");
-		expect(getFlag(["--opt=123"], "--opt")).toBe("123");
-	});
-
-	test("getFlag first occurrence", () => {
-		expect(getFlag(["-u", "first", "-u", "second"], "-u")).toBe("first");
-	});
-
-	test("getFlag with boolean flag", () => {
-		expect(getFlag(["-v"], "-v")).toBe(true);
-		expect(getFlag(["-v", "file.txt"], "-v")).toBe("file.txt");
-	});
-
-	test("getArg skips bool and value flags", () => {
-		const args = ["-i", "-u", "root", "sh", "-c", "whoami"];
-		const options = { flags: ["-i"], flagsWithValue: ["-u"] };
-
-		expect(getArg(args, 0, options)).toBe("sh");
-		expect(getArg(args, 1, options)).toBe("-c");
-		expect(getArg(args, 2, options)).toBe("whoami");
-		expect(getArg(args, 3, options)).toBeUndefined();
-	});
-
-	test("getArg with no flags", () => {
-		const args = ["file1", "file2", "file3"];
-		const options = { flags: [], flagsWithValue: [] };
-
-		expect(getArg(args, 0, options)).toBe("file1");
-		expect(getArg(args, 1, options)).toBe("file2");
-		expect(getArg(args, 2, options)).toBe("file3");
-	});
-
-	test("getArg empty args", () => {
-		const args: string[] = [];
-		const options = { flags: ["-n"] };
-
-		expect(getArg(args, 0, options)).toBeUndefined();
-	});
-
-	test("getArg skips values for flagsWithValue", () => {
-		const args = ["-d", ":", "-f", "1", "input.txt"];
-		const options = { flagsWithValue: ["-d", "-f"] };
-
-		expect(getArg(args, 0, options)).toBe("input.txt");
-	});
-
-	test("getArg keeps tokens after -- as positional", () => {
-		const args = ["-n", "--", "-n", "hello"];
-		const options = { flags: ["-n"] };
-
-		expect(getArg(args, 0, options)).toBe("-n");
-		expect(getArg(args, 1, options)).toBe("hello");
-	});
-
-	test("getArg -- blocks all flag processing", () => {
-		const args = ["-a", "--", "-a", "-b", "-c"];
-		const options = { flags: ["-a", "-b", "-c"] };
-
-		expect(getArg(args, 0, options)).toBe("-a");
-		expect(getArg(args, 1, options)).toBe("-b");
-		expect(getArg(args, 2, options)).toBe("-c");
-	});
-
-	test("getArg with mixed flags and positionals", () => {
-		const args = ["-v", "file1", "-o", "output.txt", "file2"];
-		const options = { flags: ["-v"], flagsWithValue: ["-o"] };
-
-		expect(getArg(args, 0, options)).toBe("file1");
-		expect(getArg(args, 1, options)).toBe("file2");
-	});
-
-	test("getArg at end of args", () => {
-		const args = ["a", "b", "c"];
-		expect(getArg(args, 5, {})).toBeUndefined();
-	});
-});