From 845ee89054301e61abe294f43047c0227c72e8ca Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 10 Sep 2026 15:47:54 +0900 Subject: [PATCH] =?UTF-8?q?feat(scripts):=20=EB=86=93=EC=B9=9C=208?= =?UTF-8?q?=EA=B1=B4=EC=9D=84=20=EC=BD=94=EB=93=9C=EB=A1=9C=20=EB=A7=89?= =?UTF-8?q?=EA=B1=B0=EB=82=98=20=EA=B2=80=ED=86=A0=EB=A1=9C=20=EB=B3=B4?= =?UTF-8?q?=EB=82=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 먼저 쟀다. 경고를 일괄 차단으로 올리면 채택된 편집 9건이 막힌다 — V-004 에서 고친 바로 그 9건이다. 그래서 경고는 검토로 보내고 차단은 검토가 판정할 때 일어나게 뒀다. 코드로 막은 것 셋. code[] 리비전 — check_evidence 는 리비전이 있는지만 보고 인용한 코드가 그 리비전에서 왔는지는 안 본다. 이 배치에서 실제로 났고 사람이 손으로 잡았다. 한글 수사와 그 경계 — 「다섯 개 → 여섯 개」는 결정적이다. 앵커 검사기의 오탐을 0 으로 만드는 데 시간의 절반이 갔다. 처음 판이 저장소 전체에서 401건을 냈고 전부 오탐이었다. code[] 는 한 모양이 아니다 — 심볼, 축약 경로, 줄 범위, 호스트 절대 경로, 설정 키가 섞여 있다. 축약 경로를 「없다」로 세면 있는 코드를 없다고 하는 것이고 그게 채택된 편집 아홉 건을 막았던 실패와 같은 모양이다. 판정할 수 있는 것만 판정하고 못 보는 것은 세어서 낸다. 검토로 보낸 것 다섯. D2 는 아무 계수도 안 움직이던 자리였다 — 수치도 인용도 없이 산문만 더하면 보호 구간 비교에 잡힐 것이 없다. 1인칭 표지가 늘어난 것만 보고 그 문장을 짚어 준다. 판정이 아니라 라우팅이다. 만들다 버그를 찾았다. 경고가 인용하는 문장이 파일 첫 문단에서 한 글자씩 깎이고 있었다. rfind 가 -1 을 낼 때 +2 를 해서 1 이 됐다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Q4vKjQo9KKBBokzxqXLCfk --- scripts/check-code-anchors.py | 172 +++++++++++++++++++++++++++++ scripts/check-preservation.py | 38 ++++++- scripts/tests/test_code_anchors.py | 56 ++++++++++ scripts/tests/test_preservation.py | 52 +++++++++ 4 files changed, 317 insertions(+), 1 deletion(-) create mode 100644 scripts/check-code-anchors.py create mode 100644 scripts/tests/test_code_anchors.py diff --git a/scripts/check-code-anchors.py b/scripts/check-code-anchors.py new file mode 100644 index 0000000..c7ee89b --- /dev/null +++ b/scripts/check-code-anchors.py @@ -0,0 +1,172 @@ +#!/usr/bin/env python3 +"""기록이 가리키는 코드가 **그 리비전에** 실재하는지 본다. + +`check_evidence.mjs --repo` 는 `sourceRepository.revision` 이 그 저장소에 **있는지**만 본다 +(`:126`, `git cat-file -e ^{commit}`). **인용한 코드가 그 리비전에서 왔는지는 안 본다.** +그래서 「작업 트리에는 있고 지정 커밋에는 없는 파일」을 인용해도 통과한다 — 체크아웃을 그냥 +읽는 분석이 자동으로 만드는 결함이다. + +이 배치에서 실제로 났다. 기록이 `scripts/capture-evidence.py:72` 를 가리켰는데 그 파일은 +그 배치가 **만든** 것이라 고정 리비전에 없었고, 관문은 전부 통과했다. 사람이 `git cat-file` +을 손으로 쳐서 잡았다. **사람이 한 번 잡은 것과 다음에도 잡히는 것은 다르다.** + +**결정적으로 판정 가능하다** — 그 커밋에 그 경로가 있는지, 줄 번호가 파일 길이 안인지. +그래서 코드로 막는다. 내용이 맞는 인용인지는 보지 않는다. 그것은 사람이 읽을 일이다. + + python3 scripts/check-code-anchors.py <프로젝트> +""" +from __future__ import annotations + +import argparse +import glob +import os +import re +import subprocess +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +sys.path.insert(0, os.path.join(ROOT, "scripts")) +import techlog # noqa: E402 + +ANCHOR = re.compile(r"^(?P[^:]+?)(?::(?P\d+))?$") + + +def _undecidable(rel: str) -> str | None: + """이 앵커를 리비전과 대조할 수 있나. 못 하면 그 사유. + + 저장소의 `code[]` 는 한 모양이 아니다 — 심볼(`FeedPersistenceIT.l2Eager…`), + 축약 경로(`` `.../CaSkeletonApplication.java` ``), 줄 범위(`:141,159-184`), + 호스트 절대 경로(`/etc/letsencrypt/…`), 설정 키(`refresh:disabled`) 가 섞여 있다. + + **판정할 수 있는 것만 판정한다.** 축약 경로를 「그 리비전에 없다」로 세면 있는 코드를 + 없다고 하는 것이고, 그것이 이 배치에서 채택된 편집 아홉 건을 막았던 실패와 같은 모양이다. + 못 보는 것은 세어서 낸다 — 조용히 건너뛰면 「전부 맞다」가 「본 것만 맞다」를 가린다. + """ + if not LOOKS_LIKE_PATH.search(rel): + return "심볼이거나 경로가 아니다" + if "/" not in rel: + # 이름만 있는 것은 저장소 어디에 있는지 말하지 않는다. 뿌리에 있다고 가정하면 + # 있는 파일을 없다고 한다 — TechLog 의 앵커 여덟이 그 모양이었다 + return "폴더 없이 파일 이름만 있다" + if "..." in rel or "…" in rel: + return "축약된 경로다" + if rel.startswith("/") or rel.startswith("~"): + return "저장소 밖의 절대 경로다" + if any(ch in rel for ch in " `\"'"): + return "따옴표·백틱·공백이 섞여 있다" + if rel.endswith("/"): + return "폴더를 가리킨다" + return None + +# 계약의 `code[]` 는 `:` 이다. **심볼 앵커는 파일 경로가 아니다** — +# `FeedPersistenceIT.l2EagerToOneFires…` 같은 것을 경로로 읽으면 있는 코드를 없다고 한다. +# 경로로 보이는 것만 대조하고 나머지는 「못 대조한 앵커」로 센다. 세지 않고 넘기면 +# 「전부 맞다」가 「본 것만 맞다」를 가린다 +LOOKS_LIKE_PATH = re.compile(r"[/\\]|\.(?:java|kt|py|ts|tsx|js|mjs|go|rs|sql|ya?ml|json|xml|" + r"gradle|properties|md|sh|toml|cfg|conf)$") + + +def _git(repo: str, *args: str) -> tuple[int, str]: + try: + p = subprocess.run(["git", "-C", repo, *args], + capture_output=True, text=True, timeout=30) + except (OSError, subprocess.SubprocessError) as e: + return 127, str(e) + return p.returncode, p.stdout + + +def verify(project: str) -> tuple[techlog.Report, str | None]: + rep = techlog.Report(project) + base = os.path.join(ROOT, "docs", project) + index_path = os.path.join(base, "tech-log-studio", "tech-log-tree.json") + index = techlog.load_index(index_path) + if index is None: + return rep, "tech-log-tree.json 이 없다" + + repos = index.get("sourceRepository") or {} + repos = repos if isinstance(repos, list) else [repos] + checked = skipped = 0 + for _topic, _kind, node in techlog.nodes(index): + anchors = node.get("code") or [] + if not anchors: + continue + for r in repos: + path, rev = r.get("path"), r.get("revision") + if not path or not os.path.isdir(path): + rep.warn("저장소가 이 기계에 없다", f"{r.get('name') or project}: {path}") + skipped += len(anchors) + continue + if not rev: + rep.warn("리비전이 없어 대조하지 못한다", + f"{r.get('name') or project} — sourceRepository.revision 이 비었다") + skipped += len(anchors) + continue + for anchor in anchors: + m = ANCHOR.match(anchor.strip()) + if not m: + skipped += 1 + rep.warn("대조하지 못한 앵커 — 형식을 못 읽겠다", anchor[:70]) + continue + rel, line = m.group("path"), m.group("line") + why = _undecidable(rel) + if why: + skipped += 1 + rep.warn(f"대조하지 못한 앵커 — {why}", f"{node.get('slug')} — {anchor[:70]}") + continue + checked += 1 + code, blob = _git(path, "cat-file", "-e", f"{rev}:{rel}") + if code != 0: + rep.error("인용한 코드가 그 리비전에 없다", + f"{node.get('slug')} — {rel} @ {rev[:8]}") + continue + if line: + code, text = _git(path, "show", f"{rev}:{rel}") + if code == 0 and int(line) > len(text.splitlines()): + rep.error("인용한 줄이 그 리비전의 파일 길이를 넘는다", + f"{node.get('slug')} — {rel}:{line} @ {rev[:8]} " + f"(그 커밋에서 {len(text.splitlines())}줄)") + rep.facts["대조한 앵커"] = checked + if skipped: + rep.facts["못 대조한 앵커"] = skipped + return rep, None + + +def main() -> int: + ap = argparse.ArgumentParser(description="인용한 코드가 그 리비전에 실재하는지 본다.") + ap.add_argument("projects", nargs="*") + ap.add_argument("--samples", type=int, default=3) + args = ap.parse_args() + + projects = args.projects or sorted( + os.path.basename(os.path.dirname(p)) + for p in glob.glob(os.path.join(ROOT, "docs/*/tech-log-studio")) + if not os.path.basename(os.path.dirname(p)).startswith("_")) + missing = [p for p in projects if not os.path.isdir(os.path.join(ROOT, "docs", p))] + if missing: + print(f"대상이 성립하지 않는다 — 그런 프로젝트가 없다: {', '.join(missing)}", + file=sys.stderr) + return 2 + + reports = [] + for p in projects: + rep, why = verify(p) + if why: + print(f"대상이 성립하지 않는다 — {p}: {why}", file=sys.stderr) + return 2 + reports.append(rep) + + for rep in reports: + facts = " · ".join(f"{k}={v}" for k, v in rep.facts.items()) or "앵커 없음" + print(f"\n[{rep.project}] {facts}") + for label, bucket, mark in (("error", rep.errors, "✗"), ("warn", rep.warns, "!")): + for rule, details in sorted(bucket.items(), key=lambda kv: -len(kv[1])): + print(f" {mark} {label} {len(details):>4} {rule}") + for d in details[:args.samples]: + print(f" · {d}") + e = sum(r.error_count for r in reports) + print(f"\nCODE ANCHORS: {'FAIL' if e else 'PASS'} — 프로젝트 {len(reports)} · error {e}") + return 1 if e else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/check-preservation.py b/scripts/check-preservation.py index a238575..8f7ac8f 100644 --- a/scripts/check-preservation.py +++ b/scripts/check-preservation.py @@ -41,6 +41,13 @@ EXTRACTORS: dict[str, re.Pattern[str]] = { # `500행`·`5개다` 처럼 조사나 명사가 붙은 자리에서 보호가 통째로 풀린다. 한국어에서 # 숫자는 거의 항상 뭔가가 바로 붙으므로, 보호가 가장 필요한 자리에서 가장 안 걸렸다. # 버전 문자열(`1.1.0`)은 `.` 이 막아 여전히 토큰이 안 나온다 — 그것은 인라인 코드로 견준다 + # 한글 수사. 아라비아 숫자만 보면 「다섯 개 → 여섯 개」가 안 보인다. 실제로 이 배치에서 + # 한 번 놓쳤고 사람이 잡았다. 세는 말(개·건·장·줄…)이 뒤따르는 자리만 본다 — + # 「하나」·「둘」은 「하나뿐」·「둘 다」처럼 수가 아닌 쓰임이 많다 + "한글수사": re.compile( + r"(? str: i = text.find(needle) if i < 0: return "" - start = max(text.rfind("\n\n", 0, i) + 2, 0) + # rfind 가 -1 을 낼 때 +2 를 하면 1 이 되어 첫 글자를 잘라먹는다. + # 파일 첫 문단의 경고가 전부 한 글자씩 깎여 나갔다 + at = text.rfind("\n\n", 0, i) + start = 0 if at < 0 else at + 2 stop = text.find("\n\n", i) chunk = text[start:stop if stop > 0 else len(text)] return re.sub(r"\s+", " ", chunk).strip()[:200] @@ -120,6 +145,17 @@ def compare(before: str, after: str) -> dict: "note": "절이 통째로 없어졌다. 덜어 낸 것인지 한계를 지운 것인지는 " "근거를 읽어야 안다"}) + # 자료에 없는 1인칭이 들어왔나. 늘어난 것만 본다 — 지우는 것은 이 규범에서 안전한 쪽이다 + for mark in VOICE_MARKS: + gained = after.count(mark) - before.count(mark) + if gained > 0: + warnings.append({ + "kind": "1인칭", "change": "새로생김", "count": gained, "value": mark, + "sentence": _sentence_of(after, mark), + "note": "자료에 이 사람의 행동·판단이 남아 있는지 상류에서 확인한다. " + "없으면 지어낸 것이고, 있으면 정상이다 — 검사기가 가릴 수 없다", + }) + hb, ha = _hedges(before), _hedges(after) hedge = [] for w in sorted(hb - ha): diff --git a/scripts/tests/test_code_anchors.py b/scripts/tests/test_code_anchors.py new file mode 100644 index 0000000..c797be9 --- /dev/null +++ b/scripts/tests/test_code_anchors.py @@ -0,0 +1,56 @@ +"""인용한 코드가 그 리비전에 실재하는지 보는 검사기. + +`check_evidence.mjs --repo` 는 리비전이 **있는지**만 본다. 인용한 코드가 **그 리비전에서 +왔는지**는 안 본다. 이 배치에서 실제로 그 결함이 났고 사람이 손으로 잡았다. +""" +import importlib.util +import os +import subprocess +import unittest + +ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +TOOL = os.path.join(ROOT, "scripts", "check-code-anchors.py") +_spec = importlib.util.spec_from_file_location("check_code_anchors", TOOL) +ca = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(ca) + + +class UndecidableTest(unittest.TestCase): + """판정할 수 있는 것만 판정한다. 못 보는 것은 세어서 낸다.""" + + def test_a_plain_repo_path_is_decidable(self): + self.assertIsNone(ca._undecidable("scripts/audit-records.py")) + + def test_shapes_this_checker_cannot_decide(self): + cases = { + "FeedPersistenceIT.l2EagerToOneFires": "심볼", + "`.../CaSkeletonApplication.java`": "축약 또는 백틱", + "/etc/letsencrypt/renewal-hooks/": "저장소 밖 절대 경로", + "tech-log-serving-contract.json": "폴더 없이 이름만", + "renewal-hooks/deploy/": "폴더를 가리킨다", + } + for anchor, why in cases.items(): + with self.subTest(why=why): + self.assertIsNotNone(ca._undecidable(anchor), f"{anchor} 를 판정하려 든다") + + +class SweepTest(unittest.TestCase): + def _cli(self, *args): + return subprocess.run(["python3", TOOL, *args], cwd=ROOT, + capture_output=True, text=True) + + def test_every_project_in_this_repository_passes(self): + """대조군. 지금 저장소의 앵커에 하나라도 걸리면 정책이 과하다. + + 축약 경로를 「없다」로 세면 있는 코드를 없다고 하는 것이고, 그것이 이 배치에서 + 채택된 편집 아홉 건을 막았던 실패와 같은 모양이다. + """ + p = self._cli("--samples", "1") + self.assertEqual(0, p.returncode, p.stdout + p.stderr) + + def test_a_missing_project_is_not_reported_as_clean(self): + self.assertEqual(2, self._cli("nosuchxyz").returncode) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_preservation.py b/scripts/tests/test_preservation.py index ffb6dc3..85206a9 100644 --- a/scripts/tests/test_preservation.py +++ b/scripts/tests/test_preservation.py @@ -107,3 +107,55 @@ class PreservationTest(unittest.TestCase): if __name__ == "__main__": unittest.main() + + +class KoreanNumeralTest(unittest.TestCase): + """한글 수사. 아라비아 숫자만 보면 「다섯 개 → 여섯 개」가 안 보인다. + + 이 배치에서 실제로 한 번 놓쳤고 사람이 잡았다. + """ + + def test_a_changed_korean_numeral_is_an_error(self): + for before, after in (("증거 다섯 개", "증거 여섯 개"), + ("문장 세 줄", "문장 네 줄"), + ("열두 건", "열세 건")): + with self.subTest(before=before): + self.assertTrue(cp.compare(before, after)["errors"]) + + def test_counting_words_that_are_not_numbers_are_left_alone(self): + """대조군. 「하나뿐」·「둘 다」는 수가 아니다. 세면 정상을 막는다.""" + for text in ("하나뿐이다", "둘 다 맞다", "한편으로는 그렇다"): + with self.subTest(text=text): + self.assertEqual([], cp.compare(text, text)["errors"]) + + +class UnsourcedVoiceTest(unittest.TestCase): + """자료에 없는 1인칭. 보호 구간 비교로는 원리적으로 안 보이던 자리다.""" + + BEFORE = "피드 아이템을 엔티티로 조회한 뒤 메모리에서 DTO로 옮기는 코드다." + + def test_added_first_person_experience_is_surfaced_as_a_warning(self): + after = ("처음에는 조인 한 번으로 가져올 거라고 믿었다. " + "팀에서는 다른 의견이 많았지만 나는 조회 방식을 먼저 보자고 했다.\n\n" + + self.BEFORE) + res = cp.compare(self.BEFORE, after) + self.assertEqual([], res["errors"], "판정이 아니라 라우팅이다") + marks = {w["value"] for w in res["warnings"] if w["kind"] == "1인칭"} + self.assertTrue({"처음에는", "믿었다", "팀에서는"} <= marks, marks) + + def test_the_warning_points_at_the_sentence(self): + after = "처음에는 그렇게 믿었다.\n\n" + self.BEFORE + w = next(x for x in cp.compare(self.BEFORE, after)["warnings"] + if x["kind"] == "1인칭") + self.assertIn("처음에는", w["sentence"]) + + def test_removing_first_person_is_not_reported(self): + """지우는 것은 이 규범에서 안전한 쪽이다.""" + after = "처음에는 그렇게 믿었다. " + self.BEFORE + self.assertEqual([], [w for w in cp.compare(after, self.BEFORE)["warnings"] + if w["kind"] == "1인칭"]) + + def test_an_ordinary_rewrite_raises_no_voice_warning(self): + """대조군.""" + self.assertEqual([], [w for w in cp.compare(self.BEFORE, self.BEFORE)["warnings"] + if w["kind"] == "1인칭"])