@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 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/vite-src-lib.mjs` — the per-importer sibling-`$lib` Vite
12
- remap shared by the site and file-browser so their copies cannot drift — with
13
- types in `lib/vite-src-lib.d.mts` and its own `node --test` fixtures
14
- (`npm run test:vite`).
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
+ }
@@ -60,7 +60,9 @@ export const SIBLING_PACKAGES = {
60
60
  */
61
61
  subpaths: {
62
62
  styles: 'styles/global.css',
63
- previews: 'components/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.1.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), and the Vite sibling-$lib remap shared by site and file-browser.",
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": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout",
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 renamed-away checkouts stay gone', () => {
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
  });