@widgetic/dev-tools 0.3.0 → 0.3.2
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 +42 -8
- package/README.md +63 -9
- package/bin/check-readme-contracts.mjs +12 -7
- package/lib/frontend-layout.mjs +10 -1
- package/lib/readme-contract.d.mts +47 -16
- package/lib/readme-contract.mjs +116 -38
- package/package.json +1 -1
- package/test/frontend-layout.test.mjs +6 -0
- package/test/readme-contract.test.mjs +136 -52
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,27 @@
|
|
|
3
3
|
The format roughly follows [Keep a Changelog](https://keepachangelog.com/); the
|
|
4
4
|
reasons matter more than the categories.
|
|
5
5
|
|
|
6
|
+
## 0.3.1 — 2026-10-08
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
- **The `i18n` and `rtl` subpaths of `@widgetic/design-system` in the sibling
|
|
11
|
+
alias table** (`SIBLING_PACKAGES['design-system'].subpaths`). `i18n` is the
|
|
12
|
+
words kit (the translator and `createI18n` that every package reads its
|
|
13
|
+
sentences through, with the test-only `i18n/audit` below it) and `rtl` is the
|
|
14
|
+
right to left kit (the source audit, `rtl/audit`, that the tests of every
|
|
15
|
+
package read their source through). An alias is a prefix match and the first
|
|
16
|
+
one that matches wins, so without an entry of its own the bare
|
|
17
|
+
`@widgetic/design-system` alias turned `@widgetic/design-system/i18n/audit`
|
|
18
|
+
into `<lib>/index.ts/i18n/audit`, which is nothing: a dev server or a test run
|
|
19
|
+
of a package that reads either kit could not resolve it. The layout test pins
|
|
20
|
+
both entries, and its disk-truth gate already fails if either points at a
|
|
21
|
+
directory that is not in the checkout.
|
|
22
|
+
- Consumers that cannot wait for this release (`widget-creator` carries the same
|
|
23
|
+
two entries in its own `vite.config.ts`, in front of the table, and drops them
|
|
24
|
+
on its own once the installed dev-tools has them) lose nothing by taking it
|
|
25
|
+
later.
|
|
26
|
+
|
|
6
27
|
## 0.3.0 — 2026-09-22
|
|
7
28
|
|
|
8
29
|
### Added
|
|
@@ -33,16 +54,29 @@ reasons matter more than the categories.
|
|
|
33
54
|
|
|
34
55
|
### Changed
|
|
35
56
|
|
|
36
|
-
- **`check-readme-contracts`
|
|
57
|
+
- **`check-readme-contracts` now requires a section from all nine READMEs, and
|
|
58
|
+
reads the three hand-linking ones as their own tier.** `embed-sdk`,
|
|
37
59
|
`recorder` and `ui-sdk` consume a sibling through a hand-made link to its
|
|
38
60
|
built output rather than the dev-alias workflow, so the canonical
|
|
39
|
-
sibling-source sentences would be false in their READMEs
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
61
|
+
sibling-source sentences would be false in their READMEs. They carry a
|
|
62
|
+
canonical **linked-sibling** section instead (`CANONICAL_LINKING_SENTENCES`):
|
|
63
|
+
what the link resolves, why a sibling edit stays invisible until that package
|
|
64
|
+
rebuilds its `dist/`, and that the package's own install script is both the
|
|
65
|
+
setup and the repair path. The ban alone was never documentation: it kept
|
|
66
|
+
wrong instructions out without requiring the right ones, so three READMEs
|
|
67
|
+
that said nothing about the link they depend on passed it silently, having
|
|
68
|
+
been read by nothing at all before it. Requiring the section
|
|
69
|
+
also forced the ban to admit tiers: `npm link`, `volta run`, `llinks` and the
|
|
70
|
+
after-install re-run are *live* in those packages (`recorder`'s `lps` runs
|
|
71
|
+
`volta run npm link`, its `llinks` script reports what
|
|
72
|
+
`node_modules/@widgetic` resolves to), so banning them there would ban the
|
|
73
|
+
truth; `npm run ldt` and the retired `typescript-sdk` name stay banned in both
|
|
74
|
+
tiers because they are dead for everyone. New findings:
|
|
75
|
+
`linked-sibling section missing` and `linked-sibling section drift`. The
|
|
76
|
+
fixture suite drives both tiers (a linking README with no section fails, the
|
|
77
|
+
canonical section passes at any wrap width, a reworded one drifts, a fenced
|
|
78
|
+
command stays exempt, and `npm link` still fails in an adopter's prose), and
|
|
79
|
+
the real checkout test asserts every subject is read off the disk so none can
|
|
46
80
|
pass vacuously. `collectReadmeDrift`'s option is now `packages`; the old
|
|
47
81
|
`adopters` name throws rather than silently falling back to the defaults.
|
|
48
82
|
|
package/README.md
CHANGED
|
@@ -174,15 +174,22 @@ tarball, publish, and have every consumer refresh its lockfile in the same
|
|
|
174
174
|
commit as its version bump. Run it as `npm run check:readme` here, or
|
|
175
175
|
`npx check-readme-contracts` anywhere the package is installed.
|
|
176
176
|
|
|
177
|
-
Three packages consume a sibling
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
the
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
177
|
+
Three packages consume a sibling the other way round: `embed-sdk`, `recorder`
|
|
178
|
+
and `ui-sdk` link a sibling checkout by hand to its built output instead —
|
|
179
|
+
`lps`, `lapisdk`, a raw `ln -s`. The sibling-source sentences would be false in
|
|
180
|
+
their READMEs, so they carry [their own canonical sentences](lib/readme-contract.mjs)
|
|
181
|
+
— the link, what it resolves, and why a sibling edit needs a rebuild to show up
|
|
182
|
+
— and [Linked siblings](#linked-siblings-consuming-built-output-not-source)
|
|
183
|
+
below is the section they copy. The retired-instruction ban reaches them one
|
|
184
|
+
tier narrower: `npm link`, `volta run`, `llinks` and the after-install re-run
|
|
185
|
+
are those packages' *live* setup — `recorder`'s `lps` runs `volta run npm link`,
|
|
186
|
+
and its `llinks` script reports what `node_modules/@widgetic` resolves to — so
|
|
187
|
+
that half of the ban would be banning the truth about them. What stays banned
|
|
188
|
+
in either tier is the lore that is dead everywhere: the `ldt` step, which these
|
|
189
|
+
packages never adopted, and the retired `typescript-sdk` name. All of it is
|
|
190
|
+
data in `LINKING_PACKAGES` and `STALE_PATTERNS` in
|
|
191
|
+
`lib/readme-contract.mjs`. They were read by nothing before this check — not
|
|
192
|
+
the adopters' check, not a test — so drift there failed nothing at all.
|
|
186
193
|
|
|
187
194
|
Two things keep the link era's failure mode visible, because **nothing
|
|
188
195
|
fails** when sibling-source development quietly stops working: the dynamic
|
|
@@ -200,6 +207,53 @@ hook, and site's `lps` exists for the same purpose for its embedded
|
|
|
200
207
|
`file-browser`. Those are per-app choices about which sibling to iterate on;
|
|
201
208
|
they are not part of dev-tools setup, and no step here depends on them.
|
|
202
209
|
|
|
210
|
+
### Linked siblings: consuming built output, not source
|
|
211
|
+
|
|
212
|
+
`embed-sdk`, `recorder` and `ui-sdk` consume a sibling the other way round:
|
|
213
|
+
they link a sibling checkout into `node_modules` by hand — from a script the
|
|
214
|
+
package owns — and import what that checkout **builds**, so a sibling edit is
|
|
215
|
+
invisible here until that package rebuilds its `dist/`. The mechanism is
|
|
216
|
+
theirs and the scripts differ (`lapisdk`, `lps`, a raw `ln -s`), so the
|
|
217
|
+
canonical sentences stay command-neutral and each README names its own scripts
|
|
218
|
+
around them. These are the four sentences, in this order; the same text is
|
|
219
|
+
data in [`lib/readme-contract.mjs`](lib/readme-contract.mjs), which is what the
|
|
220
|
+
check matches:
|
|
221
|
+
|
|
222
|
+
This package consumes sibling `@widgetic/*` checkouts through a link in
|
|
223
|
+
`node_modules` that resolves the checkout itself — its built output, not its
|
|
224
|
+
source. The link is made by hand rather than through the `@widgetic/dev-tools`
|
|
225
|
+
dev-alias setup the adopting apps use, so a sibling edit stays invisible here
|
|
226
|
+
until that package rebuilds its `dist/`. Setup is the install script this
|
|
227
|
+
package ships: it reinstalls and then links the sibling, so `node_modules`
|
|
228
|
+
keeps resolving the checkout rather than the published package. The dev-alias
|
|
229
|
+
workflow these packages have not adopted, and the reasons the adopting apps use
|
|
230
|
+
it, are described in [the dev-tools README](../dev-tools/README.md).
|
|
231
|
+
|
|
232
|
+
App-specific sentences may sit between the canonical ones — what the package's
|
|
233
|
+
own scripts are called, which sibling it links, what has to be rebuilt first.
|
|
234
|
+
Commands belong in a fenced block, where the check does not read them: say what
|
|
235
|
+
the script does in prose, show what to run in the fence.
|
|
236
|
+
|
|
237
|
+
```md
|
|
238
|
+
## Sibling packages
|
|
239
|
+
|
|
240
|
+
<the four canonical sentences, wrapped to this README's width>
|
|
241
|
+
|
|
242
|
+
`npm run i` is the whole setup here: it reinstalls `node_modules` and then
|
|
243
|
+
runs this package's link step.
|
|
244
|
+
|
|
245
|
+
\`\`\`sh
|
|
246
|
+
npm run i # install, then link the sibling checkout
|
|
247
|
+
npm run lapisdk # re-link only, after a fresh node_modules
|
|
248
|
+
\`\`\`
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
The `../dev-tools/README.md` link is relative to a `Frontend/` app, which is
|
|
252
|
+
where all three packages sit. `check-readme-contracts` reports
|
|
253
|
+
`linked-sibling section missing` when a README never raises the relationship at
|
|
254
|
+
all and `linked-sibling section drift` when it does but the wording has
|
|
255
|
+
forked — the same two shapes the adopter tier reports.
|
|
256
|
+
|
|
203
257
|
### The link doctor: checking sibling links, dists, and dead names
|
|
204
258
|
|
|
205
259
|
`check-links` is the automated form of the eyeballing this section used to
|
|
@@ -13,9 +13,13 @@
|
|
|
13
13
|
*
|
|
14
14
|
* Three more packages consume a sibling through a hand-made link to its built
|
|
15
15
|
* output — `embed-sdk`, `recorder`, `ui-sdk` — and were read by nothing at
|
|
16
|
-
* all, so
|
|
17
|
-
*
|
|
18
|
-
* sibling
|
|
16
|
+
* all, so drift in one of their READMEs failed nothing. They compile no
|
|
17
|
+
* sibling source, so the sibling-source sentences would be false in them; they
|
|
18
|
+
* carry the canonical linked-sibling sentences instead, which state what the
|
|
19
|
+
* link resolves and what that costs. The retired-instruction ban reaches them
|
|
20
|
+
* one tier narrower: the link-era mechanics it names are those packages' live
|
|
21
|
+
* setup, so only the patterns retired for every package (`npm run ldt`, the
|
|
22
|
+
* retired `typescript-sdk` name) are scanned for in their prose.
|
|
19
23
|
*
|
|
20
24
|
* This check reads each package's README and fails when the canonical
|
|
21
25
|
* sibling-source sentences are missing, rewritten, or reordered, or when
|
|
@@ -57,12 +61,13 @@ if (packages.length === 0) {
|
|
|
57
61
|
console.log(
|
|
58
62
|
`[check-readme-contracts] ${packages.length} READMEs under Frontend/` +
|
|
59
63
|
` — ${ADOPTER_PACKAGES.length} adopters (canonical section required)` +
|
|
60
|
-
` + ${LINKING_PACKAGES.length} linking packages (
|
|
64
|
+
` + ${LINKING_PACKAGES.length} linking packages (linked-sibling section required)`
|
|
61
65
|
);
|
|
62
66
|
if (findings.length === 0) {
|
|
63
67
|
console.log(
|
|
64
|
-
' OK — every adopter carries the canonical sibling-source section
|
|
65
|
-
' and no README teaches the
|
|
68
|
+
' OK — every adopter carries the canonical sibling-source section and every linking package\n' +
|
|
69
|
+
' the canonical linked-sibling one, in the canonical wording, and no README teaches the\n' +
|
|
70
|
+
' instructions retired for its tier.\n'
|
|
66
71
|
);
|
|
67
72
|
process.exit(0);
|
|
68
73
|
}
|
|
@@ -72,6 +77,6 @@ for (const { kind, pkg, detail, fix } of findings) {
|
|
|
72
77
|
}
|
|
73
78
|
console.error(
|
|
74
79
|
`\n ${findings.length} drifted README${findings.length === 1 ? '' : 's'} across ` +
|
|
75
|
-
`${new Set(findings.map((f) => f.pkg)).size}
|
|
80
|
+
`${new Set(findings.map((f) => f.pkg)).size} package(s).\n`
|
|
76
81
|
);
|
|
77
82
|
process.exit(1);
|
package/lib/frontend-layout.mjs
CHANGED
|
@@ -67,7 +67,16 @@ export const SIBLING_PACKAGES = {
|
|
|
67
67
|
components: 'components',
|
|
68
68
|
icons: 'icons',
|
|
69
69
|
stores: 'stores',
|
|
70
|
-
fonts: 'fonts'
|
|
70
|
+
fonts: 'fonts',
|
|
71
|
+
// The words kit every package reads its sentences through. The alias
|
|
72
|
+
// is a prefix match, so the test-only `@widgetic/design-system/i18n/audit`
|
|
73
|
+
// resolves through this one entry. Without it the bare-index alias
|
|
74
|
+
// below swallows `@widgetic/design-system/i18n` and turns it into
|
|
75
|
+
// `<lib>/index.ts/i18n`, which is nothing.
|
|
76
|
+
i18n: 'i18n',
|
|
77
|
+
// The right to left kit: the source audit (`rtl/audit`) that the tests of every package read their
|
|
78
|
+
// source through. A prefix match as well, and for the same reason as `i18n` above.
|
|
79
|
+
rtl: 'rtl'
|
|
71
80
|
}
|
|
72
81
|
},
|
|
73
82
|
// `dir` was `props-editor` (see older configs — and dangling symlinks).
|
|
@@ -21,11 +21,21 @@ export const ADOPTER_PACKAGES: string[];
|
|
|
21
21
|
/** The packages whose READMEs must also carry the publish section. */
|
|
22
22
|
export const PUBLISH_PACKAGES: string[];
|
|
23
23
|
|
|
24
|
+
/**
|
|
25
|
+
* The canonical linked-sibling prose, for the packages in
|
|
26
|
+
* {@link LINKING_PACKAGES}. Same matching rules as the sibling sentences: an
|
|
27
|
+
* ordered-substring match, app-specific sentences allowed between them. The
|
|
28
|
+
* sentences stay command-neutral — the three packages link from different
|
|
29
|
+
* scripts — and each README names its own around them.
|
|
30
|
+
*/
|
|
31
|
+
export const CANONICAL_LINKING_SENTENCES: string[];
|
|
32
|
+
|
|
24
33
|
/**
|
|
25
34
|
* The packages that consume a sibling through a hand-made link to its built
|
|
26
|
-
* output instead of the dev-alias workflow. They
|
|
27
|
-
*
|
|
28
|
-
*
|
|
35
|
+
* output instead of the dev-alias workflow. They compile no sibling source, so
|
|
36
|
+
* they carry {@link CANONICAL_LINKING_SENTENCES} rather than the sibling-source
|
|
37
|
+
* sentences, and only the patterns retired for every tier are scanned for in
|
|
38
|
+
* their prose — the link-era mechanics are their live setup.
|
|
29
39
|
*/
|
|
30
40
|
export const LINKING_PACKAGES: string[];
|
|
31
41
|
|
|
@@ -38,17 +48,29 @@ export const CHECKED_PACKAGES: string[];
|
|
|
38
48
|
*/
|
|
39
49
|
export interface ReadmeFinding {
|
|
40
50
|
/**
|
|
41
|
-
* - `ldt section missing` —
|
|
42
|
-
* section at all (or no README).
|
|
43
|
-
* - `ldt section drift` —
|
|
44
|
-
* the canonical sentences, or link-era instructions are
|
|
45
|
-
*
|
|
51
|
+
* - `ldt section missing` — an adopter's README has no canonical
|
|
52
|
+
* sibling-source section at all (or no README).
|
|
53
|
+
* - `ldt section drift` — an adopter's section exists but its wording
|
|
54
|
+
* diverges from the canonical sentences, or link-era instructions are
|
|
55
|
+
* present in its prose.
|
|
56
|
+
* - `linked-sibling section missing` — a linking package's README never
|
|
57
|
+
* describes the hand-made link to its sibling checkout.
|
|
58
|
+
* - `linked-sibling section drift` — the README raises the link
|
|
59
|
+
* relationship but its wording diverges from
|
|
60
|
+
* {@link CANONICAL_LINKING_SENTENCES}, or instructions retired for every
|
|
61
|
+
* tier are present in its prose.
|
|
46
62
|
* - `publish section missing` — a publishing package's README has no
|
|
47
63
|
* canonical publish-preparation section.
|
|
48
64
|
* - `publish section drift` — the section exists but its wording diverges
|
|
49
65
|
* from {@link CANONICAL_PUBLISH_SENTENCES}.
|
|
50
66
|
*/
|
|
51
|
-
kind:
|
|
67
|
+
kind:
|
|
68
|
+
| 'ldt section missing'
|
|
69
|
+
| 'ldt section drift'
|
|
70
|
+
| 'linked-sibling section missing'
|
|
71
|
+
| 'linked-sibling section drift'
|
|
72
|
+
| 'publish section missing'
|
|
73
|
+
| 'publish section drift';
|
|
52
74
|
/** The package directory under `Frontend/` that owns the finding. */
|
|
53
75
|
pkg: string;
|
|
54
76
|
/** What is wrong, README-relative. */
|
|
@@ -61,14 +83,23 @@ export interface ReadmeFinding {
|
|
|
61
83
|
* The stale link-era instructions present in one README's prose (fenced code
|
|
62
84
|
* blocks excluded), as readable labels. Word-bounded, so `pnpm link` does not
|
|
63
85
|
* match the `npm link` pattern.
|
|
86
|
+
*
|
|
87
|
+
* The default `'adopter'` tier returns every retired pattern; `'linking'`
|
|
88
|
+
* returns only those retired for every package (`npm run ldt`, the
|
|
89
|
+
* `typescript-sdk` name), because the link-era mechanics describe a linking
|
|
90
|
+
* package's live setup rather than drift.
|
|
64
91
|
*/
|
|
65
|
-
export declare function staleInstructionHits(
|
|
92
|
+
export declare function staleInstructionHits(
|
|
93
|
+
text: string,
|
|
94
|
+
tier?: 'adopter' | 'linking'
|
|
95
|
+
): string[];
|
|
66
96
|
|
|
67
97
|
/**
|
|
68
98
|
* Find what one package's README violates, by tier: an adopter must carry the
|
|
69
|
-
* canonical sibling-source sentences (and a publisher the publish ones),
|
|
70
|
-
*
|
|
71
|
-
*
|
|
99
|
+
* canonical sibling-source sentences (and a publisher the publish ones), a
|
|
100
|
+
* linking package the canonical linked-sibling ones, and every tier keeps the
|
|
101
|
+
* instructions retired for it out of its prose. An absent README yields the
|
|
102
|
+
* missing-section finding for whichever section that package's tier requires.
|
|
72
103
|
*/
|
|
73
104
|
export declare function readmeFindings(
|
|
74
105
|
pkg: string,
|
|
@@ -89,9 +120,9 @@ export interface CollectReadmeDriftOptions {
|
|
|
89
120
|
|
|
90
121
|
/**
|
|
91
122
|
* Collect every README finding under a Frontend checkout: each adopter's
|
|
92
|
-
* README must carry the canonical sibling-source sentences, in order,
|
|
93
|
-
*
|
|
94
|
-
* instructions in prose.
|
|
123
|
+
* README must carry the canonical sibling-source sentences, in order, each
|
|
124
|
+
* linking package's the canonical linked-sibling ones, and no README may teach
|
|
125
|
+
* the instructions retired for its tier in prose.
|
|
95
126
|
*/
|
|
96
127
|
export declare function collectReadmeDrift(
|
|
97
128
|
frontendRoot: string,
|
package/lib/readme-contract.mjs
CHANGED
|
@@ -10,14 +10,16 @@
|
|
|
10
10
|
* carry the canonical sibling-source sentences verbatim. The publish tier
|
|
11
11
|
* ({@link PUBLISH_PACKAGES}) adds the publish-preparation sentences.
|
|
12
12
|
* - **Linking packages** ({@link LINKING_PACKAGES}) consume a sibling through
|
|
13
|
-
* a hand-made link to its built output instead — `lps`, `
|
|
14
|
-
* `ln -s`. They
|
|
15
|
-
* would be false in their READMEs
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
13
|
+
* a hand-made link to its built output instead — `lps`, `lapisdk`, a raw
|
|
14
|
+
* `ln -s`. They compile no sibling source, so the sibling-source sentences
|
|
15
|
+
* would be false in their READMEs; they carry
|
|
16
|
+
* {@link CANONICAL_LINKING_SENTENCES} instead, which state what the link
|
|
17
|
+
* resolves to and what that costs. The retired-instruction ban reaches them
|
|
18
|
+
* through its global half only: the link-era mechanics are these packages'
|
|
19
|
+
* *live* setup — `recorder`'s `lps` runs `volta run npm link`, its `llinks`
|
|
20
|
+
* script reports what `node_modules/@widgetic` resolves to — so banning
|
|
21
|
+
* `npm link` in their prose would ban the truth about them. The ban's other
|
|
22
|
+
* half is the dev-alias story, and that is an adopter's story.
|
|
21
23
|
*
|
|
22
24
|
* The section earned its guard by drifting three different ways. It taught a
|
|
23
25
|
* hand-linking practice after the practice was retired (site's `lps` and
|
|
@@ -83,12 +85,33 @@ export const CANONICAL_PUBLISH_SENTENCES = [
|
|
|
83
85
|
/** The packages whose READMEs must carry the publish-preparation section. */
|
|
84
86
|
export const PUBLISH_PACKAGES = ['chat', 'file-browser'];
|
|
85
87
|
|
|
88
|
+
/**
|
|
89
|
+
* The canonical linked-sibling prose, for the packages in
|
|
90
|
+
* {@link LINKING_PACKAGES}. Same matching rules as the sibling sentences:
|
|
91
|
+
* ordered substrings over whitespace-collapsed prose, with app-specific
|
|
92
|
+
* sentences allowed between them.
|
|
93
|
+
*
|
|
94
|
+
* What the three share is the shape, not the command: `embed-sdk` links from
|
|
95
|
+
* its `lapisdk` script, `recorder` from `lps`, `ui-sdk` from a raw `ln -s`.
|
|
96
|
+
* These sentences therefore stay command-neutral — they say what the link
|
|
97
|
+
* resolves, why that is not the dev-alias workflow, and that the package's own
|
|
98
|
+
* install script is the setup and the repair path — and each README names its
|
|
99
|
+
* own scripts around them, in its own words and its own fenced block.
|
|
100
|
+
*/
|
|
101
|
+
export const CANONICAL_LINKING_SENTENCES = [
|
|
102
|
+
'This package consumes sibling `@widgetic/*` checkouts through a link in `node_modules` that resolves the checkout itself — its built output, not its source.',
|
|
103
|
+
'The link is made by hand rather than through the `@widgetic/dev-tools` dev-alias setup the adopting apps use, so a sibling edit stays invisible here until that package rebuilds its `dist/`.',
|
|
104
|
+
'Setup is the install script this package ships: it reinstalls and then links the sibling, so `node_modules` keeps resolving the checkout rather than the published package.',
|
|
105
|
+
'The dev-alias workflow these packages have not adopted, and the reasons the adopting apps use it, are described in [the dev-tools README](../dev-tools/README.md).'
|
|
106
|
+
];
|
|
107
|
+
|
|
86
108
|
/**
|
|
87
109
|
* The packages that consume a sibling checkout through a hand-made link to its
|
|
88
110
|
* built output rather than the dev-alias workflow — `embed-sdk` and `ui-sdk`
|
|
89
|
-
*
|
|
90
|
-
* They are exempt from the canonical
|
|
91
|
-
* sibling
|
|
111
|
+
* link `@widgetic/api-sdk` from a script, `recorder` links it and
|
|
112
|
+
* `@widgetic/design-system` from `lps`. They are exempt from the canonical
|
|
113
|
+
* sibling-source sentences (they compile no sibling source) and carry
|
|
114
|
+
* {@link CANONICAL_LINKING_SENTENCES} instead.
|
|
92
115
|
*/
|
|
93
116
|
export const LINKING_PACKAGES = ['embed-sdk', 'recorder', 'ui-sdk'];
|
|
94
117
|
|
|
@@ -97,17 +120,28 @@ export const CHECKED_PACKAGES = [...ADOPTER_PACKAGES, ...LINKING_PACKAGES];
|
|
|
97
120
|
|
|
98
121
|
/**
|
|
99
122
|
* Instructions from the link era that must never come back, word-bounded on
|
|
100
|
-
* both sides
|
|
101
|
-
* before the `npm`), so
|
|
102
|
-
*
|
|
123
|
+
* both sides and tagged with the tiers they are retired for. `npm link`
|
|
124
|
+
* cannot match inside `pnpm link` (the boundary fails before the `npm`), so
|
|
125
|
+
* file-browser's packaging prose — how *other* projects consume file-browser —
|
|
126
|
+
* stays out of scope, as it should be.
|
|
127
|
+
*
|
|
128
|
+
* `both` — dead for every package: the `ldt` step belongs to a workflow the
|
|
129
|
+
* linking packages never adopted, and `typescript-sdk` is a package that no
|
|
130
|
+
* longer exists. Neither is ever true, so neither may be taught anywhere.
|
|
131
|
+
*
|
|
132
|
+
* `adopter` — the link-era mechanics the dev-alias workflow replaced. Retired
|
|
133
|
+
* in an adopter's prose, where hand-made links are redundant and the advice to
|
|
134
|
+
* recreate one is the drift this contract was written for. Not retired in a
|
|
135
|
+
* linking package's: there the same words describe the setup that is actually
|
|
136
|
+
* running, so the ban stops at the tier boundary.
|
|
103
137
|
*/
|
|
104
138
|
const STALE_PATTERNS = [
|
|
105
|
-
{ pattern: /\bnpm run ldt\b/, label: '`npm run ldt`' },
|
|
106
|
-
{ pattern: /\
|
|
107
|
-
{ pattern: /\
|
|
108
|
-
{ pattern: /\
|
|
109
|
-
{ pattern: /\
|
|
110
|
-
{ pattern: /\
|
|
139
|
+
{ pattern: /\bnpm run ldt\b/, label: '`npm run ldt`', tiers: 'both' },
|
|
140
|
+
{ pattern: /\btypescript-sdk\b/, label: 'the retired `typescript-sdk` package name', tiers: 'both' },
|
|
141
|
+
{ pattern: /\bnpm link\b/, label: '`npm link`', tiers: 'adopter' },
|
|
142
|
+
{ pattern: /\bvolta run\b/, label: '`volta run`', tiers: 'adopter' },
|
|
143
|
+
{ pattern: /\bllinks\b/, label: 'the `llinks` verify script', tiers: 'adopter' },
|
|
144
|
+
{ pattern: /\bmust be re-run\b/, label: 'the after-install re-run instruction', tiers: 'adopter' }
|
|
111
145
|
];
|
|
112
146
|
|
|
113
147
|
/**
|
|
@@ -115,7 +149,7 @@ const STALE_PATTERNS = [
|
|
|
115
149
|
* link-doctor's problems, so reporters can treat the two checks alike.
|
|
116
150
|
*
|
|
117
151
|
* @typedef {object} ReadmeFinding
|
|
118
|
-
* @property {'ldt section missing' | 'ldt section drift' | 'publish section missing' | 'publish section drift'} kind
|
|
152
|
+
* @property {'ldt section missing' | 'ldt section drift' | 'linked-sibling section missing' | 'linked-sibling section drift' | 'publish section missing' | 'publish section drift'} kind
|
|
119
153
|
* @property {string} pkg The package directory under `Frontend/`.
|
|
120
154
|
* @property {string} detail What is wrong, README-relative.
|
|
121
155
|
* @property {string} fix The action that repairs it.
|
|
@@ -167,9 +201,21 @@ function firstMissingSentence(text, sentences) {
|
|
|
167
201
|
return null;
|
|
168
202
|
}
|
|
169
203
|
|
|
170
|
-
/**
|
|
171
|
-
|
|
172
|
-
|
|
204
|
+
/**
|
|
205
|
+
* The stale link-era instructions present in the text, as readable labels.
|
|
206
|
+
*
|
|
207
|
+
* The default `'adopter'` tier returns every retired pattern, which is what a
|
|
208
|
+
* caller scanning prose with no tier in hand (the CLI's docs, an audit) wants.
|
|
209
|
+
* `'linking'` narrows it to the patterns retired for everyone.
|
|
210
|
+
*
|
|
211
|
+
* @param {string} text Whitespace-collapsed prose.
|
|
212
|
+
* @param {'adopter' | 'linking'} [tier] Whose prose this is; defaults to `'adopter'`.
|
|
213
|
+
* @returns {string[]}
|
|
214
|
+
*/
|
|
215
|
+
export function staleInstructionHits(text, tier = 'adopter') {
|
|
216
|
+
return STALE_PATTERNS.filter(
|
|
217
|
+
({ pattern, tiers }) => (tiers === 'both' || tier === 'adopter') && pattern.test(text)
|
|
218
|
+
).map(({ label }) => label);
|
|
173
219
|
}
|
|
174
220
|
|
|
175
221
|
/**
|
|
@@ -181,14 +227,18 @@ export function staleInstructionHits(text) {
|
|
|
181
227
|
* @param {string} pkg The package's directory name under `Frontend/`.
|
|
182
228
|
* @param {string} text Whitespace-collapsed prose.
|
|
183
229
|
* @param {string} fix The action that repairs the drift.
|
|
230
|
+
* @param {'adopter' | 'linking'} tier Whose prose this is.
|
|
184
231
|
* @returns {ReadmeFinding[]}
|
|
185
232
|
*/
|
|
186
|
-
function staleFindings(pkg, text, fix) {
|
|
187
|
-
const stale = staleInstructionHits(text);
|
|
233
|
+
function staleFindings(pkg, text, fix, tier) {
|
|
234
|
+
const stale = staleInstructionHits(text, tier);
|
|
188
235
|
if (stale.length === 0) return [];
|
|
189
236
|
return [
|
|
190
237
|
{
|
|
191
|
-
|
|
238
|
+
// Both tiers report banned prose as drift on the section they require,
|
|
239
|
+
// so the finding names a section the README actually owes: `ldt` is an
|
|
240
|
+
// adopter's section, and a linking package owes the linked-sibling one.
|
|
241
|
+
kind: tier === 'linking' ? 'linked-sibling section drift' : 'ldt section drift',
|
|
192
242
|
pkg,
|
|
193
243
|
detail: `link-era instructions present in the README: ${stale.join(', ')}`,
|
|
194
244
|
fix
|
|
@@ -198,10 +248,11 @@ function staleFindings(pkg, text, fix) {
|
|
|
198
248
|
|
|
199
249
|
/**
|
|
200
250
|
* Find what one package's README violates, by tier: an adopter must carry the
|
|
201
|
-
* canonical sibling-source sentences (and a publisher the publish ones),
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* absent —
|
|
251
|
+
* canonical sibling-source sentences (and a publisher the publish ones), a
|
|
252
|
+
* linking package the canonical linked-sibling ones, and every tier keeps the
|
|
253
|
+
* instructions retired for it out of its prose. `readmePath` exists only for
|
|
254
|
+
* the error message when the file itself is absent — an absent README is a
|
|
255
|
+
* missing section in whichever tier asked for it.
|
|
205
256
|
*
|
|
206
257
|
* @param {string} pkg The package's directory name under `Frontend/`.
|
|
207
258
|
* @param {string} readmePath Where the README should be.
|
|
@@ -212,14 +263,40 @@ export function readmeFindings(pkg, readmePath, raw) {
|
|
|
212
263
|
const findings = [];
|
|
213
264
|
const text = prose(raw);
|
|
214
265
|
|
|
215
|
-
// A linking package carries
|
|
216
|
-
//
|
|
266
|
+
// A linking package carries its own canonical section: the hand-made link
|
|
267
|
+
// to a sibling's built output *is* its setup, and a README that never says
|
|
268
|
+
// so leaves the reader to infer the mechanism from `node_modules` — the
|
|
269
|
+
// same silence that let a `npm link` line be copied into it unnoticed.
|
|
217
270
|
if (LINKING_PACKAGES.includes(pkg)) {
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
271
|
+
const linkingGap = text
|
|
272
|
+
? firstMissingSentence(text, CANONICAL_LINKING_SENTENCES)
|
|
273
|
+
: CANONICAL_LINKING_SENTENCES[0];
|
|
274
|
+
if (linkingGap !== null) {
|
|
275
|
+
// Prose that already raises the link mechanism has a section that
|
|
276
|
+
// drifted; prose that never raises it has no section to drift — the
|
|
277
|
+
// same distinction the adopter tier draws. The signal is the
|
|
278
|
+
// mechanism itself (the link, the `node_modules` path, the workflow it
|
|
279
|
+
// is not), not the word "sibling", which any sentence can carry while
|
|
280
|
+
// saying nothing about how the sibling arrives.
|
|
281
|
+
const drifted = /\blink|\bnode_modules\b|dev-tools/i.test(text);
|
|
282
|
+
findings.push({
|
|
283
|
+
kind: drifted ? 'linked-sibling section drift' : 'linked-sibling section missing',
|
|
284
|
+
pkg,
|
|
285
|
+
detail: drifted
|
|
286
|
+
? `the linked-sibling section does not carry the canonical prose — first sentence missing or out of order: "${linkingGap}"`
|
|
287
|
+
: `no linked-sibling section was found in ${readmePath}`,
|
|
288
|
+
fix: 'copy the canonical linked-sibling section from dev-tools/README.md ("Linked siblings"); keep app-specific notes and commands outside its sentences'
|
|
289
|
+
});
|
|
290
|
+
}
|
|
291
|
+
findings.push(
|
|
292
|
+
...staleFindings(
|
|
293
|
+
pkg,
|
|
294
|
+
text,
|
|
295
|
+
'retire it: the `ldt` step and the retired `typescript-sdk` name are dead for this package too, whose live hand-made link its own section documents',
|
|
296
|
+
'linking'
|
|
297
|
+
)
|
|
222
298
|
);
|
|
299
|
+
return findings;
|
|
223
300
|
}
|
|
224
301
|
|
|
225
302
|
const canonicalGap = text ? firstMissingSentence(text, CANONICAL_SENTENCES) : CANONICAL_SENTENCES[0];
|
|
@@ -252,7 +329,8 @@ export function readmeFindings(pkg, readmePath, raw) {
|
|
|
252
329
|
...staleFindings(
|
|
253
330
|
pkg,
|
|
254
331
|
text,
|
|
255
|
-
'retire the link-era instructions; the workflow is an ordinary npm install (see dev-tools README, "The ldt workflow")'
|
|
332
|
+
'retire the link-era instructions; the workflow is an ordinary npm install (see dev-tools README, "The ldt workflow")',
|
|
333
|
+
'adopter'
|
|
256
334
|
)
|
|
257
335
|
);
|
|
258
336
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@widgetic/dev-tools",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails), the Vite sibling-$lib remap, the canonical Frontend sibling layout that builds every consumer's dev-alias tables, and check-links — the link-doctor that fails when a sibling symlink dangles, a promised dist/ file is missing, or a dead checkout name lingers, and check-design-system-peers — which fails when the two design-system peers' lockfiles drift apart.",
|
|
6
6
|
"repository": {
|
|
@@ -22,13 +22,19 @@ test('the design-system table expands to every subpath plus the index', () => {
|
|
|
22
22
|
'@widgetic/design-system',
|
|
23
23
|
'@widgetic/design-system/components',
|
|
24
24
|
'@widgetic/design-system/fonts',
|
|
25
|
+
'@widgetic/design-system/i18n',
|
|
25
26
|
'@widgetic/design-system/icons',
|
|
27
|
+
'@widgetic/design-system/rtl',
|
|
26
28
|
'@widgetic/design-system/shad-editor',
|
|
27
29
|
'@widgetic/design-system/stores',
|
|
28
30
|
'@widgetic/design-system/styles'
|
|
29
31
|
].sort()
|
|
30
32
|
);
|
|
31
33
|
assert.equal(aliases['@widgetic/design-system/icons'], `${FRONTEND}/design-system/src/lib/icons`);
|
|
34
|
+
// the words kit: a directory, and the test-only `i18n/audit` resolves under it as a prefix
|
|
35
|
+
assert.equal(aliases['@widgetic/design-system/i18n'], `${FRONTEND}/design-system/src/lib/i18n`);
|
|
36
|
+
// the right to left kit: a directory as well, and the test-only `rtl/audit` resolves under it as a prefix
|
|
37
|
+
assert.equal(aliases['@widgetic/design-system/rtl'], `${FRONTEND}/design-system/src/lib/rtl`);
|
|
32
38
|
// styles is a file, not a directory — the one entry that ever differed
|
|
33
39
|
assert.equal(
|
|
34
40
|
aliases['@widgetic/design-system/styles'],
|
|
@@ -43,6 +43,7 @@ import assert from 'node:assert/strict';
|
|
|
43
43
|
|
|
44
44
|
import {
|
|
45
45
|
ADOPTER_PACKAGES,
|
|
46
|
+
CANONICAL_LINKING_SENTENCES,
|
|
46
47
|
CANONICAL_PUBLISH_SENTENCES,
|
|
47
48
|
CANONICAL_SENTENCES,
|
|
48
49
|
CHECKED_PACKAGES,
|
|
@@ -81,9 +82,9 @@ function findingsFor(root, { kind, pkg } = {}) {
|
|
|
81
82
|
);
|
|
82
83
|
}
|
|
83
84
|
|
|
84
|
-
/**
|
|
85
|
-
function
|
|
86
|
-
const words =
|
|
85
|
+
/** One canonical sentence set, joined and wrapped to a line width. */
|
|
86
|
+
function wrapped(sentences, wrap) {
|
|
87
|
+
const words = sentences.join(' ').split(' ');
|
|
87
88
|
const lines = [];
|
|
88
89
|
let line = '';
|
|
89
90
|
for (const word of words) {
|
|
@@ -95,24 +96,22 @@ function section(wrap) {
|
|
|
95
96
|
}
|
|
96
97
|
}
|
|
97
98
|
if (line) lines.push(line);
|
|
98
|
-
return
|
|
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`;
|
|
99
110
|
}
|
|
100
111
|
|
|
101
112
|
/** The canonical publish-preparation prose, wrapped like an adopter's. */
|
|
102
113
|
function publishSection() {
|
|
103
|
-
|
|
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`;
|
|
114
|
+
return `## Publishing\n\n${wrapped(CANONICAL_PUBLISH_SENTENCES, 72)}\n`;
|
|
116
115
|
}
|
|
117
116
|
|
|
118
117
|
/** A README that names dev-tools but carries none of the canonical prose. */
|
|
@@ -224,10 +223,22 @@ describe('stale link-era instructions', () => {
|
|
|
224
223
|
);
|
|
225
224
|
assert.deepEqual(hits, [
|
|
226
225
|
'`npm run ldt`',
|
|
226
|
+
'the retired `typescript-sdk` package name',
|
|
227
227
|
'`npm link`',
|
|
228
228
|
'`volta run`',
|
|
229
229
|
'the `llinks` verify script',
|
|
230
|
-
'the after-install re-run instruction'
|
|
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`',
|
|
231
242
|
'the retired `typescript-sdk` package name'
|
|
232
243
|
]);
|
|
233
244
|
});
|
|
@@ -307,15 +318,16 @@ describe('the publish contract', () => {
|
|
|
307
318
|
});
|
|
308
319
|
|
|
309
320
|
describe('the checkout collector', () => {
|
|
310
|
-
it('accepts a checkout where every
|
|
311
|
-
const root = checkout(
|
|
312
|
-
Object.fromEntries(
|
|
321
|
+
it('accepts a checkout where every subject carries its sections', () => {
|
|
322
|
+
const root = checkout({
|
|
323
|
+
...Object.fromEntries(
|
|
313
324
|
ADOPTER_PACKAGES.map((p) => [
|
|
314
325
|
p,
|
|
315
326
|
PUBLISH_PACKAGES.includes(p) ? `${CLEAN}\n\n${publishSection()}` : CLEAN
|
|
316
327
|
])
|
|
317
|
-
)
|
|
318
|
-
|
|
328
|
+
),
|
|
329
|
+
...Object.fromEntries(LINKING_PACKAGES.map((p) => [p, linkingSection(72)]))
|
|
330
|
+
});
|
|
319
331
|
assert.deepEqual(collectReadmeDrift(root), {
|
|
320
332
|
packages: [...CHECKED_PACKAGES],
|
|
321
333
|
findings: []
|
|
@@ -343,11 +355,23 @@ describe('the checkout collector', () => {
|
|
|
343
355
|
it('checks every default subject, including ones with no README', () => {
|
|
344
356
|
const root = checkout({ site: CLEAN });
|
|
345
357
|
const f = findingsFor(root);
|
|
346
|
-
// Five adopters missing the sibling section,
|
|
347
|
-
//
|
|
348
|
-
//
|
|
349
|
-
|
|
350
|
-
assert.
|
|
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
|
+
);
|
|
351
375
|
});
|
|
352
376
|
|
|
353
377
|
it('honors an explicit package list', () => {
|
|
@@ -372,63 +396,123 @@ describe('the linking tier', () => {
|
|
|
372
396
|
// the canonical sentences would be false in their READMEs.
|
|
373
397
|
assert.ok(LINKING_PACKAGES.every((p) => CHECKED_PACKAGES.includes(p)));
|
|
374
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.
|
|
375
403
|
for (const pkg of LINKING_PACKAGES) {
|
|
376
|
-
assert.deepEqual(
|
|
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
|
+
);
|
|
377
418
|
}
|
|
378
419
|
});
|
|
379
420
|
|
|
380
|
-
it('
|
|
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', () => {
|
|
381
447
|
const root = checkout({
|
|
382
448
|
'embed-sdk': '# Widgetic Embed SDK\n\nInstall the sibling: `npm link @widgetic/api-sdk`.\n'
|
|
383
449
|
});
|
|
384
450
|
const f = findingsFor(root, { pkg: 'embed-sdk' });
|
|
385
451
|
assert.equal(f.length, 1);
|
|
386
|
-
assert.equal(f[0].kind, '
|
|
387
|
-
assert.match(f[0].detail, /
|
|
388
|
-
assert.match(f[0].
|
|
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/);
|
|
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/);
|
|
392
455
|
});
|
|
393
456
|
|
|
394
|
-
it('
|
|
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', () => {
|
|
395
470
|
const root = checkout({
|
|
396
471
|
'ui-sdk':
|
|
397
|
-
'# Widgetic UI SDK\n\nRun `npm run ldt` to link,
|
|
398
|
-
'
|
|
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)
|
|
399
475
|
});
|
|
400
476
|
const f = findingsFor(root, { pkg: 'ui-sdk' });
|
|
401
477
|
assert.equal(f.length, 1);
|
|
478
|
+
assert.equal(f[0].kind, 'linked-sibling section drift');
|
|
402
479
|
assert.match(f[0].detail, /`npm run ldt`/);
|
|
403
|
-
assert.match(f[0].detail, /the `
|
|
404
|
-
assert.match(f[0].detail, /the after-install re-run instruction/);
|
|
480
|
+
assert.match(f[0].detail, /the retired `typescript-sdk` package name/);
|
|
405
481
|
});
|
|
406
482
|
|
|
407
|
-
it('
|
|
408
|
-
// Same prose, two tiers:
|
|
409
|
-
// package, while an adopter
|
|
410
|
-
assert.deepEqual(readmeFindings('recorder', 'recorder/README.md',
|
|
411
|
-
const adopter = readmeFindings('site', 'site/README.md',
|
|
412
|
-
assert.deepEqual(adopter.map((x) => x.kind), ['ldt section
|
|
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']);
|
|
413
493
|
});
|
|
414
494
|
|
|
415
495
|
it('does not require the publish sentences from a linking package either', () => {
|
|
416
496
|
// The publish tier is about the two packages that ship a dist tarball;
|
|
417
497
|
// a linking package is never asked for those sentences.
|
|
418
|
-
assert.deepEqual(
|
|
498
|
+
assert.deepEqual(
|
|
499
|
+
readmeFindings('ui-sdk', 'ui-sdk/README.md', `${linkingSection(72)}\nPublishing notes.\n`),
|
|
500
|
+
[]
|
|
501
|
+
);
|
|
419
502
|
});
|
|
420
503
|
|
|
421
504
|
it('exempts fenced examples, exactly as the adopter tier does', () => {
|
|
422
|
-
const fenced = `${
|
|
505
|
+
const fenced = `${linkingSection(72)}\n\`\`\`sh\n# historical: npm run ldt after every install\n\`\`\`\n`;
|
|
423
506
|
assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', fenced), []);
|
|
424
507
|
});
|
|
425
508
|
|
|
426
509
|
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
|
-
|
|
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`;
|
|
429
513
|
const f = readmeFindings('recorder', 'recorder/README.md', proseForm);
|
|
430
514
|
assert.equal(f.length, 1);
|
|
431
|
-
assert.equal(f[0].kind, '
|
|
515
|
+
assert.equal(f[0].kind, 'linked-sibling section drift');
|
|
432
516
|
});
|
|
433
517
|
});
|
|
434
518
|
|