From 64e83340f44997fd64d87e31fbc2153f897b21ee Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:18:01 -0700 Subject: [PATCH 1/2] Resync src/schemas/templates/heft.json with the website docs --- apps/heft/src/schemas/templates/heft.json | 254 ++++++++++++---------- 1 file changed, 140 insertions(+), 114 deletions(-) diff --git a/apps/heft/src/schemas/templates/heft.json b/apps/heft/src/schemas/templates/heft.json index 6f7bac9cc38..087762787dd 100644 --- a/apps/heft/src/schemas/templates/heft.json +++ b/apps/heft/src/schemas/templates/heft.json @@ -10,137 +10,163 @@ */ // "extends": "base-project/config/heft.json", - "eventActions": [ - // { - // /** - // * (Required) 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", - // - // /** - // * (Required) The Heft stage when this action should be performed. Note that heft.json event actions - // * are scheduled after any plugin tasks have processed the event. For example, a "compile" event action - // * will be performed after the TypeScript compiler has been invoked. - // * - // * Options: "clean", "pre-compile", "compile", "bundle", "post-build" - // */ - // "heftEvent": "clean", - // + /** + * Defines aliases for existing Heft actions, and allows them to be invoked by + * name with default parameters. The JSON keys is are user-defined names. + * + * For example, the "heft start" alias is conventionally defined to invoke + * "heft build-watch --serve" using a definition like this: + * + * "aliasesByName": { "start": { "actionName": "build-watch", "defaultParameters": [ "--serve" ] } } + */ + "aliasesByName": { + // /** + // * The command-line action name of the Heft alias that is being defined. + // * This JSON key is a user-defined value. + // */ + // "example-alias-name": { // /** - // * (Required) A user-defined tag whose purpose is to allow configs to replace/delete handlers that - // * were added by other configs. + // * The name of the existing Heft command-line action to be invoked by this alias. // */ - // "actionId": "my-example-action", + // "actionName": "example-action", // // /** - // * (Required) Glob patterns to be deleted. The paths are resolved relative to the project folder. - // * Documentation for supported glob syntaxes: https://www.npmjs.com/package/fast-glob + // * A list of command-line parameters to pass to the Heft action by default. + // * These parameters will be appended after the specified action and before + // * any user-specified parameters. // */ - // "globsToDelete": [ - // "dist", - // "lib", - // "lib-esnext", - // "temp" - // ] - // }, - // + // "defaultParameters": [ "--do-some-thing" ] + // } + }, + + /** + * List of Heft lifecycle plugins to be loaded for this project. + */ + "heftPlugins": [ // { // /** - // * (Required) The kind of built-in operation that should be performed. - // * The "copyFiles" action copies files that match the specified patterns. - // */ - // "actionKind": "copyFiles", - // - // /** - // * (Required) The Heft stage when this action should be performed. Note that heft.json event actions - // * are scheduled after any plugin tasks have processed the event. For example, a "compile" event action - // * will be performed after the TypeScript compiler has been invoked. - // * - // * Options: "pre-compile", "compile", "bundle", "post-build" + // * (REQUIRED) The NPM package name for the plugin. // */ - // "heftEvent": "pre-compile", + // "pluginPackage": "@mycorp/heft-example-plugin", // // /** - // * (Required) A user-defined tag whose purpose is to allow configs to replace/delete handlers that - // * were added by other configs. + // * The name of the plugin to load from the NPM package's heft-plugin.json manifest. + // * If not specified, and if the plugin package provides a single plugin, then that + // * plugin will be loaded. // */ - // "actionId": "my-example-action", + // // "pluginName": "example-plugin", // // /** - // * (Required) An array of copy operations to run perform during the specified Heft event. + // * Options to pass to the plugin. This is a custom object whose structure + // * is defined by the plugin. // */ - // "copyOperations": [ - // { - // /** - // * (Required) The base folder that files will be copied from, relative to the project root. - // * Settings such as "includeGlobs" and "excludeGlobs" will be resolved relative - // * to this folder. - // * NOTE: Assigning "sourceFolder" does not by itself select any files to be copied. - // */ - // "sourceFolder": "src", - // - // /** - // * (Required) One or more folders that files will be copied into, relative to the project root. - // * If you specify more than one destination folder, Heft will read the input files only once, using - // * streams to efficiently write multiple outputs. - // */ - // "destinationFolders": ["dist/assets"], - // - // /** - // * If specified, this option recursively scans all folders under "sourceFolder" and includes any files - // * that match the specified extensions. (If "fileExtensions" and "includeGlobs" are both - // * specified, their selections are added together.) - // */ - // "fileExtensions": [".jpg", ".png"], - // - // /** - // * A list of glob patterns that select files to be copied. The paths are resolved relative - // * to "sourceFolder". - // * Documentation for supported glob syntaxes: https://www.npmjs.com/package/fast-glob - // */ - // "includeGlobs": ["assets/*.md"], - // - // /** - // * A list of glob patterns that exclude files/folders from being copied. The paths are resolved relative - // * to "sourceFolder". These exclusions eliminate items that were selected by the "includeGlobs" - // * or "fileExtensions" setting. - // */ - // "excludeGlobs": [], - // - // /** - // * Normally, when files are selected under a child folder, a corresponding folder will be created in - // * the destination folder. Specify flatten=true to discard the source path and copy all matching files - // * to the same folder. If two files have the same name an error will be reported. - // * The default value is false. - // */ - // "flatten": false, - // - // /** - // * If true, filesystem hard links will be created instead of copying the file. Depending on the - // * operating system, this may be faster. (But note that it may cause unexpected behavior if a tool - // * modifies the link.) The default value is false. - // */ - // "hardlink": false - // } - // ] + // // "options": { "example-key": "example-value" } // } ], /** - * The list of Heft plugins to be loaded. + * Heft phases that can be run during an execution of Heft. + * The JSON keys is are user-defined names. */ - "heftPlugins": [ - // { - // /** - // * The path to the plugin package. - // */ - // "plugin": "path/to/my-plugin", - // - // /** - // * An optional object that provides additional settings that may be defined by the plugin. - // */ - // // "options": { } - // } - ] + "phasesByName": { + /** + * The name of the phase, which is used by other fields such as "phaseDependencies". + * This JSON key is a user-defined value. + */ + "example-phase": { + /** + * A description to be shown in the command-line help. + */ + "phaseDescription": "An example phase", + + /** + * A list of delete operations to perform when cleaning at the beginning of phase execution. + * Their structure is similar the options used by the delete-files-plugin. + */ + "cleanFiles": [ + // { + // /** + // * Absolute path to the source file or folder, relative to the project root. + // * If "fileExtensions", "excludeGlobs", or "includeGlobs" are specified, then "sourcePath" + // * is assumed to be a folder; if it is not a folder, an error will be thrown. + // * Settings such as "includeGlobs" and "excludeGlobs" will be resolved relative to this path. + // * If no globs or file extensions are specified, the entire folder will be copied. + // * If this parameter is not provided, it defaults to the project root. + // */ + // // "sourcePath": "lib", + // + // /** + // * If specified, this option recursively scans all folders under "sourcePath" and includes + // * any files that match the specified extensions. If "fileExtensions" and "includeGlobs" + // * are both specified, their selections are added together. + // */ + // // "fileExtensions": [ ".png" ], + // + // /** + // * A list of glob patterns that select files to be copied. The paths are resolved relative + // * to "sourcePath", which must be a folder path. If "fileExtensions" and "includeGlobs" + // * are both specified, their selections are added together. + // * + // * For glob syntax, refer to: https://www.npmjs.com/package/fast-glob + // */ + // // "excludeGlobs": [], + // + // + // /** + // * A list of glob patterns that exclude files or folders from being copied. The paths are resolved + // * relative to "sourcePath", which must be a folder path. These exclusions eliminate items that + // * were selected by the "includeGlobs" or "fileExtensions" setting. + // * + // * For glob syntax, refer to: https://www.npmjs.com/package/fast-glob + // */ + // // "includeGlobs": [ "**/temp" ] + // } + ], + + /** + * A list of phase names that must be run before this phase can start. + */ + "phaseDependencies": [], + + /** + * Heft tasks that are run during an execution of the Heft phase. + * The JSON keys is are user-defined names. + */ + "tasksByName": { + /** + * The name of the task, which is used by other fields such as "taskDependencies". + * This JSON key is a user-defined value. + */ + "example-task": { + /** + * A list of task names that must be run before this task can start. + */ + "taskDependencies": [], + + /** + * (REQUIRED) The Heft plugin to be loaded, which will perform the operation for this task. + */ + "taskPlugin": { + /** + * (REQUIRED) The NPM package name for the plugin. + */ + "pluginPackage": "@mycorp/heft-example-plugin" + + /** + * The name of the plugin to load from the NPM package's heft-plugin.json manifest. + * If not specified, and if the plugin package provides a single plugin, then that + * plugin will be loaded. + */ + // "pluginName": "example-plugin", + + /** + * Options to pass to the plugin. This is a custom object whose structure + * is defined by the plugin. + */ + // "options": { "example-key": "example-value" } + } + } + } + } + } } From 90f87581e06d07e34e689687db842a9fcb3f62f8 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:19:15 -0700 Subject: [PATCH 2/2] rush change --- .../octogonz-heft-json-template_2024-07-11-01-18.json | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 common/changes/@rushstack/heft/octogonz-heft-json-template_2024-07-11-01-18.json diff --git a/common/changes/@rushstack/heft/octogonz-heft-json-template_2024-07-11-01-18.json b/common/changes/@rushstack/heft/octogonz-heft-json-template_2024-07-11-01-18.json new file mode 100644 index 00000000000..828a9360cfb --- /dev/null +++ b/common/changes/@rushstack/heft/octogonz-heft-json-template_2024-07-11-01-18.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@rushstack/heft", + "comment": "Update schemas/templates/heft.json to reflect new settings", + "type": "patch" + } + ], + "packageName": "@rushstack/heft" +} \ No newline at end of file