blazelint 0.2.2

// by RuztyCrabs

[!WARNING] This is a University Research Project and SHOULD NOT BE USED ON PRODUCTION ENVIRONMENTS. The goal is to determine the feasibility, performance and developer experience of Rust Programming Language for implementing static code analyzers for Ballerina Language.

Table of Contents

• Documentation
• Installation
• Usage
• Development environment
  • Using GitHub Codespaces
  • Using VS Code
• Building
  • Prerequisites
  • Steps
• Debugging
  • Prerequisites
  • Steps
• Contributing
• TODO
• License

Documentation

• BNF Grammar for Ballerina Subset
• Software Requirement Specification (SRS)
• Pipeline overview

Installation

Install the latest published version from crates.io:

cargo install blazelint

Pre-build binaries are available for Linux from the latest GitHub release.

Windows and MacOS binaries will be added in a later release.

Usage

Analyze a Ballerina source file by passing its path to blazelint:

blazelint path/to/file.bal

[!NOTE] Use the limited subset document in the BNF when defining Ballerina syntax to be linted.

The tool prints the input program, a token stream, the parsed AST, and exits or emits diagnostics if there is any and exits with a non-zero status.

Running from a checked-out repository is also supported:

cargo run -- path/to/file.bal

[!NOTE] cargo run builds and executes an unoptimized build (for debug requirments). Always use cargo build --release for any benchmark or observations on performance.

For a quick smoke test, you can reuse the sample program in tests/test.bal:

blazelint tests/test.bal

Development environment

A pre-configured Dev Container is available that can be used to investigate, develop or debug the program without installing anything on the host machine.

It can be launched and used fully remotely inside a browser using GitHub codespaces, or locally using Visual Studio Code.

Using GitHub Codespaces

1. Click Code → Create codespace from the GitHub UI.
2. Wait for the Codespace to provision (first run will take some significant time).
3. Start Developing!

Using Visual Studio Code

1. Install the Dev Containers extension.
2. Clone this repository and open it in VS Code.
3. Run the Dev Containers: Reopen in Container command.
4. Wait till the container spins up.
5. Start Developing!

The container comes with:

• Rust toolchain
• Typst CLI for building the SRS
• Ballerina runtime
• Extensions for Language Servers, syntax highlighting and debugging support
• Common utilities (zsh, GitHub CLI, git, etc.)

Building

Prerequisites

• Git 2.51.0 or newer
• Rust Toolchain 1.86.0 or newer (Get it here)

Steps

1. Create a fork and clone to local:

   git clone https://github.com/<your-profile-name>/Blazelint.git
   

2. cd into the directory:

   cd Blazelint
   

3. Build with cargo:

   cargo build --release
   

Debugging

Prerequisites

• Build requirements stated here.
• Visual Studio Code IDE by Microsoft
• Rust Analyzer extension by rust-lang.org
• CodeLLDB extension by Vadim Chugunov
• Ballerina toolchain and IDE extension (optional - for testing or writing ballerina codes)

Steps

• You can adjust the tests/test.bal file if you need to debug a specific diagnostic.
• Set breakpoints as needed.
• Click on Run and Debug from the main method or use ctrl+shift+D to jump to debug menu.

[!NOTE] It is possible to debug with any IDE including Neovim, Emacs and etc but we recommend Visual Studio Code for easier setup.

Contributing

• Changes should be developed and push to following branches based on the area of the feature.

  • feature/linter-core: Changes to the linter engine (lexer, parser, semantic analyzer and BNF document).
  • ci/cd: Changes related to continous integration and deployments.
  • docs: Changes related to documentation.

• Run all formatter, lint, and test checks locally before opening a pull request:

  bash scripts/check.sh
  

TODO

Roadmap of the project can be viewed from here.

License

This project is licensed under the MIT License.