Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions adapters/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

All of the Factory's I/O. `github.py` is the one transport: every request to GitHub goes through it, and nothing else in
this repo reaches the network. `pull.py` reads the facts of a pull request that its own reads give, `timeline.py` its reviews, labels and who acted,
`checks.py` its checks and its place in the queue, `facts.py` the one snapshot of it all, `records.py` the Factory's own run records,
and `artifacts.py` a failed Run's outcome from its artifact. A port decides nothing
`checks.py` its checks and its place in the queue, `threads.py` its review threads, `facts.py` the one snapshot of it all,
`records.py` the Factory's own run records, and `artifacts.py` a failed Run's outcome from its artifact. A port decides nothing
and hands the Kernel no text: what it cannot read whole it says is short, and the title travels beside the facts.

Not built yet, by the stories that hold their rules: threads.py, items.py, acceptance.py, issues.py, settings.py, effects.py, usage.py.
Not built yet, by the stories that hold their rules: items.py, acceptance.py, issues.py, settings.py, effects.py, usage.py.

| Rule | Held by |
|---|---|
Expand All @@ -26,6 +26,9 @@ Not built yet, by the stories that hold their rules: threads.py, items.py, accep
| A run counts only as a dispatch of a Role's workflow from this repo's default branch; its name says whose it is | `tests/test_adapters.py::test_only_a_dispatch_of_a_role_workflow_from_the_default_branch_in_this_repo_counts` |
| A counted run not yet named is reported by its id after one more read 5 s later, and every read of runs is uncached | `tests/test_adapters.py::test_a_run_listed_under_its_workflows_name_is_unidentified_after_one_more_read` |
| Write access is a person's alone, read from the collaborator permission, admin, maintain or write, once a login | `tests/test_adapters.py::test_an_actor_is_told_by_its_account_type_and_the_configuration` |
| Each review thread is read with who opened and resolved it, told by account; a person's is `human`, and no comment's text is read | `tests/test_adapters.py::test_each_thread_is_read_with_who_opened_and_resolved_it_and_a_persons_is_human` |
| A thread is a Lens's only when its author is that Lens's own App; only a required model Lens's open thread with no category defers | `tests/test_adapters.py::test_only_a_required_lenss_own_apps_open_thread_defers` |
| Threads are whole only when every one counted was read, once, and no cursor repeats | `tests/test_adapters.py::test_threads_are_read_page_by_page_and_whole_only_when_every_one_was_read_once` |
| A review's dismissal, its dismisser and its state before are read from the timeline; no text of GitHub's is kept | `tests/test_adapters.py::test_reviews_are_read_with_their_commit_content_and_who_dismissed_them` |
| Every check run on the head is given with its exact name, its App and its workflow file, and none dropped | `tests/test_adapters.py::test_every_check_run_on_the_head_is_read_with_its_name_app_and_workflow` |
| The snapshot is refused when the pull request moved while it was read, and is held to `facts/1` | `tests/test_adapters.py::test_a_snapshot_whose_head_moved_while_it_was_read_is_refused` |
Expand Down
26 changes: 10 additions & 16 deletions adapters/checks.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
"""The checks on a pull request's head, its place in the merge queue, and how many review threads it holds, in one
GraphQL read of the head's status rollup (design section 3.3; P-32's read gives the shape).
"""The checks on a pull request's head and its place in the merge queue, in one GraphQL read of the head's status
rollup (design section 3.3; P-32's read gives the shape).

Every check run the head's rollup lists is given with its name exactly as GitHub gives it, the id of the App that
reported it, the path of the workflow file that ran it, null where GitHub names none, its conclusion, or its status
Expand All @@ -12,8 +12,6 @@
short. Whether the pull request is in the merge queue is its entry, an object, or null: any other shape is refused. A
rollup of another commit than the head is refused, and so is one read while the pull request's head moved.

A thread's resolved state and its Finding's category are `adapters/threads.py`'s, not built: here only their count is
read, so that a pull request with no thread is read whole and one with any is not.
"""
from __future__ import annotations

Expand All @@ -29,7 +27,6 @@
pullRequest(number: $number) {
headRefOid
mergeQueueEntry { position }
reviewThreads(first: 1) { totalCount }
commits(last: 1) {
nodes {
commit {
Expand Down Expand Up @@ -82,9 +79,9 @@ def check(node: dict) -> dict:

def read(transport, pull: dict) -> dict:
"""The head's check runs and whether they were read whole, whether the pull request is in the merge queue, and
how many review threads it holds; every page is of the head the pull request's first read named."""
every page is of the head the pull request's first read named."""
owner, name = pull["base"]["repo"]["full_name"].split("/")
found, after, queue, threads, seen, total, ids, cursors = [], None, None, None, 0, None, [], set()
found, after, queue, seen, total, ids, cursors = [], None, None, 0, None, [], set()
while True:
variables = {"owner": owner, "name": name, "number": pull["number"], "after": after}
answer = transport.send(request("POST", "/graphql", body={"query": QUERY, "variables": variables}))
Expand All @@ -97,20 +94,17 @@ def read(transport, pull: dict) -> dict:
raise Unanswered("the checks were read of another commit than the head")
if pr.get("headRefOid") != pull["head"]["sha"]:
raise Unanswered("the pull request's head moved while its checks were read")
count = (pr.get("reviewThreads") or {}).get("totalCount") if isinstance(pr.get("reviewThreads"), dict) else None
if not isinstance(count, int) or isinstance(count, bool) or count < 0:
raise Unanswered("the count of review threads cannot be read")
entry = pr.get("mergeQueueEntry", False)
if not (entry is None or isinstance(entry, dict)):
raise Unanswered("the pull request's place in the merge queue cannot be read")
queue, threads = entry is not None, count
queue = entry is not None
rollup = commit.get("statusCheckRollup")
if rollup is None:
return {"checks": found, "complete": after is None, "queue": queue, "threads": threads}
return {"checks": found, "complete": after is None, "queue": queue}
contexts = rollup.get("contexts") if isinstance(rollup, dict) else None
page = (contexts or {}).get("pageInfo") if isinstance(contexts, dict) else None
if not isinstance(contexts, dict) or not isinstance(contexts.get("nodes"), list) or not isinstance(page, dict):
return {"checks": found, "complete": False, "queue": queue, "threads": threads}
return {"checks": found, "complete": False, "queue": queue}
counted = contexts.get("totalCount")
total = counted if total is None else total
for node in contexts["nodes"]:
Expand All @@ -126,10 +120,10 @@ def read(transport, pull: dict) -> dict:
whole = isinstance(total, int) and not isinstance(total, bool) and counted == total and seen == total
if after is not None:
whole = whole and all(isinstance(i, str) and i for i in ids) and len(set(ids)) == len(ids)
return {"checks": found, "complete": whole, "queue": queue, "threads": threads}
return {"checks": found, "complete": whole, "queue": queue}
if page.get("hasNextPage") is not True or not isinstance(page.get("endCursor"), str) or not page["endCursor"]:
return {"checks": found, "complete": False, "queue": queue, "threads": threads}
return {"checks": found, "complete": False, "queue": queue}
if page["endCursor"] in cursors or not isinstance(total, int) or isinstance(total, bool) or seen >= total:
return {"checks": found, "complete": False, "queue": queue, "threads": threads}
return {"checks": found, "complete": False, "queue": queue}
cursors.add(page["endCursor"])
after = page["endCursor"]
13 changes: 7 additions & 6 deletions adapters/facts.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@
may be of the commit between (the known limit; pinning them is still to be built). A part that cannot be read
refuses the whole; a list that was not read whole says so in its `complete` flag, and the Kernel defers on it.

Two parts are not read yet, and say so: a thread's state and its Finding's category wait on `adapters/threads.py`, so
`threads` is whole only when the pull request holds none; and the acceptance contract waits on
`adapters/acceptance.py`, so `acceptance` is null and never read whole. The run records are the records port's, read
One part is not read yet, and says so: the acceptance contract waits on `adapters/acceptance.py`, so `acceptance` is
null and never read whole. A Lens's thread has no category or severity until `harness/` uploads the Finding records they
are joined from (`adapters/threads.py`). The run records are the records port's, read
once a pass: the caller says whether that read was whole.

`read_at` is taken after the last read, never given by the caller. `last_push_at` is the push's own time where the head
Expand All @@ -25,7 +25,7 @@
import json
import pathlib

from adapters import checks, pull, timeline
from adapters import checks, pull, threads, timeline
from adapters.github import Unanswered
from tools.jsonschema_lite import validate

Expand All @@ -52,6 +52,7 @@ def snapshot(transport, repo: str, number: int, identities: dict, accounts: time
writer = timeline.since_writer(events, accounts)
labels = timeline.label_events(events, accounts)
read = checks.read(transport, first)
found, threads_whole = threads.read(transport, first, accounts)
if pusher is not None and pushed_at is None:
raise Unanswered("the head's push names its pusher but no time that can be read")
if not pull.unchanged(transport, first):
Expand All @@ -69,12 +70,12 @@ def snapshot(transport, repo: str, number: int, identities: dict, accounts: time
"last_push_at": pushed_at or now,
"last_writer_action_at": writer["last_writer_action_at"],
"reviews": reviews,
"threads": [],
"threads": found,
"checks": read["checks"],
"queue": read["queue"],
"acts_since_writer": writer["acts_since_writer"],
"acceptance": None,
"complete": {"acceptance": False, "reviews": reviews_whole, "threads": read["threads"] == 0,
"complete": {"acceptance": False, "reviews": reviews_whole, "threads": threads_whole,
"checks": read["complete"], "diff": content["complete"],
"changed_paths": paths["complete"], "runs": runs_whole is True, "timeline": timeline_whole},
"read_at": now,
Expand Down
117 changes: 117 additions & 0 deletions adapters/threads.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
"""A pull request's review threads, as `facts/1` holds them: each thread's id, whether it is resolved and by whom, and
who opened it and when, with its Finding's category and severity where the facts can give them (design section 3.3).

One GraphQL read of the threads, page by page. Who opened a thread is its first comment's author, and when, that
comment's time: a first comment that replies to another is not the opener's, and the thread is refused. Who resolved
it is GitHub's `resolvedBy`, which is typed a User: a resolved thread GitHub names no resolver for, as it is taken to
when an App resolved it or the account is gone, has `resolved_by` null, and the Kernel defers on that thread alone
(`unreadable_thread`). No trial has recorded either yet. Each actor is told by its account id and type,
never by a name's spelling (decision 0005, L-57), and its write access read once a login, as `adapters/timeline.py`
does. No comment's text is read. A thread whose opener GitHub no longer names, a deleted account's, is refused with the
snapshot, as an unreadable actor is anywhere: the known cost is that such a pull request is never read whole. A thread
deleted and another made between two pages leaves the count the same and one unread, as the rollup can.

A thread a person opened is `human`, with no severity (section 3.3). Any other thread, a Lens's among them, has neither:
a required Lens's category and severity come from its own Finding record, in its Run's `applied/1`, joined by
`surface.key` (decision 0038), and no Run uploads one until `harness/` builds `apply`. A thread is a Lens's only when
its author is that Lens's own App, by account id and type, as the caller names it: an outside reviewer's, CodeRabbit's
or Codex's, is no required Lens's, and gates nothing. The Kernel reads a required model Lens's own App's open thread
with neither as unreadable, and defers on it alone (`kernel/derive.py`'s `unreadable_thread`).

The list is whole only when its last page says there is no next one, every thread it counts was read, and none twice;
a cursor that repeats, or a next page past the count, ends the read short, as `adapters/checks.py` does for the rollup.
"""
from __future__ import annotations

import re

from adapters import timeline
from adapters.github import Unanswered, request

PAGE = 100
TIME = re.compile(r"[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]Z")
QUERY = """query FactsThreads($owner: String!, $name: String!, $number: Int!, $after: String) {
repository(owner: $owner, name: $name) {
pullRequest(number: $number) {
reviewThreads(first: %d, after: $after) {
totalCount
pageInfo { hasNextPage endCursor }
nodes {
id isResolved
resolvedBy { login databaseId }
comments(first: 1) {
nodes {
createdAt
replyTo { id }
author { __typename login ... on User { databaseId } ... on Bot { databaseId } }
}
}
}
}
}
}
}""" % PAGE


def _account(author, kind=None):
"""A GraphQL actor as the REST user object `timeline.Accounts` reads: its login, its id and its type."""
if not isinstance(author, dict):
raise Unanswered("a thread's actor cannot be read")
kind = kind or author.get("__typename")
return {"login": author.get("login"), "id": author.get("databaseId"), "type": kind}


def thread(node: dict, accounts: timeline.Accounts) -> dict:
"""One thread as `facts/1` holds it; refused when any part GitHub gives cannot be read."""
ident, resolved = node.get("id"), node.get("isResolved")
comments = node.get("comments") if isinstance(node.get("comments"), dict) else {}
first = comments.get("nodes") if isinstance(comments.get("nodes"), list) else None
if not isinstance(ident, str) or not ident or type(resolved) is not bool or not first \
or not isinstance(first[0], dict):
raise Unanswered("a review thread's id, state or first comment cannot be read")
if first[0].get("replyTo") is not None:
raise Unanswered("a review thread's first comment replies to another: its opener cannot be read")
opened_at = first[0].get("createdAt")
if not (isinstance(opened_at, str) and TIME.fullmatch(opened_at)):
raise Unanswered("a review thread's time cannot be read")
opened_by = accounts.actor(_account(first[0].get("author")))
by = node.get("resolvedBy")
if not resolved and by is not None:
raise Unanswered("an open review thread that names who resolved it")
resolved_by = accounts.actor(_account(by, "User")) if by is not None else None
human = opened_by["kind"] == "human"
return {"id": ident, "resolved": resolved, "opened_by": opened_by, "category": "human" if human else None,
"severity": None, "resolved_by": resolved_by, "opened_at": opened_at}


def read(transport, pull: dict, accounts: timeline.Accounts) -> tuple:
"""Every review thread of the pull request, and whether they were read whole."""
owner, name = pull["base"]["repo"]["full_name"].split("/")
found, after, total, ids, cursors = [], None, None, [], set()
while True:
variables = {"owner": owner, "name": name, "number": pull["number"], "after": after}
answer = transport.send(request("POST", "/graphql", body={"query": QUERY, "variables": variables}))
if answer["status"] != 200 or not isinstance(answer["body"], dict) or answer["body"].get("errors"):
raise Unanswered("the threads' read answered %d" % answer["status"])
pr = (((answer["body"].get("data") or {}).get("repository") or {}).get("pullRequest")) or {}
listed = pr.get("reviewThreads")
page = listed.get("pageInfo") if isinstance(listed, dict) else None
if not isinstance(listed, dict) or not isinstance(listed.get("nodes"), list) or not isinstance(page, dict):
return found, False
counted = listed.get("totalCount")
total = counted if total is None else total
if not isinstance(total, int) or isinstance(total, bool) or counted != total:
return found, False
for node in listed["nodes"]:
if not isinstance(node, dict):
raise Unanswered("a review thread is not one GitHub gives")
found.append(thread(node, accounts))
ids.append(found[-1]["id"])
if page.get("hasNextPage") is False:
return found, len(ids) == total and len(set(ids)) == len(ids)
cursor = page.get("endCursor")
if page.get("hasNextPage") is not True or not isinstance(cursor, str) or not cursor or cursor in cursors \
or len(ids) >= total:
return found, False
cursors.add(cursor)
after = cursor
Loading
Loading