@widgetic/dev-tools 0.2.0 → 0.3.1
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 +90 -18
- package/README.md +114 -35
- package/bin/check-design-system-peers.mjs +53 -0
- package/bin/check-layout-fixtures.mjs +0 -0
- package/bin/check-links-fixtures.mjs +0 -0
- package/bin/check-links.mjs +0 -0
- package/bin/check-readme-contracts-fixtures.mjs +27 -0
- package/bin/check-readme-contracts.mjs +82 -0
- package/lib/frontend-layout.mjs +10 -1
- package/lib/lockfile-peers.mjs +193 -0
- package/lib/readme-contract.d.mts +130 -0
- package/lib/readme-contract.mjs +385 -0
- package/lib/semver-lite.mjs +71 -0
- package/package.json +11 -4
- package/test/frontend-layout.test.mjs +6 -0
- package/test/lockfile-peers.test.mjs +208 -0
- package/test/readme-contract.test.mjs +543 -0
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Does the lockfile-peers check actually fail when coordination breaks?
|
|
4
|
+
*
|
|
5
|
+
* Each rule is driven against a throwaway Frontend checkout — manifests,
|
|
6
|
+
* lockfiles and the design-system checkout written to disagree on purpose —
|
|
7
|
+
* asserting on `collectPeersProblems`'s findings. The false-positive shapes
|
|
8
|
+
* matter as much as the true ones: a checker that red-flags an aligned pair,
|
|
9
|
+
* an exact-pin consumer, or a `>=` peer gets switched off within a day.
|
|
10
|
+
*
|
|
11
|
+
* Fixtures are built in the OS temp dir, never in the package.
|
|
12
|
+
*
|
|
13
|
+
* Runs on the built-in test runner:
|
|
14
|
+
*
|
|
15
|
+
* npm run test:peers
|
|
16
|
+
*/
|
|
17
|
+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
18
|
+
import { spawnSync } from 'node:child_process';
|
|
19
|
+
import { tmpdir } from 'node:os';
|
|
20
|
+
import { join } from 'node:path';
|
|
21
|
+
import { fileURLToPath } from 'node:url';
|
|
22
|
+
import { after, describe, it } from 'node:test';
|
|
23
|
+
import assert from 'node:assert/strict';
|
|
24
|
+
|
|
25
|
+
import { collectPeersProblems, formatPeersProblems } from '../lib/lockfile-peers.mjs';
|
|
26
|
+
import { satisfies } from '../lib/semver-lite.mjs';
|
|
27
|
+
|
|
28
|
+
const DT_ROOT = fileURLToPath(new URL('..', import.meta.url));
|
|
29
|
+
|
|
30
|
+
const root = mkdtempSync(join(tmpdir(), 'dt-peers-'));
|
|
31
|
+
after(() => rmSync(root, { recursive: true, force: true }));
|
|
32
|
+
|
|
33
|
+
/** Write `root/<pkg>/<file>` with parent dirs. */
|
|
34
|
+
function put(pkg, file, content) {
|
|
35
|
+
const dir = join(root, pkg);
|
|
36
|
+
mkdirSync(dir, { recursive: true });
|
|
37
|
+
writeFileSync(join(dir, file), content);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** A healthy two-peer checkout: both resolve V, both declare ^V, checkout carries V. */
|
|
41
|
+
function healthyAt(version) {
|
|
42
|
+
for (const pkg of ['canvas', 'file-browser']) {
|
|
43
|
+
put(pkg, 'package.json', JSON.stringify({
|
|
44
|
+
name: pkg,
|
|
45
|
+
dependencies: { '@widgetic/design-system': `^${version}` }
|
|
46
|
+
}));
|
|
47
|
+
put(pkg, 'package-lock.json', JSON.stringify({
|
|
48
|
+
lockfileVersion: 3,
|
|
49
|
+
packages: { 'node_modules/@widgetic/design-system': { version } }
|
|
50
|
+
}));
|
|
51
|
+
}
|
|
52
|
+
put('design-system', 'package.json', JSON.stringify({
|
|
53
|
+
name: '@widgetic/design-system',
|
|
54
|
+
version
|
|
55
|
+
}));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function problemsFor(mutate) {
|
|
59
|
+
if (mutate) mutate();
|
|
60
|
+
return collectPeersProblems(root);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
describe('semver-lite', () => {
|
|
64
|
+
it('admits carets, >= peers, and exact pins', () => {
|
|
65
|
+
assert.equal(satisfies('0.5.14', '^0.5.12'), true);
|
|
66
|
+
assert.equal(satisfies('0.5.12', '^0.5.12'), true);
|
|
67
|
+
assert.equal(satisfies('0.6.0', '^0.5.12'), false); // ^0.x pins the minor
|
|
68
|
+
assert.equal(satisfies('1.9.0', '^1.2.3'), true); // non-zero major opens the minor
|
|
69
|
+
assert.equal(satisfies('2.0.0', '^1.2.3'), false);
|
|
70
|
+
assert.equal(satisfies('0.5.14', '>=0.3.0'), true);
|
|
71
|
+
assert.equal(satisfies('0.5.14', '0.5.14'), true);
|
|
72
|
+
assert.equal(satisfies('0.5.15', '0.5.14'), false);
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
it('fails closed on shapes it does not understand', () => {
|
|
76
|
+
assert.equal(satisfies('0.5.14', 'workspace:*'), false);
|
|
77
|
+
assert.equal(satisfies('0.5.14', '~0.5.12'), false); // tilde out of vocabulary on purpose
|
|
78
|
+
assert.equal(satisfies('0.5.14-beta.1', '^0.5.12'), false);
|
|
79
|
+
assert.equal(satisfies('not-a-version', '^1.0.0'), false);
|
|
80
|
+
});
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
describe('collectPeersProblems', () => {
|
|
84
|
+
it('passes the healthy aligned pair — no false positive', () => {
|
|
85
|
+
assert.deepEqual(problemsFor(() => healthyAt('0.5.14')), []);
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
it('passes an exact-pin consumer whose pin matches', () => {
|
|
89
|
+
healthyAt('0.5.14');
|
|
90
|
+
put('file-browser', 'package.json', JSON.stringify({
|
|
91
|
+
name: 'file-browser',
|
|
92
|
+
dependencies: { '@widgetic/design-system': '0.5.14' }
|
|
93
|
+
}));
|
|
94
|
+
assert.deepEqual(collectPeersProblems(root), []);
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
it('flags version divergence when the lockfiles disagree within the same range', () => {
|
|
98
|
+
healthyAt('0.5.14');
|
|
99
|
+
put('file-browser', 'package-lock.json', JSON.stringify({
|
|
100
|
+
lockfileVersion: 3,
|
|
101
|
+
packages: { 'node_modules/@widgetic/design-system': { version: '0.5.12' } }
|
|
102
|
+
}));
|
|
103
|
+
const problems = collectPeersProblems(root);
|
|
104
|
+
// Two findings: the divergence itself, and checkout-sync for file-browser
|
|
105
|
+
// (its 0.5.12 lock also differs from the checkout's 0.5.14 — the exact
|
|
106
|
+
// shape the real repo was in before the alignment commit).
|
|
107
|
+
assert.equal(problems.length, 2);
|
|
108
|
+
assert.equal(problems[0].kind, 'version-divergence');
|
|
109
|
+
assert.match(problems[0].detail, /canvas 0\.5\.14/);
|
|
110
|
+
assert.match(problems[0].detail, /file-browser 0\.5\.12/);
|
|
111
|
+
assert.match(problems[0].fix, /coordinated/);
|
|
112
|
+
assert.equal(problems[1].kind, 'checkout-sync');
|
|
113
|
+
assert.equal(problems[1].pkg, 'file-browser');
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
it('fires at the next publish: stale ranges and out-of-sync lockfiles, two findings per peer', () => {
|
|
117
|
+
healthyAt('0.5.14');
|
|
118
|
+
put('design-system', 'package.json', JSON.stringify({
|
|
119
|
+
name: '@widgetic/design-system',
|
|
120
|
+
version: '0.6.0'
|
|
121
|
+
}));
|
|
122
|
+
const problems = collectPeersProblems(root);
|
|
123
|
+
assert.equal(problems.filter((p) => p.kind === 'stale-manifest').length, 2); // ^0.5.12 cannot admit 0.6.0
|
|
124
|
+
assert.equal(problems.filter((p) => p.kind === 'checkout-sync').length, 2); // locks still at 0.5.14
|
|
125
|
+
assert.ok(problems.every((p) => p.fix.match(/coordinated|together with the other peer/)));
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
it('fires checkout-sync on a minor-only release, which a caret range silently admits', () => {
|
|
129
|
+
healthyAt('0.5.14');
|
|
130
|
+
put('design-system', 'package.json', JSON.stringify({
|
|
131
|
+
name: '@widgetic/design-system',
|
|
132
|
+
version: '0.5.15'
|
|
133
|
+
}));
|
|
134
|
+
const problems = collectPeersProblems(root);
|
|
135
|
+
assert.deepEqual(problems.map((p) => p.kind), ['checkout-sync', 'checkout-sync']);
|
|
136
|
+
assert.match(problems[0].detail, /carries 0\.5\.15 but canvas's lockfile resolves 0\.5\.14/);
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
it('goes quiet again once the coordinated bump lands', () => {
|
|
140
|
+
healthyAt('0.5.14');
|
|
141
|
+
put('design-system', 'package.json', JSON.stringify({
|
|
142
|
+
name: '@widgetic/design-system',
|
|
143
|
+
version: '0.5.15'
|
|
144
|
+
}));
|
|
145
|
+
for (const pkg of ['canvas', 'file-browser']) {
|
|
146
|
+
put(pkg, 'package.json', JSON.stringify({
|
|
147
|
+
name: pkg,
|
|
148
|
+
dependencies: { '@widgetic/design-system': '^0.5.15' }
|
|
149
|
+
}));
|
|
150
|
+
put(pkg, 'package-lock.json', JSON.stringify({
|
|
151
|
+
lockfileVersion: 3,
|
|
152
|
+
packages: { 'node_modules/@widgetic/design-system': { version: '0.5.15' } }
|
|
153
|
+
}));
|
|
154
|
+
}
|
|
155
|
+
assert.deepEqual(collectPeersProblems(root), []);
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
it('reports an unreadable lockfile instead of crashing', () => {
|
|
159
|
+
healthyAt('0.5.14');
|
|
160
|
+
writeFileSync(join(root, 'canvas', 'package-lock.json'), '{ not json');
|
|
161
|
+
const problems = collectPeersProblems(root);
|
|
162
|
+
assert.equal(problems[0].kind, 'unreadable');
|
|
163
|
+
assert.equal(problems[0].pkg, 'canvas');
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
it('reports a lockfile that resolves no design-system at all', () => {
|
|
167
|
+
healthyAt('0.5.14');
|
|
168
|
+
put('canvas', 'package-lock.json', JSON.stringify({ lockfileVersion: 3, packages: {} }));
|
|
169
|
+
const problems = collectPeersProblems(root);
|
|
170
|
+
assert.equal(problems[0].kind, 'unresolved');
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
it('formats findings with kind, detail, and the arrow-fix', () => {
|
|
174
|
+
healthyAt('0.5.14');
|
|
175
|
+
put('file-browser', 'package-lock.json', JSON.stringify({
|
|
176
|
+
lockfileVersion: 3,
|
|
177
|
+
packages: { 'node_modules/@widgetic/design-system': { version: '0.5.12' } }
|
|
178
|
+
}));
|
|
179
|
+
const text = formatPeersProblems(collectPeersProblems(root));
|
|
180
|
+
assert.match(text, /version-divergence/);
|
|
181
|
+
assert.match(text, /→/);
|
|
182
|
+
});
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
describe('the CLI', () => {
|
|
186
|
+
const bin = join(DT_ROOT, 'bin', 'check-design-system-peers.mjs');
|
|
187
|
+
|
|
188
|
+
it('exits 0 on the healthy fixture root', () => {
|
|
189
|
+
healthyAt('0.5.14');
|
|
190
|
+
const { status } = spawnSync(process.execPath, [bin, root], { encoding: 'utf8' });
|
|
191
|
+
assert.equal(status, 0);
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
it('exits 1 on a diverged fixture root and prints the findings', () => {
|
|
195
|
+
put('file-browser', 'package-lock.json', JSON.stringify({
|
|
196
|
+
lockfileVersion: 3,
|
|
197
|
+
packages: { 'node_modules/@widgetic/design-system': { version: '0.5.12' } }
|
|
198
|
+
}));
|
|
199
|
+
const { status, stderr } = spawnSync(process.execPath, [bin, root], { encoding: 'utf8' });
|
|
200
|
+
assert.equal(status, 1);
|
|
201
|
+
assert.match(stderr, /version-divergence/);
|
|
202
|
+
});
|
|
203
|
+
|
|
204
|
+
it('exits 2 without a root argument', () => {
|
|
205
|
+
const { status } = spawnSync(process.execPath, [bin], { encoding: 'utf8' });
|
|
206
|
+
assert.equal(status, 2);
|
|
207
|
+
});
|
|
208
|
+
});
|