docs/ko/repository-discovery.md

# 저장소 탐색 범위 확인

[English](../repository-discovery.md)

QAMap은 import 관계를 찾을 때 먼저 Git이 추적하는 파일과 ignore 규칙에
걸리지 않는 미추적 파일을 확인합니다. Git이 저장소가 아니라고 확인한
경우에만 디렉토리를 직접 탐색합니다. 이 방식은 고정된 디렉토리 제외
규칙을 사용하며 Git ignore 파일은 해석하지 않습니다. Git 자체가 없거나
목록을 읽는 데 실패하면 범위를 넓히지 않고 탐색 불가로 표시합니다.

## 결과 읽기

`qamap qa --format json`의 `importDiscovery`에서 자세한 내용을 확인할 수
있습니다. 기본 출력과 Markdown 보고서에는 요약이 표시됩니다.

| 항목 | 확인할 내용 |
| --- | --- |
| `inventoryFiles` | 목록에 포함된 파일 수입니다. 모두 분석했다는 뜻은 아닙니다. |
| `parsedSources` | JS/TS/Vue/Svelte 파일 중 이번에 분석했거나 이전 import 분석을 재사용한 파일 수입니다. |
| `skipped` | 읽지 않은 경로와 이유입니다. 파일 수 제한, 크기 초과, 지원하지 않는 언어 등을 구분합니다. |
| `inventoryComplete` | 선택한 디렉토리에서 탐색 정책에 따른 파일 목록 수집이 끝났는지 나타냅니다. |
| `fingerprint` | 분석 입력과 탐색 정책이 달라졌는지 비교할 수 있는 값입니다. |

12,000개 소스 파일 제한에 걸린 경로도 목록에서 사라지지 않고
`source-limit`으로 표시됩니다. 너무 큰 파일, 바이너리, 심볼릭 링크,
하위 Git 저장소 등도 별도 사유로 구분합니다.

## 이전 분석 재사용

파일 내용은 매번 다시 읽고 해시를 비교합니다. 내용이 그대로면 이전에
찾아둔 import 관계를 재사용하고, 바뀐 파일만 다시 분석합니다. 프로그램을
종료하고 다시 실행해도 재사용할 수 있습니다. 파일 목록, 경로 별칭,
워크스페이스 패키지 설정이 바뀌면 연결 대상을 잘못 재사용하지 않도록
import 관계를 모두 다시 계산합니다.

전체 JSON의 `importIndexReuse`에서 재사용 여부를 확인할 수 있습니다.
이 값은 **마지막 import 인덱스 갱신**의 내역입니다. 앞선 QA 단계에서 이미
캐시를 만들었을 수 있으므로 명령 전체의 작업량으로 해석하면 안 됩니다.

| 항목 | 확인할 내용 |
| --- | --- |
| `status` | 최초 분석, 전체 재사용, 일부 갱신, 재구축, 비활성화, 사용 불가를 구분합니다. |
| `storage` | 캐시 저장, 변경 없음, 저장 생략, 저장 실패를 구분합니다. |
| `reusedSources` / `rebuiltSources` | 이번 갱신에서 재사용한 파일 수와 다시 분석한 파일 수입니다. |
| `hasBaseline` | 비교할 수 있는 이전 분석이 있는지 나타냅니다. |
| `changedSources` | 이전 분석 이후 추가, 삭제되거나 내용이 바뀐 파일입니다. 비교 기준이 없으면 비어 있습니다. |
| `affectedImporters` | 이전 연결과 현재 연결을 따라 찾은 상위 파일입니다. 설정 변경 시에는 연결이 있는 파일을 보수적으로 포함합니다. 실제 제품 동작에 영향이 있다는 확정은 아닙니다. |
| `reason` | 캐시 손상, 만료, 연결 설정 변경 등 재구축 이유입니다. |

재사용 여부는 `importDiscovery.fingerprint`를 바꾸지 않습니다. 에이전트용
축약 출력에도 이 실행별 집계를 넣지 않습니다.

캐시는 운영체제 임시 디렉토리의 `qamap-import-index-<사용자 ID>`에
저장됩니다. 숫자 사용자 ID가 없는 운영체제에서는 사용자 식별값의 해시를
사용합니다. 저장하는 것은 상대 경로, 내용 해시, 확인된 파일 간 연결입니다.
소스 본문과 원문 import 문자열은 저장하지 않습니다. 그래도 경로는 내부
구조를 드러낼 수 있으므로 비공개 저장소의 캐시도 공개하지 마세요.

지원하는 운영체제에서는 본인만 읽고 쓸 수 있도록 권한을 제한합니다.
심볼릭 링크, 공유 권한의 경로, 분석 대상 저장소 내부 경로는 캐시 저장소로
사용하지 않습니다. 저장소 파일을 변경하지 않으며, 캐시를 지워도 다음
실행에서 다시 분석합니다.

캐시 하나는 최대 8 MiB입니다. 저장이 끝날 때 저장소 8개 분량을 남기고
24시간이 지난 관리 대상 파일을 정리합니다. 동시 저장 중에는 잠시 개수가
늘어날 수 있습니다. 중단된 임시 파일도 24시간 이후 정리 대상입니다.
별도 백그라운드 정리 작업은 없습니다. 캐시가 손상되거나 만료되면 새로
분석하며, Git 탐색이 실패했다고 이전 캐시를 결과로 내보내지는 않습니다.

저장을 끄려면 다음과 같이 실행하세요.

```sh
QAMAP_IMPORT_CACHE=off qamap qa --format json
```

이 기능은 import 구문 분석과 연결 계산을 줄입니다. 모든 파일 읽기를
생략하거나 저장소 전체 QA 분석을 재사용하는 기능은 아니며, LLM 토큰
절감량도 아직 입증하지 않았습니다.

## 주의할 점

- 분석기 파일이라고 해서 모든 수정이 분석 규칙 변경은 아닙니다. 읽기량
  기록만 추가했다면 탐지 결과나 오탐이 달라졌다고 설명하지 않습니다.
  규칙 검증을 제안할 때는 실제 변경 줄의 분석 관련 근거를 확인합니다.
  연결된 파일과 스키마는 참고 근거로 유지하며, 주변 정의 없이는 의미를
  판단할 수 없는 변경은 사람이 검토해야 합니다.
- 이 결과는 **import 탐색 범위**입니다. 저장소의 모든 동작을 이해했거나
  모든 테스트를 확인했다는 뜻이 아닙니다.
- 현재 작업 디렉토리의 파일을 읽습니다. 과거 커밋의 실행 환경을 재현하지
  않으며, 패키지 하나만 선택했다면 다른 패키지까지 확인한 것도 아닙니다.
- 경로만으로도 내부 구조가 드러날 수 있으므로 비공개 저장소의 보고서는
  공개하지 마세요. 소스 본문은 이 탐색 내역에 복사하지 않습니다.
- 기본 분석은 저장소를 변경하지 않으며 실행 상태는 `not-run`입니다.
  위에서 설명한 임시 캐시만 별도로 저장합니다.
- 아래 저장소 근거 인덱스는 import 이외의 구조도 다루지만, 제품 전체의
  동작이나 실제 LLM 토큰 절감량까지 증명하지는 않습니다.

## 검증

전용 테스트는 프로세스 재시작, 파일 수정과 삭제, 별칭 변경, 순환 참조,
캐시 손상과 경로 안전성, 동시 저장, 용량 관리, 저장 비활성화를 확인합니다.
2,005개 소스 파일로 최초 실행, 재사용, 일부 변경, 캐시 없는 실행의
연결 결과와 fingerprint가 같은지도 비교합니다.

```sh
pnpm build
node --test --test-name-pattern="large import inventory" test/import-index-cache.test.mjs
```

출력되는 시간은 해당 환경의 단일 측정값입니다. 고정된 속도 향상이나
LLM 토큰 절감률을 뜻하지 않습니다.

## 저장소 근거 인덱스 (개발 중)

전체 QA JSON의 `repositoryIndex`에는 함수와 import 별칭, export 연결,
테스트 위치, 등록 지점 후보, 검증 설정과 명세 위치가 담깁니다. JS/TS는
TypeScript 구문 분석기를 사용합니다. 코드를 실행하거나 타입을 검사하지는
않습니다. 지원하지 않는 언어와 문법, 읽지 못한 파일, 분석 한도는
`coverage.skipped`에서 확인할 수 있습니다.

반복 실행에서는 내용이 같은 파일의 분석 결과를 재사용합니다. 다만 변경
여부를 확인하려고 파일을 읽고 해시를 계산하는 작업은 남습니다. `reuse`의
`readFiles`, `readBytes`는 읽기 작업이고, `reusedFiles`, `rebuiltFiles`는
재사용하거나 새로 분석한 파일 수입니다. CLI 전체 작업량이나 LLM 토큰
사용량과 혼동하면 안 됩니다.

`repositoryImpact.paths`는 변경한 선언에서 import와 export를 따라가며
관련 테스트와 등록 지점 후보를 찾습니다. 패키지 경계에서도 선언된 연결만
사용합니다. 같은 이름의 무관한 함수나 사용하지 않는 import는 제품 영향으로
추가하지 않습니다. 후보 파일이 여러 개거나 동적으로 모듈을 불러오면
`boundaries`에 확인할 위치를 남깁니다. 모든 결과는 검토용 초안이며,
`not-run`은 테스트를 실행하지 않았다는 뜻입니다.

이 인덱스는 현재 작업 폴더의 파일을 읽습니다. 과거 커밋을 복원한 분석은
아닙니다. 워크스페이스를 지정했다면 인덱스 경로는 워크스페이스 루트 기준이며,
기존 패키지 단위 QA 경로와 기준이 다를 수 있습니다.

캐시는 저장소 밖 임시 폴더의 `qamap-repository-index-<사용자 ID>`에
저장합니다. 소스 본문, 테스트 설명, 명령 본문, 응답 예시는 넣지 않습니다.
구조를 알 수 있는 이름과 경로는 포함되므로 비공개 저장소의 결과는 공개하지
마세요. 스냅샷당 8MiB, 저장소 8개, 24시간 보관 한도를 적용하며, 별도 정리
프로세스는 없습니다. `QAMAP_REPOSITORY_CACHE=off`로 저장을 끌 수 있습니다.

에이전트용 4KB 결과에는 핵심 경로와 확인이 필요한 위치를 남깁니다. 생략한
전체 분석은 로컬 복원 파일에서 확인합니다. 복원 파일에서도 분석기가 원래
지원하지 않는 범위까지 확인했다고 주장하지 않습니다.

## 추가 탐색과 비용 비교

저장소 벤치마크는 같은 파일 내용을 다시 읽은 횟수와 바이트 수, 첫 압축
보고서를 받은 뒤 추가로 호출한 도구를 기록합니다. 일부만 읽었다면 그 부분만
계산합니다. 반복 읽기가 꼭 낭비인 것은 아니며, 압축 때문에 추가 탐색이
발생했다고 단정하지도 않습니다.

실측 시간에는 임시 저장소 준비, 인덱스 사전 생성, 에이전트 작업, 결과 검사와
정리를 포함합니다. 더 적게 읽거나 빨리 끝났더라도 필요한 근거를 놓쳤다면
절감 효과로 인정하지 않습니다. 실제 모델을 호출하지 않는 로컬 검증에서는
토큰 사용량과 실측 시간을 비워 둡니다.

실행 방법과 관측 범위는 [벤치마크 실행 안내](../../scripts/agent-bench/README.md)를
참고하세요. 이 비교는 공개된 가상 저장소만 사용합니다.