버전·호환·누출 검사

이 페이지는 @platform/vue-debugger의 버전 정책과, 그 정책을 사람이 아니라 기계가 지키게 하는 안전장치를 다룹니다. 버전 정책은 소비 프로젝트가 안심하고 올릴 수 있는 약속이고, 누출 검사는 "조건부 동적 import라 어차피 제거된다"는 믿음이 아니라 빌드 산출물을 직접 grep해 검증하는 마지막 방어선입니다. 절반은 유지보수자용(버전·호환), 절반은 소비 프로젝트용(누출 검사·로컬 링크)입니다.

현재 버전은 0.17.4, peerDependency는 vue ^3.4.0 하나뿐이며 런타임 의존성은 0개입니다. 배포·반입 절차는 빌드와 배포와 폐쇄망 반입을, 소비 프로젝트의 검증 빌드 구성은 검증 빌드를 함께 보세요.

semver 정책

버전 숫자만 보고도 "이걸 올리면 내 코드를 고쳐야 하나"를 판단할 수 있어야 하므로, 다음 규칙을 따릅니다.

변경	버전	예시
패널 추가, 옵션 추가	minor (0.11 → 0.12)	새 패널, 새 attachDebugger 옵션
attachDebugger 시그니처·옵션 변경	major	옵션 제거·이름 변경, 반환 핸들 형태 변경
버그 수정, 내부 정리	patch (0.12.0 → 0.12.1)	동작은 그대로, 결함만 수정

즉 호출부(attachDebugger)를 건드리지 않는 추가는 minor, 건드리는 변경은 major입니다. 기능을 추가했다면 옵션 레퍼런스·패널 레퍼런스도 같은 PR에서 갱신합니다.

TIP

패널·옵션을 추가하거나 변경하면 CHANGELOG.md에 더해 README의 기능표와 SETUP.md를 함께 갱신하세요. 세 곳이 어긋나면 소비 개발자가 문서대로 따라 했는데 동작이 다른 상황이 생깁니다.

Vue 호환

이 패키지는 pinia/vue-router/axios를 import하지 않고 런타임에 구조적으로 발견하지만, Vue 자체의 비공개 내부 표면(컴포넌트 인스턴스 트리 등)에는 의존합니다. 그 의존부는 전부 src/core/vueInternals.ts 한 파일에 격리돼 있고, test/provenance.spec.ts가 그 표면이 실제 Vue에서 여전히 유효한지를 계약 테스트로 지킵니다.

peer 범위는 ^3.4입니다. 호스트 앱이 Vue 메이저/마이너를 올렸을 때의 절차는 다음과 같습니다.

npm run test -w @platform/vue-debugger    # provenance.spec 포함

provenance.spec 통과  →  Vue 내부 표면이 그대로. 손댈 것 없음.
provenance.spec 깨짐  →  src/core/vueInternals.ts 만 손본다 (다른 곳은 건드리지 않음).

내부 표면이 바뀌면 수정 범위는 vueInternals.ts 한 파일로 한정됩니다. 이것이 내부 의존부를 한 파일에 모아 둔 이유입니다 — 버전업의 충격을 한 곳으로 가두고, 계약 테스트가 그 충격을 즉시 적발합니다.

WARNING

provenance.spec가 통과하면 그 Vue 버전에서 안전하다는 뜻이지만, peer 범위(^3.4)를 넓혀 새 메이저를 공식 지원하려면 package.json의 peerDependencies.vue도 함께 올리고 그 변경 자체를 릴리스 노트에 남기세요.

프로덕션 누출 검사

진짜 프로덕션 빌드에는 디버거 코드가 전혀 들어가지 않습니다. 활성 분기가 import.meta.env.DEV || (import.meta.env.MODE === 'staging' && import.meta.env.VITE_DEBUGGER === 'on')처럼 정적으로 치환되는 식이라, production(mode !== 'staging')에서는 false가 되어 그 안의 동적 import()가 dead-code로 통째 제거되기 때문입니다(원리는 환경별 설정).

VITE_DEBUGGER 단독 분기 금지

MODE === 'staging'을 AND로 박지 않고 VITE_DEBUGGER만으로 분기하면, 셸/CI 환경변수에 VITE_DEBUGGER=on이 새는 순간 production 빌드에도 디버거가 실립니다(보안 감사가 재현한 누출 경로). 자세한 3층 방어는 보안·누출 차단 을 보세요.

하지만 이건 소비 프로젝트가 분기 코드를 정확히 작성했을 때만 성립합니다. 믿지 말고 검사합니다.

CI 누출 게이트 (소비 프로젝트에 필수)

패키지에 동봉된 게이트를 자사 CI의 blocking(required) 스텝으로 두세요. 실제 배포될 dist를 만든 직후 디버거 마커 3종(__VUE_DEBUGGER__·vue-debugger-host·__vdbgWrapped, minify 보존)을 스캔하고, 잡히면 exit 1로 배포를 차단합니다(런타임 의존성 0).

npm run build                       # 실제 배포 산출물(production)
npx vue-debugger-leak-check dist    # 누출 발견 시 exit 1 → 배포 차단

bin을 못 쓰는 임시 상황의 약식은 grep -rl "__VUE_DEBUGGER__" dist이며, 정식 게이트는 위 명령입니다. 게이트 배선·트립와이어·데이터 거버넌스 등 전체 보안 모델은 보안·누출 차단 에 정리돼 있습니다.

워크숍 유지보수자용 양방향 검사

이 저장소에는 scripts/check-debugger-leak.mjs가 있어 프로덕션엔 없어야 하고 검증(staging) 빌드엔 반드시 있어야 함을 양방향으로 확인합니다(--expect). 이는 워크숍 유지보수자 전용이며, 외부 소비자는 위 동봉 bin(npx vue-debugger-leak-check)을 쓰세요.

로컬에서 소비 프로젝트와 함께 개발 (선택)

배포 전에 실제 소비 앱에서 디버거 변경을 먼저 확인하고 싶을 때, npm link로 로컬 패키지를 연결합니다.

# 1) 디버거를 빌드하고 전역에 링크
cd packages/vue-debugger && npm run build && npm link

# 2) 소비 프로젝트에서 그 링크를 가져다 씀
cd /소비/프로젝트 && npm link @platform/vue-debugger

# 3) 디버거를 고칠 때마다 다시 빌드
cd packages/vue-debugger && npm run build

dist를 소비하므로 매번 빌드가 필요합니다

npm link는 소비 앱이 디버거의 dist(배포 진입점)를 소비하게 합니다. 따라서 디버거 소스를 고쳐도 npm run build를 다시 돌리기 전에는 반영되지 않습니다. 워크숍 내부 소비자(a-solution·playground)는 vite alias로 src를 직접 써서 HMR이 되지만, npm link는 그 경로가 아니라는 점에 유의하세요.

검증이 끝나면 링크를 풀고, 배포 절차(빌드와 배포)를 따르세요. 배포 전 실제 tgz를 신규 소비 앱에 설치해 돌리는 회귀 게이트(npm run verify:debugger)는 검증 빌드에서 다룹니다.