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/init.py ADDED
@@ -0,0 +1,178 @@
1
+ """`devkb init`: integrate devkb into a repository, idempotently, and take it out again.
2
+
3
+ devkb init [--project .] [--toolset lean] [--hooks] [--no-build] [--dry-run]
4
+ devkb init --remove [--project .]
5
+
6
+ Writes managed blocks, never whole files, so the repository's own content is untouched and re-running only refreshes
7
+ the block:
8
+
9
+ AGENTS.md when to use which devkb tool (read by Codex and most coding agents)
10
+ CLAUDE.md `@AGENTS.md`, so Claude Code reads the same instructions (one place to maintain)
11
+ .mcp.json the devkb MCP server, merged into any servers already declared
12
+ .gitignore .devkb/ (the graph is built locally, never committed)
13
+ git hooks with --hooks: rebuild the graph in the background after a commit, merge or checkout
14
+
15
+ Why instructions and not only a server: in the study, agents left to choose used the graph in 88% of runs that
16
+ followed a call chain and in none of the requirement, solution or review runs. The savings were measured with these
17
+ instructions in place.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import argparse
22
+ import json
23
+ import re
24
+ import subprocess
25
+ import sys
26
+ from pathlib import Path
27
+
28
+ BEGIN, END = "<!-- devkb:begin (managed by `devkb init`; edit outside this block) -->", "<!-- devkb:end -->"
29
+ HASH_BEGIN, HASH_END = "# devkb:begin (managed by `devkb init`)", "# devkb:end"
30
+ HOOKS = ("post-commit", "post-merge", "post-checkout")
31
+
32
+ AGENTS_BLOCK = """## devkb: before you change code
33
+
34
+ This repository has a graph of its code (calls, tests, raised errors, commits, configuration) in `.devkb/`. Ask it
35
+ for a whole answer when the question follows a chain; for a one-hop lookup, search as usual. Each answer lists every
36
+ item with the line of code that proves it, and says what it could not see. Use the MCP server's `pack` tool, or the
37
+ same answer from the `devkb pack` command:
38
+
39
+ 1. **Before you edit an existing file**: `pack(kind="file", subject=PATH)` (`devkb pack --project . file PATH`): the
40
+ functions other files call (your change must keep them working), the files that depend on it, the tests to run.
41
+ 2. **Before you change a function's behaviour**: `pack(kind="change", subject=NAME, path=PATH)`: callers at any depth
42
+ and the tests to run.
43
+ 3. **When you start from an error message**: `pack(kind="error", subject=MESSAGE)`: what raises it and the route
44
+ handlers that reach it.
45
+ 4. **Who calls one function directly** (for a signature change): search with grep. It is one hop, and the graph only
46
+ adds a step (measured: packs saved 66-77% on chains, nothing on one-hop lookups).
47
+ 5. **After editing**, run the tests the pack named first, then the full suite. If you edited many files, rebuild
48
+ first: `devkb build --project .`.
49
+
50
+ For questions in between:
51
+
52
+ | Question | Use |
53
+ |---|---|
54
+ | The impact of a change / who calls a function, at any depth | `impact` / `callers` |
55
+ | An error message to its cause | `rca_trace` |
56
+ | Which tests to run | `tests_to_run`, or `tests_for` a file or function |
57
+ | A commit or a diff to review | `review_pack` |
58
+ | A setting or a service | `config` |
59
+
60
+ Rules: an answer marked **Complete** is the whole answer: do not search again or call another tool to check it. If it
61
+ is incomplete, search only the files it names. If it says files changed since the graph was built, re-read those."""
62
+
63
+
64
+ def _between(text: str, begin: str, end: str) -> re.Pattern:
65
+ return re.compile(rf"\n?{re.escape(begin)}.*?{re.escape(end)}\n?", re.S)
66
+
67
+
68
+ def _set_block(text: str, body: str, begin: str = BEGIN, end: str = END) -> str:
69
+ block = f"{begin}\n{body}\n{end}\n"
70
+ rx = _between(text, begin, end)
71
+ if rx.search(text):
72
+ return rx.sub(lambda _m: "\n" + block if _m.group(0).startswith("\n") else block, text, count=1)
73
+ sep = "" if not text else ("\n" if text.endswith("\n") else "\n\n")
74
+ return text + sep + block
75
+
76
+
77
+ def _drop_block(text: str, begin: str = BEGIN, end: str = END) -> str:
78
+ return _between(text, begin, end).sub("\n", text, count=1).strip("\n") + "\n" if begin in text else text
79
+
80
+
81
+ class Plan:
82
+ def __init__(self, root: Path, dry_run: bool) -> None:
83
+ self.root, self.dry_run, self.changes = root, dry_run, []
84
+
85
+ def write(self, rel: str, text: str | None) -> None:
86
+ path = self.root / rel
87
+ old = path.read_text() if path.exists() else None
88
+ if text is not None and not text.strip():
89
+ text = None
90
+ if old == text:
91
+ return
92
+ self.changes.append(f"{'remove' if text is None else 'create' if old is None else 'update'} {rel}")
93
+ if self.dry_run:
94
+ return
95
+ if text is None:
96
+ path.unlink(missing_ok=True)
97
+ else:
98
+ path.parent.mkdir(parents=True, exist_ok=True)
99
+ path.write_text(text)
100
+
101
+
102
+ def _read(path: Path) -> str:
103
+ return path.read_text() if path.exists() else ""
104
+
105
+
106
+ def _mcp(root: Path, toolset: str | None) -> str | None:
107
+ path = root / ".mcp.json"
108
+ try:
109
+ cfg = json.loads(path.read_text()) if path.exists() else {}
110
+ except ValueError:
111
+ raise SystemExit(f"{path} is not valid JSON; fix it or add the devkb server by hand")
112
+ servers = cfg.setdefault("mcpServers", {})
113
+ if toolset is None:
114
+ servers.pop("devkb", None)
115
+ if not servers:
116
+ cfg.pop("mcpServers")
117
+ return json.dumps(cfg, indent=2) + "\n" if cfg else None
118
+ servers["devkb"] = {"command": "devkb", "args": ["mcp", "--project", ".", "--toolset", toolset]}
119
+ return json.dumps(cfg, indent=2) + "\n"
120
+
121
+
122
+ def _hooks_dir(root: Path) -> Path:
123
+ out = subprocess.run(["git", "rev-parse", "--git-path", "hooks"], cwd=root, capture_output=True, text=True)
124
+ if out.returncode != 0:
125
+ raise SystemExit(f"{root} is not a git repository")
126
+ return (root / out.stdout.strip()).resolve()
127
+
128
+
129
+ def _hook(text: str, install: bool) -> str | None:
130
+ body = "( devkb build --project \"$(git rev-parse --show-toplevel)\" > /dev/null 2>&1 & )"
131
+ if install:
132
+ return _set_block(text or "#!/bin/sh\n", body, HASH_BEGIN, HASH_END)
133
+ out = _drop_block(text, HASH_BEGIN, HASH_END)
134
+ return None if out.strip() in ("", "#!/bin/sh") else out
135
+
136
+
137
+ def run(root: Path, toolset: str | None, hooks: bool, dry_run: bool) -> list[str]:
138
+ """toolset None removes devkb. Returns the changes made (or planned, with dry_run)."""
139
+ p = Plan(root, dry_run)
140
+ install = toolset is not None
141
+ agents, claude, ignore = _read(root / "AGENTS.md"), _read(root / "CLAUDE.md"), _read(root / ".gitignore")
142
+ p.write("AGENTS.md", _set_block(agents, AGENTS_BLOCK) if install else _drop_block(agents))
143
+ p.write("CLAUDE.md", _set_block(claude, "@AGENTS.md") if install else _drop_block(claude))
144
+ p.write(".gitignore", _set_block(ignore, ".devkb/", HASH_BEGIN, HASH_END) if install else _drop_block(ignore, HASH_BEGIN, HASH_END))
145
+ p.write(".mcp.json", _mcp(root, toolset))
146
+ hdir = _hooks_dir(root)
147
+ for name in HOOKS:
148
+ path = hdir / name
149
+ if not install or hooks:
150
+ before = len(p.changes)
151
+ p.write(str(path), _hook(_read(path), install)) # an absolute path joins as itself (worktrees)
152
+ if install and len(p.changes) > before and not dry_run:
153
+ path.chmod(0o755)
154
+ return p.changes
155
+
156
+
157
+ def main(argv: list[str] | None = None) -> int:
158
+ ap = argparse.ArgumentParser(prog="devkb init", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
159
+ ap.add_argument("--project", default=".")
160
+ ap.add_argument("--toolset", default="lean-pack", help="the MCP toolset agents get (lean-pack, lean, dev, core, workflow, all)")
161
+ ap.add_argument("--hooks", action="store_true", help="rebuild the graph after commits, merges and checkouts")
162
+ ap.add_argument("--no-build", action="store_true")
163
+ ap.add_argument("--remove", action="store_true", help="take devkb out of the repository again")
164
+ ap.add_argument("--dry-run", action="store_true")
165
+ a = ap.parse_args(argv)
166
+ root = Path(a.project).resolve()
167
+ changes = run(root, None if a.remove else a.toolset, a.hooks, a.dry_run)
168
+ print(("would " if a.dry_run else "") + ("\n".join(changes) if changes else "nothing to change"))
169
+ if not (a.remove or a.no_build or a.dry_run):
170
+ from devkb import cli # noqa: PLC0415
171
+ return cli.main(["build", "--project", str(root)])
172
+ if not a.remove and not a.dry_run:
173
+ print(f"next: devkb build --project {a.project}")
174
+ return 0
175
+
176
+
177
+ if __name__ == "__main__":
178
+ raise SystemExit(main())
devkb/mcp_server.py ADDED
@@ -0,0 +1,216 @@
1
+ #!/usr/bin/env python3
2
+ """devkb-sdlc: the software-engineering-process API as an MCP server (ODSF-307).
3
+
4
+ Read-only tools over one project's devkb graph, one per question a development
5
+ stage asks. Tool descriptions are kept to a sentence on purpose: an MCP
6
+ server's tool list is paid for in every model turn, so a long description is a
7
+ recurring token cost, not a one-off.
8
+
9
+ uv run --python ">=3.10" --no-project --with "mcp>=1.23,<2" python devkb/mcp_server.py --project ODSF
10
+
11
+ Environment: DEVKB_PROJECT (default project), DEVKB_TOOLSET (core, workflow or all), DEVKB_DIR (a pinned graph snapshot
12
+ instead of the live `.devkb/`).
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import json
18
+ import os
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
23
+
24
+ from mcp.server.fastmcp import FastMCP # noqa: E402
25
+ from mcp.types import ToolAnnotations # noqa: E402
26
+
27
+ from devkb.process_api import ProcessAPI, project_for # noqa: E402
28
+
29
+ READ_ONLY = ToolAnnotations(readOnlyHint=True, idempotentHint=True, destructiveHint=False, openWorldHint=False)
30
+ CORE = ["sdlc_context", "trace", "find_docs", "callers", "tests_for", "tests_to_run", "impact", "owner", "review_pack",
31
+ "lineage", "graph_status", "config"]
32
+ WORKFLOW = ["feature_brief", "bug_brief", "rca_trace", "refactor_scope", "explain_area", "find_code", "history"]
33
+ DOCS = ["design_brief", "flow_sequence", "test_items", "review_doc", "role_brief"]
34
+ # `core`: single-question tools. `workflow`: one tool per kind of development work, plus the few core tools those
35
+ # workflows still need. `docs`: writing and reviewing designs and test specifications, and starting a role's session
36
+ # (ODSF-311). `all`: every tool. A smaller set costs fewer tokens to load, so the choice is a deployment decision.
37
+ TOOLSETS = {"core": CORE, "workflow": WORKFLOW + ["review_pack", "tests_to_run", "impact", "sdlc_context", "find_docs"],
38
+ "docs": DOCS + ["find_docs", "explain_area", "find_code", "sdlc_context", "history"],
39
+ # ODSF-313: only the tools the benchmarks showed earn their place (chains and joins), so each turn loads fewer
40
+ # tool definitions. Their list answers all carry `coverage`.
41
+ "lean": ["rca_trace", "impact", "callers", "tests_for", "tests_to_run", "review_pack", "config"],
42
+ # `devkb init`'s default: lean, plus orienting in an area before writing new code there. Lean alone left an
43
+ # agent implementing a feature with nothing to ask (it read whole files instead); lean stays as measured.
44
+ # Packs over MCP: one call returns a whole answer (the measured "pack" arm put it in the prompt; here the
45
+ # agent asks for it). `lean-pack` is the arm that measures that; `lean` stays as measured.
46
+ "lean-pack": ["rca_trace", "impact", "callers", "tests_for", "tests_to_run", "review_pack", "config", "pack"],
47
+ "dev": ["rca_trace", "impact", "callers", "tests_for", "tests_to_run", "review_pack", "config",
48
+ "explain_area", "feature_brief", "find_code", "pack"],
49
+ "all": CORE + WORKFLOW + DOCS + ["pack"]}
50
+ INSTRUCTIONS = ("Dev-process graph for this repository: tickets, specs, commits, symbols, calls, tests, owners. "
51
+ "Ask it first, then read only the files it names. Every reply says if the graph is stale.")
52
+
53
+
54
+ def _compact(reply: dict) -> str:
55
+ """Compact JSON text. FastMCP pretty-prints a dict return with indentation, which
56
+ costs the model tokens on every call for no reader."""
57
+ return json.dumps(reply, separators=(",", ":"))
58
+
59
+
60
+ def build(api: ProcessAPI, toolset: str = "all") -> FastMCP:
61
+ mcp = FastMCP("devkb-sdlc", instructions=INSTRUCTIONS)
62
+ enabled = set(TOOLSETS[toolset])
63
+
64
+ def tool(fn):
65
+ return mcp.tool(annotations=READ_ONLY, structured_output=False)(fn) if fn.__name__ in enabled else fn
66
+
67
+ @tool
68
+ def sdlc_context(ticket: str) -> str:
69
+ """Brief for a ticket: status, owner role, epic, spec and requirement chain, related docs, similar tickets, commit and file counts."""
70
+ return _compact(api.call("sdlc_context", ticket=ticket))
71
+
72
+ @tool
73
+ def trace(ticket: str) -> str:
74
+ """Requirement-to-ticket chain with status, and the Gate 0 readiness verdict for a story."""
75
+ return _compact(api.call("trace", ticket=ticket))
76
+
77
+ @tool
78
+ def find_docs(topic: str, kinds: list[str] | None = None, limit: int = 8) -> str:
79
+ """Ranked specs, ADRs and design docs on a topic. kinds: specification, adr, design."""
80
+ return _compact(api.call("find_docs", topic=topic, kinds=kinds, limit=limit))
81
+
82
+ @tool
83
+ def callers(symbol: str, depth: int = 1) -> str:
84
+ """Who calls this function (name or path::name), directly and up to depth 3; tests are listed last."""
85
+ return _compact(api.call("callers", symbol=symbol, depth=depth))
86
+
87
+ @tool
88
+ def tests_for(ref: str) -> str:
89
+ """Tests linked to a function or file, with a runnable pytest line."""
90
+ return _compact(api.call("tests_for", ref=ref))
91
+
92
+ @tool
93
+ def tests_to_run(files: list[str]) -> str:
94
+ """Which tests to run for these changed files, ranked, with a runnable pytest line."""
95
+ return _compact(api.call("tests_to_run", files=files))
96
+
97
+ @tool
98
+ def impact(files: list[str], depth: int = 2) -> str:
99
+ """Blast radius of changing these files: affected callers, endpoints, flows, tests to run, owning roles."""
100
+ return _compact(api.call("impact", files=files, depth=depth))
101
+
102
+ @tool
103
+ def owner(path: str) -> str:
104
+ """Which role owns a path and which roles must not touch it."""
105
+ return _compact(api.call("owner", path=path))
106
+
107
+ @tool
108
+ def pack(kind: str, subject: str, path: str = "", role: str = "") -> str:
109
+ """Whole answer in one call, with proof lines and coverage. kind: file (subject=path), refactor or change (a function), error (message), pr, ticket."""
110
+ from devkb.packs import Packer # noqa: PLC0415
111
+ p = Packer(api)
112
+ run = {"file": lambda: p.file(subject), "refactor": lambda: p.refactor(subject, role, path),
113
+ "change": lambda: p.change(subject, path), "error": lambda: p.error(subject),
114
+ "pr": lambda: p.pr(subject), "ticket": lambda: p.ticket(subject)}.get(kind)
115
+ return run() if run else f"Unknown kind {kind!r}: use file, refactor, change, error, pr or ticket."
116
+
117
+ @tool
118
+ def review_pack(rev: str) -> str:
119
+ """Review context for a commit or range (a..b): changed symbols, callers outside the diff, tests, untested symbols, docs, warnings, owners."""
120
+ return _compact(api.call("review_pack", rev=rev))
121
+
122
+ @tool
123
+ def lineage(ticket: str) -> str:
124
+ """Bug lineage, duplicates, blockers, commits and spec of a ticket."""
125
+ return _compact(api.call("lineage", ticket=ticket))
126
+
127
+ @tool
128
+ def feature_brief(goal: str, ticket: str = "") -> str:
129
+ """Build a feature: similar code, governing docs, similar past work, owner and forbidden paths, tests to copy and run."""
130
+ return _compact(api.call("feature_brief", goal=goal, ticket=ticket))
131
+
132
+ @tool
133
+ def bug_brief(ticket: str = "", text: str = "") -> str:
134
+ """Fix a bug from a ticket id or symptom text: suspects, entry points, recent commits, similar past bugs and their fixes, tests."""
135
+ return _compact(api.call("bug_brief", ticket=ticket, text=text))
136
+
137
+ @tool
138
+ def rca_trace(symptom: str, depth: int = 3) -> str:
139
+ """Root cause: an error message or name to the raising code, callers up to the entry points, recent commits on that path, tests."""
140
+ return _compact(api.call("rca_trace", symptom=symptom, depth=depth))
141
+
142
+ @tool
143
+ def refactor_scope(target: str, role: str = "") -> str:
144
+ """Before a refactor: callers by file, test files, endpoints, tests to run, and caller files your role code may not edit."""
145
+ return _compact(api.call("refactor_scope", target=target, role=role))
146
+
147
+ @tool
148
+ def explain_area(path: str) -> str:
149
+ """Understand a directory or file: key symbols by dependents, entry points, owners, governing docs, tests, recent commits."""
150
+ return _compact(api.call("explain_area", path=path))
151
+
152
+ @tool
153
+ def find_code(query: str, under: str = "") -> str:
154
+ """Find code by plain words matched against symbol names, paths and docstrings; optionally under a path prefix."""
155
+ return _compact(api.call("find_code", query=query, under=under))
156
+
157
+ @tool
158
+ def history(files: list[str]) -> str:
159
+ """The latest commits that touched these files, with dates and ticket ids."""
160
+ return _compact(api.call("history", files=files))
161
+
162
+ @tool
163
+ def design_brief(kind: str, topic: str) -> str:
164
+ """Before writing a functional, architecture, detailed or sequence design or a test_spec: outline, facts to cite, related docs, next spec id."""
165
+ return _compact(api.call("design_brief", kind=kind, topic=topic))
166
+
167
+ @tool
168
+ def flow_sequence(entry: str) -> str:
169
+ """Recorded call order from an endpoint, function or flow id, as numbered messages and Mermaid sequence-diagram text."""
170
+ return _compact(api.call("flow_sequence", entry=entry))
171
+
172
+ @tool
173
+ def test_items(area: str) -> str:
174
+ """Test items for a path or function from what it raises, the endpoints it serves and untested branches, marked covered or not."""
175
+ return _compact(api.call("test_items", area=area))
176
+
177
+ @tool
178
+ def review_doc(path: str, kind: str = "") -> str:
179
+ """Review a design or test-spec document against the repo: broken references, drift since written, unmentioned code, missing sections."""
180
+ return _compact(api.call("review_doc", path=path, kind=kind))
181
+
182
+ @tool
183
+ def role_brief(role: str) -> str:
184
+ """Session start for a role code (QA, BE, TL, OPS, DSA, DE...): territory, waiting tickets, key code, tests, docs, role-specific facts."""
185
+ return _compact(api.call("role_brief", role=role))
186
+
187
+ @tool
188
+ def config(query: str = "") -> str:
189
+ """A setting (env var) or service: code reading it, files declaring it, services deploying it, repos; empty for an overview."""
190
+ return _compact(api.call("config", query=query))
191
+
192
+ @tool
193
+ def graph_status() -> str:
194
+ """Size of the graph and whether it is stale against the repository."""
195
+ return _compact(api.call("graph_status"))
196
+
197
+ return mcp
198
+
199
+
200
+ def main() -> int:
201
+ ap = argparse.ArgumentParser(description="devkb-sdlc MCP server (stdio)")
202
+ ap.add_argument("--project", default=os.environ.get("DEVKB_PROJECT"))
203
+ ap.add_argument("--devkb-dir", default=os.environ.get("DEVKB_DIR"))
204
+ ap.add_argument("--toolset", default=os.environ.get("DEVKB_TOOLSET", "lean-pack"), choices=sorted(TOOLSETS))
205
+ ns = ap.parse_args()
206
+ if not ns.project:
207
+ ns.project = project_for(Path.cwd())
208
+ if not ns.project:
209
+ ap.error("--project or DEVKB_PROJECT is required (and the working directory is in no registered project)")
210
+ api = ProcessAPI(ns.project, devkb_dir=Path(ns.devkb_dir) if ns.devkb_dir else None)
211
+ build(api, ns.toolset).run(transport="stdio")
212
+ return 0
213
+
214
+
215
+ if __name__ == "__main__":
216
+ sys.exit(main())
devkb/model.py ADDED
@@ -0,0 +1,221 @@
1
+ """Node/edge model for the dev-process knowledge graph (ADR-SDP-DEVKB-001).
2
+
3
+ Deliberately storage-free, mirroring discovery/model.py's own shape (Node/Edge/
4
+ graph-container, deterministic uid, JSON-serializable) rather than inventing a
5
+ second graph representation for the same kind of problem — but a distinct
6
+ "devkb:" uid domain, so a project's .devkb/ store and its .onboarding/graph.json
7
+ can never collide or be silently conflated (different hash domain, different
8
+ vocabulary, different update cadence).
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import json
13
+
14
+ import hashlib
15
+ from dataclasses import dataclass, field
16
+ from typing import Any, Iterable, Iterator
17
+
18
+ # Node types (devkb/ontology.md, ADR-SDP-DEVKB-001). Phase 1 + Phase 2
19
+ # (File/TestCase, ODSF-032) + Phase 3 (Warning, ODSF-033) + the BL-series
20
+ # (Symbol/Release/WorkUnit, body/legs model -- ticket-independent knowledge
21
+ # building) + the KNOWLEDGE_SPEC.md batch (Endpoint/Component/Subsystem/
22
+ # Flow/ErrorSignature/Spec, BL-7 through BL-14, ODSF-043) + the renovated
23
+ # lifecycle (Requirement/Evidence, BL-14, ADR-SDP-DEVKB-002 §1, ODSF-230).
24
+ # Epic and Story are deliberately NOT here: they are Ticket nodes carrying
25
+ # `ticket_type`, and the names are query aliases (ADR-SDP-DEVKB-002 §2).
26
+ NODE_TYPES = (
27
+ "Ticket", "Commit", "WorkPackage", "Milestone", "File", "TestCase", "Warning",
28
+ "Symbol", "Release", "WorkUnit",
29
+ "Endpoint", "Component", "Subsystem", "Flow", "ErrorSignature", "Spec",
30
+ "Requirement", # one PMS requirement, natural key REQ-NNN (BL-14)
31
+ "Evidence", # one ev_/of_ evidence record, confidence as recorded (BL-14)
32
+ # ADR-SDP-DEVKB-005 (ODSF-312): a product graph spans member repositories; settings are things.
33
+ "Repository", # one registered project's repository, natural key its project code
34
+ "ConfigKey", # one named setting (env var or config-file key); its value is never stored
35
+ # ADR-DEVKB-007: a pull request is a change set that merges commits and closes tickets; hosted issues are Tickets.
36
+ "PullRequest", # one pull request, natural key PR-<number>; no description, review text or author by default
37
+ )
38
+
39
+ VERBS = (
40
+ "REFERENCES", # Commit -> Ticket
41
+ "CAUSED_BY", # Ticket -> Ticket (Bug Lineage)
42
+ "REGRESSION_OF", # Ticket -> Ticket (Bug Lineage)
43
+ "DUPLICATE_OF", # Ticket -> Ticket (Bug Lineage)
44
+ "BLOCKS", # Ticket -> Ticket (Bug Lineage)
45
+ "PART_OF", # Ticket -> WorkPackage, or File -> Component (BL-8)
46
+ "BELONGS_TO", # WorkPackage -> Milestone
47
+ "TOUCHES", # Commit -> File
48
+ "TESTED_BY", # File -> TestCase, or Symbol -> TestCase (BL-4)
49
+ "FLAGGED_BY", # File -> Warning
50
+ "DEFINED_IN", # Symbol -> File
51
+ "CALLS", # Symbol -> Symbol (same language; Python cross-file, BL-3b)
52
+ "TAGS", # Release -> Commit
53
+ "GROUPS", # WorkUnit -> Commit
54
+ "CALLS_API", # Symbol (frontend, TS) -> Symbol (backend route handler, BL-4b)
55
+ "REALIZES", # Component -> Subsystem (BL-8)
56
+ "REGISTERED_ON", # Symbol (middleware) -> Endpoint (BL-10)
57
+ "RAISES", # Symbol -> ErrorSignature (BL-9)
58
+ "LOGS", # Symbol -> ErrorSignature (BL-9)
59
+ "SIMILAR_TO", # Ticket -> Ticket, threshold-free (BL-11)
60
+ "STEP", # Flow -> Symbol|Endpoint, sequence: int property (BL-12)
61
+ "DOCUMENTS", # Spec -> Ticket (BL-13)
62
+ # BL-14, ADR-SDP-DEVKB-002 §3 -- all four from extractors/lifecycle.py.
63
+ "CHILD_OF", # Story (Ticket) -> Epic (Ticket), Trace `Epic` row
64
+ "DERIVED_FROM", # Ticket -> Requirement, Trace `Requirement` row
65
+ "IMPLEMENTS", # Ticket -> Spec, Trace `Specification` row
66
+ "EVIDENCED_BY", # Ticket | Spec -> Evidence, a cited ev_/of_ id
67
+ # ADR-SDP-DEVKB-005 (ODSF-312), extractors/configuration.py and extractors/members.py.
68
+ "IN_REPO", # File -> Repository
69
+ "READS", # Symbol | File (module level) -> ConfigKey
70
+ "DECLARES", # File -> ConfigKey (.env.example, compose environment, systemd Environment=, pms.config.json)
71
+ "DEPLOYS", # File -> Component (compose service, systemd unit, Dockerfile)
72
+ # ADR-DEVKB-007, extractors/pull_requests.py.
73
+ "MERGES", # PullRequest -> Commit: the commits it brought in (git subjects 0.9, GitHub's list 1.0)
74
+ "CLOSES", # PullRequest -> Ticket: the issues it closes (GitHub's record 1.0, a commit keyword 0.7 unverified)
75
+ )
76
+
77
+
78
+ def uid_for(node_type: str, natural_key: str) -> str:
79
+ """Deterministic SHA-256 identity, same rationale as discovery/model.py's
80
+ own uid_for: a node keeps its identity across re-runs, so a diff between
81
+ two builds means something instead of being noise from re-ordered
82
+ iteration. "devkb:" prefix keeps this store's uids out of any other
83
+ graph's namespace (discovery's are "discovery:", OCO's are bare sha256)."""
84
+ digest = hashlib.sha256(f"{node_type}:{natural_key}".encode()).hexdigest()
85
+ return f"devkb:{node_type.lower()}:{digest[:16]}"
86
+
87
+
88
+ @dataclass
89
+ class Node:
90
+ type: str
91
+ natural_key: str
92
+ source: str
93
+ props: dict[str, Any] = field(default_factory=dict)
94
+
95
+ @property
96
+ def uid(self) -> str:
97
+ return uid_for(self.type, self.natural_key)
98
+
99
+ def to_dict(self) -> dict[str, Any]:
100
+ return {
101
+ "uid": self.uid,
102
+ "type": self.type,
103
+ "natural_key": self.natural_key,
104
+ "source": self.source,
105
+ "properties": self.props,
106
+ }
107
+
108
+
109
+ @dataclass(frozen=True)
110
+ class Edge:
111
+ verb: str
112
+ src: str # natural key of the source node (same type-scoped key as Node.natural_key)
113
+ src_type: str
114
+ dst: str
115
+ dst_type: str
116
+ source: str
117
+ confidence: float = 1.0
118
+ evidence_ref: str = ""
119
+ # Verb-specific structured data beyond the three fields every edge
120
+ # already has -- e.g. SIMILAR_TO's shared_file_count/overlap_score
121
+ # (BL-11), meant to be sorted/filtered on at query time, not buried in
122
+ # evidence_ref's free text. hash=False/compare=False: two edges with
123
+ # the same (verb, src, dst) are the same edge for dedup purposes
124
+ # regardless of extra content -- callers that need per-pair extras must
125
+ # not add_edge() the same triple twice with different values.
126
+ extra: dict[str, Any] = field(default_factory=dict, hash=False, compare=False)
127
+
128
+ @property
129
+ def from_uid(self) -> str:
130
+ return uid_for(self.src_type, self.src)
131
+
132
+ @property
133
+ def to_uid(self) -> str:
134
+ return uid_for(self.dst_type, self.dst)
135
+
136
+ def to_dict(self) -> dict[str, Any]:
137
+ return {
138
+ "from_uid": self.from_uid,
139
+ "to_uid": self.to_uid,
140
+ "verb": self.verb,
141
+ "properties": {
142
+ "source": self.source,
143
+ "confidence": self.confidence,
144
+ "evidence_ref": self.evidence_ref,
145
+ **self.extra,
146
+ },
147
+ }
148
+
149
+
150
+ class DevKBGraph:
151
+ """An in-memory dev-process graph with by-type/by-verb iteration. No
152
+ index by uid/adjacency here -- that's devkb/index.py's job, built once at
153
+ query time (traverse_graph.py's GraphIndex pattern), not baked into the
154
+ storage-free container itself."""
155
+
156
+ def __init__(self) -> None:
157
+ self._nodes: dict[tuple[str, str], Node] = {}
158
+ self._edges: set[Edge] = set()
159
+
160
+ def add_node(self, node_type: str, natural_key: str, source: str, **props: Any) -> Node:
161
+ if node_type not in NODE_TYPES:
162
+ raise ValueError(f"unknown node type {node_type!r}, expected one of {NODE_TYPES}")
163
+ key = (node_type, natural_key)
164
+ existing = self._nodes.get(key)
165
+ clean_props = {k: v for k, v in props.items() if v is not None}
166
+ if existing is not None:
167
+ existing.props.update(clean_props)
168
+ return existing
169
+ node = Node(node_type, natural_key, source, clean_props)
170
+ self._nodes[key] = node
171
+ return node
172
+
173
+ def add_edge(
174
+ self, verb: str, src_type: str, src: str, dst_type: str, dst: str,
175
+ source: str, confidence: float = 1.0, evidence_ref: str = "",
176
+ extra: dict[str, Any] | None = None,
177
+ ) -> None:
178
+ if verb not in VERBS:
179
+ raise ValueError(f"unknown verb {verb!r}, expected one of {VERBS}")
180
+ self._edges.add(Edge(verb, src, src_type, dst, dst_type, source, confidence, evidence_ref, extra or {}))
181
+
182
+ def nodes(self, node_type: str | None = None) -> Iterator[Node]:
183
+ for (t, _key), node in self._nodes.items():
184
+ if node_type is None or t == node_type:
185
+ yield node
186
+
187
+ def edges(self, verb: str | None = None) -> Iterator[Edge]:
188
+ for edge in self._edges:
189
+ if verb is None or edge.verb == verb:
190
+ yield edge
191
+
192
+ def to_dict(self) -> dict[str, Any]:
193
+ return {
194
+ "nodes": [n.to_dict() for n in self._nodes.values()],
195
+ # every field in the key: two extractors' edges with the same ends (TOUCHES from
196
+ # git and from the baseline) must not come out in set order (ODSF-230 determinism)
197
+ "edges": [e.to_dict() for e in sorted(self._edges, key=lambda e: (
198
+ e.verb, e.src, e.dst, e.src_type, e.dst_type, e.source, e.evidence_ref, e.confidence,
199
+ json.dumps(e.extra, sort_keys=True, default=str)))],
200
+ }
201
+
202
+ def node_count(self) -> int:
203
+ return len(self._nodes)
204
+
205
+ def edge_count(self) -> int:
206
+ return len(self._edges)
207
+
208
+
209
+ def merge(graphs: Iterable[DevKBGraph]) -> DevKBGraph:
210
+ """Combine N per-extractor graphs into one project-wide graph -- each
211
+ extractor only knows its own source, so cross-source edges (e.g. a
212
+ Commit REFERENCES a Ticket) are only correct once both sides' nodes
213
+ exist, which is why build.py runs extractors before merging, not
214
+ interleaved."""
215
+ out = DevKBGraph()
216
+ for g in graphs:
217
+ for n in g.nodes():
218
+ out.add_node(n.type, n.natural_key, n.source, **n.props)
219
+ for e in g.edges():
220
+ out.add_edge(e.verb, e.src_type, e.src, e.dst_type, e.dst, e.source, e.confidence, e.evidence_ref, e.extra)
221
+ return out
@@ -0,0 +1,57 @@
1
+ """Module (discovery/graph.json) <-> File (devkb) natural-key translation
2
+ (devkb Phase 2 step 2, ADR-SDP-DEVKB-001, ODSF-032).
3
+
4
+ The two graphs stay independent stores -- different domain, different update
5
+ cadence, per the ADR's own rejection of merging them. This is a query-time
6
+ join helper only, never a persisted merge.
7
+
8
+ Translation is exact, not a dotted-module-to-path guess: extract_python.py/
9
+ extract_typescript.py already write each Module node's `file` property
10
+ relative to its own Service's root, and each Service node's `root` property
11
+ is that service's absolute path -- so a Module's path relative to repo_root
12
+ is just `service.root.relative_to(repo_root) / module.file`.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ from pathlib import Path
18
+
19
+
20
+ def build_module_to_file(discovery_graph_path: Path, repo_root: Path) -> dict[str, str]:
21
+ """{module_natural_key: file_path_relative_to_repo_root}. A Module whose
22
+ Service has no root under repo_root, or whose graph.json is missing/
23
+ unreadable, is silently skipped -- "can't translate" is a correct answer
24
+ here, not an error worth raising (a discovery graph may not exist yet,
25
+ e.g. before Step 2 of onboard.py has ever run)."""
26
+ try:
27
+ data = json.loads(discovery_graph_path.read_text())
28
+ except (OSError, ValueError):
29
+ return {}
30
+
31
+ service_roots: dict[str, Path] = {}
32
+ for n in data.get("nodes", []):
33
+ if n.get("type") == "Service" and n.get("root"):
34
+ service_roots[n["natural_key"]] = Path(n["root"])
35
+
36
+ repo_root_resolved = repo_root.resolve()
37
+ out: dict[str, str] = {}
38
+ for n in data.get("nodes", []):
39
+ if n.get("type") != "Module":
40
+ continue
41
+ svc_root = service_roots.get(n.get("service"))
42
+ rel_file = n.get("file")
43
+ if svc_root is None or not rel_file:
44
+ continue
45
+ try:
46
+ svc_rel = svc_root.resolve().relative_to(repo_root_resolved)
47
+ except ValueError:
48
+ continue # service root isn't under this repo -- can't translate
49
+ out[n["natural_key"]] = str(svc_rel / rel_file)
50
+ return out
51
+
52
+
53
+ def file_to_module(discovery_graph_path: Path, repo_root: Path) -> dict[str, str]:
54
+ """Inverse of build_module_to_file -- the direction devkb's own File
55
+ nodes need at query time: given a devkb File natural_key (a repo-relative
56
+ path), find the richer discovery Module context (service, uid) for it."""
57
+ return {file_path: mod_key for mod_key, file_path in build_module_to_file(discovery_graph_path, repo_root).items()}