codegraphx 0.1.0__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.
Files changed (44) hide show
  1. codegraph/__init__.py +37 -0
  2. codegraph/cli.py +106 -0
  3. codegraph/commands/__init__.py +1 -0
  4. codegraph/commands/conflicts.py +154 -0
  5. codegraph/commands/diff.py +189 -0
  6. codegraph/commands/export.py +141 -0
  7. codegraph/commands/graph.py +200 -0
  8. codegraph/commands/index.py +924 -0
  9. codegraph/commands/serve.py +62 -0
  10. codegraph/commands/why.py +645 -0
  11. codegraph/decisions/__init__.py +18 -0
  12. codegraph/decisions/conflicts.py +238 -0
  13. codegraph/decisions/extractor.py +698 -0
  14. codegraph/decisions/llm_extractor.py +161 -0
  15. codegraph/decisions/sources.py +298 -0
  16. codegraph/git/__init__.py +5 -0
  17. codegraph/git/diff.py +115 -0
  18. codegraph/git/history.py +156 -0
  19. codegraph/git/incremental.py +75 -0
  20. codegraph/git/refs.py +70 -0
  21. codegraph/models.py +211 -0
  22. codegraph/parser/__init__.py +1 -0
  23. codegraph/parser/base.py +164 -0
  24. codegraph/parser/common.py +147 -0
  25. codegraph/parser/parallel.py +96 -0
  26. codegraph/parser/registry.py +83 -0
  27. codegraph/parser/treesitter_cpp.py +102 -0
  28. codegraph/parser/treesitter_go.py +113 -0
  29. codegraph/parser/treesitter_java.py +79 -0
  30. codegraph/parser/treesitter_js.py +15 -0
  31. codegraph/parser/treesitter_py.py +163 -0
  32. codegraph/parser/treesitter_rust.py +120 -0
  33. codegraph/parser/treesitter_ts.py +178 -0
  34. codegraph/storage.py +767 -0
  35. codegraph/web/__init__.py +1 -0
  36. codegraph/web/app.py +271 -0
  37. codegraph/web/static/app.js +356 -0
  38. codegraph/web/static/index.html +59 -0
  39. codegraph/web/static/styles.css +92 -0
  40. codegraphx-0.1.0.dist-info/METADATA +262 -0
  41. codegraphx-0.1.0.dist-info/RECORD +44 -0
  42. codegraphx-0.1.0.dist-info/WHEEL +4 -0
  43. codegraphx-0.1.0.dist-info/entry_points.txt +2 -0
  44. codegraphx-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,924 @@
1
+ """codegraph index: parse sources across Git history and persist the graph."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import re
7
+ from datetime import datetime, timezone
8
+ from pathlib import Path
9
+
10
+ import typer
11
+ from rich.console import Console
12
+ from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
13
+
14
+ from codegraph.decisions.sources import extract_all
15
+ from codegraph.git.diff import get_changed_lines
16
+ from codegraph.git.history import CommitInfo, GitHistory
17
+ from codegraph.models import (
18
+ CodeNode,
19
+ Decision,
20
+ DecisionTier,
21
+ Edge,
22
+ normalize_location_path,
23
+ )
24
+ from codegraph.parser.base import BaseParser
25
+ from codegraph.parser.registry import get_parser_for_path, is_supported_source
26
+ from codegraph.storage import (
27
+ clear_graph,
28
+ connect,
29
+ count_decisions,
30
+ count_edges,
31
+ count_nodes,
32
+ db_path_for_root,
33
+ init_schema,
34
+ insert_decision_links,
35
+ insert_decisions,
36
+ insert_edges,
37
+ insert_nodes,
38
+ load_edges,
39
+ load_nodes,
40
+ replace_graph_rows,
41
+ )
42
+
43
+ console = Console()
44
+ logger = logging.getLogger(__name__)
45
+
46
+ MAX_CHANGED_LINES = 1000 # skip line-binding on huge diffs
47
+
48
+ # A decision that claims thousands of lines is not a line-level fact.
49
+ MAX_BINDING_FILES = 10
50
+ MAX_BINDING_LINES = 250
51
+
52
+ # Governed (ADR-style) binding stays deliberately small.
53
+ MAX_GOVERNED_FILES = 12
54
+ MAX_GOVERNED_NODES_PER_FILE = 60
55
+ MAX_GOVERNED_NODES = 200
56
+
57
+ GOVERNS_FRONT_MATTER = re.compile(r"^\s*governs\s*:\s*(?P<paths>.+)$", re.IGNORECASE | re.MULTILINE)
58
+ GOVERNS_COMMENT = re.compile(
59
+ r"<!--\s*governs?\s*:\s*(?P<paths>.*?)\s*-->", re.IGNORECASE | re.DOTALL
60
+ )
61
+ BACKTICKED_PATH = re.compile(
62
+ r"`{1,2}([A-Za-z0-9_./-]+\.(?:py|ts|tsx|js|mjs|cjs|java|go|rs|cpp|cc|cxx|hpp|hh|hxx|h))`{1,2}"
63
+ )
64
+ # reStructuredText marks a literal with double backticks (``redirect``), markdown
65
+ # with one. Matching only the single form meant a Python project's changelog —
66
+ # Flask writes everything as ``name`` — bound far less than it should.
67
+ BACKTICKED_IDENT = re.compile(r"`{1,2}([A-Za-z_][A-Za-z0-9_.]*)`{1,2}")
68
+
69
+
70
+ def is_distinctive_identifier(ident: str) -> bool:
71
+ """True when a backticked word is specific enough to identify code.
72
+
73
+ Stops prose words like `index` or `decision` from binding an ADR to random
74
+ symbols.
75
+ """
76
+ if len(ident) < 6:
77
+ return False
78
+ return "_" in ident or ident[0].isupper() or len(ident) >= 10
79
+
80
+ SKIP_DIRS = {
81
+ "node_modules",
82
+ ".git",
83
+ "dist",
84
+ "build",
85
+ ".venv",
86
+ "venv",
87
+ "__pycache__",
88
+ ".codegraph",
89
+ ".pytest_cache",
90
+ ".mypy_cache",
91
+ ".ruff_cache",
92
+ "target",
93
+ ".cargo",
94
+ "vendor",
95
+ }
96
+
97
+ INDEX_STEPS: list[str] = [
98
+ "Walk Git history",
99
+ "Parse snapshots with tree-sitter",
100
+ "Extract decisions from commits/ADRs",
101
+ "Write graph store",
102
+ ]
103
+
104
+
105
+ def resolve_repo_path(path: Path) -> Path:
106
+ """Resolve and validate the repository path."""
107
+ target = path.expanduser().resolve()
108
+ if not target.exists():
109
+ raise typer.BadParameter(f"Path not found: {path}")
110
+ return target
111
+
112
+
113
+ def is_skipped_path(root: Path, file_path: str) -> bool:
114
+ """Return True when a repo-relative path should be ignored."""
115
+ parts = Path(file_path).parts
116
+ return any(part in SKIP_DIRS for part in parts)
117
+
118
+
119
+ def parse_source_text(path_str: str, text: str) -> tuple[list[CodeNode], list[Edge]]:
120
+ """Parse in-memory source text into nodes and edges."""
121
+ parser = get_parser_for_path(Path(path_str))
122
+ if parser is None:
123
+ return [], []
124
+ # Tree-sitter parsers read from disk; use a side channel via monkeypatch-like temp parse.
125
+ nodes = parser.parse_text(path_str, text) if hasattr(parser, "parse_text") else []
126
+ edges = parser.extract_edges(nodes) if nodes else []
127
+ return nodes, edges
128
+
129
+
130
+ def _node_source(text: str, node: CodeNode) -> str:
131
+ """Return the source lines a node version covers."""
132
+ lines = text.splitlines()
133
+ return "\n".join(lines[node.line_start - 1 : node.line_end])
134
+
135
+
136
+ def _as_utc(value: datetime) -> datetime:
137
+ """Return a timezone-aware datetime so versions can be compared."""
138
+ return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
139
+
140
+
141
+ def _has_unchanged_live_version(
142
+ versions: list[CodeNode],
143
+ node: CodeNode,
144
+ text: str,
145
+ history,
146
+ rel_path: str,
147
+ text_cache: dict[tuple[str, str], str],
148
+ commit_timestamp: datetime | None = None,
149
+ ) -> bool:
150
+ """True when this commit must not open a new version of the symbol.
151
+
152
+ Two cases:
153
+
154
+ * a live version already covers the same range *and* the same source text, so
155
+ the symbol did not change;
156
+ * a live version was created by a **later** commit. This happens when history
157
+ is re-read after an amend, rebase or reset, and the stored graph is already
158
+ newer than the commit being ingested. Opening a version for the older
159
+ commit would close the newer one at an earlier instant and invert the
160
+ timeline.
161
+ """
162
+ for prev in versions:
163
+ if prev.valid_to is not None:
164
+ continue
165
+ if commit_timestamp is not None and _as_utc(prev.valid_from) > _as_utc(
166
+ commit_timestamp
167
+ ):
168
+ return True
169
+ if prev.line_start != node.line_start or prev.line_end != node.line_end:
170
+ continue
171
+ if prev.commit_sha == node.commit_sha:
172
+ return True
173
+ cache_key = (prev.commit_sha, rel_path)
174
+ prev_text = text_cache.get(cache_key)
175
+ if prev_text is None:
176
+ prev_text = history.get_file_at_commit(prev.commit_sha, rel_path)
177
+ text_cache[cache_key] = prev_text
178
+ if prev_text and _node_source(prev_text, prev) == _node_source(text, node):
179
+ return True
180
+ return False
181
+
182
+
183
+ def close_previous_versions(
184
+ live: dict[tuple[str, str], list[CodeNode]],
185
+ key: tuple[str, str],
186
+ when: datetime,
187
+ ) -> None:
188
+ """Set valid_to on open node versions for a (file, name) key."""
189
+ for node in live.get(key, []):
190
+ if node.valid_to is None:
191
+ node.valid_to = when
192
+
193
+
194
+ def _live_nodes(live: dict[tuple[str, str], list[CodeNode]]) -> list[CodeNode]:
195
+ """Return every currently live node version."""
196
+ return [
197
+ node
198
+ for versions in live.values()
199
+ for node in versions
200
+ if node.valid_to is None
201
+ ]
202
+
203
+
204
+ def ingest_commit(
205
+ history: GitHistory,
206
+ commit: CommitInfo,
207
+ live: dict[tuple[str, str], list[CodeNode]],
208
+ all_nodes: list[CodeNode],
209
+ all_edges: list[Edge],
210
+ text_cache: dict[tuple[str, str], str] | None = None,
211
+ ) -> None:
212
+ """Parse changed source files at one commit and version nodes.
213
+
214
+ Nodes are versioned first, then call edges are resolved against every symbol
215
+ live at this commit — including symbols introduced by the same commit in
216
+ another file. Resolving per file would drop cross-file calls, and the
217
+ working-tree path already resolves them, so the two would disagree.
218
+ """
219
+ cache = text_cache if text_cache is not None else {}
220
+ parsed: list[tuple[BaseParser, list[CodeNode]]] = []
221
+ for rel in commit.changed_files:
222
+ rel_n = normalize_location_path(rel)
223
+ if is_skipped_path(history.root, rel_n) or not is_supported_source(Path(rel_n)):
224
+ continue
225
+ text = history.get_file_at_commit(commit.sha, rel_n)
226
+ if not text:
227
+ close_previous_versions(live, (rel_n, "*"), commit.timestamp)
228
+ # close all nodes in that file
229
+ for key in [k for k in live if k[0] == rel_n]:
230
+ close_previous_versions(live, key, commit.timestamp)
231
+ continue
232
+
233
+ parser = get_parser_for_path(Path(rel_n))
234
+ if parser is None:
235
+ continue
236
+ try:
237
+ nodes = parser.parse_text(
238
+ rel_n, text, commit_sha=commit.sha, valid_from=commit.timestamp
239
+ )
240
+ except Exception as exc: # noqa: BLE001
241
+ logger.warning("Parse failed at %s %s: %s", commit.sha[:10], rel_n, exc)
242
+ continue
243
+
244
+ seen_names = {(n.file_path, n.name) for n in nodes}
245
+ for key in [k for k in live if k[0] == rel_n and (k[0], k[1]) not in seen_names]:
246
+ close_previous_versions(live, key, commit.timestamp)
247
+
248
+ for node in nodes:
249
+ key = (node.file_path, node.name)
250
+ if _has_unchanged_live_version(
251
+ live.get(key, []), node, text, history, rel_n, cache, commit.timestamp
252
+ ):
253
+ # Same symbol, same lines, same source: keep the existing version
254
+ # instead of forking a second live version.
255
+ continue
256
+ # Close every other live version of this symbol before appending.
257
+ for prev in live.get(key, []):
258
+ if prev.valid_to is None:
259
+ prev.valid_to = commit.timestamp
260
+ live.setdefault(key, []).append(node)
261
+ all_nodes.append(node)
262
+
263
+ parsed.append((parser, nodes))
264
+
265
+ live_scope = _live_nodes(live)
266
+ for parser, nodes in parsed:
267
+ try:
268
+ all_edges.extend(parser.extract_edges(nodes, scope=live_scope))
269
+ except Exception as exc: # noqa: BLE001
270
+ logger.warning("Edge extract failed for %s: %s", nodes[0].file_path, exc)
271
+
272
+
273
+ def load_decisions(
274
+ repo_path: Path,
275
+ depth: int,
276
+ use_llm: bool = False,
277
+ llm_model: str = "llama3.2",
278
+ progress_console: Console | None = None,
279
+ ) -> list[Decision]:
280
+ """Extract decisions from the repository's own history and documents.
281
+
282
+ Nothing is fabricated: a repository whose commits and documents carry no
283
+ rationale produces no decisions, and the index says so.
284
+
285
+ Args:
286
+ progress_console: Where human-readable output goes; defaults to stdout
287
+ but is stderr when `--json` is in use so stdout stays parseable.
288
+ """
289
+ decisions = extract_all(
290
+ repo_path, depth=depth, use_llm=use_llm, llm_model=llm_model
291
+ )
292
+ if not decisions:
293
+ (progress_console or console).print(
294
+ "[yellow]warn[/] No decisions found in commits, ADRs or CHANGELOG. "
295
+ "The graph will hold structure only."
296
+ )
297
+ (progress_console or console).print(
298
+ "[dim]Record why in a commit message ('... because ...'), an ADR, "
299
+ "or a CHANGELOG entry, then re-run index.[/]"
300
+ )
301
+ return decisions
302
+
303
+
304
+ def _ingest_working_tree(
305
+ root: Path, all_nodes: list[CodeNode], all_edges: list[Edge], jobs: int = 0
306
+ ) -> None:
307
+ """Parse files currently on disk when Git history is unavailable."""
308
+ from codegraph.parser.parallel import parse_files_parallel
309
+ from codegraph.parser.registry import is_supported_source
310
+
311
+ now = datetime.now(timezone.utc)
312
+ items: list[tuple[str, str]] = []
313
+ for path in sorted(root.rglob("*")):
314
+ if not path.is_file() or not is_supported_source(path):
315
+ continue
316
+ rel_parts = path.relative_to(root).parts
317
+ if any(part in SKIP_DIRS for part in rel_parts):
318
+ continue
319
+ rel = normalize_location_path(str(path.relative_to(root)))
320
+ try:
321
+ text = path.read_text(encoding="utf-8")
322
+ except (OSError, UnicodeDecodeError) as exc:
323
+ logger.warning("Read failed %s: %s", path, exc)
324
+ continue
325
+ items.append((rel, text))
326
+
327
+ nodes, edges = parse_files_parallel(
328
+ items, commit_sha="WORKTREE", valid_from=now, jobs=jobs
329
+ )
330
+ all_nodes.extend(nodes)
331
+ all_edges.extend(edges)
332
+
333
+
334
+
335
+
336
+ def _commit_sha_from_ref(source_ref: str) -> str:
337
+ """Extract a hex sha from a source_ref like 'commit abc123...'."""
338
+ for token in source_ref.replace(":", " ").split():
339
+ if len(token) >= 7 and all(c in "0123456789abcdefABCDEF" for c in token):
340
+ return token
341
+ return ""
342
+
343
+
344
+ def parse_governs(text: str) -> list[str]:
345
+ """Return the code paths a document declares it governs.
346
+
347
+ Two forms are recognised, so both MD/ADR conventions work:
348
+
349
+ * a front-matter or inline line `governs: src/a.py, src/b/`
350
+ * an HTML comment `<!-- governs: src/a.py -->`
351
+ """
352
+ out: list[str] = []
353
+ for pattern in (GOVERNS_FRONT_MATTER, GOVERNS_COMMENT):
354
+ for match in pattern.finditer(text or ""):
355
+ for raw in re.split(r"[,\s]+", match.group("paths").strip()):
356
+ value = normalize_location_path(raw).strip("`'\"*-")
357
+ if value and value not in out:
358
+ out.append(value)
359
+ return out
360
+
361
+
362
+ def _representative_nodes(nodes: list[CodeNode]) -> list[CodeNode]:
363
+ """One node per (file, name), preferring the live version.
364
+
365
+ Governed bindings must cover a whole file, not just its oldest symbols, so
366
+ historical duplicates are collapsed before the fan-out cap is applied.
367
+ """
368
+ best: dict[tuple[str, str], CodeNode] = {}
369
+ for node in nodes:
370
+ key = (node.file_path, node.name)
371
+ prev = best.get(key)
372
+ if prev is None:
373
+ best[key] = node
374
+ continue
375
+ prev_live, node_live = prev.valid_to is None, node.valid_to is None
376
+ if node_live != prev_live:
377
+ if node_live:
378
+ best[key] = node
379
+ elif _as_utc(node.valid_from) > _as_utc(prev.valid_from):
380
+ best[key] = node
381
+ return sorted(best.values(), key=lambda n: n.line_start)
382
+
383
+
384
+ def _governed_nodes(
385
+ text: str,
386
+ by_file: dict[str, list[CodeNode]],
387
+ node_names: dict[str, list[CodeNode]],
388
+ ) -> list[tuple[str, CodeNode]]:
389
+ """Resolve the code a prose decision points at.
390
+
391
+ Sources, in order of precision: an explicit `governs:` declaration, a
392
+ backticked source path, and a backticked identifier that is a real node name.
393
+ """
394
+ targets: list[tuple[str, CodeNode]] = []
395
+ seen: set[tuple[str, str]] = set()
396
+
397
+ def add(path: str, node: CodeNode) -> None:
398
+ key = (path, node.uid)
399
+ if key not in seen:
400
+ seen.add(key)
401
+ targets.append((path, node))
402
+
403
+ paths = parse_governs(text)
404
+ paths += [normalize_location_path(p) for p in BACKTICKED_PATH.findall(text or "")]
405
+ for value in paths:
406
+ if len(targets) >= MAX_GOVERNED_NODES:
407
+ break
408
+ if value in by_file:
409
+ for node in by_file[value][:MAX_GOVERNED_NODES_PER_FILE]:
410
+ add(value, node)
411
+ continue
412
+ prefix = value.rstrip("/") + "/"
413
+ matched = sorted(f for f in by_file if f.startswith(prefix))
414
+ for file_path in matched[:MAX_GOVERNED_FILES]:
415
+ if len(targets) >= MAX_GOVERNED_NODES:
416
+ break
417
+ for node in by_file[file_path][:MAX_GOVERNED_NODES_PER_FILE]:
418
+ add(file_path, node)
419
+
420
+ for ident in BACKTICKED_IDENT.findall(text or ""):
421
+ candidates = node_names.get(ident, [])
422
+ if not candidates and "." in ident:
423
+ # ``app.route`` names a symbol on a module; the last segment is the
424
+ # candidate, and it still has to be unique to bind.
425
+ candidates = node_names.get(ident.rsplit(".", 1)[-1], [])
426
+ if not candidates:
427
+ continue
428
+ files = {n.file_path for n in candidates}
429
+ if len(files) > 3:
430
+ continue # too generic to be evidence about code
431
+ # A name defined in exactly one file is unambiguous no matter how it is
432
+ # spelled, so short identifiers like `redirect` bind when they are unique.
433
+ unique = len(files) == 1 and len(ident) >= 4
434
+ if not unique and not is_distinctive_identifier(ident):
435
+ continue
436
+ for node in candidates[:MAX_GOVERNED_NODES_PER_FILE]:
437
+ add(node.file_path, node)
438
+ return targets
439
+
440
+
441
+ def _read_decision_text(root: Path, decision: Decision) -> str:
442
+ """Read the document a prose decision came from, when it is a local file."""
443
+ if not decision.file_path or not decision.file_path.endswith(".md"):
444
+ return ""
445
+ path = (root / decision.file_path).resolve()
446
+ try:
447
+ if path.is_file() and path.is_relative_to(root):
448
+ return path.read_text(encoding="utf-8", errors="replace")
449
+ except (OSError, ValueError):
450
+ return ""
451
+ return ""
452
+
453
+
454
+ def cap_links(
455
+ links: list[tuple[str, str, str, int]],
456
+ *,
457
+ max_files: int = MAX_BINDING_FILES,
458
+ max_lines: int = MAX_BINDING_LINES,
459
+ ) -> list[tuple[str, str, str, int]]:
460
+ """Drop bindings that claim too much code to be a line-level fact.
461
+
462
+ A commit that touched half the repository is provenance for a whole change,
463
+ not evidence about a single line; such decisions stay reachable through the
464
+ commit-level fallback instead of claiming hundreds of line links.
465
+ """
466
+ grouped: dict[str, list[tuple[str, str, str, int]]] = {}
467
+ for item in links:
468
+ grouped.setdefault(item[0], []).append(item)
469
+ kept: list[tuple[str, str, str, int]] = []
470
+ dropped = 0
471
+ for decision_uid, items in grouped.items():
472
+ files = {item[2] for item in items}
473
+ if len(files) > max_files or len(items) > max_lines:
474
+ dropped += 1
475
+ logger.debug(
476
+ "No line binding for %s: %s file(s), %s line(s)",
477
+ decision_uid,
478
+ len(files),
479
+ len(items),
480
+ )
481
+ continue
482
+ kept.extend(items)
483
+ if dropped:
484
+ logger.info("Kept commit-level binding for %s over-broad decision(s)", dropped)
485
+ return kept
486
+
487
+
488
+ def bind_decisions_to_lines(
489
+ root: Path,
490
+ decisions: list[Decision],
491
+ nodes: list[CodeNode],
492
+ ) -> list[tuple[str, str, str, int]]:
493
+ """Bind decisions to the code they describe.
494
+
495
+ Commit decisions bind to the changed lines that fall inside a CodeNode.
496
+ Decisions without a commit (ADRs, CHANGELOG entries) bind to the code they
497
+ name: an explicit `governs:` declaration, a backticked source path, or a
498
+ backticked identifier that matches a node name.
499
+
500
+ Returns:
501
+ Rows for decision_code_links: (decision_uid, node_uid, file_path, line).
502
+ """
503
+ links: list[tuple[str, str, str, int]] = []
504
+ by_file: dict[str, list[CodeNode]] = {}
505
+ for node in nodes:
506
+ by_file.setdefault(node.file_path, []).append(node)
507
+
508
+ governed_by_file = {path: _representative_nodes(items) for path, items in by_file.items()}
509
+ governed_names: dict[str, list[CodeNode]] = {}
510
+ for items in governed_by_file.values():
511
+ for node in items:
512
+ governed_names.setdefault(node.name, []).append(node)
513
+
514
+ for decision in decisions:
515
+ sha = _commit_sha_from_ref(decision.source_ref)
516
+ if not sha:
517
+ # Fall back to the decision's own file:line if present
518
+ if decision.file_path and decision.line:
519
+ matches = [
520
+ n
521
+ for n in by_file.get(decision.file_path, [])
522
+ if n.contains_line(decision.line)
523
+ ]
524
+ if matches:
525
+ node = min(matches, key=lambda n: n.line_end - n.line_start)
526
+ links.append((decision.uid, node.uid, decision.file_path, decision.line))
527
+ continue
528
+ if decision.tier is DecisionTier.DECISION:
529
+ text = _read_decision_text(root, decision)
530
+ haystack = "\n".join(
531
+ [decision.content, decision.reason, *decision.alternatives, text]
532
+ )
533
+ for path, node in _governed_nodes(haystack, governed_by_file, governed_names):
534
+ links.append((decision.uid, node.uid, path, node.line_start))
535
+ continue
536
+
537
+ try:
538
+ changed = get_changed_lines(root, sha)
539
+ total = sum(len(v) for v in changed.values())
540
+ if total > MAX_CHANGED_LINES:
541
+ # Keep binds only for lines that fall inside known CodeNodes.
542
+ logger.warning(
543
+ "filtered line bind for %s: %s changed lines", sha, total
544
+ )
545
+ filtered: dict[str, list[int]] = {}
546
+ for fpath, lines in changed.items():
547
+ hits = [
548
+ ln
549
+ for ln in lines
550
+ if any(n.contains_line(ln) for n in by_file.get(fpath, []))
551
+ ]
552
+ if hits:
553
+ filtered[fpath] = hits[:200]
554
+ changed = filtered
555
+ except Exception as exc: # noqa: BLE001
556
+ logger.warning("changed lines failed for %s: %s", sha, exc)
557
+ changed = {}
558
+
559
+ if not changed and decision.file_path and decision.line:
560
+ matches = [
561
+ n for n in by_file.get(decision.file_path, []) if n.contains_line(decision.line)
562
+ ]
563
+ if matches:
564
+ node = min(matches, key=lambda n: n.line_end - n.line_start)
565
+ links.append((decision.uid, node.uid, decision.file_path, decision.line))
566
+ continue
567
+
568
+ decision_links: list[tuple[str, str, str, int]] = []
569
+ for file_path, lines in changed.items():
570
+ candidates = by_file.get(file_path, [])
571
+ for ln in lines:
572
+ hit = [n for n in candidates if n.contains_line(ln)]
573
+ if not hit:
574
+ continue
575
+ node = min(hit, key=lambda n: n.line_end - n.line_start)
576
+ decision_links.append((decision.uid, node.uid, file_path, ln))
577
+ links.extend(cap_links(decision_links))
578
+ return links
579
+
580
+
581
+ class GraphShrinkError(RuntimeError):
582
+ """Raised when an incremental run would shrink the stored graph."""
583
+
584
+
585
+ def guard_node_collapse(new_count: int, previous_count: int, *, replace: bool) -> None:
586
+ """Refuse an incremental write that would drop most of the stored graph.
587
+
588
+ A full rebuild or a first index may legitimately produce any count; an
589
+ incremental merge must never shrink the graph by more than half.
590
+
591
+ Args:
592
+ new_count: Node versions about to be written.
593
+ previous_count: Node versions currently stored.
594
+ replace: True when the write is a full rebuild.
595
+
596
+ Raises:
597
+ GraphShrinkError: When the write would lose data.
598
+ """
599
+ if replace or previous_count <= 0:
600
+ return
601
+ if new_count < previous_count * 0.5:
602
+ raise GraphShrinkError(
603
+ f"node count would drop from {previous_count} to {new_count}; "
604
+ "this looks like a lost-history rebuild"
605
+ )
606
+
607
+
608
+ def _close_superseded_live_versions(nodes: list[CodeNode]) -> int:
609
+ """Repair a legacy graph that has several live versions of one symbol.
610
+
611
+ Older `index` runs could leave two simultaneously-live versions of the same
612
+ (file_path, name). Keep the newest and close the rest at its `valid_from`.
613
+
614
+ Returns:
615
+ Number of versions that were closed.
616
+ """
617
+ groups: dict[tuple[str, str], list[CodeNode]] = {}
618
+ for node in nodes:
619
+ if node.valid_to is None:
620
+ groups.setdefault((node.file_path, node.name), []).append(node)
621
+ closed = 0
622
+ for versions in groups.values():
623
+ if len(versions) < 2:
624
+ continue
625
+ versions.sort(key=lambda n: n.valid_from)
626
+ keeper = versions[-1]
627
+ for older in versions[:-1]:
628
+ older.valid_to = keeper.valid_from
629
+ closed += 1
630
+ return closed
631
+
632
+
633
+ def _load_stored_graph(db_path: Path) -> tuple[list[CodeNode], list[Edge]]:
634
+ """Load the persisted graph so an incremental run can merge into it."""
635
+ conn = connect(db_path)
636
+ try:
637
+ init_schema(conn)
638
+ return load_nodes(conn), load_edges(conn)
639
+ finally:
640
+ conn.close()
641
+
642
+
643
+ def _is_flat_worktree_graph(nodes: list[CodeNode]) -> bool:
644
+ """True when every stored node comes from a working-tree snapshot, not Git."""
645
+ return all(node.commit_sha == "WORKTREE" for node in nodes)
646
+
647
+
648
+ def _recorded_node_count(root: Path) -> int:
649
+ """Node versions the last successful index claimed to have written (0 if unknown)."""
650
+ from codegraph.git.incremental import load_last_state
651
+
652
+ value = load_last_state(root).get("node_count")
653
+ try:
654
+ return int(value) # type: ignore[arg-type]
655
+ except (TypeError, ValueError):
656
+ return 0
657
+
658
+
659
+ def write_sqlite_graph(
660
+ db_path: Path,
661
+ nodes: list[CodeNode],
662
+ edges: list[Edge],
663
+ decisions: list[Decision],
664
+ links: list[tuple[str, str, str, int]] | None = None,
665
+ *,
666
+ replace: bool = True,
667
+ ) -> tuple[int, int, int]:
668
+ """Persist nodes/edges/decisions/links and return counts.
669
+
670
+ Args:
671
+ db_path: SQLite database path.
672
+ nodes: Node versions to store (full merged set when incremental).
673
+ edges: Edges to store (full merged set when incremental).
674
+ decisions: Decisions to store.
675
+ links: decision_code_links rows.
676
+ replace: True for a full rebuild (clears the tables first). False for an
677
+ incremental run, where only the rows being rewritten are deleted.
678
+
679
+ Returns:
680
+ (node_count, edge_count, decision_count) after the write.
681
+ """
682
+ conn = connect(db_path)
683
+ try:
684
+ init_schema(conn)
685
+ if replace:
686
+ clear_graph(conn)
687
+ else:
688
+ replace_graph_rows(conn, [n.uid for n in nodes])
689
+ node_uids = {n.uid for n in nodes}
690
+ candidates = [e for e in edges if e.from_uid in node_uids and e.to_uid in node_uids]
691
+ # Writing must be idempotent: re-reading history after an amend or rebase
692
+ # re-derives edges that are already stored.
693
+ unique_keys = dict.fromkeys(
694
+ (e.from_uid, e.to_uid, e.kind, e.file_path, e.line) for e in candidates
695
+ )
696
+ live_edges = [
697
+ Edge(from_uid=from_uid, to_uid=to_uid, kind=kind, file_path=path, line=line)
698
+ for from_uid, to_uid, kind, path, line in unique_keys
699
+ ]
700
+ if len(live_edges) != len(edges):
701
+ logger.debug(
702
+ "Dropped %d duplicate or dangling edge(s)", len(edges) - len(live_edges)
703
+ )
704
+ insert_nodes(conn, nodes)
705
+ insert_edges(conn, live_edges)
706
+ insert_decisions(conn, decisions)
707
+ insert_decision_links(conn, links or [])
708
+ return count_nodes(conn), count_edges(conn), count_decisions(conn)
709
+ finally:
710
+ conn.close()
711
+
712
+
713
+ def run_index_progress(steps: list[str], progress_console: Console | None = None) -> None:
714
+ """Show multi-stage index progress bar."""
715
+ with Progress(
716
+ SpinnerColumn(),
717
+ TextColumn("[progress.description]{task.description}"),
718
+ BarColumn(),
719
+ TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
720
+ TimeElapsedColumn(),
721
+ console=progress_console or console,
722
+ ) as progress:
723
+ overall = progress.add_task("Indexing", total=len(steps))
724
+ for step in steps:
725
+ task = progress.add_task(step, total=6)
726
+ for _ in range(6):
727
+ progress.update(task, advance=1)
728
+ progress.update(overall, advance=1)
729
+
730
+
731
+ def index_command(
732
+ path: Path = typer.Argument(..., help="Repository or directory path to index", metavar="PATH"),
733
+ depth: int = typer.Option(
734
+ 100,
735
+ "--depth",
736
+ help="How many recent commits to walk (default 100)",
737
+ metavar="N",
738
+ ),
739
+ use_llm: bool = typer.Option(
740
+ False,
741
+ "--use-llm",
742
+ help="Use local Ollama to extract decisions when rules miss",
743
+ ),
744
+ llm_model: str = typer.Option(
745
+ "llama3.2",
746
+ "--llm-model",
747
+ help="Ollama model name for --use-llm",
748
+ metavar="MODEL",
749
+ ),
750
+ as_json: bool = typer.Option(
751
+ False,
752
+ "--json",
753
+ help="Emit machine-readable JSON summary",
754
+ ),
755
+ jobs: int = typer.Option(
756
+ 0,
757
+ "--jobs",
758
+ help="Parallel parse workers (0 = CPU-1)",
759
+ metavar="N",
760
+ ),
761
+ full: bool = typer.Option(
762
+ False,
763
+ "--full",
764
+ help="Force full rebuild (ignore incremental state)",
765
+ ),
766
+ ) -> None:
767
+ """Parse Git history with tree-sitter and persist the code graph.
768
+
769
+ Args:
770
+ path: Repository root or subdirectory.
771
+ depth: Max commits to walk.
772
+ """
773
+ logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(message)s")
774
+ try:
775
+ target = resolve_repo_path(path)
776
+ except typer.BadParameter as exc:
777
+ console.print(f"[bold red]Invalid argument[/] {exc}")
778
+ raise typer.Exit(code=2) from exc
779
+
780
+ root = target if target.is_dir() else target.parent
781
+ # With --json the only thing on stdout must be the JSON document, so all
782
+ # human-facing output goes to stderr.
783
+ stream_console = Console(stderr=True) if as_json else console
784
+ stream_console.print(
785
+ f"[bold cyan]Indexing[/] {target} ... [dim]depth={depth}[/]"
786
+ )
787
+ run_index_progress(INDEX_STEPS, progress_console=stream_console)
788
+
789
+ all_nodes: list[CodeNode] = []
790
+ all_edges: list[Edge] = []
791
+ live: dict[tuple[str, str], list[CodeNode]] = {}
792
+ text_cache: dict[tuple[str, str], str] = {}
793
+ commit_count = 0
794
+
795
+ try:
796
+ history = GitHistory(root)
797
+ except ValueError as exc:
798
+ stream_console.print(f"[yellow]warn[/] {exc}; parsing working tree only")
799
+ history = None
800
+
801
+ db_path = db_path_for_root(root)
802
+ replace = full
803
+ previous_nodes = 0
804
+ previous_edges = 0
805
+ if not full and db_path.exists():
806
+ stored_nodes, stored_edges = _load_stored_graph(db_path)
807
+ recorded = _recorded_node_count(root)
808
+ if stored_nodes and history is not None and (
809
+ _is_flat_worktree_graph(stored_nodes) or 0 < len(stored_nodes) < recorded
810
+ ):
811
+ stream_console.print(
812
+ "[yellow]warn[/] stored graph is incomplete "
813
+ f"({len(stored_nodes)} of {recorded or '?'} recorded node versions); "
814
+ "rebuilding from scratch"
815
+ )
816
+ replace = True
817
+ elif stored_nodes:
818
+ replace = False
819
+ previous_nodes = len(stored_nodes)
820
+ previous_edges = len(stored_edges)
821
+ repaired = _close_superseded_live_versions(stored_nodes)
822
+ if repaired:
823
+ stream_console.print(
824
+ f"[yellow]warn[/] repaired {repaired} duplicate live node version(s)"
825
+ )
826
+ all_nodes.extend(stored_nodes)
827
+ all_edges.extend(stored_edges)
828
+ for node in stored_nodes:
829
+ if node.valid_to is None:
830
+ live.setdefault((node.file_path, node.name), []).append(node)
831
+ stream_console.print(
832
+ f"[dim]incremental[/] keeping {previous_nodes} stored node version(s), "
833
+ f"{previous_edges} edge(s)"
834
+ )
835
+
836
+ head_sha = ""
837
+ if history is not None:
838
+ from codegraph.git.incremental import commits_after
839
+
840
+ if full or replace:
841
+ commits = list(history.iter_commits(depth=depth))
842
+ pending = list(reversed(commits))
843
+ else:
844
+ pending = commits_after(root, history, depth=depth)
845
+ for commit in pending:
846
+ try:
847
+ ingest_commit(history, commit, live, all_nodes, all_edges, text_cache)
848
+ commit_count += 1
849
+ except Exception as exc: # noqa: BLE001
850
+ logger.warning("Skip commit %s: %s", commit.sha, exc)
851
+ try:
852
+ head = next(history.iter_commits(depth=1), None)
853
+ if head is not None:
854
+ head_sha = head.sha
855
+ except Exception as exc: # noqa: BLE001
856
+ logger.warning("Cannot read HEAD: %s", exc)
857
+
858
+ if not all_nodes:
859
+ _ingest_working_tree(root, all_nodes, all_edges, jobs=jobs)
860
+
861
+ if use_llm:
862
+ stream_console.print(
863
+ f"[yellow]warn[/] --use-llm enabled (model={llm_model}); "
864
+ "falls back to rules if Ollama is down"
865
+ )
866
+ decisions = load_decisions(
867
+ root, depth, use_llm=use_llm, llm_model=llm_model,
868
+ progress_console=stream_console,
869
+ )
870
+
871
+ try:
872
+ guard_node_collapse(len(all_nodes), previous_nodes, replace=replace)
873
+ except GraphShrinkError as exc:
874
+ stream_console.print(f"[bold red]Refusing to write[/] {exc}")
875
+ stream_console.print(
876
+ "[dim]Existing graph left untouched. Re-run with --full to rebuild "
877
+ "from scratch.[/]"
878
+ )
879
+ raise typer.Exit(code=4) from exc
880
+ links = bind_decisions_to_lines(root, decisions, all_nodes)
881
+ node_count, edge_count, decision_count = write_sqlite_graph(
882
+ db_path, all_nodes, all_edges, decisions, links, replace=replace
883
+ )
884
+
885
+ if head_sha:
886
+ # Record the persisted size so a truncated graph is detected next run.
887
+ from codegraph.git.incremental import save_last_head
888
+
889
+ try:
890
+ save_last_head(root, head_sha, node_count=node_count)
891
+ except OSError as exc: # noqa: BLE001
892
+ logger.warning("Cannot save incremental state: %s", exc)
893
+
894
+ if as_json:
895
+ import json as jsonlib
896
+
897
+ typer.echo(
898
+ jsonlib.dumps(
899
+ {
900
+ "root": str(root),
901
+ "commits": commit_count,
902
+ "nodes": node_count,
903
+ "edges": edge_count,
904
+ "decisions": decision_count,
905
+ },
906
+ ensure_ascii=False,
907
+ )
908
+ )
909
+ return
910
+
911
+ console.print()
912
+ console.print(f"[bold green]Index complete[/] [bold]{root}[/]")
913
+ console.print(f" · Commits walked: [bold]{commit_count}[/]")
914
+ console.print(f" · Nodes: [bold]{node_count}[/]")
915
+ console.print(f" · Edges: [bold]{edge_count}[/]")
916
+ console.print(f" · Decisions: [bold]{decision_count}[/]")
917
+ console.print(f" · Database: [bold]{db_path_for_root(root)}[/]")
918
+ console.print("[dim]Next: codegraph why <file>:<line> to view a decision card[/]")
919
+
920
+
921
+ app = typer.Typer(help="Index a codebase from Git history (tree-sitter + SQLite)")
922
+
923
+ if __name__ == "__main__":
924
+ app()