[heft] Add Heft "Phases" and "Tasks" to Allow for Heavy Customization of Heft Build Flows

.gitignore

@@ -80,3 +80,4 @@ dist
 
 # Heft
 .heft
+.cache

README.md

@@ -51,11 +51,14 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/eslint/eslint-plugin](./eslint/eslint-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Feslint-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Feslint-plugin) | [changelog](./eslint/eslint-plugin/CHANGELOG.md) | [@rushstack/eslint-plugin](https://www.npmjs.com/package/@rushstack/eslint-plugin) |
 | [/eslint/eslint-plugin-packlets](./eslint/eslint-plugin-packlets/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Feslint-plugin-packlets.svg)](https://badge.fury.io/js/%40rushstack%2Feslint-plugin-packlets) | [changelog](./eslint/eslint-plugin-packlets/CHANGELOG.md) | [@rushstack/eslint-plugin-packlets](https://www.npmjs.com/package/@rushstack/eslint-plugin-packlets) |
 | [/eslint/eslint-plugin-security](./eslint/eslint-plugin-security/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Feslint-plugin-security.svg)](https://badge.fury.io/js/%40rushstack%2Feslint-plugin-security) | [changelog](./eslint/eslint-plugin-security/CHANGELOG.md) | [@rushstack/eslint-plugin-security](https://www.npmjs.com/package/@rushstack/eslint-plugin-security) |
+| [/heft-plugins/heft-api-extractor-plugin](./heft-plugins/heft-api-extractor-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-api-extractor-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-api-extractor-plugin) | [changelog](./heft-plugins/heft-api-extractor-plugin/CHANGELOG.md) | [@rushstack/heft-api-extractor-plugin](https://www.npmjs.com/package/@rushstack/heft-api-extractor-plugin) |
 | [/heft-plugins/heft-dev-cert-plugin](./heft-plugins/heft-dev-cert-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-dev-cert-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-dev-cert-plugin) | [changelog](./heft-plugins/heft-dev-cert-plugin/CHANGELOG.md) | [@rushstack/heft-dev-cert-plugin](https://www.npmjs.com/package/@rushstack/heft-dev-cert-plugin) |
 | [/heft-plugins/heft-jest-plugin](./heft-plugins/heft-jest-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-jest-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-jest-plugin) | [changelog](./heft-plugins/heft-jest-plugin/CHANGELOG.md) | [@rushstack/heft-jest-plugin](https://www.npmjs.com/package/@rushstack/heft-jest-plugin) |
+| [/heft-plugins/heft-lint-plugin](./heft-plugins/heft-lint-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-lint-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-lint-plugin) | [changelog](./heft-plugins/heft-lint-plugin/CHANGELOG.md) | [@rushstack/heft-lint-plugin](https://www.npmjs.com/package/@rushstack/heft-lint-plugin) |
 | [/heft-plugins/heft-sass-plugin](./heft-plugins/heft-sass-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin) | [changelog](./heft-plugins/heft-sass-plugin/CHANGELOG.md) | [@rushstack/heft-sass-plugin](https://www.npmjs.com/package/@rushstack/heft-sass-plugin) |
 | [/heft-plugins/heft-serverless-stack-plugin](./heft-plugins/heft-serverless-stack-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin) | [changelog](./heft-plugins/heft-serverless-stack-plugin/CHANGELOG.md) | [@rushstack/heft-serverless-stack-plugin](https://www.npmjs.com/package/@rushstack/heft-serverless-stack-plugin) |
 | [/heft-plugins/heft-storybook-plugin](./heft-plugins/heft-storybook-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin) | [changelog](./heft-plugins/heft-storybook-plugin/CHANGELOG.md) | [@rushstack/heft-storybook-plugin](https://www.npmjs.com/package/@rushstack/heft-storybook-plugin) |
+| [/heft-plugins/heft-typescript-plugin](./heft-plugins/heft-typescript-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-typescript-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-typescript-plugin) | [changelog](./heft-plugins/heft-typescript-plugin/CHANGELOG.md) | [@rushstack/heft-typescript-plugin](https://www.npmjs.com/package/@rushstack/heft-typescript-plugin) |
 | [/heft-plugins/heft-webpack4-plugin](./heft-plugins/heft-webpack4-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-webpack4-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-webpack4-plugin) | [changelog](./heft-plugins/heft-webpack4-plugin/CHANGELOG.md) | [@rushstack/heft-webpack4-plugin](https://www.npmjs.com/package/@rushstack/heft-webpack4-plugin) |
 | [/heft-plugins/heft-webpack5-plugin](./heft-plugins/heft-webpack5-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-webpack5-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-webpack5-plugin) | [changelog](./heft-plugins/heft-webpack5-plugin/CHANGELOG.md) | [@rushstack/heft-webpack5-plugin](https://www.npmjs.com/package/@rushstack/heft-webpack5-plugin) |
 | [/libraries/api-extractor-model](./libraries/api-extractor-model/) | [![npm version](https://badge.fury.io/js/%40microsoft%2Fapi-extractor-model.svg)](https://badge.fury.io/js/%40microsoft%2Fapi-extractor-model) | [changelog](./libraries/api-extractor-model/CHANGELOG.md) | [@microsoft/api-extractor-model](https://www.npmjs.com/package/@microsoft/api-extractor-model) |
@@ -120,8 +123,6 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/build-tests/eslint-7-test](./build-tests/eslint-7-test/) | This project contains a build test to validate ESLint 7 compatibility with the latest version of @rushstack/eslint-config (and by extension, the ESLint plugin) |
 | [/build-tests/hashed-folder-copy-plugin-webpack4-test](./build-tests/hashed-folder-copy-plugin-webpack4-test/) | Building this project exercises @rushstack/hashed-folder-copy-plugin with Webpack 4. |
 | [/build-tests/hashed-folder-copy-plugin-webpack5-test](./build-tests/hashed-folder-copy-plugin-webpack5-test/) | Building this project exercises @rushstack/hashed-folder-copy-plugin with Webpack 5. NOTE - THIS TEST IS CURRENTLY EXPECTED TO BE BROKEN |
-| [/build-tests/heft-action-plugin](./build-tests/heft-action-plugin/) | This project contains a Heft plugin that adds a custom action |
-| [/build-tests/heft-action-plugin-test](./build-tests/heft-action-plugin-test/) | This project exercises a custom Heft action |
 | [/build-tests/heft-copy-files-test](./build-tests/heft-copy-files-test/) | Building this project tests copying files with Heft |
 | [/build-tests/heft-example-plugin-01](./build-tests/heft-example-plugin-01/) | This is an example heft plugin that exposes hooks for other plugins |
 | [/build-tests/heft-example-plugin-02](./build-tests/heft-example-plugin-02/) | This is an example heft plugin that taps the hooks exposed from heft-example-plugin-01 |

UPGRADING_AND_TESTING.md

@@ -0,0 +1,155 @@
+# Upgrading to Multi-Phase Heft
+
+## Update heft.json
+The new version of Heft uses an updated schema based on the spec defined in Github issue [#3181](https://github.com/microsoft/rushstack/issues/3181). The new schema can be found [here](https://github.com/D4N14L/rushstack/blob/user/danade/HeftNext2/apps/heft/src/schemas/heft.schema.json).
+
+There are a few differences between the old format and the new format. The following is an [example legacy "heft.json" file](https://github.com/microsoft/rushstack-samples/blob/main/heft/heft-node-jest-tutorial/config/heft.json):
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
+  "eventActions": [
+    {
+      /**
+       * The kind of built-in operation that should be performed.
+       * The "deleteGlobs" action deletes files or folders that match the
+       * specified glob patterns.
+       */
+      "actionKind": "deleteGlobs",
+
+      /**
+       * The stage of the Heft run during which this action should occur.
+       * Note that actions specified in heft.json occur at the end of the
+       * stage of the Heft run.
+       */
+      "heftEvent": "clean",
+
+      /**
+       * A user-defined tag whose purpose is to allow configs to replace/delete
+       * handlers that were added by other configs.
+       */
+      "actionId": "defaultClean",
+
+      /**
+       * Glob patterns to be deleted. The paths are resolved relative to the project folder.
+       */
+      "globsToDelete": ["dist", "lib", "temp"]
+    }
+  ],
+
+  /**
+   * The list of Heft plugins to be loaded.
+   */
+  "heftPlugins": [
+    {
+      /**
+       * The path to the plugin package.
+       */
+      "plugin": "@rushstack/heft-jest-plugin"
+
+      /**
+       * An optional object that provides additional settings that may be defined by the plugin.
+       */
+      // "options": { }
+    }
+  ]
+}
+```
+Given this "heft.json" configuration, we can see that only the Jest plugin has been added. However, legacy Heft included a few specific additional plugins by default, making the list of plugins used for this Heft configuration:
+ - Jest plugin
+ - TypeScript plugin
+   - Additional linting performed in the TypeScript plugin
+ - API Extractor plugin
+
+Additionally, any plugin added would simply need to be added to the `heftPlugins` array.
+
+The new version of Heft does not include any default plugins, so **these plugins must all be added individually to "package.json"**. These include the plugins:
+ - `@rushstack/heft-jest-plugin`
+ - `@rushstack/heft-typescript-plugin`
+ - `@rushstack/heft-lint-plugin`
+ - `@rushstack/heft-api-extractor-plugin`
+
+Additionally, these plugins must be added in the form of `phases` and `tasks`. The following is an **updated "heft.json" for the same sample project**, using the schema new schema specified above:
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
+
+  "heftPlugins": [
+    /**
+     * Heft plugins is still around as a field, though it now hosts lifecycle
+     * plugins, which are plugins that have access to different lifecycle
+     * hooks, like "onToolStart", "onToolStop", and "recordMetrics".
+     * These are specified using the same schema as "taskPlugin" below.
+     *
+     * The field was not renamed, as there are plans to implement a form of
+     * simplified plugin specification. This is not yet implemented.
+     */
+  ]
+
+  "phasesByName": {
+    "build": {
+      "tasksByName": {
+        "typescript": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-typescript-plugin"
+            /**
+             * Plugin names can also be specified, if the package contains more than
+             * one plugin. Ex:
+             * "pluginName": "TypeScriptPlugin"
+             */
+          }
+          /**
+           * Additionally, you can specify events which provide simple functionality,
+           * but only one taskPlugin or one taskEvent can be specified per-task.\
+           *
+           * "taskEvent": {
+           *   "eventKind": "copyFiles|deleteFiles|runScript"
+           *   "options": {
+           *     ... (see schema)
+           *   }
+           * }
+           */
+        },
+        "lint": {
+          "taskDependencies": ["typescript"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-lint-plugin"
+          }
+        },
+        "api-extractor": {
+          "taskDependencies": ["typescript"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-api-extractor-plugin"
+          }
+        }
+      }
+    },
+    "test": {
+      "phaseDependencies": ["build"],
+      "tasksByName": {
+        "jest": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-jest-plugin",
+            "pluginName": "JestPlugin"
+          }
+        }
+      }
+    }
+  }
+}
+```
+Immediately, there are a few key differences
+ - There are now two types of plugins, "lifecycle plugins" and "task plugins"
+ - Actions that can be performed by Heft are now defined in "heft.json". As such, we must create both the `build` and `test` actions that can be run by executing `heft build` or `heft test` on the CLI.
+   - Note: `heft build` will perform only the `build` phase, while `heft test` will perform both the `build` and `test` phases, due to the phase dependency. Additionally, the new `heft run` command can be used to run a scoped set of phases. For example, `heft run --only test` will only run the `test` phase
+ - All internal default plugins are now external, and must be included in this structure manually
+   - Usage of rigs is encouraged, since the rig brings "heft.json" with it
+ - Order of execution of plugins is determined by `phaseDependencies` between phases, and `taskDependencies` within phases
+ - Packages can now contain multiple plugins
+ - `heftEvents` have become `taskEvents`, and are implemented as a member of a task
+
+## Testing this Branch On Your Own Project
+1. Following the above instructions, create a Heft rig in this branch that can be consumed by your project to perform it's build. All Rushstack plugins have been converted to be compatible with the updated Heft. You can optionally use `@rushstack/heft-node-rig` or `@rushstack/heft-web-rig` for your build, as these have also been converted.
+2. Build this branch, including `@rushstack/heft` and the target rig package
+3. Symlink the rig package into the appropriate `node_modules` folder for your project
+4. Replace the `node_modules/@rushstack/heft` folder for your project with a symlink to the Heft folder in this branch
+5. Run Heft against your project by executing `node ./node_modules/@rushstack/heft/lib/start.js build` to run the build phase, as described above

apps/api-documenter/package.json

@@ -11,8 +11,8 @@
   "license": "MIT",
   "scripts": {
     "build": "heft build --clean",
-    "_phase:build": "heft build --clean",
-    "_phase:test": "heft test --no-build"
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
   },
   "bin": {
     "api-documenter": "./bin/api-documenter"

apps/heft/package.json

@@ -42,10 +42,7 @@
     "argparse": "~1.0.9",
     "chokidar": "~3.4.0",
     "fast-glob": "~3.2.4",
-    "glob": "~7.0.5",
     "glob-escape": "~0.0.2",
-    "prettier": "~2.3.0",
-    "semver": "~7.3.0",
     "tapable": "1.1.3",
     "true-case-path": "~2.2.1"
   },
@@ -55,13 +52,7 @@
     "@rushstack/heft": "0.45.14",
     "@rushstack/heft-node-rig": "1.9.15",
     "@types/argparse": "1.0.38",
-    "@types/eslint": "8.2.0",
-    "@types/glob": "7.1.1",
     "@types/heft-jest": "1.0.1",
-    "@types/node": "12.20.24",
-    "@types/semver": "7.3.5",
-    "colors": "~1.2.1",
-    "tslint": "~5.20.1",
-    "typescript": "~4.6.3"
+    "@types/node": "12.20.24"
   }
 }