C++ OverFlow

이름의 뜻: 개발 작업을 반복할수록(C++ — C 드라이브가 ++ 되는 비유) C 드라이브가 캐시·빌드 산출물로 가득 차오르는 문제, 그걸 정리하자는 의미입니다.

# C 드라이브의 일생
def work_harder():
    [C++ for work in 매일]   # work 할 때마다 C 가 ++
    print(C)                  # 겁나 큼
    return 멘붕                # 0 아님

개발 환경에 쌓인 캐시, 가상환경, 빌드 산출물 같은 정리 후보를 찾아 용량을 요약하는 로컬 스캐너입니다.

현재 MVP는 Python 프로젝트 주변의 정리 후보를 탐색합니다. 향후 LLM 모델 캐시, C++ 빌드 산출물 등으로 탐색 범위를 확장할 수 있도록 카테고리 규칙을 YAML로 분리해 두었습니다.

주요 기능

• 지정한 경로 아래의 정리 후보 디렉터리와 파일 탐색
• 카테고리별 총 용량, 항목 수, 파일 수 집계
• 삭제해도 되는지 판단하기 쉬운 설명 제공
• outputs/overflow_report.md Markdown 리포트 저장
• config/categories.yaml 기반 규칙 확장

현재 탐색 대상

• Python 바이트코드 캐시: __pycache__, *.pyc, *.pyo
• Python 가상환경: .venv, venv, env, pyvenv.cfg
• pip 캐시
• 빌드 산출물: dist, build, *.egg-info, .eggs
• 테스트/분석 캐시: .pytest_cache, .mypy_cache, .ruff_cache, .tox, htmlcov, .coverage
• Jupyter 체크포인트: .ipynb_checkpoints
• Windows 임시 폴더: %TEMP%, %LOCALAPPDATA%/Temp
• 문서/엑셀/PPT 임시파일과 자동 복구 폴더
• 로컬 LLM 저장소: Ollama, LM Studio, Hugging Face 캐시

설치

Python 3.11 기준으로 확인했습니다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

PowerShell 실행 정책 때문에 가상환경 활성화가 막히면 현재 세션에서만 아래 명령을 실행한 뒤 다시 시도합니다.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

실행

현재 디렉터리를 스캔합니다.

python main.py .

여러 경로를 한 번에 넘길 수도 있습니다.

python main.py C:\Projects C:\Users\me\AppData\Local

인자를 생략하면 사용자 홈 디렉터리를 기준으로 스캔합니다.

python main.py

출력

실행하면 콘솔에 카테고리별 요약이 출력되고, outputs/overflow_report.md가 생성됩니다.

예시:

==================================================
  C++ OverFlow - 스캔 결과 요약
==================================================
  스캔 경로: .
  회수 가능: 903.2 MB
  오류:      0건

  pip 캐시                      883.4 MB  ###################
    - cache                                    883.4 MB
  가상환경 (venv)                  19.8 MB
    - .venv                                     19.8 MB
==================================================
[저장] outputs\overflow_report.md

현재 버전은 정리 후보를 찾고 보고서만 생성합니다. 파일이나 디렉터리를 자동 삭제하지 않습니다.

Markdown 리포트에는 초보자 추천 행동, GUI로 옮기기 쉬운 화면 액션, 위험도, 쉬운 설명, 카테고리별 상위 항목 목록이 포함됩니다. 실제 출력 예시는 docs/sample_report.md 참고.

프로젝트 구조

.
+-- main.py                       # CLI 진입점 (백엔드 단독 테스트용)
+-- requirements.txt
+-- backend/                      # 5단계 워크플로우 모듈
|   +-- __init__.py               # Scanner / Analyzer / Recommender / Reporter export
|   +-- config/
|   |   +-- categories.yaml       # 카테고리 규칙
|   +-- rules/
|   |   +-- loader.py             # YAML 규칙 로더
|   +-- scanner/
|   |   +-- engine.py             # 1) 스캔
|   +-- analyzer/
|   |   +-- analyzer.py           # 2) 분석 및 카테고리별 집계
|   +-- recommender/
|   |   +-- guides.py             # 3) 정리 전략/가이드
|   +-- cleaner/
|   |   +-- executor.py           # 4) 정리 실행 (구현 예정)
|   +-- reporter/
|   |   +-- reporter.py           # 5) 콘솔 요약 + Markdown 리포트
+-- outputs/                      # overflow_report.md 생성 위치
+-- docs/                         # 컨셉/MVP 이미지

워크플로우는 컨셉 이미지와 동일하게 scan -> analyze -> recommend -> clean -> report 5단계로 모듈이 나뉘어 있습니다. 현재 MVP는 4단계(clean)를 제외한 1, 2, 3, 5단계까지 동작하며, 정리 실행은 보고서로만 안내합니다.

규칙 추가

탐색 규칙은 backend/config/categories.yaml에 추가합니다.

기본 형태:

categories:
  my_cache:
    label: "내 캐시"
    phase: 1
    patterns:
      - "**/.my_cache"
    fixed_paths:
      windows: "%USERPROFILE%/.my_cache"
      linux: "~/.cache/my_cache"
      mac: "~/Library/Caches/my_cache"

지원하는 주요 필드:

• label: 콘솔과 리포트에 표시할 이름
• phase: 활성화 단계
• patterns: 스캔 경로 아래에서 찾을 glob 스타일 패턴
• fixed_paths: OS별 고정 탐색 경로
• detect_by_file: 특정 파일이 있으면 그 부모 디렉터리를 후보로 등록
• note: 규칙 설명

개발 메모

검사 명령:

python -m compileall main.py backend
python -m pip check

생성물인 .venv, __pycache__, outputs/*는 Git 추적 대상에서 제외합니다.