test(claude): 스킬이 인용하는 절 이름을 문서 제목과 대조한다
문제: 스킬은 정본 문서의 절을 「이름」이나 「N절」로 가리킨다. 문서 검사 (verify:documentation)는 경로만 보므로, 문서를 번역하거나 절을 바꾸면 인용한 절이 사라져도 통과한다. 지금 9곳이 그렇다. - fe-structure: 「Decision rule」(지금 「판단 규칙」), 「The adapter kernel」(지금 「adapter kernel」) - fe-a11y: 「What the automated run scans」, 「Included primitives」 - fe-design-system: 「Arbitrary-value policy」 - fe-performance: 「Service Worker steps」 - fe-ux: 「routing 6.4절」이 앞 인용(typescript 설계서)의 6.4절로 읽힌다. 그 설계서에는 6.4절이 없다. - desktop-gates: 경로 없이 `gates.md`·`operate.md`라고만 쓴다. 고른 방법: scripts/tests/test_claude_setup.py의 SkillTest에 시험을 더한다. - 모든 repo 스킬에서 읽는 인용 꼴: `경로.md` 「이름」, `경로.md` N절 (3·4절, 6.1·11절), `경로.md` N절 「이름」, 같은 문서 N절, `fe-x` 「이름」(다른 스킬의 절). - 인용마다 대상 파일에 그 제목이 있는지 본다. 제목은 앞 번호와 끝 괄호를 뗀 꼴도 받는다. 「이름:」만 있는 소제목 줄도 받는다. 코드 블록 안 제목은 보지 않는다. - 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 둔다. - 9곳은 지금 제목으로 고치고, 짧게 쓴 경로는 전체 경로로 쓴다. 버린 대안: 문서 검사(scripts/lib/docs-system.ts)에 넣는 방법. 스킬 구성의 다른 규칙이 이미 이 시험 파일에 있고, `scripts/verify.sh hooks`로 노트북에서 바로 돈다. 위험: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 거짓 실패가 난다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰 지금 196개 인용에는 그런 경우가 없다. 「N절」이 다른 문서를 줄여 부르면(「routing 6.4절」) 앞 경로로 읽으니 전체 경로로 쓴다. 이 시험은 게이트가 아니라 hooks 단계에서 돈다. 검증: python3 -m unittest scripts.tests.test_claude_setup. - 고치기 전: 새 시험이 9곳(과 처음 판에서 거짓 실패 2곳)을 냈다(RED). - 고친 뒤: 24개 모두 통과했다. 인용 196개를 확인했다.
This commit is contained in:
@@ -29,6 +29,72 @@ KNOWLEDGE_SECTIONS = ["언제 쓰나 · 넘기는 곳", "함정", "이 분야에
|
||||
BANNED_IN_DESCRIPTION = ("PROACTIVELY", "MUST", "CRITICAL", "IMPORTANT", "<example>")
|
||||
|
||||
|
||||
# A skill points at a section as `path.md` 「name」, `path.md` 3.1절 (or 3·4절), `path.md` 4.1절 「name」,
|
||||
# 같은 문서 6절 (the path cited last), or `fe-x` 「name」 (another skill's section).
|
||||
CITED_TARGET = re.compile(r"`([^`\s]+\.md)`|`((?:fe-[a-z0-9-]+|new-feature|desktop-gates))`|(같은 문서)")
|
||||
SECTION_NUMBERS = re.compile(r"(\d+(?:\.\d+)*(?:·\d+(?:\.\d+)*)*)절")
|
||||
SECTION_NAME = re.compile(r"「([^」]+)」")
|
||||
# What follows a citation up to the first of these is about that citation; past it is the sentence's own text.
|
||||
CITATION_END = re.compile(r"—|`|\(|\)|;|\. |。")
|
||||
HEADING_NUMBER = re.compile(r"^(\d+(?:\.\d+)*)\.?(?=\s)")
|
||||
|
||||
|
||||
# A paragraph label on its own line ("자동 실행이 검사하는 것:") names a part of a section the same way a heading does.
|
||||
LABEL_LINE = re.compile(r"^\*{0,2}([^\s*#|>`-][^:|]*?)\*{0,2}:\s*$")
|
||||
|
||||
|
||||
def headings(path: Path) -> tuple[set[str], set[str]]:
|
||||
"""The section names of a markdown file and the numbers of its numbered headings.
|
||||
|
||||
A name is a heading's text, with and without its leading number and a trailing "(…)", or a label line."""
|
||||
names, numbers, fenced = set(), set(), False
|
||||
for line in path.read_text(encoding="utf-8").splitlines():
|
||||
if line.startswith("```"):
|
||||
fenced = not fenced
|
||||
if fenced:
|
||||
continue
|
||||
label = LABEL_LINE.match(line)
|
||||
if label:
|
||||
names.add(label.group(1).strip())
|
||||
if not re.match(r"#{1,6} ", line):
|
||||
continue
|
||||
text = line.lstrip("#").strip()
|
||||
number = HEADING_NUMBER.match(text)
|
||||
if number:
|
||||
numbers.add(number.group(1))
|
||||
for name in (text, text[number.end():].strip() if number else text):
|
||||
names.add(name)
|
||||
names.add(re.sub(r"\s*\([^()]*\)$", "", name))
|
||||
return names, numbers
|
||||
|
||||
|
||||
def cited_sections(text: str) -> list[tuple[int, str, str]]:
|
||||
"""(line, target file, 「name」 or N절) for every section a skill names after a path or another skill."""
|
||||
found, last_path = [], None
|
||||
for number, line in enumerate(text.splitlines(), 1):
|
||||
matches = list(CITED_TARGET.finditer(line))
|
||||
for index, match in enumerate(matches):
|
||||
path, skill, same = match.groups()
|
||||
if path:
|
||||
target = last_path = path
|
||||
elif skill:
|
||||
target = f".claude/skills/{skill}/SKILL.md"
|
||||
elif last_path:
|
||||
target = last_path
|
||||
else:
|
||||
continue
|
||||
rest = line[match.end(): matches[index + 1].start() if index + 1 < len(matches) else len(line)]
|
||||
end = CITATION_END.search(rest)
|
||||
segment = rest[: end.start()] if end else rest
|
||||
if skill or same:
|
||||
# Only a section named right after it: `fe-x`의 「검증」, 같은 문서 12절.
|
||||
segment = re.match(r"(?:의)?\s*(?:\d[\d.·]*절\s*)?(?:「[^」]+」)?", segment).group(0)
|
||||
for numbers in SECTION_NUMBERS.findall(segment):
|
||||
found.extend((number, target, f"{value}절") for value in numbers.split("·"))
|
||||
found.extend((number, target, f"「{name}」") for name in SECTION_NAME.findall(segment))
|
||||
return found
|
||||
|
||||
|
||||
def front_matter(path: Path) -> tuple[dict[str, str], list[str]]:
|
||||
"""The scalar fields and the list items of a document's YAML front matter."""
|
||||
match = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S)
|
||||
@@ -185,6 +251,52 @@ class SkillTest(unittest.TestCase):
|
||||
self.assertIn("쓴다", description, f"{name}: say when to use it")
|
||||
self.assertIn("부른다", description, f"{name}: say what the user says that calls it")
|
||||
|
||||
def test_every_section_a_skill_cites_is_a_heading_of_that_document(self) -> None:
|
||||
# The path check (verify:documentation) passes when a cited document is translated or renumbered
|
||||
# and the section the skill names is gone: 「Decision rule」 outlived its heading this way.
|
||||
missing = []
|
||||
for path in sorted((CLAUDE / "skills").glob("*/SKILL.md")):
|
||||
for line, target, section in cited_sections(path.read_text(encoding="utf-8")):
|
||||
document = REPO / target
|
||||
if not document.is_file():
|
||||
missing.append(f"{path.parent.name}:{line}: {target} does not exist")
|
||||
continue
|
||||
names, numbers = headings(document)
|
||||
known = numbers if section.endswith("절") and not section.startswith("「") else names
|
||||
if section.strip("「」").removesuffix("절") not in known:
|
||||
missing.append(f"{path.parent.name}:{line}: {target} has no section {section}")
|
||||
self.assertEqual(missing, [], "\n" + "\n".join(missing))
|
||||
|
||||
def test_the_section_check_reads_each_citation_form(self) -> None:
|
||||
text = "\n".join([
|
||||
"- 배럴 — `docs/a.md` 「공개 경계」, `docs/b.md` 3·4.1절",
|
||||
"- 토큰 — `docs/c.md` 6절 「검사 규칙」, 같은 문서 12절",
|
||||
"- 원칙 — `PRODUCT.md` 원칙 1, 「Constraints」",
|
||||
"- 골든을 본다(`fe-design-system` 「검증」). 예제가 없으면 「없음」",
|
||||
"- `docs/d.md` — 설명. 아래 「함정」",
|
||||
])
|
||||
self.assertEqual(cited_sections(text), [
|
||||
(1, "docs/a.md", "「공개 경계」"), (1, "docs/b.md", "3절"), (1, "docs/b.md", "4.1절"),
|
||||
(2, "docs/c.md", "6절"), (2, "docs/c.md", "「검사 규칙」"), (2, "docs/c.md", "12절"),
|
||||
(3, "PRODUCT.md", "「Constraints」"),
|
||||
(4, ".claude/skills/fe-design-system/SKILL.md", "「검증」"),
|
||||
])
|
||||
|
||||
def test_the_section_check_reads_headings_numbers_and_labels(self) -> None:
|
||||
import tempfile
|
||||
with tempfile.TemporaryDirectory() as folder:
|
||||
document = Path(folder) / "doc.md"
|
||||
document.write_text("\n".join([
|
||||
"# 제목", "## 3. merge 가능 판정", "### 3.1 열린 결정", "#### 토큰 CSS 검사 규칙 (`check:design-system`)",
|
||||
"임의 값(arbitrary value) 정책:", "- 목록 줄: 이름이 아니다", "```text", "## 9. 코드 안 제목", "```",
|
||||
]), encoding="utf-8")
|
||||
names, numbers = headings(document)
|
||||
self.assertEqual(numbers, {"3", "3.1"})
|
||||
for name in ("merge 가능 판정", "열린 결정", "토큰 CSS 검사 규칙", "임의 값(arbitrary value) 정책"):
|
||||
self.assertIn(name, names)
|
||||
self.assertNotIn("코드 안 제목", names)
|
||||
self.assertFalse(any(name.startswith("목록 줄") for name in names))
|
||||
|
||||
def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None:
|
||||
for name, canon in self.CANON.items():
|
||||
body = (CLAUDE / "skills" / name / "SKILL.md").read_text(encoding="utf-8")
|
||||
|
||||
Reference in New Issue
Block a user