@atlassianlabs/jql-parser

We have been looking for options to parse JQL outside of Jira and without calling the Jira API. As a result, we came across the following package:

Can anyone from @atlassian comment if this is an officially supported package that we can rely on? The README and documentation on that package are very limited and do not make statements on the project status or intended use. Any insights on this would be helpful.

PS. I am making this post in the Ecosystem Design Announcements category as requested at the end of the README. Seems strange though.

2 Likes

@tbinna,

I’m somewhat of a “language geek” so I was pretty excited a couple years ago when some of the Jira dev team created a formal grammar of JQL in ANTLR4. However, a grammar is a bit of a tricky case. While we do rely on the underlying g file (the grammar), the rest is code generation provided by ANTLR4. Also it isn’t the “authoritative” grammar, which lives with the Jira source code so there is a risk grammar changes would not propagate and rebuild the public Javascript library. Most of all, it is labeled “Atlassian Labs”, where the language is:

Atlassian Labs holds unsupported apps and personal projects by Atlassian developers. Although you may find unique and highly useful functionality in the Atlassian Labs apps, Atlassian takes no responsibility for your use of these apps. The apps are often developed in conjunction with Atlassian hack-a-thons and ShipIt days and are provided to you completely “as-is”, with all bugs and errors, and are not supported by Atlassian. Our bug-fix policy page - Security Bugfix Policy | Atlassian - describes how and when we resolve security bugs in our products, including apps listed here. Unless licensed otherwise by Atlassian, the Atlassian Labs apps are subject to Section 14 of the Cloud Terms of Service – Cloud Terms of Service | Atlassian – or Section 8 of the Software License Agreement – Software License Agreement | Atlassian, as applicable, and are “No-Charge Products” as defined therein.

2 Likes

Thanks, Ian! That is all the information I was looking for :+1:

@ibuchanan is correct here. To provide some additional context this parser is used internally in Jira for our client side parsing of JQL, and was released to the public as part of a series of packages to improve the ecosystem developer experience with JQL (see Advanced search just got easier for Atlassian app developers - Atlassian Developer Blog).

While it is published under the @atlassianlabs scope it is a package we still rely on heavily within Jira and are continuing to support. You may also be interested in the @atlassianlabs/jql-ast - npm package which is a higher level abstraction of the parsed JQL and is a good fit for many use cases that need to traverse the query.

1 Like

Hey @Kyle thanks for providing additional context - that’s really helpful. If this is something that teams within Atlassian are maintaining it’s a shame this is not advertised in the developer docs.

May I suggest putting the statement below from your blog into the package README? Or, alternatively link the blog in the README. This would have helped us understand the current state of the package.

These packages are currently in the initial development phase published to the @atlassianlabs scope. Once we’ve had an opportunity to review ecosystem feedback and adoption we will look to make final revisions to the API and promote a release to the @atlassian scope.

2 Likes

Hi,

Currently, it looks like jql-editor family of libraries was released to public and then forgotten about by Atlassian.

It was released and never updated after that, UI components have the dependency on styled-components v3, which is not used in AtlasKit core libraries anymore and has several vulnerabilities in its dependency tree.

Are you able to share any kind of plans for these libraries, so we can decide whether we should use them, or they will never be updated anymore?