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
@@ -17,8 +17,7 @@ import { pinOccurrenceId, canonicalPath } from '../lib/identity.js';
17
17
  import { applyPatches, planUsesPatches } from '../lib/patcher.js';
18
18
  import { resolveTargets } from '../lib/targets.js';
19
19
  import { mapLimit } from '../lib/concurrency.js';
20
-
21
- const SHA_RE = /^[0-9a-f]{40}$/i;
20
+ import { GIT_SHA_RE } from '../lib/org-schema.js';
22
21
 
23
22
  /**
24
23
  * @typedef {object} PinChange
@@ -69,7 +68,7 @@ export async function pin({ cwd = process.cwd(), workflows, dryRun = true, token
69
68
  const ignore = parseIgnoreDirectives(source);
70
69
  for (const { ref } of collectUses(doc)) {
71
70
  if (ref.kind !== 'external' && ref.kind !== 'reusable-workflow') continue;
72
- if (!ref.ref || SHA_RE.test(ref.ref)) continue;
71
+ if (!ref.ref || GIT_SHA_RE.test(ref.ref)) continue;
73
72
  if (isIgnored(ignore, ref.line, 'unpinned-action')) continue;
74
73
  const id = pinOccurrenceId({ file, cwd, ref });
75
74
  if (fix && fix !== id) continue;
@@ -155,7 +154,8 @@ export function rewriteUses(source, ref, sha) {
155
154
 
156
155
  /**
157
156
  * @param {Awaited<ReturnType<typeof pin>>} result
158
- * @param {{format: 'toon'|'json'|'text', dryRun: boolean, cwd?: string}} opts
157
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', dryRun: boolean,
158
+ * cwd?: string}} opts
159
159
  */
160
160
  export function renderPin(result, opts) {
161
161
  const cwd = opts.cwd ?? process.cwd();
@@ -194,7 +194,11 @@ export function renderPin(result, opts) {
194
194
  records.push({ label: 'ERROR', fields: { file: rel(e.file ?? '', cwd), action: e.action ?? '', msg: e.error } });
195
195
  }
196
196
  records.push({ label: 'SUMMARY', fields: { changes: result.changes.length, errors: result.errors.length, dry_run: opts.dryRun } });
197
- return format(opts.format, records, { status: result.status });
197
+ return format(opts.format, records, {
198
+ status: result.status,
199
+ title: opts.dryRun ? 'Action pin plan' : 'Applied action pins',
200
+ metadata: { mode: opts.dryRun ? 'dry run' : 'write' },
201
+ });
198
202
  }
199
203
 
200
204
  function rel(p, cwd) {
@@ -79,7 +79,8 @@ export async function report({
79
79
 
80
80
  /**
81
81
  * @param {Awaited<ReturnType<typeof report>>} result
82
- * @param {{format: 'toon'|'json'|'text', mode: string, cwd?: string}} opts
82
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', mode: string,
83
+ * cwd?: string}} opts
83
84
  */
84
85
  export function renderReport(result, opts) {
85
86
  const cwd = opts.cwd ?? process.cwd();
@@ -197,7 +198,11 @@ export function renderReport(result, opts) {
197
198
  offline: result.offline,
198
199
  },
199
200
  });
200
- return format(opts.format, records, { status: result.status });
201
+ return format(opts.format, records, {
202
+ status: result.status,
203
+ title: 'Security and dependency report',
204
+ metadata: { upgradeMode: opts.mode, offline: result.offline },
205
+ });
201
206
  }
202
207
 
203
208
  function rel(p, cwd) {
@@ -24,10 +24,9 @@ import { parseIgnoreDirectives, isIgnored } from '../lib/ignore.js';
24
24
  import { format } from '../lib/formatter.js';
25
25
  import { occurrenceId, canonicalPath } from '../lib/identity.js';
26
26
  import { applyPatches, planUsesPatches, readVersionComment } from '../lib/patcher.js';
27
+ import { GIT_SHA_RE } from '../lib/org-schema.js';
27
28
  import { resolveTargets } from '../lib/targets.js';
28
29
 
29
- const SHA_RE = /^[0-9a-f]{40}$/i;
30
-
31
30
  /**
32
31
  * @typedef {object} UpgradeChange
33
32
  * @property {string} id
@@ -93,7 +92,7 @@ export async function upgrade({
93
92
  if (ref.kind !== 'external' && ref.kind !== 'reusable-workflow') continue;
94
93
  if (isIgnored(ignore, ref.line, 'unpinned-action')) continue;
95
94
  const inlineVersion = readVersionComment(source, ref);
96
- const currentVersion = ref.ref && SHA_RE.test(ref.ref) ? inlineVersion : ref.ref;
95
+ const currentVersion = ref.ref && GIT_SHA_RE.test(ref.ref) ? inlineVersion : ref.ref;
97
96
  if (!currentVersion) continue;
98
97
  const id = occurrenceId({
99
98
  kind: 'upgrade',
@@ -258,7 +257,8 @@ function bumpLevel(from, to) {
258
257
 
259
258
  /**
260
259
  * @param {Awaited<ReturnType<typeof upgrade>>} result
261
- * @param {{format: 'toon'|'json'|'text', dryRun: boolean, mode: string, cwd?: string}} opts
260
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', dryRun: boolean,
261
+ * mode: string, cwd?: string}} opts
262
262
  */
263
263
  export function renderUpgrade(result, opts) {
264
264
  const cwd = opts.cwd ?? process.cwd();
@@ -313,7 +313,11 @@ export function renderUpgrade(result, opts) {
313
313
  records.push({ label: 'ERROR', fields: { file: rel(e.file ?? '', cwd), action: e.action ?? '', msg: e.error } });
314
314
  }
315
315
  records.push({ label: 'SUMMARY', fields: { changes: result.changes.length, skipped: (result.skipped ?? []).length, errors: result.errors.length, mode: opts.mode, dry_run: opts.dryRun } });
316
- return format(opts.format, records, { status: result.status });
316
+ return format(opts.format, records, {
317
+ status: result.status,
318
+ title: opts.dryRun ? 'Action upgrade plan' : 'Applied action upgrades',
319
+ metadata: { mode: opts.mode, operation: opts.dryRun ? 'dry run' : 'write' },
320
+ });
317
321
  }
318
322
 
319
323
  function rel(p, cwd) {
@@ -10,9 +10,19 @@ import { readVersionComment } from '../lib/patcher.js';
10
10
  import { occurrenceId, canonicalPath } from '../lib/identity.js';
11
11
  import { format } from '../lib/formatter.js';
12
12
  import { mapLimit } from '../lib/concurrency.js';
13
+ import { GIT_SHA_RE } from '../lib/org-schema.js';
13
14
 
14
- const SHA_RE = /^[0-9a-f]{40}$/i;
15
-
15
+ /**
16
+ * Verify that external action references are full repository-owned commit
17
+ * SHAs and that optional actions-warden version metadata resolves to the same
18
+ * commit.
19
+ *
20
+ * @param {object} [options]
21
+ * @param {string} [options.cwd]
22
+ * @param {string[]} [options.workflows]
23
+ * @param {string} [options.token]
24
+ * @returns {Promise<{files: string[], checks: object[], warnings: object[], errors: object[], status: 'OK'|'FAIL'}>}
25
+ */
16
26
  export async function verify({ cwd = process.cwd(), workflows, token } = {}) {
17
27
  const files = await resolveTargets({ workflows, cwd });
18
28
  const resolvedToken = resolveToken(token);
@@ -43,7 +53,7 @@ export async function verify({ cwd = process.cwd(), workflows, token } = {}) {
43
53
  start: ref.start,
44
54
  subject: ref.raw,
45
55
  });
46
- if (!ref.ref || !SHA_RE.test(ref.ref)) {
56
+ if (!ref.ref || !GIT_SHA_RE.test(ref.ref)) {
47
57
  return { type: 'error', value: {
48
58
  id,
49
59
  file,
@@ -123,6 +133,13 @@ export async function verify({ cwd = process.cwd(), workflows, token } = {}) {
123
133
  };
124
134
  }
125
135
 
136
+ /**
137
+ * Render a verification result in a supported public output format.
138
+ *
139
+ * @param {Awaited<ReturnType<typeof verify>>} result
140
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', cwd?: string}} options
141
+ * @returns {string}
142
+ */
126
143
  export function renderVerify(result, { format: outputFormat, cwd = process.cwd() }) {
127
144
  if (outputFormat === 'json') {
128
145
  return format('json', [], {
@@ -189,5 +206,8 @@ export function renderVerify(result, { format: outputFormat, cwd = process.cwd()
189
206
  errors: result.errors.length,
190
207
  },
191
208
  });
192
- return format(outputFormat, records, { status: result.status });
209
+ return format(outputFormat, records, {
210
+ status: result.status,
211
+ title: 'Pinned action verification',
212
+ });
193
213
  }
package/src/index.js CHANGED
@@ -15,7 +15,7 @@ export { verify, renderVerify } from './commands/verify.js';
15
15
  export { scanOrganization, renderOrganizationScan } from './commands/org-scan.js';
16
16
  export { listRules } from './rules/index.js';
17
17
  export { parseWorkflowFile, parseWorkflowSource, collectUses, collectImages, parseActionRef } from './lib/parser.js';
18
- export { format, renderToon, renderJson, renderText, renderSarif, summarize, SEVERITY_ORDER } from './lib/formatter.js';
18
+ export { format, renderToon, renderJson, renderText, renderCsv, renderSarif, renderHtml, summarize, SEVERITY_ORDER } from './lib/formatter.js';
19
19
  export { discoverWorkflows } from './lib/paths.js';
20
20
  export { redact } from './lib/redact.js';
21
21
  export { parseIgnoreDirectives, isIgnored } from './lib/ignore.js';
@@ -34,3 +34,7 @@ export {
34
34
  loadBaseline,
35
35
  serializeBaseline,
36
36
  } from './lib/baseline.js';
37
+ export {
38
+ compareOrganizationReports,
39
+ loadOrganizationReport,
40
+ } from './lib/org-report-comparison.js';