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
@@ -6,20 +6,46 @@
6
6
  */
7
7
 
8
8
  import { TextDecoder } from 'node:util';
9
+ import { GIT_SHA_RE, NAME_RE, REPOSITORY_VISIBILITIES } from './org-schema.js';
9
10
  import { ghFetch } from './resolver.js';
10
11
 
11
12
  const API = 'https://api.github.com';
12
- const NAME_RE = /^[A-Za-z0-9_.-]+$/;
13
- const SHA_RE = /^[0-9a-f]{40}$/i;
13
+
14
+ /** HTTP status GitHub returns for Git requests against a repository with no commits. */
15
+ const EMPTY_REPOSITORY_STATUS = 409;
16
+
17
+ /** Maximum decoded bytes accepted for one remote workflow YAML blob. */
14
18
  export const MAX_WORKFLOW_BYTES = 2 * 1024 * 1024;
19
+
20
+ /** Maximum workflow and composite-action files accepted per repository. */
15
21
  export const MAX_WORKFLOW_FILES = 1000;
22
+
23
+ /** Maximum cumulative decoded workflow bytes accepted per repository. */
16
24
  export const MAX_REPOSITORY_WORKFLOW_BYTES = 32 * 1024 * 1024;
17
25
 
18
26
  /**
19
27
  * List every repository visible to the supplied token for an organization.
28
+ * The optional page observer receives only bounded counters and sanitized
29
+ * GitHub rate-limit metadata; repository objects remain in the final result.
30
+ *
31
+ * @param {object} [options]
32
+ * @param {string} options.organization
33
+ * @param {string} [options.token]
34
+ * @param {string} [options.cwd]
35
+ * @param {(event: object) => void|Promise<void>} [options.onRetry]
36
+ * @param {(event: object) => void|Promise<void>} [options.onPage]
20
37
  */
21
- export async function listOrganizationRepositories({ organization, token, cwd, onRetry } = {}) {
38
+ export async function listOrganizationRepositories({
39
+ organization,
40
+ token,
41
+ cwd,
42
+ onRetry,
43
+ onPage,
44
+ } = {}) {
22
45
  const org = validateName(organization, 'organization');
46
+ if (onPage !== undefined && typeof onPage !== 'function') {
47
+ throw new Error('onPage must be a function');
48
+ }
23
49
  const repositories = [];
24
50
  const seen = new Set();
25
51
 
@@ -31,12 +57,16 @@ export async function listOrganizationRepositories({ organization, token, cwd, o
31
57
  per_page: '100',
32
58
  page: String(page),
33
59
  });
60
+ let responseMetadata;
34
61
  const response = await ghFetch({
35
62
  url: `${API}/orgs/${encodeURIComponent(org)}/repos?${query}`,
36
63
  token,
37
64
  cwd,
38
65
  useCache: false,
39
66
  onRetry,
67
+ onResponse: event => {
68
+ responseMetadata = event;
69
+ },
40
70
  });
41
71
  if (response.status !== 200) {
42
72
  throw new Error(`could not list repositories for ${org} (HTTP ${response.status})`);
@@ -52,6 +82,13 @@ export async function listOrganizationRepositories({ organization, token, cwd, o
52
82
  seen.add(key);
53
83
  repositories.push(repository);
54
84
  }
85
+ if (onPage) {
86
+ await onPage(Object.freeze({
87
+ page,
88
+ repositoriesDiscovered: repositories.length,
89
+ rateLimit: responseMetadata?.rateLimit ?? null,
90
+ }));
91
+ }
55
92
  if (response.body.length < 100) {
56
93
  return repositories.sort((left, right) => left.fullName.localeCompare(right.fullName));
57
94
  }
@@ -61,6 +98,8 @@ export async function listOrganizationRepositories({ organization, token, cwd, o
61
98
 
62
99
  /**
63
100
  * Fetch and validate the workflow-bearing portion of a repository tree.
101
+ * The default-branch commit is resolved first and the tree is then read by that
102
+ * commit's tree SHA, so the evidence and its permalinks describe one revision.
64
103
  * The returned snapshot can be compared with a checkpoint before any blobs
65
104
  * are downloaded.
66
105
  */
@@ -75,65 +114,39 @@ export async function fetchRepositoryWorkflowTree({
75
114
  if (includePath !== undefined && typeof includePath !== 'function') {
76
115
  throw new Error('includePath must be a function');
77
116
  }
78
- if (!normalized.defaultBranch) {
79
- return workflowTree(normalized, { entries: [], empty: true, treeSha: null });
80
- }
81
- const treeUrl = `${API}/repos/${encodeURIComponent(normalized.owner)}`
82
- + `/${encodeURIComponent(normalized.name)}/git/trees/`
83
- + `${encodeURIComponent(normalized.defaultBranch)}?recursive=1`;
117
+ const emptyTree = () => workflowTree(normalized, {
118
+ entries: [],
119
+ empty: true,
120
+ treeSha: null,
121
+ commitSha: null,
122
+ });
123
+ if (!normalized.defaultBranch) return emptyTree();
124
+ const commit = await fetchDefaultBranchCommit({ repository: normalized, token, cwd, onRetry });
125
+ if (commit === null) return emptyTree();
126
+
84
127
  const treeResponse = await ghFetch({
85
- url: treeUrl,
128
+ url: `${repositoryApiUrl(normalized)}/git/trees/${commit.treeSha}?recursive=1`,
86
129
  token,
87
130
  cwd,
88
131
  useCache: false,
89
132
  onRetry,
90
133
  });
91
- if (treeResponse.status === 409) {
92
- return workflowTree(normalized, { entries: [], empty: true, treeSha: null });
93
- }
94
134
  if (treeResponse.status !== 200) {
95
- throw new Error(`could not read ${normalized.fullName}@${normalized.defaultBranch} tree (HTTP ${treeResponse.status})`);
96
- }
97
- if (!treeResponse.body || typeof treeResponse.body !== 'object' || !Array.isArray(treeResponse.body.tree)) {
98
- throw new Error(`invalid tree response for ${normalized.fullName}`);
99
- }
100
- if (typeof treeResponse.body.truncated !== 'boolean') {
101
- throw new Error(`invalid tree truncation state for ${normalized.fullName}`);
102
- }
103
- if (!SHA_RE.test(String(treeResponse.body.sha ?? ''))) {
104
- throw new Error(`invalid tree SHA for ${normalized.fullName}`);
105
- }
106
- if (treeResponse.body.truncated === true) {
107
- throw new Error(`tree response for ${normalized.fullName} was truncated; refusing an incomplete scan`);
108
- }
109
-
110
- const entries = treeResponse.body.tree
111
- .filter(entry => (
112
- entry?.type === 'blob'
113
- && isWorkflowPath(entry.path)
114
- && (includePath === undefined || includePath(entry.path))
115
- ))
116
- .sort((left, right) => left.path.localeCompare(right.path));
117
- if (entries.length > MAX_WORKFLOW_FILES) {
118
- throw new Error(
119
- `${normalized.fullName} has more than ${MAX_WORKFLOW_FILES} workflow files; refusing an unbounded scan`,
120
- );
121
- }
122
- const declaredBytes = entries.reduce(
123
- (total, entry) => total + (
124
- Number.isSafeInteger(entry.size) && entry.size >= 0 ? entry.size : 0
125
- ),
126
- 0,
127
- );
128
- if (declaredBytes > MAX_REPOSITORY_WORKFLOW_BYTES) {
129
135
  throw new Error(
130
- `${normalized.fullName} workflow sources exceed the ${MAX_REPOSITORY_WORKFLOW_BYTES}-byte repository limit`,
136
+ `could not read ${normalized.fullName}@${normalized.defaultBranch} tree`
137
+ + ` (HTTP ${treeResponse.status})`,
131
138
  );
132
139
  }
140
+ const entries = selectWorkflowEntries(treeResponse.body, {
141
+ repository: normalized,
142
+ expectedTreeSha: commit.treeSha,
143
+ includePath,
144
+ });
133
145
  return workflowTree(normalized, {
134
146
  entries,
135
147
  empty: false,
136
- treeSha: String(treeResponse.body.sha).toLowerCase(),
148
+ treeSha: commit.treeSha,
149
+ commitSha: commit.commitSha,
137
150
  });
138
151
  }
139
152
 
@@ -160,62 +173,39 @@ export async function fetchRepositoryWorkflows({
160
173
  onRetry,
161
174
  });
162
175
  validateWorkflowTree(tree, normalized);
163
- if (tree.empty) {
164
- return { sources: [], errors: [], empty: true, treeSha: tree.treeSha };
165
- }
176
+ const result = {
177
+ sources: [],
178
+ errors: [],
179
+ entries: [],
180
+ empty: tree.empty,
181
+ treeSha: tree.treeSha,
182
+ commitSha: tree.commitSha,
183
+ };
184
+ if (tree.empty) return result;
166
185
 
167
- const sources = [];
168
- const errors = [];
169
186
  let sourceBytes = 0;
187
+ const request = { owner: normalized.owner, repo: normalized.name, token, cwd, onRetry };
170
188
  for (const entry of tree.entries) {
171
- if (!SHA_RE.test(String(entry.sha ?? ''))) {
172
- errors.push({ path: entry.path, error: 'workflow tree entry has an invalid blob SHA' });
189
+ const outcome = await readWorkflowEntry(entry, request);
190
+ result.entries.push(outcome.detail);
191
+ if (outcome.error) {
192
+ result.errors.push({ path: entry.path, error: outcome.error });
173
193
  continue;
174
194
  }
175
- if (
176
- entry.size !== undefined
177
- && (!Number.isSafeInteger(entry.size) || entry.size < 0)
178
- ) {
179
- errors.push({ path: entry.path, error: 'workflow tree entry has an invalid size' });
180
- continue;
181
- }
182
- if (Number.isFinite(entry.size) && entry.size > MAX_WORKFLOW_BYTES) {
183
- errors.push({
184
- path: entry.path,
185
- error: `workflow exceeds the ${MAX_WORKFLOW_BYTES}-byte scan limit`,
186
- });
187
- continue;
188
- }
189
- let source;
190
- try {
191
- source = await fetchBlobText({
192
- owner: normalized.owner,
193
- repo: normalized.name,
194
- sha: entry.sha,
195
- token,
196
- cwd,
197
- onRetry,
198
- });
199
- } catch (error) {
200
- errors.push({ path: entry.path, error: String(error.message ?? error) });
201
- continue;
202
- }
203
- sourceBytes += Buffer.byteLength(source);
204
- if (sourceBytes > MAX_REPOSITORY_WORKFLOW_BYTES) {
205
- throw new Error(
206
- `${normalized.fullName} workflow sources exceed the ${MAX_REPOSITORY_WORKFLOW_BYTES}-byte repository limit`,
207
- );
208
- }
209
- sources.push({ path: entry.path, source, sha: String(entry.sha).toLowerCase() });
195
+ sourceBytes += Buffer.byteLength(outcome.text);
196
+ if (sourceBytes > MAX_REPOSITORY_WORKFLOW_BYTES) throw repositoryLimitError(normalized);
197
+ result.sources.push({ path: entry.path, source: outcome.text, sha: outcome.detail.blobSha });
210
198
  }
211
- return {
212
- sources,
213
- errors,
214
- empty: false,
215
- treeSha: tree.treeSha,
216
- };
199
+ return result;
217
200
  }
218
201
 
202
+ /**
203
+ * Return whether a validated Git tree path belongs to the supported workflow
204
+ * or composite-action discovery scope.
205
+ *
206
+ * @param {unknown} path
207
+ * @returns {boolean}
208
+ */
219
209
  export function isWorkflowPath(path) {
220
210
  if (
221
211
  typeof path !== 'string'
@@ -267,13 +257,127 @@ async function fetchBlobText({ owner, repo, sha, token, cwd, onRetry }) {
267
257
  throw new Error(`workflow blob ${sha} size did not match its metadata`);
268
258
  }
269
259
  try {
270
- return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
260
+ return { text: new TextDecoder('utf-8', { fatal: true }).decode(bytes), bytes: bytes.length };
271
261
  } catch {
272
262
  throw new Error(`workflow blob ${sha} is not valid UTF-8`);
273
263
  }
274
264
  }
275
265
 
276
- function workflowTree(repository, { entries, empty, treeSha }) {
266
+ async function readWorkflowEntry(entry, request) {
267
+ const blobSha = GIT_SHA_RE.test(String(entry.sha ?? ''))
268
+ ? String(entry.sha).toLowerCase()
269
+ : null;
270
+ const treeBytes = Number.isSafeInteger(entry.size) && entry.size >= 0 ? entry.size : null;
271
+ const unreadable = error => ({
272
+ detail: { path: entry.path, blobSha, bytes: treeBytes, readable: false },
273
+ error,
274
+ });
275
+ const failure = checkEntryReadable(entry);
276
+ if (failure) return unreadable(failure);
277
+ try {
278
+ const blob = await fetchBlobText({ ...request, sha: entry.sha });
279
+ return {
280
+ detail: { path: entry.path, blobSha, bytes: blob.bytes, readable: true },
281
+ text: blob.text,
282
+ };
283
+ } catch (error) {
284
+ return unreadable(String(error.message ?? error));
285
+ }
286
+ }
287
+
288
+ function repositoryLimitError(repository) {
289
+ return new Error(
290
+ `${repository.fullName} workflow sources exceed`
291
+ + ` the ${MAX_REPOSITORY_WORKFLOW_BYTES}-byte repository limit`,
292
+ );
293
+ }
294
+
295
+ async function fetchDefaultBranchCommit({ repository, token, cwd, onRetry }) {
296
+ const response = await ghFetch({
297
+ url: `${repositoryApiUrl(repository)}/commits/heads/`
298
+ + encodeURIComponent(repository.defaultBranch),
299
+ token,
300
+ cwd,
301
+ useCache: false,
302
+ onRetry,
303
+ });
304
+ if (response.status === EMPTY_REPOSITORY_STATUS) return null;
305
+ if (response.status !== 200) {
306
+ throw new Error(
307
+ `could not read ${repository.fullName}@${repository.defaultBranch} commit`
308
+ + ` (HTTP ${response.status})`,
309
+ );
310
+ }
311
+ const commitSha = String(response.body?.sha ?? '');
312
+ const treeSha = String(response.body?.commit?.tree?.sha ?? '');
313
+ if (!GIT_SHA_RE.test(commitSha) || !GIT_SHA_RE.test(treeSha)) {
314
+ throw new Error(`invalid commit response for ${repository.fullName}`);
315
+ }
316
+ return { commitSha: commitSha.toLowerCase(), treeSha: treeSha.toLowerCase() };
317
+ }
318
+
319
+ function selectWorkflowEntries(body, { repository, expectedTreeSha, includePath }) {
320
+ if (!body || typeof body !== 'object' || !Array.isArray(body.tree)) {
321
+ throw new Error(`invalid tree response for ${repository.fullName}`);
322
+ }
323
+ if (typeof body.truncated !== 'boolean') {
324
+ throw new Error(`invalid tree truncation state for ${repository.fullName}`);
325
+ }
326
+ if (!GIT_SHA_RE.test(String(body.sha ?? ''))) {
327
+ throw new Error(`invalid tree SHA for ${repository.fullName}`);
328
+ }
329
+ if (String(body.sha).toLowerCase() !== expectedTreeSha) {
330
+ throw new Error(`tree response for ${repository.fullName} did not match the commit`);
331
+ }
332
+ if (body.truncated === true) {
333
+ throw new Error(
334
+ `tree response for ${repository.fullName} was truncated; refusing an incomplete scan`,
335
+ );
336
+ }
337
+ const entries = body.tree
338
+ .filter(entry => (
339
+ entry?.type === 'blob'
340
+ && isWorkflowPath(entry.path)
341
+ && (includePath === undefined || includePath(entry.path))
342
+ ))
343
+ .sort((left, right) => left.path.localeCompare(right.path));
344
+ if (entries.length > MAX_WORKFLOW_FILES) {
345
+ throw new Error(
346
+ `${repository.fullName} has more than ${MAX_WORKFLOW_FILES} workflow files;`
347
+ + ' refusing an unbounded scan',
348
+ );
349
+ }
350
+ const declaredBytes = entries.reduce(
351
+ (total, entry) => total + (
352
+ Number.isSafeInteger(entry.size) && entry.size >= 0 ? entry.size : 0
353
+ ),
354
+ 0,
355
+ );
356
+ if (declaredBytes > MAX_REPOSITORY_WORKFLOW_BYTES) {
357
+ throw repositoryLimitError(repository);
358
+ }
359
+ return entries;
360
+ }
361
+
362
+ function checkEntryReadable(entry) {
363
+ if (!GIT_SHA_RE.test(String(entry.sha ?? ''))) {
364
+ return 'workflow tree entry has an invalid blob SHA';
365
+ }
366
+ if (entry.size !== undefined && (!Number.isSafeInteger(entry.size) || entry.size < 0)) {
367
+ return 'workflow tree entry has an invalid size';
368
+ }
369
+ if (Number.isFinite(entry.size) && entry.size > MAX_WORKFLOW_BYTES) {
370
+ return `workflow exceeds the ${MAX_WORKFLOW_BYTES}-byte scan limit`;
371
+ }
372
+ return null;
373
+ }
374
+
375
+ function repositoryApiUrl(repository) {
376
+ return `${API}/repos/${encodeURIComponent(repository.owner)}`
377
+ + `/${encodeURIComponent(repository.name)}`;
378
+ }
379
+
380
+ function workflowTree(repository, { entries, empty, treeSha, commitSha }) {
277
381
  return {
278
382
  repository: repository.fullName,
279
383
  branch: repository.defaultBranch,
@@ -285,6 +389,7 @@ function workflowTree(repository, { entries, empty, treeSha }) {
285
389
  })),
286
390
  empty,
287
391
  treeSha,
392
+ commitSha,
288
393
  };
289
394
  }
290
395
 
@@ -296,14 +401,15 @@ function validateWorkflowTree(tree, repository) {
296
401
  || tree.branch !== repository.defaultBranch
297
402
  || typeof tree.empty !== 'boolean'
298
403
  || !Array.isArray(tree.entries)
299
- || (tree.treeSha !== null && !SHA_RE.test(String(tree.treeSha)))
404
+ || (tree.treeSha !== null && !GIT_SHA_RE.test(String(tree.treeSha)))
405
+ || (tree.commitSha !== null && !GIT_SHA_RE.test(String(tree.commitSha)))
300
406
  ) {
301
407
  throw new Error(`invalid workflow tree snapshot for ${repository.fullName}`);
302
408
  }
303
409
  if (tree.empty && tree.entries.length > 0) {
304
410
  throw new Error(`invalid workflow tree snapshot for ${repository.fullName}`);
305
411
  }
306
- if (!tree.empty && tree.treeSha === null) {
412
+ if (!tree.empty && (tree.treeSha === null || tree.commitSha === null)) {
307
413
  throw new Error(`invalid workflow tree snapshot for ${repository.fullName}`);
308
414
  }
309
415
  if (tree.entries.length > MAX_WORKFLOW_FILES) {
@@ -340,7 +446,7 @@ function normalizeRepository(raw, expectedOwner) {
340
446
  const defaultBranch = suppliedDefaultBranch == null
341
447
  ? null
342
448
  : validateRef(String(suppliedDefaultBranch));
343
- const visibility = ['public', 'private', 'internal'].includes(raw.visibility)
449
+ const visibility = REPOSITORY_VISIBILITIES.includes(raw.visibility)
344
450
  ? raw.visibility
345
451
  : raw.private === true ? 'private' : 'public';
346
452
  return {
@@ -0,0 +1,211 @@
1
+ /**
2
+ * Safe organization-scan artifact defaults.
3
+ *
4
+ * There is no reliable cross-agent runtime signal, so callers select an
5
+ * execution context explicitly. Context controls presentation defaults only;
6
+ * automatic organization artifacts always derive from the same scan identity.
7
+ */
8
+
9
+ import { resolve } from 'node:path';
10
+ import { emptyBaseline, loadBaseline } from './baseline.js';
11
+ import { loadConfig } from './config.js';
12
+ import { format } from './formatter.js';
13
+ import {
14
+ createOrganizationCheckpointArtifactKey,
15
+ createOrganizationCheckpointIdentity,
16
+ } from './org-checkpoint.js';
17
+ import { NAME_RE, normalizePatterns } from './org-schema.js';
18
+ import { pathExists } from './paths.js';
19
+ import { RULES } from '../rules/index.js';
20
+ import { VERSION } from '../version.js';
21
+
22
+ /** Preferred execution-context environment variable. */
23
+ export const EXECUTION_CONTEXT_ENVIRONMENT_VARIABLE = 'ACTIONS_WARDEN_CONTEXT';
24
+
25
+ const EXECUTION_CONTEXTS = new Set(['agent', 'auto', 'ci', 'interactive']);
26
+
27
+ const REPORT_EXTENSIONS = Object.freeze({
28
+ csv: 'csv',
29
+ html: 'html',
30
+ json: 'json',
31
+ sarif: 'sarif',
32
+ text: 'txt',
33
+ toon: 'toon',
34
+ });
35
+ const ARTIFACT_PREFIX = '.actions-warden-org-scan';
36
+
37
+ /**
38
+ * Resolve CLI flag precedence over the ACTIONS_WARDEN_CONTEXT environment
39
+ * variable. Returns `auto` when neither selects a context.
40
+ */
41
+ export function resolveExecutionContext({
42
+ optionValue,
43
+ optionSource,
44
+ environmentValue,
45
+ } = {}) {
46
+ if (optionSource === 'cli') return optionValue ? 'agent' : 'auto';
47
+ if (environmentValue !== undefined && String(environmentValue).trim() !== '') {
48
+ const context = String(environmentValue).trim().toLowerCase();
49
+ if (!EXECUTION_CONTEXTS.has(context)) {
50
+ throw new Error(
51
+ `${EXECUTION_CONTEXT_ENVIRONMENT_VARIABLE} must be agent, auto, ci, or interactive`,
52
+ );
53
+ }
54
+ return context;
55
+ }
56
+ return 'auto';
57
+ }
58
+
59
+ /**
60
+ * Build stable, scope-specific paths for an organization scan.
61
+ *
62
+ * @param {object} options
63
+ * @param {string} options.organization
64
+ * @param {string} options.cwd
65
+ * @param {string[]} [options.repositories]
66
+ * @param {'all'|'public'|'private'|'internal'} options.visibility
67
+ * @param {boolean} options.includeArchived
68
+ * @param {boolean} options.includeDisabled
69
+ * @param {boolean} options.includeForks
70
+ * @param {number} [options.maxRepositories]
71
+ * @param {'low'|'medium'|'high'|'critical'} [options.severity]
72
+ * @param {boolean} options.explain
73
+ * @param {string|false} [options.configPath]
74
+ * @param {string} [options.baseline]
75
+ * @param {'toon'|'json'|'text'|'csv'|'sarif'|'html'} options.reportFormat
76
+ */
77
+ export async function createOrganizationScanArtifacts({
78
+ organization,
79
+ cwd,
80
+ repositories,
81
+ visibility,
82
+ includeArchived,
83
+ includeDisabled,
84
+ includeForks,
85
+ maxRepositories,
86
+ severity,
87
+ explain,
88
+ configPath,
89
+ baseline,
90
+ reportFormat,
91
+ }) {
92
+ validateOrganization(organization);
93
+ const patterns = normalizePatterns(repositories);
94
+ const config = await loadConfig({
95
+ cwd,
96
+ path: configPath,
97
+ ruleIds: RULES.map(rule => rule.id),
98
+ });
99
+ const baselinePath = baseline ?? config.baseline;
100
+ const baselineData = baselinePath
101
+ ? await loadBaseline({ path: baselinePath, cwd })
102
+ : emptyBaseline();
103
+ const identity = createOrganizationCheckpointIdentity({
104
+ organization,
105
+ repositories: patterns,
106
+ visibility,
107
+ includeArchived,
108
+ includeDisabled,
109
+ includeForks,
110
+ maxRepositories,
111
+ severity,
112
+ explain,
113
+ config,
114
+ baselineData,
115
+ });
116
+ const key = createOrganizationCheckpointArtifactKey(identity);
117
+ const groupedKey = key.match(/.{8}/g).join('.');
118
+ const checkpointPath = `${ARTIFACT_PREFIX}.${groupedKey}.checkpoint.json`;
119
+ const reportExtension = REPORT_EXTENSIONS[reportFormat];
120
+ if (!reportExtension) throw new Error(`invalid organization report format: ${reportFormat}`);
121
+ const reportPath = `${ARTIFACT_PREFIX}.${groupedKey}.report.${reportExtension}`;
122
+
123
+ return {
124
+ checkpointPath,
125
+ reportPath,
126
+ resume: await pathExists(resolve(cwd, checkpointPath)),
127
+ configPath: config.path,
128
+ baselinePath: baselineData.path,
129
+ };
130
+ }
131
+
132
+ /**
133
+ * Render the bounded stdout contract emitted after an organization file report.
134
+ * Run provenance (tool version and timing) appears only here, never in the
135
+ * deterministic report, aggregate, or manifest.
136
+ *
137
+ * @param {object} options
138
+ * @param {Date} options.startedAt When the run began.
139
+ * @param {Date} options.finishedAt When the report was written.
140
+ */
141
+ export function renderOrganizationScanReceipt({
142
+ result,
143
+ startedAt,
144
+ finishedAt,
145
+ reportPath,
146
+ reportFormat,
147
+ checkpointPath,
148
+ resumed,
149
+ repositoriesReused = 0,
150
+ reportLayout = 'single',
151
+ reportDirectory,
152
+ manifestPath,
153
+ kind = 'actions-warden-org-scan-receipt',
154
+ }) {
155
+ return format('json', [], {
156
+ status: result.status,
157
+ json: {
158
+ schemaVersion: '1.0',
159
+ kind,
160
+ command: 'org-scan',
161
+ organization: result.organization,
162
+ tool: { name: 'actions-warden', version: VERSION },
163
+ run: {
164
+ startedAt: startedAt.toISOString(),
165
+ finishedAt: finishedAt.toISOString(),
166
+ durationMs: Math.max(0, finishedAt.getTime() - startedAt.getTime()),
167
+ },
168
+ status: result.status,
169
+ summary: result.summary,
170
+ report: {
171
+ path: reportPath,
172
+ format: reportFormat,
173
+ layout: reportLayout,
174
+ ...(reportDirectory ? { directory: reportDirectory } : {}),
175
+ ...(manifestPath ? { manifest: manifestPath } : {}),
176
+ },
177
+ checkpoint: {
178
+ path: checkpointPath,
179
+ resumed,
180
+ repositoriesReused,
181
+ },
182
+ coverage: compactCoverage(result.coverage),
183
+ ...(result.comparison ? { comparison: result.comparison.summary } : {}),
184
+ },
185
+ });
186
+ }
187
+
188
+ function compactCoverage(coverage = {}) {
189
+ return {
190
+ complete: coverage.complete === true,
191
+ enumerationComplete: coverage.enumerationComplete === true,
192
+ selectedRepositoriesComplete: coverage.selectedRepositoriesComplete === true,
193
+ eligibleRepositoriesComplete: coverage.eligibleRepositoriesComplete === true,
194
+ limitedByMaxRepositories: coverage.limitedByMaxRepositories === true,
195
+ repositoriesOmittedByLimit: Number.isSafeInteger(coverage.repositoriesOmittedByLimit)
196
+ ? coverage.repositoriesOmittedByLimit
197
+ : 0,
198
+ incompleteRepositories: Array.isArray(coverage.incompleteRepositories)
199
+ ? coverage.incompleteRepositories.length
200
+ : 0,
201
+ };
202
+ }
203
+
204
+ function validateOrganization(organization) {
205
+ if (
206
+ typeof organization !== 'string'
207
+ || !NAME_RE.test(organization)
208
+ || organization === '.'
209
+ || organization === '..'
210
+ ) throw new Error('invalid organization');
211
+ }