đŹđ§ English version
Voir aussi : SystÚme de mémoire · Référence YAML · Inventaire des outils · Retour à l'index
RaggableTree
Graphe sĂ©mantique multi-langage du code source : parsing Tree-sitter, enrichissement embeddings, stockage vectoriel, et exposition aux agents via 29 tools. Remplace la lecture de fichiers brute par un index structurĂ© Ă cinq niveaux stratifiĂ©s (L0 monorepo â L1 package â L2 module â L3 symbole â L4 statement) plus la couche d'arĂȘtes entre eux.
Vue d'ensemble
Un agent qui n'a que file_read et directory_read doit lire des fichiers entiers, deviner leurs relations et surcharger son contexte LLM. Le RaggableTree précalcule ces éléments :
- Structure : chaque fichier est décomposé en classes, méthodes, fonctions, avec des Fully-Qualified Names stables (
pkg::Module::Class::method). - Relations : imports, appels, hĂ©ritage et implĂ©mentations sont rĂ©solus Ă partir de l'AST et stockĂ©s comme arĂȘtes du graphe.
- Sémantique : signatures, docstrings, extraits de code et, optionnellement, résumés LLM sont composés en
EmbeddingTextpuis vectorisĂ©s. - Ăvolution : un moteur de rĂ©indexation incrĂ©mentale met Ă jour l'index pour les seuls fichiers modifiĂ©s â Ă la demande (
incremental_reindex, une liste de fichiers ou une plage de commits git) et paresseusement avant la réponse de chaque tool de lecture (voir Fraßcheur).
Les tools exposĂ©s (codebase_map, symbol_detail, flow_trace, impact_analysis, etc.) donnent Ă l'agent des requĂȘtes structurelles au lieu de grep sur du plain-text.
Quick start
using Orkeon.Analysis.Abstractions.DTOs.Tools;
using Orkeon.Analysis.Adapters;
using Orkeon.Analysis.Core;
using Orkeon.Domain.FileSystem;
// fileSystem : IFileSystemService (VFS) avec le projet monté sur /src
var builder = new RaggableTreeBuilder(new TypeScriptAdapter(), fileSystem);
var result = await builder.BuildAsync(
"/src",
new IndexCodebaseRequest { RootPath = "/src" },
CancellationToken.None);
Console.WriteLine($"{result.Tree.Nodes.Count} nodes, {result.Tree.Edges.Count} edges, indexId={result.IndexId}");
Exemples exécutables : basic-indexing (le builder ci-dessus, depuis le C#), crew-yaml (une crew YAML qui utilise les tools via le CLI orkeon standard, qui les enregistre par défaut) et custom-adapter (un nouveau langage).
Pour un usage en DI :
services.AddRaggableTree(new RaggableTreeOptions
{
Embedding = new EmbeddingOptions { Provider = EmbeddingProviderKind.OpenAI, ApiKey = apiKey },
});
services.AddRaggableTreeTools(); // les 29 tools agents (Orkeon.Tools.Analysis)
AddRaggableTree (Orkeon.Analysis.DependencyInjection) enregistre les douze
adaptateurs de langage, les cinq fingerprinters de framework, le summarizer, le
provider d'embedding, le singleton InMemoryRaggableStore (exposé aussi comme
IRaggableStore et IIndexInvalidation), l'IndexFreshnessService, le provider de
diff git, l'IRaggableTreeEventBus, l'ICodebaseContextProvider et les validateurs de
citations. Le runner host appelle plutĂŽt AddRaggableTreeWithLogging(options)
(Orkeon.Infrastructure) : mĂȘmes enregistrements, avec le trafic HTTP d'embedding
OpenAI/Ollama acheminé vers le journal des échanges LLM. Le REPL orkeon-repl appelle
AddRaggableTree avec des embeddings on-device et ne lit aucune section de configuration.
Configuration
La seule surface de configuration que les hÎtes livrés lient est la section
appsettings RaggableTree, lue clé par clé par le runner host (orkeon run et les
autres runners) â il n'existe pas de clĂ© raggableTree: dans le YAML de crew, et le REPL
ne lie rien. Le RaggableTree est actif par défaut dans les deux :
{
"RaggableTree": {
"Enabled": true, // false désactive entiÚrement la feature (opt-out du runner)
"Embedding": {
"Provider": "LocalSmartComponents", // le dĂ©faut du runner â ou None | OpenAI | Ollama (Onnx est un bras no-op rĂ©servĂ©)
"Model": "", // vide â le dĂ©faut du provider
"ApiKey": null, // OpenAI uniquement
"BaseUrl": null, // OpenAI / Ollama
"Dimensions": null, // OpenAI (défaut 1536) / Ollama (défaut 768)
"MaxTextChars": null // plafond par texte cÎté OpenAI
}
}
}
La section porte ces deux clés et rien d'autre : le runner refuse de démarrer sur
toute autre clĂ© sous RaggableTree, en la nommant. Ce que couvre un index se rĂšgle Ă
chaque appel index_codebase (exclude, root_alias, enrich_with_llm,
respect_gitignore, languages, max_parallelism â voir le catalogue de tools),
jamais par l'hĂŽte. Les langages en particulier ne se configurent jamais : ils sont
auto-détectés depuis la codebase et scellés par appel.
Le reste de RaggableTreeOptions est accessible en C# via AddRaggableTree(options) :
Summarizer (Provider = None | Anthropic â ce dernier enregistre
LlmNodeSummarizer sur l'ILlmProvider de l'hĂŽte, et un appel index_codebase avec
enrich_with_llm rĂ©sume alors chaque nĆud ; plus Model, vide par dĂ©faut, ce qui exĂ©cute les rĂ©sumĂ©s sur le modĂšle de
l'ILlmProvider de l'hÎte, et Concurrency, défaut 5) et ValidateCitations (défaut true, enregistre les
validateurs de citations ICitationBlockValidator / IInlineFqnValidator). Le runner
host ne positionne jamais de résumeur : aucun hÎte livré ne génÚre donc de résumés LLM.
à noter : le défaut C# de Embedding.Provider est None ; seul le runner host prend
LocalSmartComponents par défaut.
Tous les champs sont des record immuables dans Orkeon.Analysis.DependencyInjection.RaggableTreeOptions.
Pipeline en six phases
- Discovery (
IFileSystemDiscoverer) â parcours rĂ©cursif, dĂ©tection de packages via markers (package.json,*.csproj,pyproject.toml,go.mod,Cargo.toml,pom.xml,build.gradle,build.gradle.kts,composer.json,Gemfile,CMakeLists.txt), exclusion via patterns et les fichiers d'ignorance de l'arbre tels que git les applique (.git/info/exclude, le.gitignoreracine, chaque.gitignoreimbriquĂ© pour les chemins sous son dossier). Un fichier dont la politique du systĂšme de fichiers refuse la lecture (un droit de montage, une extension bloquĂ©e) est Ă©cartĂ© et comptĂ©, jamais un Ă©chec de toute la construction :index_codebasele signale dansfilter_stats.excluded_by_policyetfilter_stats.excluded_by_policy_paths. - Parse + Extract (
UniversalSemanticMapper+ILanguageAdapter) â Tree-sitter parse â application des queries de l'adaptateur â nĆuds L2 (module) et L3 (symbole) avecFqn,Signature,SourceSnippet,Sha256; statements L4 (StatementExtractor), extraits Ă chaque construction. Les fichiers sont lus et analysĂ©smax_parallelismĂ la fois, puis fusionnĂ©s un par un dans l'ordre de dĂ©couverte : l'index (nĆuds, arĂȘtes, leur ordre,IndexId) est le mĂȘme quel que soit le degrĂ©.incremental_reindexanalyse ses fichiers modifiĂ©s l'un aprĂšs l'autre. - Dependency resolution (
DependencyGraphBuilder+IReferenceResolver) â rĂ©solution des imports, appels, hĂ©ritage, implĂ©mentations en arĂȘtes (EdgeKind.Imports,Calls,Extends,Implements). Les FQN non rĂ©solus deviennent desUnresolvedRef. Une liste de bases C# traceImplementsvers une interface etExtendsvers une classe, comme en Java et en TypeScript. Une base nommĂ©e par son nom court, quand plusieurs types le dĂ©clarent, se rĂ©sout dans cet ordre : la dĂ©claration du fichier du propriĂ©taire ; celle de la portĂ©e nommĂ©e la plus proche qui englobe le propriĂ©taire (son espace de noms, ou un espace de noms ou un type qui le contient ; une dĂ©claration hors de tout espace de noms ou type n'englobe rien) ; celle d'un fichier qu'importe le fichier du propriĂ©taire (un import relatif, un import Python d'un fichier de l'arbre, un module Go ou Rust, unusingC# de son espace de noms) ; le seul type restant. Sinon aucune arĂȘte n'est tracĂ©e : deux espaces de noms dont aucun n'englobe le propriĂ©taire ni n'est utilisĂ©, ou deux modules dont aucun n'est importĂ©, laissent la base sans lien. Les dĂ©clarations d'un mĂȘme espace de noms C# comptent pour un seul type (un type partiel) ; dans un langage Ă modules (TypeScript, Python, Go...) chaque fichier dĂ©clare le sien. - Fingerprinting (
IFrameworkFingerprinter) â application des rĂšgles par dĂ©corateur/annotation (NestJS, Angular, ASP.NET, Flask, FastAPI) : pose de tags commehttp-endpoint,guard,servicesur les nĆuds concernĂ©s. - Enrichissement â optionnellement un rĂ©sumĂ© LLM (
INodeSummarizer, quand l'appel positionneenrich_with_llmet qu'un summarizer est enregistrĂ©), composition duEmbeddingText(IEmbeddingTextComposer), puis embedding batch (IEmbeddingProvider, sautĂ© quand aucun n'est enregistrĂ©). - Persistance â l'arbre vit dans
InMemoryRaggableStore(index_codebaseen remplace le contenu), qui rĂ©pond aussi Ă toutes les requĂȘtes. Quand unIVectorStoreProviderest enregistrĂ©,IndexAsyncreçoit en plus un miroir des embeddings â aucun hĂŽte livrĂ© n'en enregistre (MemoryProviderVectorStoreAdapter,Orkeon.Analysis.Vectors, adapte n'importe quelIMemoryProviderpour un hĂŽte qui le souhaite), et rien ne relit ce miroir. Entre les sessions,index_codebaseenregistre l'arbre dans une base SQLite,<root>/.orkeon/cache/raggable-tree/index.db(voir Cache d'index).
Chaque phase rapporte sa progression (IndexBuildPhase : Discovery, Parse, Resolve, Enrich, Embed, Persist) à un IProgress<IndexBuildProgress> optionnel enregistré par l'hÎte (le REPL le branche sur la barre de progression de sa ligne d'état).
La rĂ©indexation incrĂ©mentale (IncrementalReindexEngine) repart de la phase 2 pour les fichiers changĂ©s uniquement, rĂ©utilise les nĆuds des fichiers inchangĂ©s, et ne lance les phases 4-6 que sur les newNodes.
Documents Markdown
Markdown est un langage de premier rang de l'index, hors du chemin Tree-sitter : les fichiers .md ou .markdown sont découverts comme langage markdown et analysés avec Markdig par MarkdownDocumentMapper (Orkeon.Analysis.Adapters), une lecture par fichier. Chaque fichier produit :
- un nĆud
Sectionpar titre (niveaux 1 Ă 6, FQN imbriquĂ©<fichier>::Titre/Sous, niveau L3) dont la plage court jusqu'au titre suivant de mĂȘme niveau ou supĂ©rieur ; - un nĆud
CodeFencepar bloc dĂ©limitĂ© (le langage est son tag ; un blocmermaidporte aussi le tagmermaid), un nĆudLinkpar lien (tagtarget:<cible brute>, plusresolved:<fqn>quandMarkdownDocumentMapper.ResolveLinksAsyncretrouve la cible dans le store, par chemin ou par nom local ; un lien non rĂ©solu ne garde que sa cible brute) et un nĆudFrontMatterpour un bloc YAML initial (les clĂ©s de premier niveau sont ses tags), tous de niveau L4.
Les plages sont des offsets en octets UTF-8 (NodeRange.StartByte/EndByte), comme pour les autres langages. Les quatre valeurs Markdown de UniversalNodeKind (Section, CodeFence, Link, FrontMatter) sont ajoutĂ©es aprĂšs Unknown car le graphe persistĂ© stocke l'enum par nom ; Control (un bouton, un champ, une liste d'une page web) les suit, pour l'outil firefox, dont PageOutlineMapper projette une page de la mĂȘme façon â une Section par titre ou repĂšre, un Link par lien, un Control par contrĂŽle, dans un magasin propre Ă la page (guide). codebase_search restreint au langage markdown (son option FilterLanguages) renvoie les sections. Limites : un fichier .md n'a pas de nĆud module dans l'arbre, donc un lien fichier vers fichier ne se rĂ©sout que contre un store qui en contient un, et le build n'appelle pas encore ResolveLinksAsync.
Catalogue de tools
| Tool | Usage | RequĂȘte type |
|---|---|---|
index_codebase |
Construit l'index initial | { "root_path": "/src" } |
incremental_reindex |
Met Ă jour l'index aprĂšs modif de fichiers (liste explicite, ou plage git from_commit/to_commit) |
{ "changed_files": ["src/a.ts"] } |
index_status |
Liste les racines virtuelles indexĂ©es (date, comptes de nĆuds/arĂȘtes) | {} |
is_path_indexed |
Vérifie si un chemin est couvert par une racine indexée | { "virtual_path": "/src/app/main.ts" } |
codebase_map |
Vue d'ensemble : packages, compte de fichiers/symboles | { "level": "L2_Module" } |
package_summary |
Résumé d'un package (modules, points d'entrée comme Program.cs ou index.ts, packages que ses modules importent, symboles clés) |
{ "fqn": "app::core" } |
symbol_detail |
Détail d'un symbole (signature, doc, callers, callees) | { "fqn": "app::UserService::create" } |
symbol_source |
Extrait du code source (signature, body, span complet) | { "fqn": "...", "mode": "SignatureAndBody" } |
codebase_search |
Recherche hybride â embedding + BM25 fusionnĂ©s (voir plus bas) | { "query": "session expiration", "top_k": 10 } |
dependency_graph |
Graphe de dépendances à une portée (L1/L2/L3) ; rendu Mermaid/DOT sur include_mermaid / include_dot (désactivés par défaut) |
{ "scope": "L2_Module", "edge_kinds": ["imports", "calls"] } |
sub_graph |
Expansion BFS autour de seeds | { "seeds": ["pkg::X"], "depth": 3 } |
edge_list |
Toutes les arĂȘtes des genres donnĂ©s dans l'index entier, paginĂ©es, extrĂ©mitĂ©s en FQN | { "edge_kinds": ["inherits"], "page_size": 500 } |
flow_trace |
Chemins d'appel entre deux FQN | { "from": "A", "to": "B", "max_paths": 5 } |
impact_analysis |
Impacts transitifs d'un changement | { "target": "...", "direction": "Backward" } |
complexity_report |
Top-N par métrique (Cyclomatic, NestingDepth, FanOut, LoC, Callers) |
{ "metric": "Cyclomatic", "top_n": 20 } |
access_cost |
Coût d'accÚs aux ports (lectures, écritures, appels en boucle, filtres en mémoire) des membres par fqns ou changed_files, restreint à roots |
{ "changed_files": ["/src/Orders/A.cs"], "roots": ["/src/Orders"] } |
statement_query |
RequĂȘtes structurelles L4 (if, try, return...) â chaque index porte les statements | { "parent_fqns": ["..."], "kinds": ["TryCatch"] } |
node_outline |
Membres d'un fichier source (toute grammaire chargée) ou sections Markdown, avec sélecteur, genre, plages d'octets et de lignes | { "path": "/workspace/Calc.cs" } |
node_read |
Un membre par sélecteur : texte, plage et SHA-256, lu sans coupure | { "path": "/workspace/Calc.cs", "selector": "Demo.Calc.Add(int)" } |
node_replace |
Remplace un nĆud par sĂ©lecteur et SHA-256 attendu (classe Edit) | { "path": "/workspace/Calc.cs", "selector": "Demo.Calc.Add(int)", "expected_hash": "<sha256>", "text": "..." } |
node_insert |
Ajoute un nĆud inside, before ou after un sĂ©lecteur d'ancrage (classe Edit) |
{ "path": "/workspace/Calc.cs", "selector": "Demo.Calc", "position": "inside", "text": "public int Zero() => 0;" } |
edit_batch |
Plusieurs opérations node_replace / node_insert sur plusieurs fichiers en une transaction (classe Edit) |
{ "operations": [{ "kind": "node_replace", "path": "/workspace/Calc.cs", "selector": "Demo.Calc.Add(int)", "expected_hash": "<sha256>", "text": "..." }], "validate": "parse" } |
node_ensure |
Applique une opération d'intention idempotente (ensure_using, ensure_import, ensure_field, ensure_member, ensure_section, insert_under_heading, replace_mermaid), voir Opérations d'intention |
{ "op": "ensure_using", "path": "/workspace/Calc.cs", "name": "System.Text" } |
structural_search |
Trouve des nĆuds de syntaxe par motif ou par rĂšgle (classe Read), voir Recherche structurelle | { "language": "cs", "pattern": "Log.Write($X)" } |
structural_rewrite |
Réécrit les correspondances avec un gabarit fix, à blanc par défaut (classe Edit), voir Réécriture structurelle |
{ "language": "cs", "pattern": "Log.Write($X)", "fix": "logger.Info($X)", "glob": "src/**/*.cs" } |
affected_tests |
Projets et classes de test atteints par le graphe depuis les fichiers modifiĂ©s, voir RequĂȘtes sur le graphe | { "changed_files": ["/src/Orders/A.cs"] } |
batch_anchors |
Fermeture d'ancres (contenu, appelants, tests) et recouvrement de deux ensembles d'ancres | { "action": "closure", "fqns": ["Demo.Calc"] } |
documented_in |
Sections Markdown qui documentent un symbole | { "fqn": "Demo.Calc" } |
documents_of |
Symboles documentés par les sections d'un fichier Markdown | { "path": "/workspace/docs/calc.md" } |
Les 29 tools sont enregistrés via AddRaggableTreeTools (Orkeon.Tools.Analysis.DependencyInjection.RaggableToolsExtensions).
index_codebase porte les réglages de construction à chaque appel
(IndexCodebaseRequest) : root_path (obligatoire, un chemin virtuel), languages
(vide = auto-détection), exclude (défaut node_modules, dist, .git, bin,
obj), respect_gitignore (défaut true : .git/info/exclude et chaque .gitignore de l'arbre, lus selon les rÚgles de gitignore(5) : **/ couvre zéro dossier, un /** final couvre tout le contenu, un / en début ou au milieu ancre le motif, une espace finale échappée est conservée ; les classes POSIX telles que [[:alpha:]] ne sont pas prises en charge), enrich_with_llm (défaut false ; exige
un résumeur enregistré), root_alias (remplace le préfixe de racine virtuelle de chaque
FQN), embedding_model, max_parallelism (combien de fichiers sont lus et analysés
à la fois : 0, le défaut, un par processeur ; 1 l'un aprÚs l'autre ; une valeur
négative est refusée) et use_cache (défaut true ; false reconstruit tout, puis
enregistre) â exactement ce que lit la construction. Les statements sont
toujours extraits, et un argument que la requĂȘte ne dĂ©clare pas est ignorĂ©.
incremental_reindex accepte le mĂȘme root_path, plus changed_files ou from_commit/to_commit.
Cache d'index
AddRaggableTree enregistre CachingTreeBuilder, dont index_codebase se sert pour
garder l'index entre les sessions. Chaque construction enregistre l'arbre, le SHA-256, la taille et
l'heure d'écriture de chaque fichier indexé et le SHA-256 de chaque marqueur de paquet dans une seule base SQLite,
<root>/.orkeon/cache/raggable-tree/index.db, dans un dossier qui porte son propre
.gitignore (*). L'appel suivant avec les mĂȘmes options la relit et rĂ©pond cache :
cache |
Quand | Ce qu'il fait |
|---|---|---|
hit |
Aucun fichier n'a changé | Recharge l'arbre enregistré |
refreshed |
Au plus la moitié des fichiers a changé (ajoutés, modifiés, supprimés), aucun marqueur de paquet n'a changé, pas de root_alias |
Recharge l'arbre et réindexe les fichiers modifiés (reindexed_file_count), comme incremental_reindex, puis l'enregistre |
miss |
Rien d'enregistré, une clé changée, un marqueur changé, ou plus de fichiers modifiés | Reconstruit tout, puis enregistre |
bypassed |
use_cache: false |
Reconstruit tout, puis enregistre |
disabled |
L'outil a été construit sans cache (pas d'AddRaggableTree) |
Reconstruit tout, n'enregistre rien |
La clé couvre ce qui façonne l'arbre au-delà des fichiers : les options (languages,
exclude, respect_gitignore, root_alias, enrich_with_llm, embedding_model, pas
max_parallelism), la version de l'assembly Analysis, celle du sérialiseur, et les
adaptateurs, fingerprinters, résumeur et embedder (avec sa dimension et le modÚle qu'il nomme, bge-micro-v2 pour le local) que l'hÎte cùble.
Une clé changée est un miss. Les fichiers d'ignore (chaque .gitignore imbriqué et .git/info/exclude) sont des marqueurs de validité comme les marqueurs de package : un changement force une reconstruction complÚte, et le chemin incrémental saute les chemins ignorés. Une racine que le processus ne peut pas écrire est indexée
sans cache. Seul un fichier corrompu ou qui n'est pas une base (SQLITE_CORRUPT, SQLITE_NOTADB) efface la base du cache ; une base occupée ou verrouillée abandonne l'enregistrement et garde la base.
Schéma de la base
RaggableTreeCache possĂšde la base. Une base garde jusqu'Ă RaggableTreeCache.MaxEntries
(3) index enregistrés cÎte à cÎte, un par clé : deux appelants qui indexent une racine avec
des options différentes retrouvent chacun le sien. Un enregistrement supprime toute entrée
enregistrée par un autre runtime (un autre format de cache ou une autre version de l'Analysis,
la colonne runtime), qu'aucune clé du runtime courant ne peut atteindre, puis évince au-delà de
ce nombre l'entrée utilisée le moins récemment (used_at, que rafraßchissent chaque
enregistrement et chaque hit). La version de son schéma est PRAGMA user_version (3) ;
une base d'une autre version voit ses tables supprimées et recréées à l'enregistrement
suivant, et se lit comme un miss d'ici lĂ . La connexion tourne avec foreign_keys = ON et le
journal en mode WAL.
| Table | Clé primaire | Contenu |
|---|---|---|
cache_entries |
entry_id (alias du rowid) ; cache_key UNIQUE |
Un index enregistrĂ© : sa clĂ©, son identitĂ© et ses arĂȘtes |
indexed_files |
(entry_id, path) (WITHOUT ROWID) |
L'empreinte de chaque fichier indexé d'une entrée |
package_markers |
(entry_id, path) (WITHOUT ROWID) |
Le SHA-256 de chaque marqueur de paquet d'une entrée |
node_groups |
group_id (alias du rowid) ; (entry_id, virtual_path) UNIQUE |
Les nĆuds d'un fichier source d'une entrĂ©e |
node_runs |
(entry_id, position) (WITHOUT ROWID) |
L'ordre des nĆuds d'une entrĂ©e dans son arbre |
Toute autre table nomme son entrĂ©e par entry_id, une FOREIGN KEY â cache_entries (entry_id)
ON DELETE CASCADE : supprimer une entrée supprime avec elle ses fichiers, marqueurs, groupes
et séquences.
cache_entries :
| Colonne | Type | Contrainte | Sens |
|---|---|---|---|
entry_id |
INTEGER |
PRIMARY KEY |
Clé de substitution, référencée par toutes les autres tables |
cache_key |
TEXT |
NOT NULL UNIQUE |
Le SHA-256 de la clé décrite plus haut |
runtime |
TEXT |
NOT NULL |
Le format de cache et la version de l'Analysis qui ont enregistré l'entrée, la part de la clé qu'un autre runtime ne retrouve jamais |
index_id |
TEXT |
NOT NULL |
L'IndexId de l'arbre enregistré |
generation |
INTEGER |
NOT NULL, CHECK (generation > 0) |
Compte les enregistrements sous cette clé, à partir de 1 |
node_count, edge_count |
INTEGER |
NOT NULL |
La taille de l'arbre, pour qui inspecte la base ; le chargement ne les lit pas |
edges |
BLOB |
NOT NULL |
Toutes les arĂȘtes, gzip du tableau JSON des arĂȘtes du sĂ©rialiseur |
saved_at |
TEXT |
NOT NULL |
L'heure UTC du dernier enregistrement, ISO 8601 |
used_at |
TEXT |
NOT NULL |
L'heure UTC du dernier enregistrement ou hit, ISO 8601 ; ordonne l'éviction |
indexed_files :
| Colonne | Type | Contrainte | Sens |
|---|---|---|---|
entry_id |
INTEGER |
NOT NULL, FOREIGN KEY ON DELETE CASCADE |
L'entrée |
path |
TEXT |
NOT NULL |
Le fichier, relatif Ă la racine |
sha256 |
TEXT |
NOT NULL |
Le SHA-256 de son contenu, hexadécimal minuscule |
size_bytes |
INTEGER |
NOT NULL |
Sa taille quand il a été haché |
modified_ticks |
INTEGER |
nullable | Son heure de derniÚre écriture (ticks UTC) quand il a été haché ; NULL quand cette heure n'est pas fiable |
package_markers a entry_id, path et sha256, comme indexed_files. Le constructeur
les compare aux fichiers qu'il découvre pour distinguer un hit, un rafraßchissement ou un miss.
node_groups :
| Colonne | Type | Contrainte | Sens |
|---|---|---|---|
group_id |
INTEGER |
PRIMARY KEY |
Clé de substitution, référencée par node_runs |
entry_id |
INTEGER |
NOT NULL, FOREIGN KEY ON DELETE CASCADE |
L'entrée ; (entry_id, group_id) est aussi UNIQUE, cible de la clé étrangÚre de node_runs |
virtual_path |
TEXT |
NOT NULL, UNIQUE avec entry_id |
Le fichier source des nĆuds (VirtualFilePath) ; les nĆuds sans fichier partagent le chemin vide |
node_count |
INTEGER |
NOT NULL, CHECK (node_count > 0) |
Combien de nĆuds contient nodes |
content_sha256 |
TEXT |
NOT NULL |
Le SHA-256 du JSON non compressé de nodes |
generation |
INTEGER |
NOT NULL |
La génération de l'enregistrement qui a écrit la ligne en dernier |
nodes |
BLOB |
NOT NULL |
gzip du tableau JSON des nĆuds du groupe, dans l'ordre de l'arbre |
node_runs :
| Colonne | Type | Contrainte | Sens |
|---|---|---|---|
entry_id |
INTEGER |
NOT NULL, FOREIGN KEY ON DELETE CASCADE |
L'entrée |
position |
INTEGER |
NOT NULL |
Le rang de la séquence dans son entrée, à partir de 0 |
group_id |
INTEGER |
NOT NULL ; (entry_id, group_id) FOREIGN KEY â node_groups (entry_id, group_id), indexĂ©e (ix_node_runs_group) |
Le groupe dont la sĂ©quence prend ses nĆuds |
node_count |
INTEGER |
NOT NULL, CHECK (node_count > 0) |
Combien de nĆuds la sĂ©quence prend |
La liste des nĆuds de l'arbre n'est pas groupĂ©e par fichier : les nĆuds d'un fichier peuvent
revenir aprÚs ceux d'un autre. node_runs garde cet ordre : le chargement lit les séquences
d'une entrĂ©e par position et chacune prend les node_count nĆuds suivants de son groupe,
si bien que l'arbre se relit dans l'ordre oĂč il a Ă©tĂ© enregistrĂ©. Une sĂ©quence qui demande
plus de nĆuds que son groupe n'en a, ou un groupe dont aucune sĂ©quence ne reprend tous les
nĆuds, fait du chargement un miss. La clĂ© Ă©trangĂšre composite interdit Ă une sĂ©quence de
nommer un groupe qui n'existe pas ou qui appartient à une autre entrée, et interdit de
supprimer un groupe qu'une séquence nomme encore : un enregistrement supprime les séquences
avant les groupes. Le contrĂŽle a lieu Ă la fin de chaque instruction, si bien que la cascade
depuis une entrée supprime ensemble ses séquences et ses groupes.
Un enregistrement est une seule transaction :
- L'entrée de la clé est insérée ou mise à jour (
ON CONFLICT (cache_key) DO UPDATE) : une clé nouvelle part de la génération1, une clé connue l'augmente de un ;saved_atetused_atprennent l'heure courante. - Les
indexed_filesetpackage_markersde l'entrĂ©e sont réécrites. - Les nĆuds sont groupĂ©s par fichier. Un groupe dont le
content_sha256n'a pas changé est laissé tel quel ; un groupe modifié ou nouveau est inséré ou mis à jour (ON CONFLICT (entry_id, virtual_path) DO UPDATE) avec la génération courante ; un groupe dont le fichier a disparu est supprimé aprÚs les séquences. - Les
node_runsde l'entrée sont réécrites. - Les entrées d'un autre
runtimesont supprimées, puis les entrées au-delà deMaxEntries, parused_atdepuis la plus récente, et leurs lignes avec elles.
AprÚs le commit, une base dont les pages libres dépassent la moitié de ses pages (une grande
entrĂ©e vient d'ĂȘtre supprimĂ©e) est compactĂ©e par VACUUM, et le fichier rĂ©trĂ©cit sur le disque ;
en deçà , l'enregistrement suivant réutilise les pages libres. Une compaction qui échoue (une base
occupée, pas de place pour la copie) laisse les entrées enregistrées telles quelles, et
l'enregistrement suivant réessaie.
Un rafraßchissement qui réindexe trois fichiers réécrit donc trois groupes, pas tout l'arbre.
Un chargement qui échoue (un fichier qui n'est pas une base SQLite, une table absente, un blob
qui ne se décompresse ou ne se désérialise pas, des séquences et des groupes qui ne concordent pas) est un miss.
Un enregistrement qui échoue sur une erreur SQLite supprime la base avec ses fichiers -wal
et -shm et réessaie une fois.
Empreintes des fichiers
Découvrir les fichiers les hache tous, ce qui lit chaque octet de la racine à chaque appel.
Comme git status, le constructeur passe au découvreur les empreintes qu'il a enregistrées :
un fichier dont la taille et l'heure de derniÚre écriture égalent son empreinte garde le
SHA-256 enregistrĂ© sans ĂȘtre lu (le dĂ©couvreur vĂ©rifie quand mĂȘme que le VFS l'autorise Ă le
lire). Une empreinte ne garde l'heure d'écriture que si elle précÚde de plus de deux secondes
le dĂ©but de la dĂ©couverte ; un fichier Ă©crit dans cette fenĂȘtre, ou aprĂšs, est enregistrĂ©
avec modified_ticks à NULL et haché de nouveau à l'appel suivant, si bien qu'une
modification faite pendant une construction, ou sous la résolution de l'horloge, n'est jamais
masquée. L'empreinte ne voit pas une modification qui garde à la fois la taille et l'heure
d'écriture (un outil qui restaure l'heure) ; use_cache: false reconstruit depuis le contenu.
Stratégies d'agents
Le framework expose ICodebaseContextProvider qui produit un rĂ©sumĂ© compact du codebase (packages, top complexitĂ©, top couplage, patterns dĂ©tectĂ©s) adaptĂ© au system prompt d'un agent. Trois formats : markdown (dĂ©faut, ~300 tokens), compact (~150 tokens), json (~400 tokens). Aucun composant du framework ne l'appelle automatiquement â il est enregistrĂ© par AddRaggableTree et l'hĂŽte le rĂ©sout et injecte le rĂ©sumĂ© lĂ oĂč il le souhaite.
Recherche hybride
codebase_search (et IRaggableStore.SemanticSearchAsync) est hybride : un
classement cosinus par embeddings et un classement lexical BM25
sont fusionnés par Reciprocal Rank Fusion (SemanticQuery.Mode : Hybrid par défaut /
Vector / Lexical). Le versant lexical utilise un tokenizer conscient du code
(CodeTokenizer) : les identifiants sont découpés aux frontiÚres camelCase / snake_case /
chiffres et indexés à la fois en sous-tokens et en entier
(getUserById â get user by id getuserbyid), de sorte que les requĂȘtes par identifiant
exact gardent leur signal fort tandis que les requĂȘtes conceptuelles gagnent en rappel.
Chaque SearchHit porte MatchOrigin (hybrid/vector/bm25) ; les scores hybrides
sont des agrĂ©gats de rangs RRF (pas des similaritĂ©s â ne jamais les comparer entre
origines). Sans embedder cùblé, Hybrid dégrade vers Lexical au lieu de renvoyer vide ;
un Vector explicite ne renvoie aucun résultat sans embedder.
FraĂźcheur (coordination Ă©dition â recherche)
L'index reste fidÚle à un workspace en cours d'édition grùce à une conception mark-dirty + réindexation paresseuse :
- Hook d'Ă©criture â
FileWriteToolprend unIIndexInvalidationoptionnel (enregistrĂ© parAddRaggableTree, implĂ©mentĂ© par le store) : chaque Ă©criture rĂ©ussie marque son chemin comme sale. O(1), synchrone, no-op hors des racines indexĂ©es. - Passe paresseuse â les tools de lecture (
codebase_search,symbol_source,flow_trace,codebase_map) appellentIndexFreshnessService.EnsureFreshAsyncavant de rĂ©pondre : l'ensemble sale âȘ les changements du working tree git (attrape les Ă©ditions viashell_command) est rĂ©indexĂ© incrĂ©mentalement â groupĂ©, single-flight, avec debounce (une sonde git propre fait foi pendant 2 s). Les rĂ©ponses decodebase_searchrapportentrefreshed_files;index_statusrapportedirty_count/dirty_paths, de sorte que le « pĂ©rimĂ© » est observable. - SĂ»retĂ© du store â
InMemoryRaggableStoredĂ©tient unReaderWriterLockSlim: les recherches Ă©numĂšrent en sĂ©curitĂ© PENDANT une rĂ©indexation incrĂ©mentale. Le rafraĂźchissement publieRaggableTreeUpdatedsur l'IRaggableTreeEventBus. - Borne â la rĂ©indexation remplace les nĆuds et arĂȘtes de chaque fichier modifiĂ© et
rĂ©utilise tous les autres nĆuds : son coĂ»t est proportionnel aux fichiers modifiĂ©s, pas
au dépÎt ; un fichier de 2 000 lignes se réindexe en moins de 2 s.
incremental_reindexrapporte les totaux de l'index (node_count,edge_count), les fichiers analysĂ©s et la durĂ©e mesurĂ©e par le moteur. - BarriĂšre d'Ă©chec â un rafraĂźchissement en Ă©chec sert l'index courant (pĂ©rimĂ©) et conserve la dette de saletĂ© pour la tentative suivante : un rĂ©sultat pĂ©rimĂ© vaut mieux qu'une recherche morte.
Il n'existe pas de mode de synchronisation piloté par un watcher : ICodebaseWatcher
(FileSystemWatcherCodebaseWatcher, qu'aucun hÎte livré n'enregistre) reste disponible pour
les hÎtes qui veulent une invalidation poussée en plus de la passe paresseuse.
Sélecteurs
node_outline et node_read adressent une déclaration d'un fichier par un sélecteur, sous l'une de trois formes :
- Lisible :
Ns.Type.Member(paramTypes), p. ex.Demo.Calc.Add(int). Les types de paramÚtres sont optionnels et requis seulement quand des surcharges existent ; une surcharge ambiguë est une erreur qui liste les sélecteurs candidats. - Markdown :
Section/Sub(chemin de titres), servi pour les fichiers.mdet.markdown: une section va de son titre Ă la ligne prĂ©cĂ©dant le titre suivant de mĂȘme niveau ou supĂ©rieur. Des titres frĂšres de mĂȘme nom sous un mĂȘme parent se distinguent par un ordinal Ă partir de 1 sur n'importe quel segment :A/Notes[2],A[2]/Notes[1]. Sans ordinal, un chemin ambigu est une erreur qui listeA/Notes[1],A/Notes[2]; le plan montre la forme avec ordinal pour les doublons (etA[2]/Notespour leurs descendants) et la forme simple pour un nom unique. Un ordinal Ă©gal Ă 0 ou au-delĂ des frĂšres est une erreur de sĂ©lecteur introuvable. - Repli :
@ts:<node-path>, le chemin tree-sitterroot/<index>/<kind>/...(indexla position Ă partir de 0 parmi les enfants nommĂ©s), pour un nĆud que la forme lisible ne peut pas nommer.
Un sĂ©lecteur rĂ©sout exactement un nĆud ou Ă©choue en listant les candidats. L'Ă©tendue d'un nĆud inclut ses commentaires de tĂȘte et ses attributs ou dĂ©corateurs.
Grammaires livrĂ©es (LanguageRegistry.Shipped) : typescript (.ts, .tsx), python (.py), csharp (.cs), go (.go), rust (.rs), javascript (.js, .jsx, .mjs, .cjs), java (.java), c (.c), cpp (.cpp, .cc, .cxx, .hpp, .hh, .hxx, .h), php (.php), ruby (.rb), bash (.sh, .bash), markdown (.md, .markdown). Un en-tĂȘte .h est lu en C++, sur-ensemble qui parse aussi les en-tĂȘtes C. Le registre charge aussi tsx, agda, css, embedded-template, haskell, html, jsdoc, json, julia, ql, razor, scala et verilog : aucun adaptateur ne les indexe et la dĂ©couverte ne rĂ©clame pas leurs fichiers. OCaml (pas de build macOS dans le paquet) et les grammaires swift, toml et tsq, propres Ă Windows, sont Ă©laguĂ©es Ă la publication.
Les outils de nĆuds et les outils structurels lisent un fichier dans toute grammaire de LanguageRegistry.Parseable : les grammaires indexĂ©es ci-dessus, .tsx Ă©tant lu par la grammaire tsx, puis tsx (.tsx), agda (.agda), css (.css), embedded-template (.erb, .ejs), haskell (.hs), html (.html, .htm), json (.json), julia (.jl), ql (.ql, .qll), razor (.cshtml, .razor), scala (.scala, .sc) et verilog (.v, .sv, .vh, .svh) ; jsdoc ne rĂ©clame aucune extension. Un fichier dont l'extension n'est rĂ©clamĂ©e par aucune grammaire est refusĂ© par son nom. La forme lisible nomme les dĂ©clarations en C#, TypeScript, JavaScript, Python, Go (une mĂ©thode est Type.Methode), Rust (les fonctions d'un bloc impl se rangent sous son type), Java, C et C++ (par dĂ©clarateur : n::A::g pour une dĂ©finition hors classe), PHP, Ruby, Bash, Scala, Julia et JSON (le chemin des clĂ©s, a.b) ; les sections en Markdown. Un fichier oĂč aucun genre de dĂ©claration n'est connu (CSS, HTML, Haskell, Verilog...) a pour plan les chemins @ts: de ses nĆuds de premier niveau, Ă travers un nĆud englobant unique (@ts:document/0/element/2/element). Le receveur d'une mĂ©thode (self en Rust, self ou cls en Python) ne compte pas parmi ses types de paramĂštres.
node_outline liste les membres avec sélecteur, genre, plage d'octets et plage de lignes. node_read renvoie le texte d'un membre, sa plage et le SHA-256 de ses octets, sans coupure : l'outil porte sa propre borne de résultat (node_read = 256 000 caractÚres dans AgentDefaults), la coupure par défaut des résultats d'outil ne s'applique donc pas.
Ăditeur structurel
node_replace remplace un nĆud (sĂ©lecteur de node_outline, hash de node_read) via StructuralEditEngine :
- Ăpissure d'octets : seuls les octets du nĆud changent ; le reste du fichier est identique Ă l'octet prĂšs.
- Refus d'un hash pĂ©rimĂ© : le SHA-256 courant du nĆud est comparĂ© Ă
expected_hashavant toute écriture ; un écart est refusé par uneStaleHashExceptionqui nomme le hash attendu et le hash réel. - Validation par ré-analyse : le résultat est analysé de nouveau et les diagnostics comparés par position ; un remplacement est refusé s'il introduit un diagnostic absent avant (Markdown n'a pas de validation d'analyse).
- Ătendue remplacĂ©e : elle inclut les commentaires et attributs de tĂȘte du nĆud, donc un remplacement qui les omet les supprime. Une section Markdown remplace aussi ses sous-sections.
- Fins de ligne du remplacement normalisées sur celles du fichier.
- Ăcriture : protĂ©gĂ©e par une copie de sauvegarde restaurĂ©e en cas d'Ă©chec. Elle n'est pas atomique.
- Un refus (hash périmé, erreur d'analyse, montage en lecture seule, chemin hors de la racine de travail de l'agent) est un résultat en échec, fichier intact ; une écriture réussie marque l'index sale.
Opérations d'intention
node_ensure et le champ op de edit_batch appliquent une opération idempotente ; chacune est un no-op qui n'écrit rien et renvoie applied: false quand sa cible est déjà satisfaite.
| Opération | ParamÚtres | RÚgle d'idempotence | RÚgle de placement |
|---|---|---|---|
ensure_using |
name |
le using est déjà présent | dans le bloc des using, à sa place triée |
ensure_import |
name, module |
l'import est déjà présent | dans le bloc des imports |
ensure_field |
selector (type), text |
un membre de ce nom existe | prĂšs des champs du type |
ensure_member |
selector (type), text |
un membre de ce nom existe | prĂšs des membres du type |
ensure_section |
name (chemin de titres), level? |
chaque titre du chemin existe | titres manquants ajoutés en fin de fichier, chacun au niveau de sa profondeur |
insert_under_heading |
selector (titre), text |
aucune : ajoute toujours | en fin de section, avant le titre suivant de mĂȘme niveau ou supĂ©rieur |
replace_mermaid |
selector (section), index (base 0), text |
le corps du bloc vaut déjà text |
seul le corps du n-iÚme bloc mermaid (``` ou ~~~) de la section et de ses sous-sections change ; moins de blocs : refusé, fichier intact |
Types de graphe
GraphKindNames (Orkeon.Analysis.Abstractions) fait correspondre des noms de workflow en minuscules aux énumérations existantes.
| Nom d'arĂȘte | EdgeKind |
|---|---|
contains |
Contains |
calls |
Calls |
imports |
Imports |
inherits |
Extends + Implements |
extends |
Extends |
implements |
Implements |
tests |
Tests |
documents |
Documents |
project_depends |
ProjectDepends |
| Nom de nĆud | NĆud du graphe |
|---|---|
file |
nĆud fichier (Module) |
project |
nĆud Package d'un csproj ou package.json marqueur |
namespace |
Namespace |
type |
classe, interface, trait, struct, enum, record, type |
member |
fonction, méthode, constructeur, destructeur, opérateur, propriété, champ, constante, variable |
doc_section |
Section |
test |
nĆud Method portant le tag test |
EdgeKind compte aussi Tests, Documents et ProjectDepends (flags 1<<5 Ă 1<<7). Il n'y a pas de genre references : rien ne le produit. Les arĂȘtes documents relient une section Markdown aux symboles qu'elle nomme (voir RequĂȘtes sur le graphe).
Utiliser les noms
edge_kindsetnode_kindsdedependency_graphetsub_graph, ainsi queedge_kindsdeflow_traceetedge_list, prennent les noms de workflow en minuscules, sans tenir compte de la casse (Importsvautimports). Un nom inconnu est refusĂ©, en le nommant. Les rĂ©ponses Ă©crivent un genre sous la mĂȘme forme en minuscules, si bien qu'un script peut renvoyer ce qu'il a lu :edges[].kindvautimports,project_depends,extendsouimplements(une arĂȘte est l'un ou l'autre, jamaisinherits), et une combinaison joint ses noms par,(imports, calls). Toute Ă©numĂ©ration[Flags]scalaire d'une requĂȘte ou d'une rĂ©ponse d'outil prend cette forme (noms des membres en snake_case joints par,) :symbol_detailprendexpand: "members"ou"callers, callees"; un nombre est refusĂ©.edge_listparcourt l'index entier, contrairement Ădependency_graph, dontmax_nodesborne les nĆuds avant que les arĂȘtes soient collectĂ©es : toutes les classes de base d'une codebase, c'estedge_kinds: ["inherits"]. Ses arĂȘtes sont triĂ©es par FQN source, FQN cible, genre et id d'arĂȘte ;next_cursor(null sur la derniĂšre page) reprend aprĂšs la derniĂšre arĂȘte renvoyĂ©e, si bien qu'aucune page n'est rĂ©pĂ©tĂ©e ni sautĂ©e tant que l'index ne change pas.totalcompte toutes les arĂȘtes retenues,root_fqngarde les arĂȘtes dont une extrĂ©mitĂ© est ce nĆud ou se trouve sous lui (un paquet ou un fichier par chemin, un type ou un membre par FQN avec frontiĂšre, un espace de noms par ses fichiers et son nom), etpage_sizeva jusqu'Ă 1000 (200 par dĂ©faut).from/tosont des FQN,from_id/to_idles ids de nĆud qu'Ă©critdependency_graph; une extrĂ©mitĂ© hors de l'index garde son id dans les deux.symbol_detailavecexpand: "inheritance"listeextendsetimplementsen FQN, et ce qui pointe vers le symbole :derived_by(les types qui l'Ă©tendent) etimplemented_by(les types qui l'implĂ©mentent).flow_tracesuitcallsquandedge_kindsest vide ;inheritssuit Ă la foisextendsetimplements.codebase_searchmettruncatedquand il a renvoyĂ©top_krĂ©sultats, et aussi quand son prĂ©filtre de genre ou de langage a retenu plus que les 1000 nĆuds qu'il classe.- Quand
node_kindsest donnĂ©,dependency_graphrespecte toujoursScope: les genres et les tags passent dans la requĂȘte de nĆuds, etMaxNodesborne le rĂ©sultat. dependency_graphnomme ses cycles :cyclesliste chaque composante fortement connexe de la portĂ©e sous la forme{ fqns, member_count, edge_kind }, la plus grande d'abord, les membres en FQN (la forme denodes[].fqn).max_cycles(20 par dĂ©faut) etmax_cycle_members(50 par dĂ©faut) bornent la liste,cycles_truncateddit si l'un des deux l'a coupĂ©e, etmetrics.cycle_countgarde le compte complet. Les cycles suivent les mĂȘmes genres d'arĂȘtes queedges(les imports quandedge_kindsest vide), etedge_kindles nomme tous (imports, calls).cyclesetcycle_countcouvrent toute la portĂ©e ;node_countetedge_countcouvrent les nĆuds renvoyĂ©s, quemax_nodes,root_fqnetnode_kindssĂ©lectionnent.
Construction du graphe
ProjectGraphBuilderlit chaque csproj dĂ©jĂ trouvĂ© par le dĂ©couvreur (une lecture par csproj) et transforme chaqueProjectReferenceen arĂȘteproject_depends(\et..sont normalisĂ©s), plus des arĂȘtesContainsdu parent vers l'enfant.TestEdgeLinkertaguetestles mĂ©thodes[Fact]et[Theory](et le propriĂ©taire d'un appel TypeScripttestouit), et relie par des arĂȘtestestsles symboles qu'elles appellent dans les projets rĂ©fĂ©rencĂ©s.- Les deux s'exĂ©cutent Ă la construction complĂšte et Ă la rĂ©indexation incrĂ©mentale, oĂč ils passent aprĂšs les fingerprinters.
Limites
- Le FQN ne porte que le nom : une arĂȘte
testsvers un membre surchargĂ© relie toutes les surcharges. - Un test qui appelle un symbole rĂ©cemment ajoutĂ© dans un autre fichier n'a pas d'arĂȘte
testsavant une rĂ©indexation complĂšte. - Un callback de test TypeScript n'a pas de nĆud : ses appels appartiennent au symbole englobant, sinon au nĆud fichier. Aujourd'hui seul le tag est posĂ© sur le nĆud fichier ; les arĂȘtes
testsd'un test TypeScript au niveau fichier ne sont pas encore produites.
RequĂȘtes sur le graphe
Quatre tools de classe Read répondent à des questions sur le graphe sans lire le code. Tous reportent dans unresolved les noms qu'ils n'ont pas pu résoudre.
affected_tests
EntrĂ©e : changed_files ou base (une ref git dont le diff donne les fichiers) ; sans l'un ni l'autre, base vaut HEAD, soit les changements de l'arbre de travail. RĂ©ponse : all, test_projects (dossiers), test_classes (atteintes par les arĂȘtes tests), unresolved.
- Une extension neutre (
.md,.txt,.png, ...) est exemptée..claude/et le dossier de travail sont ignorés. allvauttruequand un fichier non neutre n'est pas dans l'index, n'a pas de projet propriétaire, ou quand l'expansion est tronquée.- Limites :
project_dependsvient des seuls csproj ; les tests TypeScript sont Ă©tiquetĂ©s mais sans arĂȘtestests; une arĂȘtetestsentre fichiers n'existe qu'aprĂšs une rĂ©indexation complĂšte.
batch_anchors
Entrée : action, puis fqns / files pour closure, ou a / b (chacun {fqns, files}) pour overlap.
closure: les nĆuds contenus sous les ancres, plus leurs appelants Ă profondeur 1, plus lestestsentrants. RĂ©ponse :nodes,unresolved,truncated.overlap: liste danssharedles nĆuds communs aux deux fermetures, ou renseignedisjoint. La rĂ©ponse porte aussiunresolved_a,unresolved_b,truncated.- Une fermeture tronquĂ©e, ou une ancre non rĂ©solue d'un cĂŽtĂ©, ne prouve jamais la disjonction ; une ancre non rĂ©solue prĂ©sente des deux cĂŽtĂ©s figure dans
shared.
documented_in et documents_of
documented_in(fqn) :sections[]avecpath,heading_path,start_line.documents_of(path) :symbols[]avecfqn,kind,file(relatif au dĂ©pĂŽt),heading_path.- L'arĂȘte
Documentsva d'uneSectionvers un symbole. Elle est construite Ă partir des spans de code, textes de lien et titres Ă©gaux au nom local d'un symbole, rĂ©solus par nom local : un nom ambigu relie tous les candidats.DocumentsEdgeLinkerconstruit les arĂȘtes au build complet et Ă la rĂ©indexation incrĂ©mentale. - Le mapper Markdown Ă©tiquette une
Sectioncode:<text>oulink:<text>pour chaque span ou lien de ce type.
Recherche structurelle
structural_search (classe Read) trouve des nĆuds de syntaxe par motif ou par rĂšgle. Le moteur est natif (aucun binaire ast-grep) : chaque fichier candidat est analysĂ© de nouveau par le matcher, un rĂ©sultat ne vient donc jamais d'un index pĂ©rimĂ©. Donner exactement un de pattern, rule (un objet) ou rule_file.
Le language est toute grammaire de LanguageRegistry.Parseable ou un alias (cs, ts, js, c++, rb, sh, md) ; il choisit les fichiers parcourus par extension, et une rÚgle typescript parcourt .ts et .tsx. Un motif est analysé avec cette grammaire : un motif PHP se passe de la balise <?php, un motif JSON est une valeur dont les métavariables tiennent lieu de valeurs ({"name": $N}).
Sous-ensemble de rĂšgles :
| Clé | Signification |
|---|---|
kind |
Le genre du nĆud (nom de la grammaire tree-sitter) |
pattern |
Un motif de code avec métavariables |
regex |
Une expression rĂ©guliĂšre sur le texte du nĆud |
field |
Le nom du champ que le nĆud occupe chez son parent |
inside |
Le nĆud a un parent qui satisfait la sous-rĂšgle : le parent direct sauf avec stopBy: end |
has |
Le nĆud a un enfant qui satisfait la sous-rĂšgle : un enfant direct sauf avec stopBy: end |
not |
La sous-rĂšgle ne doit pas correspondre |
all / any |
Toutes / au moins une des sous-rĂšgles correspondent |
stopBy |
OĂč inside / has cessent de monter ou de descendre : neighbor (dĂ©faut), end, ou un objet de rĂšgle |
Toute autre clĂ© (follows, precedes, matches, constraints, transform, âŠ) est refusĂ©e par son nom.
MĂ©tavariables : $A capture un nĆud, et un nom rĂ©pĂ©tĂ© doit correspondre Ă un texte Ă©gal ; $$$ARGS capture une suite de nĆuds frĂšres. Les captures sont renvoyĂ©es avec chaque correspondance.
Langages : C# (cs), TypeScript (ts), Markdown (md) et les autres grammaires livrées par l'index. En Markdown les genres sont heading, fence, link et front_matter ; regex porte sur le texte du titre ou sur la chaßne d'information de la clÎture, et ni pattern ni field ne sont disponibles (field est refusé).
Un fichier de rÚgles YAML (id, language, rule, message, severity, fix) est lu via le VFS sous une racine montée ; fix est lu, jamais appliqué.
Les résultats sont bornés par max_results (100 par défaut) et max_files (500 par défaut) ; le résultat indique truncated et files_scanned. Chaque correspondance porte chemin, ligne, colonne, texte, symbole englobant et captures.
node_insert ajoute un nĆud Ă une position relative Ă un sĂ©lecteur d'ancrage :
insideajoute le texte comme dernier membre d'un corps entre accolades (classe, struct, interface, namespace, impl ou objet JSON), aprĂšs le dernier membre d'un corps indentĂ© ou fermĂ© parend(Python, Ruby), ou Ă la fin de la section d'un titre Markdown ; un membre d'enum C#, Rust ou C et une paire JSON reçoivent la virgule de sĂ©paration. L'indentation est celle du premier frĂšre, sinon celle du parent plus l'unitĂ© dĂ©tectĂ©e du fichier (espaces ou tabulations) ; un corps vide utilise la seconde rĂšgle.beforeinsĂšre au-dessus des commentaires et attributs de tĂȘte de l'ancre,afteren dessous ; un texte multi-ligne est rĂ©-indentĂ© ligne Ă ligne sur l'indentation de l'ancre. Aucun hash d'ancrage n'est requis pourbefore/after.- Le rĂ©sultat est rĂ©-analysĂ© comme pour
node_replaceet refusé s'il introduit un diagnostic.
edit_batch applique des opérations node_replace et node_insert sur plusieurs fichiers en une transaction (EditTransaction) :
expected_hashest requis pournode_replace, absent pournode_insert. Les opĂ©rations d'un mĂȘme fichier s'appliquent dans l'ordre sur les octets dĂ©jĂ modifiĂ©s : le second hash est vĂ©rifiĂ© contre l'Ă©tat aprĂšs la premiĂšre.- Le droit d'Ă©criture de chaque chemin est vĂ©rifiĂ© avant toute Ă©criture ; chaque fichier est rĂ©-analysĂ© en mĂ©moire (
validate: "parse") avant la premiÚre écriture. - Avant la premiÚre écriture, un journal
/output/edit-batch/<id>.journalgarde les octets d'origine de chaque fichier ; il est supprimé en cas de succÚs, et leedit_batchsuivant sur le montage rejoue un journal resté. Un échec d'écriture restaure les fichiers déjà écrits depuis la mémoire ; si cette restauration échoue aussi, le journal reste et l'appel lÚve uneAggregateException. Unedit_batchconcurrent sur un fichier tenu est refusé (le verrou est dans le processus). validate: "build"écrit les fichiers, puisDotnetBuildValidatorconstruit le.csproj/.slnle plus proche au-dessus des fichiers modifiés (dotnet build --no-restore, délai maximal, processus tué à l'annulation). Un build rouge restaure les octets d'origine ; sans projet trouvé, la vérification est ignorée et signalée.- Le résultat liste le chemin et la plage de chaque opération, et l'issue de la validation.
Réécriture structurelle
structural_rewrite (classe Edit) réécrit chaque nĆud trouvĂ© par un pattern ou une rule avec un modĂšle fix, sur les fichiers de paths / glob (bornĂ©s par max_files).
dry_runvauttruepar défaut : rien n'est écrit, le résultat porte un diff unifié par fichier, le nombre de correspondances et le nombre appliqué.- Chaque fichier réécrit est ré-analysé en mémoire ; un fichier dont la réécriture ne s'analyse pas est refusé seul (
refused_reason), les autres sont appliqués. - Toute grammaire que sert
structural_searchsauf Markdown, qui est refusé.
Extensibilité
Ajouter un langage
Implémenter ILanguageAdapter (Orkeon.Analysis.Abstractions.Interfaces) : fournir LanguageName, FileExtensions, les sept queries Tree-sitter (DeclarationQuery, ImportQuery, CallQuery, InheritanceQuery, DocCommentQuery, DecoratorQuery, StatementQuery), les mappings MapNodeKind et MapStatementKind, et les extracteurs ExtractSignature / ResolveImportPath (RefineKind, ResolveDocComment, ExtractName et GetExtraModifiers ont une implémentation par défaut). Enregistrer l'adaptateur via DI (services.AddSingleton<ILanguageAdapter, MyAdapter>()) : le builder et le moteur incrémental prennent tous les ILanguageAdapter enregistrés, à cÎté des douze intégrés (LanguageAdapterFactory : TypeScript, Python, C#, Go, Rust, JavaScript, Java, C, C++, PHP, Ruby, Bash) ; un adaptateur enregistré aprÚs AddRaggableTree avec le LanguageName d'un intégré le remplace. Un adaptateur Java exécutable, écrit avant que Java soit intégré et gardé comme exemple minimal du contrat, vit dans examples/raggable-tree/custom-adapter/.
Ajouter un fingerprinter
Créer un IReadOnlyList<FingerprintRule> listant les décorateurs/annotations à matcher avec leurs tags puis construire un FrameworkFingerprinter(framework, rules). Voir Orkeon.Analysis.Fingerprinters.NestJsRules comme référence (15 rÚgles).
Ajouter un embedding provider
ImplĂ©menter IEmbeddingProvider.EmbedBatchAsync(texts, ct) â IReadOnlyList<ReadOnlyMemory<float>>. Trois implĂ©mentations de rĂ©fĂ©rence : OpenAIEmbeddingProvider, OllamaEmbeddingProvider, et LocalEmbeddingProvider (cf. section ci-dessous). La mĂ©thode d'interface par dĂ©faut EmbedAsync(nodes, model, ct) (sur IEmbeddingProvider, Orkeon.Analysis.Abstractions.Interfaces) remplit node.Embedding Ă partir du EmbeddingText composĂ©.
Embedding providers
Cinq membres existent sur EmbeddingProviderKind :
| Provider | Réseau | Clé API | Dims | Notes |
|---|---|---|---|---|
None |
n/a | n/a | n/a | Aucun embedding (le défaut C#) : embedding et miroir sautés, codebase_search dégrade vers BM25 |
Onnx |
non | non | â | RĂ©servĂ© â actuellement un bras d'enregistrement no-op |
OpenAI |
requis | requis | 1536 (text-embedding-3-small) |
Qualité maximale, MTEB ~62.3 |
Ollama |
local (HTTP) | non | dépend du modÚle (768 supposé pour le nomic-embed-text par défaut) |
Daemon Ollama / llama.cpp local requis (défaut http://localhost:11434/) |
LocalSmartComponents |
non | non | 384 (BGE-micro-v2) | In-process, ONNX CPU, dĂ©marrage Ă froid ~200 ms â le dĂ©faut du runner host |
Provider local LocalSmartComponents
Implémenté par Orkeon.Tools.Embeddings.Local (package opt-in, package upstream SmartComponents.LocalEmbeddings v0.1.0-preview10148, modÚle BGE-micro-v2). Adapté aux contextes CLI dev, indexation CI offline, démos sans clé d'API.
Trade-off qualité / coût :
- 384 dimensions vs 1536 (OpenAI) â recherche sĂ©mantique moins fine sur du Q&A factuel hors-domaine.
- Score MTEB ~58.5 vs ~62.3 â acceptable pour l'indexation de code (les signatures, FQN et docstrings sont des signaux structurĂ©s moins ambigus que du texte long).
- CoĂ»t d'API â 0 (modĂšle embarquĂ© dans le NuGet, ~22 MB).
- Aucune dépendance réseau, aucune clé à gérer.
- Démarrage à froid ~150-300 ms (chargement ONNX en mémoire) ; ~5-15 ms / texte sur CPU x86_64 moderne.
- Empreinte RAM ~200 MB une fois le modÚle chargé.
Configuration minimale (appsettings.json)
{
"RaggableTree": {
"Embedding": {
"Provider": "LocalSmartComponents"
// Dimensions, BaseUrl, ApiKey, Model : tous optionnels et ignorés.
// Defaults : 384 dims (BGE-micro-v2), CPU, in-process.
}
}
}
CÎté code, l'enregistrement DI est :
services.AddOrkeonLocalEmbeddings(); // package Orkeon.Tools.Embeddings.Local
services.AddRaggableTree(new RaggableTreeOptions
{
Embedding = new EmbeddingOptions
{
Provider = EmbeddingProviderKind.LocalSmartComponents,
},
});
Configuration étendue avec ModelPath VFS
Pour pointer vers un autre modĂšle ONNX que le BGE-micro-v2 embarquĂ©, dĂ©clarer un mount VFS lecture seule et passer un chemin virtuel dans LocalEmbeddingOptions.ModelPath (Orkeon.Analysis.Abstractions.DependencyInjection). Les chemins physiques (C:/..., /var/...) sont rejetĂ©s par IFileSystemService â voir vfs-compliance.md. Ces options se positionnent en C# : le runner host ne lit pas de section RaggableTree:Embedding:Local et enregistre toujours le modĂšle embarquĂ© avec ses dĂ©fauts.
{
"Orkeon": {
"FileSystem": {
"Mounts": [
"C:\\data\\embedding-models:/models:ro" // <physique>:<virtuel>:<droits>
]
}
}
}
services.AddOrkeonLocalEmbeddings(new LocalEmbeddingOptions
{
ModelPath = "/models/my-custom.onnx", // chemin virtuel â rĂ©solu par IFileSystemService
MaxConcurrency = 8, // défaut : Environment.ProcessorCount
MaxTextChars = 2000, // dĂ©faut 2000 (BGE-micro-v2 : fenĂȘtre de 512 tokens)
});
services.AddRaggableTree(new RaggableTreeOptions
{
Embedding = new EmbeddingOptions { Provider = EmbeddingProviderKind.LocalSmartComponents },
});
Un ModelPath qui ne contient aucun modĂšle chargeable (un dossier vide, un chemin sans rien derriĂšre, un fichier qui n'est pas un modĂšle) ne fait Ă©chouer ni la construction de l'hĂŽte ni la liste des outils : le provider se construit, et le premier embedding lĂšve une InvalidOperationException qui nomme le ModelPath, l'erreur de la bibliothĂšque en exception interne. Ni l'Ă©chec de l'embedder ni celui de Dimensions ne sont mis en cache : l'appel suivant rĂ©essaie une fois le modĂšle en place. Le garde-fou du modĂšle d'embeddings signale un provider qui ne peut pas donner ses dimensions avec le message du provider lui-mĂȘme, en Warning, et saute sa vĂ©rification. Le chemin lui-mĂȘme reste vĂ©rifiĂ© sans attendre contre les montages.
Sans AddOrkeonLocalEmbeddings, EmbeddingOptions.Local porte les mĂȘmes options et AddRaggableTree instancie le provider par rĂ©flexion â ce qui Ă©choue bruyamment si l'assembly Orkeon.Tools.Embeddings.Local n'est pas rĂ©fĂ©rencĂ©e par l'hĂŽte.
Les licences du modÚle et du package upstream sont tracées dans THIRD-PARTY-NOTICES.md. Un exemple console minimal vit dans examples/local-embeddings/.
Ajouter un vector store
ImplĂ©menter IVectorStoreProvider (IndexAsync, SearchAsync, DeleteAsync) et l'enregistrer : le builder et le moteur incrĂ©mental y reflĂštent alors les embeddings (DeleteAsync pour les nĆuds supprimĂ©s Ă la rĂ©indexation). L'implĂ©mentation livrĂ©e est MemoryProviderVectorStoreAdapter (Orkeon.Analysis.Vectors), qui projette VectorDocument/VectorMetadata sur n'importe lequel des six providers mĂ©moire (Redis, SQLite, ChromaDB, Pinecone, LanceDB, InMemory) â la construire sur l'IMemoryProvider de son choix. Les requĂȘtes continuent de s'exĂ©cuter sur InMemoryRaggableStore : le miroir est en Ă©criture seule en V1.
Limitations V1
- Pas de support des macros C++ / templates pleinement résolus, ni des méta-programmations Ruby/Elixir.
- Le résolveur d'imports est heuristique pour les langages dynamiques (Python, TypeScript, JavaScript, Ruby, PHP) : les re-exports et les monkey patches peuvent produire des
UnresolvedRef. - Les arĂȘtes d'import entre fichiers viennent des chemins relatifs, sauf dans quatre langages qui rĂ©solvent un nom une fois tous les fichiers analysĂ©s. Un
using N;C# atteint les fichiers qui dĂ©clarent un type du namespaceNdont le nom court apparaĂźt comme identifiant dans le fichier qui importe (commentaires exclus, chaĂźnes comprises), pas tous les fichiers deN;using static N.T;etusing A = N.T;atteignent les fichiers qui dĂ©clarentT; un namespace qu'aucun fichier de l'arbre ne dĂ©clare va vers un nĆudext::dotnet::N. La visibilitĂ© du namespace propre au fichier (un type du mĂȘme namespace employĂ© sansusing) ne trace aucune arĂȘte, et unglobal usingne compte que dans le fichier qui le porte, pas dans les autres fichiers de son projet. UnimportGo placĂ© sous le chemin de module dugo.modd'un package atteint les fichiers.gohors tests (_test.goexclus) du dossier situĂ© sous ce chemin ; tout autre chemin va versext::go::<chemin>. Unuse crate::a::b::CRust atteintsrc/a/b.rsousrc/a/b/mod.rs, le plus long prĂ©fixe du chemin qui est un fichier de module (la fin peut nommer un Ă©lĂ©ment) ;super::,self::et un premier segment qui nomme un module enfant du module courant partent du module courant ; tout autre premier segment (std, une dĂ©pendance) va versext::cargo::<crate>, crate voisine d'un workspace comprise. Unimport a.bou unfrom a.b import cPython est rĂ©solu contre les fichiers de l'arbre :a/b.pyou le packagea/b/__init__.py, cherchĂ© sous les dossiers que Python aurait danssys.path. Pour un fichier hors de tout package (son dossier ne contient pas de__init__.py), un script : son propre dossier, puis chaque dossier au-dessus, le plus proche d'abord. Pour un fichier d'un package : le dossier au-dessus de son package le plus haut d'abord, puis les dossiers au-dessus de celui-ci, et les dossiers Ă l'intĂ©rieur du package en dernier (ils ne sont sur le chemin que si le fichier est lancĂ© comme script). Le premier dossier qui contient le module l'emporte ; Ă dĂ©faut, le premier qui contient une partie initiale de son chemin (import a.boĂčbest un attribut dea.pyatteinta.py). Dansfrom a.b import c, d, un nom qui est un sous-module ou un sous-package (a/b/c.py,a/b/c/__init__.py) atteint son fichier et les autres atteignenta.blui-mĂȘme, un joker aussi.from . import xetfrom ..m import ypartent du package du fichier qui importe, un package plus haut par point supplĂ©mentaire, et celui qui n'atteint aucun fichier de l'arbre ne trace aucune arĂȘte. Un import absolu qu'aucun dossier ne contient va versext::pypi::<premier segment>(bibliothĂšque standard comprise), de mĂȘme qu'un fichier qui importe son propre nom (unredis.pyqui contientimport redis) ; un fichier du projet qui porte le nom d'une bibliothĂšque est pris pour elle quand il vient en premier sur ce chemin. Un import placĂ© dans une fonction, untryou unif TYPE_CHECKING:compte comme celui du fichier. Un module atteint seulement par unsys.pathmodifiĂ© Ă l'exĂ©cution, un paquet installĂ© en mode Ă©ditable ouimportlibn'est pas trouvĂ©. Un rafraĂźchissement incrĂ©mental reconstruit les arĂȘtes d'import des fichiers qu'il analyse de nouveau, et rĂ©sout Ă nouveau les importeurs Go inchangĂ©s d'un package qui gagne un fichier, ainsi que les importeurs Python inchangĂ©s d'un fichier qui rejoint l'arbre lorsque leur import avait tracĂ© une arĂȘte (versext::pypi::<un segment du nouveau chemin sous la racine indexĂ©e>ou vers le__init__.pyd'un package au-dessus de lui ; un import relatif qui n'avait rien atteint n'est pas retrouvĂ©, ni un import qui atteint dĂ©jĂ un fichier plus Ă©loignĂ© que le nouveau, ni les imports d'un fichier dont un nouveau__init__.pyfait de son propre dossier un package, ce qui change l'ordre de ses dossiers de recherche), mais pas celles d'un fichier C# inchangĂ© qui nomme un type qu'un fichier modifiĂ© dĂ©clare dĂ©sormais. UnimportJava, unusePHP, unrequireRuby (Ă la diffĂ©rence derequire_relative) et un#include <...>C nomment un paquet, un namespace ou un en-tĂȘte systĂšme, pas un fichier, et ne tracent aucune arĂȘte vers un fichier de l'arbre ; unsourceBash dont le chemin contient une variable n'est pas rĂ©solu. Ungo.modou un marqueur de package que le systĂšme de fichiers refuse de lire est traitĂ© comme absent. Un chemin PHP qui commence par/(__DIR__ . '/lib/a.php') se lit depuis le dossier du fichier.package_summarytire lesdependenciesd'un package de ces arĂȘtes (les packages qui contiennent les fichiers que ses modules importent) : un package Java, PHP ou Ruby n'en rapporte donc aucune. - Les arĂȘtes se rĂ©solvent dans un groupe de graphe (
DependencyGraphBuilder.GraphGroupOf) : C et C++ en partagent un, si bien qu'un fichier.catteint l'en-tĂȘte.hqu'il inclut (parsĂ© en C++) et les fonctions qui y sont dĂ©clarĂ©es ; JavaScript et TypeScript en partagent un autre. Les autres langages se rĂ©solvent chacun dans le leur. - Le summarizer se configure uniquement en C# (
Summarizer.Provider+ unILlmProvider) ; les embeddings OpenAI/Ollama exigent leur endpoint, alors que le défaut on-device du runner host ne demande rien. Le pipeline fonctionne sans embeddings (codebase_searchclasse alors par BM25 seul). - L'index est local au processus :
InMemoryRaggableStoreest reconstruit parindex_codebasedans chaque processus, et le miroir vector store optionnel n'est jamais relu. FileSystemWatcherCodebaseWatcher(l'implĂ©mentation d'ICodebaseWatcher, qu'aucun hĂŽte livrĂ© n'enregistre) se base surSystem.IO.FileSystemWatcherâ sous Linux/WSL, les Ă©vĂ©nements de rename peuvent arriver dĂ©composĂ©s (observĂ©s comme Deleted puis Created).- Le cache d'index ne se rafraĂźchit sur place que sans
root_aliaset quand au plus la moitiĂ© des fichiers a changĂ© ; sinon il reconstruit tout. Un fichier dont le contenu n'a pas changĂ© garde ses nĆuds enregistrĂ©s mĂȘme quand un fichier qu'il importe a changĂ© : le rafraĂźchissement relie Ă nouveau les arĂȘtes, il ne rĂ©analyse pas le fichier. La base gardeMaxEntries(3) clĂ©s du runtime courant : une quatriĂšme Ă©vince la moins rĂ©cemment utilisĂ©e, et une entrĂ©e d'un autre runtime est supprimĂ©e Ă l'enregistrement suivant. Une empreinte de fichier ne voit pas une modification qui garde Ă la fois la taille et l'heure d'Ă©criture ;use_cache: falsereconstruit depuis le contenu.
Voir aussi : ADR RaggableTree · Inventaire des outils · Retour à l'index