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
@@ -0,0 +1,50 @@
1
+ // @ts-check
2
+ /**
3
+ * Token-Oriented Object Notation: one labeled record per line,
4
+ * `LABEL: key=value key=value`, empty values omitted, trailing `STATUS:` line.
5
+ */
6
+
7
+ import { redact } from '../redact.js';
8
+
9
+ /**
10
+ * @param {string} value
11
+ * @returns {string}
12
+ */
13
+ function quoteIfNeeded(value) {
14
+ if (value === '') return '""';
15
+ if (/[\s="\\]/.test(value) || [...value].some(char => char.charCodeAt(0) < 32)) {
16
+ return JSON.stringify(value);
17
+ }
18
+ return value;
19
+ }
20
+
21
+ /**
22
+ * Serialize a record to a single TOON line.
23
+ *
24
+ * @param {string} label
25
+ * @param {Record<string, unknown>} fields
26
+ * @returns {string}
27
+ */
28
+ export function toonLine(label, fields) {
29
+ const parts = [];
30
+ for (const [k, v] of Object.entries(fields)) {
31
+ if (v === null || v === undefined || v === '') continue;
32
+ const value = typeof v === 'string' ? v : String(v);
33
+ const key = redact(String(k)).replace(/[^a-zA-Z0-9_.-]/g, '_');
34
+ parts.push(`${key}=${quoteIfNeeded(redact(value))}`);
35
+ }
36
+ return parts.length === 0 ? `${label}:` : `${label}: ${parts.join(' ')}`;
37
+ }
38
+
39
+ /**
40
+ * Render a TOON document.
41
+ *
42
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
43
+ * @param {{status?: 'OK'|'FAIL'}} [options]
44
+ * @returns {string}
45
+ */
46
+ export function renderToon(records, options = {}) {
47
+ const lines = records.map(r => toonLine(r.label, r.fields));
48
+ if (options.status) lines.push(`STATUS: ${options.status}`);
49
+ return lines.join('\n') + '\n';
50
+ }
@@ -1,6 +1,8 @@
1
1
  /**
2
2
  * Output formatter supporting TOON (Token-Oriented Object Notation), JSON,
3
- * plain text, and SARIF.
3
+ * plain text, CSV, SARIF, and self-contained HTML. Each serializer lives under
4
+ * `src/lib/formats/`; this module dispatches by format name and re-exports the
5
+ * public renderers.
4
6
  *
5
7
  * TOON output rules:
6
8
  * - One record per line: `LABEL: key=value key=value`
@@ -9,94 +11,33 @@
9
11
  * - Trailing `STATUS: OK` or `STATUS: FAIL` signal for machine consumers
10
12
  */
11
13
 
12
- import { redact, redactDeep } from './redact.js';
14
+ import { renderCsv } from './formats/csv.js';
15
+ import { renderHtml } from './formats/html.js';
16
+ import { renderJson } from './formats/json.js';
17
+ import { renderSarif } from './formats/sarif.js';
18
+ import { renderText } from './formats/text.js';
19
+ import { renderToon } from './formats/toon.js';
20
+ import { SEVERITY_LEVELS } from './org-schema.js';
21
+
22
+ export { renderCsv } from './formats/csv.js';
23
+ export { renderHtml } from './formats/html.js';
24
+ export { renderJson } from './formats/json.js';
25
+ export { renderSarif } from './formats/sarif.js';
26
+ export { renderText } from './formats/text.js';
27
+ export { renderToon, toonLine } from './formats/toon.js';
13
28
 
14
29
  /**
15
30
  * Severity ordering, lowest-to-highest.
16
31
  */
17
- export const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
18
-
19
- /**
20
- * @param {string} value
21
- * @returns {string}
22
- */
23
- function quoteIfNeeded(value) {
24
- if (value === '') return '""';
25
- if (/[\s="\\]/.test(value) || [...value].some(char => char.charCodeAt(0) < 32)) {
26
- return JSON.stringify(value);
27
- }
28
- return value;
29
- }
30
-
31
- /**
32
- * Serialize a record to a single TOON line.
33
- *
34
- * @param {string} label
35
- * @param {Record<string, unknown>} fields
36
- * @returns {string}
37
- */
38
- export function toonLine(label, fields) {
39
- const parts = [];
40
- for (const [k, v] of Object.entries(fields)) {
41
- if (v === null || v === undefined || v === '') continue;
42
- const value = typeof v === 'string' ? v : String(v);
43
- parts.push(`${k}=${quoteIfNeeded(redact(value))}`);
44
- }
45
- return parts.length === 0 ? `${label}:` : `${label}: ${parts.join(' ')}`;
46
- }
47
-
48
- /**
49
- * Render a TOON document.
50
- *
51
- * @param {Array<{label: string, fields: Record<string, unknown>}>} records
52
- * @param {{status?: 'OK'|'FAIL'}} [options]
53
- * @returns {string}
54
- */
55
- export function renderToon(records, options = {}) {
56
- const lines = records.map(r => toonLine(r.label, r.fields));
57
- if (options.status) lines.push(`STATUS: ${options.status}`);
58
- return lines.join('\n') + '\n';
59
- }
60
-
61
- /**
62
- * Render JSON with stable key ordering and 2-space indent.
63
- *
64
- * @param {unknown} payload
65
- * @returns {string}
66
- */
67
- export function renderJson(payload) {
68
- return JSON.stringify(redactDeep(payload), null, 2) + '\n';
69
- }
70
-
71
- /**
72
- * Render plain text (human-readable summary).
73
- *
74
- * @param {Array<{label: string, fields: Record<string, unknown>}>} records
75
- * @param {{status?: 'OK'|'FAIL'}} [options]
76
- * @returns {string}
77
- */
78
- export function renderText(records, options = {}) {
79
- const lines = records.map(r => {
80
- const kv = Object.entries(r.fields)
81
- .filter(([, v]) => v !== null && v !== undefined && v !== '')
82
- .map(([k, v]) => `${k}=${escapeText(redact(String(v)))}`)
83
- .join(' ');
84
- return `[${r.label}] ${kv}`;
85
- });
86
- if (options.status) lines.push(`==> ${options.status}`);
87
- return lines.join('\n') + '\n';
88
- }
89
-
90
- function escapeText(value) {
91
- return JSON.stringify(value).slice(1, -1);
92
- }
32
+ export const SEVERITY_ORDER = [...SEVERITY_LEVELS];
93
33
 
94
34
  /**
95
35
  * Format records into the requested output mode.
96
36
  *
97
- * @param {'toon'|'json'|'text'|'sarif'} format
37
+ * @param {'toon'|'json'|'text'|'csv'|'sarif'|'html'} format
98
38
  * @param {Array<{label: string, fields: Record<string, unknown>}>} records
99
- * @param {{status?: 'OK'|'FAIL', json?: unknown}} [options]
39
+ * @param {{status?: 'OK'|'FAIL', json?: unknown, title?: string,
40
+ * metadata?: Record<string, unknown>}} [options]
100
41
  * @returns {string}
101
42
  */
102
43
  export function format(format_, records, options = {}) {
@@ -105,126 +46,18 @@ export function format(format_, records, options = {}) {
105
46
  return renderJson(options.json ?? recordsToJson(records, options));
106
47
  case 'text':
107
48
  return renderText(records, options);
49
+ case 'csv':
50
+ return renderCsv(records, options);
108
51
  case 'sarif':
109
52
  return renderSarif(records, options);
53
+ case 'html':
54
+ return renderHtml(records, options);
110
55
  case 'toon':
111
56
  default:
112
57
  return renderToon(records, options);
113
58
  }
114
59
  }
115
60
 
116
- /**
117
- * Render records as SARIF 2.1.0 for GitHub code scanning.
118
- *
119
- * @param {Array<{label: string, fields: Record<string, unknown>}>} records
120
- * @param {{status?: string}} [options]
121
- */
122
- export function renderSarif(records, options = {}) {
123
- const ruleRecords = records.filter(record => record.label === 'RULE');
124
- const resultRecords = records.filter(record => (
125
- record.label === 'FINDING'
126
- || record.label === 'ERROR'
127
- || record.label === 'WARNING'
128
- || record.label === 'PIN'
129
- || record.label === 'UPGRADE'
130
- ));
131
- const rules = new Map();
132
- for (const record of ruleRecords) {
133
- const id = String(record.fields.id ?? 'actions-warden');
134
- rules.set(id, {
135
- id,
136
- shortDescription: {
137
- text: String(record.fields.description ?? id),
138
- },
139
- defaultConfiguration: {
140
- level: sarifLevel(String(record.fields.severity ?? 'low')),
141
- },
142
- });
143
- }
144
-
145
- const results = resultRecords.map(record => {
146
- const fields = record.fields;
147
- const ruleId = String(fields.type ?? `actions-warden/${record.label.toLowerCase()}`);
148
- if (!rules.has(ruleId)) {
149
- rules.set(ruleId, {
150
- id: ruleId,
151
- shortDescription: { text: ruleId },
152
- defaultConfiguration: {
153
- level: record.label === 'ERROR'
154
- ? 'error'
155
- : sarifLevel(String(fields.sev ?? 'low')),
156
- },
157
- });
158
- }
159
- const file = fields.file ? String(fields.file) : null;
160
- const line = Number(fields.line);
161
- return {
162
- ruleId,
163
- level: record.label === 'ERROR'
164
- ? 'error'
165
- : record.label === 'WARNING'
166
- ? 'warning'
167
- : sarifLevel(String(fields.sev ?? (record.label === 'FINDING' ? 'warning' : 'low'))),
168
- message: {
169
- text: String(fields.explain ?? fields.msg ?? summarizeFields(record.label, fields)),
170
- },
171
- ...(file ? {
172
- locations: [{
173
- physicalLocation: {
174
- artifactLocation: { uri: file.replace(/\\/g, '/') },
175
- ...(Number.isInteger(line) && line > 0
176
- ? { region: { startLine: line } }
177
- : {}),
178
- },
179
- }],
180
- } : {}),
181
- ...(fields.id ? {
182
- partialFingerprints: {
183
- // GitHub code scanning recognizes this key and uses the suffix to
184
- // distinguish multiple results with the same semantic fingerprint.
185
- primaryLocationLineHash: `${fields.fingerprint ?? fields.id}:1`,
186
- 'actions-warden/id': String(fields.id),
187
- ...(fields.fingerprint
188
- ? { 'actions-warden/semantic': String(fields.fingerprint) }
189
- : {}),
190
- },
191
- } : {}),
192
- };
193
- });
194
-
195
- return renderJson({
196
- $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
197
- version: '2.1.0',
198
- runs: [{
199
- tool: {
200
- driver: {
201
- name: 'actions-warden',
202
- informationUri: 'https://github.com/chiz0me/actions-warden',
203
- rules: [...rules.values()],
204
- },
205
- },
206
- invocations: [{
207
- executionSuccessful: options.status !== 'ERROR',
208
- }],
209
- results,
210
- }],
211
- });
212
- }
213
-
214
- function sarifLevel(severity) {
215
- if (severity === 'critical' || severity === 'high' || severity === 'error') return 'error';
216
- if (severity === 'medium' || severity === 'warning') return 'warning';
217
- return 'note';
218
- }
219
-
220
- function summarizeFields(label, fields) {
221
- const details = Object.entries(fields)
222
- .filter(([key, value]) => !['id', 'file', 'line'].includes(key) && value != null && value !== '')
223
- .map(([key, value]) => `${key}=${String(value)}`)
224
- .join(' ');
225
- return `${label}: ${details}`;
226
- }
227
-
228
61
  /**
229
62
  * Convert records to a generic JSON payload when no custom JSON is supplied.
230
63
  *