actions-warden 0.3.0 → 0.6.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 (78) hide show
  1. package/AGENTS.md +60 -12
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +180 -58
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +23 -8
  6. package/docs/AI-AGENTS.md +125 -29
  7. package/docs/CLI.md +346 -69
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +114 -18
  10. package/docs/GITHUB-ACTION.md +163 -29
  11. package/docs/JAVASCRIPT-API.md +177 -11
  12. package/docs/OUTPUTS.md +408 -40
  13. package/docs/README.md +1 -1
  14. package/examples/README.md +21 -0
  15. package/examples/baseline-adoption/README.md +79 -0
  16. package/examples/baseline-adoption/github-actions.yml +56 -0
  17. package/examples/baseline-adoption/policy.yml +7 -0
  18. package/examples/ci-violation-reporting/README.md +82 -0
  19. package/examples/ci-violation-reporting/github-actions.yml +55 -0
  20. package/examples/ci-violation-reporting/policy.yml +7 -0
  21. package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
  22. package/examples/csv-reporting/README.md +50 -0
  23. package/examples/csv-reporting/github-actions.yml +59 -0
  24. package/examples/html-organization-report/README.md +35 -0
  25. package/examples/html-organization-report/github-actions.yml +61 -0
  26. package/examples/notifications/README.md +67 -0
  27. package/examples/notifications/github-actions.yml +163 -0
  28. package/examples/org-scan.yml +24 -5
  29. package/examples/sarif-code-scanning/README.md +42 -0
  30. package/examples/sarif-code-scanning/github-actions.yml +66 -0
  31. package/examples/upgrade-pr.yml +1 -1
  32. package/llms.txt +14 -5
  33. package/package.json +8 -4
  34. package/skills/actions-warden/SKILL.md +91 -39
  35. package/src/action.js +353 -187
  36. package/src/cli.js +416 -209
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +452 -286
  39. package/src/commands/pin.js +9 -5
  40. package/src/commands/report.js +7 -2
  41. package/src/commands/upgrade.js +9 -5
  42. package/src/commands/verify.js +24 -4
  43. package/src/index.js +5 -1
  44. package/src/lib/action-summary.js +656 -0
  45. package/src/lib/annotations.js +4 -6
  46. package/src/lib/baseline.js +11 -1
  47. package/src/lib/config.js +10 -5
  48. package/src/lib/destination.js +98 -0
  49. package/src/lib/execution.js +5 -1
  50. package/src/lib/formats/csv.js +125 -0
  51. package/src/lib/formats/html.js +394 -0
  52. package/src/lib/formats/json.js +17 -0
  53. package/src/lib/formats/sarif.js +229 -0
  54. package/src/lib/formats/text.js +30 -0
  55. package/src/lib/formats/toon.js +50 -0
  56. package/src/lib/formatter.js +25 -192
  57. package/src/lib/github-org.js +208 -102
  58. package/src/lib/org-artifacts.js +211 -0
  59. package/src/lib/org-checkpoint.js +159 -35
  60. package/src/lib/org-progress.js +182 -4
  61. package/src/lib/org-report-comparison.js +505 -0
  62. package/src/lib/org-report-directory.js +251 -0
  63. package/src/lib/org-report.js +223 -0
  64. package/src/lib/org-run.js +305 -0
  65. package/src/lib/org-schema.js +89 -0
  66. package/src/lib/org-source-links.js +39 -0
  67. package/src/lib/parser.js +5 -0
  68. package/src/lib/path-equality.js +30 -0
  69. package/src/lib/paths.js +18 -1
  70. package/src/lib/redact.js +58 -7
  71. package/src/lib/resolver.js +66 -9
  72. package/src/lib/types.js +137 -0
  73. package/src/lib/writer.js +3 -0
  74. package/src/rules/pull-request-target-checkout.js +5 -0
  75. package/src/rules/unpinned-action.js +2 -3
  76. package/src/rules/workflow-structure.js +2 -4
  77. package/src/version.js +1 -1
  78. package/src/lib/agent-mode.js +0 -175
@@ -12,21 +12,42 @@ import { resolveRepositoryFile } from './config.js';
12
12
  import { summarize } from './formatter.js';
13
13
  import { isWorkflowPath } from './github-org.js';
14
14
  import { canonicalPath } from './identity.js';
15
+ import {
16
+ FILE_STATUSES,
17
+ GIT_SHA_RE,
18
+ NAME_RE,
19
+ SEVERITIES,
20
+ comparePaths,
21
+ isJsonValue,
22
+ isRecord,
23
+ } from './org-schema.js';
24
+ import { sourcePermalink, sourceUrl } from './org-source-links.js';
15
25
  import { redactDeep } from './redact.js';
16
26
  import { writeFileGuarded } from './writer.js';
17
27
  import { listRules } from '../rules/index.js';
18
28
  import { VERSION } from '../version.js';
19
29
 
20
30
  const CHECKPOINT_KIND = 'actions-warden-org-scan';
21
- const CHECKPOINT_SCHEMA_VERSION = '1.0';
31
+ const CHECKPOINT_SCHEMA_VERSION = '1.1';
32
+ const TOOL_VERSION_RE = /^\d+\.\d+\.\d+$/;
33
+
34
+ /**
35
+ * Checkpoint compatibility generation. Increment it whenever organization
36
+ * discovery, parsing, finding identity, rule evaluation, or persisted result
37
+ * semantics change; compatible package releases keep the current value.
38
+ */
39
+ export const ORGANIZATION_ANALYSIS_GENERATION = 3;
40
+
41
+ /** Maximum accepted or generated checkpoint size, in bytes. */
22
42
  export const MAX_ORGANIZATION_CHECKPOINT_BYTES = 256 * 1024 * 1024;
23
- const NAME_RE = /^[A-Za-z0-9_.-]+$/;
24
- const SHA_RE = /^[0-9a-f]{40}$/i;
25
43
  const ID_RE = /^[0-9a-f]{16}$/;
26
- const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
27
44
  const RULE_IDS = new Set(['parse-error', ...listRules().map(rule => rule.id)]);
28
45
  const RULES_HASH = digest(listRules());
29
46
 
47
+ /**
48
+ * Build the version-independent identity that controls whether checkpoint
49
+ * results are compatible with the requested scan and policy.
50
+ */
30
51
  export function createOrganizationCheckpointIdentity({
31
52
  organization,
32
53
  repositories,
@@ -41,7 +62,7 @@ export function createOrganizationCheckpointIdentity({
41
62
  baselineData,
42
63
  }) {
43
64
  return {
44
- toolVersion: VERSION,
65
+ analysisGeneration: ORGANIZATION_ANALYSIS_GENERATION,
45
66
  rulesHash: RULES_HASH,
46
67
  organization: organization.toLowerCase(),
47
68
  scope: {
@@ -66,6 +87,21 @@ export function createOrganizationCheckpointIdentity({
66
87
  };
67
88
  }
68
89
 
90
+ /**
91
+ * Create the stable key used by automatic organization-scan artifacts from
92
+ * the version-independent compatibility identity.
93
+ */
94
+ export function createOrganizationCheckpointArtifactKey(identity) {
95
+ return createHash('sha256')
96
+ .update(stableStringify(identity))
97
+ .digest('hex')
98
+ .slice(0, 32);
99
+ }
100
+
101
+ /**
102
+ * Load and fully validate a checkpoint, returning its reusable repository
103
+ * results. Only the current schema version is accepted.
104
+ */
69
105
  export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
70
106
  const resolvedPath = await resolveRepositoryFile(path, cwd);
71
107
  const metadata = await stat(resolvedPath);
@@ -84,12 +120,16 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
84
120
  throw error;
85
121
  }
86
122
  if (!isRecord(checkpoint) || checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
87
- throw new Error(`organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}"`);
123
+ throw new Error(
124
+ `organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}";`
125
+ + ' older checkpoints cannot be resumed, so start a fresh scan to replace it',
126
+ );
88
127
  }
89
128
  if (checkpoint.kind !== CHECKPOINT_KIND) {
90
129
  throw new Error('file is not an actions-warden organization checkpoint');
91
130
  }
92
- validateIdentity(checkpoint.identity, identity);
131
+ const storedIdentity = normalizeCheckpointIdentity(checkpoint);
132
+ validateIdentity(storedIdentity, identity);
93
133
  if (!Array.isArray(checkpoint.repositories)) {
94
134
  throw new Error('organization checkpoint repositories must be an array');
95
135
  }
@@ -104,10 +144,12 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
104
144
  return { path: resolvedPath, results };
105
145
  }
106
146
 
147
+ /** Validate a checkpoint destination without creating or replacing a file. */
107
148
  export async function validateOrganizationCheckpointPath({ path, cwd }) {
108
149
  return writeFileGuarded({ path, content: '', cwd, dryRun: true });
109
150
  }
110
151
 
152
+ /** Serialize, redact, size-check, and atomically replace a checkpoint. */
111
153
  export async function writeOrganizationCheckpoint({
112
154
  path,
113
155
  cwd,
@@ -120,6 +162,7 @@ export async function writeOrganizationCheckpoint({
120
162
  const content = `${JSON.stringify(redactDeep({
121
163
  schemaVersion: CHECKPOINT_SCHEMA_VERSION,
122
164
  kind: CHECKPOINT_KIND,
165
+ toolVersion: VERSION,
123
166
  identity,
124
167
  repositories,
125
168
  }), null, 2)}\n`;
@@ -131,31 +174,49 @@ export async function writeOrganizationCheckpoint({
131
174
  return writeFileGuarded({ path, content, cwd, dryRun: false });
132
175
  }
133
176
 
177
+ /** Return whether a result is error-free and still matches the live revision. */
134
178
  export function canReuseCheckpointResult(result, repository, treeSha) {
135
179
  return result.repository === repository.fullName
136
180
  && result.branch === repository.defaultBranch
137
181
  && result.treeSha === treeSha
138
- && result.errors.length === 0;
182
+ && result.errors.length === 0
183
+ && !result.findings.some(finding => finding.ruleId === 'parse-error');
139
184
  }
140
185
 
141
- export function restoreCheckpointResult(result, { repository, cwd, sourceUrl }) {
186
+ /**
187
+ * Rehydrate validated checkpoint data with local paths and live source links.
188
+ * The live default-branch commit supplies every permalink and the revision's
189
+ * commit, so a resumed report matches a freshly scanned one.
190
+ */
191
+ export function restoreCheckpointResult(result, { repository, cwd, commitSha }) {
142
192
  const repositoryRoot = resolve(cwd, repository.owner, repository.name);
193
+ const blobShas = new Map(result.fileDetails.map(detail => [detail.path, detail.blobSha]));
194
+ const link = (path, line) => sourcePermalink(repository, commitSha, path, line);
143
195
  const findings = result.findings.map(finding => ({
144
196
  ...finding,
145
197
  file: resolve(repositoryRoot, ...finding.file.split('/')),
146
198
  repository: repository.fullName,
147
199
  branch: repository.defaultBranch,
148
200
  url: sourceUrl(repository, finding.file, finding.line),
201
+ path: finding.file,
202
+ blobSha: blobShas.get(finding.file) ?? null,
203
+ permalink: link(finding.file, finding.line),
149
204
  }));
150
205
  return {
151
206
  repository,
152
- revision: { branch: repository.defaultBranch, treeSha: result.treeSha },
207
+ revision: {
208
+ branch: repository.defaultBranch,
209
+ treeSha: result.treeSha,
210
+ commitSha: commitSha ?? null,
211
+ },
153
212
  files: [...result.files],
213
+ fileDetails: result.fileDetails.map(detail => ({ ...detail, permalink: link(detail.path) })),
154
214
  findings,
155
215
  errors: result.errors.map(error => ({
156
216
  repository: repository.fullName,
157
217
  ...(error.path ? { path: error.path } : {}),
158
218
  error: error.error,
219
+ ...(error.path ? { permalink: link(error.path) } : {}),
159
220
  })),
160
221
  summary: { ...result.summary },
161
222
  status: result.status,
@@ -169,11 +230,18 @@ function serializeCheckpointResult(result, cwd) {
169
230
  branch: result.revision.branch,
170
231
  treeSha: result.revision.treeSha,
171
232
  files: [...result.files],
233
+ fileDetails: result.fileDetails.map(detail => ({
234
+ path: detail.path,
235
+ blobSha: detail.blobSha,
236
+ bytes: detail.bytes,
237
+ status: detail.status,
238
+ findings: detail.findings,
239
+ })),
172
240
  findings: result.findings.map(finding => {
173
241
  const copy = { ...finding, file: canonicalPath(finding.file, repositoryRoot) };
174
- delete copy.repository;
175
- delete copy.branch;
176
- delete copy.url;
242
+ for (const derived of ['repository', 'branch', 'url', 'path', 'blobSha', 'permalink']) {
243
+ delete copy[derived];
244
+ }
177
245
  return copy;
178
246
  }),
179
247
  errors: result.errors.map(error => ({
@@ -188,7 +256,7 @@ function serializeCheckpointResult(result, cwd) {
188
256
  function validateIdentity(actual, expected) {
189
257
  if (!isRecord(actual)) throw new Error('organization checkpoint identity is invalid');
190
258
  for (const field of [
191
- 'toolVersion',
259
+ 'analysisGeneration',
192
260
  'rulesHash',
193
261
  'organization',
194
262
  'scope',
@@ -201,6 +269,16 @@ function validateIdentity(actual, expected) {
201
269
  }
202
270
  }
203
271
 
272
+ function normalizeCheckpointIdentity(checkpoint) {
273
+ if (!isRecord(checkpoint.identity)) {
274
+ throw new Error('organization checkpoint identity is invalid');
275
+ }
276
+ if (typeof checkpoint.toolVersion !== 'string' || !TOOL_VERSION_RE.test(checkpoint.toolVersion)) {
277
+ throw new Error('organization checkpoint toolVersion is invalid');
278
+ }
279
+ return checkpoint.identity;
280
+ }
281
+
204
282
  function validateCheckpointResult(value, identity) {
205
283
  if (!isRecord(value)) throw new Error('organization checkpoint repository result is invalid');
206
284
  const repository = validateFullName(value.repository);
@@ -213,12 +291,18 @@ function validateCheckpointResult(value, identity) {
213
291
  explain: identity.scope.explain,
214
292
  });
215
293
  const errors = validateErrors(value.errors, repository);
294
+ const fileDetails = validateFileDetails(value.fileDetails, {
295
+ repository,
296
+ files,
297
+ findings,
298
+ errors,
299
+ });
216
300
  const summary = validateSummary(value.summary, files, findings, repository);
217
301
  const status = findings.length === 0 && errors.length === 0 ? 'OK' : 'FAIL';
218
302
  if (value.status !== status) {
219
303
  throw new Error(`organization checkpoint status is inconsistent for ${repository}`);
220
304
  }
221
- return { repository, branch, treeSha, files, findings, errors, summary, status };
305
+ return { repository, branch, treeSha, files, fileDetails, findings, errors, summary, status };
222
306
  }
223
307
 
224
308
  function validateFullName(value) {
@@ -244,7 +328,7 @@ function validateBranch(value) {
244
328
  }
245
329
 
246
330
  function validateSha(value, repository) {
247
- if (typeof value !== 'string' || !SHA_RE.test(value)) {
331
+ if (typeof value !== 'string' || !GIT_SHA_RE.test(value)) {
248
332
  throw new Error(`invalid checkpoint tree SHA for ${repository}`);
249
333
  }
250
334
  return value.toLowerCase();
@@ -258,7 +342,7 @@ function validateFiles(value, repository) {
258
342
  if (new Set(value).size !== value.length) {
259
343
  throw new Error(`duplicate checkpoint workflow path for ${repository}`);
260
344
  }
261
- if (value.some((path, index) => index > 0 && value[index - 1].localeCompare(path) > 0)) {
345
+ if (value.some((path, index) => index > 0 && comparePaths(value[index - 1], path) > 0)) {
262
346
  throw new Error(`checkpoint workflow paths are not ordered for ${repository}`);
263
347
  }
264
348
  return [...value];
@@ -314,6 +398,64 @@ function validateErrors(value, repository) {
314
398
  });
315
399
  }
316
400
 
401
+ const FILE_DETAIL_KEYS = ['blobSha', 'bytes', 'findings', 'path', 'status'];
402
+
403
+ function validateFileDetails(value, { repository, files, findings, errors }) {
404
+ if (!Array.isArray(value)) throw new Error(`invalid checkpoint fileDetails for ${repository}`);
405
+ const details = value.map(detail => validateFileDetail(detail, repository));
406
+ for (let index = 1; index < details.length; index += 1) {
407
+ const order = comparePaths(details[index - 1].path, details[index].path);
408
+ if (order === 0) throw new Error(`duplicate checkpoint fileDetails path for ${repository}`);
409
+ if (order > 0) throw new Error(`checkpoint fileDetails are not ordered for ${repository}`);
410
+ }
411
+ assertFileDetailsMatchEvidence(details, { repository, files, findings, errors });
412
+ return details;
413
+ }
414
+
415
+ function validateFileDetail(detail, repository) {
416
+ if (
417
+ !isRecord(detail)
418
+ || Object.keys(detail).sort().join() !== FILE_DETAIL_KEYS.join()
419
+ || !isWorkflowPath(detail.path)
420
+ || !FILE_STATUSES.has(detail.status)
421
+ || (detail.blobSha !== null && !GIT_SHA_RE.test(String(detail.blobSha)))
422
+ || (detail.bytes !== null && !isCount(detail.bytes))
423
+ || !isCount(detail.findings)
424
+ ) throw new Error(`invalid checkpoint fileDetails entry for ${repository}`);
425
+ return {
426
+ path: detail.path,
427
+ blobSha: detail.blobSha === null ? null : detail.blobSha.toLowerCase(),
428
+ bytes: detail.bytes,
429
+ status: detail.status,
430
+ findings: detail.findings,
431
+ };
432
+ }
433
+
434
+ function assertFileDetailsMatchEvidence(details, { repository, files, findings, errors }) {
435
+ const readable = details
436
+ .filter(detail => detail.status !== 'unreadable')
437
+ .map(detail => detail.path);
438
+ const errorPaths = new Set(errors.map(error => error.path));
439
+ const inconsistent = (
440
+ readable.length !== files.length
441
+ || readable.some((path, index) => path !== files[index])
442
+ || details.some(detail => detail.status === 'unreadable' && !errorPaths.has(detail.path))
443
+ || details.some(detail => !fileDetailMatchesFindings(detail, findings))
444
+ );
445
+ if (inconsistent) throw new Error(`inconsistent checkpoint fileDetails for ${repository}`);
446
+ }
447
+
448
+ function fileDetailMatchesFindings(detail, findings) {
449
+ const own = findings.filter(finding => finding.file === detail.path);
450
+ const parseError = own.some(finding => finding.ruleId === 'parse-error');
451
+ return own.length === detail.findings
452
+ && (detail.status === 'parse-error') === parseError;
453
+ }
454
+
455
+ function isCount(value) {
456
+ return Number.isSafeInteger(value) && value >= 0;
457
+ }
458
+
317
459
  function validateSummary(value, files, findings, repository) {
318
460
  if (!isRecord(value)) throw new Error(`invalid checkpoint summary for ${repository}`);
319
461
  const fields = [
@@ -358,21 +500,3 @@ function stableValue(value) {
358
500
  }
359
501
  return value;
360
502
  }
361
-
362
- function isJsonValue(value, seen = new Set()) {
363
- if (value === null || ['string', 'boolean'].includes(typeof value)) return true;
364
- if (typeof value === 'number') return Number.isFinite(value);
365
- if (!value || typeof value !== 'object' || seen.has(value)) return false;
366
- seen.add(value);
367
- const valid = Array.isArray(value)
368
- ? value.every(item => isJsonValue(item, seen))
369
- : Object.entries(value).every(([key, item]) => (
370
- typeof key === 'string' && isJsonValue(item, seen)
371
- ));
372
- seen.delete(value);
373
- return valid;
374
- }
375
-
376
- function isRecord(value) {
377
- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
378
- }
@@ -1,10 +1,165 @@
1
1
  /**
2
- * Human-readable rendering for structured organization-scan progress events.
3
- * Progress is a separate channel from final report serialization.
2
+ * Organization-scan progress rendering and stderr reporters.
3
+ *
4
+ * Progress is a separate, best-effort channel from final report
5
+ * serialization. Public library callbacks remain strict; this adapter catches
6
+ * failures from its own output stream so a closed log pipe cannot invalidate
7
+ * otherwise durable scan evidence.
4
8
  */
5
9
 
6
- import { redact } from './redact.js';
10
+ import { redact, redactDeep } from './redact.js';
7
11
 
12
+ const ORGANIZATION_PROGRESS_CONTEXTS = new Set(['agent', 'auto', 'ci', 'interactive']);
13
+ const REPORTED_SCAN_FAILURES = new WeakSet();
14
+
15
+ /**
16
+ * Return whether a structured JSON progress channel already reported this
17
+ * error as a terminal `scan-failed` event, so callers do not report it twice.
18
+ *
19
+ * @param {unknown} error
20
+ * @returns {boolean}
21
+ */
22
+ export function isScanFailureReported(error) {
23
+ return Boolean(error) && typeof error === 'object' && REPORTED_SCAN_FAILURES.has(error);
24
+ }
25
+
26
+ /** Public organization progress modes accepted by the CLI. */
27
+ export const ORGANIZATION_PROGRESS_MODES = Object.freeze([
28
+ 'auto',
29
+ 'plain',
30
+ 'json',
31
+ 'none',
32
+ ]);
33
+
34
+ /**
35
+ * Resolve an implicit progress mode for an explicit execution context.
36
+ * Context changes presentation only; it never changes scan scope or evidence.
37
+ */
38
+ export function resolveOrganizationProgressMode({
39
+ mode = 'auto',
40
+ context = 'auto',
41
+ isTTY = false,
42
+ } = {}) {
43
+ if (!ORGANIZATION_PROGRESS_MODES.includes(mode)) {
44
+ throw new Error('progress must be auto, plain, json, or none');
45
+ }
46
+ if (!ORGANIZATION_PROGRESS_CONTEXTS.has(context)) {
47
+ throw new Error('progress context must be agent, auto, ci, or interactive');
48
+ }
49
+ if (mode !== 'auto') return mode;
50
+ if (context === 'agent') return 'none';
51
+ if (context === 'ci') return 'plain';
52
+ if (context === 'interactive') return 'plain';
53
+ return isTTY ? 'plain' : 'none';
54
+ }
55
+
56
+ /**
57
+ * Create a best-effort progress reporter for human lines or JSON Lines.
58
+ * Every JSON event receives stable envelope metadata and is written to the
59
+ * supplied stream one event per line.
60
+ */
61
+ export function createOrganizationProgressReporter({
62
+ mode = 'auto',
63
+ context = 'auto',
64
+ stream = process.stderr,
65
+ isTTY = stream.isTTY === true,
66
+ now = Date.now,
67
+ } = {}) {
68
+ const resolvedMode = resolveOrganizationProgressMode({ mode, context, isTTY });
69
+ const startedAt = now();
70
+ let disabled = resolvedMode === 'none';
71
+ let closed = false;
72
+ let pendingWrites = 0;
73
+ let listenerAttached = false;
74
+ let cleanupScheduled = false;
75
+
76
+ const onError = () => {
77
+ disabled = true;
78
+ };
79
+ if (typeof stream?.on === 'function') {
80
+ stream.on('error', onError);
81
+ listenerAttached = true;
82
+ }
83
+
84
+ function cleanupListener() {
85
+ if (!listenerAttached) return;
86
+ listenerAttached = false;
87
+ if (typeof stream?.removeListener === 'function') {
88
+ stream.removeListener('error', onError);
89
+ } else if (typeof stream?.off === 'function') {
90
+ stream.off('error', onError);
91
+ }
92
+ }
93
+
94
+ function scheduleCleanup() {
95
+ if (!closed || pendingWrites !== 0 || !listenerAttached || cleanupScheduled) return;
96
+ cleanupScheduled = true;
97
+ // Writable streams invoke a failed write's callback before emitting the
98
+ // corresponding error event. Keep the listener through that event turn.
99
+ setImmediate(() => {
100
+ cleanupScheduled = false;
101
+ if (closed && pendingWrites === 0) cleanupListener();
102
+ });
103
+ }
104
+
105
+ function write(value) {
106
+ if (disabled || closed) return false;
107
+ try {
108
+ pendingWrites += 1;
109
+ return stream.write(value, error => {
110
+ pendingWrites = Math.max(0, pendingWrites - 1);
111
+ if (error) disabled = true;
112
+ scheduleCleanup();
113
+ });
114
+ } catch {
115
+ pendingWrites = Math.max(0, pendingWrites - 1);
116
+ disabled = true;
117
+ scheduleCleanup();
118
+ return false;
119
+ }
120
+ }
121
+
122
+ function emit(rawEvent) {
123
+ if (disabled || closed) return null;
124
+ const current = now();
125
+ const { type, ...fields } = rawEvent;
126
+ const event = Object.freeze({
127
+ ...redactDeep(fields),
128
+ schemaVersion: '1.0',
129
+ kind: 'actions-warden-org-scan-progress',
130
+ event: redact(type),
131
+ timestamp: new Date(current).toISOString(),
132
+ elapsedMs: Math.max(0, current - startedAt),
133
+ });
134
+ if (resolvedMode === 'json') {
135
+ return write(`${JSON.stringify(event)}\n`) ? event : null;
136
+ }
137
+ const message = formatOrganizationProgress(rawEvent);
138
+ return !message || write(message) ? event : null;
139
+ }
140
+
141
+ function close() {
142
+ closed = true;
143
+ scheduleCleanup();
144
+ }
145
+
146
+ function failScan(organization, error) {
147
+ emit({ type: 'scan-failed', organization, error: String(error?.message ?? error) });
148
+ if (resolvedMode === 'json' && error && typeof error === 'object') {
149
+ REPORTED_SCAN_FAILURES.add(error);
150
+ }
151
+ }
152
+
153
+ return {
154
+ emit,
155
+ failScan,
156
+ close,
157
+ mode: resolvedMode,
158
+ requestedMode: mode,
159
+ };
160
+ }
161
+
162
+ /** Render one redacted progress line, or an empty string for an unknown event. */
8
163
  export function formatOrganizationProgress(event) {
9
164
  switch (event.type) {
10
165
  case 'scan-started':
@@ -15,19 +170,38 @@ export function formatOrganizationProgress(event) {
15
170
  return line('created organization scan checkpoint');
16
171
  case 'discovery-started':
17
172
  return line(`discovering repositories in ${event.organization}`);
173
+ case 'discovery-page':
174
+ return line(
175
+ `repository discovery page ${event.page}: ${event.repositoriesDiscovered} visible`
176
+ + (Number.isSafeInteger(event.rateLimitRemaining)
177
+ ? `, GitHub API remaining ${event.rateLimitRemaining}`
178
+ : ''),
179
+ );
18
180
  case 'discovery-completed':
19
181
  return line(
20
182
  `selected ${event.selected} of ${event.discovered} discovered repositories`
21
183
  + ` (${event.eligible} eligible)`,
22
184
  );
23
185
  case 'repository-started':
24
- return line(`[${event.position}/${event.total}] scanning ${event.repository}`);
186
+ return line(
187
+ `[${event.position}/${event.total}] scanning ${event.repository}`
188
+ + (Number.isSafeInteger(event.active)
189
+ ? ` (${event.active}/${event.concurrency} active)`
190
+ : ''),
191
+ );
192
+ case 'repository-phase':
193
+ return line(`[${event.position}/${event.total}] ${event.repository}: ${event.phase}`);
25
194
  case 'request-retry':
26
195
  return line(
27
196
  `${event.repository ? `${event.repository}: ` : ''}`
28
197
  + `GitHub request retry ${event.attempt}/${event.maxRetries}`
29
198
  + ` after ${event.reason} (${event.delayMs}ms)`,
30
199
  );
200
+ case 'checkpoint-written':
201
+ return line(
202
+ `${event.repository}: checkpoint durable`
203
+ + ` (${event.repositories}/${event.total} repositories)`,
204
+ );
31
205
  case 'repository-completed':
32
206
  return line(
33
207
  `[${event.completed}/${event.total}] ${event.reused ? 'resumed' : 'completed'} `
@@ -40,6 +214,10 @@ export function formatOrganizationProgress(event) {
40
214
  + `repositories, ${event.reused} resumed, ${event.findings} findings, `
41
215
  + `${event.errors} errors in ${event.elapsedMs}ms`,
42
216
  );
217
+ case 'scan-failed':
218
+ return line(`organization scan failed for ${event.organization}: ${event.error}`);
219
+ case 'command-failed':
220
+ return line(`organization scan command failed for ${event.organization}: ${event.error}`);
43
221
  default:
44
222
  return '';
45
223
  }