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 のようにベース名で書いても、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	—	デフォルトロケール。Starlight の prefix なし root ロケールには `"root"` を指定
`locales`	string[]	—	サポートするロケールのリスト（例: `["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 対応