제안: version-pins 핀의 메이저가 산출물이 가정하는 메이저와 일치하는지 검증해요

[DaveDev42]

배경

#31부터 생성 프로젝트의 @apps-in-toss/web-framework 버전은 .github/version-pins/package.json의 정확 버전 핀이 단일 소스이고, Dependabot이 이 디렉터리를 감시해 범프 PR을 열어요.

그런데 #33의 근본 원인을 다시 보면 — 문제의 본질은 "버전이 유동적"이라는 것 이전에 산출물 형상이 가정하는 메이저(3.x의 apps-in-toss.config.ts)와 실제 설치되는 메이저(2.x)가 어긋난 것이었어요. 지금 구조에는 이 메이저 정합성을 지키는 장치가 없어요.

리스크

프레임워크가 다음 메이저(예: 4.0.0)를 발행하면 Dependabot이 3.0.2 → 4.0.0 범프 PR을 열어요. 현재 핀 가드(src/apps-in-toss/version-policy.ts:22)는 semver 형태(^\d+\.\d+\.\d+$)만 검사하고 메이저는 보지 않아서, 그 PR은 CI 전부 green인 채 머지될 수 있어요. 4.x가 config 스키마·산출물 형상을 바꾸는 릴리스라면, 머지 후 첫 릴리스부터 생성 프로젝트가 #33과 같은 형상 불일치로 깨져요. (발행 직후 스모크(#37)가 마지막에 잡아주긴 하지만, 그건 이미 발행된 뒤예요.)

제안

지원 메이저를 소스에 선언하고, 핀과의 일치를 유닛 테스트로 강제해요:

1. version-policy.ts에 지원 메이저 상수 선언 (예: APPS_IN_TOSS_WEB_FRAMEWORK_SUPPORTED_MAJOR = 3) — 산출물 형상을 다음 메이저로 올릴 때 여기만 바꿔요.
2. 핀 버전의 메이저가 이 상수와 일치하는지 검사하는 유닛 테스트 추가.

효과: Dependabot의 patch/minor 범프는 지금처럼 자동으로 흐르고, 메이저 범프 PR만 CI red가 돼요. 메이저 전환은 "테스트가 막아선 것을 사람이 의도적으로 상수와 함께 올리는" 명시적 마이그레이션 커밋이 돼요.

대안 (비교용)

dependabot.yml의 /​.github/version-pins 항목에 ignore: [{ dependency-name: "@apps-in-toss/web-framework", update-types: ["version-update:semver-major"] }]를 추가해 메이저 범프 PR 자체를 막는 방법도 있어요. 설정만으로 끝나는 장점이 있지만, 새 메이저가 나왔다는 사실 자체를 알기 어려워져요(PR이 아예 안 열리므로). 테스트 방식은 PR은 열리되 red가 되어 인지와 차단을 동시에 얻어요. 둘을 병행해도 돼요(ignore로 소음 차단 + 테스트로 안전망).

참고

• fix: 스캐폴딩 실패 시 만든 파일을 보존하고 콘솔 appName을 미리 검증합니다 #36 리뷰 과정에서 나온 아이디어 중 유효하다고 판단해 분리한 항목이에요 (fix: 스캐폴딩 실패 시 만든 파일을 보존하고 콘솔 appName을 미리 검증합니다 #36 본문 "후속 제안").
• 관련: feat: 생성 프로젝트의 web-framework 버전을 검증된 정확 버전으로 고정합니다 #31, package.json에 web-framework 버전이 'latest' 리터럴로 기록돼 dist-tag 상태에 따라 scaffold 직후 빌드가 실패해요 #33, ci: 발행 직후 스모크 테스트 잡을 추가합니다 #37