github-milestone-roadmap 0.1.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.
- github_milestone_roadmap/__init__.py +8 -0
- github_milestone_roadmap/build.py +169 -0
- github_milestone_roadmap/changes.py +377 -0
- github_milestone_roadmap/cli.py +142 -0
- github_milestone_roadmap/config.py +304 -0
- github_milestone_roadmap/static/app.js +577 -0
- github_milestone_roadmap/static/index.html +49 -0
- github_milestone_roadmap/static/styles.css +589 -0
- github_milestone_roadmap-0.1.0.dist-info/METADATA +134 -0
- github_milestone_roadmap-0.1.0.dist-info/RECORD +13 -0
- github_milestone_roadmap-0.1.0.dist-info/WHEEL +4 -0
- github_milestone_roadmap-0.1.0.dist-info/entry_points.txt +2 -0
- github_milestone_roadmap-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""Build a live roadmap website from GitHub release milestones."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
try:
|
|
6
|
+
__version__ = version("github-milestone-roadmap")
|
|
7
|
+
except PackageNotFoundError: # pragma: no cover - only when not installed
|
|
8
|
+
__version__ = "unknown"
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
"""Write the static roadmap site for a configuration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from html import escape
|
|
7
|
+
from importlib.resources import files
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from string import Template
|
|
10
|
+
|
|
11
|
+
from . import __version__
|
|
12
|
+
from .config import RoadmapConfig
|
|
13
|
+
|
|
14
|
+
STATIC_ASSETS = ("app.js", "styles.css")
|
|
15
|
+
|
|
16
|
+
GITHUB_ICON_PATH = (
|
|
17
|
+
"M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 "
|
|
18
|
+
"0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13"
|
|
19
|
+
"-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07"
|
|
20
|
+
"-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08"
|
|
21
|
+
"-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82A7.65 7.65 0 0 1 8 3.86c.68 0 1.36"
|
|
22
|
+
".09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27"
|
|
23
|
+
".82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93"
|
|
24
|
+
"-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def read_static_text(name: str) -> str:
|
|
29
|
+
"""Read a file shipped in the package's ``static`` folder.
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
name : str
|
|
34
|
+
File name inside ``static``.
|
|
35
|
+
|
|
36
|
+
Returns
|
|
37
|
+
-------
|
|
38
|
+
str
|
|
39
|
+
File contents.
|
|
40
|
+
"""
|
|
41
|
+
return (
|
|
42
|
+
files("github_milestone_roadmap")
|
|
43
|
+
.joinpath("static", name)
|
|
44
|
+
.read_text(encoding="utf-8")
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def render_source_link(source_url: str) -> str:
|
|
49
|
+
"""Render the GitHub link shown in the top-right corner.
|
|
50
|
+
|
|
51
|
+
Parameters
|
|
52
|
+
----------
|
|
53
|
+
source_url : str
|
|
54
|
+
Link target; empty means no link.
|
|
55
|
+
|
|
56
|
+
Returns
|
|
57
|
+
-------
|
|
58
|
+
str
|
|
59
|
+
HTML for the link, or an empty string.
|
|
60
|
+
"""
|
|
61
|
+
if not source_url:
|
|
62
|
+
return ""
|
|
63
|
+
return (
|
|
64
|
+
f' <a class="github-link" href="{escape(source_url)}" '
|
|
65
|
+
'rel="noreferrer">\n'
|
|
66
|
+
' <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">\n'
|
|
67
|
+
f' <path d="{GITHUB_ICON_PATH}" />\n'
|
|
68
|
+
" </svg>\n"
|
|
69
|
+
" <span>GitHub</span>\n"
|
|
70
|
+
" </a>"
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def render_index_html(config: RoadmapConfig) -> str:
|
|
75
|
+
"""Fill the ``index.html`` template from a configuration.
|
|
76
|
+
|
|
77
|
+
All configuration values are HTML-escaped.
|
|
78
|
+
|
|
79
|
+
Parameters
|
|
80
|
+
----------
|
|
81
|
+
config : RoadmapConfig
|
|
82
|
+
The roadmap configuration.
|
|
83
|
+
|
|
84
|
+
Returns
|
|
85
|
+
-------
|
|
86
|
+
str
|
|
87
|
+
The rendered page.
|
|
88
|
+
"""
|
|
89
|
+
repo_links = "\n".join(
|
|
90
|
+
f' <a href="#{escape(repo.name)}">{escape(repo.name)}</a>'
|
|
91
|
+
for repo in config.repos
|
|
92
|
+
)
|
|
93
|
+
subtitle_paragraph = (
|
|
94
|
+
f' <p class="subtitle">{escape(config.subtitle)}</p>'
|
|
95
|
+
if config.subtitle
|
|
96
|
+
else ""
|
|
97
|
+
)
|
|
98
|
+
template = Template(read_static_text("index.html"))
|
|
99
|
+
return template.substitute(
|
|
100
|
+
title=escape(config.title),
|
|
101
|
+
heading=escape(config.heading),
|
|
102
|
+
description=escape(config.description),
|
|
103
|
+
home_url=escape(config.home.url),
|
|
104
|
+
home_text=escape(config.home.text),
|
|
105
|
+
source_link=render_source_link(config.source_url),
|
|
106
|
+
subtitle_paragraph=subtitle_paragraph,
|
|
107
|
+
repo_links=repo_links,
|
|
108
|
+
version=escape(__version__),
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def build_runtime_config(config: RoadmapConfig) -> dict[str, object]:
|
|
113
|
+
"""Build the ``config.json`` content that ``app.js`` reads in the browser.
|
|
114
|
+
|
|
115
|
+
Parameters
|
|
116
|
+
----------
|
|
117
|
+
config : RoadmapConfig
|
|
118
|
+
The roadmap configuration.
|
|
119
|
+
|
|
120
|
+
Returns
|
|
121
|
+
-------
|
|
122
|
+
dict
|
|
123
|
+
JSON-serialisable runtime configuration.
|
|
124
|
+
"""
|
|
125
|
+
return {
|
|
126
|
+
"cache_key": config.cache_key,
|
|
127
|
+
"repos": [
|
|
128
|
+
{"owner": repo.owner, "name": repo.name, "description": repo.description}
|
|
129
|
+
for repo in config.repos
|
|
130
|
+
],
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def build_site(config: RoadmapConfig, output_dir: Path) -> list[Path]:
|
|
135
|
+
"""Write the roadmap site into a directory.
|
|
136
|
+
|
|
137
|
+
Existing files with the same names are overwritten; other files in
|
|
138
|
+
``output_dir`` are left untouched.
|
|
139
|
+
|
|
140
|
+
Parameters
|
|
141
|
+
----------
|
|
142
|
+
config : RoadmapConfig
|
|
143
|
+
The roadmap configuration.
|
|
144
|
+
output_dir : Path
|
|
145
|
+
Directory to write into; created if missing.
|
|
146
|
+
|
|
147
|
+
Returns
|
|
148
|
+
-------
|
|
149
|
+
list of Path
|
|
150
|
+
The files written.
|
|
151
|
+
"""
|
|
152
|
+
output_dir.mkdir(parents=True, exist_ok=True)
|
|
153
|
+
written: list[Path] = []
|
|
154
|
+
|
|
155
|
+
index_path = output_dir / "index.html"
|
|
156
|
+
index_path.write_text(render_index_html(config), encoding="utf-8")
|
|
157
|
+
written.append(index_path)
|
|
158
|
+
|
|
159
|
+
for name in STATIC_ASSETS:
|
|
160
|
+
path = output_dir / name
|
|
161
|
+
path.write_text(read_static_text(name), encoding="utf-8")
|
|
162
|
+
written.append(path)
|
|
163
|
+
|
|
164
|
+
config_path = output_dir / "config.json"
|
|
165
|
+
config_path.write_text(
|
|
166
|
+
json.dumps(build_runtime_config(config), indent=2) + "\n", encoding="utf-8"
|
|
167
|
+
)
|
|
168
|
+
written.append(config_path)
|
|
169
|
+
return written
|
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
"""List issues/PRs added to vX.Y.Z milestones in the last N hours.
|
|
2
|
+
|
|
3
|
+
Uses the GitHub GraphQL API: one query per repo fetches every SemVer
|
|
4
|
+
milestone (updated within the window) together with its issues, PRs, and
|
|
5
|
+
their timeline ``MilestonedEvent``s. Only events created within the window
|
|
6
|
+
are reported. The output is Markdown with nested lists, suitable for pasting
|
|
7
|
+
into Slack.
|
|
8
|
+
|
|
9
|
+
GraphQL requires authentication, so a GitHub token is needed.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
from datetime import UTC, datetime, timedelta
|
|
16
|
+
from typing import Any
|
|
17
|
+
|
|
18
|
+
import httpx
|
|
19
|
+
|
|
20
|
+
from .config import RepoConfig
|
|
21
|
+
|
|
22
|
+
VERSION_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")
|
|
23
|
+
GRAPHQL_URL = "https://api.github.com/graphql"
|
|
24
|
+
|
|
25
|
+
# Fetch all milestones (open + closed), and for each their issues and PRs
|
|
26
|
+
# with their timeline milestoned events. Pagination is capped at first
|
|
27
|
+
# pages here for simplicity; we page milestones outer-loop, and inner
|
|
28
|
+
# connections use `first: 50`.
|
|
29
|
+
QUERY = """
|
|
30
|
+
query($owner: String!, $repo: String!, $cursor: String) {
|
|
31
|
+
repository(owner: $owner, name: $repo) {
|
|
32
|
+
milestones(first: 10, after: $cursor, states: [OPEN, CLOSED],
|
|
33
|
+
orderBy: {field: UPDATED_AT, direction: DESC}) {
|
|
34
|
+
pageInfo { hasNextPage endCursor }
|
|
35
|
+
nodes {
|
|
36
|
+
number
|
|
37
|
+
title
|
|
38
|
+
updatedAt
|
|
39
|
+
url
|
|
40
|
+
issues(first: 50, states: [OPEN, CLOSED]) {
|
|
41
|
+
nodes {
|
|
42
|
+
number
|
|
43
|
+
title
|
|
44
|
+
url
|
|
45
|
+
updatedAt
|
|
46
|
+
timelineItems(first: 20, itemTypes: [MILESTONED_EVENT]) {
|
|
47
|
+
nodes {
|
|
48
|
+
__typename
|
|
49
|
+
... on MilestonedEvent {
|
|
50
|
+
createdAt
|
|
51
|
+
milestoneTitle
|
|
52
|
+
actor { login }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
pullRequests(first: 50, states: [OPEN, CLOSED, MERGED]) {
|
|
59
|
+
nodes {
|
|
60
|
+
number
|
|
61
|
+
title
|
|
62
|
+
url
|
|
63
|
+
updatedAt
|
|
64
|
+
timelineItems(first: 20, itemTypes: [MILESTONED_EVENT]) {
|
|
65
|
+
nodes {
|
|
66
|
+
__typename
|
|
67
|
+
... on MilestonedEvent {
|
|
68
|
+
createdAt
|
|
69
|
+
milestoneTitle
|
|
70
|
+
actor { login }
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
# {milestone_title: {"number": int, "items": {item_number: item}}}
|
|
83
|
+
MilestoneAdditions = dict[str, dict[str, Any]]
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def parse_iso(ts: str) -> datetime:
|
|
87
|
+
"""Parse a GitHub ISO-8601 timestamp.
|
|
88
|
+
|
|
89
|
+
Parameters
|
|
90
|
+
----------
|
|
91
|
+
ts : str
|
|
92
|
+
Timestamp such as ``2026-01-02T03:04:05Z``.
|
|
93
|
+
|
|
94
|
+
Returns
|
|
95
|
+
-------
|
|
96
|
+
datetime
|
|
97
|
+
Timezone-aware datetime.
|
|
98
|
+
"""
|
|
99
|
+
return datetime.fromisoformat(ts.replace("Z", "+00:00"))
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def trim_to_minute(ts: str) -> str:
|
|
103
|
+
"""Drop the seconds from a UTC ISO-8601 timestamp.
|
|
104
|
+
|
|
105
|
+
Parameters
|
|
106
|
+
----------
|
|
107
|
+
ts : str
|
|
108
|
+
Timestamp ending in ``Z`` or ``+00:00``.
|
|
109
|
+
|
|
110
|
+
Returns
|
|
111
|
+
-------
|
|
112
|
+
str
|
|
113
|
+
Timestamp like ``2026-01-02T03:04Z``; other formats are returned as-is.
|
|
114
|
+
"""
|
|
115
|
+
ts = ts.replace("+00:00", "Z")
|
|
116
|
+
if len(ts) >= 17 and ts.endswith("Z"):
|
|
117
|
+
return ts[:16] + "Z"
|
|
118
|
+
return ts
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def compute_version_key(title: str) -> tuple[int, int, int]:
|
|
122
|
+
"""Build a sort key from a ``vX.Y.Z`` milestone title.
|
|
123
|
+
|
|
124
|
+
Parameters
|
|
125
|
+
----------
|
|
126
|
+
title : str
|
|
127
|
+
Milestone title matching ``VERSION_RE``.
|
|
128
|
+
|
|
129
|
+
Returns
|
|
130
|
+
-------
|
|
131
|
+
tuple of int
|
|
132
|
+
``(major, minor, patch)``.
|
|
133
|
+
|
|
134
|
+
Raises
|
|
135
|
+
------
|
|
136
|
+
ValueError
|
|
137
|
+
If the title is not a ``vX.Y.Z`` version.
|
|
138
|
+
"""
|
|
139
|
+
match = VERSION_RE.match(title)
|
|
140
|
+
if match is None:
|
|
141
|
+
raise ValueError(f"not a vX.Y.Z version: {title!r}")
|
|
142
|
+
return (int(match.group(1)), int(match.group(2)), int(match.group(3)))
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def run_graphql_query(client: httpx.Client, variables: dict[str, Any]) -> dict:
|
|
146
|
+
"""Run ``QUERY`` against the GitHub GraphQL API.
|
|
147
|
+
|
|
148
|
+
Parameters
|
|
149
|
+
----------
|
|
150
|
+
client : httpx.Client
|
|
151
|
+
Authenticated HTTP client.
|
|
152
|
+
variables : dict
|
|
153
|
+
Query variables (``owner``, ``repo``, ``cursor``).
|
|
154
|
+
|
|
155
|
+
Returns
|
|
156
|
+
-------
|
|
157
|
+
dict
|
|
158
|
+
The ``data`` part of the response.
|
|
159
|
+
|
|
160
|
+
Raises
|
|
161
|
+
------
|
|
162
|
+
httpx.HTTPStatusError
|
|
163
|
+
On a non-2xx response.
|
|
164
|
+
RuntimeError
|
|
165
|
+
If the response contains GraphQL errors.
|
|
166
|
+
"""
|
|
167
|
+
resp = client.post(GRAPHQL_URL, json={"query": QUERY, "variables": variables})
|
|
168
|
+
resp.raise_for_status()
|
|
169
|
+
data = resp.json()
|
|
170
|
+
if "errors" in data:
|
|
171
|
+
raise RuntimeError(data["errors"])
|
|
172
|
+
return data["data"]
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def collect_milestone_additions(
|
|
176
|
+
client: httpx.Client, repo: RepoConfig, cutoff: datetime
|
|
177
|
+
) -> MilestoneAdditions:
|
|
178
|
+
"""Find issues/PRs added to ``vX.Y.Z`` milestones of a repo since ``cutoff``.
|
|
179
|
+
|
|
180
|
+
Parameters
|
|
181
|
+
----------
|
|
182
|
+
client : httpx.Client
|
|
183
|
+
Authenticated HTTP client.
|
|
184
|
+
repo : RepoConfig
|
|
185
|
+
Repository to query.
|
|
186
|
+
cutoff : datetime
|
|
187
|
+
Only milestone events at or after this time are reported.
|
|
188
|
+
|
|
189
|
+
Returns
|
|
190
|
+
-------
|
|
191
|
+
MilestoneAdditions
|
|
192
|
+
``{milestone_title: {"number": int, "items": {num: item}}}``.
|
|
193
|
+
"""
|
|
194
|
+
grouped: MilestoneAdditions = {}
|
|
195
|
+
cursor: str | None = None
|
|
196
|
+
|
|
197
|
+
while True:
|
|
198
|
+
data = run_graphql_query(
|
|
199
|
+
client, {"owner": repo.owner, "repo": repo.name, "cursor": cursor}
|
|
200
|
+
)
|
|
201
|
+
milestones = data["repository"]["milestones"]
|
|
202
|
+
stop = False
|
|
203
|
+
|
|
204
|
+
for milestone in milestones["nodes"]:
|
|
205
|
+
title = milestone["title"]
|
|
206
|
+
if not VERSION_RE.match(title):
|
|
207
|
+
continue
|
|
208
|
+
# Milestones are ordered by updatedAt desc; once we hit one
|
|
209
|
+
# older than cutoff we can stop paging.
|
|
210
|
+
if parse_iso(milestone["updatedAt"]) < cutoff:
|
|
211
|
+
stop = True
|
|
212
|
+
continue
|
|
213
|
+
|
|
214
|
+
for coll_key in ("issues", "pullRequests"):
|
|
215
|
+
for node in milestone[coll_key]["nodes"]:
|
|
216
|
+
# Prefilter: item's own updatedAt must be within window.
|
|
217
|
+
if parse_iso(node["updatedAt"]) < cutoff:
|
|
218
|
+
continue
|
|
219
|
+
matching = [
|
|
220
|
+
event
|
|
221
|
+
for event in node["timelineItems"]["nodes"]
|
|
222
|
+
if event.get("__typename") == "MilestonedEvent"
|
|
223
|
+
and event.get("milestoneTitle") == title
|
|
224
|
+
and parse_iso(event["createdAt"]) >= cutoff
|
|
225
|
+
]
|
|
226
|
+
if not matching:
|
|
227
|
+
continue
|
|
228
|
+
event = max(matching, key=lambda e: e["createdAt"])
|
|
229
|
+
actor = (event.get("actor") or {}).get("login") or "unknown"
|
|
230
|
+
bucket = grouped.setdefault(
|
|
231
|
+
title, {"number": milestone["number"], "items": {}}
|
|
232
|
+
)
|
|
233
|
+
bucket["items"][node["number"]] = {
|
|
234
|
+
"number": node["number"],
|
|
235
|
+
"title": (node.get("title") or "").strip(),
|
|
236
|
+
"url": node.get("url") or "",
|
|
237
|
+
"note": (
|
|
238
|
+
f"added by @{actor} at {trim_to_minute(event['createdAt'])}"
|
|
239
|
+
),
|
|
240
|
+
"sort_key": event["createdAt"],
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
if stop or not milestones["pageInfo"]["hasNextPage"]:
|
|
244
|
+
break
|
|
245
|
+
cursor = milestones["pageInfo"]["endCursor"]
|
|
246
|
+
|
|
247
|
+
return grouped
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def format_item_link(item: dict[str, Any]) -> str:
|
|
251
|
+
"""Format an issue/PR as a Markdown link.
|
|
252
|
+
|
|
253
|
+
Parameters
|
|
254
|
+
----------
|
|
255
|
+
item : dict
|
|
256
|
+
Item with ``number``, ``title`` and ``url``.
|
|
257
|
+
|
|
258
|
+
Returns
|
|
259
|
+
-------
|
|
260
|
+
str
|
|
261
|
+
``[#N title](url)``.
|
|
262
|
+
"""
|
|
263
|
+
return f"[#{item['number']} {item['title']}]({item['url']})"
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def render_changes_report(
|
|
267
|
+
repos: tuple[RepoConfig, ...],
|
|
268
|
+
repo_data: dict[str, MilestoneAdditions | Exception],
|
|
269
|
+
hours: float,
|
|
270
|
+
) -> str:
|
|
271
|
+
"""Render the Markdown report of milestone additions.
|
|
272
|
+
|
|
273
|
+
Parameters
|
|
274
|
+
----------
|
|
275
|
+
repos : tuple of RepoConfig
|
|
276
|
+
Repositories in report order.
|
|
277
|
+
repo_data : dict
|
|
278
|
+
Result of ``collect_milestone_additions`` per repo name, or the
|
|
279
|
+
exception raised while collecting it.
|
|
280
|
+
hours : float
|
|
281
|
+
Look-back window, used in headings.
|
|
282
|
+
|
|
283
|
+
Returns
|
|
284
|
+
-------
|
|
285
|
+
str
|
|
286
|
+
Markdown report.
|
|
287
|
+
"""
|
|
288
|
+
lines: list[str] = [f"# Milestone additions in the last {hours:g}h", ""]
|
|
289
|
+
total_items = 0
|
|
290
|
+
repos_with_items = 0
|
|
291
|
+
total_versions = 0
|
|
292
|
+
|
|
293
|
+
for repo in repos:
|
|
294
|
+
lines.append(f"- {repo.name}")
|
|
295
|
+
result = repo_data.get(repo.name)
|
|
296
|
+
if isinstance(result, Exception):
|
|
297
|
+
lines.append(f" - _error: {result}_")
|
|
298
|
+
continue
|
|
299
|
+
grouped = result or {}
|
|
300
|
+
if not grouped:
|
|
301
|
+
lines.append(f" - _no additions in the last {hours:g}h_")
|
|
302
|
+
continue
|
|
303
|
+
|
|
304
|
+
repos_with_items += 1
|
|
305
|
+
total_versions += len(grouped)
|
|
306
|
+
|
|
307
|
+
for title in sorted(grouped, key=compute_version_key):
|
|
308
|
+
bucket = grouped[title]
|
|
309
|
+
milestone_url = (
|
|
310
|
+
f"https://github.com/{repo.owner}/{repo.name}"
|
|
311
|
+
f"/milestone/{bucket['number']}"
|
|
312
|
+
)
|
|
313
|
+
lines.append(f" - [{title}]({milestone_url})")
|
|
314
|
+
items = sorted(bucket["items"].values(), key=lambda i: i["sort_key"])
|
|
315
|
+
for item in items:
|
|
316
|
+
lines.append(f" - {format_item_link(item)}")
|
|
317
|
+
total_items += 1
|
|
318
|
+
|
|
319
|
+
lines.append("")
|
|
320
|
+
lines.append(
|
|
321
|
+
f"Summary: {total_items} items across "
|
|
322
|
+
f"{repos_with_items} repos / {total_versions} versions "
|
|
323
|
+
f"in the last {hours:g}h."
|
|
324
|
+
)
|
|
325
|
+
return "\n".join(lines)
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def create_github_client(token: str) -> httpx.Client:
|
|
329
|
+
"""Create an HTTP client authenticated against the GitHub API.
|
|
330
|
+
|
|
331
|
+
Parameters
|
|
332
|
+
----------
|
|
333
|
+
token : str
|
|
334
|
+
GitHub token.
|
|
335
|
+
|
|
336
|
+
Returns
|
|
337
|
+
-------
|
|
338
|
+
httpx.Client
|
|
339
|
+
The client; the caller is responsible for closing it.
|
|
340
|
+
"""
|
|
341
|
+
headers = {
|
|
342
|
+
"Accept": "application/vnd.github+json",
|
|
343
|
+
"Authorization": f"Bearer {token}",
|
|
344
|
+
"User-Agent": "github-milestone-roadmap",
|
|
345
|
+
}
|
|
346
|
+
return httpx.Client(headers=headers, timeout=60.0)
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def report_milestone_changes(
|
|
350
|
+
client: httpx.Client, repos: tuple[RepoConfig, ...], hours: float
|
|
351
|
+
) -> tuple[str, bool]:
|
|
352
|
+
"""Collect milestone additions for all repos and render the report.
|
|
353
|
+
|
|
354
|
+
Parameters
|
|
355
|
+
----------
|
|
356
|
+
client : httpx.Client
|
|
357
|
+
Authenticated HTTP client.
|
|
358
|
+
repos : tuple of RepoConfig
|
|
359
|
+
Repositories to report on.
|
|
360
|
+
hours : float
|
|
361
|
+
Look-back window in hours.
|
|
362
|
+
|
|
363
|
+
Returns
|
|
364
|
+
-------
|
|
365
|
+
tuple of (str, bool)
|
|
366
|
+
The Markdown report, and whether any repo failed.
|
|
367
|
+
"""
|
|
368
|
+
cutoff = datetime.now(UTC) - timedelta(hours=hours)
|
|
369
|
+
repo_data: dict[str, MilestoneAdditions | Exception] = {}
|
|
370
|
+
had_error = False
|
|
371
|
+
for repo in repos:
|
|
372
|
+
try:
|
|
373
|
+
repo_data[repo.name] = collect_milestone_additions(client, repo, cutoff)
|
|
374
|
+
except Exception as exc: # noqa: BLE001
|
|
375
|
+
had_error = True
|
|
376
|
+
repo_data[repo.name] = exc
|
|
377
|
+
return render_changes_report(repos, repo_data, hours), had_error
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
"""Command-line interface: ``github-milestone-roadmap build|changes``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import os
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
from . import __version__
|
|
11
|
+
from .build import build_site
|
|
12
|
+
from .changes import create_github_client, report_milestone_changes
|
|
13
|
+
from .config import ConfigError, load_config
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def build_arg_parser() -> argparse.ArgumentParser:
|
|
17
|
+
"""Create the argument parser for the CLI.
|
|
18
|
+
|
|
19
|
+
Returns
|
|
20
|
+
-------
|
|
21
|
+
argparse.ArgumentParser
|
|
22
|
+
Parser with the ``build`` and ``changes`` subcommands.
|
|
23
|
+
"""
|
|
24
|
+
parser = argparse.ArgumentParser(
|
|
25
|
+
prog="github-milestone-roadmap",
|
|
26
|
+
description="Build a live roadmap website from GitHub release milestones.",
|
|
27
|
+
)
|
|
28
|
+
parser.add_argument(
|
|
29
|
+
"--version", action="version", version=f"%(prog)s {__version__}"
|
|
30
|
+
)
|
|
31
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
32
|
+
|
|
33
|
+
build = subparsers.add_parser(
|
|
34
|
+
"build", help="Write the static roadmap site to a directory."
|
|
35
|
+
)
|
|
36
|
+
build.add_argument(
|
|
37
|
+
"--config",
|
|
38
|
+
type=Path,
|
|
39
|
+
default=Path("roadmap.toml"),
|
|
40
|
+
help="Roadmap config file (default: roadmap.toml).",
|
|
41
|
+
)
|
|
42
|
+
build.add_argument(
|
|
43
|
+
"--output",
|
|
44
|
+
type=Path,
|
|
45
|
+
required=True,
|
|
46
|
+
help="Directory to write the site to (created if missing).",
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
changes = subparsers.add_parser(
|
|
50
|
+
"changes",
|
|
51
|
+
help="Print a Markdown list of issues/PRs recently added to vX.Y.Z milestones.",
|
|
52
|
+
)
|
|
53
|
+
changes.add_argument(
|
|
54
|
+
"--config",
|
|
55
|
+
type=Path,
|
|
56
|
+
default=Path("roadmap.toml"),
|
|
57
|
+
help="Roadmap config file (default: roadmap.toml).",
|
|
58
|
+
)
|
|
59
|
+
changes.add_argument(
|
|
60
|
+
"--hours",
|
|
61
|
+
type=float,
|
|
62
|
+
default=24.0,
|
|
63
|
+
help="Look-back window in hours (default: 24).",
|
|
64
|
+
)
|
|
65
|
+
changes.add_argument(
|
|
66
|
+
"--token",
|
|
67
|
+
default=os.environ.get("GITHUB_TOKEN"),
|
|
68
|
+
help="GitHub token (default: $GITHUB_TOKEN).",
|
|
69
|
+
)
|
|
70
|
+
return parser
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def run_build_command(args: argparse.Namespace) -> int:
|
|
74
|
+
"""Run the ``build`` subcommand.
|
|
75
|
+
|
|
76
|
+
Parameters
|
|
77
|
+
----------
|
|
78
|
+
args : argparse.Namespace
|
|
79
|
+
Parsed arguments.
|
|
80
|
+
|
|
81
|
+
Returns
|
|
82
|
+
-------
|
|
83
|
+
int
|
|
84
|
+
Exit code.
|
|
85
|
+
"""
|
|
86
|
+
config = load_config(args.config)
|
|
87
|
+
written = build_site(config, args.output)
|
|
88
|
+
print(
|
|
89
|
+
f"github-milestone-roadmap {__version__}: wrote {len(written)} files "
|
|
90
|
+
f"to {args.output}",
|
|
91
|
+
file=sys.stderr,
|
|
92
|
+
)
|
|
93
|
+
return 0
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def run_changes_command(args: argparse.Namespace) -> int:
|
|
97
|
+
"""Run the ``changes`` subcommand.
|
|
98
|
+
|
|
99
|
+
Parameters
|
|
100
|
+
----------
|
|
101
|
+
args : argparse.Namespace
|
|
102
|
+
Parsed arguments.
|
|
103
|
+
|
|
104
|
+
Returns
|
|
105
|
+
-------
|
|
106
|
+
int
|
|
107
|
+
Exit code: 0 on success, 1 if any repo failed, 2 without a token.
|
|
108
|
+
"""
|
|
109
|
+
if not args.token:
|
|
110
|
+
print(
|
|
111
|
+
"error: GraphQL requires a token; set GITHUB_TOKEN or pass --token.",
|
|
112
|
+
file=sys.stderr,
|
|
113
|
+
)
|
|
114
|
+
return 2
|
|
115
|
+
config = load_config(args.config)
|
|
116
|
+
with create_github_client(args.token) as client:
|
|
117
|
+
report, had_error = report_milestone_changes(client, config.repos, args.hours)
|
|
118
|
+
print(report)
|
|
119
|
+
return 1 if had_error else 0
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def main(argv: list[str] | None = None) -> int:
|
|
123
|
+
"""Run the CLI.
|
|
124
|
+
|
|
125
|
+
Parameters
|
|
126
|
+
----------
|
|
127
|
+
argv : list of str or None
|
|
128
|
+
Arguments without the program name; ``None`` uses ``sys.argv``.
|
|
129
|
+
|
|
130
|
+
Returns
|
|
131
|
+
-------
|
|
132
|
+
int
|
|
133
|
+
Exit code.
|
|
134
|
+
"""
|
|
135
|
+
args = build_arg_parser().parse_args(argv)
|
|
136
|
+
try:
|
|
137
|
+
if args.command == "build":
|
|
138
|
+
return run_build_command(args)
|
|
139
|
+
return run_changes_command(args)
|
|
140
|
+
except (ConfigError, FileNotFoundError) as exc:
|
|
141
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
142
|
+
return 2
|