@rushstack/rundown 1.0.213 → 1.0.216

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rundown",
-  "version": "1.0.213",
+  "version": "1.0.216",
   "description": "Detect load time regressions by running an app, tracing require() calls, and generating a deterministic report",
   "repository": {
     "type": "git",
@@ -17,20 +17,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@rushstack/node-core-library": "3.51.0",
+    "@rushstack/node-core-library": "3.51.1",
     "@rushstack/ts-command-line": "4.12.2",
     "string-argv": "~0.3.1"
   },
   "devDependencies": {
     "@rushstack/eslint-config": "3.0.0",
-    "@rushstack/heft": "0.47.4",
-    "@rushstack/heft-node-rig": "1.10.4",
+    "@rushstack/heft": "0.47.5",
+    "@rushstack/heft-node-rig": "1.10.7",
     "@types/heft-jest": "1.0.1",
     "@types/node": "12.20.24"
   },
   "scripts": {
     "build": "heft build --clean",
     "_phase:build": "heft build --clean"
-  },
-  "readme": "# @rushstack/rundown\n\nSlow startup times for Node.js commands or services?  **Rundown** can invoke a Node.js process and:\n\n1. **View imported files:** Intercept all `require()` calls and show which paths were loaded.\n2. **Find culprits:** Show the chain for `require()` calls for each import, explaining why it was imported.\n3. **Detect regressions over time:** Generate a concise \"snapshot\" report that can be committed to Git.  Changes\n   to this file may indicate potential performance regressions.\n\n\n## Installation\n\nYou can install this tool globally:\n\n```shell\n$ npm install --global @rushstack/rundown\n\n# View command line help\n$ rundown --help\n```\n\nIf you will generate rundown snapshots during your build, it is recommended to install via `devDependencies`:\n\n```shell\n$ cd my-tool\n$ npm install @rushstack/rundown --save-dev\n```\n\n\n## Viewing imported files\n\nSuppose you maintain a small NPM project that is invoked as follows:\n\n```shell\n# The folder where your tool is developed\n$ cd my-tool\n\n# When you invoke \"my-tool --my-option 123 --verbose\" from the shell, let's suppose that it invokes\n# this Node.js command:\n$ node lib/start.js --my-option 123 --verbose\n```\n\nAnd suppose that your tool's startup time is rather slow, because the code calls `require()` to load many different\nNPM packages.  We can create a report to see all the imports:\n\n```shell\n# We use \"--args\" to pass the command-line arguments for \"my-tool\"\n$ rundown inspect --script lib/start.js --args=\"--my-option 123 --verbose\"\n```\n\nThe report may look like this:\n\n**rundown-inspect.log**\n```\n/path/to/my-tool/lib/start.js\n/path/to/my-tool/node_modules/at-least-node/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/copy-sync/copy-sync.js\n/path/to/my-tool/node_modules/fs-extra/lib/copy-sync/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/copy/copy.js\n/path/to/my-tool/node_modules/fs-extra/lib/copy/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/empty/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/file.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/link.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink-paths.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink-type.js\n/path/to/my-tool/node_modules/fs-extra/lib/ensure/symlink.js\n/path/to/my-tool/node_modules/fs-extra/lib/fs/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/json/jsonfile.js\n/path/to/my-tool/node_modules/fs-extra/lib/json/output-json-sync.js\n/path/to/my-tool/node_modules/fs-extra/lib/json/output-json.js\n/path/to/my-tool/node_modules/fs-extra/lib/mkdirs/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/mkdirs/make-dir.js\n/path/to/my-tool/node_modules/fs-extra/lib/move-sync/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/move-sync/move-sync.js\n/path/to/my-tool/node_modules/fs-extra/lib/move/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/move/move.js\n/path/to/my-tool/node_modules/fs-extra/lib/output/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/path-exists/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/remove/index.js\n/path/to/my-tool/node_modules/fs-extra/lib/remove/rimraf.js\n/path/to/my-tool/node_modules/fs-extra/lib/util/stat.js\n/path/to/my-tool/node_modules/fs-extra/lib/util/utimes.js\n/path/to/my-tool/node_modules/graceful-fs/clone.js\n/path/to/my-tool/node_modules/graceful-fs/graceful-fs.js\n/path/to/my-tool/node_modules/graceful-fs/legacy-streams.js\n/path/to/my-tool/node_modules/graceful-fs/polyfills.js\n/path/to/my-tool/node_modules/jsonfile/index.js\n/path/to/my-tool/node_modules/jsonfile/utils.js\n/path/to/my-tool/node_modules/universalify/index.js\n```\n\n## Finding callers\n\nTo see how each file is imported, you can add the `--trace-imports` switch.\n```shell\n# We use \"--args\" to pass the command-line arguments for \"my-tool\"\n$ rundown inspect --script lib/start.js --args=\"--my-option 123 --verbose\" --trace-imports\n```\n\nThe report now shows more detail:\n\n**rundown-inspect.log**\n```\n. . .\n/path/to/my-tool/node_modules/graceful-fs/legacy-streams.js\n  imported by /path/to/my-tool/node_modules/graceful-fs/graceful-fs.js\n  imported by /path/to/my-tool/node_modules/fs-extra/lib/fs/index.js\n  imported by /path/to/my-tool/node_modules/fs-extra/lib/index.js\n  imported by /path/to/my-tool/lib/start.js\n  imported by /rundown/lib/launcher.js\n\n/path/to/my-tool/node_modules/graceful-fs/polyfills.js\n  imported by /path/to/my-tool/node_modules/graceful-fs/graceful-fs.js\n  imported by /path/to/my-tool/node_modules/fs-extra/lib/fs/index.js\n  imported by /path/to/my-tool/node_modules/fs-extra/lib/index.js\n  imported by /path/to/my-tool/lib/start.js\n  imported by rundown/lib/launcher.js\n. . .\n```\n\n## Fixing problems\n\nIt may be the case that many of these imports are not actually used.  You can avoid preloading them\nby converting them to lazy imports using the `Import.lazy()` from\n[@rushstack/node-core-library](https://www.npmjs.com/package/@rushstack/node-core-library)\nor [import-lazy](https://www.npmjs.com/package/import-lazy).\n\n\n## Generating a snapshot\n\nTo detect future regressions, use the `rundown snapshot` command to write a snapshot file:\n\n```shell\n# We use \"--args\" to pass the command-line arguments for \"my-tool\"\n$ rundown snapshot --script lib/start.js --args=\"--my-option 123 --verbose\"\n\n# This file can be committed to Git to track regressions\n$ git add rundown-snapshot.log\n```\n\nThe snapshot file format eliminates spurious diffs, by showing only the names of the imported packages.\nFor local projects in a monorepo, it will show relative paths.  Example output:\n\n**rundown-snapshot.log**\n```\n../path/to/monorepo-sibling\nat-least-node\nfs-extra\ngraceful-fs\njsonfile\nuniversalify\n```\n\n## Command-line reference\n\n```\nusage: rundown [-h] <command> ...\n\nDetect load time regressions by running an app, tracing require() calls, and\ngenerating a deterministic report\n\nPositional arguments:\n  <command>\n    snapshot  Invoke a Node.js script and generate a test snapshot\n    inspect   Invoke a Node.js script and generate detailed diagnostic output\n\nOptional arguments:\n  -h, --help  Show this help message and exit.\n\nFor detailed help about a specific command, use: rundown <command> -h\n```\n\n```\nusage: rundown snapshot [-h] -s PATH [-a STRING] [-q] [-i]\n\nInvoke a Node.js script and generate a test snapshot. This command creates a\nconcise report that can be added to Git, so that its diff can be used to\ndetect performance regressions\n\nOptional arguments:\n  -h, --help            Show this help message and exit.\n  -s PATH, --script PATH\n                        The path to a .js file that will be the entry point\n                        for the target Node.js process\n  -a STRING, --args STRING\n                        Specifies command-line arguments to be passed to the\n                        target Node.js process. The value should be a single\n                        text string delimited by spaces. Example: rundown\n                        inspect --scripts ./example.js --args=\"--flag\n                        --option=123\"\n  -q, --quiet           Suppress STDOUT/STDERR for the target Node.js process\n  -i, --ignore-exit-code\n                        Do not report an error if the target Node.js process\n                        returns a nonzero exit code\n```\n\n```\nusage: rundown inspect [-h] -s PATH [-a STRING] [-q] [-i] [-t]\n\nInvoke a Node.js script and generate detailed diagnostic output. This command\nis used to inspect performance regressions.\n\nOptional arguments:\n  -h, --help            Show this help message and exit.\n  -s PATH, --script PATH\n                        The path to a .js file that will be the entry point\n                        for the target Node.js process\n  -a STRING, --args STRING\n                        Specifies command-line arguments to be passed to the\n                        target Node.js process. The value should be a single\n                        text string delimited by spaces. Example: rundown\n                        inspect --scripts ./example.js --args=\"--flag\n                        --option=123\"\n  -q, --quiet           Suppress STDOUT/STDERR for the target Node.js process\n  -i, --ignore-exit-code\n                        Do not report an error if the target Node.js process\n                        returns a nonzero exit code\n  -t, --trace-imports   Reports the call chain for each module path, showing\n                        how it was imported\n```\n\n## Links\n\n- [CHANGELOG.md](\n  https://github.com/microsoft/rushstack/blob/main/apps/rundown/CHANGELOG.md) - Find\n  out what's new in the latest version\n\nRundown is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
+  }
 }