rk147 commited on
Commit
70e736e
Β·
verified Β·
1 Parent(s): 4567c9a

Update app/utils/map_builder.py

Browse files
Files changed (1) hide show
  1. app/utils/map_builder.py +157 -195
app/utils/map_builder.py CHANGED
@@ -1,7 +1,7 @@
1
  """
2
- Map builder β€” static AST analysis to produce a call/flow graph.
3
- Python: uses ast module (accurate).
4
- Other languages: LLM fallback (best-effort).
5
  """
6
 
7
  import ast
@@ -11,22 +11,33 @@ from typing import List, Dict, Optional
11
  from groq import Groq
12
  from app.config import GROQ_API_KEY, MODEL_NAME, MAX_TOKENS
13
 
 
 
 
 
 
 
 
 
 
 
 
14
 
15
  @dataclass
16
  class GraphNode:
17
  id: str
18
  label: str
19
- kind: str # function | class | entry | dead | external | branch | loop | exception
20
  file: str
21
  line: int
22
- docstring: str = ""
23
 
24
 
25
  @dataclass
26
  class GraphEdge:
27
  source: str
28
  target: str
29
- kind: str # calls | returns | branch_true | branch_false | loop | exception | imports
30
 
31
 
32
  @dataclass
@@ -45,68 +56,64 @@ class CallGraph:
45
  }
46
 
47
 
48
- # ── Python AST analyzer ──────────────────────────────────────────────────────
49
 
50
  class _PythonVisitor(ast.NodeVisitor):
51
- def __init__(self, filename: str):
52
  self.filename = filename
 
53
  self.nodes: List[GraphNode] = []
54
  self.edges: List[GraphEdge] = []
55
  self._scope_stack: List[str] = []
56
  self._defined: set = set()
57
- self._called: set = set()
58
-
59
- def _current_scope(self) -> Optional[str]:
60
- return self._scope_stack[-1] if self._scope_stack else None
61
 
62
- def _node_id(self, name: str) -> str:
63
  return f"{self.filename}::{name}"
64
 
 
 
 
65
  def visit_FunctionDef(self, node):
66
- nid = self._node_id(node.name)
67
- self._defined.add(node.name)
 
68
  doc = ast.get_docstring(node) or ""
69
  self.nodes.append(GraphNode(
70
- id=nid,
71
- label=node.name,
72
- kind="function",
73
- file=self.filename,
74
- line=node.lineno,
75
- docstring=doc[:120],
76
  ))
77
- if self._current_scope():
78
- self.edges.append(GraphEdge(
79
- source=self._node_id(self._current_scope()),
80
- target=nid,
81
- kind="calls",
82
- ))
83
- self._scope_stack.append(node.name)
84
  self.generic_visit(node)
85
  self._scope_stack.pop()
86
 
87
  visit_AsyncFunctionDef = visit_FunctionDef
88
 
89
  def visit_ClassDef(self, node):
90
- nid = self._node_id(node.name)
91
- self._defined.add(node.name)
 
 
92
  self.nodes.append(GraphNode(
93
- id=nid,
94
- label=node.name,
95
- kind="class",
96
- file=self.filename,
97
- line=node.lineno,
98
  ))
99
- self._scope_stack.append(node.name)
100
  self.generic_visit(node)
101
  self._scope_stack.pop()
102
 
103
  def visit_Call(self, node):
104
- scope = self._current_scope()
105
  if not scope:
106
  self.generic_visit(node)
107
  return
108
 
109
- # Resolve function name
110
  if isinstance(node.func, ast.Name):
111
  callee = node.func.id
112
  elif isinstance(node.func, ast.Attribute):
@@ -115,136 +122,44 @@ class _PythonVisitor(ast.NodeVisitor):
115
  self.generic_visit(node)
116
  return
117
 
118
- self._called.add(callee)
119
- target_id = self._node_id(callee)
 
 
 
 
 
120
 
121
- # Add external node if not defined locally
122
  if callee not in self._defined:
123
  if not any(n.id == target_id for n in self.nodes):
124
  self.nodes.append(GraphNode(
125
- id=target_id,
126
- label=callee,
127
- kind="external",
128
- file=self.filename,
129
- line=getattr(node, "lineno", 0),
130
- ))
131
-
132
- self.edges.append(GraphEdge(
133
- source=self._node_id(scope),
134
- target=target_id,
135
- kind="calls",
136
- ))
137
- self.generic_visit(node)
138
-
139
- def visit_If(self, node):
140
- scope = self._current_scope()
141
- if scope:
142
- branch_id = f"{self.filename}::if_L{node.lineno}"
143
- self.nodes.append(GraphNode(
144
- id=branch_id,
145
- label=f"if (line {node.lineno})",
146
- kind="branch",
147
- file=self.filename,
148
- line=node.lineno,
149
- ))
150
- self.edges.append(GraphEdge(
151
- source=self._node_id(scope),
152
- target=branch_id,
153
- kind="branch_true",
154
- ))
155
- if node.orelse:
156
- else_id = f"{self.filename}::else_L{node.lineno}"
157
- self.nodes.append(GraphNode(
158
- id=else_id,
159
- label=f"else (line {node.lineno})",
160
- kind="branch",
161
- file=self.filename,
162
- line=node.lineno,
163
- ))
164
- self.edges.append(GraphEdge(
165
- source=self._node_id(scope),
166
- target=else_id,
167
- kind="branch_false",
168
  ))
169
- self.generic_visit(node)
170
 
171
- def visit_For(self, node):
172
- self._add_loop_node("for", node)
173
- self.generic_visit(node)
174
-
175
- def visit_While(self, node):
176
- self._add_loop_node("while", node)
177
- self.generic_visit(node)
178
-
179
- def _add_loop_node(self, kind: str, node):
180
- scope = self._current_scope()
181
- if scope:
182
- loop_id = f"{self.filename}::{kind}_L{node.lineno}"
183
- self.nodes.append(GraphNode(
184
- id=loop_id,
185
- label=f"{kind} loop (line {node.lineno})",
186
- kind="loop",
187
- file=self.filename,
188
- line=node.lineno,
189
- ))
190
- self.edges.append(GraphEdge(
191
- source=self._node_id(scope),
192
- target=loop_id,
193
- kind="loop",
194
- ))
195
-
196
- def visit_ExceptHandler(self, node):
197
- scope = self._current_scope()
198
- if scope:
199
- exc_id = f"{self.filename}::except_L{node.lineno}"
200
- exc_type = node.type.id if isinstance(node.type, ast.Name) else "Exception"
201
- self.nodes.append(GraphNode(
202
- id=exc_id,
203
- label=f"except {exc_type} (line {node.lineno})",
204
- kind="exception",
205
- file=self.filename,
206
- line=node.lineno,
207
- ))
208
- self.edges.append(GraphEdge(
209
- source=self._node_id(scope),
210
- target=exc_id,
211
- kind="exception",
212
- ))
213
- self.generic_visit(node)
214
 
215
- def visit_Import(self, node):
216
- for alias in node.names:
217
- imp_id = self._node_id(f"import::{alias.name}")
218
- if not any(n.id == imp_id for n in self.nodes):
219
- self.nodes.append(GraphNode(
220
- id=imp_id,
221
- label=alias.name,
222
- kind="external",
223
- file=self.filename,
224
- line=node.lineno,
225
- ))
226
  self.generic_visit(node)
227
 
228
- def find_dead_code(self):
229
- """Mark functions defined but never called as dead."""
 
230
  for node in self.nodes:
231
- if node.kind == "function" and node.label not in self._called:
232
- # Check it's not an entry point (called from top level)
233
- has_incoming = any(
234
- e.target == node.id for e in self.edges
235
- if e.kind == "calls"
236
- )
237
- if not has_incoming:
238
- node.kind = "entry" # top-level callable = entry point
239
 
240
 
241
  def _analyze_python(filename: str, code: str) -> CallGraph:
242
  graph = CallGraph()
243
  try:
244
  tree = ast.parse(code)
245
- visitor = _PythonVisitor(filename)
246
  visitor.visit(tree)
247
- visitor.find_dead_code()
248
  graph.nodes = visitor.nodes
249
  graph.edges = visitor.edges
250
  except SyntaxError as e:
@@ -252,27 +167,25 @@ def _analyze_python(filename: str, code: str) -> CallGraph:
252
  return graph
253
 
254
 
255
- # ── LLM fallback for non-Python ─────────────────────────────────────────────
256
 
257
  def _analyze_llm_fallback(filename: str, code: str, language: str) -> CallGraph:
258
  graph = CallGraph()
259
  try:
260
  client = Groq(api_key=GROQ_API_KEY)
261
- prompt = f"""Analyze this {language} code and return ONLY a JSON object with:
262
  {{
263
- "nodes": [
264
- {{"id": "unique_id", "label": "name", "kind": "function|class|entry|external|branch|loop|exception", "line": 1}}
265
- ],
266
- "edges": [
267
- {{"source": "id1", "target": "id2", "kind": "calls|branch_true|branch_false|loop|exception|imports"}}
268
- ]
269
  }}
 
 
270
 
271
  File: {filename}
272
  Code:
273
  {code[:3000]}
274
 
275
- JSON only, no markdown:"""
276
 
277
  resp = client.chat.completions.create(
278
  model=MODEL_NAME,
@@ -281,22 +194,22 @@ JSON only, no markdown:"""
281
  temperature=0.1,
282
  )
283
  text = resp.choices[0].message.content.strip()
284
- start = text.find("{")
285
- end = text.rfind("}") + 1
286
  if start >= 0 and end > start:
287
  data = json.loads(text[start:end])
288
  for n in data.get("nodes", []):
289
  graph.nodes.append(GraphNode(
290
- id=f"{filename}::{n.get('id', '')}",
291
  label=n.get("label", ""),
292
  kind=n.get("kind", "function"),
293
  file=filename,
294
  line=n.get("line", 0),
 
295
  ))
296
  for e in data.get("edges", []):
297
  graph.edges.append(GraphEdge(
298
- source=f"{filename}::{e.get('source', '')}",
299
- target=f"{filename}::{e.get('target', '')}",
300
  kind=e.get("kind", "calls"),
301
  ))
302
  except Exception as ex:
@@ -304,38 +217,77 @@ JSON only, no markdown:"""
304
  return graph
305
 
306
 
307
- # ── LLM narrative ────────────────────────────────────────────────────────────
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
308
 
309
- def _generate_narrative(graph: CallGraph, files: dict) -> str:
310
  try:
311
  client = Groq(api_key=GROQ_API_KEY)
312
- node_summary = "\n".join(
313
- f"- {n.label} ({n.kind}) in {n.file} line {n.line}"
314
- for n in graph.nodes[:30]
315
- )
316
- edge_summary = "\n".join(
317
- f"- {e.source.split('::')[-1]} β†’ {e.target.split('::')[-1]} [{e.kind}]"
318
- for e in graph.edges[:30]
 
 
 
 
 
319
  )
320
- prompt = f"""Given this code call graph, write a concise plain-English narrative explaining:
321
- 1. What the entry points are and what they do
322
- 2. The main execution flow (A calls B which calls C...)
323
- 3. Key branching and decision points
324
- 4. Any notable loops, recursion, or exception handling
325
- 5. What the code achieves overall
 
 
 
326
 
327
- Nodes:
328
- {node_summary}
329
 
330
- Edges:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
331
  {edge_summary}
332
 
333
- Narrative (3-6 sentences, plain English):"""
334
 
335
  resp = client.chat.completions.create(
336
  model=MODEL_NAME,
337
  messages=[{"role": "user", "content": prompt}],
338
- max_tokens=512,
339
  temperature=0.3,
340
  )
341
  return resp.choices[0].message.content.strip()
@@ -343,17 +295,13 @@ Narrative (3-6 sentences, plain English):"""
343
  return f"Could not generate narrative: {e}"
344
 
345
 
346
- # ── Public API ───────────────────────────────────────────────────────────────
347
 
348
  def build_graph(files: dict) -> CallGraph:
349
  """
350
- Build a combined call graph for all files.
351
-
352
  Args:
353
- files: dict of {filename: (code_text, language)}
354
-
355
- Returns:
356
- CallGraph with all nodes, edges, and narrative
357
  """
358
  from app.modules.language_detector import detect_language
359
 
@@ -368,7 +316,7 @@ def build_graph(files: dict) -> CallGraph:
368
  combined.edges.extend(g.edges)
369
  combined.errors.extend(g.errors)
370
 
371
- # Deduplicate nodes by id
372
  seen = set()
373
  deduped = []
374
  for n in combined.nodes:
@@ -377,7 +325,21 @@ def build_graph(files: dict) -> CallGraph:
377
  deduped.append(n)
378
  combined.nodes = deduped
379
 
380
- # Generate narrative
381
- combined.narrative = _generate_narrative(combined, files)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
382
 
383
  return combined
 
1
  """
2
+ Map builder β€” clean call graph.
3
+ Only tracks functions and classes (no branches/loops/exceptions β€” those are noise).
4
+ Generates per-node LLM descriptions for tooltips.
5
  """
6
 
7
  import ast
 
11
  from groq import Groq
12
  from app.config import GROQ_API_KEY, MODEL_NAME, MAX_TOKENS
13
 
14
+ NOISE_BUILTINS = {
15
+ "print", "len", "range", "append", "extend", "str", "int", "float",
16
+ "list", "dict", "set", "tuple", "isinstance", "hasattr", "getattr",
17
+ "setattr", "enumerate", "zip", "map", "filter", "sorted", "reversed",
18
+ "open", "format", "repr", "type", "super", "staticmethod", "classmethod",
19
+ "property", "encode", "decode", "strip", "split", "join", "lower",
20
+ "upper", "replace", "get", "keys", "values", "items", "update", "pop",
21
+ "insert", "remove", "index", "count", "copy", "clear", "write", "read",
22
+ "close", "next", "iter", "vars", "dir", "id", "hash", "abs", "round",
23
+ }
24
+
25
 
26
  @dataclass
27
  class GraphNode:
28
  id: str
29
  label: str
30
+ kind: str # function | class | entry | external
31
  file: str
32
  line: int
33
+ description: str = "" # LLM-generated 1-liner
34
 
35
 
36
  @dataclass
37
  class GraphEdge:
38
  source: str
39
  target: str
40
+ kind: str # calls | imports
41
 
42
 
43
  @dataclass
 
56
  }
57
 
58
 
59
+ # ── Python AST ────────────────────────────────────────────────────────────────
60
 
61
  class _PythonVisitor(ast.NodeVisitor):
62
+ def __init__(self, filename: str, code: str):
63
  self.filename = filename
64
+ self.code = code
65
  self.nodes: List[GraphNode] = []
66
  self.edges: List[GraphEdge] = []
67
  self._scope_stack: List[str] = []
68
  self._defined: set = set()
69
+ self._called_from: Dict[str, set] = {} # callee -> set of callers
 
 
 
70
 
71
+ def _id(self, name: str) -> str:
72
  return f"{self.filename}::{name}"
73
 
74
+ def _scope(self) -> Optional[str]:
75
+ return self._scope_stack[-1] if self._scope_stack else None
76
+
77
  def visit_FunctionDef(self, node):
78
+ name = node.name
79
+ nid = self._id(name)
80
+ self._defined.add(name)
81
  doc = ast.get_docstring(node) or ""
82
  self.nodes.append(GraphNode(
83
+ id=nid, label=name, kind="function",
84
+ file=self.filename, line=node.lineno,
85
+ description=doc[:100],
 
 
 
86
  ))
87
+ parent = self._scope()
88
+ if parent:
89
+ self.edges.append(GraphEdge(source=self._id(parent), target=nid, kind="calls"))
90
+ self._called_from.setdefault(name, set()).add(parent)
91
+ self._scope_stack.append(name)
 
 
92
  self.generic_visit(node)
93
  self._scope_stack.pop()
94
 
95
  visit_AsyncFunctionDef = visit_FunctionDef
96
 
97
  def visit_ClassDef(self, node):
98
+ name = node.name
99
+ nid = self._id(name)
100
+ self._defined.add(name)
101
+ doc = ast.get_docstring(node) or ""
102
  self.nodes.append(GraphNode(
103
+ id=nid, label=name, kind="class",
104
+ file=self.filename, line=node.lineno,
105
+ description=doc[:100],
 
 
106
  ))
107
+ self._scope_stack.append(name)
108
  self.generic_visit(node)
109
  self._scope_stack.pop()
110
 
111
  def visit_Call(self, node):
112
+ scope = self._scope()
113
  if not scope:
114
  self.generic_visit(node)
115
  return
116
 
 
117
  if isinstance(node.func, ast.Name):
118
  callee = node.func.id
119
  elif isinstance(node.func, ast.Attribute):
 
122
  self.generic_visit(node)
123
  return
124
 
125
+ # Skip noise builtins and dunder methods
126
+ if callee in NOISE_BUILTINS or callee.startswith("__"):
127
+ self.generic_visit(node)
128
+ return
129
+
130
+ target_id = self._id(callee)
131
+ self._called_from.setdefault(callee, set()).add(scope)
132
 
133
+ # Only add external node if it's a meaningful call not defined locally
134
  if callee not in self._defined:
135
  if not any(n.id == target_id for n in self.nodes):
136
  self.nodes.append(GraphNode(
137
+ id=target_id, label=callee, kind="external",
138
+ file=self.filename, line=getattr(node, "lineno", 0),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
139
  ))
 
140
 
141
+ # Avoid duplicate edges
142
+ edge = GraphEdge(source=self._id(scope), target=target_id, kind="calls")
143
+ if not any(e.source == edge.source and e.target == edge.target for e in self.edges):
144
+ self.edges.append(edge)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
145
 
 
 
 
 
 
 
 
 
 
 
 
146
  self.generic_visit(node)
147
 
148
+ def resolve_entry_points(self):
149
+ """Functions not called by anything else = entry points."""
150
+ all_targets = {e.target for e in self.edges}
151
  for node in self.nodes:
152
+ if node.kind == "function" and node.id not in all_targets:
153
+ node.kind = "entry"
 
 
 
 
 
 
154
 
155
 
156
  def _analyze_python(filename: str, code: str) -> CallGraph:
157
  graph = CallGraph()
158
  try:
159
  tree = ast.parse(code)
160
+ visitor = _PythonVisitor(filename, code)
161
  visitor.visit(tree)
162
+ visitor.resolve_entry_points()
163
  graph.nodes = visitor.nodes
164
  graph.edges = visitor.edges
165
  except SyntaxError as e:
 
167
  return graph
168
 
169
 
170
+ # ── LLM fallback for non-Python ───────────────────────────────────────────────
171
 
172
  def _analyze_llm_fallback(filename: str, code: str, language: str) -> CallGraph:
173
  graph = CallGraph()
174
  try:
175
  client = Groq(api_key=GROQ_API_KEY)
176
+ prompt = f"""Analyze this {language} code. Return ONLY a JSON object:
177
  {{
178
+ "nodes": [{{"id": "unique_id", "label": "name", "kind": "function|class|entry|external", "line": 1, "description": "one line what it does"}}],
179
+ "edges": [{{"source": "id1", "target": "id2", "kind": "calls|imports"}}]
 
 
 
 
180
  }}
181
+ Only include functions and classes β€” NO branches, loops, or exception handlers as nodes.
182
+ Skip trivial utility calls (print, len, append etc).
183
 
184
  File: {filename}
185
  Code:
186
  {code[:3000]}
187
 
188
+ JSON only:"""
189
 
190
  resp = client.chat.completions.create(
191
  model=MODEL_NAME,
 
194
  temperature=0.1,
195
  )
196
  text = resp.choices[0].message.content.strip()
197
+ start, end = text.find("{"), text.rfind("}") + 1
 
198
  if start >= 0 and end > start:
199
  data = json.loads(text[start:end])
200
  for n in data.get("nodes", []):
201
  graph.nodes.append(GraphNode(
202
+ id=f"{filename}::{n.get('id','')}",
203
  label=n.get("label", ""),
204
  kind=n.get("kind", "function"),
205
  file=filename,
206
  line=n.get("line", 0),
207
+ description=n.get("description", ""),
208
  ))
209
  for e in data.get("edges", []):
210
  graph.edges.append(GraphEdge(
211
+ source=f"{filename}::{e.get('source','')}",
212
+ target=f"{filename}::{e.get('target','')}",
213
  kind=e.get("kind", "calls"),
214
  ))
215
  except Exception as ex:
 
217
  return graph
218
 
219
 
220
+ # ── LLM node descriptions (batch) ────────────────────────────────────────────
221
+
222
+ def _generate_descriptions(nodes: List[GraphNode], files: dict) -> List[GraphNode]:
223
+ """
224
+ For nodes without a description (or with only a docstring),
225
+ generate a clean 1-line description via LLM in one batched call.
226
+ """
227
+ needs_desc = [n for n in nodes if not n.description and n.kind in ("function", "class", "entry")]
228
+ if not needs_desc:
229
+ return nodes
230
+
231
+ # Build code snippets for each
232
+ snippets = []
233
+ for n in needs_desc[:20]: # cap at 20 to avoid huge prompt
234
+ code, _ = files.get(n.file, ("", ""))
235
+ lines = code.split("\n")
236
+ start = max(0, n.line - 1)
237
+ snippet = "\n".join(lines[start:start + 8])
238
+ snippets.append(f"name: {n.label}\n```\n{snippet}\n```")
239
 
 
240
  try:
241
  client = Groq(api_key=GROQ_API_KEY)
242
+ prompt = f"""For each function/class below, write exactly ONE sentence (max 12 words) describing what it does.
243
+ Return ONLY a JSON array of strings in the same order as the input.
244
+
245
+ {chr(10).join(f'{i+1}. {s}' for i, s in enumerate(snippets))}
246
+
247
+ JSON array:"""
248
+
249
+ resp = client.chat.completions.create(
250
+ model=MODEL_NAME,
251
+ messages=[{"role": "user", "content": prompt}],
252
+ max_tokens=800,
253
+ temperature=0.2,
254
  )
255
+ text = resp.choices[0].message.content.strip()
256
+ start_i = text.find("[")
257
+ end_i = text.rfind("]") + 1
258
+ if start_i >= 0 and end_i > start_i:
259
+ descriptions = json.loads(text[start_i:end_i])
260
+ for i, n in enumerate(needs_desc[:len(descriptions)]):
261
+ n.description = descriptions[i] if i < len(descriptions) else ""
262
+ except Exception:
263
+ pass
264
 
265
+ return nodes
 
266
 
267
+
268
+ # ── Narrative ─────────────────────────────────────────────────────────────────
269
+
270
+ def _generate_narrative(graph: CallGraph) -> str:
271
+ try:
272
+ client = Groq(api_key=GROQ_API_KEY)
273
+ entries = [n for n in graph.nodes if n.kind == "entry"]
274
+ funcs = [n for n in graph.nodes if n.kind in ("function", "class")]
275
+ edge_summary = "\n".join(
276
+ f" {e.source.split('::')[-1]} β†’ {e.target.split('::')[-1]}"
277
+ for e in graph.edges[:40] if e.kind == "calls"
278
+ )
279
+ prompt = f"""Given this code call graph, write a concise plain-English flow narrative (4-6 sentences):
280
+ - Entry points: {', '.join(n.label for n in entries[:8])}
281
+ - Functions/classes: {', '.join(n.label for n in funcs[:20])}
282
+ - Call flow:
283
  {edge_summary}
284
 
285
+ Explain: what starts execution, the main flow, key dependencies. Plain English only:"""
286
 
287
  resp = client.chat.completions.create(
288
  model=MODEL_NAME,
289
  messages=[{"role": "user", "content": prompt}],
290
+ max_tokens=400,
291
  temperature=0.3,
292
  )
293
  return resp.choices[0].message.content.strip()
 
295
  return f"Could not generate narrative: {e}"
296
 
297
 
298
+ # ── Public API ────────────────────────────────────────────────────────────────
299
 
300
  def build_graph(files: dict) -> CallGraph:
301
  """
302
+ Build a clean call graph.
 
303
  Args:
304
+ files: {filename: (code_text, language)}
 
 
 
305
  """
306
  from app.modules.language_detector import detect_language
307
 
 
316
  combined.edges.extend(g.edges)
317
  combined.errors.extend(g.errors)
318
 
319
+ # Deduplicate nodes
320
  seen = set()
321
  deduped = []
322
  for n in combined.nodes:
 
325
  deduped.append(n)
326
  combined.nodes = deduped
327
 
328
+ # Remove orphan externals (external nodes with no incoming edges from defined functions)
329
+ defined_ids = {n.id for n in combined.nodes if n.kind != "external"}
330
+ has_incoming_from_defined = set()
331
+ for e in combined.edges:
332
+ if e.source in defined_ids:
333
+ has_incoming_from_defined.add(e.target)
334
+ combined.nodes = [
335
+ n for n in combined.nodes
336
+ if n.kind != "external" or n.id in has_incoming_from_defined
337
+ ]
338
+
339
+ # Generate descriptions
340
+ combined.nodes = _generate_descriptions(combined.nodes, files)
341
+
342
+ # Narrative
343
+ combined.narrative = _generate_narrative(combined)
344
 
345
  return combined