GLQL transpiler, wrapping the WASM build, written in Rust
!Latest Release !Rust Coverage !TypeScript Coverage !Pipeline Status
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.
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.
Install the module:
``sh`
npm install --save @gitlab/query-language-rust
Import and use the module:
`html`
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/
> [!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.
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:
`bash`
rustc --version
cargo --version
If using VSCode, consider installing the rust-analyzer extension.
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 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.
The following checks will run automatically before you push your code:
- Tests: Ensures all tests pass using cargo test.cargo clippy
- Clippy: Runs to check for lint warnings and ensures no warnings are present.cargo fmt --check
- Format: Ensures code is formatted properly using .cargo check
- Check: Runs to verify that the code compiles without errors.
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.
To run the TypeScript tests, use:
`bash`
npm test
For continuous integration testing:
`bash`
npm run test:ci
Coverage reports are automatically generated in CI/CD and published to GitLab Pages at:
- Rust coverage: https://gitlab-org.gitlab.io/glql/coverage/https://gitlab-org.gitlab.io/glql/coverage-ts/
- TypeScript coverage:
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
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.
When making changes to the GLQL Rust codebase, you can follow these steps to test your modifications end-to-end in GitLab GDK:
In glql-rust directory:
1. Build the Rust code to WASM wasm-pack build --target web --out-dir pkgnpm run build
2. Build the npm package echo "$(pwd)/npm/dist/main.js"
3. Copy the full path to the build
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.
1. If you don't already have access, start onboarding by requesting access to the community forks.
1. Clone the community fork repository.
1. Create a new feature branch (git checkout -b feature/my-feature).git commit -am 'Add new feature'
1. Commit your changes ().git push origin feature/my-feature
1. Push to the branch ().
1. Open an MR.
> [!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 for more details on the release process.
- The Rust book
- Rust by Example