@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/dist/index.d.ts
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
import { CacheMode } from "@provino/transform/v8cache";
|
|
2
|
+
import { CoverageInstrumenter, CreateLoader, IsolationTier, Loader, ModulePolicy, Pragmas, Resolver, SerializedLoaderConfig, SourceMapV3, TierChoice, TierSources } from "@provino/types";
|
|
3
|
+
/**
|
|
4
|
+
* Coverage for a project's loader (B23b): the Istanbul instrumenter its pipeline calls on a file
|
|
5
|
+
* requested with `instrument: true`, and which files those are.
|
|
6
|
+
* @public
|
|
7
|
+
*/
|
|
8
|
+
interface ProjectCoverage {
|
|
9
|
+
readonly instrumenter: CoverageInstrumenter;
|
|
10
|
+
/** Whether the user module at this absolute path is instrumented (`createCoverageFilter`). */
|
|
11
|
+
readonly shouldInstrument: (path: string) => boolean;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Options for `createProjectLoader`.
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
interface ProjectLoaderOptions {
|
|
18
|
+
readonly coverage?: ProjectCoverage;
|
|
19
|
+
/**
|
|
20
|
+
* Whether the wrapper scripts use V8's code cache in `config.cacheDir` (`LoaderOptions.codeCache`,
|
|
21
|
+
* B23e). Default `'off'`. The worker passes `'on'` unless its project collects coverage (T3.7's
|
|
22
|
+
* rule, `cacheModeFor`: V8 reports no block ranges for a function restored from a code cache);
|
|
23
|
+
* `coverage` here turns it off whatever this says, and so does a config with no `cacheDir`
|
|
24
|
+
* (`--no-cache`).
|
|
25
|
+
*/
|
|
26
|
+
readonly codeCache?: CacheMode;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Creates the worker's loader for one project. `config.mappers` are loaded by `ModuleRef` first,
|
|
30
|
+
* which is why this is async. Mock hoisting follows `config.hoist` (the dialect's policy, by
|
|
31
|
+
* value), and every module's wrapper declares `config.moduleScope`'s names. `config.transform`'s
|
|
32
|
+
* transformers are loaded here, in the worker, from their own paths (T3.8); a file one of them
|
|
33
|
+
* matches goes through it, every other file through Oxc. `config.cacheDir` turns the transform cache
|
|
34
|
+
* on (T3.6): a file's record is read from it before any work and written after.
|
|
35
|
+
* @public
|
|
36
|
+
*/
|
|
37
|
+
export declare function createProjectLoader(root: string, config: SerializedLoaderConfig, policy: ModulePolicy, options?: ProjectLoaderOptions): Promise<Loader>;
|
|
38
|
+
/**
|
|
39
|
+
* A loader for modules the coordinator runs itself.
|
|
40
|
+
* @public
|
|
41
|
+
*/
|
|
42
|
+
interface CoordinatorLoader extends Disposable {
|
|
43
|
+
/**
|
|
44
|
+
* Imports the module at `file` (an absolute path) through the project's transform, and resolves
|
|
45
|
+
* with its exports as an `import` sees them under the policy's `interopDefault`. The module
|
|
46
|
+
* itself is never mocked. A module imported twice is evaluated once.
|
|
47
|
+
*/
|
|
48
|
+
import<T = unknown>(file: string): Promise<T>;
|
|
49
|
+
/**
|
|
50
|
+
* `file` (an absolute path) transformed as a worker transforms a covered file: through the
|
|
51
|
+
* project's transform with the instrumenter, before the module-runner rewrite. For files the
|
|
52
|
+
* tests never loaded. Needs the loader to have been created with `coverage`. A file the transform
|
|
53
|
+
* fails on throws `LOADER_TRANSFORM_FAILED`.
|
|
54
|
+
*/
|
|
55
|
+
transformForCoverage(file: string): {
|
|
56
|
+
readonly code: string;
|
|
57
|
+
readonly map: SourceMapV3 | null;
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* What `specifier` imported from `from` (an absolute path) resolves to, as a `require` resolves
|
|
61
|
+
* it under the project's mappers, or `undefined` when it doesn't resolve or is a Node builtin
|
|
62
|
+
* no mapper takes. For the affected-test graph (B23c). `options.conditions` replaces the
|
|
63
|
+
* project's export conditions (the call's `require` is added either way). Under the config's
|
|
64
|
+
* `skipNodeResolution`, a specifier with no path separator resolves only through a mapper, as
|
|
65
|
+
* jest-resolve's `_prepareForResolution` skips its node lookup.
|
|
66
|
+
*/
|
|
67
|
+
resolveDependency(specifier: string, from: string, options?: {
|
|
68
|
+
readonly conditions?: readonly string[];
|
|
69
|
+
}): string | undefined;
|
|
70
|
+
/**
|
|
71
|
+
* Drops the resolver's file-system caches (for the given paths, or all of them): call it when
|
|
72
|
+
* files were added or removed, or a specifier that missed would keep missing.
|
|
73
|
+
*/
|
|
74
|
+
invalidateResolution(paths?: readonly string[]): void;
|
|
75
|
+
/** Forgets every module; further imports start over. */
|
|
76
|
+
dispose(): void;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Creates the coordinator-mode loader of one project: its resolver, mappers and transform (the
|
|
80
|
+
* Jest transformers load here, in this process, from their own paths), at the isolation tier
|
|
81
|
+
* `none`. `config` is the project's `SerializedLoaderConfig`, the one its workers build theirs
|
|
82
|
+
* from, so a file resolves and transforms here as it does there.
|
|
83
|
+
* @public
|
|
84
|
+
*/
|
|
85
|
+
export declare function createCoordinatorLoader(root: string, config: SerializedLoaderConfig, policy: ModulePolicy, options?: {
|
|
86
|
+
readonly coverage?: ProjectCoverage;
|
|
87
|
+
}): Promise<CoordinatorLoader>;
|
|
88
|
+
/**
|
|
89
|
+
* Error codes `@provino/loader` throws. `ERR_REQUIRE_ASYNC_MODULE` keeps Node's code, since tests
|
|
90
|
+
* match on it; a module that isn't found is a `ModuleNotFoundError`, with Node's codes.
|
|
91
|
+
* @public
|
|
92
|
+
*/
|
|
93
|
+
type LoaderErrorCode = "LOADER_NOT_IMPLEMENTED" | "LOADER_TRANSFORM_FAILED" | "LOADER_UNSUPPORTED_MODULE" | "LOADER_TSCONFIG_NOT_FOUND" | "LOADER_INVALID_MAPPER" | "LOADER_NO_MODULE_MOCKS" | "LOADER_NO_REAL_MODULE" | "LOADER_UNRESOLVED_MOCK" | "LOADER_INVALID_TRANSFORM_CLAIMS" | "ERR_REQUIRE_ASYNC_MODULE";
|
|
94
|
+
/**
|
|
95
|
+
* A specifier that doesn't resolve, thrown when its import or `require` runs. Its `name` stays
|
|
96
|
+
* `Error`, as Node's own not-found errors and jest-resolve's `ModuleNotFoundError` have it, since
|
|
97
|
+
* tests print and compare it; the text is the dialect's (`module-not-found`).
|
|
98
|
+
* @public
|
|
99
|
+
*/
|
|
100
|
+
export declare class ModuleNotFoundError extends Error {
|
|
101
|
+
readonly code: "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
|
|
102
|
+
constructor(code: "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND", message: string);
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* A `node_modules` file with ES module syntax that no transform takes and Node could not load,
|
|
106
|
+
* in the dialect's words (`require-esm`, Jest's `Must use import to load ES Module`). Its `name`
|
|
107
|
+
* stays `Error` and its code is Node's, as Jest's own error has them; its `cause` is Node's error.
|
|
108
|
+
* @public
|
|
109
|
+
*/
|
|
110
|
+
export declare class RequireEsmError extends Error {
|
|
111
|
+
readonly code: "ERR_REQUIRE_ESM";
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* A loader error with a stable code.
|
|
115
|
+
* @public
|
|
116
|
+
*/
|
|
117
|
+
export declare class LoaderError extends Error {
|
|
118
|
+
readonly code: LoaderErrorCode;
|
|
119
|
+
constructor(code: LoaderErrorCode, message: string, options?: ErrorOptions);
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Creates a worker's loader.
|
|
123
|
+
* @public
|
|
124
|
+
*/
|
|
125
|
+
export declare const createLoader: CreateLoader;
|
|
126
|
+
/**
|
|
127
|
+
* The `ModulePolicy` keys that turn on evaluating shared externals per file.
|
|
128
|
+
* @public
|
|
129
|
+
*/
|
|
130
|
+
type ReevaluateKey = Extract<keyof ModulePolicy, `reevaluate${string}`>;
|
|
131
|
+
/**
|
|
132
|
+
* Every reevaluate key off: what a loader that outlives its files spreads over its policy (the
|
|
133
|
+
* coordinator's). A new key fails to compile here until it is listed.
|
|
134
|
+
* @public
|
|
135
|
+
*/
|
|
136
|
+
export declare const NO_REEVALUATION: { readonly [K in ReevaluateKey]: false; };
|
|
137
|
+
/**
|
|
138
|
+
* Whether a policy evaluates shared externals per file: any reevaluate key on. The loader then
|
|
139
|
+
* opens a window on each external's first load and inlines what it learns; what a window counts
|
|
140
|
+
* (a read, a write) is the worker's watcher's business.
|
|
141
|
+
* @public
|
|
142
|
+
*/
|
|
143
|
+
export declare function reevaluatesExternals(policy: Pick<ModulePolicy, ReevaluateKey>): boolean;
|
|
144
|
+
/** How `installSourceMappedStacks` reads a frame. */
|
|
145
|
+
interface StackOptions {
|
|
146
|
+
/**
|
|
147
|
+
* `mapped-name` names a frame after the name its map holds at the frame's own position
|
|
148
|
+
* (`ModulePolicy.stackFrameNames`); `engine` (the default) keeps the name V8 gave it.
|
|
149
|
+
*/
|
|
150
|
+
readonly frameNames?: "mapped-name" | "engine";
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Installs an `Error.prepareStackTrace` that maps each frame in a module `loader` compiled through
|
|
154
|
+
* that module's source map, then formats the stack with the formatter it found (Node's own, which
|
|
155
|
+
* keeps Node's header for its coded errors). A frame keeps its file and its function name; only
|
|
156
|
+
* its line and column change, and only when the map has a segment on the frame's own line at or
|
|
157
|
+
* before its column (the lookup `source-map-support` and `@jridgewell/trace-mapping` make). A
|
|
158
|
+
* frame the map can't place, or one in a file the loader didn't compile, stays as V8 gave it.
|
|
159
|
+
* The formatter also carries the frame mapper itself, under `MAP_CALL_SITES`. Returns the
|
|
160
|
+
* uninstall, which puts the previous formatter back if this one is still installed.
|
|
161
|
+
* Process-wide: the worker installs it once, after it made its loader.
|
|
162
|
+
* @public
|
|
163
|
+
*/
|
|
164
|
+
export declare function installSourceMappedStacks(loader: Pick<Loader, "getSourceMap">, options?: StackOptions): () => void;
|
|
165
|
+
/** The docblock pragma that raises a file's tier: `@provino-isolate realm`. */
|
|
166
|
+
export declare const ISOLATE_PRAGMA = "provino-isolate";
|
|
167
|
+
/** Whether `value` names an isolation tier. */
|
|
168
|
+
export declare function isIsolationTier(value: string): value is IsolationTier;
|
|
169
|
+
/**
|
|
170
|
+
* The tier a test file runs at, from the sources that name one.
|
|
171
|
+
*
|
|
172
|
+
* - It **raises and never lowers**: a docblock or a learned tier below the project's changes
|
|
173
|
+
* nothing (and says nothing: a shared template may name a tier a stricter project already
|
|
174
|
+
* exceeds).
|
|
175
|
+
* - A `@provino-isolate` value that is not a tier (`none`, `registry`, `realm`, `process`) is
|
|
176
|
+
* ignored with a warning, and the file keeps what the other sources give it. A pragma given
|
|
177
|
+
* twice counts each value.
|
|
178
|
+
* - When two sources name the tier chosen, `source` is the first of `config`, `docblock`,
|
|
179
|
+
* `learned`.
|
|
180
|
+
* - `testFile` only names the file in a warning.
|
|
181
|
+
* @public
|
|
182
|
+
*/
|
|
183
|
+
export declare function tierFor(testFile: string, sources: TierSources): TierChoice;
|
|
184
|
+
/**
|
|
185
|
+
* The `@provino-isolate` pragma of the leading block comment of `source`, as `Pragmas`; `undefined`
|
|
186
|
+
* when there is none. The grammar is jest-docblock's for one pragma: the first comment only (after
|
|
187
|
+
* whitespace), an optional `*` before each line, `@provino-isolate value` on its own line, `//`
|
|
188
|
+
* comments dropped from the value, and a repeated pragma as a list. A comment that is not closed
|
|
189
|
+
* has no pragma.
|
|
190
|
+
* @public
|
|
191
|
+
*/
|
|
192
|
+
export declare function isolatePragmaOf(source: string): Pragmas | undefined;
|
|
193
|
+
/**
|
|
194
|
+
* `isolatePragmaOf` of the file at `path`, reading its first 4 KiB (all of it when the leading
|
|
195
|
+
* comment does not end there). A file that can't be read has no pragma: the worker reports it
|
|
196
|
+
* when it loads the file.
|
|
197
|
+
* @public
|
|
198
|
+
*/
|
|
199
|
+
export declare function readIsolatePragma(path: string): Promise<Pragmas | undefined>;
|
|
200
|
+
export type { CoordinatorLoader, LoaderErrorCode, ProjectCoverage, ProjectLoaderOptions, ReevaluateKey, StackOptions };
|