AST improvement: remove unnecessary [node] boxing into arrays

.changeset/ast-unboxing-major.md

@@ -0,0 +1,27 @@
+---
+'@elastic/esql-types': major
+'@elastic/esql-traversal': major
+'@elastic/esql-parser': minor
+'@elastic/esql': minor
+---
+
+Remove array-boxed nodes (`[node]`) from the ES|QL AST — in parser output and in the type system.
+
+**Breaking changes in `@elastic/esql-types`:**
+
+- `ESQLAstItem` no longer has an array arm: it is now a deprecated alias of `ESQLSingleAstItem`. Code that hand-builds boxed args (`args: [left, [right]]`) no longer compiles — write `args: [left, right]` instead.
+- `args` is narrowed from `ESQLAstItem[]` to `ESQLAstExpression[]` on `ESQLCommand`, `ESQLCommandOption`, `ESQLFunction`, and `ESQLFunctionCallExpression`, and the `ESQLUnaryExpression`, `ESQLPostfixUnaryExpression`, `ESQLOrderExpression`, and `ESQLBinaryExpression` tuples are narrowed accordingly.
+- `ESQLProperNode` is now a deprecated alias of `ESQLAstNode` — all nodes are *proper* nodes now.
+
+**Breaking changes in `@elastic/esql-traversal`:**
+
+- `Walker.walkExpression()` is typed `ESQLAstExpression | ESQLAstExpression[]` (previously relied on the `ESQLAstItem` array arm).
+- `VisitorContext.args()` yields `ESQLAstExpression` and no longer yields raw arrays.
+- `firstItem`, `lastItem`, `resolveItem`, and `singleItems` are deprecated: the AST no longer contains array-boxed nodes, so access args directly (`args[0]`, `args.at(-1)`, plain iteration). They remain exported and runtime-tolerant of legacy boxed input for one major cycle.
+
+**Parser output changes (`@elastic/esql-parser`):**
+
+- No AST node is ever wrapped in an array anymore. Notable shapes that changed: `LIMIT ?` / `SAMPLE ?` (`args: [[param]]` to `args: [param]`), `DISSECT ... append_separator=?`, `RERANK ?` (`query` was an array in violation of its declared type), `WHERE x : ?`, and field assignments (`args: [column, [expression]]` to `args: [column, expression]`).
+- A missing assignment right-hand side (`SET x =`, `ENRICH p WITH x =`) is now an explicit `{ type: 'unknown', incomplete: true }` placeholder node instead of an empty array.
+
+**Migration:** replace `[node]` boxing with `node` when building ASTs; replace `firstItem(args)`/`resolveItem(arg)`/`lastItem(args)`/`singleItems(args)` with `args[0]`/`arg`/`args.at(-1)`/`args`.

packages/esql-ast/src/esql/builder/builder.ts

@@ -34,7 +34,6 @@ import type {
   ESQLSource,
   ESQLParamLiteral,
   ESQLFunction,
-  ESQLAstItem,
   ESQLStringLiteral,
   ESQLBinaryExpression,
   ESQLUnaryExpression,
@@ -349,7 +348,7 @@ export namespace Builder {
 
       export const call = (
         nameOrOperator: string | ESQLIdentifier | ESQLParamLiteral,
-        args: ESQLAstItem[],
+        args: ESQLAstExpression[],
         template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
         fromParser?: Partial<AstNodeParserFields>
       ): ESQLFunction => {
@@ -370,7 +369,7 @@ export namespace Builder {
 
       export const unary = (
         name: string,
-        arg: ESQLAstItem,
+        arg: ESQLAstExpression,
         template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
         fromParser?: Partial<AstNodeParserFields>
       ): ESQLUnaryExpression => {
@@ -383,7 +382,7 @@ export namespace Builder {
 
       export const postfix = (
         name: string,
-        arg: ESQLAstItem,
+        arg: ESQLAstExpression,
         template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
         fromParser?: Partial<AstNodeParserFields>
       ): ESQLUnaryExpression => {
@@ -396,7 +395,7 @@ export namespace Builder {
 
       export const binary = <Name extends BinaryExpressionOperator = BinaryExpressionOperator>(
         name: Name,
-        args: [left: ESQLAstItem, right: ESQLAstItem],
+        args: [left: ESQLAstExpression, right: ESQLAstExpression],
         template?: Omit<AstNodeTemplate<ESQLBinaryExpression<Name>>, 'subtype' | 'name' | 'args'>,
         fromParser?: Partial<AstNodeParserFields>
       ): ESQLBinaryExpression<Name> => {
@@ -409,7 +408,7 @@ export namespace Builder {
     }
 
     export const where = (
-      args: [left: ESQLAstItem, right: ESQLAstItem],
+      args: [left: ESQLAstExpression, right: ESQLAstExpression],
       template?: Omit<AstNodeTemplate<ESQLFunction>, 'subtype' | 'name' | 'operator' | 'args'>,
       fromParser?: Partial<AstNodeParserFields>
     ) => Builder.expression.func.binary('where', args, template, fromParser);

packages/esql-ast/src/esql/is.ts

@@ -132,7 +132,7 @@ export const isESQLFunction = (node: unknown): node is types.ESQLFunction =>
   (node as types.ESQLFunction).type === 'function';
 
 export const isESQLNamedParamLiteral = (
-  node: types.ESQLAstItem
+  node: types.ESQLAstExpression
 ): node is types.ESQLNamedParamLiteral =>
   isESQLAstBaseItem(node) &&
   (node as types.ESQLNamedParamLiteral).literalType === 'param' &&

packages/esql-parser/src/esql/__tests__/binary_expression_grouping.test.ts

@@ -6,19 +6,15 @@
  */
 
 import { EsqlQuery } from './query';
-import type { ESQLAstItem, ESQLAstQueryExpression, ESQLProperNode } from '@elastic/esql-types';
-import { singleItems, Walker } from '@elastic/esql-traversal';
+import type { ESQLAstQueryExpression, ESQLProperNode } from '@elastic/esql-types';
+import { Walker } from '@elastic/esql-traversal';
 
 const removeParserFields = (tree: ESQLAstQueryExpression): void => {
   Walker.walk(tree, {
     visitAny: (node: Partial<ESQLProperNode>) => {
       delete node.text;
       delete node.location;
       delete node.incomplete;
-      const args = (node as { args?: ESQLAstItem[] }).args;
-      if (Array.isArray(args)) {
-        (node as { args?: ESQLAstItem[] }).args = [...singleItems(args)];
-      }
     },
   });
 };

packages/esql-parser/src/esql/__tests__/completion.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { EsqlQuery } from './query';
-import type { ESQLAstCompletionCommand, ESQLAstItem, ESQLFunction } from '@elastic/esql-types';
+import type { ESQLAstCompletionCommand, ESQLFunction } from '@elastic/esql-types';
 
 describe('COMPLETION command', () => {
   describe('correctly formatted', () => {
@@ -35,7 +35,7 @@ describe('COMPLETION command', () => {
       it('parses prompt when it is a param', () => {
         const text = `FROM index | COMPLETION ? WITH { "inference_id": "my_inference_endpoint" }`;
         const query = EsqlQuery.fromSrc(text);
-        const promptArg = query.ast.commands[1].args[0] as ESQLAstItem[];
+        const promptArg = query.ast.commands[1].args[0];
 
         expect(promptArg).toMatchObject({
           type: 'literal',

packages/esql-parser/src/esql/__tests__/header.set.test.ts

@@ -470,7 +470,10 @@ describe('SET instruction parsing', () => {
             type: 'function',
             subtype: 'binary-expression',
             name: '=',
-            args: [{ type: 'identifier', name: 'timezone' }, []],
+            args: [
+              { type: 'identifier', name: 'timezone' },
+              { type: 'unknown', incomplete: true },
+            ],
             incomplete: true,
           },
         ],

packages/esql-parser/src/esql/__tests__/limit.test.ts

@@ -27,22 +27,20 @@ describe('LIMIT', () => {
           type: 'command',
           name: 'limit',
           args: [
-            [
-              {
-                incomplete: false,
-                name: '',
-                paramKind: '?',
-                paramType: 'named',
-                text: '?param',
-                type: 'literal',
-                literalType: 'param',
-                value: 'param',
-                location: {
-                  max: 24,
-                  min: 19,
-                },
+            {
+              incomplete: false,
+              name: '',
+              paramKind: '?',
+              paramType: 'named',
+              text: '?param',
+              type: 'literal',
+              literalType: 'param',
+              value: 'param',
+              location: {
+                max: 24,
+                min: 19,
               },
-            ],
+            },
           ],
         },
       ]);

packages/esql-parser/src/esql/__tests__/rerank.test.ts

@@ -136,12 +136,10 @@ describe('RERANK', () => {
             name: '=',
             args: [
               {},
-              [
-                {
-                  type: 'function',
-                  name: 'substring',
-                },
-              ],
+              {
+                type: 'function',
+                name: 'substring',
+              },
             ],
           },
         ],

packages/esql-parser/src/esql/__tests__/stats.test.ts

@@ -102,18 +102,16 @@ describe('STATS', () => {
                     },
                   ],
                 },
-                [
-                  {
-                    type: 'function',
-                    name: 'agg',
-                    args: [
-                      {
-                        type: 'literal',
-                        valueUnquoted: 'salary',
-                      },
-                    ],
-                  },
-                ],
+                {
+                  type: 'function',
+                  name: 'agg',
+                  args: [
+                    {
+                      type: 'literal',
+                      valueUnquoted: 'salary',
+                    },
+                  ],
+                },
               ],
             },
           ],
@@ -293,18 +291,16 @@ describe('STATS', () => {
                           },
                         ],
                       },
-                      [
-                        {
-                          type: 'function',
-                          name: 'agg',
-                          args: [
-                            {
-                              type: 'literal',
-                              valueUnquoted: 'salary',
-                            },
-                          ],
-                        },
-                      ],
+                      {
+                        type: 'function',
+                        name: 'agg',
+                        args: [
+                          {
+                            type: 'literal',
+                            valueUnquoted: 'salary',
+                          },
+                        ],
+                      },
                     ],
                   },
                   {