Merge remote-tracking branch 'remotes/origin/main' into octogonz/heft…

…-updated-schemas

apps/api-documenter/CHANGELOG.json

@@ -1,6 +1,21 @@
 {
   "name": "@microsoft/api-documenter",
   "entries": [
+    {
+      "version": "7.22.13",
+      "tag": "@microsoft/api-documenter_v7.22.13",
+      "date": "Thu, 08 Jun 2023 15:21:17 GMT",
+      "comments": {
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@rushstack/heft\" to `0.52.2`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/heft-node-rig\" to `2.2.2`"
+          }
+        ]
+      }
+    },
     {
       "version": "7.22.12",
       "tag": "@microsoft/api-documenter_v7.22.12",

apps/api-documenter/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Thu, 08 Jun 2023 00:20:02 GMT and should not be manually modified.
+This log was last generated on Thu, 08 Jun 2023 15:21:17 GMT and should not be manually modified.
+
+## 7.22.13
+Thu, 08 Jun 2023 15:21:17 GMT
+
+_Version update only_
 
 ## 7.22.12
 Thu, 08 Jun 2023 00:20:02 GMT

apps/api-documenter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/api-documenter",
-  "version": "7.22.12",
+  "version": "7.22.13",
   "description": "Read JSON files from api-extractor, generate documentation pages",
   "repository": {
     "type": "git",

apps/heft/.npmignore

@@ -30,3 +30,4 @@
 # (Add your project-specific overrides here)
 !/includes/**
 !UPGRADING.md
+!heft-plugin.json

apps/heft/CHANGELOG.json

@@ -1,6 +1,18 @@
 {
   "name": "@rushstack/heft",
   "entries": [
+    {
+      "version": "0.52.2",
+      "tag": "@rushstack/heft_v0.52.2",
+      "date": "Thu, 08 Jun 2023 15:21:17 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Provide a useful error message when encountering legacy Heft configurations"
+          }
+        ]
+      }
+    },
     {
       "version": "0.52.1",
       "tag": "@rushstack/heft_v0.52.1",

apps/heft/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log - @rushstack/heft
 
-This log was last generated on Thu, 08 Jun 2023 00:20:02 GMT and should not be manually modified.
+This log was last generated on Thu, 08 Jun 2023 15:21:17 GMT and should not be manually modified.
+
+## 0.52.2
+Thu, 08 Jun 2023 15:21:17 GMT
+
+### Patches
+
+- Provide a useful error message when encountering legacy Heft configurations
 
 ## 0.52.1
 Thu, 08 Jun 2023 00:20:02 GMT

apps/heft/UPGRADING.md

@@ -1,5 +1,37 @@
 # Upgrade notes for @rushstack/heft
 
+### Heft 0.53.0
+The `taskEvent` configuration option in heft.json has been removed, and use of any `taskEvent`-based functionality is now accomplished by referencing the plugins directly within the `@rushstack/heft` package.
+
+Plugin name mappings for previously-existing task events are:
+- `copyFiles` -> `copy-files-plugin`
+- `deleteFiles` -> `delete-files-plugin`
+- `runScript` -> `run-script-plugin`
+- `nodeService` -> `node-service-plugin`
+
+Example diff of a heft.json file that uses the `copyFiles` task event:
+```diff
+{
+  "phasesByName": {
+    "build": {
+      "tasksbyName": {
+        "perform-copy": {
+-          "taskEvent": {
+-            "eventKind": "copyFiles",
++          "taskPlugin": {
++            "pluginPackage": "@rushstack/heft",
++            "pluginName": "copy-files-plugin",
+            "options": {
+              ...
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ### Heft 0.52.0
 
 The `nodeService` built-in plugin now supports the `--serve` parameter, to be consistent with the `@rushstack/heft-webpack5-plugin` dev server.
@@ -91,13 +123,13 @@ Lifecycle plugins are specified in the top-level `heftPlugins` array. Plugins ca
 
   "heftPlugins": [
     {
-      "packageName": "@rushstack/heft-metrics-reporter",
+      "pluginPackage": "@rushstack/heft-metrics-reporter",
       "options": {
         "disableMetrics": true
       }
     },
     {
-      "packageName": "@rushstack/heft-initialization-plugin",
+      "pluginPackage": "@rushstack/heft-initialization-plugin",
       "pluginName": "my-lifecycle-plugin"
     }
   ]
@@ -118,7 +150,7 @@ The following is an example "heft.json" file defining both a "build" and a "test
   // "heftPlugins" can be used alongside "phasesByName"
   "heftPlugins": [
     {
-      "packageName": "@rushstack/heft-metrics-reporter"
+      "pluginPackage": "@rushstack/heft-metrics-reporter"
     }
   ],
 
@@ -146,8 +178,9 @@ The following is an example "heft.json" file defining both a "build" and a "test
           }
         },
         "copy-assets": {
-          "taskEvent": {
-            "eventKind": "copyFiles",
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft",
+            "pluginName": "copy-files-plugin",
             "options": {
               "copyOperations": [
                 {

apps/heft/heft-plugin.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft-plugin.schema.json",
+
+  "lifecyclePlugins": [],
+
+  "taskPlugins": [
+    {
+      "pluginName": "copy-files-plugin",
+      "entryPoint": "./lib/plugins/CopyFilesPlugin",
+      "optionsSchema": "./lib/schemas/copy-files-options.schema.json"
+    },
+    {
+      "pluginName": "delete-files-plugin",
+      "entryPoint": "./lib/plugins/DeleteFilesPlugin",
+      "optionsSchema": "./lib/schemas/delete-files-options.schema.json"
+    },
+    {
+      "pluginName": "node-service-plugin",
+      "entryPoint": "./lib/plugins/NodeServicePlugin",
+      "parameterScope": "node-service",
+      "parameters": [
+        {
+          "longName": "--serve",
+          "parameterKind": "flag",
+          "description": "Start a local web server for testing purposes. This parameter is only available when running in watch mode."
+        }
+      ]
+    },
+    {
+      "pluginName": "run-script-plugin",
+      "entryPoint": "./lib/plugins/RunScriptPlugin",
+      "optionsSchema": "./lib/schemas/run-script-options.schema.json"
+    }
+  ]
+}

apps/heft/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/heft",
-  "version": "0.52.1",
+  "version": "0.52.2",
   "description": "Build all your JavaScript projects the same way: A way that works.",
   "keywords": [
     "toolchain",

apps/heft/src/configuration/HeftPluginConfiguration.ts

@@ -80,41 +80,6 @@ export class HeftPluginConfiguration {
     return await heftPluginConfigurationPromise;
   }
 
-  public get lifecyclePluginDefinitions(): ReadonlySet<HeftLifecyclePluginDefinition> {
-    if (!this._lifecyclePluginDefinitions) {
-      this._lifecyclePluginDefinitions = new Set();
-      for (const lifecyclePluginDefinitionJson of this._heftPluginConfigurationJson.lifecyclePlugins || []) {
-        this._lifecyclePluginDefinitions.add(
-          HeftLifecyclePluginDefinition.loadFromObject({
-            heftPluginDefinitionJson: lifecyclePluginDefinitionJson,
-            packageRoot: this.packageRoot,
-            packageName: this.packageName
-          })
-        );
-      }
-    }
-    return this._lifecyclePluginDefinitions;
-  }
-
-  /**
-   * Task plugin definitions sourced from the heft-plugin.json file.
-   */
-  public get taskPluginDefinitions(): ReadonlySet<HeftTaskPluginDefinition> {
-    if (!this._taskPluginDefinitions) {
-      this._taskPluginDefinitions = new Set();
-      for (const taskPluginDefinitionJson of this._heftPluginConfigurationJson.taskPlugins || []) {
-        this._taskPluginDefinitions.add(
-          HeftTaskPluginDefinition.loadFromObject({
-            heftPluginDefinitionJson: taskPluginDefinitionJson,
-            packageRoot: this.packageRoot,
-            packageName: this.packageName
-          })
-        );
-      }
-    }
-    return this._taskPluginDefinitions;
-  }
-
   /**
    * Returns a loaded plugin definition for the provided specifier. Specifiers are normally obtained from the
    * heft.json file.
@@ -123,10 +88,10 @@ export class HeftPluginConfiguration {
     pluginSpecifier: IHeftConfigurationJsonPluginSpecifier
   ): HeftPluginDefinitionBase {
     if (!pluginSpecifier.pluginName) {
-      const pluginDefinitions: HeftPluginDefinitionBase[] = [
-        ...this.lifecyclePluginDefinitions,
-        ...this.taskPluginDefinitions
-      ];
+      const pluginDefinitions: HeftPluginDefinitionBase[] = ([] as HeftPluginDefinitionBase[]).concat(
+        Array.from(this._getLifecyclePluginDefinitions()),
+        Array.from(this._getTaskPluginDefinitions())
+      );
       // Make an attempt at resolving the plugin without the name by looking for the first plugin
       if (pluginDefinitions.length > 1) {
         throw new Error(
@@ -150,6 +115,24 @@ export class HeftPluginConfiguration {
     }
   }
 
+  /**
+   * Returns if the provided plugin definition is a lifecycle plugin definition.
+   */
+  public isLifecyclePluginDefinition(
+    pluginDefinition: HeftPluginDefinitionBase
+  ): pluginDefinition is HeftLifecyclePluginDefinition {
+    return this._getLifecyclePluginDefinitions().has(pluginDefinition);
+  }
+
+  /**
+   * Returns if the provided plugin definition is a task plugin definition.
+   */
+  public isTaskPluginDefinition(
+    pluginDefinition: HeftPluginDefinitionBase
+  ): pluginDefinition is HeftTaskPluginDefinition {
+    return this._getTaskPluginDefinitions().has(pluginDefinition);
+  }
+
   /**
    * Returns a loaded lifecycle plugin definition for the provided plugin name. If one can't be found,
    * returns undefined.
@@ -159,7 +142,10 @@ export class HeftPluginConfiguration {
   ): HeftLifecyclePluginDefinition | undefined {
     if (!this._lifecyclePluginDefinitionsMap) {
       this._lifecyclePluginDefinitionsMap = new Map(
-        [...this.lifecyclePluginDefinitions].map((d: HeftLifecyclePluginDefinition) => [d.pluginName, d])
+        Array.from(this._getLifecyclePluginDefinitions()).map((d: HeftLifecyclePluginDefinition) => [
+          d.pluginName,
+          d
+        ])
       );
     }
     return this._lifecyclePluginDefinitionsMap.get(lifecyclePluginName);
@@ -172,12 +158,47 @@ export class HeftPluginConfiguration {
   public tryGetTaskPluginDefinitionByName(taskPluginName: string): HeftTaskPluginDefinition | undefined {
     if (!this._taskPluginDefinitionsMap) {
       this._taskPluginDefinitionsMap = new Map(
-        [...this.taskPluginDefinitions].map((d: HeftTaskPluginDefinition) => [d.pluginName, d])
+        Array.from(this._getTaskPluginDefinitions()).map((d: HeftTaskPluginDefinition) => [d.pluginName, d])
       );
     }
     return this._taskPluginDefinitionsMap.get(taskPluginName);
   }
 
+  private _getLifecyclePluginDefinitions(): ReadonlySet<HeftLifecyclePluginDefinition> {
+    if (!this._lifecyclePluginDefinitions) {
+      this._lifecyclePluginDefinitions = new Set();
+      for (const lifecyclePluginDefinitionJson of this._heftPluginConfigurationJson.lifecyclePlugins || []) {
+        this._lifecyclePluginDefinitions.add(
+          HeftLifecyclePluginDefinition.loadFromObject({
+            heftPluginDefinitionJson: lifecyclePluginDefinitionJson,
+            packageRoot: this.packageRoot,
+            packageName: this.packageName
+          })
+        );
+      }
+    }
+    return this._lifecyclePluginDefinitions;
+  }
+
+  /**
+   * Task plugin definitions sourced from the heft-plugin.json file.
+   */
+  private _getTaskPluginDefinitions(): ReadonlySet<HeftTaskPluginDefinition> {
+    if (!this._taskPluginDefinitions) {
+      this._taskPluginDefinitions = new Set();
+      for (const taskPluginDefinitionJson of this._heftPluginConfigurationJson.taskPlugins || []) {
+        this._taskPluginDefinitions.add(
+          HeftTaskPluginDefinition.loadFromObject({
+            heftPluginDefinitionJson: taskPluginDefinitionJson,
+            packageRoot: this.packageRoot,
+            packageName: this.packageName
+          })
+        );
+      }
+    }
+    return this._taskPluginDefinitions;
+  }
+
   private _validate(heftPluginConfigurationJson: IHeftPluginConfigurationJson, packageName: string): void {
     if (
       !heftPluginConfigurationJson.lifecyclePlugins?.length &&

apps/heft/src/configuration/HeftPluginDefinition.ts

@@ -211,7 +211,7 @@ export abstract class HeftPluginDefinitionBase {
     }
 
     // Ensure that plugin names are unique. Main reason for this restriction is to ensure that command-line
-    // parameter conflicts can be handled/undocumented synonms can be provided in all scenarios
+    // parameter conflicts can be handled/undocumented synonyms can be provided in all scenarios
     const existingPluginPath: string | undefined = HeftPluginDefinitionBase._loadedPluginPathsByName.get(
       this.pluginName
     );

apps/heft/src/pluginFramework/HeftLifecycle.ts

@@ -8,7 +8,10 @@ import { HeftPluginConfiguration } from '../configuration/HeftPluginConfiguratio
 import { HeftPluginHost } from './HeftPluginHost';
 import type { InternalHeftSession } from './InternalHeftSession';
 import type { IHeftConfigurationJsonPluginSpecifier } from '../utilities/CoreConfigFiles';
-import type { HeftLifecyclePluginDefinition } from '../configuration/HeftPluginDefinition';
+import type {
+  HeftLifecyclePluginDefinition,
+  HeftPluginDefinitionBase
+} from '../configuration/HeftPluginDefinition';
 import type { IHeftLifecyclePlugin, IHeftPlugin } from './IHeftPlugin';
 import {
   HeftLifecycleSession,
@@ -144,11 +147,12 @@ export class HeftLifecycle extends HeftPluginHost {
       let pluginConfigurationIndex: number = 0;
       for (const pluginSpecifier of this._lifecyclePluginSpecifiers) {
         const pluginConfiguration: HeftPluginConfiguration = pluginConfigurations[pluginConfigurationIndex++];
-        const pluginDefinition: HeftLifecyclePluginDefinition =
+        const pluginDefinition: HeftPluginDefinitionBase =
           pluginConfiguration.getPluginDefinitionBySpecifier(pluginSpecifier);
 
         // Ensure the plugin is a lifecycle plugin
-        if (!pluginConfiguration.lifecyclePluginDefinitions.has(pluginDefinition)) {
+        const isLifecyclePlugin: boolean = pluginConfiguration.isLifecyclePluginDefinition(pluginDefinition);
+        if (!isLifecyclePlugin) {
           throw new Error(
             `Plugin ${JSON.stringify(pluginDefinition.pluginName)} from package ` +
               `${JSON.stringify(pluginSpecifier.pluginPackage)} is not a lifecycle plugin.`