@open-tomato/rafa 0.46.0 → 0.48.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/README.md +70 -37
- package/dist/adapters/logger/settings.d.ts +2 -2
- package/dist/bugs/places.d.ts +1 -1
- package/dist/bugs/record.d.ts +1 -1
- package/dist/bundled/skills/dev-planner/SKILL.md +2 -2
- package/dist/cli.js +73457 -72996
- package/dist/config/index.d.ts +5 -0
- package/dist/config/index.js +6 -4
- package/dist/config/shape.d.ts +20 -15
- package/dist/config/templates.d.ts +64 -0
- package/dist/config-registry.d.ts +21 -12
- package/dist/config-schema-board-project.d.ts +3 -3
- package/dist/config-schema-bugs.d.ts +3 -3
- package/dist/config-schema-checks.d.ts +114 -0
- package/dist/config-schema-errors.d.ts +3 -3
- package/dist/config-schema-features.d.ts +4 -4
- package/dist/config-schema-hub.d.ts +6 -4
- package/dist/config-schema-issues.d.ts +2 -2
- package/dist/config-schema-logger.d.ts +3 -3
- package/dist/config-schema-loop-continue.d.ts +3 -3
- package/dist/config-schema-loop-retries.d.ts +4 -4
- package/dist/config-schema-release.d.ts +23 -24
- package/dist/config-schema-tests.d.ts +35 -27
- package/dist/config-schema-triage.d.ts +3 -3
- package/dist/config-schema-wrap-up.d.ts +4 -4
- package/dist/core/command/command.d.ts +1 -1
- package/dist/core/command/confirm.d.ts +11 -5
- package/dist/core/command/global-flags.d.ts +25 -0
- package/dist/core/command/index.d.ts +47 -23
- package/dist/core/command/registry-types.d.ts +4 -4
- package/dist/core/command/shared-flags.d.ts +40 -0
- package/dist/core/command/types.d.ts +3 -2
- package/dist/core/config/branch-template.d.ts +2 -0
- package/dist/core/config/config-items.d.ts +1 -1
- package/dist/core/config/config-load-module.d.ts +43 -0
- package/dist/core/config/config-load.d.ts +43 -12
- package/dist/core/config/config-origins.d.ts +31 -30
- package/dist/core/config/config-schema.d.ts +11 -0
- package/dist/core/config/config-sections.d.ts +15 -14
- package/dist/core/config/config.d.ts +90 -25
- package/dist/core/config/core-section.d.ts +1 -1
- package/dist/core/config/default-routing.d.ts +1 -1
- package/dist/core/config/index.d.ts +14 -10
- package/dist/core/config/merge-method.d.ts +40 -0
- package/dist/core/config/scope.d.ts +2 -2
- package/dist/core/config/section.d.ts +81 -1
- package/dist/core/config/sections.d.ts +17 -6
- package/dist/core/git/gh-runner.d.ts +1 -1
- package/dist/core/git/git.d.ts +34 -0
- package/dist/core/git/index.d.ts +13 -8
- package/dist/core/loop/claude.d.ts +11 -5
- package/dist/core/loop/hop-record.d.ts +6 -6
- package/dist/core/loop/index.d.ts +9 -8
- package/dist/core/loop/session-record-parse.d.ts +9 -2
- package/dist/core/loop/sessions.d.ts +23 -11
- package/dist/core/loop/suite-failure.d.ts +8 -6
- package/dist/core/output/active.d.ts +1 -1
- package/dist/core/plan/block-reader.d.ts +1 -1
- package/dist/core/runtime/identity.d.ts +13 -0
- package/dist/core/runtime/index.d.ts +12 -6
- package/dist/effort/store/check-rows.d.ts +1 -1
- package/dist/effort/store/commit-stats.d.ts +1 -1
- package/dist/effort/store/index.js +7 -8
- package/dist/effort/store/merge-commit-gaps.d.ts +1 -1
- package/dist/effort/store/plan-stubs.d.ts +1 -1
- package/dist/effort/store/session-row-types.d.ts +2 -2
- package/dist/errors/rafa-codes.d.ts +1 -1
- package/dist/index-2xzkzwm6.js +670 -0
- package/dist/index-ajv88fkm.js +448 -0
- package/dist/{index-ykggr043.js → index-fpgmdmww.js} +13 -5
- package/dist/index-g91ys6kw.js +249 -0
- package/dist/{index-cy98y87p.js → index-jx3x70xh.js} +1111 -638
- package/dist/{index-gvek4r8m.js → index-m672ptpg.js} +84 -26
- package/dist/{index-39kbcw68.js → index-w5qbpdtp.js} +415 -842
- package/dist/{index-gqz4jn6j.js → index-z4r20zwr.js} +8974 -11438
- package/dist/{index-j4k2vdz3.js → index-zsak0jy6.js} +124 -290
- package/dist/index.js +24940 -18766
- package/dist/learning/index.js +221 -12
- package/dist/plan/index.js +10 -9
- package/dist/ports/index.d.ts +7 -7
- package/dist/ports/learning.d.ts +5 -4
- package/dist/ports/spec-review.d.ts +1 -1
- package/dist/ready-gax3hhtt.js +241 -0
- package/dist/release-templates/release-bot-fragment.yml +6 -6
- package/dist/release-templates/release-publish.yml +8 -8
- package/dist/release-templates/release-settle.yml +8 -7
- package/dist/release-templates/release-tag.yml +8 -7
- package/package.json +53 -2
- package/dist/index-77ajfffn.js +0 -223
- package/dist/index-jh1r4kcn.js +0 -1067
- package/dist/index-z1w83f81.js +0 -4
- package/dist/pr/checks.d.ts +0 -133
- package/dist/pr/types.d.ts +0 -422
- package/dist/ready-4f8edezt.js +0 -2016
package/dist/index-z1w83f81.js
DELETED
package/dist/pr/checks.d.ts
DELETED
|
@@ -1,133 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The check-row readers of a pull request: raw `gh pr checks` output in,
|
|
3
|
-
* one verdict out.
|
|
4
|
-
*
|
|
5
|
-
* A PR is not finished until CI has spoken about it, and two failure
|
|
6
|
-
* shapes made that worth automating rather than leaving to the session's
|
|
7
|
-
* judgement:
|
|
8
|
-
*
|
|
9
|
-
* - A CONFLICTING PR schedules no workflow run at all, because GitHub
|
|
10
|
-
* cannot build `refs/pull/<n>/merge` for a branch that does not merge
|
|
11
|
-
* cleanly. The loop would report a finished plan whose code had never
|
|
12
|
-
* been through CI once.
|
|
13
|
-
* - A resolved conflict can still red the whole battery at its first
|
|
14
|
-
* step (a lockfile out of step with the merged manifests fails
|
|
15
|
-
* `bun install --frozen-lockfile`, and nothing downstream runs).
|
|
16
|
-
*
|
|
17
|
-
* Both are invisible from inside the session that pushed.
|
|
18
|
-
*
|
|
19
|
-
* ## Zero rows is two readings, and the head's age tells them apart
|
|
20
|
-
*
|
|
21
|
-
* GitHub registers a push's runs some seconds after the push, so a poll
|
|
22
|
-
* in that gap reads zero rows off a pull request whose checks are about
|
|
23
|
-
* to appear. Zero rows on an OLD head is the settled reading above: no
|
|
24
|
-
* run is coming. So a caller that knows when the head was committed
|
|
25
|
-
* hands that time over ({@link WaitOptions.headCommittedAtMs}), and zero
|
|
26
|
-
* rows on a head younger than {@link FIRST_CHECK_GRACE_MS} is polled
|
|
27
|
-
* again like a pending reading. A caller that hands over no time gets
|
|
28
|
-
* `none` on the first poll, as every caller did before the grace
|
|
29
|
-
* existed: the loop's CI gate and `pr triage --resolve` hand over none.
|
|
30
|
-
*
|
|
31
|
-
* The time is the head commit's COMMITTED date, which is not the push
|
|
32
|
-
* time: a commit made an hour ago and pushed just now reads as old and
|
|
33
|
-
* gets no grace. A provider answers a committed date and no push time,
|
|
34
|
-
* and the wrong direction of that error is the cheap one, since it is
|
|
35
|
-
* the behaviour there was before.
|
|
36
|
-
*
|
|
37
|
-
* Everything here is pure: the only effect {@link waitForChecks} has is
|
|
38
|
-
* the `probe` handed to it, and its clock and its wait are injected too,
|
|
39
|
-
* so the polling logic is testable without a network or a timer. The
|
|
40
|
-
* `gh` invocations that feed it live with the rest of the port, not
|
|
41
|
-
* here, which is what keeps `checks.test.ts` free of a process spawn.
|
|
42
|
-
*
|
|
43
|
-
* {@link waitForChecks} polls ROWS rather than stdout, so the poll runs
|
|
44
|
-
* over `PullRequests.checks` (`./types.ts`) without either side naming
|
|
45
|
-
* the CLI. {@link parseChecks} is what turns one provider's stdout into
|
|
46
|
-
* those rows, and the `gh` adapter is its only caller.
|
|
47
|
-
*
|
|
48
|
-
* The row type, the verdict type, {@link verdictOf} and `failingRows`
|
|
49
|
-
* are core's (`packages/rafa/src/effort/store/check-rows.ts`), where the store's plan
|
|
50
|
-
* CI writer reads them; this file re-exports them under the same names.
|
|
51
|
-
*/
|
|
52
|
-
import type { CheckOutcome, CheckRow, ChecksVerdict } from '@open-tomato/rafa/store/check-rows';
|
|
53
|
-
export type { CheckOutcome, CheckRow, ChecksVerdict } from '@open-tomato/rafa/store/check-rows';
|
|
54
|
-
export { failingRows, verdictOf } from '@open-tomato/rafa/store/check-rows';
|
|
55
|
-
/**
|
|
56
|
-
* Maps a GitHub check state onto an outcome.
|
|
57
|
-
*
|
|
58
|
-
* An UNRECOGNISED state counts as pending on purpose: the alternative is
|
|
59
|
-
* declaring a run green on a state nobody classified, and a wrong green
|
|
60
|
-
* here lands a plan whose CI never agreed. Waiting is recoverable — the
|
|
61
|
-
* deadline ends it and the raw state is printed in the summary.
|
|
62
|
-
*/
|
|
63
|
-
export declare function classifyState(state: string): CheckOutcome;
|
|
64
|
-
/**
|
|
65
|
-
* Parses `gh pr checks --json name,state,link` output into rows.
|
|
66
|
-
*
|
|
67
|
-
* Returns an empty list for anything that is not a JSON array — `gh`
|
|
68
|
-
* writes a plain `no checks reported` message and exits non-zero when a
|
|
69
|
-
* PR has none, and that is a verdict here rather than an error.
|
|
70
|
-
*/
|
|
71
|
-
export declare function parseChecks(stdout: string): CheckRow[];
|
|
72
|
-
/** One line per check, for the console and for a repair prompt. */
|
|
73
|
-
export declare function formatRows(rows: readonly CheckRow[]): string;
|
|
74
|
-
/**
|
|
75
|
-
* How long after a head commit zero rows still reads as "no check has
|
|
76
|
-
* registered yet" rather than "no check is coming": two minutes.
|
|
77
|
-
*
|
|
78
|
-
* Measured from the head commit's committed date, by the clock
|
|
79
|
-
* {@link waitForChecks} was handed. It is a ceiling on one wait as well:
|
|
80
|
-
* a head dated ahead of that clock is held no longer than this from the
|
|
81
|
-
* wait's own first poll.
|
|
82
|
-
*/
|
|
83
|
-
export declare const FIRST_CHECK_GRACE_MS = 120000;
|
|
84
|
-
export interface WaitOptions {
|
|
85
|
-
/**
|
|
86
|
-
* The rows of one poll. A caller on the port hands
|
|
87
|
-
* `PullRequests.checks` here, and a caller holding raw
|
|
88
|
-
* `gh pr checks --json ...` stdout hands {@link parseChecks} of it.
|
|
89
|
-
*/
|
|
90
|
-
probe: () => Promise<readonly CheckRow[]>;
|
|
91
|
-
timeoutMs: number;
|
|
92
|
-
intervalMs: number;
|
|
93
|
-
/** Injected for tests; defaults to the real clock. */
|
|
94
|
-
now?: () => number;
|
|
95
|
-
/** Injected for tests; defaults to a real timer. */
|
|
96
|
-
sleep?: (ms: number) => Promise<void>;
|
|
97
|
-
/**
|
|
98
|
-
* Called after every poll, for progress output. The verdict is the one
|
|
99
|
-
* the wait acts on, so a poll of zero rows the grace holds is reported
|
|
100
|
-
* `pending`, which is why it is polled again.
|
|
101
|
-
*/
|
|
102
|
-
onPoll?: (rows: readonly CheckRow[], verdict: ChecksVerdict, elapsedMs: number) => void;
|
|
103
|
-
/**
|
|
104
|
-
* When the pull request's head was committed, in the milliseconds
|
|
105
|
-
* `now` answers in. Handed over, zero rows on a head younger than
|
|
106
|
-
* {@link FIRST_CHECK_GRACE_MS} is polled again; left out, or a value
|
|
107
|
-
* that is no finite number, zero rows ends `none` on the first poll.
|
|
108
|
-
*/
|
|
109
|
-
headCommittedAtMs?: number;
|
|
110
|
-
}
|
|
111
|
-
export interface WaitResult {
|
|
112
|
-
/** `timeout` means the deadline passed while checks were still running. */
|
|
113
|
-
verdict: ChecksVerdict | 'timeout';
|
|
114
|
-
rows: readonly CheckRow[];
|
|
115
|
-
elapsedMs: number;
|
|
116
|
-
polls: number;
|
|
117
|
-
}
|
|
118
|
-
/**
|
|
119
|
-
* Polls a PR's checks until they settle, the deadline passes, or the PR
|
|
120
|
-
* reports no checks at all.
|
|
121
|
-
*
|
|
122
|
-
* `none` returns rather than waiting out the deadline: a PR with no
|
|
123
|
-
* checks is conflicting, has no workflow matching its changed paths, or
|
|
124
|
-
* was pushed so recently that none has registered. Only the last
|
|
125
|
-
* resolves by waiting, and only for {@link FIRST_CHECK_GRACE_MS}, so
|
|
126
|
-
* zero rows is polled again while {@link WaitOptions.headCommittedAtMs}
|
|
127
|
-
* says the head is that young and ends `none` otherwise. The caller
|
|
128
|
-
* tells the first two apart, since only it knows the merge state.
|
|
129
|
-
*
|
|
130
|
-
* A deadline that passes inside the grace ends `timeout`, with no rows,
|
|
131
|
-
* as it does for any reading that was still being polled.
|
|
132
|
-
*/
|
|
133
|
-
export declare function waitForChecks(options: WaitOptions): Promise<WaitResult>;
|
package/dist/pr/types.d.ts
DELETED
|
@@ -1,422 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The pull request port: what every pull request provider answers, and
|
|
3
|
-
* the record shapes it answers with.
|
|
4
|
-
*
|
|
5
|
-
* Until this port, the wrap-up stage reached `gh` directly through
|
|
6
|
-
* `src/utils/pr.ts` — deleted now — so the only way to hold a caller to
|
|
7
|
-
* a behaviour was to run `gh`. This port is the seam that replaced it:
|
|
8
|
-
* an adapter over the GitHub CLI implements it, a second provider later
|
|
9
|
-
* is another adapter, and a caller typed against {@link PullRequests}
|
|
10
|
-
* names neither.
|
|
11
|
-
*
|
|
12
|
-
* ## What the port owes, and what it leaves out
|
|
13
|
-
*
|
|
14
|
-
* - Every member answers a promise, because the `gh` adapter spawns a
|
|
15
|
-
* process for each one. A provider that could answer synchronously
|
|
16
|
-
* still answers a resolved promise rather than widening the port.
|
|
17
|
-
* - A pull request a READ is looking for and does not find is `null`,
|
|
18
|
-
* never a throw: the current branch having no open PR is the
|
|
19
|
-
* ordinary first case of `pr current`, not a failure. A provider
|
|
20
|
-
* that could not be ASKED — no network, no authentication, a command
|
|
21
|
-
* that did not run — throws, so an outage never reads as an empty
|
|
22
|
-
* repository. A WRITE is the other way round
|
|
23
|
-
* ({@link PullRequests.editBody}): it was handed the pull request to
|
|
24
|
-
* act on rather than discovering it, so a number nothing answers for
|
|
25
|
-
* throws there. {@link PullRequests.changedFiles} and
|
|
26
|
-
* {@link PullRequests.reviews} throw on an absent pull request too:
|
|
27
|
-
* their caller, the owner gate, was handed the number it reads, and
|
|
28
|
-
* an empty list would read as "touches nothing" or "nobody has
|
|
29
|
-
* reviewed" where the truth is "could not be read".
|
|
30
|
-
* {@link PullRequests.workflowCount} is the one read
|
|
31
|
-
* that answers null on ANY failure rather than throwing: its null is
|
|
32
|
-
* not an empty answer but the riskier one, read by the caller the
|
|
33
|
-
* same as "workflows exist", so an outage cannot pass for "this
|
|
34
|
-
* repository has no workflow" and a throw would buy nothing.
|
|
35
|
-
* - The states GitHub spells in its own words are narrowed here
|
|
36
|
-
* ({@link PullRequestState}, {@link Mergeability}) so a caller
|
|
37
|
-
* switches on a closed set, while the words that have no closed set
|
|
38
|
-
* worth inventing — `mergeStateStatus`, a check's `state` — stay
|
|
39
|
-
* verbatim on the record, because an unrecognised one has to stay
|
|
40
|
-
* reportable rather than be flattened into a wrong verdict. That is
|
|
41
|
-
* the same rule {@link CheckRow} already keeps for check states.
|
|
42
|
-
* - The check-row readers are NOT the port's. `parseChecks`,
|
|
43
|
-
* `verdictOf` and `waitForChecks` in `./checks.js` are pure, they
|
|
44
|
-
* work on any provider's rows, and a provider re-implementing them
|
|
45
|
-
* could disagree with the wrap-up gate about what green means. The
|
|
46
|
-
* port answers rows and the verdict over them ({@link ChecksReading});
|
|
47
|
-
* the waiting is done by the caller around {@link PullRequests.checks}.
|
|
48
|
-
* - Nothing is cached. Each call asks the provider, because a triage
|
|
49
|
-
* that acted on a stale reading would act on a pull request that has
|
|
50
|
-
* already moved.
|
|
51
|
-
* - {@link PullRequests.close} closes WITHOUT merging, and decides
|
|
52
|
-
* nothing: whether the pull request is open, what its closing leaves
|
|
53
|
-
* open and whether a person agreed are its caller's to have read and
|
|
54
|
-
* asked first.
|
|
55
|
-
*
|
|
56
|
-
* ## Why the members are function-typed properties
|
|
57
|
-
*
|
|
58
|
-
* TypeScript compares a method signature's parameters bivariantly and a
|
|
59
|
-
* function-typed property's contravariantly, so only the property
|
|
60
|
-
* spelling refuses an adapter that narrows a parameter. `merge` is the
|
|
61
|
-
* member that makes this matter: an adapter implementing
|
|
62
|
-
* `merge(n: number, method: 'squash')` would compile against a method
|
|
63
|
-
* signature and then be handed `'rebase'` by a caller reading
|
|
64
|
-
* `pr.mergeMethod` out of the config. Measured in `types.test.ts`, which
|
|
65
|
-
* holds that refusal (TS2322) and, as its control, the same port spelled
|
|
66
|
-
* with method signatures accepting the same adapter. The store port
|
|
67
|
-
* (`packages/rafa/src/effort/store/types.ts`) is spelled this way for the same reason.
|
|
68
|
-
*/
|
|
69
|
-
import type { CheckRow, ChecksVerdict } from './checks.js';
|
|
70
|
-
export type { CheckRow, ChecksVerdict } from './checks.js';
|
|
71
|
-
/**
|
|
72
|
-
* How a merge is made. GitHub's three, and no other: `gh pr merge`
|
|
73
|
-
* takes exactly `--squash`, `--merge` and `--rebase`, and a provider
|
|
74
|
-
* that cannot do one of them refuses the call rather than substituting
|
|
75
|
-
* another, which would rewrite history the operator did not ask for.
|
|
76
|
-
*/
|
|
77
|
-
export type MergeMethod = 'squash' | 'merge' | 'rebase';
|
|
78
|
-
/**
|
|
79
|
-
* The merge methods, in the order a refusal lists them.
|
|
80
|
-
*
|
|
81
|
-
* A runtime value beside the type so the config reader and the
|
|
82
|
-
* `--method` flag validate against one list rather than each spelling
|
|
83
|
-
* the three words again. Frozen: a caller that pushed onto it would
|
|
84
|
-
* change what every later refusal says it accepts.
|
|
85
|
-
*/
|
|
86
|
-
export declare const MERGE_METHODS: readonly MergeMethod[];
|
|
87
|
-
/** Whether a value is one of {@link MERGE_METHODS}. */
|
|
88
|
-
export declare function isMergeMethod(value: unknown): value is MergeMethod;
|
|
89
|
-
/**
|
|
90
|
-
* Where a pull request stands. `merged` is its own member rather than a
|
|
91
|
-
* flag on `closed`: a merged PR and an abandoned one are the same state
|
|
92
|
-
* to GitHub's `closed` and opposite answers to every caller here.
|
|
93
|
-
*/
|
|
94
|
-
export type PullRequestState = 'open' | 'closed' | 'merged';
|
|
95
|
-
/**
|
|
96
|
-
* Whether the head merges into the base.
|
|
97
|
-
*
|
|
98
|
-
* `unknown` is GitHub's own answer while it computes the merge commit,
|
|
99
|
-
* and it is kept rather than resolved to a guess: a caller waits or
|
|
100
|
-
* reports it, and `merge` refuses on it, where treating it as mergeable
|
|
101
|
-
* would send a merge GitHub is about to refuse anyway.
|
|
102
|
-
*/
|
|
103
|
-
export type Mergeability = 'mergeable' | 'conflicting' | 'unknown';
|
|
104
|
-
/** Who opened a pull request, or wrote a comment on it. */
|
|
105
|
-
export interface PullRequestAuthor {
|
|
106
|
-
/** The account's login, as trust and the dependabot rule read it. */
|
|
107
|
-
readonly login: string;
|
|
108
|
-
/** True for a bot account, which `dependabot[bot]` is. */
|
|
109
|
-
readonly isBot: boolean;
|
|
110
|
-
}
|
|
111
|
-
/**
|
|
112
|
-
* One pull request as a list answers it: enough for a line of `pr list`
|
|
113
|
-
* or `pr current`, and for choosing which PR an action acts on.
|
|
114
|
-
*/
|
|
115
|
-
export interface PullRequestSummary {
|
|
116
|
-
readonly number: number;
|
|
117
|
-
readonly title: string;
|
|
118
|
-
readonly url: string;
|
|
119
|
-
readonly state: PullRequestState;
|
|
120
|
-
/** The branch the PR is FROM, which is the branch a caller matches on. */
|
|
121
|
-
readonly headRefName: string;
|
|
122
|
-
/** The branch the PR is INTO. */
|
|
123
|
-
readonly baseRefName: string;
|
|
124
|
-
readonly author: PullRequestAuthor;
|
|
125
|
-
/**
|
|
126
|
-
* True when the head is on a fork. Such a PR cannot be checked out
|
|
127
|
-
* into a worktree of this repository, so `triage --resolve` refuses it.
|
|
128
|
-
*/
|
|
129
|
-
readonly isCrossRepository: boolean;
|
|
130
|
-
/** When the PR last moved, ISO 8601, as the 72-hour selection rule reads it. */
|
|
131
|
-
readonly updatedAt: string;
|
|
132
|
-
}
|
|
133
|
-
/**
|
|
134
|
-
* One issue a pull request closes when it merges, as the provider links
|
|
135
|
-
* the two.
|
|
136
|
-
*
|
|
137
|
-
* The provider's link, not the body's words: on GitHub it is
|
|
138
|
-
* `closingIssuesReferences`, which holds the issues a closing keyword in
|
|
139
|
-
* the body names (measured on `open-tomato/rafa#763`, whose sixteen
|
|
140
|
-
* `Closes #<n>` lines are its sixteen references) and, by GitHub's
|
|
141
|
-
* documentation, the ones linked by hand from the pull request's
|
|
142
|
-
* Development panel — so it can hold an issue the body never mentions.
|
|
143
|
-
* Reading the body's keywords is `closedIssuesIn` in
|
|
144
|
-
* `src/board/roadmap.ts`, a separate reading a caller compares this one
|
|
145
|
-
* with.
|
|
146
|
-
*
|
|
147
|
-
* An issue can live in another repository — `GoogleCloudPlatform/scion#2453`
|
|
148
|
-
* closes eight issues of the fork `ptone/scion` — so
|
|
149
|
-
* {@link ClosingIssue.repository} is always written, and a caller that
|
|
150
|
-
* matches on {@link ClosingIssue.number} alone checks the repository
|
|
151
|
-
* first.
|
|
152
|
-
*/
|
|
153
|
-
export interface ClosingIssue {
|
|
154
|
-
/** The issue's number in its own repository. */
|
|
155
|
-
readonly number: number;
|
|
156
|
-
/** The issue's repository, `owner/name`. */
|
|
157
|
-
readonly repository: string;
|
|
158
|
-
/** The issue's own URL. */
|
|
159
|
-
readonly url: string;
|
|
160
|
-
}
|
|
161
|
-
/**
|
|
162
|
-
* One pull request in full: the summary widened with what only a
|
|
163
|
-
* per-PR read answers.
|
|
164
|
-
*/
|
|
165
|
-
export interface PullRequestDetail extends PullRequestSummary {
|
|
166
|
-
/** The PR body. Empty string when it has none, never null. */
|
|
167
|
-
readonly body: string;
|
|
168
|
-
/** The head commit, which a triage comment is pinned to. */
|
|
169
|
-
readonly headRefOid: string;
|
|
170
|
-
/**
|
|
171
|
-
* When the head commit was committed, ISO 8601, as the provider
|
|
172
|
-
* answers it; null when it does not. It is the commit's own date and
|
|
173
|
-
* NOT the push time, so a commit made earlier and pushed just now
|
|
174
|
-
* reads as old. `rafa pr wait` reads it for the grace a young head
|
|
175
|
-
* gets before zero checks reads as none (`FIRST_CHECK_GRACE_MS` in
|
|
176
|
-
* `./checks.js`), and null means no grace.
|
|
177
|
-
*/
|
|
178
|
-
readonly headCommittedAt: string | null;
|
|
179
|
-
readonly mergeable: Mergeability;
|
|
180
|
-
/**
|
|
181
|
-
* GitHub's `mergeStateStatus` verbatim — `CLEAN`, `BLOCKED`, `DIRTY`,
|
|
182
|
-
* `BEHIND`, `UNKNOWN` and whatever it adds next. Kept unnarrowed so a
|
|
183
|
-
* refusal can name the word GitHub used.
|
|
184
|
-
*/
|
|
185
|
-
readonly mergeStateStatus: string;
|
|
186
|
-
/** Label names, as the readiness gate and triage read them. */
|
|
187
|
-
readonly labels: readonly string[];
|
|
188
|
-
/**
|
|
189
|
-
* The issues the PR closes on merge, in the provider's order — on
|
|
190
|
-
* `gh`, issue number ascending, not the order the body names them in
|
|
191
|
-
* (`open-tomato/rafa#763`). Empty when it closes none.
|
|
192
|
-
*/
|
|
193
|
-
readonly closes: readonly ClosingIssue[];
|
|
194
|
-
}
|
|
195
|
-
/**
|
|
196
|
-
* One merged pull request, as {@link PullRequests.listMerged} answers it:
|
|
197
|
-
* which head was merged, at which commit, and when.
|
|
198
|
-
*
|
|
199
|
-
* Only what telling a local branch's fate needs. `headRefOid` is the head
|
|
200
|
-
* commit the pull request was merged AT, which a squash merge leaves
|
|
201
|
-
* unreachable from the base, so a caller compares it with a local tip
|
|
202
|
-
* rather than asking git whether the branch is merged.
|
|
203
|
-
*/
|
|
204
|
-
export interface MergedPullRequest {
|
|
205
|
-
readonly number: number;
|
|
206
|
-
/** The branch the PR was FROM. Still answered after the branch is deleted. */
|
|
207
|
-
readonly headRefName: string;
|
|
208
|
-
/** The head commit when the PR was merged. */
|
|
209
|
-
readonly headRefOid: string;
|
|
210
|
-
/** When the PR was merged, ISO 8601. Never null: the PR is merged. */
|
|
211
|
-
readonly mergedAt: string;
|
|
212
|
-
}
|
|
213
|
-
/** A PR's checks, and the one verdict over them. */
|
|
214
|
-
export interface ChecksReading {
|
|
215
|
-
readonly rows: readonly CheckRow[];
|
|
216
|
-
/**
|
|
217
|
-
* `none` when the PR has no checks at all, which a conflict produces,
|
|
218
|
-
* and so does a head pushed before its first check registered.
|
|
219
|
-
*/
|
|
220
|
-
readonly verdict: ChecksVerdict;
|
|
221
|
-
}
|
|
222
|
-
/**
|
|
223
|
-
* One comment on a pull request — the shape the triage marker comment is
|
|
224
|
-
* read back from and edited through.
|
|
225
|
-
*/
|
|
226
|
-
export interface PullRequestComment {
|
|
227
|
-
/** The provider's own id, which {@link PullRequests.editComment} takes. */
|
|
228
|
-
readonly id: string;
|
|
229
|
-
readonly author: PullRequestAuthor;
|
|
230
|
-
readonly body: string;
|
|
231
|
-
/** ISO 8601. A rerun reports when the comment it found was written. */
|
|
232
|
-
readonly updatedAt: string;
|
|
233
|
-
/** The comment's own URL, for the line that points at it. */
|
|
234
|
-
readonly url: string;
|
|
235
|
-
}
|
|
236
|
-
/**
|
|
237
|
-
* One review submitted on a pull request, as the owner gate reads it:
|
|
238
|
-
* who reviewed, what they said, and when.
|
|
239
|
-
*
|
|
240
|
-
* Only what telling "the latest review of this login" and whether it
|
|
241
|
-
* approves needs; the review's body, comments and commit are not
|
|
242
|
-
* answered.
|
|
243
|
-
*/
|
|
244
|
-
export interface PullRequestReview {
|
|
245
|
-
/** The reviewer's login. */
|
|
246
|
-
readonly login: string;
|
|
247
|
-
/**
|
|
248
|
-
* GitHub's review state verbatim — `APPROVED`, `CHANGES_REQUESTED`,
|
|
249
|
-
* `COMMENTED`, `DISMISSED` and whatever it adds next. Kept unnarrowed,
|
|
250
|
-
* as `mergeStateStatus` is, so a caller compares it with `APPROVED`
|
|
251
|
-
* and an unrecognised word is simply not an approval.
|
|
252
|
-
*/
|
|
253
|
-
readonly state: string;
|
|
254
|
-
/** When the review was submitted, ISO 8601. */
|
|
255
|
-
readonly submittedAt: string;
|
|
256
|
-
}
|
|
257
|
-
/**
|
|
258
|
-
* A pull request to open, as {@link PullRequests.create} takes it.
|
|
259
|
-
*
|
|
260
|
-
* The head is a branch already pushed to the repository the provider
|
|
261
|
-
* resolves: opening one never pushes, forks or asks where to push, so
|
|
262
|
-
* the branch and its commit are the caller's to have put there first.
|
|
263
|
-
*/
|
|
264
|
-
export interface PullRequestDraft {
|
|
265
|
-
/** The branch the PR is FROM, already on the remote. */
|
|
266
|
-
readonly head: string;
|
|
267
|
-
/** The branch the PR is INTO. */
|
|
268
|
-
readonly base: string;
|
|
269
|
-
readonly title: string;
|
|
270
|
-
/** The PR body. An empty one is a body, and opens a PR with none. */
|
|
271
|
-
readonly body: string;
|
|
272
|
-
}
|
|
273
|
-
/**
|
|
274
|
-
* What a merge did.
|
|
275
|
-
*
|
|
276
|
-
* `merged` false is a merge the provider REFUSED — not green, not
|
|
277
|
-
* mergeable, a protected base — and `detail` is what it said, so the
|
|
278
|
-
* caller prints the provider's reason rather than a guess. A merge that
|
|
279
|
-
* could not be attempted at all throws instead, because the clean-up
|
|
280
|
-
* that follows a merge must never run on an unread outcome.
|
|
281
|
-
*/
|
|
282
|
-
export interface MergeOutcome {
|
|
283
|
-
readonly merged: boolean;
|
|
284
|
-
/** Non-empty either way: what the provider reported. */
|
|
285
|
-
readonly detail: string;
|
|
286
|
-
}
|
|
287
|
-
/** How {@link PullRequests.close} closes a pull request. */
|
|
288
|
-
export interface ClosePullRequestOptions {
|
|
289
|
-
/**
|
|
290
|
-
* True to delete the head branch with the close. Required rather than
|
|
291
|
-
* defaulted, so no caller deletes a branch, or keeps one, by leaving a
|
|
292
|
-
* key out.
|
|
293
|
-
*/
|
|
294
|
-
readonly deleteBranch: boolean;
|
|
295
|
-
}
|
|
296
|
-
/**
|
|
297
|
-
* A pull request provider.
|
|
298
|
-
*
|
|
299
|
-
* Every member is a function-typed property, for the reason in the
|
|
300
|
-
* module note. Nothing here touches git: switching branches, pulling and
|
|
301
|
-
* deleting branches after a merge are the merge command's own steps, so
|
|
302
|
-
* a provider is only ever the remote half.
|
|
303
|
-
*/
|
|
304
|
-
export interface PullRequests {
|
|
305
|
-
/** The provider's name, as a refusal and `doctor` spell it. */
|
|
306
|
-
readonly kind: 'gh';
|
|
307
|
-
/**
|
|
308
|
-
* The open PR whose head is this branch, or null when there is none.
|
|
309
|
-
* The first of several, when a branch somehow has more than one.
|
|
310
|
-
*/
|
|
311
|
-
findOpen: (branch: string) => Promise<PullRequestSummary | null>;
|
|
312
|
-
/** Every open PR, newest first. */
|
|
313
|
-
list: () => Promise<readonly PullRequestSummary[]>;
|
|
314
|
-
/**
|
|
315
|
-
* The most recent merged PRs, newest CREATED first — not newest merged,
|
|
316
|
-
* which is `gh`'s own order — up to a fixed limit the provider names.
|
|
317
|
-
* A merged PR past that limit is not answered, so an absent head is
|
|
318
|
-
* "not among the recent merges" and never "never merged".
|
|
319
|
-
*/
|
|
320
|
-
listMerged: () => Promise<readonly MergedPullRequest[]>;
|
|
321
|
-
/** One PR in full, or null when the repository has no such PR. */
|
|
322
|
-
get: (number: number) => Promise<PullRequestDetail | null>;
|
|
323
|
-
/** The PR's checks now. One poll: the waiting is the caller's. */
|
|
324
|
-
checks: (number: number) => Promise<ChecksReading>;
|
|
325
|
-
/**
|
|
326
|
-
* The paths the PR changes, in the provider's order.
|
|
327
|
-
*
|
|
328
|
-
* The WHOLE list or a throw, never a part of it: a list short of the
|
|
329
|
-
* PR's own changed-file count throws, because an owner gate reading
|
|
330
|
-
* a partial list could find every path it saw at home and let through
|
|
331
|
-
* a path it never saw. An absent PR throws too; see the module note.
|
|
332
|
-
*/
|
|
333
|
-
changedFiles: (number: number) => Promise<readonly string[]>;
|
|
334
|
-
/**
|
|
335
|
-
* Every review submitted on the PR, in the provider's order, oldest
|
|
336
|
-
* first on `gh`. Throws when the provider could not be asked or the PR
|
|
337
|
-
* is absent, so a failed read never passes for "no reviews".
|
|
338
|
-
*/
|
|
339
|
-
reviews: (number: number) => Promise<readonly PullRequestReview[]>;
|
|
340
|
-
/** Opens the PR in a browser. */
|
|
341
|
-
browse: (number: number) => Promise<void>;
|
|
342
|
-
/** Merges the PR, or answers why the provider would not. */
|
|
343
|
-
merge: (number: number, method: MergeMethod) => Promise<MergeOutcome>;
|
|
344
|
-
/**
|
|
345
|
-
* Closes the PR WITHOUT merging it, leaving `comment` as its closing
|
|
346
|
-
* comment, and answers nothing.
|
|
347
|
-
*
|
|
348
|
-
* A WRITE, so every failure throws, an absent PR among them, for the
|
|
349
|
-
* reason {@link PullRequests.editBody} gives. The comment is required
|
|
350
|
-
* and never blank: a pull request closed unmerged says why. The head
|
|
351
|
-
* branch stays where it is unless `options.deleteBranch` is true.
|
|
352
|
-
* Whether the PR is still open is the caller's to have read: what a
|
|
353
|
-
* provider answers for one already closed or merged is not held here.
|
|
354
|
-
*/
|
|
355
|
-
close: (number: number, comment: string, options: ClosePullRequestOptions) => Promise<void>;
|
|
356
|
-
/**
|
|
357
|
-
* Opens a PR from `draft.head` into `draft.base`, answering it as
|
|
358
|
-
* opened.
|
|
359
|
-
*
|
|
360
|
-
* A WRITE, so every failure throws — a head with a PR already open
|
|
361
|
-
* into that base among them, since answering the one already there
|
|
362
|
-
* would hide that the caller did not look first. The head must
|
|
363
|
-
* already be pushed; see {@link PullRequestDraft}.
|
|
364
|
-
*/
|
|
365
|
-
create: (draft: PullRequestDraft) => Promise<PullRequestSummary>;
|
|
366
|
-
/**
|
|
367
|
-
* Replaces the PR's title and answers nothing. An absent PR throws,
|
|
368
|
-
* for the reason {@link PullRequests.editBody} gives.
|
|
369
|
-
*/
|
|
370
|
-
editTitle: (number: number, title: string) => Promise<void>;
|
|
371
|
-
/**
|
|
372
|
-
* Retargets the PR onto the branch `base` and answers nothing. An
|
|
373
|
-
* absent PR throws, for the reason {@link PullRequests.editBody}
|
|
374
|
-
* gives; nothing reads back what the edit wrote, so a caller that
|
|
375
|
-
* needs the new {@link PullRequestSummary.baseRefName} reads the PR
|
|
376
|
-
* again.
|
|
377
|
-
*/
|
|
378
|
-
editBase: (number: number, base: string) => Promise<void>;
|
|
379
|
-
/**
|
|
380
|
-
* Replaces the PR's own body — the description above the
|
|
381
|
-
* conversation, not a comment under it — and answers nothing.
|
|
382
|
-
*
|
|
383
|
-
* The body is written WHOLE, because a provider has no way to append
|
|
384
|
-
* one: the text to keep is what {@link PullRequests.get} already
|
|
385
|
-
* answered, and composing the new body out of it is the caller's.
|
|
386
|
-
*
|
|
387
|
-
* A pull request that is absent THROWS here, where
|
|
388
|
-
* {@link PullRequests.get} answers null. A caller writing a body has
|
|
389
|
-
* already chosen which pull request it is writing to, so a number
|
|
390
|
-
* nothing answers for is a fault, and an edit that silently wrote
|
|
391
|
-
* nowhere would lose the sentence it was carrying.
|
|
392
|
-
*/
|
|
393
|
-
editBody: (number: number, body: string) => Promise<void>;
|
|
394
|
-
/** Every comment on the PR, oldest first. */
|
|
395
|
-
comments: (number: number) => Promise<readonly PullRequestComment[]>;
|
|
396
|
-
/** Posts a comment, answering the comment as posted. */
|
|
397
|
-
comment: (number: number, body: string) => Promise<PullRequestComment>;
|
|
398
|
-
/**
|
|
399
|
-
* Replaces a comment's body, answering it as edited. One triage
|
|
400
|
-
* comment per PR, with its history in that comment's edits, is what
|
|
401
|
-
* this member is for.
|
|
402
|
-
*/
|
|
403
|
-
editComment: (id: string, body: string) => Promise<PullRequestComment>;
|
|
404
|
-
/**
|
|
405
|
-
* The failing log of one CI run, as the evidence a triage quotes.
|
|
406
|
-
* Empty string when the provider has no log for it.
|
|
407
|
-
*/
|
|
408
|
-
failedLog: (runId: string) => Promise<string>;
|
|
409
|
-
/**
|
|
410
|
-
* How many workflows the repository holds, or null when that could not
|
|
411
|
-
* be read.
|
|
412
|
-
*
|
|
413
|
-
* Zero is the one answer that means "nothing on the provider tests a
|
|
414
|
-
* pull request here". Null — a denied read, a missing repository, an
|
|
415
|
-
* outage, a payload that carries no count — must be read by the caller
|
|
416
|
-
* as the riskier case, workflows existing, and never as zero: a check
|
|
417
|
-
* that has not reported is ambiguous exactly when a workflow could
|
|
418
|
-
* still report it. The count is the whole repository's, not one page
|
|
419
|
-
* of it.
|
|
420
|
-
*/
|
|
421
|
-
workflowCount: () => Promise<number | null>;
|
|
422
|
-
}
|