[Profiler] Spawn and profile process (elastic#230352)

Adds the possibility to spawn a process and profile it from start to
finish, using `--inspect-wait`:

### Spawning a new process

You can also spawn a new process, so you can profile start to finish.
This is useful for shorter-lived processes. Use the `--spawn` flag for
this purpose:

`node scripts/profile.js --spawn -- node scripts/my_expensive_script`

The script will be executed with `NODE_OPTIONS=inspect-wait`, which will
pause the script until the profiler script has attached to the debugger.

---------------

Also made Flags a generic type, so specified flags can be fully typed
(when the consumer opts in).

Author: dgieselaar

scripts/profile.js

@@ -7,9 +7,6 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-require('@babel/register')({
-  extensions: ['.ts', '.js'],
-  presets: [['@babel/preset-env', { targets: { node: 'current' } }], '@babel/preset-typescript'],
-});
+require('../src/setup_node_env');
 
 require('@kbn/profiler-cli/cli');

src/platform/packages/shared/kbn-dev-cli-runner/index.ts

@@ -7,8 +7,11 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-export * from './src/run';
-export * from './src/run_with_commands';
-export * from './src/flags';
-export * from './src/flags_reader';
+export * from './src/run/run';
+export type * from './src/run/types';
+export * from './src/run/run_with_commands';
+export * from './src/flags/flags';
+export type * from './src/flags/types';
+export * from './src/flags/flags_reader';
+
 export type { CleanupTask } from './src/cleanup';

src/platform/packages/shared/kbn-dev-cli-runner/src/flags.test.ts renamed to src/platform/packages/shared/kbn-dev-cli-runner/src/flags/flags.test.ts

@@ -9,31 +9,7 @@
 
 import getopts from 'getopts';
 import { LOG_LEVEL_FLAGS, DEFAULT_LOG_LEVEL } from '@kbn/tooling-log';
-
-import type { RunOptions } from './run';
-
-export interface Flags {
-  verbose: boolean;
-  quiet: boolean;
-  silent: boolean;
-  debug: boolean;
-  help: boolean;
-  _: string[];
-  unexpected: string[];
-
-  [key: string]: undefined | boolean | string | string[];
-}
-
-export interface FlagOptions {
-  allowUnexpected?: boolean;
-  guessTypesForUnexpectedFlags?: boolean;
-  help?: string;
-  examples?: string;
-  alias?: { [key: string]: string | string[] };
-  boolean?: string[];
-  string?: string[];
-  default?: { [key: string]: any };
-}
+import type { FlagOptions, Flags } from './types';
 
 export function mergeFlagOptions(global: FlagOptions = {}, local: FlagOptions = {}): FlagOptions {
   return {
@@ -62,7 +38,7 @@ export const DEFAULT_FLAG_ALIASES = {
 
 export function getFlags(
   argv: string[],
-  flagOptions: RunOptions['flags'] = {},
+  flagOptions: FlagOptions = {},
   defaultLogLevel: string = DEFAULT_LOG_LEVEL
 ): Flags {
   const unexpectedNames = new Set<string>();

src/platform/packages/shared/kbn-dev-cli-runner/src/flags.ts renamed to src/platform/packages/shared/kbn-dev-cli-runner/src/flags/flags.ts

@@ -12,7 +12,7 @@ import Path from 'path';
 import { createFlagError } from '@kbn/dev-cli-errors';
 import { LOG_LEVEL_FLAGS } from '@kbn/tooling-log';
 
-type FlagValue = string | string[] | boolean;
+type FlagValue = string | string[] | boolean | number;
 const FORCED_FLAGS = new Set([...LOG_LEVEL_FLAGS.map((l) => l.name), 'help']);
 
 const makeAbsolute = (rel: string) => Path.resolve(process.cwd(), rel);
@@ -78,6 +78,7 @@ export class FlagsReader {
 
     switch (typeof value) {
       case 'boolean':
+      case 'number':
         throw createFlagError(`expected --${key} to be a string`);
       case 'string':
         return value ? [value] : [];

src/platform/packages/shared/kbn-dev-cli-runner/src/flags_reader.test.ts renamed to src/platform/packages/shared/kbn-dev-cli-runner/src/flags/flags_reader.test.ts

@@ -0,0 +1,88 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+// iterate over the items in order, to find non-nullish types
+type Coalesce<T extends any[]> = T extends [infer T1, ...infer TTail]
+  ? T1 extends null | undefined | false
+    ? Coalesce<TTail>
+    : T1
+  : T extends [infer T1]
+  ? T1
+  : false;
+
+// make sure string[] is not converted into { [key:string]: string }
+// which is too wide to be useful
+type FlagsToObj<T extends string[] | undefined, TValue> = string[] extends T
+  ? {}
+  : T extends string[]
+  ? {
+      [key in T[number] & string]?: TValue;
+    }
+  : {};
+
+type IsStringLiteral<T extends string[] | undefined> = string[] extends T
+  ? false
+  : undefined extends T
+  ? false
+  : true;
+
+type IsTypedFlagOptions<TFlagOptions extends FlagOptions> = Coalesce<
+  [IsStringLiteral<TFlagOptions['string']>, IsStringLiteral<TFlagOptions['boolean']>]
+>;
+
+interface UnspecifiedFlags {
+  [key: string]: string | string[] | boolean | undefined;
+}
+
+/**
+ * Infer the type of Flags from FlagOptions. Inference only kicks in when
+ * either `string` or `boolean` consists of string literals (which only
+ * is the case when the flag options are tagged with the `as const` modifier.)
+ * Otherwise the type we create is too specific and we'd have to use `as const`
+ * everywhere.
+ */
+export type FlagsOf<TFlagOptions extends FlagOptions> =
+  IsTypedFlagOptions<TFlagOptions> extends true
+    ? BaseFlags<
+        (true extends TFlagOptions['allowUnexpected'] ? UnspecifiedFlags : {}) &
+          (TFlagOptions['string'] extends string[]
+            ? FlagsToObj<TFlagOptions['string'], string>
+            : {}) &
+          (TFlagOptions['boolean'] extends string[]
+            ? FlagsToObj<TFlagOptions['boolean'], boolean>
+            : {})
+      >
+    : Flags;
+
+/**
+ * Base variant of Flags that does not automatically set unspecified
+ * flags `([key:string]: ...)`
+ */
+export type BaseFlags<TExtraFlags extends UnspecifiedFlags = {}> = {
+  verbose: boolean;
+  quiet: boolean;
+  silent: boolean;
+  debug: boolean;
+  help: boolean;
+  _: string[];
+  unexpected: string[];
+} & TExtraFlags;
+
+export type Flags = BaseFlags<UnspecifiedFlags>;
+
+export interface FlagOptions {
+  allowUnexpected?: boolean;
+  guessTypesForUnexpectedFlags?: boolean;
+  help?: string;
+  examples?: string;
+  alias?: { [key: string]: string | string[] };
+  boolean?: string[];
+  string?: string[];
+  default?: { [key: string]: any };
+}

src/platform/packages/shared/kbn-dev-cli-runner/src/flags_reader.ts renamed to src/platform/packages/shared/kbn-dev-cli-runner/src/flags/flags_reader.ts

@@ -8,7 +8,7 @@
  */
 
 import { getCommandLevelHelp, getHelp, getHelpForAllCommands } from './help';
-import type { Command } from './run_with_commands';
+import type { Command } from './run/run_with_commands';
 
 const fooCommand: Command<any> = {
   description: `

src/platform/packages/shared/kbn-dev-cli-runner/src/flags/types.ts

@@ -13,7 +13,7 @@ import chalk from 'chalk';
 import dedent from 'dedent';
 import { getLogLevelFlagsHelp } from '@kbn/tooling-log';
 
-import type { Command } from './run_with_commands';
+import type { Command } from './run/run_with_commands';
 
 const DEFAULT_GLOBAL_USAGE = `node ${Path.relative(process.cwd(), process.argv[1])}`;
 export const GLOBAL_FLAGS = dedent`

src/platform/packages/shared/kbn-dev-cli-runner/src/help.test.ts

@@ -7,42 +7,26 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-import type { LogLevel } from '@kbn/tooling-log';
-import { pickLevelFromFlags, ToolingLog } from '@kbn/tooling-log';
-import type { ProcRunner } from '@kbn/dev-proc-runner';
-import { withProcRunner } from '@kbn/dev-proc-runner';
 import { createFlagError } from '@kbn/dev-cli-errors';
+import { withProcRunner } from '@kbn/dev-proc-runner';
+import { ToolingLog, pickLevelFromFlags } from '@kbn/tooling-log';
+import { Cleanup } from '../cleanup';
+import { DEFAULT_FLAG_ALIASES, getFlags } from '../flags/flags';
+import { FlagsReader } from '../flags/flags_reader';
+import { getHelp } from '../help';
+import { Metrics } from '../metrics';
+import type { RunFn, RunOptions } from './types';
+import type { FlagOptions, Flags, FlagsOf } from '../flags/types';
 
-import type { Flags, FlagOptions } from './flags';
-import { getFlags, DEFAULT_FLAG_ALIASES } from './flags';
-import { FlagsReader } from './flags_reader';
-import { getHelp } from './help';
-import type { CleanupTask } from './cleanup';
-import { Cleanup } from './cleanup';
-import type { MetricsMeta } from './metrics';
-import { Metrics } from './metrics';
-
-export interface RunContext {
-  log: ToolingLog;
-  flags: Flags;
-  procRunner: ProcRunner;
-  statsMeta: MetricsMeta;
-  addCleanupTask: (task: CleanupTask) => void;
-  flagsReader: FlagsReader;
-}
-export type RunFn<T = void> = (context: RunContext) => Promise<T> | void;
-
-export interface RunOptions {
-  usage?: string;
-  description?: string;
-  log?: {
-    defaultLevel?: LogLevel;
-    context?: string;
-  };
-  flags?: FlagOptions;
-}
+export async function run<T, TFlagOptions extends FlagOptions = FlagOptions>(
+  fn: RunFn<T, FlagsOf<TFlagOptions>>,
+  options?: RunOptions<TFlagOptions>
+): Promise<T | undefined>;
 
-export async function run<T>(fn: RunFn<T>, options: RunOptions = {}): Promise<T | undefined> {
+export async function run<T>(
+  fn: RunFn<T, Flags>,
+  options: RunOptions = {}
+): Promise<T | undefined> {
   const flags = getFlags(process.argv.slice(2), options.flags, options.log?.defaultLevel);
   const log = new ToolingLog(
     {