@kana-ai/edgar-ext-github 0.0.0-stage → 0.1.1

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.
Files changed (136) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +469 -2
  3. package/agents/dismiss/agent.toml +4 -0
  4. package/agents/dismiss/instructions.md +25 -0
  5. package/dist/src/api/app.d.ts +16 -0
  6. package/dist/src/api/app.js +32 -0
  7. package/dist/src/api/client.d.ts +26 -0
  8. package/dist/src/api/client.js +103 -0
  9. package/dist/src/api/failures.d.ts +8 -0
  10. package/dist/src/api/failures.js +31 -0
  11. package/dist/src/feed/alerts.d.ts +26 -0
  12. package/dist/src/feed/alerts.js +117 -0
  13. package/dist/src/feed/cards.d.ts +32 -0
  14. package/dist/src/feed/cards.js +164 -0
  15. package/dist/src/feed/service.d.ts +28 -0
  16. package/dist/src/feed/service.js +163 -0
  17. package/dist/src/index.d.ts +490 -0
  18. package/dist/src/index.js +62 -0
  19. package/dist/src/schemas/config.d.ts +57 -0
  20. package/dist/src/schemas/config.js +89 -0
  21. package/dist/src/schemas/github.d.ts +417 -0
  22. package/dist/src/schemas/github.js +216 -0
  23. package/dist/src/schemas/tools.d.ts +620 -0
  24. package/dist/src/schemas/tools.js +501 -0
  25. package/dist/src/tools/alerts.d.ts +45 -0
  26. package/dist/src/tools/alerts.js +100 -0
  27. package/dist/src/tools/branch.d.ts +9 -0
  28. package/dist/src/tools/branch.js +48 -0
  29. package/dist/src/tools/checks.d.ts +118 -0
  30. package/dist/src/tools/checks.js +223 -0
  31. package/dist/src/tools/discussion.d.ts +41 -0
  32. package/dist/src/tools/discussion.js +66 -0
  33. package/dist/src/tools/pull-request.d.ts +195 -0
  34. package/dist/src/tools/pull-request.js +537 -0
  35. package/dist/src/tools/repository.d.ts +53 -0
  36. package/dist/src/tools/repository.js +134 -0
  37. package/dist/src/tools/screenshot.d.ts +21 -0
  38. package/dist/src/tools/screenshot.js +99 -0
  39. package/dist/src/tracker/assignee.d.ts +15 -0
  40. package/dist/src/tracker/assignee.js +65 -0
  41. package/dist/src/tracker/cards.d.ts +41 -0
  42. package/dist/src/tracker/cards.js +361 -0
  43. package/dist/src/tracker/comments.d.ts +9 -0
  44. package/dist/src/tracker/comments.js +68 -0
  45. package/dist/src/tracker/description.d.ts +19 -0
  46. package/dist/src/tracker/description.js +55 -0
  47. package/dist/src/tracker/hand-back.d.ts +8 -0
  48. package/dist/src/tracker/hand-back.js +60 -0
  49. package/dist/src/tracker/port.d.ts +2 -0
  50. package/dist/src/tracker/port.js +42 -0
  51. package/dist/src/tracker/states.d.ts +77 -0
  52. package/dist/src/tracker/states.js +189 -0
  53. package/dist/src/tracker/tools.d.ts +143 -0
  54. package/dist/src/tracker/tools.js +131 -0
  55. package/dist/src/tracker/transitions.d.ts +12 -0
  56. package/dist/src/tracker/transitions.js +101 -0
  57. package/edgar-extension.json +507 -0
  58. package/package.json +43 -3
  59. package/schemas/assign.in.json +15 -0
  60. package/schemas/assign.out.json +14 -0
  61. package/schemas/attach_screenshot.in.json +44 -0
  62. package/schemas/attach_screenshot.out.json +31 -0
  63. package/schemas/batch_cards.in.json +27 -0
  64. package/schemas/batch_cards.out.json +37 -0
  65. package/schemas/branch_protection.in.json +15 -0
  66. package/schemas/branch_protection.out.json +67 -0
  67. package/schemas/ci_run.in.json +12 -0
  68. package/schemas/ci_run.out.json +109 -0
  69. package/schemas/close.in.json +14 -0
  70. package/schemas/close.out.json +10 -0
  71. package/schemas/close_pull_request.in.json +21 -0
  72. package/schemas/close_pull_request.out.json +14 -0
  73. package/schemas/comment.in.json +19 -0
  74. package/schemas/comment.out.json +10 -0
  75. package/schemas/config.json +202 -0
  76. package/schemas/count_sighting.in.json +17 -0
  77. package/schemas/count_sighting.out.json +10 -0
  78. package/schemas/create_card.in.json +108 -0
  79. package/schemas/create_card.out.json +13 -0
  80. package/schemas/dependabot_alerts.in.json +49 -0
  81. package/schemas/dependabot_alerts.out.json +75 -0
  82. package/schemas/dismiss_dependabot_alert.in.json +26 -0
  83. package/schemas/dismiss_dependabot_alert.out.json +27 -0
  84. package/schemas/find_assignee.in.json +15 -0
  85. package/schemas/find_assignee.out.json +10 -0
  86. package/schemas/find_cards.in.json +18 -0
  87. package/schemas/find_cards.out.json +33 -0
  88. package/schemas/find_dependabot_dismissal.in.json +12 -0
  89. package/schemas/find_dependabot_dismissal.out.json +27 -0
  90. package/schemas/find_description.in.json +15 -0
  91. package/schemas/find_description.out.json +10 -0
  92. package/schemas/find_pull_request.in.json +25 -0
  93. package/schemas/find_pull_request.out.json +14 -0
  94. package/schemas/hand_back.in.json +11 -0
  95. package/schemas/hand_back.out.json +18 -0
  96. package/schemas/linked_pull_requests.in.json +15 -0
  97. package/schemas/linked_pull_requests.out.json +44 -0
  98. package/schemas/list_pull_requests.in.json +26 -0
  99. package/schemas/list_pull_requests.out.json +42 -0
  100. package/schemas/merge_pull_request.in.json +22 -0
  101. package/schemas/merge_pull_request.out.json +16 -0
  102. package/schemas/move.in.json +15 -0
  103. package/schemas/move.out.json +10 -0
  104. package/schemas/note_pull_request.in.json +15 -0
  105. package/schemas/note_pull_request.out.json +10 -0
  106. package/schemas/open_pull_request.in.json +113 -0
  107. package/schemas/open_pull_request.out.json +15 -0
  108. package/schemas/pull_request_checks.in.json +11 -0
  109. package/schemas/pull_request_checks.out.json +72 -0
  110. package/schemas/pull_request_discussion.in.json +11 -0
  111. package/schemas/pull_request_discussion.out.json +107 -0
  112. package/schemas/pull_request_state.in.json +11 -0
  113. package/schemas/pull_request_state.out.json +52 -0
  114. package/schemas/push_branch.in.json +21 -0
  115. package/schemas/push_branch.out.json +13 -0
  116. package/schemas/release_follow_ups.in.json +15 -0
  117. package/schemas/release_follow_ups.out.json +13 -0
  118. package/schemas/reopen_dependabot_alert.in.json +33 -0
  119. package/schemas/reopen_dependabot_alert.out.json +22 -0
  120. package/schemas/restore_assignee.in.json +20 -0
  121. package/schemas/restore_assignee.out.json +10 -0
  122. package/schemas/restore_description.in.json +20 -0
  123. package/schemas/restore_description.out.json +10 -0
  124. package/schemas/update_description.in.json +15 -0
  125. package/schemas/update_description.out.json +14 -0
  126. package/schemas/update_pull_request.in.json +81 -0
  127. package/schemas/update_pull_request.out.json +10 -0
  128. package/schemas/wait_for_checks.in.json +11 -0
  129. package/schemas/wait_for_checks.out.json +72 -0
  130. package/schemas/wait_for_merge.in.json +11 -0
  131. package/schemas/wait_for_merge.out.json +17 -0
  132. package/schemas/wait_for_passed_checks.in.json +11 -0
  133. package/schemas/wait_for_passed_checks.out.json +72 -0
  134. package/schemas/wait_for_review.in.json +11 -0
  135. package/schemas/wait_for_review.out.json +52 -0
  136. package/workflows/resume.toml +17 -0
@@ -0,0 +1,32 @@
1
+ import { createPrivateKey, sign } from "node:crypto";
2
+ import { attempt, permanentFailure } from "@kana-ai/edgar-sdk";
3
+ /** How long before its expiry a cached installation token is minted again. */
4
+ export const RENEW_BEFORE_MS = 5 * 60_000;
5
+ const held = new Map();
6
+ const base64url = (data) => Buffer.from(data).toString("base64url");
7
+ /** The JWT that signs the App in, RS256 with its private key, issued a minute back for clock drift and valid for nine minutes; a key that is not a PEM private key is `unauthenticated`. */
8
+ export function appJwt(app, pem, now = Date.now()) {
9
+ const seconds = Math.floor(now / 1000);
10
+ const head = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
11
+ const claims = base64url(JSON.stringify({ iat: seconds - 60, exp: seconds + 540, iss: String(app.id) }));
12
+ return attempt(() => {
13
+ const key = createPrivateKey(pem);
14
+ return `${head}.${claims}.${base64url(sign("sha256", Buffer.from(`${head}.${claims}`), key))}`;
15
+ }, () => permanentFailure("unauthenticated", "the GitHub App key is not a PEM private key", {
16
+ cause: "GITHUB_TOKEN holds the App key when [extensions.github] app is set",
17
+ }));
18
+ }
19
+ const keyOf = (app) => `${String(app.id)}:${String(app.installation)}`;
20
+ /** The installation token minted for `app` that is still good at `now`, past which it is minted again. */
21
+ export function heldToken(app, now = Date.now()) {
22
+ const found = held.get(keyOf(app));
23
+ return found !== undefined && found.expiresAt - RENEW_BEFORE_MS > now ? found.token : undefined;
24
+ }
25
+ /** Keeps a minted installation token in this process's memory until five minutes before `expires_at`. */
26
+ export function holdToken(app, token, expiresAt) {
27
+ held.set(keyOf(app), { token, expiresAt: Date.parse(expiresAt) });
28
+ }
29
+ /** Forgets every held token, for a test that starts clean. */
30
+ export function forgetTokens() {
31
+ held.clear();
32
+ }
@@ -0,0 +1,26 @@
1
+ import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ /** The secret every GitHub call sends. */
4
+ export declare const TOKEN = "GITHUB_TOKEN";
5
+ /** The host every GitHub call goes to. */
6
+ export declare const HOST: "api.github.com";
7
+ /** The secret and the capability of each tool that calls the API. */
8
+ export declare const apiAccess: {
9
+ readonly secrets: readonly ["GITHUB_TOKEN"];
10
+ readonly capabilities: readonly ["network:api.github.com"];
11
+ };
12
+ /** The hosts a job log's redirect goes to; the token never goes there, as `fetch` drops `authorization` on a redirect to another origin. */
13
+ export declare const LOG_HOSTS: readonly ["*.blob.core.windows.net", "*.actions.githubusercontent.com"];
14
+ /** The answer of one GitHub call: the parsed body, or the failure it maps to. */
15
+ export type Reply<T> = Result<T, Failure>;
16
+ type Method = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
17
+ /** Calls the GitHub REST API and parses the answer with `schema`. */
18
+ export declare function github<T>(ctx: Ctx<typeof TOKEN>, method: Method, path: string, schema: z.ZodType<T>, body?: Readonly<Record<string, unknown>>): Promise<Reply<T>>;
19
+ /** Calls the GitHub REST API like `github`, with the requests the token has left from `x-ratelimit-remaining`, 0 when the answer has none. */
20
+ export declare function githubCounted<T>(ctx: Ctx<typeof TOKEN>, method: Method, path: string, schema: z.ZodType<T>, body?: Readonly<Record<string, unknown>>): Promise<Reply<{
21
+ value: T;
22
+ remaining: number;
23
+ }>>;
24
+ /** GETs a text answer, such as a job log behind its redirect; a body that cannot be read is `provider_unavailable`. */
25
+ export declare function githubText(ctx: Ctx<typeof TOKEN>, path: string): Promise<Reply<string>>;
26
+ export {};
@@ -0,0 +1,103 @@
1
+ import { attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, unwrapOr, } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { appJwt, heldToken, holdToken } from "#api/app";
4
+ import { limits, mapFailure } from "#api/failures";
5
+ import { config } from "#schemas/config";
6
+ /** The secret every GitHub call sends. */
7
+ export const TOKEN = "GITHUB_TOKEN";
8
+ /** The host every GitHub call goes to. */
9
+ export const HOST = limits.source;
10
+ /** The secret and the capability of each tool that calls the API. */
11
+ export const apiAccess = { secrets: [TOKEN], capabilities: [`network:${HOST}`] };
12
+ /** The hosts a job log's redirect goes to; the token never goes there, as `fetch` drops `authorization` on a redirect to another origin. */
13
+ export const LOG_HOSTS = ["*.blob.core.windows.net", "*.actions.githubusercontent.com"];
14
+ /** Sends one GitHub REST call with `authorization`; the answer's rate limit goes on the call's outcome, and an error answer maps to its failure. */
15
+ async function send(ctx, method, path, authorization, body) {
16
+ const context = `github ${method} ${path}`;
17
+ const headers = {
18
+ accept: "application/vnd.github+json",
19
+ authorization,
20
+ "user-agent": "edgar",
21
+ "x-github-api-version": "2022-11-28",
22
+ ...(body === undefined ? {} : { "content-type": "application/json" }),
23
+ };
24
+ const sent = await attemptAsync(async () => await fetch(`https://${HOST}${path}`, {
25
+ method,
26
+ signal: ctx.signal,
27
+ headers,
28
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
29
+ }), (caught) => fetchFailure(caught, ctx.signal, context));
30
+ if (!sent.ok)
31
+ return sent;
32
+ const response = sent.value;
33
+ reportLimit(ctx, limitFromHeaders(response.headers, limits.scheme, HOST));
34
+ if (response.ok)
35
+ return ok(response);
36
+ const json = unwrapOr(await attemptAsync(async () => await response.json(), () => null), null);
37
+ return err(mapFailure(response.status, response.headers, json, context));
38
+ }
39
+ const minted = z.object({ token: z.string(), expires_at: z.string() });
40
+ /** An installation token of `app`: the one held, or one minted with the App's JWT and then held. */
41
+ async function installationToken(ctx, app) {
42
+ const known = heldToken(app);
43
+ if (known !== undefined)
44
+ return ok(known);
45
+ const jwt = appJwt(app, ctx.secrets.get(TOKEN));
46
+ if (!jwt.ok)
47
+ return jwt;
48
+ const path = `/app/installations/${String(app.installation)}/access_tokens`;
49
+ const sent = await send(ctx, "POST", path, `Bearer ${jwt.value}`, {});
50
+ if (!sent.ok)
51
+ return sent;
52
+ const parsed = minted.safeParse(unwrapOr(await attemptAsync(async () => await sent.value.json(), () => null), null));
53
+ if (!parsed.success) {
54
+ return err(failure("tool_error", `github POST ${path}: unexpected answer`));
55
+ }
56
+ holdToken(app, parsed.data.token, parsed.data.expires_at);
57
+ return ok(parsed.data.token);
58
+ }
59
+ /** The `authorization` of a call: `GITHUB_TOKEN` as a token, or with `[extensions.github] app` set, an installation token of that App, `GITHUB_TOKEN` then holding the App's private key. A secret read outside the call is a bug and throws before the request. */
60
+ async function authorizationOf(ctx) {
61
+ const app = config.safeParse(ctx.config ?? {}).data?.app;
62
+ if (app === undefined)
63
+ return ok(`Bearer ${ctx.secrets.get(TOKEN)}`);
64
+ const token = await installationToken(ctx, app);
65
+ return token.ok ? ok(`Bearer ${token.value}`) : token;
66
+ }
67
+ /** Calls the GitHub REST API and parses the answer with `schema`. */
68
+ export async function github(ctx, method, path, schema, body) {
69
+ const read = await githubCounted(ctx, method, path, schema, body);
70
+ return read.ok ? ok(read.value.value) : read;
71
+ }
72
+ /** Calls the GitHub REST API like `github`, with the requests the token has left from `x-ratelimit-remaining`, 0 when the answer has none. */
73
+ export async function githubCounted(ctx, method, path, schema, body) {
74
+ const authorization = await authorizationOf(ctx);
75
+ if (!authorization.ok)
76
+ return authorization;
77
+ const sent = await send(ctx, method, path, authorization.value, body);
78
+ if (!sent.ok)
79
+ return sent;
80
+ const remaining = Number(sent.value.headers.get("x-ratelimit-remaining"));
81
+ const json = unwrapOr(await attemptAsync(async () => await sent.value.json(), () => null), null);
82
+ const parsed = schema.safeParse(json);
83
+ if (parsed.success) {
84
+ return ok({
85
+ value: parsed.data,
86
+ remaining: Number.isFinite(remaining) ? Math.max(0, Math.floor(remaining)) : 0,
87
+ });
88
+ }
89
+ const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
90
+ return err(failure("tool_error", `github ${method} ${path}: unexpected answer`, {
91
+ cause: `fields: ${fields}`,
92
+ }));
93
+ }
94
+ /** GETs a text answer, such as a job log behind its redirect; a body that cannot be read is `provider_unavailable`. */
95
+ export async function githubText(ctx, path) {
96
+ const authorization = await authorizationOf(ctx);
97
+ if (!authorization.ok)
98
+ return authorization;
99
+ const sent = await send(ctx, "GET", path, authorization.value);
100
+ if (!sent.ok)
101
+ return sent;
102
+ return await attemptAsync(async () => await sent.value.text(), (caught) => fetchFailure(caught, ctx.signal, `github GET ${path}`));
103
+ }
@@ -0,0 +1,8 @@
1
+ import { type Failure } from "@kana-ai/edgar-sdk";
2
+ /** GitHub reports its rate limits in `x-ratelimit-*` on every answer of its API host. */
3
+ export declare const limits: {
4
+ readonly scheme: "github";
5
+ readonly source: "api.github.com";
6
+ };
7
+ /** Maps a GitHub error answer to a failure, a 403 that carries a rate limit first; `cause` holds the status and GitHub's `message`. A `forbidden` answer says what the token needs, from `X-Accepted-GitHub-Permissions` (a fine-grained token or an App) or `X-Accepted-OAuth-Scopes` (a classic token). */
8
+ export declare function mapFailure(status: number, headers: Headers, body: unknown, context: string, now?: number): Failure;
@@ -0,0 +1,31 @@
1
+ import { vendorFailure } from "@kana-ai/edgar-sdk";
2
+ import { errorBody } from "#schemas/github";
3
+ /** GitHub reports its rate limits in `x-ratelimit-*` on every answer of its API host. */
4
+ export const limits = { scheme: "github", source: "api.github.com" };
5
+ const statusKinds = new Map([
6
+ [401, "unauthenticated"],
7
+ [403, "forbidden"],
8
+ [404, "not_found"],
9
+ [410, "not_found"],
10
+ [422, "invalid"],
11
+ [429, "rate_limited"],
12
+ ]);
13
+ /** Maps a GitHub error answer to a failure, a 403 that carries a rate limit first; `cause` holds the status and GitHub's `message`. A `forbidden` answer says what the token needs, from `X-Accepted-GitHub-Permissions` (a fine-grained token or an App) or `X-Accepted-OAuth-Scopes` (a classic token). */
14
+ export function mapFailure(status, headers, body, context, now = Date.now()) {
15
+ const vendor = errorBody.safeParse(body);
16
+ const message = vendor.success ? (vendor.data.message ?? "") : "";
17
+ const cause = `${String(status)} ${message}`.trim();
18
+ const secondary = vendor.success && (vendor.data.documentation_url ?? "").includes("secondary-rate-limits");
19
+ const limited = status === 403 &&
20
+ (headers.get("x-ratelimit-remaining") === "0" || headers.has("retry-after") || secondary);
21
+ const kind = limited
22
+ ? "rate_limited"
23
+ : status >= 500
24
+ ? "provider_unavailable"
25
+ : (statusKinds.get(status) ?? "tool_error");
26
+ const failed = vendorFailure(kind, context, cause, headers, limits, now);
27
+ const needs = headers.get("x-accepted-github-permissions") ?? headers.get("x-accepted-oauth-scopes");
28
+ return kind === "forbidden" && needs !== null && needs !== ""
29
+ ? { ...failed, message: `${failed.message}: the GITHUB_TOKEN needs ${needs}` }
30
+ : failed;
31
+ }
@@ -0,0 +1,26 @@
1
+ import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
2
+ import { type TOKEN } from "#api/client";
3
+ import { type DependabotFeed } from "#schemas/config";
4
+ /** What one process keeps between sweeps: the fingerprints of the cards it opened, and what it last said about each repository. */
5
+ export interface Memory {
6
+ readonly opened: Set<string>;
7
+ readonly said: Map<string, string>;
8
+ }
9
+ /** Removes from `opened` each fingerprint that is not in `open`. */
10
+ export declare function forget(opened: Set<string>, open: ReadonlySet<string>): void;
11
+ /** What one sweep did. */
12
+ export interface Swept {
13
+ readonly read: number;
14
+ readonly filed: number;
15
+ readonly tracked: number;
16
+ /** The cards that wait for the next sweep: past `max_per_run`, refused by the tracker, or not asked for because the tracker could not answer. */
17
+ readonly held: number;
18
+ readonly below: number;
19
+ /** The seconds GitHub asks the token to wait, when a rate limit ended the reading; else 0. */
20
+ readonly wait: number;
21
+ }
22
+ /**
23
+ * One sweep: reads the open alerts and opens at most `max_per_run` cards, the worst first. A fingerprint this process opened is tracked, and EDGAR answers a repeat with the open card that holds it. After a sweep that read every repository, a fingerprint whose alert is no longer open is forgotten, so the memory holds only open alerts.
24
+ * A card the tracker refuses is said and asked for again at the next sweep. When the tracker cannot answer, no other card is asked for in this sweep.
25
+ */
26
+ export declare function sweepAlerts(ctx: Ctx<typeof TOKEN>, feed: DependabotFeed, memory: Memory): Promise<Result<Swept, Failure>>;
@@ -0,0 +1,117 @@
1
+ import { ok } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { github } from "#api/client";
4
+ import { alertCard, alertKey, rankOf } from "#feed/cards";
5
+ import { severities } from "#schemas/config";
6
+ import { alert } from "#schemas/github";
7
+ import { factsOf } from "#tools/repository";
8
+ const PAGE = 100;
9
+ /** Removes from `opened` each fingerprint that is not in `open`. */
10
+ export function forget(opened, open) {
11
+ for (const key of opened)
12
+ if (!open.has(key))
13
+ opened.delete(key);
14
+ }
15
+ /** Writes what the read of a repository came to when that differs from the sweep before, so a repository with Dependabot off is one log line, not one for each sweep. */
16
+ function say(ctx, said, repo, line) {
17
+ if (line === undefined) {
18
+ said.delete(repo);
19
+ return;
20
+ }
21
+ if (said.get(repo) !== line)
22
+ ctx.log(`github dependabot: ${repo} ${line}`);
23
+ said.set(repo, line);
24
+ }
25
+ /**
26
+ * The cards the open alerts of each repository ask for now, the worst first: one for each advisory of a package, at or above `severity_min`. GitHub filters by severity, and the rank is checked here again, so the floor holds whatever GitHub sends.
27
+ * A repository that fails is said and the reading goes on; a rate limit ends the reading with its wait, since the limit is the token's; a refused token is the failure.
28
+ * shortcut: one page of the 100 newest open alerts for each repository; upgrade to `Link` pagination when a repository holds more at once.
29
+ */
30
+ async function readAlerts(ctx, feed, said) {
31
+ const floor = rankOf(feed.severity_min);
32
+ const query = new URLSearchParams({
33
+ state: "open",
34
+ severity: severities.slice(floor).join(","),
35
+ sort: "created",
36
+ direction: "desc",
37
+ per_page: String(PAGE),
38
+ });
39
+ const groups = new Map();
40
+ let read = 0;
41
+ let below = 0;
42
+ let wait = 0;
43
+ for (const [repo, service] of Object.entries(feed.services)) {
44
+ const path = `/repos/${repo}/dependabot/alerts?${query.toString()}`;
45
+ const listed = await github(ctx, "GET", path, z.array(alert));
46
+ if (!listed.ok) {
47
+ const failed = listed.error;
48
+ if (failed.outcome === "permanent_failure" && failed.kind === "unauthenticated")
49
+ return listed;
50
+ say(ctx, said, repo, `is not read: ${failed.kind}: ${failed.message}`);
51
+ if (failed.outcome === "temporary_failure" && failed.kind === "rate_limited") {
52
+ wait = failed.retry_after ?? 0;
53
+ break;
54
+ }
55
+ continue;
56
+ }
57
+ read += 1;
58
+ const full = listed.value.length === PAGE;
59
+ say(ctx, said, repo, full ? `has more open alerts than the ${String(PAGE)} read` : undefined);
60
+ const home = { service, repo, column: feed.card_column };
61
+ for (const a of listed.value.map(factsOf)) {
62
+ const rank = rankOf(a.severity);
63
+ if (rank !== -1 && rank < floor) {
64
+ below += 1;
65
+ continue;
66
+ }
67
+ const key = alertKey(repo, a);
68
+ const group = groups.get(key);
69
+ groups.set(key, { home, alerts: group === undefined ? [a] : [...group.alerts, a] });
70
+ }
71
+ }
72
+ const cards = [...groups]
73
+ .map(([key, group]) => ({ key, card: alertCard(group.home, group.alerts) }))
74
+ .sort((a, b) => rankOf(b.card.block.severity ?? "") - rankOf(a.card.block.severity ?? ""));
75
+ return ok({ cards, whole: read === Object.keys(feed.services).length, read, below, wait });
76
+ }
77
+ /**
78
+ * One sweep: reads the open alerts and opens at most `max_per_run` cards, the worst first. A fingerprint this process opened is tracked, and EDGAR answers a repeat with the open card that holds it. After a sweep that read every repository, a fingerprint whose alert is no longer open is forgotten, so the memory holds only open alerts.
79
+ * A card the tracker refuses is said and asked for again at the next sweep. When the tracker cannot answer, no other card is asked for in this sweep.
80
+ */
81
+ export async function sweepAlerts(ctx, feed, memory) {
82
+ const found = await readAlerts(ctx, feed, memory.said);
83
+ if (!found.ok)
84
+ return found;
85
+ const { cards, whole, read, below, wait } = found.value;
86
+ if (whole)
87
+ forget(memory.opened, new Set(cards.map(({ key }) => key)));
88
+ let filed = 0;
89
+ let tracked = 0;
90
+ let held = 0;
91
+ let answers = true;
92
+ for (const { key, card } of cards) {
93
+ if (memory.opened.has(key)) {
94
+ tracked += 1;
95
+ continue;
96
+ }
97
+ if (!answers || filed >= feed.max_per_run) {
98
+ held += 1;
99
+ continue;
100
+ }
101
+ const made = await ctx.cards.open(card);
102
+ if (made.ok && made.value.outcome === "done") {
103
+ memory.opened.add(key);
104
+ filed += 1;
105
+ continue;
106
+ }
107
+ held += 1;
108
+ answers = made.ok && made.value.outcome !== "temporary_failure";
109
+ const why = made.ok
110
+ ? "message" in made.value
111
+ ? made.value.message
112
+ : made.value.outcome
113
+ : made.error.message;
114
+ ctx.log(`github dependabot: could not open "${card.title}"${answers ? "" : ", so the other cards wait for the next sweep"}: ${why}`);
115
+ }
116
+ return ok({ read, filed, tracked, held, below, wait });
117
+ }
@@ -0,0 +1,32 @@
1
+ import type { CardSpec } from "@kana-ai/edgar-contracts/rpc";
2
+ import type { z } from "zod";
3
+ import type { checkRun, openPull } from "#schemas/github";
4
+ import type { dependabotAlerts } from "#schemas/tools";
5
+ import { type Check } from "#tools/checks";
6
+ type OpenPull = z.infer<typeof openPull>;
7
+ type Alert = z.infer<typeof dependabotAlerts.output>["alerts"][number];
8
+ /** Where a card goes: the project's service of the repository, and the column of a new card. */
9
+ export interface Home {
10
+ readonly service: string;
11
+ readonly repo: string;
12
+ readonly column: string;
13
+ }
14
+ /** The 16 hex characters of the card block's fingerprint, from what makes the card one of a kind. */
15
+ export declare function fingerprintOf(text: string): string;
16
+ /** The card of a pull request a person asked EDGAR to review or assigned to it: lane `review`, with the pull request and its head in `decided`. Another person's pull request only; EDGAR's own `edgar/` branches are not reviewed here. */
17
+ export declare function reviewCard(home: Home, pull: OpenPull, login: string): CardSpec | undefined;
18
+ /** The failed checks of a commit by where they ran: one group per workflow run of GitHub Actions, by its run URL, and one per other check run. */
19
+ export declare function failedGroups(runs: readonly z.infer<typeof checkRun>[]): ReadonlyMap<string, readonly Check[]>;
20
+ /** One card for each failed workflow run, or other failed check, on the newest commit of the default branch: lane `fix`. */
21
+ export declare function redBranchCards(home: Home, base: string, runs: readonly z.infer<typeof checkRun>[]): readonly CardSpec[];
22
+ /** The card of EDGAR's own pull request whose checks went red: lane `fix`, naming the card the pull request belongs to. */
23
+ export declare function redPullCard(home: Home, pull: OpenPull, runs: readonly z.infer<typeof checkRun>[]): CardSpec | undefined;
24
+ /** The open alerts of one advisory of one package in a repository, one for each manifest GitHub raised it in. */
25
+ export type AlertGroup = readonly [Alert, ...Alert[]];
26
+ /** The rank of a severity, the worst highest; -1 for a word this does not know, which is filed last and never dropped. */
27
+ export declare function rankOf(severity: string): number;
28
+ /** What makes a Dependabot card one of a kind: the repository, in lower case, the advisory and the package. The alert number is not in it, because GitHub raises one alert for each manifest and one card is the change for all of them. */
29
+ export declare function alertKey(repo: string, a: Alert): string;
30
+ /** The card of one advisory of one package: kind `defect`, with the severity of its worst alert, the advisory and its link, and for each alert the manifest, the vulnerable range, the fixed version and the link. `decided.batch` is the repository, so the cards of one repository are worked one at a time and can be worked as one change. It does not judge whether the code reaches the fault; a stage reads that. */
31
+ export declare function alertCard(home: Home, alerts: AlertGroup): CardSpec;
32
+ export {};
@@ -0,0 +1,164 @@
1
+ import { createHash } from "node:crypto";
2
+ import { severities } from "#schemas/config";
3
+ import { checksOf, runOf, summaryOf } from "#tools/checks";
4
+ import { cardOf, repoPath } from "#tools/pull-request";
5
+ const TITLE_LENGTH = 120;
6
+ /** The most alerts one Dependabot card lists; a monorepo can raise one advisory in more manifests than a person reads. */
7
+ const LISTED = 20;
8
+ /** The 16 hex characters of the card block's fingerprint, from what makes the card one of a kind. */
9
+ export function fingerprintOf(text) {
10
+ return createHash("sha256").update(text).digest("hex").slice(0, 16);
11
+ }
12
+ const short = (text) => text.slice(0, TITLE_LENGTH);
13
+ /** The card of a pull request a person asked EDGAR to review or assigned to it: lane `review`, with the pull request and its head in `decided`. Another person's pull request only; EDGAR's own `edgar/` branches are not reviewed here. */
14
+ export function reviewCard(home, pull, login) {
15
+ const author = pull.user?.login;
16
+ if (author === login || cardOf(pull.head.ref) !== null)
17
+ return undefined;
18
+ const asked = pull.requested_reviewers.some((p) => p.login === login);
19
+ const assigned = pull.assignees.some((p) => p.login === login);
20
+ if (!asked && !assigned)
21
+ return undefined;
22
+ const head = pull.head.repo?.full_name ?? home.repo;
23
+ const why = asked ? "asked EDGAR to review" : "assigned EDGAR to";
24
+ const description = [
25
+ `${author ?? "Someone"} ${why} ${pull.html_url}: ${pull.title}`,
26
+ `The change is on ${head} at branch ${pull.head.ref}, commit ${pull.head.sha.slice(0, 7)}.`,
27
+ ].join("\n\n");
28
+ return {
29
+ title: short(`Review ${home.repo}#${String(pull.number)}: ${pull.title}`),
30
+ description,
31
+ column: home.column,
32
+ block: {
33
+ kind: "request",
34
+ service: home.service,
35
+ fingerprint: fingerprintOf(`github:${home.repo}#${String(pull.number)}`),
36
+ decided: {
37
+ lane: "review",
38
+ pull_request: pull.html_url,
39
+ head_repo: head,
40
+ head_branch: pull.head.ref,
41
+ },
42
+ },
43
+ };
44
+ }
45
+ /** The failed checks of a commit by where they ran: one group per workflow run of GitHub Actions, by its run URL, and one per other check run. */
46
+ export function failedGroups(runs) {
47
+ const groups = new Map();
48
+ const listed = { total_count: runs.length, check_runs: [...runs] };
49
+ checksOf(listed, { statuses: [] }).forEach((check, index) => {
50
+ if (check.state !== "failed")
51
+ return;
52
+ const url = check.url ?? "";
53
+ const run = runOf(url);
54
+ const key = run === undefined
55
+ ? url === ""
56
+ ? `check:${String(runs[index]?.id ?? check.name)}`
57
+ : url
58
+ : `https://github.com/${run.repo}/actions/runs/${run.run}`;
59
+ groups.set(key, [...(groups.get(key) ?? []), check]);
60
+ });
61
+ return groups;
62
+ }
63
+ /** One card for each failed workflow run, or other failed check, on the newest commit of the default branch: lane `fix`. */
64
+ export function redBranchCards(home, base, runs) {
65
+ const commit = runs.find((r) => r.head_sha !== undefined)?.head_sha ?? base;
66
+ return [...failedGroups(runs)].map(([where, checks]) => {
67
+ const names = checks.map((c) => c.name).join(", ");
68
+ const link = where.startsWith("https://") ? where : undefined;
69
+ return {
70
+ title: short(`${home.repo} ${base} is red: ${names}`),
71
+ description: [
72
+ `The newest commit of ${base} in ${home.repo}, ${commit.slice(0, 7)}, failed: ${names}.`,
73
+ link === undefined ? undefined : `The run is at ${link}`,
74
+ ]
75
+ .filter((line) => line !== undefined)
76
+ .join("\n\n"),
77
+ column: home.column,
78
+ block: {
79
+ kind: "defect",
80
+ service: home.service,
81
+ fingerprint: fingerprintOf(`github:${home.repo}:${where}`),
82
+ decided: {
83
+ lane: "fix",
84
+ commit,
85
+ ...(link === undefined ? {} : { run: link }),
86
+ jobs: names,
87
+ },
88
+ },
89
+ };
90
+ });
91
+ }
92
+ /** The card of EDGAR's own pull request whose checks went red: lane `fix`, naming the card the pull request belongs to. */
93
+ export function redPullCard(home, pull, runs) {
94
+ const card = cardOf(pull.head.ref);
95
+ if (card === null)
96
+ return undefined;
97
+ const checks = checksOf({ total_count: runs.length, check_runs: [...runs] }, { statuses: [] });
98
+ if (!checks.some((c) => c.state === "failed"))
99
+ return undefined;
100
+ return {
101
+ title: short(`Checks failed on ${home.repo}#${String(pull.number)} of ${card}`),
102
+ description: [
103
+ `The checks of ${pull.html_url}, which EDGAR opened for ${card}, failed on ${pull.head.sha.slice(0, 7)}. ${summaryOf(checks, pull.head.sha)}`,
104
+ `The change is on branch ${pull.head.ref}.`,
105
+ ].join("\n\n"),
106
+ column: home.column,
107
+ block: {
108
+ kind: "defect",
109
+ service: home.service,
110
+ fingerprint: fingerprintOf(`github:${home.repo}#${String(pull.number)}:checks`),
111
+ decided: {
112
+ lane: "fix",
113
+ card,
114
+ pull_request: pull.html_url,
115
+ head_branch: pull.head.ref,
116
+ commit: pull.head.sha,
117
+ },
118
+ },
119
+ };
120
+ }
121
+ /** The rank of a severity, the worst highest; -1 for a word this does not know, which is filed last and never dropped. */
122
+ export function rankOf(severity) {
123
+ return severities.findIndex((known) => known === severity.toLowerCase());
124
+ }
125
+ /** What makes a Dependabot card one of a kind: the repository, in lower case, the advisory and the package. The alert number is not in it, because GitHub raises one alert for each manifest and one card is the change for all of them. */
126
+ export function alertKey(repo, a) {
127
+ const name = repoPath(repo) ?? repo.toLowerCase();
128
+ return fingerprintOf(`github:dependabot:${name}:${a.ghsa}:${a.package ?? ""}`);
129
+ }
130
+ /** The card of one advisory of one package: kind `defect`, with the severity of its worst alert, the advisory and its link, and for each alert the manifest, the vulnerable range, the fixed version and the link. `decided.batch` is the repository, so the cards of one repository are worked one at a time and can be worked as one change. It does not judge whether the code reaches the fault; a stage reads that. */
131
+ export function alertCard(home, alerts) {
132
+ const [first] = alerts;
133
+ const worst = alerts.reduce((a, b) => (rankOf(b.severity) > rankOf(a.severity) ? b : a)).severity;
134
+ const name = first.package ?? "a package";
135
+ const where = alerts.slice(0, LISTED).map((a) => {
136
+ const fixed = a.first_patched === null ? "no fixed version yet" : `fixed in \`${a.first_patched}\``;
137
+ const scope = a.scope === null ? "" : ` (${a.scope})`;
138
+ return `- \`${a.manifest ?? "no manifest named"}\`${scope}: vulnerable in \`${a.vulnerable_range}\`, ${fixed}, ${a.url}`;
139
+ });
140
+ const more = alerts.length > LISTED ? [`- and ${String(alerts.length - LISTED)} more manifests`] : [];
141
+ return {
142
+ title: short(`${home.service}: ${name}: ${first.summary}`),
143
+ description: [
144
+ `Dependabot reports a ${worst} advisory in ${name} of ${home.repo}: ${first.summary}`,
145
+ [
146
+ `Advisory: ${first.cve === null ? first.ghsa : `${first.ghsa} (${first.cve})`}, https://github.com/advisories/${first.ghsa}`,
147
+ `Package: ${name}${first.ecosystem === null ? "" : ` (${first.ecosystem})`}`,
148
+ `Severity: ${worst}`,
149
+ `Repository: ${home.repo}`,
150
+ ].join("\n"),
151
+ ["Where GitHub raised it:", ...where, ...more].join("\n"),
152
+ `\`github__dependabot_alerts\` with \`repo\` ${home.repo} and the \`number\` of an alert reads that alert as it is now.`,
153
+ ].join("\n\n"),
154
+ column: home.column,
155
+ block: {
156
+ kind: "defect",
157
+ service: home.service,
158
+ fingerprint: alertKey(home.repo, first),
159
+ severity: worst,
160
+ occurrences: alerts.length,
161
+ decided: { batch: repoPath(home.repo) ?? home.repo.toLowerCase() },
162
+ },
163
+ };
164
+ }
@@ -0,0 +1,28 @@
1
+ import { type Ctx, type Failure, type Outcome, type Result } from "@kana-ai/edgar-sdk";
2
+ import { type TOKEN } from "#api/client";
3
+ import { type Config } from "#schemas/config";
4
+ type Watch = NonNullable<Config["watch"]>;
5
+ /** What one sweep did. */
6
+ export interface Swept {
7
+ readonly read: number;
8
+ readonly filed: number;
9
+ readonly tracked: number;
10
+ /** The seconds GitHub asks the token to wait, when a rate limit ended the sweep; else 0. */
11
+ readonly wait: number;
12
+ }
13
+ /** One sweep over each watched repository; a fingerprint this process opened already is tracked, and EDGAR answers a repeat with the open card that holds it. After a sweep that read every repository on github.com, a fingerprint whose fault is gone is forgotten. A repository that fails is logged and the sweep goes on; a rate limit ends the sweep with its wait, since the limit is the token's; a refused token ends it. */
14
+ export declare function sweep(ctx: Ctx<typeof TOKEN>, settings: Config, watch: Watch, login: string, opened: Set<string>): Promise<Result<Swept, Failure>>;
15
+ /**
16
+ * The watch: with `[extensions.github.watch]` set, a sweep every `every_seconds` until the engine stops it; without it, it only waits. A refused token ends it with its permanent failure, which opens its breaker; a repository that fails waits for the next sweep, and after a rate limit the next sweep waits as long as GitHub asks.
17
+ * shortcut: what was filed lives in memory, so a restart asks for the open cards again, and EDGAR answers each with the card it has; upgrade when a service can keep state.
18
+ * shortcut: red checks on EDGAR's own pull request open a card that names the pull request's card, since a service cannot comment on a card or start a sub-run; upgrade when the engine takes a comment from a service.
19
+ */
20
+ export declare function watch(ctx: Ctx<typeof TOKEN>): Promise<Outcome>;
21
+ /**
22
+ * The Dependabot feed: with `[extensions.github.dependabot]` set, a sweep every `every_seconds` until the engine stops it; without it, it only waits. A refused token ends it with its permanent failure, which opens its breaker; a repository that fails waits for the next sweep, and after a rate limit the next sweep waits as long as GitHub asks.
23
+ * shortcut: what was filed lives in memory, so a restart asks for the open cards again, and EDGAR answers each with the card it has; an alert that is still open after its card closed is filed again then. Upgrade when a service can keep state.
24
+ */
25
+ export declare function feedAlerts(ctx: Ctx<typeof TOKEN>): Promise<Outcome>;
26
+ /** The one service of the extension: the watch and the Dependabot feed side by side, each off without its table. When one ends with a failure, the other is stopped and the service ends with that failure. */
27
+ export declare function serve(ctx: Ctx<typeof TOKEN>): Promise<Outcome>;
28
+ export {};