コンテンツにスキップ
contextlint

GRP-003 孤立ドキュメント

概要

Section titled “概要”

files でマッチするドキュメントのうち、他のどのドキュメントからもリンクされていない（incoming reference が 0 件の）ファイルを検出します。検出されると warning で報告されます。プロジェクトスコープ のルールで、include で読み込んだ全ドキュメントを横断して評価されます。

entryPoints で指定したファイル（READMEや index など、外から辿られる起点ドキュメント）は孤立として扱われません。

なぜ必要か

Section titled “なぜ必要か”

ファイル名を変えた、別のディレクトリに移した、新規作成したまま既存ドキュメントから貼り忘れた、といったケースで、ファイルは存在するけれど誰からも辿れない “孤立ドキュメント” が生まれます。これは検索しないと見つからず、結果として誰にも読まれず、内容が古くなっても誰も気づきません。 AI でドキュメントを大量生成したあとにも頻発します。このルールはそうした孤立を検出します。

オプション

Section titled “オプション”
フィールド型必須説明
filesstring—孤立判定の対象とするファイルの glob。未指定なら全ドキュメント
entryPointsstring[]—起点ドキュメントとみなして孤立判定から除外する glob 配列

entryPoints の各パターンは、対象ファイルのパスとファイル名（basename）の両方に対して照合されます。README.md のようにベース名で書いても、docs/README.md のようにパスで書いても機能します。

違反例

Section titled “違反例”

リポジトリに次の 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

修正後

Section titled “修正後”

参照する側のドキュメントからリンクを追加するか、不要なら削除します。

docs/architecture.md:


## Background


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

設定例

Section titled “設定例”
{
  "rule": "grp003",
  "options": {
    "files": "docs/**/*.md",
    "entryPoints": ["README.md", "docs/index.md"]
  }
}

entryPoints には、どこからも参照されないが起点として正当なファイルを列挙します。これを忘れると README 自身が孤立として報告されてしまうので、目次・トップページ系のファイルは必ず entryPoints に入れる運用が安全です。

関連ルール

Section titled “関連ルール”