@jakubmazanec/carson 0.1.0-11dd4a3

package/src/workspace/Workspace.ts

@@ -0,0 +1,553 @@
+import {ensureEmptyDirectory, findExistingDirectory, isRootPath} from '@jakubmazanec/fs-utils';
+import {readFile, packageJsonSchema, type PackageJson} from '@jakubmazanec/zod-utils';
+import glob from 'fast-glob';
+import fs from 'fs-extra';
+import json5 from 'json5';
+import path from 'node:path';
+import {z} from 'zod';
+
+import {getPackageJsonWorkspaces, getRepositoryBranches, getRepositoryUrl} from './internals.js';
+import {Project} from './Project.js';
+import {saveWorkspaceConfig} from './saveWorkspaceConfig.js';
+import {workspaceConfigSchema} from './WorkspaceConfig.js';
+import {type WorkspaceConfig} from './WorkspaceConfig.js';
+import {type WorkspaceCreateOptions} from './WorkspaceCreateOptions.js';
+import {type WorkspaceCreateProjectOptions} from './WorkspaceCreateProjectOptions.js';
+import {WorkspaceDependencies} from './WorkspaceDependencies.js';
+import {WorkspaceError} from './WorkspaceError.js';
+import type {WorkspaceOptions} from './WorkspaceOptions.js';
+import {type WorkspacePackageJson} from './WorkspacePackageJson.js';
+import type {WorkspaceProjectGlobs} from './WorkspaceProjectGlobs.js';
+import {type WorkspaceProjects} from './WorkspaceProjects.js';
+import {type WorkspaceRepository} from './WorkspaceRepository.js';
+import {type WorkspaceUpdateOptions} from './WorkspaceUpdateOptions.js';
+import {CARSON_CONFIG_DIRECTORY, WORKSPACE_CONFIG_FILENAME} from '../constants.js';
+import {applyTemplateRenders} from '../template/applyTemplateRenders.js';
+import {renderTemplate} from '../template/renderTemplate.js';
+
+/**
+ * Workspace represent a directory, usually a git repository, that contains {@linkcode Project} instances.
+ *
+ * @typeParam M If true, the workspace is multi-project workspace (so-called "monorepo").
+ */
+export class Workspace<M extends boolean = true> {
+  /** Workspace path. */
+  readonly path: string;
+
+  /** Does the workspace contain a multiple projects? */
+  readonly isMultiProject: M;
+
+  /** Globs used to find projects. */
+  projectGlobs: WorkspaceProjectGlobs<M>;
+
+  /** Workspace projects. */
+  projects: WorkspaceProjects<M>;
+
+  /** Workspace configuration; if it's not found, the default is an empty object. */
+  config: WorkspaceConfig;
+
+  /** Parsed workspace `package.json` file (if the workspace contains multiple projects); if it's not found, the default is an empty object. */
+  packageJson: WorkspacePackageJson<M>;
+
+  /** Workspace git repository. */
+  repository?: WorkspaceRepository;
+
+  /** Dependencies of all projects. */
+  dependencies: WorkspaceDependencies<M> = [] as unknown as WorkspaceDependencies<M>;
+
+  /** Development dependencies of all projects. */
+  devDependencies: WorkspaceDependencies<M> = [] as unknown as WorkspaceDependencies<M>;
+
+  /** All dependencies of all projects and workspace dependencies. */
+  allDependencies: WorkspaceDependencies<M> = [] as unknown as WorkspaceDependencies<M>;
+
+  /** Versions of each dependency. */
+  dependencyVersions: Record<string, string[]> = {};
+
+  /** Errors found during reading from the file system. */
+  errors: Array<InstanceType<typeof WorkspaceError>> = [];
+
+  constructor(options: WorkspaceOptions<M>) {
+    this.path = options.path;
+
+    if (typeof options.isMultiProject === 'undefined' || options.isMultiProject) {
+      this.isMultiProject = true as M;
+
+      let projectGlobOption = (options as WorkspaceOptions<true>).projectGlobs;
+
+      if (projectGlobOption) {
+        this.projectGlobs = projectGlobOption as WorkspaceProjectGlobs<M>;
+      } else {
+        this.projectGlobs = [] as string[] as WorkspaceProjectGlobs<M>;
+      }
+
+      let {projects} = options as WorkspaceOptions<true>;
+
+      if (projects) {
+        this.projects = projects.map(
+          (project) => new Project({...project, workspace: this}),
+        ) as WorkspaceProjects<M>;
+      } else {
+        this.projects = [] as Array<Project<M>> as WorkspaceProjects<M>;
+      }
+
+      let packageJsonOption = (options as WorkspaceOptions<true>).packageJson;
+
+      if (packageJsonOption) {
+        this.packageJson = packageJsonOption as M extends true ? PackageJson : null;
+      } else {
+        let emptyPackageJson: PackageJson = {};
+
+        this.packageJson = emptyPackageJson as M extends true ? PackageJson : null;
+      }
+    } else {
+      this.isMultiProject = false as M;
+      this.projectGlobs = null as M extends true ? string[] : null;
+      this.packageJson = null as M extends true ? PackageJson : null;
+
+      let {projects} = options as WorkspaceOptions<false>;
+
+      if (projects) {
+        this.projects = projects.map(
+          (project) => new Project({...project, workspace: this}),
+        ) as WorkspaceProjects<M>;
+
+        if ((this.projects[0] as Project<false>).path !== this.path) {
+          throw new WorkspaceError('PATH_MISMATCH');
+        }
+      } else {
+        this.projects = [] as Array<Project<M>> as WorkspaceProjects<M>;
+      }
+    }
+
+    let configOption = options.config;
+
+    if (configOption) {
+      this.config = configOption;
+    } else {
+      let emptyWorkspaceConfig: WorkspaceConfig = {};
+
+      this.config = emptyWorkspaceConfig;
+    }
+
+    if (options.repository) {
+      this.repository = options.repository;
+    }
+
+    if (options.errors) {
+      this.errors = options.errors;
+    }
+
+    // add missing project globs
+    if (this.isMultiProject && !(this.projectGlobs as string[]).length) {
+      let packageJsonWorkspaces = getPackageJsonWorkspaces(this.packageJson as PackageJson);
+
+      if (packageJsonWorkspaces) {
+        this.projectGlobs = [...packageJsonWorkspaces] as M extends true ? string[] : null;
+      }
+    }
+
+    this.updateDependencies();
+  }
+
+  /**
+   * Creates new workspace within the file system.
+   *
+   * @param options Options.
+   * @returns The new workspace
+   */
+  static async create({args, path: workspacePath, templateId}: WorkspaceCreateOptions) {
+    // TODO: test that workspace returned by this method has the same value of isMultiProject when the same workspace is after its creation re-read with .read()
+    let workspace = new this({
+      path: workspacePath,
+      config: {
+        template: templateId,
+      },
+    });
+
+    await ensureEmptyDirectory(workspace.path);
+    await saveWorkspaceConfig({
+      workspacePath: workspace.path,
+      workspaceConfig: {template: templateId},
+    });
+
+    let templateRenders = await renderTemplate({
+      templateId,
+      templateData: {
+        workspace,
+        args,
+      },
+    });
+
+    await applyTemplateRenders({
+      templateRenders,
+      path: workspace.path,
+      ignoreCreateStrategies: false,
+      ignoreCheckStrategies: true,
+    });
+
+    return Workspace.read(workspace.path);
+  }
+
+  static async read(workspacePath: string): Promise<Workspace | Workspace<false>> {
+    let resolvedWorkspacePath = path.resolve(workspacePath);
+
+    if (!(await fs.pathExists(resolvedWorkspacePath))) {
+      throw new WorkspaceError('NO_SUCH_WORKSPACE_PATH', {
+        messageParameters: [resolvedWorkspacePath],
+        data: {
+          path: resolvedWorkspacePath,
+        },
+      });
+    }
+
+    // load root package.json
+    let rootPackageJsonPath = path.join(resolvedWorkspacePath, 'package.json');
+    let doesRootPackageJsonExist = await fs.pathExists(rootPackageJsonPath);
+    let rootPackageJson: PackageJson | z.ZodError;
+
+    if (doesRootPackageJsonExist) {
+      rootPackageJson = await readFile(rootPackageJsonPath, packageJsonSchema, {
+        parser: (rawString: string) => json5.parse<unknown>(rawString),
+      });
+    } else {
+      rootPackageJson = {};
+    }
+
+    if (rootPackageJson instanceof z.ZodError) {
+      rootPackageJson = {};
+    }
+
+    // add projects
+    let projectGlobs = getPackageJsonWorkspaces(rootPackageJson);
+
+    // we're dealing with single-project workspace
+    if (!projectGlobs) {
+      let workspace = new this({
+        path: resolvedWorkspacePath,
+        isMultiProject: false,
+      });
+
+      await workspace.read();
+      await workspace.readProjects();
+
+      return workspace;
+    }
+
+    // assemble workspace options
+    let workspace = new this({
+      path: resolvedWorkspacePath,
+      isMultiProject: true,
+      projectGlobs,
+      packageJson: rootPackageJson,
+    });
+
+    await workspace.read();
+    await workspace.readProjects();
+
+    return workspace;
+  }
+
+  /**
+   * Traverses file system up from the search path and tries to find a directory that is a root of a workspace.
+   */
+  static async find(searchPath: string): Promise<string | undefined> {
+    let startingPath = await findExistingDirectory(path.resolve(searchPath));
+    let currentPath = startingPath;
+    let singlePackageWorkspacePath: string | undefined;
+    let multiPackageWorkspacePath: string | undefined;
+
+    while (
+      !(isRootPath(currentPath) || (singlePackageWorkspacePath && multiPackageWorkspacePath))
+    ) {
+      let packageJsonPath = path.join(currentPath, 'package.json');
+      let doesPackageJsonExist = await fs.pathExists(packageJsonPath);
+
+      if (doesPackageJsonExist) {
+        let packageJson = await readFile(packageJsonPath, packageJsonSchema, {
+          parser: (rawString: string) => json5.parse<unknown>(rawString),
+        });
+
+        if (!(packageJson instanceof Error)) {
+          let projectGlobs = getPackageJsonWorkspaces(packageJson);
+
+          if (projectGlobs?.length) {
+            multiPackageWorkspacePath ??= currentPath;
+          } else {
+            singlePackageWorkspacePath ??= currentPath;
+          }
+        }
+      }
+
+      currentPath = path.dirname(currentPath);
+    }
+
+    if (multiPackageWorkspacePath) {
+      return multiPackageWorkspacePath;
+    } else if (singlePackageWorkspacePath) {
+      return singlePackageWorkspacePath;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Traverses file system up from the search path and tries to find and read a workspace.
+   */
+  static async findAndRead(searchPath: string): Promise<Workspace | Workspace<false> | undefined> {
+    let workspacePath = await Workspace.find(searchPath);
+
+    if (workspacePath) {
+      return Workspace.read(workspacePath);
+    }
+
+    return undefined;
+  }
+
+  async read(): Promise<this> {
+    if (!(await fs.pathExists(this.path))) {
+      throw new WorkspaceError('NO_SUCH_WORKSPACE_PATH', {
+        messageParameters: [this.path],
+        data: {
+          path: this.path,
+        },
+      });
+    }
+
+    let errors: Array<InstanceType<typeof WorkspaceError>> = [];
+    let repositoryUrl = await getRepositoryUrl(this.path);
+    let repositoryBranches = await getRepositoryBranches(this.path);
+
+    // load workspace config
+    let workspaceConfigPath = path.join(
+      this.path,
+      CARSON_CONFIG_DIRECTORY,
+      WORKSPACE_CONFIG_FILENAME,
+    );
+    let doesWorkspaceConfigExist = await fs.pathExists(workspaceConfigPath);
+    let workspaceConfig: WorkspaceConfig | z.ZodError;
+
+    if (doesWorkspaceConfigExist) {
+      workspaceConfig = await readFile(workspaceConfigPath, workspaceConfigSchema, {
+        parser: (rawString: string) => json5.parse<unknown>(rawString),
+      });
+    } else {
+      workspaceConfig = {};
+    }
+
+    if (workspaceConfig instanceof z.ZodError) {
+      let zodError = workspaceConfig;
+      let workspaceError = new WorkspaceError('INVALID_WORKSPACE_CONFIG', {
+        messageParameters: [workspaceConfigPath],
+        data: {
+          path: workspaceConfigPath,
+          zodIssues: zodError.issues,
+        },
+      });
+
+      errors.push(workspaceError);
+
+      workspaceConfig = {};
+    }
+
+    if (this.isMultiProject) {
+      // load root package.json
+      let rootPackageJsonPath = path.join(this.path, 'package.json');
+      let doesRootPackageJsonExist = await fs.pathExists(rootPackageJsonPath);
+      let rootPackageJson: PackageJson | z.ZodError;
+
+      if (doesRootPackageJsonExist) {
+        rootPackageJson = await readFile(rootPackageJsonPath, packageJsonSchema, {
+          parser: (rawString: string) => json5.parse<unknown>(rawString),
+        });
+      } else {
+        rootPackageJson = {};
+      }
+
+      if (rootPackageJson instanceof z.ZodError) {
+        let zodError = rootPackageJson;
+        let workspaceError = new WorkspaceError('INVALID_PACKAGE_JSON', {
+          messageParameters: [rootPackageJsonPath],
+          data: {
+            path: rootPackageJsonPath,
+            zodIssues: zodError.issues,
+          },
+        });
+
+        errors.push(workspaceError);
+
+        rootPackageJson = {};
+      }
+
+      let projectGlobs = getPackageJsonWorkspaces(rootPackageJson);
+
+      this.projectGlobs = (projectGlobs ?? []) as WorkspaceProjectGlobs<M>;
+      this.packageJson = rootPackageJson as WorkspacePackageJson<M>;
+      this.config = workspaceConfig;
+      this.errors = errors;
+
+      if (repositoryUrl) {
+        this.repository = {
+          url: repositoryUrl,
+          branches: repositoryBranches ?? [],
+        };
+      }
+
+      await this.readProjects();
+
+      return this;
+    }
+
+    // we're dealing with single-project workspace
+    this.config = workspaceConfig;
+    this.errors = errors;
+
+    if (repositoryUrl) {
+      this.repository = {
+        url: repositoryUrl,
+        branches: repositoryBranches ?? [],
+      };
+    }
+
+    await this.readProjects();
+
+    return this;
+  }
+
+  async update({args}: WorkspaceUpdateOptions): Promise<this> {
+    if (!this.config.template) {
+      throw new Error('Templat ID is missing in the workspace config!');
+    }
+
+    let templateRenders = await renderTemplate({
+      templateId: this.config.template,
+      templateData: {
+        workspace: this,
+        args,
+      },
+    });
+
+    await applyTemplateRenders({
+      templateRenders,
+      path: this.path,
+      ignoreCreateStrategies: true,
+      ignoreCheckStrategies: false,
+    });
+
+    await this.read();
+
+    return this;
+  }
+
+  getProject(projectName: Project<M> | string): Project<M> | undefined {
+    for (let project of this.projects) {
+      if (project.name === projectName || project === projectName) {
+        return project;
+      }
+    }
+
+    return undefined;
+  }
+
+  async createProject({
+    templateId,
+    projectPath,
+    projectName,
+    args,
+  }: WorkspaceCreateProjectOptions): Promise<Project<M>> {
+    if (this.projects.some((project) => projectPath === project.path)) {
+      throw new Error('Project with same path already exists!');
+    }
+
+    if (this.projects.some((project) => projectName === project.name)) {
+      throw new Error('Project with same name already exists!');
+    }
+
+    if (!this.isMultiProject && this.projects.length >= 1) {
+      throw new Error('Only multi-project Workspace can have more than 1 project!');
+    }
+
+    let newProject = await Project.create({
+      templateId,
+      projectPath,
+      projectName,
+      args,
+      workspace: this,
+    });
+
+    this.addProject(newProject);
+
+    return newProject;
+  }
+
+  addProject(newProject: Project<M>): Project<M> {
+    if (this.projects.some((project) => newProject.path === project.path)) {
+      throw new Error('Project with same path already exists!');
+    }
+
+    if (this.projects.some((project) => newProject.name === project.name)) {
+      throw new Error('Project with same name already exists!');
+    }
+
+    if (!this.isMultiProject && this.projects.length >= 1) {
+      throw new Error('Only multi-project Workspace can have more than 1 project!');
+    }
+
+    this.projects.push(newProject);
+    this.sortProjects();
+    this.updateDependencies();
+
+    return newProject;
+  }
+
+  async readProjects(): Promise<Array<Project<M>>> {
+    if (this.projectGlobs) {
+      let projects: Array<Project<M>> = [];
+      let packagePaths = await glob(this.projectGlobs, {
+        cwd: this.path,
+        onlyDirectories: true,
+      });
+
+      for (let packagePath of packagePaths) {
+        let project = await Project.read(path.join(this.path, packagePath), this);
+
+        projects.push(project);
+      }
+
+      this.projects = projects;
+    } else {
+      this.projects = [await Project.read(this.path, this)];
+    }
+
+    this.sortProjects();
+    this.updateDependencies();
+
+    return this.projects;
+  }
+
+  private sortProjects(): void {
+    this.projects.sort((projectA, projectB) => {
+      if (projectA.path < projectB.path) {
+        return -1;
+      } else if (projectA.path > projectB.path) {
+        return 1;
+      }
+
+      return 0;
+    });
+  }
+
+  private updateDependencies(): void {
+    this.dependencies = WorkspaceDependencies.fromWorkspace(this);
+    this.devDependencies = WorkspaceDependencies.fromWorkspace(this, {
+      includeOnlyDevDependencies: true,
+    });
+    this.allDependencies = WorkspaceDependencies.fromWorkspace(this, {
+      includeDevDependencies: true,
+      includeWorkspaceDependencies: true,
+    });
+    this.dependencyVersions = this.allDependencies.getVersions({
+      useExactVersions: true,
+    });
+  }
+}

package/src/workspace/WorkspaceConfig.ts

@@ -0,0 +1,9 @@
+import {z} from 'zod';
+
+export const workspaceConfigSchema = z
+  .object({
+    template: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+export type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;

package/src/workspace/WorkspaceCreateOptions.ts

@@ -0,0 +1,5 @@
+export type WorkspaceCreateOptions = {
+  path: string;
+  templateId: string;
+  args: Record<string, unknown>;
+};

package/src/workspace/WorkspaceCreateProjectOptions.ts

@@ -0,0 +1,6 @@
+export type WorkspaceCreateProjectOptions = {
+  templateId: string;
+  projectPath: string;
+  projectName: string;
+  args: Record<string, unknown>;
+};