# Spec: dataset-management

## ADDED Requirements

### Requirement: Git 仓库解析与候选 commit 筛选
系统 SHALL 接受开源 Git 仓库地址作为输入，遍历提交历史，按"变更规模适中、语言分布均衡、提交信息完整"规则筛选候选 commit。

#### Scenario: 筛选候选 commit
- **WHEN** 用户提供开源 Git 仓库地址并触发数据集构建
- **THEN** 系统遍历提交历史并输出符合筛选规则的候选 commit 列表

### Requirement: Unidiff 提取
系统 SHALL 为每个入选 commit 提取统一 Unidiff 格式变更文本，并保留变更前后文件上下文。

#### Scenario: 提取 diff 与上下文
- **WHEN** 一个 commit 被选中为样本
- **THEN** 系统产出 Unidiff 变更文本及变更前后文件上下文并持久化

### Requirement: 可插拔缺陷预埋
系统 SHALL 按可插拔缺陷规则在真实 diff 中预埋缺陷。内置缺陷类型 MUST 至少包括：空指针引用、资源未关闭、边界条件错误（含边界条件错乱）、逻辑运算符误用、并发安全问题。每种缺陷 MUST 为一条独立规则文件并按语言组织；用户新增规则文件即可自定义缺陷类型而无需改动框架代码。所有语言的规则 MUST 基于语法解析做 AST 级变换，MUST NOT 使用正则/纯文本级替换：Python 用标准库 `ast`；Java 用 `javalang`；JavaScript 用 `esprima`（新增依赖须在代码注释或文档中说明理由）。禁止引入重型多语言解析框架（如 tree-sitter、ANTLR）。无论内置或自定义规则，植入位置 MUST 精确可知。

#### Scenario: 内置规则预埋缺陷
- **WHEN** 对一个样本执行缺陷预埋
- **THEN** 系统按适用语言的规则植入缺陷，并记录缺陷类型与精确植入位置

#### Scenario: 自定义规则即插即用
- **WHEN** 用户新增一条自定义缺陷规则文件且不改动框架代码
- **THEN** 新样本可预埋该自定义缺陷并被正确标注

### Requirement: Ground Truth 标注
系统 SHALL 为每个样本生成含缺陷位置、缺陷类型、参考修复建议、语言类型的 Ground Truth 记录。

#### Scenario: 生成 Ground Truth
- **WHEN** 缺陷预埋完成
- **THEN** 系统产出与预埋一致的 Ground Truth 记录（缺陷类型/位置/参考修复/语言），抽查可复验

### Requirement: 实验数据集交付
系统 SHALL 交付 12 个 commit 样本的实验数据集，覆盖至少 3 种主流编程语言且语言分布均衡。

#### Scenario: 数据集构建完成
- **WHEN** 数据集构建流程结束
- **THEN** 产出 12 个带标注样本，覆盖 ≥3 种语言且分布均衡

### Requirement: 排除真实缺陷挖掘
系统 MUST NOT 做真实缺陷的自动挖掘（不做静态分析告警收集、不做历史 bug commit 自动识别），缺陷一律采用预埋方式。

#### Scenario: 仅预埋来源
- **WHEN** 检查数据集中任意缺陷记录
- **THEN** 该缺陷均来源于内置或自定义预埋规则，且有对应规则标识