@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
package/README.md CHANGED
@@ -19,8 +19,8 @@ own fonts and works offline.
19
19
 
20
20
  ## Quick start
21
21
 
22
- **In the browser.** Open [`loadline.html`](loadline.html) and drop your build on it. No install, no
23
- 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
24
24
  inside the page.
25
25
 
26
26
  **In the terminal.**
@@ -29,6 +29,7 @@ inside the page.
29
29
  npx @bymaksym/loadline dist/app # the build root: the metafile and browser/ are found
30
30
  npx @bymaksym/loadline dist/app --html loadline.html --open # and the page, with the build already in it
31
31
  npx @bymaksym/loadline dist/app/browser # the build folder on its own
32
+ npx @bymaksym/loadline . # the project: the newest build inside it is found
32
33
  npx @bymaksym/loadline dist/app/browser-stats.json --dist dist/app/browser
33
34
  ```
34
35
 
@@ -48,16 +49,29 @@ ships `loadline.html` next to the command, under `npm root -g`.
48
49
  ## Compatibility
49
50
 
50
51
  Loadline reads ES module output, either from an esbuild metafile or from the compiled folder, whose
51
- chunks carry their own import graph.
52
+ chunks carry their own import graph, and webpack builds from their `stats.json`.
52
53
 
53
- | Build tool | Frameworks | What to pass |
54
- | -------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
55
- | esbuild (metafile) | Angular 17+, plain esbuild | The build root, or the metafile with `--dist` |
56
- | Vite, Rollup, Rolldown | Vue, React, Svelte, Solid, Nuxt, SvelteKit, Astro, React Router 7 | The build folder |
57
- | 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 |
58
61
 
59
62
  Webpack resolves imports at run time through its own loader, so the shipped files contain no graph
60
- 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.
61
75
 
62
76
  A build folder must contain the `index.html` of the build, which names the chunk the application
63
77
  starts at. Source maps in the folder are optional: without them every figure still comes out, but
@@ -106,6 +120,132 @@ Optional inputs widen the report:
106
120
 
107
121
  ## In CI
108
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
+ Or the Action in this repository, which runs the same check and adds the full report to the job
146
+ summary. It runs the Loadline version it was released with, so pinning the Action pins the tool:
147
+
148
+ <!-- x-release-please-start-version -->
149
+
150
+ ```yaml
151
+ - uses: actions/checkout@v7
152
+ - uses: actions/setup-node@v7
153
+ with: { node-version: 22 }
154
+ - run: npm ci && npm run build
155
+ - uses: bymaksym/LoadLine@v1.2.0
156
+ with:
157
+ path: dist/my-app
158
+ args: --max-boot 350kB # anything the command takes
159
+ ```
160
+
161
+ <!-- x-release-please-end -->
162
+
163
+ **GitLab CI** — `.gitlab-ci.yml`:
164
+
165
+ ```yaml
166
+ loadline:
167
+ image: node:22
168
+ rules:
169
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
170
+ script:
171
+ - npm ci && npm run build
172
+ - npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
173
+ ```
174
+
175
+ **Bitbucket Pipelines** — `bitbucket-pipelines.yml`:
176
+
177
+ ```yaml
178
+ image: node:22
179
+ pipelines:
180
+ pull-requests:
181
+ '**':
182
+ - step:
183
+ name: Loadline
184
+ script:
185
+ - npm ci && npm run build
186
+ - npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
187
+ ```
188
+
189
+ **Azure Pipelines** — `azure-pipelines.yml` (the `pr` trigger covers GitHub and Bitbucket
190
+ repositories; in Azure Repos, a branch policy runs it):
191
+
192
+ ```yaml
193
+ trigger: none
194
+ pr:
195
+ - '*'
196
+ pool:
197
+ vmImage: ubuntu-latest
198
+ steps:
199
+ - task: NodeTool@0
200
+ inputs: { versionSpec: '22.x' }
201
+ - script: npm ci && npm run build
202
+ - script: npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
203
+ ```
204
+
205
+ **CircleCI** — `.circleci/config.yml` (it runs on every push; "Only build pull requests" in the
206
+ project settings limits it to pull requests):
207
+
208
+ ```yaml
209
+ version: 2.1
210
+ jobs:
211
+ loadline:
212
+ docker:
213
+ - image: cimg/node:22
214
+ steps:
215
+ - checkout
216
+ - run: npm ci && npm run build
217
+ - run: npx @bymaksym/loadline@1 dist/my-app --format summary --max-boot 350kB
218
+ workflows:
219
+ loadline:
220
+ jobs:
221
+ - loadline
222
+ ```
223
+
224
+ - **Your own install command** if it is not npm: `pnpm install --frozen-lockfile`, `yarn`.
225
+ - **More to fail on**: `--fail-on high` adds the most serious signals; run it once first without
226
+ the flag, so an existing build does not fail on day one for something nobody touched.
227
+ - **Limits in `loadline.json`** instead of flags, and the step becomes
228
+ `npx @bymaksym/loadline@1 dist/my-app --format summary`. See [Configuration](#configuration).
229
+ - **The whole report** — package names, the import chains, the screens by name — needs the build to
230
+ say what is inside each file: `ng build --stats-json` in Angular, `build.sourcemap: true` in Vite.
231
+ Without it the limits still work.
232
+
233
+ **A badge** of the first load, green, amber or red by the same verdict as the report, with the
234
+ change when there is a `--baseline`:
235
+
236
+ ```bash
237
+ npx @bymaksym/loadline@1 dist/my-app --format badge > loadline.svg
238
+ ```
239
+
240
+ Commit it from the pipeline of the main branch and show it in the README with
241
+ `![first load](loadline.svg)`, or attach it to the pull request. It is a plain SVG: nothing fetched,
242
+ no badge service.
243
+
244
+ When you want the comment on every pull request with what it **adds** compared with `main`, use the
245
+ full recipes below.
246
+
247
+ ### Everything it can do
248
+
109
249
  The command prints the same headline, table and signals as the page, and can fail the build.
110
250
 
111
251
  ```bash
@@ -126,8 +266,10 @@ for builds that write no `stats.json`. Write it on every run, passing or failing
126
266
  compares against yesterday rather than against the last green build.
127
267
 
128
268
  Output formats: `text` (default), `summary` for the whole report in a dozen lines, `json`,
129
- `markdown`, `sarif` for GitHub code scanning, and `pr-comment`, which carries an HTML marker so
130
- the next run edits its comment instead of adding another. `--lang en|es` — English unless it is
269
+ `markdown`, `sarif` for GitHub code scanning, `pr-comment`, which carries an HTML marker so
270
+ the next run edits its comment instead of adding another, and `agent` for a coding agent or a
271
+ script: the five actions worth most, each with its file, import chain and saving, as `key=value`
272
+ lines with no prose. `--lang en|es` — English unless it is
131
273
  asked for in Spanish, never read from the machine's locale, which is the same rule the page
132
274
  follows with its language button. `loadline --help` for the full list.
133
275
 
@@ -148,8 +290,8 @@ jobs:
148
290
  weight:
149
291
  runs-on: ubuntu-latest
150
292
  steps:
151
- - uses: actions/checkout@v4
152
- - uses: actions/setup-node@v4
293
+ - uses: actions/checkout@v7
294
+ - uses: actions/setup-node@v7
153
295
  with: { node-version: 22 }
154
296
  - run: npm ci && npm run build
155
297
 
@@ -162,7 +304,7 @@ jobs:
162
304
 
163
305
  - run: |
164
306
  baseline=$([ -f base/loadline-baseline.json ] && echo "--baseline base/loadline-baseline.json")
165
- npx @bymaksym/loadline dist/app/browser $baseline --export loadline-baseline.json --format pr-comment > comment.md
307
+ npx @bymaksym/loadline@1 dist/app/browser $baseline --export loadline-baseline.json --format pr-comment > comment.md
166
308
 
167
309
  - if: github.event_name == 'pull_request'
168
310
  run: gh pr comment "$NUMBER" --body-file comment.md --edit-last --create-if-none
@@ -170,59 +312,103 @@ jobs:
170
312
 
171
313
  # On main, the snapshot becomes the baseline of every pull request opened after it.
172
314
  - if: github.event_name == 'push'
173
- uses: actions/upload-artifact@v4
315
+ uses: actions/upload-artifact@v7
174
316
  with: { name: loadline-baseline, path: loadline-baseline.json }
175
317
 
176
- - run: npx @bymaksym/loadline dist/app/browser --format sarif > loadline.sarif
177
- - uses: github/codeql-action/upload-sarif@v3
318
+ - run: npx @bymaksym/loadline@1 dist/app/browser --format sarif > loadline.sarif
319
+ - uses: github/codeql-action/upload-sarif@v4
178
320
  with: { sarif_file: loadline.sarif }
179
321
  ```
180
322
 
181
323
  To make the pull request fail on growth rather than only report it, add one more step after the
182
324
  comment, so the comment is posted whatever the verdict:
183
- `npx @bymaksym/loadline dist/app/browser $baseline --max-growth 20kB` (or `--max-growth-pct 5`).
184
- With a baseline it judges what this pull request added, not the size of the whole application.
325
+ `[ -z "$baseline" ] || npx @bymaksym/loadline@1 dist/app/browser $baseline --max-growth 20kB` (or
326
+ `--max-growth-pct 5`). It judges what this pull request added, not the size of the whole
327
+ application — and it needs a baseline, which the first run on `main` does not have yet.
328
+
329
+ The recipes pin the major version (`@1`): a new major can move a threshold, and a pipeline should
330
+ change its verdict because the code changed, not because a tool updated overnight. In a job log,
331
+ `--format summary` prints a dozen lines instead of the whole report.
332
+
333
+ ### GitLab CI
334
+
335
+ The same idea: the default branch keeps its snapshot as an artifact, and each merge request
336
+ downloads it, compares, and keeps one note up to date. Posting the note needs a project access
337
+ token with the `api` scope, saved as a masked CI/CD variable called `LOADLINE_TOKEN` — the job's own
338
+ token can read artifacts but cannot write notes. Without the variable the job still runs and fails
339
+ on the gates; it only does not comment.
340
+
341
+ ```yaml
342
+ # .gitlab-ci.yml
343
+ loadline:
344
+ image: node:22
345
+ rules:
346
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
347
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
348
+ script:
349
+ - npm ci && npm run build
350
+ # The snapshot the default branch left on its last successful run of this job.
351
+ - >
352
+ curl --fail --silent --location --header "JOB-TOKEN: $CI_JOB_TOKEN" --output base.json
353
+ "$CI_API_V4_URL/projects/$CI_PROJECT_ID/jobs/artifacts/$CI_DEFAULT_BRANCH/raw/loadline-baseline.json?job=loadline"
354
+ || rm -f base.json
355
+ - baseline=$([ -f base.json ] && echo "--baseline base.json")
356
+ - npx @bymaksym/loadline@1 dist/app/browser $baseline --export loadline-baseline.json --format pr-comment > comment.md
357
+ # One note per merge request, edited on every push: found by the marker the comment carries.
358
+ - |
359
+ if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ] && [ -n "$LOADLINE_TOKEN" ]; then
360
+ notes="$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
361
+ id=$(curl --silent --header "PRIVATE-TOKEN: $LOADLINE_TOKEN" "$notes?per_page=100" \
362
+ | 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):"")})')
363
+ if [ -n "$id" ]; then method=PUT; url="$notes/$id"; else method=POST; url="$notes"; fi
364
+ curl --silent --request "$method" --header "PRIVATE-TOKEN: $LOADLINE_TOKEN" --data-urlencode "body@comment.md" "$url" > /dev/null
365
+ fi
366
+ # Fails the merge request on growth, after the note is posted. Growth needs a baseline,
367
+ # which the very first run of the default branch does not have yet.
368
+ - if [ -n "$baseline" ]; then npx @bymaksym/loadline@1 dist/app/browser $baseline --max-growth 20kB --format summary; fi
369
+ artifacts:
370
+ paths: [loadline-baseline.json]
371
+ expire_in: 30 days
372
+ ```
185
373
 
186
374
  ## Configuration
187
375
 
188
- A `loadline.json` in the working directory is read without any flag; `--config <file>` points at
189
- another one. Flags on the command line win over the file. The page writes this file, and the
190
- command reads it, so thresholds edited in the browser are the ones CI judges by.
376
+ Everything is optional. A `loadline.json` next to your code sets the thresholds, makes CI fail, and
377
+ records the signals the team has decided to live with. The page and the command both read it, so
378
+ they judge the build the same way.
191
379
 
192
380
  ```json
193
381
  {
382
+ "$schema": "https://unpkg.com/@bymaksym/loadline/loadline.schema.json",
194
383
  "tool": "loadline",
195
384
  "version": 1,
196
- "criteria": { "bootOk": 174080 },
197
- "gates": { "maxBoot": "350kB", "failOn": "high", "failOnNewPackage": true },
198
- "packages": ["@angular/core", "@angular/common", "rxjs"],
199
- "accepted": [
200
- {
201
- "kind": "dupes",
202
- "key": "date-fns",
203
- "why": "two versions until the calendar library releases 4.x",
204
- "who": "@maks",
205
- "until": "2026-12-01",
206
- "bytes": 14336
207
- }
208
- ]
385
+ "gates": { "maxBoot": "350kB", "screens": { "map": "900kB" }, "failOn": "high" },
386
+ "accepted": [{ "kind": "dupes", "key": "date-fns", "why": "until 4.x", "until": "2026-12-01" }]
209
387
  }
210
388
  ```
211
389
 
212
- `accepted` records a signal the team has decided to live with: it names a reason, a person and an
213
- expiry. The signal comes back when the date passes, or when the figure it was agreed at has grown.
214
- Everything accepted is listed under the report, so no signal disappears silently.
390
+ With the `$schema` line your editor completes every key, explains it on hover and underlines a typo.
391
+ Anything the command cannot use in the file is printed, never ignored. Flags win over the file.
215
392
 
216
- `--fail-on-new-package` catches the way bundles actually grow — one `npm install` at a time. With a
217
- `packages` list it fails on anything not on it; with a `--baseline` and no list, on anything that
218
- was not in the bootstrap last time.
393
+ | I want to… | Read |
394
+ | ------------------------------------------------ | ------------------------------------------------------------------------------- |
395
+ | Fail CI on size, growth, new packages, signals | [Configuring Loadline](docs/CONFIG.md#fail-the-build-on-size) |
396
+ | Give one heavy screen its own limit | [One limit per screen](docs/CONFIG.md#one-limit-per-screen) |
397
+ | Change what counts as good or bad | [Thresholds](docs/CONFIG.md#change-the-thresholds) |
398
+ | Live with a signal without hiding it forever | [Accept a signal](docs/CONFIG.md#accept-a-signal) |
399
+ | Never ship a package, or never in the first load | [Forbid something](docs/CONFIG.md#forbid-something) |
400
+ | Share one file between many repositories | [Share the configuration](docs/CONFIG.md#share-the-configuration) |
401
+ | Fix a build read wrong: entry, screens, page | [When it reads your build wrong](docs/CONFIG.md#when-it-reads-your-build-wrong) |
402
+ | See every key and its recommended value | [Reference](docs/CONFIG-REFERENCE.md) |
219
403
 
220
404
  ## Documentation
221
405
 
406
+ - [Configuring Loadline](docs/CONFIG.md) — `loadline.json` by task, with examples, and the
407
+ [reference](docs/CONFIG-REFERENCE.md) of every key.
222
408
  - [How it works](docs/HOW-IT-WORKS.md) — the algorithm, what each signal means, the limits of the
223
409
  analysis, and [how the other tools compare](docs/HOW-IT-WORKS.md#7-what-the-other-tools-do).
224
- - [CONTRIBUTING.md](CONTRIBUTING.md) — what CI checks before you spend time on a change.
225
- - [SECURITY.md](SECURITY.md) — report vulnerabilities privately, never as an issue.
410
+ - [CONTRIBUTING.md](.github/CONTRIBUTING.md) — what CI checks before you spend time on a change.
411
+ - [SECURITY.md](.github/SECURITY.md) — report vulnerabilities privately, never as an issue.
226
412
  - [CHANGELOG.md](CHANGELOG.md) — what changed in each version.
227
413
 
228
414
  When opening an issue, the **Copy diagnostics** button at the end of the report writes about thirty