@davidbyoung/software-factory 0.1.11 → 0.1.13

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 (85) 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 +9 -7
  5. package/dist/board.mjs +59 -36
  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 +16 -7
  13. package/dist/config.d.mts +7 -0
  14. package/dist/config.mjs +68 -5
  15. package/dist/explain.mjs +6 -0
  16. package/dist/guard-commit.d.mts +3 -3
  17. package/dist/guard-commit.mjs +31 -6
  18. package/dist/guard-ticket-text.d.mts +3 -2
  19. package/dist/guard-ticket-text.mjs +7 -4
  20. package/dist/labels.d.mts +28 -0
  21. package/dist/labels.mjs +36 -0
  22. package/dist/lib/clock.d.mts +3 -1
  23. package/dist/lib/clock.mjs +12 -6
  24. package/dist/lib/pull-tickets.d.mts +15 -0
  25. package/dist/lib/pull-tickets.mjs +12 -0
  26. package/dist/lib/refined-check.d.mts +1 -1
  27. package/dist/lib/refined-check.mjs +3 -5
  28. package/dist/lib/usage.d.mts +3 -1
  29. package/dist/lib/usage.mjs +4 -2
  30. package/dist/lib/work-status.d.mts +29 -23
  31. package/dist/lib/work-status.mjs +30 -33
  32. package/dist/merge-policy.d.mts +9 -7
  33. package/dist/merge-policy.mjs +13 -11
  34. package/dist/poller.d.mts +5 -3
  35. package/dist/poller.mjs +27 -17
  36. package/dist/pr.d.mts +22 -0
  37. package/dist/pr.mjs +60 -10
  38. package/dist/remove.mjs +16 -9
  39. package/dist/review-tickets.d.mts +12 -0
  40. package/dist/review-tickets.mjs +59 -0
  41. package/dist/review-verdict.d.mts +6 -1
  42. package/dist/review-verdict.mjs +15 -9
  43. package/dist/reviewers.d.mts +7 -4
  44. package/dist/reviewers.mjs +19 -12
  45. package/dist/runner/github-actions.mjs +6 -7
  46. package/dist/runner/types.d.mts +7 -6
  47. package/dist/status.d.mts +19 -7
  48. package/dist/status.mjs +38 -23
  49. package/dist/sync.d.mts +8 -0
  50. package/dist/sync.mjs +30 -1
  51. package/dist/ticket-fields.d.mts +4 -2
  52. package/dist/ticket-fields.mjs +10 -3
  53. package/dist/ticket.d.mts +14 -7
  54. package/dist/ticket.mjs +121 -72
  55. package/dist/tickets/github.d.mts +10 -2
  56. package/dist/tickets/github.mjs +74 -20
  57. package/dist/tickets/index.d.mts +9 -2
  58. package/dist/tickets/index.mjs +20 -5
  59. package/dist/tickets/types.d.mts +59 -30
  60. package/dist/tickets/types.mjs +13 -3
  61. package/dist/tool-names.d.mts +7 -0
  62. package/dist/tool-names.mjs +1 -0
  63. package/dist/tools.d.mts +4 -1
  64. package/dist/tools.mjs +5 -0
  65. package/docs/cli.md +12 -8
  66. package/docs/configuration.md +179 -9
  67. package/docs/developing.md +17 -9
  68. package/docs/github/by-hand.md +2 -2
  69. package/docs/github/reference.md +22 -22
  70. package/docs/plugins.md +6 -6
  71. package/docs/workflow.md +8 -6
  72. package/package.json +1 -1
  73. package/review.md +11 -11
  74. package/rules.md +25 -16
  75. package/settings.schema.json +45 -0
  76. package/skills/factory-address-review/SKILL.md +7 -6
  77. package/skills/factory-build/SKILL.md +28 -22
  78. package/skills/factory-refine/SKILL.md +1 -1
  79. package/skills/factory-resolve-conflicts/SKILL.md +5 -4
  80. package/workflows/factory-build.yml +6 -5
  81. package/workflows/factory-claude-review.yml +38 -1
  82. package/workflows/factory-conflicts.yml +1 -1
  83. package/workflows/factory-merge-policy.yml +8 -7
  84. package/workflows/factory-review-verdict.yml +1 -1
  85. package/workflows/factory-review.yml +1 -1
@@ -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,7 @@
1
+ import { type Labels } from "../labels.mts";
1
2
  import { type Gh } from "../lib/gh.mts";
2
3
  import { type Settings } from "../config.mts";
3
- import { type Tickets } from "./types.mts";
4
+ import { type Key, type Tickets } from "./types.mts";
4
5
  import { type FieldMapping } from "../ticket-fields.mts";
5
6
  export * from "./types.mts";
6
7
  /** The ticket system's message for a type that is not built. */
@@ -8,6 +9,12 @@ export declare const unsupportedType: (type: string) => string;
8
9
  export type Opened = {
9
10
  tickets: Tickets;
10
11
  };
12
+ /** How a ticket system of this type writes a ticket, without opening its
13
+ * adapter, for text written ahead of time, such as a workflow's run name. */
14
+ export declare function refOf(type: string): (key: Key) => string;
15
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
16
+ * does, without opening its adapter. */
17
+ export declare function keyOf(type: string): (typed: string) => Key;
11
18
  /** The settings' adapter, reaching its system through the GitHub CLI. The
12
19
  * repository and board are the caller's, since a workflow can name its own. */
13
20
  export declare function openTickets(settings: Settings, target: {
@@ -19,4 +26,4 @@ export declare function openTickets(settings: Settings, target: {
19
26
  * The follow-ups ticket stays whole. `readAll` is the adapter's, since its
20
27
  * callers read comments, labels, and cards, never a refined ticket's
21
28
  * sections. */
22
- export declare function withTicketFields(inner: Tickets, mapping: FieldMapping, repository: string): Tickets;
29
+ export declare function withTicketFields(inner: Tickets, mapping: FieldMapping, repository: string, names?: Labels["tickets"]): Tickets;
@@ -1,9 +1,10 @@
1
1
  // Which adapter the settings' `tickets.type` picks, built for a command in a
2
2
  // session or CI. `github` is the only one; the settings refuse any other
3
3
  // value before this runs (`config.mts`).
4
+ import { TICKET_LABELS } from "../labels.mjs";
4
5
  import { gh } from "../lib/gh.mjs";
5
6
  import { fieldNamesOf } from "../config.mjs";
6
- import { githubTickets } from "./github.mjs";
7
+ import { githubKey, githubRef, githubTickets } from "./github.mjs";
7
8
  import { ghTransport } from "./transport.mjs";
8
9
  import { need } from "./types.mjs";
9
10
  import { join, split } from "../ticket-fields.mjs";
@@ -11,6 +12,20 @@ import { BUILT, unsupported } from "../tool-names.mjs";
11
12
  export * from "./types.mjs";
12
13
  /** The ticket system's message for a type that is not built. */
13
14
  export const unsupportedType = (type) => unsupported("tickets.type", type, "ticket system", Object.keys(BUILT.tickets));
15
+ /** How a ticket system of this type writes a ticket, without opening its
16
+ * adapter, for text written ahead of time, such as a workflow's run name. */
17
+ export function refOf(type) {
18
+ if (type !== "github")
19
+ throw new Error(unsupportedType(type));
20
+ return githubRef;
21
+ }
22
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
23
+ * does, without opening its adapter. */
24
+ export function keyOf(type) {
25
+ if (type !== "github")
26
+ throw new Error(unsupportedType(type));
27
+ return githubKey;
28
+ }
14
29
  /** The settings' adapter, reaching its system through the GitHub CLI. The
15
30
  * repository and board are the caller's, since a workflow can name its own. */
16
31
  export async function openTickets(settings, target, run = gh) {
@@ -28,7 +43,7 @@ export async function openTickets(settings, target, run = gh) {
28
43
  const mapping = settings.tickets.ticketFields;
29
44
  return {
30
45
  tickets: Object.values(mapping).some((v) => v !== null)
31
- ? withTicketFields(tickets, mapping, target.repository)
46
+ ? withTicketFields(tickets, mapping, target.repository, settings.tickets.labels)
32
47
  : tickets,
33
48
  };
34
49
  }
@@ -37,9 +52,9 @@ export async function openTickets(settings, target, run = gh) {
37
52
  * The follow-ups ticket stays whole. `readAll` is the adapter's, since its
38
53
  * callers read comments, labels, and cards, never a refined ticket's
39
54
  * sections. */
40
- export function withTicketFields(inner, mapping, repository) {
55
+ export function withTicketFields(inner, mapping, repository, names = TICKET_LABELS) {
41
56
  const fields = () => need(inner, "fields");
42
- const whole = (labels) => labels.includes("follow-up");
57
+ const whole = (labels) => labels.includes(names["follow-up"]);
43
58
  /** The description to write, once every named field is checked and
44
59
  * written. */
45
60
  const written = async (n, body) => {
@@ -72,7 +87,7 @@ export function withTicketFields(inner, mapping, repository) {
72
87
  const values = await fields().read(n);
73
88
  return {
74
89
  ...ticket,
75
- body: join(ticket.body, values, mapping, ticket.labels),
90
+ body: join(ticket.body, values, mapping, ticket.labels, names.spec),
76
91
  };
77
92
  },
78
93
  async writeBody(n, body) {
@@ -1,5 +1,9 @@
1
+ /** A ticket's identity: the key its ticket system gives it, as text, such
2
+ * as `12` on GitHub or `PROJ-12` in Jira. */
3
+ export type Key = string;
1
4
  export type TicketComment = {
2
- id: number;
5
+ /** Opaque: never compared as a number. */
6
+ id: string;
3
7
  author: string;
4
8
  createdAt: string;
5
9
  body: string;
@@ -8,7 +12,7 @@ export type TicketComment = {
8
12
  export type BoardItem = {
9
13
  /** The system's own ID for the card, for the adapter's writes. */
10
14
  itemId: string;
11
- number: number;
15
+ key: Key;
12
16
  status: string | null;
13
17
  /** When Status last changed. */
14
18
  updatedAt: string | null;
@@ -18,19 +22,20 @@ export type BoardItem = {
18
22
  cost?: number | null;
19
23
  };
20
24
  export type Ticket = {
21
- number: number;
25
+ key: Key;
22
26
  title: string;
23
27
  state: "open" | "closed";
24
28
  closedAt: string | null;
25
29
  labels: string[];
26
30
  body: string;
31
+ /** Oldest first, in the order the ticket system keeps them. */
27
32
  comments: TicketComment[];
28
33
  /** The ticket's card, when "Read everything at once" was asked for the
29
34
  * board and the adapter has one; null when it is not on the board. */
30
35
  card?: BoardItem | null;
31
36
  };
32
37
  export type TicketSummary = {
33
- number: number;
38
+ key: Key;
34
39
  title: string;
35
40
  labels: string[];
36
41
  };
@@ -50,8 +55,8 @@ export type Board = {
50
55
  /** The board's own title, for the report `factory board check` prints. */
51
56
  title?: string;
52
57
  fields: BoardField[];
53
- /** This repository's tickets on the board, by number. */
54
- items: Map<number, BoardItem>;
58
+ /** This repository's tickets on the board, by key. */
59
+ items: Map<Key, BoardItem>;
55
60
  };
56
61
  /** One write to a card's field. */
57
62
  export type Write = {
@@ -71,7 +76,7 @@ export type BoardOps = {
71
76
  /** Every card and the board's fields. */
72
77
  read(): Promise<Board>;
73
78
  /** Puts the ticket on the board, and returns its card's ID. */
74
- add(ticket: number): Promise<string>;
79
+ add(ticket: Key): Promise<string>;
75
80
  /** Writes the fields of a card already on the board. */
76
81
  set(itemId: string, writes: Write[]): Promise<void>;
77
82
  /** The open boards the repository's owner has. */
@@ -102,26 +107,28 @@ export type NewField = {
102
107
  type: "select";
103
108
  options: string[];
104
109
  };
110
+ /** A ticket another waits on. Its key can name a ticket `key` would refuse,
111
+ * such as one in another repository. */
105
112
  export type Blocker = {
106
- number: number;
113
+ key: Key;
107
114
  state: "open" | "closed";
108
115
  };
109
116
  export type BlockerOps = {
110
117
  /** What a ticket waits on, open or closed. */
111
- list(ticket: number): Promise<Blocker[]>;
118
+ list(ticket: Key): Promise<Blocker[]>;
112
119
  /** Records that `ticket` waits on `by`. */
113
- add(ticket: number, by: number): Promise<void>;
114
- remove(ticket: number, by: number): Promise<void>;
120
+ add(ticket: Key, by: Key): Promise<void>;
121
+ remove(ticket: Key, by: Key): Promise<void>;
115
122
  };
116
123
  export type LabelHistoryOps = {
117
124
  /** Whether the label was ever removed from the ticket. */
118
- wasRemoved(ticket: number, label: string): Promise<boolean>;
125
+ wasRemoved(ticket: Key, label: string): Promise<boolean>;
119
126
  };
120
127
  export type AttachmentOps = {
121
128
  /** Comments with the images attached; returns the comment's ID. */
122
- comment(ticket: number, body: string, files: string[]): Promise<number>;
129
+ comment(ticket: Key, body: string, files: string[]): Promise<string>;
123
130
  /** Replaces the body with the images attached. */
124
- writeBody(ticket: number, body: string, files: string[]): Promise<void>;
131
+ writeBody(ticket: Key, body: string, files: string[]): Promise<void>;
125
132
  };
126
133
  /** A field tickets can have, set on the ticket itself. */
127
134
  export type TicketField = {
@@ -137,15 +144,15 @@ export type FieldOps = {
137
144
  /** The fields tickets can have, in the system's order. */
138
145
  list(): Promise<TicketField[]>;
139
146
  /** Whether the ticket can hold the field, and how many characters. */
140
- holds(ticket: number, field: string): Promise<{
147
+ holds(ticket: Key, field: string): Promise<{
141
148
  max: number | null;
142
149
  } | {
143
150
  reason: string;
144
151
  }>;
145
152
  /** The ticket's text field values, by field name. */
146
- read(ticket: number): Promise<Record<string, string>>;
153
+ read(ticket: Key): Promise<Record<string, string>>;
147
154
  /** Sets each field by name; null clears it. */
148
- write(ticket: number, values: Record<string, string | null>): Promise<void>;
155
+ write(ticket: Key, values: Record<string, string | null>): Promise<void>;
149
156
  };
150
157
  export declare const GROUPS: readonly ["board", "blockers", "label-history", "attachments", "fields"];
151
158
  export type Group = (typeof GROUPS)[number];
@@ -155,8 +162,14 @@ export type NewTicket = {
155
162
  labels: string[];
156
163
  };
157
164
  export type Tickets = {
165
+ /** The key a person typed, or KeyError saying what a key looks like in
166
+ * this system. It checks only typed input: keys the adapter returned, such
167
+ * as a blocker's, are used as they are. */
168
+ key(typed: string): Key;
169
+ /** How the ticket is written in prose and output, such as `#12`. */
170
+ ref(ticket: Key): string;
158
171
  /** The ticket, or NotFoundError when there is none. */
159
- read(ticket: number): Promise<Ticket>;
172
+ read(ticket: Key): Promise<Ticket>;
160
173
  /** Every open ticket, however many there are. */
161
174
  listOpen(): Promise<TicketSummary[]>;
162
175
  /** Every open ticket and the 30 closed ones most recently updated, as
@@ -166,32 +179,48 @@ export type Tickets = {
166
179
  readAll?(options?: {
167
180
  board?: boolean;
168
181
  }): Promise<Ticket[]>;
169
- writeBody(ticket: number, body: string): Promise<void>;
170
- writeTitle(ticket: number, title: string): Promise<void>;
182
+ writeBody(ticket: Key, body: string): Promise<void>;
183
+ writeTitle(ticket: Key, title: string): Promise<void>;
171
184
  /** Returns the comment's ID. The body is posted as given. */
172
- comment(ticket: number, body: string): Promise<number>;
185
+ comment(ticket: Key, body: string): Promise<string>;
173
186
  /** NotFoundError when the comment is gone. */
174
- editComment(id: number, body: string): Promise<void>;
187
+ editComment(id: string, body: string): Promise<void>;
175
188
  /** NotFoundError when the comment is gone. */
176
- deleteComment(id: number): Promise<void>;
177
- /** Returns the new ticket's number. */
178
- open(ticket: NewTicket): Promise<number>;
179
- addLabel(ticket: number, label: string): Promise<void>;
180
- removeLabel(ticket: number, label: string): Promise<void>;
189
+ deleteComment(id: string): Promise<void>;
190
+ /** Returns the new ticket's key. */
191
+ open(ticket: NewTicket): Promise<Key>;
192
+ addLabel(ticket: Key, label: string): Promise<void>;
193
+ removeLabel(ticket: Key, label: string): Promise<void>;
181
194
  /** Whether a comment by `author` may decide on a ticket: an answer to a
182
195
  * question, taken as an instruction. Rejects when the system cannot
183
196
  * say. */
184
197
  mayDecide(author: string): Promise<boolean>;
185
- /** What makes a merged pull request close the ticket. */
186
- linkText(ticket: number): string;
198
+ /** The line in a pull request's body that closes the ticket when it
199
+ * merges, or that says it builds part of it. */
200
+ linkText(ticket: Key, kind: LinkKind): string;
201
+ /** The tickets a pull request's body closes and builds part of, each in
202
+ * the order the body links them, once. */
203
+ linksIn(body: string): Links;
187
204
  /** The address of the ticket's page. */
188
- address(ticket: number): string;
205
+ address(ticket: Key): string;
189
206
  board?: BoardOps;
190
207
  blockers?: BlockerOps;
191
208
  labelHistory?: LabelHistoryOps;
192
209
  attachments?: AttachmentOps;
193
210
  fields?: FieldOps;
194
211
  };
212
+ export type LinkKind = "closes" | "part";
213
+ export type Links = {
214
+ closes: Key[];
215
+ partOf: Key[];
216
+ };
217
+ /** Typed text that is not a key this ticket system uses. */
218
+ export declare class KeyError extends Error {
219
+ constructor(message: string);
220
+ }
221
+ /** The order tickets are listed in: by key, letters first, then the number
222
+ * as a number, so PROJ-9 comes before PROJ-12. */
223
+ export declare const compareKeys: (a: Key, b: Key) => number;
195
224
  /** A ticket or comment that does not exist, told apart from any other
196
225
  * failure. Every adapter throws this one. */
197
226
  export declare class NotFoundError extends Error {
@@ -10,6 +10,16 @@ export const GROUPS = [
10
10
  "attachments",
11
11
  "fields",
12
12
  ];
13
+ /** Typed text that is not a key this ticket system uses. */
14
+ export class KeyError extends Error {
15
+ constructor(message) {
16
+ super(message);
17
+ this.name = "KeyError";
18
+ }
19
+ }
20
+ /** The order tickets are listed in: by key, letters first, then the number
21
+ * as a number, so PROJ-9 comes before PROJ-12. */
22
+ export const compareKeys = (a, b) => a.localeCompare(b, "en", { numeric: true });
13
23
  /** A ticket or comment that does not exist, told apart from any other
14
24
  * failure. Every adapter throws this one. */
15
25
  export class NotFoundError extends Error {
@@ -62,17 +72,17 @@ export async function readAll(tickets, options = {}) {
62
72
  if (tickets.readAll)
63
73
  return tickets.readAll(options);
64
74
  const open = await tickets.listOpen();
65
- const read = await Promise.all(open.map((t) => tickets.read(t.number)));
75
+ const read = await Promise.all(open.map((t) => tickets.read(t.key)));
66
76
  if (!options.board || !tickets.board)
67
77
  return read;
68
78
  const board = await tickets.board.read();
69
- return read.map((t) => ({ ...t, card: board.items.get(t.number) ?? null }));
79
+ return read.map((t) => ({ ...t, card: board.items.get(t.key) ?? null }));
70
80
  }
71
81
  /** The cards `readAll` carried, as a Board, for the code that reads one. */
72
82
  export function boardOf(tickets) {
73
83
  const items = new Map();
74
84
  for (const t of tickets)
75
85
  if (t.card)
76
- items.set(t.number, t.card);
86
+ items.set(t.key, t.card);
77
87
  return { projectId: "", fields: [], items };
78
88
  }
@@ -5,7 +5,14 @@ export type Built = {
5
5
  runner: readonly string[];
6
6
  /** Each spec tool, with the check \`specs.check\` defaults to. */
7
7
  specs: Readonly<Record<string, string>>;
8
+ /** Why a ticket system or code host refuses a label name, or null, for
9
+ * each that limits names beyond their not being empty. */
10
+ labelFaults: {
11
+ tickets: Readonly<Record<string, LabelFault>>;
12
+ codeHost: Readonly<Record<string, LabelFault>>;
13
+ };
8
14
  };
15
+ export type LabelFault = (name: string) => string | null;
9
16
  export declare const BUILT: Built;
10
17
  /** The words every command fails with for a name that is not built, such
11
18
  * as `tickets.type "jira" is not supported. "github" is the only ticket
@@ -11,6 +11,7 @@ export const BUILT = {
11
11
  specs: {
12
12
  openspec: "npx --no-install openspec validate --all --strict --no-interactive",
13
13
  },
14
+ labelFaults: { tickets: {}, codeHost: {} },
14
15
  };
15
16
  /** The words every command fails with for a name that is not built, such
16
17
  * as `tickets.type "jira" is not supported. "github" is the only ticket
package/dist/tools.d.mts CHANGED
@@ -6,10 +6,13 @@ import { type Runner } from "./runner/index.mts";
6
6
  import type { Chosen, SecretStep, SetupContext, SetupStep, ToolSetup } from "./setup.mts";
7
7
  import { type Tickets } from "./tickets/index.mts";
8
8
  import { type SpecTools } from "./specs/index.mts";
9
- import { type Built } from "./tool-names.mts";
9
+ import { type Built, type LabelFault } from "./tool-names.mts";
10
10
  export type Tool = {
11
11
  label: string;
12
12
  setup: ToolSetup;
13
+ /** Why it refuses a label name, where it limits names beyond their not
14
+ * being empty. */
15
+ labelFault?: LabelFault;
13
16
  };
14
17
  export type Registry = {
15
18
  codeHost: Record<string, Tool & {
package/dist/tools.mjs CHANGED
@@ -53,6 +53,7 @@ export const TOOLS = {
53
53
  },
54
54
  specs: specTools(),
55
55
  };
56
+ const faultsOf = (tools) => Object.fromEntries(Object.entries(tools).flatMap(([name, t]) => t.labelFault ? [[name, t.labelFault]] : []));
56
57
  /** The names and keys the settings accept, as `config.mts` checks them. */
57
58
  export function builtOf(r) {
58
59
  return {
@@ -60,6 +61,10 @@ export function builtOf(r) {
60
61
  tickets: Object.fromEntries(Object.entries(r.tickets).map(([name, t]) => [name, t.keys])),
61
62
  runner: Object.keys(r.runner),
62
63
  specs: Object.fromEntries(Object.entries(r.specs).map(([name, t]) => [name, t.defaultCheck])),
64
+ labelFaults: {
65
+ tickets: faultsOf(r.tickets),
66
+ codeHost: faultsOf(r.codeHost),
67
+ },
63
68
  };
64
69
  }
65
70
  /** The tools in use, in the order setup asks for them. */