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/config.py
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"""Settings: ``config.toml`` at the record's root."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
import tomllib
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from waymark.record.problems import WHOLE_FILE, Problem
|
|
9
|
+
from waymark.record.terms import Layout, ReviewLevel
|
|
10
|
+
|
|
11
|
+
CONFIG_FILE = "config.toml"
|
|
12
|
+
RECORD_DIR = "waymark"
|
|
13
|
+
"""The record's folder, at the top of a repository or an atlas."""
|
|
14
|
+
|
|
15
|
+
_REPO_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
|
|
16
|
+
RECORD_FORMAT = 1
|
|
17
|
+
"""The record format this version of wm reads and writes."""
|
|
18
|
+
|
|
19
|
+
_TOP_KEYS = frozenset(
|
|
20
|
+
{
|
|
21
|
+
"wm_version",
|
|
22
|
+
"record_format",
|
|
23
|
+
"default_review",
|
|
24
|
+
"commit_scopes",
|
|
25
|
+
"agent_tools",
|
|
26
|
+
"atlas",
|
|
27
|
+
"references",
|
|
28
|
+
}
|
|
29
|
+
)
|
|
30
|
+
_ATLAS_KEYS = frozenset({"name", "repos"})
|
|
31
|
+
_REPO_KEYS = frozenset({"path"})
|
|
32
|
+
_REFERENCE_KEYS = frozenset({"path"})
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class CodeRepo:
|
|
37
|
+
"""A code repository an atlas covers, with an optional relative-path hint."""
|
|
38
|
+
|
|
39
|
+
name: str
|
|
40
|
+
path_hint: str | None
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass(frozen=True)
|
|
44
|
+
class Reference:
|
|
45
|
+
"""Another atlas whose specs this project reads, with an optional relative-path hint."""
|
|
46
|
+
|
|
47
|
+
atlas: str
|
|
48
|
+
path_hint: str | None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@dataclass(frozen=True)
|
|
52
|
+
class Config:
|
|
53
|
+
"""The settings wm reads."""
|
|
54
|
+
|
|
55
|
+
wm_version: str
|
|
56
|
+
record_format: int
|
|
57
|
+
default_review: ReviewLevel
|
|
58
|
+
commit_scopes: tuple[str, ...] | None
|
|
59
|
+
agent_tools: tuple[str, ...]
|
|
60
|
+
atlas_name: str | None
|
|
61
|
+
repos: tuple[CodeRepo, ...]
|
|
62
|
+
references: tuple[Reference, ...] = ()
|
|
63
|
+
|
|
64
|
+
@property
|
|
65
|
+
def layout(self) -> Layout:
|
|
66
|
+
return Layout.REPO if self.atlas_name is None else Layout.ATLAS
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def repo_names(self) -> frozenset[str]:
|
|
70
|
+
return frozenset(repo.name for repo in self.repos)
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class _Reader:
|
|
74
|
+
"""Collects problems while values are pulled out of the parsed TOML."""
|
|
75
|
+
|
|
76
|
+
def __init__(self) -> None:
|
|
77
|
+
self.problems: list[Problem] = []
|
|
78
|
+
|
|
79
|
+
def problem(self, code: str, message: str) -> None:
|
|
80
|
+
self.problems.append(Problem(CONFIG_FILE, WHOLE_FILE, code, message))
|
|
81
|
+
|
|
82
|
+
def unknown_keys(self, table: dict[str, Any], known: frozenset[str], where: str) -> None:
|
|
83
|
+
for key in sorted(set(table) - known):
|
|
84
|
+
self.problem(
|
|
85
|
+
"unknown-setting", f'"{key}" is not a setting{where}. Remove it or fix its name.'
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
def string(self, table: dict[str, Any], key: str, where: str = "") -> str | None:
|
|
89
|
+
value = table.get(key)
|
|
90
|
+
if isinstance(value, str) and value.strip():
|
|
91
|
+
return value.strip()
|
|
92
|
+
self.problem("invalid-setting", f'Set "{key}"{where} to a non-empty string.')
|
|
93
|
+
return None
|
|
94
|
+
|
|
95
|
+
def strings(self, table: dict[str, Any], key: str) -> tuple[str, ...] | None:
|
|
96
|
+
value = table.get(key)
|
|
97
|
+
if isinstance(value, list) and all(isinstance(item, str) and item for item in value):
|
|
98
|
+
return tuple(value)
|
|
99
|
+
self.problem("invalid-setting", f'Set "{key}" to a list of non-empty strings.')
|
|
100
|
+
return None
|
|
101
|
+
|
|
102
|
+
def format_number(self, table: dict[str, Any]) -> int | None:
|
|
103
|
+
value = table.get("record_format")
|
|
104
|
+
if isinstance(value, int) and not isinstance(value, bool) and value >= 1:
|
|
105
|
+
return value
|
|
106
|
+
self.problem(
|
|
107
|
+
"invalid-setting",
|
|
108
|
+
'Set "record_format" to the record\'s format number. It is written by wm; '
|
|
109
|
+
f"a record made by this version has {RECORD_FORMAT}.",
|
|
110
|
+
)
|
|
111
|
+
return None
|
|
112
|
+
|
|
113
|
+
def review_level(self, table: dict[str, Any]) -> ReviewLevel | None:
|
|
114
|
+
value = table.get("default_review")
|
|
115
|
+
if isinstance(value, str) and value in set(ReviewLevel):
|
|
116
|
+
return ReviewLevel(value)
|
|
117
|
+
levels = ", ".join(f'"{level.value}"' for level in ReviewLevel)
|
|
118
|
+
self.problem("invalid-setting", f'Set "default_review" to one of {levels}.')
|
|
119
|
+
return None
|
|
120
|
+
|
|
121
|
+
def repos(self, atlas: dict[str, Any]) -> tuple[CodeRepo, ...]:
|
|
122
|
+
tables = atlas.get("repos", {})
|
|
123
|
+
if not isinstance(tables, dict):
|
|
124
|
+
self.problem(
|
|
125
|
+
"invalid-setting",
|
|
126
|
+
'Name each code repo with its own "[atlas.repos.<name>]" table.',
|
|
127
|
+
)
|
|
128
|
+
return ()
|
|
129
|
+
repos: list[CodeRepo] = []
|
|
130
|
+
for name, table in tables.items():
|
|
131
|
+
where = f' in "[atlas.repos.{name}]"'
|
|
132
|
+
if not _REPO_NAME.fullmatch(name) or not isinstance(table, dict):
|
|
133
|
+
self.problem(
|
|
134
|
+
"invalid-setting",
|
|
135
|
+
f'"{name}" is not a usable repo entry. Use "[atlas.repos.<name>]" with '
|
|
136
|
+
"letters, digits, dots, hyphens or underscores in the name.",
|
|
137
|
+
)
|
|
138
|
+
continue
|
|
139
|
+
self.unknown_keys(table, _REPO_KEYS, where)
|
|
140
|
+
hint = self.string(table, "path", where) if "path" in table else None
|
|
141
|
+
repos.append(CodeRepo(name, hint))
|
|
142
|
+
return tuple(repos)
|
|
143
|
+
|
|
144
|
+
def references(self, tables: object) -> tuple[Reference, ...]:
|
|
145
|
+
if not isinstance(tables, dict):
|
|
146
|
+
self.problem(
|
|
147
|
+
"invalid-setting",
|
|
148
|
+
'Name each referenced atlas with its own "[references.<atlas>]" table.',
|
|
149
|
+
)
|
|
150
|
+
return ()
|
|
151
|
+
references: list[Reference] = []
|
|
152
|
+
for name, table in tables.items():
|
|
153
|
+
where = f' in "[references.{name}]"'
|
|
154
|
+
if not _REPO_NAME.fullmatch(name) or not isinstance(table, dict):
|
|
155
|
+
self.problem(
|
|
156
|
+
"invalid-setting",
|
|
157
|
+
f'"{name}" is not a usable reference. Use "[references.<atlas>]" with the '
|
|
158
|
+
"other atlas's name.",
|
|
159
|
+
)
|
|
160
|
+
continue
|
|
161
|
+
self.unknown_keys(table, _REFERENCE_KEYS, where)
|
|
162
|
+
hint = self.string(table, "path", where) if "path" in table else None
|
|
163
|
+
references.append(Reference(name, hint))
|
|
164
|
+
return tuple(references)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def parse_config(text: str) -> tuple[Config | None, tuple[Problem, ...]]:
|
|
168
|
+
"""Read the settings. Returns no config when any setting is unusable."""
|
|
169
|
+
reader = _Reader()
|
|
170
|
+
try:
|
|
171
|
+
data = tomllib.loads(text)
|
|
172
|
+
except tomllib.TOMLDecodeError as error:
|
|
173
|
+
reader.problem("invalid-toml", f"The file is not valid TOML: {error}. Fix the syntax.")
|
|
174
|
+
return None, tuple(reader.problems)
|
|
175
|
+
|
|
176
|
+
reader.unknown_keys(data, _TOP_KEYS, "")
|
|
177
|
+
wm_version = reader.string(data, "wm_version")
|
|
178
|
+
record_format = reader.format_number(data)
|
|
179
|
+
default_review = reader.review_level(data)
|
|
180
|
+
agent_tools = reader.strings(data, "agent_tools")
|
|
181
|
+
commit_scopes = reader.strings(data, "commit_scopes") if "commit_scopes" in data else None
|
|
182
|
+
|
|
183
|
+
atlas_name: str | None = None
|
|
184
|
+
repos: tuple[CodeRepo, ...] = ()
|
|
185
|
+
if "atlas" in data:
|
|
186
|
+
atlas = data["atlas"]
|
|
187
|
+
if isinstance(atlas, dict):
|
|
188
|
+
reader.unknown_keys(atlas, _ATLAS_KEYS, ' in "[atlas]"')
|
|
189
|
+
atlas_name = reader.string(atlas, "name", ' in "[atlas]"')
|
|
190
|
+
repos = reader.repos(atlas)
|
|
191
|
+
else:
|
|
192
|
+
reader.problem("invalid-setting", 'Write the atlas settings as an "[atlas]" table.')
|
|
193
|
+
references = reader.references(data["references"]) if "references" in data else ()
|
|
194
|
+
if atlas_name is not None and atlas_name in {reference.atlas for reference in references}:
|
|
195
|
+
reader.problem("invalid-setting", "An atlas can't reference itself. Remove the reference.")
|
|
196
|
+
|
|
197
|
+
if (
|
|
198
|
+
reader.problems
|
|
199
|
+
or wm_version is None
|
|
200
|
+
or record_format is None
|
|
201
|
+
or default_review is None
|
|
202
|
+
or agent_tools is None
|
|
203
|
+
):
|
|
204
|
+
return None, tuple(reader.problems)
|
|
205
|
+
config = Config(
|
|
206
|
+
wm_version,
|
|
207
|
+
record_format,
|
|
208
|
+
default_review,
|
|
209
|
+
commit_scopes,
|
|
210
|
+
agent_tools,
|
|
211
|
+
atlas_name,
|
|
212
|
+
repos,
|
|
213
|
+
references,
|
|
214
|
+
)
|
|
215
|
+
return config, ()
|
waymark/record/deltas.py
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
"""Deltas: a change's edits to one spec, and how they merge into it.
|
|
2
|
+
|
|
3
|
+
A delta adds, modifies or removes requirements. It may also carry the spec's
|
|
4
|
+
title, purpose and repos; it must carry the purpose when it creates the spec.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
|
|
10
|
+
from waymark.record.outline import collect_sections, parse_facts, require_title, split_names
|
|
11
|
+
from waymark.record.problems import Problem
|
|
12
|
+
from waymark.record.specs import (
|
|
13
|
+
PURPOSE,
|
|
14
|
+
REPOS_FACT,
|
|
15
|
+
REQUIREMENTS,
|
|
16
|
+
Requirement,
|
|
17
|
+
Spec,
|
|
18
|
+
named_blocks,
|
|
19
|
+
parse_requirements,
|
|
20
|
+
parse_spec,
|
|
21
|
+
requirement_key,
|
|
22
|
+
)
|
|
23
|
+
from waymark.record.text import Document
|
|
24
|
+
|
|
25
|
+
ADDED = "Added requirements"
|
|
26
|
+
MODIFIED = "Modified requirements"
|
|
27
|
+
REMOVED = "Removed requirements"
|
|
28
|
+
|
|
29
|
+
_REASON = re.compile(r"^Reason:\s*(\S.*)$")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class Removal:
|
|
34
|
+
"""A requirement a delta removes, and why."""
|
|
35
|
+
|
|
36
|
+
name: str
|
|
37
|
+
reason: str
|
|
38
|
+
index: int
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def key(self) -> str:
|
|
42
|
+
return requirement_key(self.name)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class Delta:
|
|
47
|
+
"""A change's edits to one spec."""
|
|
48
|
+
|
|
49
|
+
domain: str
|
|
50
|
+
doc: Document
|
|
51
|
+
title: str
|
|
52
|
+
repos: tuple[str, ...] | None
|
|
53
|
+
purpose: str | None
|
|
54
|
+
added: tuple[Requirement, ...]
|
|
55
|
+
modified: tuple[Requirement, ...]
|
|
56
|
+
removed: tuple[Removal, ...]
|
|
57
|
+
problems: tuple[Problem, ...]
|
|
58
|
+
|
|
59
|
+
def touched(self) -> tuple[tuple[str, str], ...]:
|
|
60
|
+
"""The key and name of every requirement this delta adds, modifies or removes."""
|
|
61
|
+
named = [(item.key, item.name) for item in (*self.added, *self.modified)]
|
|
62
|
+
named += [(item.key, item.name) for item in self.removed]
|
|
63
|
+
return tuple(named)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@dataclass(frozen=True)
|
|
67
|
+
class Merge:
|
|
68
|
+
"""The result of merging a delta: the spec's new text, or why it doesn't apply."""
|
|
69
|
+
|
|
70
|
+
text: str | None
|
|
71
|
+
problems: tuple[Problem, ...]
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _parse_removals(doc: Document, problems: list[Problem]) -> tuple[Removal, ...]:
|
|
75
|
+
sections = {section.title.casefold(): section for section in doc.sections(2)}
|
|
76
|
+
parent = sections.get(REMOVED.casefold())
|
|
77
|
+
if parent is None:
|
|
78
|
+
return ()
|
|
79
|
+
removals: list[Removal] = []
|
|
80
|
+
for name, section in named_blocks(doc, parent, problems):
|
|
81
|
+
lines = doc.lines[section.body_start : section.end]
|
|
82
|
+
reason = next((m.group(1).strip() for line in lines if (m := _REASON.match(line.text))), "")
|
|
83
|
+
if not reason:
|
|
84
|
+
problems.append(
|
|
85
|
+
Problem(
|
|
86
|
+
doc.path,
|
|
87
|
+
section.start + 1,
|
|
88
|
+
"removal-without-reason",
|
|
89
|
+
f'Removing "{name}" needs a reason. Add a "Reason: <why>" line under it.',
|
|
90
|
+
)
|
|
91
|
+
)
|
|
92
|
+
removals.append(Removal(name, reason, section.start))
|
|
93
|
+
return tuple(removals)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def parse_delta(domain: str, doc: Document) -> Delta:
|
|
97
|
+
"""Read a delta file."""
|
|
98
|
+
problems: list[Problem] = []
|
|
99
|
+
title = require_title(doc, problems)
|
|
100
|
+
facts = parse_facts(doc, {REPOS_FACT}, problems, prose=False)
|
|
101
|
+
repos: tuple[str, ...] | None = None
|
|
102
|
+
if REPOS_FACT in facts:
|
|
103
|
+
repos = split_names(facts[REPOS_FACT].value)
|
|
104
|
+
if not repos:
|
|
105
|
+
problems.append(
|
|
106
|
+
Problem(
|
|
107
|
+
doc.path,
|
|
108
|
+
facts[REPOS_FACT].index + 1,
|
|
109
|
+
"empty-fact",
|
|
110
|
+
f'"{REPOS_FACT}:" names no repo. List the repos, or remove the line.',
|
|
111
|
+
)
|
|
112
|
+
)
|
|
113
|
+
sections = collect_sections(
|
|
114
|
+
doc, (), problems, optional=(PURPOSE, ADDED, MODIFIED, REMOVED), strict=True
|
|
115
|
+
)
|
|
116
|
+
purpose: str | None = None
|
|
117
|
+
if PURPOSE in sections:
|
|
118
|
+
purpose = doc.body(sections[PURPOSE])
|
|
119
|
+
if not purpose:
|
|
120
|
+
problems.append(
|
|
121
|
+
Problem(
|
|
122
|
+
doc.path,
|
|
123
|
+
sections[PURPOSE].start + 1,
|
|
124
|
+
"empty-section",
|
|
125
|
+
f'"## {PURPOSE}" is empty. Write the purpose, or remove the section.',
|
|
126
|
+
)
|
|
127
|
+
)
|
|
128
|
+
added = parse_requirements(doc, sections[ADDED], problems) if ADDED in sections else ()
|
|
129
|
+
modified = parse_requirements(doc, sections[MODIFIED], problems) if MODIFIED in sections else ()
|
|
130
|
+
removed = _parse_removals(doc, problems)
|
|
131
|
+
|
|
132
|
+
named = [(item.key, item.name) for item in (*added, *modified)]
|
|
133
|
+
named += [(item.key, item.name) for item in removed]
|
|
134
|
+
seen: set[str] = set()
|
|
135
|
+
for key, name in named:
|
|
136
|
+
if key in seen:
|
|
137
|
+
problems.append(
|
|
138
|
+
Problem(
|
|
139
|
+
doc.path,
|
|
140
|
+
1,
|
|
141
|
+
"duplicate-requirement",
|
|
142
|
+
f'Requirement "{name}" appears more than once in this delta. '
|
|
143
|
+
"Keep one operation for it.",
|
|
144
|
+
)
|
|
145
|
+
)
|
|
146
|
+
seen.add(key)
|
|
147
|
+
if not seen and purpose is None and repos is None:
|
|
148
|
+
problems.append(
|
|
149
|
+
Problem(
|
|
150
|
+
doc.path,
|
|
151
|
+
1,
|
|
152
|
+
"empty-delta",
|
|
153
|
+
f'The delta changes nothing. Add a "## {ADDED}", "## {MODIFIED}" or '
|
|
154
|
+
f'"## {REMOVED}" section with at least one requirement.',
|
|
155
|
+
)
|
|
156
|
+
)
|
|
157
|
+
return Delta(domain, doc, title, repos, purpose, added, modified, removed, tuple(problems))
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def delta_mismatches(spec: Spec | None, delta: Delta) -> tuple[Problem, ...]:
|
|
161
|
+
"""Why a delta doesn't apply to the spec as it now stands; empty when it does."""
|
|
162
|
+
path = delta.doc.path
|
|
163
|
+
problems: list[Problem] = []
|
|
164
|
+
if spec is not None and spec.problems:
|
|
165
|
+
return (
|
|
166
|
+
Problem(
|
|
167
|
+
path,
|
|
168
|
+
1,
|
|
169
|
+
"spec-unreadable",
|
|
170
|
+
f'The spec "{spec.domain}" has format problems, so no delta can merge into it. '
|
|
171
|
+
"Fix the spec first.",
|
|
172
|
+
),
|
|
173
|
+
)
|
|
174
|
+
if spec is None and delta.purpose is None:
|
|
175
|
+
problems.append(
|
|
176
|
+
Problem(
|
|
177
|
+
path,
|
|
178
|
+
1,
|
|
179
|
+
"delta-without-purpose",
|
|
180
|
+
f'This delta creates the spec "{delta.domain}", so it must say what the spec '
|
|
181
|
+
f'is for. Add a "## {PURPOSE}" section.',
|
|
182
|
+
)
|
|
183
|
+
)
|
|
184
|
+
for requirement in delta.added:
|
|
185
|
+
if spec is not None and spec.requirement(requirement.name) is not None:
|
|
186
|
+
problems.append(
|
|
187
|
+
Problem(
|
|
188
|
+
path,
|
|
189
|
+
requirement.start + 1,
|
|
190
|
+
"delta-requirement-exists",
|
|
191
|
+
f'The spec already has a requirement "{requirement.name}". '
|
|
192
|
+
f'Move it under "## {MODIFIED}", or rename it.',
|
|
193
|
+
)
|
|
194
|
+
)
|
|
195
|
+
changed = [(item.name, item.start) for item in delta.modified]
|
|
196
|
+
changed += [(item.name, item.index) for item in delta.removed]
|
|
197
|
+
for name, index in changed:
|
|
198
|
+
if spec is None or spec.requirement(name) is None:
|
|
199
|
+
problems.append(
|
|
200
|
+
Problem(
|
|
201
|
+
path,
|
|
202
|
+
index + 1,
|
|
203
|
+
"delta-requirement-missing",
|
|
204
|
+
f'The spec "{delta.domain}" has no requirement "{name}" to modify or '
|
|
205
|
+
f'remove. Update the delta to match the spec, or move it under "## {ADDED}".',
|
|
206
|
+
)
|
|
207
|
+
)
|
|
208
|
+
return tuple(problems)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def delta_is_merged(spec: Spec | None, delta: Delta) -> bool:
|
|
212
|
+
"""Whether the spec already reads the way the delta says it should."""
|
|
213
|
+
if spec is None or spec.problems:
|
|
214
|
+
return False
|
|
215
|
+
for requirement in (*delta.added, *delta.modified):
|
|
216
|
+
living = spec.requirement(requirement.name)
|
|
217
|
+
if living is None or living.block != requirement.block:
|
|
218
|
+
return False
|
|
219
|
+
if any(spec.requirement(removal.name) is not None for removal in delta.removed):
|
|
220
|
+
return False
|
|
221
|
+
if delta.purpose is not None and spec.purpose != delta.purpose:
|
|
222
|
+
return False
|
|
223
|
+
return delta.repos is None or spec.repos == delta.repos
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _new_spec_text(delta: Delta) -> str:
|
|
227
|
+
newline = delta.doc.newline
|
|
228
|
+
lines = [f"# {delta.title}", ""]
|
|
229
|
+
if delta.repos:
|
|
230
|
+
lines += [f"{REPOS_FACT}: {', '.join(delta.repos)}", ""]
|
|
231
|
+
lines += [f"## {PURPOSE}", "", *(delta.purpose or "").split("\n"), "", f"## {REQUIREMENTS}"]
|
|
232
|
+
for requirement in delta.added:
|
|
233
|
+
lines += ["", *requirement.block]
|
|
234
|
+
return newline.join(lines) + newline
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def _reparse(spec: Spec, lines: list[str]) -> Document:
|
|
238
|
+
return Document.parse(spec.doc.path, "".join(lines))
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def _replace_and_remove(spec: Spec, delta: Delta, lines: list[str], newline: str) -> None:
|
|
242
|
+
edits: list[tuple[int, int, list[str]]] = []
|
|
243
|
+
for requirement in delta.modified:
|
|
244
|
+
target = spec.requirement(requirement.name)
|
|
245
|
+
assert target is not None
|
|
246
|
+
edits.append((target.start, target.end, [text + newline for text in requirement.block]))
|
|
247
|
+
for removal in delta.removed:
|
|
248
|
+
target = spec.requirement(removal.name)
|
|
249
|
+
assert target is not None
|
|
250
|
+
edits.append((target.start, target.extent_end, []))
|
|
251
|
+
for start, end, replacement in sorted(edits, key=lambda edit: edit[0], reverse=True):
|
|
252
|
+
lines[start:end] = replacement
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _append_added(spec: Spec, delta: Delta, lines: list[str], newline: str) -> None:
|
|
256
|
+
doc = _reparse(spec, lines)
|
|
257
|
+
section = next(s for s in doc.sections(2) if s.title.casefold() == REQUIREMENTS.casefold())
|
|
258
|
+
position = doc.content_end(section.start, section.end)
|
|
259
|
+
new: list[str] = []
|
|
260
|
+
for requirement in delta.added:
|
|
261
|
+
new += [newline, *(text + newline for text in requirement.block)]
|
|
262
|
+
lines[position:position] = new
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _set_purpose(spec: Spec, purpose: str, lines: list[str], newline: str) -> None:
|
|
266
|
+
doc = _reparse(spec, lines)
|
|
267
|
+
section = next(s for s in doc.sections(2) if s.title.casefold() == PURPOSE.casefold())
|
|
268
|
+
end = doc.content_end(section.body_start, section.end)
|
|
269
|
+
start = section.body_start
|
|
270
|
+
while start < end and doc.lines[start].is_blank:
|
|
271
|
+
start += 1
|
|
272
|
+
lines[start:end] = [text + newline for text in purpose.split("\n")]
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def _set_repos(spec: Spec, repos: tuple[str, ...], lines: list[str], newline: str) -> None:
|
|
276
|
+
doc = _reparse(spec, lines)
|
|
277
|
+
fact_line = f"{REPOS_FACT}: {', '.join(repos)}{newline}"
|
|
278
|
+
facts = parse_facts(doc, {REPOS_FACT}, [], prose=True)
|
|
279
|
+
if REPOS_FACT in facts:
|
|
280
|
+
index = facts[REPOS_FACT].index
|
|
281
|
+
lines[index : index + 1] = [fact_line]
|
|
282
|
+
else:
|
|
283
|
+
title = doc.title
|
|
284
|
+
assert title is not None
|
|
285
|
+
lines[title.index + 1 : title.index + 1] = [newline, fact_line]
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def merge_delta(spec: Spec | None, delta: Delta) -> Merge:
|
|
289
|
+
"""Merge a delta into its spec, or create the spec when there is none.
|
|
290
|
+
|
|
291
|
+
Only the lines of the requirements the delta names change; every other line
|
|
292
|
+
of the spec, and its line endings, stay as they are.
|
|
293
|
+
"""
|
|
294
|
+
problems = (*delta.problems, *delta_mismatches(spec, delta))
|
|
295
|
+
if problems:
|
|
296
|
+
return Merge(None, tuple(problems))
|
|
297
|
+
if spec is None:
|
|
298
|
+
return Merge(_new_spec_text(delta), ())
|
|
299
|
+
|
|
300
|
+
newline = spec.doc.newline
|
|
301
|
+
lines = spec.doc.raw_lines()
|
|
302
|
+
if lines and not spec.doc.lines[-1].ending:
|
|
303
|
+
lines[-1] += newline
|
|
304
|
+
_replace_and_remove(spec, delta, lines, newline)
|
|
305
|
+
if delta.added:
|
|
306
|
+
_append_added(spec, delta, lines, newline)
|
|
307
|
+
if delta.purpose is not None:
|
|
308
|
+
_set_purpose(spec, delta.purpose, lines, newline)
|
|
309
|
+
if delta.repos is not None:
|
|
310
|
+
_set_repos(spec, delta.repos, lines, newline)
|
|
311
|
+
while len(lines) > 1 and not lines[-1].strip():
|
|
312
|
+
lines.pop()
|
|
313
|
+
|
|
314
|
+
text = "".join(lines)
|
|
315
|
+
merged = parse_spec(spec.domain, Document.parse(spec.doc.path, text))
|
|
316
|
+
if merged.problems:
|
|
317
|
+
return Merge(None, merged.problems)
|
|
318
|
+
return Merge(text, ())
|
waymark/record/design.py
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""Designs: how a change will be built, and the decisions it makes."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from waymark.record.outline import collect_sections, content, require_title
|
|
8
|
+
from waymark.record.problems import Problem
|
|
9
|
+
from waymark.record.text import Document
|
|
10
|
+
|
|
11
|
+
CONTEXT = "Context"
|
|
12
|
+
APPROACH = "Approach"
|
|
13
|
+
DECISIONS = "Decisions"
|
|
14
|
+
RISKS = "Risks and trade-offs"
|
|
15
|
+
REQUIRED_SECTIONS = (CONTEXT, APPROACH, DECISIONS, RISKS)
|
|
16
|
+
DECISION_PARTS = ("Options", "Choice", "Why")
|
|
17
|
+
|
|
18
|
+
_DECISION = re.compile(r"^Decision:\s*(\S.*)$")
|
|
19
|
+
_PART = re.compile(r"^\s*(?:[-*]\s+)?(Options|Choice|Why):")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(frozen=True)
|
|
23
|
+
class Decision:
|
|
24
|
+
"""One decision: the options, the choice and why."""
|
|
25
|
+
|
|
26
|
+
name: str
|
|
27
|
+
text: str
|
|
28
|
+
index: int
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True)
|
|
32
|
+
class Design:
|
|
33
|
+
"""A change's design."""
|
|
34
|
+
|
|
35
|
+
doc: Document
|
|
36
|
+
title: str
|
|
37
|
+
sections: Mapping[str, str]
|
|
38
|
+
decisions: tuple[Decision, ...]
|
|
39
|
+
problems: tuple[Problem, ...]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def parse_design(doc: Document) -> Design:
|
|
43
|
+
"""Read a design."""
|
|
44
|
+
problems: list[Problem] = []
|
|
45
|
+
title = require_title(doc, problems)
|
|
46
|
+
found = collect_sections(doc, REQUIRED_SECTIONS, problems)
|
|
47
|
+
sections = {name: content(doc, found, name, problems) for name in REQUIRED_SECTIONS}
|
|
48
|
+
|
|
49
|
+
decisions: list[Decision] = []
|
|
50
|
+
if DECISIONS in found:
|
|
51
|
+
parent = found[DECISIONS]
|
|
52
|
+
for section in doc.sections(3, parent.body_start, parent.end):
|
|
53
|
+
match = _DECISION.match(section.title)
|
|
54
|
+
if match is None:
|
|
55
|
+
problems.append(
|
|
56
|
+
Problem(
|
|
57
|
+
doc.path,
|
|
58
|
+
section.start + 1,
|
|
59
|
+
"decision-format",
|
|
60
|
+
f'"{section.title}" is not a decision heading. '
|
|
61
|
+
'Write it as "Decision: <name>".',
|
|
62
|
+
)
|
|
63
|
+
)
|
|
64
|
+
continue
|
|
65
|
+
lines = doc.lines[section.body_start : section.end]
|
|
66
|
+
parts = {m.group(1) for line in lines if (m := _PART.match(line.text))}
|
|
67
|
+
missing = [part for part in DECISION_PARTS if part not in parts]
|
|
68
|
+
if missing:
|
|
69
|
+
wanted = ", ".join(f'"{part}:"' for part in missing)
|
|
70
|
+
problems.append(
|
|
71
|
+
Problem(
|
|
72
|
+
doc.path,
|
|
73
|
+
section.start + 1,
|
|
74
|
+
"decision-incomplete",
|
|
75
|
+
f'Decision "{match.group(1).strip()}" gives the options, the choice and '
|
|
76
|
+
f"why. Add a line starting with {wanted}.",
|
|
77
|
+
)
|
|
78
|
+
)
|
|
79
|
+
decisions.append(Decision(match.group(1).strip(), doc.body(section), section.start))
|
|
80
|
+
return Design(doc, title, sections, tuple(decisions), tuple(problems))
|