콘텐츠로 이동
contextlint

GRP-002 순환 참조

개요

섹션 제목: “개요”

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

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

왜 필요한가

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

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

옵션

섹션 제목: “옵션”
필드타입필수설명
filesstring—순환 검출의 대상으로 할 파일의 glob. 미지정이면 모든 문서
excludestring[]—그래프에서 제외할 파일의 glob 배열

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

위반 예시

섹션 제목: “위반 예시”
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로 지정한 파일은 그래프에서 노드째 제외됩니다. 그것들을 거친 순환은 검출 대상 외가 되므로, 양방향 링크가 필요한 목차계 파일에만 사용하는 것이 권장됩니다.

관련 규칙

섹션 제목: “관련 규칙”