콘텐츠로 이동
contextlint

GRP-003 고립 문서

개요

섹션 제목: “개요”

files와 일치하는 문서 중, 다른 어느 문서에서도 링크되지 않은(incoming reference가 0건인) 파일을 검출합니다. 검출되면 warning 으로 보고됩니다. 프로젝트 스코프 의 규칙으로, include로 읽어들인 모든 문서를 횡단하여 평가됩니다.

entryPoints로 지정한 파일(README나 index 등, 외부에서 추적되는 기점 문서)은 고립으로 취급되지 않습니다.

왜 필요한가

섹션 제목: “왜 필요한가”

파일 이름을 변경했거나, 다른 디렉터리로 이동했거나, 새로 생성한 채로 기존 문서에서 붙이는 것을 잊어버린 케이스에서, 파일은 존재하지만 누구에게서도 추적되지 않는 “고립 문서” 가 생겨납니다. 이것은 검색하지 않으면 발견되지 않으며, 결과적으로 누구에게도 읽히지 않고, 내용이 낡아져도 누구도 알아채지 못합니다. AI로 문서를 대량 생성한 후에도 빈발합니다. 이 규칙은 그러한 고립을 검출합니다.

옵션

섹션 제목: “옵션”
필드타입필수설명
filesstring—고립 판정의 대상으로 할 파일의 glob. 미지정이면 모든 문서
entryPointsstring[]—기점 문서로 간주하여 고립 판정에서 제외할 glob 배열

entryPoints의 각 패턴은, 대상 파일의 경로와 파일명(basename) 양쪽에 대해 대조됩니다. README.md처럼 베이스 이름으로 써도, 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에 넣는 운용이 안전합니다.

관련 규칙

섹션 제목: “관련 규칙”