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.
Files changed (61) hide show
  1. devkb/__init__.py +11 -0
  2. devkb/audit.py +173 -0
  3. devkb/bench/add_packs.py +52 -0
  4. devkb/bench/cli_tasks.py +105 -0
  5. devkb/bench/confirm_tasks.py +149 -0
  6. devkb/bench/module_truth.py +249 -0
  7. devkb/bench/oco_tasks.py +216 -0
  8. devkb/bench/pipeline.py +313 -0
  9. devkb/bench/process_tasks.py +135 -0
  10. devkb/bench/report.py +74 -0
  11. devkb/bench/run.py +174 -0
  12. devkb/bench/truth_check.py +148 -0
  13. devkb/bench/workflow_report.py +64 -0
  14. devkb/bench/workflow_run.py +206 -0
  15. devkb/bench/workflow_tasks.py +227 -0
  16. devkb/build.py +258 -0
  17. devkb/build_symbols.py +1394 -0
  18. devkb/call_recall.py +159 -0
  19. devkb/cli.py +53 -0
  20. devkb/coverage.py +155 -0
  21. devkb/edge_truth.py +272 -0
  22. devkb/extractors/backlog.py +113 -0
  23. devkb/extractors/component_subsystem.py +116 -0
  24. devkb/extractors/configuration.py +267 -0
  25. devkb/extractors/files_tests.py +220 -0
  26. devkb/extractors/flows.py +117 -0
  27. devkb/extractors/lifecycle.py +258 -0
  28. devkb/extractors/members.py +160 -0
  29. devkb/extractors/pull_requests.py +271 -0
  30. devkb/extractors/releases.py +49 -0
  31. devkb/extractors/source_baseline.py +66 -0
  32. devkb/extractors/spec_docs.py +220 -0
  33. devkb/extractors/symbol_tests.py +131 -0
  34. devkb/extractors/test_inventory.py +38 -0
  35. devkb/extractors/ticket_similarity.py +193 -0
  36. devkb/extractors/tickets_git.py +151 -0
  37. devkb/extractors/warnings.py +230 -0
  38. devkb/extractors/work_units.py +90 -0
  39. devkb/github.py +515 -0
  40. devkb/gitutil.py +16 -0
  41. devkb/index.py +51 -0
  42. devkb/init.py +178 -0
  43. devkb/mcp_server.py +216 -0
  44. devkb/model.py +221 -0
  45. devkb/module_file_bridge.py +57 -0
  46. devkb/ontology.md +178 -0
  47. devkb/packs.py +462 -0
  48. devkb/process_api.py +1601 -0
  49. devkb/project_context.py +191 -0
  50. devkb/query.py +251 -0
  51. devkb/service.py +324 -0
  52. devkb/startup.py +103 -0
  53. devkb/test_discovery.py +76 -0
  54. devkb/ts_symbols.py +291 -0
  55. devkb-0.2.0.dist-info/METADATA +162 -0
  56. devkb-0.2.0.dist-info/RECORD +61 -0
  57. devkb-0.2.0.dist-info/WHEEL +5 -0
  58. devkb-0.2.0.dist-info/entry_points.txt +2 -0
  59. devkb-0.2.0.dist-info/licenses/LICENSE +202 -0
  60. devkb-0.2.0.dist-info/licenses/NOTICE +11 -0
  61. 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())