Rank function completion by known input type compatibility #58

Goal

Improve function-name completion by ranking functions according to the type of the value flowing into the completion position when that type can be determined reliably.

Type information is optional. In many Expressif expressions the current value is dynamically typed or cannot be inferred statically. In those cases completion must preserve the existing catalog-based behavior unchanged.

This feature is therefore an opportunistic ranking improvement, not a prerequisite for completion and not a strict type filter.

Expected behavior

When the input type is known, rank function completions by compatibility with that input.

Conceptually:

exact match
implicitly coercible
incompatible

For example, given:

.amount |

if the language server can determine that .amount is numeric, numeric functions should rank ahead of functions requiring an implicit coercion, which in turn should rank ahead of functions known to be incompatible.

The exact functions and compatibility rules come from Expressif itself.

Unknown input types

Unknown input types are expected and common.

For example:

@value |

may provide no reliable static type for @value.

In that case the server must fall back to the existing completion behavior:

function catalog + existing deterministic ranking

No function should be removed or demoted merely because the input type could not be established.

Unknown type is therefore a property of the completion context, not a per-function compatibility category that needs to be exposed to the user.

Ranking, not filtering

This feature must never turn completion into a hard type gate.

All normal function candidates should remain discoverable. Known compatibility only influences ordering.

When the input type is known, the preferred order is:

Exact
Coercible
Incompatible

When the input type is unknown, preserve the existing ordering.

No Compatible / All completion modes are required for this feature.

Implicit coercion

Expressif supports implicit coercion, so a function whose declared input type does not exactly match the current value may still be fully valid.

Completion ranking must therefore distinguish direct compatibility from compatibility through implicit coercion.

The language server must not maintain its own coercion matrix or duplicate Expressif binding rules.

Conceptually:

Expressif semantic/type API
      │
      ├── inferred/known input type
      └── compatibility with function input
              │
              ├── exact
              ├── coercible
              └── incompatible
                      │
                      ▼
               CompletionService

Expressif remains authoritative for whether an input can be accepted directly or through coercion.

Scope

Implement type-aware ranking for function completion that:

• determines the value flowing into a function completion position when possible;
• obtains a reliable input type only where Expressif's semantic/type model can provide one;
• ranks exact input matches first;
• ranks implicitly coercible matches next;
• ranks known incompatible functions after compatible functions;
• leaves the candidate set intact;
• falls back to current catalog-based completion when the input type is unknown;
• keeps ordering deterministic within each compatibility class;
• remains editor-agnostic.

Initial support may focus on pipeline positions where the input value and its type can be identified reliably.

Shared function metadata

The existing shared function catalog remains the source of available functions and their metadata.

This issue must not introduce a second function catalog.

If function input-type information or compatibility information is not currently exposed by Expressif in a reusable form, the required semantic/type capability should be added to Expressif itself and then consumed by the language server.

The language server should not infer compatibility from function names, documentation text, or duplicated type rules.

LSP ordering

Use standard LSP completion ordering mechanisms such as sortText where practical.

The displayed function label and insertion behavior should remain unchanged from ordinary function completion.

Compatibility affects ranking only.

Within one compatibility category, preserve a stable secondary ordering consistent with existing completion behavior.

Examples

Known type

.amount |

Conceptual ordering:

multiply            exact
round               exact
some-text-function  coercible
some-date-function  incompatible

Unknown type

@value |

Completion should behave like the existing function-name completion and should not invent a type merely to rank results.

Implicit coercion

If Expressif allows the known input type to be coerced to a function's accepted input type, that function should remain a high-quality completion candidate, but below a direct type match.

Acceptance criteria

• Existing function completion continues to work when no input type is known.
• Unknown input types preserve the current catalog-based completion ordering/behavior.
• When an input type is known, exact matches rank ahead of functions requiring implicit coercion.
• Coercible matches rank ahead of known incompatible functions.
• No normal function candidates are filtered out solely because of type compatibility.
• Implicit coercion rules come from Expressif rather than being duplicated in the language server.
• The existing shared function catalog remains the source of available functions.
• Ranking is deterministic within each compatibility class.
• Standard LSP completion ordering mechanisms are used where practical.
• Initial pipeline scenarios with known types are covered by tests.
• Unknown/dynamic input scenarios are covered by tests.
• Implicit coercion scenarios are covered by tests.
• Known incompatible scenarios are covered by tests.
• The implementation remains editor-agnostic.

Out of scope

• Filtering the completion list by type.
• Requiring complete type inference before providing completion.
• Adding user-facing completion modes such as Compatible versus All.
• Reimplementing Expressif coercion or binding rules in the language server.
• Full data-flow/type inference across every Expressif construct.
• Parameter-value completion.
• Reporting coercion as a diagnostic.
• Automatically inserting explicit coercion functions.
• VS Code-specific completion logic.