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
   • Preset
   • 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.
• Reusable presets: Group rule classes into composable presets.
• Automated fixes: Automatically apply fixes to detected violations.
• Extensible helpers: Integrate with external systems like SonarQube or LLMs.

---

Installation

From Playground

To load Moose-Rule-Engine runtime from a Playground:

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

To load everything for development, including tests:

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

Baseline Dependency

To use Moose-Rule-Engine as a dependency:

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

By default this loads only the runtime package. Tests and dev dependencies are opt-in through the tests or dev groups.

---

Usage

MooseRuleEngine takes files and rule classes and returns a collection of fixes. Here is a step-by-step guide to using 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:

ruleEngine setRules: { MyCustomRule }.

4. Add Presets (Optional)

Presets are reusable groups of rule classes. Pass preset classes to the engine:

ruleEngine setPresets: { MyProjectPreset }.

You can also add presets individually and combine them with explicitly selected rule classes:

ruleEngine
  addPreset: MyProjectPreset;
  setRules: { MyAdditionalRule }.

5. 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.

6. Run the Engine

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

fixes := ruleEngine detectAndFix.

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

Preset

A preset is an MRERulePreset subclass that defines a named, reusable group of rule classes. A preset may inherit rules from other presets through parentPresets.

Class {
  #name : 'MyProjectPreset',
  #superclass : 'MRERulePreset',
  #category : 'MyProject-Rules',
  #package : 'MyProject-Rules'
}

MyProjectPreset class >> presetName
  ^ 'my-project'

MyProjectPreset class >> parentPresets
  ^ { MyBasePreset }

MyProjectPreset class >> rules
  ^ {
    MyCustomRule.
    MyAdditionalRule }

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.