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.
- codegraph/__init__.py +37 -0
- codegraph/cli.py +106 -0
- codegraph/commands/__init__.py +1 -0
- codegraph/commands/conflicts.py +154 -0
- codegraph/commands/diff.py +189 -0
- codegraph/commands/export.py +141 -0
- codegraph/commands/graph.py +200 -0
- codegraph/commands/index.py +924 -0
- codegraph/commands/serve.py +62 -0
- codegraph/commands/why.py +645 -0
- codegraph/decisions/__init__.py +18 -0
- codegraph/decisions/conflicts.py +238 -0
- codegraph/decisions/extractor.py +698 -0
- codegraph/decisions/llm_extractor.py +161 -0
- codegraph/decisions/sources.py +298 -0
- codegraph/git/__init__.py +5 -0
- codegraph/git/diff.py +115 -0
- codegraph/git/history.py +156 -0
- codegraph/git/incremental.py +75 -0
- codegraph/git/refs.py +70 -0
- codegraph/models.py +211 -0
- codegraph/parser/__init__.py +1 -0
- codegraph/parser/base.py +164 -0
- codegraph/parser/common.py +147 -0
- codegraph/parser/parallel.py +96 -0
- codegraph/parser/registry.py +83 -0
- codegraph/parser/treesitter_cpp.py +102 -0
- codegraph/parser/treesitter_go.py +113 -0
- codegraph/parser/treesitter_java.py +79 -0
- codegraph/parser/treesitter_js.py +15 -0
- codegraph/parser/treesitter_py.py +163 -0
- codegraph/parser/treesitter_rust.py +120 -0
- codegraph/parser/treesitter_ts.py +178 -0
- codegraph/storage.py +767 -0
- codegraph/web/__init__.py +1 -0
- codegraph/web/app.py +271 -0
- codegraph/web/static/app.js +356 -0
- codegraph/web/static/index.html +59 -0
- codegraph/web/static/styles.css +92 -0
- codegraphx-0.1.0.dist-info/METADATA +262 -0
- codegraphx-0.1.0.dist-info/RECORD +44 -0
- codegraphx-0.1.0.dist-info/WHEEL +4 -0
- codegraphx-0.1.0.dist-info/entry_points.txt +2 -0
- codegraphx-0.1.0.dist-info/licenses/LICENSE +21 -0
codegraph/git/history.py
ADDED
|
@@ -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."""
|
codegraph/parser/base.py
ADDED
|
@@ -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)
|