[ES|QL] improve function validation errors

[drewdaemon]

WHEN I have typed a function invocation
AND there are no matching function signatures
THEN I expect to see helpful feedback and guidance

Explanation

Today, our validation errors for functions suffer from a few shortcomings like

• [ES|QL] report all accepted types during parameter validation #183683
• [ES|QL] prioritize argument type error messages over argument count #180506

These generally come down to the validation engine making assumptions about which call signature to use to generate the validation messages.

We should get less smart to get more smart. To do this, we should give the user as much relevant information as possible without being overwhelming.

Note: This is not only a user-facing enhancement. Making these errors more deterministic will result in a more maintainable validation test suite since we always assert against the error strings. It is a pain if they change without changing meaningfully.

Proposed algorithm

Let `I` := the given invocation.

Let `A` := all function definitions with the same number of parameters (arity) as `I`.

If `A` is not the empty set

	Let `S` be the signature matching the invocation.

	If `S` is not `null`
		return.
	If `S` is `null`, 
		report the differences between `I` and each signature in `A`.

If `A` is the empty set
	report that `I` matches no call signature and list all valid signatures.

Examples

Given func has the following signatures

• version
• number, number
• string, string
• boolean, boolean, boolean

The following invocations should generate the following approximate error messages

func(number)

"Expected func(version) but found func(number)."

func(version, version)

"Expected one of func(number, number), func(string, string) but found func(version, version)."

func()

"Expected one of func(version), func(number, number), func(string, string), or func(boolean, boolean, boolean) but found func(version, version)."

[elasticmachine]

Pinging @elastic/kibana-esql (Team:ESQL)

[drewdaemon]

Impact low since the auto-complete should keep most users out of incorrect function signatures.

[drewdaemon]

Impact medium since this issue now encompasses a few key enhancements to our validation error messages.