basstler-hub 4.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 (53) hide show
  1. basstler/plan_site/__init__.py +0 -0
  2. basstler/plan_site/__main__.py +532 -0
  3. basstler/plan_site/attach_approval.py +207 -0
  4. basstler/plan_site/build_start.py +289 -0
  5. basstler/plan_site/cards.py +498 -0
  6. basstler/plan_site/chip_tone.py +102 -0
  7. basstler/plan_site/dispatch_check.py +569 -0
  8. basstler/plan_site/entry_point_approval.py +176 -0
  9. basstler/plan_site/exceptions.py +259 -0
  10. basstler/plan_site/handover_button.py +37 -0
  11. basstler/plan_site/hub.py +467 -0
  12. basstler/plan_site/hub_page.py +725 -0
  13. basstler/plan_site/item_classifier.py +300 -0
  14. basstler/plan_site/live_state_display.py +104 -0
  15. basstler/plan_site/merge_workflow_refresh.py +68 -0
  16. basstler/plan_site/plan_overview.py +128 -0
  17. basstler/plan_site/plan_page.py +190 -0
  18. basstler/plan_site/plan_page_header.py +54 -0
  19. basstler/plan_site/plan_page_vocabulary.py +84 -0
  20. basstler/plan_site/publication.py +796 -0
  21. basstler/plan_site/site_read.py +149 -0
  22. basstler/plan_site/site_repository.py +125 -0
  23. basstler/plan_site/site_vocabulary.py +55 -0
  24. basstler/plan_site/token_storage.py +256 -0
  25. basstler/plan_site/user_steps.py +477 -0
  26. basstler/plan_site/workflows.py +514 -0
  27. basstler/templates/hub.html +25 -0
  28. basstler/templates/plan_handover_guide.md.jinja +108 -0
  29. basstler/templates/plan_handover_pull_request.md.jinja +42 -0
  30. basstler/templates/plan_handover_summary.md.jinja +6 -0
  31. basstler/templates/plan_handover_taken_over.md.jinja +12 -0
  32. basstler/templates/plan_site_dispatch_workflow.yml +36 -0
  33. basstler/templates/plan_site_merge_workflow.yml +14 -0
  34. basstler/templates/plan_site_store_token_command.sh +6 -0
  35. basstler/templates/plan_site_workflow.yml +24 -0
  36. basstler/templates/review_triage_mark_viewed_caller.yml +34 -0
  37. basstler/templates/review_triage_mark_viewed_setup.md.jinja +42 -0
  38. basstler/templates/shared_token_store_command.sh +10 -0
  39. basstler/templates/site.css +267 -0
  40. basstler/templates/site_index.html +26 -0
  41. basstler/templates/site_layout.html +18 -0
  42. basstler/templates/site_live_progress.js +119 -0
  43. basstler/templates/site_live_state.js +28 -0
  44. basstler/templates/site_parts.html +97 -0
  45. basstler/templates/site_plan.html +169 -0
  46. basstler/templates/site_plan.js +171 -0
  47. basstler/templates/site_plan_pull_request_recheck.js +195 -0
  48. basstler_hub-4.2.0.dist-info/METADATA +21 -0
  49. basstler_hub-4.2.0.dist-info/RECORD +53 -0
  50. basstler_hub-4.2.0.dist-info/WHEEL +4 -0
  51. basstler_hub-4.2.0.dist-info/entry_points.txt +2 -0
  52. basstler_hub-4.2.0.dist-info/licenses/LICENSE +202 -0
  53. basstler_hub-4.2.0.dist-info/licenses/NOTICE +13 -0
File without changes
@@ -0,0 +1,532 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Build the plan site: the hub, each repository's plans, and each plan's page.
4
+
5
+ Reads the hub file, fetches every repository it lists, and renders that repository's
6
+ plans with the live state of every pull request they reference. Nothing here needs a
7
+ Claude session or belongs to an account, so the site is the same for everyone:
8
+
9
+ <site>/ the hub, one card per repository
10
+ <site>/<owner>/<repo>/ that repository's plans
11
+ <site>/<owner>/<repo>/<plan>/ a plan's page
12
+
13
+ Usage:
14
+ python3 -m basstler.plan_site --registry <owner/repo> --output _site \\
15
+ [--site-url <url>] [--remote-root <url or directory>]
16
+
17
+ The hub file is read off the registry's notes branch. A plan whose manifest fails
18
+ validation, or a repository whose notes cannot be fetched, is reported and left out;
19
+ everything else is still published.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import hashlib
26
+ import re
27
+ import sys
28
+ import tempfile
29
+ from abc import ABC, abstractmethod
30
+ from dataclasses import dataclass, field
31
+ from datetime import UTC, datetime
32
+ from enum import StrEnum
33
+ from pathlib import Path
34
+ from typing import Any
35
+
36
+ import yaml
37
+
38
+ from basstler.github.pull_request_source import (
39
+ GitHubPullRequestSource,
40
+ PullRequestSource,
41
+ )
42
+ from basstler.github.repository import GitHubAddress, Repository
43
+ from basstler.locations import ProjectLocation
44
+ from basstler.plan.dependencies import DependencyResolver, PlanDirectory
45
+ from basstler.plan.exceptions import PlanValidationError
46
+ from basstler.plan.model import PlanDocument
47
+ from basstler.plan.repository_rules import RepositoryRules
48
+ from basstler.plan.structure import Plan
49
+ from basstler.plan.validation import PlanValidator
50
+ from basstler.plan_site.cards import PlanTimeAttribute
51
+ from basstler.plan_site.hub import NotesBranch, PlanHub, SiteAddress
52
+ from basstler.plan_site.hub_page import (
53
+ CountedItem,
54
+ HubPage,
55
+ PlanSummary,
56
+ ProgressCard,
57
+ RepositoryIndexPage,
58
+ RepositorySummary,
59
+ SiteStylesheet,
60
+ SiteSummary,
61
+ SkippedPage,
62
+ )
63
+ from basstler.plan_site.item_classifier import ItemClassifier
64
+ from basstler.plan_site.plan_page import PlanPage, RenderedPlanPage
65
+ from basstler.plan_site.plan_page_header import PlanPageHeader
66
+ from basstler.standard_streams import StandardStreamHandler
67
+ from basstler.text_file import TextFile
68
+
69
+ logger = StandardStreamHandler.logger_for(__name__)
70
+ """
71
+ This module's logger, which is also what its command prints through.
72
+ """
73
+
74
+
75
+ class SiteFile(StrEnum):
76
+ """
77
+ The files the site writes beside its pages.
78
+ """
79
+
80
+ PAGE = "index.html"
81
+ """
82
+ The page a directory serves, for the hub, every index and every plan alike.
83
+ """
84
+
85
+ NO_JEKYLL = ".nojekyll"
86
+ """
87
+ The marker that stops GitHub Pages from running Jekyll over already-rendered HTML.
88
+ """
89
+
90
+ DIGEST = "site-digest.txt"
91
+ """
92
+ The site's :class:`SiteDigest`, which a deploy compares with the published one.
93
+ """
94
+
95
+ STYLESHEET = "site.css"
96
+ """
97
+ The one stylesheet every page links, at the site's root.
98
+ """
99
+
100
+
101
+ BUILD_TIME_PATTERN = re.compile(
102
+ rf"<time [^>]*{PlanTimeAttribute.REFRESHED}[^>]*>[^<]*</time>".encode()
103
+ )
104
+ """
105
+ The element a plan page shows the build time in.
106
+ """
107
+
108
+
109
+ @dataclass(frozen=True)
110
+ class SiteDigest:
111
+ """
112
+ A fingerprint of a built site's pages: two builds have the same digest exactly when
113
+ they publish the same files with the same content, apart from the build time.
114
+ """
115
+
116
+ site_directory: Path
117
+ """
118
+ The root directory the site was built into.
119
+ """
120
+
121
+ @property
122
+ def value(self) -> str:
123
+ """
124
+ The fingerprint, as a hexadecimal SHA-256, leaving out :attr:`SiteFile.DIGEST`.
125
+ """
126
+ digest = hashlib.sha256()
127
+ for path in sorted(self.site_directory.rglob("*")):
128
+ relative_path = path.relative_to(self.site_directory)
129
+ if not path.is_file() or relative_path == Path(SiteFile.DIGEST):
130
+ continue
131
+ digest.update(relative_path.as_posix().encode())
132
+ digest.update(hashlib.sha256(self.content_of(path)).digest())
133
+ return digest.hexdigest()
134
+
135
+ @staticmethod
136
+ def content_of(path: Path) -> bytes:
137
+ """
138
+ :param path: A built file.
139
+ :return: Its content without the build time, so a build that changed nothing
140
+ else has the published digest and skips the deploy.
141
+ """
142
+ return BUILD_TIME_PATTERN.sub(b"", path.read_bytes())
143
+
144
+ def write(self) -> None:
145
+ """
146
+ Write :attr:`value` to the site's :attr:`SiteFile.DIGEST`.
147
+ """
148
+ TextFile(self.site_directory / SiteFile.DIGEST).write(f"{self.value}\n")
149
+
150
+
151
+ # %% a plan as the notes branch stores it
152
+
153
+
154
+ @dataclass
155
+ class PlanSource:
156
+ """
157
+ One plan's manifest and roadmap, as read from its directory on the notes branch.
158
+ """
159
+
160
+ directory_name: str
161
+ """
162
+ The plan's directory name, which is also the path its page is published under.
163
+ """
164
+
165
+ manifest: dict[str, Any]
166
+ """
167
+ The parsed ``plan.yaml``, not yet validated.
168
+ """
169
+
170
+ roadmap_text: str
171
+ """
172
+ The plan's ``roadmap.md``, or an empty string if it has none.
173
+ """
174
+
175
+ @classmethod
176
+ def from_directory(cls, directory: Path) -> PlanSource:
177
+ """
178
+ Read one plan's directory.
179
+
180
+ :param directory: The directory holding the plan's manifest.
181
+ :return: The plan's source.
182
+ """
183
+ roadmap = directory / PlanDocument.ROADMAP
184
+ return cls(
185
+ directory_name=directory.name,
186
+ manifest=yaml.safe_load(TextFile(directory / PlanDocument.MANIFEST).read()),
187
+ roadmap_text=TextFile(roadmap).read() if roadmap.exists() else "",
188
+ )
189
+
190
+ @classmethod
191
+ def every_plan_in(cls, plans_directory: Path) -> list[PlanSource]:
192
+ """
193
+ Read every plan under a ``plans`` directory, in directory-name order.
194
+
195
+ :param plans_directory: The directory holding one subdirectory per plan.
196
+ :return: Each subdirectory that carries a manifest.
197
+ """
198
+ return [
199
+ cls.from_directory(manifest.parent)
200
+ for manifest in sorted(plans_directory.glob(f"*/{PlanDocument.MANIFEST}"))
201
+ ]
202
+
203
+
204
+ # %% the site
205
+
206
+
207
+ @dataclass
208
+ class PublishedPlan:
209
+ """
210
+ One plan rendered to its page, with the entry the index lists it under.
211
+ """
212
+
213
+ page: RenderedPlanPage
214
+ """
215
+ The plan's rendered page.
216
+ """
217
+
218
+ summary: PlanSummary
219
+ """
220
+ The plan's card on its repository's index.
221
+ """
222
+
223
+
224
+ @dataclass
225
+ class SiteSection[SectionCard: ProgressCard](ABC):
226
+ """
227
+ One part of the site: the pages it writes under the site's root, and the card that
228
+ stands for it on the page above: a repository's on the hub, or the whole site's.
229
+ """
230
+
231
+ address: SiteAddress
232
+ """
233
+ The address the whole site is served from, which every link is built on.
234
+ """
235
+
236
+ pull_request_source: PullRequestSource
237
+ """
238
+ Where the live pull request state comes from.
239
+ """
240
+
241
+ built_at: datetime = field(default_factory=lambda: datetime.now(UTC), kw_only=True)
242
+ """
243
+ When the site is built, which every plan page shows as its last refresh.
244
+ """
245
+
246
+ @property
247
+ def stylesheet_url(self) -> str:
248
+ """
249
+ The address of the site's one stylesheet, which every page links.
250
+ """
251
+ return f"{self.address.hub_url}{SiteFile.STYLESHEET}"
252
+
253
+ @abstractmethod
254
+ def build(self, output: Path) -> SectionCard:
255
+ """
256
+ Render this part of the site.
257
+
258
+ :param output: The site's root directory.
259
+ :return: The card summing this part up.
260
+ """
261
+
262
+ @staticmethod
263
+ def write_page(directory: Path, html: str) -> None:
264
+ """
265
+ :param directory: The directory the page is served from.
266
+ :param html: The page's rendered HTML.
267
+ """
268
+ directory.mkdir(parents=True, exist_ok=True)
269
+ TextFile(directory / SiteFile.PAGE).write(html)
270
+
271
+
272
+ @dataclass
273
+ class RepositorySite(SiteSection[RepositorySummary]):
274
+ """
275
+ One repository's plans: their pages plus the index linking them.
276
+ """
277
+
278
+ notes: NotesBranch
279
+ """
280
+ The repository's notes branch, which holds and dates its plans.
281
+ """
282
+
283
+ plans_directory: Path = field(init=False)
284
+ """
285
+ The notes branch's ``plans`` directory, checked out with one subdirectory per plan.
286
+ """
287
+
288
+ plan_directory: PlanDirectory = field(init=False)
289
+ """
290
+ The same plans, as the ``<plan-id>/<item-id>`` entries of any one of them resolve
291
+ against.
292
+ """
293
+
294
+ repository_rules: RepositoryRules = field(init=False)
295
+ """
296
+ The rules every plan of the repository follows, as its notes branch holds them.
297
+ """
298
+
299
+ def __post_init__(self) -> None:
300
+ """
301
+ Check the plans out of the notes branch and load them and the repository's rules.
302
+ """
303
+ self.plans_directory = self.notes.check_out_plans()
304
+ self.plan_directory = PlanDirectory(self.plans_directory)
305
+ self.repository_rules = RepositoryRules.from_file(
306
+ self.plans_directory / ProjectLocation.PLAN_RULES.name
307
+ )
308
+
309
+ def plan_url(self, directory_name: str) -> str:
310
+ """
311
+ :param directory_name: The plan's directory name.
312
+ :return: The address its page is served from.
313
+ """
314
+ return self.address.plan_url(self.notes.repository, directory_name)
315
+
316
+ def build(self, output: Path) -> RepositorySummary:
317
+ """
318
+ Render this repository's index and plans into the site.
319
+
320
+ :param output: The site's root directory.
321
+ :return: The repository's card on the hub, naming every plan left out.
322
+ """
323
+ sources = PlanSource.every_plan_in(self.plans_directory)
324
+ skipped = {
325
+ source.directory_name: page
326
+ for source in sources
327
+ if (page := self.skipped_page_of(source)) is not None
328
+ }
329
+ published = {
330
+ source.directory_name: self.publish(source)
331
+ for source in sources
332
+ if source.directory_name not in skipped
333
+ }
334
+ repository_directory = output / str(self.notes.repository)
335
+ for directory_name, plan in published.items():
336
+ self.write_page(repository_directory / directory_name, plan.page.html)
337
+ repository = RepositorySummary.over_plans(
338
+ str(self.notes.repository),
339
+ self.address.repository_url(self.notes.repository),
340
+ [plan.summary for plan in published.values()],
341
+ list(skipped.values()),
342
+ )
343
+ index = RepositoryIndexPage(
344
+ repository, self.address.hub_url, self.stylesheet_url
345
+ )
346
+ self.write_page(repository_directory, index.render())
347
+ return repository
348
+
349
+ def skipped_page_of(self, source: PlanSource) -> SkippedPage | None:
350
+ """
351
+ :param source: The plan to check.
352
+ :return: Why it is left out of the site, logging it, or ``None`` when its
353
+ manifest passes validation.
354
+ """
355
+ problems = PlanValidator(source.manifest, self.plan_directory).problems
356
+ if not problems:
357
+ return None
358
+ page = SkippedPage(
359
+ site_path=f"{self.notes.repository}/{source.directory_name}",
360
+ reason=PlanValidationError(problems).error_message(),
361
+ )
362
+ logger.warning(f"{page.site_path} is not published: {page.reason}")
363
+ return page
364
+
365
+ def publish(self, source: PlanSource) -> PublishedPlan:
366
+ """
367
+ Render one valid plan.
368
+
369
+ :param source: The plan to render.
370
+ :return: Its page and its index entry.
371
+ """
372
+ plan = Plan.from_mapping(source.manifest)
373
+ dependencies = DependencyResolver(plan, self.plan_directory)
374
+ live_pull_requests = self.pull_request_source.live_pull_requests_of(
375
+ dependencies.pull_request_references
376
+ )
377
+ for repository, failure in live_pull_requests.read_failures.items():
378
+ logger.warning(
379
+ f"{self.notes.repository}/{source.directory_name}: "
380
+ f"{ItemClassifier.access_warning_of(repository, failure)}"
381
+ )
382
+ renderer = PlanPage(
383
+ stylesheet_url=self.stylesheet_url,
384
+ plan=plan,
385
+ roadmap_text=source.roadmap_text,
386
+ repository_rules=self.repository_rules,
387
+ live_pull_requests=live_pull_requests,
388
+ header=PlanPageHeader(
389
+ tracking_url=self.tracking_url_of(plan),
390
+ hub_url=self.address.hub_url,
391
+ index_url=self.address.repository_url(self.notes.repository),
392
+ history=self.notes.history_of(source.directory_name),
393
+ built_at=self.built_at,
394
+ ),
395
+ plan_directory=self.plan_directory,
396
+ locate_plan_page=self.plan_url,
397
+ )
398
+ page = renderer.render()
399
+ summary = PlanSummary(
400
+ id=plan.id,
401
+ title=plan.title,
402
+ description=plan.description,
403
+ page_url=self.plan_url(source.directory_name),
404
+ counted_items=CountedItem.from_plan(plan),
405
+ )
406
+ return PublishedPlan(page=page, summary=summary)
407
+
408
+ def tracking_url_of(self, plan: Plan) -> str | None:
409
+ """
410
+ :param plan: The plan whose tracking issue to link.
411
+ :return: The tracking issue's page, or ``None`` if the plan has none.
412
+ """
413
+ if plan.tracking_issue is None:
414
+ return None
415
+ return self.pull_request_source.issue_url(
416
+ Repository.parse(plan.default_repository), plan.tracking_issue
417
+ )
418
+
419
+
420
+ @dataclass
421
+ class HubSite(SiteSection[SiteSummary]):
422
+ """
423
+ The whole site: the hub page over every repository the hub file lists.
424
+ """
425
+
426
+ hub: PlanHub
427
+ """
428
+ The hub file, naming the repositories to publish.
429
+ """
430
+
431
+ remote_root: str = GitHubAddress.WEB.value
432
+ """
433
+ Where the listed repositories are fetched from, as
434
+ :meth:`Repository.clone_url_under` takes it.
435
+ """
436
+
437
+ def build(self, output: Path) -> SiteSummary:
438
+ """
439
+ Render every repository, then the hub linking them and the stylesheet every page
440
+ links, then the site's digest.
441
+
442
+ :param output: The directory to write the site into.
443
+ :return: The site's summary, holding every repository's card in the hub file's
444
+ order.
445
+ """
446
+ with tempfile.TemporaryDirectory() as scratch:
447
+ repositories = [
448
+ self.build_repository(
449
+ Repository.parse(repository), Path(scratch) / str(position), output
450
+ )
451
+ for position, repository in enumerate(self.hub.repositories)
452
+ ]
453
+ summary = SiteSummary.over_repositories(repositories)
454
+ self.write_page(output, HubPage(summary, self.stylesheet_url).render())
455
+ TextFile(output / SiteFile.STYLESHEET).write(SiteStylesheet().render())
456
+ (output / SiteFile.NO_JEKYLL).touch()
457
+ SiteDigest(output).write()
458
+ return summary
459
+
460
+ def build_repository(
461
+ self, repository: Repository, scratch: Path, output: Path
462
+ ) -> RepositorySummary:
463
+ """
464
+ :param repository: The repository to publish.
465
+ :param scratch: A directory of its own to fetch the notes into.
466
+ :param output: The site's root directory.
467
+ :return: The repository's card, with an error when its notes cannot be read.
468
+ """
469
+ notes = NotesBranch.fetch(
470
+ repository, self.hub.notes_branch, self.remote_root, scratch
471
+ )
472
+ if notes is None:
473
+ return RepositorySummary.unreadable(
474
+ str(repository), f"cannot fetch {self.hub.notes_branch}"
475
+ )
476
+ site = RepositorySite(
477
+ address=self.address,
478
+ pull_request_source=self.pull_request_source,
479
+ notes=notes,
480
+ built_at=self.built_at,
481
+ )
482
+ return site.build(output)
483
+
484
+
485
+ def main() -> int:
486
+ """
487
+ Parse arguments and build the site. See the module docstring for the CLI contract.
488
+ """
489
+ parser = argparse.ArgumentParser(
490
+ description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
491
+ )
492
+ parser.add_argument(
493
+ "--registry", required=True, help="The repository whose notes hold the hub file"
494
+ )
495
+ parser.add_argument(
496
+ "--output", required=True, type=Path, help="The directory to write the site to"
497
+ )
498
+ parser.add_argument(
499
+ "--site-url", default=None, help="The site's address, if not the hub file's"
500
+ )
501
+ parser.add_argument(
502
+ "--remote-root",
503
+ default=GitHubAddress.WEB.value,
504
+ help="Where repositories are fetched from, as <root>/<owner>/<repo>.git",
505
+ )
506
+ arguments = parser.parse_args()
507
+
508
+ hub = PlanHub.from_registry(
509
+ Repository.parse(arguments.registry), arguments.remote_root
510
+ )
511
+ if hub is None:
512
+ logger.error(f"{arguments.registry} has no hub file on its notes branch.")
513
+ return 1
514
+ site_url = arguments.site_url or hub.site_url
515
+ if not site_url:
516
+ logger.error("The hub file names no site_url; pass --site-url.")
517
+ return 1
518
+ site = HubSite(
519
+ address=SiteAddress(site_url),
520
+ pull_request_source=GitHubPullRequestSource.from_environment(
521
+ reads_mergeable_states=True
522
+ ),
523
+ hub=hub,
524
+ remote_root=arguments.remote_root,
525
+ )
526
+ summary = site.build(arguments.output)
527
+ logger.info(f"published {summary.progress_label} to {arguments.output}")
528
+ return 0
529
+
530
+
531
+ if __name__ == "__main__":
532
+ sys.exit(main())