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
« 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."""
3from __future__ import annotations
5import re
6from dataclasses import dataclass
7from typing import Any
9READY = "ready"
10NEEDS_INPUT = "needs-input"
11BLOCKED = "blocked"
12OUT_OF_SCOPE = "out-of-scope"
13READINESS_STATUSES = (READY, NEEDS_INPUT, BLOCKED, OUT_OF_SCOPE)
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)
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.
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)
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)
156@dataclass(frozen=True)
157class IssueContext:
158 """Issue text supplied by an adapter before code mutation starts."""
160 title: str | None = None
161 body: str | None = None
162 labels: tuple[str, ...] = ()
164 @property
165 def provided(self) -> bool:
166 return bool((self.title or "").strip() or (self.body or "").strip() or self.labels)
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)
184 missing: list[str] = []
185 blockers: list[str] = []
186 questions: list[str] = []
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?")
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?")
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 }
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
264def _normalize_heading(value: str) -> str:
265 return re.sub(r"[^a-z0-9]+", " ", value.lower()).strip()
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
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
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 []
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
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
317def _bullet_lines(text: str) -> list[str]:
318 """List items, markers removed — each a statement in its own right.
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.
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))]
334def _bullet_text(line: str) -> str:
335 match = _BULLET_RE.match(line)
336 return match.group("text").strip() if match else ""
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]
347def _is_scope_exclusion_heading(title: str) -> bool:
348 """Does this heading open a section that bounds the **change**?
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.
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 )
367def _scannable_chunks(body: str) -> list[tuple[bool, str]]:
368 """``body`` split into the pieces a declaration may hide in, boundaries removed.
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()]
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.
409 Two independent filters, and each does one job:
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.
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.
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}."
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}"
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))
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
458def _is_blocked(combined: str, labels: tuple[str, ...]) -> bool:
459 if not _BLOCKED_LABELS.isdisjoint(labels):
460 return True
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
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
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."
483def _is_actionable_blocker(text: str) -> bool:
484 return bool(_BLOCKED_RE.search(text)) and not bool(_NON_BLOCKING_DEPENDENCY_RE.search(text))
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 }
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 }
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