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