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
@@ -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())