# 介绍

实现了一个CLI工具子模块，完成OpenSODA T2赛题。

本任务是基于 OpenDigger 已实现的各类指标，开发一个命令行工具，使得用户可以在终端查询 GitHub 上每一个仓库或每一个开发者在各项指标上的数据结果。

该子模块的形态是一个可运行的CLI工具，安装后用户可以通过一系列命令达成各种查询功能，如：

查询**特定仓库**在**特定指标**上的数据；

查询**特定仓库**在**特定自然月**上在**特定指标**上的数据；

查询**特定仓库**在**特定自然月份**上的**整体报告**；

按类型、来源等**分类**查询**特定仓库**在**特定自然月份**上的整体报告（**其余具体功能**见后续的功能展示和CLI命令介绍，此处不一一列出）。



# 主要功能展示

**（npm网页若不显示图片，系图床加载超时，此时请下载源代码查看README.md文档）**

## 1、查询特定仓库在特定指标上的数据，可以选择导出到本地某位置

**查询，不导出报告**

```
hq --repo X-lab2017/open-digger --metric openrank
```

![](pictures/1.png)

**查询，导出报告（默认路径为：当前目录下/output.txt，可通过--path参数自行设定，此处先新建一个report文件夹，在设置参数保存报告到此文件夹中）**

```
mkdir report
hq --repo X-lab2017/open-digger --metric openrank --download --path report/output.txt
```

![](pictures/2.png)

![](pictures/3.png)

## 2、查询**特定仓库**在**特定自然月**上在**特定指标**上的数据

**前者不保存报告文件，后者保存（此处不设置路径，默认输出到终端目录下output.txt）**

```
hq --repo X-lab2017/open-digger --metric openrank --month 2023-01
hq --repo X-lab2017/open-digger --metric openrank --month 2023-01 --download
```

![](pictures/4.png)

![](pictures/5.png)

![](pictures/6.png)

## 3、查询**特定仓库**在**特定自然月份**上的**整体报告**，本支持本地导出功能

**前者不保存报告文件，后者保存（此处不设置路径，默认输出到终端目录下output.txt）**

```
hq --repo X-lab2017/open-digger --month 2023-01
hq --repo X-lab2017/open-digger --month 2023-01 --download
```

![](pictures/7.png)

![](pictures/8.png)

![](pictures/9.png)

## 4、查询特定仓库的所有指标，支持本地导出

```
hq --repo X-lab2017/open-digger
hq --repo X-lab2017/open-digger --download
```

![](pictures/10.png)

![](pictures/11.png)

## 5、查询特定仓库，某类型的所有指标情况，支持指定自然月，支持本地导出

**查询类型Type为index的所有指标，后者设置了--download可保存报告到本地**

```
hq --repo X-lab2017/open-digger --type index
hq --repo X-lab2017/open-digger --type index --download
```

![](pictures/12.png)

![](pictures/13.png)

**查询来源from为chaoss的所有指标，后者指定了某个月份**

```
hq --repo X-lab2017/open-digger --from chaoss
hq --repo X-lab2017/open-digger --from chaoss --month 2023-01
```

![](pictures/14.png)

![](pictures/15.png)

**查询同时满足指定类型和指定来源的指标，支持指定自然月**

```
hq --repo X-lab2017/open-digger --type metric --from chaoss --month 2023-01
```

![](pictures/0.png)



# 安装&测试

全局安装

```
// 安装
npm install -g hdx-t2-query
// 测试运行&修改代码功能
hq -v
...
// 卸载
npm uninstall -g hdx-t2-query
```

开发者测试

```
// 先下载源代码，再进入源代码目录执行命令，进行link
npm link
// 测试运行&修改代码功能
hq -v
...
// 取消link
npm unlink
```



# 提供的CLI命令、参数介绍

## hq

为hdx-t2-query缩写，此处用作启动工具。

## --clear&--noClear

设置在每次查询前后是否对终端清屏，主要在开发测试中使用，最终版本中我已经把该功能关闭。

## --version

缩写为--v，查看工具版本。

## --debug

用于debug的选项，最终版本中我已把该功能关闭，若需要请手动修改打开。

## --download

缩写为--d，默认取值为false，用于设置是否将报告保存到本地。

## --repo

缩写为--r，默认取值为'X-lab2017/open-digger'，即指向本次查询仓库（本工具按要求使用了给定仓库的数据，故该值**无特殊情况不用更改，请使用默认值**。若要查询其他仓库，需要对源代码做微调，因为其他仓库的数据指标路径不一定和比赛仓库的数据指标路径格式相同）。

## --metric

缩写为--me，默认取值为'all'，当取all时将查询符合要求的**所有**指标；当取特定指标名字时将**只**查询该特定指标的情况。

## --type

缩写为--ty，默认取值为'all'，该参数用于限定**查询多个指标**时，按**类型**选择需要查询**哪些指标**。可取的类型详见**比赛仓库**中给出数据的类型（index、metric等）。

## --from

缩写为--f，默认取值为'all'，该参数用于限定**查询多个指标**时，按**来源**选择需要查询**哪些指标**。可取的来源详见**比赛仓库**中给出数据的来源（xlab、chaoss）。

## --path

缩写为--p，默认值取值为'output.txt'，该参数用于选择保存报告到本地的路径，默认保存到终端目录下的output.txt文件（为了避免不必要的bug，若设置到其他目录，请保证其他目录的路径存在）。

# 代码结构

![](pictures/16.png)

README.md即该文档，package.json为包信息设置，index.js为框架入口。

utils目录下为工具的各个模块（其中query_backup.js和queryAll_backup.js为开发过程中的测试代码，在成品版本中作为留档，无功能作用）。

pictures目录下为README.md中需要加载的图片，若在npm网页端仓库图床加载失败，可支持下载源码并查看图片完整的README.md文档。