@davidbyoung/software-factory 0.1.12 → 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 (55) hide show
  1. package/dist/board.d.mts +3 -1
  2. package/dist/board.mjs +12 -6
  3. package/dist/commands.mjs +1 -1
  4. package/dist/config.d.mts +7 -0
  5. package/dist/config.mjs +68 -5
  6. package/dist/explain.mjs +6 -0
  7. package/dist/guard-commit.d.mts +3 -3
  8. package/dist/guard-commit.mjs +31 -6
  9. package/dist/guard-ticket-text.d.mts +3 -2
  10. package/dist/guard-ticket-text.mjs +7 -4
  11. package/dist/labels.d.mts +28 -0
  12. package/dist/labels.mjs +36 -0
  13. package/dist/lib/refined-check.d.mts +1 -1
  14. package/dist/lib/refined-check.mjs +3 -5
  15. package/dist/lib/work-status.d.mts +6 -4
  16. package/dist/lib/work-status.mjs +17 -7
  17. package/dist/merge-policy.d.mts +9 -7
  18. package/dist/merge-policy.mjs +13 -11
  19. package/dist/poller.d.mts +3 -1
  20. package/dist/poller.mjs +10 -4
  21. package/dist/pr.d.mts +4 -0
  22. package/dist/pr.mjs +6 -3
  23. package/dist/remove.mjs +16 -9
  24. package/dist/review-verdict.d.mts +6 -1
  25. package/dist/review-verdict.mjs +15 -9
  26. package/dist/status.d.mts +2 -0
  27. package/dist/status.mjs +6 -3
  28. package/dist/sync.d.mts +4 -0
  29. package/dist/sync.mjs +17 -1
  30. package/dist/ticket-fields.d.mts +4 -2
  31. package/dist/ticket-fields.mjs +10 -3
  32. package/dist/ticket.d.mts +2 -1
  33. package/dist/ticket.mjs +30 -15
  34. package/dist/tickets/index.d.mts +2 -1
  35. package/dist/tickets/index.mjs +5 -4
  36. package/dist/tool-names.d.mts +7 -0
  37. package/dist/tool-names.mjs +1 -0
  38. package/dist/tools.d.mts +4 -1
  39. package/dist/tools.mjs +5 -0
  40. package/docs/cli.md +1 -1
  41. package/docs/configuration.md +178 -8
  42. package/docs/developing.md +1 -1
  43. package/docs/github/by-hand.md +2 -2
  44. package/docs/github/reference.md +21 -21
  45. package/docs/workflow.md +8 -6
  46. package/package.json +1 -1
  47. package/rules.md +7 -2
  48. package/settings.schema.json +45 -0
  49. package/skills/factory-address-review/SKILL.md +3 -3
  50. package/skills/factory-build/SKILL.md +3 -3
  51. package/skills/factory-resolve-conflicts/SKILL.md +1 -1
  52. package/workflows/factory-conflicts.yml +1 -1
  53. package/workflows/factory-merge-policy.yml +8 -7
  54. package/workflows/factory-review-verdict.yml +1 -1
  55. package/workflows/factory-review.yml +1 -1
package/dist/board.d.mts CHANGED
@@ -17,6 +17,8 @@ export type FieldNames = {
17
17
  export type BoardConfig = {
18
18
  columns: Columns;
19
19
  fields: FieldNames;
20
+ /** The name of the follow-ups ticket's label. */
21
+ followUp: string;
20
22
  };
21
23
  export declare const DEFAULT_FIELDS: FieldNames;
22
24
  export declare const DEFAULT_BOARD: BoardConfig;
@@ -99,7 +101,7 @@ type PullEvent = {
99
101
  export declare function closedPullComments(event: PullEvent, links: Links, openFollowUps: Key[], columns: Columns, ref: (key: Key) => string): Comment[];
100
102
  /** The nightly run's clears: claims and starts over 24 hours old with no
101
103
  * pull request. */
102
- export declare function nightlyComments(snapshot: RepoSnapshot, now: Date, columns: Columns, ref: (key: Key) => string): Comment[];
104
+ export declare function nightlyComments(snapshot: RepoSnapshot, now: Date, columns: Columns, ref: (key: Key) => string, followUp: string): Comment[];
103
105
  /** What collect saves for apply: the tickets and the pull requests. */
104
106
  export type Saved = {
105
107
  tickets: Ticket[];
package/dist/board.mjs CHANGED
@@ -20,6 +20,7 @@
20
20
  //
21
21
  // Tickets and the board go through the ticket interface (`tickets/`); the
22
22
  // pull requests through `code-host/`.
23
+ import { TICKET_LABELS } from "./labels.mjs";
23
24
  import { colorOn, painter, plain, } from "./lib/color.mjs";
24
25
  import { readFileSync, writeFileSync } from "node:fs";
25
26
  import { join } from "node:path";
@@ -40,10 +41,15 @@ export const DEFAULT_FIELDS = {
40
41
  export const DEFAULT_BOARD = {
41
42
  columns: DEFAULT_COLUMNS,
42
43
  fields: DEFAULT_FIELDS,
44
+ followUp: TICKET_LABELS["follow-up"],
43
45
  };
44
46
  /** The columns and fields the settings name. */
45
47
  export function boardConfigOf(s) {
46
- return { columns: columnsOf(s), fields: fieldNamesOf(s) };
48
+ return {
49
+ columns: columnsOf(s),
50
+ fields: fieldNamesOf(s),
51
+ followUp: s.tickets.labels["follow-up"],
52
+ };
47
53
  }
48
54
  const FIELD_KINDS = [
49
55
  {
@@ -261,7 +267,7 @@ export function planSync(snapshot, board, runPage, cfg = DEFAULT_BOARD) {
261
267
  const everyPull = [...snapshot.pulls, ...(snapshot.donePulls ?? [])];
262
268
  const fields = checkFields(board.fields, cfg);
263
269
  return snapshot.issues.map((issue) => {
264
- const derived = derive(issue, cardOf(board, issue.key, cfg.columns), snapshot.pulls, cfg.columns);
270
+ const derived = derive(issue, cardOf(board, issue.key, cfg.columns), snapshot.pulls, cfg.columns, cfg.followUp);
265
271
  const listPrice = issueCost(issue, everyPull);
266
272
  const cost = listPrice === null
267
273
  ? null
@@ -350,9 +356,9 @@ export function closedPullComments(event, links, openFollowUps, columns, ref) {
350
356
  }
351
357
  /** The nightly run's clears: claims and starts over 24 hours old with no
352
358
  * pull request. */
353
- export function nightlyComments(snapshot, now, columns, ref) {
359
+ export function nightlyComments(snapshot, now, columns, ref, followUp) {
354
360
  return snapshot.issues.flatMap((issue) => {
355
- const clear = toClear(issue, snapshot.pulls, now);
361
+ const clear = toClear(issue, snapshot.pulls, now, followUp);
356
362
  if (!clear)
357
363
  return [];
358
364
  const named = { key: issue.key, ref: ref(issue.key) };
@@ -398,7 +404,7 @@ async function collect(d, opts) {
398
404
  const event = JSON.parse(d.readFile(opts.event));
399
405
  if (event.action === "closed") {
400
406
  const followUps = snapshot.issues
401
- .filter((i) => i.state === "open" && i.labels.includes("follow-up"))
407
+ .filter((i) => i.state === "open" && i.labels.includes(d.config.followUp))
402
408
  .map((i) => i.key);
403
409
  const links = ticketsOf({
404
410
  body: event.pull_request.body ?? "",
@@ -413,7 +419,7 @@ async function collect(d, opts) {
413
419
  }
414
420
  }
415
421
  if (opts.nightly) {
416
- const comments = nightlyComments(snapshot, d.now(), d.config.columns, (k) => d.tickets.ref(k));
422
+ const comments = nightlyComments(snapshot, d.now(), d.config.columns, (k) => d.tickets.ref(k), d.config.followUp);
417
423
  await postAll(comments, d, opts.dryRun);
418
424
  if (comments.length && !opts.dryRun)
419
425
  saved = await read(d);
package/dist/commands.mjs CHANGED
@@ -194,7 +194,7 @@ export async function main(argv, d) {
194
194
  return failed(`Could not start ticket ${id}'s spec in ${folder}`);
195
195
  d.out(`Started ticket ${id}'s spec in ${folder}`);
196
196
  }
197
- const files = tool.files(id, labels.includes("spec"));
197
+ const files = tool.files(id, labels.includes(s.tickets.labels.spec));
198
198
  const width = Math.max(...files.map((f) => f.path.length)) + 2;
199
199
  const kinds = Math.max(...files.map((f) => f.kind.length));
200
200
  d.out(`Write each file from ticket ${id}'s body:`);
package/dist/config.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { type Paint } from "./lib/color.mts";
3
3
  import { type FieldMapping } from "./ticket-fields.mts";
4
+ import { type Labels } from "./labels.mts";
4
5
  import { type Built } from "./tool-names.mts";
5
6
  import { type Watch, type Columns, type StateKey } from "./lib/work-status.mts";
6
7
  export declare class SettingsError extends Error {
@@ -59,6 +60,8 @@ export type Settings = {
59
60
  * first and then any heading of the repository's own, with the ticket
60
61
  * field that holds it, or null for the description. */
61
62
  ticketFields: FieldMapping;
63
+ /** The name of each label the factory puts on tickets. */
64
+ labels: Labels["tickets"];
62
65
  };
63
66
  /** Where pull requests are, and the pattern a build's branch is named
64
67
  * by. The pattern is null only when init reads settings without it, to
@@ -66,6 +69,8 @@ export type Settings = {
66
69
  codeHost: {
67
70
  type: string;
68
71
  branchName: string | null;
72
+ /** The name of each label the factory puts on pull requests. */
73
+ labels: Labels["codeHost"];
69
74
  };
70
75
  builds: {
71
76
  /** What notices a card moved to Ready and starts its build. */
@@ -297,6 +302,8 @@ export type Target = {
297
302
  watch: Watch | null;
298
303
  /** The column each state shows in on the board. */
299
304
  columns: Columns;
305
+ /** The name of the follow-ups ticket's label. */
306
+ followUp: string;
300
307
  };
301
308
  /** The settings' answer, with GITHUB_REPOSITORY and FACTORY_BOARD_NUMBER
302
309
  * winning where they are set. */
package/dist/config.mjs CHANGED
@@ -18,7 +18,8 @@ import { matchesAny } from "./lib/glob.mjs";
18
18
  import { listed } from "./lib/listed.mjs";
19
19
  import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
20
20
  import { FACTORY_FIELDS } from "./ticket-fields.mjs";
21
- import { BUILT, unsupported } from "./tool-names.mjs";
21
+ import { PR_LABELS, sameLabel, TICKET_LABELS } from "./labels.mjs";
22
+ import { BUILT, unsupported, } from "./tool-names.mjs";
22
23
  import { DEFAULT_COLUMNS, STATE_KEYS, sameName, watchOf, } from "./lib/work-status.mjs";
23
24
  export class SettingsError extends Error {
24
25
  }
@@ -144,13 +145,15 @@ export const SETTINGS_KEYS = {
144
145
  "session-minutes",
145
146
  "rules",
146
147
  ],
147
- tickets: ["type", "board", "columns", "fields"],
148
+ tickets: ["type", "board", "columns", "fields", "labels"],
149
+ "tickets.labels": Object.keys(TICKET_LABELS),
148
150
  "tickets.columns": Object.keys(STATE_KEYS),
149
151
  "tickets.fields": [
150
152
  ...Object.keys(FIELD_DEFAULTS),
151
153
  ...FACTORY_FIELDS.map((f) => f.key),
152
154
  ],
153
- "code-host": ["type", "branch-name"],
155
+ "code-host": ["type", "branch-name", "labels"],
156
+ "code-host.labels": Object.keys(PR_LABELS),
154
157
  builds: ["trigger", "runner", "poll-minutes"],
155
158
  specs: ["type", "check"],
156
159
  commands: [
@@ -317,6 +320,46 @@ function names(v, key, defaults) {
317
320
  return [k, value.trim()];
318
321
  }));
319
322
  }
323
+ /** One side's label names: each key the file sets, checked by the tool
324
+ * that shows it, and the rest at their defaults. */
325
+ function labelsOf(v, key, defaults, fault) {
326
+ const o = object(v, key);
327
+ const set = Object.keys(defaults).filter((k) => o[k] !== undefined);
328
+ const names = { ...defaults };
329
+ for (const k of set) {
330
+ const value = o[k];
331
+ if (typeof value !== "string")
332
+ fail(`${key}.${k}`, "must be text");
333
+ const name = value.trim();
334
+ if (!name)
335
+ fail(`${key}.${k}`, "must not be empty");
336
+ const why = fault?.(name);
337
+ if (why)
338
+ fail(`${key}.${k}`, why);
339
+ names[k] = name;
340
+ }
341
+ return { names, set };
342
+ }
343
+ /** Fails on two labels with one name, ignoring capitals, naming a key the
344
+ * file sets: of two it sets, the later. Ticket and pull request labels are
345
+ * compared only when one tool holds both. */
346
+ function sameNames(sides, oneTool) {
347
+ const groups = oneTool ? [sides] : sides.map((side) => [side]);
348
+ for (const group of groups) {
349
+ const all = group.flatMap((side) => Object.entries(side.names).map(([k, name]) => ({
350
+ at: `${side.key}.${k}`,
351
+ name,
352
+ set: side.set.includes(k),
353
+ })));
354
+ for (const [i, b] of all.entries())
355
+ for (const a of all.slice(0, i)) {
356
+ if (!sameLabel(a.name, b.name))
357
+ continue;
358
+ const [blamed, other] = b.set ? [b, a] : [a, b];
359
+ fail(blamed.at, `"${blamed.name}" is already ${other.at}. Give each label its own name`);
360
+ }
361
+ }
362
+ }
320
363
  /** A key under `tickets.fields` naming a heading of the repository's own. */
321
364
  export const OWN_HEADING = /^[a-z0-9]+(-[a-z0-9]+)*$/;
322
365
  /** The ticket-side keys under `tickets.fields`: the four factory fields,
@@ -600,6 +643,12 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
600
643
  if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
601
644
  throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
602
645
  const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
646
+ const ticketLabels = labelsOf(tickets.labels, "tickets.labels", TICKET_LABELS, built.labelFaults.tickets[ticketType]);
647
+ const prLabels = labelsOf(codeHostBlock.labels, "code-host.labels", PR_LABELS, built.labelFaults.codeHost[codeHost]);
648
+ sameNames([
649
+ { key: "tickets.labels", ...ticketLabels },
650
+ { key: "code-host.labels", ...prLabels },
651
+ ], ticketType === codeHost);
603
652
  const builds = object(top.builds, "builds");
604
653
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
605
654
  const minutes = builds["poll-minutes"];
@@ -682,8 +731,9 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
682
731
  columns,
683
732
  fields: fieldNames,
684
733
  ticketFields,
734
+ labels: ticketLabels.names,
685
735
  },
686
- codeHost: { type: codeHost, branchName },
736
+ codeHost: { type: codeHost, branchName, labels: prLabels.names },
687
737
  builds: { trigger, runner, pollMinutes },
688
738
  specs,
689
739
  specCheck,
@@ -769,6 +819,18 @@ export function parseChoices(text, load) {
769
819
  throw bad();
770
820
  return v;
771
821
  }
822
+ /** js-yaml's error for `key: a: b`, said as the fix: the value needs
823
+ * quotes. Null for any other error. */
824
+ function needsQuotes(e, text) {
825
+ const { reason, mark } = e;
826
+ if (reason !== "bad indentation of a mapping entry" || !mark)
827
+ return null;
828
+ const m = /^\s*([^\s:#][^:]*): (\S.*: .*?)\s*$/.exec(text.split("\n")[mark.line] ?? "");
829
+ if (!m || /^["'[{]/.test(m[2]))
830
+ return null;
831
+ const [, key, value] = m;
832
+ return `line ${mark.line + 1}: ${key}: ${value} needs quotes around the name, such as ${key}: "${value}"`;
833
+ }
772
834
  /** The settings combined from the factory's defaults, each preset in
773
835
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
774
836
  * into the lock. `factoryFile` and `ownFile` say which preset files are
@@ -782,7 +844,7 @@ export async function resolveFiles(d, { partial = false, ...keep } = {}) {
782
844
  own = load(ownText);
783
845
  }
784
846
  catch (e) {
785
- throw new SettingsError(`${SETTINGS_FILE}: ${e.message}`);
847
+ throw new SettingsError(`${SETTINGS_FILE}: ${needsQuotes(e, ownText) ?? e.message}`);
786
848
  }
787
849
  const P = await import("./preset.mjs");
788
850
  const top = isObj(own) ? own : {};
@@ -1193,6 +1255,7 @@ export function targetOf(s, env) {
1193
1255
  : s.tickets.board,
1194
1256
  watch: watchOf(s.builds.trigger, s.builds.pollMinutes),
1195
1257
  columns: columnsOf(s),
1258
+ followUp: s.tickets.labels["follow-up"],
1196
1259
  };
1197
1260
  }
1198
1261
  /** The repository, code host, and runner for a command a workflow runs
package/dist/explain.mjs CHANGED
@@ -75,6 +75,9 @@ export async function explainLines(s, marks, exists) {
75
75
  block(["tickets", "fields"]);
76
76
  for (const [k, v] of Object.entries(s.tickets.ticketFields))
77
77
  put(["tickets", "fields", k], v ?? "none");
78
+ block(["tickets", "labels"]);
79
+ for (const [k, v] of Object.entries(s.tickets.labels))
80
+ put(["tickets", "labels", k], v);
78
81
  block(["code-host"]);
79
82
  put(["code-host", "type"], s.codeHost.type);
80
83
  // Quoted always: YAML reads a pattern that starts with `{` as a map.
@@ -82,6 +85,9 @@ export async function explainLines(s, marks, exists) {
82
85
  text: `${pad(1)}branch-name: ${JSON.stringify(s.codeHost.branchName)}`,
83
86
  mark: marks.value(["code-host", "branch-name"]),
84
87
  });
88
+ block(["code-host", "labels"]);
89
+ for (const [k, v] of Object.entries(s.codeHost.labels))
90
+ put(["code-host", "labels", k], v);
85
91
  block(["builds"]);
86
92
  put(["builds", "trigger"], s.builds.trigger);
87
93
  put(["builds", "runner"], s.builds.runner);
@@ -10,16 +10,16 @@ export type HookInput = {
10
10
  * part of a command. A quoted single word is unquoted instead: the shell
11
11
  * passes "main" to git as main. */
12
12
  export declare function blankQuoted(cmd: string): string;
13
- /** "verdict: override" is the owner's approval of one commit, and agents act
13
+ /** The override is the owner's approval of one commit, and agents act
14
14
  * through the owner's account, so GitHub cannot tell their override from the
15
15
  * owner's. This is a tripwire, not a lock: it stops the ordinary gh ways of
16
16
  * adding it, not a script written to get around it. It reads each command of
17
- * the chain as typed, since the spaced name is always quoted, and blocks one
17
+ * the chain as typed, since a name with a space in it is quoted, and blocks one
18
18
  * that adds the override as --add-label's value or a labels[]= field, or that
19
19
  * writes to the labels API with the override anywhere in the command, as a
20
20
  * body sent with --input does. Removing the override, alone or beside adding
21
21
  * another label, is allowed. */
22
- export declare function addsOverride(raw: string): boolean;
22
+ export declare function addsOverride(raw: string, name: string): boolean;
23
23
  export type GitCall = {
24
24
  kind: "push" | "commit";
25
25
  segment: string;
@@ -17,6 +17,7 @@ import { homedir } from "node:os";
17
17
  import { dirname, isAbsolute, join, relative } from "node:path";
18
18
  import { fileURLToPath } from "node:url";
19
19
  import { defaultDeps, loadSettings, settingsPath } from "./config.mjs";
20
+ import { PR_LABELS } from "./labels.mjs";
20
21
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
21
22
  /** Heredoc bodies and quoted strings blanked, so a commit message, grep
22
23
  * pattern, or file body that mentions "git push -f" or "main" is not read as
@@ -29,17 +30,23 @@ export function blankQuoted(cmd) {
29
30
  .replace(/"(?:[^"\\]|\\[\s\S])*"/g, '""')
30
31
  .replace(/'[^']*'/g, "''");
31
32
  }
32
- const OVERRIDE = String.raw `verdict(:|%3A)( |%20|\+)override`;
33
- /** "verdict: override" is the owner's approval of one commit, and agents act
33
+ /** The override's name as a pattern that also matches it URL-encoded: a
34
+ * colon as %3A, and a space as %20 or +. */
35
+ const overridePattern = (name) => name
36
+ .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
37
+ .replace(/:/g, "(:|%3A)")
38
+ .replace(/ /g, "( |%20|\\+)");
39
+ /** The override is the owner's approval of one commit, and agents act
34
40
  * through the owner's account, so GitHub cannot tell their override from the
35
41
  * owner's. This is a tripwire, not a lock: it stops the ordinary gh ways of
36
42
  * adding it, not a script written to get around it. It reads each command of
37
- * the chain as typed, since the spaced name is always quoted, and blocks one
43
+ * the chain as typed, since a name with a space in it is quoted, and blocks one
38
44
  * that adds the override as --add-label's value or a labels[]= field, or that
39
45
  * writes to the labels API with the override anywhere in the command, as a
40
46
  * body sent with --input does. Removing the override, alone or beside adding
41
47
  * another label, is allowed. */
42
- export function addsOverride(raw) {
48
+ export function addsOverride(raw, name) {
49
+ const OVERRIDE = overridePattern(name);
43
50
  const segments = raw
44
51
  .split(/\|\||&&|[;&|()]|\n/)
45
52
  .filter((s) => /^\s*gh\s/.test(s));
@@ -50,6 +57,21 @@ export function addsOverride(raw) {
50
57
  segments.some((s) => /\/labels(\s|$)/.test(s) &&
51
58
  /--input|-X\s*(POST|PUT)|--method\s+(POST|PUT)/.test(s)));
52
59
  }
60
+ /** The override's name in the lock of the checkout at `dir`, or its
61
+ * default where there is no lock to read. */
62
+ async function overrideName(dir) {
63
+ const top = checkoutOf(dir);
64
+ const lock = join(top, ".claude/factory.lock");
65
+ if (!existsSync(lock))
66
+ return PR_LABELS["verdict-override"];
67
+ try {
68
+ const s = await loadSettings(defaultDeps(top, { FACTORY_LOCK: lock }));
69
+ return s.codeHost.labels["verdict-override"];
70
+ }
71
+ catch {
72
+ return PR_LABELS["verdict-override"];
73
+ }
74
+ }
53
75
  function resolvePath(dir, to) {
54
76
  if (isAbsolute(to))
55
77
  return to;
@@ -162,8 +184,11 @@ const pushesTo = (segment, branch) => new RegExp(String.raw `\s(\S*:)?(refs\/hea
162
184
  export async function checkCommit(input, err, defaultOf = branchOf) {
163
185
  const raw = input.tool_input?.command ?? "";
164
186
  const cwd = input.cwd ?? ".";
165
- if (addsOverride(raw))
166
- return '"verdict: override" is the owner\'s label. Ask them to add it.';
187
+ if (/\bgh\s/.test(raw) && /label/i.test(raw)) {
188
+ const name = await overrideName(cwd);
189
+ if (addsOverride(raw, name))
190
+ return `"${name}" is the owner's label. Ask them to add it.`;
191
+ }
167
192
  const calls = gitCalls(blankQuoted(raw), cwd);
168
193
  if (calls.length === 0)
169
194
  return null;
@@ -23,5 +23,6 @@ export declare function checkTicketText(input: {
23
23
  * tag, so `factory ticket` and `factory pr comment` post nothing. */
24
24
  export declare function refuseBareTags(text: string): void;
25
25
  /** The owner's pass of the review verdict for one commit, which no agent
26
- * adds ("What merges without the owner" in rules.md). */
27
- export declare function refuseOverride(label: string): void;
26
+ * adds ("What merges without the owner" in rules.md), by its key or by
27
+ * `name`, the name the settings give it. */
28
+ export declare function refuseOverride(label: string, name: string): void;
@@ -15,6 +15,7 @@
15
15
  // forms, which is how a session posts without `gh issue`.
16
16
  // GitHub serves a pull request's conversation comments, and its body, as
17
17
  // an issue's, so those paths are read too; `gh pr` and `pulls/N` are not.
18
+ import { PR_LABELS, sameLabel } from "./labels.mjs";
18
19
  import { readFileSync } from "node:fs";
19
20
  import { resolve } from "node:path";
20
21
  /** The tags GitHub renders on purpose, which issue text may use bare. Not
@@ -281,8 +282,10 @@ export function refuseBareTags(text) {
281
282
  throw new Error(refusal(tags));
282
283
  }
283
284
  /** The owner's pass of the review verdict for one commit, which no agent
284
- * adds ("What merges without the owner" in rules.md). */
285
- export function refuseOverride(label) {
286
- if (label.trim().toLowerCase() === "verdict: override")
287
- throw new Error("Refused: the verdict: override label is the owner's pass of the review verdict, which an agent never adds.");
285
+ * adds ("What merges without the owner" in rules.md), by its key or by
286
+ * `name`, the name the settings give it. */
287
+ export function refuseOverride(label, name) {
288
+ const given = label.trim();
289
+ if ([PR_LABELS["verdict-override"], name].some((n) => sameLabel(n, given)))
290
+ throw new Error(`Refused: the ${name} label is the owner's pass of the review verdict, which an agent never adds.`);
288
291
  }
@@ -0,0 +1,28 @@
1
+ /** The labels on tickets, each key with its default name. */
2
+ export declare const TICKET_LABELS: {
3
+ readonly spec: "spec";
4
+ readonly "follow-up": "follow-up";
5
+ };
6
+ /** The labels on pull requests, each key with its default name. */
7
+ export declare const PR_LABELS: {
8
+ readonly "merge-automatic": "merge-automatic";
9
+ readonly "merge-manual": "merge-manual";
10
+ readonly "verdict-override": "verdict-override";
11
+ };
12
+ export type TicketLabel = keyof typeof TICKET_LABELS;
13
+ export type PrLabel = keyof typeof PR_LABELS;
14
+ /** The name in effect for each key. */
15
+ export type Labels = {
16
+ tickets: Record<TicketLabel, string>;
17
+ codeHost: Record<PrLabel, string>;
18
+ };
19
+ export declare const DEFAULT_LABELS: Labels;
20
+ /** A key's name on one side, or `word` unchanged when it is not one of
21
+ * that side's keys, so a label of the repository's own passes through. */
22
+ export declare function labelOf(names: Readonly<Record<string, string>>, word: string): string;
23
+ /** Two names that differ only in capitals count as one label. */
24
+ export declare const sameLabel: (a: string, b: string) => boolean;
25
+ /** Labels as a person or a session reads them: one whose name is not its
26
+ * key carries the key after it, as `needs-spec (spec)`, so a session that
27
+ * knows only the key can tell which it is. */
28
+ export declare function shownLabels(labels: readonly string[], names: Readonly<Record<string, string>>): string[];
@@ -0,0 +1,36 @@
1
+ // The labels the factory adds to tickets and pull requests. Each has a key,
2
+ // which the skills, rules, and commands use, and a name, which the ticket
3
+ // system or code host shows: the key unless `tickets.labels` or
4
+ // `code-host.labels` sets another. It imports nothing that imports the
5
+ // settings, so the hooks can read it without them.
6
+ /** The labels on tickets, each key with its default name. */
7
+ export const TICKET_LABELS = {
8
+ spec: "spec",
9
+ "follow-up": "follow-up",
10
+ };
11
+ /** The labels on pull requests, each key with its default name. */
12
+ export const PR_LABELS = {
13
+ "merge-automatic": "merge-automatic",
14
+ "merge-manual": "merge-manual",
15
+ "verdict-override": "verdict-override",
16
+ };
17
+ export const DEFAULT_LABELS = {
18
+ tickets: { ...TICKET_LABELS },
19
+ codeHost: { ...PR_LABELS },
20
+ };
21
+ /** A key's name on one side, or `word` unchanged when it is not one of
22
+ * that side's keys, so a label of the repository's own passes through. */
23
+ export function labelOf(names, word) {
24
+ return Object.hasOwn(names, word) ? names[word] : word;
25
+ }
26
+ /** Two names that differ only in capitals count as one label. */
27
+ export const sameLabel = (a, b) => a.toLowerCase() === b.toLowerCase();
28
+ /** Labels as a person or a session reads them: one whose name is not its
29
+ * key carries the key after it, as `needs-spec (spec)`, so a session that
30
+ * knows only the key can tell which it is. */
31
+ export function shownLabels(labels, names) {
32
+ const keyOf = new Map(Object.entries(names)
33
+ .filter(([key, name]) => key !== name)
34
+ .map(([key, name]) => [name, key]));
35
+ return labels.map((l) => (keyOf.has(l) ? `${l} (${keyOf.get(l)})` : l));
36
+ }
@@ -4,4 +4,4 @@
4
4
  * the `spec` label needs its decisions and at least one acceptance
5
5
  * criterion. One with it needs its decisions, a spec with a capability
6
6
  * and a numbered line, and the builder's design and tasks. */
7
- export declare function missingParts(body: string, labels: string[]): string[];
7
+ export declare function missingParts(body: string, labels: string[], names: Readonly<Record<"spec" | "follow-up", string>>): string[];
@@ -2,8 +2,6 @@
2
2
  // `factory ticket refined` makes before it posts the marker, for the
3
3
  // factory's own refiner as for a plugin's. It reads headings only, never
4
4
  // what a section says.
5
- const SPEC_LABEL = "spec";
6
- const FOLLOW_UP_LABEL = "follow-up";
7
5
  /** The body's lines outside its fenced code blocks, so a sample body in a
8
6
  * code block is not read as the ticket's own. */
9
7
  function proseLines(body) {
@@ -39,8 +37,8 @@ function under(lines, heading, toEnd = false) {
39
37
  * the `spec` label needs its decisions and at least one acceptance
40
38
  * criterion. One with it needs its decisions, a spec with a capability
41
39
  * and a numbered line, and the builder's design and tasks. */
42
- export function missingParts(body, labels) {
43
- if (labels.includes(FOLLOW_UP_LABEL))
40
+ export function missingParts(body, labels, names) {
41
+ if (labels.includes(names["follow-up"]))
44
42
  return [];
45
43
  const lines = proseLines(body);
46
44
  const missing = [];
@@ -49,7 +47,7 @@ export function missingParts(body, labels) {
49
47
  missing.push(`missing: ${part}`);
50
48
  };
51
49
  need(lines.includes("## Decisions"), "## Decisions");
52
- if (!labels.includes(SPEC_LABEL)) {
50
+ if (!labels.includes(names.spec)) {
53
51
  const criteria = under(lines, "## Acceptance criteria");
54
52
  if (criteria === null)
55
53
  need(false, "## Acceptance criteria");
@@ -153,15 +153,17 @@ export type Derived = {
153
153
  /** Open pull requests that put the issue In review. */
154
154
  pulls: number[];
155
155
  };
156
- /** The pull requests that put this issue In review. */
157
- export declare function reviewingPulls(issue: Issue, pulls: PullRequest[]): PullRequest[];
156
+ /** The pull requests that put this issue In review: those that close it,
157
+ * and on the follow-ups ticket, labeled `followUp`, those that build part
158
+ * of it. */
159
+ export declare function reviewingPulls(issue: Issue, pulls: PullRequest[], followUp?: string): PullRequest[];
158
160
  /** The page of an Actions run, from the board's or the view's session: the
159
161
  * run's ID, which `runPage` turns into its page. Null for any other
160
162
  * session. */
161
163
  export declare function actionsRunLink(derived: Pick<Derived, "session" | "runsIn">, runPage: (id: string) => string): string | null;
162
164
  /** An issue's Status is the first rule that applies: Done, In review,
163
165
  * In progress, Ready, In refinement, Backlog. */
164
- export declare function derive(issue: Issue, card: BoardCard | null, pulls: PullRequest[], columns?: Columns): Derived;
166
+ export declare function derive(issue: Issue, card: BoardCard | null, pulls: PullRequest[], columns?: Columns, followUp?: string): Derived;
165
167
  /** Over 24 hours In progress or In refinement with a session. */
166
168
  export declare function isStale(derived: Derived, now: Date): boolean;
167
169
  /** How long a card may sit in Ready before the poller should have started
@@ -178,7 +180,7 @@ export declare function watchOf(trigger: "own-server" | "github-action" | "manua
178
180
  export declare function isNotStarted(derived: Derived, openBlockers: Key[], now: Date, minutes?: number): boolean;
179
181
  /** A claim or start over 24 hours old with no pull request, which the
180
182
  * nightly sync clears. Null when there is nothing to clear. */
181
- export declare function toClear(issue: Issue, pulls: PullRequest[], now: Date): {
183
+ export declare function toClear(issue: Issue, pulls: PullRequest[], now: Date, followUp?: string): {
182
184
  kind: "claim" | "start";
183
185
  since: string;
184
186
  } | null;
@@ -1,3 +1,10 @@
1
+ // Who is working on what, read from the marker comments sessions post on a
2
+ // ticket and from the board's Status. The terminal view
3
+ // (`factory status`), the board sync (`factory board`), and the
4
+ // poller (`factory poller`) all decide from this one module, so they
5
+ // cannot disagree. It reads tickets as the ticket interface returns them
6
+ // (`tickets/types.mts`) and never calls a ticket system itself.
7
+ import { TICKET_LABELS } from "../labels.mjs";
1
8
  export const AGENT_MARK = "<!-- agent -->";
2
9
  export const STATUSES = [
3
10
  "Backlog",
@@ -215,10 +222,12 @@ export function workState(comments) {
215
222
  }
216
223
  return { live, lastLive, start };
217
224
  }
218
- /** The pull requests that put this issue In review. */
219
- export function reviewingPulls(issue, pulls) {
225
+ /** The pull requests that put this issue In review: those that close it,
226
+ * and on the follow-ups ticket, labeled `followUp`, those that build part
227
+ * of it. */
228
+ export function reviewingPulls(issue, pulls, followUp = TICKET_LABELS["follow-up"]) {
220
229
  return pulls.filter((pull) => pull.closes.includes(issue.key) ||
221
- (issue.labels.includes("follow-up") && pull.partOf.includes(issue.key)));
230
+ (issue.labels.includes(followUp) && pull.partOf.includes(issue.key)));
222
231
  }
223
232
  const READY_RESETS = new Set([
224
233
  "released",
@@ -256,7 +265,7 @@ function claimSession(claim) {
256
265
  }
257
266
  /** An issue's Status is the first rule that applies: Done, In review,
258
267
  * In progress, Ready, In refinement, Backlog. */
259
- export function derive(issue, card, pulls, columns = DEFAULT_COLUMNS) {
268
+ export function derive(issue, card, pulls, columns = DEFAULT_COLUMNS, followUp = TICKET_LABELS["follow-up"]) {
260
269
  const work = workState(issue.comments);
261
270
  const marked = markedComments(issue.comments);
262
271
  if (issue.state === "closed") {
@@ -267,7 +276,7 @@ export function derive(issue, card, pulls, columns = DEFAULT_COLUMNS) {
267
276
  pulls: [],
268
277
  };
269
278
  }
270
- const reviewing = reviewingPulls(issue, pulls);
279
+ const reviewing = reviewingPulls(issue, pulls, followUp);
271
280
  if (reviewing.length > 0) {
272
281
  const first = [...reviewing].sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
273
282
  return {
@@ -396,8 +405,9 @@ export function isNotStarted(derived, openBlockers, now, minutes = 5) {
396
405
  }
397
406
  /** A claim or start over 24 hours old with no pull request, which the
398
407
  * nightly sync clears. Null when there is nothing to clear. */
399
- export function toClear(issue, pulls, now) {
400
- if (issue.state !== "open" || reviewingPulls(issue, pulls).length > 0)
408
+ export function toClear(issue, pulls, now, followUp = TICKET_LABELS["follow-up"]) {
409
+ if (issue.state !== "open" ||
410
+ reviewingPulls(issue, pulls, followUp).length > 0)
401
411
  return null;
402
412
  const work = workState(issue.comments);
403
413
  const old = (m) => m !== null && now.getTime() - Date.parse(m.createdAt) > 24 * HOUR;
@@ -12,10 +12,10 @@ export declare const inGithubNames: (files: {
12
12
  previousPath?: string;
13
13
  status: string;
14
14
  }[]) => ChangedFile[];
15
- /** The two merge labels. The merge-policy workflow applies one and removes the
16
- * other; only "merge: automatic" turns auto-merge on. */
17
- export declare const AUTOMATIC = "merge: automatic";
18
- export declare const MANUAL = "merge: manual";
15
+ /** The keys of the two merge labels. The merge-policy workflow applies one
16
+ * and removes the other; only the automatic one turns auto-merge on. */
17
+ export declare const AUTOMATIC = "merge-automatic";
18
+ export declare const MANUAL = "merge-manual";
19
19
  export type Risk = {
20
20
  risk: typeof AUTOMATIC | typeof MANUAL;
21
21
  reasons: string[];
@@ -53,9 +53,11 @@ export declare function decide(paths: Risk, commandHolds: string[]): Risk;
53
53
  /** The description of the "Who merges" commit status: what happens, and why,
54
54
  * on one line. GitHub cuts a status description at 140 characters. */
55
55
  export declare function statusLine({ risk, reasons }: Risk): string;
56
- /** What the merge-policy workflow needs: the label to set, the one to remove,
57
- * whether auto-merge goes on, and the status line. */
58
- export declare function workflowOutput(result: Risk): {
56
+ /** What the merge-policy workflow needs: the label to set and the one to
57
+ * remove, each by the name `names` gives it, whether auto-merge goes on,
58
+ * and the status line. */
59
+ export declare function workflowOutput(result: Risk, names: Readonly<Record<typeof AUTOMATIC | typeof MANUAL, string>>): {
60
+ label: string;
59
61
  other: string;
60
62
  automatic: boolean;
61
63
  status: string;