codebeacon 0.2.0__tar.gz → 0.3.0__tar.gz

{codebeacon-0.2.0 → codebeacon-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.2.0
+Version: 0.3.0
 Summary: Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph
 Project-URL: Homepage, https://github.com/codebeacon/codebeacon
 Project-URL: Repository, https://github.com/codebeacon/codebeacon
@@ -85,9 +85,15 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 - **Tree-sitter based** — structural AST parsing, not regex; all language grammars included out of the box
 - **Two-pass DI resolution** — Pass 1 extracts local AST nodes; Pass 2 builds a global symbol table and resolves Interface → Implementation mappings that single-pass tools miss
 - **Wave merge architecture** — files processed in parallel chunks, results merged globally; handles large monorepos without memory blowouts
-- **Multiple output formats** — JSON knowledge graph, Markdown wiki, Obsidian vault, AI context maps, MCP server
+- **Multiple output formats** — JSON knowledge graph, Markdown wiki, Obsidian vault, AI context maps, MCP server, interactive HTML
+- **Visual exploration** — `beacon.html` (D3 collapsible tree) and `callflow.html` (Mermaid architecture diagrams grouped by community), regenerated on every scan
 - **Community detection** — Leiden/Louvain clustering reveals your actual architectural boundaries
-- **Incremental cache** — SHA-256 based; only re-extracts files that changed since the last scan
+- **Incremental cache** — SHA-256 + mtime/size fast path; mtime-only bumps from sync tools (Obsidian/iCloud/Nextcloud) never trigger needless re-extraction
+- **Confidence promotion** — cross-file `calls` edges are promoted from INFERRED to EXTRACTED when an explicit import proves the binding
+- **Safe writes** — beacon.json has a shrink guard (a partial run can never overwrite a complete graph) and stamps `built_at_commit` so REPORT.md flags stale outputs against the current HEAD
+- **Multi-developer friendly** — `codebeacon hook install` registers a git merge driver for `beacon.json` and a post-commit incremental rebuild hook, so two devs scanning the same branch never produce merge conflicts in the graph
+- **Hardened output** — YAML frontmatter and MCP labels are sanitized: U+2028/U+2029, C0 controls, and bidi marks are stripped before they reach Obsidian, Cursor, or the agent
+- **gitignore-style `.codebeaconignore`** — last-match-wins with `!` negation, dir patterns (`build/`), anchored patterns (`/secrets.txt`), trailing-whitespace rules
 - **Zero configuration** — auto-detects frameworks and languages; generates `codebeacon.yaml` for repeat runs
 - **Deep-dive mode** — `--deep-dive` generates per-project `.codebeacon/` + `CLAUDE.md` for every sub-project; running `codebeacon scan . --update` from any sub-project folder automatically syncs all projects in the workspace
 
@@ -159,8 +165,10 @@ project-root/
   .cursorrules           ← Cursor IDE context (same merge strategy)
   AGENTS.md              ← OpenAI Agents / Codex context (same merge strategy)
   .codebeacon/
-    beacon.json          ← full knowledge graph (node-link JSON, queryable)
-    REPORT.md            ← god nodes, surprising connections, hub files
+    beacon.json          ← full knowledge graph; embeds `meta.built_at_commit`
+    beacon.html          ← D3 collapsible-tree viewer (open in browser)
+    callflow.html        ← Mermaid call-flow diagrams grouped by community
+    REPORT.md            ← god nodes, surprising connections, hub files, freshness
     wiki/
       index.md           ← global index (~200 tokens)
       overview.md        ← platform stats + cross-project connections
@@ -307,7 +315,7 @@ All language parsers (Java, Kotlin, Python, JavaScript, TypeScript, Go, Ruby, PH
 codebeacon scan <path> [options]
 codebeacon scan .                         # current directory
 codebeacon scan /workspace                # workspace root (multi-project)
-codebeacon scan . --update                # incremental: only re-extract changed files
+codebeacon scan . --update                # incremental: mtime/size fast path + content-hash fallback
 codebeacon scan . --wiki-only             # skip re-extraction, regenerate wiki/obsidian/context map from existing beacon.json
 codebeacon scan . --obsidian-dir <path>   # write Obsidian vault to custom location
 codebeacon scan . --semantic              # enable LLM semantic extraction
@@ -319,9 +327,13 @@ codebeacon init [path]                    # auto-generate codebeacon.yaml
 codebeacon sync                           # run from codebeacon.yaml
 codebeacon sync --config <file>           # use a specific config file
 
-# Query the knowledge graph (coming soon)
-codebeacon query <term>                   # search nodes and edges
-codebeacon path <source> <target>         # shortest path between two nodes
+# Query the knowledge graph
+codebeacon query <term> [--dir .codebeacon] [--limit N]   # search nodes by label substring
+codebeacon path <source> <target> [--dir .codebeacon]     # shortest dependency path
+
+# Multi-developer support (git plumbing)
+codebeacon hook install [path]            # install merge driver + post-commit incremental rebuild
+codebeacon merge-driver <base> <cur> <other>  # invoked by git after `hook install`; union-merges beacon.json
 
 # Integrations
 codebeacon serve [--dir .codebeacon]      # start MCP server (stdio)
@@ -330,6 +342,58 @@ codebeacon install                        # install Claude Code skill
 
 ---
 
+## Visual Exploration
+
+Every scan writes two self-contained HTML files alongside `beacon.json`:
+
+```
+.codebeacon/beacon.html      # D3 v7 collapsible tree — open in any browser
+.codebeacon/callflow.html    # Mermaid architecture diagrams, one per community
+```
+
+No build step, no static server, no copy-paste. Open the file, click to expand
+projects → types → nodes; hover for source paths and degree. `callflow.html`
+groups your graph by community and renders each as a Mermaid flowchart, with
+the cross-community out-edges listed in a collapsed table.
+
+---
+
+## Multi-Developer Workflow
+
+Two developers running `codebeacon scan` on the same branch produce two
+slightly different `beacon.json` files — historically a merge conflict
+hotspot. `codebeacon hook install` solves this:
+
+```bash
+codebeacon hook install            # in the repo root
+```
+
+This registers:
+
+- a **git merge driver** that union-merges two `beacon.json` files into one
+  (nodes deduped by ID, edges deduped by `(source, target, relation)`),
+- a `.gitattributes` entry pointing `*beacon.json` at the driver,
+- a **post-commit hook** that runs `codebeacon scan . --update` in the
+  background so the graph never falls behind your commits. Output goes to
+  `~/.cache/codebeacon-rebuild.log`.
+
+The merge driver always exits 0 — a graph regen never blocks a real merge.
+
+---
+
+## Safety Guarantees
+
+A few invariants the writer enforces on every successful scan:
+
+| Guard | What it prevents |
+|---|---|
+| **Shrink guard** | A partial-extraction failure or interrupted run can never overwrite a larger complete `beacon.json`. Pass `force=True` from the API to bypass. |
+| **Atomic write** | `beacon.json` is written via `os.replace`, so the file is either complete or untouched — no half-written graphs. |
+| **`built_at_commit` stamp** | `beacon.json` embeds `meta.built_at_commit` (full SHA) and `REPORT.md` shows the short SHA. If HEAD has advanced past it, the report flags the graph as `⚠ stale` with a one-line remediation hint. |
+| **Frontmatter / label hardening** | YAML frontmatter values are single-quoted and escape U+2028, U+2029, tabs, and C0 controls; MCP tool output runs every label through the same sanitizer. A malicious identifier in source code cannot break Obsidian's YAML parser or inject control sequences into an LLM agent's context. |
+
+---
+
 ## Configuration
 
 Run `codebeacon init` to generate `codebeacon.yaml`, or write it manually:
@@ -366,16 +430,29 @@ deep_dive: false               # set to true to generate per-project outputs
 
 ### .codebeaconignore
 
-Place a `.codebeaconignore` file at your project root to exclude directories or files from scanning. Syntax is the same as `.gitignore` — one pattern per line, `#` for comments.
+Place a `.codebeaconignore` file at your project root to exclude directories or files from scanning. Syntax matches `.gitignore` — last-match-wins with `!` negation, anchored patterns (`/foo`), dir-only patterns (`build/`), and comments:
 
 ```
 # .codebeaconignore
-generated/
+
+# directories
 build/
-*.generated.ts
+generated/
 fixtures/
+
+# anchored to root only
+/scripts/local-only.ts
+
+# glob patterns
+*.gen.ts
+**/snapshots/**
+
+# re-include a specific file even though build/ is ignored
+!build/manifest.ts
 ```
 
+`!pattern` re-includes a previously-ignored path; later rules override earlier ones. The walker prunes directories whose name matches the rule set, but defers pruning when any negation rule could un-ignore a nested file.
+
 ---
 
 ## How It Compares

{codebeacon-0.2.0 → codebeacon-0.3.0}/README.de.md

@@ -44,9 +44,15 @@ Bestehende Tools lösen dieses Problem nur teilweise. Route-Analyzer erfassen Ih
 - **Auf tree-sitter basierend** — strukturelles AST-Parsing, keine Regex; Sprachgrammatiken standardmäßig enthalten
 - **2-Pass DI-Auflösung** — Pass 1 extrahiert lokale AST-Knoten; Pass 2 baut eine globale Symboltabelle auf und löst Interface → Implementation-Mappings auf
 - **Wave-Merge-Architektur** — Dateien werden in parallelen Chunks verarbeitet und global zusammengeführt; auch große Monorepos ohne Speicherprobleme
-- **Mehrere Ausgabeformate** — JSON-Knowledge-Graph, Markdown-Wiki, Obsidian Vault, KI-Kontextkarten, MCP-Server
+- **Mehrere Ausgabeformate** — JSON-Knowledge-Graph, Markdown-Wiki, Obsidian Vault, KI-Kontextkarten, MCP-Server, interaktives HTML
+- **Visuelle Exploration** — `beacon.html` (D3 einklappbarer Baum) und `callflow.html` (Mermaid-Architekturdiagramme nach Community gruppiert) werden bei jedem Scan neu erzeugt
 - **Community-Erkennung** — Leiden/Louvain-Clustering deckt tatsächliche Architekturgrenzen auf
-- **Inkrementeller Cache** — SHA-256-basiert; extrahiert nur seit dem letzten Scan geänderte Dateien neu
+- **Inkrementeller Cache** — SHA-256 + mtime/size Fast-Path; reine mtime-Änderungen durch Sync-Tools (Obsidian/iCloud/Nextcloud) lösen niemals eine unnötige Re-Extraktion aus
+- **Confidence-Promotion** — datei-übergreifende `calls`-Kanten werden automatisch von INFERRED auf EXTRACTED hochgestuft, wenn ein expliziter Import das Binding belegt
+- **Sichere Schreibvorgänge** — beacon.json hat einen Shrink-Guard (ein Teil-Lauf kann niemals einen vollständigen Graph überschreiben) und stempelt `built_at_commit`, sodass REPORT.md veraltete Ausgaben gegen den aktuellen HEAD kennzeichnet
+- **Multi-Entwickler-freundlich** — `codebeacon hook install` registriert einen git-Merge-Driver für `beacon.json` und einen Post-Commit-Hook für inkrementelle Rebuilds; zwei Devs, die denselben Branch scannen, produzieren niemals Merge-Konflikte im Graph
+- **Gehärtete Ausgabe** — YAML-Frontmatter und MCP-Labels werden sanitisiert: U+2028/U+2029, C0-Steuerzeichen und Bidi-Marken werden entfernt, bevor sie Obsidian, Cursor oder den Agenten erreichen
+- **`.codebeaconignore` im gitignore-Stil** — last-match-wins mit `!`-Negation, Verzeichnis-Patterns (`build/`), verankerte Patterns (`/secrets.txt`), Trailing-Whitespace-Regeln
 - **Keine Konfiguration notwendig** — erkennt Frameworks und Sprachen automatisch; generiert `codebeacon.yaml` für Folgeläufe
 - **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
 
@@ -116,8 +122,10 @@ project-root/
   .cursorrules           ← Cursor-IDE-Kontext (gleiche Merge-Strategie)
   AGENTS.md              ← OpenAI-Agents-/Codex-Kontext (gleiche Merge-Strategie)
   .codebeacon/
-    beacon.json          ← vollständiger Knowledge Graph (Node-Link-JSON, abfragbar)
-    REPORT.md            ← God-Nodes, überraschende Verbindungen, Hub-Dateien
+    beacon.json          ← vollständiger Knowledge Graph; bettet `meta.built_at_commit` ein
+    beacon.html          ← D3-Baum-Viewer (im Browser öffnen)
+    callflow.html        ← Mermaid-Call-Flow-Diagramme, nach Community gruppiert
+    REPORT.md            ← God-Nodes, überraschende Verbindungen, Hub-Dateien, Frische
     wiki/
       index.md
       overview.md
@@ -159,6 +167,50 @@ workspace/
     .codebeacon/              ← frontend-Graph
 ```
 
+## Visuelle Exploration
+
+Jeder Scan schreibt zwei eigenständige HTML-Dateien neben `beacon.json`:
+
+```
+.codebeacon/beacon.html      # D3 v7 einklappbarer Baum — in jedem Browser öffnen
+.codebeacon/callflow.html    # Mermaid-Architekturdiagramme, eines pro Community
+```
+
+Kein Build, kein statischer Server, kein Copy-Paste. Datei öffnen, klicken um Projekte → Typen → Knoten auszuklappen; Hover zeigt Source-Pfade und Grad. `callflow.html` gruppiert den Graph nach Community und rendert jede als Mermaid-Flowchart, mit den ausgehenden Cross-Community-Kanten in einer einklappbaren Tabelle.
+
+---
+
+## Multi-Entwickler-Workflow
+
+Zwei Devs, die `codebeacon scan` auf demselben Branch ausführen, produzieren leicht unterschiedliche `beacon.json` — historisch ein Merge-Konflikt-Hotspot. `codebeacon hook install` löst das:
+
+```bash
+codebeacon hook install            # im Repo-Root
+```
+
+Es registriert:
+
+- einen **git-Merge-Driver**, der zwei `beacon.json` per Union zu einer zusammenführt (Knoten per ID, Kanten per `(source, target, relation)` dedupliziert),
+- einen `.gitattributes`-Eintrag, der `*beacon.json` auf den Driver verweist,
+- einen **Post-Commit-Hook**, der `codebeacon scan . --update` im Hintergrund ausführt, damit der Graph niemals hinter den Commits zurückbleibt. Ausgabe in `~/.cache/codebeacon-rebuild.log`.
+
+Der Merge-Driver beendet sich immer mit 0 — eine Graph-Regeneration blockiert niemals einen echten Merge.
+
+---
+
+## Sicherheitsgarantien
+
+Invarianten, die der Writer bei jedem erfolgreichen Scan durchsetzt:
+
+| Guard | Was er verhindert |
+|---|---|
+| **Shrink-Guard** | Eine partielle Extraktion oder ein unterbrochener Lauf kann niemals eine größere vollständige `beacon.json` überschreiben. Per `force=True` aus der API umgehbar. |
+| **Atomares Schreiben** | `beacon.json` wird via `os.replace` geschrieben, die Datei ist also entweder komplett oder unangetastet — niemals halb geschrieben. |
+| **`built_at_commit`-Stempel** | `beacon.json` bettet `meta.built_at_commit` (vollständige SHA) ein und `REPORT.md` zeigt die Kurz-SHA. Wenn HEAD weiter ist, markiert der Report den Graphen als `⚠ stale` mit einem einzeiligen Hinweis. |
+| **Frontmatter-/Label-Härtung** | YAML-Frontmatter-Werte sind single-quoted und escapen U+2028, U+2029, Tab und C0-Steuerzeichen; MCP-Tool-Ausgabe lässt jedes Label durch denselben Sanitizer laufen. Ein böswilliger Identifier im Quellcode kann Obsidians YAML-Parser nicht zerschlagen oder Steuersequenzen in den Kontext eines LLM-Agenten injizieren. |
+
+---
+
 ## Konfiguration
 
 Führe `codebeacon init` aus, um `codebeacon.yaml` zu generieren, oder erstelle die Datei manuell:
@@ -195,16 +247,29 @@ deep_dive: false               # auf true setzen für Pro-Projekt-Ausgabe
 
 ### .codebeaconignore
 
-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.
+Platziere eine `.codebeaconignore`-Datei im Projektstammverzeichnis, um Verzeichnisse oder Dateien vom Scan auszuschließen. Semantik konform zu `.gitignore` — last-match-wins mit `!`-Negation, verankerte Muster (`/foo`), nur-Verzeichnis-Muster (`build/`), Kommentare:
 
 ```
 # .codebeaconignore
-generated/
+
+# Verzeichnisse
 build/
-*.generated.ts
+generated/
 fixtures/
+
+# nur am Root verankert
+/scripts/local-only.ts
+
+# Glob-Muster
+*.gen.ts
+**/snapshots/**
+
+# eine Datei wieder einschließen, auch wenn build/ ignoriert ist
+!build/manifest.ts
 ```
 
+`!pattern` schließt einen zuvor ignorierten Pfad wieder ein; spätere Regeln überschreiben frühere. Der Walker schneidet Verzeichnisse weg, deren Name auf das Regelset matcht, aber er verschiebt das Wegschneiden, wenn eine Negationsregel eine geschachtelte Datei wieder einschließen könnte.
+
 ---
 
 ## KI-Integration
@@ -300,8 +365,12 @@ codebeacon scan /workspace --deep-dive    # Pro-Projekt- + kombinierte Workspace
 codebeacon init [pfad]                    # codebeacon.yaml generieren
 codebeacon sync                           # von codebeacon.yaml ausführen
 
-codebeacon query <Begriff>                # Graph durchsuchen (demnächst)
-codebeacon path <Quelle> <Ziel>           # kürzester Pfad zwischen zwei Knoten
+codebeacon query <Begriff> [--dir .codebeacon] [--limit N]   # Knoten per Label-Substring suchen
+codebeacon path <Quelle> <Ziel> [--dir .codebeacon]          # kürzester Abhängigkeitspfad
+
+# Multi-Entwickler-Support (git plumbing)
+codebeacon hook install [path]            # Merge-Driver + Post-Commit-Inkrement-Rebuild installieren
+codebeacon merge-driver <base> <cur> <other>  # von git nach `hook install` aufgerufen; Union-Merge von beacon.json
 
 codebeacon serve [--dir .codebeacon]      # MCP-Server starten (stdio)
 codebeacon install                        # Claude-Code-Skill installieren

{codebeacon-0.2.0 → codebeacon-0.3.0}/README.es.md

@@ -44,9 +44,15 @@ Las herramientas existentes resuelven esto de forma parcial. Los analizadores de
 - **Basado en tree-sitter** — análisis AST estructural, no expresiones regulares; gramáticas de lenguaje incluidas por defecto
 - **Resolución DI en 2 pasos** — Pass 1 extrae nodos AST locales; Pass 2 construye una tabla de símbolos global y resuelve los mapeos Interface → Implementation
 - **Arquitectura Wave merge** — archivos procesados en chunks paralelos y fusionados globalmente; maneja grandes monorepos sin problemas de memoria
-- **Múltiples formatos de salida** — grafo JSON, wiki Markdown, Obsidian Vault, mapas de contexto para IA, servidor MCP
+- **Múltiples formatos de salida** — grafo JSON, wiki Markdown, Obsidian Vault, mapas de contexto para IA, servidor MCP, HTML interactivo
+- **Exploración visual** — `beacon.html` (árbol colapsable D3) y `callflow.html` (diagramas Mermaid de arquitectura por comunidad) regenerados en cada escaneo
 - **Detección de comunidades** — clustering Leiden/Louvain revela los límites arquitectónicos reales
-- **Caché incremental** — basado en SHA-256; solo re-extrae archivos modificados desde el último escaneo
+- **Caché incremental** — SHA-256 + ruta rápida por mtime/size; los cambios de mtime sin cambio de contenido (Obsidian/iCloud/Nextcloud) nunca disparan re-extracción innecesaria
+- **Promoción de confianza** — los edges `calls` entre archivos pasan de INFERRED a EXTRACTED automáticamente cuando un import explícito prueba el binding
+- **Escrituras seguras** — beacon.json tiene shrink guard (una ejecución parcial nunca puede sobrescribir un grafo completo) y estampa `built_at_commit` para que REPORT.md marque la salida como stale frente al HEAD actual
+- **Amigable para múltiples desarrolladores** — `codebeacon hook install` registra un git merge driver para `beacon.json` y un hook post-commit de rebuild incremental, así dos devs escaneando la misma rama nunca producen conflictos de merge en el grafo
+- **Salida endurecida** — los frontmatter YAML y las etiquetas MCP se sanitizan: U+2028/U+2029, controles C0 y marcas bidi se eliminan antes de llegar a Obsidian, Cursor o al agente
+- **`.codebeaconignore` estilo gitignore** — last-match-wins con negación `!`, patrones de directorio (`build/`), patrones anclados (`/secrets.txt`), reglas de espacio final
 - **Cero configuración** — detecta frameworks y lenguajes automáticamente; genera `codebeacon.yaml` para ejecuciones posteriores
 - **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
 
@@ -115,8 +121,10 @@ project-root/
   .cursorrules           ← contexto para Cursor IDE (misma estrategia de fusión)
   AGENTS.md              ← contexto para OpenAI Agents / Codex (misma estrategia de fusión)
   .codebeacon/
-    beacon.json          ← grafo de conocimiento completo (JSON node-link, consultable)
-    REPORT.md            ← nodos dios, conexiones sorprendentes, archivos hub
+    beacon.json          ← grafo de conocimiento completo; incrusta `meta.built_at_commit`
+    beacon.html          ← visor de árbol colapsable D3 (abrir en cualquier navegador)
+    callflow.html        ← diagramas Mermaid de call-flow agrupados por comunidad
+    REPORT.md            ← nodos dios, conexiones sorprendentes, archivos hub, frescura
     wiki/
       index.md
       overview.md
@@ -158,6 +166,50 @@ workspace/
     .codebeacon/
 ```
 
+## Exploración visual
+
+Cada escaneo escribe dos archivos HTML autocontenidos junto a `beacon.json`:
+
+```
+.codebeacon/beacon.html      # árbol colapsable D3 v7 — abrir en cualquier navegador
+.codebeacon/callflow.html    # diagramas Mermaid de arquitectura, uno por comunidad
+```
+
+Sin build, sin servidor estático, sin copy-paste. Abre el archivo, haz clic para expandir proyectos → tipos → nodos; hover para ver paths y degree. `callflow.html` agrupa el grafo por comunidad y renderiza cada una como flowchart Mermaid, con los edges salientes a otras comunidades en una tabla plegada.
+
+---
+
+## Flujo multi-desarrollador
+
+Dos devs ejecutando `codebeacon scan` en la misma rama producen `beacon.json` ligeramente distintos — un punto clásico de conflicto de merge. `codebeacon hook install` lo resuelve:
+
+```bash
+codebeacon hook install            # en la raíz del repo
+```
+
+Registra:
+
+- un **git merge driver** que union-mergea dos `beacon.json` en uno (nodos deduplicados por ID, edges deduplicados por `(source, target, relation)`),
+- una entrada `.gitattributes` apuntando `*beacon.json` al driver,
+- un **hook post-commit** que ejecuta `codebeacon scan . --update` en background para que el grafo nunca quede atrás de los commits. Salida en `~/.cache/codebeacon-rebuild.log`.
+
+El merge driver siempre sale con 0 — la regeneración del grafo nunca bloquea un merge real.
+
+---
+
+## Garantías de seguridad
+
+Invariantes que el writer impone en cada escaneo exitoso:
+
+| Guard | Lo que previene |
+|---|---|
+| **Shrink guard** | Una extracción parcial fallida o una ejecución interrumpida nunca puede sobrescribir un `beacon.json` completo y más grande. Bypass con `force=True` desde la API. |
+| **Escritura atómica** | `beacon.json` se escribe vía `os.replace`, así que el archivo está completo o intacto — nunca a medio escribir. |
+| **Estampa `built_at_commit`** | `beacon.json` incrusta `meta.built_at_commit` (SHA completo) y `REPORT.md` muestra el SHA corto. Si HEAD avanzó, el reporte marca el grafo como `⚠ stale` con un hint de remediación. |
+| **Hardening de frontmatter / etiquetas** | Los valores YAML van entre comillas simples y escapan U+2028, U+2029, tab y controles C0; la salida MCP pasa todas las etiquetas por el mismo sanitizer. Un identificador malicioso en código fuente no puede romper el parser YAML de Obsidian ni inyectar secuencias de control en el contexto de un agente LLM. |
+
+---
+
 ## Configuración
 
 Ejecuta `codebeacon init` para generar `codebeacon.yaml`, o escríbelo manualmente:
@@ -194,16 +246,29 @@ deep_dive: false               # establecer true para salida por proyecto
 
 ### .codebeaconignore
 
-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.
+Coloca un archivo `.codebeaconignore` en la raíz del proyecto para excluir directorios o archivos del escaneo. Semántica compatible con `.gitignore` — last-match-wins con negación `!`, patrones anclados (`/foo`), patrones solo-directorio (`build/`), comentarios:
 
 ```
 # .codebeaconignore
-generated/
+
+# directorios
 build/
-*.generated.ts
+generated/
 fixtures/
+
+# anclado solo a la raíz
+/scripts/local-only.ts
+
+# patrones glob
+*.gen.ts
+**/snapshots/**
+
+# re-incluir un archivo aunque build/ esté ignorado
+!build/manifest.ts
 ```
 
+`!pattern` re-incluye una ruta previamente ignorada; reglas posteriores anulan las anteriores. El walker poda directorios cuyo nombre coincida con las reglas, pero pospone la poda cuando alguna regla de negación pueda re-incluir un archivo anidado.
+
 ---
 
 ## Integración con IA
@@ -299,8 +364,12 @@ codebeacon scan /workspace --deep-dive    # salida por proyecto + workspace comb
 codebeacon init [ruta]                    # generar codebeacon.yaml
 codebeacon sync                           # ejecutar desde codebeacon.yaml
 
-codebeacon query <término>                # buscar en el grafo (próximamente)
-codebeacon path <origen> <destino>        # ruta más corta entre dos nodos
+codebeacon query <término> [--dir .codebeacon] [--limit N]   # buscar nodos por substring de etiqueta
+codebeacon path <origen> <destino> [--dir .codebeacon]       # ruta más corta de dependencias
+
+# Soporte multi-desarrollador (git plumbing)
+codebeacon hook install [path]            # instala merge driver + hook post-commit incremental
+codebeacon merge-driver <base> <cur> <other>  # invocado por git tras `hook install`; union-merge de beacon.json
 
 codebeacon serve [--dir .codebeacon]      # servidor MCP (stdio)
 codebeacon install                        # instalar skill de Claude Code

{codebeacon-0.2.0 → codebeacon-0.3.0}/README.fr.md

@@ -44,9 +44,15 @@ Les outils existants ne résolvent ce problème qu'en partie. Les analyseurs de
 - **Basé sur tree-sitter** — analyse AST structurelle, pas de regex ; grammaires de langage incluses par défaut
 - **Résolution DI en 2 passes** — Pass 1 extrait les nœuds AST locaux ; Pass 2 construit une table de symboles globale et résout les mappings Interface → Implementation
 - **Architecture Wave merge** — fichiers traités en chunks parallèles puis fusionnés globalement ; gère les grands monorepos sans problème mémoire
-- **Formats de sortie multiples** — knowledge graph JSON, wiki Markdown, Obsidian Vault, cartes de contexte IA, serveur MCP
+- **Formats de sortie multiples** — knowledge graph JSON, wiki Markdown, Obsidian Vault, cartes de contexte IA, serveur MCP, HTML interactif
+- **Exploration visuelle** — `beacon.html` (arbre repliable D3) et `callflow.html` (diagrammes d'architecture Mermaid par communauté) régénérés à chaque scan
 - **Détection de communautés** — clustering Leiden/Louvain révèle les vraies frontières architecturales
-- **Cache incrémental** — basé sur SHA-256 ; ré-extrait uniquement les fichiers modifiés depuis le dernier scan
+- **Cache incrémental** — SHA-256 + chemin rapide mtime/size ; les modifications de mtime sans changement de contenu (Obsidian/iCloud/Nextcloud) ne déclenchent jamais une ré-extraction inutile
+- **Promotion de confiance** — les arêtes `calls` inter-fichiers passent de INFERRED à EXTRACTED automatiquement quand un import explicite prouve le binding
+- **Écritures sûres** — beacon.json a un shrink guard (une exécution partielle ne peut jamais écraser un graphe complet) et estampille `built_at_commit` afin que REPORT.md signale les sorties stale par rapport au HEAD courant
+- **Multi-développeur** — `codebeacon hook install` enregistre un git merge driver pour `beacon.json` et un hook post-commit de rebuild incrémental, de sorte que deux devs scannant la même branche ne produisent jamais de conflits de merge sur le graphe
+- **Sortie durcie** — les frontmatter YAML et les labels MCP sont sanitisés : U+2028/U+2029, contrôles C0 et marques bidi sont supprimés avant d'atteindre Obsidian, Cursor ou l'agent
+- **`.codebeaconignore` style gitignore** — last-match-wins avec négation `!`, patterns de répertoire (`build/`), patterns ancrés (`/secrets.txt`), règles sur espaces de fin
 - **Zéro configuration** — détecte automatiquement les frameworks et langages ; génère `codebeacon.yaml` pour les exécutions suivantes
 - **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
 
@@ -115,8 +121,10 @@ project-root/
   .cursorrules           ← contexte Cursor IDE (même stratégie de fusion)
   AGENTS.md              ← contexte OpenAI Agents / Codex (même stratégie de fusion)
   .codebeacon/
-    beacon.json          ← knowledge graph complet (JSON node-link, interrogeable)
-    REPORT.md            ← nœuds dieu, connexions surprenantes, fichiers hub
+    beacon.json          ← knowledge graph complet ; embarque `meta.built_at_commit`
+    beacon.html          ← visualiseur d'arbre repliable D3 (ouvrir dans un navigateur)
+    callflow.html        ← diagrammes Mermaid de call-flow groupés par communauté
+    REPORT.md            ← nœuds dieu, connexions surprenantes, fichiers hub, fraîcheur
     wiki/
       index.md
       overview.md
@@ -158,6 +166,50 @@ workspace/
     .codebeacon/
 ```
 
+## Exploration visuelle
+
+Chaque scan écrit deux fichiers HTML autonomes à côté de `beacon.json` :
+
+```
+.codebeacon/beacon.html      # arbre repliable D3 v7 — ouvrir dans n'importe quel navigateur
+.codebeacon/callflow.html    # diagrammes d'architecture Mermaid, un par communauté
+```
+
+Pas de build, pas de serveur statique, pas de copier-coller. Ouvre le fichier, clique pour déplier projets → types → nœuds ; survole pour voir le chemin source et le degré. `callflow.html` groupe le graphe par communauté et rend chacune en flowchart Mermaid, avec les arêtes sortantes inter-communautés dans un tableau pliable.
+
+---
+
+## Workflow multi-développeur
+
+Deux devs exécutant `codebeacon scan` sur la même branche produisent des `beacon.json` légèrement différents — point chaud historique de conflits de merge. `codebeacon hook install` règle ça :
+
+```bash
+codebeacon hook install            # à la racine du repo
+```
+
+Cela enregistre :
+
+- un **git merge driver** qui union-merge deux `beacon.json` en un seul (nœuds dédupliqués par ID, arêtes par `(source, target, relation)`),
+- une entrée `.gitattributes` pointant `*beacon.json` vers le driver,
+- un **hook post-commit** qui lance `codebeacon scan . --update` en arrière-plan pour que le graphe ne soit jamais en retard sur les commits. Sortie dans `~/.cache/codebeacon-rebuild.log`.
+
+Le merge driver sort toujours en 0 — la régénération du graphe ne bloque jamais un vrai merge.
+
+---
+
+## Garanties de sécurité
+
+Quelques invariants que le writer applique à chaque scan réussi :
+
+| Guard | Ce qu'il empêche |
+|---|---|
+| **Shrink guard** | Une extraction partielle ratée ou une exécution interrompue ne peut jamais écraser un `beacon.json` complet plus grand. Bypass via `force=True` depuis l'API. |
+| **Écriture atomique** | `beacon.json` est écrit via `os.replace`, donc le fichier est soit complet soit intact — jamais à moitié écrit. |
+| **Estampille `built_at_commit`** | `beacon.json` embarque `meta.built_at_commit` (SHA complet) et `REPORT.md` affiche le SHA court. Si HEAD a avancé, le rapport marque le graphe comme `⚠ stale` avec un hint d'une ligne. |
+| **Durcissement frontmatter / labels** | Les valeurs YAML sont en single-quoted et échappent U+2028, U+2029, tabulation et contrôles C0 ; la sortie MCP passe chaque label par le même sanitizer. Un identifiant malveillant dans le code source ne peut pas casser le parser YAML d'Obsidian ni injecter de séquences de contrôle dans le contexte d'un agent LLM. |
+
+---
+
 ## Configuration
 
 Exécutez `codebeacon init` pour générer `codebeacon.yaml`, ou créez-le manuellement :
@@ -194,16 +246,29 @@ deep_dive: false               # mettre à true pour une sortie par projet
 
 ### .codebeaconignore
 
-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.
+Placez un fichier `.codebeaconignore` à la racine du projet pour exclure des répertoires ou fichiers du scan. Sémantique conforme à `.gitignore` — last-match-wins avec négation `!`, motifs ancrés (`/foo`), motifs uniquement répertoire (`build/`), commentaires :
 
 ```
 # .codebeaconignore
-generated/
+
+# répertoires
 build/
-*.generated.ts
+generated/
 fixtures/
+
+# ancré à la racine uniquement
+/scripts/local-only.ts
+
+# motifs glob
+*.gen.ts
+**/snapshots/**
+
+# ré-inclure un fichier même si build/ est ignoré
+!build/manifest.ts
 ```
 
+`!pattern` ré-inclut un chemin précédemment ignoré ; les règles ultérieures écrasent les précédentes. Le walker élague les répertoires dont le nom matche, mais reporte l'élagage quand une règle de négation pourrait ré-inclure un fichier imbriqué.
+
 ---
 
 ## Intégration IA
@@ -299,8 +364,12 @@ codebeacon scan /workspace --deep-dive    # sortie par projet + workspace combin
 codebeacon init [chemin]                  # générer codebeacon.yaml
 codebeacon sync                           # exécuter depuis codebeacon.yaml
 
-codebeacon query <terme>                  # rechercher dans le graphe (bientôt)
-codebeacon path <source> <cible>          # chemin le plus court entre deux nœuds
+codebeacon query <terme> [--dir .codebeacon] [--limit N]   # rechercher des nœuds par sous-chaîne de label
+codebeacon path <source> <cible> [--dir .codebeacon]       # chemin de dépendances le plus court
+
+# Support multi-développeur (git plumbing)
+codebeacon hook install [path]            # installer merge driver + hook post-commit incrémental
+codebeacon merge-driver <base> <cur> <other>  # invoqué par git après `hook install` ; union-merge de beacon.json
 
 codebeacon serve [--dir .codebeacon]      # serveur MCP (stdio)
 codebeacon install                        # installer le skill Claude Code