taf-git 0.0.0-stage → 3.0.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.
- package/CHANGELOG.md +413 -0
- package/LICENSE +21 -0
- package/README.md +266 -2
- package/RECEIPT-FORMAT.md +100 -0
- package/dist/badge.d.ts +23 -0
- package/dist/badge.js +150 -0
- package/dist/badge.js.map +1 -0
- package/dist/cli.d.ts +42 -0
- package/dist/cli.js +323 -0
- package/dist/cli.js.map +1 -0
- package/dist/git-env.d.ts +20 -0
- package/dist/git-env.js +45 -0
- package/dist/git-env.js.map +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/parsers/bun.d.ts +58 -0
- package/dist/parsers/bun.js +126 -0
- package/dist/parsers/bun.js.map +1 -0
- package/dist/parsers/index.d.ts +21 -0
- package/dist/parsers/index.js +63 -0
- package/dist/parsers/index.js.map +1 -0
- package/dist/parsers/jest.d.ts +41 -0
- package/dist/parsers/jest.js +87 -0
- package/dist/parsers/jest.js.map +1 -0
- package/dist/parsers/junit.d.ts +24 -0
- package/dist/parsers/junit.js +144 -0
- package/dist/parsers/junit.js.map +1 -0
- package/dist/parsers/vitest.d.ts +16 -0
- package/dist/parsers/vitest.js +61 -0
- package/dist/parsers/vitest.js.map +1 -0
- package/dist/parsers/wjttc.d.ts +37 -0
- package/dist/parsers/wjttc.js +152 -0
- package/dist/parsers/wjttc.js.map +1 -0
- package/dist/receipt-push.d.ts +38 -0
- package/dist/receipt-push.js +63 -0
- package/dist/receipt-push.js.map +1 -0
- package/dist/skipped-names.d.ts +60 -0
- package/dist/skipped-names.js +159 -0
- package/dist/skipped-names.js.map +1 -0
- package/dist/taf-core.d.ts +32 -0
- package/dist/taf-core.js +303 -0
- package/dist/taf-core.js.map +1 -0
- package/package.json +64 -4
- package/project.faf +57 -0
package/README.md
CHANGED
|
@@ -1,3 +1,267 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- faf: taf-git | TypeScript | cli | A Test Receipt Printer for git -->
|
|
2
|
+
<!-- faf: doc=readme | canonical=project.faf | score=100 | family=TAF -->
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
# taf-git
|
|
5
|
+
|
|
6
|
+
[](https://github.com/Wolfe-Jam/taf-git)
|
|
7
|
+
[](https://github.com/anthropics/claude-code-action)
|
|
8
|
+
[](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/taf-git)
|
|
9
|
+
|
|
10
|
+
**A receipt printer for your tests.**
|
|
11
|
+
|
|
12
|
+
Every time your tests run in CI, taf-git writes a small receipt: when they ran, how many passed, failed and were skipped. The receipts are saved in your repo, one after another, on their own branch. Over time they show whether your tests really kept passing.
|
|
13
|
+
|
|
14
|
+
Anyone can get green once. Receipts show it over time.
|
|
15
|
+
|
|
16
|
+
`npm: taf-git` · `GitHub Action: Wolfe-Jam/taf-git` · MIT, free
|
|
17
|
+
|
|
18
|
+
Formerly `faf-taf-git`. Installing `taf-git` also gives you a `faf-taf-git` command, so existing scripts keep working. GitHub forwards `uses: Wolfe-Jam/faf-taf-git@…` to this repo, but not the reusable workflow: change `faf-taf-git/.github/workflows/receipt.yml` to `taf-git/.github/workflows/receipt.yml@v3.0.0`.
|
|
19
|
+
|
|
20
|
+
## Why
|
|
21
|
+
|
|
22
|
+
- **Test results usually vanish.** CI shows today's run, then the log expires. Receipts stay.
|
|
23
|
+
- **You can look back.** When did that test start failing? Was main green before the last release?
|
|
24
|
+
- **Other people can check.** Users, reviewers, auditors and AI agents can read the history themselves instead of taking your word for it.
|
|
25
|
+
|
|
26
|
+
## What a receipt looks like
|
|
27
|
+
|
|
28
|
+
Receipts are saved in a file called `.taf`, on a branch called `taf-receipts`:
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
- timestamp: 2026-10-29T20:28:58.090Z
|
|
32
|
+
result: PASSED
|
|
33
|
+
tests:
|
|
34
|
+
total: 628
|
|
35
|
+
passed: 621
|
|
36
|
+
failed: 0
|
|
37
|
+
skipped: 7
|
|
38
|
+
trigger: github-actions
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`result` is `PASSED`, `FAILED` or `SKIPPED` (every test skipped). The full format is in [RECEIPT-FORMAT.md](./RECEIPT-FORMAT.md).
|
|
42
|
+
|
|
43
|
+
When tests are skipped, the receipt also names them (up to 25), with a hash of the full set and what changed since the previous receipt. A skipped count that stays at 7 can't hide a different 7:
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
skipped_tests:
|
|
47
|
+
names:
|
|
48
|
+
- "auth.test.ts > login > uses the refresh token"
|
|
49
|
+
hash: sha256:…
|
|
50
|
+
newly_skipped:
|
|
51
|
+
- "auth.test.ts > login > uses the refresh token"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Names come from JUnit XML reports and Bun's output. Other formats keep the count only.
|
|
55
|
+
|
|
56
|
+
## Set it up (GitHub Actions)
|
|
57
|
+
|
|
58
|
+
Two jobs: your test job runs the tests and uploads their output; a receipt job reads that output and saves the receipt. [faf-cli](https://github.com/Wolfe-Jam/faf-cli)'s CI uses the same two jobs. Add it to a workflow, for example `.github/workflows/tests.yml`, and swap the install and test lines for your own.
|
|
59
|
+
|
|
60
|
+
```yaml
|
|
61
|
+
name: Tests
|
|
62
|
+
|
|
63
|
+
on:
|
|
64
|
+
push:
|
|
65
|
+
branches: [main]
|
|
66
|
+
pull_request:
|
|
67
|
+
|
|
68
|
+
jobs:
|
|
69
|
+
test:
|
|
70
|
+
runs-on: ubuntu-latest
|
|
71
|
+
permissions:
|
|
72
|
+
contents: read # the tests never run with write access
|
|
73
|
+
|
|
74
|
+
steps:
|
|
75
|
+
- uses: actions/checkout@v7
|
|
76
|
+
- uses: actions/setup-node@v7
|
|
77
|
+
with:
|
|
78
|
+
node-version: '24.x'
|
|
79
|
+
- run: npm ci
|
|
80
|
+
|
|
81
|
+
- name: Run tests
|
|
82
|
+
run: |
|
|
83
|
+
set -o pipefail
|
|
84
|
+
npm test 2>&1 | tee test-output.txt
|
|
85
|
+
|
|
86
|
+
- name: Upload the test output
|
|
87
|
+
if: ${{ !cancelled() }} # a failed run uploads too
|
|
88
|
+
uses: actions/upload-artifact@v7
|
|
89
|
+
with:
|
|
90
|
+
name: test-output
|
|
91
|
+
path: test-output.txt
|
|
92
|
+
|
|
93
|
+
receipt:
|
|
94
|
+
needs: test
|
|
95
|
+
# runs when the tests failed too; only for pushes to main
|
|
96
|
+
if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
|
|
97
|
+
permissions:
|
|
98
|
+
contents: write # lets this job, and only this job, save receipts
|
|
99
|
+
uses: Wolfe-Jam/taf-git/.github/workflows/receipt.yml@v3.0.0
|
|
100
|
+
with:
|
|
101
|
+
artifact-name: test-output
|
|
102
|
+
test-output-file: test-output.txt
|
|
103
|
+
test-result: ${{ needs.test.result }} # a red test job is recorded as FAILED
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
That's it. The first run creates the `taf-receipts` branch for you.
|
|
107
|
+
|
|
108
|
+
**Five things this setup gets right:**
|
|
109
|
+
|
|
110
|
+
1. **Failed runs get a receipt too.** A red run is recorded as `FAILED`, not left out, even when no single test failed (a coverage threshold) or the tests never reported (the install failed, a test did not compile): then the receipt has zero counts. A history with only green runs proves less.
|
|
111
|
+
2. **Only `main` gets receipts.** Pull requests still run the tests, but the record is about `main`. A pull request from a fork gets a read-only token, so it could not save a receipt anyway.
|
|
112
|
+
3. **The test job goes red** when tests fail, with no extra steps: it runs the tests the normal way.
|
|
113
|
+
4. **Tests run once.** The receipt reads the output of the run that just happened.
|
|
114
|
+
5. **Only the receipt job can write.** Your test code runs with a read-only token.
|
|
115
|
+
|
|
116
|
+
Give the `receipt` job `permissions: contents: write`: a reusable workflow gets no more access than the job that calls it.
|
|
117
|
+
|
|
118
|
+
**Reusable workflow inputs**
|
|
119
|
+
|
|
120
|
+
| Input | What it does | Default |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `artifact-name` | The artifact your test job uploaded | required |
|
|
123
|
+
| `test-output-file` | The file inside that artifact: the test output or JUnit XML report. A single uploaded file sits at the artifact's root, so `path: reports/junit.xml` is `junit.xml` here | required |
|
|
124
|
+
| `test-result` | The test job's result, `${{ needs.test.result }}`. When it is `failure` the receipt is `FAILED`, even if the output counts no failed test (a coverage threshold) or there is no output at all (zero counts). It is the whole job's result: a step after the tests that fails makes the receipt `FAILED` too | required |
|
|
125
|
+
| `target-branch` | The branch receipts are saved to | `taf-receipts` |
|
|
126
|
+
| `skipped-names` | How many skipped test names each receipt carries. `0` turns it off | `25` |
|
|
127
|
+
| `runs-on` | The runner for the receipt job | `ubuntu-latest` |
|
|
128
|
+
| `commit-message` | The commit message for each receipt | `chore(taf): update .taf receipt [skip ci]` |
|
|
129
|
+
|
|
130
|
+
If the test job failed and there is no artifact, the run is recorded as `FAILED` with zero counts, with a warning that names the likely cause: the tests never reported (the install, the build or a test's compile failed first), or the upload step is missing `if: ${{ !cancelled() }}`, or the name is wrong. If the test job passed and there is still no artifact, the name is wrong: the receipt job fails and says so. A test job that was cancelled or skipped gets no receipt.
|
|
131
|
+
|
|
132
|
+
Its outputs are the action's outputs (see [Settings](#settings)), for example `${{ needs.receipt.outputs.result }}`.
|
|
133
|
+
|
|
134
|
+
### One job instead
|
|
135
|
+
|
|
136
|
+
If you want a single job, use the action as a step. The job needs `contents: write`, so your tests run with write access too.
|
|
137
|
+
|
|
138
|
+
```yaml
|
|
139
|
+
jobs:
|
|
140
|
+
test:
|
|
141
|
+
runs-on: ubuntu-latest
|
|
142
|
+
permissions:
|
|
143
|
+
contents: write # lets the action save receipts
|
|
144
|
+
|
|
145
|
+
steps:
|
|
146
|
+
- uses: actions/checkout@v7
|
|
147
|
+
- uses: actions/setup-node@v7
|
|
148
|
+
with:
|
|
149
|
+
node-version: '24.x'
|
|
150
|
+
- run: npm ci
|
|
151
|
+
|
|
152
|
+
- name: Run tests
|
|
153
|
+
id: tests
|
|
154
|
+
# on main: keep going, so a failed run still gets a receipt
|
|
155
|
+
continue-on-error: ${{ github.ref == 'refs/heads/main' && github.event_name != 'pull_request' }}
|
|
156
|
+
run: |
|
|
157
|
+
set -o pipefail
|
|
158
|
+
npm test 2>&1 | tee test-output.txt
|
|
159
|
+
|
|
160
|
+
- name: Print the receipt
|
|
161
|
+
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
|
|
162
|
+
uses: Wolfe-Jam/taf-git@v3.0.0
|
|
163
|
+
with:
|
|
164
|
+
test-output-file: test-output.txt
|
|
165
|
+
target-branch: taf-receipts
|
|
166
|
+
test-outcome: ${{ steps.tests.outcome }} # a failed test step is a FAILED receipt
|
|
167
|
+
fail-on-failed-tests: 'true' # receipt first, then the step fails if the run was red
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
On `main` the test step keeps going when it fails, the receipt is saved as `FAILED`, and `fail-on-failed-tests` turns the job red. `test-outcome` covers a test step that fails with no failed test in its output (a test file that did not compile, a coverage threshold, a linter in `npm test`). Everywhere else the test step fails the job itself.
|
|
171
|
+
|
|
172
|
+
If your tests run on several operating systems, print the receipt from the one that runs the most tests.
|
|
173
|
+
|
|
174
|
+
## Works with your test runner
|
|
175
|
+
|
|
176
|
+
| Runner | What to give the action |
|
|
177
|
+
|---|---|
|
|
178
|
+
| **Python (pytest)** | `pytest --junitxml=report.xml`, then `test-output-file: report.xml` |
|
|
179
|
+
| **Any runner that writes JUnit XML** | the XML report file (Rust with `cargo nextest`, Go with `gotestsum --junitfile`, Java with Maven or Gradle, .NET, PHPUnit, Jest with `jest-junit`) |
|
|
180
|
+
| **Jest** | the console output (`npm test 2>&1 \| tee test-output.txt`) |
|
|
181
|
+
| **Vitest** | the console output |
|
|
182
|
+
| **Bun** | the console output of `bun test` |
|
|
183
|
+
| **WJTTC** | the console output |
|
|
184
|
+
|
|
185
|
+
JUnit XML is the common report format most test runners can write. If your runner isn't in the table, check whether it can write JUnit XML.
|
|
186
|
+
|
|
187
|
+
**Maven and Gradle write one XML file per test class.** Join them into one file first, or the receipt covers a single class, and one class's file can read PASSED for a run that failed:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
cat target/surefire-reports/TEST-*.xml > report.xml # Maven
|
|
191
|
+
cat build/test-results/test/TEST-*.xml > report.xml # Gradle
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Other CI systems
|
|
195
|
+
|
|
196
|
+
The command-line tool does the same job anywhere Node.js runs (GitLab, Jenkins, CircleCI, Bitbucket, Azure, your own machine):
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
npm test 2>&1 | tee test-output.txt
|
|
200
|
+
npx taf-git --file test-output.txt --commit
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
`--commit` commits the updated `.taf` for you. Leave it off to just update the file.
|
|
204
|
+
|
|
205
|
+
## Read your receipts
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
git fetch origin taf-receipts
|
|
209
|
+
git show origin/taf-receipts:.taf
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Make a badge for your README:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
npx taf-git badge --output badge.svg
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## Settings
|
|
219
|
+
|
|
220
|
+
**Action inputs**
|
|
221
|
+
|
|
222
|
+
| Input | What it does | Default |
|
|
223
|
+
|---|---|---|
|
|
224
|
+
| `test-output-file` | The file with your test output or JUnit XML report | required |
|
|
225
|
+
| `target-branch` | The branch receipts are saved to. Use `taf-receipts`. Written in a separate worktree, so your checkout isn't touched. | the current branch |
|
|
226
|
+
| `auto-commit` | Commit and push the receipt | `true` |
|
|
227
|
+
| `commit-message` | The commit message | `chore(taf): update .taf receipt [skip ci]` |
|
|
228
|
+
| `skipped-names` | How many skipped test names each receipt carries. `0` turns it off | `25` |
|
|
229
|
+
| `fail-on-push-error` | Fail the step when the receipt can't be pushed to the current branch (a warning otherwise). A push another run beat is tried again first, up to 5 times. With `target-branch`, a push that fails after 5 tries always fails | `false` |
|
|
230
|
+
| `fail-on-failed-tests` | Fail the step when the receipt is `FAILED` (failing tests, or `test-outcome: failure`), after the receipt is saved and the outputs are set | `false` |
|
|
231
|
+
| `test-outcome` | Your test step's outcome (`${{ steps.tests.outcome }}`) or test job's result. Only `failure` counts: the receipt is `FAILED` even when the output counts no failed test, or nothing at all. Any other value leaves the result to the output | none |
|
|
232
|
+
|
|
233
|
+
**When another run pushes first.** On the current branch (no `target-branch`) the action tries the push again up to 5 times, with a short random wait between tries, from a temporary worktree that holds only `.taf`. Your checkout is not moved: later steps in the job run on the commit that was tested. After such a retry the checkout keeps its own receipt commit, which was not pushed, so it is behind the remote and its `.taf` lacks the other runs' receipts. A later step that reads `.taf` or pushes should fetch first, or use `target-branch`. Commits that earlier steps made in the checkout go out with the receipt only when the first push succeeds; a retry pushes the receipt alone.
|
|
234
|
+
|
|
235
|
+
**Action outputs:** `result`, `passed`, `failed`, `skipped`, `newly-skipped`, `total`, `taf-updated`, `receipt-pushed`. For example, `${{ steps.taf.outputs.passed }}`.
|
|
236
|
+
|
|
237
|
+
**Command-line options:** `--file`, `--commit`, `--message`, `--cwd`, `--verbose` (`--name value` or `--name=value`). With `--commit`, a push that fails exits 1. Run `npx taf-git --help` for the full list.
|
|
238
|
+
|
|
239
|
+
## How hard is it to fake?
|
|
240
|
+
|
|
241
|
+
Receipts are written by CI from the real test output and saved in git. Editing or deleting an old receipt changes the git history, so anyone comparing the history can see it. The `taf-receipts` branch only ever grows: never rewrite, squash or force-push it.
|
|
242
|
+
|
|
243
|
+
A receipt records what one CI run's tests did, and when. It does not name the commit it tested, and it does not prove a published package was built from any commit.
|
|
244
|
+
|
|
245
|
+
## With FAF (optional)
|
|
246
|
+
|
|
247
|
+
taf-git works on any git repo; you don't need anything else. If your project also uses [FAF](https://faf.one) (a `project.faf` file describing the project for AI), the two fit together: `project.faf` says what the project is, and `.taf` shows its tests kept passing.
|
|
248
|
+
|
|
249
|
+
## Upgrading from v1
|
|
250
|
+
|
|
251
|
+
v1 ran your tests inside the action. v2 reads a file your own test step wrote. Replace `test-command:` with a test step that saves its output, and point `test-output-file:` at that file (see the setup above).
|
|
252
|
+
|
|
253
|
+
## Develop
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
npm ci
|
|
257
|
+
npm test # the test suite
|
|
258
|
+
npm run build # rebuilds dist/, which the action runs
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).
|
|
262
|
+
|
|
263
|
+
## License
|
|
264
|
+
|
|
265
|
+
MIT. Free forever.
|
|
266
|
+
|
|
267
|
+
If taf-git is useful to you, a star helps other people find it.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# .taf — Test Receipt Format
|
|
2
|
+
**v1.1 · TAF = Testing AI Format · tagline: "Test Receipts"**
|
|
3
|
+
|
|
4
|
+
> **Proof Over Time.** Anyone can get green **once.** TAF proves it **over time** — an append-only Test Receipt on every CI run, git-anchored and tamper-evident. Solid engineering shows in the timeline; everything else gets exposed.
|
|
5
|
+
|
|
6
|
+
*The canonical `.taf` file format. This repo (`taf-git`) is the receipt printer; this spec pins the file it writes.*
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## What a `.taf` is
|
|
11
|
+
|
|
12
|
+
A **Receipt Printer for git.** Every CI run prints one receipt — timestamp, counts, result, trigger — appended to a `.taf` file. The receipts accumulate on a `taf-receipts` branch. The history is append-only. **The proof is the timeline, not any single run.**
|
|
13
|
+
|
|
14
|
+
- **Standalone.** Works on any git repo. No FAF required — install the action, get receipts.
|
|
15
|
+
- **Git-native + portable.** The receipt lives *in the repo*, versioned — it survives a CI-vendor migration, which vendor-locked run history does not.
|
|
16
|
+
- **The unique value:** a one-time green is a snapshot (gameable); *"1,847 receipts over 14 months, none missing"* is proof. The format exists to make that timeline portable and falsifiable — nothing more. Thinness is the point.
|
|
17
|
+
|
|
18
|
+
## Tamper-*evident*, not tamper-proof
|
|
19
|
+
|
|
20
|
+
Three mechanisms make tampering **visible**:
|
|
21
|
+
- **Edits** → the commit SHA changes; a rewritten receipt no longer matches its commit.
|
|
22
|
+
- **Deletions** → append-only history on the `taf-receipts` branch makes a removed run a gap you can see.
|
|
23
|
+
- **Forgery** → receipts are written in the CI sandbox from real test output, never by hand.
|
|
24
|
+
|
|
25
|
+
**Honest boundary: tamper-*evident*, not tamper-*proof*.** A maintainer can still decline to run CI on a red commit, or force-push the branch — but those leave *evidence* (missing receipts, a rewritten history). The audit claim is **"none missing,"** not "cannot fail."
|
|
26
|
+
|
|
27
|
+
## The receipt — pinned schema
|
|
28
|
+
|
|
29
|
+
What `taf-git` writes today. Minimal by design.
|
|
30
|
+
|
|
31
|
+
```yaml
|
|
32
|
+
format_version: "1.0.0" # receipt-template version
|
|
33
|
+
project: my-repo # repo / "vendor"
|
|
34
|
+
created: 2026-06-28T09:00:00Z # ISO 8601 UTC
|
|
35
|
+
last_updated: 2026-06-28T09:05:00Z # ISO 8601 UTC — bumped on each append
|
|
36
|
+
|
|
37
|
+
test_history: # append-only, oldest → newest
|
|
38
|
+
- timestamp: 2026-06-28T09:05:00Z # ISO 8601 UTC — the receipt date
|
|
39
|
+
result: PASSED # PASSED | FAILED | IMPROVED | DEGRADED | SKIPPED
|
|
40
|
+
tests: # itemized lines (nested)
|
|
41
|
+
total: 7
|
|
42
|
+
passed: 7
|
|
43
|
+
failed: 0
|
|
44
|
+
skipped: 0 # optional
|
|
45
|
+
trigger: github-actions # optional — what fired the run
|
|
46
|
+
command: npm test # optional — the command run
|
|
47
|
+
skipped_tests: # optional (v1.1) — which tests were skipped
|
|
48
|
+
names: # sorted, at most 25 by default
|
|
49
|
+
- "a.test.ts > outer > skipped one"
|
|
50
|
+
hash: sha256:… # the full set, sorted, "\n"-joined, UTF-8
|
|
51
|
+
newly_skipped: # only when non-empty and the previous set is known
|
|
52
|
+
- "a.test.ts > outer > skipped one"
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Field rules**
|
|
56
|
+
|
|
57
|
+
| field | rule | notes |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `test_history[]` | **required** | the spine — the one hard parse requirement; append-only, never edit a past entry |
|
|
60
|
+
| `…timestamp` | **required** | ISO 8601 UTC |
|
|
61
|
+
| `…result` | **required** | enum: `PASSED` \| `FAILED` \| `IMPROVED` \| `DEGRADED` \| `SKIPPED` (added in 2.4.4: tests were found and every one was skipped). Readers should show a value they don't know rather than reject the receipt. Since 2.7.0 a `FAILED` receipt can have `failed: 0` (or zero counts): the test step failed without a failing test, such as a test file that did not compile or a coverage threshold |
|
|
62
|
+
| `…tests{total,passed,failed}` | **required** | nested; `skipped` optional |
|
|
63
|
+
| `…trigger` / `…command` | optional | provenance of the run |
|
|
64
|
+
| `…skipped_tests` | optional (v1.1) | which tests were skipped, so a steady count can't hide a changed set. `names`: sorted, normalised (no colour codes, paths or timings), capped (25 by default; `truncated: true` past the cap). `hash`: sha256 of every name, sorted and `\n`-joined, so readers compare sets past the cap. `newly_skipped` / `no_longer_skipped`: against the receipt before this one, only when non-empty and that receipt's set is known (a receipt with no block and no skips counts as an empty set). Written only when the output names every skipped test; `names: []` with `no_longer_skipped` marks a return to zero |
|
|
65
|
+
| `format_version` `project` `created` `last_updated` | writer-emitted | the canonical writer always emits these; readers tolerate their absence |
|
|
66
|
+
|
|
67
|
+
**Optional FAF tenant fields (the CAR use case):** a receipt may carry `faf_associated`, `faf_location`, `faf_score` — so it records not just *did tests pass* but *what the project's AI-readiness was when they did*. Optional; absent ≠ invalid.
|
|
68
|
+
|
|
69
|
+
**Readers ignore keys they don't know.** A receipt may gain optional fields in a minor version (v1.1 added `skipped_tests`); a reader must not reject an entry, or split it in two, because of an unknown key or a nested list under one.
|
|
70
|
+
|
|
71
|
+
**Deprecated variants — do NOT emit:** early `.taf` files used `format:`/`version:` headers and *flat* `passed:`/`failed:` per run. Canonical is `format_version`/`project` + *nested* `tests`. Readers MAY accept the old shape; writers MUST emit canonical.
|
|
72
|
+
|
|
73
|
+
## Where it fits — interoperate, don't compete
|
|
74
|
+
|
|
75
|
+
`.taf` is a thin git-native **timeline**, not a rival to per-run formats:
|
|
76
|
+
|
|
77
|
+
- **JUnit XML / TAP** describe **one** run, inside CI. `.taf` is the **portable record across runs**, in the repo. `taf-git` parses Jest/Vitest/JUnit output → appends a receipt.
|
|
78
|
+
- **SLSA / in-toto** attest build provenance to a side store. `.taf` keeps **test** provenance **in the repo** — human-readable, vendor-neutral, offline-readable.
|
|
79
|
+
- Position: `.taf` is the **lowest-friction, in-repo, vendor-neutral proof-over-time** layer. Where a heavier provenance standard is already in play, `.taf` complements it.
|
|
80
|
+
|
|
81
|
+
## The CAR Framework
|
|
82
|
+
|
|
83
|
+
TAF is the **Receipt** in a closed loop — it doesn't stand alone in the FAF world, and doesn't require FAF outside it:
|
|
84
|
+
- **FAF** = the **Claim** (project DNA / AI-readiness)
|
|
85
|
+
- **WJTTC** = the **Audit** (deep test analysis)
|
|
86
|
+
- **TAF** = the **Receipt** (append-only proof the tests ran)
|
|
87
|
+
|
|
88
|
+
FAF is **one tenant** of the printer, not a precondition.
|
|
89
|
+
|
|
90
|
+
## Honest scope — who actually needs this
|
|
91
|
+
|
|
92
|
+
**Yes:** OSS maintainers proving honest history · regulated/audit work (SOC 2 / ISO / HIPAA) needing append-only trails · supply-chain verifiers · **AI-agent accountability** (CI-sandbox receipts an agent can't silently edit) · FAF projects completing CAR.
|
|
93
|
+
**Probably not:** the median dev whose CI badge already says enough. *If you have to ask whether you need it, you likely don't — and that's fine.*
|
|
94
|
+
|
|
95
|
+
## Provenance of this spec
|
|
96
|
+
|
|
97
|
+
- **v1.1 (2026-11)** — optional `skipped_tests` per receipt (names, hash, newly / no longer skipped), asked for by a developer whose skipped count stayed the same while the tests behind it changed; readers must ignore unknown keys. `format_version` in the file stays `"1.0.0"`: v1.1 only adds an optional field.
|
|
98
|
+
- **v1.0 (2026-06-28)** — single canonical Receipt Format. Pins the `faf-taf-git` emitter schema (now `taf-git`); leads with Proof Over Time; states the tamper-evidence boundary honestly.
|
|
99
|
+
- Supersedes earlier drafts (2025-10-27) that predated `faf-taf-git` (now `taf-git`) and over-formatted a thin-value artifact.
|
|
100
|
+
- **License:** MIT.
|
package/dist/badge.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Badge Generator for taf-git
|
|
3
|
+
*
|
|
4
|
+
* Generates shields.io-style SVG badges from .taf test history.
|
|
5
|
+
* Self-contained SVG with Verdana font, no external dependencies.
|
|
6
|
+
*/
|
|
7
|
+
export interface BadgeOptions {
|
|
8
|
+
tafPath?: string;
|
|
9
|
+
label?: string;
|
|
10
|
+
}
|
|
11
|
+
export interface BadgeResult {
|
|
12
|
+
success: boolean;
|
|
13
|
+
svg?: string;
|
|
14
|
+
error?: string;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Render a shields.io flat-style SVG badge.
|
|
18
|
+
*/
|
|
19
|
+
export declare function renderBadgeSvg(label: string, value: string, color: string): string;
|
|
20
|
+
/**
|
|
21
|
+
* Generate a badge SVG from a .taf file.
|
|
22
|
+
*/
|
|
23
|
+
export declare function generateBadge(options?: BadgeOptions): BadgeResult;
|
package/dist/badge.js
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Badge Generator for taf-git
|
|
4
|
+
*
|
|
5
|
+
* Generates shields.io-style SVG badges from .taf test history.
|
|
6
|
+
* Self-contained SVG with Verdana font, no external dependencies.
|
|
7
|
+
*/
|
|
8
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
9
|
+
if (k2 === undefined) k2 = k;
|
|
10
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
11
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
12
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
13
|
+
}
|
|
14
|
+
Object.defineProperty(o, k2, desc);
|
|
15
|
+
}) : (function(o, m, k, k2) {
|
|
16
|
+
if (k2 === undefined) k2 = k;
|
|
17
|
+
o[k2] = m[k];
|
|
18
|
+
}));
|
|
19
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
20
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
21
|
+
}) : function(o, v) {
|
|
22
|
+
o["default"] = v;
|
|
23
|
+
});
|
|
24
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
25
|
+
var ownKeys = function(o) {
|
|
26
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
27
|
+
var ar = [];
|
|
28
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
29
|
+
return ar;
|
|
30
|
+
};
|
|
31
|
+
return ownKeys(o);
|
|
32
|
+
};
|
|
33
|
+
return function (mod) {
|
|
34
|
+
if (mod && mod.__esModule) return mod;
|
|
35
|
+
var result = {};
|
|
36
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
37
|
+
__setModuleDefault(result, mod);
|
|
38
|
+
return result;
|
|
39
|
+
};
|
|
40
|
+
})();
|
|
41
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
42
|
+
exports.renderBadgeSvg = renderBadgeSvg;
|
|
43
|
+
exports.generateBadge = generateBadge;
|
|
44
|
+
const fs = __importStar(require("fs"));
|
|
45
|
+
const yaml = __importStar(require("yaml"));
|
|
46
|
+
const COLOR_PASS = '#003366'; // Navy blue (deep — white-text contrast; cyan was too light)
|
|
47
|
+
const COLOR_FAIL = '#E32400'; // Red
|
|
48
|
+
const COLOR_NONE = '#9F9F9F'; // Gray
|
|
49
|
+
/**
|
|
50
|
+
* Render a shields.io flat-style SVG badge.
|
|
51
|
+
*/
|
|
52
|
+
function renderBadgeSvg(label, value, color) {
|
|
53
|
+
// Approximate text widths using Verdana 11px (6.5px per char average)
|
|
54
|
+
const charWidth = 6.5;
|
|
55
|
+
const padding = 10;
|
|
56
|
+
const labelWidth = Math.round(label.length * charWidth + padding * 2);
|
|
57
|
+
const valueWidth = Math.round(value.length * charWidth + padding * 2);
|
|
58
|
+
const totalWidth = labelWidth + valueWidth;
|
|
59
|
+
const height = 20;
|
|
60
|
+
const labelX = labelWidth / 2;
|
|
61
|
+
const valueX = labelWidth + valueWidth / 2;
|
|
62
|
+
return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${height}" role="img" aria-label="${label}: ${value}">
|
|
63
|
+
<title>${label}: ${value}</title>
|
|
64
|
+
<linearGradient id="s" x2="0" y2="100%">
|
|
65
|
+
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
|
|
66
|
+
<stop offset="1" stop-opacity=".1"/>
|
|
67
|
+
</linearGradient>
|
|
68
|
+
<clipPath id="r">
|
|
69
|
+
<rect width="${totalWidth}" height="${height}" rx="3" fill="#fff"/>
|
|
70
|
+
</clipPath>
|
|
71
|
+
<g clip-path="url(#r)">
|
|
72
|
+
<rect width="${labelWidth}" height="${height}" fill="#555"/>
|
|
73
|
+
<rect x="${labelWidth}" width="${valueWidth}" height="${height}" fill="${color}"/>
|
|
74
|
+
<rect width="${totalWidth}" height="${height}" fill="url(#s)"/>
|
|
75
|
+
</g>
|
|
76
|
+
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
|
|
77
|
+
<text x="${labelX}" y="14" fill="#010101" fill-opacity=".3">${label}</text>
|
|
78
|
+
<text x="${labelX}" y="13" fill="#fff">${label}</text>
|
|
79
|
+
<text x="${valueX}" y="14" fill="#010101" fill-opacity=".3">${value}</text>
|
|
80
|
+
<text x="${valueX}" y="13" fill="#fff">${value}</text>
|
|
81
|
+
</g>
|
|
82
|
+
</svg>`;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Read a .taf file and extract the latest test run.
|
|
86
|
+
*/
|
|
87
|
+
function getLatestRun(tafPath) {
|
|
88
|
+
if (!fs.existsSync(tafPath)) {
|
|
89
|
+
return null;
|
|
90
|
+
}
|
|
91
|
+
const content = fs.readFileSync(tafPath, 'utf-8');
|
|
92
|
+
// Handle YAML document separators (same logic as taf-core.ts)
|
|
93
|
+
const lines = content.split('\n');
|
|
94
|
+
const yamlLines = [];
|
|
95
|
+
for (const line of lines) {
|
|
96
|
+
if (line.trim() === '---' && yamlLines.length > 0)
|
|
97
|
+
break;
|
|
98
|
+
if (line.trim() === '---' && yamlLines.length === 0)
|
|
99
|
+
continue;
|
|
100
|
+
yamlLines.push(line);
|
|
101
|
+
}
|
|
102
|
+
const parsed = yaml.parse(yamlLines.join('\n'));
|
|
103
|
+
if (!parsed || typeof parsed !== 'object')
|
|
104
|
+
return null;
|
|
105
|
+
if (!Array.isArray(parsed.test_history) || parsed.test_history.length === 0)
|
|
106
|
+
return null;
|
|
107
|
+
const latest = parsed.test_history[parsed.test_history.length - 1];
|
|
108
|
+
if (!latest.tests || typeof latest.tests.total !== 'number')
|
|
109
|
+
return null;
|
|
110
|
+
return {
|
|
111
|
+
passed: latest.tests.passed ?? 0,
|
|
112
|
+
total: latest.tests.total,
|
|
113
|
+
failed: latest.tests.failed ?? 0,
|
|
114
|
+
skipped: latest.tests.skipped ?? 0,
|
|
115
|
+
result: typeof latest.result === 'string' ? latest.result : '',
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Generate a badge SVG from a .taf file.
|
|
120
|
+
*/
|
|
121
|
+
function generateBadge(options = {}) {
|
|
122
|
+
const label = options.label || 'TAF';
|
|
123
|
+
const tafPath = options.tafPath || '.taf';
|
|
124
|
+
try {
|
|
125
|
+
const run = getLatestRun(tafPath);
|
|
126
|
+
if (!run) {
|
|
127
|
+
return {
|
|
128
|
+
success: true,
|
|
129
|
+
svg: renderBadgeSvg(label, 'no data', COLOR_NONE),
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
const skippedSuffix = run.skipped > 0 ? ` (${run.skipped} skipped)` : '';
|
|
133
|
+
// A FAILED receipt with no failed test (the test step failed another way:
|
|
134
|
+
// a file that did not compile, a coverage threshold) is red, not passing.
|
|
135
|
+
const failedRun = run.result === 'FAILED' && run.failed === 0;
|
|
136
|
+
const value = failedRun ? 'run failed' : `${run.passed}/${run.total} passing${skippedSuffix}`;
|
|
137
|
+
const color = run.failed > 0 || failedRun ? COLOR_FAIL : run.passed === 0 ? COLOR_NONE : COLOR_PASS;
|
|
138
|
+
return {
|
|
139
|
+
success: true,
|
|
140
|
+
svg: renderBadgeSvg(label, value, color),
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
catch (error) {
|
|
144
|
+
return {
|
|
145
|
+
success: false,
|
|
146
|
+
error: error instanceof Error ? error.message : 'Failed to generate badge',
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
//# sourceMappingURL=badge.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"badge.js","sourceRoot":"","sources":["../src/badge.ts"],"names":[],"mappings":"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"}
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* taf-git - The Git-Native Receipt Printer
|
|
4
|
+
*
|
|
5
|
+
* v2.x CLI: reads test output from file (pre-capture pattern)
|
|
6
|
+
* Platform-agnostic - works in ANY CI/CD environment or locally
|
|
7
|
+
*/
|
|
8
|
+
export interface CLIOptions {
|
|
9
|
+
file?: string;
|
|
10
|
+
autoCommit?: boolean;
|
|
11
|
+
commitMessage?: string;
|
|
12
|
+
cwd?: string;
|
|
13
|
+
/** Skipped names per receipt; 0 turns them off (default 25). */
|
|
14
|
+
skippedNamesCap?: number;
|
|
15
|
+
verbose?: boolean;
|
|
16
|
+
logger?: (message: string) => void;
|
|
17
|
+
}
|
|
18
|
+
export interface CLIResult {
|
|
19
|
+
success: boolean;
|
|
20
|
+
testResults?: {
|
|
21
|
+
total: number;
|
|
22
|
+
passed: number;
|
|
23
|
+
failed: number;
|
|
24
|
+
result: string;
|
|
25
|
+
};
|
|
26
|
+
tafUpdated: boolean;
|
|
27
|
+
error?: string;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Main CLI function - reads test output from file
|
|
31
|
+
*/
|
|
32
|
+
export declare function runTafGit(options?: CLIOptions): Promise<CLIResult>;
|
|
33
|
+
/**
|
|
34
|
+
* The value of an option, written `--name value` or `--name=value`; undefined
|
|
35
|
+
* when it isn't there or has no value.
|
|
36
|
+
*/
|
|
37
|
+
export declare function optionValue(args: string[], name: string): string | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* The installed package's version. package.json sits one level above both
|
|
40
|
+
* src/ (tests) and dist/ (the published bin).
|
|
41
|
+
*/
|
|
42
|
+
export declare function cliVersion(): string;
|