@stackbilt/ci 0.1.1 → 0.1.3
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/README.md +94 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# @stackbilt/ci
|
|
2
|
+
|
|
3
|
+
GitHub Actions integration helpers for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos.
|
|
4
|
+
|
|
5
|
+
> **Want the full toolkit?** Just install the CLI — it includes everything:
|
|
6
|
+
> ```bash
|
|
7
|
+
> npm install -g @stackbilt/cli
|
|
8
|
+
> ```
|
|
9
|
+
> Only install this package directly if you need GitHub Actions helpers without the CLI.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @stackbilt/ci
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
### Write Actions outputs and summaries
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { setOutput, setSummary } from '@stackbilt/ci';
|
|
23
|
+
|
|
24
|
+
setOutput('governance-status', 'PASS');
|
|
25
|
+
setSummary('## Governance check passed\nNo violations detected.');
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Annotate drift violations
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { annotateDriftViolations } from '@stackbilt/ci';
|
|
32
|
+
|
|
33
|
+
// Emits ::warning:: or ::error:: annotations inline on PR diffs.
|
|
34
|
+
// BLOCKER/CRITICAL severity = error; others = warning.
|
|
35
|
+
annotateDriftViolations(violations);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Annotate validation status
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { annotateValidationStatus } from '@stackbilt/ci';
|
|
42
|
+
|
|
43
|
+
annotateValidationStatus('FAIL', 'Missing required Governed-By trailer');
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Format a PR comment
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { formatPRComment } from '@stackbilt/ci';
|
|
50
|
+
|
|
51
|
+
const body = formatPRComment({
|
|
52
|
+
status: 'WARN',
|
|
53
|
+
summary: '2 drift violations detected',
|
|
54
|
+
violations,
|
|
55
|
+
suggestions: ['Pin axios to the blessed version'],
|
|
56
|
+
score: 0.85,
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## API Reference
|
|
61
|
+
|
|
62
|
+
### `setOutput(name, value): void`
|
|
63
|
+
|
|
64
|
+
Appends `name=value` to `$GITHUB_OUTPUT`. No-op outside Actions.
|
|
65
|
+
|
|
66
|
+
### `setSummary(markdown): void`
|
|
67
|
+
|
|
68
|
+
Appends markdown to `$GITHUB_STEP_SUMMARY`. No-op outside Actions.
|
|
69
|
+
|
|
70
|
+
### `annotateDriftViolations(violations: DriftViolation[]): void`
|
|
71
|
+
|
|
72
|
+
Emits `::error::` / `::warning::` for each violation with file and line number.
|
|
73
|
+
|
|
74
|
+
### `annotateValidationStatus(status, summary): void`
|
|
75
|
+
|
|
76
|
+
Emits `::error::` for FAIL, `::warning::` for WARN, nothing for PASS.
|
|
77
|
+
|
|
78
|
+
### `formatPRComment(result): string`
|
|
79
|
+
|
|
80
|
+
Formats governance results as a markdown PR comment with status, violations table (max 20), and suggestions.
|
|
81
|
+
|
|
82
|
+
## Requirements
|
|
83
|
+
|
|
84
|
+
- Node >= 18
|
|
85
|
+
- Peer dependency: `@stackbilt/types`
|
|
86
|
+
|
|
87
|
+
## License
|
|
88
|
+
|
|
89
|
+
Apache-2.0
|
|
90
|
+
|
|
91
|
+
## Links
|
|
92
|
+
|
|
93
|
+
- [Repository](https://github.com/Stackbilt-dev/charter)
|
|
94
|
+
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
|