GitLab Query Language

This is the Rust version of GLQL compiler library, originally written in Haskell.

Goals of this library include:

Transpiling GLQL queries, including the YAML frontmatter block to a GraphQL response. Currently, the queries are transpiled using a WASM build of the Haskell version and YAML is transformed on the frontend using JS-YAML.
Transforming the result of a GraphQL call using transformer functions.

Installation

GitLabQueryLanguage 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:

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

Import and use the module:

<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 Example

Clone the repo and install the dev dependencies:

npm install

Build the module:

npm run build

Start the server of your choice. E.g.wds:

npx wds

Development

Ensure you have the following installed:

Rust (version 1.73.0)
Cargo (usually comes with Rust)
Lefthook (for managing git hooks)
Nodejs (for running the GLQL -> GraphQL compiler)

To verify your Rust and Cargo installation, run:

rustc --version
cargo --version

If using VSCode, consider installing the 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:

brew install lefthook

For other platforms or methods to install, see installation docs for Lefthook.

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

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

To run the tests manually, use the following command:

cargo test --verbose

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

Formatting Code

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

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:

cargo fmt

Linting with Clippy

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

cargo clippy -- -D warnings

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

Examples

Build and launch npm/index.html to test the GLQL -> GraphQL compiler:

cargo install wasm-pack
rustup target add wasm32-unknown-unknown
wasm-pack build --target web
cd npm
npm install
npm run build
npx wds

[!tip] Tip

You can switch between legacy issues query and work items query by setting the glqlWorkItems feature flag in index.html to true or false.

Contributing

If you don't already have access, start onboarding by requesting access to the community forks.
Clone the community fork repository.
Create a new feature branch (git checkout -b feature/my-feature).
Commit your changes (git commit -am 'Add new feature').
Push to the branch (git push origin feature/my-feature).
Open an MR.

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.