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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/workspace",
-  "version": "0.0.1-dev.125",
+  "version": "0.0.1-dev.5",
   "description": "Workspace and project model primitives for monorepo tooling",
   "keywords": [
     "typescript",
@@ -10,15 +10,6 @@
     "tsconfig",
     "decohere"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/workspace#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/workspace"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -33,9 +24,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.125",
-    "@decohere/crucible": "0.0.1-dev.125",
-    "@decohere/devkit": "0.0.1-dev.125",
+    "@decohere/di": "0.0.1-dev.5",
+    "@decohere/core": "0.0.1-dev.5",
     "picomatch": "^4.0.4",
     "rxjs": "^7.8.2",
     "typescript": "^6.0.3"

package/src/const.ts

@@ -0,0 +1,19 @@
+export const TS_CONFIG = "tsconfig.json";
+export const PACKAGE_JSON = "package.json";
+export const NODE_MODULES = "node_modules";
+export const FIXTURES = "__fixtures__";
+export const WORKSPACE_CONFIG = ".decohere.js";
+export const PROJECTS_DIR = "projects";
+
+import type { WorkspaceOptions } from "./models/workspace-config.type.js";
+
+export const WorkspaceDefaults: WorkspaceOptions = {
+	rootDir: "./",
+	outDir: "dist",
+	includeProjects: [`${PROJECTS_DIR}/**/${PACKAGE_JSON}`],
+	ignoreProjects: [`**/${NODE_MODULES}/**`, `**/${FIXTURES}/**`, "**/dist/**"],
+	include: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+	ignore: ["**/*.d.ts", "**/*.d.mts", "**/*.d.cts", `**/${NODE_MODULES}/**`],
+	copyFiles: [],
+	configurations: [{ name: "debug" }],
+};

package/src/errors.ts

@@ -0,0 +1 @@
+export class WorkspaceConfigurationError extends Error {}

package/src/factories/config.factory.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { cache } from "@decohere/core/caching";
+import { io } from "@decohere/core/io";
+import { WORKSPACE_CONFIG } from "../const.js";
+import type { WorkspaceOptions } from "../models/workspace-config.type.js";
+
+class ConfigFactory {
+	@cache()
+	public async getUserConfig(configFile?: string): Promise<Partial<WorkspaceOptions>> {
+		const file = configFile ?? WORKSPACE_CONFIG;
+		if (!file || !(await io.fileExists(file))) {
+			return {} as WorkspaceOptions;
+		}
+		const fileUrl = pathToFileURL(path.resolve(file)).href;
+		const conf = (await import(fileUrl)).default as Partial<WorkspaceOptions>;
+		return conf;
+	}
+}
+
+export const UserConfigFactory = new ConfigFactory();

package/src/factories/find-workspace-root.ts

@@ -0,0 +1,32 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { PACKAGE_JSON, PROJECTS_DIR } from "../const.js";
+
+/**
+ * The workspace root for a command run from `startDir`: the nearest directory at or above
+ * it with a `package.json` and a `projects/` folder. Falls back to `startDir`, so running
+ * from a package directory (`projects/api`) still sees the whole workspace.
+ */
+export function findWorkspaceRoot(startDir: string): string {
+	const start = path.resolve(startDir);
+	let dir = start;
+	for (;;) {
+		if (
+			existsSync(path.join(dir, PACKAGE_JSON)) &&
+			isDirectory(path.join(dir, PROJECTS_DIR))
+		) {
+			return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return start;
+		dir = parent;
+	}
+}
+
+function isDirectory(fullPath: string): boolean {
+	try {
+		return statSync(fullPath).isDirectory();
+	} catch {
+		return false;
+	}
+}

package/src/factories/project.factory.ts

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { type FileEx, io } from "@decohere/core/io";
+import { merge } from "@decohere/core/objects";
+import { WorkspaceConfigurationError } from "../errors.js";
+import { PackageJson } from "../models/package-json.model.js";
+import { Project, type ProjectConfig, type ProjectSeed } from "../models/project.model.js";
+import type { WorkspaceOptions } from "../models/workspace-config.type.js";
+
+export class ProjectFactory {
+	public static async getProjectSeeds(config: WorkspaceOptions) {
+		const { includeProjects, ignoreProjects, rootDir } = config;
+		const cwd = rootDir ?? "./";
+
+		const discoveredPackageJsonFiles = await io.findFiles(includeProjects, {
+			cwd,
+			ignore: ignoreProjects,
+		});
+		const packageJsonFiles = ProjectFactory.filterNestedPackageJsonFiles(
+			discoveredPackageJsonFiles,
+		);
+		const projects = await Promise.all(
+			packageJsonFiles.map((file) => ProjectFactory.projectFrom(file, config)),
+		);
+
+		return projects.sort((a, b) => a.name.localeCompare(b.name));
+	}
+
+	private static filterNestedPackageJsonFiles(files: readonly FileEx[]) {
+		const normalize = (filePath: string) => filePath.replaceAll("\\", "/");
+		const packageJsonSet = new Set(files.map((file) => normalize(file.relativePath)));
+
+		return files.filter((file) => {
+			const relativePath = normalize(file.relativePath);
+			const projectDir = path.posix.dirname(relativePath);
+			let dir = path.posix.dirname(projectDir);
+			while (dir !== "." && dir !== "/") {
+				if (packageJsonSet.has(`${dir}/package.json`)) {
+					return false;
+				}
+				dir = path.posix.dirname(dir);
+			}
+
+			return true;
+		});
+	}
+
+	public static async getProjects(config: WorkspaceOptions, configuration?: string) {
+		const seeds = await ProjectFactory.getProjectSeeds(config);
+		return seeds.map((seed) => new Project(seed.name, seed.config, configuration));
+	}
+
+	private static async projectFrom(
+		file: FileEx,
+		config: WorkspaceOptions,
+	): Promise<ProjectSeed> {
+		const packageJsonData = await io
+			.readJsonFile<PackageJson>(file.fullPath)
+			.catch((error) => {
+				throw new WorkspaceConfigurationError(
+					`Error reading package.json ${file.fullPath}`,
+					error,
+				);
+			});
+		const name = packageJsonData.name;
+		const packageJson = new PackageJson(packageJsonData);
+		const projectDir = path.dirname(file.relativePath);
+		const mergedConfig = merge.withOptions<ProjectConfig>(
+			{ mergeArrays: false },
+			config,
+			config?.projects?.[name] ?? {},
+			{ projectDir, packageJson },
+		);
+		return { name, config: mergedConfig };
+	}
+}

package/src/factories/workspace.factory.ts

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { io } from "@decohere/core/io";
+import { merge } from "@decohere/core/objects";
+import { PACKAGE_JSON, WorkspaceDefaults } from "../const.js";
+import { PackageJson } from "../models/package-json.model.js";
+import { Workspace } from "../models/workspace.model.js";
+import type {
+	WorkspaceFactoryOptions,
+	WorkspaceOptions,
+} from "../models/workspace-config.type.js";
+import { UserConfigFactory } from "./config.factory.js";
+import { ProjectFactory } from "./project.factory.js";
+
+class Factory {
+	public async create(options: WorkspaceFactoryOptions & Partial<WorkspaceOptions> = {}) {
+		const config = await this.getMergedConfig(options);
+		const projectSeeds = await ProjectFactory.getProjectSeeds(config);
+		const packageJson = await this.getPackageJson(config.rootDir ?? "./");
+		const workspace = new Workspace({ packageJson, config, projects: projectSeeds });
+		return workspace;
+	}
+
+	private async getMergedConfig(
+		options: WorkspaceFactoryOptions & Partial<WorkspaceOptions>,
+	): Promise<WorkspaceOptions> {
+		const { configFile, ...rest } = options;
+		const userConfig = await UserConfigFactory.getUserConfig(configFile);
+		return merge.withOptions<WorkspaceOptions>(
+			{ mergeArrays: false },
+			WorkspaceDefaults,
+			userConfig,
+			rest,
+		) as WorkspaceOptions;
+	}
+
+	private async getPackageJson(rootDir: string) {
+		const packageJsonPath = path.join(rootDir, PACKAGE_JSON);
+		if (!(await io.fileExists(packageJsonPath))) return;
+		const data = await io.readJsonFile<Partial<PackageJson>>(packageJsonPath);
+		return new PackageJson(data);
+	}
+}
+
+export const WorkspaceFactory = new Factory();

package/{types/src/index.d.ts → src/index.ts}

@@ -15,4 +15,10 @@ export { sourceExtensions } from "./models/source-extensions.js";
 export type { ProjectFileEvent } from "./models/project-file-event.js";
 export { DEFAULT_COMPILER_OPTIONS, Tsconfig } from "./models/tsconfig.model.js";
 export { Workspace } from "./models/workspace.model.js";
-export type { Configuration, ProjectOptions, UiConfig, WorkspaceFactoryOptions, WorkspaceOptions, } from "./models/workspace-config.type.js";
+export type {
+	Configuration,
+	ProjectOptions,
+	UiConfig,
+	WorkspaceFactoryOptions,
+	WorkspaceOptions,
+} from "./models/workspace-config.type.js";

package/src/models/has-package-json.mixin.ts

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { invalidateMemoize, memoize } from "@decohere/core/caching";
+import { io } from "@decohere/core/io";
+import { PACKAGE_JSON } from "../const.js";
+import { PackageJson } from "./package-json.model.js";
+
+export abstract class HasPackageJson {
+	protected abstract packageJson?: PackageJson;
+	protected abstract get packageJsonDirectory(): string;
+
+	@memoize()
+	public async getPackageJson() {
+		return new PackageJson(
+			await io.readJsonFile(path.join(this.packageJsonDirectory, PACKAGE_JSON)),
+		);
+	}
+
+	public get packageJsonPath() {
+		return path.join(this.packageJsonDirectory, PACKAGE_JSON);
+	}
+
+	public async getVersion() {
+		return (await this.getPackageJson()).version;
+	}
+
+	public async persistPackageJson(packageJson: PackageJson) {
+		await io.writeFile(this.packageJsonPath, packageJson.toJSON());
+		invalidateMemoize.evict(this, HasPackageJson.prototype.getPackageJson);
+	}
+}

package/src/models/has-tsconfig.mixin.ts

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { memoize } from "@decohere/core/caching";
+import { io } from "@decohere/core/io";
+import { TS_CONFIG } from "../const.js";
+import { Tsconfig } from "./tsconfig.model.js";
+
+export abstract class HasTsConfig {
+	protected abstract get tsConfigDirectory(): string;
+	protected abstract get fallbackTsConfigDirectory(): string | undefined;
+
+	@memoize()
+	public async getTsConfig() {
+		for (const configPath of this.tsConfigPaths) {
+			if (await io.fileExists(configPath)) return Tsconfig.parse(configPath);
+		}
+		return Tsconfig.default();
+	}
+
+	@memoize()
+	public getTsConfigSync() {
+		const configPath = this.findTsConfigPath();
+		if (configPath != null) return Tsconfig.parseSync(configPath);
+		return Tsconfig.default();
+	}
+
+	/** First existing `tsconfig.json` on this object, if any. */
+	protected findTsConfigPath(): string | undefined {
+		return this.tsConfigPaths.find((configPath) => HasTsConfig.fileExistsSync(configPath));
+	}
+
+	private get tsConfigPaths(): string[] {
+		const paths = [path.join(this.tsConfigDirectory, TS_CONFIG)];
+		const fallback = this.fallbackTsConfigDirectory;
+		if (fallback != null) {
+			paths.push(path.join(fallback, TS_CONFIG));
+		}
+		return paths;
+	}
+
+	private static fileExistsSync(filePath: string): boolean {
+		try {
+			return fs.statSync(filePath).isFile();
+		} catch {
+			return false;
+		}
+	}
+}

package/src/models/package-aliases.ts

@@ -0,0 +1,130 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { Project } from "./project.model.js";
+import { sourceExtensions } from "./source-extensions.js";
+
+export type PackageAliases = {
+	/** Absolute base for SWC `jsc.paths` / specifier resolution. */
+	baseUrl: string;
+	/** Package-name and `name/*` keys, values relative to `baseUrl`. */
+	paths: Record<string, string[]>;
+};
+
+/**
+ * Convention aliases from workspace packages, then tsconfig `paths` for the same keys.
+ * Prefer `Workspace.getPackageAliases` when a workspace is available.
+ */
+function build(
+	projects: readonly Project[],
+	options: { baseUrl: string; tsconfigPaths?: Record<string, string[]> },
+): PackageAliases {
+	const baseUrl = path.resolve(options.baseUrl);
+	const paths = {
+		...conventionAliasPaths(projects, baseUrl),
+		...options.tsconfigPaths,
+	};
+	return { baseUrl, paths };
+}
+
+/** Bare import specifier that is not relative, absolute, or a node/file URL. */
+function isBareSpecifier(specifier: string): boolean {
+	return (
+		specifier.length > 0 &&
+		!specifier.startsWith(".") &&
+		!specifier.startsWith("/") &&
+		!specifier.startsWith("node:") &&
+		!specifier.startsWith("file:") &&
+		!specifier.startsWith("data:") &&
+		!specifier.startsWith("#")
+	);
+}
+
+/**
+ * Resolve a bare specifier through package aliases (SWC-style `paths`
+ * relative to `baseUrl`) to an absolute `.ts` path. Longest key wins.
+ */
+function resolvePath(
+	specifier: string,
+	paths: Record<string, string[]>,
+	baseUrl: string,
+): string | null {
+	if (!isBareSpecifier(specifier)) return null;
+
+	const resolvedBase = path.resolve(baseUrl);
+	const keys = Object.keys(paths).sort((a, b) => b.length - a.length);
+
+	for (const key of keys) {
+		const target = paths[key]?.[0];
+		if (target == null) continue;
+
+		if (key.endsWith("/*")) {
+			const prefix = key.slice(0, -1);
+			if (!specifier.startsWith(prefix)) continue;
+			const mappedRoot = target.endsWith("/*") ? target.slice(0, -2) : target;
+			const subpath = specifier.slice(prefix.length);
+			return subpathSource(path.resolve(resolvedBase, mappedRoot, subpath));
+		}
+
+		if (specifier === key) {
+			return toTsSourcePath(path.resolve(resolvedBase, target.replace(/\*$/, "")));
+		}
+	}
+
+	return null;
+}
+
+function conventionAliasPaths(
+	projects: readonly Project[],
+	baseUrl: string,
+): Record<string, string[]> {
+	const aliases: Record<string, string[]> = {};
+
+	for (const project of projects) {
+		const name = project.name;
+		if (name.length === 0) continue;
+
+		const entry = path.resolve(project.getSourceEntryPath());
+		// A package with no root entry (only subpaths, like core) gets no bare alias, and its
+		// subpaths resolve under `src/`.
+		const hasEntry = existsSync(entry);
+		if (hasEntry) aliases[name] = [toPosixRelative(baseUrl, entry)];
+		const subpathRoot = hasEntry
+			? path.dirname(entry)
+			: path.resolve(project.rootDir, project.projectDirectory, "src");
+		if (existsSync(subpathRoot)) {
+			aliases[`${name}/*`] = [`${toPosixRelative(baseUrl, subpathRoot)}/*`];
+		}
+		// Subpaths the package exports, mapped to their sources (#518): these can name any file,
+		// not just `<sub>.ts` or `<sub>/index.ts` under the entry's directory.
+		for (const [subpath, source] of Object.entries(project.getSourceExports())) {
+			aliases[`${name}/${subpath.slice(2)}`] = [toPosixRelative(baseUrl, source)];
+		}
+	}
+
+	return aliases;
+}
+
+function toPosixRelative(from: string, to: string): string {
+	const relative = path.relative(from, to);
+	if (relative === "") return ".";
+	return relative.split(path.sep).join("/");
+}
+
+/**
+ * The source file a wildcard subpath names: `<sub>` with a source extension (`.ts`, `.tsx`, or
+ * `.mts`/`.cts` for `.mjs`/`.cjs`), else the `index` source of the directory it names (as
+ * `@pkg/models` is `src/models/index.ts`), else `<sub>.ts` for the caller to report missing.
+ */
+function subpathSource(candidate: string): string {
+	const files = sourceExtensions.candidates(candidate);
+	const directory = candidate.replace(/\.([mc]?[jt]sx?)$/, "");
+	const indexes = sourceExtensions.candidates(path.join(directory, "index"));
+	return [...files, ...indexes].find((file) => existsSync(file)) ?? toTsSourcePath(candidate);
+}
+
+/** A target as a source path: itself when it is one, else its first source candidate. */
+function toTsSourcePath(candidate: string): string {
+	return sourceExtensions.candidates(candidate)[0] ?? `${candidate}.ts`;
+}
+
+export const packageAliases = { build, isBareSpecifier, resolvePath };

package/src/models/package-json.model.ts

@@ -0,0 +1,231 @@
+export type RepositoryReference =
+	| string
+	| {
+			type?: string;
+			url?: string;
+			directory?: string;
+	  };
+
+export type PackageExports = string | { [key: string]: PackageExports };
+
+type ParsedRepository = {
+	owner: string;
+	name: string;
+};
+
+export class PackageJson {
+	private static readonly PACKAGE_JSON_KEY_ORDER = [
+		"$schema",
+		"name",
+		"displayName",
+		"version",
+		"description",
+		"keywords",
+		"homepage",
+		"bugs",
+		"repository",
+		"license",
+		"author",
+		"contributors",
+		"funding",
+		"type",
+		"main",
+		"module",
+		"types",
+		"exports",
+		"files",
+		"bin",
+		"man",
+		"directories",
+		"scripts",
+		"dependencies",
+		"devDependencies",
+		"peerDependencies",
+		"peerDependenciesMeta",
+		"optionalDependencies",
+		"bundledDependencies",
+		"engines",
+		"os",
+		"cpu",
+		"private",
+		"publishConfig",
+		"workspaces",
+		"packageManager",
+		"forge",
+	] as const;
+
+	public constructor(data?: Partial<PackageJson>) {
+		Object.assign(this, data);
+		this.dependencies = this.dependencies ?? {};
+		this.devDependencies = this.devDependencies ?? {};
+	}
+
+	public sort(): this {
+		const sorted = this.toSortedPackageJsonRecord();
+		Object.assign(this, sorted);
+		return this;
+	}
+
+	public withVersion(version: string): PackageJson {
+		return new PackageJson({ ...this, version });
+	}
+
+	public withDependencies(dependencies: Record<string, string>): PackageJson {
+		return new PackageJson({ ...this, dependencies });
+	}
+
+	public withDevDependencies(devDependencies: Record<string, string>): PackageJson {
+		return new PackageJson({ ...this, devDependencies });
+	}
+
+	public toJSON(): string {
+		return `${JSON.stringify(this.toSortedPackageJsonRecord(), null, 2)}\n`;
+	}
+
+	public getRepositoryOwner() {
+		return this.parseRepository()?.owner;
+	}
+
+	public getRepositoryName() {
+		return this.parseRepository()?.name;
+	}
+
+	public getRepositoryFullName() {
+		const parsed = this.parseRepository();
+		if (parsed == null) {
+			return undefined;
+		}
+
+		return `${parsed.owner}/${parsed.name}`;
+	}
+
+	private sortDependencyMap(input: Record<string, string>) {
+		return Object.fromEntries(
+			Object.entries(input).sort(([left], [right]) => left.localeCompare(right, "en")),
+		);
+	}
+
+	private sortPackageJsonKeys(source: Record<string, unknown>) {
+		const sorted = Object.create(null) as Record<string, unknown>;
+
+		for (const key of PackageJson.PACKAGE_JSON_KEY_ORDER) {
+			if (key in source) {
+				sorted[key] = source[key];
+			}
+		}
+
+		const remainingKeys = Object.keys(source)
+			.filter((key) => !PackageJson.PACKAGE_JSON_KEY_ORDER.includes(key as never))
+			.sort();
+
+		for (const key of remainingKeys) {
+			sorted[key] = source[key];
+		}
+
+		return sorted;
+	}
+
+	private toSortedPackageJsonRecord() {
+		const clone = { ...this } as Record<string, unknown>;
+		if (clone.dependencies) {
+			clone.dependencies = this.sortDependencyMap(
+				clone.dependencies as Record<string, string>,
+			);
+		}
+		if (clone.devDependencies) {
+			clone.devDependencies = this.sortDependencyMap(
+				clone.devDependencies as Record<string, string>,
+			);
+		}
+		return this.sortPackageJsonKeys(clone);
+	}
+
+	private repositoryReferenceToString(repository?: RepositoryReference) {
+		if (typeof repository === "string") {
+			return repository;
+		}
+
+		if (repository == null) {
+			return "";
+		}
+
+		return String(repository.url ?? "");
+	}
+
+	private parseRepository(): ParsedRepository | undefined {
+		const repositoryValue = this.repositoryReferenceToString(this.repository);
+		if (repositoryValue === "") {
+			return undefined;
+		}
+
+		const trimmed = repositoryValue.trim();
+
+		if (!trimmed.includes("://") && !trimmed.startsWith("git@")) {
+			const shorthand = /^(?:[a-z0-9-]+:)?([^/\s]+)\/([^\s]+)$/i.exec(trimmed);
+			if (shorthand) {
+				return {
+					owner: shorthand[1].toLowerCase(),
+					name: this.sanitizeRepositoryName(shorthand[2]),
+				};
+			}
+		}
+
+		const ssh = /^git@[^:]+:([^/\s]+)\/([^\s]+)$/i.exec(trimmed);
+		if (ssh) {
+			return {
+				owner: ssh[1].toLowerCase(),
+				name: this.sanitizeRepositoryName(ssh[2]),
+			};
+		}
+
+		const urlRepository = this.parseRepositoryFromUrl(trimmed);
+		if (urlRepository != null) {
+			return urlRepository;
+		}
+
+		return undefined;
+	}
+
+	private parseRepositoryFromUrl(repository: string): ParsedRepository | undefined {
+		const normalized = repository.replace(/^git\+/, "");
+		let url: URL;
+		try {
+			url = new URL(normalized);
+		} catch {
+			return undefined;
+		}
+
+		const segments = url.pathname.split("/").filter(Boolean);
+		if (segments.length < 2) {
+			return undefined;
+		}
+
+		const owner = segments[0]?.toLowerCase();
+		const name = this.sanitizeRepositoryName(segments[1] ?? "");
+		if (owner == null || owner === "" || name === "") {
+			return undefined;
+		}
+
+		return {
+			owner,
+			name,
+		};
+	}
+
+	private sanitizeRepositoryName(name: string) {
+		return name.replace(/\.git$/i, "").toLowerCase();
+	}
+
+	public readonly name: string;
+	public version: string;
+	public readonly repository?: RepositoryReference;
+	public readonly main: string;
+	/** `exports` as written in package.json: a path, or a map of subpaths (values may be condition maps). */
+	public readonly exports?: PackageExports;
+	public readonly peerDependencies?: Record<string, string>;
+	public readonly optionalDependencies?: Record<string, string>;
+	public readonly scripts: Record<string, string>;
+	public dependencies: Record<string, string> = {};
+	public devDependencies: Record<string, string> = {};
+	public readonly private?: boolean;
+}