Documentation
¶
Overview ¶
Package lint는 위키를 순회하며 스키마와 링크 무결성을 검사한다.
규칙 ID는 점 표기 소문자이고 ADR 0005의 parity 비교 키가 되므로 한 번 정하면 바꾸지 않는다는 전제로 지었다.
Index ¶
- func Linkable(w walk.Doc) bool
- func LinkableSlugs(walked []walk.Doc, skipRel, skipSlug string) map[string]bool
- func LinkableTargets(walked []walk.Doc, self string) int
- func OrphanCount(res Result) int
- func RequiredFields(stage string, cfg config.Config) []string
- func ResolvedLinks(links, targets map[string]bool) int
- type GateResult
- type Options
- type Result
- type Rule
- type Severity
- type Summary
- type Violation
- type WikiFinding
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Linkable ¶
Linkable은 문서가 게이트의 유효한 연결 대상인지를 판정한다. inbox 단계 문서는 promote 되면 파일이 옮겨지며 슬러그가 날짜 접두사가 떨어진 형태로 바뀌어 가리키던 링크가 깨지므로 뺀다(ADR 0022). 단계를 읽을 수 없는 문서(파싱 실패, 프론트매터 없음, 필드 없음)도 그 자리에 남으리라 보장할 수 없어 뺀다. 색인(root_files)은 승급 대상이 아니라 그 자리에 남으므로 포함한다. EvaluateGate 를 부르는 모든 곳이 이 판정을 공유해야 대상 수가 갈라지지 않는다.
func LinkableSlugs ¶
LinkableSlugs는 유효 연결 대상이 되는 문서의 슬러그 집합을 낸다. skipRel 은 판정 대상 문서의 순회 경로이고 skipSlug 는 그 문서가 갖게 될 슬러그다. 아직 파일이 없는 new 는 슬러그로만 자기를 뺀다. 위키링크 해석과 같은 기준이어야 하므로 슬러그는 날짜 접두사를 포함한 파일 이름 그대로다.
func LinkableTargets ¶
LinkableTargets는 판정 대상 문서 self 를 뺀 유효 연결 대상 수를 센다.
func OrphanCount ¶
OrphanCount는 lint 결과에서 고아 문서 수를 낸다. status 같은 다른 지표가 graph.orphan 과 같은 판정을 쓰게 하는 통로다. 고아의 정의는 graph.orphan 규칙이 단일 진실원이므로 여기서 다시 세지 않는다.
func RequiredFields ¶
RequiredFields는 단계별 필수 필드를 반환한다. upstream 계약 meta/frontmatter-schema.md의 단계별 필수 정의에서 왔고, 꺼진 속성의 필수성은 사라진다.
func ResolvedLinks ¶
ResolvedLinks는 문서가 가진 링크 슬러그 중 실제로 이어지는 것만 센다. 위키에 없는 슬러그와 링크 대상이 못 되는 문서(inbox 단계)를 뺀다. **게이트가 해석되지 않는 슬러그를 세면 아무것도 막지 못한다.** 없는 슬러그 둘을 적으면 아무 데도 안 이어진 문서가 context 로 올라간다([ADR 0054]).
Types ¶
type GateResult ¶
type GateResult struct {
Passed bool // 게이트를 통과했는가. 유예와 게이트 오프도 통과다
Deferred bool // 링크 대상이 부족해 게이트를 적용하지 않았는가 (ADR 0021)
Links int // 그 문서의 고유 위키링크 수
Targets int // 자신을 뺀 링크 가능 문서 수
Min int // min_wikilinks
}
GateResult는 승급 게이트 판정 결과다.
func EvaluateGate ¶
func EvaluateGate(links, targets, minWikilinks int) GateResult
EvaluateGate는 문서 하나의 승급 게이트를 판정한다. links 는 그 문서의 고유 위키링크 수, targets 는 자신을 뺀 링크 가능 문서 수다. lint, promote, new 가 같은 판정을 써야 커맨드로 통과한 문서를 lint 가 거절하지 않는다. min_wikilinks 가 0 이면 게이트 자체가 꺼져 있어 유예 표시도 하지 않는다.
type Options ¶
type Options struct {
IncludeInbox bool
}
Options는 lint 의 판정 범위다. 기본 범위는 inbox 디렉토리 문서의 스키마 판정을 뺀 나머지다(ADR 0070). IncludeInbox 를 주면 inbox 문서의 스키마 판정을 함께 한다. 순회와 링크 그래프, 게이트의 링크 대상 집계는 어느 쪽이든 inbox 를 그대로 담는다.
type Result ¶
type Result struct {
Violations []Violation `json:"violations"`
WikiFindings []WikiFinding `json:"wikiFindings"`
Summary Summary `json:"summary"`
}
Result는 lint 실행 결과다.
func Run ¶
Run은 위키 루트를 순회해 위반 목록을 반환한다. 순회와 파싱은 internal/walk 가 담당한다. 순회는 경로 기준 정렬, 파일 안은 줄 번호와 규칙 ID 기준 정렬이므로 같은 위키에 대한 결과는 항상 바이트까지 같다.
func (Result) HasBlocking ¶
HasBlocking은 승급을 막는 위반(error 또는 reject)이 있는지를 반환한다.
type Rule ¶
type Rule struct {
ID string `json:"id"`
// SeverityID와 DescID는 카탈로그 메시지 ID 다. JSON 에는 푼 값을 낸다.
SeverityID string `json:"-"`
DescID string `json:"-"`
}
Rule은 lint 규칙 하나의 메타데이터다. ID 는 동등성 검증의 정규화 표가 짝짓는 문자열 그대로다. 등급과 설명은 메시지 ID 로 담고 읽을 때 푼다. 규칙 목록은 패키지 초기화 시점에 만들어지는데 그때는 아직 출력 언어가 정해지기 전이라, 여기서 문자열로 굳히면 rules show 가 늘 기본 언어로 나온다. ADR 0049.
func Rules ¶
func Rules() []Rule
Rules는 이 바이너리가 검사하는 규칙 전부를 반환한다. 규칙 메타데이터의 진실원은 이 목록 하나다. rules show 가 여기서 읽고 계획된 eject 도 여기서 읽는다(ADR 0039).
func (Rule) MarshalJSON ¶
MarshalJSON은 푼 문자열을 낸다. --json 소비자는 ID 가 아니라 문장을 받는다.
type Summary ¶
type Summary struct {
Files int `json:"files"`
Error int `json:"error"`
Warn int `json:"warn"`
Reject int `json:"reject"`
// SkippedInbox는 기본 범위에서 판정에서 뺀 inbox 문서 수다.
// IncludeInbox 를 줬으면 0 이다.
SkippedInbox int `json:"skippedInbox"`
}
Summary는 등급별 위반 수와 검사한 파일 수다.
type Violation ¶
type Violation struct {
Rule string `json:"rule"`
Severity Severity `json:"severity"`
Path string `json:"path"`
Line int `json:"line"`
Message string `json:"message"`
Fix string `json:"fix"`
}
Violation은 위반 하나다. 모든 위반은 경로와 줄, 무엇이 잘못됐는지, 어떻게 고치는지를 담는다. ADR 0009의 메시지 품질 요구다.
type WikiFinding ¶
type WikiFinding struct {
Rule string `json:"rule"`
Severity Severity `json:"severity"`
Topic string `json:"topic"`
Percent int `json:"percent"`
Threshold int `json:"threshold"`
Total int `json:"total"`
Paths []string `json:"paths"`
Fix string `json:"fix"`
}
WikiFinding은 파일이 아니라 위키 전체의 통계로 판정되는 진단이다. 파일 위반 배열에 섞지 않고 별도로 보고한다. 대표 규칙은 wiki.broad-topic이다.
Source Files