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/edits.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""The edits wm makes to record files: the lines it owns, and nothing else.
|
|
2
|
+
|
|
3
|
+
Every function takes a parsed artifact and returns the file's new text. Lines
|
|
4
|
+
that aren't touched come back byte for byte, with their line endings.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
from collections.abc import Sequence
|
|
9
|
+
|
|
10
|
+
from waymark.record.outline import parse_facts
|
|
11
|
+
from waymark.record.proposal import ACCEPTED, OUTCOME, OWNER, PATH, SYNCED, Proposal
|
|
12
|
+
from waymark.record.tasks import Tasks
|
|
13
|
+
from waymark.record.text import Document
|
|
14
|
+
|
|
15
|
+
_BOX = re.compile(r"^- \[[ xX]\]")
|
|
16
|
+
_FORMAT_LINE = re.compile(r"^record_format\s*=\s*\d+", re.MULTILINE)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _lines(doc: Document) -> list[str]:
|
|
20
|
+
"""The file's lines, each ending in a line break."""
|
|
21
|
+
lines = doc.raw_lines()
|
|
22
|
+
if lines and not doc.lines[-1].ending:
|
|
23
|
+
lines[-1] += doc.newline
|
|
24
|
+
return lines
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def edit_item(
|
|
28
|
+
tasks: Tasks,
|
|
29
|
+
number: str,
|
|
30
|
+
*,
|
|
31
|
+
ticked: bool | None = None,
|
|
32
|
+
remove: Sequence[str] = (),
|
|
33
|
+
add: Sequence[str] = (),
|
|
34
|
+
) -> str:
|
|
35
|
+
"""Change one item's evidence: its tick, its labeled lines, and new lines at its end."""
|
|
36
|
+
item = tasks.item(number)
|
|
37
|
+
assert item is not None
|
|
38
|
+
newline = tasks.doc.newline
|
|
39
|
+
lines = _lines(tasks.doc)
|
|
40
|
+
lines[item.end : item.end] = [f" - {text}{newline}" for text in add]
|
|
41
|
+
spans = sorted((item.spans[label] for label in remove if label in item.spans), reverse=True)
|
|
42
|
+
for start, end in spans:
|
|
43
|
+
del lines[start:end]
|
|
44
|
+
if ticked is not None:
|
|
45
|
+
mark = "x" if ticked else " "
|
|
46
|
+
lines[item.index] = _BOX.sub(f"- [{mark}]", lines[item.index], count=1)
|
|
47
|
+
return "".join(lines)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def set_fact(proposal: Proposal, key: str, line: str | None) -> str:
|
|
51
|
+
"""Write, replace or remove one of wm's fact lines under a proposal's title."""
|
|
52
|
+
doc = proposal.doc
|
|
53
|
+
newline = doc.newline
|
|
54
|
+
lines = _lines(doc)
|
|
55
|
+
facts = parse_facts(doc, {OWNER, PATH, ACCEPTED, SYNCED}, [], prose=True)
|
|
56
|
+
if key in facts:
|
|
57
|
+
index = facts[key].index
|
|
58
|
+
lines[index : index + 1] = [] if line is None else [line + newline]
|
|
59
|
+
elif line is not None:
|
|
60
|
+
last = max(fact.index for fact in facts.values())
|
|
61
|
+
lines[last + 1 : last + 1] = [line + newline]
|
|
62
|
+
return "".join(lines)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def set_outcome(proposal: Proposal, outcome: str) -> str:
|
|
66
|
+
"""Write the outcome section, replacing one that is already there."""
|
|
67
|
+
doc = proposal.doc
|
|
68
|
+
newline = doc.newline
|
|
69
|
+
lines = _lines(doc)
|
|
70
|
+
body = [f"## {OUTCOME}{newline}", newline, *(text + newline for text in outcome.split("\n"))]
|
|
71
|
+
section = next((s for s in doc.sections(2) if s.title.casefold() == OUTCOME.casefold()), None)
|
|
72
|
+
if section is None:
|
|
73
|
+
while lines and not lines[-1].strip():
|
|
74
|
+
lines.pop()
|
|
75
|
+
return "".join([*lines, newline, *body])
|
|
76
|
+
trailing = [newline] if section.end < len(lines) else []
|
|
77
|
+
lines[section.start : section.end] = [*body, *trailing]
|
|
78
|
+
return "".join(lines)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def set_record_format(config_text: str, number: int) -> str:
|
|
82
|
+
"""Advance the record format number in the settings, leaving every other line alone."""
|
|
83
|
+
assert _FORMAT_LINE.search(config_text) is not None
|
|
84
|
+
return _FORMAT_LINE.sub(f"record_format = {number}", config_text, count=1)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def replace_spans(doc: Document, replacements: dict[tuple[int, int, int], str]) -> str:
|
|
88
|
+
"""Replace spans of text inside lines; keys are (line index, start, end)."""
|
|
89
|
+
lines = doc.raw_lines()
|
|
90
|
+
offset = 1 if doc.bom else 0
|
|
91
|
+
for (index, start, end), text in sorted(replacements.items(), reverse=True):
|
|
92
|
+
shift = offset if index == 0 else 0
|
|
93
|
+
line = lines[index]
|
|
94
|
+
lines[index] = line[: start + shift] + text + line[end + shift :]
|
|
95
|
+
return "".join(lines)
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Gate evidence in a record file: the lines only wm writes.
|
|
2
|
+
|
|
3
|
+
Used to tell whether an edit adds, changes or removes evidence. The evidence
|
|
4
|
+
is the ticks, blockers, spec gaps and review records in a task list, and the
|
|
5
|
+
acceptance, synced and override lines in a proposal.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import re
|
|
9
|
+
from collections import Counter
|
|
10
|
+
|
|
11
|
+
from waymark.record.changes import PROPOSAL_FILE, TASKS_FILE
|
|
12
|
+
from waymark.record.tasks import is_evidence_line
|
|
13
|
+
from waymark.record.text import Document
|
|
14
|
+
|
|
15
|
+
_ITEM = re.compile(r"^- \[([ xX])\] (\d+\.\d+)\s")
|
|
16
|
+
_PROPOSAL_EVIDENCE = re.compile(r"^(Accepted|Synced|Review override):")
|
|
17
|
+
_NOTE = re.compile(r"^ [-*] Note: \S")
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def evidence(relative: str, text: str) -> Counter[str]:
|
|
21
|
+
"""Every piece of evidence in a record file, each named so it can be reported."""
|
|
22
|
+
name = relative.rsplit("/", 1)[-1]
|
|
23
|
+
found: Counter[str] = Counter()
|
|
24
|
+
doc = Document.parse(relative, text)
|
|
25
|
+
if name == TASKS_FILE:
|
|
26
|
+
number = "?"
|
|
27
|
+
for line in doc.lines:
|
|
28
|
+
if line.in_fence:
|
|
29
|
+
continue
|
|
30
|
+
item = _ITEM.match(line.text)
|
|
31
|
+
if item:
|
|
32
|
+
number = item.group(2)
|
|
33
|
+
if item.group(1) != " ":
|
|
34
|
+
found[f"the tick on item {number}"] += 1
|
|
35
|
+
elif is_evidence_line(line.text):
|
|
36
|
+
found[f'"{line.text.strip()[2:]}" under item {number}'] += 1
|
|
37
|
+
elif name == PROPOSAL_FILE:
|
|
38
|
+
for line in doc.lines:
|
|
39
|
+
if not line.in_fence and _PROPOSAL_EVIDENCE.match(line.text):
|
|
40
|
+
found[f'the "{line.text.strip()}" line'] += 1
|
|
41
|
+
return found
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def evidence_changes(relative: str, before: str, after: str) -> list[str]:
|
|
45
|
+
"""The evidence an edit would add or take away; empty when it leaves evidence alone."""
|
|
46
|
+
old, new = evidence(relative, before), evidence(relative, after)
|
|
47
|
+
added = [f"adds {name}" for name in sorted((new - old).elements())]
|
|
48
|
+
removed = [f"removes {name}" for name in sorted((old - new).elements())]
|
|
49
|
+
return added + removed
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def only_adds_notes(before: str, after: str) -> bool:
|
|
53
|
+
"""Whether an edit to a task list does nothing but add note lines."""
|
|
54
|
+
old = Counter(Document.parse("", before).raw_lines())
|
|
55
|
+
new = Counter(Document.parse("", after).raw_lines())
|
|
56
|
+
if old - new:
|
|
57
|
+
return False
|
|
58
|
+
return all(_NOTE.match(line) or line.startswith(" ") for line in (new - old).elements())
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Explorations: saved thinking on a topic, whose conclusion says where it went."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from waymark.record.outline import collect_sections, require_title
|
|
8
|
+
from waymark.record.problems import Problem
|
|
9
|
+
from waymark.record.text import Document
|
|
10
|
+
|
|
11
|
+
CONTEXT = "Context"
|
|
12
|
+
QUESTIONS = "Questions"
|
|
13
|
+
APPROACHES = "Approaches"
|
|
14
|
+
CONCLUSION = "Conclusion"
|
|
15
|
+
RELATED = "Related"
|
|
16
|
+
REQUIRED_SECTIONS = (CONTEXT, QUESTIONS, APPROACHES, CONCLUSION, RELATED)
|
|
17
|
+
|
|
18
|
+
_PARKED = re.compile(r"^Parked:\s*(.*)$")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class Exploration:
|
|
23
|
+
"""A saved exploration.
|
|
24
|
+
|
|
25
|
+
``parked`` is the reason from a ``Parked:`` conclusion. ``conclusion_links``
|
|
26
|
+
are the link targets in the conclusion, in order.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
name: str
|
|
30
|
+
doc: Document
|
|
31
|
+
title: str
|
|
32
|
+
sections: Mapping[str, str]
|
|
33
|
+
conclusion: str
|
|
34
|
+
parked: str | None
|
|
35
|
+
conclusion_links: tuple[str, ...]
|
|
36
|
+
problems: tuple[Problem, ...]
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def parse_exploration(name: str, doc: Document) -> Exploration:
|
|
40
|
+
"""Read an exploration."""
|
|
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
|
+
conclusion = sections[CONCLUSION]
|
|
47
|
+
parked: str | None = None
|
|
48
|
+
links: tuple[str, ...] = ()
|
|
49
|
+
if CONCLUSION in found:
|
|
50
|
+
section = found[CONCLUSION]
|
|
51
|
+
links = tuple(
|
|
52
|
+
link.target for link in doc.links() if section.body_start <= link.index < section.end
|
|
53
|
+
)
|
|
54
|
+
match = _PARKED.match(conclusion)
|
|
55
|
+
if match:
|
|
56
|
+
parked = match.group(1).strip()
|
|
57
|
+
if not parked:
|
|
58
|
+
problems.append(
|
|
59
|
+
Problem(
|
|
60
|
+
doc.path,
|
|
61
|
+
section.start + 1,
|
|
62
|
+
"parked-without-reason",
|
|
63
|
+
'A parked exploration says why. Write "Parked: <reason>".',
|
|
64
|
+
)
|
|
65
|
+
)
|
|
66
|
+
return Exploration(name, doc, title, sections, conclusion, parked, links, tuple(problems))
|
waymark/record/files.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""Reading the record's files and folders.
|
|
2
|
+
|
|
3
|
+
Files are read as UTF-8 and kept exactly as they are on disk, line endings
|
|
4
|
+
included. Paths handed in and out are relative to the record's root and use
|
|
5
|
+
forward slashes.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
from waymark.record.problems import WHOLE_FILE, Problem
|
|
12
|
+
from waymark.record.text import Document
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class Entry:
|
|
17
|
+
"""A file or folder inside a record folder."""
|
|
18
|
+
|
|
19
|
+
name: str
|
|
20
|
+
is_dir: bool
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class RecordFiles:
|
|
24
|
+
"""The files under one record root."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, root: Path) -> None:
|
|
27
|
+
self.root = root
|
|
28
|
+
|
|
29
|
+
def path(self, relative: str) -> Path:
|
|
30
|
+
return self.root.joinpath(*relative.split("/")) if relative else self.root
|
|
31
|
+
|
|
32
|
+
def is_file(self, relative: str) -> bool:
|
|
33
|
+
return self.path(relative).is_file()
|
|
34
|
+
|
|
35
|
+
def entries(self, relative: str) -> tuple[Entry, ...]:
|
|
36
|
+
"""A folder's files and folders, sorted by name; hidden entries are left out."""
|
|
37
|
+
folder = self.path(relative)
|
|
38
|
+
if not folder.is_dir():
|
|
39
|
+
return ()
|
|
40
|
+
found = [
|
|
41
|
+
Entry(child.name, child.is_dir())
|
|
42
|
+
for child in folder.iterdir()
|
|
43
|
+
if not child.name.startswith(".")
|
|
44
|
+
]
|
|
45
|
+
return tuple(sorted(found, key=lambda entry: entry.name))
|
|
46
|
+
|
|
47
|
+
def read(self, relative: str, problems: list[Problem]) -> str | None:
|
|
48
|
+
"""A file's text; a file that can't be read as UTF-8 is reported as a problem."""
|
|
49
|
+
try:
|
|
50
|
+
return self.path(relative).read_bytes().decode("utf-8")
|
|
51
|
+
except UnicodeDecodeError:
|
|
52
|
+
problems.append(
|
|
53
|
+
Problem(
|
|
54
|
+
relative,
|
|
55
|
+
WHOLE_FILE,
|
|
56
|
+
"not-utf8",
|
|
57
|
+
"The file is not valid UTF-8. Save it again as UTF-8.",
|
|
58
|
+
)
|
|
59
|
+
)
|
|
60
|
+
except OSError as error:
|
|
61
|
+
problems.append(
|
|
62
|
+
Problem(
|
|
63
|
+
relative,
|
|
64
|
+
WHOLE_FILE,
|
|
65
|
+
"unreadable",
|
|
66
|
+
f"The file can't be read ({error.strerror or error}). Check that it exists "
|
|
67
|
+
"and that you may read it.",
|
|
68
|
+
)
|
|
69
|
+
)
|
|
70
|
+
return None
|
|
71
|
+
|
|
72
|
+
def document(self, relative: str, problems: list[Problem]) -> Document | None:
|
|
73
|
+
"""A file parsed as markdown, or None when it can't be read."""
|
|
74
|
+
text = self.read(relative, problems)
|
|
75
|
+
return None if text is None else Document.parse(relative, text)
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""The acceptance fingerprint: a digest of everything an acceptance covers.
|
|
2
|
+
|
|
3
|
+
It covers what the human approved:
|
|
4
|
+
|
|
5
|
+
- the proposal, apart from the acceptance line and the outcome;
|
|
6
|
+
- every delta, and the design;
|
|
7
|
+
- each task item's definition (number, title, review level, criteria,
|
|
8
|
+
verification and repo), but none of its evidence;
|
|
9
|
+
- the living text of what the deltas modify or remove, so that another change
|
|
10
|
+
archiving into the same requirement withdraws this acceptance.
|
|
11
|
+
|
|
12
|
+
Line endings don't count, so two checkouts of one commit agree.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
import hashlib
|
|
16
|
+
from collections.abc import Mapping
|
|
17
|
+
|
|
18
|
+
from waymark.record.changes import Change
|
|
19
|
+
from waymark.record.specs import Spec
|
|
20
|
+
from waymark.record.terms import ReviewLevel
|
|
21
|
+
|
|
22
|
+
FINGERPRINT_LENGTH = 16
|
|
23
|
+
_ABSENT = "\x00absent"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _normalized(text: str) -> str:
|
|
27
|
+
return text.replace("\r\n", "\n").replace("\r", "\n")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def fingerprint_parts(
|
|
31
|
+
change: Change, specs: Mapping[str, Spec], default_review: ReviewLevel
|
|
32
|
+
) -> list[tuple[str, str]]:
|
|
33
|
+
"""The labeled pieces of text the fingerprint is made of, in a fixed order."""
|
|
34
|
+
parts: list[tuple[str, str]] = []
|
|
35
|
+
if change.proposal is not None:
|
|
36
|
+
parts.append(("proposal", change.proposal.accepted_text()))
|
|
37
|
+
if change.design is not None:
|
|
38
|
+
parts.append(("design", change.design.doc.text))
|
|
39
|
+
for domain in sorted(change.deltas):
|
|
40
|
+
delta = change.deltas[domain]
|
|
41
|
+
spec = specs.get(domain)
|
|
42
|
+
parts.append((f"delta:{domain}", delta.doc.text))
|
|
43
|
+
names = [item.name for item in delta.modified] + [item.name for item in delta.removed]
|
|
44
|
+
for name in sorted(names):
|
|
45
|
+
living = spec.requirement(name) if spec else None
|
|
46
|
+
text = "\n".join(living.block) if living else _ABSENT
|
|
47
|
+
parts.append((f"base:{domain}:{' '.join(name.split()).casefold()}", text))
|
|
48
|
+
if delta.purpose is not None:
|
|
49
|
+
parts.append((f"base-purpose:{domain}", spec.purpose if spec else _ABSENT))
|
|
50
|
+
if delta.repos is not None:
|
|
51
|
+
parts.append((f"base-repos:{domain}", ", ".join(spec.repos) if spec else _ABSENT))
|
|
52
|
+
for item in change.tasks.items if change.tasks else ():
|
|
53
|
+
definition = [
|
|
54
|
+
item.title,
|
|
55
|
+
item.level(default_review).value,
|
|
56
|
+
item.criteria if item.criteria is not None else _ABSENT,
|
|
57
|
+
item.verify if item.verify is not None else _ABSENT,
|
|
58
|
+
item.repo if item.repo is not None else _ABSENT,
|
|
59
|
+
]
|
|
60
|
+
parts.append((f"item:{item.number}", "\x00".join(definition)))
|
|
61
|
+
return parts
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def change_fingerprint(
|
|
65
|
+
change: Change, specs: Mapping[str, Spec], default_review: ReviewLevel
|
|
66
|
+
) -> str:
|
|
67
|
+
"""The fingerprint of a change as it now stands."""
|
|
68
|
+
digest = hashlib.sha256()
|
|
69
|
+
for label, text in fingerprint_parts(change, specs, default_review):
|
|
70
|
+
data = _normalized(text).encode("utf-8")
|
|
71
|
+
digest.update(f"{label}\x00{len(data)}\x00".encode())
|
|
72
|
+
digest.update(data)
|
|
73
|
+
return digest.hexdigest()[:FINGERPRINT_LENGTH]
|
waymark/record/git.py
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
"""What the record model asks git: where the repository is, and when things last changed.
|
|
2
|
+
|
|
3
|
+
Only local, read-only git commands are run. Nothing here clones, pulls, pushes
|
|
4
|
+
or touches the network.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import datetime
|
|
8
|
+
import subprocess
|
|
9
|
+
from collections.abc import Iterable
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class GitError(Exception):
|
|
14
|
+
"""Git is missing, or a git command failed."""
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _run(folder: Path, *arguments: str) -> str:
|
|
18
|
+
try:
|
|
19
|
+
result = subprocess.run(
|
|
20
|
+
["git", "-C", str(folder), "-c", "core.quotepath=off", *arguments],
|
|
21
|
+
capture_output=True,
|
|
22
|
+
encoding="utf-8",
|
|
23
|
+
errors="replace",
|
|
24
|
+
check=False,
|
|
25
|
+
)
|
|
26
|
+
except OSError as error:
|
|
27
|
+
raise GitError(
|
|
28
|
+
"git could not be run. Waymark needs git; install it and make sure it is on PATH."
|
|
29
|
+
) from error
|
|
30
|
+
if result.returncode != 0:
|
|
31
|
+
detail = result.stderr.strip() or f"exit code {result.returncode}"
|
|
32
|
+
raise GitError(f"git {arguments[0]} failed: {detail}")
|
|
33
|
+
return result.stdout
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def repository_root(folder: Path) -> Path | None:
|
|
37
|
+
"""The top folder of the git repository that contains a folder; None outside one."""
|
|
38
|
+
try:
|
|
39
|
+
return Path(_run(folder, "rev-parse", "--show-toplevel").strip())
|
|
40
|
+
except GitError:
|
|
41
|
+
return None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def user_name(folder: Path) -> str | None:
|
|
45
|
+
"""The name git signs commits with here; None when it isn't set."""
|
|
46
|
+
try:
|
|
47
|
+
return _run(folder, "config", "user.name").strip() or None
|
|
48
|
+
except GitError:
|
|
49
|
+
return None
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def current_branch(folder: Path) -> str | None:
|
|
53
|
+
"""The checked-out branch; None when HEAD is detached or this is not a repository."""
|
|
54
|
+
try:
|
|
55
|
+
return _run(folder, "branch", "--show-current").strip() or None
|
|
56
|
+
except GitError:
|
|
57
|
+
return None
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def version() -> str | None:
|
|
61
|
+
"""The installed git's version line; None when git can't be run."""
|
|
62
|
+
try:
|
|
63
|
+
return _run(Path.cwd(), "--version").strip() or None
|
|
64
|
+
except GitError:
|
|
65
|
+
return None
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def is_ignored(repository: Path, relative: str) -> bool:
|
|
69
|
+
"""Whether git ignores a path in a repository (relative to its top, with forward slashes)."""
|
|
70
|
+
try:
|
|
71
|
+
result = subprocess.run(
|
|
72
|
+
["git", "-C", str(repository), "check-ignore", "-q", "--no-index", "--", relative],
|
|
73
|
+
capture_output=True,
|
|
74
|
+
check=False,
|
|
75
|
+
)
|
|
76
|
+
except OSError:
|
|
77
|
+
return False
|
|
78
|
+
return result.returncode == 0
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def exclude(repository: Path, relative: str) -> None:
|
|
82
|
+
"""Keep a path out of this clone's commits, through its own exclude file.
|
|
83
|
+
|
|
84
|
+
The exclude file belongs to the clone and is never committed, so nothing
|
|
85
|
+
the project shares changes.
|
|
86
|
+
"""
|
|
87
|
+
where = Path(_run(repository, "rev-parse", "--git-path", "info/exclude").strip())
|
|
88
|
+
path = where if where.is_absolute() else repository / where
|
|
89
|
+
current = path.read_bytes().decode("utf-8", errors="replace") if path.is_file() else ""
|
|
90
|
+
separator = "" if not current or current.endswith("\n") else "\n"
|
|
91
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
92
|
+
with path.open("a", encoding="utf-8", newline="") as handle:
|
|
93
|
+
handle.write(f"{separator}/{relative}\n")
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def config_value(repository: Path, key: str) -> str | None:
|
|
97
|
+
"""A setting from this clone's own git config; None when it isn't set there."""
|
|
98
|
+
try:
|
|
99
|
+
return _run(repository, "config", "--local", "--get", key).strip() or None
|
|
100
|
+
except GitError:
|
|
101
|
+
return None
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def set_config(repository: Path, key: str, value: str) -> None:
|
|
105
|
+
"""Set a setting in this clone's own git config. Nothing shared changes."""
|
|
106
|
+
_run(repository, "config", "--local", key, value)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def default_hooks_folder(repository: Path) -> Path:
|
|
110
|
+
"""The folder git reads hooks from when ``core.hooksPath`` is not set."""
|
|
111
|
+
common = Path(_run(repository, "rev-parse", "--git-common-dir").strip())
|
|
112
|
+
return (common if common.is_absolute() else repository / common) / "hooks"
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def staged_paths(repository: Path) -> tuple[str, ...]:
|
|
116
|
+
"""The paths the next commit changes, relative to the repository's top."""
|
|
117
|
+
try:
|
|
118
|
+
listing = _run(repository, "diff", "--cached", "--name-only", "-z")
|
|
119
|
+
except GitError:
|
|
120
|
+
return ()
|
|
121
|
+
return tuple(path for path in listing.split("\0") if path)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def stage(repository: Path, paths: Iterable[str]) -> None:
|
|
125
|
+
"""Stage files for the next commit."""
|
|
126
|
+
_run(repository, "add", "--", *paths)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def stage_executable(repository: Path, paths: Iterable[str]) -> None:
|
|
130
|
+
"""Stage files with their executable bit, which a checkout on Windows can't set itself."""
|
|
131
|
+
_run(repository, "add", "--chmod=+x", "--", *paths)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def remote_url(repository: Path, remote: str = "origin") -> str | None:
|
|
135
|
+
"""A remote's URL as this clone's config has it; nothing is fetched."""
|
|
136
|
+
try:
|
|
137
|
+
return _run(repository, "remote", "get-url", remote).strip() or None
|
|
138
|
+
except GitError:
|
|
139
|
+
return None
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def last_changed(repository: Path, folders: Iterable[str]) -> dict[str, datetime.datetime]:
|
|
143
|
+
"""When each folder last changed in git's history.
|
|
144
|
+
|
|
145
|
+
Folders are given relative to the repository root, with forward slashes. A
|
|
146
|
+
folder with no commits yet is left out. One pass over the history answers
|
|
147
|
+
for every folder.
|
|
148
|
+
"""
|
|
149
|
+
wanted = {folder.strip("/") for folder in folders}
|
|
150
|
+
found: dict[str, datetime.datetime] = {}
|
|
151
|
+
if not wanted:
|
|
152
|
+
return found
|
|
153
|
+
try:
|
|
154
|
+
log = _run(repository, "log", "--format=@%cI", "--name-only", "--", *sorted(wanted))
|
|
155
|
+
except GitError:
|
|
156
|
+
return found
|
|
157
|
+
when: datetime.datetime | None = None
|
|
158
|
+
for line in log.splitlines():
|
|
159
|
+
if line.startswith("@"):
|
|
160
|
+
when = datetime.datetime.fromisoformat(line[1:])
|
|
161
|
+
elif line and when is not None:
|
|
162
|
+
for folder in wanted - found.keys():
|
|
163
|
+
if line == folder or line.startswith(f"{folder}/"):
|
|
164
|
+
found[folder] = when
|
|
165
|
+
if len(found) == len(wanted):
|
|
166
|
+
break
|
|
167
|
+
return found
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
"""The committed git hooks: where they live, what they are, and whether git uses them.
|
|
2
|
+
|
|
3
|
+
The hooks sit in ``.waymark/hooks/`` and every clone points git at them with
|
|
4
|
+
``core.hooksPath``. A repository that already uses another hook manager is
|
|
5
|
+
left alone.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import stat
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from enum import StrEnum
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from waymark.record import git, templates
|
|
14
|
+
|
|
15
|
+
HOOKS_DIR = ".waymark/hooks"
|
|
16
|
+
HOOKS = {"commit-msg": "hook-commit-msg", "pre-commit": "hook-pre-commit"}
|
|
17
|
+
"""Each hook's file name, and its template."""
|
|
18
|
+
|
|
19
|
+
_MANAGER_FILES = (
|
|
20
|
+
".husky",
|
|
21
|
+
".pre-commit-config.yaml",
|
|
22
|
+
"lefthook.yml",
|
|
23
|
+
"lefthook.yaml",
|
|
24
|
+
"lefthook.json",
|
|
25
|
+
".lefthook.yml",
|
|
26
|
+
".lefthook.yaml",
|
|
27
|
+
".overcommit.yml",
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class HooksState(StrEnum):
|
|
32
|
+
"""Whether this clone runs the committed hooks."""
|
|
33
|
+
|
|
34
|
+
SET = "set"
|
|
35
|
+
NOT_SET = "not-set"
|
|
36
|
+
ABSENT = "absent"
|
|
37
|
+
MANAGED = "managed"
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class HooksStatus:
|
|
42
|
+
"""Whether this clone runs the hooks; ``manager`` names another hook setup, if any."""
|
|
43
|
+
|
|
44
|
+
state: HooksState
|
|
45
|
+
manager: str | None = None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
ATTRIBUTES = f"{HOOKS_DIR}/.gitattributes"
|
|
49
|
+
_ATTRIBUTES_TEXT = (
|
|
50
|
+
"# Written by wm (Waymark): the hooks are shell scripts, which need LF line endings\n"
|
|
51
|
+
"# on every platform, whatever git's line-ending settings say.\n"
|
|
52
|
+
"* text eol=lf\n"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def hook_scripts() -> dict[str, str]:
|
|
57
|
+
"""Each committed hook script's path, relative to the repository's top, with its text."""
|
|
58
|
+
return {f"{HOOKS_DIR}/{name}": templates.render(source) for name, source in HOOKS.items()}
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def hook_files() -> dict[str, str]:
|
|
62
|
+
"""Every file in the hooks folder: the scripts, and the attributes that keep them LF."""
|
|
63
|
+
return {**hook_scripts(), ATTRIBUTES: _ATTRIBUTES_TEXT}
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def hook_manager(root: Path) -> str | None:
|
|
67
|
+
"""Another hook setup this repository already uses, in a few words; None when there is none."""
|
|
68
|
+
configured = git.config_value(root, "core.hooksPath")
|
|
69
|
+
if configured is not None and Path(configured).as_posix().rstrip("/") != HOOKS_DIR:
|
|
70
|
+
return f'core.hooksPath is set to "{configured}"'
|
|
71
|
+
for name in _MANAGER_FILES:
|
|
72
|
+
if (root / name).exists():
|
|
73
|
+
return f"the repository has {name}"
|
|
74
|
+
try:
|
|
75
|
+
folder = git.default_hooks_folder(root)
|
|
76
|
+
except git.GitError:
|
|
77
|
+
return None
|
|
78
|
+
for name in HOOKS:
|
|
79
|
+
if (folder / name).is_file():
|
|
80
|
+
return f"git already runs its own {name} hook"
|
|
81
|
+
return None
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def hooks_status(root: Path) -> HooksStatus:
|
|
85
|
+
"""Whether this clone runs the committed hooks."""
|
|
86
|
+
manager = hook_manager(root)
|
|
87
|
+
if manager is not None:
|
|
88
|
+
return HooksStatus(HooksState.MANAGED, manager)
|
|
89
|
+
if not all((root / path).is_file() for path in hook_scripts()):
|
|
90
|
+
return HooksStatus(HooksState.ABSENT)
|
|
91
|
+
configured = git.config_value(root, "core.hooksPath")
|
|
92
|
+
if configured is not None and Path(configured).as_posix().rstrip("/") == HOOKS_DIR:
|
|
93
|
+
return HooksStatus(HooksState.SET)
|
|
94
|
+
return HooksStatus(HooksState.NOT_SET)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def make_executable(root: Path) -> None:
|
|
98
|
+
"""Give the hook files their executable bit, which git needs to run them on Linux and macOS."""
|
|
99
|
+
for relative in hook_scripts():
|
|
100
|
+
path = root / relative
|
|
101
|
+
path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def read_message(path: Path) -> str:
|
|
105
|
+
"""A commit message file, as git wrote it."""
|
|
106
|
+
return path.read_bytes().decode("utf-8", errors="replace")
|