Skip to content

Commit 7234be0

Browse files
Wanderererclaude
Wandererer
and
claude
committed
feat: add --deep-dive mode, fix React forwardRef extraction and import remapping
- Add `--deep-dive` flag to `scan` and `sync`: generates per-project `.codebeacon/` + `CLAUDE.md` for each sub-project alongside a combined workspace output; running `codebeacon scan . --update` from any sub-project automatically finds parent config and syncs all projects - Walk-up config search via `find_config(walk_up=True)` so updates work from any sub-project directory without knowing the workspace root - Fix relative `output.dir` resolution in `_cmd_sync` — now resolves against the config file's parent directory instead of CWD - Fix `shares_db_entity` edge silently dropped when an edge already exists between two nodes; now merges `shared_entities` into existing edge - Fix React/Next.js `React.forwardRef()` components not extracted when non-exported (shadcn/ui style); add `component.hoc_local` query pattern - Fix `_remap_import_edges` case-insensitive label lookup so that `@/components/ui/card` resolves to node label `Card` - Add Configuration YAML section to de/es/fr/pt-BR READMEs - Document deep-dive mode across all 8 language READMEs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent c6f0644 commit 7234be0

16 files changed

Lines changed: 774 additions & 25 deletions

‎README.de.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Bestehende Tools lösen dieses Problem nur teilweise. Route-Analyzer erfassen Ih
4848
- **Community-Erkennung** — Leiden/Louvain-Clustering deckt tatsächliche Architekturgrenzen auf
4949
- **Inkrementeller Cache** — SHA-256-basiert; extrahiert nur seit dem letzten Scan geänderte Dateien neu
5050
- **Keine Konfiguration notwendig** — erkennt Frameworks und Sprachen automatisch; generiert `codebeacon.yaml` für Folgeläufe
51+
- **Deep-Dive-Modus** — `--deep-dive` erzeugt für jedes Sub-Projekt eigene `.codebeacon/` + `CLAUDE.md`; ein Update-Aufruf aus **beliebigem** Sub-Projekt-Ordner synchronisiert automatisch alle Projekte im Workspace
5152

5253
---
5354

@@ -129,6 +130,69 @@ project-root/
129130
obsidian/ ← Obsidian Vault (eine Notiz pro Graph-Knoten)
130131
```
131132

133+
### Deep-Dive-Modus
134+
135+
Mit `--deep-dive` erhält jedes Sub-Projekt sein eigenes `.codebeacon/` + `CLAUDE.md`. Claude Code lädt `CLAUDE.md`-Dateien hierarchisch — eine Sitzung in `api-server/` lädt also sowohl den Workspace-Überblick als auch die projektspezifischen Details.
136+
137+
Das entscheidende Merkmal: ein Update-Aufruf aus **jedem beliebigen Sub-Projekt** synchronisiert automatisch den gesamten Workspace:
138+
139+
```bash
140+
# Erster Deep-Dive-Scan
141+
codebeacon scan /workspace --deep-dive
142+
143+
# Später aus einem beliebigen Sub-Projekt — findet die übergeordnete Konfig und aktualisiert ALLE Projekte
144+
cd /workspace/api-server
145+
codebeacon scan . --update
146+
```
147+
148+
Ausgabestruktur:
149+
```
150+
workspace/
151+
CLAUDE.md ← kombiniert (alle Projekte)
152+
codebeacon.yaml ← deep_dive: true
153+
.codebeacon/ ← kombinierter Knowledge Graph
154+
api-server/
155+
CLAUDE.md ← nur api-server
156+
.codebeacon/ ← api-server-Graph
157+
frontend/
158+
CLAUDE.md ← nur frontend
159+
.codebeacon/ ← frontend-Graph
160+
```
161+
162+
## Konfiguration
163+
164+
Führe `codebeacon init` aus, um `codebeacon.yaml` zu generieren, oder erstelle die Datei manuell:
165+
166+
```yaml
167+
version: 1
168+
169+
projects:
170+
- name: api-server
171+
path: ./api-server
172+
type: spring-boot # optional: wird automatisch erkannt
173+
174+
- name: frontend
175+
path: ./frontend
176+
type: react
177+
178+
output:
179+
dir: .codebeacon
180+
wiki: true
181+
obsidian: true
182+
context_map:
183+
targets: [CLAUDE.md, .cursorrules, AGENTS.md]
184+
185+
wave:
186+
auto: true
187+
chunk_size: 300 # Dateien pro Chunk
188+
max_parallel: 5 # parallele Threads
189+
190+
semantic:
191+
enabled: false # mit --semantic überschreiben
192+
193+
deep_dive: false # auf true setzen für Pro-Projekt-Ausgabe
194+
```
195+
132196
### .codebeaconignore
133197
134198
Platziere eine `.codebeaconignore`-Datei im Projektstammverzeichnis, um Verzeichnisse oder Dateien vom Scan auszuschließen. Gleiche Syntax wie `.gitignore` — ein Muster pro Zeile, `#` für Kommentare.
@@ -231,6 +295,7 @@ codebeacon scan . --update # inkrementell: nur geänderte Dateien
231295
codebeacon scan . --wiki-only # Extraktion überspringen, Wiki/Obsidian/Kontext aus vorhandenem beacon.json regenerieren
232296
codebeacon scan . --semantic # LLM-semantische Extraktion
233297
codebeacon scan . --list-only # nur Frameworks erkennen
298+
codebeacon scan /workspace --deep-dive # Pro-Projekt- + kombinierte Workspace-Ausgabe
234299

235300
codebeacon init [pfad] # codebeacon.yaml generieren
236301
codebeacon sync # von codebeacon.yaml ausführen

‎README.es.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Las herramientas existentes resuelven esto de forma parcial. Los analizadores de
4848
- **Detección de comunidades** — clustering Leiden/Louvain revela los límites arquitectónicos reales
4949
- **Caché incremental** — basado en SHA-256; solo re-extrae archivos modificados desde el último escaneo
5050
- **Cero configuración** — detecta frameworks y lenguajes automáticamente; genera `codebeacon.yaml` para ejecuciones posteriores
51+
- **Modo Deep Dive** — `--deep-dive` genera `.codebeacon/` + `CLAUDE.md` propios para cada sub-proyecto; ejecutar el comando de actualización desde **cualquier** sub-proyecto sincroniza automáticamente todos los proyectos del workspace
5152

5253
---
5354

@@ -128,6 +129,69 @@ project-root/
128129
obsidian/ ← Obsidian Vault (una nota por nodo del grafo)
129130
```
130131

132+
### Modo Deep Dive
133+
134+
Con `--deep-dive`, cada sub-proyecto recibe su propio `.codebeacon/` + `CLAUDE.md`. Claude Code carga los archivos `CLAUDE.md` de forma jerárquica, por lo que una sesión en `api-server/` carga tanto la visión general del workspace como los detalles específicos del proyecto.
135+
136+
La clave: un comando de actualización desde **cualquier sub-proyecto** sincroniza todo el workspace automáticamente:
137+
138+
```bash
139+
# Primer escaneo deep dive
140+
codebeacon scan /workspace --deep-dive
141+
142+
# Más tarde, desde cualquier sub-proyecto — encuentra la config padre y actualiza TODOS los proyectos
143+
cd /workspace/api-server
144+
codebeacon scan . --update
145+
```
146+
147+
Estructura de salida:
148+
```
149+
workspace/
150+
CLAUDE.md ← combinado (todos los proyectos)
151+
codebeacon.yaml ← deep_dive: true
152+
.codebeacon/ ← grafo combinado
153+
api-server/
154+
CLAUDE.md ← solo api-server
155+
.codebeacon/
156+
frontend/
157+
CLAUDE.md ← solo frontend
158+
.codebeacon/
159+
```
160+
161+
## Configuración
162+
163+
Ejecuta `codebeacon init` para generar `codebeacon.yaml`, o escríbelo manualmente:
164+
165+
```yaml
166+
version: 1
167+
168+
projects:
169+
- name: api-server
170+
path: ./api-server
171+
type: spring-boot # opcional: se detecta automáticamente
172+
173+
- name: frontend
174+
path: ./frontend
175+
type: react
176+
177+
output:
178+
dir: .codebeacon
179+
wiki: true
180+
obsidian: true
181+
context_map:
182+
targets: [CLAUDE.md, .cursorrules, AGENTS.md]
183+
184+
wave:
185+
auto: true
186+
chunk_size: 300 # archivos por chunk
187+
max_parallel: 5 # hilos paralelos
188+
189+
semantic:
190+
enabled: false # sobrescribir con --semantic
191+
192+
deep_dive: false # establecer true para salida por proyecto
193+
```
194+
131195
### .codebeaconignore
132196
133197
Coloca un archivo `.codebeaconignore` en la raíz del proyecto para excluir directorios o archivos del escaneo. Misma sintaxis que `.gitignore` — un patrón por línea, `#` para comentarios.
@@ -230,6 +294,7 @@ codebeacon scan . --update # incremental: solo archivos modificad
230294
codebeacon scan . --wiki-only # saltar extracción, regenerar wiki/obsidian/contexto desde beacon.json existente
231295
codebeacon scan . --semantic # extracción semántica con LLM
232296
codebeacon scan . --list-only # solo detectar frameworks
297+
codebeacon scan /workspace --deep-dive # salida por proyecto + workspace combinado
233298

234299
codebeacon init [ruta] # generar codebeacon.yaml
235300
codebeacon sync # ejecutar desde codebeacon.yaml

‎README.fr.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Les outils existants ne résolvent ce problème qu'en partie. Les analyseurs de
4848
- **Détection de communautés** — clustering Leiden/Louvain révèle les vraies frontières architecturales
4949
- **Cache incrémental** — basé sur SHA-256 ; ré-extrait uniquement les fichiers modifiés depuis le dernier scan
5050
- **Zéro configuration** — détecte automatiquement les frameworks et langages ; génère `codebeacon.yaml` pour les exécutions suivantes
51+
- **Mode Deep Dive** — `--deep-dive` génère un `.codebeacon/` + `CLAUDE.md` propre à chaque sous-projet ; une commande de mise à jour depuis **n'importe quel** sous-projet synchronise automatiquement tous les projets du workspace
5152

5253
---
5354

@@ -128,6 +129,69 @@ project-root/
128129
obsidian/ ← Obsidian Vault (une note par nœud du graphe)
129130
```
130131

132+
### Mode Deep Dive
133+
134+
Avec `--deep-dive`, chaque sous-projet reçoit son propre `.codebeacon/` + `CLAUDE.md`. Claude Code charge les fichiers `CLAUDE.md` de manière hiérarchique — une session dans `api-server/` charge à la fois la vue d'ensemble du workspace et les détails spécifiques au projet.
135+
136+
Le point clé : une commande de mise à jour depuis **n'importe quel sous-projet** synchronise automatiquement tout le workspace :
137+
138+
```bash
139+
# Premier scan deep dive
140+
codebeacon scan /workspace --deep-dive
141+
142+
# Plus tard, depuis n'importe quel sous-projet — trouve la config parente et met à jour TOUS les projets
143+
cd /workspace/api-server
144+
codebeacon scan . --update
145+
```
146+
147+
Structure de sortie :
148+
```
149+
workspace/
150+
CLAUDE.md ← combiné (tous les projets)
151+
codebeacon.yaml ← deep_dive: true
152+
.codebeacon/ ← graphe combiné
153+
api-server/
154+
CLAUDE.md ← api-server uniquement
155+
.codebeacon/
156+
frontend/
157+
CLAUDE.md ← frontend uniquement
158+
.codebeacon/
159+
```
160+
161+
## Configuration
162+
163+
Exécutez `codebeacon init` pour générer `codebeacon.yaml`, ou créez-le manuellement :
164+
165+
```yaml
166+
version: 1
167+
168+
projects:
169+
- name: api-server
170+
path: ./api-server
171+
type: spring-boot # optionnel : détecté automatiquement
172+
173+
- name: frontend
174+
path: ./frontend
175+
type: react
176+
177+
output:
178+
dir: .codebeacon
179+
wiki: true
180+
obsidian: true
181+
context_map:
182+
targets: [CLAUDE.md, .cursorrules, AGENTS.md]
183+
184+
wave:
185+
auto: true
186+
chunk_size: 300 # fichiers par chunk
187+
max_parallel: 5 # threads parallèles
188+
189+
semantic:
190+
enabled: false # écraser avec --semantic
191+
192+
deep_dive: false # mettre à true pour une sortie par projet
193+
```
194+
131195
### .codebeaconignore
132196
133197
Placez un fichier `.codebeaconignore` à la racine du projet pour exclure des répertoires ou fichiers du scan. Même syntaxe que `.gitignore` — un motif par ligne, `#` pour les commentaires.
@@ -230,6 +294,7 @@ codebeacon scan . --update # incrémental : fichiers modifiés se
230294
codebeacon scan . --wiki-only # ignorer la ré-extraction, régénérer wiki/obsidian/contexte depuis beacon.json existant
231295
codebeacon scan . --semantic # extraction sémantique LLM
232296
codebeacon scan . --list-only # détecter les frameworks uniquement
297+
codebeacon scan /workspace --deep-dive # sortie par projet + workspace combiné
233298

234299
codebeacon init [chemin] # générer codebeacon.yaml
235300
codebeacon sync # exécuter depuis codebeacon.yaml

‎README.ja.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ AI コーディングセッションを新しく開くたびに、アシスタ
4848
- **コミュニティ検出** — Leiden/Louvain クラスタリングで実際のアーキテクチャ境界を発見
4949
- **インクリメンタルキャッシュ** — SHA-256 ベース；前回スキャン以降に変更されたファイルのみ再抽出
5050
- **ゼロ設定** — フレームワークと言語を自動検出；繰り返し実行のために `codebeacon.yaml` を自動生成
51+
- **ディープダイブモード** — `--deep-dive` で各サブプロジェクトに専用の `.codebeacon/` + `CLAUDE.md` を生成；**どのサブプロジェクトからでも**更新コマンドを実行するだけでワークスペース全体が自動同期
5152

5253
---
5354

@@ -135,6 +136,35 @@ project-root/
135136
obsidian/ ← Obsidian Vault (グラフノードごとに 1 ノート)
136137
```
137138

139+
### ディープダイブモード
140+
141+
`--deep-dive` を使うと、各サブプロジェクトが独自の `.codebeacon/` + `CLAUDE.md` を持ちます。Claude Code は `CLAUDE.md` を階層的にロードするため、`api-server/` でセッションを開くとワークスペース全体の概要とプロジェクト固有の詳細が両方ロードされます。
142+
143+
最大のポイント：**どのサブプロジェクトから実行しても**、親の設定ファイルを自動検出してワークスペース全体を更新します：
144+
145+
```bash
146+
# 初回ディープダイブスキャン
147+
codebeacon scan /workspace --deep-dive
148+
149+
# 以降、どのサブプロジェクトからでも — 親の設定を見つけ、全プロジェクトを更新
150+
cd /workspace/api-server
151+
codebeacon scan . --update
152+
```
153+
154+
出力構造：
155+
```
156+
workspace/
157+
CLAUDE.md ← 統合 (全プロジェクト)
158+
codebeacon.yaml ← deep_dive: true
159+
.codebeacon/ ← 統合ナレッジグラフ
160+
api-server/
161+
CLAUDE.md ← api-server のみ
162+
.codebeacon/
163+
frontend/
164+
CLAUDE.md ← frontend のみ
165+
.codebeacon/
166+
```
167+
138168
---
139169

140170
## AI 連携
@@ -229,6 +259,7 @@ codebeacon scan . --wiki-only # 再抽出をスキップし、既存
229259
codebeacon scan . --obsidian-dir <path> # Obsidian Vault をカスタム場所に書き込み
230260
codebeacon scan . --semantic # LLM セマンティック抽出を有効化
231261
codebeacon scan . --list-only # フレームワーク検出のみ、抽出なし
262+
codebeacon scan /workspace --deep-dive # プロジェクト別 + 統合ワークスペース出力
232263

233264
# 設定ベースモード
234265
codebeacon init [path] # codebeacon.yaml を自動生成
@@ -276,6 +307,8 @@ wave:
276307

277308
semantic:
278309
enabled: false # --semantic フラグでオーバーライド
310+
311+
deep_dive: false # true にすると各プロジェクト別出力を生成
279312
```
280313
281314
### .codebeaconignore

‎README.ko.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ AI 코딩 세션을 새로 열 때마다 어시스턴트는 백지 상태에서
4848
- **커뮤니티 감지** — Leiden/Louvain 클러스터링으로 실제 아키텍처 경계 도출
4949
- **증분 캐시** — SHA-256 기반; 마지막 스캔 이후 변경된 파일만 재추출
5050
- **제로 설정** — 프레임워크와 언어 자동 감지; 반복 실행을 위한 `codebeacon.yaml` 자동 생성
51+
- **딥다이브 모드** — `--deep-dive`는 각 서브 프로젝트에 개별 `.codebeacon/` + `CLAUDE.md`를 생성; 어느 서브 프로젝트 폴더에서든 `codebeacon scan . --update`를 실행하면 워크스페이스의 모든 프로젝트가 자동으로 업데이트됨
5152

5253
---
5354

@@ -134,6 +135,47 @@ project-root/
134135
obsidian/ ← Obsidian 볼트 (그래프 노드당 노트 1개)
135136
```
136137

138+
### 딥다이브 모드
139+
140+
`--deep-dive`를 사용하면 각 서브 프로젝트에도 자체 `.codebeacon/` 디렉토리와 `CLAUDE.md`가 생성되어, 서브 프로젝트 내에서 열린 AI 세션이 프로젝트별 전체 컨텍스트를 갖게 됩니다:
141+
142+
```
143+
workspace/
144+
CLAUDE.md ← 통합 (모든 프로젝트)
145+
.cursorrules
146+
AGENTS.md
147+
codebeacon.yaml ← deep_dive: true
148+
.codebeacon/ ← 통합 지식 그래프
149+
beacon.json
150+
wiki/
151+
obsidian/
152+
api-server/
153+
CLAUDE.md ← api-server 전용
154+
.codebeacon/ ← api-server 그래프
155+
beacon.json
156+
wiki/
157+
obsidian/
158+
frontend/
159+
CLAUDE.md ← frontend 전용
160+
.codebeacon/ ← frontend 그래프
161+
beacon.json
162+
wiki/
163+
obsidian/
164+
```
165+
166+
Claude Code는 `CLAUDE.md`를 계층적으로 로드하므로, `api-server/`에서 세션을 열면 상위 워크스페이스 개요와 프로젝트별 세부 정보가 모두 로드됩니다.
167+
168+
초기 스캔 이후 어느 서브 프로젝트에서든 업데이트:
169+
170+
```bash
171+
# 초기 딥다이브 스캔
172+
codebeacon scan /workspace --deep-dive
173+
174+
# 이후 어느 서브 프로젝트에서든 — 부모 설정을 찾아 모든 프로젝트 업데이트
175+
cd /workspace/api-server
176+
codebeacon scan . --update
177+
```
178+
137179
---
138180

139181
## AI 통합
@@ -228,6 +270,7 @@ codebeacon scan . --wiki-only # 재추출 건너뛰고 기존 beacon
228270
codebeacon scan . --obsidian-dir <path> # Obsidian 볼트를 커스텀 위치에 저장
229271
codebeacon scan . --semantic # LLM 시맨틱 추출 활성화
230272
codebeacon scan . --list-only # 프레임워크 감지만, 추출 제외
273+
codebeacon scan /workspace --deep-dive # 프로젝트별 + 통합 워크스페이스 출력
231274

232275
# 설정 기반 모드
233276
codebeacon init [path] # codebeacon.yaml 자동 생성
@@ -275,6 +318,8 @@ wave:
275318

276319
semantic:
277320
enabled: false # --semantic 플래그로 오버라이드
321+
322+
deep_dive: false # true로 설정하면 프로젝트별 출력 생성
278323
```
279324
280325
### .codebeaconignore

0 commit comments

Comments
 (0)