feat: update createProject

Author: velut

src/create-project.test.ts

@@ -3,9 +3,10 @@ import fs from "node:fs/promises";
 import { join } from "pathe";
 import { temporaryDirectoryTask } from "tempy";
 import { expect, test } from "vitest";
-import { createProject, type CreateProjectOptions } from "./create-project.ts";
+import { createProject } from "./create-project.ts";
+import type { CreateProjectOptions } from "./types.ts";
 
-const _createProject = (options: CreateProjectOptions) => Effect.runPromise(createProject(options));
+const _createProject = (opts: CreateProjectOptions) => Effect.runPromise(createProject(opts));
 
 test("no cwd", async () => {
 	await temporaryDirectoryTask(async (dir) => {

src/create-project.ts

@@ -1,38 +1,40 @@
-import { Data, Effect } from "effect";
+import { Effect } from "effect";
 import { ModuleKind, ModuleResolutionKind, Project, ScriptTarget } from "ts-morph";
+import { ProjectError } from "./errors.ts";
+import type { CreateProjectOptions, CreateProjectReturn } from "./types.ts";
 
-export type CreateProjectOptions = {
-	indexFilePath: string;
-	cwd: string;
-};
-
-/** @internal */
-export class ProjectError extends Data.TaggedError("ProjectError")<{
-	readonly cause?: unknown;
-}> {}
-
-export const createProject = ({ indexFilePath, cwd }: CreateProjectOptions) =>
-	Effect.try({
-		try: () => {
+export function createProject({ indexFilePath, cwd }: CreateProjectOptions) {
+	return Effect.try({
+		try: (): CreateProjectReturn => {
 			const project = new Project({
 				compilerOptions: {
+					// Include esnext types.
 					// See https://github.com/dsherret/ts-morph/issues/938
 					// and https://github.com/microsoft/TypeScript/blob/master/lib/lib.esnext.full.d.ts
 					lib: ["lib.esnext.full.d.ts"],
+
+					// Set modern target and module resolutions options.
 					target: ScriptTarget.ESNext,
 					module: ModuleKind.ESNext,
 					moduleResolution: ModuleResolutionKind.Bundler,
-					// By default, ts-morph creates a project rooted in the current working directory.
-					// We must change the `typeRoots` directory to the temporary directory
-					// where the packages are installed, otherwise TypeScript will discover
-					// `@types` packages from our local `node_modules` directory.
+
+					// By default, `ts-morph` creates a project rooted in the current working directory
+					// (that is, where this library or an app using it is running).
+					// We must change the `typeRoots` directory to the temporary directory where
+					// the analyzed package is installed, otherwise TypeScript will discover
+					// `@types` packages from our local `node_modules` directory giving
+					// inconsistent analysis results due to available type definitions.
 					// See https://www.typescriptlang.org/tsconfig#typeRoots.
 					typeRoots: [cwd],
 				},
 			});
+
+			// Add index file and resolve module imports.
 			const indexFile = project.addSourceFileAtPath(indexFilePath);
 			project.resolveSourceFileDependencies();
+
 			return { project, indexFile };
 		},
-		catch: (e) => new ProjectError({ cause: e }),
+		catch: (err) => new ProjectError({ cause: err }),
 	});
+}

src/errors.ts

@@ -13,3 +13,6 @@ export class PackageJsonError extends Data.TaggedError("PackageJsonError")<{ cau
 
 /** `PackageTypesError` occurs when the types entry point file for a package cannot be resolved. */
 export class PackageTypesError extends Data.TaggedError("PackageTypesError") {}
+
+/** `ProjectError` occurs when the `ts-morph` project cannot be created. */
+export class ProjectError extends Data.TaggedError("ProjectError")<{ readonly cause?: unknown }> {}

src/types.ts

@@ -288,3 +288,21 @@ export interface WorkDir {
 	/** Cleanup function to remove the directory. */
 	close: () => Promise<void>;
 }
+
+/** `CreateProjectOptions` contains the options for calling {@link createProject}. */
+export interface CreateProjectOptions {
+	/** Path to the types entry point file. */
+	indexFilePath: string;
+
+	/** Directory where the analyzed package is installed. */
+	cwd: string;
+}
+
+/** `CreateProjectReturn` represents the return value of {@link createProject}. */
+export interface CreateProjectReturn {
+	/** `Project` created with `ts-morph`. */
+	project: Project;
+
+	/** `SourceFile` created with `ts-morph` representing the index file. */
+	indexFile: SourceFile;
+}