@stackbilt/git 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 +96 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# @stackbilt/git
|
|
2
|
+
|
|
3
|
+
Git trailer parsing, commit risk scoring, and governance suggestion generation 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 trailer parsing and risk scoring without the CLI.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @stackbilt/git
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
### Parse trailers from a commit message
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { parseTrailersFromMessage } from '@stackbilt/git';
|
|
23
|
+
|
|
24
|
+
const trailers = parseTrailersFromMessage('abc1234', `feat(api): add user endpoint
|
|
25
|
+
|
|
26
|
+
Governed-By: ADR-0012
|
|
27
|
+
Resolves-Request: REQ-0045
|
|
28
|
+
`);
|
|
29
|
+
|
|
30
|
+
console.log(trailers.governedBy);
|
|
31
|
+
// [{ commitSha: 'abc1234', reference: 'ADR-0012' }]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Assess commit risk
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { assessCommitRisk } from '@stackbilt/git';
|
|
38
|
+
|
|
39
|
+
assessCommitRisk(['migrations/002_add_table.sql'], 'feat: add table');
|
|
40
|
+
// => 'HIGH'
|
|
41
|
+
|
|
42
|
+
assessCommitRisk(['lib/utils.ts'], 'refactor: extract helper');
|
|
43
|
+
// => 'MEDIUM'
|
|
44
|
+
|
|
45
|
+
assessCommitRisk(['README.md'], 'docs: update readme');
|
|
46
|
+
// => 'LOW'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**Risk classification:**
|
|
50
|
+
|
|
51
|
+
| Level | File patterns |
|
|
52
|
+
| ------ | ------------- |
|
|
53
|
+
| HIGH | `migrations/`, `*.sql`, `worker/handlers/`, `worker/services/` |
|
|
54
|
+
| MEDIUM | `lib/`, `components/`, `context/`, `worker/lib/` |
|
|
55
|
+
| LOW | `*.md`, `*.json`, `*.yml`, `test/`, `*.test.*`, `.github/` |
|
|
56
|
+
|
|
57
|
+
### Generate governance suggestions
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
import { generateSuggestions } from '@stackbilt/git';
|
|
61
|
+
|
|
62
|
+
const suggestions = generateSuggestions(trailers, unlinkedCommits, totalCommits);
|
|
63
|
+
// ['No commits have governance trailers. Consider linking significant changes to ADRs.']
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## API Reference
|
|
67
|
+
|
|
68
|
+
### `parseTrailersFromMessage(commitSha, message): ParsedTrailers`
|
|
69
|
+
|
|
70
|
+
Parse `Governed-By` and `Resolves-Request` trailers from a single commit message.
|
|
71
|
+
|
|
72
|
+
### `parseAllTrailers(commits: GitCommit[]): ParsedTrailers`
|
|
73
|
+
|
|
74
|
+
Parse trailers from an array of commits, returning combined results.
|
|
75
|
+
|
|
76
|
+
### `assessCommitRisk(filesChanged, commitMessage): CommitRiskLevel`
|
|
77
|
+
|
|
78
|
+
Score a commit as `HIGH`, `MEDIUM`, or `LOW`. Falls back to message keyword analysis when no files are provided.
|
|
79
|
+
|
|
80
|
+
### `generateSuggestions(trailers, unlinkedCommits, totalCommits): string[]`
|
|
81
|
+
|
|
82
|
+
Generate governance suggestions based on trailer coverage and unlinked high-risk commits.
|
|
83
|
+
|
|
84
|
+
## Requirements
|
|
85
|
+
|
|
86
|
+
- Node >= 18
|
|
87
|
+
- Peer dependency: `@stackbilt/types`
|
|
88
|
+
|
|
89
|
+
## License
|
|
90
|
+
|
|
91
|
+
Apache-2.0
|
|
92
|
+
|
|
93
|
+
## Links
|
|
94
|
+
|
|
95
|
+
- [Repository](https://github.com/Stackbilt-dev/charter)
|
|
96
|
+
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
|