@moo.md/hum 0.0.0 → 0.2.0

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 (110) hide show
  1. package/package.json +2 -2
  2. package/schema/hum.schema.json +2 -2
  3. package/scripts/eval.ts +88 -50
  4. package/src/adapter-api.ts +46 -14
  5. package/src/adapters/admit.ts +2 -2
  6. package/src/adapters/argument.ts +1 -1
  7. package/src/adapters/claim.ts +18 -15
  8. package/src/adapters/claude-bg.ts +72 -32
  9. package/src/adapters/claude-p.ts +26 -25
  10. package/src/adapters/contract.ts +22 -10
  11. package/src/adapters/each-call.ts +9 -0
  12. package/src/adapters/fake.ts +6 -6
  13. package/src/adapters/git.ts +12 -19
  14. package/src/adapters/github-client.ts +102 -0
  15. package/src/adapters/github.ts +50 -136
  16. package/src/adapters/guard.ts +20 -9
  17. package/src/adapters/history.ts +12 -15
  18. package/src/adapters/item-file.ts +1 -1
  19. package/src/adapters/markdown.ts +49 -42
  20. package/src/adapters/marked.ts +15 -13
  21. package/src/adapters/model-call.ts +4 -4
  22. package/src/adapters/once.ts +5 -5
  23. package/src/adapters/owner-commit.ts +13 -11
  24. package/src/adapters/pull-requests.ts +11 -13
  25. package/src/adapters/registry.ts +7 -7
  26. package/src/adapters/roundup.ts +31 -37
  27. package/src/adapters/serial.ts +4 -5
  28. package/src/adapters/transcript.ts +13 -8
  29. package/src/cli/main.ts +1 -0
  30. package/src/cli/ops.ts +32 -14
  31. package/src/cli/service.ts +14 -8
  32. package/src/cli/setup.ts +8 -3
  33. package/src/cli/shared-watch.ts +3 -3
  34. package/src/config/checks.ts +14 -18
  35. package/src/config/machine.ts +5 -7
  36. package/src/config/refusal.ts +7 -0
  37. package/src/config/schema.ts +9 -9
  38. package/src/config/settings.ts +17 -2
  39. package/src/config/state-map.ts +5 -3
  40. package/src/decide/alignment.ts +4 -4
  41. package/src/decide/answer.ts +24 -22
  42. package/src/decide/kind.ts +1 -6
  43. package/src/decide/labels.ts +9 -9
  44. package/src/decide/merge.ts +6 -7
  45. package/src/decide/prose.ts +4 -4
  46. package/src/decide/question.ts +23 -20
  47. package/src/decide/review.ts +4 -2
  48. package/src/decide/risk.ts +25 -19
  49. package/src/decide/taste.ts +3 -3
  50. package/src/exec.ts +10 -4
  51. package/src/index.ts +14 -13
  52. package/src/loop/check-item.ts +3 -3
  53. package/src/loop/ci.ts +1 -1
  54. package/src/loop/github.ts +2 -2
  55. package/src/loop/groups.ts +13 -6
  56. package/src/loop/memory.ts +40 -28
  57. package/src/loop/notes.ts +5 -5
  58. package/src/loop/pair.ts +1 -1
  59. package/src/loop/pass.ts +18 -12
  60. package/src/loop/proof.ts +9 -7
  61. package/src/loop/prove-item.ts +3 -3
  62. package/src/loop/records.ts +12 -13
  63. package/src/loop/signals.ts +6 -6
  64. package/src/measure/inputs.ts +1 -1
  65. package/src/measure/measure.ts +4 -4
  66. package/src/measure/rate.ts +2 -0
  67. package/src/service/ci-tick.ts +2 -2
  68. package/src/service/supervise.ts +3 -2
  69. package/src/service/token.ts +3 -3
  70. package/src/service/wake.ts +2 -2
  71. package/src/service/workflows.ts +2 -2
  72. package/src/setup/propose.ts +4 -4
  73. package/src/setup/prove.ts +20 -14
  74. package/src/setup/scan.ts +31 -24
  75. package/src/setup/shipped.ts +8 -2
  76. package/src/setup/tables.ts +4 -3
  77. package/src/setup/waits.ts +9 -11
  78. package/src/setup/write.ts +17 -10
  79. package/src/slots/pool.ts +32 -24
  80. package/src/state/events.ts +1 -1
  81. package/src/state/faults.ts +13 -5
  82. package/src/state/format.ts +2 -2
  83. package/src/state/items.ts +20 -15
  84. package/src/state/open.ts +2 -2
  85. package/src/state/ops.ts +16 -10
  86. package/src/state/records.ts +5 -5
  87. package/src/state/runs.ts +33 -26
  88. package/src/state/saved.ts +44 -32
  89. package/src/status/file.ts +20 -1
  90. package/src/status/format.ts +47 -57
  91. package/src/status/sections.ts +2 -2
  92. package/src/worker/alignment-report.ts +4 -5
  93. package/src/worker/answers.ts +26 -24
  94. package/src/worker/base-check.ts +4 -5
  95. package/src/worker/checks.ts +25 -11
  96. package/src/worker/kind.ts +23 -19
  97. package/src/worker/land.ts +115 -126
  98. package/src/worker/merged.ts +9 -7
  99. package/src/worker/open.ts +15 -13
  100. package/src/worker/prose-run.ts +3 -3
  101. package/src/worker/questions.ts +15 -12
  102. package/src/worker/scheduler.ts +4 -4
  103. package/src/worker/signature.ts +3 -3
  104. package/src/worker/tally.ts +0 -2
  105. package/src/worker/taste.ts +6 -15
  106. package/src/worker/thin-path.ts +150 -123
  107. package/src/worker/thread.ts +25 -0
  108. package/src/worker/worker.ts +125 -73
  109. package/surface.json +633 -2198
  110. package/src/slots/scan.ts +0 -26
@@ -24,7 +24,7 @@ export const FIXED_PARTS = [
24
24
 
25
25
  export const PURPOSES = ["plan", "build", "fix", "review"] as const;
26
26
  export const SIZES = ["small", "medium", "large"] as const;
27
- export const TIERS = ["light", "standard", "top"] as const;
27
+ const TIERS = ["light", "standard", "top"] as const;
28
28
  export const EFFORTS = ["low", "medium", "high"] as const;
29
29
 
30
30
  /** A machine state tagged with either of these waits on something outside the run. */
@@ -49,7 +49,7 @@ const branchPrefix = z
49
49
  .refine(isBranchPrefix, "a branch prefix followed by an item id must make a valid git branch name");
50
50
 
51
51
  /** Where hum runs: a service on the owner's Mac, and a scheduled and event-woken CI workflow. */
52
- export const RUN_PLACES = ["mac", "ci"] as const;
52
+ const RUN_PLACES = ["mac", "ci"] as const;
53
53
 
54
54
  export type RunPlace = (typeof RUN_PLACES)[number];
55
55
 
@@ -61,10 +61,10 @@ export type MergeMethod = (typeof MERGE_METHODS)[number];
61
61
  export const REVIEWS = ["none", "agent", "owner"] as const;
62
62
 
63
63
  /** When a merged change ships: at once, or once the proof its path names arrives. */
64
- export const RELEASES = ["at-once", "after-proof"] as const;
64
+ const RELEASES = ["at-once", "after-proof"] as const;
65
65
 
66
66
  /** What a break after merge becomes: follow-up work, or a block on the path. */
67
- export const BREAKS = ["follow-up", "block"] as const;
67
+ const BREAKS = ["follow-up", "block"] as const;
68
68
 
69
69
  /** Each place a model's judgment decides, measured on its own labelled set. */
70
70
  export const BOUNDARIES = ["kind", "alignment", "plan-outcome", "review-verdict", "reply-option", "repeat-pair", "taste"] as const;
@@ -87,10 +87,10 @@ const pattern = z.string().min(1).refine(isRegExp, "a pattern is a valid regular
87
87
  const date = z.iso.date();
88
88
 
89
89
  /** When a refresh step runs: after every return, or only when a lockfile changed since the slot was last installed. */
90
- export const REFRESH_WHEN = ["always", "lockfile-changed"] as const;
90
+ const REFRESH_WHEN = ["always", "lockfile-changed"] as const;
91
91
 
92
92
  /** Whether a slot gets its own services, or every slot shares one set and gets its own database. */
93
- export const SLOT_SERVICES = ["per-slot", "shared"] as const;
93
+ const SLOT_SERVICES = ["per-slot", "shared"] as const;
94
94
 
95
95
  const RefreshStep = z.strictObject({ run: name, when: z.enum(REFRESH_WHEN) });
96
96
 
@@ -157,7 +157,7 @@ const Shipped = z.object({
157
157
  mergedShown: count.describe("Merged changes the status file lists."),
158
158
  choicesShown: count.describe("Choices made without the owner that the status file lists, newest first."),
159
159
  statusReadTimeoutSeconds: seconds.describe("How long a read for the status file, such as the newest published version, may take before it is left out."),
160
- commandTimeoutSeconds: seconds.describe("How long one git, gh, npm or Claude Code management command may run before it is stopped and its call fails naming it. A run's agent and a repo's checks have their own limits."),
160
+ commandTimeoutSeconds: seconds.describe("How long one git, gh, npm or Claude Code management command, one GitHub request or one start check may run before it is stopped and its call fails naming it. A run's agent and a repo's checks have their own limits."),
161
161
  mergeTries: count.describe("Tries to merge a change when the base branch moves under it."),
162
162
  writeRaceRetries: z.int().nonnegative().describe("Retries of a markdown write that another writer's push beat."),
163
163
  itemReadsAtOnce: count.describe("Item files the markdown source reads at once; each read is a git process."),
@@ -229,7 +229,7 @@ const Shipped = z.object({
229
229
  memoryUnusedRuns: count.describe("Runs without use after which a memory.md entry is listed for the owner."),
230
230
  measureWindow: count.describe("Merged changes the per-merge numbers average over, and the window per path."),
231
231
  loopIntervalSeconds: seconds.describe("The time between passes that collect review notes, file check items and confirm CI ran their checks."),
232
- proofTimeoutSeconds: seconds.describe("How long running a new check on one note's commit may take before the proof fails."),
232
+ proofTimeoutSeconds: seconds.describe("How long the repo's checks may run, on a run's branch, on the base after a merge or as a new check on one note's commit, before they are stopped and fail."),
233
233
  kindFloors: z.record(name, name).describe("A kind's lowest risk level: its changes take at least this level, as in { \"check\": \"high\" }."),
234
234
  checkKind: name.describe("The kind of the work item filed for a rule that review notes repeat: it turns the notes into one check."),
235
235
  breakCheck: z.boolean().describe("Whether the repo's checks run on the base after each merge, so a test that breaks there files a follow-up item."),
@@ -253,7 +253,7 @@ const withShippedDefaults = (settings: Settings): { [Key in keyof Settings]: z.Z
253
253
  // SAFETY: `Object.fromEntries` loses the per-key types; each entry is its setting with its own shipped default.
254
254
  Object.fromEntries(Object.entries<z.ZodType>(settings).map(([key, setting]) => [key, setting.default(SHIPPED_DEFAULTS[key as keyof Settings])])) as never;
255
255
 
256
- export const Role = z.strictObject({
256
+ const Role = z.strictObject({
257
257
  file: name,
258
258
  purpose: z.enum(PURPOSES),
259
259
  skills: z.array(name),
@@ -1,6 +1,21 @@
1
1
  import { join } from "node:path";
2
2
  import type { z } from "zod";
3
3
  import { orMissing, readJson } from "../state/fs.ts";
4
+ import { migrateConfig } from "./migrate.ts";
4
5
 
5
- /** The settings `schema` names, read from the repo's `.hum/hum.json`. A repo with no `hum.json` gets the schema's own defaults. Throws when the file is unreadable or a value is refused. */
6
- export const readSettings = <S extends z.ZodType>(repo: string, schema: S): z.output<S> => schema.parse(orMissing(() => readJson(join(repo, ".hum", "hum.json")), {}));
6
+ /**
7
+ * The settings `schema` names, read from the repo's `.hum/hum.json` after it is migrated to the schema version this
8
+ * engine runs. A repo with no `hum.json` gets the schema's own defaults. Throws when the file is unreadable, its
9
+ * schema version is one this engine does not read, or a value is refused.
10
+ */
11
+ export const readSettings = <S extends z.ZodType>(repo: string, schema: S): z.output<S> => {
12
+ const raw = orMissing(() => readJson(join(repo, ".hum", "hum.json")), undefined);
13
+
14
+ if (raw === undefined) return schema.parse({});
15
+
16
+ const migrated = migrateConfig(raw);
17
+
18
+ if (!migrated.ok) throw new Error(migrated.refusal.message);
19
+
20
+ return schema.parse(migrated.value);
21
+ };
@@ -5,9 +5,11 @@ import type { Config } from "./load.ts";
5
5
  import { kindMachine } from "./machine.ts";
6
6
  import type { Kind } from "./schema.ts";
7
7
 
8
- /** A work item saved in a state of a kind. */
8
+ /** A work item saved in a state of a kind. `kind` is the kind's `machine.id`, as a saved snapshot records it, which need not be its file name. */
9
9
  export type SavedItem = { readonly kind: string; readonly state: string };
10
10
 
11
+ const kindWithId = (config: Config, id: string): Kind | undefined => Object.values(config.kinds).find((kind) => kind.machine.id === id);
12
+
11
13
  /** Where a saved state goes under the new kind: itself, its mapped name, or nowhere. */
12
14
  const mappedState = (previous: Kind, next: Kind, state: string): string | undefined => {
13
15
  if (state in next.machine.states) return state;
@@ -19,8 +21,8 @@ const mappedState = (previous: Kind, next: Kind, state: string): string | undefi
19
21
  /** The saved items whose state the new config neither keeps nor maps. */
20
22
  export const unmappedItems = (current: Config, next: Config, saved: readonly SavedItem[]): SavedItem[] =>
21
23
  saved.filter(({ kind, state }) => {
22
- const previous = current.kinds[kind];
23
- const target = next.kinds[kind];
24
+ const previous = kindWithId(current, kind);
25
+ const target = kindWithId(next, kind);
24
26
 
25
27
  return previous !== undefined && (target === undefined || mappedState(previous, target, state) === undefined);
26
28
  });
@@ -15,12 +15,12 @@ export const AlignmentAnswer = z.strictObject({ alignment: Grade, verification:
15
15
  export type AlignmentAnswer = z.infer<typeof AlignmentAnswer>;
16
16
 
17
17
  /** Whether the alignment call may raise a level: the decision model's measured rate at this boundary meets the bar. */
18
- export const gatesAlignment = (config: Pick<HumConfig, "decisionModel" | "measuredModels" | "minJudgeRate">): boolean => isTrusted([config.decisionModel], "alignment", config);
18
+ export const doesGateAlignment = (config: Pick<HumConfig, "decisionModel" | "measuredModels" | "minJudgeRate">): boolean => isTrusted([config.decisionModel], "alignment", config);
19
19
 
20
20
  /** The cheap model call that grades a change against the item it answers. Below the bar its grades go in a report and decide nothing. */
21
21
  export const alignmentQuestion = (item: Pick<Item, "title" | "body">, diff: string, config: Pick<HumConfig, "diffLimit" | "decisionModel" | "measuredModels" | "minJudgeRate">) => ({
22
22
  boundary: "alignment" as const,
23
- reportOnly: !gatesAlignment(config) || undefined,
23
+ reportOnly: !doesGateAlignment(config) || undefined,
24
24
  prompt: [
25
25
  "Grade this change against the item it answers. alignment: does the diff do what the item asked, no more and no less? verification: do the tests or proof in the diff show it works? Grade each sound, partial or concern.",
26
26
  DATA_RULE,
@@ -61,7 +61,7 @@ const gradeOfRank = (rank: number, levels: number): number => (levels < 2 ? GRAD
61
61
  * Whether the alignment call's grades raise the level one step: they put the merge-risk score in a higher band than
62
62
  * sound grades would at the same level. The call never lowers a level.
63
63
  */
64
- export const raisesLevel = (rank: number, levels: number, answer: AlignmentAnswer, { mergeRisk }: Pick<HumConfig, "mergeRisk">): boolean => {
64
+ export const doesRaiseLevel = ({ rank, levels, answer, config: { mergeRisk } }: { readonly rank: number; readonly levels: number; readonly answer: AlignmentAnswer; readonly config: Pick<HumConfig, "mergeRisk"> }): boolean => {
65
65
  const fromLevel = gradeOfRank(rank, levels);
66
66
 
67
67
  const scored = (alignment: number, verification: number): number =>
@@ -75,5 +75,5 @@ export const alignedPlacement = (placement: Placement, answer: AlignmentAnswer,
75
75
  const rank = config.levels.findIndex(({ name }) => name === placement.level.name);
76
76
  const above = config.levels[Math.min(rank + 1, config.levels.length - 1)];
77
77
 
78
- return above && raisesLevel(rank, config.levels.length, answer, config) ? { ...placement, level: above, steps: [...placement.steps, { step: "alignment" }] } : placement;
78
+ return above && doesRaiseLevel({ rank, levels: config.levels.length, answer, config }) ? { ...placement, level: above, steps: [...placement.steps, { step: "alignment" }] } : placement;
79
79
  };
@@ -2,6 +2,7 @@ import { z } from "zod";
2
2
  import type { ThreadEntry } from "../adapter-api.ts";
3
3
  import { OWNER_APPROVAL } from "./merge.ts";
4
4
  import { DATA_RULE, fenced } from "./prose.ts";
5
+ import { bareWord } from "./question.ts";
5
6
 
6
7
  /** What the model call answers when none of the question's options fits the reply. */
7
8
  export const NONE_OF_THESE = "none of these";
@@ -15,10 +16,17 @@ export type Resolution =
15
16
  | { readonly source: "none-of-these" }
16
17
  | { readonly source: "abstained"; readonly why: string };
17
18
 
18
- const WORD_EDGES = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
19
+ /** Each way an answer comes to pick its option, by the name its settled answer is saved under. */
20
+ export const RESOLUTION_SOURCES = {
21
+ marker: "marker",
22
+ free: "free",
23
+ "first-word": "first-word",
24
+ model: "model",
25
+ "none-of-these": "none-of-these",
26
+ abstained: "abstained",
27
+ } as const satisfies { readonly [S in Resolution["source"]]: S };
19
28
 
20
- const firstWordOf = (text: string): string =>
21
- (text.trim().split(/\s+/)[0] ?? "").replaceAll(WORD_EDGES, "").toLowerCase();
29
+ const firstWordOf = (text: string): string => bareWord(text.trim().split(/\s+/)[0] ?? "").toLowerCase();
22
30
 
23
31
  /** The option an answer picks by its hidden marker, else by its first word matching an option exactly. */
24
32
  export const matchOption = (
@@ -39,9 +47,7 @@ export const matchOption = (
39
47
 
40
48
  /** The cheap model call that picks one of a question's options for a reply no marker or exact word settles. */
41
49
  export const replyQuestion = (
42
- question: string,
43
- options: readonly string[],
44
- reply: string,
50
+ { question, options, reply }: { readonly question: string; readonly options: readonly string[]; readonly reply: string },
45
51
  ) => ({
46
52
  boundary: "reply-option" as const,
47
53
  prompt: [
@@ -65,12 +71,14 @@ export type Stage =
65
71
  /** It has merged, or otherwise ended. */
66
72
  | "ended";
67
73
 
74
+ export const DISPOSITIONS = ["applied", "held", "dropped"] as const;
75
+
68
76
  export type Disposition = {
69
- readonly disposition: "applied" | "held" | "dropped";
77
+ readonly disposition: (typeof DISPOSITIONS)[number];
70
78
  readonly why: string;
71
79
  };
72
80
 
73
- export type DisposeFacts = {
81
+ type DisposeFacts = {
74
82
  readonly resolution: Resolution;
75
83
  /** An earlier answer to the same question was applied. */
76
84
  readonly answeredBefore: boolean;
@@ -79,6 +87,11 @@ export type DisposeFacts = {
79
87
 
80
88
  const dropped = (why: string): Disposition => ({ disposition: "dropped", why });
81
89
 
90
+ const isUnmatched = ({ source }: Resolution): boolean => source === "none-of-these" || source === "abstained";
91
+
92
+ /** Whether a model call, not the owner's own word, picked the approval. */
93
+ const isModelApproval = (resolution: Resolution): boolean => resolution.source === "model" && resolution.option === OWNER_APPROVAL;
94
+
82
95
  /** D4: every answer is applied, held for the next state, or dropped with its reason. A model's pick never approves a change that waits for the owner's approval. */
83
96
  export const dispose = ({
84
97
  resolution,
@@ -87,20 +100,9 @@ export const dispose = ({
87
100
  }: DisposeFacts): Disposition => {
88
101
  if (answeredBefore) return dropped("The question already has an answer.");
89
102
 
90
- if (
91
- resolution.source === "none-of-these" ||
92
- resolution.source === "abstained"
93
- )
94
- return dropped("No option matched the reply.");
95
-
96
- if (
97
- resolution.source === "model" &&
98
- resolution.option === OWNER_APPROVAL &&
99
- stage === "approval"
100
- )
101
- return dropped(
102
- `a model cannot approve it; reply with the word ${OWNER_APPROVAL}`,
103
- );
103
+ if (isUnmatched(resolution)) return dropped("No option matched the reply.");
104
+
105
+ if (isModelApproval(resolution) && stage === "approval") return dropped(`a model cannot approve it; reply with the word ${OWNER_APPROVAL}`);
104
106
 
105
107
  if (stage === "ended") return dropped("The item has ended.");
106
108
 
@@ -9,11 +9,6 @@ const TEMPLATE_FIELD = /^(?:kind:[ \t]*(\S+)|#{1,6}[ \t]*kind[ \t]*\n+[ \t]*(\S+
9
9
  /** The answer a model call gives when no kind fits. */
10
10
  export const UNSURE = "unsure";
11
11
 
12
- /** Where an item's kind came from. A fallback is an abstention: the item is unclear and runs on the fallback kind. */
13
- export type KindOf =
14
- | { readonly kind: string; readonly from: "source" | "model" }
15
- | { readonly kind: string; readonly from: "fallback"; readonly why: string };
16
-
17
12
  /** The kind an item names itself: a label the owner mapped to a kind or that is a kind's name, else its template field. */
18
13
  export const declaredKind = (item: Pick<Item, "body" | "labels">, kinds: readonly string[], kindLabels: HumConfig["kindLabels"]): string | undefined => {
19
14
  const field = TEMPLATE_FIELD.exec(item.body);
@@ -35,5 +30,5 @@ export const kindQuestion = (item: Pick<Item, "title" | "body">, { kinds, kindMe
35
30
  });
36
31
 
37
32
  /** A change of the docs-only kind that touches a path outside its globs is not docs. */
38
- export const leavesDocs = (paths: readonly string[], { docsOnly }: Pick<HumConfig, "docsOnly">): boolean =>
33
+ export const doesLeaveDocs = (paths: readonly string[], { docsOnly }: Pick<HumConfig, "docsOnly">): boolean =>
39
34
  paths.some((path) => !docsOnly.paths.some((glob) => new Bun.Glob(glob).match(path)));
@@ -22,15 +22,15 @@ const SHA_IN_TEXT = /\b[0-9a-f]{7,40}\b/g;
22
22
  const shasIn = (text: string): readonly string[] =>
23
23
  text.match(SHA_IN_TEXT) ?? [];
24
24
 
25
- const names = (later: PastChange, earlier: PastChange): boolean =>
25
+ const doesName = (later: PastChange, earlier: PastChange): boolean =>
26
26
  shasIn(`${later.subject}\n${later.body}`).some((sha) =>
27
27
  earlier.sha.startsWith(sha),
28
28
  );
29
29
 
30
- const sharesAFile = (a: PastChange, b: PastChange): boolean =>
30
+ const doShareAFile = (a: PastChange, b: PastChange): boolean =>
31
31
  a.files.some((file) => b.files.includes(file));
32
32
 
33
- const revertsByTrailer = (
33
+ const doesRevertByTrailer = (
34
34
  later: PastChange,
35
35
  earlier: PastChange,
36
36
  { revertTrailer }: LabelRules,
@@ -39,14 +39,14 @@ const revertsByTrailer = (
39
39
  ([, sha]) => sha !== undefined && earlier.sha.startsWith(sha),
40
40
  );
41
41
 
42
- const revertsByTitle = (
42
+ const doesRevertByTitle = (
43
43
  later: PastChange,
44
44
  earlier: PastChange,
45
45
  { revertSubject }: LabelRules,
46
46
  ): boolean =>
47
47
  new RegExp(revertSubject).test(later.subject) &&
48
48
  (later.subject.includes(`"${earlier.subject}"`) ||
49
- names(later, earlier) ||
49
+ doesName(later, earlier) ||
50
50
  later.blamed.includes(earlier.sha));
51
51
 
52
52
  const isRevertOf = (
@@ -54,8 +54,8 @@ const isRevertOf = (
54
54
  earlier: PastChange,
55
55
  rules: LabelRules,
56
56
  ): boolean =>
57
- revertsByTrailer(later, earlier, rules) ||
58
- revertsByTitle(later, earlier, rules);
57
+ doesRevertByTrailer(later, earlier, rules) ||
58
+ doesRevertByTitle(later, earlier, rules);
59
59
 
60
60
  const isFixOf = (
61
61
  later: PastChange,
@@ -63,7 +63,7 @@ const isFixOf = (
63
63
  { fixSubject }: LabelRules,
64
64
  ): boolean =>
65
65
  new RegExp(fixSubject).test(later.subject) &&
66
- (names(later, earlier) || later.blamed.includes(earlier.sha));
66
+ (doesName(later, earlier) || later.blamed.includes(earlier.sha));
67
67
 
68
68
  /** The later change that breaks `changes[at]`, and how: a revert of it, else a fix among the next `fixWindow` changes on its files. */
69
69
  export const breakOf = (
@@ -81,7 +81,7 @@ export const breakOf = (
81
81
  if (reverting) return { by: reverting, label: "reverted" };
82
82
 
83
83
  const fixing = later
84
- .filter((next) => sharesAFile(next, change))
84
+ .filter((next) => doShareAFile(next, change))
85
85
  .slice(0, rules.fixWindow)
86
86
  .find((next) => isFixOf(next, change, rules));
87
87
 
@@ -30,11 +30,11 @@ const STRICTEST_PROOF = "the owner's word that the change is proven";
30
30
  export type Approvals = { readonly review: boolean; readonly owner: boolean };
31
31
 
32
32
  /** What clears a clear change without the owner, by its level's review. The owner's approval clears any change. */
33
- const CLEARED_BY: Readonly<Record<(typeof REVIEWS)[number], (approvals: Approvals) => boolean>> = {
33
+ const CLEARED_BY = {
34
34
  none: () => true,
35
35
  agent: (approvals) => approvals.review,
36
36
  owner: () => false,
37
- };
37
+ } as const satisfies Record<(typeof REVIEWS)[number], (approvals: Approvals) => boolean>;
38
38
 
39
39
  const NO_APPROVALS: Approvals = { review: false, owner: false };
40
40
 
@@ -60,7 +60,7 @@ export const routeOf = (
60
60
  return {
61
61
  level,
62
62
  unclear,
63
- mergesAlone: unclear.length === 0 && CLEARED_BY[level.review](NO_APPROVALS),
63
+ mergesAlone: isCleared({ level, unclear }, NO_APPROVALS),
64
64
  proof:
65
65
  level.release === "after-proof"
66
66
  ? proofs.join("; ") || STRICTEST_PROOF
@@ -69,16 +69,15 @@ export const routeOf = (
69
69
  };
70
70
 
71
71
  /** A route merges once nothing waits: on its own, once a fresh review approved a clear change at an agent-reviewed level, or once the owner approved it. */
72
- export const isCleared = (route: Route, approvals: Approvals): boolean =>
72
+ export const isCleared = (route: Pick<Route, "level" | "unclear">, approvals: Approvals): boolean =>
73
73
  approvals.owner || (route.unclear.length === 0 && CLEARED_BY[route.level.review](approvals));
74
74
 
75
75
  /** Every level that asks for a review gets a fresh review run first; the owner's review comes after it. */
76
- export const needsReviewRun = (route: Route): boolean => route.level.review !== "none";
76
+ export const doesNeedReviewRun = (route: Route): boolean => route.level.review !== "none";
77
77
 
78
78
  /** Where the target branch requires a pull request, every change lands through one, merging itself only when cleared; elsewhere a cleared change is pushed. */
79
79
  export const landingOf = (
80
- requiresPullRequest: boolean,
81
- cleared: boolean,
80
+ { requiresPullRequest, cleared }: { readonly requiresPullRequest: boolean; readonly cleared: boolean },
82
81
  ): Landing => {
83
82
  if (requiresPullRequest) return { via: "pull-request", autoMerge: cleared };
84
83
 
@@ -1,9 +1,9 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { stripVTControlCharacters } from "node:util";
3
3
  import parseDiff from "parse-diff";
4
- import stringify from "safe-stable-stringify";
5
4
  import { z } from "zod";
6
5
  import type { Finished } from "../adapters/claude-p.ts";
6
+ import { hashJson } from "../config/hash.ts";
7
7
  import type { Boundary, HumConfig } from "../config/schema.ts";
8
8
 
9
9
  const TAG_HASH = 12;
@@ -41,7 +41,7 @@ export const PlanFile = z.strictObject({
41
41
  export type PlanFile = z.infer<typeof PlanFile>;
42
42
 
43
43
  /** A plan's identity: a later run reads the plan with this hash, and any other text is not the approved plan. */
44
- export const planHash = (plan: PlanFile): string => createHash("sha256").update(stringify(plan)).digest("hex");
44
+ export const planHash = (plan: PlanFile): string => hashJson(plan);
45
45
 
46
46
  /** The two states whose outcome is prose: the events each may pick, and the safer pick an unsure run takes. */
47
47
  export const PROSE_STATES = {
@@ -75,7 +75,7 @@ export const pickSchema = (events: readonly string[]): JsonSchema => jsonSchemaO
75
75
  const isInHunk = (line: number, { newStart, newLines }: { newStart: number; newLines: number }): boolean => line >= newStart && line < newStart + Math.max(newLines, 1);
76
76
 
77
77
  /** At least one cite, and each names a file the diff changes and a line inside one of its hunks. */
78
- export const citesDiff = (cites: readonly Cite[], diff: string): boolean => {
78
+ export const doesCiteDiff = (cites: readonly Cite[], diff: string): boolean => {
79
79
  const files = parseDiff(diff);
80
80
  const isChanged = ({ file, line }: Cite): boolean => files.some((changed) => changed.to === file && changed.chunks.some((hunk) => isInHunk(line, hunk)));
81
81
 
@@ -84,7 +84,7 @@ export const citesDiff = (cites: readonly Cite[], diff: string): boolean => {
84
84
 
85
85
  /** Code's check on the artifact behind a pick: why it fails, or undefined when it holds. */
86
86
  const FENCES = new Map<string, (pick: EventPick, diff: string) => string | undefined>([
87
- ["request-changes", (pick, diff) => (citesDiff(pick.cites, diff) ? undefined : "request-changes must cite a file and a line the diff changes")],
87
+ ["request-changes", (pick, diff) => (doesCiteDiff(pick.cites, diff) ? undefined : "request-changes must cite a file and a line the diff changes")],
88
88
  ["plan-ready", (pick) => (pick.plan ? undefined : "plan-ready must hold a plan: a summary, at least one step and the paths it touches")],
89
89
  ]);
90
90
 
@@ -4,9 +4,9 @@ import type { HumConfig } from "../config/schema.ts";
4
4
  import { DAY_MS } from "../time.ts";
5
5
 
6
6
  /** The reasons a run gives for needing the owner, each with the facts code checks it against. */
7
- export const ASK_REASONS = ["missing-secret", "past-undoing", "spends-money", "publishes", "choice", "unsure"] as const;
7
+ const ASK_REASONS = ["missing-secret", "past-undoing", "spends-money", "publishes", "choice", "unsure"] as const;
8
8
 
9
- export type AskReason = (typeof ASK_REASONS)[number];
9
+ type AskReason = (typeof ASK_REASONS)[number];
10
10
 
11
11
  const ChoiceOption = z.strictObject({ word: z.string().min(1), paths: z.array(z.string().min(1)) });
12
12
 
@@ -33,29 +33,29 @@ export type AskFacts = {
33
33
  readonly undoableLevels: readonly string[];
34
34
  };
35
35
 
36
- export type AskDecision =
36
+ type AskDecision =
37
37
  /** `confirmed`: the facts bear the reason out, so its own question is asked; otherwise the owner gets the plain one. */
38
38
  | { readonly action: "ask"; readonly reason: AskReason; readonly confirmed: boolean }
39
39
  | { readonly action: "decide"; readonly choice: string; readonly over: readonly string[] };
40
40
 
41
- /** A choice is cheap to undo when every option touches only the change's own files, on a level where that is safe. */
42
- const isCheapChoice = ({ options = [], default: chosen }: RunReason, { changedPaths, level, undoableLevels }: AskFacts): boolean =>
43
- options.some(({ word }) => word === chosen) && undoableLevels.includes(level) && options.every(({ paths }) => paths.every((path) => changedPaths.includes(path)));
41
+ /** The run's own pick, when the choice is cheap to undo: every option touches only the change's own files, on a level where that is safe. */
42
+ const cheapPick = ({ options = [], default: chosen }: RunReason, { changedPaths, level, undoableLevels }: AskFacts): string | undefined =>
43
+ undoableLevels.includes(level) && options.every(({ paths }) => paths.every((path) => changedPaths.includes(path))) ? options.find(({ word }) => word === chosen)?.word : undefined;
44
44
 
45
- const CONFIRMS: Readonly<Record<AskReason, (reason: RunReason, facts: AskFacts) => boolean>> = {
45
+ const CONFIRMS = {
46
46
  "missing-secret": ({ variable }, { runnerVariables }) => variable !== undefined && !runnerVariables.has(variable),
47
47
  "past-undoing": ({ command }) => command !== undefined,
48
48
  "spends-money": () => true,
49
49
  publishes: () => true,
50
50
  choice: () => false,
51
51
  unsure: () => true,
52
- };
52
+ } as const satisfies Record<AskReason, (reason: RunReason, facts: AskFacts) => boolean>;
53
53
 
54
54
  /** Whether the owner is asked: a reason the facts cannot confirm still asks, and a cheap choice is made without them. */
55
55
  export const askDecision = (reason: RunReason, facts: AskFacts): AskDecision => {
56
- if (reason.kind === "choice" && isCheapChoice(reason, facts)) {
57
- return { action: "decide", choice: reason.default ?? "", over: (reason.options ?? []).map(({ word }) => word) };
58
- }
56
+ const choice = reason.kind === "choice" ? cheapPick(reason, facts) : undefined;
57
+
58
+ if (choice !== undefined) return { action: "decide", choice, over: (reason.options ?? []).map(({ word }) => word) };
59
59
 
60
60
  return { action: "ask", reason: reason.kind, confirmed: CONFIRMS[reason.kind](reason, facts) };
61
61
  };
@@ -86,10 +86,10 @@ const ASKED = {
86
86
  unsure: () => PLAIN_QUESTIONS.unsure,
87
87
  } as const satisfies Record<AskReason, (reason: RunReason) => string>;
88
88
 
89
- export type AskedQuestion = { readonly question: Question; readonly plain: PlainQuestion };
89
+ type AskedQuestion = { readonly question: Question; readonly plain: PlainQuestion };
90
90
 
91
91
  /** The question a run's need becomes. A reason the facts bear out asks its own question with the run's words folded; any other asks in the run's words. */
92
- export const askedQuestion = (reason: RunReason, confirmed: boolean, runsWords: string | undefined): AskedQuestion => {
92
+ export const askedQuestion = ({ reason, confirmed, runsWords }: { readonly reason: RunReason; readonly confirmed: boolean; readonly runsWords: string | undefined }): AskedQuestion => {
93
93
  const kind = confirmed ? reason.kind : "unsure";
94
94
  const options = reason.options?.map(({ word }) => word);
95
95
 
@@ -105,7 +105,7 @@ const SIDE_QUESTIONS: readonly string[] = [PLAIN_QUESTIONS.kind, PLAIN_QUESTIONS
105
105
  export const isWaitQuestion = (text: string): boolean => !SIDE_QUESTIONS.includes(text);
106
106
 
107
107
  /** Why a question text is refused. */
108
- export type QuestionIssue = "too-wide" | "no-question-mark" | "names-item" | "long-word";
108
+ type QuestionIssue = "too-wide" | "no-question-mark" | "names-item" | "long-word";
109
109
 
110
110
  const QUESTION_MARK = "?";
111
111
 
@@ -113,11 +113,14 @@ const words = (text: string): string[] => text.split(/\s+/).filter(Boolean);
113
113
 
114
114
  const cellsOf = (text: string): number => Bun.stringWidth(text);
115
115
 
116
- const WORD_EDGES = /^\W+|\W+$/g;
116
+ const WORD_EDGES = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
117
+
118
+ /** A word without the punctuation around it. */
119
+ export const bareWord = (word: string): string => word.replaceAll(WORD_EDGES, "");
117
120
 
118
121
  /** The question text rules: at most `cells` wide, ends in "?", names no item id, and no word over `wordCells`. */
119
- export const questionIssues = (text: string, item: string, { cells, wordCells }: HumConfig["questionLimits"]): QuestionIssue[] => {
120
- const mentionsItem = words(text).some((word) => word.replaceAll(WORD_EDGES, "") === item);
122
+ export const questionIssues = ({ text, item, limits: { cells, wordCells } }: { readonly text: string; readonly item: string; readonly limits: HumConfig["questionLimits"] }): QuestionIssue[] => {
123
+ const mentionsItem = words(text).some((word) => bareWord(word) === item);
121
124
 
122
125
  return [
123
126
  ...(cellsOf(text) > cells ? (["too-wide"] as const) : []),
@@ -129,7 +132,7 @@ export const questionIssues = (text: string, item: string, { cells, wordCells }:
129
132
 
130
133
  /** A question to put on the thread: the run's own text when it passes the rules, else the plain one with the run's text folded. */
131
134
  export const composeQuestion = (draft: Question, plain: PlainQuestion, item: string, limits: HumConfig["questionLimits"]): Question => {
132
- if (questionIssues(draft.text, item, limits).length === 0) return draft;
135
+ if (questionIssues({ text: draft.text, item, limits }).length === 0) return draft;
133
136
 
134
137
  return { ...draft, text: PLAIN_QUESTIONS[plain], detail: [draft.text, draft.detail].filter(Boolean).join("\n\n") };
135
138
  };
@@ -148,12 +151,12 @@ export type Waiting = {
148
151
  export const questionOrder = (a: Waiting, b: Waiting): number => a.priority - b.priority || b.behind - a.behind || a.since - b.since;
149
152
 
150
153
  /** The priority of an item: the index of its first label in the owner's list, or past the end when it has none. */
151
- export const priorityOf = (labels: readonly string[], priorityLabels: readonly string[]): number => {
154
+ export const priorityOf = ({ labels, priorityLabels }: { readonly labels: readonly string[]; readonly priorityLabels: readonly string[] }): number => {
152
155
  const found = priorityLabels.findIndex((label) => labels.includes(label));
153
156
 
154
157
  return found < 0 ? priorityLabels.length : found;
155
158
  };
156
159
 
157
160
  /** How many more questions the owner can be asked now: the cap less those asked within the last day. No cap leaves no limit. */
158
- export const roomToAsk = (askedAt: readonly number[], cap: number | undefined, now: number): number =>
161
+ export const roomToAsk = ({ askedAt, cap, now }: { readonly askedAt: readonly number[]; readonly cap: number | undefined; readonly now: number }): number =>
159
162
  cap === undefined ? Number.POSITIVE_INFINITY : Math.max(0, cap - askedAt.filter((at) => now - at < DAY_MS).length);
@@ -1,4 +1,3 @@
1
- import type { Item } from "../adapter-api.ts";
2
1
  import type { HumConfig } from "../config/schema.ts";
3
2
  import { DATA_RULE, fenced } from "./prose.ts";
4
3
 
@@ -6,5 +5,8 @@ import { DATA_RULE, fenced } from "./prose.ts";
6
5
  * What a fresh review run reads: the item as the owner asked it and the change's diff. It takes no thread, so the
7
6
  * author's plan, questions and answers never reach the reviewer.
8
7
  */
9
- export const reviewInput = (item: Pick<Item, "id" | "title" | "body">, diff: string, { diffLimit }: Pick<HumConfig, "diffLimit">): string =>
8
+ /** What a prompt quotes of an item: plain text, whatever its id's source. */
9
+ export type ItemText = { readonly id: string; readonly title: string; readonly body: string };
10
+
11
+ export const reviewInput = (item: ItemText, diff: string, { diffLimit }: Pick<HumConfig, "diffLimit">): string =>
10
12
  [`# Item ${item.id}: ${item.title}`, DATA_RULE, fenced("item", item.body.trim()), `## The change`, fenced("diff", diff.slice(0, diffLimit))].join("\n\n");
@@ -1,19 +1,24 @@
1
1
  import { quantile } from "simple-statistics";
2
+ import { z } from "zod";
2
3
  import type { HumConfig, Launch, Level, PathRule } from "../config/schema.ts";
3
4
 
4
5
  /** What only the owner changes: hum's own config, the owner's adapters and the CI workflows. */
5
6
  const OWN_PATHS = [".hum/**", "adapters/**", ".github/workflows/**"] as const;
6
7
 
7
8
  /** What hum reads from a change's diff. */
8
- export type Change = {
9
- readonly paths: readonly string[];
10
- /** Lines added plus lines deleted. */
11
- readonly size: number;
12
- /** An added or removed line matches the project's loosened-check rule. */
13
- readonly loosened: boolean;
14
- /** A changed line in `package.json` or a lockfile names the engine package. */
15
- readonly pinChanged: boolean;
16
- };
9
+ export const Change = z
10
+ .object({
11
+ paths: z.array(z.string().min(1)).readonly(),
12
+ /** Lines added plus lines deleted. */
13
+ size: z.int().nonnegative(),
14
+ /** An added or removed line matches the project's loosened-check rule. */
15
+ loosened: z.boolean(),
16
+ /** A changed line in `package.json` or a lockfile names the engine package. */
17
+ pinChanged: z.boolean(),
18
+ })
19
+ .readonly();
20
+
21
+ export type Change = z.infer<typeof Change>;
17
22
 
18
23
  export const LABELS = ["reverted", "fixed", "clean"] as const;
19
24
 
@@ -76,12 +81,12 @@ export type Placement = {
76
81
  readonly steps: readonly Step[];
77
82
  };
78
83
 
79
- const matches = (glob: string, path: string): boolean =>
84
+ const doesMatch = (glob: string, path: string): boolean =>
80
85
  new Bun.Glob(glob).match(path);
81
86
 
82
87
  const isLaunchOn = (launch: Launch, { now, base }: Moment): boolean =>
83
88
  "base" in launch
84
- ? matches(launch.base, base)
89
+ ? doesMatch(launch.base, base)
85
90
  : Date.parse(launch.from) <= now && now < Date.parse(launch.until);
86
91
 
87
92
  /** Fixed or reverted changes among a path's last `of` merged changes. */
@@ -119,13 +124,16 @@ export const placeChange = (
119
124
  names[Math.min(strictest, rank(name) + 1)] ?? name;
120
125
 
121
126
  const rulesOn = (path: string): readonly PathRule[] =>
122
- policy.paths.filter((rule) => matches(rule.glob, path));
127
+ policy.paths.filter((rule) => doesMatch(rule.glob, path));
123
128
 
124
129
  const isStrict = (path: string): boolean =>
125
- policy.strictPaths.some((glob) => matches(glob, path));
130
+ policy.strictPaths.some((glob) => doesMatch(glob, path));
126
131
 
127
132
  const isOwn = (path: string): boolean =>
128
- [...OWN_PATHS, ...policy.hookPaths].some((glob) => matches(glob, path));
133
+ [...OWN_PATHS, ...policy.hookPaths].some((glob) => doesMatch(glob, path));
134
+
135
+ /** A path no rule places, outside the strict paths and hum's own. */
136
+ const isUnclear = (path: string): boolean => rulesOn(path).length === 0 && !isStrict(path) && !isOwn(path);
129
137
 
130
138
  const touched = [
131
139
  ...new Map(
@@ -162,7 +170,7 @@ export const placeChange = (
162
170
 
163
171
  const launchSteps = policy.launches.flatMap((launch): SetsLevel[] =>
164
172
  isLaunchOn(launch, moment) &&
165
- change.paths.some((path) => matches(launch.glob, path))
173
+ change.paths.some((path) => doesMatch(launch.glob, path))
166
174
  ? [{ step: "launch", glob: launch.glob, level: launch.level }]
167
175
  : [],
168
176
  );
@@ -176,7 +184,7 @@ export const placeChange = (
176
184
  ),
177
185
  ...(change.pinChanged ? [{ step: "engine-pin" } as const] : []),
178
186
  ...change.paths.flatMap((path): Step[] =>
179
- (moment.blocked ?? []).some((glob) => matches(glob, path)) ? [{ step: "blocked-path", path }] : [],
187
+ (moment.blocked ?? []).some((glob) => doesMatch(glob, path)) ? [{ step: "blocked-path", path }] : [],
180
188
  ),
181
189
  ];
182
190
 
@@ -208,9 +216,7 @@ export const placeChange = (
208
216
 
209
217
  return {
210
218
  level,
211
- unclear: change.paths.filter(
212
- (path) => rulesOn(path).length === 0 && !isStrict(path) && !isOwn(path),
213
- ),
219
+ unclear: change.paths.filter(isUnclear),
214
220
  steps: [...ruleSteps, ...launchSteps, ...kindFloorSteps, ...floors, ...bumps],
215
221
  };
216
222
  };