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에 넣는 운용이 안전합니다.