printable-shell-command 0.1.3 → 0.1.4

package/.github/workflows/CI.yaml

@@ -0,0 +1,14 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: make setup
+      - run: make lint
+      - run: make test-js

package/Makefile

@@ -1,3 +1,6 @@
+.PHONY: test
+test: lint test-js
+
 .PHONY: lint
 lint: setup
 	bun x @biomejs/biome check
@@ -6,6 +9,10 @@ lint: setup
 format: setup
 	bun x @biomejs/biome check --write
 
+.PHONY: test-js
+test-js: setup
+	bun test
+
 # https://github.com/lgarron/repo
 REPO_COMMANDS = publish
 
@@ -18,3 +25,11 @@ ${REPO_COMMANDS}:
 .PHONY: setup
 setup:
 	bun install --frozen-lockfile
+
+.PHONY: clean
+clean:
+	# No-op
+
+.PHONY: reset
+reset: clean
+	rm -rf ./node_modules

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {

package/src/index.ts

@@ -1,5 +1,9 @@
+const DEFAULT_MAIN_INDENTATION = "";
+const DEFAULT_ARG_INDENTATION = "  ";
+const DEFAULT_ARGUMENT_LINE_WRAPPING = "by-entry";
+
 const INLINE_SEPARATOR = " ";
-const LINE_WRAP_SEPARATOR = " \\\n  ";
+const LINE_WRAP_LINE_END = " \\\n";
 
 // biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.
 function isString(s: any): s is string {
@@ -21,7 +25,12 @@ export interface PrintOptions {
 	// - "extra-safe": Quote all arguments, even ones that don't need it. This is
 	//   more likely to be safe under all circumstances.
 	quoting?: "auto" | "extra-safe";
-	lineWrap?: "none" | "by-entry";
+	// Line wrapping to use between arguments. Defaults to `"by-entry"`.
+	argumentLineWrapping?:
+		| "by-entry"
+		| "nested-by-entry"
+		| "by-argument"
+		| "inline";
 }
 
 // https://mywiki.wooledge.org/BashGuide/SpecialCharacters
@@ -150,7 +159,7 @@ export class PrintableShellCommand {
 	#escapeArg(
 		arg: string,
 		isMainCommand: boolean,
-		options?: PrintOptions,
+		options: PrintOptions,
 	): string {
 		const argCharacters = new Set(arg);
 		const specialShellCharacters = isMainCommand
@@ -169,46 +178,86 @@ export class PrintableShellCommand {
 		return arg;
 	}
 
-	#smallIndent(s: string, options?: PrintOptions): string {
-		return (options?.mainIndentation ?? "") + s;
+	#mainIndentation(options: PrintOptions): string {
+		return options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;
+	}
+
+	#argIndentation(options: PrintOptions): string {
+		return (
+			this.#mainIndentation(options) +
+			(options?.argIndentation ?? DEFAULT_ARG_INDENTATION)
+		);
+	}
+
+	#lineWrapSeparator(options: PrintOptions): string {
+		return LINE_WRAP_LINE_END + this.#argIndentation(options);
 	}
 
-	#bigIndent(s: string, options?: PrintOptions): string {
-		return this.#smallIndent((options?.argIndentation ?? "  ") + s, options);
+	#argPairSeparator(options: PrintOptions): string {
+		switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {
+			case "by-entry": {
+				return INLINE_SEPARATOR;
+			}
+			case "nested-by-entry": {
+				return this.#lineWrapSeparator(options) + this.#argIndentation(options);
+			}
+			case "by-argument": {
+				return this.#lineWrapSeparator(options);
+			}
+			case "inline": {
+				return INLINE_SEPARATOR;
+			}
+			default:
+				throw new Error("Invalid argument line wrapping argument.");
+		}
+	}
+
+	#entrySeparator(options: PrintOptions): string {
+		switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {
+			case "by-entry": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "nested-by-entry": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "by-argument": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "inline": {
+				return INLINE_SEPARATOR;
+			}
+			default:
+				throw new Error("Invalid argument line wrapping argument.");
+		}
 	}
 
 	public getPrintableCommand(options?: PrintOptions): string {
-		const lines: string[] = [];
+		// TODO: Why in the world does TypeScript not give the `options` arg the type of `PrintOptions | undefined`???
+		// biome-ignore lint/style/noParameterAssign: We want a default assignment without affecting the signature.
+		options ??= {};
+		const serializedEntries: string[] = [];
 
-		lines.push(
-			this.#smallIndent(
+		serializedEntries.push(
+			this.#mainIndentation(options) +
 				this.#escapeArg(this.commandName, true, options),
-				options,
-			),
 		);
 
-		// let pendingNewlineAfterPart = options?.separateLines === "dash-heuristic";
 		for (let i = 0; i < this.args.length; i++) {
 			const argsEntry = this.args[i];
 
 			if (isString(argsEntry)) {
-				lines.push(
-					this.#bigIndent(this.#escapeArg(argsEntry, false, options), options),
-				);
+				serializedEntries.push(this.#escapeArg(argsEntry, false, options));
 			} else {
 				const [part1, part2] = argsEntry;
-
-				lines.push(
-					this.#bigIndent(
-						this.#escapeArg(part1, false, options) +
-							INLINE_SEPARATOR +
-							this.#escapeArg(part2, false, options),
-						options,
-					),
+				serializedEntries.push(
+					this.#escapeArg(part1, false, options) +
+						this.#argPairSeparator(options) +
+						this.#escapeArg(part2, false, options),
 				);
 			}
 		}
-		return lines.join(LINE_WRAP_SEPARATOR);
+
+		return serializedEntries.join(this.#entrySeparator(options));
 	}
 
 	public print(options?: PrintOptions): void {

package/test/index.test.ts

@@ -0,0 +1,152 @@
+import { expect, test } from "bun:test";
+import { PrintableShellCommand } from "../src";
+
+const rsyncCommand = new PrintableShellCommand("rsync", [
+	"-avz",
+	["--exclude", ".DS_Store"],
+	["--exclude", ".git"],
+	"./dist/web/experiments.cubing.net/test/deploy/",
+	"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+]);
+
+test("args for commands", () => {
+	expect(rsyncCommand.toCommandWithFlatArgs()).toEqual([
+		"rsync",
+		[
+			"-avz",
+			"--exclude",
+			".DS_Store",
+			"--exclude",
+			".git",
+			"./dist/web/experiments.cubing.net/test/deploy/",
+			"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+		],
+	]);
+	expect(rsyncCommand.toFlatCommand()).toEqual([
+		"rsync",
+		"-avz",
+		"--exclude",
+		".DS_Store",
+		"--exclude",
+		".git",
+		"./dist/web/experiments.cubing.net/test/deploy/",
+		"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+	]);
+	expect(rsyncCommand.toCommandWithFlatArgs()).toEqual(rsyncCommand.forNode());
+	expect(rsyncCommand.toFlatCommand()).toEqual(rsyncCommand.forBun());
+});
+
+test("default formatting", () => {
+	expect(rsyncCommand.getPrintableCommand()).toEqual(
+		`rsync \\
+  -avz \\
+  --exclude .DS_Store \\
+  --exclude .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			quoting: "auto",
+			argumentLineWrapping: "by-entry",
+		}),
+	).toEqual(rsyncCommand.getPrintableCommand());
+});
+
+test("extra-safe quoting", () => {
+	expect(rsyncCommand.getPrintableCommand({ quoting: "extra-safe" })).toEqual(
+		`'rsync' \\
+  '-avz' \\
+  '--exclude' '.DS_Store' \\
+  '--exclude' '.git' \\
+  './dist/web/experiments.cubing.net/test/deploy/' \\
+  'experiments.cubing.net:~/experiments.cubing.net/test/deploy/'`,
+	);
+});
+
+test("indentation", () => {
+	expect(
+		rsyncCommand.getPrintableCommand({ argIndentation: "\t   \t" }),
+	).toEqual(
+		`rsync \\
+	   	-avz \\
+	   	--exclude .DS_Store \\
+	   	--exclude .git \\
+	   	./dist/web/experiments.cubing.net/test/deploy/ \\
+	   	experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(rsyncCommand.getPrintableCommand({ argIndentation: "↪ " })).toEqual(
+		`rsync \\
+↪ -avz \\
+↪ --exclude .DS_Store \\
+↪ --exclude .git \\
+↪ ./dist/web/experiments.cubing.net/test/deploy/ \\
+↪ experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(rsyncCommand.getPrintableCommand({ mainIndentation: "  " })).toEqual(
+		`  rsync \\
+    -avz \\
+    --exclude .DS_Store \\
+    --exclude .git \\
+    ./dist/web/experiments.cubing.net/test/deploy/ \\
+    experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			mainIndentation: "🙈",
+			argIndentation: "🙉",
+		}),
+	).toEqual(
+		`🙈rsync \\
+🙈🙉-avz \\
+🙈🙉--exclude .DS_Store \\
+🙈🙉--exclude .git \\
+🙈🙉./dist/web/experiments.cubing.net/test/deploy/ \\
+🙈🙉experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+});
+
+test("line wrapping", () => {
+	expect(
+		rsyncCommand.getPrintableCommand({ argumentLineWrapping: "by-entry" }),
+	).toEqual(rsyncCommand.getPrintableCommand());
+	expect(
+		rsyncCommand.getPrintableCommand({
+			argumentLineWrapping: "nested-by-entry",
+		}),
+	).toEqual(`rsync \\
+  -avz \\
+  --exclude \\
+    .DS_Store \\
+  --exclude \\
+    .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`);
+	expect(
+		rsyncCommand.getPrintableCommand({ argumentLineWrapping: "by-argument" }),
+	).toEqual(`rsync \\
+  -avz \\
+  --exclude \\
+  .DS_Store \\
+  --exclude \\
+  .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			argumentLineWrapping: "inline",
+		}),
+	).toEqual(
+		"rsync -avz --exclude .DS_Store --exclude .git ./dist/web/experiments.cubing.net/test/deploy/ experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+	);
+});
+
+test("command with space is escaped by default", () => {
+	const command = new PrintableShellCommand(
+		"/Applications/My App.app/Contents/Resources/my-app",
+	);
+
+	expect(command.getPrintableCommand()).toEqual(
+		`'/Applications/My App.app/Contents/Resources/my-app'`,
+	);
+});