feat: added project references, with more docs

Author: JoshuaKGoldberg

.prettierignore

@@ -1,3 +1,3 @@
+./cases/
 .all-contributorsrc
 .husky/
-cases/

README.md

@@ -15,12 +15,42 @@
 
 ## Usage
 
+You'll need [hyperfine](https://github.com/sharkdp/hyperfine) installed locally, such as with `brew install hyperfine` or `winget install hyperfine`.
+See [sharkdp/hyperfine#installation](https://github.com/sharkdp/hyperfine#installation).
+
 ```shell
 npm install
 npm generate
 npm measure
 ```
 
+### Measured Attributes
+
+The `caseEntries` values in `src/data.ts` can be modified to test:
+
+- `files`: roughly how many generated files should be linted
+- `layout`: what rough shape of imports those files exhibit:
+  - `"even"`: a single root-level `index.ts` importing from roughly an even triangle shape of files
+  - `"references"`: a single root-level `tsconfig.json` with project references to a few projects
+  - `"wide"`: one root-level `index.ts` importing from all files in the project
+- `singleRun`: whether to enable [single-run inference](https://v8--typescript-eslint.netlify.app/packages/parser#disallowautomaticsingleruninference) as a performance boost
+- `types`: whether to use `parserOptions.project` or `parserOptions.projectService` for typed linting
+
+## Results
+
+Right now, `parserOptions.project` outperforms `parserOptions.projectService`.
+This is a performance issue and we are investigating it as a critical bug for v8.
+
+```plaintext
+┌───────┬──────────────────────┬──────────────────────┬──────────────────────┬──────────────────────┐
+│ files │ project (even)       │ project (references) │ service (even)       │ service (references) │
+┼───────┼──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┤
+│ 128   │ '1.149 s ±  0.030 s' │ '1.135 s ±  0.008 s' │ '1.178 s ±  0.010 s' │ '1.736 s ±  0.012 s' │
+│ 512   │ '1.636 s ±  0.009 s' │ '1.656 s ±  0.004 s' │ '1.895 s ±  0.007 s' │ '2.613 s ±  0.020 s' │
+│ 1024  │ '2.353 s ±  0.013 s' │ '2.399 s ±  0.016 s' │ '3.130 s ±  0.017 s' │ '4.034 s ±  0.061 s' │
+┴───────┴──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┘
+```
+
 ## Contributors
 
 <!-- spellchecker: disable -->

cspell.json

@@ -1,5 +1,5 @@
 {
 	"dictionaries": ["typescript"],
 	"ignorePaths": [".github", "cases", "node_modules"],
-	"words": ["execa", "knip", "packagejson", "tseslint"]
+	"words": ["execa", "knip", "packagejson", "sharkdp", "tseslint", "winget"]
 }

src/creators/createEvenCaseFiles.ts

@@ -0,0 +1,33 @@
+export interface ESLintConfigFileOptions {
+	singleRun: boolean;
+	types: "tsconfig.eslint.json" | "projectService" | true;
+}
+
+export function createESLintConfigFile({
+	singleRun,
+	types,
+}: ESLintConfigFileOptions) {
+	const [projectKey, projectValue] =
+		types === "projectService" ? ["projectService", true] : ["project", types];
+
+	return `
+		import tseslint from "typescript-eslint";
+
+		export default tseslint.config(
+			tseslint.configs.base,
+			{
+				files: ["**/*.ts"],
+				languageOptions: {
+					parserOptions: {
+						${singleRun ? "disallowAutomaticSingleRunInference: true," : ""}
+						${projectKey}: ${typeof projectValue === "string" ? `"${projectValue}"` : projectValue},
+						tsconfigRootDir: import.meta.dirname,
+					},
+				},
+				rules: {
+					"@typescript-eslint/no-floating-promises": "error"
+				}
+			},
+		);
+	`;
+}

src/creators/createProjectsCaseFiles.ts

@@ -0,0 +1,18 @@
+import { NamedCaseData } from "../../data.js";
+
+export function createPackageFile(data: NamedCaseData) {
+	return {
+		devDependencies: {
+			"@eslint/js": "*",
+			eslint: "*",
+			typescript: "*",
+			"typescript-eslint": "rc-v8",
+		},
+		name: data.name,
+		private: true,
+		scripts: {
+			lint: "eslint src",
+		},
+		type: "module",
+	};
+}

src/creators/createWideCaseFiles.ts

@@ -0,0 +1,12 @@
+export function createStandardTSConfigFile() {
+	return {
+		compilerOptions: {
+			module: "NodeNext",
+			noEmit: true,
+			skipLibCheck: true,
+			strict: true,
+			target: "ESNext",
+		},
+		include: ["src"],
+	};
+}

src/creators/files.ts

@@ -0,0 +1,15 @@
+import { CaseData } from "../data.js";
+import { writeStructure } from "../writing/writeStructure.js";
+import { writeEvenCaseFiles } from "./cases/createEvenCaseFiles.js";
+import { createReferencesCaseFiles } from "./cases/createReferencesCaseFiles.js";
+import { writeWideCaseFiles } from "./cases/createWideCaseFiles.js";
+
+const caseFileCreators = {
+	even: writeEvenCaseFiles,
+	references: createReferencesCaseFiles,
+	wide: writeWideCaseFiles,
+};
+
+export async function writeCaseFiles(data: CaseData, directory: string) {
+	return await writeStructure(directory, caseFileCreators[data.layout](data));
+}

src/creators/files/createESLintConfigFile.ts

@@ -3,16 +3,16 @@ export const casesPath = "cases";
 export const caseEntries = [
 	{
 		label: "files",
-		// values: [1, 32, 64, 128, 256, 512, 1024],
-		values: [512, 1024],
+		values: [128, 512, 1024],
 	},
 	{
 		label: "layout",
-		values: ["even" /* , "projects" , "wide" */],
+		// values: ["even" /* , "references" , "wide" */],
+		values: ["even", "references" /* , "wide" */],
 	},
 	{
 		label: "singleRun",
-		values: [false, true],
+		values: [/* false, */ true],
 	},
 	{
 		label: "types",

src/creators/files/createPackageFile.ts

@@ -2,56 +2,27 @@ import { execa } from "execa";
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { createESLintConfigFile, writeCaseFiles } from "./creators/files.js";
+import { writeCaseFiles } from "./creators/writeCaseFiles.js";
+import { createPackageFile } from "./creators/files/createPackageFile.js";
+import { createESLintConfigFile } from "./creators/files/createESLintConfigFile.js";
 import { CaseData, NamedCaseData, caseEntries, casesPath } from "./data.js";
 import { createProjectName } from "./utils.js";
 import { writeFile } from "./writing/writeFile.js";
 
-async function createCase(data: CaseData): Promise<NamedCaseData> {
-	const name = createProjectName(data);
+async function createCase(data: NamedCaseData): Promise<NamedCaseData> {
+	const name = createProjectName({
+		files: data.files,
+		layout: data.layout,
+		singleRun: data.singleRun,
+		types: data.types,
+	});
 	const directory = path.join(casesPath, name);
 
 	console.log(`Populating ${name}...`);
 
 	await fs.mkdir(path.join(directory, "src"), { recursive: true });
 
-	await writeFile(directory, "eslint.config.js", createESLintConfigFile(data));
-
-	await writeFile(
-		directory,
-		"package.json",
-		{
-			devDependencies: {
-				"@eslint/js": "*",
-				eslint: "*",
-				typescript: "*",
-				"typescript-eslint": "rc-v8",
-			},
-			name,
-			private: true,
-			scripts: {
-				lint: "eslint src",
-			},
-			type: "module",
-		},
-		"json",
-	);
-
-	await writeFile(
-		directory,
-		"tsconfig.json",
-		{
-			compilerOptions: {
-				module: "NodeNext",
-				noEmit: true,
-				skipLibCheck: true,
-				strict: true,
-				target: "ESNext",
-			},
-			include: ["src"],
-		},
-		"json",
-	);
+	await writeFile(directory, "package.json", createPackageFile(data), "json");
 
 	console.log("Created", await writeCaseFiles(data, directory), "files");
 
@@ -71,10 +42,10 @@ const cases: NamedCaseData[] = [];
 
 for (const files of caseEntries[0].values) {
 	for (const layout of caseEntries[1].values) {
-		for (const singleRun of caseEntries[2].values) {
-			for (const types of caseEntries[3].values) {
-				cases.push(await createCase({ files, layout, singleRun, types }));
-			}
+		for (const types of caseEntries[3].values) {
+			const data: CaseData = { files, layout, singleRun: true, types };
+			const name = createProjectName(data);
+			cases.push(await createCase({ ...data, name }));
 		}
 	}
 }