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
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,8 +265,8 @@ git fetch origin main
quest check --base origin/main --branch quest/m0/export
```

Fetch the base first, since a stale one can predate the quest. The
`quest-merge` skill runs this before landing a PR. A repository with
Fetch the base first, since a stale one can predate the quest. `quest merge`
runs this on the head it lands. A repository with
`quest` installed in CI can also run it on pull requests, where the checkout is
detached, so pass the head branch:

Expand All @@ -284,8 +284,8 @@ still judge whether a rewrite matches what remains.
binary carries, and reports a missing, outdated, or retired one. A job that
checks a PR with a binary built from the base passes `--no-stubs`, since that
binary's skills would reject a PR that changes a stub; the PR's own binary
checks them in its own `quest check`. This repository's merge queue and the
`quest-merge` skill's preflight do so.
checks them in its own `quest check`. This repository's merge queue and
`quest merge` do so.

A link into a submodule that is not checked out, as in a fresh worktree or
`actions/checkout` by default, resolves at the commit its gitlink pins when a
Expand Down Expand Up @@ -563,7 +563,11 @@ it creates is the queue signal, so a queued PR shows no hold. It refuses while
any session holds the PR, so release your own hold first. `--land` needs the full 40-character
head SHA and refuses once the head moves, or while the latest run of any
check on it failed, required or not, naming each; pending checks do not block.
It enables auto-merge bound to that SHA, or merges at once when nothing is
It also refuses a head that fails `quest check --no-stubs --base <base> --branch
<head branch>`, which it runs on git objects it fetches, so nothing from the
head runs, and ignores findings the base already has; run a `quest` the PR
cannot modify, since the head's own build could skip the check. A base without
quests skips it. It enables auto-merge bound to that SHA, or merges at once when nothing is
left to wait for. `--squash` or `--rebase` picks the method, and it refuses one
the repository disallows; otherwise it uses the only method the repository
allows, or else a merge commit, and refuses when merge commits are off and more
Expand Down
5 changes: 1 addition & 4 deletions assets/skills/merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,8 @@ Otherwise, the changes since the reviewed head need no new review only when they
The repository's review policy decides whose record counts and may require more, such as a maintainer's review.
Where it says nothing, only a record on a PR whose author has write access counts: anyone else writes their own PR body, so their head needs a local review that rewrites the record.

Before queueing, check the head with a `quest` the PR cannot modify: fetch the PR's base branch and its exact head, check the head out apart from your own checkout, such as in a detached worktree under `.tmp/`, and from a directory outside it run `quest --root <head-checkout> check --no-stubs --base <remote>/<base> --branch <head-branch>`.
The head's files are untrusted, and a stale local base can skip the check; `--no-stubs` is there because the PR's own checks verify its stubs.
A finding means the PR leaves its quest inaccurate: it needs `/quest-iterate`.

Queue the head with `quest merge <pr> --land <full 40-character head SHA>`, adding `--squash` or `--rebase` when the repository's root instructions name that method for the PR's base.
Run a `quest` the PR cannot modify, such as an installed release rather than a build from the head's checkout: it refuses a head that leaves its quest inaccurate, a check the head's own code could skip.
A refusal says what the head or the repository needs: follow it, sending a head that needs a fix or its base merged to `/quest-iterate`.
Ask instead when it refuses a head `/quest-iterate` left unchanged, and never pass `--direct` unless the user explicitly asks.

Expand Down
45 changes: 0 additions & 45 deletions quest/m0/token-waste/merge-check.md

This file was deleted.

46 changes: 36 additions & 10 deletions src/cli/hold.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// a time. It holds the `quest:active` label, and the ID of the timeline event
// that added the label is its hold token, since sessions often share an account.
// `quest merge` takes no label: the pinned auto-merge or merge-queue entry it creates is the queue signal.
import { ACTIVE_LABEL, handedBack, isHoldLabel, latestHold, heldToken, withoutHandBack } from "../core";
import { ACTIVE_LABEL, formatFinding, handedBack, isHoldLabel, latestHold, heldToken, withoutHandBack } from "../core";
import { cleanAutoMergeRefusal, immediateMerge, queueHead } from "../github/merge";
import { repositoryPath } from "./claims";
import {
Expand All @@ -19,6 +19,7 @@ import {
import { latestContexts } from "../github/checks";
import { ALLOWS, LAND_CHECK, METHOD_NAMES, contexts, enqueue } from "./land";
import { QUEUE_CHECK } from "./land-queue";
import type { LandingCheck } from "./landed";
import { classifyCheck } from "./status";
import { Refusal, ago } from "./start";

Expand All @@ -28,7 +29,7 @@ export type Method = "merge" | "squash" | "rebase";
const READ = `query HoldOwnership($owner: String!, $repo: String!, $number: Int!) {
repository(owner: $owner, name: $repo) {
pullRequest(number: $number) {
id url state isDraft body updatedAt baseRefName headRefOid mergeStateStatus isMergeQueueEnabled isInMergeQueue
id url state isDraft body updatedAt baseRefName baseRefOid headRefName headRefOid mergeStateStatus isMergeQueueEnabled isInMergeQueue
labels(first: 100) { nodes { name } }
timelineItems(last: 100, itemTypes: [LABELED_EVENT]) {
nodes { __typename ... on LabeledEvent { id createdAt label { name } } }
Expand All @@ -52,6 +53,10 @@ interface Snapshot {
body: string;
updatedAt: string;
base: string;
/** The commit the base branch points at. */
baseSha: string;
/** The head branch's name. */
branch: string;
head: string;
mergeState: string;
queue: boolean;
Expand Down Expand Up @@ -208,22 +213,29 @@ function signalMethod(
return method;
}

/** What `quest merge` lands, and how. */
export interface LandRequest {
/** The full head SHA to land, which must still be the PR's head. */
sha: string;
/** The method the caller asked for; otherwise {@link mergeMethod} picks one on an ungated base. */
method?: Method;
/** Merge at once on an ungated base with auto-merge disabled. */
direct?: boolean;
check: LandingCheck;
}

/**
* Land `sha`, which must still be the head of `pr`, while no session holds it:
* enable auto-merge bound to it, or merge at once when GitHub would refuse auto-merge because
* nothing is left to wait for. A base with a merge queue gets {@link pick} instead.
* A base that requires the `quest land` check queues it for `quest land` instead:
* auto-merge whose commit body pins `sha`, with a method {@link signalMethod} picks.
* That request only signals the queue: `quest land` lands with its own method. It takes no label.
* `named` is the method the caller asked for; otherwise {@link mergeMethod} picks one on an ungated base.
* It first refuses a head whose quest check finds anything, so the refusal comes before a queue
* build is spent, even on a base whose gate checks it again.
*/
export async function land(
pr: PullRequest,
sha: string,
named: Method | undefined,
deps: GitHubDependencies,
direct = false,
): Promise<void> {
export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDependencies): Promise<void> {
const { sha, method: named, direct = false } = request;
const labels = new Labels(pr, deps);
const current = (snapshot: Snapshot) => headAt(snapshot, sha);
const snapshot = await labels.read();
Expand All @@ -241,6 +253,18 @@ export async function land(
}
};
await passing(labels.github, pr, snapshot.url, sha);
const findings = await request.check({
remote: `https://github.com/${pr.owner}/${pr.repo}.git`,
base: snapshot.base,
baseSha: snapshot.baseSha,
branch: snapshot.branch,
sha,
token: deps.token,
});
if (findings.length > 0)
throw new Refusal(
`${snapshot.url} head ${sha} fails quest check against ${snapshot.base}:\n${findings.map(formatFinding).join("\n")}\nfix the PR, then land it again`,
);
const needs = await requirements(labels.github, pr, snapshot.base);
if (needs.checks.some((check) => check.name === LAND_CHECK)) {
if (named !== undefined)
Expand Down Expand Up @@ -518,6 +542,8 @@ class Labels {
body: typeof row.body === "string" ? row.body : "",
updatedAt: string(row.updatedAt),
base: string(row.baseRefName),
baseSha: string(row.baseRefOid),
branch: string(row.headRefName),
head: string(row.headRefOid),
mergeState: string(row.mergeStateStatus),
queue: row.isMergeQueueEnabled === true,
Expand Down
3 changes: 2 additions & 1 deletion src/cli/land-bump.ts
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,8 @@ async function settle(target: Repository, record: Bump, connection: BumpConnecti
direct = object(await (await github.request(path)).json()).allow_auto_merge !== true;
}
try {
await land({ ...target, number: pr }, head, undefined, connection.deps, direct);
// The bump PR is this process's own commit of version files, so it has no quest to check.
await land({ ...target, number: pr }, { sha: head, direct, check: async () => [] }, connection.deps);
} catch (error) {
if (!(error instanceof Refusal)) throw error;
return fail(`landing it was refused: ${error.message}`);
Expand Down
147 changes: 133 additions & 14 deletions src/cli/landed.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,39 @@
// lives here rather than in the core.

import { spawnSync } from "node:child_process";
import { accessSync, constants, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { type Finding, branchQuest } from "../core";
import { type Finding, branchQuest, check } from "../core";
import { discoveryEnv } from "./git";
import { snapshot } from "./tree";

/**
* A finding when `branch` (default: the current branch) is a quest's branch
* and the working tree neither deletes nor modifies that quest relative to its
* merge base with `base`. Not a quest branch, or no such quest at the merge
* base, is no finding.
* and `head` (default: the working tree) neither deletes nor modifies that
* quest relative to its merge base with `base`. Not a quest branch, or no such
* quest at the merge base, is no finding. With `head`, `root` is the
* repository's top level, as in a bare repository.
*/
export function landed(root: string, base: string, branch?: string): Finding[] {
const name = branch ?? currentBranch(root);
const mergeBase = git(root, ["merge-base", base, "HEAD"]);
export function landed(root: string, base: string, options: { branch?: string; head?: string } = {}): Finding[] {
const name = options.branch ?? currentBranch(root);
const head = options.head ?? "HEAD";
const mergeBase = git(root, ["merge-base", base, head]);
if (mergeBase.status !== 0) {
throw new Error(`no merge base between ${base} and HEAD: ${mergeBase.stderr.trim() || "unrelated histories"}`);
throw new Error(
`no merge base between ${base} and ${head}: ${mergeBase.stderr.trim() || "unrelated histories"}`,
);
}
const commit = mergeBase.stdout.trim();
const path = questAt(root, commit, name);
// Without a head, the pathspec and `<rev>:./path` are relative to the root,
// which may sit below the repository's top level; a bare repository has no
// work tree to be relative to.
const relative = options.head === undefined ? "./" : "";
const path = questAt(root, commit, name, relative);
if (path === null) return [];
// The pathspec and `<rev>:./path` are relative to the root, which may sit
// below the repository's top level.
const diff = git(root, ["diff", "--quiet", "--no-ext-diff", commit, "--", `./${path}`]);
const heads = options.head === undefined ? [] : [options.head];
const diff = git(root, ["diff", "--quiet", "--no-ext-diff", commit, ...heads, "--", `${relative}${path}`]);
if (diff.status === 1) return [];
if (diff.status !== 0) throw new Error(`git diff ${commit} -- ${path}: ${diff.stderr.trim()}`);
return [
Expand All @@ -39,11 +50,119 @@ export function landed(root: string, base: string, branch?: string): Finding[] {
];
}

/** The PR head `quest merge` is about to land, and where to fetch it and its base. */
export interface LandingHead {
/** The base repository's Git URL, which serves the head's commits even from a fork. */
remote: string;
/** The base branch's name, and the commit it points at. */
base: string;
baseSha: string;
branch: string;
sha: string;
token: string;
}

/** Checks a head before `quest merge` queues it; resolves to its findings, empty when it may land. */
export type LandingCheck = (head: LandingHead) => Promise<Finding[]>;

/**
* What `quest check --no-stubs --base <base> --branch <branch>` reports on `head.sha`, against a
* freshly fetched base. The head is untrusted, so nothing from it runs or is checked out: the
* check reads git objects. It fetches both commits by SHA into the repository of the checkout at
* `root`, writing no ref, so Git sends only what that repository lacks and an interrupted run leaves
* nothing behind. A checkout it cannot write, or a shallow one whose history could hide the merge
* base, gives way to a temporary bare repository, as does no checkout.
* A finding the base already has is not the head's, as the land daemon screens a head, and a
* repository with no quests on either side does not use them.
*/
export function landingCheck(root: string): LandingCheck {
return async (head) => {
const local = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir", "--is-shallow-repository"]);
const [common, shallow] = local.stdout.trim().split("\n");
const borrowed = local.status === 0 && shallow === "false" && writable(common);
const dir = borrowed ? common : mkdtempSync(join(tmpdir(), "quest-merge-"));
const { baseSha: base, sha: tip } = head;
const run = (args: string[], env: Record<string, string> = {}) => {
const result = spawnSync("git", ["-c", "core.hooksPath=/dev/null", "-C", dir, ...args], {
encoding: "utf8",
env: { ...discoveryEnv(), GIT_TERMINAL_PROMPT: "0", ...env },
maxBuffer: 1 << 30,
});
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`git ${args[0]} failed: ${result.stderr.trim()}`);
return result.stdout.trim();
};
// Findings and errors name the scratch directory and the base's SHA, which the refusal need not show.
const tidy = (finding: Finding): Finding => ({
...finding,
message: finding.message.replaceAll(`${dir}/`, "").replaceAll(base, `origin/${head.base}`),
});
try {
if (!borrowed) run(["init", "--quiet", "--bare"]);
// The token rides in the environment, after any configuration the user's environment already passes.
const count = Number(process.env.GIT_CONFIG_COUNT ?? 0) || 0;
const basic = Buffer.from(`x-access-token:${head.token}`).toString("base64");
run(["fetch", "--quiet", "--no-tags", "--no-write-fetch-head", head.remote, base, tip], {
GIT_CONFIG_COUNT: String(count + 2),
// An empty value drops any header the checkout already sends, such as actions/checkout's, which GitHub would reject as a duplicate.
[`GIT_CONFIG_KEY_${count}`]: "http.https://github.com/.extraheader",
[`GIT_CONFIG_VALUE_${count}`]: "",
[`GIT_CONFIG_KEY_${count + 1}`]: "http.https://github.com/.extraheader",
[`GIT_CONFIG_VALUE_${count + 1}`]: `Authorization: basic ${basic}`,
});
Comment thread
kixelated marked this conversation as resolved.
Resolved
const quests = (ref: string) => run(["ls-tree", "--name-only", ref, "quest"]) !== "";
const based = quests(base);
if (!based && !quests(tip)) return [];
// A finding the base already has is not this PR's, such as one a `quest` older than the tree's
// format reports; one more of the same in the head is.
const known = based ? treeCheck(dir, base) : [];
const findings = treeCheck(dir, tip).filter((finding) => {
const index = known.findIndex((old) => old.path === finding.path && old.message === finding.message);
if (index === -1) return true;
known.splice(index, 1);
return false;
});
let accurate: Finding[];
try {
accurate = landed(dir, base, { branch: head.branch, head: tip });
} catch (error) {
throw new Error(
tidy({ path: "", line: null, message: String(error instanceof Error ? error.message : error) })
.message,
);
}
return [...findings, ...accurate].map(tidy);
} finally {
if (!borrowed) rmSync(dir, { recursive: true, force: true });
}
};
}

/** Whether this process may write the objects of the Git directory `dir`. */
function writable(dir: string): boolean {
try {
accessSync(join(dir, "objects"), constants.W_OK);
return true;
} catch {
return false;
}
}

/** `quest check`'s findings on `commit`; a tree it cannot read, such as one with no quests left, is one. */
function treeCheck(dir: string, commit: string): Finding[] {
try {
const tree = snapshot(dir, commit, null);
return check(tree.docs, tree.exists);
} catch (error) {
return [{ path: "quest", line: null, message: error instanceof Error ? error.message : String(error) }];
}
}

/** The quest file `branch` names, if it existed at `commit`. */
function questAt(root: string, commit: string, branch: string): string | null {
function questAt(root: string, commit: string, branch: string, relative: string): string | null {
if (!branch.startsWith("quest/") || branch.endsWith("/")) return null;
const path = branchQuest(branch);
return git(root, ["cat-file", "-e", `${commit}:./${path}`]).status === 0 ? path : null;
return git(root, ["cat-file", "-e", `${commit}:${relative}${path}`]).status === 0 ? path : null;
}

function currentBranch(root: string): string {
Expand Down
Loading
Loading