@bymaksym/loadline 1.0.0 → 1.2.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 (112) hide show
  1. package/README.md +229 -43
  2. package/dist/cli/cli/args.js +79 -128
  3. package/dist/cli/cli/gates.js +80 -14
  4. package/dist/cli/cli/main.js +164 -33
  5. package/dist/cli/cli/memory.js +40 -4
  6. package/dist/cli/cli/{declared.js → read/declared.js} +1 -1
  7. package/dist/cli/cli/read/locate.js +214 -0
  8. package/dist/cli/cli/{read-build.js → read/read-build.js} +149 -84
  9. package/dist/cli/cli/read/read-config.js +120 -0
  10. package/dist/cli/cli/{html-report.js → render/html-report.js} +14 -10
  11. package/dist/cli/cli/render/render-agent.js +114 -0
  12. package/dist/cli/cli/render/render-asked.js +104 -0
  13. package/dist/cli/cli/render/render-badge.js +140 -0
  14. package/dist/cli/cli/{render-json.js → render/render-json.js} +18 -5
  15. package/dist/cli/cli/{render-markdown.js → render/render-markdown.js} +5 -5
  16. package/dist/cli/cli/{render-pr.js → render/render-pr.js} +33 -13
  17. package/dist/cli/cli/{render-sarif.js → render/render-sarif.js} +8 -3
  18. package/dist/cli/cli/{render-text.js → render/render-text.js} +118 -111
  19. package/dist/cli/cli/render/terminal.js +55 -0
  20. package/dist/cli/cli/report.js +68 -27
  21. package/dist/cli/cli/self-check.js +19 -23
  22. package/dist/cli/cli/since-last.js +2 -2
  23. package/dist/cli/cli/text/text-errors.js +124 -0
  24. package/dist/cli/cli/text/text.js +343 -0
  25. package/dist/cli/cli/text/usage.js +240 -0
  26. package/dist/cli/src/app/core/analysis/analysis.js +63 -23
  27. package/dist/cli/src/app/core/analysis/{barrels.js → graph/barrels.js} +1 -1
  28. package/dist/cli/src/app/core/analysis/{blast.js → graph/blast.js} +56 -17
  29. package/dist/cli/src/app/core/analysis/{cycles.js → graph/cycles.js} +1 -1
  30. package/dist/cli/src/app/core/analysis/{importers.js → graph/importers.js} +1 -1
  31. package/dist/cli/src/app/core/analysis/{insights.js → graph/insights.js} +10 -4
  32. package/dist/cli/src/app/core/analysis/invariant.js +1 -1
  33. package/dist/cli/src/app/core/analysis/metafile.types.js +7 -1
  34. package/dist/cli/src/app/core/analysis/{delivery.js → screens/delivery.js} +1 -1
  35. package/dist/cli/src/app/core/analysis/{entries.js → screens/entries.js} +50 -9
  36. package/dist/cli/src/app/core/analysis/screens/marks.js +32 -0
  37. package/dist/cli/src/app/core/analysis/screens/route-files.js +116 -0
  38. package/dist/cli/src/app/core/analysis/{sourcemap.js → sourcemap/sourcemap.js} +106 -7
  39. package/dist/cli/src/app/core/analysis/{split-drift.js → sourcemap/split-drift.js} +1 -1
  40. package/dist/cli/src/app/core/analysis/tool.js +83 -0
  41. package/dist/cli/src/app/core/assets/assets.js +134 -15
  42. package/dist/cli/src/app/core/baseline/baseline.js +0 -0
  43. package/dist/cli/src/app/core/{intake → build-text}/index-html.js +168 -13
  44. package/dist/cli/src/app/core/build-text/route-table.js +178 -0
  45. package/dist/cli/src/app/core/build-text/tool-marks.js +54 -0
  46. package/dist/cli/src/app/core/caching/caching.js +121 -43
  47. package/dist/cli/src/app/core/caching/from-analysis.js +20 -4
  48. package/dist/cli/src/app/core/config/config-text.js +90 -0
  49. package/dist/cli/src/app/core/config/config-values.js +358 -0
  50. package/dist/cli/src/app/core/config/loadline-config.js +81 -16
  51. package/dist/cli/src/app/core/config/merge-config.js +98 -0
  52. package/dist/cli/src/app/core/deps/deps.js +104 -16
  53. package/dist/cli/src/app/core/export/summary.js +29 -5
  54. package/dist/cli/src/app/core/findings/actions.js +3 -1
  55. package/dist/cli/src/app/core/findings/{boot-single.js → bundle/boot-single.js} +3 -3
  56. package/dist/cli/src/app/core/findings/{dupes.js → bundle/dupes.js} +8 -5
  57. package/dist/cli/src/app/core/findings/{graph.js → bundle/graph.js} +30 -18
  58. package/dist/cli/src/app/core/findings/{own-in-boot.js → bundle/own-in-boot.js} +9 -5
  59. package/dist/cli/src/app/core/findings/{requests.js → bundle/requests.js} +3 -3
  60. package/dist/cli/src/app/core/findings/{shipped.js → bundle/shipped.js} +28 -14
  61. package/dist/cli/src/app/core/findings/compose.js +6 -1
  62. package/dist/cli/src/app/core/findings/effort.js +2 -0
  63. package/dist/cli/src/app/core/findings/finding.types.js +1 -0
  64. package/dist/cli/src/app/core/findings/findings.js +48 -19
  65. package/dist/cli/src/app/core/findings/{assets.js → folder/assets.js} +38 -14
  66. package/dist/cli/src/app/core/findings/{caching.js → folder/caching.js} +16 -9
  67. package/dist/cli/src/app/core/findings/{page.js → folder/page.js} +6 -2
  68. package/dist/cli/src/app/core/findings/{scan.js → folder/scan.js} +25 -11
  69. package/dist/cli/src/app/core/findings/kind-names.js +163 -0
  70. package/dist/cli/src/app/core/findings/{deps.js → supplied/deps.js} +13 -8
  71. package/dist/cli/src/app/core/findings/supplied/forbidden.js +71 -0
  72. package/dist/cli/src/app/core/findings/{situation.js → supplied/situation.js} +2 -2
  73. package/dist/cli/src/app/core/findings/text/causes.js +39 -0
  74. package/dist/cli/src/app/core/findings/{finding-html.js → text/finding-html.js} +8 -1
  75. package/dist/cli/src/app/core/findings/{finding-text.js → text/finding-text.js} +208 -77
  76. package/dist/cli/src/app/core/findings/text/tool-advice.js +97 -0
  77. package/dist/cli/src/app/core/format/format.utils.js +158 -11
  78. package/dist/cli/src/app/core/format/ownership.js +93 -0
  79. package/dist/cli/src/app/core/i18n/en.js +76 -17
  80. package/dist/cli/src/app/core/i18n/es.js +82 -22
  81. package/dist/cli/src/app/core/intake/bundle-graph.js +281 -43
  82. package/dist/cli/src/app/core/intake/dist-files.js +82 -14
  83. package/dist/cli/src/app/core/intake/embedded.js +11 -1
  84. package/dist/cli/src/app/core/intake/unreached.js +139 -0
  85. package/dist/cli/src/app/core/intake/webpack-modules.js +185 -0
  86. package/dist/cli/src/app/core/intake/webpack-stats.js +298 -0
  87. package/dist/cli/src/app/core/project/project-context.js +16 -4
  88. package/dist/cli/src/app/core/project/project-name.js +36 -0
  89. package/dist/cli/src/app/core/scan/scan.js +58 -19
  90. package/dist/cli/src/app/core/scan/secrets.js +23 -3
  91. package/dist/cli/src/app/core/situation/situation-text.js +23 -0
  92. package/dist/cli/src/app/core/situation/situation.js +6 -4
  93. package/dist/cli/src/app/core/timing/timing.js +5 -2
  94. package/dist/cli/src/app/core/whatif/defer.js +29 -4
  95. package/dist/cli/src/app/core/whatif/source-importers.js +58 -0
  96. package/dist/cli/src/app/core/whatif/why.js +102 -0
  97. package/docs/CONFIG-REFERENCE.md +230 -0
  98. package/docs/CONFIG.md +511 -0
  99. package/docs/HOW-IT-WORKS.md +286 -25
  100. package/loadline.html +24 -20
  101. package/loadline.schema.json +1209 -0
  102. package/package.json +35 -29
  103. package/dist/cli/cli/locate.js +0 -60
  104. package/dist/cli/cli/text.js +0 -215
  105. /package/dist/cli/cli/{read-build.types.js → read/read-build.types.js} +0 -0
  106. /package/dist/cli/cli/{render-json.types.js → render/render-json.types.js} +0 -0
  107. /package/dist/cli/cli/{text.types.js → text/text.types.js} +0 -0
  108. /package/dist/cli/src/app/core/analysis/{exclusive.js → graph/exclusive.js} +0 -0
  109. /package/dist/cli/src/app/core/analysis/{insights.types.js → graph/insights.types.js} +0 -0
  110. /package/dist/cli/src/app/core/analysis/{module-graph.js → graph/module-graph.js} +0 -0
  111. /package/dist/cli/src/app/core/analysis/{sourcemap.types.js → sourcemap/sourcemap.types.js} +0 -0
  112. /package/dist/cli/src/app/core/findings/{finding-plain.js → text/finding-plain.js} +0 -0
@@ -104,6 +104,23 @@ Three more rules joined them:
104
104
  - **Data is not a screen.** `import('./locales/ru-RU.json')` produces a lazy entry exactly like a
105
105
  route does. Excalidraw lazy-loads fifty languages, and its table came out with sixty-one rows for
106
106
  an application with one screen. Data entries are listed separately.
107
+ - **Where the code has a route table, the table decides.** Read from a build folder, the chunks still
108
+ carry the router's table, because its keys are the router's API and no minifier renames them: an
109
+ object with a `path` and a `component`, `loadComponent`, `loadChildren`, `lazy`, `getComponent` or
110
+ `asyncComponent` whose value imports the chunk (`core/build-text/route-table.ts`); a router that
111
+ uses another word is named in `build.routeKeys`. Stencil's loader lists its components the same
112
+ way — the id of each chunk and the tag it defines — and is read as its table: components named by
113
+ their tag, and the polyfills it fetches for old browsers, which it does not list, no screens.
114
+ Sapper's manifest has none of those shapes — a list of components, `{js:()=>import("./index.e902f999.js")}`,
115
+ and a list of routes, each a regular expression and its page by place in the first list — and is
116
+ read too: the expression gives the path, its groups named by the route's parameters
117
+ (`/profile/[user]/[view]`). Without it, a Sapper build without source maps had seven screens called
118
+ `index`, told apart by their hashes. With two routes found, a lazy chunk
119
+ a route imports is a screen, named after the route when there is no source map to name it, and one
120
+ no route imports is not: Nuxt without maps listed fourteen language files and its i18n config as
121
+ screens named after hashes, and PocketBase listed seventeen documentation tabs. Without a table,
122
+ every lazy chunk stays a screen as before, and the report says it found none — a stats file has
123
+ no code to look in, so it says nothing then.
107
124
 
108
125
  ### 2.4 Splitting the cost
109
126
 
@@ -140,7 +157,14 @@ report is in compressed figures. To keep the two units from being confused, the
140
157
  its raw size under the compressed one, and the head of its file tree says `raw` and how much of the
141
158
  chunk is unattributed. Those bytes are the bundler's own code — module wrapper, banners — which
142
159
  belongs to no input file. The sum of the files plus that remainder is the raw size on the row, when
143
- the two measurements agree, which is checked rather than assumed (§3.23). Other tools
160
+ the two measurements agree, which is checked rather than assumed (§3.23).
161
+
162
+ A signal that puts a figure from inside a chunk in a sentence gives it in the report's unit anyway, at
163
+ the ratio the bytes around it compress by and with `≈`: "≈80 kB of dependencies" for the chunks that
164
+ mix them with your code, the share of the chunk's own compressed size; packages against your own code
165
+ in the first load, at the ratio the bootstrap compresses by. Given raw, a gzip report said "283 kB
166
+ re-invalidated" and "268 kB of packages" over an 87 kB bootstrap, and the first of those was being
167
+ compared against a threshold in gzip. Other tools
144
168
  (`esbuild-visualizer`, Sonda) show the raw figure as the chunk's headline, which is why their numbers
145
169
  look nothing like Loadline's until both are read in the same unit.
146
170
 
@@ -220,7 +244,7 @@ chunks, the question none of them answers is whether the build is **well divided
220
244
 
221
245
  That is not a property of any row. More chunks is not better and fewer is not better: what matters is
222
246
  that what a screen needs at once arrives in few pieces and what it may never need stays apart. So it
223
- is measured on the distribution (`core/analysis/shape.ts`), with two numbers per zone:
247
+ is measured on the distribution (`core/analysis/screens/shape.ts`), with two numbers per zone:
224
248
 
225
249
  - **Concentration**: how much of a zone sits in its largest chunk. Fifteen shared chunks where one
226
250
  holds 93 % is a different situation from fifteen even ones, and a list of fifteen rows hides it.
@@ -272,6 +296,11 @@ was loaded with that page; without it, Loadline says "not known" rather than pri
272
296
  from the wrong thing. The page is read with regular expressions rather than `DOMParser`, so the
273
297
  command and the browser read it the same way.
274
298
 
299
+ The command's **whole first trip** — everything downloaded before anything appears — counts those
300
+ late chunks too. Read off `index.html` alone it left them out, and a real Angular build printed "the
301
+ whole first trip is 133 kB" under a 464 kB bootstrap: the 346 kB missing was the very chunk that made
302
+ the first load take two trips. Late or not, it arrives before the first paint.
303
+
275
304
  ---
276
305
 
277
306
  ## 3. The signals
@@ -336,6 +365,11 @@ moved nothing.
336
365
  Only a copy that actually weighs something in some chunk counts: a version resolved but tree-shaken
337
366
  away is not paid twice.
338
367
 
368
+ The version comes from the pnpm directory name, which carries more than the version: the peers it was
369
+ resolved against, or a hash of them — `@angular+material@22.1.6_2ffb4168…` — and, on a name too long
370
+ for the disk, a cut — `@angular+platform-browser@2_49839d…`. Only a whole `x.y.z` at its head is taken;
371
+ the cut one is given no version rather than `2`.
372
+
339
373
  ### 3.5 Expensive screen
340
374
 
341
375
  **Fires when** a screen carries more than 6× the median of its own code, and over 100 kB.
@@ -348,13 +382,35 @@ _inside_ the screen — a viewer, an editor, a chart — it belongs in a deferre
348
382
  These fire only with a baseline loaded: the previous build's `stats.json`, a Loadline export, or the
349
383
  whole previous build folder. Both measurements are always compared in the same mode — a bare previous
350
384
  `stats.json` is compared raw even if the report is compressed, and the table says so. For compressed
351
- against compressed, give the previous folder with its `stats.json` inside.
352
-
353
- - **The bootstrap has grown** — by 10 % and 10 kB or more, editable under Criteria.
385
+ against compressed, give the previous folder: with its `stats.json` (or `browser-stats.json`) inside, or
386
+ without one, in which case its graph is read from its chunks as the build on screen is. The page used
387
+ to refuse a previous folder without `stats.json`, which left every Vite build without a way to be
388
+ compared there, and it did not know the name Angular gives that file from 22.2 on.
389
+
390
+ - **The bootstrap has grown** — by 10 % and 10 kB or more, editable under Criteria. It also says
391
+ **where the growth comes from**: the packages and the folders of your own code that entered, left,
392
+ grew or shrank in the bootstrap, biggest first, up to five. The delta alone answered "how much";
393
+ the question on a merge request is "what did I add", and before this it was answered by opening
394
+ two reports side by side. The weights are raw bytes per package, shown in the report's unit at the
395
+ ratio the bootstrap compresses by — `≈`, like every saving. A move under 512 raw bytes is left
396
+ out as noise. Own folders are compared only when both snapshots record them; against an export
397
+ older than that, the list is packages only, and says so, rather than reading every folder of the
398
+ project as new.
354
399
  - **A package has entered the bootstrap** — an npm package that was not in the baseline's. Project
355
400
  folders do not count: they change with every commit.
356
401
  - **A screen has grown** — shared + own is compared, **without the bootstrap**. Comparing totals, a
357
- bigger bootstrap would flag all twenty screens at once.
402
+ bigger bootstrap would flag all twenty screens at once. Each screen it names also says **where its
403
+ growth comes from**, by the bootstrap's rules: the packages and own folders that moved in the
404
+ chunks that screen loads beyond the bootstrap, up to three per screen, raw weights shown at the
405
+ ratio _that screen_ compresses by. "`reports` +120 kB" sent the person to open two reports;
406
+ "`xlsx` ≈+118 kB (new)" is the answer. It needs both snapshots to carry the screen's breakdown:
407
+ against an older export, or a build that did not say what is inside its chunks, the screen is
408
+ named without causes rather than with every package of it read as new.
409
+
410
+ The bootstrap follows the same rule. A snapshot of a folder read without source maps records an
411
+ empty list of packages next to a bootstrap of 200 kB: not "nothing", "not known". Against one, the
412
+ growth is given without causes and no package is said to have entered — before, a real build reported
413
+ `@angular/core` as new against its own previous version.
358
414
 
359
415
  ⚠️ **One trap remains**: when a near-global shared chunk grows, every screen loading it goes up by the
360
416
  same amount — in one real app, 19 screens at "+247 kB". So when most screens grow by about the same
@@ -542,6 +598,9 @@ file — `0fPdmq0U.js` rather than `orders` — and there is no breakdown by pac
542
598
  entry point. Everything else comes out in full. It exists because two real builds, elk and immich,
543
599
  neither of which publishes maps, came out as a page of hashes with nothing to explain them.
544
600
 
601
+ With it, "nothing stands out" is not said: that card vouches for the breakdown — no package shipped
602
+ twice — and there is no breakdown to vouch for.
603
+
545
604
  ### 3.18 What the report cannot reach
546
605
 
547
606
  **Fires when** some JavaScript of the build is imported by nothing reachable from the entry point, by
@@ -573,7 +632,16 @@ single-page application is nearly everything. It does not grow with depth; it ju
573
632
  this build — which chunk names the most others, and how many name it — and reported as LOW, MID or
574
633
  HIGH with the reason. LOW is the runtime-chunk shape, which is what webpack emits and what largely
575
634
  avoids the problem, with the caveat that usually gets dropped: that chunk changes on every deploy and
576
- has to be tiny and inlined, or the cost comes straight back.
635
+ has to be tiny and inlined, or the cost comes straight back. That caveat is for a chunk of the first
636
+ load: when the small chunk holding the names is lazy, as in Angular RealWorld, it comes with the
637
+ screen that needs it, there is no page to inline it into, and the advice is to keep it small.
638
+
639
+ **A name without a hash stops it.** The cascade travels through names that change, and a chunk written
640
+ as `index.js` changes its content on every edit below it and never its name. Solid's Rollup template
641
+ ships exactly that, and the report said "touching any leaf moves the whole build" of a build where the
642
+ eight chunks importing `index.js` never change for it. Those edges are not followed. One large file
643
+ naming most of the build while few chunks carry its name is then its own shape, and said as such: a
644
+ change stops at that file, and what it costs is the file.
577
645
 
578
646
  **With a baseline it stops being a model.** Two builds diffed by file name _are_ the delta a browser
579
647
  would pay. The changed files split into the ones where the edit landed and the ones that only moved
@@ -754,6 +822,31 @@ file itself. On the same Angular 22 probe, the graph walk over the metafile alon
754
822
  against a 222 555-byte bootstrap (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It
755
823
  does not fire on chunks a map covered, because for those there is nothing left to drift.
756
824
 
825
+ ### 3.24 What `loadline.json` forbids
826
+
827
+ **Fires when** a rule of `forbidden` matches a file of the build: a package by name, or files of the
828
+ project by path, anywhere in the build or — with `"in": "bootstrap"` — in the first load. One signal
829
+ per rule, `high` whatever the size.
830
+
831
+ Every other signal is this tool's opinion of a build. This one is the team's, written down, and the
832
+ tool only says where it is broken and which import breaks it. That is why the size does not decide
833
+ the severity: a 2 kB locale of `moment` breaks "no moment" exactly as much as the whole library, and
834
+ a threshold under which a forbidden package passes would be a second rule nobody wrote.
835
+
836
+ **Declarative, not code.** The obvious alternative was the ESLint model — rules as plugins somebody
837
+ installs. A plugin cannot run in the page, which is one offline HTML file, so the page and the
838
+ command would judge the same `loadline.json` differently, which is the disagreement the file exists
839
+ to end. A rule over data the analysis already has — every file, its package and its zone — runs in
840
+ both. Patterns are `*` and nothing more, matched by hand like the ones of `build`: a regular
841
+ expression built from somebody's text is one more thing that can hang on a bundle of megabytes.
842
+
843
+ **An ordinary signal, on purpose.** Its key is the rule as written, so an exception is an entry in
844
+ `accepted` with a reason and a date, and failing on it is `failOn` or `failOnSignals`. dependency-cruiser
845
+ and Statoscope, the closest prior art, give their rules a severity of their own; here that would have
846
+ been a second, smaller version of the gates and of `accepted` living inside one block. Statoscope's
847
+ `restricted-packages` looks at the whole compilation: "never in the first load" is the part none of
848
+ them says.
849
+
757
850
  ---
758
851
 
759
852
  ## 4. Traps found while building it
@@ -806,7 +899,8 @@ which keeps its `path`; only `providers` and `loadComponent` move down to the ch
806
899
  ## 5. Data format
807
900
 
808
901
  Loadline reads the [esbuild metafile](https://esbuild.github.io/api/#metafile), written by Angular
809
- with `--stats-json` and by plain esbuild with its metafile option. The keys it uses:
902
+ with `--stats-json` and by plain esbuild with its metafile option, and webpack's `stats.json`,
903
+ translated into one (below). The keys it uses:
810
904
 
811
905
  | Key | What for |
812
906
  | ---------------------------------- | --------------------------------------------------------------------------------- |
@@ -838,30 +932,157 @@ module bundle carries its graph in the code that ships:
838
932
  so the entry ends up imported by its own children: there is no "chunk nobody imports" to find. Only
839
933
  `index.html` can name it. It does so in one of two ways — a `<script src>`, or an `import()` inside
840
934
  an inline script, which is how SvelteKit starts its application.
841
- - **A folder of webpack or Turbopack chunks is refused.** Those builds have entry chunks and no graph:
935
+ - **A folder of webpack or Turbopack chunks is refused, and its stats file read instead.** Those builds have entry chunks and no graph:
842
936
  their imports are numbers the loader resolves at run time. Read as ES modules, a Next.js export came
843
937
  out as one bootstrap of seven files, zero screens and "nothing stands out" — confident, detailed and
844
- false. A folder whose entry carries that runtime **and** where nothing imports anything lazily is
845
- named for what it is. Both halves are needed: the marker alone would refuse an ES bundle carrying
846
- one webpack-built dependency, and no lazy edges alone is an ordinary application with every route
847
- eager.
938
+ false. Before webpack 5 the runtime was called `webpackJsonp` (Create React App 1 to 3, Vue CLI), and
939
+ until it was known a webpack 4 build of three lazy routes read as one bootstrap of 1 kB and no
940
+ screens; `fixtures/webpack4-app` is that build. A webpack build of one chunk writes no runtime and is
941
+ still read: it has no graph to lose. A folder whose entry carries that runtime, where nothing imports anything lazily **and** where
942
+ another chunk registers with it is named for what it is. All three are needed: the marker alone
943
+ would refuse an ES bundle carrying one webpack-built dependency, no lazy edges alone is an ordinary
944
+ application with every route eager, and a runtime with nothing to load is ember-auto-import's
945
+ inside an Ember `vendor.js`, which was refused as Next.js.
946
+ - **Before ES modules the graph is still in the files, as strings.** AMD writes `define(["./a.js"], …)`
947
+ and SystemJS `System.register(["./a.js"], …)`: both are read as static edges, with `.js` tried when
948
+ the id leaves it off, as RequireJS and Rollup's `amd` output do. A page may start the application
949
+ from `data-main` or from a string in an inline script (`s.src="/client/client.1180.js"`, Sapper's
950
+ way) rather than a tag, and both count. Polymer's AMD build read as a 2 kB loader, zero screens
951
+ and 1.1 MB "in no figure here", and Sapper's was refused with "no index.html" next to its page.
952
+ - **Last, a chunk nothing imports but something names.** A loader older than `import()`, or one that
953
+ builds the file name at run time, keeps the names as plain strings: Stencil lists components as
954
+ `"p-w91mnxr1"` and loads `./${id}.entry.js`. A chunk no edge reaches, whose name — or, when it
955
+ looks like a hash, the part before its first dot — appears as a string in a chunk the application
956
+ reaches, is taken as loaded on demand by it. It only ever touches what nothing else reached, so
957
+ a build whose chunks are all reached reads exactly as before, and a plain word (`index`, `vendor`)
958
+ is never a name. A Stencil app went from zero screens and 33 of 36 chunks unaccounted for to its
959
+ components.
960
+ - **What no screen downloads is left out and counted**, the way the server side is: what only a
961
+ `<script nomodule>` (or the `catch` of an inline loader) reaches is the copy for old browsers, and
962
+ a service worker — registered in the page or the code — runs beside the page with what it
963
+ imports. Counted, a Stencil bootstrap was 48 kB of which 42 were its SystemJS fallback.
964
+ - **When the rules are wrong, `build` in `loadline.json` says it**: `entries`, `ignore`, `screens` and
965
+ `page`, file names with `*` ([Configuring Loadline](CONFIG.md#when-it-reads-your-build-wrong)). Every
966
+ rule here is a guess about how some tool writes a folder, and a tool that does something new will
967
+ get past them; the way through should not be a release. The page asks for `entries` where the
968
+ folder was refused, and the command takes it as `--entry`.
969
+ - **A folder comes in four ways, and all of them read the stats file inside it first.** Dropped,
970
+ chosen with the button, picked with the API that keeps it, or read again after a rebuild: webpack
971
+ writes its `stats.json` inside the folder it builds, and only the drop looked for it — the same
972
+ folder chosen with the button was refused with "put the stats file in the folder", where it was.
973
+ And a drop the browser will not list is said: Chrome, on a page opened from the disk, hands over
974
+ the folder and fails to read what is inside it, and the drop did nothing and said nothing. The
975
+ button reads the same folder there.
976
+ - **The same file under two names is a copy that travels or a copy that is stored.** Two names with
977
+ one content are two cache entries when the page or the code asks for both — Sapper links `main.css`
978
+ and its runtime loads `chunk.css`. When it asks for one or none, the second copy is never
979
+ downloaded and costs the deploy, not the visit: Stencil writes its global stylesheet as `app.css`
980
+ and again under a hash, the page asks for neither, and the report said a visitor downloads both.
848
981
  - **Without `.js.map` the report loses the inside of each chunk**, and nothing else.
982
+ - **With them it still does not know who imports what.** A map says which source wrote each stretch
983
+ of a chunk; the `import` statements between those sources were erased by the bundler. So the chain
984
+ from the entry to a package, its exclusive weight, the files importing it, and what `--what-if`
985
+ would save are "not known" for a folder read alone — not "nobody imports it" and "0 B", which is
986
+ what a real build printed for `@angular/material`, 92 kB of its bootstrap. The `stats.json` has
987
+ the edges.
988
+ - **Without maps, a screen is named the way the bundler named its chunk.** Rollup, Vite and esbuild
989
+ name a chunk after the module it starts at and append an eight-character hash, so `Article-BZRh73np.js`
990
+ is the screen `Article`. A real Vue build had its table read `Article-BZRh73np` under a signal saying
991
+ every row was a hash nobody could read. A name that is only a hash (`0fPdmq0U.js`), or Angular's
992
+ `chunk-`, stays what it is, and that signal is for those.
993
+ - **"No source maps" is said of the folder only when no chunk of the bootstrap has one.** Vite writes no
994
+ map for the 84 bytes of `plugin-vue:export-helper`, and a folder with sixteen maps was announced as
995
+ having none, with every saving "not known". One chunk missing its map is named, with its weight.
996
+ Nor is a chunk with nothing of yours in it unknown: esbuild puts its runtime helpers in a chunk whose
997
+ `inputs` is `{}`, and an Angular build read with its `stats.json` was told it had no source maps.
998
+ - **A chunk is named after the module it starts at, not its template.** Angular names every chunk
999
+ `chunk-<hash>.js`, so the name says nothing, and the last source in the map is taken — the bundler
1000
+ writes the module a chunk exists for last. Angular lists a component's template after the
1001
+ component, so that was `orders.page.html`: templates and stylesheets are skipped.
1002
+ - **Angular's own maps point outside `node_modules/@angular`.** Its packages are built with Bazel,
1003
+ and a file of `@angular/forms` comes out as `node_modules/.pnpm/k8-fastbuild-ST-…/bin/packages/forms/…`
1004
+ (`bin/src/material/…` for the components repository). Read as a path, that is a package called
1005
+ `.pnpm`; it is read as `@angular/forms`, and never as a second installed copy of it.
849
1006
 
850
1007
  The preload lists are the one place a bundler's own behaviour changes a figure. Vite does not wait for
851
1008
  a lazy chunk to arrive and be parsed before fetching what it imports — it bakes the list into the call
852
1009
  and asks for the whole set at once. Angular does not. Without reading those lists, every screen of a
853
1010
  Vite application would be counted one round trip deeper than it is.
854
1011
 
1012
+ ### webpack's `stats.json`
1013
+
1014
+ Refused on purpose until 09/10/2026, with "Statoscope does it better". It is also what nearly every
1015
+ application written before 2020 can produce — Angular up to 16, Create React App, Vue CLI, Gatsby,
1016
+ Nuxt 2, Rspack — and their folders cannot be read, so for them the refusal was the whole answer.
1017
+ The stats file has the three things the metafile has, in another shape, and
1018
+ `core/intake/webpack-stats.ts` translates it:
1019
+
1020
+ | webpack | metafile |
1021
+ | ------------------------------------ | ----------------------------------------------------------- |
1022
+ | `modules[]` and `chunks[].modules[]` | `inputs`, with the edges taken from each module's `reasons` |
1023
+ | `chunks[].files` and `assets[].size` | `outputs`, one per file the browser downloads |
1024
+ | `entrypoints[].chunks` | static edges: the files an entry starts with |
1025
+ | `chunks[].origins` | lazy edges: which file asked for the chunk, and where |
1026
+
1027
+ - **A lazy chunk group is one screen.** Every chunk sharing an origin — the `import()` at one place in
1028
+ one file — is fetched at once by `__webpack_require__.e`. The one holding the module asked for is
1029
+ the lazy entry; the others (the vendors `splitChunks` moved out, a chunk two routes share) travel
1030
+ with it, statically, and in the same round trip (`fetchedWith`, which plays the part of Vite's
1031
+ preload list).
1032
+ - **⚠️ A module's `size` is its source, before minification.** An Angular 8 main chunk is 2.9 MB of
1033
+ modules in a file of 560 kB. The per-file weights are those sizes shared out in proportion to what
1034
+ the file weighs, so they add up to the file: an estimate, since minification does not shrink every
1035
+ file by the same factor. A source map in the folder replaces it with a measurement, as for any build.
1036
+ - **A concatenated module is taken apart.** webpack 4 writes "`./src/main.ts + 20 modules` imports
1037
+ rxjs", and taken at its word `main.ts` was a barrel of 26 re-exports holding 546 kB. The file that
1038
+ wrote the import is found by what it wrote — a relative path that resolves, a package named in its
1039
+ source — or by the module webpack says imported it first; with none of them the edge is left out.
1040
+ webpack 5 names the file itself (`resolvedModule`).
1041
+ - **What is no file is left out**: `multi …` entries, `external "React"`, ignored modules. webpack's
1042
+ own runtime is filed under `node_modules/webpack`, and the loaders in front of a name, the query of
1043
+ a Vue component's part and the `./` are dropped, so the names are the metafile's.
1044
+ - **The stats file sits inside the folder it describes** when webpack writes it there — Angular 8's
1045
+ `dist/stats-es2015.json`, Create React App's `build/bundle-stats.json`, Vue CLI's `dist/report.json`
1046
+ — and the command and the page both read it with that folder, so the figures stay compressed.
1047
+
1048
+ `fixtures/webpack4-app` and `fixtures/webpack5-app` hold up the translation: the application of
1049
+ `vite-app` comes out with the same three screens and the same deferred widget.
1050
+
1051
+ ### Yours or theirs
1052
+
1053
+ Every rule that tells your code from a dependency asks one function (`core/format/ownership.ts`),
1054
+ where there used to be a dozen `includes('node_modules')`. A file is a dependency when it sits under
1055
+ `node_modules/`, with one convention read: Sapper keeps an application's own modules in
1056
+ `src/node_modules/` so they import by name, and the RealWorld app's `api.js` and `utils.js` came out
1057
+ as packages, Sapper's runtime as a package called `@sapper/app.mjs`. `build.own` and
1058
+ `build.dependencies` of `loadline.json` say the rest — a monorepo's `packages/ui` as the package `ui`,
1059
+ code of yours that a tool put under `node_modules/`. Like the language of the figures, it is set once
1060
+ from outside, by the command when it reads the file and by the page when one is dropped, because a
1061
+ path is named from everywhere in the report.
1062
+
1063
+ ### What wrote the build
1064
+
1065
+ The advice names a setting, and a setting belongs to a tool: an Ember build was told to write
1066
+ `sourcemap: true` in a Vite config it does not have, and that its `console.log` calls might be
1067
+ Angular's. The tool is in what is read already (`core/analysis/tool.ts`): the reader that translated a
1068
+ webpack stats file or found Stencil's list of components says so (`Metafile.builtBy`), the page names
1069
+ Sapper, Nuxt, SvelteKit, Ember and Polymer, a chunk names Vite (its preload helper) and Angular (the
1070
+ `ng-version` its runtime sets), and with source maps the packages name the framework. A metafile
1071
+ nobody else wrote is esbuild's. The command prints it in its lead and in `builtWith`, and the advice
1072
+ on source maps, on splitting the dependencies out and on whose a `console.log` is uses it; when
1073
+ nothing says, the advice names Vite and Angular, as before.
1074
+
855
1075
  ### What is not a metafile
856
1076
 
857
- Three files are commonly believed to be "the stats of my build". "Could not read it" would be a lie
858
- about all three: the file is fine, it is another format, and Loadline says which.
1077
+ Two files are commonly believed to be "the stats of my build". "Could not read it" would be a lie
1078
+ about both: the file is fine, it is another format, and Loadline says which.
859
1079
 
860
- | What | Where it comes from | Why it is not read |
861
- | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
862
- | webpack `stats.json` | Angular's `browser` builder (up to v16), Next.js, Rspack | Different shape: `chunks`/`modules`/`assets` arrays |
863
- | Vite `manifest.json` | `build.manifest: true` | Not needed: the folder itself says the same thing, and better |
864
- | `rollup-plugin-visualizer` | its `--json` output | A drawn tree, not the build's own record |
1080
+ | What | Where it comes from | Why it is not read |
1081
+ | -------------------------- | ---------------------- | ------------------------------------------------------------- |
1082
+ | Vite `manifest.json` | `build.manifest: true` | Not needed: the folder itself says the same thing, and better |
1083
+ | `rollup-plugin-visualizer` | its `--json` output | A drawn tree, not the build's own record |
1084
+
1085
+ A webpack `stats.json` written with `chunks` or `assets` off is refused too: it has nothing to analyse.
865
1086
 
866
1087
  The Vite manifest was the obvious thing to read and it aged badly in a few months: with Rolldown as
867
1088
  the default it is a compatibility layer somebody has to switch on, while the folder is always there
@@ -869,7 +1090,7 @@ and needs nobody to maintain a format.
869
1090
 
870
1091
  ### Two build shapes that are not a plain SPA
871
1092
 
872
- Both were analysed wrongly at first, and both are becoming more common (`core/analysis/entries.ts`).
1093
+ Both were analysed wrongly at first, and both are becoming more common (`core/analysis/screens/entries.ts`).
873
1094
 
874
1095
  **Server-side rendering writes one metafile with both sides in it.** Nobody downloads the server
875
1096
  bundle and it is usually the bigger of the two, so "the entry that reaches the most" would pick it and
@@ -943,6 +1164,28 @@ An answer nobody recognises becomes "unanswered" plus a line to print, the same
943
1164
  no reason: an answer is the only thing in this file that can move a colour, so it is the one mistake
944
1165
  that would otherwise change a verdict silently.
945
1166
 
1167
+ ### One file shared by many repositories
1168
+
1169
+ `extends` follows what every tool with shared configuration agrees on — semantic-release, ESLint,
1170
+ Renovate, TypeScript, Biome, Stylelint: left to right, the last one wins, the file that extends goes
1171
+ last, and a path is read from the file that writes it. Where they disagree is lists, and the choice
1172
+ here is **lists add up**, with Biome and webpack, against TypeScript, where a list in the child
1173
+ replaces the base's whole. "I set `include` and lost the base's" is the best-known surprise of
1174
+ `tsconfig.json`, and the lists of this file — packages, acceptances, forbidden rules — are things a
1175
+ repository adds to. Renovate decides per option, which is the one shape nobody can predict without
1176
+ reading its source. Taking something of the base away, which adding cannot do, already has a way that
1177
+ carries a reason: an acceptance.
1178
+
1179
+ Three things were left out, each for a reason. **No URLs**: a base fetched at run time needs network
1180
+ in CI and can change under a build without a commit; a package is pinned by the lock file. **No name
1181
+ prefix** (`eslint-config-`, `commitlint-config-`): one more rule to learn, and a name that is not the
1182
+ one in `package.json`. **No plugins**: see 3.24.
1183
+
1184
+ The page has no disk, so it cannot follow `extends`. It says so above the report and applies only
1185
+ what the dropped file says; `--print-config` writes the joined file for it. Two keys do not join:
1186
+ `situation`, which is one team's answers with its name on them, and `mode`, which a file cannot change
1187
+ under a base that wrote its sizes in another unit.
1188
+
946
1189
  ---
947
1190
 
948
1191
  ## 6. Design decisions
@@ -1016,6 +1259,23 @@ next to its module: `analysis.ts` computes, `analysis.types.ts` says what comes
1016
1259
  reading order — a module opens on its first function instead of two hundred lines of declarations.
1017
1260
  Types that never leave their file stay in it, and so does the input contract of a component.
1018
1261
 
1262
+ **No two folders of `core/` import each other in a loop.** Loadline reports import cycles between
1263
+ folders, and run on its own build it found one: seven folders — `intake`, `analysis`, `assets`,
1264
+ `caching`, `baseline`, `findings`, `config` — each reaching the others. Two small readers kept the loop
1265
+ closed: `index-html.ts` and `route-table.ts` lived in `intake/`, which reads a dropped folder with
1266
+ everything else, while `assets/` and `analysis/` needed them. They import nothing of the analysis, so
1267
+ they moved to `core/build-text/` — what a build writes in its own text, read by every layer above it —
1268
+ and the loop opened. The last edge, `situation/` borrowing three sentences from `config/`, went the
1269
+ same way: those sentences live next to the code that says them.
1270
+
1271
+ **No folder holds more than twenty files.** Past that a folder is scrolled rather than read, so the
1272
+ big ones are split by what their files are about: `core/analysis/` into `graph/`, `screens/`,
1273
+ `sourcemap/` and `views/`; `core/findings/` into the signals read from the bundle (`bundle/`), from the
1274
+ rest of the build folder (`folder/`) and from what somebody hands over (`supplied/`), with their words
1275
+ in `text/`; `cli/` into `read/`, `render/` and `text/`. Four modules sharing a prefix get a folder of
1276
+ that name for the same reason. `tooling/check-folders.mjs` holds both lines, and the exceptions it
1277
+ allows say why.
1278
+
1019
1279
  **Three path aliases, one per layer**, declared in `tsconfig.json`: `@core/*`, `@shared/*` and
1020
1280
  `@state/*`, for imports that would otherwise climb. Siblings and one level up stay relative.
1021
1281
  `features/` has no alias on purpose: inside a screen everything is a sibling, and an alias there would
@@ -1060,10 +1320,11 @@ question none of them answers, and leaves out things several of them do well.
1060
1320
  - **Line-level duplication across chunks** (Bundle Buddy). Loadline works at file and package level.
1061
1321
  Not started on purpose: comparing everything with everything is expensive inside the browser, and
1062
1322
  the typical finding — a copied utility — usually weighs little.
1063
- - **Webpack** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads an esbuild metafile
1064
- or a folder of ES modules, and webpack is neither: it resolves imports at run time through
1065
- `__webpack_require__`, so there is nothing in the shipped file to read. That leaves out Angular 16
1066
- and earlier, Next.js and Create React App.
1323
+ - **Webpack's own detail** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads
1324
+ webpack's `stats.json` as a metafile since 09/10/2026, so its questions — the first load, the screens,
1325
+ what each one adds — are answered for webpack builds too. What it does not read is everything
1326
+ webpack-specific those tools show: module ids, chunk-group internals, the minified size of each
1327
+ module measured in the bundle rather than shared out. Next.js with Turbopack writes no stats file.
1067
1328
 
1068
1329
  ### 7.3 One finding worth keeping
1069
1330