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,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,4 @@
1
+ # {{title}}: roadmap
2
+
3
+ <!-- One list line per change this milestone expects. Link a proposed change to its
4
+ proposal; write a change that is not proposed yet as a plain line. -->
@@ -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()
@@ -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
+ )