Repolinter

https://todogroup.github.io/repolinter
Admin
Repolinter is a customizable tool that lints open source repositories against configurable rulesets...
Tokens:15,924
Snippets:113
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Repolinter with npm

Source: https://todogroup.github.io/repolinter

Install Repolinter globally using npm. Requires Node.js >= v10.

```bash
npm install -g repolinter
```

--------------------------------

### defaultFormatter output example

Source: https://todogroup.github.io/repolinter

Example output from the defaultFormatter, showing the CLI-style LintResult with checkmarks and status messages for each rule.

```text
✔ license-file-exists: found (LICENSE)
✔ readme-file-exists: found (README.md)
✔ contributing-file-exists: found (CONTRIBUTING)
✔ code-of-conduct-file-exists: found (CODE-OF-CONDUCT)
✔ changelog-file-exists: found (CHANGELOG)
✔ readme-references-license: File README.md contains license
✔ license-detectable-by-licensee: Licensee identified the license for project: Apache License 2.0
✔ test-directory-exists: found (tests)
✔ integrates-with-ci: found (.travis.yml)
✔ source-license-headers-exist: The first 5 lines of 'index.js' contain all of the requested patterns.
...
✔ github-issue-template-exists: found (ISSUE_TEMPLATE)
✔ github-pull-request-template-exists: found (PULL_REQUEST_TEMPLATE)
✔ package-metadata-exists: found (Gemfile)
✔ package-metadata-exists: found (package.json)
```

--------------------------------

### Example Output of repolinter lint

Source: https://todogroup.github.io/repolinter

Example output from running repolinter lint on a directory, showing successful checks and exit code 0.

```bash
repolinter % repolinter lint .
Target directory: <directory>
Lint:
✔ license-file-exists: Found file (LICENSE)
✔ readme-file-exists: Found file (README.md)
✔ contributing-file-exists: Found file (CONTRIBUTING)
✔ code-of-conduct-file-exists: Found file (CODE-OF-CONDUCT)
✔ changelog-file-exists: Found file (CHANGELOG)
...
repolinter % echo $?
0
```

--------------------------------

### Numerical axiom comparisons (contributor-count)

Source: https://todogroup.github.io/repolinter

Example using a numerical axiom (`contributor-count`) with numerical comparisons in the `where` conditional. Note that numerical comparisons on non-numerical axioms always fail.

```json
{
  "axioms": {
    "contributor-count": "contributors"
  },
  "rules": {
    "my-rule": {
      "where": ["contributors>6", "contributors<200"],
      // ...
    }
  }
}
```

```yaml
axioms:
  contributor-count: contributors
rules:
  my-rule:
    where:
    - contributors>6
    - contributors<200
    rule:
      ...
```

--------------------------------

### markdownFormatter output example

Source: https://todogroup.github.io/repolinter

Example output from the markdownFormatter, showing a markdown document with a summary table of lint results.

```markdown
# Repolinter Report

This Repolinter run generated the following results:
| ❗  Error | ❌  Fail | ⚠️  Warn | ✅  Pass | Ignored | Total |
|---|---|---|---|---|---|
| 0 | 0 | 0 | 15 | 10 | 25 |
...
```

--------------------------------

### Configure licensee axiom

Source: https://todogroup.github.io/repolinter

Configure the licensee axiom to detect the repository license and use a license identifier in a rule's where clause. Requires licensee installed in PATH or Repolinter's directory.

```json
{
  "axioms": {
    "licensee": "license"
  },
  "rules": {
    "my-rule": {
      "where": ["license=Apache-2.0"],
      // ...
    }
  }
}
```

--------------------------------

### Axiom usage in ruleset (packagers)

Source: https://todogroup.github.io/repolinter

Example ruleset configuration using an axiom to detect the packaging system. The `where` conditional uses the axiom target `package-type` with a string comparison.

```json
{
  "$schema": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/schema.json",
  "version": 2,
  "axioms": {
    "packagers": "package-type"
  },
  "rules": {
    "this-only-runs-if-npm": {
      "level": "error",
      "where": ["package-type=npm"],
      "rule": { /* ... */ }
    }
  }
}
```

```yaml
version: 2
axioms:
  packagers: package-type
rules:
  this-only-runs-if-npm:
    level: error
    where: [package-type=npm]
    rule:
      ...
```

--------------------------------

### Format output as JSON with --format json

Source: https://todogroup.github.io/repolinter

Use the --format flag with 'json' to output results in JSON format. The example shows the command and a truncated JSON response.

```bash
repolinter % repolinter lint --format json .
{"params":{"targetDir":"/Users/nkoontz/Documents/code/repolinter","filterPaths":[],...
```

--------------------------------

### Format output as Markdown with --format markdown

Source: https://todogroup.github.io/repolinter

Use the --format flag with 'markdown' to output results in Markdown format. The example shows the command and a truncated Markdown report.

```bash
repolinter % repolinter lint --format markdown .
# Repolinter Report

This Repolinter run generated the following results:
| ❗  Error | ❌  Fail | ⚠️  Warn | ✅  Pass | Ignored | Total |
|---|---|---|---|---|---|
| 0 | 0 | 0 | 15 | 10 | 25 |
...
```

--------------------------------

### Configure linguist axiom

Source: https://todogroup.github.io/repolinter

Configure the linguist axiom to detect programming languages and use a language value in a rule's where clause. Requires linguist installed in PATH or Repolinter's directory.

```json
{
  "axioms": {
    "linguist":" language"
  },
  "rules": {
    "my-rule": {
      "where": ["language=javascript"],
      // ...
    }
  }
}
```

--------------------------------

### Fix Configuration JSON Schema Template

Source: https://todogroup.github.io/repolinter

Template for a fix configuration JSON schema. Use this as a starting point when creating a new fix. The $id should be updated to point to the actual fix configuration file.

```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": {}
}
```

--------------------------------

### FileSystem Class

Source: https://todogroup.github.io/repolinter

Documentation for the FileSystem class and its methods, including constructor, static and instance methods for file operations.

```APIDOC
## new FileSystem(targetDir, filterPaths)

### Description
Utility filesystem class that scopes operations to a given set of directories and a CWD.

### Constructor
`new FileSystem(targetDir: any, filterPaths: any)`

### Parameters
- **targetDir** (any) - Default `'.'` - The target directory.
- **filterPaths** (any) - Default `[]` - Paths to filter.

```

```APIDOC
## FileSystem.fileExists(file)

### Description
Asynchronously checks if a file exists using fs.access.

### Method
`fileExists(file: string): Promise<boolean>`

### Parameters
- **file** (string) - An absolute path to verify the existence of.

### Returns
`Promise<boolean>` - Whether or not the path exists.

```

```APIDOC
## FileSystem.relativeFileExists(file)

### Description
Asynchronously checks if a file exists using fs.access.

### Method
`relativeFileExists(file: string): Promise<boolean>`

### Parameters
- **file** (string) - A path relative to targetDir to check the existence of.

### Returns
`Promise<boolean>` - Whether or not the path exists.

```

```APIDOC
## FileSystem.findFirst(globs, nocase)

### Description
Find the first file or directory matching a list of globs. Globs are searched from first to last. Returns the relative path of that file or directory, or undefined if none was found.

### Method
`findFirst(globs: (string | Array<string>), nocase: boolean): Promise<(undefined | string)>`

### Parameters
- **globs** ((string | Array<string>)) - The globs to search with.
- **nocase** (boolean) - Whether or not to ignore case-sensitivity.

### Returns
`Promise<(undefined | string)>` - A path relative to this.targetDir, or undefined if no items were found.

```

```APIDOC
## FileSystem.findFirstFile(globs, nocase)

### Description
Find the first file matching a list of globs. Globs are searched from first to last. Returns the relative path of that file, or undefined if none was found.

### Method
`findFirstFile(globs: (string | Array<string>), nocase: boolean): Promise<(undefined | string)>`

### Parameters
- **globs** ((string | Array<string>)) - The globs to search with.
- **nocase** (boolean) - Whether or not to ignore case-sensitivity.

### Returns
`Promise<(undefined | string)>` - A path relative to this.targetDir, or undefined if no items were found.

```

```APIDOC
## FileSystem.findAllFiles(globs, nocase)

### Description
Find all files matching a list of globs. Globs are searched from first to last. Returns the relative path of all files, or undefined if none was found. Automatically removes symlinks from results.

### Method
`findAllFiles(globs: (string | Array<string>), nocase: boolean): Promise<Array<string>>`

### Parameters
- **globs** ((string | Array<string>)) - The globs to search with.
- **nocase** (boolean) - Whether or not to ignore case-sensitivity.

### Returns
`Promise<Array<string>>` - A list of paths relative to this.targetDir.

```

```APIDOC
## FileSystem.findAll(globs, nocase = false)

### Description
Find all files or directories matching a list of globs. Globs are searched from first to last. Returns the relative path of all items, or undefined if none was found. Automatically removes symlinks from results.

### Method
`findAll(globs: (string | Array<string>), nocase: boolean?): Promise<Array<string>>`

### Parameters
- **globs** ((string | Array<string>)) - The globs to search with.
- **nocase** (boolean?) - Default `false` - Whether or not to ignore case-sensitivity.

### Returns
`Promise<Array<string>>` - A list of paths relative to this.targetDir.

```

```APIDOC
## FileSystem.getFileContents(relativeFile)

### Description
Get the contents of a file in utf8 given a relative path.

### Method
`getFileContents(relativeFile: string): Promise<(string | undefined)>`

### Parameters
- **relativeFile** (string) - A path relative to this.targetDir.

### Returns
`Promise<(string | undefined)>` - A string with the file contents, or undefined if the file is not found.

```

```APIDOC
## FileSystem.setFileContents(relativeFile, contents)

### Description
Set the contents of a file in utf8 given a relative path and contents.

### Method
`setFileContents(relativeFile: string, contents: string): Promise<void>`

### Parameters
- **relativeFile** (string) - A path relative to this.targetDir.
- **contents** (string) - A string with the file contents.

### Returns
`Promise<void>`

```

```APIDOC
## FileSystem.removeFile(relativeFile)

### Description
Remove the file at the specified path.

### Method
`removeFile(relativeFile: string): Promise<void>`

### Parameters
- **relativeFile** (string) - A path relative to this.targetDir.

### Returns
`Promise<void>`

```

--------------------------------

### apache-notice rule equivalent configuration

Source: https://todogroup.github.io/repolinter

Equivalent configuration for the apache-notice rule, which checks for a NOTICE file in the repository root.

```json
{
  "type": "file-existence",
  "options": {"globsAny": ["NOTICE*"]}
}
```

--------------------------------

### Configure contributor-count axiom

Source: https://todogroup.github.io/repolinter

Configure the contributor-count axiom to count contributors via gitlog and use numerical comparisons in a rule's where clause.

```json
{
  "axioms": {
    "contributor-count": "contributors"
  },
  "rules": {
    "my-rule": {
      "where": ["contributors>6", "contributors<200"],
      // ...
    }
  }
}
```

--------------------------------

### lint(targetDir, filterPaths, ruleset, dryRun)

Source: https://todogroup.github.io/repolinter

Runs the repolinter engine on a specified directory, with optional filter paths, custom ruleset, and dry-run mode.

```APIDOC
## lint(targetDir, filterPaths, ruleset, dryRun)

### Description
An exposed function for the repolinter engine. Use this function to run repolinter on a specified directory targetDir. You can also optionally specify which paths to allowlist (filterPaths), whether or not to actually commit modifications (fixes), and a custom ruleset object to use. This function will not throw an error on failure, instead indicating that an error has occurred in returned value.

### Method
lint

### Parameters
- **targetDir** (string) - Required - The directory of the repository to lint.
- **filterPaths** (Array<string>?) - Optional - A list of directories to allow linting of, or [] for all. Default: `[]`.
- **ruleset** ((Object | string | null)?) - Optional - A custom ruleset object with the same structure as the JSON ruleset configs, or a string path to a JSON config. Set to null for repolinter to automatically find it in the repository. Default: `null`.
- **dryRun** (boolean?) - Optional - If true, repolinter will report suggested fixes, but will make no disk modifications. Default: `false`.

### Returns
`Promise<LintResult>`: An object representing the output of the linter.
```

--------------------------------

### runRuleset(ruleset, targets, fileSystem, dryRun)

Source: https://todogroup.github.io/repolinter

Executes all operations in a ruleset, including linting and fixing, and returns the results.

```APIDOC
## runRuleset(ruleset, targets, fileSystem, dryRun)

### Description
Run all operations in a ruleset, including linting and fixing. Returns a list of objects with the output of the linter rules.

### Method
runRuleset

### Parameters
- **ruleset** (Array<RuleInfo>) - Required - A ruleset (list of rules with information about each). This parameter can be generated from a config using parseConfig.
- **targets** ((Object<string, Result> | boolean)) - Required - The axiom targets to enable for this run of the ruleset. Structure is from the output of determineTargets. Use true for all targets.
- **fileSystem** (FileSystem) - Required - A filesystem object configured with filter paths and a target directory.
- **dryRun** (boolean) - Required - If true, repolinter will report suggested fixes, but will make no disk modifications.

### Returns
`Promise<Array<FormatResult>>`: Objects indicating the result of the linter rules.
```

--------------------------------

### Limit paths with --allowPaths

Source: https://todogroup.github.io/repolinter

Use the --allowPaths option to specify an allowed list of paths, preventing accidental linting of build artifacts. Paths must be contained in the target directory/repository.

```bash
repolinter lint --allowPaths ./a/path --allowPaths /another/path
```

--------------------------------

### Formatter

Source: https://todogroup.github.io/repolinter

Documentation for the Formatter object and its formatOutput property.

```APIDOC
## Formatter

### Description
Object containing a function to format the entire linter output.

### Properties
- **formatOutput** (function (LintResult, boolean): string) - A function to format the entire linter output.

```

--------------------------------

### Minimal README existence rule (JSON and YAML)

Source: https://todogroup.github.io/repolinter

Minimal rule that checks for the existence of a README file using the file-existence check with globsAny set to README*. Shown in JSON and YAML.

```json
"readme-file-exists" : {
  "level": "error",
  "rule": {
    "type": "file-existence",
    "options": {
      "globsAny": ["README*"]
    }
  }
}
```

```yaml
readme-file-exists:
  level: error
  rule:
    type: file-existence
    options:
      globsAny:
      - README*
```

--------------------------------

### Register Rule Configuration Schema in rulesets/schema.json

Source: https://todogroup.github.io/repolinter

Item to add to the `root.then.properties.rules.properties.rule.allOf` list in `rulesets/schema.json` to register the rule configuration schema. This is required due to limitations with JSON Schema.

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

--------------------------------

### Lint a Local Repository with repolinter lint

Source: https://todogroup.github.io/repolinter

Lint a local repository directory with Repolinter. Uses the local repolinter.json ruleset or the default ruleset if none is found.

```bash
repolinter lint <directory>
```

--------------------------------

### Invoke repolinter with URL ruleset

Source: https://todogroup.github.io/repolinter

Invokes repolinter with a URL-based ruleset. Relative paths in `extends` are resolved relative to the original URL.

```bash
repolinter -u http://example.com/custom-rules.yaml
```

--------------------------------

### README hash check with fix (JSON and YAML)

Source: https://todogroup.github.io/repolinter

Rule that checks the README against a SHA256 hash and replaces it if the check fails. Uses the file-hash check and the file-create fix with replace: true and a text URL. Includes policyInfo and policyUrl.

```json
"readme-file-up-to-date" : {
  "level": "error",
  "rule": {
    "type": "file-hash",
    "options": {
      "globsAny": ["README*"],
      "algorithm": "sha256",
      "hash": "..."
    }
  },
  "fix": {
    "type": "file-create",
    "options": {
      "file": "README.md",
      "replace": true,
      "text": { "url": "www.example.com/mytext.txt" }
    }
  },
  "policyInfo": "Gotta keep that readme up to date",
  "policyUrl": "www.example.com/mycompany"
}
```

```yaml
readme-file-up-to-date:
  level: error
  rule:
    type: file-hash
    options:
      globsAny:
      - README*
      algorithm: sha256
      hash: "..."
  fix:
    type: file-create
    options:
      file: README.md
      replace: true
      text:
        url: www.example.com/mytext.txt
  policyInfo: Gotta keep that readme up to date
  policyUrl: www.example.com/mycompany
```

--------------------------------

### Invoke repolinter with file ruleset

Source: https://todogroup.github.io/repolinter

Invokes repolinter with a file-based ruleset. Relative paths in `extends` are resolved relative to the original file path.

```bash
repolinter -r /etc/repolinter/custom-rules.yaml
```

--------------------------------

### Axioms configuration syntax

Source: https://todogroup.github.io/repolinter

Defines the axioms configuration object in JSON and YAML formats. Each axiom is a key-value pair where the key is the axiom ID and the value is the target used in the `where` conditional.

```json
"axioms": {
  "<axiom-id>": "<axiom-target>"
}
```

```yaml
axioms:
  <axiom-id>: axiom-target
```

--------------------------------

### Rule Configuration JSON Schema Template

Source: https://todogroup.github.io/repolinter

Template for a rule configuration JSON schema. The file must be named `<rule-name>-config.json` and placed under the `rules` folder. The top-level type must be `object` and the `$id` field must be an absolute raw.githubusercontent.com URL to the hosted schema.

```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": {}
}
```

--------------------------------

### Lint a remote git repository with --git flag

Source: https://todogroup.github.io/repolinter

Use the --git flag to lint a remote repository. The directory input is interpreted as a git URL and Repolinter automatically clones it into a temporary directory.

```bash
repolinter lint -g https://github.com/todogroup/repolinter.git
```

--------------------------------

### Rule Implementation Interface

Source: https://todogroup.github.io/repolinter

Interface for a rule implementation module. `fs` is a `FileSystem` scoped to the current repository and `opts` is the options provided by the ruleset. Use `Result#targets` to show individual files/patterns checked; avoid filenames in `Result#message`. Throw an error if the rule fails to execute.

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

--------------------------------

### Extending a ruleset with extends

Source: https://todogroup.github.io/repolinter

Extends a ruleset by including an `extends` top-level key with a URL or file path. The two files are recursively merged, and extended rulesets can be up to 20 levels deep.

```json
{
  "extends": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json"
  "rules": {
    # disable CI check
    "integrates-with-ci": {
      "level": "off"
    }
  }
}
```

```yaml
extends: https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json
rules:
  # disable CI check
  integrates-with-ci
    level: off
    ...
```

--------------------------------

### determineTargets(axiomconfig, fs)

Source: https://todogroup.github.io/repolinter

Determines the appropriate targets to run against based on an axiom configuration.

```APIDOC
## determineTargets(axiomconfig, fs)

### Description
Given an axiom configuration, determine the appropriate targets to run against (e.g. "target=javascript").

### Method
determineTargets

### Parameters
- **axiomconfig** (type not specified) - Required - The axiom configuration.
- **fs** (type not specified) - Required - The filesystem object.

### Returns
Not specified in the source.
```

--------------------------------

### Lint a repository with the Repolinter JavaScript API

Source: https://todogroup.github.io/repolinter

Use the Repolinter JavaScript API to lint a repository. The lint function returns a promise that resolves to a result object. This API gives developers complete control over configuration and formatting.

```javascript
const repolinter = require('repolinter')
const result = await repolinter.lint('.')
```

--------------------------------

### Formatter interface

Source: https://todogroup.github.io/repolinter

Defines the contract for a Repolinter formatter. Implementations must return the formatted output as a string instead of printing to STDOUT.

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

--------------------------------

### Axiom implementation interface

Source: https://todogroup.github.io/repolinter

Interface for an axiom implementation. The function receives a FileSystem scoped to the current repository and returns a Result. The result should contain an array of targets where t.path is a valid target. On failure, return a failing result with an error message instead of throwing.

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

--------------------------------

### Fix Schema Registration in rulesets/schema.json

Source: https://todogroup.github.io/repolinter

Register the fix schema in rulesets/schema.json by adding this item to the list under root.then.properties.rules.properties.fix.allOf. Note 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" } } } }
```

--------------------------------

### Repolinter ruleset base (JSON and YAML)

Source: https://todogroup.github.io/repolinter

Base structure for a Repolinter ruleset in JSON and YAML. The JSON version includes the $schema field for validation; the YAML version omits it. Use version 2 unless you have a legacy configuration.

```json
{
  "$schema": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/schema.json",
  "version": 2,
  "axioms": {},
  "rules": {}
}
```

```yaml
version: 2
axioms: {}
rules:
```

--------------------------------

### MarkdownFormatter and slug API

Source: https://todogroup.github.io/repolinter

Code snippets for the MarkdownFormatter class methods and the slug function.

```APIDOC
## MarkdownFormatter.formatResult(result, symbol, dryRun?)

### Description
Formats a FormatResult object into a line of human-readable text.

### Method
formatResult

### Signature
formatResult(result: FormatResult, symbol: string, dryRun?: boolean): string

### Parameters
- **result** (FormatResult) - Required - The result to format, must be valid.
- **symbol** (string) - Required - The symbol to use at the start of the log line (ex. ✅).
- **dryRun** (boolean?) - Optional - Whether or not to say the fix is "suggested" instead of "applied".

### Returns
- **string** - The formatted string.
```

```APIDOC
## MarkdownFormatter.formatOutput(output, dryRun?)

### Description
Formats a LintResult object into a human-readable output.

### Method
formatOutput

### Signature
formatOutput(output: LintResult, dryRun?: boolean): string

### Parameters
- **output** (LintResult) - Required - The linter output to format.
- **dryRun** (boolean?) - Optional - Whether or not to print fix "suggested" or "applied".

### Returns
- **string** - The formatted output.
```

```APIDOC
## slug(string)

### Description
Parses a unicode string into a markdown anchor link using a GitHub-flavored algorithm.

### Method
slug

### Signature
slug(string: string): string

### Parameters
- **string** (string) - Required - The heading to parse.

### Returns
- **string** - The slug to use in URLs.
```

--------------------------------

### Fix Implementation Interface

Source: https://todogroup.github.io/repolinter

Interface for a fix implementation. The function receives a FileSystem scoped to the current repository, options from the ruleset, target filepaths that failed the associated rule, and a dryRun flag. It should return a Result, using Result#targets to show changed files, or throw an error on failure.

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

--------------------------------

### shouldRuleRun(validTargets, ruleAxioms)

Source: https://todogroup.github.io/repolinter

Determines whether a rule should run based on its axioms and a list of valid targets.

```APIDOC
## shouldRuleRun(validTargets, ruleAxioms)

### Description
Checks a rule's list of axioms against a list of valid targets, and determines if the rule should run or not based on the following rules criteria: the rule's list has a direct match on a target OR the rule specifies a numerical axiom (ex. >) and the target list contains a target that matches that axiom. Supported numerical axioms are >, <, >=, <=, and = Only.

### Method
shouldRuleRun

### Parameters
- **validTargets** (Array<string>) - Required - The axiom target list in "target=thing" format, including the wildcard entry ("target=_"). For numerical targets it is assumed that only one entry and the wildcard are present (e.g. ["target=2", "target=3", "target=_ "] is invalid).
- **ruleAxioms** (Array<string>) - Required - The rule "where" specification to validate against.

### Returns
`Array<string>`: The list of unsatisfied axioms, if any. Empty array indicates the rule should run.
```
Tokens:
Raw