Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Añadir compatibilidad con un lenguaje al índice de código
El índice de código lee un repositorio en dos niveles:
- El nivel rápido (gramáticas de tree-sitter y escáneres escritos a mano) se ejecuta sobre cada archivo en cada commit. Produce chunks, símbolos y aristas de llamadas.
- Un nivel del compilador (un indexador SCIP sobre los archivos modificados) añade símbolos y aristas exactos según el compilador, donde existe un indexador.
Un lenguaje cuenta con compatibilidad cuando el nivel rápido tiene una vía para él. Índice de código explica los niveles y enumera lo que obtiene cada lenguaje.
La regla principal: mantenerse fuera del sello del extractor
Las filas del nivel rápido llevan un sello de versión del código que las produjo (server/code/domain/extract/extractor_stamp.py):
- El sello es un sha256 sobre los tokens de código (
logic_tokens: sin comentarios, líneas en blanco ni docstrings; un import cuenta como los nombres que enlaza, no como la ruta del paquete) de cada módulo deSTAGE_MODULES, más las versiones instaladas de las gramáticas deSTAMPED_GRAMMARS(tree-sitter,tree-sitter-cpp,tree-sitter-python,tree-sitter-bash). - Cuando el sello cambia, el worker de ingesta vuelve a derivar las etapas afectadas (
chunk,symbol,edge,guard) en lotes espaciados para cada archivo de cada espacio de nombres indexado en las familias de lenguajes afectadas (_maybe_rechunkenserver/code/app/index/ingest_pass.py). - Un módulo asignado a una familia en
MODULE_LANGUAGES(lang_python.py, los módulosts_*) solo mueve los archivos de esa familia. Un módulo compartido (treesitter.py,chunker.py) o la gramática principaltree-sittermueve todos los archivos. - En un despliegue grande eso son horas de ingesta.
Añade un lenguaje nuevo donde no mueva ningún sello:
| Archivo | ¿En el sello? | Qué va ahí |
|---|---|---|
server/code/domain/extract/lang_<lang>.py |
no | El carril: parse_<lang>(path, source) -> ParsedFile con símbolos, includes y sitios de llamada. |
server/code/domain/extract/lang_detect.py |
no | LANG_BY_EXTENSION (y las reglas de shell): qué archivos son de este lenguaje. |
server/code/app/index/ingest_parse.py |
no | Un wrapper _parse_<lang> en _PARSERS; resolución de includes en ingest_resolve.py si el carril tiene imports. |
server/code/domain/extract/lane_units.py |
no | Helpers compartidos para un carril sin gramática: span_chunks y el enlazador de referencias bind_sites. |
server/code/domain/extract/treesitter.py |
sí | lang_for_path solo para los lenguajes principales sellados. Añadir una extensión aquí vuelve a fragmentar todos los espacios de nombres. |
chunker.py, edges_treesitter.py, los demás STAGE_MODULES |
sí | Fragmentación y extracción de aristas compartidas. Cámbialos solo cuando la extracción cambie para todos. |
Los lenguajes que lang_for_path no nombra se detectan en lang_detect.py, así que añadir uno no mueve ningún sello. Los comentarios y docstrings de los módulos sellados se pueden editar libremente. Esos módulos están excluidos del formateo, porque un formateador podría reescribir las comillas de las cadenas, que son tokens de código.
Cada módulo de server/code/domain/extract/ está en una etapa de STAGE_MODULES o aparece, con su motivo, en NON_EXTRACTOR_MODULES en tests/unit/test_code_extractor_stamp.py. Pon un módulo de carril nuevo en NON_EXTRACTOR_MODULES, o esa prueba fallará.
1. Elige la forma del lane
| Forma | Ejemplos | Lo que aportas |
|---|---|---|
| Lane de gramática | lang_typescript.py, lang_rust.py, lang_go.py, lang_java.py |
Una dependencia de gramática tree-sitter en pyproject.toml; símbolos y sitios de llamada obtenidos del árbol; los chunks y las aristas provienen del chunker compartido y del recorredor de aristas. |
| Lane sin árbol | lang_proto.py, lang_gotemplate.py, lang_hcl.py, lang_k8s.py, lang_jsonnet.py (LANE_UNIT_LANGS) |
Un escáner escrito a mano; ParsedFile.tree queda en None; chunks de lane_units.span_chunks, aristas de reference_sites + SITE_RULES enlazados mediante lane_units.bind_sites. |
| Lane solo de includes | tla, flatbuffers, cmake, doc (_LANE_INCLUDE_LANGS) |
Símbolos e includes resueltos por el resolvedor de lane simple. |
| Lenguaje embebido | SQL dentro de Go y Java (go_sql_units, java_sql_units), islas de shell en Dockerfiles y Makefiles |
Unidades incorporadas al análisis del archivo anfitrión (_join_island_symbols), normalmente tras un ajuste de interruptor de desactivación. |
| Solo chunks | .css, archivos de texto (lang_text.py) |
Solo la detección: el archivo se divide en chunks y se puede buscar, sin símbolos. |
La gramática de un lane de gramática no está en STAMPED_GRAMMARS, por lo que actualizarla no cambia ningún sello. El lane es responsable de volver a derivar sus filas.
2. Escribir el parser
parse_<lang>(path: str, source: bytes) -> ParsedFile devuelve la etiqueta del lenguaje, los símbolos (treesitter.Symbol: nombre calificado, tipo, rango, firma), los includes y lo que necesita la etapa de aristas. Sigue el lane existente más cercano:
- Los nombres calificados siguen la ruta de módulos del lenguaje (Rust: la ruta del crate a partir de la ruta del archivo;
mod.rs/lib.rsdan nombre a su directorio). El id de un símbolo es un hash del nombre calificado y de la firma normalizada, así que un nombre inestable regenera filas en cada reindexado. - Los includes se resuelven contra las rutas que contiene el espacio de nombres (
wanted_paths, y despuésresolve_imports/resolve_usesen el lane, llamados desdeingest_resolve.py). Los paquetes externos no se resuelven a nada, no a una suposición. - Las aristas de llamada enlazan primero los nombres únicos dentro del mismo archivo, después los únicos en el repositorio con menor confianza, y no enlazan nada cuando un nombre es ambiguo (
lane_units.bind_siteshace esto para los lanes sin árbol). - Los tipos de contenedor (una clase, un bloque impl) pertenecen al lane. Registrar uno en la tabla por lenguaje del chunker modifica
chunker.pyy cambia el stamp.
Registra el lane:
# 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,
...
}
y añade la extensión a LANG_BY_EXTENSION (".rs": "rust"). El wrapper importa el lane de forma diferida, de modo que una gramática opcional sigue siendo opcional. Una nueva gramática de tree-sitter también se añade a bounded_parse._LOADERS, por donde pasa primero cada parseo.
3. Prueba el lane
- Una prueba del lane,
tests/unit/test_code_lang_<lang>.py, analiza pequeñas fuentes en línea y verifica nombres, tipos, rangos, includes y edges. Se omite cuando la gramática no está presente:pytest.importorskip("tree_sitter_rust").test_code_lang_rust.pyytest_code_lang_typescript.pyson los modelos. -
El corpus de lanes. Agrega fixtures en
tests/fixtures/code_lanes/<lang>/: sintéticos, o extractos de código abierto bajo su propia licencia, listados entests/fixtures/code_lanes/NOTICE.md.tests/unit/test_code_lanes_corpus.pyderiva lenguajes, símbolos, facetas, includes y edges de cada fixture y los compara contests/fixtures/code_lanes/expected.json. Regenera y revisa el diff:python -m tests.code_lanes.corpus --write git diff tests/fixtures/code_lanes/expected.jsonUn número que cambia ahí modifica lo que contiene cada espacio de nombres. Revísalo.
- La protección de costo. Un parser agregado a
ingest_parse._PARSERSnecesita una entradaSAMPLESentests/unit/lane_walks.py;tests/unit/test_code_regex_cost.pyluego mide el tiempo del lane sobre formas generadas y falla ante un recorrido que supere el tiempo lineal. - La prueba del stamp.
tests/unit/test_code_extractor_stamp.pycon el nuevo módulo enNON_EXTRACTOR_MODULES. - Recuperación. Para un lane que deba responder bien a
code.searchocode.symbol, ejecuta el gate de code-intelligence antes y después.make bench-code-intel-drycomprueba el conjunto de preguntas sin conexión;make bench-code-intello ejecuta contra un servidor con un embedder real, nunca el falso (ejecución de benchmarks).
4. Actualizar los espacios de nombres existentes
Un carril fuera del stamp no cambia nada de lo que ya está indexado. Los commits nuevos usan el carril; los archivos antiguos conservan sus filas anteriores (a menudo solo con chunks). Vuelva a derivarlos con un backfill dirigido:
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 vuelve a ingerir solo esas rutas relativas al repositorio en la punta de la rama y no modifica la marca de agua. Ejecútelo donde estén el .env del servidor y los espejos de los repositorios, por ejemplo en el contenedor de workers (operaciones del índice de código).
Advertencia: si un cambio debe tocar un módulo con stamp (una corrección en
chunker.py, una extensión entreesitter.py), indíquelo en el PR. Cada despliegue que lo incorpore vuelve a derivar las etapas afectadas para todos los archivos de las familias correspondientes en todos los espacios de nombres. Un cambio enchunker.pysolo muevechunk; un cambio enedges_treesitter.pymueveedge,chunkyguard; un cambio en el parser mueve todas las etapas.
5. Añadir un nivel del compilador (opcional)
Un nivel del compilador compensa cuando las aristas del nivel rápido son ambiguas (sobrecargas, despacho dinámico, reexportaciones) y existe un indexador SCIP. TIERS en server/code/domain/index/compiler_tiers.py enumera los niveles. Cada TierSpec nombra el indexador (scip-clang, scip-typescript, scip-go, scip-python), su clave de marca de agua en code_index_state (scip_commit, scip_commit_ts, scip_commit_go, scip_commit_py) y los workers que la hacen avanzar. Un nivel nuevo necesita:
- Un arnés que ejecute el indexador sobre los archivos modificados de un rango de commits y convierta
su salida al delta JSON de Loom:
scripts/scip_harness/(run_delta.sh,run_typescript_delta.sh,run_python_delta.sh,run_go_monorepo_delta.sh,scip_to_delta.py). - Un worker de delta (
server/code/workers/scip_ts_delta.py,scip_py_delta.pyyscip_go_delta.pyson los modelos): surun_passentrega su_run_repoarun_tierenserver/code/app/index/compiler_tier.py, que se encarga del bucle de entradas, el aislamiento de fallos y el reinicio de la ejecución completa. Viene con sus ajustesLOOM_CODE_SCIP_<LANG>_DELTA_ENABLED/_INTERVAL_SECONDS/_TIMEOUT_SECONDS(añadir un worker). Un productor externo sube los datos mediantecode.scip_ingest, y el workercode_scip_applyaplica los lotes completos. - Una clave de marca de agua en
watermark_key_fordecode_scip_applyy una fila deTierSpec, para quecode.index_statusy el dashboard informen del nivel.
Las filas del nivel del compilador llevan tier='scip'. Las lecturas las combinan con el nivel rápido por nombre calificado, dando preferencia al nivel del compilador. Los archivos que el indexador omite, y los commits anteriores a la llegada de su delta, se siguen leyendo desde el nivel rápido.