Table of Contents

🇬🇧 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 EmbeddingText puis 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

  1. 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 .gitignore racine, chaque .gitignore imbriquĂ© 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_codebase le signale dans filter_stats.excluded_by_policy et filter_stats.excluded_by_policy_paths.
  2. Parse + Extract (UniversalSemanticMapper + ILanguageAdapter) — Tree-sitter parse → application des queries de l'adaptateur → nƓuds L2 (module) et L3 (symbole) avec Fqn, Signature, SourceSnippet, Sha256 ; statements L4 (StatementExtractor), extraits Ă  chaque construction. Les fichiers sont lus et analysĂ©s max_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_reindex analyse ses fichiers modifiĂ©s l'un aprĂšs l'autre.
  3. 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 des UnresolvedRef. Une liste de bases C# trace Implements vers une interface et Extends vers 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, un using C# 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.
  4. Fingerprinting (IFrameworkFingerprinter) — application des rĂšgles par dĂ©corateur/annotation (NestJS, Angular, ASP.NET, Flask, FastAPI) : pose de tags comme http-endpoint, guard, service sur les nƓuds concernĂ©s.
  5. Enrichissement — optionnellement un rĂ©sumĂ© LLM (INodeSummarizer, quand l'appel positionne enrich_with_llm et qu'un summarizer est enregistrĂ©), composition du EmbeddingText (IEmbeddingTextComposer), puis embedding batch (IEmbeddingProvider, sautĂ© quand aucun n'est enregistrĂ©).
  6. Persistance — l'arbre vit dans InMemoryRaggableStore (index_codebase en remplace le contenu), qui rĂ©pond aussi Ă  toutes les requĂȘtes. Quand un IVectorStoreProvider est enregistrĂ©, IndexAsync reçoit en plus un miroir des embeddings — aucun hĂŽte livrĂ© n'en enregistre (MemoryProviderVectorStoreAdapter, Orkeon.Analysis.Vectors, adapte n'importe quel IMemoryProvider pour un hĂŽte qui le souhaite), et rien ne relit ce miroir. Entre les sessions, index_codebase enregistre 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 Section par 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 CodeFence par bloc dĂ©limitĂ© (le langage est son tag ; un bloc mermaid porte aussi le tag mermaid), un nƓud Link par lien (tag target:<cible brute>, plus resolved:<fqn> quand MarkdownDocumentMapper.ResolveLinksAsync retrouve 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Ɠud FrontMatter pour 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 :

  1. 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ération 1, une clé connue l'augmente de un ; saved_at et used_at prennent l'heure courante.
  2. Les indexed_files et package_markers de l'entrée sont réécrites.
  3. Les nƓuds sont groupĂ©s par fichier. Un groupe dont le content_sha256 n'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.
  4. Les node_runs de l'entrée sont réécrites.
  5. Les entrées d'un autre runtime sont supprimées, puis les entrées au-delà de MaxEntries, par used_at depuis 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 — FileWriteTool prend un IIndexInvalidation optionnel (enregistrĂ© par AddRaggableTree, 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) appellent IndexFreshnessService.EnsureFreshAsync avant de rĂ©pondre : l'ensemble sale âˆȘ les changements du working tree git (attrape les Ă©ditions via shell_command) est rĂ©indexĂ© incrĂ©mentalement — groupĂ©, single-flight, avec debounce (une sonde git propre fait foi pendant 2 s). Les rĂ©ponses de codebase_search rapportent refreshed_files ; index_status rapporte dirty_count/dirty_paths, de sorte que le « pĂ©rimĂ© » est observable.
  • SĂ»retĂ© du store — InMemoryRaggableStore dĂ©tient un ReaderWriterLockSlim : les recherches Ă©numĂšrent en sĂ©curitĂ© PENDANT une rĂ©indexation incrĂ©mentale. Le rafraĂźchissement publie RaggableTreeUpdated sur 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_reindex rapporte 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 .md et .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 liste A/Notes[1], A/Notes[2] ; le plan montre la forme avec ordinal pour les doublons (et A[2]/Notes pour 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-sitter root/<index>/<kind>/... (index la 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_hash avant toute Ă©criture ; un Ă©cart est refusĂ© par une StaleHashException qui 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_kinds et node_kinds de dependency_graph et sub_graph, ainsi que edge_kinds de flow_trace et edge_list, prennent les noms de workflow en minuscules, sans tenir compte de la casse (Imports vaut imports). 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[].kind vaut imports, project_depends, extends ou implements (une arĂȘte est l'un ou l'autre, jamais inherits), 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_detail prend expand: "members" ou "callers, callees" ; un nombre est refusĂ©.
  • edge_list parcourt l'index entier, contrairement Ă  dependency_graph, dont max_nodes borne les nƓuds avant que les arĂȘtes soient collectĂ©es : toutes les classes de base d'une codebase, c'est edge_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. total compte toutes les arĂȘtes retenues, root_fqn garde 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), et page_size va jusqu'Ă  1000 (200 par dĂ©faut). from/to sont des FQN, from_id/to_id les ids de nƓud qu'Ă©crit dependency_graph ; une extrĂ©mitĂ© hors de l'index garde son id dans les deux.
  • symbol_detail avec expand: "inheritance" liste extends et implements en FQN, et ce qui pointe vers le symbole : derived_by (les types qui l'Ă©tendent) et implemented_by (les types qui l'implĂ©mentent).
  • flow_trace suit calls quand edge_kinds est vide ; inherits suit Ă  la fois extends et implements.
  • codebase_search met truncated quand il a renvoyĂ© top_k rĂ©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_kinds est donnĂ©, dependency_graph respecte toujours Scope : les genres et les tags passent dans la requĂȘte de nƓuds, et MaxNodes borne le rĂ©sultat.
  • dependency_graph nomme ses cycles : cycles liste 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 de nodes[].fqn). max_cycles (20 par dĂ©faut) et max_cycle_members (50 par dĂ©faut) bornent la liste, cycles_truncated dit si l'un des deux l'a coupĂ©e, et metrics.cycle_count garde le compte complet. Les cycles suivent les mĂȘmes genres d'arĂȘtes que edges (les imports quand edge_kinds est vide), et edge_kind les nomme tous (imports, calls). cycles et cycle_count couvrent toute la portĂ©e ; node_count et edge_count couvrent les nƓuds renvoyĂ©s, que max_nodes, root_fqn et node_kinds sĂ©lectionnent.

Construction du graphe

  • ProjectGraphBuilder lit chaque csproj dĂ©jĂ  trouvĂ© par le dĂ©couvreur (une lecture par csproj) et transforme chaque ProjectReference en arĂȘte project_depends (\ et .. sont normalisĂ©s), plus des arĂȘtes Contains du parent vers l'enfant.
  • TestEdgeLinker tague test les mĂ©thodes [Fact] et [Theory] (et le propriĂ©taire d'un appel TypeScript test ou it), et relie par des arĂȘtes tests les 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 tests vers 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 tests avant 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 tests d'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.
  • all vaut true quand 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_depends vient des seuls csproj ; les tests TypeScript sont Ă©tiquetĂ©s mais sans arĂȘtes tests ; une arĂȘte tests entre 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 les tests entrants. RĂ©ponse : nodes, unresolved, truncated.
  • overlap : liste dans shared les nƓuds communs aux deux fermetures, ou renseigne disjoint. La rĂ©ponse porte aussi unresolved_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[] avec path, heading_path, start_line.
  • documents_of (path) : symbols[] avec fqn, kind, file (relatif au dĂ©pĂŽt), heading_path.
  • L'arĂȘte Documents va d'une Section vers 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. DocumentsEdgeLinker construit les arĂȘtes au build complet et Ă  la rĂ©indexation incrĂ©mentale.
  • Le mapper Markdown Ă©tiquette une Section code:<text> ou link:<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 :

  • inside ajoute 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Ă© par end (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.
  • before insĂšre au-dessus des commentaires et attributs de tĂȘte de l'ancre, after en dessous ; un texte multi-ligne est rĂ©-indentĂ© ligne Ă  ligne sur l'indentation de l'ancre. Aucun hash d'ancrage n'est requis pour before/after.
  • Le rĂ©sultat est rĂ©-analysĂ© comme pour node_replace et 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_hash est requis pour node_replace, absent pour node_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>.journal garde les octets d'origine de chaque fichier ; il est supprimĂ© en cas de succĂšs, et le edit_batch suivant 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 une AggregateException. Un edit_batch concurrent sur un fichier tenu est refusĂ© (le verrou est dans le processus).
  • validate: "build" Ă©crit les fichiers, puis DotnetBuildValidator construit le .csproj/.sln le 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_run vaut true par 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_search sauf 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 namespace N dont le nom court apparaĂźt comme identifiant dans le fichier qui importe (commentaires exclus, chaĂźnes comprises), pas tous les fichiers de N ; using static N.T; et using A = N.T; atteignent les fichiers qui dĂ©clarent T ; un namespace qu'aucun fichier de l'arbre ne dĂ©clare va vers un nƓud ext::dotnet::N. La visibilitĂ© du namespace propre au fichier (un type du mĂȘme namespace employĂ© sans using) ne trace aucune arĂȘte, et un global using ne compte que dans le fichier qui le porte, pas dans les autres fichiers de son projet. Un import Go placĂ© sous le chemin de module du go.mod d'un package atteint les fichiers .go hors tests (_test.go exclus) du dossier situĂ© sous ce chemin ; tout autre chemin va vers ext::go::<chemin>. Un use crate::a::b::C Rust atteint src/a/b.rs ou src/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 vers ext::cargo::<crate>, crate voisine d'un workspace comprise. Un import a.b ou un from a.b import c Python est rĂ©solu contre les fichiers de l'arbre : a/b.py ou le package a/b/__init__.py, cherchĂ© sous les dossiers que Python aurait dans sys.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.b oĂč b est un attribut de a.py atteint a.py). Dans from 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 atteignent a.b lui-mĂȘme, un joker aussi. from . import x et from ..m import y partent 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 vers ext::pypi::<premier segment> (bibliothĂšque standard comprise), de mĂȘme qu'un fichier qui importe son propre nom (un redis.py qui contient import 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, un try ou un if TYPE_CHECKING: compte comme celui du fichier. Un module atteint seulement par un sys.path modifiĂ© Ă  l'exĂ©cution, un paquet installĂ© en mode Ă©ditable ou importlib n'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 (vers ext::pypi::<un segment du nouveau chemin sous la racine indexĂ©e> ou vers le __init__.py d'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__.py fait 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. Un import Java, un use PHP, un require Ruby (Ă  la diffĂ©rence de require_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 ; un source Bash dont le chemin contient une variable n'est pas rĂ©solu. Un go.mod ou 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_summary tire les dependencies d'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 .c atteint l'en-tĂȘte .h qu'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 + un ILlmProvider) ; 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_search classe alors par BM25 seul).
  • L'index est local au processus : InMemoryRaggableStore est reconstruit par index_codebase dans 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 sur System.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_alias et 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 garde MaxEntries (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: false reconstruit depuis le contenu.

Voir aussi : ADR RaggableTree · Inventaire des outils · Retour à l'index