@jakubmazanec/carson 0.1.0-c5ebb6f → 0.1.0-next.336fe21

package/src/workspace/WorkspaceDependency.ts

@@ -0,0 +1,18 @@
+import {type WorkspaceDependencyProject} from './WorkspaceDependencyProject.js';
+
+/**
+ * Dependency is an external piece of software (e.g. a package) that is installed in a {@link Workspace | a workspace} and usually required by one or more of its {@link Project | projects}.
+ */
+export type WorkspaceDependency = {
+  /** Dependency name. */
+  name: string;
+
+  /** List of SemVer version ranges of the dependency that are installed in the workspace. */
+  versions: string[];
+
+  /** List of exact versions of the dependency that are installed in the workspace. */
+  exactVersions: string[];
+
+  /** Collection of projects that require the dependency. */
+  projects: WorkspaceDependencyProject[];
+};

package/src/workspace/WorkspaceDependencyProject.ts

@@ -0,0 +1,13 @@
+/**
+ * Type alias for {@link WorkspaceDependency.projects | WorkspaceDependency.projects} property.
+ */
+export type WorkspaceDependencyProject = {
+  /** Project name. */
+  name: string;
+
+  /** SemVer version range of the dependency that is actually is actually required by the project. */
+  version: string;
+
+  /** Exact version of the dependency that is actually is actually required by the project. */
+  exactVersion: string;
+};

package/src/workspace/WorkspaceError.ts

@@ -1,15 +1,24 @@
 import {createCustomErrorWithData} from '@jakubmazanec/error';
 import {type ZodIssue} from 'zod';
 
+/**
+ * A subclass of `Error` that indicates a workspace failure.
+ */
 export const WorkspaceError = createCustomErrorWithData(
   'WorkspaceError',
   {
-    // MISSING_NAME_FIELD: 'No "name" field in file "{0}".',
     INVALID_PACKAGE_JSON: 'Invalid package.json file "{0}".',
     INVALID_WORKSPACE_CONFIG: 'Invalid workspace config file "{0}".',
     NO_SUCH_WORKSPACE_PATH: 'Workspace path "{0}" doesn\'t exist.',
+    NO_WORKSPACE_FOUND: 'No workspace was found at path "{0}".',
     PATH_MISMATCH:
       'In a single-project workspace, the workspace path must be the same as the project path.',
+    WORKSPACE_PATH_NOT_EMPTY: 'Workspace path "{0}" must be an empty directory.',
+    MISSING_CARSON_TEMPLATE_ID: 'Workspace config "{0}" is missing the Carson template ID.',
+
+    DUPLICATE_PROJECT_NAME: 'Workspace already contains project with name "{0}"',
+    DUPLICATE_PROJECT_PATH: 'Workspace already contains project with path "{0}"',
+    TOO_MANY_PROJECTS: "Workspace can't contain more projects.",
   },
   class WorkspaceErrorData {
     path?: string;

package/src/workspace/WorkspaceFindAndReadOptions.ts

@@ -0,0 +1,6 @@
+/**
+ * {@link Workspace.findAndRead | Workspace.findAndRead} options parameter.
+ */
+export type WorkspaceFindAndReadOptions = {
+  throwIfNotFound?: boolean;
+};

package/src/workspace/WorkspaceOptions.ts

@@ -2,18 +2,18 @@ import {type PackageJson} from '@jakubmazanec/zod-utils';
 
 import {type WorkspaceConfig} from './WorkspaceConfig.js';
 import {type WorkspaceError} from './WorkspaceError.js';
-import {type WorkspaceOptionsProjectOptions} from './WorkspaceOptionsProjectOptions.js';
+import {type WorkspaceOptionsProject} from './WorkspaceOptionsProject.js';
 import {type WorkspaceRepository} from './WorkspaceRepository.js';
 
 /**
- * New workspace options.
+ * {@link Workspace.constructor | Workspace constructor} options parameter.
  */
 export type WorkspaceOptions<M extends boolean> = M extends true
   ? {
       path: string;
       isMultiProject?: M;
       projectGlobs?: string[];
-      projects?: WorkspaceOptionsProjectOptions[];
+      projects?: WorkspaceOptionsProject[];
       config?: WorkspaceConfig;
       packageJson?: PackageJson;
       repository?: WorkspaceRepository;
@@ -22,7 +22,7 @@ export type WorkspaceOptions<M extends boolean> = M extends true
   : {
       path: string;
       isMultiProject?: M;
-      projects?: [WorkspaceOptionsProjectOptions];
+      projects?: [WorkspaceOptionsProject];
       config?: WorkspaceConfig;
       repository?: WorkspaceRepository;
       errors?: Array<InstanceType<typeof WorkspaceError>>;

package/src/workspace/{WorkspaceOptionsProjectOptions.ts → WorkspaceOptionsProject.ts}

@@ -2,7 +2,10 @@ import {type PackageJson} from '@jakubmazanec/zod-utils';
 
 import {type ProjectConfig} from './ProjectConfig.js';
 
-export type WorkspaceOptionsProjectOptions = {
+/**
+ * Type alias for {@link WorkspaceOptions.projects | WorkspaceOptions.projects} property.
+ */
+export type WorkspaceOptionsProject = {
   path: string;
   config?: ProjectConfig;
   packageJson?: PackageJson;

package/src/workspace/WorkspacePackageJson.ts

@@ -1,3 +1,6 @@
 import {type PackageJson} from '@jakubmazanec/zod-utils';
 
+/**
+ * Type alias for {@link Workspace.packageJson | Workspace.packageJson} property.
+ */
 export type WorkspacePackageJson<M extends boolean> = M extends true ? PackageJson : null;

package/src/workspace/WorkspaceProjectGlobs.ts

@@ -1 +1,4 @@
+/**
+ * Type alias for {@link Workspace.projectGlobs | Workspace.projectGlobs} property.
+ */
 export type WorkspaceProjectGlobs<M extends boolean> = M extends true ? string[] : null;

package/src/workspace/WorkspaceProjects.ts

@@ -1,3 +1,6 @@
 import {type Project} from './Project.js';
 
+/**
+ * Type alias for {@link Workspace.projects | Workspace.projects} property.
+ */
 export type WorkspaceProjects<M extends boolean> = Array<Project<M>>; // TODO: should be `M extends true ? Array<Project<M>> : [Project<M>?]`; change when this is fixed: https://github.com/microsoft/TypeScript/issues/54302

package/src/workspace/WorkspaceRepository.ts

@@ -1,4 +1,7 @@
+/**
+ * A workspace repository.
+ */
 export type WorkspaceRepository = {
   branches: string[];
-  url: string;
+  url?: string;
 };

package/src/workspace/WorkspaceUpdateOptions.ts

@@ -1,3 +1,6 @@
+/**
+ * {@link Workspace.update | Workspace.update} options parameter.
+ */
 export type WorkspaceUpdateOptions = {
   args: Record<string, unknown>;
 };

package/src/workspace/internals/compareProjectPath.ts

@@ -0,0 +1,14 @@
+import {type Project} from '../Project.js';
+
+export function compareProjectPath<M extends boolean = true>(
+  projectA: Project<M>,
+  projectB: Project<M>,
+) {
+  if (projectA.path < projectB.path) {
+    return -1;
+  } else if (projectA.path > projectB.path) {
+    return 1;
+  }
+
+  return 0;
+}

package/src/workspace/internals/compareWorkspaceDependencyProjectName.ts

@@ -0,0 +1,14 @@
+import {type WorkspaceDependencyProject} from '../WorkspaceDependencyProject.js';
+
+export function compareWorkspaceDependencyProjectName(
+  projectA: WorkspaceDependencyProject,
+  projectB: WorkspaceDependencyProject,
+) {
+  if (projectA.name < projectB.name) {
+    return -1;
+  } else if (projectA.name > projectB.name) {
+    return 1;
+  }
+
+  return 0;
+}

package/src/workspace/internals/getRepositoryBranches.ts

@@ -17,6 +17,14 @@ export async function getRepositoryBranches(repositoryPath: string): Promise<str
     repositoryBranches = branchSummary.all.map((branch) =>
       branch.replace(REMOTE_NAME_PREFIX_REGEXP, ''),
     );
+
+    if (!repositoryBranches.length) {
+      branchSummary = await git.branch(['-a']);
+
+      repositoryBranches = branchSummary.all.map((branch) =>
+        branch.replace(REMOTE_NAME_PREFIX_REGEXP, ''),
+      );
+    }
   } catch (error) {
     // no-op
   }

package/src/workspace/internals/getRepositoryUrl.ts

@@ -4,7 +4,6 @@ export async function getRepositoryUrl(repositoryPath: string): Promise<string |
   let repositoryUrl: string | undefined;
 
   try {
-    // load git repo
     let git = simpleGit({
       baseDir: repositoryPath,
       binary: 'git',

package/src/workspace/internals.ts

@@ -1,4 +1,6 @@
+export * from './internals/compareProjectPath.js';
 export * from './internals/compareSemver.js';
+export * from './internals/compareWorkspaceDependencyProjectName.js';
 export * from './internals/getPackageJsonWorkspaces.js';
 export * from './internals/getRepositoryBranches.js';
 export * from './internals/getRepositoryUrl.js';

package/src/workspace/saveProjectConfig.ts

@@ -5,11 +5,19 @@ import {type ProjectConfig} from './ProjectConfig.js';
 import {CARSON_CONFIG_DIRECTORY, PROJECT_CONFIG_FILENAME} from '../constants.js';
 import {prettify} from '../template/internals.js';
 
+/**
+ * {@link saveProjectConfig} options parameter.
+ */
 export type SaveProjectConfigOptions = {
   projectPath: string;
   projectConfig: ProjectConfig;
 };
 
+/**
+ * Saves project configuration to the config file.
+ *
+ * @param options Options.
+ */
 export async function saveProjectConfig({projectPath, projectConfig}: SaveProjectConfigOptions) {
   await fs.ensureDir(path.join(projectPath, CARSON_CONFIG_DIRECTORY));
 

package/src/workspace/saveWorkspaceConfig.ts

@@ -5,11 +5,19 @@ import {type WorkspaceConfig} from './WorkspaceConfig.js';
 import {CARSON_CONFIG_DIRECTORY, WORKSPACE_CONFIG_FILENAME} from '../constants.js';
 import {prettify} from '../template/internals.js';
 
+/**
+ * {@link saveWorkspaceConfig} options parameter.
+ */
 export type SaveWorkspaceConfigOptions = {
   workspacePath: string;
   workspaceConfig: WorkspaceConfig;
 };
 
+/**
+ * Saves workspace configuration to the config file.
+ *
+ * @param options Options.
+ */
 export async function saveWorkspaceConfig({
   workspacePath,
   workspaceConfig,

package/src/workspace.ts

@@ -1,10 +1,22 @@
 export * from './workspace/Project.js';
 export * from './workspace/ProjectConfig.js';
+export * from './workspace/ProjectCreateOptions.js';
 export * from './workspace/ProjectError.js';
+export * from './workspace/ProjectOptions.js';
+export * from './workspace/ProjectUpdateOptions.js';
 export * from './workspace/saveProjectConfig.js';
 export * from './workspace/saveWorkspaceConfig.js';
 export * from './workspace/Workspace.js';
 export * from './workspace/WorkspaceConfig.js';
+export * from './workspace/WorkspaceCreateOptions.js';
+export * from './workspace/WorkspaceCreateProjectOptions.js';
 export * from './workspace/WorkspaceDependencies.js';
 export * from './workspace/WorkspaceError.js';
+export * from './workspace/WorkspaceFindAndReadOptions.js';
+export * from './workspace/WorkspaceOptions.js';
+export * from './workspace/WorkspaceOptionsProject.js';
+export * from './workspace/WorkspacePackageJson.js';
+export * from './workspace/WorkspaceProjectGlobs.js';
+export * from './workspace/WorkspaceProjects.js';
 export * from './workspace/WorkspaceRepository.js';
+export * from './workspace/WorkspaceUpdateOptions.js';

package/dist/workspace/WorkspaceOptionsProjectOptions.js

@@ -1,3 +0,0 @@
-export { };
-
-//# sourceMappingURL=WorkspaceOptionsProjectOptions.js.map

package/dist/workspace/WorkspaceOptionsProjectOptions.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/workspace/WorkspaceOptionsProjectOptions.ts"],"sourcesContent":["import {type PackageJson} from '@jakubmazanec/zod-utils';\n\nimport {type ProjectConfig} from './ProjectConfig.js';\n\nexport type WorkspaceOptionsProjectOptions = {\n  path: string;\n  config?: ProjectConfig;\n  packageJson?: PackageJson;\n};\n"],"names":[],"mappings":"AAAA,WAQE"}