@provino/loader 0.0.0-stage → 0.1.0-rc.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/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
- # Temporary Holding Version
1
+ # @provino/loader
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 that is pre-alpha and not on npm yet. 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 };