modify harness framework

2026-08-05 01:42:21 +09:00
parent 6646344113
commit 41020d78d8
74 changed files with 2663 additions and 3145 deletions
@@ -0,0 +1,124 @@
+# Harness 운영 가이드
+
+## Requirements
+
+Windows, Python 3.10 이상, Codex CLI가 필요하다. CMake 프로젝트에는 Visual Studio의
+Desktop development with C++ 워크로드와 MSBuild, CMake/CTest를 설치한다.
+
+## 프로젝트 자동 감지
+
+프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의
+CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는
+건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는
+오류로 처리한다.
+
+설정 파일은 선택 사항이다. 기본 자동 감지와 `.harness/build` 경로를 그대로 사용할
+때는 만들지 않아도 된다. 프로젝트별 override가 필요하면 다음처럼 예시를 복사한다.
+
+```powershell
+Copy-Item .harness/config.example.json .harness/config.json
+```
+
+계획을 승인해 phase 파일을 만든 뒤 Executor를 실행한다.
+
+```powershell
+python scripts/execute.py <phase-name>
+python scripts/execute.py <phase-name> --push
+```
+
+## Harness Python 검증
+
+이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
+다음 명령으로 실행한다.
+
+```powershell
+uv run --with pytest python -m pytest -v -rs
+```
+
+## CMake preset 설정
+
+`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
+`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
+지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
+
+```json
+{
+  "version": 1,
+  "projectType": "cmake",
+  "cmake": {
+    "sourceDir": ".",
+    "binaryDir": "out/build/windows-debug",
+    "configurePreset": "windows-debug",
+    "buildPreset": "windows-debug",
+    "testPreset": "windows-debug"
+  }
+}
+```
+
+```powershell
+cmake --preset windows-debug
+cmake --build --preset windows-debug
+ctest --preset windows-debug --output-on-failure
+```
+
+Preset을 쓰지 않는 경우에는 같은 격리된 build directory를 명시한다.
+
+```powershell
+cmake -S . -B .harness/build -A x64
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+## 직접 MSBuild 설정
+
+`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
+지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
+파일과 인수를 JSON 배열로 적는다.
+
+```json
+{
+  "version": 1,
+  "projectType": "msbuild",
+  "msbuild": {
+    "solution": "MyProject.sln",
+    "configuration": "Debug",
+    "platform": "x64",
+    "testCommand": ["build/tests/Debug/MyProjectTests.exe"]
+  }
+}
+```
+
+```powershell
+MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
+.\build\tests\Debug\MyProjectTests.exe
+```
+
+## TDD 확장
+
+`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다
+`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은
+기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를
+대체하지 않고 추가한다.
+
+```json
+{
+  "version": 1,
+  "tdd": {
+    "testRoots": ["tests", "integration-tests"],
+    "testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
+    "exclude": ["legacy/generated/**"]
+  }
+}
+```
+
+## 실패 복구
+
+- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
+- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다.
+- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
+- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다.
+- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다.
+- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리,
+  종료 코드와 출력 tail을 확인하고 해당 명령을 단독으로 다시 실행한다. Harness는
+  별도의 로그 파일을 만들지 않는다.