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
waymark/record/atlas.py
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Finding an atlas and its code repos on this machine.
|
|
2
|
+
|
|
3
|
+
The registry is asked first. When it has no usable entry, a relative-path
|
|
4
|
+
hint is tried, and used only when it leads to the right repository: an atlas
|
|
5
|
+
whose settings carry the expected name, or a git repository's top folder whose
|
|
6
|
+
pointer file, if it has one, names the expected atlas.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from enum import StrEnum
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from waymark.record import git
|
|
14
|
+
from waymark.record.config import CONFIG_FILE, RECORD_DIR, CodeRepo, parse_config
|
|
15
|
+
from waymark.record.pointer import POINTER_FILE, Pointer, parse_pointer
|
|
16
|
+
from waymark.record.registry import Registry
|
|
17
|
+
|
|
18
|
+
REGISTER = "wm atlas register"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Found(StrEnum):
|
|
22
|
+
"""How a folder was found."""
|
|
23
|
+
|
|
24
|
+
REGISTRY = "registry"
|
|
25
|
+
HINT = "hint"
|
|
26
|
+
MISSING = "missing"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class Location:
|
|
31
|
+
"""Where an atlas or code repo is on this machine, if anywhere.
|
|
32
|
+
|
|
33
|
+
``detail`` says why it is missing, or, when only its hint found it, how to
|
|
34
|
+
register it. It names no folder, so it can go into JSON as it is.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
name: str
|
|
38
|
+
folder: Path | None
|
|
39
|
+
found: Found
|
|
40
|
+
detail: str = ""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _read(path: Path) -> str | None:
|
|
44
|
+
try:
|
|
45
|
+
return path.read_bytes().decode("utf-8")
|
|
46
|
+
except (OSError, UnicodeDecodeError):
|
|
47
|
+
return None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def atlas_name_at(folder: Path) -> str | None:
|
|
51
|
+
"""The name of the atlas whose top folder this is; None when it isn't one."""
|
|
52
|
+
text = _read(folder / RECORD_DIR / CONFIG_FILE)
|
|
53
|
+
config = parse_config(text)[0] if text is not None else None
|
|
54
|
+
return config.atlas_name if config else None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def read_pointer(folder: Path) -> tuple[Pointer | None, str | None]:
|
|
58
|
+
"""A folder's pointer file, and why it can't be read, if it can't; (None, None) without one."""
|
|
59
|
+
text = _read(folder / POINTER_FILE)
|
|
60
|
+
if text is None:
|
|
61
|
+
return None, None
|
|
62
|
+
return parse_pointer(text)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def pointer_atlas(folder: Path) -> tuple[str | None, str | None]:
|
|
66
|
+
"""The atlas a folder's pointer file names, and why it can't be read, if it can't."""
|
|
67
|
+
pointer, problem = read_pointer(folder)
|
|
68
|
+
return (pointer.atlas if pointer else None), problem
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def is_repo_top(folder: Path) -> bool:
|
|
72
|
+
"""Whether a folder is the top folder of a git repository."""
|
|
73
|
+
if not folder.is_dir():
|
|
74
|
+
return False
|
|
75
|
+
top = git.repository_root(folder)
|
|
76
|
+
return top is not None and top.resolve() == folder.resolve()
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def repo_problem(folder: Path, atlas: str) -> str | None:
|
|
80
|
+
"""Why a folder can't be the code repo of an atlas; None when it can. Names no folder."""
|
|
81
|
+
if not folder.is_dir():
|
|
82
|
+
return "the folder doesn't exist"
|
|
83
|
+
if not is_repo_top(folder):
|
|
84
|
+
return "the folder is not the top folder of a git repository"
|
|
85
|
+
named, _ = pointer_atlas(folder)
|
|
86
|
+
if named is not None and named != atlas:
|
|
87
|
+
return f'its pointer names the atlas "{named}", not "{atlas}"'
|
|
88
|
+
return None
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _hinted(base: Path, hint: str | None) -> Path | None:
|
|
92
|
+
if not hint:
|
|
93
|
+
return None
|
|
94
|
+
return (base / hint).resolve()
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def locate_atlas(
|
|
98
|
+
name: str, registry: Registry, base: Path | None = None, hint: str | None = None
|
|
99
|
+
) -> Location:
|
|
100
|
+
"""Find an atlas: through the registry, or through a hint relative to ``base``."""
|
|
101
|
+
entry = registry.atlas(name)
|
|
102
|
+
stale = ""
|
|
103
|
+
if entry is not None and entry.path is not None:
|
|
104
|
+
if atlas_name_at(entry.path) == name:
|
|
105
|
+
return Location(name, entry.path, Found.REGISTRY)
|
|
106
|
+
stale = " The registry's entry points to a folder that holds no atlas of that name."
|
|
107
|
+
folder = _hinted(base, hint) if base is not None else None
|
|
108
|
+
if folder is not None and atlas_name_at(folder) == name:
|
|
109
|
+
detail = (
|
|
110
|
+
f'Found the atlas "{name}" through its path hint. '
|
|
111
|
+
f'To register it on this machine, run "{REGISTER}" there.'
|
|
112
|
+
)
|
|
113
|
+
return Location(name, folder, Found.HINT, detail)
|
|
114
|
+
tried = f" Its path hint ({hint}) doesn't lead to it." if hint else ""
|
|
115
|
+
return Location(
|
|
116
|
+
name,
|
|
117
|
+
None,
|
|
118
|
+
Found.MISSING,
|
|
119
|
+
f'The atlas "{name}" is not on this machine\'s registry.{stale}{tried} '
|
|
120
|
+
f'Clone it, then run "{REGISTER}" in it.',
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def locate_repo(atlas: str, atlas_root: Path, repo: CodeRepo, registry: Registry) -> Location:
|
|
125
|
+
"""Find one of an atlas's code repos: through the registry, or its hint."""
|
|
126
|
+
registered = registry.repo(atlas, repo.name)
|
|
127
|
+
stale = ""
|
|
128
|
+
if registered is not None:
|
|
129
|
+
problem = repo_problem(registered, atlas)
|
|
130
|
+
if problem is None:
|
|
131
|
+
return Location(repo.name, registered, Found.REGISTRY)
|
|
132
|
+
stale = f" The registry's entry is unusable: {problem}."
|
|
133
|
+
folder = _hinted(atlas_root, repo.path_hint)
|
|
134
|
+
if folder is not None and repo_problem(folder, atlas) is None:
|
|
135
|
+
detail = (
|
|
136
|
+
f'Found the code repo "{repo.name}" through its path hint. '
|
|
137
|
+
f'To register it on this machine, run "{REGISTER}" in the atlas.'
|
|
138
|
+
)
|
|
139
|
+
return Location(repo.name, folder, Found.HINT, detail)
|
|
140
|
+
tried = f" Its path hint ({repo.path_hint}) doesn't lead to it." if repo.path_hint else ""
|
|
141
|
+
return Location(
|
|
142
|
+
repo.name,
|
|
143
|
+
None,
|
|
144
|
+
Found.MISSING,
|
|
145
|
+
f'The code repo "{repo.name}" is not on this machine\'s registry.{stale}{tried} '
|
|
146
|
+
f'Register its folder with "{REGISTER} {repo.name} <folder>".',
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def contains(folder: Path, path: Path) -> bool:
|
|
151
|
+
"""Whether a path is a folder or inside it."""
|
|
152
|
+
try:
|
|
153
|
+
path.resolve().relative_to(folder.resolve())
|
|
154
|
+
except ValueError:
|
|
155
|
+
return False
|
|
156
|
+
return True
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
"""Changes: one folder per unit of work, holding its proposal, deltas, design and tasks."""
|
|
2
|
+
|
|
3
|
+
import datetime
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from waymark.record.config import Config
|
|
8
|
+
from waymark.record.deltas import Delta, parse_delta
|
|
9
|
+
from waymark.record.design import Design, parse_design
|
|
10
|
+
from waymark.record.files import RecordFiles
|
|
11
|
+
from waymark.record.names import NAME_RULE, is_valid_name
|
|
12
|
+
from waymark.record.problems import WHOLE_FILE, Problem
|
|
13
|
+
from waymark.record.proposal import PATH, SHORT, Proposal, parse_proposal
|
|
14
|
+
from waymark.record.tasks import Tasks, parse_tasks
|
|
15
|
+
from waymark.record.terms import Layout, ReviewLevel
|
|
16
|
+
|
|
17
|
+
PROPOSAL_FILE = "proposal.md"
|
|
18
|
+
DESIGN_FILE = "design.md"
|
|
19
|
+
TASKS_FILE = "tasks.md"
|
|
20
|
+
SPECS_DIR = "specs"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class Change:
|
|
25
|
+
"""A change folder and what is in it.
|
|
26
|
+
|
|
27
|
+
``problems`` holds every problem in the change's files; each one's path
|
|
28
|
+
says which file it belongs to.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
name: str
|
|
32
|
+
path: str
|
|
33
|
+
archived_on: datetime.date | None
|
|
34
|
+
proposal: Proposal | None
|
|
35
|
+
deltas: Mapping[str, Delta]
|
|
36
|
+
design: Design | None
|
|
37
|
+
tasks: Tasks | None
|
|
38
|
+
problems: tuple[Problem, ...]
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def short_path(self) -> bool:
|
|
42
|
+
return self.proposal is not None and self.proposal.short_path
|
|
43
|
+
|
|
44
|
+
def problems_in(self, relative: str) -> tuple[Problem, ...]:
|
|
45
|
+
"""The problems in one file or folder of the change."""
|
|
46
|
+
target = f"{self.path}/{relative}"
|
|
47
|
+
return tuple(
|
|
48
|
+
problem
|
|
49
|
+
for problem in self.problems
|
|
50
|
+
if problem.path == target or problem.path.startswith(f"{target}/")
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _load_deltas(files: RecordFiles, path: str, problems: list[Problem]) -> dict[str, Delta]:
|
|
55
|
+
deltas: dict[str, Delta] = {}
|
|
56
|
+
for entry in files.entries(f"{path}/{SPECS_DIR}"):
|
|
57
|
+
relative = f"{path}/{SPECS_DIR}/{entry.name}"
|
|
58
|
+
domain = entry.name.removesuffix(".md")
|
|
59
|
+
if entry.is_dir or not entry.name.endswith(".md") or not is_valid_name(domain):
|
|
60
|
+
problems.append(
|
|
61
|
+
Problem(
|
|
62
|
+
relative,
|
|
63
|
+
WHOLE_FILE,
|
|
64
|
+
"unexpected-file",
|
|
65
|
+
f"A change's specs folder holds one <domain>.md delta per spec, named in "
|
|
66
|
+
f"{NAME_RULE}. Rename or remove this.",
|
|
67
|
+
)
|
|
68
|
+
)
|
|
69
|
+
continue
|
|
70
|
+
doc = files.document(relative, problems)
|
|
71
|
+
if doc is not None:
|
|
72
|
+
deltas[domain] = parse_delta(domain, doc)
|
|
73
|
+
problems.extend(deltas[domain].problems)
|
|
74
|
+
return deltas
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _check_against_config(change: Change, config: Config | None, problems: list[Problem]) -> None:
|
|
78
|
+
"""Rules that span files: the short path's limits, and repos in an atlas."""
|
|
79
|
+
proposal, tasks = change.proposal, change.tasks
|
|
80
|
+
default = config.default_review if config else ReviewLevel.SELF
|
|
81
|
+
if proposal and proposal.no_spec_changes and change.deltas:
|
|
82
|
+
problems.append(
|
|
83
|
+
Problem(
|
|
84
|
+
proposal.doc.path,
|
|
85
|
+
WHOLE_FILE,
|
|
86
|
+
"impact-mismatch",
|
|
87
|
+
'The impact says "No spec changes", but the change has deltas. '
|
|
88
|
+
"List the specs it touches, or remove the deltas.",
|
|
89
|
+
)
|
|
90
|
+
)
|
|
91
|
+
if change.short_path and change.design is not None:
|
|
92
|
+
problems.append(
|
|
93
|
+
Problem(
|
|
94
|
+
change.design.doc.path,
|
|
95
|
+
WHOLE_FILE,
|
|
96
|
+
"short-path-design",
|
|
97
|
+
f"A change on the short path has no design. Remove {DESIGN_FILE}, or remove "
|
|
98
|
+
f'the "{PATH}: {SHORT}" line from the proposal.',
|
|
99
|
+
)
|
|
100
|
+
)
|
|
101
|
+
if change.short_path and tasks is not None:
|
|
102
|
+
problems.extend(
|
|
103
|
+
Problem(
|
|
104
|
+
tasks.doc.path,
|
|
105
|
+
item.index + 1,
|
|
106
|
+
"short-path-review",
|
|
107
|
+
f"Item {item.number} needs an independent review, which the short path "
|
|
108
|
+
f'doesn\'t allow. Remove the "{PATH}: {SHORT}" line from the proposal, or '
|
|
109
|
+
"lower the item's review level.",
|
|
110
|
+
)
|
|
111
|
+
for item in tasks.items
|
|
112
|
+
if item.level(default) is ReviewLevel.INDEPENDENT
|
|
113
|
+
)
|
|
114
|
+
if config is None:
|
|
115
|
+
return
|
|
116
|
+
atlas = config.layout is Layout.ATLAS
|
|
117
|
+
known = ", ".join(sorted(config.repo_names)) or "none yet"
|
|
118
|
+
for item in tasks.items if tasks else ():
|
|
119
|
+
if atlas and item.repo is None:
|
|
120
|
+
problems.append(
|
|
121
|
+
Problem(
|
|
122
|
+
tasks.doc.path if tasks else change.path,
|
|
123
|
+
item.index + 1,
|
|
124
|
+
"item-without-repo",
|
|
125
|
+
f"In an atlas every item names the repo it works in. Add a "
|
|
126
|
+
f'"Repo: <name>" line under item {item.number} (repos: {known}).',
|
|
127
|
+
)
|
|
128
|
+
)
|
|
129
|
+
elif item.repo is not None and item.repo not in config.repo_names:
|
|
130
|
+
problems.append(
|
|
131
|
+
Problem(
|
|
132
|
+
tasks.doc.path if tasks else change.path,
|
|
133
|
+
item.index + 1,
|
|
134
|
+
"unknown-repo",
|
|
135
|
+
f'Item {item.number} names the repo "{item.repo}", which the settings '
|
|
136
|
+
f"don't list (repos: {known}). Fix the name, or add the repo to the settings."
|
|
137
|
+
if atlas
|
|
138
|
+
else f'Item {item.number} has a "Repo:" line, but this project is not an '
|
|
139
|
+
"atlas. Remove the line.",
|
|
140
|
+
)
|
|
141
|
+
)
|
|
142
|
+
for delta in change.deltas.values():
|
|
143
|
+
for repo in delta.repos or ():
|
|
144
|
+
if repo not in config.repo_names:
|
|
145
|
+
problems.append(
|
|
146
|
+
Problem(
|
|
147
|
+
delta.doc.path,
|
|
148
|
+
WHOLE_FILE,
|
|
149
|
+
"unknown-repo",
|
|
150
|
+
f'The delta names the repo "{repo}", which the settings don\'t list '
|
|
151
|
+
f"(repos: {known}). Fix the name, or add the repo to the settings."
|
|
152
|
+
if atlas
|
|
153
|
+
else 'The delta has a "Repos:" line, but this project is not an atlas. '
|
|
154
|
+
"Remove the line.",
|
|
155
|
+
)
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def load_change(
|
|
160
|
+
files: RecordFiles,
|
|
161
|
+
path: str,
|
|
162
|
+
name: str,
|
|
163
|
+
config: Config | None,
|
|
164
|
+
archived_on: datetime.date | None = None,
|
|
165
|
+
) -> Change:
|
|
166
|
+
"""Read a change folder."""
|
|
167
|
+
problems: list[Problem] = []
|
|
168
|
+
proposal: Proposal | None = None
|
|
169
|
+
design: Design | None = None
|
|
170
|
+
tasks: Tasks | None = None
|
|
171
|
+
deltas: dict[str, Delta] = {}
|
|
172
|
+
for entry in files.entries(path):
|
|
173
|
+
relative = f"{path}/{entry.name}"
|
|
174
|
+
if entry.is_dir and entry.name == SPECS_DIR:
|
|
175
|
+
deltas = _load_deltas(files, path, problems)
|
|
176
|
+
elif entry.is_dir or entry.name not in (PROPOSAL_FILE, DESIGN_FILE, TASKS_FILE):
|
|
177
|
+
problems.append(
|
|
178
|
+
Problem(
|
|
179
|
+
relative,
|
|
180
|
+
WHOLE_FILE,
|
|
181
|
+
"unexpected-file",
|
|
182
|
+
f"A change holds {PROPOSAL_FILE}, {DESIGN_FILE}, {TASKS_FILE} and a "
|
|
183
|
+
f"{SPECS_DIR} folder. Move this elsewhere or remove it.",
|
|
184
|
+
)
|
|
185
|
+
)
|
|
186
|
+
else:
|
|
187
|
+
doc = files.document(relative, problems)
|
|
188
|
+
if doc is None:
|
|
189
|
+
continue
|
|
190
|
+
if entry.name == PROPOSAL_FILE:
|
|
191
|
+
proposal = parse_proposal(doc)
|
|
192
|
+
problems.extend(proposal.problems)
|
|
193
|
+
elif entry.name == DESIGN_FILE:
|
|
194
|
+
design = parse_design(doc)
|
|
195
|
+
problems.extend(design.problems)
|
|
196
|
+
else:
|
|
197
|
+
tasks = parse_tasks(doc)
|
|
198
|
+
problems.extend(tasks.problems)
|
|
199
|
+
change = Change(name, path, archived_on, proposal, deltas, design, tasks, ())
|
|
200
|
+
if archived_on is None:
|
|
201
|
+
_check_against_config(change, config, problems)
|
|
202
|
+
return Change(name, path, archived_on, proposal, deltas, design, tasks, tuple(sorted(problems)))
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""The charter: what the project is, the context every agent gets, and rules per step."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Mapping
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
|
|
6
|
+
from waymark.record.outline import collect_sections, require_title
|
|
7
|
+
from waymark.record.problems import Problem
|
|
8
|
+
from waymark.record.terms import Step
|
|
9
|
+
from waymark.record.text import Document
|
|
10
|
+
|
|
11
|
+
CHARTER_FILE = "charter.md"
|
|
12
|
+
|
|
13
|
+
VISION = "Vision"
|
|
14
|
+
GOALS = "Goals"
|
|
15
|
+
NON_GOALS = "Non-goals"
|
|
16
|
+
CONSTRAINTS = "Constraints"
|
|
17
|
+
GLOSSARY = "Glossary"
|
|
18
|
+
CONTEXT = "Context"
|
|
19
|
+
RULES = "Rules"
|
|
20
|
+
REQUIRED_SECTIONS = (VISION, GOALS, NON_GOALS, CONSTRAINTS, GLOSSARY, CONTEXT, RULES)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class Charter:
|
|
25
|
+
"""The project's charter.
|
|
26
|
+
|
|
27
|
+
``context`` goes to every agent. ``rules`` holds the text for each workflow
|
|
28
|
+
step that has any; an agent gets only its own step's rules.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
doc: Document
|
|
32
|
+
title: str
|
|
33
|
+
sections: Mapping[str, str]
|
|
34
|
+
context: str
|
|
35
|
+
rules: Mapping[Step, str]
|
|
36
|
+
problems: tuple[Problem, ...]
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def parse_charter(doc: Document) -> Charter:
|
|
40
|
+
"""Read the charter. Sections may be empty while the charter is still a skeleton."""
|
|
41
|
+
problems: list[Problem] = []
|
|
42
|
+
title = require_title(doc, problems)
|
|
43
|
+
found = collect_sections(doc, REQUIRED_SECTIONS, problems)
|
|
44
|
+
sections = {name: doc.body(found[name]) if name in found else "" for name in REQUIRED_SECTIONS}
|
|
45
|
+
|
|
46
|
+
rules: dict[Step, str] = {}
|
|
47
|
+
if RULES in found:
|
|
48
|
+
parent = found[RULES]
|
|
49
|
+
for section in doc.sections(3, parent.body_start, parent.end):
|
|
50
|
+
name = section.title.casefold()
|
|
51
|
+
if name not in set(Step):
|
|
52
|
+
steps = ", ".join(step.value for step in Step)
|
|
53
|
+
problems.append(
|
|
54
|
+
Problem(
|
|
55
|
+
doc.path,
|
|
56
|
+
section.start + 1,
|
|
57
|
+
"unknown-step",
|
|
58
|
+
f'"{section.title}" is not a workflow step, so no agent would get '
|
|
59
|
+
f"these rules. Use one of: {steps}.",
|
|
60
|
+
)
|
|
61
|
+
)
|
|
62
|
+
elif Step(name) in rules:
|
|
63
|
+
problems.append(
|
|
64
|
+
Problem(
|
|
65
|
+
doc.path,
|
|
66
|
+
section.start + 1,
|
|
67
|
+
"duplicate-section",
|
|
68
|
+
f'The rules for "{name}" appear twice. Merge the two sections.',
|
|
69
|
+
)
|
|
70
|
+
)
|
|
71
|
+
else:
|
|
72
|
+
text = doc.body(section)
|
|
73
|
+
if text:
|
|
74
|
+
rules[Step(name)] = text
|
|
75
|
+
return Charter(doc, title, sections, sections[CONTEXT], rules, tuple(problems))
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""The commit-message check: conventional commits, with the project's scopes if it lists any.
|
|
2
|
+
|
|
3
|
+
A message reads ``<type>(<scope>)!: <summary>``, where the scope and the ``!``
|
|
4
|
+
(a breaking change) are optional. When the project lists scopes, a scope
|
|
5
|
+
given must be one of them. Messages git writes itself pass as they are.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import re
|
|
9
|
+
|
|
10
|
+
TYPES = (
|
|
11
|
+
"build",
|
|
12
|
+
"chore",
|
|
13
|
+
"ci",
|
|
14
|
+
"docs",
|
|
15
|
+
"feat",
|
|
16
|
+
"fix",
|
|
17
|
+
"perf",
|
|
18
|
+
"refactor",
|
|
19
|
+
"revert",
|
|
20
|
+
"style",
|
|
21
|
+
"test",
|
|
22
|
+
)
|
|
23
|
+
"""The commit types the check accepts."""
|
|
24
|
+
|
|
25
|
+
_HEADER = re.compile(
|
|
26
|
+
r"^(?P<type>[a-z]+)(?:\((?P<scope>[^()\s]*)\))?(?P<breaking>!)?:(?P<summary>.*)$"
|
|
27
|
+
)
|
|
28
|
+
_GIT_WRITTEN = ("Merge ", 'Revert "', "fixup! ", "squash! ", "amend! ")
|
|
29
|
+
_SCISSORS = "# ------------------------ >8 ------------------------"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _lines(message: str) -> list[str]:
|
|
33
|
+
"""The message as git will record it: comments and everything below the scissors gone."""
|
|
34
|
+
kept: list[str] = []
|
|
35
|
+
for line in message.replace("\r\n", "\n").split("\n"):
|
|
36
|
+
if line.startswith(_SCISSORS):
|
|
37
|
+
break
|
|
38
|
+
if not line.startswith("#"):
|
|
39
|
+
kept.append(line.rstrip())
|
|
40
|
+
while kept and not kept[0]:
|
|
41
|
+
kept.pop(0)
|
|
42
|
+
return kept
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def commit_problem( # noqa: PLR0911 - one return per rule
|
|
46
|
+
message: str, scopes: tuple[str, ...] | None = None
|
|
47
|
+
) -> str | None:
|
|
48
|
+
"""What is wrong with a commit message, and how to fix it; None when it is fine."""
|
|
49
|
+
lines = _lines(message)
|
|
50
|
+
if not lines:
|
|
51
|
+
return "The commit message is empty. Write one such as: feat: add a result limit"
|
|
52
|
+
header = lines[0]
|
|
53
|
+
if header.startswith(_GIT_WRITTEN):
|
|
54
|
+
return None
|
|
55
|
+
example = "<type>(<scope>): <summary>, for example: fix: accept an empty search query"
|
|
56
|
+
match = _HEADER.match(header)
|
|
57
|
+
if match is None:
|
|
58
|
+
return (
|
|
59
|
+
f'"{header}" is not a conventional commit summary. Write it as {example}. '
|
|
60
|
+
f"Types: {', '.join(TYPES)}."
|
|
61
|
+
)
|
|
62
|
+
kind, scope = match["type"], match["scope"]
|
|
63
|
+
if kind not in TYPES:
|
|
64
|
+
return f'"{kind}" is not a commit type. Use one of: {", ".join(TYPES)}.'
|
|
65
|
+
if scope is not None and not scope:
|
|
66
|
+
return "The scope in parentheses is empty. Name a scope, or leave out the parentheses."
|
|
67
|
+
if scope is not None and scopes is not None and scope not in scopes:
|
|
68
|
+
return (
|
|
69
|
+
f'"{scope}" is not one of this project\'s commit scopes ({", ".join(scopes)}). '
|
|
70
|
+
"Use one of them, or leave the scope out."
|
|
71
|
+
)
|
|
72
|
+
if not match["summary"].strip():
|
|
73
|
+
return f"The summary after the colon is empty. Write it as {example}."
|
|
74
|
+
if not match["summary"].startswith(" "):
|
|
75
|
+
return "Put one space after the colon, before the summary."
|
|
76
|
+
if len(lines) > 1 and lines[1]:
|
|
77
|
+
return "Leave a blank line between the summary and the rest of the message."
|
|
78
|
+
return None
|