Skip to content

Commit ecb67af

Browse files
xnuinsidexnuinside
committed
codegraph version 1..0.0
1 parent 1e541dc commit ecb67af

22 files changed

+3367
-162
lines changed

‎.flake8‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
[flake8]
2-
exclude = .github,.git,__pycache__,docs/source/conf.py,old,build,dist,models.py,omymodels/test.py
3-
ignore = D100, D103, D101, D102, D104,D107, D403, D210, D400, D401, W503, W293, D205
2+
exclude = .github,.git,__pycache__,docs/source/conf.py,old,build,dist,.tox,*.egg-info
3+
ignore = D100, D103, D101, D102, D104, D107, D403, D210, D400, D401, W503, W293, D205
44
max-complexity = 10
55
max-line-length = 120
6+
per-file-ignores =
7+
__init__.py:F401
8+
codegraph/vizualyzer.py:E501

‎.github/workflows/main.yml‎

Lines changed: 37 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,45 +7,61 @@ on:
77
branches: [ main ]
88

99
jobs:
10-
flake8_py3:
10+
lint:
1111
runs-on: ubuntu-latest
1212
steps:
1313
- uses: actions/checkout@v4
1414
- name: Set up Python 3.12
1515
uses: actions/setup-python@v5
1616
with:
17-
python-version: 3.12
18-
- name: Install dependencies
17+
python-version: "3.12"
18+
- name: Install flake8
1919
run: |
2020
python -m pip install --upgrade pip
21-
pip install flake8 pytest
22-
23-
- name: Run flake8 (suo)
24-
uses: julianwachholz/flake8-action@v2
25-
with:
26-
checkName: 'flake8_py3'
27-
env:
28-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
21+
pip install flake8
22+
- name: Run flake8
23+
run: |
24+
flake8 codegraph/ tests/
2925
3026
tests:
3127
runs-on: ubuntu-latest
32-
needs: [flake8_py3]
28+
needs: [lint]
3329
strategy:
30+
fail-fast: false
3431
matrix:
35-
python: [3.12]
32+
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
3633
steps:
3734
- uses: actions/checkout@v4
38-
- name: Set up Python
35+
- name: Set up Python ${{ matrix.python-version }}
3936
uses: actions/setup-python@v5
4037
with:
41-
python-version: ${{ matrix.python }}
38+
python-version: ${{ matrix.python-version }}
4239
- name: Install dependencies
4340
run: |
4441
python -m pip install --upgrade pip
45-
pip install poetry
46-
poetry install
47-
env:
48-
POETRY_VIRTUALENVS_CREATE: false
49-
- name: Test with pytest
42+
pip install pytest matplotlib networkx click
43+
- name: Run tests
44+
run: |
45+
pytest tests/ -v
46+
47+
tox:
48+
runs-on: ubuntu-latest
49+
needs: [lint]
50+
steps:
51+
- uses: actions/checkout@v4
52+
- name: Set up Python versions
53+
uses: actions/setup-python@v5
54+
with:
55+
python-version: |
56+
3.9
57+
3.10
58+
3.11
59+
3.12
60+
3.13
61+
- name: Install tox
62+
run: |
63+
python -m pip install --upgrade pip
64+
pip install tox
65+
- name: Run tox
5066
run: |
51-
pytest tests/ -vv
67+
tox

‎ARCHITECTURE.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# CodeGraph Architecture
2+
3+
This document describes the architecture and design of the CodeGraph tool.
4+
5+
## Overview
6+
7+
CodeGraph is a Python tool that creates dependency graphs from Python source code. It analyzes Python files, extracts function/class definitions and their relationships, and generates interactive visualizations.
8+
9+
## Project Structure
10+
11+
```
12+
codegraph/
13+
├── codegraph/ # Main package
14+
│ ├── __init__.py # Package init, version definition
15+
│ ├── main.py # CLI entry point (click-based)
16+
│ ├── core.py # Core graph building logic
17+
│ ├── parser.py # Python source code parser
18+
│ ├── utils.py # Utility functions
19+
│ └── vizualyzer.py # Visualization (D3.js + matplotlib)
20+
├── tests/ # Test suite
21+
│ ├── test_codegraph.py # Basic tests
22+
│ ├── test_graph_generation.py # Comprehensive graph tests
23+
│ ├── test_utils.py # Utility function tests
24+
│ └── test_data/ # Test fixtures
25+
├── docs/ # Documentation
26+
├── pyproject.toml # Poetry configuration
27+
├── tox.ini # Multi-version testing
28+
└── .github/workflows/ # CI/CD
29+
```
30+
31+
## Core Components
32+
33+
### 1. Parser (`codegraph/parser.py`)
34+
35+
The parser uses Python's `tokenize` module to extract code structure from source files.
36+
37+
**Key Classes:**
38+
- `_Object` - Base class for all parsed objects (lineno, endno, name, parent)
39+
- `Function` - Represents a function definition
40+
- `AsyncFunction` - Represents an async function definition
41+
- `Class` - Represents a class definition with methods
42+
- `Import` - Collects all imports from a module
43+
44+
**Main Function:**
45+
- `create_objects_array(fname, source)` - Parses source code and returns list of objects
46+
47+
**Import Handling:**
48+
- Simple imports: `import os` → `['os']`
49+
- From imports: `from os import path` → `['os.path']`
50+
- Comma-separated: `from pkg import a, b, c` → `['pkg.a', 'pkg.b', 'pkg.c']`
51+
- Aliased imports: `from pkg import mod as m` → `['pkg.mod as m']`
52+
53+
### 2. Core (`codegraph/core.py`)
54+
55+
The core module builds the dependency graph from parsed data.
56+
57+
**Key Classes:**
58+
- `CodeGraph` - Main class that orchestrates graph building
59+
60+
**Key Functions:**
61+
- `get_code_objects(paths_list)` - Parse all files and return dict of module → objects
62+
- `get_imports_and_entities_lines()` - Extract imports and entity line ranges
63+
- `collect_entities_usage_in_modules()` - Find where entities are used
64+
- `search_entity_usage()` - Check if entity is used in a line
65+
66+
**Data Flow:**
67+
```
68+
Python Files → Parser → Code Objects → Import Analysis → Entity Usage → Dependency Graph
69+
```
70+
71+
**Graph Format:**
72+
```python
73+
{
74+
"/path/to/module.py": {
75+
"function_name": ["other_module.func1", "local_func"],
76+
"class_name": ["dependency1"],
77+
}
78+
}
79+
```
80+
81+
### 3. Visualizer (`codegraph/vizualyzer.py`)
82+
83+
Provides two visualization modes: D3.js (default) and matplotlib (legacy).
84+
85+
**D3.js Visualization:**
86+
- `convert_to_d3_format()` - Converts graph to D3.js node/link format
87+
- `get_d3_html_template()` - Returns complete HTML with embedded D3.js
88+
- `draw_graph()` - Saves HTML and opens in browser
89+
90+
**D3.js Features:**
91+
- Force-directed layout for automatic node positioning
92+
- Zoom/pan with mouse wheel and drag
93+
- Node dragging to reposition
94+
- Collapse/expand modules and entities
95+
- Search with autocomplete
96+
- Tooltips and statistics panel
97+
98+
**Matplotlib Visualization:**
99+
- `draw_graph_matplotlib()` - Legacy visualization using networkx
100+
- `process_module_in_graph()` - Process single module into graph
101+
102+
**D3.js Data Format:**
103+
```json
104+
{
105+
"nodes": [
106+
{"id": "module.py", "type": "module", "collapsed": false},
107+
{"id": "module.py:func", "label": "func", "type": "entity", "parent": "module.py"}
108+
],
109+
"links": [
110+
{"source": "module.py", "target": "module.py:func", "type": "module-entity"},
111+
{"source": "module.py:func", "target": "other.py:dep", "type": "dependency"}
112+
]
113+
}
114+
```
115+
116+
### 4. CLI (`codegraph/main.py`)
117+
118+
Click-based command-line interface.
119+
120+
**Options:**
121+
- `paths` - Directory or file paths to analyze
122+
- `--matplotlib` - Use legacy matplotlib visualization
123+
- `--output` - Custom output path for HTML file
124+
125+
### 5. Utilities (`codegraph/utils.py`)
126+
127+
Helper functions for file system operations.
128+
129+
**Key Functions:**
130+
- `get_python_paths_list(path)` - Recursively find all .py files
131+
132+
## Data Flow
133+
134+
```
135+
1. CLI receives path(s)
136+
↓
137+
2. utils.get_python_paths_list() finds all .py files
138+
↓
139+
3. parser.create_objects_array() parses each file
140+
- Extracts functions, classes, methods
141+
- Collects import statements
142+
↓
143+
4. core.CodeGraph.usage_graph() builds dependency graph
144+
- Maps entities to line ranges
145+
- Finds entity usage in code
146+
- Creates dependency edges
147+
↓
148+
5. vizualyzer.draw_graph() creates visualization
149+
- Converts to D3.js format
150+
- Generates HTML with embedded JS
151+
- Opens in browser
152+
```
153+
154+
## Node Types
155+
156+
| Type | Visual | Description |
157+
|------|--------|-------------|
158+
| Module | Green square | Python .py file |
159+
| Entity | Blue circle | Function or class |
160+
| External | Gray circle | Dependency from outside analyzed codebase |
161+
162+
## Link Types
163+
164+
| Type | Visual | Description |
165+
|------|--------|-------------|
166+
| module-entity | Green dashed | Module contains entity |
167+
| module-module | Orange solid | Module imports from module |
168+
| dependency | Red | Entity uses another entity |
169+
170+
## Testing Strategy
171+
172+
- **Unit tests**: Parser, import handling, utility functions
173+
- **Integration tests**: Full graph generation on test data
174+
- **Self-reference tests**: CodeGraph analyzing its own codebase
175+
- **Multi-version**: Python 3.9 - 3.13 via tox
176+
177+
## Dependencies
178+
179+
- **networkx**: Graph data structure (for matplotlib mode)
180+
- **matplotlib**: Legacy visualization
181+
- **click**: CLI framework
182+
183+
## Extension Points
184+
185+
1. **New visualizers**: Add functions to `vizualyzer.py`
186+
2. **New parsers**: Extend `parser.py` for other languages
187+
3. **New link types**: Add to `convert_to_d3_format()`
188+
4. **Export formats**: Add to `vizualyzer.py` (JSON, DOT, etc.)

‎CHANGELOG.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-01-17
9+
10+
### Added
11+
12+
**Interactive D3.js Visualization (New Default)**
13+
- D3.js visualization is now the default instead of matplotlib
14+
- Zoom & Pan: Mouse wheel to zoom, drag background to pan
15+
- Drag nodes: Reposition individual nodes by dragging
16+
- Collapse/Expand: Click on modules or entities to collapse/expand their children
17+
- Double-click: Focus and zoom to any node
18+
- Tooltips: Hover over nodes to see details (type, parent module, connection count)
19+
- Auto zoom-to-fit: Graph automatically fits to screen after loading
20+
21+
**Module-to-Module Connections**
22+
- Orange links now show dependencies between .py files
23+
- Visual representation of which modules depend on which
24+
- Module connections are always visible even when entities are collapsed
25+
26+
**Search with Autocomplete**
27+
- Search box at the top center of the visualization
28+
- Ctrl+F (Cmd+F on Mac) to focus search
29+
- Autocomplete dropdown with up to 10 matching results
30+
- Results show node type (module/entity/external) with color coding
31+
- Arrow keys to navigate, Enter to select, Esc to close
32+
- Highlighting: Selected node and its connections are highlighted, others dimmed
33+
- Info panel shows number of connected nodes
34+
35+
**Visual Design**
36+
- Modules: Green squares (larger)
37+
- Entities: Blue circles (functions/classes)
38+
- External dependencies: Gray circles
39+
- Module-to-Module links: Orange, thick (3px)
40+
- Module-to-Entity links: Green, dashed
41+
- Entity-to-Dependency links: Red
42+
- Statistics panel showing module count, entity count, and module connections
43+
- Legend explaining all node and link types
44+
- Dark theme with high contrast
45+
46+
**CLI Options**
47+
- `--matplotlib` flag to use legacy matplotlib visualization
48+
- `--output PATH` to specify custom output path for HTML file
49+
- Default output: `./codegraph.html` (current working directory)
50+
51+
### Changed
52+
- Default visualization changed from matplotlib to D3.js
53+
- `draw_graph()` now generates interactive HTML instead of matplotlib window
54+
- Renamed `draw_graph()` to `draw_graph_matplotlib()` for legacy visualization
55+
56+
### Fixed
57+
- KeyError when analyzing codebases with external imports not in the analyzed path
58+
- Now gracefully skips modules not found in the analyzed codebase
59+
- Comma-separated imports now properly parsed (e.g., `from package import a, b, c`)
60+
- Fixed missing connections when imports use comma-separated syntax
61+
62+
### Testing
63+
- Added comprehensive test suite for graph generation (`tests/test_graph_generation.py`)
64+
- Tests for import parsing: simple imports, comma-separated, aliased imports
65+
- Tests for CodeGraph connections between modules
66+
- Tests for D3.js format conversion
67+
- Tests verifying codegraph can analyze its own codebase
68+
- Support for Python 3.9, 3.10, 3.11, 3.12, 3.13
69+
- Added `tox.ini` for multi-version testing
70+
- Added GitHub Actions CI matrix for all supported Python versions
71+
72+
## [0.1.0] - Previous
73+
74+
### Added
75+
- Initial matplotlib visualization
76+
- Basic dependency graph generation
77+
- CLI interface with click
78+
- Support for Python 3.12+

‎CHANGELOG.txt‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

0 commit comments

Comments
 (0)