품질 게이트 가이드

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` (40게이트)

make check-all은 “방어를 제거하면 RED가 되는” 반사실 게이트(ADR-0025)를 한 번에 돌리는 릴리스 기준선입니다.
pre-commit은 같은 계열을 변경 영역에 따라 조건부로 나눠 실행하고, check-help-counts 하나만 pre-commit 전용입니다 — 배포 계약 게이트 목록에 도움말 표시값 게이트를 끼우지 않기 위한 의도적 분리입니다.

게이트	검증 대상
`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`	자체 소스 설명 주석 0건과 UI 소스맵 제외 정책
`check-runtime-prereqs`	배포 런타임 전제 배선 · nginx 종단 · LIO 모듈 패키징
`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`	DPDK 제품 소유 자원의 생성·회수·실패 정리 계약
`check-single-ui-surface`	Single Edge 이벤트·명령 연결, 공개 소스맵 부재와 반사실 회귀

check-rpc-param-contract 와 check-fe-rpc-params 는 겹치는 것처럼 보이지만 소비처가 다릅니다 — 전자는 contracts/rpc_params.json 레지스트리에 등재된 메서드의 CLI 소비를 보고, 후자는 Web UI 소스를 훑습니다.
2026-08-06 계약 불일치 회차에서 전자가 UI 를 보지 않는다는 것이 드러나 후자를 신설했습니다(설계 §8.1).
전자는 “보내는데 핸들러가 안 읽는다”를 아직 WARN 으로 흘려보내며, FAIL 승격은 후속 과제입니다(설계 §8.3).

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-09-16 공개 소스 e028ef2**입니다.
제품 버전은 2.0.0이며 초기 2.0.0 태그와 이후 main을 설치한 commit으로 구분합니다.

항목	공개 근거와 확인 범위
현재 제품 소스	`e028ef2`: 기본 ZFS·명시 선택 Btrfs LXC, 객체별 실제 저장소 identity, 정지 rootfs 복원, 영구 Job·snapshot 요청자 audit, LXC 7 CPU 가중치
VM 삭제 수정	`5e84387`: 디스크 삭제 성공까지 파일형 NVRAM 보존. 지정 Ubuntu worker 실기와 Arch 설치 서비스 API 실기 각 5개 통과. Ubuntu 운영 daemon은 교체하지 않음
Btrfs 실기	Omarchy 4.0.3·Arch, kernel `7.2.3-arch1-3`, LXC `7.0.0-2`, btrfs-progs `7.1-1`, ZFS 미설치. API 생성·guest 부팅·파일 영속화·CoW 복제·snapshot·복원·거부·기본값 변경 후 동작·정리 통과
복구·완료 관측	실제 Btrfs에 구성한 교환 전·후 journal 복구와 삭제 재시도 통과. snapshot 성공·거부·삭제의 terminal Job, 각 1개 WS 완료·요청자 audit 일치. 프로세스 강제 종료나 정전 시험은 아님
구현 검증	`e028ef2`의 `make test`, `make -j1 check-all` 40개와 release 빌드 통과. `check-lxc-storage`의 저장소 24개·반사실, driver 7그룹, snapshot audit 12조합 통과. 실제 guest 시험과 격리 회귀 수치를 합산하지 않음
문서 게시	Btrfs 가이드 Pages 실행 성공. 현재 문서 전체 대조 범위는 문서 현행화 인계에서 추적
남은 범위	Btrfs rootless·quota·send/receive 제품 백업·자동 migration은 미지원. Ubuntu ZFS 전체 실기 회귀·host reboot·정전·ENOSPC·장시간 안정성·모든 환경 인증은 별도

원시 증거의 요약·해시는 Btrfs API 검증 인계와 NVRAM 수정 인계를 따릅니다.
이번 문서 변경은 제품 실기 재실행이나 전체 감사 완료를 뜻하지 않습니다.

이전 공개 검증 회차 — 2026-09-15

다음은 22d6912의 당시 결과입니다.
이후 Btrfs 소스에서 모든 UI·전체 메모리 검사를 같은 수만큼 다시 통과했다는 뜻이 아닙니다.

항목	공개 근거와 확인 범위
제품 소스	`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.0입니다.

PureCVisor v2.0.0 운영 가이드 — 공개 범위 21개 장, 마지막 장 번호 22.