repolinter - 自动化开源仓库质量检测与修复工具

对开源仓库进行常见问题检查。

安装

Repolinter 需要 Node.JS >= v12 才能正常运行。安装 Node.JS 后，可以使用 npm 安装 Repolinter：

npm install -g repolinter

检查本地仓库

安装完成后，运行以下命令来检查一个目录：

repolinter lint <directory>

上述命令将使用本地 repolinter.json 规则集或默认规则集（如果未找到本地规则集）来检查 <directory>：

repolinter % repolinter lint .
目标目录：<directory>
检查：
✔ license-file-exists：找到文件（LICENSE）
✔ readme-file-exists：找到文件（README.md）
✔ contributing-file-exists：找到文件（CONTRIBUTING）
✔ code-of-conduct-file-exists：找到文件（CODE-OF-CONDUCT）
✔ changelog-file-exists：找到文件（CHANGELOG）
...
repolinter % echo $?
0

检查远程仓库

Repolinter 还支持使用 --git 标志检查 git 仓库。启用此标志后，目录输入将被解释为 git URL，Repolinter 会自动将其克隆到临时目录中。

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

格式化输出

Repolinter CLI 目前支持三种输出格式模式：

默认（也称为结果）
JSON
Markdown

你可以使用 --format 标志切换格式。使用 JSON 格式的示例：

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

使用 Markdown 格式的示例：

repolinter % repolinter lint --format markdown .
# Repolinter 报告

此次 Repolinter 运行生成以下结果：
| ❗  错误 | ❌  失败 | ⚠️  警告 | ✅  通过 | 忽略 | 总计 |
|---|---|---|---|---|---|
| 0 | 0 | 0 | 15 | 10 | 25 |
...

限制路径

Repolinter 通过 --allowPaths 选项支持允许的路径列表，以防止意外检查构建产物。这些路径仍必须包含在目标目录/仓库中。

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

禁用修改

默认情况下，Repolinter 会自动执行规则集指定的修复。如果不希望这样做，可以使用 --dryRun 标志禁用此功能。

规则集配置

类似于 eslint 使用 eslintrc 文件来确定要执行的验证过程，Repolinter 使用 JSON 或 YAML 配置文件（称为规则集）来确定对仓库应运行哪些检查。在规则集中，可以配置两种主要行为：

规则 - Repolinter 应对仓库执行的检查。
公理 - Repolinter 应用于有条件运行规则的外部库。

这些组合功能让你能够精细控制 Repolinter 运行的检查。

提供规则集

Repolinter 将按以下优先顺序从这些来源获取配置：

使用 --rulesetFile 或 --rulesetUrl 指定的规则集
被检查项目根目录下的 repolint.json、repolinter.json、repolint.yaml 或 repolinter.yaml 文件
默认规则集

创建规则集

任何规则集都以以下基础开始，分别以 JSON 和 YAML 格式显示：

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

version: 2
axioms: {}
rules:

其中：

$schema - 指向所有 Repolinter 规则集的 JSON schema。此 schema 既验证规则集，又使规则集创建过程更加简便。
version - 指定 Repolinter 应期待的规则集版本。目前有两个版本：遗留配置省略版本号（示例）和其他所有情况使用的 2。除非你知道自己在做什么，否则请使用 2。
axiom - 公理功能，在公理部分covered。
rules - 实际的规则集，在规则部分covered。

规则

规则是以下格式的对象：

"<规则名称>": {
  "level": "error" | "warning" | "off",
  "rule": {
    "type": "<规则类型>",
    "options": {
      // <规则选项>
    }
  },
  "where": ["condition=*"],
  "fix": {
    "type": "<修复类型>",
    "options": {
      // <修复选项>
    }
  },
  "policyInfo": "...",
  "policyUrl": "..."
}

<规则名称>:
  level: error | warning | off
  rule:
    type: <规则类型>
    options:
      <规则选项>
  where: [condition=*]
  fix:
    type: <修复类型>
    options:
      <修复选项>
  policyInfo: >-
    ...
  policyUrl: >-
    ...

rule - 要执行的检查。Repolinter 可以执行规则文档中列出的任何检查。与 eslint 不同，Repolinter 的检查旨在被重复使用和专门化：例如，file-existence 检查可以在同一规则集中用于 README-file-exists 规则和 LICENSE-file-exists 规则。这允许用户通过配置通用检查来编写非常具体的规则集。
level - 如果检查失败时通知的错误级别。warning 不会改变退出代码，而 off 则不会运行检查。
where - 基于公理有条件地启用或禁用此规则。此数组中的字符串遵循 <axiom>=<value> 格式，其中 value 可以是公理输出或 *，用于简单测试公理是否启用。如果存在此选项，则仅当所有指定的公理输出都存在时，此规则才会运行。Repolinter 中可用的公理可以在公理文档中找到。
fix (可选) - 如果 rule 执行的检查失败时要执行的操作。Repolinter 可以执行修复文档中列出的任何操作。
policyInfo, policyUrl (可选) - 格式化程序用于从政策角度说明检查存在原因的信息。注意：policyInfo 将自动在末尾添加句点以便于格式化。

一个检查 README 是否存在的最小规则示例：

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

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

检查 README 是否匹配特定哈希值，如果不匹配则替换：

"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": "必须保持 readme 更新",
  "policyUrl": "www.example.com/mycompany"
}

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: 必须保持 readme 更新
  policyUrl: www.example.com/mycompany

公理

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

axioms:
  <axiom-id>: axiom-target

每个公理都被配置为axioms对象中的键值对，其中<axiom-id>指定要运行的程序，<axiom-target>指定在where条件中使用的目标。可用的公理ID可以在公理文档中找到。需要注意的是，某些公理需要外部包才能运行。

使用公理来检测项目的打包系统的配置示例：

{
  "$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": { /* ... */ }
    }
  }
}

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

一些公理（例如contributor-count）输出数值而不是字符串。对于这些公理，也可以在where条件中指定数值比较（<、>、<=、>=）。请注意，如果对非数值公理使用数值比较，比较将始终失败。

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

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

扩展规则集

一个规则集可以扩展另一个规则集，在这种情况下，两个文件将被递归合并。被扩展的规则集本身可以扩展额外的规则集，最多可深入20个规则集。

通过包含一个指定URL或文件路径的"extends"顶级键来扩展规则集：

{
  "extends": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json"
  "rules": {
    # 禁用CI检查
    "integrates-with-ci": {
      "level": "off"
    }
  }
}

extends: https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/default.json
rules:
  # 禁用CI检查
  integrates-with-ci
    level: off
    ...

相对路径是相对于用于访问扩展文件的位置解析的。例如，如果repolinter被调用为：

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

而该规则集包含extends: "./default.yaml"，路径将相对于原始URL解析为http://example.com/default.yaml。如果repolinter被调用为：

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

而该规则集包含extends: "./default.yaml"，路径将相对于原始文件路径解析为/etc/repolinter/default.yaml。

YAML和JSON规则集可以从任一格式扩展。

API

Repolinter还包括一个可扩展的JavaScript API：

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

此API允许开发人员完全控制Repolinter应使用的配置和格式。该库的文档可以在API文档中找到。

进一步了解

许可证

本项目根据Apache 2.0许可证授权。