@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.
@@ -0,0 +1,543 @@
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_LINKING_SENTENCES,
47
+ CANONICAL_PUBLISH_SENTENCES,
48
+ CANONICAL_SENTENCES,
49
+ CHECKED_PACKAGES,
50
+ LINKING_PACKAGES,
51
+ PUBLISH_PACKAGES,
52
+ collectReadmeDrift,
53
+ readmeFindings,
54
+ staleInstructionHits
55
+ } from '../lib/readme-contract.mjs';
56
+
57
+ const FRONTEND = fileURLToPath(new URL('../..', import.meta.url));
58
+ const DISK_OK = existsSync(join(FRONTEND, 'site', 'package.json'));
59
+
60
+ /** Every fixture this run created, so a failure cannot leave one behind. */
61
+ const created = [];
62
+ after(() => {
63
+ for (const root of created) rmSync(root, { recursive: true, force: true });
64
+ });
65
+
66
+ /** A throwaway Frontend checkout. `readmes` maps adopter → raw README text. */
67
+ function checkout(readmes) {
68
+ const root = mkdtempSync(join(tmpdir(), 'readme-contract-'));
69
+ created.push(root);
70
+ for (const [pkg, text] of Object.entries(readmes)) {
71
+ const dir = join(root, pkg);
72
+ mkdirSync(dir, { recursive: true });
73
+ writeFileSync(join(dir, 'README.md'), text);
74
+ }
75
+ return root;
76
+ }
77
+
78
+ /** The findings for one fixture root, filtered by kind and/or adopter. */
79
+ function findingsFor(root, { kind, pkg } = {}) {
80
+ return collectReadmeDrift(root).findings.filter(
81
+ (f) => (kind ? f.kind === kind : true) && (pkg ? f.pkg === pkg : true)
82
+ );
83
+ }
84
+
85
+ /** One canonical sentence set, joined and wrapped to a line width. */
86
+ function wrapped(sentences, wrap) {
87
+ const words = sentences.join(' ').split(' ');
88
+ const lines = [];
89
+ let line = '';
90
+ for (const word of words) {
91
+ if (line && `${line} ${word}`.length > wrap) {
92
+ lines.push(line);
93
+ line = word;
94
+ } else {
95
+ line = line ? `${line} ${word}` : word;
96
+ }
97
+ }
98
+ if (line) lines.push(line);
99
+ return lines.join('\n');
100
+ }
101
+
102
+ /** The canonical sibling-source section, wrapped for one adopter's width. */
103
+ function section(wrap) {
104
+ return `## Sibling packages\n\n${wrapped(CANONICAL_SENTENCES, wrap)}\n`;
105
+ }
106
+
107
+ /** The canonical linked-sibling section, wrapped the same way. */
108
+ function linkingSection(wrap) {
109
+ return `## Sibling packages\n\n${wrapped(CANONICAL_LINKING_SENTENCES, wrap)}\n`;
110
+ }
111
+
112
+ /** The canonical publish-preparation prose, wrapped like an adopter's. */
113
+ function publishSection() {
114
+ return `## Publishing\n\n${wrapped(CANONICAL_PUBLISH_SENTENCES, 72)}\n`;
115
+ }
116
+
117
+ /** A README that names dev-tools but carries none of the canonical prose. */
118
+ const DRIFTED_ONLY = [
119
+ '## Sibling packages',
120
+ '',
121
+ 'This app compiles sibling `@widgetic/*` packages from source in dev. The',
122
+ 'alias tables come from the installed `@widgetic/dev-tools` dependency — an',
123
+ 'ordinary `npm install` is all the setup there is.',
124
+ '',
125
+ 'The why and the silent-degrade failure mode live in',
126
+ '[the dev-tools README](../dev-tools/README.md).',
127
+ ''
128
+ ].join('\n');
129
+
130
+ /** A clean adopter README: canonical prose plus app-specific extras. */
131
+ const CLEAN = `${section(72)}
132
+
133
+ ### Chat iteration without publishing
134
+
135
+ - \`npm run lps\` links the chat sibling for iteration without publishing.
136
+ `;
137
+
138
+ /** Prose an adopter and a linking package may both carry, before any tools. */
139
+ const PLAIN = '# Some app\n\nNotes about the app, saying nothing about siblings.\n';
140
+
141
+ describe('the canonical sentence matcher', () => {
142
+ it('accepts the prose wrapped to any line width', () => {
143
+ for (const wrap of [40, 60, 72, 88, 200]) {
144
+ const f = readmeFindings('demo', 'demo/README.md', section(wrap));
145
+ assert.deepEqual(f, [], `wrap ${wrap} should pass`);
146
+ }
147
+ });
148
+
149
+ it('rejects a reworded sentence, naming the first divergence', () => {
150
+ const reworded = section(72).replace(
151
+ 'there is no linking step',
152
+ 'no linking step is involved'
153
+ );
154
+ const f = readmeFindings('demo', 'demo/README.md', reworded);
155
+ assert.equal(f.length, 1);
156
+ assert.equal(f[0].kind, 'ldt section drift');
157
+ // The finding names the first canonical sentence that is missing, so the
158
+ // repair knows exactly which words to restore.
159
+ assert.match(f[0].detail, /An ordinary `npm install` is the whole setup/);
160
+ });
161
+
162
+ it('rejects reordered sentences even with the wording intact', () => {
163
+ const reordered = [
164
+ CANONICAL_SENTENCES[1],
165
+ CANONICAL_SENTENCES[0],
166
+ CANONICAL_SENTENCES[3],
167
+ CANONICAL_SENTENCES[2]
168
+ ].join(' ');
169
+ const f = readmeFindings('demo', 'demo/README.md', reordered);
170
+ assert.equal(f.length, 1);
171
+ assert.equal(f[0].kind, 'ldt section drift');
172
+ });
173
+
174
+ it('accepts app-specific sentences interleaved between canonical ones', () => {
175
+ const interleaved = [
176
+ 'Intro of the app\u2019s own.',
177
+ CANONICAL_SENTENCES[0],
178
+ 'A middle sentence of the app\u2019s own.',
179
+ CANONICAL_SENTENCES[1],
180
+ CANONICAL_SENTENCES[2],
181
+ 'Another sentence of the app\u2019s own.',
182
+ CANONICAL_SENTENCES[3]
183
+ ].join(' ');
184
+ assert.deepEqual(readmeFindings('demo', 'demo/README.md', interleaved), []);
185
+ });
186
+
187
+ it('accepts prose after the block that reuses section vocabulary', () => {
188
+ const after = `${section(72)}
189
+
190
+ The setup above has no linking step and nothing to re-run. The app also
191
+ ships a \`dev:ds\` script for design-system iteration; the workflow it uses
192
+ lives in the dev-tools README.
193
+ `;
194
+ assert.deepEqual(readmeFindings('demo', 'demo/README.md', after), []);
195
+ });
196
+
197
+ it('reports a missing section plainly when the README never mentions dev-tools', () => {
198
+ const f = readmeFindings('demo', 'demo/README.md', '# Demo\n\nJust an app.\n');
199
+ assert.equal(f.length, 1);
200
+ assert.equal(f[0].kind, 'ldt section missing');
201
+ assert.match(f[0].detail, /no sibling-source section/);
202
+ });
203
+
204
+ it('reports drift, not missing, when dev-tools is named but the prose diverges', () => {
205
+ const f = readmeFindings('demo', 'demo/README.md', DRIFTED_ONLY);
206
+ assert.equal(f.length, 1);
207
+ assert.equal(f[0].kind, 'ldt section drift');
208
+ });
209
+
210
+ it('treats an absent README as a missing section', () => {
211
+ const f = readmeFindings('demo', 'demo/README.md', '');
212
+ assert.equal(f.length, 1);
213
+ assert.equal(f[0].kind, 'ldt section missing');
214
+ });
215
+ });
216
+
217
+ describe('stale link-era instructions', () => {
218
+ it('flags the retired patterns wherever prose carries them', () => {
219
+ const hits = staleInstructionHits(
220
+ 'Run `npm run ldt` or `npm link @widgetic/dev-tools`; `volta run npm i` works too. ' +
221
+ 'Use `llinks` to verify; the entry must be re-run after installs, ' +
222
+ 'and the old `typescript-sdk` name is dead.'
223
+ );
224
+ assert.deepEqual(hits, [
225
+ '`npm run ldt`',
226
+ 'the retired `typescript-sdk` package name',
227
+ '`npm link`',
228
+ '`volta run`',
229
+ 'the `llinks` verify script',
230
+ 'the after-install re-run instruction'
231
+ ]);
232
+ });
233
+
234
+ it('narrows to the patterns retired for every package when told the tier', () => {
235
+ // The link-era mechanics are a linking package's live setup, so only the
236
+ // lore that is dead everywhere survives the narrowing.
237
+ const mechanics = 'npm link, volta run, llinks, must be re-run';
238
+ assert.deepEqual(staleInstructionHits(mechanics, 'linking'), []);
239
+ assert.equal(staleInstructionHits(mechanics).length, 4);
240
+ assert.deepEqual(staleInstructionHits('npm run ldt and typescript-sdk', 'linking'), [
241
+ '`npm run ldt`',
242
+ 'the retired `typescript-sdk` package name'
243
+ ]);
244
+ });
245
+
246
+ it('does not flag `pnpm link` inside the npm-link pattern', () => {
247
+ assert.deepEqual(
248
+ staleInstructionHits('Other projects use `pnpm link --global @widgetic/file-browser`.'),
249
+ []
250
+ );
251
+ });
252
+
253
+ it('does not flag prose that merely describes the era in passing', () => {
254
+ assert.deepEqual(
255
+ staleInstructionHits('The retired practice was a symlink recreated by hand after installs.'),
256
+ []
257
+ );
258
+ });
259
+
260
+ it('scans outside fenced blocks only', () => {
261
+ const withFence = `${section(72)}
262
+
263
+ \`\`\`sh
264
+ # historical: npm run ldt after every install
265
+ npm run llinks
266
+ \`\`\`
267
+ `;
268
+ assert.deepEqual(readmeFindings('demo', 'demo/README.md', withFence), []);
269
+ });
270
+ });
271
+
272
+ describe('the publish contract', () => {
273
+ it('publishes to exactly the packages that ship a dist tarball', { skip: !DISK_OK }, () => {
274
+ assert.deepEqual(PUBLISH_PACKAGES, ['chat', 'file-browser']);
275
+ assert.ok(PUBLISH_PACKAGES.every((p) => ADOPTER_PACKAGES.includes(p)));
276
+ // Every publisher ships `files: ['dist']` — the sentence that calls
277
+ // dist the tarball's only content must match manifest reality.
278
+ for (const pkg of PUBLISH_PACKAGES) {
279
+ const manifest = JSON.parse(
280
+ readFileSync(join(FRONTEND, pkg, 'package.json'), 'utf8')
281
+ );
282
+ assert.deepEqual(manifest.files, ['dist']);
283
+ }
284
+ });
285
+
286
+ it('accepts a publisher whose README carries the publish sentences plus its own flow notes', () => {
287
+ const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${publishSection()}\n`);
288
+ assert.deepEqual(f, []);
289
+ });
290
+
291
+ it('accepts fenced publish commands without scanning them', () => {
292
+ const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${publishSection()}\n\n\`\`\`sh\nnpm publish\n\`\`\`\n`);
293
+ assert.deepEqual(f, []);
294
+ });
295
+
296
+ it('reports a missing publish section on a publisher without one', () => {
297
+ const f = readmeFindings('chat', 'chat/README.md', CLEAN);
298
+ assert.deepEqual(f.map((x) => x.kind), ['publish section missing']);
299
+ });
300
+
301
+ it('reports drift when the publish prose is reworded, naming the first gap', () => {
302
+ const reworded = publishSection().replace('land as one commit', 'are committed together');
303
+ const f = readmeFindings('chat', 'chat/README.md', `${CLEAN}\n${reworded}`);
304
+ assert.equal(f.length, 1);
305
+ assert.equal(f[0].kind, 'publish section drift');
306
+ assert.match(f[0].detail, /land as one commit/);
307
+ });
308
+
309
+ it('reports a missing publish section too when the README is absent', () => {
310
+ const f = readmeFindings('chat', 'chat/README.md', '');
311
+ assert.deepEqual(f.map((x) => x.kind), ['ldt section missing', 'publish section missing']);
312
+ });
313
+
314
+ it('requires nothing extra from packages that do not publish', () => {
315
+ const f = readmeFindings('editor', 'editor/README.md', CLEAN);
316
+ assert.deepEqual(f, []);
317
+ });
318
+ });
319
+
320
+ describe('the checkout collector', () => {
321
+ it('accepts a checkout where every subject carries its sections', () => {
322
+ const root = checkout({
323
+ ...Object.fromEntries(
324
+ ADOPTER_PACKAGES.map((p) => [
325
+ p,
326
+ PUBLISH_PACKAGES.includes(p) ? `${CLEAN}\n\n${publishSection()}` : CLEAN
327
+ ])
328
+ ),
329
+ ...Object.fromEntries(LINKING_PACKAGES.map((p) => [p, linkingSection(72)]))
330
+ });
331
+ assert.deepEqual(collectReadmeDrift(root), {
332
+ packages: [...CHECKED_PACKAGES],
333
+ findings: []
334
+ });
335
+ });
336
+
337
+ it('fails the checkout where one adopter drifted and one is missing', () => {
338
+ const root = checkout({
339
+ site: DRIFTED_ONLY,
340
+ editor: CLEAN,
341
+ 'widget-creator': '# Just an app.\n'
342
+ });
343
+ const f = collectReadmeDrift(root, {
344
+ packages: ['site', 'editor', 'widget-creator']
345
+ }).findings;
346
+ assert.deepEqual(
347
+ f.map((x) => [x.pkg, x.kind]),
348
+ [
349
+ ['site', 'ldt section drift'],
350
+ ['widget-creator', 'ldt section missing']
351
+ ]
352
+ );
353
+ });
354
+
355
+ it('checks every default subject, including ones with no README', () => {
356
+ const root = checkout({ site: CLEAN });
357
+ const f = findingsFor(root);
358
+ // Five adopters missing the sibling section, the two publishers missing
359
+ // the publish section on top of it, and the three linking packages
360
+ // missing their own section — an absent README is a missing section in
361
+ // whichever tier asked for it, so no subject can pass vacuously.
362
+ assert.equal(
363
+ f.length,
364
+ ADOPTER_PACKAGES.length - 1 + PUBLISH_PACKAGES.length + LINKING_PACKAGES.length
365
+ );
366
+ assert.ok(
367
+ f.every((x) =>
368
+ [
369
+ 'ldt section missing',
370
+ 'publish section missing',
371
+ 'linked-sibling section missing'
372
+ ].includes(x.kind)
373
+ )
374
+ );
375
+ });
376
+
377
+ it('honors an explicit package list', () => {
378
+ const root = checkout({ site: CLEAN, editor: DRIFTED_ONLY });
379
+ const { findings } = collectReadmeDrift(root, { packages: ['site'] });
380
+ assert.deepEqual(findings, []);
381
+ });
382
+
383
+ it('refuses the retired `adopters` option name instead of checking the defaults', () => {
384
+ const root = checkout({ site: CLEAN });
385
+ assert.throws(
386
+ () => collectReadmeDrift(root, { adopters: ['site'] }),
387
+ /renamed to `packages`/
388
+ );
389
+ });
390
+ });
391
+
392
+ describe('the linking tier', () => {
393
+ it('reads the three hand-linking packages by default', () => {
394
+ assert.deepEqual(LINKING_PACKAGES, ['embed-sdk', 'recorder', 'ui-sdk']);
395
+ // Every linking package is a subject, and none of them is an adopter:
396
+ // the canonical sentences would be false in their READMEs.
397
+ assert.ok(LINKING_PACKAGES.every((p) => CHECKED_PACKAGES.includes(p)));
398
+ assert.ok(LINKING_PACKAGES.every((p) => !ADOPTER_PACKAGES.includes(p)));
399
+ // Every linking subject with no section is a finding, not a pass: this is
400
+ // the state all three READMEs were in while the ban was the whole
401
+ // contract — the check was green and nobody reading them learned how the
402
+ // sibling arrives.
403
+ for (const pkg of LINKING_PACKAGES) {
404
+ assert.deepEqual(
405
+ findingsFor(checkout({ [pkg]: PLAIN }), { pkg }).map((f) => f.kind),
406
+ ['linked-sibling section missing']
407
+ );
408
+ }
409
+ });
410
+
411
+ it('accepts the canonical linked-sibling section wrapped to any line width', () => {
412
+ for (const wrap of [40, 60, 72, 88, 200]) {
413
+ assert.deepEqual(
414
+ readmeFindings('embed-sdk', 'embed-sdk/README.md', linkingSection(wrap)),
415
+ [],
416
+ `wrap ${wrap} should pass`
417
+ );
418
+ }
419
+ });
420
+
421
+ it('reports drift, not missing, when the prose raises the link but forks the wording', () => {
422
+ // Reworded on the unwrapped join: at a wrap width the phrase can straddle
423
+ // a line break, and the replacement would silently match nothing.
424
+ const forked = CANONICAL_LINKING_SENTENCES.join(' ').replace(
425
+ 'not its source',
426
+ 'rather than its source'
427
+ );
428
+ const f = readmeFindings('recorder', 'recorder/README.md', forked);
429
+ assert.equal(f.length, 1);
430
+ assert.equal(f[0].kind, 'linked-sibling section drift');
431
+ // The finding names the first canonical sentence that is missing, so the
432
+ // repair knows exactly which words to restore.
433
+ assert.match(f[0].detail, /its built output, not its source/);
434
+ });
435
+
436
+ it('accepts app-specific sentences and commands around the canonical ones', () => {
437
+ const withNotes =
438
+ '## Sibling packages\n\n' +
439
+ `${CANONICAL_LINKING_SENTENCES[0]}\n\n` +
440
+ 'Here that script is `npm run lps`, which links both siblings at once.\n\n' +
441
+ `${CANONICAL_LINKING_SENTENCES.slice(1).join(' ')}\n\n` +
442
+ '```sh\nnpm run i\nnpm run lps\n```\n';
443
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', withNotes), []);
444
+ });
445
+
446
+ it('fails a linking README whose only mention of the sibling is not the section', () => {
447
+ const root = checkout({
448
+ 'embed-sdk': '# Widgetic Embed SDK\n\nInstall the sibling: `npm link @widgetic/api-sdk`.\n'
449
+ });
450
+ const f = findingsFor(root, { pkg: 'embed-sdk' });
451
+ assert.equal(f.length, 1);
452
+ assert.equal(f[0].kind, 'linked-sibling section drift');
453
+ assert.match(f[0].detail, /does not carry the canonical prose/);
454
+ assert.match(f[0].fix, /canonical linked-sibling section/);
455
+ });
456
+
457
+ it('allows the link-era mechanics that are these packages live setup', () => {
458
+ // recorder's lps script is `volta run npm link` and its llinks script
459
+ // reports what node_modules/@widgetic resolves to — prose describing that
460
+ // is the truth about the package, so the ban stops at the tier boundary.
461
+ const raw =
462
+ `${linkingSection(72)}\n\n` +
463
+ '`npm run lps` links both siblings through `volta run` with the pinned\n' +
464
+ 'toolchain, and `npm run llinks` reports what `node_modules/@widgetic`\n' +
465
+ 'resolves to.\n';
466
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', raw), []);
467
+ });
468
+
469
+ it('flags the instructions that are dead for every package, wherever they appear', () => {
470
+ const root = checkout({
471
+ 'ui-sdk':
472
+ '# Widgetic UI SDK\n\nRun `npm run ldt` to link, and the old `typescript-sdk`\n' +
473
+ 'name is gone.\n' +
474
+ linkingSection(72)
475
+ });
476
+ const f = findingsFor(root, { pkg: 'ui-sdk' });
477
+ assert.equal(f.length, 1);
478
+ assert.equal(f[0].kind, 'linked-sibling section drift');
479
+ assert.match(f[0].detail, /`npm run ldt`/);
480
+ assert.match(f[0].detail, /the retired `typescript-sdk` package name/);
481
+ });
482
+
483
+ it('requires its own sentences — and only its own — from a linking package', () => {
484
+ // Same prose, two tiers: the linked-sibling section completes a linking
485
+ // package, while an adopter carrying that text has drifted from its own.
486
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', linkingSection(72)), []);
487
+ const adopter = readmeFindings('site', 'site/README.md', linkingSection(72));
488
+ assert.deepEqual(adopter.map((x) => x.kind), ['ldt section drift']);
489
+ // The reverse: an adopter's section satisfies a linking package nowhere,
490
+ // because it never states how the sibling arrives.
491
+ const linking = readmeFindings('recorder', 'recorder/README.md', section(72));
492
+ assert.deepEqual(linking.map((x) => x.kind), ['linked-sibling section drift']);
493
+ });
494
+
495
+ it('does not require the publish sentences from a linking package either', () => {
496
+ // The publish tier is about the two packages that ship a dist tarball;
497
+ // a linking package is never asked for those sentences.
498
+ assert.deepEqual(
499
+ readmeFindings('ui-sdk', 'ui-sdk/README.md', `${linkingSection(72)}\nPublishing notes.\n`),
500
+ []
501
+ );
502
+ });
503
+
504
+ it('exempts fenced examples, exactly as the adopter tier does', () => {
505
+ const fenced = `${linkingSection(72)}\n\`\`\`sh\n# historical: npm run ldt after every install\n\`\`\`\n`;
506
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', fenced), []);
507
+ });
508
+
509
+ it('flags the same words when prose carries them rather than a fence', () => {
510
+ // The counterpart of the fence test: outside a fence, the words fail —
511
+ // with the globally-dead lore, which is what the fence above quotes.
512
+ const proseForm = `${linkingSection(72)}\nHistorical note: npm run ldt was how it used to work.\n`;
513
+ const f = readmeFindings('recorder', 'recorder/README.md', proseForm);
514
+ assert.equal(f.length, 1);
515
+ assert.equal(f[0].kind, 'linked-sibling section drift');
516
+ });
517
+ });
518
+
519
+ describe('the real Frontend checkout', { skip: !DISK_OK }, () => {
520
+ it('is clean — every adopter carries the canonical sections, in the canonical wording', () => {
521
+ const { findings } = collectReadmeDrift(FRONTEND);
522
+ assert.deepEqual(
523
+ findings,
524
+ [],
525
+ `READMEs drifted from the contract:\n${findings
526
+ .map((x) => ` ${x.pkg}: ${x.detail}`)
527
+ .join('\n')}`
528
+ );
529
+ });
530
+
531
+ it('reads both tiers off the disk, so a real README cannot go unchecked', () => {
532
+ const { packages } = collectReadmeDrift(FRONTEND);
533
+ assert.deepEqual(packages, CHECKED_PACKAGES);
534
+ // A subject whose file vanished would pass a prose scan vacuously, so
535
+ // this asserts the three linking READMEs are really there to be read.
536
+ for (const pkg of LINKING_PACKAGES) {
537
+ assert.ok(
538
+ existsSync(join(FRONTEND, pkg, 'README.md')),
539
+ `${pkg}/README.md is a contract subject and must exist`
540
+ );
541
+ }
542
+ });
543
+ });