# JQL AST

[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)

JQL Abstract Syntax Tree (JAST) is a json schema used to represent parsed JQL.

### Goals
- A Jast from one platform should be re-usable as a Jast from another (Java ↔︎ JS ↔︎ iOS)
- Contain enough information to render a rich JQL editing experience (e.g. Syntax highlighting)
- Represent invalid and partially formed JQL (and contain detailed information on syntax errors)

### What Jast is not
- Does not represent every detail appearing in the real syntax, but rather just the structural or content-related details (e.g. Parentheses are implicit in the tree structure so they are not included as nodes)
- Does not contain any data specific to a individual Jira instance (besides the string of the original JQL query itself). Eg: no knowledge of available fields/users/values/operators
- Syntax validation should not be performed on the Jast (this is done using the CST)
- Autocomplete suggestions should not be populated using the Jast (this is done using the CST)

### Use cases
- Syntax highlighting
- Rendering errors

## Basic usage

To generate an AST you need the JQL string you want to parse and a `JastBuilder`.

```typescript
import { JastBuilder, Jast } from "@atlassianlabs/jql-ast";

const someJqlQuery = 'issuetype = bug';
const myJast: Jast = new JastBuilder().build(someJqlQuery);
```

## Installation

```sh
yarn add @atlassianlabs/jql-ast
```

## Documentation

Refer to [docs](docs/README.md) for more details.

## FAQ

#### Why do we need an Abstact Syntaxt Tree (over the free CST)?

ANTLR4 auto-generated parsers already generate a Concrete Syntax Tree from a JQL string. This tree is more detailed than
the AST but otherwise VERY similar, why not just use that?

The main reason is that the CST doesn’t immediately fulfill all of the listed goals above. But there are some other
differences to mention:

- The produced CST is not directly under our control, so updates to ANTLR4 syntax implementation only need to cause
  updates to the AST generator, no UI component updates necessary.
- CST is not inherently serializable, but we can send a pre-parsed AST to be rendered early / in SSR without loading the
  whole parser and ANTLR4 runtime immediately.
- Since we control creation of the AST, we can make logically consistent transformations to it without going through the
  parser again.
- We can make sensible simplifications to the tree, e.g. combining ORDER BY into one terminal node instead of three,
  collapsing inactive notCompoundOperators, etc.

## Support

For developers outside of Atlassian looking for help, or to report issues, [please make a post on the community forum](https://community.developer.atlassian.com/c/atlassian-ecosystem-design).
We will monitor the forums and redirect topics to the appropriate maintainers.

## License
Copyright (c) 2021 - 2022 Atlassian and others. Apache 2.0 licensed, see [LICENSE](LICENSE) file.