Update watch documentation

spring6225 · Mar 28, 2023 · a941299 · a941299
1 parent 4632ec8
commit a941299
Show file tree

Hide file tree

Showing 25 changed files with 42 additions and 203 deletions.
diff --git a/apps/heft/UPGRADING.md b/apps/heft/UPGRADING.md
@@ -1,6 +1,6 @@
 # Upgrade notes for @rushstack/heft
 
-### Heft 0.49.0-rc.1
+### Heft 0.50.0-rc.4
 
 Multi-phase Heft is a complete re-write of the `@rushstack/heft` project with the intention of being more closely compatible with multi-phase Rush builds. In addition, this update brings greater customizability and improved parallel process handling to Heft.
 
@@ -37,7 +37,7 @@ Additionally, task- and phase-specific parameters may be provided to the `heft r
 In addition, Heft will generate actions for each phase specified in the "heft.json" configuration. These actions are executed by running `heft <phaseName>` and run Heft to the specified phase, including all phase dependencies. As such, these inferred Heft actions are equivalent to running `heft run --to <phaseName>`, and are intended as a CLI shorthand.
 
 #### Watch Mode
-Watch mode is now a first-class feature in Heft. Watch mode actions are created for all Heft actions. For example, to run "build" and "test" phases in watch mode, either of the commands `heft test-watch` or `heft run-watch --to test`. When running in watch mode, Heft will start a file watcher and watch for changes, restarting the watch loop when changes to source files are detected. The list of changed files will be provided to the plugin for incremental processing.
+Watch mode is now a first-class feature in Heft. Watch mode actions are created for all Heft actions. For example, to run "build" and "test" phases in watch mode, either of the commands `heft test-watch` or `heft run-watch --to test`. When running in watch mode, Heft prefers the `runIncremental` hook to the `run` hook (see [Heft Task Plugins](#heft-task-plugins)).
 
 #### Heft Plugins
 ##### Heft Lifecycle Plugins
@@ -48,8 +48,11 @@ Heft lifecycle plugins provide the implementation for certain lifecycle-related
 
 ##### Heft Task Plugins
 Heft task plugins provide the implementation for Heft tasks. Heft plugins provide an `apply` method, and here plugins can hook into the following Tapable hooks:
+- `registerFileOperations` - Invoked exactly once before the first time a plugin runs. Allows a plugin to register copy or delete operations using the same options as the `copyFiles` and `deleteFiles` Heft events (this hook is how those events are implemented).
 - `run` - Used to provide plugin-related task functionality
-- `runIncremental` - Used to provide plugin-related task functionality when in watch mode. A list of modified files is provided for the plugin to process. If no `runIncremental` implementation is provided, Heft will fall back to using the `run` hook as usual.
+- `runIncremental` - Used to provide plugin-related task functionality when in watch mode. If no `runIncremental` implementation is provided for a task, Heft will fall back to using the `run` hook as usual. The options structure includes two functions used to support watch operations:
+  - `requestRun()` - This function asks the Heft runtime to schedule a new run of the plugin's owning task, potentially cancelling the current build.
+  - `watchGlobAsync(patterns, options)` - This function is provided for convenience for the common case of monitoring a glob for changes. It returns a `Map<string, IWatchedFileState>` that enumerates the list of files (or folders) selected by the glob and whether or not they have changed since the previous invocation. It will automatically invoke the `requestRun()` callback if it detects changes to files or directory listings that might impact the output of the glob.
 
 ##### Heft Cross-Plugin Interaction
 Heft plugins can use the `requestAccessToPluginByName` API to access the requested plugin accessors. Accessors are objects provided by plugins for external use and are the ideal place to share plugin-specific information or hooks used to provide additional plugin functionality.
@@ -154,21 +157,7 @@ The following is an example "heft.json" file defining both a "build" and a "test
   }
 }
 ```
-##### Watch Mode Options in "heft.json"
-Since watch mode and the associated file watcher are now directly managed by Heft, some watch mode options have been provided to modify behavior when encountering modified source files:
-```json
-{
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      "**/*.snap"
-    ],
-    "forbiddenSourceFileGlobs": [
-      "tsconfig.json"
-    ]
-  }
-}
-```
-These options allow developers to tell Heft to ignore when specific source file changes are made (for example, when checked-in snapshot files are updated by Jest) or to break the Heft build when specific source file changes are made (for example, modifying a configuration file that is only loaded on the first execution). Notably, these properties are global and apply to all watch mode actions.
+
 ##### Property Inheritance in "heft.json"
 Previously, common properties between a "heft.json" file its extended base file would merge arrays and overwrite objects. Now, both arrays and objects will merge, allowing for simplified use of the "heft.json" file when customizing extended base configurations.
 
@@ -199,12 +188,6 @@ One thing to note is that different mergeBehavior verbs are used for the merging
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      "**/*.snap"
-    ]
-  },
-
   "phasesByName": {
     "build": {
       "cleanFiles": [
@@ -337,7 +320,7 @@ In updating to the new version of Heft, plugins will also need to be updated for
 - Plugins can no longer define their own actions. If a plugin deserves its own action, a dedicated phase should be added to the consumers "heft.json"
 - The `runScript` Heft event has been modified to only accept a `runAsync` method, and the properties have been updated to reflect what is available to normal Heft task plugins
 - Path-related variables have been renamed to clarify they are paths (ex. `HeftConfiguration.buildFolder` is now `HeftConfiguration.buildFolderPath`)
-- The `runIncremental` hook can now be utilized to add native incremental watch mode support
+- The `runIncremental` hook can now be utilized to add ensure that watch mode rebuilds occur in proper dependency order
 - The `clean` hook was removed in favor of the `cleanFiles` option in "heft.json" in order to make it obvious what files are being cleaned and when
 - The `folderNameForTests` and `extensionForTests` properties are now specified in the `@rushstack/heft-jest-plugin` options in "heft.json" instead of in "typescript.json"
 

diff --git a/apps/heft/src/pluginFramework/InternalHeftSession.ts b/apps/heft/src/pluginFramework/InternalHeftSession.ts
@@ -116,19 +116,6 @@ export class InternalHeftSession {
     return this._phasesByName!;
   }
 
-  public get watchOptions(): IHeftSessionWatchOptions {
-    if (!this._watchOptions) {
-      this._watchOptions = {
-        ignoredSourceFileGlobs: this._heftConfigurationJson.watchOptions?.ignoredSourceFileGlobs || [],
-        forbiddenSourceFileGlobs: [
-          ...FORBIDDEN_SOURCE_FILE_GLOBS,
-          ...(this._heftConfigurationJson.watchOptions?.forbiddenSourceFileGlobs || [])
-        ]
-      };
-    }
-    return this._watchOptions;
-  }
-
   public getSessionForPhase(phase: HeftPhase): HeftPhaseSession {
     let phaseSession: HeftPhaseSession | undefined = this._phaseSessionsByPhase.get(phase);
     if (!phaseSession) {

diff --git a/apps/heft/src/schemas/heft.schema.json b/apps/heft/src/schemas/heft.schema.json
@@ -102,32 +102,6 @@
       "type": "string"
     },
 
-    "watchOptions": {
-      "title": "Watch Mode Options",
-      "type": "object",
-      "description": "Global options used by Heft when running in watch mode.",
-      "properties": {
-        "ignoredSourceFileGlobs": {
-          "title": "Ignored Source File Globs",
-          "type": "array",
-          "description": "Glob patterns for source files that should be ignored when watching for changes. Changes to these files will still be detected and recorded by Heft, but will not trigger a rebuild.",
-          "items": {
-            "type": "string",
-            "pattern": "[^\\\\]"
-          }
-        },
-        "forbiddenSourceFileGlobs": {
-          "title": "Forbidden Source File Globs",
-          "type": "array",
-          "description": "Glob patterns for source files that should break the build when watching for changes. Changes to these files will cause Heft to exit with an error. Changes in project \"package.json\" files and \"config\" and \".rush\" folders are always forbidden and do not need to be included in this list.",
-          "items": {
-            "type": "string",
-            "pattern": "[^\\\\]"
-          }
-        }
-      }
-    },
-
     "heftPlugins": {
       "type": "array",
       "description": "List of Heft plugins that are used by a project.",

diff --git a/apps/heft/src/utilities/CoreConfigFiles.ts b/apps/heft/src/utilities/CoreConfigFiles.ts
@@ -45,15 +45,9 @@ export interface IHeftConfigurationJsonPhases {
   [phaseName: string]: IHeftConfigurationJsonPhaseSpecifier;
 }
 
-export interface IHeftConfigurationJsonWatchOptions {
-  ignoredSourceFileGlobs?: string[];
-  forbiddenSourceFileGlobs?: string[];
-}
-
 export interface IHeftConfigurationJson {
   heftPlugins?: IHeftConfigurationJsonPluginSpecifier[];
   phasesByName?: IHeftConfigurationJsonPhases;
-  watchOptions?: IHeftConfigurationJsonWatchOptions;
 }
 
 export class CoreConfigFiles {

diff --git a/build-tests-samples/heft-node-basic-tutorial/config/heft.json b/build-tests-samples/heft-node-basic-tutorial/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests-samples/heft-node-jest-tutorial/config/heft.json b/build-tests-samples/heft-node-jest-tutorial/config/heft.json
@@ -1,13 +1,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests-samples/heft-serverless-stack-tutorial/config/heft.json b/build-tests-samples/heft-serverless-stack-tutorial/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests-samples/heft-storybook-react-tutorial/config/heft.json b/build-tests-samples/heft-storybook-react-tutorial/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests-samples/heft-webpack-basic-tutorial/config/heft.json b/build-tests-samples/heft-webpack-basic-tutorial/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-jest-reporters-test/config/heft.json b/build-tests/heft-jest-reporters-test/config/heft.json
@@ -1,13 +1,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-minimal-rig-test/profiles/default/config/heft.json b/build-tests/heft-minimal-rig-test/profiles/default/config/heft.json
@@ -1,13 +1,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-node-everything-esm-module-test/config/heft.json b/build-tests/heft-node-everything-esm-module-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   "phasesByName": {
     "build": {
       "cleanFiles": [

diff --git a/build-tests/heft-node-everything-test/config/heft.json b/build-tests/heft-node-everything-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-parameter-plugin-test/config/heft.json b/build-tests/heft-parameter-plugin-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-sass-test/config/heft.json b/build-tests/heft-sass-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-typescript-composite-test/config/heft.json b/build-tests/heft-typescript-composite-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-webpack4-everything-test/config/heft.json b/build-tests/heft-webpack4-everything-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {

diff --git a/build-tests/heft-webpack5-everything-test/config/heft.json b/build-tests/heft-webpack5-everything-test/config/heft.json
@@ -4,13 +4,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
-  "watchOptions": {
-    "ignoredSourceFileGlobs": [
-      // Snapshots from Jest are updated even when the source file hasn't changed
-      "**/*.snap"
-    ]
-  },
-
   // TODO: Add comments
   "phasesByName": {
     "build": {