Moose-Rule-Engine

Moose-Rule-Engine is a multi-language, rule-based engine designed for code analysis, automated remediation, and large-scale refactoring.

---

Table of Contents

1. Features
2. Installation
   • From Playground
   • Baseline Dependency
3. Usage
4. Core Concepts
   • Rule
   • Helper
     • SonarQube Helper
     • LLM Helper

---

Features

• Multi-language support: Analyze and refactor code across multiple programming languages.
• Rule-based engine: Define custom rules for code analysis and remediation.
• Automated fixes: Automatically apply fixes to detected violations.
• Extensible helpers: Integrate with external systems like SonarQube or LLMs.

---

Installation

From Playground

To load the Moose-Rule-Engine from the Playground, run the following script:

Metacello new
  githubUser: 'Evref-BL' project: 'Moose-Rule-Engine' commitish: 'main' path: 'src';
  baseline: 'MooseRuleEngine';
  onConflict: [ :ex | ex useIncoming ];
  load.

Baseline Dependency

To include Moose-Rule-Engine as a dependency in your project, add the following to your baseline:

spec baseline: 'MooseRuleEngine' with: [
  spec repository: 'github://Evref-BL/Moose-Rule-Engine:main'.
].

---

Usage

MooseRuleEngine take files and rules and return a collection of fixes. Here is a step by step on how to use it

1. Initialize the Rule Engine

Start by creating an instance of the MooseRuleEngine:

ruleEngine := MooseRuleEngine new.

2. Set Up Files

You need to provide the files you want to analyze. Create a file object and add it to the engine:

file := File new path: '<path/to/your/file>'; content: '<file content>'; model: '<model moose of your file>'.

ruleEngine setFiles: { file }.

Optional: Set a Project Model

You can optionally define a model that represents your project, such as a Famix model. This model will be injected into all your rules, providing additional context for analysis and fixes:

ruleEngine setModel: model.

3. Define Rules

Define the rules you want to apply. Rules are objects that analyze files and suggest fixes. Add your rules to the engine:

rule := MyCustomRule new.
ruleEngine setRules: { rule }.

4. Add Helpers (Optional)

Helpers can be used to enhance the functionality of your rules. For example, you can add a SonarQube helper:

sonarqubeApi := SonarQubeApi new host: '<your_sonarqube_host>'; privateToken: '<your_private_token>'.
sonarHelper := MRESonarqubeHelper new 
  sonarqubeApi: sonarqubeApi;
  projectKey: 'your_project_key';
  type: 'all'.

ruleEngine addHelper: sonarHelper.

5. Run the Engine

Run the engine to detect and fix issues in the provided files:

fixes := ruleEngine detectAndFix.

6. Review the Output

The engine returns a collection of fixes. Each fix contains the following attributes:

• startPos: Start position of the fix.
• endPos: End position of the fix.
• content: New content between start and end position
• file: File where the fix is applied.

Core Concepts

Rule

Rules are the core of the Moose-Rule-Engine. A rule has:

• Name: A unique identifier.
• Description: A brief explanation of the rule.

Example Initialization

initialize
  super initialize.
  name := 'name'.
  description := 'description'.

Methods

• analyse: Takes an MREFile and returns a collection of MREViolation.
• fix: Takes an MREViolation and returns a collection of MREFix.

A rule must also specify the file extensions it supports. To help with common languages, MooseRuleEngine provides traits such as TJavaRule for Java files and TTypescriptRule for TypeScript files.

Helper

Helpers are classes injected into rules to assist in writing them. They are useful for interacting with external systems like SonarQube or LLMs.

Creating a Helper

To create a helper, extend MREHelper and define a name.

Accessing a Helper in a Rule

rule getHelper: 'helperName'.

SonarQube Helper

The SonarQube helper allows you to use SonarQube analysis in your rules.

Example Usage

sonarHelper violationsOf: rule inFile: file usingRuleId: sonarRuleId.

Initialization

sonarqubeApi := SonarQubeApi new host: '<your_sonarqube_host>'; privateToken: '<your_private_token>'.

sonarHelper := MRESonarqubeHelper new 
  sonarqubeApi: sonarqubeApi;
  projectKey: 'your_project_key';
  type: 'all'.

LLM Helper

The LLM helper can fix violations using a language model.

Example Usage

llmHelper fix: code withMessage: message.

Initialization

llmApi := LLMAPI chat.
llmApi host: '<llm_host>'.
llmApi apiKey: '<llm_api_key>'.
llmHelper := MRELLMHelper new llmApi: llmApi.