show similar commands with an edit distance of 2 or less (#206)

Fixes #201

Uses the Optimal string alignment distance algorithm to compute edit distance, which allows for additions, removals, substitutions, and swaps - all as 1 cost operations.

Suggests any commands within an edit distance of <=2 by default, which is configurable. You can set it to 0 to disable the feature.

Author: jakemac53

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.2.0
+
+* Suggest similar commands if an unknown command is encountered, when using the
+  `CommandRunner`.
+  * The max edit distance for suggestions defaults to 2, but can be configured
+    using the `suggestionDistanceLimit` parameter on the constructor. You can
+    set it to `0` to disable the feature.
+
 ## 2.1.1
 
 * Fix a bug with `mandatory` options which caused a null assertion failure when

lib/command_runner.dart

@@ -77,7 +77,14 @@ class CommandRunner<T> {
   ArgParser get argParser => _argParser;
   final ArgParser _argParser;
 
-  CommandRunner(this.executableName, this.description, {int? usageLineLength})
+  /// The maximum edit distance allowed when suggesting possible intended
+  /// commands.
+  ///
+  /// Set to `0` in order to disable suggestions, defaults to `2`.
+  final int suggestionDistanceLimit;
+
+  CommandRunner(this.executableName, this.description,
+      {int? usageLineLength, this.suggestionDistanceLimit = 2})
       : _argParser = ArgParser(usageLineLength: usageLineLength) {
     argParser.addFlag('help',
         abbr: 'h', negatable: false, help: 'Print this usage information.');
@@ -158,13 +165,19 @@ class CommandRunner<T> {
 
           command.usageException('Missing subcommand for "$commandString".');
         } else {
+          var requested = argResults.rest[0];
+
+          // Build up a help message containing similar commands, if found.
+          var similarCommands =
+              _similarCommandsText(requested, commands.values);
+
           if (command == null) {
             usageException(
-                'Could not find a command named "${argResults.rest[0]}".');
+                'Could not find a command named "$requested".$similarCommands');
           }
 
           command.usageException('Could not find a subcommand named '
-              '"${argResults.rest[0]}" for "$commandString".');
+              '"$requested" for "$commandString".$similarCommands');
         }
       }
 
@@ -196,6 +209,34 @@ class CommandRunner<T> {
     return (await command.run()) as T?;
   }
 
+  // Returns help text for commands similar to `name`, in sorted order.
+  String _similarCommandsText(String name, Iterable<Command<T>> commands) {
+    if (suggestionDistanceLimit <= 0) return '';
+    var distances = <Command<T>, int>{};
+    var candidates =
+        SplayTreeSet<Command<T>>((a, b) => distances[a]! - distances[b]!);
+    for (var command in commands) {
+      if (command.hidden) continue;
+      var distance = _editDistance(name, command.name);
+      if (distance <= suggestionDistanceLimit) {
+        distances[command] = distance;
+        candidates.add(command);
+      }
+    }
+    if (candidates.isEmpty) return '';
+
+    var similar = StringBuffer();
+    similar
+      ..writeln()
+      ..writeln()
+      ..writeln('Did you mean one of these?');
+    for (var command in candidates) {
+      similar.writeln('  ${command.name}');
+    }
+
+    return similar.toString();
+  }
+
   String _wrap(String text, {int? hangingIndent}) => wrapText(text,
       length: argParser.usageLineLength, hangingIndent: hangingIndent);
 }
@@ -433,3 +474,43 @@ String _getCommandUsage(Map<String, Command> commands,
 
   return buffer.toString();
 }
+
+/// Returns the edit distance between `from` and `to`.
+//
+/// Allows for edits, deletes, substitutions, and swaps all as single cost.
+///
+/// See https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance#Optimal_string_alignment_distance
+int _editDistance(String from, String to) {
+  // Add a space in front to mimic indexing by 1 instead of 0.
+  from = ' $from';
+  to = ' $to';
+  var distances = [
+    for (var i = 0; i < from.length; i++)
+      [
+        for (var j = 0; j < to.length; j++)
+          if (i == 0) j else if (j == 0) i else 0,
+      ],
+  ];
+
+  for (var i = 1; i < from.length; i++) {
+    for (var j = 1; j < to.length; j++) {
+      // Removals from `from`.
+      var min = distances[i - 1][j] + 1;
+      // Additions to `from`.
+      min = math.min(min, distances[i][j - 1] + 1);
+      // Substitutions (and equality).
+      min = math.min(
+          min,
+          distances[i - 1][j - 1] +
+              // Cost is zero if substitution was not actually necessary.
+              (from[i] == to[j] ? 0 : 1));
+      // Allows for basic swaps, but no additional edits of swapped regions.
+      if (i > 1 && j > 1 && from[i] == to[j - 1] && from[i - 1] == to[j]) {
+        min = math.min(min, distances[i - 2][j - 2] + 1);
+      }
+      distances[i][j] = min;
+    }
+  }
+
+  return distances.last.last;
+}

pubspec.yaml

@@ -1,5 +1,5 @@
 name: args
-version: 2.1.1
+version: 2.2.0
 homepage: https://github.com/dart-lang/args
 description: >-
  Library for defining parsers for parsing raw command-line arguments into a set

test/command_runner_test.dart

@@ -239,6 +239,154 @@ information about a command.'''));
           completes);
     });
 
+    group('suggests similar commands', () {
+      test('deletions', () {
+        var command = FooCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['afoo', 'foao', 'fooa']) {
+          expect(() => runner.run([typo]), throwsUsageException('''
+Could not find a command named "$typo".
+
+Did you mean one of these?
+  foo
+''', anything));
+        }
+      });
+
+      test('additions', () {
+        var command = LongCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['ong', 'lng', 'lon']) {
+          expect(() => runner.run([typo]), throwsUsageException('''
+Could not find a command named "$typo".
+
+Did you mean one of these?
+  long
+''', anything));
+        }
+      });
+
+      test('substitutions', () {
+        var command = LongCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['aong', 'lang', 'lona']) {
+          expect(() => runner.run([typo]), throwsUsageException('''
+Could not find a command named "$typo".
+
+Did you mean one of these?
+  long
+''', anything));
+        }
+      });
+
+      test('swaps', () {
+        var command = LongCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['olng', 'lnog', 'logn']) {
+          expect(() => runner.run([typo]), throwsUsageException('''
+Could not find a command named "$typo".
+
+Did you mean one of these?
+  long
+''', anything));
+        }
+      });
+
+      test('combinations', () {
+        var command = LongCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['oln', 'on', 'lgn', 'alogn']) {
+          expect(() => runner.run([typo]), throwsUsageException('''
+Could not find a command named "$typo".
+
+Did you mean one of these?
+  long
+''', anything));
+        }
+      });
+
+      test('sorts by relevance', () {
+        var a = CustomNameCommand('abcd');
+        runner.addCommand(a);
+        var b = CustomNameCommand('bcd');
+        runner.addCommand(b);
+
+        expect(() => runner.run(['abdc']), throwsUsageException('''
+Could not find a command named "abdc".
+
+Did you mean one of these?
+  abcd
+  bcd
+''', anything));
+
+        expect(() => runner.run(['bdc']), throwsUsageException('''
+Could not find a command named "bdc".
+
+Did you mean one of these?
+  bcd
+  abcd
+''', anything));
+      });
+
+      test('omits commands with an edit distance over 2', () {
+        var command = LongCommand();
+        runner.addCommand(command);
+
+        for (var typo in ['llllong', 'aolgn', 'abcg', 'longggg']) {
+          expect(
+              () => runner.run([typo]),
+              throwsUsageException(
+                  'Could not find a command named "$typo".', anything));
+        }
+      });
+
+      test('max edit distance is configurable', () {
+        runner = CommandRunner('test', 'A test command runner.',
+            suggestionDistanceLimit: 1)
+          ..addCommand(LongCommand());
+        expect(
+            () => runner.run(['ng']),
+            throwsUsageException(
+                'Could not find a command named "ng".', anything));
+
+        runner = CommandRunner('test', 'A test command runner.',
+            suggestionDistanceLimit: 3)
+          ..addCommand(LongCommand());
+        expect(() => runner.run(['g']), throwsUsageException('''
+Could not find a command named "g".
+
+Did you mean one of these?
+  long
+''', anything));
+      });
+
+      test('supports subcommands', () {
+        var command = FooCommand();
+        command.addSubcommand(LongCommand());
+        runner.addCommand(command);
+        expect(() => runner.run(['foo', 'ong']), throwsUsageException('''
+Could not find a subcommand named "ong" for "test foo".
+
+Did you mean one of these?
+  long
+''', anything));
+      });
+
+      test('doesn\'t show hidden commands', () {
+        var command = HiddenCommand();
+        runner.addCommand(command);
+        expect(
+            () => runner.run(['hidde']),
+            throwsUsageException(
+                'Could not find a command named "hidde".', anything));
+      });
+    });
+
     group('with --help', () {
       test('with no command prints the usage', () {
         expect(() => runner.run(['--help']), prints('''

test/test_utils.dart

@@ -223,6 +223,16 @@ class AllowAnythingCommand extends Command {
   }
 }
 
+class CustomNameCommand extends Command {
+  @override
+  final String name;
+
+  CustomNameCommand(this.name);
+
+  @override
+  String get description => 'A command with a custom name';
+}
+
 void throwsIllegalArg(function, {String? reason}) {
   expect(function, throwsArgumentError, reason: reason);
 }
@@ -231,7 +241,7 @@ void throwsFormat(ArgParser parser, List<String> args) {
   expect(() => parser.parse(args), throwsFormatException);
 }
 
-Matcher throwsUsageException(String message, String usage) =>
+Matcher throwsUsageException(Object? message, Object? usage) =>
     throwsA(isA<UsageException>()
         .having((e) => e.message, 'message', message)
         .having((e) => e.usage, 'usage', usage));