Allow filtering custom completions by description

[kiil]

Description

Allow filtering custom completions by description

When a custom completer returns suggestions with descriptions, only the value field was matched against the user's prefix. This made it impossible to narrow down a list by typing a fragment of the human-readable description — e.g. completing an email like lk446763made-up@gmx.net by typing the user's name "Lennart".

Add a new match_description option (default false) to the custom completion options record. When enabled, CustomCompletion::fetch also checks each suggestion's description against the active prefix using the configured match_algorithm, keeping a suggestion if either its value or description matches. The completed value remains the suggestion's value — only filtering is affected. Default behavior is unchanged.

Per review feedback, the option lives on the CompletionOptions struct rather than being threaded around as a separate bool, keeping completion configuration in one place.

User-facing changes (Release notes)

Custom completers can now opt into matching the user's prefix against suggestion descriptions in addition to values, by setting match_description: true in the returned options record. The inserted completion is still the suggestion's value.

def "nu-complete users" [] {
  {
    options: { match_description: true, completion_algorithm: "substring" }
    completions: [
      { value: "lk446763@example.com", description: "Lennart Kiil" }
      { value: "ab123456@example.com", description: "Alice Bob" }
    ]
  }
}

Additional notes

Addresses #18139

[fdncred]

I'm not sure how I feel about this. Completions are for completing commands not for completing descriptions.

[kiil]

@fdncred only the command (value) is completed. This simply allows for filtering both by value and description in the UI (where you use characters to filter and tab to complete).

Let's say the value is lk446763made-up@gmx.net and the description is "Some Full Name". Then you can filter by either, but only lk446763made-up@gmx.net ( the value that is sent to the command ) is completed.

I explain a use case in more detail here: #18139

[fdncred]

I feel like this should be a completion option vs working all the time.

nushell/crates/nu-cli/tests/completions/mod.rs

Line 133 in de614f1

{{ completions: [{}], options: {{ {} }} }}

nushell/crates/nu-cli/tests/completions/mod.rs

Line 342 in de614f1

options: { completion_algorithm: "substring" }

[kiil]

@fdncred I agree it would be best to make it optional, eventhough I feel it should be the default, because as long as the description is shown alongside the value, people will intuitively expect to be able to filter on the description also.

I do not really know how to make it configurable, though.

[fdncred]

I can see how it would be helpful. Lemme see what others think.

[kiil]

I amended the commit to include a bool completion config option for description.

[fdncred]

I think adding match_description is fine but that only works for custom completions written in nushell script, not for the built-in.

One way to get it to work for built-in menus is to change reedline to add another menu item bool.

This is how the default completion menu is defined:

const DEFAULT_COMPLETION_MENU: &str = r#"
{
  name: completion_menu
  only_buffer_difference: false
  marker: "| "
  type: {
      layout: columnar
      columns: 4
      col_width: 20
      col_padding: 2
      tab_traversal: "horizontal"
  }
  style: {
      text: green,
      selected_text: green_reverse
      description_text: yellow
  }
}"#;

Something could be added under tab_traversal, this way people could enable it or disable it pretty easily.

[kiil]

@fdncred

Do you think we can land this for custom completions first?

I am not too familiar with reedline functionality, but this PR for custom completions works regardless.

[fdncred]

I think we should be updating the completion_options struct here instead of passing around a new bool. Although not your changes, I think the same is true for should_sort and should_filter. Having options spread all over the place and not in the struct makes it very difficult to track what's going on.

[fdncred]

Let's maybe try and clean this up with the struct changes I suggested.

[kiil]

@fdncred - I'll have a look later today or tomorrow in the morning. Your comments and help are much appreciated.

[kiil]

@fdncred I think I managed to do what you asked for.

[fdncred]

I can land this when the CI is green and the Description is updated and in compliance with our default PR request template. Maybe look at others if you're not sure what that means. We use the template to create release notes and either you or your LLM created this PR request template out of spec.

[kiil]

I updated the PR according to the template.

[fdncred]

Thanks @kiil