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