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,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, ()
@@ -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, ())
@@ -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))