@davidbyoung/software-factory 0.0.0-stage → 0.1.0
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/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +205 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- package/workflows/factory-review.yml +75 -0
|
@@ -0,0 +1,510 @@
|
|
|
1
|
+
export const AGENT_MARK = "<!-- agent -->";
|
|
2
|
+
export const STATUSES = [
|
|
3
|
+
"Backlog",
|
|
4
|
+
"In refinement",
|
|
5
|
+
"Ready",
|
|
6
|
+
"In progress",
|
|
7
|
+
"In review",
|
|
8
|
+
"Done",
|
|
9
|
+
];
|
|
10
|
+
/** The six states a ticket moves through, by the key a repository's
|
|
11
|
+
* settings use for each. Inside the code a state stays one of `Status`; a
|
|
12
|
+
* board's own column names are applied only where the board is read and
|
|
13
|
+
* where it is written. */
|
|
14
|
+
export const STATE_KEYS = {
|
|
15
|
+
backlog: "Backlog",
|
|
16
|
+
refining: "In refinement",
|
|
17
|
+
ready: "Ready",
|
|
18
|
+
building: "In progress",
|
|
19
|
+
review: "In review",
|
|
20
|
+
done: "Done",
|
|
21
|
+
};
|
|
22
|
+
/** The factory's own board: every state has the column of its own name. */
|
|
23
|
+
export const DEFAULT_COLUMNS = {
|
|
24
|
+
Backlog: "Backlog",
|
|
25
|
+
"In refinement": "In refinement",
|
|
26
|
+
Ready: "Ready",
|
|
27
|
+
"In progress": "In progress",
|
|
28
|
+
"In review": "In review",
|
|
29
|
+
Done: "Done",
|
|
30
|
+
};
|
|
31
|
+
/** A name matches whatever its capitals and the spaces around it. */
|
|
32
|
+
export const sameName = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
|
|
33
|
+
/** The column a ticket in `status` shows in: its own, or else the nearest
|
|
34
|
+
* earlier state's. Nothing but an approved ticket shows in the Ready
|
|
35
|
+
* column, so a state with no column passes over it. */
|
|
36
|
+
export function columnFor(status, columns) {
|
|
37
|
+
for (let i = STATUSES.indexOf(status); i >= 0; i--) {
|
|
38
|
+
const name = columns[STATUSES[i]];
|
|
39
|
+
if (name !== null && (STATUSES[i] !== "Ready" || status === "Ready"))
|
|
40
|
+
return name;
|
|
41
|
+
}
|
|
42
|
+
return columns.Backlog ?? "Backlog";
|
|
43
|
+
}
|
|
44
|
+
/** The state whose column is named `name`, or null when none is. */
|
|
45
|
+
export function statusOfColumn(name, columns) {
|
|
46
|
+
return (STATUSES.find((s) => columns[s] !== null && sameName(columns[s], name)) ??
|
|
47
|
+
null);
|
|
48
|
+
}
|
|
49
|
+
/** How a sentence names where the card is: "In progress" when the state has
|
|
50
|
+
* a column of its own, "in Todo" when it shows in another's. */
|
|
51
|
+
function cardAt(status, columns) {
|
|
52
|
+
const name = columnFor(status, columns);
|
|
53
|
+
return columns[status] === null ? `in ${name}` : name;
|
|
54
|
+
}
|
|
55
|
+
const MARKER_LINE = /^<!-- work-status: (?:(refining|claim) (local|cloud|actions) (\S+)|started (cloud|actions) (\S+)|(waiting|refined|released|cleared|partial)) -->$/;
|
|
56
|
+
/** A comment's lines outside fenced code blocks, trimmed. */
|
|
57
|
+
function linesOutsideFences(body) {
|
|
58
|
+
const lines = [];
|
|
59
|
+
let fence = null;
|
|
60
|
+
for (const raw of body.split(/\r?\n/)) {
|
|
61
|
+
const line = raw.trim();
|
|
62
|
+
const opener = /^(`{3,}|~{3,})/.exec(line)?.[1];
|
|
63
|
+
if (opener) {
|
|
64
|
+
if (fence === null)
|
|
65
|
+
fence = opener;
|
|
66
|
+
else if (opener[0] === fence[0] && opener.length >= fence.length)
|
|
67
|
+
fence = null;
|
|
68
|
+
continue;
|
|
69
|
+
}
|
|
70
|
+
if (fence === null)
|
|
71
|
+
lines.push(line);
|
|
72
|
+
}
|
|
73
|
+
return lines;
|
|
74
|
+
}
|
|
75
|
+
/** The markers in one comment: each on a line of its own, outside a fenced
|
|
76
|
+
* code block, in a comment that also carries the agent mark. */
|
|
77
|
+
export function parseMarkers(body) {
|
|
78
|
+
if (!body.includes(AGENT_MARK))
|
|
79
|
+
return [];
|
|
80
|
+
const found = [];
|
|
81
|
+
for (const line of linesOutsideFences(body)) {
|
|
82
|
+
const match = MARKER_LINE.exec(line);
|
|
83
|
+
if (!match)
|
|
84
|
+
continue;
|
|
85
|
+
const [, session, where, id, startWhere, started, bare] = match;
|
|
86
|
+
if (session === "refining" || session === "claim") {
|
|
87
|
+
found.push({ kind: session, where: where, id });
|
|
88
|
+
}
|
|
89
|
+
else if (started) {
|
|
90
|
+
found.push({
|
|
91
|
+
kind: "started",
|
|
92
|
+
where: startWhere,
|
|
93
|
+
marker: started,
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
else {
|
|
97
|
+
found.push({
|
|
98
|
+
kind: bare,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return found;
|
|
103
|
+
}
|
|
104
|
+
// Cost markers, which say what a session or a CI review spent at API list
|
|
105
|
+
// prices: `<!-- cost: 3.41 session=ID -->` from a session,
|
|
106
|
+
// `<!-- cost: 0.92 -->` from the CI review's summary.
|
|
107
|
+
/** The account the CI review's summary is posted from. */
|
|
108
|
+
export const CI_BOT = "github-actions[bot]";
|
|
109
|
+
const COST_LINE = /^<!-- cost: (\d+(?:\.\d+)?)(?: session=\S+)? -->$/;
|
|
110
|
+
/** Whether a body already carries a cost marker, read as `parseCosts` reads
|
|
111
|
+
* one: on a line of its own, outside a fenced code block. A marker quoted in
|
|
112
|
+
* prose does not count. */
|
|
113
|
+
export function hasCostMarker(body) {
|
|
114
|
+
return linesOutsideFences(body).some((line) => COST_LINE.test(line));
|
|
115
|
+
}
|
|
116
|
+
/** The cost markers in one comment, read as markers are: each on a line of
|
|
117
|
+
* its own, outside a fenced code block. Only the owner's account, which the
|
|
118
|
+
* agents post as, and the CI review's bot count; the owner's comments count
|
|
119
|
+
* only with the agent mark. */
|
|
120
|
+
export function parseCosts(comment, owner) {
|
|
121
|
+
const fromAgent = comment.author === owner && comment.body.includes(AGENT_MARK);
|
|
122
|
+
if (!fromAgent && comment.author !== CI_BOT)
|
|
123
|
+
return [];
|
|
124
|
+
return linesOutsideFences(comment.body).flatMap((line) => {
|
|
125
|
+
const match = COST_LINE.exec(line);
|
|
126
|
+
return match ? [Number(match[1])] : [];
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
/** Whether a pull request's body says it builds this issue, as "Closes #N"
|
|
130
|
+
* or "Part of #N". */
|
|
131
|
+
export function buildsIssue(body, number) {
|
|
132
|
+
return new RegExp(`\\b(?:closes|part of) #${number}(?!\\d)`, "i").test(body);
|
|
133
|
+
}
|
|
134
|
+
/** The issue's Cost: every cost marker on it and on each pull request, open,
|
|
135
|
+
* merged, or closed, that builds it, to the cent. Null when there are none. */
|
|
136
|
+
export function issueCost(issue, pulls, owner) {
|
|
137
|
+
const comments = [
|
|
138
|
+
...issue.comments,
|
|
139
|
+
...pulls
|
|
140
|
+
.filter((pull) => pull.closes.includes(issue.number) ||
|
|
141
|
+
buildsIssue(pull.body, issue.number))
|
|
142
|
+
.flatMap((pull) => pull.comments ?? []),
|
|
143
|
+
];
|
|
144
|
+
const costs = comments.flatMap((c) => parseCosts(c, owner));
|
|
145
|
+
if (costs.length === 0)
|
|
146
|
+
return null;
|
|
147
|
+
return Math.round(costs.reduce((a, b) => a + b, 0) * 100) / 100;
|
|
148
|
+
}
|
|
149
|
+
// Reviewer runs, which the SubagentStart and SubagentStop hooks record in one
|
|
150
|
+
// "Reviewers in this session" comment per session
|
|
151
|
+
// (`factory reviewers`). Each row carries a hidden copy of itself.
|
|
152
|
+
export const REVIEWER_RUNS_MARK = "<!-- reviewer-runs session=";
|
|
153
|
+
const RUN_LINE = /^<!-- reviewer-run: (\{.*\}) -->$/;
|
|
154
|
+
export function runLine(run) {
|
|
155
|
+
return `<!-- reviewer-run: ${JSON.stringify(run)} -->`;
|
|
156
|
+
}
|
|
157
|
+
/** The runs in a reviewer-runs comment the agents posted. */
|
|
158
|
+
export function parseRuns(comment) {
|
|
159
|
+
if (!comment.body.includes(REVIEWER_RUNS_MARK) ||
|
|
160
|
+
!comment.body.includes(AGENT_MARK))
|
|
161
|
+
return [];
|
|
162
|
+
return linesOutsideFences(comment.body).flatMap((line) => {
|
|
163
|
+
const match = RUN_LINE.exec(line);
|
|
164
|
+
if (!match)
|
|
165
|
+
return [];
|
|
166
|
+
try {
|
|
167
|
+
const run = JSON.parse(match[1]);
|
|
168
|
+
return typeof run.reviewer === "string" &&
|
|
169
|
+
typeof run.start === "string" &&
|
|
170
|
+
!Number.isNaN(Date.parse(run.start))
|
|
171
|
+
? [run]
|
|
172
|
+
: [];
|
|
173
|
+
}
|
|
174
|
+
catch {
|
|
175
|
+
return [];
|
|
176
|
+
}
|
|
177
|
+
});
|
|
178
|
+
}
|
|
179
|
+
/** How long a run may say "running" before it reads as one that never
|
|
180
|
+
* recorded its finish. */
|
|
181
|
+
export const STUCK_AFTER_MS = 2 * 60 * 60 * 1000;
|
|
182
|
+
export const isStuck = (run, now) => run.result === "running" &&
|
|
183
|
+
now.getTime() - Date.parse(run.start) > STUCK_AFTER_MS;
|
|
184
|
+
function byTime(a, b) {
|
|
185
|
+
const at = Date.parse(a.createdAt);
|
|
186
|
+
const bt = Date.parse(b.createdAt);
|
|
187
|
+
return at !== bt ? at - bt : a.id - b.id;
|
|
188
|
+
}
|
|
189
|
+
export function markedComments(comments) {
|
|
190
|
+
return [...comments]
|
|
191
|
+
.sort(byTime)
|
|
192
|
+
.flatMap((comment) => parseMarkers(comment.body).map((marker) => ({ ...comment, marker })));
|
|
193
|
+
}
|
|
194
|
+
/** A claim is live when it was posted while no other claim was, and no
|
|
195
|
+
* release or clear has followed. A claim posted while another was live never
|
|
196
|
+
* counts, so a losing run that crashes before deleting it blocks nothing. */
|
|
197
|
+
export function workState(comments) {
|
|
198
|
+
let live = null;
|
|
199
|
+
let lastLive = null;
|
|
200
|
+
let start = null;
|
|
201
|
+
for (const marked of markedComments(comments)) {
|
|
202
|
+
switch (marked.marker.kind) {
|
|
203
|
+
case "claim":
|
|
204
|
+
if (!live)
|
|
205
|
+
live = lastLive = marked;
|
|
206
|
+
start = null;
|
|
207
|
+
break;
|
|
208
|
+
case "released":
|
|
209
|
+
case "cleared":
|
|
210
|
+
case "partial":
|
|
211
|
+
live = null;
|
|
212
|
+
start = null;
|
|
213
|
+
break;
|
|
214
|
+
case "refining":
|
|
215
|
+
start = null;
|
|
216
|
+
break;
|
|
217
|
+
case "started":
|
|
218
|
+
start = marked;
|
|
219
|
+
break;
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
return { live, lastLive, start };
|
|
223
|
+
}
|
|
224
|
+
/** Whether a pull request's body says it builds part of the follow-ups
|
|
225
|
+
* issue, as "Part of #N". A plain mention, such as a build linking the issue
|
|
226
|
+
* it added a line to, does not count. */
|
|
227
|
+
export function buildsPartOf(body, number) {
|
|
228
|
+
return new RegExp(`\\bpart of #${number}(?!\\d)`, "i").test(body);
|
|
229
|
+
}
|
|
230
|
+
/** The pull requests that put this issue In review. */
|
|
231
|
+
export function reviewingPulls(issue, pulls) {
|
|
232
|
+
return pulls.filter((pull) => pull.closes.includes(issue.number) ||
|
|
233
|
+
(issue.labels.includes("follow-up") &&
|
|
234
|
+
buildsPartOf(pull.body, issue.number)));
|
|
235
|
+
}
|
|
236
|
+
const READY_RESETS = new Set([
|
|
237
|
+
"released",
|
|
238
|
+
"cleared",
|
|
239
|
+
"partial",
|
|
240
|
+
"refined",
|
|
241
|
+
"refining",
|
|
242
|
+
"waiting",
|
|
243
|
+
]);
|
|
244
|
+
// An old `cloud` marker leaves "Runs in" empty: nothing writes it any more.
|
|
245
|
+
const RUNS_IN = {
|
|
246
|
+
local: "Local",
|
|
247
|
+
cloud: "",
|
|
248
|
+
actions: "Actions",
|
|
249
|
+
};
|
|
250
|
+
const runsIn = (where) => RUNS_IN[where];
|
|
251
|
+
// With no "Runs in" value to say where an old cloud session ran, its Session
|
|
252
|
+
// says so, as plain text.
|
|
253
|
+
const sessionText = (where, id) => where === "cloud" ? `cloud ${id}` : id;
|
|
254
|
+
/** The page of an Actions run, from the board's or the view's session: the
|
|
255
|
+
* run's ID, which `runPage` turns into its page. Null for any other
|
|
256
|
+
* session. */
|
|
257
|
+
export function actionsRunLink(derived, runPage) {
|
|
258
|
+
if (derived.runsIn !== "Actions" || !/^\d+$/.test(derived.session))
|
|
259
|
+
return null;
|
|
260
|
+
return runPage(derived.session);
|
|
261
|
+
}
|
|
262
|
+
function claimSession(claim) {
|
|
263
|
+
if (!claim || claim.marker.kind !== "claim")
|
|
264
|
+
return { session: "", runsIn: "" };
|
|
265
|
+
return {
|
|
266
|
+
session: sessionText(claim.marker.where, claim.marker.id),
|
|
267
|
+
runsIn: runsIn(claim.marker.where),
|
|
268
|
+
};
|
|
269
|
+
}
|
|
270
|
+
/** An issue's Status is the first rule that applies: Done, In review,
|
|
271
|
+
* In progress, Ready, In refinement, Backlog. */
|
|
272
|
+
export function derive(issue, card, pulls, columns = DEFAULT_COLUMNS) {
|
|
273
|
+
const work = workState(issue.comments);
|
|
274
|
+
const marked = markedComments(issue.comments);
|
|
275
|
+
if (issue.state === "closed") {
|
|
276
|
+
return {
|
|
277
|
+
status: "Done",
|
|
278
|
+
...claimSession(work.lastLive),
|
|
279
|
+
since: issue.closedAt,
|
|
280
|
+
pulls: [],
|
|
281
|
+
};
|
|
282
|
+
}
|
|
283
|
+
const reviewing = reviewingPulls(issue, pulls);
|
|
284
|
+
if (reviewing.length > 0) {
|
|
285
|
+
const first = [...reviewing].sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
|
|
286
|
+
return {
|
|
287
|
+
status: "In review",
|
|
288
|
+
...claimSession(work.lastLive),
|
|
289
|
+
since: first.createdAt,
|
|
290
|
+
pulls: reviewing.map((pull) => pull.number),
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
if (work.live) {
|
|
294
|
+
return {
|
|
295
|
+
status: "In progress",
|
|
296
|
+
...claimSession(work.live),
|
|
297
|
+
since: work.live.createdAt,
|
|
298
|
+
pulls: [],
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
if (work.start) {
|
|
302
|
+
const where = work.start.marker.kind === "started" ? work.start.marker.where : "cloud";
|
|
303
|
+
return {
|
|
304
|
+
status: "In progress",
|
|
305
|
+
session: `${where}, starting`,
|
|
306
|
+
runsIn: runsIn(where),
|
|
307
|
+
since: work.start.createdAt,
|
|
308
|
+
pulls: [],
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
if (card?.status === "Ready" && card.updatedAt) {
|
|
312
|
+
const reset = marked.filter((m) => READY_RESETS.has(m.marker.kind)).at(-1);
|
|
313
|
+
if (!reset || Date.parse(card.updatedAt) > Date.parse(reset.createdAt)) {
|
|
314
|
+
return {
|
|
315
|
+
status: "Ready",
|
|
316
|
+
session: "",
|
|
317
|
+
runsIn: "",
|
|
318
|
+
since: card.updatedAt,
|
|
319
|
+
pulls: [],
|
|
320
|
+
};
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
// Past the session rules, the newest marker says where the card stands. A
|
|
324
|
+
// card moves only forward on its own: when the next step is the owner's,
|
|
325
|
+
// it stays where it is, waiting on them, until they move it. Their move
|
|
326
|
+
// to Backlog wins once it is later than that marker.
|
|
327
|
+
const newest = marked.at(-1);
|
|
328
|
+
const waitingOn = (status, since) => ({
|
|
329
|
+
status,
|
|
330
|
+
session: "Waiting on you",
|
|
331
|
+
runsIn: "",
|
|
332
|
+
since,
|
|
333
|
+
pulls: [],
|
|
334
|
+
});
|
|
335
|
+
const backlog = (since) => ({
|
|
336
|
+
status: "Backlog",
|
|
337
|
+
session: "",
|
|
338
|
+
runsIn: "",
|
|
339
|
+
since,
|
|
340
|
+
pulls: [],
|
|
341
|
+
});
|
|
342
|
+
if (!newest)
|
|
343
|
+
return backlog(card?.updatedAt ?? null);
|
|
344
|
+
// A card in the backlog column says the owner sent the ticket back only
|
|
345
|
+
// when the ticket's own state shows in another column: where it shows in
|
|
346
|
+
// that one too, the sync put the card there.
|
|
347
|
+
const ownerBacklog = card?.status === "Backlog" &&
|
|
348
|
+
card.updatedAt !== null &&
|
|
349
|
+
Date.parse(card.updatedAt) > Date.parse(newest.createdAt) &&
|
|
350
|
+
!(newest.marker.kind === "waiting" || newest.marker.kind === "refined"
|
|
351
|
+
? sameName(columnFor("In refinement", columns), columnFor("Backlog", columns))
|
|
352
|
+
: newest.marker.kind === "released" || newest.marker.kind === "cleared"
|
|
353
|
+
? sameName(columnFor("In progress", columns), columnFor("Backlog", columns))
|
|
354
|
+
: false)
|
|
355
|
+
? card.updatedAt
|
|
356
|
+
: null;
|
|
357
|
+
switch (newest.marker.kind) {
|
|
358
|
+
case "refining":
|
|
359
|
+
return {
|
|
360
|
+
status: "In refinement",
|
|
361
|
+
session: sessionText(newest.marker.where, newest.marker.id),
|
|
362
|
+
runsIn: runsIn(newest.marker.where),
|
|
363
|
+
since: newest.createdAt,
|
|
364
|
+
pulls: [],
|
|
365
|
+
};
|
|
366
|
+
case "waiting":
|
|
367
|
+
case "refined":
|
|
368
|
+
return ownerBacklog
|
|
369
|
+
? backlog(ownerBacklog)
|
|
370
|
+
: waitingOn("In refinement", newest.createdAt);
|
|
371
|
+
case "released":
|
|
372
|
+
case "cleared":
|
|
373
|
+
return ownerBacklog
|
|
374
|
+
? backlog(ownerBacklog)
|
|
375
|
+
: waitingOn("In progress", newest.createdAt);
|
|
376
|
+
case "partial":
|
|
377
|
+
return backlog(ownerBacklog ?? newest.createdAt);
|
|
378
|
+
default:
|
|
379
|
+
return backlog(card?.updatedAt ?? null);
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
const HOUR = 60 * 60 * 1000;
|
|
383
|
+
/** Over 24 hours In progress or In refinement with a session. */
|
|
384
|
+
export function isStale(derived, now) {
|
|
385
|
+
if (derived.status !== "In progress" && derived.status !== "In refinement")
|
|
386
|
+
return false;
|
|
387
|
+
if (!derived.session || derived.session === "Waiting on you")
|
|
388
|
+
return false;
|
|
389
|
+
return (derived.since !== null &&
|
|
390
|
+
now.getTime() - Date.parse(derived.since) > 24 * HOUR);
|
|
391
|
+
}
|
|
392
|
+
/** Ready for over 5 minutes with no start: the poller should have fired. */
|
|
393
|
+
export function isNotStarted(derived, openBlockers, now) {
|
|
394
|
+
return (derived.status === "Ready" &&
|
|
395
|
+
openBlockers.length === 0 &&
|
|
396
|
+
derived.since !== null &&
|
|
397
|
+
now.getTime() - Date.parse(derived.since) > 5 * 60 * 1000);
|
|
398
|
+
}
|
|
399
|
+
/** A claim or start over 24 hours old with no pull request, which the
|
|
400
|
+
* nightly sync clears. Null when there is nothing to clear. */
|
|
401
|
+
export function toClear(issue, pulls, now) {
|
|
402
|
+
if (issue.state !== "open" || reviewingPulls(issue, pulls).length > 0)
|
|
403
|
+
return null;
|
|
404
|
+
const work = workState(issue.comments);
|
|
405
|
+
const old = (m) => m !== null && now.getTime() - Date.parse(m.createdAt) > 24 * HOUR;
|
|
406
|
+
if (old(work.live))
|
|
407
|
+
return { kind: "claim", since: work.live.createdAt };
|
|
408
|
+
if (old(work.start)) {
|
|
409
|
+
return { kind: "start", since: work.start.createdAt };
|
|
410
|
+
}
|
|
411
|
+
return null;
|
|
412
|
+
}
|
|
413
|
+
/** "2026-11-09 14:05 UTC" */
|
|
414
|
+
export function utc(iso) {
|
|
415
|
+
return `${new Date(iso).toISOString().slice(0, 16).replace("T", " ")} UTC`;
|
|
416
|
+
}
|
|
417
|
+
function sessionPhrase(who) {
|
|
418
|
+
if (who.where === "actions") {
|
|
419
|
+
const run = who.link ? `[${who.id}](${who.link})` : who.id;
|
|
420
|
+
const by = who.actor ? `, started by @${who.actor}` : "";
|
|
421
|
+
return `in GitHub Actions, run ${run}${by}.`;
|
|
422
|
+
}
|
|
423
|
+
const where = "in a local session";
|
|
424
|
+
if (who.id === "unknown")
|
|
425
|
+
return `${where}.`;
|
|
426
|
+
return `${where}, ${who.id}.`;
|
|
427
|
+
}
|
|
428
|
+
/** "The card stays In progress, waiting on you." */
|
|
429
|
+
const waiting = (columns) => `The card stays ${cardAt("In progress", columns)}, waiting on you.`;
|
|
430
|
+
/** Where a ticket can be sent to build again: the Ready column when the
|
|
431
|
+
* board has one, and always a session. */
|
|
432
|
+
const again = (issue, columns) => {
|
|
433
|
+
const ready = columns.Ready;
|
|
434
|
+
if (ready === null)
|
|
435
|
+
return `To try again, tell a session to build #${issue}, or run \`factory build ${issue}\`.`;
|
|
436
|
+
return `Move it to ${ready} to try again.`;
|
|
437
|
+
};
|
|
438
|
+
export function commentBody(c, columns = DEFAULT_COLUMNS) {
|
|
439
|
+
const mark = (marker, sentence) => `${sentence}\n\n<!-- work-status: ${marker} -->\n${AGENT_MARK}`;
|
|
440
|
+
// A session's cost note goes after what the comment says.
|
|
441
|
+
const withCost = (text, cost) => cost ? `${text}\n\n${cost}` : text;
|
|
442
|
+
const WAITING = waiting(columns);
|
|
443
|
+
const ready = columns.Ready;
|
|
444
|
+
switch (c.kind) {
|
|
445
|
+
case "cost":
|
|
446
|
+
return `${c.cost}\n${AGENT_MARK}`;
|
|
447
|
+
case "refining":
|
|
448
|
+
return mark(`refining ${c.who.where} ${c.who.id}`, `Refining this issue ${sessionPhrase(c.who)}`);
|
|
449
|
+
case "waiting":
|
|
450
|
+
return mark("waiting", withCost("Refinement is waiting on you: the questions are in the comment above.", c.cost));
|
|
451
|
+
case "refined": {
|
|
452
|
+
const sentence = ready === null
|
|
453
|
+
? `Refinement is done. This board has no column for approving a build: tell a session to build #${c.issue}, or run \`factory build ${c.issue}\`.`
|
|
454
|
+
: `Refinement is done. The card stays ${cardAt("In refinement", columns)} until it moves to ${ready}, which starts a build in GitHub Actions: move it there, or ask this session to. To build it on your machine instead, tell a local session to work #${c.issue}.`;
|
|
455
|
+
const before = c.before?.trimEnd();
|
|
456
|
+
const lead = [before, c.cost].filter(Boolean).join("\n\n");
|
|
457
|
+
return mark("refined", lead ? `${lead}\n\n${sentence}` : sentence);
|
|
458
|
+
}
|
|
459
|
+
case "started":
|
|
460
|
+
return mark(`started actions ${c.marker}`, `Starting a build in GitHub Actions: the card moved to ${ready ?? "Ready"}.`);
|
|
461
|
+
case "dispatch-failed":
|
|
462
|
+
return mark("released", `Could not start a build in GitHub Actions: GitHub answered ${c.status} (${c.reason}). ${WAITING} ${again(c.issue, columns)}`);
|
|
463
|
+
case "claim":
|
|
464
|
+
return mark(`claim ${c.who.where} ${c.who.id}`, `Building this ${sessionPhrase(c.who)}`);
|
|
465
|
+
case "stopped": {
|
|
466
|
+
const head = `Stopped without a pull request: ${c.reason}. ${WAITING}`;
|
|
467
|
+
const tail = c.where === "actions"
|
|
468
|
+
? `Run \`factory build ${c.issue}\` to try again${ready === null ? "." : `, or move it to ${ready}.`}`
|
|
469
|
+
: `Tell a session to work #${c.issue} again${ready === null ? "." : `, or move it to ${ready} to build it in GitHub Actions.`}`;
|
|
470
|
+
return mark("released", withCost(`${head} ${tail}`, c.cost));
|
|
471
|
+
}
|
|
472
|
+
case "ended":
|
|
473
|
+
return mark("released", `The run ended without a pull request. ${WAITING} ${again(c.issue, columns)}`);
|
|
474
|
+
case "cleared-claim":
|
|
475
|
+
return mark("cleared", `Cleared the claim from ${utc(c.since)}: no pull request after 24 hours, so that session has stopped. ${WAITING} ${again(c.issue, columns)}`);
|
|
476
|
+
case "cleared-start":
|
|
477
|
+
return mark("cleared", `Cleared the build started ${utc(c.since)}: no claim or pull request after 24 hours. ${WAITING} ${again(c.issue, columns)}`);
|
|
478
|
+
case "follow-ups-merged":
|
|
479
|
+
return mark("partial", `Pull request #${c.pull} merged part of these follow-ups. The unchecked lines wait for the next build; the card is back in ${columnFor("Backlog", columns)}.`);
|
|
480
|
+
case "pull-closed":
|
|
481
|
+
return mark("released", ready === null
|
|
482
|
+
? `Pull request #${c.pull} was closed without merging. ${WAITING} Tell a session to build #${c.issue}, or run \`factory build ${c.issue}\`, to rebuild it, or ask a session to refine it first.`
|
|
483
|
+
: `Pull request #${c.pull} was closed without merging. ${WAITING} Move it to ${ready} to rebuild it, or ask a session to refine it first.`);
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
/** What the views and the sync work from: the open tickets and those
|
|
487
|
+
* closed in the last day, from what "Read everything at once" returned, and
|
|
488
|
+
* the pull requests. */
|
|
489
|
+
export function toSnapshot(tickets, pulls, now, donePulls = []) {
|
|
490
|
+
const day = 24 * HOUR;
|
|
491
|
+
const issues = tickets.filter((t) => t.state === "open" ||
|
|
492
|
+
(t.closedAt !== null && now.getTime() - Date.parse(t.closedAt) <= day));
|
|
493
|
+
return {
|
|
494
|
+
issues,
|
|
495
|
+
pulls,
|
|
496
|
+
donePulls: donePulls.filter((d) => !pulls.some((p) => p.number === d.number)),
|
|
497
|
+
};
|
|
498
|
+
}
|
|
499
|
+
/** A ticket's card, its column read as the state that column shows. A
|
|
500
|
+
* card with no Status has none; one in a column no state names is
|
|
501
|
+
* "Unmapped". */
|
|
502
|
+
export const cardOf = (board, number, columns = DEFAULT_COLUMNS) => {
|
|
503
|
+
const item = board.items.get(number);
|
|
504
|
+
if (!item)
|
|
505
|
+
return null;
|
|
506
|
+
const status = item.status === null
|
|
507
|
+
? null
|
|
508
|
+
: (statusOfColumn(item.status, columns) ?? "Unmapped");
|
|
509
|
+
return { status, updatedAt: item.updatedAt };
|
|
510
|
+
};
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/** A changed file under GitHub's own field names, which the commands under
|
|
3
|
+
* `auto-merge.commands` have always been handed. */
|
|
4
|
+
export type ChangedFile = {
|
|
5
|
+
filename: string;
|
|
6
|
+
previous_filename?: string;
|
|
7
|
+
status?: string;
|
|
8
|
+
};
|
|
9
|
+
/** The code host's changed files under those names. */
|
|
10
|
+
export declare const inGithubNames: (files: {
|
|
11
|
+
path: string;
|
|
12
|
+
previousPath?: string;
|
|
13
|
+
status: string;
|
|
14
|
+
}[]) => ChangedFile[];
|
|
15
|
+
/** The two merge labels. The merge-policy workflow applies one and removes the
|
|
16
|
+
* other; only "merge: automatic" turns auto-merge on. */
|
|
17
|
+
export declare const AUTOMATIC = "merge: automatic";
|
|
18
|
+
export declare const MANUAL = "merge: manual";
|
|
19
|
+
export type Risk = {
|
|
20
|
+
risk: typeof AUTOMATIC | typeof MANUAL;
|
|
21
|
+
reasons: string[];
|
|
22
|
+
};
|
|
23
|
+
export type Policy = {
|
|
24
|
+
allow: readonly string[];
|
|
25
|
+
deny: readonly string[];
|
|
26
|
+
};
|
|
27
|
+
/** The decision from the changed paths alone: a factory file, then deny,
|
|
28
|
+
* then anything outside allow, holds the pull request. A renamed file is
|
|
29
|
+
* checked under both names. */
|
|
30
|
+
export declare function classify(files: ChangedFile[], policy: Policy): Risk;
|
|
31
|
+
/** What a command under auto-merge.commands is given on its standard input. */
|
|
32
|
+
export type CommandInput = {
|
|
33
|
+
repository: string;
|
|
34
|
+
pull: number;
|
|
35
|
+
base: string;
|
|
36
|
+
head: string;
|
|
37
|
+
files: ChangedFile[];
|
|
38
|
+
};
|
|
39
|
+
export type CommandResult = {
|
|
40
|
+
command: string;
|
|
41
|
+
status: number | null;
|
|
42
|
+
output: string;
|
|
43
|
+
ran: boolean;
|
|
44
|
+
};
|
|
45
|
+
/** Runs one command from the current directory, the root of the checkout
|
|
46
|
+
* the workflow made, with the pull request as JSON on its standard input. */
|
|
47
|
+
export declare function runCommand(command: string, input: CommandInput): CommandResult;
|
|
48
|
+
/** Exit 0 allows the merge. Anything else holds it, with what the command
|
|
49
|
+
* printed as the reason, or the command's name when it printed nothing. */
|
|
50
|
+
export declare function commandReasons(results: CommandResult[]): string[];
|
|
51
|
+
/** The path decision, then each command's, as one. */
|
|
52
|
+
export declare function decide(paths: Risk, commandHolds: string[]): Risk;
|
|
53
|
+
/** The description of the "Who merges" commit status: what happens, and why,
|
|
54
|
+
* on one line. GitHub cuts a status description at 140 characters. */
|
|
55
|
+
export declare function statusLine({ risk, reasons }: Risk): string;
|
|
56
|
+
/** What the merge-policy workflow needs: the label to set, the one to remove,
|
|
57
|
+
* whether auto-merge goes on, and the status line. */
|
|
58
|
+
export declare function workflowOutput(result: Risk): {
|
|
59
|
+
other: string;
|
|
60
|
+
automatic: boolean;
|
|
61
|
+
status: string;
|
|
62
|
+
risk: typeof AUTOMATIC | typeof MANUAL;
|
|
63
|
+
reasons: string[];
|
|
64
|
+
};
|
|
65
|
+
/** `factory merge-policy N`. */
|
|
66
|
+
export declare function run(argv: string[]): Promise<number>;
|