saidake/code-trace-tree-jetbrains

Code Trace Tree

Construisez et affichez des workflows de code sous forme d'arbres imbriqués de points de trace (lignes, fichiers et répertoires). Utilisez les scripts Python fournis pour opérer le stockage hybride utilisé par les plugins IDE Code Trace Tree, puis demandez le rechargement de l'IDE.

Modifiez ou synchronisez les traces uniquement lorsque l'utilisateur le demande explicitement (par exemple : générer des nœuds liés à un sujet, ajouter un conseil sur une ligne, relier après des modifications). Ne faites pas de synchronisation automatique à chaque tour. Ne supprimez jamais les points de trace existants (y compris ceux que rebind signale comme "invalid") à moins que l'utilisateur ne demande explicitement de les supprimer.

Comment utiliser cette compétence

Lisez uniquement ce SKILL.md. Ne listez, ne recherchez et n'explorez pas les dossiers scripts/ ou references/ de cette compétence, et n'ouvrez pas le source des scripts pour apprendre l'API. Invoquez les commandes Python documentées par chemin absolu.

Ouvrez scripts/ ou references/ uniquement si vous rencontrez un problème critique lors de l'utilisation de la compétence (script manquant ou qui plante, stockage corrompu, ou une erreur que ce fichier ne couvre pas).

Emplacement des scripts de la compétence

Les scripts d'aide se trouvent sous <Chemin Compétence Agent>/code-trace-tree/scripts/.

Chemin Compétence Agent est le répertoire des compétences de cet agent (le parent de code-trace-tree/) pour l'agent que vous exécutez — local au projet s'il existe, sinon global. Il se termine par skills, pas par code-trace-tree. Les chemins correspondent à npx skills. Le tableau liste des exemples courants ; les autres agents listés fonctionnent de la même manière.

Agent (exemples)	Chemin Compétence Agent Global	Chemin Compétence Agent Local au Projet
Claude Code	~/.claude/skills	<repo>/.claude/skills
Cursor	~/.cursor/skills	<repo>/.agents/skills
GitHub Copilot	~/.copilot/skills	<repo>/.agents/skills
Codex	~/.codex/skills	<repo>/.agents/skills
Gemini CLI	~/.gemini/skills	<repo>/.agents/skills

Sous Windows, ~ correspond à %USERPROFILE%. Résolvez Chemin Compétence Agent une fois par session. Invoquez les scripts avec des chemins absolus via python (ou python3 si c'est ce qui est dans PATH). Gardez le répertoire de travail courant dans le projet IDE (ne faites pas cd dans le dossier de la compétence). Invocations directes : Opérations de l'Arbre de Trace. Sous PowerShell, voir aussi Windows PowerShell.

Opérations de l'Arbre de Trace

Tous les appels de scripts de la compétence. Remplacez le Chemin Compétence Agent absolu pour CET agent. Gardez le répertoire de travail courant dans le projet IDE (ne faites pas cd dans le dossier de la compétence). Sous PowerShell, voir Windows PowerShell.

• resolve_storage.py
• create_tree.py
• trace_tree.py
• request_refresh.py
• request_refresh_profile.py
• request_refresh_settings.py
• select_trace_points.py

resolve_storage.py

Résout l'ID du projet et le XML global lié. Si le stockage est manquant, le crée (Cas C). Si .idea/code-trace-tree.project.id existe mais que le XML est absent, recrée le XML avec ce même projectId. Ne crée/écrase pas le fichier .idea id. Les mutations create_tree et trace_tree add / ensure / move / delete / rebind créent également le stockage automatiquement. trace_tree search ne crée pas automatiquement.

Utilisation

python "<Chemin Compétence Agent>/code-trace-tree/scripts/resolve_storage.py" [project_path]

Paramètres optionnels :

• [project_path] : Chemin utilisé pour découvrir la racine du projet IDE (par défaut : CWD). Passez la racine du projet pour que le <path> du XML soit correct.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). Les erreurs affichent ERROR: … sur stderr.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<OS Config Dir>/code-trace-tree",
  "project_id": "<uuid or null>",
  "storage_xml": "<abs xml path>"
}

created est true lorsqu'un nouveau XML a été écrit. Sortie 0 en cas de succès ; 1 si la racine du projet ne peut pas être trouvée.

Exemple :

python "<Chemin Compétence Agent>/code-trace-tree/scripts/resolve_storage.py"
python "<Chemin Compétence Agent>/code-trace-tree/scripts/resolve_storage.py" /path/to/project

create_tree.py

Crée un arbre de points de trace imbriqué en un seul appel. Garantit uniquement les racines de la charge utile (et les enfants des racines qui existent déjà). Une fois qu'un nœud est créé, ses descendants sont ajoutés (pas de garantie par enfant). Ne faites pas search si ce n'est pas nécessaire — ce script garantit déjà les nœuds existants. Utilisez search lorsque vous avez besoin d'IDs (sélectionner/déplacer/supprimer) ou pour inspecter. Les localisateurs LINE sont les mêmes que trace_tree.py (file + line + content). Ignorez l'occurrence du contenu de la ligne (occurrenceIndex / totalOccurrences) — le script le calcule. Préférez --tree-file sur PowerShell.

Le --parent-id optionnel attache la charge utile sous un nœud existant (ce parent est résolu, pas garanti).

Utilisation

python "<Chemin Compétence Agent>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Chemin Compétence Agent>/code-trace-tree/scripts/create_tree.py" tree.json
python "<Chemin Compétence Agent>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Paramètres requis (exactement une source d'arbre) :

• --tree-file <chemin> : Fichier JSON (- = entrée standard). Préférez ceci à --tree.
• --tree <json> : Chaîne JSON.
• Positionnel <chemin> : identique à --tree-file.

Paramètres (partagés ; tous optionnels) :

• --project <chemin> : Chemin du projet (par défaut : CWD).
• --profile <nom> : Remplacement du nom de profil (par défaut : <activeProfileName>).
• --dry-run : N'écrit pas le XML et ne rafraîchit pas.
• --no-refresh : Ignore le signal de rafraîchissement IDE.
• --parent-id <uuid> : Parent existant ; répétez vers la racine → parent immédiat. Omettre pour la racine du profil.
• --parent <json> : JSON du chemin du parent existant (ne combinez pas avec --parent-id).

JSON de l'arbre (un objet nœud ou un tableau d'objets nœuds). Chaque nœud utilise la même forme, y compris children (description sur chaque nœud, pas seulement la racine) :

{
  "file": "src/A.java",
  "line": 10,
  "content": "void methodA() {",
  "name": "methodA",
  "description": "",
  "type": "LINE",
  "children": [
    {
      "file": "src/B.java",
      "line": 40,
      "content": "void methodB() {",
      "name": "methodB",
      "description": "",
      "type": "LINE",
      "children": [
        {
          "file": "src/C.java",
          "line": 20,
          "content": "void methodC() {",
          "name": "methodC",
          "description": "",
          "type": "LINE"
        },
        {
          "type": "FILE",
          "file": "src/Util.java",
          "name": "Util",
          "description": ""
        }
      ]
    }
  ]
}

Champs (chaque nœud, y compris les enfants) : file (obligatoire) ; type (LINE | FILE | DIRECTORY ; omettre pour inférer : line/content → LINE, sinon chemin sur disque) ; LINE nécessite line + content ; name / description / children optionnels. N'incluez pas occurrenceIndex / totalOccurrences. children est un tableau des mêmes objets.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). skipped: true sur un nœud signifie que la garantie l'a trouvé ; les enfants de ce nœud sont toujours garantis. created: true signifie ajout ; les descendants de ce nœud ont été ajoutés sans garantie.

{
  "action": "create_tree",
  "profile": "<profile-name>",
  "storage_xml": "<abs>",
  "parentId": "<uuid or empty>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <node-object>, "children": [ … ] } ],
  "refreshed": true
}

Sortie 0 en cas de succès.

Exemple :

python "<Chemin Compétence Agent>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Chemin Compétence Agent>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file tree.json

trace_tree.py

Recherche, ajoute, garantit, déplace, supprime et relie les nœuds. Ignorez l'occurrence du contenu de la ligne (occurrenceIndex / totalOccurrences) — ne transmettez jamais ces champs ; le script les calcule.

Utilisation

python "<Chemin Compétence Agent>/code-trace-tree/scripts/trace_tree.py" <sous-commande> [flags…]
python "<Chemin Compétence Agent>/code-trace-tree/scripts/trace_tree.py" [flags-partagés] <sous-commande> [flags…]

Les flags partagés (--project, --profile, --dry-run, --no-refresh) peuvent apparaître avant ou après la sous-commande. Omettre --project lorsque le CWD est déjà dans le projet IDE (les scripts remontent pour trouver .vscode / .idea / .git, ou d'autres marqueurs de projet courants). Profil par défaut : <activeProfileName>.

Localisateurs LINE : le point de trace stocké est [file, line, full-trimmed-line]. --line est obligatoire. Le script vérifie le texte trimé à cette ligne, stocke la ligne trimée complète (une sous-chaîne --content est étendue), puis définit occurrenceIndex / totalOccurrences en scannant le fichier. Les lignes trimées dupliquées dans un même fichier sont distinctes car --line sélectionne quelle copie. Ignorez l'occurrence : ne lisez, ne transmettez et ne calculez pas occurrenceIndex / totalOccurrences. Sous PowerShell, protégez le --content entre guillemets avec --% (voir Windows PowerShell) ou utilisez un point de trace sous-chaîne plus --line. N'enveloppez jamais le CLI dans un helper qui utilise un paramètre nommé $Args.

Point de trace	Résultat
Ligne exacte + texte trimé complet	Utilisé tel quel
Sous-chaîne distinctive de cette ligne (ex. .handleEmailTriggerRequest()	--line obligatoire ; stocke la ligne trimée complète
Même texte trimé sur 2+ lignes	Passez --line pour la copie prévue ; le script définit l'occurrence
Appel multi-lignes	Préférez la ligne physique la plus distinctive (souvent la continuation .methodName()

add vs ensure : add crée toujours un nouvel UUID (comme le plugin IDE). Utilisez-le pour un deuxième nœud sur la même ligne avec un libellé ou un parent différent. ensure est get-or-create : même identité → "skipped": true (sortie 0). Pour LINE, l'identité est file + lineContent trimé + la copie sélectionnée par --line (le script stocke l'occurrence ; ne la transmettez pas). L'identité FILE/DIRECTORY est path + type. --trace-name, description et parent ne font pas partie de l'identité.

Générer un arbre : préférez create_tree.py. Ne faites pas search si ce n'est pas nécessaire — le script garantit les nœuds existants et ajoute les sous-arbres. Utilisez search lorsque vous avez besoin d'IDs pour sélectionner/déplacer/supprimer ou pour inspecter. Pour un seul nœud, utilisez ensure (get-or-create ; pas de search nécessaire) ou add (toujours un nouvel UUID).

Chemin du parent : préférez --parent-id répété de l'ancêtre vers la racine → parent immédiat. Omettre pour la racine sur add / ensure. Ne combinez pas --parent-id avec --parent. Les chaînes nues dans le JSON --parent sont des UUID uniquement, pas des libellés traceName.

Forme --parent	Exemple
Racine	--parent [] (nécessaire pour move vers la racine ; add / ensure par défaut à la racine)
ID de nœud en JSON	--parent '["3d41c2d1-…"]'
[file, line, content]	--parent '[["src/A.java",10,"void methodA() {"]]'

méthode A def
  méthode B call
    méthode C call   ← ajouter (ou ensure si B existait déjà) avec --parent-id idA --parent-id idB

Relier après des modifications sur disque : Les agents ne modifient pas via l'éditeur IDE, donc le décalage de ligne en direct ne s'applique pas. Après tout tour qui a modifié le source du projet, exécutez rebind (optionnellement --file pour les chemins touchés) avant de vous fier aux localisateurs ou de sélectionner/naviguer. Rebind répare lineNumber à partir de lineContent trimé et recalcule les occurrences. Le tableau "invalid" signifie que ces localisateurs LINE n'ont pas été trouvés — laissez ces nœuds dans l'arbre ; ne les delete PAS sauf si l'utilisateur demande de les supprimer.

Pour de nombreux appels mutants, utilisez --no-refresh sur chacun, puis un seul request_refresh.py à la fin.

Sous-commande obligatoire :

• <sous-commande> : search | add | ensure | move | delete | rebind

Paramètres (partagés ; tous optionnels) :

• --project <chemin> : Chemin du projet (par défaut : CWD).
• --profile <nom> : Remplacement du nom de profil (par défaut : <activeProfileName>).
• --dry-run : N'écrit pas le XML et ne rafraîchit pas.
• --no-refresh : Ignore le signal de rafraîchissement IDE.

Paramètres (search ; tous optionnels) :

• --id <uuid> : UUID du nœud.
• --file <chemin> : Chemin relatif du fichier/répertoire.
• --line <n> : Numéro de ligne basé sur 1.
• --content <texte> : Correspondance de sous-chaîne sur lineContent.
• --trace-name <texte> : Correspondance de sous-chaîne sur traceName.
• --type <LINE|FILE|DIRECTORY> : Filtre par type.

Paramètres (add / ensure) :

• Localisateur (obligatoire) : --file + --line + --content pour LINE (une sous-chaîne de cette ligne est OK) ; --file pour FILE/DIRECTORY. Ou positionnel FICHIER LIGNE CONTENU, ou chemin.
• --parent-id <uuid> (optionnel) : UUID du nœud parent ; répétez de l'ancêtre vers la racine → parent immédiat (préféré). Omettre pour la racine.
• --parent <json> (optionnel) : JSON du chemin parent (ne combinez pas avec --parent-id).
• --trace-name <texte> (optionnel) : Libellé du point de trace.
• --description <texte> (optionnel) : Description.
• --type <LINE|FILE|DIRECTORY> (optionnel) : Remplacement du type (par défaut : LINE).

Paramètres (move) :

• Localisateur (obligatoire) : --id, ou --file + --line + --content, ou --file seul pour FILE/DIRECTORY.
• Nouveau parent (obligatoire) : --parent-id (répétez de l'ancêtre vers la racine → parent immédiat) ou --parent JSON. Pour la racine, utilisez --parent []. Ne combinez pas --parent-id avec --parent.

Paramètres (delete) :

• Localisateur (obligatoire) : --id, ou --file + --line + --content, ou --file seul pour FILE/DIRECTORY.

Paramètres (rebind ; tous optionnels) :

• --file <chemin> : Limiter aux chemins relatifs ; répétable. Par défaut : tous les nœuds LINE du profil.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). Les erreurs affichent ERROR: … sur stderr et sortent avec un code non nul.

node-object :

{
  "id": "<uuid>",
  "parentId": "<uuid or empty>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<relative path>",
  "line": "<n or empty>",
  "content": "<trimmed lineContent>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search :

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<profile-name>",
  "matches": [ <node-object>, … ]
}

add (toujours créé ; pas de "skipped") :

[suite tronquée pour la traduction]