@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/pulls.js

@@ -0,0 +1,462 @@
+import { authorAssociation, applyTriageFields, GITHUB_WORLD_USER, githubNotFound, hasBareRepo, implicitReviewId, listGitPlaneRefs, mergePullRequest, nextRepoNumber, mergeIntoBranchInPlane, normalizeLogins, paginate, planeAncestors, syncPrHeadsToBranchTip, planeCommitBody, prPlaneDiffFiles, readGitCommitFromPlane, resolvePlaneRef, reviewStateForEvent, serializeReviewComment, toAssignees, toGithubIssue, toGithubPullFile, toGithubRest, toGithubReview, } from "../github-twin.js";
+import { announce, asView, gh, nextSeq, put, send, writer } from "./shared.js";
+import { assignable } from "./repos.js";
+import { closingIssueNumbers } from "./push-reactions.js";
+const numberOf = (g) => Number(decodeURIComponent(g.seg[4]));
+/** `owner`'s repository in `repo`'s network (the forks of one root, docs.github.com/pull-requests/collaborating-with-
+ *  pull-requests/working-with-forks/about-forks), or nothing. */
+function forkInNetwork(st, repo, owner) {
+    const rootOf = (name) => {
+        let at = name;
+        for (let hops = 0; hops < 50; hops++) {
+            const parent = st.repos.find((r) => r.full_name === at)?.parent_full_name;
+            if (!parent)
+                break;
+            at = parent;
+        }
+        return at;
+    };
+    const network = rootOf(repo);
+    return st.repos.find((r) => r.owner.toLowerCase() === owner.toLowerCase() && r.full_name !== repo && rootOf(r.full_name) === network)?.full_name;
+}
+/** The pull request a path names, as a pull request (never an issue's counter shell). */
+const pullOf = (g) => {
+    const n = numberOf(g);
+    return g.state().prs.find((p) => p.repository === g.repo && p.number === n && p.is_pull_request);
+};
+/** A door INTO a pull request 404s when nobody opened it: an empty list would say it is real and quiet. */
+const intoPull = (serve) => async (ctx) => {
+    const g = gh(ctx);
+    const pr = pullOf(g);
+    return pr ? serve(ctx, g, pr, pr.number) : send(ctx, githubNotFound());
+};
+/** A pull request as GitHub answers it whole: its fields, the counts GitHub computes (commits, changed files,
+ *  additions, deletions, issue comments and review comments) each from what the list endpoints answer unless
+ *  the stored pull request carries it (an observed one's pulled counts), and its mergeability. */
+async function fullPull(g, pr) {
+    const st = g.state();
+    const files = await filesOf(g, pr);
+    const commits = (await planeCommitsOf(g, pr))?.length ?? pr.commits ?? 0;
+    const on = (kind) => st.comments.filter((c) => c.repository === pr.repository && c.number === pr.number && c.kind === kind).length;
+    return {
+        ...toGithubRest(pr, st.milestones),
+        commits: pr.commits ?? commits,
+        changed_files: pr.changed_files ?? files.length,
+        additions: pr.additions ?? files.reduce((n, f) => n + (Number(f.additions) || 0), 0),
+        deletions: pr.deletions ?? files.reduce((n, f) => n + (Number(f.deletions) || 0), 0),
+        comments: on('issue'),
+        review_comments: on('review'),
+        ...(await mergeability(g, pr)),
+    };
+}
+/** Write a pull request's fields and answer it as GitHub renders it (whole, or as the operation's view), announcing `action`. */
+async function writePull(ctx, g, number, operation, fields, action, status = 200, view) {
+    const id = `${g.repo}#${number}`;
+    await put(ctx, { operation, subjectType: 'pull_request', subjectId: id, fields: { number, repository: g.repo, ...fields } });
+    const st = g.state();
+    const found = st.prs.find((p) => p.id === id);
+    const out = found ? toGithubRest(found, st.milestones) : { number };
+    await announce(ctx, [{ event: 'pull_request', action, repository: g.repo, number, pr: out }]);
+    return ctx.reply(view ? asView(view, out) : found ? await fullPull(g, found) : out, status);
+}
+export function pullsSemantics() {
+    return {
+        // GitHub's filters: state (open|closed|all, default open), head (owner:branch or branch), base.
+        // The default order is newest first; a pull request's number is its creation order.
+        'pulls/list': async (ctx) => {
+            const { repo, query, state } = gh(ctx);
+            const st = state();
+            const lp = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+            const stateF = (lp.get('state') ?? 'open').toLowerCase();
+            const headF = lp.get('head') ?? undefined;
+            const baseF = lp.get('base') ?? undefined;
+            const headBranch = headF !== undefined ? (headF.includes(':') ? headF.slice(headF.indexOf(':') + 1) : headF) : undefined;
+            // `head` is user:ref-name; the user is whoever holds the head branch (the fork's owner for a pull request from a fork)
+            const headUser = headF?.includes(':') ? headF.slice(0, headF.indexOf(':')).toLowerCase() : undefined;
+            const filtered = st.prs.filter((p) => p.repository === repo && p.is_pull_request).filter((p) => {
+                const prState = p.merged ? 'closed' : (p.state ?? 'open');
+                if (stateF !== 'all' && prState !== stateF)
+                    return false;
+                if (headBranch !== undefined && p.head_ref !== headBranch && p.head_sha !== headBranch)
+                    return false;
+                if (headUser !== undefined && (p.head_repo ?? p.repository).split('/')[0].toLowerCase() !== headUser)
+                    return false;
+                if (baseF !== undefined && p.base_ref !== baseF)
+                    return false;
+                return true;
+            });
+            const dirP = (lp.get('direction') ?? 'desc').toLowerCase() === 'asc' ? 1 : -1;
+            return ctx.reply(paginate([...filtered].sort((a, b) => (a.number - b.number) * dirP), query).map((p) => asView('pull-request-simple', toGithubRest(p, st.milestones))));
+        },
+        // GitHub's pull request carries its counts (commits, changed_files, additions, deletions, comments,
+        // review_comments; all required by the schema): each from what the list endpoints answer, unless the
+        // stored pull request already carries it (an observed one's pulled counts)
+        'pulls/get': async (ctx) => {
+            const g = gh(ctx);
+            const pr = pullOf(g);
+            if (!pr)
+                return send(ctx, githubNotFound());
+            return send(ctx, { status: 200, body: await fullPull(g, pr) });
+        },
+        // 204 when merged, else 404
+        'pulls/check-if-merged': async (ctx) => send(ctx, pullOf(gh(ctx))?.merged ? { status: 204, body: undefined } : githubNotFound()),
+        // one review comment, addressed without its pull request
+        'pulls/get-review-comment': async (ctx) => {
+            const { repo, seg, state } = gh(ctx);
+            const cid = Number(decodeURIComponent(seg[5]));
+            const c = state().comments.find((x) => x.repository === repo && x.kind === 'review' && x.id === cid);
+            return send(ctx, c ? { status: 200, body: serializeReviewComment(c) } : githubNotFound());
+        },
+        // The IMPLICIT REVIEW rides the list, as on GitHub: a review comment posted on its own is wrapped
+        // in a review, synthesized from the comments naming it (submitted at the earliest, authored by the
+        // first, COMMENTED), never stored; the projection counts it into the review count the same way.
+        'pulls/list-reviews': intoPull(async (ctx, g, _pr, n) => {
+            const st = g.state();
+            const items = st.reviews.filter((r) => r.repository === g.repo && r.number === n);
+            const wrapperId = implicitReviewId(g.repo, n);
+            const wrapped = st.comments.filter((c) => c.repository === g.repo && c.number === n && c.kind === 'review' && c.review_id === wrapperId);
+            if (wrapped.length > 0) {
+                const dated = wrapped.map((c) => c.created_at).filter((d) => d !== undefined).sort();
+                const author = wrapped.find((c) => c.user_login !== undefined);
+                items.push({
+                    id: wrapperId, repository: g.repo, number: n, state: 'COMMENTED', body: '',
+                    ...(dated[0] !== undefined ? { submitted_at: dated[0] } : {}),
+                    ...(author?.user_login !== undefined ? { user_login: author.user_login } : {}),
+                    ...(author?.user_type !== undefined ? { user_type: author.user_type } : {}),
+                });
+            }
+            return ctx.reply(paginate(items, g.query).map(toGithubReview));
+        }),
+        // one review, on the (repo, number, id) the dismiss and edit writes use
+        'pulls/get-review': intoPull(async (ctx, g, _pr, n) => {
+            const rid = Number(decodeURIComponent(g.seg[6]));
+            const r = g.state().reviews.find((x) => x.repository === g.repo && x.number === n && x.id === rid);
+            return send(ctx, r ? { status: 200, body: toGithubReview(r) } : githubNotFound());
+        }),
+        // the diff-thread comments (with their diff anchors when a local write set them)
+        'pulls/list-review-comments': intoPull(async (ctx, g, _pr, n) => ctx.reply(paginate(g.state().comments.filter((c) => c.repository === g.repo && c.number === n && c.kind === 'review'), g.query).map(serializeReviewComment))),
+        // The plane's real diff when the base and head both exist there (an observed pull request with a
+        // pulled count but no per-file evidence keeps none, so the list never contradicts its own count).
+        'pulls/list-files': intoPull(async (ctx, g, pr) => ctx.reply(paginate(await filesOf(g, pr), g.query).map((f) => toGithubPullFile(g.repo, pr.head_sha ?? '', f)))),
+        // In a repository with history, the plane's commits: those the head reaches that the base did not
+        // hold (a merged one's base is its merge commit's first parent), oldest first; none without history.
+        'pulls/list-commits': intoPull(async (ctx, g, pr) => {
+            const plane = await planeCommitsOf(g, pr);
+            if (plane) {
+                const bodies = [];
+                for (const sha of paginate(plane, g.query)) {
+                    const b = await planeCommitBody(g.repo, sha, g.root);
+                    if (b)
+                        bodies.push(b);
+                }
+                return ctx.reply(bodies);
+            }
+            return ctx.reply([]);
+        }),
+        // {users, teams}: teams are not modeled
+        'pulls/list-requested-reviewers': intoPull(async (ctx, _g, pr) => ctx.reply({ users: toAssignees(pr.requested_reviewers), teams: [] })),
+        // 422 without title, head and base. `head` may be owner:branch, a branch, a ref or a sha: the branch
+        // is the head ref; its tip (a registered ref or branch) is head_sha. In a repository whose history
+        // is in the plane, a head branch that does not exist there is GitHub's 422. An `owner:branch` head whose owner
+        // is not this repository's names that owner's fork in the same network, and the branch is read there
+        // (docs.github.com/rest/pulls/pulls#create-a-pull-request: "For cross-repository pull requests in the same
+        // network, namespace head with a user like this: username:branch"); an owner with no fork in the network is 422.
+        'pulls/create': async (ctx) => {
+            const { repo, body, occurredAt, caller, root, state } = gh(ctx);
+            const missing = ['title', 'head', 'base'].filter((k) => !body[k]);
+            if (missing.length)
+                return ctx.reply({ message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'PullRequest', field, code: 'missing_field' })) }, 422);
+            const number = nextRepoNumber(state(), repo);
+            const id = `${repo}#${number}`;
+            const headRaw = String(body.head);
+            const headRef = headRaw.includes(':') ? headRaw.slice(headRaw.indexOf(':') + 1) : headRaw;
+            const branchName = headRef.replace(/^refs\/heads\//, '');
+            const invalidHead = () => ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequest', field: 'head', code: 'invalid' }], documentation_url: 'https://docs.github.com/rest/pulls/pulls#create-a-pull-request' }, 422);
+            const headOwner = headRaw.includes(':') ? headRaw.slice(0, headRaw.indexOf(':')) : undefined;
+            let headRepo = repo;
+            if (headOwner !== undefined && headOwner.toLowerCase() !== repo.split('/')[0].toLowerCase()) {
+                const fork = forkInNetwork(state(), repo, headOwner);
+                if (!fork)
+                    return invalidHead();
+                headRepo = fork;
+            }
+            let resolvedHeadSha = headRaw;
+            if (!/^[0-9a-f]{40}$/i.test(headRaw)) {
+                const st0 = state();
+                const tip = st0.gitRefs.find((x) => x.repository === headRepo && x.ref === `refs/heads/${branchName}`)?.object_sha
+                    ?? st0.branches.find((b) => b.repository === headRepo && b.name === branchName)?.commit_sha;
+                if (tip)
+                    resolvedHeadSha = tip;
+                else if (headRepo !== repo || (hasBareRepo(repo, root) && !(await listGitPlaneRefs(repo, root)).some((r) => r.ref === `refs/heads/${branchName}`)))
+                    return invalidHead();
+            }
+            const fields = { number, repository: repo, ...(headRepo !== repo ? { head_repo: headRepo } : {}), title: body.title, body: body.body, base_ref: body.base, head_sha: resolvedHeadSha, head_ref: branchName, state: 'open', user_login: caller ?? 'octocat', user_type: 'User', created_at: occurredAt, author_association: authorAssociation(state(), repo, caller ?? 'octocat'), maintainer_can_modify: body.maintainer_can_modify === true };
+            if (body.draft !== undefined)
+                fields.draft = body.draft === true;
+            await put(ctx, { operation: 'pull_request.create', subjectType: 'pull_request', subjectId: id, fields });
+            // read back through the projection, so the derived counts agree with the carried lists
+            const st = state();
+            const created = st.prs.find((p) => p.id === id) ?? { id, number, repository: repo, review_count: 0, comment_count: 0, title: body.title, body: body.body, base_ref: body.base, head_sha: resolvedHeadSha, head_ref: branchName, state: 'open' };
+            const out = toGithubRest(created, st.milestones);
+            await announce(ctx, [{ event: 'pull_request', action: 'opened', repository: repo, number, pr: out }]);
+            const stored = st.prs.find((p) => p.id === id);
+            return ctx.reply(stored ? await fullPull(gh(ctx), stored) : out, 201);
+        },
+        // REST has no draft parameter on an edit (draft transitions are GraphQL mutations)
+        'pulls/update': intoPull(async (ctx, g, pr, number) => {
+            const { body } = g;
+            const fields = {};
+            if (body.title !== undefined)
+                fields.title = body.title;
+            if (body.body !== undefined)
+                fields.body = body.body;
+            if (body.base !== undefined)
+                fields.base_ref = body.base;
+            if (body.state !== undefined)
+                fields.state = body.state;
+            applyTriageFields(fields, body);
+            const reopening = body.state === 'open' && (pr.state ?? 'open') === 'closed';
+            return writePull(ctx, g, number, 'pull_request.update', fields, body.state === 'closed' ? 'closed' : reopening ? 'reopened' : 'edited');
+        }),
+        // A review binds to the pull request's head at submission (its commit_id; a caller may pin one),
+        // which is the exact-head semantic merge gates rely on. Inline `comments` become review comments
+        // wrapped by THIS review.
+        'pulls/create-review': intoPull(async (ctx, g, pr, number) => {
+            const { repo, body, occurredAt, caller } = g;
+            const seq = nextSeq(ctx, 'review');
+            const commitId = body.commit_id !== undefined ? String(body.commit_id) : pr.head_sha;
+            const fields = { repository: repo, number, state: reviewStateForEvent(body.event), body: body.body, submitted_at: occurredAt, user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(g.state(), repo, caller ?? GITHUB_WORLD_USER) };
+            if (commitId !== undefined)
+                fields.commit_id = commitId;
+            await put(ctx, { operation: 'pull_request_review.submit', subjectType: 'pull_request_review', subjectId: `review:${seq}`, fields });
+            if (Array.isArray(body.comments)) {
+                for (const raw of body.comments) {
+                    const cSeq = nextSeq(ctx, 'comment');
+                    const cFields = { repository: repo, number, body: raw.body, created_at: occurredAt, updated_at: occurredAt, review_id: seq, user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(g.state(), repo, caller ?? GITHUB_WORLD_USER), ...(commitId !== undefined ? { commit_id: commitId } : {}) };
+                    if (raw.path !== undefined)
+                        cFields.path = String(raw.path);
+                    if (raw.line !== undefined)
+                        cFields.line = Number(raw.line);
+                    if (raw.side !== undefined)
+                        cFields.side = String(raw.side);
+                    if (raw.start_line !== undefined)
+                        cFields.start_line = Number(raw.start_line);
+                    await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${cSeq}`, fields: cFields });
+                }
+            }
+            const review = toGithubReview(g.state().reviews.find((r) => r.repository === repo && r.number === number && r.id === seq));
+            await announce(ctx, [{ event: 'pull_request_review', action: 'submitted', repository: repo, number, review }]);
+            return ctx.reply(review);
+        }),
+        // dismiss (a message is required) or edit a submitted review's body: an overlay on the review
+        'pulls/dismiss-review': async (ctx) => reviewOverlay(ctx, 'dismiss'),
+        'pulls/update-review': async (ctx) => reviewOverlay(ctx, 'update'),
+        // A reply IN a review thread: it inherits the root comment's diff anchor and threads by
+        // in_reply_to; it rides the pull request's implicit review (a reply is not the reviewer's verdict).
+        'pulls/create-reply-for-review-comment': async (ctx) => {
+            const g = gh(ctx);
+            const { repo, seg, body, occurredAt, caller, state } = g;
+            const number = numberOf(g);
+            const rootId = Number(decodeURIComponent(seg[6]));
+            const parent = state().comments.find((c) => c.repository === repo && c.number === number && c.kind === 'review' && c.id === rootId);
+            if (!parent)
+                return send(ctx, githubNotFound());
+            // an empty body is refused as a missing one is
+            if (body.body === undefined || String(body.body) === '')
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReviewComment', field: 'body', code: 'missing_field' }] }, 422);
+            const seq = nextSeq(ctx, 'comment');
+            const anchor = {};
+            if (parent.commit_id !== undefined)
+                anchor.commit_id = parent.commit_id;
+            if (parent.path !== undefined)
+                anchor.path = parent.path;
+            if (parent.line !== undefined)
+                anchor.line = parent.line;
+            if (parent.side !== undefined)
+                anchor.side = parent.side;
+            if (parent.diff_hunk !== undefined)
+                anchor.diff_hunk = parent.diff_hunk;
+            const fields = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, in_reply_to: rootId, review_id: implicitReviewId(repo, number), user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(state(), repo, caller ?? GITHUB_WORLD_USER), ...anchor };
+            await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields });
+            const comment = serializeReviewComment(state().comments.find((c) => c.repository === repo && c.kind === 'review' && c.id === seq));
+            await announce(ctx, [{ event: 'pull_request_review_comment', action: 'created', repository: repo, number, comment }]);
+            return ctx.reply(comment, 201);
+        },
+        // A review (diff-thread) comment, wrapped in the pull request's implicit review, bound to the head
+        // (or its parent's commit when it replies), with the diff anchor a local write gives it.
+        'pulls/create-review-comment': intoPull(async (ctx, g, _pr, number) => {
+            const { repo, body, occurredAt, caller, state } = g;
+            const seq = nextSeq(ctx, 'comment');
+            const fields = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, review_id: implicitReviewId(repo, number), user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(state(), repo, caller ?? GITHUB_WORLD_USER) };
+            const parent = body.in_reply_to === undefined ? undefined : state().comments.find((c) => c.repository === repo && c.number === number && c.kind === 'review' && c.id === Number(body.in_reply_to));
+            const commitId = parent ? parent.commit_id : body.commit_id ?? state().prs.find((p) => p.repository === repo && p.number === number)?.head_sha;
+            if (commitId !== undefined)
+                fields.commit_id = String(commitId);
+            if (body.path !== undefined)
+                fields.path = String(body.path);
+            if (body.line !== undefined)
+                fields.line = Number(body.line);
+            if (body.side !== undefined)
+                fields.side = String(body.side);
+            if (body.start_line !== undefined)
+                fields.start_line = Number(body.start_line);
+            if (body.diff_hunk !== undefined)
+                fields.diff_hunk = String(body.diff_hunk);
+            if (body.in_reply_to !== undefined)
+                fields.in_reply_to = Number(body.in_reply_to);
+            await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields });
+            const comment = serializeReviewComment(state().comments.find((c) => c.repository === repo && c.kind === 'review' && c.id === seq));
+            await announce(ctx, [{ event: 'pull_request_review_comment', action: 'created', repository: repo, number, comment }]);
+            return ctx.reply(comment, 201);
+        }),
+        // Merge through the gates: 405 when merged or closed or a draft; 409 when `sha` names a head the
+        // branch has moved from (the caller's optimistic precondition); then the required checks and the
+        // rulesets, and a real merge commit on the plane.
+        'pulls/merge': intoPull(async (ctx, g, pr, number) => {
+            const { repo, body, occurredAt, caller, root, state } = g;
+            const refused = ctx.legal('pull-request', 'merged', 'pulls/merge', pr.merged)
+                ?? ctx.legal('pull-request', 'state', 'pulls/merge', pr.state ?? 'open')
+                ?? ctx.legal('pull-request', 'draft', 'pulls/merge', pr.draft);
+            if (refused)
+                return ctx.refuse(refused);
+            if (body.sha !== undefined && String(body.sha) !== pr.head_sha)
+                return ctx.reply({ message: 'Head branch was modified. Review and try the merge again.' }, 409);
+            const method = body.merge_method ? String(body.merge_method) : 'merge';
+            if (!['merge', 'squash', 'rebase'].includes(method))
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequest', field: 'merge_method', code: 'invalid' }] }, 422);
+            const base = pr.base_ref ?? 'main';
+            const before = hasBareRepo(repo, root) ? await resolvePlaneRef(repo, base, base, root) : null;
+            // what the pull request says it closes, read before the merge moves its base: its body and its commits' messages
+            const messages = [];
+            for (const sha of (await planeCommitsOf(g, pr)) ?? [])
+                messages.push(String((await planeCommitBody(repo, sha, root))?.commit?.message ?? ''));
+            const closes = closingIssueNumbers([pr.body ?? '', ...messages]);
+            const landed = await mergePullRequest(repo, pr, method, occurredAt, root, caller, writer(ctx));
+            if (!landed.ok)
+                return ctx.reply({ message: landed.message }, landed.status);
+            const st = state();
+            const merged = st.prs.find((p) => p.id === `${repo}#${number}`);
+            await announce(ctx, [{ event: 'pull_request', action: 'closed', repository: repo, number, pr: toGithubRest(merged, st.milestones) }]);
+            // The merge moved the base branch: a push to it, which GitHub's processes read as any push (workflows on push,
+            // Dependabot's manifests, the branch's files) (docs.github.com/webhooks/webhook-events-and-payloads#push: "a
+            // commit or tag is pushed", as a merge's commit is to the base branch).
+            if (before && before !== landed.sha)
+                await announce(ctx, [{ event: 'push', action: '', repository: repo, number: 0, ref: `refs/heads/${base}`, before, after: landed.sha }]);
+            // A pull request merged into the default branch closes the issues it links with a closing keyword
+            // (docs.github.com/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
+            if (base === (st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main')) {
+                for (const n of closes) {
+                    const issue = state().issues.find((i) => i.repository === repo && i.number === n);
+                    // the close is the issue's move by the merge (manifest.ts)
+                    if (!issue || (issue.state ?? 'open') !== 'open' || ctx.legal('issue', 'state', 'pulls/merge', issue.state ?? 'open', 'closed', issue.id))
+                        continue;
+                    await put(ctx, { operation: 'issue.update', subjectType: 'issue', subjectId: issue.id, fields: { number: n, repository: repo, state: 'closed', state_reason: 'completed', updated_at: occurredAt } });
+                    const now = state();
+                    const closed = now.issues.find((i) => i.id === issue.id);
+                    await announce(ctx, [{ event: 'issues', action: 'closed', repository: repo, number: n, ...(closed ? { issue: toGithubIssue(closed, now.milestones, undefined, now.comments) } : {}) }]);
+                }
+            }
+            return ctx.reply({ sha: landed.sha, merged: true, message: 'Pull Request successfully merged' });
+        }),
+        // a review is requested from someone with access to the repository, never from the pull request's author; a
+        // repository the twin knows only through its pull requests (an observed or seeded World) has no access list to check
+        'pulls/request-reviewers': intoPull(async (ctx, g, pr, number) => {
+            const asked = normalizeLogins(g.body.reviewers);
+            const docs = 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request';
+            if (pr.user_login && asked.includes(pr.user_login))
+                return ctx.reply({ message: 'Review cannot be requested from pull request author.', documentation_url: docs }, 422);
+            const st = g.state();
+            const access = new Set(assignable(st, g.repo));
+            if (st.repos.some((r) => r.full_name === g.repo) && asked.some((login) => !access.has(login)))
+                return ctx.reply({ message: `Reviews may only be requested from collaborators. One or more of the users or teams you specified is not a collaborator of the ${g.repo} repository.`, documentation_url: docs }, 422);
+            const merged = [...(pr.requested_reviewers ?? [])];
+            for (const login of asked)
+                if (!merged.includes(login))
+                    merged.push(login);
+            return writePull(ctx, g, number, 'pull_request.request_reviewers', { requested_reviewers: merged }, 'review_requested', 201, 'pull-request-simple');
+        }),
+        'pulls/remove-requested-reviewers': intoPull(async (ctx, g, pr, number) => {
+            const remove = new Set(normalizeLogins(g.body.reviewers));
+            return writePull(ctx, g, number, 'pull_request.remove_requested_reviewers', { requested_reviewers: (pr.requested_reviewers ?? []).filter((login) => !remove.has(login)) }, 'review_request_removed', 200, 'pull-request-simple');
+        }),
+        // brings the base's latest commits into the head branch with a merge commit, as GitHub's Update branch does (202);
+        // a head already up to date stays as it is, and one that conflicts is refused
+        // (the head branch is written where it lives: the fork, for a pull request from one)
+        'pulls/update-branch': intoPull(async (ctx, g, pr, number) => {
+            const headRef = pr.head_ref ?? '';
+            const headRepo = pr.head_repo ?? g.repo;
+            const baseTip = await resolvePlaneRef(g.repo, pr.base_ref ?? 'main', pr.base_ref ?? 'main', g.root);
+            if (baseTip && headRef) {
+                const merged = await mergeIntoBranchInPlane(headRepo, headRef, baseTip, `Merge branch '${pr.base_ref ?? 'main'}' into ${headRef}`, 'merge', g.occurredAt, g.root);
+                if (merged && 'conflict' in merged)
+                    return ctx.reply({ message: 'merge conflict between base and head', documentation_url: 'https://docs.github.com/rest/pulls/pulls#update-a-pull-request-branch' }, 422);
+                if (merged && merged.sha !== pr.head_sha) {
+                    await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${headRepo}#refs/heads/${headRef}`, fields: { repository: headRepo, ref: `refs/heads/${headRef}`, object_sha: merged.sha, object_type: 'commit' } });
+                    await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${headRepo}#${headRef}`, fields: { repository: headRepo, name: headRef, commit_sha: merged.sha } });
+                    await syncPrHeadsToBranchTip(headRepo, headRef, merged.sha, g.root, g.occurredAt);
+                }
+            }
+            return ctx.reply({ message: 'Updating pull request branch.', url: `https://api.github.com/repos/${g.repo}/pulls/${number}` }, 202);
+        }),
+    };
+}
+/** Dismiss a review (PUT .../reviews/:rid/dismissals, a message required) or edit its body
+ *  (PUT .../reviews/:rid), as an overlay on the submitted review. */
+async function reviewOverlay(ctx, how) {
+    const g = gh(ctx);
+    const { repo, seg, body, state } = g;
+    const number = numberOf(g);
+    const rid = Number(decodeURIComponent(seg[6]));
+    const submitted = state().reviews.find((r) => r.repository === repo && r.number === number && r.id === rid);
+    if (!submitted)
+        return send(ctx, githubNotFound());
+    if (how === 'dismiss') {
+        if (!body.message)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReview', field: 'message', code: 'missing_field' }] }, 422);
+        // the dismissal is the review's move (manifest.ts), kept as an overlay on the submitted review
+        const refused = ctx.legal('pull-request-review', 'state', 'pulls/dismiss-review', submitted.state, 'DISMISSED', String(rid));
+        if (refused)
+            return ctx.reply({ message: refused.message }, refused.status);
+        await put(ctx, { operation: 'pull_request_review_overlay.dismiss', subjectType: 'pull_request_review_overlay', subjectId: `reviewoverlay:${rid}`, fields: { review_id: rid, state: 'DISMISSED', dismissed_message: String(body.message) } });
+    }
+    else {
+        if (body.body === undefined)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReview', field: 'body', code: 'missing_field' }] }, 422);
+        await put(ctx, { operation: 'pull_request_review_overlay.update', subjectType: 'pull_request_review_overlay', subjectId: `reviewoverlay:${rid}`, fields: { review_id: rid, body: String(body.body) } });
+    }
+    const review = toGithubReview(state().reviews.find((x) => x.id === rid));
+    await announce(ctx, [{ event: 'pull_request_review', action: how === 'dismiss' ? 'dismissed' : 'edited', repository: repo, number, review }]);
+    return ctx.reply(review);
+}
+/** A pull request's changed files: the plane's real diff when its base and head both exist there; never fabricated. */
+async function filesOf(g, pr) {
+    return (await prPlaneDiffFiles(g.state(), g.repo, pr, g.root)) ?? [];
+}
+/** An open pull request's mergeability in a repository with history, as GitHub computes it when the pull request is
+ *  read (docs.github.com/rest/guides/using-the-rest-api-to-interact-with-your-git-database#checking-mergeability-of-pull-
+ *  requests): whether its head merges into its base without conflicts. Where the documentation stops and the twin
+ *  decides: a conflict-free merge reads `clean`, a conflicted one `dirty`; the computation is never pending. Nothing
+ *  when the pull request is closed or its repository has no history (what it carries stands). */
+async function mergeability(g, pr) {
+    const { repo, root } = g;
+    if (pr.merged || (pr.state ?? 'open') !== 'open' || !pr.head_sha || !hasBareRepo(repo, root))
+        return {};
+    const merged = await mergeIntoBranchInPlane(repo, pr.base_ref ?? 'main', pr.head_sha, '', 'merge', g.occurredAt, root, undefined, true);
+    if (!merged)
+        return {};
+    return 'conflict' in merged ? { mergeable: false, mergeable_state: 'dirty' } : { mergeable: true, mergeable_state: 'clean' };
+}
+/** In a repository with history, the commits a pull request's head reaches that its base did not hold (a merged
+ *  one's base is its merge commit's first parent), oldest first; undefined in a repository without history. */
+async function planeCommitsOf(g, pr) {
+    const { repo, root } = g;
+    if (!pr.head_sha || !hasBareRepo(repo, root))
+        return undefined;
+    const mergeCommit = pr.merge_commit_sha ? await readGitCommitFromPlane(repo, pr.merge_commit_sha, root) : null;
+    const base = mergeCommit?.parents[0] ?? await resolvePlaneRef(repo, pr.base_ref ?? 'main', pr.base_ref ?? 'main', root);
+    const held = base ? await planeAncestors(repo, base, root) : new Map();
+    // oldest first: by commit time, and within one second (git's resolution) a parent before its child — the walk
+    // from the head meets a commit's parents after it, so a later walk position is the older commit
+    const walked = [...(await planeAncestors(repo, pr.head_sha, root))].map(([sha, at], i) => ({ sha, at, i }));
+    return walked.filter(({ sha }) => !held.has(sha)).sort((a, b) => (a.at - b.at) || (b.i - a.i)).map(({ sha }) => sha);
+}

package/dist/src/semantics/push-reactions.d.ts

@@ -0,0 +1,101 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type GithubState, type GithubWorkflow } from '../github-twin.js';
+/** A workflow's jobs, in file order: each job's id (its key under `jobs:`) and the name GitHub shows for it, its `name:`
+ *  or else its id (docs.github.com/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idname). */
+export declare function jobsOf(source: string): Array<{
+    id: string;
+    name: string;
+}>;
+/** The permissions a workflow grants its GITHUB_TOKEN: its `permissions:` blocks (`contents: write`, or `read-all` /
+ *  `write-all`), over the default a repository created today has, read access to contents and packages
+ *  (docs.github.com/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). */
+export declare function tokenPermissions(source: string): Record<string, string>;
+/** A queued run of a workflow, with a job per job of its file at the run's commit (one named for the workflow when
+ *  the file cannot be read): what a dispatch, a push or a pull request starts. A run from a fork that needs a
+ *  maintainer's approval first is created waiting, `action_required`, with no jobs until it is approved
+ *  (approveRun). */
+export declare function queueRun(ctx: SemanticsContext, st: GithubState, repo: string, wf: GithubWorkflow, branch: string, headSha: string, event: string, actor?: string, opts?: {
+    awaitingApproval?: boolean;
+    headRepo?: string;
+}): Promise<number>;
+/** The check run an Actions job reports on its commit: named for the job, under the GitHub Actions app's check suite,
+ *  with the job's status and conclusion, and the job's id (a job's check_run_url names it)
+ *  (docs.github.com/rest/guides/using-the-rest-api-to-interact-with-checks: GitHub Actions reports each job as a check
+ *  run; docs.github.com/rest/actions/workflow-jobs). */
+export declare function actionsCheckRun(job: {
+    id: number;
+    repository: string;
+    head_sha: string;
+    name: string;
+    run_id: number;
+}, status: 'queued' | 'completed', conclusion: string | null, at: string): {
+    operation: string;
+    subjectType: string;
+    subjectId: string;
+    fields: Record<string, unknown>;
+};
+/** A run's jobs, queued: one per job of the workflow file at the run's commit. The first keeps the id a run's single
+ *  job has always had. */
+export declare function queueJobs(ctx: SemanticsContext, st: GithubState, repo: string, wf: GithubWorkflow, runId: number, runNumber: number, branch: string, headSha: string): Promise<void>;
+/** The issue numbers texts link with GitHub's closing keywords, `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`,
+ *  `resolve`, `resolves` or `resolved` before `#n` (docs.github.com/issues/tracking-your-work-with-issues/using-issues/
+ *  linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword). */
+export declare function closingIssueNumbers(texts: string[]): number[];
+/** Whether a pull request's author needs a maintainer to approve its workflow runs: by default a first-time
+ *  contributor from a fork, "users who have never had a commit or pull request merged into the repository"
+ *  (docs.github.com/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/
+ *  managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories).
+ *  Where the documentation stops and the twin decides: someone with write access to the repository (its owner, an
+ *  owner of its organization, a collaborator with write or more) is not a first-time contributor. */
+export declare function needsApproval(st: GithubState, repo: string, author: string | null | undefined): boolean;
+/** Whether `login` has write access to `repo`: its owner, an owner of its organization, or a collaborator with write
+ *  or more. */
+export declare function canWrite(st: GithubState, repo: string, login: string): boolean;
+/** A pull request opened, reopened or pushed to runs the base repository's workflows whose `on:` includes
+ *  pull_request, as its head commit has them (docs.github.com/actions/writing-workflows/choosing-when-your-workflow-
+ *  runs/events-that-trigger-workflows#pull_request: by default on opened, synchronize and reopened). A first-time
+ *  contributor's run from a fork waits for approval (needsApproval). */
+export declare function reactToPullRequest(ctx: SemanticsContext, repo: string, number: number, action: string): Promise<void>;
+/** A direct push to a branch whose rulesets require pull requests fails those rules, and the push is refused when
+ *  one is active (docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/
+ *  available-rules-for-rulesets#require-a-pull-request-before-merging). In evaluate mode the push lands and its rule
+ *  suite records what would have failed (docs.github.com/.../managing-rulesets/managing-rulesets-for-a-repository#viewing-insights-for-rulesets). */
+export declare function directPushRules(st: GithubState, repo: string, branch: string): {
+    refused: string | undefined;
+    evaluations: Array<{
+        ruleset_id: number;
+        ruleset_name: string;
+        rule_type: string;
+        enforcement: string;
+        result: string;
+        details: string | null;
+    }>;
+};
+/** GitHub's reactions to a branch of `repo` moving from `before` to `after`. */
+export declare function reactToPush(ctx: SemanticsContext, repo: string, ref: string, before: string, after: string): Promise<void>;
+/** Whether Dependabot alerts are on for a repository: off until someone with admin access turns them on
+ *  (docs.github.com/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts,
+ *  docs.github.com/rest/repos/repos#enable-vulnerability-alerts). */
+export declare function dependabotOn(ctx: SemanticsContext, repo: string): boolean;
+/** Dependabot reads package.json manifests at a commit of the default branch: an alert opens for a dependency an
+ *  advisory names at a vulnerable version, and an open one is fixed once the manifest no longer asks for one
+ *  (docs.github.com/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). */
+export declare function dependabotReads(ctx: SemanticsContext, repo: string, commit: string, manifests: string[], removed?: string[]): Promise<void>;
+/** Every package.json at a commit, for Dependabot's first read when its alerts are turned on. */
+export declare function manifestsAt(repo: string, commit: string, root?: string): Promise<string[]>;
+/** What a run's workflow steps uploaded, read from the workflow file at the run's commit: its artifacts, uploaded while
+ *  it runs, and its caches, saved when its job ends. */
+export declare function runOutputs(repo: string, run: {
+    id: number;
+    workflow_id: number;
+    head_sha: string;
+    head_branch?: string;
+}, st: GithubState, root: string | undefined, write: (w: {
+    operation: string;
+    subjectType: string;
+    subjectId: string;
+    fields: Record<string, unknown>;
+}) => Promise<void>, nextId: (prefix: string) => number, at: string, what?: {
+    artifacts: boolean;
+    caches: boolean;
+}): Promise<void>;