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
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
1"""Canonical Markdown renderers for ship artifacts.
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"""
8from __future__ import annotations
10import re
11from typing import Any
13from . import evidence
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"
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"}
40#: Dependency-advisory severity buckets, most → least severe.
41DEPS_SEVERITY_ORDER = ("critical", "high", "moderate", "low")
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 }
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.
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"
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)
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)
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).
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
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).
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"
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"
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.
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.
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:
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.
291 A genuinely clean review stays expressible; it just has to say what it
292 looked at.
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"
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.
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.
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``.
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"
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:"
392def jury_verdict_summary(body: str) -> tuple[str, ...] | None:
393 """The findings-summary items of a jury verdict :func:`render_jury_verdict` wrote (#1437).
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.
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
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).
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.
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"
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.
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"
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.
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"
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.
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"
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.
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"
628def _table_row(cells: list[str]) -> str:
629 return "| " + " | ".join(cells) + " |"
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)]
638def _count(value: Any) -> int:
639 return value if isinstance(value, int) and not isinstance(value, bool) else 0
642def _issue_ref(value: Any) -> str:
643 if isinstance(value, int) and not isinstance(value, bool):
644 return f"#{value}"
645 return _value(value, "?")
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)
656def _is_number(value: Any) -> bool:
657 return isinstance(value, (int, float)) and not isinstance(value, bool)
660def _fmt_pct(value: Any) -> str:
661 return f"{value:.1f}%" if _is_number(value) else "—"
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
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)
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
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 )
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
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
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
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.
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"
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.
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"
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"
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"
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"
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"]
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()]
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()]
968def _canonical_severity(severity: str) -> str:
969 lowered = severity.strip().lower()
970 return _SEVERITY_ALIASES.get(lowered, lowered)
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)
978def _cell(value: str) -> str:
979 """Escape a non-empty finding string for a Markdown table cell.
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("|", "\\|")
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
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"
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)
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
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
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 )
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"
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
1096def _closing_reference(issue_number: int | None) -> str:
1097 return f"Closes #{issue_number}" if isinstance(issue_number, int) else "Refs #<issue-number>"
1100def _issue(issue_number: int | None) -> str:
1101 return f"#{issue_number}" if isinstance(issue_number, int) else "not recorded"
1104def _pr(pull_request: int | None) -> str:
1105 return f"#{pull_request}" if isinstance(pull_request, int) else "not opened"
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"
1114def _slug(value: str) -> str:
1115 return slug(value)
1118def _value(value: Any, fallback: str) -> str:
1119 if isinstance(value, str) and value.strip():
1120 return value.strip()
1121 return fallback