跳转到内容
contextlint

GRP-001 可追溯链

概述

Section titled “概述”

验证 ID 能否像 需求 → 设计 → 测试计划 那样在多个文档阶段中按顺序追溯。某个阶段中 ID 未被引用时,会报告为 warning。这是项目作用域规则,会跨越 include 加载的所有文档进行评估。

收集首阶段(chain[0])idColumn 中的 ID,并依次确认其后各阶段的 refColumn 是否引用了这些 ID。

为什么需要

Section titled “为什么需要”

在 需求 → 设计 → 测试 这样的流程中,「需求 ID 必定在设计中被引用,设计中出现的 ID 必定在测试中被引用」是一致性的最低条件。但当增加一项需求却忘了写设计,或忘了写测试计划时,文件分散后人眼无法追踪。本规则可机械化检测链中的缺失。

选项

Section titled “选项”
字段类型必填说明
chainobject[]✓构成链的各阶段(至少 2 阶段)。数组顺序即验证顺序
idPatternstring—仅将匹配此正则表达式的值视为 ID(不匹配的值将被忽略)

chain 的各阶段

Section titled “chain 的各阶段”
字段类型必填说明
stagestring✓阶段名(将出现在错误信息中)
filesstring✓表示该阶段文档的 glob
idColumnstring—该阶段定义 ID 的列名(首阶段必填)
refColumnstring—该阶段引用前一阶段 ID 的列名(第二阶段及以后必填)

首阶段指定 idColumn,第二阶段及以后指定 refColumn。

违例

Section titled “违例”
docs/requirements.md:


| ID      | Name   |
| ------- | ------ |
| REQ-001 | Login  |
| REQ-002 | Logout |


docs/design.md:


| Requirement | Detail        |
| ----------- | ------------- |
| REQ-001     | Design login  |

REQ-002 未被 docs/design.md 的 Requirement 列引用,因此判定为违例。

docs/requirements.md
  line 4  warning  REQ-002 defined in docs/requirements.md but not referenced in stage "Design"  GRP-001

修正后

Section titled “修正后”
docs/design.md:


| Requirement | Detail         |
| ----------- | -------------- |
| REQ-001     | Design login   |
| REQ-002     | Design logout  |

配置示例

Section titled “配置示例”
{
  "rule": "grp001",
  "options": {
    "chain": [
      { "stage": "Requirements", "files": "**/requirements.md", "idColumn": "ID" },
      { "stage": "Design", "files": "**/design.md", "refColumn": "Requirement" },
      { "stage": "Test", "files": "**/test-plan.md", "refColumn": "Covers" }
    ],
    "idPattern": "^REQ-\\d{3}$"
  }
}

3 阶段以上的链也能通过扩展 chain 数组直接表达。指定 idPattern 可以将表头样例行或表记不一致的行从 ID 集合中排除。

相关规则

Section titled “相关规则”