repo-xray

repo-xray

A repo evidence engine: a script produces machine evidence, and you turn that evidence into short, kind, actionable advice. The reader may be new to coding — plain words, no tool jargon, at most three suggestions at a time unless they ask for a full report.

NO STRUCTURAL CLAIM WITHOUT RUNNING THE SCRIPT
NO ABSENCE CLAIM WITHOUT STATING THE SCAN RANGE
A DEAD "CANDIDATE" IS NOT A VERDICT

If you have not run the script in this session, do not state counts ("unused functions: 12") or absence ("that function doesn't exist"). Run it first, read the JSON, then make the smallest true claim the evidence supports. Cross this line and the tool becomes a confident guesser — exactly the failure it exists to prevent.

Commands

Run from anywhere; point --root at the repo being analyzed.

# Full structure scan -> writes <root>/.repo-xray/report.json
python3 <skill-path>/scripts/audit.py scan --root <repo>

# "Does X exist anywhere?" -> exact hits + similar names, prints JSON
python3 <skill-path>/scripts/audit.py find <name> --root <repo>

<skill-path> is this skill's directory — in plugin installs that is ${CLAUDE_PLUGIN_ROOT}/skills/repo-xray. The scan needs only Python 3 (stdlib) — no installs. Suggest adding .repo-xray/ to .gitignore once, the first time a scan runs in a repo.

실행 시간 — 느린 것 ≠ 멈춘 것

스캔은 저장소 크기에 따라 수 초에서 수십 초가 걸린다(함수가 많으면 near-duplicate 비교가 가장 오래 걸린다). 이건 정상이다. 짧은 타임아웃으로 끊고 다시 돌리지 마라 — 죽은 줄 알고 재실행하면 프로세스만 겹쳐 쌓여 머신이 포화되고 오히려 더 느려진다(관측된 실패 모드다). 오래 걸릴 것 같으면 한 번만 백그라운드로 돌리고 완료를 기다린 뒤 report.json을 읽어라. 스캔은 끝나면 항상 리포트를 쓰므로, 리포트가 없으면 "아직 도는 중"이지 "고장"이 아니다. near_duplicate_scan_truncated: true가 보이면 near-dup만 시간 상한에 걸려 일부 생략된 것이고, 나머지 결과는 완전하다.

Which command for which question

• "중복 코드 있어?", "정리할 것 알려줘", "구조 어때?", "안 쓰는 코드?" → scan, then read report.json.
• "X라는 함수/기능 이미 있어?", "어디서 쓰여?" → find X. If the user describes a behavior rather than a name ("환율 바꾸는 거"), run find on 2-3 plausible names (e.g. exchange, usd_to_krw, convertRate) and also check similar_symbol_names in the output.
• Before writing a new helper the repo might already have → find first.