문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.
고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
`git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.
위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
"not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
the working tree", "reports the references as not verified when the
checkout does not have the pinned commit", "fails a link out of the
repository into a repository that is not paired".
Refs: 1105/12-02