crysk 0.3.2 → 0.4.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 (66) hide show
  1. package/README.md +52 -32
  2. package/dist/SKILL-12as0f3q.md +74 -0
  3. package/dist/SKILL-2h445snn.md +140 -0
  4. package/dist/SKILL-6vy283pt.md +140 -0
  5. package/dist/SKILL-dsnffnfp.md +140 -0
  6. package/dist/SKILL-ebn0fqaq.md +140 -0
  7. package/dist/SKILL-gnrbph72.md +140 -0
  8. package/dist/SKILL-kq0xejn3.md +553 -0
  9. package/dist/SKILL-qaqsbygw.md +66 -0
  10. package/dist/SKILL-vws0aqb8.md +553 -0
  11. package/dist/ci-admission-a6d0wk1c.md +128 -0
  12. package/dist/ci-admission-t0f5qwth.md +128 -0
  13. package/dist/cli.js +14567 -14177
  14. package/dist/index.js +270 -56
  15. package/dist/review-refuter-btpgnkcd.md +77 -0
  16. package/package.json +2 -2
  17. package/prompts/default/PROVENANCE.md +1 -0
  18. package/prompts/default/review-refuter.md +6 -0
  19. package/skills/crysk/SKILL.md +3 -3
  20. package/skills/crysk-ci-setup/SKILL.md +4 -4
  21. package/skills/crysk-ci-setup/references/ci-admission.md +2 -2
  22. package/skills/crysk-loop/SKILL.md +19 -8
  23. package/skills/crysk-pr/SKILL.md +1 -1
  24. package/src/assets.ts +2 -2
  25. package/src/ci/gates.ts +9 -6
  26. package/src/ci/outcome.ts +4 -4
  27. package/src/ci/platform-config.ts +127 -0
  28. package/src/ci/platform-report.ts +702 -0
  29. package/src/ci/platform.ts +449 -0
  30. package/src/ci/reporter.ts +9 -7
  31. package/src/ci/review-admission.ts +8 -4
  32. package/src/ci/setup.ts +112 -9
  33. package/src/commands/ci-setup.ts +21 -18
  34. package/src/commands/init.ts +21 -12
  35. package/src/compare/loop.ts +9 -1
  36. package/src/compare/martian-adapter.ts +1 -1
  37. package/src/doctor.ts +48 -29
  38. package/src/index.ts +1 -1
  39. package/src/menu-context.ts +1 -1
  40. package/src/pr/admission.ts +53 -11
  41. package/src/pr/ci-admission-gate.ts +2 -1
  42. package/src/pr/finding-state-record.ts +58 -0
  43. package/src/pr/gate-record.ts +22 -0
  44. package/src/pr/inline.ts +3 -0
  45. package/src/pr/posting.ts +4 -0
  46. package/src/pr/pr-status.ts +27 -7
  47. package/src/pr/pr.ts +39 -8
  48. package/src/pr/preflight.ts +43 -1
  49. package/src/pr/publish-outcome.ts +10 -2
  50. package/src/pr/review-pr.ts +5 -3
  51. package/src/pr/target.ts +16 -3
  52. package/src/rereview/classify.ts +4 -0
  53. package/src/rereview/prepare.ts +47 -22
  54. package/src/rereview/state.ts +34 -8
  55. package/src/review/boundary.ts +2 -1
  56. package/src/review/materiality-gate.ts +25 -1
  57. package/src/review/pipeline.ts +60 -15
  58. package/src/review/preflight.ts +132 -28
  59. package/src/review/prompt-set.ts +12 -8
  60. package/src/review/report.ts +34 -14
  61. package/src/review/review.ts +14 -5
  62. package/src/review/run.ts +54 -18
  63. package/src/security/published-text.ts +161 -0
  64. package/src/triage/triage.ts +2 -1
  65. package/src/updater.ts +1 -1
  66. package/src/wizard.ts +35 -9
@@ -0,0 +1,702 @@
1
+ // The action's report step: tell the Crysk platform how a run ended, so every
2
+ // run is recorded (#157) with its cost attributed (#139), then hand it the
3
+ // run's findings so the dashboard can show them.
4
+ //
5
+ // It runs only in platform mode (action.yml gates the step on
6
+ // `workflow_dispatch`, a non-empty `dispatch-id` and a run token being present),
7
+ // after the publish step. Standalone use never reaches it.
8
+ //
9
+ // WHY THE REPORT IS METADATA ONLY: the body carries counts, token totals,
10
+ // costs, model names and shas. It never carries a finding, a claim, a summary,
11
+ // a hop trail or any other text that can quote the customer's code. The
12
+ // builder below COPIES the numeric fields it names out of the run directory
13
+ // instead of forwarding a document, so a field added to findings.json tomorrow
14
+ // cannot leak by default.
15
+ //
16
+ // WHY THE FINDINGS GO SEPARATELY: they are the part that can quote customer
17
+ // code, so they travel in their own request to /runs/findings. The platform
18
+ // encrypts them and honors each repository's metadata-only mode on its side,
19
+ // but a metadata_only repository's code must never leave the runner at all:
20
+ // the action reads `data_mode` from the same token exchange as the run token
21
+ // (CRYSK_DATA_MODE) and, unless it is exactly `full`, this script reduces each
22
+ // finding to non-text fields (METADATA_ONLY_FINDING_FIELDS below). The body is
23
+ // exactly `{ schema_version, findings }`: the `findings` array as the engine
24
+ // wrote it (in `full` mode), never the document's `debug` arrays or its
25
+ // summary prose. It is sent only after the
26
+ // report succeeded (the report creates the run the findings attach to), and
27
+ // never for a run with no findings.json or zero findings.
28
+ //
29
+ // WHY it never fails the job: the review already succeeded or failed on its own
30
+ // merits and its outcome is posted. A platform that is down, a revoked token or
31
+ // a rejected field is reported as a `::warning::` with the HTTP status and the
32
+ // API's message, never a token, and the step exits 0. A findings upload that
33
+ // fails is a warning too, never a red job.
34
+ //
35
+ // WHY the base URL is the constant from ./platform and never an input: the run
36
+ // token goes to that URL (see platform.ts).
37
+ //
38
+ // WHY the run directory is read here: the report must also say what a review
39
+ // that wrote nothing did (skipped, size-gated, failed before writing), so a
40
+ // missing or unreadable directory is the zero report, not an error. The
41
+ // `run_dir` output is empty for a run where every hunter died, a fatal error
42
+ // and a cancelled job (action.yml "KNOWN GAP"), so those report zero counts
43
+ // even when a findings.json was written.
44
+ //
45
+ // RUNS BEFORE NO INSTALL, like publish: every import is a builtin or a module
46
+ // whose own import closure is package-free. test/ci/platform-report.test.ts
47
+ // walks that closure, so a package import added anywhere in it fails a test
48
+ // instead of failing the job at module load.
49
+
50
+ import { readFileSync } from "node:fs";
51
+ import path from "node:path";
52
+ import {
53
+ FINDING_STATE_FILE,
54
+ type FindingStateRecord,
55
+ } from "../pr/finding-state-record";
56
+ import { GATE_RECORD_FILE } from "../pr/gate-record";
57
+ import type { FindingsDocument } from "../review/findings";
58
+ import { validateFindingsDocument } from "../review/findings";
59
+ import { PLATFORM_API_URL, type PlatformDataMode } from "./platform";
60
+
61
+ // The platform caps `agents` at 64 entries.
62
+ const MAX_AGENTS = 64;
63
+
64
+ // The platform accepts at most 500 findings per run. The first 500 in the
65
+ // engine's order go out and the rest are named in a warning.
66
+ const MAX_FINDINGS = 500;
67
+
68
+ // Long enough for a slow API, short enough that a hung endpoint cannot hold the
69
+ // job's tail.
70
+ const REQUEST_TIMEOUT_MS = 30_000;
71
+
72
+ const SHA = /^[0-9a-f]{40}$/;
73
+
74
+ export interface RunReportAgent {
75
+ agent_key: string;
76
+ model?: string;
77
+ tokens_in: number;
78
+ tokens_out: number;
79
+ cost_usd: number;
80
+ duration_ms?: number;
81
+ attempts?: number;
82
+ status?: string;
83
+ }
84
+
85
+ export interface RunReportBody {
86
+ outcome: string;
87
+ pr_number: number;
88
+ head_sha: string;
89
+ base_sha?: string | null;
90
+ run_status?: string;
91
+ schema_version?: string;
92
+ engine_version?: string;
93
+ model?: string;
94
+ // `blocking` and `advisory` are this run's findings. `unresolved_blocking` is what the gate decides on,
95
+ // earlier findings still open included; absent when the run recorded none.
96
+ // `refuted_by_hunter` counts what the refuter removed, which never reaches `findings[]`.
97
+ counts: {
98
+ blocking: number;
99
+ advisory: number;
100
+ unresolved_blocking?: number;
101
+ refuted_by_hunter?: Record<string, number>;
102
+ };
103
+ usage: {
104
+ tokens_in: number;
105
+ tokens_out: number;
106
+ cost_usd: number;
107
+ cost_is_floor?: boolean;
108
+ wall_ms?: number;
109
+ index_ms?: number;
110
+ sync_ms?: number;
111
+ };
112
+ agents: RunReportAgent[];
113
+ // Which findings stay open, under ids that last across runs. Absent when the run recorded none.
114
+ finding_states?: FindingStateRecord;
115
+ }
116
+
117
+ // What the builder knows about the run directory. Either part is absent when
118
+ // the file is missing or unreadable.
119
+ export interface RunDirFacts {
120
+ findings?: unknown;
121
+ pipeline?: unknown;
122
+ gate?: unknown;
123
+ findingStates?: unknown;
124
+ }
125
+
126
+ export interface BuildRunReportInput {
127
+ // The action's `status` output for this run. Empty when the CLI never wrote
128
+ // one (a failure before it started); reported as `error`.
129
+ outcome: string;
130
+ prNumber: number;
131
+ // The trigger's resolved head, the fallback when no findings were written.
132
+ triggerHeadSha: string;
133
+ run: RunDirFacts;
134
+ }
135
+
136
+ // null when the run has no usable head: the platform requires a 40-hex sha, so
137
+ // a report without one cannot be sent.
138
+ export function buildRunReport(
139
+ input: BuildRunReportInput,
140
+ ): RunReportBody | null {
141
+ let doc: FindingsDocument | undefined;
142
+ if (input.run.findings !== undefined) {
143
+ try {
144
+ doc = validateFindingsDocument(input.run.findings);
145
+ } catch {
146
+ // An unreadable document is a run that wrote nothing usable.
147
+ doc = undefined;
148
+ }
149
+ }
150
+
151
+ const headSha = [doc?.head_sha, input.triggerHeadSha].find(
152
+ (sha): sha is string => typeof sha === "string" && SHA.test(sha),
153
+ );
154
+ if (headSha === undefined) return null;
155
+
156
+ if (doc === undefined) {
157
+ return {
158
+ outcome: input.outcome === "" ? "error" : input.outcome,
159
+ pr_number: input.prNumber,
160
+ head_sha: headSha,
161
+ counts: { blocking: 0, advisory: 0 },
162
+ usage: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
163
+ agents: [],
164
+ };
165
+ }
166
+
167
+ const telemetry = doc.telemetry;
168
+ let blocking = 0;
169
+ let advisory = 0;
170
+ for (const finding of doc.findings) {
171
+ if (finding.tier === "blocking") blocking += 1;
172
+ else if (finding.tier === "advisory") advisory += 1;
173
+ }
174
+
175
+ return {
176
+ outcome: input.outcome === "" ? "error" : input.outcome,
177
+ pr_number: input.prNumber,
178
+ head_sha: headSha,
179
+ ...(typeof doc.base_sha === "string" && SHA.test(doc.base_sha)
180
+ ? { base_sha: doc.base_sha }
181
+ : {}),
182
+ run_status: doc.run_status,
183
+ schema_version: doc.schema_version,
184
+ ...(doc.engine === undefined ? {} : { engine_version: doc.engine.version }),
185
+ ...(typeof doc.model === "string" && doc.model !== ""
186
+ ? { model: doc.model }
187
+ : {}),
188
+ counts: {
189
+ blocking,
190
+ advisory,
191
+ ...gateCount(input.run.gate),
192
+ refuted_by_hunter: refutedByHunter(doc),
193
+ },
194
+ usage: {
195
+ tokens_in: count(telemetry.tokens_in),
196
+ tokens_out: count(telemetry.tokens_out),
197
+ cost_usd: cost(telemetry.cost_usd_est),
198
+ ...(telemetry.cost_usd_est_is_floor === true
199
+ ? { cost_is_floor: true }
200
+ : {}),
201
+ wall_ms: count(telemetry.wall_ms),
202
+ // Zero means no index was built, so there is no time to report.
203
+ ...(count(telemetry.index_ms) > 0
204
+ ? { index_ms: count(telemetry.index_ms) }
205
+ : {}),
206
+ ...(telemetry.sync_ms === undefined
207
+ ? {}
208
+ : { sync_ms: count(telemetry.sync_ms) }),
209
+ },
210
+ agents: buildAgents(doc, input.run.pipeline),
211
+ ...findingStates(input.run.findingStates),
212
+ };
213
+ }
214
+
215
+ // The file is the run's own, but this goes off the runner, in metadata-only mode too: only the known
216
+ // fields of the known shapes pass, so a future field that quotes code cannot ride along. Rows past the
217
+ // cap count as dropped, so the platform says it does not know instead of reading them as resolved.
218
+ const STABLE_ID = /^R\d{3,}$/;
219
+ const FINDING_ID = /^[A-Za-z0-9_.-]{1,64}$/;
220
+ const OPEN_STATUSES = new Set([
221
+ "carried",
222
+ "unconfirmed",
223
+ "suppressed",
224
+ "deferred",
225
+ ]);
226
+ const TIERS = new Set(["blocking", "advisory", "unrecoverable"]);
227
+ const MAX_FINDING_STATES = 500;
228
+
229
+ function findingStates(record: unknown): {
230
+ finding_states?: FindingStateRecord;
231
+ } {
232
+ if (typeof record !== "object" || record === null) return {};
233
+ const { open, fresh, resolved, superseded, dropped } = record as Record<
234
+ string,
235
+ unknown
236
+ >;
237
+ if (
238
+ !Array.isArray(open) ||
239
+ typeof fresh !== "object" ||
240
+ fresh === null ||
241
+ Array.isArray(fresh) ||
242
+ !Array.isArray(resolved) ||
243
+ typeof dropped !== "number" ||
244
+ !Number.isInteger(dropped) ||
245
+ dropped < 0
246
+ ) {
247
+ return {};
248
+ }
249
+ const rows = open.flatMap((row): FindingStateRecord["open"] => {
250
+ const { id, status, tier } = (row ?? {}) as Record<string, unknown>;
251
+ return typeof id === "string" &&
252
+ STABLE_ID.test(id) &&
253
+ typeof status === "string" &&
254
+ OPEN_STATUSES.has(status) &&
255
+ typeof tier === "string" &&
256
+ TIERS.has(tier)
257
+ ? [{ id, status, tier }]
258
+ : [];
259
+ });
260
+ return {
261
+ finding_states: {
262
+ open: rows.slice(0, MAX_FINDING_STATES),
263
+ fresh: Object.fromEntries(
264
+ Object.entries(fresh as Record<string, unknown>)
265
+ .filter(
266
+ (entry): entry is [string, string] =>
267
+ FINDING_ID.test(entry[0]) &&
268
+ typeof entry[1] === "string" &&
269
+ STABLE_ID.test(entry[1]),
270
+ )
271
+ .slice(0, MAX_FINDING_STATES),
272
+ ),
273
+ resolved: resolved
274
+ .filter(
275
+ (id): id is string => typeof id === "string" && STABLE_ID.test(id),
276
+ )
277
+ .slice(0, MAX_FINDING_STATES),
278
+ superseded: (Array.isArray(superseded) ? superseded : [])
279
+ .filter(
280
+ (id): id is string => typeof id === "string" && STABLE_ID.test(id),
281
+ )
282
+ .slice(0, MAX_FINDING_STATES),
283
+ dropped: dropped + Math.max(0, rows.length - MAX_FINDING_STATES),
284
+ },
285
+ };
286
+ }
287
+
288
+ // Counts only, and only a plain name: this goes off the runner in metadata-only mode too, and a refuted
289
+ // finding's claim can quote the customer's code.
290
+ function refutedByHunter(doc: FindingsDocument): Record<string, number> {
291
+ // A Map, so a hunter named like an object's own property counts like any other.
292
+ const counts = new Map<string, number>();
293
+ for (const finding of doc.debug.refuted as unknown[]) {
294
+ const name = (finding as { hunter?: unknown } | null | undefined)?.hunter;
295
+ const hunter =
296
+ typeof name === "string" && FINDING_ID.test(name) ? name : "unknown";
297
+ counts.set(hunter, (counts.get(hunter) ?? 0) + 1);
298
+ }
299
+ return Object.fromEntries(counts);
300
+ }
301
+
302
+ function gateCount(gate: unknown): { unresolved_blocking?: number } {
303
+ const value = (gate as { unresolved_blocking?: unknown } | null | undefined)
304
+ ?.unresolved_blocking;
305
+ return typeof value === "number" && Number.isInteger(value) && value >= 0
306
+ ? { unresolved_blocking: value }
307
+ : {};
308
+ }
309
+
310
+ function count(value: unknown): number {
311
+ return typeof value === "number" && Number.isFinite(value) && value > 0
312
+ ? Math.round(value)
313
+ : 0;
314
+ }
315
+
316
+ function cost(value: unknown): number {
317
+ return typeof value === "number" && Number.isFinite(value) && value > 0
318
+ ? value
319
+ : 0;
320
+ }
321
+
322
+ // `telemetry.per_agent` is declared with the lab-shared minimum (tokens_total +
323
+ // duration_ms) but this engine writes the richer PerAgentUsage, so each field
324
+ // is read through a runtime check, as review/report.ts does. `detail` is never
325
+ // copied: it is the provider's own words and can echo prompt text.
326
+ function buildAgents(
327
+ doc: FindingsDocument,
328
+ pipeline: unknown,
329
+ ): RunReportAgent[] {
330
+ const models = stepModels(pipeline);
331
+ const perAgent = doc.telemetry.per_agent ?? {};
332
+ // validateFindingsDocument only checks that `telemetry` is an object, so a
333
+ // row that is not one is skipped instead of read.
334
+ return Object.entries(perAgent as Record<string, unknown>)
335
+ .filter(
336
+ (entry): entry is [string, Record<string, unknown>] =>
337
+ typeof entry[1] === "object" &&
338
+ entry[1] !== null &&
339
+ !Array.isArray(entry[1]),
340
+ )
341
+ .slice(0, MAX_AGENTS)
342
+ .map(([key, row]) => {
343
+ const model = modelOf(models, key);
344
+ return {
345
+ agent_key: key,
346
+ ...(model === undefined ? {} : { model }),
347
+ tokens_in: count(row.tokens_in),
348
+ tokens_out: count(row.tokens_out),
349
+ cost_usd: cost(row.cost_usd_est),
350
+ duration_ms: count(row.duration_ms),
351
+ ...(typeof row.attempts === "number" && row.attempts > 0
352
+ ? { attempts: count(row.attempts) }
353
+ : {}),
354
+ ...(typeof row.status === "string" ? { status: row.status } : {}),
355
+ };
356
+ });
357
+ }
358
+
359
+ // pipeline.json's `steps[]` rows are `{ name, model, ... }`.
360
+ function stepModels(pipeline: unknown): Array<{ name: string; model: string }> {
361
+ if (typeof pipeline !== "object" || pipeline === null) return [];
362
+ const steps = (pipeline as { steps?: unknown }).steps;
363
+ if (!Array.isArray(steps)) return [];
364
+ const rows: Array<{ name: string; model: string }> = [];
365
+ for (const step of steps) {
366
+ if (typeof step !== "object" || step === null) continue;
367
+ const { name, model } = step as { name?: unknown; model?: unknown };
368
+ if (typeof name === "string" && typeof model === "string" && model !== "") {
369
+ rows.push({ name, model });
370
+ }
371
+ }
372
+ return rows;
373
+ }
374
+
375
+ // A hunter's step is `hunter-<key>`; a refuter, verifier or adjudicator fans
376
+ // out one step per finding (`refuter-F001`) under one `per_agent` row. Three
377
+ // rows are keyed by something other than their steps' name: the summary row's
378
+ // step is `summarizer`, the verifier's are `verify-<id>` and the adjudicator's
379
+ // are `adjudicate-<id>` (pipeline.ts, rereview/verify.ts). Without the alias
380
+ // those rows would go out with no model.
381
+ const STEP_NAME_ALIASES: Readonly<Record<string, string>> = {
382
+ summary: "summarizer",
383
+ verifier: "verify",
384
+ adjudicator: "adjudicate",
385
+ };
386
+
387
+ function modelOf(
388
+ steps: ReadonlyArray<{ name: string; model: string }>,
389
+ key: string,
390
+ ): string | undefined {
391
+ const stem = STEP_NAME_ALIASES[key] ?? key;
392
+ return steps.find(
393
+ (step) =>
394
+ step.name === key ||
395
+ step.name === stem ||
396
+ step.name === `hunter-${key}` ||
397
+ step.name.startsWith(`${stem}-`),
398
+ )?.model;
399
+ }
400
+
401
+ // Reads findings.json and pipeline.json from a run directory. A missing or
402
+ // unparseable file is simply absent.
403
+ export function readRunDir(
404
+ runDir: string,
405
+ readText: (file: string) => string = (file) => readFileSync(file, "utf8"),
406
+ ): RunDirFacts {
407
+ const facts: RunDirFacts = {};
408
+ if (runDir === "") return facts;
409
+ for (const [key, file] of [
410
+ ["findings", "findings.json"],
411
+ ["pipeline", "pipeline.json"],
412
+ ["gate", GATE_RECORD_FILE],
413
+ ["findingStates", FINDING_STATE_FILE],
414
+ ] as const) {
415
+ try {
416
+ facts[key] = JSON.parse(readText(path.join(runDir, file)));
417
+ } catch {
418
+ // absent or malformed: see above
419
+ }
420
+ }
421
+ return facts;
422
+ }
423
+
424
+ export type SendReportResult =
425
+ | { ok: true; recorded: boolean; runId?: string }
426
+ // `message` names the HTTP status and the API's own `message`. It never
427
+ // carries the token.
428
+ | { ok: false; message: string };
429
+
430
+ export interface SendReportDeps {
431
+ fetch: typeof fetch;
432
+ baseUrl: string;
433
+ runToken: string;
434
+ }
435
+
436
+ type PostResult =
437
+ | { ok: true; reply: Record<string, unknown> }
438
+ | { ok: false; message: string };
439
+
440
+ // One authenticated JSON POST to the platform. Every failure, whether an HTTP
441
+ // status or a transport error, comes back as a message that never carries the
442
+ // token.
443
+ async function postJson(
444
+ deps: SendReportDeps,
445
+ endpoint: string,
446
+ body: unknown,
447
+ ): Promise<PostResult> {
448
+ try {
449
+ const response = await deps.fetch(`${deps.baseUrl}${endpoint}`, {
450
+ method: "POST",
451
+ headers: {
452
+ Authorization: `Bearer ${deps.runToken}`,
453
+ "Content-Type": "application/json",
454
+ },
455
+ body: JSON.stringify(body),
456
+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
457
+ });
458
+ if (!response.ok) {
459
+ const message = await apiMessage(response);
460
+ return {
461
+ ok: false,
462
+ message: `HTTP ${response.status}${message === undefined ? "" : ` — ${message}`}`,
463
+ };
464
+ }
465
+ const parsed: unknown = await response.json().catch(() => ({}));
466
+ return {
467
+ ok: true,
468
+ reply: typeof parsed === "object" && parsed !== null ? { ...parsed } : {},
469
+ };
470
+ } catch (error) {
471
+ const detail = error instanceof Error ? error.message : String(error);
472
+ return {
473
+ ok: false,
474
+ message: `the request could not complete: ${detail.split(deps.runToken).join("***")}`,
475
+ };
476
+ }
477
+ }
478
+
479
+ export async function sendRunReport(
480
+ deps: SendReportDeps,
481
+ body: RunReportBody,
482
+ ): Promise<SendReportResult> {
483
+ const result = await postJson(deps, "/runs/report", body);
484
+ if (!result.ok) return result;
485
+ // recorded=false is a repeat of the same run attempt: a success.
486
+ const { reply } = result;
487
+ return {
488
+ ok: true,
489
+ recorded: reply.recorded !== false,
490
+ ...(typeof reply.run_id === "string" ? { runId: reply.run_id } : {}),
491
+ };
492
+ }
493
+
494
+ export interface FindingsUploadBody {
495
+ schema_version: string;
496
+ // Each object exactly as the engine wrote it into findings.json.
497
+ findings: unknown[];
498
+ }
499
+
500
+ export interface FindingsUpload {
501
+ body: FindingsUploadBody;
502
+ // Findings beyond MAX_FINDINGS that were left out of the body.
503
+ dropped: number;
504
+ }
505
+
506
+ // The only fields of a finding a metadata_only repository's upload carries: ids,
507
+ // locations, enum-like labels and counters. NEVER the claim, proof_refs,
508
+ // hop_trail, symbol, dedupe_key or materiality (all can quote the code), and
509
+ // NEVER a key this list does not name, so a field added to the engine
510
+ // tomorrow stays on the runner by default.
511
+ const METADATA_ONLY_FINDING_FIELDS = [
512
+ "id",
513
+ "category",
514
+ "path",
515
+ "line",
516
+ "severity",
517
+ "tier",
518
+ "hunter",
519
+ "evidence_class",
520
+ "refuter_verdict",
521
+ "causal_disposition",
522
+ "root_cause_id",
523
+ "hops_used",
524
+ ] as const;
525
+
526
+ function metadataOnlyFinding(finding: unknown): Record<string, unknown> {
527
+ const kept: Record<string, unknown> = {};
528
+ if (typeof finding !== "object" || finding === null) return kept;
529
+ for (const field of METADATA_ONLY_FINDING_FIELDS) {
530
+ const value: unknown = Reflect.get(finding, field);
531
+ // Scalars only: a structure under an allowlisted name is not the field the
532
+ // platform expects and could hold text.
533
+ if (
534
+ typeof value === "string" ||
535
+ typeof value === "number" ||
536
+ typeof value === "boolean"
537
+ ) {
538
+ kept[field] = value;
539
+ }
540
+ }
541
+ return kept;
542
+ }
543
+
544
+ // null when there is nothing to upload: no findings.json, one this engine
545
+ // cannot read, or zero findings. The document is validated only to know it is
546
+ // one; in `full` mode the objects sent are the raw parsed ones, so a field the
547
+ // validator does not model still reaches the platform untouched. In
548
+ // `metadata_only` mode each is reduced to METADATA_ONLY_FINDING_FIELDS.
549
+ export function buildFindingsUpload(
550
+ document: unknown,
551
+ dataMode: PlatformDataMode,
552
+ ): FindingsUpload | null {
553
+ let doc: FindingsDocument;
554
+ try {
555
+ doc = validateFindingsDocument(document);
556
+ } catch {
557
+ return null;
558
+ }
559
+ if (typeof document !== "object" || document === null) return null;
560
+ const raw = "findings" in document ? document.findings : undefined;
561
+ if (!Array.isArray(raw) || raw.length === 0) return null;
562
+ const sent: unknown[] = raw.slice(0, MAX_FINDINGS);
563
+ return {
564
+ body: {
565
+ schema_version: doc.schema_version,
566
+ findings: dataMode === "full" ? sent : sent.map(metadataOnlyFinding),
567
+ },
568
+ dropped: Math.max(0, raw.length - MAX_FINDINGS),
569
+ };
570
+ }
571
+
572
+ export type SendFindingsResult =
573
+ | {
574
+ ok: true;
575
+ stored: number;
576
+ recorded: boolean;
577
+ mode: "full" | "metadata_only" | undefined;
578
+ }
579
+ // Same message contract as SendReportResult.
580
+ | { ok: false; message: string };
581
+
582
+ export async function sendRunFindings(
583
+ deps: SendReportDeps,
584
+ body: FindingsUploadBody,
585
+ ): Promise<SendFindingsResult> {
586
+ const result = await postJson(deps, "/runs/findings", body);
587
+ if (!result.ok) return result;
588
+ const { reply } = result;
589
+ return {
590
+ ok: true,
591
+ stored: typeof reply.stored === "number" ? reply.stored : 0,
592
+ // recorded=false is a repeat of the same upload: a success.
593
+ recorded: reply.recorded !== false,
594
+ mode:
595
+ reply.mode === "full" || reply.mode === "metadata_only"
596
+ ? reply.mode
597
+ : undefined,
598
+ };
599
+ }
600
+
601
+ async function apiMessage(response: Response): Promise<string | undefined> {
602
+ try {
603
+ const parsed = (await response.json()) as { message?: unknown };
604
+ return typeof parsed.message === "string" && parsed.message !== ""
605
+ ? parsed.message
606
+ : undefined;
607
+ } catch {
608
+ return undefined;
609
+ }
610
+ }
611
+
612
+ function escapeCommandData(text: string): string {
613
+ return text.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
614
+ }
615
+
616
+ export interface RunReportStepDeps {
617
+ fetch: typeof fetch;
618
+ env: Record<string, string | undefined>;
619
+ baseUrl: string;
620
+ readText?: (file: string) => string;
621
+ stdout: (text: string) => void;
622
+ }
623
+
624
+ // The step's shell. ALWAYS 0: see the header.
625
+ export async function runReportStep(deps: RunReportStepDeps): Promise<number> {
626
+ const runToken = deps.env.CRYSK_RUN_TOKEN ?? "";
627
+ const warn = (message: string): void =>
628
+ deps.stdout(
629
+ `::warning title=crysk::${escapeCommandData(`Crysk run report not recorded: ${message}`)}\n`,
630
+ );
631
+ const warnFindings = (message: string): void =>
632
+ deps.stdout(
633
+ `::warning title=crysk::${escapeCommandData(`Crysk findings not uploaded: ${message}`)}\n`,
634
+ );
635
+ // The whole step, not only the request: a run directory this engine wrote is
636
+ // read and shaped here too, and a throw from either must still be a warning.
637
+ try {
638
+ if (runToken === "") {
639
+ warn("no run token reached this step.");
640
+ return 0;
641
+ }
642
+ const prNumber = Number(deps.env.TRIGGER_PR ?? "");
643
+ if (!Number.isInteger(prNumber) || prNumber <= 0) {
644
+ warn("the run resolved no pull request number.");
645
+ return 0;
646
+ }
647
+ const run = readRunDir(deps.env.CRYSK_RUN_DIR ?? "", deps.readText);
648
+ const body = buildRunReport({
649
+ outcome: deps.env.CRYSK_OUTCOME ?? "",
650
+ prNumber,
651
+ triggerHeadSha: deps.env.TRIGGER_HEAD_SHA ?? "",
652
+ run,
653
+ });
654
+ if (body === null) {
655
+ warn("the run resolved no head sha.");
656
+ return 0;
657
+ }
658
+ const platform = { fetch: deps.fetch, baseUrl: deps.baseUrl, runToken };
659
+ const result = await sendRunReport(platform, body);
660
+ if (!result.ok) {
661
+ warn(result.message);
662
+ return 0;
663
+ }
664
+ // Only a recorded run has somewhere for findings to attach (409 otherwise).
665
+ try {
666
+ const upload = buildFindingsUpload(
667
+ run.findings,
668
+ deps.env.CRYSK_DATA_MODE === "full" ? "full" : "metadata_only",
669
+ );
670
+ if (upload === null) return 0;
671
+ if (upload.dropped > 0) {
672
+ warnFindings(
673
+ `only the first ${MAX_FINDINGS} findings are uploaded; ${upload.dropped} more were dropped.`,
674
+ );
675
+ }
676
+ const sent = await sendRunFindings(platform, upload.body);
677
+ if (!sent.ok) warnFindings(sent.message);
678
+ } catch (error) {
679
+ const detail = error instanceof Error ? error.message : String(error);
680
+ warnFindings(
681
+ `the findings could not be sent: ${detail.split(runToken).join("***")}`,
682
+ );
683
+ }
684
+ } catch (error) {
685
+ const detail = error instanceof Error ? error.message : String(error);
686
+ warn(
687
+ `the report could not be built: ${detail.split(runToken).join("***")}`,
688
+ );
689
+ }
690
+ return 0;
691
+ }
692
+
693
+ if (import.meta.main) {
694
+ process.exit(
695
+ await runReportStep({
696
+ fetch,
697
+ env: process.env,
698
+ baseUrl: PLATFORM_API_URL,
699
+ stdout: (text) => process.stdout.write(text),
700
+ }),
701
+ );
702
+ }