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
codegraph/storage.py ADDED
@@ -0,0 +1,767 @@
1
+ """SQLite graph store: nodes, edges, and decisions persistence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sqlite3
7
+ from datetime import datetime, timezone
8
+ from pathlib import Path
9
+
10
+ from codegraph.models import CodeNode, Decision, DecisionTier, Edge
11
+
12
+ DEFAULT_DB_REL = Path(".codegraph") / "graph.db"
13
+
14
+ SCHEMA_SQL = """
15
+ CREATE TABLE IF NOT EXISTS nodes (
16
+ uid TEXT PRIMARY KEY,
17
+ kind TEXT,
18
+ name TEXT,
19
+ file_path TEXT,
20
+ line_start INT,
21
+ line_end INT,
22
+ language TEXT,
23
+ parent_uid TEXT,
24
+ valid_from TEXT,
25
+ valid_to TEXT,
26
+ commit_sha TEXT
27
+ );
28
+ CREATE TABLE IF NOT EXISTS decision_code_links (
29
+ decision_uid TEXT NOT NULL,
30
+ node_uid TEXT NOT NULL,
31
+ file_path TEXT NOT NULL,
32
+ line INTEGER NOT NULL,
33
+ commit_sha TEXT NOT NULL DEFAULT '',
34
+ PRIMARY KEY (decision_uid, file_path, line)
35
+ );
36
+ CREATE INDEX IF NOT EXISTS idx_dcl_file_line ON decision_code_links(file_path, line);
37
+ CREATE INDEX IF NOT EXISTS idx_dcl_decision ON decision_code_links(decision_uid);
38
+ CREATE TABLE IF NOT EXISTS edges (
39
+ from_uid TEXT,
40
+ to_uid TEXT,
41
+ kind TEXT,
42
+ file_path TEXT,
43
+ line INT
44
+ );
45
+ CREATE TABLE IF NOT EXISTS decisions (
46
+ uid TEXT PRIMARY KEY,
47
+ content TEXT,
48
+ reason TEXT,
49
+ alternatives TEXT,
50
+ status TEXT,
51
+ source TEXT,
52
+ source_ref TEXT,
53
+ timestamp TEXT,
54
+ author TEXT,
55
+ file_path TEXT,
56
+ line INT,
57
+ constraints TEXT,
58
+ confidence REAL,
59
+ category TEXT,
60
+ tier TEXT DEFAULT 'decision'
61
+ );
62
+ """
63
+
64
+ # Columns added when upgrading older local DBs
65
+ _NODE_MIGRATIONS = (
66
+ ("valid_from", "TEXT"),
67
+ ("valid_to", "TEXT"),
68
+ ("commit_sha", "TEXT"),
69
+ )
70
+
71
+
72
+ def db_path_for_root(root: Path) -> Path:
73
+ """Return graph.db path under the repository root."""
74
+ return root / DEFAULT_DB_REL
75
+
76
+
77
+ def find_db(start: Path | None = None) -> Path | None:
78
+ """Walk up from `start` looking for an existing graph database.
79
+
80
+ `codegraph index <path>` writes the database inside `<path>`, but every query
81
+ command used to look only at the current directory. A first-time user who ran
82
+ `codegraph index some/repo` from their home directory then got "no record" for
83
+ everything, because the query was reading the wrong place. Git solves the same
84
+ problem by walking up to the repository root; this does the same.
85
+
86
+ Returns the database path, or None when no ancestor has one.
87
+ """
88
+ current = (start or Path.cwd()).resolve()
89
+ for candidate in (current, *current.parents):
90
+ db = candidate / DEFAULT_DB_REL
91
+ if db.is_file():
92
+ return db
93
+ return None
94
+
95
+
96
+ def connect(db_path: Path) -> sqlite3.Connection:
97
+ """Open (and create if needed) the SQLite database."""
98
+ db_path.parent.mkdir(parents=True, exist_ok=True)
99
+ conn = sqlite3.connect(str(db_path))
100
+ conn.execute("PRAGMA journal_mode=WAL;")
101
+ init_schema(conn)
102
+ return conn
103
+
104
+
105
+ def init_schema(conn: sqlite3.Connection) -> None:
106
+ """Create tables and apply lightweight migrations."""
107
+ conn.executescript(SCHEMA_SQL)
108
+ _migrate_nodes(conn)
109
+ _migrate_decision_category(conn)
110
+ _migrate_links(conn)
111
+ conn.commit()
112
+
113
+
114
+ def _migrate_decision_category(conn: sqlite3.Connection) -> None:
115
+ try:
116
+ cols = {row[1] for row in conn.execute("PRAGMA table_info(decisions)")}
117
+ if not cols:
118
+ return
119
+ if "category" not in cols:
120
+ conn.execute("ALTER TABLE decisions ADD COLUMN category TEXT DEFAULT 'design'")
121
+ if "tier" not in cols:
122
+ conn.execute("ALTER TABLE decisions ADD COLUMN tier TEXT DEFAULT 'decision'")
123
+ except sqlite3.Error:
124
+ pass
125
+
126
+
127
+ def _migrate_links(conn: sqlite3.Connection) -> None:
128
+ cols = {row[1] for row in conn.execute("PRAGMA table_info(decision_code_links)")}
129
+ if cols and "commit_sha" not in cols:
130
+ conn.execute(
131
+ "ALTER TABLE decision_code_links ADD COLUMN commit_sha TEXT NOT NULL DEFAULT ''"
132
+ )
133
+ conn.execute(
134
+ "CREATE INDEX IF NOT EXISTS idx_dcl_file_line ON decision_code_links(file_path, line)"
135
+ )
136
+ conn.execute("CREATE INDEX IF NOT EXISTS idx_dcl_decision ON decision_code_links(decision_uid)")
137
+
138
+
139
+ def _migrate_nodes(conn: sqlite3.Connection) -> None:
140
+ """Add missing columns on older nodes tables."""
141
+ cols = {row[1] for row in conn.execute("PRAGMA table_info(nodes)")}
142
+ for name, coltype in _NODE_MIGRATIONS:
143
+ if name not in cols:
144
+ conn.execute(f"ALTER TABLE nodes ADD COLUMN {name} {coltype}")
145
+
146
+
147
+ def clear_graph(conn: sqlite3.Connection) -> None:
148
+ """Delete existing graph rows before a full rebuild.
149
+
150
+ Only call this for a full rebuild (`codegraph index --full`, or a first
151
+ index). Incremental runs must use `replace_graph_rows` so previously
152
+ indexed history is preserved.
153
+ """
154
+ conn.execute("DELETE FROM edges")
155
+ conn.execute("DELETE FROM nodes")
156
+ conn.execute("DELETE FROM decisions")
157
+ conn.execute("DELETE FROM decision_code_links")
158
+ conn.commit()
159
+
160
+
161
+ def load_nodes(conn: sqlite3.Connection) -> list[CodeNode]:
162
+ """Return every stored CodeNode version, oldest first."""
163
+ rows = conn.execute(
164
+ "SELECT uid, kind, name, file_path, line_start, line_end, language, parent_uid, "
165
+ "valid_from, valid_to, commit_sha FROM nodes ORDER BY valid_from"
166
+ ).fetchall()
167
+ return [_row_to_node(row) for row in rows]
168
+
169
+
170
+ def load_edges(conn: sqlite3.Connection) -> list[Edge]:
171
+ """Return every stored Edge."""
172
+ rows = conn.execute(
173
+ "SELECT from_uid, to_uid, kind, file_path, line FROM edges"
174
+ ).fetchall()
175
+ return [
176
+ Edge(
177
+ from_uid=str(r[0] or ""),
178
+ to_uid=str(r[1] or ""),
179
+ kind=str(r[2] or "uses"),
180
+ file_path=str(r[3] or ""),
181
+ line=max(int(r[4] or 1), 1),
182
+ )
183
+ for r in rows
184
+ ]
185
+
186
+
187
+ def _chunks(values: list[str], size: int = 500) -> list[list[str]]:
188
+ """Split a list into chunks small enough for SQLite parameter limits."""
189
+ return [values[i : i + size] for i in range(0, len(values), size)]
190
+
191
+
192
+ def replace_graph_rows(conn: sqlite3.Connection, node_uids: list[str]) -> None:
193
+ """Delete only the rows an incremental run is about to re-insert.
194
+
195
+ Untouched history stays in place, so a second `codegraph index` cannot wipe
196
+ the graph. Decisions and their line links are always fully re-derived by the
197
+ indexer, so they are replaced wholesale. Edges are rewritten from the merged
198
+ in-memory set, which keeps the edge count stable across runs.
199
+
200
+ Args:
201
+ conn: Open SQLite connection.
202
+ node_uids: Node uids being rewritten.
203
+ """
204
+ conn.execute("DELETE FROM decisions")
205
+ conn.execute("DELETE FROM decision_code_links")
206
+ conn.execute("DELETE FROM edges")
207
+ for chunk in _chunks(node_uids):
208
+ marks = ",".join("?" * len(chunk))
209
+ conn.execute(f"DELETE FROM nodes WHERE uid IN ({marks})", chunk)
210
+ conn.commit()
211
+
212
+
213
+ def _dt(value: datetime | None) -> str | None:
214
+ """Serialize datetime for SQLite storage."""
215
+ return value.isoformat() if value else None
216
+
217
+
218
+ def insert_nodes(conn: sqlite3.Connection, nodes: list[CodeNode]) -> None:
219
+ """Bulk insert node versions."""
220
+ conn.executemany(
221
+ "INSERT OR REPLACE INTO nodes "
222
+ "(uid, kind, name, file_path, line_start, line_end, language, parent_uid, "
223
+ "valid_from, valid_to, commit_sha) "
224
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
225
+ [
226
+ (
227
+ n.uid,
228
+ n.kind,
229
+ n.name,
230
+ n.file_path,
231
+ n.line_start,
232
+ n.line_end,
233
+ n.language,
234
+ n.parent_uid,
235
+ _dt(n.valid_from),
236
+ _dt(n.valid_to),
237
+ n.commit_sha,
238
+ )
239
+ for n in nodes
240
+ ],
241
+ )
242
+ conn.commit()
243
+
244
+
245
+ def insert_edges(conn: sqlite3.Connection, edges: list[Edge]) -> None:
246
+ """Bulk insert edges, one row per (from, to, kind).
247
+
248
+ A call site produces one edge, so a function that calls `format` fifty times
249
+ generated fifty identical `(from, to, kind)` rows. Measured across five
250
+ repositories, 6-12% of all edge rows were such duplicates; on fmt one template
251
+ helper held 1026 rows pointing at 18 targets. The graph is a set of
252
+ relationships, so repeated rows carry no information and inflate every count
253
+ that reports edge totals.
254
+
255
+ `file_path` and `line` are kept from the first occurrence: they record where
256
+ the edge was observed, which stays true whichever call site is kept.
257
+ """
258
+ if not edges:
259
+ return
260
+ seen: set[tuple[str, str, str]] = set()
261
+ rows: list[tuple[str, str, str, str, int]] = []
262
+ for edge in edges:
263
+ key = (edge.from_uid, edge.to_uid, edge.kind)
264
+ if key in seen:
265
+ continue
266
+ seen.add(key)
267
+ rows.append((edge.from_uid, edge.to_uid, edge.kind, edge.file_path, edge.line))
268
+ conn.executemany(
269
+ "INSERT INTO edges (from_uid, to_uid, kind, file_path, line) VALUES (?, ?, ?, ?, ?)",
270
+ rows,
271
+ )
272
+ conn.commit()
273
+
274
+
275
+ def _tier_value(decision: Decision) -> str:
276
+ """Serialize a decision tier, tolerating plain strings from old callers."""
277
+ tier = getattr(decision, "tier", DecisionTier.DECISION)
278
+ return tier.value if isinstance(tier, DecisionTier) else str(tier)
279
+
280
+
281
+ def insert_decisions(conn: sqlite3.Connection, decisions: list[Decision]) -> None:
282
+ """Bulk insert extracted decisions."""
283
+ conn.executemany(
284
+ "INSERT OR REPLACE INTO decisions "
285
+ "(uid, content, reason, alternatives, status, source, source_ref, timestamp, "
286
+ "author, file_path, line, constraints, confidence, category, tier) "
287
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
288
+ [
289
+ (
290
+ d.uid,
291
+ d.content,
292
+ d.reason,
293
+ json.dumps(d.alternatives, ensure_ascii=False),
294
+ d.status.value,
295
+ d.source.value,
296
+ d.source_ref,
297
+ d.timestamp.isoformat(),
298
+ d.author,
299
+ d.file_path,
300
+ d.line,
301
+ json.dumps(d.constraints, ensure_ascii=False),
302
+ d.confidence,
303
+ getattr(d, "category", "design"),
304
+ _tier_value(d),
305
+ )
306
+ for d in decisions
307
+ ],
308
+ )
309
+ conn.commit()
310
+
311
+
312
+ def count_nodes(conn: sqlite3.Connection) -> int:
313
+ """Count stored node versions."""
314
+ row = conn.execute("SELECT COUNT(*) FROM nodes").fetchone()
315
+ return int(row[0]) if row else 0
316
+
317
+
318
+ def count_edges(conn: sqlite3.Connection) -> int:
319
+ """Count stored edges."""
320
+ row = conn.execute("SELECT COUNT(*) FROM edges").fetchone()
321
+ return int(row[0]) if row else 0
322
+
323
+
324
+ def count_decisions(conn: sqlite3.Connection) -> int:
325
+ """Count stored decisions."""
326
+ row = conn.execute("SELECT COUNT(*) FROM decisions").fetchone()
327
+ return int(row[0]) if row else 0
328
+
329
+
330
+ def _row_to_node(row: tuple) -> CodeNode:
331
+ """Map a nodes row to CodeNode."""
332
+ (
333
+ uid,
334
+ kind,
335
+ name,
336
+ path,
337
+ line_start,
338
+ line_end,
339
+ language,
340
+ parent_uid,
341
+ valid_from,
342
+ valid_to,
343
+ commit_sha,
344
+ ) = row
345
+ return CodeNode(
346
+ uid=uid,
347
+ kind=kind,
348
+ name=name,
349
+ file_path=path,
350
+ line_start=line_start,
351
+ line_end=line_end,
352
+ language=language,
353
+ parent_uid=parent_uid,
354
+ valid_from=datetime.fromisoformat(valid_from) if valid_from else datetime.fromtimestamp(0),
355
+ valid_to=datetime.fromisoformat(valid_to) if valid_to else None,
356
+ commit_sha=commit_sha or "",
357
+ )
358
+
359
+
360
+ def find_node_at_line(
361
+ conn: sqlite3.Connection,
362
+ file_path: str,
363
+ line: int,
364
+ at: datetime | None = None,
365
+ ) -> CodeNode | None:
366
+ """Return the innermost live CodeNode covering file:line.
367
+
368
+ A node version is live when ``valid_to`` is NULL or still in the future at
369
+ ``at``. Dead versions (a symbol that moved or was deleted) are never
370
+ returned, so ``why`` cannot answer about a line using a tombstoned node.
371
+
372
+ Args:
373
+ conn: Open SQLite connection.
374
+ file_path: Repo-relative source path.
375
+ line: 1-based line number.
376
+ at: Reference instant; defaults to now (UTC).
377
+
378
+ Returns:
379
+ The innermost live CodeNode version, or None when the line has no live node.
380
+ """
381
+ reference = at or datetime.now(timezone.utc)
382
+ rows = conn.execute(
383
+ "SELECT uid, kind, name, file_path, line_start, line_end, language, parent_uid, "
384
+ "valid_from, valid_to, commit_sha "
385
+ "FROM nodes WHERE file_path = ? AND line_start <= ? AND line_end >= ? "
386
+ "AND (valid_to IS NULL OR valid_to >= ?) "
387
+ "ORDER BY (valid_to IS NULL) DESC, (line_end - line_start) ASC, valid_from DESC "
388
+ "LIMIT 1",
389
+ (file_path, line, line, reference.isoformat()),
390
+ ).fetchall()
391
+ if not rows:
392
+ return None
393
+ return _row_to_node(rows[0])
394
+
395
+
396
+ def query_nodes_at(conn: sqlite3.Connection, at: datetime, scope: str) -> list[CodeNode]:
397
+ """Return nodes valid at a timestamp, filtered by file_path prefix."""
398
+ prefix = (scope or "").replace("\\", "/").rstrip("/")
399
+ sql = (
400
+ "SELECT uid, kind, name, file_path, line_start, line_end, language, parent_uid, "
401
+ "valid_from, valid_to, commit_sha FROM nodes "
402
+ "WHERE valid_from <= ? AND (valid_to IS NULL OR valid_to >= ?) "
403
+ )
404
+ params: list[object] = [at.isoformat(), at.isoformat()]
405
+ if prefix and prefix != ".":
406
+ sql += "AND (file_path = ? OR file_path LIKE ?) "
407
+ params.extend([prefix, prefix + "/%"])
408
+ sql += "ORDER BY file_path, line_start"
409
+ return [_row_to_node(row) for row in conn.execute(sql, params).fetchall()]
410
+
411
+
412
+ def count_edges_at(conn: sqlite3.Connection, at: datetime, scope: str = "") -> int:
413
+ """Count edges whose both endpoints are valid at the given timestamp.
414
+
415
+ Scope filters edges by the source node's file_path prefix.
416
+ """
417
+ prefix = (scope or "").replace("\\", "/").rstrip("/")
418
+ sql = """
419
+ SELECT COUNT(*) FROM edges e
420
+ WHERE EXISTS (
421
+ SELECT 1 FROM nodes n_from
422
+ WHERE n_from.uid = e.from_uid
423
+ AND n_from.valid_from <= ?
424
+ AND (n_from.valid_to IS NULL OR n_from.valid_to >= ?)
425
+ ) AND EXISTS (
426
+ SELECT 1 FROM nodes n_to
427
+ WHERE n_to.uid = e.to_uid
428
+ AND n_to.valid_from <= ?
429
+ AND (n_to.valid_to IS NULL OR n_to.valid_to >= ?)
430
+ )
431
+ """
432
+ params: list[object] = [at.isoformat(), at.isoformat(), at.isoformat(), at.isoformat()]
433
+ if prefix and prefix != ".":
434
+ sql += " AND (e.file_path = ? OR e.file_path LIKE ?) "
435
+ params.extend([prefix, prefix + "/%"])
436
+ row = conn.execute(sql, params).fetchone()
437
+ return int(row[0]) if row else 0
438
+
439
+
440
+ def list_edges_at(
441
+ conn: sqlite3.Connection, at: datetime, scope: str = "", limit: int = 400
442
+ ) -> list[dict]:
443
+ """Return live edges (both endpoints valid at at) for visualization.
444
+
445
+ Each item: {"from_uid", "to_uid", "kind", "file_path", "line"}.
446
+ """
447
+ prefix = (scope or "").replace("\\", "/").rstrip("/")
448
+ sql = """
449
+ SELECT e.from_uid, e.to_uid, e.kind, e.file_path, e.line
450
+ FROM edges e
451
+ WHERE EXISTS (
452
+ SELECT 1 FROM nodes n_from
453
+ WHERE n_from.uid = e.from_uid
454
+ AND n_from.valid_from <= ?
455
+ AND (n_from.valid_to IS NULL OR n_from.valid_to >= ?)
456
+ ) AND EXISTS (
457
+ SELECT 1 FROM nodes n_to
458
+ WHERE n_to.uid = e.to_uid
459
+ AND n_to.valid_from <= ?
460
+ AND (n_to.valid_to IS NULL OR n_to.valid_to >= ?)
461
+ )
462
+ """
463
+ params: list[object] = [at.isoformat(), at.isoformat(), at.isoformat(), at.isoformat()]
464
+ if prefix and prefix != ".":
465
+ sql += (
466
+ " AND (e.file_path = ? OR e.file_path LIKE ? "
467
+ "OR e.from_uid LIKE ? OR e.to_uid LIKE ?) "
468
+ )
469
+ params.extend([prefix, prefix + "/%", prefix + "::%", prefix + "::%"])
470
+ sql += " LIMIT ?"
471
+ params.append(limit)
472
+ rows = conn.execute(sql, params).fetchall()
473
+ return [
474
+ {
475
+ "from_uid": r[0],
476
+ "to_uid": r[1],
477
+ "kind": r[2] or "uses",
478
+ "file_path": r[3] or "",
479
+ "line": r[4] or 0,
480
+ }
481
+ for r in rows
482
+ ]
483
+
484
+
485
+ def query_decisions_for_line(conn: sqlite3.Connection, file_path: str, line: int) -> list[Decision]:
486
+ """Return decisions bound to file:line only (strict line match)."""
487
+ rows = conn.execute(
488
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
489
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
490
+ "WHERE file_path = ? AND line = ? "
491
+ "ORDER BY timestamp DESC LIMIT 20",
492
+ (file_path, line),
493
+ ).fetchall()
494
+ return [_row_to_decision(row) for row in rows]
495
+
496
+
497
+ def query_decisions_for_file(conn: sqlite3.Connection, file_path: str) -> list[Decision]:
498
+ """Return decisions whose file_path equals this file (any line)."""
499
+ prefix = file_path.replace("\\", "/")
500
+ rows = conn.execute(
501
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
502
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
503
+ "WHERE file_path = ? "
504
+ "ORDER BY timestamp DESC LIMIT 20",
505
+ (prefix,),
506
+ ).fetchall()
507
+ return [_row_to_decision(row) for row in rows]
508
+
509
+
510
+ def query_decisions_for_dir(
511
+ conn: sqlite3.Connection, file_path: str, limit: int = 5
512
+ ) -> list[Decision]:
513
+ """Return decisions under the file's directory prefix (directory fallback).
514
+
515
+ A file at the repository root has the root as its directory, which means
516
+ records for other root-level files — never records from the whole graph.
517
+ """
518
+ path = file_path.replace("\\", "/")
519
+ if "/" not in path:
520
+ rows = conn.execute(
521
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
522
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
523
+ "WHERE file_path NOT LIKE '%/%' "
524
+ "ORDER BY timestamp DESC LIMIT ?",
525
+ (limit,),
526
+ ).fetchall()
527
+ return [_row_to_decision(row) for row in rows]
528
+
529
+ parent = path.rsplit("/", 1)[0]
530
+ rows = conn.execute(
531
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
532
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
533
+ "WHERE file_path = ? OR file_path LIKE ? "
534
+ "ORDER BY timestamp DESC LIMIT ?",
535
+ (parent, parent + "/%", limit),
536
+ ).fetchall()
537
+ return [_row_to_decision(row) for row in rows]
538
+
539
+
540
+ def query_decisions_for_commit(conn: sqlite3.Connection, commit_sha: str) -> list[Decision]:
541
+ """Return decisions whose source_ref mentions this commit sha."""
542
+ if not commit_sha:
543
+ return []
544
+ short = commit_sha[:10]
545
+ rows = conn.execute(
546
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
547
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
548
+ "WHERE source_ref LIKE ? OR source_ref LIKE ? "
549
+ "ORDER BY timestamp DESC LIMIT 10",
550
+ (f"%{commit_sha}%", f"%{short}%"),
551
+ ).fetchall()
552
+ return [_row_to_decision(row) for row in rows]
553
+
554
+
555
+ def query_decisions_for_file_links(
556
+ conn: sqlite3.Connection, file_path: str, limit: int = 20
557
+ ) -> list[Decision]:
558
+ """Return decisions bound to any line of this file via decision_code_links.
559
+
560
+ A governed ADR answers for the whole file it declares, including lines that no
561
+ CodeNode covers (module docstrings, imports, blank lines between symbols).
562
+ """
563
+ rows = conn.execute(
564
+ "SELECT DISTINCT d.uid, d.content, d.reason, d.alternatives, d.status, d.source, "
565
+ "d.source_ref, d.timestamp, d.author, d.file_path, d.line, d.constraints, "
566
+ "d.confidence, d.category, d.tier "
567
+ "FROM decisions d "
568
+ "JOIN decision_code_links l ON l.decision_uid = d.uid "
569
+ "WHERE l.file_path = ? "
570
+ "ORDER BY d.timestamp DESC LIMIT ?",
571
+ (file_path, limit),
572
+ ).fetchall()
573
+ return [_row_to_decision(row) for row in rows]
574
+
575
+
576
+ def query_all_decisions(conn: sqlite3.Connection) -> list[Decision]:
577
+ """Return all stored decisions."""
578
+ rows = conn.execute(
579
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
580
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
581
+ "ORDER BY timestamp ASC"
582
+ ).fetchall()
583
+ return [_row_to_decision(row) for row in rows]
584
+
585
+
586
+ def _row_to_decision(row: tuple) -> Decision:
587
+ """Map a decisions row to Decision.
588
+
589
+ Rows from older schemas may miss `category` and `tier`; they are padded so
590
+ an existing database keeps reading.
591
+ """
592
+ from codegraph.models import DecisionSource, DecisionStatus, DecisionTier
593
+
594
+ items = list(row)
595
+ while len(items) < 15:
596
+ items.append(None)
597
+ (
598
+ uid,
599
+ content,
600
+ reason,
601
+ alternatives,
602
+ status,
603
+ source,
604
+ source_ref,
605
+ timestamp,
606
+ author,
607
+ file_path,
608
+ line,
609
+ constraints,
610
+ confidence,
611
+ category,
612
+ tier,
613
+ ) = items[:15]
614
+ status_val = status if status in DecisionStatus._value2member_map_ else "accepted"
615
+ source_val = source if source in DecisionSource._value2member_map_ else "commit"
616
+ tier_val = str(tier or DecisionTier.DECISION.value)
617
+ if tier_val not in DecisionTier._value2member_map_:
618
+ tier_val = DecisionTier.DECISION.value
619
+ return Decision(
620
+ uid=uid,
621
+ content=content or "",
622
+ reason=reason or "",
623
+ alternatives=json.loads(alternatives or "[]"),
624
+ status=DecisionStatus(status_val),
625
+ source=DecisionSource(source_val),
626
+ source_ref=source_ref or "",
627
+ timestamp=datetime.fromisoformat(timestamp) if timestamp else datetime.fromtimestamp(0),
628
+ author=author or "",
629
+ file_path=file_path or "",
630
+ line=line,
631
+ constraints=json.loads(constraints or "[]"),
632
+ confidence=float(confidence or 0.5),
633
+ category=str(category or "design"),
634
+ tier=DecisionTier(tier_val),
635
+ )
636
+
637
+
638
+ def insert_decision_links(
639
+ conn: sqlite3.Connection,
640
+ links: list[tuple[str, str, str, int]],
641
+ ) -> None:
642
+ """Insert (decision_uid, node_uid, file_path, line) rows.
643
+
644
+ The table is unique on (decision_uid, file_path, line), and a decision can
645
+ legitimately reach two nodes that start on the same line — a class and its
646
+ first method, for example. Keep the first row for a given line instead of
647
+ letting the insert fail: one link is enough to answer "why" for that line.
648
+ """
649
+ if not links:
650
+ return
651
+ seen: set[tuple[str, str, int]] = set()
652
+ rows: list[tuple[str, str, str, int]] = []
653
+ for decision_uid, node_uid, file_path, line in links:
654
+ key = (decision_uid, file_path, line)
655
+ if key in seen:
656
+ continue
657
+ seen.add(key)
658
+ rows.append((decision_uid, node_uid, file_path, line))
659
+ conn.executemany(
660
+ "INSERT INTO decision_code_links (decision_uid, node_uid, file_path, line) "
661
+ "VALUES (?, ?, ?, ?)",
662
+ rows,
663
+ )
664
+ conn.commit()
665
+
666
+
667
+ def query_decisions_for_line_links(
668
+ conn: sqlite3.Connection, file_path: str, line: int
669
+ ) -> list[Decision]:
670
+ """Return decisions linked to a concrete file:line via decision_code_links."""
671
+ rows = conn.execute(
672
+ "SELECT d.uid, d.content, d.reason, d.alternatives, d.status, d.source, "
673
+ "d.source_ref, d.timestamp, d.author, d.file_path, d.line, d.constraints, d.confidence, "
674
+ "d.category, d.tier "
675
+ "FROM decisions d "
676
+ "JOIN decision_code_links l ON l.decision_uid = d.uid "
677
+ "WHERE l.file_path = ? AND l.line = ? "
678
+ "ORDER BY d.timestamp DESC LIMIT 20",
679
+ (file_path, line),
680
+ ).fetchall()
681
+ return [_row_to_decision(row) for row in rows]
682
+
683
+
684
+ def query_decisions_for_node_lines(
685
+ conn: sqlite3.Connection,
686
+ file_path: str,
687
+ line_start: int,
688
+ line_end: int,
689
+ ) -> list[Decision]:
690
+ """Return decisions linked to any line inside a node range (line-level)."""
691
+ rows = conn.execute(
692
+ "SELECT DISTINCT d.uid, d.content, d.reason, d.alternatives, d.status, d.source, "
693
+ "d.source_ref, d.timestamp, d.author, d.file_path, d.line, d.constraints, d.confidence, "
694
+ "d.category, d.tier "
695
+ "FROM decisions d "
696
+ "JOIN decision_code_links l ON l.decision_uid = d.uid "
697
+ "WHERE l.file_path = ? AND l.line >= ? AND l.line <= ? "
698
+ "ORDER BY d.timestamp DESC LIMIT 20",
699
+ (file_path, line_start, line_end),
700
+ ).fetchall()
701
+ return [_row_to_decision(row) for row in rows]
702
+
703
+
704
+ def query_decisions_at(
705
+ conn: sqlite3.Connection, at_time: datetime, scope: str = ""
706
+ ) -> list[Decision]:
707
+ """Return decisions known at a timestamp, optionally filtered by file prefix.
708
+
709
+ Uses decision.timestamp <= at_time (decisions are not retracted in MVP).
710
+ """
711
+ prefix = (scope or "").replace("\\", "/").rstrip("/")
712
+ sql = (
713
+ "SELECT uid, content, reason, alternatives, status, source, source_ref, timestamp, "
714
+ "author, file_path, line, constraints, confidence, category, tier FROM decisions "
715
+ "WHERE timestamp <= ? "
716
+ )
717
+ params: list[object] = [at_time.isoformat()]
718
+ if prefix and prefix != ".":
719
+ sql += "AND (file_path = ? OR file_path LIKE ? OR file_path = '') "
720
+ params.extend([prefix, prefix + "/%"])
721
+ sql += "ORDER BY timestamp ASC"
722
+ return [_row_to_decision(row) for row in conn.execute(sql, params).fetchall()]
723
+
724
+
725
+ def link_decision_to_lines(
726
+ conn: sqlite3.Connection,
727
+ decision_uid: str,
728
+ node_uid: str,
729
+ file_path: str,
730
+ lines: list[int],
731
+ commit_sha: str = "",
732
+ ) -> None:
733
+ """Insert decision->line links, ignoring duplicate (uid, file, line) keys."""
734
+ if not lines:
735
+ return
736
+ rows = [
737
+ (decision_uid, node_uid, file_path.replace("\\", "/"), int(ln), commit_sha)
738
+ for ln in lines
739
+ if ln and ln > 0
740
+ ]
741
+ conn.executemany(
742
+ "INSERT OR IGNORE INTO decision_code_links "
743
+ "(decision_uid, node_uid, file_path, line, commit_sha) VALUES (?, ?, ?, ?, ?)",
744
+ rows,
745
+ )
746
+ conn.commit()
747
+
748
+
749
+ def find_nodes_containing_lines(
750
+ conn: sqlite3.Connection, file_path: str, lines: list[int]
751
+ ) -> list[str]:
752
+ """Return distinct node uids whose range covers any of the given lines."""
753
+ if not lines:
754
+ return []
755
+ path = file_path.replace("\\", "/")
756
+ seen: list[str] = []
757
+ for ln in lines:
758
+ rows = conn.execute(
759
+ "SELECT DISTINCT uid FROM nodes "
760
+ "WHERE file_path = ? AND line_start <= ? AND line_end >= ? "
761
+ "ORDER BY (line_end - line_start) ASC LIMIT 5",
762
+ (path, ln, ln),
763
+ ).fetchall()
764
+ for (uid,) in rows:
765
+ if uid not in seen:
766
+ seen.append(uid)
767
+ return seen