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
|
@@ -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))
|