@bymaksym/loadline 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +182 -0
- package/bin/loadline.js +50 -0
- package/dist/cli/cli/args.js +324 -0
- package/dist/cli/cli/args.types.js +3 -0
- package/dist/cli/cli/gates.js +173 -0
- package/dist/cli/cli/gates.types.js +3 -0
- package/dist/cli/cli/main.js +156 -0
- package/dist/cli/cli/read-build.js +382 -0
- package/dist/cli/cli/read-build.types.js +3 -0
- package/dist/cli/cli/render-json.js +116 -0
- package/dist/cli/cli/render-json.types.js +10 -0
- package/dist/cli/cli/render-markdown.js +30 -0
- package/dist/cli/cli/render-pr.js +76 -0
- package/dist/cli/cli/render-sarif.js +83 -0
- package/dist/cli/cli/render-text.js +388 -0
- package/dist/cli/cli/report.js +196 -0
- package/dist/cli/cli/report.types.js +3 -0
- package/dist/cli/cli/self-check.js +85 -0
- package/dist/cli/cli/text.js +180 -0
- package/dist/cli/cli/text.types.js +10 -0
- package/dist/cli/src/app/core/analysis/analysis.js +661 -0
- package/dist/cli/src/app/core/analysis/analysis.types.js +6 -0
- package/dist/cli/src/app/core/analysis/barrels.js +128 -0
- package/dist/cli/src/app/core/analysis/blast.js +172 -0
- package/dist/cli/src/app/core/analysis/cycles.js +110 -0
- package/dist/cli/src/app/core/analysis/delivery.js +143 -0
- package/dist/cli/src/app/core/analysis/entries.js +217 -0
- package/dist/cli/src/app/core/analysis/exclusive.js +91 -0
- package/dist/cli/src/app/core/analysis/importers.js +38 -0
- package/dist/cli/src/app/core/analysis/insights.js +202 -0
- package/dist/cli/src/app/core/analysis/insights.types.js +10 -0
- package/dist/cli/src/app/core/analysis/invariant.js +69 -0
- package/dist/cli/src/app/core/analysis/metafile.types.js +44 -0
- package/dist/cli/src/app/core/analysis/module-graph.js +192 -0
- package/dist/cli/src/app/core/analysis/sourcemap.js +231 -0
- package/dist/cli/src/app/core/analysis/sourcemap.types.js +3 -0
- package/dist/cli/src/app/core/analysis/split-drift.js +47 -0
- package/dist/cli/src/app/core/assets/assets.js +296 -0
- package/dist/cli/src/app/core/assets/assets.types.js +11 -0
- package/dist/cli/src/app/core/baseline/baseline.js +0 -0
- package/dist/cli/src/app/core/baseline/baseline.types.js +3 -0
- package/dist/cli/src/app/core/caching/caching.js +241 -0
- package/dist/cli/src/app/core/caching/caching.types.js +10 -0
- package/dist/cli/src/app/core/caching/from-analysis.js +73 -0
- package/dist/cli/src/app/core/config/loadline-config.js +110 -0
- package/dist/cli/src/app/core/config/loadline-config.types.js +12 -0
- package/dist/cli/src/app/core/criteria/criteria.js +228 -0
- package/dist/cli/src/app/core/criteria/criteria.types.js +3 -0
- package/dist/cli/src/app/core/deps/deps.js +225 -0
- package/dist/cli/src/app/core/deps/deps.types.js +15 -0
- package/dist/cli/src/app/core/export/markdown-table.utils.js +40 -0
- package/dist/cli/src/app/core/export/summary.js +72 -0
- package/dist/cli/src/app/core/findings/actions.js +59 -0
- package/dist/cli/src/app/core/findings/assets.js +130 -0
- package/dist/cli/src/app/core/findings/caching.js +165 -0
- package/dist/cli/src/app/core/findings/compose.js +41 -0
- package/dist/cli/src/app/core/findings/deps.js +66 -0
- package/dist/cli/src/app/core/findings/effort.js +117 -0
- package/dist/cli/src/app/core/findings/finding-html.js +13 -0
- package/dist/cli/src/app/core/findings/finding-plain.js +26 -0
- package/dist/cli/src/app/core/findings/finding-text.js +1231 -0
- package/dist/cli/src/app/core/findings/finding.types.js +80 -0
- package/dist/cli/src/app/core/findings/findings.js +514 -0
- package/dist/cli/src/app/core/findings/graph.js +167 -0
- package/dist/cli/src/app/core/findings/own-in-boot.js +88 -0
- package/dist/cli/src/app/core/findings/page.js +49 -0
- package/dist/cli/src/app/core/findings/requests.js +185 -0
- package/dist/cli/src/app/core/findings/scan.js +126 -0
- package/dist/cli/src/app/core/findings/shipped.js +244 -0
- package/dist/cli/src/app/core/findings/situation.js +116 -0
- package/dist/cli/src/app/core/format/format.utils.js +204 -0
- package/dist/cli/src/app/core/i18n/en.js +819 -0
- package/dist/cli/src/app/core/i18n/es.js +822 -0
- package/dist/cli/src/app/core/i18n/ui-strings.js +11 -0
- package/dist/cli/src/app/core/i18n/ui.js +7 -0
- package/dist/cli/src/app/core/intake/bundle-graph.js +346 -0
- package/dist/cli/src/app/core/intake/bundle-graph.types.js +3 -0
- package/dist/cli/src/app/core/intake/dist-files.js +160 -0
- package/dist/cli/src/app/core/intake/index-html.js +292 -0
- package/dist/cli/src/app/core/json/json.utils.js +55 -0
- package/dist/cli/src/app/core/measurement/measurement.types.js +14 -0
- package/dist/cli/src/app/core/project/budget-advice.js +76 -0
- package/dist/cli/src/app/core/project/project-context.js +394 -0
- package/dist/cli/src/app/core/project/project-context.types.js +3 -0
- package/dist/cli/src/app/core/scan/catalog.js +67 -0
- package/dist/cli/src/app/core/scan/scan.js +280 -0
- package/dist/cli/src/app/core/scan/scan.types.js +10 -0
- package/dist/cli/src/app/core/scan/secrets.js +0 -0
- package/dist/cli/src/app/core/situation/situation.js +261 -0
- package/dist/cli/src/app/core/situation/situation.types.js +19 -0
- package/dist/cli/src/app/core/timing/timing.js +87 -0
- package/dist/cli/src/app/core/timing/timing.types.js +3 -0
- package/dist/cli/src/app/core/whatif/defer.js +68 -0
- package/dist/cli/src/app/state/report-messages.utils.js +73 -0
- package/docs/HOW-IT-WORKS.md +1087 -0
- package/loadline.html +78 -0
- package/package.json +154 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 bymaksym
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Loadline
|
|
2
|
+
|
|
3
|
+
> Weight per screen: what someone opening a screen of your app actually downloads, how much of that
|
|
4
|
+
> everybody else pays for too, and what is worth moving elsewhere.
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/@bymaksym/loadline)
|
|
7
|
+
[](https://github.com/bymaksym/LoadLine/actions/workflows/ci.yml)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
Bundle analysers report what each chunk weighs. Loadline reports what each **screen** costs: it
|
|
11
|
+
walks the import graph of your build, separates the bootstrap everyone downloads from the code a
|
|
12
|
+
single route adds, and counts how many round trips each screen takes to arrive.
|
|
13
|
+
|
|
14
|
+
It runs two ways from the same code, with the same results — as a single HTML page in your browser,
|
|
15
|
+
or as a command in your pipeline. Nothing is uploaded and nothing is fetched: the page carries its
|
|
16
|
+
own fonts and works offline.
|
|
17
|
+
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
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
|
+
inside the page.
|
|
23
|
+
|
|
24
|
+
**In the terminal.**
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx @bymaksym/loadline dist/app/browser # the build folder on its own
|
|
28
|
+
npx @bymaksym/loadline dist/app/stats.json --dist dist/app/browser
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Zero runtime dependencies, no install script, Node 20.19 or newer. `npm i -g @bymaksym/loadline` installs it;
|
|
32
|
+
`pnpm`, `yarn`, `bun` and `deno` all work, as do `pnpm dlx`, `yarn dlx` and `bunx`. The package also
|
|
33
|
+
ships `loadline.html` next to the command, under `npm root -g`.
|
|
34
|
+
|
|
35
|
+
## Compatibility
|
|
36
|
+
|
|
37
|
+
Loadline reads ES module output, either from an esbuild metafile or from the compiled folder, whose
|
|
38
|
+
chunks carry their own import graph.
|
|
39
|
+
|
|
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) |
|
|
45
|
+
|
|
46
|
+
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.
|
|
48
|
+
|
|
49
|
+
A build folder must contain the `index.html` of the build, which names the chunk the application
|
|
50
|
+
starts at. Source maps in the folder are optional: without them every figure still comes out, but
|
|
51
|
+
chunks are not broken down by source file and screens are named after their chunk.
|
|
52
|
+
|
|
53
|
+
To get a metafile out of Angular:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
ng build --configuration <the-one-your-pipeline-deploys> --stats-json
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## What you get
|
|
60
|
+
|
|
61
|
+
- **One headline number** — what is downloaded before anything appears.
|
|
62
|
+
- **One row per screen**, with bootstrap, shared code and own code on a common scale, plus **how
|
|
63
|
+
many round trips** the screen takes. A screen split across three levels of static imports costs
|
|
64
|
+
three sequential requests however little it weighs.
|
|
65
|
+
- **Real compressed sizes**, computed with `CompressionStream` over your actual output. Brotli
|
|
66
|
+
figures appear when the folder carries `.js.br` files.
|
|
67
|
+
- **Signals with a name and a fix** — shared code labelled as deferred, bootstrap pulled in for a
|
|
68
|
+
lazy screen, duplicate package versions, CommonJS packages the bundler cannot tree-shake, large
|
|
69
|
+
data files travelling in the bootstrap, and more.
|
|
70
|
+
- **Search by package or file** — which chunks it is in, what it weighs in each, which screens pay
|
|
71
|
+
for it, and the chain of imports that brings it in.
|
|
72
|
+
- **Provenance on every figure** — each threshold says whether it is external, derived or a
|
|
73
|
+
convention, and each number whether it was measured, derived, declared or is unknown.
|
|
74
|
+
|
|
75
|
+
Optional inputs widen the report:
|
|
76
|
+
|
|
77
|
+
| Drop in | Adds |
|
|
78
|
+
| ------------------------------------------- | --------------------------------------------------------------------------- |
|
|
79
|
+
| The build folder (`--dist`) | Gzip and brotli figures, per-file weights, first-load round trips |
|
|
80
|
+
| A previous build or export (`--baseline`) | Per-screen deltas, and what a returning visitor re-downloads |
|
|
81
|
+
| `angular.json`, `package.json`, the CI file | Whether your size budgets sit in the configuration the pipeline builds |
|
|
82
|
+
| A browser measurement, pasted into Measured | What is actually served: compression, 304s, third parties, real round trips |
|
|
83
|
+
| Several apps at once | What microfrontends ship twice, and what a shared package would save |
|
|
84
|
+
|
|
85
|
+
## In CI
|
|
86
|
+
|
|
87
|
+
The command prints the same headline, table and signals as the page, and can fail the build.
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
loadline dist/app/browser \
|
|
91
|
+
--baseline loadline-baseline.json \
|
|
92
|
+
--max-boot 350kB \
|
|
93
|
+
--max-growth 20kB \
|
|
94
|
+
--fail-on high
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Exit code `0` when nothing broke a gate, `1` when something did, `2` when the arguments or files
|
|
98
|
+
could not be used. With no `--max-…` and no `--fail-on` it only reports. Growth is measured on what
|
|
99
|
+
each screen adds beyond the bootstrap, and the bootstrap is checked separately, so a bootstrap that
|
|
100
|
+
grew does not break every screen's gate at once.
|
|
101
|
+
|
|
102
|
+
`--export <file>` writes this build as the baseline for the next run — the only way to produce one
|
|
103
|
+
for builds that write no `stats.json`. Write it on every run, passing or failing, so tomorrow
|
|
104
|
+
compares against yesterday rather than against the last green build.
|
|
105
|
+
|
|
106
|
+
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
|
|
109
|
+
asked for in Spanish, never read from the machine's locale, which is the same rule the page
|
|
110
|
+
follows with its language button. `loadline --help` for the full list.
|
|
111
|
+
|
|
112
|
+
```yaml
|
|
113
|
+
# .github/workflows/loadline.yml
|
|
114
|
+
name: Loadline
|
|
115
|
+
on: pull_request
|
|
116
|
+
permissions: { contents: read, pull-requests: write, security-events: write }
|
|
117
|
+
jobs:
|
|
118
|
+
weight:
|
|
119
|
+
runs-on: ubuntu-latest
|
|
120
|
+
steps:
|
|
121
|
+
- uses: actions/checkout@v4
|
|
122
|
+
- uses: actions/setup-node@v4
|
|
123
|
+
with: { node-version: 22 }
|
|
124
|
+
- 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
|
|
127
|
+
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
|
|
130
|
+
with: { sarif_file: loadline.sarif }
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Configuration
|
|
134
|
+
|
|
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.
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"tool": "loadline",
|
|
142
|
+
"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
|
+
]
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
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.
|
|
162
|
+
|
|
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.
|
|
166
|
+
|
|
167
|
+
## Documentation
|
|
168
|
+
|
|
169
|
+
- [How it works](docs/HOW-IT-WORKS.md) — the algorithm, what each signal means, the limits of the
|
|
170
|
+
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.
|
|
173
|
+
- [CHANGELOG.md](CHANGELOG.md) — what changed in each version.
|
|
174
|
+
|
|
175
|
+
When opening an issue, the **Copy diagnostics** button at the end of the report writes about thirty
|
|
176
|
+
lines describing the build and what Loadline decided about it. Package names are real; paths in your
|
|
177
|
+
own code are replaced by stable hashes, so it can be pasted in public.
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
[MIT](LICENSE). Offered with no commitment of support: issues and pull requests are welcome and may
|
|
182
|
+
sit unanswered.
|
package/bin/loadline.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/*
|
|
3
|
+
* The executable. It is hand-written JavaScript and not compiled output for two reasons: it is the
|
|
4
|
+
* only file that needs the shebang, and it is the only one that knows where the repository root is,
|
|
5
|
+
* which is how `--version` gets the version without a copy of it in the source.
|
|
6
|
+
*
|
|
7
|
+
* Checked by `tsconfig.scripts.json`: `require` of a built path hands back `any`, so the one thing
|
|
8
|
+
* worth writing down is what this file expects to find on the other side of it.
|
|
9
|
+
*/
|
|
10
|
+
// @ts-check
|
|
11
|
+
|
|
12
|
+
const { join } = require('node:path');
|
|
13
|
+
|
|
14
|
+
/** What `dist/cli/cli/main.js` exports. The command's whole interface to its own executable. */
|
|
15
|
+
/** @typedef {{ run: (argv: string[], version: string) => Promise<number> }} CompiledCli */
|
|
16
|
+
|
|
17
|
+
const root = join(__dirname, '..');
|
|
18
|
+
const entry = join(root, 'dist', 'cli', 'cli', 'main.js');
|
|
19
|
+
|
|
20
|
+
/** @type {CompiledCli | undefined} */
|
|
21
|
+
let main;
|
|
22
|
+
try {
|
|
23
|
+
main = require(entry);
|
|
24
|
+
} catch {
|
|
25
|
+
// Which of the two advices is right depends on where this file sits: inside `node_modules` it
|
|
26
|
+
// is an install that arrived without its compiled half, and the fix is another install; in a
|
|
27
|
+
// clone it is a checkout nobody has compiled yet, and the fix is the build script.
|
|
28
|
+
const installed = __dirname.includes('node_modules');
|
|
29
|
+
process.stderr.write(
|
|
30
|
+
installed
|
|
31
|
+
? 'This install is missing its compiled analysis. Install it again: npm i -g @bymaksym/loadline\n'
|
|
32
|
+
: 'The command is not built yet. Run: pnpm build:cli\n',
|
|
33
|
+
);
|
|
34
|
+
process.exitCode = 2;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
if (main) {
|
|
38
|
+
const { version } = require(join(root, 'package.json'));
|
|
39
|
+
main.run(process.argv.slice(2), version).then(
|
|
40
|
+
code => {
|
|
41
|
+
process.exitCode = code;
|
|
42
|
+
},
|
|
43
|
+
/** @param {unknown} error */
|
|
44
|
+
error => {
|
|
45
|
+
const stack = error instanceof Error ? error.stack : undefined;
|
|
46
|
+
process.stderr.write(`${stack ?? String(error)}\n`);
|
|
47
|
+
process.exitCode = 2;
|
|
48
|
+
},
|
|
49
|
+
);
|
|
50
|
+
}
|
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Reading the command line. No dependency for this on purpose: the whole surface is a handful of
|
|
4
|
+
* long flags, and an argument parser would be the only runtime dependency of a tool whose point is
|
|
5
|
+
* that it does not need one.
|
|
6
|
+
*/
|
|
7
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
+
exports.USAGE = exports.parseArgs = void 0;
|
|
9
|
+
const criteria_1 = require("../src/app/core/criteria/criteria");
|
|
10
|
+
const ui_strings_1 = require("../src/app/core/i18n/ui-strings");
|
|
11
|
+
const json_utils_1 = require("../src/app/core/json/json.utils");
|
|
12
|
+
const project_context_1 = require("../src/app/core/project/project-context");
|
|
13
|
+
// The two lists the page also uses. Written out again here, they drifted: adding a language would
|
|
14
|
+
// have been accepted by the page and rejected by the command.
|
|
15
|
+
const MODES = new Set(criteria_1.MODES);
|
|
16
|
+
const LANGS = new Set(ui_strings_1.LANGS);
|
|
17
|
+
const FORMATS = new Set([
|
|
18
|
+
'text',
|
|
19
|
+
'json',
|
|
20
|
+
'markdown',
|
|
21
|
+
'pr-comment',
|
|
22
|
+
'sarif',
|
|
23
|
+
'summary',
|
|
24
|
+
]);
|
|
25
|
+
const SEVERITIES = new Set(['high', 'mid', 'none']);
|
|
26
|
+
/** Flags that take a value. Everything else is a switch, which is how a missing value gets caught. */
|
|
27
|
+
const WITH_VALUE = new Set([
|
|
28
|
+
'--dist',
|
|
29
|
+
'--baseline',
|
|
30
|
+
'--export',
|
|
31
|
+
'--project',
|
|
32
|
+
'--mode',
|
|
33
|
+
'--lang',
|
|
34
|
+
'--format',
|
|
35
|
+
'--criteria',
|
|
36
|
+
'--config',
|
|
37
|
+
'--lock',
|
|
38
|
+
'--audit',
|
|
39
|
+
'--what-if',
|
|
40
|
+
'--max-boot',
|
|
41
|
+
'--max-screen',
|
|
42
|
+
'--max-own',
|
|
43
|
+
'--max-growth',
|
|
44
|
+
'--max-growth-pct',
|
|
45
|
+
'--fail-on',
|
|
46
|
+
]);
|
|
47
|
+
const EMPTY = {
|
|
48
|
+
target: '',
|
|
49
|
+
dist: null,
|
|
50
|
+
baseline: null,
|
|
51
|
+
export: null,
|
|
52
|
+
project: null,
|
|
53
|
+
mode: null,
|
|
54
|
+
criteria: null,
|
|
55
|
+
config: null,
|
|
56
|
+
lock: null,
|
|
57
|
+
audit: null,
|
|
58
|
+
whatIf: [],
|
|
59
|
+
lang: 'en',
|
|
60
|
+
format: 'text',
|
|
61
|
+
gates: {
|
|
62
|
+
maxBoot: null,
|
|
63
|
+
maxScreen: null,
|
|
64
|
+
maxOwn: null,
|
|
65
|
+
maxGrowth: null,
|
|
66
|
+
maxGrowthRatio: null,
|
|
67
|
+
failOn: 'none',
|
|
68
|
+
failOnNewPackage: false,
|
|
69
|
+
},
|
|
70
|
+
color: true,
|
|
71
|
+
help: false,
|
|
72
|
+
version: false,
|
|
73
|
+
selfCheck: false,
|
|
74
|
+
};
|
|
75
|
+
/** A percentage as it is written on the command line (`10`) into the fraction the code compares. */
|
|
76
|
+
const parsePercent = (value) => {
|
|
77
|
+
const number = Number(value.replace('%', ''));
|
|
78
|
+
return Number.isFinite(number) && number >= 0 ? number / 100 : null;
|
|
79
|
+
};
|
|
80
|
+
const sizeError = (flag, value) => `${flag} takes a size like 350kB, 1.5MB or a number of bytes, not "${value}".`;
|
|
81
|
+
/**
|
|
82
|
+
* Applies one flag to the options. Returns the message when the value cannot be used, so every
|
|
83
|
+
* rejection names the flag it was about instead of saying "invalid arguments".
|
|
84
|
+
*/
|
|
85
|
+
const apply = (options, flag, value, positional) => {
|
|
86
|
+
switch (flag) {
|
|
87
|
+
case '-h':
|
|
88
|
+
case '--help': {
|
|
89
|
+
options.help = true;
|
|
90
|
+
return null;
|
|
91
|
+
}
|
|
92
|
+
case '-V':
|
|
93
|
+
case '--version': {
|
|
94
|
+
options.version = true;
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
case '--no-color': {
|
|
98
|
+
options.color = false;
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
case '--self-check': {
|
|
102
|
+
options.selfCheck = true;
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
case '--dist': {
|
|
106
|
+
options.dist = value;
|
|
107
|
+
return null;
|
|
108
|
+
}
|
|
109
|
+
case '--baseline': {
|
|
110
|
+
options.baseline = value;
|
|
111
|
+
return null;
|
|
112
|
+
}
|
|
113
|
+
case '--export': {
|
|
114
|
+
options.export = value;
|
|
115
|
+
return null;
|
|
116
|
+
}
|
|
117
|
+
case '--project': {
|
|
118
|
+
options.project = value;
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
case '--criteria': {
|
|
122
|
+
options.criteria = value;
|
|
123
|
+
return null;
|
|
124
|
+
}
|
|
125
|
+
case '--config': {
|
|
126
|
+
options.config = value;
|
|
127
|
+
return null;
|
|
128
|
+
}
|
|
129
|
+
case '--lock': {
|
|
130
|
+
options.lock = value;
|
|
131
|
+
return null;
|
|
132
|
+
}
|
|
133
|
+
case '--audit': {
|
|
134
|
+
options.audit = value;
|
|
135
|
+
return null;
|
|
136
|
+
}
|
|
137
|
+
case '--what-if': {
|
|
138
|
+
options.whatIf.push(value);
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
case '--fail-on-new-package': {
|
|
142
|
+
options.gates.failOnNewPackage = true;
|
|
143
|
+
return null;
|
|
144
|
+
}
|
|
145
|
+
case '--mode': {
|
|
146
|
+
const mode = (0, json_utils_1.asMember)(value, MODES);
|
|
147
|
+
if (mode === null) {
|
|
148
|
+
return `--mode takes raw, gzip or brotli, not "${value}".`;
|
|
149
|
+
}
|
|
150
|
+
options.mode = mode;
|
|
151
|
+
return null;
|
|
152
|
+
}
|
|
153
|
+
case '--lang': {
|
|
154
|
+
const lang = (0, json_utils_1.asMember)(value, LANGS);
|
|
155
|
+
if (lang === null) {
|
|
156
|
+
return `--lang takes en or es, not "${value}".`;
|
|
157
|
+
}
|
|
158
|
+
options.lang = lang;
|
|
159
|
+
return null;
|
|
160
|
+
}
|
|
161
|
+
case '--format': {
|
|
162
|
+
const format = (0, json_utils_1.asMember)(value, FORMATS);
|
|
163
|
+
if (format === null) {
|
|
164
|
+
return `--format takes text, json, markdown, pr-comment, sarif or summary, not "${value}".`;
|
|
165
|
+
}
|
|
166
|
+
options.format = format;
|
|
167
|
+
return null;
|
|
168
|
+
}
|
|
169
|
+
case '--fail-on': {
|
|
170
|
+
const failOn = (0, json_utils_1.asMember)(value, SEVERITIES);
|
|
171
|
+
if (failOn === null) {
|
|
172
|
+
return `--fail-on takes high, mid or none, not "${value}".`;
|
|
173
|
+
}
|
|
174
|
+
options.gates.failOn = failOn;
|
|
175
|
+
return null;
|
|
176
|
+
}
|
|
177
|
+
case '--max-boot': {
|
|
178
|
+
options.gates.maxBoot = (0, project_context_1.parseSize)(value);
|
|
179
|
+
return options.gates.maxBoot === null ? sizeError(flag, value) : null;
|
|
180
|
+
}
|
|
181
|
+
case '--max-screen': {
|
|
182
|
+
options.gates.maxScreen = (0, project_context_1.parseSize)(value);
|
|
183
|
+
return options.gates.maxScreen === null ? sizeError(flag, value) : null;
|
|
184
|
+
}
|
|
185
|
+
case '--max-own': {
|
|
186
|
+
options.gates.maxOwn = (0, project_context_1.parseSize)(value);
|
|
187
|
+
return options.gates.maxOwn === null ? sizeError(flag, value) : null;
|
|
188
|
+
}
|
|
189
|
+
case '--max-growth': {
|
|
190
|
+
options.gates.maxGrowth = (0, project_context_1.parseSize)(value);
|
|
191
|
+
return options.gates.maxGrowth === null ? sizeError(flag, value) : null;
|
|
192
|
+
}
|
|
193
|
+
case '--max-growth-pct': {
|
|
194
|
+
options.gates.maxGrowthRatio = parsePercent(value);
|
|
195
|
+
return options.gates.maxGrowthRatio === null ? `--max-growth-pct takes a number, not "${value}".` : null;
|
|
196
|
+
}
|
|
197
|
+
default: {
|
|
198
|
+
if (flag.startsWith('-')) {
|
|
199
|
+
return `Unknown flag: ${flag}`;
|
|
200
|
+
}
|
|
201
|
+
positional.push(flag);
|
|
202
|
+
return null;
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
};
|
|
206
|
+
/** `--flag=value` and `--flag value` are the same thing; this turns the first into the second. */
|
|
207
|
+
const expand = (argv) => argv.flatMap(argument => {
|
|
208
|
+
const equals = argument.startsWith('--') ? argument.indexOf('=') : -1;
|
|
209
|
+
return equals > 0 ? [argument.slice(0, equals), argument.slice(equals + 1)] : [argument];
|
|
210
|
+
});
|
|
211
|
+
const parseArgs = (argv) => {
|
|
212
|
+
const options = { ...EMPTY, gates: { ...EMPTY.gates } };
|
|
213
|
+
const args = expand(argv);
|
|
214
|
+
const positional = [];
|
|
215
|
+
for (let index = 0; index < args.length; index++) {
|
|
216
|
+
const flag = args[index] ?? '';
|
|
217
|
+
const takesValue = WITH_VALUE.has(flag);
|
|
218
|
+
const value = takesValue ? args[++index] : undefined;
|
|
219
|
+
if (takesValue && value === undefined) {
|
|
220
|
+
return { ok: false, message: `${flag} needs a value.` };
|
|
221
|
+
}
|
|
222
|
+
const failed = apply(options, flag, value ?? '', positional);
|
|
223
|
+
if (failed) {
|
|
224
|
+
return { ok: false, message: failed };
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
if (options.help || options.version) {
|
|
228
|
+
return { ok: true, options };
|
|
229
|
+
}
|
|
230
|
+
const target = positional[0];
|
|
231
|
+
if (!target) {
|
|
232
|
+
return { ok: false, message: 'Missing the stats.json or the build folder to analyse.' };
|
|
233
|
+
}
|
|
234
|
+
if (positional.length > 1) {
|
|
235
|
+
return { ok: false, message: `Unexpected argument: ${positional[1]}` };
|
|
236
|
+
}
|
|
237
|
+
return { ok: true, options: { ...options, target } };
|
|
238
|
+
};
|
|
239
|
+
exports.parseArgs = parseArgs;
|
|
240
|
+
exports.USAGE = `Loadline — weight per screen, from the terminal.
|
|
241
|
+
|
|
242
|
+
Usage
|
|
243
|
+
loadline <stats.json|build folder> [options]
|
|
244
|
+
|
|
245
|
+
A build folder works on its own: its chunks carry the import graph, so anything that emits ES
|
|
246
|
+
modules — Vite, Rollup, Rolldown, esbuild — is read without a stats file. It has to hold the
|
|
247
|
+
index.html of the build, which is what names the chunk the application starts at.
|
|
248
|
+
|
|
249
|
+
Reading the build
|
|
250
|
+
--dist <folder> The build output (the "browser" folder). Gives gzip figures, brotli when
|
|
251
|
+
it carries .br files, and exact per-file weights when it carries .js.map.
|
|
252
|
+
Not needed when the folder is what is being analysed.
|
|
253
|
+
--baseline <file> A previous stats.json or a Loadline export, to compare against.
|
|
254
|
+
--export <file> Write this build's snapshot there, to be the --baseline of a later run.
|
|
255
|
+
The other half of --baseline, and the only one a build that writes no
|
|
256
|
+
stats.json has: a folder read as a graph could be compared against a
|
|
257
|
+
baseline and never produce one.
|
|
258
|
+
--lock <file> pnpm-lock.yaml, package-lock.json or yarn.lock. Says which packages you
|
|
259
|
+
did not ask for directly and what pulls each one in.
|
|
260
|
+
--audit <file.json> The output of "pnpm audit --json" or "npm audit --json". Crossed with
|
|
261
|
+
what actually ships: "3 of your 47 are in the first load" instead of
|
|
262
|
+
"you have 47". Nothing is fetched — both files are ones you already have.
|
|
263
|
+
--project <folder> Where angular.json, package.json and the pipeline file live. Adds the
|
|
264
|
+
budget checks. Not read unless asked for.
|
|
265
|
+
--mode raw|gzip|brotli Which figure the report is in. Default: the best --dist allows.
|
|
266
|
+
--criteria <file.json> Thresholds replacing the recommended ones. The Criteria tab of the page
|
|
267
|
+
writes this file with its "Download criteria" button.
|
|
268
|
+
--config <file.json> loadline.json: the thresholds, the gates and the signals the team has
|
|
269
|
+
decided to live with, kept next to the code. Without the flag, a
|
|
270
|
+
loadline.json in the working directory is read if there is one. Flags on
|
|
271
|
+
the command line win over the file.
|
|
272
|
+
|
|
273
|
+
Output
|
|
274
|
+
--format <format> text (default), summary, json, markdown, pr-comment or sarif.
|
|
275
|
+
summary is the whole report in a dozen lines — the figures, what to
|
|
276
|
+
fix first and nothing else — for a pipeline step that runs next to
|
|
277
|
+
twenty others and should not bury them.
|
|
278
|
+
pr-comment writes the comment a bot leaves on a merge request, with
|
|
279
|
+
an HTML marker so the next run edits it instead of adding a
|
|
280
|
+
sixteenth one. sarif anchors each signal to a file, which is what
|
|
281
|
+
GitHub's code scanning reads.
|
|
282
|
+
--lang en|es Default: en.
|
|
283
|
+
--no-color Never emit colour. It is off already when stdout is not a terminal.
|
|
284
|
+
|
|
285
|
+
Failing the build
|
|
286
|
+
--max-boot <size> Fail when the bootstrap is over it.
|
|
287
|
+
--max-screen <size> Fail when the total download of a screen is over it.
|
|
288
|
+
--max-own <size> Fail when the own code of a screen is over it.
|
|
289
|
+
--max-growth <size> With --baseline: fail when the bootstrap or a screen grows by more.
|
|
290
|
+
--max-growth-pct <n> The same, as a percentage.
|
|
291
|
+
--fail-on high|mid|none Fail when a signal of that severity is raised. Default: none.
|
|
292
|
+
--fail-on-new-package Fail when a package enters the bootstrap that was not in the baseline,
|
|
293
|
+
or that the "packages" list of loadline.json does not name.
|
|
294
|
+
|
|
295
|
+
Asking what if
|
|
296
|
+
--what-if <name> What the first load would weigh without that package, folder or file —
|
|
297
|
+
the figure to have BEFORE spending the afternoon. Exact: the graph is
|
|
298
|
+
walked without those files, and what stops being reachable is what stops
|
|
299
|
+
being downloaded. It does not re-chunk the build, so the round trips and
|
|
300
|
+
the per-screen totals are not recomputed and the output says so.
|
|
301
|
+
Repeatable.
|
|
302
|
+
|
|
303
|
+
Checking the tool itself
|
|
304
|
+
--self-check Work the bootstrap out twice — once by walking the import graph, once
|
|
305
|
+
by closing what index.html announces — and fail when the two disagree.
|
|
306
|
+
It says nothing about the bundle: it catches the build changing shape
|
|
307
|
+
under Loadline, which is how the figures go wrong without an error.
|
|
308
|
+
Needs the index.html, so pass the build folder or add --dist. Prints
|
|
309
|
+
the check and nothing else.
|
|
310
|
+
|
|
311
|
+
Exit codes
|
|
312
|
+
0 ran, nothing broke a gate.
|
|
313
|
+
1 a gate broke.
|
|
314
|
+
2 the arguments or the files could not be used.
|
|
315
|
+
|
|
316
|
+
Examples
|
|
317
|
+
loadline dist/app/browser
|
|
318
|
+
loadline dist/app/stats.json --dist dist/app/browser
|
|
319
|
+
loadline dist/app/stats.json --dist dist/app/browser --max-boot 350kB --fail-on high
|
|
320
|
+
loadline dist/app/stats.json --baseline prev/stats.json --max-growth 20kB --format json
|
|
321
|
+
loadline dist --export loadline-baseline.json
|
|
322
|
+
loadline dist --baseline loadline-baseline.json --max-growth 20kB
|
|
323
|
+
loadline dist/app/stats.json --dist dist/app/browser --self-check
|
|
324
|
+
`;
|