[Refactor] preprocessing 동작 보존 정리 — 주석·죽은 코드·포맷 청소

[SepGOM]

[Refactor]preprocessing 동작 보존 정리 — 주석·죽은 코드·포맷 청소

목적

Step 1 preprocessing/*(특히 extractor.py)에 죽은 코드·과거 이력 주석·트레일링 공백이 섞여 있어 읽기·디버깅이 어렵다.
preprocessing/ 폴더 안에서만 동작 보존(behavior-preserving) 청소를 하고, 바깥 API(extract_text, build_sir, extract_context_edges, split_sentences)는 그대로 유지한다.
로직·구조는 바꾸지 않는다. 죽은 코드 제거 · 주석 정리 · 공백 청소만 한다.

브랜치

refactor/v1/sm/preprocessing

범위 (체크리스트)

죽은 코드 제거 (사용처 0 grep 확인된 것만)

• extractor.py _DOMAIN_SCRAPERS dict 제거 — 정의만 있고 미참조 (_run_domain_scraper는 "chosun.com" in domain 하드코딩으로 우회)
• 미사용 import 정리 (segmenter, sir_builder, pdf/* grep 확인 후)
• 제거 금지 확인 — _extract_from_docx(extract_text에서 호출), _extract_entity_refs/_extract_event_refs(sir_builder.py:106-107에서 호출)는 동작에 묶여 있어 남긴다

주석 정리

• extractor.py 과거 이력 주석 정리: [v2에서 누락](L301), [v2에서 버그](L342), _try_trafilatura docstring의 "v2 원본 코드(주석 보존)" 블록(L201–207, 본문과 중복)
• _extract_from_docx / _extract_entity_refs / _extract_event_refs — "미구현 → stub/빈 리스트 반환" 임을 주석으로 명확화 (동작 유지)
• 코드와 어긋난 낡은 설명 주석 갱신
• [김예슬] 등 기여자 표기 주석은 보존
• 헤더 논문 참고 주석 정리 — OCR/PDF 상세 인용 11개 제거(해당 모듈 pdf/로 위임), 직접 사용하는 Trafilatura 출처만 유지
• 위임 맵 낡은 주석 갱신 — URL → Trafilatura (TODO) → (실패 시 LLMScraper 폴백) (URL 추출은 이미 구현 완료)

포맷 청소

• 트레일링 화이트스페이스 제거 (extractor.py 9줄, scraper_sandbox.py 1줄)
• 과도한 빈 줄·들여쓰기 흐트러짐 정돈 (extractor.py L282–284, L361 등)

테스트·확인

• pytest tests/test_pipeline.py 통과 (segmenter / sir_builder 커버)
• 파이프라인 샘플 1~2건(URL/PDF) 추출 본문 길이·내용 리팩 전과 동일 수동 확인
• git diff 검토 — 로직 변경 라인 0 (삭제·주석·공백만)

범위 밖

• extractor.py LLMScraper 분해·구조 변경 ([김예슬] v3 작업물, builder_agent로 이관 예정 → 로직·구조 불변)
• User-Agent 헤더 상수화 등 중복 통합 (이관/김예슬 합의 필요)
• config.preprocessing.* 키 추가, OCR 팩토리 패턴 도입
• DOCX 실제 구현
• structverify/ 루트 공통 모듈 생성

완료 기준

• extract_text(), build_sir(), extract_context_edges(), split_sentences() import 경로·시그니처 변경 없음
• tests/test_pipeline.py 통과
• 변경 범위: structverify/preprocessing/ 내부만, git diff에 로직 변경 라인 없음
• eval 샘플 추출 결과 리팩 전과 동일

후속 취합

• extractor.py LLMScraper → builder_agent.pretrain_domain() 이관 (박재윤·김예슬)
• User-Agent/임계값 상수화, config.preprocessing.* 외부화