basstler-notes 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.
@@ -0,0 +1,346 @@
1
+ """
2
+ Reading check-setup.sh's report.
3
+
4
+ The script's tab-separated rows are its whole interface, so they are read back into the
5
+ check each row is about and the status it reports.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import subprocess
11
+ from collections.abc import Mapping
12
+ from dataclasses import dataclass
13
+ from enum import IntEnum, StrEnum
14
+ from pathlib import Path
15
+
16
+ from basstler.bash import Bash
17
+ from basstler.exit_codes import SetupCheckExitCode
18
+ from basstler.locations import PluginLocation
19
+ from basstler.plugin_root import PluginRoot
20
+ from basstler.setup.exceptions import CheckSetupFailedError
21
+
22
+ # %% what a report is made of
23
+
24
+
25
+ class SetupCheck(StrEnum):
26
+ """
27
+ The checks check-setup.sh reports on, in the order it prints them.
28
+ """
29
+
30
+ TOOLING_FILES = "tooling_files"
31
+ """
32
+ The plugin's own files a set up clone runs.
33
+ """
34
+
35
+ SESSION_START_HOOK = "session_start_hook"
36
+ """
37
+ The SessionStart hook registered in the plugin.
38
+ """
39
+
40
+ CLAUDE_LOCAL_MD_IGNORED = "claude_local_md_ignored"
41
+ """
42
+ ``CLAUDE.local.md`` excluded from commits.
43
+ """
44
+
45
+ NOTES_REMOTE = "notes_remote"
46
+ """
47
+ The remote the notes branch resolves to, and where that came from.
48
+ """
49
+
50
+ NOTES_REMOTE_URL = "notes_remote_url"
51
+ """
52
+ That remote's URL.
53
+ """
54
+
55
+ NOTES_BRANCH_NAME = "notes_branch_name"
56
+ """
57
+ The notes branch's name, and where that came from.
58
+ """
59
+
60
+ NOTES_PATH = "notes_path"
61
+ """
62
+ The notes file's path on that branch, and where that came from.
63
+ """
64
+
65
+ NOTES_REPOSITORY_ACCESS = "notes_repository_access"
66
+ """
67
+ A cloud session reaching the repository the notes are kept in.
68
+ """
69
+
70
+ NOTES_BRANCH = "notes_branch"
71
+ """
72
+ The notes branch existing on its remote.
73
+ """
74
+
75
+ NOTES_FILE = "notes_file"
76
+ """
77
+ The notes file existing on that branch.
78
+ """
79
+
80
+ STACK_UPSTREAM = "stack_upstream"
81
+ """
82
+ The project's upstream named for the stacked-pull-request workflow.
83
+ """
84
+
85
+ UPSTREAM_REVIEWS_ACTION = "upstream_reviews_action"
86
+ """
87
+ The fork's own upstream-reviews Action, installed at the session's basstler.
88
+ """
89
+
90
+ PLAN_SITE = "plan_site"
91
+ """
92
+ Every repository on the plan site storing its token and starting the site's build.
93
+ """
94
+
95
+ PLAN_SITE_ACCESS = "plan_site_access"
96
+ """
97
+ A cloud session reaching the plan site's repository, so a plan save can start the
98
+ build.
99
+ """
100
+
101
+ GIT_IDENTITY = "git_identity"
102
+ """
103
+ The identity commits are authored with, against the recorded one.
104
+ """
105
+
106
+ PACKAGE_DEPENDENCIES = "package_dependencies"
107
+ """
108
+ Every dependency the package declares being installed.
109
+ """
110
+
111
+ BASSTLER_VERSION = "basstler_version"
112
+ """
113
+ The installed package's version, against the plugin's own release.
114
+ """
115
+
116
+ CLAUDE_LOCAL_MD = "claude_local_md"
117
+ """
118
+ ``CLAUDE.local.md`` written by the SessionStart hook.
119
+ """
120
+
121
+
122
+ class RepositoryCheck(StrEnum):
123
+ """
124
+ The checks check-setup.sh reports once for each repository, after the fixed ones.
125
+ """
126
+
127
+ PLAN_SITE_REPOSITORY = "plan_site_repository"
128
+ """
129
+ One repository on the plan site other than the clone's own, informational only.
130
+ """
131
+
132
+
133
+ class CheckStatus(StrEnum):
134
+ """
135
+ The status check-setup.sh reports for a single check.
136
+ """
137
+
138
+ OK = "ok"
139
+ """
140
+ Nothing to do.
141
+ """
142
+
143
+ NEEDS_SETUP = "needs-setup"
144
+ """
145
+ Something still has to be set up.
146
+ """
147
+
148
+ IN_PROGRESS = "in-progress"
149
+ """
150
+ Another process is setting it up right now, so it is waited for rather than set up
151
+ again.
152
+ """
153
+
154
+ UNVERIFIED = "unverified"
155
+ """
156
+ Nothing the check could read decides it yet, so it is neither passed nor failed.
157
+ """
158
+
159
+ MISMATCHED = "mismatched"
160
+ """
161
+ The plugin's hooks and the package they call are not one release.
162
+ """
163
+
164
+ INFORMATIONAL = "info"
165
+ """
166
+ Context rather than a verdict.
167
+ """
168
+
169
+
170
+ class ReportRowField(StrEnum):
171
+ """
172
+ How one report row is laid out.
173
+ """
174
+
175
+ SEPARATOR = "\t"
176
+ """
177
+ What separates a row's check, status and detail.
178
+ """
179
+
180
+
181
+ class ReportRowPosition(IntEnum):
182
+ """
183
+ Where each field sits in one report row.
184
+ """
185
+
186
+ CHECK = 0
187
+ """
188
+ The check the row reports on.
189
+ """
190
+
191
+ STATUS = 1
192
+ """
193
+ The status it reports.
194
+ """
195
+
196
+ DETAIL = 2
197
+ """
198
+ The human-readable explanation.
199
+ """
200
+
201
+
202
+ @dataclass(frozen=True)
203
+ class CheckResult:
204
+ """
205
+ What check-setup.sh reported for one check.
206
+ """
207
+
208
+ status: CheckStatus
209
+ """
210
+ Whether the check passed, needs setup, or is context rather than a verdict.
211
+ """
212
+
213
+ detail: str
214
+ """
215
+ The human-readable explanation printed alongside the status.
216
+ """
217
+
218
+ @property
219
+ def fields(self) -> str:
220
+ """
221
+ :return: The status and the detail as a report row prints them after its
222
+ check.
223
+ """
224
+ return f"{self.status}{ReportRowField.SEPARATOR}{self.detail}"
225
+
226
+
227
+ @dataclass(frozen=True)
228
+ class SetupReport:
229
+ """
230
+ One parsed run of check-setup.sh: what it reported, and how it exited.
231
+ """
232
+
233
+ exit_code: SetupCheckExitCode
234
+ """
235
+ The status the script exited with.
236
+ """
237
+
238
+ results: dict[SetupCheck, CheckResult]
239
+ """
240
+ Every reported check, keyed by the check it reports on.
241
+ """
242
+
243
+ repository_results: list[CheckResult]
244
+ """
245
+ What each :class:`RepositoryCheck` row reported, in the order printed.
246
+ """
247
+
248
+ @classmethod
249
+ def from_completed_process(
250
+ cls,
251
+ process: subprocess.CompletedProcess[str],
252
+ requested_checks: frozenset[SetupCheck] = frozenset(SetupCheck),
253
+ ) -> SetupReport:
254
+ """
255
+ Parse a finished check-setup.sh run.
256
+
257
+ :param process: The finished check-setup.sh subprocess, its output captured.
258
+ :param requested_checks: The checks the run was asked to report on.
259
+ :return: The parsed report.
260
+ :raises CheckSetupFailedError: If the script exits with a status that carries no
261
+ report, a requested check has no row, or a row cannot be read.
262
+ """
263
+ results = {}
264
+ repository_results = []
265
+ unreadable_rows = []
266
+ for line in process.stdout.splitlines():
267
+ fields = line.split(ReportRowField.SEPARATOR)
268
+ if not cls.is_readable(fields):
269
+ unreadable_rows.append(line)
270
+ continue
271
+ check, status, detail = fields
272
+ result = CheckResult(CheckStatus(status), detail)
273
+ if check in RepositoryCheck:
274
+ repository_results.append(result)
275
+ else:
276
+ results[SetupCheck(check)] = result
277
+ missing_checks = [
278
+ check
279
+ for check in SetupCheck
280
+ if check in requested_checks and check not in results
281
+ ]
282
+ if (
283
+ process.returncode not in SetupCheckExitCode.reporting_statuses
284
+ or missing_checks
285
+ or unreadable_rows
286
+ ):
287
+ raise CheckSetupFailedError(
288
+ process.returncode, process.stderr, missing_checks, unreadable_rows
289
+ )
290
+ return cls(SetupCheckExitCode(process.returncode), results, repository_results)
291
+
292
+ @staticmethod
293
+ def is_readable(fields: list[str]) -> bool:
294
+ """
295
+ :param fields: One printed row, split at its separators.
296
+ :return: Whether the row holds a declared check, a declared status and a detail.
297
+ """
298
+ return (
299
+ len(fields) == len(ReportRowPosition)
300
+ and (
301
+ fields[ReportRowPosition.CHECK] in SetupCheck
302
+ or fields[ReportRowPosition.CHECK] in RepositoryCheck
303
+ )
304
+ and fields[ReportRowPosition.STATUS] in CheckStatus
305
+ )
306
+
307
+
308
+ # %% running the script
309
+
310
+
311
+ @dataclass(frozen=True)
312
+ class SetupCheckScript:
313
+ """
314
+ check-setup.sh as it runs against one clone.
315
+ """
316
+
317
+ project_root: Path
318
+ """
319
+ The clone it inspects.
320
+ """
321
+
322
+ environment: Mapping[str, str]
323
+ """
324
+ The environment it runs in.
325
+ """
326
+
327
+ plugin_root: PluginRoot
328
+ """
329
+ The plugin it belongs to.
330
+ """
331
+
332
+ def run(self, *arguments: str) -> subprocess.CompletedProcess[str]:
333
+ """
334
+ :param arguments: Its flags.
335
+ :return: The finished run, its report and standard error captured; a non-zero
336
+ status means only that something still needs setting up.
337
+ """
338
+ return subprocess.run(
339
+ Bash.locate(self.environment).command(
340
+ self.plugin_root.path_of(PluginLocation.SETUP_CHECK_SCRIPT), *arguments
341
+ ),
342
+ cwd=self.project_root,
343
+ env=dict(self.environment),
344
+ capture_output=True,
345
+ encoding="utf-8",
346
+ )