@widgetic/dev-tools 0.1.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/README.md ADDED
@@ -0,0 +1,102 @@
1
+ # @widgetic/dev-tools
2
+
3
+ Build-time checks shared by the published `@widgetic` packages. Published once so
4
+ the repositories that consume it cannot drift apart.
5
+
6
+ | Bin | What it does |
7
+ | --- | --- |
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
+ | `check-runtime-deps-fixtures` | Runs the fixture suite that proves the check above fails when it should. |
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`).
15
+
16
+ ## Why this is a published package
17
+
18
+ `check-runtime-deps` used to live twice: once inside `@widgetic/design-system` and
19
+ once inside `@widgetic/file-browser`. Each package is published from its own
20
+ repository, and neither CI could reach the other's checkout, so the two files had
21
+ to be kept in step by hand — and that sync obligation was the only thing holding
22
+ them together. Keeping a copy per repository meant every fix to the check was a
23
+ two-repository change, and a repository that forgot was silently unguarded.
24
+
25
+ The `$lib` remap is the same story one abstraction up: the site and file-browser
26
+ each kept an inline Vite plugin that had to match by hand. It lives here too.
27
+
28
+ Both live here instead. A consumer installs the package once and calls each tool
29
+ by name, so a fix reaches every consumer as an ordinary version bump.
30
+
31
+ ## Using it
32
+
33
+ ```jsonc
34
+ // package.json of a consuming package
35
+ {
36
+ "devDependencies": {
37
+ "@widgetic/dev-tools": "^0.1.0"
38
+ },
39
+ "scripts": {
40
+ // run after the build — the check fails when there is no build to inspect
41
+ "check:deps": "check-runtime-deps",
42
+ // the same fixtures, against the version this repository installed
43
+ "test:deps": "check-runtime-deps-fixtures"
44
+ }
45
+ }
46
+ ```
47
+
48
+ Then, in CI, after the build:
49
+
50
+ ```sh
51
+ npm run check:deps # manifest vs npm pack --dry-run's file list
52
+ npm run test:deps # the check itself, against fixtures that must fail it
53
+ ```
54
+
55
+ `check-runtime-deps [packageDir]` defaults to `cwd`, so a monorepo can point it at
56
+ sibling packages.
57
+
58
+ ### Loading the remap
59
+
60
+ ```js
61
+ // vite.config of a consumer (site and file-browser both do this)
62
+ const specifier = '@widgetic/dev-tools/lib/vite-src-lib.mjs';
63
+ const mod = await import(/* @vite-ignore */ specifier).catch(() => null);
64
+ const plugin =
65
+ mod &&
66
+ mod.createSiblingSrcLibPlugin({
67
+ importerFragments: ['/design-system/src/'],
68
+ libRoots: [resolve(__dirname, '../design-system/src/lib')],
69
+ ownLibMarker: '/file-browser/src/lib/'
70
+ });
71
+ ```
72
+
73
+ Load it dynamically: the package is dev-only tooling, and a consumer whose dev
74
+ server runs without it linked must degrade to a warning, not fail its config.
75
+ See `Frontend/site/scripts/widgetic-dev-aliases.ts` for the working example.
76
+
77
+ ### A deliberate exception
78
+
79
+ `EXCEPTIONS` in [`bin/check-runtime-deps.mjs`](bin/check-runtime-deps.mjs) is the
80
+ one shared place to record a dependency the scanner cannot see. It is keyed by
81
+ package name, so one release can carry an exception for several packages without
82
+ any of them seeing another's.
83
+
84
+ The map is compiled into the installed tool, so **adding an entry is a change
85
+ here and a release** — not an edit in the consumer. Every entry needs a reason
86
+ specific enough that a reviewer can check it; each one is a claim the check can
87
+ no longer make.
88
+
89
+ ## Releasing
90
+
91
+ 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
93
+ `npm pack --dry-run`, then publishes to npm if the version is not already on the
94
+ registry — the same shape as `@widgetic/design-system`'s and
95
+ `@widgetic/file-browser`'s pipelines, so it uses the `NPM_TOKEN` that is already
96
+ set on the `Frontend` group.
97
+
98
+ Local, from this checkout: `npm publish --access public` (a `prepublishOnly`
99
+ guard runs the full suite first; CI publishes with `--ignore-scripts`, which
100
+ skips that guard — the pipeline itself is the guard there).
101
+
102
+ Moving a consumer forward is then a devDependency bump.
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Run the fixture suite that proves `check-runtime-deps` fails when it should.
4
+ *
5
+ * The suite ships in this package so a consuming repository can run it against
6
+ * the exact version it installed, instead of trusting that somebody else
7
+ * watched the guard go red. `npm run test:deps` in a consumer is this script,
8
+ * and so is the `test:deps` step in its CI.
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-runtime-deps.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-runtime-deps] the fixture suite failed: the check no longer fails when it should.\n' +
24
+ ' That makes a green `check-runtime-deps` meaningless, so it is a failure of the check itself.\n'
25
+ );
26
+ }
27
+
28
+ process.exit(status ?? 1);
@@ -0,0 +1,449 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Does the manifest describe the published output?
4
+ *
5
+ * A published package has two halves that must agree: the tarball npm would
6
+ * upload, and the dependency lists in `package.json`. When they drift, nothing
7
+ * tells you — the package installs, the registry is happy, and the damage lands
8
+ * on consumers as install weight or as a missing module:
9
+ *
10
+ * phantom a `dependencies` entry the built output never imports.
11
+ * Every consumer of the package installs it and its whole
12
+ * transitive family, for nothing. `@widgetic/design-system` carried
13
+ * `@internationalized/date` and `shadcn-svelte` that way — `bits-ui`
14
+ * already supplies the former as its own peer, and the latter is
15
+ * only ever invoked as `npx shadcn-svelte` from a script — and
16
+ * `@widgetic/file-browser` shipped `@sveltejs/adapter-node`, `vite`,
17
+ * `tailwindcss`, `shadcn-svelte` and `chart.js` the same way, 163
18
+ * install entries including every OS/arch variant of esbuild and
19
+ * rollup. A build-only tool in `dependencies` is the same bug at one
20
+ * remove.
21
+ *
22
+ * missing something the output imports that is in neither `dependencies`
23
+ * nor `peerDependencies`. The consumer's install never contains it,
24
+ * so the import fails in their build — or, worse, resolves to
25
+ * whatever copy a sibling package happened to hoist. The
26
+ * design-system's shipped output imported `tailwind-merge`,
27
+ * `tailwind-variants`, `tailwindcss-animate` and
28
+ * `@tailwindcss/typography` (the last two
29
+ * loaded as plugins from the `@config` directive in
30
+ * `dist/styles/global.css`), plus `@tiptap/extension-heading`,
31
+ * re-exported by `dist/components/shad-editor/` while being declared
32
+ * nowhere — a resolved-by-accident import into a host's tree.
33
+ *
34
+ * The `missing` rule covers the **declaration files too**, not only the runtime
35
+ * code. A `.d.ts` that re-exports an undeclared package breaks a consumer's
36
+ * `tsc` run even though nothing executes it, and the types are as much part of
37
+ * the published output as the `.js` — 237 of the 520 files the design-system
38
+ * shipped are declarations.
39
+ *
40
+ * Both are checked here, against `npm pack --dry-run`'s file list rather than a
41
+ * guess at `files`/`.npmignore` (npm is the only authority on what ships), and
42
+ * against the specifiers that actually appear in that output.
43
+ *
44
+ * Peers are exempt from the phantom rule: a peer is a contract with the host,
45
+ * and a package may legitimately require one it imports only at runtime through
46
+ * the host's bundler. devDependencies are exempt too — the rule is about what
47
+ * consumers install, and devDependencies are never installed for a consumer.
48
+ * But a *devDependency* that the shipped runtime code imports is a violation,
49
+ * because the host will not get it.
50
+ *
51
+ * Usage: check-runtime-deps [packageDir] (default: cwd)
52
+ * Run it after the build — it fails if there is no build to inspect.
53
+ *
54
+ * This is the **only** copy. It used to live twice — once inside each package it
55
+ * guards — because `@widgetic/design-system` and `@widgetic/file-browser` are
56
+ * published from separate repositories, and neither CI could reach the other's
57
+ * checkout, so the two files had to be diffed against each other by hand and
58
+ * that sync obligation was the only thing holding them together. It is published
59
+ * here as `@widgetic/dev-tools` and installed by both, so a change to the check
60
+ * reaches every consumer as an ordinary version bump.
61
+ *
62
+ * The fixture suite that proves this check fails when it should lives in `test/`
63
+ * and ships in the tarball, so a consumer can run it against the exact version it
64
+ * installed instead of trusting that somebody else watched it fail:
65
+ *
66
+ * npx check-runtime-deps-fixtures (or: npm run test:deps in this repo)
67
+ */
68
+
69
+ import { execFileSync } from 'node:child_process';
70
+ import { readFileSync } from 'node:fs';
71
+ import { builtinModules } from 'node:module';
72
+ import { resolve } from 'node:path';
73
+
74
+ // ---------------------------------------------------------------------------
75
+ // Exceptions
76
+ // ---------------------------------------------------------------------------
77
+ /**
78
+ * Dependencies this package is right to declare but whose use the scanner
79
+ * cannot see, or undeclared imports it is right to make. Keep these empty if at
80
+ * all possible: every entry is a claim the check can no longer make, so each
81
+ * one needs a reason specific enough that a reviewer can verify it.
82
+ *
83
+ * Keyed by the package name in `package.json` — the map is shared by every
84
+ * consumer of this tool, so one release can carry an exception for several
85
+ * packages without any of them seeing another's.
86
+ */
87
+ const EXCEPTIONS = {
88
+ // '@widgetic/example': {
89
+ // unused: { 'some-css-side-effect': 'the host is told to @import this directly' },
90
+ // undeclared: { 'some-global': 'injected by the host as a script tag' },
91
+ // },
92
+ };
93
+
94
+ // ---------------------------------------------------------------------------
95
+ // Reading the published output
96
+ // ---------------------------------------------------------------------------
97
+
98
+ /** Extensions that can carry an import of another package. */
99
+ const SCANNABLE = new Set([
100
+ '.js',
101
+ '.mjs',
102
+ '.cjs',
103
+ '.jsx',
104
+ '.ts',
105
+ '.mts',
106
+ '.cts',
107
+ '.tsx',
108
+ '.svelte',
109
+ '.css',
110
+ '.pcss',
111
+ '.scss',
112
+ '.sass',
113
+ '.less'
114
+ ]);
115
+
116
+ /**
117
+ * A declaration file. It is scanned like any other output file, but what it
118
+ * imports is *referenced* rather than *executed*, and that difference is worth
119
+ * keeping: it decides how a missing dependency is described to whoever has to
120
+ * fix it, not whether it is reported.
121
+ */
122
+ const isDeclaration = (path) => /\.d\.(ts|mts|cts)$/.test(path);
123
+
124
+ /**
125
+ * The exact file list npm would upload. `--ignore-scripts` keeps a `prepare`
126
+ * hook from rebuilding mid-check; `--dry-run` writes nothing.
127
+ */
128
+ function packedFiles(dir) {
129
+ let out;
130
+ try {
131
+ out = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
132
+ cwd: dir,
133
+ encoding: 'utf8',
134
+ stdio: ['ignore', 'pipe', 'pipe']
135
+ });
136
+ } catch (error) {
137
+ const detail = (error.stderr || error.message || '').toString().trim();
138
+ throw new Error(`npm pack failed, so there is no output to check:\n${detail}`);
139
+ }
140
+
141
+ // npm has emitted a bare array here for a long time; tolerate the {0: [...]} shape too.
142
+ const parsed = JSON.parse(out);
143
+ const entry = Array.isArray(parsed) ? parsed[0] : Object.values(parsed)[0];
144
+ const files = (entry?.files ?? []).map((f) => f.path);
145
+ return { name: entry?.name, version: entry?.version, files };
146
+ }
147
+
148
+ // ---------------------------------------------------------------------------
149
+ // Finding the imports
150
+ // ---------------------------------------------------------------------------
151
+
152
+ /**
153
+ * Package specifiers used in one file.
154
+ *
155
+ * Comments and string literals are skipped by walking the file with a small
156
+ * state machine rather than by regex over the raw text. That distinction is the
157
+ * difference between a usable check and a noisy one: `// Also remove from 'all'
158
+ * if present` and `` console.log(`deselecting from "all"`) `` both look exactly
159
+ * like `from 'all'` to a regex, and a checker that reports `all` as a missing
160
+ * dependency on its first run gets switched off.
161
+ */
162
+ function specifiersIn(source) {
163
+ const found = new Set();
164
+ const length = source.length;
165
+ let i = 0;
166
+ let state = 'code';
167
+
168
+ while (i < length) {
169
+ const c = source[i];
170
+
171
+ if (state === 'line') {
172
+ if (c === '\n') state = 'code';
173
+ i += 1;
174
+ continue;
175
+ }
176
+
177
+ if (state === 'block') {
178
+ if (c === '*' && source[i + 1] === '/') {
179
+ state = 'code';
180
+ i += 2;
181
+ continue;
182
+ }
183
+ i += 1;
184
+ continue;
185
+ }
186
+
187
+ if (c === '/' && source[i + 1] === '/') {
188
+ state = 'line';
189
+ i += 2;
190
+ continue;
191
+ }
192
+ if (c === '/' && source[i + 1] === '*') {
193
+ state = 'block';
194
+ i += 2;
195
+ continue;
196
+ }
197
+
198
+ if (c === '"' || c === "'" || c === '`') {
199
+ const quote = c;
200
+ let j = i + 1;
201
+ while (j < length) {
202
+ if (source[j] === '\\') {
203
+ j += 2;
204
+ continue;
205
+ }
206
+ if (source[j] === quote) break;
207
+ j += 1;
208
+ }
209
+ const value = source.slice(i + 1, j);
210
+ // Only a string that follows an import keyword is a specifier. The
211
+ // lookback window is generous enough for a wrapped multi-line import.
212
+ const before = source.slice(Math.max(0, i - 120), i);
213
+ if (isImportPosition(before)) found.add(value);
214
+ i = j + 1;
215
+ continue;
216
+ }
217
+
218
+ i += 1;
219
+ }
220
+
221
+ return found;
222
+ }
223
+
224
+ const IMPORT_POSITION = [
225
+ /\bfrom\s*$/, // import x from '…' / export * from '…'
226
+ /\bimport\s*\(\s*$/, // import('…')
227
+ /\bimport\s*$/, // import '…'
228
+ /\bexport\s*$/, // export '…' (rare, but valid)
229
+ /\brequire\s*\(\s*$/, // require('…')
230
+ /@(?:import|plugin|config|source|reference)\s+(?:url\(\s*)?$/, // CSS / Tailwind at-rules
231
+ /<reference\s+types=\s*$/ // /// <reference types="…" />
232
+ ];
233
+
234
+ function isImportPosition(before) {
235
+ return IMPORT_POSITION.some((re) => re.test(before.replace(/\/\/\/\s*$/, '/// ')));
236
+ }
237
+
238
+ const BUILTINS = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)]);
239
+
240
+ /**
241
+ * The package a specifier resolves to, or `null` when it is not a package:
242
+ * relative paths, `node:` builtins, URLs, and bundler-virtual modules.
243
+ *
244
+ * SvelteKit's `$app/*`, `$env/*` and `$service-worker` are virtual modules
245
+ * served by `@sveltejs/kit`, so they are attributed to it — otherwise a package
246
+ * that legitimately lists kit as a dependency would look like it never uses it.
247
+ *
248
+ * Sub-path imports (`pkg/sub`) belong to `pkg`; the sub-path is not a package.
249
+ */
250
+ function packageOf(specifier) {
251
+ if (!specifier) return null;
252
+ if (specifier.startsWith('.') || specifier.startsWith('/')) return null;
253
+ if (/^[a-z][a-z0-9+.-]*:/i.test(specifier)) return null; // http:, data:, node:
254
+ if (BUILTINS.has(specifier)) return null;
255
+
256
+ if (
257
+ specifier.startsWith('$app/') ||
258
+ specifier.startsWith('$env/') ||
259
+ specifier === '$service-worker'
260
+ ) {
261
+ return '@sveltejs/kit';
262
+ }
263
+ if (specifier.startsWith('$')) return null; // $lib and other bundler aliases
264
+
265
+ const parts = specifier.split('/');
266
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
267
+ }
268
+
269
+ // ---------------------------------------------------------------------------
270
+ // The two rules
271
+ // ---------------------------------------------------------------------------
272
+
273
+ function collect(dir) {
274
+ const manifest = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8'));
275
+ const { files, name, version } = packedFiles(dir);
276
+
277
+ const used = new Set(); // package names the output imports
278
+ const usedInRuntime = new Map(); // …from files that execute
279
+ const usedInDeclarations = new Map(); // …from the types the package ships
280
+ let scanned = 0;
281
+
282
+ for (const file of files) {
283
+ // A `.d.ts` lands on the `.ts` extension, which is scannable on purpose: a
284
+ // declaration that names a package is a claim about it, and a package
285
+ // whose types are re-exported is reason to declare or peer it.
286
+ const ext = file.slice(file.lastIndexOf('.'));
287
+ if (!SCANNABLE.has(ext)) continue;
288
+
289
+ let source;
290
+ try {
291
+ source = readFileSync(resolve(dir, file), 'utf8');
292
+ } catch {
293
+ continue; // a directory entry, or a file npm listed but did not write
294
+ }
295
+ scanned += 1;
296
+
297
+ const declarations = isDeclaration(file);
298
+ for (const specifier of specifiersIn(source)) {
299
+ const pkg = packageOf(specifier);
300
+ if (!pkg) continue;
301
+ used.add(pkg);
302
+ if (!declarations && !usedInRuntime.has(pkg)) usedInRuntime.set(pkg, file);
303
+ if (declarations && !usedInDeclarations.has(pkg)) usedInDeclarations.set(pkg, file);
304
+ }
305
+ }
306
+
307
+ return {
308
+ manifest,
309
+ name: name ?? manifest.name,
310
+ version: version ?? manifest.version,
311
+ files,
312
+ used,
313
+ usedInRuntime,
314
+ usedInDeclarations,
315
+ scanned
316
+ };
317
+ }
318
+
319
+ function checkPhantom({ manifest, name, used }) {
320
+ const exceptions = EXCEPTIONS[name]?.unused ?? {};
321
+ const offenders = [];
322
+
323
+ for (const dep of Object.keys(manifest.dependencies ?? {})) {
324
+ if (used.has(dep) || exceptions[dep]) continue;
325
+ offenders.push(dep);
326
+ }
327
+
328
+ return offenders;
329
+ }
330
+
331
+ function checkMissing({ manifest, name, usedInRuntime, usedInDeclarations }) {
332
+ const exceptions = EXCEPTIONS[name]?.undeclared ?? {};
333
+ const declared = new Set([
334
+ ...Object.keys(manifest.dependencies ?? {}),
335
+ ...Object.keys(manifest.peerDependencies ?? {})
336
+ ]);
337
+ const declaredDev = new Set(Object.keys(manifest.devDependencies ?? {}));
338
+ const offenders = [];
339
+ const seen = new Set();
340
+
341
+ // One report per package, and the runtime reference wins: it is the one that
342
+ // breaks a consumer's *build*, which is the more urgent of the two.
343
+ const consider = (pkg, file, fromTypes) => {
344
+ if (declared.has(pkg) || exceptions[pkg] || seen.has(pkg)) return;
345
+ seen.add(pkg);
346
+ offenders.push({
347
+ pkg,
348
+ file,
349
+ // The most useful thing to say: a devDependency is installed for the
350
+ // maintainer and for nobody else, and a types-only reference still fails
351
+ // a consumer's typecheck even though nothing runs it.
352
+ kind: fromTypes ? 'types' : declaredDev.has(pkg) ? 'dev' : 'absent'
353
+ });
354
+ };
355
+
356
+ for (const [pkg, file] of usedInRuntime) consider(pkg, file, false);
357
+ for (const [pkg, file] of usedInDeclarations) consider(pkg, file, true);
358
+
359
+ return offenders;
360
+ }
361
+
362
+ // ---------------------------------------------------------------------------
363
+ // Report
364
+ // ---------------------------------------------------------------------------
365
+
366
+ function main() {
367
+ const dir = resolve(process.argv[2] ?? '.');
368
+ let collected;
369
+ try {
370
+ collected = collect(dir);
371
+ } catch (error) {
372
+ console.error(`\n[check-runtime-deps] ${error.message}`);
373
+ process.exit(1);
374
+ }
375
+
376
+ const { manifest, name, version, files, scanned, used } = collected;
377
+
378
+ if (scanned === 0) {
379
+ console.error(
380
+ `\n[check-runtime-deps] ${name}@${version} packs ${files.length} file(s) and none of them are ` +
381
+ `scannable. Is dist/ built? Run the package build first — a check that inspects nothing passes for the wrong reason.`
382
+ );
383
+ process.exit(1);
384
+ }
385
+
386
+ const phantom = checkPhantom(collected);
387
+ const missing = checkMissing(collected);
388
+
389
+ console.log(`[check-runtime-deps] ${name}@${version}`);
390
+ console.log(
391
+ ` packed ${files.length} file(s), scanned ${scanned}, found ${used.size} package import(s)`
392
+ );
393
+ console.log(
394
+ ` declared: ${Object.keys(manifest.dependencies ?? {}).length} dependencies, ` +
395
+ `${Object.keys(manifest.peerDependencies ?? {}).length} peers, ` +
396
+ `${Object.keys(manifest.devDependencies ?? {}).length} dev`
397
+ );
398
+
399
+ if (phantom.length === 0 && missing.length === 0) {
400
+ console.log(' OK — every declared dependency is used, and every import is declared.\n');
401
+ return;
402
+ }
403
+
404
+ if (phantom.length > 0) {
405
+ console.error(
406
+ `\n ${phantom.length} declared dependenc${phantom.length === 1 ? 'y' : 'ies'} the published output never imports:`
407
+ );
408
+ for (const dep of phantom) {
409
+ const dev = manifest.devDependencies?.[dep];
410
+ console.error(
411
+ ` - ${dep}${dev ? ` (also in devDependencies: ${dev})` : ''}\n` +
412
+ ` Not imported by any packed file. Move it to devDependencies if only the build or the\n` +
413
+ ` tooling uses it, or delete it. Every consumer currently installs it and its whole\n` +
414
+ ` transitive family for nothing.`
415
+ );
416
+ }
417
+ }
418
+
419
+ if (missing.length > 0) {
420
+ console.error(
421
+ `\n ${missing.length} package${missing.length === 1 ? '' : 's'} imported by the runtime output but not declared:`
422
+ );
423
+ for (const { pkg, file, kind } of missing) {
424
+ const why =
425
+ kind === 'dev'
426
+ ? 'declared as a devDependency — installed for this repo and for no consumer'
427
+ : kind === 'types'
428
+ ? 'declared nowhere, and referenced by the types this package ships'
429
+ : 'declared nowhere';
430
+ const consequence =
431
+ kind === 'types'
432
+ ? ` referenced by ${file}. Add it to dependencies (or peerDependencies if the\n` +
433
+ ` host must own the copy), or a consumer's typecheck fails on this package.`
434
+ : ` imported by ${file}. Add it to dependencies (or peerDependencies if the host\n` +
435
+ ` must own the copy), or the import fails in the consumer's build.`;
436
+ console.error(` - ${pkg} (${why})\n${consequence}`);
437
+ }
438
+ }
439
+
440
+ console.error(
441
+ '\n If an entry above is deliberate, add it to EXCEPTIONS in @widgetic/dev-tools\n' +
442
+ ' (bin/check-runtime-deps.mjs) with a reason a reviewer can check, and release it —\n' +
443
+ ' this copy is installed, not edited in place. The map is keyed by package name, so\n' +
444
+ ' one release can carry an exception for every consumer that needs one.\n'
445
+ );
446
+ process.exit(1);
447
+ }
448
+
449
+ main();
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Types for the shared Frontend layout and dev-alias builders
3
+ * (`frontend-layout.mjs`). Hand-written, dependency-free — same rules as
4
+ * `vite-src-lib.d.mts` beside it.
5
+ */
6
+
7
+ /** One sibling checkout, keyed by its `@widgetic/*` name suffix. */
8
+ export interface SiblingPackage {
9
+ /** The checkout's directory under `Frontend/`. */
10
+ dir: string;
11
+ /** The package's dev source is this `src/lib`-style tree. */
12
+ lib?: string;
13
+ /** The package is consumed through this single file. */
14
+ entry?: string;
15
+ /** Declared subpath aliases (design-system only): suffix → path in the lib tree. */
16
+ subpaths?: Record<string, string>;
17
+ }
18
+
19
+ /** The canonical sibling layout. */
20
+ export declare const SIBLING_PACKAGES: Record<string, SiblingPackage>;
21
+
22
+ /** One sibling's resolved roots: the checkout root plus its lib tree or entry. */
23
+ export interface SiblingPackageRoot {
24
+ root: string;
25
+ lib?: string;
26
+ entry?: string;
27
+ }
28
+
29
+ /** Resolve absolute roots for the named siblings under `frontendRoot`. */
30
+ export declare function siblingPackageRoots(
31
+ frontendRoot: string,
32
+ names: readonly string[]
33
+ ): Map<string, SiblingPackageRoot>;
34
+
35
+ /** Options for {@link buildSiblingAliases}. */
36
+ export interface BuildSiblingAliasesOptions {
37
+ /** The `@widgetic/*` names to emit, in order. */
38
+ packages: readonly string[];
39
+ /** Emit the bare `@widgetic/design-system` index alias (default: true). */
40
+ designSystemIndex?: boolean;
41
+ /** Which design-system subpaths to emit (default: every declared one). */
42
+ designSystemSubpaths?: readonly string[];
43
+ }
44
+
45
+ /** The dev alias table for the selected packages, spread-ready for `resolve.alias`. */
46
+ export declare function buildSiblingAliases(
47
+ frontendRoot: string,
48
+ options: BuildSiblingAliasesOptions
49
+ ): Record<string, string>;
50
+
51
+ /** The `optimizeDeps.exclude` list for the selected packages. */
52
+ export declare function devOptimizeExclude(packages: readonly string[]): string[];
53
+
54
+ /** The `ssr.noExternal` list for the selected packages. */
55
+ export declare function devSsrNoExternal(packages: readonly string[]): string[];