@provino/loader 0.0.0-stage → 0.1.0-rc.1
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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/graph/index.d.ts +199 -0
- package/dist/graph/index.js +3 -0
- package/dist/graph.js +571 -0
- package/dist/index.d.ts +200 -0
- package/dist/index.js +3272 -0
- package/package.json +46 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pixel Perfect Software
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @provino/loader
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The module loader: a two-phase module-runner engine with a fresh module registry for each test file, `node_modules` shared natively, and module mocks applied on every import. It also loads a global setup module in the coordinator.
|
|
4
|
+
|
|
5
|
+
This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner for Jest projects, on npm as [`provino`](https://www.npmjs.com/package/provino). The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
|
|
6
|
+
|
|
7
|
+
**Versioning:** this package is `@beta` as a whole. There is no semver promise for it before 1.0, and its API can change in any release.
|
|
8
|
+
|
|
9
|
+
[MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { Resolver } from "@provino/types";
|
|
2
|
+
/**
|
|
3
|
+
* How an edge resolves: as an `import` (ES syntax, `import()`) or a `require`.
|
|
4
|
+
* @public
|
|
5
|
+
*/
|
|
6
|
+
type EdgeKind = "import" | "require";
|
|
7
|
+
/**
|
|
8
|
+
* One module request a file makes, with the text as written.
|
|
9
|
+
* @public
|
|
10
|
+
*/
|
|
11
|
+
interface ScannedEdge {
|
|
12
|
+
readonly specifier: string;
|
|
13
|
+
readonly kind: EdgeKind;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* What a file's source holds.
|
|
17
|
+
* @public
|
|
18
|
+
*/
|
|
19
|
+
interface Scan {
|
|
20
|
+
readonly edges: readonly ScannedEdge[];
|
|
21
|
+
/**
|
|
22
|
+
* The file calls `require(…)` or `import(…)` with a specifier the scan can't read (a computed
|
|
23
|
+
* one): an edge the graph can't see.
|
|
24
|
+
*/
|
|
25
|
+
readonly dynamic: boolean;
|
|
26
|
+
/**
|
|
27
|
+
* The file has ES module syntax (`import`/`export` declarations, `import.meta`), as
|
|
28
|
+
* `esmSyntaxOf` reads it, a file the lexer rejects counting as having it: what Node, which can't
|
|
29
|
+
* run it either, would meet.
|
|
30
|
+
*/
|
|
31
|
+
readonly esm: boolean;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Starts the lexer's WebAssembly build. `scanSource` works without it (the first scan compiles the
|
|
35
|
+
* module synchronously); a worker awaits this once at start-up, where an `await` is free.
|
|
36
|
+
* @public
|
|
37
|
+
*/
|
|
38
|
+
export declare function initLexer(): Promise<void>;
|
|
39
|
+
/**
|
|
40
|
+
* Whether `source` has ES module syntax: an `import` or `export` declaration, or `import.meta`
|
|
41
|
+
* (`import()` alone is CommonJS too). `null` when the file has the words and the lexer can't parse
|
|
42
|
+
* it: a caller says what a file nothing can run counts as (Node reads it as ES module syntax,
|
|
43
|
+
* jest-runtime's `esmLexer.ts` `hasEsmSyntax` as none).
|
|
44
|
+
* @public
|
|
45
|
+
*/
|
|
46
|
+
export declare function esmSyntaxOf(source: string): boolean | null;
|
|
47
|
+
/**
|
|
48
|
+
* The edges of `source`. A file the lexer can't parse (it holds syntax no engine would run) is
|
|
49
|
+
* `dynamic`, and still gets its `require` edges.
|
|
50
|
+
* @public
|
|
51
|
+
*/
|
|
52
|
+
export declare function scanSource(source: string): Scan;
|
|
53
|
+
/**
|
|
54
|
+
* A target of an edge: a real path, a `node:` builtin, or `null` for one that doesn't resolve.
|
|
55
|
+
* @public
|
|
56
|
+
*/
|
|
57
|
+
type EdgeTarget = string | null;
|
|
58
|
+
/**
|
|
59
|
+
* One resolved edge.
|
|
60
|
+
* @public
|
|
61
|
+
*/
|
|
62
|
+
interface GraphEdge {
|
|
63
|
+
readonly specifier: string;
|
|
64
|
+
readonly kind: EdgeKind;
|
|
65
|
+
readonly target: EdgeTarget;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* One scanned file: its edges, whether it has a specifier the scan couldn't read, and whether it
|
|
69
|
+
* has ES module syntax (`Scan.esm`).
|
|
70
|
+
* @public
|
|
71
|
+
*/
|
|
72
|
+
interface GraphNode {
|
|
73
|
+
readonly edges: readonly GraphEdge[];
|
|
74
|
+
readonly dynamic: boolean;
|
|
75
|
+
readonly esm: boolean;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The cache key: a hash of the lockfile's hash (`lockfileHash`, which the loader takes from the
|
|
79
|
+
* transform cache's), the install marker's size and mtime, the graph format, the lexer's version
|
|
80
|
+
* and how edges resolve (`extra`: the resolver's fingerprint and the conditions). `null` when the
|
|
81
|
+
* project has no lockfile, and the graph then stays in memory.
|
|
82
|
+
* @public
|
|
83
|
+
*/
|
|
84
|
+
export declare function graphCacheKey(root: string, extra: string, lockfileHash: string | null): string | null;
|
|
85
|
+
/**
|
|
86
|
+
* What `buildThirdPartyGraph` takes.
|
|
87
|
+
* @public
|
|
88
|
+
*/
|
|
89
|
+
interface GraphOptions {
|
|
90
|
+
readonly root: string;
|
|
91
|
+
/** The worker's resolver: edges resolve as the loader resolves them. */
|
|
92
|
+
readonly resolver: Resolver;
|
|
93
|
+
/** The resolution conditions the loader uses. Default `['node']`. */
|
|
94
|
+
readonly conditions?: readonly string[];
|
|
95
|
+
/**
|
|
96
|
+
* The cache directory (the file is `<dir>/graph/<key>.json`). `null` or absent keeps the graph
|
|
97
|
+
* in memory, as does a project with no lockfile.
|
|
98
|
+
*/
|
|
99
|
+
readonly cacheDir?: string | null;
|
|
100
|
+
/**
|
|
101
|
+
* The hash of the project's lockfile (`lockfileHash` in `@provino/transform`, which the loader
|
|
102
|
+
* takes from the transform cache), part of the cache key. `null` or absent: no disk cache.
|
|
103
|
+
*/
|
|
104
|
+
readonly lockfileHash?: string | null;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* A file's place in the graph, with the files its edges lead to.
|
|
108
|
+
* @public
|
|
109
|
+
*/
|
|
110
|
+
interface GraphEntry {
|
|
111
|
+
readonly path: string;
|
|
112
|
+
readonly node: GraphNode;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* One edge of a closure, with the file that makes it.
|
|
116
|
+
* @public
|
|
117
|
+
*/
|
|
118
|
+
interface ClosureEdge {
|
|
119
|
+
readonly importer: string;
|
|
120
|
+
readonly edge: GraphEdge;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The edges of a file's closure, each distinct request once (the first importer to make it).
|
|
124
|
+
* @public
|
|
125
|
+
*/
|
|
126
|
+
interface ClosureEdges {
|
|
127
|
+
/** The files of the closure, the file itself first. */
|
|
128
|
+
readonly paths: readonly string[];
|
|
129
|
+
readonly edges: readonly ClosureEdge[];
|
|
130
|
+
/** Some file in the closure has an edge the graph can't see, or could not be read. */
|
|
131
|
+
readonly dynamic: boolean;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* The graph of the files under `node_modules` that a set of entries reaches.
|
|
135
|
+
* @public
|
|
136
|
+
*/
|
|
137
|
+
interface ThirdPartyGraph {
|
|
138
|
+
/**
|
|
139
|
+
* Scans `entry` and every file under `node_modules` it can reach, unless already known. What a
|
|
140
|
+
* cache file holds counts as known and is not stamped here: `reachable` and `edgesOf` do that, on
|
|
141
|
+
* a file's first visit.
|
|
142
|
+
*/
|
|
143
|
+
add(entry: string): void;
|
|
144
|
+
/** Whether `path` is in the graph. */
|
|
145
|
+
has(path: string): boolean;
|
|
146
|
+
/** A file's edges, or `undefined` when it wasn't added or reached. */
|
|
147
|
+
nodeOf(path: string): GraphNode | undefined;
|
|
148
|
+
/**
|
|
149
|
+
* A file's edges as a walk sees them: added first if it is a file under `node_modules` the graph
|
|
150
|
+
* doesn't know, and stamped on its first visit in this worker (as `reachable` and `edgesOf` do).
|
|
151
|
+
* `undefined` for any other path. For a walk that may stop early, where building `path`'s whole
|
|
152
|
+
* closure first would be wasted.
|
|
153
|
+
*/
|
|
154
|
+
visitNode(path: string): GraphNode | undefined;
|
|
155
|
+
/**
|
|
156
|
+
* Every file `path` can reach, itself included, in discovery order (a cycle ends the walk).
|
|
157
|
+
* Empty for a path that isn't in the graph.
|
|
158
|
+
*/
|
|
159
|
+
reachable(path: string): readonly GraphEntry[];
|
|
160
|
+
/**
|
|
161
|
+
* The edges of `path`'s closure, deduplicated, computed once per worker. Adds `path` first if it
|
|
162
|
+
* is a file under `node_modules` the graph doesn't know. Empty for any other path.
|
|
163
|
+
*/
|
|
164
|
+
edgesOf(path: string): ClosureEdges;
|
|
165
|
+
/** Every path in the graph. */
|
|
166
|
+
paths(): IterableIterator<string>;
|
|
167
|
+
readonly size: number;
|
|
168
|
+
/** The number of edges, resolved or not. */
|
|
169
|
+
readonly edgeCount: number;
|
|
170
|
+
/** How many files this graph scanned itself, rather than read from the cache. */
|
|
171
|
+
readonly scanned: number;
|
|
172
|
+
/** Whether the graph began from a cache file. */
|
|
173
|
+
readonly fromCache: boolean;
|
|
174
|
+
/** Writes what was scanned to the cache, if it is on and anything is new. */
|
|
175
|
+
save(): void;
|
|
176
|
+
}
|
|
177
|
+
/** Whether `path` is a real file under `node_modules` the graph covers. */
|
|
178
|
+
export declare function inGraph(path: string): boolean;
|
|
179
|
+
/**
|
|
180
|
+
* Builds a graph, empty but for the cache file's nodes. Nothing is scanned until an entry is
|
|
181
|
+
* added, and the lexer should be started first (`initLexer`).
|
|
182
|
+
* @public
|
|
183
|
+
*/
|
|
184
|
+
export declare function buildThirdPartyGraph(options: GraphOptions): ThirdPartyGraph;
|
|
185
|
+
/**
|
|
186
|
+
* The directory of the package a `node_modules` file belongs to (`…/node_modules/@scope/name`),
|
|
187
|
+
* with `/` for separators, or `null` for a path that has no package directory (it is not under
|
|
188
|
+
* `node_modules`, or it is a package's directory itself). The innermost `node_modules` counts, so a
|
|
189
|
+
* nested copy is its own package.
|
|
190
|
+
* @public
|
|
191
|
+
*/
|
|
192
|
+
export declare function packageDirOf(path: string): string | null;
|
|
193
|
+
/**
|
|
194
|
+
* Every file in the graph that can reach any of `targets` through its edges (a target is
|
|
195
|
+
* included only if another target, or itself through a cycle, reaches it), in no particular order.
|
|
196
|
+
* @public
|
|
197
|
+
*/
|
|
198
|
+
export declare function importersOf(graph: ThirdPartyGraph, targets: string | readonly string[]): readonly string[];
|
|
199
|
+
export type { ClosureEdge, ClosureEdges, EdgeKind, EdgeTarget, GraphEdge, GraphEntry, GraphNode, GraphOptions, Scan, ScannedEdge, ThirdPartyGraph };
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import { a as esmSyntaxOf, i as inGraph, l as graphCacheKey, n as packageDirOf, o as initLexer, r as buildThirdPartyGraph, s as scanSource, t as importersOf } from "../graph.js";
|
|
2
|
+
|
|
3
|
+
export { buildThirdPartyGraph, esmSyntaxOf, graphCacheKey, importersOf, inGraph, initLexer, packageDirOf, scanSource };
|