@xand0dev/traceflow 0.0.0-stage → 0.2.1

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