@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 +102 -0
- package/bin/check-runtime-deps-fixtures.mjs +28 -0
- package/bin/check-runtime-deps.mjs +449 -0
- package/lib/frontend-layout.d.mts +55 -0
- package/lib/frontend-layout.mjs +179 -0
- package/lib/vite-src-lib.d.mts +43 -0
- package/lib/vite-src-lib.mjs +139 -0
- package/package.json +38 -0
- package/test/check-runtime-deps.test.mjs +246 -0
- package/test/frontend-layout.test.mjs +120 -0
- package/test/vite-src-lib.test.mjs +227 -0
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[];
|