@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
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one directory layout of the `Frontend/` sibling checkout, and the
|
|
3
|
+
* `@widgetic/*` dev-alias tables every consumer used to keep by hand.
|
|
4
|
+
*
|
|
5
|
+
* Every app here (site, widget-creator, chat, editor, …) can compile sibling
|
|
6
|
+
* `@widgetic/*` **source** in dev instead of built `dist/` — instant HMR on a
|
|
7
|
+
* library edit, no per-package build loop. That mapping must point at specific
|
|
8
|
+
* paths inside specific sibling checkouts, and when a sibling is renamed or
|
|
9
|
+
* moved, every hand-kept copy of the table goes stale at once and silently:
|
|
10
|
+
* an alias to a directory that no longer exists resolves nothing, Vite falls
|
|
11
|
+
* through to `node_modules` (or a dangling link), and the dev server keeps
|
|
12
|
+
* booting — the feature is just quietly gone. That is not hypothetical: the
|
|
13
|
+
* tables drifted until `@widgetic/editor` pointed at the deleted
|
|
14
|
+
* `props-editor` checkout in one app and carried the same dead path in
|
|
15
|
+
* another, which is why the site grew per-entry `existsSync` fallbacks — the
|
|
16
|
+
* table itself had become untrustworthy.
|
|
17
|
+
*
|
|
18
|
+
* This module is the fix: the directory each `@widgetic/*` name maps to is
|
|
19
|
+
* declared **once**, here, with the moves recorded beside the entries. The
|
|
20
|
+
* builders below turn the layout into the three artifacts every consumer
|
|
21
|
+
* needs — the alias table, the `optimizeDeps.exclude` list, and the
|
|
22
|
+
* `ssr.noExternal` list — so "alias what you selected, exclude what you
|
|
23
|
+
* aliased, never SSR-externalize what you compile" is one decision instead of
|
|
24
|
+
* three lists that can disagree.
|
|
25
|
+
*
|
|
26
|
+
* What stays in the consumer: **which** packages it selects (that is a
|
|
27
|
+
* behavior choice — aliasing a package's index to `src/` changes what its dev
|
|
28
|
+
* server compiles), and nothing else. Adding a sibling or renaming one is a
|
|
29
|
+
* change here and a version bump, not a five-repository edit.
|
|
30
|
+
*
|
|
31
|
+
* Zero dependencies, plain ESM with hand-written JSDoc types — same rules as
|
|
32
|
+
* `vite-src-lib.mjs` beside it.
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* The sibling checkouts, keyed by their `@widgetic/*` name suffix.
|
|
37
|
+
*
|
|
38
|
+
* `dir` is the checkout's directory under `Frontend/` — the single fact that
|
|
39
|
+
* used to be copied into every consumer. Renames are recorded here, which is
|
|
40
|
+
* what makes the map trustworthy: the entry that used to say `props-editor`
|
|
41
|
+
* now says `editor`, with the old name kept as a comment so the next person
|
|
42
|
+
* knows why a dead path might still exist in older configs.
|
|
43
|
+
*
|
|
44
|
+
* `lib` marks packages whose dev source is a `src/lib` tree (Svelte library
|
|
45
|
+
* layout); `entry` marks those consumed through a single file.
|
|
46
|
+
*/
|
|
47
|
+
export const SIBLING_PACKAGES = {
|
|
48
|
+
'api-sdk': { dir: 'api-sdk', entry: 'src/index.ts' },
|
|
49
|
+
'cache-layer': { dir: 'cache-layer', entry: 'src/index.ts' },
|
|
50
|
+
canvas: { dir: 'canvas', lib: 'src/lib' },
|
|
51
|
+
// `dir` was `prompt-chat` when the package was created (see older configs).
|
|
52
|
+
chat: { dir: 'chat', lib: 'src/lib' },
|
|
53
|
+
creator: { dir: 'widget-creator', lib: 'src/lib' },
|
|
54
|
+
'design-system': {
|
|
55
|
+
dir: 'design-system',
|
|
56
|
+
lib: 'src/lib',
|
|
57
|
+
/**
|
|
58
|
+
* The subpath aliases the design-system source needs: alias suffix →
|
|
59
|
+
* path inside the lib tree. `styles` is a file, the rest directories.
|
|
60
|
+
*/
|
|
61
|
+
subpaths: {
|
|
62
|
+
styles: 'styles/global.css',
|
|
63
|
+
previews: 'components/previews',
|
|
64
|
+
'shad-editor': 'shad-editor',
|
|
65
|
+
components: 'components',
|
|
66
|
+
icons: 'icons',
|
|
67
|
+
stores: 'stores',
|
|
68
|
+
fonts: 'fonts'
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
// `dir` was `props-editor` (see older configs — and dangling symlinks).
|
|
72
|
+
editor: { dir: 'editor', lib: 'src/lib' },
|
|
73
|
+
'file-browser': { dir: 'file-browser', lib: 'src/lib' }
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Absolute roots for the named siblings under `frontendRoot`.
|
|
78
|
+
*
|
|
79
|
+
* @param {string} frontendRoot The `Frontend/` checkout root.
|
|
80
|
+
* @param {readonly string[]} names Package names (suffixes of `@widgetic/*`).
|
|
81
|
+
* @returns {Map<string, {root: string, lib?: string, entry?: string}>} Name →
|
|
82
|
+
* the checkout root plus its `lib` tree or `entry` file, absolute.
|
|
83
|
+
*/
|
|
84
|
+
export function siblingPackageRoots(frontendRoot, names) {
|
|
85
|
+
const roots = new Map();
|
|
86
|
+
for (const name of names) {
|
|
87
|
+
const pkg = SIBLING_PACKAGES[name];
|
|
88
|
+
if (!pkg) {
|
|
89
|
+
throw new Error(
|
|
90
|
+
`siblingPackageRoots: '${name}' is not in SIBLING_PACKAGES — add it to ` +
|
|
91
|
+
`@widgetic/dev-tools's frontend-layout.mjs rather than pointing at a directory by hand`
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
roots.set(name, {
|
|
95
|
+
root: `${frontendRoot}/${pkg.dir}`,
|
|
96
|
+
...(pkg.lib ? { lib: `${frontendRoot}/${pkg.dir}/${pkg.lib}` } : {}),
|
|
97
|
+
...(pkg.entry ? { entry: `${frontendRoot}/${pkg.dir}/${pkg.entry}` } : {})
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
return roots;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Build the dev alias table for the selected packages.
|
|
105
|
+
*
|
|
106
|
+
* Library packages alias to their `src/lib` tree; entry packages alias to
|
|
107
|
+
* their entry file; a package with declared subpaths gets one alias per
|
|
108
|
+
* subpath (`@widgetic/design-system/icons` → `<lib>/icons`) plus, with
|
|
109
|
+
* `designSystemIndex`, the bare specifier → the lib's `index.ts` — which is
|
|
110
|
+
* what makes the dev server compile design-system source on any import.
|
|
111
|
+
*
|
|
112
|
+
* @param {string} frontendRoot The `Frontend/` checkout root.
|
|
113
|
+
* @param {{
|
|
114
|
+
* packages: readonly string[],
|
|
115
|
+
* designSystemIndex?: boolean,
|
|
116
|
+
* designSystemSubpaths?: readonly string[]
|
|
117
|
+
* }} options
|
|
118
|
+
* `packages` selects the `@widgetic/*` names to emit (order is preserved).
|
|
119
|
+
* The two design-system options narrow what a consumer compiles: subpaths
|
|
120
|
+
* default to every declared subpath, and the index alias defaults to on
|
|
121
|
+
* whenever `design-system` is selected at all.
|
|
122
|
+
* @returns {Record<string, string>} Alias → absolute path, spread-ready for
|
|
123
|
+
* `resolve.alias`.
|
|
124
|
+
*/
|
|
125
|
+
export function buildSiblingAliases(frontendRoot, { packages, designSystemIndex = true, designSystemSubpaths }) {
|
|
126
|
+
const aliases = {};
|
|
127
|
+
for (const name of packages) {
|
|
128
|
+
const pkg = SIBLING_PACKAGES[name];
|
|
129
|
+
if (!pkg) {
|
|
130
|
+
throw new Error(
|
|
131
|
+
`buildSiblingAliases: '${name}' is not in SIBLING_PACKAGES — add it to ` +
|
|
132
|
+
`@widgetic/dev-tools's frontend-layout.mjs rather than pointing at a directory by hand`
|
|
133
|
+
);
|
|
134
|
+
}
|
|
135
|
+
const lib = `${frontendRoot}/${pkg.dir}/${pkg.lib ?? ''}`.replace(/\/$/, '');
|
|
136
|
+
if (name === 'design-system' && pkg.subpaths) {
|
|
137
|
+
const selected = designSystemSubpaths ?? Object.keys(pkg.subpaths);
|
|
138
|
+
for (const suffix of selected) {
|
|
139
|
+
const target = pkg.subpaths[suffix];
|
|
140
|
+
if (!target) {
|
|
141
|
+
throw new Error(
|
|
142
|
+
`buildSiblingAliases: '${suffix}' is not a declared design-system subpath ` +
|
|
143
|
+
`(declared: ${Object.keys(pkg.subpaths).join(', ')})`
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
aliases[`@widgetic/design-system/${suffix}`] = `${lib}/${target}`;
|
|
147
|
+
}
|
|
148
|
+
if (designSystemIndex) aliases['@widgetic/design-system'] = `${lib}/index.ts`;
|
|
149
|
+
continue;
|
|
150
|
+
}
|
|
151
|
+
aliases[`@widgetic/${name}`] = pkg.entry ? `${frontendRoot}/${pkg.dir}/${pkg.entry}` : lib;
|
|
152
|
+
}
|
|
153
|
+
return aliases;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The `optimizeDeps.exclude` list for the selected packages: Vite must not
|
|
158
|
+
* prebundle anything whose source is being aliased, or dev loads the prebundle
|
|
159
|
+
* while edits go to `src/` and the two diverge.
|
|
160
|
+
*
|
|
161
|
+
* @param {readonly string[]} packages Same selection as `buildSiblingAliases`.
|
|
162
|
+
* @returns {string[]} The `@widgetic/*` names, in selection order.
|
|
163
|
+
*/
|
|
164
|
+
export function devOptimizeExclude(packages) {
|
|
165
|
+
return packages.map((name) => `@widgetic/${name}`);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The `ssr.noExternal` list for the selected packages: packages compiled from
|
|
170
|
+
* source during SSR must not be externalized to node's resolution, or SSR
|
|
171
|
+
* loads the built package while the client compiles `src/` and the two diverge.
|
|
172
|
+
* Same rule as `devOptimizeExclude`, different mechanism.
|
|
173
|
+
*
|
|
174
|
+
* @param {readonly string[]} packages Same selection as `buildSiblingAliases`.
|
|
175
|
+
* @returns {string[]} The `@widgetic/*` names, in selection order.
|
|
176
|
+
*/
|
|
177
|
+
export function devSsrNoExternal(packages) {
|
|
178
|
+
return packages.map((name) => `@widgetic/${name}`);
|
|
179
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the shared sibling-`$lib` remap plugin (`vite-src-lib.mjs`).
|
|
3
|
+
*
|
|
4
|
+
* Hand-written rather than generated, and deliberately free of a `vite`
|
|
5
|
+
* import: `@widgetic/dev-tools` stays zero-dependency, and the shape below is
|
|
6
|
+
* structurally what Vite's `Plugin` requires of a `resolveId`-only plugin, so
|
|
7
|
+
* consumers drop it straight into their `plugins` array.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/** Options for {@link createSiblingSrcLibPlugin}. */
|
|
11
|
+
export interface SiblingSrcLibPluginOptions {
|
|
12
|
+
/** Vite plugin name. Defaults to `widgetic-sibling-src-lib`. */
|
|
13
|
+
name?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Path fragments — matched against the normalized importer path — that
|
|
16
|
+
* identify a file being compiled from a sibling package's `src` tree. Only
|
|
17
|
+
* ids imported from such files are remapped.
|
|
18
|
+
*/
|
|
19
|
+
importerFragments: readonly string[];
|
|
20
|
+
/**
|
|
21
|
+
* The `src/lib` root each fragment's package resolves `$lib` against, in
|
|
22
|
+
* the same order as `importerFragments`.
|
|
23
|
+
*/
|
|
24
|
+
libRoots: readonly string[];
|
|
25
|
+
/**
|
|
26
|
+
* Marker of the host app's own `src/lib` (for example `/site/src/lib/`).
|
|
27
|
+
* When SvelteKit's `$lib` alias has already rewritten a sibling's import
|
|
28
|
+
* into an absolute path under the host, the marker suffix is taken back
|
|
29
|
+
* apart and re-resolved against the sibling's tree.
|
|
30
|
+
*/
|
|
31
|
+
ownLibMarker?: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** The remap plugin — structurally a Vite `Plugin`; safe in `plugins: [...]`. */
|
|
35
|
+
export interface SiblingSrcLibPlugin {
|
|
36
|
+
name: string;
|
|
37
|
+
enforce: "pre";
|
|
38
|
+
resolveId(id: string, importer?: string): string | null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export declare function createSiblingSrcLibPlugin(
|
|
42
|
+
options: SiblingSrcLibPluginOptions,
|
|
43
|
+
): SiblingSrcLibPlugin;
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `$lib` remap for sibling-package sources compiled inside a host app's
|
|
3
|
+
* Vite dev server — one implementation, shared by everyone who needs it, so
|
|
4
|
+
* the copies cannot drift apart.
|
|
5
|
+
*
|
|
6
|
+
* A sibling package whose source imports `$lib/...` (design-system,
|
|
7
|
+
* file-browser) cannot simply be aliased to its `src/` tree by the host app:
|
|
8
|
+
* `$lib` is an alias of the project Vite is building, so inside the host app
|
|
9
|
+
* it points at the host's own `src/lib`. A sibling file's
|
|
10
|
+
* `import '$lib/utils.js'` then resolves into the host's tree — a missing
|
|
11
|
+
* module at best, a same-named wrong module at worst, and the dev log fills
|
|
12
|
+
* with hundreds of pre-transform errors that bury the real ones.
|
|
13
|
+
*
|
|
14
|
+
* The remap is therefore per **importer**: `$lib` inside design-system's files
|
|
15
|
+
* is design-system's, and `$lib` inside the host's files is the host's, which
|
|
16
|
+
* SvelteKit still owns. This plugin touches only ids whose importer lives
|
|
17
|
+
* inside a registered sibling's `src` tree, and it returns a path only when
|
|
18
|
+
* that file exists — a genuinely missing module still fails loudly, against
|
|
19
|
+
* the right tree.
|
|
20
|
+
*
|
|
21
|
+
* Two id shapes are handled, because both arrive in practice:
|
|
22
|
+
*
|
|
23
|
+
* - `$lib/...` — the specifier as the sibling wrote it; and
|
|
24
|
+
* - an absolute path under the host's own `src/lib` — SvelteKit's `$lib`
|
|
25
|
+
* alias may already have rewritten the specifier before this hook sees it,
|
|
26
|
+
* so the `ownLibMarker` occurrence is taken back apart and re-resolved
|
|
27
|
+
* against the sibling's tree.
|
|
28
|
+
*
|
|
29
|
+
* The `.js`-stripping and the candidate ladder exist for shadcn-derived
|
|
30
|
+
* source, which imports `$lib/foo/index.js` while the file is `index.ts`, and
|
|
31
|
+
* `$lib/utils.js` while the file is `utils.ts`.
|
|
32
|
+
*
|
|
33
|
+
* Consumers: site (`scripts/widgetic-dev-aliases.ts`) and file-browser
|
|
34
|
+
* (`vite.config.ts`). Both load this module dynamically and only while
|
|
35
|
+
* compiling sibling source (dev servers); types live beside it in
|
|
36
|
+
* `vite-src-lib.d.mts`. Zero dependencies — Node built-ins only.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
import { existsSync, statSync } from "node:fs";
|
|
40
|
+
import path from "node:path";
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Resolve `rest` inside a package's `src/lib`, trying the extensions shadcn
|
|
44
|
+
* source leaves implicit, and preserving any query string. Returns `null`
|
|
45
|
+
* when nothing exists — the host's resolver chain (and Vite's error for an
|
|
46
|
+
* unresolvable import) takes over from there.
|
|
47
|
+
*/
|
|
48
|
+
function resolvePackageLibPath(libRoot, rest) {
|
|
49
|
+
const queryIndex = rest.indexOf("?");
|
|
50
|
+
const query = queryIndex >= 0 ? rest.slice(queryIndex) : "";
|
|
51
|
+
const rel = (queryIndex >= 0 ? rest.slice(0, queryIndex) : rest).replace(
|
|
52
|
+
/\\/g,
|
|
53
|
+
"/",
|
|
54
|
+
);
|
|
55
|
+
// shadcn source often imports `$lib/foo/index.js` while the file is `index.ts`
|
|
56
|
+
const withoutJsExt = rel.replace(/\.js$/, "");
|
|
57
|
+
const bases = [path.resolve(libRoot, rel)];
|
|
58
|
+
if (withoutJsExt !== rel) bases.push(path.resolve(libRoot, withoutJsExt));
|
|
59
|
+
|
|
60
|
+
const candidates = [];
|
|
61
|
+
for (const base of bases) {
|
|
62
|
+
candidates.push(
|
|
63
|
+
base,
|
|
64
|
+
`${base}.ts`,
|
|
65
|
+
`${base}.js`,
|
|
66
|
+
`${base}.svelte`,
|
|
67
|
+
`${base}.json`,
|
|
68
|
+
path.join(base, "index.ts"),
|
|
69
|
+
path.join(base, "index.js"),
|
|
70
|
+
path.join(base, "index.svelte"),
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
for (const candidate of candidates) {
|
|
74
|
+
if (existsSync(candidate) && statSync(candidate).isFile())
|
|
75
|
+
return candidate + query;
|
|
76
|
+
}
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Build the remap plugin. `importerFragments` and `libRoots` pair up
|
|
82
|
+
* one-to-one: a file whose normalized importer path contains
|
|
83
|
+
* `importerFragments[i]` resolves `$lib` against `libRoots[i]`. The default
|
|
84
|
+
* name matches the plugin the site used before this module existed;
|
|
85
|
+
* file-browser keeps its own for log readability.
|
|
86
|
+
*
|
|
87
|
+
* @param {{
|
|
88
|
+
* name?: string,
|
|
89
|
+
* importerFragments: readonly string[],
|
|
90
|
+
* libRoots: readonly string[],
|
|
91
|
+
* ownLibMarker?: string
|
|
92
|
+
* }} options
|
|
93
|
+
* @returns {{ name: string, enforce: 'pre', resolveId: (id: string, importer?: string) => string | null }}
|
|
94
|
+
*/
|
|
95
|
+
export function createSiblingSrcLibPlugin({
|
|
96
|
+
name = "widgetic-sibling-src-lib",
|
|
97
|
+
importerFragments,
|
|
98
|
+
libRoots,
|
|
99
|
+
ownLibMarker,
|
|
100
|
+
}) {
|
|
101
|
+
if (importerFragments.length !== libRoots.length) {
|
|
102
|
+
throw new Error(
|
|
103
|
+
`createSiblingSrcLibPlugin: importerFragments (${importerFragments.length}) and ` +
|
|
104
|
+
`libRoots (${libRoots.length}) must pair up one-to-one`,
|
|
105
|
+
);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const fragments = [...importerFragments];
|
|
109
|
+
const roots = [...libRoots];
|
|
110
|
+
const marker = ownLibMarker ? ownLibMarker.replace(/\\/g, "/") : null;
|
|
111
|
+
|
|
112
|
+
return {
|
|
113
|
+
name,
|
|
114
|
+
enforce: "pre",
|
|
115
|
+
resolveId(id, importer) {
|
|
116
|
+
if (!importer) return null;
|
|
117
|
+
const importerNorm = importer.replace(/\\/g, "/");
|
|
118
|
+
const index = fragments.findIndex((fragment) =>
|
|
119
|
+
importerNorm.includes(fragment),
|
|
120
|
+
);
|
|
121
|
+
if (index === -1) return null;
|
|
122
|
+
|
|
123
|
+
let rest = null;
|
|
124
|
+
if (id === "$lib" || id.startsWith("$lib/")) {
|
|
125
|
+
rest = id === "$lib" ? "" : id.slice("$lib/".length);
|
|
126
|
+
} else if (marker) {
|
|
127
|
+
// Kit's `$lib` alias may already have rewritten the specifier to an
|
|
128
|
+
// absolute path inside the host app before this hook sees it. Take it back.
|
|
129
|
+
const idNorm = id.replace(/\\/g, "/");
|
|
130
|
+
const markerIndex = idNorm.indexOf(marker);
|
|
131
|
+
if (markerIndex !== -1)
|
|
132
|
+
rest = idNorm.slice(markerIndex + marker.length);
|
|
133
|
+
}
|
|
134
|
+
if (rest === null) return null;
|
|
135
|
+
|
|
136
|
+
return resolvePackageLibPath(roots[index], rest);
|
|
137
|
+
},
|
|
138
|
+
};
|
|
139
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@widgetic/dev-tools",
|
|
3
|
+
"version": "0.1.0",
|
|
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.",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://gitlab.com/widgeticai/Frontend/dev-tools.git"
|
|
9
|
+
},
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"access": "public"
|
|
12
|
+
},
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20"
|
|
16
|
+
},
|
|
17
|
+
"bin": {
|
|
18
|
+
"check-runtime-deps": "bin/check-runtime-deps.mjs",
|
|
19
|
+
"check-runtime-deps-fixtures": "bin/check-runtime-deps-fixtures.mjs"
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"bin",
|
|
23
|
+
"lib",
|
|
24
|
+
"test"
|
|
25
|
+
],
|
|
26
|
+
"scripts": {
|
|
27
|
+
"check:deps": "node bin/check-runtime-deps.mjs",
|
|
28
|
+
"test:deps": "node bin/check-runtime-deps-fixtures.mjs",
|
|
29
|
+
"test:vite": "node --test test/vite-src-lib.test.mjs",
|
|
30
|
+
"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",
|
|
32
|
+
"prepublishOnly": "npm test"
|
|
33
|
+
},
|
|
34
|
+
"volta": {
|
|
35
|
+
"node": "22.14.0",
|
|
36
|
+
"npm": "11.1.0"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Does the manifest check actually fail?
|
|
4
|
+
*
|
|
5
|
+
* `check-runtime-deps.mjs` guards the published package against two ways its
|
|
6
|
+
* `package.json` and its built output can disagree — a declared dependency
|
|
7
|
+
* nothing imports, and an import nothing declares. Both failures are invisible
|
|
8
|
+
* at publish time: the tarball uploads, the registry is happy, and the cost lands
|
|
9
|
+
* on consumers.
|
|
10
|
+
*
|
|
11
|
+
* A guard nobody has watched fail is indistinguishable from one that inspects
|
|
12
|
+
* nothing — and a checker that has only ever reported `OK` is exactly that. It
|
|
13
|
+
* even carries a `scanned === 0` escape hatch for precisely that suspicion. So
|
|
14
|
+
* each rule is driven here against a throwaway fixture
|
|
15
|
+
* package whose manifest and `dist/` are written to disagree on purpose, and the
|
|
16
|
+
* assertion is on the **exit code**, because that is the only thing CI reads.
|
|
17
|
+
*
|
|
18
|
+
* This suite ships in `@widgetic/dev-tools` and runs against the exact version a
|
|
19
|
+
* consumer installed — `npx check-runtime-deps-fixtures` — so every repository
|
|
20
|
+
* can watch the guard fail in its own pipeline without keeping a copy of it.
|
|
21
|
+
* That is why it runs in CI next to the check rather than on demand: it is the
|
|
22
|
+
* only thing that has ever made the check go red.
|
|
23
|
+
*
|
|
24
|
+
* The false-positive cases matter as much as the true ones. A checker that
|
|
25
|
+
* reports `all` because a comment says `from 'all'` gets switched off within a
|
|
26
|
+
* day, so the comment, string-literal, subpath and virtual-module shapes are
|
|
27
|
+
* pinned too.
|
|
28
|
+
*
|
|
29
|
+
* Fixtures are built in the OS temp dir, never in the package: `npm pack` runs
|
|
30
|
+
* against them, and a fixture that drifted into `dist/` would be published.
|
|
31
|
+
*
|
|
32
|
+
* Runs on the built-in test runner — no framework, no dependencies:
|
|
33
|
+
* npm run test:deps (in this repo)
|
|
34
|
+
* npx check-runtime-deps-fixtures (in a consumer, against what it installed)
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
import { execFileSync } from 'node:child_process';
|
|
38
|
+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
39
|
+
import { tmpdir } from 'node:os';
|
|
40
|
+
import { dirname, join } from 'node:path';
|
|
41
|
+
import { fileURLToPath } from 'node:url';
|
|
42
|
+
import { after, describe, it } from 'node:test';
|
|
43
|
+
import assert from 'node:assert/strict';
|
|
44
|
+
|
|
45
|
+
const CHECK = fileURLToPath(new URL('../bin/check-runtime-deps.mjs', import.meta.url));
|
|
46
|
+
|
|
47
|
+
/** Every fixture this run created, so a failure cannot leave one behind. */
|
|
48
|
+
const created = [];
|
|
49
|
+
|
|
50
|
+
after(() => {
|
|
51
|
+
for (const root of created) rmSync(root, { recursive: true, force: true });
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* A minimal package whose only contents are the manifest and the output npm
|
|
56
|
+
* would pack. `files` is deliberately omitted: npm's default packing is part of
|
|
57
|
+
* what the check is trusting, so the fixtures use it rather than override it.
|
|
58
|
+
*/
|
|
59
|
+
function fixture({ manifest, dist }) {
|
|
60
|
+
const root = mkdtempSync(join(tmpdir(), 'check-runtime-deps-'));
|
|
61
|
+
created.push(root);
|
|
62
|
+
|
|
63
|
+
writeFileSync(
|
|
64
|
+
join(root, 'package.json'),
|
|
65
|
+
JSON.stringify({ name: 'fixture-pkg', version: '1.0.0', ...manifest }, null, 2)
|
|
66
|
+
);
|
|
67
|
+
|
|
68
|
+
for (const [file, contents] of Object.entries(dist)) {
|
|
69
|
+
const full = join(root, 'dist', file);
|
|
70
|
+
mkdirSync(dirname(full), { recursive: true });
|
|
71
|
+
writeFileSync(full, contents);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
return root;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Run the check against a fixture and report what CI would see. */
|
|
78
|
+
function run(root) {
|
|
79
|
+
try {
|
|
80
|
+
const stdout = execFileSync('node', [CHECK, root], {
|
|
81
|
+
encoding: 'utf8',
|
|
82
|
+
stdio: ['ignore', 'pipe', 'pipe']
|
|
83
|
+
});
|
|
84
|
+
return { code: 0, output: stdout };
|
|
85
|
+
} catch (error) {
|
|
86
|
+
// A non-zero exit is the expected path here, so the output lives on the
|
|
87
|
+
// error rather than in a return value.
|
|
88
|
+
return { code: error.status ?? 1, output: `${error.stdout ?? ''}${error.stderr ?? ''}` };
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
describe('an import the manifest does not declare', () => {
|
|
93
|
+
it('fails, and names the package and the file that imports it', () => {
|
|
94
|
+
const root = fixture({
|
|
95
|
+
manifest: { dependencies: { svelte: '^5' } },
|
|
96
|
+
dist: {
|
|
97
|
+
'index.js': [
|
|
98
|
+
"import { onMount } from 'svelte';",
|
|
99
|
+
"import { modal } from 'some-ui-kit';"
|
|
100
|
+
].join('\n')
|
|
101
|
+
}
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
const { code, output } = run(root);
|
|
105
|
+
|
|
106
|
+
assert.equal(code, 1, 'an undeclared import must fail the check');
|
|
107
|
+
assert.match(output, /some-ui-kit/, 'the offending package must be named');
|
|
108
|
+
assert.match(output, /index\.js/, 'the importing file must be named');
|
|
109
|
+
// A declared, imported dependency must not be collateral damage.
|
|
110
|
+
assert.doesNotMatch(output, /- svelte /);
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
it('fails for a package declared only as a devDependency, and says so', () => {
|
|
114
|
+
// The distinction a reader needs: a devDependency is installed for this
|
|
115
|
+
// repo and for no consumer, so the import breaks in their build.
|
|
116
|
+
const root = fixture({
|
|
117
|
+
manifest: {
|
|
118
|
+
dependencies: { 'declared-dep': '^1' },
|
|
119
|
+
devDependencies: { 'build-only-tool': '^1' }
|
|
120
|
+
},
|
|
121
|
+
dist: { 'index.js': ["import 'declared-dep';", "import 'build-only-tool';"].join('\n') }
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
const { code, output } = run(root);
|
|
125
|
+
|
|
126
|
+
assert.equal(code, 1);
|
|
127
|
+
assert.match(output, /build-only-tool/);
|
|
128
|
+
assert.match(output, /devDependency/);
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
it('fails for an import a declaration file makes, not only a runtime file', () => {
|
|
132
|
+
// The published output ships its types, so a `.d.ts` that re-exports an
|
|
133
|
+
// undeclared package breaks a consumer's typecheck even though nothing
|
|
134
|
+
// runs it.
|
|
135
|
+
const root = fixture({
|
|
136
|
+
manifest: { dependencies: { 'declared-dep': '^1' } },
|
|
137
|
+
dist: {
|
|
138
|
+
'index.js': "import 'declared-dep';\n",
|
|
139
|
+
'index.d.ts': "export type { Thing } from 'types-only-pkg';\n"
|
|
140
|
+
}
|
|
141
|
+
});
|
|
142
|
+
|
|
143
|
+
const { code, output } = run(root);
|
|
144
|
+
|
|
145
|
+
assert.equal(code, 1);
|
|
146
|
+
assert.match(output, /types-only-pkg/);
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
it('accepts a subpath import of a declared package, which is not a package of its own', () => {
|
|
150
|
+
const root = fixture({
|
|
151
|
+
manifest: { dependencies: { 'ui-kit': '^1' } },
|
|
152
|
+
dist: { 'index.js': "import 'ui-kit/button/button.css';\n" }
|
|
153
|
+
});
|
|
154
|
+
|
|
155
|
+
assert.equal(run(root).code, 0);
|
|
156
|
+
});
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
describe('a declared dependency the output never imports', () => {
|
|
160
|
+
it('fails, so install weight cannot creep back in either', () => {
|
|
161
|
+
const root = fixture({
|
|
162
|
+
manifest: { dependencies: { 'never-imported': '^1' } },
|
|
163
|
+
dist: { 'index.js': 'export const answer = 42;\n' }
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
const { code, output } = run(root);
|
|
167
|
+
|
|
168
|
+
assert.equal(code, 1);
|
|
169
|
+
assert.match(output, /never-imported/);
|
|
170
|
+
});
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
describe('what must not be reported', () => {
|
|
174
|
+
it('ignores a package named in a comment or a string literal', () => {
|
|
175
|
+
// Both shapes look exactly like `from '…'` to a regex, and a check that
|
|
176
|
+
// reports them on its first run is a check that gets deleted.
|
|
177
|
+
const root = fixture({
|
|
178
|
+
manifest: { dependencies: { 'real-dep': '^1' } },
|
|
179
|
+
dist: {
|
|
180
|
+
'index.js': [
|
|
181
|
+
"// import x from 'commented-out';",
|
|
182
|
+
"/* export * from 'block-commented'; */",
|
|
183
|
+
'const where = "deselecting from \'string-literal\'";',
|
|
184
|
+
"import 'real-dep';",
|
|
185
|
+
''
|
|
186
|
+
].join('\n')
|
|
187
|
+
}
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
const { code, output } = run(root);
|
|
191
|
+
|
|
192
|
+
assert.equal(code, 0, `expected a clean pass, got:\n${output}`);
|
|
193
|
+
assert.doesNotMatch(output, /commented-out|block-commented|string-literal/);
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
it('exempts peers from the phantom rule, since a peer is a contract with the host', () => {
|
|
197
|
+
const root = fixture({
|
|
198
|
+
manifest: { peerDependencies: { svelte: '^5' } },
|
|
199
|
+
dist: { 'index.js': 'export const answer = 42;\n' }
|
|
200
|
+
});
|
|
201
|
+
|
|
202
|
+
assert.equal(run(root).code, 0);
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
it('attributes a SvelteKit virtual module to the package that serves it', () => {
|
|
206
|
+
// `$app/environment` is not a package, but a package that imports it is
|
|
207
|
+
// making a claim about `@sveltejs/kit` — so declaring kit must satisfy the
|
|
208
|
+
// check rather than leave it looking like an undeclared import.
|
|
209
|
+
const root = fixture({
|
|
210
|
+
manifest: { peerDependencies: { '@sveltejs/kit': '^2' } },
|
|
211
|
+
dist: { 'index.js': "import { browser } from '$app/environment';\n" }
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
assert.equal(run(root).code, 0);
|
|
215
|
+
});
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
describe('the check itself', () => {
|
|
219
|
+
it('passes a manifest that agrees with its output', () => {
|
|
220
|
+
const root = fixture({
|
|
221
|
+
manifest: {
|
|
222
|
+
dependencies: { 'declared-dep': '^1' },
|
|
223
|
+
peerDependencies: { svelte: '^5' }
|
|
224
|
+
},
|
|
225
|
+
dist: {
|
|
226
|
+
'index.js': ["import 'declared-dep';", "import { onMount } from 'svelte';"].join('\n')
|
|
227
|
+
}
|
|
228
|
+
});
|
|
229
|
+
|
|
230
|
+
assert.equal(run(root).code, 0);
|
|
231
|
+
});
|
|
232
|
+
|
|
233
|
+
it('fails when there is no scannable output, rather than passing vacuously', () => {
|
|
234
|
+
// The failure mode that makes a green check worthless: a check that
|
|
235
|
+
// inspects nothing.
|
|
236
|
+
const root = fixture({
|
|
237
|
+
manifest: { dependencies: { 'declared-dep': '^1' } },
|
|
238
|
+
dist: { 'notes.json': '{"not": "scannable"}\n' }
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
const { code, output } = run(root);
|
|
242
|
+
|
|
243
|
+
assert.equal(code, 1);
|
|
244
|
+
assert.match(output, /scannable/);
|
|
245
|
+
});
|
|
246
|
+
});
|