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
@@ -3,11 +3,11 @@
3
3
  * fetch workflow YAML from each default branch, and aggregate audit findings.
4
4
  */
5
5
 
6
- import { realpath } from 'node:fs/promises';
7
- import { basename, dirname, join, resolve } from 'node:path';
6
+ import { createHash } from 'node:crypto';
7
+ import { resolve } from 'node:path';
8
8
  import picomatch from 'picomatch';
9
9
  import { auditSources } from './audit.js';
10
- import { loadBaseline } from '../lib/baseline.js';
10
+ import { emptyBaseline, loadBaseline } from '../lib/baseline.js';
11
11
  import { filterIgnoredPaths, loadConfig } from '../lib/config.js';
12
12
  import { mapLimit } from '../lib/concurrency.js';
13
13
  import { format, summarize } from '../lib/formatter.js';
@@ -19,17 +19,24 @@ import {
19
19
  } from '../lib/github-org.js';
20
20
  import {
21
21
  canReuseCheckpointResult,
22
+ createOrganizationCheckpointArtifactKey,
22
23
  createOrganizationCheckpointIdentity,
23
24
  loadOrganizationCheckpoint,
24
25
  restoreCheckpointResult,
25
26
  validateOrganizationCheckpointPath,
26
27
  writeOrganizationCheckpoint,
27
28
  } from '../lib/org-checkpoint.js';
29
+ import { buildOrganizationReport, organizationReportRecords } from '../lib/org-report.js';
30
+ import {
31
+ NAME_RE,
32
+ VISIBILITIES,
33
+ comparePaths,
34
+ normalizePatterns,
35
+ } from '../lib/org-schema.js';
36
+ import { sourcePermalink, sourceUrl } from '../lib/org-source-links.js';
28
37
  import { resolveToken } from '../lib/resolver.js';
29
- import { listRules, RULES } from '../rules/index.js';
30
-
31
- const VISIBILITIES = new Set(['all', 'public', 'private', 'internal']);
32
- const ORGANIZATION_RE = /^[A-Za-z0-9_.-]+$/;
38
+ import { RULES } from '../rules/index.js';
39
+ import { sameFilePath } from '../lib/path-equality.js';
33
40
 
34
41
  /**
35
42
  * @param {object} opts
@@ -70,29 +77,149 @@ export async function scanOrganization({
70
77
  resume = false,
71
78
  onProgress,
72
79
  } = {}) {
80
+ const settings = validateScanOptions({
81
+ organization,
82
+ cwd,
83
+ token,
84
+ repositories,
85
+ visibility,
86
+ includeArchived,
87
+ includeDisabled,
88
+ includeForks,
89
+ maxRepositories,
90
+ concurrency,
91
+ severity,
92
+ explain,
93
+ configPath,
94
+ baseline,
95
+ checkpointPath,
96
+ resume,
97
+ onProgress,
98
+ });
99
+ const startedAt = Date.now();
100
+ await emitProgress(onProgress, { type: 'scan-started', organization });
101
+ const environment = await prepareScanEnvironment(settings);
102
+ const loadedCheckpoint = await loadResumeState(settings, environment);
103
+ const selection = await selectScanRepositories(settings, environment);
104
+ const checkpoint = await openCheckpoint(settings, environment, loadedCheckpoint, selection);
105
+ const state = { settings, environment, loadedCheckpoint, selection, checkpoint };
106
+ const counters = await scanSelectedRepositories(state);
107
+
108
+ const result = assembleOrganizationResult(state, counters.repositoryResults);
109
+ await emitProgress(onProgress, {
110
+ type: 'scan-completed',
111
+ organization,
112
+ status: result.status,
113
+ total: selection.selected.length,
114
+ completed: counters.completed,
115
+ reused: counters.reused,
116
+ findings: result.summary.findings,
117
+ errors: result.summary.errors,
118
+ elapsedMs: Date.now() - startedAt,
119
+ });
120
+ return result;
121
+ }
122
+
123
+ /**
124
+ * Render an organization scan result with repository-relative paths and the
125
+ * selected public serialization contract.
126
+ *
127
+ * @param {Awaited<ReturnType<typeof scanOrganization>>} result
128
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', cwd?: string,
129
+ * comparison?: object}} options
130
+ * @returns {string}
131
+ */
132
+ export function renderOrganizationScan(result, {
133
+ format: outputFormat,
134
+ cwd = process.cwd(),
135
+ comparison = result.comparison,
136
+ }) {
137
+ const report = buildOrganizationReport(result, { cwd, comparison });
138
+ if (outputFormat === 'json') {
139
+ return format('json', [], { status: report.status, json: report });
140
+ }
141
+ const { records, title, metadata } = organizationReportRecords(report, {
142
+ format: outputFormat,
143
+ });
144
+ return format(outputFormat, records, { status: report.status, title, metadata });
145
+ }
146
+
147
+ function validateScanOptions(settings) {
148
+ assertOrganizationName(settings.organization);
149
+ if (!VISIBILITIES.has(settings.visibility)) {
150
+ throw new Error(`invalid visibility: ${settings.visibility}`);
151
+ }
152
+ assertConcurrency(settings.concurrency);
153
+ assertMaxRepositories(settings.maxRepositories);
154
+ assertCheckpointOptions(settings.checkpointPath, settings.resume);
155
+ if (settings.onProgress !== undefined && typeof settings.onProgress !== 'function') {
156
+ throw new Error('onProgress must be a function');
157
+ }
158
+ return settings;
159
+ }
160
+
161
+ function assertOrganizationName(organization) {
73
162
  if (
74
163
  typeof organization !== 'string'
75
- || !ORGANIZATION_RE.test(organization)
164
+ || !NAME_RE.test(organization)
76
165
  || organization === '.'
77
166
  || organization === '..'
78
167
  ) throw new Error('invalid organization');
79
- if (!VISIBILITIES.has(visibility)) throw new Error(`invalid visibility: ${visibility}`);
168
+ }
169
+
170
+ function assertConcurrency(concurrency) {
80
171
  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 16) {
81
172
  throw new Error('concurrency must be an integer from 1 to 16');
82
173
  }
83
- if (maxRepositories !== undefined && (!Number.isInteger(maxRepositories) || maxRepositories < 1)) {
84
- throw new Error('max repositories must be a positive integer');
85
- }
174
+ }
175
+
176
+ function assertMaxRepositories(maxRepositories) {
177
+ if (
178
+ maxRepositories !== undefined
179
+ && (!Number.isInteger(maxRepositories) || maxRepositories < 1)
180
+ ) throw new Error('max repositories must be a positive integer');
181
+ }
182
+
183
+ function assertCheckpointOptions(checkpointPath, resume) {
86
184
  if (checkpointPath !== undefined && (typeof checkpointPath !== 'string' || !checkpointPath)) {
87
185
  throw new Error('checkpoint path must be a non-empty string');
88
186
  }
89
187
  if (typeof resume !== 'boolean') throw new Error('resume must be a boolean');
90
188
  if (resume && !checkpointPath) throw new Error('resume requires a checkpoint path');
91
- if (onProgress !== undefined && typeof onProgress !== 'function') {
92
- throw new Error('onProgress must be a function');
93
- }
94
- const startedAt = Date.now();
95
- await emitProgress(onProgress, { type: 'scan-started', organization });
189
+ }
190
+
191
+ async function loadResumeState(settings, environment) {
192
+ const { cwd, checkpointPath, resume, onProgress } = settings;
193
+ if (!resume) return { results: new Map() };
194
+ const loadedCheckpoint = await loadOrganizationCheckpoint({
195
+ path: checkpointPath,
196
+ cwd,
197
+ identity: environment.checkpointIdentity,
198
+ });
199
+ await emitProgress(onProgress, {
200
+ type: 'checkpoint-loaded',
201
+ repositories: loadedCheckpoint.results.size,
202
+ });
203
+ return loadedCheckpoint;
204
+ }
205
+
206
+ async function prepareScanEnvironment(settings) {
207
+ const {
208
+ organization,
209
+ cwd,
210
+ token,
211
+ repositories,
212
+ visibility,
213
+ includeArchived,
214
+ includeDisabled,
215
+ includeForks,
216
+ maxRepositories,
217
+ severity,
218
+ explain,
219
+ configPath,
220
+ baseline,
221
+ checkpointPath,
222
+ } = settings;
96
223
  const patterns = normalizePatterns(repositories);
97
224
  const resolvedToken = resolveToken(token);
98
225
  const config = await loadConfig({
@@ -103,7 +230,7 @@ export async function scanOrganization({
103
230
  const baselinePath = baseline ?? config.baseline;
104
231
  const baselineData = baselinePath
105
232
  ? await loadBaseline({ path: baselinePath, cwd })
106
- : { path: null, ids: new Set(), fingerprints: new Set() };
233
+ : emptyBaseline();
107
234
  if (checkpointPath) {
108
235
  await validateOrganizationCheckpointPath({ path: checkpointPath, cwd });
109
236
  await assertCheckpointDoesNotReplaceControlFile(checkpointPath, cwd, [
@@ -124,21 +251,36 @@ export async function scanOrganization({
124
251
  config,
125
252
  baselineData,
126
253
  });
127
- const loadedCheckpoint = resume
128
- ? await loadOrganizationCheckpoint({ path: checkpointPath, cwd, identity: checkpointIdentity })
129
- : { results: new Map() };
130
- if (resume) {
131
- await emitProgress(onProgress, {
132
- type: 'checkpoint-loaded',
133
- repositories: loadedCheckpoint.results.size,
134
- });
135
- }
254
+ return { patterns, resolvedToken, config, baselineData, checkpointIdentity };
255
+ }
256
+
257
+ async function selectScanRepositories(settings, environment) {
258
+ const {
259
+ organization,
260
+ cwd,
261
+ includeArchived,
262
+ includeDisabled,
263
+ includeForks,
264
+ maxRepositories,
265
+ visibility,
266
+ onProgress,
267
+ } = settings;
268
+ const { patterns, resolvedToken } = environment;
136
269
  await emitProgress(onProgress, { type: 'discovery-started', organization });
137
270
  const discovered = await listOrganizationRepositories({
138
271
  organization,
139
272
  token: resolvedToken,
140
273
  cwd,
141
274
  onRetry: retry => emitRetryProgress(onProgress, retry),
275
+ onPage: page => emitProgress(onProgress, {
276
+ type: 'discovery-page',
277
+ organization,
278
+ page: page.page,
279
+ repositoriesDiscovered: page.repositoriesDiscovered,
280
+ ...(Number.isSafeInteger(page.rateLimit?.remaining)
281
+ ? { rateLimitRemaining: page.rateLimit.remaining }
282
+ : {}),
283
+ }),
142
284
  });
143
285
  const eligible = selectRepositories(discovered, {
144
286
  patterns,
@@ -160,144 +302,288 @@ export async function scanOrganization({
160
302
  eligible: eligible.length,
161
303
  selected: selected.length,
162
304
  });
305
+ return { discovered, eligible, selected };
306
+ }
163
307
 
164
- const checkpointResults = new Map();
165
- for (const repository of selected) {
308
+ async function openCheckpoint(settings, environment, loadedCheckpoint, selection) {
309
+ const { cwd, checkpointPath, resume, onProgress } = settings;
310
+ const results = new Map();
311
+ for (const repository of selection.selected) {
166
312
  const stored = loadedCheckpoint.results.get(repository.fullName.toLowerCase());
167
313
  if (!stored) continue;
168
- checkpointResults.set(repository.fullName.toLowerCase(), restoreCheckpointResult(stored, {
314
+ results.set(repository.fullName.toLowerCase(), restoreCheckpointResult(stored, {
169
315
  repository,
170
316
  cwd,
171
- sourceUrl,
317
+ commitSha: null,
172
318
  }));
173
319
  }
174
- const persistCheckpoint = createCheckpointWriter({
320
+ const persist = createCheckpointWriter({
175
321
  path: checkpointPath,
176
322
  cwd,
177
- identity: checkpointIdentity,
178
- results: checkpointResults,
323
+ identity: environment.checkpointIdentity,
324
+ results,
179
325
  });
180
326
  if (checkpointPath && !resume) {
181
- await persistCheckpoint();
327
+ await persist();
182
328
  await emitProgress(onProgress, { type: 'checkpoint-created' });
183
329
  }
330
+ return { results, persist };
331
+ }
184
332
 
185
- let completed = 0;
186
- let reused = 0;
187
- const repositoryResults = await mapLimit(selected, concurrency, async (repository, index) => {
333
+ async function scanSelectedRepositories(state) {
334
+ const { settings, selection } = state;
335
+ const counters = { completed: 0, reused: 0, active: 0 };
336
+ const repositoryResults = await mapLimit(
337
+ selection.selected,
338
+ settings.concurrency,
339
+ (repository, index) => processRepository(state, counters, repository, index),
340
+ );
341
+ return { ...counters, repositoryResults };
342
+ }
343
+
344
+ async function processRepository(state, counters, repository, index) {
345
+ const { settings, selection, checkpoint } = state;
346
+ const { onProgress, checkpointPath, concurrency } = settings;
347
+ const total = selection.selected.length;
348
+ counters.active += 1;
349
+ await emitProgress(onProgress, {
350
+ type: 'repository-started',
351
+ repository: repository.fullName,
352
+ position: index + 1,
353
+ total,
354
+ completed: counters.completed,
355
+ active: counters.active,
356
+ concurrency,
357
+ });
358
+ const emitPhase = phase => emitProgress(onProgress, {
359
+ type: 'repository-phase',
360
+ repository: repository.fullName,
361
+ position: index + 1,
362
+ total,
363
+ completed: counters.completed,
364
+ active: counters.active,
365
+ concurrency,
366
+ phase,
367
+ });
368
+ const { repositoryResult, wasReused } = await scanRepository(state, repository, emitPhase);
369
+ if (checkpointPath) {
370
+ await emitPhase('writing checkpoint');
371
+ checkpoint.results.set(repository.fullName.toLowerCase(), repositoryResult);
372
+ const durableRepositories = await checkpoint.persist();
188
373
  await emitProgress(onProgress, {
189
- type: 'repository-started',
374
+ type: 'checkpoint-written',
190
375
  repository: repository.fullName,
191
376
  position: index + 1,
192
- total: selected.length,
377
+ total,
378
+ repositories: durableRepositories,
193
379
  });
194
- let repositoryResult;
195
- let wasReused = false;
196
- try {
197
- const workflowTree = await fetchRepositoryWorkflowTree({
380
+ }
381
+ counters.completed += 1;
382
+ if (wasReused) counters.reused += 1;
383
+ counters.active -= 1;
384
+ await emitProgress(onProgress, {
385
+ type: 'repository-completed',
386
+ repository: repository.fullName,
387
+ position: index + 1,
388
+ total,
389
+ completed: counters.completed,
390
+ reused: wasReused,
391
+ status: repositoryResult.status,
392
+ files: repositoryResult.files.length,
393
+ findings: repositoryResult.findings.length,
394
+ errors: repositoryResult.errors.length,
395
+ active: counters.active,
396
+ concurrency,
397
+ });
398
+ return repositoryResult;
399
+ }
400
+
401
+ async function scanRepository(state, repository, emitPhase) {
402
+ try {
403
+ return await readOrReuseRepository(state, repository, emitPhase);
404
+ } catch (error) {
405
+ if (error instanceof ProgressCallbackError) throw error;
406
+ return {
407
+ repositoryResult: failedRepositoryResult(repository, error),
408
+ wasReused: false,
409
+ };
410
+ }
411
+ }
412
+
413
+ async function readOrReuseRepository(state, repository, emitPhase) {
414
+ const { settings, environment, loadedCheckpoint } = state;
415
+ const { cwd, onProgress } = settings;
416
+ const { config, resolvedToken } = environment;
417
+ await emitPhase('reading default-branch tree');
418
+ const workflowTree = await fetchRepositoryWorkflowTree({
419
+ repository,
420
+ token: resolvedToken,
421
+ cwd,
422
+ includePath: path => filterIgnoredPaths([
423
+ virtualPath(cwd, repository, path),
424
+ ], config, cwd).length > 0,
425
+ onRetry: retry => emitRetryProgress(onProgress, retry, repository.fullName),
426
+ });
427
+ const stored = loadedCheckpoint.results.get(repository.fullName.toLowerCase());
428
+ await emitPhase('checking resumable evidence');
429
+ if (stored && canReuseCheckpointResult(stored, repository, workflowTree.treeSha)) {
430
+ return {
431
+ repositoryResult: restoreCheckpointResult(stored, {
198
432
  repository,
199
- token: resolvedToken,
200
433
  cwd,
201
- includePath: path => filterIgnoredPaths([
202
- virtualPath(cwd, repository, path),
203
- ], config, cwd).length > 0,
204
- onRetry: retry => emitRetryProgress(onProgress, retry, repository.fullName),
205
- });
206
- const stored = loadedCheckpoint.results.get(repository.fullName.toLowerCase());
207
- if (stored && canReuseCheckpointResult(stored, repository, workflowTree.treeSha)) {
208
- repositoryResult = restoreCheckpointResult(stored, { repository, cwd, sourceUrl });
209
- wasReused = true;
210
- } else {
211
- const fetched = await fetchRepositoryWorkflows({
212
- repository,
213
- token: resolvedToken,
214
- cwd,
215
- workflowTree,
216
- onRetry: retry => emitRetryProgress(onProgress, retry, repository.fullName),
217
- });
218
- const sources = fetched.sources.map(item => ({
219
- file: virtualPath(cwd, repository, item.path),
220
- source: item.source,
221
- }));
222
- const auditResult = await auditSources({
223
- cwd,
224
- sources,
225
- severity,
226
- explain,
227
- config,
228
- baselineData,
229
- });
230
- const errors = fetched.errors.map(error => ({
231
- repository: repository.fullName,
232
- path: error.path,
233
- error: error.error,
234
- }));
235
- const findings = auditResult.findings.map(finding => ({
236
- ...finding,
237
- repository: repository.fullName,
238
- branch: repository.defaultBranch,
239
- url: sourceUrl(
240
- repository,
241
- canonicalPath(finding.file, resolve(cwd, repository.owner, repository.name)),
242
- finding.line,
243
- ),
244
- }));
245
- repositoryResult = {
246
- repository,
247
- revision: {
248
- branch: repository.defaultBranch,
249
- treeSha: fetched.treeSha,
250
- },
251
- files: auditResult.files.map(file => canonicalPath(
252
- file,
253
- resolve(cwd, repository.owner, repository.name),
254
- )),
255
- findings,
256
- errors,
257
- summary: auditResult.summary,
258
- status: auditResult.status === 'FAIL' || errors.length > 0 ? 'FAIL' : 'OK',
259
- };
260
- }
261
- } catch (error) {
262
- if (error instanceof ProgressCallbackError) throw error;
263
- repositoryResult = {
264
- repository,
265
- revision: { branch: repository.defaultBranch, treeSha: null },
266
- files: [],
267
- findings: [],
268
- errors: [{
269
- repository: repository.fullName,
270
- error: String(error.message ?? error),
271
- }],
272
- summary: emptySummary(),
273
- status: 'FAIL',
274
- };
275
- }
276
- if (checkpointPath) {
277
- checkpointResults.set(repository.fullName.toLowerCase(), repositoryResult);
278
- await persistCheckpoint();
279
- }
280
- completed += 1;
281
- if (wasReused) reused += 1;
282
- await emitProgress(onProgress, {
283
- type: 'repository-completed',
434
+ commitSha: workflowTree.commitSha,
435
+ }),
436
+ wasReused: true,
437
+ };
438
+ }
439
+ await emitPhase('downloading workflow YAML');
440
+ const fetched = await fetchRepositoryWorkflows({
441
+ repository,
442
+ token: resolvedToken,
443
+ cwd,
444
+ workflowTree,
445
+ onRetry: retry => emitRetryProgress(onProgress, retry, repository.fullName),
446
+ });
447
+ await emitPhase('auditing workflows');
448
+ return {
449
+ repositoryResult: await auditRepositoryResult(state, repository, fetched),
450
+ wasReused: false,
451
+ };
452
+ }
453
+
454
+ async function auditRepositoryResult(state, repository, fetched) {
455
+ const { cwd, severity, explain } = state.settings;
456
+ const { config, baselineData } = state.environment;
457
+ const repositoryRoot = resolve(cwd, repository.owner, repository.name);
458
+ const sources = fetched.sources.map(item => ({
459
+ file: virtualPath(cwd, repository, item.path),
460
+ source: item.source,
461
+ }));
462
+ const auditResult = await auditSources({
463
+ cwd,
464
+ sources,
465
+ severity,
466
+ explain,
467
+ config,
468
+ baselineData,
469
+ });
470
+ const blobShas = new Map(fetched.entries.map(entry => [entry.path, entry.blobSha]));
471
+ const link = (path, line) => sourcePermalink(repository, fetched.commitSha, path, line);
472
+ const errors = fetched.errors.map(error => ({
473
+ repository: repository.fullName,
474
+ path: error.path,
475
+ error: error.error,
476
+ permalink: link(error.path),
477
+ }));
478
+ const findings = auditResult.findings.map(finding => {
479
+ const path = canonicalPath(finding.file, repositoryRoot);
480
+ return {
481
+ ...finding,
284
482
  repository: repository.fullName,
285
- position: index + 1,
286
- total: selected.length,
287
- completed,
288
- reused: wasReused,
289
- status: repositoryResult.status,
290
- files: repositoryResult.files.length,
291
- findings: repositoryResult.findings.length,
292
- errors: repositoryResult.errors.length,
293
- });
294
- return repositoryResult;
483
+ branch: repository.defaultBranch,
484
+ url: sourceUrl(repository, path, finding.line),
485
+ path,
486
+ blobSha: blobShas.get(path) ?? null,
487
+ permalink: link(path, finding.line),
488
+ };
295
489
  });
490
+ return {
491
+ repository,
492
+ revision: {
493
+ branch: repository.defaultBranch,
494
+ treeSha: fetched.treeSha,
495
+ commitSha: fetched.commitSha,
496
+ },
497
+ files: auditResult.files.map(file => canonicalPath(file, repositoryRoot)),
498
+ fileDetails: buildFileDetails(fetched.entries, findings, link),
499
+ findings,
500
+ errors,
501
+ summary: auditResult.summary,
502
+ status: auditResult.status === 'FAIL' || errors.length > 0 ? 'FAIL' : 'OK',
503
+ };
504
+ }
296
505
 
506
+ function buildFileDetails(entries, findings, link) {
507
+ const counts = new Map();
508
+ const parseErrors = new Set();
509
+ for (const finding of findings) {
510
+ counts.set(finding.path, (counts.get(finding.path) ?? 0) + 1);
511
+ if (finding.ruleId === 'parse-error') parseErrors.add(finding.path);
512
+ }
513
+ return entries
514
+ .map(entry => ({
515
+ path: entry.path,
516
+ blobSha: entry.blobSha,
517
+ bytes: entry.bytes,
518
+ status: fileStatus(entry, parseErrors),
519
+ findings: counts.get(entry.path) ?? 0,
520
+ permalink: link(entry.path),
521
+ }))
522
+ .sort((left, right) => comparePaths(left.path, right.path));
523
+ }
524
+
525
+ function fileStatus(entry, parseErrors) {
526
+ if (!entry.readable) return 'unreadable';
527
+ return parseErrors.has(entry.path) ? 'parse-error' : 'scanned';
528
+ }
529
+
530
+ function failedRepositoryResult(repository, error) {
531
+ return {
532
+ repository,
533
+ revision: { branch: repository.defaultBranch, treeSha: null, commitSha: null },
534
+ files: [],
535
+ fileDetails: [],
536
+ findings: [],
537
+ errors: [{
538
+ repository: repository.fullName,
539
+ error: String(error.message ?? error),
540
+ }],
541
+ summary: emptySummary(),
542
+ status: 'FAIL',
543
+ };
544
+ }
545
+
546
+ function assembleOrganizationResult(state, repositoryResults) {
547
+ const { settings, environment, selection } = state;
548
+ const { checkpointIdentity, patterns, baselineData, config } = environment;
297
549
  const findings = repositoryResults.flatMap(result => result.findings);
298
550
  const errors = repositoryResults.flatMap(result => result.errors);
299
- const counts = summarize(findings);
300
- const summary = {
551
+ const summary = summarizeRepositoryResults(selection, repositoryResults, findings, errors);
552
+ return {
553
+ organization: settings.organization,
554
+ analysis: {
555
+ generation: checkpointIdentity.analysisGeneration,
556
+ identity: createHash('sha256')
557
+ .update(createOrganizationCheckpointArtifactKey(checkpointIdentity))
558
+ .digest('hex'),
559
+ },
560
+ scope: {
561
+ repositories: patterns,
562
+ visibility: settings.visibility,
563
+ includeArchived: settings.includeArchived,
564
+ includeDisabled: settings.includeDisabled,
565
+ includeForks: settings.includeForks,
566
+ maxRepositories: settings.maxRepositories ?? null,
567
+ concurrency: settings.concurrency,
568
+ severity: settings.severity ?? null,
569
+ },
570
+ coverage: describeCoverage(selection, repositoryResults),
571
+ repositories: repositoryResults,
572
+ findings,
573
+ errors,
574
+ summary,
575
+ baseline: {
576
+ path: baselineData.path,
577
+ suppressed: summary.suppressed,
578
+ },
579
+ configPath: config.path,
580
+ status: findings.length === 0 && errors.length === 0 ? 'OK' : 'FAIL',
581
+ };
582
+ }
583
+
584
+ function summarizeRepositoryResults(selection, repositoryResults, findings, errors) {
585
+ const { discovered, eligible, selected } = selection;
586
+ return {
301
587
  repositoriesDiscovered: discovered.length,
302
588
  repositoriesEligible: eligible.length,
303
589
  repositoriesSelected: selected.length,
@@ -314,125 +600,27 @@ export async function scanOrganization({
314
600
  ),
315
601
  suppressed: repositoryResults.reduce((total, result) => total + result.summary.suppressed, 0),
316
602
  errors: errors.length,
317
- ...counts,
603
+ ...summarize(findings),
318
604
  };
319
- const result = {
320
- organization,
321
- scope: {
322
- repositories: patterns,
323
- visibility,
324
- includeArchived,
325
- includeDisabled,
326
- includeForks,
327
- maxRepositories: maxRepositories ?? null,
328
- concurrency,
329
- severity: severity ?? null,
330
- },
331
- repositories: repositoryResults,
332
- findings,
333
- errors,
334
- summary,
335
- baseline: {
336
- path: baselineData.path,
337
- suppressed: summary.suppressed,
338
- },
339
- configPath: config.path,
340
- status: findings.length === 0 && errors.length === 0 ? 'OK' : 'FAIL',
341
- };
342
- await emitProgress(onProgress, {
343
- type: 'scan-completed',
344
- organization,
345
- status: result.status,
346
- total: selected.length,
347
- completed,
348
- reused,
349
- findings: summary.findings,
350
- errors: summary.errors,
351
- elapsedMs: Date.now() - startedAt,
352
- });
353
- return result;
354
605
  }
355
606
 
356
- export function renderOrganizationScan(result, { format: outputFormat, cwd = process.cwd() }) {
357
- if (outputFormat === 'json') {
358
- return format('json', [], {
359
- status: result.status,
360
- json: {
361
- schemaVersion: '1.0',
362
- organization: result.organization,
363
- scope: result.scope,
364
- repositories: result.repositories.map(repositoryResult => ({
365
- repository: repositoryResult.repository,
366
- revision: repositoryResult.revision,
367
- files: repositoryResult.files,
368
- findings: repositoryResult.findings.map(finding => normalizeFinding(finding, cwd)),
369
- errors: repositoryResult.errors,
370
- summary: repositoryResult.summary,
371
- status: repositoryResult.status,
372
- })),
373
- findings: result.findings.map(finding => normalizeFinding(finding, cwd)),
374
- errors: result.errors,
375
- summary: result.summary,
376
- baseline: {
377
- ...result.baseline,
378
- path: result.baseline.path ? canonicalPath(result.baseline.path, cwd) : null,
379
- },
380
- configPath: result.configPath ? canonicalPath(result.configPath, cwd) : null,
381
- status: result.status,
382
- },
383
- });
384
- }
385
-
386
- const records = [];
387
- if (outputFormat === 'sarif') {
388
- for (const rule of listRules()) records.push({ label: 'RULE', fields: rule });
389
- }
390
- for (const repositoryResult of result.repositories) {
391
- records.push({
392
- label: 'REPOSITORY',
393
- fields: {
394
- repo: repositoryResult.repository.fullName,
395
- visibility: repositoryResult.repository.visibility,
396
- branch: repositoryResult.revision.branch,
397
- files: repositoryResult.files.length,
398
- findings: repositoryResult.findings.length,
399
- errors: repositoryResult.errors.length,
400
- status: repositoryResult.status,
401
- },
402
- });
403
- for (const finding of repositoryResult.findings) {
404
- records.push({
405
- label: 'FINDING',
406
- fields: {
407
- id: finding.id,
408
- ...finding.fields,
409
- repo: finding.repository,
410
- file: canonicalPath(finding.file, cwd),
411
- line: finding.line,
412
- url: finding.url,
413
- ...(finding.explain ? { explain: finding.explain } : {}),
414
- ...(outputFormat === 'sarif' && finding.fingerprint
415
- ? { fingerprint: finding.fingerprint }
416
- : {}),
417
- },
418
- });
419
- }
420
- for (const error of repositoryResult.errors) {
421
- records.push({
422
- label: 'ERROR',
423
- fields: {
424
- repo: error.repository,
425
- file: error.path ? `${error.repository}/${error.path}` : undefined,
426
- msg: error.error,
427
- },
428
- });
429
- }
430
- }
431
- records.push({
432
- label: 'SUMMARY',
433
- fields: { organization: result.organization, ...result.summary },
434
- });
435
- return format(outputFormat, records, { status: result.status });
607
+ function describeCoverage(selection, repositoryResults) {
608
+ const { eligible, selected } = selection;
609
+ const incompleteRepositories = repositoryResults
610
+ .filter(repositoryResult => !repositoryCoverageComplete(repositoryResult))
611
+ .map(repositoryResult => repositoryResult.repository.fullName)
612
+ .sort((left, right) => left.localeCompare(right));
613
+ const selectedRepositoriesComplete = incompleteRepositories.length === 0;
614
+ const limitedByMaxRepositories = selected.length < eligible.length;
615
+ return {
616
+ complete: selectedRepositoriesComplete && !limitedByMaxRepositories,
617
+ enumerationComplete: true,
618
+ selectedRepositoriesComplete,
619
+ eligibleRepositoriesComplete: selectedRepositoriesComplete && !limitedByMaxRepositories,
620
+ limitedByMaxRepositories,
621
+ repositoriesOmittedByLimit: eligible.length - selected.length,
622
+ incompleteRepositories,
623
+ };
436
624
  }
437
625
 
438
626
  function selectRepositories(repositories, options) {
@@ -450,29 +638,6 @@ function selectRepositories(repositories, options) {
450
638
  });
451
639
  }
452
640
 
453
- function normalizePatterns(patterns) {
454
- if (patterns === undefined) return [];
455
- if (!Array.isArray(patterns) || patterns.some(pattern => typeof pattern !== 'string' || !pattern)) {
456
- throw new Error('repository filters must be non-empty strings');
457
- }
458
- return [...new Set(patterns)];
459
- }
460
-
461
- function normalizeFinding(finding, cwd) {
462
- return {
463
- ...finding,
464
- file: canonicalPath(finding.file, cwd),
465
- };
466
- }
467
-
468
- function sourceUrl(repository, path, line) {
469
- if (!repository.defaultBranch) return repository.htmlUrl;
470
- const encodedPath = path.split('/').map(encodeURIComponent).join('/');
471
- const encodedBranch = encodeURIComponent(repository.defaultBranch);
472
- const suffix = Number.isInteger(line) && line > 0 ? `#L${line}` : '';
473
- return `${repository.htmlUrl}/blob/${encodedBranch}/${encodedPath}${suffix}`;
474
- }
475
-
476
641
  function virtualPath(cwd, repository, path) {
477
642
  return resolve(cwd, repository.owner, repository.name, ...path.split('/'));
478
643
  }
@@ -480,7 +645,7 @@ function virtualPath(cwd, repository, path) {
480
645
  function createCheckpointWriter({ path, cwd, identity, results }) {
481
646
  let pending = Promise.resolve();
482
647
  return async function persistCheckpoint() {
483
- if (!path) return;
648
+ if (!path) return 0;
484
649
  const snapshot = [...results.values()];
485
650
  const write = pending.then(() => writeOrganizationCheckpoint({
486
651
  path,
@@ -490,23 +655,24 @@ function createCheckpointWriter({ path, cwd, identity, results }) {
490
655
  }));
491
656
  pending = write;
492
657
  await write;
658
+ return snapshot.length;
493
659
  };
494
660
  }
495
661
 
662
+ function repositoryCoverageComplete(repositoryResult) {
663
+ return repositoryResult.errors.length === 0
664
+ && !repositoryResult.findings.some(finding => finding.ruleId === 'parse-error');
665
+ }
666
+
496
667
  async function assertCheckpointDoesNotReplaceControlFile(path, cwd, controlFiles) {
497
668
  const requested = resolve(cwd, path);
498
- const checkpoint = comparablePath(join(await realpath(dirname(requested)), basename(requested)));
499
669
  for (const controlFile of controlFiles) {
500
- if (controlFile && comparablePath(resolve(controlFile)) === checkpoint) {
670
+ if (controlFile && await sameFilePath(requested, resolve(controlFile))) {
501
671
  throw new Error('checkpoint path cannot replace the active config or baseline');
502
672
  }
503
673
  }
504
674
  }
505
675
 
506
- function comparablePath(path) {
507
- return process.platform === 'win32' ? path.toLowerCase() : path;
508
- }
509
-
510
676
  async function emitRetryProgress(onProgress, retry, repository) {
511
677
  await emitProgress(onProgress, {
512
678
  type: 'request-retry',