품질 게이트 가이드

22.1 개요

PureCVisor는 커밋 훅과 계약 게이트 타깃으로 코드 품질을 자동 검증합니다.

커밋 시:
  설치된 pre-commit hook (변경 영역별 조건부 검사) → 선택 설치한 commit-msg hook → 커밋 완료

릴리스 전:
  make check-all (계약 게이트 전량) + make test (등록된 전체 테스트) → 검증 정책의 릴리스 조건 확인

pre-commit은 staged 변경 종류(C 소스 / API / UI / 전체)를 보고 실행할 게이트를 고르므로 실제 실행 수는 커밋마다 다릅니다.
문서만 바꾼 커밋은 빌드·테스트 게이트를 전부 건너뜁니다.
반면 make check-all은 조건 분기 없이 의존 목록 전량을 매번 돌립니다.
게이트 수의 정본은 항상 Makefile 의 check-all: 의존 목록입니다 — 문서의 숫자가 어긋나면 Makefile 이 옳습니다.

22.2 pre-commit hook (변경 영역별 조건부 검사)

# pre-commit 설치
make install-hooks
# 커밋 메시지 형식 검사도 사용할 경우 별도 설치
cp scripts/commit-msg .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

단계	게이트	트리거	차단
1	기본 빌드(`make all`, Single Edge) 경고 0	C 변경	차단
2	Single Edge 빌드 경고 0	C 변경	차단
3	등록된 유닛 테스트 (hook 최소 200건)	C 변경	차단
4	REST↔RPC 정합성	API 변경	차단
4 계열	변경 영역별 계약 게이트와 도움말 수 검사 (`scripts/pre-commit`의 조건이 정본)	해당 영역 변경	차단
5	프론트엔드 패턴 (10건 임계값) · ESLint · OpenAPI 동기화 · UI 번들 최신성 · XSS 패턴 · i18n 키 정합성	UI 변경	차단
6	cppcheck 정적 분석 에러	C 변경 + cppcheck 설치	차단
7	바이너리 크기 3MB 상한	C 변경	차단
8	SAFE 통합 테스트 + 보안 스캔 (OWASP Top 10)	API/UI + 데몬 실행	차단
9	문서에 RPC/테스트 수가 있을 때 정합성 보조 검사	C 변경	경고
10	신규 TODO/FIXME	C 변경	경고
11	ASan/UBSan test_runner (5분 타임아웃)	C 변경 + sanitize 가능	차단
12	Valgrind definite leak	C 변경 + valgrind 설치	차단
13	gitleaks 시크릿 스캔	staged diff	차단

커밋 메시지 형식은 pre-commit이 아니라 commit-msg hook이 판정합니다(22.3 참조).

22.3 commit-msg hook

허용 접두사: feat | fix | refactor | perf | docs | chore | test | ci | style

형식:
  <type>: <설명>
  <type>(scope): <설명>

예시:
  feat: VM 스냅샷 목록 필터 추가
  fix(rest_server): rate limiter 우회 수정
  perf: json_generator → json_to_string 전환

22.4 계약 게이트 일괄 — `make check-all` (42게이트)

make -j1 check-all

게이트	검사 범위
`check-aws-manual-removed`	AWS 수동 이관·S3 실행/API/UI 부재·북마크와 VM/OVA/로컬 백업/일반 Job 보존
`check-rbac`	ADR-0019 RBAC 정책 계약
`check-rpc-consumers`	AF-C4 RPC 소비⊆등록 계약
`check-dead-exports`	미소비 공개 심볼(dead export) 차단
`check-rpc-param-contract`	RPC param-key 계약 (Stage 2)
`check-json-ingress`	JSON 파싱 초크포인트
`check-safety-controls`	안전통제 효과 테스트 레지스트리
`check-error-codes`	raw 에러코드 리터럴 방지 (DISP-6)
`check-cli-exit-status`	`pcvctl` 성공·실패·사용법 오류 0/1/2와 VPC terminal Job 효과 테스트
`check-audit-placement`	audit 배치 계약 (ADR-0018)
`check-cors-anchor`	CORS 오리진 앵커 (A05·V3·V13)
`check-secret-logging`	감사 로그 자격증명 마스킹 (A09·V14·V16)
`check-ssrf-guard`	아웃바운드 리다이렉트 금지 (A10·V4)
`check-grpc-authz`	gRPC 인증/RBAC (A01·V8)
`check-ssrf-target-guard`	아웃바운드 대상 SSRF allowlist (A10·V4)
`check-audit-hashchain`	감사 로그 해시체인 (A09)
`check-rng-safe`	보안 RNG/PBKDF2 하드닝 (A02·V11)
`check-uds-authz`	UDS root-only 접근 (A01·V8)
`check-transport-bind`	평문 전송 루프백 바인딩 (A02·V12)
`check-proxy-identity`	프록시 클라이언트 신원 단일 경계
`check-container-owner-scope`	컨테이너 operator owner-scope (A01)
`check-mtls-wiring`	mTLS 클라이언트 인증서 검증 배선 (A02·V12)
`check-tls-min-version`	TLS 최소 버전 고정 (A02·V11·V12)
`check-secret-wipe`	시크릿 free-without-wipe 방지 (OVL-1 후속)
`check-security-headers`	`/ui` 정적 응답 보안 헤더 (A05)
`check-password-policy`	user-create 비밀번호 복잡도 정책 (A07)
`check-ws-token-url`	WS URL-query 토큰 인증 제거 (A07)
`check-zpool-suspend-recover`	ZFS 풀 SUSPENDED 탐지 + 가드된 자동복구
`check-deb-apparmor`	2.0 deb AppArmor 미부착 (ADR-0028)
`check-public-comments`	설명 주석·소스맵 제외, 변환 회귀와 공개 실행 계약
`check-vendor-integrity`	벤더링 자산 SHA-256 핀 — 전수 등재·유령·심링크 우회 차단 (A03)
`check-npm-lockfile`	npm 의존 SRI 핀·레지스트리 단일 출처·lock 드리프트 0 (A03)
`check-deb-supply-chain`	deb 의존 버전 하한 배선·md5sums 전수·벤더 핀 전이 (A03)
`check-fe-rpc-params`	UI 가 보내는 요청 파라미터 키 ⊆ 백엔드 핸들러가 읽는 키
`check-network-mode-contract`	UI network mode enum과 백엔드 whitelist 양방향 정합성
`check-iscsi-chap-argv`	initiator CHAP 비밀번호의 `iscsiadm` argv 재도입 차단
`check-rpc-route-unique`	`g_rpc_routes` 중복 등록 금지 (라우트 섀도잉 차단)
`check-rerror-guard`	Web UI의 JSON-RPC `r.error` 미검사 호출부 래칫
`check-dpdk-owned-lifecycle`	ADR-0053 OVS ownership·MTU·VM lifecycle·accepted Job 배선
`check-single-ui-surface`	이벤트·경보·감사·명령 연결과 개발판 소스맵 배포 계약
`check-runtime-prereqs`	원격 daemon/CLI ABI stop-before-mutation · 배포 런타임 전제 · nginx 종단 · LIO 모듈 패키징
`check-vnc-proxy-lifetime`	실제 binary relay·REST context·WS signal/source/FD 종료 수명 (ADR-0065)

22.5 품질 게이트 건너뛰기

# 긴급 커밋 (pre-commit + commit-msg 모두 건너뜀)
git commit --no-verify -m "fix: 긴급 수정"

# 주의: 훅을 건너뛴 커밋도 릴리스 전 make check-all + make test는 그대로 통과해야 함

22.6 신규 RPC 추가 시 체크리스트

handler_xxx.h에 함수 선언
handler_xxx.c에 핸들러 구현
dispatcher.c 라우트 등록 (g_hash_table_insert)
Makefile DAEMON_SRCS에 소스 등록
make clean && make all — 경고 0 확인
nc -U 수동 RPC 테스트
REST 필요 시 rest_server.c 라우팅 추가
scripts/verify_api_consistency.sh — FAIL 0 확인
공개 가이드·RPC 계약을 갱신하고 make check-rbac로 등록·정책 매핑 검증
git commit — pre-commit 조건부 게이트 통과

22.7 2026-09-07 검토·시정 현황

아래는 개발선의 감사·시정 회차입니다.
공개 저장소의 제품 코드와 시험 수치, 지원 환경 인증은 별도로 판정합니다.
파일 목록을 만들거나 시험이 통과했다는 이유만으로 전체 감사를 완료 처리하지 않습니다.

항목	확인 결과	판정 경계
전수 대상	현행 1,600파일 목록·해시 고정	목록화는 본문 검토가 아님
이번 본문 검토	소스·시험 22파일, 4,626행과 직접 호출부	나머지 파일·계약은 후속 검토 대상
기존 발견 처분	36건 중 34건 시정 검증·2건 후속	기존 회차의 누적 처분
새 회차 발견	I/O·모니터링 7건 미완료(P2 5·P3 2)	기존 36건 처분과 구분
지정 UI 시정	전체 60파일 505 PASS·독립 대조 44 PASS	지정 시정의 로컬 검증 결과
UI 운영 확인	독립 운영 노드 2대의 자산 21/21·브라우저 cache 17/17·기본 로드·health 정상	실제 VM 변경 효과·모든 환경 인증은 별도
전체 감사	FAIL(미완료)	미검토 소스, 결과·회수 계약과 지원 환경·전체 메모리 검사 잔여

독립 리뷰는 변경 작성자와 별도 검토자가 같은 소스·입력·원본 결과를 대조하는 절차입니다.
시정 후 재검토와 실제 설치 확인은 완료 범위를 구체적으로 기록하며, 개발선 결과를 공개 소스의 시정 완료로 전용하지 않습니다.

공개 스냅샷의 C 1,375/1,375·audit startup 5/5와 계약 gate 38/38은 2026-08-31 기록입니다.
2026-09-07 문서 배포에서 다시 실행한 전체 C·제품 UI 시험 수치가 아니며, 후속 공개 소스 검증은 22.8절을 따릅니다.
Pages 자체는 콘텐츠 build·route·링크·공개 자산 검사와 게시 후 HTTP·브라우저 확인으로 검증합니다.

22.8 공개 소스·문서 현황

2026-10-16 현재 소스 (2.0.2): 2.0.1 공개 소스에 REST 요청 처리 보안 시정 두 건만 반영했습니다.
변경 목록은 CHANGELOG.md의 2.0.2 항목을 따릅니다.

2026-10-11 현재 소스 (2.0.1): 2.0.0 공개 소스에 보안 시정만 반영했습니다.
변경 목록은 CHANGELOG.md의 2.0.1 항목, 결정은 ADR-0079를 따릅니다.

2026-10-08 현재 소스: AWS 수동 이관·S3 백업 제거와 공통 Job/WS·QGA·VM 시작· Trace·VNC·OVA·자가 치유 보강을 포함합니다.
버전 2.0.0을 유지하며 기존 태그·패키지는 재발행하지 않았습니다.
최신 공개 인계의 검증 범위를 따르며, 아래 표는 과거 회차의 검증 기록입니다.

2026-10-02 소스 기준: 공개 제품 로직을 개발 main에 맞췄다.
NVRAM·첫 알림 쿨다운 시정은 유지하며 LXC는 ZFS 전용이다.
공개 전용 Btrfs와 개발 main 미병합 후속 브랜치는 포함하지 않는다.
정합화 인계에서 이번 검증을 구분한다.

2026-09-15 검증 기록

항목	공개 근거와 확인 범위
제품 소스	`22d6912`: 호스트 첫 알림 쿨다운 수정, 공개 UI 표면·소스맵 부재 검사를 `check-all`·`dev-check`에 연결
C·UI 시험	해당 소스 검증 회차에서 C 1,479 PASS·14 SKIP, audit startup 5 PASS, UI 512 PASS·0 SKIP
계약·빌드	공개 `check-all` 40 PASS, UI 표면 반사실 11 PASS, debug·clean release 경고 0
메모리 검사	ASan/UBSan 전체 통과(기본 leak detection 비활성), 지정 self-healing Valgrind 4 PASS·오류/definite/indirect/possible leak 0
GPU 테스트 영상	`52587a5`, Pages 게시 성공: 4개 기능·16편, RTX 3070 Ti·Windows 11의 124초 영상 추가
영상 검증 범위	30초 Vulkan 렌더링과 종료·원복 확인. 장시간 안정성·모든 GPU·게임 성능 인증은 별도
문서 현행화	현재 소스·설정·게이트와 문서를 대조하고 문서 링크·사이트 build·공개 자산을 검증. 문서 변경은 제품 시험의 재실행이나 전체 감사 완료를 의미하지 않음

지정 Valgrind 통과는 이전 전체 검사 잔여를 닫는 근거가 아닙니다.
미검토 소스, 결과·자원 회수 계약, 전체 메모리 검사와 지원 환경 인증이 남아 있어 전체 감사는 FAIL(미완료)를 유지합니다.
개발선의 22.7절 이력과 이 공개 소스 회차의 결과를 합산하지 않습니다.
공개 제품 버전은 2.0.2입니다.

PureCVisor v2.0.2 Complete Guide — 22장 끝.