npm package: @specs-feup/clava-misra
Description: Clava library to automatically detect and correct violations of the MISRA-C:2012 standard in C code
Author: Milena Gouveia
Latest version: 1.0.4

# Clava-MISRA Tool

A Clava-based library to automatically detect and correct parts of C code that violate MISRA-C:2012 coding standard.

For more details, see the [Clava Transpiler repository](https://github.com/specs-feup/clava).

## Installation

To get started, ensure the tool's NPM package is installed in your project:

```bash
npm install @specs-feup/clava-misra
```

## Usage

### 1. Analysis
You can use the tool to detect violations by executing the following statements in your script:

```ts
import MISRATool from "@specs-feup/clava-misra/MISRATool";

MISRATool.checkCompliance();
```
After analysis, each identified violation will be displayed, including its location and description.

### 2. Correction
Besides analysis, the tool can also correct the provided source code to comply with the coding guidelines, using the following statements:

```ts
import MISRATool from "@specs-feup/clava-misra/MISRATool";

MISRATool.correctViolations();
```

After the transformation, any violations that could not be fixed will be displayed along with their justification. The corrected files will be saved in the `woven_code` folder.

You can provide an **optional** JSON config file to assist in correcting specific rules, such as implicit function calls, disallowed functions, and missing return statements. For instance, you can:
-  Define default values for certain types to address functions with missing return statements.
- Specify the path or library for implicit function calls.
- Provide custom implementations for disallowed functions.

The config file should follow this structure:
```json
{
  "defaultValues": {
    "unsigned int": 0,  
    "float": 0.0,
    "enum Status": "SUCCESS",
    "Color": "RED",
    "my_int_type": "0"
  }, 
  "implicitCalls": {
    "printf": "stdio.h",
    "foo": "CxxSources/utils/functions.c"
  },
  "disallowedFunctions": {
    "stdlib.h": {
      "malloc": {
        "replacement": "custom_malloc",
        "location": "utils/custom_stdlib.c"
      },
      "exit": {
        "replacement": "custom_exit",
        "location": "utils/custom_stdlib.c"
      }
    }
  }
}
```
**Note:** Not all fields (`defaultValues`, `implicitCalls`, `disallowedFunctions`) are mandatory. If the config file is not provided or lacks the necessary information to fix a violation, the violation will remain and be displayed as unresolved. 


## Execution

To execute a project that uses this tool, provide the following information:

- The path to your **script file**. 
- The **C standard** to use (`c90`, `c99`, or `c11`).
- The path to the **source code** to process.
- *(Optional)* The full path to a **config file**.
- *(Optional)* The **analysis type**:
  - `system`: For rules whose violation detection requires analyzing multiple files together
  - `single`: For rules whose violation detection is identified within individual translation units independently
  - `all`: For both system and single translation rules (default)

```bash
npx clava classic <scriptFile.js> -pi -std <c90 | c99 | c11> -p <path/to/source/code> [-av "<options>"]
```

**Note:** Some guidelines are tied to a specific C language standard (e.g., c90, c99, c11). Therefore, they will not be detected when running under other standards. For instance, the rule 17.3 (*"A function shall not be declared implicitly"*) only applies to c90 and is not reported when analyzing c99.

### Examples:

Default use (no config file or analysis type):

```bash
npx clava classic dist/main.js -pi -std c99 -p CxxSources/
```
In this case, analysis type is `all` by default.

With analysis type specified:
```bash
npx clava classic dist/main.js -pi -std c99 -p CxxSources/ -av "type=system"
```

Using a config file:
```bash
npx clava classic dist/main.js -pi -std c99 -p CxxSources/ -av "config=misra_config.json"
```

With both analysis and config file specified:
```bash
npx clava classic dist/main.js -pi -std c99 -p CxxSources/ -av "type=system config=misra_config.json"
```

To view other available options, run:

```bash
npx clava classic --help
```