번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
코드 인덱스에 언어 지원 추가하기
코드 인덱스는 저장소를 두 개의 티어로 읽습니다.
- 빠른 티어(tree-sitter 문법과 직접 작성한 스캐너)는 모든 커밋에서 모든 파일에 대해 실행됩니다. 청크, 심볼, 호출 엣지를 생성합니다.
- 컴파일러 티어(변경된 파일에 대한 SCIP 인덱서)는 인덱서가 있는 경우 컴파일러 수준으로 정확한 심볼과 엣지를 추가합니다.
빠른 티어에 해당 언어를 처리하는 레인이 있으면 그 언어를 지원하는 것입니다. 코드 인덱스에서 티어에 대한 설명과 각 언어가 제공받는 기능 목록을 확인할 수 있습니다.
단 하나의 규칙: extractor stamp를 건드리지 않는다
빠른 티어 행에는 해당 행을 만든 코드의 버전 스탬프가 들어 있습니다 (server/code/domain/extract/extractor_stamp.py):
- 스탬프는
STAGE_MODULES에 속한 모든 모듈의 코드 토큰(logic_tokens: 주석, 빈 줄, docstring 제외. import는 패키지 경로가 아니라 바인딩되는 이름으로 계산)과STAMPED_GRAMMARS에 있는 grammar(tree-sitter,tree-sitter-cpp,tree-sitter-python,tree-sitter-bash)의 설치된 버전에 대한 sha256입니다. - 스탬프가 바뀌면 ingest 워커는 영향을 받는 언어 계열에 속한, 인덱싱된 모든 네임스페이스의 모든 파일에 대해 변경된 단계(
chunk,symbol,edge,guard)를 속도를 조절한 배치로 다시 도출합니다 (server/code/app/index/ingest_pass.py의_maybe_rechunk). MODULE_LANGUAGES에서 한 계열에만 매핑된 모듈(lang_python.py,ts_*모듈)은 해당 계열의 파일만 다시 처리하게 합니다. 공유 모듈(treesitter.py,chunker.py)이나 핵심tree-sittergrammar가 바뀌면 모든 파일이 다시 처리됩니다.- 대규모 배포에서는 ingest에 몇 시간이 걸립니다.
스탬프가 바뀌지 않는 위치에 새 언어를 추가합니다:
| 파일 | 스탬프에 포함? | 들어갈 내용 |
|---|---|---|
server/code/domain/extract/lang_<lang>.py |
아니요 | 레인: 심볼, include, 호출 지점을 담은 parse_<lang>(path, source) -> ParsedFile. |
server/code/domain/extract/lang_detect.py |
아니요 | LANG_BY_EXTENSION(및 셸 규칙): 어떤 파일이 이 언어에 해당하는지 정합니다. |
server/code/app/index/ingest_parse.py |
아니요 | _PARSERS의 _parse_<lang> 래퍼. 레인에 import가 있으면 ingest_resolve.py에 include 해석을 추가합니다. |
server/code/domain/extract/lane_units.py |
아니요 | grammar가 없는 레인을 위한 공유 헬퍼: span_chunks와 bind_sites 참조 바인더. |
server/code/domain/extract/treesitter.py |
예 | 스탬프된 핵심 언어 전용 lang_for_path. 여기에 확장자를 추가하면 모든 네임스페이스가 다시 청킹됩니다. |
chunker.py, edges_treesitter.py, 그 외 STAGE_MODULES |
예 | 공유 청킹 및 edge 추출. 모두에게 적용되는 추출 방식 자체가 바뀔 때만 변경합니다. |
lang_for_path에 이름이 없는 언어는 lang_detect.py에서 감지하므로, 언어를 추가해도 스탬프는 바뀌지 않습니다. 스탬프된 모듈의 주석과 docstring은 자유롭게 수정해도 됩니다. 이 모듈들은 포매터 대상에서 제외되어 있는데, 포매터가 코드 토큰인 문자열 따옴표를 다시 쓸 수 있기 때문입니다.
server/code/domain/extract/ 아래의 모든 모듈은 STAGE_MODULES의 단계에 속하거나, tests/unit/test_code_extractor_stamp.py의 NON_EXTRACTOR_MODULES에 이유와 함께 명시되어 있어야 합니다. 새 레인 모듈은 NON_EXTRACTOR_MODULES에 넣어야 하며, 그렇지 않으면 해당 테스트가 실패합니다.
1. 레인의 형태 선택
| 형태 | 예시 | 제공해야 할 것 |
|---|---|---|
| 문법 레인 | lang_typescript.py, lang_rust.py, lang_go.py, lang_java.py |
pyproject.toml의 tree-sitter 문법 의존성. 심볼과 호출 지점은 트리에서 추출하며, 청크와 엣지는 공유 청커와 엣지 워커가 만듭니다. |
| 트리 없는 레인 | lang_proto.py, lang_gotemplate.py, lang_hcl.py, lang_k8s.py, lang_jsonnet.py (LANE_UNIT_LANGS) |
직접 작성한 스캐너. ParsedFile.tree는 None으로 유지되며, 청크는 lane_units.span_chunks에서, 엣지는 reference_sites + SITE_RULES를 lane_units.bind_sites로 바인딩해 만듭니다. |
| include 전용 레인 | tla, flatbuffers, cmake, doc (_LANE_INCLUDE_LANGS) |
단순 레인 리졸버가 해석하는 심볼과 include. |
| 임베디드 언어 | Go와 Java 안의 SQL (go_sql_units, java_sql_units), Dockerfile과 Makefile 안의 셸 영역 |
호스트 파일의 파싱에 합쳐지는 유닛(_join_island_symbols). 보통 킬 스위치 설정이 함께 제공됩니다. |
| 청크 전용 | .css, 텍스트 파일 (lang_text.py) |
감지 외에는 필요 없음. 파일은 청크로 나뉘어 검색할 수 있지만 심볼은 없습니다. |
문법 레인의 문법은 STAMPED_GRAMMARS에 포함되지 않으므로, 문법을 업그레이드해도 스탬프가 바뀌지 않습니다. 레인이 자체 행을 다시 도출할 책임을 집니다.
2. 파서 작성
parse_<lang>(path: str, source: bytes) -> ParsedFile은 언어 태그, 심볼(treesitter.Symbol: 한정 이름(qualified name), 종류, 범위, 시그니처), include, 그리고 엣지 단계에 필요한 정보를 반환합니다. 가장 가까운 기존 레인을 따르세요.
- 한정 이름(qualified name)은 언어의 모듈 경로를 따릅니다(Rust: 파일 경로에서 얻은 crate 경로이며,
mod.rs/lib.rs는 해당 디렉터리의 이름이 됩니다). 심볼 id는 한정 이름과 정규화된 시그니처를 해시한 값이므로, 이름이 불안정하면 재인덱싱할 때마다 행이 바뀝니다. - Include는 네임스페이스가 가진 경로를 기준으로 해석합니다(
wanted_paths, 이어서 레인의resolve_imports/resolve_uses를 사용하며ingest_resolve.py에서 호출합니다). 외부 패키지는 추측하지 않고 아무것도 가리키지 않도록 해석합니다. - 호출 엣지는 같은 파일에서 유일한 이름을 먼저 바인딩하고, 그다음 저장소 전체에서 유일한 이름을 더 낮은 신뢰도로 바인딩하며, 이름이 모호하면 바인딩하지 않습니다(트리가 없는 레인에서는
lane_units.bind_sites가 이를 처리합니다). - 컨테이너 종류(클래스, impl 블록)는 레인에 속합니다. 청커의 언어별 테이블에 등록하면
chunker.py가 바뀌고 스탬프가 달라집니다.
레인을 등록합니다.
# server/code/app/index/ingest_parse.py
def _parse_rust(path: str, source: bytes) -> ParsedFile:
from server.code.domain.extract.lang_rust import parse_rust
return parse_rust(path, source)
_PARSERS = {
...
"rust": _parse_rust,
...
}
그리고 LANG_BY_EXTENSION에 확장자(".rs": "rust")를 추가합니다. 래퍼는 레인을 지연 import하므로 선택적 grammar는 계속 선택적으로 남습니다. 새 tree-sitter grammar는 모든 파싱이 가장 먼저 거치는 bounded_parse._LOADERS에도 추가해야 합니다.
3. 레인 테스트
- 레인 테스트,
tests/unit/test_code_lang_<lang>.py는 작은 인라인 소스를 파싱하고 이름, 종류, 범위, include, 엣지를 검증합니다. 문법(grammar)이 없으면 건너뜁니다:pytest.importorskip("tree_sitter_rust").test_code_lang_rust.py와test_code_lang_typescript.py가 모범 사례입니다. -
레인 코퍼스.
tests/fixtures/code_lanes/<lang>/아래에 픽스처를 추가합니다. 직접 만든 합성 코드이거나, 고유한 라이선스를 가진 오픈 소스 발췌본이며, 후자는tests/fixtures/code_lanes/NOTICE.md에 나열합니다.tests/unit/test_code_lanes_corpus.py는 모든 픽스처에서 언어, 심볼, 패싯, include, 엣지를 도출하여tests/fixtures/code_lanes/expected.json과 비교합니다. 다시 생성한 뒤 diff를 검토합니다:python -m tests.code_lanes.corpus --write git diff tests/fixtures/code_lanes/expected.json여기서 값이 바뀌면 모든 네임스페이스에 저장되는 내용이 달라집니다. 반드시 검토하세요.
- 비용 가드.
ingest_parse._PARSERS에 추가한 파서는tests/unit/lane_walks.py에SAMPLES항목이 필요합니다. 그러면tests/unit/test_code_regex_cost.py가 생성된 여러 형태의 입력으로 레인의 실행 시간을 측정하고, 선형을 넘는 탐색이 있으면 실패합니다. - 스탬프 테스트.
tests/unit/test_code_extractor_stamp.py에서 새 모듈을NON_EXTRACTOR_MODULES에 추가합니다. - 검색.
code.search나code.symbol에 좋은 답을 내야 하는 레인이라면, 변경 전과 후에 코드 인텔리전스 게이트를 실행합니다.make bench-code-intel-dry는 질문 세트를 오프라인으로 검사하고,make bench-code-intel은 실제 임베더가 있는 서버를 대상으로 실행합니다. 가짜 임베더는 절대 사용하지 마세요 (벤치마크 실행).
4. 기존 네임스페이스 최신 상태로 갱신하기
스탬프 밖의 레인은 이미 인덱싱된 것을 바꾸지 않습니다. 새 커밋은 해당 레인을 사용하지만, 기존 파일은 이전 행을 그대로 유지합니다(대개 chunk만 있는 상태). 대상을 지정한 backfill로 다시 도출하세요.
git -C <checkout of the repository> ls-files '*.rs' > rust-paths.txt
loom code backfill --org <org> --namespace <code-namespace> --paths-file rust-paths.txt
--paths-file은 브랜치 팁에서 해당 저장소 상대 경로만 다시 수집하며 워터마크는 건드리지 않습니다. 서버의 .env와 저장소 미러가 있는 곳, 예를 들어 workers 컨테이너에서 실행하세요(코드 인덱스 운영).
경고: 변경이 스탬프된 모듈(
chunker.py수정,treesitter.py확장)을 건드려야 한다면 PR에 그 사실을 명시하세요. 해당 변경을 반영하는 모든 배포는 모든 네임스페이스에서 영향받는 계열의 모든 파일에 대해 이동된 단계를 다시 도출합니다.chunker.py변경은chunk만 이동시키고,edges_treesitter.py변경은edge,chunk,guard를 이동시키며, 파서 변경은 모든 단계를 이동시킵니다.
5. 컴파일러 티어 추가하기 (선택 사항)
빠른 티어의 엣지가 모호하고(오버로드, 동적 디스패치, re-export) SCIP 인덱서가 존재한다면 컴파일러 티어가 도움이 됩니다. server/code/domain/index/compiler_tiers.py의 TIERS에 티어 목록이 있습니다. 각 TierSpec은 인덱서(scip-clang, scip-typescript, scip-go, scip-python), 해당 인덱서의 code_index_state 워터마크 키(scip_commit, scip_commit_ts, scip_commit_go, scip_commit_py), 그리고 이를 진행시키는 워커를 지정합니다. 새 티어에는 다음이 필요합니다.
- 커밋 범위에서 변경된 파일에 대해 인덱서를 실행하고 그 출력을 Loom의 JSON 델타로 변환하는 하니스:
scripts/scip_harness/(run_delta.sh,run_typescript_delta.sh,run_python_delta.sh,run_go_monorepo_delta.sh,scip_to_delta.py). - 델타 워커(
server/code/workers/scip_ts_delta.py,scip_py_delta.py,scip_go_delta.py가 모범 사례입니다): 워커의run_pass는 자신의_run_repo를server/code/app/index/compiler_tier.py의run_tier에 넘기며, 이 함수가 엔트리 루프, 실패 격리, 전체 실행 초기화를 담당합니다. 워커에는LOOM_CODE_SCIP_<LANG>_DELTA_ENABLED/_INTERVAL_SECONDS/_TIMEOUT_SECONDS설정이 함께 제공됩니다(워커 추가하기). 외부 생산자는 대신code.scip_ingest로 업로드하며,code_scip_apply워커가 완결된 배치를 적용합니다. code_scip_apply의watermark_key_for에 추가하는 워터마크 키와TierSpec행. 이를 통해code.index_status와 대시보드가 해당 티어를 보고합니다.
컴파일러 티어 행에는 tier='scip'이 지정됩니다. 읽기 시에는 이 행을 빠른 티어와 한정된 심볼 이름(qualified name, 모듈 또는 컨테이너로 한정된 심볼 이름) 기준으로 병합하며, 컴파일러 티어를 우선합니다. 인덱서가 건너뛴 파일과 델타가 반영되기 전의 커밋은 계속 빠른 티어에서 읽습니다.