pr / done (pull_request) Canceled after 0s
상대 링크 검사가 둘이고 규칙이 갈라졌다. check-docs.py의 link는 git이 아는 경로만 받고 저장소 밖(..)은 실패로 본다. check-work-docs.py는 디스크를 exists()로 봐서 git이 모르는 파일, git mv가 남긴 빈 폴더, 저장소 밖 형제 clone(../design-docs/…)도 통과시킨다. 기본 실행은 같은 PR 단계에서 check-docs.py link가 다시 보지만, lychee 없는 기계에서 손으로 쓰는 --links는 약한 쪽의 답만 준다. check-docs.py의 check_link 몸통을 broken_relative_links(known, path, text)로 뽑고(규칙은 그대로) check-work-docs.py가 그 모듈을 불러 기본 실행과 --links 모두 같은 함수를 쓴다. 그래서 링크 규칙을 한 곳에서 고친다. --links에 저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout .claude/worktrees/…, 빌드 출력)을 주면 그 git으로는 대조할 수 없으므로 rc=2로 거절한다. 버린 안: check-work-docs.py에 git 대조를 따로 구현 — 규칙이 다시 둘이 된다. 위험: check-work-docs.py 기본 실행도 이제 코드 블록·인라인 코드·「이력」 인용 블록 안의 링크를 보지 않는다(check-docs.py link와 같다). 지금 트리에서 깨진 링크 0은 그대로다. 옛 --links가 깨짐으로 본 인라인 코드 속 링크 표기 (docs/upgrade/2026-11-round9-followups.md:31)는 이제 링크로 보지 않는다. 시험 fixture가 git 저장소가 됐다(known_paths가 git ls-files를 쓴다). 검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py' OK(129), python3 scripts/check-work-docs.py rc=0, python3 scripts/check-work-docs.py --links docs README.md rc=0(536 링크, 깨짐 0), python3 scripts/check-docs.py rc=0. Refs: REV-BE-0017 BREAKING CHANGE: check-work-docs.py --links가 저장소 루트를 넘는 링크와 git이 모르는 곳을 가리키는 링크를 깨짐(rc=1)으로 보고, 저장소 밖이나 git이 모르는 파일을 받으면 rc=2로 거절한다. 그 명령을 스크립트로 쓰는 파생 서비스는 docs/upgrade/2026-11-docs-check-references.md 5번을 본다.
203 lines
10 KiB
Python
203 lines
10 KiB
Python
"""scripts/check-work-docs.py의 시험. 고장 낸 지침 배치에서 실패하고, 맞는 배치에서 통과하는지 본다.
|
|
|
|
python3 -m unittest discover -s scripts/tests
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import importlib.util
|
|
import io
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
import unittest
|
|
from contextlib import redirect_stderr, redirect_stdout
|
|
from pathlib import Path
|
|
|
|
SCRIPTS = Path(__file__).resolve().parent.parent
|
|
_spec = importlib.util.spec_from_file_location("check_work_docs", SCRIPTS / "check-work-docs.py")
|
|
check_work_docs = importlib.util.module_from_spec(_spec)
|
|
sys.modules["check_work_docs"] = check_work_docs
|
|
_spec.loader.exec_module(check_work_docs)
|
|
|
|
PLAYBOOK = "".join(f"## {heading}\n\n- 한 줄.\n\n" for heading in check_work_docs.SKELETON)
|
|
|
|
|
|
class Repository:
|
|
"""A throwaway git working tree with the smallest work manual the checker accepts. It sits one folder
|
|
below `outside`, so a test can put a file next to the repository that a `../` link would reach."""
|
|
|
|
def __init__(self) -> None:
|
|
self._directory = tempfile.TemporaryDirectory()
|
|
self.outside = Path(self._directory.name)
|
|
self.root = self.outside / "repo"
|
|
self.root.mkdir()
|
|
subprocess.run(["git", "init", "-q", str(self.root)], check=True)
|
|
self.write("AGENTS.md", "# 정본\n\n- 지도 한 줄.\n")
|
|
self.write("CLAUDE.md", "@AGENTS.md\n\n- Claude 전용 한 줄.\n")
|
|
self.write("docs/work/README.md", "# 작업 매뉴얼\n")
|
|
self.write("docs/work/evidence.md", "# 근거\n\n`1101/05-18`은 여기에 둔다.\n")
|
|
for name in check_work_docs.PLAYBOOKS:
|
|
self.write(f"docs/work/{name}", f"# {name}\n\n{PLAYBOOK}")
|
|
for name in check_work_docs.REFERENCES:
|
|
self.write(f"docs/work/{name}", "# 참고\n")
|
|
self.write("src/app/AGENTS.md", "# app\n\n- 지역 규칙.\n")
|
|
self.write("src/app/CLAUDE.md", "@AGENTS.md\n")
|
|
self.saved = {name: getattr(check_work_docs, name) for name in ("REPO_ROOT", "MAP", "CLAUDE_ENTRY", "WORK", "README")}
|
|
check_work_docs.REPO_ROOT = self.root
|
|
check_work_docs.MAP = self.root / "AGENTS.md"
|
|
check_work_docs.CLAUDE_ENTRY = self.root / "CLAUDE.md"
|
|
check_work_docs.WORK = self.root / "docs/work"
|
|
check_work_docs.README = check_work_docs.WORK / "README.md"
|
|
|
|
def write(self, path: str, text: str) -> None:
|
|
target = self.root / path
|
|
target.parent.mkdir(parents=True, exist_ok=True)
|
|
target.write_text(text, encoding="utf-8")
|
|
|
|
def run(self, *args: str) -> tuple[int, str]:
|
|
out, err = io.StringIO(), io.StringIO()
|
|
argv = sys.argv
|
|
sys.argv = ["check-work-docs.py", *args]
|
|
try:
|
|
with redirect_stdout(out), redirect_stderr(err):
|
|
code = check_work_docs.main()
|
|
finally:
|
|
sys.argv = argv
|
|
return code, err.getvalue()
|
|
|
|
def close(self) -> None:
|
|
for name, value in self.saved.items():
|
|
setattr(check_work_docs, name, value)
|
|
self._directory.cleanup()
|
|
|
|
|
|
class CheckWorkDocsTest(unittest.TestCase):
|
|
def setUp(self) -> None:
|
|
self.repo = Repository()
|
|
self.addCleanup(self.repo.close)
|
|
|
|
def assertFailsWith(self, fragment: str) -> None:
|
|
code, err = self.repo.run()
|
|
self.assertEqual(code, 1, err)
|
|
self.assertIn(fragment, err)
|
|
|
|
def test_the_smallest_valid_manual_passes(self) -> None:
|
|
self.assertEqual(self.repo.run(), (0, ""))
|
|
|
|
def test_a_map_over_forty_lines_fails(self) -> None:
|
|
self.repo.write("AGENTS.md", "# 정본\n" + "- 줄.\n" * 40)
|
|
self.assertFailsWith("AGENTS.md: 41 lines, limit 40")
|
|
|
|
def test_a_claude_entry_over_ten_lines_fails(self) -> None:
|
|
self.repo.write("CLAUDE.md", "@AGENTS.md\n" + "- 줄.\n" * 10)
|
|
self.assertFailsWith("CLAUDE.md: 11 lines, limit 10")
|
|
|
|
def test_a_claude_entry_that_does_not_import_the_map_fails(self) -> None:
|
|
self.repo.write("CLAUDE.md", "# 지도\n\n@AGENTS.md\n")
|
|
self.assertFailsWith("CLAUDE.md: the first line must be '@AGENTS.md'")
|
|
|
|
def test_the_entry_path_counts_the_map_the_claude_entry_the_readme_and_one_playbook(self) -> None:
|
|
# Each file's own limit keeps the sum under ENTRY_PATH_LIMIT today, so lower it to see the sum.
|
|
lines = sum(len((self.repo.root / name).read_text(encoding="utf-8").splitlines())
|
|
for name in ("AGENTS.md", "CLAUDE.md", "docs/work/README.md", "docs/work/improve.md"))
|
|
original = check_work_docs.ENTRY_PATH_LIMIT
|
|
check_work_docs.ENTRY_PATH_LIMIT = lines - 1
|
|
self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original)
|
|
self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines")
|
|
|
|
def test_a_folder_rule_book_over_two_hundred_lines_fails(self) -> None:
|
|
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 200)
|
|
self.assertFailsWith("src/app/AGENTS.md: 201 lines, limit 200")
|
|
|
|
def test_a_folder_rule_book_of_two_hundred_lines_passes(self) -> None:
|
|
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 199)
|
|
self.assertEqual(self.repo.run(), (0, ""))
|
|
|
|
def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None:
|
|
self.repo.write("src/web/AGENTS.md", "# web\n")
|
|
self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'")
|
|
|
|
def test_a_folder_claude_file_that_holds_rules_fails(self) -> None:
|
|
self.repo.write("src/app/CLAUDE.md", "@AGENTS.md\n\n- 여기에도 규칙을 쓴다.\n")
|
|
self.assertFailsWith("src/app/CLAUDE.md: must be exactly '@AGENTS.md'")
|
|
|
|
def test_a_folder_claude_file_without_a_rule_book_fails(self) -> None:
|
|
self.repo.write("src/old/CLAUDE.md", "@AGENTS.md\n")
|
|
self.assertFailsWith("src/old/CLAUDE.md: imports src/old/AGENTS.md, which does not exist")
|
|
|
|
def test_build_output_is_not_a_folder_rule_book(self) -> None:
|
|
self.repo.write("src/app/build/tmp/AGENTS.md", "# 복사본\n")
|
|
self.assertEqual(self.repo.run()[0], 0)
|
|
|
|
def test_a_history_id_in_a_folder_rule_book_fails(self) -> None:
|
|
self.repo.write("src/app/AGENTS.md", "# app\n\n- 리뷰 05-18에서 정했다.\n")
|
|
self.assertFailsWith("src/app/AGENTS.md:3")
|
|
|
|
def test_a_history_id_in_a_claude_rule_skill_or_agent_fails(self) -> None:
|
|
for path in (".claude/rules/x.md", ".claude/skills/x/SKILL.md", ".claude/agents/x.md"):
|
|
with self.subTest(path=path):
|
|
self.repo.write(path, "# 규칙\n\n- RR-03-03에서 고쳤다.\n")
|
|
self.assertFailsWith(f"{path}:3")
|
|
(self.repo.root / path).unlink()
|
|
|
|
def test_a_work_stream_or_red_team_id_in_a_playbook_fails(self) -> None:
|
|
for line in ("- 자세는 rate-limiting.md다(W4 BE-OBS-A).", "- BE-CONFIG-001로 고쳤다.", "- W4에서 정했다."):
|
|
with self.subTest(line=line):
|
|
self.repo.write("docs/work/operate.md", f"# operate.md\n\n{PLAYBOOK}{line}\n")
|
|
self.assertFailsWith("docs/work/operate.md:")
|
|
|
|
def test_words_that_only_look_like_a_work_stream_pass(self) -> None:
|
|
self.repo.write("docs/work/operate.md", f"# operate.md\n\n{PLAYBOOK}- W3C 표준과 HTTP-W1-x는 이름이 아니다.\n")
|
|
self.assertEqual(self.repo.run()[0], 0)
|
|
|
|
def test_local_claude_state_is_not_checked(self) -> None:
|
|
self.repo.write(".claude/worktrees/other/AGENTS.md", "# 다른 worktree\n\n- 리뷰 05-18.\n")
|
|
self.assertEqual(self.repo.run()[0], 0)
|
|
|
|
def test_a_broken_link_in_a_folder_rule_book_fails(self) -> None:
|
|
self.repo.write("src/app/AGENTS.md", "# app\n\n[설계](README.md)\n")
|
|
self.assertFailsWith("src/app/AGENTS.md:3: broken relative link 'README.md'")
|
|
|
|
def links(self, text: str) -> tuple[int, str]:
|
|
self.repo.write("docs/guide.md", f"# 안내\n\n{text}")
|
|
return self.repo.run("--links", str(self.repo.root / "docs/guide.md"))
|
|
|
|
def test_links_out_of_the_repository_fail_even_when_the_file_is_there(self) -> None:
|
|
# check-docs.py `link` refuses `..` past the root; --links used to accept any file on disk.
|
|
(self.repo.outside / "x.md").write_text("# 옆 clone\n", encoding="utf-8")
|
|
code, err = self.links("[옆](../../x.md)\n")
|
|
self.assertEqual(code, 1, err)
|
|
self.assertIn("guide.md:3: broken relative link '../../x.md'", err)
|
|
|
|
def test_links_to_a_folder_git_does_not_know_fail(self) -> None:
|
|
# `git mv` leaves the old folder on disk; a fresh checkout does not have it.
|
|
(self.repo.root / "docs/moved").mkdir(parents=True)
|
|
code, err = self.links("[옛 폴더](moved/)\n")
|
|
self.assertEqual(code, 1, err)
|
|
self.assertIn("broken relative link 'moved/'", err)
|
|
|
|
def test_links_follow_the_document_checker_rules(self) -> None:
|
|
# One rule for both checkers: links in code, inline code and history quotes are not links.
|
|
code, err = self.links("[지도](../AGENTS.md)\n\n```text\n[예](gone.md)\n```\n\n`[예](gone.md)`\n\n"
|
|
"> 이력: [옛](gone.md)\n")
|
|
self.assertEqual((code, err), (0, ""))
|
|
|
|
def test_links_from_a_file_outside_the_repository_are_refused(self) -> None:
|
|
(self.repo.outside / "x.md").write_text("# 밖\n", encoding="utf-8")
|
|
code, err = self.repo.run("--links", str(self.repo.outside / "x.md"))
|
|
self.assertEqual(code, 2, err)
|
|
self.assertIn("outside the repository", err)
|
|
|
|
def test_links_from_an_ignored_checkout_inside_the_repository_are_refused(self) -> None:
|
|
# Another worktree under .claude/worktrees/ has its own git; its links say nothing about this one's.
|
|
self.repo.write(".gitignore", ".claude/worktrees/\n")
|
|
self.repo.write(".claude/worktrees/other/a.md", "# 다른 checkout\n\n[지도](../../../AGENTS.md)\n")
|
|
code, err = self.repo.run("--links", str(self.repo.root / ".claude/worktrees/other/a.md"))
|
|
self.assertEqual(code, 2, err)
|
|
self.assertIn("not a file git knows", err)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
unittest.main()
|