GRP-003 孤立文档

概述

在 files 匹配的文档中,检测未被其它任何文档链接(incoming reference 数为 0)的文件。检测到时会报告为 warning。这是项目作用域规则,会跨越 include 加载的所有文档进行评估。

entryPoints 中指定的文件(像 README 或 index 那样从外部追溯的起点文档)不会被视为孤立。

由于改文件名、移动到其它目录、或新建之后忘记从既有文档中链接,文件存在但任何人都无法追溯,这就形成「孤立文档」。这类文档不搜索就找不到,结果是无人阅读;即便内容陈旧也无人察觉。AI 大量生成文档之后也频繁发生。本规则可检测此类孤立。

字段	类型	必填	说明
`files`	string	—	孤立判定对象的文件 glob。未指定则覆盖所有文档
`entryPoints`	string[]	—	视为起点文档而从孤立判定中排除的 glob 数组

entryPoints 的每个模式都会与对象文件的路径和文件名(basename)双方进行匹配。无论用 README.md 这样的 basename 书写,还是用 docs/README.md 这样的路径书写都生效。

假设仓库中存在以下 3 个文件。

docs/README.md       — 起点文档
docs/architecture.md — 从 README 通过 [ ](./architecture.md) 引用
docs/legacy-notes.md — 未被任何文档链接

docs/legacy-notes.md 未被其它任何文档引用,故判定为违例。

docs/legacy-notes.md
  line 1  warning  docs/legacy-notes.md has no incoming references from any other document  GRP-003

从引用方文档添加链接,或在不需要时直接删除。

docs/architecture.md:

## Background

For historical context, see [legacy notes](./legacy-notes.md).

{
  "rule": "grp003",
  "options": {
    "files": "docs/**/*.md",
    "entryPoints": ["README.md", "docs/index.md"]
  }
}

在 entryPoints 中列出虽未被引用但作为起点合理的文件。如果忘记列入,README 自身可能被报告为孤立,因此推荐将目录、首页类文件务必加入 entryPoints。