콘텐츠로 이동

분석 신뢰성

이 동작은 0.5.0 이후 출시되지 않은 Go/CLI 변경 사항을 설명합니다.

다음 다섯 가지 소스 처리 명령어(parse, fingerprint, graph show, graph analyze, graph hotspots)에서 사용할 수 있는 플래그는 다음과 같습니다:

플래그 기본값 의미
--include GLOB 모든 지원 소스 일치하는 소스 경로 포함; 여러 패턴을 선택하려면 반복합니다.
--exclude GLOB 없음 일치하는 경로 또는 디렉터리 제외; 여러 패턴을 위해 반복합니다.
--max-file-size BYTES 10485760 (10 MiB) 더 큰 소스 파일 건너뜁니다; 0은 이 제한을 비활성화합니다.
--strict false 스캔 또는 파싱 진단이 발생하면 결과를 내보내기 전에 실패합니다.

패턴은 선택한 입력 디렉터리를 기준으로 슬래시로 구분된 gitignore 스타일의 글로브를 사용합니다. 단일 파일 입력의 경우 패턴은 해당 기본 이름과 일치합니다. 패턴을 따옴표로 묶어 셸이 확장하지 않도록 합니다. 포함 항목은 합집합을 형성하며, 제외 항목이 우선합니다. 포함 항목은 .gitignore, 테스트 필터링 또는 내장 제외 항목을 재정의하지 않습니다. 부정 패턴(!pattern)은 이러한 플래그에서 허용되지 않으며, 별도의 포함 및 제외 컨트롤을 사용합니다.

터미널 창
codeknit parse ./src --include '**/*.go' --exclude '**/generated/' --strict
codeknit fingerprint ./src --max-file-size 2097152 --include '**/*.ts'
codeknit parse ./src/app.go --output-mode inline --format json

디렉터리 스캔은 프로세스 작업 디렉터리와 독립적으로 프로젝트 위치에 대한 조상 및 중첩 .gitignore 파일을 준수합니다. 가장 가까운 .git 디렉터리 또는 작업 트리 마커가 저장소 경계를 설정합니다. 저장소 외부에서는 조상 무시 파일이 여전히 적용됩니다. 무시된 디렉터리 아래의 선택된 하위 디렉터리는 무시된 상태로 유지됩니다. 명시적으로 일반 소스 파일을 선택하면 무시 및 테스트 필터링을 우회하지만, 포함/제외 및 크기 제한은 여전히 적용됩니다.

소스 심볼릭 링크, 디렉터리 심볼릭 링크 및 비정규 소스는 건너뛰고 보고됩니다. 읽기는 스캔 루트에 국한되며, 발견 후 파일이 커져도 크기 제한이 다시 적용되므로 이를 우회할 수 없습니다. 내장 디렉터리 제외 항목에는 .git, .hg, .svn, node_modules, Python 캐시 및 일반적인 Python 가상 환경이 포함됩니다. 테스트 파일은 --collect-test가 설정되지 않는 한 제외된 상태로 유지됩니다.

읽을 수 없는 디렉터리/파일, 무시 파일 읽기 실패, 건너뛴 심볼릭 링크, 과도하게 큰 소스 및 구문 경고는 분석을 불완전하게 만듭니다. 기본적으로 사용 가능한 부분 결과는 유지되며 진단은 stderr에 표시됩니다. 파싱 JSON에는 errors에 경로/이유 기록이 포함되며, SKT에는 [errors]가 인라인으로 또는 warnings.skt에 포함됩니다. 그래프/지문 명령어도 진단을 stderr에 보고합니다. 의도적으로 무시되거나 필터링된 파일은 경고가 아닙니다. --strict는 출력 게시 전에 불완전한 결과를 거부합니다. 지원되는 소스가 선택되지 않은 입력 또는 모든 소스 읽기가 실패한 실행은 항상 실패로 종료됩니다.

TUI는 동일한 심볼릭 링크 정책과 10 MiB 기본값을 사용합니다. 해당 양식은 아직 새로운 선택 및 엄격 플래그를 노출하지 않습니다.

트리 출력은 전체 소스 이름에 .skt를 추가합니다: src/foo.c는 src/foo.c.skt가 되고, src/foo.h는 src/foo.h.skt가 됩니다. 분할 출력은 src/foo.c_part1.skt, src/foo.c_part2.skt 등을 사용합니다. 사전 및 진단 파일은 예약된 이름 dict.skt 및 warnings.skt를 유지합니다. 대소문자만 다른 충돌을 포함하여 충돌하는 출력 경로는 명시적으로 실패합니다.

트리 SKT는 --max-lines가 최소 3이어야 합니다. 각 심볼 청크는 [symbols] 및 ## source-path 헤더를 반복합니다. 엣지만 있는 청크는 [edges]를 포함합니다. 모든 소스 청크는 제한을 준수하며, 사전 및 진단 파일은 별도의 보조 출력입니다. 플랫 SKT는 소스 블록을 그대로 유지하므로 해당 행 제한은 큰 소스 블록에 대한 하드 바운드가 아닌 분할 대상입니다. JSON은 단일 문서이며 행 수로 분할되지 않습니다.

디렉터리 생성은 형제 스테이징 디렉터리에서 완료됩니다. --clean이 없으면 선택한 형식에 대한 기존 생성 출력이 오류를 발생시킵니다. --clean이 있으면 오래된 .skt 파일(SKT 모드) 또는 codeknit.json(JSON 모드)은 성공적인 생성 후에만 교체됩니다. 관련 없는 항목은 보존되며, 충돌이 발생하면 오류가 발생합니다. 소스 디렉터리 또는 그 조상을 출력 디렉터리로 사용하지 마십시오.

게시는 디렉터리별 잠금을 보유하고, 이전 출력을 백업하며, 교체가 실패하면 복원합니다. 프로세스가 디렉터리 이름 변경 사이에 종료되면 다음 호출은 어떤 것도 생성하기 전에 백업을 복원합니다. 형제 .NAME.codeknit.lock 파일은 향후 게시자와 조정하기 위해 의도적으로 유지됩니다. 활성 잠금 또는 복구 백업을 제거하지 마십시오. 두 디렉터리 이름 변경 사이에 짧은 간격이 있으므로 중단 없는 액세스가 필요한 독자는 생성과 조정해야 합니다. 이는 프로세스 실패 복구를 제공하지만 저장소 실패 또는 전원 손실에 대한 보장은 아닙니다.

개별 보고서는 대상 파일을 교체하기 전에 임시 형제 파일에 기록되고 동기화됩니다. 기존 파일은 생성 중에 잘리지 않습니다. 인라인 stdout은 소비자가 실패할 경우 롤백할 수 없습니다.

정확한 일치는 지문 생성이 가능한 선언 중에서 동일한 심볼 범주 내의 정규화된 완전한 토큰 스트림이 동일한 것을 의미합니다. 이는 동일한 소스 텍스트 또는 입증된 의미론적 동등성을 의미하지 않습니다. 정확한 후보 그룹은 퍼지 해시 동등성이 아닌 토큰 스트림 자체를 사용합니다.

500개 미만의 적합한 심볼에서는 구조적 탐지가 동일한 범주의 모든 쌍을 비교합니다. 500개 이상에서는 모든 정확한 토큰 쌍이 후보 검색과 독립적으로 유지되며, 다른 쌍은 심볼당 상위 50개 구조적 이웃을 사용합니다. 따라서 근사 중복 검색은 대규모 입력에서 철저하지 않습니다. 검색은 여전히 모든 벡터를 스캔하며, 전체 알고리즘을 준이차적으로 만들지는 않습니다.

유사도 범위 필터링이 여전히 적용됩니다. 기본 범위는 65~95%이며, 이는 100% 일치를 제외합니다. 정확한 일치를 포함하려면 다음을 사용하십시오:

터미널 창
codeknit fingerprint ./src --min-similarity 100 --max-similarity 100

선택적 --rerank은 의미론적 후보를 추가하고, 코사인 일치를 적용하며, 결합된 점수를 기준으로 필터링합니다. 이는 구조적으로 정확한 후보를 제거할 수 있습니다. 임베딩 텍스트는 추출에 사용된 동일한 제한된 소스 스냅샷에서 가져옵니다. 안정적인 입력과 고정된 점수는 결정론적 순서를 생성하며, 동점도 포함됩니다. 모델 응답 자체는 외부 입력입니다.

internal/emitter/calibration_test.go는 70% 임계값에서 작은 레이블이 지정된 소스 픽스처를 평가하며, 유사도 점수와 별도로 참/거짓 긍정 및 부정, 정밀도 및 재현률을 보고합니다. 이 픽스처에는 하나의 정확한 쌍, 두 개의 근사 클론 쌍 및 세 개의 관련 없는 쌍이 있으며, 500개 심볼 경계 아래와 걸쳐 테스트됩니다. 이는 회귀 검사이며 실제 정확도의 대표적인 추정치가 아닙니다. 더 큰 다국어 교정 및 성능 예산은 로드맵 작업으로 남아 있습니다.