npm package: @stevending1st/open-digger-cli
Description: OpenDigger CLI
Author: stevending1st
Latest version: 0.0.8

# open-digger-cli

> 📈 一个查询 [open-digger][1] 指标的 CLI 工具。

## 💡 功能 & 路线图

- ✅ 基础的指标查询，支持指定特定的指标、时间范围。
- ✅ 生成 pdf 报告，支持指定特定的指标、时间范围。
- ✅ 支持对话式交互，使用更友好。
- 🚧<sup style="color: red;">\*</sup> 支持更多的报告输出格式。
- 🚧<sup style="color: red;">\*</sup> 为生成报告添加**插件系统**，让使用者自定义更多内容。
- ✅ 为命令行查询工具添加**插件系统**，让使用者自定义更多内容。

## 🧶 设计思路

命令行获取命令和参数后，解析数据，根据子命令执行不同操作（在执行操作前会向 open-digger 提供的数据服务进行数据拉取）：

数据查询功能：将获取的数据打印到命令行工具；

数据导出功能：将获取的数据根据命令，使用不同的引擎进行渲染，再进行不同形式的导出。

在此过程中，open-digger-cli 计划提供丰富的 hook，以便用户根据自己的需要进行数据展示。

## 💣 实现难点

1. 支持 `json`、`yml` 等配置文件难度较低，但可拓展性有限；目前计划支持 `js`、`mjs` 等配置文件，增强软件的可拓展性，但难度较之前大大提高。

2. 目前计划支持 pdf 导出，数据传递及数据展示难度都较大，pdf 按预期格式导出也具有一定困难。

## 🔧 安装

本工具基于 Node.js，请在安装本工具前安装前 Node.js 环境。

```bash
npm i -g @stevending1st/open-digger-cli
```

## ⌨️ 命令行使用

### 版本查询

```bash
digger --version

# 或

digger -v
```

### 帮助命令

#### 全局帮助

```bash
digger --help

# 或

digger -h
```

### 子命令帮助

```bash
digger --help <command>

# 或

digger -h <command>
```

`<command>`: 子命令，目前支持 `chat`、`export`

### 指标查询

查询指定仓库/用户的指标。

```bash
digger <example> -m <metrics> [-t <time>]
```

- `<example>`：指定一个仓库或者用户。例如：`X-lab2017/open-digger`、`stevending1st`。
- `<metrics>`：指定查询的指标，支持多个指标，多个查询用 `,` 连接。例如：`openrank`、`openrank activity`。
  目前支持参数：`openrank`、`activity`、`attention`、`active_dates_and_times`、`stars`、`technical_fork`、`participants`、`new_contributors`、`new_contributors_detail`、`inactive_contributors`、`bus_factor`、`bus_factor_detail`、`issues_new`、`issues_closed`、`issue_comments`、`issue_response_time`、`issue_resolution_duration`、`issue_age`、`code_change_lines`、`code_change_lines_add`、`code_change_lines_remove`、`code_change_lines_sum`、`change_requests`、`change_requests_accepted`、`change_requests_reviews`、`change_request_response_time`、`change_request_resolution_duration`、`change_request_age`、`activity_details`。
- `<time>`：查询的时间范围，格式为 yyyyMM 或 yyyyMM-yyyyMM 。例如：`202203`、`201912-202212`。

#### 查询指定仓库的指定指标

```bash
digger <example> -m <metrics>
```

例如：`digger X-lab2017/open-digger -m openrank`

```bash
repo.owner: X-lab2017
repo.name: open-digger
repo.url:https://github.com/X-lab2017/open-digger
repo.openrank:  {
  '2020-08': 3.46,
  '2020-09': 3.7,
  '2020-10': 4.28,
  '2020-11': 5.2,
  '2020-12': 7.82,
  '2021-01': 7.29,
  '2021-02': 4.45,
  '2021-03': 2.95,
  '2021-04': 3.36,
  '2021-05': 3.1,
  '2021-06': 4.78,
  '2021-07': 3.59,
  '2021-08': 2.56,
  '2021-09': 2.18,
  '2021-10': 2,
  '2021-11': 1.88,
  '2021-12': 2.3,
  '2022-01': 3.52,
  '2022-02': 3.55,
  '2022-03': 4.49,
  '2022-04': 2.69,
  '2022-05': 2.88,
  '2022-06': 5.59,
  '2022-07': 6.47,
  '2022-08': 6.01,
  '2022-09': 7.16,
  '2022-10': 9.32,
  '2022-11': 11.82,
  '2022-12': 15.16,
  '2023-01': 15.38,
  '2023-02': 32.22,
  '2023-03': 16.17,
  '2023-04': 13.55,
  '2023-05': 13.42,
  '2023-06': 10.05,
  '2023-07': 10.56,
  '2023-08': 9.83,
  '2023-09': 8.59
}
```

#### 查询指定时间范围的指定仓库的指定指标

```bash
digger <example> -m <metrics> -t <time>
```

例如：`digger X-lab2017/open-digger -m openrank stars -t 202201-202206`

```bash
repo.owner: X-lab2017
repo.name: open-digger
repo.url:https://github.com/X-lab2017/open-digger
month: 202201-202206
repo.openrank:  {
  '2022-01': 3.52,
  '2022-02': 3.55,
  '2022-03': 4.49,
  '2022-04': 2.69,
  '2022-05': 2.88,
  '2022-06': 5.59
}
repo.stars:  {
  '2022-01': 5,
  '2022-02': 5,
  '2022-03': 102,
  '2022-04': 3,
  '2022-05': 4,
  '2022-06': 1
}
```

#### 查询指定用户的指定指标

```bash
digger <example> -m <metrics>
```

例如：`digger stevending1st -m openrank`

```bash
user: stevending1st
repo.url:https://github.com/stevending1st
user.openrank:  {
  '2017-01': 0.66,
  '2017-02': 0.56,
  '2017-03': 0.48,
  '2017-04': 0.4,
  '2017-05': 0.34,
  '2017-06': 0.29,
  '2017-07': 0.25,
  '2017-08': 0.21,
  '2017-09': 0.18,
  '2017-10': 0.15,
  '2017-11': 0.13,
  '2017-12': 0.11,
  '2018-01': 0.09,
  '2018-02': 0.08,
  '2018-03': 0.07,
  '2018-04': 0.06,
  '2018-05': 0.05,
  '2018-06': 0.04,
  '2018-07': 0.35,
  '2018-08': 0.3,
  '2018-09': 0.26,
  '2018-10': 0.22,
  '2018-11': 0.18,
  '2018-12': 0.16,
  '2019-01': 0.13,
  '2019-02': 0.11,
  '2019-03': 0.1,
  '2019-04': 0.08,
  '2019-05': 0.07,
  '2019-06': 0.06,
  '2019-07': 0.05,
  '2019-08': 0.37,
  '2019-09': 0.31,
  '2019-10': 0.27,
  '2019-11': 0.23,
  '2019-12': 0.19,
  '2020-01': 0.46,
  '2020-02': 0.39,
  '2020-03': 0.33,
  '2020-04': 0.22,
  '2020-05': 0.19,
  '2020-06': 0.16,
  '2020-07': 0.14,
  '2020-08': 0.12,
  '2020-09': 0.1,
  '2020-10': 0.25,
  '2020-11': 0.28,
  '2020-12': 0.24,
  '2021-01': 0.31,
  '2021-02': 0.26,
  '2021-03': 0.89,
  '2021-04': 1.29,
  '2021-05': 1.35,
  '2021-06': 1.62,
  '2021-07': 1.69,
  '2021-08': 3.01,
  '2021-09': 2.8,
  '2021-10': 2,
  '2021-11': 2.18,
  '2021-12': 1.85,
  '2022-01': 1.71,
  '2022-02': 2.98,
  '2022-03': 3.73,
  '2022-04': 2.13,
  '2022-05': 1.64,
  '2022-06': 1.37,
  '2022-07': 0.9,
  '2022-08': 0.54,
  '2022-09': 1.45,
  '2022-10': 3.16,
  '2022-11': 2.53,
  '2022-12': 1.97,
  '2023-01': 1.41,
  '2023-02': 2.48,
  '2023-03': 1.44,
  '2023-04': 2.67,
  '2023-05': 2.44,
  '2023-06': 2.81,
  '2023-07': 3.4,
  '2023-08': 2.05,
  '2023-09': 1.97
}
```

#### 查询指定时间范围的指定用户的指定指标

```bash
digger <example> -m <metrics> -t <time>
```

例如：`digger stevending1st -m openrank -t 202101-202112`

```bash
user: stevending1st
repo.url:https://github.com/stevending1st
month: 202101-202112
user.openrank:  {
  '2021-01': 0.31,
  '2021-02': 0.26,
  '2021-03': 0.89,
  '2021-04': 1.29,
  '2021-05': 1.35,
  '2021-06': 1.62,
  '2021-07': 1.69,
  '2021-08': 3.01,
  '2021-09': 2.8,
  '2021-10': 2,
  '2021-11': 2.18,
  '2021-12': 1.85
}
```

### 导出文件

```bash
digger export <example> -m <metrics> [-t <time>]
```

- `<example>`：指定一个仓库或者用户。例如：`X-lab2017/open-digger`、`stevending1st`。
- `<metrics>`：指定查询的指标，支持多个指标，多个查询用 `,` 连接。例如：`openrank`、`openrank activity`。
  目前支持参数：`openrank`、`activity`、`attention`、`active_dates_and_times`、`stars`、`technical_fork`、`participants`、`new_contributors`、`new_contributors_detail`、`inactive_contributors`、`bus_factor`、`bus_factor_detail`、`issues_new`、`issues_closed`、`issue_comments`、`issue_response_time`、`issue_resolution_duration`、`issue_age`、`code_change_lines`、`code_change_lines_add`、`code_change_lines_remove`、`code_change_lines_sum`、`change_requests`、`change_requests_accepted`、`change_requests_reviews`、`change_request_response_time`、`change_request_resolution_duration`、`change_request_age`、`activity_details`。
- `<time>`：查询的时间范围，格式为 yyyyMM 或 yyyyMM-yyyyMM 。例如：`202203`、`201912-202212`。

## 🧩 插件

本应用计划支持**强大的插件功能**，支持在命令行工具进行数据展示和生成报告等流程中调用 api 以自定义显示内容。

例子：

```js
import Table from 'cli-table3';

export default {
  cli: {
    openrank: ({ metric, time, example, data }) => {
      const showData = [];
      for (let key in data) {
        showData.push([key, data[key]]);
      }

      const table = new Table({
        head: ['Time', 'openRank'],
        colWidths: [10, 20]
      });

      table.push(...showData);

      console.log(`${example}'s openrank(${time}):`);

      console.log(table.toString());
    }
  }
};
```

在配置文件所在目录执行：

```bash
digger X-lab2017/open-digger -m openrank stars -t 202201-202206
```

结果：

```bash
repo.owner: X-lab2017
repo.name: open-digger
repo.url:https://github.com/X-lab2017/open-digger
month: 202201-202206
X-lab2017/open-digger's openrank(202201-202206):
┌──────────┬────────────────────┐
│ Time     │ openrank           │
├──────────┼────────────────────┤
│ 2022-01  │ 3.52               │
├──────────┼────────────────────┤
│ 2022-02  │ 3.55               │
├──────────┼────────────────────┤
│ 2022-03  │ 4.49               │
├──────────┼────────────────────┤
│ 2022-04  │ 2.69               │
├──────────┼────────────────────┤
│ 2022-05  │ 2.88               │
├──────────┼────────────────────┤
│ 2022-06  │ 5.59               │
└──────────┴────────────────────┘
repo.stars:  {
  '2022-01': 5,
  '2022-02': 5,
  '2022-03': 102,
  '2022-04': 3,
  '2022-05': 4,
  '2022-06': 1
}
```

[1]: https://github.com/X-lab2017/open-digger