@teambit/builder 1.0.107 → 1.0.108

package/build-pipe.ts

@@ -0,0 +1,216 @@
+import { EnvDefinition } from '@teambit/envs';
+import { ComponentMap, ComponentID } from '@teambit/component';
+import { Logger, LongProcessLogger } from '@teambit/logger';
+import mapSeries from 'p-map-series';
+import prettyTime from 'pretty-time';
+import { capitalize } from '@teambit/toolbox.string.capitalize';
+import chalk from 'chalk';
+import { ArtifactFactory, ArtifactList, FsArtifact } from './artifact';
+import { BuildContext, BuildTask, BuildTaskHelper, BuiltTaskResult } from './build-task';
+import { ComponentResult } from './types';
+import { TasksQueue } from './tasks-queue';
+import { EnvsBuildContext } from './builder.service';
+import { TaskResultsList } from './task-results-list';
+
+export type TaskResults = {
+  /**
+   * task itself. useful for getting its id/description later on.
+   */
+  task: BuildTask;
+
+  /**
+   * environment were the task was running
+   */
+  env: EnvDefinition;
+
+  /**
+   * component build results.
+   */
+  componentsResults: ComponentResult[];
+
+  /**
+   * artifacts generated by the build pipeline.
+   * in case the task finished with errors, this prop is undefined.
+   */
+  artifacts: ComponentMap<ArtifactList<FsArtifact>> | undefined;
+
+  /**
+   * timestamp of start initiation.
+   */
+  startTime: number;
+
+  /**
+   * timestamp of task completion.
+   */
+  endTime: number;
+};
+
+type PipeOptions = {
+  exitOnFirstFailedTask?: boolean; // by default it skips only when a dependent failed.
+  showEnvNameInOutput?: boolean;
+  showEnvVersionInOutput?: boolean; // in case it shows the env-name, whether should show also the version
+};
+
+export class BuildPipe {
+  private failedTasks: BuildTask[] = [];
+  private failedDependencyTask: BuildTask | undefined;
+  private longProcessLogger: LongProcessLogger;
+  private taskResults: TaskResults[] = [];
+  constructor(
+    /**
+     * array of services to apply on the components.
+     */
+    readonly tasksQueue: TasksQueue,
+    readonly envsBuildContext: EnvsBuildContext,
+    readonly logger: Logger,
+    readonly artifactFactory: ArtifactFactory,
+    private previousTaskResults?: TaskResults[],
+    private options?: PipeOptions
+  ) {}
+
+  get allTasksResults(): TaskResults[] {
+    return [...(this.previousTaskResults || []), ...(this.taskResults || [])];
+  }
+
+  /**
+   * execute a pipeline of build tasks.
+   */
+  async execute(): Promise<TaskResultsList> {
+    this.addSignalListener();
+    await this.executePreBuild();
+    this.longProcessLogger = this.logger.createLongProcessLogger('running tasks', this.tasksQueue.length);
+    await mapSeries(this.tasksQueue, async ({ task, env }) => this.executeTask(task, env));
+    this.longProcessLogger.end();
+    const capsuleRootDir = Object.values(this.envsBuildContext)[0]?.capsuleNetwork.capsulesRootDir;
+    const tasksResultsList = new TaskResultsList(this.tasksQueue, this.taskResults, capsuleRootDir);
+    await this.executePostBuild(tasksResultsList);
+
+    return tasksResultsList;
+  }
+
+  /**
+   * for some reason, some tasks (such as typescript compilation) ignore ctrl+C. this fixes it.
+   */
+  private addSignalListener() {
+    process.on('SIGTERM', () => {
+      process.exit();
+    });
+
+    process.on('SIGINT', () => {
+      process.exit();
+    });
+  }
+
+  private async executePreBuild() {
+    this.logger.setStatusLine('executing pre-build for all tasks');
+    const longProcessLogger = this.logger.createLongProcessLogger('running pre-build for all tasks');
+    await mapSeries(this.tasksQueue, async ({ task, env }) => {
+      if (!task.preBuild) return;
+      await task.preBuild(this.getBuildContext(env.id));
+    });
+    longProcessLogger.end();
+  }
+
+  private async executeTask(task: BuildTask, env: EnvDefinition): Promise<void> {
+    const taskId = BuildTaskHelper.serializeId(task);
+    const envName = this.options?.showEnvNameInOutput ? `(${this.getPrettyEnvName(env.id)}) ` : '';
+    const taskLogPrefix = `${envName}[${this.getPrettyAspectName(task.aspectId)}: ${task.name}]`;
+    this.longProcessLogger.logProgress(`${taskLogPrefix}${task.description ? ` ${task.description}` : ''}`, false);
+    this.updateFailedDependencyTask(task);
+    if (this.shouldSkipTask(taskId, env.id)) {
+      return;
+    }
+    const startTask = process.hrtime();
+    const taskStartTime = Date.now();
+    const buildContext = this.getBuildContext(env.id);
+    let buildTaskResult: BuiltTaskResult;
+    try {
+      buildTaskResult = await task.execute(buildContext);
+    } catch (err) {
+      this.logger.consoleFailure(`env: ${env.id}, task "${taskId}" threw an error`);
+      throw err;
+    }
+
+    const endTime = Date.now();
+    const compsWithErrors = buildTaskResult.componentsResults.filter((c) => c.errors?.length);
+    let artifacts: ComponentMap<ArtifactList<FsArtifact>> | undefined;
+    const duration = prettyTime(process.hrtime(startTask));
+    if (compsWithErrors.length) {
+      this.logger.consoleFailure(`env: ${env.id}, task "${taskId}" has failed`);
+      this.logger.consoleFailure(
+        chalk.red(`${this.longProcessLogger.getProgress()} env: ${env.id}, task "${taskId}" has failed in ${duration}`)
+      );
+      this.failedTasks.push(task);
+    } else {
+      this.logger.consoleSuccess(
+        chalk.green(`${this.longProcessLogger.getProgress()} ${taskLogPrefix} Completed successfully in ${duration}`)
+      );
+      const defs = buildTaskResult.artifacts || [];
+      artifacts = this.artifactFactory.generate(buildContext, defs, task);
+    }
+
+    const taskResults: TaskResults = {
+      task,
+      env,
+      componentsResults: buildTaskResult.componentsResults,
+      artifacts,
+      startTime: taskStartTime,
+      endTime,
+    };
+
+    this.taskResults.push(taskResults);
+  }
+
+  private getPrettyAspectName(aspectId: string): string {
+    const resolvedId = ComponentID.fromString(aspectId);
+    const tokens = resolvedId.name.split('-').map((token) => capitalize(token));
+    return tokens.join(' ');
+  }
+
+  private getPrettyEnvName(envId: string) {
+    const resolvedId = ComponentID.fromString(envId);
+    const ver = this.options?.showEnvVersionInOutput ? `@${resolvedId.version}` : '';
+    return `${resolvedId.fullName}${ver}`;
+  }
+
+  private async executePostBuild(tasksResults: TaskResultsList) {
+    const longProcessLogger = this.logger.createLongProcessLogger('running post-build for all tasks');
+    this.logger.setStatusLine('executing post-build for all tasks');
+    await mapSeries(this.tasksQueue, async ({ task, env }) => {
+      if (!task.postBuild) return;
+      await task.postBuild(this.getBuildContext(env.id), tasksResults);
+    });
+    longProcessLogger.end();
+  }
+
+  private updateFailedDependencyTask(task: BuildTask) {
+    if (!this.failedDependencyTask && this.failedTasks.length && task.dependencies) {
+      task.dependencies.forEach((dependency) => {
+        const { aspectId, name } = BuildTaskHelper.deserializeIdAllowEmptyName(dependency);
+        this.failedDependencyTask = this.failedTasks.find((failedTask) => {
+          if (name && name !== failedTask.name) return false;
+          return aspectId === failedTask.aspectId;
+        });
+      });
+    }
+  }
+
+  private shouldSkipTask(taskId: string, envId: string): boolean {
+    if (this.options?.exitOnFirstFailedTask && this.failedTasks.length) {
+      const failedTaskId = BuildTaskHelper.serializeId(this.failedTasks[0]);
+      this.logger.consoleWarning(`env: ${envId}, task "${taskId}" has skipped due to "${failedTaskId}" failure`);
+      return true;
+    }
+    if (!this.failedDependencyTask) return false;
+    const failedTaskId = BuildTaskHelper.serializeId(this.failedDependencyTask);
+    this.logger.consoleWarning(`env: ${envId}, task "${taskId}" has skipped due to "${failedTaskId}" failure`);
+    return true;
+  }
+
+  private getBuildContext(envId: string): BuildContext {
+    const buildContext = this.envsBuildContext[envId];
+    if (!buildContext) throw new Error(`unable to find buildContext for ${envId}`);
+    buildContext.previousTasksResults = this.allTasksResults;
+    return buildContext;
+  }
+}

package/build-pipeline-order.ts

@@ -0,0 +1,192 @@
+import { Graph, Node, Edge } from '@teambit/graph.cleargraph';
+import TesterAspect from '@teambit/tester';
+import { EnvDefinition, Environment } from '@teambit/envs';
+import { BuildTask, BuildTaskHelper } from './build-task';
+import type { TaskSlot } from './builder.main.runtime';
+import { TasksQueue } from './tasks-queue';
+import { PipeFunctionNames } from './builder.service';
+
+type TaskDependenciesGraph = Graph<string, string>;
+type Location = 'start' | 'middle' | 'end';
+type TasksLocationGraph = { location: Location; graph: TaskDependenciesGraph };
+type PipelineEnv = { env: EnvDefinition; pipeline: BuildTask[] };
+type DataPerLocation = { location: Location; graph: TaskDependenciesGraph; pipelineEnvs: PipelineEnv[] };
+
+/**
+ * there are two ways how to add tasks to build pipeline.
+ * 1. `getBuildPipe()` method of the env.
+ * 2. registering to the `builder.registerBuildTask()`.
+ *
+ * in the option #1, it's possible to determine the order. e.g. `getBuildPipe() { return [taskA, taskB, taskC]; }`
+ * in the option #2, the register happens once the extension is loaded, so there is no way to put
+ * one task before/after another task.
+ *
+ * To be able to determine the order, you can do the following
+ * 1. "task.location", it has two options "start" and "end". the rest are "middle".
+ * 2. "task.dependencies", the dependencies must be completed for all envs before this task starts.
+ * the dependencies are applicable inside a location and not across locations. see getLocation()
+ * or/and continue reading for more info about this.
+ *
+ * to determine the final order of the tasks, the following is done:
+ * 1. split all tasks to three groups: start, middle and end.
+ * 2. for each group define a dependencies graph for the tasks with "dependencies" prop and the pipeline.
+ * 3. start with the first group "start", toposort the dependencies graph and push the found tasks
+ * to a queue. once completed, iterate the pipeline and add all tasks to the queue.
+ * 4. do the same for the "middle" and "end" groups.
+ *
+ * the reason for splitting the tasks to the three groups and not using the "dependencies" field
+ * alone to determine the order is that the "start" and "end" groups are mostly core and "middle"
+ * is mostly the user entering tasks to the pipeline and we as the core don't know about the users
+ * tasks. For example, a core task "PublishComponent" must happen after the compiler, however, a
+ * user might have an env without a compiler. if we determine the order only by the dependencies
+ * field, the "PublishComponent" would have a dependency "compiler" and because in this case there
+ * is no compiler task, it would throw an error about missing dependencies.
+ */
+export function calculatePipelineOrder(
+  taskSlot: TaskSlot,
+  envs: EnvDefinition[],
+  pipeNameOnEnv: PipeFunctionNames,
+  tasks: string[] = [],
+  skipTests = false
+): TasksQueue {
+  const graphs: TasksLocationGraph[] = [];
+  const locations: Location[] = ['start', 'middle', 'end']; // the order is important here!
+  locations.forEach((location) => {
+    graphs.push({ location, graph: new Graph<string, string>() });
+  });
+  const pipelineEnvs: PipelineEnv[] = [];
+  envs.forEach((envDefinition) => {
+    const pipeline = getPipelineForEnv(taskSlot, envDefinition.env, pipeNameOnEnv);
+    pipelineEnvs.push({ env: envDefinition, pipeline });
+  });
+
+  const flattenedPipeline: BuildTask[] = pipelineEnvs.map((pipelineEnv) => pipelineEnv.pipeline).flat();
+  flattenedPipeline.forEach((task) => addDependenciesToGraph(graphs, flattenedPipeline, task));
+
+  const dataPerLocation: DataPerLocation[] = graphs.map(({ location, graph }) => {
+    const pipelineEnvsPerLocation: PipelineEnv[] = pipelineEnvs.map(({ env, pipeline }) => {
+      return { env, pipeline: pipeline.filter((task) => (task.location || 'middle') === location) };
+    });
+    return { location, graph, pipelineEnvs: pipelineEnvsPerLocation };
+  });
+
+  const tasksQueue = new TasksQueue();
+  locations.forEach((location) => addTasksToGraph(tasksQueue, dataPerLocation, location));
+  if (tasks.length) {
+    return new TasksQueue(
+      ...tasksQueue.filter(({ task }) => tasks.includes(task.name) || tasks.includes(task.aspectId))
+    );
+  }
+  if (skipTests) {
+    return new TasksQueue(...tasksQueue.filter(({ task }) => task.aspectId !== TesterAspect.id));
+  }
+  return tasksQueue;
+}
+
+function addTasksToGraph(tasksQueue: TasksQueue, dataPerLocation: DataPerLocation[], location: Location) {
+  const data = dataPerLocation.find((d) => d.location === location);
+  if (!data) return;
+  const sorted = data.graph.toposort();
+  sorted.forEach((taskNode) => {
+    const { aspectId, name } = BuildTaskHelper.deserializeId(taskNode.attr);
+    data.pipelineEnvs.forEach(({ env, pipeline }) => {
+      const taskIndex = pipeline.findIndex(
+        (pipelineTask) => pipelineTask.aspectId === aspectId && pipelineTask.name === name
+      );
+      if (taskIndex < 0) return;
+      const task = pipeline[taskIndex];
+      tasksQueue.push({ env, task });
+      pipeline.splice(taskIndex, 1); // delete the task from the pipeline
+    });
+  });
+  data.pipelineEnvs.forEach(({ env, pipeline }) => {
+    pipeline.forEach((task) => tasksQueue.push({ env, task }));
+  });
+}
+
+function addDependenciesToGraph(graphs: TasksLocationGraph[], pipeline: BuildTask[], task: BuildTask) {
+  if (!task.dependencies || !task.dependencies.length) return;
+  const taskId = BuildTaskHelper.serializeId(task);
+  task.dependencies.forEach((dependency) => {
+    const { aspectId, name } = BuildTaskHelper.deserializeIdAllowEmptyName(dependency);
+    const dependencyTasks = pipeline.filter((pipelineTask) => {
+      if (pipelineTask.aspectId !== aspectId) return false;
+      return name ? name === pipelineTask.name : true;
+    });
+    if (dependencyTasks.length === 0) {
+      throw new Error(
+        `Pipeline error - missing task dependency "${dependency}" of the "${BuildTaskHelper.serializeId(task)}"`
+      );
+    }
+    dependencyTasks.forEach((dependencyTask) => {
+      const location = getLocation(task, dependencyTask);
+      if (!location) {
+        // the dependency is behind and will be in the correct order regardless the graph.
+        return;
+      }
+      const graphLocation = graphs.find((g) => g.location === location);
+      if (!graphLocation) throw new Error(`unable to find graph for location ${location}`);
+      const dependencyId = BuildTaskHelper.serializeId(dependencyTask);
+      const graph = graphLocation.graph;
+      graph.setNode(new Node(taskId, taskId));
+      graph.setNode(new Node(dependencyId, dependencyId));
+      graph.setEdge(new Edge(dependencyId, taskId, 'dependency'));
+    });
+  });
+}
+
+/**
+ * since the task execution is happening per group: "start", "middle" and "end", the dependencies
+ * need to be inside the same group.
+ * e.g. if a dependency located at "end" group and the task located at "start", it's impossible to
+ * complete the dependency before the task, there it throws an error.
+ * it's ok to have the dependency located earlier, e.g. "start" and the task at "end", and in this
+ * case, it will not be part of the graph because there is no need to do any special calculation.
+ */
+function getLocation(task: BuildTask, dependencyTask: BuildTask): Location | null {
+  const taskLocation = task.location || 'middle';
+  const dependencyLocation = dependencyTask.location || 'middle';
+
+  const isDependencyAhead =
+    (taskLocation === 'start' && dependencyLocation !== 'start') ||
+    (taskLocation === 'middle' && dependencyLocation === 'end');
+
+  const isDependencyEqual = taskLocation === dependencyLocation;
+
+  if (isDependencyAhead) {
+    throw new Error(`a task "${BuildTaskHelper.serializeId(task)}" located at ${taskLocation}
+has a dependency "${BuildTaskHelper.serializeId(dependencyTask)} located at ${dependencyLocation},
+which is invalid. the dependency must be located earlier or in the same location as the task"`);
+  }
+
+  if (isDependencyEqual) {
+    return taskLocation;
+  }
+
+  // dependency is behind. e.g. task is "end" and dependency is "start". no need to enter to the
+  // graph as it's going to be executed in the right order regardless the graph.
+  return null;
+}
+
+function getPipelineForEnv(taskSlot: TaskSlot, env: Environment, pipeNameOnEnv: string): BuildTask[] {
+  const buildTasks: BuildTask[] = env[pipeNameOnEnv] ? env[pipeNameOnEnv]() : [];
+  const slotsTasks = taskSlot.values().flat();
+  const tasksAtStart: BuildTask[] = [];
+  const tasksAtEnd: BuildTask[] = [];
+  slotsTasks.forEach((task) => {
+    if (task.location === 'start') {
+      tasksAtStart.push(task);
+      return;
+    }
+    if (task.location === 'end') {
+      tasksAtEnd.push(task);
+      return;
+    }
+    tasksAtStart.push(task);
+  });
+
+  // merge with extension registered tasks.
+  const mergedTasks = [...tasksAtStart, ...buildTasks, ...tasksAtEnd];
+
+  return mergedTasks;
+}

package/build-pipeline-result-list.ts

@@ -0,0 +1,97 @@
+import { ComponentID, ComponentMap, Component } from '@teambit/component';
+import { isEmpty, compact } from 'lodash';
+import type { ArtifactObject } from '@teambit/legacy/dist/consumer/component/sources/artifact-files';
+import { Artifact, ArtifactList } from './artifact';
+import { TaskResults } from './build-pipe';
+import { TaskMetadata } from './types';
+
+export type PipelineReport = {
+  taskId: string; // task aspect-id
+  taskName: string;
+  taskDescription?: string;
+  startTime?: number;
+  endTime?: number;
+  errors?: Array<Error | string>;
+  warnings?: string[];
+};
+
+export type AspectData = {
+  aspectId: string;
+  data: TaskMetadata;
+};
+
+/**
+ * Helper to get the data and artifacts from the TasksResultsList before saving during the tag
+ */
+export class BuildPipelineResultList {
+  private artifactListsMap: ComponentMap<ArtifactList<Artifact>>;
+  constructor(private tasksResults: TaskResults[], private components: Component[]) {
+    this.artifactListsMap = this.getFlattenedArtifactListsMapFromAllTasks();
+  }
+
+  private getFlattenedArtifactListsMapFromAllTasks(): ComponentMap<ArtifactList<Artifact>> {
+    const artifactListsMaps = this.tasksResults.flatMap((t) => (t.artifacts ? [t.artifacts] : []));
+    return ComponentMap.as<ArtifactList<Artifact>>(this.components, (component) => {
+      const artifacts: Artifact[] = [];
+      artifactListsMaps.forEach((artifactListMap) => {
+        const artifactList = artifactListMap.getValueByComponentId(component.id);
+        if (artifactList) artifacts.push(...artifactList);
+      });
+      return ArtifactList.fromArray(artifacts);
+    });
+  }
+
+  public getMetadataFromTaskResults(componentId: ComponentID): { [taskId: string]: TaskMetadata } {
+    const compResults = this.tasksResults.reduce((acc, current: TaskResults) => {
+      const foundComponent = current.componentsResults.find((c) => c.component.id.isEqual(componentId));
+      const taskId = current.task.aspectId;
+      if (foundComponent && foundComponent.metadata) {
+        acc[taskId] = this.mergeDataIfPossible(foundComponent.metadata, acc[taskId], taskId);
+      }
+      return acc;
+    }, {});
+    return compResults;
+  }
+
+  public getPipelineReportOfComponent(componentId: ComponentID): PipelineReport[] {
+    const compResults = this.tasksResults.map((taskResults: TaskResults) => {
+      const foundComponent = taskResults.componentsResults.find((c) => c.component.id.isEqual(componentId));
+      if (!foundComponent) return null;
+      const pipelineReport: PipelineReport = {
+        taskId: taskResults.task.aspectId,
+        taskName: taskResults.task.name,
+        taskDescription: taskResults.task.description,
+        errors: foundComponent.errors,
+        warnings: foundComponent.warnings,
+        startTime: foundComponent.startTime,
+        endTime: foundComponent.endTime,
+      };
+      return pipelineReport;
+    });
+    return compact(compResults);
+  }
+
+  public getDataOfComponent(componentId: ComponentID): AspectData[] {
+    const tasksData = this.getMetadataFromTaskResults(componentId);
+    return Object.keys(tasksData).map((taskId) => ({
+      aspectId: taskId,
+      data: tasksData[taskId],
+    }));
+  }
+
+  public getArtifactsDataOfComponent(componentId: ComponentID): ArtifactObject[] | undefined {
+    return this.artifactListsMap.getValueByComponentId(componentId)?.toObject();
+  }
+
+  private mergeDataIfPossible(currentData: TaskMetadata, existingData: TaskMetadata | undefined, taskId: string) {
+    if (!existingData || isEmpty(existingData)) return currentData;
+    // both exist
+    if (typeof currentData !== 'object') {
+      throw new Error(`task data must be "object", get ${typeof currentData} for ${taskId}`);
+    }
+    if (Array.isArray(currentData)) {
+      throw new Error(`task data must be "object", get Array for ${taskId}`);
+    }
+    return { ...currentData, ...existingData };
+  }
+}

package/build-task.ts

@@ -0,0 +1,151 @@
+import type { Component } from '@teambit/component';
+import { LaneId } from '@teambit/lane-id';
+import { ExecutionContext } from '@teambit/envs';
+import type { Network } from '@teambit/isolator';
+import type { ComponentResult } from './types';
+import type { ArtifactDefinition } from './artifact';
+import { TaskResultsList } from './task-results-list';
+import { TaskResults } from './build-pipe';
+import { PipeName } from './builder.service';
+
+export type TaskLocation = 'start' | 'end';
+
+/**
+ * delimiter between task.aspectId and task.name
+ */
+export const TaskIdDelimiter = ':';
+
+/**
+ * A folder to write artifacts generated during a build task
+ * This folder is used in the core envs and excluded by default from the package tar file (the core envs is writing this into the npmignore file)
+ */
+export const CAPSULE_ARTIFACTS_DIR = 'artifacts';
+
+export interface BuildContext extends ExecutionContext {
+  /**
+   * all components about to be built/tagged.
+   */
+  components: Component[];
+
+  /**
+   * network of capsules ready to be built.
+   */
+  capsuleNetwork: Network;
+
+  /**
+   * data generated by tasks that were running before this task
+   */
+  previousTasksResults: TaskResults[];
+
+  /**
+   * Run the build pipeline in dev mode
+   */
+  dev?: boolean;
+
+  /**
+   * pipe name such as "build", "tas", "snap".
+   * an example usage is "deploy" task which is running in snap and tag pipeline and has different needs in each one.
+   */
+  pipeName: PipeName;
+
+  /**
+   * current lane-id if exists. empty when on main.
+   */
+  laneId?: LaneId;
+}
+
+export interface TaskDescriptor {
+  aspectId: string;
+  name?: string;
+  description?: string;
+}
+
+export interface BuildTask {
+  /**
+   * aspect id serialized of the creator of the task.
+   * todo: automate this so then it won't be needed to pass manually.
+   */
+  aspectId: string;
+
+  /**
+   * name of the task. function as an identifier among other tasks of the same aspectId.
+   * spaces and special characters are not allowed. as a convention, use UpperCamelCase style.
+   * (e.g. TypescriptCompiler).
+   */
+  name: string;
+
+  /**
+   * description of what the task does.
+   * if available, the logger will log it show it in the status-line.
+   */
+  description?: string;
+
+  /**
+   * where to put the task, before the env pipeline or after
+   */
+  location?: TaskLocation;
+
+  /**
+   * execute a task in a build context
+   */
+  execute(context: BuildContext): Promise<BuiltTaskResult>;
+
+  /**
+   * run before the build pipeline has started. this is useful when some preparation are needed to
+   * be done on all envs before the build starts.
+   * e.g. typescript compiler needs to write the tsconfig file. doing it during the task, will
+   * cause dependencies from other envs to get this tsconfig written.
+   */
+  preBuild?(context: BuildContext): Promise<void>;
+
+  /**
+   * run after the build pipeline completed for all envs. useful for doing some cleanup on the
+   * capsules before the deployment starts.
+   */
+  postBuild?(context: BuildContext, tasksResults: TaskResultsList): Promise<void>;
+
+  /**
+   * needed if you want the task to be running only after the dependencies were completed
+   * for *all* envs.
+   * normally this is not needed because the build-pipeline runs the tasks in the same order
+   * they're located in the `getBuildPipe()` array and according to the task.location.
+   * the case where this is useful is when a task not only needs to be after another task, but also
+   * after all environments were running that task.
+   * a dependency is task.aspectId. if an aspect has multiple tasks, to be more specific, use
+   * "aspectId:name", e.g. "teambit.compilation/compiler:TypescriptCompiler".
+   */
+  dependencies?: string[];
+}
+
+// TODO: rename to BuildTaskResults
+export interface BuiltTaskResult {
+  /**
+   * build results for each of the components in the build context.
+   */
+  componentsResults: ComponentResult[];
+
+  /**
+   * array of artifact definitions to generate after a successful build.
+   */
+  artifacts?: ArtifactDefinition[];
+}
+
+export class BuildTaskHelper {
+  static serializeId({ aspectId, name }: { aspectId: string; name: string }): string {
+    return aspectId + TaskIdDelimiter + name;
+  }
+  static deserializeId(id: string): { aspectId: string; name: string } {
+    const split = id.split(TaskIdDelimiter);
+    if (split.length === 0) throw new Error(`deserializeId, ${id} is empty`);
+    if (split.length === 1) throw new Error(`deserializeId, ${id} has only aspect-id without name`);
+    if (split.length === 2) return { aspectId: split[0], name: split[1] };
+    throw new Error(`deserializeId, id ${id} has more than one ${TaskIdDelimiter}`);
+  }
+  /**
+   * don't throw an error when the id includes only the aspect-id without the task name.
+   * useful for task dependencies, when it's allowed to specify the aspect-id only.
+   */
+  static deserializeIdAllowEmptyName(id: string): { aspectId: string; name?: string } {
+    return id.includes(TaskIdDelimiter) ? BuildTaskHelper.deserializeId(id) : { aspectId: id, name: undefined };
+  }
+}