npm package: @gitlab/query-language-rust
Description: GLQL transpiler, wrapping the WASM build, written in Rust
Latest version: 0.26.0

# GitLab Query Language

![Latest Release](https://img.shields.io/npm/v/@gitlab/query-language-rust) ![Rust Coverage](https://gitlab.com/gitlab-org/glql/badges/main/coverage.svg?job=coverage) ![Pipeline Status](https://gitlab.com/gitlab-org/glql/badges/main/pipeline.svg)

The compiler is built in Rust[^1] and distributed as two packages:

- **npm / WASM** (`@gitlab/query-language-rust`): Used by GitLab's frontend for client-side query compilation.
- **Ruby gem** (`gitlab_query_language`): Used by GitLab's backend for server-side query processing.

Goals of this library include:

- Transpiling GLQL queries, including the YAML frontmatter block to a GraphQL response.
- Transforming the result of a GraphQL call using transformer functions.

## npm / WASM

`@gitlab/query-language-rust` is an npm module that provides a simple interface for converting `glql`
queries into other formats.

It wraps the WebAssembly build of the `glql` compiler, written in Rust.

### Usage

Install the module:

```sh
npm install --save @gitlab/query-language-rust
```

Import and use the module:

```html
<script type="module">
  import { glql } from '@gitlab/query-language-rust';

  let query = 'label != "backend" and author = currentUser() and weight = 1 and updated > today()';

  let graphql = await glql.compile(query, {
    group: 'gitlab-org',
    username: 'johnhope',
  });

  console.log(graphql);
</script>
```

### Running the Browser Playground

Clone the repo, then install the dev dependencies, build the WASM target, and serve the `npm/` directory:

```sh
npm install
cargo install wasm-pack
rustup target add wasm32-unknown-unknown
wasm-pack build --target web
npx wds -r npm/
```

## Ruby Gem

The same Rust compiler is also available as a Ruby gem, providing native Ruby bindings for server-side use.

### Installation

Add to your Gemfile:

```ruby
gem 'gitlab_query_language'
```

Or install directly:

```bash
gem install gitlab_query_language
```

### Usage

```ruby
require 'gitlab_query_language'

query = 'label != "backend" and author = currentUser() and weight = 1'
result = Glql.compile(query, { group: 'gitlab-org', username: 'johnhope', fields: 'title' })
puts result
```

### Interactive Console (CLI / REPL)

The Ruby gem provides a quick way to test GLQL queries from the command line without needing a browser:

```bash
cd glql_rb
bundle exec rake compile
bundle exec rake console
```

```ruby
irb(main):001> Glql.compile('type = Issue', {group: 'gitlab-org', username: 'johnhope', fields: 'id'})
=>
{"fields" => [{"key" => "id", "label" => "ID", "name" => "id"}],
 "output" => "query GLQL(...) { ... }",
 "success" => true,
 "variables" => { ... }}
```

For full details on the Ruby gem, see [glql_rb/README.md](glql_rb/README.md).

## Development

Install [mise](https://mise.jdx.dev/) (or [asdf](https://asdf-vm.com/)), then run:

```bash
mise install        # installs Rust, Node.js, and Ruby at the versions pinned in .tool-versions
brew install lefthook  # for managing git hooks (see below)
```

If using VSCode, consider installing the [`rust-analyzer`](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension.

### Setting Up Lefthook

Lefthook is used to automate certain checks before pushing code to the repository, such as running tests, ensuring code is formatted, and checking for lint warnings.

To install Lefthook globally on MacOS, run:

```bash
brew install lefthook
```

For other platforms or methods to install, see [installation docs](https://github.com/evilmartians/lefthook/blob/master/docs/install.md) for Lefthook.

Once `lefthook` is installed, enable it in your project by running the following command in the root of your repository:

```bash
lefthook install
```

This command will set up Lefthook to manage git hooks for pre-push checks as defined in the `lefthook.yml` file.

### Pre-push Hooks

The following checks will run automatically before you push your code:

- **Tests**: Ensures all tests pass using `cargo test`.
- **Clippy**: Runs `cargo clippy` to check for lint warnings and ensures no warnings are present.
- **Format**: Ensures code is formatted properly using `cargo fmt --check`.
- **Check**: Runs `cargo check` to verify that the code compiles without errors.

## Running Tests

### Rust Tests

To run the Rust tests manually, use the following command:

```bash
cargo test
```

This will build and run all tests defined in your Rust project.

### WASM Package Tests

To run the WASM package tests, use:

```bash
npm test
```

For continuous integration testing:

```bash
npm run test:ci
```

### Code Coverage

Coverage reports are automatically generated in CI/CD and published to GitLab Pages at:

- Rust coverage: `https://gitlab-org.gitlab.io/glql/coverage/`

### Formatting Code

To ensure your code is properly formatted using `rustfmt`, run:

```bash
cargo fmt -- --check
```

This command checks whether your code adheres to the formatting rules but does not modify any files. To automatically format your code, run:

```bash
cargo fmt
```

### Linting with Clippy

To lint your code and catch common mistakes or inefficiencies, run:

```bash
cargo clippy -- -D warnings
```

This will treat all warnings as errors and prevent the code from building if any warnings are found.

### End-to-End Testing

When making changes to the GLQL Rust codebase, you can follow these steps to test your modifications end-to-end in [GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit):

**In glql-rust directory:**

1. Build the Rust code to WASM `wasm-pack build --target web --out-dir pkg`
2. Build the npm package `npm run build`
3. Copy the full path to the build `echo "$(pwd)/npm/dist/main.js"`

**In Gitlab GDK directory:**

Update the import paths in both `app/assets/javascripts/glql/core/parser.js` and `app/assets/javascripts/glql/core/transformer.js`:

```js
// change from
import { glql } from '@gitlab/query-language-rust';

// to
import { glql } from 'file:///path/from/step/3/above';
```

Now you can test your changes in any markdown field embedding there your GLQL query, for example:

````markdown
```glql
display: table
fields: title, labels, author
query: group = "gitlab-org" and label = "group::knowlegde" and user = currentUser()
```
````

**Note:** Every time you make a change in `glql-rust`, you must rebuild both the WASM and npm packages for the changes to take effect.

## Contributing

1. If you don't already have access, start onboarding by [requesting access to the community forks](https://gitlab.com/gitlab-community/meta#request-access-to-community-forks).
1. Clone the [community fork repository](https://gitlab.com/gitlab-community/gitlab-org/glql).
1. Create a new feature branch (`git checkout -b feature/my-feature`).
1. Commit your changes (`git commit -am 'Add new feature'`).
1. Push to the branch (`git push origin feature/my-feature`).
1. Open an MR.

### Toolchain version sync

Runtime versions are pinned in three places that must stay in sync:

| File                           | What it controls                                              |
| ------------------------------ | ------------------------------------------------------------- |
| `.tool-versions`               | Local dev environment (mise / asdf)                           |
| `.gitlab-ci.yml`               | CI pipeline images and variables (`RUST_VERSION`, image tags) |
| `.gitlab/duo/agent-config.yml` | Duo Developer agent environment                               |

When bumping a Rust, Node.js, or Ruby version, update all three files.

## Release process

> [!important] Pre-requisites
> You need Developer permissions in the project.

On the `main` branch, run any of the below pipeline jobs to create a
release:

- `release-patch`: Bump patch version and publish to NPM.
- `release-minor`: Bump minor version and publish to NPM.
- `release-major`: Bump major version and publish to NPM.

The release-\* job will additionally create a release MR to also bump the Ruby gem version and dependency. This currently requires manual approval to trigger the gem release.

See the gem [glql_rb/README.md](glql_rb/README.md) for more details on the release process.

## Additional Reading

### Learning Rust

- [The Rust book](https://doc.rust-lang.org/book/)
- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)

## Learning more about GLQL

- [Architecture Design Document](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/glql/)
- [User facing docs](https://docs.gitlab.com/ee/user/glql/)

[^1]: Originally written in [Haskell](https://gitlab.com/gitlab-org/gitlab-query-language/glql-haskell).