CLI · 실행

결과 해석과 진단

검색 결과는 선택한 질의·품사·경계·사전으로 확인한 형태 후보입니다. 결과가 없다는 사실만으로 관련 내용이 원문에 없다고 결론 내릴 수는 없습니다. 이 페이지의 진단 명령은 네이티브 CLI 기준입니다.

결과 없음 점검

먼저 종료 코드와 stderr를 확인합니다. 일반 검색에서 1은 일치 없음, 2는 오류입니다. 오류가 없다면 같은 파일에서 조건을 하나씩 비교합니다.

# 검색어와 사전 분석 확인
kfind --explain-query --pos verb 걷다

# 같은 파일에서 경계 조건만 비교
kfind --pos verb --boundary smart 걷다 sample.txt
kfind --pos verb --boundary any 걷다 sample.txt

# 원문에 있는 표기를 알고 있는 경우
kfind --literal 걸었다 sample.txt

any에서만 나오면 경계·구조 조건이 후보를 제한했을 수 있습니다. any는 단어 내부의 불필요한 후보도 포함하므로 주변 문맥을 확인합니다. 두 경계에서 모두 없으면 표제어·품사·표기와 사전 범위를 확인합니다. 오타 교정과 동의어 확장은 지원하지 않습니다.

파일 자체가 검색 대상인지도 점검합니다. 네이티브 CLI의 ignore·glob·인코딩 조건과 npm CLI의 탐색 규칙은 다릅니다. --explain-query는 질의의 분석과 검색 계획을 설명하며, 원문에서 탈락한 모든 후보의 사유를 열거하지 않습니다.

걷다와 걸다는 활용형 걸어가 같으므로, 걷다 검색에 길을 걸어와 전화를 걸어가 모두 나올 수 있습니다. smart도 이 문맥의 의미를 구분하지 않습니다. 형태 후보가 맞는지와 의도한 뜻인지는 별도로 판단해야 합니다.

구조 판정의 한계

구조 검증이 필요한 후보에는 제한된 원문 window를 사용합니다. 기본 제한은 원문 256 byte와 정규화 후 64 Unicode scalar이며 현재 token과 필요한 인접 문맥에 적용됩니다. 입력 파일 전체의 크기 제한은 아닙니다.

Window 추출, 구조 graph 준비나 좌표 정렬에 실패하면 해당 후보를 제외하고 네이티브 CLI는 파일 경로와 structural_verification_incomplete 진단을 stderr에 출력합니다. 이미 찾은 결과는 stdout에 유지하지만 종료 코드는 2입니다. 일반 text, JSON Lines, 집계와 quiet 출력에 같은 계약을 적용합니다.

이 진단은 구조 context를 판정하지 못한 사실을 뜻하며 후보 수는 제공하지 않습니다. 진단이 없다는 사실도 지원하지 않는 활용이나 조기 종료 뒤의 구간까지 검색했다는 보장은 아닙니다. Rust 호출자는 find_all_with_diagnostics와 SearchDiagnostics로 같은 상태를 확인할 수 있습니다. npm CLI에는 이 진단 계약을 적용하지 않습니다.

누락 확인이 중요하면 any와 알려진 원문 표기의 literal 검색을 함께 검토합니다. 이 방법도 지원하지 않는 활용, 오타나 의미 검색까지 복구한다는 보장은 없습니다.

진단 형식

사람이 읽는 진단은 stderr에만 기록하고 검색 결과는 stdout에 유지합니다. 오류 메시지에는 실패한 옵션, 경로 또는 리소스 조건을 포함합니다.

JSON Lines mode에서도 진단을 JSON record에 섞지 않습니다. 호출자는 두 스트림과 종료 상태를 함께 보존합니다.

오류 분류

컴파일 오류에는 빈 질의, tag·전역 POS 충돌, 잘못된 옵션 값과 plan 상한 초과가 포함됩니다. 리소스 오류에는 파일 누락, version·schema·source 불일치와 digest 검증 실패가 포함됩니다.

입력 오류에는 경로 조회, decode와 read 실패가 포함됩니다. 출력 오류에는 broken pipe를 제외한 stdout write 실패가 포함됩니다.

종료 상태

Native CLI는 명령별 종료 계약을 따릅니다. npm CLI는 검색 결과가 있으면 0, 없으면 1, 오류가 발생하면 2를 반환합니다. 셸에서 set -e를 사용할 때는 검색 결과 없음도 허용할지 명시해야 합니다.

부분 stdout이 있어도 최종 상태가 오류면 완결된 결과가 아닙니다.