@bymaksym/loadline 1.2.1 → 1.3.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 (45) hide show
  1. package/README.md +1 -1
  2. package/dist/cli/cli/main.js +7 -4
  3. package/dist/cli/cli/read/locate.js +61 -0
  4. package/dist/cli/cli/read/read-build.js +7 -4
  5. package/dist/cli/cli/read/read-config.js +21 -3
  6. package/dist/cli/cli/render/render-json.js +1 -0
  7. package/dist/cli/cli/render/render-text.js +25 -1
  8. package/dist/cli/cli/report.js +10 -3
  9. package/dist/cli/cli/text/text-errors.js +14 -0
  10. package/dist/cli/cli/text/text.js +4 -0
  11. package/dist/cli/cli/text/usage.js +4 -4
  12. package/dist/cli/src/app/core/analysis/analysis.js +18 -4
  13. package/dist/cli/src/app/core/analysis/sourcemap/index-map.js +193 -0
  14. package/dist/cli/src/app/core/analysis/sourcemap/sourcemap.js +2 -1
  15. package/dist/cli/src/app/core/analysis/sourcemap/split-drift.js +39 -1
  16. package/dist/cli/src/app/core/assets/assets.js +35 -6
  17. package/dist/cli/src/app/core/caching/caching.js +1 -0
  18. package/dist/cli/src/app/core/deps/deps.js +68 -19
  19. package/dist/cli/src/app/core/export/summary.js +2 -1
  20. package/dist/cli/src/app/core/findings/actions.js +24 -3
  21. package/dist/cli/src/app/core/findings/bundle/dupes.js +22 -7
  22. package/dist/cli/src/app/core/findings/bundle/requests.js +1 -0
  23. package/dist/cli/src/app/core/findings/bundle/shipped.js +17 -2
  24. package/dist/cli/src/app/core/findings/effort.js +5 -5
  25. package/dist/cli/src/app/core/findings/folder/assets.js +13 -2
  26. package/dist/cli/src/app/core/findings/folder/caching.js +5 -5
  27. package/dist/cli/src/app/core/findings/folder/scan.js +2 -7
  28. package/dist/cli/src/app/core/findings/supplied/forbidden.js +1 -1
  29. package/dist/cli/src/app/core/findings/text/finding-html.js +25 -2
  30. package/dist/cli/src/app/core/findings/text/finding-text.js +88 -42
  31. package/dist/cli/src/app/core/findings/text/tool-advice.js +33 -1
  32. package/dist/cli/src/app/core/format/format.utils.js +14 -1
  33. package/dist/cli/src/app/core/i18n/en.js +57 -0
  34. package/dist/cli/src/app/core/i18n/es.js +57 -0
  35. package/dist/cli/src/app/core/intake/bundle-graph.js +2 -1
  36. package/dist/cli/src/app/core/intake/native-export.js +84 -0
  37. package/dist/cli/src/app/core/project/budget-advice.js +22 -1
  38. package/dist/cli/src/app/core/project/project-name.js +32 -4
  39. package/dist/cli/src/app/core/scan/scan.js +56 -8
  40. package/dist/cli/src/app/core/situation/situation.js +3 -3
  41. package/dist/cli/src/app/core/whatif/source-importers.js +2 -1
  42. package/docs/CONFIG.md +2 -1
  43. package/docs/HOW-IT-WORKS.md +90 -7
  44. package/loadline.html +23 -21
  45. package/package.json +38 -39
@@ -0,0 +1,84 @@
1
+ "use strict";
2
+ /**
3
+ * An Expo export for a phone rather than a browser, recognised so it is refused with its name.
4
+ *
5
+ * `expo export` for Android and iOS writes a folder that looks enough like a web build to be read as
6
+ * one, and three ways in gave three wrong answers, all with exit code 2: the project folder was told
7
+ * to "build it the way you deploy it (npm run build)" — these apps have no `build`, they have
8
+ * `bundle` — the export folder was asked whether it was "the browser/ folder of the build", which is
9
+ * Angular's, and the bundle itself "is not valid JSON". Forced through with `--entry`, the report
10
+ * contradicted itself: a 985 kB bootstrap with no screens over a first trip of 0 B, nine seconds on
11
+ * slow 4G for an app the store already installed, and the images of `assets/` — Metro names them by
12
+ * hash, with no extension — as 47 files nothing names.
13
+ *
14
+ * Supporting native apps is out of scope on purpose: what an app costs to install and to update is
15
+ * what Expo Atlas already shows. What is in scope is saying what this is. The marks, any one enough:
16
+ *
17
+ * - `metadata.json` whose `fileMetadata` names `android` or `ios`: the manifest `expo export` writes.
18
+ * - a `.hbc` file, or any file starting with Hermes bytecode's magic number.
19
+ * - a bundle under `_expo/static/js/android/` or `_expo/static/js/ios/`.
20
+ *
21
+ * A web export (`expo export --platform web`) has `_expo/static/js/web/`, an `index.html` and no
22
+ * native platform in its metadata: it is a web build, and it is read as one.
23
+ */
24
+ Object.defineProperty(exports, "__esModule", { value: true });
25
+ exports.isExpoPackage = exports.nativeExportOf = exports.nativePlatformsIn = exports.isHermesBytecode = void 0;
26
+ /** Hermes bytecode starts with `0x1F1903C103BC1FC6`, little-endian. */
27
+ const HERMES_MAGIC = [0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f];
28
+ const NATIVE_PLATFORMS = ['android', 'ios'];
29
+ /** Whether the first bytes of a file are Hermes bytecode. */
30
+ const isHermesBytecode = (head) => head.length >= HERMES_MAGIC.length && HERMES_MAGIC.every((byte, index) => head[index] === byte);
31
+ exports.isHermesBytecode = isHermesBytecode;
32
+ /** The native platforms an Expo `metadata.json` names, or none when it is not one. */
33
+ const nativePlatformsIn = (metadata) => {
34
+ if (!metadata) {
35
+ return [];
36
+ }
37
+ try {
38
+ const parsed = JSON.parse(metadata);
39
+ const files = parsed && typeof parsed === 'object' ? parsed['fileMetadata'] : undefined;
40
+ return files && typeof files === 'object' ? NATIVE_PLATFORMS.filter(platform => platform in files) : [];
41
+ }
42
+ catch {
43
+ return [];
44
+ }
45
+ };
46
+ exports.nativePlatformsIn = nativePlatformsIn;
47
+ const PLATFORM_FOLDER = /(?:^|\/)_expo\/static\/js\/(android|ios)\//;
48
+ /**
49
+ * Whether a folder is a native export, from the paths inside it (relative, with `/`) and the text of
50
+ * its `metadata.json` when it has one. `null` for anything else, a web export included.
51
+ */
52
+ const nativeExportOf = (paths, metadata) => {
53
+ const named = (0, exports.nativePlatformsIn)(metadata);
54
+ const hermes = paths.find(path => /\.hbc$/i.test(path));
55
+ const platformFolders = [...new Set(paths.map(path => PLATFORM_FOLDER.exec(path)?.[1]).filter(name => !!name))];
56
+ const platforms = [...new Set([...named, ...platformFolders])];
57
+ if (named.length > 0) {
58
+ return { platforms, evidence: 'metadata.json' };
59
+ }
60
+ if (hermes) {
61
+ return { platforms, evidence: hermes };
62
+ }
63
+ const folder = paths.find(path => PLATFORM_FOLDER.test(path));
64
+ return folder ? { platforms, evidence: folder } : null;
65
+ };
66
+ exports.nativeExportOf = nativeExportOf;
67
+ /** Whether a `package.json` is an Expo app's: `expo` among its dependencies. */
68
+ const isExpoPackage = (manifest) => {
69
+ if (!manifest) {
70
+ return false;
71
+ }
72
+ try {
73
+ const parsed = JSON.parse(manifest);
74
+ const record = parsed && typeof parsed === 'object' ? parsed : {};
75
+ return ['dependencies', 'devDependencies'].some(field => {
76
+ const deps = record[field];
77
+ return !!deps && typeof deps === 'object' && 'expo' in deps;
78
+ });
79
+ }
80
+ catch {
81
+ return false;
82
+ }
83
+ };
84
+ exports.isExpoPackage = isExpoPackage;
@@ -15,7 +15,8 @@
15
15
  * which would fail the next build for a reason having nothing to do with the build.
16
16
  */
17
17
  Object.defineProperty(exports, "__esModule", { value: true });
18
- exports.screenBudgetAdvice = exports.budgetAdvice = void 0;
18
+ exports.budgetStanding = exports.firstLimitOf = exports.screenBudgetAdvice = exports.budgetAdvice = void 0;
19
+ const project_context_1 = require("./project-context");
19
20
  const KB = 1024;
20
21
  /** Rounded to something a person would write down. Nobody puts `maximumError: 731 kB` in a file. */
21
22
  const roundKb = (bytes) => {
@@ -78,3 +79,23 @@ const screenBudgetAdvice = (largestScriptRawBytes, headroom = 0.15) => {
78
79
  return { warningKb, errorKb, currentBytes: largestScriptRawBytes, snippet };
79
80
  };
80
81
  exports.screenBudgetAdvice = screenBudgetAdvice;
82
+ /** The figure that fires first: the warning, else the error. */
83
+ const firstLimitOf = (standing) => standing.warning ?? standing.error;
84
+ exports.firstLimitOf = firstLimitOf;
85
+ /**
86
+ * The budget that applies, chosen as the budget signals choose it: among the configurations the
87
+ * pipeline builds when one was read, the strictest; otherwise the default configuration's, or the
88
+ * strictest of all. `null` when no configuration has one: `budgetNone` already says so.
89
+ */
90
+ const budgetStanding = (context, initialRawBytes) => {
91
+ const rows = (0, project_context_1.configurationBudgets)(context).filter(row => row.hasBudget);
92
+ const built = (0, project_context_1.pipelineKnown)(context) ? rows.filter(row => row.builtBy.length > 0) : [];
93
+ const defaulted = rows.filter(row => row.name === context.angular?.defaultConfiguration);
94
+ const pool = built.length > 0 ? built : defaulted.length > 0 ? defaulted : rows;
95
+ const bound = (row) => row.warning ?? row.error ?? Infinity;
96
+ const chosen = pool.toSorted((a, b) => bound(a) - bound(b))[0];
97
+ return chosen && initialRawBytes > 0
98
+ ? { config: chosen.name, current: initialRawBytes, warning: chosen.warning, error: chosen.error }
99
+ : null;
100
+ };
101
+ exports.budgetStanding = budgetStanding;
@@ -28,9 +28,37 @@ const GENERIC_FOLDERS = new Set([
28
28
  const folderName = (folder) => folder
29
29
  .replaceAll('\\', '/')
30
30
  .split('/')
31
- .filter(part => part !== '' && part !== '.' && part !== '..')
31
+ .filter(part => !['', '.', '..'].includes(part))
32
32
  .findLast(part => !GENERIC_FOLDERS.has(part.toLowerCase()) && !/\.json$/i.test(part)) ?? null;
33
- const projectNameOf = (sources) => [sources.packageName, sources.angularProject, sources.pageTitle, sources.folder ? folderName(sources.folder) : null]
34
- .map(name => name?.trim())
35
- .find(name => !!name) ?? null;
33
+ /**
34
+ * The titles a project generator writes and nobody changed: "Vite + React + TS" names the template,
35
+ * not the application, and reading it as the name would put the same name on every Vite app there is.
36
+ */
37
+ const TEMPLATE_TITLES = new Set(['vite app', 'react app', 'svelte app', 'sveltekit app', 'angular', 'document', 'app']);
38
+ const isTemplateTitle = (title) => {
39
+ const lower = title.toLowerCase();
40
+ return TEMPLATE_TITLES.has(lower) || lower === 'vite' || lower.startsWith('vite + ');
41
+ };
42
+ /**
43
+ * **The build's own title first, then the package, then the Angular project, then the folder.**
44
+ *
45
+ * One order whatever was passed, so the same build gets the same name with and without `--project`.
46
+ * The package name came first, and it is only known when `--project` is given or a `package.json`
47
+ * sits a few folders above the build: a build copied to a temporary folder was called "Esail IT
48
+ * Solutions" (its `<title>`) without the flag and "control-horario-angular" with it. The title is in
49
+ * the build itself, so it does not depend on what else the command was given — and it is the name
50
+ * the application calls itself on screen, which a package name often is not ("frontend", "web").
51
+ * A title left as the generator wrote it is skipped: it names a template, not this application.
52
+ */
53
+ const projectNameOf = (sources) => {
54
+ const title = sources.pageTitle?.trim();
55
+ return ([
56
+ title && !isTemplateTitle(title) ? title : null,
57
+ sources.packageName,
58
+ sources.angularProject,
59
+ sources.folder ? folderName(sources.folder) : null,
60
+ ]
61
+ .map(name => name?.trim())
62
+ .find(name => !!name) ?? null);
63
+ };
36
64
  exports.projectNameOf = projectNameOf;
@@ -9,7 +9,8 @@
9
9
  * a byte leaving the machine.
10
10
  */
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.scanBuild = exports.exposureOf = void 0;
12
+ exports.scanBuild = exports.generatedOf = exports.exposureOf = void 0;
13
+ const index_map_1 = require("../analysis/sourcemap/index-map");
13
14
  const sourcemap_1 = require("../analysis/sourcemap/sourcemap");
14
15
  const format_utils_1 = require("../format/format.utils");
15
16
  const ownership_1 = require("../format/ownership");
@@ -120,7 +121,7 @@ const mapReaders = (texts, maps) => {
120
121
  const map = maps.find(entry => entry.name === `${chunk}.map`);
121
122
  let reader = null;
122
123
  try {
123
- const parsed = map ? JSON.parse(map.text) : null;
124
+ const parsed = map ? (0, index_map_1.parseSourceMap)(map.text) : null;
124
125
  if ((0, sourcemap_1.isSourceMap)(parsed)) {
125
126
  const segments = (0, sourcemap_1.segmentsOf)(parsed);
126
127
  // Line starts once, so resolving a position is a binary search rather than a
@@ -202,15 +203,46 @@ const startsIndentedLine = (text, index) => {
202
203
  }
203
204
  return start < index && text[start - 1] === '\n';
204
205
  };
205
- const leftoversOf = (texts, modules, readerFor) => {
206
+ /**
207
+ * Whether a match sits in a comment, in a file that is not minified (a minifier keeps none but the
208
+ * legal ones). `// console.log(` on line 34 of a service worker was counted as a leftover, and it is
209
+ * the one thing about that line that is certain not to run.
210
+ *
211
+ * Read back to the start of the line, at most 500 characters: a line that starts a comment (`//`,
212
+ * `/*`, or the `*` of a block's middle), or a `//` after a space with no quote after it, which is a
213
+ * trailing comment and not the `//` of a URL inside a string.
214
+ */
215
+ const inComment = (text, index) => {
216
+ const lineStart = text.lastIndexOf('\n', index - 1) + 1;
217
+ const before = text.slice(Math.max(lineStart, index - 500), index);
218
+ const lead = before.trimStart();
219
+ if (lead.startsWith('//')) {
220
+ return true;
221
+ }
222
+ // A block comment the line opens or continues, unless it closes before the match: a licence
223
+ // header and the call after it on the same line (`/*! lodash MIT */ console.log(…)`) is code.
224
+ if ((lead.startsWith('/*') || lead.startsWith('*')) && !before.includes('*/')) {
225
+ return true;
226
+ }
227
+ const slashes = before.lastIndexOf('//');
228
+ return slashes > 0 && /\s/.test(before[slashes - 1] ?? '') && !/['"`]/.test(before.slice(slashes));
229
+ };
230
+ const isScript = (name) => /\.m?js$/i.test(name);
231
+ const leftoversOf = (texts, modules, readerFor, generated) => {
206
232
  const found = [];
233
+ // A file in the folder the bundler did not write: copied as it is, from `public/` or an assets
234
+ // folder — a service worker, a configuration script. Only known where the bundler listed what it
235
+ // wrote (a metafile, webpack's stats); a folder read on its own cannot tell, and says nothing.
236
+ // Whose code it is stays unknown without a map: it may be the project's, or a library somebody
237
+ // copied in. What changes is that it is not called a chunk.
238
+ const copied = (chunk) => !!generated && isScript(chunk) && !generated.has(chunk);
207
239
  /**
208
240
  * How many of a marker's matches in one chunk are the project's own, and whether that could be
209
241
  * decided at all. Without a map the honest answer is "all of them, and I do not know whose".
210
242
  */
211
243
  const countIn = (chunk, text, pattern) => {
212
244
  const minified = isMinified(text);
213
- const hits = [...text.matchAll(pattern)].filter(hit => !minified || !startsIndentedLine(text, hit.index));
245
+ const hits = [...text.matchAll(pattern)].filter(hit => minified ? !startsIndentedLine(text, hit.index) : !inComment(text, hit.index));
214
246
  if (hits.length === 0) {
215
247
  return { count: 0, attributed: true };
216
248
  }
@@ -228,6 +260,7 @@ const leftoversOf = (texts, modules, readerFor) => {
228
260
  let count = 0;
229
261
  let attributed = true;
230
262
  const where = [];
263
+ const copies = [];
231
264
  for (const [chunk, text] of texts) {
232
265
  const hits = countIn(chunk, text, pattern);
233
266
  attributed &&= hits.attributed;
@@ -236,9 +269,12 @@ const leftoversOf = (texts, modules, readerFor) => {
236
269
  }
237
270
  count += hits.count;
238
271
  where.push(chunk);
272
+ if (copied(chunk)) {
273
+ copies.push(chunk);
274
+ }
239
275
  }
240
276
  if (count > 0) {
241
- found.push({ kind, count, where, attributed });
277
+ found.push({ kind, count, where, attributed, copied: copies });
242
278
  }
243
279
  }
244
280
  // These are read from the inputs the metafile names rather than from the text of a chunk, so
@@ -246,7 +282,13 @@ const leftoversOf = (texts, modules, readerFor) => {
246
282
  for (const { kind, pattern } of DEV_INPUTS) {
247
283
  const hit = modules.filter(module => pattern.test(module.path));
248
284
  if (hit.length > 0) {
249
- found.push({ kind, count: hit.length, where: hit.map(module => module.label), attributed: true });
285
+ found.push({
286
+ kind,
287
+ count: hit.length,
288
+ where: hit.map(module => module.label),
289
+ attributed: true,
290
+ copied: [],
291
+ });
250
292
  }
251
293
  }
252
294
  return found;
@@ -307,7 +349,7 @@ const exposureOf = (maps) => {
307
349
  // Both fields are checked entry by entry rather than asserted whole: the assertion
308
350
  // made a map with one non-string in `sources` throw on the first `.includes`, and the
309
351
  // catch below then dropped everything that map knew instead of the one bad entry.
310
- const parsed = (0, json_utils_1.asRecord)(JSON.parse(map.text));
352
+ const parsed = (0, json_utils_1.asRecord)((0, index_map_1.parseSourceMap)(map.text));
311
353
  return {
312
354
  sources: ((0, json_utils_1.asArray)(parsed?.['sources']) ?? []).map(source => (0, json_utils_1.asText)(source)),
313
355
  contents: (0, json_utils_1.asArray)(parsed?.['sourcesContent']) ?? [],
@@ -344,11 +386,17 @@ const exposureOf = (maps) => {
344
386
  return { maps: maps.length, ownFiles: paths.size, hasContent, paths: [...paths], envReferences };
345
387
  };
346
388
  exports.exposureOf = exposureOf;
389
+ /**
390
+ * The scripts the bundler wrote, by file name, when it said so: every chunk of a metafile or of
391
+ * webpack's stats. `null` for a folder read on its own, where every script found is a chunk.
392
+ */
393
+ const generatedOf = (analysis) => analysis.readFrom === 'folder' ? null : new Set(analysis.allChunks.map(chunk => (0, format_utils_1.baseName)(chunk)));
394
+ exports.generatedOf = generatedOf;
347
395
  const scanBuild = (input) => {
348
396
  const readerFor = mapReaders(input.texts, input.maps);
349
397
  return {
350
398
  secrets: (0, secrets_1.findSecrets)(input.texts, envOwners(input.modules, readerFor)),
351
- leftovers: leftoversOf(input.texts, input.modules, readerFor),
399
+ leftovers: leftoversOf(input.texts, input.modules, readerFor, input.generated ?? null),
352
400
  licences: licencesOf(input.texts),
353
401
  thirdParty: thirdPartyOf(input.modules, input.boot),
354
402
  exposure: (0, exports.exposureOf)(input.maps),
@@ -225,11 +225,11 @@ const readSituation = (value, lang = 'en') => {
225
225
  situation.rum = raw['rum'] === true;
226
226
  situation.answeredBy = readText(raw['answeredBy']);
227
227
  const answeredAt = readText(raw['answeredAt']);
228
- if (answeredAt !== null && !DATE.test(answeredAt)) {
229
- problems.push(t.badAnsweredAt(answeredAt));
228
+ if (answeredAt === null || DATE.test(answeredAt)) {
229
+ situation.answeredAt = answeredAt;
230
230
  }
231
231
  else {
232
- situation.answeredAt = answeredAt;
232
+ problems.push(t.badAnsweredAt(answeredAt));
233
233
  }
234
234
  return { situation, problems };
235
235
  };
@@ -10,6 +10,7 @@
10
10
  */
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
12
  exports.importersInSources = void 0;
13
+ const index_map_1 = require("../analysis/sourcemap/index-map");
13
14
  const sourcemap_1 = require("../analysis/sourcemap/sourcemap");
14
15
  const ownership_1 = require("../format/ownership");
15
16
  const json_utils_1 = require("../json/json.utils");
@@ -31,7 +32,7 @@ const importersInSources = (maps, name) => {
31
32
  const pattern = importOf(name);
32
33
  const read = maps.map(map => {
33
34
  try {
34
- const parsed = (0, json_utils_1.asRecord)(JSON.parse(map.text));
35
+ const parsed = (0, json_utils_1.asRecord)((0, index_map_1.parseSourceMap)(map.text));
35
36
  return {
36
37
  sources: ((0, json_utils_1.asArray)(parsed?.['sources']) ?? []).map(source => (0, json_utils_1.asText)(source) ?? ''),
37
38
  contents: ((0, json_utils_1.asArray)(parsed?.['sourcesContent']) ?? []).map(content => (0, json_utils_1.asText)(content)),
package/docs/CONFIG.md CHANGED
@@ -37,7 +37,8 @@ The first line is what makes the file easy: VS Code, WebStorm and most editors r
37
37
  points at and then **complete every key, explain it on hover, list the allowed values and underline
38
38
  a typo** as you type. `tool` and `version` are always those two values.
39
39
 
40
- The command finds `loadline.json` in the working directory on its own; `--config <file>` points at
40
+ The command finds `loadline.json` in the working directory on its own, or in its `.config/` folder when
41
+ the root has none (the root wins when both exist); `--config <file>` points at
41
42
  another one. The page reads it too when you drop it in with the build.
42
43
 
43
44
  ## How the file is used
@@ -303,6 +303,51 @@ the first load take two trips. Late or not, it arrives before the first paint.
303
303
 
304
304
  ---
305
305
 
306
+ ### 2.10 Where the bytes go
307
+
308
+ The screens table says what each screen weighs and the bootstrap tab what the first load holds.
309
+ Neither answers the question a heavy screen raises next: _which package_ makes it heavy, and does
310
+ that package cost every screen or only some? That question is about a path (package → chunk →
311
+ screen), and the Flow tab draws those paths (`core/analysis/views/flow/`).
312
+
313
+ **Three columns.**
314
+
315
+ - **Left:** each package, plus your own code as one node. Each node is as tall as what it weighs in
316
+ the build.
317
+ - **Middle:** where those bytes live. The bootstrap comes first; every screen downloads it before
318
+ anything. Then the shared chunks, ranked by size × screens. Last, every screen's own chunks.
319
+ - **Right:** each screen with its first trip, split into bootstrap + shared + own, the same three
320
+ figures as the screens table.
321
+
322
+ A ribbon's width is bytes, and its colour is where those bytes live.
323
+
324
+ **Two scales, on purpose.** The left and middle columns count each byte once: `chart.js` is 224 kB
325
+ however many screens load it. The right column counts each byte once per screen that downloads it.
326
+ On one scale, the right column of a build with twelve screens would be about ten times taller than
327
+ the left one. So the screens get a scale of their own: their heights compare with each other and
328
+ with nothing else. Each middle node shares its height out among the screens that download it, and
329
+ the bootstrap leaves in as many equal ribbons as there are screens. The page says this under the
330
+ legend.
331
+
332
+ **A package inside a chunk is its raw share.** It is the treemap's `≈` figure. The bytes the
333
+ metafile gives to no file form one node, the bundler's code. That way every chunk is fully counted
334
+ and the columns add up; the tests check this on every fixture, raw and gzip. A folder read without
335
+ its source maps describes nothing inside its chunks, so those bytes form a node called "not broken
336
+ down". The first version put them under the bundler's name, which put a whole build there.
337
+
338
+ **Readable at any size.** Past 12 packages, 8 shared chunks or 12 screens, the rest fold into one
339
+ node per column that lists what it holds. The columns are ordered with a barycentre pass (two
340
+ sweeps between the middle and the screens, then the packages), and the folded nodes stay at the
341
+ bottom. A test checks the order crosses no more ribbons than sorting by weight.
342
+
343
+ **The sentence on top** is worked out, not written. The first case that applies wins:
344
+
345
+ 1. A package that more screens download than import it, through the bootstrap or a shared chunk.
346
+ "Import" means your own files import it directly, and that is all the sentence claims.
347
+ 2. What makes the heaviest screen heavy, beyond the bootstrap.
348
+ 3. The heaviest part of the bootstrap, when no screen adds anything to it.
349
+ 4. Without source maps, the heaviest screen and its three parts.
350
+
306
351
  ## 3. The signals
307
352
 
308
353
  A number on its own is not a problem. What turns data into something worth touching is context: how
@@ -814,13 +859,25 @@ shared chunk, `metafile: true`, `minify: true` — comes out at **0.9892**, and
814
859
  **0.9975**: the deficit is the per-chunk wrapper, in the direction the overhead predicts. Whatever
815
860
  moves the figure sits between esbuild's metafile and the folder Angular writes, on some of its builds.
816
861
 
817
- **Why it is a signal and not a correction.** Scaling the breakdown down by the ratio would make the
818
- totals reconcile and would be a model: it assumes every file moved by the same proportion, and nothing
819
- here measures whether it did. There is an exact answer available instead, and the signal's fix is to
820
- go and get it — build with source maps and drop the folder, and the split is measured on the generated
821
- file itself. On the same Angular 22 probe, the graph walk over the metafile alone totals 280 153 bytes
822
- against a 222 555-byte bootstrap (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It
823
- does not fire on chunks a map covered, because for those there is nothing left to drift.
862
+ **A signal, and since 28/10/2026 a correction too.** This section used to stop at the signal:
863
+ scaling the breakdown down by the ratio would make the totals reconcile and would be a model, assuming
864
+ every file moved by the same proportion. Two things changed that. The cause was found — Angular's
865
+ chunk optimizer bundles the chunks again after esbuild and shares each chunk's length out in
866
+ proportion, before the last minification — which is exactly a same-proportion move. And leaving the
867
+ figures as they were made the report contradict itself on every card but this one: espaciot-app
868
+ without maps read "Bootstrap 117 kB" over "≈117 kB of packages against ≈30 kB of your own" (147),
869
+ and one package was 53 kB in one card and 72 kB in another. Scaled to the file, the same build gives
870
+ 93 + 24; built with maps, it measures 93 + 25.
871
+
872
+ So a chunk whose parts add up to **more** than the file, past the same 5 % and kibibyte, has them
873
+ scaled down to it (`chunkScalesOf`), and every card's figures add up. Never up: parts short of the
874
+ file are the wrapper and the runtime, which belong to nobody's file, and sharing them out would be
875
+ inventing them. This card still fires, saying the metafile was off and by how much, because the
876
+ scaled figures are a proportion and the exact answer is still one flag away — build with source maps
877
+ and drop the folder, and the split is measured on the generated file itself. On the same Angular 22
878
+ probe, the graph walk over the metafile alone totals 280 153 bytes against a 222 555-byte bootstrap
879
+ (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It does not fire on chunks a map
880
+ covered, because for those there is nothing left to drift.
824
881
 
825
882
  ### 3.24 What `loadline.json` forbids
826
883
 
@@ -1123,6 +1180,17 @@ line carries a **count as a screen** button, as every row of the table carries a
1123
1180
  telling a screen from a piece of one is partly done by reading file names, and no set of names fits
1124
1181
  every project. A reclassified entry is remembered with the session.
1125
1182
 
1183
+ ### What is refused by name: a native app
1184
+
1185
+ An Expo export for Android or iOS — a `metadata.json` naming those platforms, bundles under
1186
+ `_expo/static/js/android/` or `ios/`, Hermes bytecode (`.hbc`, or any file starting with its magic
1187
+ number) — is refused with exit code `2` and the code `NATIVE_APP` in `--format json`, saying what it
1188
+ is. So is the project folder of an Expo app with no web build in it. Loadline weighs what a browser
1189
+ downloads per screen; a native app arrives installed from a store, and read as a web build it gave a
1190
+ 985 kB bootstrap with no screens, a first trip of 0 B and nine seconds on slow 4G for something
1191
+ nobody downloads that way. What a native bundle holds is what Expo Atlas shows. A web export
1192
+ (`expo export --platform web`) is a web build and is read as one.
1193
+
1126
1194
  ### The other files, all optional
1127
1195
 
1128
1196
  | File | What is read |
@@ -1138,6 +1206,13 @@ every project. A reclassified entry is remembered with the session.
1138
1206
  | `package.json` | `scripts` (to follow the pipeline's commands), `zone.js` and `@angular/core` |
1139
1207
  | `.gitlab-ci.yml` / GitHub workflow | Commands containing `ng build` or a build script, with the job they live in |
1140
1208
 
1209
+ A source map is read in either shape the specification allows: a regular map, with `sources` and
1210
+ `mappings` at its root, or an **index map** — `sections`, each with an offset and a map of its own —
1211
+ which is what Metro writes (an Expo export's map came in 2,290 sections). The sections are joined
1212
+ into one map where the JSON is read, so every reader sees the same thing. A section that points at
1213
+ another file (`url`) is not fetched, and a map that cannot be read is said to be there in a format
1214
+ Loadline does not read, never counted as no map.
1215
+
1141
1216
  The page's "Export analysis" button and the command's `--export` write the same file. That matters
1142
1217
  more than it sounds: a `stats.json` is the only baseline a build can produce on its own, and Vite,
1143
1218
  Rollup, SvelteKit, Nuxt, Astro and Solid do not write one — so before `--export` the only way to get a
@@ -1146,6 +1221,14 @@ baseline for any of them was to open a browser and press a button, which a pipel
1146
1221
  The pipeline file is read without a YAML parser, line by line, which is why every command found is
1147
1222
  shown in the Project tab with what it resolves to: if the heuristic gets it wrong, it shows.
1148
1223
 
1224
+ **The name at the top of the report** comes from one order, whatever else was passed: the page's
1225
+ `<title>` in `index.html`, then the `name` of a `package.json` (the one `--project` names, or the
1226
+ nearest one above the build), then the Angular project, then the build folder's own name. The title
1227
+ is first because it is in the build: a package name is only known with `--project` or when the
1228
+ build sits inside its repository, and the same build copied to a temporary folder was called by its
1229
+ title without the flag and by its package with it. A title left as a generator wrote it (`Vite +
1230
+ React + TS`, `React App`) names a template, and is skipped.
1231
+
1149
1232
  ### How `loadline.json` is allowed to grow
1150
1233
 
1151
1234
  The file is `version: 1`, and the rule is that **every addition is an optional block and the version