@widgetic/dev-tools 0.1.0 → 0.2.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 +91 -0
- package/README.md +159 -5
- package/bin/check-layout-fixtures.mjs +35 -0
- package/bin/check-links-fixtures.mjs +28 -0
- package/bin/check-links.mjs +80 -0
- package/lib/check-links.d.mts +78 -0
- package/lib/check-links.mjs +349 -0
- package/lib/frontend-layout.mjs +3 -1
- package/package.json +12 -5
- package/test/check-links.test.mjs +359 -0
- package/test/frontend-layout.test.mjs +19 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
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.2.0 — 2026-09-20
|
|
7
|
+
|
|
8
|
+
### Added
|
|
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.
|
|
26
|
+
|
|
27
|
+
## 0.2.0 — 2026-09-19
|
|
28
|
+
|
|
29
|
+
The release that makes `frontend-layout.mjs` the only dev-alias table: all six
|
|
30
|
+
`Frontend/` apps that compile sibling source in dev (site, file-browser,
|
|
31
|
+
widget-creator, chat, editor, `__template__`) now build their tables from this
|
|
32
|
+
module instead of keeping hand-written copies.
|
|
33
|
+
|
|
34
|
+
### Removed
|
|
35
|
+
|
|
36
|
+
- **The `previews` design-system subpath** from `frontend-layout.mjs` — it
|
|
37
|
+
shipped in 0.1.0, inherited from the hand-kept consumer tables this module
|
|
38
|
+
replaced, and pointed at `components/previews`, a directory that no longer
|
|
39
|
+
exists and that no consumer imports. The alias every table carried resolved
|
|
40
|
+
nothing. Re-add only with a live path; the fixtures now forbid a dead one.
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- **A disk-truth gate for subpath targets** in the `frontend-layout` fixtures:
|
|
45
|
+
every declared subpath alias must point at a path that exists in a real
|
|
46
|
+
checkout, so a directory rename fails a test here instead of silently
|
|
47
|
+
killing an alias in six apps at once. (The suite already checked checkout
|
|
48
|
+
directories; this closes the subpath gap that let `previews` ship.)
|
|
49
|
+
- **`ldt` link scripts and dev-tools symlinks** in widget-creator, chat,
|
|
50
|
+
editor, and `__template__`, so every app can resolve the shared modules the
|
|
51
|
+
way site and file-browser already did.
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
|
|
55
|
+
- **widget-creator's two dead aliases**: `@widgetic/chat` → the deleted
|
|
56
|
+
`prompt-chat` checkout and `@widgetic/editor` → the deleted `props-editor`
|
|
57
|
+
checkout, surviving only because nothing imported those specifiers there.
|
|
58
|
+
The canonical layout resolves both names to their real directories.
|
|
59
|
+
- **widget-creator's inline `$lib` remap** (a fourth hand-copy, drifted toward
|
|
60
|
+
its own loop style) now uses the shared `createSiblingSrcLibPlugin`, and its
|
|
61
|
+
remap plugin only loads in dev — the gate under which it can ever fire.
|
|
62
|
+
- **The publish pipeline never ran `test:layout`** even though the layout
|
|
63
|
+
module ships in the tarball; the build stage now runs all three suites
|
|
64
|
+
before `npm pack --dry-run`. (`test:vite` had the same gap before 0.1.0.)
|
|
65
|
+
|
|
66
|
+
### Changed
|
|
67
|
+
|
|
68
|
+
- The consumers' dynamic-load degrade pattern is unchanged: where dev-tools is
|
|
69
|
+
not linked (Render/production), a config still warns and compiles no sibling
|
|
70
|
+
source — but selecting a package name the layout does not declare now throws
|
|
71
|
+
at config load. Silent fall-through to `node_modules` is how the drift
|
|
72
|
+
started; loud is the point.
|
|
73
|
+
|
|
74
|
+
## 0.1.0 — 2026-09-19
|
|
75
|
+
|
|
76
|
+
First publish. What the tarball actually contained:
|
|
77
|
+
|
|
78
|
+
- **`bin/check-runtime-deps`** (+ `check-runtime-deps-fixtures`): fails when a
|
|
79
|
+
package's manifest and its published output disagree — a `dependencies`
|
|
80
|
+
entry the output never imports (a phantom), or an import the manifest does
|
|
81
|
+
not declare (missing). Released once so per-repository copies could not
|
|
82
|
+
drift; the `EXCEPTIONS` map inside the tool is the one shared place for
|
|
83
|
+
dependencies a scanner cannot see.
|
|
84
|
+
- **`lib/vite-src-lib.mjs`**: the per-importer sibling-`$lib` Vite remap
|
|
85
|
+
shared by the site and file-browser (`createSiblingSrcLibPlugin`), with
|
|
86
|
+
types and `node --test` fixtures.
|
|
87
|
+
- **`lib/frontend-layout.mjs`** (v1): the canonical `Frontend/` sibling
|
|
88
|
+
layout — `SIBLING_PACKAGES` keyed by `@widgetic/*` name suffix, with
|
|
89
|
+
renames recorded beside the entries — plus `buildSiblingAliases`,
|
|
90
|
+
`devOptimizeExclude`, and `devSsrNoExternal`. Shipped with the stale
|
|
91
|
+
`previews` subpath inherited from the hand-kept tables (removed in 0.2.0).
|
package/README.md
CHANGED
|
@@ -8,10 +8,16 @@ the repositories that consume it cannot drift apart.
|
|
|
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
10
|
|
|
11
|
-
It also ships `lib
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
It also ships two `lib/` modules with hand-written types and their own `node --test`
|
|
12
|
+
fixtures:
|
|
13
|
+
|
|
14
|
+
- `lib/vite-src-lib.mjs` — the per-importer sibling-`$lib` Vite remap shared by
|
|
15
|
+
the site and file-browser so their copies cannot drift (`npm run test:vite`).
|
|
16
|
+
- `lib/frontend-layout.mjs` — the canonical `Frontend/` sibling layout and the
|
|
17
|
+
builder that turns it into every consumer's dev-alias tables, so a sibling
|
|
18
|
+
move or rename is a change here, not a five-repository edit
|
|
19
|
+
(`npm run test:layout`). See [Building a consumer's dev
|
|
20
|
+
aliases](#building-a-consumers-dev-aliases-libfrontend-layoutmjs) below.
|
|
15
21
|
|
|
16
22
|
## Why this is a published package
|
|
17
23
|
|
|
@@ -74,6 +80,154 @@ Load it dynamically: the package is dev-only tooling, and a consumer whose dev
|
|
|
74
80
|
server runs without it linked must degrade to a warning, not fail its config.
|
|
75
81
|
See `Frontend/site/scripts/widgetic-dev-aliases.ts` for the working example.
|
|
76
82
|
|
|
83
|
+
### Building a consumer's dev aliases
|
|
84
|
+
|
|
85
|
+
Every app under `Frontend/` can compile sibling `@widgetic/*` **source** in dev
|
|
86
|
+
instead of built `dist/` — instant HMR on a library edit. Doing that correctly
|
|
87
|
+
needs three lists that must agree: the alias table, `optimizeDeps.exclude`
|
|
88
|
+
(never prebundle what you alias — the prebundle loads while edits go to `src/`
|
|
89
|
+
and the two diverge), and `ssr.noExternal` (never externalize what you compile
|
|
90
|
+
— SSR loads the built package while the client compiles `src/`, same divergence
|
|
91
|
+
by a different mechanism).
|
|
92
|
+
|
|
93
|
+
Six apps kept those lists by hand, and they drifted. Aliases to directories
|
|
94
|
+
that no longer existed resolved nothing while the dev server kept booting —
|
|
95
|
+
Vite falls through to `node_modules` or a dangling link — which is why
|
|
96
|
+
per-entry `existsSync` fallbacks started appearing in one config after
|
|
97
|
+
another: the tables had become untrustworthy.
|
|
98
|
+
|
|
99
|
+
`frontend-layout.mjs` fixes the cause: the directory each `@widgetic/*` name
|
|
100
|
+
maps to is declared **once** (`SIBLING_PACKAGES`, with renames recorded beside
|
|
101
|
+
the entries — `editor` was `props-editor`, `chat` was `prompt-chat`), and one
|
|
102
|
+
selection produces all three artifacts:
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
const layout = await import(
|
|
106
|
+
/* @vite-ignore */ '@widgetic/dev-tools/lib/frontend-layout.mjs'
|
|
107
|
+
).catch(() => null);
|
|
108
|
+
|
|
109
|
+
const packages = ['api-sdk', 'design-system', 'cache-layer'];
|
|
110
|
+
|
|
111
|
+
resolve: {
|
|
112
|
+
alias: layout
|
|
113
|
+
? layout.buildSiblingAliases(frontendRoot, { packages })
|
|
114
|
+
: {}, // degrade, don't fail the config
|
|
115
|
+
},
|
|
116
|
+
optimizeDeps: { exclude: layout ? layout.devOptimizeExclude(packages) : [] },
|
|
117
|
+
ssr: { noExternal: layout ? layout.devSsrNoExternal(packages) : [] },
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
What stays in the consumer is **which** packages it selects — a behavior
|
|
121
|
+
choice, since aliasing a package's index to `src/` changes what the dev server
|
|
122
|
+
compiles — and nothing else. A sibling move or rename is a change here and a
|
|
123
|
+
version bump, not an edit in every app. Selecting a name the layout does not
|
|
124
|
+
declare throws at config load: an unaliased sibling silently falls through to
|
|
125
|
+
`node_modules`, and loud is the point.
|
|
126
|
+
|
|
127
|
+
`@widgetic/design-system` narrows with two options. `designSystemSubpaths`
|
|
128
|
+
picks which `@widgetic/design-system/<subpath>` aliases to emit (defaults to
|
|
129
|
+
every subpath the layout declares), and `designSystemIndex: false` keeps the
|
|
130
|
+
bare specifier resolving to the installed package — subpath aliases only, no
|
|
131
|
+
index-to-`src/` rewrite.
|
|
132
|
+
|
|
133
|
+
Load it dynamically, exactly like the remap: a bare specifier resolved through
|
|
134
|
+
`node_modules`, degrading to a warning where dev-tools is not linked (Render
|
|
135
|
+
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)
|
|
137
|
+
below. `Frontend/site/scripts/widgetic-dev-aliases.ts` is the working example.
|
|
138
|
+
|
|
139
|
+
The layout's fixtures gate it against the disk: every declared subpath target
|
|
140
|
+
must exist in a real checkout, so a directory rename fails a test here instead
|
|
141
|
+
of silently killing an alias in six apps at once. (0.1.0 shipped a stale
|
|
142
|
+
subpath — `design-system/previews` → a directory that no longer exists —
|
|
143
|
+
inherited from the hand-kept tables it replaced; this gate is what forbids the
|
|
144
|
+
next one.)
|
|
145
|
+
|
|
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 —
|
|
171
|
+
sibling dev aliases disabled"), the app boots, and sibling packages compile
|
|
172
|
+
from their installed `dist/` instead of `src/` — HMR on library edits quietly
|
|
173
|
+
gone. The warning on the first dev-server boot is the tell — and
|
|
174
|
+
[the link-doctor](#the-link-doctor-checking-sibling-links-dists-and-dead-names)
|
|
175
|
+
below turns that manual check into a test.
|
|
176
|
+
|
|
177
|
+
### The link doctor: checking sibling links, dists, and dead names
|
|
178
|
+
|
|
179
|
+
`check-links` is the automated form of the eyeballing this section used to
|
|
180
|
+
describe. It walks every package in the `Frontend/` checkout and fails on
|
|
181
|
+
three classes of silent rot:
|
|
182
|
+
|
|
183
|
+
- **dangling `@widgetic/*` symlinks** — a link whose target no longer exists
|
|
184
|
+
(the rename residue `llinks` could only show you), plus links that resolve
|
|
185
|
+
*outside* the checkout, which shadow the sibling with a foreign copy;
|
|
186
|
+
- **promised `dist/` output that nobody built** — every `main`/`module`/
|
|
187
|
+
`svelte`/`types` entry and non-glob `exports` value must exist on disk, so
|
|
188
|
+
a manifest cannot promise a file a stale build no longer produces;
|
|
189
|
+
- **dead checkout names** — live references to `props-editor` or
|
|
190
|
+
`prompt-chat` in source, config, CSS or JSON. Comments, archive trees
|
|
191
|
+
(`__docs`/`__specs`), build output and the reporter's own rename tables are
|
|
192
|
+
exempt; a *live* glob, import or path still naming a deleted checkout is
|
|
193
|
+
the finding.
|
|
194
|
+
|
|
195
|
+
Run it from the dev-tools checkout, or from an app that has it linked:
|
|
196
|
+
|
|
197
|
+
```sh
|
|
198
|
+
npm run check:links # in Frontend/dev-tools
|
|
199
|
+
node node_modules/@widgetic/dev-tools/bin/check-links.mjs # from any app
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Every failure prints the fix that repairs it, and the fixture suite
|
|
203
|
+
(`npx check-links-fixtures`) ships in the tarball so a consumer can watch the
|
|
204
|
+
guard fail in its own CI before trusting a green run.
|
|
205
|
+
|
|
206
|
+
The exemption tables live in `lib/check-links.mjs` — `EXEMPT_DEADNAME_PACKAGES`
|
|
207
|
+
for packages that *name* the renames as data (dev-tools itself), and
|
|
208
|
+
`DEFAULT_EXEMPT_FILES` for the handful of files whose dead references are
|
|
209
|
+
deliberate, each carrying a reason in the comment beside it. Like
|
|
210
|
+
`EXCEPTIONS`, they are compiled into the installed tool: adding an entry is a
|
|
211
|
+
change here and a release, not an edit in the consumer.
|
|
212
|
+
|
|
213
|
+
Note the asymmetry with this package's own CI: dev-tools is checked out alone
|
|
214
|
+
there — no `Frontend/` parent — so CI runs the fixtures, not the check. The
|
|
215
|
+
check itself belongs in the pipelines of the checkouts it inspects, where it
|
|
216
|
+
can see the siblings.
|
|
217
|
+
|
|
218
|
+
A link can also go **stale** rather than missing: a sibling rename leaves a
|
|
219
|
+
symlink to a directory that no longer exists, which resolves nothing while
|
|
220
|
+
looking installed — the site's `chat` link survived the `prompt-chat` rename
|
|
221
|
+
that way. If `llinks` shows an entry but the dev server still warns, check
|
|
222
|
+
whether the link's target exists.
|
|
223
|
+
|
|
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.
|
|
230
|
+
|
|
77
231
|
### A deliberate exception
|
|
78
232
|
|
|
79
233
|
`EXCEPTIONS` in [`bin/check-runtime-deps.mjs`](bin/check-runtime-deps.mjs) is the
|
|
@@ -89,7 +243,7 @@ no longer make.
|
|
|
89
243
|
## Releasing
|
|
90
244
|
|
|
91
245
|
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
|
|
246
|
+
this package, the fixtures against the check, the remap and layout fixtures, and
|
|
93
247
|
`npm pack --dry-run`, then publishes to npm if the version is not already on the
|
|
94
248
|
registry — the same shape as `@widgetic/design-system`'s and
|
|
95
249
|
`@widgetic/file-browser`'s pipelines, so it uses the `NPM_TOKEN` that is already
|
|
@@ -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,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the link-doctor's rules (`check-links.mjs`). Hand-written,
|
|
3
|
+
* dependency-free — same rules as `frontend-layout.d.mts` beside it.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** One problem the link-doctor found in a Frontend checkout. */
|
|
7
|
+
export interface LinkProblem {
|
|
8
|
+
/** The rule that caught it. */
|
|
9
|
+
kind: 'dangling link' | 'outside checkout' | 'missing dist' | 'dead name';
|
|
10
|
+
/** The package directory under `Frontend/` that owns the broken promise. */
|
|
11
|
+
pkg: string;
|
|
12
|
+
/** What is broken, package-relative. */
|
|
13
|
+
detail: string;
|
|
14
|
+
/** The action that repairs it. */
|
|
15
|
+
fix: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** The result of scanning one checkout. */
|
|
19
|
+
export interface LinkProblems {
|
|
20
|
+
/** Every package directory found under the root, sorted. */
|
|
21
|
+
packages: string[];
|
|
22
|
+
/** Everything broken, grouped by package in discovery order. */
|
|
23
|
+
problems: LinkProblem[];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Manifest-relative values that promise a file on disk: the classic entry
|
|
28
|
+
* fields plus every non-glob string leaf of `exports`. Source-first `.ts`
|
|
29
|
+
* contracts are skipped; `.d.ts` build artifacts are not.
|
|
30
|
+
*/
|
|
31
|
+
export declare function promisedFiles(manifest: Record<string, unknown>): string[];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Dead-name hits in one file's text, word-bounded on both sides —
|
|
35
|
+
* `prompt-chat-messages-scroll` does not match, `../prompt-chat/src/lib` does.
|
|
36
|
+
*/
|
|
37
|
+
export declare function deadNameHits(text: string): string[];
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Symlinked `@widgetic/*` entries under one package's node_modules, plus one
|
|
41
|
+
* nested level. A dangling link's target is `null`.
|
|
42
|
+
*/
|
|
43
|
+
export declare function widgeticLinks(
|
|
44
|
+
pkgDir: string
|
|
45
|
+
): { linkPath: string; target: string | null }[];
|
|
46
|
+
|
|
47
|
+
/** Options for {@link collectLinkProblems}. */
|
|
48
|
+
export interface CollectLinkProblemsOptions {
|
|
49
|
+
/**
|
|
50
|
+
* Per-package dead-name file exemptions, keyed by package directory,
|
|
51
|
+
* valued at checkout-relative paths. Defaults to
|
|
52
|
+
* `DEFAULT_EXEMPT_FILES`; the fixture suite overrides this to prove the
|
|
53
|
+
* tables are honored.
|
|
54
|
+
*/
|
|
55
|
+
exemptFiles?: Record<string, string[]>;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Collect every broken sibling promise under a Frontend checkout: dangling
|
|
60
|
+
* `@widgetic/*` symlinks, links that escape the checkout, manifest-promised
|
|
61
|
+
* files that do not exist, and live references to dead checkout names.
|
|
62
|
+
*/
|
|
63
|
+
export declare function collectLinkProblems(
|
|
64
|
+
frontendRoot: string,
|
|
65
|
+
options?: CollectLinkProblemsOptions
|
|
66
|
+
): LinkProblems;
|
|
67
|
+
|
|
68
|
+
/** The dead checkout names and their canonical replacements. */
|
|
69
|
+
export declare const DEAD_CHECKOUT_NAMES: Record<string, string>;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Packages the dead-name rule skips entirely — the reporter and its docs name
|
|
73
|
+
* the renames as data. Links and dist promises are still checked for these.
|
|
74
|
+
*/
|
|
75
|
+
export declare const EXEMPT_DEADNAME_PACKAGES: readonly string[];
|
|
76
|
+
|
|
77
|
+
/** Per-package dead-name file exemptions, keyed by package directory. */
|
|
78
|
+
export declare const DEFAULT_EXEMPT_FILES: Record<string, string[]>;
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The link-doctor's rules, as data. The CLI in `bin/check-links.mjs` formats and
|
|
3
|
+
* exits; this module decides what is broken.
|
|
4
|
+
*
|
|
5
|
+
* Everything here is injectable-root pure: `collectLinkProblems(frontendRoot)`
|
|
6
|
+
* takes the `Frontend/` checkout root and returns the problems found under it,
|
|
7
|
+
* which is what lets the fixture suite in `test/` build a throwaway checkout,
|
|
8
|
+
* break it on purpose, and assert on the result without spawning the CLI.
|
|
9
|
+
*
|
|
10
|
+
* Zero dependencies, plain ESM with hand-written JSDoc types — same rules as
|
|
11
|
+
* `frontend-layout.mjs` beside it.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
|
|
15
|
+
import { join, relative } from 'node:path';
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Checkout directories that no longer exist but are known to linger in configs,
|
|
19
|
+
* imports and CSS classnames. Keyed by the dead name; valued at the canonical
|
|
20
|
+
* replacement so the message can say what to migrate to. Every entry here is a
|
|
21
|
+
* rename that actually happened and actually left residue behind.
|
|
22
|
+
*/
|
|
23
|
+
export const DEAD_CHECKOUT_NAMES = {
|
|
24
|
+
'props-editor': '@widgetic/editor (the props-editor checkout was renamed to editor/)',
|
|
25
|
+
'prompt-chat': '@widgetic/chat (the prompt-chat checkout was renamed to chat/)'
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Packages the dead-name rule skips entirely. `dev-tools` is the reporter: its
|
|
30
|
+
* alias tables, this check's own data and its docs exist to *name* the renames
|
|
31
|
+
* (`props-editor` → `editor`, `prompt-chat` → `chat`), and flagging the
|
|
32
|
+
* reporter for knowing its history would be self-defeating. Its links and
|
|
33
|
+
* dist promises are still checked like any other package.
|
|
34
|
+
*/
|
|
35
|
+
export const EXEMPT_DEADNAME_PACKAGES = ['dev-tools'];
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Per-package file exemptions for the dead-name rule, keyed by package
|
|
39
|
+
* directory, valued at checkout-relative paths. Every entry is a claim that the
|
|
40
|
+
* reference is deliberate — kept narrow, and worded so a reviewer can verify it.
|
|
41
|
+
* The rule scans everything else, so a new dead reference cannot hide behind an
|
|
42
|
+
* old exemption.
|
|
43
|
+
*/
|
|
44
|
+
export const DEFAULT_EXEMPT_FILES = {
|
|
45
|
+
// Deprecated rollback path (its own header says so): resolvePackageLib tries
|
|
46
|
+
// the pre-rename candidates first but guards every one with existsSync and
|
|
47
|
+
// falls through to node_modules. Fix its chat fallback if the embed build is
|
|
48
|
+
// ever revived — do not copy this pattern.
|
|
49
|
+
site: ['scripts/build-creator-embed.mjs'],
|
|
50
|
+
// The PropsEditor component styles its consumers through a live
|
|
51
|
+
// `:global(.props-editor …)` wrapper classname that predates the checkout
|
|
52
|
+
// rename — an identifier the code sets and the standalone shell consumes,
|
|
53
|
+
// not a path. Renaming it is a coordinated product change, not a cleanup.
|
|
54
|
+
editor: ['src/lib/components/editors/PropsEditor.svelte']
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/** Suffixes of files worth dead-name-scanning. CSS is deliberately absent:
|
|
58
|
+
* the editor package's own component *is* styled through a `.props-editor`
|
|
59
|
+
* classname that predates the checkout rename — a selector the code sets and
|
|
60
|
+
* the app consumes — so matching dead names inside stylesheets flags live
|
|
61
|
+
* identifiers. A CSS-only dead checkout path has not occurred yet; add the
|
|
62
|
+
* suffix back with that distinction handled if one ever does. */
|
|
63
|
+
const SCANNABLE_SUFFIXES = [
|
|
64
|
+
'.ts',
|
|
65
|
+
'.tsx',
|
|
66
|
+
'.mts',
|
|
67
|
+
'.cts',
|
|
68
|
+
'.js',
|
|
69
|
+
'.mjs',
|
|
70
|
+
'.cjs',
|
|
71
|
+
'.jsx',
|
|
72
|
+
'.svelte',
|
|
73
|
+
'.html',
|
|
74
|
+
'.json',
|
|
75
|
+
'.md'
|
|
76
|
+
];
|
|
77
|
+
|
|
78
|
+
/** Basenames never worth scanning — dependency state and lock metadata. */
|
|
79
|
+
const SKIP_BASENAMES = new Set(['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']);
|
|
80
|
+
|
|
81
|
+
/** Directories never traversed: VCS state, generated output, archives. */
|
|
82
|
+
const SKIP_DIRS = new Set([
|
|
83
|
+
'.git',
|
|
84
|
+
'.svelte-kit',
|
|
85
|
+
'node_modules',
|
|
86
|
+
'dist',
|
|
87
|
+
'build',
|
|
88
|
+
'.output',
|
|
89
|
+
'coverage',
|
|
90
|
+
// The dunder convention here is for archives: `__docs`, `__specs`. They are
|
|
91
|
+
// history — guides written when the old names were current — and a rename
|
|
92
|
+
// does not reach back and rewrite its own documentation.
|
|
93
|
+
'__docs',
|
|
94
|
+
'__docs__',
|
|
95
|
+
'__specs',
|
|
96
|
+
'__specs__'
|
|
97
|
+
]);
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Comment lines are stripped from source scanning by prefix, not by parsing:
|
|
101
|
+
* a rename's documentation lives in comments (every dead name in the tree was
|
|
102
|
+
* introduced by a rename comment at least once), while a dead *path* has to be
|
|
103
|
+
* in code or a string to resolve.
|
|
104
|
+
*/
|
|
105
|
+
const COMMENT_LINE_PREFIXES = ['//', '*', '/*', '<!--'];
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Manifest-relative values that promise a file on disk: the classic entry
|
|
109
|
+
* fields plus every string leaf of `exports`. Glob patterns are skipped (a
|
|
110
|
+
* pattern cannot be missing the way a file can) and so are `.ts` values (a
|
|
111
|
+
* source-first export is a deliberate contract, not a build artifact).
|
|
112
|
+
*
|
|
113
|
+
* @param {Record<string, unknown>} manifest A parsed package.json.
|
|
114
|
+
* @returns {string[]} Manifest-relative paths, deduplicated, in declaration order.
|
|
115
|
+
*/
|
|
116
|
+
export function promisedFiles(manifest) {
|
|
117
|
+
const values = [];
|
|
118
|
+
const push = (value) => {
|
|
119
|
+
if (typeof value !== 'string') return;
|
|
120
|
+
if (!value.startsWith('./')) return;
|
|
121
|
+
if (value.includes('*')) return;
|
|
122
|
+
// Skip source-first `.ts` contracts — but not `.d.ts`, which is a build
|
|
123
|
+
// artifact like any other and exactly as missing when nobody built it.
|
|
124
|
+
if (value.endsWith('.ts') && !/\.d\.(mts|cts|ts)$/.test(value)) return;
|
|
125
|
+
values.push(value);
|
|
126
|
+
};
|
|
127
|
+
for (const field of ['main', 'module', 'svelte', 'types']) push(manifest[field]);
|
|
128
|
+
const walk = (node) => {
|
|
129
|
+
if (typeof node === 'string') push(node);
|
|
130
|
+
else if (node && typeof node === 'object') for (const child of Object.values(node)) walk(child);
|
|
131
|
+
};
|
|
132
|
+
walk(manifest.exports);
|
|
133
|
+
return [...new Set(values)];
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Dead-name hits in one file's text. Word-bounded on both sides so
|
|
138
|
+
* `prompt-chat-messages-scroll` (a live classname in the chat package) does not
|
|
139
|
+
* match `prompt-chat`, while a bare specifier, glob or `.env` path does.
|
|
140
|
+
*
|
|
141
|
+
* @param {string} text The file's contents.
|
|
142
|
+
* @returns {string[]} Dead names present, in declaration order.
|
|
143
|
+
*/
|
|
144
|
+
export function deadNameHits(text) {
|
|
145
|
+
const hits = [];
|
|
146
|
+
for (const name of Object.keys(DEAD_CHECKOUT_NAMES)) {
|
|
147
|
+
const pattern = new RegExp(`(?<![\\w-])${name}(?![\\w-])`);
|
|
148
|
+
if (pattern.test(text)) hits.push(name);
|
|
149
|
+
}
|
|
150
|
+
return hits;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** One reported problem: what kind, where, and the fix that repairs it. */
|
|
154
|
+
/**
|
|
155
|
+
* @typedef {Object} LinkProblem
|
|
156
|
+
* @property {'dangling link' | 'outside checkout' | 'missing dist' | 'dead name'} kind
|
|
157
|
+
* @property {string} pkg The package directory under Frontend/.
|
|
158
|
+
* @property {string} detail What is broken, package-relative.
|
|
159
|
+
* @property {string} fix The action that repairs it.
|
|
160
|
+
*/
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Symlinked `@widgetic/*` entries under one package's node_modules, plus one
|
|
164
|
+
* nested level (bundled/workspace deps). A dangling link's target resolves to
|
|
165
|
+
* `null` — `realpathSync` throws on exactly the condition being checked.
|
|
166
|
+
*
|
|
167
|
+
* @param {string} pkgDir The package checkout root.
|
|
168
|
+
* @returns {{linkPath: string, target: string | null}[]}
|
|
169
|
+
*/
|
|
170
|
+
export function widgeticLinks(pkgDir) {
|
|
171
|
+
const links = [];
|
|
172
|
+
const scopes = [join(pkgDir, 'node_modules', '@widgetic')];
|
|
173
|
+
const nm = join(pkgDir, 'node_modules');
|
|
174
|
+
if (existsSync(nm)) {
|
|
175
|
+
for (const entry of readdirSync(nm, { withFileTypes: true })) {
|
|
176
|
+
if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '@widgetic') continue;
|
|
177
|
+
const nested = join(nm, entry.name, 'node_modules', '@widgetic');
|
|
178
|
+
if (existsSync(nested)) scopes.push(nested);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
for (const scope of scopes) {
|
|
182
|
+
if (!existsSync(scope)) continue;
|
|
183
|
+
for (const entry of readdirSync(scope, { withFileTypes: true })) {
|
|
184
|
+
const linkPath = join(scope, entry.name);
|
|
185
|
+
let target = null;
|
|
186
|
+
try {
|
|
187
|
+
target = realpathSync(linkPath);
|
|
188
|
+
} catch {
|
|
189
|
+
// Dangling — the finding itself.
|
|
190
|
+
}
|
|
191
|
+
links.push({ linkPath, target });
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
return links;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Recursively collect scannable files under dir, honoring the skip lists.
|
|
199
|
+
*
|
|
200
|
+
* @param {string} dir Directory to walk.
|
|
201
|
+
* @param {string[]} out Accumulator.
|
|
202
|
+
* @returns {string[]}
|
|
203
|
+
*/
|
|
204
|
+
function scannableFiles(dir, out = []) {
|
|
205
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
206
|
+
if (entry.name.startsWith('.') || SKIP_BASENAMES.has(entry.name)) continue;
|
|
207
|
+
const full = join(dir, entry.name);
|
|
208
|
+
if (entry.isDirectory()) {
|
|
209
|
+
if (!SKIP_DIRS.has(entry.name)) scannableFiles(full, out);
|
|
210
|
+
} else if (SCANNABLE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix))) {
|
|
211
|
+
out.push(full);
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
return out;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Whether a file is exempt from the dead-name rule in this checkout.
|
|
219
|
+
*
|
|
220
|
+
* @param {string} pkgDir The package root.
|
|
221
|
+
* @param {string} file Absolute file path.
|
|
222
|
+
* @param {string} frontendRoot The checkout root, for package-relative keys.
|
|
223
|
+
* @param {Record<string, string[]>} exemptFiles Package → relative paths.
|
|
224
|
+
*/
|
|
225
|
+
function isExemptFile(pkgDir, file, frontendRoot, exemptFiles) {
|
|
226
|
+
const pkg = relative(frontendRoot, pkgDir);
|
|
227
|
+
const rel = relative(pkgDir, file);
|
|
228
|
+
return (exemptFiles[pkg] ?? []).includes(rel);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Collect every broken sibling promise under a Frontend checkout.
|
|
233
|
+
*
|
|
234
|
+
* @param {string} frontendRoot The `Frontend/` checkout root.
|
|
235
|
+
* @param {{exemptFiles?: Record<string, string[]>}} [options]
|
|
236
|
+
* Overrides for the exemption tables — the fixture suite uses this to prove
|
|
237
|
+
* the tables themselves are honored.
|
|
238
|
+
* @returns {{packages: string[], problems: LinkProblem[]}}
|
|
239
|
+
*/
|
|
240
|
+
export function collectLinkProblems(frontendRoot, options = {}) {
|
|
241
|
+
const exemptFiles = options.exemptFiles ?? DEFAULT_EXEMPT_FILES;
|
|
242
|
+
// Canonicalize before any comparison: realpath resolves symlinks in the root
|
|
243
|
+
// itself (macOS reports /var/... as /private/var/...), and a link target
|
|
244
|
+
// compared against an unresolved root would be misread as outside the
|
|
245
|
+
// checkout even when it lives inside it.
|
|
246
|
+
try {
|
|
247
|
+
frontendRoot = realpathSync(frontendRoot);
|
|
248
|
+
} catch {
|
|
249
|
+
// A root that cannot be resolved gets reported by the caller's own
|
|
250
|
+
// existence checks; readdirSync below fails loudly enough.
|
|
251
|
+
}
|
|
252
|
+
/** @type {LinkProblem[]} */
|
|
253
|
+
const problems = [];
|
|
254
|
+
|
|
255
|
+
const packages = readdirSync(frontendRoot, { withFileTypes: true })
|
|
256
|
+
.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
|
|
257
|
+
.map((entry) => entry.name)
|
|
258
|
+
.filter((name) => existsSync(join(frontendRoot, name, 'package.json')))
|
|
259
|
+
.sort();
|
|
260
|
+
|
|
261
|
+
for (const pkg of packages) {
|
|
262
|
+
const pkgDir = join(frontendRoot, pkg);
|
|
263
|
+
let manifest;
|
|
264
|
+
try {
|
|
265
|
+
manifest = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
|
|
266
|
+
} catch (error) {
|
|
267
|
+
problems.push({
|
|
268
|
+
kind: 'missing dist',
|
|
269
|
+
pkg,
|
|
270
|
+
detail: `package.json is not readable JSON (${error instanceof Error ? error.message : String(error)})`,
|
|
271
|
+
fix: 'repair the manifest — nothing downstream of it can be trusted while it does not parse'
|
|
272
|
+
});
|
|
273
|
+
continue;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
// Rule 1 — every @widgetic symlink resolves, and into this checkout.
|
|
277
|
+
for (const { linkPath, target } of widgeticLinks(pkgDir)) {
|
|
278
|
+
const rel = relative(pkgDir, linkPath);
|
|
279
|
+
if (!target) {
|
|
280
|
+
problems.push({
|
|
281
|
+
kind: 'dangling link',
|
|
282
|
+
pkg,
|
|
283
|
+
detail: `${rel} resolves to nothing`,
|
|
284
|
+
fix: 'relink it (npm run ldt, or recreate the symlink) after confirming the sibling checkout exists'
|
|
285
|
+
});
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
if (!existsSync(target)) {
|
|
289
|
+
problems.push({
|
|
290
|
+
kind: 'dangling link',
|
|
291
|
+
pkg,
|
|
292
|
+
detail: `${rel} → ${target} does not exist`,
|
|
293
|
+
fix: 'relink it (npm run ldt, or recreate the symlink) after confirming the sibling checkout exists'
|
|
294
|
+
});
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
if (!target.startsWith(frontendRoot)) {
|
|
298
|
+
problems.push({
|
|
299
|
+
kind: 'outside checkout',
|
|
300
|
+
pkg,
|
|
301
|
+
detail: `${rel} → ${relative(frontendRoot, target)} (outside the checkout)`,
|
|
302
|
+
fix: 'remove the link and relink to the sibling checkout — a foreign copy shadows the sibling and looks installed'
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// Rule 2 — every manifest-promised file exists.
|
|
308
|
+
for (const promised of promisedFiles(manifest)) {
|
|
309
|
+
if (existsSync(join(pkgDir, promised))) continue;
|
|
310
|
+
problems.push({
|
|
311
|
+
kind: 'missing dist',
|
|
312
|
+
pkg,
|
|
313
|
+
detail: `manifest promises ${promised} but the file does not exist`,
|
|
314
|
+
fix: 'build the package, or delete the stale export if the output is gone for good'
|
|
315
|
+
});
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
// Rule 3 — no references to dead checkout names.
|
|
319
|
+
if (EXEMPT_DEADNAME_PACKAGES.includes(pkg)) continue;
|
|
320
|
+
for (const file of scannableFiles(pkgDir)) {
|
|
321
|
+
if (isExemptFile(pkgDir, file, frontendRoot, exemptFiles)) continue;
|
|
322
|
+
const text = readFileSync(file, 'utf8');
|
|
323
|
+
const isSource = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx|svelte)$/.test(file);
|
|
324
|
+
const lines = text.split('\n');
|
|
325
|
+
// Comment-prefix stripping applies to source files only: a dead path
|
|
326
|
+
// has to be in code or a string to resolve, while documentation of the
|
|
327
|
+
// renames lives in comments and must stay scannable-exempt. Markdown,
|
|
328
|
+
// json and html are scanned whole.
|
|
329
|
+
const scanned = isSource
|
|
330
|
+
? lines
|
|
331
|
+
.filter((line) => {
|
|
332
|
+
const trimmed = line.trimStart();
|
|
333
|
+
return !COMMENT_LINE_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
|
|
334
|
+
})
|
|
335
|
+
.join('\n')
|
|
336
|
+
: text;
|
|
337
|
+
for (const name of deadNameHits(scanned)) {
|
|
338
|
+
problems.push({
|
|
339
|
+
kind: 'dead name',
|
|
340
|
+
pkg,
|
|
341
|
+
detail: `${relative(pkgDir, file)} references "${name}" — a checkout that no longer exists`,
|
|
342
|
+
fix: `migrate to ${DEAD_CHECKOUT_NAMES[name]}; delete the reference if nothing consumes it`
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
return { packages, problems };
|
|
349
|
+
}
|
package/lib/frontend-layout.mjs
CHANGED
|
@@ -60,7 +60,9 @@ export const SIBLING_PACKAGES = {
|
|
|
60
60
|
*/
|
|
61
61
|
subpaths: {
|
|
62
62
|
styles: 'styles/global.css',
|
|
63
|
-
previews
|
|
63
|
+
// `previews` (→ components/previews) was removed: the directory no
|
|
64
|
+
// longer exists and no consumer imports it — the alias every table
|
|
65
|
+
// used to carry resolved nothing. Re-add only with a live path.
|
|
64
66
|
'shad-editor': 'shad-editor',
|
|
65
67
|
components: 'components',
|
|
66
68
|
icons: 'icons',
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@widgetic/dev-tools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails),
|
|
5
|
+
"description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails), the Vite sibling-$lib remap, the canonical Frontend sibling layout that builds every consumer's dev-alias tables, and check-links — the link-doctor that fails when a sibling symlink dangles, a promised dist/ file is missing, or a dead checkout name lingers.",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://gitlab.com/widgeticai/Frontend/dev-tools.git"
|
|
@@ -16,19 +16,26 @@
|
|
|
16
16
|
},
|
|
17
17
|
"bin": {
|
|
18
18
|
"check-runtime-deps": "bin/check-runtime-deps.mjs",
|
|
19
|
-
"check-runtime-deps-fixtures": "bin/check-runtime-deps-fixtures.mjs"
|
|
19
|
+
"check-runtime-deps-fixtures": "bin/check-runtime-deps-fixtures.mjs",
|
|
20
|
+
"check-links": "bin/check-links.mjs",
|
|
21
|
+
"check-links-fixtures": "bin/check-links-fixtures.mjs",
|
|
22
|
+
"check-layout-fixtures": "bin/check-layout-fixtures.mjs"
|
|
20
23
|
},
|
|
21
24
|
"files": [
|
|
22
25
|
"bin",
|
|
23
26
|
"lib",
|
|
24
|
-
"test"
|
|
27
|
+
"test",
|
|
28
|
+
"CHANGELOG.md"
|
|
25
29
|
],
|
|
26
30
|
"scripts": {
|
|
27
31
|
"check:deps": "node bin/check-runtime-deps.mjs",
|
|
28
32
|
"test:deps": "node bin/check-runtime-deps-fixtures.mjs",
|
|
29
33
|
"test:vite": "node --test test/vite-src-lib.test.mjs",
|
|
30
34
|
"test:layout": "node --test test/frontend-layout.test.mjs",
|
|
31
|
-
"test": "
|
|
35
|
+
"test:layout:disk": "node bin/check-layout-fixtures.mjs",
|
|
36
|
+
"check:links": "node bin/check-links.mjs",
|
|
37
|
+
"test:links": "node bin/check-links-fixtures.mjs",
|
|
38
|
+
"test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links",
|
|
32
39
|
"prepublishOnly": "npm test"
|
|
33
40
|
},
|
|
34
41
|
"volta": {
|
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Does the link-doctor actually fail when a sibling promise breaks?
|
|
4
|
+
*
|
|
5
|
+
* `check-links.mjs` guards a Frontend checkout against three ways its sibling
|
|
6
|
+
* wiring can silently rot — a `@widgetic/*` symlink that resolves to nothing,
|
|
7
|
+
* a manifest that promises built output nobody built, and a source tree that
|
|
8
|
+
* still names a checkout which no longer exists. All three degrade quietly:
|
|
9
|
+
* the dev server boots, the feature is just gone. A guard nobody has watched
|
|
10
|
+
* fail is indistinguishable from one that inspects nothing.
|
|
11
|
+
*
|
|
12
|
+
* Each rule is driven here against a throwaway checkout — sibling packages
|
|
13
|
+
* written to `node_modules/@widgetic/*` links, manifests and sources that
|
|
14
|
+
* disagree on purpose — asserting on `collectLinkProblems`'s findings. The
|
|
15
|
+
* false-positive shapes matter as much as the true ones: a checker that
|
|
16
|
+
* reports the reporter's own rename history, live hyphenated classnames, or a
|
|
17
|
+
* manifest whose exports are glob patterns gets switched off within a day.
|
|
18
|
+
*
|
|
19
|
+
* Fixtures are built in the OS temp dir, never in the package: the fixture
|
|
20
|
+
* root is deliberately indistinguishable from a real Frontend checkout.
|
|
21
|
+
*
|
|
22
|
+
* Runs on the built-in test runner — no framework, no dependencies:
|
|
23
|
+
*
|
|
24
|
+
* npm run test:links (in this repo)
|
|
25
|
+
* npx check-links-fixtures (in a consumer, against what it installed)
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
|
|
29
|
+
import { spawnSync } from 'node:child_process';
|
|
30
|
+
import { tmpdir } from 'node:os';
|
|
31
|
+
import { dirname, join } from 'node:path';
|
|
32
|
+
import { fileURLToPath } from 'node:url';
|
|
33
|
+
import { after, describe, it } from 'node:test';
|
|
34
|
+
import assert from 'node:assert/strict';
|
|
35
|
+
|
|
36
|
+
import { collectLinkProblems, deadNameHits, promisedFiles } from '../lib/check-links.mjs';
|
|
37
|
+
|
|
38
|
+
const BIN = fileURLToPath(new URL('../bin/check-links.mjs', import.meta.url));
|
|
39
|
+
|
|
40
|
+
/** Every fixture this run created, so a failure cannot leave one behind. */
|
|
41
|
+
const created = [];
|
|
42
|
+
|
|
43
|
+
after(() => {
|
|
44
|
+
for (const root of created) rmSync(root, { recursive: true, force: true });
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* A minimal Frontend checkout. `packages` maps sibling directory → manifest;
|
|
49
|
+
* each gets `package.json`, and any `files`/`links` entries are materialized.
|
|
50
|
+
*
|
|
51
|
+
* `links` entries are `[pkg, name, targetDir]`: a symlink at
|
|
52
|
+
* `<pkg>/node_modules/@widgetic/<name>` → `<targetDir>`. Pass `null` as the
|
|
53
|
+
* target to build a **dangling** link — the symlink points at a checkout that
|
|
54
|
+
* is never created, which is the residue a rename leaves behind.
|
|
55
|
+
*/
|
|
56
|
+
function checkout({ packages, links = [] }) {
|
|
57
|
+
const root = mkdtempSync(join(tmpdir(), 'check-links-'));
|
|
58
|
+
created.push(root);
|
|
59
|
+
for (const [pkg, manifest] of Object.entries(packages)) {
|
|
60
|
+
const pkgDir = join(root, pkg);
|
|
61
|
+
mkdirSync(pkgDir, { recursive: true });
|
|
62
|
+
writeFileSync(join(pkgDir, 'package.json'), JSON.stringify(manifest, null, 2));
|
|
63
|
+
}
|
|
64
|
+
for (const [pkg, name, targetDir] of links) {
|
|
65
|
+
const scope = join(root, pkg, 'node_modules', '@widgetic');
|
|
66
|
+
mkdirSync(scope, { recursive: true });
|
|
67
|
+
if (targetDir === null) {
|
|
68
|
+
// Dangling by omission: the sibling was never created.
|
|
69
|
+
symlinkSync(join(root, `${name}-deleted`), join(scope, name), 'dir');
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
const target = join(root, targetDir);
|
|
73
|
+
mkdirSync(target, { recursive: true });
|
|
74
|
+
symlinkSync(target, join(scope, name), 'dir');
|
|
75
|
+
}
|
|
76
|
+
return root;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Run the CLI against a checkout root, returning what CI would read. */
|
|
80
|
+
function run(root) {
|
|
81
|
+
// Spawned, not imported: the exit code is the only thing CI reads, and the
|
|
82
|
+
// bin's default-root behavior must stay exercised alongside the pure API.
|
|
83
|
+
const result = spawnSync(process.execPath, [BIN, root], { encoding: 'utf8' });
|
|
84
|
+
return { code: result.status, output: `${result.stdout ?? ''}${result.stderr ?? ''}` };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** The problems for one fixture root, filtered by kind and/or package. */
|
|
88
|
+
function findings(root, { kind, pkg } = {}) {
|
|
89
|
+
return collectLinkProblems(root).problems.filter(
|
|
90
|
+
(p) => (kind ? p.kind === kind : true) && (pkg ? p.pkg === pkg : true)
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
describe('rule 1 — dangling @widgetic symlinks', () => {
|
|
95
|
+
it('fails when a link resolves to nothing, and names the package and link', () => {
|
|
96
|
+
const root = checkout({
|
|
97
|
+
packages: { site: { name: '@widgetic/site' } },
|
|
98
|
+
// The sibling the link points at was deleted after linking.
|
|
99
|
+
links: [['site', 'editor', null]]
|
|
100
|
+
});
|
|
101
|
+
const [problem] = findings(root, { kind: 'dangling link', pkg: 'site' });
|
|
102
|
+
assert.ok(problem, 'a dangling link must be reported');
|
|
103
|
+
assert.match(problem.detail, /node_modules\/@widgetic\/editor/);
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
it('reports which links resolve, so a clean run is not an inspecting-nothing run', () => {
|
|
107
|
+
const root = checkout({
|
|
108
|
+
packages: { site: { name: '@widgetic/site' }, chat: { name: '@widgetic/chat' } },
|
|
109
|
+
links: [['site', 'chat', 'chat']]
|
|
110
|
+
});
|
|
111
|
+
const links = collectLinkProblems(root).problems.filter((p) => p.kind === 'dangling link');
|
|
112
|
+
assert.equal(links.length, 0, 'a resolving sibling link is not a finding');
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
it('fails when a link resolves outside the checkout', () => {
|
|
116
|
+
const root = checkout({ packages: { site: { name: '@widgetic/site' } } });
|
|
117
|
+
const scope = join(root, 'site', 'node_modules', '@widgetic');
|
|
118
|
+
mkdirSync(scope, { recursive: true });
|
|
119
|
+
symlinkSync(tmpdir(), join(scope, 'chat'), 'dir');
|
|
120
|
+
const [problem] = findings(root, { kind: 'outside checkout' });
|
|
121
|
+
assert.ok(problem, 'a link escaping the checkout must be reported');
|
|
122
|
+
});
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
describe('rule 2 — manifest-promised dist output', () => {
|
|
126
|
+
it('fails when a promised main/module/svelte/types file does not exist', () => {
|
|
127
|
+
const root = checkout({
|
|
128
|
+
packages: {
|
|
129
|
+
editor: {
|
|
130
|
+
name: '@widgetic/editor',
|
|
131
|
+
main: './dist/index.js',
|
|
132
|
+
module: './dist/index.js',
|
|
133
|
+
svelte: './dist/index.js',
|
|
134
|
+
types: './dist/index.d.ts'
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
});
|
|
138
|
+
const problems = findings(root, { kind: 'missing dist', pkg: 'editor' });
|
|
139
|
+
// Three fields promise the same file (deduplicated to one promise) plus
|
|
140
|
+
// the types entry — two distinct files, both missing.
|
|
141
|
+
assert.equal(problems.length, 2);
|
|
142
|
+
assert.match(problems[0].detail, /dist\/index\.js/);
|
|
143
|
+
assert.match(problems[1].detail, /dist\/index\.d\.ts/);
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
it('fails for a missing non-glob exports value', () => {
|
|
147
|
+
const root = checkout({
|
|
148
|
+
packages: {
|
|
149
|
+
'design-system': {
|
|
150
|
+
name: '@widgetic/design-system',
|
|
151
|
+
exports: {
|
|
152
|
+
'.': { import: './dist/index.js' },
|
|
153
|
+
'./previews': { import: './dist/components/previews/index.js' }
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
});
|
|
158
|
+
mkdirSync(join(root, 'design-system', 'dist'), { recursive: true });
|
|
159
|
+
writeFileSync(join(root, 'design-system', 'dist', 'index.js'), 'export {}');
|
|
160
|
+
const problems = findings(root, { kind: 'missing dist', pkg: 'design-system' });
|
|
161
|
+
assert.equal(problems.length, 1, 'only the previews export is unbuilt');
|
|
162
|
+
assert.match(problems[0].detail, /previews/);
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
it('does not flag glob exports or source-first .ts exports', () => {
|
|
166
|
+
const root = checkout({
|
|
167
|
+
packages: {
|
|
168
|
+
canvas: {
|
|
169
|
+
name: '@widgetic/canvas',
|
|
170
|
+
main: './dist/index.js',
|
|
171
|
+
types: './src/index.ts',
|
|
172
|
+
exports: {
|
|
173
|
+
'.': { types: './src/index.ts', import: './dist/index.js' },
|
|
174
|
+
'./icons/*': './dist/icons/*.js',
|
|
175
|
+
'./package.json': './package.json'
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
});
|
|
180
|
+
mkdirSync(join(root, 'canvas', 'dist'), { recursive: true });
|
|
181
|
+
writeFileSync(join(root, 'canvas', 'dist', 'index.js'), 'export {}');
|
|
182
|
+
const problems = findings(root, { kind: 'missing dist' });
|
|
183
|
+
assert.deepEqual(problems, [], 'globs, .ts contracts and existing files are not promises broken');
|
|
184
|
+
});
|
|
185
|
+
});
|
|
186
|
+
|
|
187
|
+
describe('rule 3 — dead checkout names', () => {
|
|
188
|
+
it('fails in source code, naming the file and the replacement', () => {
|
|
189
|
+
const root = checkout({
|
|
190
|
+
packages: { site: { name: '@widgetic/site' } }
|
|
191
|
+
});
|
|
192
|
+
writeFileSync(
|
|
193
|
+
join(root, 'site', 'vite.config.ts'),
|
|
194
|
+
["import { defineConfig } from 'vite';", "const ignore = ['**/props-editor/dist/**'];"].join('\n')
|
|
195
|
+
);
|
|
196
|
+
const [problem] = findings(root, { kind: 'dead name', pkg: 'site' });
|
|
197
|
+
assert.ok(problem, 'a live dead glob must be reported');
|
|
198
|
+
assert.match(problem.fix, /@widgetic\/editor/);
|
|
199
|
+
});
|
|
200
|
+
|
|
201
|
+
it('fails in config JSON and other non-source files, not only imports', () => {
|
|
202
|
+
const root = checkout({
|
|
203
|
+
packages: { chat: { name: '@widgetic/chat' } }
|
|
204
|
+
});
|
|
205
|
+
writeFileSync(join(root, 'chat', 'conf.json'), '{"dir": "props-editor"}\n');
|
|
206
|
+
writeFileSync(join(root, 'chat', 'README.md'), 'Run the app from Frontend/prompt-chat/.\n');
|
|
207
|
+
const problems = findings(root, { kind: 'dead name' });
|
|
208
|
+
assert.equal(problems.length, 2, 'JSON and markdown carry dead paths too');
|
|
209
|
+
});
|
|
210
|
+
|
|
211
|
+
it('does not flag live hyphenated identifiers that merely contain a dead name', () => {
|
|
212
|
+
const root = checkout({
|
|
213
|
+
packages: { chat: { name: '@widgetic/chat' } }
|
|
214
|
+
});
|
|
215
|
+
writeFileSync(
|
|
216
|
+
join(root, 'chat', 'names.ts'),
|
|
217
|
+
"export const MESSAGES_CLASS = 'prompt-chat-messages-scroll';\n"
|
|
218
|
+
);
|
|
219
|
+
assert.deepEqual(findings(root, { kind: 'dead name' }), [], 'prompt-chat-messages is a live identifier');
|
|
220
|
+
});
|
|
221
|
+
|
|
222
|
+
it('leaves CSS stylesheets unscanned — their identifiers are live contracts', () => {
|
|
223
|
+
const root = checkout({
|
|
224
|
+
packages: { editor: { name: '@widgetic/editor' } }
|
|
225
|
+
});
|
|
226
|
+
writeFileSync(
|
|
227
|
+
join(root, 'editor', 'component.css'),
|
|
228
|
+
':global(.props-editor) { overflow: hidden }\n'
|
|
229
|
+
);
|
|
230
|
+
assert.deepEqual(
|
|
231
|
+
findings(root, { kind: 'dead name' }),
|
|
232
|
+
[],
|
|
233
|
+
'.props-editor is the PropsEditor wrapper classname, not a checkout path'
|
|
234
|
+
);
|
|
235
|
+
});
|
|
236
|
+
|
|
237
|
+
it('strips comment lines from source, so documenting a rename is not a violation', () => {
|
|
238
|
+
const root = checkout({
|
|
239
|
+
packages: { 'widget-creator': { name: '@widgetic/creator' } }
|
|
240
|
+
});
|
|
241
|
+
writeFileSync(
|
|
242
|
+
join(root, 'widget-creator', 'vite.config.ts'),
|
|
243
|
+
[
|
|
244
|
+
'// The hand-kept table drifted onto two dead paths (prompt-chat, props-editor).',
|
|
245
|
+
'/* block * props-editor */',
|
|
246
|
+
'const dead = 0; // trailing props-editor comment stays exempt',
|
|
247
|
+
'const live = "props-editor";'
|
|
248
|
+
].join('\n')
|
|
249
|
+
);
|
|
250
|
+
const problems = findings(root, { kind: 'dead name' });
|
|
251
|
+
assert.equal(problems.length, 1, 'only the live string remains scannable');
|
|
252
|
+
assert.match(problems[0].detail, /vite\.config\.ts/);
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
it('skips archive trees (__docs, __specs) and build output', () => {
|
|
256
|
+
const root = checkout({
|
|
257
|
+
packages: { site: { name: '@widgetic/site' } }
|
|
258
|
+
});
|
|
259
|
+
mkdirSync(join(root, 'site', '__docs'), { recursive: true });
|
|
260
|
+
mkdirSync(join(root, 'site', 'build', 'client'), { recursive: true });
|
|
261
|
+
writeFileSync(join(root, 'site', '__docs', 'history.md'), 'props-editor was renamed.\n');
|
|
262
|
+
writeFileSync(join(root, 'site', 'build', 'client', 'bundle.js'), 'props-editor\n');
|
|
263
|
+
assert.deepEqual(findings(root, { kind: 'dead name' }), [], 'history and build output are not live references');
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
it('skips the reporter package (dev-tools) — it names the renames as data', () => {
|
|
267
|
+
const root = checkout({
|
|
268
|
+
packages: {
|
|
269
|
+
'dev-tools': {
|
|
270
|
+
name: '@widgetic/dev-tools',
|
|
271
|
+
main: './dist/index.js'
|
|
272
|
+
},
|
|
273
|
+
site: { name: '@widgetic/site' }
|
|
274
|
+
}
|
|
275
|
+
});
|
|
276
|
+
mkdirSync(join(root, 'dev-tools', 'lib'), { recursive: true });
|
|
277
|
+
writeFileSync(join(root, 'dev-tools', 'lib', 'check-links.mjs'), 'const DEAD = { "props-editor": 1 };\n');
|
|
278
|
+
writeFileSync(join(root, 'site', 'vite.config.ts'), 'const ignore = ["prompt-chat"];');
|
|
279
|
+
const problems = findings(root, { kind: 'dead name' });
|
|
280
|
+
assert.equal(problems.length, 1, 'dev-tools is exempt; site is not');
|
|
281
|
+
assert.equal(problems[0].pkg, 'site');
|
|
282
|
+
});
|
|
283
|
+
|
|
284
|
+
it('honors per-package file exemptions but scans everything else in the package', () => {
|
|
285
|
+
const root = checkout({
|
|
286
|
+
packages: { site: { name: '@widgetic/site' } }
|
|
287
|
+
});
|
|
288
|
+
mkdirSync(join(root, 'site', 'scripts'), { recursive: true });
|
|
289
|
+
writeFileSync(join(root, 'site', 'scripts', 'build-creator-embed.mjs'), 'const c = "../prompt-chat/src/lib";\n');
|
|
290
|
+
writeFileSync(join(root, 'site', 'vite.config.ts'), 'const ignore = ["prompt-chat"];');
|
|
291
|
+
const { problems } = collectLinkProblems(root, {
|
|
292
|
+
exemptFiles: { site: ['scripts/build-creator-embed.mjs'] }
|
|
293
|
+
});
|
|
294
|
+
const dead = problems.filter((p) => p.kind === 'dead name');
|
|
295
|
+
assert.equal(dead.length, 1, 'the exempt file is skipped; the rest of the package is not');
|
|
296
|
+
assert.match(dead[0].detail, /vite\.config\.ts/);
|
|
297
|
+
});
|
|
298
|
+
});
|
|
299
|
+
|
|
300
|
+
describe('the CLI', () => {
|
|
301
|
+
it('exits 0 with a summary when the checkout is clean', () => {
|
|
302
|
+
const root = checkout({
|
|
303
|
+
packages: {
|
|
304
|
+
editor: { name: '@widgetic/editor', main: './dist/index.js' },
|
|
305
|
+
site: { name: '@widgetic/site' }
|
|
306
|
+
},
|
|
307
|
+
links: [['site', 'editor', 'editor']]
|
|
308
|
+
});
|
|
309
|
+
mkdirSync(dirname(join(root, 'editor', 'dist', 'index.js')), { recursive: true });
|
|
310
|
+
writeFileSync(join(root, 'editor', 'dist', 'index.js'), 'export {}');
|
|
311
|
+
const { code, output } = run(root);
|
|
312
|
+
assert.equal(code, 0, output);
|
|
313
|
+
assert.match(output, /2 packages/);
|
|
314
|
+
assert.match(output, /OK/);
|
|
315
|
+
});
|
|
316
|
+
|
|
317
|
+
it('exits 1 and prints the fix when anything is broken', () => {
|
|
318
|
+
const root = checkout({
|
|
319
|
+
packages: { site: { name: '@widgetic/site' }, editor: { name: '@widgetic/editor', main: './dist/index.js' } },
|
|
320
|
+
links: [['site', 'editor', null]]
|
|
321
|
+
});
|
|
322
|
+
const { code, output } = run(root);
|
|
323
|
+
assert.equal(code, 1);
|
|
324
|
+
assert.match(output, /dangling link/);
|
|
325
|
+
assert.match(output, /missing dist/);
|
|
326
|
+
assert.match(output, /npm run ldt/);
|
|
327
|
+
});
|
|
328
|
+
|
|
329
|
+
it('exits 1 when the root holds no packages', () => {
|
|
330
|
+
const root = mkdtempSync(join(tmpdir(), 'check-links-empty-'));
|
|
331
|
+
created.push(root);
|
|
332
|
+
const { code, output } = run(root);
|
|
333
|
+
assert.equal(code, 1);
|
|
334
|
+
assert.match(output, /no packages found/);
|
|
335
|
+
});
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
describe('unit shapes', () => {
|
|
339
|
+
it('promisedFiles skips globs and .ts, dedupes, and walks exports', () => {
|
|
340
|
+
const manifest = {
|
|
341
|
+
main: './dist/index.js',
|
|
342
|
+
module: './dist/index.js',
|
|
343
|
+
types: './src/index.ts',
|
|
344
|
+
exports: {
|
|
345
|
+
'.': './dist/index.js',
|
|
346
|
+
'./icons/*': './dist/icons/*.js',
|
|
347
|
+
'./package.json': './package.json'
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
assert.deepEqual(promisedFiles(manifest), ['./dist/index.js', './package.json']);
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
it('deadNameHits is word-bounded on both sides', () => {
|
|
354
|
+
assert.deepEqual(deadNameHits('import "../prompt-chat/src/lib"'), ['prompt-chat']);
|
|
355
|
+
assert.deepEqual(deadNameHits('.prompt-chat-messages-scroll {}'), []);
|
|
356
|
+
assert.deepEqual(deadNameHits('Frontend/props-editor/.env'), ['props-editor']);
|
|
357
|
+
assert.deepEqual(deadNameHits('nothing here'), []);
|
|
358
|
+
});
|
|
359
|
+
});
|
|
@@ -23,7 +23,6 @@ test('the design-system table expands to every subpath plus the index', () => {
|
|
|
23
23
|
'@widgetic/design-system/components',
|
|
24
24
|
'@widgetic/design-system/fonts',
|
|
25
25
|
'@widgetic/design-system/icons',
|
|
26
|
-
'@widgetic/design-system/previews',
|
|
27
26
|
'@widgetic/design-system/shad-editor',
|
|
28
27
|
'@widgetic/design-system/stores',
|
|
29
28
|
'@widgetic/design-system/styles'
|
|
@@ -107,14 +106,31 @@ test('the exclude and noExternal lists mirror the selection', () => {
|
|
|
107
106
|
* The layout truth on disk: every declared directory must exist, and the
|
|
108
107
|
* renamed-away ones must not come back. This is the pin that keeps a future
|
|
109
108
|
* sibling move a one-file change here instead of a silent five-repo drift.
|
|
109
|
+
*
|
|
110
|
+
* These gates need the real `Frontend/` checkout beside this package — which
|
|
111
|
+
* this repo's own CI does not have (it checks out dev-tools alone), so they
|
|
112
|
+
* skip there and run for real through `check-layout-fixtures` in a consumer,
|
|
113
|
+
* whose CI *does* sit beside the siblings.
|
|
110
114
|
*/
|
|
111
|
-
test('every declared checkout directory exists under Frontend/', () => {
|
|
115
|
+
test('every declared checkout directory exists under Frontend/', { skip: !existsSync(join(FRONTEND, 'api-sdk')) ? 'requires the Frontend/ sibling checkout (run check-layout-fixtures in a consumer)' : false }, () => {
|
|
112
116
|
for (const pkg of Object.values(SIBLING_PACKAGES)) {
|
|
113
117
|
assert.ok(existsSync(join(FRONTEND, pkg.dir)), `missing checkout: ${pkg.dir}`);
|
|
114
118
|
}
|
|
115
119
|
});
|
|
116
120
|
|
|
117
|
-
test('the
|
|
121
|
+
test('every declared subpath target exists inside its lib tree', { skip: !existsSync(join(FRONTEND, 'api-sdk')) ? 'requires the Frontend/ sibling checkout (run check-layout-fixtures in a consumer)' : false }, () => {
|
|
122
|
+
for (const [name, pkg] of Object.entries(SIBLING_PACKAGES)) {
|
|
123
|
+
if (!pkg.lib || !pkg.subpaths) continue;
|
|
124
|
+
for (const [suffix, target] of Object.entries(pkg.subpaths)) {
|
|
125
|
+
assert.ok(
|
|
126
|
+
existsSync(join(FRONTEND, pkg.dir, pkg.lib, target)),
|
|
127
|
+
`${name} subpath '${suffix}' -> ${target} does not exist`
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
test('the renamed-away checkouts stay gone', { skip: !existsSync(join(FRONTEND, 'api-sdk')) ? 'requires the Frontend/ sibling checkout (run check-layout-fixtures in a consumer)' : false }, () => {
|
|
118
134
|
assert.ok(!existsSync(join(FRONTEND, 'props-editor')));
|
|
119
135
|
assert.ok(!existsSync(join(FRONTEND, 'prompt-chat')));
|
|
120
136
|
});
|