actions-warden 0.4.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 (76) hide show
  1. package/AGENTS.md +46 -8
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +171 -61
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +15 -5
  6. package/docs/AI-AGENTS.md +109 -29
  7. package/docs/CLI.md +284 -60
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +97 -24
  10. package/docs/GITHUB-ACTION.md +157 -27
  11. package/docs/JAVASCRIPT-API.md +172 -8
  12. package/docs/OUTPUTS.md +399 -36
  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 +78 -35
  35. package/src/action.js +351 -174
  36. package/src/cli.js +191 -177
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +451 -280
  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 +137 -96
  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/paths.js +18 -1
  69. package/src/lib/redact.js +58 -7
  70. package/src/lib/resolver.js +66 -9
  71. package/src/lib/types.js +137 -0
  72. package/src/rules/pull-request-target-checkout.js +5 -0
  73. package/src/rules/unpinned-action.js +2 -3
  74. package/src/rules/workflow-structure.js +2 -4
  75. package/src/version.js +1 -1
  76. package/src/lib/agent-mode.js +0 -174
@@ -12,6 +12,16 @@ 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';
@@ -19,21 +29,25 @@ import { VERSION } from '../version.js';
19
29
 
20
30
  const CHECKPOINT_KIND = 'actions-warden-org-scan';
21
31
  const CHECKPOINT_SCHEMA_VERSION = '1.1';
22
- const LEGACY_CHECKPOINT_SCHEMA_VERSION = '1.0';
23
- const FIRST_ANALYSIS_GENERATION_TOOL_VERSION = '0.3.0';
24
32
  const TOOL_VERSION_RE = /^\d+\.\d+\.\d+$/;
25
- // Increment this whenever organization discovery, parsing, finding identity,
26
- // rule evaluation, or persisted result semantics can change. Package releases
27
- // that leave those behaviors compatible must keep the generation unchanged.
28
- export const ORGANIZATION_ANALYSIS_GENERATION = 1;
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. */
29
42
  export const MAX_ORGANIZATION_CHECKPOINT_BYTES = 256 * 1024 * 1024;
30
- const NAME_RE = /^[A-Za-z0-9_.-]+$/;
31
- const SHA_RE = /^[0-9a-f]{40}$/i;
32
43
  const ID_RE = /^[0-9a-f]{16}$/;
33
- const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
34
44
  const RULE_IDS = new Set(['parse-error', ...listRules().map(rule => rule.id)]);
35
45
  const RULES_HASH = digest(listRules());
36
46
 
47
+ /**
48
+ * Build the version-independent identity that controls whether checkpoint
49
+ * results are compatible with the requested scan and policy.
50
+ */
37
51
  export function createOrganizationCheckpointIdentity({
38
52
  organization,
39
53
  repositories,
@@ -74,41 +88,20 @@ export function createOrganizationCheckpointIdentity({
74
88
  }
75
89
 
76
90
  /**
77
- * Create the stable key used by automatic agent artifacts.
78
- *
79
- * Generation 1 deliberately retains the exact identity serialization used by
80
- * v0.3.0 so existing automatic checkpoints remain discoverable after an
81
- * upgrade. Later generations use the version-independent compatibility
82
- * identity directly.
91
+ * Create the stable key used by automatic organization-scan artifacts from
92
+ * the version-independent compatibility identity.
83
93
  */
84
94
  export function createOrganizationCheckpointArtifactKey(identity) {
85
- const compatibleIdentity = identity.analysisGeneration === 1
86
- ? {
87
- toolVersion: FIRST_ANALYSIS_GENERATION_TOOL_VERSION,
88
- rulesHash: identity.rulesHash,
89
- organization: identity.organization,
90
- scope: {
91
- repositories: identity.scope.repositories,
92
- visibility: identity.scope.visibility,
93
- includeArchived: identity.scope.includeArchived,
94
- includeDisabled: identity.scope.includeDisabled,
95
- includeForks: identity.scope.includeForks,
96
- maxRepositories: identity.scope.maxRepositories,
97
- severity: identity.scope.severity,
98
- explain: identity.scope.explain,
99
- },
100
- configHash: identity.configHash,
101
- baselineHash: identity.baselineHash,
102
- }
103
- : identity;
104
95
  return createHash('sha256')
105
- .update(identity.analysisGeneration === 1
106
- ? JSON.stringify(compatibleIdentity)
107
- : stableStringify(compatibleIdentity))
96
+ .update(stableStringify(identity))
108
97
  .digest('hex')
109
98
  .slice(0, 32);
110
99
  }
111
100
 
101
+ /**
102
+ * Load and fully validate a checkpoint, returning its reusable repository
103
+ * results. Only the current schema version is accepted.
104
+ */
112
105
  export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
113
106
  const resolvedPath = await resolveRepositoryFile(path, cwd);
114
107
  const metadata = await stat(resolvedPath);
@@ -126,14 +119,10 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
126
119
  if (error instanceof SyntaxError) throw new Error('organization checkpoint is not valid JSON');
127
120
  throw error;
128
121
  }
129
- if (
130
- !isRecord(checkpoint)
131
- || ![CHECKPOINT_SCHEMA_VERSION, LEGACY_CHECKPOINT_SCHEMA_VERSION]
132
- .includes(checkpoint.schemaVersion)
133
- ) {
122
+ if (!isRecord(checkpoint) || checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
134
123
  throw new Error(
135
- `organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}"`
136
- + ` or "${LEGACY_CHECKPOINT_SCHEMA_VERSION}"`,
124
+ `organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}";`
125
+ + ' older checkpoints cannot be resumed, so start a fresh scan to replace it',
137
126
  );
138
127
  }
139
128
  if (checkpoint.kind !== CHECKPOINT_KIND) {
@@ -152,18 +141,15 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
152
141
  if (results.has(key)) throw new Error(`duplicate checkpoint repository: ${result.repository}`);
153
142
  results.set(key, result);
154
143
  }
155
- return {
156
- path: resolvedPath,
157
- results,
158
- migrationRequired: checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION
159
- || checkpoint.toolVersion !== VERSION,
160
- };
144
+ return { path: resolvedPath, results };
161
145
  }
162
146
 
147
+ /** Validate a checkpoint destination without creating or replacing a file. */
163
148
  export async function validateOrganizationCheckpointPath({ path, cwd }) {
164
149
  return writeFileGuarded({ path, content: '', cwd, dryRun: true });
165
150
  }
166
151
 
152
+ /** Serialize, redact, size-check, and atomically replace a checkpoint. */
167
153
  export async function writeOrganizationCheckpoint({
168
154
  path,
169
155
  cwd,
@@ -188,31 +174,49 @@ export async function writeOrganizationCheckpoint({
188
174
  return writeFileGuarded({ path, content, cwd, dryRun: false });
189
175
  }
190
176
 
177
+ /** Return whether a result is error-free and still matches the live revision. */
191
178
  export function canReuseCheckpointResult(result, repository, treeSha) {
192
179
  return result.repository === repository.fullName
193
180
  && result.branch === repository.defaultBranch
194
181
  && result.treeSha === treeSha
195
- && result.errors.length === 0;
182
+ && result.errors.length === 0
183
+ && !result.findings.some(finding => finding.ruleId === 'parse-error');
196
184
  }
197
185
 
198
- 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 }) {
199
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);
200
195
  const findings = result.findings.map(finding => ({
201
196
  ...finding,
202
197
  file: resolve(repositoryRoot, ...finding.file.split('/')),
203
198
  repository: repository.fullName,
204
199
  branch: repository.defaultBranch,
205
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),
206
204
  }));
207
205
  return {
208
206
  repository,
209
- revision: { branch: repository.defaultBranch, treeSha: result.treeSha },
207
+ revision: {
208
+ branch: repository.defaultBranch,
209
+ treeSha: result.treeSha,
210
+ commitSha: commitSha ?? null,
211
+ },
210
212
  files: [...result.files],
213
+ fileDetails: result.fileDetails.map(detail => ({ ...detail, permalink: link(detail.path) })),
211
214
  findings,
212
215
  errors: result.errors.map(error => ({
213
216
  repository: repository.fullName,
214
217
  ...(error.path ? { path: error.path } : {}),
215
218
  error: error.error,
219
+ ...(error.path ? { permalink: link(error.path) } : {}),
216
220
  })),
217
221
  summary: { ...result.summary },
218
222
  status: result.status,
@@ -226,11 +230,18 @@ function serializeCheckpointResult(result, cwd) {
226
230
  branch: result.revision.branch,
227
231
  treeSha: result.revision.treeSha,
228
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
+ })),
229
240
  findings: result.findings.map(finding => {
230
241
  const copy = { ...finding, file: canonicalPath(finding.file, repositoryRoot) };
231
- delete copy.repository;
232
- delete copy.branch;
233
- delete copy.url;
242
+ for (const derived of ['repository', 'branch', 'url', 'path', 'blobSha', 'permalink']) {
243
+ delete copy[derived];
244
+ }
234
245
  return copy;
235
246
  }),
236
247
  errors: result.errors.map(error => ({
@@ -262,26 +273,10 @@ function normalizeCheckpointIdentity(checkpoint) {
262
273
  if (!isRecord(checkpoint.identity)) {
263
274
  throw new Error('organization checkpoint identity is invalid');
264
275
  }
265
- if (checkpoint.schemaVersion === CHECKPOINT_SCHEMA_VERSION) {
266
- if (typeof checkpoint.toolVersion !== 'string' || !TOOL_VERSION_RE.test(checkpoint.toolVersion)) {
267
- throw new Error('organization checkpoint toolVersion is invalid');
268
- }
269
- return checkpoint.identity;
276
+ if (typeof checkpoint.toolVersion !== 'string' || !TOOL_VERSION_RE.test(checkpoint.toolVersion)) {
277
+ throw new Error('organization checkpoint toolVersion is invalid');
270
278
  }
271
- if (checkpoint.identity.toolVersion !== FIRST_ANALYSIS_GENERATION_TOOL_VERSION) {
272
- throw new Error(
273
- `organization checkpoint toolVersion ${String(checkpoint.identity.toolVersion)}`
274
- + ' has no compatible analysis generation',
275
- );
276
- }
277
- return {
278
- analysisGeneration: 1,
279
- rulesHash: checkpoint.identity.rulesHash,
280
- organization: checkpoint.identity.organization,
281
- scope: checkpoint.identity.scope,
282
- configHash: checkpoint.identity.configHash,
283
- baselineHash: checkpoint.identity.baselineHash,
284
- };
279
+ return checkpoint.identity;
285
280
  }
286
281
 
287
282
  function validateCheckpointResult(value, identity) {
@@ -296,12 +291,18 @@ function validateCheckpointResult(value, identity) {
296
291
  explain: identity.scope.explain,
297
292
  });
298
293
  const errors = validateErrors(value.errors, repository);
294
+ const fileDetails = validateFileDetails(value.fileDetails, {
295
+ repository,
296
+ files,
297
+ findings,
298
+ errors,
299
+ });
299
300
  const summary = validateSummary(value.summary, files, findings, repository);
300
301
  const status = findings.length === 0 && errors.length === 0 ? 'OK' : 'FAIL';
301
302
  if (value.status !== status) {
302
303
  throw new Error(`organization checkpoint status is inconsistent for ${repository}`);
303
304
  }
304
- return { repository, branch, treeSha, files, findings, errors, summary, status };
305
+ return { repository, branch, treeSha, files, fileDetails, findings, errors, summary, status };
305
306
  }
306
307
 
307
308
  function validateFullName(value) {
@@ -327,7 +328,7 @@ function validateBranch(value) {
327
328
  }
328
329
 
329
330
  function validateSha(value, repository) {
330
- if (typeof value !== 'string' || !SHA_RE.test(value)) {
331
+ if (typeof value !== 'string' || !GIT_SHA_RE.test(value)) {
331
332
  throw new Error(`invalid checkpoint tree SHA for ${repository}`);
332
333
  }
333
334
  return value.toLowerCase();
@@ -341,7 +342,7 @@ function validateFiles(value, repository) {
341
342
  if (new Set(value).size !== value.length) {
342
343
  throw new Error(`duplicate checkpoint workflow path for ${repository}`);
343
344
  }
344
- 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)) {
345
346
  throw new Error(`checkpoint workflow paths are not ordered for ${repository}`);
346
347
  }
347
348
  return [...value];
@@ -397,6 +398,64 @@ function validateErrors(value, repository) {
397
398
  });
398
399
  }
399
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
+
400
459
  function validateSummary(value, files, findings, repository) {
401
460
  if (!isRecord(value)) throw new Error(`invalid checkpoint summary for ${repository}`);
402
461
  const fields = [
@@ -441,21 +500,3 @@ function stableValue(value) {
441
500
  }
442
501
  return value;
443
502
  }
444
-
445
- function isJsonValue(value, seen = new Set()) {
446
- if (value === null || ['string', 'boolean'].includes(typeof value)) return true;
447
- if (typeof value === 'number') return Number.isFinite(value);
448
- if (!value || typeof value !== 'object' || seen.has(value)) return false;
449
- seen.add(value);
450
- const valid = Array.isArray(value)
451
- ? value.every(item => isJsonValue(item, seen))
452
- : Object.entries(value).every(([key, item]) => (
453
- typeof key === 'string' && isJsonValue(item, seen)
454
- ));
455
- seen.delete(value);
456
- return valid;
457
- }
458
-
459
- function isRecord(value) {
460
- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
461
- }
@@ -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
  }