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,698 @@
1
+ """Rule-based decision extraction (no LLM)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import re
7
+ from datetime import datetime
8
+
9
+ from codegraph.models import (
10
+ Decision,
11
+ DecisionSource,
12
+ DecisionStatus,
13
+ DecisionTier,
14
+ make_uid,
15
+ )
16
+
17
+ # Keywords that signal a design rationale in prose. Deliberately narrow: a word
18
+ # like "since"/"must be"/"to support" matches ordinary English and used to turn
19
+ # release notes into "decisions".
20
+ DECISION_KEYWORDS: tuple[str, ...] = (
21
+ "because",
22
+ "tradeoff",
23
+ "trade-off",
24
+ "instead of",
25
+ "rather than",
26
+ "chose",
27
+ "we chose",
28
+ "we picked",
29
+ "we decided",
30
+ "decided",
31
+ "so that",
32
+ "in order to",
33
+ "switched to",
34
+ "migrated to",
35
+ "for performance",
36
+ "for security",
37
+ "for simplicity",
38
+ "for compatibility",
39
+ "for reliability",
40
+ "this avoids",
41
+ "this prevents",
42
+ "avoids",
43
+ "prevents",
44
+ "due to",
45
+ "because of",
46
+ "as a result of",
47
+ "opted for",
48
+ "in favor of",
49
+ "to reduce",
50
+ "to avoid",
51
+ "to prevent",
52
+ "to simplify",
53
+ "to fix",
54
+ "to resolve",
55
+ "resolves",
56
+ )
57
+
58
+ # Clause markers that introduce the *reason* half of a decision.
59
+ _REASON_MARKERS: tuple[str, ...] = (
60
+ " because ",
61
+ " so that ",
62
+ " in order to ",
63
+ " due to ",
64
+ " because of ",
65
+ " as a result of ",
66
+ " to fix ",
67
+ " to avoid ",
68
+ " to prevent ",
69
+ " to reduce ",
70
+ " to simplify ",
71
+ " for performance ",
72
+ " for security ",
73
+ " for simplicity ",
74
+ " for compatibility ",
75
+ " for reliability ",
76
+ )
77
+
78
+ # Clause markers that introduce a *rejected alternative*.
79
+ _ALT_MARKERS: tuple[str, ...] = (
80
+ " instead of ",
81
+ " rather than ",
82
+ " in favor of ",
83
+ )
84
+
85
+ _SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+|\n+")
86
+ _BULLET_PREFIX = re.compile(r"^\s*[-*+]\s+")
87
+ _WORD = re.compile(r"[A-Za-z][A-Za-z0-9_\-]*")
88
+
89
+ CONVENTIONAL_COMMIT = re.compile(
90
+ r"^(?P<type>feat|fix|refactor|perf|docs|ci|chore|test|build)(\([^)]+\))?:\s*(?P<subject>.+)$",
91
+ re.IGNORECASE,
92
+ )
93
+
94
+ BULLET_RE = re.compile(r"^\s*[-*+]\s+(?P<text>.+)$", re.MULTILINE)
95
+
96
+
97
+ def join_wrapped_lines(text: str) -> str:
98
+ """Join hard-wrapped paragraph lines back into sentences.
99
+
100
+ A commit body is wrapped at ~72 columns, so one sentence spans several lines:
101
+
102
+ We want to have the "completion" command for such programs because it
103
+ will allow the completion of flags and of arguments (if provided
104
+ by the program).
105
+
106
+ Splitting per line produced a decision whose reason was just "because it".
107
+ Paragraphs are separated by a blank line, and a line opening a bullet starts
108
+ its own paragraph, so both stay distinct after joining.
109
+ """
110
+ out: list[str] = []
111
+ buffer: list[str] = []
112
+ for raw in (text or "").splitlines():
113
+ line = raw.rstrip()
114
+ if not line.strip():
115
+ if buffer:
116
+ out.append(" ".join(buffer))
117
+ buffer = []
118
+ continue
119
+ if _BULLET_PREFIX.match(line) and buffer:
120
+ out.append(" ".join(buffer))
121
+ buffer = []
122
+ buffer.append(line.strip())
123
+ if buffer:
124
+ out.append(" ".join(buffer))
125
+ return "\n\n".join(out)
126
+
127
+
128
+ def split_sentences(text: str) -> list[str]:
129
+ """Split text into sentence-like fragments, dropping list markers."""
130
+ parts = [_BULLET_PREFIX.sub("", p).strip() for p in _SENTENCE_SPLIT.split(text)]
131
+ return [p for p in parts if p]
132
+
133
+
134
+ def split_commit_parts(message: str) -> tuple[str, list[str]]:
135
+ """Split a commit message into (subject, body_bullets_or_paragraphs)."""
136
+ lines = (message or "").splitlines()
137
+ subject = lines[0].strip() if lines else ""
138
+ body = "\n".join(lines[1:]).strip()
139
+ bullets = [m.group("text").strip() for m in BULLET_RE.finditer(body) if m.group("text").strip()]
140
+ if bullets:
141
+ return subject, bullets
142
+ if body:
143
+ # Join the wrap before splitting: `_SENTENCE_SPLIT` breaks on newlines, so a
144
+ # sentence spanning two lines became a fragment ending mid-clause
145
+ # ("because it").
146
+ return subject, [p for p in split_sentences(join_wrapped_lines(body)) if p]
147
+ return subject, []
148
+
149
+
150
+ def looks_like_decision(sentence: str) -> bool:
151
+ """Return True when a sentence contains decision rationale keywords."""
152
+ lower = sentence.lower()
153
+ return any(k in lower for k in DECISION_KEYWORDS)
154
+
155
+
156
+ _STRUCTURAL_SECTIONS = frozenset(
157
+ {
158
+ "changed",
159
+ "changes",
160
+ "removed",
161
+ "added",
162
+ "fixed",
163
+ "deprecated",
164
+ "security",
165
+ "breaking",
166
+ "unreleased",
167
+ "changelog",
168
+ "notes",
169
+ "improvements",
170
+ "improvement",
171
+ "features",
172
+ "feature",
173
+ "bug fixes",
174
+ "bugfixes",
175
+ "fixes",
176
+ "docs",
177
+ "documentation",
178
+ "performance",
179
+ "tests",
180
+ "refactor",
181
+ "maintenance",
182
+ "dependencies",
183
+ "deps",
184
+ "breaking changes",
185
+ "other changes",
186
+ }
187
+ )
188
+ _SECTION_PREFIX = re.compile(r"^(?P<head>[^:]{1,40}):\s+(?P<body>\S.*)$")
189
+ # A sentence cut mid-clause starts with one of these; a real decision does not.
190
+ _FRAGMENT_LEADS = frozenset(
191
+ {
192
+ "now",
193
+ "also",
194
+ "thus",
195
+ "so",
196
+ "then",
197
+ "therefore",
198
+ "however",
199
+ "instead",
200
+ "further",
201
+ "additionally",
202
+ "moreover",
203
+ }
204
+ )
205
+ _IDENTIFIER_HINT = re.compile(r"[A-Z0-9_`\[\]()\-]")
206
+ _TRAILING = " .,;:"
207
+ # "use sqlite" is two words but a statement; "same run" is two words of debris.
208
+ _DECISION_VERBS = frozenset(
209
+ {
210
+ "use",
211
+ "prefer",
212
+ "switch",
213
+ "replace",
214
+ "drop",
215
+ "remove",
216
+ "add",
217
+ "keep",
218
+ "avoid",
219
+ "revert",
220
+ "migrate",
221
+ "adopt",
222
+ "choose",
223
+ "chose",
224
+ "disable",
225
+ "enable",
226
+ "store",
227
+ "parse",
228
+ "cache",
229
+ "bump",
230
+ "rename",
231
+ "move",
232
+ "require",
233
+ "allow",
234
+ "reject",
235
+ "deprecate",
236
+ "support",
237
+ "expose",
238
+ "return",
239
+ "accept",
240
+ "validate",
241
+ "configure",
242
+ "defer",
243
+ "merge",
244
+ "split",
245
+ "extract",
246
+ "load",
247
+ "run",
248
+ }
249
+ )
250
+
251
+
252
+ _HEAD_NOISE = re.compile(r"[^\w\s]+")
253
+
254
+
255
+ def _section_head(head: str) -> str:
256
+ """Normalise a section heading for lookup: drop emoji, symbols and case.
257
+
258
+ Release logs are full of "🚀 Improvements:" and "Bug fixes:"; the emoji should
259
+ not stop the heading from being recognised as structural noise.
260
+ """
261
+ cleaned = _HEAD_NOISE.sub(" ", head or "")
262
+ return " ".join(cleaned.split()).strip().lower()
263
+
264
+
265
+ def decision_text_body(text: str) -> str:
266
+ """Return the statement part of a decision, without a section heading.
267
+
268
+ Changelog extraction passes "Changed: bullet" and "Version 3.2.0: bullet" in,
269
+ so the heading has to be recognised for both the readability fix (a card
270
+ should not read "Changed: ...") and the fragment check.
271
+ """
272
+ match = _SECTION_PREFIX.match(text or "")
273
+ if not match:
274
+ return (text or "").strip()
275
+ return match.group("body").strip()
276
+
277
+
278
+ _DANGLING_TAIL = frozenset(
279
+ {
280
+ "and",
281
+ "or",
282
+ "but",
283
+ "with",
284
+ "without",
285
+ "to",
286
+ "of",
287
+ "for",
288
+ "in",
289
+ "on",
290
+ "at",
291
+ "by",
292
+ "as",
293
+ "than",
294
+ "the",
295
+ "a",
296
+ "an",
297
+ "e.g",
298
+ "i.e",
299
+ "such",
300
+ "like",
301
+ "including",
302
+ }
303
+ )
304
+
305
+
306
+ def clean_clause(text: str) -> str:
307
+ """Trim a clause that was cut mid-phrase.
308
+
309
+ A sentence split at "because" or "instead of" can leave a dangling tail:
310
+ "to avoid errors from version mismatches (e.g." ends inside a parenthesis and
311
+ on a conjunction. An unbalanced open bracket is removed with everything after
312
+ it, and trailing connector words are dropped, so a card never ends mid-thought.
313
+ """
314
+ value = " ".join((text or "").split()).strip()
315
+ while value.count("(") > value.count(")") and "(" in value:
316
+ value = value[: value.rfind("(")].strip()
317
+ words = value.rstrip(" .,;:").split()
318
+ while words and words[-1].lower().strip(".,;:") in _DANGLING_TAIL:
319
+ words.pop()
320
+ return " ".join(words).rstrip(" .,;:")
321
+
322
+
323
+ def polish_decision_content(text: str) -> str:
324
+ """Make a decision read like a sentence instead of a clause fragment.
325
+
326
+ Structural headings are dropped, dangling clause tails are trimmed, sentences
327
+ are capitalised, and trailing punctuation is removed. Version headings
328
+ ("Version 3.2.0: ...") are kept, because they tell the reader which release
329
+ introduced the change.
330
+ """
331
+ value = " ".join((text or "").split()).strip().rstrip(_TRAILING)
332
+ match = _SECTION_PREFIX.match(value)
333
+ if match and _section_head(match.group("head")) in _STRUCTURAL_SECTIONS:
334
+ value = match.group("body").strip()
335
+ value = clean_clause(value)
336
+ first = value.split(" ", 1)[0] if value else ""
337
+ # demo.html and --file are names, not sentences: capitalising them would
338
+ # rename the thing the card is about.
339
+ is_name = any(ch in first for ch in "./_-`") or any(c.isupper() for c in first)
340
+ if value and value[0].isalpha() and value[0].islower() and not is_name:
341
+ value = value[0].upper() + value[1:]
342
+ return value
343
+
344
+
345
+ def polish_alternative(text: str) -> str:
346
+ """Normalize an alternative without touching its spelling.
347
+
348
+ Alternatives are frequently package names or identifiers (`safe-buffer`,
349
+ `setuptools`), so capitalising them would change what they name. Only
350
+ whitespace and a dangling tail are normalised.
351
+ """
352
+ return clean_clause(" ".join((text or "").split()).strip().rstrip("."))
353
+
354
+
355
+ def is_usable_decision_content(text: str) -> bool:
356
+ """True when a decision's content stands on its own.
357
+
358
+ A decision card that reads "now bracket the range" or "Update" is worse than
359
+ no card: it teaches the reader to ignore the feature. Fragments are dropped
360
+ only for decisions — a plain commit subject is still kept as history.
361
+ """
362
+ raw = decision_text_body(" ".join((text or "").split()).strip().rstrip(_TRAILING))
363
+ words = raw.split()
364
+ if len(words) < 2:
365
+ return False
366
+ first = words[0].lower().strip(",")
367
+ if first in _FRAGMENT_LEADS:
368
+ return False
369
+ if len(words) >= 3 or first in _DECISION_VERBS:
370
+ return True
371
+ return any(_IDENTIFIER_HINT.search(w) for w in words)
372
+
373
+
374
+ def split_content_reason(sentence: str) -> tuple[str, str]:
375
+ """Split a rationale sentence into (content, reason)."""
376
+ text = " ".join(sentence.strip().split())
377
+ lower = text.lower()
378
+ for marker in _REASON_MARKERS:
379
+ idx = lower.find(marker)
380
+ if idx > 0:
381
+ left = text[:idx].strip().rstrip(",;:")
382
+ right = text[idx:].strip()
383
+ if left:
384
+ return left[:220], right[:500]
385
+ return text[:220], ""
386
+
387
+
388
+ def split_decision_parts(sentence: str) -> tuple[str, str, list[str]]:
389
+ """Split one sentence into (content, reason, alternatives).
390
+
391
+ "use node:buffer instead of safe-buffer" yields content "use node:buffer"
392
+ and alternatives ["safe-buffer"]; a "because ..." clause becomes the reason.
393
+ A clause is only read as an alternative when the sentence looks complete —
394
+ a fragment cut mid-phrase ("... upsert instead of calling") would otherwise
395
+ produce a meaningless alternative.
396
+ """
397
+ text = " ".join((sentence or "").strip().split())
398
+ alternatives: list[str] = []
399
+ complete = text.endswith((".", ")", "`", "!", "?"))
400
+ lower = text.lower()
401
+ for marker in _ALT_MARKERS:
402
+ idx = lower.find(marker)
403
+ if idx > 0 and complete:
404
+ alternative = text[idx + len(marker) :].strip().rstrip(".")
405
+ if len(alternative.split()) >= 1:
406
+ alternatives.append(alternative[:180])
407
+ text = text[:idx].strip().rstrip(",;:")
408
+ break
409
+ content, reason = split_content_reason(text)
410
+ return content, reason, alternatives
411
+
412
+
413
+ def classify_tier(content: str, reason: str, alternatives: list[str]) -> DecisionTier:
414
+ """A record is a decision only when it states why or what it rejected."""
415
+ if (reason or "").strip() or alternatives:
416
+ return DecisionTier.DECISION
417
+ return DecisionTier.EVENT
418
+
419
+
420
+ def content_fingerprint(text: str) -> str:
421
+ """Return a stable 8-hex-char fingerprint of decision content.
422
+
423
+ `hash()` is salted per process, so it cannot be used in a persisted uid;
424
+ blake2b gives the same value in every process and on every machine.
425
+ """
426
+ normalized = " ".join((text or "").split()).lower()
427
+ return hashlib.blake2b(normalized.encode("utf-8"), digest_size=4).hexdigest()
428
+
429
+
430
+ def decision_from_sentence(
431
+ sentence: str,
432
+ *,
433
+ source: DecisionSource,
434
+ source_ref: str,
435
+ timestamp: datetime,
436
+ author: str = "",
437
+ file_path: str = "",
438
+ line: int | None = None,
439
+ uid_prefix: str = "dec",
440
+ confidence: float = 0.55,
441
+ category: str = "design",
442
+ tier: DecisionTier | None = None,
443
+ ) -> Decision | None:
444
+ """Build a Decision from one sentence, or None for an unusable fragment.
445
+
446
+ Args:
447
+ tier: Force a tier; when omitted it is derived from the sentence
448
+ (reason or rejected alternative => decision, otherwise event).
449
+ """
450
+ raw_content, reason, alternatives = split_decision_parts(sentence)
451
+ reason = clean_clause(reason)
452
+ content = polish_decision_content(raw_content)
453
+ alternatives = [polish_alternative(a) for a in alternatives if a.strip()]
454
+ if len(content) > 220:
455
+ content = content[:217] + "..."
456
+ resolved_tier = tier or classify_tier(content, reason, alternatives)
457
+ # A decision has to read like a statement; a clause fragment is not one. Plain
458
+ # history (events) is kept even when terse, because it is still a record.
459
+ if resolved_tier is DecisionTier.DECISION and not is_usable_decision_content(raw_content):
460
+ return None
461
+ uid = make_uid(file_path or source_ref, "decision", uid_prefix, max(line or 1, 1))
462
+ uid = f"{uid}::{content_fingerprint(content)}"
463
+ return Decision(
464
+ uid=uid,
465
+ content=content,
466
+ reason=reason,
467
+ alternatives=alternatives,
468
+ status=DecisionStatus.ACCEPTED,
469
+ source=source,
470
+ source_ref=source_ref,
471
+ timestamp=timestamp,
472
+ author=author,
473
+ file_path=file_path,
474
+ line=line,
475
+ constraints=[],
476
+ confidence=confidence,
477
+ category=category,
478
+ tier=resolved_tier,
479
+ )
480
+
481
+
482
+ def decision_from_commit_subject(
483
+ message: str,
484
+ *,
485
+ source_ref: str,
486
+ timestamp: datetime,
487
+ author: str = "",
488
+ file_path: str = "",
489
+ ) -> Decision | None:
490
+ """Build one record from a commit subject line.
491
+
492
+ Every commit subject becomes a record. It is a *decision* only when the
493
+ subject itself states a reason or a rejected alternative — or when it is a
494
+ dependency bump that says why (for example "to fix CVE-2026-12590").
495
+ """
496
+ subject, _body = split_commit_parts(message)
497
+ if not subject:
498
+ return None
499
+ match = CONVENTIONAL_COMMIT.match(subject)
500
+ subject_text = match.group("subject").strip() if match else subject.strip()
501
+ if not subject_text:
502
+ return None
503
+
504
+ dep = is_dependency_commit(subject) or is_dependency_commit(subject_text)
505
+ content, reason, alternatives = split_decision_parts(subject_text)
506
+ tier = classify_tier(content, reason, alternatives)
507
+ if tier is DecisionTier.DECISION:
508
+ confidence = 0.65 if dep else 0.6
509
+ else:
510
+ confidence = 0.5
511
+ return decision_from_sentence(
512
+ subject_text,
513
+ source=DecisionSource.COMMIT,
514
+ source_ref=source_ref,
515
+ timestamp=timestamp,
516
+ author=author,
517
+ file_path=file_path,
518
+ uid_prefix="commit-subject",
519
+ confidence=confidence,
520
+ category="dependency" if dep else "design",
521
+ tier=tier,
522
+ )
523
+
524
+
525
+ def decisions_from_commit_body(
526
+ message: str,
527
+ *,
528
+ source_ref: str,
529
+ timestamp: datetime,
530
+ author: str = "",
531
+ file_path: str = "",
532
+ ) -> list[Decision]:
533
+ """Extract records from commit body bullets / paragraphs.
534
+
535
+ A bullet becomes a decision only when it carries a reason or a rejected
536
+ alternative; otherwise it is kept as a low-confidence event.
537
+ """
538
+ _subject, parts = split_commit_parts(message)
539
+ out: list[Decision] = []
540
+ for part in parts:
541
+ if not looks_like_decision(part):
542
+ continue
543
+ content, reason, alternatives = split_decision_parts(part)
544
+ tier = classify_tier(content, reason, alternatives)
545
+ decision = decision_from_sentence(
546
+ part,
547
+ source=DecisionSource.COMMIT,
548
+ source_ref=source_ref,
549
+ timestamp=timestamp,
550
+ author=author,
551
+ file_path=file_path,
552
+ uid_prefix="commit-body",
553
+ confidence=0.7 if tier is DecisionTier.DECISION else 0.55,
554
+ tier=tier,
555
+ )
556
+ if decision is not None:
557
+ out.append(decision)
558
+ return out
559
+
560
+
561
+ def extract_decisions_from_text(
562
+ text: str,
563
+ *,
564
+ source: DecisionSource,
565
+ source_ref: str,
566
+ timestamp: datetime,
567
+ author: str = "",
568
+ file_path: str = "",
569
+ confidence: float = 0.55,
570
+ category: str = "design",
571
+ tier: DecisionTier | None = None,
572
+ ) -> list[Decision]:
573
+ """Extract decision-like sentences from free text.
574
+
575
+ Args:
576
+ tier: Force the tier for every hit; when omitted each sentence is
577
+ classified on its own (reason/alternative => decision).
578
+ """
579
+ found: list[Decision] = []
580
+ for sentence in split_sentences(text):
581
+ if not looks_like_decision(sentence):
582
+ continue
583
+ decision = decision_from_sentence(
584
+ sentence,
585
+ source=source,
586
+ source_ref=source_ref,
587
+ timestamp=timestamp,
588
+ author=author,
589
+ file_path=file_path,
590
+ uid_prefix=source.value,
591
+ confidence=confidence,
592
+ category=category,
593
+ tier=tier,
594
+ )
595
+ if decision is not None:
596
+ found.append(decision)
597
+ return found
598
+
599
+
600
+ def parse_adr_markdown(text: str) -> dict[str, str]:
601
+ """Parse a simple ADR markdown file into sections."""
602
+ sections: dict[str, str] = {}
603
+ current = "title"
604
+ buf: list[str] = []
605
+ for line in text.splitlines():
606
+ heading = re.match(r"^#{1,6}\s+(.*)$", line.strip())
607
+ if heading:
608
+ if buf:
609
+ sections[current] = "\n".join(buf).strip()
610
+ buf = []
611
+ title = heading.group(1).strip().lower()
612
+ current = _normalize_heading(title)
613
+ continue
614
+ buf.append(line)
615
+ if buf:
616
+ sections[current] = "\n".join(buf).strip()
617
+ return sections
618
+
619
+
620
+ def _normalize_heading(title: str) -> str:
621
+ """Map ADR heading variants to canonical keys."""
622
+ if "status" in title:
623
+ return "status"
624
+ if "context" in title:
625
+ return "context"
626
+ if "decision" in title or "chosen" in title:
627
+ return "decision"
628
+ if "consequence" in title:
629
+ return "consequences"
630
+ if "alternative" in title or "option" in title:
631
+ return "alternatives"
632
+ if "title" in title or title.startswith("adr"):
633
+ return "title"
634
+ return title or "body"
635
+
636
+
637
+ def decision_from_adr_sections(
638
+ sections: dict[str, str],
639
+ *,
640
+ source_ref: str,
641
+ timestamp: datetime,
642
+ file_path: str,
643
+ ) -> Decision | None:
644
+ """Build one Decision from parsed ADR sections."""
645
+ content = sections.get("decision") or sections.get("title") or ""
646
+ if not content.strip():
647
+ return None
648
+ content = split_sentences(content)[0][:220]
649
+ status_raw = (sections.get("status") or "accepted").strip().lower()
650
+ status = DecisionStatus.ACCEPTED
651
+ if "reject" in status_raw:
652
+ status = DecisionStatus.REJECTED
653
+ elif "super" in status_raw or "replac" in status_raw:
654
+ status = DecisionStatus.SUPERSEDED
655
+
656
+ alternatives: list[str] = []
657
+ alt_text = sections.get("alternatives") or ""
658
+ for sentence in split_sentences(alt_text)[:5]:
659
+ alternatives.append(sentence[:180])
660
+
661
+ constraints: list[str] = []
662
+ for sentence in split_sentences(sections.get("consequences") or "")[:5]:
663
+ constraints.append(sentence[:180])
664
+
665
+ uid = make_uid(file_path, "decision", "adr", 1)
666
+ return Decision(
667
+ uid=uid,
668
+ content=content,
669
+ reason=(sections.get("context") or sections.get("decision") or "")[:500],
670
+ alternatives=alternatives,
671
+ status=status,
672
+ source=DecisionSource.ADR,
673
+ source_ref=source_ref,
674
+ timestamp=timestamp,
675
+ author="",
676
+ file_path=file_path,
677
+ line=None,
678
+ constraints=constraints,
679
+ confidence=0.8,
680
+ tier=DecisionTier.DECISION,
681
+ )
682
+
683
+
684
+ DEPENDENCY_RE = re.compile(
685
+ r"^(build\(deps|chore\(deps|deps(\([^)]*\))?:|bump |update .* to v?\d|dependabot)",
686
+ re.IGNORECASE,
687
+ )
688
+
689
+ # "bump qs from 6.5.2 to 6.5.3" / "bump body-parser to ^2.3.0"
690
+ DEPENDENCY_BUMP_RE = re.compile(
691
+ r"\bbump[s]?\b[^.]*\b(from|to)\b", re.IGNORECASE
692
+ )
693
+
694
+
695
+ def is_dependency_commit(text: str) -> bool:
696
+ """Return True when a commit subject looks like a dependency bump."""
697
+ value = (text or "").strip()
698
+ return bool(DEPENDENCY_RE.match(value) or DEPENDENCY_BUMP_RE.search(value))