devkb 0.2.0__tar.gz → 0.2.1__tar.gz

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 (98) hide show
  1. {devkb-0.2.0/devkb.egg-info → devkb-0.2.1}/PKG-INFO +7 -1
  2. {devkb-0.2.0 → devkb-0.2.1}/README.md +6 -0
  3. devkb-0.2.1/devkb/cpp_symbols.py +338 -0
  4. {devkb-0.2.0 → devkb-0.2.1}/devkb/mcp_server.py +27 -2
  5. {devkb-0.2.0 → devkb-0.2.1/devkb.egg-info}/PKG-INFO +7 -1
  6. {devkb-0.2.0 → devkb-0.2.1}/devkb.egg-info/SOURCES.txt +2 -0
  7. {devkb-0.2.0 → devkb-0.2.1}/pyproject.toml +1 -1
  8. devkb-0.2.1/tests/test_claude_plugin.py +30 -0
  9. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_mcp_odsf307.py +19 -0
  10. {devkb-0.2.0 → devkb-0.2.1}/LICENSE +0 -0
  11. {devkb-0.2.0 → devkb-0.2.1}/NOTICE +0 -0
  12. {devkb-0.2.0 → devkb-0.2.1}/devkb/__init__.py +0 -0
  13. {devkb-0.2.0 → devkb-0.2.1}/devkb/audit.py +0 -0
  14. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/add_packs.py +0 -0
  15. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/cli_tasks.py +0 -0
  16. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/confirm_tasks.py +0 -0
  17. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/module_truth.py +0 -0
  18. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/oco_tasks.py +0 -0
  19. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/pipeline.py +0 -0
  20. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/process_tasks.py +0 -0
  21. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/report.py +0 -0
  22. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/run.py +0 -0
  23. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/truth_check.py +0 -0
  24. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/workflow_report.py +0 -0
  25. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/workflow_run.py +0 -0
  26. {devkb-0.2.0 → devkb-0.2.1}/devkb/bench/workflow_tasks.py +0 -0
  27. {devkb-0.2.0 → devkb-0.2.1}/devkb/build.py +0 -0
  28. {devkb-0.2.0 → devkb-0.2.1}/devkb/build_symbols.py +0 -0
  29. {devkb-0.2.0 → devkb-0.2.1}/devkb/call_recall.py +0 -0
  30. {devkb-0.2.0 → devkb-0.2.1}/devkb/cli.py +0 -0
  31. {devkb-0.2.0 → devkb-0.2.1}/devkb/coverage.py +0 -0
  32. {devkb-0.2.0 → devkb-0.2.1}/devkb/edge_truth.py +0 -0
  33. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/backlog.py +0 -0
  34. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/component_subsystem.py +0 -0
  35. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/configuration.py +0 -0
  36. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/files_tests.py +0 -0
  37. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/flows.py +0 -0
  38. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/lifecycle.py +0 -0
  39. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/members.py +0 -0
  40. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/pull_requests.py +0 -0
  41. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/releases.py +0 -0
  42. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/source_baseline.py +0 -0
  43. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/spec_docs.py +0 -0
  44. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/symbol_tests.py +0 -0
  45. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/test_inventory.py +0 -0
  46. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/ticket_similarity.py +0 -0
  47. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/tickets_git.py +0 -0
  48. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/warnings.py +0 -0
  49. {devkb-0.2.0 → devkb-0.2.1}/devkb/extractors/work_units.py +0 -0
  50. {devkb-0.2.0 → devkb-0.2.1}/devkb/github.py +0 -0
  51. {devkb-0.2.0 → devkb-0.2.1}/devkb/gitutil.py +0 -0
  52. {devkb-0.2.0 → devkb-0.2.1}/devkb/index.py +0 -0
  53. {devkb-0.2.0 → devkb-0.2.1}/devkb/init.py +0 -0
  54. {devkb-0.2.0 → devkb-0.2.1}/devkb/model.py +0 -0
  55. {devkb-0.2.0 → devkb-0.2.1}/devkb/module_file_bridge.py +0 -0
  56. {devkb-0.2.0 → devkb-0.2.1}/devkb/ontology.md +0 -0
  57. {devkb-0.2.0 → devkb-0.2.1}/devkb/packs.py +0 -0
  58. {devkb-0.2.0 → devkb-0.2.1}/devkb/process_api.py +0 -0
  59. {devkb-0.2.0 → devkb-0.2.1}/devkb/project_context.py +0 -0
  60. {devkb-0.2.0 → devkb-0.2.1}/devkb/query.py +0 -0
  61. {devkb-0.2.0 → devkb-0.2.1}/devkb/service.py +0 -0
  62. {devkb-0.2.0 → devkb-0.2.1}/devkb/startup.py +0 -0
  63. {devkb-0.2.0 → devkb-0.2.1}/devkb/test_discovery.py +0 -0
  64. {devkb-0.2.0 → devkb-0.2.1}/devkb/ts_symbols.py +0 -0
  65. {devkb-0.2.0 → devkb-0.2.1}/devkb.egg-info/dependency_links.txt +0 -0
  66. {devkb-0.2.0 → devkb-0.2.1}/devkb.egg-info/entry_points.txt +0 -0
  67. {devkb-0.2.0 → devkb-0.2.1}/devkb.egg-info/requires.txt +0 -0
  68. {devkb-0.2.0 → devkb-0.2.1}/devkb.egg-info/top_level.txt +0 -0
  69. {devkb-0.2.0 → devkb-0.2.1}/setup.cfg +0 -0
  70. {devkb-0.2.0 → devkb-0.2.1}/tests/test_bench_pipeline_detail.py +0 -0
  71. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_ablation_process_odsf316.py +0 -0
  72. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_audit_efficiency_odsf314.py +0 -0
  73. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_authoring_odsf311.py +0 -0
  74. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bench_odsf308.py +0 -0
  75. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bl_baseline_symbols_odsf042.py +0 -0
  76. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bl_containment_errors_criticality_odsf043.py +0 -0
  77. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bl_crossfile_ts_api_odsf043.py +0 -0
  78. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bl_linkage_workunits_odsf042.py +0 -0
  79. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_bl_similarity_flows_specs_odsf043.py +0 -0
  80. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_builder_checkout_odsf104.py +0 -0
  81. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_call_resolution_odsf305.py +0 -0
  82. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_confirmatory_truth_odsf315.py +0 -0
  83. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_coverage_classes_odsf313.py +0 -0
  84. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_coverage_odsf304.py +0 -0
  85. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_files_tests_odsf032.py +0 -0
  86. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_init.py +0 -0
  87. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_process_api_odsf306.py +0 -0
  88. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_process_api_odsf309.py +0 -0
  89. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_product_graph_odsf312.py +0 -0
  90. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_pull_requests_adr007.py +0 -0
  91. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_similarity_ranking_odsf059.py +0 -0
  92. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_submodules_odsf312.py +0 -0
  93. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_typed_calls_odsf312.py +0 -0
  94. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_warnings_odsf033.py +0 -0
  95. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_workflow_bench_odsf310.py +0 -0
  96. {devkb-0.2.0 → devkb-0.2.1}/tests/test_devkb_workflows_odsf310.py +0 -0
  97. {devkb-0.2.0 → devkb-0.2.1}/tests/test_module_truth_routes.py +0 -0
  98. {devkb-0.2.0 → devkb-0.2.1}/tests/test_reexports_module_calls.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: devkb
3
- Version: 0.2.0
3
+ Version: 0.2.1
4
4
  Summary: A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server
5
5
  Author: Hung T. Le
6
6
  License-Expression: Apache-2.0
@@ -129,6 +129,12 @@ devkb pack --project . file path/to/file.py # before editing a file
129
129
 
130
130
  **Claude Code**: nothing more to do. `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the
131
131
  instructions. Start `claude` in the repository, approve the `devkb` server when asked, and check it with `/mcp`.
132
+ Or skip `pip` and `devkb init` and install the plugin, which brings the server, its instructions and a hook that builds
133
+ the graph in the background (needs [uv](https://docs.astral.sh/uv/)):
134
+
135
+ ```
136
+ /plugin install devkb --marketplace namiq-ai/devkb
137
+ ```
132
138
 
133
139
  **Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:
134
140
 
@@ -93,6 +93,12 @@ devkb pack --project . file path/to/file.py # before editing a file
93
93
 
94
94
  **Claude Code**: nothing more to do. `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the
95
95
  instructions. Start `claude` in the repository, approve the `devkb` server when asked, and check it with `/mcp`.
96
+ Or skip `pip` and `devkb init` and install the plugin, which brings the server, its instructions and a hook that builds
97
+ the graph in the background (needs [uv](https://docs.astral.sh/uv/)):
98
+
99
+ ```
100
+ /plugin install devkb --marketplace namiq-ai/devkb
101
+ ```
96
102
 
97
103
  **Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:
98
104
 
@@ -0,0 +1,338 @@
1
+ """C/C++ Symbol and call extraction (stdlib only, no parser dependency).
2
+
3
+ Same trade as ts_symbols.py: a scanner, not a compiler. It masks comments, string and character literals and
4
+ preprocessor lines, then walks the braces, so a `{` in a string or a commented-out function never confuses it. It
5
+ finds function *definitions* (free functions, methods defined in a class body, `Foo::bar` defined out of line,
6
+ constructors, destructors, operators) and `class`/`struct`/`union`/`enum` definitions, nested in namespaces and
7
+ classes, and the calls inside each function body.
8
+
9
+ What it does not do, and says so rather than guess: no preprocessor expansion (a function a macro generates has no
10
+ Symbol), no overload resolution (overloads share one qualified name; a call resolves to a name, not a signature), no
11
+ type inference (`a.f()` is attributed to `f` only when exactly one `f` exists in the repository), no template
12
+ instantiation. Calls inside a lambda belong to the function that contains it.
13
+
14
+ Qualified names join with `.` (`ns.Class.method`), as Python's do, so every consumer that splits on the last `.` to
15
+ get the short name works on C++ unchanged.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import re
20
+ from pathlib import Path
21
+
22
+ CPP_SUFFIXES = (".c", ".cc", ".cpp", ".cxx", ".c++", ".h", ".hh", ".hpp", ".hxx", ".h++", ".inl", ".ipp", ".tpp")
23
+ _SKIP_PARTS = re.compile(r"(^|/)(third_party|thirdparty|vendor|external|extern|deps|node_modules|build|cmake-build[^/]*|\.git)/")
24
+
25
+ _CONTROL = {"if", "for", "while", "switch", "catch", "return", "sizeof", "alignof", "alignas", "decltype", "typeid",
26
+ "noexcept", "static_assert", "defined", "throw", "else", "do", "new", "delete", "case", "co_return",
27
+ "co_await", "co_yield", "requires", "__attribute__", "static_cast", "dynamic_cast", "const_cast",
28
+ "reinterpret_cast", "and", "or", "not", "using", "typedef", "template", "operator", "asm", "__asm__"}
29
+ # Test frameworks declare a test as a macro that looks like a function; it is a test case, not a Symbol.
30
+ _TEST_MACROS = {"TEST", "TEST_F", "TEST_P", "TYPED_TEST", "TYPED_TEST_P", "TEST_CASE", "TEST_CASE_METHOD",
31
+ "SCENARIO", "BOOST_AUTO_TEST_CASE", "BOOST_FIXTURE_TEST_CASE", "BOOST_AUTO_TEST_SUITE", "TEST_SUITE",
32
+ "TEMPLATE_TEST_CASE", "INSTANTIATE_TEST_SUITE_P", "FIXTURE_TEST_CASE", "BOOST_AUTO_TEST_CASE_TEMPLATE"}
33
+
34
+ _SCOPE_KW = re.compile(r"\b(class|struct|union|enum(?:\s+(?:class|struct))?)\s+(?:\[\[[^\]]*\]\]\s*)*(?:[A-Z_][A-Z0-9_]*\s+)*([A-Za-z_]\w*)(?:\s+final)?\s*(?:[:{]|$)")
35
+ _NAMESPACE = re.compile(r"\bnamespace\s+([A-Za-z_][\w:]*)?\s*$")
36
+ _IDENT = re.compile(r"[A-Za-z_~]\w*")
37
+ _CALL = re.compile(r"(?<![\w$])(~?[A-Za-z_]\w*)\s*(?:<[^<>;(){}]*>)?\s*\(")
38
+ _TEST_CASE = re.compile(r"^[ \t]*(TEST|TEST_F|TEST_P|TYPED_TEST|TYPED_TEST_P|BOOST_AUTO_TEST_CASE|BOOST_FIXTURE_TEST_CASE)"
39
+ r"\s*\(\s*([A-Za-z_]\w*)\s*(?:,\s*([A-Za-z_]\w*))?", re.M)
40
+ _CATCH_CASE = re.compile(r"^[ \t]*(?:TEST_CASE|SCENARIO|TEMPLATE_TEST_CASE)\s*\(\s*\"([^\"\n]+)\"", re.M)
41
+
42
+
43
+ def is_cpp_path(rel: str) -> bool:
44
+ return rel.lower().endswith(CPP_SUFFIXES) and not _SKIP_PARTS.search(rel)
45
+
46
+
47
+ def mask(src: str) -> str:
48
+ """The source with comments, string/char literals (contents) and preprocessor lines blanked, same length and
49
+ same newlines, so offsets and line numbers stay true."""
50
+ out = list(src)
51
+ n, i = len(src), 0
52
+
53
+ def blank(a: int, b: int) -> None:
54
+ for k in range(a, b):
55
+ if out[k] != "\n":
56
+ out[k] = " "
57
+
58
+ line_start = True
59
+ while i < n:
60
+ c = src[i]
61
+ if c == "\n":
62
+ line_start = True
63
+ i += 1
64
+ continue
65
+ if c in " \t\r":
66
+ i += 1
67
+ continue
68
+ if c == "#" and line_start: # preprocessor directive, with `\` continuations
69
+ j = i
70
+ while j < n:
71
+ if src[j] == "\n" and not src[j - 1:j] == "\\" and src[max(0, j - 2):j] != "\\\r":
72
+ break
73
+ j += 1
74
+ blank(i, j)
75
+ i = j
76
+ continue
77
+ line_start = False
78
+ if src.startswith("//", i):
79
+ j = src.find("\n", i)
80
+ j = n if j == -1 else j
81
+ blank(i, j)
82
+ i = j
83
+ elif src.startswith("/*", i):
84
+ j = src.find("*/", i + 2)
85
+ j = n if j == -1 else j + 2
86
+ blank(i, j)
87
+ i = j
88
+ elif c == "R" and src.startswith('R"', i) and (i == 0 or not (src[i - 1].isalnum() or src[i - 1] == "_")):
89
+ m = re.match(r'R"([^()\\ ]{0,16})\(', src[i:i + 24])
90
+ if m:
91
+ end = src.find(")" + m.group(1) + '"', i)
92
+ j = n if end == -1 else end + len(m.group(1)) + 2
93
+ blank(i + 1, j)
94
+ i = j
95
+ else:
96
+ i += 1
97
+ elif c in "\"'":
98
+ j = i + 1
99
+ while j < n and src[j] != c and src[j] != "\n":
100
+ j += 2 if src[j] == "\\" else 1
101
+ blank(i + 1, min(j, n))
102
+ i = j + 1
103
+ else:
104
+ i += 1
105
+ return "".join(out)
106
+
107
+
108
+ def _match_brace(text: str, open_pos: int) -> int:
109
+ depth = 0
110
+ for i in range(open_pos, len(text)):
111
+ c = text[i]
112
+ if c == "{":
113
+ depth += 1
114
+ elif c == "}":
115
+ depth -= 1
116
+ if depth == 0:
117
+ return i + 1
118
+ return len(text)
119
+
120
+
121
+ def _strip_template(header: str) -> str:
122
+ """Drop leading `template <...>` clauses (nesting-aware) so the declaration itself is what is left."""
123
+ h = header.lstrip()
124
+ while h.startswith("template"):
125
+ m = re.match(r"template\s*<", h)
126
+ if not m:
127
+ break
128
+ depth, i = 1, m.end()
129
+ while i < len(h) and depth:
130
+ depth += {"<": 1, ">": -1}.get(h[i], 0)
131
+ i += 1
132
+ h = h[i:].lstrip()
133
+ return h
134
+
135
+
136
+ def _function_name(header: str) -> str | None:
137
+ """The (possibly `A::b`-qualified) name of the function a header before `{` defines, else None."""
138
+ h = _strip_template(header)
139
+ h = re.sub(r"\[\[[^\]]*\]\]", " ", h)
140
+ depth, open_at = 0, -1
141
+ for i, c in enumerate(h): # the first top-level `(` whose preceding token is a name
142
+ if c == "(" and depth == 0:
143
+ before = h[:i].rstrip()
144
+ m = re.search(r"(operator\s*(?:\(\s*\)|\[\s*\]|[^\w\s(]+|\s+[\w:<>*&\s]+?)|~?[A-Za-z_]\w*)$", before)
145
+ if m and m.group(1) not in _CONTROL and not (m.group(1).startswith("operator") and False):
146
+ open_at = i
147
+ name_end = len(before)
148
+ name_start = m.start(1)
149
+ # fold a leading `A::B::` / `A<T>::` qualifier into the name
150
+ q = re.search(r"((?:~?[A-Za-z_]\w*(?:\s*<[^<>]*>)?\s*::\s*)+)$", before[:name_start])
151
+ if q:
152
+ name_start = q.start(1)
153
+ name = re.sub(r"\s+", "", re.sub(r"<[^<>]*>", "", before[name_start:name_end])) \
154
+ if not before[name_start:].startswith("operator") else re.sub(r"\s+", " ", before[name_start:]).strip()
155
+ return name
156
+ return None
157
+ if c in "<":
158
+ depth += 0
159
+ return None
160
+
161
+
162
+ def _close_paren(text: str, open_at: int) -> int:
163
+ depth = 0
164
+ for i in range(open_at, len(text)):
165
+ if text[i] == "(":
166
+ depth += 1
167
+ elif text[i] == ")":
168
+ depth -= 1
169
+ if depth == 0:
170
+ return i
171
+ return -1
172
+
173
+
174
+ def _is_definition_header(header: str) -> str | None:
175
+ """The function name when `header` (the text since the last `;`, `{` or `}`) is a function definition head."""
176
+ h = _strip_template(header).strip()
177
+ if not h or h.startswith(("namespace", "extern \"", "do", "else", "try", "typedef", "using")) and "(" not in h:
178
+ return None
179
+ if re.search(r"(^|[^\w])=\s*[^=]*$", h.split("(")[0]) and "(" not in h.split("=")[0]:
180
+ return None # `x = {` / `auto f = [](...) {`
181
+ m = re.search(r"\(", h)
182
+ if not m:
183
+ return None
184
+ name = _function_name(h)
185
+ if not name or name in _TEST_MACROS:
186
+ return None
187
+ end = _close_paren(h, h.index("(", len(h[: h.find(name.split("::")[-1])]) if False else m.start()))
188
+ if end == -1:
189
+ return None
190
+ # what follows the parameter list may only be qualifiers, a trailing return type or a constructor init list
191
+ tail = h[end + 1:].strip()
192
+ if tail and not re.match(r"^(?:(?:const|volatile|noexcept(?:\s*\([^)]*\))?|override|final|&&?|mutable|constexpr|"
193
+ r"throw\s*\([^)]*\)|__attribute__\s*\(\(.*?\)\)|\[\[[^\]]*\]\])\s*)*"
194
+ r"(?:->[^;{}]*|:[^;{}:][^;{}]*|:)?$", tail, re.S):
195
+ return None
196
+ return name
197
+
198
+
199
+ def _is_ctor_init_brace(header: str) -> bool:
200
+ """`Foo::Foo(int x) : a(x), b` followed by `{`: the brace opens `b{...}`, not the body."""
201
+ h = _strip_template(header)
202
+ m = re.search(r"\)\s*(?:noexcept\s*)?(?:const\s*)?:(?!:)", h)
203
+ return bool(m and re.search(r"[\w>]\s*$", h) and not re.search(r"\)\s*(?:const\s*)?(?:noexcept\s*)?$", h))
204
+
205
+
206
+ def extract_source(src: str) -> tuple[list[dict], list[tuple[str, str, str | None, str | None]]]:
207
+ """(symbols, calls). symbols: [{qualified_name, kind, line_start, line_end}]; calls:
208
+ [(caller_qualified_name, callee_short_name, receiver_or_None, qualifier_or_None)]."""
209
+ text = mask(src)
210
+ symbols: list[dict] = []
211
+ calls: list[tuple[str, str, str | None, str | None]] = []
212
+ line_of = _line_index(text)
213
+
214
+ def walk(start: int, end: int, scope: list[str], in_class: bool) -> None:
215
+ i, header_start = start, start
216
+ while i < end:
217
+ c = text[i]
218
+ if c == ";":
219
+ header_start = i + 1
220
+ elif c == "}":
221
+ header_start = i + 1
222
+ elif c == "{":
223
+ header = text[header_start:i]
224
+ close = _match_brace(text, i)
225
+ if _is_ctor_init_brace(header):
226
+ i = close
227
+ continue
228
+ stripped = _strip_template(header).strip()
229
+ ns = _NAMESPACE.search(stripped)
230
+ if ns is not None and "(" not in stripped:
231
+ parts = [p for p in (ns.group(1) or "").split("::") if p]
232
+ walk(i + 1, close - 1, scope + parts, False)
233
+ elif re.match(r"^extern\s*\"[^\"]*\"\s*$|^extern\s*$", re.sub(r"\"[^\"]*\"", '""', stripped) or "x"):
234
+ walk(i + 1, close - 1, scope, in_class)
235
+ else:
236
+ fname = _is_definition_header(header)
237
+ kw = _SCOPE_KW.search(stripped) if fname is None else None
238
+ if fname is not None:
239
+ qn = ".".join(scope + [p for p in fname.split("::") if p]) if not fname.startswith("operator") \
240
+ else ".".join(scope + [fname])
241
+ # a method's own class qualifies it; a nested-name definition keeps the qualifier it was given
242
+ a = _name_pos(text, header_start, i, fname)
243
+ symbols.append({"qualified_name": qn, "kind": "method" if (in_class or "::" in fname) else "function",
244
+ "line_start": line_of(a), "line_end": line_of(close - 1)})
245
+ for call in _calls_in(text[i + 1:close - 1]):
246
+ calls.append((qn, *call))
247
+ elif kw is not None and stripped.split()[0] in ("class", "struct", "union", "enum", "typedef") \
248
+ or kw is not None and re.match(r"^(class|struct|union|enum)\b", stripped):
249
+ kind = kw.group(1).split()[0]
250
+ name = kw.group(2)
251
+ symbols.append({"qualified_name": ".".join(scope + [name]), "kind": "class" if kind != "enum" else "enum",
252
+ "line_start": line_of(header_start + len(header) - len(header.lstrip())),
253
+ "line_end": line_of(close - 1)})
254
+ if kind != "enum":
255
+ walk(i + 1, close - 1, scope + [name], True)
256
+ # anything else (initialiser, lambda at namespace scope, a block): not a Symbol
257
+ i = close
258
+ header_start = i
259
+ continue
260
+ i += 1
261
+
262
+ walk(0, len(text), [], False)
263
+ return symbols, calls
264
+
265
+
266
+ def _name_pos(text: str, a: int, b: int, name: str) -> int:
267
+ j = text.find(name.split("::")[0].lstrip("~"), a, b)
268
+ return a + (len(text[a:b]) - len(text[a:b].lstrip())) if j == -1 else j
269
+
270
+
271
+ def _line_index(text: str):
272
+ import bisect
273
+ starts = [0] + [m.end() for m in re.finditer(r"\n", text)]
274
+ return lambda pos: bisect.bisect_right(starts, max(pos, 0))
275
+
276
+
277
+ def _calls_in(body: str) -> list[tuple[str, str | None, str | None]]:
278
+ """(callee short name, receiver, qualifier) for each call in a function body."""
279
+ out = []
280
+ for m in _CALL.finditer(body):
281
+ name = m.group(1)
282
+ if name in _CONTROL:
283
+ continue
284
+ before = body[:m.start()].rstrip()
285
+ receiver = qualifier = None
286
+ if before.endswith("::"):
287
+ q = re.search(r"((?:[A-Za-z_]\w*(?:\s*<[^<>]*>)?\s*::\s*)*[A-Za-z_]\w*)\s*::$", before)
288
+ if q:
289
+ qualifier = re.sub(r"\s+|<[^<>]*>", "", q.group(1))
290
+ elif before.endswith((".", "->")):
291
+ r = re.search(r"([A-Za-z_]\w*|\)|\])\s*(?:\.|->)$", before)
292
+ receiver = r.group(1) if r and r.group(1) not in (")", "]") else "<expr>"
293
+ elif re.search(r"\b(?:new|class|struct|enum|typename)\s*$", before):
294
+ pass
295
+ out.append((name, receiver, qualifier))
296
+ return out
297
+
298
+
299
+ def extract_file(path: Path) -> tuple[list[dict], list[tuple[str, str, str | None, str | None]]]:
300
+ try:
301
+ return extract_source(path.read_text(errors="replace"))
302
+ except OSError:
303
+ return [], []
304
+
305
+
306
+ def test_cases(src: str) -> list[tuple[str, int]]:
307
+ """[(test name, 1-based line)] for GoogleTest, Boost.Test and Catch2 cases."""
308
+ out = []
309
+ for m in _TEST_CASE.finditer(src):
310
+ name = f"{m.group(2)}.{m.group(3)}" if m.group(3) else m.group(2)
311
+ out.append((name, src.count("\n", 0, m.start()) + 1))
312
+ for m in _CATCH_CASE.finditer(src):
313
+ out.append((m.group(1), src.count("\n", 0, m.start()) + 1))
314
+ return sorted(out, key=lambda t: t[1])
315
+
316
+
317
+ def resolve_call(caller_qn: str, callee: str, receiver: str | None, qualifier: str | None,
318
+ by_short: dict[str, list[str]]) -> tuple[str | None, float, str]:
319
+ """(target qualified name, confidence, source tag) among the repository's qualified names with this short name
320
+ (`by_short[short] = [qualified names]`), or (None, 0, "") when it is ambiguous or unknown. Never a guess between
321
+ two equally good candidates."""
322
+ cands = by_short.get(callee, [])
323
+ if not cands:
324
+ return None, 0.0, ""
325
+ if qualifier:
326
+ q = qualifier.replace("::", ".")
327
+ hit = sorted({c for c in cands if c == f"{q}.{callee}" or c.endswith(f".{q}.{callee}")})
328
+ return (hit[0], 0.8, "cpp-qualified") if len(hit) == 1 else (None, 0.0, "")
329
+ if receiver is None or receiver == "this":
330
+ cls = caller_qn.rsplit(".", 1)[0] if "." in caller_qn else ""
331
+ while cls: # a bare call from a method prefers the same class, then the enclosing namespaces
332
+ hit = sorted({c for c in cands if c == f"{cls}.{callee}"})
333
+ if len(hit) == 1:
334
+ return hit[0], 0.8, "cpp-same-scope"
335
+ cls = cls.rsplit(".", 1)[0] if "." in cls else ""
336
+ if len(set(cands)) == 1:
337
+ return cands[0], (0.5 if receiver else 0.6), "cpp-unique-name"
338
+ return None, 0.0, ""
@@ -25,6 +25,28 @@ from mcp.server.fastmcp import FastMCP # noqa: E402
25
25
  from mcp.types import ToolAnnotations # noqa: E402
26
26
 
27
27
  from devkb.process_api import ProcessAPI, project_for # noqa: E402
28
+ from devkb.service import GraphNotBuilt # noqa: E402
29
+
30
+
31
+ class _LazyAPI:
32
+ """The process API, loaded on first use. A plugin starts the server before any graph exists (its session-start
33
+ hook builds one in the background); until then every tool says how to get one instead of the server failing."""
34
+
35
+ def __init__(self, project: str, devkb_dir: Path | None) -> None:
36
+ self._args, self._api = (project, devkb_dir), None
37
+
38
+ def get(self) -> ProcessAPI:
39
+ if self._api is None:
40
+ self._api = ProcessAPI(self._args[0], devkb_dir=self._args[1])
41
+ return self._api
42
+
43
+ def call(self, name: str, **kw) -> dict:
44
+ try:
45
+ return self.get().call(name, **kw)
46
+ except GraphNotBuilt as e:
47
+ return {"error": "no graph yet", "detail": str(e),
48
+ "next": "the graph is being built in the background on first use; ask again in a minute, or run "
49
+ "`devkb build --project .` and wait for it"}
28
50
 
29
51
  READ_ONLY = ToolAnnotations(readOnlyHint=True, idempotentHint=True, destructiveHint=False, openWorldHint=False)
30
52
  CORE = ["sdlc_context", "trace", "find_docs", "callers", "tests_for", "tests_to_run", "impact", "owner", "review_pack",
@@ -108,7 +130,10 @@ def build(api: ProcessAPI, toolset: str = "all") -> FastMCP:
108
130
  def pack(kind: str, subject: str, path: str = "", role: str = "") -> str:
109
131
  """Whole answer in one call, with proof lines and coverage. kind: file (subject=path), refactor or change (a function), error (message), pr, ticket."""
110
132
  from devkb.packs import Packer # noqa: PLC0415
111
- p = Packer(api)
133
+ try:
134
+ p = Packer(api.get() if isinstance(api, _LazyAPI) else api)
135
+ except GraphNotBuilt:
136
+ return "No devkb graph yet: it is being built in the background; ask again in a minute."
112
137
  run = {"file": lambda: p.file(subject), "refactor": lambda: p.refactor(subject, role, path),
113
138
  "change": lambda: p.change(subject, path), "error": lambda: p.error(subject),
114
139
  "pr": lambda: p.pr(subject), "ticket": lambda: p.ticket(subject)}.get(kind)
@@ -207,7 +232,7 @@ def main() -> int:
207
232
  ns.project = project_for(Path.cwd())
208
233
  if not ns.project:
209
234
  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)
235
+ api = _LazyAPI(ns.project, Path(ns.devkb_dir) if ns.devkb_dir else None)
211
236
  build(api, ns.toolset).run(transport="stdio")
212
237
  return 0
213
238
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: devkb
3
- Version: 0.2.0
3
+ Version: 0.2.1
4
4
  Summary: A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server
5
5
  Author: Hung T. Le
6
6
  License-Expression: Apache-2.0
@@ -129,6 +129,12 @@ devkb pack --project . file path/to/file.py # before editing a file
129
129
 
130
130
  **Claude Code**: nothing more to do. `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the
131
131
  instructions. Start `claude` in the repository, approve the `devkb` server when asked, and check it with `/mcp`.
132
+ Or skip `pip` and `devkb init` and install the plugin, which brings the server, its instructions and a hook that builds
133
+ the graph in the background (needs [uv](https://docs.astral.sh/uv/)):
134
+
135
+ ```
136
+ /plugin install devkb --marketplace namiq-ai/devkb
137
+ ```
132
138
 
133
139
  **Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:
134
140
 
@@ -9,6 +9,7 @@ devkb/build_symbols.py
9
9
  devkb/call_recall.py
10
10
  devkb/cli.py
11
11
  devkb/coverage.py
12
+ devkb/cpp_symbols.py
12
13
  devkb/edge_truth.py
13
14
  devkb/github.py
14
15
  devkb/gitutil.py
@@ -63,6 +64,7 @@ devkb/extractors/tickets_git.py
63
64
  devkb/extractors/warnings.py
64
65
  devkb/extractors/work_units.py
65
66
  tests/test_bench_pipeline_detail.py
67
+ tests/test_claude_plugin.py
66
68
  tests/test_devkb_ablation_process_odsf316.py
67
69
  tests/test_devkb_audit_efficiency_odsf314.py
68
70
  tests/test_devkb_authoring_odsf311.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "devkb"
7
- version = "0.2.0"
7
+ version = "0.2.1"
8
8
  description = "A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -0,0 +1,30 @@
1
+ """The Claude Code plugin in plugins/devkb: its skills are copies of skills/, its server uses the default toolset, and
2
+ the package version it installs exists."""
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from pathlib import Path
8
+
9
+ ROOT = Path(__file__).resolve().parents[1]
10
+ PLUGIN = ROOT / "plugins" / "devkb"
11
+
12
+
13
+ def test_plugin_skills_are_identical_to_the_originals():
14
+ for skill in (PLUGIN / "skills").glob("*/SKILL.md"):
15
+ assert skill.read_text() == (ROOT / "skills" / skill.parent.name / "SKILL.md").read_text(), skill.parent.name
16
+
17
+
18
+ def test_plugin_server_uses_lean_pack_and_a_released_version():
19
+ args = json.loads((PLUGIN / ".mcp.json").read_text())["mcpServers"]["devkb"]["args"]
20
+ assert args[-1] == "lean-pack" and "${CLAUDE_PROJECT_DIR}" in args
21
+ floor = re.search(r">=([0-9.]+)", args[1]).group(1)
22
+ version = re.search(r'^version = "([0-9.]+)"', (ROOT / "pyproject.toml").read_text(), re.M).group(1)
23
+ assert tuple(map(int, floor.split("."))) <= tuple(map(int, version.split(".")))
24
+ assert json.loads((PLUGIN / ".claude-plugin" / "plugin.json").read_text())["version"] == version
25
+
26
+
27
+ def test_marketplace_points_at_the_plugin():
28
+ m = json.loads((ROOT / ".claude-plugin" / "marketplace.json").read_text())
29
+ entry = next(p for p in m["plugins"] if p["name"] == "devkb")
30
+ assert (ROOT / entry["source"]).resolve() == PLUGIN.resolve()
@@ -83,3 +83,22 @@ def test_pack_is_a_tool_in_dev_and_lean_pack_and_lean_stays_as_measured():
83
83
  assert "pack" in module.TOOLSETS["dev"] and "pack" in module.TOOLSETS["lean-pack"]
84
84
  assert module.TOOLSETS["lean"] == ["rca_trace", "impact", "callers", "tests_for", "tests_to_run", "review_pack", "config"]
85
85
  assert module.TOOLSETS["lean-pack"] == module.TOOLSETS["lean"] + ["pack"]
86
+
87
+
88
+ def test_the_server_starts_without_a_graph_and_says_how_to_get_one(tmp_path):
89
+ pytest.importorskip("mcp.server.fastmcp")
90
+ import asyncio
91
+ import importlib.util
92
+ import subprocess as sp
93
+
94
+ sp.run(["git", "init", "-q", str(tmp_path)], check=True)
95
+ (tmp_path / "a.py").write_text("def f():\n return 1\n")
96
+ spec = importlib.util.spec_from_file_location("devkb_mcp_server", _REPO_ROOT / "devkb" / "mcp_server.py")
97
+ module = importlib.util.module_from_spec(spec)
98
+ spec.loader.exec_module(module)
99
+ server = module.build(module._LazyAPI(str(tmp_path), None), "lean-pack")
100
+ out = asyncio.run(server.call_tool("callers", {"symbol": "f"}))
101
+ text = (out[0] if isinstance(out, tuple) else out)[0].text
102
+ assert "no graph yet" in text
103
+ out = asyncio.run(server.call_tool("pack", {"kind": "refactor", "subject": "f"}))
104
+ assert "No devkb graph yet" in (out[0] if isinstance(out, tuple) else out)[0].text
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes