devkb 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- devkb/__init__.py +11 -0
- devkb/audit.py +173 -0
- devkb/bench/add_packs.py +52 -0
- devkb/bench/cli_tasks.py +105 -0
- devkb/bench/confirm_tasks.py +149 -0
- devkb/bench/module_truth.py +249 -0
- devkb/bench/oco_tasks.py +216 -0
- devkb/bench/pipeline.py +313 -0
- devkb/bench/process_tasks.py +135 -0
- devkb/bench/report.py +74 -0
- devkb/bench/run.py +174 -0
- devkb/bench/truth_check.py +148 -0
- devkb/bench/workflow_report.py +64 -0
- devkb/bench/workflow_run.py +206 -0
- devkb/bench/workflow_tasks.py +227 -0
- devkb/build.py +258 -0
- devkb/build_symbols.py +1394 -0
- devkb/call_recall.py +159 -0
- devkb/cli.py +53 -0
- devkb/coverage.py +155 -0
- devkb/edge_truth.py +272 -0
- devkb/extractors/backlog.py +113 -0
- devkb/extractors/component_subsystem.py +116 -0
- devkb/extractors/configuration.py +267 -0
- devkb/extractors/files_tests.py +220 -0
- devkb/extractors/flows.py +117 -0
- devkb/extractors/lifecycle.py +258 -0
- devkb/extractors/members.py +160 -0
- devkb/extractors/pull_requests.py +271 -0
- devkb/extractors/releases.py +49 -0
- devkb/extractors/source_baseline.py +66 -0
- devkb/extractors/spec_docs.py +220 -0
- devkb/extractors/symbol_tests.py +131 -0
- devkb/extractors/test_inventory.py +38 -0
- devkb/extractors/ticket_similarity.py +193 -0
- devkb/extractors/tickets_git.py +151 -0
- devkb/extractors/warnings.py +230 -0
- devkb/extractors/work_units.py +90 -0
- devkb/github.py +515 -0
- devkb/gitutil.py +16 -0
- devkb/index.py +51 -0
- devkb/init.py +178 -0
- devkb/mcp_server.py +216 -0
- devkb/model.py +221 -0
- devkb/module_file_bridge.py +57 -0
- devkb/ontology.md +178 -0
- devkb/packs.py +462 -0
- devkb/process_api.py +1601 -0
- devkb/project_context.py +191 -0
- devkb/query.py +251 -0
- devkb/service.py +324 -0
- devkb/startup.py +103 -0
- devkb/test_discovery.py +76 -0
- devkb/ts_symbols.py +291 -0
- devkb-0.2.0.dist-info/METADATA +162 -0
- devkb-0.2.0.dist-info/RECORD +61 -0
- devkb-0.2.0.dist-info/WHEEL +5 -0
- devkb-0.2.0.dist-info/entry_points.txt +2 -0
- devkb-0.2.0.dist-info/licenses/LICENSE +202 -0
- devkb-0.2.0.dist-info/licenses/NOTICE +11 -0
- devkb-0.2.0.dist-info/top_level.txt +1 -0
devkb/project_context.py
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
"""Where a project lives and how it is laid out, for every devkb tool.
|
|
2
|
+
|
|
3
|
+
devkb works on any git repository. A project is named either by a path (`--project .` or
|
|
4
|
+
`--project /path/to/repo`) or by a code listed in an optional registry (`DEVKB_REGISTRY`, a JSON file
|
|
5
|
+
`{"projects": [{"code": "APP", "repo": "/path"}]}`). Its layout comes from `devkb.json` at the repository
|
|
6
|
+
root, or from `pms.config.json` when a project already has one; both are optional, and every path has a
|
|
7
|
+
default, so a bare repository works with no configuration at all.
|
|
8
|
+
|
|
9
|
+
devkb.json (every key optional):
|
|
10
|
+
|
|
11
|
+
{"code": "APP", "ticket_prefix": "APP",
|
|
12
|
+
"paths": {"issues_dir": "issues", "spec_dirs": ["docs", "docs/adr"], "frontend_src": "web/src",
|
|
13
|
+
"frontend_kind": "nextjs", "sprint_dir": "sprints", "board_file": "BOARD.md"},
|
|
14
|
+
"role_profiles": {"BE": "roles/backend.md"}, "roles_dir": "roles", "graph": {"members": []},
|
|
15
|
+
"run_repo_scripts": false}
|
|
16
|
+
|
|
17
|
+
`run_repo_scripts` must be true before devkb imports or runs any script that lives in the analysed
|
|
18
|
+
repository (a readiness gate, a compliance monitor). It is off by default: analysing a repository must
|
|
19
|
+
never execute its code.
|
|
20
|
+
"""
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import json
|
|
24
|
+
import os
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
from typing import Any
|
|
28
|
+
|
|
29
|
+
CONFIG_FILES = ("devkb.json", "pms.config.json")
|
|
30
|
+
PROJECTS_JSON = Path(os.environ["DEVKB_REGISTRY"]) if os.environ.get("DEVKB_REGISTRY") else None
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def load_config(repo_root: Path) -> dict:
|
|
34
|
+
"""The project's devkb configuration: devkb.json, else pms.config.json, else {}."""
|
|
35
|
+
for name in CONFIG_FILES:
|
|
36
|
+
cfg = _read_json(Path(repo_root) / name)
|
|
37
|
+
if isinstance(cfg, dict):
|
|
38
|
+
return cfg
|
|
39
|
+
return {}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def run_repo_scripts(repo_root: Path) -> bool:
|
|
43
|
+
return bool(load_config(repo_root).get("run_repo_scripts")) or os.environ.get("DEVKB_RUN_REPO_SCRIPTS") == "1"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True)
|
|
47
|
+
class ProjectContext:
|
|
48
|
+
code: str
|
|
49
|
+
repo_root: Path
|
|
50
|
+
ticket_prefix: str
|
|
51
|
+
issues_dir: Path
|
|
52
|
+
tests_dir: Path
|
|
53
|
+
sprint_dir: Path
|
|
54
|
+
devkb_dir: Path
|
|
55
|
+
board_file: Path
|
|
56
|
+
wp_map_file: Path
|
|
57
|
+
# Where the project's frontend is and which extractor reads it; defaulted so callers that only need
|
|
58
|
+
# tickets and paths can construct a context without it.
|
|
59
|
+
frontend_src: Path | None = None
|
|
60
|
+
frontend_kind: str = "nextjs"
|
|
61
|
+
# ODSF-102. Where THIS project keeps the documents that specify it, relative
|
|
62
|
+
# to its own root. `spec_docs.py` used to hardcode four globs, so a project
|
|
63
|
+
# keeping specs anywhere else was invisible to its own BA: ODSF's whole
|
|
64
|
+
# specification set lives under `backlogs/` and its graph carried 2 Spec
|
|
65
|
+
# nodes, while OCO -- whose layout happens to match those globs -- carried
|
|
66
|
+
# 187. Empty means "use the defaults", so a project that declares nothing is
|
|
67
|
+
# byte-identical to before: this is opt-in, not a re-shaping of every graph.
|
|
68
|
+
# Defaulted for the same reason frontend_src above is -- ProjectContext is
|
|
69
|
+
# constructed directly by tests and by callers with no opinion about specs.
|
|
70
|
+
spec_dirs: tuple[str, ...] = ()
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
# Exactly the roots spec_docs.py scanned before this was configurable, with
|
|
74
|
+
# their original recursion: a trailing `/**` means "and subdirectories", its
|
|
75
|
+
# absence means top level only. `design` was the only recursive one, and
|
|
76
|
+
# `docs/adr`'s siblings under `docs/` were deliberately excluded -- keeping the
|
|
77
|
+
# distinction is what makes "a project that declares nothing is unchanged" true
|
|
78
|
+
# rather than nearly true.
|
|
79
|
+
#
|
|
80
|
+
# ODSF-103 adds `docs` — top level only, NOT `docs/**`. The subdirectories under
|
|
81
|
+
# `docs/` are per-owner working areas (compliance evidence, process diagrams,
|
|
82
|
+
# requirement templates) and are not specifications of the system; `docs/adr/`
|
|
83
|
+
# is already covered by its own entry. A project's consolidated
|
|
84
|
+
# requirement/technical/test documents DO live at that top level, and were
|
|
85
|
+
# reachable only as `File` nodes, so a context bundle could not surface the
|
|
86
|
+
# document that answers the question it was asked. Widening the DEFAULT rather
|
|
87
|
+
# than leaving it to each project's declaration: `docs/` is a universal
|
|
88
|
+
# convention, and a project that disagrees can now say so (ODSF-102).
|
|
89
|
+
#
|
|
90
|
+
# ODSF-128 adds `docs/spec` — top level only, for the same reason `docs` is:
|
|
91
|
+
# it is where ADR-SDP-SPEC-001 puts generated-then-curated specifications, and
|
|
92
|
+
# `docs` above is deliberately non-recursive so it does not reach a
|
|
93
|
+
# subdirectory. Every project gets it in the default rather than each having to
|
|
94
|
+
# declare it, because the folder contract is the platform's, not one project's.
|
|
95
|
+
DEFAULT_SPEC_DIRS: tuple[str, ...] = ("docs/adr", "docs", "docs/spec", "design/**", ".onboarding")
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def safe_spec_dirs(declared: Any, default: tuple[str, ...] = DEFAULT_SPEC_DIRS) -> tuple[str, ...]:
|
|
99
|
+
"""Validate a project's declared spec roots.
|
|
100
|
+
|
|
101
|
+
This value comes out of a config file and is then used to walk the
|
|
102
|
+
filesystem, so an entry that escapes the project is refused rather than
|
|
103
|
+
resolved: `../../etc`, an absolute path, or a `~` are dropped. A
|
|
104
|
+
non-list, or a list with nothing usable left in it, falls back to the
|
|
105
|
+
default -- a malformed declaration must not silently produce an empty
|
|
106
|
+
corpus, which would look exactly like a project with no specifications.
|
|
107
|
+
"""
|
|
108
|
+
if not isinstance(declared, list):
|
|
109
|
+
return default
|
|
110
|
+
out: list[str] = []
|
|
111
|
+
for entry in declared:
|
|
112
|
+
if not isinstance(entry, str):
|
|
113
|
+
continue
|
|
114
|
+
raw = entry.strip()
|
|
115
|
+
# Tested BEFORE the trailing slash is trimmed: stripping first turned
|
|
116
|
+
# "/etc" into "etc", which is not a refusal but a silent reinterpretation
|
|
117
|
+
# as <repo>/etc -- a different directory than the one declared, quietly
|
|
118
|
+
# substituted. Refusing is the only honest answer to a root this code
|
|
119
|
+
# cannot honour.
|
|
120
|
+
if not raw or raw.startswith(("/", "~")) or ".." in Path(raw).parts:
|
|
121
|
+
continue
|
|
122
|
+
rel = raw.strip("/")
|
|
123
|
+
if rel:
|
|
124
|
+
out.append(rel)
|
|
125
|
+
return tuple(dict.fromkeys(out)) or default
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def _read_json(path: Path, default: Any = None) -> Any:
|
|
129
|
+
try:
|
|
130
|
+
return json.loads(path.read_text())
|
|
131
|
+
except (OSError, ValueError):
|
|
132
|
+
return default
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def external_context(code: str, repo_root: Path, devkb_dir: Path) -> ProjectContext:
|
|
136
|
+
"""A context for a repository outside the factory registry: a public project in a benchmark (ODSF-315). It is
|
|
137
|
+
never a fallback of `resolve()`, which keeps refusing an unregistered code; a caller asks for it explicitly, and
|
|
138
|
+
such a repository has no tickets, board or role profiles, so those paths simply do not exist."""
|
|
139
|
+
root = Path(repo_root).resolve()
|
|
140
|
+
return ProjectContext(code=code, repo_root=root, ticket_prefix=f"{code}-EXT", issues_dir=root / "issues",
|
|
141
|
+
tests_dir=root / "tests", sprint_dir=root / "sprints", devkb_dir=Path(devkb_dir),
|
|
142
|
+
board_file=root / "PROJECT_BOARD.md", wp_map_file=root / "wp-map.json")
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def registry() -> list[dict]:
|
|
146
|
+
if PROJECTS_JSON is None:
|
|
147
|
+
return []
|
|
148
|
+
return (_read_json(PROJECTS_JSON, {}) or {}).get("projects", [])
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _from_root(code: str | None, repo_root: Path) -> ProjectContext:
|
|
152
|
+
cfg = load_config(repo_root)
|
|
153
|
+
project = cfg.get("project") if isinstance(cfg.get("project"), dict) else {}
|
|
154
|
+
code = code or cfg.get("code") or project.get("code") or repo_root.name.upper()
|
|
155
|
+
ticket_prefix = cfg.get("ticket_prefix") or project.get("code") or code
|
|
156
|
+
paths = cfg.get("paths", {}) if isinstance(cfg.get("paths"), dict) else {}
|
|
157
|
+
issues_rel = paths.get("issues_dir") or "issues"
|
|
158
|
+
sprint_rel = paths.get("sprint_dir") or "historical/sprints"
|
|
159
|
+
board_rel = paths.get("board_file") or "sdp/data/PROJECT_BOARD.md"
|
|
160
|
+
wp_map_rel = paths.get("orchestrator_wp_map") or "sdp/data/orchestrator/wp-map.json"
|
|
161
|
+
return ProjectContext(
|
|
162
|
+
code=code,
|
|
163
|
+
repo_root=repo_root,
|
|
164
|
+
ticket_prefix=ticket_prefix,
|
|
165
|
+
issues_dir=repo_root / issues_rel,
|
|
166
|
+
tests_dir=repo_root / "tests",
|
|
167
|
+
sprint_dir=repo_root / sprint_rel,
|
|
168
|
+
devkb_dir=Path(os.environ["DEVKB_DIR"]) if os.environ.get("DEVKB_DIR") else repo_root / ".devkb",
|
|
169
|
+
board_file=repo_root / board_rel,
|
|
170
|
+
wp_map_file=repo_root / wp_map_rel,
|
|
171
|
+
frontend_src=(repo_root / paths["frontend_src"]) if paths.get("frontend_src") else None,
|
|
172
|
+
frontend_kind=paths.get("frontend_kind") or "nextjs",
|
|
173
|
+
spec_dirs=safe_spec_dirs(paths.get("spec_dirs")),
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def resolve(code: str) -> ProjectContext:
|
|
178
|
+
"""`code` is a path to a repository, a code in the registry, or a code matching DEVKB_REPO's
|
|
179
|
+
configuration. Raises ValueError when none applies: devkb refuses to guess which repository is meant."""
|
|
180
|
+
as_path = Path(code).expanduser()
|
|
181
|
+
if as_path.is_dir() and (as_path / ".git").exists() or code in (".", "..") or "/" in code:
|
|
182
|
+
if not as_path.is_dir():
|
|
183
|
+
raise ValueError(f"{code!r} is not a directory")
|
|
184
|
+
return _from_root(None, as_path.resolve())
|
|
185
|
+
entry = next((p for p in registry() if p.get("code") == code), None)
|
|
186
|
+
if entry is not None:
|
|
187
|
+
return _from_root(code, Path(entry["repo"]).resolve())
|
|
188
|
+
if os.environ.get("DEVKB_REPO"):
|
|
189
|
+
return _from_root(code, Path(os.environ["DEVKB_REPO"]).resolve())
|
|
190
|
+
raise ValueError(f"{code!r} is neither a repository path nor a registered project "
|
|
191
|
+
"(pass --project PATH, set DEVKB_REPO, or list it in DEVKB_REGISTRY)")
|
devkb/query.py
ADDED
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""devkb query — a linked, evidence-backed context bundle for one node.
|
|
3
|
+
|
|
4
|
+
Usage: python3 devkb/query.py --project CODE --about ODSF-021
|
|
5
|
+
python3 devkb/query.py --project CODE --about M2 (milestone)
|
|
6
|
+
python3 devkb/query.py --project CODE --about A-01 (work package)
|
|
7
|
+
python3 devkb/query.py --project CODE stories implementing SPEC-ODSF-003
|
|
8
|
+
(also `epics`/`tickets`; a SPEC id or a spec path)
|
|
9
|
+
|
|
10
|
+
Returns JSON: the node itself plus every edge touching it (outgoing and
|
|
11
|
+
incoming), each with the linked node's identifying fields inlined -- a
|
|
12
|
+
context bundle an agent or human can act on directly, not a raw file dump
|
|
13
|
+
(requirement per ADR-SDP-DEVKB-001 / ODSF-021's acceptance criteria).
|
|
14
|
+
"""
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import argparse
|
|
18
|
+
import json
|
|
19
|
+
import re
|
|
20
|
+
import sys
|
|
21
|
+
from pathlib import Path
|
|
22
|
+
from typing import Any
|
|
23
|
+
|
|
24
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
|
25
|
+
|
|
26
|
+
from devkb.index import DevKBIndex, load
|
|
27
|
+
from devkb.model import NODE_TYPES
|
|
28
|
+
from devkb.module_file_bridge import file_to_module
|
|
29
|
+
from devkb.project_context import resolve, ProjectContext
|
|
30
|
+
|
|
31
|
+
_STALE_HINT = (
|
|
32
|
+
"no .devkb/ store found for this project -- run "
|
|
33
|
+
"`python3 devkb/build.py --project {code}` first"
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _find_node(idx: DevKBIndex, natural_key: str) -> dict[str, Any] | None:
|
|
38
|
+
"""Tries every node type for this natural key -- Phase 1 has no path-based
|
|
39
|
+
types yet (File is a later phase), so a plain "what type is this key"
|
|
40
|
+
guess isn't needed: Ticket/Commit ids/WorkPackage ids/Milestone ids don't
|
|
41
|
+
collide in practice, but check all four rather than assuming the caller
|
|
42
|
+
knows the type."""
|
|
43
|
+
for node_type in NODE_TYPES:
|
|
44
|
+
node = idx.node(node_type, natural_key)
|
|
45
|
+
if node is not None:
|
|
46
|
+
return node
|
|
47
|
+
return None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _linked_summary(node: dict[str, Any]) -> dict[str, Any]:
|
|
51
|
+
props = node.get("properties", {})
|
|
52
|
+
label = props.get("title") or props.get("subject") or node["natural_key"]
|
|
53
|
+
return {"uid": node["uid"], "type": node["type"], "natural_key": node["natural_key"], "label": label}
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
#: Verbs whose neighbour count is unbounded by construction, and the number of
|
|
57
|
+
#: them a bundle carries. `SIMILAR_TO` is threshold-free on purpose — the
|
|
58
|
+
#: extractor emits an edge for ANY shared file and stores the real score so
|
|
59
|
+
#: that filtering can happen HERE, at query time ("rank at the edge, don't gate
|
|
60
|
+
#: at the build"). That half was specified and never built, so a bundle carried
|
|
61
|
+
#: every neighbour: measured on OCO, a median ticket had 539 of them and the
|
|
62
|
+
#: worst had 1,404, which is not a context bundle, it is the backlog.
|
|
63
|
+
_RANKED_VERBS = {"SIMILAR_TO": 10}
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _rank_key(link: dict[str, Any]) -> float:
|
|
67
|
+
ev = link.get("evidence") or {}
|
|
68
|
+
# `weighted_score` knows the difference between sharing a Makefile and
|
|
69
|
+
# sharing one service; `overlap_score` is the pre-BL-11-fix fallback for a
|
|
70
|
+
# graph built before it existed.
|
|
71
|
+
for field in ("weighted_score", "overlap_score", "shared_file_count"):
|
|
72
|
+
value = ev.get(field)
|
|
73
|
+
if isinstance(value, (int, float)):
|
|
74
|
+
return float(value)
|
|
75
|
+
return 0.0
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _ranked(links: list[dict[str, Any]]) -> dict[str, Any]:
|
|
79
|
+
"""Cap the verbs that fan out, and SAY how many were left out.
|
|
80
|
+
|
|
81
|
+
Silently dropping links would be the same defect ODSF-058 removed from the
|
|
82
|
+
report — a document that abbreviates without admitting it. The count is
|
|
83
|
+
part of the answer, not an implementation detail.
|
|
84
|
+
"""
|
|
85
|
+
omitted: dict[str, int] = {}
|
|
86
|
+
winners: dict[str, list[dict[str, Any]]] = {}
|
|
87
|
+
for verb, cap in _RANKED_VERBS.items():
|
|
88
|
+
group = [link for link in links if link["verb"] == verb]
|
|
89
|
+
if len(group) <= cap:
|
|
90
|
+
continue # nothing dropped, so nothing reordered either
|
|
91
|
+
group.sort(key=_rank_key, reverse=True)
|
|
92
|
+
omitted[verb] = len(group) - cap
|
|
93
|
+
winners[verb] = group[:cap]
|
|
94
|
+
|
|
95
|
+
if not winners:
|
|
96
|
+
return {"links": links, "omitted": omitted}
|
|
97
|
+
|
|
98
|
+
# Survivors take the positions the verb already occupied, in rank order:
|
|
99
|
+
# the bundle's overall link order stays the graph's, and a top-N list is
|
|
100
|
+
# returned strongest-first, because for a truncated list the order IS part
|
|
101
|
+
# of the answer.
|
|
102
|
+
queues = {verb: iter(kept) for verb, kept in winners.items()}
|
|
103
|
+
out: list[dict[str, Any]] = []
|
|
104
|
+
for link in links:
|
|
105
|
+
verb = link["verb"]
|
|
106
|
+
if verb not in winners:
|
|
107
|
+
out.append(link)
|
|
108
|
+
continue
|
|
109
|
+
nxt = next(queues[verb], None)
|
|
110
|
+
if nxt is not None:
|
|
111
|
+
out.append(nxt)
|
|
112
|
+
return {"links": out, "omitted": omitted}
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def context_bundle(idx: DevKBIndex, natural_key: str, ctx: ProjectContext | None = None) -> dict[str, Any]:
|
|
116
|
+
node = _find_node(idx, natural_key)
|
|
117
|
+
if node is None:
|
|
118
|
+
return {"found": False, "natural_key": natural_key}
|
|
119
|
+
|
|
120
|
+
if node["type"] == "File" and ctx is not None:
|
|
121
|
+
# Phase 2 step 2 (module_file_bridge): richer discovery/graph.json
|
|
122
|
+
# context for a File node, joined at query time -- never persisted
|
|
123
|
+
# into .devkb/ itself, the two stores stay independent per the ADR.
|
|
124
|
+
discovery_graph_path = ctx.repo_root / ".onboarding" / "graph.json"
|
|
125
|
+
module_key = file_to_module(discovery_graph_path, ctx.repo_root).get(node["natural_key"])
|
|
126
|
+
if module_key:
|
|
127
|
+
node = {**node, "properties": {**node["properties"], "discovery_module": module_key}}
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
outgoing = _ranked(
|
|
131
|
+
[{"verb": e["verb"], "to": _linked_summary(idx.by_uid[e["to_uid"]]), "evidence": e["properties"]}
|
|
132
|
+
for e in idx.out_edges.get(node["uid"], [])
|
|
133
|
+
if e["to_uid"] in idx.by_uid])
|
|
134
|
+
incoming = _ranked(
|
|
135
|
+
[{"verb": e["verb"], "from": _linked_summary(idx.by_uid[e["from_uid"]]), "evidence": e["properties"]}
|
|
136
|
+
for e in idx.in_edges.get(node["uid"], [])
|
|
137
|
+
if e["from_uid"] in idx.by_uid])
|
|
138
|
+
bundle = {"found": True, "node": node,
|
|
139
|
+
"outgoing": outgoing["links"], "incoming": incoming["links"]}
|
|
140
|
+
omitted = {
|
|
141
|
+
verb: outgoing["omitted"].get(verb, 0) + incoming["omitted"].get(verb, 0)
|
|
142
|
+
for verb in set(outgoing["omitted"]) | set(incoming["omitted"])
|
|
143
|
+
}
|
|
144
|
+
if omitted:
|
|
145
|
+
# Named `omitted_by_verb` rather than a bare count: "673 hidden" tells
|
|
146
|
+
# a reader nothing, "673 SIMILAR_TO below the top 10 by weighted
|
|
147
|
+
# overlap" tells them whether they care.
|
|
148
|
+
bundle["omitted_by_verb"] = omitted
|
|
149
|
+
bundle["ranked_by"] = "weighted_score"
|
|
150
|
+
return bundle
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
#: ADR-SDP-DEVKB-002 §2: `Epic`/`Story` are query aliases for
|
|
154
|
+
#: `Ticket{ticket_type: EPIC|STORY}`; `tickets` is every Ticket. A Ticket with
|
|
155
|
+
#: no `ticket_type` (a graph built before BL-14) is a plain ticket, so it only
|
|
156
|
+
#: ever answers to `tickets`.
|
|
157
|
+
_TICKET_ALIASES: dict[str, str | None] = {"stories": "STORY", "epics": "EPIC", "tickets": None}
|
|
158
|
+
_QUESTION_RE = re.compile(r"^\s*(stories|epics|tickets)\s+implementing\s+(\S+)\s*$", re.IGNORECASE)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _resolve_spec(idx: DevKBIndex, ref: str) -> list[dict[str, Any]]:
|
|
162
|
+
"""Spec nodes `ref` names: its path (natural key) first, else its `spec_id`.
|
|
163
|
+
More than one means the id is ambiguous -- the build links none of them by
|
|
164
|
+
it (`extractors/lifecycle.py`), and `implementing` answers the same way."""
|
|
165
|
+
node = idx.node("Spec", ref)
|
|
166
|
+
if node is not None:
|
|
167
|
+
return [node]
|
|
168
|
+
return sorted(
|
|
169
|
+
(n for n in idx.by_type.get("Spec", []) if n.get("properties", {}).get("spec_id") == ref),
|
|
170
|
+
key=lambda n: n["natural_key"],
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def implementing(idx: DevKBIndex, kind: str, ref: str) -> dict[str, Any]:
|
|
175
|
+
"""Tickets with an `IMPLEMENTS` edge to the spec `ref` (a SPEC id or a
|
|
176
|
+
path), filtered by the Epic/Story alias. `found` is about the SPEC: a
|
|
177
|
+
known spec nothing implements yet is `found: true` with no results."""
|
|
178
|
+
kind = kind.lower()
|
|
179
|
+
wanted = _TICKET_ALIASES[kind]
|
|
180
|
+
specs = _resolve_spec(idx, ref)
|
|
181
|
+
if not specs:
|
|
182
|
+
return {"found": False, "question": f"{kind} implementing {ref}", "spec": ref}
|
|
183
|
+
if len(specs) > 1:
|
|
184
|
+
return {"found": False, "question": f"{kind} implementing {ref}", "spec": ref,
|
|
185
|
+
"ambiguous": [s["natural_key"] for s in specs]}
|
|
186
|
+
results: dict[str, dict[str, Any]] = {}
|
|
187
|
+
for spec in specs:
|
|
188
|
+
for e in idx.in_edges.get(spec["uid"], []):
|
|
189
|
+
if e["verb"] != "IMPLEMENTS":
|
|
190
|
+
continue
|
|
191
|
+
ticket = idx.by_uid.get(e["from_uid"])
|
|
192
|
+
if ticket is None or ticket["type"] != "Ticket":
|
|
193
|
+
continue
|
|
194
|
+
props = ticket.get("properties", {})
|
|
195
|
+
# ADR-DEVKB-007: an issue with sub-issues is an epic whatever its own type
|
|
196
|
+
if wanted is not None and props.get("ticket_type") != wanted and not (wanted == "EPIC" and props.get("has_sub_issues")):
|
|
197
|
+
continue
|
|
198
|
+
results[ticket["natural_key"]] = {
|
|
199
|
+
**_linked_summary(ticket),
|
|
200
|
+
"ticket_type": props.get("ticket_type"),
|
|
201
|
+
"status": props.get("status"),
|
|
202
|
+
"spec": spec["natural_key"],
|
|
203
|
+
"evidence_ref": e["properties"].get("evidence_ref"),
|
|
204
|
+
}
|
|
205
|
+
return {
|
|
206
|
+
"found": True, "question": f"{kind} implementing {ref}",
|
|
207
|
+
"specs": [_linked_summary(s) for s in specs],
|
|
208
|
+
"count": len(results),
|
|
209
|
+
"results": [results[k] for k in sorted(results)],
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def main() -> int:
|
|
214
|
+
ap = argparse.ArgumentParser(description="Query the devkb graph for one project")
|
|
215
|
+
ap.add_argument("--project", required=True, help="Project code, e.g. ODSF")
|
|
216
|
+
ap.add_argument("--about", help="A ticket id, WP id, or milestone id")
|
|
217
|
+
ap.add_argument(
|
|
218
|
+
"question", nargs="*",
|
|
219
|
+
help='a question instead of --about: "stories|epics|tickets implementing <SPEC-id|spec path>"',
|
|
220
|
+
)
|
|
221
|
+
args = ap.parse_args()
|
|
222
|
+
question = " ".join(args.question).strip()
|
|
223
|
+
if bool(args.about) == bool(question):
|
|
224
|
+
ap.error("give exactly one of --about KEY or a question "
|
|
225
|
+
'("stories implementing SPEC-ODSF-003")')
|
|
226
|
+
match = _QUESTION_RE.match(question) if question else None
|
|
227
|
+
if question and match is None:
|
|
228
|
+
ap.error(f"unrecognised question {question!r}; expected "
|
|
229
|
+
'"stories|epics|tickets implementing <SPEC-id|spec path>"')
|
|
230
|
+
|
|
231
|
+
try:
|
|
232
|
+
ctx = resolve(args.project)
|
|
233
|
+
except ValueError as exc:
|
|
234
|
+
print(f"Error: {exc}", file=sys.stderr)
|
|
235
|
+
return 1
|
|
236
|
+
|
|
237
|
+
if not (ctx.devkb_dir / "manifest.json").exists():
|
|
238
|
+
print(f"Error: {_STALE_HINT.format(code=args.project)}", file=sys.stderr)
|
|
239
|
+
return 1
|
|
240
|
+
|
|
241
|
+
idx = load(ctx.devkb_dir)
|
|
242
|
+
if match is not None:
|
|
243
|
+
bundle = implementing(idx, match.group(1), match.group(2))
|
|
244
|
+
else:
|
|
245
|
+
bundle = context_bundle(idx, args.about, ctx)
|
|
246
|
+
print(json.dumps(bundle, indent=2))
|
|
247
|
+
return 0 if bundle["found"] else 1
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
if __name__ == "__main__":
|
|
251
|
+
sys.exit(main())
|