Coverage for src/keel/intake.py: 100%

208 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""Pure issue intake and readiness classification for work-owning commands.""" 

2 

3from __future__ import annotations 

4 

5import re 

6from dataclasses import dataclass 

7from typing import Any 

8 

9READY = "ready" 

10NEEDS_INPUT = "needs-input" 

11BLOCKED = "blocked" 

12OUT_OF_SCOPE = "out-of-scope" 

13READINESS_STATUSES = (READY, NEEDS_INPUT, BLOCKED, OUT_OF_SCOPE) 

14 

15_SECTION_RE = re.compile(r"^(?P<hashes>#{1,6})\s+(?P<title>.+?)\s*$", re.MULTILINE) 

16_BULLET_RE = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+(?P<text>.+?)\s*$") 

17_BLOCKED_RE = re.compile( 

18 r"\b(blocked by|depends on|dependency|waiting on|needs dependency|blocked until)\b", 

19 re.IGNORECASE, 

20) 

21#: The public name for the blocked-by phrase set, so other readers of "this is waiting on 

22#: something" (``keel stale-blockers``, #1512) extend one definition instead of copying it. 

23BLOCKED_PHRASE_RE = _BLOCKED_RE 

24_NON_BLOCKING_DEPENDENCY_RE = re.compile( 

25 r"\b(no dependenc(?:y|ies)|dependenc(?:y|ies):\s*(?:none|no|n/a)|" 

26 r"depends on:\s*(?:none|no|n/a)|blocked by:\s*(?:none|no|n/a)|" 

27 r"waiting on\s+(?:none|no one|nobody|no-one))\b", 

28 re.IGNORECASE, 

29) 

30#: Public name for the "no blocker, despite the phrase" set (``Depends on: none``), shared 

31#: with ``keel stale-blockers`` (#1512) for the same reason as ``BLOCKED_PHRASE_RE``. 

32NON_BLOCKING_DEPENDENCY_RE = _NON_BLOCKING_DEPENDENCY_RE 

33_AMBIGUOUS_RE = re.compile( 

34 r"\b(tbd|todo|unclear|ambiguous|maybe|not sure|needs clarification|decide later)\b", 

35 re.IGNORECASE, 

36) 

37_OUT_OF_SCOPE_LABELS = frozenset({"out-of-scope", "wontfix", "not-planned"}) 

38#: Headings whose whole section is a boundary statement **about the change** (#1168). 

39#: Normalised by :func:`_normalize_heading`, so ``## Non-goals`` and ``## non goals`` 

40#: are the same heading; ``not in this change`` is this repository's own spelling, 

41#: used by every issue written since #1182. 

42#: 

43#: Deliberately **not** here: ``Not planned``, ``Will not do``, ``Decision``, 

44#: ``Status``, ``Resolution``. Those are close-reason headings — a section saying the 

45#: issue will not be done — and dropping them would silence the very statement intake 

46#: exists to read. The round-1 gate seats caught exactly that: with them in the set, 

47#: `## Not planned` / `This issue is out of scope; closing.` came back `ready` with 

48#: `can_mutate_code: true`. The test is what the section says about, not how 

49#: negative it sounds. 

50_SCOPE_EXCLUSION_HEADINGS = frozenset( 

51 { 

52 "out of scope", 

53 "non goals", 

54 "non goal", 

55 "not in scope", 

56 "not in this change", 

57 } 

58) 

59#: The short form, anchored at the start, for the **title** and nowhere else. 

60#: 

61#: A title is one line, with nothing in front of it and nothing after it to qualify — it 

62#: names the issue's whole subject. A body sentence is not: `Out of scope for v1: the 

63#: Android client.` opening an issue is a boundary, `Not in scope for Windows.` is a 

64#: carve-out, and neither closes anything. Fifteen review rounds went into trying to tell 

65#: those from a closure by position, and each rule inverted on some real sentence. The 

66#: body asks the one question that has an answer: is the issue the subject. 

67_OUT_OF_SCOPE_OPENER_RE = re.compile( 

68 r"^(?:out[- ]of[- ]scope|not planned|wontfix|won't fix|not in scope)\b", 

69 re.IGNORECASE, 

70) 

71#: A declaration **in the body**: a sentence whose subject is the issue. 

72#: 

73#: Anchored at the start of the *sentence* — which is not the same as the start of a 

74#: line, and that distinction is the whole lesson of this change. Eight rounds tried to 

75#: anchor a short `Out of scope: …` form at a line start and it broke on every piece of 

76#: markdown that can precede one. A sentence start is stable, and requiring the issue to 

77#: be the **subject** is what separates a closure from a mention: "This issue is out of 

78#: scope" closes it, "A backport of this issue is out of scope" carves out a backport. 

79#: An unanchored match refused the second, which is #1168 inverted. 

80_OUT_OF_SCOPE_DECLARATION_RE = re.compile( 

81 r"^(?:this|the)\s+issue\s+(?:is|was|remains)\s+" 

82 r"(?:out[- ]of[- ]scope|not planned|wontfix|won't fix|not in scope)" 

83 r"(?![A-Za-z0-9])", 

84 re.IGNORECASE, 

85) 

86#: Markdown that can sit in front of a sentence without being part of it. Stripped before 

87#: the anchor is applied, so a bullet or a quote marker does not hide the subject. 

88_LEADING_MARKUP_RE = re.compile( 

89 r"^(?:" 

90 r"\s*(?:[-*+]|\d+[.)])\s+" # list marker 

91 r"|\s*>\s*" # block quote 

92 r"|\s*\[[ xX]?\]\s*" # task box 

93 r"|\s*(?:-{3,}|\*{3,}|_{3,})\s*" # thematic break 

94 # `[\s\S]` rather than `.`: an HTML comment may span lines, and `.` does not cross 

95 # one, so a multi-line comment in front of a sentence was left where it stood. 

96 r"|\s*<!--[\s\S]*?-->\s*" # html comment 

97 r"|\s*!\[[^\]]*\]\([^)]*\)\s*" # image 

98 r"|[*_]{1,3}" # emphasis run 

99 r"|\s+" 

100 r")+" 

101) 

102#: A short label opening a heading or a line — ``Decision — …``, ``Status: …``. Removed 

103#: before the anchor so the subject that follows is seen, while a sentence that merely 

104#: *mentions* the issue further in ("A backport of this issue is out of scope") is not, 

105#: because it carries no such separator before the subject. Bounded in length and 

106#: forbidden sentence-ending punctuation, so it cannot eat a real clause. 

107_LEADING_LABEL_RE = re.compile( 

108 # A label is a **short name**, not a clause: at most three words, each a word with 

109 # optional internal punctuation, then an explicit terminator. `Decision:`, 

110 # `Follow-up:`, `Update 2026-09-14:`, `Decision (2026-09-14) —` all qualify. 

111 # 

112 # The length-capped "anything up to a terminator" form this replaces let the label 

113 # strip re-anchor the pattern in the middle of a compound sentence: `Users need safer 

114 # sync — this issue is not in scope for Windows.` became `this issue is not in scope 

115 # for Windows.` and read as a closure, when it carves out Windows. That is #1168 

116 # inverted, and the subject test cannot see it because the subject really is there — 

117 # just not at the start of the sentence, which is the whole point of the anchor. 

118 r"^\w[\w.()/'’-]*(?:\s+[\w.()/'’-]+){0,2}\s*[:\u2014\u2013]\s*" 

119 # A spaced hyphen separates the same way; `-` inside a word does not. 

120 r"|^\w[\w.()/'’]*(?:\s+[\w.()/'’]+){0,2}\s+-\s+" 

121) 

122 

123 

124def _declaration_candidates(text: str, *, allow_label: bool = False) -> tuple[str, ...]: 

125 """Every prefix-stripped form of one sentence the declaration may be anchored in. 

126 

127 The sentence **as written** comes first, because the label pattern cannot tell a 

128 `Decision:` prefix from the declaration's own `out of scope: closing.` — stripping 

129 unconditionally ate the closure down to `closing.`. Then markdown removed; then a 

130 label removed and markdown removed *again*, because `**Decision:** This issue is…` 

131 leaves a closing `**` between the label and the subject that the first pass cannot 

132 see. Each round of this review found one of these. 

133 """ 

134 forms = [text.strip()] 

135 stripped = _LEADING_MARKUP_RE.sub("", forms[0]) 

136 if stripped != forms[0]: 

137 forms.append(stripped) 

138 if not allow_label: 

139 return tuple(forms) 

140 delabelled = _LEADING_LABEL_RE.sub("", stripped, count=1).strip() 

141 if delabelled != stripped: 

142 forms.append(_LEADING_MARKUP_RE.sub("", delabelled).strip()) 

143 return tuple(forms) 

144 

145 

146_DOCS_RE = re.compile(r"\b(doc|docs|documentation|readme|changelog)\b", re.IGNORECASE) 

147_TESTS_RE = re.compile(r"\b(test|tests|coverage|ci|lint)\b", re.IGNORECASE) 

148_BLOCKED_LABELS = frozenset({"blocked", "status:blocked", "needs-dependency"}) 

149_RISK_RE = re.compile( 

150 r"\b(security|release|migration|schema|api|breaking|billing|secret|credential|ci|" 

151 r"production|compatibility)\b", 

152 re.IGNORECASE, 

153) 

154 

155 

156@dataclass(frozen=True) 

157class IssueContext: 

158 """Issue text supplied by an adapter before code mutation starts.""" 

159 

160 title: str | None = None 

161 body: str | None = None 

162 labels: tuple[str, ...] = () 

163 

164 @property 

165 def provided(self) -> bool: 

166 return bool((self.title or "").strip() or (self.body or "").strip() or self.labels) 

167 

168 

169def assess_issue( 

170 *, 

171 title: str | None = None, 

172 body: str | None = None, 

173 labels: tuple[str, ...] = (), 

174) -> dict[str, Any]: 

175 """Return a deterministic readiness record for an issue-like work item.""" 

176 context = IssueContext(title=title, body=body, labels=tuple(labels)) 

177 sections = _sections(context.body or "") 

178 acceptance = _acceptance_criteria(sections) 

179 objective = _objective(context.title, context.body, sections) 

180 deliverable = _deliverable(sections, acceptance) 

181 combined = " ".join(filter(None, (context.title, context.body, " ".join(context.labels)))) 

182 normalized_labels = tuple(label.strip().lower() for label in context.labels) 

183 

184 missing: list[str] = [] 

185 blockers: list[str] = [] 

186 questions: list[str] = [] 

187 

188 if not objective: 

189 missing.append("objective") 

190 questions.append("What objective should this issue accomplish?") 

191 if not deliverable: 

192 missing.append("deliverable") 

193 questions.append("What concrete deliverable should be produced?") 

194 if not acceptance: 

195 missing.append("acceptance_criteria") 

196 questions.append("What acceptance criteria define done for this issue?") 

197 

198 status = READY 

199 reason = "Issue has an objective, deliverable, and acceptance criteria." 

200 out_of_scope_reason = _out_of_scope_reason( 

201 title=context.title, 

202 body=context.body, 

203 labels=normalized_labels, 

204 ) 

205 if out_of_scope_reason: 

206 status = OUT_OF_SCOPE 

207 reason = out_of_scope_reason 

208 questions = [] 

209 elif _is_blocked(combined, normalized_labels): 

210 status = BLOCKED 

211 reason = "Issue declares a dependency or waiting condition." 

212 blockers.append(_blocked_summary(combined)) 

213 questions.append("What dependency must clear before this issue can start?") 

214 elif missing: 

215 status = NEEDS_INPUT 

216 reason = f"Missing required intake field(s): {', '.join(missing)}." 

217 elif _AMBIGUOUS_RE.search(combined): 

218 status = NEEDS_INPUT 

219 reason = "Issue scope contains ambiguous or deferred wording." 

220 missing.append("scope_clarity") 

221 questions.append("Which exact scope should be implemented now?") 

222 

223 return { 

224 "schema_version": "keel.issue-intake.v1", 

225 "provided": context.provided, 

226 "status": status, 

227 "can_mutate_code": status == READY, 

228 "work_block_policy": { 

229 "skip_when_not_ready": status != READY, 

230 "continue_with_next_ready_issue": status != READY, 

231 "non_ready_statuses": [NEEDS_INPUT, BLOCKED, OUT_OF_SCOPE], 

232 }, 

233 "reason": reason, 

234 "objective": objective, 

235 "deliverable": deliverable, 

236 "acceptance_criteria": acceptance, 

237 "risk_tier_inputs": _risk_inputs(combined, normalized_labels), 

238 "required_docs_tests": _required_docs_tests(combined, acceptance), 

239 "missing_info": missing, 

240 "blockers": blockers, 

241 "questions": _unique(questions)[:3], 

242 "ledger_record": { 

243 "readiness": status, 

244 "mutation_allowed": status == READY, 

245 "skip_reason": None if status == READY else reason, 

246 "question_count": len(_unique(questions)[:3]), 

247 }, 

248 } 

249 

250 

251def _sections(body: str) -> dict[str, str]: 

252 matches = list(_SECTION_RE.finditer(body)) 

253 if not matches: 

254 return {} 

255 sections: dict[str, str] = {} 

256 for index, match in enumerate(matches): 

257 title = _normalize_heading(match.group("title")) 

258 start = match.end() 

259 end = matches[index + 1].start() if index + 1 < len(matches) else len(body) 

260 sections[title] = body[start:end].strip() 

261 return sections 

262 

263 

264def _normalize_heading(value: str) -> str: 

265 return re.sub(r"[^a-z0-9]+", " ", value.lower()).strip() 

266 

267 

268def _objective(title: str | None, body: str | None, sections: dict[str, str]) -> str | None: 

269 for key in ("objective", "problem", "summary", "context"): 

270 if value := _first_sentence_or_bullet(sections.get(key, "")): 

271 return value 

272 if body and not sections: 

273 return _first_sentence_or_bullet(body) 

274 return title.strip() if title and title.strip() else None 

275 

276 

277def _deliverable(sections: dict[str, str], acceptance: list[str]) -> str | None: 

278 del acceptance 

279 for key in ("deliverable", "proposed direction", "proposal", "scope", "implementation"): 

280 if value := _first_sentence_or_bullet(sections.get(key, "")): 

281 return value 

282 return None 

283 

284 

285def _acceptance_criteria(sections: dict[str, str]) -> list[str]: 

286 for key in ( 

287 "acceptance criteria", 

288 "acceptance", 

289 "definition of done", 

290 "done when", 

291 "dod", 

292 ): 

293 if key in sections: 

294 bullets = _bullets(sections[key]) 

295 return bullets if bullets else _sentences(sections[key]) 

296 return [] 

297 

298 

299def _first_sentence_or_bullet(text: str) -> str | None: 

300 bullets = _bullets(text) 

301 if bullets: 

302 return bullets[0] 

303 sentences = _sentences(text) 

304 return sentences[0] if sentences else None 

305 

306 

307def _bullets(text: str) -> list[str]: 

308 items: list[str] = [] 

309 for line in text.splitlines(): 

310 if match := _BULLET_RE.match(line): 

311 item = match.group("text").strip() 

312 if item: 

313 items.append(item) 

314 return items 

315 

316 

317def _bullet_lines(text: str) -> list[str]: 

318 """List items, markers removed — each a statement in its own right. 

319 

320 `_sentences` joins lines carrying no terminator, so a plain bullet above a 

321 declaration (`- Discussed with the team` then `- This issue is out of scope.`) puts 

322 the declaration mid-sentence, past the anchor. A list item is a statement whether or 

323 not it ends in a full stop. 

324 

325 List items **only**. Every line was tried and refused prose the moment a wrap put the 

326 phrase at a line start; block quotes were tried and refused it too, because Markdown 

327 prefixes each continuation line of a quote with `>`. Neither shape carries a list 

328 marker. The subject test is what makes this safe now — a bullet has to name the issue 

329 to match anything at all. 

330 """ 

331 return [item for line in text.splitlines() if (item := _bullet_text(line))] 

332 

333 

334def _bullet_text(line: str) -> str: 

335 match = _BULLET_RE.match(line) 

336 return match.group("text").strip() if match else "" 

337 

338 

339def _sentences(text: str) -> list[str]: 

340 compact = " ".join(line.strip() for line in text.splitlines() if line.strip()) 

341 if not compact: 

342 return [] 

343 parts = [part.strip() for part in re.split(r"(?<=[.!?])\s+", compact) if part.strip()] 

344 return parts or [compact] 

345 

346 

347def _is_scope_exclusion_heading(title: str) -> bool: 

348 """Does this heading open a section that bounds the **change**? 

349 

350 The test is *starts with*, not equals. ``## Out of scope for v1``, 

351 ``## Out of scope: mobile UI`` and ``## Non-goals for now`` are the same kind of 

352 section as ``## Out of scope``, and an equality test refused the issues that wrote 

353 them — #1168 coming back through the heading, which is now read as prose. A section 

354 titled "Out of scope…" is a boundary whatever qualifies it. 

355 

356 A close-reason heading (``Not planned``, ``Decision``, ``Status``) is deliberately 

357 not in the set: it names a status for the issue, and dropping it would silence the 

358 statement intake exists to read. 

359 """ 

360 normalised = _normalize_heading(title) 

361 return any( 

362 normalised == heading or normalised.startswith(heading + " ") 

363 for heading in _SCOPE_EXCLUSION_HEADINGS 

364 ) 

365 

366 

367def _scannable_chunks(body: str) -> list[tuple[bool, str]]: 

368 """``body`` split into the pieces a declaration may hide in, boundaries removed. 

369 

370 A scope-exclusion section goes whole — heading and content. What remains comes back 

371 per section, with the heading's own text as a chunk **separate from** its body: 

372 inline, it glues onto the sentence below (`- works ## Decision Out of scope: 

373 closing.`) and the declaration pattern is anchored at a sentence start; dropped, a 

374 declaration written *in* a heading becomes invisible. Each gate round found one of 

375 those halves. 

376 """ 

377 matches = list(_SECTION_RE.finditer(body)) 

378 if not matches: 

379 return [(False, body)] 

380 chunks: list[tuple[bool, str]] = [(False, body[: matches[0].start()])] 

381 for index, match in enumerate(matches): 

382 # An exclusion section owns its own body and nothing else. Owning nested headings 

383 # was tried and failed in both directions: `# Out of scope` over a run of `##` 

384 # sections swallowed the `## Decision` that closed the issue, and every heuristic 

385 # for telling a title level from a section level inverted on some real body. What 

386 # makes the simple rule safe is the subject test above — a bullet under a boundary 

387 # section saying `Out of scope: the mobile client` names no issue and matches 

388 # nothing, so the section's *contents* no longer need hiding, only its own prose. 

389 if _is_scope_exclusion_heading(match.group("title")): 

390 continue 

391 end = matches[index + 1].start() if index + 1 < len(matches) else len(body) 

392 # Flagged as a heading: its text may carry a record label (`Decision —`) in front 

393 # of the declaration. It does **not** get the short form — `## Not planned` over a 

394 # list of features is a boundary section, and reading its title as a closure 

395 # refused the issue while the identical bullets under `## Non-goals` passed. 

396 chunks.append((True, match.group("title"))) 

397 chunks.append((False, body[match.end() : end])) 

398 return [(is_heading, chunk) for is_heading, chunk in chunks if chunk.strip()] 

399 

400 

401def _out_of_scope_reason( 

402 *, 

403 title: str | None, 

404 body: str | None, 

405 labels: tuple[str, ...], 

406) -> str | None: 

407 """Return the concrete scope declaration, ignoring structural exclusions. 

408 

409 Two independent filters, and each does one job: 

410 

411 * **Structurally**, a scope-exclusion section is removed whole. Its heading and its 

412 bullets describe what the change leaves out; none of it says the issue is closed. 

413 * **In what remains**, a declaration is a sentence whose *subject is the issue* — 

414 ``this issue is out of scope``, opening the sentence. Not ``Out of scope: …``, 

415 which is the same string as a boundary bullet; not a mention in the middle of a 

416 sentence, which carves out a part rather than closing the whole. The short form 

417 is the title's, where one line and no markdown make an anchor safe. 

418 

419 Everything left is searched, title and body alike. A maintainer writing 

420 ``## Decision — this issue is out of scope; closing`` is declaring it closed, and 

421 intake must not hand that to s2. 

422 

423 ``non-goal`` is deliberately **not** a declaration marker. It names a non-goal of 

424 the change ("Non-goal: rewrite the parser"), which is a boundary like the section 

425 it usually appears under, not a statement that the issue will not be done. The 

426 ``## Non-goals`` heading is handled structurally above. 

427 """ 

428 for label in labels: 

429 if label in _OUT_OF_SCOPE_LABELS: 

430 return f"Issue carries out-of-scope label: {label}." 

431 

432 # The title takes the short form: it names the issue's whole subject, with nothing 

433 # before it and nothing after it to qualify. 

434 if title and (heading := title.strip()): 

435 if _OUT_OF_SCOPE_OPENER_RE.search(heading) or _OUT_OF_SCOPE_DECLARATION_RE.search(heading): 

436 return f"Issue declares itself out of scope: {heading}" 

437 

438 #: `(text, may a leading label be stripped)`. A heading's `Decision —` prefix is a 

439 #: record label; the same shape inside prose is a prepositional phrase (`For Windows: 

440 #: this issue is not in scope.`), and stripping it turned a carve-out into a closure. 

441 candidates: list[tuple[str, bool]] = [] 

442 if body: 

443 for is_heading, chunk in _scannable_chunks(body): 

444 candidates.extend((sentence, is_heading) for sentence in _sentences(chunk)) 

445 candidates.extend((line, False) for line in _bullet_lines(chunk)) 

446 

447 for candidate, allow_label in candidates: 

448 # Leading markdown removed first, so the anchor sees the sentence rather than the 

449 # bullet in front of it. 

450 if any( 

451 _OUT_OF_SCOPE_DECLARATION_RE.search(form) 

452 for form in _declaration_candidates(candidate, allow_label=allow_label) 

453 ): 

454 return f"Issue declares itself out of scope: {candidate.strip()}" 

455 return None 

456 

457 

458def _is_blocked(combined: str, labels: tuple[str, ...]) -> bool: 

459 if not _BLOCKED_LABELS.isdisjoint(labels): 

460 return True 

461 

462 compact = " ".join(line.strip() for line in combined.splitlines() if line.strip()) 

463 # Fast path: bypass expensive sentence iteration if no 

464 # blocked regex match exists globally in normalized text 

465 if not _BLOCKED_RE.search(compact): 

466 return False 

467 

468 # ⚡ Bolt Optimization: Unroll any() generator to avoid generator overhead 

469 for sentence in _sentences(compact): 

470 if _is_actionable_blocker(sentence): 

471 return True 

472 return False 

473 

474 

475def _blocked_summary(combined: str) -> str: 

476 sentences = _sentences(combined) 

477 for sentence in sentences: 

478 if _is_actionable_blocker(sentence): 

479 return sentence 

480 return "Declared blocked dependency." 

481 

482 

483def _is_actionable_blocker(text: str) -> bool: 

484 return bool(_BLOCKED_RE.search(text)) and not bool(_NON_BLOCKING_DEPENDENCY_RE.search(text)) 

485 

486 

487def _risk_inputs(combined: str, labels: tuple[str, ...]) -> dict[str, Any]: 

488 keywords = _unique(match.group(0).lower() for match in _RISK_RE.finditer(combined)) 

489 risk_labels = [label for label in labels if "risk" in label or label.startswith("tier")] 

490 return { 

491 "keywords": keywords, 

492 "labels": risk_labels, 

493 "has_high_risk_signal": bool(keywords or risk_labels), 

494 } 

495 

496 

497def _required_docs_tests(combined: str, acceptance: list[str]) -> dict[str, Any]: 

498 text = " ".join([combined, *acceptance]) 

499 return { 

500 "docs": "required" if _DOCS_RE.search(text) else "unspecified", 

501 "tests": "required" if _TESTS_RE.search(text) else "unspecified", 

502 } 

503 

504 

505def _unique(items) -> list[str]: 

506 seen = set() 

507 result = [] 

508 for item in items: 

509 v = str(item).strip() 

510 if v and v not in seen: 

511 seen.add(v) 

512 result.append(v) 

513 return result