@widgetic/dev-tools 0.2.0 → 0.3.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 +56 -18
- package/README.md +60 -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 +77 -0
- package/lib/lockfile-peers.mjs +193 -0
- package/lib/readme-contract.d.mts +99 -0
- package/lib/readme-contract.mjs +307 -0
- package/lib/semver-lite.mjs +71 -0
- package/package.json +11 -4
- package/test/lockfile-peers.test.mjs +208 -0
- package/test/readme-contract.test.mjs +459 -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
|
+
});
|
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Does the README contract actually fail when an adopter's prose drifts?
|
|
4
|
+
*
|
|
5
|
+
* `readme-contract.mjs` guards the one paragraph six Frontend apps copy by
|
|
6
|
+
* hand: the sibling-source section that says how their dev-alias setup works.
|
|
7
|
+
* A contract every README holds by copy-paste rots three ways, and all three
|
|
8
|
+
* already happened — a section teaching the retired hand-linking practice,
|
|
9
|
+
* a full adopter with no section at all (`file-browser`), and six forked
|
|
10
|
+
* wordings that made every workflow change a six-edit affair. All of it
|
|
11
|
+
* degrades silently: nothing fails, the section just stops being true.
|
|
12
|
+
*
|
|
13
|
+
* The second tier is the packages that link a sibling by hand instead of
|
|
14
|
+
* compiling its source — `embed-sdk`, `recorder`, `ui-sdk`. Their READMEs
|
|
15
|
+
* were read by nothing at all: not the adopters' check, not a test. They get
|
|
16
|
+
* no canonical section (it would be false) but they do get the
|
|
17
|
+
* retired-instruction ban, and both rules are driven here.
|
|
18
|
+
*
|
|
19
|
+
* Each rule is driven here against a throwaway checkout — READMEs written to
|
|
20
|
+
* drift on purpose, wrapped differently than the canonical prose — asserting
|
|
21
|
+
* on `collectReadmeDrift`'s findings. The false-positive shapes matter as
|
|
22
|
+
* much as the true ones: a checker that flags file-browser's `pnpm link`
|
|
23
|
+
* packaging prose (how *other* projects consume file-browser) or a bullet
|
|
24
|
+
* note beside the prose gets switched off within a day.
|
|
25
|
+
*
|
|
26
|
+
* The real checkout is checked too, with the `FRONTEND_DISK` skip pattern:
|
|
27
|
+
* the layout fixtures gate the alias tables against the disk the same way,
|
|
28
|
+
* and both skip where the sibling checkout cannot exist (a standalone clone,
|
|
29
|
+
* CI in the published package) rather than fail.
|
|
30
|
+
*
|
|
31
|
+
* Runs on the built-in test runner — no framework, no dependencies:
|
|
32
|
+
*
|
|
33
|
+
* npm run test:readme (in this repo)
|
|
34
|
+
* npx check-readme-contracts (in a consumer, against what it installed)
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
38
|
+
import { tmpdir } from 'node:os';
|
|
39
|
+
import { join } from 'node:path';
|
|
40
|
+
import { fileURLToPath } from 'node:url';
|
|
41
|
+
import { after, describe, it } from 'node:test';
|
|
42
|
+
import assert from 'node:assert/strict';
|
|
43
|
+
|
|
44
|
+
import {
|
|
45
|
+
ADOPTER_PACKAGES,
|
|
46
|
+
CANONICAL_PUBLISH_SENTENCES,
|
|
47
|
+
CANONICAL_SENTENCES,
|
|
48
|
+
CHECKED_PACKAGES,
|
|
49
|
+
LINKING_PACKAGES,
|
|
50
|
+
PUBLISH_PACKAGES,
|
|
51
|
+
collectReadmeDrift,
|
|
52
|
+
readmeFindings,
|
|
53
|
+
staleInstructionHits
|
|
54
|
+
} from '../lib/readme-contract.mjs';
|
|
55
|
+
|
|
56
|
+
const FRONTEND = fileURLToPath(new URL('../..', import.meta.url));
|
|
57
|
+
const DISK_OK = existsSync(join(FRONTEND, 'site', 'package.json'));
|
|
58
|
+
|
|
59
|
+
/** Every fixture this run created, so a failure cannot leave one behind. */
|
|
60
|
+
const created = [];
|
|
61
|
+
after(() => {
|
|
62
|
+
for (const root of created) rmSync(root, { recursive: true, force: true });
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
/** A throwaway Frontend checkout. `readmes` maps adopter → raw README text. */
|
|
66
|
+
function checkout(readmes) {
|
|
67
|
+
const root = mkdtempSync(join(tmpdir(), 'readme-contract-'));
|
|
68
|
+
created.push(root);
|
|
69
|
+
for (const [pkg, text] of Object.entries(readmes)) {
|
|
70
|
+
const dir = join(root, pkg);
|
|
71
|
+
mkdirSync(dir, { recursive: true });
|
|
72
|
+
writeFileSync(join(dir, 'README.md'), text);
|
|
73
|
+
}
|
|
74
|
+
return root;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The findings for one fixture root, filtered by kind and/or adopter. */
|
|
78
|
+
function findingsFor(root, { kind, pkg } = {}) {
|
|
79
|
+
return collectReadmeDrift(root).findings.filter(
|
|
80
|
+
(f) => (kind ? f.kind === kind : true) && (pkg ? f.pkg === pkg : true)
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The canonical section, wrapped for one adopter's line width. */
|
|
85
|
+
function section(wrap) {
|
|
86
|
+
const words = CANONICAL_SENTENCES.join(' ').split(' ');
|
|
87
|
+
const lines = [];
|
|
88
|
+
let line = '';
|
|
89
|
+
for (const word of words) {
|
|
90
|
+
if (line && `${line} ${word}`.length > wrap) {
|
|
91
|
+
lines.push(line);
|
|
92
|
+
line = word;
|
|
93
|
+
} else {
|
|
94
|
+
line = line ? `${line} ${word}` : word;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
if (line) lines.push(line);
|
|
98
|
+
return `## Sibling packages\n\n${lines.join('\n')}\n`;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** The canonical publish-preparation prose, wrapped like an adopter's. */
|
|
102
|
+
function publishSection() {
|
|
103
|
+
const words = CANONICAL_PUBLISH_SENTENCES.join(' ').split(' ');
|
|
104
|
+
const lines = [];
|
|
105
|
+
let line = '';
|
|
106
|
+
for (const word of words) {
|
|
107
|
+
if (line && `${line} ${word}`.length > 72) {
|
|
108
|
+
lines.push(line);
|
|
109
|
+
line = word;
|
|
110
|
+
} else {
|
|
111
|
+
line = line ? `${line} ${word}` : word;
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
if (line) lines.push(line);
|
|
115
|
+
return `## Publishing\n\n${lines.join('\n')}\n`;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** A README that names dev-tools but carries none of the canonical prose. */
|
|
119
|
+
const DRIFTED_ONLY = [
|
|
120
|
+
'## Sibling packages',
|
|
121
|
+
'',
|
|
122
|
+
'This app compiles sibling `@widgetic/*` packages from source in dev. The',
|
|
123
|
+
'alias tables come from the installed `@widgetic/dev-tools` dependency — an',
|
|
124
|
+
'ordinary `npm install` is all the setup there is.',
|
|
125
|
+
'',
|
|
126
|
+
'The why and the silent-degrade failure mode live in',
|
|
127
|
+
'[the dev-tools README](../dev-tools/README.md).',
|
|
128
|
+
''
|
|
129
|
+
].join('\n');
|
|
130
|
+
|
|
131
|
+
/** A clean adopter README: canonical prose plus app-specific extras. */
|
|
132
|
+
const CLEAN = `${section(72)}
|
|
133
|
+
|
|
134
|
+
### Chat iteration without publishing
|
|
135
|
+
|
|
136
|
+
- \`npm run lps\` links the chat sibling for iteration without publishing.
|
|
137
|
+
`;
|
|
138
|
+
|
|
139
|
+
/** Prose an adopter and a linking package may both carry, before any tools. */
|
|
140
|
+
const PLAIN = '# Some app\n\nNotes about the app, saying nothing about siblings.\n';
|
|
141
|
+
|
|
142
|
+
describe('the canonical sentence matcher', () => {
|
|
143
|
+
it('accepts the prose wrapped to any line width', () => {
|
|
144
|
+
for (const wrap of [40, 60, 72, 88, 200]) {
|
|
145
|
+
const f = readmeFindings('demo', 'demo/README.md', section(wrap));
|
|
146
|
+
assert.deepEqual(f, [], `wrap ${wrap} should pass`);
|
|
147
|
+
}
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
it('rejects a reworded sentence, naming the first divergence', () => {
|
|
151
|
+
const reworded = section(72).replace(
|
|
152
|
+
'there is no linking step',
|
|
153
|
+
'no linking step is involved'
|
|
154
|
+
);
|
|
155
|
+
const f = readmeFindings('demo', 'demo/README.md', reworded);
|
|
156
|
+
assert.equal(f.length, 1);
|
|
157
|
+
assert.equal(f[0].kind, 'ldt section drift');
|
|
158
|
+
// The finding names the first canonical sentence that is missing, so the
|
|
159
|
+
// repair knows exactly which words to restore.
|
|
160
|
+
assert.match(f[0].detail, /An ordinary `npm install` is the whole setup/);
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
it('rejects reordered sentences even with the wording intact', () => {
|
|
164
|
+
const reordered = [
|
|
165
|
+
CANONICAL_SENTENCES[1],
|
|
166
|
+
CANONICAL_SENTENCES[0],
|
|
167
|
+
CANONICAL_SENTENCES[3],
|
|
168
|
+
CANONICAL_SENTENCES[2]
|
|
169
|
+
].join(' ');
|
|
170
|
+
const f = readmeFindings('demo', 'demo/README.md', reordered);
|
|
171
|
+
assert.equal(f.length, 1);
|
|
172
|
+
assert.equal(f[0].kind, 'ldt section drift');
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
it('accepts app-specific sentences interleaved between canonical ones', () => {
|
|
176
|
+
const interleaved = [
|
|
177
|
+
'Intro of the app\u2019s own.',
|
|
178
|
+
CANONICAL_SENTENCES[0],
|
|
179
|
+
'A middle sentence of the app\u2019s own.',
|
|
180
|
+
CANONICAL_SENTENCES[1],
|
|
181
|
+
CANONICAL_SENTENCES[2],
|
|
182
|
+
'Another sentence of the app\u2019s own.',
|
|
183
|
+
CANONICAL_SENTENCES[3]
|
|
184
|
+
].join(' ');
|
|
185
|
+
assert.deepEqual(readmeFindings('demo', 'demo/README.md', interleaved), []);
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
it('accepts prose after the block that reuses section vocabulary', () => {
|
|
189
|
+
const after = `${section(72)}
|
|
190
|
+
|
|
191
|
+
The setup above has no linking step and nothing to re-run. The app also
|
|
192
|
+
ships a \`dev:ds\` script for design-system iteration; the workflow it uses
|
|
193
|
+
lives in the dev-tools README.
|
|
194
|
+
`;
|
|
195
|
+
assert.deepEqual(readmeFindings('demo', 'demo/README.md', after), []);
|
|
196
|
+
});
|
|
197
|
+
|
|
198
|
+
it('reports a missing section plainly when the README never mentions dev-tools', () => {
|
|
199
|
+
const f = readmeFindings('demo', 'demo/README.md', '# Demo\n\nJust an app.\n');
|
|
200
|
+
assert.equal(f.length, 1);
|
|
201
|
+
assert.equal(f[0].kind, 'ldt section missing');
|
|
202
|
+
assert.match(f[0].detail, /no sibling-source section/);
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
it('reports drift, not missing, when dev-tools is named but the prose diverges', () => {
|
|
206
|
+
const f = readmeFindings('demo', 'demo/README.md', DRIFTED_ONLY);
|
|
207
|
+
assert.equal(f.length, 1);
|
|
208
|
+
assert.equal(f[0].kind, 'ldt section drift');
|
|
209
|
+
});
|
|
210
|
+
|
|
211
|
+
it('treats an absent README as a missing section', () => {
|
|
212
|
+
const f = readmeFindings('demo', 'demo/README.md', '');
|
|
213
|
+
assert.equal(f.length, 1);
|
|
214
|
+
assert.equal(f[0].kind, 'ldt section missing');
|
|
215
|
+
});
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
describe('stale link-era instructions', () => {
|
|
219
|
+
it('flags the retired patterns wherever prose carries them', () => {
|
|
220
|
+
const hits = staleInstructionHits(
|
|
221
|
+
'Run `npm run ldt` or `npm link @widgetic/dev-tools`; `volta run npm i` works too. ' +
|
|
222
|
+
'Use `llinks` to verify; the entry must be re-run after installs, ' +
|
|
223
|
+
'and the old `typescript-sdk` name is dead.'
|
|
224
|
+
);
|
|
225
|
+
assert.deepEqual(hits, [
|
|
226
|
+
'`npm run ldt`',
|
|
227
|
+
'`npm link`',
|
|
228
|
+
'`volta run`',
|
|
229
|
+
'the `llinks` verify script',
|
|
230
|
+
'the after-install re-run instruction',
|
|
231
|
+
'the retired `typescript-sdk` package name'
|
|
232
|
+
]);
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
it('does not flag `pnpm link` inside the npm-link pattern', () => {
|
|
236
|
+
assert.deepEqual(
|
|
237
|
+
staleInstructionHits('Other projects use `pnpm link --global @widgetic/file-browser`.'),
|
|
238
|
+
[]
|
|
239
|
+
);
|
|
240
|
+
});
|
|
241
|
+
|
|
242
|
+
it('does not flag prose that merely describes the era in passing', () => {
|
|
243
|
+
assert.deepEqual(
|
|
244
|
+
staleInstructionHits('The retired practice was a symlink recreated by hand after installs.'),
|
|
245
|
+
[]
|
|
246
|
+
);
|
|
247
|
+
});
|
|
248
|
+
|
|
249
|
+
it('scans outside fenced blocks only', () => {
|
|
250
|
+
const withFence = `${section(72)}
|
|
251
|
+
|
|
252
|
+
\`\`\`sh
|
|
253
|
+
# historical: npm run ldt after every install
|
|
254
|
+
npm run llinks
|
|
255
|
+
\`\`\`
|
|
256
|
+
`;
|
|
257
|
+
assert.deepEqual(readmeFindings('demo', 'demo/README.md', withFence), []);
|
|
258
|
+
});
|
|
259
|
+
});
|
|
260
|
+
|
|
261
|
+
describe('the publish contract', () => {
|
|
262
|
+
it('publishes to exactly the packages that ship a dist tarball', { skip: !DISK_OK }, () => {
|
|
263
|
+
assert.deepEqual(PUBLISH_PACKAGES, ['chat', 'file-browser']);
|
|
264
|
+
assert.ok(PUBLISH_PACKAGES.every((p) => ADOPTER_PACKAGES.includes(p)));
|
|
265
|
+
// Every publisher ships `files: ['dist']` — the sentence that calls
|
|
266
|
+
// dist the tarball's only content must match manifest reality.
|
|
267
|
+
for (const pkg of PUBLISH_PACKAGES) {
|
|
268
|
+
const manifest = JSON.parse(
|
|
269
|
+
readFileSync(join(FRONTEND, pkg, 'package.json'), 'utf8')
|
|
270
|
+
);
|
|
271
|
+
assert.deepEqual(manifest.files, ['dist']);
|
|
272
|
+
}
|
|
273
|
+
});
|
|
274
|
+
|
|
275
|
+
it('accepts a publisher whose README carries the publish sentences plus its own flow notes', () => {
|
|
276
|
+
const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${publishSection()}\n`);
|
|
277
|
+
assert.deepEqual(f, []);
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
it('accepts fenced publish commands without scanning them', () => {
|
|
281
|
+
const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${publishSection()}\n\n\`\`\`sh\nnpm publish\n\`\`\`\n`);
|
|
282
|
+
assert.deepEqual(f, []);
|
|
283
|
+
});
|
|
284
|
+
|
|
285
|
+
it('reports a missing publish section on a publisher without one', () => {
|
|
286
|
+
const f = readmeFindings('chat', 'chat/README.md', CLEAN);
|
|
287
|
+
assert.deepEqual(f.map((x) => x.kind), ['publish section missing']);
|
|
288
|
+
});
|
|
289
|
+
|
|
290
|
+
it('reports drift when the publish prose is reworded, naming the first gap', () => {
|
|
291
|
+
const reworded = publishSection().replace('land as one commit', 'are committed together');
|
|
292
|
+
const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${reworded}`);
|
|
293
|
+
assert.equal(f.length, 1);
|
|
294
|
+
assert.equal(f[0].kind, 'publish section drift');
|
|
295
|
+
assert.match(f[0].detail, /land as one commit/);
|
|
296
|
+
});
|
|
297
|
+
|
|
298
|
+
it('reports a missing publish section too when the README is absent', () => {
|
|
299
|
+
const f = readmeFindings('chat', 'chat/README.md', '');
|
|
300
|
+
assert.deepEqual(f.map((x) => x.kind), ['ldt section missing', 'publish section missing']);
|
|
301
|
+
});
|
|
302
|
+
|
|
303
|
+
it('requires nothing extra from packages that do not publish', () => {
|
|
304
|
+
const f = readmeFindings('editor', 'editor/README.md', CLEAN);
|
|
305
|
+
assert.deepEqual(f, []);
|
|
306
|
+
});
|
|
307
|
+
});
|
|
308
|
+
|
|
309
|
+
describe('the checkout collector', () => {
|
|
310
|
+
it('accepts a checkout where every adopter carries its sections', () => {
|
|
311
|
+
const root = checkout(
|
|
312
|
+
Object.fromEntries(
|
|
313
|
+
ADOPTER_PACKAGES.map((p) => [
|
|
314
|
+
p,
|
|
315
|
+
PUBLISH_PACKAGES.includes(p) ? `${CLEAN}\n\n${publishSection()}` : CLEAN
|
|
316
|
+
])
|
|
317
|
+
)
|
|
318
|
+
);
|
|
319
|
+
assert.deepEqual(collectReadmeDrift(root), {
|
|
320
|
+
packages: [...CHECKED_PACKAGES],
|
|
321
|
+
findings: []
|
|
322
|
+
});
|
|
323
|
+
});
|
|
324
|
+
|
|
325
|
+
it('fails the checkout where one adopter drifted and one is missing', () => {
|
|
326
|
+
const root = checkout({
|
|
327
|
+
site: DRIFTED_ONLY,
|
|
328
|
+
editor: CLEAN,
|
|
329
|
+
'widget-creator': '# Just an app.\n'
|
|
330
|
+
});
|
|
331
|
+
const f = collectReadmeDrift(root, {
|
|
332
|
+
packages: ['site', 'editor', 'widget-creator']
|
|
333
|
+
}).findings;
|
|
334
|
+
assert.deepEqual(
|
|
335
|
+
f.map((x) => [x.pkg, x.kind]),
|
|
336
|
+
[
|
|
337
|
+
['site', 'ldt section drift'],
|
|
338
|
+
['widget-creator', 'ldt section missing']
|
|
339
|
+
]
|
|
340
|
+
);
|
|
341
|
+
});
|
|
342
|
+
|
|
343
|
+
it('checks every default subject, including ones with no README', () => {
|
|
344
|
+
const root = checkout({ site: CLEAN });
|
|
345
|
+
const f = findingsFor(root);
|
|
346
|
+
// Five adopters missing the sibling section, plus the two publishers
|
|
347
|
+
// missing the publish section on top of it. The linking packages are
|
|
348
|
+
// subjects too, but a README that is not there teaches nothing.
|
|
349
|
+
assert.equal(f.length, ADOPTER_PACKAGES.length - 1 + PUBLISH_PACKAGES.length);
|
|
350
|
+
assert.ok(f.every((x) => x.kind === 'ldt section missing' || x.kind === 'publish section missing'));
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
it('honors an explicit package list', () => {
|
|
354
|
+
const root = checkout({ site: CLEAN, editor: DRIFTED_ONLY });
|
|
355
|
+
const { findings } = collectReadmeDrift(root, { packages: ['site'] });
|
|
356
|
+
assert.deepEqual(findings, []);
|
|
357
|
+
});
|
|
358
|
+
|
|
359
|
+
it('refuses the retired `adopters` option name instead of checking the defaults', () => {
|
|
360
|
+
const root = checkout({ site: CLEAN });
|
|
361
|
+
assert.throws(
|
|
362
|
+
() => collectReadmeDrift(root, { adopters: ['site'] }),
|
|
363
|
+
/renamed to `packages`/
|
|
364
|
+
);
|
|
365
|
+
});
|
|
366
|
+
});
|
|
367
|
+
|
|
368
|
+
describe('the linking tier', () => {
|
|
369
|
+
it('reads the three hand-linking packages by default', () => {
|
|
370
|
+
assert.deepEqual(LINKING_PACKAGES, ['embed-sdk', 'recorder', 'ui-sdk']);
|
|
371
|
+
// Every linking package is a subject, and none of them is an adopter:
|
|
372
|
+
// the canonical sentences would be false in their READMEs.
|
|
373
|
+
assert.ok(LINKING_PACKAGES.every((p) => CHECKED_PACKAGES.includes(p)));
|
|
374
|
+
assert.ok(LINKING_PACKAGES.every((p) => !ADOPTER_PACKAGES.includes(p)));
|
|
375
|
+
for (const pkg of LINKING_PACKAGES) {
|
|
376
|
+
assert.deepEqual(findingsFor(checkout({ [pkg]: PLAIN }), { pkg }), []);
|
|
377
|
+
}
|
|
378
|
+
});
|
|
379
|
+
|
|
380
|
+
it('fails a linking README that teaches the retired hand-linking', () => {
|
|
381
|
+
const root = checkout({
|
|
382
|
+
'embed-sdk': '# Widgetic Embed SDK\n\nInstall the sibling: `npm link @widgetic/api-sdk`.\n'
|
|
383
|
+
});
|
|
384
|
+
const f = findingsFor(root, { pkg: 'embed-sdk' });
|
|
385
|
+
assert.equal(f.length, 1);
|
|
386
|
+
assert.equal(f[0].kind, 'ldt section drift');
|
|
387
|
+
assert.match(f[0].detail, /link-era instructions present/);
|
|
388
|
+
assert.match(f[0].detail, /`npm link`/);
|
|
389
|
+
// The repair names this package's actual state — still hand-linking —
|
|
390
|
+
// rather than telling an adopter's story about an ordinary npm install.
|
|
391
|
+
assert.match(f[0].fix, /has not adopted the dev-alias workflow/);
|
|
392
|
+
});
|
|
393
|
+
|
|
394
|
+
it('flags every retired pattern in a linking README, wherever it appears', () => {
|
|
395
|
+
const root = checkout({
|
|
396
|
+
'ui-sdk':
|
|
397
|
+
'# Widgetic UI SDK\n\nRun `npm run ldt` to link, then `npx llinks` to verify,\n' +
|
|
398
|
+
'and the symlink must be re-run after installs.\n'
|
|
399
|
+
});
|
|
400
|
+
const f = findingsFor(root, { pkg: 'ui-sdk' });
|
|
401
|
+
assert.equal(f.length, 1);
|
|
402
|
+
assert.match(f[0].detail, /`npm run ldt`/);
|
|
403
|
+
assert.match(f[0].detail, /the `llinks` verify script/);
|
|
404
|
+
assert.match(f[0].detail, /the after-install re-run instruction/);
|
|
405
|
+
});
|
|
406
|
+
|
|
407
|
+
it('does not require the canonical sentences — but an adopter carrying that text still must', () => {
|
|
408
|
+
// Same prose, two tiers: nothing about it is missing for a linking
|
|
409
|
+
// package, while an adopter is missing the whole canonical section.
|
|
410
|
+
assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', PLAIN), []);
|
|
411
|
+
const adopter = readmeFindings('site', 'site/README.md', PLAIN);
|
|
412
|
+
assert.deepEqual(adopter.map((x) => x.kind), ['ldt section missing']);
|
|
413
|
+
});
|
|
414
|
+
|
|
415
|
+
it('does not require the publish sentences from a linking package either', () => {
|
|
416
|
+
// The publish tier is about the two packages that ship a dist tarball;
|
|
417
|
+
// a linking package is never asked for those sentences.
|
|
418
|
+
assert.deepEqual(readmeFindings('ui-sdk', 'ui-sdk/README.md', `${PLAIN}\nPublishing notes.\n`), []);
|
|
419
|
+
});
|
|
420
|
+
|
|
421
|
+
it('exempts fenced examples, exactly as the adopter tier does', () => {
|
|
422
|
+
const fenced = `${PLAIN}\n\`\`\`sh\n# historical: npm link @widgetic/api-sdk\n\`\`\`\n`;
|
|
423
|
+
assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', fenced), []);
|
|
424
|
+
});
|
|
425
|
+
|
|
426
|
+
it('flags the same words when prose carries them rather than a fence', () => {
|
|
427
|
+
// The counterpart of the fence test: outside a fence, the words fail.
|
|
428
|
+
const proseForm = `${PLAIN}\nHistorical note: npm link @widgetic/api-sdk was how it used to work.\n`;
|
|
429
|
+
const f = readmeFindings('recorder', 'recorder/README.md', proseForm);
|
|
430
|
+
assert.equal(f.length, 1);
|
|
431
|
+
assert.equal(f[0].kind, 'ldt section drift');
|
|
432
|
+
});
|
|
433
|
+
});
|
|
434
|
+
|
|
435
|
+
describe('the real Frontend checkout', { skip: !DISK_OK }, () => {
|
|
436
|
+
it('is clean — every adopter carries the canonical sections, in the canonical wording', () => {
|
|
437
|
+
const { findings } = collectReadmeDrift(FRONTEND);
|
|
438
|
+
assert.deepEqual(
|
|
439
|
+
findings,
|
|
440
|
+
[],
|
|
441
|
+
`READMEs drifted from the contract:\n${findings
|
|
442
|
+
.map((x) => ` ${x.pkg}: ${x.detail}`)
|
|
443
|
+
.join('\n')}`
|
|
444
|
+
);
|
|
445
|
+
});
|
|
446
|
+
|
|
447
|
+
it('reads both tiers off the disk, so a real README cannot go unchecked', () => {
|
|
448
|
+
const { packages } = collectReadmeDrift(FRONTEND);
|
|
449
|
+
assert.deepEqual(packages, CHECKED_PACKAGES);
|
|
450
|
+
// A subject whose file vanished would pass a prose scan vacuously, so
|
|
451
|
+
// this asserts the three linking READMEs are really there to be read.
|
|
452
|
+
for (const pkg of LINKING_PACKAGES) {
|
|
453
|
+
assert.ok(
|
|
454
|
+
existsSync(join(FRONTEND, pkg, 'README.md')),
|
|
455
|
+
`${pkg}/README.md is a contract subject and must exist`
|
|
456
|
+
);
|
|
457
|
+
}
|
|
458
|
+
});
|
|
459
|
+
});
|