# 场景 3：科研项目合规与复现性检查

## 目标

检查科研代码仓库的许可证合规性、信息安全风险，并评估项目的可复现性，生成评分卡报告。

## 参数

| 参数 | 必需 | 说明 |
|------|------|------|
| `--owner` | 是 | 仓库所有者 |
| `--repo` | 是 | 仓库名称 |
| `--output` | 否 | 输出文件路径 |
| `--local-path` | 否 | 本地仓库路径（用于 compliance 扫描，默认当前目录） |

## 数据收集步骤

### Step 1: 合规扫描
需要先在本地克隆的仓库目录中运行：
```bash
cd $LOCAL_REPO_PATH
gitlink-cli compliance +scan --format json
```

五个模块：
- **license**: 检测 LICENSE 文件是否存在、许可证类型
- **deps**: 检查依赖是否与许可证兼容
- **secrets**: 扫描硬编码密钥/Access Token
- **exposure**: 检测 PII（邮箱、手机号）和内部 URL 暴露
- **vocab**: 敏感词汇扫描

### Step 2: README 完整性
```bash
gitlink-cli api GET "raw/$OWNER/$REPO/master/README.md" --format json 2>/dev/null
```
检测以下章节是否存在（每项 0/0.5/1.0）：
- 项目标题与描述
- 安装说明（Install/安装/Setup）
- 使用说明（Usage/使用/Quick Start）
- 依赖声明（Requirements/依赖/Dependencies）
- 许可证信息
- 引用/致谢（Citation/Acknowledgement/引用）

### Step 3: 依赖声明检测
```bash
gitlink-cli api GET "/v1/$OWNER/$REPO/sub_entries?ref=master" --format json
```
检测依赖文件存在性：
- `package.json` (Node.js)
- `go.mod` (Go)
- `requirements.txt` / `pyproject.toml` / `Pipfile` (Python)
- `Cargo.toml` (Rust)
- `CMakeLists.txt` / `conanfile.txt` (C/C++)
- `pom.xml` / `build.gradle` (Java)
- `Gemfile` (Ruby)
- `DESCRIPTION` (R)
- `Project.toml` (Julia)

### Step 4: 构建说明检测
- README 中搜索关键词：build, install, compile, make, 构建, 安装, 编译
- 检测 Makefile / Dockerfile / docker-compose.yml 的存在
- 检测 CI 配置文件（.github/workflows/, .gitlab-ci.yml, Jenkinsfile）

### Step 5: CI/CD 配置
```bash
gitlink-cli ci +builds --owner $OWNER --repo $REPO --limit 10 --format json
```
- builds 列表非空 = 有 CI 配置
- 最近构建状态 = CI 是否通过

### Step 6: 测试证据
- 检测 test/、tests/、spec/、__tests__/ 目录
- README 中搜索 test、测试、validate
- 检测测试框架文件（*_test.go, *_test.py, *.test.js, *.spec.ts）

### Step 7: 数据可用性声明
- 扫描 README + 描述中的：
  - URL 指向 data/ 目录
  - dataset / 数据集关键词
  - Zenodo / Figshare / Kaggle / HuggingFace 链接
  - DOI 引用

## 复现性评分

8 维度加权评分（每维 0 / 0.5 / 1.0）：

| 维度 | 权重 | 评分标准 |
|------|------|---------|
| 许可证 | 15% | 1: 有 OSI 合规许可证; 0.5: 有非标准许可证; 0: 无 |
| 无密钥/PII | 15% | 1: 无发现; 0.5: 有低风险发现; 0: 发现密钥 |
| README 完整 | 15% | 1: ≥5 个必需章节; 0.5: 3-4 个; 0: <3 个 |
| 依赖声明 | 15% | 1: 有标准依赖文件; 0.5: README 中列出依赖; 0: 无 |
| 构建说明 | 10% | 1: 详细步骤; 0.5: 简要提及; 0: 无 |
| CI 配置 | 10% | 1: CI 存在且通过; 0.5: CI 存在但失败; 0: 无 CI |
| 测试证据 | 10% | 1: 有测试目录+说明; 0.5: 其中之一; 0: 无 |
| 数据可用性 | 10% | 1: 明确数据引用; 0.5: 隐含提及; 0: 无 |

总分 100：
```
Score = SUM(dimension_score_i * weight_i) * 100
```

等级：
- **A** (>=85)：优秀，高度可复现
- **B** (70-84)：良好，基本可复现
- **C** (55-69)：一般，部分可复现
- **D** (40-54)：不足，复现困难
- **F** (<40)：差，几乎不可复现

## 输出

1. **HTML 评分卡** (`output/reproducibility-{repo}-{date}.html`)：
   - 总体评分仪表盘
   - 8 维度雷达图
   - 各维度明细表（评分 + 证据 + 改进建议）
   - 合规风险汇总

2. **Wiki Markdown** — 精简评分卡

## 可执行脚本

```bash
cd /path/to/local/repo
bash workflows/08-research-compliance.sh --owner zzx-coder --repo gitlink-cli
```

## 改进建议生成

根据评分自动生成改进建议：

| 缺失项 | 建议 |
|--------|------|
| 无 LICENSE | 建议添加 MIT/Apache-2.0/GPL-3.0 许可证 |
| 无 README | 建议添加 README 说明项目目的、安装和使用 |
| 无依赖文件 | 建议添加 package.json/go.mod/requirements.txt |
| 无 CI | 建议配置 .github/workflows 或 GitLink CI |
| 无测试 | 建议添加 unit test 和 smoke test |
| 无数据声明 | 建议说明数据集来源或生成方法 |
