# @elastic/esql-grammar

> **Do not edit any file in this package by hand.** All TypeScript files are auto-generated by
> the grammar sync CI job from `elastic/elasticsearch`. Edit the source grammar there.

Auto-generated ANTLR4 TypeScript lexer and parser artifacts for the ES|QL grammar.
This is an internal workspace package — it is not published to npm.

## Contents

| File | Description |
|------|-------------|
| `src/esql_lexer.g4` | ES|QL lexer grammar (source of truth: `elastic/elasticsearch`) |
| `src/esql_parser.g4` | ES|QL parser grammar |
| `src/esql_lexer.ts` | Generated ANTLR4 lexer |
| `src/esql_parser.ts` | Generated ANTLR4 parser |
| `src/esql_parser_listener.ts` | Generated parse-tree listener |
| `src/lexer/` | Supporting lexer sub-grammars |
| `src/parser/` | Supporting parser sub-grammars |
| `src/lexer_config.js` | Hand-written lexer superclass (PromQL depth tracking, feature flags) |
| `src/parser_config.js` | Hand-written parser superclass (feature flags) |

## Grammar sync

The CI job `.buildkite/scripts/esql_grammar_sync.sh` copies updated grammars from
`elastic/elasticsearch`, regenerates the TypeScript artifacts, and opens a PR touching
only this package. When the sync adds new grammar rules, a follow-up PR to
`@elastic/esql` wires them into the AST layer (see the `/grammar-sync-update` skill).

## Regenerate manually

```sh
yarn workspace @elastic/esql-grammar build:antlr4
```

Requires `antlr` CLI. Install on macOS with:

```sh
yarn workspace @elastic/esql-grammar antlr4:deps
```