@kana-ai/edgar-ext-github 0.1.4 → 0.1.6

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.
@@ -17,6 +17,7 @@ export declare const pushBranch: {
17
17
  repo: z.ZodString;
18
18
  branch: z.ZodOptional<z.ZodString>;
19
19
  to: z.ZodOptional<z.ZodString>;
20
+ suffix: z.ZodOptional<z.ZodString>;
20
21
  }, z.core.$strip>;
21
22
  output: z.ZodObject<{
22
23
  branch: z.ZodString;
@@ -49,6 +50,7 @@ export declare const openPullRequest: {
49
50
  exit_code: z.ZodNullable<z.ZodNumber>;
50
51
  pre_existing: z.ZodOptional<z.ZodBoolean>;
51
52
  runs: z.ZodOptional<z.ZodNumber>;
53
+ covered: z.ZodOptional<z.ZodArray<z.ZodString>>;
52
54
  }, z.core.$strip>>;
53
55
  }, z.core.$strip>>;
54
56
  not_verified: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -70,10 +72,13 @@ export declare const openPullRequest: {
70
72
  }, z.core.$strip>>;
71
73
  proof_passes: z.ZodOptional<z.ZodString>;
72
74
  related: z.ZodOptional<z.ZodUnion<readonly [z.ZodURL, z.ZodArray<z.ZodURL>]>>;
75
+ after: z.ZodOptional<z.ZodURL>;
76
+ first: z.ZodOptional<z.ZodString>;
73
77
  }, z.core.$strip>;
74
78
  output: z.ZodObject<{
75
79
  url: z.ZodString;
76
80
  number: z.ZodNumber;
81
+ commit: z.ZodOptional<z.ZodString>;
77
82
  }, z.core.$strip>;
78
83
  };
79
84
  /** The input and output of `close_pull_request`, which the engine calls with the output of the `open_pull_request` call that it undoes. The sweep adds `text`, the line that says why, when a person closed the card of the pull request. */
@@ -150,6 +155,7 @@ export declare const updatePullRequest: {
150
155
  exit_code: z.ZodNullable<z.ZodNumber>;
151
156
  pre_existing: z.ZodOptional<z.ZodBoolean>;
152
157
  runs: z.ZodOptional<z.ZodNumber>;
158
+ covered: z.ZodOptional<z.ZodArray<z.ZodString>>;
153
159
  }, z.core.$strip>>;
154
160
  }, z.core.$strip>>;
155
161
  not_verified: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -206,6 +212,7 @@ export declare const listPullRequests: {
206
212
  repo: z.ZodString;
207
213
  }, z.core.$strip>>;
208
214
  merged_within_hours: z.ZodOptional<z.ZodNumber>;
215
+ unless_noted: z.ZodOptional<z.ZodString>;
209
216
  }, z.core.$strip>;
210
217
  output: z.ZodObject<{
211
218
  pull_requests: z.ZodArray<z.ZodObject<{
@@ -219,6 +226,7 @@ export declare const listPullRequests: {
219
226
  open: "open";
220
227
  }>;
221
228
  }, z.core.$strip>>;
229
+ companion: z.ZodOptional<z.ZodLiteral<true>>;
222
230
  }, z.core.$strip>>;
223
231
  complete: z.ZodBoolean;
224
232
  }, z.core.$strip>;
@@ -481,6 +489,37 @@ export declare const ciRun: {
481
489
  unread: z.ZodArray<z.ZodNumber>;
482
490
  }, z.core.$strip>;
483
491
  };
492
+ /** The input and output of `code_owners`: the people who should review a pull request, at most two, as `request_reviewers` takes them, and as the run's `who_can_act` with why each one. */
493
+ export declare const codeOwners: {
494
+ input: z.ZodObject<{
495
+ url: z.ZodString;
496
+ }, z.core.$strip>;
497
+ output: z.ZodObject<{
498
+ source: z.ZodEnum<{
499
+ codeowners: "codeowners";
500
+ history: "history";
501
+ }>;
502
+ reviewers: z.ZodArray<z.ZodString>;
503
+ team_reviewers: z.ZodArray<z.ZodString>;
504
+ who_can_act: z.ZodArray<z.ZodObject<{
505
+ github: z.ZodOptional<z.ZodString>;
506
+ name: z.ZodOptional<z.ZodString>;
507
+ why: z.ZodString;
508
+ }, z.core.$strip>>;
509
+ }, z.core.$strip>;
510
+ };
511
+ /** The input and output of `request_reviewers`. */
512
+ export declare const requestReviewers: {
513
+ input: z.ZodObject<{
514
+ url: z.ZodString;
515
+ reviewers: z.ZodArray<z.ZodString>;
516
+ team_reviewers: z.ZodArray<z.ZodString>;
517
+ }, z.core.$strip>;
518
+ output: z.ZodObject<{
519
+ url: z.ZodString;
520
+ requested: z.ZodArray<z.ZodString>;
521
+ }, z.core.$strip>;
522
+ };
484
523
  /** The input and output of `branch_protection`. */
485
524
  export declare const branchProtection: {
486
525
  input: z.ZodObject<{
@@ -570,6 +609,8 @@ export declare const createCardTool: {
570
609
  outside: "outside";
571
610
  team: "team";
572
611
  }>>;
612
+ requested_by: z.ZodExactOptional<z.ZodString>;
613
+ requested_by_id: z.ZodExactOptional<z.ZodString>;
573
614
  }, z.core.$strict>;
574
615
  }, z.core.$strict>;
575
616
  parent: z.ZodExactOptional<z.ZodString>;
@@ -21,6 +21,11 @@ export const pushBranch = {
21
21
  .min(1)
22
22
  .optional()
23
23
  .describe("the edgar/ branch on origin that gets the head of the sandbox: the branch of an open pull request"),
24
+ suffix: z
25
+ .string()
26
+ .regex(/^[a-z]+$/)
27
+ .optional()
28
+ .describe("with `branch`: the head of the sandbox goes to `<branch>-<suffix>` instead, so one sandbox opens a second pull request, such as a companion"),
24
29
  }),
25
30
  output: z.object({ branch: z.string(), commit: z.string() }),
26
31
  };
@@ -41,7 +46,7 @@ export const openPullRequest = {
41
46
  card: z
42
47
  .looseObject({ id: z.string().min(1), title: z.string().min(1), url: z.string().optional() })
43
48
  .optional()
44
- .describe("the run's card: the title becomes `<id>: <title>`, and the body opens with its link"),
49
+ .describe("the run's card: the title becomes `<id>: <title>`, at most 72 characters with a trailing `[tag]` kept whole, and the body opens with its link"),
45
50
  large_diff_lines: z
46
51
  .number()
47
52
  .int()
@@ -59,10 +64,11 @@ export const openPullRequest = {
59
64
  exit_code: z.number().int().nullable(),
60
65
  pre_existing: z.boolean().optional(),
61
66
  runs: z.number().int().positive().optional(),
67
+ covered: z.array(z.string()).optional(),
62
68
  })),
63
69
  })
64
70
  .optional()
65
- .describe("the output of a check stage: the body lists each check that passed under Verified, saying when it passed only on its second run, and each other check under Not verified, with a failure that the check gave on the base commit too named as one the change did not cause"),
71
+ .describe("the output of a check stage: the body lists each check that passed under Verified, saying when it passed only on its second run, and each other check under Not verified, with a failure that the check gave on the base commit too named as one the change did not cause, and the changed files each check covers, or that it covers none, when the check says which paths it covers"),
66
72
  not_verified: z
67
73
  .array(z.string())
68
74
  .optional()
@@ -86,8 +92,20 @@ export const openPullRequest = {
86
92
  .union([httpsUrl, z.array(httpsUrl).max(5)])
87
93
  .optional()
88
94
  .describe("one URL, or at most 5, of the pull requests this one goes with, named after the body; each must be https, which the tool checks when it runs"),
95
+ after: httpsUrl
96
+ .optional()
97
+ .describe("the companion pull request that this one is built on: the body says to merge it first"),
98
+ first: z
99
+ .string()
100
+ .min(1)
101
+ .optional()
102
+ .describe("for a companion pull request: why the fix of the card needs it; the body says to merge this one first"),
103
+ }),
104
+ output: z.object({
105
+ url: z.string(),
106
+ number: z.number().int(),
107
+ commit: z.string().optional().describe("the head commit of the pull request"),
89
108
  }),
90
- output: z.object({ url: z.string(), number: z.number().int() }),
91
109
  };
92
110
  /** The input and output of `close_pull_request`, which the engine calls with the output of the `open_pull_request` call that it undoes. The sweep adds `text`, the line that says why, when a person closed the card of the pull request. */
93
111
  export const closePullRequest = {
@@ -166,6 +184,11 @@ export const listPullRequests = {
166
184
  .max(720)
167
185
  .optional()
168
186
  .describe("with it, the pull requests merged within this many hours, in place of the open ones"),
187
+ unless_noted: z
188
+ .string()
189
+ .min(1)
190
+ .optional()
191
+ .describe("with merged_within_hours, leaves out each merged pull request whose EDGAR note already holds this text as one of its lines, so a merge that was handled is not listed again"),
169
192
  }),
170
193
  output: z.object({
171
194
  pull_requests: z.array(z.object({
@@ -175,6 +198,10 @@ export const listPullRequests = {
175
198
  unmerged: z
176
199
  .array(z.object({ url: z.string(), state: z.enum(["open", "closed"]) }))
177
200
  .describe("with merged_within_hours, the pull requests of its `Goes with:` line that are not merged; empty otherwise"),
201
+ companion: z
202
+ .literal(true)
203
+ .optional()
204
+ .describe("with merged_within_hours, a companion pull request: the fix of its card is built on it and moves the card when it merges"),
178
205
  })),
179
206
  complete: z
180
207
  .boolean()
@@ -401,6 +428,35 @@ export const ciRun = {
401
428
  .describe("failed jobs past the log limit, read with /job/<id>"),
402
429
  }),
403
430
  };
431
+ /** The input and output of `code_owners`: the people who should review a pull request, at most two, as `request_reviewers` takes them, and as the run's `who_can_act` with why each one. */
432
+ export const codeOwners = {
433
+ input: byUrl,
434
+ output: z.object({
435
+ source: z
436
+ .enum(["codeowners", "history"])
437
+ .describe("codeowners: the CODEOWNERS file names them; history: they changed the files most, and most recently"),
438
+ reviewers: z.array(z.string()).describe("the login of each person"),
439
+ team_reviewers: z.array(z.string()).describe("the slug of each team that CODEOWNERS names"),
440
+ who_can_act: z
441
+ .array(z.object({
442
+ github: z.string().optional().describe("the login of a person"),
443
+ name: z.string().optional().describe("a team, as @org/slug"),
444
+ why: z.string(),
445
+ }))
446
+ .min(1),
447
+ }),
448
+ };
449
+ /** The input and output of `request_reviewers`. */
450
+ export const requestReviewers = {
451
+ input: byUrl.extend({
452
+ reviewers: z.array(z.string().min(1)).describe("the login of each person to ask"),
453
+ team_reviewers: z.array(z.string().min(1)).describe("the slug of each team to ask"),
454
+ }),
455
+ output: z.object({
456
+ url: z.string(),
457
+ requested: z.array(z.string()).describe("each login and team slug that GitHub now asks"),
458
+ }),
459
+ };
404
460
  /** The input and output of `branch_protection`. */
405
461
  export const branchProtection = {
406
462
  input: z.object({ repo: z.string().min(1), branch: z.string().min(1) }),
@@ -1,8 +1,9 @@
1
- /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
1
+ /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` and `suffix`, the head goes to `<branch>-<suffix>`, a second pull request of the same sandbox. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
2
2
  export declare const pushBranch: import("@kana-ai/edgar-sdk").Tool<{
3
3
  repo: string;
4
4
  branch?: string | undefined;
5
5
  to?: string | undefined;
6
+ suffix?: string | undefined;
6
7
  }, {
7
8
  branch: string;
8
9
  commit: string;
@@ -18,14 +18,15 @@ async function git(ctx, args) {
18
18
  }
19
19
  return ok(ran.value.stdout.trim());
20
20
  }
21
- /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
21
+ /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` and `suffix`, the head goes to `<branch>-<suffix>`, a second pull request of the same sandbox. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
22
22
  export const pushBranch = defineTool({
23
23
  description: "Push to origin through the sandbox, never forced: with `to`, the head of the sandbox to that edgar/ branch; with `branch` alone, that edgar/ branch under its own name",
24
24
  input: schema.input,
25
25
  output: schema.output,
26
26
  capabilities: ["git:push", "sandbox:read"],
27
- execute: async ({ branch, to }, ctx) => {
28
- const target = to ?? branch;
27
+ execute: async ({ branch, to, suffix }, ctx) => {
28
+ const target = to ?? (branch !== undefined && suffix !== undefined ? `${branch}-${suffix}` : branch);
29
+ const head = to !== undefined || suffix !== undefined;
29
30
  if (target === undefined) {
30
31
  return permanentFailure("invalid_input", "push_branch needs `branch` or `to`");
31
32
  }
@@ -36,15 +37,11 @@ export const pushBranch = defineTool({
36
37
  const commit = await git(ctx, [
37
38
  "rev-parse",
38
39
  "--verify",
39
- to === undefined ? `refs/heads/${target}` : "HEAD",
40
+ head ? "HEAD" : `refs/heads/${target}`,
40
41
  ]);
41
42
  if (!commit.ok)
42
43
  return commit.error;
43
- const pushed = await git(ctx, [
44
- "push",
45
- "origin",
46
- to === undefined ? target : `HEAD:refs/heads/${to}`,
47
- ]);
44
+ const pushed = await git(ctx, ["push", "origin", head ? `HEAD:refs/heads/${target}` : target]);
48
45
  if (!pushed.ok)
49
46
  return pushed.error;
50
47
  return done({ branch: target, commit: commit.value });
@@ -80,7 +80,7 @@ export function summaryOf(checks, commit) {
80
80
  ? `The 1 check passed on ${short}.`
81
81
  : `All ${String(total)} checks passed on ${short}.`;
82
82
  }
83
- /** Reads the head commit of the pull request at `url` and the files it changes, then its check runs and statuses, and judges them. A closed or merged pull request is `closed` with no check read, so no wait goes on for it. With `now`, a pull request with no check that was updated less than `FIRST_CHECK_GRACE_SECONDS` before it is `skipped`. */
83
+ /** Reads the head commit of the pull request at `url` and the files it changes, then its check runs and statuses, and judges them; when the token may not read statuses, it judges the check runs alone and says so. A closed or merged pull request is `closed` with no check read, so no wait goes on for it. With `now`, a pull request with no check that was updated less than `FIRST_CHECK_GRACE_SECONDS` before it is `skipped`. */
84
84
  async function checksOfPull(ctx, url, now) {
85
85
  const path = pullOf(url);
86
86
  if (!path.ok)
@@ -110,9 +110,11 @@ async function checksOfPull(ctx, url, now) {
110
110
  if (!runs.ok)
111
111
  return runs.error;
112
112
  const status = await github(ctx, "GET", `${repo}/commits/${commit}/status?per_page=100`, combinedStatus);
113
- if (!status.ok)
113
+ // A GitHub App installation without commit statuses still reports Actions as check runs: judge on those.
114
+ const unread = !status.ok && status.error.kind === "forbidden";
115
+ if (!status.ok && !unread)
114
116
  return status.error;
115
- const checks = checksOf(runs.value, status.value);
117
+ const checks = checksOf(runs.value, status.ok ? status.value : { statuses: [] });
116
118
  const sinceUpdate = (now ?? Infinity) - Date.parse(read.value.updated_at);
117
119
  if (checks.length === 0 && sinceUpdate < FIRST_CHECK_GRACE_SECONDS * 1000)
118
120
  return skipped();
@@ -125,7 +127,9 @@ async function checksOfPull(ctx, url, now) {
125
127
  checks: checks.length,
126
128
  failed: checks.filter((c) => c.state === "failed").map(({ name, url }) => ({ name, url })),
127
129
  retry_after_seconds: state === "pending" ? RECHECK_SECONDS : null,
128
- summary: summaryOf(checks, commit),
130
+ summary: unread
131
+ ? `${summaryOf(checks, commit)} I may not read the commit statuses of this repository, so only its check runs count.`
132
+ : summaryOf(checks, commit),
129
133
  changed_files: read.value.changed_files,
130
134
  });
131
135
  }
@@ -0,0 +1,34 @@
1
+ /** One line of a CODEOWNERS file: the paths it matches, and its owners as a login or `org/team`. */
2
+ export interface Rule {
3
+ readonly pattern: RegExp;
4
+ readonly owners: readonly string[];
5
+ }
6
+ /** The rules of a CODEOWNERS file in order. An owner by email is left out, since GitHub asks only a login or a team for a review. */
7
+ export declare function rulesOf(text: string): readonly Rule[];
8
+ /** How many of `paths` each owner owns, by the last rule that matches each path, as GitHub reads the file: a last rule with no owner leaves its path with none. */
9
+ export declare function ownersOf(rules: readonly Rule[], paths: readonly string[]): Map<string, number>;
10
+ /** The reviewer tools of the GitHub extension, by the name the manifest gives them. */
11
+ export declare const ownerTools: {
12
+ /** shortcut: the first 100 files of the pull request, and the newest 100 commits of the base branch for each of its first 10 files, so at most 15 reads; upgrade to GraphQL blame when a change is larger. */
13
+ code_owners: import("@kana-ai/edgar-sdk").Tool<{
14
+ url: string;
15
+ }, {
16
+ source: "codeowners" | "history";
17
+ reviewers: string[];
18
+ team_reviewers: string[];
19
+ who_can_act: {
20
+ github?: string | undefined;
21
+ name?: string | undefined;
22
+ why: string;
23
+ }[];
24
+ }, "GITHUB_TOKEN">;
25
+ /** GitHub refuses a request for someone who cannot review there, such as a person who is no longer a collaborator, with 422: the pull request then waits for a review as before. */
26
+ request_reviewers: import("@kana-ai/edgar-sdk").Tool<{
27
+ url: string;
28
+ reviewers: string[];
29
+ team_reviewers: string[];
30
+ }, {
31
+ url: string;
32
+ requested: string[];
33
+ }, "GITHUB_TOKEN">;
34
+ };
@@ -0,0 +1,182 @@
1
+ import { defineTool, done, ok, skipped } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { apiAccess, github } from "#api/client";
4
+ import { authoredPull, fileContent, listedCommit, pullFile, reviewRequest } from "#schemas/github";
5
+ import { codeOwners, requestReviewers } from "#schemas/tools";
6
+ import { pullOf } from "#tools/pull-request";
7
+ /** Where GitHub looks for the CODEOWNERS file, in its order: it uses the first one it finds. */
8
+ const CODEOWNERS_FILES = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
9
+ const DAY = 86_400_000;
10
+ const HALF_LIFE_DAYS = 90;
11
+ const WINDOW_DAYS = 365;
12
+ const PATHS = 10;
13
+ const TOP = 2;
14
+ /** What each part of a CODEOWNERS pattern means as a regular expression; any other character stands for itself. */
15
+ const TOKENS = {
16
+ "**/": "(?:.*/)?",
17
+ "/**": "/.*",
18
+ "**": ".*",
19
+ "*": "[^/]*",
20
+ "?": "[^/]",
21
+ };
22
+ /** A CODEOWNERS pattern with gitignore's rules: a slash at the start or in the middle anchors it at the root, a slash at the end matches a folder, and a match covers what is inside, except for a last part of `*`, which GitHub reads as one level. */
23
+ function patternOf(glob) {
24
+ const anchored = glob.startsWith("/") || glob.slice(0, -1).includes("/");
25
+ const body = glob
26
+ .replace(/^\/|\/$/g, "")
27
+ .replace(/\*\*\/|\/\*\*$|\*\*|\*|\?|[.+^${}()|[\]\\]/g, (part) => TOKENS[part] ?? `\\${part}`);
28
+ const inside = glob.endsWith("/") ? "/.*" : glob.endsWith("/*") ? "" : "(?:/.*)?";
29
+ return new RegExp(`^${anchored ? "" : "(?:.*/)?"}${body}${inside}$`);
30
+ }
31
+ /** The rules of a CODEOWNERS file in order. An owner by email is left out, since GitHub asks only a login or a team for a review. */
32
+ export function rulesOf(text) {
33
+ return text.split("\n").flatMap((line) => {
34
+ const [glob = "", ...owners] = line.replace(/#.*/, "").trim().split(/\s+/);
35
+ if (glob === "")
36
+ return [];
37
+ const named = owners.filter((owner) => owner.startsWith("@")).map((owner) => owner.slice(1));
38
+ return [{ pattern: patternOf(glob), owners: named }];
39
+ });
40
+ }
41
+ /** How many of `paths` each owner owns, by the last rule that matches each path, as GitHub reads the file: a last rule with no owner leaves its path with none. */
42
+ export function ownersOf(rules, paths) {
43
+ const counted = new Map();
44
+ for (const path of paths) {
45
+ const rule = rules.findLast(({ pattern }) => pattern.test(path));
46
+ for (const owner of rule?.owners ?? [])
47
+ counted.set(owner, (counted.get(owner) ?? 0) + 1);
48
+ }
49
+ return counted;
50
+ }
51
+ /** Whether a login can never review: an App, or the pull request's own author, who is EDGAR on its own pull request. */
52
+ function leftOut(login, author, type) {
53
+ return type === "Bot" || login.endsWith("[bot]") || login.toLowerCase() === author.toLowerCase();
54
+ }
55
+ /** The first CODEOWNERS file of the base branch, or `undefined` when there is none. */
56
+ async function codeOwnersFile(ctx, repo, ref) {
57
+ for (const file of CODEOWNERS_FILES) {
58
+ const read = await github(ctx, "GET", `${repo}/contents/${file}?ref=${ref}`, fileContent);
59
+ if (read.ok)
60
+ return ok({ file, text: Buffer.from(read.value.content, "base64").toString() });
61
+ if (read.error.kind !== "not_found")
62
+ return read;
63
+ }
64
+ return ok(undefined);
65
+ }
66
+ /** The answer for the top owners, a login or `org/team` each, with why. */
67
+ function answer(source, top) {
68
+ return {
69
+ source,
70
+ reviewers: top.filter(([owner]) => !owner.includes("/")).map(([owner]) => owner),
71
+ team_reviewers: top
72
+ .filter(([owner]) => owner.includes("/"))
73
+ .map(([owner]) => owner.slice(owner.indexOf("/") + 1)),
74
+ who_can_act: top.map(([owner, why]) => owner.includes("/") ? { name: `@${owner}`, why } : { github: owner, why }),
75
+ };
76
+ }
77
+ /** Each author's weight over the commits of the window: a commit counts 1, halved for each 90 days of its age, so a steady author outweighs the one who made the newest change. Each author's commit count and newest commit go with it. */
78
+ function ranked(commits, now) {
79
+ const by = new Map();
80
+ for (const { login, at } of commits) {
81
+ const was = by.get(login) ?? { login, score: 0, commits: 0, newest: 0 };
82
+ by.set(login, {
83
+ login,
84
+ score: was.score + 0.5 ** ((now - at) / DAY / HALF_LIFE_DAYS),
85
+ commits: was.commits + 1,
86
+ newest: Math.max(was.newest, at),
87
+ });
88
+ }
89
+ return [...by.values()].sort((a, b) => b.score - a.score || b.newest - a.newest || a.login.localeCompare(b.login));
90
+ }
91
+ /** The reviewer tools of the GitHub extension, by the name the manifest gives them. */
92
+ export const ownerTools = {
93
+ /** shortcut: the first 100 files of the pull request, and the newest 100 commits of the base branch for each of its first 10 files, so at most 15 reads; upgrade to GraphQL blame when a change is larger. */
94
+ code_owners: defineTool({
95
+ description: "Find who should review a pull request: the owners that CODEOWNERS names for its files, else the at most two people who changed those files most and most recently in the last 12 months, never a bot or its author; skipped when there is none",
96
+ input: codeOwners.input,
97
+ output: codeOwners.output,
98
+ ...apiAccess,
99
+ execute: async ({ url }, ctx) => {
100
+ const path = pullOf(url);
101
+ if (!path.ok)
102
+ return path.error;
103
+ const repo = path.value.replace(/\/pulls\/\d+$/, "");
104
+ const pull = await github(ctx, "GET", path.value, authoredPull);
105
+ if (!pull.ok)
106
+ return pull.error;
107
+ const listed = await github(ctx, "GET", `${path.value}/files?per_page=100`, z.array(pullFile));
108
+ if (!listed.ok)
109
+ return listed.error;
110
+ const author = pull.value.user?.login ?? "";
111
+ const paths = listed.value.map((file) => file.filename);
112
+ const ref = encodeURIComponent(pull.value.base.ref);
113
+ const found = await codeOwnersFile(ctx, repo, ref);
114
+ if (!found.ok)
115
+ return found.error;
116
+ if (found.value !== undefined) {
117
+ const { file, text } = found.value;
118
+ const owned = [...ownersOf(rulesOf(text), paths)]
119
+ .filter(([owner]) => !leftOut(owner, author))
120
+ .sort(([, a], [, b]) => b - a)
121
+ .slice(0, TOP);
122
+ if (owned.length > 0) {
123
+ const why = (count) => `${file} names them for ${String(count)} of the ${String(paths.length)} changed files`;
124
+ return done(answer("codeowners", owned.map(([owner, count]) => [owner, why(count)])));
125
+ }
126
+ }
127
+ const now = Date.now();
128
+ const seen = new Map();
129
+ for (const file of paths.slice(0, PATHS)) {
130
+ const query = new URLSearchParams({
131
+ sha: pull.value.base.ref,
132
+ path: file,
133
+ per_page: "100",
134
+ });
135
+ const read = await github(ctx, "GET", `${repo}/commits?${query.toString()}`, z.array(listedCommit));
136
+ if (!read.ok)
137
+ return read.error;
138
+ for (const { sha, author: by, commit } of read.value) {
139
+ const at = Date.parse(commit.author?.date ?? "");
140
+ if (by === null || leftOut(by.login, author, by.type) || !(now - at < WINDOW_DAYS * DAY))
141
+ continue;
142
+ seen.set(sha, { login: by.login, at });
143
+ }
144
+ }
145
+ const top = ranked([...seen.values()], now).slice(0, TOP);
146
+ if (top.length === 0)
147
+ return skipped();
148
+ const why = (commits, newest) => `${String(commits)} of the ${String(seen.size)} commits to the changed files in the last 12 months, the newest on ${new Date(newest).toISOString().slice(0, 10)}`;
149
+ return done(answer("history", top.map(({ login, commits, newest }) => [login, why(commits, newest)])));
150
+ },
151
+ }),
152
+ /** GitHub refuses a request for someone who cannot review there, such as a person who is no longer a collaborator, with 422: the pull request then waits for a review as before. */
153
+ request_reviewers: defineTool({
154
+ description: "Ask people and teams to review a pull request; skipped when there is no one to ask or GitHub cannot ask them",
155
+ input: requestReviewers.input,
156
+ output: requestReviewers.output,
157
+ ...apiAccess,
158
+ side_effect: true,
159
+ undo: "none",
160
+ undo_reason: "A review request only asks; the people asked are still the right ones when a later stage is undone.",
161
+ execute: async ({ url, reviewers, team_reviewers }, ctx) => {
162
+ const path = pullOf(url);
163
+ if (!path.ok)
164
+ return path.error;
165
+ if (reviewers.length === 0 && team_reviewers.length === 0)
166
+ return skipped();
167
+ const asked = await github(ctx, "POST", `${path.value}/requested_reviewers`, reviewRequest, {
168
+ reviewers,
169
+ team_reviewers,
170
+ });
171
+ if (!asked.ok)
172
+ return asked.error.kind === "invalid" ? skipped() : asked.error;
173
+ return done({
174
+ url,
175
+ requested: [
176
+ ...asked.value.requested_reviewers.map((person) => person.login),
177
+ ...asked.value.requested_teams.map((team) => team.slug),
178
+ ],
179
+ });
180
+ },
181
+ }),
182
+ };
@@ -27,7 +27,9 @@ export declare function changeNotices(files: readonly {
27
27
  readonly prefix: string;
28
28
  readonly notice: string;
29
29
  }[]): string[];
30
- /** A pull request's title for its card, `<id>: <card title>`, so a reviewer sees the card at a glance; with no card, the title as written. */
30
+ /**
31
+ * A pull request's title, `<id>: <title>` for its card, so a reviewer sees the card at a glance. Past 72 characters, the words before a trailing `[tag]` are cut where a word ends, and the tag stays whole: a repository can start a build from a tag in the merge commit's message, which holds the title.
32
+ */
31
33
  export declare function titleOf(title: string, card: Card | undefined): string;
32
34
  /** The first line of a body for its card: its link, or its id when the card has no address. */
33
35
  export declare function cardLine(card: Card | undefined): string;
@@ -63,6 +65,7 @@ export declare const pullRequestTools: {
63
65
  exit_code: number | null;
64
66
  pre_existing?: boolean | undefined;
65
67
  runs?: number | undefined;
68
+ covered?: string[] | undefined;
66
69
  }[];
67
70
  } | undefined;
68
71
  not_verified?: string[] | undefined;
@@ -76,9 +79,12 @@ export declare const pullRequestTools: {
76
79
  } | undefined;
77
80
  proof_passes?: string | undefined;
78
81
  related?: string | string[] | undefined;
82
+ after?: string | undefined;
83
+ first?: string | undefined;
79
84
  }, {
80
85
  url: string;
81
86
  number: number;
87
+ commit?: string | undefined;
82
88
  }, "GITHUB_TOKEN">;
83
89
  /** The review line of the first body is left out: that review read the change before this one. The notices compare the change with the pull request's own base. */
84
90
  update_pull_request: import("@kana-ai/edgar-sdk").Tool<{
@@ -102,6 +108,7 @@ export declare const pullRequestTools: {
102
108
  exit_code: number | null;
103
109
  pre_existing?: boolean | undefined;
104
110
  runs?: number | undefined;
111
+ covered?: string[] | undefined;
105
112
  }[];
106
113
  } | undefined;
107
114
  not_verified?: string[] | undefined;
@@ -172,12 +179,13 @@ export declare const pullRequestTools: {
172
179
  url: string;
173
180
  state: "closed" | "merged" | "open";
174
181
  }, "GITHUB_TOKEN">;
175
- /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. */
182
+ /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. With `unless_noted`, each merged pull request costs one read of its comments, so one that EDGAR's note already says was handled costs nothing more, here or in the tracker. */
176
183
  list_pull_requests: import("@kana-ai/edgar-sdk").Tool<{
177
184
  services: {
178
185
  repo: string;
179
186
  }[];
180
187
  merged_within_hours?: number | undefined;
188
+ unless_noted?: string | undefined;
181
189
  }, {
182
190
  pull_requests: {
183
191
  url: string;
@@ -187,6 +195,7 @@ export declare const pullRequestTools: {
187
195
  url: string;
188
196
  state: "closed" | "open";
189
197
  }[];
198
+ companion?: true | undefined;
190
199
  }[];
191
200
  complete: boolean;
192
201
  }, "GITHUB_TOKEN">;