REF-004 区域依赖

概述

验证跨越区域(zonesDir 下的子目录)的 Markdown 链接已在源区域的 overview.md 依赖章节中显式声明。未声明的跨区域引用会报告为 error。

为什么需要

将文档按 auth/、payment/、notification/ 等区域(以职责为单位的目录)管理时,区域之间的依赖关系会以隐式链接的形式不断增加。即使设计意图是「auth 不依赖 payment」,链接可以自由编写,依赖也会在不知不觉间扩散。本规则强制「区域间依赖必须在 overview.md 的依赖章节中显式声明」,使设计意图与文档结构保持一致。

选项

字段	类型	必填	说明
zonesDir	string	✓	区域所在目录的路径
dependencySection	string	—	声明依赖的章节标题(默认值:Dependencies)

zonesDir 直接子目录下的每个子目录都被视为一个区域。每个区域都应有 overview.md,其中包含 dependencySection 指定的标题,且该标题下的表格中列出依赖目标的区域名。

违例

docs/zones/auth/overview.md:
# Auth zone

## Dependencies

| Zone |
| ---- |

docs/zones/auth/login.md:
详见 [计费逻辑](../payment/charge.md)。

auth/login.md 含有指向 payment 区域的链接,但 auth/overview.md 的 Dependencies 章节未声明 payment,因此判定为违例。

docs/zones/auth/login.md
  line 1  error  Cross-zone reference to "payment" zone, but "payment" is not listed in the "Dependencies" section of auth/overview.md  REF-004

修正后

在 overview.md 中显式添加依赖。

docs/zones/auth/overview.md:
# Auth zone

## Dependencies

| Zone    |
| ------- |
| payment |

如果是不必要的依赖,则移除链接,或重新审视依赖源区域。

配置示例

{
  "rule": "ref004",
  "options": {
    "zonesDir": "docs/zones",
    "dependencySection": "Dependencies"
  }
}

相关规则

• REF-001 链接断裂 — 验证链接目标文件是否存在
• GRP-001 可追溯链 — 验证 ID 之间的依赖关系图
• GRP-002 循环引用 — 检测文档之间的循环依赖