@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
package/CHANGELOG.md
CHANGED
|
@@ -3,28 +3,84 @@
|
|
|
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.
|
|
6
|
+
## 0.3.1 — 2026-10-08
|
|
7
7
|
|
|
8
8
|
### Added
|
|
9
9
|
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
+
|
|
27
|
+
## 0.3.0 — 2026-09-22
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
|
|
31
|
+
- **`check-design-system-peers`** (`lib/lockfile-peers.mjs` +
|
|
32
|
+
`lib/semver-lite.mjs`): fails when `canvas` and `file-browser` — the two
|
|
33
|
+
peers resolving `@widgetic/design-system` from the registry — drift apart:
|
|
34
|
+
lockfiles resolving different versions, a lockfile that no longer matches
|
|
35
|
+
the version the design-system checkout carries, or a manifest range the
|
|
36
|
+
checkout version left. The incident that motivated it: when 0.5.14
|
|
37
|
+
published, canvas's lockfile refreshed while file-browser's kept resolving
|
|
38
|
+
0.5.12 — both ranges still satisfied, nothing failed, and the two apps
|
|
39
|
+
quietly started shipping different component trees. The rule makes the
|
|
40
|
+
next publish's consumer refresh land as one coordinated change: the
|
|
41
|
+
checkout-version comparison fires in both peers the moment a release bumps,
|
|
42
|
+
and goes quiet only when both lockfiles have moved together. Ships with
|
|
43
|
+
its own `node --test` fixture suite (`npm run test:peers`) proving every
|
|
44
|
+
rule fails and every false-positive shape (aligned pair, exact pin, `>=`
|
|
45
|
+
peer) passes. The CLI now has a `bin` entry (`check-design-system-peers`),
|
|
46
|
+
so a peer can call it by name rather than by path into `node_modules` —
|
|
47
|
+
without it the check was reachable only from its own repository.
|
|
48
|
+
- **The publish pipeline runs the two fixture suites it was missing.**
|
|
49
|
+
`test:peers` and `test:readme` are in the build stage before
|
|
50
|
+
`npm pack --dry-run`. Both need no sibling checkout — the readme suite
|
|
51
|
+
already skips its disk-dependent tests where `Frontend/` cannot exist — so
|
|
52
|
+
a release can no longer ship with the peers rules or the README contract
|
|
53
|
+
unrun, which is how 0.2.0 shipped `test:layout` unrun until it was fixed.
|
|
26
54
|
|
|
27
|
-
|
|
55
|
+
### Changed
|
|
56
|
+
|
|
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`,
|
|
59
|
+
`recorder` and `ui-sdk` consume a sibling through a hand-made link to its
|
|
60
|
+
built output rather than the dev-alias workflow, so the canonical
|
|
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
|
|
80
|
+
pass vacuously. `collectReadmeDrift`'s option is now `packages`; the old
|
|
81
|
+
`adopters` name throws rather than silently falling back to the defaults.
|
|
82
|
+
|
|
83
|
+
## 0.2.0 — 2026-09-20
|
|
28
84
|
|
|
29
85
|
The release that makes `frontend-layout.mjs` the only dev-alias table: all six
|
|
30
86
|
`Frontend/` apps that compile sibling source in dev (site, file-browser,
|
|
@@ -41,6 +97,22 @@ module instead of keeping hand-written copies.
|
|
|
41
97
|
|
|
42
98
|
### Added
|
|
43
99
|
|
|
100
|
+
- **`check-links`, the link-doctor** the `ldt` workflow section promised: a
|
|
101
|
+
check that fails when any Frontend package carries a dangling
|
|
102
|
+
`@widgetic/*` symlink (or one resolving outside the checkout), a
|
|
103
|
+
manifest-promised file that nobody built (`main`/`module`/`svelte`/`types`
|
|
104
|
+
and non-glob `exports` values), or a live reference to a dead checkout name
|
|
105
|
+
(`props-editor`, `prompt-chat`). Comments, `__docs`/`__specs` archives,
|
|
106
|
+
build output and live hyphenated identifiers (`.prompt-chat-messages-*`)
|
|
107
|
+
are exempt; dev-tools itself is exempt from the dead-name rule because it
|
|
108
|
+
names the renames as data. Ships with its own fixture bin
|
|
109
|
+
(`check-links-fixtures`) proving every rule fails and every false-positive
|
|
110
|
+
shape passes, plus hand-written `.d.mts` types. Its first real-tree run
|
|
111
|
+
caught `@widgetic/design-system` still exporting the deleted
|
|
112
|
+
`./dist/components/previews/*` and the site's watcher ignoring
|
|
113
|
+
`prompt-chat/dist` and `props-editor/dist` — globs that resolve nothing
|
|
114
|
+
while the chat/editor dist writes they were meant to ignore now reach the
|
|
115
|
+
dev server.
|
|
44
116
|
- **A disk-truth gate for subpath targets** in the `frontend-layout` fixtures:
|
|
45
117
|
every declared subpath alias must point at a path that exists in a real
|
|
46
118
|
checkout, so a directory rename fails a test here instead of silently
|
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@ the repositories that consume it cannot drift apart.
|
|
|
7
7
|
| --- | --- |
|
|
8
8
|
| `check-runtime-deps` | Fails when a package's `package.json` and its published output disagree: a `dependencies` entry the output never imports (a *phantom*, install weight every consumer pays for), or an import the manifest does not declare (a *missing* dependency, which breaks a consumer's build). |
|
|
9
9
|
| `check-runtime-deps-fixtures` | Runs the fixture suite that proves the check above fails when it should. |
|
|
10
|
+
| `check-design-system-peers` | Fails when `canvas` and `file-browser` — the two peers that resolve `@widgetic/design-system` from the registry — disagree: lockfiles resolving different versions, or a lockfile that no longer matches the version the design-system checkout carries. Makes the next publish's consumer refresh land as one coordinated change instead of two drifted ones. |
|
|
10
11
|
|
|
11
12
|
It also ships two `lib/` modules with hand-written types and their own `node --test`
|
|
12
13
|
fixtures:
|
|
@@ -18,6 +19,10 @@ fixtures:
|
|
|
18
19
|
move or rename is a change here, not a five-repository edit
|
|
19
20
|
(`npm run test:layout`). See [Building a consumer's dev
|
|
20
21
|
aliases](#building-a-consumers-dev-aliases-libfrontend-layoutmjs) below.
|
|
22
|
+
- `lib/lockfile-peers.mjs` — the design-system peer-coordination rules behind
|
|
23
|
+
`check-design-system-peers` (with `lib/semver-lite.mjs`, the deliberately
|
|
24
|
+
tiny range test that fails closed on shapes it does not parse)
|
|
25
|
+
(`npm run test:peers`).
|
|
21
26
|
|
|
22
27
|
## Why this is a published package
|
|
23
28
|
|
|
@@ -77,8 +82,9 @@ const plugin =
|
|
|
77
82
|
```
|
|
78
83
|
|
|
79
84
|
Load it dynamically: the package is dev-only tooling, and a consumer whose dev
|
|
80
|
-
server runs without it
|
|
81
|
-
See `Frontend/site/scripts/widgetic-dev-aliases.ts` for the working
|
|
85
|
+
server runs without it installed must degrade to a warning, not fail its
|
|
86
|
+
config. See `Frontend/site/scripts/widgetic-dev-aliases.ts` for the working
|
|
87
|
+
example.
|
|
82
88
|
|
|
83
89
|
### Building a consumer's dev aliases
|
|
84
90
|
|
|
@@ -133,7 +139,7 @@ index-to-`src/` rewrite.
|
|
|
133
139
|
Load it dynamically, exactly like the remap: a bare specifier resolved through
|
|
134
140
|
`node_modules`, degrading to a warning where dev-tools is not linked (Render
|
|
135
141
|
builds compile no sibling source anyway). The apps link it with their `ldt`
|
|
136
|
-
script — see [the `ldt` workflow](#the-ldt-workflow-
|
|
142
|
+
script — see [the `ldt` workflow](#the-ldt-workflow-developing-against-sibling-source)
|
|
137
143
|
below. `Frontend/site/scripts/widgetic-dev-aliases.ts` is the working example.
|
|
138
144
|
|
|
139
145
|
The layout's fixtures gate it against the disk: every declared subpath target
|
|
@@ -143,37 +149,111 @@ subpath — `design-system/previews` → a directory that no longer exists —
|
|
|
143
149
|
inherited from the hand-kept tables it replaced; this gate is what forbids the
|
|
144
150
|
next one.)
|
|
145
151
|
|
|
146
|
-
### The `ldt` workflow:
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
`
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
152
|
+
### The `ldt` workflow: developing against sibling source
|
|
153
|
+
|
|
154
|
+
The apps that compile sibling `@widgetic/*` source in dev point here. The
|
|
155
|
+
workflow was once a hand-run `ldt` script that recreated the
|
|
156
|
+
`node_modules/@widgetic/dev-tools` link after every `npm run i` — an install
|
|
157
|
+
rebuilds `node_modules` and prunes an unowned link as an extra. It is
|
|
158
|
+
retired: dev-tools has published to the registry since 0.2.0, every app
|
|
159
|
+
declares it as a real dependency, and an ordinary `npm install` is the whole
|
|
160
|
+
setup. The `import()`s below resolve through `node_modules` from the
|
|
161
|
+
installed package; nothing is created by hand and nothing needs re-running
|
|
162
|
+
after an install.
|
|
163
|
+
|
|
164
|
+
The apps state this in their own READMEs, and hand-copied prose drifts —
|
|
165
|
+
it taught the retired linking practice, it went missing entirely in an app
|
|
166
|
+
that needed it, and the wordings forked until a workflow change had no
|
|
167
|
+
single place to land. `check-readme-contracts` turns that into a test:
|
|
168
|
+
every adopter's sibling-source section must carry [the canonical
|
|
169
|
+
sentences](lib/readme-contract.mjs), in order, with no link-era
|
|
170
|
+
instructions in prose. The packages that publish to the registry (`chat`,
|
|
171
|
+
`file-browser`) must also carry [the canonical
|
|
172
|
+
publish-preparation sentences](lib/readme-contract.mjs) — package the
|
|
173
|
+
tarball, publish, and have every consumer refresh its lockfile in the same
|
|
174
|
+
commit as its version bump. Run it as `npm run check:readme` here, or
|
|
175
|
+
`npx check-readme-contracts` anywhere the package is installed.
|
|
176
|
+
|
|
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.
|
|
193
|
+
|
|
194
|
+
Two things keep the link era's failure mode visible, because **nothing
|
|
195
|
+
fails** when sibling-source development quietly stops working: the dynamic
|
|
196
|
+
import degrades to the warning ("@widgetic/dev-tools not resolvable —
|
|
171
197
|
sibling dev aliases disabled"), the app boots, and sibling packages compile
|
|
172
198
|
from their installed `dist/` instead of `src/` — HMR on library edits quietly
|
|
173
199
|
gone. The warning on the first dev-server boot is the tell — and
|
|
174
200
|
[the link-doctor](#the-link-doctor-checking-sibling-links-dists-and-dead-names)
|
|
175
201
|
below turns that manual check into a test.
|
|
176
202
|
|
|
203
|
+
Apps may still link individual siblings to iterate without publishing —
|
|
204
|
+
chat's idempotent `scripts/link-siblings.mjs` links its sibling peers
|
|
205
|
+
(dev-tools, api-sdk, design-system) from a `predev` and `prepackage:watch`
|
|
206
|
+
hook, and site's `lps` exists for the same purpose for its embedded
|
|
207
|
+
`file-browser`. Those are per-app choices about which sibling to iterate on;
|
|
208
|
+
they are not part of dev-tools setup, and no step here depends on them.
|
|
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
|
+
|
|
177
257
|
### The link doctor: checking sibling links, dists, and dead names
|
|
178
258
|
|
|
179
259
|
`check-links` is the automated form of the eyeballing this section used to
|
|
@@ -192,7 +272,7 @@ three classes of silent rot:
|
|
|
192
272
|
exempt; a *live* glob, import or path still naming a deleted checkout is
|
|
193
273
|
the finding.
|
|
194
274
|
|
|
195
|
-
Run it from the dev-tools checkout, or from
|
|
275
|
+
Run it from the dev-tools checkout, or from any app that has it installed:
|
|
196
276
|
|
|
197
277
|
```sh
|
|
198
278
|
npm run check:links # in Frontend/dev-tools
|
|
@@ -221,12 +301,11 @@ looking installed — the site's `chat` link survived the `prompt-chat` rename
|
|
|
221
301
|
that way. If `llinks` shows an entry but the dev server still warns, check
|
|
222
302
|
whether the link's target exists.
|
|
223
303
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
keeps owing the after-`npm run i` re-run.
|
|
304
|
+
That is now the only state: every app consumes the published package as a
|
|
305
|
+
dependency and no `ldt` step exists anywhere. The story stays because the
|
|
306
|
+
link-era failure modes are exactly what the link-doctor guards against — a
|
|
307
|
+
stale `npm link` habit or a per-app iteration script can still leave a link
|
|
308
|
+
that outlives its target.
|
|
230
309
|
|
|
231
310
|
### A deliberate exception
|
|
232
311
|
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Are the design-system peers' lockfiles still one coordinated story?
|
|
4
|
+
*
|
|
5
|
+
* `@widgetic/design-system` reaches sibling apps through two registry
|
|
6
|
+
* consumers — `canvas` and `file-browser` — and each keeps its own lockfile.
|
|
7
|
+
* A caret range promises compatibility, not coordination: when 0.5.14
|
|
8
|
+
* published, canvas's lockfile refreshed to it while file-browser's kept
|
|
9
|
+
* resolving 0.5.12. Nothing broke, no test went red, and both resolutions
|
|
10
|
+
* satisfied `^0.5.12` — but the two apps had quietly started shipping
|
|
11
|
+
* different component trees, so a shared screen renders with two different
|
|
12
|
+
* designs depending on which app hosts it. That split is what this check
|
|
13
|
+
* makes impossible:
|
|
14
|
+
*
|
|
15
|
+
* version-divergence the peers' lockfiles must resolve the same
|
|
16
|
+
* design-system version — the same bar, not merely a
|
|
17
|
+
* bar both ranges happen to admit.
|
|
18
|
+
*
|
|
19
|
+
* stale-manifest each peer's range must admit the version the
|
|
20
|
+
* design-system checkout carries. This fires at the
|
|
21
|
+
* next publish: a fresh version in the checkout fails
|
|
22
|
+
* both `^0.5.12` ranges until the bump lands, and the
|
|
23
|
+
* failure is the scheduled reminder to do the bump as
|
|
24
|
+
* the coordinated pair the changelog requires.
|
|
25
|
+
*
|
|
26
|
+
* Scope is the Frontend checkout this package ships in. The rules are pure
|
|
27
|
+
* data in `lib/lockfile-peers.mjs` (with `lib/semver-lite.mjs` supplying the
|
|
28
|
+
* range test — failing closed on any range shape it cannot parse); this CLI
|
|
29
|
+
* formats them and exits 1 when anything is broken.
|
|
30
|
+
*
|
|
31
|
+
* Usage: check-design-system-peers [frontendRoot]
|
|
32
|
+
*/
|
|
33
|
+
import { collectPeersProblems, formatPeersProblems, PEERS } from '../lib/lockfile-peers.mjs';
|
|
34
|
+
|
|
35
|
+
const root = process.argv[2];
|
|
36
|
+
if (!root) {
|
|
37
|
+
console.error('usage: check-design-system-peers <frontendRoot>');
|
|
38
|
+
process.exit(2);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const problems = collectPeersProblems(root);
|
|
42
|
+
if (problems.length > 0) {
|
|
43
|
+
console.error(
|
|
44
|
+
`[check-design-system-peers] ${problems.length} problem(s) under ${root}\n\n` +
|
|
45
|
+
formatPeersProblems(problems) +
|
|
46
|
+
'\n'
|
|
47
|
+
);
|
|
48
|
+
process.exit(1);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
console.log(
|
|
52
|
+
`OK — ${PEERS.join(' and ')} resolve the same @widgetic/design-system, and both ranges admit the checkout's version.`
|
|
53
|
+
);
|
|
File without changes
|
|
File without changes
|
package/bin/check-links.mjs
CHANGED
|
File without changes
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Run the fixture suite that proves the README contract fails when it should.
|
|
4
|
+
*
|
|
5
|
+
* Same contract as `check-links-fixtures`: the suite ships in this package so
|
|
6
|
+
* a consuming repository can run it against the exact version it installed,
|
|
7
|
+
* instead of trusting that somebody else watched the guard go red.
|
|
8
|
+
*
|
|
9
|
+
* The runner is spawned rather than the suite imported, so the output and the
|
|
10
|
+
* exit code are the runner's own — which is the only thing CI reads.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { spawnSync } from 'node:child_process';
|
|
14
|
+
import { fileURLToPath } from 'node:url';
|
|
15
|
+
|
|
16
|
+
const suite = fileURLToPath(new URL('../test/readme-contract.test.mjs', import.meta.url));
|
|
17
|
+
|
|
18
|
+
const { status } = spawnSync(process.execPath, ['--test', suite], { stdio: 'inherit' });
|
|
19
|
+
|
|
20
|
+
if (status !== 0) {
|
|
21
|
+
console.error(
|
|
22
|
+
'\n[check-readme-contracts] the fixture suite failed: the check no longer fails when it should.\n' +
|
|
23
|
+
' That makes a green contract check meaningless, so it is a failure of the check itself.\n'
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
process.exit(status ?? 1);
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Does every README still tell the truth about its sibling-package setup?
|
|
4
|
+
*
|
|
5
|
+
* Six Frontend apps compile sibling `@widgetic/*` source in dev and each
|
|
6
|
+
* copies the sibling-source section of its README by hand from the dev-tools
|
|
7
|
+
* README. Hand-copied prose rots: it taught the retired hand-linking practice
|
|
8
|
+
* (site's `lps` and `pnpm link` lore, naming a package that no longer
|
|
9
|
+
* existed), it never existed in an app that loads dev-tools's alias modules
|
|
10
|
+
* on every dev boot (`file-browser`), and the wordings forked per app until a
|
|
11
|
+
* workflow change had no single place to land. Nothing fails when it does —
|
|
12
|
+
* the section just stops being true.
|
|
13
|
+
*
|
|
14
|
+
* Three more packages consume a sibling through a hand-made link to its built
|
|
15
|
+
* output — `embed-sdk`, `recorder`, `ui-sdk` — and were read by nothing at
|
|
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.
|
|
23
|
+
*
|
|
24
|
+
* This check reads each package's README and fails when the canonical
|
|
25
|
+
* sibling-source sentences are missing, rewritten, or reordered, or when
|
|
26
|
+
* link-era instructions (`npm run ldt`, `npm link`, `volta run`, `llinks`,
|
|
27
|
+
* the after-install re-run, the retired `typescript-sdk` name) appear in
|
|
28
|
+
* prose. Fenced code blocks are exempt: quoting history is documentation,
|
|
29
|
+
* running it is not. The rules are pure data in `lib/readme-contract.mjs`;
|
|
30
|
+
* this CLI formats them and exits 1 when anything is broken.
|
|
31
|
+
*
|
|
32
|
+
* The fixture suite that proves each rule fails when it should (and that its
|
|
33
|
+
* false-positive shapes pass) is `test/readme-contract.test.mjs`, shipped in
|
|
34
|
+
* the tarball:
|
|
35
|
+
*
|
|
36
|
+
* npx check-readme-contracts-fixtures (or: npm run test:readme in this repo)
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
import { ADOPTER_PACKAGES, LINKING_PACKAGES, collectReadmeDrift } from '../lib/readme-contract.mjs';
|
|
40
|
+
import { existsSync, statSync } from 'node:fs';
|
|
41
|
+
import { fileURLToPath } from 'node:url';
|
|
42
|
+
import { resolve } from 'node:path';
|
|
43
|
+
|
|
44
|
+
// Same convention as check-links's `[frontendRoot]`: an explicit checkout
|
|
45
|
+
// root for the fixture suite (and for auditing a checkout you are not
|
|
46
|
+
// inside), defaulting to the Frontend/ root this package ships in.
|
|
47
|
+
const argRoot = process.argv[2];
|
|
48
|
+
const frontendRoot = argRoot ? resolve(argRoot) : fileURLToPath(new URL('../..', import.meta.url));
|
|
49
|
+
if (!existsSync(frontendRoot) || !statSync(frontendRoot).isDirectory()) {
|
|
50
|
+
console.error(`[check-readme-contracts] not a directory: ${frontendRoot}`);
|
|
51
|
+
process.exit(1);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const { packages, findings } = collectReadmeDrift(frontendRoot);
|
|
55
|
+
|
|
56
|
+
if (packages.length === 0) {
|
|
57
|
+
console.error(`[check-readme-contracts] no packages found — nothing to check`);
|
|
58
|
+
process.exit(1);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
console.log(
|
|
62
|
+
`[check-readme-contracts] ${packages.length} READMEs under Frontend/` +
|
|
63
|
+
` — ${ADOPTER_PACKAGES.length} adopters (canonical section required)` +
|
|
64
|
+
` + ${LINKING_PACKAGES.length} linking packages (linked-sibling section required)`
|
|
65
|
+
);
|
|
66
|
+
if (findings.length === 0) {
|
|
67
|
+
console.log(
|
|
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'
|
|
71
|
+
);
|
|
72
|
+
process.exit(0);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
for (const { kind, pkg, detail, fix } of findings) {
|
|
76
|
+
console.error(`\n ${pkg}: ${kind}\n ${detail}\n → ${fix}`);
|
|
77
|
+
}
|
|
78
|
+
console.error(
|
|
79
|
+
`\n ${findings.length} drifted README${findings.length === 1 ? '' : 's'} across ` +
|
|
80
|
+
`${new Set(findings.map((f) => f.pkg)).size} package(s).\n`
|
|
81
|
+
);
|
|
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).
|