devkb 0.2.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.
- devkb/__init__.py +11 -0
- devkb/audit.py +173 -0
- devkb/bench/add_packs.py +52 -0
- devkb/bench/cli_tasks.py +105 -0
- devkb/bench/confirm_tasks.py +149 -0
- devkb/bench/module_truth.py +249 -0
- devkb/bench/oco_tasks.py +216 -0
- devkb/bench/pipeline.py +313 -0
- devkb/bench/process_tasks.py +135 -0
- devkb/bench/report.py +74 -0
- devkb/bench/run.py +174 -0
- devkb/bench/truth_check.py +148 -0
- devkb/bench/workflow_report.py +64 -0
- devkb/bench/workflow_run.py +206 -0
- devkb/bench/workflow_tasks.py +227 -0
- devkb/build.py +258 -0
- devkb/build_symbols.py +1394 -0
- devkb/call_recall.py +159 -0
- devkb/cli.py +53 -0
- devkb/coverage.py +155 -0
- devkb/edge_truth.py +272 -0
- devkb/extractors/backlog.py +113 -0
- devkb/extractors/component_subsystem.py +116 -0
- devkb/extractors/configuration.py +267 -0
- devkb/extractors/files_tests.py +220 -0
- devkb/extractors/flows.py +117 -0
- devkb/extractors/lifecycle.py +258 -0
- devkb/extractors/members.py +160 -0
- devkb/extractors/pull_requests.py +271 -0
- devkb/extractors/releases.py +49 -0
- devkb/extractors/source_baseline.py +66 -0
- devkb/extractors/spec_docs.py +220 -0
- devkb/extractors/symbol_tests.py +131 -0
- devkb/extractors/test_inventory.py +38 -0
- devkb/extractors/ticket_similarity.py +193 -0
- devkb/extractors/tickets_git.py +151 -0
- devkb/extractors/warnings.py +230 -0
- devkb/extractors/work_units.py +90 -0
- devkb/github.py +515 -0
- devkb/gitutil.py +16 -0
- devkb/index.py +51 -0
- devkb/init.py +178 -0
- devkb/mcp_server.py +216 -0
- devkb/model.py +221 -0
- devkb/module_file_bridge.py +57 -0
- devkb/ontology.md +178 -0
- devkb/packs.py +462 -0
- devkb/process_api.py +1601 -0
- devkb/project_context.py +191 -0
- devkb/query.py +251 -0
- devkb/service.py +324 -0
- devkb/startup.py +103 -0
- devkb/test_discovery.py +76 -0
- devkb/ts_symbols.py +291 -0
- devkb-0.2.0.dist-info/METADATA +162 -0
- devkb-0.2.0.dist-info/RECORD +61 -0
- devkb-0.2.0.dist-info/WHEEL +5 -0
- devkb-0.2.0.dist-info/entry_points.txt +2 -0
- devkb-0.2.0.dist-info/licenses/LICENSE +202 -0
- devkb-0.2.0.dist-info/licenses/NOTICE +11 -0
- devkb-0.2.0.dist-info/top_level.txt +1 -0
devkb/ts_symbols.py
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
"""TypeScript/TSX Symbol extraction (devkb BL-3c, body/legs model).
|
|
2
|
+
|
|
3
|
+
Regex-based, mirroring discovery/extract_typescript.py's own established
|
|
4
|
+
approach (no TS parser in Python's stdlib, and the factory's discovery tooling already
|
|
5
|
+
established regex-over-source as an acceptable tradeoff for this class of
|
|
6
|
+
tool -- confirmed proven and shipped, not a shortcut unique to this file).
|
|
7
|
+
Extracts function/component/class-level Symbols -- discovery's own
|
|
8
|
+
extractor only goes to file (Module) level; this is the missing piece that
|
|
9
|
+
made the frontend invisible to devkb entirely (BL-3 was Python-only until
|
|
10
|
+
now, so 0 of any registered project's real TypeScript/React code -- the
|
|
11
|
+
actual user-facing behavior -- was in the graph at all).
|
|
12
|
+
|
|
13
|
+
Per-Symbol, also captures get/post/put(...) API-client call sites within
|
|
14
|
+
that symbol's own body -- porting extract_typescript.py's CALL_RE/
|
|
15
|
+
QUOTED_RE/DEFAULT_BASE_PARAM_RE/CONST_STR_RE patterns verbatim (same
|
|
16
|
+
regexes, same reasoning already proven against pms-web/src/lib/api.ts's
|
|
17
|
+
real 3 helper names) rather than reinventing the same regex differently.
|
|
18
|
+
This is the frontend half of BL-4b's cross-language CALLS_API edge --
|
|
19
|
+
resolution against real backend Symbols happens in build_symbols.py, which
|
|
20
|
+
has visibility into both languages; this module only extracts.
|
|
21
|
+
|
|
22
|
+
**Known remaining gap, confirmed live, not silently worked around**: OCO's
|
|
23
|
+
own `webapp/frontend/src/lib/api.ts` routes every call through a single
|
|
24
|
+
generic `apiFetch<T>(path, init?)` wrapper (HTTP method carried in `init`,
|
|
25
|
+
defaulting to GET) rather than three separately-named `get`/`post`/`put`
|
|
26
|
+
helpers -- `CALL_RE` (below, ported from `discovery/extract_typescript.py`)
|
|
27
|
+
doesn't match that shape, so `route_calls` comes back real-but-empty for
|
|
28
|
+
OCO even though Symbol extraction itself (including the object-literal
|
|
29
|
+
fix below) now correctly finds `api.qualityScore` etc. as real Symbols.
|
|
30
|
+
Not fixed here: it's a materially different call shape (an `init.method`
|
|
31
|
+
value to parse, not a function name), and `discovery/extract_typescript.py`
|
|
32
|
+
itself -- the already-shipped pattern this ports from -- has the exact
|
|
33
|
+
same gap (confirmed: its own `CALL_RE` also finds zero matches against
|
|
34
|
+
this file). Extending past what's already proven and shipped elsewhere in
|
|
35
|
+
this codebase is a real follow-up, not this pass's job.
|
|
36
|
+
|
|
37
|
+
Deliberately narrower than a real parser: only top-level `function Name(...)`,
|
|
38
|
+
`const Name = (...) => {...}`, `class Name`, and object-literal-method
|
|
39
|
+
entries (`export const pmsApi = { overview: () => get<T>("/overview") }`)
|
|
40
|
+
are extracted as Symbols. The object-literal case is not cosmetic --
|
|
41
|
+
confirmed live against both real frontends this was built for: ODSF's own
|
|
42
|
+
`pms-web/src/lib/api.ts` (`pmsApi = { overview: () => get<PMSOverview>
|
|
43
|
+
("/overview"), ... }`) and OCO's `webapp/frontend/src/lib/api.ts`
|
|
44
|
+
(`api = { graphStats: () => apiFetch<T>("/graph/stats"), ... }`) BOTH
|
|
45
|
+
route 100% of their real API calls through this shape, not a bare
|
|
46
|
+
top-level `function`/arrow-const -- without object-literal-method
|
|
47
|
+
detection, `CALLS_API` (BL-4b) produced zero edges on either project's
|
|
48
|
+
actual code. A call inside a genuinely undetected symbol's body (nested
|
|
49
|
+
object literals beyond the outer container, computed keys, spread) is
|
|
50
|
+
still simply not attributed to anything, not mis-attributed to the wrong
|
|
51
|
+
one -- the same precision-over-recall choice BL-4 already made.
|
|
52
|
+
"""
|
|
53
|
+
from __future__ import annotations
|
|
54
|
+
|
|
55
|
+
import re
|
|
56
|
+
from pathlib import Path
|
|
57
|
+
|
|
58
|
+
_FUNC_DECL_RE = re.compile(
|
|
59
|
+
r'^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(',
|
|
60
|
+
re.MULTILINE,
|
|
61
|
+
)
|
|
62
|
+
_ARROW_CONST_RE = re.compile(
|
|
63
|
+
r'^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?\([^)]*\)\s*(?::[^=]+)?=>\s*\{',
|
|
64
|
+
re.MULTILINE,
|
|
65
|
+
)
|
|
66
|
+
_CLASS_RE = re.compile(r'^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)', re.MULTILINE)
|
|
67
|
+
_OBJECT_LITERAL_RE = re.compile(
|
|
68
|
+
r'^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*\{',
|
|
69
|
+
re.MULTILINE,
|
|
70
|
+
)
|
|
71
|
+
_OBJECT_METHOD_RE = re.compile(
|
|
72
|
+
r'^\s*([A-Za-z_$][\w$]*)\s*:\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=]+)?=>\s*',
|
|
73
|
+
re.MULTILINE,
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
# Ported verbatim from discovery/extract_typescript.py -- same helper-name
|
|
77
|
+
# convention (pms-web/src/lib/api.ts's own get/post/put), same reasoning.
|
|
78
|
+
CALL_RE = re.compile(r'\b(get|post|put)(?:<[^>]*>)?\(\s*[`"]([^`"]+)[`"]([^)]*)\)')
|
|
79
|
+
QUOTED_RE = re.compile(r'[`"]([^`"]+)[`"]')
|
|
80
|
+
DEFAULT_BASE_PARAM_RE = re.compile(r'base\s*=\s*([A-Za-z_$][\w$]*)')
|
|
81
|
+
CONST_STR_RE = re.compile(r'\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*["\']([^"\']+)["\']')
|
|
82
|
+
|
|
83
|
+
_METHOD_MAP = {"get": "GET", "post": "POST", "put": "PUT"}
|
|
84
|
+
|
|
85
|
+
# ── ODSF-314: the call shapes OCO's frontend actually uses (CALLS_API was 0 there) ──────────────────────────────
|
|
86
|
+
# fetch(`/api/v1/jobs/${id}`, {method: "POST"}); a wrapper `apiFetch(path)` that prefixes a module constant;
|
|
87
|
+
# a URL builder `acknowledgeAnomalyUrl(id)` defined in one file and passed to fetch in another.
|
|
88
|
+
_TEMPLATE_PARAM = re.compile(r"\$\{\s*([A-Za-z_$][\w$.]*)?[^}]*\}")
|
|
89
|
+
_FETCH_LITERAL = re.compile(r"\bfetch\(\s*([`\"'])(.+?)\1(.{0,240})", re.S)
|
|
90
|
+
_FETCH_BUILDER = re.compile(r"\bfetch\(\s*([A-Za-z_$][\w$]*)\((.{0,240})", re.S)
|
|
91
|
+
_METHOD_OPT = re.compile(r"method\s*:\s*[`\"'](\w+)[`\"']")
|
|
92
|
+
_BUILDER_FN = re.compile(r"(?:export\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::\s*string)?\s*\{\s*return\s+([`\"'])(.+?)\2", re.S)
|
|
93
|
+
_BUILDER_ARROW = re.compile(r"(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*\([^)]*\)\s*(?::\s*string)?\s*=>\s*([`\"'])(.+?)\2", re.S)
|
|
94
|
+
_WRAPPER_FN = re.compile(r"function\s+([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(\s*([A-Za-z_$][\w$]*)\s*:\s*string[^)]*\)[^{]*\{(.{0,600})", re.S)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def normalise_path(raw: str, consts: dict[str, str]) -> str | None:
|
|
98
|
+
"""A URL as a route-shaped path: `${CONST}` becomes the constant's value, any other `${...}` a `{}` slot, the
|
|
99
|
+
query string and an origin are dropped, and a leading unknown base is dropped. None when it is not a path."""
|
|
100
|
+
def sub(m):
|
|
101
|
+
name = m.group(1) or ""
|
|
102
|
+
return consts.get(name, "{}")
|
|
103
|
+
path = _TEMPLATE_PARAM.sub(sub, raw.split("?")[0].strip())
|
|
104
|
+
path = re.sub(r"^https?://[^/]+", "", path)
|
|
105
|
+
while path.startswith("{}"):
|
|
106
|
+
path = path[2:]
|
|
107
|
+
path = path.rstrip("/")
|
|
108
|
+
return path if path.startswith("/") and len(path) > 1 else None
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def route_shape(path: str) -> str:
|
|
112
|
+
"""`/api/v1/jobs/{job_id}` and `/api/v1/jobs/{}` compare equal."""
|
|
113
|
+
return re.sub(r"\{[^}]*\}|<[^>]+>", "{}", path.rstrip("/"))
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def collect_url_helpers(files: list[Path]) -> tuple[dict[str, str], dict[str, str]]:
|
|
117
|
+
"""Repository-wide (builders, wrappers): a function returning a URL template, by name -> its path; a function
|
|
118
|
+
whose first string parameter is fetched behind a module constant, by name -> that prefix."""
|
|
119
|
+
builders: dict[str, str] = {}
|
|
120
|
+
wrappers: dict[str, str] = {}
|
|
121
|
+
for path in files:
|
|
122
|
+
try:
|
|
123
|
+
text = path.read_text(errors="replace")
|
|
124
|
+
except OSError:
|
|
125
|
+
continue
|
|
126
|
+
consts = dict(CONST_STR_RE.findall(text))
|
|
127
|
+
for rx in (_BUILDER_FN, _BUILDER_ARROW):
|
|
128
|
+
for name, _q, url in rx.findall(text):
|
|
129
|
+
norm = normalise_path(url, consts)
|
|
130
|
+
if norm:
|
|
131
|
+
builders.setdefault(name, norm)
|
|
132
|
+
for name, param, body in _WRAPPER_FN.findall(text):
|
|
133
|
+
m = re.search(r"fetch\(\s*`\$\{\s*([A-Za-z_$][\w$]*)\s*\}\$\{\s*" + re.escape(param) + r"\s*\}`", body)
|
|
134
|
+
if m and m.group(1) in consts:
|
|
135
|
+
wrappers.setdefault(name, consts[m.group(1)].rstrip("/"))
|
|
136
|
+
return builders, wrappers
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _method(tail: str, default: str = "GET") -> str:
|
|
140
|
+
m = _METHOD_OPT.search(tail.split(");")[0][:240]) # up to the end of this call, past any nested call's ")"
|
|
141
|
+
return m.group(1).upper() if m else default
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _matching_brace_end(text: str, open_brace_pos: int) -> int:
|
|
145
|
+
"""Index just past the closing brace matching the `{` at open_brace_pos,
|
|
146
|
+
via depth counting -- not string/comment-aware (a `{` inside a string
|
|
147
|
+
literal or comment can throw this off), the same class of imprecision
|
|
148
|
+
discovery/extract_typescript.py's own regex approach already accepts.
|
|
149
|
+
Unbalanced input (a parse this heuristic can't follow) falls back to
|
|
150
|
+
"rest of file" rather than raising."""
|
|
151
|
+
depth = 0
|
|
152
|
+
for i in range(open_brace_pos, len(text)):
|
|
153
|
+
if text[i] == "{":
|
|
154
|
+
depth += 1
|
|
155
|
+
elif text[i] == "}":
|
|
156
|
+
depth -= 1
|
|
157
|
+
if depth == 0:
|
|
158
|
+
return i + 1
|
|
159
|
+
return len(text)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _expr_body_end(text: str, start: int, container_end: int) -> int:
|
|
163
|
+
"""End of a single-expression arrow body (no `{...}` block) -- the
|
|
164
|
+
first top-level `,` before the enclosing object literal's own closing
|
|
165
|
+
brace, tracking paren/bracket/brace depth so a call's own commas
|
|
166
|
+
(`get<T>(a, b)`) don't end the body early. Not string/template-literal
|
|
167
|
+
aware, same class of imprecision `_matching_brace_end` already
|
|
168
|
+
accepts."""
|
|
169
|
+
depth = 0
|
|
170
|
+
i = start
|
|
171
|
+
while i < container_end:
|
|
172
|
+
c = text[i]
|
|
173
|
+
if c in "([{":
|
|
174
|
+
depth += 1
|
|
175
|
+
elif c in ")]}":
|
|
176
|
+
if depth == 0:
|
|
177
|
+
return i
|
|
178
|
+
depth -= 1
|
|
179
|
+
elif c == "," and depth == 0:
|
|
180
|
+
return i
|
|
181
|
+
i += 1
|
|
182
|
+
return container_end
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def _find_symbols(source: str) -> list[tuple[str, str, int, int, int]]:
|
|
186
|
+
"""[(name, kind, line_start, body_start, body_end), ...] -- body_start/
|
|
187
|
+
end bound the text a call-scan should search within for THIS symbol
|
|
188
|
+
only, not the whole file (the same function-body scoping BL-4 already
|
|
189
|
+
established for precision over recall)."""
|
|
190
|
+
out: list[tuple[str, str, int, int, int]] = []
|
|
191
|
+
for pat, kind in ((_FUNC_DECL_RE, "function"), (_ARROW_CONST_RE, "function"), (_CLASS_RE, "class")):
|
|
192
|
+
for m in pat.finditer(source):
|
|
193
|
+
name = m.group(1)
|
|
194
|
+
open_brace = source.find("{", m.end() - 1)
|
|
195
|
+
if open_brace == -1:
|
|
196
|
+
continue
|
|
197
|
+
body_end = _matching_brace_end(source, open_brace)
|
|
198
|
+
line_start = source.count("\n", 0, m.start()) + 1
|
|
199
|
+
out.append((name, kind, line_start, m.end(), body_end))
|
|
200
|
+
|
|
201
|
+
# Object-literal methods (`export const pmsApi = { overview: () =>
|
|
202
|
+
# get<T>("/overview"), ... }`) -- the real, dominant shape both real
|
|
203
|
+
# frontends this was built for actually use (see module docstring).
|
|
204
|
+
# Qualified by the outer container's own name, e.g. "pmsApi.overview" --
|
|
205
|
+
# entries in a container nested deeper than one level flatten onto the
|
|
206
|
+
# outermost container's name, an accepted approximation, not a full
|
|
207
|
+
# recursive object-literal parser.
|
|
208
|
+
for lit_m in _OBJECT_LITERAL_RE.finditer(source):
|
|
209
|
+
container_name = lit_m.group(1)
|
|
210
|
+
open_brace = source.find("{", lit_m.end() - 1)
|
|
211
|
+
if open_brace == -1:
|
|
212
|
+
continue
|
|
213
|
+
container_end = _matching_brace_end(source, open_brace)
|
|
214
|
+
for em in _OBJECT_METHOD_RE.finditer(source, open_brace, container_end):
|
|
215
|
+
entry_name = em.group(1)
|
|
216
|
+
line_start = source.count("\n", 0, em.start()) + 1
|
|
217
|
+
body_start = em.end()
|
|
218
|
+
if body_start < len(source) and source[body_start] == "{":
|
|
219
|
+
body_end = _matching_brace_end(source, body_start)
|
|
220
|
+
else:
|
|
221
|
+
body_end = _expr_body_end(source, body_start, container_end)
|
|
222
|
+
out.append((f"{container_name}.{entry_name}", "function", line_start, body_start, body_end))
|
|
223
|
+
return out
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def extract_file_calls(body: str, consts: dict[str, str], builders: dict[str, str], wrappers: dict[str, str]) -> list[tuple[str, str]]:
|
|
227
|
+
"""(method, normalised path) for each API call in a symbol's body (ODSF-314 shapes)."""
|
|
228
|
+
out: list[tuple[str, str]] = []
|
|
229
|
+
for _q, url, tail in _FETCH_LITERAL.findall(body):
|
|
230
|
+
norm = normalise_path(url, consts)
|
|
231
|
+
if norm:
|
|
232
|
+
out.append((_method(tail), norm))
|
|
233
|
+
for name, tail in _FETCH_BUILDER.findall(body):
|
|
234
|
+
if name in builders:
|
|
235
|
+
out.append((_method(tail), builders[name]))
|
|
236
|
+
for name, prefix in wrappers.items():
|
|
237
|
+
for m in re.finditer(r"\b" + re.escape(name) + r"(?:<[^>]*>)?\(\s*([`\"'])(.+?)\1(.{0,240})", body, re.S):
|
|
238
|
+
norm = normalise_path(m.group(2), consts)
|
|
239
|
+
if norm:
|
|
240
|
+
out.append((_method(m.group(3)), prefix + norm))
|
|
241
|
+
return out
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def extract_file(path: Path, repo_root: Path, helpers: tuple[dict[str, str], dict[str, str]] | None = None,
|
|
245
|
+
) -> tuple[list[dict], list[tuple[str, str, str]]]:
|
|
246
|
+
"""Returns (symbols, route_calls) for one .ts/.tsx file.
|
|
247
|
+
symbols: [{qualified_name (bare name, no nesting -- top-level only),
|
|
248
|
+
kind, line_start}, ...]
|
|
249
|
+
route_calls: [(symbol_qualified_name, method, path), ...] -- the
|
|
250
|
+
frontend half of BL-4b; build_symbols.py resolves these against real
|
|
251
|
+
backend Symbol routes, this function has no visibility into those."""
|
|
252
|
+
try:
|
|
253
|
+
source = path.read_text(errors="replace")
|
|
254
|
+
except OSError:
|
|
255
|
+
return [], []
|
|
256
|
+
|
|
257
|
+
consts = dict(CONST_STR_RE.findall(source))
|
|
258
|
+
default_base_match = DEFAULT_BASE_PARAM_RE.search(source)
|
|
259
|
+
default_base = consts.get(default_base_match.group(1), "") if default_base_match else ""
|
|
260
|
+
|
|
261
|
+
symbols: list[dict] = []
|
|
262
|
+
route_calls: list[tuple[str, str, str]] = []
|
|
263
|
+
for name, kind, line_start, body_start, body_end in _find_symbols(source):
|
|
264
|
+
symbols.append({"qualified_name": name, "kind": kind, "line_start": line_start})
|
|
265
|
+
|
|
266
|
+
body = source[body_start:body_end]
|
|
267
|
+
for m in CALL_RE.finditer(body):
|
|
268
|
+
helper, call_path, rest = m.group(1), m.group(2), m.group(3)
|
|
269
|
+
if call_path.startswith("$") or "{" in call_path:
|
|
270
|
+
# ODSF-314: a template path is still a route, with its interpolations as parameter slots
|
|
271
|
+
norm = normalise_path(call_path, consts)
|
|
272
|
+
if norm:
|
|
273
|
+
route_calls.append((name, _METHOD_MAP[helper], norm))
|
|
274
|
+
continue
|
|
275
|
+
trailing_quoted = QUOTED_RE.findall(rest)
|
|
276
|
+
explicit_base = trailing_quoted[-1] if trailing_quoted else None
|
|
277
|
+
base = explicit_base if explicit_base is not None else default_base
|
|
278
|
+
route_calls.append((name, _METHOD_MAP[helper], f"{base}{call_path}"))
|
|
279
|
+
builders, wrappers = helpers or ({}, {})
|
|
280
|
+
for method, call_path in extract_file_calls(body, consts, builders, wrappers):
|
|
281
|
+
route_calls.append((name, method, call_path))
|
|
282
|
+
return symbols, route_calls
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
def list_ts_files(repo_root: Path) -> list[Path]:
|
|
286
|
+
return sorted(
|
|
287
|
+
p for p in repo_root.rglob("*")
|
|
288
|
+
if p.suffix in (".ts", ".tsx")
|
|
289
|
+
and "node_modules" not in p.parts and ".next" not in p.parts and p.name.endswith((".ts", ".tsx"))
|
|
290
|
+
and not p.name.endswith(".d.ts")
|
|
291
|
+
)
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: devkb
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server
|
|
5
|
+
Author: Hung T. Le
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Repository, https://github.com/namiq-ai/devkb
|
|
8
|
+
Project-URL: Issues, https://github.com/namiq-ai/devkb/issues
|
|
9
|
+
Project-URL: Benchmark, https://github.com/namiq-ai/devkb/blob/main/docs/BENCHMARK.md
|
|
10
|
+
Keywords: knowledge graph,software development agents,coding agents,mcp,code intelligence,call graph,software process
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Software Development
|
|
21
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
License-File: NOTICE
|
|
26
|
+
Requires-Dist: pyyaml>=6
|
|
27
|
+
Provides-Extra: mcp
|
|
28
|
+
Requires-Dist: mcp<2,>=1.23; extra == "mcp"
|
|
29
|
+
Provides-Extra: study
|
|
30
|
+
Requires-Dist: scipy>=1.10; extra == "study"
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
33
|
+
Requires-Dist: mcp<2,>=1.23; extra == "dev"
|
|
34
|
+
Requires-Dist: scipy>=1.10; extra == "dev"
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
|
|
37
|
+
# devkb
|
|
38
|
+
|
|
39
|
+
[](https://doi.org/10.5281/zenodo.24267143)
|
|
40
|
+
|
|
41
|
+
**A knowledge graph of your repository for software development agents.** Agents answer "what calls this, what breaks, which tests"
|
|
42
|
+
in one step instead of searching file by file: 55% cheaper, with better answers, in our benchmark.
|
|
43
|
+
|
|
44
|
+
<picture>
|
|
45
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/img/benchmark-dark.svg">
|
|
46
|
+
<img alt="Median cost per task: plain search $0.070 (quality 0.931); devkb 12 tools $0.059, 18% cheaper (0.955); devkb 7 tools $0.040, 38% cheaper (0.963); devkb pack $0.025, 55% cheaper (0.981)" src="docs/img/benchmark-light.svg">
|
|
47
|
+
</picture>
|
|
48
|
+
|
|
49
|
+
## 1. What devkb is
|
|
50
|
+
|
|
51
|
+
- **A graph** built from your source and git history: functions, calls, tests, routes, errors, configuration,
|
|
52
|
+
commits, pull requests, tickets ([ontology](devkb/ontology.md)).
|
|
53
|
+
- **Packs**: one command answers a whole question (who calls this, what breaks, which tests to run), each item with
|
|
54
|
+
the source line that proves it, and a statement of what the graph could not see.
|
|
55
|
+
- **An MCP server** giving agents the same answers as tools, for Claude Code, Codex and any MCP client.
|
|
56
|
+
|
|
57
|
+
Everything runs locally: devkb reads files and runs `git`, never your code (unless `devkb.json` opts in), and the graph never leaves your machine.
|
|
58
|
+
|
|
59
|
+
### Languages
|
|
60
|
+
|
|
61
|
+
| Language | Status | What devkb understands |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| Python | ✅ Supported | functions, classes, calls (through imports, re-exports, typed objects, base classes), tests, FastAPI/Flask routes, raised and logged errors, environment variables; every pack |
|
|
64
|
+
| TypeScript, TSX | 🟡 Partial | functions, components, classes, and the HTTP calls they make to backend routes; not calls between them |
|
|
65
|
+
| JavaScript (`.js`, `.mjs`) | 🟡 Partial | as TypeScript |
|
|
66
|
+
| Odoo XML | 🟡 Partial | templates and menus |
|
|
67
|
+
| Bash / shell | ⬜ Not yet | files and history only |
|
|
68
|
+
| C, C++, Java, Rust, Go, C#, others | ⬜ Not yet | files and history only |
|
|
69
|
+
|
|
70
|
+
"Files and history" is the language-independent layer every repository gets: files, commits, pull requests and
|
|
71
|
+
tickets.
|
|
72
|
+
|
|
73
|
+
## 2. How much it saves
|
|
74
|
+
|
|
75
|
+
Latest benchmark: the 7 open-source repositories in [`bench/repos.yaml`](bench/repos.yaml), 57 tasks, 1,138 agent
|
|
76
|
+
runs, the same model (Sonnet) in every arm, answers scored against truth computed from the source. Cost, turns and
|
|
77
|
+
tokens are the median run; saving is per task against plain search, averaged over tasks; quality is the mean score:
|
|
78
|
+
|
|
79
|
+
| | Plain search | devkb, 12 tools | devkb, 7 tools | devkb pack |
|
|
80
|
+
|---|---|---|---|---|
|
|
81
|
+
| **Cost per task** | $0.070 | $0.059 | $0.040 | **$0.025** |
|
|
82
|
+
| **Saving** | — | 18% | 38% | **55%** |
|
|
83
|
+
| **Quality** (0–1) | 0.931 | 0.955 (+0.024) | 0.963 (+0.032) | **0.981 (+0.050)** |
|
|
84
|
+
| Turns | 4 | 6 | 5 | **3** |
|
|
85
|
+
| Context processed (tokens) | 126k | 169k | 147k | **75k** |
|
|
86
|
+
| of which cache reads | 123k | 163k | 141k | 74k |
|
|
87
|
+
| of which new input and cache writes | 8.3k | 4.1k | 2.0k | 1.3k |
|
|
88
|
+
| Output tokens | 1.4k | 1.8k | 1.3k | 0.9k |
|
|
89
|
+
|
|
90
|
+
Saving and quality gain by repository (95% intervals in the results):
|
|
91
|
+
|
|
92
|
+
| Repository | Tasks | 7 tools: saving / quality | pack: saving / quality |
|
|
93
|
+
|---|---|---|---|
|
|
94
|
+
| lnbits | 10 | 53% / +0.032 | **66%** / +0.049 |
|
|
95
|
+
| Netflix Dispatch | 8 | 45% / +0.040 | **61%** / +0.081 |
|
|
96
|
+
| Prefect | 9 | 41% / −0.017 | **59%** / +0.047 |
|
|
97
|
+
| lattice-scan | 12 | 36% / +0.052 | **51%** / +0.058 |
|
|
98
|
+
| Mealie | 6 | 18% / +0.095 | **42%** / +0.062 |
|
|
99
|
+
| devkb | 4 | 1% / +0.004 | **40%** / +0.004 |
|
|
100
|
+
| click | 8 | 6% / +0.016 | 15% / +0.023 |
|
|
101
|
+
|
|
102
|
+
The saving is in call chains (66–77% on tasks that trace an error or a change to the route handlers that reach it);
|
|
103
|
+
on one-hop questions, as in click, plain search is already good. An earlier pre-registered study (30 held-out tasks,
|
|
104
|
+
1,020 runs, two model sizes) found packs 41% cheaper and the lean tools 35% ([`study/`](study/); `make verify`
|
|
105
|
+
recomputes it). Details and corrections: [`bench/results/2026-11-15-registry`](bench/results/2026-11-15-registry/);
|
|
106
|
+
add a repository: [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
|
|
107
|
+
|
|
108
|
+
## 3. Set up
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
pip install "devkb[mcp]"
|
|
112
|
+
cd your-repo
|
|
113
|
+
devkb init --hooks
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
This builds the graph into `.devkb/`, adds a short devkb section to `AGENTS.md` and `CLAUDE.md`, registers the MCP
|
|
117
|
+
server in `.mcp.json`, and rebuilds the graph after each commit. Your own content in those files is kept;
|
|
118
|
+
`devkb init --remove` undoes it.
|
|
119
|
+
|
|
120
|
+
Ask it directly:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
devkb pack --project . refactor my_function # who calls it, which tests
|
|
124
|
+
devkb pack --project . error "message text" # which route handlers reach it
|
|
125
|
+
devkb pack --project . file path/to/file.py # before editing a file
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Your agent
|
|
129
|
+
|
|
130
|
+
**Claude Code**: nothing more to do. `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the
|
|
131
|
+
instructions. Start `claude` in the repository, approve the `devkb` server when asked, and check it with `/mcp`.
|
|
132
|
+
|
|
133
|
+
**Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{"mcpServers": {"devkb": {"command": "devkb", "args": ["mcp", "--project", ".", "--toolset", "lean-pack"]}}}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
**Codex**: add to `~/.codex/config.toml`:
|
|
140
|
+
|
|
141
|
+
```toml
|
|
142
|
+
[mcp_servers.devkb]
|
|
143
|
+
command = "devkb"
|
|
144
|
+
args = ["mcp", "--project", ".", "--toolset", "lean-pack"]
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Codex and Cursor read the instructions in `AGENTS.md`; Claude Code reads them through `CLAUDE.md`.
|
|
148
|
+
|
|
149
|
+
What agents get by default (`--toolset lean-pack`): a `pack` tool that returns a whole answer in one call, and the
|
|
150
|
+
seven single-question tools. The instructions tell them to ask for a pack when a question follows a chain (a file
|
|
151
|
+
before editing, a change, an error) and to search as usual for a one-hop lookup, which is where the benchmark found
|
|
152
|
+
the saving and where it did not. Measured with agents asking for the pack themselves (lnbits and Dispatch, 400 runs):
|
|
153
|
+
53% cheaper than plain search with the highest quality of any arm, against 42% for the seven tools alone
|
|
154
|
+
([`bench/results/2026-11-15-lean-pack`](bench/results/2026-11-15-lean-pack/)).
|
|
155
|
+
|
|
156
|
+
## 4. Licence and citation
|
|
157
|
+
|
|
158
|
+
Code: [Apache-2.0](LICENSE). The study in [`study/`](study/) (paper, figures, pre-registration, data):
|
|
159
|
+
[CC BY 4.0](study/LICENSE). Benchmark results quote third-party code under its own licences
|
|
160
|
+
([`bench/results/NOTICE`](bench/results/NOTICE)). Releases: [`docs/RELEASING.md`](docs/RELEASING.md).
|
|
161
|
+
|
|
162
|
+
> Hung T. Le. *Precomputed Context, Not More Tools: A Pre-Registered Study of Process Graphs for Coding Agents.* 2026.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
devkb/__init__.py,sha256=O5q8anVDql91x_pmNPGcWc7wE_P7rkVHji9Vx3pbaHI,616
|
|
2
|
+
devkb/audit.py,sha256=A-158J2t9lVg-fuaOw7GscWROkYmQnkaIRO9hr6ohs8,8765
|
|
3
|
+
devkb/build.py,sha256=xmpZ-GG0g8jcIUEO25zqUfdxJ9bqvpd4inThX7GLEok,12747
|
|
4
|
+
devkb/build_symbols.py,sha256=zyPPvsLZ-nwpIfUlEi1DlKffdGt66ZSlwnTKOH_vZts,72782
|
|
5
|
+
devkb/call_recall.py,sha256=H8rTJ_O-0Pl_NqOelkpm6jKK-wwA_vT-8dV5ZytmR3c,6873
|
|
6
|
+
devkb/cli.py,sha256=LN_vxCtzroKggw1YWHMVN5tv0-TJsTGSA4TEao_3UX4,1941
|
|
7
|
+
devkb/coverage.py,sha256=sCLre1le2qceZegPDejQZIw9jK0Kx9dAh119NpkBVZ4,7032
|
|
8
|
+
devkb/edge_truth.py,sha256=ouT8z1O0Ijdpq1TLIhKHnfvs0-4NJCG3NiUzQv2LC9k,12714
|
|
9
|
+
devkb/github.py,sha256=BrrdwrwXfS0qfNrKrJWjj-lliainZyW2dv89ZQIXG00,25792
|
|
10
|
+
devkb/gitutil.py,sha256=FJiAhggpE_tThsUZkDXuHsyAIMyBM3dikWLuF5sZT5k,616
|
|
11
|
+
devkb/index.py,sha256=x-l2SyfHPdh69vvuA9cq_n4aN7HqsLuZBUNZ6Rp8VnM,1924
|
|
12
|
+
devkb/init.py,sha256=ZknV1tG6UOw56Cfh1SusK11gwxofVxCr9lzARhW8YH0,8462
|
|
13
|
+
devkb/mcp_server.py,sha256=nmwKDrKMDNEwRfjoJnEZOS8-tmetWRuBLXQ-ydX6JBA,11247
|
|
14
|
+
devkb/model.py,sha256=bX8RDdazil6OtMTnQ84KXiGtneuLNXXBS7-Ej-Wi57A,10197
|
|
15
|
+
devkb/module_file_bridge.py,sha256=TGeEH5gFT1_pdc4Em_ELE--KSh1ErZJfxE0g1OGvxvs,2546
|
|
16
|
+
devkb/ontology.md,sha256=WLZP3VEcMv5Fhaw8gGMMD2v5HK4PdnbI6agaoF08GZA,18592
|
|
17
|
+
devkb/packs.py,sha256=vOMLOC21gIozvGFIreS1_Rfop1hfl0QEkHflU4u7MGU,28462
|
|
18
|
+
devkb/process_api.py,sha256=M08SgOoi9_hEey7ZmhhaCLbJsTTKzRPgUad8ztnsHuw,96970
|
|
19
|
+
devkb/project_context.py,sha256=Sw8dwK1R-Pm9wObNDdmCOCkhuJ0ZWk5QrD5uHsd152w,9489
|
|
20
|
+
devkb/query.py,sha256=sMVlPmKtkm3bgYOu8sVzHI54zf-4mytlNWNr2HQ8ihs,10885
|
|
21
|
+
devkb/service.py,sha256=QmBz8YjESSdkGiZK-OXJCQqBmPcPQvI08XqoGM6hkSE,15342
|
|
22
|
+
devkb/startup.py,sha256=dAAra5q3tZcxyqDTebEM0wT3efenakFtGXEys_wlOrA,4776
|
|
23
|
+
devkb/test_discovery.py,sha256=65l5jGbVhPP5S96b0--CF6z3Nla7KHz1WO1y5sBFJAA,3116
|
|
24
|
+
devkb/ts_symbols.py,sha256=U2J5tT93c2nFIkJ2a76wPY_S0jpS-wShFROxX3p7QuM,14805
|
|
25
|
+
devkb/bench/add_packs.py,sha256=f2siiU1dS5aOdn0bveZI_qJy_o-FUCIlCxnV8DMyLIc,1968
|
|
26
|
+
devkb/bench/cli_tasks.py,sha256=lVDv9ZR8gvU7Z0AneQqLJNyGTILFNNh_lQZSOzy5CAo,4902
|
|
27
|
+
devkb/bench/confirm_tasks.py,sha256=ZCQQS1lSzIFgPJNX6bleFmAwkrNymMNJJVQHLkob1Es,7729
|
|
28
|
+
devkb/bench/module_truth.py,sha256=7wCP5wPFpjHDfXWPxltHeiphzM7clugtxzWWI3o0EM0,11765
|
|
29
|
+
devkb/bench/oco_tasks.py,sha256=1Cyb84gKH6hoD-qOv9UE8Mgwyuz1AyyxngJGVJFcbKs,12463
|
|
30
|
+
devkb/bench/pipeline.py,sha256=0CHioo69cXwpXmpGMGZWK49wHHF1qBDLmC8VuIomefg,16314
|
|
31
|
+
devkb/bench/process_tasks.py,sha256=IGIEmBbIq0_kwZ3eWtTa-0YcTPWFg02NldFODo5geqM,6584
|
|
32
|
+
devkb/bench/report.py,sha256=Zp1H_8miBZlqna_t4RHBWQpgclTg3w1hQfpHJlpio0Y,3111
|
|
33
|
+
devkb/bench/run.py,sha256=RTHewqWFPoTQO3SJBE1W5pnadmJ4lnr0vw9pEa9VXLk,8757
|
|
34
|
+
devkb/bench/truth_check.py,sha256=j_9f-Q5vxL81jSSStoJhvOPYyESkDP0UMJfMsUOUvmI,7230
|
|
35
|
+
devkb/bench/workflow_report.py,sha256=XupmfGFYqIoVFN0xUXVkR-bK6S05q2gxqKq07s7w7Ew,2851
|
|
36
|
+
devkb/bench/workflow_run.py,sha256=9T5qivW_dTlTFpI3X6c7fhGF6OBtNz7D-_ryGl7lWWM,12162
|
|
37
|
+
devkb/bench/workflow_tasks.py,sha256=dA_SfEti3KaBtF5Dqo3MTki64jB1rkdEY2PkduLTRpU,11456
|
|
38
|
+
devkb/extractors/backlog.py,sha256=eqPAMNfCN7Pqj_PSuSs4KsCMcYQWMX6oU2jD00gIJ2w,4255
|
|
39
|
+
devkb/extractors/component_subsystem.py,sha256=kbv_akJKYehiDKmFaDJh0GRwOz43R1dmwAViPnRfj0s,4950
|
|
40
|
+
devkb/extractors/configuration.py,sha256=DaOJxKcLFmgXJLEVE3fiNCNk9zS-bwH2AzagH5pO3YI,12907
|
|
41
|
+
devkb/extractors/files_tests.py,sha256=POAbsWBLM1mPeLlsGtz2XYx4FNzt6mJI6LksgqmHRDI,11026
|
|
42
|
+
devkb/extractors/flows.py,sha256=x2D3nJ1bCScKgYK9Vb6i5280_0IE8xnVbho7ApdGTvM,5141
|
|
43
|
+
devkb/extractors/lifecycle.py,sha256=DduwMKSHd4Po5RbRgupFo2GfFGgf8bkynpvCwkltgN4,11833
|
|
44
|
+
devkb/extractors/members.py,sha256=sVI5B5YyyzMxWqBAyb422rzWkUhYpj_iXXQQoD1wzKw,7636
|
|
45
|
+
devkb/extractors/pull_requests.py,sha256=hSPuIpMx4E-r8tdlAQpjRqGkxVAQx3GbZk8jcMhZP3A,14513
|
|
46
|
+
devkb/extractors/releases.py,sha256=_snlSqMxxkvsauP39gtmpUCelqckYwjMAzanIVzWEv0,1900
|
|
47
|
+
devkb/extractors/source_baseline.py,sha256=0IgULo8kbDtD0_2EWOfiBP10jxYP6JxN_RNPSZUIgao,2965
|
|
48
|
+
devkb/extractors/spec_docs.py,sha256=Lzzi3VOTXeEVxNIyH7uf8pmAXpR2iV3uuf5yngxuZ_w,10331
|
|
49
|
+
devkb/extractors/symbol_tests.py,sha256=HgmH0ghWsx5mGqJ4axc4INWEOYkjh88-1AXMHJ1FIcU,6577
|
|
50
|
+
devkb/extractors/test_inventory.py,sha256=OIJ02X0XBByuR30PZl4hU77RWDvxh1EGN-w-40zH2tQ,1597
|
|
51
|
+
devkb/extractors/ticket_similarity.py,sha256=WpYIaSlLFhfJ1Z8_QNeEIw-mJEXtu2rcAjwqO22fciA,9924
|
|
52
|
+
devkb/extractors/tickets_git.py,sha256=JRflFngL_w8GlZ-KarFf3QK2JB3pEGsU_GiQPCcP-Bo,6244
|
|
53
|
+
devkb/extractors/warnings.py,sha256=sfR53S4_s2fVKSkpsRGy9O5VVHnhUYLXpm1tG_ZXSkQ,10557
|
|
54
|
+
devkb/extractors/work_units.py,sha256=6fAcAHPI-FVPHJxnJgtkGtSu8bk8qSWJMN6wmaDHPDM,3984
|
|
55
|
+
devkb-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
56
|
+
devkb-0.2.0.dist-info/licenses/NOTICE,sha256=C0Tp2eLG0fnkr1YD2DiZWPhQGq6K9G-oUmqiiAo6qTM,532
|
|
57
|
+
devkb-0.2.0.dist-info/METADATA,sha256=l4rhZiVx5yxduZg29eBRgQR7-S0uHeo1-21XxjELGTY,8023
|
|
58
|
+
devkb-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
59
|
+
devkb-0.2.0.dist-info/entry_points.txt,sha256=dMyM4r2uYlB7SeL3keNXA2pWtRrwmRSLBEBHiJ4qbtg,41
|
|
60
|
+
devkb-0.2.0.dist-info/top_level.txt,sha256=vM5y5cuKDRtyO6ZKtD-BzBzoJzMzuE8DhRGYsbWRSnQ,6
|
|
61
|
+
devkb-0.2.0.dist-info/RECORD,,
|