@teambit/builder 0.0.551 → 0.0.556

package/dist/artifact/artifact-definition.d.ts

@@ -1,10 +1,45 @@
 export declare type ArtifactDefinition = {
+    /**
+     * name of the artifact.
+     * e.g. a project might utilize two different artifacts for the same typescript compiler, one
+     * that generates ES5 files and another for ES6, this prop helps to distinguish between the two.
+     */
     name: string;
+    /**
+     * aspect id that created the artifact. sometimes it's not the same as the task.id.
+     * e.g. teambit.compilation/compiler executes teambit.typescript/typescript code that generates dists artifacts
+     * the generatedBy in this case is the teambit.typescript/typescript while the task.id is
+     * teambit.compilation/compiler
+     */
     generatedBy?: string;
+    /**
+     * description of the artifact.
+     */
     description?: string;
+    /**
+     * glob patterns of files to include upon artifact creation. minimatch is used to match the patterns.
+     * e.g. ['*.ts', '!foo.ts'] matches all ts files but ignores foo.ts.
+     */
     globPatterns: string[];
+    /**
+     * define the root directory for reading the artifacts from the capsule file system.
+     * the rootDir must be unique per artifacts, otherwise we risk overriding data between artifacts.
+     */
     rootDir?: string;
+    /**
+     * adds a directory prefix for all artifact files.
+     */
     dirPrefix?: string;
+    /**
+     * determine the context of the artifact.
+     * default artifact context is `component`.
+     * "env" is useful when the same file is generated for all components, for example, "preview"
+     * task may create the same webpack file for all components of that env.
+     */
     context?: 'component' | 'env';
+    /**
+     * storage resolver. can be used to replace where artifacts are stored.
+     * default resolver persists artifacts on scope. (not recommended for large files!)
+     */
     storageResolver?: string;
 };

package/dist/artifact/artifact-factory.d.ts

@@ -17,5 +17,8 @@ export declare class ArtifactFactory {
     private getStorageResolver;
     private toComponentMap;
     private getRootDir;
+    /**
+     * generate artifacts from a build context according to the spec defined in the artifact definitions.
+     */
     generate(context: BuildContext, defs: ArtifactDefinition[], task: BuildTask): ComponentMap<ArtifactList>;
 }

package/dist/artifact/artifact-list.d.ts

@@ -7,11 +7,20 @@ export declare type ResolverMap = {
 export declare class ArtifactList {
     readonly artifacts: Artifact[];
     constructor(artifacts: Artifact[]);
+    /**
+     * return an array of artifact objects.
+     */
     toArray(): Artifact[];
+    /**
+     * group artifacts by the storage resolver.
+     */
     groupByResolver(): ResolverMap;
     toObject(): ArtifactObject[];
     groupByTaskId(): {
         [key: string]: Artifact;
     };
+    /**
+     * store all artifacts using the configured storage resolvers.
+     */
     store(component: Component): Promise<void[]>;
 }

package/dist/artifact/artifact.d.ts

@@ -3,17 +3,68 @@ import type { BuildTask } from '../build-task';
 import type { StorageResolver } from '../storage';
 import type { ArtifactDefinition } from './artifact-definition';
 export declare class Artifact {
+    /**
+     * definition of the artifact.
+     */
     readonly def: ArtifactDefinition;
+    /**
+     * storage resolver. can be used to replace where artifacts are stored.
+     */
     readonly storageResolver: StorageResolver;
     readonly files: ArtifactFiles;
+    /**
+     * join this with `this.paths` to get the absolute paths
+     */
     readonly rootDir: string;
+    /**
+     * the declaring task.
+     * todo: change this to taskDescriptor that has only the metadata of the task, so it could be
+     * saved into the model.
+     */
     readonly task: BuildTask;
+    /**
+     * timestamp of the artifact creation.
+     */
     readonly timestamp: number;
-    constructor(def: ArtifactDefinition, storageResolver: StorageResolver, files: ArtifactFiles, rootDir: string, task: BuildTask, timestamp?: number);
+    constructor(
+    /**
+     * definition of the artifact.
+     */
+    def: ArtifactDefinition, 
+    /**
+     * storage resolver. can be used to replace where artifacts are stored.
+     */
+    storageResolver: StorageResolver, files: ArtifactFiles, 
+    /**
+     * join this with `this.paths` to get the absolute paths
+     */
+    rootDir: string, 
+    /**
+     * the declaring task.
+     * todo: change this to taskDescriptor that has only the metadata of the task, so it could be
+     * saved into the model.
+     */
+    task: BuildTask, 
+    /**
+     * timestamp of the artifact creation.
+     */
+    timestamp?: number);
     get storage(): StorageResolver;
+    /**
+     * name of the artifact.
+     */
     get name(): string;
+    /**
+     * description of the artifact.
+     */
     get description(): string | undefined;
+    /**
+     * aspect id (string) that generated the artifact
+     */
     get generatedBy(): string;
+    /**
+     * archive all artifact files into a tar.
+     */
     tar(): void;
     toObject(): ArtifactObject;
 }

package/dist/build-pipe.d.ts

@@ -8,14 +8,36 @@ import { TasksQueue } from './tasks-queue';
 import { EnvsBuildContext } from './builder.service';
 import { TaskResultsList } from './task-results-list';
 export declare 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> | undefined;
+    /**
+     * timestamp of start initiation.
+     */
     startTime: number;
+    /**
+     * timestamp of task completion.
+     */
     endTime: number;
 };
 export declare class BuildPipe {
+    /**
+     * array of services to apply on the components.
+     */
     readonly tasksQueue: TasksQueue;
     readonly envsBuildContext: EnvsBuildContext;
     readonly logger: Logger;
@@ -24,7 +46,14 @@ export declare class BuildPipe {
     private failedDependencyTask;
     private longProcessLogger;
     private taskResults;
-    constructor(tasksQueue: TasksQueue, envsBuildContext: EnvsBuildContext, logger: Logger, artifactFactory: ArtifactFactory);
+    constructor(
+    /**
+     * array of services to apply on the components.
+     */
+    tasksQueue: TasksQueue, envsBuildContext: EnvsBuildContext, logger: Logger, artifactFactory: ArtifactFactory);
+    /**
+     * execute a pipeline of build tasks.
+     */
     execute(): Promise<TaskResultsList>;
     private executePreBuild;
     private executeTask;
@@ -32,5 +61,8 @@ export declare class BuildPipe {
     private updateFailedDependencyTask;
     private shouldSkipTask;
     private getBuildContext;
+    /**
+     * create a build pipe from an array of tasks.
+     */
     static from(tasksQueue: TasksQueue, envsBuildContext: EnvsBuildContext, logger: Logger, artifactFactory: ArtifactFactory): BuildPipe;
 }

package/dist/build-pipeline-order.d.ts

@@ -1,4 +1,34 @@
 import { EnvDefinition } from '@teambit/envs';
 import type { TaskSlot } from './builder.main.runtime';
 import { TasksQueue } from './tasks-queue';
+/**
+ * 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 declare function calculatePipelineOrder(taskSlot: TaskSlot, envs: EnvDefinition[], pipeNameOnEnv?: string, tasks?: string[], skipTests?: boolean): TasksQueue;

package/dist/build-pipeline-result-list.d.ts

@@ -15,6 +15,9 @@ export declare type AspectData = {
     aspectId: string;
     data: Serializable;
 };
+/**
+ * Helper to get the data and artifacts from the TasksResultsList before saving during the tag
+ */
 export declare class BuildPipelineResultList {
     private tasksResults;
     private components;

package/dist/build-task.d.ts

@@ -6,24 +6,81 @@ import type { ArtifactDefinition } from './artifact';
 import { TaskResultsList } from './task-results-list';
 import { TaskResults } from './build-pipe';
 export declare type TaskLocation = 'start' | 'end';
+/**
+ * delimiter between task.aspectId and task.name
+ */
 export declare const TaskIdDelimiter = ":";
 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[];
 }
 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[];
 }
 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 declare class BuildTaskHelper {

package/dist/builder.main.runtime.d.ts

@@ -41,7 +41,13 @@ export declare class BuilderMain {
     private storeArtifacts;
     private pipelineResultsToBuilderData;
     tagListener(components: Component[], options?: OnTagOpts, isolateOptions?: IsolateComponentsOptions): Promise<OnTagResults>;
+    /**
+     * register a new storage resolver.
+     */
     registerStorageResolver(storageResolver: StorageResolver): this;
+    /**
+     * get storage resolver by name. otherwise, returns default.
+     */
     getStorageResolver(name: string): StorageResolver | undefined;
     getArtifactsVinylByExtension(component: Component, aspectName: string): Promise<ArtifactVinyl[]>;
     getArtifactsVinylByExtensionAndName(component: Component, aspectName: string, name: string): Promise<ArtifactVinyl[]>;
@@ -51,6 +57,12 @@ export declare class BuilderMain {
     getDataByAspect(component: Component, aspectName: string): Serializable | undefined;
     getArtifacts(component: Component): ArtifactObject[] | undefined;
     getBuilderData(component: Component): BuilderData | undefined;
+    /**
+     * build given components for release.
+     * for each one of the envs it runs a series of tasks.
+     * in case of an error in a task, it stops the execution of that env and continue to the next
+     * env. at the end, the results contain the data and errors per env.
+     */
     build(components: Component[], isolateOptions?: IsolateComponentsOptions, builderOptions?: BuilderServiceOptions): Promise<TaskResultsList>;
     runTagTasks(components: Component[], isolateOptions?: IsolateComponentsOptions): Promise<TaskResultsList>;
     runSnapTasks(components: Component[], isolateOptions?: IsolateComponentsOptions): Promise<TaskResultsList>;
@@ -61,9 +73,24 @@ export declare class BuilderMain {
         tagTasks: string[];
         snapTasks: string[];
     };
+    /**
+     * register a build task to apply on all component build pipelines.
+     * build happens on `bit build` and as part of `bit tag --persist`.
+     */
     registerBuildTasks(tasks: BuildTask[]): this;
+    /**
+     * @deprecated use registerTagTasks or registerSnapTasks
+     */
     registerDeployTasks(tasks: BuildTask[]): this;
+    /**
+     * tag tasks that don't get executed on `bit build`, only on `bit tag'.
+     * this pipeline is running once the build-pipeline has completed.
+     */
     registerTagTasks(tasks: BuildTask[]): this;
+    /**
+     * tag tasks that don't get executed on `bit build`, only on `bit snap'.
+     * this pipeline is running once the build-pipeline has completed.
+     */
     registerSnapTasks(tasks: BuildTask[]): this;
     static slots: (((registerFn: () => string) => SlotRegistry<BuildTask>) | ((registerFn: () => string) => SlotRegistry<StorageResolver>))[];
     static runtime: import("@teambit/harmony").RuntimeDefinition;

package/dist/builder.service.d.ts

@@ -33,15 +33,53 @@ export declare type BuilderDescriptor = Array<{
 }>;
 declare type PipeFunctionNames = keyof typeof pipeNames;
 export declare class BuilderService implements EnvService<BuildServiceResults, BuilderDescriptor> {
+    /**
+     * isolator extension.
+     */
     private isolator;
+    /**
+     * logger extension.
+     */
     private logger;
+    /**
+     * task slot (e.g tasks registered by other extensions.).
+     */
     private taskSlot;
+    /**
+     * a method with such name should be implemented on the env in order to run the pipe tasks.
+     */
     private pipeNameOnEnv;
+    /**
+     * pipe name to display on the console during the execution
+     */
     private displayPipeName;
     private artifactFactory;
     private scope;
     name: string;
-    constructor(isolator: IsolatorMain, logger: Logger, taskSlot: TaskSlot, pipeNameOnEnv: PipeFunctionNames, displayPipeName: string, artifactFactory: ArtifactFactory, scope: ScopeMain);
+    constructor(
+    /**
+     * isolator extension.
+     */
+    isolator: IsolatorMain, 
+    /**
+     * logger extension.
+     */
+    logger: Logger, 
+    /**
+     * task slot (e.g tasks registered by other extensions.).
+     */
+    taskSlot: TaskSlot, 
+    /**
+     * a method with such name should be implemented on the env in order to run the pipe tasks.
+     */
+    pipeNameOnEnv: PipeFunctionNames, 
+    /**
+     * pipe name to display on the console during the execution
+     */
+    displayPipeName: string, artifactFactory: ArtifactFactory, scope: ScopeMain);
+    /**
+     * runs all tasks for all envs
+     */
     runOnce(envsExecutionContext: ExecutionContext[], options: BuilderServiceOptions): Promise<TaskResultsList>;
     render(env: EnvDefinition): JSX.Element;
     private renderOnePipe;

package/dist/storage/storage-resolver.d.ts

@@ -4,6 +4,12 @@ export declare type StoreResult = {
     [path: string]: string;
 };
 export interface StorageResolver {
+    /**
+     * name of the storage resolver.
+     */
     name: string;
+    /**
+     * store artifacts in the storage.
+     */
     store(component: Component, artifacts: ArtifactList): Promise<void>;
 }

package/dist/task-results-list.d.ts

@@ -2,10 +2,20 @@ import { TasksQueue } from './tasks-queue';
 import { TaskResults } from './build-pipe';
 export declare class TaskResultsList {
     tasksQueue: TasksQueue;
+    /**
+     * results of all tasks executed in the build pipeline.
+     */
     tasksResults: TaskResults[];
-    constructor(tasksQueue: TasksQueue, tasksResults: TaskResults[]);
+    constructor(tasksQueue: TasksQueue, 
+    /**
+     * results of all tasks executed in the build pipeline.
+     */
+    tasksResults: TaskResults[]);
     hasErrors(): boolean;
     throwErrorsIfExist(): void;
+    /**
+     * group errors from all tasks and show them nicely to the user
+     */
     getErrorMessageFormatted(): string | null;
     private aggregateTaskErrorsToOneString;
 }

package/dist/tasks-queue.d.ts

@@ -6,6 +6,9 @@ declare type EnvTask = {
 };
 export declare class TasksQueue extends Array<EnvTask> {
     toString(): string;
+    /**
+     * make sure tasks names are valid and there are no duplications
+     */
     validate(): void;
     private validateTaskName;
     private validateDuplications;

package/dist/types.d.ts

@@ -6,10 +6,28 @@ export declare type TaskMetadata = {
     [key: string]: Serializable;
 };
 export declare type ComponentResult = {
+    /**
+     * instance of the component
+     */
     component: Component;
+    /**
+     * metadata generated during component build.
+     */
     metadata?: TaskMetadata;
+    /**
+     * returning errors from build tasks will cause a pipeline failure and logs all returned errors.
+     */
     errors?: Array<Error | string>;
+    /**
+     * warnings generated throughout the build task.
+     */
     warnings?: string[];
+    /**
+     * timestamp in milliseconds when the task started
+     */
     startTime?: number;
+    /**
+     * timestamp in milliseconds when the task ended
+     */
     endTime?: number;
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@teambit/builder",
-  "version": "0.0.551",
+  "version": "0.0.556",
   "homepage": "https://bit.dev/teambit/pipelines/builder",
   "main": "dist/index.js",
   "componentId": {
     "scope": "teambit.pipelines",
     "name": "builder",
-    "version": "0.0.551"
+    "version": "0.0.556"
   },
   "dependencies": {
     "p-map-series": "2.1.0",
@@ -22,18 +22,18 @@
     "globby": "11.0.1",
     "@babel/runtime": "7.12.18",
     "core-js": "^3.0.0",
-    "@teambit/component": "0.0.551",
-    "@teambit/envs": "0.0.551",
-    "@teambit/logger": "0.0.467",
-    "@teambit/tester": "0.0.551",
-    "@teambit/isolator": "0.0.551",
-    "@teambit/cli": "0.0.382",
-    "@teambit/workspace": "0.0.551",
-    "@teambit/aspect-loader": "0.0.551",
-    "@teambit/graphql": "0.0.551",
-    "@teambit/scope": "0.0.551",
-    "@teambit/bit-error": "0.0.368",
-    "@teambit/component-id": "0.0.372"
+    "@teambit/component": "0.0.556",
+    "@teambit/envs": "0.0.556",
+    "@teambit/logger": "0.0.472",
+    "@teambit/tester": "0.0.556",
+    "@teambit/isolator": "0.0.556",
+    "@teambit/cli": "0.0.387",
+    "@teambit/workspace": "0.0.556",
+    "@teambit/aspect-loader": "0.0.556",
+    "@teambit/graphql": "0.0.556",
+    "@teambit/scope": "0.0.556",
+    "@teambit/bit-error": "0.0.373",
+    "@teambit/component-id": "0.0.377"
   },
   "devDependencies": {
     "@types/lodash": "4.14.165",
@@ -45,10 +45,10 @@
     "@types/jest": "^26.0.0",
     "@types/react-dom": "^17.0.5",
     "@types/node": "12.20.4",
-    "@teambit/pipelines.aspect-docs.builder": "0.0.101"
+    "@teambit/pipelines.aspect-docs.builder": "0.0.106"
   },
   "peerDependencies": {
-    "@teambit/legacy": "1.0.169",
+    "@teambit/legacy": "1.0.173",
     "react-dom": "^16.8.0 || ^17.0.0",
     "react": "^16.8.0 || ^17.0.0"
   },
@@ -76,12 +76,18 @@
         "react": "-"
       },
       "peerDependencies": {
-        "@teambit/legacy": "1.0.169",
+        "@teambit/legacy": "1.0.173",
         "react-dom": "^16.8.0 || ^17.0.0",
         "react": "^16.8.0 || ^17.0.0"
       }
     }
   },
+  "files": [
+    "dist",
+    "!dist/tsconfig.tsbuildinfo",
+    "README.md",
+    "README.mdx"
+  ],
   "private": false,
   "engines": {
     "node": ">=12.22.0"

package/artifact/artifact-definition.ts

@@ -1,52 +0,0 @@
-export type ArtifactDefinition = {
-  /**
-   * name of the artifact.
-   * e.g. a project might utilize two different artifacts for the same typescript compiler, one
-   * that generates ES5 files and another for ES6, this prop helps to distinguish between the two.
-   */
-  name: string;
-
-  /**
-   * aspect id that created the artifact. sometimes it's not the same as the task.id.
-   * e.g. teambit.compilation/compiler executes teambit.typescript/typescript code that generates dists artifacts
-   * the generatedBy in this case is the teambit.typescript/typescript while the task.id is
-   * teambit.compilation/compiler
-   */
-  generatedBy?: string;
-
-  /**
-   * description of the artifact.
-   */
-  description?: string;
-
-  /**
-   * glob patterns of files to include upon artifact creation. minimatch is used to match the patterns.
-   * e.g. ['*.ts', '!foo.ts'] matches all ts files but ignores foo.ts.
-   */
-  globPatterns: string[];
-
-  /**
-   * define the root directory for reading the artifacts from the capsule file system.
-   * the rootDir must be unique per artifacts, otherwise we risk overriding data between artifacts.
-   */
-  rootDir?: string;
-
-  /**
-   * adds a directory prefix for all artifact files.
-   */
-  dirPrefix?: string;
-
-  /**
-   * determine the context of the artifact.
-   * default artifact context is `component`.
-   * "env" is useful when the same file is generated for all components, for example, "preview"
-   * task may create the same webpack file for all components of that env.
-   */
-  context?: 'component' | 'env';
-
-  /**
-   * storage resolver. can be used to replace where artifacts are stored.
-   * default resolver persists artifacts on scope. (not recommended for large files!)
-   */
-  storageResolver?: string;
-};