docs: update readme and docs (#32)

Co-authored-by: Scarlett Eliza <[email protected]>
Co-authored-by: Felix Angelov <[email protected]>

Author: 3 people

.github/cspell.json

@@ -0,0 +1,24 @@
+{
+  "version": "0.2",
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "dictionaries": ["vgv_allowed", "vgv_forbidden"],
+  "dictionaryDefinitions": [
+    {
+      "name": "vgv_allowed",
+      "path": "https://raw.githubusercontent.com/verygoodopensource/very_good_dictionaries/main/allowed.txt",
+      "description": "Allowed VGV Spellings"
+    },
+    {
+      "name": "vgv_forbidden",
+      "path": "https://raw.githubusercontent.com/verygoodopensource/very_good_dictionaries/main/forbidden.txt",
+      "description": "Forbidden VGV Spellings"
+    }
+  ],
+  "useGitignore": true,
+
+  "words": [
+    "subcommand",
+    "inverseflag",
+    "trueflag"
+  ]
+}

.github/workflows/main.yaml

@@ -16,6 +16,12 @@ jobs:
   semantic_pull_request:
     uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/semantic_pull_request.yml@v1
 
+  spell-check:
+    uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/spell_check.yml@v1
+    with:
+      includes: "**/*.md"
+      modified_files_only: false
+
   build:
     uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
 

README.md

@@ -1,69 +1,92 @@
-# Cli Completion
 
+# CLI Completion
+
+[![Very Good Ventures][logo_white]][very_good_ventures_link_dark]
+[![Very Good Ventures][logo_black]][very_good_ventures_link_light]
+
+[![pub package][pub_badge]][pub_link]
 [![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
-[![Powered by Mason](https://img.shields.io/endpoint?url=https%3A%2F%2Ftinyurl.com%2Fmason-badge)](https://github.com/felangel/mason)
 [![License: MIT][license_badge]][license_link]
 
-Completion toolkit for Command runner based Dart CLIs
+---
 
-## Installation 💻
+Completion functionality for Dart Command-Line Interfaces built using CommandRunner.
 
-**❗ In order to start using Cli Completion you must have the [Dart SDK][dart_install_link] installed on your machine.**
+Developed with 💙 by [Very Good Ventures][very_good_ventures_link] 🦄
 
-Add `cli_completion` to your `pubspec.yaml`:
 
-```yaml
-dependencies:
-  cli_completion:
-```
+## Installation 💻
 
-Install it:
+**❗ In order to start using CLI Completion you must have the [Dart SDK][dart_install_link] installed
+on your machine.**
 
-```sh
-dart pub get
+```
+flutter pub add cli_completion
 ```
 
----
 
-## Continuous Integration 🤖
 
-Cli Completion comes with a built-in [GitHub Actions workflow][github_actions_link] powered by [Very Good Workflows][very_good_workflows_link] but you can also add your preferred CI/CD solution.
+## Usage ✨
 
-Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Workflows][very_good_coverage_link].
+On your `CommandRunner` class, extend `CompletionCommandRunner` :
 
----
+```dart
+import 'package:cli_completion/cli_completion.dart';
 
-## Running Tests 🧪
+class ExampleCommandRunner extends CompletionCommandRunner<int> {
+...
+```
+This will make the first command run to install the completion files automatically. To disable that behavior, set `enableAutoInstall` to false:
+
+```dart
+class ExampleCommandRunner extends **CompletionCommandRunner**<int> {
+  
+  @override
+  bool get enableAutoInstall => false;
+...
+```
 
-To run all unit tests:
+When `enableAutoInstall` is set to false, users will have to call `install-completion-files` to install these files manually.
 
-```sh
-dart pub global activate coverage 1.2.0
-dart test --coverage=coverage
-dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info
+```bash
+$ example_cli install-completion-files
 ```
 
-To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov).
+## Documentation 📝
+
+For an overview of how this package works, check out the [documentation][docs_link].
+
+---
+
+### ⚠️ Using analytics
+
+Handling completion requests should be straightforward.
+
+If there are any checks (like analytics, telemetry, or anything that you may have on `run` or `runCommand` overrides) before running subcommands, make sure you fast track the `completion` command to skip all of the unnecessary computations.
 
-```sh
-# Generate Coverage Report
-genhtml coverage/lcov.info -o coverage/
+Example:
 
-# Open Coverage Report
-open coverage/index.html
+```dart
+@override
+Future<int?> runCommand(ArgResults topLevelResults) async {
+  if (topLevelResults.command?.name == 'completion') {
+    super.runCommand(topLevelResults);
+      return;
+  }
+  // ... analytics and other unrelated stuff 
 ```
 
 [dart_install_link]: https://dart.dev/get-dart
-[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions
 [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
 [license_link]: https://opensource.org/licenses/MIT
 [logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only
 [logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only
-[mason_link]: https://github.com/felangel/mason
 [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
 [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
-[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage
 [very_good_ventures_link]: https://verygood.ventures
 [very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only
 [very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only
 [very_good_workflows_link]: https://github.com/VeryGoodOpenSource/very_good_workflows
+[docs_link]: https://github.com/VeryGoodOpenSource/cli_completion/tree/main/doc
+[pub_link]: https://cli_completion.pckg.pub
+[pub_badge]: https://img.shields.io/pub/v/cli_completion.svg

doc/README.md

@@ -0,0 +1,75 @@
+# CLI Completion
+
+`cli_completion` is a Dart package that aims to enable Dart CLI applications to receive shell completions with minimal setup. You can also customize completion suggestions programmatically.
+
+It is inspired by Kevin Moore's package [completion](https://pub.dev/packages/completion) and the excellent [tab tab package](https://github.com/mklabs/tabtab) for JS CLIs.
+
+It works on bash and zsh on Linux, macOS, and Windows.
+
+## How It Works
+
+There are several ways to achieve shell completions for CLI commands. Most of them depend on which shell you are using and, in some cases, the terminal.
+
+The approach used by `cli_completion` is to create shell script files in a directory under the user's home ( `~/.dart-cli-completion`  for Linux/macOS users) and then source these scripts in the shell initialization files (`~/.zshrc`, for example).
+
+We call this process [installation](#the-installation-process).
+
+Then, scripts are installed and sourced (via `source ~/.zshrc`).
+
+These scripts instruct the shell to call the “completion” subcommand in the CLI when the user presses <TAB>.
+
+Then, the messages generated by that command will be sent back to the shell, which will take care of formatting it and displaying it to the user as completion suggestions.
+
+We call this process [parsing](#how-parsing-completion-works) .
+
+### The Installation Process
+
+The class `CompletionCommandRunner` tries to create these files upon any command run. It does nothing if the completion files exist and displays a short error message if there is an error in the process.
+
+To disable this behavior, set `enableAutoInstall` to false on your `CompletionCommandRunner` subclass.
+
+### How Parsing Completion Works
+
+`CompletionCommandRunner` is responsible for handling the `completion` sub-command and reading some particular environment variables that contain the state of the user input upon tab press.
+
+Once it parses the user input, it reads the `ArgParser` grammar to create valid suggestions.
+
+### Use Cases
+
+You can find below some completion use cases that is handled by this package:
+
+Completes with options and subcommands:
+```bash
+$ example_cli |
+--rootFlag          -- A flag: in the root command
+some_command        -- This is help for some_command
+some_other_command  -- This is help for some_other_command
+```
+
+Completes partially written commands and options:
+```bash
+$ example_cli some|
+some_command        -- This is help for some_command
+```
+
+Hides aliases and hidden options and commands:
+```bash
+$ example_cli some_command|
+--continuous   -- A continuous option: any value is allowed
+--discrete     -- A discrete option with "allowed" values (mandatory)
+--help         -- Print this usage information.
+--inverseflag  -- A flag that the default value is true
+--multi-c      -- An continuous option that can be passed multiple times
+--multi-d      -- An discrete option that can be passed multiple times 
+--trueflag     -- A flag that cannot be negated
+```
+ 
+Completes with values of option with "allowed" values:
+```bash
+example_cli some_command --discrete |
+bar  -- bar help
+faa  -- faa help
+foo  -- foo help
+```
+
+For more use cases, check out the [integration tests](https://github.com/VeryGoodOpenSource/cli_completion/blob/main/example/test/integration/completion_integration_test.dart).

lib/src/command_runner/completion_command_runner.dart

@@ -52,6 +52,7 @@ abstract class CompletionCommandRunner<T> extends CommandRunner<T> {
   bool get enableAutoInstall => true;
 
   /// The [CompletionInstallation] used to install completion files.
+  @visibleForTesting
   CompletionInstallation get completionInstallation {
     var completionInstallation = _completionInstallation;