@boxxy/train 0.0.0-stage → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +43 -2
- package/dist/decide-merge.d.ts +3 -0
- package/dist/index.d.ts +2 -0
- package/dist/types.d.ts +9 -0
- package/package.json +40 -4
- package/src/decide-merge.ts +153 -0
- package/src/index.ts +2 -0
- package/src/types.ts +16 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 the boxxy authors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,44 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>@boxxy/train</h1>
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
<p>
|
|
5
|
+
<a href="https://www.npmjs.com/package/@boxxy/train"><img src="https://img.shields.io/npm/v/@boxxy/train" alt="npm version"></a>
|
|
6
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<a href="../../docs/design/boxxy/README.md">Documentation</a>
|
|
11
|
+
</p>
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
boxxy's merge rule, `decideMerge`, which decides what the boxxy server does next with a pull request
|
|
15
|
+
that is ready to merge. The server reads the pull request and calls `decideMerge` with what it read.
|
|
16
|
+
`decideMerge` returns one of three answers, and the server acts on it:
|
|
17
|
+
|
|
18
|
+
- finish the merge attempt with an outcome, such as `merged` when the pull request has merged, or
|
|
19
|
+
`repair` when a required check failed;
|
|
20
|
+
- wait, and read the pull request again later;
|
|
21
|
+
- merge the pull request at the head commit the server read.
|
|
22
|
+
|
|
23
|
+
The server merges only when boxxy's review passed, every required check passed and the verify gate
|
|
24
|
+
passed, all at that head commit. The package does no I/O: the server passes in what it read, the
|
|
25
|
+
merge rules, the time, and the last merge it asked for, so that `decideMerge` does not ask again too
|
|
26
|
+
soon.
|
|
27
|
+
|
|
28
|
+
The package is named for the merge train, a later rule that would merge several pull requests at
|
|
29
|
+
once. Its [design](../../docs/design/boxxy/merge-train.md) is not built.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
Install the package from [npm](https://www.npmjs.com/package/@boxxy/train) with Bun:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
bun add @boxxy/train
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The package runs on [Bun](https://bun.sh) 1.3 or newer.
|
|
40
|
+
|
|
41
|
+
## Documentation
|
|
42
|
+
|
|
43
|
+
[The merge step](../../docs/design/boxxy/review-and-merge.md#the-merge-step) holds the table of
|
|
44
|
+
cases that `decideMerge` checks in order, each outcome, and what the server reads and how often.
|
package/dist/index.d.ts
ADDED
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { Instant, MergeReading, MergeRequest, MergeRules } from '@boxxy/model';
|
|
2
|
+
export interface DecideMergeInput {
|
|
3
|
+
readonly observed: MergeReading;
|
|
4
|
+
readonly rules: MergeRules;
|
|
5
|
+
readonly deadlinePassed: boolean;
|
|
6
|
+
readonly acted: MergeRequest | null;
|
|
7
|
+
readonly now: Instant;
|
|
8
|
+
readonly actRetryMinutes: number;
|
|
9
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@boxxy/train",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.5",
|
|
4
|
+
"description": "boxxy's merge rule: decides each read of a merge from the pull request, its checks, its review and its verify reading",
|
|
5
|
+
"homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/train#readme",
|
|
6
|
+
"bugs": "https://github.com/zgeoff/boxxy/issues",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/zgeoff/boxxy.git",
|
|
11
|
+
"directory": "modules/train"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"src",
|
|
15
|
+
"!src/**/*.test.ts",
|
|
16
|
+
"dist"
|
|
17
|
+
],
|
|
18
|
+
"type": "module",
|
|
19
|
+
"exports": {
|
|
20
|
+
".": {
|
|
21
|
+
"types": "./dist/index.d.ts",
|
|
22
|
+
"default": "./src/index.ts"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"build": "rm -rf dist && tsrs -p tsconfig.build.json",
|
|
30
|
+
"typecheck": "tsrs --noEmit"
|
|
31
|
+
},
|
|
32
|
+
"dependencies": {
|
|
33
|
+
"@boxxy/model": "0.2.5"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@faker-js/faker": "10.6.0"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"bun": ">=1.3",
|
|
40
|
+
"node": ">=24"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
CommitSha,
|
|
3
|
+
GateRecord,
|
|
4
|
+
JobStep,
|
|
5
|
+
MergeCloseOut,
|
|
6
|
+
MergeObservation,
|
|
7
|
+
MergeOutcome,
|
|
8
|
+
UnreadableMerge,
|
|
9
|
+
} from '@boxxy/model';
|
|
10
|
+
import { toJSONValue } from '@boxxy/model';
|
|
11
|
+
import type { DecideMergeInput } from './types.ts';
|
|
12
|
+
|
|
13
|
+
const minuteMs = 60_000;
|
|
14
|
+
|
|
15
|
+
// The merge rule: one step for each read of a merge attempt. It checks the rows of the merge
|
|
16
|
+
// table from the top, and the first match wins. Every green answer needs a record at the head.
|
|
17
|
+
export function decideMerge(input: DecideMergeInput): JobStep {
|
|
18
|
+
const observed = input.observed;
|
|
19
|
+
|
|
20
|
+
// no later read can give a head, so only the owner moves the merge on
|
|
21
|
+
if (observed.state === 'unreadable') {
|
|
22
|
+
return buildBlocked(observed);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const required = [...new Set([...input.rules.checks, ...observed.baseRequired])];
|
|
26
|
+
|
|
27
|
+
const finish = (outcome: MergeOutcome, fields: Partial<MergeCloseOut> = {}): JobStep =>
|
|
28
|
+
buildFinish(observed, required, outcome, fields);
|
|
29
|
+
|
|
30
|
+
if (observed.state === 'merged') {
|
|
31
|
+
return finish('merged', {
|
|
32
|
+
mergeCommit: observed.mergeCommit,
|
|
33
|
+
byBoxxy: input.acted?.head === observed.head,
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
if (observed.state === 'closed') {
|
|
38
|
+
return finish('closed');
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// a push after the review sends the item back to it
|
|
42
|
+
if (!isPassedAt(observed.review, observed.head)) {
|
|
43
|
+
return finish('stale');
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
if (observed.mergeable === 'conflict') {
|
|
47
|
+
return finish('repair', { cause: 'conflict' });
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const red = required.filter((name) => observed.checks.get(name) === 'failure');
|
|
51
|
+
|
|
52
|
+
if (red.length > 0) {
|
|
53
|
+
return finish('repair', { cause: 'checks-red', failed: red });
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// a check with no run, one still going, or one that ended neither success nor failure is not
|
|
57
|
+
// green; nor is a head whose mergeable state GitHub has not worked out yet
|
|
58
|
+
const pending = required.filter((name) => observed.checks.get(name) !== 'success');
|
|
59
|
+
|
|
60
|
+
if (pending.length > 0 || observed.mergeable === 'unknown') {
|
|
61
|
+
return input.deadlinePassed
|
|
62
|
+
? finish('stalled')
|
|
63
|
+
: {
|
|
64
|
+
kind: 'wait',
|
|
65
|
+
reason: pending.length > 0 ? 'checks pending' : 'mergeable state unknown',
|
|
66
|
+
pending,
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// a rules file without the verify gate in its checks must still never merge an unverified head
|
|
71
|
+
if (observed.verify.status !== 'verified') {
|
|
72
|
+
return finish('unverified');
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const sent = input.acted?.head === observed.head ? input.acted : null;
|
|
76
|
+
|
|
77
|
+
if (sent?.answer?.kind === 'not-mergeable') {
|
|
78
|
+
return finish('refused', { reason: sent.answer.reason });
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
if (sent !== null && input.deadlinePassed) {
|
|
82
|
+
return finish('stalled');
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// a second call is safe, because the forge merges only at the head it names
|
|
86
|
+
if (sent !== null && input.now - sent.at < input.actRetryMinutes * minuteMs) {
|
|
87
|
+
return { kind: 'wait', reason: 'merge requested', pending: [] };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return {
|
|
91
|
+
kind: 'act',
|
|
92
|
+
action: {
|
|
93
|
+
kind: 'merge',
|
|
94
|
+
unit: { members: [{ pullRequest: observed.pullRequest, head: observed.head }] },
|
|
95
|
+
method: input.rules.method,
|
|
96
|
+
required,
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function buildBlocked(observed: UnreadableMerge): JobStep {
|
|
102
|
+
const closeOut: MergeCloseOut = {
|
|
103
|
+
outcome: 'blocked',
|
|
104
|
+
head: null,
|
|
105
|
+
required: [],
|
|
106
|
+
failed: [],
|
|
107
|
+
cause: null,
|
|
108
|
+
mergeCommit: null,
|
|
109
|
+
reason: formatReadProblem(observed),
|
|
110
|
+
byBoxxy: false,
|
|
111
|
+
verify: null,
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
return { kind: 'finish', closeOut: toJSONValue(closeOut) };
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function formatReadProblem(observed: UnreadableMerge): string {
|
|
118
|
+
if (observed.problem === 'no-pull-request') {
|
|
119
|
+
return 'the item has no pull request';
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
const name = `${observed.pullRequest.repo}#${observed.pullRequest.number}`;
|
|
123
|
+
|
|
124
|
+
return observed.problem === 'no-commit'
|
|
125
|
+
? `the pull request ${name} has no commit`
|
|
126
|
+
: `the forge holds no pull request ${name}`;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function buildFinish(
|
|
130
|
+
observed: MergeObservation,
|
|
131
|
+
required: readonly string[],
|
|
132
|
+
outcome: MergeOutcome,
|
|
133
|
+
fields: Partial<MergeCloseOut>,
|
|
134
|
+
): JobStep {
|
|
135
|
+
const closeOut: MergeCloseOut = {
|
|
136
|
+
outcome,
|
|
137
|
+
head: observed.head,
|
|
138
|
+
required,
|
|
139
|
+
failed: [],
|
|
140
|
+
cause: null,
|
|
141
|
+
mergeCommit: null,
|
|
142
|
+
reason: null,
|
|
143
|
+
byBoxxy: false,
|
|
144
|
+
verify: observed.verify,
|
|
145
|
+
...fields,
|
|
146
|
+
};
|
|
147
|
+
|
|
148
|
+
return { kind: 'finish', closeOut: toJSONValue(closeOut) };
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function isPassedAt(review: GateRecord | null, head: CommitSha): boolean {
|
|
152
|
+
return review?.status === 'passed' && review.head === head;
|
|
153
|
+
}
|
package/src/index.ts
ADDED
package/src/types.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { Instant, MergeReading, MergeRequest, MergeRules } from '@boxxy/model';
|
|
2
|
+
|
|
3
|
+
export interface DecideMergeInput {
|
|
4
|
+
readonly observed: MergeReading;
|
|
5
|
+
readonly rules: MergeRules;
|
|
6
|
+
|
|
7
|
+
// the merge step's time limit, from the attempt's claim, has passed
|
|
8
|
+
readonly deadlinePassed: boolean;
|
|
9
|
+
|
|
10
|
+
// the last merge request boxxy sent for the attempt, null before the first
|
|
11
|
+
readonly acted: MergeRequest | null;
|
|
12
|
+
readonly now: Instant;
|
|
13
|
+
|
|
14
|
+
// a request with no answer is sent again only this long after it was marked
|
|
15
|
+
readonly actRetryMinutes: number;
|
|
16
|
+
}
|