repolinter/docs/development.md

Lint open source repositories

# Development

Repolinter is broken down into 7 main components, each of which is contained in a subfolder:

- **Axioms** - located under [axioms](../axioms)
- **CLI** - located under [bin](../bin)
- **Rules** - located under [rules](../rules)
- **Fixes** - located under [fixes](../fixes)
- **Formatters** - located under [formatters](../formatters)
- **Utilities** - located under [lib](../lib)
- **Built-In Rulesets and Schema** - located under [rulesets](../rulesets)

## Axioms

Axioms are registered in [axioms/axioms.js](../axioms/axioms.js) and in [rulesets/schema.json](../rulesets/schema.json). An axiom implementation consists of a module with the following interface:

```TypeScript
async (fs: FileSystem) => Result
```

Where fs is a [`FileSystem`](../lib/file_system.js) scoped to the current repository.

The contents of the result should be an array of targets where `t.path` is a target that the axiom has determined is valid (ex. for language detecting axiom a possible result could be `new Result('', [{ path: 'javascript' passed: true }, { path: 'typescript', passed: true}], true)`). If the axiom fails to execute, it should return a failing result with an error message included instead of throwing an error.

## Rules

A rule consists of two parts: a JavaScript module, which determines the rule's functionality and a JSON schema, which validates the rule's configuration options in rulesets. Rules are registered in [rules/rules.js](../rules/rules.js) and [rulesets/schema.json](../rulesets/schema.json). Rules are also documented under [rules.md](./rules.md).

### Rule Configuration JSON Schema

The configuration JSON schema determines how `rule.options` should be validated for this rule. All [JSON Schema](https://json-schema.org/) tools supported by [AJV](https://ajv.js.org/) all available, with a few important caveats:

- The file itself should always be named `<rule-name>-config.json` and be located under the `rules` folder.
- The top-level type should always be `object`.
- The `$id` field should be an absolute raw.githubusercontent.com URL to where the schema is hosted on GitHub (ex. https://raw.githubusercontent.com/todogroup/repolinter/master/rules/apache-notice-config.json). This allows IDEs such as VSCode to apply the schema via a URL.

To get started, you can use the following template:

```JSON
{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "https://raw.githubusercontent.com/todogroup/repolinter/master/rules/<rule-name>-config.json",
    "type": "object",
    "properties": {}
}
```

Due to limitations with JSON Schema, you also must register your rule configuration schema in [rulesets/schema.json](../rulesets/schema.json) by adding the following item to the list under `root.then.properties.rules.properties.rule.allOf`:

```JSON
{ "if": { "properties": { "type": { "const": "<rule-name>" } } }, "then": { "properties": { "options": { "$ref": "../rules/<rule-name>-config.json" } } } }
```

### JavaScript Implementation

A rule implementation consists of a module with the following interface:

```TypeScript
async (fs: FileSystem, opts /* type determined by your JSON schema */) => Result
```

Where fs is a [`FileSystem`](../lib/file_system.js) scoped to the current repository and `opts` is the options provided by the ruleset.

A rule implementation is encouraged to use `Result#targets` to show the individual files/patterns checked when processing the rule. Including filenames in `Result#message` is discouraged as it makes formatting difficult. If a rule fails to execute, it should throw an error.

## Fixes

A fix, similar to a rule, consists of two parts: a JavaScript module, which determines the fix's functionality and a JSON schema, which validates the fix's configuration options in rulesets. Fixes are registered in [fixes/fixes.js](../fixes/fixes.js) and [rulesets/schema.json](../rulesets/schema.json). Fixes are also documented under [fixes.md](./fixes.md).

### Fix Configuration JSON Schema

Fix JSON schemas work identically to [rule JSON schemas](#rule-configuration-json-schema), with the only difference the respective names and paths.

To get started, you can use the following template:

```JSON
{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "https://raw.githubusercontent.com/todogroup/repolinter/master/fixes/<fix-name>-config.json",
    "type": "object",
    "properties": {}
}
```

Similar as with rules, you must register the fix schema in [rulesets/schema.json](../rulesets/schema.json) by adding the following item to the list under `root.then.properties.rules.properties.fix.allOf` (note that this is a different list than the rule registration list):

```JSON
{ "if": { "properties": { "type": { "const": "<fix-name>" } } }, "then": { "properties": { "options": { "$ref": "../rules/<fix-name>-config.json" } } } }
```

### JavaScript Implementation

Unlike rules, a fix implementation consists of a module with the following interface:

```TypeScript
async (fs: FileSystem, options /* Type determined by your JSON schema */, targets: string[], dryRun: boolean) => Result
```

Where fs is a [`FileSystem`](../lib/file_system.js) scoped to the current repository, `opts` is the options provided by the ruleset, `targets` are filepaths which did not pass the rule associated with this fix, and `dryRun` determines if the fix is allowed to make changes to the repository.

The fix implementation is encouraged to use `Result#targets` to show the individual files/patterns changed. If the fix fails to execute, it should either return a failed result or throw an error.

## Formatters

Formatters are exported by [index.js](../index.js) and manually called by the [CLI](../bin/repolinter.js). A formatter implementation consists of the following interface:

```TypeScript
interface Formatter {
  formatOutput(output: LintResult, dryRun: boolean): string
}
```

Formatters do not print to `STDOUT` instead choosing to return the output as a string.

If needed, a formatter can accept extra configuration from the ruleset through the `formatOptions` property, which will be directly passed through to `LintResult#formatOptions`. These options are not typed and are formatter dependent.