feat(cli): provide shell completion scripts (#477)

* feat(cli): provide shell completion scripts

Resolves #262

* Rework completion support to be more like ruff

* Add `just install-binary`

* Derive `clap::ValueEnum` for `LogLevel`

So we get completions and the standardized `[possible values: <enum>]` docs

* Add `--help` test for `generate-shell-completion`

* CHANGELOG bullet

* Add documentation

* Normalize executable name

---------

Co-authored-by: Davis Vaughan <davis@posit.co>

Author: salim-b

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 # Development version
 
+- New `air generate-shell-completion <SHELL>` hidden command that emits a script to stdout that generates shell completions. Supports bash, zsh, fish, powershell, and elvish (#477, @salim-b).
+
+  For zsh, run the following to add to your `.zshrc`:
+
+  ```bash
+  echo 'eval "$(air generate-shell-completion zsh)"' >> ~/.zshrc
+  ```
+
+  For powershell, run the following to add to your profile:
+
+  ```powershell
+  if (!(Test-Path -Path $PROFILE)) {
+    New-Item -ItemType File -Path $PROFILE -Force
+  }
+  Add-Content -Path $PROFILE -Value '(& air generate-shell-completion powershell) | Out-String | Invoke-Expression'
+  ```
+
+  Then restart your shell and type `air <tab>` to see completions.
 
 # 0.8.2
 

Cargo.lock

@@ -33,6 +33,7 @@ bytes = "1.8.0"
 cargo_metadata = "0.20.0"
 case = "1.0.0"
 clap = { version = "4.5.20", features = ["derive"] }
+clap_complete = "4.5.66"
 colored = "3.0.0"
 comments = { path = "./crates/comments" }
 crates = { path = "./crates/crates" }

Cargo.toml

@@ -14,6 +14,7 @@ publish = true
 [dependencies]
 anyhow = { workspace = true }
 clap = { workspace = true, features = ["wrap_help"] }
+clap_complete = { workspace = true }
 colored = { workspace = true }
 crates = { workspace = true }
 fs = { workspace = true }

crates/air/Cargo.toml

@@ -37,6 +37,10 @@ pub(crate) enum Command {
 
     /// Start a language server
     LanguageServer(LanguageServerCommand),
+
+    /// Generate shell completion scripts
+    #[clap(hide = true)]
+    GenerateShellCompletion(GenerateShellCompletionCommand),
 }
 
 #[derive(Clone, Debug, Parser)]
@@ -55,12 +59,17 @@ pub(crate) struct FormatCommand {
 #[derive(Clone, Debug, Parser)]
 pub(crate) struct LanguageServerCommand {}
 
+#[derive(Clone, Debug, Parser)]
+pub(crate) struct GenerateShellCompletionCommand {
+    /// The shell for which to generate the completion script
+    pub shell: clap_complete::Shell,
+}
+
 /// All configuration options that can be passed "globally"
 #[derive(Debug, Default, clap::Args)]
 #[command(next_help_heading = "Global options")]
 pub(crate) struct GlobalOptions {
-    /// The log level. One of: `error`, `warn`, `info`, `debug`, or `trace`. Defaults
-    /// to `warn`.
+    /// The log level [default: warn]
     #[arg(long, global = true)]
     pub(crate) log_level: Option<logging::LogLevel>,
 

crates/air/src/args.rs

@@ -1,2 +1,3 @@
 pub(crate) mod format;
+pub(crate) mod generate_shell_completion;
 pub(crate) mod language_server;

crates/air/src/commands.rs

@@ -0,0 +1,15 @@
+use crate::args::{Args, GenerateShellCompletionCommand};
+use crate::status::ExitStatus;
+use clap::CommandFactory;
+
+pub(crate) fn generate_shell_completion(
+    command: GenerateShellCompletionCommand,
+) -> anyhow::Result<ExitStatus> {
+    clap_complete::generate(
+        command.shell,
+        &mut Args::command(),
+        "air",
+        &mut std::io::stdout(),
+    );
+    Ok(ExitStatus::Success)
+}

crates/air/src/commands/generate_shell_completion.rs

@@ -17,6 +17,9 @@ pub fn run(args: Args) -> anyhow::Result<ExitStatus> {
     }
 
     match args.command {
+        Command::GenerateShellCompletion(command) => {
+            commands::generate_shell_completion::generate_shell_completion(command)
+        }
         Command::Format(command) => commands::format::format(command),
         Command::LanguageServer(command) => commands::language_server::language_server(command),
     }

crates/air/src/lib.rs

@@ -58,7 +58,7 @@ fn turn_off_colors(
     layer.with_ansi(false)
 }
 
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, clap::ValueEnum)]
 pub(crate) enum LogLevel {
     Error,
     #[default]

crates/air/src/logging.rs

@@ -0,0 +1,70 @@
+use std::process::Command;
+
+use crate::helpers::CommandExt;
+use crate::helpers::binary_path;
+
+#[test]
+fn test_completions_help() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("--help")
+            .run()
+            .normalize_os_executable_name()
+    );
+}
+
+#[test]
+fn test_completions_bash() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("bash")
+            .run()
+            .normalize_os_executable_name()
+    );
+}
+
+#[test]
+fn test_completions_elvish() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("elvish")
+            .run()
+            .normalize_os_executable_name()
+    );
+}
+
+#[test]
+fn test_completions_fish() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("fish")
+            .run()
+            .normalize_os_executable_name()
+    );
+}
+
+#[test]
+fn test_completions_powershell() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("powershell")
+            .run()
+            .normalize_os_executable_name()
+    );
+}
+
+#[test]
+fn test_completions_zsh() {
+    insta::assert_snapshot!(
+        Command::new(binary_path())
+            .arg("generate-shell-completion")
+            .arg("zsh")
+            .run()
+            .normalize_os_executable_name()
+    );
+}