GRP-003 孤立文档

概述

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

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

为什么需要

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

选项

字段	类型	必填	说明
`files`	string	—	孤立判定对象的文件 glob。未指定则覆盖所有文档
`entryPoints`	string[]	—	视为起点文档而从孤立判定中排除的 glob 数组
`siteRouter`	object	—	解析 Starlight 等 SSG 生成的 routed URL(如 `/docs/x/`),从而能够计入经由 SSG 链接的入度

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

`siteRouter` — SSG 的 routed URL 支持

不指定 siteRouter 时,/docs/x/ 这类绝对 URL 的入度不会被计入,因此只能经由 SSG 链接到达的文档会被错误判定为孤立。可用字段与 REF-001 的 siteRouter 完全相同。

子字段	类型	必填	说明
`preset`	string	—	已知的 SSG 预设。目前仅支持 `"starlight"`
`contentDir`	string	✓	内容目录（如 `"packages/site/src/content/docs"`）
`defaultLocale`	string	—	默认 locale。Starlight 无前缀的 root locale 指定为 `"root"`
`locales`	string[]	—	支持的 locale 列表（如 `["root", "ja", "ko", "zh"]`）
`urlPrefix`	string	—	(不使用 preset 的通用配置) 从 URL 中剥离的前缀
`indexFile`	string	—	最先尝试的 index 文件名（默认: `"index.md"`）

Starlight (i18n) 示例:

{
  "rule": "grp003",
  "options": {
    "files": "packages/site/src/content/docs/**/*.md",
    "entryPoints": ["docs/*/index.md"],
    "siteRouter": {
      "preset": "starlight",
      "contentDir": "packages/site/src/content/docs",
      "defaultLocale": "root",
      "locales": ["root", "ja", "ko", "zh"]
    }
  }
}

违例

假设仓库中存在以下 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。

GRP-003 孤立文档

概述

为什么需要

选项

siteRouter — SSG 的 routed URL 支持

违例

修正后

配置示例

相关规则

`siteRouter` — SSG 的 routed URL 支持