REF-002 ID 的定义与引用

概述

验证定义文件(如需求书)中声明的 ID 与其它文件(测试或设计文档等)的引用是否双向一致。这是项目作用域规则,会跨越 include 加载的所有文档进行评估。

• 被引用但无定义的 ID → error
• 已定义但未被引用的 ID → warning

为什么需要

需求 ID 通常在定义文件(如 requirements.md)中声明,并被测试、设计、实现文档引用。重命名或删除需求时,引用方文档不会自动跟随。反之,已定义却无人引用的需求,可能意味着它未被实现或测试覆盖。本规则可机械化验证双向的可追溯性。

选项

字段	类型	必填	说明
definitions	string	✓	定义 ID 的文件 glob
references	string[]	✓	引用 ID 的文件 glob 数组
idColumn	string	✓	定义文件中存放 ID 的列名
idPattern	string	✓	视为 ID 的值的正则表达式

idPattern 同时用于匹配定义侧表格列的值与引用侧文档中的文本。由于纯文本中的 token 也是对象,为避免误捕非 ID 单词,推荐包含明确的前缀(如 ^REQ-)。

违例

docs/requirements.md:
| ID     | 内容             |
| ------ | ---------------- |
| REQ-01 | 用户注册         |
| REQ-02 | 重置密码         |

docs/tests.md:
- REQ-01 的测试为 ...
- REQ-99 的测试为 ...

REQ-99 未定义,因此判定为 error;REQ-02 未被任何地方引用,因此判定为 warning。

docs/tests.md
  line 2  error  ID "REQ-99" is referenced but not defined in any definition file  REF-002

docs/requirements.md
  line 4  warning  ID "REQ-02" is defined but never referenced  REF-002

修正后

将定义侧没有的 REQ-99 改为 REQ-02,使 REQ-02 被引用。

docs/tests.md:
- REQ-01 的测试为 ...
- REQ-02 的测试为 ...

配置示例

{
  "rule": "ref002",
  "options": {
    "definitions": "**/requirements.md",
    "references": ["**/tests.md", "**/design.md"],
    "idColumn": "ID",
    "idPattern": "^REQ-\\d+$"
  }
}

相关规则

• TBL-006 文件间 ID 唯一性 — 验证定义文件内 ID 是否重复
• REF-003 稳定度一致性 — 验证 ID 引用在稳定度层面是否一致
• GRP-001 可追溯链 — 验证 ID 之间的依赖关系图