@bymaksym/loadline 0.1.0 → 1.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 (115) hide show
  1. package/README.md +272 -45
  2. package/dist/cli/cli/args.js +97 -116
  3. package/dist/cli/cli/gates.js +80 -14
  4. package/dist/cli/cli/main.js +275 -31
  5. package/dist/cli/cli/memory.js +114 -0
  6. package/dist/cli/cli/read/declared.js +52 -0
  7. package/dist/cli/cli/read/locate.js +214 -0
  8. package/dist/cli/cli/{read-build.js → read/read-build.js} +156 -87
  9. package/dist/cli/cli/read/read-config.js +120 -0
  10. package/dist/cli/cli/render/html-report.js +111 -0
  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} +26 -10
  15. package/dist/cli/cli/{render-markdown.js → render/render-markdown.js} +6 -6
  16. package/dist/cli/cli/{render-pr.js → render/render-pr.js} +37 -15
  17. package/dist/cli/cli/{render-sarif.js → render/render-sarif.js} +11 -6
  18. package/dist/cli/cli/{render-text.js → render/render-text.js} +169 -127
  19. package/dist/cli/cli/render/terminal.js +55 -0
  20. package/dist/cli/cli/report.js +76 -29
  21. package/dist/cli/cli/self-check.js +19 -23
  22. package/dist/cli/cli/since-last.js +45 -0
  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 +68 -24
  27. package/dist/cli/src/app/core/analysis/{barrels.js → graph/barrels.js} +10 -3
  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 +21 -7
  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} +87 -11
  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} +13 -7
  40. package/dist/cli/src/app/core/analysis/tool.js +83 -0
  41. package/dist/cli/src/app/core/assets/assets.js +137 -16
  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 +234 -29
  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 +123 -45
  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 +141 -23
  53. package/dist/cli/src/app/core/deps/pins.js +63 -0
  54. package/dist/cli/src/app/core/export/summary.js +54 -12
  55. package/dist/cli/src/app/core/findings/actions.js +65 -6
  56. package/dist/cli/src/app/core/findings/bundle/boot-single.js +76 -0
  57. package/dist/cli/src/app/core/findings/bundle/dupes.js +68 -0
  58. package/dist/cli/src/app/core/findings/{graph.js → bundle/graph.js} +32 -20
  59. package/dist/cli/src/app/core/findings/{own-in-boot.js → bundle/own-in-boot.js} +9 -5
  60. package/dist/cli/src/app/core/findings/{requests.js → bundle/requests.js} +3 -3
  61. package/dist/cli/src/app/core/findings/{shipped.js → bundle/shipped.js} +30 -18
  62. package/dist/cli/src/app/core/findings/compose.js +6 -1
  63. package/dist/cli/src/app/core/findings/effort.js +4 -0
  64. package/dist/cli/src/app/core/findings/finding.types.js +2 -0
  65. package/dist/cli/src/app/core/findings/findings.js +68 -55
  66. package/dist/cli/src/app/core/findings/{assets.js → folder/assets.js} +65 -16
  67. package/dist/cli/src/app/core/findings/{caching.js → folder/caching.js} +17 -10
  68. package/dist/cli/src/app/core/findings/{page.js → folder/page.js} +6 -2
  69. package/dist/cli/src/app/core/findings/{scan.js → folder/scan.js} +37 -13
  70. package/dist/cli/src/app/core/findings/kind-names.js +163 -0
  71. package/dist/cli/src/app/core/findings/{deps.js → supplied/deps.js} +13 -8
  72. package/dist/cli/src/app/core/findings/supplied/forbidden.js +71 -0
  73. package/dist/cli/src/app/core/findings/{situation.js → supplied/situation.js} +2 -2
  74. package/dist/cli/src/app/core/findings/text/causes.js +39 -0
  75. package/dist/cli/src/app/core/findings/text/finding-html.js +33 -0
  76. package/dist/cli/src/app/core/findings/{finding-text.js → text/finding-text.js} +307 -103
  77. package/dist/cli/src/app/core/findings/text/tool-advice.js +97 -0
  78. package/dist/cli/src/app/core/format/format.utils.js +172 -18
  79. package/dist/cli/src/app/core/format/ownership.js +93 -0
  80. package/dist/cli/src/app/core/i18n/en.js +180 -61
  81. package/dist/cli/src/app/core/i18n/es.js +192 -68
  82. package/dist/cli/src/app/core/intake/bundle-graph.js +285 -46
  83. package/dist/cli/src/app/core/intake/dist-files.js +87 -16
  84. package/dist/cli/src/app/core/intake/embedded.js +56 -0
  85. package/dist/cli/src/app/core/intake/unreached.js +139 -0
  86. package/dist/cli/src/app/core/intake/webpack-modules.js +185 -0
  87. package/dist/cli/src/app/core/intake/webpack-stats.js +298 -0
  88. package/dist/cli/src/app/core/project/budget-advice.js +14 -10
  89. package/dist/cli/src/app/core/project/project-context.js +89 -19
  90. package/dist/cli/src/app/core/project/project-name.js +36 -0
  91. package/dist/cli/src/app/core/scan/scan.js +116 -39
  92. package/dist/cli/src/app/core/scan/secrets.js +0 -0
  93. package/dist/cli/src/app/core/situation/situation-text.js +23 -0
  94. package/dist/cli/src/app/core/situation/situation.js +9 -8
  95. package/dist/cli/src/app/core/timing/timing.js +5 -2
  96. package/dist/cli/src/app/core/whatif/defer.js +29 -4
  97. package/dist/cli/src/app/core/whatif/source-importers.js +58 -0
  98. package/dist/cli/src/app/core/whatif/why.js +102 -0
  99. package/dist/cli/src/app/state/report-messages.utils.js +1 -4
  100. package/docs/CONFIG-REFERENCE.md +230 -0
  101. package/docs/CONFIG.md +511 -0
  102. package/docs/HOW-IT-WORKS.md +286 -25
  103. package/loadline.html +26 -24
  104. package/loadline.schema.json +1209 -0
  105. package/package.json +71 -35
  106. package/dist/cli/cli/text.js +0 -180
  107. package/dist/cli/src/app/core/findings/finding-html.js +0 -13
  108. /package/dist/cli/cli/{read-build.types.js → read/read-build.types.js} +0 -0
  109. /package/dist/cli/cli/{render-json.types.js → render/render-json.types.js} +0 -0
  110. /package/dist/cli/cli/{text.types.js → text/text.types.js} +0 -0
  111. /package/dist/cli/src/app/core/analysis/{exclusive.js → graph/exclusive.js} +0 -0
  112. /package/dist/cli/src/app/core/analysis/{insights.types.js → graph/insights.types.js} +0 -0
  113. /package/dist/cli/src/app/core/analysis/{module-graph.js → graph/module-graph.js} +0 -0
  114. /package/dist/cli/src/app/core/analysis/{sourcemap.types.js → sourcemap/sourcemap.types.js} +0 -0
  115. /package/dist/cli/src/app/core/findings/{finding-plain.js → text/finding-plain.js} +0 -0
package/README.md CHANGED
@@ -1,4 +1,6 @@
1
- # Loadline
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/bymaksym/LoadLine/main/.github/banner.png?v=2" alt="Loadline — weight per screen" width="100%">
3
+ </p>
2
4
 
3
5
  > Weight per screen: what someone opening a screen of your app actually downloads, how much of that
4
6
  > everybody else pays for too, and what is worth moving elsewhere.
@@ -17,17 +19,29 @@ own fonts and works offline.
17
19
 
18
20
  ## Quick start
19
21
 
20
- **In the browser.** Open [`loadline.html`](loadline.html) and drop your build on it. No install, no
21
- server, no build step. Press **See an example** to see the report on a synthetic build that ships
22
+ **In the browser.** Open [`loadline.html`](loadline.html) and drop your build on it, or choose it with
23
+ **Choose build folder**. No install, no server, no build step. Press **See an example** to see the report on a synthetic build that ships
22
24
  inside the page.
23
25
 
24
26
  **In the terminal.**
25
27
 
26
28
  ```bash
29
+ npx @bymaksym/loadline dist/app # the build root: the metafile and browser/ are found
30
+ npx @bymaksym/loadline dist/app --html loadline.html --open # and the page, with the build already in it
27
31
  npx @bymaksym/loadline dist/app/browser # the build folder on its own
28
- npx @bymaksym/loadline dist/app/stats.json --dist dist/app/browser
32
+ npx @bymaksym/loadline . # the project: the newest build inside it is found
33
+ npx @bymaksym/loadline dist/app/browser-stats.json --dist dist/app/browser
29
34
  ```
30
35
 
36
+ Pointed at the root of an Angular build, the command finds `browser-stats.json` (Angular 22.2) or
37
+ `stats.json` (up to 22.1) and the `browser/` folder next to it. `--html` writes the same page as
38
+ `loadline.html` with the files the command read inside it, so a script can produce a report somebody
39
+ opens with a double click — treemap, search and every chunk included, nothing to drag in.
40
+
41
+ Each run is remembered in `node_modules/.cache/loadline`, and the next run of the same build says
42
+ what moved — `since the last run: bootstrap 156 kB → 129 kB (−27 kB)` — without a `--baseline`. It is
43
+ a line and a column, never a gate; `--no-cache` turns it off.
44
+
31
45
  Zero runtime dependencies, no install script, Node 20.19 or newer. `npm i -g @bymaksym/loadline` installs it;
32
46
  `pnpm`, `yarn`, `bun` and `deno` all work, as do `pnpm dlx`, `yarn dlx` and `bunx`. The package also
33
47
  ships `loadline.html` next to the command, under `npm root -g`.
@@ -35,16 +49,29 @@ ships `loadline.html` next to the command, under `npm root -g`.
35
49
  ## Compatibility
36
50
 
37
51
  Loadline reads ES module output, either from an esbuild metafile or from the compiled folder, whose
38
- chunks carry their own import graph.
52
+ chunks carry their own import graph, and webpack builds from their `stats.json`.
39
53
 
40
- | Build tool | Frameworks | What to pass |
41
- | -------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
42
- | esbuild (metafile) | Angular 17+, plain esbuild | `stats.json`, ideally with `--dist` |
43
- | Vite, Rollup, Rolldown | Vue, React, Svelte, Solid, Nuxt, SvelteKit, Astro, React Router 7 | The build folder |
44
- | webpack, Turbopack, Rspack | Angular ≤ 16, Next.js, Create React App | Not supported — see [Statoscope](https://github.com/statoscope/statoscope) |
54
+ | Build tool | Frameworks | What to pass |
55
+ | ---------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
56
+ | esbuild (metafile) | Angular 17+, plain esbuild | The build root, or the metafile with `--dist` |
57
+ | Vite, Rollup, Rolldown | Vue, React, Svelte, Solid, Nuxt, SvelteKit, Astro, React Router 7 | The build folder |
58
+ | Older formats: AMD, SystemJS, `nomodule` | Sapper, Stencil, Polymer, Ember, RequireJS, Vite's legacy plugin | The build folder, or the project root: the build is found inside it |
59
+ | webpack, Rspack | Angular ≤ 16, Create React App, Vue CLI, Gatsby, Nuxt 2 | The `stats.json` with `--dist`, or the build folder when it is inside it |
60
+ | Turbopack | Next.js | Not supported: it writes no stats file |
45
61
 
46
62
  Webpack resolves imports at run time through its own loader, so the shipped files contain no graph
47
- to read. Builds in that format are named for what they are rather than analysed.
63
+ to read; its `stats.json` does, and Loadline reads it as a metafile. How to get one:
64
+
65
+ | Tool | Command | Where it lands |
66
+ | ---------------- | ------------------------------------- | -------------------------------- |
67
+ | Angular 8 to 16 | `ng build --stats-json` | `dist/<app>/stats(-es2015).json` |
68
+ | Create React App | `react-scripts build --stats` | `build/bundle-stats.json` |
69
+ | Vue CLI | `vue-cli-service build --report-json` | `dist/report.json` |
70
+ | plain webpack | `webpack --json > stats.json` | wherever it is redirected |
71
+
72
+ Inside the build folder, `loadline <folder>` finds it; anywhere else, pass it with `--dist <folder>`.
73
+ A module's size in that file is its source before minification, so what each file weighs inside a
74
+ chunk is shared out in proportion until the folder's source maps measure it.
48
75
 
49
76
  A build folder must contain the `index.html` of the build, which names the chunk the application
50
77
  starts at. Source maps in the folder are optional: without them every figure still comes out, but
@@ -56,6 +83,10 @@ To get a metafile out of Angular:
56
83
  ng build --configuration <the-one-your-pipeline-deploys> --stats-json
57
84
  ```
58
85
 
86
+ Angular 22.2 and later write it as `dist/<app>/browser-stats.json`; earlier versions as
87
+ `dist/<app>/stats.json`.
88
+ Either way, `loadline dist/<app>` finds it.
89
+
59
90
  ## What you get
60
91
 
61
92
  - **One headline number** — what is downloaded before anything appears.
@@ -67,6 +98,10 @@ ng build --configuration <the-one-your-pipeline-deploys> --stats-json
67
98
  - **Signals with a name and a fix** — shared code labelled as deferred, bootstrap pulled in for a
68
99
  lazy screen, duplicate package versions, CommonJS packages the bundler cannot tree-shake, large
69
100
  data files travelling in the bootstrap, and more.
101
+ - **A map of the bundle** — one rectangle per chunk, sized by what it weighs in the report's unit,
102
+ with what fills it drawn inside, by package and by folder of yours. Click to open a chunk, as in
103
+ `esbuild-visualizer`, with the difference that the area between chunks is what travels and the
104
+ area inside one is each part's raw share, because a compressed share of one module does not exist.
70
105
  - **Search by package or file** — which chunks it is in, what it weighs in each, which screens pay
71
106
  for it, and the chain of imports that brings it in.
72
107
  - **Provenance on every figure** — each threshold says whether it is external, derived or a
@@ -79,11 +114,120 @@ Optional inputs widen the report:
79
114
  | The build folder (`--dist`) | Gzip and brotli figures, per-file weights, first-load round trips |
80
115
  | A previous build or export (`--baseline`) | Per-screen deltas, and what a returning visitor re-downloads |
81
116
  | `angular.json`, `package.json`, the CI file | Whether your size budgets sit in the configuration the pipeline builds |
117
+ | The lock file (`--lock`) | Who brings each package in, and whether a duplicate is pinned beyond reach |
82
118
  | A browser measurement, pasted into Measured | What is actually served: compression, 304s, third parties, real round trips |
83
119
  | Several apps at once | What microfrontends ship twice, and what a shared package would save |
84
120
 
85
121
  ## In CI
86
122
 
123
+ ### The minimum
124
+
125
+ Enough for most projects: every pull request is built and fails if the first load is over the
126
+ limit. Copy one, change `dist/my-app` to your build folder (`outputPath` in `angular.json`, `outDir`
127
+ in Vite), and that is all.
128
+
129
+ **GitHub Actions** — `.github/workflows/loadline.yml`:
130
+
131
+ ```yaml
132
+ name: Loadline
133
+ on: pull_request
134
+ jobs:
135
+ loadline:
136
+ runs-on: ubuntu-latest
137
+ steps:
138
+ - uses: actions/checkout@v7
139
+ - uses: actions/setup-node@v7
140
+ with: { node-version: 22 }
141
+ - run: npm ci && npm run build
142
+ - run: npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
143
+ ```
144
+
145
+ **GitLab CI** — `.gitlab-ci.yml`:
146
+
147
+ ```yaml
148
+ loadline:
149
+ image: node:22
150
+ rules:
151
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
152
+ script:
153
+ - npm ci && npm run build
154
+ - npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
155
+ ```
156
+
157
+ **Bitbucket Pipelines** — `bitbucket-pipelines.yml`:
158
+
159
+ ```yaml
160
+ image: node:22
161
+ pipelines:
162
+ pull-requests:
163
+ '**':
164
+ - step:
165
+ name: Loadline
166
+ script:
167
+ - npm ci && npm run build
168
+ - npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
169
+ ```
170
+
171
+ **Azure Pipelines** — `azure-pipelines.yml` (the `pr` trigger covers GitHub and Bitbucket
172
+ repositories; in Azure Repos, a branch policy runs it):
173
+
174
+ ```yaml
175
+ trigger: none
176
+ pr:
177
+ - '*'
178
+ pool:
179
+ vmImage: ubuntu-latest
180
+ steps:
181
+ - task: NodeTool@0
182
+ inputs: { versionSpec: '22.x' }
183
+ - script: npm ci && npm run build
184
+ - script: npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
185
+ ```
186
+
187
+ **CircleCI** — `.circleci/config.yml` (it runs on every push; "Only build pull requests" in the
188
+ project settings limits it to pull requests):
189
+
190
+ ```yaml
191
+ version: 2.1
192
+ jobs:
193
+ loadline:
194
+ docker:
195
+ - image: cimg/node:22
196
+ steps:
197
+ - checkout
198
+ - run: npm ci && npm run build
199
+ - run: npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
200
+ workflows:
201
+ loadline:
202
+ jobs:
203
+ - loadline
204
+ ```
205
+
206
+ - **Your own install command** if it is not npm: `pnpm install --frozen-lockfile`, `yarn`.
207
+ - **More to fail on**: `--fail-on high` adds the most serious signals; run it once first without
208
+ the flag, so an existing build does not fail on day one for something nobody touched.
209
+ - **Limits in `loadline.json`** instead of flags, and the step becomes
210
+ `npx @bymaksym/loadline@1 dist/my-app --format summary`. See [Configuration](#configuration).
211
+ - **The whole report** — package names, the import chains, the screens by name — needs the build to
212
+ say what is inside each file: `ng build --stats-json` in Angular, `build.sourcemap: true` in Vite.
213
+ Without it the limits still work.
214
+
215
+ **A badge** of the first load, green, amber or red by the same verdict as the report, with the
216
+ change when there is a `--baseline`:
217
+
218
+ ```bash
219
+ npx @bymaksym/loadline@1 dist/my-app --format badge > loadline.svg
220
+ ```
221
+
222
+ Commit it from the pipeline of the main branch and show it in the README with
223
+ `![first load](loadline.svg)`, or attach it to the pull request. It is a plain SVG: nothing fetched,
224
+ no badge service.
225
+
226
+ When you want the comment on every pull request with what it **adds** compared with `main`, use the
227
+ full recipes below.
228
+
229
+ ### Everything it can do
230
+
87
231
  The command prints the same headline, table and signals as the page, and can fail the build.
88
232
 
89
233
  ```bash
@@ -104,78 +248,161 @@ for builds that write no `stats.json`. Write it on every run, passing or failing
104
248
  compares against yesterday rather than against the last green build.
105
249
 
106
250
  Output formats: `text` (default), `summary` for the whole report in a dozen lines, `json`,
107
- `markdown`, `sarif` for GitHub code scanning, and `pr-comment`, which carries an HTML marker so
108
- the next run edits its comment instead of adding another. `--lang en|es` — English unless it is
251
+ `markdown`, `sarif` for GitHub code scanning, `pr-comment`, which carries an HTML marker so
252
+ the next run edits its comment instead of adding another, and `agent` for a coding agent or a
253
+ script: the five actions worth most, each with its file, import chain and saving, as `key=value`
254
+ lines with no prose. `--lang en|es` — English unless it is
109
255
  asked for in Spanish, never read from the machine's locale, which is the same rule the page
110
256
  follows with its language button. `loadline --help` for the full list.
111
257
 
258
+ The comment is worth most when it says what the pull request **adds**, and that needs the figures
259
+ of `main` to compare against. A pipeline keeps nothing between runs — the cache in
260
+ `node_modules/.cache` is gone with the runner — so `main` leaves its snapshot as an artifact on every
261
+ push, and each pull request downloads the latest one and passes it as `--baseline`. Until `main` has
262
+ run once there is nothing to download, and the comment shows plain figures instead of differences.
263
+
112
264
  ```yaml
113
265
  # .github/workflows/loadline.yml
114
266
  name: Loadline
115
- on: pull_request
116
- permissions: { contents: read, pull-requests: write, security-events: write }
267
+ on:
268
+ push: { branches: [main] }
269
+ pull_request:
270
+ permissions: { contents: read, actions: read, pull-requests: write, security-events: write }
117
271
  jobs:
118
272
  weight:
119
273
  runs-on: ubuntu-latest
120
274
  steps:
121
- - uses: actions/checkout@v4
122
- - uses: actions/setup-node@v4
275
+ - uses: actions/checkout@v7
276
+ - uses: actions/setup-node@v7
123
277
  with: { node-version: 22 }
124
278
  - run: npm ci && npm run build
125
- - run: npx @bymaksym/loadline dist/app/browser --format pr-comment > comment.md
126
- - run: gh pr comment "$NUMBER" --body-file comment.md --edit-last --create-if-none
279
+
280
+ # The snapshot main left on its last green run: what this pull request is compared to.
281
+ - if: github.event_name == 'pull_request'
282
+ run: |
283
+ run=$(gh run list --branch main --workflow loadline.yml --status success --limit 1 --json databaseId --jq '.[0].databaseId')
284
+ if [ -n "$run" ]; then gh run download "$run" --name loadline-baseline --dir base; fi
285
+ env: { GH_TOKEN: '${{ github.token }}' }
286
+
287
+ - run: |
288
+ baseline=$([ -f base/loadline-baseline.json ] && echo "--baseline base/loadline-baseline.json")
289
+ npx @bymaksym/loadline@1 dist/app/browser $baseline --export loadline-baseline.json --format pr-comment > comment.md
290
+
291
+ - if: github.event_name == 'pull_request'
292
+ run: gh pr comment "$NUMBER" --body-file comment.md --edit-last --create-if-none
127
293
  env: { GH_TOKEN: '${{ github.token }}', NUMBER: '${{ github.event.number }}' }
128
- - run: npx @bymaksym/loadline dist/app/browser --format sarif > loadline.sarif
129
- - uses: github/codeql-action/upload-sarif@v3
294
+
295
+ # On main, the snapshot becomes the baseline of every pull request opened after it.
296
+ - if: github.event_name == 'push'
297
+ uses: actions/upload-artifact@v7
298
+ with: { name: loadline-baseline, path: loadline-baseline.json }
299
+
300
+ - run: npx @bymaksym/loadline@1 dist/app/browser --format sarif > loadline.sarif
301
+ - uses: github/codeql-action/upload-sarif@v4
130
302
  with: { sarif_file: loadline.sarif }
131
303
  ```
132
304
 
305
+ To make the pull request fail on growth rather than only report it, add one more step after the
306
+ comment, so the comment is posted whatever the verdict:
307
+ `[ -z "$baseline" ] || npx @bymaksym/loadline@1 dist/app/browser $baseline --max-growth 20kB` (or
308
+ `--max-growth-pct 5`). It judges what this pull request added, not the size of the whole
309
+ application — and it needs a baseline, which the first run on `main` does not have yet.
310
+
311
+ The recipes pin the major version (`@1`): a new major can move a threshold, and a pipeline should
312
+ change its verdict because the code changed, not because a tool updated overnight. In a job log,
313
+ `--format summary` prints a dozen lines instead of the whole report.
314
+
315
+ ### GitLab CI
316
+
317
+ The same idea: the default branch keeps its snapshot as an artifact, and each merge request
318
+ downloads it, compares, and keeps one note up to date. Posting the note needs a project access
319
+ token with the `api` scope, saved as a masked CI/CD variable called `LOADLINE_TOKEN` — the job's own
320
+ token can read artifacts but cannot write notes. Without the variable the job still runs and fails
321
+ on the gates; it only does not comment.
322
+
323
+ ```yaml
324
+ # .gitlab-ci.yml
325
+ loadline:
326
+ image: node:22
327
+ rules:
328
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
329
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
330
+ script:
331
+ - npm ci && npm run build
332
+ # The snapshot the default branch left on its last successful run of this job.
333
+ - >
334
+ curl --fail --silent --location --header "JOB-TOKEN: $CI_JOB_TOKEN" --output base.json
335
+ "$CI_API_V4_URL/projects/$CI_PROJECT_ID/jobs/artifacts/$CI_DEFAULT_BRANCH/raw/loadline-baseline.json?job=loadline"
336
+ || rm -f base.json
337
+ - baseline=$([ -f base.json ] && echo "--baseline base.json")
338
+ - npx @bymaksym/loadline@1 dist/app/browser $baseline --export loadline-baseline.json --format pr-comment > comment.md
339
+ # One note per merge request, edited on every push: found by the marker the comment carries.
340
+ - |
341
+ if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ] && [ -n "$LOADLINE_TOKEN" ]; then
342
+ notes="$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
343
+ id=$(curl --silent --header "PRIVATE-TOKEN: $LOADLINE_TOKEN" "$notes?per_page=100" \
344
+ | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const n=JSON.parse(s).find(n=>n.body.includes("<!-- loadline-report -->"));process.stdout.write(n?String(n.id):"")})')
345
+ if [ -n "$id" ]; then method=PUT; url="$notes/$id"; else method=POST; url="$notes"; fi
346
+ curl --silent --request "$method" --header "PRIVATE-TOKEN: $LOADLINE_TOKEN" --data-urlencode "body@comment.md" "$url" > /dev/null
347
+ fi
348
+ # Fails the merge request on growth, after the note is posted. Growth needs a baseline,
349
+ # which the very first run of the default branch does not have yet.
350
+ - if [ -n "$baseline" ]; then npx @bymaksym/loadline@1 dist/app/browser $baseline --max-growth 20kB --format summary; fi
351
+ artifacts:
352
+ paths: [loadline-baseline.json]
353
+ expire_in: 30 days
354
+ ```
355
+
133
356
  ## Configuration
134
357
 
135
- A `loadline.json` in the working directory is read without any flag; `--config <file>` points at
136
- another one. Flags on the command line win over the file. The page writes this file, and the
137
- command reads it, so thresholds edited in the browser are the ones CI judges by.
358
+ Everything is optional. A `loadline.json` next to your code sets the thresholds, makes CI fail, and
359
+ records the signals the team has decided to live with. The page and the command both read it, so
360
+ they judge the build the same way.
138
361
 
139
362
  ```json
140
363
  {
364
+ "$schema": "https://unpkg.com/@bymaksym/loadline/loadline.schema.json",
141
365
  "tool": "loadline",
142
366
  "version": 1,
143
- "criteria": { "bootOk": 174080 },
144
- "gates": { "maxBoot": "350kB", "failOn": "high", "failOnNewPackage": true },
145
- "packages": ["@angular/core", "@angular/common", "rxjs"],
146
- "accepted": [
147
- {
148
- "kind": "dupes",
149
- "key": "date-fns",
150
- "why": "two versions until the calendar library releases 4.x",
151
- "who": "@maks",
152
- "until": "2026-12-01",
153
- "bytes": 14336
154
- }
155
- ]
367
+ "gates": { "maxBoot": "350kB", "screens": { "map": "900kB" }, "failOn": "high" },
368
+ "accepted": [{ "kind": "dupes", "key": "date-fns", "why": "until 4.x", "until": "2026-12-01" }]
156
369
  }
157
370
  ```
158
371
 
159
- `accepted` records a signal the team has decided to live with: it names a reason, a person and an
160
- expiry. The signal comes back when the date passes, or when the figure it was agreed at has grown.
161
- Everything accepted is listed under the report, so no signal disappears silently.
372
+ With the `$schema` line your editor completes every key, explains it on hover and underlines a typo.
373
+ Anything the command cannot use in the file is printed, never ignored. Flags win over the file.
162
374
 
163
- `--fail-on-new-package` catches the way bundles actually grow — one `npm install` at a time. With a
164
- `packages` list it fails on anything not on it; with a `--baseline` and no list, on anything that
165
- was not in the bootstrap last time.
375
+ | I want to… | Read |
376
+ | ------------------------------------------------ | ------------------------------------------------------------------------------- |
377
+ | Fail CI on size, growth, new packages, signals | [Configuring Loadline](docs/CONFIG.md#fail-the-build-on-size) |
378
+ | Give one heavy screen its own limit | [One limit per screen](docs/CONFIG.md#one-limit-per-screen) |
379
+ | Change what counts as good or bad | [Thresholds](docs/CONFIG.md#change-the-thresholds) |
380
+ | Live with a signal without hiding it forever | [Accept a signal](docs/CONFIG.md#accept-a-signal) |
381
+ | Never ship a package, or never in the first load | [Forbid something](docs/CONFIG.md#forbid-something) |
382
+ | Share one file between many repositories | [Share the configuration](docs/CONFIG.md#share-the-configuration) |
383
+ | Fix a build read wrong: entry, screens, page | [When it reads your build wrong](docs/CONFIG.md#when-it-reads-your-build-wrong) |
384
+ | See every key and its recommended value | [Reference](docs/CONFIG-REFERENCE.md) |
166
385
 
167
386
  ## Documentation
168
387
 
388
+ - [Configuring Loadline](docs/CONFIG.md) — `loadline.json` by task, with examples, and the
389
+ [reference](docs/CONFIG-REFERENCE.md) of every key.
169
390
  - [How it works](docs/HOW-IT-WORKS.md) — the algorithm, what each signal means, the limits of the
170
391
  analysis, and [how the other tools compare](docs/HOW-IT-WORKS.md#7-what-the-other-tools-do).
171
- - [CONTRIBUTING.md](CONTRIBUTING.md) — what CI checks before you spend time on a change.
172
- - [SECURITY.md](SECURITY.md) — report vulnerabilities privately, never as an issue.
392
+ - [CONTRIBUTING.md](.github/CONTRIBUTING.md) — what CI checks before you spend time on a change.
393
+ - [SECURITY.md](.github/SECURITY.md) — report vulnerabilities privately, never as an issue.
173
394
  - [CHANGELOG.md](CHANGELOG.md) — what changed in each version.
174
395
 
175
396
  When opening an issue, the **Copy diagnostics** button at the end of the report writes about thirty
176
397
  lines describing the build and what Loadline decided about it. Package names are real; paths in your
177
398
  own code are replaced by stable hashes, so it can be pasted in public.
178
399
 
400
+ ## Community
401
+
402
+ [Discord — ByMaksymDev Labs](https://discord.gg/ctDJjFF9yT), where Loadline has its own
403
+ channel. Bugs and feature requests are better off as issues here, where they can be found
404
+ again; the chat is for everything that is a conversation.
405
+
179
406
  ## License
180
407
 
181
408
  [MIT](LICENSE). Offered with no commitment of support: issues and pull requests are welcome and may