@widgetic/dev-tools 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,129 @@
1
+ # Changelog
2
+
3
+ The format roughly follows [Keep a Changelog](https://keepachangelog.com/); the
4
+ reasons matter more than the categories.
5
+
6
+ ## 0.3.0 — 2026-09-22
7
+
8
+ ### Added
9
+
10
+ - **`check-design-system-peers`** (`lib/lockfile-peers.mjs` +
11
+ `lib/semver-lite.mjs`): fails when `canvas` and `file-browser` — the two
12
+ peers resolving `@widgetic/design-system` from the registry — drift apart:
13
+ lockfiles resolving different versions, a lockfile that no longer matches
14
+ the version the design-system checkout carries, or a manifest range the
15
+ checkout version left. The incident that motivated it: when 0.5.14
16
+ published, canvas's lockfile refreshed while file-browser's kept resolving
17
+ 0.5.12 — both ranges still satisfied, nothing failed, and the two apps
18
+ quietly started shipping different component trees. The rule makes the
19
+ next publish's consumer refresh land as one coordinated change: the
20
+ checkout-version comparison fires in both peers the moment a release bumps,
21
+ and goes quiet only when both lockfiles have moved together. Ships with
22
+ its own `node --test` fixture suite (`npm run test:peers`) proving every
23
+ rule fails and every false-positive shape (aligned pair, exact pin, `>=`
24
+ peer) passes. The CLI now has a `bin` entry (`check-design-system-peers`),
25
+ so a peer can call it by name rather than by path into `node_modules` —
26
+ without it the check was reachable only from its own repository.
27
+ - **The publish pipeline runs the two fixture suites it was missing.**
28
+ `test:peers` and `test:readme` are in the build stage before
29
+ `npm pack --dry-run`. Both need no sibling checkout — the readme suite
30
+ already skips its disk-dependent tests where `Frontend/` cannot exist — so
31
+ a release can no longer ship with the peers rules or the README contract
32
+ unrun, which is how 0.2.0 shipped `test:layout` unrun until it was fixed.
33
+
34
+ ### Changed
35
+
36
+ - **`check-readme-contracts` reads nine READMEs, not six.** `embed-sdk`,
37
+ `recorder` and `ui-sdk` consume a sibling through a hand-made link to its
38
+ built output rather than the dev-alias workflow, so the canonical
39
+ sibling-source sentences would be false in their READMEs and are not
40
+ required of them — but the retired-instruction ban is, and their READMEs
41
+ were read by nothing at all before this: not the adopters' check, not a
42
+ test. `LINKING_PACKAGES` names the tier, the fixture suite drives both of
43
+ its directions (a linking README teaching `npm link` fails, plain prose
44
+ passes, and the same plain prose still fails as an adopter), and the real
45
+ checkout test asserts both tiers are read off the disk so a subject cannot
46
+ pass vacuously. `collectReadmeDrift`'s option is now `packages`; the old
47
+ `adopters` name throws rather than silently falling back to the defaults.
48
+
49
+ ## 0.2.0 — 2026-09-20
50
+
51
+ The release that makes `frontend-layout.mjs` the only dev-alias table: all six
52
+ `Frontend/` apps that compile sibling source in dev (site, file-browser,
53
+ widget-creator, chat, editor, `__template__`) now build their tables from this
54
+ module instead of keeping hand-written copies.
55
+
56
+ ### Removed
57
+
58
+ - **The `previews` design-system subpath** from `frontend-layout.mjs` — it
59
+ shipped in 0.1.0, inherited from the hand-kept consumer tables this module
60
+ replaced, and pointed at `components/previews`, a directory that no longer
61
+ exists and that no consumer imports. The alias every table carried resolved
62
+ nothing. Re-add only with a live path; the fixtures now forbid a dead one.
63
+
64
+ ### Added
65
+
66
+ - **`check-links`, the link-doctor** the `ldt` workflow section promised: a
67
+ check that fails when any Frontend package carries a dangling
68
+ `@widgetic/*` symlink (or one resolving outside the checkout), a
69
+ manifest-promised file that nobody built (`main`/`module`/`svelte`/`types`
70
+ and non-glob `exports` values), or a live reference to a dead checkout name
71
+ (`props-editor`, `prompt-chat`). Comments, `__docs`/`__specs` archives,
72
+ build output and live hyphenated identifiers (`.prompt-chat-messages-*`)
73
+ are exempt; dev-tools itself is exempt from the dead-name rule because it
74
+ names the renames as data. Ships with its own fixture bin
75
+ (`check-links-fixtures`) proving every rule fails and every false-positive
76
+ shape passes, plus hand-written `.d.mts` types. Its first real-tree run
77
+ caught `@widgetic/design-system` still exporting the deleted
78
+ `./dist/components/previews/*` and the site's watcher ignoring
79
+ `prompt-chat/dist` and `props-editor/dist` — globs that resolve nothing
80
+ while the chat/editor dist writes they were meant to ignore now reach the
81
+ dev server.
82
+ - **A disk-truth gate for subpath targets** in the `frontend-layout` fixtures:
83
+ every declared subpath alias must point at a path that exists in a real
84
+ checkout, so a directory rename fails a test here instead of silently
85
+ killing an alias in six apps at once. (The suite already checked checkout
86
+ directories; this closes the subpath gap that let `previews` ship.)
87
+ - **`ldt` link scripts and dev-tools symlinks** in widget-creator, chat,
88
+ editor, and `__template__`, so every app can resolve the shared modules the
89
+ way site and file-browser already did.
90
+
91
+ ### Fixed
92
+
93
+ - **widget-creator's two dead aliases**: `@widgetic/chat` → the deleted
94
+ `prompt-chat` checkout and `@widgetic/editor` → the deleted `props-editor`
95
+ checkout, surviving only because nothing imported those specifiers there.
96
+ The canonical layout resolves both names to their real directories.
97
+ - **widget-creator's inline `$lib` remap** (a fourth hand-copy, drifted toward
98
+ its own loop style) now uses the shared `createSiblingSrcLibPlugin`, and its
99
+ remap plugin only loads in dev — the gate under which it can ever fire.
100
+ - **The publish pipeline never ran `test:layout`** even though the layout
101
+ module ships in the tarball; the build stage now runs all three suites
102
+ before `npm pack --dry-run`. (`test:vite` had the same gap before 0.1.0.)
103
+
104
+ ### Changed
105
+
106
+ - The consumers' dynamic-load degrade pattern is unchanged: where dev-tools is
107
+ not linked (Render/production), a config still warns and compiles no sibling
108
+ source — but selecting a package name the layout does not declare now throws
109
+ at config load. Silent fall-through to `node_modules` is how the drift
110
+ started; loud is the point.
111
+
112
+ ## 0.1.0 — 2026-09-19
113
+
114
+ First publish. What the tarball actually contained:
115
+
116
+ - **`bin/check-runtime-deps`** (+ `check-runtime-deps-fixtures`): fails when a
117
+ package's manifest and its published output disagree — a `dependencies`
118
+ entry the output never imports (a phantom), or an import the manifest does
119
+ not declare (missing). Released once so per-repository copies could not
120
+ drift; the `EXCEPTIONS` map inside the tool is the one shared place for
121
+ dependencies a scanner cannot see.
122
+ - **`lib/vite-src-lib.mjs`**: the per-importer sibling-`$lib` Vite remap
123
+ shared by the site and file-browser (`createSiblingSrcLibPlugin`), with
124
+ types and `node --test` fixtures.
125
+ - **`lib/frontend-layout.mjs`** (v1): the canonical `Frontend/` sibling
126
+ layout — `SIBLING_PACKAGES` keyed by `@widgetic/*` name suffix, with
127
+ renames recorded beside the entries — plus `buildSiblingAliases`,
128
+ `devOptimizeExclude`, and `devSsrNoExternal`. Shipped with the stale
129
+ `previews` subpath inherited from the hand-kept tables (removed in 0.2.0).
package/README.md CHANGED
@@ -7,11 +7,22 @@ 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
- It also ships `lib/vite-src-lib.mjs` — the per-importer sibling-`$lib` Vite
12
- remap shared by the site and file-browser so their copies cannot drift — with
13
- types in `lib/vite-src-lib.d.mts` and its own `node --test` fixtures
14
- (`npm run test:vite`).
12
+ It also ships two `lib/` modules with hand-written types and their own `node --test`
13
+ fixtures:
14
+
15
+ - `lib/vite-src-lib.mjs` — the per-importer sibling-`$lib` Vite remap shared by
16
+ the site and file-browser so their copies cannot drift (`npm run test:vite`).
17
+ - `lib/frontend-layout.mjs` — the canonical `Frontend/` sibling layout and the
18
+ builder that turns it into every consumer's dev-alias tables, so a sibling
19
+ move or rename is a change here, not a five-repository edit
20
+ (`npm run test:layout`). See [Building a consumer's dev
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`).
15
26
 
16
27
  ## Why this is a published package
17
28
 
@@ -71,8 +82,176 @@ const plugin =
71
82
  ```
72
83
 
73
84
  Load it dynamically: the package is dev-only tooling, and a consumer whose dev
74
- server runs without it linked must degrade to a warning, not fail its config.
75
- See `Frontend/site/scripts/widgetic-dev-aliases.ts` for the working example.
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.
88
+
89
+ ### Building a consumer's dev aliases
90
+
91
+ Every app under `Frontend/` can compile sibling `@widgetic/*` **source** in dev
92
+ instead of built `dist/` — instant HMR on a library edit. Doing that correctly
93
+ needs three lists that must agree: the alias table, `optimizeDeps.exclude`
94
+ (never prebundle what you alias — the prebundle loads while edits go to `src/`
95
+ and the two diverge), and `ssr.noExternal` (never externalize what you compile
96
+ — SSR loads the built package while the client compiles `src/`, same divergence
97
+ by a different mechanism).
98
+
99
+ Six apps kept those lists by hand, and they drifted. Aliases to directories
100
+ that no longer existed resolved nothing while the dev server kept booting —
101
+ Vite falls through to `node_modules` or a dangling link — which is why
102
+ per-entry `existsSync` fallbacks started appearing in one config after
103
+ another: the tables had become untrustworthy.
104
+
105
+ `frontend-layout.mjs` fixes the cause: the directory each `@widgetic/*` name
106
+ maps to is declared **once** (`SIBLING_PACKAGES`, with renames recorded beside
107
+ the entries — `editor` was `props-editor`, `chat` was `prompt-chat`), and one
108
+ selection produces all three artifacts:
109
+
110
+ ```js
111
+ const layout = await import(
112
+ /* @vite-ignore */ '@widgetic/dev-tools/lib/frontend-layout.mjs'
113
+ ).catch(() => null);
114
+
115
+ const packages = ['api-sdk', 'design-system', 'cache-layer'];
116
+
117
+ resolve: {
118
+ alias: layout
119
+ ? layout.buildSiblingAliases(frontendRoot, { packages })
120
+ : {}, // degrade, don't fail the config
121
+ },
122
+ optimizeDeps: { exclude: layout ? layout.devOptimizeExclude(packages) : [] },
123
+ ssr: { noExternal: layout ? layout.devSsrNoExternal(packages) : [] },
124
+ ```
125
+
126
+ What stays in the consumer is **which** packages it selects — a behavior
127
+ choice, since aliasing a package's index to `src/` changes what the dev server
128
+ compiles — and nothing else. A sibling move or rename is a change here and a
129
+ version bump, not an edit in every app. Selecting a name the layout does not
130
+ declare throws at config load: an unaliased sibling silently falls through to
131
+ `node_modules`, and loud is the point.
132
+
133
+ `@widgetic/design-system` narrows with two options. `designSystemSubpaths`
134
+ picks which `@widgetic/design-system/<subpath>` aliases to emit (defaults to
135
+ every subpath the layout declares), and `designSystemIndex: false` keeps the
136
+ bare specifier resolving to the installed package — subpath aliases only, no
137
+ index-to-`src/` rewrite.
138
+
139
+ Load it dynamically, exactly like the remap: a bare specifier resolved through
140
+ `node_modules`, degrading to a warning where dev-tools is not linked (Render
141
+ builds compile no sibling source anyway). The apps link it with their `ldt`
142
+ script — see [the `ldt` workflow](#the-ldt-workflow-developing-against-sibling-source)
143
+ below. `Frontend/site/scripts/widgetic-dev-aliases.ts` is the working example.
144
+
145
+ The layout's fixtures gate it against the disk: every declared subpath target
146
+ must exist in a real checkout, so a directory rename fails a test here instead
147
+ of silently killing an alias in six apps at once. (0.1.0 shipped a stale
148
+ subpath — `design-system/previews` → a directory that no longer exists —
149
+ inherited from the hand-kept tables it replaced; this gate is what forbids the
150
+ next one.)
151
+
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 without compiling its source: `embed-sdk`,
178
+ `recorder` and `ui-sdk` link a sibling checkout by hand to its built output
179
+ instead — `lps`, `npm link`, a raw `ln -s`. The canonical sentences would be
180
+ false in their READMEs, so they are not required of them; what is required is
181
+ the retired-instruction ban, because a `npm link` instruction is as wrong in
182
+ their prose as in an adopter's. They are read by the same check for that one
183
+ rule (`LINKING_PACKAGES` in `lib/readme-contract.mjs`). They were read by
184
+ nothing before it — not the adopters' check, not a test — so drift there
185
+ failed nothing at all.
186
+
187
+ Two things keep the link era's failure mode visible, because **nothing
188
+ fails** when sibling-source development quietly stops working: the dynamic
189
+ import degrades to the warning ("@widgetic/dev-tools not resolvable —
190
+ sibling dev aliases disabled"), the app boots, and sibling packages compile
191
+ from their installed `dist/` instead of `src/` — HMR on library edits quietly
192
+ gone. The warning on the first dev-server boot is the tell — and
193
+ [the link-doctor](#the-link-doctor-checking-sibling-links-dists-and-dead-names)
194
+ below turns that manual check into a test.
195
+
196
+ Apps may still link individual siblings to iterate without publishing —
197
+ chat's idempotent `scripts/link-siblings.mjs` links its sibling peers
198
+ (dev-tools, api-sdk, design-system) from a `predev` and `prepackage:watch`
199
+ hook, and site's `lps` exists for the same purpose for its embedded
200
+ `file-browser`. Those are per-app choices about which sibling to iterate on;
201
+ they are not part of dev-tools setup, and no step here depends on them.
202
+
203
+ ### The link doctor: checking sibling links, dists, and dead names
204
+
205
+ `check-links` is the automated form of the eyeballing this section used to
206
+ describe. It walks every package in the `Frontend/` checkout and fails on
207
+ three classes of silent rot:
208
+
209
+ - **dangling `@widgetic/*` symlinks** — a link whose target no longer exists
210
+ (the rename residue `llinks` could only show you), plus links that resolve
211
+ *outside* the checkout, which shadow the sibling with a foreign copy;
212
+ - **promised `dist/` output that nobody built** — every `main`/`module`/
213
+ `svelte`/`types` entry and non-glob `exports` value must exist on disk, so
214
+ a manifest cannot promise a file a stale build no longer produces;
215
+ - **dead checkout names** — live references to `props-editor` or
216
+ `prompt-chat` in source, config, CSS or JSON. Comments, archive trees
217
+ (`__docs`/`__specs`), build output and the reporter's own rename tables are
218
+ exempt; a *live* glob, import or path still naming a deleted checkout is
219
+ the finding.
220
+
221
+ Run it from the dev-tools checkout, or from any app that has it installed:
222
+
223
+ ```sh
224
+ npm run check:links # in Frontend/dev-tools
225
+ node node_modules/@widgetic/dev-tools/bin/check-links.mjs # from any app
226
+ ```
227
+
228
+ Every failure prints the fix that repairs it, and the fixture suite
229
+ (`npx check-links-fixtures`) ships in the tarball so a consumer can watch the
230
+ guard fail in its own CI before trusting a green run.
231
+
232
+ The exemption tables live in `lib/check-links.mjs` — `EXEMPT_DEADNAME_PACKAGES`
233
+ for packages that *name* the renames as data (dev-tools itself), and
234
+ `DEFAULT_EXEMPT_FILES` for the handful of files whose dead references are
235
+ deliberate, each carrying a reason in the comment beside it. Like
236
+ `EXCEPTIONS`, they are compiled into the installed tool: adding an entry is a
237
+ change here and a release, not an edit in the consumer.
238
+
239
+ Note the asymmetry with this package's own CI: dev-tools is checked out alone
240
+ there — no `Frontend/` parent — so CI runs the fixtures, not the check. The
241
+ check itself belongs in the pipelines of the checkouts it inspects, where it
242
+ can see the siblings.
243
+
244
+ A link can also go **stale** rather than missing: a sibling rename leaves a
245
+ symlink to a directory that no longer exists, which resolves nothing while
246
+ looking installed — the site's `chat` link survived the `prompt-chat` rename
247
+ that way. If `llinks` shows an entry but the dev server still warns, check
248
+ whether the link's target exists.
249
+
250
+ That is now the only state: every app consumes the published package as a
251
+ dependency and no `ldt` step exists anywhere. The story stays because the
252
+ link-era failure modes are exactly what the link-doctor guards against — a
253
+ stale `npm link` habit or a per-app iteration script can still leave a link
254
+ that outlives its target.
76
255
 
77
256
  ### A deliberate exception
78
257
 
@@ -89,7 +268,7 @@ no longer make.
89
268
  ## Releasing
90
269
 
91
270
  Push to `main` with a new `version` in `package.json`. CI runs the check against
92
- this package, the fixtures against the check, the remap fixtures, and
271
+ this package, the fixtures against the check, the remap and layout fixtures, and
93
272
  `npm pack --dry-run`, then publishes to npm if the version is not already on the
94
273
  registry — the same shape as `@widgetic/design-system`'s and
95
274
  `@widgetic/file-browser`'s pipelines, so it uses the `NPM_TOKEN` that is already
@@ -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
+ );
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Run the frontend-layout disk-truth fixtures against the real Frontend
4
+ * checkout.
5
+ *
6
+ * The layout tests that read the sibling tree skip in this repo's CI —
7
+ * dev-tools is checked out alone there, with no `Frontend/` beside it — so
8
+ * they run for real through this bin, in a consumer whose checkout sits
9
+ * beside the siblings. Wire `test:layout` into a consumer's CI and a sibling
10
+ * rename fails *somebody's* build instead of drifting silently through six
11
+ * dev-alias tables.
12
+ *
13
+ * Same contract as `check-runtime-deps-fixtures` and `check-links-fixtures`:
14
+ * spawned rather than imported, so the output and the exit code are the
15
+ * runner's own — the only thing CI reads. The suite still runs its pure
16
+ * table-shape tests everywhere; only the disk gates need the checkout.
17
+ */
18
+
19
+ import { spawnSync } from 'node:child_process';
20
+ import { fileURLToPath } from 'node:url';
21
+
22
+ const suite = fileURLToPath(new URL('../test/frontend-layout.test.mjs', import.meta.url));
23
+
24
+ const { status } = spawnSync(process.execPath, ['--test', suite], { stdio: 'inherit' });
25
+
26
+ if (status !== 0) {
27
+ console.error(
28
+ '\n[check-layout-fixtures] the layout fixtures failed: a declared checkout, subpath target, ' +
29
+ 'or rename promise no longer matches the disk.\n' +
30
+ ' Fix the layout module or the checkout — a stale alias table kills sibling-source dev\n' +
31
+ ' in every consumer at once, silently.\n'
32
+ );
33
+ }
34
+
35
+ process.exit(status ?? 1);
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Run the fixture suite that proves `check-links` fails when it should.
4
+ *
5
+ * Same contract as `check-runtime-deps-fixtures`: the suite ships in this
6
+ * package so a consuming repository can run it against the exact version it
7
+ * installed, instead of trusting that somebody else watched the guard go red.
8
+ * `npm run test:links` in a consumer is this script, and so is the CI step.
9
+ *
10
+ * The runner is spawned rather than the suite imported, so the output and the
11
+ * exit code are the runner's own — which is the only thing CI reads.
12
+ */
13
+
14
+ import { spawnSync } from 'node:child_process';
15
+ import { fileURLToPath } from 'node:url';
16
+
17
+ const suite = fileURLToPath(new URL('../test/check-links.test.mjs', import.meta.url));
18
+
19
+ const { status } = spawnSync(process.execPath, ['--test', suite], { stdio: 'inherit' });
20
+
21
+ if (status !== 0) {
22
+ console.error(
23
+ '\n[check-links] the fixture suite failed: the check no longer fails when it should.\n' +
24
+ ' That makes a green `check-links` meaningless, so it is a failure of the check itself.\n'
25
+ );
26
+ }
27
+
28
+ process.exit(status ?? 1);
@@ -0,0 +1,80 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Does every promise the sibling links make still resolve?
4
+ *
5
+ * A Frontend checkout can break in three ways that nothing fails on, because
6
+ * each one degrades silently instead of erroring:
7
+ *
8
+ * dangling link `node_modules/@widgetic/*` is a symlink whose target no
9
+ * longer exists — a sibling was renamed or deleted without
10
+ * relinking. Worse than absent: `ls node_modules/@widgetic`
11
+ * still shows the entry, so the link *looks* installed while
12
+ * resolving nothing. The rename that created this class was
13
+ * `chat` → `prompt-chat` in the site, which kept booting fine
14
+ * with a link pointing at a checkout that was gone.
15
+ *
16
+ * missing dist a manifest promises built output (`main`, `module`,
17
+ * `svelte`, `types`, or a non-glob `exports` value) and the
18
+ * file is not on disk. Linked consumers resolve the link and
19
+ * then fail inside the sibling. This is the rule that caught
20
+ * `@widgetic/design-system` still exporting
21
+ * `./dist/components/previews/*` after the `previews`
22
+ * directory had been deleted.
23
+ *
24
+ * dead name a source or config file still names a checkout that does
25
+ * not exist (`props-editor`, `prompt-chat` — both renamed,
26
+ * both left behind as import specifiers, alias globs, ignore
27
+ * globs, an `.env` path in a runtime warning, even a README
28
+ * quickstart). A dead name in a glob resolves nothing and
29
+ * looks installed; the alias that used to say `props-editor`
30
+ * shipped that way in two consumers.
31
+ *
32
+ * Scope is the Frontend checkout this package ships in: every sibling directory
33
+ * with a `package.json`. The rules are pure data in `lib/check-links.mjs`; this
34
+ * CLI formats them and exits 1 when anything is broken. Exemptions live there —
35
+ * per-file for deliberate references, whole-table for the packages that *name*
36
+ * the renames as data (the reporter does not flag itself).
37
+ *
38
+ * The fixture suite that proves each rule fails when it should (and that its
39
+ * false-positive shapes pass) is `test/check-links.test.mjs`, shipped in the
40
+ * tarball:
41
+ *
42
+ * npx check-links-fixtures (or: npm run test:links in this repo)
43
+ */
44
+
45
+ import { collectLinkProblems } from '../lib/check-links.mjs';
46
+ import { existsSync, statSync } from 'node:fs';
47
+ import { fileURLToPath } from 'node:url';
48
+ import { resolve } from 'node:path';
49
+
50
+ // Same convention as check-runtime-deps's `[packageDir]`: an explicit checkout
51
+ // root for the fixture suite (and for auditing a checkout you are not inside),
52
+ // defaulting to the Frontend/ root this package ships in.
53
+ const argRoot = process.argv[2];
54
+ const frontendRoot = argRoot ? resolve(argRoot) : fileURLToPath(new URL('../..', import.meta.url));
55
+ if (!existsSync(frontendRoot) || !statSync(frontendRoot).isDirectory()) {
56
+ console.error(`[check-links] not a directory: ${frontendRoot}`);
57
+ process.exit(1);
58
+ }
59
+
60
+ const { packages, problems } = collectLinkProblems(frontendRoot);
61
+
62
+ if (packages.length === 0) {
63
+ console.error(`[check-links] no packages found under ${frontendRoot} — nothing to check`);
64
+ process.exit(1);
65
+ }
66
+
67
+ console.log(`[check-links] ${packages.length} packages under Frontend/`);
68
+ if (problems.length === 0) {
69
+ console.log(' OK — every @widgetic link resolves, every promised dist/ file exists, no dead checkout names.\n');
70
+ process.exit(0);
71
+ }
72
+
73
+ for (const { kind, pkg, detail, fix } of problems) {
74
+ console.error(`\n ${pkg}: ${kind}\n ${detail}\n → ${fix}`);
75
+ }
76
+ console.error(
77
+ `\n ${problems.length} broken promise${problems.length === 1 ? '' : 's'} across ` +
78
+ `${new Set(problems.map((p) => p.pkg)).size} package(s).\n`
79
+ );
80
+ process.exit(1);
@@ -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,77 @@
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 a `npm link` instruction copied back into one of their READMEs
17
+ * would have failed nothing. They carry no canonical section (they compile no
18
+ * sibling source), but they are scanned the same way.
19
+ *
20
+ * This check reads each package's README and fails when the canonical
21
+ * sibling-source sentences are missing, rewritten, or reordered, or when
22
+ * link-era instructions (`npm run ldt`, `npm link`, `volta run`, `llinks`,
23
+ * the after-install re-run, the retired `typescript-sdk` name) appear in
24
+ * prose. Fenced code blocks are exempt: quoting history is documentation,
25
+ * running it is not. The rules are pure data in `lib/readme-contract.mjs`;
26
+ * this CLI formats them and exits 1 when anything is broken.
27
+ *
28
+ * The fixture suite that proves each rule fails when it should (and that its
29
+ * false-positive shapes pass) is `test/readme-contract.test.mjs`, shipped in
30
+ * the tarball:
31
+ *
32
+ * npx check-readme-contracts-fixtures (or: npm run test:readme in this repo)
33
+ */
34
+
35
+ import { ADOPTER_PACKAGES, LINKING_PACKAGES, collectReadmeDrift } from '../lib/readme-contract.mjs';
36
+ import { existsSync, statSync } from 'node:fs';
37
+ import { fileURLToPath } from 'node:url';
38
+ import { resolve } from 'node:path';
39
+
40
+ // Same convention as check-links's `[frontendRoot]`: an explicit checkout
41
+ // root for the fixture suite (and for auditing a checkout you are not
42
+ // inside), defaulting to the Frontend/ root this package ships in.
43
+ const argRoot = process.argv[2];
44
+ const frontendRoot = argRoot ? resolve(argRoot) : fileURLToPath(new URL('../..', import.meta.url));
45
+ if (!existsSync(frontendRoot) || !statSync(frontendRoot).isDirectory()) {
46
+ console.error(`[check-readme-contracts] not a directory: ${frontendRoot}`);
47
+ process.exit(1);
48
+ }
49
+
50
+ const { packages, findings } = collectReadmeDrift(frontendRoot);
51
+
52
+ if (packages.length === 0) {
53
+ console.error(`[check-readme-contracts] no packages found — nothing to check`);
54
+ process.exit(1);
55
+ }
56
+
57
+ console.log(
58
+ `[check-readme-contracts] ${packages.length} READMEs under Frontend/` +
59
+ ` — ${ADOPTER_PACKAGES.length} adopters (canonical section required)` +
60
+ ` + ${LINKING_PACKAGES.length} linking packages (retired instructions banned)`
61
+ );
62
+ if (findings.length === 0) {
63
+ console.log(
64
+ ' OK — every adopter carries the canonical sibling-source section, in the canonical wording,\n' +
65
+ ' and no README teaches the retired link-era instructions.\n'
66
+ );
67
+ process.exit(0);
68
+ }
69
+
70
+ for (const { kind, pkg, detail, fix } of findings) {
71
+ console.error(`\n ${pkg}: ${kind}\n ${detail}\n → ${fix}`);
72
+ }
73
+ console.error(
74
+ `\n ${findings.length} drifted README${findings.length === 1 ? '' : 's'} across ` +
75
+ `${new Set(findings.map((f) => f.pkg)).size} adopter(s).\n`
76
+ );
77
+ process.exit(1);