@provino/snapshot 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 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/snapshot
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 snapshot engine: the `.snap` file format, the per-file state machine, and the coordinator's update mode and totals. A dialect supplies the printer and the words.
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,266 @@
1
+ # Third-party notices
2
+
3
+ Provino includes code copied from the projects below. Each vendor directory has an `UPSTREAM.md` naming the source, the version and every local change.
4
+
5
+ This file is the license notice for that code. Source files keep the license header they had upstream, but the build does not carry every header into a package's `dist`: it keeps some and drops others, and a few copied files never had one (`natural-compare`'s only says `@license MIT License`; Vitest's `jsdom-keys.ts` and `.each` title code have none). So the published `provino` package, and every other package whose `dist` holds copied code (`@provino/dialect-jest`, `@provino/dialect-vitest`, `@provino/snapshot`, `@provino/env-shared` and `@provino/coverage`), ships this file as `THIRD_PARTY_NOTICES.md`, and `pnpm hygiene` fails a package that holds copied code without it. Each of those copies must equal this file.
6
+
7
+ ## Jest
8
+
9
+ `packages/dialect-jest/src/runtime/vendor/jest-expect/` is copied from Jest v30.5.2 (https://github.com/jestjs/jest).
10
+
11
+ `packages/dialect-jest/src/runtime/vendor/jest-circus/` is copied from Jest v30.5.2 (`jest-circus`'s `src/formatNodeAssertErrors.ts`).
12
+
13
+ `packages/dialect-jest/src/each/vendor/jest-each/` is copied from Jest v30.5.2 (`jest-each`'s `table/array.ts` and `table/interpolation.ts`, and one function of `jest-regex-util`).
14
+
15
+ `packages/dialect-jest/src/runtime/vendor/jest-snapshot/` and `packages/snapshot/src/vendor/deep-merge.ts` are copied from Jest v30.5.2, `packages/jest-snapshot/src/mockSerializer.ts` and `utils.ts`.
16
+
17
+ Smaller copies from Jest v30.5.x that have no vendor directory, each with its source named in the file's own comments:
18
+
19
+ - `packages/dialect-jest/src/node/cli-table.ts` is jest-cli's table of command-line options, with each option's description (`src/args.ts`).
20
+ - `packages/dialect-jest/src/node/valid-config.ts` is jest-config's example configs that validation checks against (`ValidConfig.ts`).
21
+ - `packages/dialect-jest/src/node/text.ts` holds message texts from jest-config and jest-validate.
22
+ - `packages/dialect-jest/src/node/docblock.ts` and `packages/orchestrator/src/worker/internal/runtime/pragmas.ts` hold the regular expressions of jest-docblock's `extract` and `parse` (`index.ts`).
23
+
24
+ `packages/harness/src/hoist-corpus/vendor/jest.json` holds test inputs copied from Jest v30.5.2, `packages/babel-plugin-jest-hoist/src/__tests__/hoistPlugin.nodejs18.test.ts`. Same MIT license as below. It is not part of any published package.
25
+
26
+ ```
27
+ MIT License
28
+
29
+ Copyright (c) Meta Platforms, Inc. and affiliates.
30
+ Copyright Contributors to the Jest project.
31
+
32
+ Permission is hereby granted, free of charge, to any person obtaining a copy
33
+ of this software and associated documentation files (the "Software"), to deal
34
+ in the Software without restriction, including without limitation the rights
35
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
36
+ copies of the Software, and to permit persons to whom the Software is
37
+ furnished to do so, subject to the following conditions:
38
+
39
+ The above copyright notice and this permission notice shall be included in all
40
+ copies or substantial portions of the Software.
41
+
42
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
43
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
44
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
45
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
46
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
47
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
48
+ SOFTWARE.
49
+ ```
50
+
51
+ ## Vitest
52
+
53
+ `packages/dialect-vitest/src/vendor/pretty-format/` is copied from Vitest v5.0.5 (https://github.com/vitest-dev/vitest), `packages/pretty-format/src/` and `packages/snapshot/src/port/mockSerializer.ts`; the files keep the Meta Platforms license header they were forked with (`mockSerializer.ts` is Jest's, under its older "Facebook, Inc." name: the Jest license above).
54
+
55
+ `packages/harness/src/hoist-corpus/vendor/vitest.json` holds test inputs copied from Vitest v5.0.5 (https://github.com/vitest-dev/vitest), `test/unit/test/injector-mock.test.ts`. It is not part of any published package.
56
+
57
+ `packages/dialect-vitest/src/each/vendor/` is copied from Vitest v5.0.5: `formatTitle` from the runner's `suite.ts`, `display.ts` and parts of `helpers.ts` from `@vitest/utils`, and `@vitest/pretty-format` (a fork of Jest's pretty-format, so its files keep Meta's MIT header).
58
+
59
+ `packages/env-shared/src/vendor/vitest/jsdom-keys.ts` is copied unchanged from Vitest v5.0.5, `packages/vitest/src/integrations/env/jsdom-keys.ts`: the keys jsdom's interfaces and window add. The file has no license header. `provino` ships it, through `@provino/env-shared`.
60
+
61
+ ```
62
+ MIT License
63
+
64
+ Copyright (c) 2021-Present VoidZero Inc. and Vitest contributors
65
+
66
+ Permission is hereby granted, free of charge, to any person obtaining a copy
67
+ of this software and associated documentation files (the "Software"), to deal
68
+ in the Software without restriction, including without limitation the rights
69
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
70
+ copies of the Software, and to permit persons to whom the Software is
71
+ furnished to do so, subject to the following conditions:
72
+
73
+ The above copyright notice and this permission notice shall be included in all
74
+ copies or substantial portions of the Software.
75
+
76
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
77
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
78
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
79
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
80
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
81
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
82
+ SOFTWARE.
83
+ ```
84
+
85
+ ## natural-compare
86
+
87
+ `packages/snapshot/src/vendor/natural-compare.ts` is natural-compare 1.4.0 by Lauri Rooden (https://github.com/litejs/natural-compare-lite), ported to TypeScript. It orders the keys of a `.snap` file as Jest and Vitest do.
88
+
89
+ ```
90
+ MIT License
91
+
92
+ Copyright (c) 2015 Lauri Rooden
93
+
94
+ Permission is hereby granted, free of charge, to any person obtaining a copy
95
+ of this software and associated documentation files (the "Software"), to deal
96
+ in the Software without restriction, including without limitation the rights
97
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
98
+ copies of the Software, and to permit persons to whom the Software is
99
+ furnished to do so, subject to the following conditions:
100
+
101
+ The above copyright notice and this permission notice shall be included in all
102
+ copies or substantial portions of the Software.
103
+
104
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
105
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
106
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
107
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
108
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
109
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
110
+ SOFTWARE.
111
+ ```
112
+
113
+ ## @vitest/istanbul-lib-instrument
114
+
115
+ `packages/coverage/src/vendor/istanbul-lib-instrument/` is copied from `@vitest/istanbul-lib-instrument` 2.1.0 (https://github.com/vitest-dev/istanbuljs, tag `v2.1.0`), Vitest's fork of `istanbul-lib-instrument` that parses with Oxc. It instruments the code for `--coverage`. The package's `LICENSE` holds two licenses: the original `istanbuljs` BSD-3-Clause license (Yahoo! Inc.) and the Vitest MIT license, and both apply.
116
+
117
+ ```
118
+ Copyright 2012-2015 Yahoo! Inc.
119
+ All rights reserved.
120
+
121
+ Redistribution and use in source and binary forms, with or without
122
+ modification, are permitted provided that the following conditions are met:
123
+ * Redistributions of source code must retain the above copyright
124
+ notice, this list of conditions and the following disclaimer.
125
+ * Redistributions in binary form must reproduce the above copyright
126
+ notice, this list of conditions and the following disclaimer in the
127
+ documentation and/or other materials provided with the distribution.
128
+ * Neither the name of the Yahoo! Inc. nor the
129
+ names of its contributors may be used to endorse or promote products
130
+ derived from this software without specific prior written permission.
131
+
132
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
133
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
134
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
135
+ DISCLAIMED. IN NO EVENT SHALL YAHOO! INC. BE LIABLE FOR ANY
136
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
137
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
138
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
139
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
140
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
141
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
142
+
143
+ MIT License
144
+
145
+ Copyright (c) 2021-Present VoidZero Inc. and Vitest contributors
146
+
147
+ Permission is hereby granted, free of charge, to any person obtaining a copy
148
+ of this software and associated documentation files (the "Software"), to deal
149
+ in the Software without restriction, including without limitation the rights
150
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
151
+ copies of the Software, and to permit persons to whom the Software is
152
+ furnished to do so, subject to the following conditions:
153
+
154
+ The above copyright notice and this permission notice shall be included in all
155
+ copies or substantial portions of the Software.
156
+
157
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
158
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
159
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
160
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
161
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
162
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
163
+ SOFTWARE.
164
+ ```
165
+
166
+ ## Jenkins xunit plugin
167
+
168
+ `packages/reporters/src/junit/vendor/junit-10.xsd` is the JUnit schema of the Jenkins xunit plugin (https://github.com/jenkinsci/xunit-plugin, commit `ae25da5089d4f94ac6c4669bf736e4d416cc4665`), copied unchanged. It is used only by the JUnit reporter's test, to check the reporter's output with `xmllint-wasm`. It is not part of any published package. The file carries its own license header:
169
+
170
+ ```
171
+ The MIT License (MIT)
172
+
173
+ Copyright (c) 2014, Gregory Boissinot
174
+
175
+ Permission is hereby granted, free of charge, to any person obtaining a copy
176
+ of this software and associated documentation files (the "Software"), to deal
177
+ in the Software without restriction, including without limitation the rights
178
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
179
+ copies of the Software, and to permit persons to whom the Software is
180
+ furnished to do so, subject to the following conditions:
181
+
182
+ The above copyright notice and this permission notice shall be included in
183
+ all copies or substantial portions of the Software.
184
+
185
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
186
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
187
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
188
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
189
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
190
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
191
+ THE SOFTWARE.
192
+ ```
193
+
194
+ ## vscode-jest
195
+
196
+ `packages/harness/fixtures/cli/reporters-twenty/fixture.json` holds, as the text of a file, the reporter vscode-jest 6.4.4 ships (`extension/out/reporter.js`, from the `vscode-jest-6.4.4.vsix` release asset of the jest-community/vscode-jest repository, tag `v6.4.4`), unmodified; `UPSTREAM.md` beside it has the asset's checksum. The same reporter, unmodified, is the `fixture.json` of each IDE-replay fixture in `packages/harness/fixtures/ide/vscode-jest-all`, `packages/harness/fixtures/ide/vscode-jest-dashed`, `packages/harness/fixtures/ide/vscode-jest-file`, `packages/harness/fixtures/ide/vscode-jest-pattern`, `packages/harness/fixtures/ide/vscode-jest-coverage`, `packages/harness/fixtures/ide/vscode-jest-related`, `packages/harness/fixtures/ide/vscode-jest-watch`, `packages/harness/fixtures/ide/vscode-jest-watch-all`, `packages/harness/fixtures/ide/vscode-jest-test-pattern`, `packages/harness/fixtures/ide/vscode-jest-test`, `packages/harness/fixtures/ide/vscode-jest-update-snapshot`, with an `UPSTREAM.md` beside each. All of these are test fixtures: none is part of any published package. The extension's license:
197
+
198
+ ```
199
+ MIT License
200
+
201
+ Copyright (c) 2016 Orta
202
+
203
+ Permission is hereby granted, free of charge, to any person obtaining a copy
204
+ of this software and associated documentation files (the "Software"), to deal
205
+ in the Software without restriction, including without limitation the rights
206
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
207
+ copies of the Software, and to permit persons to whom the Software is
208
+ furnished to do so, subject to the following conditions:
209
+
210
+ The above copyright notice and this permission notice shall be included in all
211
+ copies or substantial portions of the Software.
212
+
213
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
214
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
215
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
216
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
217
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
218
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
219
+ SOFTWARE.
220
+ ```
221
+
222
+ ## Unicode Character Database
223
+
224
+ `packages/reporters/src/live/terminal/vendor/width-table.ts` is generated from the Unicode Character Database 16.0.0 (`EastAsianWidth.txt` and `emoji-data.txt`, https://www.unicode.org/Public/16.0.0/ucd/) by `packages/reporters/scripts/width-table.ts`, with an `UPSTREAM.md` beside it. It is part of `@provino/reporters` and so of `provino`. The data files' license:
225
+
226
+ ```
227
+ UNICODE LICENSE V3
228
+
229
+ COPYRIGHT AND PERMISSION NOTICE
230
+
231
+ Copyright © 1991-2026 Unicode, Inc.
232
+
233
+ NOTICE TO USER: Carefully read the following legal agreement. BY
234
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
235
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
236
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
237
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
238
+
239
+ Permission is hereby granted, free of charge, to any person obtaining a
240
+ copy of data files and any associated documentation (the "Data Files") or
241
+ software and any associated documentation (the "Software") to deal in the
242
+ Data Files or Software without restriction, including without limitation
243
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
244
+ copies of the Data Files or Software, and to permit persons to whom the
245
+ Data Files or Software are furnished to do so, provided that either (a)
246
+ this copyright and permission notice appear with all copies of the Data
247
+ Files or Software, or (b) this copyright and permission notice appear in
248
+ associated Documentation.
249
+
250
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
251
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
252
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
253
+ THIRD PARTY RIGHTS.
254
+
255
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
256
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
257
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
258
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
259
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
260
+ FILES OR SOFTWARE.
261
+
262
+ Except as contained in this notice, the name of a copyright holder shall
263
+ not be used in advertising or otherwise to promote the sale, use or other
264
+ dealings in these Data Files or Software without prior written
265
+ authorization of the copyright holder.
266
+ ```
@@ -0,0 +1,94 @@
1
+ /**
2
+ * What a `SnapshotError` carries in `code`.
3
+ * @public
4
+ */
5
+ type SnapshotErrorCode = "SNAPSHOT_NO_PRINTER" | "SNAPSHOT_NO_INLINE_FRAME" | "SNAPSHOT_NO_RESOLVER" | "SNAPSHOT_HEADER_MISMATCH" | "SNAPSHOT_NOT_INITIALIZED" | "SNAPSHOT_INLINE_NOT_BUILT" | "SNAPSHOT_BAD_KEY" | "SNAPSHOT_BAD_SERIALIZER";
6
+ /**
7
+ * An error from the snapshot engine. Tests assert on `code`, not on the text.
8
+ * @public
9
+ */
10
+ export declare class SnapshotError extends Error {
11
+ override readonly name = "SnapshotError";
12
+ readonly code: SnapshotErrorCode;
13
+ constructor(code: SnapshotErrorCode, message: string, options?: ErrorOptions);
14
+ }
15
+ /**
16
+ * How a run treats snapshots: `all` rewrites any that differ (`-u`), `new` writes the ones that
17
+ * don't exist yet, `none` writes nothing and fails a missing one (CI). It is what
18
+ * `FileJob.updateSnapshots` carries.
19
+ * @public
20
+ */
21
+ type SnapshotUpdateMode = "all" | "new" | "none";
22
+ /**
23
+ * Where a test file's snapshots live by default: `__snapshots__/<file>.snap` beside it (the
24
+ * policy's `dirName` and `extension`).
25
+ * @public
26
+ */
27
+ export declare function defaultSnapshotPath(testPath: string, layout: {
28
+ readonly dirName: string;
29
+ readonly extension: string;
30
+ }): string;
31
+ /**
32
+ * The snapshots of one file, by key.
33
+ * @public
34
+ */
35
+ type SnapshotData = Record<string, string>;
36
+ /**
37
+ * Writes a `.snap` file's text: the header, then every entry in natural order, a blank line
38
+ * between them, one newline at the end.
39
+ * @public
40
+ */
41
+ export declare function serializeSnapFile(data: Readonly<SnapshotData>, header: string): string;
42
+ /**
43
+ * Runs a `.snap` file's text and returns what it exports. A file that throws gives what it had
44
+ * exported by then, as in Jest; the header check is what reports it.
45
+ * @public
46
+ */
47
+ export declare function evaluateSnapFile(text: string): SnapshotData;
48
+ /**
49
+ * `null` when the file starts with `header`, else why it doesn't. Text, no colour.
50
+ * @public
51
+ */
52
+ export declare function checkSnapHeader(text: string, header: string): string | null;
53
+ /**
54
+ * The key of the n-th snapshot of a test, back to the test's name: the number at the end goes.
55
+ * @public
56
+ */
57
+ export declare function keyToTestName(key: string): string;
58
+ /**
59
+ * Escapes a snapshot for a template literal: a backtick, a backslash and `${`.
60
+ * @public
61
+ */
62
+ export declare const escapeBacktickString: (text: string) => string;
63
+ /**
64
+ * A snapshot as the template literal a `.snap` file holds.
65
+ * @public
66
+ */
67
+ export declare const printBacktickString: (text: string) => string;
68
+ /**
69
+ * `\r\n` and `\r` become `\n`.
70
+ * @public
71
+ */
72
+ export declare const normalizeNewlines: (text: string) => string;
73
+ /**
74
+ * Pads a multi-line snapshot with a line break at each end, so the file reads easier.
75
+ * @public
76
+ */
77
+ export declare const addExtraLineBreaks: (text: string) => string;
78
+ /**
79
+ * Takes the padding off again. Not `trim`, which would also eat blank lines and spaces a custom
80
+ * serializer meant.
81
+ * @public
82
+ */
83
+ export declare const removeExtraLineBreaks: (text: string) => string;
84
+ /**
85
+ * Merges `source` (a snapshot's property matchers) into `target` (the received value).
86
+ * @public
87
+ */
88
+ export declare function deepMerge(target: unknown, source: unknown): unknown;
89
+ /**
90
+ * Orders strings so that numbers inside them compare as numbers: `numbers 2` before `numbers 10`.
91
+ * @public
92
+ */
93
+ export declare function naturalCompare(first: string, second: string): number;
94
+ export type { SnapshotData, SnapshotErrorCode, SnapshotUpdateMode };
package/dist/index.js ADDED
@@ -0,0 +1,188 @@
1
+ import { basename, dirname, join } from "node:path";
2
+
3
+ // src/errors.ts
4
+ /**
5
+ * An error from the snapshot engine. Tests assert on `code`, not on the text.
6
+ * @public
7
+ */
8
+ var SnapshotError = class extends Error {
9
+ name = "SnapshotError";
10
+ code;
11
+ constructor(code, message, options) {
12
+ super(message, options);
13
+ this.code = code;
14
+ }
15
+ };
16
+
17
+ // src/paths.ts
18
+ /**
19
+ * Where a test file's snapshots live by default: `__snapshots__/<file>.snap` beside it (the
20
+ * policy's `dirName` and `extension`).
21
+ * @public
22
+ */
23
+ function defaultSnapshotPath(testPath, layout) {
24
+ return join(dirname(testPath), layout.dirName, `${basename(testPath)}${layout.extension}`);
25
+ }
26
+
27
+ // src/text.ts
28
+ /**
29
+ * Escapes a snapshot for a template literal: a backtick, a backslash and `${`.
30
+ * @public
31
+ */
32
+ const escapeBacktickString = (text) => text.replaceAll(/`|\\|\$\{/g, "\\$&");
33
+ /**
34
+ * A snapshot as the template literal a `.snap` file holds.
35
+ * @public
36
+ */
37
+ const printBacktickString = (text) => `\`${escapeBacktickString(text)}\``;
38
+ /**
39
+ * `\r\n` and `\r` become `\n`.
40
+ * @public
41
+ */
42
+ const normalizeNewlines = (text) => text.replaceAll(/\r\n|\r/g, "\n");
43
+ /**
44
+ * Pads a multi-line snapshot with a line break at each end, so the file reads easier.
45
+ * @public
46
+ */
47
+ const addExtraLineBreaks = (text) => text.includes("\n") ? `\n${text}\n` : text;
48
+ /**
49
+ * Takes the padding off again. Not `trim`, which would also eat blank lines and spaces a custom
50
+ * serializer meant.
51
+ * @public
52
+ */
53
+ const removeExtraLineBreaks = (text) => text.length > 2 && text.startsWith("\n") && text.endsWith("\n") ? text.slice(1, -1) : text;
54
+
55
+ // src/vendor/natural-compare.ts
56
+ /*
57
+ * natural-compare 1.4.0 (https://github.com/litejs/natural-compare-lite)
58
+ * @author Lauri Rooden
59
+ * @license MIT License
60
+ *
61
+ * The comparison both Jest and Vitest sort a `.snap` file's keys with, ported to TypeScript.
62
+ */
63
+ /**
64
+ * Orders strings so that numbers inside them compare as numbers: `numbers 2` before `numbers 10`.
65
+ * @public
66
+ */
67
+ function naturalCompare(first, second) {
68
+ let index = 0;
69
+ let codeA = 0;
70
+ let codeB = 1;
71
+ let posA = 0;
72
+ let posB = 0;
73
+ function getCode(text, pos, numeric) {
74
+ if (numeric) {
75
+ const isDigit = (at) => {
76
+ const code = getCode(text, at, false);
77
+ return code < 76 && code > 65;
78
+ };
79
+ index = pos;
80
+ while (isDigit(index)) ++index;
81
+ return +text.slice(pos - 1, index);
82
+ }
83
+ const code = text.charCodeAt(pos) || 0;
84
+ if (code < 45 || code > 127) return code;
85
+ if (code < 46) return 65;
86
+ if (code < 48) return code - 1;
87
+ if (code < 58) return code + 18;
88
+ if (code < 65) return code - 11;
89
+ if (code < 91) return code + 11;
90
+ if (code < 97) return code - 37;
91
+ if (code < 123) return code + 5;
92
+ return code - 63;
93
+ }
94
+ const a = `${first}`;
95
+ const b = `${second}`;
96
+ if (a !== b) while (codeB) {
97
+ codeA = getCode(a, posA++, false);
98
+ codeB = getCode(b, posB++, false);
99
+ if (codeA < 76 && codeB < 76 && codeA > 66 && codeB > 66) {
100
+ codeA = getCode(a, posA, true);
101
+ posA = index;
102
+ codeB = getCode(b, posB, true);
103
+ posB = index;
104
+ }
105
+ if (codeA !== codeB) return codeA < codeB ? -1 : 1;
106
+ }
107
+ return 0;
108
+ }
109
+
110
+ // src/snap-file.ts
111
+ /**
112
+ * Writes a `.snap` file's text: the header, then every entry in natural order, a blank line
113
+ * between them, one newline at the end.
114
+ * @public
115
+ */
116
+ function serializeSnapFile(data, header) {
117
+ return `${header}\n\n${Object.keys(data).sort(naturalCompare).map((key) => `exports[${printBacktickString(key)}] = ${printBacktickString(normalizeNewlines(data[key] ?? ""))};`).join("\n\n")}\n`;
118
+ }
119
+ /**
120
+ * Runs a `.snap` file's text and returns what it exports. A file that throws gives what it had
121
+ * exported by then, as in Jest; the header check is what reports it.
122
+ * @public
123
+ */
124
+ function evaluateSnapFile(text) {
125
+ const data = Object.create(null);
126
+ try {
127
+ new Function("exports", text)(data);
128
+ } catch {}
129
+ return data;
130
+ }
131
+ /**
132
+ * `null` when the file starts with `header`, else why it doesn't. Text, no colour.
133
+ * @public
134
+ */
135
+ function checkSnapHeader(text, header) {
136
+ const first = (text.split("\n", 1)[0] ?? "").replace(/\r$/, "");
137
+ if (first === header) return null;
138
+ if (!/^\/\/ .*\bv\d+/.test(first)) return `Outdated snapshot: no snapshot header found. The file must start with "${header}". Update the snapshots of this file to write it.`;
139
+ return `Outdated snapshot: the file's header is "${first}", and this project's is "${header}". Update the snapshots of this file to write the right one.`;
140
+ }
141
+ /**
142
+ * The key of the n-th snapshot of a test, back to the test's name: the number at the end goes.
143
+ * @public
144
+ */
145
+ function keyToTestName(key) {
146
+ if (!/ \d+$/.test(key)) throw new SnapshotError("SNAPSHOT_BAD_KEY", `Snapshot keys must end with a number: "${key}"`);
147
+ return key.replace(/ \d+$/, "");
148
+ }
149
+
150
+ // src/vendor/deep-merge.ts
151
+ function isObject(item) {
152
+ return item != null && typeof item === "object" && !Array.isArray(item);
153
+ }
154
+ function isAnyOrAnything(input) {
155
+ return "$$typeof" in input && input.$$typeof === Symbol.for("jest.asymmetricMatcher") && ["Any", "Anything"].includes(input.constructor.name);
156
+ }
157
+ function deepMergeArray(target, source) {
158
+ const mergedOutput = [...target];
159
+ for (const [index, sourceElement] of source.entries()) {
160
+ const targetElement = mergedOutput[index];
161
+ if (Array.isArray(target[index]) && Array.isArray(sourceElement)) mergedOutput[index] = deepMergeArray(target[index], sourceElement);
162
+ else if (isObject(targetElement) && !isAnyOrAnything(sourceElement)) mergedOutput[index] = deepMerge(target[index], sourceElement);
163
+ else mergedOutput[index] = sourceElement;
164
+ }
165
+ return mergedOutput;
166
+ }
167
+ /**
168
+ * Merges `source` (a snapshot's property matchers) into `target` (the received value).
169
+ * @public
170
+ */
171
+ function deepMerge(target, source) {
172
+ if (isObject(target) && isObject(source)) {
173
+ const mergedOutput = { ...target };
174
+ for (const key of Object.keys(source)) {
175
+ const value = source[key];
176
+ if (isObject(value) && !value.$$typeof) {
177
+ if (key in target) mergedOutput[key] = deepMerge(target[key], value);
178
+ else Object.assign(mergedOutput, { [key]: value });
179
+ } else if (Array.isArray(value)) mergedOutput[key] = deepMergeArray(target[key], value);
180
+ else Object.assign(mergedOutput, { [key]: value });
181
+ }
182
+ return mergedOutput;
183
+ }
184
+ if (Array.isArray(target) && Array.isArray(source)) return deepMergeArray(target, source);
185
+ return target;
186
+ }
187
+
188
+ export { SnapshotError, addExtraLineBreaks, checkSnapHeader, deepMerge, defaultSnapshotPath, escapeBacktickString, evaluateSnapFile, keyToTestName, naturalCompare, normalizeNewlines, printBacktickString, removeExtraLineBreaks, serializeSnapFile };