GRP-002 순환 참조

개요

문서 간의 Markdown 링크를 그래프로 간주하여, 순환(A → B → C → A 같은 폐로)이 발생하지 않았는지를 검증합니다. 순환이 발견되면 error 로 보고됩니다. 프로젝트 스코프 의 규칙으로, include로 읽어들인 모든 문서를 횡단하여 평가됩니다.

검출 대상은 상대 경로로 .md 파일을 가리키는 링크만입니다. 앵커만의 링크(#section)나 외부 URL은 무시됩니다.

왜 필요한가

문서 A가 B를 참조하고, B가 C를 참조하고, C가 A를 참조하는 식의 순환은, 사람이 단독 파일을 보고 있는 것만으로는 절대 알아챌 수 없습니다. 정합성 있는 의존 관계를 유지하려면, 문서 그래프가 DAG(유향 비순환 그래프)인 것이 바람직하며, 순환은 독자의 혼란과 갱신 시의 영향 범위 추적 곤란을 낳습니다. AI로 대량으로 문서를 생성하면, 링크가 의도치 않게 양방향이 되어 순환이 발생하기도 합니다. 이 규칙은 그런 순환을 검출합니다.

옵션

필드	타입	필수	설명
`files`	string	—	순환 검출의 대상으로 할 파일의 glob. 미지정이면 모든 문서
`exclude`	string[]	—	그래프에서 제외할 파일의 glob 배열
`siteRouter`	object	—	Starlight 같은 SSG가 생성하는 routed URL(예: `/docs/x/`)을 해결하여 순환 검출이 그 링크를 따라갈 수 있게 함

옵션 전체를 생략해도 동작합니다. exclude는 목차 파일이나 index 파일처럼 여러 방향의 링크를 의도적으로 가지는 파일을 제외할 용도로 사용합니다.

`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": "grp002",
  "options": {
    "siteRouter": {
      "preset": "starlight",
      "contentDir": "packages/site/src/content/docs",
      "defaultLocale": "root",
      "locales": ["root", "ja", "ko", "zh"]
    }
  }
}

위반 예시

docs/a.md:

# A
See [B](./b.md).

docs/b.md:

# B
See [C](./c.md).

docs/c.md:

# C
See [A](./a.md).

a.md → b.md → c.md → a.md의 순환이 발생하고 있으므로 위반이 됩니다.

docs/a.md
  line 2  error  Circular reference detected: docs/a.md -> docs/b.md -> docs/c.md -> docs/a.md  GRP-002

수정 후

순환 중에서 「가장 의존이 약한 링크」 를 1개 끊습니다. 예를 들어 c.md → a.md의 링크를 다른 표현으로 바꿉니다.

docs/c.md:

# C

This module is consumed by upstream documents.

설정 예시

{
  "rule": "grp002",
  "options": {
    "files": "docs/**/*.md",
    "exclude": ["docs/index.md", "docs/sitemap.md"]
  }
}

exclude로 지정한 파일은 그래프에서 노드째 제외됩니다. 그것들을 거친 순환은 검출 대상 외가 되므로, 양방향 링크가 필요한 목차계 파일에만 사용하는 것이 권장됩니다.