@niwa-labs/pstack 0.0.0-stage → 0.0.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 (163) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +260 -2
  3. package/package.json +28 -4
  4. package/scripts/upstream-map.ts +90 -0
  5. package/src/author.ts +57 -0
  6. package/src/binding.ts +32 -0
  7. package/src/catalog.ts +86 -0
  8. package/src/composition.ts +66 -0
  9. package/src/index.ts +50 -0
  10. package/src/mapping/analyze.ts +223 -0
  11. package/src/mapping/assemble.ts +96 -0
  12. package/src/mapping/diff.ts +139 -0
  13. package/src/mapping/format.ts +67 -0
  14. package/src/mapping/git.ts +69 -0
  15. package/src/mapping/index.ts +18 -0
  16. package/src/mapping/maintain.ts +36 -0
  17. package/src/mapping/schema.ts +50 -0
  18. package/src/mapping/sources.ts +108 -0
  19. package/src/mapping/tool.ts +77 -0
  20. package/src/mapping/verify.ts +130 -0
  21. package/src/plugin.ts +136 -0
  22. package/src/policy.ts +115 -0
  23. package/src/ports.ts +184 -0
  24. package/src/pr-binding.ts +88 -0
  25. package/src/records.ts +61 -0
  26. package/src/roles.ts +49 -0
  27. package/src/trunk.ts +59 -0
  28. package/src/upstream-actions.ts +135 -0
  29. package/src/upstream-records.ts +71 -0
  30. package/src/upstream.ts +151 -0
  31. package/src/workflows/adapted.md +780 -0
  32. package/src/workflows/authoring-a-skill.ts +52 -0
  33. package/src/workflows/autonomous-run.ts +56 -0
  34. package/src/workflows/autopilot-full.ts +90 -0
  35. package/src/workflows/autopilot-stack.ts +125 -0
  36. package/src/workflows/babysit.ts +124 -0
  37. package/src/workflows/benny-reproduce.ts +122 -0
  38. package/src/workflows/benny-triage.ts +89 -0
  39. package/src/workflows/bug-fix.ts +54 -0
  40. package/src/workflows/entry.ts +130 -0
  41. package/src/workflows/eval.ts +63 -0
  42. package/src/workflows/feature.ts +54 -0
  43. package/src/workflows/hillclimb.ts +78 -0
  44. package/src/workflows/investigation.ts +41 -0
  45. package/src/workflows/lib/catalog.ts +45 -0
  46. package/src/workflows/lib/change.ts +70 -0
  47. package/src/workflows/lib/forensics.ts +37 -0
  48. package/src/workflows/lib/git.ts +30 -0
  49. package/src/workflows/lib/go.ts +58 -0
  50. package/src/workflows/lib/inputs.ts +34 -0
  51. package/src/workflows/lib/lane.ts +170 -0
  52. package/src/workflows/lib/measure.ts +34 -0
  53. package/src/workflows/lib/plan.ts +24 -0
  54. package/src/workflows/lib/script.ts +79 -0
  55. package/src/workflows/lib/ship.ts +110 -0
  56. package/src/workflows/lib/texts.ts +18 -0
  57. package/src/workflows/lib/trunk.ts +91 -0
  58. package/src/workflows/multi-phase-plan.ts +83 -0
  59. package/src/workflows/opening-a-pr.ts +62 -0
  60. package/src/workflows/pause-safely.ts +50 -0
  61. package/src/workflows/perf-issue.ts +87 -0
  62. package/src/workflows/prototype.ts +76 -0
  63. package/src/workflows/refactoring.ts +54 -0
  64. package/src/workflows/runtime-forensics.ts +26 -0
  65. package/src/workflows/scenarios.ts +380 -0
  66. package/src/workflows/session-pickup.ts +57 -0
  67. package/src/workflows/shipping.ts +63 -0
  68. package/src/workflows/suite.ts +129 -0
  69. package/src/workflows/texts/authoring-a-skill.json +5 -0
  70. package/src/workflows/texts/autonomous-run.json +5 -0
  71. package/src/workflows/texts/autopilot-full.json +5 -0
  72. package/src/workflows/texts/autopilot-stack.json +5 -0
  73. package/src/workflows/texts/babysit.json +5 -0
  74. package/src/workflows/texts/benny-reproduce.json +5 -0
  75. package/src/workflows/texts/benny-triage.json +5 -0
  76. package/src/workflows/texts/bug-fix.json +5 -0
  77. package/src/workflows/texts/bugbot-triage.json +5 -0
  78. package/src/workflows/texts/eval.json +5 -0
  79. package/src/workflows/texts/feature.json +5 -0
  80. package/src/workflows/texts/hillclimb.json +5 -0
  81. package/src/workflows/texts/investigation.json +5 -0
  82. package/src/workflows/texts/multi-phase-plan.json +5 -0
  83. package/src/workflows/texts/opening-a-pr.json +5 -0
  84. package/src/workflows/texts/pause-safely.json +5 -0
  85. package/src/workflows/texts/perf-issue.json +5 -0
  86. package/src/workflows/texts/prototype.json +5 -0
  87. package/src/workflows/texts/refactoring.json +5 -0
  88. package/src/workflows/texts/runtime-forensics.json +5 -0
  89. package/src/workflows/texts/session-pickup.json +5 -0
  90. package/src/workflows/texts/trace-forensics.json +5 -0
  91. package/src/workflows/texts/visual-parity.json +5 -0
  92. package/src/workflows/texts/worker.json +5 -0
  93. package/src/workflows/trace-forensics.ts +27 -0
  94. package/src/workflows/upstream-sync.ts +182 -0
  95. package/src/workflows/visual-parity.ts +52 -0
  96. package/src/workflows/worktree-cleanup.ts +57 -0
  97. package/test/author.test.ts +61 -0
  98. package/test/benny.test.ts +138 -0
  99. package/test/binding.test.ts +54 -0
  100. package/test/catalog-helpers.test.ts +49 -0
  101. package/test/closure.test.ts +45 -0
  102. package/test/composition.test.ts +23 -0
  103. package/test/eval.test.ts +23 -0
  104. package/test/lanes.test.ts +334 -0
  105. package/test/mapping-diff.test.ts +64 -0
  106. package/test/mapping-support.ts +110 -0
  107. package/test/mapping-texts.test.ts +106 -0
  108. package/test/mapping.test.ts +276 -0
  109. package/test/package-layout.ts +68 -0
  110. package/test/policy.test.ts +98 -0
  111. package/test/ports.test.ts +45 -0
  112. package/test/ports.ts +173 -0
  113. package/test/roles.test.ts +21 -0
  114. package/test/suite.test.ts +167 -0
  115. package/test/support.ts +541 -0
  116. package/test/texts.test.ts +174 -0
  117. package/test/tool.test.ts +48 -0
  118. package/test/trunk-helpers.test.ts +149 -0
  119. package/test/trunk.test.ts +24 -0
  120. package/test/upstream-sync.test.ts +246 -0
  121. package/test/upstream.test.ts +106 -0
  122. package/test/worktree-cleanup.test.ts +107 -0
  123. package/tsconfig.json +7 -0
  124. package/upstream/LICENSE +21 -0
  125. package/upstream/SOURCE.json +5 -0
  126. package/upstream/benny/FOR_AGENTS.md +89 -0
  127. package/upstream/benny/README.md +23 -0
  128. package/upstream/benny/skills/reproduce-and-fix-issues/SKILL.md +310 -0
  129. package/upstream/benny/skills/reproduce-and-fix-issues/references/control-adapter.md +169 -0
  130. package/upstream/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md +205 -0
  131. package/upstream/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md +93 -0
  132. package/upstream/benny/skills/setup-benny/SKILL.md +265 -0
  133. package/upstream/benny/skills/triage-issue-reports/SKILL.md +240 -0
  134. package/upstream/benny/skills/triage-issue-reports/references/routing.example.md +61 -0
  135. package/upstream/benny/templates/configuration.example.yaml +84 -0
  136. package/upstream/benny/templates/reproduce-automation-prompt.md +33 -0
  137. package/upstream/benny/templates/triage-automation-prompt.md +39 -0
  138. package/upstream/mapping.json +699 -0
  139. package/upstream/poteto-mode/SKILL.md +110 -0
  140. package/upstream/poteto-mode/playbooks/authoring-a-skill.md +12 -0
  141. package/upstream/poteto-mode/playbooks/autonomous-run.md +13 -0
  142. package/upstream/poteto-mode/playbooks/autopilot-full.md +25 -0
  143. package/upstream/poteto-mode/playbooks/autopilot-stack.md +8 -0
  144. package/upstream/poteto-mode/playbooks/babysit.md +10 -0
  145. package/upstream/poteto-mode/playbooks/bug-fix.md +15 -0
  146. package/upstream/poteto-mode/playbooks/eval.md +25 -0
  147. package/upstream/poteto-mode/playbooks/feature.md +21 -0
  148. package/upstream/poteto-mode/playbooks/hillclimb.md +21 -0
  149. package/upstream/poteto-mode/playbooks/investigation.md +14 -0
  150. package/upstream/poteto-mode/playbooks/multi-phase-plan.md +11 -0
  151. package/upstream/poteto-mode/playbooks/opening-a-pr.md +9 -0
  152. package/upstream/poteto-mode/playbooks/pause-safely.md +10 -0
  153. package/upstream/poteto-mode/playbooks/perf-issue.md +25 -0
  154. package/upstream/poteto-mode/playbooks/prototype.md +14 -0
  155. package/upstream/poteto-mode/playbooks/refactoring.md +16 -0
  156. package/upstream/poteto-mode/playbooks/runtime-forensics.md +11 -0
  157. package/upstream/poteto-mode/playbooks/session-pickup.md +11 -0
  158. package/upstream/poteto-mode/playbooks/shipping.md +12 -0
  159. package/upstream/poteto-mode/playbooks/trace-forensics.md +14 -0
  160. package/upstream/poteto-mode/playbooks/visual-parity.md +11 -0
  161. package/upstream/poteto-mode/playbooks/worktree-cleanup.md +12 -0
  162. package/upstream/poteto-mode/references/bugbot-triage.md +142 -0
  163. package/upstream/poteto-mode/worker.md +11 -0
@@ -0,0 +1,66 @@
1
+ /**
2
+ * pstack's composition: the plugins a host installs to run its playbooks, in the order it installs them.
3
+ *
4
+ * The playbooks are built on forge (pull requests, pipelines, merges), evidence (verdicts and the merge result of a
5
+ * pair of commits), watch (agents that went silent or loop) and plan (the plan a go is given on); pstack itself comes
6
+ * last. What pstack needs of the host besides is not its to install: the sessions and git modules before it, the
7
+ * workflow module after it, and the binding by which a session attests under one address for its whole life.
8
+ *
9
+ * ```ts
10
+ * const base = defaultComposition({ home, harnesses, agents });
11
+ * const beforeWorkflow = base.filter((part) => part.name !== "workflow");
12
+ * const workflow = base.filter((part) => part.name === "workflow");
13
+ * export default [...beforeWorkflow, ...pstack({ bind: addressingOf(base), forge: { servers }, roles }), ...workflow];
14
+ * ```
15
+ */
16
+
17
+ import { evidence } from "@niwa-labs/evidence";
18
+ import { forge } from "@niwa-labs/forge";
19
+ import type { ForgeOptions } from "@niwa-labs/forge";
20
+ import { plan } from "@niwa-labs/plan";
21
+ import type { CallerBinding, Plugin } from "@niwa-labs/plugin";
22
+ import { watch } from "@niwa-labs/watch";
23
+ import type { WatchOptions } from "@niwa-labs/watch";
24
+
25
+ import { pstackPlugin } from "./plugin.ts";
26
+ import type { PstackOptions } from "./plugin.ts";
27
+
28
+ /** What pstack's composition is made with: pstack's own options, the forge's, and the host's binding. */
29
+ export interface PstackCompositionOptions extends Omit<PstackOptions, "forges"> {
30
+ /** The binding evidence attests with: `addressingOf(plugins)` of the host's sessions and agents modules. */
31
+ readonly bind: CallerBinding;
32
+ /** The forges whose hosts an author's box can add when the caller's grant allows them. */
33
+ readonly forge: ForgeOptions;
34
+ readonly watch?: WatchOptions;
35
+ }
36
+
37
+ /** What pstack needs of the host besides the plugins of its composition. */
38
+ export const PSTACK_NEEDS = {
39
+ /** The binding by which a session attests under one address: the one evidence is given. */
40
+ addressing: "the caller binding of the sessions and agents modules",
41
+ /** The sessions module, before pstack: the workflow SDK starts the boxed sessions through it. */
42
+ sessions: "@niwa-labs/sessions",
43
+ /** The git module, before pstack: the worktrees the lanes work in. */
44
+ git: "@niwa-labs/git",
45
+ /** The workflow module, after pstack: the entry, the playbooks and the suite are its built-ins. */
46
+ workflow: "@niwa-labs/workflow",
47
+ /** With `benny`: plugins of the owner's that offer his three ports, before pstack (`benny.ports`, or installed by the host). */
48
+ bennyPorts: "plugins that offer the issue tracker, report channel and product control ports of Benny",
49
+ } as const;
50
+
51
+ /** pstack's plugins, to install after the sessions and git modules and before the workflow module. */
52
+ export function pstack(options: PstackCompositionOptions): Plugin[] {
53
+ if (typeof options.bind !== "function") {
54
+ throw new TypeError("pstack: it needs the caller binding of the host (addressingOf), so a verdict's author keeps one address");
55
+ }
56
+ const { bind, forge: forgeOptions, watch: watchOptions, ...own } = options;
57
+ return [
58
+ forge(forgeOptions),
59
+ evidence({ bind }),
60
+ watch(watchOptions ?? {}),
61
+ plan(),
62
+ // The plugins that provide Benny's ports come before pstack, which reads what they offer when it is installed.
63
+ ...(own.benny?.ports ?? []),
64
+ pstackPlugin({ ...own, forges: forgeOptions.servers.map((server) => server.host) }),
65
+ ];
66
+ }
package/src/index.ts ADDED
@@ -0,0 +1,50 @@
1
+ /**
2
+ * pstack: delivery playbooks run as niwa's built-in workflows. The entry routes a request to the playbook it needs;
3
+ * the suite tries every new version of them on scenarios before the host runs it.
4
+ */
5
+
6
+ export { PSTACK_NEEDS, pstack } from "./composition.ts";
7
+ export type { PstackCompositionOptions } from "./composition.ts";
8
+ export { addressingOf } from "./binding.ts";
9
+ export type { Binding } from "./binding.ts";
10
+ export { AuthorRefusal, authorLaunch } from "./author.ts";
11
+ export type { AuthorRefusalCode } from "./author.ts";
12
+ export { BENNY, ENTRY, GATED, PLAYBOOKS, SUITE, SUITE_BUILTIN, SYNC, SYNC_BUILTIN, UNGATED, gatedOf, scriptOf } from "./catalog.ts";
13
+ export type { Builtin } from "./catalog.ts";
14
+ export {
15
+ BENNY_CHANNEL,
16
+ BENNY_CONTROL,
17
+ BENNY_PORTS,
18
+ BENNY_TRACKER,
19
+ CHANNEL_ACTIONS,
20
+ CONTROL_ACTIONS,
21
+ TRACKER_ACTIONS,
22
+ TrackerIssue,
23
+ bennyChannelNotify,
24
+ bennyChannelReply,
25
+ bennyControlBringUp,
26
+ bennyControlCapabilities,
27
+ bennyControlCleanup,
28
+ bennyControlDrive,
29
+ bennyControlInspect,
30
+ bennyControlRecord,
31
+ bennyControlScreenshot,
32
+ bennyTrackerComment,
33
+ bennyTrackerCreate,
34
+ bennyTrackerFind,
35
+ bennyTrackerLinkPr,
36
+ } from "./ports.ts";
37
+ export type { PortOffer } from "./ports.ts";
38
+ export { pstackPlugin } from "./plugin.ts";
39
+ export type { BennyOptions, PstackOptions } from "./plugin.ts";
40
+ export { BennyReported, SessionAddress, bennyReport, pstackAuthorOptions, pstackRoles } from "./records.ts";
41
+ export { GO, VERDICTS, decide, goCovers, goDigest, goSubject, mayGiveGo, mergeRequirements } from "./policy.ts";
42
+ export type { Found, MergeSubject, PlanRevision, Required } from "./policy.ts";
43
+ export { isLockfile, isManifest, trunkKind } from "./trunk.ts";
44
+ export type { TrunkFacts, TrunkKind } from "./trunk.ts";
45
+ export { AuthorRole, Roles, SeatRole } from "./roles.ts";
46
+ export type { RolesInput } from "./roles.ts";
47
+ export { refreshUpstream, playbookNames } from "./upstream.ts";
48
+ export type { UpstreamSource } from "./upstream.ts";
49
+ export { accept, advance, analyze, assemble, formatMapping, formatReport, parseMapping } from "./mapping/index.ts";
50
+ export type { AssembledText, Mapping, Report } from "./mapping/index.ts";
@@ -0,0 +1,223 @@
1
+ /**
2
+ * What the mapping says now, measured and not judged: whether it is consistent, how much of the upstream text it
3
+ * covers, and what became of each entry's ranges since the commits they were recorded at.
4
+ *
5
+ * Every range is followed from its recorded commit to the current one, on each side: the upstream side from the
6
+ * commit it was recorded at to the commit of the snapshot, our side from the commit it was recorded at to the head
7
+ * of this repository. The carried upstream ranges are what coverage counts. Nothing here concludes anything: a
8
+ * touched range comes with its old and new text, and what it means is for the reader to say.
9
+ */
10
+
11
+ import { carry, diffText } from "./diff.ts";
12
+ import type { Segment, Span } from "./diff.ts";
13
+ import type { Entry, Mapping, Ref } from "./schema.ts";
14
+ import type { Texts, UpstreamTexts } from "./sources.ts";
15
+
16
+ /** Something the mapping gets wrong about itself. */
17
+ export interface Problem {
18
+ readonly entry?: string;
19
+ readonly message: string;
20
+ }
21
+
22
+ /** What became of one range. */
23
+ export interface Moved {
24
+ readonly status: "unchanged" | "touched" | "gone";
25
+ readonly from: Ref;
26
+ /** Where the range is now; absent when it is gone. */
27
+ readonly to?: Ref;
28
+ /** The text of a touched range as it was recorded, and as it reads now. */
29
+ readonly old?: string;
30
+ readonly new?: string;
31
+ }
32
+
33
+ /** What became of one entry: the worst of its sides. */
34
+ export interface EntryMove {
35
+ readonly id: string;
36
+ readonly kind: Entry["kind"];
37
+ readonly status: "unchanged" | "touched" | "gone";
38
+ readonly upstream: Moved;
39
+ readonly ours: readonly Moved[];
40
+ readonly note?: string;
41
+ }
42
+
43
+ /** A run of upstream characters no entry covers. */
44
+ export interface Uncovered {
45
+ readonly start: number;
46
+ readonly end: number;
47
+ readonly text: string;
48
+ /** Whether the text is not in upstream at the oldest commit the mapping was recorded at. */
49
+ readonly added: boolean;
50
+ }
51
+
52
+ /** How much of one upstream file the entries cover. */
53
+ export interface FileCoverage {
54
+ readonly file: string;
55
+ readonly size: number;
56
+ readonly covered: number;
57
+ readonly percent: number;
58
+ readonly uncovered: readonly Uncovered[];
59
+ }
60
+
61
+ /** The measurement. */
62
+ export interface Report {
63
+ readonly upstream: { readonly commit: string };
64
+ readonly ours: { readonly head: string };
65
+ readonly problems: readonly Problem[];
66
+ /** What is wrong with the texts the scripts import, held to the map: measured apart, for they follow the map and lag it. */
67
+ readonly texts: readonly Problem[];
68
+ readonly coverage: { readonly size: number; readonly covered: number; readonly percent: number; readonly files: readonly FileCoverage[] };
69
+ readonly entries: readonly EntryMove[];
70
+ /** The entries that are not unchanged. */
71
+ readonly unresolved: number;
72
+ }
73
+
74
+ const percentOf = (part: number, whole: number): number => (whole === 0 ? 100 : (part / whole) * 100);
75
+
76
+ /** The problems of the mapping in itself: its entries, and its ranges at the commits they were recorded at. */
77
+ function validate(mapping: Mapping, upstream: UpstreamTexts, ours: Texts): { problems: Problem[]; sound: Set<string> } {
78
+ const problems: Problem[] = [];
79
+ const bad = new Set<string>();
80
+ const complain = (entry: Entry, message: string): void => {
81
+ problems.push({ entry: entry.id, message });
82
+ bad.add(entry.id);
83
+ };
84
+ const seen = new Set<string>();
85
+ const inside = (entry: Entry, side: string, ref: Ref, texts: Texts): void => {
86
+ const text = texts.at(ref.commit, ref.file);
87
+ if (text === undefined) complain(entry, `${side} file ${ref.file} does not exist at ${ref.commit}`);
88
+ else if (ref.range[1] > text.length) complain(entry, `${side} range [${ref.range.join(", ")}) is outside ${ref.file} at ${ref.commit}, which has ${String(text.length)} characters`);
89
+ };
90
+ const scope = new Set(upstream.files());
91
+ for (const entry of mapping.entries) {
92
+ if (seen.has(entry.id)) complain(entry, "the id is used by another entry");
93
+ seen.add(entry.id);
94
+ if (entry.kind === "dropped") {
95
+ if (entry.note === undefined) complain(entry, "a dropped entry says why in its note");
96
+ if (entry.ours.length > 0) complain(entry, "a dropped entry has no range of ours");
97
+ } else if (entry.ours.length === 0) complain(entry, `a ${entry.kind} entry links to the ranges of ours that carry it`);
98
+ if (upstream.same(entry.upstream.commit, upstream.current) && !scope.has(entry.upstream.file)) complain(entry, `${entry.upstream.file} is not an upstream file of the snapshot`);
99
+ else inside(entry, "upstream", entry.upstream, upstream);
100
+ for (const link of entry.ours) inside(entry, "our", link, ours);
101
+ }
102
+ // Upstream ranges recorded at one commit of one file must not overlap: a character belongs to one entry.
103
+ const groups = new Map<string, Array<{ entry: Entry; range: Span }>>();
104
+ for (const entry of mapping.entries) {
105
+ if (bad.has(entry.id)) continue;
106
+ const key = `${upstream.same(entry.upstream.commit, upstream.current) ? upstream.current : entry.upstream.commit}\0${entry.upstream.file}`;
107
+ groups.set(key, [...(groups.get(key) ?? []), { entry, range: entry.upstream.range }]);
108
+ }
109
+ for (const group of groups.values()) {
110
+ const sorted = [...group].sort((a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1]);
111
+ let reach = sorted[0];
112
+ for (const next of sorted.slice(1)) {
113
+ if (reach !== undefined && next.range[0] < reach.range[1]) {
114
+ problems.push({ entry: next.entry.id, message: `the upstream range overlaps the one of ${reach.entry.id}` });
115
+ bad.add(next.entry.id);
116
+ }
117
+ if (reach === undefined || next.range[1] > reach.range[1]) reach = next;
118
+ }
119
+ }
120
+ return { problems, sound: new Set(mapping.entries.map((one) => one.id).filter((id) => !bad.has(id))) };
121
+ }
122
+
123
+ /** Follows ranges from the commits they were recorded at to the current one, side by side. */
124
+ class Mover {
125
+ private readonly moves = new Map<string, Map<string, string | null>>();
126
+ private readonly segments = new Map<string, Segment[]>();
127
+
128
+ constructor(private readonly texts: Texts) {}
129
+
130
+ /** The segments from a file at a commit to its current path, or null when the file is gone. */
131
+ diff(commit: string, file: string): { file: string; segments: Segment[] } | null {
132
+ if (!this.moves.has(commit)) this.moves.set(commit, this.texts.moved(commit));
133
+ const moved = this.moves.get(commit) as Map<string, string | null>;
134
+ const now = moved.has(file) ? (moved.get(file) as string | null) : file;
135
+ if (now === null) return null;
136
+ const key = `${commit}\0${file}\0${now}`;
137
+ if (!this.segments.has(key)) {
138
+ const before = this.texts.at(commit, file);
139
+ const after = this.texts.at(this.texts.current, now);
140
+ if (before === undefined || after === undefined) return null;
141
+ this.segments.set(key, diffText(before, after));
142
+ }
143
+ return { file: now, segments: this.segments.get(key) as Segment[] };
144
+ }
145
+
146
+ /** What became of one range. */
147
+ move(ref: Ref): Moved {
148
+ if (this.texts.same(ref.commit, this.texts.current)) return { status: "unchanged", from: ref, to: ref };
149
+ const found = this.diff(ref.commit, ref.file);
150
+ if (found === null) return { status: "gone", from: ref };
151
+ const carried = carry(found.segments, ref.range);
152
+ if (carried.status === "gone") return { status: "gone", from: ref };
153
+ const to: Ref = { commit: this.texts.current, file: found.file, range: [carried.range[0], carried.range[1]] };
154
+ if (carried.status === "unchanged") return { status: "unchanged", from: ref, to };
155
+ const before = this.texts.at(ref.commit, ref.file) as string;
156
+ const after = this.texts.at(this.texts.current, found.file) as string;
157
+ return { status: "touched", from: ref, to, old: before.slice(...ref.range), new: after.slice(...carried.range) };
158
+ }
159
+ }
160
+
161
+ /** The worst status of a set of sides. */
162
+ function worst(upstream: Moved, ours: readonly Moved[]): EntryMove["status"] {
163
+ if (upstream.status === "gone" || (ours.length > 0 && ours.every((one) => one.status === "gone"))) return "gone";
164
+ return upstream.status === "unchanged" && ours.every((one) => one.status === "unchanged") ? "unchanged" : "touched";
165
+ }
166
+
167
+ /** The runs of characters of a text outside a set of ranges. */
168
+ function gaps(size: number, ranges: readonly Span[]): Span[] {
169
+ const found: Span[] = [];
170
+ let at = 0;
171
+ for (const [start, end] of [...ranges].sort((a, b) => a[0] - b[0])) {
172
+ if (start > at) found.push([at, start]);
173
+ at = Math.max(at, end);
174
+ }
175
+ if (at < size) found.push([at, size]);
176
+ return found;
177
+ }
178
+
179
+ /** Measure the mapping against the snapshot and this repository. */
180
+ export function analyze(mapping: Mapping, upstream: UpstreamTexts, ours: Texts): Report {
181
+ const { problems, sound } = validate(mapping, upstream, ours);
182
+ const upstreamMover = new Mover(upstream);
183
+ const oursMover = new Mover(ours);
184
+ const entries: EntryMove[] = [];
185
+ for (const entry of mapping.entries) {
186
+ if (!sound.has(entry.id)) continue;
187
+ const up = upstreamMover.move(entry.upstream);
188
+ const ourSides = entry.ours.map((link) => oursMover.move(link));
189
+ entries.push({ id: entry.id, kind: entry.kind, status: worst(up, ourSides), upstream: up, ours: ourSides, ...(entry.note === undefined ? {} : { note: entry.note }) });
190
+ }
191
+
192
+ // The commits older than the snapshot that the mapping was recorded at: text not in them is new.
193
+ const older = [...new Set(mapping.entries.map((one) => one.upstream.commit))].filter((commit) => !upstream.same(commit, upstream.current));
194
+ const files: FileCoverage[] = [];
195
+ for (const file of upstream.files()) {
196
+ const text = upstream.at(upstream.current, file) as string;
197
+ const ranges = entries.flatMap((one) => (one.upstream.to?.file === file ? [one.upstream.to.range] : []));
198
+ const runs = gaps(text.length, ranges);
199
+ const uncovered = runs.map(([start, end]): Uncovered => {
200
+ const added =
201
+ older.length > 0 &&
202
+ older.every((commit) => {
203
+ if (upstream.at(commit, file) === undefined) return true;
204
+ const found = upstreamMover.diff(commit, file);
205
+ return found === null || !found.segments.some((one) => one.same && one.newStart < end && start < one.newEnd);
206
+ });
207
+ return { start, end, text: text.slice(start, end), added };
208
+ });
209
+ const missing = uncovered.reduce((sum, one) => sum + (one.end - one.start), 0);
210
+ files.push({ file, size: text.length, covered: text.length - missing, percent: percentOf(text.length - missing, text.length), uncovered });
211
+ }
212
+ const size = files.reduce((sum, one) => sum + one.size, 0);
213
+ const covered = files.reduce((sum, one) => sum + one.covered, 0);
214
+ return {
215
+ upstream: { commit: upstream.current },
216
+ ours: { head: ours.current },
217
+ problems,
218
+ texts: [],
219
+ coverage: { size, covered, percent: percentOf(covered, size), files },
220
+ entries,
221
+ unresolved: entries.filter((one) => one.status !== "unchanged").length,
222
+ };
223
+ }
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The texts the scripts give their sessions, assembled from the mapping: the blocks of an upstream file that are
3
+ * `prompt` verbatim from the snapshot, those that are `adapted` from our text they link to, in the order they have
4
+ * upstream; `code` and `dropped` blocks are not in a prompt. A text is the files it is made of, one after the other.
5
+ */
6
+
7
+ import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+
10
+ import { playbookNames } from "../upstream.ts";
11
+ import type { Mapping } from "./schema.ts";
12
+ import type { Texts, UpstreamTexts } from "./sources.ts";
13
+
14
+ /** One text a script imports: a playbook, the worker rules, a reference, or an automation of Benny. */
15
+ export interface AssembledText {
16
+ /** The name of its file without `.json`: `bug-fix`. */
17
+ readonly name: string;
18
+ /** The heading of the text: `Bug fix`. */
19
+ readonly title: string;
20
+ /** The whole text. */
21
+ readonly text: string;
22
+ }
23
+
24
+ /** The title of a text: its first heading, without the marks. */
25
+ export function titleOf(text: string, fallback: string): string {
26
+ const heading = text.split("\n").find((line) => /^#{1,6}\s/.test(line));
27
+ return heading === undefined ? fallback : heading.replace(/^#{1,6}\s+/, "").trim();
28
+ }
29
+
30
+ /** What a text is made of: the upstream files, in order. */
31
+ interface TextSpec {
32
+ readonly name: string;
33
+ readonly title?: string;
34
+ readonly files: readonly string[];
35
+ }
36
+
37
+ const SKILLS = "benny/skills";
38
+
39
+ /** The texts there are: every playbook, the worker rules, the Bugbot reference, and Benny's two automations. */
40
+ export function textSpecs(snapshot: string): TextSpec[] {
41
+ return [
42
+ ...playbookNames(snapshot).map((name) => ({ name, files: [`poteto-mode/playbooks/${name}.md`] })),
43
+ { name: "worker", title: "Worker rules", files: ["poteto-mode/worker.md", "poteto-mode/SKILL.md"] },
44
+ { name: "bugbot-triage", files: ["poteto-mode/references/bugbot-triage.md"] },
45
+ { name: "benny-triage", files: [`${SKILLS}/triage-issue-reports/SKILL.md`] },
46
+ {
47
+ name: "benny-reproduce",
48
+ files: [`${SKILLS}/reproduce-and-fix-issues/SKILL.md`, `${SKILLS}/reproduce-and-fix-issues/references/verify-existing-fix.md`, `${SKILLS}/reproduce-and-fix-issues/references/control-adapter.md`],
49
+ },
50
+ ];
51
+ }
52
+
53
+ /** Assemble the text of one upstream file from its entries. */
54
+ function pieceOf(mapping: Mapping, upstream: UpstreamTexts, ours: Texts, file: string): string {
55
+ const text = upstream.at(upstream.current, file);
56
+ if (text === undefined) return "";
57
+ const entries = mapping.entries.filter((one) => one.upstream.file === file).sort((a, b) => a.upstream.range[0] - b.upstream.range[0]);
58
+ let out = "";
59
+ for (const entry of entries) {
60
+ if (!upstream.same(entry.upstream.commit, upstream.current)) {
61
+ throw new Error(`${entry.id} is recorded at upstream commit ${entry.upstream.commit}, the snapshot is at ${upstream.current}: carry the entry to the snapshot before assembling`);
62
+ }
63
+ if (entry.kind === "prompt") out += text.slice(...entry.upstream.range);
64
+ else if (entry.kind === "adapted") {
65
+ for (const link of entry.ours) {
66
+ const ourText = ours.at(link.commit, link.file);
67
+ if (ourText === undefined) throw new Error(`${entry.id} links to ${link.file}, which does not exist at ${link.commit}`);
68
+ out += ourText.slice(...link.range);
69
+ }
70
+ }
71
+ }
72
+ return out;
73
+ }
74
+
75
+ /** The texts of the mapping, in the order of `textSpecs`; one that no block of the mapping puts in a prompt has none. */
76
+ export function assemble(mapping: Mapping, upstream: UpstreamTexts, ours: Texts): AssembledText[] {
77
+ const made: AssembledText[] = [];
78
+ for (const spec of textSpecs(upstream.snapshot)) {
79
+ const pieces = spec.files.map((file) => pieceOf(mapping, upstream, ours, file)).filter((piece) => piece !== "");
80
+ if (pieces.length === 0) continue;
81
+ const text = pieces.map((piece, index) => (index < pieces.length - 1 ? `${piece.replace(/\s+$/, "")}\n\n` : piece)).join("");
82
+ made.push({ name: spec.name, title: spec.title ?? titleOf(text, spec.name), text });
83
+ }
84
+ return made;
85
+ }
86
+
87
+ /** The JSON file of a text, as the scripts import it. */
88
+ export const jsonOf = (one: AssembledText): string => `${JSON.stringify(one, null, 2)}\n`;
89
+
90
+ /** Write the texts as the JSON files the scripts import, and remove the ones that are no longer a text. */
91
+ export function writeTexts(texts: readonly AssembledText[], dir: string): void {
92
+ mkdirSync(dir, { recursive: true });
93
+ const names = new Set(texts.map((one) => `${one.name}.json`));
94
+ for (const file of readdirSync(dir)) if (file.endsWith(".json") && !names.has(file)) rmSync(join(dir, file));
95
+ for (const one of texts) writeFileSync(join(dir, `${one.name}.json`), jsonOf(one));
96
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * What happened to a range of characters when a text changed.
3
+ *
4
+ * The two texts are compared by lines, and inside each block of lines that differs by the characters the old and the
5
+ * new block share at their start and at their end. What is left between is the change. A range that lies wholly in
6
+ * the text the two share is unchanged: it only shifted. A range with a change inside it, or at its edge, is touched,
7
+ * and it follows the change to the new text. A range whose characters are all removed is gone. Offsets are positions
8
+ * in the string, UTF-16 code units, as `String.prototype.slice` counts them.
9
+ */
10
+
11
+ /** A start and an end offset: the characters from start up to, not including, end. */
12
+ export type Span = readonly [start: number, end: number];
13
+
14
+ /** One stretch of the old text and the stretch of the new text that stands for it. */
15
+ export interface Segment {
16
+ readonly oldStart: number;
17
+ readonly oldEnd: number;
18
+ readonly newStart: number;
19
+ readonly newEnd: number;
20
+ /** Whether both stretches are the same text. */
21
+ readonly same: boolean;
22
+ }
23
+
24
+ /** What happened to a range. */
25
+ export type Carried = { readonly status: "unchanged"; readonly range: Span } | { readonly status: "touched"; readonly range: Span } | { readonly status: "gone" };
26
+
27
+ /** Beyond this many line pairs the lines are not compared one by one: the whole text counts as changed. */
28
+ const MAX_PAIRS = 16_000_000;
29
+
30
+ /** The lines of a text, each with its newline, and the offset each starts at. */
31
+ function linesOf(text: string): { lines: string[]; starts: number[] } {
32
+ const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
33
+ const starts: number[] = [];
34
+ let at = 0;
35
+ for (const line of lines) {
36
+ starts.push(at);
37
+ at += line.length;
38
+ }
39
+ starts.push(at);
40
+ return { lines, starts };
41
+ }
42
+
43
+ /** The pairs of equal lines of a longest common subsequence of two line lists, as indexes. */
44
+ function commonLines(a: readonly string[], b: readonly string[]): Array<[number, number]> {
45
+ let head = 0;
46
+ while (head < a.length && head < b.length && a[head] === b[head]) head += 1;
47
+ let tail = 0;
48
+ while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail += 1;
49
+ const pairs: Array<[number, number]> = [];
50
+ for (let i = 0; i < head; i += 1) pairs.push([i, i]);
51
+ const n = a.length - head - tail;
52
+ const m = b.length - head - tail;
53
+ if (n > 0 && m > 0 && n * m <= MAX_PAIRS) {
54
+ // table[i][j]: the length of the longest common subsequence of the middle of a from i and of b from j.
55
+ const width = m + 1;
56
+ const table = new Uint32Array((n + 1) * width);
57
+ for (let i = n - 1; i >= 0; i -= 1) {
58
+ for (let j = m - 1; j >= 0; j -= 1) {
59
+ table[i * width + j] = a[head + i] === b[head + j] ? (table[(i + 1) * width + j + 1] as number) + 1 : Math.max(table[(i + 1) * width + j] as number, table[i * width + j + 1] as number);
60
+ }
61
+ }
62
+ let i = 0;
63
+ let j = 0;
64
+ while (i < n && j < m) {
65
+ if (a[head + i] === b[head + j]) {
66
+ pairs.push([head + i, head + j]);
67
+ i += 1;
68
+ j += 1;
69
+ } else if ((table[(i + 1) * width + j] as number) >= (table[i * width + j + 1] as number)) i += 1;
70
+ else j += 1;
71
+ }
72
+ }
73
+ for (let i = 0; i < tail; i += 1) pairs.push([a.length - tail + i, b.length - tail + i]);
74
+ return pairs;
75
+ }
76
+
77
+ /** Add a segment, joining it to the one before when both are the same text. */
78
+ function push(into: Segment[], next: Segment): void {
79
+ if (next.oldStart === next.oldEnd && next.newStart === next.newEnd) return;
80
+ const last = into.at(-1);
81
+ if (last !== undefined && last.same && next.same) into[into.length - 1] = { ...last, oldEnd: next.oldEnd, newEnd: next.newEnd };
82
+ else into.push(next);
83
+ }
84
+
85
+ /** Compare two texts: segments that cover both, in order, the same text and the changed text between. */
86
+ export function diffText(before: string, after: string): Segment[] {
87
+ const segments: Segment[] = [];
88
+ if (before === after) {
89
+ push(segments, { oldStart: 0, oldEnd: before.length, newStart: 0, newEnd: after.length, same: true });
90
+ return segments;
91
+ }
92
+ const a = linesOf(before);
93
+ const b = linesOf(after);
94
+ const pairs = commonLines(a.lines, b.lines);
95
+ // Changed blocks of lines sit between the pairs of equal ones.
96
+ let oldAt = 0;
97
+ let newAt = 0;
98
+ const changed = (oldTo: number, newTo: number): void => {
99
+ const oldStart = a.starts[oldAt] as number;
100
+ const oldEnd = a.starts[oldTo] as number;
101
+ const newStart = b.starts[newAt] as number;
102
+ const newEnd = b.starts[newTo] as number;
103
+ if (oldStart === oldEnd && newStart === newEnd) return;
104
+ const from = before.slice(oldStart, oldEnd);
105
+ const to = after.slice(newStart, newEnd);
106
+ let head = 0;
107
+ while (head < from.length && head < to.length && from[head] === to[head]) head += 1;
108
+ let tail = 0;
109
+ while (tail < from.length - head && tail < to.length - head && from[from.length - 1 - tail] === to[to.length - 1 - tail]) tail += 1;
110
+ push(segments, { oldStart, oldEnd: oldStart + head, newStart, newEnd: newStart + head, same: true });
111
+ push(segments, { oldStart: oldStart + head, oldEnd: oldEnd - tail, newStart: newStart + head, newEnd: newEnd - tail, same: false });
112
+ push(segments, { oldStart: oldEnd - tail, oldEnd, newStart: newEnd - tail, newEnd, same: true });
113
+ };
114
+ for (const [i, j] of pairs) {
115
+ changed(i, j);
116
+ push(segments, { oldStart: a.starts[i] as number, oldEnd: a.starts[i + 1] as number, newStart: b.starts[j] as number, newEnd: b.starts[j + 1] as number, same: true });
117
+ oldAt = i + 1;
118
+ newAt = j + 1;
119
+ }
120
+ changed(a.lines.length, b.lines.length);
121
+ return segments;
122
+ }
123
+
124
+ /** The segment that holds the old character at an offset. */
125
+ function holding(segments: readonly Segment[], offset: number): Segment | undefined {
126
+ return segments.find((one) => one.oldStart <= offset && offset < one.oldEnd);
127
+ }
128
+
129
+ /** Follow a range of the old text into the new one. */
130
+ export function carry(segments: readonly Segment[], range: Span): Carried {
131
+ const [start, end] = range;
132
+ const first = holding(segments, start);
133
+ const last = holding(segments, end - 1);
134
+ if (first === undefined || last === undefined) return { status: "gone" };
135
+ if (first === last && first.same) return { status: "unchanged", range: [first.newStart + (start - first.oldStart), first.newStart + (end - first.oldStart)] };
136
+ const newStart = first.same ? first.newStart + (start - first.oldStart) : first.newStart;
137
+ const newEnd = last.same ? last.newStart + (end - last.oldStart) : last.newEnd;
138
+ return newStart >= newEnd ? { status: "gone" } : { status: "touched", range: [newStart, newEnd] };
139
+ }
@@ -0,0 +1,67 @@
1
+ /** The measurement as text for a reader. The JSON form of a report is the report itself. */
2
+
3
+ import type { Moved, Report } from "./analyze.ts";
4
+
5
+ const pct = (value: number): string => `${value.toFixed(2)}%`;
6
+ const span = (ref: { file: string; range: readonly [number, number] }): string => `${ref.file} [${String(ref.range[0])}, ${String(ref.range[1])})`;
7
+ const quote = (text: string, limit: number): string => {
8
+ const flat = text.replace(/\s+/g, " ").trim();
9
+ return JSON.stringify(flat.length > limit ? `${flat.slice(0, limit)}...` : flat);
10
+ };
11
+
12
+ function side(label: string, moved: Moved, limit: number): string[] {
13
+ const where = moved.to === undefined ? `${span(moved.from)} -> gone` : `${span(moved.from)} -> ${span(moved.to)}`;
14
+ const lines = [` ${label}: ${moved.status}: ${where}`];
15
+ if (moved.status === "touched") lines.push(` old: ${quote(moved.old ?? "", limit)}`, ` new: ${quote(moved.new ?? "", limit)}`);
16
+ return lines;
17
+ }
18
+
19
+ /** The report as lines: coverage per file, the uncovered ranges, and the entries that are not unchanged. */
20
+ export function formatReport(report: Report, opts: { limit?: number } = {}): string {
21
+ const limit = opts.limit ?? 240;
22
+ const out: string[] = [`upstream snapshot ${report.upstream.commit}`, `ours head ${report.ours.head}`, ""];
23
+ if (report.problems.length > 0) {
24
+ out.push(`PROBLEMS ${String(report.problems.length)}`);
25
+ for (const one of report.problems) out.push(` ${one.entry === undefined ? "" : `${one.entry}: `}${one.message}`);
26
+ out.push("");
27
+ }
28
+ if (report.texts.length > 0) {
29
+ out.push(`TEXT PROBLEMS ${String(report.texts.length)}`);
30
+ for (const one of report.texts) out.push(` ${one.entry === undefined ? "" : `${one.entry}: `}${one.message}`);
31
+ out.push("");
32
+ }
33
+ out.push(`COVERAGE ${pct(report.coverage.percent)} (${String(report.coverage.covered)} of ${String(report.coverage.size)} characters)`);
34
+ for (const file of report.coverage.files) out.push(` ${pct(file.percent).padStart(8)} ${String(file.covered).padStart(6)}/${String(file.size).padEnd(6)} ${file.file}`);
35
+ const uncovered = report.coverage.files.flatMap((file) => file.uncovered.map((one) => ({ file: file.file, ...one })));
36
+ out.push("", `UNCOVERED ${String(uncovered.length)} ranges`);
37
+ for (const one of uncovered) out.push(` ${one.file} [${String(one.start)}, ${String(one.end)}) ${String(one.end - one.start)} characters${one.added ? " added" : ""}: ${quote(one.text, limit)}`);
38
+ const count = (status: string): number => report.entries.filter((one) => one.status === status).length;
39
+ out.push("", `ENTRIES ${String(report.entries.length)}: ${String(count("unchanged"))} unchanged, ${String(count("touched"))} touched, ${String(count("gone"))} gone`);
40
+ for (const entry of report.entries.filter((one) => one.status !== "unchanged")) {
41
+ out.push(` ${entry.status} ${entry.id} (${entry.kind})${entry.note === undefined ? "" : `: ${entry.note}`}`);
42
+ out.push(...side("upstream", entry.upstream, limit));
43
+ for (const one of entry.ours) out.push(...side("ours", one, limit));
44
+ }
45
+ return `${out.join("\n")}\n`;
46
+ }
47
+
48
+ /** The numbers of a report, for a caller that reads them: coverage, and what is not settled. One short line: the per-file coverage is in the report. */
49
+ export function summaryOf(report: Report): { problems: number; textProblems: number; coverage: number; entries: number; unchanged: number; touched: number; gone: number; uncovered: number } {
50
+ const count = (status: string): number => report.entries.filter((one) => one.status === status).length;
51
+ return {
52
+ problems: report.problems.length,
53
+ textProblems: report.texts.length,
54
+ coverage: report.coverage.percent,
55
+ entries: report.entries.length,
56
+ unchanged: count("unchanged"),
57
+ touched: count("touched"),
58
+ gone: count("gone"),
59
+ uncovered: report.coverage.files.reduce((sum, one) => sum + one.uncovered.length, 0),
60
+ };
61
+ }
62
+
63
+ /** The numbers for a map that could not be read at all: one problem, and the reason. */
64
+ export function unreadable(error: unknown): { problems: number; textProblems: number; coverage: number; entries: number; unchanged: number; touched: number; gone: number; uncovered: number; error: string } {
65
+ const message = error instanceof Error ? error.message : String(error);
66
+ return { problems: 1, textProblems: 0, coverage: 0, entries: 0, unchanged: 0, touched: 0, gone: 0, uncovered: 0, error: message.slice(0, 500) };
67
+ }