codebeacon 0.1.2__tar.gz → 0.1.4__tar.gz

codebeacon-0.1.4/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Wandererer

codebeacon-0.1.4/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

{codebeacon-0.1.2 → codebeacon-0.1.4}/.github/workflows/ci.yml

@@ -16,9 +16,9 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"

codebeacon-0.1.4/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/codebeacon/
+    permissions:
+      id-token: write  # Trusted Publishing (OIDC) — 비밀번호 불필요
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{codebeacon-0.1.2 → codebeacon-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -42,14 +42,14 @@ Requires-Dist: pytest>=7.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.md"><img src="https://img.shields.io/badge/lang-English-blue" alt="English"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.ko.md"><img src="https://img.shields.io/badge/lang-한국어-red" alt="Korean"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.ja.md"><img src="https://img.shields.io/badge/lang-日本語-green" alt="Japanese"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.zh-CN.md"><img src="https://img.shields.io/badge/lang-简体中文-orange" alt="Chinese"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.es.md"><img src="https://img.shields.io/badge/lang-Español-yellow" alt="Spanish"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.fr.md"><img src="https://img.shields.io/badge/lang-Français-blueviolet" alt="French"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.de.md"><img src="https://img.shields.io/badge/lang-Deutsch-lightgrey" alt="German"></a>
-  <a href="https://github.com/codebeacon/codebeacon/blob/main/README.pt-BR.md"><img src="https://img.shields.io/badge/lang-Português_(BR)-brightgreen" alt="Portuguese (Brazil)"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.md"><img src="https://img.shields.io/badge/lang-English-blue" alt="English"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.ko.md"><img src="https://img.shields.io/badge/lang-한국어-red" alt="Korean"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.ja.md"><img src="https://img.shields.io/badge/lang-日本語-green" alt="Japanese"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.zh-CN.md"><img src="https://img.shields.io/badge/lang-简体中文-orange" alt="Chinese"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.es.md"><img src="https://img.shields.io/badge/lang-Español-yellow" alt="Spanish"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.fr.md"><img src="https://img.shields.io/badge/lang-Français-blueviolet" alt="French"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.de.md"><img src="https://img.shields.io/badge/lang-Deutsch-lightgrey" alt="German"></a>
+  <a href="https://github.com/Wandererer/codebeacon/blob/main/README.pt-BR.md"><img src="https://img.shields.io/badge/lang-Português_(BR)-brightgreen" alt="Portuguese (Brazil)"></a>
 </p>
 
 <h1 align="center">codebeacon</h1>
@@ -62,8 +62,8 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/codebeacon/"><img src="https://img.shields.io/pypi/v/codebeacon" alt="PyPI"></a>
   <a href="https://pypi.org/project/codebeacon/"><img src="https://img.shields.io/pypi/pyversions/codebeacon" alt="Python"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
-  <a href="https://github.com/codebeacon/codebeacon/stargazers"><img src="https://img.shields.io/github/stars/codebeacon/codebeacon" alt="GitHub Stars"></a>
-  <a href="https://github.com/codebeacon/codebeacon/commits/main"><img src="https://img.shields.io/github/last-commit/codebeacon/codebeacon" alt="Last Commit"></a>
+  <a href="https://github.com/Wandererer/codebeacon/stargazers"><img src="https://img.shields.io/github/stars/Wandererer/codebeacon" alt="GitHub Stars"></a>
+  <a href="https://github.com/Wandererer/codebeacon/commits/main"><img src="https://img.shields.io/github/last-commit/Wandererer/codebeacon" alt="Last Commit"></a>
 </p>
 
 ---
@@ -81,14 +81,15 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 ## Key Features
 
 - **Unified pipeline** — route/controller analysis + knowledge graph in one tool, no manual stitching
-- **17 frameworks, 9 languages** — Spring Boot, NestJS, Django, FastAPI, Rails, Express, React, Vue, Angular, Svelte, Gin, Laravel, Actix-Web, ASP.NET Core, Vapor, Ktor, and more
-- **Tree-sitter based** — structural AST parsing, not regex; all 17 language grammars included out of the box
+- **24 frameworks, 9 languages** — Spring Boot, NestJS, Django, FastAPI, Flask, Rails, Express, Fastify, Koa, React, Next.js, Vue, Nuxt, Angular, SvelteKit, Gin, Echo, Fiber, Laravel, Actix-Web, Axum, ASP.NET Core, Vapor, Ktor
+- **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
 - **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
 - **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
 
 ---
 
@@ -117,11 +118,11 @@ codebeacon sync                      # subsequent runs via config
 |----------|-----------|
 | Java / Kotlin | Spring Boot, Ktor |
 | Python | Django, FastAPI, Flask |
-| JavaScript / TypeScript | Express, NestJS, React, Vue, Angular, Svelte |
-| Go | Gin |
+| JavaScript / TypeScript | Express, Fastify, Koa, NestJS, React, Next.js, Vue, Nuxt, Angular, SvelteKit |
+| Go | Gin, Echo, Fiber |
 | Ruby | Rails |
 | PHP | Laravel |
-| Rust | Actix-Web |
+| Rust | Actix-Web, Axum |
 | C# | ASP.NET Core |
 | Swift | Vapor |
 
@@ -150,37 +151,147 @@ codebeacon runs a two-pass extraction pipeline:
 
 ## Output Structure
 
-After a scan, everything lands in `.codebeacon/`:
+After a scan, context map files are updated at the project root (existing user content is preserved) and the knowledge graph lands in `.codebeacon/`:
 
 ```
-.codebeacon/
-  beacon.json          ← full knowledge graph (node-link JSON, queryable)
-  REPORT.md            ← god nodes, surprising connections, hub files
-  CLAUDE.md            ← AI context map (also written to project root)
-  .cursorrules         ← Cursor IDE context
-  AGENTS.md            ← OpenAI Agents / Codex context
-  wiki/
-    index.md           ← global index (~200 tokens)
-    overview.md        ← platform stats + cross-project connections
-    routes.md          ← all routes table
-    cross-project/
-      connections.md   ← cross-service edges
-    <project>/
-      index.md
-      routes.md
-      controllers/<Name>.md
-      services/<Name>.md
-      entities/<Name>.md
-      components/<Name>.md
-  obsidian/            ← Obsidian vault (one note per graph node)
+project-root/
+  CLAUDE.md              ← AI context map (codebeacon block merged; user content kept)
+  .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
+    wiki/
+      index.md           ← global index (~200 tokens)
+      overview.md        ← platform stats + cross-project connections
+      routes.md          ← all routes table
+      cross-project/
+        connections.md   ← cross-service edges
+      <project>/
+        index.md
+        routes.md
+        controllers/<Name>.md
+        services/<Name>.md
+        entities/<Name>.md
+        components/<Name>.md
+    obsidian/            ← Obsidian vault (one note per graph node)
 ```
 
+### Deep Dive Mode
+
+With `--deep-dive`, each sub-project also gets its own `.codebeacon/` directory and `CLAUDE.md`, so AI sessions opened inside a sub-project have full project-specific context:
+
+```
+workspace/
+  CLAUDE.md                   ← combined (all projects)
+  .cursorrules
+  AGENTS.md
+  codebeacon.yaml             ← deep_dive: true
+  .codebeacon/                ← combined knowledge graph
+    beacon.json
+    wiki/
+    obsidian/
+  api-server/
+    CLAUDE.md                 ← api-server only
+    .codebeacon/              ← api-server graph
+      beacon.json
+      wiki/
+      obsidian/
+  frontend/
+    CLAUDE.md                 ← frontend only
+    .codebeacon/              ← frontend graph
+      beacon.json
+      wiki/
+      obsidian/
+```
+
+Claude Code loads `CLAUDE.md` hierarchically, so opening a session in `api-server/` loads both the parent workspace overview **and** the project-specific details.
+
+To update from any sub-project directory after the initial scan:
+
+```bash
+# Initial deep-dive scan
+codebeacon scan /workspace --deep-dive
+
+# Later, from any sub-project — finds the parent config and updates ALL projects
+cd /workspace/api-server
+codebeacon scan . --update
+```
+
+---
+
+## AI Integration
+
+### Claude Code Skill (`/codebeacon`)
+
+Install codebeacon as a Claude Code slash command:
+
+```bash
+pip install codebeacon
+codebeacon install
+```
+
+This copies `SKILL.md` to `~/.claude/skills/codebeacon/` and registers the `/codebeacon` trigger in `~/.claude/CLAUDE.md`. Restart your Claude Code session, then type `/codebeacon` to scan the current directory.
+
+```
+/codebeacon                  # scan current directory
+/codebeacon /path/to/project # scan a specific path
+/codebeacon sync             # re-scan from codebeacon.yaml
+```
+
+### MCP Server
+
+Run codebeacon as a persistent MCP server so any MCP-compatible client can query your knowledge graph directly.
+
+**Step 1 — scan your project:**
+```bash
+codebeacon scan .
+```
+
+**Step 2 — add to your MCP client config:**
+
+**Claude Code** (`.claude.json` in project root or `~/.claude.json` globally):
+```json
+{
+  "mcpServers": {
+    "codebeacon": {
+      "command": "codebeacon",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "codebeacon": {
+      "command": "codebeacon",
+      "args": ["serve", "--dir", "/path/to/.codebeacon"]
+    }
+  }
+}
+```
+
+**Available MCP tools** once connected:
+
+| Tool | Description |
+|------|-------------|
+| `beacon_wiki_index` | Global project overview (routes, services, entities count) |
+| `beacon_wiki_article` | Read a specific wiki article by path |
+| `beacon_query` | Search nodes by label substring |
+| `beacon_path` | Shortest dependency path between two nodes |
+| `beacon_blast_radius` | Upstream callers + downstream affected nodes |
+| `beacon_routes` | List all HTTP routes, filterable by project |
+| `beacon_services` | List all services/classes, filterable by project |
+
 ---
 
 ## Installation Options
 
 ```bash
-pip install codebeacon              # all 17 language grammars included
+pip install codebeacon              # all language grammars included
 pip install codebeacon[cluster]     # + Leiden community detection (graspologic)
 pip install --upgrade codebeacon    # upgrade to latest version with all dependencies
 ```
@@ -197,10 +308,11 @@ 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 . --wiki-only             # regenerate wiki without re-extracting
+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
 codebeacon scan . --list-only             # detect frameworks only, don't extract
+codebeacon scan /workspace --deep-dive    # per-project + combined workspace outputs
 
 # Config-driven mode
 codebeacon init [path]                    # auto-generate codebeacon.yaml
@@ -238,7 +350,6 @@ output:
   dir: .codebeacon
   wiki: true
   obsidian: true
-  graph_html: true
   context_map:
     targets: [CLAUDE.md, .cursorrules, AGENTS.md]
 
@@ -249,6 +360,20 @@ wave:
 
 semantic:
   enabled: false               # override with --semantic flag
+
+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.
+
+```
+# .codebeaconignore
+generated/
+build/
+*.generated.ts
+fixtures/
 ```
 
 ---
@@ -287,14 +412,16 @@ All processing is local. Your source code never leaves your machine.
 
 - Tree-sitter AST parsing runs entirely in-process
 - No telemetry, no analytics, no network calls during normal operation
-- The `--semantic` flag (disabled by default) sends code excerpts to your configured LLM API — only enable it explicitly
+- The `--semantic` flag (disabled by default) activates two extraction modes:
+  1. **Structured comment parsing** (no LLM required) — infers cross-references from Javadoc (`@see`, `{@link}`), Python docstrings (`:class:`, `:func:`), and JSDoc (`@see`, `@param` types)
+  2. **LLM inference** (optional) — when `ANTHROPIC_API_KEY` is set, sends code excerpts to the Claude API for deeper relationship inference; only enable it explicitly
 
 ---
 
 ## Contributing
 
 ```bash
-git clone https://github.com/codebeacon/codebeacon
+git clone https://github.com/Wandererer/codebeacon
 cd codebeacon
 pip install -e ".[dev,cluster]"
 pytest