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
@@ -32,6 +32,76 @@ const { audit } = await import('actions-warden');
32
32
  The raw API result does not include `schemaVersion`; renderers add the versioned
33
33
  wire format.
34
34
 
35
+ ## Complete root export reference
36
+
37
+ The package root deliberately exposes a finite public surface. Every export is
38
+ listed here; adding an export without a non-empty reference entry fails
39
+ `npm run check:docs`.
40
+
41
+ | export | category | contract |
42
+ |---|---|---|
43
+ | `audit` | command | Audit discovered or selected local workflow files |
44
+ | `auditSources` | command | Audit caller-supplied YAML sources entirely in memory |
45
+ | `renderAudit` | renderer | Serialize an audit result in a supported output format |
46
+ | `pin` | command | Plan or explicitly apply immutable SHA pins |
47
+ | `renderPin` | renderer | Serialize a pin result in a supported output format |
48
+ | `rewriteUses` | rewrite utility | Return source with one parsed action reference rewritten to a SHA |
49
+ | `upgrade` | command | Plan or explicitly apply cooldown-aware dependency upgrades |
50
+ | `renderUpgrade` | renderer | Serialize an upgrade result in a supported output format |
51
+ | `report` | command | Combine audit, dry-run pin, and dry-run upgrade results |
52
+ | `renderReport` | renderer | Serialize a combined report result |
53
+ | `verify` | command | Verify SHA ownership and version metadata against GitHub |
54
+ | `renderVerify` | renderer | Serialize a verification result |
55
+ | `scanOrganization` | command | Audit eligible organization repositories through read-only GitHub APIs |
56
+ | `renderOrganizationScan` | renderer | Serialize an organization scan result |
57
+ | `compareOrganizationReports` | comparison | Classify new, resolved, unchanged, and unknown findings across compatible organization reports |
58
+ | `loadOrganizationReport` | comparison | Safely load and validate a bounded organization JSON report inside the working directory |
59
+ | `listRules` | rule catalog | Return the live rule IDs, default severities, and descriptions |
60
+ | `parseWorkflowFile` | parser | Read and parse one workflow or composite-action YAML file |
61
+ | `parseWorkflowSource` | parser | Parse one supplied YAML string without executing it |
62
+ | `collectUses` | parser utility | Return external, reusable, local, and Docker action references from a parsed document |
63
+ | `collectImages` | parser utility | Return job, service, and Docker-action image references from a parsed document |
64
+ | `parseActionRef` | parser utility | Classify one `uses` scalar while preserving source location metadata |
65
+ | `format` | formatter | Dispatch records to TOON, JSON, text, CSV, SARIF, or HTML rendering |
66
+ | `renderToon` | formatter | Render line-oriented TOON records |
67
+ | `renderJson` | formatter | Render recursively redacted, indented JSON |
68
+ | `renderText` | formatter | Render escaped human-readable records |
69
+ | `renderCsv` | formatter | Render deterministic, control-safe, spreadsheet-safe CSV records |
70
+ | `renderSarif` | formatter | Render SARIF 2.1.0 results |
71
+ | `renderHtml` | formatter | Render a deterministic, self-contained, searchable HTML report |
72
+ | `summarize` | formatter utility | Count findings by severity |
73
+ | `SEVERITY_ORDER` | constant | Lowest-to-highest severity ordering |
74
+ | `discoverWorkflows` | discovery | Discover default or caller-selected workflow paths inside a repository |
75
+ | `redact` | security utility | Replace credential-like substrings in one value |
76
+ | `parseIgnoreDirectives` | ignore utility | Parse line, block, next-line, and file ignore directives |
77
+ | `isIgnored` | ignore utility | Test whether a rule occurrence is inside an ignore scope |
78
+ | `loadConfig` | policy | Discover, load, and strictly normalize repository policy |
79
+ | `DEFAULT_CONFIG` | policy constant | Normalized built-in policy used when no config file is active |
80
+ | `listOrganizationRepositories` | GitHub reader | List every organization repository visible to the supplied token |
81
+ | `fetchRepositoryWorkflowTree` | GitHub reader | Fetch and validate a default-branch workflow tree snapshot |
82
+ | `fetchRepositoryWorkflows` | GitHub reader | Fetch bounded workflow YAML blobs from a validated tree |
83
+ | `isWorkflowPath` | GitHub reader utility | Test whether a Git tree path is in remote workflow discovery scope |
84
+ | `MAX_WORKFLOW_BYTES` | limit | Maximum decoded bytes accepted for one remote YAML file |
85
+ | `MAX_WORKFLOW_FILES` | limit | Maximum remote workflow files accepted per repository |
86
+ | `MAX_REPOSITORY_WORKFLOW_BYTES` | limit | Maximum cumulative decoded YAML bytes accepted per repository |
87
+ | `loadBaseline` | baseline | Load and validate accepted finding IDs and fingerprints |
88
+ | `serializeBaseline` | baseline | Serialize reviewed findings deterministically, excluding parser failures |
89
+ | `assignBaselineFingerprints` | baseline | Attach stable semantic fingerprints to finding objects |
90
+
91
+ ## Package entry points
92
+
93
+ The command modules are also available as explicit package subpaths. Each
94
+ subpath exposes the exports declared by its referenced command module.
95
+
96
+ | entry point | primary exports |
97
+ |---|---|
98
+ | `actions-warden/commands/audit` | `audit`, `auditSources`, `renderAudit` |
99
+ | `actions-warden/commands/pin` | `pin`, `renderPin`, `rewriteUses` |
100
+ | `actions-warden/commands/upgrade` | `upgrade`, `renderUpgrade` |
101
+ | `actions-warden/commands/report` | `report`, `renderReport` |
102
+ | `actions-warden/commands/verify` | `verify`, `renderVerify` |
103
+ | `actions-warden/commands/org-scan` | `scanOrganization`, `renderOrganizationScan` |
104
+
35
105
  ## Command functions
36
106
 
37
107
  ### `audit(options)`
@@ -93,6 +163,30 @@ does not execute supplied YAML.
93
163
  When passing a custom config, use the normalized shape returned by `loadConfig`,
94
164
  not raw YAML keys.
95
165
 
166
+ #### Embedding in a broader repository scanner
167
+
168
+ If a caller already owns GitHub discovery and has downloaded a bounded,
169
+ revision-identified evidence snapshot, call `auditSources` for the workflow
170
+ files in that snapshot. Do not also call `scanOrganization` for the same
171
+ repositories: two independent discovery passes can consume extra API quota and
172
+ can observe different tree revisions.
173
+
174
+ The ownership boundary is:
175
+
176
+ - the embedding scanner owns authentication, organization inventory, Git tree
177
+ completeness, blob-size limits, snapshot identity, cache/checkpoint policy,
178
+ non-workflow checks, and aggregate reporting;
179
+ - actions-warden owns YAML parsing, ignore-directive behavior, finding
180
+ identity, severity/baseline filtering, and the complete rule catalog returned
181
+ by `listRules()`;
182
+ - repository source remains data: neither side should import or execute it.
183
+
184
+ Pass unique paths rooted under one stable virtual `cwd` so finding IDs and
185
+ relative paths remain deterministic. Cache identity must include the exact
186
+ actions-warden version and live rule catalog, in addition to the repository
187
+ revision and caller policy. A rule upgrade must not reuse results from a prior
188
+ catalog.
189
+
96
190
  ### `pin(options)`
97
191
 
98
192
  ```js
@@ -184,7 +278,9 @@ Returns:
184
278
  ```js
185
279
  {
186
280
  organization,
281
+ analysis,
187
282
  scope,
283
+ coverage,
188
284
  repositories,
189
285
  findings,
190
286
  errors,
@@ -196,7 +292,15 @@ Returns:
196
292
  ```
197
293
 
198
294
  `findings` and `errors` are flattened for ingestion. `repositories` retains
199
- per-repository identity, revision, files, findings, errors, summary, and status.
295
+ per-repository identity, revision (`branch`, `treeSha`, and `commitSha`), `files`,
296
+ `fileDetails` (one entry per selected workflow file, with its blob SHA, size,
297
+ status, finding count, and permalink), findings, errors, summary, and status.
298
+ Each finding also carries `path`, `blobSha`, and `permalink`.
299
+ `analysis` contains a compatibility generation and stable public identity that
300
+ covers scan scope, policy, baseline contents, and the rule catalog.
301
+ `coverage` distinguishes successful coverage of selected repositories from
302
+ complete coverage of every eligible repository; `maxRepositories` can make it
303
+ incomplete without changing an otherwise clean selected result to `FAIL`.
200
304
 
201
305
  The organization scan is read-only and does not clone, check out, execute, or
202
306
  persist raw remote workflow sources. Repository failures are accumulated when
@@ -205,11 +309,14 @@ possible; failures that prevent organization discovery throw.
205
309
  `checkpointPath` explicitly enables atomic checkpoint writes inside `cwd`.
206
310
  Set `resume: true` to require, validate, and update an existing checkpoint at
207
311
  that path. The organization, selection and audit options, normalized policy,
208
- baseline contents, package version, and rule catalog must match. Concurrency
209
- and token changes are allowed. Resume performs fresh discovery and tree reads;
210
- it reuses only error-free results whose repository, default branch, and tree
211
- SHA remain unchanged. Checkpoints contain redacted report data and revision
212
- metadata, never tokens or raw YAML.
312
+ baseline contents, analysis generation, and rule catalog must match.
313
+ Concurrency, token, and compatible package-version changes are allowed. The
314
+ producing package version remains metadata that the next checkpoint write
315
+ refreshes. Only the current checkpoint schema is accepted; checkpoints hold
316
+ file details but neither commits nor links, which each run rebuilds. Resume performs fresh
317
+ discovery and tree reads; it reuses only error-free results whose repository,
318
+ default branch, and tree SHA remain unchanged. Checkpoints contain redacted
319
+ report data and revision metadata, never tokens or raw YAML.
213
320
 
214
321
  `onProgress` may be synchronous or asynchronous and is awaited in event order
215
322
  at each emission point. A callback error rejects the scan; repository results
@@ -222,10 +329,13 @@ objects are shallow-frozen and use these `type` values:
222
329
  | `checkpoint-loaded` | `repositories` |
223
330
  | `checkpoint-created` | none |
224
331
  | `discovery-started` | `organization` |
332
+ | `discovery-page` | `organization`, `page`, `repositoriesDiscovered`, optional `rateLimitRemaining` |
225
333
  | `discovery-completed` | `discovered`, `eligible`, `selected` |
226
- | `repository-started` | `repository`, `position`, `total` |
334
+ | `repository-started` | `repository`, `position`, `total`, `completed`, `active`, `concurrency` |
335
+ | `repository-phase` | `repository`, `position`, `total`, `completed`, `active`, `concurrency`, `phase` |
227
336
  | `request-retry` | optional `repository`, `attempt`, `maxRetries`, `reason`, `delayMs`, optional `status` |
228
- | `repository-completed` | `repository`, `completed`, `total`, `reused`, `status`, `files`, `findings`, `errors` |
337
+ | `checkpoint-written` | `repository`, `position`, `total`, `repositories` |
338
+ | `repository-completed` | `repository`, `completed`, `total`, `reused`, `status`, `files`, `findings`, `errors`, `active`, `concurrency` |
229
339
  | `scan-completed` | `organization`, `status`, `completed`, `total`, `reused`, `findings`, `errors`, `elapsedMs` |
230
340
 
231
341
  Progress is observational and is not included in the returned result or its
@@ -238,6 +348,47 @@ object enters an AI context. Implement the same bounded behavior by saving the
238
348
  rendered report and returning only `status`, `summary`, and the saved path to
239
349
  the agent.
240
350
 
351
+ ### Comparing organization reports
352
+
353
+ Load a prior JSON report, create the current JSON contract, and compare their
354
+ semantic finding fingerprints:
355
+
356
+ ```js
357
+ import {
358
+ compareOrganizationReports,
359
+ loadOrganizationReport,
360
+ renderOrganizationScan,
361
+ scanOrganization,
362
+ } from 'actions-warden';
363
+
364
+ const previous = await loadOrganizationReport({
365
+ path: 'reports/org.previous.json',
366
+ cwd: '/repo',
367
+ });
368
+ const currentResult = await scanOrganization({
369
+ organization: 'my-org',
370
+ cwd: '/repo',
371
+ token: process.env.GITHUB_TOKEN,
372
+ severity: 'high',
373
+ });
374
+ const current = JSON.parse(renderOrganizationScan(currentResult, {
375
+ format: 'json',
376
+ cwd: '/repo',
377
+ }));
378
+ const comparison = compareOrganizationReports({ previous, current });
379
+ const html = renderOrganizationScan(currentResult, {
380
+ format: 'html',
381
+ cwd: '/repo',
382
+ comparison,
383
+ });
384
+ ```
385
+
386
+ Comparison requires matching analysis identities. It returns deterministically
387
+ ordered `new`, `resolved`, `unchanged`, and `unknown` finding arrays. A prior
388
+ finding is resolved only when the current report successfully covered that
389
+ repository without parse failures; missing, failed, or unparseable repositories
390
+ make resolution unknown.
391
+
241
392
  ## Renderers
242
393
 
243
394
  Use the matching renderer to obtain the CLI-compatible wire format:
@@ -272,7 +423,18 @@ Command/render pairs are:
272
423
  | `scanOrganization` | `renderOrganizationScan` |
273
424
 
274
425
  Lower-level formatters are also exported: `format`, `renderToon`, `renderJson`,
275
- `renderText`, `renderSarif`, `summarize`, and `SEVERITY_ORDER`.
426
+ `renderText`, `renderCsv`, `renderSarif`, `renderHtml`, `summarize`, and
427
+ `SEVERITY_ORDER`.
428
+
429
+ `renderCsv(records, options)` accepts labeled records plus optional `status`.
430
+ It emits a deterministic union header, one physical row per record, and a final
431
+ status row. Nested values become compact JSON cells, control characters are
432
+ escaped, formula-like strings are neutralized, and credentials are redacted.
433
+
434
+ `renderHtml(records, options)` accepts the same labeled records used by TOON
435
+ and text plus optional `status`, `title`, and `metadata`. It redacts and escapes
436
+ dynamic values, permits only HTTPS links, loads no external assets, and rejects
437
+ documents larger than 32 MiB.
276
438
 
277
439
  Every renderer applies credential redaction. See [output contracts](./OUTPUTS.md)
278
440
  before depending on the serialized structure.
@@ -298,12 +460,16 @@ import {
298
460
  Additional exports include baseline helpers, organization GitHub readers
299
461
  (`listOrganizationRepositories`, `fetchRepositoryWorkflowTree`, and
300
462
  `fetchRepositoryWorkflows`), redaction, the live rule catalog, and organization
301
- size limits. A validated workflow-tree snapshot can be supplied to
463
+ size limits. `fetchRepositoryWorkflowTree` resolves the default-branch commit
464
+ first and reads the tree by its tree SHA; the snapshot carries `commitSha`, and
465
+ `fetchRepositoryWorkflows` also returns per-file `entries`. A validated
466
+ workflow-tree snapshot can be supplied to
302
467
  `fetchRepositoryWorkflows` to avoid a duplicate tree request. See
303
468
  [src/index.js](../src/index.js) for the exact export list in the checked-out
304
469
  version.
305
470
 
306
- Command entry points are also available as explicit package subpaths:
471
+ The [package entry-point table](#package-entry-points) is exhaustive. Example
472
+ subpath imports:
307
473
 
308
474
  ```js
309
475
  import { audit } from 'actions-warden/commands/audit';