feat: experimental binary source mapping (#5)

* Experimentally adds binary source mapping for built binaries
	- Syntax: `npx bin-path dist.js:::src.ts --foo bar`
* Refactors helpers into their own file and adds separate tests

Author: tommy-mitchell

.xo-config.json

@@ -3,7 +3,8 @@
 		"arrow-parens": "off",
 		"quotes": ["error", "double"],
 		"object-curly-spacing": ["error", "always"],
-		"object-shorthand": ["error", "always", { "avoidExplicitReturnArrows": false }]
+		"object-shorthand": ["error", "always", { "avoidExplicitReturnArrows": false }],
+		"unicorn/no-process-exit": "off"
 	},
 	"overrides": [
 		{
@@ -17,6 +18,12 @@
 				"n/file-extension-in-import": ["error", "always", { ".ts": "always" }],
 				"@typescript-eslint/prefer-regexp-exec": "off"
 			}
+		},
+		{
+			"files": "test/fixtures/**/*.*",
+			"rules": {
+				"import/no-extraneous-dependencies": "off"
+			}
 		}
 	]
 }

package.json

@@ -34,10 +34,9 @@
 	],
 	"scripts": {
 		"prepare": "npm run build",
-		"build": "tsc -p tsconfig.build.json && execify --pkg --fix-shebangs",
+		"build": "tsc -p tsconfig.build.json && execify --pkg --fix-shebang",
 		"lint": "xo",
-		"test": "listr 'tsc --noEmit' 'c8 npm run ava'",
-		"ava": "cross-env NODE_OPTIONS='--loader=tsx --no-warnings=ExperimentalWarning' ava"
+		"test": "listr 'tsc --noEmit' 'c8 ava'"
 	},
 	"ava": {
 		"files": [
@@ -46,8 +45,12 @@
 		"extensions": {
 			"ts": "module"
 		},
+		"environmentVariables": {
+			"concurrency": "5"
+		},
 		"nodeArguments": [
-			"--loader=tsx",
+			"--loader=ts-node/esm",
+			"--loader=esmock",
 			"--no-warnings=ExperimentalWarning"
 		]
 	},
@@ -56,15 +59,19 @@
 		"get-bin-path": "^10.0.0"
 	},
 	"devDependencies": {
+		"@shopify/semaphore": "^3.0.2",
 		"@tommy-mitchell/tsconfig": "^1.1.0",
 		"@types/node": "^16.17",
 		"ava": "^5.3.1",
 		"c8": "^8.0.1",
 		"cross-env": "^7.0.3",
+		"esmock": "^2.3.6",
 		"execify-cli": "^0.1.0",
+		"is-executable": "^2.0.1",
 		"listr-cli": "^0.3.0",
 		"meow": "^11.0.0",
-		"tsx": "^3.12.7",
+		"testtriple": "^2.2.3",
+		"ts-node": "^10.9.1",
 		"typescript": "~5.1.6",
 		"xo": "^0.54.2"
 	}

readme.md

@@ -22,12 +22,10 @@ yarn global add bin-path-cli
 ```
 </details>
 
-*Uses top-level await. Requires Node 14.8 or higher.*
-
 ## Usage
 
 ```sh
-npx bin-path [binary-name] [arguments or flags…]
+npx bin-path [source-map] [binary-name] [arguments or flags…]
 ```
 
 ### Curent Working Directory
@@ -54,10 +52,10 @@ $ npx bin-path --some-flag arg1 arg2
 ```js
 // cli.js
 #!/usr/bin/env node
-import meow from "meow";
+import process from "node:process";
 
-const {input} = meow({importMeta: import.meta});
-console.log(`Arguments: [${input.join(", ")}]`);
+const args = process.argv.slice(2);
+console.log(`Arguments: [${args.join(", ")}]`);
 ```
 
 ```sh
@@ -114,6 +112,45 @@ $ npx bin-path --foo-flag
 ```
 </details>
 
+### Source Mapping
+
+If you're writing your binary in a language that compiles to JavaScript (e.g. TypeScript) and would like to test your source binary, you can map the built file to the source file by using the following format as the first argument to `bin-path`:
+
+```sh
+$ npx bin-path dist.js:::src.ts
+```
+
+<details>
+<summary>Example</summary>
+
+```
+\__ dist/
+    \__ cli.js
+\__ src/
+    \__ cli.ts
+\__ package.json
+```
+
+</details>
+
+#### Notice
+
+This is an experimental feature, currently only available under the `beta` dist-tag. To use, install `bin-path-cli` with:
+
+```sh
+npm install --global bin-path-cli@beta
+```
+
+<details>
+<summary>Other Package Managers</summary>
+
+```sh
+yarn global add bin-path-cli@beta
+```
+</details>
+
+The feature is under-tested and the syntax is subject to change. If you have any problems or suggestings, please [file an issue](https://github.com/tommy-mitchell/bin-path-cli/issues/new).
+
 ## Related
 
 - [get-bin-path](https://github.com/ehmicky/get-bin-path) - Get the current package's binary path.

src/cli.ts

@@ -1,47 +1,26 @@
-#!/usr/bin/env tsx
+#!/usr/bin/env ts-node-esm
 import process from "node:process";
-import { getBinPath } from "get-bin-path";
 import { execa, type ExecaError } from "execa";
-
-type ExitOptions = {
-	message?: string;
-	exitCode?: number;
-};
-
-/** Exit with an optional error message. */
-const exit = ({ message, exitCode = 1 }: ExitOptions = {}) => {
-	if (message) {
-		console.error(message);
-	}
-
-	process.exit(exitCode);
-};
+import { exit, tryGetBinPath, tryMapBinPath } from "./helpers.js";
 
 // First two arguments are Node binary and this binary
 const args = process.argv.slice(2);
 
-/** Attempt to get a named binary from the first argument, or fallback to default binary. */
-const tryGetBinPath = async (binaryName?: string): ReturnType<typeof getBinPath> => {
-	if (binaryName) {
-		const binPath = await getBinPath({ name: binaryName });
-
-		if (binPath) {
-			args.shift();
-			return binPath;
-		}
+const firstArg = args.at(0);
+const shouldMap = firstArg?.includes(":::");
 
-		return tryGetBinPath();
-	}
-
-	return getBinPath();
-};
+if (shouldMap) {
+	args.shift();
+}
 
-// First argument could be a named binary to use
-const maybeBinaryName = args.at(0);
-const binPath = await tryGetBinPath(maybeBinaryName);
+let binPath = await tryGetBinPath({ args });
 
 if (!binPath) {
-	exit({ message: "No binary found. Usage: `$ npx bin-path [binary-name] [arguments or flags…]`" });
+	exit({ message: "No binary found. Usage: `$ npx bin-path [source-map] [binary-name] [arguments or flags…]`" });
+}
+
+if (shouldMap) {
+	binPath = tryMapBinPath({ binPath: binPath!, map: firstArg! });
 }
 
 try {

src/helpers.ts

@@ -0,0 +1,62 @@
+import process from "node:process";
+import { getBinPath } from "get-bin-path";
+import type { Match } from "./types.js";
+
+type ExitArgs = {
+	message?: string;
+	exitCode?: number;
+};
+
+/** Exit with an optional error message. */
+export const exit = ({ message, exitCode = 1 }: ExitArgs = {}): never => {
+	if (message) {
+		console.error(message);
+	}
+
+	process.exit(exitCode);
+};
+
+type TryGetBinPathArgs = {
+	args: typeof process.argv;
+};
+
+/** Attempt to get a named binary from the first argument, or fallback to default binary. */
+export const tryGetBinPath = async ({ args }: TryGetBinPathArgs): ReturnType<typeof getBinPath> => {
+	// First argument could be a named binary to use
+	const binaryName = args.at(0);
+
+	if (binaryName) {
+		const binPath = await getBinPath({ name: binaryName });
+
+		if (binPath) {
+			args.shift();
+			return binPath;
+		}
+	}
+
+	return getBinPath();
+};
+
+/** https://regex101.com/r/OLVdtN/1 */
+const mapRegex = /(?<dPath>[^.]+)(?<dExt>\.\w+):::(?<sPath>[^.]+)(?<sExt>\.\w+)/;
+
+type MapBinPathArgs = {
+	binPath: string;
+	map: string;
+};
+
+/** Maps built binary to source binary if possible. */
+export const tryMapBinPath = ({ binPath, map }: MapBinPathArgs): string => {
+	const match = map.match(mapRegex) as Match<"dPath" | "dExt" | "sPath" | "sExt">;
+
+	if (!match) {
+		return binPath;
+	}
+
+	const {
+		dPath: distPath, dExt: distExtension,
+		sPath: sourcePath, sExt: sourceExtension,
+	} = match.groups;
+
+	return binPath.replace(distPath, sourcePath).replace(distExtension, sourceExtension);
+};

src/types.ts

@@ -0,0 +1,14 @@
+// Based on https://github.com/microsoft/TypeScript/issues/32098#issuecomment-1279645368
+type RegExpGroups<Groups extends string, Alternates extends string | undefined = undefined> = (
+	RegExpMatchArray & {
+		groups: (
+			| { [name in Groups]: string }
+			| { [name in NonNullable<Alternates>]?: string }
+			| Record<string, string>
+		);
+	}
+);
+
+export type Match<Groups extends string> = RegExpGroups<Groups> | null; // eslint-disable-line @typescript-eslint/ban-types
+
+export type MatchAll<Groups extends string, Alternates extends string> = IterableIterator<RegExpGroups<Groups, Alternates>>;