@davidbyoung/software-factory 0.1.11 → 0.1.12

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 (56) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +7 -7
  5. package/dist/board.mjs +50 -33
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +15 -6
  13. package/dist/lib/clock.d.mts +3 -1
  14. package/dist/lib/clock.mjs +12 -6
  15. package/dist/lib/pull-tickets.d.mts +15 -0
  16. package/dist/lib/pull-tickets.mjs +12 -0
  17. package/dist/lib/usage.d.mts +3 -1
  18. package/dist/lib/usage.mjs +4 -2
  19. package/dist/lib/work-status.d.mts +23 -19
  20. package/dist/lib/work-status.mjs +14 -27
  21. package/dist/poller.d.mts +3 -3
  22. package/dist/poller.mjs +18 -14
  23. package/dist/pr.d.mts +18 -0
  24. package/dist/pr.mjs +54 -7
  25. package/dist/review-tickets.d.mts +12 -0
  26. package/dist/review-tickets.mjs +59 -0
  27. package/dist/reviewers.d.mts +7 -4
  28. package/dist/reviewers.mjs +19 -12
  29. package/dist/runner/github-actions.mjs +6 -7
  30. package/dist/runner/types.d.mts +7 -6
  31. package/dist/status.d.mts +17 -7
  32. package/dist/status.mjs +35 -23
  33. package/dist/sync.d.mts +4 -0
  34. package/dist/sync.mjs +14 -1
  35. package/dist/ticket.d.mts +13 -7
  36. package/dist/ticket.mjs +94 -60
  37. package/dist/tickets/github.d.mts +10 -2
  38. package/dist/tickets/github.mjs +74 -20
  39. package/dist/tickets/index.d.mts +7 -1
  40. package/dist/tickets/index.mjs +15 -1
  41. package/dist/tickets/types.d.mts +59 -30
  42. package/dist/tickets/types.mjs +13 -3
  43. package/docs/cli.md +11 -7
  44. package/docs/configuration.md +1 -1
  45. package/docs/developing.md +16 -8
  46. package/docs/github/reference.md +1 -1
  47. package/docs/plugins.md +6 -6
  48. package/package.json +1 -1
  49. package/review.md +11 -11
  50. package/rules.md +18 -14
  51. package/skills/factory-address-review/SKILL.md +4 -3
  52. package/skills/factory-build/SKILL.md +25 -19
  53. package/skills/factory-refine/SKILL.md +1 -1
  54. package/skills/factory-resolve-conflicts/SKILL.md +4 -3
  55. package/workflows/factory-build.yml +6 -5
  56. package/workflows/factory-claude-review.yml +38 -1
package/dist/ticket.mjs CHANGED
@@ -16,14 +16,14 @@
16
16
  // And the reads and writes the skills make, through the ticket interface
17
17
  // (`tickets/`), so no skill calls a ticket system itself:
18
18
  //
19
- // factory ticket view N [--field title|state|labels|body] [--json]
19
+ // factory ticket view N [--field title|state|labels|body|ref] [--json]
20
20
  // factory ticket answers N # the comments that count as answers
21
21
  // factory ticket list [--label LABEL] [--title "TITLE"] [--json]
22
22
  // factory ticket edit N [--title TITLE] [--body-file FILE [--attach FILE]...]
23
23
  // factory ticket comment N --body-file FILE [--attach FILE]...
24
24
  // factory ticket open --title TITLE --body-file FILE [--label LABEL]...
25
25
  // factory ticket label N --add LABEL | --remove LABEL | --was-removed LABEL
26
- // factory ticket link N
26
+ // factory ticket link N [--part]
27
27
  // factory ticket blockers N
28
28
  // factory ticket block N --by M
29
29
  // factory ticket unblock N --by M
@@ -33,8 +33,9 @@
33
33
  // `waiting`, `refined`, `stop`, and `cost` post what the session and its
34
34
  // subagents spent, as a share of the subscription and at API list prices,
35
35
  // since the clock started, or since the
36
- // session started when it has none, then restart it. `cost` posts to issue
37
- // or pull request N. The clock is keyed by CLAUDE_CODE_SESSION_ID, the ID the
36
+ // session started when it has none, then restart it. `cost` posts to ticket
37
+ // N; `factory pr cost` posts to a pull request. The clock is keyed by
38
+ // CLAUDE_CODE_SESSION_ID, the ID the
38
39
  // hooks receive and the transcript's file name.
39
40
  //
40
41
  // `refined` posts its marker only on a ticket whose body a build can read
@@ -67,20 +68,22 @@ import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
67
68
  import { boardConfigOf, checkFields } from "./board.mjs";
68
69
  import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
69
70
  import { openTickets } from "./tickets/index.mjs";
70
- import { GROUPS, need, supports, } from "./tickets/types.mjs";
71
+ import { GROUPS, compareKeys, need, supports, } from "./tickets/types.mjs";
72
+ import { linkPulls, ownLinks } from "./lib/pull-tickets.mjs";
71
73
  import { NotSignedInError } from "./code-host/types.mjs";
72
74
  export async function readComments(c, issue) {
73
75
  return (await c.tickets.read(issue)).comments;
74
76
  }
75
77
  /** The cost note for what this session spent since its clock started, and
76
- * the clock restarted from now. */
77
- function takeCost(issue, d) {
78
+ * the clock restarted from now. `on` is where the note is posted, as
79
+ * written in prose. */
80
+ export function takeCost(on, d) {
78
81
  const session = d.env.CLAUDE_CODE_SESSION_ID ?? "";
79
82
  if (!session)
80
- return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, issue, session);
83
+ return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, on, session);
81
84
  const clock = d.clock.read(session);
82
85
  const now = d.now().toISOString();
83
- const note = costNote(measure(d, session, clock?.start ?? null), issue, session);
86
+ const note = costNote(measure(d, session, clock?.start ?? null), on, session);
84
87
  // Only claim and refining choose the issue: a note posted elsewhere, such
85
88
  // as on a pull request, keeps the clock's.
86
89
  d.clock.write(session, { issue: clock ? clock.issue : null, start: now });
@@ -106,6 +109,11 @@ function startClock(issue, d) {
106
109
  async function post(c, issue, kind) {
107
110
  return c.tickets.comment(issue, commentBody(kind, c.config.columns));
108
111
  }
112
+ /** The ticket as a comment names it. */
113
+ const named = (c, key) => ({
114
+ key,
115
+ ref: c.tickets.ref(key),
116
+ });
109
117
  async function remove(c, commentId) {
110
118
  await c.tickets.deleteComment(commentId);
111
119
  }
@@ -115,7 +123,7 @@ export async function openBlockers(c, issue) {
115
123
  if (!c.tickets.blockers)
116
124
  return [];
117
125
  const blockers = await c.tickets.blockers.list(issue);
118
- return blockers.filter((b) => b.state === "open").map((b) => b.number);
126
+ return blockers.filter((b) => b.state === "open").map((b) => b.key);
119
127
  }
120
128
  /** The outcome of a claim, as `factory-build` reads it. */
121
129
  export function claimOutcome(comments, mine) {
@@ -133,7 +141,7 @@ async function claim(issue, who, d) {
133
141
  await post(d, issue, {
134
142
  kind: "stopped",
135
143
  where: "actions",
136
- issue,
144
+ issue: named(d, issue),
137
145
  reason,
138
146
  });
139
147
  };
@@ -146,7 +154,7 @@ async function claim(issue, who, d) {
146
154
  throw error;
147
155
  }
148
156
  if (blockers.length > 0) {
149
- const list = blockers.map((n) => `#${n}`).join(", ");
157
+ const list = blockers.map((k) => d.tickets.ref(k)).join(", ");
150
158
  await stopUnattended(`it waits on ${list}, which has to merge first`);
151
159
  return `blocked by: ${list}`;
152
160
  }
@@ -189,10 +197,10 @@ async function end(issue, who, d) {
189
197
  (live.marker.where === who.where && live.marker.id === who.id));
190
198
  if (!mine)
191
199
  return "not live";
192
- const pulls = await d.openPulls(d.repository, d.codeHost);
200
+ const pulls = linkPulls(await d.openPulls(d.repository, d.codeHost), d.tickets, d.own);
193
201
  if (reviewingPulls(ticket, pulls).length > 0)
194
202
  return "kept";
195
- await post(d, issue, { kind: "ended", issue });
203
+ await post(d, issue, { kind: "ended", issue: named(d, issue) });
196
204
  return "released";
197
205
  }
198
206
  export function withLine(body, line) {
@@ -203,11 +211,11 @@ export function withLine(body, line) {
203
211
  async function followUp(file, text, d) {
204
212
  const line = `- [ ] ${file}: ${text}`;
205
213
  const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes("follow-up"));
206
- const [first] = open.sort((a, b) => a.number - b.number);
214
+ const [first] = open.sort((a, b) => compareKeys(a.key, b.key));
207
215
  if (first) {
208
- const issue = await d.tickets.read(first.number);
209
- await d.tickets.writeBody(first.number, withLine(issue.body, line));
210
- return `added to #${first.number}`;
216
+ const issue = await d.tickets.read(first.key);
217
+ await d.tickets.writeBody(first.key, withLine(issue.body, line));
218
+ return `added to ${d.tickets.ref(first.key)}`;
211
219
  }
212
220
  const body = withLine('Small problems noticed while doing other work, one line each, built together once the owner approves this issue. See "Follow-ups" in `.claude/factory/rules.md`.\n', line);
213
221
  const made = await d.tickets.open({
@@ -215,23 +223,24 @@ async function followUp(file, text, d) {
215
223
  labels: ["follow-up"],
216
224
  body,
217
225
  });
218
- return `opened #${made}`;
226
+ return `opened ${d.tickets.ref(made)}`;
219
227
  }
220
228
  /** Set the card's Status to Ready, as the owner would. */
221
229
  async function moveToReady(issue, d) {
230
+ const ref = d.tickets.ref(issue);
222
231
  const found = await d.tickets.read(issue);
223
232
  if (found.state !== "open")
224
- throw new Error(`#${issue} is closed.`);
233
+ throw new Error(`${ref} is closed.`);
225
234
  if (d.board === null)
226
235
  throw new Error("The settings name no board.");
227
236
  const ready = d.config.columns.Ready?.[0] ?? null;
228
237
  if (ready === null)
229
- throw new Error(`This board has no column for ready. Tell a session to build #${issue}, or run factory build ${issue}.`);
238
+ throw new Error(`This board has no column for ready. Tell a session to build ${ref}, or run factory build ${issue}.`);
230
239
  const board = need(d.tickets, "board");
231
240
  const read = await board.read();
232
241
  const item = read.items.get(issue);
233
242
  if (!item)
234
- throw new Error(`#${issue} is not on the board.`);
243
+ throw new Error(`${ref} is not on the board.`);
235
244
  if (item.status !== null && sameName(item.status, ready))
236
245
  return;
237
246
  const fields = checkFields(read.fields, d.config);
@@ -273,9 +282,9 @@ function options(args, name) {
273
282
  }
274
283
  /** A ticket for a reader: title, state, labels, body, and each comment with
275
284
  * its ID and author. */
276
- export function formatTicket(t) {
285
+ export function formatTicket(t, ref) {
277
286
  const lines = [
278
- `#${t.number} ${t.title}`,
287
+ `${ref} ${t.title}`,
279
288
  `state: ${t.state}`,
280
289
  `labels: ${t.labels.join(", ") || "(none)"}`,
281
290
  "",
@@ -304,7 +313,12 @@ async function answersOf(t, ticket) {
304
313
  .filter((c) => deciders.has(c.author))
305
314
  .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
306
315
  }
307
- const FIELDS = ["title", "state", "labels", "body"];
316
+ const FIELDS = ["title", "state", "labels", "body", "ref"];
317
+ /** A ticket as `--json` prints it: its key, then its written form. */
318
+ const withRef = (t, tickets) => {
319
+ const { key, ...rest } = t;
320
+ return { key, ref: tickets.ref(key), ...rest };
321
+ };
308
322
  const READS_AND_WRITES = new Set([
309
323
  "view",
310
324
  "answers",
@@ -332,42 +346,41 @@ async function branchOf(ticket, d) {
332
346
  throw e;
333
347
  throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
334
348
  }
335
- return d.branchName
336
- .replaceAll("{ticket}", String(ticket))
337
- .replaceAll("{user}", user);
349
+ return d.branchName.replaceAll("{ticket}", ticket).replaceAll("{user}", user);
338
350
  }
339
351
  /** The commands that read or write a ticket for a skill. Null when
340
352
  * `command` is not one of them. */
341
353
  async function ticketCommand(command, args, d) {
342
354
  const t = d.tickets;
343
- const n = Number(args[0]);
344
- const numbered = () => {
345
- if (!Number.isInteger(n) || n <= 0)
355
+ const keyed = () => {
356
+ if (!args[0] || args[0].startsWith("--"))
346
357
  throw new Error(USAGE);
347
- return n;
358
+ return t.key(args[0]);
348
359
  };
349
360
  const json = args.includes("--json");
350
361
  switch (command) {
351
362
  case "view": {
352
- const ticket = await t.read(numbered());
363
+ const ticket = await t.read(keyed());
353
364
  const field = option(args, "--field");
354
365
  if (json)
355
- d.out(JSON.stringify(ticket, null, 2));
366
+ d.out(JSON.stringify(withRef(ticket, t), null, 2));
356
367
  else if (field === undefined)
357
- formatTicket(ticket).forEach(d.out);
368
+ formatTicket(ticket, t.ref(ticket.key)).forEach(d.out);
358
369
  else if (!FIELDS.includes(field))
359
370
  throw new Error(`--field is one of ${FIELDS.join(", ")}.`);
360
371
  else if (field === "labels")
361
372
  ticket.labels.forEach(d.out);
373
+ else if (field === "ref")
374
+ d.out(t.ref(ticket.key));
362
375
  else
363
376
  d.out(String(ticket[field]));
364
377
  return 0;
365
378
  }
366
379
  case "answers": {
367
- const ticket = await t.read(numbered());
380
+ const ticket = await t.read(keyed());
368
381
  const answers = await answersOf(t, ticket);
369
382
  if (answers.length === 0)
370
- d.out(`#${ticket.number} has no answers from an approver yet.`);
383
+ d.out(`${t.ref(ticket.key)} has no answers from an approver yet.`);
371
384
  answers.forEach((c, i) => {
372
385
  if (i > 0)
373
386
  d.out("");
@@ -381,17 +394,17 @@ async function ticketCommand(command, args, d) {
381
394
  const kept = (await t.listOpen())
382
395
  .filter((x) => label === undefined || x.labels.includes(label))
383
396
  .filter((x) => title === undefined || x.title === title)
384
- .sort((a, b) => a.number - b.number);
397
+ .sort((a, b) => compareKeys(a.key, b.key));
385
398
  if (json)
386
- d.out(JSON.stringify(kept, null, 2));
399
+ d.out(JSON.stringify(kept.map((x) => withRef(x, t)), null, 2));
387
400
  else
388
401
  for (const x of kept)
389
- d.out(`${x.number}\t${x.title}\t${x.labels.join(", ")}`);
402
+ d.out(`${x.key}\t${x.title}\t${x.labels.join(", ")}`);
390
403
  return 0;
391
404
  }
392
405
  case "edit":
393
406
  case "comment": {
394
- const ticket = numbered();
407
+ const ticket = keyed();
395
408
  const file = option(args, "--body-file");
396
409
  const newTitle = command === "edit" ? option(args, "--title") : undefined;
397
410
  if (!file && newTitle === undefined)
@@ -438,7 +451,7 @@ async function ticketCommand(command, args, d) {
438
451
  return 0;
439
452
  }
440
453
  case "label": {
441
- const ticket = numbered();
454
+ const ticket = keyed();
442
455
  const add = option(args, "--add");
443
456
  const removed = option(args, "--remove");
444
457
  const was = option(args, "--was-removed");
@@ -450,7 +463,6 @@ async function ticketCommand(command, args, d) {
450
463
  d.out((await history.wasRemoved(ticket, was)) ? "yes" : "no");
451
464
  }
452
465
  else if (add !== undefined) {
453
- // GitHub labels a pull request through its ticket API too.
454
466
  refuseOverride(add);
455
467
  await t.addLabel(ticket, add);
456
468
  d.out("added");
@@ -462,25 +474,26 @@ async function ticketCommand(command, args, d) {
462
474
  return 0;
463
475
  }
464
476
  case "link":
465
- d.out(t.linkText(numbered()));
477
+ d.out(t.linkText(keyed(), args.includes("--part") ? "part" : "closes"));
466
478
  return 0;
467
479
  case "branch": {
468
- const ticket = await t.read(numbered());
469
- d.out(await branchOf(ticket.number, d));
480
+ const ticket = await t.read(keyed());
481
+ d.out(await branchOf(ticket.key, d));
470
482
  return 0;
471
483
  }
472
484
  case "blockers": {
473
- const list = await need(t, "blockers").list(numbered());
485
+ const list = await need(t, "blockers").list(keyed());
474
486
  for (const b of list)
475
- d.out(`#${b.number} ${b.state}`);
487
+ d.out(`${t.ref(b.key)} ${b.state}`);
476
488
  return 0;
477
489
  }
478
490
  case "block":
479
491
  case "unblock": {
480
- const ticket = numbered();
481
- const by = Number(option(args, "--by"));
482
- if (!Number.isInteger(by) || by <= 0)
492
+ const ticket = keyed();
493
+ const given = option(args, "--by");
494
+ if (given === undefined)
483
495
  throw new Error(USAGE);
496
+ const by = t.key(given);
484
497
  const blockers = need(t, "blockers");
485
498
  if (command === "block")
486
499
  await blockers.add(ticket, by);
@@ -493,10 +506,21 @@ async function ticketCommand(command, args, d) {
493
506
  return null;
494
507
  }
495
508
  }
509
+ /** The steps after the reads and writes, each on one ticket. */
510
+ const STEPS = new Set([
511
+ "claim",
512
+ "still-live",
513
+ "stop",
514
+ "end",
515
+ "ready",
516
+ "refining",
517
+ "waiting",
518
+ "cost",
519
+ "refined",
520
+ ]);
496
521
  const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|answers|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
497
522
  export async function main(argv, deps) {
498
523
  const [command, first, ...rest] = argv;
499
- const issue = Number(first);
500
524
  try {
501
525
  // `supports` answers before anything is read: it names the groups.
502
526
  const settings = await deps.settings();
@@ -511,6 +535,7 @@ export async function main(argv, deps) {
511
535
  repository,
512
536
  board,
513
537
  ...opened,
538
+ own: ownLinks(settings),
514
539
  };
515
540
  if (command === "supports") {
516
541
  if (!first || !GROUPS.includes(first))
@@ -527,8 +552,9 @@ export async function main(argv, deps) {
527
552
  const handled = await ticketCommand(command ?? "", first === undefined ? rest : [first, ...rest], d);
528
553
  if (handled !== null)
529
554
  return handled;
530
- if (!command || !Number.isInteger(issue) || issue <= 0)
555
+ if (!STEPS.has(command ?? "") || !first || first.startsWith("--"))
531
556
  throw new Error(USAGE);
557
+ const issue = d.tickets.key(first);
532
558
  if (command === "still-live") {
533
559
  const live = await stillLive(issue, d);
534
560
  d.out(live ? "live" : "not live");
@@ -549,9 +575,9 @@ export async function main(argv, deps) {
549
575
  await post(d, issue, {
550
576
  kind: "stopped",
551
577
  where: who.where,
552
- issue,
578
+ issue: named(d, issue),
553
579
  reason: rest[0],
554
- cost: takeCost(issue, d),
580
+ cost: takeCost(d.tickets.ref(issue), d),
555
581
  });
556
582
  d.out("released");
557
583
  return 0;
@@ -568,10 +594,18 @@ export async function main(argv, deps) {
568
594
  startClock(issue, d);
569
595
  break;
570
596
  case "waiting":
571
- await post(d, issue, { kind: "waiting", cost: takeCost(issue, d) });
597
+ await post(d, issue, {
598
+ kind: "waiting",
599
+ cost: takeCost(d.tickets.ref(issue), d),
600
+ });
572
601
  break;
573
602
  case "cost":
574
- await post(d, issue, { kind: "cost", cost: takeCost(issue, d) });
603
+ // Read first: a number that is no ticket leaves the clock.
604
+ await d.tickets.read(issue);
605
+ await post(d, issue, {
606
+ kind: "cost",
607
+ cost: takeCost(d.tickets.ref(issue), d),
608
+ });
575
609
  break;
576
610
  case "refined": {
577
611
  // A body the build could not read gets no marker, whoever wrote it.
@@ -590,9 +624,9 @@ export async function main(argv, deps) {
590
624
  const before = at === -1 ? undefined : d.readFile(rest[at + 1]);
591
625
  await post(d, issue, {
592
626
  kind: "refined",
593
- issue,
627
+ issue: named(d, issue),
594
628
  before,
595
- cost: takeCost(issue, d),
629
+ cost: takeCost(d.tickets.ref(issue), d),
596
630
  });
597
631
  break;
598
632
  }
@@ -632,7 +666,7 @@ export async function run(argv) {
632
666
  claimStore: {
633
667
  read: (issue) => {
634
668
  const path = claimPath(issue);
635
- return existsSync(path) ? Number(readFileSync(path, "utf8")) : null;
669
+ return existsSync(path) ? readFileSync(path, "utf8").trim() : null;
636
670
  },
637
671
  write: (issue, id) => writeFileSync(claimPath(issue), String(id)),
638
672
  },
@@ -1,5 +1,5 @@
1
1
  import type { Gh } from "../lib/gh.mts";
2
- import { type Board, type BoardField, type NewField, type Ticket, type TicketComment, type Tickets } from "./types.mts";
2
+ import { type Key, type LinkKind, type Links, type Board, type BoardField, type NewField, type Ticket, type TicketComment, type Tickets } from "./types.mts";
3
3
  import { type Transport } from "./transport.mts";
4
4
  export type GithubOptions = {
5
5
  transport: Transport;
@@ -123,6 +123,14 @@ type StatusOption = {
123
123
  * valid GraphQL. */
124
124
  export declare function setColumnsMutation(field: string, options: StatusOption[]): string;
125
125
  /** The id in the URL `gh issue comment` prints. */
126
- export declare function commentIdFromUrl(url: string): number;
126
+ export declare function commentIdFromUrl(url: string): string;
127
+ /** A key typed for GitHub: an issue's number. */
128
+ export declare function githubKey(typed: string): Key;
129
+ /** How GitHub writes a ticket: `#12`, or `owner/repo#4` for one in another
130
+ * repository, whose key is already written that way. */
131
+ export declare const githubRef: (key: Key) => string;
132
+ export declare const githubLinkText: (key: Key, kind: LinkKind) => string;
133
+ /** The `Closes #N` and `Part of #N` lines in a pull request's body. */
134
+ export declare function githubLinksIn(body: string): Links;
127
135
  export declare function githubTickets(o: GithubOptions): Tickets;
128
136
  export {};
@@ -6,12 +6,12 @@
6
6
  import { rmSync, writeFileSync } from "node:fs";
7
7
  import { tmpdir } from "node:os";
8
8
  import { dirname, join } from "node:path";
9
- import { NotFoundError, } from "./types.mjs";
9
+ import { KeyError, NotFoundError, } from "./types.mjs";
10
10
  import { writeAccess } from "./github-access.mjs";
11
11
  import { statusOf } from "./transport.mjs";
12
12
  import { sameName } from "../lib/work-status.mjs";
13
13
  const toComment = (raw) => ({
14
- id: raw.id,
14
+ id: String(raw.id),
15
15
  createdAt: raw.created_at,
16
16
  body: raw.body ?? "",
17
17
  author: raw.user?.login ?? "ghost",
@@ -51,14 +51,14 @@ fragment issue on Issue {
51
51
  }
52
52
  }`;
53
53
  export const toComments = (raw) => (raw?.nodes ?? []).map((c) => ({
54
- id: c.databaseId,
54
+ id: String(c.databaseId),
55
55
  createdAt: c.createdAt,
56
56
  body: c.body,
57
57
  author: c.author?.login ?? "ghost",
58
58
  }));
59
59
  export function fromRawIssue(raw) {
60
60
  return {
61
- number: raw.number,
61
+ key: String(raw.number),
62
62
  title: raw.title,
63
63
  state: raw.state === "OPEN" ? "open" : "closed",
64
64
  closedAt: raw.closedAt,
@@ -125,9 +125,9 @@ export function toBoard(pages, repository) {
125
125
  if (number === undefined ||
126
126
  raw.content?.repository?.nameWithOwner !== repository)
127
127
  continue;
128
- items.set(number, {
128
+ items.set(String(number), {
129
129
  itemId: raw.id,
130
- number,
130
+ key: String(number),
131
131
  status: raw.status?.name ?? null,
132
132
  updatedAt: raw.status?.updatedAt ?? null,
133
133
  session: raw.session?.text ?? "",
@@ -208,7 +208,29 @@ export function commentIdFromUrl(url) {
208
208
  const match = /#issuecomment-(\d+)/.exec(url);
209
209
  if (!match)
210
210
  throw new Error(`gh printed no comment address: ${url.trim()}`);
211
- return Number(match[1]);
211
+ return match[1];
212
+ }
213
+ /** A key typed for GitHub: an issue's number. */
214
+ export function githubKey(typed) {
215
+ if (/^[1-9]\d*$/.test(typed))
216
+ return typed;
217
+ if (/^[\w.-]+\/[\w.-]+#\d+$/.test(typed))
218
+ throw new KeyError(`${typed} is in another repository: the factory reads only its state as a blocker`);
219
+ throw new KeyError(`${typed} is not a ticket here: a GitHub ticket is its number, such as 12`);
220
+ }
221
+ /** How GitHub writes a ticket: `#12`, or `owner/repo#4` for one in another
222
+ * repository, whose key is already written that way. */
223
+ export const githubRef = (key) => key.includes("/") ? key : `#${key}`;
224
+ export const githubLinkText = (key, kind) => `${kind === "closes" ? "Closes" : "Part of"} ${githubRef(key)}`;
225
+ /** The `Closes #N` and `Part of #N` lines in a pull request's body. */
226
+ export function githubLinksIn(body) {
227
+ const links = { closes: [], partOf: [] };
228
+ for (const m of body.matchAll(/\b(closes|part of) #(\d+)(?!\d)/gi)) {
229
+ const list = m[1].toLowerCase() === "closes" ? links.closes : links.partOf;
230
+ if (!list.includes(m[2]))
231
+ list.push(m[2]);
232
+ }
233
+ return links;
212
234
  }
213
235
  const ISSUE_FIELDS = `query IssueFields($owner: String!, $name: String!) {
214
236
  repository(owner: $owner, name: $name) {
@@ -244,6 +266,18 @@ export function githubTickets(o) {
244
266
  const t = o.transport;
245
267
  let lastBoard = null;
246
268
  const issue = (n) => found(`#${n}`, t.rest("GET", `${API}/issues/${n}`));
269
+ // GitHub numbers issues and pull requests from one sequence, and its
270
+ // issues API writes to either, so a write first checks that the number
271
+ // is an issue.
272
+ const issues = new Set();
273
+ const anIssue = async (n) => {
274
+ if (issues.has(n))
275
+ return;
276
+ const raw = await issue(n);
277
+ if (raw.pull_request)
278
+ throw new NotFoundError(`#${n}`);
279
+ issues.add(n);
280
+ };
247
281
  /** Board `number`'s Status field, or null when it has none. */
248
282
  const statusField = async (number) => {
249
283
  const answer = await t.graphql(STATUS_FIELD, { owner: o.boardOwner ?? repoOwner, number });
@@ -278,13 +312,16 @@ export function githubTickets(o) {
278
312
  return lastBoard;
279
313
  };
280
314
  const tickets = {
315
+ key: githubKey,
316
+ ref: githubRef,
281
317
  async read(n) {
282
318
  const raw = await issue(n);
283
319
  if (raw.pull_request)
284
320
  throw new NotFoundError(`#${n}`);
321
+ issues.add(n);
285
322
  const comments = await t.rest("GET", `${API}/issues/${n}/comments?per_page=100`, { paginate: true });
286
323
  return {
287
- number: raw.number,
324
+ key: String(raw.number),
288
325
  title: raw.title,
289
326
  state: raw.state === "closed" ? "closed" : "open",
290
327
  closedAt: raw.closed_at,
@@ -295,25 +332,29 @@ export function githubTickets(o) {
295
332
  },
296
333
  async listOpen() {
297
334
  const all = await t.rest("GET", `${API}/issues?state=open&per_page=100`, { paginate: true });
298
- return all
299
- .filter((i) => !i.pull_request)
300
- .map((i) => ({
301
- number: i.number,
335
+ const open = all.filter((i) => !i.pull_request);
336
+ for (const i of open)
337
+ issues.add(String(i.number));
338
+ return open.map((i) => ({
339
+ key: String(i.number),
302
340
  title: i.title,
303
341
  labels: i.labels.map(labelName),
304
342
  }));
305
343
  },
306
344
  async writeBody(n, body) {
345
+ await anIssue(n);
307
346
  await found(`#${n}`, t.rest("PATCH", `${API}/issues/${n}`, { fields: { body } }));
308
347
  },
309
348
  async writeTitle(n, title) {
349
+ await anIssue(n);
310
350
  await found(`#${n}`, t.rest("PATCH", `${API}/issues/${n}`, { fields: { title } }));
311
351
  },
312
352
  async comment(n, body) {
353
+ await anIssue(n);
313
354
  const made = await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/comments`, {
314
355
  fields: { body },
315
356
  }));
316
- return made.id;
357
+ return String(made.id);
317
358
  },
318
359
  async editComment(id, body) {
319
360
  await found(`comment ${id}`, t.rest("PATCH", `${API}/issues/comments/${id}`, { fields: { body } }));
@@ -328,14 +369,16 @@ export function githubTickets(o) {
328
369
  const made = await t.rest("POST", `${API}/issues`, {
329
370
  fields,
330
371
  });
331
- return made.number;
372
+ return String(made.number);
332
373
  },
333
374
  async addLabel(n, label) {
375
+ await anIssue(n);
334
376
  await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/labels`, {
335
377
  fields: { labels: [label] },
336
378
  }));
337
379
  },
338
380
  async removeLabel(n, label) {
381
+ await anIssue(n);
339
382
  try {
340
383
  await t.rest("DELETE", `${API}/issues/${n}/labels/${encodeURIComponent(label)}`);
341
384
  }
@@ -348,7 +391,8 @@ export function githubTickets(o) {
348
391
  }
349
392
  },
350
393
  mayDecide: (author) => writeAccess(t, o.repository, author),
351
- linkText: (n) => `Closes #${n}`,
394
+ linkText: githubLinkText,
395
+ linksIn: githubLinksIn,
352
396
  address: (n) => `https://github.com/${o.repository}/issues/${n}`,
353
397
  board: {
354
398
  read: readBoard,
@@ -357,6 +401,8 @@ export function githubTickets(o) {
357
401
  if (o.board === null)
358
402
  throw new Error("The settings name no board.");
359
403
  const raw = await issue(n);
404
+ if (raw.pull_request)
405
+ throw new NotFoundError(`#${n}`);
360
406
  const added = await t.graphql(ADD_CARD, { project: board.projectId, content: raw.node_id });
361
407
  return added.data.addProjectV2ItemById.item.id;
362
408
  },
@@ -463,6 +509,7 @@ export function githubTickets(o) {
463
509
  },
464
510
  async write(n, values) {
465
511
  const fields = await issueFields();
512
+ await anIssue(n);
466
513
  const { node_id } = await issue(n);
467
514
  for (const [name, value] of Object.entries(values)) {
468
515
  const field = fields.find((f) => f.name === name);
@@ -477,12 +524,17 @@ export function githubTickets(o) {
477
524
  blockers: {
478
525
  async list(n) {
479
526
  const list = await found(`#${n}`, t.rest("GET", `${API}/issues/${n}/dependencies/blocked_by`, { paginate: true }));
480
- return list.map((b) => ({
481
- number: b.number,
482
- state: b.state === "open" ? "open" : "closed",
483
- }));
527
+ return list.map((b) => {
528
+ const repo = b.repository_url?.replace(/^.*\/repos\//, "");
529
+ const elsewhere = repo && repo.toLowerCase() !== o.repository.toLowerCase();
530
+ return {
531
+ key: elsewhere ? `${repo}#${b.number}` : String(b.number),
532
+ state: b.state === "open" ? "open" : "closed",
533
+ };
534
+ });
484
535
  },
485
536
  async add(n, by) {
537
+ await anIssue(n);
486
538
  const blocker = await issue(by);
487
539
  await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/dependencies/blocked_by`, {
488
540
  fields: { issue_id: blocker.id },
@@ -514,12 +566,14 @@ export function githubTickets(o) {
514
566
  after = info.hasNextPage ? info.endCursor : null;
515
567
  } while (after);
516
568
  const read = fromIssuesPages(pages);
569
+ for (const x of read)
570
+ issues.add(x.key);
517
571
  if (!options.board)
518
572
  return read;
519
573
  const board = await readBoard();
520
574
  return read.map((x) => ({
521
575
  ...x,
522
- card: board.items.get(x.number) ?? null,
576
+ card: board.items.get(x.key) ?? null,
523
577
  }));
524
578
  };
525
579
  if (o.cli) {
@@ -1,6 +1,6 @@
1
1
  import { type Gh } from "../lib/gh.mts";
2
2
  import { type Settings } from "../config.mts";
3
- import { type Tickets } from "./types.mts";
3
+ import { type Key, type Tickets } from "./types.mts";
4
4
  import { type FieldMapping } from "../ticket-fields.mts";
5
5
  export * from "./types.mts";
6
6
  /** The ticket system's message for a type that is not built. */
@@ -8,6 +8,12 @@ export declare const unsupportedType: (type: string) => string;
8
8
  export type Opened = {
9
9
  tickets: Tickets;
10
10
  };
11
+ /** How a ticket system of this type writes a ticket, without opening its
12
+ * adapter, for text written ahead of time, such as a workflow's run name. */
13
+ export declare function refOf(type: string): (key: Key) => string;
14
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
15
+ * does, without opening its adapter. */
16
+ export declare function keyOf(type: string): (typed: string) => Key;
11
17
  /** The settings' adapter, reaching its system through the GitHub CLI. The
12
18
  * repository and board are the caller's, since a workflow can name its own. */
13
19
  export declare function openTickets(settings: Settings, target: {