@xand0dev/traceflow 0.0.0-stage → 0.2.0

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.
package/dist/parser.py ADDED
@@ -0,0 +1,825 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ TraceFlow parser: Django + React + React Native.
4
+
5
+ Reads a project with `ast` and regex and prints one JSON document to stdout:
6
+ services, pages, endpoints, models and the links between them
7
+ (page -> endpoint -> model). Every item carries its file and line.
8
+
9
+ Strictly read-only. Never imports or runs the target project.
10
+
11
+ Usage: python parser.py <project_root>
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import ast
17
+ import json
18
+ import os
19
+ import re
20
+ import sys
21
+ from pathlib import Path
22
+ from typing import Any
23
+
24
+ SCHEMA_VERSION = 2
25
+
26
+ SKIP_DIRS = frozenset({
27
+ "node_modules", ".git", "__pycache__", "venv", ".venv", "env", ".env",
28
+ "dist", "build", "out", "staticfiles", "static", ".expo", "migrations",
29
+ ".idea", ".vscode", ".vercel", ".next", ".tanstack", ".pytest_cache",
30
+ ".mypy_cache", ".ruff_cache", "coverage", ".turbo", "Pods",
31
+ })
32
+
33
+ JS_EXT = (".js", ".jsx", ".ts", ".tsx")
34
+ HTTP_METHODS = ("get", "post", "put", "patch", "delete")
35
+
36
+
37
+ def walk(root: str):
38
+ for dirpath, dirs, files in os.walk(root):
39
+ dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
40
+ yield dirpath, files
41
+
42
+
43
+ def rel(path: str, root: str) -> str:
44
+ return os.path.relpath(path, root).replace(os.sep, "/")
45
+
46
+
47
+ def read(path: str) -> str:
48
+ try:
49
+ return Path(path).read_text(encoding="utf-8", errors="replace")
50
+ except OSError:
51
+ return ""
52
+
53
+
54
+ def parse_py(path: str) -> ast.Module | None:
55
+ try:
56
+ return ast.parse(read(path), filename=path)
57
+ except (SyntaxError, ValueError):
58
+ return None
59
+
60
+
61
+ # ──────────────────────────────────────────────────────────────────────────────
62
+ # Paths: one shape for Django routes and frontend calls
63
+ # ──────────────────────────────────────────────────────────────────────────────
64
+
65
+ _DJANGO_PARAM = re.compile(r"<(?:\w+:)?(\w+)>")
66
+ _REGEX_GROUP = re.compile(r"\(\?P<(\w+)>[^)]*\)")
67
+ _TEMPLATE_PARAM = re.compile(r"\$\{\s*([\w.]+)[^}]*\}")
68
+
69
+
70
+ def normalize_path(path: str) -> str:
71
+ """'/api/orders/<int:pk>/' and `/api/orders/${id}/` both become '/api/orders/{pk}/'-style."""
72
+ p = path.strip()
73
+ p = p.split("?")[0].split("#")[0]
74
+ p = p.lstrip("^").rstrip("$")
75
+ p = _REGEX_GROUP.sub(lambda m: "{" + m.group(1) + "}", p)
76
+ p = _DJANGO_PARAM.sub(lambda m: "{" + m.group(1) + "}", p)
77
+ p = _TEMPLATE_PARAM.sub(lambda m: "{" + m.group(1).split(".")[-1] + "}", p)
78
+ p = re.sub(r"/+", "/", "/" + p.lstrip("/"))
79
+ return p
80
+
81
+
82
+ def path_key(path: str) -> str:
83
+ """Comparable key: params become '*', trailing slash ignored."""
84
+ segs = [s for s in normalize_path(path).split("/") if s]
85
+ return "/" + "/".join("*" if s.startswith("{") else s for s in segs)
86
+
87
+
88
+ def match_endpoint(call_path: str, endpoints: list[dict[str, Any]]) -> dict[str, Any] | None:
89
+ key = path_key(call_path)
90
+ segs = key.strip("/").split("/")
91
+ for ep in endpoints:
92
+ if ep["_key"] == key:
93
+ return ep
94
+ for ep in endpoints:
95
+ esegs = ep["_key"].strip("/").split("/")
96
+ if len(esegs) == len(segs) and all(a == "*" or b == "*" or a == b for a, b in zip(esegs, segs)):
97
+ return ep
98
+ return None
99
+
100
+
101
+ # ──────────────────────────────────────────────────────────────────────────────
102
+ # Django
103
+ # ──────────────────────────────────────────────────────────────────────────────
104
+
105
+ def find_django_root(target: str) -> str | None:
106
+ if os.path.exists(os.path.join(target, "manage.py")):
107
+ return target
108
+ for dirpath, files in walk(target):
109
+ if "manage.py" in files:
110
+ return dirpath
111
+ return None
112
+
113
+
114
+ def find_settings(django_root: str) -> tuple[str | None, str | None]:
115
+ """Find ROOT_URLCONF in settings.py or in a settings/ package (base.py, dev.py, ...)."""
116
+ candidates: list[str] = []
117
+ for dirpath, files in walk(django_root):
118
+ in_pkg = os.path.basename(dirpath) == "settings"
119
+ for f in files:
120
+ if f == "settings.py" or (in_pkg and f.endswith(".py")):
121
+ candidates.append(os.path.join(dirpath, f))
122
+ candidates.sort(key=lambda p: (os.path.basename(p) not in ("settings.py", "base.py", "__init__.py"), len(p)))
123
+ for path in candidates:
124
+ tree = parse_py(path)
125
+ if not tree:
126
+ continue
127
+ for node in ast.walk(tree):
128
+ if isinstance(node, ast.Assign):
129
+ for t in node.targets:
130
+ if isinstance(t, ast.Name) and t.id == "ROOT_URLCONF" and isinstance(node.value, ast.Constant):
131
+ return path, str(node.value.value)
132
+ return (candidates[0] if candidates else None), None
133
+
134
+
135
+ def guess_root_urls(django_root: str) -> str | None:
136
+ """No ROOT_URLCONF found: use the urls.py that sits next to wsgi.py or asgi.py."""
137
+ for dirpath, files in walk(django_root):
138
+ if "urls.py" in files and ("wsgi.py" in files or "asgi.py" in files):
139
+ return os.path.join(dirpath, "urls.py")
140
+ return None
141
+
142
+
143
+ def detect_db(settings_path: str | None) -> str:
144
+ src = ""
145
+ if settings_path:
146
+ folder = os.path.dirname(settings_path)
147
+ files = [os.path.join(folder, f) for f in os.listdir(folder) if f.endswith(".py")] if os.path.basename(folder) == "settings" else [settings_path]
148
+ src = "\n".join(read(f) for f in files)
149
+ if "postgresql" in src or "postgis" in src:
150
+ return "PostgreSQL"
151
+ if "mysql" in src:
152
+ return "MySQL"
153
+ if "oracle" in src:
154
+ return "Oracle"
155
+ return "SQLite"
156
+
157
+
158
+ def resolve_module(dotted: str, django_root: str) -> str | None:
159
+ parts = dotted.split(".")
160
+ for candidate in (os.path.join(*parts) + ".py", os.path.join(*parts, "__init__.py")):
161
+ full = os.path.join(django_root, candidate)
162
+ if os.path.exists(full):
163
+ return full
164
+ return None
165
+
166
+
167
+ def _call_name(node: ast.Call) -> str:
168
+ if isinstance(node.func, ast.Name):
169
+ return node.func.id
170
+ if isinstance(node.func, ast.Attribute):
171
+ return node.func.attr
172
+ return ""
173
+
174
+
175
+ def _str(node: ast.AST | None) -> str | None:
176
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
177
+ return node.value
178
+ return None
179
+
180
+
181
+ def _view_name(node: ast.AST) -> str | None:
182
+ if isinstance(node, ast.Name):
183
+ return node.id
184
+ if isinstance(node, ast.Attribute):
185
+ return node.attr
186
+ if isinstance(node, ast.Call):
187
+ if isinstance(node.func, ast.Attribute) and node.func.attr == "as_view":
188
+ return _view_name(node.func.value)
189
+ return _view_name(node.func)
190
+ return None
191
+
192
+
193
+ def _router_name(node: ast.AST | None) -> str | None:
194
+ """`router.urls` -> 'router'."""
195
+ if isinstance(node, ast.Attribute) and node.attr == "urls" and isinstance(node.value, ast.Name):
196
+ return node.value.id
197
+ return None
198
+
199
+
200
+ def _imported_files(tree: ast.Module, path: str, django_root: str) -> dict[str, str]:
201
+ """Map names imported with `from x import name` to the file that defines them."""
202
+ out: dict[str, str] = {}
203
+ for node in ast.walk(tree):
204
+ if not isinstance(node, ast.ImportFrom):
205
+ continue
206
+ mod = node.module or ""
207
+ if node.level:
208
+ base = os.path.dirname(path)
209
+ for _ in range(node.level - 1):
210
+ base = os.path.dirname(base)
211
+ cand = os.path.join(base, *mod.split(".")) if mod else base
212
+ file = cand + ".py" if os.path.exists(cand + ".py") else os.path.join(cand, "__init__.py")
213
+ else:
214
+ file = resolve_module(mod, django_root) or ""
215
+ if file and os.path.exists(file):
216
+ for alias in node.names:
217
+ out[alias.asname or alias.name] = file
218
+ return out
219
+
220
+
221
+ def _register_routes(tree: ast.Module, path: str, router: str | None, prefix: str) -> list[dict[str, Any]]:
222
+ """DRF `router.register("prefix", ViewSet)` calls, for one router or all of them."""
223
+ out: list[dict[str, Any]] = []
224
+ for node in ast.walk(tree):
225
+ if not (isinstance(node, ast.Call) and _call_name(node) == "register" and len(node.args) >= 2):
226
+ continue
227
+ owner = node.func.value.id if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name) else None
228
+ if router is not None and owner != router:
229
+ continue
230
+ route = _str(node.args[0])
231
+ if route is None:
232
+ continue
233
+ base = normalize_path(prefix + "/" + route.lstrip("^").rstrip("$") + "/")
234
+ kw = {k.arg: _str(k.value) for k in node.keywords}
235
+ common = {"view": _view_name(node.args[1]) or "unknown", "name": kw.get("basename") or "", "file": path, "line": node.lineno}
236
+ out.append({"path": base, "kind": "viewset-list", **common})
237
+ out.append({"path": base + "{id}/", "kind": "viewset-detail", **common})
238
+ return out
239
+
240
+
241
+ def parse_urls(path: str, django_root: str, prefix: str, seen: set[str]) -> list[dict[str, Any]]:
242
+ if path in seen:
243
+ return []
244
+ seen = seen | {path}
245
+ tree = parse_py(path)
246
+ if not tree:
247
+ return []
248
+ out: list[dict[str, Any]] = []
249
+
250
+ # Where each DRF router is mounted: path("api/", include(router.urls)) or urlpatterns += router.urls
251
+ mounts: dict[str, str] = {}
252
+ for node in ast.walk(tree):
253
+ if isinstance(node, ast.Call) and _call_name(node) in ("path", "re_path", "url") and len(node.args) >= 2:
254
+ route = _str(node.args[0])
255
+ target = node.args[1]
256
+ if route is not None and isinstance(target, ast.Call) and _call_name(target) == "include" and target.args:
257
+ r = _router_name(target.args[0])
258
+ if r:
259
+ mounts[r] = prefix + route.lstrip("^").rstrip("$")
260
+ elif isinstance(node, (ast.Assign, ast.AugAssign)):
261
+ for sub in ast.walk(node.value):
262
+ r = _router_name(sub)
263
+ if r and r not in mounts:
264
+ mounts[r] = prefix
265
+
266
+ for node in ast.walk(tree):
267
+ if not isinstance(node, ast.Call):
268
+ continue
269
+ name = _call_name(node)
270
+ if name in ("path", "re_path", "url") and len(node.args) >= 2:
271
+ route = _str(node.args[0])
272
+ if route is None:
273
+ continue
274
+ target = node.args[1]
275
+ if isinstance(target, ast.Call) and _call_name(target) == "include":
276
+ mod = _str(target.args[0]) if target.args else None
277
+ if not mod and target.args and isinstance(target.args[0], ast.Tuple):
278
+ mod = _str(target.args[0].elts[0]) if target.args[0].elts else None
279
+ sub = resolve_module(mod, django_root) if mod else None
280
+ if sub:
281
+ out.extend(parse_urls(sub, django_root, prefix + route.lstrip("^").rstrip("$"), seen))
282
+ continue
283
+ if isinstance(target, ast.Attribute) and target.attr == "urls":
284
+ continue # admin.site.urls and similar bundles, not one endpoint
285
+ kw = {k.arg: _str(k.value) for k in node.keywords}
286
+ out.append({
287
+ "path": normalize_path(prefix + route),
288
+ "view": _view_name(target) or "unknown",
289
+ "name": kw.get("name") or "",
290
+ "kind": "route",
291
+ "file": path,
292
+ "line": node.lineno,
293
+ })
294
+
295
+ local_routers = {
296
+ n.func.value.id for n in ast.walk(tree)
297
+ if isinstance(n, ast.Call) and _call_name(n) == "register"
298
+ and isinstance(n.func, ast.Attribute) and isinstance(n.func.value, ast.Name)
299
+ }
300
+ for router in local_routers:
301
+ out.extend(_register_routes(tree, path, router, mounts.get(router, prefix)))
302
+ # Routers defined in another module and mounted here
303
+ imports = _imported_files(tree, path, django_root)
304
+ for router, mount in mounts.items():
305
+ if router in local_routers or router not in imports or imports[router] in seen:
306
+ continue
307
+ other = parse_py(imports[router])
308
+ if other:
309
+ out.extend(_register_routes(other, imports[router], router, mount))
310
+ return out
311
+
312
+
313
+ def collect_python_symbols(django_root: str) -> tuple[dict[str, dict], list[dict[str, Any]]]:
314
+ """Index view-like classes/functions and Django models across the backend."""
315
+ views: dict[str, dict] = {}
316
+ models: list[dict[str, Any]] = []
317
+ classes: list[tuple[ast.ClassDef, str]] = []
318
+ for dirpath, files in walk(django_root):
319
+ for fname in files:
320
+ if not fname.endswith(".py"):
321
+ continue
322
+ path = os.path.join(dirpath, fname)
323
+ tree = parse_py(path)
324
+ if not tree:
325
+ continue
326
+ for node in ast.iter_child_nodes(tree):
327
+ if isinstance(node, ast.ClassDef):
328
+ classes.append((node, path))
329
+ views.setdefault(node.name, {
330
+ "file": path, "line": node.lineno, "node": node, "bases": [_base_name(b) for b in node.bases],
331
+ })
332
+ elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
333
+ views.setdefault(node.name, {"file": path, "line": node.lineno, "node": node, "bases": []})
334
+
335
+ # A class is a model if it extends models.Model, a Django base model, or another model class.
336
+ model_names = set(MODEL_BASES)
337
+ changed = True
338
+ while changed:
339
+ changed = False
340
+ for node, _ in classes:
341
+ if node.name not in model_names and any(_base_name(b) in model_names for b in node.bases):
342
+ model_names.add(node.name)
343
+ changed = True
344
+ for node, path in classes:
345
+ if node.name in model_names and node.name not in MODEL_BASES and not _is_abstract(node):
346
+ models.append(_model_info(node, path))
347
+ views.pop(node.name, None)
348
+ return views, models
349
+
350
+
351
+ MODEL_BASES = {"Model", "AbstractUser", "AbstractBaseUser", "PolymorphicModel", "MPTTModel", "TimeStampedModel"}
352
+
353
+
354
+ def _is_abstract(node: ast.ClassDef) -> bool:
355
+ for item in node.body:
356
+ if isinstance(item, ast.ClassDef) and item.name == "Meta":
357
+ for stmt in item.body:
358
+ if isinstance(stmt, ast.Assign) and any(isinstance(t, ast.Name) and t.id == "abstract" for t in stmt.targets):
359
+ return isinstance(stmt.value, ast.Constant) and stmt.value.value is True
360
+ return False
361
+
362
+
363
+ def _base_name(node: ast.AST) -> str:
364
+ if isinstance(node, ast.Name):
365
+ return node.id
366
+ if isinstance(node, ast.Attribute):
367
+ return node.attr
368
+ return ""
369
+
370
+
371
+ RELATION_FIELDS = {"ForeignKey", "OneToOneField", "ManyToManyField"}
372
+
373
+
374
+ def _model_info(node: ast.ClassDef, path: str) -> dict[str, Any]:
375
+ fields: list[str] = []
376
+ relations: list[dict[str, str]] = []
377
+ for item in node.body:
378
+ if not isinstance(item, ast.Assign) or not isinstance(item.value, ast.Call):
379
+ continue
380
+ for t in item.targets:
381
+ if not isinstance(t, ast.Name):
382
+ continue
383
+ ftype = _call_name(item.value)
384
+ if not ftype.endswith(("Field", "Key")):
385
+ continue
386
+ fields.append(f"{t.id}: {ftype}")
387
+ if ftype in RELATION_FIELDS and item.value.args:
388
+ target = item.value.args[0]
389
+ tname = _str(target) or _base_name(target)
390
+ if tname:
391
+ relations.append({"field": t.id, "type": ftype, "target": tname.split(".")[-1]})
392
+ return {"name": node.name, "fields": fields, "relations": relations, "file": path, "line": node.lineno}
393
+
394
+
395
+ def view_details(view: dict | None, model_names: set[str]) -> tuple[list[str], list[str]]:
396
+ """Return (http methods, models used) for a view class or function."""
397
+ if not view:
398
+ return ["GET"], []
399
+ node = view["node"]
400
+ used = sorted({n.id for n in ast.walk(node) if isinstance(n, ast.Name) and n.id in model_names})
401
+ bases = " ".join(view["bases"])
402
+ if isinstance(node, ast.ClassDef):
403
+ defined = [f.name.upper() for f in node.body
404
+ if isinstance(f, (ast.FunctionDef, ast.AsyncFunctionDef)) and f.name in HTTP_METHODS]
405
+ if defined:
406
+ return defined, used
407
+ if "ReadOnly" in bases:
408
+ return ["GET"], used
409
+ if "ViewSet" in bases:
410
+ return ["GET", "POST", "PUT", "PATCH", "DELETE"], used
411
+ if "ListCreate" in bases:
412
+ return ["GET", "POST"], used
413
+ if "RetrieveUpdateDestroy" in bases:
414
+ return ["GET", "PUT", "PATCH", "DELETE"], used
415
+ if "Create" in bases:
416
+ return ["POST"], used
417
+ return ["GET"], used
418
+ decorated = [d for d in getattr(node, "decorator_list", []) if isinstance(d, ast.Call) and _call_name(d) == "api_view"]
419
+ if decorated and decorated[0].args and isinstance(decorated[0].args[0], ast.List):
420
+ return [(_str(e) or "GET").upper() for e in decorated[0].args[0].elts], used
421
+ return ["GET"], used
422
+
423
+
424
+ def endpoint_group(path: str) -> str:
425
+ segs = [s for s in path.split("/") if s and not s.startswith("{")]
426
+ if segs and segs[0] == "api":
427
+ segs = segs[1:]
428
+ if segs and re.fullmatch(r"v\d+", segs[0]):
429
+ segs = segs[1:]
430
+ if any(s in ("login", "logout", "register", "token", "auth") for s in segs[:2]):
431
+ return "auth"
432
+ return segs[0] if segs else "root"
433
+
434
+
435
+ # ──────────────────────────────────────────────────────────────────────────────
436
+ # Frontends
437
+ # ──────────────────────────────────────────────────────────────────────────────
438
+
439
+ _API_LITERAL = re.compile(r"""(["'`])((?:\$\{[^}`]+\})?/api/[^"'`\s]*)\1""")
440
+ _METHOD_HINT = re.compile(r"""method\s*:\s*["'`](\w+)["'`]""", re.I)
441
+ _AXIOS_METHOD = re.compile(r"""\.(get|post|put|patch|delete)\s*\(\s*$""", re.I)
442
+ _IMPORT = re.compile(r"""import\s+[^'"]*?from\s+["'](\.[^"']+)["']""")
443
+
444
+
445
+ def extract_calls(path: str) -> list[dict[str, Any]]:
446
+ src = read(path)
447
+ calls: list[dict[str, Any]] = []
448
+ for m in _API_LITERAL.finditer(src):
449
+ raw = m.group(2)
450
+ raw = re.sub(r"^\$\{[^}]+\}", "", raw)
451
+ before = src[max(0, m.start() - 40):m.start()]
452
+ after = src[m.end():m.end() + 160]
453
+ method = "GET"
454
+ am = _AXIOS_METHOD.search(before)
455
+ hm = _METHOD_HINT.search(after.split(")")[0] + ")" if ")" in after else after)
456
+ if am:
457
+ method = am.group(1).upper()
458
+ elif hm:
459
+ method = hm.group(1).upper()
460
+ calls.append({
461
+ "path": normalize_path(raw),
462
+ "method": method,
463
+ "file": path,
464
+ "line": src.count("\n", 0, m.start()) + 1,
465
+ })
466
+ return calls
467
+
468
+
469
+ def local_imports(path: str) -> list[str]:
470
+ out: list[str] = []
471
+ base = os.path.dirname(path)
472
+ for m in _IMPORT.finditer(read(path)):
473
+ stem = os.path.normpath(os.path.join(base, m.group(1)))
474
+ for ext in JS_EXT:
475
+ for cand in (stem + ext, os.path.join(stem, "index" + ext)):
476
+ if os.path.exists(cand):
477
+ out.append(cand)
478
+ return out
479
+
480
+
481
+ def index_components(root: str) -> dict[str, str]:
482
+ comps: dict[str, str] = {}
483
+ for dirpath, files in walk(root):
484
+ for f in files:
485
+ if f.endswith(JS_EXT) and not f.endswith(".d.ts"):
486
+ comps.setdefault(f.rsplit(".", 1)[0], os.path.join(dirpath, f))
487
+ return comps
488
+
489
+
490
+ _ROUTE_JSX = re.compile(
491
+ r"<Route\b(?P<attrs>[^>]*?)element=\{\s*<(?P<comp>\w+)", re.DOTALL)
492
+ _ROUTE_OBJ = re.compile(
493
+ r"""path\s*:\s*["'](?P<path>[^"']*)["'][^}]*?(?:element\s*:\s*<(?P<comp>\w+)|Component\s*:\s*(?P<comp2>\w+))""",
494
+ re.DOTALL)
495
+ _WRAPPERS = {"Navigate", "Layout", "Suspense", "Outlet", "PrivateRoute", "ProtectedRoute", "RequireAuth", "AnimatedPage"}
496
+
497
+
498
+ def parse_web_pages(root: str, comps: dict[str, str]) -> list[dict[str, Any]]:
499
+ pages: list[dict[str, Any]] = []
500
+ seen: set[str] = set()
501
+ for dirpath, files in walk(root):
502
+ for f in files:
503
+ if not f.endswith(JS_EXT):
504
+ continue
505
+ path = os.path.join(dirpath, f)
506
+ src = read(path)
507
+ if "Route" not in src and "createBrowserRouter" not in src:
508
+ continue
509
+ for m in _ROUTE_JSX.finditer(src):
510
+ pm = re.search(r"""path=["']([^"']*)["']""", m.group("attrs"))
511
+ is_index = re.search(r"\bindex\b", m.group("attrs"))
512
+ route = pm.group(1) if pm else ("/" if is_index else None)
513
+ comp = m.group("comp")
514
+ if route is None or comp in _WRAPPERS:
515
+ continue
516
+ _add_page(pages, seen, route, comp, comps, path, src.count("\n", 0, m.start()) + 1)
517
+ for m in _ROUTE_OBJ.finditer(src):
518
+ comp = m.group("comp") or m.group("comp2")
519
+ if comp in _WRAPPERS:
520
+ continue
521
+ _add_page(pages, seen, m.group("path"), comp, comps, path, src.count("\n", 0, m.start()) + 1)
522
+ # Next.js-style or plain pages/ folders when no router was found
523
+ if not pages:
524
+ for d in ("src/pages", "pages", "src/views", "app"):
525
+ pdir = os.path.join(root, d)
526
+ if not os.path.isdir(pdir):
527
+ continue
528
+ for f in sorted(os.listdir(pdir)):
529
+ if f.endswith(JS_EXT) and not f.startswith(("_", ".", "index")):
530
+ comp = f.rsplit(".", 1)[0]
531
+ route = "/" + re.sub(r"(Page|View)$", "", comp).lower()
532
+ _add_page(pages, seen, route, comp, comps, os.path.join(pdir, f), 1)
533
+ return pages
534
+
535
+
536
+ def _add_page(pages, seen, route, comp, comps, decl_file, decl_line):
537
+ route = route if route.startswith("/") else "/" + route
538
+ if route in seen:
539
+ return
540
+ seen.add(route)
541
+ file = comps.get(comp)
542
+ pages.append({
543
+ "name": comp,
544
+ "path": route,
545
+ "component": comp,
546
+ "file": file or decl_file,
547
+ "line": 1 if file else decl_line,
548
+ "auth": bool(re.search(r"admin|account|profile|settings|dashboard|cabinet|orders", comp, re.I)),
549
+ })
550
+
551
+
552
+ _SCREEN = re.compile(
553
+ r"""<(?P<nav>\w+)\.Screen\s+name=["'](?P<name>[^"']+)["'](?:[^>]*?component=\{(?P<comp>\w+)\})?""", re.DOTALL)
554
+
555
+
556
+ def parse_rn_screens(root: str, comps: dict[str, str]) -> list[dict[str, Any]]:
557
+ screens: list[dict[str, Any]] = []
558
+ seen: set[str] = set()
559
+ for dirpath, files in walk(root):
560
+ for f in files:
561
+ if not f.endswith(JS_EXT):
562
+ continue
563
+ path = os.path.join(dirpath, f)
564
+ src = read(path)
565
+ if ".Screen" not in src:
566
+ continue
567
+ for m in _SCREEN.finditer(src):
568
+ name = m.group("name")
569
+ if name in seen:
570
+ continue
571
+ seen.add(name)
572
+ comp = m.group("comp") or name + "Screen"
573
+ screens.append({
574
+ "name": name,
575
+ "component": comp,
576
+ "navType": "tab" if "tab" in m.group("nav").lower() else "stack",
577
+ "file": comps.get(comp, path),
578
+ "line": 1 if comp in comps else src.count("\n", 0, m.start()) + 1,
579
+ })
580
+ # expo-router: app/ directory files are screens
581
+ app_dir = os.path.join(root, "app")
582
+ if not screens and os.path.isdir(app_dir):
583
+ for dirpath, files in walk(app_dir):
584
+ for f in files:
585
+ if f.endswith(JS_EXT) and not f.startswith("_"):
586
+ name = rel(os.path.join(dirpath, f), app_dir).rsplit(".", 1)[0]
587
+ screens.append({"name": name, "component": name, "navType": "stack",
588
+ "file": os.path.join(dirpath, f), "line": 1})
589
+ return screens
590
+
591
+
592
+ def find_frontends(target: str) -> list[dict[str, Any]]:
593
+ projects: list[dict[str, Any]] = []
594
+ for dirpath, files in walk(target):
595
+ if "package.json" not in files:
596
+ continue
597
+ try:
598
+ pkg = json.loads(read(os.path.join(dirpath, "package.json")) or "{}")
599
+ except json.JSONDecodeError:
600
+ continue
601
+ deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
602
+ if "react" not in deps:
603
+ continue
604
+ is_rn = "react-native" in deps or "expo" in deps
605
+ if not is_rn and not any(k in deps for k in ("react-dom", "vite", "react-router-dom", "next")):
606
+ continue
607
+ projects.append({
608
+ "root": dirpath,
609
+ "name": pkg.get("name") or os.path.basename(dirpath),
610
+ "type": "mobile" if is_rn else "web",
611
+ "deps": deps,
612
+ })
613
+ return projects
614
+
615
+
616
+ # ──────────────────────────────────────────────────────────────────────────────
617
+ # Stack summary
618
+ # ──────────────────────────────────────────────────────────────────────────────
619
+
620
+ STACK_JS = {
621
+ "react": "React", "react-native": "React Native", "expo": "Expo", "next": "Next.js",
622
+ "vite": "Vite", "react-router-dom": "React Router", "@tanstack/react-query": "TanStack Query",
623
+ "axios": "Axios", "redux": "Redux", "@reduxjs/toolkit": "Redux Toolkit", "zustand": "Zustand",
624
+ "tailwindcss": "Tailwind", "typescript": "TypeScript",
625
+ }
626
+ STACK_PY = {
627
+ "django": "Django", "djangorestframework": "Django REST", "celery": "Celery", "channels": "Channels",
628
+ "redis": "Redis", "psycopg": "psycopg", "psycopg2": "psycopg", "psycopg2-binary": "psycopg",
629
+ "drf-spectacular": "OpenAPI", "fastapi": "FastAPI",
630
+ }
631
+
632
+
633
+ def python_deps(django_root: str | None, target: str) -> set[str]:
634
+ names: set[str] = set()
635
+ for base in filter(None, {django_root, target}):
636
+ for fname in ("requirements.txt", "requirements/base.txt", "pyproject.toml", "Pipfile"):
637
+ src = read(os.path.join(base, fname)).lower()
638
+ for key in STACK_PY:
639
+ if re.search(rf"(^|[\s\"'\[]){re.escape(key)}([\s=<>~!\[\"',;]|$)", src, re.M):
640
+ names.add(STACK_PY[key])
641
+ return names
642
+
643
+
644
+ # ──────────────────────────────────────────────────────────────────────────────
645
+ # Main
646
+ # ──────────────────────────────────────────────────────────────────────────────
647
+
648
+ def scan(target: str) -> dict[str, Any]:
649
+ target = os.path.abspath(target)
650
+ django_root = find_django_root(target)
651
+ endpoints: list[dict[str, Any]] = []
652
+ models: list[dict[str, Any]] = []
653
+ db = None
654
+ stack: set[str] = set()
655
+
656
+ if django_root:
657
+ stack.add("Django")
658
+ settings_path, urlconf = find_settings(django_root)
659
+ db = detect_db(settings_path)
660
+ settings_src = read(settings_path) if settings_path else ""
661
+ if "rest_framework" in settings_src:
662
+ stack.add("Django REST")
663
+ if "channels" in settings_src:
664
+ stack.add("Channels")
665
+ views, models = collect_python_symbols(django_root)
666
+ model_names = {m["name"] for m in models}
667
+ root_urls = resolve_module(urlconf, django_root) if urlconf else None
668
+ root_urls = root_urls or guess_root_urls(django_root)
669
+ if root_urls:
670
+ endpoints = parse_urls(root_urls, django_root, "", set())
671
+ for ep in endpoints:
672
+ view = views.get(ep["view"])
673
+ methods, used = view_details(view, model_names)
674
+ if ep["kind"] == "viewset-list":
675
+ methods = [m for m in methods if m in ("GET", "POST")] or ["GET"]
676
+ elif ep["kind"] == "viewset-detail":
677
+ methods = [m for m in methods if m != "POST"] or ["GET"]
678
+ ep["methods"] = methods
679
+ ep["models"] = used
680
+ if view:
681
+ ep["viewFile"] = rel(view["file"], target)
682
+ ep["viewLine"] = view["line"]
683
+ stack |= python_deps(django_root, target)
684
+
685
+ # de-duplicate endpoints by normalized key
686
+ unique: dict[str, dict[str, Any]] = {}
687
+ for ep in endpoints:
688
+ key = path_key(ep["path"])
689
+ if key in unique:
690
+ unique[key]["methods"] = sorted(set(unique[key]["methods"]) | set(ep["methods"]))
691
+ continue
692
+ ep["_key"] = key
693
+ ep["id"] = "ep:" + key
694
+ ep["group"] = endpoint_group(ep["path"])
695
+ ep["file"] = rel(ep["file"], target)
696
+ unique[key] = ep
697
+ endpoints = sorted(unique.values(), key=lambda e: (e["group"], e["path"]))
698
+
699
+ services: list[dict[str, Any]] = []
700
+ pages_out: list[dict[str, Any]] = []
701
+ unmatched: list[dict[str, Any]] = []
702
+
703
+ for i, fe in enumerate(find_frontends(target), start=1):
704
+ for dep, label in STACK_JS.items():
705
+ if dep in fe["deps"]:
706
+ stack.add(label)
707
+ comps = index_components(fe["root"])
708
+ safe = re.sub(r"[^a-zA-Z0-9-]", "", fe["name"]) or f"app{i}"
709
+ sid = f"frontend-{fe['type']}-{safe}-{i}"
710
+ items = parse_web_pages(fe["root"], comps) if fe["type"] == "web" else parse_rn_screens(fe["root"], comps)
711
+ attributed: set[str] = set()
712
+ for item in items:
713
+ files = [item["file"]] + local_imports(item["file"])
714
+ calls = [c for f in files for c in extract_calls(f)]
715
+ attributed.update(files)
716
+ links = []
717
+ for c in calls:
718
+ ep = match_endpoint(c["path"], endpoints)
719
+ if ep:
720
+ links.append({"endpoint": ep["id"], "method": c["method"], "file": rel(c["file"], target), "line": c["line"]})
721
+ else:
722
+ unmatched.append({**c, "file": rel(c["file"], target), "from": item["name"]})
723
+ item["id"] = f"page:{sid}:{item.get('path') or item['name']}"
724
+ item["service"] = sid
725
+ item["file"] = rel(item["file"], target)
726
+ item["calls"] = _dedupe_links(links)
727
+ pages_out.append(item)
728
+
729
+ # API calls in files no page imports (hooks, stores, services) belong to the app itself
730
+ app_calls = []
731
+ for dirpath, files in walk(fe["root"]):
732
+ for f in files:
733
+ path = os.path.join(dirpath, f)
734
+ if not f.endswith(JS_EXT) or path in attributed:
735
+ continue
736
+ for c in extract_calls(path):
737
+ ep = match_endpoint(c["path"], endpoints)
738
+ if ep:
739
+ app_calls.append({"endpoint": ep["id"], "method": c["method"], "file": rel(c["file"], target), "line": c["line"]})
740
+
741
+ service = {
742
+ "id": sid,
743
+ "name": fe["name"],
744
+ "type": "frontend",
745
+ "subtype": fe["type"],
746
+ "root": rel(fe["root"], target),
747
+ "calls": _dedupe_links(app_calls),
748
+ }
749
+ # v1 compatibility for the VS Code webview
750
+ if fe["type"] == "web":
751
+ service["pages"] = [p for p in pages_out if p["service"] == sid]
752
+ else:
753
+ service["screens"] = [p for p in pages_out if p["service"] == sid]
754
+ services.append(service)
755
+
756
+ if django_root:
757
+ services.append({"id": "backend", "name": "Django API", "type": "backend",
758
+ "root": rel(django_root, target)})
759
+ if db:
760
+ services.append({"id": "database", "name": db, "type": "database"})
761
+ stack.add(db)
762
+
763
+ for m in models:
764
+ m["id"] = "model:" + m["name"]
765
+ m["file"] = rel(m["file"], target)
766
+
767
+ for ep in endpoints:
768
+ ep.pop("_key", None)
769
+ ep["groupOrder"] = 0
770
+ ep["type"] = ep.pop("kind")
771
+
772
+ edges = []
773
+ for p in pages_out:
774
+ for c in p["calls"]:
775
+ edges.append({"source": p["id"], "target": c["endpoint"], "kind": "calls", "method": c["method"]})
776
+ for s in services:
777
+ for c in s.get("calls", []):
778
+ edges.append({"source": s["id"], "target": c["endpoint"], "kind": "calls", "method": c["method"]})
779
+ for ep in endpoints:
780
+ for mname in ep["models"]:
781
+ edges.append({"source": ep["id"], "target": "model:" + mname, "kind": "uses"})
782
+ names = {m["name"] for m in models}
783
+ for m in models:
784
+ for r in m["relations"]:
785
+ if r["target"] in names and r["target"] != m["name"]:
786
+ edges.append({"source": m["id"], "target": "model:" + r["target"], "kind": "relation", "field": r["field"]})
787
+
788
+ return {
789
+ "schema": SCHEMA_VERSION,
790
+ "root": target,
791
+ "project": os.path.basename(target),
792
+ "stack": sorted(stack),
793
+ "services": services,
794
+ "pages": pages_out,
795
+ "endpoints": endpoints,
796
+ "models": models,
797
+ "edges": edges,
798
+ "unmatchedCalls": unmatched[:50],
799
+ }
800
+
801
+
802
+ def _dedupe_links(links: list[dict[str, Any]]) -> list[dict[str, Any]]:
803
+ seen: set[tuple[str, str]] = set()
804
+ out = []
805
+ for link in links:
806
+ key = (link["endpoint"], link["method"])
807
+ if key not in seen:
808
+ seen.add(key)
809
+ out.append(link)
810
+ return out
811
+
812
+
813
+ def main() -> None:
814
+ if len(sys.argv) < 2:
815
+ print(json.dumps({"error": "Usage: parser.py <project_root>"}))
816
+ sys.exit(1)
817
+ target = sys.argv[1]
818
+ if not os.path.isdir(target):
819
+ print(json.dumps({"error": f"Directory not found: {target}"}))
820
+ sys.exit(1)
821
+ print(json.dumps(scan(target), ensure_ascii=False, indent=2))
822
+
823
+
824
+ if __name__ == "__main__":
825
+ main()