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.
- waymark/__init__.py +3 -0
- waymark/__main__.py +8 -0
- waymark/adapters/__init__.py +102 -0
- waymark/adapters/claude_code.py +238 -0
- waymark/assets/__init__.py +43 -0
- waymark/assets/agents/wm-implementer.md +45 -0
- waymark/assets/agents/wm-reviewer.md +43 -0
- waymark/assets/skills/wm-apply/SKILL.md +58 -0
- waymark/assets/skills/wm-archive/SKILL.md +32 -0
- waymark/assets/skills/wm-explore/SKILL.md +34 -0
- waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
- waymark/assets/skills/wm-onboard/SKILL.md +27 -0
- waymark/assets/skills/wm-pr/SKILL.md +24 -0
- waymark/assets/skills/wm-propose/SKILL.md +32 -0
- waymark/assets/skills/wm-update/SKILL.md +31 -0
- waymark/cli.py +537 -0
- waymark/hooks/__init__.py +6 -0
- waymark/hooks/commands.py +190 -0
- waymark/hooks/decide.py +314 -0
- waymark/hooks/events.py +79 -0
- waymark/py.typed +0 -0
- waymark/record/__init__.py +5 -0
- waymark/record/atlas.py +156 -0
- waymark/record/changes.py +202 -0
- waymark/record/charter.py +75 -0
- waymark/record/commits.py +78 -0
- waymark/record/config.py +215 -0
- waymark/record/deltas.py +318 -0
- waymark/record/design.py +80 -0
- waymark/record/edits.py +95 -0
- waymark/record/evidence.py +58 -0
- waymark/record/explorations.py +66 -0
- waymark/record/files.py +75 -0
- waymark/record/fingerprint.py +73 -0
- waymark/record/git.py +167 -0
- waymark/record/githooks.py +106 -0
- waymark/record/links.py +104 -0
- waymark/record/milestones.py +84 -0
- waymark/record/moves.py +60 -0
- waymark/record/names.py +39 -0
- waymark/record/outline.py +144 -0
- waymark/record/pointer.py +56 -0
- waymark/record/problems.py +20 -0
- waymark/record/project.py +118 -0
- waymark/record/proposal.py +171 -0
- waymark/record/record.py +340 -0
- waymark/record/registry.py +158 -0
- waymark/record/specs.py +227 -0
- waymark/record/state.py +472 -0
- waymark/record/store.py +88 -0
- waymark/record/tasks.py +415 -0
- waymark/record/templates/charter.md +45 -0
- waymark/record/templates/ci-workflow.yml +29 -0
- waymark/record/templates/config-atlas.toml +8 -0
- waymark/record/templates/config.toml +19 -0
- waymark/record/templates/delta.md +29 -0
- waymark/record/templates/design.md +20 -0
- waymark/record/templates/exploration.md +22 -0
- waymark/record/templates/goal.md +13 -0
- waymark/record/templates/hook-commit-msg +8 -0
- waymark/record/templates/hook-pre-commit +8 -0
- waymark/record/templates/proposal.md +18 -0
- waymark/record/templates/roadmap.md +4 -0
- waymark/record/templates/tasks.md +10 -0
- waymark/record/templates.py +30 -0
- waymark/record/terms.py +51 -0
- waymark/record/text.py +197 -0
- waymark/services/__init__.py +1 -0
- waymark/services/atlas.py +162 -0
- waymark/services/check.py +129 -0
- waymark/services/ci.py +44 -0
- waymark/services/common.py +154 -0
- waymark/services/context.py +296 -0
- waymark/services/doctor.py +367 -0
- waymark/services/githooks.py +132 -0
- waymark/services/instructions.py +304 -0
- waymark/services/integration.py +170 -0
- waymark/services/lifecycle.py +454 -0
- waymark/services/migrations.py +90 -0
- waymark/services/pr.py +177 -0
- waymark/services/references.py +27 -0
- waymark/services/setup.py +127 -0
- waymark/views/__init__.py +5 -0
- waymark/views/payloads.py +568 -0
- waymark/views/render.py +506 -0
- waymark/views/schemas.py +413 -0
- waymark/views/style.py +102 -0
- waymark_cli-0.1.0.dist-info/METADATA +313 -0
- waymark_cli-0.1.0.dist-info/RECORD +92 -0
- waymark_cli-0.1.0.dist-info/WHEEL +4 -0
- waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
- waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Written by wm (Waymark): checks that the commit message is a conventional commit.
|
|
3
|
+
# Regenerate it with "wm git-hooks". It warns, and lets the commit through, without wm.
|
|
4
|
+
if command -v wm >/dev/null 2>&1; then
|
|
5
|
+
exec wm run-hook commit-msg "$1"
|
|
6
|
+
fi
|
|
7
|
+
echo "Waymark: wm is not on PATH, so this commit message was not checked. Install it: pipx install waymark-cli" >&2
|
|
8
|
+
exit 0
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Written by wm (Waymark): runs "wm check" when a commit changes the record.
|
|
3
|
+
# Regenerate it with "wm git-hooks". It warns, and lets the commit through, without wm.
|
|
4
|
+
if command -v wm >/dev/null 2>&1; then
|
|
5
|
+
exec wm run-hook pre-commit
|
|
6
|
+
fi
|
|
7
|
+
echo "Waymark: wm is not on PATH, so the record was not checked. Install it: pipx install waymark-cli" >&2
|
|
8
|
+
exit 0
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# {{title}}
|
|
2
|
+
|
|
3
|
+
{{facts}}
|
|
4
|
+
## Why
|
|
5
|
+
|
|
6
|
+
<!-- The problem or opportunity, and why now. -->
|
|
7
|
+
|
|
8
|
+
## What changes
|
|
9
|
+
|
|
10
|
+
<!-- What will be different once this change is archived. -->
|
|
11
|
+
|
|
12
|
+
## Non-goals
|
|
13
|
+
|
|
14
|
+
<!-- What this change deliberately does not do. -->
|
|
15
|
+
|
|
16
|
+
## Impact
|
|
17
|
+
|
|
18
|
+
<!-- The specs this change touches, or "No spec changes". In an atlas, also the repos. -->
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Tasks
|
|
2
|
+
|
|
3
|
+
## 1. <Section title>
|
|
4
|
+
|
|
5
|
+
- [ ] 1.1 <What to build>
|
|
6
|
+
- Criteria: <what must be true when it is done>
|
|
7
|
+
- Verify: <how to check it>
|
|
8
|
+
- [ ] 1.2 <What to build> `review: independent`
|
|
9
|
+
- Criteria: <what must be true when it is done>
|
|
10
|
+
- Verify: <how to check it>
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""The built-in templates. A project contains no template files; wm carries them."""
|
|
2
|
+
|
|
3
|
+
from importlib import resources
|
|
4
|
+
|
|
5
|
+
CONFIG = "config.toml"
|
|
6
|
+
ATLAS_CONFIG = "config-atlas.toml"
|
|
7
|
+
CHARTER = "charter.md"
|
|
8
|
+
PROPOSAL = "proposal.md"
|
|
9
|
+
GOAL = "goal.md"
|
|
10
|
+
ROADMAP = "roadmap.md"
|
|
11
|
+
EXPLORATION = "exploration.md"
|
|
12
|
+
DELTA = "delta.md"
|
|
13
|
+
DESIGN = "design.md"
|
|
14
|
+
TASKS = "tasks.md"
|
|
15
|
+
CI_WORKFLOW = "ci-workflow.yml"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def render(name: str, **values: str) -> str:
|
|
19
|
+
"""A template's text with its ``{{placeholders}}`` filled in."""
|
|
20
|
+
source = resources.files("waymark.record").joinpath("templates", name)
|
|
21
|
+
text = source.read_text(encoding="utf-8")
|
|
22
|
+
for key, value in values.items():
|
|
23
|
+
text = text.replace("{{" + key + "}}", value)
|
|
24
|
+
assert "{{" not in text, f"template {name} has an unfilled placeholder"
|
|
25
|
+
return text
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def title_from_name(name: str) -> str:
|
|
29
|
+
"""A readable title for a kebab-case name."""
|
|
30
|
+
return name.replace("-", " ").capitalize()
|
waymark/record/terms.py
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""The fixed vocabulary of the record: levels, verdicts, steps and phases."""
|
|
2
|
+
|
|
3
|
+
from enum import StrEnum
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Layout(StrEnum):
|
|
7
|
+
"""Where the record lives."""
|
|
8
|
+
|
|
9
|
+
REPO = "repo"
|
|
10
|
+
ATLAS = "atlas"
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class ReviewLevel(StrEnum):
|
|
14
|
+
"""How a task item is checked."""
|
|
15
|
+
|
|
16
|
+
SELF = "self"
|
|
17
|
+
INDEPENDENT = "independent"
|
|
18
|
+
NONE = "none"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Verdict(StrEnum):
|
|
22
|
+
"""What a reviewer concluded about a task item."""
|
|
23
|
+
|
|
24
|
+
PASS = "pass"
|
|
25
|
+
CHANGES = "changes"
|
|
26
|
+
SPEC_GAP = "spec-gap"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class Step(StrEnum):
|
|
30
|
+
"""A workflow step an agent works in; the charter holds rules for each."""
|
|
31
|
+
|
|
32
|
+
EXPLORE = "explore"
|
|
33
|
+
PROPOSE = "propose"
|
|
34
|
+
SPECS = "specs"
|
|
35
|
+
DESIGN = "design"
|
|
36
|
+
TASKS = "tasks"
|
|
37
|
+
APPLY = "apply"
|
|
38
|
+
REVIEW = "review"
|
|
39
|
+
ARCHIVE = "archive"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class Phase(StrEnum):
|
|
43
|
+
"""How far an active change has come."""
|
|
44
|
+
|
|
45
|
+
PROPOSED = "proposed"
|
|
46
|
+
SPECIFIED = "specified"
|
|
47
|
+
DESIGNED = "designed"
|
|
48
|
+
PLANNED = "planned"
|
|
49
|
+
ACCEPTED = "accepted"
|
|
50
|
+
APPLYING = "applying"
|
|
51
|
+
APPLIED = "applied"
|
waymark/record/text.py
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
"""Markdown as wm reads it: lines with their endings, fences, headings, sections, links.
|
|
2
|
+
|
|
3
|
+
A document keeps every line's text and line ending apart, so a later write can
|
|
4
|
+
change the lines it owns and put everything else back byte for byte.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
|
|
10
|
+
BOM = ""
|
|
11
|
+
|
|
12
|
+
_LINE_BREAK = re.compile(r"\r\n|\n|\r")
|
|
13
|
+
_FENCE = re.compile(r"^\s*(`{3,}|~{3,})")
|
|
14
|
+
_HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.*?)[ \t]*$")
|
|
15
|
+
_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
|
|
16
|
+
_CODE_SPAN = re.compile(r"(`+).+?\1")
|
|
17
|
+
_INLINE_LINK = re.compile(r"\]\(\s*<?([^()\s<>]+)>?(?:\s+\"[^\"]*\")?\s*\)")
|
|
18
|
+
_REFERENCE_LINK = re.compile(r"^ {0,3}\[[^\]^][^\]]*\]:\s*<?([^\s<>]+)>?")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class Line:
|
|
23
|
+
"""One line: its text, its line ending, and whether it is inside a code fence."""
|
|
24
|
+
|
|
25
|
+
text: str
|
|
26
|
+
ending: str
|
|
27
|
+
in_fence: bool
|
|
28
|
+
|
|
29
|
+
@property
|
|
30
|
+
def is_blank(self) -> bool:
|
|
31
|
+
return not self.text.strip()
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class Heading:
|
|
36
|
+
"""A heading: its level, its title, and the index of its line."""
|
|
37
|
+
|
|
38
|
+
level: int
|
|
39
|
+
title: str
|
|
40
|
+
index: int
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass(frozen=True)
|
|
44
|
+
class Section:
|
|
45
|
+
"""A heading and the lines under it, up to the next heading of its level or above."""
|
|
46
|
+
|
|
47
|
+
heading: Heading
|
|
48
|
+
end: int
|
|
49
|
+
|
|
50
|
+
@property
|
|
51
|
+
def title(self) -> str:
|
|
52
|
+
return self.heading.title
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def start(self) -> int:
|
|
56
|
+
return self.heading.index
|
|
57
|
+
|
|
58
|
+
@property
|
|
59
|
+
def body_start(self) -> int:
|
|
60
|
+
return self.heading.index + 1
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass(frozen=True)
|
|
64
|
+
class Link:
|
|
65
|
+
"""A link target, with the line and the span where the target is written."""
|
|
66
|
+
|
|
67
|
+
index: int
|
|
68
|
+
start: int
|
|
69
|
+
end: int
|
|
70
|
+
target: str
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _track_fence(text: str, fence: str | None) -> tuple[bool, str | None]:
|
|
74
|
+
"""Whether a line is part of a code fence, and the fence still open after it."""
|
|
75
|
+
match = _FENCE.match(text)
|
|
76
|
+
if fence is None:
|
|
77
|
+
return (True, match.group(1)) if match else (False, None)
|
|
78
|
+
closes = (
|
|
79
|
+
match is not None
|
|
80
|
+
and match.group(1)[0] == fence[0]
|
|
81
|
+
and len(match.group(1)) >= len(fence)
|
|
82
|
+
and text.strip() == match.group(1)
|
|
83
|
+
)
|
|
84
|
+
return True, None if closes else fence
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass(frozen=True, eq=False)
|
|
88
|
+
class Document:
|
|
89
|
+
"""A markdown file, split into lines and outlined by its headings.
|
|
90
|
+
|
|
91
|
+
``path`` is relative to the record's root, with forward slashes.
|
|
92
|
+
"""
|
|
93
|
+
|
|
94
|
+
path: str
|
|
95
|
+
text: str
|
|
96
|
+
bom: bool
|
|
97
|
+
lines: tuple[Line, ...]
|
|
98
|
+
headings: tuple[Heading, ...]
|
|
99
|
+
|
|
100
|
+
@classmethod
|
|
101
|
+
def parse(cls, path: str, text: str) -> "Document":
|
|
102
|
+
bom = text.startswith(BOM)
|
|
103
|
+
body = text[1:] if bom else text
|
|
104
|
+
lines: list[Line] = []
|
|
105
|
+
fence: str | None = None
|
|
106
|
+
position = 0
|
|
107
|
+
for match in _LINE_BREAK.finditer(body):
|
|
108
|
+
in_fence, fence = _track_fence(body[position : match.start()], fence)
|
|
109
|
+
lines.append(Line(body[position : match.start()], match.group(), in_fence))
|
|
110
|
+
position = match.end()
|
|
111
|
+
if position < len(body):
|
|
112
|
+
in_fence, fence = _track_fence(body[position:], fence)
|
|
113
|
+
lines.append(Line(body[position:], "", in_fence))
|
|
114
|
+
headings = [
|
|
115
|
+
Heading(len(found.group(1)), found.group(2), index)
|
|
116
|
+
for index, line in enumerate(lines)
|
|
117
|
+
if not line.in_fence and (found := _HEADING.match(line.text))
|
|
118
|
+
]
|
|
119
|
+
return cls(path, text, bom, tuple(lines), tuple(headings))
|
|
120
|
+
|
|
121
|
+
@property
|
|
122
|
+
def newline(self) -> str:
|
|
123
|
+
"""The file's line ending: that of its first line, or LF for a one-line file."""
|
|
124
|
+
for line in self.lines:
|
|
125
|
+
if line.ending:
|
|
126
|
+
return line.ending
|
|
127
|
+
return "\n"
|
|
128
|
+
|
|
129
|
+
@property
|
|
130
|
+
def title(self) -> Heading | None:
|
|
131
|
+
"""The first level-1 heading."""
|
|
132
|
+
return next((heading for heading in self.headings if heading.level == 1), None)
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def preamble(self) -> tuple[int, int]:
|
|
136
|
+
"""The line range between the title and the next heading."""
|
|
137
|
+
title = self.title
|
|
138
|
+
start = 0 if title is None else title.index + 1
|
|
139
|
+
end = next((h.index for h in self.headings if h.index >= start), len(self.lines))
|
|
140
|
+
return start, end
|
|
141
|
+
|
|
142
|
+
def raw_lines(self) -> list[str]:
|
|
143
|
+
"""Every line with its ending; joined, they give back the file's exact text."""
|
|
144
|
+
raw = [line.text + line.ending for line in self.lines]
|
|
145
|
+
if self.bom:
|
|
146
|
+
if raw:
|
|
147
|
+
raw[0] = BOM + raw[0]
|
|
148
|
+
else:
|
|
149
|
+
raw.append(BOM)
|
|
150
|
+
return raw
|
|
151
|
+
|
|
152
|
+
def sections(self, level: int, start: int = 0, end: int | None = None) -> tuple[Section, ...]:
|
|
153
|
+
"""The sections of one heading level whose headings lie in a line range."""
|
|
154
|
+
stop = len(self.lines) if end is None else end
|
|
155
|
+
inside = [heading for heading in self.headings if start <= heading.index < stop]
|
|
156
|
+
found: list[Section] = []
|
|
157
|
+
for position, heading in enumerate(inside):
|
|
158
|
+
if heading.level != level:
|
|
159
|
+
continue
|
|
160
|
+
later = (h.index for h in inside[position + 1 :] if h.level <= level)
|
|
161
|
+
found.append(Section(heading, next(later, stop)))
|
|
162
|
+
return tuple(found)
|
|
163
|
+
|
|
164
|
+
def content_end(self, start: int, end: int) -> int:
|
|
165
|
+
"""The index after the last non-blank line in a range; ``start`` if all are blank."""
|
|
166
|
+
last = end
|
|
167
|
+
while last > start and self.lines[last - 1].is_blank:
|
|
168
|
+
last -= 1
|
|
169
|
+
return last
|
|
170
|
+
|
|
171
|
+
def text_between(self, start: int, end: int) -> str:
|
|
172
|
+
"""The text of a line range, without HTML comments or surrounding blank lines.
|
|
173
|
+
|
|
174
|
+
Lines are joined with LF whatever the file's line endings are.
|
|
175
|
+
"""
|
|
176
|
+
joined = "\n".join(line.text for line in self.lines[start:end])
|
|
177
|
+
return _COMMENT.sub("", joined).strip()
|
|
178
|
+
|
|
179
|
+
def body(self, section: Section) -> str:
|
|
180
|
+
"""A section's text under its heading."""
|
|
181
|
+
return self.text_between(section.body_start, section.end)
|
|
182
|
+
|
|
183
|
+
def links(self) -> tuple[Link, ...]:
|
|
184
|
+
"""Every link target outside code fences and code spans."""
|
|
185
|
+
found: list[Link] = []
|
|
186
|
+
for index, line in enumerate(self.lines):
|
|
187
|
+
if line.in_fence:
|
|
188
|
+
continue
|
|
189
|
+
reference = _REFERENCE_LINK.match(line.text)
|
|
190
|
+
if reference:
|
|
191
|
+
found.append(Link(index, reference.start(1), reference.end(1), reference.group(1)))
|
|
192
|
+
continue
|
|
193
|
+
code = [match.span() for match in _CODE_SPAN.finditer(line.text)]
|
|
194
|
+
for match in _INLINE_LINK.finditer(line.text):
|
|
195
|
+
if not any(start <= match.start() < end for start, end in code):
|
|
196
|
+
found.append(Link(index, match.start(1), match.end(1), match.group(1)))
|
|
197
|
+
return tuple(found)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Services: what the commands do. They decide and refuse; the record model reads and writes."""
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"""Atlases on this machine: registering them, pointing a code repo at one, references.
|
|
2
|
+
|
|
3
|
+
wm never clones, pulls or pushes. These commands only record where the
|
|
4
|
+
repositories already are, and read another atlas's specs where it sits.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import os
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
from waymark import __version__
|
|
11
|
+
from waymark.record import git
|
|
12
|
+
from waymark.record.atlas import Found, atlas_name_at, locate_atlas, locate_repo, repo_problem
|
|
13
|
+
from waymark.record.config import CONFIG_FILE, RECORD_DIR, Config
|
|
14
|
+
from waymark.record.files import RecordFiles
|
|
15
|
+
from waymark.record.pointer import POINTER_FILE, Pointer, render_pointer
|
|
16
|
+
from waymark.record.project import Project
|
|
17
|
+
from waymark.record.record import Record, load_record
|
|
18
|
+
from waymark.record.registry import Registry, load_registry, stage_registry
|
|
19
|
+
from waymark.record.store import Transaction
|
|
20
|
+
from waymark.services import integration
|
|
21
|
+
from waymark.services.common import Done, Refusal, commit, open_record
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _atlas_config(record: Record) -> Config:
|
|
25
|
+
config = record.config
|
|
26
|
+
if config is None:
|
|
27
|
+
problems = [p.message for p in record.problems if p.path == CONFIG_FILE]
|
|
28
|
+
detail = problems[0] if problems else "It could not be read."
|
|
29
|
+
raise Refusal(f"{RECORD_DIR}/{CONFIG_FILE} has problems. {detail}")
|
|
30
|
+
if config.atlas_name is None:
|
|
31
|
+
raise Refusal(
|
|
32
|
+
"This project keeps its record in its own repository, not in an atlas, so there is "
|
|
33
|
+
"nothing to register. An atlas is made with: wm init --atlas <name>"
|
|
34
|
+
)
|
|
35
|
+
return config
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def readable_registry() -> Registry:
|
|
39
|
+
"""This machine's registry, refused when it can't be read."""
|
|
40
|
+
registry = load_registry()
|
|
41
|
+
if registry.problems:
|
|
42
|
+
raise Refusal(
|
|
43
|
+
f"The registry at {registry.path} can't be read: {registry.problems[0]} "
|
|
44
|
+
"Fix it, or remove it and register again."
|
|
45
|
+
)
|
|
46
|
+
return registry
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _commit_registry(registry: Registry) -> None:
|
|
50
|
+
commit(stage_registry(registry))
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def register(start: Path, repo: str | None = None, folder: str | None = None) -> Done:
|
|
54
|
+
"""Register the atlas around a folder and its code repos on this machine.
|
|
55
|
+
|
|
56
|
+
Without a repo, every code repo whose path hint leads to it is registered
|
|
57
|
+
too. With one, that repo is registered at the folder given.
|
|
58
|
+
"""
|
|
59
|
+
record = open_record(start)
|
|
60
|
+
config = _atlas_config(record)
|
|
61
|
+
atlas = config.atlas_name
|
|
62
|
+
assert atlas is not None
|
|
63
|
+
root = record.project.root
|
|
64
|
+
known = readable_registry()
|
|
65
|
+
lines: list[str] = []
|
|
66
|
+
previous = known.atlas(atlas)
|
|
67
|
+
if previous and previous.path and previous.path.resolve() != root.resolve():
|
|
68
|
+
lines.append(f'The atlas "{atlas}" was registered at {previous.path}; it is now here.')
|
|
69
|
+
updated = known.with_atlas(atlas, root)
|
|
70
|
+
lines.append(f'Registered the atlas "{atlas}" at {root}.')
|
|
71
|
+
if repo is not None:
|
|
72
|
+
if repo not in config.repo_names:
|
|
73
|
+
listed = ", ".join(sorted(config.repo_names)) or "none yet"
|
|
74
|
+
raise Refusal(
|
|
75
|
+
f'The atlas "{atlas}" has no code repo "{repo}" (repos: {listed}). Add an '
|
|
76
|
+
f'"[atlas.repos.{repo}]" table to {RECORD_DIR}/{CONFIG_FILE} first.'
|
|
77
|
+
)
|
|
78
|
+
target = (start / (folder or ".")).resolve()
|
|
79
|
+
problem = repo_problem(target, atlas)
|
|
80
|
+
if problem is not None:
|
|
81
|
+
raise Refusal(f'"{repo}" can\'t be registered at {target}: {problem}.')
|
|
82
|
+
updated = updated.with_repo(atlas, repo, target)
|
|
83
|
+
lines.append(f'Registered the code repo "{repo}" at {target}.')
|
|
84
|
+
else:
|
|
85
|
+
for code_repo in config.repos:
|
|
86
|
+
location = locate_repo(atlas, root, code_repo, updated)
|
|
87
|
+
if location.found is Found.HINT and location.folder is not None:
|
|
88
|
+
updated = updated.with_repo(atlas, code_repo.name, location.folder)
|
|
89
|
+
lines.append(
|
|
90
|
+
f'Registered the code repo "{code_repo.name}" at {location.folder}, '
|
|
91
|
+
"found through its path hint."
|
|
92
|
+
)
|
|
93
|
+
elif location.found is Found.REGISTRY:
|
|
94
|
+
lines.append(
|
|
95
|
+
f'The code repo "{code_repo.name}" is registered at {location.folder}.'
|
|
96
|
+
)
|
|
97
|
+
else:
|
|
98
|
+
lines.append(f"Not found: {location.detail}")
|
|
99
|
+
folders = [
|
|
100
|
+
location.folder
|
|
101
|
+
for code_repo in config.repos
|
|
102
|
+
if (location := locate_repo(atlas, root, code_repo, updated)).folder is not None
|
|
103
|
+
]
|
|
104
|
+
project_files = RecordFiles(root)
|
|
105
|
+
transaction = Transaction(project_files)
|
|
106
|
+
local = integration.stage_local(transaction, project_files, config.agent_tools, folders)
|
|
107
|
+
_commit_registry(updated)
|
|
108
|
+
commit(transaction)
|
|
109
|
+
integration.keep_local(root, local)
|
|
110
|
+
lines += [f"{change.status}: {change.path}" for change in local if change.status != "unchanged"]
|
|
111
|
+
lines.append(f"The registry is at {updated.path}.")
|
|
112
|
+
return Done("\n".join(lines))
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def register_new_atlas(root: Path, name: str) -> str:
|
|
116
|
+
"""Register an atlas that was just created; returns what to tell the person."""
|
|
117
|
+
known = load_registry()
|
|
118
|
+
if known.problems:
|
|
119
|
+
return f"The registry can't be read, so the atlas is not registered. {known.problems[0]}"
|
|
120
|
+
_commit_registry(known.with_atlas(name, root))
|
|
121
|
+
return f'Registered the atlas "{name}" on this machine.'
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _relative_hint(folder: Path, base: Path) -> str | None:
|
|
125
|
+
try:
|
|
126
|
+
return Path(os.path.relpath(folder, base)).as_posix()
|
|
127
|
+
except ValueError: # another drive, on Windows
|
|
128
|
+
return None
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def point(start: Path, atlas: str, path: str | None = None) -> Done:
|
|
132
|
+
"""Write the pointer file that tells a code repo which atlas holds its record."""
|
|
133
|
+
top = git.repository_root(start)
|
|
134
|
+
if top is None:
|
|
135
|
+
raise Refusal("A pointer goes in a code repo, and this folder is not in a git repository.")
|
|
136
|
+
if (top / RECORD_DIR / CONFIG_FILE).is_file():
|
|
137
|
+
raise Refusal(
|
|
138
|
+
f"This repository holds a Waymark record itself ({RECORD_DIR}/{CONFIG_FILE}), so it "
|
|
139
|
+
"needs no pointer."
|
|
140
|
+
)
|
|
141
|
+
if path is not None:
|
|
142
|
+
folder = (top / path).resolve()
|
|
143
|
+
if atlas_name_at(folder) != atlas:
|
|
144
|
+
raise Refusal(f'{folder} is not the top folder of the atlas "{atlas}".')
|
|
145
|
+
hint: str | None = Path(path).as_posix()
|
|
146
|
+
else:
|
|
147
|
+
location = locate_atlas(atlas, load_registry())
|
|
148
|
+
if location.folder is None:
|
|
149
|
+
raise Refusal(f"{location.detail} Or pass its folder with --path <relative folder>.")
|
|
150
|
+
folder = location.folder
|
|
151
|
+
hint = _relative_hint(folder, top)
|
|
152
|
+
config = load_record(Project(folder)).config
|
|
153
|
+
pin = config.wm_version if config else __version__
|
|
154
|
+
transaction = Transaction(RecordFiles(top))
|
|
155
|
+
existed = (top / POINTER_FILE).is_file()
|
|
156
|
+
transaction.write(POINTER_FILE, render_pointer(Pointer(atlas, hint, pin)))
|
|
157
|
+
commit(transaction)
|
|
158
|
+
verb = "Updated" if existed else "Wrote"
|
|
159
|
+
return Done(
|
|
160
|
+
f'{verb} {POINTER_FILE}: this repository\'s record is the atlas "{atlas}". Commit it so '
|
|
161
|
+
"anyone who clones this repository finds the atlas too."
|
|
162
|
+
)
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""The health check: everything wrong with the record, and everything worth a look."""
|
|
2
|
+
|
|
3
|
+
import datetime
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from enum import StrEnum
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from waymark import __version__
|
|
9
|
+
from waymark.record import git
|
|
10
|
+
from waymark.record.config import CONFIG_FILE, RECORD_FORMAT
|
|
11
|
+
from waymark.record.problems import WHOLE_FILE
|
|
12
|
+
from waymark.record.project import RECORD_DIR
|
|
13
|
+
from waymark.record.record import Record, link_problems
|
|
14
|
+
from waymark.record.state import ConflictKind, ExplorationStatus, RecordState, derive_state
|
|
15
|
+
from waymark.services.common import install_hint, open_record
|
|
16
|
+
|
|
17
|
+
STALE_AFTER_DAYS = 30
|
|
18
|
+
"""A change untouched in git for this long is worth a look."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Severity(StrEnum):
|
|
22
|
+
"""Errors make the check fail; warnings are reported and pass."""
|
|
23
|
+
|
|
24
|
+
ERROR = "error"
|
|
25
|
+
WARNING = "warning"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True, order=True)
|
|
29
|
+
class Finding:
|
|
30
|
+
"""One thing the check found. ``path`` is relative to the record's root."""
|
|
31
|
+
|
|
32
|
+
severity: Severity
|
|
33
|
+
path: str
|
|
34
|
+
line: int
|
|
35
|
+
code: str
|
|
36
|
+
message: str
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _state_findings(record: Record, state: RecordState) -> list[Finding]:
|
|
40
|
+
found: list[Finding] = []
|
|
41
|
+
for name, change in state.changes.items():
|
|
42
|
+
path = record.changes[name].path
|
|
43
|
+
found.extend(
|
|
44
|
+
Finding(Severity.ERROR, path, WHOLE_FILE, "conflict", conflict.message)
|
|
45
|
+
for conflict in change.conflicts
|
|
46
|
+
if conflict.kind is ConflictKind.MISMATCH
|
|
47
|
+
)
|
|
48
|
+
if change.applied:
|
|
49
|
+
message = (
|
|
50
|
+
f'The change "{name}" is applied but not archived. Once its code is merged, '
|
|
51
|
+
f'the human archives it with "wm archive {name}".'
|
|
52
|
+
)
|
|
53
|
+
found.append(Finding(Severity.WARNING, path, WHOLE_FILE, "not-archived", message))
|
|
54
|
+
found.extend(
|
|
55
|
+
Finding(Severity.WARNING, "changes", WHOLE_FILE, "overlap", conflict.message)
|
|
56
|
+
for conflict in state.overlaps
|
|
57
|
+
)
|
|
58
|
+
for name, exploration in state.explorations.items():
|
|
59
|
+
if exploration.status is ExplorationStatus.UNREADABLE:
|
|
60
|
+
path = record.explorations[name].doc.path
|
|
61
|
+
found.append(
|
|
62
|
+
Finding(
|
|
63
|
+
Severity.ERROR,
|
|
64
|
+
path,
|
|
65
|
+
WHOLE_FILE,
|
|
66
|
+
"conclusion-unreadable",
|
|
67
|
+
exploration.detail or "",
|
|
68
|
+
)
|
|
69
|
+
)
|
|
70
|
+
return found
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _stale_findings(record: Record, now: datetime.datetime) -> list[Finding]:
|
|
74
|
+
root = record.project.root
|
|
75
|
+
folders = {f"{RECORD_DIR}/{change.path}": change for change in record.changes.values()}
|
|
76
|
+
found: list[Finding] = []
|
|
77
|
+
for folder, when in git.last_changed(root, folders).items():
|
|
78
|
+
days = (now - when).days
|
|
79
|
+
if days >= STALE_AFTER_DAYS:
|
|
80
|
+
change = folders[folder]
|
|
81
|
+
message = (
|
|
82
|
+
f'The change "{change.name}" has not been touched for {days} days. '
|
|
83
|
+
"Pick it up again, or remove it if it was dropped."
|
|
84
|
+
)
|
|
85
|
+
found.append(Finding(Severity.WARNING, change.path, WHOLE_FILE, "stale", message))
|
|
86
|
+
return found
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _setup_findings(record: Record) -> list[Finding]:
|
|
90
|
+
config = record.config
|
|
91
|
+
found: list[Finding] = []
|
|
92
|
+
if config is None:
|
|
93
|
+
return found
|
|
94
|
+
if config.wm_version != __version__:
|
|
95
|
+
message = (
|
|
96
|
+
f"The project is pinned to wm {config.wm_version}, and this is wm {__version__}. "
|
|
97
|
+
f"Writing commands are refused. Install the pinned version: "
|
|
98
|
+
f"{install_hint(config.wm_version)}"
|
|
99
|
+
)
|
|
100
|
+
found.append(Finding(Severity.WARNING, CONFIG_FILE, WHOLE_FILE, "version-pin", message))
|
|
101
|
+
if config.record_format != RECORD_FORMAT:
|
|
102
|
+
message = (
|
|
103
|
+
f"The record is in format {config.record_format}, and this wm writes format "
|
|
104
|
+
f'{RECORD_FORMAT}. Run "wm update" to migrate it.'
|
|
105
|
+
)
|
|
106
|
+
found.append(Finding(Severity.WARNING, CONFIG_FILE, WHOLE_FILE, "record-format", message))
|
|
107
|
+
return found
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def check_record(record: Record, now: datetime.datetime) -> tuple[Finding, ...]:
|
|
111
|
+
"""Everything the health check finds in a loaded record, in a stable order."""
|
|
112
|
+
found = [
|
|
113
|
+
Finding(Severity.ERROR, p.path, p.line, p.code, p.message)
|
|
114
|
+
for p in (*record.problems, *link_problems(record))
|
|
115
|
+
]
|
|
116
|
+
found += _state_findings(record, derive_state(record))
|
|
117
|
+
found += _stale_findings(record, now)
|
|
118
|
+
found += _setup_findings(record)
|
|
119
|
+
return tuple(sorted(found))
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def check(start: Path, now: datetime.datetime) -> tuple[Finding, ...]:
|
|
123
|
+
"""Check the record around a folder. Reading never needs the pinned version."""
|
|
124
|
+
return check_record(open_record(start), now)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def has_errors(findings: tuple[Finding, ...]) -> bool:
|
|
128
|
+
"""Whether the check fails."""
|
|
129
|
+
return any(finding.severity is Severity.ERROR for finding in findings)
|
waymark/services/ci.py
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""The CI workflow: GitHub Actions installs the pinned wm and runs wm check.
|
|
2
|
+
|
|
3
|
+
It is added only when asked for, with ``wm ci``; ``wm update`` keeps it
|
|
4
|
+
current once it exists. In an atlas it belongs in the atlas: code repos'
|
|
5
|
+
CI runs nothing from wm.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
from waymark.record import templates
|
|
11
|
+
from waymark.record.files import RecordFiles
|
|
12
|
+
from waymark.record.store import Transaction
|
|
13
|
+
from waymark.services.common import Done, commit, open_record, require_pinned
|
|
14
|
+
|
|
15
|
+
WORKFLOW = ".github/workflows/waymark.yml"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def stage_workflow(transaction: Transaction, files: RecordFiles, *, only_if_present: bool) -> str:
|
|
19
|
+
"""Stage the workflow; says whether it was created, updated, unchanged or left out."""
|
|
20
|
+
current = files.read(WORKFLOW, []) if files.is_file(WORKFLOW) else None
|
|
21
|
+
if current is None and only_if_present:
|
|
22
|
+
return "absent"
|
|
23
|
+
text = templates.render(templates.CI_WORKFLOW)
|
|
24
|
+
if current == text:
|
|
25
|
+
return "unchanged"
|
|
26
|
+
transaction.write(WORKFLOW, text)
|
|
27
|
+
return "created" if current is None else "updated"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def add_workflow(start: Path) -> Done:
|
|
31
|
+
"""Add, or bring up to date, the workflow that runs wm check in CI."""
|
|
32
|
+
record = open_record(start)
|
|
33
|
+
require_pinned(record)
|
|
34
|
+
files = RecordFiles(record.project.root)
|
|
35
|
+
transaction = Transaction(files)
|
|
36
|
+
status = stage_workflow(transaction, files, only_if_present=False)
|
|
37
|
+
commit(transaction)
|
|
38
|
+
if status == "unchanged":
|
|
39
|
+
return Done(f"{WORKFLOW} is already current.")
|
|
40
|
+
return Done(
|
|
41
|
+
f"{status}: {WORKFLOW}\nOn GitHub, it installs the wm version this project pins and runs "
|
|
42
|
+
'"wm check" on every push and pull request. Review it and commit it.',
|
|
43
|
+
transaction.paths,
|
|
44
|
+
)
|