[ES|QL] Support all AST node types in Walker (elastic#188712)

## Summary

Partially addresses elastic#182255

- This PR add support for all ES|QL AST node types in the `Walker`
class, which means all nodes from any query now will be visited.


### Checklist

Delete any items that are not applicable to this PR.

- [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)

packages/kbn-esql-ast/src/types.ts

@@ -12,20 +12,27 @@ export type ESQLAstCommand = ESQLCommand | ESQLAstMetricsCommand;
 
 export type ESQLAstNode = ESQLAstCommand | ESQLAstItem;
 
+/**
+ * Represents an *expression* in the AST.
+ */
 export type ESQLSingleAstItem =
-  | ESQLFunction
+  | ESQLFunction // "function call expression"
   | ESQLCommandOption
-  | ESQLSource
-  | ESQLColumn
+  | ESQLSource // "source identifier expression"
+  | ESQLColumn // "field identifier expression"
   | ESQLTimeInterval
-  | ESQLList
-  | ESQLLiteral
+  | ESQLList // "list expression"
+  | ESQLLiteral // "literal expression"
   | ESQLCommandMode
-  | ESQLInlineCast
+  | ESQLInlineCast // "inline cast expression"
   | ESQLUnknownItem;
 
 export type ESQLAstField = ESQLFunction | ESQLColumn;
 
+/**
+ * An array of AST nodes represents different things in different contexts.
+ * For example, in command top level arguments it is treated as an "assignment expression".
+ */
 export type ESQLAstItem = ESQLSingleAstItem | ESQLAstItem[];
 
 export interface ESQLLocation {

packages/kbn-esql-ast/src/walker/README.md

@@ -0,0 +1,41 @@
+# ES|QL AST Walker
+
+The ES|QL AST Walker is a utility that traverses the ES|QL AST and provides a
+set of callbacks that can be used to perform introspection of the AST.
+
+To start a new *walk* you create a `Walker` instance and call the `walk()` method
+with the AST node to start the walk from.
+
+```ts
+
+import { Walker, getAstAndSyntaxErrors } from '@kbn/esql-ast';
+
+const walker = new Walker({
+  // Called every time a function node is visited.
+  visitFunction: (fn) => {
+    console.log('Function:', fn.name);
+  },
+  // Called every time a source identifier node is visited.
+  visitSource: (source) => {
+    console.log('Source:', source.name);
+  },
+});
+
+const { ast } = getAstAndSyntaxErrors('FROM source | STATS fn()');
+walker.walk(ast);
+```
+
+Conceptual structure of an ES|QL AST:
+
+- A single ES|QL query is composed of one or more source commands and zero or
+  more transformation commands.
+- Each command is represented by a `command` node.
+- Each command contains a list expressions named in ES|QL AST as *AST Item*.
+  - `function` — function call expression.
+  - `option` — a list of expressions with a specific role in the command.
+  - `source` — s source identifier expression.
+  - `column` — a field identifier expression.
+  - `timeInterval` — a time interval expression.
+  - `list` — a list literal expression.
+  - `literal` — a literal expression.
+  - `inlineCast` — an inline cast expression.