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