테스트: 검증 스위트

실행하기

just test
# or
python3 tests/validate.py

어디서든 실행되며 Python 3만 필요하다(서드파티 패키지도 네트워크도 필요 없다). 검사마다 한 줄을 출력하고 어느 하나라도 실패하면 0이 아닌 값으로 종료하므로 CI와 프리커밋 훅으로 알맞다.

검사하는 것

• 예상되는 주제 수(스크립트 상단의 상수).
• 각 부 안에서 N.0부터 시작하는 연속 번호.
• 모든 주제에서 H1이 파일 이름의 소수와 일치.
• H1 제목이 spec/structure.md와 앞의 소수만이 아니라 글자 하나하나까지 일치.
• 모든 내용 주제(1부부터 8부, 주제 N.1 이상)에 필수 섹션이 있고, 템플릿과 정확히 같은 순서일 것.
• 모든 내용 주제의 최소 단어 수(1,500단어). 의도적 예외를 위한 허용 목록이 스크립트 안에 있다.
• 어떤 Markdown 파일에도 엠 대시 없음.
• 엔 대시는 숫자 사이에서만. “2.1–2.8”은 통과하고 나머지는 실패한다.
• 금지된 문구 없음(“not only”, “but also”, “load-bearing”).
• 모든 내부 .md 링크가 해결됨.
• 본문 속 교차 참조가 실제 주제를 가리킴: 디스크에 대응하는 파일이 없는 주제 번호에 대한 참조는 실패하며, 게시된 사이트의 주제 링크 자동화가 쓰는 것과 같은 참조 패턴을 사용한다.
• Wikipedia 링크의 형식이 올바름(https://en.wikipedia.org/wiki/...).
• spec/structure.md가 디스크의 파일과 일치. 양방향으로.
• README, 홈페이지, 콘텐츠 페이지가 모든 주제로 링크.

검사가 실패할 때

실패한 줄은 파일과 문제를 알려 준다. 흔한 해결책:

• 엠 대시 발견: ”—“를 없애도록 문장을 다시 쓴다. 그냥 지우지 마라.
• 섹션 누락: 주제 템플릿에서 빠진 ## 섹션을 추가한다.
• 구조 불일치: spec/structure.md를 갱신하지 않고 주제를 추가하거나 이름을 바꿨거나 그 반대다. 둘을 다시 맞춘다.
• 깨진 링크: 경로를 고치거나 이름 변경 뒤에 갱신한다.
• 번호의 빈틈: 부가 N.0부터 연속되도록 번호를 다시 매긴다.

검증 스위트 너머

• just spell은 저장소에 codespell을 실행한다. 설정은 오탐 무시 목록을 포함해 pyproject.toml의 [tool.codespell] 섹션이다.
• just stats는 tools/stats.py에서 Markdown 보고서(주제별 단어 수, 얇은 주제, Wikipedia 링크, 참고 문헌 항목)를 출력한다.

지속적 통합

• .github/workflows/test.yml은 모든 풀 리퀘스트와 main이 아닌 브랜치로의 푸시에서 실행된다. 검증 스위트와 codespell이다. 이 저장소는 사이트를 빌드하거나 배포하지 않으며, 렌더링은 별도의 software-engineering-metrics.github.io 저장소에서 이루어진다.
• .github/workflows/links.yml은 lychee로 외부 링크를 매주 검사하고(무시 패턴은 .lycheeignore), 결과를 하나의 “Link checker report” 이슈에 유지한다. 외부 링크는 의도적으로 PR 경로 밖에 두었다.

테스트가 다루지 않는 것

스위트는 구조와 스타일을 검사하며 진실은 검사하지 않는다. 참고 문헌이 실재하는지, 본문이 정확한지는 알 수 없다. 인용과 사실은 직접 또는 조사 과정으로 검증하라. Wikipedia 링크의 존재(형식과는 별개)도 네트워크 검사가 필요하며, 스위트가 오프라인에서 실행되도록 의도적으로 빼 두었다.