Test: terminal suggest improvements

[meganrogge]

Refs #239519, #233799, #240408, #239515, #239518, #241252, #241220, #239977, #239028, #240104, #233368, #238085, #239022, #237979, #240661, #239978

• Linux @joshspicer
• macOS @chrmarti
• Windows @legomushroom

Complexity: 5

Authors: @meganrogge, @Tyriar

Roles: Developer, Engineering Manager

Create Issue

---

Overview

We’ve significantly improved shell completions across several shells—bash, zsh, fish, and pwsh. This update enhances ghost text detection, sorting, and documentation support among other areas. The following sections outline detailed steps to test each improvement.

Pre-requisites

• Terminal Settings:
  Ensure that terminal.integrated.suggest.enabled is enabled in your settings.
• Customization:
  Further customize settings under terminal.suggest as needed.

---

Testing Instructions

1. Improved Ghost Text Detection

• Background:
  Completions in fish were previously flaky due to incorrect ghost text parsing. Now, they should appear consistently. Additionally, inline suggestions (denoted with a ⭐ icon) should appear as the top suggestions.

• Steps:

  1. Enable and configure terminal.integrated.suggest.inlineSuggestion.
  2. Use a shell that supports inline completions and verify that suggestions appear consistently.
  3. Confirm that ghost text displays properly even if not styled as dimmed/italic.

  

---

2. Improved Sorting

• Background:
  Sorting now prioritizes commands with inline descriptions, details, and documentation. Commands with specs (or builtins) should appear before executables pulled from $PATH.

• Steps:

  1. Type co and verify that code (which has a spec) appears before col (an executable).
  2. Check that file suggestions starting with a–z are prioritized over those beginning with _, and that punctuation is ignored when sorting.

---

3. Enhanced Documentation Support

• Background:
  For bash and zsh, completions now include parsed documentation from man/help commands:

  • Inline: A concise command description.
  • Details Widget: Displays command arguments at the top and the full markdown-formatted description below.

• Steps:

  1. See the list of example zsh commands that should have these properties here. For bash, run compgen -b to get the list of builtin commands.
  2. Verify that each builtin command suggestion displays a brief inline description.
  3. Open the details widget to ensure that command arguments and full documentation are formatted correctly.
     

---

4. Aliases Support

• Background:
  Command aliases now appear in the suggestions list. Note that spec information may be missing for some aliases (see Issue #240374).

• Steps:

  1. Test various aliases and verify that they appear in the suggestion list.

---

5. File Path Extensions Filtering

• Background:
  File suggestions are now filtered by extensions for specific commands:

  • For python3, only .py files should be listed.
  • For node, only .mjs, .js, and .cjs files should appear.

• Steps:

  1. Run python3 in the terminal and confirm that only files ending in .py are suggested.
  2. Run node and verify that only the specified file extensions are displayed.

---

6. Path Resource Completion (Windows Specific)

• Background:
  Absolute path completion on Windows has been improved.

• Steps:

  1. Test drive suggestions:
     • Type cd | and verify that available drives (e.g., C:\, D:\) are shown.
  2. Test directory suggestions:
     • Type cd C:\| and confirm that directories (e.g., C:\Windows) with the same prefix are displayed.
  3. Test drive resolution:
     • Type cd :| to verify that all drives are shown.
  4. For bash and zsh, check that using ~ correctly resolves to the home directory.

---

7. Configuring quick suggestions

• Background:
  It can now be configured when suggestions automatically show up (aka. quick suggestions).

• Steps:

  1. Configure terminal.integrated.suggest.quickSuggestions and make sure each option works as expected.

[chrmarti]

On terminal.integrated.suggest.quickSuggestions: In which examples would unknown apply?

[Tyriar]

@chrmarti when unknown is true you'll see path suggestions a lot more, particularly when we don't have the fig spec. See the list at #241771 for commands where unknown does not apply.