@bymaksym/loadline 0.1.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.
Files changed (98) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -0
  3. package/bin/loadline.js +50 -0
  4. package/dist/cli/cli/args.js +324 -0
  5. package/dist/cli/cli/args.types.js +3 -0
  6. package/dist/cli/cli/gates.js +173 -0
  7. package/dist/cli/cli/gates.types.js +3 -0
  8. package/dist/cli/cli/main.js +156 -0
  9. package/dist/cli/cli/read-build.js +382 -0
  10. package/dist/cli/cli/read-build.types.js +3 -0
  11. package/dist/cli/cli/render-json.js +116 -0
  12. package/dist/cli/cli/render-json.types.js +10 -0
  13. package/dist/cli/cli/render-markdown.js +30 -0
  14. package/dist/cli/cli/render-pr.js +76 -0
  15. package/dist/cli/cli/render-sarif.js +83 -0
  16. package/dist/cli/cli/render-text.js +388 -0
  17. package/dist/cli/cli/report.js +196 -0
  18. package/dist/cli/cli/report.types.js +3 -0
  19. package/dist/cli/cli/self-check.js +85 -0
  20. package/dist/cli/cli/text.js +180 -0
  21. package/dist/cli/cli/text.types.js +10 -0
  22. package/dist/cli/src/app/core/analysis/analysis.js +661 -0
  23. package/dist/cli/src/app/core/analysis/analysis.types.js +6 -0
  24. package/dist/cli/src/app/core/analysis/barrels.js +128 -0
  25. package/dist/cli/src/app/core/analysis/blast.js +172 -0
  26. package/dist/cli/src/app/core/analysis/cycles.js +110 -0
  27. package/dist/cli/src/app/core/analysis/delivery.js +143 -0
  28. package/dist/cli/src/app/core/analysis/entries.js +217 -0
  29. package/dist/cli/src/app/core/analysis/exclusive.js +91 -0
  30. package/dist/cli/src/app/core/analysis/importers.js +38 -0
  31. package/dist/cli/src/app/core/analysis/insights.js +202 -0
  32. package/dist/cli/src/app/core/analysis/insights.types.js +10 -0
  33. package/dist/cli/src/app/core/analysis/invariant.js +69 -0
  34. package/dist/cli/src/app/core/analysis/metafile.types.js +44 -0
  35. package/dist/cli/src/app/core/analysis/module-graph.js +192 -0
  36. package/dist/cli/src/app/core/analysis/sourcemap.js +231 -0
  37. package/dist/cli/src/app/core/analysis/sourcemap.types.js +3 -0
  38. package/dist/cli/src/app/core/analysis/split-drift.js +47 -0
  39. package/dist/cli/src/app/core/assets/assets.js +296 -0
  40. package/dist/cli/src/app/core/assets/assets.types.js +11 -0
  41. package/dist/cli/src/app/core/baseline/baseline.js +0 -0
  42. package/dist/cli/src/app/core/baseline/baseline.types.js +3 -0
  43. package/dist/cli/src/app/core/caching/caching.js +241 -0
  44. package/dist/cli/src/app/core/caching/caching.types.js +10 -0
  45. package/dist/cli/src/app/core/caching/from-analysis.js +73 -0
  46. package/dist/cli/src/app/core/config/loadline-config.js +110 -0
  47. package/dist/cli/src/app/core/config/loadline-config.types.js +12 -0
  48. package/dist/cli/src/app/core/criteria/criteria.js +228 -0
  49. package/dist/cli/src/app/core/criteria/criteria.types.js +3 -0
  50. package/dist/cli/src/app/core/deps/deps.js +225 -0
  51. package/dist/cli/src/app/core/deps/deps.types.js +15 -0
  52. package/dist/cli/src/app/core/export/markdown-table.utils.js +40 -0
  53. package/dist/cli/src/app/core/export/summary.js +72 -0
  54. package/dist/cli/src/app/core/findings/actions.js +59 -0
  55. package/dist/cli/src/app/core/findings/assets.js +130 -0
  56. package/dist/cli/src/app/core/findings/caching.js +165 -0
  57. package/dist/cli/src/app/core/findings/compose.js +41 -0
  58. package/dist/cli/src/app/core/findings/deps.js +66 -0
  59. package/dist/cli/src/app/core/findings/effort.js +117 -0
  60. package/dist/cli/src/app/core/findings/finding-html.js +13 -0
  61. package/dist/cli/src/app/core/findings/finding-plain.js +26 -0
  62. package/dist/cli/src/app/core/findings/finding-text.js +1231 -0
  63. package/dist/cli/src/app/core/findings/finding.types.js +80 -0
  64. package/dist/cli/src/app/core/findings/findings.js +514 -0
  65. package/dist/cli/src/app/core/findings/graph.js +167 -0
  66. package/dist/cli/src/app/core/findings/own-in-boot.js +88 -0
  67. package/dist/cli/src/app/core/findings/page.js +49 -0
  68. package/dist/cli/src/app/core/findings/requests.js +185 -0
  69. package/dist/cli/src/app/core/findings/scan.js +126 -0
  70. package/dist/cli/src/app/core/findings/shipped.js +244 -0
  71. package/dist/cli/src/app/core/findings/situation.js +116 -0
  72. package/dist/cli/src/app/core/format/format.utils.js +204 -0
  73. package/dist/cli/src/app/core/i18n/en.js +819 -0
  74. package/dist/cli/src/app/core/i18n/es.js +822 -0
  75. package/dist/cli/src/app/core/i18n/ui-strings.js +11 -0
  76. package/dist/cli/src/app/core/i18n/ui.js +7 -0
  77. package/dist/cli/src/app/core/intake/bundle-graph.js +346 -0
  78. package/dist/cli/src/app/core/intake/bundle-graph.types.js +3 -0
  79. package/dist/cli/src/app/core/intake/dist-files.js +160 -0
  80. package/dist/cli/src/app/core/intake/index-html.js +292 -0
  81. package/dist/cli/src/app/core/json/json.utils.js +55 -0
  82. package/dist/cli/src/app/core/measurement/measurement.types.js +14 -0
  83. package/dist/cli/src/app/core/project/budget-advice.js +76 -0
  84. package/dist/cli/src/app/core/project/project-context.js +394 -0
  85. package/dist/cli/src/app/core/project/project-context.types.js +3 -0
  86. package/dist/cli/src/app/core/scan/catalog.js +67 -0
  87. package/dist/cli/src/app/core/scan/scan.js +280 -0
  88. package/dist/cli/src/app/core/scan/scan.types.js +10 -0
  89. package/dist/cli/src/app/core/scan/secrets.js +0 -0
  90. package/dist/cli/src/app/core/situation/situation.js +261 -0
  91. package/dist/cli/src/app/core/situation/situation.types.js +19 -0
  92. package/dist/cli/src/app/core/timing/timing.js +87 -0
  93. package/dist/cli/src/app/core/timing/timing.types.js +3 -0
  94. package/dist/cli/src/app/core/whatif/defer.js +68 -0
  95. package/dist/cli/src/app/state/report-messages.utils.js +73 -0
  96. package/docs/HOW-IT-WORKS.md +1087 -0
  97. package/loadline.html +78 -0
  98. package/package.json +154 -0
@@ -0,0 +1,296 @@
1
+ "use strict";
2
+ /**
3
+ * Reading the build folder for everything that is not JavaScript.
4
+ *
5
+ * Every figure here comes from files that were already in the folder somebody dropped, or from the
6
+ * text of chunks that were already open. Nothing is fetched, nothing is recompressed, and — the
7
+ * rule that decides the shape of this file — **nothing is estimated**. "This PNG would be 310 kB in
8
+ * AVIF" is a number nobody measured; what gets said instead is what it weighs, what format it is
9
+ * in, and whether a modern version of it is sitting in the same folder.
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.readAssets = exports.kindOf = exports.extensionOf = void 0;
13
+ const json_utils_1 = require("../json/json.utils");
14
+ const EXTENSIONS = {
15
+ js: 'script',
16
+ mjs: 'script',
17
+ cjs: 'script',
18
+ css: 'style',
19
+ woff: 'font',
20
+ woff2: 'font',
21
+ ttf: 'font',
22
+ otf: 'font',
23
+ eot: 'font',
24
+ png: 'image',
25
+ jpg: 'image',
26
+ jpeg: 'image',
27
+ gif: 'image',
28
+ webp: 'image',
29
+ avif: 'image',
30
+ svg: 'image',
31
+ ico: 'image',
32
+ bmp: 'image',
33
+ mp4: 'video',
34
+ webm: 'video',
35
+ mov: 'video',
36
+ mp3: 'audio',
37
+ ogg: 'audio',
38
+ wav: 'audio',
39
+ map: 'map',
40
+ };
41
+ /** Formats a newer one supersedes, when both are in the folder. Fonts first, then pictures. */
42
+ const SUPERSEDED_BY = {
43
+ woff2: ['woff', 'ttf', 'otf', 'eot'],
44
+ avif: ['webp', 'png', 'jpg', 'jpeg'],
45
+ webp: ['png', 'jpg', 'jpeg'],
46
+ };
47
+ const extensionOf = (name) => (/\.([\da-z]+)$/i.exec(name)?.[1] ?? '').toLowerCase();
48
+ exports.extensionOf = extensionOf;
49
+ const kindOf = (name) => EXTENSIONS[(0, exports.extensionOf)(name)] ?? 'other';
50
+ exports.kindOf = kindOf;
51
+ /** The three of the eight kinds the media table holds. The only place they are listed. */
52
+ const MEDIA_KINDS = new Set(['image', 'video', 'audio']);
53
+ /**
54
+ * The kind that puts a file in the media table, or `null` when it belongs in none.
55
+ *
56
+ * `kindOf` answers over all eight kinds and the table holds three, so the wide answer used to be
57
+ * asserted back down into the narrow one. This asks the same question so that the answer is
58
+ * already narrow, which is what both the filter and the row below need.
59
+ */
60
+ const mediaKindOf = (name) => (0, json_utils_1.asMember)((0, exports.kindOf)(name), MEDIA_KINDS);
61
+ /**
62
+ * The face a font file belongs to.
63
+ *
64
+ * Build tools write `Roboto-Bold-A1B2C3.woff2`, `roboto_700.woff2`, `Inter-Regular.ttf`. What
65
+ * identifies the family is the first segment, with the content hash and the weight taken off. It
66
+ * is a convention rather than a fact, and it is the right kind of guess to make: getting it wrong
67
+ * groups two families into one row, which is visible and harmless, while not grouping at all means
68
+ * seven weights of Roboto read as seven unrelated files.
69
+ */
70
+ const familyOf = (name) => {
71
+ const base = name.replace(/\.[^.]+$/, '');
72
+ const head = base.split(/[_-]/, 1)[0] ?? base;
73
+ return head.toLowerCase();
74
+ };
75
+ /**
76
+ * Every token in a text that looks like a file name. One pass, so a big chunk is read once.
77
+ *
78
+ * The lookbehind is not a nicety, it is what makes the pass linear. Without it, `[\w.-]+` is tried
79
+ * again from every position inside a long run of word characters — a base64 blob in a minified
80
+ * chunk, say — and each attempt walks to the end of the run before failing. On a 5.9 MB chunk with
81
+ * wasm embedded that took minutes and found nothing; anchored to a boundary, each run is attempted
82
+ * once and the same file reads in 112 ms. The set of tokens is identical either way: a greedy match
83
+ * already starts at the boundary, so all the lookbehind removes is the attempts that cannot match.
84
+ */
85
+ const NAME_TOKEN = /(?<![\w.-])[\w.-]+\.[a-z0-9]{2,5}/gi;
86
+ /** A copy of another file under a different encoding: `app.js.br` next to `app.js`. */
87
+ const PRE_COMPRESSED = /\.(?:br|brotli|gz|zst)$/i;
88
+ /** A `data:` URI as a bundler writes one when a file falls under the inline threshold. */
89
+ const DATA_URI = /data:([\w./+-]+);base64,[\d+/A-Za-z]+={0,2}/g;
90
+ /** Fonts grouped into the faces they really are. */
91
+ const fontsOf = (files, preloaded) => {
92
+ const byFamily = new Map();
93
+ for (const file of files) {
94
+ if ((0, exports.kindOf)(file.name) !== 'font') {
95
+ continue;
96
+ }
97
+ const family = familyOf(file.name);
98
+ byFamily.set(family, [...(byFamily.get(family) ?? []), file]);
99
+ }
100
+ return [...byFamily]
101
+ .map(([name, group]) => {
102
+ const formats = [...new Set(group.map(file => (0, exports.extensionOf)(file.name)))];
103
+ const best = formats.includes('woff2') ? 'woff2' : null;
104
+ const beaten = new Set(best ? SUPERSEDED_BY[best] : []);
105
+ return {
106
+ name,
107
+ files: group
108
+ .map(file => ({ name: file.name, bytes: file.bytes, format: (0, exports.extensionOf)(file.name) }))
109
+ .toSorted((a, b) => b.bytes - a.bytes),
110
+ bytes: group.reduce((sum, file) => sum + file.bytes, 0),
111
+ formats,
112
+ preloaded: group.filter(file => preloaded.has(file.name)).map(file => file.name),
113
+ // Only when the better format is genuinely there: this never says "convert it",
114
+ // it says "you are shipping the same face twice and one of them is not used".
115
+ superseded: group.filter(file => beaten.has((0, exports.extensionOf)(file.name))).map(file => file.name),
116
+ };
117
+ })
118
+ .toSorted((a, b) => b.bytes - a.bytes);
119
+ };
120
+ /** Pictures and video, with whether a modern version of the same name is already there. */
121
+ const mediaOf = (files, inPage) => {
122
+ const media = files.filter(file => mediaKindOf(file.name) !== null);
123
+ // Two files are the same picture when everything but the extension matches. The hash a bundler
124
+ // adds is part of the name and stays in the comparison, which is what keeps it honest.
125
+ const stems = new Map();
126
+ for (const file of media) {
127
+ const stem = file.name.replace(/\.[^.]+$/, '');
128
+ stems.set(stem, (stems.get(stem) ?? new Set()).add((0, exports.extensionOf)(file.name)));
129
+ }
130
+ return media
131
+ .map((file) => {
132
+ const format = (0, exports.extensionOf)(file.name);
133
+ const siblings = stems.get(file.name.replace(/\.[^.]+$/, '')) ?? new Set();
134
+ const modern = ['avif', 'webp'].find(better => siblings.has(better) && SUPERSEDED_BY[better]?.includes(format));
135
+ return {
136
+ ...file,
137
+ // Never the fallback: `media` is exactly the files whose kind is one of the three.
138
+ kind: mediaKindOf(file.name) ?? 'image',
139
+ format,
140
+ inPage: inPage.has(file.name),
141
+ modernNeighbour: modern ?? null,
142
+ };
143
+ })
144
+ .toSorted((a, b) => b.bytes - a.bytes);
145
+ };
146
+ /** Which file names appear anywhere in the text of the build, plus whatever the page names. */
147
+ const referencedNames = (input) => {
148
+ const known = new Set(input.files.map(file => file.name));
149
+ const found = new Set(input.inPage);
150
+ const scan = (text) => {
151
+ for (const [token] of text.matchAll(NAME_TOKEN)) {
152
+ if (known.has(token)) {
153
+ found.add(token);
154
+ }
155
+ }
156
+ };
157
+ if (input.html) {
158
+ scan(input.html);
159
+ }
160
+ for (const text of input.texts.values()) {
161
+ scan(text);
162
+ }
163
+ return found;
164
+ };
165
+ /** The stylesheets each chunk names in its own text: how a lazy screen's CSS is attributed to it. */
166
+ const stylesByChunk = (input, sizeOf) => {
167
+ const styles = new Set(input.files.filter(file => (0, exports.kindOf)(file.name) === 'style').map(file => file.name));
168
+ const rows = [];
169
+ for (const [chunk, text] of input.texts) {
170
+ if ((0, exports.kindOf)(chunk) !== 'script') {
171
+ continue;
172
+ }
173
+ const named = new Set();
174
+ for (const [token] of text.matchAll(NAME_TOKEN)) {
175
+ if (styles.has(token)) {
176
+ named.add(token);
177
+ }
178
+ }
179
+ if (named.size > 0) {
180
+ rows.push({ chunk, styles: [...named], bytes: [...named].reduce((sum, css) => sum + sizeOf(css), 0) });
181
+ }
182
+ }
183
+ return rows.toSorted((a, b) => b.bytes - a.bytes);
184
+ };
185
+ /**
186
+ * Bytes of a chunk that are an image the bundler put inline because it fell under a threshold.
187
+ *
188
+ * Those bytes are hiding inside the figure that matters most: they cannot be deferred, they are not
189
+ * cached separately, and they appear in no list of assets anywhere. One icon is nothing; forty of
190
+ * them is a chunk that is a third pictures.
191
+ */
192
+ const inlinedOf = (texts) => {
193
+ const rows = [];
194
+ for (const [chunk, text] of texts) {
195
+ if ((0, exports.kindOf)(chunk) !== 'script' && (0, exports.kindOf)(chunk) !== 'style') {
196
+ continue;
197
+ }
198
+ let count = 0;
199
+ let bytes = 0;
200
+ const types = new Set();
201
+ for (const [uri, type = ''] of text.matchAll(DATA_URI)) {
202
+ count += 1;
203
+ bytes += uri.length;
204
+ types.add(type);
205
+ }
206
+ if (count > 0) {
207
+ rows.push({ chunk, count, bytes, types: [...types] });
208
+ }
209
+ }
210
+ return rows.toSorted((a, b) => b.bytes - a.bytes);
211
+ };
212
+ /** Files with the same content under two names, when something actually compared the content. */
213
+ const duplicatesOf = (files, hashes) => {
214
+ if (!hashes || hashes.size === 0) {
215
+ return [];
216
+ }
217
+ const byHash = new Map();
218
+ for (const file of files) {
219
+ const hash = hashes.get(file.path);
220
+ if (hash) {
221
+ byHash.set(hash, [...(byHash.get(hash) ?? []), file]);
222
+ }
223
+ }
224
+ return [...byHash]
225
+ .filter(([, group]) => group.length > 1)
226
+ .map(([hash, group]) => ({
227
+ hash: hash.slice(0, 12),
228
+ // The path, not the name: two copies of one file are usually in different folders, and
229
+ // "index.html, index.html, index.html" names nothing anybody can go and look at.
230
+ names: group.map(file => file.path),
231
+ bytes: group[0]?.bytes ?? 0,
232
+ wasted: (group.length - 1) * (group[0]?.bytes ?? 0),
233
+ }))
234
+ .toSorted((a, b) => b.wasted - a.wasted);
235
+ };
236
+ /** The whole first trip: everything the page asks for before anything appears. */
237
+ const firstTripOf = (input, sizeOf) => {
238
+ const named = [...input.inPage];
239
+ const total = (kinds) => named.filter(name => kinds.includes((0, exports.kindOf)(name))).reduce((sum, name) => sum + sizeOf(name), 0);
240
+ const scripts = total(['script']);
241
+ const styles = total(['style']);
242
+ const fonts = named
243
+ .filter(name => (0, exports.kindOf)(name) === 'font' && input.preloaded.has(name))
244
+ .reduce((sum, name) => sum + sizeOf(name), 0);
245
+ const images = total(['image']);
246
+ return {
247
+ scripts,
248
+ styles,
249
+ fonts,
250
+ images,
251
+ total: scripts + styles + fonts + images,
252
+ files: named.filter(name => (0, exports.kindOf)(name) !== 'font' || input.preloaded.has(name)).length,
253
+ };
254
+ };
255
+ const readAssets = (input) => {
256
+ const sizes = new Map(input.files.map(file => [file.name, file.bytes]));
257
+ const sizeOf = (name) => input.weigh?.get(name) ?? sizes.get(name) ?? 0;
258
+ const referenced = referencedNames(input);
259
+ const referencesRead = input.texts.size > 0 || input.html !== null;
260
+ const inlined = inlinedOf(input.texts);
261
+ // Scripts only. A prefetched font or picture is a different conversation and a much smaller
262
+ // one; what makes this worth a line is a framework fetching whole routes nobody asked for.
263
+ const prefetched = [...(input.prefetched ?? [])]
264
+ .filter(name => (0, exports.kindOf)(name) === 'script')
265
+ .map(name => ({ name, bytes: sizeOf(name) }))
266
+ .toSorted((a, b) => b.bytes - a.bytes);
267
+ return {
268
+ files: input.files.map(file => ({ ...file, kind: (0, exports.kindOf)(file.name) })),
269
+ fonts: fontsOf(input.files, input.preloaded),
270
+ media: mediaOf(input.files, input.inPage),
271
+ prefetched,
272
+ prefetchedBytes: prefetched.reduce((sum, file) => sum + file.bytes, 0),
273
+ // A source map is nobody's reference and never will be: it is named by the chunk it belongs
274
+ // to, and listing every `.map` as unreachable would bury the leftovers this is for. The
275
+ // same holds for a pre-compressed copy: `app.js.br` is `app.js` served under a different
276
+ // encoding, nothing links to it by name, and the server picks it by the request header.
277
+ // Listing them was worse than noise — those are the files the brotli figures in this very
278
+ // report were read from, so it advised deleting what made its own headline exact.
279
+ unreferenced: referencesRead
280
+ ? input.files.filter(file => !referenced.has(file.name) &&
281
+ (0, exports.kindOf)(file.name) !== 'map' &&
282
+ !PRE_COMPRESSED.test(file.name) &&
283
+ !input.texts.has(file.name) &&
284
+ !/^index(\.[\w-]+)?\.html$/i.test(file.name))
285
+ : [],
286
+ referencesRead,
287
+ duplicates: duplicatesOf(input.files, input.hashes),
288
+ contentCompared: !!input.hashes && input.hashes.size > 0,
289
+ inlined,
290
+ inlinedBytes: inlined.reduce((sum, row) => sum + row.bytes, 0),
291
+ stylesByChunk: stylesByChunk(input, sizeOf),
292
+ firstTrip: firstTripOf(input, sizeOf),
293
+ inPage: [...input.inPage],
294
+ };
295
+ };
296
+ exports.readAssets = readAssets;
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+ /**
3
+ * What the build folder holds besides JavaScript.
4
+ *
5
+ * This is the biggest hole the tool had, and the reason is worth writing down: **nobody downloads
6
+ * JavaScript, they download a page.** Until now `isAsset()` accepted `.js`, `.mjs` and `.css`, and
7
+ * of the CSS only what it compressed to; everything else in the folder — the fonts, the images, the
8
+ * icons, the leftovers of last month's deploy — was invisible to a tool whose headline claims to
9
+ * say what the first load costs.
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ /** The shapes of a saved baseline and of the comparison against it. */
3
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,241 @@
1
+ "use strict";
2
+ /**
3
+ * The cost of an update, worked out from the two things that are already there: the file names of
4
+ * this build and the file names of the previous one.
5
+ *
6
+ * The whole method is one observation. A build tool writes the content hash into the file name, so
7
+ * **a name that has not changed is a file the browser does not ask for again**. Comparing two lists
8
+ * of names is therefore not an approximation of the cache delta, it is the cache delta — as long as
9
+ * the names carry hashes, which is the third figure here and the reason it is measured too.
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.readCaching = exports.unhashableFiles = exports.unstableChunks = exports.updateCostOf = exports.unhashedName = void 0;
13
+ /**
14
+ * A content hash in a file name: `main-A1B2C3D4.js`, `main.a1b2c3d4.js`, `chunk-0fPdmq0U.mjs`.
15
+ *
16
+ * Eight characters or more of hex or base64 next to the extension. Shorter than that and it is a
17
+ * version number somebody wrote by hand, which is exactly the case this is meant to catch rather
18
+ * than accept.
19
+ */
20
+ const HASHED = /[.\-_][\dA-Za-z_-]{8,}\.[\da-z]+$/;
21
+ /**
22
+ * The same thing when the hash **is** the whole name: `ChDGvcpR.js`, `DkjDNEOM.js`, `BauOL-29.js`.
23
+ *
24
+ * SvelteKit, Nuxt and Rollup all write chunks with no readable prefix at all, and `HASHED` needs a
25
+ * separator before the hash, so it said no to every one of them: nine files on SvelteKit and twelve
26
+ * on Nuxt reported as uncacheable, at `mid`, when they are the most cacheable files in the build.
27
+ *
28
+ * Mixed case is what tells a hash from a word — `version.json` and `_payload.json` really do carry
29
+ * no hash and stay reported. It costs a hand-written `AppShell.js` being taken for a hash, and that
30
+ * is the right way round to be wrong: the price is one missing line, not a false claim.
31
+ */
32
+ const BARE_HASH = /^[\dA-Za-z_-]{8,}\.[\da-z]+$/;
33
+ const MIXED_CASE = /(?=.*[a-z])(?=.*[A-Z])/;
34
+ /**
35
+ * A name somebody wrote, with something after it: `main-K7QW2X.js`, `chunk-A1B2.js`.
36
+ *
37
+ * It has to be kept out of `BARE_HASH`, because base64 includes `-` and `_` and without this
38
+ * `main-K7QW2X` reads as one opaque token — which would take a six-character version suffix for a
39
+ * content hash and stop reporting exactly the case this signal exists for.
40
+ */
41
+ const WRITTEN_PREFIX = /^[a-z]{3,}[.\-_]/;
42
+ /** A version pinned in the query string: `app.js?v=3`. It defeats the cache on every deploy. */
43
+ const VERSIONED_QUERY = /[?&]v(?:er|ersion)?=/i;
44
+ /** The name with its content hash taken off, which is what makes two builds' files comparable. */
45
+ const unhashedName = (name) => name.replace(/[.\-_][\dA-Za-z_-]{8,}(\.[\da-z]+)$/, '$1');
46
+ exports.unhashedName = unhashedName;
47
+ /** A name that is nothing but a hash: `ChDGvcpR.js`. Taking the hash off it would leave `.js`. */
48
+ const isBareHash = (name) => BARE_HASH.test(name) && MIXED_CASE.test(name) && !WRITTEN_PREFIX.test(name);
49
+ /**
50
+ * The key a file is matched by across two builds.
51
+ *
52
+ * Normally the name with the hash taken off, which is the whole method: a build tool writes the
53
+ * content hash into the name, so `main-A1.js` and `main-B2.js` are one file that changed.
54
+ *
55
+ * It has nothing to work with when the name **is** the hash — SvelteKit, Nuxt and Rollup write
56
+ * chunks called `ChDGvcpR.js` — because there is no name left underneath. Every one of those read
57
+ * as one file gone and another arrived: a two-byte edit to a shared module in the SvelteKit probe
58
+ * reported 10 kB added and 10 kB removed rather than 10 kB changed, and the split into the edit and
59
+ * the cascade it set off never saw the largest file in the build.
60
+ *
61
+ * For those, the identity is what the chunk is made of rather than what it is called. It is not a
62
+ * guess and not a heuristic over the bytes: the analysis already works out the biggest source file
63
+ * of every chunk, from the same metafile or source map the weights come from, and the snapshot
64
+ * carries it. A content key is only used when it names exactly one chunk on that side — two chunks
65
+ * built around the same file say nothing about which of them is which — and `CONTENT_KEY` in
66
+ * front of it is there so it can never be mistaken for a file name.
67
+ */
68
+ const CONTENT_KEY = '\u{0}';
69
+ const keysOf = (files) => {
70
+ const perContent = new Map();
71
+ for (const [name, file] of files) {
72
+ if (file.content && isBareHash(name)) {
73
+ perContent.set(file.content, (perContent.get(file.content) ?? 0) + 1);
74
+ }
75
+ }
76
+ const keys = new Map();
77
+ for (const [name, file] of files) {
78
+ const byContent = !!file.content && isBareHash(name) && perContent.get(file.content) === 1;
79
+ keys.set(name, byContent ? `${CONTENT_KEY}${file.content ?? ''}` : (0, exports.unhashedName)(name));
80
+ }
81
+ return keys;
82
+ };
83
+ /**
84
+ * The changed files split into the edit and the cascade it set off.
85
+ *
86
+ * Both halves are read, neither is modelled: the two builds' names say which files changed, and the
87
+ * current build's import edges say which of them carry a changed name inside. A file naming nothing
88
+ * that changed cannot have moved for any reason but its own content — that is where the edit was.
89
+ *
90
+ * The split is a pair of bounds and is presented as one. A file that was edited *and* sits
91
+ * downstream of another edited file looks exactly like a pure cascade victim from here, so `roots`
92
+ * is a floor on the edit and `carried` a ceiling on the cascade.
93
+ */
94
+ const cascadeOf = (changed, importers) => {
95
+ const changedNames = new Set(changed.map(file => file.name));
96
+ // A changed file is explained by the cascade when it names another file that also changed:
97
+ // that name is inside its bytes, so its hash had to move whether or not anything else did.
98
+ const carriedNames = new Set([...importers]
99
+ .filter(([target]) => changedNames.has(target))
100
+ .flatMap(([, naming]) => naming)
101
+ .filter(name => changedNames.has(name)));
102
+ const carried = changed.filter(file => carriedNames.has(file.name));
103
+ const roots = changed.filter(file => !carriedNames.has(file.name));
104
+ const bytesOf = (files) => files.reduce((sum, file) => sum + file.bytes, 0);
105
+ return {
106
+ roots: roots.map(file => file.name),
107
+ rootBytes: bytesOf(roots),
108
+ carried: carried.map(file => file.name),
109
+ carriedBytes: bytesOf(carried),
110
+ };
111
+ };
112
+ /**
113
+ * What somebody who already had the previous version has to download.
114
+ *
115
+ * Files are matched by their **unhashed** name, so `main-A1.js` and `main-B2.js` are the same file
116
+ * having changed rather than one file gone and another arrived. That distinction is the entire
117
+ * point: `12 gone, 12 new` says nothing, `12 changed, 1.2 MB re-downloaded` says what it costs.
118
+ *
119
+ * @param importers file name → the names of the files that carry it inside them, from the current
120
+ * build's import edges. Optional: without it the update cost is the same figure it
121
+ * always was, and the split into edit and cascade is `null` rather than guessed.
122
+ */
123
+ const updateCostOf = (current, previous, importers = null) => {
124
+ const previousKeys = keysOf(previous);
125
+ const currentKeys = keysOf(current);
126
+ const before = new Map();
127
+ for (const [name, file] of previous) {
128
+ before.set(previousKeys.get(name) ?? (0, exports.unhashedName)(name), { name, bytes: file.bytes });
129
+ }
130
+ const changed = [];
131
+ const added = [];
132
+ const seen = new Set();
133
+ let reused = 0;
134
+ let fresh = 0;
135
+ for (const [name, file] of current) {
136
+ const bytes = file.bytes;
137
+ fresh += bytes;
138
+ const key = currentKeys.get(name) ?? (0, exports.unhashedName)(name);
139
+ const was = before.get(key);
140
+ seen.add(key);
141
+ if (!was) {
142
+ added.push({ name, change: 'added', bytes });
143
+ }
144
+ else if (was.name === name) {
145
+ // Same name, same content, still in the browser's cache. Nothing to download.
146
+ reused += 1;
147
+ }
148
+ else {
149
+ changed.push({ name, change: 'changed', bytes });
150
+ }
151
+ }
152
+ const removed = [...before]
153
+ .filter(([key]) => !seen.has(key))
154
+ .map(([, was]) => ({ name: was.name, change: 'removed', bytes: was.bytes }));
155
+ const bytes = [...changed, ...added].reduce((sum, file) => sum + file.bytes, 0);
156
+ const byWeight = changed.toSorted((a, b) => b.bytes - a.bytes);
157
+ return {
158
+ bytes,
159
+ fresh,
160
+ ratio: fresh > 0 ? bytes / fresh : 0,
161
+ changed: byWeight,
162
+ added: added.toSorted((a, b) => b.bytes - a.bytes),
163
+ removed: removed.toSorted((a, b) => b.bytes - a.bytes),
164
+ reused,
165
+ cascade: importers ? cascadeOf(byWeight, importers) : null,
166
+ };
167
+ };
168
+ exports.updateCostOf = updateCostOf;
169
+ /**
170
+ * Chunks that mix somebody else's code with the project's own.
171
+ *
172
+ * This is the cause behind the symptom the update cost measures, which is why it is a separate
173
+ * figure and not a footnote on that one. Dependencies do not change for months; the project's code
174
+ * changes every day; one file holding both is invalidated every day, and everything of the first
175
+ * kind inside it is re-downloaded for nothing.
176
+ *
177
+ * @param minRatio how much of a chunk has to be somebody else's before it is worth a line. A chunk
178
+ * that is 2 % vendor is not a badly split vendor bundle, it is a chunk.
179
+ */
180
+ const unstableChunks = (chunks, minRatio) => chunks
181
+ .map((chunk) => {
182
+ const total = chunk.vendorBytes + chunk.ownBytes;
183
+ return {
184
+ name: chunk.name,
185
+ bytes: chunk.bytes,
186
+ vendorRatio: total > 0 ? chunk.vendorBytes / total : 0,
187
+ // Only when the chunk holds both. A chunk that is nothing but vendor code is the
188
+ // right answer, not the problem: its hash does not move when the project changes.
189
+ vendorBytes: chunk.ownBytes > 0 ? chunk.vendorBytes : 0,
190
+ inBoot: chunk.inBoot,
191
+ };
192
+ })
193
+ .filter(chunk => chunk.vendorBytes > 0 && chunk.vendorRatio >= minRatio)
194
+ .toSorted((a, b) => Number(b.inBoot) - Number(a.inBoot) || b.vendorBytes - a.vendorBytes);
195
+ exports.unstableChunks = unstableChunks;
196
+ /**
197
+ * The files for which "it carries no hash" is not a finding but the definition.
198
+ *
199
+ * The HTML document of a build is the one URL that has to stay put — hash it and nobody can reach
200
+ * the application. A source map is never fetched by a page: its name is derived from the chunk's,
201
+ * which already carries the hash. A pre-compressed copy is not a second cache entry either:
202
+ * `app.js.br` is `app.js` under another encoding, served at the same URL by content negotiation.
203
+ *
204
+ * Counting them turned this into the one signal that fires on every build ever read: seven entries
205
+ * on a plain Vite build, of which six were `.map` and the seventh `index.html`, and twenty-five on
206
+ * Nuxt, enough to push it to `mid` and into the "what to fix first" table. A signal that is always
207
+ * on is a signal nobody reads.
208
+ */
209
+ const NEVER_HASHED = /(?:\.map|\.html?|\.br|\.brotli|\.gz|\.zst)$/i;
210
+ /**
211
+ * Files a browser cannot keep for long.
212
+ *
213
+ * Informative almost always — a `favicon.ico` has no hash and never will — and worth a line when it
214
+ * fires on something big, because then every visit revalidates it. The `?v=` case is the one that
215
+ * is nearly always a mistake: it changes the URL on every deploy, which is what a content hash does
216
+ * except that it changes it for **every** file at once.
217
+ */
218
+ const unhashableFiles = (files, referencedAs, inPage) => files
219
+ .filter(file => !NEVER_HASHED.test(file.name))
220
+ .map((file) => {
221
+ // Every rule below reads the name, because that is what a hash is written into and what
222
+ // the page, the metafile and the compressed copies all key a file by. Only what gets
223
+ // printed is the path.
224
+ const at = { name: file.name, path: file.path ?? file.name, bytes: file.bytes };
225
+ const reference = referencedAs.get(file.name) ?? file.name;
226
+ if (VERSIONED_QUERY.test(reference)) {
227
+ return { ...at, reason: 'query', inPage: inPage.has(file.name) };
228
+ }
229
+ const bare = isBareHash(file.name);
230
+ const hashed = HASHED.test(file.name) || bare;
231
+ return hashed ? null : { ...at, reason: 'none', inPage: inPage.has(file.name) };
232
+ })
233
+ .filter(file => file !== null)
234
+ .toSorted((a, b) => Number(b.inPage) - Number(a.inPage) || b.bytes - a.bytes);
235
+ exports.unhashableFiles = unhashableFiles;
236
+ const readCaching = (input) => ({
237
+ update: input.previous ? (0, exports.updateCostOf)(input.current, input.previous, input.importers) : null,
238
+ unstable: (0, exports.unstableChunks)(input.chunks, input.minVendorRatio),
239
+ unhashable: (0, exports.unhashableFiles)(input.files, input.referencedAs, input.inPage),
240
+ });
241
+ exports.readCaching = readCaching;
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ /**
3
+ * What an update costs, as opposed to a first visit.
4
+ *
5
+ * Nobody looks at this and it is half the real cost: almost every visit to a running application is
6
+ * somebody who already had yesterday's version. Changing one line in `app.component.ts` and
7
+ * invalidating 1.2 MB of vendor code is a configuration mistake that shows up in no report anywhere,
8
+ * and it is one of the expensive ones.
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,73 @@
1
+ "use strict";
2
+ /**
3
+ * The caching figures, assembled from what the report already holds.
4
+ *
5
+ * It is a module of its own so that `caching.ts` stays rules and this stays plumbing: the page and
6
+ * the command both need exactly this assembly, and two copies of it would be two places for the
7
+ * definition of "vendor" to drift apart.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.cachingOf = void 0;
11
+ const format_utils_1 = require("../format/format.utils");
12
+ const caching_1 = require("./caching");
13
+ /**
14
+ * How much of a chunk has to be somebody else's code before mixing is the finding.
15
+ *
16
+ * A chunk that is 2 % vendor is a chunk, not a badly split vendor bundle. At a quarter and above,
17
+ * the dependencies inside it are a real part of what every deploy invalidates. It is a constant
18
+ * rather than a criterion because it is about the shape of a split and not about a budget: nothing
19
+ * a team decides changes what "mixed" means.
20
+ */
21
+ const MIN_VENDOR_RATIO = 0.25;
22
+ /** Every chunk of the build with its vendor/own split, read from the tree the analysis already built. */
23
+ const chunksOf = (analysis) => {
24
+ const boot = new Set(analysis.bootChunks);
25
+ return analysis.tree
26
+ .filter(node => node.kind === 'chunk')
27
+ .map((node) => {
28
+ const vendorBytes = node.children
29
+ .filter(child => child.kind === 'package')
30
+ .reduce((sum, child) => sum + child.bytes, 0);
31
+ const ownBytes = node.children
32
+ .filter(child => child.kind === 'folder')
33
+ .reduce((sum, child) => sum + child.bytes, 0);
34
+ return { name: node.label, bytes: node.bytes, inBoot: boot.has(node.id), vendorBytes, ownBytes };
35
+ });
36
+ };
37
+ /**
38
+ * @param assets the rest of the folder, when one was read. It also carries what the page asks
39
+ * for, which is where "does anything ask for this file" comes from: working it out
40
+ * again here is how the two halves of one report came to disagree about a favicon.
41
+ * @param hrefs the URLs `index.html` writes, query and all. `app.js?v=3` is a caching fact that
42
+ * only exists in the full string, so it cannot be read from the file names.
43
+ * @param baseline the previous build. Only the snapshots that carry `files` can answer what an
44
+ * update costs; an older export cannot, and the report says nothing rather than
45
+ * guessing from the byte totals.
46
+ */
47
+ const cachingOf = (analysis, baseline, assets, inPage, hrefs = []) => {
48
+ // What the page asks for, as the folder reader worked it out. Without a folder there is only
49
+ // what `index.html` announced of the JavaScript, which is what the caller passes.
50
+ const named = assets ? new Set(assets.inPage) : inPage;
51
+ const current = new Map(analysis.allChunks.map(file => {
52
+ const chunk = analysis.chunkOf(file);
53
+ return [(0, format_utils_1.baseName)(file), { bytes: chunk?.bytes ?? 0, content: chunk?.mainContent }];
54
+ }));
55
+ const previous = baseline?.files
56
+ ? new Map(baseline.files.map(file => [file.name, { bytes: file.bytes, content: file.content }]))
57
+ : null;
58
+ return (0, caching_1.readCaching)({
59
+ current,
60
+ previous,
61
+ chunks: chunksOf(analysis),
62
+ files: assets
63
+ ? assets.files.map(file => ({ name: file.name, path: file.path, bytes: file.bytes }))
64
+ : [...current].map(([name, file]) => ({ name, bytes: file.bytes })),
65
+ referencedAs: new Map(hrefs.map(href => [(0, format_utils_1.baseName)(/^[^?#]*/.exec(href)?.[0] ?? ''), href])),
66
+ // Keyed by file name, because that is the only thing the two builds have in common: the
67
+ // previous one is a list of names and sizes, and its output paths were never kept.
68
+ importers: new Map([...analysis.chunkImporters].map(([target, naming]) => [(0, format_utils_1.baseName)(target), naming.map(file => (0, format_utils_1.baseName)(file))])),
69
+ inPage: named,
70
+ minVendorRatio: MIN_VENDOR_RATIO,
71
+ });
72
+ };
73
+ exports.cachingOf = cachingOf;