[Search Bar/Query/Default Syntax] Parser support for "recognizedFields" options

[tsullivan]

Summary

Needed for: elastic/kibana#184496

Context: EUI exports a class called Query which is responsible for parsing search terms into an AST. The parse() method of the class accepts a ParseOptions object, which is what has been changed in this PR. The Query class and ParseOptions objects come into play when consumers of EuiSearchBar wish to manage the query outside of the component, otherwise the EuiSearchBar component will control parsing the search terms into an AST internally.

What this does: This PR updates the "default syntax" parser, used to determine queries for the Search Bar component, to support a "recognizedFields" optional option.

Why: When used for searching structured content that is managed by Kibana (i.e., the Global Search Bar and Saved Objects Finders) the search bar should work more intuitively by using logic to infer what the user is trying to do. If the search bar is designed to support field clauses such as type:typeA or tag:tagB, it would be illogical to infer that remote-cluster:my-remote-index is a field clause.

QA

General checklist

• Docs site QA - N/A, skipping due to advanced and slightly Kibana-specific usage
• Code quality checklist
  • Added or updated jest and cypress tests
• Release checklist
  • A changelog entry exists and is marked appropriately.

[cee-chen]

This looks great to me from an EUI point of view, thank you for the fantastic work Tim! I'll wait until end of week for @pugnascotia to chime in with any query/AST-specific feedback before merging.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 5e92233

History

• 💚 Build #2622 succeeded 707a9d0
• 💚 Build #2619 succeeded 99c447c
• 💚 Build #2582 succeeded c5a8707
• 💚 Build #2576 succeeded 8fe6363

[pugnascotia]

What is the ampersand doing here?

[tsullivan]

@pugnascotia

Unfortunately, PegJS documentation is no longer available directly, but it can be found here: http://web.archive.org/web/20240102234657/https://pegjs.org/documentation. Take a look under "Parsing Expression Types"

& expression
Try to match the expression. If the match succeeds, just return undefined and do not consume any input, otherwise consider the match failed.

In other words, the &{ return !hasRecognizedFields || recognizedFields.includes(id); } is a predicate check that determines whether the rule succeeds or fails. This check ensures that if hasRecognizedFields is truthy, then there is a restriction that the identifier must be included in the recognizedFields array to be treated as a field name. If the predicate passes, then the identifier is parsed as a field name. If the predicate does not pass, then the fieldName match is failed and the parser falls back to using the identifier rule.

By the way, I used Microsoft Copilot to explain this to me and help me with updating the parsing rules. If it wasn't for that, I am sure I would not have been able to figure it out.

[pugnascotia]

I checked the docs as they appear in source control, to double-check:

https://github.com/pegjs/pegjs/blob/master/docs/grammar/parsing-expression-types.md#--predicate-

So this looks good.

[pugnascotia]

LGTM