Metadata-Version: 2.4
Name: crawl-scouter
Version: 0.8.1
Summary: Pre-scraping diagnostic tool
Author: Isaac
License: MIT License
        
        Copyright (c) 2026 Isaac
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: protego
Requires-Dist: brotli
Requires-Dist: zstandard
Requires-Dist: selectolax
Requires-Dist: playwright
Provides-Extra: llm
Requires-Dist: anthropic; extra == "llm"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# 크롤링 스카우터 진단기

본격 크롤러를 짜기 전에, URL 하나로 그 사이트가 어떻게 수집 가능한지 진단하는 내부 도구.
설계 문서: `docs/specs/크롤링_스카우터_진단기_설계_v7_확장.md`

## 설치
    pip install -e .
    pip install -e ".[dev]"   # 선택: ruff/mypy 검증 시
    playwright install chromium
    pip install -e ".[llm]"   # 선택: --llm 실제 API 연결 시

## 실행
    scouter --version
    scouter https://example.com/
    scouter https://example.com/ --json
    scouter https://example.com/ --html --out report.html
    scouter https://example.com/ --html --out-dir reports
    scouter https://example.com/ --llm --html --out report.html
    scouter https://example.com/ --agent-prompt --json
    scouter https://example.com/ --ua "Mozilla/5.0 ..."

자동 저장 기본 폴더:
    set SCOUTER_OUTPUT_DIR=D:\reports
    scouter https://example.com/ --html
    scouter https://example.com/ --json

저장 우선순위: `--out` > `--out-dir` > `SCOUTER_OUTPUT_DIR` > stdout

소스 체크아웃 상태에서 직접 실행:
    python scouter.py https://example.com/

## 구성
- schemas.py             : dataclass, enum, 공통 상수
- fetcher.py             : HTTP 클라이언트, delay/UA, HTTP probe
- robots.py              : robots.txt, sitemap 후보 검증
- detection.py           : anti-bot/challenge, Unknown Mitigation, 콘텐츠 프로필
- rendering.py           : framework marker, SSR/CSR 판정
- api_candidates.py      : API 후보 HEAD 검증
- playwright_phase2.py   : Playwright 브라우저 2단계
- llm_layer.py           : 선택 LLM 해석 레이어, 입력 위생, mock/API 호출
- protocol_builder.py    : 실행 프로토콜 JSON 생성, agent prompt
- report_text.py         : 텍스트 리포트
- report_html.py         : HTML 리포트, Best Path/Risk 로직
- scouter.py             : 오케스트레이션, JSON 직렬화, CLI
- bigarray_v0_2.py       : 데이터 배열 선택 점수
- extract_arrays_v0_2.py : HTML/script 배열 후보 추출
- signals_pro.py         : 숨은 API·GraphQL·pagination·selector·encoding·official path 신호

## 문서/산출물
- docs/specs/    : 설계 명세
- docs/memos/    : 메모와 작업 지시
- docs/handover/ : 인계 기록
- QUICKSTART.md   : 외부 검수자용 실행 절차
- artifacts/qa/  : QA summary
- artifacts/zips/: 검수 패키지
- reports/       : 최신 실사이트 리포트
- pyproject.toml : editable install + console entry point
- LICENSE        : MIT License
- CHANGELOG.md   : 릴리즈 변경 이력

## 테스트
    python -m mypy
    cd tests
    python test_v0_1.py                  # v0.1 단위 (18)
    python test_challenge_v0_1.py        # 차단 감지 (9)
    python test_bigarray_v0_2.py         # 데이터 배열 점수 (14)
    python test_extract_v0_2.py          # HTML 추출 파이프라인 (15)
    python test_completeness.py          # 완전성 신호 (7)
    python test_csr_detection.py         # CSR 감지 (5)
    python test_team_review_v0_2.py      # 팀 리뷰 5개 약점 회귀 (22)
    python test_robots_backlog.py        # robots RFC 9309 + redirect (13)
    python test_v0_2_integration.py      # v0.2 연결 (9)
    python test_merge.py                 # pro signals 머지 (5)
    python test_head_verify.py           # §3.5 HEAD 검증 (24)
    python test_antibot_v0_3.py          # §3.3 제공자 식별 + Unknown Mitigation (20)
    python test_selector_encoding.py     # §3.8 selector + §3.9 인코딩 (13)
    python test_official_paths.py        # §3.7 공식 API·한국 라우팅·약관 (14)
    python test_playwright_phase2_v0_4.py # v0.4 Playwright 2단계
    python test_html_report_v0_5.py      # v0.5 HTML 리포트
    python test_challenge_mock_v0_5.py   # v0.5 challenge mock 테스트셋
    python test_challenge_phase2_v0_5.py # v0.5 challenge → Phase 2 확장
    python test_content_profile.py       # div/span 콘텐츠·JS shell 판정 회귀
    python test_modular_imports_v0_5.py  # 모듈 분리 import smoke
    python test_sitemap_validation.py    # sitemap HEAD 검증 false positive 회귀
    python test_llm_layer_v0_7.py        # v0.7 LLM 해석 레이어
    python test_protocol_v0_8.py         # v0.8 실행 프로토콜
    python test_review_improvements_v0_8.py # 외부 리뷰 반영 회귀

## 상태 (2026-06-04 갱신)
완료:
- v0.1 본체 + 차단 게이트 + brotli 수정 (이전 세션)
- v0.2 점수 코어 + HTML 추출 (이전 세션)
- 팀 리뷰 5개 약점 반영 (이번 세션):
  · 승자 점수 절대 임계값(0.30) + meaningful_keys=0 강등
  · VALUABLE/NOISE 키 충돌 해소 (size·color는 NOISE 쪽만 유지)
  · 한국어 키 보강 (이름/가격/평점 등 22개 추가)
  · value_diversity 중첩 dict 처리 명시화 + 표본 가중
  · JSON-LD 단일 객체 후보 등록
- robots 백로그 처리 (이번 세션):
  · RFC 9309 4xx → robots 기준 제한 신호 없음 / 5xx → 보수적 차단
  · redirect_chain·final_url 정보 보존
- v0.2 모듈을 진단봇 본체에 연결 (이번 세션): 마커 발견 시
  SSR_HYDRATED / HYDRATION_NO_ARRAY / HYDRATION_NO_DATA로 분기
- v0.4 Playwright 2단계:
  · CSR/CSR_SUSPECTED/challenge일 때 브라우저 진단 실행
  · 렌더링된 HTML을 1단계 분석에 재투입
  · 실제 XHR/fetch 요청과 설정 쿠키를 리포트/JSON에 기록
  · Playwright 실패 시 1단계 결과만으로 판단하도록 graceful fallback
- v0.5 HTML 리포트:
  · Best Path → Estimated Work → Data Map → Blockers & Risks 순서
  · confidence/evidence는 접힘 상세로 분리
  · robots/challenge/login/PII를 비용·일정 플래그로 표시
  · challenge 통과 시 Phase 2 API/DOM 기반 Best Path로 갱신, 미통과 시 manual_review
- v0.5 challenge mock 테스트셋:
  · 7개 provider + Unknown Mitigation fixture
  · VERIFICATION_GATE 보류와 HTML 리포트 비용 플래그 회귀
- 2차 품질선:
  · sitemap 후보 HEAD Content-Type 검증
  · robots sitemap이 text/html catch-all이면 Best Path에서 제외
  · sitemap 검증 사유를 텍스트/JSON/HTML 리포트에 표시
  · div/span 기반 정적 콘텐츠 카운팅
  · 큰 JS shell을 body_size만으로 STATIC 처리하지 않도록 보정
- 모듈 분리:
  · legacy monolith 삭제
  · 10개 책임 모듈 + scouter.py CLI로 분리
  · import smoke 포함 전체 310 PASS / 0 FAIL
- v0.7 LLM 해석 레이어:
  · LLM off면 기존 JSON/HTML 경로 유지
  · LLM on일 때 구조화 데이터만 위생 처리해 mock/API 호출
  · Executive Brief + data/strategy/gate/terms 해석을 HTML/JSON에 표시
- v0.8 실행 프로토콜:
  · BestPath별 connection_test/collection_plan/storage/verification 생성
  · 민감 header 제외, pagination/retry/storage/verification 규칙 포함
  · agent_prompt 옵션과 HTML/JSON 프로토콜 섹션 제공
- 외부 리뷰 반영:
  · VERSION/UA를 0.8 기준으로 정합화
  · QUICKSTART.md 추가
  · Best Path Trace를 protocol/HTML/JSON에 표시
  · 광고/로그/인증 API 후보를 수집용 API에서 강등
  · protocol 5a 힌트(sample_record_hint, json_path_hints) 추가
  · protocol 5b 힌트(selector_hints, wait_condition) 추가
- 릴리즈 패키징:
  · pyproject.toml, `scouter` console entry point, `--version`
  · MIT LICENSE, CHANGELOG.md, .gitignore 릴리즈 산출물 정리
  · 사용자-facing CLI 에러 메시지 정리

1차 마일스톤:
- 완료. URL 1개로 경량 진단, 필요 시 Playwright 2단계, 텍스트/JSON/HTML 리포트까지 내부 1차 판단 가능.

다음:
- v0.8 QA: 실제 샘플 리포트에서 프로토콜 품질 검수

백로그:
- curl_cffi 차단통과 (소프트콘·philpapers)
