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

358 statements  

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

1"""Canonical Markdown renderers for ship artifacts. 

2 

3These helpers keep public GitHub artifacts deterministic and consumer-neutral. 

4Adapters should post the rendered bodies verbatim instead of hand-writing PR 

5descriptions, review verdicts, jury verdicts, or extension result summaries. 

6""" 

7 

8from __future__ import annotations 

9 

10import re 

11from typing import Any 

12 

13from . import evidence 

14 

15SCHEMA_VERSION = "keel.artifacts.v1" 

16EXTENSION_RESULT_MARKER = "<!-- keel.extension-result.v1 -->" 

17ISSUE_UPDATE_MARKER = "<!-- keel.issue-update.v1 -->" 

18STEP_HANDOFF_MARKER = "<!-- keel.step-handoff.v1 -->" 

19RUN_CONTROL_HALT_MARKER = "<!-- keel.run-control-halt.v1 -->" 

20REVIEW_CYCLE_SUMMARY_MARKER = "keel.review-cycle-summary.v1" 

21#: The verdict a jury verdict renders with when nobody supplied the panel's consensus 

22#: (#1429). It reads as **not** an approval — :func:`keel.evidence.jury_verdict_token` 

23#: takes its first word, ``PANEL_CONSENSUS`` — so a template posted unfilled holds the 

24#: merge with ``jury-verdict-not-approved`` instead of approving for a panel that may 

25#: have rejected the change. 

26JURY_CONSENSUS_PLACEHOLDER = ( 

27 "<PANEL_CONSENSUS \u2014 replace with the panel's APPROVE / REQUEST_CHANGES>" 

28) 

29COVERAGE_DELTA_MARKER = "keel.coverage-delta.v1" 

30DEPS_AUDIT_MARKER = "keel.deps-audit.v1" 

31FLAKE_AUDIT_MARKER = "keel.flake-audit.v1" 

32SCAN_FINDING_MARKER = "keel.scan-finding.v1" 

33TRIAGE_AUDIT_MARKER = "keel.triage-audit.v1" 

34 

35#: Severity buckets that drive the consolidated histogram + merge recommendation, 

36#: in must-fix → advisory order. ``critical`` folds into ``blocker`` (must-fix). 

37SEVERITY_ORDER = ("blocker", "major", "minor", "nit") 

38_SEVERITY_ALIASES = {"critical": "blocker"} 

39 

40#: Dependency-advisory severity buckets, most → least severe. 

41DEPS_SEVERITY_ORDER = ("critical", "high", "moderate", "low") 

42 

43 

44def contract_as_dict() -> dict[str, Any]: 

45 """Return the canonical artifact renderer contract for ship-like flows.""" 

46 return { 

47 "schema_version": SCHEMA_VERSION, 

48 "consumer_neutral": True, 

49 "deterministic": True, 

50 "renderers": { 

51 "pr_body": "keel.artifacts.render_pr_body", 

52 "issue_update": "keel.artifacts.render_issue_update", 

53 "review_verdict": "keel.artifacts.render_review_verdict", 

54 "jury_verdict": "keel.artifacts.render_jury_verdict", 

55 "review_cycle_summary": "keel.artifacts.render_review_cycle_summary", 

56 "extension_result": "keel.artifacts.render_extension_result", 

57 "step_handoff": "keel.artifacts.render_step_handoff", 

58 "run_control_halt": "keel.artifacts.render_run_control_halt", 

59 "ship_provenance": "keel.artifacts.render_ship_provenance", 

60 }, 

61 "markers": { 

62 "review_verdict": evidence.REVIEW_VERDICT_MARKER, 

63 "jury_verdict": evidence.JURY_VERDICT_MARKER, 

64 "ship_provenance": evidence.SHIP_PROVENANCE_MARKER, 

65 "review_cycle_summary": REVIEW_CYCLE_SUMMARY_MARKER, 

66 "issue_update": ISSUE_UPDATE_MARKER, 

67 "extension_result": EXTENSION_RESULT_MARKER, 

68 "step_handoff": STEP_HANDOFF_MARKER, 

69 "run_control_halt": RUN_CONTROL_HALT_MARKER, 

70 }, 

71 "adapter_rule": "post rendered markdown verbatim when available", 

72 } 

73 

74 

75def render_pr_body( 

76 *, 

77 issue_number: int | None = None, 

78 issue_intake: dict[str, Any] | None = None, 

79 changed_files: list[str] | tuple[str, ...] | None = (), 

80 testing: list[str] | tuple[str, ...] = (), 

81 fix_evidence: list[str] | tuple[str, ...] | None = (), 

82 docs_impact: str | None = None, 

83 base_facts: bool = False, 

84) -> str: 

85 """Render the canonical PR body used by ship implementers. 

86 

87 ``base_facts`` (``team.jury.base_facts``, #1570) adds a :data:`BASE_FACTS_HEADING` 

88 section the implementer fills; keel hands it to the jury ahead of the diff 

89 (:func:`base_facts_section`, :func:`keel.jury.with_base_facts`). 

90 """ 

91 intake = issue_intake if isinstance(issue_intake, dict) else {} 

92 lines = [ 

93 "## Summary", 

94 f"- {_value(intake.get('deliverable'), 'Implement the requested change.')}", 

95 "", 

96 "## Context / Root Cause", 

97 _value(intake.get("objective"), "See the linked issue for context."), 

98 "", 

99 ] 

100 if base_facts: 

101 lines.extend([BASE_FACTS_HEADING, BASE_FACTS_PROMPT, ""]) 

102 lines.append("## Changes Made") 

103 # `None` is "git could not be read", which must not render as "nothing changed". 

104 if changed_files is None: 

105 lines.append("- The changed-file list could not be read from git.") 

106 else: 

107 files = [file for file in changed_files if isinstance(file, str)] 

108 if files: 

109 lines.extend(f"- Updated `{file}`." for file in files) 

110 else: 

111 lines.append("- No changed files recorded yet.") 

112 lines.extend(["", "## Testing"]) 

113 tests = [item for item in testing if isinstance(item, str) and item.strip()] 

114 lines.extend(f"- {item.strip()}" for item in tests) if tests else lines.append( 

115 "- Not run yet; update this section before marking the PR ready." 

116 ) 

117 # A fix's own section, rendered as a prompt rather than a claim. Coverage cannot say 

118 # whether a test *guards* a change — `fail_under = 100` is enforced, so "maintained 100% 

119 # coverage" is true of every merged PR before it is written. An audit of 14 closed fixes 

120 # found three whose tests still passed with the fix removed at the time their issue was closed 

121 # (#877, and one arm each of #871 and #879); later audits added tests that catch them, and 

122 # when #1289 recorded the audit on 2026-09-22 all 14 failed without their fix. All three 

123 # offered coverage as evidence (#1289). 

124 # The unit is the behaviour, not the git hunk: #871's guarded and 

125 # unguarded arms shared one hunk, so a per-hunk claim passed while half the fix was 

126 # unpinned. No caller supplies `fix_evidence` yet — the only one, 

127 # `contracts.ship_result_as_dict`, does not pass it — so from `keel ship --json` this is 

128 # always the prompt, and the 

129 # implementer replaces it. The parameter exists so a future caller can. 

130 lines.extend(["", "## Fix evidence"]) 

131 evidence = [item for item in fix_evidence or () if isinstance(item, str) and item.strip()] 

132 if evidence: 

133 lines.extend(f"- {item.strip()}" for item in evidence) 

134 else: 

135 lines.append( 

136 "- Not stated yet. For each behaviour this change touches — each arm of a " 

137 "conditional, each call site — name a test that fails as an assertion when that " 

138 "one change is reverted, and list any behaviour left unpinned with the reason. " 

139 "`N/A — <docs | pure refactor | dependency bump | packaging>` if there is nothing " 

140 "to revert-test." 

141 ) 

142 lines.extend( 

143 [ 

144 "", 

145 "## Docs Impact", 

146 _value(docs_impact, "Docs Impact: none — no operator-facing behavior changed."), 

147 "", 

148 _closing_reference(issue_number), 

149 ] 

150 ) 

151 return "\n".join(lines).rstrip() + "\n" 

152 

153 

154#: The PR-body section the jury is handed ahead of the diff (#1570), and the prompt the 

155#: rendered body carries until the implementer replaces it. A section still holding the 

156#: prompt states no facts: :func:`base_facts_section` reads it as absent. 

157BASE_FACTS_HEADING = "## Base facts" 

158BASE_FACTS_PROMPT = ( 

159 "- Not stated yet. List each fact about code outside this diff that the change relies " 

160 "on (an existing check upstream, an invariant a caller enforces, current behaviour on " 

161 "the base branch), each with a `path:line` or a commit. The jury verifies every one " 

162 "against the head checkout; write `none` if the change relies on nothing outside the diff." 

163) 

164 

165 

166#: Values in :data:`BASE_FACTS_HEADING` that declare no facts (#1570): ``none``, ``none.``, 

167#: ``n/a``, and the PR template's ``N/A — <reason>`` / ``N/A - <reason>`` convention. 

168_NO_BASE_FACTS_RE = re.compile( 

169 r"(?:none\.?|n/a(?:\.?|\s*[-\u2013\u2014].*))", 

170 re.IGNORECASE | re.DOTALL, 

171) 

172 

173 

174def base_facts_section(pr_body: str | None) -> str | None: 

175 """The body of a PR's :data:`BASE_FACTS_HEADING` section, or ``None`` (#1570). 

176 

177 Everything after the heading up to the next ``## `` heading, stripped. ``None`` when 

178 there is no such section, it is empty, it still carries :data:`BASE_FACTS_PROMPT`, or 

179 it says ``none`` / ``none.`` / ``n/a`` / ``n/a — <reason>`` — each is a PR that states 

180 no facts for the jury to check. 

181 """ 

182 if not isinstance(pr_body, str): 

183 return None 

184 lines = pr_body.splitlines() 

185 try: 

186 start = [line.rstrip() for line in lines].index(BASE_FACTS_HEADING) + 1 

187 except ValueError: 

188 return None 

189 section: list[str] = [] 

190 for line in lines[start:]: 

191 if line.startswith("## "): 

192 break 

193 section.append(line) 

194 text = "\n".join(section).strip() 

195 cleaned = text.lstrip("-* ").strip().strip("`").strip() 

196 if not cleaned or BASE_FACTS_PROMPT in text or _NO_BASE_FACTS_RE.fullmatch(cleaned): 

197 return None 

198 return text 

199 

200 

201def render_jury_followup_issue( 

202 *, pr_number: int, head_sha: str, findings: list[str] | tuple[str, ...] 

203) -> tuple[str, str]: 

204 """``(title, body)`` of the follow-up issue for a COMMENT panel's minors (#1570). 

205 

206 ``keel merge`` files it when ``team.jury.comment_consensus`` is what passed the gate, 

207 so the findings the panel left are tracked instead of merged past and forgotten. 

208 """ 

209 title = f"Follow up the jury's minor findings from #{pr_number}" 

210 lines = [ 

211 f"The jury's consensus on #{pr_number} at `{head_sha}` was `COMMENT`, with no " 

212 "blocking finding, and the review verdicts at that head approved, so " 

213 "`team.jury.comment_consensus` let it merge. These are the minor findings the panel " 

214 "left:", 

215 "", 

216 ] 

217 lines.extend(f"- [ ] {' '.join(item.split())}" for item in findings) 

218 lines.extend(["", f"Refs #{pr_number}"]) 

219 return title, "\n".join(lines) + "\n" 

220 

221 

222def render_issue_update( 

223 *, 

224 issue_number: int | None = None, 

225 pull_request: int | None = None, 

226 status: str = "in-progress", 

227 summary: str | None = None, 

228 next_step: str | None = None, 

229) -> str: 

230 """Render a stable issue progress/update comment.""" 

231 lines = [ 

232 ISSUE_UPDATE_MARKER, 

233 "", 

234 "## Ship update", 

235 "", 

236 f"- **Issue:** {_issue(issue_number)}", 

237 f"- **Pull request:** {_pr(pull_request)}", 

238 f"- **Status:** {_value(status, 'in-progress')}", 

239 f"- **Summary:** {_value(summary, 'No summary recorded.')}", 

240 f"- **Next step:** {_value(next_step, 'Continue the ship workflow.')}", 

241 ] 

242 return "\n".join(lines) + "\n" 

243 

244 

245def render_review_verdict( 

246 *, 

247 reviewer: str, 

248 head_sha: str | None, 

249 verdict: str = "ABSTAIN", 

250 scope: str | None = None, 

251 findings: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

252 testing: str | None = None, 

253 vendor: str | None = None, 

254 model: str | None = None, 

255) -> str: 

256 """Render a head-bound reviewer verdict comment accepted by evidence verification. 

257 

258 When ``vendor`` (and optionally ``model``) is supplied, structured 

259 ``vendor:`` / ``model:`` provenance lines are emitted so evidence 

260 verification can enforce vendor distinctness across required verdicts. The 

261 fields use the same vendor/model conventions as ``keel.provenance`` and are 

262 omitted entirely when not supplied, so the default rendering is unchanged. 

263 

264 **Pass a real ``scope`` or real ``findings``.** The defaults — "Full 

265 changed-file diff and relevant contracts" and "none" — name nothing, and 

266 :func:`keel.evidence.verdict_substance` refuses a verdict that names nothing 

267 (#926). That is deliberate: 75 of 75 verdicts across 25 pull requests were 

268 this template with the defaults left in, and the gate could not tell them 

269 apart from a review that caught a blocker. Any one of these is enough: 

270 

271 * a path (``src/keel/evidence.py``), a ``file.py:42``, a backticked token, 

272 or a called ``module.function()``; 

273 * **two** of the unbackticked forms — a bare filename; a dotted 

274 ``module.symbol`` that carries a mark prose does not use (an underscore, 

275 an internal capital, a run of capitals, or a capitalised segment), so 

276 ``Config.parse`` and ``cache.cache_key`` read and ``foo.bar`` does not; 

277 or a lowercase ``snake_case`` identifier. One alone does not count, because ``Node.js`` and 

278 ``evidence.py`` are spelled the same way and so are ``GitHub.com`` and 

279 ``Config.parse``; naming two things is what a review does and a mention 

280 does not; 

281 * a "Checked X, Y and Z" clause. That one verb keeps a free-form object, 

282 because it predates the rule and the corpus has real reviews under it 

283 naming their objects in English ("Checked the formula syntax, the 

284 version URL and the checksum placeholder"). #1106 tried to widen it to 

285 traced/read/ran/inspected/verified; those could not keep a free-form 

286 object without readmitting the receipt, and requiring their object to 

287 name something made the branch decide nothing at all — the object is 

288 part of the prose, which already takes that test. So they are ordinary 

289 prose: name two things, or one in backticks. 

290 

291 A genuinely clean review stays expressible; it just has to say what it 

292 looked at. 

293 

294 ``verdict`` is written as given on the ``Verdict:`` line, and that line is what the 

295 gate reads (#1426): the verdict counts toward a merge only when its first word is in 

296 :data:`keel.evidence.APPROVING_VERDICTS` (``APPROVE`` / ``LGTM`` / ``PASS``), and one 

297 that requests changes holds the merge. Keep the line; a verdict without it is not an 

298 approval. 

299 """ 

300 lines = [ 

301 evidence.REVIEW_VERDICT_MARKER, 

302 f"reviewer: {_slug(reviewer)}", 

303 f"head: {_value(head_sha, '<head-sha>')}", 

304 ] 

305 if isinstance(vendor, str) and vendor.strip(): 

306 lines.append(f"vendor: {_slug(vendor)}") 

307 if isinstance(model, str) and model.strip(): 

308 lines.append(f"model: {_slug(model)}") 

309 lines.extend( 

310 [ 

311 "", 

312 f"Verdict: {_value(verdict, 'ABSTAIN')}", 

313 "", 

314 f"Scope reviewed: {_value(scope, 'Full changed-file diff and relevant contracts.')}", 

315 "", 

316 "Findings:", 

317 ] 

318 ) 

319 lines.extend(_finding_lines(findings)) 

320 lines.extend(["", f"Testing noted: {_value(testing, 'See PR Testing section.')}"]) 

321 return "\n".join(lines) + "\n" 

322 

323 

324def render_jury_verdict( 

325 *, 

326 head_sha: str | None, 

327 participants: list[str] | tuple[str, ...] = (), 

328 verdict: str | None = "ABSTAIN", 

329 findings_summary: list[str] | tuple[str, ...] = (), 

330 remaining_risks: str | None = None, 

331 participating_vendors: int | None = None, 

332 panelists: int | None = None, 

333) -> str: 

334 """Render a head-bound jury verdict comment accepted by evidence verification. 

335 

336 The verdict declares ``vendors: <N>`` — the distinct vendors that actually 

337 took part. That line is the only channel by which the vendor count reaches a 

338 CI evidence check: the run ledger and the jury artifact both live under the 

339 gitignored ``.keel/state/``, so a hosted runner cannot read them, while PR 

340 comments are always visible. When ``participating_vendors`` is omitted it is 

341 inferred from ``participants``, so a caller that already lists them does not 

342 have to count twice. 

343 

344 ``panelists: <N>`` travels the same channel for the same reason (#1015). When 

345 the panel **is** the review, the number of ballots is the reviewer count the 

346 evidence gate has to require, and it is knowable only once the panel has run. 

347 An undeclared panel size leaves the gate on its floor (the minimum vendor 

348 count) rather than requiring nothing, so omitting it fails closed. Omitted, 

349 it is inferred from ``participants``. 

350 

351 ``verdict`` is the panel's consensus, written on the ``AI Jury verdict:`` line the 

352 evidence gate reads (#1429). Missing or blank, it renders ``ABSTAIN`` — a panel that 

353 stated no consensus did not approve — where it used to render ``LGTM``, an approval 

354 nobody gave. 

355 """ 

356 people = [ 

357 person.strip() for person in participants if isinstance(person, str) and person.strip() 

358 ] 

359 vendors = participating_vendors if participating_vendors is not None else len(people) 

360 seats = panelists if panelists is not None else len(people) 

361 lines = [ 

362 evidence.JURY_VERDICT_MARKER, 

363 f"head: {_value(head_sha, '<head-sha>')}", 

364 f"vendors: {vendors}", 

365 f"panelists: {seats}", 

366 "", 

367 f"AI Jury verdict: {_value(verdict, 'ABSTAIN')}.", 

368 "", 

369 f"Participants: {', '.join(people) if people else 'not recorded'}.", 

370 "", 

371 JURY_SUMMARY_HEADING, 

372 ] 

373 # One line per item, whitespace collapsed: :func:`jury_verdict_summary` reads the 

374 # summary back line by line (#1437), so a message carrying its own newline must not 

375 # end the item early — or start a line that reads as an item of its own. 

376 summaries = [ 

377 " ".join(item.split()) 

378 for item in findings_summary 

379 if isinstance(item, str) and item.strip() 

380 ] 

381 lines.extend(f"- {item}" for item in summaries) if summaries else lines.append("- none") 

382 lines.extend(["", f"{JURY_RISKS_LABEL} {_value(remaining_risks, 'none identified')}."]) 

383 return "\n".join(lines) + "\n" 

384 

385 

386#: The two labels that bracket a jury verdict's findings summary, as 

387#: :func:`render_jury_verdict` writes them and :func:`jury_verdict_summary` reads them. 

388JURY_SUMMARY_HEADING = "Findings summary:" 

389JURY_RISKS_LABEL = "Remaining risks:" 

390 

391 

392def jury_verdict_summary(body: str) -> tuple[str, ...] | None: 

393 """The findings-summary items of a jury verdict :func:`render_jury_verdict` wrote (#1437). 

394 

395 The inverse of the renderer, written against it: every ``- <item>`` line between 

396 :data:`JURY_SUMMARY_HEADING` and :data:`JURY_RISKS_LABEL`, with the renderer's 

397 ``- none`` read as no items. A verdict keel rendered from a panel lists its verified 

398 findings here as ``<severity>: <message>`` (:func:`keel.jury.jury_verdict`), which is 

399 how ``keel ship`` reuses the head's posted panel without convening another. 

400 

401 Read to the risks line rather than to the first blank line, so the parse can only ever 

402 see *more* of the comment than the renderer put in the summary — never stop short of a 

403 finding. A body without the heading is not one keel rendered, and its summary cannot be 

404 read: ``None``, which is never the same answer as "no findings". 

405 """ 

406 lines = body.splitlines() 

407 try: 

408 start = lines.index(JURY_SUMMARY_HEADING) + 1 

409 except ValueError: 

410 return None 

411 items: list[str] = [] 

412 for line in lines[start:]: 

413 if line.startswith(JURY_RISKS_LABEL): 

414 return () if items == ["none"] else tuple(items) 

415 if line.startswith("- "): 

416 items.append(line[2:].strip()) 

417 # No closing risks line: not the shape the renderer writes, so not a summary keel can 

418 # vouch for — unreadable, and the caller convenes the panel instead of reusing it. 

419 return None 

420 

421 

422def render_ship_provenance( 

423 *, 

424 run_id: str | None = None, 

425 issue: int | None = None, 

426 head_sha: str | None = None, 

427 implementer_attribution: dict[str, Any] | None = None, 

428) -> str: 

429 """Render the ship-provenance comment a live run posts on its own PR (#1013). 

430 

431 This comment is the run stamping *itself*: it says which ship run produced the 

432 PR, for which issue, at which head, and — verbatim from 

433 :func:`keel.agents.attribution` — what the implementer's attribution labels are. 

434 :func:`keel.evidence.gate_decision` arms the evidence gate on the marker ahead of 

435 the branch-name regex, so a ship run whose branch is named anything at all still 

436 reads as a keel run instead of as an unreviewed drive-by PR. 

437 

438 ``implementer_attribution`` is the dict :func:`keel.agents.attribution` (or 

439 :func:`keel.agents.profile_attribution`) returns. Pass it through unchanged: the 

440 whole point of the artifact is that the labels are *core's*, not prose's. 

441 """ 

442 record = implementer_attribution if isinstance(implementer_attribution, dict) else {} 

443 lines = [ 

444 evidence.SHIP_PROVENANCE_MARKER, 

445 f"run-id: {_value(run_id, 'not recorded')}", 

446 f"issue: {_issue(issue)}", 

447 f"head: {_value(head_sha, '<head-sha>')}", 

448 f"agent-label: {_value(record.get('agent_label'), 'not recorded')}", 

449 f"model-label: {_value(record.get('model_label'), 'not recorded')}", 

450 f"system: {_value(record.get('system'), 'not recorded')}", 

451 ] 

452 profile = record.get("delegate_profile") 

453 if isinstance(profile, str) and profile.strip(): 

454 lines.append(f"delegate-profile: {profile.strip()}") 

455 lines.extend( 

456 [ 

457 "", 

458 ( 

459 "Provenance stamp for a keel run: this pull request came out of the backbone, " 

460 "so the evidence gate applies to it." 

461 ), 

462 "", 

463 ( 

464 "The attribution labels above come from `keel attribution` — apply them to the " 

465 "PR verbatim rather than composing them by hand." 

466 ), 

467 ] 

468 ) 

469 return "\n".join(lines) + "\n" 

470 

471 

472def render_review_cycle_summary( 

473 *, 

474 reviewers: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

475 head_sha: str | None = None, 

476 run_id: str | None = None, 

477) -> str: 

478 """Render the deterministic multi-reviewer review-cycle summary comment. 

479 

480 Emits one section per reviewer (codename · focus · verdict · a 

481 ``Severity | File:Line | Description | Suggested Fix`` finding table) followed 

482 by a consolidated summary whose severity histogram — not the verdict strings — 

483 is the source of truth for the merge recommendation. The output is byte-stable 

484 for a given input so the orchestrator posts it verbatim instead of improvising 

485 a layout. When ``run_id`` is supplied an invisible ``keel.run-id`` marker is 

486 appended so an idempotent re-post edits the existing comment in place. 

487 """ 

488 clean = [reviewer for reviewer in reviewers if isinstance(reviewer, dict)] 

489 lines = [ 

490 REVIEW_CYCLE_SUMMARY_MARKER, 

491 f"head: {_value(head_sha, '<head-sha>')}", 

492 "", 

493 ] 

494 for index, reviewer in enumerate(clean): 

495 if index: 

496 lines.extend(["", "---", ""]) 

497 lines.extend(_cycle_reviewer_lines(reviewer)) 

498 if clean: 

499 lines.extend(["", "---", ""]) 

500 lines.extend(_cycle_summary_lines(clean)) 

501 if isinstance(run_id, str) and run_id.strip(): 

502 lines.extend(["", f"<!-- keel.run-id: {run_id.strip()} -->"]) 

503 return "\n".join(lines) + "\n" 

504 

505 

506def render_coverage_delta( 

507 *, 

508 codename: str, 

509 base_sha: str | None = None, 

510 head_sha: str | None = None, 

511 areas: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

512) -> str: 

513 """Render the deterministic per-PR coverage delta comment. 

514 

515 The literal first line is the caller-supplied ``codename`` (e.g. 

516 ``COVERAGE-<PR>-<UTC>``) — the load-bearing anchor the adapter finds by prefix 

517 to update the comment in place, so nothing precedes it. The adapter supplies 

518 the timestamped codename, so the renderer stays pure and byte-stable for a 

519 given input. 

520 """ 

521 lines = [ 

522 codename, 

523 "", 

524 f"Coverage delta: base@{_value(base_sha, '<base>')} → head@{_value(head_sha, '<head>')}", 

525 ] 

526 for area in areas: 

527 if isinstance(area, dict): 

528 lines.extend(["", *_coverage_area_lines(area)]) 

529 lines.extend(["", f"<!-- {COVERAGE_DELTA_MARKER} -->"]) 

530 return "\n".join(lines) + "\n" 

531 

532 

533def render_deps_audit( 

534 *, 

535 codename: str, 

536 ecosystems: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

537 licences: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

538 skipped: list[str] | tuple[str, ...] = (), 

539 security_only: bool = False, 

540) -> str: 

541 """Render the deterministic dependency-audit comment for the tracking issue. 

542 

543 The literal first line is the caller-supplied ``codename`` (e.g. 

544 ``DEPS-AUDIT-<DATE>-<UTC>``); a fresh comment is appended per run, found later 

545 by that prefix. Under ``security_only`` the licence-drift section is omitted. 

546 """ 

547 counts = _deps_counts(ecosystems) 

548 lines = [ 

549 codename, 

550 "", 

551 " | ".join(f"{severity}: {counts[severity]}" for severity in DEPS_SEVERITY_ORDER), 

552 ] 

553 for ecosystem in ecosystems: 

554 if isinstance(ecosystem, dict): 

555 lines.extend(["", *_deps_ecosystem_lines(ecosystem)]) 

556 if not security_only: 

557 lines.extend(["", *_deps_licence_lines(licences)]) 

558 skipped_items = _string_list(skipped) 

559 if skipped_items: 

560 lines.extend(["", "## Skipped", ""]) 

561 lines.extend(f"- {item}" for item in skipped_items) 

562 lines.extend(["", f"<!-- {DEPS_AUDIT_MARKER} -->"]) 

563 return "\n".join(lines) + "\n" 

564 

565 

566def render_flake_audit( 

567 *, 

568 codename: str, 

569 summary: dict[str, Any] | None = None, 

570 new_flakes: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

571 tracked: list[dict[str, Any]] | tuple[dict[str, Any], ...] = (), 

572 limitations: list[str] | tuple[str, ...] = (), 

573) -> str: 

574 """Render the deterministic flake-audit report comment. 

575 

576 The literal first line is the caller-supplied ``codename`` (e.g. 

577 ``FLAKE-AUDIT-<DATE>-<UTC>``). Newly-classified flakes render as a table (or a 

578 single italic line when none cleared the threshold); already-tracked flakes 

579 and honest limitations render only when present. 

580 """ 

581 stats = summary if isinstance(summary, dict) else {} 

582 lines = [ 

583 codename, 

584 "", 

585 ( 

586 f"runs examined: {_count(stats.get('runs'))} · " 

587 f"distinct failing tests: {_count(stats.get('distinct'))} · " 

588 f"classified flakes: {_count(stats.get('classified'))} · " 

589 f"newly-opened issues: {_count(stats.get('opened'))}" 

590 ), 

591 "", 

592 "## Newly classified flakes", 

593 "", 

594 ] 

595 flakes = _dict_list(new_flakes) 

596 if flakes: 

597 lines.append("| Test | Fail rate | Failures | Sample runs | Signature |") 

598 lines.append("| --- | --- | --- | --- | --- |") 

599 lines.extend( 

600 _table_row( 

601 [ 

602 _cell(_value(flake.get("test"), "—")), 

603 _cell(_value(flake.get("fail_rate"), "—")), 

604 _cell(str(_count(flake.get("failures")))), 

605 _cell(", ".join(_string_list(flake.get("samples"))) or "—"), 

606 _cell(_value(flake.get("signature"), "—")), 

607 ] 

608 ) 

609 for flake in flakes 

610 ) 

611 else: 

612 lines.append("_no new flakes above threshold_") 

613 tracked_rows = _dict_list(tracked) 

614 if tracked_rows: 

615 lines.extend(["", "## Already tracked (deduped)", ""]) 

616 lines.extend( 

617 f"- {_value(row.get('test'), '—')} — see {_issue_ref(row.get('issue'))}" 

618 for row in tracked_rows 

619 ) 

620 limitation_items = _string_list(limitations) 

621 if limitation_items: 

622 lines.extend(["", "## Limitations", ""]) 

623 lines.extend(f"- {item}" for item in limitation_items) 

624 lines.extend(["", f"<!-- {FLAKE_AUDIT_MARKER} -->"]) 

625 return "\n".join(lines) + "\n" 

626 

627 

628def _table_row(cells: list[str]) -> str: 

629 return "| " + " | ".join(cells) + " |" 

630 

631 

632def _dict_list(raw: Any) -> list[dict[str, Any]]: 

633 if not isinstance(raw, (list, tuple)): 

634 return [] 

635 return [item for item in raw if isinstance(item, dict)] 

636 

637 

638def _count(value: Any) -> int: 

639 return value if isinstance(value, int) and not isinstance(value, bool) else 0 

640 

641 

642def _issue_ref(value: Any) -> str: 

643 if isinstance(value, int) and not isinstance(value, bool): 

644 return f"#{value}" 

645 return _value(value, "?") 

646 

647 

648def _scalar(value: Any, fallback: str) -> str: 

649 if isinstance(value, bool): 

650 return fallback 

651 if isinstance(value, int): 

652 return str(value) 

653 return _value(value, fallback) 

654 

655 

656def _is_number(value: Any) -> bool: 

657 return isinstance(value, (int, float)) and not isinstance(value, bool) 

658 

659 

660def _fmt_pct(value: Any) -> str: 

661 return f"{value:.1f}%" if _is_number(value) else "—" 

662 

663 

664def _fmt_delta(base: Any, head: Any) -> tuple[str, bool]: 

665 if _is_number(base) and _is_number(head): 

666 delta = head - base 

667 return f"{delta:+.1f}%", abs(delta) >= 0.5 

668 return "—", False 

669 

670 

671def _coverage_row(unit: str, base: Any, head: Any, files: Any, *, is_overall: bool = False) -> str: 

672 delta_text, bold = _fmt_delta(base, head) 

673 files_text = _cell(str(files)) if str(files).strip() else "" 

674 cells = [_cell(unit), _fmt_pct(base), _fmt_pct(head), delta_text, files_text] 

675 if bold: 

676 cells = [f"**{cell}**" if cell else "" for cell in cells] 

677 elif is_overall: 

678 cells[0] = f"**{cells[0]}**" 

679 return _table_row(cells) 

680 

681 

682def _coverage_area_lines(area: dict[str, Any]) -> list[str]: 

683 name = _value(area.get("name"), "area") 

684 if area.get("skipped"): 

685 return [f"_{name} coverage skipped: {_value(area.get('skip_reason'), 'not run')}_"] 

686 lines = [ 

687 f"## {name}", 

688 "", 

689 "| Unit | Base % | Head % | Δ | Files |", 

690 "| --- | --- | --- | --- | --- |", 

691 ] 

692 lines.extend( 

693 _coverage_row( 

694 _value(row.get("unit"), "—"), row.get("base"), row.get("head"), row.get("files", "") 

695 ) 

696 for row in _dict_list(area.get("rows")) 

697 ) 

698 overall = area.get("overall") 

699 if isinstance(overall, dict): 

700 lines.append( 

701 _coverage_row("overall", overall.get("base"), overall.get("head"), "", is_overall=True) 

702 ) 

703 return lines 

704 

705 

706def _deps_sev_rank(severity: str) -> int: 

707 lowered = severity.lower() 

708 return ( 

709 DEPS_SEVERITY_ORDER.index(lowered) 

710 if lowered in DEPS_SEVERITY_ORDER 

711 else len(DEPS_SEVERITY_ORDER) 

712 ) 

713 

714 

715def _deps_counts(ecosystems: Any) -> dict[str, int]: 

716 counts = dict.fromkeys(DEPS_SEVERITY_ORDER, 0) 

717 for ecosystem in _dict_list(ecosystems): 

718 for finding in _dict_list(ecosystem.get("findings")): 

719 severity = _value(finding.get("severity"), "low").lower() 

720 if severity in counts: 

721 counts[severity] += 1 

722 return counts 

723 

724 

725def _deps_ecosystem_lines(ecosystem: dict[str, Any]) -> list[str]: 

726 name = _value(ecosystem.get("name"), "ecosystem") 

727 findings = _dict_list(ecosystem.get("findings")) 

728 if not findings: 

729 threshold = _value(ecosystem.get("threshold"), "low") 

730 return [f"_No {name} findings at or above {threshold} severity._"] 

731 findings = sorted(findings, key=lambda f: _deps_sev_rank(_value(f.get("severity"), "low"))) 

732 lines = [ 

733 f"## {name}", 

734 "", 

735 "| Package | Version | Severity | Advisory | Fix available |", 

736 "| --- | --- | --- | --- | --- |", 

737 ] 

738 lines.extend( 

739 _table_row( 

740 [ 

741 _cell(_value(finding.get("package"), "—")), 

742 _cell(_value(finding.get("version"), "—")), 

743 _cell(_value(finding.get("severity"), "low")), 

744 _cell(_value(finding.get("advisory"), "—")), 

745 _cell(_value(finding.get("fix_available"), "—")), 

746 ] 

747 ) 

748 for finding in findings 

749 ) 

750 return lines 

751 

752 

753def _deps_licence_lines(licences: Any) -> list[str]: 

754 rows = _dict_list(licences) 

755 if not rows: 

756 return ["_licences: no drift_"] 

757 lines = [ 

758 "## Licences", 

759 "", 

760 "| Status | Package | Baseline | Current |", 

761 "| --- | --- | --- | --- |", 

762 ] 

763 lines.extend( 

764 _table_row( 

765 [ 

766 _cell(_value(row.get("status"), "—")), 

767 _cell(_value(row.get("package"), "—")), 

768 _cell(_value(row.get("baseline"), "—")), 

769 _cell(_value(row.get("current"), "—")), 

770 ] 

771 ) 

772 for row in rows 

773 ) 

774 return lines 

775 

776 

777def render_scan_finding_issue( 

778 *, 

779 problem: str | None = None, 

780 location: str | None = None, 

781 severity: str | None = None, 

782 justification: str | None = None, 

783 evidence: str | None = None, 

784 suggested_fix: str | None = None, 

785 source: str | None = None, 

786 regression_of: int | None = None, 

787) -> str: 

788 """Render the deterministic issue body for a scan finding. 

789 

790 Shared by ``regression`` and ``review-all-day`` — the body carries the 

791 problem statement, ``path:line`` location, severity + justification, fenced 

792 evidence, and suggested fix, plus a provenance marker. When ``regression_of`` 

793 is supplied the grep-able ``regression-of: #N`` cross-reference is the body's 

794 literal last line. 

795 """ 

796 lines = [ 

797 "## Problem", 

798 "", 

799 _value(problem, "A scan finding was reported without a problem statement."), 

800 "", 

801 "## Location", 

802 "", 

803 f"`{_value(location, 'unknown')}`", 

804 "", 

805 "## Severity", 

806 "", 

807 f"{_value(severity, 'minor')} — {_value(justification, 'no justification recorded')}", 

808 "", 

809 "## Evidence", 

810 "", 

811 "```", 

812 _value(evidence, "none provided"), 

813 "```", 

814 "", 

815 "## Suggested fix", 

816 "", 

817 _value(suggested_fix, "none proposed"), 

818 "", 

819 f"Found by keel {_value(source, 'scan')}.", 

820 "", 

821 f"<!-- {SCAN_FINDING_MARKER} -->", 

822 ] 

823 if isinstance(regression_of, int) and not isinstance(regression_of, bool): 

824 lines.extend(["", f"regression-of: #{regression_of}"]) 

825 return "\n".join(lines) + "\n" 

826 

827 

828def render_triage_audit( 

829 *, 

830 issue: int | None = None, 

831 role: str | None = None, 

832 priority: str | None = None, 

833 status: str | None = None, 

834 tier: int | str | None = None, 

835 rationale: str | None = None, 

836 run_id: str | None = None, 

837) -> str: 

838 """Render the deterministic, label-only triage audit comment. 

839 

840 One comment per triaged issue: the applied role / priority / status labels and 

841 risk tier on one line, then the classifier's rationale. When ``run_id`` is 

842 supplied an idempotent re-post edits the existing comment in place. 

843 """ 

844 labels = " · ".join( 

845 [ 

846 f"role: {_value(role, 'unassigned')}", 

847 f"priority: {_value(priority, 'unset')}", 

848 f"status: {_value(status, 'unset')}", 

849 f"tier: {_scalar(tier, 'n/a')}", 

850 ] 

851 ) 

852 lines = [ 

853 TRIAGE_AUDIT_MARKER, 

854 f"keel triage — {_issue_ref(issue)}: {labels}", 

855 "", 

856 _value(rationale, "Classified from the existing label set."), 

857 ] 

858 if isinstance(run_id, str) and run_id.strip(): 

859 lines.extend(["", f"<!-- keel.run-id: {run_id.strip()} -->"]) 

860 return "\n".join(lines) + "\n" 

861 

862 

863def render_extension_result( 

864 *, 

865 slot: str, 

866 extension_id: str, 

867 status: str, 

868 mode: str, 

869 summary: str | None = None, 

870 artifacts: list[str] | tuple[str, ...] = (), 

871 follow_ups: list[str] | tuple[str, ...] = (), 

872) -> str: 

873 """Render a canonical extension result block/comment.""" 

874 lines = [ 

875 EXTENSION_RESULT_MARKER, 

876 "", 

877 "## Extension result", 

878 "", 

879 f"- **Slot:** `{_value(slot, 'unknown')}`", 

880 f"- **Extension:** `{_value(extension_id, 'unknown')}`", 

881 f"- **Status:** {_value(status, 'not-recorded')}", 

882 f"- **Mode:** {_value(mode, 'advisory')}", 

883 f"- **Summary:** {_value(summary, 'No summary recorded.')}", 

884 "- **Artifacts:**", 

885 ] 

886 artifact_lines = _string_bullets(artifacts) 

887 lines.extend(artifact_lines if artifact_lines else [" - none"]) 

888 lines.append("- **Follow-ups:**") 

889 follow_up_lines = _string_bullets(follow_ups) 

890 lines.extend(follow_up_lines if follow_up_lines else [" - none"]) 

891 return "\n".join(lines) + "\n" 

892 

893 

894def render_step_handoff( 

895 *, 

896 step_id: str, 

897 step_name: str | None = None, 

898 status: str = "complete", 

899 summary: str | None = None, 

900 next_step: str | None = None, 

901 evidence_ids: list[str] | tuple[str, ...] = (), 

902) -> str: 

903 """Render the canonical structured handoff between backbone steps.""" 

904 lines = [ 

905 STEP_HANDOFF_MARKER, 

906 "", 

907 "## Step handoff", 

908 "", 

909 f"- **Step:** `{_value(step_id, 'unknown')}`", 

910 f"- **Name:** {_value(step_name, 'not recorded')}", 

911 f"- **Status:** {_value(status, 'complete')}", 

912 f"- **Summary:** {_value(summary, 'No summary recorded.')}", 

913 f"- **Next step:** {_value(next_step, 'Continue the backbone plan.')}", 

914 "- **Evidence:**", 

915 ] 

916 evidence_lines = _string_bullets(evidence_ids) 

917 lines.extend(evidence_lines if evidence_lines else [" - none"]) 

918 return "\n".join(lines) + "\n" 

919 

920 

921def render_run_control_halt( 

922 *, 

923 control: str, 

924 reason: str, 

925 scope: str | None = None, 

926 observed: int | str | None = None, 

927 limit: int | str | None = None, 

928 action: str | None = None, 

929) -> str: 

930 """Render a stable hard-halt reason emitted by run controls.""" 

931 lines = [ 

932 RUN_CONTROL_HALT_MARKER, 

933 "", 

934 "## Run control halt", 

935 "", 

936 f"- **Control:** `{_value(control, 'unknown')}`", 

937 f"- **Reason:** {_value(reason, 'No reason recorded.')}", 

938 f"- **Scope:** {_value(scope, 'run')}", 

939 f"- **Observed:** {_value(observed, 'not recorded')}", 

940 f"- **Limit:** {_value(limit, 'not recorded')}", 

941 f"- **Action:** {_value(action, 'halt')}", 

942 ] 

943 return "\n".join(lines) + "\n" 

944 

945 

946def _finding_lines(findings: list[dict[str, Any]] | tuple[dict[str, Any], ...]) -> list[str]: 

947 if not findings: 

948 return ["- none"] 

949 lines: list[str] = [] 

950 for finding in findings: 

951 severity = _value(finding.get("severity") if isinstance(finding, dict) else None, "nit") 

952 message = _value(finding.get("message") if isinstance(finding, dict) else None, "") 

953 if message: 

954 lines.append(f"- {severity}: {message}") 

955 return lines or ["- none"] 

956 

957 

958def _string_bullets(values: list[str] | tuple[str, ...]) -> list[str]: 

959 return [f" - {value.strip()}" for value in values if isinstance(value, str) and value.strip()] 

960 

961 

962def _string_list(values: Any) -> list[str]: 

963 if not isinstance(values, (list, tuple)): 

964 return [] 

965 return [value.strip() for value in values if isinstance(value, str) and value.strip()] 

966 

967 

968def _canonical_severity(severity: str) -> str: 

969 lowered = severity.strip().lower() 

970 return _SEVERITY_ALIASES.get(lowered, lowered) 

971 

972 

973def _severity_rank(severity: str) -> int: 

974 canonical = _canonical_severity(severity) 

975 return SEVERITY_ORDER.index(canonical) if canonical in SEVERITY_ORDER else len(SEVERITY_ORDER) 

976 

977 

978def _cell(value: str) -> str: 

979 """Escape a non-empty finding string for a Markdown table cell. 

980 

981 Callers pass values already normalised through ``_value`` (never blank), so 

982 escaping the table delimiter and folding newlines keeps the row intact. 

983 """ 

984 return value.replace("\n", " ").replace("|", "\\|") 

985 

986 

987def _cycle_findings(raw: Any) -> list[dict[str, str]]: 

988 if not isinstance(raw, (list, tuple)): 

989 return [] 

990 findings = [ 

991 { 

992 "severity": _value(item.get("severity"), "nit"), 

993 "location": _value(item.get("location"), "—"), 

994 "description": _value(item.get("description"), "—"), 

995 "suggested_fix": _value(item.get("suggested_fix"), "—"), 

996 } 

997 for item in raw 

998 if isinstance(item, dict) 

999 ] 

1000 findings.sort(key=lambda finding: _severity_rank(finding["severity"])) 

1001 return findings 

1002 

1003 

1004#: What a review-cycle reviewer entry with no ``verdict`` renders and counts as (#1439). It 

1005#: used to be ``LGTM``, so a reviewer who said nothing read as approving and the merge 

1006#: recommendation could come out "approve"; a missing verdict is no verdict, as 

1007#: :func:`render_jury_verdict` reads one since #1432. 

1008_CYCLE_NO_VERDICT = "ABSTAIN" 

1009 

1010 

1011def _cycle_verdict(reviewer: dict[str, Any]) -> str: 

1012 """A review-cycle reviewer's verdict, or :data:`_CYCLE_NO_VERDICT` when it gave none.""" 

1013 return _value(reviewer.get("verdict"), _CYCLE_NO_VERDICT) 

1014 

1015 

1016def _cycle_reviewer_lines(reviewer: dict[str, Any]) -> list[str]: 

1017 lines = [ 

1018 f"## Reviewer: {_value(reviewer.get('codename'), 'Reviewer')} " 

1019 f"(Focus: {_value(reviewer.get('focus'), 'general review')})", 

1020 "", 

1021 f"Verdict: {_cycle_verdict(reviewer)}", 

1022 "", 

1023 ] 

1024 findings = _cycle_findings(reviewer.get("findings")) 

1025 if findings: 

1026 lines.append("| Severity | File:Line | Description | Suggested Fix |") 

1027 lines.append("| --- | --- | --- | --- |") 

1028 lines.extend( 

1029 f"| {_cell(finding['severity'])} | {_cell(finding['location'])} | " 

1030 f"{_cell(finding['description'])} | {_cell(finding['suggested_fix'])} |" 

1031 for finding in findings 

1032 ) 

1033 else: 

1034 lines.append("No findings.") 

1035 clean_areas = _string_list(reviewer.get("clean_areas")) 

1036 if clean_areas: 

1037 lines.extend(["", f"Clean areas: {', '.join(clean_areas)}"]) 

1038 return lines 

1039 

1040 

1041def _cycle_histogram(reviewers: list[dict[str, Any]]) -> dict[str, int]: 

1042 histogram = dict.fromkeys(SEVERITY_ORDER, 0) 

1043 for reviewer in reviewers: 

1044 for finding in _cycle_findings(reviewer.get("findings")): 

1045 canonical = _canonical_severity(finding["severity"]) 

1046 if canonical in histogram: 

1047 histogram[canonical] += 1 

1048 return histogram 

1049 

1050 

1051def _aggregate_clean_areas(reviewers: list[dict[str, Any]]) -> list[str]: 

1052 # Optimize deduplication: O(N) using C-level dict.fromkeys instead of O(N^2) list lookups 

1053 return list( 

1054 dict.fromkeys( 

1055 area for reviewer in reviewers for area in _string_list(reviewer.get("clean_areas")) 

1056 ) 

1057 ) 

1058 

1059 

1060def _merge_recommendation(reviewers: list[dict[str, Any]], histogram: dict[str, int]) -> str: 

1061 needs_fixes = any( 

1062 not _cycle_verdict(reviewer).lower().startswith("lgtm") for reviewer in reviewers 

1063 ) 

1064 if needs_fixes or histogram["blocker"] > 0: 

1065 return "❌ block" 

1066 if histogram["major"] + histogram["minor"] > 0: 

1067 return "⚠️ request changes" 

1068 if histogram["nit"] > 0: 

1069 return "✅ approve (cosmetic nits)" 

1070 return "✅ approve" 

1071 

1072 

1073def _cycle_summary_lines(reviewers: list[dict[str, Any]]) -> list[str]: 

1074 histogram = _cycle_histogram(reviewers) 

1075 lines = [ 

1076 "## Consolidated Summary", 

1077 "", 

1078 "Severity Histogram: " 

1079 + " · ".join(f"{severity} {histogram[severity]}" for severity in SEVERITY_ORDER), 

1080 "", 

1081 "Reviewer verdicts:", 

1082 ] 

1083 if reviewers: 

1084 lines.extend( 

1085 f"- {_value(reviewer.get('codename'), 'Reviewer')}: {_cycle_verdict(reviewer)}" 

1086 for reviewer in reviewers 

1087 ) 

1088 else: 

1089 lines.append("- none") 

1090 areas = _aggregate_clean_areas(reviewers) 

1091 lines.extend(["", f"Clean areas: {', '.join(areas) if areas else 'none reported'}"]) 

1092 lines.extend(["", f"Merge recommendation: {_merge_recommendation(reviewers, histogram)}"]) 

1093 return lines 

1094 

1095 

1096def _closing_reference(issue_number: int | None) -> str: 

1097 return f"Closes #{issue_number}" if isinstance(issue_number, int) else "Refs #<issue-number>" 

1098 

1099 

1100def _issue(issue_number: int | None) -> str: 

1101 return f"#{issue_number}" if isinstance(issue_number, int) else "not recorded" 

1102 

1103 

1104def _pr(pull_request: int | None) -> str: 

1105 return f"#{pull_request}" if isinstance(pull_request, int) else "not opened" 

1106 

1107 

1108def slug(value: str) -> str: 

1109 """Stable, deterministic slug for reviewer/run-id sub-keys (public alias).""" 

1110 clean = "".join(ch.lower() if ch.isalnum() else "-" for ch in value.strip()) 

1111 return "-".join(part for part in clean.split("-") if part) or "reviewer" 

1112 

1113 

1114def _slug(value: str) -> str: 

1115 return slug(value) 

1116 

1117 

1118def _value(value: Any, fallback: str) -> str: 

1119 if isinstance(value, str) and value.strip(): 

1120 return value.strip() 

1121 return fallback