waymark-cli 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.
Files changed (92) hide show
  1. waymark/__init__.py +3 -0
  2. waymark/__main__.py +8 -0
  3. waymark/adapters/__init__.py +102 -0
  4. waymark/adapters/claude_code.py +238 -0
  5. waymark/assets/__init__.py +43 -0
  6. waymark/assets/agents/wm-implementer.md +45 -0
  7. waymark/assets/agents/wm-reviewer.md +43 -0
  8. waymark/assets/skills/wm-apply/SKILL.md +58 -0
  9. waymark/assets/skills/wm-archive/SKILL.md +32 -0
  10. waymark/assets/skills/wm-explore/SKILL.md +34 -0
  11. waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
  12. waymark/assets/skills/wm-onboard/SKILL.md +27 -0
  13. waymark/assets/skills/wm-pr/SKILL.md +24 -0
  14. waymark/assets/skills/wm-propose/SKILL.md +32 -0
  15. waymark/assets/skills/wm-update/SKILL.md +31 -0
  16. waymark/cli.py +537 -0
  17. waymark/hooks/__init__.py +6 -0
  18. waymark/hooks/commands.py +190 -0
  19. waymark/hooks/decide.py +314 -0
  20. waymark/hooks/events.py +79 -0
  21. waymark/py.typed +0 -0
  22. waymark/record/__init__.py +5 -0
  23. waymark/record/atlas.py +156 -0
  24. waymark/record/changes.py +202 -0
  25. waymark/record/charter.py +75 -0
  26. waymark/record/commits.py +78 -0
  27. waymark/record/config.py +215 -0
  28. waymark/record/deltas.py +318 -0
  29. waymark/record/design.py +80 -0
  30. waymark/record/edits.py +95 -0
  31. waymark/record/evidence.py +58 -0
  32. waymark/record/explorations.py +66 -0
  33. waymark/record/files.py +75 -0
  34. waymark/record/fingerprint.py +73 -0
  35. waymark/record/git.py +167 -0
  36. waymark/record/githooks.py +106 -0
  37. waymark/record/links.py +104 -0
  38. waymark/record/milestones.py +84 -0
  39. waymark/record/moves.py +60 -0
  40. waymark/record/names.py +39 -0
  41. waymark/record/outline.py +144 -0
  42. waymark/record/pointer.py +56 -0
  43. waymark/record/problems.py +20 -0
  44. waymark/record/project.py +118 -0
  45. waymark/record/proposal.py +171 -0
  46. waymark/record/record.py +340 -0
  47. waymark/record/registry.py +158 -0
  48. waymark/record/specs.py +227 -0
  49. waymark/record/state.py +472 -0
  50. waymark/record/store.py +88 -0
  51. waymark/record/tasks.py +415 -0
  52. waymark/record/templates/charter.md +45 -0
  53. waymark/record/templates/ci-workflow.yml +29 -0
  54. waymark/record/templates/config-atlas.toml +8 -0
  55. waymark/record/templates/config.toml +19 -0
  56. waymark/record/templates/delta.md +29 -0
  57. waymark/record/templates/design.md +20 -0
  58. waymark/record/templates/exploration.md +22 -0
  59. waymark/record/templates/goal.md +13 -0
  60. waymark/record/templates/hook-commit-msg +8 -0
  61. waymark/record/templates/hook-pre-commit +8 -0
  62. waymark/record/templates/proposal.md +18 -0
  63. waymark/record/templates/roadmap.md +4 -0
  64. waymark/record/templates/tasks.md +10 -0
  65. waymark/record/templates.py +30 -0
  66. waymark/record/terms.py +51 -0
  67. waymark/record/text.py +197 -0
  68. waymark/services/__init__.py +1 -0
  69. waymark/services/atlas.py +162 -0
  70. waymark/services/check.py +129 -0
  71. waymark/services/ci.py +44 -0
  72. waymark/services/common.py +154 -0
  73. waymark/services/context.py +296 -0
  74. waymark/services/doctor.py +367 -0
  75. waymark/services/githooks.py +132 -0
  76. waymark/services/instructions.py +304 -0
  77. waymark/services/integration.py +170 -0
  78. waymark/services/lifecycle.py +454 -0
  79. waymark/services/migrations.py +90 -0
  80. waymark/services/pr.py +177 -0
  81. waymark/services/references.py +27 -0
  82. waymark/services/setup.py +127 -0
  83. waymark/views/__init__.py +5 -0
  84. waymark/views/payloads.py +568 -0
  85. waymark/views/render.py +506 -0
  86. waymark/views/schemas.py +413 -0
  87. waymark/views/style.py +102 -0
  88. waymark_cli-0.1.0.dist-info/METADATA +313 -0
  89. waymark_cli-0.1.0.dist-info/RECORD +92 -0
  90. waymark_cli-0.1.0.dist-info/WHEEL +4 -0
  91. waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
  92. waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,568 @@
1
+ """The data behind every view: plain payloads built from the record and its state.
2
+
3
+ A payload holds only JSON types. It carries its schema's name and version.
4
+ What it reads from this machine rather than the record (wm's own version,
5
+ the branches checked out in an atlas's repos, what the doctors find) is
6
+ named for what it is. Values that would put an absolute path in the JSON,
7
+ such as a repo's folder, sit under keys starting with an underscore: the
8
+ text views show them, and the JSON leaves them out.
9
+ """
10
+
11
+ import datetime
12
+ from pathlib import Path
13
+ from typing import TYPE_CHECKING, Any
14
+
15
+ from waymark import __version__
16
+ from waymark.record import git
17
+ from waymark.record.atlas import Location
18
+ from waymark.record.changes import Change
19
+ from waymark.record.config import RECORD_FORMAT
20
+ from waymark.record.explorations import QUESTIONS, Exploration
21
+ from waymark.record.githooks import hooks_status
22
+ from waymark.record.milestones import Milestone
23
+ from waymark.record.record import (
24
+ ArchiveEntry,
25
+ Record,
26
+ load_archived_change,
27
+ spec_history,
28
+ )
29
+ from waymark.record.specs import Spec
30
+ from waymark.record.state import (
31
+ AcceptanceState,
32
+ ChangeState,
33
+ Conflict,
34
+ ConflictKind,
35
+ ExplorationStatus,
36
+ RecordState,
37
+ StepKind,
38
+ change_state,
39
+ derive_state,
40
+ exploration_state,
41
+ milestone_state,
42
+ overlaps,
43
+ )
44
+ from waymark.record.tasks import Item
45
+ from waymark.record.terms import Layout, Verdict
46
+ from waymark.services.check import Finding, Severity, check_record
47
+ from waymark.services.common import Refusal, repo_locations
48
+ from waymark.services.context import CONTEXT_VERSION
49
+
50
+ if TYPE_CHECKING: # the doctor's checks reach the views through the CLI; no import cycle
51
+ from waymark.services.doctor import Report
52
+ from waymark.services.instructions import INSTRUCTIONS_VERSION
53
+ from waymark.services.pr import PR_VERSION
54
+
55
+ Payload = dict[str, Any]
56
+
57
+ VERSIONS = {
58
+ "status": 1,
59
+ "inbox": 1,
60
+ "ls": 1,
61
+ "check": 1,
62
+ "show.change": 1,
63
+ "show.spec": 1,
64
+ "show.milestone": 1,
65
+ "show.exploration": 1,
66
+ "instructions": INSTRUCTIONS_VERSION,
67
+ "context.explore": CONTEXT_VERSION,
68
+ "context.implement": CONTEXT_VERSION,
69
+ "context.review": CONTEXT_VERSION,
70
+ "doctor": 1,
71
+ "pr": PR_VERSION,
72
+ }
73
+ """The schema version of each payload. A breaking change to a payload bumps its number."""
74
+
75
+ KINDS = ("change", "spec", "milestone", "exploration")
76
+ RECENT = 5
77
+
78
+
79
+ def _header(name: str) -> Payload:
80
+ return {"schema": f"wm.{name}", "version": VERSIONS[name]}
81
+
82
+
83
+ def _conflict(conflict: Conflict) -> Payload:
84
+ return {
85
+ "kind": conflict.kind.value,
86
+ "spec": conflict.domain,
87
+ "requirement": conflict.requirement,
88
+ "changes": list(conflict.changes),
89
+ "message": conflict.message,
90
+ }
91
+
92
+
93
+ class _Branches:
94
+ """The branch checked out in each repo of an atlas, read once per view."""
95
+
96
+ def __init__(self, record: Record) -> None:
97
+ self.record = record
98
+ config = record.config
99
+ atlas = record.layout is Layout.ATLAS and config is not None
100
+ self.atlas = config.atlas_name if atlas and config else None
101
+ self.locations: dict[str, Location] = repo_locations(record) if self.atlas else {}
102
+ self._seen: dict[Path, str | None] = {}
103
+
104
+ def _branch(self, folder: Path) -> str | None:
105
+ if folder not in self._seen:
106
+ self._seen[folder] = git.current_branch(folder)
107
+ return self._seen[folder]
108
+
109
+ def of(self, change: Change, state: ChangeState) -> list[Payload]:
110
+ """Each repo a change touches, with its branch; a mismatch warns while it is applied."""
111
+ if self.atlas is None:
112
+ return []
113
+ touched = sorted(
114
+ {item.repo for item in change.tasks.items if item.repo} if change.tasks else ()
115
+ )
116
+ building = state.acceptance is AcceptanceState.VALID and not state.applied
117
+ places: list[tuple[str, str, Path | None]] = [
118
+ ("atlas", self.atlas, self.record.project.root)
119
+ ]
120
+ for repo in touched:
121
+ location = self.locations.get(repo)
122
+ places.append(("code", repo, location.folder if location else None))
123
+ entries = []
124
+ for kind, name, folder in places:
125
+ branch = self._branch(folder) if folder is not None else None
126
+ matches = branch == change.name
127
+ entries.append(
128
+ {
129
+ "name": name,
130
+ "kind": kind,
131
+ "found": folder is not None,
132
+ "branch": branch,
133
+ "matches": matches,
134
+ "warn": building and folder is not None and not matches,
135
+ }
136
+ )
137
+ return entries
138
+
139
+
140
+ def _change_summary(state: ChangeState, repos: list[Payload] | None = None) -> Payload:
141
+ step = state.next_step
142
+ return {
143
+ "name": state.name,
144
+ "owner": state.owner,
145
+ "phase": state.phase.value,
146
+ "short_path": state.short_path,
147
+ "acceptance": state.acceptance.value,
148
+ "ticked": state.ticked,
149
+ "total": state.total,
150
+ "next_step": {
151
+ "kind": step.kind.value,
152
+ "item": step.item,
153
+ "human": step.human,
154
+ "reason": step.reason,
155
+ },
156
+ "conflicts": [_conflict(conflict) for conflict in state.conflicts],
157
+ "repos": repos or [],
158
+ }
159
+
160
+
161
+ def _entry(kind: str, summary: str, **fields: str | None) -> Payload:
162
+ base: Payload = {"kind": kind, "change": None, "item": None, "exploration": None}
163
+ return {**base, **fields, "summary": summary}
164
+
165
+
166
+ def _item_entries(name: str, change: Change, state: ChangeState) -> list[Payload]:
167
+ entries: list[Payload] = []
168
+ items = {item.number: item for item in (change.tasks.items if change.tasks else ())}
169
+ command = f'wm resolve {name} {{}} "<what was decided>"'
170
+ for item_state in state.items:
171
+ item = items[item_state.number]
172
+ last = item.records[-1] if item.records else None
173
+ number = item.number
174
+ if item_state.escalated:
175
+ gap = item.spec_gap is not None or (last and last.verdict is Verdict.SPEC_GAP)
176
+ entries.append(
177
+ _entry(
178
+ "spec-gap" if gap else "verdict",
179
+ item_state.escalated,
180
+ change=name,
181
+ item=number,
182
+ command=command.format(number),
183
+ )
184
+ )
185
+ elif item.blocked and not item.ticked:
186
+ entries.append(
187
+ _entry(
188
+ "blocked",
189
+ item.blocked,
190
+ change=name,
191
+ item=number,
192
+ command=command.format(number),
193
+ )
194
+ )
195
+ return entries
196
+
197
+
198
+ _INBOX_ORDER = ("accept", "spec-gap", "verdict", "blocked", "conflict", "archive", "question")
199
+
200
+
201
+ def inbox_entries(record: Record, state: RecordState) -> list[Payload]:
202
+ """Everything only the human can resolve, most pressing kind first."""
203
+ entries: list[Payload] = []
204
+ for name in sorted(state.changes):
205
+ change_state_ = state.changes[name]
206
+ step = change_state_.next_step
207
+ if step.kind is StepKind.ACCEPT:
208
+ again = change_state_.acceptance is AcceptanceState.WITHDRAWN
209
+ summary = f"Accept again: {step.reason}" if again else "Ready to accept."
210
+ entries.append(_entry("accept", summary, change=name, command=f"wm accept {name}"))
211
+ if step.kind is StepKind.ARCHIVE:
212
+ command = f'wm archive {name} --outcome "<what came of it>"'
213
+ entries.append(
214
+ _entry("archive", "Applied; ready to archive.", change=name, command=command)
215
+ )
216
+ entries.extend(
217
+ _entry("conflict", conflict.message, change=name, command=None)
218
+ for conflict in change_state_.conflicts
219
+ if conflict.kind is ConflictKind.MISMATCH
220
+ )
221
+ entries.extend(_item_entries(name, record.changes[name], change_state_))
222
+ for name in sorted(state.explorations):
223
+ questions = record.explorations[name].sections[QUESTIONS]
224
+ if state.explorations[name].status is ExplorationStatus.OPEN and questions:
225
+ entries.append(_entry("question", questions, exploration=name, command=None))
226
+ return sorted(entries, key=lambda entry: _INBOX_ORDER.index(entry["kind"]))
227
+
228
+
229
+ def _writable(record: Record) -> bool:
230
+ config = record.config
231
+ return (
232
+ config is not None
233
+ and config.wm_version == __version__
234
+ and config.record_format == RECORD_FORMAT
235
+ )
236
+
237
+
238
+ def status(record: Record) -> Payload:
239
+ """Where things stand: changes in flight, milestones, what needs the human."""
240
+ state = derive_state(record)
241
+ config = record.config
242
+ milestones = []
243
+ for name in sorted(state.milestones):
244
+ milestone = state.milestones[name]
245
+ planned = len(milestone.lines) - milestone.total
246
+ milestones.append(
247
+ {
248
+ "name": name,
249
+ "archived": milestone.archived,
250
+ "total": milestone.total,
251
+ "planned": planned,
252
+ }
253
+ )
254
+ recent = sorted(record.archived_changes, reverse=True)[:RECENT]
255
+ branches = _Branches(record)
256
+ return {
257
+ **_header("status"),
258
+ "layout": record.layout.value,
259
+ "atlas": config.atlas_name if config else None,
260
+ "wm_version": __version__,
261
+ "pinned_version": config.wm_version if config else None,
262
+ "writable": _writable(record),
263
+ "changes": [
264
+ _change_summary(
265
+ state.changes[name], branches.of(record.changes[name], state.changes[name])
266
+ )
267
+ for name in sorted(state.changes)
268
+ ],
269
+ "milestones": milestones,
270
+ "needs_human": len(inbox_entries(record, state)),
271
+ "recently_archived": [
272
+ {"name": entry.name, "date": entry.date.isoformat()} for entry in recent
273
+ ],
274
+ "problems": len(record.problems),
275
+ "git_hooks": hooks_status(record.project.root).state.value,
276
+ }
277
+
278
+
279
+ def inbox(record: Record) -> Payload:
280
+ """What only the human can resolve."""
281
+ return {**_header("inbox"), "entries": inbox_entries(record, derive_state(record))}
282
+
283
+
284
+ def _finding(finding: Finding) -> Payload:
285
+ return {
286
+ "severity": finding.severity.value,
287
+ "path": finding.path,
288
+ "line": finding.line,
289
+ "code": finding.code,
290
+ "message": finding.message,
291
+ }
292
+
293
+
294
+ def check(record: Record, now: datetime.datetime) -> Payload:
295
+ """The health check's findings."""
296
+ findings = check_record(record, now)
297
+ errors = sum(1 for finding in findings if finding.severity is Severity.ERROR)
298
+ return {
299
+ **_header("check"),
300
+ "findings": [_finding(finding) for finding in findings],
301
+ "errors": errors,
302
+ "warnings": len(findings) - errors,
303
+ }
304
+
305
+
306
+ def _ls_changes(record: Record, state: RecordState, archived: bool) -> list[Payload]:
307
+ entries = []
308
+ for name in sorted(state.changes):
309
+ change = state.changes[name]
310
+ detail = f"{change.ticked}/{change.total} items; next: {change.next_step.kind.value}"
311
+ entries.append({"name": name, "state": change.phase.value, "detail": detail})
312
+ if archived:
313
+ entries.extend(
314
+ {"name": entry.name, "state": "archived", "detail": entry.date.isoformat()}
315
+ for entry in sorted(record.archived_changes, reverse=True)
316
+ )
317
+ return entries
318
+
319
+
320
+ def _ls_specs(record: Record) -> list[Payload]:
321
+ entries = []
322
+ for name in sorted(record.specs):
323
+ pending = sum(1 for change in record.changes.values() if name in change.deltas)
324
+ count = len(record.specs[name].requirements)
325
+ detail = f"{count} requirement{'s' if count != 1 else ''}"
326
+ if pending:
327
+ detail += f"; {pending} pending change{'s' if pending != 1 else ''}"
328
+ entries.append({"name": name, "state": "living", "detail": detail})
329
+ return entries
330
+
331
+
332
+ def ls(record: Record, kind: str, *, archived: bool = False, source: str | None = None) -> Payload:
333
+ """One entry per change, spec, milestone or exploration, with its state.
334
+
335
+ ``source`` names the referenced atlas the record was read from, if any.
336
+ """
337
+ state = derive_state(record)
338
+ entries: list[Payload]
339
+ if kind == "change":
340
+ entries = _ls_changes(record, state, archived)
341
+ elif kind == "spec":
342
+ entries = _ls_specs(record)
343
+ elif kind == "milestone":
344
+ entries = [
345
+ {
346
+ "name": name,
347
+ "state": "open",
348
+ "detail": f"{milestone.archived}/{milestone.total} changes archived",
349
+ }
350
+ for name, milestone in sorted(state.milestones.items())
351
+ ]
352
+ if archived:
353
+ entries.extend(
354
+ {"name": entry.name, "state": "closed", "detail": entry.date.isoformat()}
355
+ for entry in sorted(record.archived_milestones, reverse=True)
356
+ )
357
+ else:
358
+ entries = [
359
+ {"name": name, "state": exploration.status.value, "detail": exploration.detail or ""}
360
+ for name, exploration in sorted(state.explorations.items())
361
+ ]
362
+ return {**_header("ls"), "kind": kind, "from": source, "entries": entries}
363
+
364
+
365
+ def _item(item: Item, state: ChangeState | None) -> Payload:
366
+ item_state = next((i for i in state.items if i.number == item.number), None) if state else None
367
+ return {
368
+ "number": item.number,
369
+ "title": item.title,
370
+ "ticked": item.ticked,
371
+ "level": item_state.level.value if item_state else None,
372
+ "reviewed": item_state.reviewed if item_state else None,
373
+ "needs_human": item_state.escalated if item_state else None,
374
+ "criteria": item.criteria,
375
+ "verify": item.verify,
376
+ "repo": item.repo,
377
+ "blocked": item.blocked,
378
+ "spec_gap": item.spec_gap,
379
+ "notes": list(item.notes),
380
+ "records": [
381
+ {
382
+ "kind": record.kind.value,
383
+ "date": record.date.isoformat(),
384
+ "verdict": record.verdict.value if record.verdict else None,
385
+ "text": record.text,
386
+ }
387
+ for record in item.records
388
+ ],
389
+ }
390
+
391
+
392
+ def show_change(record: Record, change: Change) -> Payload:
393
+ """Everything about one change, active or archived."""
394
+ active = change.archived_on is None
395
+ state = change_state(record, change, overlaps(record)) if active else None
396
+ proposal = change.proposal
397
+ return {
398
+ **_header("show.change"),
399
+ "name": change.name,
400
+ "path": change.path,
401
+ "archived_on": change.archived_on.isoformat() if change.archived_on else None,
402
+ "title": proposal.title if proposal else None,
403
+ "state": _change_summary(state, _Branches(record).of(change, state)) if state else None,
404
+ "owner": proposal.owner if proposal else None,
405
+ "accepted": (
406
+ {"date": proposal.acceptance.date.isoformat(), "by": proposal.acceptance.who}
407
+ if proposal and proposal.acceptance
408
+ else None
409
+ ),
410
+ "synced_on": proposal.synced.isoformat() if proposal and proposal.synced else None,
411
+ "proposal": dict(proposal.sections) if proposal else None,
412
+ "outcome": proposal.outcome if proposal else None,
413
+ "deltas": [
414
+ {
415
+ "spec": domain,
416
+ "added": [item.name for item in delta.added],
417
+ "modified": [item.name for item in delta.modified],
418
+ "removed": [item.name for item in delta.removed],
419
+ }
420
+ for domain, delta in sorted(change.deltas.items())
421
+ ],
422
+ "design": (
423
+ {"decisions": [decision.name for decision in change.design.decisions]}
424
+ if change.design
425
+ else None
426
+ ),
427
+ "items": [_item(item, state) for item in (change.tasks.items if change.tasks else ())],
428
+ "problems": [
429
+ {"path": p.path, "line": p.line, "code": p.code, "message": p.message}
430
+ for p in change.problems
431
+ ],
432
+ }
433
+
434
+
435
+ def show_spec(record: Record, spec: Spec, source: str | None = None) -> Payload:
436
+ """A spec, the deltas waiting for it, and its history from the archive.
437
+
438
+ ``source`` names the referenced atlas the spec was read from, if any.
439
+ """
440
+ pending = []
441
+ for name in sorted(record.changes):
442
+ delta = record.changes[name].deltas.get(spec.domain)
443
+ if delta is not None:
444
+ pending.append(
445
+ {
446
+ "change": name,
447
+ "added": [item.name for item in delta.added],
448
+ "modified": [item.name for item in delta.modified],
449
+ "removed": [item.name for item in delta.removed],
450
+ }
451
+ )
452
+ return {
453
+ **_header("show.spec"),
454
+ "from": source,
455
+ "name": spec.domain,
456
+ "title": spec.title,
457
+ "purpose": spec.purpose,
458
+ "repos": list(spec.repos),
459
+ "requirements": [
460
+ {
461
+ "name": requirement.name,
462
+ "statement": requirement.statement,
463
+ "scenarios": [
464
+ {
465
+ "name": scenario.name,
466
+ "steps": [
467
+ {"keyword": keyword, "text": text} for keyword, text in scenario.steps
468
+ ],
469
+ }
470
+ for scenario in requirement.scenarios
471
+ ],
472
+ }
473
+ for requirement in spec.requirements
474
+ ],
475
+ "pending": pending,
476
+ "history": [
477
+ {"date": entry.date.isoformat(), "change": entry.change, "outcome": entry.outcome}
478
+ for entry in spec_history(record, spec.domain)
479
+ ],
480
+ }
481
+
482
+
483
+ def show_milestone(record: Record, milestone: Milestone) -> Payload:
484
+ """A milestone's goal and where each roadmap line stands."""
485
+ state = milestone_state(record, milestone)
486
+ return {
487
+ **_header("show.milestone"),
488
+ "name": milestone.name,
489
+ "title": milestone.goal.title if milestone.goal else None,
490
+ "goal": dict(milestone.goal.sections) if milestone.goal else None,
491
+ "lines": [
492
+ {"text": line.text, "change": line.change, "status": line.status.value}
493
+ for line in state.lines
494
+ ],
495
+ "archived": state.archived,
496
+ "total": state.total,
497
+ }
498
+
499
+
500
+ def show_exploration(record: Record, exploration: Exploration) -> Payload:
501
+ """An exploration and where it went."""
502
+ state = exploration_state(record, exploration)
503
+ return {
504
+ **_header("show.exploration"),
505
+ "name": exploration.name,
506
+ "title": exploration.title,
507
+ "status": state.status.value,
508
+ "detail": state.detail,
509
+ "sections": dict(exploration.sections),
510
+ }
511
+
512
+
513
+ def _archived(record: Record, name: str) -> ArchiveEntry | None:
514
+ matches = [
515
+ entry
516
+ for entry in record.archived_changes
517
+ if name in (entry.name, entry.path.rsplit("/", 1)[-1])
518
+ ]
519
+ return max(matches) if matches else None
520
+
521
+
522
+ def show(record: Record, name: str, kind: str | None = None) -> Payload:
523
+ """Everything about the one thing a name refers to.
524
+
525
+ A name used by more than one kind needs ``kind`` to say which. An archived
526
+ change is found by its name (the latest one) or by its dated folder name.
527
+ """
528
+ found: dict[str, Payload] = {}
529
+ if kind in (None, "change"):
530
+ archived = _archived(record, name)
531
+ if name in record.changes:
532
+ found["change"] = show_change(record, record.changes[name])
533
+ elif archived is not None:
534
+ found["change"] = show_change(record, load_archived_change(record, archived))
535
+ if kind in (None, "spec") and name in record.specs:
536
+ found["spec"] = show_spec(record, record.specs[name])
537
+ if kind in (None, "milestone") and name in record.milestones:
538
+ found["milestone"] = show_milestone(record, record.milestones[name])
539
+ if kind in (None, "exploration") and name in record.explorations:
540
+ found["exploration"] = show_exploration(record, record.explorations[name])
541
+ if not found:
542
+ what = f"{kind} named" if kind else "change, spec, milestone or exploration named"
543
+ raise Refusal(f'There is no {what} "{name}". List what there is with "wm ls <kind>".')
544
+ if len(found) > 1:
545
+ kinds = " and ".join(found)
546
+ raise Refusal(
547
+ f'"{name}" is the name of a {kinds}. Say which one: '
548
+ f"wm show {name} --kind {next(iter(found))}"
549
+ )
550
+ return next(iter(found.values()))
551
+
552
+
553
+ def doctor(report: "Report") -> Payload:
554
+ """What a doctor found on this machine. Each check's folder is shown in text only."""
555
+ return {
556
+ **_header("doctor"),
557
+ "scope": report.scope,
558
+ "ok": not report.failed,
559
+ "checks": [
560
+ {
561
+ "name": check.name,
562
+ "status": check.status.value,
563
+ "message": check.message,
564
+ "_folder": str(check.folder) if check.folder is not None else None,
565
+ }
566
+ for check in report.checks
567
+ ],
568
+ }