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.
@@ -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