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

package/src/models/project-file-event.ts

@@ -0,0 +1,9 @@
+import type { FileEx, io } from "@decohere/core/io";
+import type { Project } from "./project.model.js";
+
+export type ProjectFileEvent = {
+	eventName: io.WatchEventName;
+	project: Project;
+	configuration: string;
+	file: FileEx;
+};

package/src/models/project.model.ts

@@ -0,0 +1,340 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { cache, memoize } from "@decohere/core/caching";
+import { mixwith } from "@decohere/core/extensibility";
+import { type FileEx, io, type Watcher } from "@decohere/core/io";
+import picomatch from "picomatch";
+import { Subject } from "rxjs";
+import { WorkspaceConfigurationError } from "../errors.js";
+import { HasPackageJson } from "./has-package-json.mixin.js";
+import { HasTsConfig } from "./has-tsconfig.mixin.js";
+import { type PackageExports, PackageJson } from "./package-json.model.js";
+import type { ProjectFileEvent } from "./project-file-event.js";
+import { sourceExtensions } from "./source-extensions.js";
+import type { Configuration, WorkspaceOptions } from "./workspace-config.type.js";
+
+export type ProjectConfig = {
+	projectDir?: string;
+	packageJson?: PackageJson;
+} & WorkspaceOptions;
+
+export type ProjectSeed = {
+	name: string;
+	config?: ProjectConfig;
+};
+
+export class Project extends mixwith(HasPackageJson, HasTsConfig) {
+	protected packageJson?: PackageJson;
+	readonly #projectFileChangedSubject = new Subject<ProjectFileEvent>();
+	readonly #sourceFiles = new Map<string, FileEx>();
+	readonly #projectConfig: ProjectConfig;
+	readonly #name: string;
+	readonly #projectDirectory: string;
+	readonly #selectedConfiguration: Configuration;
+	#hasLoadedSourceFiles = false;
+	#watcher?: Watcher;
+
+	public constructor(
+		name: string,
+		config: ProjectConfig = {} as ProjectConfig,
+		selectedConfigurationName?: string,
+	) {
+		super();
+		this.#name = name;
+		this.#projectDirectory = config?.projectDir ?? name;
+		this.#projectConfig = config;
+		this.#selectedConfiguration = this.resolveConfiguration(selectedConfigurationName);
+		this.packageJson = config.packageJson ?? new PackageJson();
+	}
+
+	public get name() {
+		return this.#name;
+	}
+
+	public get isPrivate() {
+		return this.packageJson?.private === true;
+	}
+
+	public toString() {
+		return `Project(${this.#name})`;
+	}
+
+	public get projectDirectory() {
+		return this.#projectDirectory;
+	}
+
+	public get projectRoot() {
+		return path.resolve(this.#projectConfig.rootDir ?? "./", this.#projectDirectory);
+	}
+
+	public get configuration() {
+		return this.#selectedConfiguration;
+	}
+
+	protected get packageJsonDirectory(): string {
+		return this.#absoluteProjectDir;
+	}
+
+	protected get tsConfigDirectory(): string {
+		return this.#absoluteProjectDir;
+	}
+
+	protected get fallbackTsConfigDirectory(): string | undefined {
+		return this.#projectConfig.rootDir;
+	}
+
+	public get rootDir(): string {
+		return this.#projectConfig.rootDir ?? "./";
+	}
+
+	get #absoluteProjectDir(): string {
+		return this.projectRoot;
+	}
+
+	public get include() {
+		return this.#selectedConfiguration.include ?? this.#projectConfig.include ?? [];
+	}
+
+	public get ignore() {
+		const baseIgnore = this.#projectConfig.ignore ?? [];
+		const selectedIgnore = this.#selectedConfiguration.ignore ?? [];
+		return [...baseIgnore, ...selectedIgnore];
+	}
+
+	public get copyFiles() {
+		const base = this.#projectConfig.copyFiles ?? [];
+		const selected = this.#selectedConfiguration.copyFiles ?? [];
+		return [...base, ...selected];
+	}
+
+	public get dockerConfig() {
+		return this.#projectConfig.docker;
+	}
+
+	public get uiConfig() {
+		return this.#projectConfig.ui;
+	}
+
+	public get configurations(): Configuration[] {
+		return this.#projectConfig.configurations ?? [];
+	}
+
+	public get projectFileChanged$() {
+		return this.#projectFileChangedSubject.asObservable();
+	}
+
+	@memoize()
+	public async getAllFiles() {
+		const files = await io.findFiles(this.include, {
+			cwd: this.#absoluteProjectDir,
+			ignore: this.ignore,
+		});
+
+		this.#sourceFiles.clear();
+		for (const file of files) {
+			this.#sourceFiles.set(file.relativePath, file);
+		}
+		this.#hasLoadedSourceFiles = true;
+		return files;
+	}
+
+	public isSourceFile(file: FileEx) {
+		return this.#sourceFiles.has(file.relativePath);
+	}
+
+	public async watch(configuration: string) {
+		if (this.#watcher != null) {
+			return this.#watcher;
+		}
+
+		if (!this.#hasLoadedSourceFiles) {
+			await this.getAllFiles();
+		}
+
+		const watcher = io.watch(this.#absoluteProjectDir, { ignoreInitial: true });
+		this.#watcher = watcher;
+
+		watcher.on(io.WatchEvents.add, (file) => {
+			const fileEx = file as FileEx;
+			this.updateSourceFileCache(io.WatchEvents.add, fileEx);
+			this.#projectFileChangedSubject.next({
+				project: this,
+				configuration,
+				eventName: io.WatchEvents.add,
+				file: fileEx,
+			});
+		});
+
+		watcher.on(io.WatchEvents.change, (file) => {
+			const fileEx = file as FileEx;
+			this.updateSourceFileCache(io.WatchEvents.change, fileEx);
+			this.#projectFileChangedSubject.next({
+				project: this,
+				configuration,
+				eventName: io.WatchEvents.change,
+				file: fileEx,
+			});
+		});
+
+		watcher.on(io.WatchEvents.unlink, (file) => {
+			const fileEx = file as FileEx;
+			this.updateSourceFileCache(io.WatchEvents.unlink, fileEx);
+			this.#projectFileChangedSubject.next({
+				project: this,
+				configuration,
+				eventName: io.WatchEvents.unlink,
+				file: fileEx,
+			});
+		});
+
+		return watcher;
+	}
+
+	public stopWatching() {
+		this.#watcher?.close();
+		this.#watcher = undefined;
+	}
+
+	@cache()
+	public getRootOut() {
+		return path.join(this.getWorkspaceOut(), this.#selectedConfiguration.name);
+	}
+
+	@cache()
+	public getOutDir(target = "") {
+		const targetDir = this.#selectedConfiguration.pack
+			? path.join(this.projectDirectory, target)
+			: path.join(this.projectDirectory);
+
+		const out = path.join(this.getRootOut(), targetDir);
+		return out;
+	}
+
+	public getConfiguration(name: string) {
+		return this.configurations.find((b) => b.name === name);
+	}
+
+	/**
+	 * The package's entry source file. A TypeScript `main` (the workspace convention,
+	 * `src/index.ts`) is used as written. A `main` or `exports["."]` that describes the published
+	 * layout (`index.js`, `./es6/src/index.js`) is mapped back to the source it was built from,
+	 * falling back to `src/index.ts` (#518).
+	 */
+	public getSourceEntryPath(): string {
+		const projectRoot = path.join(this.rootDir, this.projectDirectory);
+		const main = this.packageJson?.main;
+		if (main != null && sourceExtensions.isSource(main)) {
+			return path.join(projectRoot, main);
+		}
+		const exports = this.packageJson?.exports;
+		const root =
+			exports == null
+				? undefined
+				: typeof exports === "string"
+					? exports
+					: (exports["."] ??
+						(Object.keys(exports).some((k) => k.startsWith(".")) ? undefined : exports));
+		for (const built of [root == null ? undefined : firstExportTarget(root), main]) {
+			const fromSrc = built?.match(/(?:^|\/)(src\/.+)$/)?.[1];
+			const source =
+				fromSrc == null ? undefined : sourceFileFor(path.join(projectRoot, fromSrc));
+			if (source != null) return source;
+		}
+		const conventional = path.join(projectRoot, "src/index.ts");
+		if (main == null || existsSync(conventional)) return conventional;
+		return path.join(projectRoot, main);
+	}
+
+	/**
+	 * The source file each subpath in package.json `exports` names, such as `./auth` →
+	 * `<project>/src/auth/auth.extensions.ts` (#518). Exports point at the release layout
+	 * (`./es6/src/auth/auth.extensions.js`); the source is the part from `src/`, with its
+	 * TypeScript extension. Wildcard subpaths, and targets with no such source file, are left out.
+	 */
+	public getSourceExports(): Record<string, string> {
+		const exports = this.packageJson?.exports;
+		if (exports == null || typeof exports === "string") return {};
+		const projectRoot = path.join(this.rootDir, this.projectDirectory);
+		const sources: Record<string, string> = {};
+		for (const [subpath, target] of Object.entries(exports)) {
+			if (!subpath.startsWith("./") || subpath.includes("*")) continue;
+			const built = firstExportTarget(target);
+			const fromSrc = built?.match(/(?:^|\/)(src\/.+)$/)?.[1];
+			if (fromSrc == null) continue;
+			const source = sourceFileFor(path.join(projectRoot, fromSrc));
+			if (source != null) sources[subpath] = source;
+		}
+		return sources;
+	}
+
+	public [Symbol.dispose]() {
+		this.stopWatching();
+	}
+
+	private getWorkspaceOut() {
+		const out = path.join(this.#projectConfig.rootDir ?? "./", this.#projectConfig.outDir);
+		return out;
+	}
+
+	private updateSourceFileCache(eventName: io.WatchEventName, file: FileEx) {
+		if (!this.#hasLoadedSourceFiles) {
+			return;
+		}
+
+		switch (eventName) {
+			case io.WatchEvents.unlink:
+				this.#sourceFiles.delete(file.relativePath);
+				return;
+			case io.WatchEvents.add:
+			case io.WatchEvents.change:
+				if (this.matchesSourcePattern(file.relativePath)) {
+					this.#sourceFiles.set(file.relativePath, file);
+					return;
+				}
+
+				this.#sourceFiles.delete(file.relativePath);
+				return;
+		}
+	}
+
+	private matchesSourcePattern(relativePath: string) {
+		if (picomatch.isMatch(relativePath, this.ignore)) {
+			return false;
+		}
+
+		return picomatch.isMatch(relativePath, this.include);
+	}
+
+	private resolveConfiguration(configurationName?: string): Configuration {
+		const resolvedConfigurationName = configurationName ?? "debug";
+
+		const configuration = this.configurations.find(
+			(c) => c.name === resolvedConfigurationName,
+		);
+		if (configuration == null) {
+			throw new WorkspaceConfigurationError(
+				`Configuration "${resolvedConfigurationName}" was not found for project "${this.name}"`,
+			);
+		}
+
+		return configuration;
+	}
+}
+
+/** The first path an exports value gives, preferring the conditions that name runtime code. */
+function firstExportTarget(value: PackageExports): string | undefined {
+	if (typeof value === "string") return value;
+	for (const condition of ["import", "default", "require", "node", "types"]) {
+		const nested = value[condition];
+		if (nested != null) return firstExportTarget(nested);
+	}
+	return undefined;
+}
+
+/** The TypeScript source a built or declaration path came from, if it exists. */
+function sourceFileFor(builtPath: string): string | undefined {
+	// A declaration names the file its JavaScript sits next to: `x.d.ts` is `x.js`.
+	const declaration = builtPath.match(/^(.*)\.d\.([mc]?)ts$/);
+	const built = declaration == null ? builtPath : `${declaration[1]}.${declaration[2]}js`;
+	return sourceExtensions.candidates(built).find((candidate) => existsSync(candidate));
+}

package/src/models/source-extensions.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+/** TypeScript source extensions a workspace compiles (#518). */
+const SOURCE = [".ts", ".tsx", ".mts", ".cts"] as const;
+
+/** The sources an import's extension can name: `./a.js` is `a.ts` or `a.tsx`, `./a.mjs` is `a.mts`. */
+const SOURCES_FOR: Record<string, readonly string[]> = {
+	".js": [".ts", ".tsx"],
+	".jsx": [".tsx"],
+	".mjs": [".mts"],
+	".cjs": [".cts"],
+	"": [".ts", ".tsx"],
+};
+
+/** Whether a path is a TypeScript source (not a declaration file). */
+function isSource(file: string): boolean {
+	return SOURCE.some((ext) => file.endsWith(ext)) && !/\.d\.[mc]?ts$/.test(file);
+}
+
+/**
+ * The source files a path written in an import (or a built path) could name, most likely first:
+ * itself when it is already a source, else the same stem with each matching source extension.
+ */
+function candidates(file: string): string[] {
+	if (isSource(file)) return [file];
+	const ext = path.extname(file);
+	const known = SOURCES_FOR[ext];
+	if (known == null) return [`${file}.ts`, `${file}.tsx`];
+	const stem = ext === "" ? file : file.slice(0, -ext.length);
+	return known.map((sourceExt) => `${stem}${sourceExt}`);
+}
+
+/** The extension a source builds to: `.mts` to `.mjs`, `.cts` to `.cjs`, the rest to `.js`. */
+function outputExtension(file: string): string {
+	if (file.endsWith(".mts")) return ".mjs";
+	if (file.endsWith(".cts")) return ".cjs";
+	return ".js";
+}
+
+/** The path a source builds to: `a.mts` to `a.mjs`, `a.cts` to `a.cjs`, `a.ts` and `a.tsx` to `a.js`. */
+function outputPath(file: string): string {
+	const ext = path.extname(file);
+	const stem = ext === "" ? file : file.slice(0, -ext.length);
+	return `${stem}${outputExtension(file)}`;
+}
+
+/** Whether a source is CommonJS (`.cts`); everything else compiles as an ES module. */
+function isCommonJs(file: string): boolean {
+	return file.endsWith(".cts");
+}
+
+export const sourceExtensions = {
+	SOURCE,
+	isSource,
+	candidates,
+	outputExtension,
+	outputPath,
+	isCommonJs,
+};

package/src/models/tsconfig.model.ts

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { io } from "@decohere/core/io";
+import ts, { type CompilerOptions } from "typescript";
+import { WorkspaceConfigurationError } from "../errors.js";
+
+const host = ts.sys;
+
+host.readFile = (file) => {
+	return fs.readFileSync(file, { encoding: "utf8" }) as string;
+};
+
+host.readDirectory = (directoryName) => {
+	return fs
+		.readdirSync(directoryName, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name);
+};
+
+export const DEFAULT_COMPILER_OPTIONS: CompilerOptions = {
+	emitDeclarationOnly: true,
+	declaration: true,
+	baseUrl: "./",
+};
+
+export class Tsconfig {
+	public static default() {
+		return new Tsconfig();
+	}
+
+	public static async parse(filePath: string) {
+		if (!(await io.fileExists(filePath))) {
+			throw new WorkspaceConfigurationError(`TSConfig not found ${filePath}`);
+		}
+		const configFileText = await io.readFile(filePath);
+		const result = ts.parseConfigFileTextToJson(filePath, configFileText);
+		if (result.error) {
+			const errorMessage = result.error.messageText.toString();
+			throw new WorkspaceConfigurationError(`Error parsing ${filePath}. ${errorMessage}`);
+		}
+		const dirName = path.resolve(path.dirname(filePath));
+		const configParseResult = ts.parseJsonConfigFileContent(result.config, host, dirName);
+		return new Tsconfig({
+			compilerOptions: configParseResult.options,
+			errors: configParseResult.errors,
+		});
+	}
+
+	public static parseSync(filePath: string) {
+		if (!Tsconfig.fileExistsSync(filePath)) {
+			throw new WorkspaceConfigurationError(`TSConfig not found ${filePath}`);
+		}
+		const configFileText = fs.readFileSync(filePath, "utf8");
+		const result = ts.parseConfigFileTextToJson(filePath, configFileText);
+		if (result.error) {
+			const errorMessage = result.error.messageText.toString();
+			throw new WorkspaceConfigurationError(`Error parsing ${filePath}. ${errorMessage}`);
+		}
+		const dirName = path.resolve(path.dirname(filePath));
+		const configParseResult = ts.parseJsonConfigFileContent(result.config, host, dirName);
+		return new Tsconfig({
+			compilerOptions: configParseResult.options,
+			errors: configParseResult.errors,
+		});
+	}
+
+	private static fileExistsSync(filePath: string): boolean {
+		try {
+			return fs.statSync(filePath).isFile();
+		} catch {
+			return false;
+		}
+	}
+
+	public constructor(data: Partial<Tsconfig> = { compilerOptions: DEFAULT_COMPILER_OPTIONS }) {
+		Object.assign(this, data);
+	}
+
+	public readonly compilerOptions: CompilerOptions;
+	public readonly errors: readonly ts.Diagnostic[];
+}

package/src/models/workspace-config.type.ts

@@ -0,0 +1,57 @@
+/**
+ * Generic configuration for a workspace build profile.
+ * Concrete tools (e.g. @decohere/forge) extend this with tool-specific fields.
+ */
+export type Configuration = {
+	name: string;
+	include?: string[];
+	ignore?: string[];
+	/** Extra globs to copy into the configuration outDir (non-transpiled assets). */
+	copyFiles?: string[];
+	/** If true, the output is packed into a folder per project directory. */
+	pack?: boolean;
+};
+
+export type DockerConfig = {
+	image?: string;
+	dockerfile?: string;
+	buildArgs?: Record<string, string>;
+	secrets?: Record<string, string>;
+	tags?: string[];
+	push?: boolean;
+};
+
+/**
+ * The UI a deployable serves from its API (`withStatic` in `@decohere/http`). `forge package` copies the
+ * UI project's build output into the deployable's `.package/` folder.
+ */
+export type UiConfig = {
+	/** Package name of the UI project, e.g. `@app/shop.web`. */
+	project: string;
+	/** The UI project's build output folder, relative to that project. Defaults to `dist`. */
+	output?: string;
+	/** Where it lands inside `.package/`, which is also the folder the API serves. Defaults to `ui`. */
+	to?: string;
+};
+
+export type WorkspaceFactoryOptions = {
+	rootDir?: string;
+	configFile?: string;
+};
+
+export type ProjectOptions = {
+	include?: string[];
+	ignore?: string[];
+	copyFiles: string[];
+	configurations: Configuration[];
+	docker?: DockerConfig;
+	ui?: UiConfig;
+};
+
+export type WorkspaceOptions = {
+	rootDir?: string;
+	outDir: string;
+	includeProjects: string[];
+	ignoreProjects: string[];
+	projects?: Record<string, Partial<ProjectOptions>>;
+} & ProjectOptions;