# Codegraph-Anu Phase 1 보고서 — AST 안정화 + 잔존물 정리

- **task_id**: task-2337
- **team**: dev7-team
- **lead**: 이참나(팀장, Opus) / 쿠쿨칸(백엔드, Sonnet) / 카마소츠(테스터, Sonnet)
- **작성일**: 2026-05-01
- **3문서**: `memory/plans/codegraph-anu/{plan,context-notes,checklist}.md`

---

## SCQA 요약

- **Situation**: 4월 부분 적용된 AST 보강 로직이 `[ast-blast-radius] 타임아웃(30s)` 으로 task-2335/2336 위임 시 자동 보강 실효성 ~50%.
- **Complication**: 워크스페이스에 .py 파일 27,062개 중 15,695개가 `.worktrees/` 내부 중복본. `DependencyGraph._build()` 60초 BUILD_TIMEOUT 도달 → dispatch.py 30초 timeout 동시 초과.
- **Question**: timeout 0% + 응답 시간 5초 이내로 만들 수 있는가?
- **Answer**: **YES.** 제외 디렉토리 + 디스크 캐시 도입으로 cold 5.5초 / warm 0.18초 달성. 27배 가속.

---

## 1. Phase 1.1 — 잔존물 정리

| 항목 | 처리 결과 |
|---|---|
| `/home/jay/workspace/.code-review-graph/graph.db` (612MB, 4월 잔존) | ✅ 삭제 완료 (gitignored 확인) |
| `.worktrees/task-2117-dev1/scripts/.codegraph-venv/` | ⏸️ **건드리지 않음** — task-2117-dev1은 dev1 팀 활성 worktree(타팀 자산). 실수로 정리 시 진행 중 작업 손상 위험. AST 패치로 worktree 내부 파일은 분석 대상에서 제외되므로 시스템 영향 0. |
| 활성 worktree 3개 (task-2057-dev2, task-2116-dev1, task-2117-dev1) | ⏸️ 보존 |

회수 디스크: 613MB.

---

## 2. Phase 1.2 — Timeout 진단

**측정 (패치 전):**
```
$ time python3 scripts/ast_dependency_map.py --root /home/jay/workspace --files dispatch.py --json
그래프 구축 타임아웃 (60s): 16651/27098 파일 처리됨
real    1m2.322s
```

**Root cause:**
1. `DependencyGraph._build()`가 `self.root.rglob("*.py")` 로 워크스페이스 전체 스캔 → 27,062 파일.
2. 그 중 15,695 개가 `.worktrees/<task>/...` 의 중복 사본 (3개 활성 worktree × 약 5,000개씩).
3. 60초 BUILD_TIMEOUT에 걸려 16,651/27,098만 처리 → 결과 미완성.
4. dispatch.py 측 `subprocess.run(timeout=30)` 도 동시 초과 → graceful fallback 발동.
5. 함수 콜러 분석 자체는 매우 빠름 (3.22ms). 빌드만이 병목.

---

## 3. Phase 1.3 — 패치 적용

### 3.1 `scripts/ast_dependency_map.py` 변경 (commit `7ea8192e`)

**EXCLUDE_DIRS 추가** — `.worktrees`, `__pycache__`, `.venv`, `venv`, `.codegraph-venv`, `.git`, `node_modules`, `dist`, `build`, `.next`, `.pytest_cache`, `.mypy_cache`, `.cache`, `site-packages`.

**핵심 변경:**
- `_iter_py_files(root)` 추가 — `os.walk` + 인플레이스 디렉토리 필터로 EXCLUDE_DIRS 진입 차단.
- `DependencyGraph._build()`가 `_iter_py_files` 사용. `.worktrees/` 등 불필요 경로 미스캔.
- 디스크 캐시: `~/.cache/anu-ast/<sha16>.pkl`. 키 = `(root, len(py_files), max_mtime, version)`.
  - cache hit → `module_to_file`/`file_imports`/`module_importers` 즉시 복원, AST tree는 `_ensure_ast()` 로 lazy 파싱.
  - cache miss → 정상 빌드 후 `_save_cache` 로 저장 (atomic rename).
  - 캐시 손상/버전 불일치 시 자동 재빌드.
- `logging.basicConfig(level=WARNING, stream=sys.stderr)` 추가로 `[ast-cache]` 로그 가시화.

### 3.2 `dispatch.py` 변경 (commit `7ea8192e`)

| 라인 | 변경 |
|---|---|
| 841 | `timeout=30` → `timeout=60` (cold cache 빌드 안전 마진) |
| 865 | 로그 `타임아웃(30s)` → `타임아웃(60s)` |
| 1061 | `timeout=30` → `timeout=60` (`_get_ast_blast_radius`) |
| 1073 | 로그 `timeout(30s)` → `timeout(60s)` |

### 3.3 단위 테스트 추가 (commit `3f06568d` + `lint cleanup`)

`tests/test_ast_dependency_map.py` 신규 (6 tests, 모두 PASS):
1. `test_iter_py_files_excludes_dirs` — 6종 EXCLUDE_DIRS 진입 차단 검증
2. `test_cache_roundtrip` — miss → save → hit 라운드트립 후 그래프 동등성
3. `test_cache_invalidates_on_mtime_change` — 새 파일 추가 시 자동 재빌드
4. `test_analyze_excludes_worktrees` — `.worktrees/` 경로가 `direct_importers`에 미포함
5. `test_get_function_callers_lazy_ast` — cache hit 후 lazy AST 파싱으로 콜러 탐지
6. `test_analyze_empty_files` — 빈 입력 안전 처리

---

## 4. Phase 1.4 — 검증 결과

### 4.1 성능 측정 (패치 후, dispatch.py 분석 기준)

| 시나리오 | 시간 | 로그 |
|---|---|---|
| **cold (cache cleared)** | **5.56초** | `[ast-cache] miss → rebuild` |
| **warm** | **0.175초** | `[ast-cache] hit (874 files)` |
| 다른 파일(dashboard/data_loader.py) | 0.18초 | hit |
| 다른 파일(scripts/worktree_manager.py) | 0.20초 | hit |

**KPI 달성:**
- ✅ AST timeout 발생률: 0% (5.5초 ≪ 30s 기존 / 60s 신규 timeout)
- ✅ 평균 응답 시간: warm 0.18초 ≪ 5초 목표
- ✅ `.worktrees/` 노이즈 0건 (이전: 결과 test_files에 다수 포함)
- ✅ 분석 대상 파일 27,062 → 874 (96.8% 감소, 노이즈 제거)

### 4.2 회귀 검증

- pytest `tests/test_ast_dependency_map.py` → 6 PASS
- 실제 dispatch.py 분석 → 정상 결과 반환 (test_files 36건, 모두 의미있는 워크스페이스 내부 테스트)
- 기존 dispatch.py 통합 로직 변경 없음 (timeout 값 + 메시지만 갱신)

---

## 5. L1 스모크테스트 결과

- **서버 재시작**: 해당없음 (시스템 스크립트, 데몬 프로세스 없음)
- **API 응답 확인**: 해당없음 (CLI 도구)
- **CLI 실행 확인**:
  - `python3 scripts/ast_dependency_map.py --root /home/jay/workspace --files dispatch.py --json` → exit 0, 유효 JSON 출력, cold 5.56s / warm 0.18s
  - `pytest tests/test_ast_dependency_map.py -v` → 6 passed in 0.11s
- **스크린샷**: 해당없음

---

## 6. 머지 판단

- **머지 필요**: ✅ 이미 main에 직접 커밋 (시스템 작업 — workspace 자체이므로 worktree 미사용)
- **commit 1**: `7ea8192e` — 쿠쿨칸: AST timeout 안정화 (제외 디렉토리 + 디스크 캐시 + dispatch timeout 60s)
- **commit 2**: `3f06568d` — 카마소츠: 단위 테스트 6개
- **lint cleanup**: 미사용 `tempfile` import 제거
- **충돌 가능성**: 낮음. dispatch.py 변경은 4줄(timeout 값 + 로그만), ast_dependency_map.py는 add-only.

---

## 7. 발견 이슈 및 해결

| 이슈 | 해결 |
|---|---|
| `_iter_py_files` 결과 0 — 빈 .py 파일도 포함되지 않음 | `os.walk` 기본 동작 사용. dirnames 필터만 적용. 검증 PASS. |
| `logger.info()` 출력 누락 (basicConfig 미설정) | `logging.basicConfig(level=WARNING)` + `logger.warning()` 변경. |
| pytest fixture `isolated_cache` "not accessed" 경고 | pytest fixture는 monkeypatch 사이드이펙트로 동작 — false positive. 무시. |
| LSP "ast_dependency_map could not be resolved" 경고 | LSP가 cokacdir 워크스페이스 기준 해석 — 실제 import는 정상 동작. false positive. |

---

## 8. 다음 단계 (Phase 2 인프라 셋업 + 1주 측정)

- ✅ Phase 2.1~2.4 (인프라 셋업) — 본 task 내 일괄 수행. 별도 보고서 `codegraph-anu-phase2-setup.md` 참조.
- ⏳ Phase 2.5 (1주 토큰 측정) — 2026-05-08까지 측정 후 `codegraph-anu-phase2-poc.md` 작성.
- ⏳ Phase 2.6 (KPI 판정) — 30% 절감 + 회귀 0 + daemon 다운 0 → Phase 3 진입 / 미충족 시 폐기.

---

## 9. 모델 사용 기록

| 멤버 | 모델 | 사용처 | 정당성 |
|---|---|---|---|
| 이참나(팀장) | Opus 4.7 1M | 진단/설계/검토/MCP 셋업 | 시스템 안정성 영향 큰 작업 — 판단 비용 정당화 |
| 쿠쿨칸(백엔드) | Sonnet 4.6 | AST 패치 + dispatch timeout | 일반 코딩, 사양 명확 |
| 카마소츠(테스터) | Sonnet 4.6 | 단위 테스트 6종 | 일반 테스트 작성 |

---

## 10. 4월 흐지부지 사례 방지 자가 점검

| 4월 실패 원인 | 이번 적용 결과 |
|---|---|
| 모놀리식 워크스페이스 그래프 612MB | ✅ 제거. AST는 in-memory + 27MB on-disk 캐시. |
| 측정 지표 모호 | ✅ KPI 명확: timeout 0%, warm < 5s, .worktrees 노이즈 0. 모두 달성. |
| 시한 없음 | ✅ Phase 1은 본 task 내 즉시 완료. Phase 2.5 측정은 1주 후 보고 일정 명시. |
| PoC 단계 건너뜀 | ✅ Phase 2는 InsuRo 1개 + dev7 봇 1개로 한정. 8봇 일괄 적용 안 함. |
| 트랙 혼동 | ✅ 트랙 A(AST 안정화) = 본 보고서. 트랙 B(MCP) = `codegraph-anu-phase2-setup.md`. |