co-maintainer 0.6.13 → 0.7.0-beta.1

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 (156) hide show
  1. package/README.md +1 -1
  2. package/dist/package.json +1 -1
  3. package/dist/src/ai/anthropic.js +2 -0
  4. package/dist/src/ai/batch.d.ts +3 -1
  5. package/dist/src/ai/batch.js +23 -2
  6. package/dist/src/ai/mermaid_loop.js +1 -1
  7. package/dist/src/ai/oauth/sign-in-with-chatgpt.js +8 -10
  8. package/dist/src/ai/openai.js +2 -0
  9. package/dist/src/ai/openrouter.js +2 -0
  10. package/dist/src/cli/args.js +47 -0
  11. package/dist/src/cli/command_json.d.ts +20 -1
  12. package/dist/src/cli/command_json.js +4 -0
  13. package/dist/src/cli/commands/config.d.ts +1 -1
  14. package/dist/src/cli/commands/config.js +1 -0
  15. package/dist/src/cli/commands/registry.js +226 -1
  16. package/dist/src/cli/commands/review.js +50 -9
  17. package/dist/src/cli/commands/serve.js +5 -0
  18. package/dist/src/cli/commands/set.js +70 -2
  19. package/dist/src/cli/commands/view.js +46 -5
  20. package/dist/src/cli/commands/view_sources.d.ts +11 -0
  21. package/dist/src/cli/commands/view_sources.js +40 -0
  22. package/dist/src/cli/main.js +5 -0
  23. package/dist/src/cli/pr_carry.d.ts +25 -0
  24. package/dist/src/cli/pr_carry.js +128 -0
  25. package/dist/src/cli/prompt.js +26 -1
  26. package/dist/src/cli/review_args.d.ts +8 -0
  27. package/dist/src/cli/review_args.js +18 -0
  28. package/dist/src/cli/review_carry.d.ts +32 -0
  29. package/dist/src/cli/review_carry.js +60 -0
  30. package/dist/src/cli/review_github.d.ts +16 -2
  31. package/dist/src/cli/review_github.js +49 -12
  32. package/dist/src/cli/review_intent.d.ts +25 -0
  33. package/dist/src/cli/review_intent.js +87 -0
  34. package/dist/src/cli/review_result.d.ts +53 -2
  35. package/dist/src/cli/review_result.js +90 -23
  36. package/dist/src/config.d.ts +27 -0
  37. package/dist/src/config.js +20 -12
  38. package/dist/src/extensions/command.d.ts +1 -0
  39. package/dist/src/extensions/command.js +355 -0
  40. package/dist/src/extensions/contexts.d.ts +65 -0
  41. package/dist/src/extensions/contexts.js +134 -0
  42. package/dist/src/extensions/cost.d.ts +8 -0
  43. package/dist/src/extensions/cost.js +6 -0
  44. package/dist/src/extensions/local_tracking.d.ts +7 -0
  45. package/dist/src/extensions/local_tracking.js +29 -0
  46. package/dist/src/extensions/mock.d.ts +29 -0
  47. package/dist/src/extensions/mock.js +67 -0
  48. package/dist/src/extensions/process.d.ts +43 -0
  49. package/dist/src/extensions/process.js +244 -0
  50. package/dist/src/extensions/registry.d.ts +79 -0
  51. package/dist/src/extensions/registry.js +240 -0
  52. package/dist/src/extensions/render_actions.d.ts +6 -0
  53. package/dist/src/extensions/render_actions.js +50 -0
  54. package/dist/src/extensions/render_cli.d.ts +18 -0
  55. package/dist/src/extensions/render_cli.js +88 -0
  56. package/dist/src/extensions/render_json.d.ts +51 -0
  57. package/dist/src/extensions/render_json.js +144 -0
  58. package/dist/src/extensions/render_markdown.d.ts +22 -0
  59. package/dist/src/extensions/render_markdown.js +96 -0
  60. package/dist/src/extensions/render_review.d.ts +44 -0
  61. package/dist/src/extensions/render_review.js +167 -0
  62. package/dist/src/extensions/report.d.ts +57 -0
  63. package/dist/src/extensions/report.js +97 -0
  64. package/dist/src/extensions/review_result.d.ts +2 -0
  65. package/dist/src/extensions/review_result.js +14 -0
  66. package/dist/src/extensions/run_folder.d.ts +74 -0
  67. package/dist/src/extensions/run_folder.js +172 -0
  68. package/dist/src/extensions/runner.d.ts +66 -0
  69. package/dist/src/extensions/runner.js +251 -0
  70. package/dist/src/extensions/schema.d.ts +103 -0
  71. package/dist/src/extensions/schema.js +539 -0
  72. package/dist/src/extensions/session.d.ts +56 -0
  73. package/dist/src/extensions/session.js +173 -0
  74. package/dist/src/github/collect.d.ts +7 -2
  75. package/dist/src/github/collect.js +66 -6
  76. package/dist/src/github/gh.d.ts +7 -0
  77. package/dist/src/github/gh.js +24 -29
  78. package/dist/src/knowledge/guide.js +3 -2
  79. package/dist/src/knowledge/instruction_files.d.ts +45 -0
  80. package/dist/src/knowledge/instruction_files.js +91 -0
  81. package/dist/src/knowledge/instructions.d.ts +78 -0
  82. package/dist/src/knowledge/instructions.js +280 -0
  83. package/dist/src/knowledge/rule_changes.d.ts +39 -0
  84. package/dist/src/knowledge/rule_changes.js +90 -0
  85. package/dist/src/knowledge/rules.d.ts +44 -0
  86. package/dist/src/knowledge/rules.js +82 -0
  87. package/dist/src/knowledge/synthesis.d.ts +1 -0
  88. package/dist/src/knowledge/synthesis.js +12 -5
  89. package/dist/src/knowledge/types.d.ts +4 -0
  90. package/dist/src/local/carry_over_store.d.ts +10 -0
  91. package/dist/src/local/carry_over_store.js +17 -0
  92. package/dist/src/local/review_local.js +100 -62
  93. package/dist/src/local/review_lock.js +15 -4
  94. package/dist/src/pr/diff_plan.d.ts +110 -0
  95. package/dist/src/pr/diff_plan.js +429 -0
  96. package/dist/src/pr/diff_summary.d.ts +17 -1
  97. package/dist/src/pr/diff_summary.js +87 -13
  98. package/dist/src/pr/review_diff.d.ts +47 -0
  99. package/dist/src/pr/review_diff.js +112 -0
  100. package/dist/src/pr/reviewer.d.ts +44 -19
  101. package/dist/src/pr/reviewer.js +114 -142
  102. package/dist/src/remote/client.js +67 -8
  103. package/dist/src/remote/http.d.ts +12 -0
  104. package/dist/src/remote/http.js +31 -0
  105. package/dist/src/remote/push_client.js +14 -3
  106. package/dist/src/remote/server/guides.js +12 -1
  107. package/dist/src/remote/server/routes.js +4 -2
  108. package/dist/src/remote/server/sessions.js +4 -1
  109. package/dist/src/remote/validate.js +11 -0
  110. package/dist/src/review/carry_over.d.ts +6 -1
  111. package/dist/src/review/carry_over.js +10 -2
  112. package/dist/src/review/coverage.d.ts +57 -0
  113. package/dist/src/review/coverage.js +186 -0
  114. package/dist/src/review/diagram.d.ts +73 -0
  115. package/dist/src/review/diagram.js +309 -0
  116. package/dist/src/review/engine.d.ts +2 -6
  117. package/dist/src/review/engine.js +1 -1
  118. package/dist/src/review/guides.d.ts +6 -0
  119. package/dist/src/review/guides.js +8 -1
  120. package/dist/src/review/intent.d.ts +24 -0
  121. package/dist/src/review/intent.js +28 -0
  122. package/dist/src/review/not_initialized.d.ts +13 -0
  123. package/dist/src/review/not_initialized.js +18 -0
  124. package/dist/src/review/system_prompt.d.ts +6 -0
  125. package/dist/src/review/system_prompt.js +13 -0
  126. package/dist/src/review/visible_paths.d.ts +22 -0
  127. package/dist/src/review/visible_paths.js +41 -0
  128. package/dist/src/server/pages/extensions.d.ts +5 -0
  129. package/dist/src/server/pages/extensions.js +72 -0
  130. package/dist/src/server/pages/pr.js +3 -2
  131. package/dist/src/services/dashboard.d.ts +8 -0
  132. package/dist/src/services/dashboard.js +8 -0
  133. package/dist/src/services/push_review.js +14 -5
  134. package/dist/src/services/remote_review.js +81 -26
  135. package/dist/src/services/replies.js +15 -8
  136. package/dist/src/services/review.d.ts +9 -3
  137. package/dist/src/services/review.js +109 -28
  138. package/dist/src/services/rules_build.d.ts +46 -0
  139. package/dist/src/services/rules_build.js +155 -0
  140. package/dist/src/services/setup.d.ts +31 -0
  141. package/dist/src/services/setup.js +120 -25
  142. package/dist/src/services/watch_comments.js +2 -0
  143. package/dist/src/store/cache_db.js +3 -0
  144. package/dist/src/store/extensions.d.ts +51 -0
  145. package/dist/src/store/extensions.js +132 -0
  146. package/dist/src/store/migrations.js +40 -0
  147. package/dist/src/types.d.ts +22 -1
  148. package/dist/src/util/atomic.d.ts +15 -1
  149. package/dist/src/util/atomic.js +59 -29
  150. package/dist/src/util/interrupt.d.ts +6 -0
  151. package/dist/src/util/interrupt.js +27 -0
  152. package/dist/src/util/runtime.d.ts +3 -1
  153. package/dist/src/util/runtime.js +2 -2
  154. package/dist/src/util/test_location_guard.d.ts +6 -0
  155. package/dist/src/util/test_location_guard.js +47 -0
  156. package/package.json +1 -1
@@ -0,0 +1,539 @@
1
+ /** The JSON an extension prints on stdout, as data.
2
+ *
3
+ * One list of field specs drives two things: the validator that decides
4
+ * whether a response is usable, and the schema table in the extensions docs
5
+ * page. A field cannot be checked one way and documented another, and the docs
6
+ * test fails when the table on the page is older than this list. The rules
7
+ * that tie one field to another (a verdict only with `ok`, a reason with
8
+ * `skipped`) are written out in `crossFieldProblem` and named in the table's
9
+ * rule column. */
10
+ export const EXTENSION_SCHEMA_VERSION = 1;
11
+ /** The longest wait a `retry` response may ask for. */
12
+ export const MAX_RETRY_AFTER_SECONDS = 180;
13
+ /** Limits that keep one response from filling app.db, the dashboard and a
14
+ * remote client's output. */
15
+ const MAX_TITLE_CHARS = 500;
16
+ const MAX_BODY_CHARS = 20_000;
17
+ const MAX_KEY_CHARS = 200;
18
+ const MAX_LABEL_CHARS = 100;
19
+ const MAX_PATH_CHARS = 1_000;
20
+ const MAX_REASON_CHARS = 2_000;
21
+ export const MAX_MARKDOWN_CHARS = 200_000;
22
+ /** A cost or a token count past these is a bug, not a bill. */
23
+ const MAX_COST_USD = 10_000;
24
+ const MAX_TOKENS = 10_000_000_000;
25
+ export const SEVERITIES = ["P0", "P1", "P2", "P3"];
26
+ export const STATUSES = ["ok", "failed", "skipped", "retry"];
27
+ export const VERDICTS = ["request_changes", "comment"];
28
+ export const MEDIA_KINDS = ["image", "video", "link"];
29
+ export const RESPONSE_FIELDS = [
30
+ {
31
+ name: "schemaVersion",
32
+ type: "integer",
33
+ required: "yes",
34
+ description: `Must be ${EXTENSION_SCHEMA_VERSION}. Any other value is Failed, with that as the reason.`,
35
+ },
36
+ {
37
+ name: "name",
38
+ type: "string",
39
+ maxLength: MAX_LABEL_CHARS,
40
+ required: "yes",
41
+ description: "The extension's own name, for its logs.",
42
+ },
43
+ {
44
+ name: "status",
45
+ type: "string",
46
+ required: "yes",
47
+ enum: STATUSES,
48
+ description: "How the run ended.",
49
+ },
50
+ {
51
+ name: "verdict",
52
+ type: "string",
53
+ required: "with `ok`, absent otherwise",
54
+ enum: VERDICTS,
55
+ description: "`request_changes` makes the whole review Request changes. It always wins over a finding's `blocking`.",
56
+ },
57
+ {
58
+ name: "reason",
59
+ type: "string",
60
+ maxLength: MAX_REASON_CHARS,
61
+ required: "with `skipped` and `retry`",
62
+ description: "Why the extension skipped, failed or wants a retry.",
63
+ },
64
+ {
65
+ name: "retryAfterSeconds",
66
+ type: "integer",
67
+ required: "with `retry`",
68
+ min: 0,
69
+ max: MAX_RETRY_AFTER_SECONDS,
70
+ description: "How long to wait before the next run.",
71
+ },
72
+ {
73
+ name: "markdown",
74
+ type: "string",
75
+ maxLength: MAX_MARKDOWN_CHARS,
76
+ required: "no",
77
+ description: "Shown in the GitHub review and the job summary, inside a `<details>` block named after the extension.",
78
+ },
79
+ {
80
+ name: "findings",
81
+ type: "array",
82
+ required: "no",
83
+ description: "Findings that join the review.",
84
+ fields: [
85
+ {
86
+ name: "key",
87
+ type: "string",
88
+ maxLength: MAX_KEY_CHARS,
89
+ required: "no",
90
+ description: "A stable id. With one, the finding is tracked across rounds: seen again means still open, missing means closed.",
91
+ },
92
+ {
93
+ name: "severity",
94
+ type: "string",
95
+ required: "yes",
96
+ enum: SEVERITIES,
97
+ description: "P0 is the most severe.",
98
+ },
99
+ {
100
+ name: "blocking",
101
+ type: "boolean",
102
+ required: "yes",
103
+ description: "Whether this finding alone should block the merge.",
104
+ },
105
+ {
106
+ name: "title",
107
+ type: "string",
108
+ maxLength: MAX_TITLE_CHARS,
109
+ required: "yes",
110
+ description: "One line.",
111
+ },
112
+ {
113
+ name: "body",
114
+ type: "string",
115
+ maxLength: MAX_BODY_CHARS,
116
+ required: "yes",
117
+ description: "The explanation, in Markdown.",
118
+ },
119
+ {
120
+ name: "path",
121
+ type: "string",
122
+ maxLength: MAX_PATH_CHARS,
123
+ required: "no",
124
+ description: "A file path relative to the repository root.",
125
+ },
126
+ {
127
+ name: "lineFrom",
128
+ type: "integer",
129
+ required: "no",
130
+ min: 1,
131
+ description: "First line in the new file.",
132
+ },
133
+ {
134
+ name: "lineTo",
135
+ type: "integer",
136
+ required: "no",
137
+ min: 1,
138
+ description: "Last line in the new file.",
139
+ },
140
+ ],
141
+ },
142
+ {
143
+ name: "data",
144
+ type: "object",
145
+ required: "no",
146
+ description: "Results with a fixed shape co-maintainer can show.",
147
+ fields: [
148
+ {
149
+ name: "media",
150
+ type: "array",
151
+ required: "no",
152
+ description: "Files the extension uploaded itself. co-maintainer uploads nothing.",
153
+ fields: [
154
+ {
155
+ name: "kind",
156
+ type: "string",
157
+ required: "yes",
158
+ enum: MEDIA_KINDS,
159
+ description: "What the URL points at.",
160
+ },
161
+ {
162
+ name: "label",
163
+ type: "string",
164
+ maxLength: MAX_LABEL_CHARS,
165
+ required: "yes",
166
+ description: "A short name, such as `main` or `pr`.",
167
+ },
168
+ {
169
+ name: "url",
170
+ type: "url",
171
+ required: "yes",
172
+ description: "An http or https URL.",
173
+ },
174
+ ],
175
+ },
176
+ {
177
+ name: "metrics",
178
+ type: "array",
179
+ required: "no",
180
+ description: "Numbers worth showing next to the result.",
181
+ fields: [
182
+ {
183
+ name: "name",
184
+ type: "string",
185
+ required: "yes",
186
+ description: "What was measured.",
187
+ },
188
+ {
189
+ name: "value",
190
+ type: "number",
191
+ required: "yes",
192
+ description: "The measurement.",
193
+ },
194
+ {
195
+ name: "unit",
196
+ type: "string",
197
+ required: "no",
198
+ description: "Such as `ms` or `MB`.",
199
+ },
200
+ ],
201
+ },
202
+ ],
203
+ },
204
+ {
205
+ name: "extraData",
206
+ type: "any",
207
+ required: "no",
208
+ description: "Free-form. Passed through to `--json` and never read by co-maintainer.",
209
+ },
210
+ {
211
+ name: "usage",
212
+ type: "object",
213
+ required: "no",
214
+ description: "What the run cost, when it used AI.",
215
+ fields: [
216
+ {
217
+ name: "costUsd",
218
+ type: "number",
219
+ required: "no",
220
+ min: 0,
221
+ max: MAX_COST_USD,
222
+ description: "Joins the review's total cost.",
223
+ },
224
+ {
225
+ name: "tokensIn",
226
+ type: "integer",
227
+ required: "no",
228
+ min: 0,
229
+ max: MAX_TOKENS,
230
+ description: "Input tokens.",
231
+ },
232
+ {
233
+ name: "tokensOut",
234
+ type: "integer",
235
+ required: "no",
236
+ min: 0,
237
+ max: MAX_TOKENS,
238
+ description: "Output tokens.",
239
+ },
240
+ {
241
+ name: "cachedIn",
242
+ type: "integer",
243
+ required: "no",
244
+ min: 0,
245
+ max: MAX_TOKENS,
246
+ description: "Cached input tokens.",
247
+ },
248
+ {
249
+ name: "cachedOut",
250
+ type: "integer",
251
+ required: "no",
252
+ min: 0,
253
+ max: MAX_TOKENS,
254
+ description: "Cached output tokens.",
255
+ },
256
+ ],
257
+ },
258
+ ];
259
+ function isRecord(value) {
260
+ return typeof value === "object" && value !== null && !Array.isArray(value);
261
+ }
262
+ function typeProblem(spec, value) {
263
+ switch (spec.type) {
264
+ case "string":
265
+ if (typeof value !== "string")
266
+ return "must be a string";
267
+ break;
268
+ case "url": {
269
+ if (typeof value !== "string")
270
+ return "must be a string";
271
+ let url;
272
+ try {
273
+ url = new URL(value);
274
+ }
275
+ catch {
276
+ return "must be an http or https URL";
277
+ }
278
+ if (url.protocol !== "http:" && url.protocol !== "https:") {
279
+ return "must be an http or https URL";
280
+ }
281
+ break;
282
+ }
283
+ case "number":
284
+ if (typeof value !== "number" || !Number.isFinite(value)) {
285
+ return "must be a number";
286
+ }
287
+ break;
288
+ case "integer":
289
+ if (typeof value !== "number" || !Number.isInteger(value)) {
290
+ return "must be an integer";
291
+ }
292
+ break;
293
+ case "boolean":
294
+ if (typeof value !== "boolean")
295
+ return "must be true or false";
296
+ break;
297
+ case "object":
298
+ if (!isRecord(value))
299
+ return "must be an object";
300
+ break;
301
+ case "array":
302
+ if (!Array.isArray(value))
303
+ return "must be an array";
304
+ break;
305
+ case "any":
306
+ break;
307
+ }
308
+ if (spec.maxLength !== undefined &&
309
+ typeof value === "string" &&
310
+ value.length > spec.maxLength) {
311
+ return `must be at most ${spec.maxLength} characters`;
312
+ }
313
+ if (spec.enum && !spec.enum.includes(value)) {
314
+ return `must be one of ${spec.enum.join(", ")}`;
315
+ }
316
+ if (typeof value === "number") {
317
+ if (spec.min !== undefined && value < spec.min) {
318
+ return `must be at least ${spec.min}`;
319
+ }
320
+ if (spec.max !== undefined && value > spec.max) {
321
+ return `must be at most ${spec.max}`;
322
+ }
323
+ }
324
+ return undefined;
325
+ }
326
+ /** The first problem in `value` against `fields`, as `path message`. Unknown
327
+ * fields are ignored, so an extension may add its own. */
328
+ function fieldsProblem(fields, value, prefix) {
329
+ for (const spec of fields) {
330
+ const path = `${prefix}${spec.name}`;
331
+ const item = value[spec.name];
332
+ if (item === undefined || item === null) {
333
+ if (spec.required === "yes")
334
+ return `${path} is required`;
335
+ continue;
336
+ }
337
+ const problem = typeProblem(spec, item);
338
+ if (problem)
339
+ return `${path} ${problem}`;
340
+ if (!spec.fields)
341
+ continue;
342
+ if (spec.type === "object") {
343
+ const nested = fieldsProblem(spec.fields, item, `${path}.`);
344
+ if (nested)
345
+ return nested;
346
+ }
347
+ if (spec.type === "array") {
348
+ const list = item;
349
+ for (let index = 0; index < list.length; index++) {
350
+ const entry = list[index];
351
+ if (!isRecord(entry))
352
+ return `${path}[${index}] must be an object`;
353
+ const nested = fieldsProblem(spec.fields, entry, `${path}[${index}].`);
354
+ if (nested)
355
+ return nested;
356
+ }
357
+ }
358
+ }
359
+ return undefined;
360
+ }
361
+ /** The rules the field list cannot say on its own. */
362
+ function crossFieldProblem(value) {
363
+ const status = value.status;
364
+ const hasVerdict = value.verdict !== undefined && value.verdict !== null;
365
+ if (status === "ok" && !hasVerdict)
366
+ return "verdict is required with ok";
367
+ if (status !== "ok" && hasVerdict) {
368
+ return `verdict must be absent with ${status}`;
369
+ }
370
+ const hasReason = typeof value.reason === "string" && value.reason !== "";
371
+ if ((status === "skipped" || status === "retry") && !hasReason) {
372
+ return `reason is required with ${status}`;
373
+ }
374
+ if (status === "retry" && typeof value.retryAfterSeconds !== "number") {
375
+ return "retryAfterSeconds is required with retry";
376
+ }
377
+ const findings = (value.findings ?? []);
378
+ for (let index = 0; index < findings.length; index++) {
379
+ const finding = findings[index];
380
+ const from = finding.lineFrom;
381
+ const to = finding.lineTo;
382
+ if (to !== undefined && from === undefined) {
383
+ return `findings[${index}].lineTo needs lineFrom`;
384
+ }
385
+ if (from !== undefined && to !== undefined && to < from) {
386
+ return `findings[${index}].lineTo must not be before lineFrom`;
387
+ }
388
+ if (from !== undefined && typeof finding.path !== "string") {
389
+ return `findings[${index}].lineFrom needs path`;
390
+ }
391
+ }
392
+ return undefined;
393
+ }
394
+ /** Checks one parsed response. An unsupported `schemaVersion` is reported on
395
+ * its own, before anything else, so an extension built for a later version
396
+ * gets a reason that says so instead of a complaint about a field it renamed. */
397
+ export function validateResponse(value) {
398
+ if (!isRecord(value)) {
399
+ return { ok: false, reason: "the response is not a JSON object" };
400
+ }
401
+ if (value.schemaVersion !== undefined &&
402
+ value.schemaVersion !== EXTENSION_SCHEMA_VERSION) {
403
+ return {
404
+ ok: false,
405
+ reason: `unsupported schemaVersion ${JSON.stringify(value.schemaVersion)}, this co-maintainer reads ${EXTENSION_SCHEMA_VERSION}`,
406
+ };
407
+ }
408
+ const problem = fieldsProblem(RESPONSE_FIELDS, value, "") ?? crossFieldProblem(value);
409
+ if (problem)
410
+ return { ok: false, reason: problem };
411
+ const data = (value.data ?? {});
412
+ const response = {
413
+ schemaVersion: EXTENSION_SCHEMA_VERSION,
414
+ name: value.name,
415
+ status: value.status,
416
+ markdown: typeof value.markdown === "string" ? value.markdown : "",
417
+ findings: (value.findings ?? []).map((finding) => ({
418
+ ...(typeof finding.key === "string" && finding.key !== ""
419
+ ? { key: finding.key }
420
+ : {}),
421
+ severity: finding.severity,
422
+ blocking: finding.blocking,
423
+ title: finding.title,
424
+ body: finding.body,
425
+ ...(typeof finding.path === "string" ? { path: finding.path } : {}),
426
+ ...(typeof finding.lineFrom === "number"
427
+ ? { lineFrom: finding.lineFrom }
428
+ : {}),
429
+ ...(typeof finding.lineTo === "number"
430
+ ? { lineTo: finding.lineTo }
431
+ : {}),
432
+ })),
433
+ data: {
434
+ media: (data.media ?? []).map((media) => ({
435
+ kind: media.kind,
436
+ label: media.label,
437
+ url: media.url,
438
+ })),
439
+ metrics: (data.metrics ?? []).map((metric) => ({
440
+ name: metric.name,
441
+ value: metric.value,
442
+ ...(typeof metric.unit === "string" ? { unit: metric.unit } : {}),
443
+ })),
444
+ },
445
+ extraData: value.extraData ?? null,
446
+ };
447
+ if (value.verdict !== undefined && value.verdict !== null) {
448
+ response.verdict = value.verdict;
449
+ }
450
+ if (typeof value.reason === "string" && value.reason !== "") {
451
+ response.reason = value.reason;
452
+ }
453
+ if (typeof value.retryAfterSeconds === "number") {
454
+ response.retryAfterSeconds = value.retryAfterSeconds;
455
+ }
456
+ if (isRecord(value.usage)) {
457
+ const usage = {};
458
+ for (const field of [
459
+ "costUsd",
460
+ "tokensIn",
461
+ "tokensOut",
462
+ "cachedIn",
463
+ "cachedOut",
464
+ ]) {
465
+ const number = value.usage[field];
466
+ if (typeof number === "number")
467
+ usage[field] = number;
468
+ }
469
+ response.usage = usage;
470
+ }
471
+ return { ok: true, response };
472
+ }
473
+ /** stdout as a response. Only the whole of stdout counts: no streaming, no
474
+ * log lines around the JSON. */
475
+ export function parseResponse(stdout) {
476
+ const text = stdout.trim();
477
+ if (text === "")
478
+ return { ok: false, reason: "the command printed nothing" };
479
+ let parsed;
480
+ try {
481
+ parsed = JSON.parse(text);
482
+ }
483
+ catch {
484
+ return { ok: false, reason: "stdout is not one JSON document" };
485
+ }
486
+ return validateResponse(parsed);
487
+ }
488
+ /** A table cell: no raw pipe, which would split the column. */
489
+ function cell(text) {
490
+ return text.replace(/\|/g, "\\|");
491
+ }
492
+ function typeLabel(spec) {
493
+ if (spec.enum)
494
+ return spec.enum.map((value) => `\`${value}\``).join(", ");
495
+ if (spec.type === "array" && spec.fields)
496
+ return "array of objects";
497
+ if (spec.type === "url")
498
+ return "string (URL)";
499
+ return spec.type;
500
+ }
501
+ function tableRows(fields, prefix, rows) {
502
+ for (const spec of fields) {
503
+ const path = `${prefix}${spec.name}`;
504
+ const limits = [];
505
+ if (spec.min !== undefined)
506
+ limits.push(`min ${spec.min}`);
507
+ if (spec.max !== undefined)
508
+ limits.push(`max ${spec.max}`);
509
+ if (spec.maxLength !== undefined) {
510
+ limits.push(`at most ${spec.maxLength} characters`);
511
+ }
512
+ const description = limits.length
513
+ ? `${spec.description} (${limits.join(", ")})`
514
+ : spec.description;
515
+ rows.push(`| \`${path}\` | ${cell(typeLabel(spec))} | ${cell(spec.required)} | ${cell(description)} |`);
516
+ if (spec.fields) {
517
+ tableRows(spec.fields, spec.type === "array" ? `${path}[].` : `${path}.`, rows);
518
+ }
519
+ }
520
+ }
521
+ /** The response schema as the Markdown table the docs page carries between
522
+ * its `extension-schema` markers. */
523
+ export function responseSchemaTable() {
524
+ const rows = ["| Field | Type | Required | Meaning |", "|---|---|---|---|"];
525
+ tableRows(RESPONSE_FIELDS, "", rows);
526
+ return rows.join("\n");
527
+ }
528
+ export const SCHEMA_BLOCK_START = "<!-- extension-schema:start -->";
529
+ export const SCHEMA_BLOCK_END = "<!-- extension-schema:end -->";
530
+ /** Rewrites the schema block in a docs page from the code. */
531
+ export function applySchemaBlock(md) {
532
+ const start = md.indexOf(SCHEMA_BLOCK_START);
533
+ const end = md.indexOf(SCHEMA_BLOCK_END);
534
+ if (start === -1 || end === -1 || end < start)
535
+ return md;
536
+ return (md.slice(0, start) +
537
+ `${SCHEMA_BLOCK_START}\n${responseSchemaTable()}\n${SCHEMA_BLOCK_END}` +
538
+ md.slice(end + SCHEMA_BLOCK_END.length));
539
+ }
@@ -0,0 +1,56 @@
1
+ import { type ReviewType } from "./registry.ts";
2
+ import { type RunOwner } from "./run_folder.ts";
3
+ import { type ExtensionReport, type PreviousExtensionFinding } from "./report.ts";
4
+ /** Where a review type keeps the keyed findings of its last round. */
5
+ export type ExtensionTracking = {
6
+ /** The round number this review is, and the findings to compare with. */
7
+ load(): Promise<{
8
+ round?: number;
9
+ previous: PreviousExtensionFinding[];
10
+ }>;
11
+ /** `previous` is what the next round compares with. */
12
+ save(report: ExtensionReport, previous: PreviousExtensionFinding[]): Promise<void>;
13
+ };
14
+ export type ReviewContext = {
15
+ /** A serve job passes its job id, so a rerun after a restart finds the
16
+ * folder the first run left. The CLI leaves it out. */
17
+ runId?: string;
18
+ owner: RunOwner;
19
+ reviewType: ReviewType;
20
+ repo: string;
21
+ prNumber: number | null;
22
+ branch: string | null;
23
+ workdir: string;
24
+ headSha: string | null;
25
+ baseSha: string | null;
26
+ scope: string;
27
+ sinceCommit: string | null;
28
+ trigger: string;
29
+ round: number;
30
+ /** Built only when an extension runs. */
31
+ diff: () => string | Promise<string>;
32
+ /** Absent: every finding is new, as in a CLI pull request review, which
33
+ * keeps nothing between runs. */
34
+ tracking?: ExtensionTracking;
35
+ signal?: AbortSignal;
36
+ log?: (message: string) => void;
37
+ };
38
+ export type WithExtensions<T> = {
39
+ review: T;
40
+ /** Empty when no extension ran. */
41
+ extensions: ExtensionReport;
42
+ };
43
+ /** One file of a review's diff, from GitHub or from git. */
44
+ export type DiffFile = {
45
+ path: string;
46
+ previousPath?: string | null;
47
+ status?: string;
48
+ patch: string;
49
+ };
50
+ /** A path in a diff header, quoted the way git quotes it. A file name may
51
+ * hold a newline, and unquoted it could forge a `+++` header in the patch an
52
+ * extension reads. */
53
+ export declare function quotePath(path: string): string;
54
+ /** A unified diff from the per-file patches every review type already has. */
55
+ export declare function unifiedDiff(files: DiffFile[]): string;
56
+ export declare function withExtensions<T>(context: ReviewContext, review: () => Promise<T>, reviewResult: (result: T) => unknown): Promise<WithExtensions<T>>;