chore: command suggestions enhancements (#828)

Author: vladfrangu

package.json

@@ -95,6 +95,7 @@
         "is-ci": "~4.1.0",
         "istextorbinary": "~9.5.0",
         "jju": "~1.4.0",
+        "js-levenshtein": "^1.1.6",
         "lodash.clonedeep": "^4.5.0",
         "mime": "~4.0.4",
         "mixpanel": "~0.18.0",
@@ -127,6 +128,7 @@
         "@types/inquirer": "^9.0.7",
         "@types/is-ci": "^3.0.4",
         "@types/jju": "^1.4.5",
+        "@types/js-levenshtein": "^1",
         "@types/lodash.clonedeep": "^4",
         "@types/mime": "^4.0.0",
         "@types/node": "^22.0.0",

src/commands/help.ts

@@ -1,9 +1,9 @@
-import { jaroWinkler } from '@skyra/jaro-winkler';
 import chalk from 'chalk';
 
 import { ApifyCommand, commandRegistry } from '../lib/command-framework/apify-command.js';
 import { Args } from '../lib/command-framework/args.js';
 import { renderHelpForCommand, renderMainHelpMenu } from '../lib/command-framework/help.js';
+import { useCommandSuggestions } from '../lib/hooks/useCommandSuggestions.js';
 import { error } from '../lib/outputs.js';
 
 export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
@@ -37,13 +37,7 @@ export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
 		const command = commandRegistry.get(lowercasedCommandString);
 
 		if (!command) {
-			const allCommands = [...commandRegistry.keys()];
-
-			const closestMatches = allCommands.filter((cmd) => {
-				const lowercased = cmd.toLowerCase();
-
-				return jaroWinkler(lowercasedCommandString, lowercased) >= 0.95;
-			});
+			const closestMatches = useCommandSuggestions(lowercasedCommandString);
 
 			let message = chalk.gray(`Command ${chalk.whiteBright(commandString)} not found`);
 

src/entrypoints/_shared.ts

@@ -15,6 +15,7 @@ import { renderMainHelpMenu, selectiveRenderHelpForCommand } from '../lib/comman
 import { readStdin } from '../lib/commands/read-stdin.js';
 import { useCLIMetadata } from '../lib/hooks/useCLIMetadata.js';
 import { shouldSkipVersionCheck } from '../lib/hooks/useCLIVersionCheck.js';
+import { useCommandSuggestions } from '../lib/hooks/useCommandSuggestions.js';
 import { error } from '../lib/outputs.js';
 import { cliDebugPrint } from '../lib/utils/cliDebugPrint.js';
 
@@ -122,9 +123,18 @@ export async function runCLI(entrypoint: string) {
 			const command = commandRegistry.get(possibleCommands.find((cmd) => commandRegistry.has(cmd)) ?? '');
 
 			if (!command) {
-				error({
-					message: `Command ${parsed._[0]} not found`,
-				});
+				const closestMatches = useCommandSuggestions(String(parsed._[0]));
+
+				let message = chalk.gray(`Command ${chalk.whiteBright(parsed._[0])} not found`);
+
+				if (closestMatches.length) {
+					message += '\n  ';
+					message += chalk.gray(
+						`Did you mean: ${closestMatches.map((cmd) => chalk.whiteBright(cmd)).join(', ')}?`,
+					);
+				}
+
+				error({ message });
 
 				return;
 			}
@@ -221,10 +231,26 @@ export async function runCLI(entrypoint: string) {
 						return errorMessageSplit[1];
 					})();
 
+					const closestMatches =
+						nonexistentType === 'subcommand'
+							? useCommandSuggestions(`${parsed._[0]} ${errorMessageSplit[1]}`)
+							: [];
+
+					const messageParts = [
+						chalk.gray(`Nonexistent ${nonexistentType}: ${chalk.whiteBright(nonexistentRepresentation)}`),
+					];
+
+					if (closestMatches.length) {
+						messageParts.push(
+							chalk.gray(
+								`  Did you mean: ${closestMatches.map((cmd) => chalk.whiteBright(cmd)).join(', ')}?`,
+							),
+						);
+					}
+
 					error({
 						message: [
-							`Nonexistent ${nonexistentType}: ${nonexistentRepresentation}`,
-							`  ${chalk.red('>')}  See more help with --help`,
+							...messageParts,
 							'',
 							selectiveRenderHelpForCommand(command, {
 								showUsageString: true,

src/lib/hooks/useCommandSuggestions.ts

@@ -0,0 +1,48 @@
+import { jaroWinkler } from '@skyra/jaro-winkler';
+import levenshtein from 'js-levenshtein';
+
+import { commandRegistry } from '../command-framework/apify-command.js';
+import { cliDebugPrint } from '../utils/cliDebugPrint.js';
+
+export function useCommandSuggestions(inputString: string) {
+	const allCommands = [...commandRegistry.entries()].sort(([a], [b]) => a.localeCompare(b));
+
+	const lowercasedCommandString = inputString.toLowerCase();
+
+	const closestMatches = allCommands
+		.map(([cmdString, cmdClass]) => {
+			const lowercased = cmdString.toLowerCase();
+			const cmdStringParts = cmdString.split(' ');
+			const lastPart = cmdStringParts[cmdStringParts.length - 1].toLowerCase();
+
+			const isAlias = cmdClass.aliases?.includes(lastPart) || cmdClass.hiddenAliases?.includes(lastPart) || false;
+
+			const levenshteinDistance = levenshtein(lowercasedCommandString, lowercased);
+			const jaroWinklerDistance = jaroWinkler(lowercasedCommandString, lowercased);
+
+			const matches = levenshteinDistance <= 2 || jaroWinklerDistance >= 0.975;
+
+			if (matches) {
+				cliDebugPrint('useCommandSuggestions', {
+					inputString: lowercasedCommandString,
+					lowercased,
+					matches,
+					levenshtein: levenshteinDistance,
+					jaroWinkler: jaroWinklerDistance,
+				});
+
+				if (!isAlias) {
+					return { string: `${lowercased}`, distance: jaroWinklerDistance };
+				}
+
+				return { string: `${lowercased} (alias for ${cmdClass.name})`, distance: jaroWinklerDistance };
+			}
+
+			return null;
+		})
+		.filter((item) => item !== null)
+		.sort((a, b) => b.distance - a.distance)
+		.map((item) => item.string);
+
+	return closestMatches;
+}

test/lib/hooks/useCommandSuggestions.test.ts

@@ -0,0 +1,92 @@
+/* eslint-disable max-classes-per-file */
+import {
+	ApifyCommand,
+	type BuiltApifyCommand as _BuiltApifyCommand,
+	commandRegistry,
+} from '../../../src/lib/command-framework/apify-command.js';
+import { useCommandSuggestions } from '../../../src/lib/hooks/useCommandSuggestions.js';
+
+const BuiltApifyCommand = ApifyCommand as typeof _BuiltApifyCommand;
+
+const subcommands = [
+	class KVSGetValue extends BuiltApifyCommand {
+		static override name = 'get-value';
+	},
+	class KVSSetValue extends BuiltApifyCommand {
+		static override name = 'set-value';
+	},
+];
+
+const fakeCommands = [
+	class Help extends BuiltApifyCommand {
+		static override name = 'help';
+	},
+	class Upgrade extends BuiltApifyCommand {
+		static override name = 'upgrade';
+		static override aliases = ['cv', 'check-version'];
+	},
+	class KeyValueStores extends BuiltApifyCommand {
+		static override name = 'key-value-stores';
+		static override aliases = ['kvs'];
+		static override subcommands = subcommands;
+	},
+];
+
+describe('useCommandSuggestions', () => {
+	let existingCommands: [string, typeof BuiltApifyCommand][];
+
+	beforeAll(() => {
+		existingCommands = [...commandRegistry.entries()];
+
+		commandRegistry.clear();
+
+		for (const command of fakeCommands) {
+			commandRegistry.set(command.name, command);
+
+			if (command.aliases?.length) {
+				for (const alias of command.aliases) {
+					commandRegistry.set(alias, command);
+
+					if (command.subcommands?.length) {
+						for (const subcommand of command.subcommands) {
+							commandRegistry.set(`${alias} ${subcommand.name}`, subcommand);
+						}
+					}
+				}
+			}
+
+			if (command.subcommands?.length) {
+				for (const subcommand of command.subcommands) {
+					commandRegistry.set(`${command.name} ${subcommand.name}`, subcommand);
+
+					if (command.aliases?.length) {
+						for (const alias of command.aliases) {
+							commandRegistry.set(`${command.name} ${alias}`, subcommand);
+						}
+					}
+				}
+			}
+		}
+	});
+
+	afterAll(() => {
+		commandRegistry.clear();
+
+		for (const [name, command] of existingCommands) {
+			commandRegistry.set(name, command);
+		}
+	});
+
+	test.each([
+		['hlp', 'help'],
+		['kv', 'kvs (alias for key-value-stores)', 'cv (alias for upgrade)'],
+		['key-value-stor', 'key-value-stores'],
+		// assert order based on distance
+		['kvs get-values', 'kvs get-value', 'kvs set-value'],
+		['kvs set-values', 'kvs set-value', 'kvs get-value'],
+	])('command suggestions for %s', (input, ...expected) => {
+		const suggestions = useCommandSuggestions(input);
+
+		expect(suggestions).toEqual(expected);
+	});
+});

yarn.lock

@@ -1687,6 +1687,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/js-levenshtein@npm:^1":
+  version: 1.1.3
+  resolution: "@types/js-levenshtein@npm:1.1.3"
+  checksum: 10c0/025f2bd8d865cfa7a996799a1a2f2a77fa2fc74a28971aa035a103de35d7c1e3d949721a88f57fdb532815bbcb2bf7019196a608ed0a8bbd1023d64c52bb251b
+  languageName: node
+  linkType: hard
+
 "@types/json-schema@npm:^7.0.15":
   version: 7.0.15
   resolution: "@types/json-schema@npm:7.0.15"
@@ -2432,6 +2439,7 @@ __metadata:
     "@types/inquirer": "npm:^9.0.7"
     "@types/is-ci": "npm:^3.0.4"
     "@types/jju": "npm:^1.4.5"
+    "@types/js-levenshtein": "npm:^1"
     "@types/lodash.clonedeep": "npm:^4"
     "@types/mime": "npm:^4.0.0"
     "@types/node": "npm:^22.0.0"
@@ -2465,6 +2473,7 @@ __metadata:
     is-ci: "npm:~4.1.0"
     istextorbinary: "npm:~9.5.0"
     jju: "npm:~1.4.0"
+    js-levenshtein: "npm:^1.1.6"
     lint-staged: "npm:^16.0.0"
     lodash.clonedeep: "npm:^4.5.0"
     mdast-util-from-markdown: "npm:^2.0.2"
@@ -5957,6 +5966,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"js-levenshtein@npm:^1.1.6":
+  version: 1.1.6
+  resolution: "js-levenshtein@npm:1.1.6"
+  checksum: 10c0/14045735325ea1fd87f434a74b11d8a14380f090f154747e613529c7cff68b5ee607f5230fa40665d5fb6125a3791f4c223f73b9feca754f989b059f5c05864f
+  languageName: node
+  linkType: hard
+
 "js-tokens@npm:^4.0.0":
   version: 4.0.0
   resolution: "js-tokens@npm:4.0.0"