@kana-ai/edgar-ext-github 0.1.2 → 0.1.3

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 (71) hide show
  1. package/README.md +130 -74
  2. package/dist/src/api/app.d.ts +25 -6
  3. package/dist/src/api/app.js +72 -9
  4. package/dist/src/api/client.d.ts +9 -6
  5. package/dist/src/api/client.js +58 -19
  6. package/dist/src/api/commits.d.ts +4 -0
  7. package/dist/src/api/commits.js +69 -0
  8. package/dist/src/api/failures.d.ts +4 -0
  9. package/dist/src/api/failures.js +14 -1
  10. package/dist/src/feed/alerts.d.ts +9 -3
  11. package/dist/src/feed/alerts.js +66 -6
  12. package/dist/src/feed/service.d.ts +10 -1
  13. package/dist/src/feed/service.js +79 -16
  14. package/dist/src/index.d.ts +97 -1
  15. package/dist/src/index.js +17 -4
  16. package/dist/src/schemas/config.d.ts +1 -0
  17. package/dist/src/schemas/config.js +73 -29
  18. package/dist/src/schemas/github.d.ts +121 -1
  19. package/dist/src/schemas/github.js +37 -2
  20. package/dist/src/schemas/tools.d.ts +159 -2
  21. package/dist/src/schemas/tools.js +129 -6
  22. package/dist/src/tools/alerts.js +1 -0
  23. package/dist/src/tools/branch.d.ts +12 -0
  24. package/dist/src/tools/branch.js +69 -1
  25. package/dist/src/tools/pull-request.d.ts +55 -7
  26. package/dist/src/tools/pull-request.js +131 -42
  27. package/dist/src/tools/revert.d.ts +27 -0
  28. package/dist/src/tools/revert.js +98 -0
  29. package/dist/src/tools/screenshot.d.ts +1 -1
  30. package/dist/src/tools/screenshot.js +25 -11
  31. package/dist/src/tracker/cards.d.ts +1 -1
  32. package/dist/src/tracker/cards.js +84 -8
  33. package/dist/src/tracker/comments.d.ts +14 -2
  34. package/dist/src/tracker/comments.js +100 -4
  35. package/dist/src/tracker/port.d.ts +1 -1
  36. package/dist/src/tracker/port.js +4 -6
  37. package/dist/src/tracker/read-link.d.ts +2 -0
  38. package/dist/src/tracker/read-link.js +23 -0
  39. package/dist/src/tracker/states.d.ts +14 -3
  40. package/dist/src/tracker/states.js +37 -6
  41. package/dist/src/tracker/tools.d.ts +27 -0
  42. package/dist/src/tracker/tools.js +63 -7
  43. package/dist/src/tracker/transitions.d.ts +14 -3
  44. package/dist/src/tracker/transitions.js +57 -10
  45. package/edgar-extension.json +121 -7
  46. package/package.json +3 -3
  47. package/schemas/attach_screenshot.in.json +19 -0
  48. package/schemas/config.json +49 -23
  49. package/schemas/create_card.in.json +4 -0
  50. package/schemas/delete_closed_branches.in.json +26 -0
  51. package/schemas/delete_closed_branches.out.json +22 -0
  52. package/schemas/find_revert_pull_request.in.json +21 -0
  53. package/schemas/find_revert_pull_request.out.json +14 -0
  54. package/schemas/list_pull_requests.out.json +5 -1
  55. package/schemas/mark_seen.in.json +11 -0
  56. package/schemas/mark_seen.out.json +10 -0
  57. package/schemas/merged_pull_request.in.json +17 -0
  58. package/schemas/merged_pull_request.out.json +18 -0
  59. package/schemas/open_pull_request.in.json +73 -1
  60. package/schemas/park.in.json +15 -0
  61. package/schemas/park.out.json +10 -0
  62. package/schemas/pull_request_state.out.json +10 -1
  63. package/schemas/release_follow_ups.in.json +5 -0
  64. package/schemas/retitle.in.json +16 -0
  65. package/schemas/retitle.out.json +13 -0
  66. package/schemas/revert_pull_request.in.json +11 -0
  67. package/schemas/revert_pull_request.out.json +14 -0
  68. package/schemas/set_priority.in.json +16 -0
  69. package/schemas/set_priority.out.json +10 -0
  70. package/schemas/update_pull_request.in.json +28 -1
  71. package/schemas/wait_for_review.out.json +10 -1
@@ -1,8 +1,9 @@
1
- import { blockLine, done, err, oneAtATime, ok, permanentFailure, readBlock, sighted, withBlock, } from "@kana-ai/edgar-sdk";
1
+ import { blockLine, done, earlierLine, err, lastNote, oneAtATime, ok, permanentFailure, readBlock, reopenedDescription, reopens, sighted, withBlock, } from "@kana-ai/edgar-sdk";
2
2
  import { z } from "zod";
3
3
  import { github, githubCounted } from "#api/client";
4
- import { foundIssues, issue, issueBy } from "#schemas/github";
5
- import { assigneeOf, cardId, ensureLabels, isHeld, inScope, isPull, isState, issueOf, marker, openStates, reposOf, settingsOf, stateOf, toCard, } from "#tracker/states";
4
+ import { cardComment, foundIssues, issue, issueBy } from "#schemas/github";
5
+ import { assigneeOf, cardId, ensureLabels, isHeld, inScope, isPull, isState, issueOf, marker, openStates, ownLogins, priorityLabels, reposOf, settingsOf, stateOf, toCard, } from "#tracker/states";
6
+ import { transition } from "#tracker/transitions";
6
7
  /** The issues of one page; GitHub's largest page is 100, and 50 keeps an answer small. */
7
8
  const PAGE = 50;
8
9
  /** The repository index and GitHub page of a `list_cards` cursor, `0:1` for none. */
@@ -37,6 +38,9 @@ export async function listCards(ctx, input) {
37
38
  const assignee = await assigneeOf(ctx, settings.value);
38
39
  if (!assignee.ok)
39
40
  return assignee.error;
41
+ const own = await ownLogins(ctx, settings.value);
42
+ if (!own.ok)
43
+ return own.error;
40
44
  const query = new URLSearchParams({
41
45
  state: "open",
42
46
  sort: "created",
@@ -53,7 +57,7 @@ export async function listCards(ctx, input) {
53
57
  const cards = listed.value.value.flatMap((found) => {
54
58
  if (isPull(found) || !inScope(settings.value, found, assignee.value))
55
59
  return [];
56
- const card = toCard(settings.value, repo, found, false);
60
+ const card = toCard(settings.value, repo, found, false, own.value);
57
61
  return card.ok && input.columns.includes(card.value.column) ? [card.value] : [];
58
62
  });
59
63
  const full = listed.value.value.length === PAGE;
@@ -85,7 +89,10 @@ export async function readCard(ctx, id) {
85
89
  if (!isHeld(settings.value, read.value, assignee.value)) {
86
90
  return permanentFailure("not_found", `github: card ${id} is out of the scope of [extensions.github.tracker]`);
87
91
  }
88
- const card = toCard(settings.value, target.value.repo, read.value, true);
92
+ const own = await ownLogins(ctx, settings.value);
93
+ if (!own.ok)
94
+ return own.error;
95
+ const card = toCard(settings.value, target.value.repo, read.value, true, own.value);
89
96
  return card.ok ? done(card.value) : card.error;
90
97
  }
91
98
  /**
@@ -178,7 +185,63 @@ async function holderOf(ctx, settings, fingerprint) {
178
185
  path: `/repos/${held.repo.repo}/issues/${String(held.item.number)}`,
179
186
  });
180
187
  }
181
- /** Files an issue inside the table's scope, or returns the open issue that already holds the block's fingerprint, counting one more sighting on it. The issue goes to the repository of the block's service, else the first; it gets `title_prefix`, `labels` and the label of `spec.column`, and with `assignee_only`, `assignee`. A retry finds the issue its first call filed by the hidden marker of the operation among the newest 10 issues of the repository. Those 10 issues are also read for an open holder of the fingerprint that the search does not index yet, and calls with one fingerprint run one at a time in this process, so the second finds the issue the first filed. */
188
+ /** The newest closed issue of the table's repositories whose block holds `fingerprint`, read to be sure as for an open one; `not_planned` is a cancelled card. */
189
+ async function closedHolderOf(ctx, settings, fingerprint) {
190
+ const repos = reposOf(settings);
191
+ const scope = repos.map((repo) => `repo:${repo.repo}`).join(" ");
192
+ const q = `${lineWords("fingerprint", fingerprint)} is:issue is:closed ${scope}`;
193
+ const query = new URLSearchParams({ q, sort: "updated", order: "desc", per_page: "5" });
194
+ const found = await github(ctx, "GET", `/search/issues?${query.toString()}`, foundIssues);
195
+ if (!found.ok)
196
+ return found;
197
+ for (const item of found.value.items) {
198
+ const repo = repos.find((known) => item.repository_url.endsWith(`/repos/${known.repo}`));
199
+ const block = readBlock(item.body ?? "");
200
+ if (repo === undefined || isPull(item) || !block.ok || block.value?.fingerprint !== fingerprint)
201
+ continue;
202
+ return ok({
203
+ id: cardId(repo, item.number),
204
+ url: item.html_url,
205
+ path: `/repos/${repo.repo}/issues/${String(item.number)}`,
206
+ cancelled: item.state_reason === "not_planned",
207
+ closed_at: item.closed_at ?? item.created_at,
208
+ });
209
+ }
210
+ return ok(undefined);
211
+ }
212
+ /** `earlierLine` for a closed issue, with the last note a person, not EDGAR or a bot, left on it before it closed, from its first 100 comments. A comment read that fails gives the line with no note: the note is context, and the new issue must still be filed.
213
+ *
214
+ * shortcut: an issue with more than 100 comments is read from its first 100 only; read the last page when long threads hold the decision.
215
+ */
216
+ async function linked(ctx, settings, closed) {
217
+ const [mine, read] = await Promise.all([
218
+ ownLogins(ctx, settings),
219
+ github(ctx, "GET", `${closed.path}/comments?per_page=100`, z.array(cardComment)),
220
+ ]);
221
+ if (!mine.ok || !read.ok)
222
+ return earlierLine(closed);
223
+ const said = read.value.map((c) => ({ text: c.body ?? "", at: c.created_at, by: c.user?.login }));
224
+ const person = (c) => c.by !== undefined && !mine.value.has(c.by) && !c.by.endsWith("[bot]");
225
+ const note = lastNote(said, closed.closed_at, person);
226
+ return earlierLine(note === undefined ? closed : { ...closed, note });
227
+ }
228
+ /** What the newest closed holder of a fingerprint comes to: opened again in `ready` when `reopens`, with `reopenedDescription` as its body, and answered; else the line that the new issue ends with. A holder out of the table's scope is linked, since its column cannot change. */
229
+ async function comeBack(ctx, settings, closed, at) {
230
+ if (!reopens(closed, at))
231
+ return await linked(ctx, settings, closed);
232
+ const moved = await transition(ctx, closed.id, "ready", true);
233
+ if (moved.outcome === "skipped")
234
+ return await linked(ctx, settings, closed);
235
+ if (moved.outcome !== "done")
236
+ return moved;
237
+ const fresh = await github(ctx, "GET", closed.path, issue);
238
+ if (!fresh.ok)
239
+ return fresh.error;
240
+ const body = reopenedDescription(fresh.value.body ?? "", at);
241
+ const written = await github(ctx, "PATCH", closed.path, issue, { body });
242
+ return written.ok ? done({ id: closed.id, url: closed.url }) : written.error;
243
+ }
244
+ /** Files an issue inside the table's scope, or returns the open issue that already holds the block's fingerprint, counting one more sighting on it. With no open holder, an issue done less than `REOPEN_DAYS` ago that holds it is opened again in `ready`; else the new issue links the newest closed holder. The issue goes to the repository of the block's service, else the first; it gets `title_prefix`, `labels` and the label of `spec.column`, and never a priority label, which only a person or `set_priority` adds, and with `assignee_only`, `assignee`. A retry finds the issue its first call filed by the hidden marker of the operation among the newest 10 issues of the repository. Those 10 issues are also read for an open holder of the fingerprint that the search does not index yet, and calls with one fingerprint run one at a time in this process, so the second finds the issue the first filed. */
182
245
  export async function createCard(ctx, spec) {
183
246
  const fingerprint = spec.block.fingerprint;
184
247
  if (fingerprint === undefined)
@@ -186,10 +249,11 @@ export async function createCard(ctx, spec) {
186
249
  return await oneAtATime(`github:${fingerprint}`, () => fileCard(ctx, spec));
187
250
  }
188
251
  /** One `create_card` call: the issue this process remembers for the fingerprint, the holder search, the newest issues, then the new issue. A retry of the operation that filed or counted on the remembered issue answers it again. */
189
- async function fileCard(ctx, spec) {
252
+ async function fileCard(ctx, asked) {
190
253
  const settings = settingsOf(ctx);
191
254
  if (!settings.ok)
192
255
  return settings.error;
256
+ let spec = asked;
193
257
  const home = homeOf(settings.value, spec);
194
258
  if (home === undefined)
195
259
  return permanentFailure("invalid", "github: no repository in repos");
@@ -236,6 +300,18 @@ async function fileCard(ctx, spec) {
236
300
  path: `/repos/${home.repo}/issues/${String(twin.number)}`,
237
301
  });
238
302
  }
303
+ if (fingerprint !== undefined) {
304
+ const closed = await closedHolderOf(ctx, settings.value, fingerprint);
305
+ if (!closed.ok)
306
+ return closed.error;
307
+ if (closed.value !== undefined) {
308
+ const at = spec.block.last_seen ?? new Date().toISOString();
309
+ const back = await comeBack(ctx, settings.value, closed.value, at);
310
+ if (typeof back === "object")
311
+ return back;
312
+ spec = { ...spec, description: `${spec.description.trimEnd()}\n\n${back}` };
313
+ }
314
+ }
239
315
  const assignee = await assigneeOf(ctx, settings.value);
240
316
  if (!assignee.ok)
241
317
  return assignee.error;
@@ -243,7 +319,7 @@ async function fileCard(ctx, spec) {
243
319
  const column = state === undefined ? undefined : settings.value.columns[state];
244
320
  const labels = [
245
321
  ...new Set([
246
- ...(spec.labels ?? []),
322
+ ...(spec.labels ?? []).filter((label) => !priorityLabels.has(label)),
247
323
  ...(settings.value.tracker.labels ?? []),
248
324
  ...(column === undefined ? [] : [column]),
249
325
  ]),
@@ -1,9 +1,21 @@
1
- import type { Comment } from "@kana-ai/edgar-contracts/rpc";
1
+ import type { Attachment, Comment, Mention } from "@kana-ai/edgar-contracts/rpc";
2
2
  import { type Outcome } from "@kana-ai/edgar-sdk";
3
3
  import { type GithubCtx } from "#tracker/states";
4
4
  /** Posts a comment with the hidden marker of the operation; a repeat finds the first comment on the issue's last page instead of posting twice. */
5
5
  export declare function postComment(ctx: GithubCtx, card: string, text: string): Promise<Outcome<{
6
6
  id: string;
7
7
  }>>;
8
- /** The first 100 comments of card `id` made after `since`, oldest first, without EDGAR's hidden marker, each flagged when it mentions EDGAR's login. */
8
+ /** Reacts with eyes to the issue as EDGAR's account; GitHub answers a repeat with the first reaction, so a retry adds none. */
9
+ export declare function markSeen(ctx: GithubCtx, card: string): Promise<Outcome<{
10
+ id: string;
11
+ }>>;
12
+ /** The pattern of a mention of `login`, which a longer login does not match. */
13
+ export declare function mentionOf(login: string): RegExp;
14
+ /** The comments made after `since` on the issues of each repository of the table that mention EDGAR's login, the first 100 of each, oldest first: one request per repository. A pull request's comment names a card id that no listing has, so the engine skips it. */
15
+ export declare function listMentions(ctx: GithubCtx, since: string): Promise<Outcome<Mention[]>>;
16
+ /** The first 100 comments of card `id` made or edited after `since`, oldest first, without EDGAR's hidden marker, each flagged when it mentions EDGAR's login, with its writer's trust and login. GitHub gives no deleted comment. */
9
17
  export declare function listComments(ctx: GithubCtx, id: string, since: string | null): Promise<Outcome<Comment[]>>;
18
+ /** The files pasted into `bodies`, once each by url, named by their link text, else by the last part of their url. */
19
+ export declare function uploadsIn(bodies: readonly string[]): Attachment[];
20
+ /** The files people pasted into the description of card `id` and into its first 100 comments: GitHub keeps no attachment apart from the text. */
21
+ export declare function listAttachments(ctx: GithubCtx, id: string): Promise<Outcome<Attachment[]>>;
@@ -2,7 +2,7 @@ import { done } from "@kana-ai/edgar-sdk";
2
2
  import { z } from "zod";
3
3
  import { github } from "#api/client";
4
4
  import { cardComment, issue } from "#schemas/github";
5
- import { issueOf, marker, ownLogin, settingsOf } from "#tracker/states";
5
+ import { cardId, issueOf, marker, ownLogin, ownLogins, reposOf, settingsOf, trustOf, } from "#tracker/states";
6
6
  /** The most comments one page answers. */
7
7
  const PAGE = 100;
8
8
  /** The hidden marker a comment of EDGAR ends with, which a reader never needs. */
@@ -33,7 +33,62 @@ export async function postComment(ctx, card, text) {
33
33
  });
34
34
  return made.ok ? done({ id: String(made.value.id) }) : made.error;
35
35
  }
36
- /** The first 100 comments of card `id` made after `since`, oldest first, without EDGAR's hidden marker, each flagged when it mentions EDGAR's login. */
36
+ /** Reacts with eyes to the issue as EDGAR's account; GitHub answers a repeat with the first reaction, so a retry adds none. */
37
+ export async function markSeen(ctx, card) {
38
+ const settings = settingsOf(ctx);
39
+ if (!settings.ok)
40
+ return settings.error;
41
+ const target = issueOf(settings.value, card);
42
+ if (!target.ok)
43
+ return target.error;
44
+ const made = await github(ctx, "POST", `${target.value.path}/reactions`, z.object({ id: z.number().int() }), { content: "eyes" });
45
+ return made.ok ? done({ id: card }) : made.error;
46
+ }
47
+ /** The pattern of a mention of `login`, which a longer login does not match. */
48
+ export function mentionOf(login) {
49
+ return new RegExp(`@${login.replace(/[[\]]/g, "\\$&")}(?![\\w-])`, "i");
50
+ }
51
+ /** The comments made after `since` on the issues of each repository of the table that mention EDGAR's login, the first 100 of each, oldest first: one request per repository. A pull request's comment names a card id that no listing has, so the engine skips it. */
52
+ export async function listMentions(ctx, since) {
53
+ const settings = settingsOf(ctx);
54
+ if (!settings.ok)
55
+ return settings.error;
56
+ const me = await ownLogin(ctx, settings.value);
57
+ if (!me.ok)
58
+ return me.error;
59
+ const own = await ownLogins(ctx, settings.value);
60
+ if (!own.ok)
61
+ return own.error;
62
+ const mention = mentionOf(me.value);
63
+ const after = Date.parse(since);
64
+ const query = new URLSearchParams({ per_page: String(PAGE), since });
65
+ const found = [];
66
+ for (const repo of reposOf(settings.value)) {
67
+ const read = await github(ctx, "GET", `/repos/${repo.repo}/issues/comments?${query.toString()}`, z.array(cardComment.extend({ issue_url: z.string() })));
68
+ if (!read.ok)
69
+ return read.error;
70
+ for (const said of read.value) {
71
+ const text = (said.body ?? "").replace(trailer, "");
72
+ const number = Number(said.issue_url.split("/").pop());
73
+ if (Date.parse(said.created_at) <= after || !mention.test(text) || !(number > 0))
74
+ continue;
75
+ found.push({
76
+ card: cardId(repo, number),
77
+ comment: {
78
+ id: String(said.id),
79
+ author: said.user?.login ?? "",
80
+ text,
81
+ at: said.created_at,
82
+ mentioned: true,
83
+ trust: trustOf(said, own.value),
84
+ ...(said.user?.login === undefined ? {} : { author_id: said.user.login }),
85
+ },
86
+ });
87
+ }
88
+ }
89
+ return done(found.sort((a, b) => a.comment.at.localeCompare(b.comment.at)));
90
+ }
91
+ /** The first 100 comments of card `id` made or edited after `since`, oldest first, without EDGAR's hidden marker, each flagged when it mentions EDGAR's login, with its writer's trust and login. GitHub gives no deleted comment. */
37
92
  export async function listComments(ctx, id, since) {
38
93
  const settings = settingsOf(ctx);
39
94
  if (!settings.ok)
@@ -44,6 +99,9 @@ export async function listComments(ctx, id, since) {
44
99
  const me = await ownLogin(ctx, settings.value);
45
100
  if (!me.ok)
46
101
  return me.error;
102
+ const own = await ownLogins(ctx, settings.value);
103
+ if (!own.ok)
104
+ return own.error;
47
105
  const query = new URLSearchParams({ per_page: String(PAGE) });
48
106
  if (since !== null)
49
107
  query.set("since", since);
@@ -51,18 +109,56 @@ export async function listComments(ctx, id, since) {
51
109
  if (!read.ok)
52
110
  return read.error;
53
111
  const after = since === null ? 0 : Date.parse(since);
54
- const mention = new RegExp(`@${me.value.replace(/[[\]]/g, "\\$&")}(?![\\w-])`, "i");
112
+ const mention = mentionOf(me.value);
55
113
  return done(read.value
56
- .filter((said) => Date.parse(said.created_at) > after)
114
+ .filter((said) => Date.parse(said.updated_at ?? said.created_at) > after)
57
115
  .map((said) => {
58
116
  const text = (said.body ?? "").replace(trailer, "");
117
+ const edited = said.updated_at === said.created_at ? undefined : said.updated_at;
59
118
  return {
60
119
  id: String(said.id),
61
120
  author: said.user?.login ?? "",
62
121
  text,
63
122
  at: said.created_at,
64
123
  mentioned: mention.test(text),
124
+ ...(edited === undefined ? {} : { edited_at: edited }),
125
+ trust: trustOf(said, own.value),
126
+ ...(said.user?.login === undefined ? {} : { author_id: said.user.login }),
65
127
  };
66
128
  })
67
129
  .sort((a, b) => a.at.localeCompare(b.at)));
68
130
  }
131
+ /** GitHub's upload hosts: `user-attachments` for today's pasted files, `user-images` for older ones. */
132
+ const HOSTS = String.raw `https:\/\/(?:github\.com\/user-attachments|user-images\.githubusercontent\.com)\/`;
133
+ /** A file pasted into a comment: a Markdown link or image with its text, or the HTML image GitHub writes for a pasted picture. */
134
+ const UPLOAD = new RegExp(String.raw `!?\[([^\]]*)\]\((${HOSTS}[^)\s]+)\)|<img\b[^>]*?\bsrc="(${HOSTS}[^"\s]+)"`, "g");
135
+ /** The files pasted into `bodies`, once each by url, named by their link text, else by the last part of their url. */
136
+ export function uploadsIn(bodies) {
137
+ const seen = new Set();
138
+ const found = [];
139
+ for (const [, text = "", link, image] of bodies.flatMap((body) => [...body.matchAll(UPLOAD)])) {
140
+ const url = link ?? image ?? "";
141
+ if (url === "" || seen.has(url))
142
+ continue;
143
+ seen.add(url);
144
+ const name = text.trim() === "" ? (url.split("/").at(-1) ?? url) : text.trim();
145
+ found.push({ id: url, name, url });
146
+ }
147
+ return found;
148
+ }
149
+ /** The files people pasted into the description of card `id` and into its first 100 comments: GitHub keeps no attachment apart from the text. */
150
+ export async function listAttachments(ctx, id) {
151
+ const settings = settingsOf(ctx);
152
+ if (!settings.ok)
153
+ return settings.error;
154
+ const target = issueOf(settings.value, id);
155
+ if (!target.ok)
156
+ return target.error;
157
+ const card = await github(ctx, "GET", target.value.path, issue.pick({ body: true }));
158
+ if (!card.ok)
159
+ return card.error;
160
+ const read = await github(ctx, "GET", `${target.value.path}/comments?per_page=${String(PAGE)}`, z.array(cardComment));
161
+ if (!read.ok)
162
+ return read.error;
163
+ return done(uploadsIn([card.value.body ?? "", ...read.value.map((said) => said.body ?? "")]));
164
+ }
@@ -1,2 +1,2 @@
1
- /** The tracker port over GitHub Issues, across each repository of `[extensions.github.tracker] repos`. With no `columns` and `tracker` tables, each method answers `invalid`. GitHub keeps no attachments apart from the body, so `attachments` answers none. */
1
+ /** The tracker port over GitHub Issues, across each repository of `[extensions.github.tracker] repos`. With no `columns` and `tracker` tables, each method answers `invalid`. `attachments` answers the files people pasted into the card and its comments. */
2
2
  export declare const tracker: import("@kana-ai/edgar-sdk").Tracker;
@@ -1,7 +1,7 @@
1
1
  import { defineTracker, done } from "@kana-ai/edgar-sdk";
2
2
  import { apiAccess } from "#api/client";
3
3
  import { createCard, listCards, readCard } from "#tracker/cards";
4
- import { listComments, postComment } from "#tracker/comments";
4
+ import { listAttachments, listComments, listMentions, postComment } from "#tracker/comments";
5
5
  import { ownLogin, personOf, settingsOf } from "#tracker/states";
6
6
  import { setLabels, transition } from "#tracker/transitions";
7
7
  function asNull(outcome) {
@@ -10,16 +10,14 @@ function asNull(outcome) {
10
10
  function asCreated(outcome) {
11
11
  return outcome.outcome === "done" ? done({ id: outcome.output.id }) : outcome;
12
12
  }
13
- /** The tracker port over GitHub Issues, across each repository of `[extensions.github.tracker] repos`. With no `columns` and `tracker` tables, each method answers `invalid`. GitHub keeps no attachments apart from the body, so `attachments` answers none. */
13
+ /** The tracker port over GitHub Issues, across each repository of `[extensions.github.tracker] repos`. With no `columns` and `tracker` tables, each method answers `invalid`. `attachments` answers the files people pasted into the card and its comments. */
14
14
  export const tracker = defineTracker({
15
15
  ...apiAccess,
16
16
  list_cards: async (input, ctx) => await listCards(ctx, input),
17
17
  card: async ({ id }, ctx) => await readCard(ctx, id),
18
18
  comments: async ({ id, since }, ctx) => await listComments(ctx, id, since),
19
- attachments: (_input, ctx) => {
20
- const settings = settingsOf(ctx);
21
- return Promise.resolve(settings.ok ? done([]) : settings.error);
22
- },
19
+ mentions: async ({ since }, ctx) => await listMentions(ctx, since),
20
+ attachments: async ({ id }, ctx) => await listAttachments(ctx, id),
23
21
  comment: async ({ card, text }, ctx) => asCreated(await postComment(ctx, card, text)),
24
22
  move: async ({ card, column }, ctx) => asNull(await transition(ctx, card, column)),
25
23
  set_labels: async ({ card, labels }, ctx) => await setLabels(ctx, card, labels),
@@ -0,0 +1,2 @@
1
+ /** Reads an issue of a repository of `[extensions.github.tracker] repos` that a card or its comments link, for a run's inbox, under the same rules as the tracker's card read: an issue out of the scope is a failure. A pull request, an issue of another repository, any other GitHub link, and every link of a project that does not use GitHub Issues as its tracker are not this reader's. */
2
+ export declare const readLink: import("@kana-ai/edgar-sdk").ReadLink;
@@ -0,0 +1,23 @@
1
+ import { cardRead, defineReadLink, ok } from "@kana-ai/edgar-sdk";
2
+ import { GIT_HOST, apiAccess } from "#api/client";
3
+ import { readCard } from "#tracker/cards";
4
+ import { listComments } from "#tracker/comments";
5
+ import { cardId, reposOf, settingsOf } from "#tracker/states";
6
+ /** The link of a GitHub issue, `https://github.com/<owner>/<repo>/issues/<number>`. A pull request's link has `pull` in place of `issues`. */
7
+ const ISSUE_LINK = /^https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/([1-9]\d*)(?:[/?#]|$)/;
8
+ /** Reads an issue of a repository of `[extensions.github.tracker] repos` that a card or its comments link, for a run's inbox, under the same rules as the tracker's card read: an issue out of the scope is a failure. A pull request, an issue of another repository, any other GitHub link, and every link of a project that does not use GitHub Issues as its tracker are not this reader's. */
9
+ export const readLink = defineReadLink({
10
+ hosts: [GIT_HOST],
11
+ ...apiAccess,
12
+ read: async (ctx, url) => {
13
+ const settings = settingsOf(ctx);
14
+ if (!settings.ok)
15
+ return ok({ kind: "not_mine" });
16
+ const [, name, number] = ISSUE_LINK.exec(url) ?? [];
17
+ const repo = reposOf(settings.value).find((known) => known.repo.toLowerCase() === name?.toLowerCase());
18
+ if (repo === undefined || number === undefined)
19
+ return ok({ kind: "not_mine" });
20
+ const id = cardId(repo, Number(number));
21
+ return cardRead(await readCard(ctx, id), await listComments(ctx, id, null));
22
+ },
23
+ });
@@ -1,4 +1,4 @@
1
- import type { Card } from "@kana-ai/edgar-contracts/rpc";
1
+ import type { Card, Trust } from "@kana-ai/edgar-contracts/rpc";
2
2
  import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
3
3
  import type { z } from "zod";
4
4
  import { TOKEN } from "#api/client";
@@ -6,6 +6,8 @@ import { type Columns, type Config, type TrackerTable } from "#schemas/config";
6
6
  import { type issue } from "#schemas/github";
7
7
  /** The label of an issue that EDGAR handed to a person; with `assignee_only`, it keeps the issue in scope while the person holds it. */
8
8
  export declare const WAITING = "edgar:waiting";
9
+ /** The priority labels, which only a person or `set_priority` adds: `create_card` drops them from what a run asks for. */
10
+ export declare const priorityLabels: ReadonlySet<string>;
9
11
  /** The engine states in their forward order. */
10
12
  export declare const states: readonly ["intake", "ready", "working", "in_review", "waiting_on_person", "in_testing", "done", "cancelled"];
11
13
  /** An engine state. */
@@ -56,10 +58,19 @@ export declare function stateOf(settings: Settings, found: Issue): State;
56
58
  export type TrackedCard = Card & {
57
59
  readonly column: State;
58
60
  };
61
+ /** Whether the writer of an issue or a comment is on the team: an association of the team, or one of EDGAR's own logins `own`. Anyone else, such as a contributor or a person with no tie to the repository, is outside. */
62
+ export declare function trustOf(written: {
63
+ readonly user?: {
64
+ readonly login: string;
65
+ } | null | undefined;
66
+ readonly author_association?: string | undefined;
67
+ }, own: ReadonlySet<string>): Trust;
59
68
  /** True when the issue is a card EDGAR still holds: closed, or open and in the table's scope. */
60
69
  export declare function isHeld(settings: Settings, found: Issue, assignee: string | undefined): boolean;
61
- /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else read as no block. */
62
- export declare function toCard(settings: Settings, repo: Repo, found: Issue, strict: boolean): Result<TrackedCard, Failure>;
70
+ /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. */
71
+ export declare function toCard(settings: Settings, repo: Repo, found: Issue, strict: boolean, own: ReadonlySet<string>): Result<TrackedCard, Failure>;
72
+ /** EDGAR's own logins: the one it works as, and `[extensions.github.tracker] assignee`. An App with no `assignee` has none, since its `[bot]` login is never a person. */
73
+ export declare function ownLogins(ctx: GithubCtx, settings: Settings): Promise<Result<ReadonlySet<string>, Failure>>;
63
74
  /** The login EDGAR works as: the login of `GITHUB_TOKEN`, found once, or with an App, `[extensions.github.tracker] assignee`, since an App's token cannot read `/user`. */
64
75
  export declare function ownLogin(ctx: GithubCtx, settings: Settings): Promise<Result<string, Failure>>;
65
76
  /** The login of `assignee_only`, or `undefined` when it is off: `assignee`, else EDGAR's own login. */
@@ -1,10 +1,17 @@
1
1
  import { createHash } from "node:crypto";
2
- import { err, ok, permanentFailure, readBlock, } from "@kana-ai/edgar-sdk";
2
+ import { err, invalidBlock, ok, permanentFailure, readBlock, } from "@kana-ai/edgar-sdk";
3
3
  import { TOKEN, github } from "#api/client";
4
4
  import { config, } from "#schemas/config";
5
5
  import { namedLabel, user, viewer } from "#schemas/github";
6
6
  /** The label of an issue that EDGAR handed to a person; with `assignee_only`, it keeps the issue in scope while the person holds it. */
7
7
  export const WAITING = "edgar:waiting";
8
+ /** The labels a person adds to give an issue a priority, the first one found winning. */
9
+ const priorities = [
10
+ ["priority:urgent", "urgent"],
11
+ ["priority:high", "high"],
12
+ ];
13
+ /** The priority labels, which only a person or `set_priority` adds: `create_card` drops them from what a run asks for. */
14
+ export const priorityLabels = new Set(priorities.map(([label]) => label));
8
15
  /** The engine states in their forward order. */
9
16
  export const states = [
10
17
  "intake",
@@ -88,32 +95,56 @@ export function stateOf(settings, found) {
88
95
  const labelled = openStates.findLast((state) => names.includes(settings.columns[state]));
89
96
  return labelled ?? "intake";
90
97
  }
98
+ /** GitHub's author associations of the team: the repository's owner, a member of the organization that owns it, and a collaborator. */
99
+ const team = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
100
+ /** Whether the writer of an issue or a comment is on the team: an association of the team, or one of EDGAR's own logins `own`. Anyone else, such as a contributor or a person with no tie to the repository, is outside. */
101
+ export function trustOf(written, own) {
102
+ const login = written.user?.login;
103
+ const mine = login !== undefined && own.has(login);
104
+ return mine || team.has(written.author_association ?? "") ? "team" : "outside";
105
+ }
91
106
  /** True when the issue is a card EDGAR still holds: closed, or open and in the table's scope. */
92
107
  export function isHeld(settings, found, assignee) {
93
108
  return found.state === "closed" || inScope(settings, found, assignee);
94
109
  }
95
- /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else read as no block. */
96
- export function toCard(settings, repo, found, strict) {
110
+ /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. */
111
+ export function toCard(settings, repo, found, strict, own) {
97
112
  const description = found.body ?? "";
98
113
  const block = readBlock(description);
99
114
  if (!block.ok && strict)
100
115
  return block;
101
- const read = block.ok ? block.value : null;
102
116
  const columns = new Set(Object.values(settings.columns));
103
117
  const assigned = found.assignees?.[0]?.login;
118
+ const taken = found.assignees?.find((person) => !own.has(person.login) && !person.login.endsWith("[bot]"))?.login;
119
+ const names = labelNames(found);
120
+ const priority = priorities.find(([label]) => names.includes(label))?.[1];
104
121
  return ok({
105
122
  id: cardId(repo, found.number),
106
123
  title: found.title,
107
124
  description,
108
125
  column: stateOf(settings, found),
109
- labels: labelNames(found).filter((name) => !columns.has(name)),
126
+ labels: names.filter((name) => !columns.has(name)),
110
127
  url: found.html_url,
111
- block: { ...(read ?? { kind: "request" }), service: repo.service },
128
+ block: block.ok
129
+ ? { ...(block.value ?? { kind: "request" }), service: repo.service }
130
+ : invalidBlock(block.error),
112
131
  ...(assigned === undefined ? {} : { assignee: assigned }),
132
+ ...(taken === undefined ? {} : { taken_by: taken, taken_by_id: taken }),
133
+ ...(priority === undefined ? {} : { priority }),
134
+ trust: trustOf(found, own),
135
+ ...(found.user?.login === undefined ? {} : { written_by_id: found.user.login }),
113
136
  });
114
137
  }
115
138
  /** The logins found so far, by the token that signs in, kept for the life of the process. */
116
139
  const logins = new Map();
140
+ /** EDGAR's own logins: the one it works as, and `[extensions.github.tracker] assignee`. An App with no `assignee` has none, since its `[bot]` login is never a person. */
141
+ export async function ownLogins(ctx, settings) {
142
+ const named = settings.tracker.assignee === undefined ? [] : [settings.tracker.assignee];
143
+ if (settings.table.app !== undefined)
144
+ return ok(new Set(named));
145
+ const me = await ownLogin(ctx, settings);
146
+ return me.ok ? ok(new Set([me.value, ...named])) : me;
147
+ }
117
148
  /** The login EDGAR works as: the login of `GITHUB_TOKEN`, found once, or with an App, `[extensions.github.tracker] assignee`, since an App's token cannot read `/user`. */
118
149
  export async function ownLogin(ctx, settings) {
119
150
  if (settings.table.app !== undefined) {
@@ -43,6 +43,7 @@ export declare const trackerTools: {
43
43
  channel: string;
44
44
  thread: string;
45
45
  };
46
+ trust?: "outside" | "team";
46
47
  };
47
48
  };
48
49
  parent?: string;
@@ -50,13 +51,26 @@ export declare const trackerTools: {
50
51
  id: string;
51
52
  url: string;
52
53
  }, "GITHUB_TOKEN">;
54
+ park: import("@kana-ai/edgar-sdk").Tool<{
55
+ card: string;
56
+ waits_for: string;
57
+ }, {
58
+ id: string;
59
+ }, "GITHUB_TOKEN">;
53
60
  release_follow_ups: import("@kana-ai/edgar-sdk").Tool<{
54
61
  card: string;
55
62
  pull_request: string;
63
+ column?: "ready" | "waiting_on_person";
56
64
  }, {
57
65
  released: string[];
58
66
  }, "GITHUB_TOKEN">;
59
67
  /** A retry with the same `seen_at` finds the sighting counted and writes nothing; with no `seen_at`, a retry whose first answer was lost counts it twice. */
68
+ set_priority: import("@kana-ai/edgar-sdk").Tool<{
69
+ card: string;
70
+ priority: "high" | "low" | "medium" | "urgent";
71
+ }, {
72
+ id: string;
73
+ }, "GITHUB_TOKEN">;
60
74
  count_sighting: import("@kana-ai/edgar-sdk").Tool<{
61
75
  card: string;
62
76
  seen_at?: string;
@@ -96,6 +110,12 @@ export declare const trackerTools: {
96
110
  to: string;
97
111
  previous: string;
98
112
  }, "GITHUB_TOKEN">;
113
+ /** GitHub keeps one reaction of a kind per account, so a retry adds none. */
114
+ mark_seen: import("@kana-ai/edgar-sdk").Tool<{
115
+ card: string;
116
+ }, {
117
+ id: string;
118
+ }, "GITHUB_TOKEN">;
99
119
  /** A retry writes the same text again, which changes nothing; the lookup tells boot whether a call that did not end wrote it. */
100
120
  update_description: import("@kana-ai/edgar-sdk").Tool<{
101
121
  card: string;
@@ -104,6 +124,13 @@ export declare const trackerTools: {
104
124
  id: string;
105
125
  previous?: string | undefined;
106
126
  }, "GITHUB_TOKEN">;
127
+ retitle: import("@kana-ai/edgar-sdk").Tool<{
128
+ card: string;
129
+ text: string;
130
+ }, {
131
+ id: string;
132
+ title: string;
133
+ }, "GITHUB_TOKEN">;
107
134
  restore_description: import("@kana-ai/edgar-sdk").Tool<{
108
135
  stage_output: {
109
136
  id: string;