@rvdbreemen/adr-kit-opencode 0.55.1 → 0.57.0

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.
@@ -47,6 +47,7 @@ def rank_proposed(report: dict) -> list[dict]:
47
47
  linked = bool(isinstance(link, dict) and link.get("linked"))
48
48
  shipped = bool(item.get("documents_shipped"))
49
49
  ready = item.get("classification") == "ready-for-confirmation"
50
+ needs_human = item.get("classification") == "needs-human-input"
50
51
  open_questions = bool(item.get("open_questions"))
51
52
  age_days = _age_days(item, evaluated_on)
52
53
  quality = item.get("quality", {})
@@ -67,7 +68,14 @@ def rank_proposed(report: dict) -> list[dict]:
67
68
  # Proposed ADR that is sharp, unlinked, unshipped, not ready and asking
68
69
  # nothing has no work attached to it, and listing it teaches the reader
69
70
  # to skim the queue.
70
- signals = (linked, shipped, ready, open_questions, below_threshold)
71
+ # `needs_human` is here because the classification it names is the one
72
+ # that used to be `ready-for-confirmation`. A record whose References
73
+ # hold only a migration placeholder is unlinked, unshipped, above the
74
+ # quality threshold and asks no open question, so `ready` was its only
75
+ # signal; reporting the placeholder honestly would otherwise drop it out
76
+ # of the queue and make it LESS visible than saying nothing. Measured on
77
+ # ADR-042 with a placeholder: 0 candidates without this line.
78
+ signals = (linked, shipped, ready, open_questions, below_threshold, needs_human)
71
79
  if not any(signals):
72
80
  continue
73
81
 
@@ -80,6 +88,11 @@ def rank_proposed(report: dict) -> list[dict]:
80
88
  reasons.append("ready for confirmation")
81
89
  if open_questions:
82
90
  reasons.append("open human questions")
91
+ if needs_human and not open_questions:
92
+ # Before the unconditional age entry on purpose: the SessionStart
93
+ # block prints reasons[:2] and the auto-grill handoff reasons[:3],
94
+ # so a reason appended after it never reaches a human.
95
+ reasons.append("human input needed")
83
96
  if below_threshold:
84
97
  reasons.append(f"quality {quality_score:.3f} below {threshold:.2f}")
85
98
  reasons.append(f"age {age_days} days")
@@ -98,6 +111,7 @@ def rank_proposed(report: dict) -> list[dict]:
98
111
  -int(shipped),
99
112
  -int(ready),
100
113
  -int(open_questions),
114
+ -int(needs_human),
101
115
  -int(below_threshold),
102
116
  -age_days,
103
117
  quality_score,
@@ -190,6 +190,15 @@ def _section_text(content: str, heading: str) -> str:
190
190
  return m.group(1) if m else ""
191
191
 
192
192
 
193
+ # Same rule as bin/adr-lint: a heading with nothing under it is a hole, not a
194
+ # section. Emptiness only. A migration placeholder counts as content here by
195
+ # decision, not by oversight: an imported record must not fail a blocking gate
196
+ # on arrival (test_adr_policy.py, test_migration_discovery.py). adr-migrate
197
+ # reports the placeholders it wrote instead, which informs without refusing.
198
+ def _is_unfilled(body: str) -> bool:
199
+ return not any(ln.strip() for ln in body.splitlines())
200
+
201
+
193
202
  def gate_completeness(content: str) -> Dict:
194
203
  """Gate 1: Completeness (0.0-1.0).
195
204
 
@@ -216,9 +225,17 @@ def gate_completeness(content: str) -> Dict:
216
225
  pattern = _SECTION_PRESENCE_RE.get(section) or re.compile(
217
226
  r"^" + re.escape(section) + r"\b", re.MULTILINE
218
227
  )
228
+ # A heading with nothing under it is not a section (TASK-198). This loop
229
+ # used to test presence alone, while three checks further down already
230
+ # measured emptiness for Decision, Alternatives and Consequences. That
231
+ # split meant References or Related Decisions could be hollow and still
232
+ # score full marks here, and `adr accept --quality-threshold` reads this
233
+ # score. The placeholder case counts too: it is what adr-migrate writes
234
+ # into a heading it has to add.
219
235
  present = bool(pattern.search(content))
220
- checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = present
221
- if not present:
236
+ filled = present and not _is_unfilled(_section_text(content, section))
237
+ checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = filled
238
+ if not filled:
222
239
  missing_sections.append(section)
223
240
 
224
241
  score = 1.0
@@ -9,7 +9,7 @@ from pathlib import Path
9
9
  from typing import Dict, List, Optional, Sequence
10
10
 
11
11
  from adr_catalog import build_relationships, load_adr_records, normalize_adr_id
12
- from adr_format import all_open_questions
12
+ from adr_format import AdrFormatError, all_open_questions, placeholder_required_sections
13
13
  from adr_quality_core import QUALITY_THRESHOLD, score_path
14
14
 
15
15
 
@@ -85,6 +85,7 @@ FINDING_CODES = (
85
85
  "FORMAT_UNKNOWN",
86
86
  "FRONTMATTER_MALFORMED",
87
87
  "OPEN_QUESTION",
88
+ "SECTION_PLACEHOLDER_ONLY",
88
89
  "STATUS_UNKNOWN",
89
90
  "SUPERSESSION_STATE_INCONSISTENT",
90
91
  "VERIFIED_IN_CHANGED",
@@ -252,6 +253,62 @@ def _mechanical_findings(record: Dict) -> List[Dict[str, str]]:
252
253
  return sorted(findings, key=lambda item: item["code"])
253
254
 
254
255
 
256
+ def _record_path(record: Dict, adr_dir: Optional[Path] = None) -> Optional[Path]:
257
+ """Resolve a record's bare filename against the ADR directory, or None.
258
+
259
+ Records reach readiness with `path` set to a filename and no directory, and
260
+ the test suite passes records whose file does not exist at all. Both are
261
+ normal, so this answers "no path" rather than raising.
262
+ """
263
+ raw = record.get("path")
264
+ if not raw:
265
+ return None
266
+ path = Path(str(raw))
267
+ if not path.is_absolute() and adr_dir is not None and not path.exists():
268
+ path = Path(adr_dir) / path.name
269
+ return path if path.is_file() else None
270
+
271
+
272
+ def _placeholder_findings(
273
+ record: Dict, adr_dir: Optional[Path] = None
274
+ ) -> List[Dict[str, str]]:
275
+ """Required sections holding an adr-kit placeholder instead of an answer.
276
+
277
+ A migrated record reaches acceptance with `- TODO: add verifiable
278
+ references.` under `## References` and nothing refuses it: the completeness
279
+ gate treats a placeholder as content by decision, because an imported record
280
+ must not fail a blocking gate on arrival. The record then classifies
281
+ `ready-for-confirmation`, which is a lie about a record nobody has finished
282
+ writing. Saying so here reaches the operator before `adr accept` freezes it,
283
+ and readiness has no power to block, which is the point.
284
+
285
+ Empty sections are deliberately not reported: `bin/adr-lint` already fails
286
+ completeness on those, so acceptance refuses them without help.
287
+ """
288
+ path = _record_path(record, adr_dir)
289
+ if path is None:
290
+ return []
291
+ try:
292
+ text = path.read_text(encoding="utf-8", errors="replace")
293
+ except OSError:
294
+ return []
295
+ try:
296
+ sections = placeholder_required_sections(text, str(record.get("format", "")))
297
+ except AdrFormatError:
298
+ # 'hybrid' and 'unknown' are legal values of record["format"], and
299
+ # neither resolves to a required-section list. Nothing to say, and
300
+ # raising here would be invisible: bin/adr-guardian swallows the
301
+ # exception and returns 0, so the queue would just go stale.
302
+ return []
303
+ return [
304
+ {
305
+ "code": "SECTION_PLACEHOLDER_ONLY",
306
+ "message": f"## {title} holds a migration placeholder, not an answer.",
307
+ }
308
+ for title in sorted(sections)
309
+ ]
310
+
311
+
255
312
  def _classification(
256
313
  record: Dict,
257
314
  mechanical: Sequence[Dict[str, str]],
@@ -293,6 +350,7 @@ def readiness_for_record(
293
350
  }
294
351
  for question in record.get("open_questions", [])
295
352
  ]
353
+ human.extend(_placeholder_findings(record, adr_dir))
296
354
  # Three booleans used to stand in for quality here, which meant a vague ADR
297
355
  # and a sharp one scored identically as long as both had a decision line and
298
356
  # a verified_in. The real weighted scorer existed the whole time behind
package/bin/adr_schema.py CHANGED
@@ -43,7 +43,7 @@ def _load_sibling(name: str):
43
43
 
44
44
  _load_sibling("adr_format")
45
45
 
46
- from adr_format import SUPPORTED_PROFILES
46
+ from adr_format import SUPPORTED_PROFILES, adr_status, status_statement
47
47
 
48
48
  FRONTMATTER_FIELD_ORDER = (
49
49
  "id",
@@ -92,8 +92,13 @@ STATUS_SECTION_RE = re.compile(
92
92
  re.IGNORECASE | re.MULTILINE,
93
93
  )
94
94
  DATE_RE = re.compile(r"\b(\d{4}-\d{2}-\d{2})\b")
95
- SUPERSEDES_RE = re.compile(r"\bSupersedes\s+ADR-(\d{1,4})\b", re.IGNORECASE)
96
- SUPERSEDED_BY_RE = re.compile(r"\bSuperseded\s+by\s+ADR-(\d{1,4})\b", re.IGNORECASE)
95
+ # The optional `[` accepts the link-wrapped form real bodies use:
96
+ # "Superseded by [ADR-124](ADR-124-title.md)". Requiring a bare ADR-NNN meant
97
+ # superseded_by came back None on those records while the status was guessed
98
+ # separately, producing frontmatter that contradicted the prose it was inferred
99
+ # from (issue #118).
100
+ SUPERSEDES_RE = re.compile(r"\bSupersedes\s+\[?ADR-(\d{1,4})\b", re.IGNORECASE)
101
+ SUPERSEDED_BY_RE = re.compile(r"\bSuperseded\s+by\s+\[?ADR-(\d{1,4})\b", re.IGNORECASE)
97
102
 
98
103
 
99
104
  class FrontmatterError(Exception):
@@ -207,14 +212,27 @@ def infer_frontmatter(body: str, path: Optional[Path] = None) -> Dict:
207
212
  title_match = generic_title
208
213
  title = title_match.group(1).strip() if title_match else ""
209
214
 
210
- status_line = ""
211
- status_match = STATUS_SECTION_RE.search(body)
212
- if status_match:
213
- status_line = status_match.group(1).strip()
214
- status_word_match = re.match(r"([A-Za-z]+)", status_line)
215
- status = status_word_match.group(1).capitalize() if status_word_match else "Proposed"
215
+ # The same region the status word was read from, so the date and the
216
+ # successor beside it are recovered from that line rather than from a
217
+ # `## Status` section the record may not have (issue #118).
218
+ status_line = status_statement(body)
219
+ # One reader for the status word, shared with adr-index, adr-judge,
220
+ # adr-lint, adr-retire and adr-watch. It handles the `## Status` heading,
221
+ # the bold-inline `**Status:** X` form and a plain `Status: X` line, and it
222
+ # returns None on anything else.
223
+ #
224
+ # None must stay None. This used to default to "Proposed" whenever the one
225
+ # recognised shape did not match - and `re.match` also returns None for any
226
+ # line starting with `**`, `[` or `-`, so bold and link-wrapped statuses
227
+ # fell through too. `status` is the field that decides whether a decision is
228
+ # binding and injected, so guessing it downgraded Accepted records in
229
+ # silence, with exit 0. Both callers already handle an undetermined status
230
+ # honestly: adr_catalog reports STATUS_UNKNOWN, and migrate_text returns it
231
+ # as an issue and writes nothing (issue #118).
232
+ status_word = adr_status(body)
233
+ status = status_word.capitalize() if status_word else None
216
234
  if status not in VALID_STATUSES:
217
- status = "Proposed"
235
+ status = None
218
236
 
219
237
  date_match = DATE_RE.search(status_line)
220
238
  status_date = date_match.group(1) if date_match else None
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rvdbreemen/adr-kit-opencode",
3
- "version": "0.55.1",
3
+ "version": "0.57.0",
4
4
  "description": "Native OpenCode plugin for ADR Kit, backed by the shared deterministic Python engines.",
5
5
  "type": "module",
6
6
  "main": "./opencode/plugin.ts",
@@ -293,7 +293,14 @@ def main(argv: list[str] | None = None) -> int:
293
293
  print("Then verify the changes and:")
294
294
  print(" git add " + " ".join(staged))
295
295
  print(f' git commit -m "chore(release): v{version}"')
296
- print(f" git tag v{version}")
296
+ # Deliberately not "git tag": since ADR-042 the tag is created by
297
+ # release-publish.yml from the merged main commit. Tagging by hand is
298
+ # how v0.55.0 was burned - the tag went on the dev tip, where every
299
+ # version site still read the previous release, and the gate refused to
300
+ # publish a tag that was already public.
301
+ print()
302
+ print(f"Do NOT tag by hand. Open a pull request into main; once it merges,")
303
+ print(f"release-publish.yml creates v{version} on the merge commit and publishes.")
297
304
  return 0
298
305
  except VersionSiteError as exc:
299
306
  print(f"bump-version: {exc}", file=sys.stderr)
@@ -0,0 +1,198 @@
1
+ #!/usr/bin/env python3
2
+ """Refuse a CHANGELOG entry appended to a section that has already shipped.
3
+
4
+ `release-publish.yml` publishes a `## [X.Y.Z]` section verbatim as the GitHub
5
+ Release body, `bump-version.py` inserts the next release heading directly under
6
+ the `## [Unreleased]` marker, and `release_phases.py` reads a section from its
7
+ heading to the next `^## [`. Section membership is therefore positional, and a
8
+ bullet written under a released heading is lost twice over: it never reaches the
9
+ next release's notes, and the release that already shipped claims work it does
10
+ not contain. That happened twice, through two separate pull requests, and no
11
+ gate saw it: both diffs carry `### Fixed` as unchanged context, so the fragment
12
+ reads exactly like a correct addition unless you map the line numbers back to
13
+ the nearest `## [` heading.
14
+
15
+ WHY THIS COUNTS BULLETS RATHER THAN COMPARING TEXT. Editing a released section
16
+ is legitimate and this project does it: measured over 59 comparable sections,
17
+ six differ from their tag, and every one is a correction rather than an
18
+ addition -- a wrong count fixed from "Nine" to "Ten", a superseded npm claim
19
+ rewritten, two whitespace reflows, two rewordings. A byte-identity rule would
20
+ fail all six. Comparing bullet text fails four of them too, because a reworded
21
+ first line reads as a new bullet. The count is what separates correcting a
22
+ released note from appending to it.
23
+
24
+ Sections whose tag carries no CHANGELOG.md, and early releases made before the
25
+ tagging convention, cannot be compared at all. They are skipped and counted in
26
+ the output rather than passed silently, because a gate that reports "checked"
27
+ while checking nothing is the failure this whole file exists to prevent.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import argparse
33
+ import re
34
+ import subprocess
35
+ import sys
36
+ from pathlib import Path
37
+ from typing import Callable, Dict, List, Optional, Tuple
38
+
39
+ ROOT = Path(__file__).resolve().parents[1]
40
+ CHANGELOG = ROOT / "CHANGELOG.md"
41
+
42
+ RELEASE_HEADING = re.compile(r"^## \[(\d+\.\d+\.\d+)\]", re.MULTILINE)
43
+ TOP_LEVEL_BULLET = re.compile(r"^- \S")
44
+
45
+
46
+ def section(text: str, version: str) -> Optional[str]:
47
+ """The body under `## [version]`, up to the next release heading.
48
+
49
+ Deliberately the same shape as `release_phases._changelog_section`, because
50
+ a gate that reads a section differently from the tool that publishes it
51
+ would pass exactly the documents that break at release time.
52
+ """
53
+ match = re.search(
54
+ rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)",
55
+ text,
56
+ re.MULTILINE | re.DOTALL,
57
+ )
58
+ return match.group(1) if match else None
59
+
60
+
61
+ def bullet_count(section_text: str) -> int:
62
+ """Top-level list items: the unit an author adds, unlike reflowed prose."""
63
+ return sum(1 for line in section_text.splitlines() if TOP_LEVEL_BULLET.match(line))
64
+
65
+
66
+ def appended_bullets(section_text: str, published_text: str) -> List[str]:
67
+ """The bullets present now that were not there at the tag.
68
+
69
+ Returned for the message only. The verdict is the count, so a reworded
70
+ bullet is not reported as an addition; this names the likely culprits by
71
+ taking the ones whose text is new, and falls back to the tail when every
72
+ bullet was reworded.
73
+ """
74
+ was = [line for line in published_text.splitlines() if TOP_LEVEL_BULLET.match(line)]
75
+ now = [line for line in section_text.splitlines() if TOP_LEVEL_BULLET.match(line)]
76
+ fresh = [line for line in now if line not in was]
77
+ gained = len(now) - len(was)
78
+ return fresh[:gained] if len(fresh) >= gained else now[-gained:]
79
+
80
+
81
+ def check(
82
+ current: str, published_for: Callable[[str], Optional[str]]
83
+ ) -> Tuple[List[Dict[str, object]], int, List[str]]:
84
+ """Compare every release section against the same section at its tag.
85
+
86
+ `published_for` returns the CHANGELOG.md at tag `vX.Y.Z`, or None when that
87
+ tag is unusable. Injected rather than called directly so the rule can be
88
+ tested without a git history, which the test matrix does not fetch.
89
+ """
90
+ findings: List[Dict[str, object]] = []
91
+ compared = 0
92
+ skipped: List[str] = []
93
+ for version in RELEASE_HEADING.findall(current):
94
+ published = published_for(version)
95
+ was = section(published, version) if published is not None else None
96
+ now = section(current, version)
97
+ if was is None or now is None:
98
+ skipped.append(version)
99
+ continue
100
+ compared += 1
101
+ if bullet_count(now) > bullet_count(was):
102
+ findings.append(
103
+ {
104
+ "version": version,
105
+ "was": bullet_count(was),
106
+ "now": bullet_count(now),
107
+ "bullets": appended_bullets(now, was),
108
+ }
109
+ )
110
+ return findings, compared, skipped
111
+
112
+
113
+ def _git(*args: str) -> Optional[str]:
114
+ result = subprocess.run(
115
+ ["git", *args], capture_output=True, text=True, encoding="utf-8", errors="replace"
116
+ )
117
+ return result.stdout if result.returncode == 0 else None
118
+
119
+
120
+ def _published_from_git(tags: set) -> Callable[[str], Optional[str]]:
121
+ # Two spellings ship in this repository: 65 tags read `v0.56.0` and 14
122
+ # older ones read `adr-kit--v0.1.0`. Resolving only the first silently
123
+ # skipped fourteen comparable sections, which is the same kind of
124
+ # overstated coverage this check exists to prevent.
125
+ def resolve(version: str) -> Optional[str]:
126
+ for tag in (f"v{version}", f"adr-kit--v{version}"):
127
+ if tag in tags:
128
+ published = _git("show", f"{tag}:CHANGELOG.md")
129
+ if published is not None:
130
+ return published
131
+ return None
132
+
133
+ return resolve
134
+
135
+
136
+ def report(findings, compared, skipped, stream=None) -> None:
137
+ # Resolved here rather than in the signature: a default bound at import
138
+ # time keeps writing to the stream that existed then, which silently
139
+ # bypasses any caller that replaced it.
140
+ stream = sys.stdout if stream is None else stream
141
+ print(
142
+ f"Compared {compared} released CHANGELOG section(s) against their tag; "
143
+ f"skipped {len(skipped)} with no usable tag.",
144
+ file=stream,
145
+ )
146
+ for finding in findings:
147
+ print(
148
+ f"\nFAIL ## [{finding['version']}] gained "
149
+ f"{finding['now'] - finding['was']} bullet(s) since its tag "
150
+ f"({finding['was']} -> {finding['now']}):",
151
+ file=stream,
152
+ )
153
+ for bullet in finding["bullets"]:
154
+ print(f" {bullet[:100]}", file=stream)
155
+ if findings:
156
+ print(
157
+ "\nThat section already shipped. release-publish.yml publishes it "
158
+ "verbatim as the GitHub Release body, so an entry added here is "
159
+ "absent from the next release's notes and falsely claimed by a "
160
+ "release that does not contain it.\nMove these bullets under "
161
+ "## [Unreleased], into the matching ### Added / ### Changed / "
162
+ "### Fixed heading.",
163
+ file=stream,
164
+ )
165
+
166
+
167
+ def main(argv: Optional[List[str]] = None) -> int:
168
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
169
+ parser.add_argument(
170
+ "--changelog", default=str(CHANGELOG), help="CHANGELOG.md to check"
171
+ )
172
+ args = parser.parse_args(argv)
173
+
174
+ listed = _git("tag")
175
+ if listed is None:
176
+ print(
177
+ "git tag failed: this check needs the tags, so the workflow step "
178
+ "running it must check out with fetch-depth: 0.",
179
+ file=sys.stderr,
180
+ )
181
+ return 2
182
+ tags = set(listed.split())
183
+ if not tags:
184
+ print(
185
+ "No tags in this checkout. The check cannot compare anything, and "
186
+ "reporting success would be a lie; check out with fetch-depth: 0.",
187
+ file=sys.stderr,
188
+ )
189
+ return 2
190
+
191
+ current = Path(args.changelog).read_text(encoding="utf-8")
192
+ findings, compared, skipped = check(current, _published_from_git(tags))
193
+ report(findings, compared, skipped)
194
+ return 1 if findings else 0
195
+
196
+
197
+ if __name__ == "__main__":
198
+ raise SystemExit(main())
@@ -14,6 +14,13 @@ once. Every mismatch is reported in one pass.
14
14
  Usage:
15
15
  python scripts/check-release-version.py --expect 0.39.0
16
16
  python scripts/check-release-version.py --expect v0.39.0 # leading v is stripped
17
+ python scripts/check-release-version.py --print-canonical # the CHANGELOG version, nothing else
18
+
19
+ `--print-canonical` exists so the release workflow can derive the tag from the
20
+ commit it is standing on (ADR-042) without a second implementation of "what
21
+ version is this". It reads the same registry entry the gate above compares
22
+ against, so the tag and the gate can never disagree about where the version
23
+ lives.
17
24
  """
18
25
  from __future__ import annotations
19
26
 
@@ -40,13 +47,16 @@ def main(argv: list[str] | None = None) -> int:
40
47
  parser = argparse.ArgumentParser(description=__doc__)
41
48
  parser.add_argument(
42
49
  "--expect",
43
- required=True,
44
50
  help="Expected release version (git tag). A leading 'v' is stripped.",
45
51
  )
52
+ parser.add_argument(
53
+ "--print-canonical",
54
+ action="store_true",
55
+ help="Print the canonical CHANGELOG version and exit, comparing nothing.",
56
+ )
46
57
  args = parser.parse_args(argv)
47
- expected = args.expect.lstrip("vV").strip()
48
- if not SEMVER.match(expected):
49
- parser.error(f"not a MAJOR.MINOR.PATCH version: {args.expect!r}")
58
+ if not args.print_canonical and not args.expect:
59
+ parser.error("one of --expect or --print-canonical is required")
50
60
 
51
61
  try:
52
62
  registry = load_registry(ROOT)
@@ -54,6 +64,21 @@ def main(argv: list[str] | None = None) -> int:
54
64
  print(f"check-release-version: {exc}", file=sys.stderr)
55
65
  return 1
56
66
 
67
+ if args.print_canonical:
68
+ canonical = read_canonical(ROOT, registry)
69
+ if not canonical:
70
+ print(
71
+ "check-release-version: the CHANGELOG names no release version",
72
+ file=sys.stderr,
73
+ )
74
+ return 1
75
+ print(canonical)
76
+ return 0
77
+
78
+ expected = args.expect.lstrip("vV").strip()
79
+ if not SEMVER.match(expected):
80
+ parser.error(f"not a MAJOR.MINOR.PATCH version: {args.expect!r}")
81
+
57
82
  print(f"Expected release version: {expected}")
58
83
  canonical = read_canonical(ROOT, registry)
59
84
  mark = "ok" if canonical == expected else "MISMATCH"
@@ -0,0 +1,171 @@
1
+ #!/usr/bin/env python3
2
+ """Drive a release end to end, leaving only what a person must do.
3
+
4
+ ADR-042: the release runs from the maintainer's machine, with the maintainer's
5
+ own credentials, because GitHub does not start workflow runs for events caused
6
+ by GITHUB_TOKEN - a pull request a workflow opens never receives the checks
7
+ `main` requires, so it can never merge. The tag is not typed here either:
8
+ `release-publish.yml` creates it from the merged commit and publishes in the
9
+ same run, and this driver only verifies that it landed where it belongs.
10
+
11
+ What stays human: deciding to release and choosing the version, writing the
12
+ release notes, approving the merge, and npm's 2FA. Everything between those is
13
+ mechanical, and mechanical steps performed by hand are what cost v0.55.0 and
14
+ left three npm versions unapproved for a week.
15
+
16
+ Safe to re-run. Each phase asks the repository whether its work is already
17
+ done, so an interrupted release is resumed rather than restarted:
18
+
19
+ python scripts/release.py 0.57.0
20
+ python scripts/release.py 0.57.0 --skip-tests # CI still runs them
21
+ python scripts/release.py 0.57.0 --status # what is left, changing nothing
22
+ python scripts/release.py 0.57.0 --only prepare # one phase
23
+
24
+ docs/RELEASING.md is the specification; the phases mirror its steps in order.
25
+ """
26
+ from __future__ import annotations
27
+
28
+ import argparse
29
+ import re
30
+ import sys
31
+ from pathlib import Path
32
+
33
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
34
+
35
+ from release_npm import ( # noqa: E402
36
+ DONE,
37
+ STAGED,
38
+ UNREACHABLE,
39
+ WRONG_LATEST,
40
+ npm_instructions,
41
+ npm_state,
42
+ npm_wrong_latest,
43
+ )
44
+ from release_phases import PHASES, Context, ReleaseError # noqa: E402
45
+
46
+ NPM_LABEL = {
47
+ DONE: "done",
48
+ WRONG_LATEST: "PUBLISHED, but `latest` names another version",
49
+ STAGED: "awaiting your 2FA",
50
+ UNREACHABLE: "npm did not answer; run this again",
51
+ }
52
+
53
+ SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
54
+
55
+
56
+ def _say(text: str = "") -> None:
57
+ print(text, flush=True)
58
+
59
+
60
+ def _status(ctx: Context) -> int:
61
+ _say(f"Release {ctx.tag}: what each phase reports about the repository now.")
62
+ _say()
63
+ for phase in PHASES:
64
+ try:
65
+ state = "done" if phase.done(ctx) else "to do"
66
+ except ReleaseError as exc: # a phase that cannot even answer
67
+ state = f"unknown ({exc})"
68
+ _say(f" step {phase.step} {phase.name:<10} {state}")
69
+ _say(f" step 3a npm {NPM_LABEL[npm_state(ctx)]}")
70
+ _say()
71
+ _say("Nothing was changed.")
72
+ return 0
73
+
74
+
75
+ def main(argv: list[str] | None = None) -> int:
76
+ parser = argparse.ArgumentParser(description=__doc__)
77
+ parser.add_argument("version", help="release version, for example 0.57.0")
78
+ parser.add_argument(
79
+ "--only",
80
+ choices=[phase.name for phase in PHASES],
81
+ help="run a single phase, skipping the done-check for it",
82
+ )
83
+ parser.add_argument(
84
+ "--status",
85
+ action="store_true",
86
+ help="report what each phase would do and change nothing",
87
+ )
88
+ parser.add_argument(
89
+ "--skip-tests",
90
+ action="store_true",
91
+ help="skip the local pytest run; the pull request still runs it in CI",
92
+ )
93
+ parser.add_argument(
94
+ "--timeout-min",
95
+ type=int,
96
+ default=45,
97
+ help="how long to wait for a merge or for the publish workflow (default 45)",
98
+ )
99
+ args = parser.parse_args(argv)
100
+
101
+ version = args.version.lstrip("vV").strip()
102
+ if not SEMVER.match(version):
103
+ parser.error(f"not a MAJOR.MINOR.PATCH version: {args.version!r}")
104
+
105
+ ctx = Context(
106
+ version=version,
107
+ skip_tests=args.skip_tests,
108
+ timeout_min=args.timeout_min,
109
+ )
110
+
111
+ if args.status:
112
+ return _status(ctx)
113
+
114
+ phases = [p for p in PHASES if p.name == args.only] if args.only else list(PHASES)
115
+ _say(f"Releasing {ctx.tag}. Re-running this command is safe; finished phases are skipped.")
116
+ _say()
117
+
118
+ for phase in phases:
119
+ label = f"step {phase.step} {phase.name}"
120
+ if not args.only and phase.done(ctx):
121
+ _say(f" {label:<22} already done")
122
+ continue
123
+ _say(f" {label:<22} running")
124
+ try:
125
+ for note in phase.run(ctx):
126
+ _say(f" {note}")
127
+ except ReleaseError as exc:
128
+ _say()
129
+ _say(f"Stopped in {phase.name}:")
130
+ _say()
131
+ _say(str(exc))
132
+ _say()
133
+ _say("Nothing after this phase ran. Fix the above and run the same "
134
+ "command again; the phases that finished will be skipped.")
135
+ return 1
136
+
137
+ _say()
138
+ state = npm_state(ctx)
139
+
140
+ if state == DONE:
141
+ _say(f"npm already serves {ctx.version} as latest.")
142
+ _say()
143
+ _say(f"{ctx.tag} is released and every surface agrees.")
144
+ return 0
145
+
146
+ if state == WRONG_LATEST:
147
+ _say("=" * 72)
148
+ _say("RELEASED, BUT npm SERVES A DIFFERENT VERSION")
149
+ _say("=" * 72)
150
+ _say()
151
+ _say(npm_wrong_latest(ctx))
152
+ return 1
153
+
154
+ if state == UNREACHABLE:
155
+ _say(f"Everything up to npm is done, but npm did not answer, so this "
156
+ f"cannot say whether {ctx.version} is published or still staged. "
157
+ f"Run the same command again once you have a connection.")
158
+ return 1
159
+
160
+ _say("=" * 72)
161
+ _say("ONE THING LEFT, AND ONLY YOU CAN DO IT")
162
+ _say("=" * 72)
163
+ _say()
164
+ _say(npm_instructions(ctx))
165
+ _say()
166
+ _say("Then re-run this command: it will verify the dist-tag and finish.")
167
+ return 0
168
+
169
+
170
+ if __name__ == "__main__":
171
+ raise SystemExit(main())