@widgetic/dev-tools 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +90 -18
- package/README.md +114 -35
- package/bin/check-design-system-peers.mjs +53 -0
- package/bin/check-layout-fixtures.mjs +0 -0
- package/bin/check-links-fixtures.mjs +0 -0
- package/bin/check-links.mjs +0 -0
- package/bin/check-readme-contracts-fixtures.mjs +27 -0
- package/bin/check-readme-contracts.mjs +82 -0
- package/lib/frontend-layout.mjs +10 -1
- package/lib/lockfile-peers.mjs +193 -0
- package/lib/readme-contract.d.mts +130 -0
- package/lib/readme-contract.mjs +385 -0
- package/lib/semver-lite.mjs +71 -0
- package/package.json +11 -4
- package/test/frontend-layout.test.mjs +6 -0
- package/test/lockfile-peers.test.mjs +208 -0
- package/test/readme-contract.test.mjs +543 -0
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The README contract, as data: what each Frontend package's README must say
|
|
3
|
+
* about its sibling-package setup, and how `readmeFindings` reports the ways
|
|
4
|
+
* the prose rots.
|
|
5
|
+
*
|
|
6
|
+
* Two tiers, because two kinds of package consume siblings:
|
|
7
|
+
*
|
|
8
|
+
* - **Adopters** ({@link ADOPTER_PACKAGES}) compile sibling `@widgetic/*`
|
|
9
|
+
* **source** in dev through the dev-alias setup dev-tools owns, and must
|
|
10
|
+
* carry the canonical sibling-source sentences verbatim. The publish tier
|
|
11
|
+
* ({@link PUBLISH_PACKAGES}) adds the publish-preparation sentences.
|
|
12
|
+
* - **Linking packages** ({@link LINKING_PACKAGES}) consume a sibling through
|
|
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.
|
|
23
|
+
*
|
|
24
|
+
* The section earned its guard by drifting three different ways. It taught a
|
|
25
|
+
* hand-linking practice after the practice was retired (site's `lps` and
|
|
26
|
+
* `pnpm link` lore pointed at a `typescript-sdk` package that no longer
|
|
27
|
+
* existed); it never existed at all in an app that loads dev-tools's alias
|
|
28
|
+
* modules on every dev boot (`file-browser`); and the wording forked per app
|
|
29
|
+
* until a change to the workflow had no single place to land. A contract
|
|
30
|
+
* every README copies by hand is a contract six checkouts hold differently.
|
|
31
|
+
*
|
|
32
|
+
* Everything here is injectable-root pure: `collectReadmeDrift(frontendRoot)`
|
|
33
|
+
* takes the `Frontend/` checkout root and returns the findings found under
|
|
34
|
+
* it, which is what lets the fixture suite build a throwaway checkout, drift
|
|
35
|
+
* it on purpose, and assert on the result without touching real READMEs.
|
|
36
|
+
*
|
|
37
|
+
* Zero dependencies, plain ESM, shipped in the tarball so a consumer can run
|
|
38
|
+
* the check against its own checkout with the installed copy.
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The canonical prose, sentence by sentence. An adopter's sibling-source
|
|
45
|
+
* section must carry every sentence, verbatim, in this order. Matching is
|
|
46
|
+
* ordered-substring over whitespace-collapsed text, so each README wraps the
|
|
47
|
+
* prose to its own line width and may interleave sentences of its own — but
|
|
48
|
+
* any rewrite of the wording fails, because the rewrites are how stale
|
|
49
|
+
* instructions crept back. The last sentence carries the dev-tools link, so
|
|
50
|
+
* a section that stops linking the workflow fails the same way one that
|
|
51
|
+
* misstates it does.
|
|
52
|
+
*/
|
|
53
|
+
export const CANONICAL_SENTENCES = [
|
|
54
|
+
'This app compiles sibling `@widgetic/*` source in dev through the dev-alias setup `@widgetic/dev-tools` owns.',
|
|
55
|
+
'The alias tables, the `$lib` remap, and everything else the mapping needs come from the installed `@widgetic/dev-tools` dependency.',
|
|
56
|
+
'An ordinary `npm install` is the whole setup — there is no linking step.',
|
|
57
|
+
'The why and the silent-degrade failure mode live in [the dev-tools README](../dev-tools/README.md).'
|
|
58
|
+
];
|
|
59
|
+
|
|
60
|
+
/** The packages whose READMEs must carry the canonical section. */
|
|
61
|
+
export const ADOPTER_PACKAGES = [
|
|
62
|
+
'chat',
|
|
63
|
+
'editor',
|
|
64
|
+
'file-browser',
|
|
65
|
+
'site',
|
|
66
|
+
'widget-creator',
|
|
67
|
+
'__template__'
|
|
68
|
+
];
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The canonical publish-preparation prose, for the packages that publish to
|
|
72
|
+
* the registry. Same matching rules as the sibling sentences: ordered
|
|
73
|
+
* substrings over collapsed prose, app-specific sentences allowed around
|
|
74
|
+
* them. The last two sentences are the discipline the lockfile incidents
|
|
75
|
+
* taught — a consumer whose lockfile never resolved the release was the
|
|
76
|
+
* failure that bit `design-system` and `file-browser` themselves.
|
|
77
|
+
*/
|
|
78
|
+
export const CANONICAL_PUBLISH_SENTENCES = [
|
|
79
|
+
'Publishing starts here: `npm run package` builds the `dist/` directory that is the only content the published tarball ships.',
|
|
80
|
+
'Linked consumers keep resolving this checkout\u2019s files until the release lands, so a change is not real for anyone else until it publishes.',
|
|
81
|
+
'After publishing, each consumer package bumps its dependency to the new version and refreshes its lockfile with `npm install`, so `npm ci` resolves the release from the registry.',
|
|
82
|
+
'A consumer that skips the lockfile refresh keeps resolving the old version, so the version bump and the lockfile refresh land as one commit.'
|
|
83
|
+
];
|
|
84
|
+
|
|
85
|
+
/** The packages whose READMEs must carry the publish-preparation section. */
|
|
86
|
+
export const PUBLISH_PACKAGES = ['chat', 'file-browser'];
|
|
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
|
+
|
|
108
|
+
/**
|
|
109
|
+
* The packages that consume a sibling checkout through a hand-made link to its
|
|
110
|
+
* built output rather than the dev-alias workflow — `embed-sdk` and `ui-sdk`
|
|
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.
|
|
115
|
+
*/
|
|
116
|
+
export const LINKING_PACKAGES = ['embed-sdk', 'recorder', 'ui-sdk'];
|
|
117
|
+
|
|
118
|
+
/** Every package the check reads, in tier order. */
|
|
119
|
+
export const CHECKED_PACKAGES = [...ADOPTER_PACKAGES, ...LINKING_PACKAGES];
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Instructions from the link era that must never come back, word-bounded on
|
|
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.
|
|
137
|
+
*/
|
|
138
|
+
const STALE_PATTERNS = [
|
|
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' }
|
|
145
|
+
];
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The one shape `collectReadmeDrift` returns per finding — same fields as the
|
|
149
|
+
* link-doctor's problems, so reporters can treat the two checks alike.
|
|
150
|
+
*
|
|
151
|
+
* @typedef {object} ReadmeFinding
|
|
152
|
+
* @property {'ldt section missing' | 'ldt section drift' | 'linked-sibling section missing' | 'linked-sibling section drift' | 'publish section missing' | 'publish section drift'} kind
|
|
153
|
+
* @property {string} pkg The package directory under `Frontend/`.
|
|
154
|
+
* @property {string} detail What is wrong, README-relative.
|
|
155
|
+
* @property {string} fix The action that repairs it.
|
|
156
|
+
*/
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Strip fenced code blocks and collapse wrapping, so sentence matching and
|
|
160
|
+
* stale-pattern scanning see prose the way a reader does. Fenced blocks are
|
|
161
|
+
* dropped entirely: the canonical section is prose, and instructions inside a
|
|
162
|
+
* fence are commands somebody is expected to run — exactly what must not
|
|
163
|
+
* sneak back. Link targets lose their `#fragment`: the anchor is navigation
|
|
164
|
+
* detail, not wording, and deep links to the workflow section are fine.
|
|
165
|
+
*
|
|
166
|
+
* @param {string} text A README's raw text.
|
|
167
|
+
* @returns {string} Prose with fences removed and runs of whitespace collapsed.
|
|
168
|
+
*/
|
|
169
|
+
function prose(text) {
|
|
170
|
+
const kept = [];
|
|
171
|
+
let fenced = false;
|
|
172
|
+
for (const line of text.split('\n')) {
|
|
173
|
+
if (/^\s*```/.test(line)) {
|
|
174
|
+
fenced = !fenced;
|
|
175
|
+
continue;
|
|
176
|
+
}
|
|
177
|
+
if (!fenced) kept.push(line);
|
|
178
|
+
}
|
|
179
|
+
return kept
|
|
180
|
+
.join('\n')
|
|
181
|
+
.replace(/\]\(([^)\s#]+)#[^)\s]*\)/g, ']($1)')
|
|
182
|
+
.replace(/\s+/g, ' ')
|
|
183
|
+
.trim();
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* The first sentence of `sentences` that is missing or out of order, or
|
|
188
|
+
* `null` when the text carries all of them, in order.
|
|
189
|
+
*
|
|
190
|
+
* @param {string} text Whitespace-collapsed prose.
|
|
191
|
+
* @param {string[]} sentences The canonical sentences to require.
|
|
192
|
+
* @returns {string | null}
|
|
193
|
+
*/
|
|
194
|
+
function firstMissingSentence(text, sentences) {
|
|
195
|
+
let at = 0;
|
|
196
|
+
for (const sentence of sentences) {
|
|
197
|
+
at = text.indexOf(sentence, at);
|
|
198
|
+
if (at === -1) return sentence;
|
|
199
|
+
at += sentence.length;
|
|
200
|
+
}
|
|
201
|
+
return null;
|
|
202
|
+
}
|
|
203
|
+
|
|
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);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* The `ldt section drift` finding for retired instructions in `text`, or none.
|
|
223
|
+
* Both tiers reach their prose this way, so the same drift reports the same
|
|
224
|
+
* way wherever it appears — only the repair differs, since an adopter's setup
|
|
225
|
+
* is already an ordinary `npm install` and a linking package's is not.
|
|
226
|
+
*
|
|
227
|
+
* @param {string} pkg The package's directory name under `Frontend/`.
|
|
228
|
+
* @param {string} text Whitespace-collapsed prose.
|
|
229
|
+
* @param {string} fix The action that repairs the drift.
|
|
230
|
+
* @param {'adopter' | 'linking'} tier Whose prose this is.
|
|
231
|
+
* @returns {ReadmeFinding[]}
|
|
232
|
+
*/
|
|
233
|
+
function staleFindings(pkg, text, fix, tier) {
|
|
234
|
+
const stale = staleInstructionHits(text, tier);
|
|
235
|
+
if (stale.length === 0) return [];
|
|
236
|
+
return [
|
|
237
|
+
{
|
|
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',
|
|
242
|
+
pkg,
|
|
243
|
+
detail: `link-era instructions present in the README: ${stale.join(', ')}`,
|
|
244
|
+
fix
|
|
245
|
+
}
|
|
246
|
+
];
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* Find what one package's README violates, by tier: an adopter must carry the
|
|
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.
|
|
256
|
+
*
|
|
257
|
+
* @param {string} pkg The package's directory name under `Frontend/`.
|
|
258
|
+
* @param {string} readmePath Where the README should be.
|
|
259
|
+
* @param {string} raw The README's raw text, or `''` when absent.
|
|
260
|
+
* @returns {ReadmeFinding[]}
|
|
261
|
+
*/
|
|
262
|
+
export function readmeFindings(pkg, readmePath, raw) {
|
|
263
|
+
const findings = [];
|
|
264
|
+
const text = prose(raw);
|
|
265
|
+
|
|
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.
|
|
270
|
+
if (LINKING_PACKAGES.includes(pkg)) {
|
|
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
|
+
)
|
|
298
|
+
);
|
|
299
|
+
return findings;
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
const canonicalGap = text ? firstMissingSentence(text, CANONICAL_SENTENCES) : CANONICAL_SENTENCES[0];
|
|
303
|
+
if (canonicalGap !== null) {
|
|
304
|
+
// A README that names dev-tools has a section that drifted; one that
|
|
305
|
+
// never mentions it has no section to drift.
|
|
306
|
+
const drifted = text.includes('@widgetic/dev-tools');
|
|
307
|
+
findings.push({
|
|
308
|
+
kind: drifted ? 'ldt section drift' : 'ldt section missing',
|
|
309
|
+
pkg,
|
|
310
|
+
detail: drifted
|
|
311
|
+
? `the sibling-source section does not carry the canonical prose — first sentence missing or out of order: "${canonicalGap}"`
|
|
312
|
+
: `no sibling-source section was found in ${readmePath}`,
|
|
313
|
+
fix: 'copy the canonical sibling-source section from dev-tools/README.md ("The ldt workflow"); keep app-specific notes outside its sentences'
|
|
314
|
+
});
|
|
315
|
+
// An absent README hides the publish requirement too — a publisher must
|
|
316
|
+
// hear about both sections, not just the first one found.
|
|
317
|
+
if (PUBLISH_PACKAGES.includes(pkg)) {
|
|
318
|
+
findings.push({
|
|
319
|
+
kind: 'publish section missing',
|
|
320
|
+
pkg,
|
|
321
|
+
detail: `no publish-preparation section was found in ${readmePath}`,
|
|
322
|
+
fix: 'copy the canonical publish-preparation sentences from dev-tools/README.md; keep app-specific flow notes outside them'
|
|
323
|
+
});
|
|
324
|
+
}
|
|
325
|
+
return findings;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
findings.push(
|
|
329
|
+
...staleFindings(
|
|
330
|
+
pkg,
|
|
331
|
+
text,
|
|
332
|
+
'retire the link-era instructions; the workflow is an ordinary npm install (see dev-tools README, "The ldt workflow")',
|
|
333
|
+
'adopter'
|
|
334
|
+
)
|
|
335
|
+
);
|
|
336
|
+
|
|
337
|
+
if (PUBLISH_PACKAGES.includes(pkg)) {
|
|
338
|
+
const publishGap = text ? firstMissingSentence(text, CANONICAL_PUBLISH_SENTENCES) : CANONICAL_PUBLISH_SENTENCES[0];
|
|
339
|
+
if (publishGap !== null) {
|
|
340
|
+
// A section that shares any canonical wording has drifted; unrelated
|
|
341
|
+
// publishing prose (app-specific iteration notes say "publishing" too)
|
|
342
|
+
// is a missing section, not a drifted one.
|
|
343
|
+
const drifted = CANONICAL_PUBLISH_SENTENCES.some((s) => text.includes(s));
|
|
344
|
+
findings.push({
|
|
345
|
+
kind: drifted ? 'publish section drift' : 'publish section missing',
|
|
346
|
+
pkg,
|
|
347
|
+
detail: drifted
|
|
348
|
+
? `the publish-preparation section does not carry the canonical prose \u2014 first sentence missing or out of order: "${publishGap}"`
|
|
349
|
+
: `no publish-preparation section was found in ${readmePath}`,
|
|
350
|
+
fix: 'copy the canonical publish-preparation sentences from dev-tools/README.md; keep app-specific flow notes outside them'
|
|
351
|
+
});
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
return findings;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* Collect every README finding under a Frontend checkout.
|
|
360
|
+
*
|
|
361
|
+
* @param {string} frontendRoot The `Frontend/` checkout root.
|
|
362
|
+
* @param {{ packages?: string[] }} [options] Package directories to check;
|
|
363
|
+
* defaults to {@link CHECKED_PACKAGES} (both tiers).
|
|
364
|
+
* @returns {{ packages: string[], findings: ReadmeFinding[] }}
|
|
365
|
+
*/
|
|
366
|
+
export function collectReadmeDrift(frontendRoot, { packages, adopters } = {}) {
|
|
367
|
+
// The option selected one tier's packages until there were two. Failing
|
|
368
|
+
// loudly beats the alternative: an old caller's list would be ignored and
|
|
369
|
+
// the defaults would be checked instead, which silently checks the wrong
|
|
370
|
+
// thing — the exact failure this package exists to prevent.
|
|
371
|
+
if (adopters !== undefined) {
|
|
372
|
+
throw new Error(
|
|
373
|
+
'collectReadmeDrift: the `adopters` option was renamed to `packages` — it now selects both contract tiers'
|
|
374
|
+
);
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
const subjects = packages ?? CHECKED_PACKAGES;
|
|
378
|
+
const findings = [];
|
|
379
|
+
for (const pkg of subjects) {
|
|
380
|
+
const readmePath = `${frontendRoot}/${pkg}/README.md`;
|
|
381
|
+
const raw = existsSync(readmePath) ? readFileSync(readmePath, 'utf8') : '';
|
|
382
|
+
findings.push(...readmeFindings(pkg, readmePath, raw));
|
|
383
|
+
}
|
|
384
|
+
return { packages: [...subjects], findings };
|
|
385
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The smallest semver range test this repo needs — `satisfies` for the range
|
|
3
|
+
* shapes the widgetic manifests actually declare: carets (`^0.5.12`),
|
|
4
|
+
* greater-than-or-equal peers (`>=0.3.0`), and exact pins (`0.5.14`).
|
|
5
|
+
*
|
|
6
|
+
* This deliberately replaces a `semver` dependency: the check ships to
|
|
7
|
+
* consumers through the dev-tools tarball, and the four lines of range logic
|
|
8
|
+
* below are the entire contract. Anything this cannot parse fails *closed* —
|
|
9
|
+
* `satisfies` returns `false` so an exotic range surfaces as a finding, not as
|
|
10
|
+
* a silent pass.
|
|
11
|
+
*
|
|
12
|
+
* @param {string} version A concrete version, e.g. `0.5.14`.
|
|
13
|
+
* @param {string} range A range specifier, e.g. `^0.5.12`.
|
|
14
|
+
* @returns {boolean} Whether `version` satisfies `range`.
|
|
15
|
+
*/
|
|
16
|
+
export function satisfies(version, range) {
|
|
17
|
+
const v = parse(version);
|
|
18
|
+
if (!v) return false;
|
|
19
|
+
|
|
20
|
+
const spec = range.trim();
|
|
21
|
+
if (spec === '*' || spec === '') return true;
|
|
22
|
+
|
|
23
|
+
// Tolerate a leading `v`.
|
|
24
|
+
const body = spec.startsWith('v') ? spec.slice(1) : spec;
|
|
25
|
+
|
|
26
|
+
if (body.startsWith('^')) {
|
|
27
|
+
const base = parse(body.slice(1));
|
|
28
|
+
if (!base) return false;
|
|
29
|
+
// ^0.x.y behaves like ~0.x.y in semver: the leftmost nonzero digit is
|
|
30
|
+
// the ceiling. For 0.5.x that means minor must match.
|
|
31
|
+
if (base.major === 0) {
|
|
32
|
+
return v.major === 0 && v.minor === base.minor && v.patch >= base.patch;
|
|
33
|
+
}
|
|
34
|
+
return v.major === base.major && cmp(v, base) >= 0;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
if (body.startsWith('>=')) {
|
|
38
|
+
const base = parse(body.slice(2));
|
|
39
|
+
return base ? cmp(v, base) >= 0 : false;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
if (body.startsWith('>')) {
|
|
43
|
+
const base = parse(body.slice(1));
|
|
44
|
+
return base ? cmp(v, base) > 0 : false;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const exact = parse(body);
|
|
48
|
+
return exact ? cmp(v, exact) === 0 : false;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Parse `major.minor.patch` into numbers, or `null` for anything else —
|
|
53
|
+
* prerelease and build suffixes are outside this check's vocabulary on
|
|
54
|
+
* purpose: failing closed beats approximating.
|
|
55
|
+
*
|
|
56
|
+
* @param {string} s
|
|
57
|
+
* @returns {{ major: number, minor: number, patch: number } | null}
|
|
58
|
+
*/
|
|
59
|
+
export function parse(s) {
|
|
60
|
+
const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(s).trim());
|
|
61
|
+
if (!m) return null;
|
|
62
|
+
return { major: +m[1], minor: +m[2], patch: +m[3] };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Three-way compare of parsed versions. */
|
|
66
|
+
function cmp(a, b) {
|
|
67
|
+
for (const k of ['major', 'minor', 'patch']) {
|
|
68
|
+
if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
|
|
69
|
+
}
|
|
70
|
+
return 0;
|
|
71
|
+
}
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@widgetic/dev-tools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"type": "module",
|
|
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.",
|
|
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": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://gitlab.com/widgeticai/Frontend/dev-tools.git"
|
|
@@ -19,7 +19,10 @@
|
|
|
19
19
|
"check-runtime-deps-fixtures": "bin/check-runtime-deps-fixtures.mjs",
|
|
20
20
|
"check-links": "bin/check-links.mjs",
|
|
21
21
|
"check-links-fixtures": "bin/check-links-fixtures.mjs",
|
|
22
|
-
"check-
|
|
22
|
+
"check-readme-contracts": "bin/check-readme-contracts.mjs",
|
|
23
|
+
"check-readme-contracts-fixtures": "bin/check-readme-contracts-fixtures.mjs",
|
|
24
|
+
"check-layout-fixtures": "bin/check-layout-fixtures.mjs",
|
|
25
|
+
"check-design-system-peers": "bin/check-design-system-peers.mjs"
|
|
23
26
|
},
|
|
24
27
|
"files": [
|
|
25
28
|
"bin",
|
|
@@ -34,8 +37,12 @@
|
|
|
34
37
|
"test:layout": "node --test test/frontend-layout.test.mjs",
|
|
35
38
|
"test:layout:disk": "node bin/check-layout-fixtures.mjs",
|
|
36
39
|
"check:links": "node bin/check-links.mjs",
|
|
40
|
+
"check:readme": "node bin/check-readme-contracts.mjs",
|
|
41
|
+
"check:peers": "node bin/check-design-system-peers.mjs",
|
|
37
42
|
"test:links": "node bin/check-links-fixtures.mjs",
|
|
38
|
-
"test": "
|
|
43
|
+
"test:readme": "node --test test/readme-contract.test.mjs",
|
|
44
|
+
"test:peers": "node --test test/lockfile-peers.test.mjs",
|
|
45
|
+
"test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links && npm run test:readme && npm run test:peers",
|
|
39
46
|
"prepublishOnly": "npm test"
|
|
40
47
|
},
|
|
41
48
|
"volta": {
|
|
@@ -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'],
|