Skip to content

Enhance ES|QL agent documentation #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timductive merged 1 commit into from
Jan 30, 2026
Merged

Enhance ES|QL agent documentation #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions src/platform/plugins/shared/esql/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,40 @@ If changes affect editor integrations or extension registry behavior, coordinate
- `src/platform/plugins/shared/esql/README.md`
- `src/platform/plugins/shared/esql/server/README.md`
- `src/platform/plugins/shared/esql/ADD_COMMAND_GUIDE.md`
- `src/platform/packages/shared/kbn-esql-language/README.md`
- `src/platform/packages/shared/kbn-esql-language/src/parser/README.md`
- `src/platform/packages/shared/kbn-esql-language/src/language/README.md`
- `src/platform/packages/shared/kbn-esql-language/src/commands/README.md`
- `src/platform/packages/shared/kbn-esql-language/src/composer/README.md`

## kbn-esql-language package guide
Package location: `src/platform/packages/shared/kbn-esql-language`

This package owns ES|QL parsing, AST utilities, and editor-facing language features
used by the ES|QL plugin and other consumers.

### What lives here
- Parser (ANTLR-based) → CST/AST + syntax validation, highlighting metadata.
- AST utilities: builder, walker, mutation, and pretty-printing.
- Language features: validation, autocomplete, hover, signature help.
- Commands: definitions and registry for ES|QL commands.
- Composer API: safe, parameterized ES|QL builder for app code.

### Key behavior
- Parser produces partial AST even with invalid queries; `withFormatting` attaches
comments/whitespace to nodes for editor features.
- Validation can degrade gracefully when callbacks (sources/fields) are missing;
keep this in mind when wiring UI services.
- Autocomplete works best-effort on invalid queries and may return empty results
when correction fails.
- Composer prefers tagged templates with parameter holes to avoid injection.

### Local demos
- ES|QL AST Inspector: `yarn storybook esql_ast_inspector`
- Kibana examples: `yarn start --run-examples` (navigate to ES|QL AST Inspector)

### Testing
- Whole package: `yarn test:jest src/platform/packages/shared/kbn-esql-language/`
- Targeted: `yarn jest:tests src/platform/packages/shared/kbn-esql-language/path/to/test/file`
- Validation tests update `src/validation/esql_validation_meta_tests.json` and should
be re-run when they change.
Loading