codeatlas-viz 0.2.2__py3-none-any.whl

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.
codeatlas/scanner.py ADDED
@@ -0,0 +1,335 @@
1
+ """Directory scanner, call-edge resolver, and graph analytics."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import fnmatch
6
+ import os
7
+ import re
8
+ from collections import Counter, defaultdict
9
+ from pathlib import Path
10
+
11
+ from .analyzers import analyze_file
12
+ from .analyzers.base import ParsedFile
13
+ from .models import CallEdge, CodeGraph, FileSummary, SymbolNode
14
+
15
+ DEFAULT_IGNORE_DIRS = frozenset({
16
+ ".git",
17
+ ".hg",
18
+ ".svn",
19
+ "node_modules",
20
+ ".venv",
21
+ "venv",
22
+ "env",
23
+ "__pycache__",
24
+ ".pytest_cache",
25
+ ".mypy_cache",
26
+ ".ruff_cache",
27
+ "dist",
28
+ "build",
29
+ ".svelte-kit",
30
+ ".next",
31
+ "coverage",
32
+ "target",
33
+ })
34
+
35
+ # Very generic method/function names that cause false cross-file edges when unresolved.
36
+ _AMBIGUOUS_GLOBAL_NAMES = frozenset({
37
+ "get", "set", "add", "remove", "delete", "update", "create", "read",
38
+ "write", "open", "close", "run", "start", "stop", "init", "main",
39
+ "append", "extend", "pop", "keys", "values", "items", "format",
40
+ "join", "split", "strip", "replace", "find", "filter", "map", "reduce",
41
+ "sort", "copy", "clear", "len", "str", "int", "float", "list", "dict",
42
+ "print", "log", "info", "debug", "warn", "error", "parse", "render",
43
+ "then", "catch", "finally", "resolve", "reject", "push", "slice", "splice",
44
+ "shift", "unshift", "includes", "indexOf", "toString", "valueOf",
45
+ "unwrap", "expect", "clone", "default", "new", "from", "into", "ok",
46
+ "err", "some", "none", "collect", "iter", "next", "is_empty", "String", "Error",
47
+ })
48
+
49
+
50
+ def _compile_ignore_patterns(patterns: list[str]) -> list[re.Pattern[str]]:
51
+ return [re.compile(fnmatch.translate(pat)) for pat in patterns]
52
+
53
+
54
+ def _load_gitignore(root: Path) -> list[str]:
55
+ """Load simple non-comment patterns from .gitignore if present."""
56
+ gitignore = root / ".gitignore"
57
+ if not gitignore.is_file():
58
+ return []
59
+ patterns: list[str] = []
60
+ try:
61
+ for raw in gitignore.read_text(encoding="utf-8", errors="replace").splitlines():
62
+ line = raw.strip()
63
+ if not line or line.startswith("#") or line.startswith("!"):
64
+ continue
65
+ cleaned = line.strip("/")
66
+ if cleaned:
67
+ patterns.append(cleaned)
68
+ except OSError:
69
+ return []
70
+ return patterns
71
+
72
+
73
+ def _is_ignored(rel_posix: str, name: str, compiled_patterns: list[re.Pattern[str]]) -> bool:
74
+ if name in DEFAULT_IGNORE_DIRS:
75
+ return True
76
+ if name.endswith((".min.js", ".min.mjs", ".bundle.js")):
77
+ return True
78
+ for pat in compiled_patterns:
79
+ if pat.match(name) or pat.match(rel_posix):
80
+ return True
81
+ return False
82
+
83
+
84
+ def _find_cycles(nodes: list[SymbolNode], edges: list[CallEdge], limit: int = 25) -> list[list[str]]:
85
+ """Find strongly connected components of size >= 2 using iterative Tarjan's algorithm."""
86
+ adj: dict[str, list[str]] = defaultdict(list)
87
+ for e in edges:
88
+ if e.source != e.target:
89
+ adj[e.source].append(e.target)
90
+
91
+ index_counter = 0
92
+ indices: dict[str, int] = {}
93
+ lowlink: dict[str, int] = {}
94
+ tarjan_stack: list[str] = []
95
+ on_stack: set[str] = set()
96
+ sccs: list[list[str]] = []
97
+
98
+ for root_node in nodes:
99
+ if root_node.id in indices:
100
+ continue
101
+ if len(sccs) >= limit:
102
+ break
103
+
104
+ # Call stack entries: [node_id, neighbor_iterator_index]
105
+ call_stack: list[list] = [[root_node.id, 0]]
106
+ indices[root_node.id] = index_counter
107
+ lowlink[root_node.id] = index_counter
108
+ index_counter += 1
109
+ tarjan_stack.append(root_node.id)
110
+ on_stack.add(root_node.id)
111
+
112
+ while call_stack:
113
+ v, nb_idx = call_stack[-1]
114
+ neighbors = adj.get(v, ())
115
+ if nb_idx < len(neighbors):
116
+ call_stack[-1][1] = nb_idx + 1
117
+ w = neighbors[nb_idx]
118
+ if w not in indices:
119
+ indices[w] = index_counter
120
+ lowlink[w] = index_counter
121
+ index_counter += 1
122
+ tarjan_stack.append(w)
123
+ on_stack.add(w)
124
+ call_stack.append([w, 0])
125
+ elif w in on_stack:
126
+ if indices[w] < lowlink[v]:
127
+ lowlink[v] = indices[w]
128
+ else:
129
+ call_stack.pop()
130
+ if call_stack:
131
+ parent = call_stack[-1][0]
132
+ if lowlink[v] < lowlink[parent]:
133
+ lowlink[parent] = lowlink[v]
134
+
135
+ if lowlink[v] == indices[v]:
136
+ component: list[str] = []
137
+ while True:
138
+ w = tarjan_stack.pop()
139
+ on_stack.remove(w)
140
+ component.append(w)
141
+ if w == v:
142
+ break
143
+ if len(component) >= 2:
144
+ sccs.append(list(reversed(component)))
145
+ if len(sccs) >= limit:
146
+ return sccs
147
+
148
+ return sccs[:limit]
149
+
150
+
151
+ def _build_import_paths(imports: list[str]) -> list[list[str]]:
152
+ return [
153
+ [p for p in imp.replace("\\", "/").replace(".", "/").split("/") if p]
154
+ for imp in imports
155
+ ]
156
+
157
+
158
+ def _resolve_target(
159
+ callee_name: str,
160
+ caller_node: SymbolNode | None,
161
+ caller_file: str,
162
+ caller_import_paths: list[list[str]],
163
+ by_file_and_name: dict[tuple[str, str], list[SymbolNode]],
164
+ by_name: dict[str, list[SymbolNode]],
165
+ file_meta: dict[str, tuple[str, str, set[str]]],
166
+ ) -> SymbolNode | None:
167
+ """Resolve a raw callee name to the most likely SymbolNode."""
168
+ # 1. Same-file symbol (prefer same-class method if caller is inside a class)
169
+ local_matches = by_file_and_name.get((caller_file, callee_name))
170
+ if local_matches:
171
+ if caller_node and caller_node.parent:
172
+ for m in local_matches:
173
+ if m.parent == caller_node.parent:
174
+ return m
175
+ return local_matches[0]
176
+
177
+ candidates = by_name.get(callee_name)
178
+ if not candidates:
179
+ return None
180
+
181
+ # 2. Imported module/file/package hint match (scored by matching path segments)
182
+ if caller_import_paths:
183
+ best_score = 0
184
+ best_candidate: SymbolNode | None = None
185
+ for c in candidates:
186
+ stem, parent_dir, c_parts = file_meta[c.file]
187
+ for parts in caller_import_paths:
188
+ if not parts:
189
+ continue
190
+ if stem in parts:
191
+ score = sum(1 for p in parts if p in c_parts) + 1
192
+ if score > best_score:
193
+ best_score = score
194
+ best_candidate = c
195
+ elif parent_dir and parent_dir == parts[-1]:
196
+ score = sum(1 for p in parts if p in c_parts)
197
+ if score > best_score:
198
+ best_score = score
199
+ best_candidate = c
200
+ if best_candidate is not None:
201
+ return best_candidate
202
+
203
+ # 3. Unique symbol in codebase (skip overly generic names)
204
+ if len(candidates) == 1 and callee_name not in _AMBIGUOUS_GLOBAL_NAMES:
205
+ return candidates[0]
206
+
207
+ return None
208
+
209
+
210
+ def scan_directory(root_path: str | Path, extra_ignores: list[str] | None = None) -> CodeGraph:
211
+ """Scan a codebase directory (or single source file) and return its resolved CodeGraph."""
212
+ root = Path(root_path).resolve()
213
+ files: list[FileSummary] = []
214
+ parsed_files: list[tuple[str, ParsedFile]] = []
215
+ all_nodes: list[SymbolNode] = []
216
+
217
+ if root.is_file():
218
+ analyzed = analyze_file(root, root.name)
219
+ if analyzed is not None:
220
+ lang, line_count, parsed = analyzed
221
+ files.append(
222
+ FileSummary(
223
+ path=root.name,
224
+ language=lang,
225
+ lines=line_count,
226
+ symbol_count=len(parsed.symbols),
227
+ )
228
+ )
229
+ parsed_files.append((root.name, parsed))
230
+ all_nodes.extend(parsed.symbols)
231
+ root = root.parent
232
+ else:
233
+ patterns = _load_gitignore(root)
234
+ if extra_ignores:
235
+ patterns.extend(extra_ignores)
236
+ compiled_patterns = _compile_ignore_patterns(patterns)
237
+
238
+ for dirpath, dirnames, filenames in os.walk(root):
239
+ rel_dir = Path(dirpath).relative_to(root).as_posix()
240
+ dirnames[:] = sorted(
241
+ d
242
+ for d in dirnames
243
+ if not _is_ignored(
244
+ f"{rel_dir}/{d}" if rel_dir != "." else d,
245
+ d,
246
+ compiled_patterns,
247
+ )
248
+ )
249
+
250
+ for fname in sorted(filenames):
251
+ fpath = Path(dirpath) / fname
252
+ rel_posix = fpath.relative_to(root).as_posix()
253
+ if _is_ignored(rel_posix, fname, compiled_patterns):
254
+ continue
255
+
256
+ analyzed = analyze_file(fpath, rel_posix)
257
+ if analyzed is None:
258
+ continue
259
+
260
+ lang, line_count, parsed = analyzed
261
+ files.append(
262
+ FileSummary(
263
+ path=rel_posix,
264
+ language=lang,
265
+ lines=line_count,
266
+ symbol_count=len(parsed.symbols),
267
+ )
268
+ )
269
+ parsed_files.append((rel_posix, parsed))
270
+ all_nodes.extend(parsed.symbols)
271
+
272
+ by_file_and_name: dict[tuple[str, str], list[SymbolNode]] = defaultdict(list)
273
+ by_name: dict[str, list[SymbolNode]] = defaultdict(list)
274
+ node_map: dict[str, SymbolNode] = {}
275
+ file_meta: dict[str, tuple[str, str, set[str]]] = {}
276
+
277
+ for node in all_nodes:
278
+ node_map[node.id] = node
279
+ by_file_and_name[(node.file, node.name)].append(node)
280
+ by_name[node.name].append(node)
281
+ if node.file not in file_meta:
282
+ c_path = Path(node.file)
283
+ stem = c_path.parent.name if c_path.stem in {"__init__", "index"} else c_path.stem
284
+ parent_dir = c_path.parent.name
285
+ file_meta[node.file] = (stem, parent_dir, set(c_path.with_suffix("").parts))
286
+
287
+ edge_counts: Counter[tuple[str, str]] = Counter()
288
+ for rel_posix, parsed in parsed_files:
289
+ import_paths = _build_import_paths(parsed.imports)
290
+ for caller_id, callees in parsed.raw_calls.items():
291
+ caller_node = node_map.get(caller_id)
292
+ for raw_callee in callees:
293
+ if (rel_posix, raw_callee) in by_file_and_name:
294
+ callee_name = raw_callee
295
+ else:
296
+ callee_name = parsed.aliases.get(raw_callee, raw_callee)
297
+ target = _resolve_target(
298
+ callee_name,
299
+ caller_node,
300
+ rel_posix,
301
+ import_paths,
302
+ by_file_and_name,
303
+ by_name,
304
+ file_meta,
305
+ )
306
+ if target and target.id != caller_id:
307
+ edge_counts[(caller_id, target.id)] += 1
308
+
309
+ edges: list[CallEdge] = []
310
+ file_edge_counts: Counter[tuple[str, str]] = Counter()
311
+ for (src, tgt), count in sorted(edge_counts.items()):
312
+ edges.append(CallEdge(source=src, target=tgt, call_count=count))
313
+ src_node = node_map.get(src)
314
+ tgt_node = node_map.get(tgt)
315
+ if src_node:
316
+ src_node.fan_out += 1
317
+ if tgt_node:
318
+ tgt_node.fan_in += 1
319
+ if src_node and tgt_node and src_node.file != tgt_node.file:
320
+ file_edge_counts[(src_node.file, tgt_node.file)] += count
321
+
322
+ file_edges = [
323
+ CallEdge(source=src_f, target=tgt_f, call_count=cnt)
324
+ for (src_f, tgt_f), cnt in sorted(file_edge_counts.items())
325
+ ]
326
+
327
+ cycles = _find_cycles(all_nodes, edges)
328
+ return CodeGraph(
329
+ root=str(root),
330
+ nodes=all_nodes,
331
+ edges=edges,
332
+ file_edges=file_edges,
333
+ files=files,
334
+ cycles=cycles,
335
+ )
codeatlas/server.py ADDED
@@ -0,0 +1,208 @@
1
+ """Local HTTP server for the CodeAtlas interactive Svelte UI and JSON API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import mimetypes
7
+ import socket
8
+ import threading
9
+ import webbrowser
10
+ from functools import partial
11
+ from http import HTTPStatus
12
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
13
+ from pathlib import Path
14
+ from typing import Any
15
+ from urllib.parse import parse_qs, urlparse
16
+
17
+ from .models import CodeGraph
18
+ from .scanner import scan_directory
19
+
20
+ WEB_DIR = Path(__file__).resolve().parent / "web"
21
+ MAX_PREVIEW_BYTES = 2_000_000
22
+
23
+
24
+ class _AppState:
25
+ def __init__(self, root: Path, graph: CodeGraph) -> None:
26
+ self.root = root.resolve()
27
+ self.graph = graph
28
+ self.lock = threading.Lock()
29
+
30
+ def rescan(self) -> CodeGraph:
31
+ fresh = scan_directory(self.root)
32
+ with self.lock:
33
+ self.graph = fresh
34
+ return fresh
35
+
36
+
37
+ class _AtlasHandler(BaseHTTPRequestHandler):
38
+ def __init__(self, *args: Any, state: _AppState, **kwargs: Any) -> None:
39
+ self.state = state
40
+ super().__init__(*args, **kwargs)
41
+
42
+ def log_message(self, format: str, *args: Any) -> None: # noqa: A002
43
+ # Keep terminal output clean; CLI prints startup info.
44
+ return
45
+
46
+ def _send_json(self, payload: Any, status: int = HTTPStatus.OK) -> None:
47
+ body = json.dumps(payload).encode("utf-8")
48
+ self.send_response(status)
49
+ self.send_header("Content-Type", "application/json; charset=utf-8")
50
+ self.send_header("Content-Length", str(len(body)))
51
+ self.send_header("Access-Control-Allow-Origin", "*")
52
+ self.end_headers()
53
+ self.wfile.write(body)
54
+
55
+ def _send_file_bytes(self, content: bytes, content_type: str, status: int = HTTPStatus.OK) -> None:
56
+ self.send_response(status)
57
+ self.send_header("Content-Type", content_type)
58
+ self.send_header("Content-Length", str(len(content)))
59
+ self.end_headers()
60
+ self.wfile.write(content)
61
+
62
+ def do_GET(self) -> None:
63
+ parsed = urlparse(self.path)
64
+ route = parsed.path
65
+
66
+ if route == "/api/health":
67
+ self._send_json({"status": "ok"})
68
+ return
69
+
70
+ if route == "/api/graph":
71
+ qs = parse_qs(parsed.query)
72
+ if qs.get("rescan") == ["1"]:
73
+ graph = self.state.rescan()
74
+ else:
75
+ with self.state.lock:
76
+ graph = self.state.graph
77
+ self._send_json(graph.to_dict())
78
+ return
79
+
80
+ if route == "/api/file":
81
+ self._handle_file_snippet(parse_qs(parsed.query))
82
+ return
83
+
84
+ self._serve_static(route)
85
+
86
+ def _handle_file_snippet(self, qs: dict[str, list[str]]) -> None:
87
+ rel = (qs.get("path") or [""])[0]
88
+ if not rel:
89
+ self._send_json({"error": "Missing 'path' query parameter"}, HTTPStatus.BAD_REQUEST)
90
+ return
91
+
92
+ target = (self.state.root / rel).resolve()
93
+ try:
94
+ target.relative_to(self.state.root)
95
+ except ValueError:
96
+ self._send_json({"error": "Access outside project root denied"}, HTTPStatus.FORBIDDEN)
97
+ return
98
+
99
+ if not target.is_file():
100
+ self._send_json({"error": "File not found"}, HTTPStatus.NOT_FOUND)
101
+ return
102
+
103
+ if target.stat().st_size > MAX_PREVIEW_BYTES:
104
+ self._send_json({"error": "File exceeds 2 MB preview limit"}, HTTPStatus.REQUEST_ENTITY_TOO_LARGE)
105
+ return
106
+
107
+ try:
108
+ all_lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
109
+ except OSError as exc:
110
+ self._send_json({"error": str(exc)}, HTTPStatus.INTERNAL_SERVER_ERROR)
111
+ return
112
+
113
+ total = len(all_lines)
114
+ try:
115
+ start = max(1, int((qs.get("start") or ["1"])[0]))
116
+ end = min(total, int((qs.get("end") or [str(total)])[0]))
117
+ except ValueError:
118
+ self._send_json({"error": "Invalid line range"}, HTTPStatus.BAD_REQUEST)
119
+ return
120
+
121
+ snippet = "\n".join(all_lines[start - 1 : end]) if total > 0 and start <= end else ""
122
+ self._send_json({
123
+ "path": rel,
124
+ "start_line": start,
125
+ "end_line": end,
126
+ "total_lines": total,
127
+ "content": snippet,
128
+ })
129
+
130
+ def _serve_static(self, route: str) -> None:
131
+ if not WEB_DIR.is_dir():
132
+ msg = b"<h1>CodeAtlas Web UI not built</h1><p>Run npm run build in frontend/.</p>"
133
+ self._send_file_bytes(msg, "text/html; charset=utf-8", HTTPStatus.SERVICE_UNAVAILABLE)
134
+ return
135
+
136
+ rel = route.lstrip("/") or "index.html"
137
+ candidate = (WEB_DIR / rel).resolve()
138
+ try:
139
+ candidate.relative_to(WEB_DIR.resolve())
140
+ except ValueError:
141
+ self._send_json({"error": "Forbidden"}, HTTPStatus.FORBIDDEN)
142
+ return
143
+
144
+ if not candidate.is_file():
145
+ # Return 404 for missing asset files; only use SPA fallback for extensionless routes.
146
+ if rel.startswith("assets/") or Path(rel).suffix:
147
+ self._send_json({"error": "Asset not found"}, HTTPStatus.NOT_FOUND)
148
+ return
149
+ candidate = WEB_DIR / "index.html"
150
+
151
+ mime, _ = mimetypes.guess_type(str(candidate))
152
+ content_type = mime or "application/octet-stream"
153
+ if content_type.startswith("text/") or content_type in ("application/javascript", "application/json"):
154
+ content_type += "; charset=utf-8"
155
+
156
+ self._send_file_bytes(candidate.read_bytes(), content_type)
157
+
158
+
159
+ class _AtlasHTTPServer(ThreadingHTTPServer):
160
+ daemon_threads = True
161
+ # On Windows, SO_REUSEADDR allows port hijacking and conflicts with SO_EXCLUSIVEADDRUSE.
162
+ allow_reuse_address = not hasattr(socket, "SO_EXCLUSIVEADDRUSE")
163
+
164
+ def server_bind(self) -> None:
165
+ if hasattr(socket, "SO_EXCLUSIVEADDRUSE"):
166
+ self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
167
+ super().server_bind()
168
+
169
+
170
+ def create_server(root: Path, graph: CodeGraph, host: str = "127.0.0.1", port: int = 4173) -> ThreadingHTTPServer:
171
+ """Create a configured ThreadingHTTPServer without starting its loop."""
172
+ state = _AppState(root=root, graph=graph)
173
+ handler = partial(_AtlasHandler, state=state)
174
+ return _AtlasHTTPServer((host, port), handler)
175
+
176
+
177
+ def serve_graph(
178
+ root: Path,
179
+ graph: CodeGraph,
180
+ host: str = "127.0.0.1",
181
+ port: int = 4173,
182
+ open_browser: bool = True,
183
+ ) -> None:
184
+ """Start the local CodeAtlas server and block until Ctrl+C."""
185
+ server: ThreadingHTTPServer | None = None
186
+ last_err: OSError | None = None
187
+ for candidate_port in range(port, port + 11):
188
+ try:
189
+ server = create_server(root, graph, host=host, port=candidate_port)
190
+ if candidate_port != port:
191
+ print(f"Port {port} busy; switched to port {candidate_port}.", flush=True)
192
+ break
193
+ except OSError as exc:
194
+ last_err = exc
195
+ if server is None:
196
+ raise RuntimeError(f"Could not bind HTTP server on ports {port}-{port + 10}: {last_err}")
197
+
198
+ actual_port = server.server_address[1]
199
+ url = f"http://{host}:{actual_port}"
200
+ print(f"CodeAtlas UI running at {url} (Press Ctrl+C to stop)", flush=True)
201
+ if open_browser:
202
+ threading.Timer(0.4, lambda: webbrowser.open(url)).start()
203
+ try:
204
+ server.serve_forever()
205
+ except KeyboardInterrupt:
206
+ print("\nShutting down CodeAtlas server.")
207
+ finally:
208
+ server.server_close()