codeatlas-viz 0.2.2__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/PKG-INFO +68 -15
  2. codeatlas_viz-0.3.0/README.md +169 -0
  3. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/pyproject.toml +2 -1
  4. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/__init__.py +1 -1
  5. codeatlas_viz-0.3.0/src/codeatlas/__main__.py +6 -0
  6. codeatlas_viz-0.3.0/src/codeatlas/analysis.py +592 -0
  7. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/analyzers/__init__.py +11 -3
  8. codeatlas_viz-0.3.0/src/codeatlas/analyzers/python_analyzer.py +129 -0
  9. codeatlas_viz-0.3.0/src/codeatlas/analyzers/treesitter_analyzer.py +264 -0
  10. codeatlas_viz-0.3.0/src/codeatlas/cli.py +213 -0
  11. codeatlas_viz-0.3.0/src/codeatlas/mcp_server.py +355 -0
  12. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/models.py +2 -0
  13. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/scanner.py +24 -12
  14. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/server.py +51 -0
  15. codeatlas_viz-0.3.0/src/codeatlas/web/assets/index-Cel4E6fz.js +6 -0
  16. codeatlas_viz-0.3.0/src/codeatlas/web/assets/index-DjvLaD13.css +1 -0
  17. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/web/index.html +2 -2
  18. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas_viz.egg-info/PKG-INFO +68 -15
  19. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas_viz.egg-info/SOURCES.txt +7 -2
  20. codeatlas_viz-0.3.0/src/codeatlas_viz.egg-info/requires.txt +7 -0
  21. codeatlas_viz-0.3.0/tests/test_analysis_and_mcp.py +268 -0
  22. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/tests/test_scanner_and_server.py +20 -0
  23. codeatlas_viz-0.2.2/README.md +0 -119
  24. codeatlas_viz-0.2.2/src/codeatlas/analyzers/python_analyzer.py +0 -130
  25. codeatlas_viz-0.2.2/src/codeatlas/cli.py +0 -134
  26. codeatlas_viz-0.2.2/src/codeatlas/web/assets/index-WkvacVWK.js +0 -4
  27. codeatlas_viz-0.2.2/src/codeatlas/web/assets/index-vVc60hrc.css +0 -1
  28. codeatlas_viz-0.2.2/src/codeatlas_viz.egg-info/requires.txt +0 -3
  29. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/LICENSE +0 -0
  30. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/setup.cfg +0 -0
  31. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/analyzers/base.py +0 -0
  32. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/analyzers/c_family_analyzer.py +0 -0
  33. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas/analyzers/js_analyzer.py +0 -0
  34. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas_viz.egg-info/dependency_links.txt +0 -0
  35. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas_viz.egg-info/entry_points.txt +0 -0
  36. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/src/codeatlas_viz.egg-info/top_level.txt +0 -0
  37. {codeatlas_viz-0.2.2 → codeatlas_viz-0.3.0}/tests/test_analyzers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codeatlas-viz
3
- Version: 0.2.2
3
+ Version: 0.3.0
4
4
  Summary: Zero-config local codebase architecture & call-graph visualizer with an interactive Svelte UI.
5
5
  Author: kutyfuty
6
6
  License: MIT
@@ -23,6 +23,9 @@ Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
24
  Provides-Extra: dev
25
25
  Requires-Dist: pytest>=8.0; extra == "dev"
26
+ Provides-Extra: treesitter
27
+ Requires-Dist: tree-sitter>=0.23; extra == "treesitter"
28
+ Requires-Dist: tree-sitter-language-pack>=0.4; extra == "treesitter"
26
29
  Dynamic: license-file
27
30
 
28
31
  # CodeAtlas
@@ -46,22 +49,24 @@ Inspect functions, classes, call-graph hubs, unreferenced ("dead") code, circula
46
49
 
47
50
  ## Key Features
48
51
 
49
- - **Zero Runtime Dependencies:** Pure Python standard-library CLI (`pip` / `pipx` ready).
52
+ - **Zero Runtime Dependencies:** Pure Python standard-library CLI (`pip` / `pipx` ready), with optional `codeatlas-viz[treesitter]` extra for Tree-sitter AST parsing.
50
53
  - **Multi-Language Analysis (9 Languages):**
51
- - **Python:** Full `ast` parsing for classes, methods, nested functions, docstrings, relative imports, and import aliases.
52
- - **JavaScript / TypeScript / Svelte:** Structural analysis of functions, arrow functions, ES6 classes, methods, getters/setters, class arrow properties, and `<script>` blocks.
53
- - **Go / Rust / Java / C / C++:** Structural parsing of structs, traits/impl blocks, receiver methods, classes, and member call sites.
54
- - **Architectural Health Score & Standalone HTML Report:**
55
- - Computes a `0–100` repository health score based on circular dependency and dead-code ratios.
56
- - Export self-contained single-file `.html` architecture reports (`codeatlas export . --format html -o report.html`).
54
+ - **Python:** Full iterative `ast` parsing for classes, methods, nested functions, docstrings, relative imports, and import aliases.
55
+ - **JavaScript / TypeScript / Svelte:** Structural analysis (or optional Tree-sitter AST) of functions, arrow functions, ES6 classes, methods, getters/setters, class arrow properties, and `<script>` blocks.
56
+ - **Go / Rust / Java / C / C++:** Structural parsing (or optional Tree-sitter AST) of structs, traits/impl blocks, receiver methods, classes, and member call sites.
57
+ - **Change Impact / Blast Radius (`codeatlas impact`):**
58
+ - Reads local `git diff` (or explicit `--file` / `--symbol` / `--diff REF`) and traces every upstream caller, affected entrypoint, and test reaching changed code.
59
+ - **CI Architecture Gate (`codeatlas check`):**
60
+ - Enforces `--max-cycles`, `--min-health`, `--max-dead-ratio`, and module boundary rules (`--rule ui/*:db/*` or `.codeatlas.toml`) in CI pipelines.
61
+ - **Built-in Stdio MCP Server (`codeatlas mcp`):**
62
+ - Zero-dependency Model Context Protocol server exposing call-graph, shortest-path, dead-code, and blast-radius tools to Claude Code, Cursor, or Windsurf.
63
+ - **Architectural Health Score & Standalone Exports (`export`):**
64
+ - Computes a `0–100` repository health score and exports standalone `.html`, GitHub-flavored `.md`, `.mmd` (Mermaid), and `.json`.
57
65
  - **Interactive Svelte 5 Web UI (`codeatlas serve`):**
58
- - Switch between **Symbol-Level** and **File-Level** dependency graphs.
59
- - **Hubs, Circular Dependencies (`Cycles`), and Unreferenced (`Dead`)** tabs.
66
+ - Switch between **Symbol**, **File**, and **Folder Cluster** views with interactive folder drill-down and spatial grid force layout.
67
+ - **Hubs, Circular Dependencies (`Cycles`), Unreferenced (`Dead`), and Blast Radius (`Impact`)** tabs.
60
68
  - **Shortest Call-Path Finder (BFS):** Highlight the exact call chain (`A → ... → B`) between any two symbols.
61
- - **Focus 1-Hop Mode:** Isolate callers and callees of the selected symbol.
62
- - **Live Source Preview:** Inspect exact source lines directly in the side panel.
63
- - **One-Click Exports:** Download `.svg` or `.mmd` (Mermaid) diagrams directly from the toolbar.
64
- - **Fast & Scalable:** Iterative Tarjan strongly-connected-components (SCC) cycle detection, precompiled `.gitignore` matching, and automatic minified bundle filtering.
69
+ - **Focus 1-Hop Mode, Live Source Preview, and `.svg`/`.mmd` downloads.**
65
70
 
66
71
  ---
67
72
 
@@ -83,9 +88,12 @@ flowchart LR
83
88
  ## Installation
84
89
 
85
90
  ```bash
86
- # Run directly with pipx / uvx (once published to PyPI)
91
+ # Run directly with pipx / uvx
87
92
  pipx install codeatlas-viz
88
93
 
94
+ # Optional: install Tree-sitter AST backend for non-Python languages
95
+ pip install "codeatlas-viz[treesitter]"
96
+
89
97
  # Or install from source
90
98
  git clone https://github.com/kutyfuty/codeatlas.git
91
99
  cd codeatlas
@@ -126,6 +134,51 @@ codeatlas export . --format mermaid -o architecture.mmd
126
134
  codeatlas export . --format json -o graph.json
127
135
  ```
128
136
 
137
+ ### 4. Change Blast Radius (`impact`)
138
+
139
+ ```bash
140
+ # Trace upstream callers, entrypoints & tests affected by git working-tree diff
141
+ codeatlas impact .
142
+
143
+ # Or check a specific git diff / file / symbol as Markdown (ideal for PR comments)
144
+ codeatlas impact . --diff HEAD~1 --format markdown
145
+ codeatlas impact . --symbol scan_directory
146
+ ```
147
+
148
+ ### 5. CI Architecture Gate (`check`)
149
+
150
+ ```bash
151
+ codeatlas check . --max-cycles 0 --min-health 80 --rule "src/ui/*:src/db/*"
152
+ ```
153
+
154
+ Or define persistent rules in `.codeatlas.toml`:
155
+
156
+ ```toml
157
+ [check]
158
+ max_cycles = 0
159
+ min_health = 80
160
+
161
+ [[rules]]
162
+ name = "UI must go through service layer"
163
+ from = "src/ui/*"
164
+ forbid = "src/db/*"
165
+ ```
166
+
167
+ ### 6. Built-in MCP Server (`mcp`)
168
+
169
+ Add CodeAtlas to Claude Code / Cursor / Windsurf via zero-dependency stdio JSON-RPC:
170
+
171
+ ```json
172
+ {
173
+ "mcpServers": {
174
+ "codeatlas": {
175
+ "command": "codeatlas",
176
+ "args": ["mcp", "/path/to/repo"]
177
+ }
178
+ }
179
+ }
180
+ ```
181
+
129
182
  ---
130
183
 
131
184
  ## Development & Testing
@@ -0,0 +1,169 @@
1
+ # CodeAtlas
2
+
3
+ **Zero-config local codebase architecture & call-graph visualizer.**
4
+
5
+ Inspect functions, classes, call-graph hubs, unreferenced ("dead") code, circular dependencies, and shortest call paths in your terminal or browser—with zero cloud uploads, zero configuration files, and zero runtime dependencies for the CLI.
6
+
7
+ ![CodeAtlas interactive Svelte call-graph demo](docs/demo.gif)
8
+
9
+ <details>
10
+ <summary>More screenshots (Overview, Focus 1-hop, File-level Graph)</summary>
11
+
12
+ | Symbol Graph & Path Finder | Focus 1-Hop Isolation | File Dependency Map |
13
+ |---|---|---|
14
+ | ![CodeAtlas Symbol Graph](docs/demo-ui.png) | ![CodeAtlas Focus 1-Hop](docs/demo-focus.png) | ![CodeAtlas File Graph](docs/demo-files.png) |
15
+
16
+ </details>
17
+
18
+ ---
19
+
20
+ ## Key Features
21
+
22
+ - **Zero Runtime Dependencies:** Pure Python standard-library CLI (`pip` / `pipx` ready), with optional `codeatlas-viz[treesitter]` extra for Tree-sitter AST parsing.
23
+ - **Multi-Language Analysis (9 Languages):**
24
+ - **Python:** Full iterative `ast` parsing for classes, methods, nested functions, docstrings, relative imports, and import aliases.
25
+ - **JavaScript / TypeScript / Svelte:** Structural analysis (or optional Tree-sitter AST) of functions, arrow functions, ES6 classes, methods, getters/setters, class arrow properties, and `<script>` blocks.
26
+ - **Go / Rust / Java / C / C++:** Structural parsing (or optional Tree-sitter AST) of structs, traits/impl blocks, receiver methods, classes, and member call sites.
27
+ - **Change Impact / Blast Radius (`codeatlas impact`):**
28
+ - Reads local `git diff` (or explicit `--file` / `--symbol` / `--diff REF`) and traces every upstream caller, affected entrypoint, and test reaching changed code.
29
+ - **CI Architecture Gate (`codeatlas check`):**
30
+ - Enforces `--max-cycles`, `--min-health`, `--max-dead-ratio`, and module boundary rules (`--rule ui/*:db/*` or `.codeatlas.toml`) in CI pipelines.
31
+ - **Built-in Stdio MCP Server (`codeatlas mcp`):**
32
+ - Zero-dependency Model Context Protocol server exposing call-graph, shortest-path, dead-code, and blast-radius tools to Claude Code, Cursor, or Windsurf.
33
+ - **Architectural Health Score & Standalone Exports (`export`):**
34
+ - Computes a `0–100` repository health score and exports standalone `.html`, GitHub-flavored `.md`, `.mmd` (Mermaid), and `.json`.
35
+ - **Interactive Svelte 5 Web UI (`codeatlas serve`):**
36
+ - Switch between **Symbol**, **File**, and **Folder Cluster** views with interactive folder drill-down and spatial grid force layout.
37
+ - **Hubs, Circular Dependencies (`Cycles`), Unreferenced (`Dead`), and Blast Radius (`Impact`)** tabs.
38
+ - **Shortest Call-Path Finder (BFS):** Highlight the exact call chain (`A → ... → B`) between any two symbols.
39
+ - **Focus 1-Hop Mode, Live Source Preview, and `.svg`/`.mmd` downloads.**
40
+
41
+ ---
42
+
43
+ ## Architecture Overview
44
+
45
+ ```mermaid
46
+ flowchart LR
47
+ CLI["cli.py (main)"] --> Scanner["scanner.py (scan_directory)"]
48
+ CLI --> Server["server.py (serve_graph)"]
49
+ Scanner --> AnalyzerRegistry["analyzers/__init__.py (analyze_file)"]
50
+ AnalyzerRegistry --> PyAnalyzer["python_analyzer.py (analyze_python)"]
51
+ AnalyzerRegistry --> JsAnalyzer["js_analyzer.py (analyze_js)"]
52
+ Scanner --> GraphModel["models.py (CodeGraph)"]
53
+ Server --> WebUI["Svelte 5 Web UI (/api/graph & /api/file)"]
54
+ ```
55
+
56
+ ---
57
+
58
+ ## Installation
59
+
60
+ ```bash
61
+ # Run directly with pipx / uvx
62
+ pipx install codeatlas-viz
63
+
64
+ # Optional: install Tree-sitter AST backend for non-Python languages
65
+ pip install "codeatlas-viz[treesitter]"
66
+
67
+ # Or install from source
68
+ git clone https://github.com/kutyfuty/codeatlas.git
69
+ cd codeatlas
70
+ pip install -e .
71
+ ```
72
+
73
+ ## Usage
74
+
75
+ ### 1. Terminal Summary (`scan`)
76
+
77
+ ```bash
78
+ codeatlas .
79
+ # or explicitly:
80
+ codeatlas scan /path/to/repo
81
+ ```
82
+
83
+ ### 2. Interactive Web UI (`serve`)
84
+
85
+ ```bash
86
+ codeatlas serve .
87
+ # Custom port / without auto-opening browser:
88
+ codeatlas serve /path/to/repo --port 4173 --no-open
89
+ ```
90
+
91
+ ### 3. Export Graph (`export`)
92
+
93
+ ```bash
94
+ # Export as self-contained single-file HTML report
95
+ codeatlas export . --format html -o report.html
96
+
97
+ # Export as GitHub-flavored Markdown summary (great for PR comments / CI)
98
+ codeatlas export . --format markdown -o SUMMARY.md
99
+
100
+ # Export as Mermaid flowchart
101
+ codeatlas export . --format mermaid -o architecture.mmd
102
+
103
+ # Export full graph analytics as JSON
104
+ codeatlas export . --format json -o graph.json
105
+ ```
106
+
107
+ ### 4. Change Blast Radius (`impact`)
108
+
109
+ ```bash
110
+ # Trace upstream callers, entrypoints & tests affected by git working-tree diff
111
+ codeatlas impact .
112
+
113
+ # Or check a specific git diff / file / symbol as Markdown (ideal for PR comments)
114
+ codeatlas impact . --diff HEAD~1 --format markdown
115
+ codeatlas impact . --symbol scan_directory
116
+ ```
117
+
118
+ ### 5. CI Architecture Gate (`check`)
119
+
120
+ ```bash
121
+ codeatlas check . --max-cycles 0 --min-health 80 --rule "src/ui/*:src/db/*"
122
+ ```
123
+
124
+ Or define persistent rules in `.codeatlas.toml`:
125
+
126
+ ```toml
127
+ [check]
128
+ max_cycles = 0
129
+ min_health = 80
130
+
131
+ [[rules]]
132
+ name = "UI must go through service layer"
133
+ from = "src/ui/*"
134
+ forbid = "src/db/*"
135
+ ```
136
+
137
+ ### 6. Built-in MCP Server (`mcp`)
138
+
139
+ Add CodeAtlas to Claude Code / Cursor / Windsurf via zero-dependency stdio JSON-RPC:
140
+
141
+ ```json
142
+ {
143
+ "mcpServers": {
144
+ "codeatlas": {
145
+ "command": "codeatlas",
146
+ "args": ["mcp", "/path/to/repo"]
147
+ }
148
+ }
149
+ }
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Development & Testing
155
+
156
+ ```bash
157
+ # Backend tests
158
+ pip install -e ".[dev]"
159
+ pytest -v
160
+
161
+ # Rebuild Svelte static bundle (outputs to src/codeatlas/web/)
162
+ cd frontend
163
+ npm install
164
+ npm run build
165
+ ```
166
+
167
+ ## License
168
+
169
+ [MIT](LICENSE)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "codeatlas-viz"
7
- version = "0.2.2"
7
+ version = "0.3.0"
8
8
  description = "Zero-config local codebase architecture & call-graph visualizer with an interactive Svelte UI."
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
@@ -34,6 +34,7 @@ Issues = "https://github.com/kutyfuty/codeatlas/issues"
34
34
 
35
35
  [project.optional-dependencies]
36
36
  dev = ["pytest>=8.0"]
37
+ treesitter = ["tree-sitter>=0.23", "tree-sitter-language-pack>=0.4"]
37
38
 
38
39
  [project.scripts]
39
40
  codeatlas = "codeatlas.cli:main"
@@ -3,7 +3,7 @@
3
3
  from .models import CallEdge, CodeGraph, FileSummary, SymbolNode
4
4
  from .scanner import scan_directory
5
5
 
6
- __version__ = "0.2.2"
6
+ __version__ = "0.3.0"
7
7
 
8
8
  __all__ = [
9
9
  "__version__",
@@ -0,0 +1,6 @@
1
+ """Enable running CodeAtlas via `python -m codeatlas`."""
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())