feat: split file system out into create-fs package, with diffCreatedDirectory tester

packages/create-fs/README.md

@@ -0,0 +1,17 @@
+<h1 align="center">create-fs</h1>
+
+<p align="center">The file system used by <a href="https://create.bingo"><code>create</code></a>. 🗄️</p>
+
+<p align="center">
+	<a href="https://github.com/JoshuaKGoldberg/create/blob/main/.github/CODE_OF_CONDUCT.md" target="_blank"><img alt="🤝 Code of Conduct: Kept" src="https://img.shields.io/badge/%F0%9F%A4%9D_code_of_conduct-kept-21bb42" /></a>
+	<a href="https://codecov.io/gh/JoshuaKGoldberg/create" target="_blank"><img alt="🧪 Coverage" src="https://img.shields.io/codecov/c/github/JoshuaKGoldberg/create?label=%F0%9F%A7%AA%20coverage" /></a>
+	<a href="https://github.com/JoshuaKGoldberg/create/blob/main/LICENSE.md" target="_blank"><img alt="📝 License: MIT" src="https://img.shields.io/badge/%F0%9F%93%9D_license-MIT-21bb42.svg"></a>
+	<a href="http://npmjs.com/package/create-testers"><img alt="📦 npm version" src="https://img.shields.io/npm/v/create-testers?color=21bb42&label=%F0%9F%93%A6%20npm" /></a>
+	<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" />
+</p>
+
+See **[create.bingo](https://create.bingo)** for documentation.
+Specifically:
+
+- [Packages > `create-fs`](https://www.create.bingo/engine/packages/create-fs): for this package's documentation
+- [Runtime > Creations > `files`](https://www.create.bingo/engine/runtime/creations#files): for where these are used

packages/create-fs/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "create-fs",
+	"version": "0.1.0",
+	"description": "The file system used by create>. 🗄️",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/JoshuaKGoldberg/create",
+		"directory": "packages/create-fs"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "Josh Goldberg ✨",
+		"email": "npm@joshuakgoldberg.com"
+	},
+	"type": "module",
+	"main": "./lib/index.js",
+	"files": [
+		"lib/",
+		"package.json",
+		"LICENSE.md",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc"
+	},
+	"devDependencies": {
+		"@types/node": "^22.10.5"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

packages/create-fs/src/createReadingFileSystem.ts

@@ -0,0 +1,11 @@
+import * as fs from "node:fs/promises";
+
+import { ReadingFileSystem } from "./types/system.js";
+
+export function createReadingFileSystem(): ReadingFileSystem {
+	return {
+		readDirectory: async (filePath: string) => await fs.readdir(filePath),
+		readFile: async (filePath: string) =>
+			(await fs.readFile(filePath)).toString(),
+	};
+}

packages/create-fs/src/createWritingFileSystem.ts

@@ -0,0 +1,14 @@
+import * as fs from "node:fs/promises";
+
+import { createReadingFileSystem } from "./createReadingFileSystem.js";
+
+export function createWritingFileSystem() {
+	return {
+		...createReadingFileSystem(),
+		writeDirectory: async (directoryPath: string) =>
+			void (await fs.mkdir(directoryPath, { recursive: true })),
+		writeFile: async (filePath: string, contents: string) => {
+			await fs.writeFile(filePath, contents);
+		},
+	};
+}

packages/create-fs/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./createReadingFileSystem.js";
+export * from "./createWritingFileSystem.js";
+export * from "./intake/intakeFromDirectory.js";
+export type * from "./types/files.js";
+export type * from "./types/system.js";

packages/create-fs/src/intake/intakeFromDirectory.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { intakeFromDirectory } from "./intakeFromDirectory.js";
+
+const mockReaddir = vi.fn();
+const mockReadFile = vi.fn();
+const mockStat = vi.fn();
+
+vi.mock("node:fs/promises", () => ({
+	get readdir() {
+		return mockReaddir;
+	},
+	get readFile() {
+		return mockReadFile;
+	},
+	get stat() {
+		return mockStat;
+	},
+}));
+
+describe("intakeFromDirectory", () => {
+	it("returns an empty object when the directory has no files", async () => {
+		mockReaddir.mockResolvedValueOnce([]);
+
+		const directory = await intakeFromDirectory("from");
+
+		expect(directory).toEqual({});
+		expect(mockReaddir.mock.calls).toEqual([["from"]]);
+		expect(mockStat).not.toHaveBeenCalled();
+	});
+
+	it("returns files when the directory contains files", async () => {
+		mockReaddir.mockResolvedValueOnce(["included-a", "included-b"]);
+		mockReadFile
+			.mockResolvedValueOnce("contents-a")
+			.mockResolvedValueOnce("contents-b");
+		mockStat
+			.mockResolvedValueOnce({
+				isDirectory: () => false,
+				mode: 123,
+			})
+			.mockResolvedValueOnce({
+				isDirectory: () => false,
+				mode: 456,
+			});
+
+		const directory = await intakeFromDirectory("from");
+
+		expect(directory).toEqual({
+			"included-a": ["contents-a", { mode: 123 }],
+			"included-b": ["contents-b", { mode: 456 }],
+		});
+		expect(mockReaddir.mock.calls).toEqual([["from"]]);
+		expect(mockStat.mock.calls).toEqual([
+			["from/included-a"],
+			["from/included-b"],
+		]);
+	});
+
+	it("returns non-excluded files when the directory contains files and excludes is provided", async () => {
+		mockReaddir.mockResolvedValueOnce(["excluded", "included-a", "included-b"]);
+		mockReadFile
+			.mockResolvedValueOnce("contents-a")
+			.mockResolvedValueOnce("contents-b");
+		mockStat
+			.mockResolvedValueOnce({
+				isDirectory: () => false,
+				mode: 123,
+			})
+			.mockResolvedValueOnce({
+				isDirectory: () => false,
+				mode: 456,
+			});
+
+		const directory = await intakeFromDirectory("from", {
+			exclude: /excluded/,
+		});
+
+		expect(directory).toEqual({
+			"included-a": ["contents-a", { mode: 123 }],
+			"included-b": ["contents-b", { mode: 456 }],
+		});
+		expect(mockReaddir.mock.calls).toEqual([["from"]]);
+		expect(mockStat.mock.calls).toEqual([
+			["from/included-a"],
+			["from/included-b"],
+		]);
+	});
+
+	it("returns a nested file when the directory contains a nested directory", async () => {
+		mockReaddir
+			.mockResolvedValueOnce(["middle"])
+			.mockResolvedValueOnce(["excluded", "included"]);
+		mockReadFile.mockResolvedValueOnce("contents");
+		mockStat
+			.mockResolvedValueOnce({
+				isDirectory: () => true,
+			})
+			.mockResolvedValueOnce({
+				isDirectory: () => false,
+				mode: 123,
+			});
+
+		const directory = await intakeFromDirectory("from", {
+			exclude: /excluded/,
+		});
+
+		expect(directory).toEqual({
+			middle: {
+				included: ["contents", { mode: 123 }],
+			},
+		});
+		expect(mockReaddir.mock.calls).toEqual([["from"], ["from/middle"]]);
+		expect(mockStat.mock.calls).toEqual([
+			["from/middle"],
+			["from/middle/included"],
+		]);
+	});
+});

packages/create-fs/src/intake/intakeFromDirectory.ts

@@ -0,0 +1,31 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+
+import { CreatedDirectory } from "../types/files.js";
+
+export interface IntakeFromDirectorySettings {
+	exclude?: RegExp;
+}
+
+export async function intakeFromDirectory(
+	directoryPath: string,
+	settings: IntakeFromDirectorySettings = {},
+) {
+	const directory: CreatedDirectory = {};
+	const children = await fs.readdir(directoryPath);
+
+	for (const child of children) {
+		if (settings.exclude?.test(child)) {
+			continue;
+		}
+
+		const childPath = path.join(directoryPath, child);
+		const stat = await fs.stat(childPath);
+
+		directory[child] = stat.isDirectory()
+			? await intakeFromDirectory(childPath, settings)
+			: [(await fs.readFile(childPath)).toString(), { mode: stat.mode }];
+	}
+
+	return directory;
+}

packages/create-fs/src/types/files.ts

@@ -0,0 +1,18 @@
+export interface CreatedDirectory {
+	[i: string]: CreatedFileEntry | undefined;
+}
+
+export type CreatedFileEntry =
+	| [string, CreatedFileOptions]
+	| [string]
+	| CreatedDirectory
+	| false
+	| string;
+
+export interface CreatedFileOptions {
+	/**
+	 * File mode (permission and sticky bits) per chmod().
+	 * @example 0o777 for an executable file.
+	 */
+	mode?: number;
+}

packages/create-fs/src/types/system.ts

@@ -0,0 +1,30 @@
+export interface DirectoryChild {
+	name: string;
+	type: "directory" | "file";
+}
+
+export type ReadDirectory = (filePath: string) => Promise<string[]>;
+
+export type ReadFile = (filePath: string) => Promise<string>;
+
+export interface ReadingFileSystem {
+	readDirectory: ReadDirectory;
+	readFile: ReadFile;
+}
+
+export type WriteDirectory = (directoryPath: string) => Promise<void>;
+
+export type WriteFile = (
+	filePath: string,
+	contents: string,
+	options?: WriteFileOptions,
+) => Promise<void>;
+
+export interface WriteFileOptions {
+	mode?: number;
+}
+
+export interface WritingFileSystem extends ReadingFileSystem {
+	writeDirectory: WriteDirectory;
+	writeFile: WriteFile;
+}

packages/create-fs/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src"
+	},
+	"extends": "../../tsconfig.base.json",
+	"include": ["src"]
+}

packages/create-fs/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineProject } from "vitest/config";
+
+export default defineProject({
+	test: {
+		clearMocks: true,
+		exclude: ["lib", "node_modules"],
+	},
+});

packages/create-testers/package.json

@@ -24,13 +24,17 @@
 		"build": "tsc"
 	},
 	"dependencies": {
-		"octokit": "^4.1.0"
+		"diff": "^7.0.0",
+		"octokit": "^4.1.0",
+		"without-undefined-properties": "^0.1.1"
 	},
 	"devDependencies": {
+		"@types/diff": "^7.0.0",
 		"zod": "3.24.1"
 	},
 	"peerDependencies": {
-		"create": "workspace:^"
+		"create": "workspace:^",
+		"create-fs": "workspace:^"
 	},
 	"engines": {
 		"node": ">=18"

packages/create-testers/src/createMockSystems.ts

@@ -1,4 +1,5 @@
-import { NativeSystem, TakeInput, WritingFileSystem } from "create";
+import { NativeSystem, TakeInput } from "create";
+import { WritingFileSystem } from "create-fs";
 import { Octokit } from "octokit";
 
 import { MockSystemOptions } from "./types.js";
@@ -20,6 +21,7 @@ export function createMockSystems(
 	};
 
 	const fs: WritingFileSystem = {
+		readDirectory: createFailingFunction("fs.readDirectory", "an input"),
 		readFile: createFailingFunction("fs.readFile", "an input"),
 		writeDirectory: createFailingFunction("fs.writeDirectory", "an input"),
 		writeFile: createFailingFunction("fs.writeFile", "an input"),