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,156 @@
1
+ """Git history access via GitPython."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ from collections.abc import Iterator
7
+ from dataclasses import dataclass, field
8
+ from datetime import datetime, timezone
9
+ from pathlib import Path
10
+
11
+ logger = logging.getLogger(__name__)
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class CommitInfo:
16
+ """Lightweight commit metadata."""
17
+
18
+ sha: str
19
+ author: str
20
+ timestamp: datetime
21
+ message: str
22
+ changed_files: list[str] = field(default_factory=list)
23
+
24
+
25
+ class GitHistory:
26
+ """Read commits and file snapshots from a local Git repository."""
27
+
28
+ def __init__(self, repo_path: Path) -> None:
29
+ """Open the repository at repo_path.
30
+
31
+ Args:
32
+ repo_path: Working tree or .git parent directory.
33
+
34
+ Raises:
35
+ ValueError: When the path is not a Git repository.
36
+ """
37
+ from git import InvalidGitRepositoryError, Repo
38
+
39
+ self._path = repo_path.expanduser().resolve()
40
+ try:
41
+ # Prefer the directory itself; fall back to parents only if it is inside a worktree.
42
+ self._repo = Repo(str(self._path))
43
+ except InvalidGitRepositoryError:
44
+ try:
45
+ self._repo = Repo(str(self._path), search_parent_directories=True)
46
+ root = Path(self._repo.working_dir).resolve()
47
+ if self._path != root and root not in self._path.parents:
48
+ raise ValueError(f"Not a git repository: {repo_path}")
49
+ except InvalidGitRepositoryError as exc:
50
+ raise ValueError(f"Not a git repository: {repo_path}") from exc
51
+
52
+ @property
53
+ def root(self) -> Path:
54
+ """Return the repository working tree root."""
55
+ return Path(self._repo.working_dir)
56
+
57
+ def iter_commits(
58
+ self, since: str | None = None, depth: int | None = None
59
+ ) -> Iterator[CommitInfo]:
60
+ """Yield commits from newest to oldest.
61
+
62
+ Args:
63
+ since: Optional ISO date lower bound (inclusive).
64
+ depth: Optional max number of commits to yield.
65
+
66
+ Yields:
67
+ CommitInfo records.
68
+ """
69
+ kwargs: dict = {"max_count": depth} if depth else {}
70
+ try:
71
+ commits = list(self._repo.iter_commits("HEAD", **kwargs))
72
+ except Exception as exc: # noqa: BLE001
73
+ logger.warning("Failed to list commits: %s", exc)
74
+ return
75
+
76
+ for commit in commits:
77
+ try:
78
+ info = self._to_info(commit)
79
+ except Exception as exc: # noqa: BLE001
80
+ logger.warning("Skip commit %s: %s", getattr(commit, "hexsha", "?"), exc)
81
+ continue
82
+ if since and info.timestamp.date().isoformat() < since:
83
+ continue
84
+ yield info
85
+
86
+ def get_file_at_commit(self, commit_sha: str, file_path: str) -> str:
87
+ """Return file text at a commit.
88
+
89
+ Args:
90
+ commit_sha: Commit hexsha.
91
+ file_path: Path relative to the repo root.
92
+
93
+ Returns:
94
+ File contents as text. Empty string when missing.
95
+ """
96
+ rel = file_path.replace("\\", "/")
97
+ try:
98
+ blob = self._repo.commit(commit_sha).tree / rel
99
+ data = blob.data_stream.read()
100
+ return data.decode("utf-8", errors="replace")
101
+ except Exception as exc: # noqa: BLE001
102
+ logger.debug("File %s not in %s: %s", rel, commit_sha, exc)
103
+ return ""
104
+
105
+ def get_commits_touching(self, file_path: str) -> list[CommitInfo]:
106
+ """Return commits that modified a path (newest first)."""
107
+ rel = file_path.replace("\\", "/")
108
+ try:
109
+ commits = list(self._repo.iter_commits("HEAD", paths=rel))
110
+ except Exception as exc: # noqa: BLE001
111
+ logger.warning("Failed to list commits for %s: %s", rel, exc)
112
+ return []
113
+ out: list[CommitInfo] = []
114
+ for commit in commits:
115
+ try:
116
+ out.append(self._to_info(commit))
117
+ except Exception as exc: # noqa: BLE001
118
+ logger.warning("Skip commit for %s: %s", rel, exc)
119
+ return out
120
+
121
+ def list_files_at_commit(self, commit_sha: str) -> list[str]:
122
+ """List blob paths under the tree at a commit."""
123
+ try:
124
+ tree = self._repo.commit(commit_sha).tree
125
+ except Exception as exc: # noqa: BLE001
126
+ logger.warning("Cannot read tree for %s: %s", commit_sha, exc)
127
+ return []
128
+ paths: list[str] = []
129
+ for blob in tree.traverse():
130
+ if getattr(blob, "type", None) == "blob":
131
+ paths.append(str(getattr(blob, "path", "")))
132
+ return paths
133
+
134
+ def _to_info(self, commit) -> CommitInfo:
135
+ """Convert a GitPython commit into CommitInfo."""
136
+ timestamp = datetime.fromtimestamp(commit.committed_date, tz=timezone.utc)
137
+ changed: list[str] = []
138
+ try:
139
+ if commit.parents:
140
+ diffs = commit.parents[0].diff(commit, create_patch=False)
141
+ for diff in diffs:
142
+ path = diff.b_path or diff.a_path
143
+ if path:
144
+ changed.append(path)
145
+ else:
146
+ changed = [item.path for item in commit.tree.traverse() if item.type == "blob"]
147
+ except Exception as exc: # noqa: BLE001
148
+ logger.debug("Changed files for %s: %s", commit.hexsha, exc)
149
+
150
+ return CommitInfo(
151
+ sha=commit.hexsha,
152
+ author=str(commit.author),
153
+ timestamp=timestamp,
154
+ message=commit.message or "",
155
+ changed_files=changed,
156
+ )
@@ -0,0 +1,75 @@
1
+ """Incremental indexing helpers (record last indexed HEAD)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import logging
7
+ from pathlib import Path
8
+
9
+ logger = logging.getLogger(__name__)
10
+
11
+ STATE_REL = Path(".codegraph") / "last_index.json"
12
+
13
+
14
+ def state_path(root: Path) -> Path:
15
+ """Return the incremental state file path."""
16
+ return root / STATE_REL
17
+
18
+
19
+ def load_last_state(root: Path) -> dict:
20
+ """Return the stored incremental state (empty when absent or unreadable)."""
21
+ path = state_path(root)
22
+ if not path.is_file():
23
+ return {}
24
+ try:
25
+ data = json.loads(path.read_text(encoding="utf-8"))
26
+ except (OSError, json.JSONDecodeError) as exc:
27
+ logger.warning("Cannot read index state: %s", exc)
28
+ return {}
29
+ return data if isinstance(data, dict) else {}
30
+
31
+
32
+ def load_last_head(root: Path) -> str | None:
33
+ """Return the last indexed HEAD sha, if any."""
34
+ value = load_last_state(root).get("head")
35
+ return str(value) if value else None
36
+
37
+
38
+ def save_last_head(root: Path, head_sha: str, node_count: int | None = None) -> None:
39
+ """Persist the HEAD sha that was just indexed.
40
+
41
+ Args:
42
+ root: Repository root.
43
+ head_sha: Commit sha that was indexed.
44
+ node_count: Node versions written by this run; lets the next run detect
45
+ a graph that was truncated behind our back.
46
+ """
47
+ path = state_path(root)
48
+ path.parent.mkdir(parents=True, exist_ok=True)
49
+ payload: dict = {"head": head_sha, "tool": "codegraph"}
50
+ if node_count is not None:
51
+ payload["node_count"] = int(node_count)
52
+ path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
53
+
54
+
55
+ def commits_after(root: Path, history, depth: int | None = 100) -> list:
56
+ """Return commits newer than the last indexed HEAD (oldest first).
57
+
58
+ Args:
59
+ root: Repository root.
60
+ history: GitHistory instance.
61
+ depth: Max commits to consider.
62
+
63
+ Returns:
64
+ CommitInfo list needing ingest. Empty when up to date.
65
+ """
66
+ last = load_last_head(root)
67
+ commits = list(history.iter_commits(depth=depth))
68
+ if not last:
69
+ return list(reversed(commits))
70
+ pending = []
71
+ for commit in commits: # newest → oldest
72
+ if commit.sha == last:
73
+ break
74
+ pending.append(commit)
75
+ return list(reversed(pending))
codegraph/git/refs.py ADDED
@@ -0,0 +1,70 @@
1
+ """Resolve git refs (tag / sha / date) to commits."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ from datetime import datetime, timezone, tzinfo
7
+ from pathlib import Path
8
+
9
+ logger = logging.getLogger(__name__)
10
+
11
+
12
+ class RefError(ValueError):
13
+ """Raised when a ref cannot be resolved."""
14
+
15
+
16
+ def resolve_ref(
17
+ repo_path: Path, ref: str, tz: tzinfo | None = None
18
+ ) -> tuple[str, datetime]:
19
+ """Resolve a tag, commit sha, or YYYY-MM-DD date to (sha, timestamp).
20
+
21
+ A date ref matches the commit's calendar date in ``tz`` — by default the
22
+ machine's local zone, which is the date ``git log --date=short`` prints. It
23
+ must not be the UTC date: at 07:00 in UTC+8 a commit dated 2026-10-29 is still
24
+ 2026-10-28 in UTC, so `codegraph diff 2026-10-29 ...` used to answer
25
+ "No commit found" for every morning east of Greenwich.
26
+
27
+ Args:
28
+ repo_path: Repository root.
29
+ ref: Tag, commit sha, or YYYY-MM-DD.
30
+ tz: Timezone for interpreting a date ref; defaults to the local zone.
31
+ """
32
+ from git import InvalidGitRepositoryError, Repo
33
+
34
+ value = (ref or "").strip()
35
+ if not value:
36
+ raise RefError("Empty ref")
37
+
38
+ root = repo_path.expanduser().resolve()
39
+ try:
40
+ repo = Repo(str(root), search_parent_directories=True)
41
+ except InvalidGitRepositoryError as exc:
42
+ raise RefError(f"Not a git repository: {root}") from exc
43
+
44
+ if len(value) == 10 and value[4] == "-" and value[7] == "-":
45
+ try:
46
+ day = datetime.strptime(value, "%Y-%m-%d").date()
47
+ except ValueError as exc:
48
+ raise RefError(f"Invalid date '{value}'. Use YYYY-MM-DD") from exc
49
+ zone = tz or datetime.now().astimezone().tzinfo or timezone.utc
50
+ best = None
51
+ best_dt = None
52
+ for commit in repo.iter_commits("HEAD"):
53
+ ts = datetime.fromtimestamp(commit.committed_date, tz=timezone.utc)
54
+ if ts.astimezone(zone).date() == day:
55
+ if best_dt is None or ts >= best_dt:
56
+ best = commit.hexsha
57
+ best_dt = ts
58
+ if best is None or best_dt is None:
59
+ raise RefError(f"No commit found on {value}")
60
+ return best, best_dt
61
+
62
+ try:
63
+ commit = repo.commit(value)
64
+ except Exception as exc:
65
+ tags = [t.name for t in repo.tags]
66
+ hint = f" Available tags: {', '.join(tags[:12])}" if tags else ""
67
+ raise RefError(f"Cannot resolve ref '{value}'.{hint}") from exc
68
+
69
+ ts = datetime.fromtimestamp(commit.committed_date, tz=timezone.utc)
70
+ return commit.hexsha, ts
codegraph/models.py ADDED
@@ -0,0 +1,211 @@
1
+ """Core data models for CodeGraph.
2
+
3
+ Structure comes from tree-sitter; decisions come from Git history, ADRs and
4
+ CHANGELOG files. Nothing is fabricated: if a repository records no rationale,
5
+ CodeGraph reports that instead of inventing a decision.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from datetime import datetime
11
+ from enum import Enum
12
+
13
+ from pydantic import BaseModel, Field
14
+
15
+
16
+ class DecisionStatus(str, Enum):
17
+ """Lifecycle state of a decision."""
18
+
19
+ ACCEPTED = "accepted"
20
+ SUPERSEDED = "superseded"
21
+ REJECTED = "rejected"
22
+
23
+
24
+ class DecisionSource(str, Enum):
25
+ """Where a decision came from."""
26
+
27
+ PR = "pr"
28
+ ISSUE = "issue"
29
+ ADR = "adr"
30
+ COMMIT = "commit"
31
+ COMMENT = "comment"
32
+
33
+
34
+ class DecisionTier(str, Enum):
35
+ """How much of a decision a record actually is.
36
+
37
+ Only ``DECISION`` records carry a rationale (a reason clause or a rejected
38
+ alternative) and are shown by default. ``EVENT`` records are plain history —
39
+ a commit subject, a changelog line — useful as context, never as an answer.
40
+ """
41
+
42
+ DECISION = "decision"
43
+ EVENT = "event"
44
+
45
+
46
+ class CodeNode(BaseModel):
47
+ """A code structure node: function, class, variable, or file."""
48
+
49
+ uid: str = Field(description="Stable identifier including commit when versioned")
50
+ kind: str = Field(description="function / class / variable / file / module")
51
+ name: str = Field(description="Symbol name")
52
+ file_path: str = Field(description="Path relative to the repo root")
53
+ line_start: int = Field(ge=1, description="Start line")
54
+ line_end: int = Field(ge=1, description="End line")
55
+ language: str = Field(description="Source language")
56
+ commit_sha: str = Field(default="", description="Commit that introduced the node")
57
+ parent_uid: str | None = Field(default=None, description="Parent node uid; None if top-level")
58
+ valid_from: datetime = Field(
59
+ default_factory=lambda: datetime.fromtimestamp(0),
60
+ description="When this node version became valid",
61
+ )
62
+ valid_to: datetime | None = Field(
63
+ default=None,
64
+ description="When this version stopped being valid; None means current",
65
+ )
66
+
67
+ def contains_line(self, line: int) -> bool:
68
+ """Return True when line falls inside this node (inclusive)."""
69
+ return self.line_start <= line <= self.line_end
70
+
71
+
72
+ class Edge(BaseModel):
73
+ """A relationship between code nodes."""
74
+
75
+ from_uid: str = Field(description="Source node uid")
76
+ to_uid: str = Field(description="Target node uid")
77
+ kind: str = Field(description="uses / defined_by / contains")
78
+ file_path: str = Field(default="", description="File where the edge appears")
79
+ line: int = Field(default=1, ge=1, description="Line where the edge appears")
80
+
81
+
82
+ class Decision(BaseModel):
83
+ """A design decision: why code is written this way."""
84
+
85
+ uid: str = Field(description="Stable identifier")
86
+ content: str = Field(description="Decision summary")
87
+ reason: str = Field(default="", description="Why")
88
+ alternatives: list[str] = Field(default_factory=list, description="Rejected options")
89
+ status: DecisionStatus = Field(default=DecisionStatus.ACCEPTED)
90
+ source: DecisionSource = Field(default=DecisionSource.ADR)
91
+ source_ref: str = Field(default="", description="Source reference, e.g. PR #48")
92
+ timestamp: datetime = Field(description="Decision time")
93
+ author: str = Field(default="", description="Author")
94
+ file_path: str = Field(default="", description="Linked code location")
95
+ line: int | None = Field(default=None, description="Linked line number")
96
+ constraints: list[str] = Field(default_factory=list, description="Related constraints")
97
+ confidence: float = Field(default=0.8, ge=0.0, le=1.0, description="Confidence 0-1")
98
+ category: str = Field(default="design", description="design | dependency")
99
+ tier: DecisionTier = Field(
100
+ default=DecisionTier.DECISION,
101
+ description="decision (has a rationale) | event (plain history)",
102
+ )
103
+
104
+ def matches_location(self, file_path: str, line: int) -> bool:
105
+ """Return True when this decision is bound to a file:line."""
106
+ return self.file_path == file_path and self.line == line
107
+
108
+ def has_rationale(self) -> bool:
109
+ """True when the record states a reason or a rejected alternative."""
110
+ return bool((self.reason or "").strip()) or bool(self.alternatives)
111
+
112
+
113
+ def normalize_location_path(raw: str) -> str:
114
+ """Normalize a user path to forward slashes for matching."""
115
+ return raw.strip().replace("\\", "/").lstrip("./")
116
+
117
+
118
+ def select_decisions(
119
+ decisions: list[Decision],
120
+ *,
121
+ include_events: bool = False,
122
+ include_dependency: bool = False,
123
+ ) -> list[Decision]:
124
+ """Return the records a default query should show.
125
+
126
+ Args:
127
+ decisions: Candidate records.
128
+ include_events: Also return event-tier records (plain history).
129
+ include_dependency: Also return dependency-category decisions.
130
+
131
+ Returns:
132
+ Decision-tier, non-dependency records by default.
133
+ """
134
+ out: list[Decision] = []
135
+ for decision in decisions:
136
+ if decision.tier is not DecisionTier.DECISION:
137
+ if include_events:
138
+ out.append(decision)
139
+ continue
140
+ if decision.category == "dependency" and not include_dependency:
141
+ continue
142
+ out.append(decision)
143
+ return out
144
+
145
+
146
+ def make_uid(file_path: str, kind: str, name: str, line_start: int, commit_sha: str = "") -> str:
147
+ """Build a stable node uid, optionally versioned by commit."""
148
+ path = normalize_location_path(file_path)
149
+ base = f"{path}::{kind}::{name}@{line_start}"
150
+ if commit_sha:
151
+ return f"{base}::{commit_sha[:12]}"
152
+ return base
153
+
154
+
155
+ def decision_to_dict(decision: Decision) -> dict:
156
+ """Serialize a Decision for every `--json` output.
157
+
158
+ One implementation so `why`, `graph` and `decisions` cannot drift apart; the
159
+ editor contract in `docs/json-contract.md` is exactly this shape.
160
+ """
161
+ return {
162
+ "uid": decision.uid,
163
+ "content": decision.content,
164
+ "reason": decision.reason,
165
+ "alternatives": decision.alternatives,
166
+ "status": decision.status.value,
167
+ "source": decision.source.value,
168
+ "source_ref": decision.source_ref,
169
+ "timestamp": decision.timestamp.isoformat(),
170
+ "author": decision.author,
171
+ "file_path": decision.file_path,
172
+ "line": decision.line,
173
+ "constraints": decision.constraints,
174
+ "confidence": decision.confidence,
175
+ "category": decision.category,
176
+ "tier": decision.tier.value,
177
+ }
178
+
179
+
180
+ def node_to_dict(node: CodeNode) -> dict:
181
+ """Serialize a CodeNode for `--json` output."""
182
+ return {
183
+ "uid": node.uid,
184
+ "kind": node.kind,
185
+ "name": node.name,
186
+ "file_path": node.file_path,
187
+ "line_start": node.line_start,
188
+ "line_end": node.line_end,
189
+ "language": node.language,
190
+ "commit_sha": node.commit_sha,
191
+ }
192
+
193
+
194
+ class DecisionChange(BaseModel):
195
+ """A decision delta between two snapshots."""
196
+
197
+ kind: str = Field(description="added / removed / changed / superseded")
198
+ decision: Decision
199
+ old_status: str | None = Field(default=None)
200
+ new_status: str | None = Field(default=None)
201
+
202
+ class Conflict(BaseModel):
203
+ """A detected contradiction between two decisions."""
204
+
205
+ type: str = Field(description="opposite / supersede / temporal")
206
+ decision_a: Decision
207
+ decision_b: Decision
208
+ location: str = Field(default="")
209
+ matched_words: list[str] = Field(default_factory=list)
210
+ explanation: str = Field(default="")
211
+ confidence: float = Field(default=1.0)
@@ -0,0 +1 @@
1
+ """Language parser package: tree-sitter implementations."""
@@ -0,0 +1,164 @@
1
+ """Abstract parser base: shared AST extraction interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from abc import ABC, abstractmethod
6
+ from datetime import datetime
7
+ from pathlib import Path
8
+
9
+ from codegraph.models import CodeNode, Edge
10
+
11
+
12
+ class BaseParser(ABC):
13
+ """Base class for language parsers."""
14
+
15
+ language: str = "unknown"
16
+
17
+ def __init__(self) -> None:
18
+ # Call sites: (caller_name, callee_name, line, file_path)
19
+ self._calls: list[tuple[str, str, int, str]] = []
20
+
21
+ @abstractmethod
22
+ def parse_file(self, path: Path) -> list[CodeNode]:
23
+ """Parse a source file and return CodeNode records.
24
+
25
+ Args:
26
+ path: Source file path.
27
+
28
+ Returns:
29
+ Extracted code nodes; empty list when parsing fails.
30
+ """
31
+
32
+ def parse_text(
33
+ self,
34
+ rel_path: str,
35
+ source: str,
36
+ commit_sha: str = "",
37
+ valid_from: datetime | None = None,
38
+ ) -> list[CodeNode]:
39
+ """Parse source text (default: subclasses override).
40
+
41
+ Args:
42
+ rel_path: Repository-relative path.
43
+ source: File contents.
44
+ commit_sha: Optional commit stamp.
45
+ valid_from: Optional validity start.
46
+
47
+ Returns:
48
+ Extracted code nodes.
49
+ """
50
+ raise NotImplementedError
51
+
52
+ def extract_edges(
53
+ self,
54
+ nodes: list[CodeNode],
55
+ calls: list[tuple[str, str, int, str]] | None = None,
56
+ scope: list[CodeNode] | None = None,
57
+ ) -> list[Edge]:
58
+ """Derive relationship edges from hierarchy and call records.
59
+
60
+ Args:
61
+ nodes: Nodes parsed for the file(s) being ingested.
62
+ calls: Call sites to resolve; defaults to the ones recorded by the
63
+ last `parse_text` on this parser.
64
+ scope: Extra nodes a callee may resolve to — the live graph at this
65
+ commit — so a call into another file still produces an edge.
66
+ Callers are always looked up among `nodes`.
67
+
68
+ Returns:
69
+ contains / defined_by / uses edges.
70
+ """
71
+ edges: list[Edge] = []
72
+ edges.extend(self._hierarchy_edges(nodes))
73
+ edges.extend(self._call_edges(nodes, calls, scope))
74
+ return edges
75
+
76
+ def _hierarchy_edges(self, nodes: list[CodeNode]) -> list[Edge]:
77
+ """Build contains / defined_by edges from parent_uid links."""
78
+ by_uid = {n.uid: n for n in nodes}
79
+ edges: list[Edge] = []
80
+ for node in nodes:
81
+ if node.parent_uid and node.parent_uid in by_uid:
82
+ parent = by_uid[node.parent_uid]
83
+ edges.append(
84
+ Edge(
85
+ from_uid=parent.uid,
86
+ to_uid=node.uid,
87
+ kind="contains",
88
+ file_path=node.file_path,
89
+ line=node.line_start,
90
+ )
91
+ )
92
+ edges.append(
93
+ Edge(
94
+ from_uid=node.uid,
95
+ to_uid=parent.uid,
96
+ kind="defined_by",
97
+ file_path=node.file_path,
98
+ line=node.line_start,
99
+ )
100
+ )
101
+ return edges
102
+
103
+ def _call_edges(
104
+ self,
105
+ nodes: list[CodeNode],
106
+ calls: list[tuple[str, str, int, str]] | None = None,
107
+ scope: list[CodeNode] | None = None,
108
+ ) -> list[Edge]:
109
+ """Match call sites to known nodes and emit uses edges.
110
+
111
+ When several nodes share the callee's name, a candidate in the file that
112
+ makes the call wins. ``helper()`` almost always means the ``helper``
113
+ defined next to it, not the identically named symbol in another package.
114
+ Cross-file fan-out is only kept when nothing local matches, so the
115
+ remaining ambiguity is the documented name-matching limitation rather
116
+ than a silent false edge.
117
+ """
118
+ sites = self._calls if calls is None else calls
119
+ by_name: dict[str, list[CodeNode]] = {}
120
+ for node in list(nodes) + list(scope or []):
121
+ by_name.setdefault(node.name, []).append(node)
122
+
123
+ ordered = sorted(nodes, key=lambda n: (n.line_start, n.line_end))
124
+ edges: list[Edge] = []
125
+ seen: set[tuple[str, str, int]] = set()
126
+
127
+ for caller_name, callee_name, line, file_path in sites:
128
+ caller = self._find_caller(ordered, caller_name, line, file_path)
129
+ targets = by_name.get(callee_name, [])
130
+ if caller is None or not targets:
131
+ continue
132
+ local = [t for t in targets if t.file_path == file_path]
133
+ if local:
134
+ targets = local
135
+ for target in targets:
136
+ key = (caller.uid, target.uid, line)
137
+ if key in seen:
138
+ continue
139
+ seen.add(key)
140
+ edges.append(
141
+ Edge(
142
+ from_uid=caller.uid,
143
+ to_uid=target.uid,
144
+ kind="uses",
145
+ file_path=file_path,
146
+ line=line,
147
+ )
148
+ )
149
+ return edges
150
+
151
+ @staticmethod
152
+ def _find_caller(
153
+ nodes: list[CodeNode], caller_name: str, line: int, file_path: str
154
+ ) -> CodeNode | None:
155
+ """Find the innermost same-name caller that contains the call line."""
156
+ candidates = [
157
+ n
158
+ for n in nodes
159
+ if n.name == caller_name and n.file_path == file_path and n.contains_line(line)
160
+ ]
161
+ if not candidates:
162
+ return None
163
+ # Prefer the tightest range (innermost function/method)
164
+ return min(candidates, key=lambda n: n.line_end - n.line_start)