[heft] Faster startup, same API (v2)

apps/heft/bin/heft

@@ -1,2 +1,11 @@
 #!/usr/bin/env node
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+// Enable the V8 compile cache before anything else is loaded (Node.js >= 22.8). It honors the
+// NODE_COMPILE_CACHE and NODE_DISABLE_COMPILE_CACHE environment variables and fails silently.
+try {
+  require('../lib-commonjs/bootstrap/CompileCache.js').tryEnableCompileCache();
+} catch {}
+
 require('../lib-commonjs/startWithVersionSelector.js');

apps/heft/config/heft.json

@@ -22,6 +22,19 @@
           }
         },
 
+        // Make lib-commonjs/index.js load each re-exported module on first access, so that
+        // require("@rushstack/heft") stays cheap for plugins and tools that only need a few exports.
+        "lazy-barrel": {
+          "taskDependencies": ["typescript"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft",
+            "pluginName": "run-script-plugin",
+            "options": {
+              "scriptPath": "./node_modules/decoupled-local-node-rig/profiles/default/includes/lazy-barrel/lazyBarrel.js"
+            }
+          }
+        },
+
         "copy-legacy-compatibility-start-js": {
           "taskDependencies": ["typescript"],
           "taskPlugin": {

apps/heft/src/bootstrap/CompileCache.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+// This module is loaded by bin/heft before anything else, so it intentionally only uses Node.js built-in modules
+// (named imports avoid the interop helpers).
+import { mkdirSync } from 'node:fs';
+import nodeModule from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface IModuleCompileCacheApi {
+  enableCompileCache?: () => unknown;
+  getCompileCacheDir?: () => string | undefined;
+}
+
+/**
+ * Enables the V8 compile cache for the current process (Node.js >= 22.8), like `module.enableCompileCache()`:
+ * the cache folder is NODE_COMPILE_CACHE if set, otherwise `<os.tmpdir()>/node-compile-cache`, and
+ * NODE_DISABLE_COMPILE_CACHE disables it. Never throws; failures just leave the compile cache disabled.
+ *
+ * @returns the compile cache folder, or undefined if the compile cache is not enabled
+ */
+export function tryEnableCompileCache(): string | undefined {
+  try {
+    const compileCacheApi: IModuleCompileCacheApi = nodeModule as IModuleCompileCacheApi;
+    if (typeof compileCacheApi.enableCompileCache !== 'function') {
+      return undefined;
+    }
+    const env: NodeJS.ProcessEnv = process.env;
+    if (env.NODE_DISABLE_COMPILE_CACHE !== undefined) {
+      return undefined;
+    }
+    if (!env.NODE_COMPILE_CACHE) {
+      // Make sure that the default cache folder can be created with a single mkdir, because Node.js' recursive
+      // folder creation never returns for some unusable locations (e.g. TMPDIR pointing into /proc).
+      try {
+        mkdirSync(join(tmpdir(), 'node-compile-cache'));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+          return undefined;
+        }
+      }
+    }
+    compileCacheApi.enableCompileCache();
+    return compileCacheApi.getCompileCacheDir?.();
+  } catch {
+    return undefined;
+  }
+}

apps/heft/src/bootstrap/enableStartupCaches.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+// This module is imported for its side effects by start.ts, before the rest of Heft is loaded.
+// It enables the V8 compile cache (a no-op if bin/heft already enabled it).
+
+import { tryEnableCompileCache } from './CompileCache';
+
+tryEnableCompileCache();

apps/heft/src/cli/CliConstants.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * Strings that define Heft's top-level command line. These are shared by the lean command-line implementation
+ * and the full ts-command-line based implementation, which must produce identical output.
+ */
+export const HEFT_TOOL_FILENAME: 'heft' = 'heft';
+
+export const HEFT_TOOL_DESCRIPTION: string = 'Heft is a pluggable build system designed for web projects.';
+
+export const DEBUG_PARAMETER_DESCRIPTION: string =
+  'Show the full call stack if an error occurs while executing the tool';
+
+export const UNMANAGED_PARAMETER_DESCRIPTION: string =
+  'Disables the Heft version selector: When Heft is invoked via the shell path, normally it' +
+  " will examine the project's package.json dependencies and try to use the locally installed version" +
+  ' of Heft. Specify "--unmanaged" to force the invoked version of Heft to be used. This is useful for' +
+  ' example if you want to test a different version of Heft.';
+
+export const VERBOSE_PARAMETER_DESCRIPTION: string = 'If specified, log information useful for debugging.';
+
+export const CLEAN_ACTION_DOCUMENTATION: string =
+  'Clean the project, removing temporary task folders and specified clean paths.';
+
+/**
+ * The description of the remainder parameter that ts-command-line's `ScopedCommandLineAction` defines.
+ */
+export const SCOPED_ACTION_REMAINDER_DESCRIPTION: string =
+  'Scoped parameters.  Must be prefixed with "--", ex. "-- --scopedParameter ' +
+  'foo --scopedFlag".  For more information on available scoped parameters, use "-- --help".';
+
+export function getRunActionDocumentation(watch: boolean): string {
+  return `Run a provided selection of Heft phases${watch ? ' in watch mode.' : ''}.`;
+}
+
+export function getPhaseActionSummary(phaseName: string, watch: boolean): string {
+  return (
+    `Runs to the ${phaseName} phase, including all transitive dependencies` +
+    (watch ? ', in watch mode.' : '.')
+  );
+}
+
+export function getPhaseActionDocumentation(
+  phaseName: string,
+  phaseDescription: string | undefined,
+  watch: boolean
+): string {
+  return getPhaseActionSummary(phaseName, watch) + (phaseDescription ? `  ${phaseDescription}` : '');
+}