diff --git a/docs/README.md b/docs/README.md index 8535108d..effd1865 100644 --- a/docs/README.md +++ b/docs/README.md @@ -181,7 +181,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | | `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | -| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 | +| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | diff --git a/scripts/check-docs.py b/scripts/check-docs.py index f2ab90fc..759254bd 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -15,6 +15,9 @@ registry에 있다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. + Spring Boot 버전은 이름 바로 뒤(「Spring Boot」·「Boot」 뒤의 세 자리 버전)만이 아니라 `Spring Boot` + 칸이 있는 표 행의 세 자리 버전과, 정본(src/gradle/libs.versions.toml의 springBoot)과 같은 + 버전 문자열(굵은 글씨·표 칸·코드 안 포함)도 잡는다. map docs/README.md의 문서 지도가 지금 있는 문서 폴더를 모두 덮는다. 지도는 표의 첫 칸에 적은 `폴더/`다. docs/ 바로 아래 폴더가 대상이고, 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다. @@ -128,11 +131,20 @@ GRADLE_PATH = re.compile(r"^:[A-Za-z][\w-]*(?::[A-Za-z][\w-]*)+$") HISTORY_QUOTE = re.compile(r"^\s*>\s*(?:\*\*)?이력") # --- 복사한 숫자 +SPRING_BOOT = "Spring Boot 버전" COPIED_NUMBERS = [ - ("Spring Boot 버전", re.compile(r"Spring Boot \d+\.\d+\.\d+")), + (SPRING_BOOT, re.compile(r"\b(?:Spring\s+)?Boot\s+v?\d+\.\d+\.\d+")), ("leaf 개수", re.compile(r"\b\d+\s*개의?\s*leaf|\bleaf\s*\d+\s*개|\b\d+\s+(?:registered\s+)?lea(?:f|ves)\b", re.I)), ] +# 이름 옆이 아닌 Spring Boot 버전: 「기준은 **4.0.8**」, 「| Spring Boot | 4.0.0 |」. +CATALOG_FILE = "src/gradle/libs.versions.toml" +CATALOG_SPRING_BOOT = re.compile(r'^springBoot\s*=\s*"([^"]+)"', re.M) +# 세 자리 버전. 앞이 낱말·점·§이면 다른 수의 일부다(1.2.3.4, RFC 절 번호 §6.5.2). +VERSION = re.compile(r"(? list[Problem]: return problems +def catalog_spring_boot(root: Path) -> re.Pattern[str] | None: + """정본의 Spring Boot 버전과 같은 버전 문자열. 카탈로그가 없으면 None(이름 옆과 표 칸만 본다).""" + catalog = root / CATALOG_FILE + found = CATALOG_SPRING_BOOT.search(catalog.read_text(encoding="utf-8")) if catalog.is_file() else None + if not found: + return None + return re.compile(r"(? list[re.Match[str]]: + """`Spring Boot` 칸(굵은 글씨·코드·링크를 벗긴 칸 전체)이 있는 표 행의 세 자리 버전.""" + if not line.lstrip().startswith("|"): + return [] + cells = [CELL_MARKUP.sub("", LINK_TEXT.sub(r"\1", cell)).strip() for cell in line.strip().strip("|").split("|")] + if not any(SPRING_BOOT_CELL.match(cell) for cell in cells): + return [] + return list(VERSION.finditer(line)) + + def check_number(root: Path, files: list[str]) -> list[Problem]: problems = [] + current = catalog_spring_boot(root) for path in files: if not checked_for_drift(path): continue seen: set[str] = set() for number, line in enumerate((root / path).read_text(encoding="utf-8").split("\n"), start=1): - for label, pattern in COPIED_NUMBERS: - for match in pattern.finditer(line): - text = match.group(0) - if text not in seen: - seen.add(text) - problems.append(Problem("number", path, text, - f"{label}를 복사했다: {text!r}. 정본을 가리킨다", number)) + found = [(label, match) for label, pattern in COPIED_NUMBERS for match in pattern.finditer(line)] + named = [match.span() for _, match in found] + # 이름 옆 복사(「Spring Boot 4.0.8」)는 한 번만 센다: 그 안의 버전을 표·정본 규칙이 다시 세지 않는다. + others = spring_boot_cell_versions(line) + (list(current.finditer(line)) if current else []) + found += [(SPRING_BOOT, match) for match in others + if not any(start <= match.start() and match.end() <= end for start, end in named)] + for label, match in found: + text = match.group(0) + if text not in seen: + seen.add(text) + problems.append(Problem("number", path, text, + f"{label}를 복사했다: {text!r}. 정본을 가리킨다", number)) return problems diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index c35cceb9..b36c630d 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -267,6 +267,43 @@ class NumberTest(RepositoryTestCase): def test_a_word_count_of_leaves_passes(self) -> None: self.assertEqual(self.errors_for("leaf 하나를 고른다.\n"), []) + def with_catalog(self, version: str = "4.0.8") -> None: + self.repo.write(check_docs.CATALOG_FILE, f'[versions]\nspringBoot = "{version}"\nother = "1.2.3"\n') + + def test_boot_without_spring_fails(self) -> None: + self.assertFailsWith(self.errors_for("BOM은 Boot 4.0.0이 푼다.\n"), "'Boot 4.0.0'") + + def test_a_bold_copy_of_the_catalog_version_fails(self) -> None: + self.with_catalog() + self.assertFailsWith(self.errors_for("이 저장소의 기준은 **4.0.8**이다.\n"), "'4.0.8'") + + def test_the_catalog_version_in_code_fails(self) -> None: + self.with_catalog() + self.assertFailsWith(self.errors_for("`org.springframework.boot:spring-boot:4.0.8`을 쓴다.\n"), "'4.0.8'") + + def test_a_version_in_a_spring_boot_table_row_fails(self) -> None: + self.with_catalog() + errors = self.errors_for("| 의존성 | 버전 |\n| --- | --- |\n| **Spring Boot** | 4.0.0 (BOM이 관리) |\n") + self.assertFailsWith(errors, "'4.0.0'") + + def test_a_copy_next_to_the_name_is_reported_once(self) -> None: + self.with_catalog() + errors = self.errors_for("| Spring Boot | Spring Boot 4.0.8 |\n") + self.assertEqual(len(errors), 1, errors) + self.assertFailsWith(errors, "'Spring Boot 4.0.8'") + + def test_another_library_in_a_table_row_passes(self) -> None: + self.with_catalog() + self.assertEqual(self.errors_for("| Hibernate | **7.1.8.Final** |\n| Spring Boot | 카탈로그 |\n"), []) + + def test_numbers_that_only_contain_the_catalog_version_pass(self) -> None: + self.with_catalog() + self.assertEqual(self.errors_for("RFC 9113 §4.0.8, 버전 14.0.8, 4.0.80, 4.0.8.1, 다른 값 1.2.3.\n"), []) + + def test_a_spring_boot_cell_name_must_be_the_whole_cell(self) -> None: + self.with_catalog() + self.assertEqual(self.errors_for("| Spring Boot BOM이 푸는 Hibernate | 7.1.8.Final |\n"), []) + class ScopeTest(RepositoryTestCase): def test_markdown_under_a_source_set_resources_folder_is_not_a_document(self) -> None: