Commits on Sep 26, 2024

1. [ES|QL] Comment parsing and pretty-printing (elastic#192173) …

   ## Summary
   
   TL;DR
   
   - Adds ability to parse out comments from source to AST.
   - Adds ability for every AST node to have *decoration*—comments,
   which can be attached from left, top, and right from the node.
   - Implements routine which attached comments to AST nodes.
   - In `BasicPrettyPrinter` adds support only for *left* and *right*
   comment printing, as the basic printer prints only on one line.
   - In `WrappingPrettyPrinter` adds support for all comment printing for
   all AST nodes.
   - Introduces a `Query` object and `query` AST node, which represent
   thole query—the root node, list of commands.
   - The ES|QL AST example plugin now displays the pretty-printed text
   version.
   
   ### Comments
   
   This PR introduced an optional `formatting` field for all AST nodes. In
   the `formatting` field one can specify comment decorations from
   different sides of a node.
   
   When parsing, once can now specify the `{ withComments: true }` option,
   which will collect all comments from the source while parsing using the
   `collectDecorations` routine. It will then also call the
   `attachDecorations`, which walks the AST and assigns each comment to
   some AST node.
   
   Further, traversal and pretty-print API have been updated to work with
   comments:
   
   - The `Walker` has been updated to be able to walk all comments from the
   AST.
   - The `BasicPrettyPrinter` adds support only for *left* and *right*
   inline comment printing, as the basic printer prints only on one line.
   - The `WrappingPrettyPrinter` adds support for all comment printing for
   all AST nodes. It switches to line-break printing mode if it detects
   there are comments with line breaks (those could be multi-line comments,
   or single line comments—single line comments are always followed
   by a line break). It also correctly inserts punctuation, when an AST
   node is surrounded by comments.
   
   ### Parsing utils
   
   All parsing utils have been moved to the `/parser` sub-folder.
   
   Files in the `/parser` folder have been renamed as per Kibana convention
   to reflect what is inside the file. For example, the `EsqlErrorListener`
   class is in a file named `esql_error_listener.ts`.
   
   A `Query` class and `ESQLAstQueryExpression` AST nodes have been
   introduced. They represent the result of a full query parse. (Before
   that, the AST root was just an array of command nodes, now the AST root
   is represented by the `ESQLAstQueryExpression` node.)
   
   ### Builder
   
   I have started the implementation of the `Builder` static class in the
   `/builder` folder. It is simply a collection of stateless AST node
   factories—functions which construct AST nodes.
   
   Some of the `Builder` methods are already used by the parser, more will
   follow. We will also use the `Builder` in upcoming [*Mutation
   API*](elastic#191812).
   
   ### ES|QL Example Plugin
   
   This PR sets up Storybook and implements few Storybook stories for the
   ES|QL AST example plugin, run it with:
   
   ```
   yarn storybook esql_ast_inspector
   ```
   
   This PR updates the *ES|QL AST Explorer* example plugin. Start Kibana
   with example plugins enabled:
   
   ```
   yarn start --run-examples
   ```
   
   And navigate to
   [`/app/esql_ast_inspector`](http://localhost:5601/app/esql_ast_inspector)
   to see the new example plugin UI.
   
   ![esql-ast-explorer](https://github.com/user-attachments/assets/8ded91ea-1b60-4514-8cf5-c8a4066a3a12)
   
   ### Checklist
   
   - [x] [Unit or functional
   tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
   were updated or added to match the most common scenarios
   
   ### For maintainers
   
   - [x] This was checked for breaking API changes and was [labeled
   appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
   
   ---------
   
   Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
   Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
   Co-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>
   (cherry picked from commit 2217337)

   

   vadimkibana committed Sep 26, 2024
   Configuration menu

   • View commit details
   • Copy full SHA for e5f98db
   • Browse repository at this point

   Copy the full SHA

   e5f98db View commit details

   Browse the repository at this point in the history