Skip to content

lint.md

Latest commit

 

History

History
265 lines (167 loc) · 10.9 KB

lint.md

File metadata and controls

265 lines (167 loc) · 10.9 KB
Raw

Lint 가이드 (Lint Guide)

English

ccg lint 카테고리에 대한 상세 레퍼런스, 보고서 계산 방식 및 결과 해석 방법을 안내합니다.

개요 (Overview)

ccg lint는 다음 세 가지 요소를 교차 확인합니다:

  1. 설정된 문서 출력 디렉토리 하위에 생성된 마크다운 문서들
  2. 그래프 데이터베이스에 이미 저장된 소스 파일 및 심볼들
  3. 그래프 심볼에 첨부된 구조화된 어노테이션들

이 명령어는 문서 커버리지 이슈와 어노테이션 품질 이슈를 함께 보고합니다.

빠른 사용법 (Quick Usage)

# 문서 및 어노테이션 상태 확인
ccg lint

# strict 모드 규칙에 따라 실패 시 종료 코드 반환
ccg lint --strict

# 기본값이 아닌 다른 문서 디렉토리 린트
ccg lint --out docs

CLI 플래그 및 .ccg.yaml의 린트 규칙에 대해서는 CLI 레퍼런스를 참조하십시오.

ccg lint 작동 방식

상위 레벨에서 린터는 다음 단계를 수행합니다:

  1. 문서 출력 디렉토리를 탐색하여 마크다운 파일 수집
  2. 데이터베이스에서 그래프 노드를 조회하고 현재 그래프에 표현된 소스 파일 도출
  3. 문서와 그래프 파일 간의 교차 확인
  4. 심볼 어노테이션 및 태그 로드
  5. 각 이슈를 린트 카테고리 중 하나로 분류

주요 구현 세부 사항:

  • index.md는 파일별 문서로 취급되지 않으므로 건너뜁니다.
  • missing 및 stale은 파일 레벨 카테고리입니다.
  • unannotated, contradiction, dead-ref, incomplete, drifted는 심볼 레벨 카테고리입니다.
  • 그래프 기반 파일 문서 커버리지를 계산할 때 테스트 파일이 포함되지만, unannotated 심볼 체크에서는 테스트가 제외됩니다.

카테고리 (Categories)

ccg lint는 다음 카테고리들을 보고합니다.

orphan

문서 파일은 존재하지만, 그래프에는 더 이상 일치하는 소스 파일이 없는 경우입니다.

  • 일반적인 원인: 코드가 삭제되거나 이동되었지만, 생성된 문서 파일이 남아 있는 경우.
  • 실제 의미: 해당 문서가 현재 라이브 코드베이스와 분리되었습니다.
  • 일반적인 해결책: 문서를 재생성하거나 오래된 문서 파일을 삭제합니다.

missing

그래프에는 소스 파일이 존재하지만, 일치하는 마크다운 문서 파일이 없는 경우입니다.

  • 일반적인 원인: 해당 파일에 대해 문서가 생성된 적이 없거나 문서 디렉토리가 불완전한 경우.
  • 실제 의미: 파일 레벨의 문서 커버리지가 누락되었습니다.
  • 일반적인 해결책: 현재 그래프 상태에 대해 문서 생성을 실행합니다.

stale

문서 파일은 존재하지만, 수정 시간이 그래프에 기록된 해당 소스 파일의 최신 업데이트 시간보다 오래된 경우입니다.

  • 일반적인 원인: 마지막 문서 생성 이후 코드가 변경되었습니다.
  • 실제 의미: 문서는 존재하지만 현재 코드를 정확하게 설명하지 못할 수 있습니다.
  • 일반적인 해결책: 그래프를 빌드하거나 업데이트한 후 문서를 재생성합니다.

unannotated

함수, 클래스 또는 타입 심볼에 어노테이션 기록이 전혀 없는 경우입니다.

  • 일반적인 원인: 심볼에 @intent와 같은 구조화된 어노테이션이 없습니다.
  • 실제 의미: 검색 및 AI 컨텍스트에서 코드를 여전히 사용할 수는 있지만, 사람이 작성한 명시적인 의도(intent) 레이어를 잃게 됩니다.
  • 일반적인 해결책: 선언부 위에 구조화된 어노테이션 주석을 추가합니다.

contradiction

어노테이션이 존재하고 하나 이상의 @param 태그를 포함하며, 해당 어노테이션이 작성된 후 코드 노드가 업데이트된 경우입니다.

  • 일반적인 원인: 시그니처나 동작이 변경되었지만, @param 상세 정보가 갱신되지 않은 경우.
  • 실제 의미: 상세 어노테이션을 신뢰할 수 없을 가능성이 높습니다.
  • 일반적인 해결책: 심볼을 검토하고 상세 어노테이션 태그를 업데이트합니다.

이는 일반적인 drift보다 의도적으로 더 엄격하게 적용됩니다. 코드 변경 시 @param 태그가 특히 틀려질 가능성이 높기 때문입니다.

dead-ref

@see 태그가 그래프에 존재하지 않는 정규화된 이름(qualified name)을 가리키는 경우입니다.

  • 일반적인 원인: 참조된 심볼의 이름이 변경되었거나, 제거되었거나, 이동되었습니다.
  • 실제 의미: 상호 참조 네비게이션이 깨졌습니다.
  • 일반적인 해결책: @see 태그를 업데이트하거나 제거합니다.

incomplete

어노테이션은 존재하지만 @intent 태그를 포함하고 있지 않은 경우입니다.

  • 일반적인 원인: 의도(intent) 어노테이션 없이 문서 주석만 추가되었거나, 태그의 일부만 작성되었습니다.
  • 실제 의미: 심볼에 대한 일부 문서화는 되어 있지만, 그것이 왜 존재하는지에 대한 가장 중요한 구조적 설명이 누락되었습니다.
  • 일반적인 해결책: 어노테이션 블록에 @intent를 추가합니다.

drifted

어노테이션은 존재하지만, 어노테이션이 작성된 후 코드 노드가 업데이트된 경우입니다.

  • 일반적인 원인: 코드가 진화하는 동안 어노테이션이 갱신되지 않았습니다.
  • 실제 의미: 어노테이션이 방향성으로는 맞을 수 있지만, 현재 구현과 일치한다고 보장할 수 없습니다.
  • 일반적인 해결책: 어노테이션을 검토하고 갱신합니다.

drifted는 contradiction보다 범위가 넓습니다. @param과 같은 상세 태그가 없더라도 심볼이 drift될 수 있습니다.

카테고리 관계 (Category Relationships)

일부 카테고리는 중복될 수 있으며, 일부는 그렇지 않습니다.

카테고리 A 카테고리 B 관계
contradiction drifted 모든 contradiction은 일종의 drift이지만, 모든 drift가 contradiction인 것은 아닙니다.
unannotated incomplete 실질적으로 상호 배타적입니다: incomplete는 어노테이션이 존재함을 의미하고, unannotated는 존재하지 않음을 의미합니다.
missing stale 파일당 상호 배타적입니다: 파일에 문서가 없으면서 동시에 오래된 문서를 가질 수는 없습니다.

파일 레벨 vs 심볼 레벨 카테고리

파일 레벨 (File-level)

  • orphan
  • missing
  • stale

이 카테고리들은 생성된 마크다운 파일이 현재 그래프 기반 소스 파일과 일치하는지에 관한 것입니다.

심볼 레벨 (Symbol-level)

  • unannotated
  • contradiction
  • dead-ref
  • incomplete
  • drifted

이 카테고리들은 그래프 내 심볼에 첨부된 구조화된 어노테이션의 품질과 최신성에 관한 것입니다.

범위 수정자 (Scope Modifiers)

린트 결과는 그래프 범위 및 경로 필터링을 통해 좁힐 수 있습니다.

네임스페이스 범위 (Namespace scope)

린트가 네임스페이스와 함께 실행되는 경우, 노드 조회 및 @see 해석은 해당 네임스페이스 범위로 제한됩니다.

실질적인 영향:

  • dead-ref 체크는 동일한 네임스페이스 범위 내에서 참조된 심볼만 확인합니다.
  • 파일 및 심볼 카테고리 수는 전체 저장소 린트와 네임스페이스 범위 린트 간에 다를 수 있습니다.

제외 필터 (Exclude filters)

제외된 파일 경로는 그래프 기반 소스 파일 및 심볼 후보를 수집할 때 건너뜁니다.

실질적인 영향:

  • 제외된 파일은 missing, stale 또는 어노테이션 관련 카테고리에 영향을 주지 않습니다.
  • 생성된 코드나 의도적으로 무시된 경로는 린트 규칙 및 설정을 통해 필터링할 수 있습니다.

필드 매핑 (Field Mapping)

사용자에게 표시되는 카테고리 라벨은 LintReport 필드에 다음과 같이 매핑됩니다:

카테고리 라벨 LintReport 필드
orphan Orphans
missing Missing
stale Stale
unannotated Unannotated
contradiction Contradictions
dead-ref DeadRefs
incomplete Incomplete
drifted Drifted

규칙 매칭과 generated lint state에서는 drift 별칭도 사용할 수 있습니다. 사용자에게 보이는 카테고리 이름은 계속 drifted입니다.

구현을 읽고 계신다면, 정확한 로직은 internal/docs/lint.go에 있습니다.

실제 결과 해석하기

missing 또는 stale 수치가 높은 경우

일반적으로 최근에 문서 생성을 실행하지 않았거나, 문서 생성 후 코드가 변경되었음을 의미합니다.

일반적인 대응:

  1. 그래프 빌드 또는 업데이트
  2. 문서 재생성
  3. 린트 재실행

unannotated 수치가 높은 경우

코드는 존재하지만 구조화된 의도 메타데이터가 여전히 부족함을 의미합니다.

일반적인 대응:

  1. 가치가 높은 심볼부터 우선순위를 정합니다.
  2. 일관되게 어노테이션을 추가합니다.
  3. 린트를 재실행하여 커버리지 개선을 확인합니다.

incomplete가 0이 아닌 경우

주석은 추가되었지만 @intent를 잊어버린 경우가 많습니다.

일반적인 대응:

  1. 나열된 심볼을 찾습니다.
  2. @intent를 추가합니다.
  3. 린트를 재실행합니다.

contradiction, dead-ref, 또는 drifted가 나타나는 경우

이러한 수치는 오래되었거나 깨진 시맨틱 메타데이터를 나타내므로 수동 검토가 필요합니다.

일반적인 대응:

  1. 심볼을 조사합니다.
  2. 오래된 태그를 업데이트하거나 제거합니다.
  3. 린트를 재실행합니다.

정책 및 억제 (Suppression and Policy)

카테고리별 규칙은 .ccg.yaml에서 설정할 수 있습니다.

예시:

rules:
  - pattern: "pkg/store/.*"
    category: unannotated
    action: ignore

action: ignore 규칙은 매칭되는 결과를 억제하며, --strict 모드에서도 동일하게 적용됩니다. 패턴은 정확한 정규화 이름 또는 정규식일 수 있습니다.

전체 규칙 레퍼런스는 CLI 레퍼런스를 참조하십시오.

CI 및 Strict 모드

ccg lint --strict는 CI 또는 pre-commit 강제 적용을 위한 것입니다.

일반적인 용도:

  • 문서 퇴보 시 CI 실패 처리
  • 중요한 린트 카테고리가 정책을 초과할 때 커밋 차단
  • 시간이 지남에 따라 생성된 문서와 어노테이션이 동기화되도록 유지

참고 항목