# pyright_check.py 구조적 개선 — 전 팀 동기화 문제 해결

## 태스크 ID: task-914.1
## 한정위임: 완료까지

---

## 배경

task-909.1에서 `pyright_check.py`의 pyright 환경 설정 문제를 수정함:
- `_find_project_root()` 함수 추가 — pyrightconfig.json을 찾아 프로젝트 루트 반환
- `subprocess.run(..., cwd=project_root)` 으로 올바른 디렉토리에서 pyright 실행

**문제**: 이 수정이 dev5에만 적용되고, dev1/4/6/7은 여전히 구버전.

## 현황 분석

### 파일 위치 (5개 독립 복사본)
- `teams/dev1/qc/verifiers/pyright_check.py` — ❌ 미수정 (109줄)
- `teams/dev4/qc/verifiers/pyright_check.py` — ❌ 미수정 (109줄)
- `teams/dev5/qc/verifiers/pyright_check.py` — ✅ 수정됨 (129줄)
- `teams/dev6/qc/verifiers/pyright_check.py` — ❌ 미수정 (109줄)
- `teams/dev7/qc/verifiers/pyright_check.py` — ❌ 미수정 (109줄)

### 호출 구조
- `teams/devN/qc/qc_verify.py` → `from verifiers import pyright_check` → `pyright_check.verify(file_paths)`
- 각 팀의 `__init__.py`에서 import

### 참고: 이미 존재하는 공유 리소스
- `teams/shared/run_pyright.sh` — 쉘 스크립트 버전, 동일한 프로젝트 루트 탐색 로직 포함 (57~69줄)
- `teams/shared/QC-RULES.md`, `QC-RULES-EXTENDED.md` — 공용 QC 규칙

## 작업 지시

### 1단계: 즉시 수정 — dev1/4/6/7 pyright_check.py 동기화

dev5 버전(`teams/dev5/qc/verifiers/pyright_check.py`)의 내용을 dev1/4/6/7에 동일 적용:

수정 사항 3가지:
1. `import os` 추가
2. `_find_project_root(file_paths)` 함수 추가 (verify 함수 전)
3. `verify()` 내 `subprocess.run()` 호출 전에 `project_root = _find_project_root(py_files)` + `cwd=project_root` 추가

수정 대상 파일:
- `teams/dev1/qc/verifiers/pyright_check.py`
- `teams/dev4/qc/verifiers/pyright_check.py`
- `teams/dev6/qc/verifiers/pyright_check.py`
- `teams/dev7/qc/verifiers/pyright_check.py`

### 2단계: 근본 원인 분석 + 재발 방지 설계

**문제의 본질**: 동일한 코드가 5개 팀에 독립 복사본으로 존재 → 한 곳 수정 시 나머지 동기화 안 됨 (DRY 위반)

개선 방안을 분석하고 **가장 실용적인 방안을 구현**:

#### 방안 A: 공유 모듈 (추천 검토)
- `teams/shared/verifiers/pyright_check.py`에 정본(canonical) 파일 배치
- 각 팀의 `verifiers/pyright_check.py`는 import 위임:
```python
# teams/devN/qc/verifiers/pyright_check.py
from teams.shared.verifiers.pyright_check import verify, MINOR_RULES
```
- **장점**: 한 곳만 수정하면 전체 적용
- **위험**: import 경로 변경으로 기존 qc_verify.py, __init__.py 수정 필요. sys.path 조작 필요할 수 있음.

#### 방안 B: 동기화 검사 스크립트 (안전)
- `teams/shared/sync_verifiers.py` — 모든 팀의 verifier 파일을 비교하여 차이점 감지
- CI/QC 파이프라인에서 주기적 실행, 차이 발견 시 경고
- **장점**: 기존 구조 변경 없음, 안전
- **단점**: 사후 감지 (사전 방지 아님)

#### 방안 C: 심볼릭 링크
- 각 팀의 `pyright_check.py`를 shared 정본으로 심볼릭 링크
- **장점**: 투명, 기존 import 구조 유지
- **위험**: git에서 심볼릭 링크 관리 복잡

**판단 기준**:
- 기존 import 구조(`from verifiers import pyright_check`)를 깨지 않는 방안 우선
- 가장 적은 수정으로 최대 효과
- 구현이 실패할 위험 낮은 쪽

### 3단계: 구현 + 검증

선택한 방안을 구현하고 검증:
1. 수정된 모든 pyright_check.py에서 `verify([])` 호출 정상 동작 확인
2. diff로 5개 팀의 pyright_check.py 동일성 확인 (방안 A/C의 경우 위임 구조 확인)
3. pyright 0 에러 (수정한 파일 대상)

---

## 수정 대상 파일
- `teams/dev1/qc/verifiers/pyright_check.py`
- `teams/dev4/qc/verifiers/pyright_check.py`
- `teams/dev6/qc/verifiers/pyright_check.py`
- `teams/dev7/qc/verifiers/pyright_check.py`
- 방안에 따라 추가 파일 (shared/verifiers/ 등)

## 수정 금지 파일
- `teams/dev5/qc/verifiers/pyright_check.py` (이미 정상, 참조용)
- `teams/devN/qc/qc_verify.py` (방안 B 선택 시 수정 불필요. 방안 A 선택 시에만 최소 수정)

## 참고 파일
- dev5 수정본 (정본): `teams/dev5/qc/verifiers/pyright_check.py`
- 쉘 스크립트 참조: `teams/shared/run_pyright.sh` (57~69줄 프로젝트 루트 탐색)

## 검증 기준
1. dev1/4/6/7의 pyright_check.verify() 호출 시 pyrightconfig.json 위치에서 pyright 실행됨
2. 5개 팀 모두 동일 동작 보장
3. 재발 방지 메커니즘 설명 (보고서에 포함)
4. pyright 0 에러 (수정 파일 대상)