@widgetic/dev-tools 0.2.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 CHANGED
@@ -3,28 +3,50 @@
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.2.0 — 2026-09-20
6
+ ## 0.3.0 — 2026-09-22
7
7
 
8
8
  ### Added
9
9
 
10
- - **`check-links`, the link-doctor** the `ldt` workflow section promised: a
11
- check that fails when any Frontend package carries a dangling
12
- `@widgetic/*` symlink (or one resolving outside the checkout), a
13
- manifest-promised file that nobody built (`main`/`module`/`svelte`/`types`
14
- and non-glob `exports` values), or a live reference to a dead checkout name
15
- (`props-editor`, `prompt-chat`). Comments, `__docs`/`__specs` archives,
16
- build output and live hyphenated identifiers (`.prompt-chat-messages-*`)
17
- are exempt; dev-tools itself is exempt from the dead-name rule because it
18
- names the renames as data. Ships with its own fixture bin
19
- (`check-links-fixtures`) proving every rule fails and every false-positive
20
- shape passes, plus hand-written `.d.mts` types. Its first real-tree run
21
- caught `@widgetic/design-system` still exporting the deleted
22
- `./dist/components/previews/*` and the site's watcher ignoring
23
- `prompt-chat/dist` and `props-editor/dist` — globs that resolve nothing
24
- while the chat/editor dist writes they were meant to ignore now reach the
25
- dev server.
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
26
35
 
27
- ## 0.2.0 — 2026-09-19
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
28
50
 
29
51
  The release that makes `frontend-layout.mjs` the only dev-alias table: all six
30
52
  `Frontend/` apps that compile sibling source in dev (site, file-browser,
@@ -41,6 +63,22 @@ module instead of keeping hand-written copies.
41
63
 
42
64
  ### Added
43
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.
44
82
  - **A disk-truth gate for subpath targets** in the `frontend-layout` fixtures:
45
83
  every declared subpath alias must point at a path that exists in a real
46
84
  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 linked must degrade to a warning, not fail its config.
81
- 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.
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-linking-dev-tools-into-an-app)
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,57 @@ 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: linking dev-tools into an app
147
-
148
- For the apps that compile sibling source, the two `import()`s above resolve
149
- through `node_modules` — and on a fresh clone there is nothing to resolve.
150
- Most apps deliberately declare **no** manifest dependency on dev-tools (Render
151
- installs devDependencies too, and an entry the registry could not satisfy
152
- would break every deploy), so the `node_modules/@widgetic/dev-tools` entry is
153
- created by hand. That is the `ldt` script, and it must be re-run **after every
154
- `npm run i`**: an install rebuilds `node_modules` and prunes the link as an
155
- unowned extra.
156
-
157
- ```sh
158
- npm run i
159
- npm run ldt # node_modules/@widgetic/dev-tools -> ../../../dev-tools
160
- npm run llinks # verify — where the app has the script
161
- ```
162
-
163
- Two flavors exist across the apps and both produce the same symlink:
164
- `volta run npm link --save @widgetic/dev-tools` (site, chat, widget-creator,
165
- `__template__` — volta pins the npm version the link runs under) and plain
166
- `npm link @widgetic/dev-tools` (editor). The `--save` is historical: the
167
- manifest is supposed to stay clean, per the Render reason above.
168
-
169
- What forgetting looks like is the dangerous part: **nothing fails**. The
170
- dynamic import degrades to the warning ("@widgetic/dev-tools not resolvable —
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 —
171
190
  sibling dev aliases disabled"), the app boots, and sibling packages compile
172
191
  from their installed `dist/` instead of `src/` — HMR on library edits quietly
173
192
  gone. The warning on the first dev-server boot is the tell — and
174
193
  [the link-doctor](#the-link-doctor-checking-sibling-links-dists-and-dead-names)
175
194
  below turns that manual check into a test.
176
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
+
177
203
  ### The link doctor: checking sibling links, dists, and dead names
178
204
 
179
205
  `check-links` is the automated form of the eyeballing this section used to
@@ -192,7 +218,7 @@ three classes of silent rot:
192
218
  exempt; a *live* glob, import or path still naming a deleted checkout is
193
219
  the finding.
194
220
 
195
- Run it from the dev-tools checkout, or from an app that has it linked:
221
+ Run it from the dev-tools checkout, or from any app that has it installed:
196
222
 
197
223
  ```sh
198
224
  npm run check:links # in Frontend/dev-tools
@@ -221,12 +247,11 @@ looking installed — the site's `chat` link survived the `prompt-chat` rename
221
247
  that way. If `llinks` shows an entry but the dev server still warns, check
222
248
  whether the link's target exists.
223
249
 
224
- The third state is the destination, not a workaround: once 0.1.0 published,
225
- an app may adopt a real dependency (`file-browser` already consumes the
226
- published package this way, no link involved) and drop the `ldt` step. That
227
- is a per-app decision — the link keeps local sibling-source development
228
- working without touching deploy behavior — but every app that keeps linking
229
- keeps owing the after-`npm run i` re-run.
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.
230
255
 
231
256
  ### A deliberate exception
232
257
 
@@ -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
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,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);
@@ -0,0 +1,193 @@
1
+ /**
2
+ * The lockfile-peers rule, as data — the CLI in `bin/check-design-system-peers.mjs`
3
+ * formats and exits, this module decides what is broken.
4
+ *
5
+ * `@widgetic/design-system` has exactly two sibling-app consumers that resolve
6
+ * it from the registry — `canvas` and `file-browser` — and a range alone cannot
7
+ * keep them coordinated: both declare `^0.5.12`, nothing forces the two
8
+ * lockfiles to move together, and when 0.5.14 published, canvas's lockfile
9
+ * refreshed to it while file-browser's kept promising 0.5.12. Nothing failed —
10
+ * both resolutions satisfy the same range — but the two consumers now pin
11
+ * different component trees, so a shared screen renders with two different
12
+ * designs depending on which app hosts it, and nobody would ever connect the
13
+ * symptom to the split. The fix is the same discipline the README contract
14
+ * enforces for publish prose: the bump lands as one coordinated change, and a
15
+ * machine check fails when it does not.
16
+ *
17
+ * Two rules:
18
+ *
19
+ * version-divergence the peers' lockfiles must resolve the *same*
20
+ * design-system version. "Both satisfy the range" is not
21
+ * the bar; the bar is the same bar.
22
+ *
23
+ * stale-manifest each peer's manifest range must admit the version the
24
+ * design-system checkout carries. This fires when a
25
+ * release leaves the declared range (a 0.6.0 across a
26
+ * `^0.5.12`); npm's caret semantics silently admit
27
+ * every minor, so the range alone can never force the
28
+ * bump.
29
+ *
30
+ * checkout-sync the peers' lockfiles must resolve the version the
31
+ * design-system checkout carries. This is the rule
32
+ * that fires at *every* publish — a version bump in the
33
+ * checkout goes red in both peers until the coordinated
34
+ * lockfile refresh lands, because a caret range would
35
+ * otherwise admit the new version and nothing would
36
+ * force anyone to move.
37
+ *
38
+ * Zero dependencies, plain ESM, injectable-root pure: every function takes the
39
+ * `Frontend/` checkout root, so the fixture suite builds a throwaway checkout,
40
+ * breaks it on purpose, and asserts on the result without touching the real
41
+ * one.
42
+ */
43
+
44
+ /** The package whose coordination is guarded, unscoped and scoped. */
45
+ export const PACKAGE = 'design-system';
46
+ export const SCOPED = `@widgetic/${PACKAGE}`;
47
+
48
+ /** The sibling apps that resolve the package from the registry, as lockfile pairs. */
49
+ export const PEERS = ['canvas', 'file-browser'];
50
+
51
+ /** The checkout whose version the peers' ranges must admit. */
52
+ export const SOURCE_PACKAGE = 'design-system';
53
+
54
+ import { satisfies } from './semver-lite.mjs';
55
+
56
+ /** Minimal JSON reader that returns `null` instead of throwing. */
57
+ export function readJson(path) {
58
+ try {
59
+ return JSON.parse(readFile(path));
60
+ } catch {
61
+ return null;
62
+ }
63
+ }
64
+
65
+ import { readFileSync as readFile } from 'node:fs';
66
+
67
+ /**
68
+ * The design-system version one peer's lockfile resolves, or `undefined`.
69
+ *
70
+ * @param {string} root The Frontend checkout root.
71
+ * @param {string} pkg The peer's directory name.
72
+ * @returns {string | undefined}
73
+ */
74
+ export function lockResolved(root, pkg) {
75
+ const lock = readJson(`${root}/${pkg}/package-lock.json`);
76
+ return lock?.packages?.[`node_modules/${SCOPED}`]?.version;
77
+ }
78
+
79
+ /**
80
+ * The design-system range one peer's manifest admits, or `undefined` when the
81
+ * manifest does not declare the dependency at all.
82
+ *
83
+ * @param {string} root The Frontend checkout root.
84
+ * @param {string} pkg The peer's directory name.
85
+ * @returns {string | undefined}
86
+ */
87
+ export function admittedRange(root, pkg) {
88
+ const manifest = readJson(`${root}/${pkg}/package.json`);
89
+ const deps = manifest?.dependencies ?? {};
90
+ return deps[SCOPED];
91
+ }
92
+
93
+ /**
94
+ * The version the design-system checkout itself carries.
95
+ *
96
+ * @param {string} root The Frontend checkout root.
97
+ * @returns {string | undefined}
98
+ */
99
+ export function checkoutVersion(root) {
100
+ return readJson(`${root}/${SOURCE_PACKAGE}/package.json`)?.version;
101
+ }
102
+
103
+ /**
104
+ * Find every lockfile-peers violation under `root`.
105
+ *
106
+ * @param {string} root The Frontend checkout root.
107
+ * @returns {{ kind: 'unreadable' | 'unresolved' | 'version-divergence' | 'stale-manifest' | 'checkout-sync', pkg: string, detail: string, fix: string }[]}
108
+ */
109
+ export function collectPeersProblems(root) {
110
+ const problems = [];
111
+ const resolved = new Map();
112
+
113
+ for (const pkg of PEERS) {
114
+ const lock = readJson(`${root}/${pkg}/package-lock.json`);
115
+ if (!lock) {
116
+ problems.push({
117
+ kind: 'unreadable',
118
+ pkg,
119
+ detail: 'no readable package-lock.json',
120
+ fix: `run npm install in ${pkg}/ so the lockfile exists`
121
+ });
122
+ continue;
123
+ }
124
+ const version = lockResolved(root, pkg);
125
+ if (!version) {
126
+ problems.push({
127
+ kind: 'unresolved',
128
+ pkg,
129
+ detail: `the lockfile has no node_modules/${SCOPED} entry`,
130
+ fix: `run npm install in ${pkg}/ so ${SCOPED} resolves into the lockfile`
131
+ });
132
+ continue;
133
+ }
134
+ resolved.set(pkg, version);
135
+ }
136
+
137
+ // Divergence needs at least two healthy resolutions to compare.
138
+ const versions = [...new Set(resolved.values())];
139
+ if (versions.length > 1) {
140
+ const detail = PEERS.filter((p) => resolved.has(p))
141
+ .map((p) => `${p} ${resolved.get(p)}`)
142
+ .join(', ');
143
+ problems.push({
144
+ kind: 'version-divergence',
145
+ pkg: PEERS.join(' + '),
146
+ detail: `the peers' lockfiles resolve different ${SCOPED} versions: ${detail}`,
147
+ fix: `bump/refresh both lockfiles as one coordinated change — run npm update ${SCOPED} in each peer, land them as one commit pair`
148
+ });
149
+ }
150
+
151
+ const checkout = checkoutVersion(root);
152
+ if (checkout) {
153
+ for (const pkg of PEERS) {
154
+ const version = resolved.get(pkg);
155
+ if (version && version !== checkout) {
156
+ problems.push({
157
+ kind: 'checkout-sync',
158
+ pkg,
159
+ detail: `the design-system checkout carries ${checkout} but ${pkg}'s lockfile resolves ${version}`,
160
+ fix: `run npm update ${SCOPED} in ${pkg}/ and land both peers' lockfiles as one coordinated commit with the design-system release`
161
+ });
162
+ }
163
+ const range = admittedRange(root, pkg);
164
+ if (range === undefined) continue;
165
+ if (!satisfies(checkout, range)) {
166
+ problems.push({
167
+ kind: 'stale-manifest',
168
+ pkg,
169
+ detail: `the manifest range ${range} does not admit the design-system checkout version ${checkout}`,
170
+ fix: `bump ${SCOPED} in ${pkg}/package.json to admit ${checkout} and refresh its lockfile — together with the other peer`
171
+ });
172
+ }
173
+ }
174
+ }
175
+
176
+ return problems;
177
+ }
178
+
179
+ /**
180
+ * Render problems the way the other dev-tools checks do: one indented
181
+ * finding with its fix, ready to paste into a terminal.
182
+ *
183
+ * @param {ReturnType<typeof collectPeersProblems>} problems
184
+ * @returns {string}
185
+ */
186
+ export function formatPeersProblems(problems) {
187
+ return problems
188
+ .map(
189
+ ({ kind, pkg, detail, fix }) =>
190
+ ` ${pkg}: ${kind}\n ${detail}\n → ${fix}`
191
+ )
192
+ .join('\n');
193
+ }