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
@@ -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
@@ -207,8 +311,9 @@ 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
312
  baseline contents, analysis generation, and rule catalog must match.
209
313
  Concurrency, token, and compatible package-version changes are allowed. The
210
- producing package version remains metadata, and compatible older checkpoints
211
- are atomically migrated on the first successful resume. Resume performs fresh
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
212
317
  discovery and tree reads; it reuses only error-free results whose repository,
213
318
  default branch, and tree SHA remain unchanged. Checkpoints contain redacted
214
319
  report data and revision metadata, never tokens or raw YAML.
@@ -224,10 +329,13 @@ objects are shallow-frozen and use these `type` values:
224
329
  | `checkpoint-loaded` | `repositories` |
225
330
  | `checkpoint-created` | none |
226
331
  | `discovery-started` | `organization` |
332
+ | `discovery-page` | `organization`, `page`, `repositoriesDiscovered`, optional `rateLimitRemaining` |
227
333
  | `discovery-completed` | `discovered`, `eligible`, `selected` |
228
- | `repository-started` | `repository`, `position`, `total` |
334
+ | `repository-started` | `repository`, `position`, `total`, `completed`, `active`, `concurrency` |
335
+ | `repository-phase` | `repository`, `position`, `total`, `completed`, `active`, `concurrency`, `phase` |
229
336
  | `request-retry` | optional `repository`, `attempt`, `maxRetries`, `reason`, `delayMs`, optional `status` |
230
- | `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` |
231
339
  | `scan-completed` | `organization`, `status`, `completed`, `total`, `reused`, `findings`, `errors`, `elapsedMs` |
232
340
 
233
341
  Progress is observational and is not included in the returned result or its
@@ -240,6 +348,47 @@ object enters an AI context. Implement the same bounded behavior by saving the
240
348
  rendered report and returning only `status`, `summary`, and the saved path to
241
349
  the agent.
242
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
+
243
392
  ## Renderers
244
393
 
245
394
  Use the matching renderer to obtain the CLI-compatible wire format:
@@ -274,7 +423,18 @@ Command/render pairs are:
274
423
  | `scanOrganization` | `renderOrganizationScan` |
275
424
 
276
425
  Lower-level formatters are also exported: `format`, `renderToon`, `renderJson`,
277
- `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.
278
438
 
279
439
  Every renderer applies credential redaction. See [output contracts](./OUTPUTS.md)
280
440
  before depending on the serialized structure.
@@ -300,12 +460,16 @@ import {
300
460
  Additional exports include baseline helpers, organization GitHub readers
301
461
  (`listOrganizationRepositories`, `fetchRepositoryWorkflowTree`, and
302
462
  `fetchRepositoryWorkflows`), redaction, the live rule catalog, and organization
303
- 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
304
467
  `fetchRepositoryWorkflows` to avoid a duplicate tree request. See
305
468
  [src/index.js](../src/index.js) for the exact export list in the checked-out
306
469
  version.
307
470
 
308
- 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:
309
473
 
310
474
  ```js
311
475
  import { audit } from 'actions-warden/commands/audit';