@final-commerce/common 2.11.0 → 2.11.1-online.10
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 +20 -0
- package/bin/gate-done.mjs +76 -54
- package/bin/lib/budget.mjs +71 -0
- package/dist/index.d.mts +295 -2
- package/dist/index.d.ts +295 -2
- package/dist/index.js +367 -9
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +341 -9
- package/dist/index.mjs.map +1 -1
- package/dist/pos-types/index.d.mts +72 -13
- package/dist/pos-types/index.d.ts +72 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -219,6 +219,26 @@ node -p "const c = require('@final-commerce/common'); c.formatCurrency(2500, 'EU
|
|
|
219
219
|
# → €25.00
|
|
220
220
|
```
|
|
221
221
|
|
|
222
|
+
## Quality gates
|
|
223
|
+
|
|
224
|
+
### `gate-done` time budgets
|
|
225
|
+
|
|
226
|
+
`gate-done` (the pre-push hook) runs three sweeps: gitleaks, Vitest with coverage, and a bundle-size or build check. It gives them two separate time budgets, both set in milliseconds through environment variables:
|
|
227
|
+
|
|
228
|
+
| Variable | Default | Covers |
|
|
229
|
+
| -------------------------- | -------- | ----------------------------- |
|
|
230
|
+
| `GATE_DONE_BUDGET_MS` | `90000` | gitleaks and the bundle sweep |
|
|
231
|
+
| `GATE_DONE_TEST_BUDGET_MS` | `300000` | the Vitest sweep on its own |
|
|
232
|
+
|
|
233
|
+
A budget only counts time spent in its own sweeps, so a slow test suite never takes time from the other sweeps, and the other sweeps never take time from the tests. Husky's pre-push hook inherits your shell environment, so you can raise a budget for one push or for good:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
GATE_DONE_TEST_BUDGET_MS=600000 git push # one push
|
|
237
|
+
export GATE_DONE_TEST_BUDGET_MS=600000 # in ~/.zshrc, for every push
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
If a sweep runs past its budget, `gate-done` kills it and blocks the push with a timeout message (`Vitest killed after 300.0s by the test budget … not a test failure`), not as a test failure. Values that are not positive integers are ignored with a warning, and the default applies.
|
|
241
|
+
|
|
222
242
|
## License
|
|
223
243
|
|
|
224
244
|
Private — Final Commerce internal use only.
|
package/bin/gate-done.mjs
CHANGED
|
@@ -2,59 +2,79 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* gate-done — pre-push hook.
|
|
4
4
|
*
|
|
5
|
-
* Runs
|
|
5
|
+
* Runs three sweeps under two time budgets:
|
|
6
6
|
*
|
|
7
|
-
* 1.
|
|
8
|
-
* 2.
|
|
9
|
-
* 3.
|
|
10
|
-
* 4. bundle — size-limit or custom bundle-size script (if configured)
|
|
7
|
+
* 1. gitleaks — credential / secret scanning (git log + staged)
|
|
8
|
+
* 2. vitest — full test suite with coverage threshold enforcement
|
|
9
|
+
* 3. bundle — size-limit or custom bundle-size script (if configured)
|
|
11
10
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* Budgets (milliseconds, read from the environment — Husky's pre-push inherits the shell):
|
|
12
|
+
*
|
|
13
|
+
* GATE_DONE_BUDGET_MS default 90000 shared by sweeps 1 and 3
|
|
14
|
+
* GATE_DONE_TEST_BUDGET_MS default 300000 sweep 2 (Vitest) on its own
|
|
15
|
+
*
|
|
16
|
+
* A budget only drains while its own sweeps run, so a slow test suite cannot
|
|
17
|
+
* starve the bundle sweep and vice versa.
|
|
18
|
+
*
|
|
19
|
+
* Any sweep failure exits 1, blocking the push.
|
|
20
|
+
* A sweep killed by its budget also exits 1, but is reported as a timeout,
|
|
21
|
+
* not as a failure of the thing it was checking.
|
|
14
22
|
*
|
|
15
23
|
* Install as Husky pre-push hook:
|
|
16
24
|
* echo "npx gate-done" > .husky/pre-push
|
|
17
25
|
*/
|
|
18
26
|
|
|
19
|
-
import { spawnSync } from 'node:child_process';
|
|
20
27
|
import { readFileSync } from 'node:fs';
|
|
21
28
|
import { resolve } from 'node:path';
|
|
22
29
|
|
|
23
|
-
|
|
30
|
+
import {
|
|
31
|
+
DEFAULT_BUDGET_MS,
|
|
32
|
+
DEFAULT_TEST_BUDGET_MS,
|
|
33
|
+
budgetKillMessage,
|
|
34
|
+
createBudget,
|
|
35
|
+
readBudgetMs,
|
|
36
|
+
runInBudget,
|
|
37
|
+
} from './lib/budget.mjs';
|
|
38
|
+
|
|
24
39
|
const t0 = Date.now();
|
|
25
40
|
|
|
26
41
|
// ── helpers ──────────────────────────────────────────────────────────────────
|
|
27
42
|
|
|
28
|
-
function remaining() {
|
|
29
|
-
return Math.max(0, BUDGET_MS - (Date.now() - t0));
|
|
30
|
-
}
|
|
31
|
-
|
|
32
43
|
function elapsed() {
|
|
33
44
|
return ((Date.now() - t0) / 1000).toFixed(1);
|
|
34
45
|
}
|
|
35
46
|
|
|
36
|
-
function
|
|
37
|
-
|
|
38
|
-
|
|
47
|
+
function makeBudget(name, envVar, fallback) {
|
|
48
|
+
const { ms, invalid } = readBudgetMs(process.env, envVar, fallback);
|
|
49
|
+
if (invalid !== undefined) {
|
|
50
|
+
warn(`${envVar}="${invalid}" is not a positive integer of milliseconds — using ${fallback}.`);
|
|
51
|
+
}
|
|
52
|
+
return createBudget(name, envVar, ms);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function checkBudget(budget, label) {
|
|
56
|
+
if (budget.exhausted()) {
|
|
57
|
+
fail(
|
|
58
|
+
`${budget.name} budget (${budget.envVar}=${budget.ms}) exhausted before "${label}" could start. ` +
|
|
59
|
+
`Push blocked — not a ${label} failure.`,
|
|
60
|
+
);
|
|
39
61
|
}
|
|
40
62
|
}
|
|
41
63
|
|
|
42
64
|
/**
|
|
43
|
-
* Run a command, streaming output
|
|
44
|
-
*
|
|
45
|
-
*
|
|
65
|
+
* Run a command, streaming output, charged to `budget`. The budget's remaining
|
|
66
|
+
* time is the child's timeout, so a runaway child cannot overrun it. A child
|
|
67
|
+
* killed by that timeout blocks the push with a timeout message instead of
|
|
68
|
+
* being reported as a failure of the sweep.
|
|
46
69
|
*/
|
|
47
|
-
function run(cmd) {
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
stdio: 'inherit',
|
|
52
|
-
timeout: remaining(),
|
|
53
|
-
});
|
|
70
|
+
function run(budget, label, cmd) {
|
|
71
|
+
const result = runInBudget(budget, cmd, { stdio: 'inherit' });
|
|
72
|
+
if (result.timedOut) fail(budgetKillMessage(label, budget, result.durationMs) + ' Push blocked.');
|
|
73
|
+
return result;
|
|
54
74
|
}
|
|
55
75
|
|
|
56
|
-
function capture(cmd) {
|
|
57
|
-
return
|
|
76
|
+
function capture(budget, cmd) {
|
|
77
|
+
return runInBudget(budget, cmd);
|
|
58
78
|
}
|
|
59
79
|
|
|
60
80
|
function fail(msg) {
|
|
@@ -74,24 +94,22 @@ function ok(msg) {
|
|
|
74
94
|
process.stdout.write(`\x1b[32m✔ [${elapsed()}s] ${msg}\x1b[0m\n`);
|
|
75
95
|
}
|
|
76
96
|
|
|
77
|
-
// ──
|
|
97
|
+
// ── budgets ──────────────────────────────────────────────────────────────────
|
|
78
98
|
|
|
79
|
-
|
|
80
|
-
|
|
99
|
+
const sweepBudget = makeBudget('sweep', 'GATE_DONE_BUDGET_MS', DEFAULT_BUDGET_MS);
|
|
100
|
+
const testBudget = makeBudget('test', 'GATE_DONE_TEST_BUDGET_MS', DEFAULT_TEST_BUDGET_MS);
|
|
81
101
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
ok('npm audit: no high/critical vulnerabilities.');
|
|
87
|
-
}
|
|
102
|
+
info(
|
|
103
|
+
`Budgets: sweeps ${sweepBudget.ms / 1000}s (GATE_DONE_BUDGET_MS), ` +
|
|
104
|
+
`tests ${testBudget.ms / 1000}s (GATE_DONE_TEST_BUDGET_MS).`,
|
|
105
|
+
);
|
|
88
106
|
|
|
89
|
-
// ──
|
|
107
|
+
// ── 1. gitleaks ───────────────────────────────────────────────────────────────
|
|
90
108
|
|
|
91
|
-
info('Sweep
|
|
92
|
-
checkBudget('gitleaks');
|
|
109
|
+
info('Sweep 1/3 — gitleaks secrets scan…');
|
|
110
|
+
checkBudget(sweepBudget, 'gitleaks');
|
|
93
111
|
|
|
94
|
-
const hasGitleaks = capture('command -v gitleaks 2>/dev/null').status === 0;
|
|
112
|
+
const hasGitleaks = capture(sweepBudget, 'command -v gitleaks 2>/dev/null').status === 0;
|
|
95
113
|
|
|
96
114
|
if (!hasGitleaks) {
|
|
97
115
|
warn(
|
|
@@ -101,19 +119,19 @@ if (!hasGitleaks) {
|
|
|
101
119
|
} else {
|
|
102
120
|
// Scan the full git history visible from HEAD — correct mode for a pre-push hook.
|
|
103
121
|
// --no-git-serial scans refs in parallel for speed within the budget.
|
|
104
|
-
const glResult = run('gitleaks git --exit-code 1 .');
|
|
122
|
+
const glResult = run(sweepBudget, 'gitleaks', 'gitleaks git --exit-code 1 .');
|
|
105
123
|
if (glResult.status !== 0) {
|
|
106
124
|
fail('gitleaks detected a potential secret. Remove it and retry the push.');
|
|
107
125
|
}
|
|
108
126
|
ok('gitleaks: no secrets detected.');
|
|
109
127
|
}
|
|
110
128
|
|
|
111
|
-
// ──
|
|
129
|
+
// ── 2. vitest coverage ────────────────────────────────────────────────────────
|
|
112
130
|
|
|
113
|
-
info('Sweep 3
|
|
114
|
-
checkBudget('
|
|
131
|
+
info('Sweep 2/3 — Vitest test suite + coverage thresholds…');
|
|
132
|
+
checkBudget(testBudget, 'Vitest');
|
|
115
133
|
|
|
116
|
-
const vitestResult = run('npx vitest run --coverage');
|
|
134
|
+
const vitestResult = run(testBudget, 'Vitest', 'npx vitest run --coverage');
|
|
117
135
|
|
|
118
136
|
if (vitestResult.status !== 0) {
|
|
119
137
|
fail('Vitest coverage gate failed — fix failing tests or low-coverage areas before pushing.');
|
|
@@ -121,10 +139,10 @@ if (vitestResult.status !== 0) {
|
|
|
121
139
|
|
|
122
140
|
ok('Vitest: all tests passed, coverage thresholds met.');
|
|
123
141
|
|
|
124
|
-
// ──
|
|
142
|
+
// ── 3. bundle size ────────────────────────────────────────────────────────────
|
|
125
143
|
|
|
126
|
-
info('Sweep
|
|
127
|
-
checkBudget('bundle audit');
|
|
144
|
+
info('Sweep 3/3 — bundle size audit…');
|
|
145
|
+
checkBudget(sweepBudget, 'bundle audit');
|
|
128
146
|
|
|
129
147
|
const pkgPath = resolve(process.cwd(), 'package.json');
|
|
130
148
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
@@ -135,21 +153,21 @@ const hasBundlesize = Boolean(pkg.devDependencies?.['bundlesize']) || Boolean(pk
|
|
|
135
153
|
const hasBuildScript = Boolean(pkg.scripts?.build);
|
|
136
154
|
|
|
137
155
|
if (hasBundleSizeScript) {
|
|
138
|
-
const result = run('npm run bundle-size');
|
|
156
|
+
const result = run(sweepBudget, 'bundle-size', 'npm run bundle-size');
|
|
139
157
|
if (result.status !== 0) fail('bundle-size script reported a violation. Push blocked.');
|
|
140
158
|
ok('Bundle size: within limits.');
|
|
141
159
|
} else if (hasSizeLimit) {
|
|
142
|
-
const result = run('npx size-limit');
|
|
160
|
+
const result = run(sweepBudget, 'size-limit', 'npx size-limit');
|
|
143
161
|
if (result.status !== 0) fail('size-limit reported a violation. Push blocked.');
|
|
144
162
|
ok('Bundle size: size-limit passed.');
|
|
145
163
|
} else if (hasBundlesize) {
|
|
146
|
-
const result = run('npx bundlesize');
|
|
164
|
+
const result = run(sweepBudget, 'bundlesize', 'npx bundlesize');
|
|
147
165
|
if (result.status !== 0) fail('bundlesize reported a violation. Push blocked.');
|
|
148
166
|
ok('Bundle size: bundlesize passed.');
|
|
149
167
|
} else if (hasBuildScript) {
|
|
150
168
|
// No size tool configured — at minimum verify the build succeeds cleanly.
|
|
151
169
|
info('No size-limit/bundlesize configured — running build as a smoke-check.');
|
|
152
|
-
const result = run('npm run build');
|
|
170
|
+
const result = run(sweepBudget, 'build', 'npm run build');
|
|
153
171
|
if (result.status !== 0) fail('Build failed during gate-done. Push blocked.');
|
|
154
172
|
ok('Build: succeeded (no size budget configured).');
|
|
155
173
|
} else {
|
|
@@ -158,5 +176,9 @@ if (hasBundleSizeScript) {
|
|
|
158
176
|
|
|
159
177
|
// ── done ─────────────────────────────────────────────────────────────────────
|
|
160
178
|
|
|
161
|
-
ok(
|
|
179
|
+
ok(
|
|
180
|
+
`gate-done completed in ${elapsed()}s ` +
|
|
181
|
+
`(sweeps ${(sweepBudget.spent() / 1000).toFixed(1)}/${sweepBudget.ms / 1000}s, ` +
|
|
182
|
+
`tests ${(testBudget.spent() / 1000).toFixed(1)}/${testBudget.ms / 1000}s). Push proceeding.`,
|
|
183
|
+
);
|
|
162
184
|
process.exit(0);
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Time budgets for the gate-* hooks.
|
|
3
|
+
*
|
|
4
|
+
* A budget is a pool of milliseconds that only drains while one of its own
|
|
5
|
+
* sweeps is running, so gate-done can give the Vitest sweep its own allowance
|
|
6
|
+
* without the fast sweeps (gitleaks, bundle) eating into it.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { spawnSync } from 'node:child_process';
|
|
10
|
+
|
|
11
|
+
export const DEFAULT_BUDGET_MS = 90_000;
|
|
12
|
+
export const DEFAULT_TEST_BUDGET_MS = 300_000;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Read a budget in milliseconds from `env[name]`.
|
|
16
|
+
* Unset or empty falls back to the default; anything that is not a positive
|
|
17
|
+
* integer also falls back, and `invalid` carries the rejected raw value so the
|
|
18
|
+
* caller can warn about it.
|
|
19
|
+
*/
|
|
20
|
+
export function readBudgetMs(env, name, fallback) {
|
|
21
|
+
const raw = env[name];
|
|
22
|
+
if (raw === undefined || raw.trim() === '') return { ms: fallback, source: 'default' };
|
|
23
|
+
const ms = Number(raw.trim());
|
|
24
|
+
if (!Number.isInteger(ms) || ms <= 0) return { ms: fallback, source: 'default', invalid: raw };
|
|
25
|
+
return { ms, source: 'env' };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function createBudget(name, envVar, ms, now = Date.now) {
|
|
29
|
+
let spentMs = 0;
|
|
30
|
+
return {
|
|
31
|
+
name,
|
|
32
|
+
envVar,
|
|
33
|
+
ms,
|
|
34
|
+
spent: () => spentMs,
|
|
35
|
+
remaining: () => Math.max(0, ms - spentMs),
|
|
36
|
+
exhausted: () => spentMs >= ms,
|
|
37
|
+
/** Charge the time `fn` takes to this budget and return its result. */
|
|
38
|
+
track(fn) {
|
|
39
|
+
const start = now();
|
|
40
|
+
try {
|
|
41
|
+
return fn();
|
|
42
|
+
} finally {
|
|
43
|
+
spentMs += now() - start;
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Run a shell command with the budget's remaining time as the child timeout.
|
|
51
|
+
* `timedOut` is true when the child was killed because the budget ran out,
|
|
52
|
+
* as opposed to exiting non-zero on its own.
|
|
53
|
+
*/
|
|
54
|
+
export function runInBudget(budget, cmd, options = {}) {
|
|
55
|
+
const before = budget.spent();
|
|
56
|
+
const result = budget.track(() =>
|
|
57
|
+
spawnSync(cmd, { shell: true, encoding: 'utf8', ...options, timeout: budget.remaining() }),
|
|
58
|
+
);
|
|
59
|
+
const durationMs = budget.spent() - before;
|
|
60
|
+
return { ...result, durationMs, timedOut: result.error?.code === 'ETIMEDOUT' };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Human-readable reason a sweep was killed by its budget; not a test failure. */
|
|
64
|
+
export function budgetKillMessage(label, budget, durationMs) {
|
|
65
|
+
const secs = (durationMs / 1000).toFixed(1);
|
|
66
|
+
return (
|
|
67
|
+
`${label} killed after ${secs}s by the ${budget.name} budget ` +
|
|
68
|
+
`(${budget.envVar}=${budget.ms}) — not a test failure. ` +
|
|
69
|
+
`Raise ${budget.envVar} (milliseconds) if the run is legitimately slow.`
|
|
70
|
+
);
|
|
71
|
+
}
|