@atlassianlabs/jql-ast

JQL AST

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.

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

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

Installation

yarn add @atlassianlabs/jql-ast

Documentation

Refer to docs 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. 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 file.