@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.
@@ -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 };