@bendyline/gezel-script-stdlib 1.0.9 → 1.1.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-script-stdlib",
3
- "version": "1.0.9",
3
+ "version": "1.1.0",
4
4
  "description": "Standard gate-script library packed into the app. Plain defineScript sources resolved in place by the script runner (scope: 'standard'); read-only, trusted, versioned with the app.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -41,7 +41,7 @@
41
41
  "!scripts/**/*.test.ts"
42
42
  ],
43
43
  "dependencies": {
44
- "@bendyline/gezel-sdk": "1.0.9"
44
+ "@bendyline/gezel-sdk": "1.1.0"
45
45
  },
46
46
  "devDependencies": {
47
47
  "@types/node": "^24.13.3",
@@ -1,13 +1,15 @@
1
1
  import { type InferredInput, defineScript, gezel } from '@bendyline/gezel-sdk';
2
- import { gateResult } from '@bendyline/gezel-sdk/checks';
2
+ import { type GateScriptResult, gateResult } from '@bendyline/gezel-sdk/checks';
3
3
 
4
4
  /**
5
5
  * Fix-review gate (the enforceable `evaluate` step of the tactical fleet):
6
6
  * the reviewer's artifact at `<task.dir>/review.md` is well-formed and its
7
7
  * verdict actually routes the loop. `Verdict: PASS` advances; a well-formed
8
8
  * `Verdict: REVISE` rejects WITH `goto` back to the fix step, carrying the
9
- * findings as the prescriptive message; a malformed report rejects in place
10
- * so the reviewer repairs the report rather than the fixer thrashing.
9
+ * findings as the prescriptive message until the revision budget is spent; a
10
+ * malformed report rejects in place so the reviewer repairs the report rather
11
+ * than the fixer thrashing. The budget is based on the evaluate step's durable
12
+ * activation count, so routing through a separate fix step cannot reset it.
11
13
  *
12
14
  * Anti-fabrication: every file the review cites must exist — probed by
13
15
  * reading each path (workspace, the task's diffpack overlay when drafting,
@@ -17,7 +19,7 @@ import { gateResult } from '@bendyline/gezel-sdk/checks';
17
19
  export const meta = defineScript({
18
20
  name: 'checkFixReview',
19
21
  description:
20
- 'Gate: a fix/improvement review artifact is well-formed — a `Verdict: PASS` or `Verdict: REVISE` line, severities from critical/major/minor/nit, every cited file exists (workspace, draft overlay, or artifacts), critical/major findings force REVISE — and a REVISE verdict routes the task back to the fix step with the findings as the message.',
22
+ 'Gate: a fix/improvement review artifact is well-formed — a `Verdict: PASS` or `Verdict: REVISE` line, severities from critical/major/minor/nit, every cited file exists (workspace, draft overlay, or artifacts), critical/major findings force REVISE — and a REVISE verdict routes the task back to the fix step with the findings as the message, up to a bounded number of review rounds.',
21
23
  kind: 'gate',
22
24
  inputs: {
23
25
  taskRef: {
@@ -38,6 +40,19 @@ export const meta = defineScript({
38
40
  type: 'string',
39
41
  description: "Step to route a REVISE verdict back to. Defaults to 'fix'.",
40
42
  },
43
+ maxReviewRounds: {
44
+ type: 'number',
45
+ description:
46
+ 'Maximum evaluate-step activations that may route REVISE back to the fixer. Defaults to 3.',
47
+ default: 3,
48
+ integer: true,
49
+ min: 1,
50
+ },
51
+ needsUserStepId: {
52
+ type: 'string',
53
+ description:
54
+ "Optional terminal escalation step used when the review budget is spent. When omitted, a terminal 'needs-user' step is discovered automatically; otherwise the gate rejects in place so its ordinary maxAttempts budget can pause the task.",
55
+ },
41
56
  },
42
57
  outputs: {
43
58
  decision: { type: 'string', description: "'approve' or 'reject'." },
@@ -60,6 +75,12 @@ interface TaskView {
60
75
  diffpackId?: string;
61
76
  }
62
77
 
78
+ interface TaskStepView {
79
+ id: string;
80
+ attemptCount?: number;
81
+ terminal?: boolean;
82
+ }
83
+
63
84
  const input = gezel.input as InferredInput<typeof meta>;
64
85
 
65
86
  /** Strip citation decoration so `./src/x.ts`, `a/src/x.ts`, `src/x.ts` compare equal. */
@@ -76,6 +97,52 @@ const task = (await gezel.task.get(input.taskRef ?? '').catch(() => null)) as Ta
76
97
  const taskDir = task?.artifactDir ?? (task?.num !== undefined ? `tasks/${task.num}` : undefined);
77
98
  const reviewPath = input.reviewPath ?? (taskDir ? `${taskDir}/review.md` : undefined);
78
99
  const fixStepId = input.fixStepId ?? 'fix';
100
+ const maxReviewRounds = input.maxReviewRounds ?? 3;
101
+
102
+ async function reviseDecision(message: string): Promise<GateScriptResult> {
103
+ const currentStep = (await gezel.task
104
+ .currentStep(input.taskRef ?? '')
105
+ .catch(() => null)) as TaskStepView | null;
106
+
107
+ // Fail closed if the durable counter cannot be read. Routing to the fixer
108
+ // without it would recreate the unbounded evaluate -> fix -> evaluate loop
109
+ // this budget exists to prevent. Rejecting in place leaves the gate's own
110
+ // maxAttempts counter intact, so the normal runtime pause remains available.
111
+ if (!currentStep) {
112
+ return gateResult(
113
+ false,
114
+ `${message}\n\nThe review needs revision, but the gate could not read the current step's review-round counter. It refused to start an unbounded repair loop; retry review or ask a user to intervene.`,
115
+ );
116
+ }
117
+
118
+ const reviewRound = Math.max(1, currentStep.attemptCount ?? 1);
119
+ if (reviewRound < maxReviewRounds) {
120
+ return {
121
+ decision: 'reject',
122
+ goto: fixStepId,
123
+ message: `${message}\n\nReview round ${reviewRound} of ${maxReviewRounds}; return to ${fixStepId} for another bounded repair pass.`,
124
+ };
125
+ }
126
+
127
+ const steps = (await gezel.task.steps(input.taskRef ?? '').catch(() => [])) as TaskStepView[];
128
+ const requestedEscalation = input.needsUserStepId?.trim();
129
+ const escalationStep = requestedEscalation
130
+ ? steps.find((step) => step.id === requestedEscalation && step.terminal)
131
+ : steps.find((step) => step.id === 'needs-user' && step.terminal);
132
+ const exhausted = `${message}\n\nReview budget exhausted after ${reviewRound} of ${maxReviewRounds} round(s). Stop the automatic repair loop and report DONE_WITH_CONCERNS with the unresolved findings.`;
133
+
134
+ if (escalationStep) {
135
+ return { decision: 'reject', goto: escalationStep.id, message: exhausted };
136
+ }
137
+
138
+ // No safe terminal route is present in older/custom books. Stay on the
139
+ // gated evaluate step instead of jumping to the fixer again. The gate's
140
+ // existing maxAttempts budget will then pause the task deterministically.
141
+ return gateResult(
142
+ false,
143
+ `${exhausted} No terminal escalation step is configured, so the gate is holding this evaluate step for user intervention.`,
144
+ );
145
+ }
79
146
 
80
147
  /**
81
148
  * A cited path exists when it reads from ANY surface the review may talk
@@ -238,11 +305,11 @@ if (!reviewPath) {
238
305
  `- [${r.severity || 'finding'}] ${r.file}${r.problem ? ` — ${r.problem}` : ''}${r.fix ? ` → ${r.fix}` : ''}`,
239
306
  )
240
307
  .join('\n');
241
- gezel.output({
242
- decision: 'reject',
243
- goto: fixStepId,
244
- message: `Reviewer verdict: REVISE. Address these findings, then bring the work back through review:\n${summary}${rows.length > 6 ? `\n…and ${rows.length - 6} more in ${reviewPath}.` : ''}`,
245
- });
308
+ gezel.output(
309
+ await reviseDecision(
310
+ `Reviewer verdict: REVISE. Address these findings, then bring the work back through review:\n${summary}${rows.length > 6 ? `\n…and ${rows.length - 6} more in ${reviewPath}.` : ''}`,
311
+ ),
312
+ );
246
313
  } else {
247
314
  gezel.output(
248
315
  gateResult(
@@ -0,0 +1,70 @@
1
+ import { type InferredInput, defineScript, gezel } from '@bendyline/gezel-sdk';
2
+
3
+ /** Publish only bookkeeping after the service has verified full record reads. */
4
+ export const meta = defineScript({
5
+ name: 'publishCorpusCoverageShard',
6
+ description:
7
+ 'Action: copy the exact paths and records of one verified review batch into its coverage shard after the read-evidence gate passes.',
8
+ kind: 'action',
9
+ inputs: {
10
+ batchesFile: {
11
+ type: 'string',
12
+ description: 'Artifact path of the published batch array.',
13
+ required: true,
14
+ },
15
+ batchNumber: { type: 'string', description: 'One-based batch number.', required: true },
16
+ outFile: { type: 'string', description: 'Artifact path of coverage-N.json.', required: true },
17
+ },
18
+ outputs: {
19
+ ok: { type: 'boolean', description: 'True when the exact shard was written.' },
20
+ outFile: { type: 'string', description: 'Artifact path written.' },
21
+ files: { type: 'number', description: 'Number of reviewed paths copied.' },
22
+ },
23
+ requires: ['artifacts.read', 'artifacts.write'],
24
+ } as const);
25
+
26
+ const input = gezel.input as InferredInput<typeof meta>;
27
+ function cleanPath(raw: string, label: string): string {
28
+ const value = raw
29
+ .replace(/\\+/g, '/')
30
+ .replace(/^\.?\/+/, '')
31
+ .replace(/^artifacts\/+/i, '')
32
+ .trim();
33
+ if (!value || value.split('/').includes('..'))
34
+ throw new Error(`${label} must be a safe artifact-relative path.`);
35
+ return value;
36
+ }
37
+ const batchesFile = cleanPath(input.batchesFile, 'batchesFile');
38
+ const outFile = cleanPath(input.outFile, 'outFile');
39
+ const number = Number(input.batchNumber);
40
+ if (!Number.isSafeInteger(number) || number < 1)
41
+ throw new Error('batchNumber must be a positive integer.');
42
+ const raw = await gezel.artifacts.read(batchesFile);
43
+ let batches: unknown;
44
+ try {
45
+ batches = JSON.parse(raw);
46
+ } catch {
47
+ throw new Error(`${batchesFile} is not valid JSON.`);
48
+ }
49
+ if (!Array.isArray(batches)) throw new Error(`${batchesFile} must be a batch array.`);
50
+ const batch = batches.find(
51
+ (value) =>
52
+ value &&
53
+ typeof value === 'object' &&
54
+ !Array.isArray(value) &&
55
+ (value as Record<string, unknown>).batchNumber === number,
56
+ ) as Record<string, unknown> | undefined;
57
+ if (
58
+ !batch ||
59
+ !Array.isArray(batch.paths) ||
60
+ !Array.isArray(batch.records) ||
61
+ batch.paths.length === 0 ||
62
+ batch.paths.length !== batch.records.length ||
63
+ batch.paths.some((value) => typeof value !== 'string') ||
64
+ batch.records.some((value) => typeof value !== 'string')
65
+ ) {
66
+ throw new Error(`${batchesFile}: batch ${number} has invalid exact paths or records.`);
67
+ }
68
+ const content = `${JSON.stringify({ batchNumber: number, reviewedFiles: batch.paths, reviewedRecords: batch.records }, null, 2)}\n`;
69
+ await gezel.artifacts.write(outFile, content);
70
+ gezel.output({ ok: true, outFile, files: batch.paths.length });
@@ -383,4 +383,6 @@ async function run(): Promise<Fields> {
383
383
  }
384
384
  }
385
385
 
386
- gezel.output(await run());
386
+ // Every declared output is stamped on every action, including inapplicable fields.
387
+ // The shared runner validates the complete contract before accepting a run.
388
+ gezel.output({ id: null, record: null, records: [], total: null, ...(await run()) });
@@ -0,0 +1,113 @@
1
+ import { type InferredInput, defineScript, gezel } from '@bendyline/gezel-sdk';
2
+
3
+ /** Compact scope evidence; the full manifest and batches remain gate inputs. */
4
+ export const meta = defineScript({
5
+ name: 'summarizePullRequestCorpus',
6
+ description:
7
+ 'Action: summarize a published PR corpus manifest and batch array into small scope metadata without sending every path and record to the model.',
8
+ kind: 'action',
9
+ inputs: {
10
+ manifestFile: {
11
+ type: 'string',
12
+ description: 'Exact artifact path of the PR file manifest.',
13
+ required: true,
14
+ },
15
+ batchesFile: {
16
+ type: 'string',
17
+ description: 'Artifact path of the runtime-published batch array.',
18
+ required: true,
19
+ },
20
+ outFile: {
21
+ type: 'string',
22
+ description: 'Artifact path of the compact scope summary.',
23
+ required: true,
24
+ },
25
+ },
26
+ outputs: {
27
+ ok: { type: 'boolean', description: 'True when scope metadata was written.' },
28
+ outFile: { type: 'string', description: 'Artifact path written.' },
29
+ files: { type: 'number', description: 'Changed-file count.' },
30
+ batches: { type: 'number', description: 'Review-batch count.' },
31
+ },
32
+ requires: ['artifacts.read', 'artifacts.write'],
33
+ } as const);
34
+
35
+ const input = gezel.input as InferredInput<typeof meta>;
36
+ function path(raw: string): string {
37
+ const value = raw
38
+ .replace(/\\+/g, '/')
39
+ .replace(/^\.?\/+/, '')
40
+ .replace(/^artifacts\/+/i, '')
41
+ .trim();
42
+ if (!value || value.split('/').includes('..'))
43
+ throw new Error('Expected a safe artifact-relative path.');
44
+ return value;
45
+ }
46
+ const manifestFile = path(input.manifestFile);
47
+ const batchesFile = path(input.batchesFile);
48
+ const outFile = path(input.outFile);
49
+ let manifest: unknown;
50
+ let batches: unknown;
51
+ try {
52
+ manifest = JSON.parse(await gezel.artifacts.read(manifestFile));
53
+ batches = JSON.parse(await gezel.artifacts.read(batchesFile));
54
+ } catch (error) {
55
+ throw new Error(
56
+ `Could not parse PR scope inputs: ${error instanceof Error ? error.message : String(error)}`,
57
+ );
58
+ }
59
+ if (
60
+ !manifest ||
61
+ typeof manifest !== 'object' ||
62
+ Array.isArray(manifest) ||
63
+ !Array.isArray(batches) ||
64
+ batches.length === 0
65
+ ) {
66
+ throw new Error('PR scope inputs must contain a manifest object and a non-empty batch array.');
67
+ }
68
+ const fields = manifest as Record<string, unknown>;
69
+ const totalFiles = fields.totalFiles;
70
+ const files = fields.files;
71
+ if (!Number.isSafeInteger(totalFiles) || !Array.isArray(files) || files.length !== totalFiles) {
72
+ throw new Error('PR manifest totalFiles does not match its file array.');
73
+ }
74
+ const ranges = batches.map((value, index) => {
75
+ if (!value || typeof value !== 'object' || Array.isArray(value))
76
+ throw new Error(`Batch ${index + 1} is not an object.`);
77
+ const batch = value as Record<string, unknown>;
78
+ if (
79
+ batch.batchNumber !== index + 1 ||
80
+ !Number.isSafeInteger(batch.start) ||
81
+ !Number.isSafeInteger(batch.end) ||
82
+ !Array.isArray(batch.paths)
83
+ ) {
84
+ throw new Error(`Batch ${index + 1} has invalid numbering or bounds.`);
85
+ }
86
+ return { number: index + 1, start: batch.start, end: batch.end, files: batch.paths.length };
87
+ });
88
+ const distribution = new Map<string, number>();
89
+ for (const value of files) {
90
+ if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
91
+ const changedPath = (value as Record<string, unknown>).path;
92
+ if (typeof changedPath !== 'string') continue;
93
+ const area = changedPath.split('/')[0] ?? '?';
94
+ distribution.set(area, (distribution.get(area) ?? 0) + 1);
95
+ }
96
+ const topAreas = [...distribution]
97
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
98
+ .slice(0, 10)
99
+ .map(([area, count]) => ({ area, count }));
100
+ const content = `${JSON.stringify(
101
+ {
102
+ manifestFile,
103
+ pullRequest: fields.pullRequest,
104
+ totalFiles,
105
+ batchCount: ranges.length,
106
+ ranges,
107
+ topAreas,
108
+ },
109
+ null,
110
+ 2,
111
+ )}\n`;
112
+ await gezel.artifacts.write(outFile, content);
113
+ gezel.output({ ok: true, outFile, files: totalFiles as number, batches: ranges.length });
@@ -0,0 +1,336 @@
1
+ import { type InferredInput, defineScript, gezel } from '@bendyline/gezel-sdk';
2
+
3
+ /** Compact, deterministic synthesis input from every gated PR-review shard. */
4
+ export const meta = defineScript({
5
+ name: 'summarizePullRequestObservations',
6
+ description:
7
+ 'Action: read every exact review-batch observations shard and publish a compact candidate index without copying all shard prose into the final reviewer prompt.',
8
+ kind: 'action',
9
+ inputs: {
10
+ batchesFile: {
11
+ type: 'string',
12
+ description: 'Exact artifact path of the published batch array.',
13
+ required: true,
14
+ },
15
+ shardDir: {
16
+ type: 'string',
17
+ description: 'Artifact directory containing observations-N.md shards.',
18
+ required: true,
19
+ },
20
+ outFile: {
21
+ type: 'string',
22
+ description: 'Artifact path of the compact synthesis index.',
23
+ required: true,
24
+ },
25
+ },
26
+ outputs: {
27
+ ok: { type: 'boolean', description: 'True when every shard was indexed.' },
28
+ outFile: { type: 'string', description: 'Artifact path written.' },
29
+ batches: { type: 'number', description: 'Number of observations shards indexed.' },
30
+ candidates: {
31
+ type: 'number',
32
+ description: 'Number of B-numbered findings candidates indexed.',
33
+ },
34
+ verificationCandidates: {
35
+ type: 'number',
36
+ description: 'Number of structured V-numbered cross-file candidates indexed.',
37
+ },
38
+ },
39
+ requires: ['artifacts.read', 'artifacts.write'],
40
+ } as const);
41
+
42
+ const input = gezel.input as InferredInput<typeof meta>;
43
+ function cleanPath(raw: string): string {
44
+ const value = raw
45
+ .replace(/\\+/g, '/')
46
+ .replace(/^\.?\/+/, '')
47
+ .replace(/^artifacts\/+/, '')
48
+ .replace(/\/+$/, '')
49
+ .trim();
50
+ if (!value || value.split('/').includes('..'))
51
+ throw new Error('Expected a safe artifact-relative path.');
52
+ return value;
53
+ }
54
+
55
+ const batchesFile = cleanPath(input.batchesFile);
56
+ const shardDir = cleanPath(input.shardDir);
57
+ const outFile = cleanPath(input.outFile);
58
+ const NON_ACTIONABLE_RE =
59
+ /\b(?:verified\s+ok|no\s+(?:defect|issue|finding|action\s+needed|functional\s+issue)|not\s+(?:a\s+bug|a\s+(?:functional|correctness)\s+defect|a\s+defect|introduced\s+by\s+this\s+patch|available\s+(?:in|for)\s+this\s+batch)|none\s+needed|acceptable(?:\s+as[- ]is)?|accept\s+as[- ]is|worth\s+noting|future\s+(?:optimization|hardening)|pre[- ]existing|functionally\s+harmless|intentional\s+limitation|needs?\s+(?:(?:central|cross[- ]file)\s+)?verification|requires?\s+(?:central\s+)?verification|central\s+verification|not\s+audited|implementation\s+(?:is\s+)?unknown|no\s+evidence\s+(?:of|that).{0,80}\bavailable|correct\s+(?:and\s+bounded\s+)?fallback|intent\s+is\s+correct|best[- ]effort|harmless\s+here|does\s+not\s+affect\s+runtime\s+behavior|finding\s+is\s+contingent|this\s+finding\s+is\s+contingent|risk\s+(?:is\s+)?low|may|might|could|potential(?:ly)?|possibly|likely|consider(?:ing)?|comment|documentation|documented|discoverability|verify\s+(?:that|the|whether)|verification\s+(?:of|whether)|(?:style|quoting|backslash)\s+(?:inconsistency|concern)|standardiz(?:e|ing)|if\s+.{0,160}\b(?:fails?|missing|empty|malformed|changes?|changed|removed|renamed|never|does\s+not|doesn't))\b/is;
60
+ const SHORTLIST_LIMIT = 8;
61
+ const UNKNOWN_SEVERITY_RANK = 3;
62
+ const SEVERITY_RANK: Record<string, number> = {
63
+ critical: 0,
64
+ major: 1,
65
+ minor: 2,
66
+ unknown: UNKNOWN_SEVERITY_RANK,
67
+ nit: 4,
68
+ };
69
+ function severityRank(severity: string): number {
70
+ return SEVERITY_RANK[severity] ?? UNKNOWN_SEVERITY_RANK;
71
+ }
72
+ const FINDING_START_RE = /^\s*(?:#{1,6}\s+|\*\*|[-*]\s+)?B(\d+)-(\d+)\b/i;
73
+ interface VerificationCandidate {
74
+ id: string;
75
+ path: string;
76
+ line: number;
77
+ severity: 'critical' | 'major' | 'minor' | 'nit';
78
+ claim: string;
79
+ verify: string;
80
+ batchNumber: number;
81
+ observationsFile: string;
82
+ }
83
+
84
+ function parseVerificationCandidates(
85
+ content: string,
86
+ batchNumber: number,
87
+ observationsFile: string,
88
+ ): VerificationCandidate[] {
89
+ const heading = /^#{1,6}\s+Verification candidates\s*$/im.exec(content);
90
+ // Older in-flight craftbook snapshots predate the structured channel.
91
+ // Their gates never promised one, so absence remains an empty list. New
92
+ // versions explicitly require the section in corpusBatchObservations.
93
+ if (!heading) return [];
94
+ const afterHeading = heading ? content.slice(heading.index + heading[0].length) : undefined;
95
+ const nextHeadingOffset = afterHeading?.search(/^#{1,6}\s+/m) ?? -1;
96
+ const section =
97
+ afterHeading === undefined
98
+ ? undefined
99
+ : nextHeadingOffset >= 0
100
+ ? afterHeading.slice(0, nextHeadingOffset)
101
+ : afterHeading;
102
+ const json = section ? /```json\s*([\s\S]*?)```/i.exec(section)?.[1] : undefined;
103
+ if (!json) throw new Error(`${observationsFile} lacks its verificationCandidates JSON block.`);
104
+ let parsed: unknown;
105
+ try {
106
+ parsed = JSON.parse(json);
107
+ } catch (error) {
108
+ throw new Error(
109
+ `${observationsFile} has invalid verificationCandidates JSON: ${error instanceof Error ? error.message : String(error)}`,
110
+ );
111
+ }
112
+ const raw =
113
+ parsed && typeof parsed === 'object' && !Array.isArray(parsed)
114
+ ? (parsed as Record<string, unknown>).verificationCandidates
115
+ : undefined;
116
+ if (!Array.isArray(raw)) {
117
+ throw new Error(`${observationsFile} verificationCandidates must be an array.`);
118
+ }
119
+ return raw.map((candidate, index) => {
120
+ if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
121
+ throw new Error(`${observationsFile} verificationCandidates[${index}] is invalid.`);
122
+ }
123
+ const fields = candidate as Record<string, unknown>;
124
+ return {
125
+ id: String(fields.id),
126
+ path: String(fields.path),
127
+ line: Number(fields.line),
128
+ severity: String(fields.severity) as VerificationCandidate['severity'],
129
+ claim: String(fields.claim),
130
+ verify: String(fields.verify),
131
+ batchNumber,
132
+ observationsFile,
133
+ };
134
+ });
135
+ }
136
+
137
+ function scopeRank(preview: string): number {
138
+ const path = /`([^`\n]+):\d+/.exec(preview)?.[1] ?? '';
139
+ if (
140
+ path.startsWith('evals/') ||
141
+ path.startsWith('scripts/') ||
142
+ path.startsWith('native/') ||
143
+ /(?:^|\/)(?:test|tests|fixtures)(?:\/|$)|\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path)
144
+ )
145
+ return 2;
146
+ if (/^packages\/[^/]+\/src\//.test(path)) return 0;
147
+ return 1;
148
+ }
149
+ let parsed: unknown;
150
+ try {
151
+ parsed = JSON.parse(await gezel.artifacts.read(batchesFile));
152
+ } catch (error) {
153
+ throw new Error(
154
+ `Could not read review batches: ${error instanceof Error ? error.message : String(error)}`,
155
+ );
156
+ }
157
+ if (!Array.isArray(parsed) || parsed.length === 0)
158
+ throw new Error('Review batches must be a non-empty array.');
159
+
160
+ const summaries = [];
161
+ const indexedCandidates: Array<{
162
+ id: string;
163
+ severity: string;
164
+ preview: string;
165
+ likelyNonIssue: boolean;
166
+ batchNumber: number;
167
+ observationsFile: string;
168
+ scopeRank: number;
169
+ }> = [];
170
+ const overflowCandidates: Array<{
171
+ id: string;
172
+ batchNumber: number;
173
+ observationsFile: string;
174
+ }> = [];
175
+ const verificationCandidates: VerificationCandidate[] = [];
176
+ let candidateCount = 0;
177
+ for (let index = 0; index < parsed.length; index++) {
178
+ const value = parsed[index];
179
+ if (!value || typeof value !== 'object' || Array.isArray(value))
180
+ throw new Error(`Batch ${index + 1} is not an object.`);
181
+ const batch = value as Record<string, unknown>;
182
+ if (
183
+ batch.batchNumber !== index + 1 ||
184
+ !Array.isArray(batch.paths) ||
185
+ batch.paths.length === 0 ||
186
+ batch.paths.some((path) => typeof path !== 'string')
187
+ ) {
188
+ throw new Error(`Batch ${index + 1} has invalid numbering or changed paths.`);
189
+ }
190
+ const number = index + 1;
191
+ const observationsFile = `${shardDir}/observations-${number}.md`;
192
+ let content: string;
193
+ try {
194
+ content = await gezel.artifacts.read(observationsFile);
195
+ } catch {
196
+ throw new Error(
197
+ `Missing exact observations shard ${observationsFile}; synthesis cannot use a subset.`,
198
+ );
199
+ }
200
+ const lines = content.split(/\r?\n/);
201
+ const headings = lines
202
+ .filter((line) => /^\s*#{1,6}\s+/.test(line))
203
+ .map((line) => line.replace(/^\s*#{1,6}\s+/, '').replace(/`/g, ''));
204
+ const missingPaths = (batch.paths as string[]).filter(
205
+ (path) => !headings.some((heading) => heading === path || heading.startsWith(`${path} `)),
206
+ );
207
+ if (missingPaths.length > 0)
208
+ throw new Error(
209
+ `${observationsFile} lacks path heading(s): ${missingPaths.slice(0, 5).join(', ')}`,
210
+ );
211
+ const batchVerificationCandidates = parseVerificationCandidates(
212
+ content,
213
+ number,
214
+ observationsFile,
215
+ );
216
+ verificationCandidates.push(...batchVerificationCandidates);
217
+ const candidates = [];
218
+ const overflow: string[] = [];
219
+ for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
220
+ const match = FINDING_START_RE.exec(lines[lineIndex]!);
221
+ if (!match) continue;
222
+ const id = `B${match[1]}-${match[2]}`;
223
+ const previewLines = [lines[lineIndex]!];
224
+ for (let next = lineIndex + 1; next < lines.length && previewLines.length < 20; next++) {
225
+ if (FINDING_START_RE.test(lines[next]!) || /^\s*#{1,4}\s+/.test(lines[next]!)) break;
226
+ previewLines.push(lines[next]!);
227
+ }
228
+ const fullPreview = previewLines.join('\n');
229
+ const severity =
230
+ /\[(critical|major|minor|nit)\]|\b\**severity\**\s*(?::|\||—|-)?\s*\**(critical|major|minor|nit)\b|(?:^|\|)\s*\**(critical|major|minor|nit)\**\s*(?:\||$)|\b(critical|major|minor|nit)\s*:|\((critical|major|minor|nit)\)|(?:—|-)\s*\**(critical|major|minor|nit)\**\s*(?:(?:—|-)|$)/im.exec(
231
+ fullPreview,
232
+ );
233
+ const normalizedSeverity = (
234
+ severity?.[1] ??
235
+ severity?.[2] ??
236
+ severity?.[3] ??
237
+ severity?.[4] ??
238
+ severity?.[5] ??
239
+ severity?.[6] ??
240
+ 'unknown'
241
+ ).toLowerCase();
242
+ const candidateScopeRank = scopeRank(fullPreview);
243
+ const likelyNonIssue =
244
+ NON_ACTIONABLE_RE.test(fullPreview) ||
245
+ (candidateScopeRank === 2 && !['critical', 'major'].includes(normalizedSeverity));
246
+ const preview = fullPreview.slice(0, likelyNonIssue ? 240 : 520);
247
+ if (candidates.length < 20) {
248
+ candidates.push({
249
+ id,
250
+ severity: normalizedSeverity,
251
+ preview,
252
+ likelyNonIssue,
253
+ });
254
+ indexedCandidates.push({
255
+ id,
256
+ severity: normalizedSeverity,
257
+ preview,
258
+ likelyNonIssue,
259
+ batchNumber: number,
260
+ observationsFile,
261
+ scopeRank: candidateScopeRank,
262
+ });
263
+ } else {
264
+ overflow.push(id);
265
+ overflowCandidates.push({ id, batchNumber: number, observationsFile });
266
+ }
267
+ }
268
+ candidateCount += candidates.length + overflow.length;
269
+ summaries.push({
270
+ batchNumber: number,
271
+ start: batch.start,
272
+ end: batch.end,
273
+ paths: batch.paths.length,
274
+ observationsFile,
275
+ bytes: new TextEncoder().encode(content).length,
276
+ candidateIds: candidates.map((candidate) => candidate.id),
277
+ nonActionableIds: candidates
278
+ .filter((candidate) => candidate.likelyNonIssue)
279
+ .map((candidate) => candidate.id),
280
+ overflow,
281
+ verificationCandidateIds: batchVerificationCandidates.map((candidate) => candidate.id),
282
+ });
283
+ }
284
+ const actionableCandidates = indexedCandidates
285
+ .filter((candidate) => !candidate.likelyNonIssue)
286
+ .sort(
287
+ (left, right) =>
288
+ severityRank(left.severity) - severityRank(right.severity) ||
289
+ left.scopeRank - right.scopeRank ||
290
+ left.batchNumber - right.batchNumber ||
291
+ left.id.localeCompare(right.id),
292
+ );
293
+ const shortlist = actionableCandidates.slice(0, SHORTLIST_LIMIT);
294
+ const omittedActionable = [
295
+ ...actionableCandidates.slice(SHORTLIST_LIMIT).map((candidate) => ({
296
+ id: candidate.id,
297
+ severity: candidate.severity,
298
+ batchNumber: candidate.batchNumber,
299
+ observationsFile: candidate.observationsFile,
300
+ })),
301
+ ...overflowCandidates.map((candidate) => ({ ...candidate, severity: 'unknown' })),
302
+ ];
303
+ verificationCandidates.sort(
304
+ (left, right) =>
305
+ severityRank(left.severity) - severityRank(right.severity) ||
306
+ left.batchNumber - right.batchNumber ||
307
+ left.id.localeCompare(right.id),
308
+ );
309
+ await gezel.artifacts.write(
310
+ outFile,
311
+ `${JSON.stringify(
312
+ {
313
+ schemaVersion: 2,
314
+ batchesFile,
315
+ batchCount: summaries.length,
316
+ candidateCount,
317
+ actionableCandidateCount: actionableCandidates.length + overflowCandidates.length,
318
+ nonActionableCandidateCount: indexedCandidates.filter((candidate) => candidate.likelyNonIssue)
319
+ .length,
320
+ shortlistLimit: SHORTLIST_LIMIT,
321
+ shortlist,
322
+ omittedActionable,
323
+ verificationCandidates,
324
+ batches: summaries,
325
+ },
326
+ null,
327
+ 2,
328
+ )}\n`,
329
+ );
330
+ gezel.output({
331
+ ok: true,
332
+ outFile,
333
+ batches: summaries.length,
334
+ candidates: candidateCount,
335
+ verificationCandidates: verificationCandidates.length,
336
+ });