@rushstack/trace-import 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/trace-import
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @microsoft/trace-import
+
+> 🚨 *EARLY PREVIEW RELEASE* 🚨
+>
+> Not all features are implemented yet.  To provide suggestions, please
+> [create a GitHub issue](https://github.com/microsoft/rushstack/issues/new/choose).
+> If you have questions, see the [Rush Stack Help page](https://rushstack.io/pages/help/support/)
+> for support resources.
+
+The `trace-import` command line tool helps you:
+
+- Analyze `import`/`require()` statements to understand why they aren't resolving correctly
+- Understand the relationships between package folders in your `node_modules` tree
+- Ensure that `package.json` files correctly export their .js and .d.ts entry points
+
+## Usage
+
+It's recommended to install this package globally:
+
+```
+# Install the NPM package
+npm install -g @rushstack/trace-import
+
+# View the command-line help
+trace-import --help
+```
+
+## Command line
+
+```
+usage: trace-import [-h] [-d] -p IMPORT_PATH [-b FOLDER_PATH] [-t {cjs,es,ts}]
+
+This tool analyzes import module paths, to determine the resolved target
+folder. For example, if the "semver" NPM package is installed, "trace-import
+--path semver/index" will print output equivalent to the Node.js require.
+resolve() API. If "@types/semver" is installed, then "trace-import
+--resolution-type ts --path semver/index" will print the .d.ts file path that
+would be resolved by a TypeScript import statement.
+
+Optional arguments:
+  -h, --help            Show this help message and exit.
+  -d, --debug           Show the full call stack if an error occurs while
+                        executing the tool
+  -p IMPORT_PATH, --path IMPORT_PATH
+                        The import module path to be analyzed. For example,
+                        "example" in expressions such as: require("example");
+                        require.resolve("example"); import { Thing } from
+                        "example";
+  -b FOLDER_PATH, --base-folder FOLDER_PATH
+                        The "--path" string will be resolved as if the import
+                        statement appeared in a script located in this folder.
+                         If omitted, the current working directory is used.
+  -t {cjs,es,ts}, --resolution-type {cjs,es,ts}
+                        The type of module resolution to perform: "cjs" for
+                        CommonJS, "es" for ES modules, or "ts" for TypeScript
+                        typings. The default value is "cjs".
+```
+
+## Sample outputs
+
+These commands were invoked in the `C:\Git\rushstack\apps\trace-import` folder
+where trace-import is developed.
+
+### Resolving a CommonJS main index
+```
+trace-import --path semver
+```
+
+Sample output:
+```
+Base folder:             C:\Git\rushstack\apps\trace-import
+Package name:            semver
+Package subpath:         (not specified)
+
+Resolving...
+
+Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\semver@7.3.8\node_modules\semver
+package.json:            semver (7.3.8)
+Main index:              "main": "index.js"
+
+Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\semver@7.3.8\node_modules\semver\index.js
+```
+
+### Resolving a CommonJS package subpath
+```
+trace-import --path typescript/bin/tsc
+```
+
+Sample output:
+```
+Base folder:             C:\Git\rushstack\apps\trace-import
+Package name:            typescript
+Package subpath:         bin/tsc
+
+Resolving...
+
+Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\typescript@4.8.4\node_modules\typescript
+package.json:            typescript (4.8.4)
+
+Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\typescript@4.8.4\node_modules\typescript\bin\tsc
+```
+
+### Resolving a TypeScript declaration
+```
+trace-import --resolution-type ts --path semver
+```
+
+Sample output:
+```
+Base folder:             C:\Git\rushstack\apps\trace-import
+Package name:            semver
+Package subpath:         (not specified)
+
+Resolving...
+
+Package folder:          C:\Git\rushstack\common\temp\node_modules\.pnpm\semver@7.3.8\node_modules\semver
+package.json:            semver (7.3.8)
+@types folder:           C:\Git\rushstack\common\temp\node_modules\.pnpm\@types+semver@7.3.5\node_modules\@types\semver
+@types package.json:     @types/semver (7.3.5)
+@types main index:       "types": "index.d.ts"
+
+Target path:             C:\Git\rushstack\common\temp\node_modules\.pnpm\@types+semver@7.3.5\node_modules\@types\semver\index.d.ts
+```
+
+### Resolving a relative path
+```
+trace-import --path ./config/rig.json
+```
+
+Sample output:
+```
+Base folder:             C:\Git\rushstack\apps\trace-import
+Import path:             ./config/rig.json
+
+The import path does not appear to reference an NPM package.
+Resolving...
+
+Target path:             C:\Git\rushstack\apps\trace-import\config\rig.json
+```
+
+## Links
+
+- [CHANGELOG.md](
+  https://github.com/microsoft/rushstack/blob/main/apps/trace-import/CHANGELOG.md) - Find
+  out what's new in the latest version
+- [Rush Lockfile Explorer](https://lfx.rushstack.io) - The desktop app for troubleshooting PNPM lockfiles
+
+The `trace-import` tool is part of the [Rush Stack](https://rushstack.io/) family of projects.

package/bin/trace-import

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../lib/start.js');

package/lib/TraceImportCommandLineParser.d.ts

@@ -0,0 +1,10 @@
+import { CommandLineParser } from '@rushstack/ts-command-line';
+export declare class TraceImportCommandLineParser extends CommandLineParser {
+    private readonly _debugParameter;
+    private readonly _pathParameter;
+    private readonly _baseFolderParameter;
+    private readonly _resolutionTypeParameter;
+    constructor();
+    protected onExecute(): Promise<void>;
+}
+//# sourceMappingURL=TraceImportCommandLineParser.d.ts.map

package/lib/TraceImportCommandLineParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TraceImportCommandLineParser.d.ts","sourceRoot":"","sources":["../src/TraceImportCommandLineParser.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,iBAAiB,EAIlB,MAAM,4BAA4B,CAAC;AAKpC,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAA6B;;cAiDtD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB3C"}

package/lib/TraceImportCommandLineParser.js

@@ -0,0 +1,76 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceImportCommandLineParser = void 0;
+const safe_1 = __importDefault(require("colors/safe"));
+const ts_command_line_1 = require("@rushstack/ts-command-line");
+const node_core_library_1 = require("@rushstack/node-core-library");
+const traceImport_1 = require("./traceImport");
+class TraceImportCommandLineParser extends ts_command_line_1.CommandLineParser {
+    constructor() {
+        super({
+            toolFilename: 'trace-import',
+            toolDescription: 'This tool analyzes import module paths, to determine the resolved target folder.  ' +
+                'For example, if the "semver" NPM package is installed, "trace-import --path semver/index" will ' +
+                'print output equivalent to the Node.js require.resolve() API.  ' +
+                'If "@types/semver" is installed, then "trace-import --resolution-type ts --path semver/index" will ' +
+                'print the .d.ts file path that would be resolved by a TypeScript import statement.'
+        });
+        this._debugParameter = this.defineFlagParameter({
+            parameterLongName: '--debug',
+            parameterShortName: '-d',
+            description: 'Show the full call stack if an error occurs while executing the tool'
+        });
+        this._pathParameter = this.defineStringParameter({
+            parameterLongName: '--path',
+            parameterShortName: '-p',
+            description: 'The import module path to be analyzed. For example, ' +
+                '"example" in expressions such as: require("example"); require.resolve("example"); import { Thing } from "example";',
+            argumentName: 'IMPORT_PATH',
+            required: true
+        });
+        this._baseFolderParameter = this.defineStringParameter({
+            parameterLongName: '--base-folder',
+            parameterShortName: '-b',
+            description: 'The "--path" string will be resolved as if the import statement appeared in a script located in this folder.  ' +
+                'If omitted, the current working directory is used.',
+            argumentName: 'FOLDER_PATH'
+        });
+        this._resolutionTypeParameter = this.defineChoiceParameter({
+            parameterLongName: '--resolution-type',
+            parameterShortName: '-t',
+            description: 'The type of module resolution to perform:  ' +
+                '"cjs" for CommonJS, "es" for ES modules, or "ts" for TypeScript typings',
+            alternatives: ['cjs', 'es', 'ts'],
+            defaultValue: 'cjs'
+        });
+    }
+    async onExecute() {
+        var _a;
+        // override
+        if (this._debugParameter.value) {
+            node_core_library_1.InternalError.breakInDebugger = true;
+        }
+        try {
+            (0, traceImport_1.traceImport)({
+                importPath: this._pathParameter.value,
+                baseFolder: this._baseFolderParameter.value,
+                resolutionType: ((_a = this._resolutionTypeParameter.value) !== null && _a !== void 0 ? _a : 'cjs')
+            });
+        }
+        catch (error) {
+            if (this._debugParameter.value) {
+                console.error('\n' + error.stack);
+            }
+            else {
+                console.error('\n' + safe_1.default.red('ERROR: ' + error.message.trim()));
+            }
+        }
+    }
+}
+exports.TraceImportCommandLineParser = TraceImportCommandLineParser;
+//# sourceMappingURL=TraceImportCommandLineParser.js.map

package/lib/TraceImportCommandLineParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TraceImportCommandLineParser.js","sourceRoot":"","sources":["../src/TraceImportCommandLineParser.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;;;;AAE3D,uDAAiC;AACjC,gEAKoC;AACpC,oEAA6D;AAE7D,+CAA4D;AAE5D,MAAa,4BAA6B,SAAQ,mCAAiB;IAMjE;QACE,KAAK,CAAC;YACJ,YAAY,EAAE,cAAc;YAC5B,eAAe,EACb,oFAAoF;gBACpF,iGAAiG;gBACjG,iEAAiE;gBACjE,qGAAqG;gBACrG,oFAAoF;SACvF,CAAC,CAAC;QAEH,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC9C,iBAAiB,EAAE,SAAS;YAC5B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EAAE,sEAAsE;SACpF,CAAC,CAAC;QAEH,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,qBAAqB,CAAC;YAC/C,iBAAiB,EAAE,QAAQ;YAC3B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EACT,sDAAsD;gBACtD,oHAAoH;YACtH,YAAY,EAAE,aAAa;YAC3B,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;QAEH,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,qBAAqB,CAAC;YACrD,iBAAiB,EAAE,eAAe;YAClC,kBAAkB,EAAE,IAAI;YACxB,WAAW,EACT,gHAAgH;gBAChH,oDAAoD;YACtD,YAAY,EAAE,aAAa;SAC5B,CAAC,CAAC;QAEH,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC,qBAAqB,CAAC;YACzD,iBAAiB,EAAE,mBAAmB;YACtC,kBAAkB,EAAE,IAAI;YACxB,WAAW,EACT,6CAA6C;gBAC7C,yEAAyE;YAC3E,YAAY,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC;YACjC,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;IAES,KAAK,CAAC,SAAS;;QACvB,WAAW;QACX,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE;YAC9B,iCAAa,CAAC,eAAe,GAAG,IAAI,CAAC;SACtC;QACD,IAAI;YACF,IAAA,yBAAW,EAAC;gBACV,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,KAAM;gBACtC,UAAU,EAAE,IAAI,CAAC,oBAAoB,CAAC,KAAK;gBAC3C,cAAc,EAAE,CAAC,MAAA,IAAI,CAAC,wBAAwB,CAAC,KAAK,mCAAI,KAAK,CAAmB;aACjF,CAAC,CAAC;SACJ;QAAC,OAAO,KAAK,EAAE;YACd,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE;gBAC9B,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;aACnC;iBAAM;gBACL,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,cAAM,CAAC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;aACpE;SACF;IACH,CAAC;CACF;AAxED,oEAwEC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport colors from 'colors/safe';\nimport {\n  CommandLineParser,\n  CommandLineFlagParameter,\n  CommandLineStringParameter,\n  CommandLineChoiceParameter\n} from '@rushstack/ts-command-line';\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport { ResolutionType, traceImport } from './traceImport';\n\nexport class TraceImportCommandLineParser extends CommandLineParser {\n  private readonly _debugParameter: CommandLineFlagParameter;\n  private readonly _pathParameter: CommandLineStringParameter;\n  private readonly _baseFolderParameter: CommandLineStringParameter;\n  private readonly _resolutionTypeParameter: CommandLineChoiceParameter;\n\n  public constructor() {\n    super({\n      toolFilename: 'trace-import',\n      toolDescription:\n        'This tool analyzes import module paths, to determine the resolved target folder.  ' +\n        'For example, if the \"semver\" NPM package is installed, \"trace-import --path semver/index\" will ' +\n        'print output equivalent to the Node.js require.resolve() API.  ' +\n        'If \"@types/semver\" is installed, then \"trace-import --resolution-type ts --path semver/index\" will ' +\n        'print the .d.ts file path that would be resolved by a TypeScript import statement.'\n    });\n\n    this._debugParameter = this.defineFlagParameter({\n      parameterLongName: '--debug',\n      parameterShortName: '-d',\n      description: 'Show the full call stack if an error occurs while executing the tool'\n    });\n\n    this._pathParameter = this.defineStringParameter({\n      parameterLongName: '--path',\n      parameterShortName: '-p',\n      description:\n        'The import module path to be analyzed. For example, ' +\n        '\"example\" in expressions such as: require(\"example\"); require.resolve(\"example\"); import { Thing } from \"example\";',\n      argumentName: 'IMPORT_PATH',\n      required: true\n    });\n\n    this._baseFolderParameter = this.defineStringParameter({\n      parameterLongName: '--base-folder',\n      parameterShortName: '-b',\n      description:\n        'The \"--path\" string will be resolved as if the import statement appeared in a script located in this folder.  ' +\n        'If omitted, the current working directory is used.',\n      argumentName: 'FOLDER_PATH'\n    });\n\n    this._resolutionTypeParameter = this.defineChoiceParameter({\n      parameterLongName: '--resolution-type',\n      parameterShortName: '-t',\n      description:\n        'The type of module resolution to perform:  ' +\n        '\"cjs\" for CommonJS, \"es\" for ES modules, or \"ts\" for TypeScript typings',\n      alternatives: ['cjs', 'es', 'ts'],\n      defaultValue: 'cjs'\n    });\n  }\n\n  protected async onExecute(): Promise<void> {\n    // override\n    if (this._debugParameter.value) {\n      InternalError.breakInDebugger = true;\n    }\n    try {\n      traceImport({\n        importPath: this._pathParameter.value!,\n        baseFolder: this._baseFolderParameter.value,\n        resolutionType: (this._resolutionTypeParameter.value ?? 'cjs') as ResolutionType\n      });\n    } catch (error) {\n      if (this._debugParameter.value) {\n        console.error('\\n' + error.stack);\n      } else {\n        console.error('\\n' + colors.red('ERROR: ' + error.message.trim()));\n      }\n    }\n  }\n}\n"]}

package/lib/start.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=start.d.ts.map

package/lib/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":""}

package/lib/start.js

@@ -0,0 +1,19 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const safe_1 = __importDefault(require("colors/safe"));
+const node_core_library_1 = require("@rushstack/node-core-library");
+const TraceImportCommandLineParser_1 = require("./TraceImportCommandLineParser");
+const toolVersion = node_core_library_1.PackageJsonLookup.loadOwnPackageJson(__dirname).version;
+console.log();
+console.log(safe_1.default.bold(`trace-import ${toolVersion}`) + ' - ' + safe_1.default.cyan('https://rushstack.io'));
+console.log();
+const commandLine = new TraceImportCommandLineParser_1.TraceImportCommandLineParser();
+commandLine.execute().catch((error) => {
+    console.error(error);
+});
+//# sourceMappingURL=start.js.map

package/lib/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;;;AAE3D,uDAAiC;AAEjC,oEAAiE;AACjE,iFAA8E;AAE9E,MAAM,WAAW,GAAW,qCAAiB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;AAEpF,OAAO,CAAC,GAAG,EAAE,CAAC;AACd,OAAO,CAAC,GAAG,CAAC,cAAM,CAAC,IAAI,CAAC,gBAAgB,WAAW,EAAE,CAAC,GAAG,KAAK,GAAG,cAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC;AACtG,OAAO,CAAC,GAAG,EAAE,CAAC;AAEd,MAAM,WAAW,GAAiC,IAAI,2DAA4B,EAAE,CAAC;AACrF,WAAW,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACpC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport colors from 'colors/safe';\n\nimport { PackageJsonLookup } from '@rushstack/node-core-library';\nimport { TraceImportCommandLineParser } from './TraceImportCommandLineParser';\n\nconst toolVersion: string = PackageJsonLookup.loadOwnPackageJson(__dirname).version;\n\nconsole.log();\nconsole.log(colors.bold(`trace-import ${toolVersion}`) + ' - ' + colors.cyan('https://rushstack.io'));\nconsole.log();\n\nconst commandLine: TraceImportCommandLineParser = new TraceImportCommandLineParser();\ncommandLine.execute().catch((error) => {\n  console.error(error);\n});\n"]}

package/lib/traceImport.d.ts

@@ -0,0 +1,9 @@
+export declare type ResolutionType = 'cjs' | 'es' | 'ts';
+interface IExecuteOptions {
+    importPath: string;
+    baseFolder: string | undefined;
+    resolutionType: ResolutionType;
+}
+export declare function traceImport(options: IExecuteOptions): void;
+export {};
+//# sourceMappingURL=traceImport.d.ts.map

package/lib/traceImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceImport.d.ts","sourceRoot":"","sources":["../src/traceImport.ts"],"names":[],"mappings":"AAkBA,oBAAY,cAAc,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjD,UAAU,eAAe;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,cAAc,EAAE,cAAc,CAAC;CAChC;AAqSD,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAY1D"}

package/lib/traceImport.js

@@ -0,0 +1,302 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceImport = void 0;
+const node_core_library_1 = require("@rushstack/node-core-library");
+const safe_1 = __importDefault(require("colors/safe"));
+const path = __importStar(require("path"));
+const process = __importStar(require("process"));
+const Resolve = __importStar(require("resolve"));
+const jsExtensions = ['.js', '.cjs', '.jsx', '.json'];
+const tsExtensions = ['.d.ts', '.ts', '.tsx', '.json'];
+// Somewhat loosely matches inputs such as:
+//   my-package/path/to/file.js
+//   [group 1 ][group 2       ]
+//
+//   @scope/my-package/path/to/file.js
+//   [group 1        ][group 2       ]
+//
+//   @scope/my-package
+//   [group 1        ]
+const packageImportPathRegExp = /^((?:@[a-z0-9_][a-z0-9\-_\.]*\/)?[a-z0-9_][a-z0-9\-_\.]*)(\/.*)?$/i;
+function logInputField(title, value) {
+    console.log(safe_1.default.cyan(title.padEnd(25)) + value);
+}
+function logOutputField(title, value) {
+    console.log(safe_1.default.green(title.padEnd(25)) + value);
+}
+function traceTypeScriptPackage(options) {
+    const { packageSubpath, packageFolder, packageJson, atTypes, warnings } = options;
+    // For example, if we started with importFullPath="semver/index",
+    // here we may get normalizedImportFullPath="@types/semver/index"
+    const normalizedImportFullPath = packageJson.name + packageSubpath;
+    // First try to resolve the .js main index
+    let cjsTargetPath = undefined;
+    try {
+        cjsTargetPath = Resolve.sync(normalizedImportFullPath, {
+            basedir: packageFolder,
+            preserveSymlinks: false,
+            extensions: jsExtensions
+        });
+    }
+    catch (error) {
+        // not found
+    }
+    const mainIndexTitle = atTypes ? '@types main index:' : 'Main index:';
+    if (cjsTargetPath) {
+        const parsedPath = path.parse(cjsTargetPath);
+        // Is the resolved .js extension okay?
+        if (tsExtensions.indexOf(parsedPath.ext.toLocaleLowerCase()) >= 0) {
+            logOutputField(mainIndexTitle, '(inferred from .js main index)');
+            console.log();
+            logOutputField('Target path:', cjsTargetPath);
+            return true;
+        }
+        // Try to replace the file extension
+        const dtsTargetPath = path.join(parsedPath.dir, parsedPath.name + '.d.ts');
+        if (node_core_library_1.FileSystem.exists(dtsTargetPath)) {
+            logOutputField(mainIndexTitle, '(inferred from .js entry point)');
+            console.log();
+            logOutputField('Target path:', dtsTargetPath);
+            return true;
+        }
+    }
+    if (!packageSubpath) {
+        // Try importing the "types"/"typings" main index:
+        if (packageJson.types) {
+            logOutputField(mainIndexTitle, `"types": ${JSON.stringify(packageJson.types)}`);
+            console.log();
+            logOutputField('Target path:', path.join(packageFolder, packageJson.types));
+            return true;
+        }
+        if (packageJson.typings) {
+            logOutputField(mainIndexTitle, `"typings": ${JSON.stringify(packageJson.typings)}`);
+            console.log();
+            logOutputField('Target path:', path.join(packageFolder, packageJson.typings));
+            return true;
+        }
+        if (atTypes) {
+            warnings.push('The @types package does not define "types" or "typings" field.');
+        }
+    }
+    else {
+        // Try importing the .d.ts file directly
+        let dtsTargetPath = undefined;
+        try {
+            dtsTargetPath = Resolve.sync(normalizedImportFullPath, {
+                basedir: packageFolder,
+                preserveSymlinks: false,
+                extensions: tsExtensions
+            });
+        }
+        catch (error) {
+            // not found
+        }
+        if (dtsTargetPath) {
+            console.log();
+            logOutputField('Target path:', dtsTargetPath);
+            return true;
+        }
+    }
+    return false;
+}
+function traceImportInner(options, warnings) {
+    let baseFolder;
+    if (options.baseFolder) {
+        baseFolder = path.resolve(options.baseFolder);
+    }
+    else {
+        baseFolder = process.cwd();
+    }
+    const importFullPath = options.importPath.trim();
+    if (!importFullPath) {
+        throw new Error(`Invalid import path syntax: ${JSON.stringify(importFullPath)}`);
+    }
+    const match = packageImportPathRegExp.exec(importFullPath);
+    logInputField('Base folder:', baseFolder);
+    if (match) {
+        const importPackageName = match[1];
+        const packageSubpath = match[2];
+        const packageSubpathWithoutSlash = packageSubpath
+            ? packageSubpath.substring(1)
+            : undefined;
+        logInputField('Package name:', importPackageName);
+        logInputField('Package subpath:', packageSubpathWithoutSlash || '(not specified)');
+        console.log('\nResolving...\n');
+        // Resolve the NPM package first
+        let packageFolder;
+        let packageJson = undefined;
+        {
+            let resolvedPackageJsonPath;
+            try {
+                resolvedPackageJsonPath = Resolve.sync(`${importPackageName}/package.json`, {
+                    basedir: baseFolder,
+                    preserveSymlinks: false
+                });
+            }
+            catch (e) {
+                // Could not find NPM package
+            }
+            if (resolvedPackageJsonPath) {
+                packageFolder = path.dirname(resolvedPackageJsonPath);
+                logOutputField('Package folder:', packageFolder);
+                packageJson = node_core_library_1.JsonFile.load(resolvedPackageJsonPath);
+                logOutputField('package.json:', `${packageJson.name || '(missing name)'} (${packageJson.version || 'missing version'})`);
+            }
+        }
+        // Also try to resolve the @types package
+        let atTypesPackageFolder = undefined;
+        let atTypesPackageJson = undefined;
+        if (options.resolutionType === 'ts') {
+            if (!importPackageName.startsWith('@types/')) {
+                const parsedPackageName = node_core_library_1.PackageName.parse(importPackageName);
+                let atTypesPackageName;
+                if (parsedPackageName.scope) {
+                    atTypesPackageName = `@types/${parsedPackageName.scope}__${parsedPackageName.unscopedName}`;
+                }
+                else {
+                    atTypesPackageName = `@types/${parsedPackageName.unscopedName}`;
+                }
+                let atTypesPackageJsonPath;
+                try {
+                    atTypesPackageJsonPath = Resolve.sync(`${atTypesPackageName}/package.json`, {
+                        basedir: baseFolder,
+                        preserveSymlinks: false
+                    });
+                }
+                catch (e) {
+                    // Unable to resolve @types package
+                }
+                if (atTypesPackageJsonPath) {
+                    atTypesPackageFolder = path.dirname(atTypesPackageJsonPath);
+                    logOutputField('@types folder:', atTypesPackageFolder);
+                    atTypesPackageJson = node_core_library_1.JsonFile.load(atTypesPackageJsonPath);
+                    logOutputField('@types package.json:', `${atTypesPackageJson.name || '(missing name)'} (${atTypesPackageJson.version || 'missing version'})`);
+                }
+            }
+        }
+        switch (options.resolutionType) {
+            case 'cjs':
+                {
+                    if (!packageFolder || !packageJson) {
+                        throw new Error(`Cannot find package "${importPackageName}" from "${baseFolder}".`);
+                    }
+                    if (!packageSubpath) {
+                        if (packageJson.main) {
+                            logOutputField('Main index:', `"main": ${JSON.stringify(packageJson.main)}`);
+                        }
+                        else {
+                            logOutputField('Main index:', '(none)');
+                        }
+                    }
+                    let targetPath;
+                    try {
+                        targetPath = Resolve.sync(importFullPath, {
+                            basedir: packageFolder,
+                            preserveSymlinks: false,
+                            extensions: jsExtensions
+                        });
+                    }
+                    catch (error) {
+                        // Are we importing the main index?
+                        if (packageSubpath) {
+                            throw new Error(`Unable to resolve the module subpath: ...${packageSubpath}`);
+                        }
+                        else {
+                            console.log('\nThis package does not define a main index.');
+                            return;
+                        }
+                    }
+                    console.log();
+                    logOutputField('Target path:', targetPath);
+                }
+                break;
+            case 'ts':
+                if (!packageFolder || (!packageJson && !atTypesPackageFolder && !atTypesPackageJson)) {
+                    throw new Error(`Cannot find package "${importPackageName}" from "${baseFolder}".`);
+                }
+                if (packageFolder && packageJson) {
+                    if (traceTypeScriptPackage({ packageSubpath, packageFolder, packageJson, warnings })) {
+                        if (atTypesPackageFolder) {
+                            warnings.push('An @types package was found but not used.');
+                        }
+                        return;
+                    }
+                }
+                if (atTypesPackageFolder && atTypesPackageJson) {
+                    if (traceTypeScriptPackage({
+                        packageSubpath,
+                        packageFolder: atTypesPackageFolder,
+                        packageJson: atTypesPackageJson,
+                        warnings,
+                        atTypes: true
+                    })) {
+                        return;
+                    }
+                }
+                throw new Error(`Unable to resolve the module subpath: ...${packageSubpath}`);
+            default:
+                throw new Error(`The "${options.resolutionType}" resolution type is not implemented yet`);
+        }
+    }
+    else {
+        logInputField('Import path:', importFullPath);
+        console.log(`\nThe import path does not appear to reference an NPM package.`);
+        console.log('Resolving...\n');
+        let targetPath;
+        try {
+            targetPath = Resolve.sync(importFullPath, {
+                basedir: baseFolder,
+                preserveSymlinks: false,
+                extensions: options.resolutionType === 'ts' ? tsExtensions : jsExtensions
+            });
+        }
+        catch (error) {
+            throw new Error(`Unable to resolve the import path: ${importFullPath}`);
+        }
+        logOutputField('Target path:', targetPath);
+    }
+}
+function traceImport(options) {
+    const warnings = [];
+    try {
+        traceImportInner(options, warnings);
+    }
+    finally {
+        if (warnings.length) {
+            console.log();
+            for (const warning of warnings) {
+                console.log(safe_1.default.yellow('Warning: ' + warning));
+            }
+        }
+    }
+}
+exports.traceImport = traceImport;
+//# sourceMappingURL=traceImport.js.map

package/lib/traceImport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceImport.js","sourceRoot":"","sources":["../src/traceImport.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport {\n  FileSystem,\n  IPackageJson,\n  IParsedPackageName,\n  JsonFile,\n  PackageName\n} from '@rushstack/node-core-library';\nimport colors from 'colors/safe';\nimport * as path from 'path';\nimport * as process from 'process';\nimport * as Resolve from 'resolve';\n\nconst jsExtensions: string[] = ['.js', '.cjs', '.jsx', '.json'];\nconst tsExtensions: string[] = ['.d.ts', '.ts', '.tsx', '.json'];\n\nexport type ResolutionType = 'cjs' | 'es' | 'ts';\n\ninterface IExecuteOptions {\n  importPath: string;\n  baseFolder: string | undefined;\n  resolutionType: ResolutionType;\n}\n\n// Somewhat loosely matches inputs such as:\n//   my-package/path/to/file.js\n//   [group 1 ][group 2       ]\n//\n//   @scope/my-package/path/to/file.js\n//   [group 1        ][group 2       ]\n//\n//   @scope/my-package\n//   [group 1        ]\nconst packageImportPathRegExp: RegExp = /^((?:@[a-z0-9_][a-z0-9\\-_\\.]*\\/)?[a-z0-9_][a-z0-9\\-_\\.]*)(\\/.*)?$/i;\n\nfunction logInputField(title: string, value: string): void {\n  console.log(colors.cyan(title.padEnd(25)) + value);\n}\n\nfunction logOutputField(title: string, value: string): void {\n  console.log(colors.green(title.padEnd(25)) + value);\n}\n\nfunction traceTypeScriptPackage(options: {\n  packageSubpath: string;\n  packageFolder: string;\n  packageJson: IPackageJson;\n  warnings: string[];\n  atTypes?: boolean;\n}): boolean {\n  const { packageSubpath, packageFolder, packageJson, atTypes, warnings } = options;\n\n  // For example, if we started with importFullPath=\"semver/index\",\n  // here we may get normalizedImportFullPath=\"@types/semver/index\"\n  const normalizedImportFullPath: string = packageJson.name + packageSubpath;\n\n  // First try to resolve the .js main index\n  let cjsTargetPath: string | undefined = undefined;\n  try {\n    cjsTargetPath = Resolve.sync(normalizedImportFullPath, {\n      basedir: packageFolder,\n      preserveSymlinks: false,\n      extensions: jsExtensions\n    });\n  } catch (error) {\n    // not found\n  }\n\n  const mainIndexTitle: string = atTypes ? '@types main index:' : 'Main index:';\n\n  if (cjsTargetPath) {\n    const parsedPath: path.ParsedPath = path.parse(cjsTargetPath);\n\n    // Is the resolved .js extension okay?\n    if (tsExtensions.indexOf(parsedPath.ext.toLocaleLowerCase()) >= 0) {\n      logOutputField(mainIndexTitle, '(inferred from .js main index)');\n      console.log();\n      logOutputField('Target path:', cjsTargetPath);\n      return true;\n    }\n\n    // Try to replace the file extension\n    const dtsTargetPath: string = path.join(parsedPath.dir, parsedPath.name + '.d.ts');\n    if (FileSystem.exists(dtsTargetPath)) {\n      logOutputField(mainIndexTitle, '(inferred from .js entry point)');\n      console.log();\n      logOutputField('Target path:', dtsTargetPath);\n      return true;\n    }\n  }\n\n  if (!packageSubpath) {\n    // Try importing the \"types\"/\"typings\" main index:\n\n    if (packageJson.types) {\n      logOutputField(mainIndexTitle, `\"types\": ${JSON.stringify(packageJson.types)}`);\n      console.log();\n      logOutputField('Target path:', path.join(packageFolder, packageJson.types));\n      return true;\n    }\n\n    if (packageJson.typings) {\n      logOutputField(mainIndexTitle, `\"typings\": ${JSON.stringify(packageJson.typings)}`);\n      console.log();\n      logOutputField('Target path:', path.join(packageFolder, packageJson.typings));\n      return true;\n    }\n\n    if (atTypes) {\n      warnings.push('The @types package does not define \"types\" or \"typings\" field.');\n    }\n  } else {\n    // Try importing the .d.ts file directly\n    let dtsTargetPath: string | undefined = undefined;\n    try {\n      dtsTargetPath = Resolve.sync(normalizedImportFullPath, {\n        basedir: packageFolder,\n        preserveSymlinks: false,\n        extensions: tsExtensions\n      });\n    } catch (error) {\n      // not found\n    }\n\n    if (dtsTargetPath) {\n      console.log();\n      logOutputField('Target path:', dtsTargetPath);\n      return true;\n    }\n  }\n\n  return false;\n}\n\nfunction traceImportInner(options: IExecuteOptions, warnings: string[]): void {\n  let baseFolder: string;\n  if (options.baseFolder) {\n    baseFolder = path.resolve(options.baseFolder);\n  } else {\n    baseFolder = process.cwd();\n  }\n\n  const importFullPath: string = options.importPath.trim();\n  if (!importFullPath) {\n    throw new Error(`Invalid import path syntax: ${JSON.stringify(importFullPath)}`);\n  }\n  const match: RegExpExecArray | null = packageImportPathRegExp.exec(importFullPath);\n\n  logInputField('Base folder:', baseFolder);\n\n  if (match) {\n    const importPackageName: string = match[1];\n    const packageSubpath: string | undefined = match[2];\n    const packageSubpathWithoutSlash: string | undefined = packageSubpath\n      ? packageSubpath.substring(1)\n      : undefined;\n\n    logInputField('Package name:', importPackageName);\n    logInputField('Package subpath:', packageSubpathWithoutSlash || '(not specified)');\n\n    console.log('\\nResolving...\\n');\n\n    // Resolve the NPM package first\n    let packageFolder: string | undefined;\n    let packageJson: IPackageJson | undefined = undefined;\n    {\n      let resolvedPackageJsonPath: string | undefined;\n      try {\n        resolvedPackageJsonPath = Resolve.sync(`${importPackageName}/package.json`, {\n          basedir: baseFolder,\n          preserveSymlinks: false\n        });\n      } catch (e) {\n        // Could not find NPM package\n      }\n\n      if (resolvedPackageJsonPath) {\n        packageFolder = path.dirname(resolvedPackageJsonPath);\n        logOutputField('Package folder:', packageFolder);\n\n        packageJson = JsonFile.load(resolvedPackageJsonPath) as IPackageJson;\n        logOutputField(\n          'package.json:',\n          `${packageJson.name || '(missing name)'} (${packageJson.version || 'missing version'})`\n        );\n      }\n    }\n\n    // Also try to resolve the @types package\n    let atTypesPackageFolder: string | undefined = undefined;\n    let atTypesPackageJson: IPackageJson | undefined = undefined;\n\n    if (options.resolutionType === 'ts') {\n      if (!importPackageName.startsWith('@types/')) {\n        const parsedPackageName: IParsedPackageName = PackageName.parse(importPackageName);\n        let atTypesPackageName: string;\n        if (parsedPackageName.scope) {\n          atTypesPackageName = `@types/${parsedPackageName.scope}__${parsedPackageName.unscopedName}`;\n        } else {\n          atTypesPackageName = `@types/${parsedPackageName.unscopedName}`;\n        }\n\n        let atTypesPackageJsonPath: string | undefined;\n        try {\n          atTypesPackageJsonPath = Resolve.sync(`${atTypesPackageName}/package.json`, {\n            basedir: baseFolder,\n            preserveSymlinks: false\n          });\n        } catch (e) {\n          // Unable to resolve @types package\n        }\n\n        if (atTypesPackageJsonPath) {\n          atTypesPackageFolder = path.dirname(atTypesPackageJsonPath);\n          logOutputField('@types folder:', atTypesPackageFolder);\n\n          atTypesPackageJson = JsonFile.load(atTypesPackageJsonPath) as IPackageJson;\n          logOutputField(\n            '@types package.json:',\n            `${atTypesPackageJson.name || '(missing name)'} (${\n              atTypesPackageJson.version || 'missing version'\n            })`\n          );\n        }\n      }\n    }\n\n    switch (options.resolutionType) {\n      case 'cjs':\n        {\n          if (!packageFolder || !packageJson) {\n            throw new Error(`Cannot find package \"${importPackageName}\" from \"${baseFolder}\".`);\n          }\n\n          if (!packageSubpath) {\n            if (packageJson.main) {\n              logOutputField('Main index:', `\"main\": ${JSON.stringify(packageJson.main)}`);\n            } else {\n              logOutputField('Main index:', '(none)');\n            }\n          }\n\n          let targetPath: string;\n          try {\n            targetPath = Resolve.sync(importFullPath, {\n              basedir: packageFolder,\n              preserveSymlinks: false,\n              extensions: jsExtensions\n            });\n          } catch (error) {\n            // Are we importing the main index?\n            if (packageSubpath) {\n              throw new Error(`Unable to resolve the module subpath: ...${packageSubpath}`);\n            } else {\n              console.log('\\nThis package does not define a main index.');\n              return;\n            }\n          }\n          console.log();\n          logOutputField('Target path:', targetPath);\n        }\n        break;\n      case 'ts':\n        if (!packageFolder || (!packageJson && !atTypesPackageFolder && !atTypesPackageJson)) {\n          throw new Error(`Cannot find package \"${importPackageName}\" from \"${baseFolder}\".`);\n        }\n\n        if (packageFolder && packageJson) {\n          if (traceTypeScriptPackage({ packageSubpath, packageFolder, packageJson, warnings })) {\n            if (atTypesPackageFolder) {\n              warnings.push('An @types package was found but not used.');\n            }\n\n            return;\n          }\n        }\n\n        if (atTypesPackageFolder && atTypesPackageJson) {\n          if (\n            traceTypeScriptPackage({\n              packageSubpath,\n              packageFolder: atTypesPackageFolder,\n              packageJson: atTypesPackageJson,\n              warnings,\n              atTypes: true\n            })\n          ) {\n            return;\n          }\n        }\n\n        throw new Error(`Unable to resolve the module subpath: ...${packageSubpath}`);\n      default:\n        throw new Error(`The \"${options.resolutionType}\" resolution type is not implemented yet`);\n    }\n  } else {\n    logInputField('Import path:', importFullPath);\n    console.log(`\\nThe import path does not appear to reference an NPM package.`);\n    console.log('Resolving...\\n');\n\n    let targetPath: string;\n    try {\n      targetPath = Resolve.sync(importFullPath, {\n        basedir: baseFolder,\n        preserveSymlinks: false,\n        extensions: options.resolutionType === 'ts' ? tsExtensions : jsExtensions\n      });\n    } catch (error) {\n      throw new Error(`Unable to resolve the import path: ${importFullPath}`);\n    }\n\n    logOutputField('Target path:', targetPath);\n  }\n}\n\nexport function traceImport(options: IExecuteOptions): void {\n  const warnings: string[] = [];\n  try {\n    traceImportInner(options, warnings);\n  } finally {\n    if (warnings.length) {\n      console.log();\n      for (const warning of warnings) {\n        console.log(colors.yellow('Warning: ' + warning));\n      }\n    }\n  }\n}\n"]}

package/package.json

@@ -1,5 +1,37 @@
 {
-  "license": "MIT",
   "name": "@rushstack/trace-import",
-  "version": "0.0.0"
-}
+  "version": "0.1.1",
+  "description": "CLI tool for understanding how require() and \"import\" statements get resolved",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack.git",
+    "directory": "apps/trace-import"
+  },
+  "bin": {
+    "trace-import": "./bin/trace-import"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@rushstack/node-core-library": "3.53.3",
+    "@rushstack/ts-command-line": "4.13.1",
+    "colors": "~1.2.1",
+    "resolve": "~1.22.1",
+    "semver": "~7.3.0",
+    "typescript": "~4.8.4"
+  },
+  "devDependencies": {
+    "@rushstack/eslint-config": "3.1.1",
+    "@rushstack/heft": "0.48.9",
+    "@rushstack/heft-node-rig": "1.11.10",
+    "@types/heft-jest": "1.0.1",
+    "@types/node": "12.20.24",
+    "@types/resolve": "1.20.2",
+    "@types/semver": "7.3.5"
+  },
+  "scripts": {
+    "start": "node lib/start",
+    "build": "heft build --clean",
+    "_phase:build": "heft build --clean",
+    "_phase:test": "heft test --no-build"
+  }
+}