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/process_api.py
ADDED
|
@@ -0,0 +1,1601 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Software-engineering-process questions over the devkb graph (ODSF-306).
|
|
3
|
+
|
|
4
|
+
Each method answers one question a development stage asks and returns a short
|
|
5
|
+
JSON-able dict: ids and paths, not node dumps. Every reply carries `_meta`
|
|
6
|
+
(when the graph was built, at which commit, whether the repository has moved
|
|
7
|
+
on) so a caller can tell a fresh answer from a stale one.
|
|
8
|
+
|
|
9
|
+
python3 devkb/process_api.py --project ODSF graph-status
|
|
10
|
+
python3 devkb/process_api.py --project ODSF callers _load_process depth=2
|
|
11
|
+
python3 devkb/process_api.py --project ODSF tests-to-run files=devkb/build_symbols.py
|
|
12
|
+
python3 devkb/process_api.py --project ODSF bench
|
|
13
|
+
|
|
14
|
+
Stage map (the AI SDLC playbook, S0 to S10): sdlc_context and find_docs serve
|
|
15
|
+
S0-S4, trace serves S5-S6, symbol/callers/callees/tests_for/impact/tests_to_run/
|
|
16
|
+
owner serve S1 and S7, review_pack serves S8, lineage serves S9-S10.
|
|
17
|
+
"""
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import argparse
|
|
21
|
+
import json
|
|
22
|
+
import math
|
|
23
|
+
import os
|
|
24
|
+
import re
|
|
25
|
+
import statistics
|
|
26
|
+
import subprocess
|
|
27
|
+
import sys
|
|
28
|
+
import time
|
|
29
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
30
|
+
from pathlib import Path
|
|
31
|
+
|
|
32
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
|
33
|
+
|
|
34
|
+
from devkb.project_context import CONFIG_FILES, registry, resolve, run_repo_scripts # noqa: E402
|
|
35
|
+
from devkb.service import CompactIndex, Staleness, Telemetry, load_index, words # noqa: E402
|
|
36
|
+
from devkb.test_discovery import _JS_TEST, _PY_TEST # noqa: E402
|
|
37
|
+
|
|
38
|
+
_TICKET_ID = re.compile(r"\b[A-Z][A-Z0-9]{1,6}-\d+\b")
|
|
39
|
+
# ODSF writes `### OWN:`; OCO writes `### YOU OWN:`, `### YOU OWN (read + write freely):` or `### TL OWNS:`.
|
|
40
|
+
_OWN = re.compile(r"### (?:YOU OWN|OWN|[A-Z]{2,3} OWNS)\b[^\n]*:\s*```[\w]*\n(.*?)```", re.DOTALL)
|
|
41
|
+
_DNT = re.compile(r"### DO NOT TOUCH:\s*```[\w]*\n(.*?)```", re.DOTALL)
|
|
42
|
+
_HUNK = re.compile(r"^@@ -\S+ \+(\d+)(?:,(\d+))? @@", re.MULTILINE)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
REPLY_BUDGET_BYTES = 3900
|
|
46
|
+
# Words that carry no meaning in a request ("add a report for the specs"). Without this, "add" matches every method called add.
|
|
47
|
+
STOP = frozenset("the and for add with that this from into how new use when why not are can has have was but its any all".split())
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def query_words(text: str) -> list[str]:
|
|
51
|
+
return [w for w in words(text) if w not in STOP]
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _fit(reply: dict, budget: int = REPLY_BUDGET_BYTES) -> dict:
|
|
55
|
+
"""Keep a reply under `budget` bytes by halving its longest list until it fits, and say what was left out.
|
|
56
|
+
A `limit` caps one list; a reply with two long lists (callers and indirect callers of a hub class) still
|
|
57
|
+
overran 4 KB, so the size itself is now enforced (ODSF-309). Totals such as `n` stay exact."""
|
|
58
|
+
omitted: dict[str, int] = {}
|
|
59
|
+
|
|
60
|
+
def size() -> int:
|
|
61
|
+
return len(json.dumps(reply, separators=(",", ":")))
|
|
62
|
+
|
|
63
|
+
while size() > budget:
|
|
64
|
+
lists = [(k, v) for k, v in reply.items() if isinstance(v, list) and len(v) > 3]
|
|
65
|
+
if not lists:
|
|
66
|
+
break
|
|
67
|
+
key, items = max(lists, key=lambda kv: len(json.dumps(kv[1], separators=(",", ":"))))
|
|
68
|
+
keep = max(3, len(items) // 2)
|
|
69
|
+
omitted[key] = omitted.get(key, 0) + len(items) - keep
|
|
70
|
+
reply[key] = items[:keep]
|
|
71
|
+
if omitted:
|
|
72
|
+
reply["truncated"] = True
|
|
73
|
+
reply["omitted"] = omitted
|
|
74
|
+
return reply
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
_GENERATED = re.compile(r"(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|poetry\.lock|uv\.lock|Cargo\.lock)$|"
|
|
78
|
+
r"\.min\.(js|css)$|(^|/)(dist|build|node_modules|__pycache__|\.next[^/]*)/")
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def is_generated_path(path: str) -> bool:
|
|
82
|
+
"""Lockfiles, minified and built output: never a place to read or edit, so never listed in an answer (ODSF-313)."""
|
|
83
|
+
return bool(_GENERATED.search(path))
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
_TEST_TREE = re.compile(r"(^|/)(tests?/[^/].*\.py|conftest\.py)$")
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def is_test_path(path: str) -> bool:
|
|
90
|
+
"""Test code: a test module by name, or any Python file in a tests/ or test/ tree (fixtures, helpers, conftest),
|
|
91
|
+
since a change that breaks those breaks the test run just the same."""
|
|
92
|
+
return bool(_PY_TEST.search(path) or _JS_TEST.search(path) or _TEST_TREE.search(path))
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _lines(block: str) -> list[str]:
|
|
96
|
+
"""Paths from a profile's fenced block. An indented line is relative to the directory line above it (OCO writes
|
|
97
|
+
`scripts/` then ` extractors/extract_*.py`); a glob is cut to the prefix before its first `*`; comments after
|
|
98
|
+
`←`, `→`, `#` or `,` are dropped."""
|
|
99
|
+
out: list[str] = []
|
|
100
|
+
parents: list[tuple[int, str]] = []
|
|
101
|
+
for line in block.splitlines():
|
|
102
|
+
clean = re.split(r"[←→#,]|\s{2,}", line.strip())[0].strip()
|
|
103
|
+
if not clean:
|
|
104
|
+
continue
|
|
105
|
+
indent = len(line) - len(line.lstrip())
|
|
106
|
+
while parents and parents[-1][0] >= indent:
|
|
107
|
+
parents.pop()
|
|
108
|
+
full = (parents[-1][1] if parents else "") + clean
|
|
109
|
+
if clean.endswith("/"):
|
|
110
|
+
parents.append((indent, full))
|
|
111
|
+
full = full.split("*", 1)[0]
|
|
112
|
+
if full and full not in out:
|
|
113
|
+
out.append(full)
|
|
114
|
+
# A directory line with lines indented under it is a heading for them, not a claim on the whole directory.
|
|
115
|
+
return [p for p in out if not (p.endswith("/") and any(q != p and q.startswith(p) for q in out))]
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def project_for(cwd: Path) -> str | None:
|
|
119
|
+
"""The registered project whose repository contains `cwd`, so a daemon job started in a
|
|
120
|
+
project's checkout needs no project argument. The deepest match wins."""
|
|
121
|
+
best, code = -1, None
|
|
122
|
+
for entry in registry():
|
|
123
|
+
try:
|
|
124
|
+
repo = Path(entry["repo"]).resolve()
|
|
125
|
+
cwd.resolve().relative_to(repo)
|
|
126
|
+
except (KeyError, ValueError, OSError):
|
|
127
|
+
continue
|
|
128
|
+
if len(str(repo)) > best:
|
|
129
|
+
best, code = len(str(repo)), entry.get("code")
|
|
130
|
+
return code
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class ProcessAPI:
|
|
134
|
+
def __init__(self, code: str, use_cache: bool = True, telemetry: bool = True, devkb_dir: Path | None = None) -> None:
|
|
135
|
+
"""`devkb_dir` (or the DEVKB_DIR environment variable) points at a pinned graph
|
|
136
|
+
snapshot instead of the project's live `.devkb/`, which any build overwrites.
|
|
137
|
+
The benchmark relies on this so every run reads the same graph. DEVKB_REPO points at the
|
|
138
|
+
checkout that snapshot was built from, so history, diffs and staleness are read there too."""
|
|
139
|
+
# ODSF-315: an explicitly external repository (a public project in a benchmark), never a silent default
|
|
140
|
+
if os.environ.get("DEVKB_EXTERNAL") == "1" and os.environ.get("DEVKB_REPO") and os.environ.get("DEVKB_DIR"):
|
|
141
|
+
from devkb.project_context import external_context # noqa: PLC0415
|
|
142
|
+
self.ctx = external_context(code, Path(os.environ["DEVKB_REPO"]), Path(os.environ["DEVKB_DIR"]))
|
|
143
|
+
else:
|
|
144
|
+
self.ctx = resolve(code)
|
|
145
|
+
self.root: Path = Path(os.environ["DEVKB_REPO"]).resolve() if os.environ.get("DEVKB_REPO") else self.ctx.repo_root
|
|
146
|
+
store = devkb_dir or (Path(os.environ["DEVKB_DIR"]) if os.environ.get("DEVKB_DIR") else self.ctx.devkb_dir)
|
|
147
|
+
self.idx: CompactIndex = load_index(self.ctx.code, self.root, store, use_cache)
|
|
148
|
+
self.stale = Staleness(self.root, self.idx.git_head)
|
|
149
|
+
self.tel = Telemetry(store, telemetry)
|
|
150
|
+
self._roles: dict[str, dict[str, list[str]]] | None = None
|
|
151
|
+
self._roles_key: tuple | None = None
|
|
152
|
+
self._cfg: dict = {}
|
|
153
|
+
self._cfg_stamp: tuple | None = None
|
|
154
|
+
self._moved_cache: dict[str, set[str]] = {}
|
|
155
|
+
self._fn_cache: dict[tuple[str, str], list[tuple[int, int, str]]] = {}
|
|
156
|
+
self._bmad_status: tuple | None = None
|
|
157
|
+
self._written: dict[tuple, str] = {} # (doc, mtime, graph head) -> date of the doc's last commit
|
|
158
|
+
|
|
159
|
+
# ── plumbing ───────────────────────────────────────────────────────────
|
|
160
|
+
def call(self, tool: str, **kw) -> dict:
|
|
161
|
+
t0 = time.perf_counter()
|
|
162
|
+
ok = True
|
|
163
|
+
try:
|
|
164
|
+
reply = getattr(self, tool)(**kw)
|
|
165
|
+
except TypeError as exc:
|
|
166
|
+
reply, ok = {"error": f"bad arguments for {tool}: {exc}"}, False
|
|
167
|
+
if "error" in reply:
|
|
168
|
+
ok = False
|
|
169
|
+
else:
|
|
170
|
+
if os.environ.get("DEVKB_NO_COVERAGE") == "1": # ODSF-316 ablation only: the reply as it was before ODSF-313
|
|
171
|
+
reply.pop("coverage", None)
|
|
172
|
+
reply = _fit(reply)
|
|
173
|
+
stale, head, behind = self.stale.check()
|
|
174
|
+
reply["_meta"] = {"built": self.idx.built_at[:16], "head": self.idx.git_head[:8], "stale": stale,
|
|
175
|
+
**({"behind": behind} if stale else {})}
|
|
176
|
+
size = len(json.dumps(reply, separators=(",", ":")))
|
|
177
|
+
self.tel.log(tool, (time.perf_counter() - t0) * 1000, size, ok)
|
|
178
|
+
return reply
|
|
179
|
+
|
|
180
|
+
def _key(self, i: int) -> str:
|
|
181
|
+
return self.idx.keys[i]
|
|
182
|
+
|
|
183
|
+
def _resolve(self, ref: str) -> tuple[int | None, dict | None]:
|
|
184
|
+
idx = self.idx
|
|
185
|
+
if "::" in ref:
|
|
186
|
+
i = idx.node("Symbol", ref)
|
|
187
|
+
return (i, None) if i is not None else (None, {"error": f"no symbol {ref}"})
|
|
188
|
+
cands = idx.short.get(ref.rsplit(".", 1)[-1], [])
|
|
189
|
+
if len(cands) == 1:
|
|
190
|
+
return cands[0], None
|
|
191
|
+
if not cands:
|
|
192
|
+
return None, {"error": f"no symbol named {ref}"}
|
|
193
|
+
return None, {"error": f"{len(cands)} symbols named {ref}; pass one as path::name",
|
|
194
|
+
"matches": [self._key(c) for c in cands[:8]]}
|
|
195
|
+
|
|
196
|
+
def _file_symbols(self, ref: str) -> list[int]:
|
|
197
|
+
return self.idx.sym_by_file.get(ref, [])
|
|
198
|
+
|
|
199
|
+
def _callers(self, start: set[int], depth: int) -> list[list[int]]:
|
|
200
|
+
"""Reverse CALLS BFS: one list of symbol indexes per depth level."""
|
|
201
|
+
seen = set(start)
|
|
202
|
+
frontier = set(start)
|
|
203
|
+
levels: list[list[int]] = []
|
|
204
|
+
for _ in range(depth):
|
|
205
|
+
nxt: set[int] = set()
|
|
206
|
+
for s in frontier:
|
|
207
|
+
for c in self.idx.sources("CALLS", s):
|
|
208
|
+
if c not in seen:
|
|
209
|
+
seen.add(c)
|
|
210
|
+
nxt.add(c)
|
|
211
|
+
levels.append(sorted(nxt, key=lambda i: (is_test_path(self._key(i).split("::")[0]), self._key(i))))
|
|
212
|
+
frontier = nxt
|
|
213
|
+
return levels
|
|
214
|
+
|
|
215
|
+
def _tests_of(self, syms: list[int]) -> dict[str, set[str]]:
|
|
216
|
+
found: dict[str, set[str]] = {}
|
|
217
|
+
for s in syms:
|
|
218
|
+
for tc in self.idx.targets("TESTED_BY", s):
|
|
219
|
+
p = self.idx.props[tc]
|
|
220
|
+
if p.get("file"):
|
|
221
|
+
found.setdefault(p["file"], set()).add(p.get("function", "?"))
|
|
222
|
+
for c in self.idx.sources("CALLS", s):
|
|
223
|
+
path, _, qual = self._key(c).partition("::")
|
|
224
|
+
if is_test_path(path):
|
|
225
|
+
found.setdefault(path, set()).add(qual.rsplit(".", 1)[-1])
|
|
226
|
+
return found
|
|
227
|
+
|
|
228
|
+
@staticmethod
|
|
229
|
+
def _run_line(files: list[str]) -> str:
|
|
230
|
+
py = [f for f in files if f.endswith(".py")]
|
|
231
|
+
return ("python3 -m pytest " + " ".join(py) + " -q") if py else ""
|
|
232
|
+
|
|
233
|
+
def _config(self) -> dict:
|
|
234
|
+
"""The project's devkb.json (or pms.config.json), parsed again only when the file changed."""
|
|
235
|
+
path = next((self.root / n for n in CONFIG_FILES if (self.root / n).is_file()), self.root / CONFIG_FILES[0])
|
|
236
|
+
try:
|
|
237
|
+
st = path.stat()
|
|
238
|
+
except OSError:
|
|
239
|
+
return {}
|
|
240
|
+
stamp = (st.st_mtime_ns, st.st_size)
|
|
241
|
+
if stamp != self._cfg_stamp:
|
|
242
|
+
try:
|
|
243
|
+
self._cfg = json.loads(path.read_text())
|
|
244
|
+
except (OSError, ValueError):
|
|
245
|
+
self._cfg = {}
|
|
246
|
+
self._cfg_stamp = stamp
|
|
247
|
+
return self._cfg
|
|
248
|
+
|
|
249
|
+
def _roles_dir(self) -> Path:
|
|
250
|
+
return self.root / str(self._config().get("roles_dir") or "sdp/process/roles")
|
|
251
|
+
|
|
252
|
+
def _role_file(self, code: str) -> str | None:
|
|
253
|
+
return self._role_file_in(self.root, self._config(), code)
|
|
254
|
+
|
|
255
|
+
@staticmethod
|
|
256
|
+
def _role_file_in(root: Path, cfg: dict, code: str) -> str | None:
|
|
257
|
+
"""A role's profile file in the roles directory: `<code>.md` or the first `<code>-*.md`, case-insensitive."""
|
|
258
|
+
try:
|
|
259
|
+
names = sorted(p.name for p in (root / str(cfg.get("roles_dir") or "sdp/process/roles")).glob("*.md"))
|
|
260
|
+
except OSError:
|
|
261
|
+
return None
|
|
262
|
+
return next((n for n in names if n.lower().startswith(code.lower() + "-") or n.lower() == code.lower() + ".md"), None)
|
|
263
|
+
|
|
264
|
+
def _profiles(self) -> dict[str, str]:
|
|
265
|
+
"""Role code -> profile file. A project that declares no `role_profiles` (OCO) still has a roster in
|
|
266
|
+
`team_roles` and the factory's default file names; project_paths is the one place that says so (ODSF-095)."""
|
|
267
|
+
declared = self._config().get("role_profiles")
|
|
268
|
+
if isinstance(declared, dict) and declared:
|
|
269
|
+
return {str(k): str(v) for k, v in declared.items()}
|
|
270
|
+
roster = self._config().get("team_roles")
|
|
271
|
+
if not isinstance(roster, list) or not roster:
|
|
272
|
+
return {}
|
|
273
|
+
return {str(c).strip().upper(): f for c in roster if (f := self._role_file(str(c).strip().upper()))}
|
|
274
|
+
|
|
275
|
+
def _role_table(self) -> dict[str, dict[str, list[str]]]:
|
|
276
|
+
roles_dir = self._roles_dir()
|
|
277
|
+
try:
|
|
278
|
+
key = (self._cfg_stamp if self._config() is not None else None, roles_dir.stat().st_mtime_ns)
|
|
279
|
+
except OSError:
|
|
280
|
+
key = (self._cfg_stamp, None)
|
|
281
|
+
if self._roles is not None and self._roles_key == key:
|
|
282
|
+
return self._roles
|
|
283
|
+
table: dict[str, dict[str, list[str]]] = {}
|
|
284
|
+
profiles = self._profiles()
|
|
285
|
+
for code, fname in profiles.items():
|
|
286
|
+
try:
|
|
287
|
+
text = (self._roles_dir() / str(fname)).read_text()
|
|
288
|
+
except OSError:
|
|
289
|
+
continue
|
|
290
|
+
own, dnt = _OWN.search(text), _DNT.search(text)
|
|
291
|
+
table[code] = {"own": _lines(own.group(1)) if own else [], "dnt": _lines(dnt.group(1)) if dnt else []}
|
|
292
|
+
self._roles, self._roles_key = table, key
|
|
293
|
+
return table
|
|
294
|
+
|
|
295
|
+
# ── S1, S7: the code and its surroundings ──────────────────────────────
|
|
296
|
+
def graph_status(self) -> dict:
|
|
297
|
+
c = self.idx.type_count
|
|
298
|
+
return {"project": self.idx.code, "nodes": len(self.idx.keys), "edges": self.idx.n_edges,
|
|
299
|
+
"symbols": c.get("Symbol", 0), "tests": c.get("TestCase", 0), "specs": c.get("Spec", 0),
|
|
300
|
+
"tickets": c.get("Ticket", 0)}
|
|
301
|
+
|
|
302
|
+
def symbol(self, name: str, limit: int = 8) -> dict:
|
|
303
|
+
found = self.idx.short.get(name.rsplit(".", 1)[-1], [])
|
|
304
|
+
return {"name": name, "n": len(found),
|
|
305
|
+
"symbols": [{"k": self._key(i), "kind": self.idx.props[i].get("kind"),
|
|
306
|
+
"line": self.idx.props[i].get("line_start")} for i in found[:limit]]}
|
|
307
|
+
|
|
308
|
+
# ── ODSF-313: say what an answer cannot see, so a partial list never looks complete ──
|
|
309
|
+
def _coverage(self, syms, shown: set[str] | None = None) -> dict:
|
|
310
|
+
"""Call sites the resolver left unattributed under these symbols' names, and the files holding them. When
|
|
311
|
+
several symbols share a name, an unresolved call may belong to any of them; `shared_by` says how many."""
|
|
312
|
+
names: dict[str, int] = {}
|
|
313
|
+
files: dict[str, None] = {}
|
|
314
|
+
n = 0
|
|
315
|
+
file_total = 0
|
|
316
|
+
for s in syms:
|
|
317
|
+
name = self._key(s).split("::")[-1].split(".")[-1]
|
|
318
|
+
if name in names:
|
|
319
|
+
continue
|
|
320
|
+
p = self.idx.props[s]
|
|
321
|
+
names[name] = len(self.idx.short.get(name, []))
|
|
322
|
+
n += int(p.get("unresolved_calls") or 0)
|
|
323
|
+
listed = p.get("unresolved_files") or []
|
|
324
|
+
file_total += int(p.get("unresolved_file_count") or len(listed)) - sum(1 for f in listed if shown and f in shown)
|
|
325
|
+
for f in listed:
|
|
326
|
+
if not shown or f not in shown:
|
|
327
|
+
files[f] = None
|
|
328
|
+
if not n:
|
|
329
|
+
return {"complete": True}
|
|
330
|
+
shared = max(names.values(), default=1)
|
|
331
|
+
# search_files is the first 10 by call count; search_file_count says how many files hold such calls in all.
|
|
332
|
+
more = {"search_file_count": file_total} if file_total > min(len(files), 10) else {}
|
|
333
|
+
if not files and any(self.idx.props[s].get("unresolved_files") for s in syms):
|
|
334
|
+
more["in_listed_files"] = True # every such call is in a file the answer already lists
|
|
335
|
+
return {"complete": False, "unresolved_calls": n, "search_files": list(files)[:10], **more,
|
|
336
|
+
**({"shared_by": shared, "note": f"{shared} symbols share this name; most of these calls may be to the others"}
|
|
337
|
+
if shared > 3 else {})}
|
|
338
|
+
|
|
339
|
+
def callers(self, symbol: str, depth: int = 1, limit: int = 25) -> dict:
|
|
340
|
+
i, err = self._resolve(symbol)
|
|
341
|
+
if err:
|
|
342
|
+
return err
|
|
343
|
+
levels = self._callers({i}, max(1, min(int(depth), 3)))
|
|
344
|
+
out = {"symbol": self._key(i), "n": [len(lv) for lv in levels]}
|
|
345
|
+
out["direct"] = [self._key(c) for c in levels[0][:limit]]
|
|
346
|
+
if len(levels) > 1:
|
|
347
|
+
out["indirect"] = [self._key(c) for lv in levels[1:] for c in lv[:limit]][:limit]
|
|
348
|
+
if len(levels[0]) > limit:
|
|
349
|
+
out["truncated"] = True
|
|
350
|
+
at_module = self.idx.props[i].get("module_callers") or []
|
|
351
|
+
if at_module: # calls outside any function: no caller symbol, only the file
|
|
352
|
+
out["module_level_files"] = list(at_module)[:limit]
|
|
353
|
+
out["coverage"] = self._coverage([i], {self._key(c).split("::")[0] for c in levels[0]} | set(at_module))
|
|
354
|
+
return out
|
|
355
|
+
|
|
356
|
+
def callees(self, symbol: str, limit: int = 25) -> dict:
|
|
357
|
+
i, err = self._resolve(symbol)
|
|
358
|
+
if err:
|
|
359
|
+
return err
|
|
360
|
+
t = sorted({self._key(c) for c in self.idx.targets("CALLS", i)})
|
|
361
|
+
return {"symbol": self._key(i), "n": len(t), "callees": t[:limit], **({"truncated": True} if len(t) > limit else {})}
|
|
362
|
+
|
|
363
|
+
def tests_for(self, ref: str, limit: int = 10) -> dict:
|
|
364
|
+
syms = self._file_symbols(ref)
|
|
365
|
+
if not syms:
|
|
366
|
+
i, err = self._resolve(ref)
|
|
367
|
+
if err:
|
|
368
|
+
return err
|
|
369
|
+
syms = [i]
|
|
370
|
+
found = self._tests_of(syms)
|
|
371
|
+
files = sorted(found, key=lambda f: (-len(found[f]), f))
|
|
372
|
+
cov = self._coverage(syms, set(files)) if len(syms) <= 3 else {}
|
|
373
|
+
return {"for": ref, "n_files": len(files), "n_tests": sum(len(v) for v in found.values()),
|
|
374
|
+
"files": [{"f": f, "t": sorted(found[f])[:5]} for f in files[:limit]],
|
|
375
|
+
"run": self._run_line(files[:limit]),
|
|
376
|
+
**({"coverage": {k: v for k, v in cov.items() if k != "search_files"} | {"search_files": [f for f in cov.get("search_files", []) if is_test_path(f)]}}
|
|
377
|
+
if cov else {})}
|
|
378
|
+
|
|
379
|
+
def tests_to_run(self, files: list[str] | str, limit: int = 12) -> dict:
|
|
380
|
+
files = [files] if isinstance(files, str) else list(files)
|
|
381
|
+
hits: dict[str, int] = {}
|
|
382
|
+
for f in files:
|
|
383
|
+
if is_test_path(f):
|
|
384
|
+
hits[f] = hits.get(f, 0) + 100
|
|
385
|
+
continue
|
|
386
|
+
for tf, names in self._tests_of(self._file_symbols(f)).items():
|
|
387
|
+
hits[tf] = hits.get(tf, 0) + len(names)
|
|
388
|
+
ranked = sorted(hits, key=lambda f: (-hits[f], f))
|
|
389
|
+
known = sum(1 for f in files if self._file_symbols(f) or is_test_path(f))
|
|
390
|
+
return {"changed": len(files), "known_to_graph": known, "n": len(ranked), "tests": ranked[:limit],
|
|
391
|
+
"run": self._run_line(ranked[:limit]),
|
|
392
|
+
**({"note": "no tests linked; run the full suite"} if not ranked else {})}
|
|
393
|
+
|
|
394
|
+
def impact(self, files: list[str] | str, depth: int = 2, limit: int = 12) -> dict:
|
|
395
|
+
files = [files] if isinstance(files, str) else list(files)
|
|
396
|
+
changed = {s for f in files for s in self._file_symbols(f)}
|
|
397
|
+
levels = self._callers(changed, max(1, min(int(depth), 3)))
|
|
398
|
+
file_set = set(files)
|
|
399
|
+
affected = [c for lv in levels for c in lv if self._key(c).split("::")[0] not in file_set
|
|
400
|
+
and not is_generated_path(self._key(c).split("::")[0])]
|
|
401
|
+
by_file: dict[str, int] = {}
|
|
402
|
+
for c in affected:
|
|
403
|
+
by_file[self._key(c).split("::")[0]] = by_file.get(self._key(c).split("::")[0], 0) + 1
|
|
404
|
+
keys = {self._key(s) for s in changed} | {self._key(c) for c in affected}
|
|
405
|
+
endpoints = sorted({self._key(e) for k in keys for e in self.idx.ep_by_owner.get(k, [])})
|
|
406
|
+
flows = sorted({self._key(f) for s in changed | set(affected) for f in self.idx.sources("STEP", s)})
|
|
407
|
+
tests = self.tests_to_run(files, limit=8)
|
|
408
|
+
return {"files": len(files), "changed_symbols": len(changed), "affected_symbols": len(affected),
|
|
409
|
+
"affected_files": [{"f": f, "n": n} for f, n in sorted(by_file.items(), key=lambda p: -p[1])[:limit]],
|
|
410
|
+
"endpoints": endpoints[:8], "n_flows": len(flows), "flows": flows[:4],
|
|
411
|
+
"tests": tests["tests"], "run": tests["run"], "owners": self._owners_of(files),
|
|
412
|
+
"coverage": self._coverage(sorted(changed)[:40], set(by_file)) if changed else {"complete": True}}
|
|
413
|
+
|
|
414
|
+
# ── S7: the fence ──────────────────────────────────────────────────────
|
|
415
|
+
def _owners_of(self, files: list[str]) -> dict[str, list[str]]:
|
|
416
|
+
owners: dict[str, list[str]] = {}
|
|
417
|
+
for code, spec in self._role_table().items():
|
|
418
|
+
for f in files:
|
|
419
|
+
if any(f.startswith(p) for p in spec["own"]):
|
|
420
|
+
owners.setdefault(code, []).append(f)
|
|
421
|
+
return {k: sorted(v)[:4] for k, v in owners.items()}
|
|
422
|
+
|
|
423
|
+
def owner(self, path: str) -> dict:
|
|
424
|
+
roles = self._role_table()
|
|
425
|
+
own = [(len(p), code) for code, s in roles.items() for p in s["own"] if path.startswith(p)]
|
|
426
|
+
own.sort(reverse=True)
|
|
427
|
+
forbidden = sorted({code for code, s in roles.items() if any(path.startswith(p) for p in s["dnt"])})
|
|
428
|
+
sub = ""
|
|
429
|
+
for s in sorted(self._config().get("subsystems", []), key=lambda s: -len(s.get("path", ""))):
|
|
430
|
+
if s.get("path") and path.startswith(s["path"]):
|
|
431
|
+
sub = s["key"]
|
|
432
|
+
break
|
|
433
|
+
return {"path": path, "owner": sorted({c for _, c in own[:1]}) if own else [], "forbidden_for": forbidden,
|
|
434
|
+
"subsystem": sub, **({"note": "no role owns this path; TL decides"} if not own else {})}
|
|
435
|
+
|
|
436
|
+
# ── S0 to S6: the requirement chain ────────────────────────────────────
|
|
437
|
+
def _ticket(self, ticket: str) -> tuple[int | None, dict | None]:
|
|
438
|
+
t = self.idx.node("Ticket", ticket)
|
|
439
|
+
return (t, None) if t is not None else (None, {"error": f"no ticket {ticket}"})
|
|
440
|
+
|
|
441
|
+
# ── pull requests and hosted issues (ADR-DEVKB-007) ──────────────────────────────────────
|
|
442
|
+
def _link(self, verb: str, p: int, other: int) -> tuple[float | None, bool]:
|
|
443
|
+
"""(confidence, unverified) of a MERGES or CLOSES edge."""
|
|
444
|
+
return self.idx.link_meta.get((verb, p, other), (None, False))
|
|
445
|
+
|
|
446
|
+
def _pr_row(self, p: int, verb: str = "", other: int | None = None) -> dict:
|
|
447
|
+
props = self.idx.props[p]
|
|
448
|
+
row = {"id": self._key(p), "title": (props.get("title") or "")[:90], "state": props.get("state")}
|
|
449
|
+
if props.get("merged_at"):
|
|
450
|
+
row["merged_at"] = str(props["merged_at"])[:10]
|
|
451
|
+
if verb and other is not None:
|
|
452
|
+
conf, unverified = self._link(verb, p, other)
|
|
453
|
+
if conf is not None and conf < 1.0:
|
|
454
|
+
row["confidence"] = conf
|
|
455
|
+
if unverified:
|
|
456
|
+
row["unverified"] = True
|
|
457
|
+
return row
|
|
458
|
+
|
|
459
|
+
def _ticket_prs(self, t: int) -> list[int]:
|
|
460
|
+
return sorted(set(self.idx.sources("CLOSES", t)), key=self._key)
|
|
461
|
+
|
|
462
|
+
def _pr_unverified(self, t: int, prs: list[int]) -> list[str]:
|
|
463
|
+
return [self._key(p) for p in prs if self._link("CLOSES", p, t)[1]]
|
|
464
|
+
|
|
465
|
+
def pr_coverage(self, unverified: list[str] | None = None) -> dict | None:
|
|
466
|
+
"""What the pull-request layer could not see, in the shape of every other `coverage`: None when the
|
|
467
|
+
repository has no GitHub remote and no pull request in its graph, so replies for it are unchanged."""
|
|
468
|
+
gh = self.idx.github
|
|
469
|
+
if not gh and not self.idx.type_count.get("PullRequest"):
|
|
470
|
+
return None
|
|
471
|
+
status = gh.get("status") or "offline"
|
|
472
|
+
unverified = sorted(set(unverified or []))
|
|
473
|
+
cov: dict = {"complete": status == "ok" and not unverified, "github": status}
|
|
474
|
+
if status == "offline":
|
|
475
|
+
cov["note"] = ("pull-request links come from git alone: rebase merges and issues closed by a pull request's "
|
|
476
|
+
"description are not visible (build with --github)")
|
|
477
|
+
elif status != "ok":
|
|
478
|
+
cov["note"] = (f"GitHub layer {status}: {gh.get('reason') or 'not fetched'}; not fetched: "
|
|
479
|
+
f"{', '.join(gh.get('not_fetched') or []) or 'everything'}; links shown are the offline ones"
|
|
480
|
+
+ (" and cached data" if gh.get("stale_cache_used") else ""))
|
|
481
|
+
if unverified:
|
|
482
|
+
cov["unverified"] = unverified
|
|
483
|
+
cov.setdefault("note", "offline closing-keyword links whose target may be a pull request, not an issue")
|
|
484
|
+
return cov
|
|
485
|
+
|
|
486
|
+
def _with_pr_coverage(self, reply: dict, unverified: list[str] | None = None) -> dict:
|
|
487
|
+
cov = self.pr_coverage(unverified)
|
|
488
|
+
if cov is not None:
|
|
489
|
+
reply["coverage"] = cov
|
|
490
|
+
return reply
|
|
491
|
+
|
|
492
|
+
@staticmethod
|
|
493
|
+
def _is_hosted(ticket: str) -> bool:
|
|
494
|
+
return bool(re.fullmatch(r"(?:[A-Za-z0-9_-]+:)?GH-\d+", ticket))
|
|
495
|
+
|
|
496
|
+
def _prs_of_commit(self, c: int) -> list[int]:
|
|
497
|
+
return sorted(set(self.idx.sources("MERGES", c)), key=self._key)
|
|
498
|
+
|
|
499
|
+
def _pr_ref(self, ref: str) -> tuple[int | None, dict | None]:
|
|
500
|
+
m = re.fullmatch(r"(?i)((?:[A-Za-z0-9_-]+:)?)(?:PR-|#)?(\d+)", str(ref).strip())
|
|
501
|
+
i = self.idx.node("PullRequest", f"{m.group(1)}PR-{m.group(2)}") if m else None
|
|
502
|
+
return (i, None) if i is not None else (None, {"error": f"no pull request {ref}"})
|
|
503
|
+
|
|
504
|
+
def pull_request(self, pr: str) -> dict:
|
|
505
|
+
"""A pull request: how it was merged, its commits, the issues it closes, and what the graph cannot verify."""
|
|
506
|
+
p, err = self._pr_ref(pr)
|
|
507
|
+
if err:
|
|
508
|
+
return self._with_pr_coverage(err)
|
|
509
|
+
idx, props = self.idx, self.idx.props[p]
|
|
510
|
+
commits = sorted(set(idx.targets("MERGES", p)), key=lambda c: (idx.props[c].get("date", ""), self._key(c)))
|
|
511
|
+
closes = sorted(set(idx.targets("CLOSES", p)), key=self._key)
|
|
512
|
+
out = {"pr": self._key(p), "title": (props.get("title") or "")[:110], "state": props.get("state"),
|
|
513
|
+
"merged_at": props.get("merged_at"), "merge_style": props.get("merge_style"), "base": props.get("base"),
|
|
514
|
+
"head": props.get("head"), "url": props.get("url"),
|
|
515
|
+
"commits": [{"h": idx.props[c].get("short_hash"), "s": (idx.props[c].get("subject") or "")[:72],
|
|
516
|
+
"c": self._link("MERGES", p, c)[0]} for c in commits[:25]],
|
|
517
|
+
"n_commits": len(commits),
|
|
518
|
+
"closes": [{"id": self._key(t), "title": (idx.props[t].get("title") or "")[:80], "c": self._link("CLOSES", p, t)[0],
|
|
519
|
+
**({"unverified": True} if self._link("CLOSES", p, t)[1] else {})} for t in closes]}
|
|
520
|
+
return self._with_pr_coverage({k: v for k, v in out.items() if v not in (None, "")},
|
|
521
|
+
[self._key(t) for t in closes if self._link("CLOSES", p, t)[1]])
|
|
522
|
+
|
|
523
|
+
def sdlc_context(self, ticket: str) -> dict:
|
|
524
|
+
t, err = self._ticket(ticket)
|
|
525
|
+
if err:
|
|
526
|
+
return err
|
|
527
|
+
idx, p = self.idx, self.idx.props[t]
|
|
528
|
+
commits = idx.sources("REFERENCES", t)
|
|
529
|
+
touched: dict[int, int] = {}
|
|
530
|
+
for c in commits:
|
|
531
|
+
for f in idx.targets("TOUCHES", c):
|
|
532
|
+
touched[f] = touched.get(f, 0) + 1
|
|
533
|
+
issues_rel = self.ctx.issues_dir.relative_to(self.root).as_posix() + "/" if self.ctx.issues_dir.is_relative_to(self.root) else "issues/"
|
|
534
|
+
files = [f for f in sorted(touched, key=lambda f: (-touched[f], self._key(f)))
|
|
535
|
+
if len(idx.sources("TOUCHES", f)) < 150 and not self._key(f).startswith(issues_rel)][:10]
|
|
536
|
+
owner_role = self._config().get("component_to_role", {}).get(p.get("component", ""), "")
|
|
537
|
+
return {"ticket": ticket, "title": (p.get("title") or "")[:110], "type": p.get("ticket_type"), "status": p.get("status"),
|
|
538
|
+
"priority": p.get("priority"), "component": p.get("component"), "assignee": p.get("assignee"),
|
|
539
|
+
"owner_role": owner_role,
|
|
540
|
+
"epic": [self._key(x) for x in idx.targets("CHILD_OF", t)],
|
|
541
|
+
"spec": [self._key(x) for x in idx.targets("IMPLEMENTS", t)],
|
|
542
|
+
"requirement": [self._key(x) for x in idx.targets("DERIVED_FROM", t)],
|
|
543
|
+
"docs": [self._key(x) for x in idx.sources("DOCUMENTS", t)][:5],
|
|
544
|
+
"similar": [{"t": self._key(b), "s": round(s, 2)} for b, s in idx.sim.get(t, [])[:4]],
|
|
545
|
+
"commits": len(commits), "files": [self._key(f) for f in files],
|
|
546
|
+
**({"pull_requests": [self._pr_row(x, "CLOSES", t) for x in self._ticket_prs(t)]} if self._ticket_prs(t) else {})}
|
|
547
|
+
|
|
548
|
+
def _bmad_stamp(self) -> tuple:
|
|
549
|
+
"""(file count, newest modification) of the BMAD ticket store, so a cached status is dropped when it changes."""
|
|
550
|
+
count = newest = 0
|
|
551
|
+
for dirpath, _dirs, names in os.walk(self.root / "_bmad-output"):
|
|
552
|
+
for name in names:
|
|
553
|
+
try:
|
|
554
|
+
m = os.stat(os.path.join(dirpath, name)).st_mtime_ns
|
|
555
|
+
except OSError:
|
|
556
|
+
continue
|
|
557
|
+
count += 1
|
|
558
|
+
newest = max(newest, m)
|
|
559
|
+
script = self.root / "_bmad" / "method" / "scripts" / "tickets.py"
|
|
560
|
+
return (count, newest, script.stat().st_mtime_ns if script.exists() else 0)
|
|
561
|
+
|
|
562
|
+
def _bmad_unknown_cached(self, root: Path, ref: str):
|
|
563
|
+
"""readiness_gate._bmad_unknown without launching `uv run tickets.py status` on every call (ODSF-309).
|
|
564
|
+
That subprocess took about 280 ms and its answer only changes when a BMAD ticket file does."""
|
|
565
|
+
script = root / "_bmad" / "method" / "scripts" / "tickets.py"
|
|
566
|
+
parts = ref.split("/")
|
|
567
|
+
if not script.exists() or len(parts) != 3:
|
|
568
|
+
return None
|
|
569
|
+
stamp = self._bmad_stamp()
|
|
570
|
+
if self._bmad_status is None or self._bmad_status[0] != stamp:
|
|
571
|
+
try:
|
|
572
|
+
status = json.loads(subprocess.run(["uv", "run", "--no-cache", str(script), "--project-root", str(root), "status"],
|
|
573
|
+
capture_output=True, text=True, timeout=120, check=True).stdout)
|
|
574
|
+
except (OSError, subprocess.SubprocessError, ValueError):
|
|
575
|
+
return None
|
|
576
|
+
self._bmad_status = (stamp, status)
|
|
577
|
+
row = next((t for t in self._bmad_status[1].get("tickets", [])
|
|
578
|
+
if t.get("epic") == parts[1] and str(t.get("id")) == parts[2]), None)
|
|
579
|
+
return (row or {}).get("unknown") or ""
|
|
580
|
+
|
|
581
|
+
def trace(self, ticket: str) -> dict:
|
|
582
|
+
t, err = self._ticket(ticket)
|
|
583
|
+
if err:
|
|
584
|
+
return err
|
|
585
|
+
idx, p = self.idx, self.idx.props[t]
|
|
586
|
+
|
|
587
|
+
def link(verb: str) -> list[dict]:
|
|
588
|
+
return [{"id": self._key(x), "status": idx.props[x].get("status")} for x in idx.targets(verb, t)]
|
|
589
|
+
|
|
590
|
+
out = {"ticket": ticket, "type": p.get("ticket_type"), "status": p.get("status"), "epic": link("CHILD_OF"),
|
|
591
|
+
"spec": link("IMPLEMENTS"), "requirement": [{"id": self._key(x)} for x in idx.targets("DERIVED_FROM", t)]}
|
|
592
|
+
prs = self._ticket_prs(t)
|
|
593
|
+
if prs:
|
|
594
|
+
out["pull_requests"] = [self._pr_row(x, "CLOSES", t) for x in prs]
|
|
595
|
+
children = sorted(set(idx.sources("CHILD_OF", t)), key=self._key) if self._is_hosted(ticket) else []
|
|
596
|
+
if children:
|
|
597
|
+
out["sub_issues"] = [{"id": self._key(x), "status": idx.props[x].get("status")} for x in children]
|
|
598
|
+
if prs or self._is_hosted(ticket):
|
|
599
|
+
self._with_pr_coverage(out, self._pr_unverified(t, prs))
|
|
600
|
+
if p.get("ticket_type") != "STORY":
|
|
601
|
+
out["gate0"] = "n/a: only STORY tickets are gated"
|
|
602
|
+
return out
|
|
603
|
+
if not run_repo_scripts(self.root):
|
|
604
|
+
out["gate0"] = "n/a: running the repository's readiness gate is off (run_repo_scripts)"
|
|
605
|
+
return out
|
|
606
|
+
try:
|
|
607
|
+
gates = self.root / "sdp" / "devsecops" / "quality-gates"
|
|
608
|
+
for extra in (gates, self.root / "issue-tools", self.root / "scripts"):
|
|
609
|
+
if str(extra) not in sys.path and extra.exists():
|
|
610
|
+
sys.path.insert(0, str(extra))
|
|
611
|
+
import readiness_gate # type: ignore
|
|
612
|
+
ipath = self.root / (p.get("issue_path") or "")
|
|
613
|
+
original = readiness_gate._bmad_unknown
|
|
614
|
+
readiness_gate._bmad_unknown = self._bmad_unknown_cached
|
|
615
|
+
try:
|
|
616
|
+
out["gate0"] = readiness_gate.check_story(ipath, self.root, self.root / "issues")
|
|
617
|
+
finally:
|
|
618
|
+
readiness_gate._bmad_unknown = original
|
|
619
|
+
except Exception as exc: # the verdict is advisory here; the real gate is `make gate-0`
|
|
620
|
+
out["gate0"] = f"unavailable: {type(exc).__name__}"
|
|
621
|
+
return out
|
|
622
|
+
|
|
623
|
+
def _doc_score(self, i: int, toks: list[str], idf: dict[str, float], topic_id: str) -> float:
|
|
624
|
+
title_w, path_w, head_w = self.idx.spec_terms[i]
|
|
625
|
+
score = 0.0
|
|
626
|
+
for w in toks:
|
|
627
|
+
score += idf[w] * ((3 if w in title_w else 0) + (2 if w in path_w else 0) + (1 if w in head_w else 0))
|
|
628
|
+
if str(self.idx.props[i].get("spec_id") or "").lower() == topic_id:
|
|
629
|
+
score += 10
|
|
630
|
+
return score
|
|
631
|
+
|
|
632
|
+
def _rank_docs(self, topic: str, kinds, candidates) -> list[tuple[float, int]]:
|
|
633
|
+
want = {kinds} if isinstance(kinds, str) else set(kinds or [])
|
|
634
|
+
toks = words(topic)
|
|
635
|
+
n = max(1, len(self.idx.spec_terms))
|
|
636
|
+
idf = {w: math.log((n + 1) / (self.idx.spec_df.get(w, 0) + 1)) + 1 for w in set(toks)}
|
|
637
|
+
topic_id = topic.strip().lower()
|
|
638
|
+
scored = []
|
|
639
|
+
for i in candidates:
|
|
640
|
+
if want and self.idx.props[i].get("doc_type") not in want:
|
|
641
|
+
continue
|
|
642
|
+
score = self._doc_score(i, toks, idf, topic_id)
|
|
643
|
+
if score > 0:
|
|
644
|
+
scored.append((score, i))
|
|
645
|
+
scored.sort(key=lambda s: (-s[0], self._key(s[1])))
|
|
646
|
+
return scored
|
|
647
|
+
|
|
648
|
+
def find_docs(self, topic: str, kinds: list[str] | str | None = None, limit: int = 8) -> dict:
|
|
649
|
+
"""Only documents that share a word with the query (or are named by it) are scored, found through
|
|
650
|
+
an inverted index built with the graph; the weights are computed once per query word."""
|
|
651
|
+
cand: set[int] = set()
|
|
652
|
+
for w in set(words(topic)):
|
|
653
|
+
cand.update(self.idx.spec_inv.get(w, ()))
|
|
654
|
+
exact = self.idx.spec_by_id.get(topic.strip().lower())
|
|
655
|
+
if exact is not None:
|
|
656
|
+
cand.add(exact)
|
|
657
|
+
scored = self._rank_docs(topic, kinds, cand)
|
|
658
|
+
return {"topic": topic, "n": len(scored),
|
|
659
|
+
"docs": [{"p": self._key(i), "t": (self.idx.props[i].get("title") or "")[:80],
|
|
660
|
+
"k": self.idx.props[i].get("doc_type"), "s": self.idx.props[i].get("status"), "sc": round(sc, 1)}
|
|
661
|
+
for sc, i in scored[:limit]]}
|
|
662
|
+
|
|
663
|
+
def _find_docs_scan(self, topic: str, kinds=None, limit: int = 8) -> list[str]:
|
|
664
|
+
"""The pre-ODSF-309 behaviour, scoring every document. Kept as the reference the inverted index must match."""
|
|
665
|
+
return [self._key(i) for _, i in self._rank_docs(topic, kinds, self.idx.spec_terms.keys())][:limit]
|
|
666
|
+
|
|
667
|
+
# ── S8: review ─────────────────────────────────────────────────────────
|
|
668
|
+
def _git(self, *args: str) -> str:
|
|
669
|
+
return subprocess.run(["git", *args], cwd=self.root, capture_output=True, text=True).stdout
|
|
670
|
+
|
|
671
|
+
@staticmethod
|
|
672
|
+
def _parse_diff(text: str) -> dict[str, list[tuple[int, int]]]:
|
|
673
|
+
files: dict[str, list[tuple[int, int]]] = {}
|
|
674
|
+
cur = ""
|
|
675
|
+
for line in text.splitlines():
|
|
676
|
+
if line.startswith("+++ b/"):
|
|
677
|
+
cur = line[6:]
|
|
678
|
+
files.setdefault(cur, [])
|
|
679
|
+
elif line.startswith("@@") and cur:
|
|
680
|
+
m = _HUNK.match(line)
|
|
681
|
+
if m:
|
|
682
|
+
start, n = int(m.group(1)), int(m.group(2) or 1)
|
|
683
|
+
files[cur].append((start, start + max(n, 1) - 1))
|
|
684
|
+
return files
|
|
685
|
+
|
|
686
|
+
def _moved_files(self, head_rev: str) -> set[str]:
|
|
687
|
+
"""Files that differ between `head_rev` and the commit the graph was built from: for those, line numbers
|
|
688
|
+
in the diff do not match the graph. One git call for the whole set (it was one call per changed file)."""
|
|
689
|
+
built = self.idx.git_head
|
|
690
|
+
if not built or head_rev == built:
|
|
691
|
+
return set()
|
|
692
|
+
if head_rev not in self._moved_cache:
|
|
693
|
+
if len(self._moved_cache) > 64:
|
|
694
|
+
self._moved_cache.clear()
|
|
695
|
+
self._moved_cache[head_rev] = {ln for ln in self._git("diff", "--name-only", head_rev, built).splitlines() if ln}
|
|
696
|
+
return self._moved_cache[head_rev]
|
|
697
|
+
|
|
698
|
+
def _has_tests(self, s: int) -> bool:
|
|
699
|
+
if self.idx.targets("TESTED_BY", s):
|
|
700
|
+
return True
|
|
701
|
+
return any(is_test_path(self._key(c).split("::")[0]) for c in self.idx.sources("CALLS", s))
|
|
702
|
+
|
|
703
|
+
def _function_ranges(self, head_rev: str, path: str) -> list[tuple[int, int, str]]:
|
|
704
|
+
"""(first line, last line, `Class.method`) for every function in `path` as it was at `head_rev`.
|
|
705
|
+
Parsing a large file costs tens of milliseconds, so the table is kept per (commit, file) (ODSF-309)."""
|
|
706
|
+
key = (head_rev, path)
|
|
707
|
+
if key in self._fn_cache:
|
|
708
|
+
return self._fn_cache[key]
|
|
709
|
+
import ast
|
|
710
|
+
src = self._git("show", f"{head_rev}:{path}")
|
|
711
|
+
ranges: list[tuple[int, int, str]] = []
|
|
712
|
+
try:
|
|
713
|
+
tree = ast.parse(src)
|
|
714
|
+
except (SyntaxError, ValueError):
|
|
715
|
+
tree = None
|
|
716
|
+
|
|
717
|
+
def walk(node: ast.AST, stack: list[str]) -> None:
|
|
718
|
+
for child in ast.iter_child_nodes(node):
|
|
719
|
+
if isinstance(child, ast.ClassDef):
|
|
720
|
+
walk(child, stack + [child.name])
|
|
721
|
+
elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
722
|
+
ranges.append((child.lineno, child.end_lineno or child.lineno, ".".join(stack + [child.name])))
|
|
723
|
+
walk(child, stack + [child.name])
|
|
724
|
+
if tree is not None:
|
|
725
|
+
walk(tree, [])
|
|
726
|
+
if len(self._fn_cache) > 64:
|
|
727
|
+
self._fn_cache.clear()
|
|
728
|
+
self._fn_cache[key] = ranges
|
|
729
|
+
return ranges
|
|
730
|
+
|
|
731
|
+
def _changed_python_names(self, head_rev: str, path: str, hunks: list[tuple[int, int]]) -> list[str]:
|
|
732
|
+
"""`Class.method` names of the functions whose lines a diff touched, read from the file as it was
|
|
733
|
+
at `head_rev`, not from the graph, which describes a later commit."""
|
|
734
|
+
return [name for start, end, name in self._function_ranges(head_rev, path)
|
|
735
|
+
if any(h0 <= end and start <= h1 for h0, h1 in hunks)]
|
|
736
|
+
|
|
737
|
+
def review_pack(self, rev: str, limit: int = 12) -> dict:
|
|
738
|
+
base, head_rev = rev.split("..", 1) if ".." in rev else (f"{rev}^", rev)
|
|
739
|
+
# Three independent git calls, run together: the diff, the commit subjects, the files moved since the graph.
|
|
740
|
+
with ThreadPoolExecutor(max_workers=3) as pool:
|
|
741
|
+
f_diff = pool.submit(self._git, "diff", "-U0", "--no-color", base, head_rev)
|
|
742
|
+
f_msgs = pool.submit(self._git, "log", "--format=%s", f"{base}..{head_rev}")
|
|
743
|
+
f_moved = pool.submit(self._moved_files, head_rev)
|
|
744
|
+
files, msgs, moved = self._parse_diff(f_diff.result()), f_msgs.result(), f_moved.result()
|
|
745
|
+
if not files:
|
|
746
|
+
return {"error": f"no diff for {rev}"}
|
|
747
|
+
changed: list[int] = []
|
|
748
|
+
drifted: list[str] = []
|
|
749
|
+
unmapped: list[str] = []
|
|
750
|
+
for f, hunks in files.items():
|
|
751
|
+
if f not in moved:
|
|
752
|
+
for s in self._file_symbols(f):
|
|
753
|
+
p = self.idx.props[s]
|
|
754
|
+
a, b = p.get("line_start") or 0, p.get("line_end") or 0
|
|
755
|
+
if any(h0 <= b and a <= h1 for h0, h1 in hunks):
|
|
756
|
+
changed.append(s)
|
|
757
|
+
elif f.endswith(".py"):
|
|
758
|
+
# The file moved on after this commit: read the commit's own source, then find each function in the graph by name.
|
|
759
|
+
drifted.append(f)
|
|
760
|
+
for name in self._changed_python_names(head_rev, f, hunks):
|
|
761
|
+
i = self.idx.node("Symbol", f"{f}::{name}")
|
|
762
|
+
if i is None:
|
|
763
|
+
unmapped.append(f"{f}::{name}")
|
|
764
|
+
else:
|
|
765
|
+
changed.append(i)
|
|
766
|
+
changed_set, file_set = set(changed), set(files)
|
|
767
|
+
outside = [c for lv in self._callers(changed_set, 1) for c in lv if self._key(c).split("::")[0] not in file_set]
|
|
768
|
+
tested = self._tests_of(changed)
|
|
769
|
+
untested = [s for s in changed if not self._has_tests(s)]
|
|
770
|
+
tickets = sorted(set(_TICKET_ID.findall(msgs)))
|
|
771
|
+
# ADR-DEVKB-007: the pull requests that brought these commits in, and the issues those close
|
|
772
|
+
prs: dict[int, None] = {}
|
|
773
|
+
for sha in self._git("rev-list", "-n", "300", f"{base}..{head_rev}").split():
|
|
774
|
+
c = self.idx.node("Commit", sha)
|
|
775
|
+
for p in (self._prs_of_commit(c) if c is not None else []):
|
|
776
|
+
prs[p] = None
|
|
777
|
+
tickets = sorted(set(tickets) | {self._key(t) for p in prs for t in self.idx.targets("CLOSES", p)})
|
|
778
|
+
pr_cov = self.pr_coverage([self._key(t) for p in prs for t in self.idx.targets("CLOSES", p) if self._link("CLOSES", p, t)[1]])
|
|
779
|
+
docs: list[str] = []
|
|
780
|
+
for tid in tickets:
|
|
781
|
+
t = self.idx.node("Ticket", tid)
|
|
782
|
+
if t is not None:
|
|
783
|
+
docs += [self._key(x) for x in self.idx.sources("DOCUMENTS", t)] + [self._key(x) for x in self.idx.targets("IMPLEMENTS", t)]
|
|
784
|
+
warnings = sorted({self.idx.props[w].get("rule", "?") for f in files for fi in [self.idx.node("File", f)] if fi is not None
|
|
785
|
+
for w in self.idx.targets("FLAGGED_BY", fi)})
|
|
786
|
+
return {"rev": rev, "files": len(files), "changed_symbols": [self._key(s) for s in changed[:limit]],
|
|
787
|
+
"n_changed_symbols": len(changed), "callers_outside": [self._key(c) for c in outside[:limit]],
|
|
788
|
+
"n_callers_outside": len(outside), "tests": [{"f": f, "t": sorted(v)[:3]} for f, v in sorted(tested.items())[:8]],
|
|
789
|
+
"untested": [self._key(s) for s in untested[:8]], "tickets": tickets[:6], "docs": sorted(set(docs))[:6],
|
|
790
|
+
"warnings": warnings[:6], "owners": self._owners_of(sorted(files)),
|
|
791
|
+
**({"drift": drifted[:6], "note": "these files changed after the commit; changed functions were read from the commit itself"} if drifted else {}),
|
|
792
|
+
**({"unmapped": unmapped[:6]} if unmapped else {}),
|
|
793
|
+
**({"pull_requests": [self._pr_row(p) for p in sorted(prs, key=self._key)[:6]]} if prs else {}),
|
|
794
|
+
**({"coverage": pr_cov} if pr_cov is not None else {})}
|
|
795
|
+
|
|
796
|
+
# ── developer tasks: one call for a whole kind of work (ODSF-310) ──────────────
|
|
797
|
+
# A developer does not ask "who calls this?" and stop. They build a feature, change behaviour, fix a ticketed bug,
|
|
798
|
+
# chase a root cause, refactor, review, learn an area. Each of those used to take four to six calls, and every call is
|
|
799
|
+
# another model turn that re-reads the whole context. These return what the task needs at once.
|
|
800
|
+
def _is_entry(self, i: int) -> bool:
|
|
801
|
+
key = self._key(i)
|
|
802
|
+
return key in self.idx.ep_by_owner or not self.idx.sources("CALLS", i) or key.endswith("::main")
|
|
803
|
+
|
|
804
|
+
def _caller_count(self, i: int) -> int:
|
|
805
|
+
"""Production callers only: what depends on this code, not what checks it."""
|
|
806
|
+
return sum(1 for c in set(self.idx.sources("CALLS", i)) if not is_test_path(self._key(c).split("::")[0]))
|
|
807
|
+
|
|
808
|
+
def _test_caller_count(self, i: int) -> int:
|
|
809
|
+
return sum(1 for c in set(self.idx.sources("CALLS", i)) if is_test_path(self._key(c).split("::")[0]))
|
|
810
|
+
|
|
811
|
+
def _code_hits(self, query: str, limit: int = 8, under: str = "", tests: bool = False) -> list[tuple[float, int]]:
|
|
812
|
+
toks = set(query_words(query))
|
|
813
|
+
if not toks:
|
|
814
|
+
return []
|
|
815
|
+
n = max(1, self.idx.n_symbols)
|
|
816
|
+
score: dict[int, float] = {}
|
|
817
|
+
matched: dict[int, int] = {}
|
|
818
|
+
for w in toks:
|
|
819
|
+
hits = self.idx.code_inv.get(w, [])
|
|
820
|
+
idf = math.log((n + 1) / (len(hits) + 1)) + 1
|
|
821
|
+
for i, wt in hits:
|
|
822
|
+
score[i] = score.get(i, 0.0) + idf * wt
|
|
823
|
+
matched[i] = matched.get(i, 0) + 1
|
|
824
|
+
ranked = []
|
|
825
|
+
for i, s in score.items():
|
|
826
|
+
path = self._key(i).split("::")[0]
|
|
827
|
+
if (under and not path.startswith(under)) or (not tests and is_test_path(path)):
|
|
828
|
+
continue
|
|
829
|
+
ranked.append((s * (0.5 + 0.5 * matched[i] / len(toks)), i))
|
|
830
|
+
ranked.sort(key=lambda r: (-r[0], -self._caller_count(r[1]), self._key(r[1])))
|
|
831
|
+
return ranked[:limit]
|
|
832
|
+
|
|
833
|
+
def _code_row(self, i: int) -> dict:
|
|
834
|
+
p = self.idx.props[i]
|
|
835
|
+
return {"k": self._key(i), "kind": p.get("kind"), "line": p.get("line_start"), "callers": self._caller_count(i),
|
|
836
|
+
"doc": (p.get("docstring_summary") or "")[:64]}
|
|
837
|
+
|
|
838
|
+
def find_code(self, query: str, limit: int = 8, under: str = "") -> dict:
|
|
839
|
+
hits = self._code_hits(query, limit, under)
|
|
840
|
+
return {"query": query, "n": len(hits), "code": [self._code_row(i) for _, i in hits]}
|
|
841
|
+
|
|
842
|
+
def _recent_commits(self, files: list[str], limit: int = 6) -> list[dict]:
|
|
843
|
+
found: dict[int, str] = {}
|
|
844
|
+
for f in files:
|
|
845
|
+
fi = self.idx.node("File", f)
|
|
846
|
+
if fi is None:
|
|
847
|
+
continue
|
|
848
|
+
for c in self.idx.sources("TOUCHES", fi):
|
|
849
|
+
if len(self.idx.targets("TOUCHES", c)) <= 40: # a mass rename tells nothing about this file
|
|
850
|
+
found.setdefault(c, f)
|
|
851
|
+
top = sorted(found, key=lambda c: (self.idx.props[c].get("date", ""), self._key(c)), reverse=True)[:limit]
|
|
852
|
+
rows = [{"h": (self.idx.props[c].get("short_hash") or "")[:8], "d": self.idx.props[c].get("date"),
|
|
853
|
+
"s": (self.idx.props[c].get("subject") or "")[:72], "t": sorted(set(_TICKET_ID.findall(self.idx.props[c].get("subject") or ""))),
|
|
854
|
+
"f": found[c]} for c in top]
|
|
855
|
+
for row, c in zip(rows, top):
|
|
856
|
+
prs = self._prs_of_commit(c)
|
|
857
|
+
if prs:
|
|
858
|
+
row["pr"] = [self._key(p) for p in prs]
|
|
859
|
+
closed = sorted({self._key(t) for p in prs for t in self.idx.targets("CLOSES", p)})
|
|
860
|
+
if closed:
|
|
861
|
+
row["closes"] = closed[:4]
|
|
862
|
+
return rows
|
|
863
|
+
|
|
864
|
+
def history(self, files: list[str] | str, limit: int = 6) -> dict:
|
|
865
|
+
files = [files] if isinstance(files, str) else list(files)
|
|
866
|
+
return self._with_pr_coverage({"files": files, "commits": self._recent_commits(files, limit)})
|
|
867
|
+
|
|
868
|
+
def _past_tickets(self, text: str, skip: str = "", bugs_only: bool = False, limit: int = 4) -> list[dict]:
|
|
869
|
+
score: dict[int, float] = {}
|
|
870
|
+
n = max(1, self.idx.type_count.get("Ticket", 1))
|
|
871
|
+
for w in set(query_words(text)):
|
|
872
|
+
hits = self.idx.ticket_inv.get(w, [])
|
|
873
|
+
idf = math.log((n + 1) / (len(hits) + 1)) + 1
|
|
874
|
+
for i in hits:
|
|
875
|
+
score[i] = score.get(i, 0.0) + idf
|
|
876
|
+
issues_rel = self.ctx.issues_dir.relative_to(self.root).as_posix() + "/" if self.ctx.issues_dir.is_relative_to(self.root) else "issues/"
|
|
877
|
+
out = []
|
|
878
|
+
for i in sorted(score, key=lambda i: (-score[i], self._key(i))):
|
|
879
|
+
p = self.idx.props[i]
|
|
880
|
+
if self._key(i) == skip or (bugs_only and p.get("ticket_type") != "BUG") or p.get("status") in ("OPEN", "BACKLOG", "WIP"):
|
|
881
|
+
continue
|
|
882
|
+
touched: dict[str, int] = {}
|
|
883
|
+
for c in self.idx.sources("REFERENCES", i):
|
|
884
|
+
for f in self.idx.targets("TOUCHES", c):
|
|
885
|
+
path = self._key(f)
|
|
886
|
+
if not path.startswith(issues_rel) and not path.endswith(".md"):
|
|
887
|
+
touched[path] = touched.get(path, 0) + 1
|
|
888
|
+
out.append({"t": self._key(i), "title": (p.get("title") or "")[:70], "files": sorted(touched, key=lambda f: -touched[f])[:3]})
|
|
889
|
+
if len(out) == limit:
|
|
890
|
+
break
|
|
891
|
+
return out
|
|
892
|
+
|
|
893
|
+
def rca_trace(self, symptom: str, depth: int = 3, limit: int = 8) -> dict:
|
|
894
|
+
toks = set(query_words(symptom))
|
|
895
|
+
n = max(1, self.idx.type_count.get("ErrorSignature", 1))
|
|
896
|
+
score: dict[int, float] = {}
|
|
897
|
+
for w in toks:
|
|
898
|
+
hits = self.idx.err_inv.get(w, [])
|
|
899
|
+
idf = math.log((n + 1) / (len(hits) + 1)) + 1
|
|
900
|
+
for e in hits:
|
|
901
|
+
score[e] = score.get(e, 0.0) + idf
|
|
902
|
+
sigs = [e for e in sorted(score, key=lambda e: (-score[e], self._key(e)))[:3] if score[e] > 0]
|
|
903
|
+
# ODSF-313: a message quoted exactly names its raiser; the fuzzy runners-up are then noise, not candidates
|
|
904
|
+
said = " ".join(symptom.lower().split())
|
|
905
|
+
exact = [e for e in score if len(m := " ".join((self.idx.props[e].get("message_template") or "").lower().split())) >= 12
|
|
906
|
+
and m.replace("{}", "") and all(part.strip() in said for part in m.split("{}") if part.strip())]
|
|
907
|
+
if exact:
|
|
908
|
+
sigs = sorted(exact, key=self._key)[:3]
|
|
909
|
+
raisers = sorted({s for e in sigs for verb in ("RAISES", "LOGS") for s in self.idx.sources(verb, e)}, key=self._key)
|
|
910
|
+
how = "error message"
|
|
911
|
+
if not raisers:
|
|
912
|
+
hits = self._code_hits(symptom, 3)
|
|
913
|
+
raisers, how = [i for _, i in hits], "code name (no error message matched)"
|
|
914
|
+
if not raisers:
|
|
915
|
+
return {"symptom": symptom, "error": "nothing in the graph matches this symptom; search the code directly"}
|
|
916
|
+
levels = self._callers(set(raisers), max(1, min(int(depth), 4)))
|
|
917
|
+
chain = [{"k": self._key(c), "d": d + 1, **({"entry": True} if self._is_entry(c) else {})}
|
|
918
|
+
for d, lv in enumerate(levels) for c in lv if not is_test_path(self._key(c).split("::")[0])]
|
|
919
|
+
files = list(dict.fromkeys([self._key(s).split("::")[0] for s in raisers] + [c["k"].split("::")[0] for c in chain if c["d"] == 1]))[:8]
|
|
920
|
+
tests = self._tests_of(raisers)
|
|
921
|
+
flows = sorted({self._key(f) for s in raisers for f in self.idx.sources("STEP", s)})
|
|
922
|
+
return {"symptom": symptom, "matched_by": how,
|
|
923
|
+
"signatures": [{"msg": (self.idx.props[e].get("message_template") or self.idx.props[e].get("label") or "")[:90],
|
|
924
|
+
"kind": self.idx.props[e].get("kind")} for e in sigs] if how == "error message" else [],
|
|
925
|
+
"raisers": [self._key(s) for s in raisers[:limit]], "chain": chain[:limit * 2],
|
|
926
|
+
"entry_points": [c["k"] for c in chain if c.get("entry")][:limit], "flows": flows[:3],
|
|
927
|
+
"recent": self._recent_commits(files, 6), "tests": [{"f": f, "t": sorted(v)[:3]} for f, v in sorted(tests.items())[:5]],
|
|
928
|
+
"coverage": self._coverage(raisers[:3])}
|
|
929
|
+
|
|
930
|
+
def bug_brief(self, ticket: str = "", text: str = "", limit: int = 6) -> dict:
|
|
931
|
+
info: dict = {}
|
|
932
|
+
if ticket:
|
|
933
|
+
t, err = self._ticket(ticket)
|
|
934
|
+
if err:
|
|
935
|
+
return err
|
|
936
|
+
p = self.idx.props[t]
|
|
937
|
+
text = text or p.get("title") or ""
|
|
938
|
+
info = {"ticket": ticket, "title": text[:110], "status": p.get("status"), "component": p.get("component"),
|
|
939
|
+
"owner_role": self._config().get("component_to_role", {}).get(p.get("component", ""), "")}
|
|
940
|
+
if not text:
|
|
941
|
+
return {"error": "give a ticket id or the symptom text"}
|
|
942
|
+
rca = self.rca_trace(text, depth=2, limit=limit)
|
|
943
|
+
suspects = rca.get("raisers") or []
|
|
944
|
+
similar = self._past_tickets(text, skip=ticket, bugs_only=True)
|
|
945
|
+
out = {**info, "matched_by": rca.get("matched_by", "none"), "suspects": suspects, "signatures": rca.get("signatures", []),
|
|
946
|
+
"entry_points": rca.get("entry_points", []), "recent": rca.get("recent", []), "similar_bugs": similar,
|
|
947
|
+
"tests": rca.get("tests", [])}
|
|
948
|
+
if not suspects:
|
|
949
|
+
out["note"] = "no suspect found by message or name; search the code directly"
|
|
950
|
+
return out
|
|
951
|
+
|
|
952
|
+
def feature_brief(self, goal: str, ticket: str = "", limit: int = 5) -> dict:
|
|
953
|
+
hits = self._code_hits(goal, limit)
|
|
954
|
+
top_files = list(dict.fromkeys(self._key(i).split("::")[0] for _, i in hits))[:3]
|
|
955
|
+
out: dict = {"goal": goal[:110], "code": [self._code_row(i) for _, i in hits],
|
|
956
|
+
"docs": self.find_docs(goal, limit=4)["docs"], "similar_work": self._past_tickets(goal, skip=ticket),
|
|
957
|
+
"owners": self._owners_of(top_files)}
|
|
958
|
+
if top_files:
|
|
959
|
+
first = self.owner(top_files[0])
|
|
960
|
+
out["boundary"] = {"path": top_files[0], "owner": first["owner"], "forbidden_for": first["forbidden_for"]}
|
|
961
|
+
tests = self.tests_to_run(top_files, limit=5)
|
|
962
|
+
out["tests"], out["run"] = tests["tests"], tests["run"]
|
|
963
|
+
if ticket and self.idx.node("Ticket", ticket) is not None:
|
|
964
|
+
ctx = self.sdlc_context(ticket)
|
|
965
|
+
out["chain"] = {k: ctx[k] for k in ("epic", "spec", "requirement") if ctx.get(k)}
|
|
966
|
+
return out
|
|
967
|
+
|
|
968
|
+
def explain_area(self, path: str, limit: int = 8) -> dict:
|
|
969
|
+
prefix = path.rstrip("/")
|
|
970
|
+
files = [f for f in self.idx.sym_by_file if f == prefix or f.startswith(prefix + "/")]
|
|
971
|
+
if not files:
|
|
972
|
+
return {"error": f"no indexed source under {path}"}
|
|
973
|
+
src = [f for f in files if not is_test_path(f)]
|
|
974
|
+
syms = [s for f in src for s in self.idx.sym_by_file[f]]
|
|
975
|
+
key_syms = sorted(syms, key=lambda s: (-self._caller_count(s), self._key(s)))[:limit]
|
|
976
|
+
eps = sorted({self._key(e) for s in syms for e in self.idx.ep_by_owner.get(self._key(s), [])})
|
|
977
|
+
topic = " ".join([prefix.replace("/", " ")] + [self._key(s).split("::")[-1] for s in key_syms[:3]])
|
|
978
|
+
tests = self.tests_to_run(src[:12], limit=6)
|
|
979
|
+
return {"path": path, "files": len(src), "symbols": len(syms),
|
|
980
|
+
"key_symbols": [{"k": self._key(s), "prod_callers": self._caller_count(s), "test_callers": self._test_caller_count(s),
|
|
981
|
+
"cx": self.idx.props[s].get("complexity")} for s in key_syms],
|
|
982
|
+
"ranked_by": "prod_callers: distinct non-test functions that call it",
|
|
983
|
+
"endpoints": eps[:6], "owners": self._owners_of(src[:30]),
|
|
984
|
+
"docs": self.find_docs(topic, limit=3)["docs"], "tests": tests["tests"],
|
|
985
|
+
"recent": self._recent_commits(src[:40], 4)}
|
|
986
|
+
|
|
987
|
+
def refactor_scope(self, target: str, role: str = "", limit: int = 12) -> dict:
|
|
988
|
+
syms = self._file_symbols(target)
|
|
989
|
+
label = target
|
|
990
|
+
if not syms:
|
|
991
|
+
i, err = self._resolve(target)
|
|
992
|
+
if err:
|
|
993
|
+
return err
|
|
994
|
+
syms, label = [i], self._key(i)
|
|
995
|
+
own = set(syms)
|
|
996
|
+
by_file: dict[str, int] = {}
|
|
997
|
+
test_callers: dict[str, int] = {}
|
|
998
|
+
for s in syms:
|
|
999
|
+
for c in self.idx.sources("CALLS", s):
|
|
1000
|
+
if c in own:
|
|
1001
|
+
continue
|
|
1002
|
+
f = self._key(c).split("::")[0]
|
|
1003
|
+
(test_callers if is_test_path(f) else by_file)[f] = (test_callers if is_test_path(f) else by_file).get(f, 0) + 1
|
|
1004
|
+
endpoints = sorted({self._key(e) for s in syms for e in self.idx.ep_by_owner.get(self._key(s), [])})
|
|
1005
|
+
flows = sorted({self._key(f) for s in syms for f in self.idx.sources("STEP", s)})
|
|
1006
|
+
files_to_touch = sorted(by_file, key=lambda f: -by_file[f])
|
|
1007
|
+
test_files = sorted(test_callers, key=lambda f: (-test_callers[f], f))
|
|
1008
|
+
blocked: list[str] = []
|
|
1009
|
+
if role: # a test file a role may not edit blocks the change as much as a source file does
|
|
1010
|
+
dnt = self._role_table().get(role, {}).get("dnt", [])
|
|
1011
|
+
blocked = sorted(f for f in files_to_touch + test_files if any(f.startswith(p) for p in dnt))
|
|
1012
|
+
tests = self.tests_to_run(list(dict.fromkeys(list(syms and [self._key(syms[0]).split("::")[0]]) + files_to_touch)), limit=8)
|
|
1013
|
+
return {"target": label, "symbols": len(syms), "public": any(self.idx.props[s].get("is_public") for s in syms),
|
|
1014
|
+
"max_complexity": max((self.idx.props[s].get("complexity") or 0 for s in syms), default=0),
|
|
1015
|
+
"caller_files": [{"f": f, "n": by_file[f]} for f in files_to_touch[:limit]], "n_caller_files": len(by_file),
|
|
1016
|
+
"test_files": test_files[:30], "n_test_files": len(test_files), "endpoints": endpoints[:6], "flows": flows[:3],
|
|
1017
|
+
"blocked_files": blocked[:limit], "tests": tests["tests"], "run": tests["run"],
|
|
1018
|
+
"coverage": self._coverage(syms, set(by_file) | set(test_files)),
|
|
1019
|
+
**({"truncated": "caller_files or test_files is longer than shown; the n_ counts are complete"}
|
|
1020
|
+
if len(by_file) > limit or len(test_files) > 30 else {})}
|
|
1021
|
+
|
|
1022
|
+
# ── S9, S10: close and knowledge ───────────────────────────────────────
|
|
1023
|
+
def lineage(self, ticket: str) -> dict:
|
|
1024
|
+
t, err = self._ticket(ticket)
|
|
1025
|
+
if err:
|
|
1026
|
+
return err
|
|
1027
|
+
idx = self.idx
|
|
1028
|
+
out: dict = {"ticket": ticket, "status": idx.props[t].get("status")}
|
|
1029
|
+
for verb in ("CAUSED_BY", "REGRESSION_OF", "DUPLICATE_OF", "BLOCKS"):
|
|
1030
|
+
fwd = [self._key(x) for x in idx.targets(verb, t)]
|
|
1031
|
+
back = [self._key(x) for x in idx.sources(verb, t)]
|
|
1032
|
+
if fwd:
|
|
1033
|
+
out[verb.lower()] = fwd
|
|
1034
|
+
if back:
|
|
1035
|
+
out[f"{verb.lower()}_by"] = back
|
|
1036
|
+
prs = self._ticket_prs(t)
|
|
1037
|
+
# a pull request that closes the ticket brings its commits into the ticket's history (ADR-DEVKB-007)
|
|
1038
|
+
via_prs = {c for p in prs for c in idx.targets("MERGES", p)}
|
|
1039
|
+
commits = sorted(set(idx.sources("REFERENCES", t)) | via_prs, key=lambda c: idx.props[c].get("date", ""))
|
|
1040
|
+
out["commits"] = len(commits)
|
|
1041
|
+
if commits:
|
|
1042
|
+
out["first"], out["last"] = idx.props[commits[0]].get("short_hash"), idx.props[commits[-1]].get("short_hash")
|
|
1043
|
+
out["spec"] = [self._key(x) for x in idx.targets("IMPLEMENTS", t)]
|
|
1044
|
+
out["work_package"] = [self._key(x) for x in idx.targets("PART_OF", t)]
|
|
1045
|
+
if prs:
|
|
1046
|
+
out["pull_requests"] = [self._pr_row(x, "CLOSES", t) for x in prs]
|
|
1047
|
+
if self._is_hosted(ticket):
|
|
1048
|
+
epic = [self._key(x) for x in idx.targets("CHILD_OF", t)]
|
|
1049
|
+
kids = [self._key(x) for x in sorted(set(idx.sources("CHILD_OF", t)), key=self._key)]
|
|
1050
|
+
if epic:
|
|
1051
|
+
out["epic"] = epic
|
|
1052
|
+
if kids:
|
|
1053
|
+
out["sub_issues"] = kids
|
|
1054
|
+
if prs or self._is_hosted(ticket):
|
|
1055
|
+
self._with_pr_coverage(out, self._pr_unverified(t, prs))
|
|
1056
|
+
return out
|
|
1057
|
+
|
|
1058
|
+
# ── configuration and repositories (ADR-SDP-DEVKB-005, ODSF-312) ────────────
|
|
1059
|
+
def _repo_of(self, key: str) -> str:
|
|
1060
|
+
head = key.split("/", 1)[0]
|
|
1061
|
+
return head.split(":", 1)[0] if ":" in head and head.split(":", 1)[0].isupper() else self.idx.code
|
|
1062
|
+
|
|
1063
|
+
def _readers(self, ck: int) -> list[int]:
|
|
1064
|
+
return sorted(set(self.idx.sources("READS", ck)), key=self._key)
|
|
1065
|
+
|
|
1066
|
+
def config(self, query: str = "", limit: int = 12) -> dict:
|
|
1067
|
+
"""A setting or a service: who reads the setting, which files declare it and which services those files
|
|
1068
|
+
deploy, in which repositories; or, for a service, its file, image, ports and settings. No query: an overview
|
|
1069
|
+
with the settings that are read but declared nowhere and declared but read nowhere."""
|
|
1070
|
+
idx, q = self.idx, query.strip()
|
|
1071
|
+
keys = [i for (t, _k), i in idx.by_key.items() if t == "ConfigKey"]
|
|
1072
|
+
comps = [i for (t, _k), i in idx.by_key.items() if t == "Component"]
|
|
1073
|
+
if not q:
|
|
1074
|
+
read = [i for i in keys if idx.sources("READS", i)]
|
|
1075
|
+
declared = {i for i in keys if idx.sources("DECLARES", i)}
|
|
1076
|
+
kinds: dict[str, int] = {}
|
|
1077
|
+
for c in comps:
|
|
1078
|
+
kinds[idx.props[c].get("kind") or "discovery"] = kinds.get(idx.props[c].get("kind") or "discovery", 0) + 1
|
|
1079
|
+
top = sorted(read, key=lambda i: (-len(set(idx.sources("READS", i))), self._key(i)))[:limit]
|
|
1080
|
+
env = [i for i in keys if idx.props[i].get("kind") == "env"]
|
|
1081
|
+
return {"settings": len(keys), "read_in_code": len(read), "components": kinds,
|
|
1082
|
+
"repositories": sorted(self._key(i) for (t, _k), i in idx.by_key.items() if t == "Repository"),
|
|
1083
|
+
"most_read": [{"k": self._key(i), "readers": len(set(idx.sources("READS", i)))} for i in top],
|
|
1084
|
+
"read_not_declared": sorted(self._key(i) for i in env if i not in declared and idx.sources("READS", i))[:limit],
|
|
1085
|
+
"declared_not_read": sorted(self._key(i) for i in env if i in declared and not idx.sources("READS", i))[:limit]}
|
|
1086
|
+
ck = idx.node("ConfigKey", q) or idx.node("ConfigKey", q.upper())
|
|
1087
|
+
if ck is not None:
|
|
1088
|
+
readers = self._readers(ck)
|
|
1089
|
+
files = sorted({self._key(f) for f in idx.sources("DECLARES", ck)})
|
|
1090
|
+
deployed = sorted({self._key(c) for f in idx.sources("DECLARES", ck) for c in idx.targets("DEPLOYS", f)})
|
|
1091
|
+
return {"setting": self._key(ck), "kind": idx.props[ck].get("kind"), "n_readers": len(readers),
|
|
1092
|
+
"read_by": [self._key(r) for r in readers[:limit]], "declared_in": files[:limit], "deployed_by": deployed[:limit],
|
|
1093
|
+
"repositories": sorted({self._repo_of(self._key(r)) for r in readers} | {self._repo_of(f) for f in files}),
|
|
1094
|
+
**({"note": "read in code but declared in no example env file, compose file, unit or Dockerfile"}
|
|
1095
|
+
if readers and not files and idx.props[ck].get("kind") == "env" else {})}
|
|
1096
|
+
comp = idx.node("Component", q) or next((c for c in comps if idx.props[c].get("label") == q), None)
|
|
1097
|
+
if comp is not None:
|
|
1098
|
+
p = idx.props[comp]
|
|
1099
|
+
files = [self._key(f) for f in idx.sources("DEPLOYS", comp)]
|
|
1100
|
+
settings = sorted({self._key(k) for f in idx.sources("DEPLOYS", comp) for k in idx.targets("DECLARES", f)})
|
|
1101
|
+
return {"component": self._key(comp), **{k: p[k] for k in ("kind", "file", "image", "ports", "exec") if p.get(k)},
|
|
1102
|
+
"defined_in": files, "settings": [{"k": s, "readers": len(self._readers(idx.node("ConfigKey", s)))} for s in settings[:limit]]}
|
|
1103
|
+
ql = q.lower()
|
|
1104
|
+
hits = sorted((i for i in keys if ql in self._key(i).lower()), key=lambda i: (-len(set(idx.sources("READS", i))), self._key(i)))
|
|
1105
|
+
chits = sorted((c for c in comps if ql in self._key(c).lower()), key=self._key)
|
|
1106
|
+
if not hits and not chits:
|
|
1107
|
+
return {"error": f"no setting or component matches {query!r}; call config with no query for an overview"}
|
|
1108
|
+
return {"query": q, "settings": [{"k": self._key(i), "readers": len(set(idx.sources("READS", i)))} for i in hits[:limit]],
|
|
1109
|
+
"components": [{"k": self._key(c), "kind": idx.props[c].get("kind")} for c in chits[:limit]]}
|
|
1110
|
+
|
|
1111
|
+
# ── documents and roles (ODSF-311) ────────────────────────────────────────────
|
|
1112
|
+
# Writing a design, a specification or a test specification, reviewing one, and starting a session as a particular
|
|
1113
|
+
# role are all work an agent does before it writes code. They need facts from the graph (what exists, who owns it,
|
|
1114
|
+
# what is untested, what changed since a document was written) and a shape (the sections the document should have).
|
|
1115
|
+
def _flow_of(self, entry: str) -> int | None:
|
|
1116
|
+
idx = self.idx
|
|
1117
|
+
if ("Flow", entry) in idx.by_key:
|
|
1118
|
+
return idx.by_key[("Flow", entry)]
|
|
1119
|
+
sym = None
|
|
1120
|
+
ep = idx.node("Endpoint", entry)
|
|
1121
|
+
if ep is not None and idx.props[ep].get("owner_symbol"):
|
|
1122
|
+
sym = idx.node("Symbol", idx.props[ep]["owner_symbol"])
|
|
1123
|
+
if sym is None:
|
|
1124
|
+
sym, err = self._resolve(entry)
|
|
1125
|
+
if err:
|
|
1126
|
+
return None
|
|
1127
|
+
for kind in ("endpoint", "daemon_entry", "ui_handler"):
|
|
1128
|
+
flow = idx.node("Flow", f"flow:{kind}:{self._key(sym)}")
|
|
1129
|
+
if flow is not None:
|
|
1130
|
+
return flow
|
|
1131
|
+
flows = idx.sources("STEP", sym)
|
|
1132
|
+
return min(flows, key=lambda f: len(idx.flow_steps.get(f, []))) if flows else None
|
|
1133
|
+
|
|
1134
|
+
def flow_sequence(self, entry: str, limit: int = 12) -> dict:
|
|
1135
|
+
"""The recorded call order from an entry point, as numbered messages and as Mermaid text for a sequence diagram."""
|
|
1136
|
+
flow = self._flow_of(entry)
|
|
1137
|
+
if flow is None:
|
|
1138
|
+
return {"error": f"no recorded flow for {entry}; flows are recorded from endpoints, daemon entries and UI handlers"}
|
|
1139
|
+
steps = [s for _, s in self.idx.flow_steps.get(flow, []) if self.idx.types[s] == "Symbol"]
|
|
1140
|
+
pos = {s: n for n, s in enumerate(steps)}
|
|
1141
|
+
messages = [(a, b) for a in steps for b in sorted(set(self.idx.targets("CALLS", a)), key=lambda x: pos.get(x, 1 << 30))
|
|
1142
|
+
if b in pos and b != a]
|
|
1143
|
+
shown = messages[:limit]
|
|
1144
|
+
files = list(dict.fromkeys(self._key(s).split("::")[0] for pair in shown for s in pair))
|
|
1145
|
+
alias = {f: f"p{n}" for n, f in enumerate(files)}
|
|
1146
|
+
lines = ["sequenceDiagram"] + [f" participant {alias[f]} as {f}" for f in files]
|
|
1147
|
+
for a, b in shown:
|
|
1148
|
+
lines.append(f" {alias[self._key(a).split('::')[0]]}->>{alias[self._key(b).split('::')[0]]}: {self._key(b).split('::')[-1].split('.')[-1]}")
|
|
1149
|
+
return {"flow": self._key(flow), "kind": self.idx.props[flow].get("touch_point_kind"), "n_steps": len(steps),
|
|
1150
|
+
"n_messages": len(messages), "participants": files,
|
|
1151
|
+
"messages": [f"{self._key(a)} -> {self._key(b)}" for a, b in shown], "mermaid": "\n".join(lines),
|
|
1152
|
+
**({"truncated": True} if len(messages) > limit else {})}
|
|
1153
|
+
|
|
1154
|
+
def _public_symbols(self, area: str) -> list[int]:
|
|
1155
|
+
prefix = area.rstrip("/")
|
|
1156
|
+
files = [f for f in self.idx.sym_by_file if (f == prefix or f.startswith(prefix + "/")) and not is_test_path(f)]
|
|
1157
|
+
syms = [s for f in files for s in self.idx.sym_by_file[f]]
|
|
1158
|
+
if not syms:
|
|
1159
|
+
i, err = self._resolve(area)
|
|
1160
|
+
if not err:
|
|
1161
|
+
syms = [i]
|
|
1162
|
+
return [s for s in syms if self.idx.props[s].get("kind") in ("function", "method", "class")
|
|
1163
|
+
and not self._key(s).split("::")[-1].split(".")[-1].startswith("_")]
|
|
1164
|
+
|
|
1165
|
+
def test_items(self, area: str, limit: int = 10) -> dict:
|
|
1166
|
+
"""Candidate test items for a path, directory or function, derived from what the code does: each error it
|
|
1167
|
+
raises (a negative test), each endpoint it serves (a contract test) and each untested branchy function."""
|
|
1168
|
+
public = self._public_symbols(area)
|
|
1169
|
+
if not public and "/" not in area and "." not in area: # plain words, not a path: search for the code
|
|
1170
|
+
public = [i for _, i in self._code_hits(area, 6)]
|
|
1171
|
+
if not public:
|
|
1172
|
+
return {"error": f"no public code under {area} in the graph built at {self.idx.git_head[:8]}"}
|
|
1173
|
+
items: list[dict] = []
|
|
1174
|
+
untested = [s for s in public if not self._has_tests(s)]
|
|
1175
|
+
for s in public:
|
|
1176
|
+
name, covered = self._key(s).split("::")[-1], self._has_tests(s)
|
|
1177
|
+
for e in self.idx.targets("RAISES", s):
|
|
1178
|
+
p = self.idx.props[e]
|
|
1179
|
+
items.append({"item": f"{name} raises {p.get('label')} when: {(p.get('message_template') or '')[:60]}",
|
|
1180
|
+
"kind": "negative", "target": self._key(s), "covered": covered})
|
|
1181
|
+
for ep in self.idx.ep_by_owner.get(self._key(s), []):
|
|
1182
|
+
items.append({"item": f"{self._key(ep)}: valid input, invalid input, and who may call it", "kind": "contract",
|
|
1183
|
+
"target": self._key(s), "covered": covered})
|
|
1184
|
+
for s in untested:
|
|
1185
|
+
cx = self.idx.props[s].get("complexity") or 0
|
|
1186
|
+
if cx >= 3:
|
|
1187
|
+
items.append({"item": f"{self._key(s).split('::')[-1]}: every branch (complexity {cx})", "kind": "branch",
|
|
1188
|
+
"target": self._key(s), "covered": False})
|
|
1189
|
+
order = {"negative": 0, "contract": 1, "branch": 2}
|
|
1190
|
+
items.sort(key=lambda it: (it["covered"], order[it["kind"]], it["target"]))
|
|
1191
|
+
files = list(dict.fromkeys(self._key(s).split("::")[0] for s in public))
|
|
1192
|
+
tests = self.tests_to_run(files[:12], limit=6)
|
|
1193
|
+
cases = self._register_cases(set(tests["tests"]))
|
|
1194
|
+
return {"area": area, "public": len(public), "untested": len(untested), "n_items": len(items), "items": items[:limit],
|
|
1195
|
+
"existing_tests": tests["tests"], "run": tests["run"], **({"register_cases": cases} if cases else {})}
|
|
1196
|
+
|
|
1197
|
+
def _register_cases(self, test_files: set[str]) -> list[str]:
|
|
1198
|
+
"""Ids of x03 test-case register cases bound to any of these test files, when the project keeps a register."""
|
|
1199
|
+
try:
|
|
1200
|
+
cfg = json.loads((self.root / "st.config.json").read_text())
|
|
1201
|
+
register = json.loads((self.root / cfg["register"]).read_text())
|
|
1202
|
+
except (OSError, ValueError, KeyError):
|
|
1203
|
+
return []
|
|
1204
|
+
cases = register.get("cases") or {}
|
|
1205
|
+
return [cid for cid, c in cases.items() if str((c.get("binding") or {}).get("node", "")).split("::")[0] in test_files][:6]
|
|
1206
|
+
|
|
1207
|
+
def _next_spec_id(self) -> str | None:
|
|
1208
|
+
found: dict[str, list[int]] = {}
|
|
1209
|
+
for sid in self.idx.spec_by_id:
|
|
1210
|
+
m = re.match(r"^spec-([a-z0-9]+)-(\d+)$", sid)
|
|
1211
|
+
if m:
|
|
1212
|
+
found.setdefault(m.group(1).upper(), []).append(int(m.group(2)))
|
|
1213
|
+
if not found:
|
|
1214
|
+
return None
|
|
1215
|
+
code = max(found, key=lambda c: len(found[c]))
|
|
1216
|
+
return f"SPEC-{code}-{max(found[code]) + 1:03d}"
|
|
1217
|
+
|
|
1218
|
+
def design_brief(self, kind: str, topic: str, limit: int = 5) -> dict:
|
|
1219
|
+
"""What to ground a document in, and the shape it should have: the sections for this kind of document, the facts
|
|
1220
|
+
from the graph that fill them, the existing documents to align with, and the next free specification id."""
|
|
1221
|
+
k = KIND_ALIASES.get(kind.lower().strip(), kind.lower().strip())
|
|
1222
|
+
if k not in TEMPLATES:
|
|
1223
|
+
return {"error": f"kind must be one of {sorted(TEMPLATES)}"}
|
|
1224
|
+
hits = self._code_hits(topic, limit)
|
|
1225
|
+
files = list(dict.fromkeys(self._key(i).split("::")[0] for _, i in hits))[:4]
|
|
1226
|
+
docs = self.find_docs(topic, limit=3)["docs"]
|
|
1227
|
+
for d in docs:
|
|
1228
|
+
i = self.idx.node("Spec", d["p"])
|
|
1229
|
+
d["heads"] = [h[:48] for h in self.idx.spec_heads.get(i, [])[:8]] if i is not None else []
|
|
1230
|
+
syms = [i for _, i in hits]
|
|
1231
|
+
endpoints = sorted({self._key(e) for s in syms for e in self.idx.ep_by_owner.get(self._key(s), [])})
|
|
1232
|
+
errors = [f"{self.idx.props[e].get('label')}: {(self.idx.props[e].get('message_template') or '')[:60]}"
|
|
1233
|
+
for s in syms for e in self.idx.targets("RAISES", s)][:6]
|
|
1234
|
+
facts: dict = {"code": [self._code_row(i) for i in syms]}
|
|
1235
|
+
if k in ("functional", "detailed"):
|
|
1236
|
+
facts["interfaces"], facts["errors"] = endpoints[:6], errors
|
|
1237
|
+
if k == "detailed":
|
|
1238
|
+
facts["symbols"] = [{"k": self._key(s), "line": self.idx.props[s].get("line_start"), "cx": self.idx.props[s].get("complexity")} for s in syms]
|
|
1239
|
+
if k == "architecture":
|
|
1240
|
+
area: dict[str, set[str]] = {}
|
|
1241
|
+
for f in files + [self._key(c).split("::")[0] for s in syms for c in self.idx.sources("CALLS", s)][:12]:
|
|
1242
|
+
area.setdefault("/".join(f.split("/")[:2]), set()).add(f)
|
|
1243
|
+
facts["components"] = [{"area": a, "files": len(fs)} for a, fs in sorted(area.items())][:6]
|
|
1244
|
+
facts["interfaces"] = endpoints[:6]
|
|
1245
|
+
facts["decisions"] = self.find_docs(topic, kinds=["adr"], limit=3)["docs"]
|
|
1246
|
+
if k == "sequence" and syms:
|
|
1247
|
+
flow = self._flow_of(self._key(syms[0])) or next((self._flow_of(self._key(c)) for lv in self._callers({syms[0]}, 3) for c in lv
|
|
1248
|
+
if self._flow_of(self._key(c)) is not None), None)
|
|
1249
|
+
if flow is not None:
|
|
1250
|
+
seq = self.flow_sequence(self._key(flow), limit=8)
|
|
1251
|
+
facts["flow"] = {k2: seq[k2] for k2 in ("flow", "participants", "messages", "mermaid") if k2 in seq}
|
|
1252
|
+
if k == "test_spec":
|
|
1253
|
+
ti = self.test_items(topic, limit=8)
|
|
1254
|
+
facts["test_items"] = {k2: ti[k2] for k2 in ("public", "untested", "items", "run") if k2 in ti}
|
|
1255
|
+
return {"kind": k, "topic": topic[:80], "outline": TEMPLATES[k], "front_matter": FRONT_MATTER,
|
|
1256
|
+
"next_spec_id": self._next_spec_id(), "docs": docs, "facts": facts, "similar_work": self._past_tickets(topic, limit=3),
|
|
1257
|
+
"owners": self._owners_of(files)}
|
|
1258
|
+
|
|
1259
|
+
def review_doc(self, path: str, kind: str = "") -> dict:
|
|
1260
|
+
"""Review a design, specification or test-specification document against the repository: references that do not
|
|
1261
|
+
exist, code it describes that changed after it was written, important code it never mentions, sections it lacks."""
|
|
1262
|
+
doc = self.root / path
|
|
1263
|
+
if not doc.is_file():
|
|
1264
|
+
return {"error": f"no document at {path}"}
|
|
1265
|
+
text = doc.read_text(errors="replace")[:200_000]
|
|
1266
|
+
k = KIND_ALIASES.get(kind.lower().strip(), kind.lower().strip()) if kind else ""
|
|
1267
|
+
refs = {m.lstrip("/") for m in re.findall(r"[\w./-]+\.(?:py|tsx|ts|jsonl|json|js|md|sh|toml|yaml|yml)(?![\w-])", text)
|
|
1268
|
+
if ("/" in m or (self.root / m).exists()) and "..." not in m}
|
|
1269
|
+
# A path whose top directory is not in this repository names another repository or an example; only a path
|
|
1270
|
+
# into a directory that exists here and a file that does not is a broken reference.
|
|
1271
|
+
missing = [p for p in refs if not (self.root / p).exists()]
|
|
1272
|
+
broken_paths = sorted(p for p in missing if (self.root / p.split("/")[0]).is_dir())
|
|
1273
|
+
elsewhere = len(missing) - len(broken_paths)
|
|
1274
|
+
ticket_re = re.compile(r"\b" + re.escape(self.ctx.ticket_prefix) + r"-\d+\b")
|
|
1275
|
+
broken_tickets = sorted({t for t in ticket_re.findall(text) if self.idx.node("Ticket", t) is None})
|
|
1276
|
+
# Only a name written as code that runs counts: `name()` or `path::name`. A bare `TestCase` or `first_seen` in a
|
|
1277
|
+
# design is as often a type, a field or a word as a function, and flagging those buries the real misses.
|
|
1278
|
+
called = set(re.findall(r"`([A-Za-z_][\w.]*)\([^`]*\)`", text)) | set(re.findall(r"`[\w-]*[./][\w./-]*::([\w.]+)`", text))
|
|
1279
|
+
unknown_symbols = sorted(n for n in called if not self.idx.short.get(n.split(".")[-1]) and n.split(".")[0] not in LIBRARY_NAMES)
|
|
1280
|
+
spec_ids = {s for s in re.findall(r"\b(?:SPEC|ADR)-[A-Z0-9-]+\b", text)}
|
|
1281
|
+
known_ids = {k.upper() for k in self.idx.spec_by_id} | {self._key(i).upper() for i in self.idx.spec_terms}
|
|
1282
|
+
broken_ids = sorted(s for s in spec_ids if s.upper() not in known_ids and not any(s.upper() in key for key in known_ids)
|
|
1283
|
+
and not re.search(r"-(?:N+|X+)$", s)) # ADR-...-NNN is a placeholder, not a reference
|
|
1284
|
+
existing = [p for p in refs if (self.root / p).exists()]
|
|
1285
|
+
stamp = (path, doc.stat().st_mtime_ns, self.idx.git_head)
|
|
1286
|
+
if stamp not in self._written:
|
|
1287
|
+
self._written[stamp] = self._git("log", "-1", "--format=%cs", "--", path).strip()
|
|
1288
|
+
written = self._written[stamp]
|
|
1289
|
+
drift = []
|
|
1290
|
+
if written:
|
|
1291
|
+
for f in existing:
|
|
1292
|
+
fi = self.idx.node("File", f)
|
|
1293
|
+
if fi is None:
|
|
1294
|
+
continue
|
|
1295
|
+
newer = [c for c in self.idx.sources("TOUCHES", fi) if (self.idx.props[c].get("date") or "") > written
|
|
1296
|
+
and len(self.idx.targets("TOUCHES", c)) <= 40]
|
|
1297
|
+
if newer:
|
|
1298
|
+
drift.append({"f": f, "newer_commits": len(newer)})
|
|
1299
|
+
drift.sort(key=lambda d: -d["newer_commits"])
|
|
1300
|
+
unmentioned: list[str] = []
|
|
1301
|
+
code_files = [f for f in existing if f in self.idx.sym_by_file and not is_test_path(f)]
|
|
1302
|
+
if code_files:
|
|
1303
|
+
common = max({"/".join(f.split("/")[:-1]) or f for f in code_files}, key=lambda d: sum(1 for f in code_files if f.startswith(d)))
|
|
1304
|
+
area = self.explain_area(common, limit=8) if common else {}
|
|
1305
|
+
unmentioned = [s["k"] for s in area.get("key_symbols", []) if not s["k"].split("::")[-1].split(".")[-1].startswith("_")
|
|
1306
|
+
and s["k"].split("::")[-1].split(".")[-1] not in text][:5]
|
|
1307
|
+
heads = [ln.lstrip("# ").strip() for ln in text.splitlines() if ln.startswith("#")][:40]
|
|
1308
|
+
missing = []
|
|
1309
|
+
if k in TEMPLATES:
|
|
1310
|
+
head_words = {w for h in heads for w in words(h)}
|
|
1311
|
+
missing = [sec for sec in TEMPLATES[k] if not ({w for w in words(sec) if w not in STOP} & head_words)]
|
|
1312
|
+
items_gap: list[str] = []
|
|
1313
|
+
if k == "test_spec" and code_files:
|
|
1314
|
+
ti = self.test_items(common, limit=40)
|
|
1315
|
+
items_gap = [it["item"][:70] for it in ti.get("items", []) if not it["covered"] and it["target"].split("::")[-1].split(".")[-1] not in text][:5]
|
|
1316
|
+
return {"path": path, "kind": k or "any", "words": len(text.split()), "headings": len(heads),
|
|
1317
|
+
"front_matter": text.startswith("---"), "missing_sections": missing,
|
|
1318
|
+
"broken": {"paths": broken_paths[:8], "symbols": unknown_symbols[:8], "tickets": broken_tickets[:8], "doc_ids": broken_ids[:6]},
|
|
1319
|
+
"outside_repo_paths": elsewhere,
|
|
1320
|
+
"drift": drift[:6], "written": written, "unmentioned": unmentioned, "untested_items_not_in_doc": items_gap,
|
|
1321
|
+
"owners": self._owners_of(existing[:20])}
|
|
1322
|
+
|
|
1323
|
+
def _role_info(self, code: str) -> tuple[str, dict]:
|
|
1324
|
+
table = self._role_table()
|
|
1325
|
+
match = next((c for c in table if c.lower() == code.lower()), "")
|
|
1326
|
+
return match, table.get(match, {})
|
|
1327
|
+
|
|
1328
|
+
def role_brief(self, role: str, limit: int = 6) -> dict:
|
|
1329
|
+
"""Everything a role needs to start a session, from the graph and the role profile: territory, work waiting,
|
|
1330
|
+
the code it owns and how to test it, the documents to read, and what is specific to the role."""
|
|
1331
|
+
code, spec = self._role_info(role)
|
|
1332
|
+
if not code:
|
|
1333
|
+
return {"error": f"unknown role {role}; known: {', '.join(sorted(self._role_table())) or 'none declared'}"}
|
|
1334
|
+
idx = self.idx
|
|
1335
|
+
profile_file = self._profiles().get(code, "")
|
|
1336
|
+
profile: dict = {"file": f"sdp/process/roles/{profile_file}"} if profile_file else {}
|
|
1337
|
+
try:
|
|
1338
|
+
body = (self._roles_dir() / profile_file).read_text()
|
|
1339
|
+
for key, label in (("Mission", "mission"), ("Decides", "decides"), ("Does NOT decide", "not_decide")):
|
|
1340
|
+
m = re.search(r"\*\*" + key + r"\*\*:\s*(.+(?:\n(?![ \t]*\n|\*\*|#|- ).+)*)", body)
|
|
1341
|
+
if m: # a profile field may wrap over several lines
|
|
1342
|
+
profile[label] = clip(" ".join(m.group(1).split()), 240)
|
|
1343
|
+
except OSError:
|
|
1344
|
+
pass
|
|
1345
|
+
mine, counts = [], {}
|
|
1346
|
+
prio = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
|
|
1347
|
+
for (typ, key), i in idx.by_key.items():
|
|
1348
|
+
if typ != "Ticket" or idx.props[i].get("assignee") != code:
|
|
1349
|
+
continue
|
|
1350
|
+
st = idx.props[i].get("status") or "?"
|
|
1351
|
+
counts[st] = counts.get(st, 0) + 1
|
|
1352
|
+
if st in ("OPEN", "WIP", "REVIEW", "BACKLOG"):
|
|
1353
|
+
mine.append(i)
|
|
1354
|
+
mine.sort(key=lambda i: (prio.get(idx.props[i].get("priority"), 9), self._key(i)))
|
|
1355
|
+
own = spec.get("own", [])
|
|
1356
|
+
files = [f for f in idx.sym_by_file if any(f.startswith(p) for p in own) and not is_test_path(f)]
|
|
1357
|
+
syms = [s for f in files for s in idx.sym_by_file[f]]
|
|
1358
|
+
key_syms = sorted(syms, key=lambda s: (-self._caller_count(s), self._key(s)))[:limit]
|
|
1359
|
+
eps = sorted({self._key(e) for s in syms for e in idx.ep_by_owner.get(self._key(s), [])})
|
|
1360
|
+
tests = self.tests_to_run(files[:40], limit=5) if files else {"tests": [], "run": ""}
|
|
1361
|
+
# What the role decides finds its documents better than its paths do (sdp/devsecops names the devkb ADRs).
|
|
1362
|
+
topic = (profile.get("decides", "") + " " + " ".join(p.strip("/").replace("/", " ") for p in own[:2])).strip()
|
|
1363
|
+
out: dict = {"role": code, "profile": profile, "territory": {"own": own, "forbidden": spec.get("dnt", [])},
|
|
1364
|
+
"work": {"counts": counts, "open": [{"t": self._key(i), "p": idx.props[i].get("priority"), "s": idx.props[i].get("status"),
|
|
1365
|
+
"title": clip(idx.props[i].get("title") or "", 100)} for i in mine[:limit]]},
|
|
1366
|
+
"area": {"files": len(files), "symbols": len(syms),
|
|
1367
|
+
"key_symbols": [{"k": self._key(s), "prod_callers": self._caller_count(s)} for s in key_syms],
|
|
1368
|
+
"endpoints": eps[:limit], "tests": tests["tests"], "run": tests["run"]},
|
|
1369
|
+
"docs": self.find_docs(topic, limit=3)["docs"] if topic else []}
|
|
1370
|
+
c = code.upper()
|
|
1371
|
+
extras: dict = {}
|
|
1372
|
+
if c in ("QA", "TEST", "TESTER", "QAE", "SET"):
|
|
1373
|
+
ti = self.test_items(own[0], limit=6) if own and any(f.startswith(own[0]) for f in idx.sym_by_file) else {}
|
|
1374
|
+
extras["untested"] = ti.get("untested")
|
|
1375
|
+
extras["test_items"] = [it["item"][:80] for it in ti.get("items", []) if not it["covered"]][:5]
|
|
1376
|
+
if c == "TL":
|
|
1377
|
+
review = [i for (typ, _k), i in idx.by_key.items() if typ == "Ticket" and idx.props[i].get("status") == "REVIEW"]
|
|
1378
|
+
drafts = [self._key(i) for (typ, _k), i in idx.by_key.items() if typ == "Spec" and idx.props[i].get("status") in ("draft", "proposed")]
|
|
1379
|
+
merges = sorted((i for (typ, _k), i in idx.by_key.items() if typ == "Commit" and (idx.props[i].get("subject") or "").startswith("Merge")),
|
|
1380
|
+
key=lambda i: idx.props[i].get("date", ""), reverse=True)[:3]
|
|
1381
|
+
extras = {"in_review": len(review), "review_queue": [self._key(i) for i in review[:limit]], "draft_specs": len(drafts),
|
|
1382
|
+
"draft_list": drafts[:4], "recent_merges": [(idx.props[i].get("subject") or "")[:70] for i in merges]}
|
|
1383
|
+
if c in ("OPS", "DEVOPS", "SRE"):
|
|
1384
|
+
daemons = sorted((i for (typ, _k), i in idx.by_key.items() if typ == "Flow" and idx.props[i].get("touch_point_kind") == "daemon_entry"),
|
|
1385
|
+
key=lambda i: -(idx.props[i].get("step_count") or 0))[:5]
|
|
1386
|
+
warn = {}
|
|
1387
|
+
for (typ, _k), i in idx.by_key.items():
|
|
1388
|
+
if typ == "Warning":
|
|
1389
|
+
warn[idx.props[i].get("severity") or "?"] = warn.get(idx.props[i].get("severity") or "?", 0) + 1
|
|
1390
|
+
cfg = self.config(limit=6) # ODSF-312: what runs, and settings nothing declares
|
|
1391
|
+
extras = {"daemon_entry_flows": [self._key(i) for i in daemons], "warnings_by_severity": warn,
|
|
1392
|
+
"components": cfg["components"], "settings_read_not_declared": cfg["read_not_declared"],
|
|
1393
|
+
"gates": sorted(k for (typ, k) in idx.by_key if typ == "File" and "quality-gates/gate-" in k)[:8]}
|
|
1394
|
+
if c in ("DSA", "TA", "ARCH", "ARCHITECT"):
|
|
1395
|
+
adrs = sorted(((idx.props[i].get("status"), self._key(i)) for (typ, _k), i in idx.by_key.items()
|
|
1396
|
+
if typ == "Spec" and idx.props[i].get("doc_type") == "adr"), reverse=True)[:5]
|
|
1397
|
+
extras = {"adrs": [f"{s or '?'}: {p}" for s, p in adrs], "subsystems": sorted({k for (typ, k) in idx.by_key if typ in ("Subsystem", "Component")})[:8]}
|
|
1398
|
+
if c in ("BA", "PO"):
|
|
1399
|
+
stories = {}
|
|
1400
|
+
for (typ, _k), i in idx.by_key.items():
|
|
1401
|
+
if typ == "Ticket" and idx.props[i].get("ticket_type") in ("EPIC", "STORY"):
|
|
1402
|
+
key = f"{idx.props[i].get('ticket_type')}/{idx.props[i].get('status')}"
|
|
1403
|
+
stories[key] = stories.get(key, 0) + 1
|
|
1404
|
+
extras = {"epics_and_stories": stories, "next_spec_id": self._next_spec_id()}
|
|
1405
|
+
if extras:
|
|
1406
|
+
out["extras"] = extras
|
|
1407
|
+
out["ask"] = ROLE_SKILLS.get(c, ROLE_SKILLS["dev"])
|
|
1408
|
+
return out
|
|
1409
|
+
|
|
1410
|
+
|
|
1411
|
+
TOOL_ARGS = {
|
|
1412
|
+
"graph-status": ("graph_status", []), "symbol": ("symbol", ["name"]), "callers": ("callers", ["symbol"]),
|
|
1413
|
+
"callees": ("callees", ["symbol"]), "tests-for": ("tests_for", ["ref"]), "tests-to-run": ("tests_to_run", ["files"]),
|
|
1414
|
+
"impact": ("impact", ["files"]), "owner": ("owner", ["path"]), "sdlc-context": ("sdlc_context", ["ticket"]),
|
|
1415
|
+
"trace": ("trace", ["ticket"]), "find-docs": ("find_docs", ["topic"]), "review-pack": ("review_pack", ["rev"]),
|
|
1416
|
+
"lineage": ("lineage", ["ticket"]), "pull-request": ("pull_request", ["pr"]),
|
|
1417
|
+
"find-code": ("find_code", ["query"]), "history": ("history", ["files"]), "feature-brief": ("feature_brief", ["goal"]),
|
|
1418
|
+
"bug-brief": ("bug_brief", ["ticket"]), "rca-trace": ("rca_trace", ["symptom"]), "refactor-scope": ("refactor_scope", ["target"]),
|
|
1419
|
+
"explain-area": ("explain_area", ["path"]),
|
|
1420
|
+
"flow-sequence": ("flow_sequence", ["entry"]), "test-items": ("test_items", ["area"]),
|
|
1421
|
+
"design-brief": ("design_brief", ["kind", "topic"]), "review-doc": ("review_doc", ["path", "kind"]),
|
|
1422
|
+
"role-brief": ("role_brief", ["role"]),
|
|
1423
|
+
"config": ("config", ["query"]),
|
|
1424
|
+
}
|
|
1425
|
+
|
|
1426
|
+
|
|
1427
|
+
TEXT_TOOLS = frozenset({"find-code", "feature-brief", "rca-trace", "find-docs"})
|
|
1428
|
+
|
|
1429
|
+
|
|
1430
|
+
def _coerce(name: str, value: str):
|
|
1431
|
+
if name in ("files",):
|
|
1432
|
+
return [v for v in value.split(",") if v]
|
|
1433
|
+
return int(value) if value.isdigit() else value
|
|
1434
|
+
|
|
1435
|
+
|
|
1436
|
+
# Document shapes for design_brief and review_doc (ODSF-311). Short on purpose: a section name that says what goes in it.
|
|
1437
|
+
TEMPLATES = {
|
|
1438
|
+
"functional": ["Purpose and users", "Scope and non-goals", "Functional requirements, numbered and testable",
|
|
1439
|
+
"Interfaces: commands, endpoints, data in and out", "Business rules and error handling",
|
|
1440
|
+
"Acceptance criteria", "Traceability to requirement and tickets"],
|
|
1441
|
+
"architecture": ["Context and constraints", "Components and responsibilities", "Interfaces between components",
|
|
1442
|
+
"Data and state", "Key decisions with ADR links", "Quality attributes", "Risks and open questions"],
|
|
1443
|
+
"detailed": ["Modules and files", "Data structures", "Algorithms and rules", "Error handling",
|
|
1444
|
+
"Interfaces and signatures", "Test hooks", "Migration and compatibility"],
|
|
1445
|
+
"sequence": ["Participants", "Main flow as numbered messages", "Alternative and error flows", "Preconditions and postconditions"],
|
|
1446
|
+
"test_spec": ["Scope and objectives", "Test items", "Test cases with steps and expected results", "Test data and fixtures",
|
|
1447
|
+
"Entry and exit criteria", "Traceability to requirements"],
|
|
1448
|
+
}
|
|
1449
|
+
KIND_ALIASES = {"function": "functional", "functional_design": "functional", "design": "detailed", "detail": "detailed",
|
|
1450
|
+
"detailed_design": "detailed", "arch": "architecture", "architecture_design": "architecture",
|
|
1451
|
+
"test": "test_spec", "testspec": "test_spec", "test-spec": "test_spec", "test_specification": "test_spec",
|
|
1452
|
+
"seq": "sequence", "sequence_diagram": "sequence"}
|
|
1453
|
+
def clip(text: str, n: int) -> str:
|
|
1454
|
+
"""Shorten at a sentence end if one is near the limit, else at a word, never mid-word."""
|
|
1455
|
+
if len(text) <= n:
|
|
1456
|
+
return text
|
|
1457
|
+
cut = text[:n]
|
|
1458
|
+
end = cut.rfind(". ")
|
|
1459
|
+
if end >= n * 0.5:
|
|
1460
|
+
return cut[: end + 1]
|
|
1461
|
+
return cut[: cut.rfind(" ")].rstrip(",;:") + " …" if " " in cut else cut + "…"
|
|
1462
|
+
|
|
1463
|
+
|
|
1464
|
+
# Library and builtin names a design quotes as calls; they are not this repository's code, so never a broken reference.
|
|
1465
|
+
LIBRARY_NAMES = frozenset("sha256 sha1 md5 hashlib len str int float dict list set tuple print open sorted json os re sys "
|
|
1466
|
+
"subprocess pathlib Path time datetime uuid isinstance getattr fetch require useEffect useState".split())
|
|
1467
|
+
FRONT_MATTER = ["id", "title", "type", "status", "created", "updated", "owner", "source", "tickets"]
|
|
1468
|
+
# Which developer-task skills a role reaches for first; role_brief names them so a session starts with the right ones.
|
|
1469
|
+
ROLE_SKILLS = {
|
|
1470
|
+
"dev": ["devkb-feature", "devkb-enhance", "devkb-bugfix", "devkb-refactor"],
|
|
1471
|
+
"QA": ["devkb-testspec", "devkb-design-review", "devkb-review", "devkb-rca"],
|
|
1472
|
+
"TL": ["devkb-review", "devkb-design-review", "devkb-onboard", "devkb-spec"],
|
|
1473
|
+
"OPS": ["devkb-rca", "devkb-onboard", "devkb-review"],
|
|
1474
|
+
"DSA": ["devkb-spec", "devkb-design-review", "devkb-onboard"],
|
|
1475
|
+
"BA": ["devkb-spec", "devkb-design-review"], "PO": ["devkb-spec", "devkb-design-review"],
|
|
1476
|
+
"DE": ["devkb-feature", "devkb-rca", "devkb-testspec"], "MLE": ["devkb-feature", "devkb-rca", "devkb-testspec"],
|
|
1477
|
+
"KC": ["devkb-onboard", "devkb-design-review"], "CM": ["devkb-review", "devkb-onboard"],
|
|
1478
|
+
}
|
|
1479
|
+
ROLE_SKILLS["TA"] = ROLE_SKILLS["ARCH"] = ROLE_SKILLS["DSA"]
|
|
1480
|
+
ROLE_SKILLS["TEST"] = ROLE_SKILLS["TESTER"] = ROLE_SKILLS["QA"]
|
|
1481
|
+
ROLE_SKILLS["DEVOPS"] = ROLE_SKILLS["SRE"] = ROLE_SKILLS["OPS"]
|
|
1482
|
+
|
|
1483
|
+
LATENCY_TARGET_MS = 50
|
|
1484
|
+
REPLY_TARGET_BYTES = 4096
|
|
1485
|
+
|
|
1486
|
+
|
|
1487
|
+
def bench_api(api: ProcessAPI, reps: int = 25) -> dict:
|
|
1488
|
+
"""Time every tool, warm, on arguments that can succeed. An error reply is tiny and fast and would flatter
|
|
1489
|
+
the numbers, so a tool that has no valid sample is listed under `skipped`, never counted as fast (ODSF-309:
|
|
1490
|
+
the first version timed six of the eleven tools and quoted that as the API's latency)."""
|
|
1491
|
+
idx = api.idx
|
|
1492
|
+
unique = [v[0] for v in idx.short.values() if len(v) == 1 and idx.sources("CALLS", v[0])]
|
|
1493
|
+
sym = idx.keys[max(unique, key=lambda s: len(idx.sources("CALLS", s)))] if unique else None
|
|
1494
|
+
files = [f for f, ss in idx.sym_by_file.items() if any(idx.sources("CALLS", s) for s in ss)][:3]
|
|
1495
|
+
tickets = [(k, i) for (t, k), i in idx.by_key.items() if t == "Ticket"]
|
|
1496
|
+
busy = max(tickets, key=lambda p: len(idx.sources("REFERENCES", p[1])))[0] if tickets else None
|
|
1497
|
+
story = next((k for k, i in tickets if idx.props[i].get("ticket_type") == "STORY"), None)
|
|
1498
|
+
head = api._git("log", "-1", "--format=%h", "--no-merges", "--", "*.py").strip()
|
|
1499
|
+
msg = next((idx.props[i].get("message_template") for (typ, _k), i in idx.by_key.items()
|
|
1500
|
+
if typ == "ErrorSignature" and len(words(idx.props[i].get("message_template") or "")) >= 3), None)
|
|
1501
|
+
flows = sorted((i for (typ, _k), i in idx.by_key.items() if typ == "Flow"), key=lambda i: -len(idx.flow_steps.get(i, [])))
|
|
1502
|
+
flow = idx.keys[flows[0]] if flows else None
|
|
1503
|
+
doc = next((idx.keys[i] for i in sorted(idx.spec_terms) if (api.root / idx.keys[i]).is_file()), None)
|
|
1504
|
+
role = next(iter(sorted(api._role_table())), None)
|
|
1505
|
+
setting = next((idx.keys[i] for (typ, _k), i in sorted(idx.by_key.items()) if typ == "ConfigKey" and idx.sources("READS", i)), None)
|
|
1506
|
+
plan: list[tuple[str, dict | None, str]] = [
|
|
1507
|
+
("graph_status", {}, ""), ("symbol", {"name": sym.split("::")[-1]} if sym else None, "no symbol with a caller"),
|
|
1508
|
+
("callers", {"symbol": sym, "depth": 2} if sym else None, "no symbol with a caller"),
|
|
1509
|
+
("callees", {"symbol": sym} if sym else None, "no symbol with a caller"),
|
|
1510
|
+
("tests_for", {"ref": files[0]} if files else None, "no file with callers"),
|
|
1511
|
+
("tests_to_run", {"files": files} if files else None, "no file with callers"),
|
|
1512
|
+
("impact", {"files": files, "depth": 3} if files else None, "no file with callers"),
|
|
1513
|
+
("owner", {"path": files[0]} if files else None, "no file with callers"),
|
|
1514
|
+
("sdlc_context", {"ticket": busy} if busy else None, "no tickets"),
|
|
1515
|
+
("lineage", {"ticket": busy} if busy else None, "no tickets"),
|
|
1516
|
+
("trace", {"ticket": story} if story else None, "no STORY ticket"),
|
|
1517
|
+
("find_docs", {"topic": "quality gate readiness specification"} if idx.spec_terms else None, "no specs"),
|
|
1518
|
+
("review_pack", {"rev": head} if head else None, "no python commit"),
|
|
1519
|
+
("find_code", {"query": " ".join(words(sym.split("::")[-1]))} if sym else None, "no symbol with a caller"),
|
|
1520
|
+
("history", {"files": files[:2]} if files else None, "no file with callers"),
|
|
1521
|
+
("feature_brief", {"goal": " ".join(words(sym.split("::")[-1])) + " handling"} if sym else None, "no symbol with a caller"),
|
|
1522
|
+
("bug_brief", {"ticket": busy} if busy else None, "no tickets"),
|
|
1523
|
+
("rca_trace", {"symptom": msg} if msg else None, "no error signature"),
|
|
1524
|
+
("refactor_scope", {"target": sym} if sym else None, "no symbol with a caller"),
|
|
1525
|
+
("explain_area", {"path": files[0].rsplit("/", 1)[0] if "/" in files[0] else files[0]} if files else None, "no file with callers"),
|
|
1526
|
+
("flow_sequence", {"entry": flow} if flow else None, "no recorded flow"),
|
|
1527
|
+
("test_items", {"area": files[0]} if files else None, "no file with callers"),
|
|
1528
|
+
("design_brief", {"kind": "detailed", "topic": " ".join(words(sym.split("::")[-1]))} if sym else None, "no symbol with a caller"),
|
|
1529
|
+
("review_doc", {"path": doc, "kind": "detailed"} if doc else None, "no spec document on disk"),
|
|
1530
|
+
("role_brief", {"role": role} if role else None, "no declared role"),
|
|
1531
|
+
("config", {"query": setting} if setting else None, "no setting read in code")]
|
|
1532
|
+
per_tool: dict[str, dict] = {}
|
|
1533
|
+
skipped: dict[str, str] = {}
|
|
1534
|
+
for tool, kw, why in plan:
|
|
1535
|
+
if kw is None:
|
|
1536
|
+
skipped[tool] = why
|
|
1537
|
+
continue
|
|
1538
|
+
t0 = time.perf_counter()
|
|
1539
|
+
first = api.call(tool, **kw)
|
|
1540
|
+
first_ms = (time.perf_counter() - t0) * 1000
|
|
1541
|
+
if "error" in first:
|
|
1542
|
+
skipped[tool] = "error: " + str(first["error"])[:60]
|
|
1543
|
+
continue
|
|
1544
|
+
samples = []
|
|
1545
|
+
for _ in range(8 if tool in ("trace", "review_pack") else reps):
|
|
1546
|
+
t0 = time.perf_counter()
|
|
1547
|
+
r = api.call(tool, **kw)
|
|
1548
|
+
samples.append((time.perf_counter() - t0) * 1000)
|
|
1549
|
+
samples.sort()
|
|
1550
|
+
per_tool[tool] = {"first_ms": round(first_ms, 2), "p50_ms": round(statistics.median(samples), 2),
|
|
1551
|
+
"p95_ms": round(samples[max(0, int(len(samples) * 0.95) - 1)], 2),
|
|
1552
|
+
"bytes": len(json.dumps(r, separators=(",", ":")))}
|
|
1553
|
+
worst = max(per_tool, key=lambda k: per_tool[k]["p95_ms"]) if per_tool else ""
|
|
1554
|
+
return {"tools": len(per_tool), "per_tool": per_tool, "skipped": skipped, "slowest": worst,
|
|
1555
|
+
"ok": bool(per_tool) and all(v["p95_ms"] < LATENCY_TARGET_MS and v["bytes"] < REPLY_TARGET_BYTES for v in per_tool.values())}
|
|
1556
|
+
|
|
1557
|
+
|
|
1558
|
+
def bench(code: str) -> dict:
|
|
1559
|
+
t0 = time.perf_counter()
|
|
1560
|
+
ProcessAPI(code, use_cache=False, telemetry=False)
|
|
1561
|
+
cold_rebuild = time.perf_counter() - t0
|
|
1562
|
+
t0 = time.perf_counter()
|
|
1563
|
+
api = ProcessAPI(code, telemetry=False)
|
|
1564
|
+
cold_cached = time.perf_counter() - t0
|
|
1565
|
+
out = {"project": code, "nodes": len(api.idx.keys), "edges": api.idx.n_edges,
|
|
1566
|
+
"cold_rebuild_s": round(cold_rebuild, 2), "cold_cached_s": round(cold_cached, 2),
|
|
1567
|
+
"target_p95_ms": LATENCY_TARGET_MS, **bench_api(api)}
|
|
1568
|
+
return out
|
|
1569
|
+
|
|
1570
|
+
|
|
1571
|
+
def main() -> int:
|
|
1572
|
+
ap = argparse.ArgumentParser(description="devkb process API")
|
|
1573
|
+
ap.add_argument("--project", required=True)
|
|
1574
|
+
ap.add_argument("tool", help="one of: " + ", ".join(sorted(TOOL_ARGS)) + ", bench")
|
|
1575
|
+
ap.add_argument("args", nargs="*", help="positional arguments, then key=value")
|
|
1576
|
+
ns = ap.parse_args()
|
|
1577
|
+
if ns.tool == "bench":
|
|
1578
|
+
out = bench(ns.project)
|
|
1579
|
+
print(json.dumps(out, indent=2))
|
|
1580
|
+
return 0 if out["ok"] else 1
|
|
1581
|
+
if ns.tool not in TOOL_ARGS:
|
|
1582
|
+
print(json.dumps({"error": f"unknown tool {ns.tool}", "tools": sorted(TOOL_ARGS)}))
|
|
1583
|
+
return 2
|
|
1584
|
+
method, pos = TOOL_ARGS[ns.tool]
|
|
1585
|
+
kw: dict = {}
|
|
1586
|
+
plain = [a for a in ns.args if "=" not in a]
|
|
1587
|
+
if ns.tool in TEXT_TOOLS and plain:
|
|
1588
|
+
kw[pos[0]] = " ".join(plain) # a symptom, goal or query is words, not one argument
|
|
1589
|
+
else:
|
|
1590
|
+
for name, value in zip(pos, plain):
|
|
1591
|
+
kw[name] = _coerce(name, value)
|
|
1592
|
+
for a in ns.args:
|
|
1593
|
+
if "=" in a:
|
|
1594
|
+
k, _, v = a.partition("=")
|
|
1595
|
+
kw[k] = _coerce(k, v)
|
|
1596
|
+
print(json.dumps(ProcessAPI(ns.project).call(method, **kw), separators=(",", ":")))
|
|
1597
|
+
return 0
|
|
1598
|
+
|
|
1599
|
+
|
|
1600
|
+
if __name__ == "__main__":
|
|
1601
|
+
sys.exit(main())
|