@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.
Files changed (98) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -0
  3. package/bin/loadline.js +50 -0
  4. package/dist/cli/cli/args.js +324 -0
  5. package/dist/cli/cli/args.types.js +3 -0
  6. package/dist/cli/cli/gates.js +173 -0
  7. package/dist/cli/cli/gates.types.js +3 -0
  8. package/dist/cli/cli/main.js +156 -0
  9. package/dist/cli/cli/read-build.js +382 -0
  10. package/dist/cli/cli/read-build.types.js +3 -0
  11. package/dist/cli/cli/render-json.js +116 -0
  12. package/dist/cli/cli/render-json.types.js +10 -0
  13. package/dist/cli/cli/render-markdown.js +30 -0
  14. package/dist/cli/cli/render-pr.js +76 -0
  15. package/dist/cli/cli/render-sarif.js +83 -0
  16. package/dist/cli/cli/render-text.js +388 -0
  17. package/dist/cli/cli/report.js +196 -0
  18. package/dist/cli/cli/report.types.js +3 -0
  19. package/dist/cli/cli/self-check.js +85 -0
  20. package/dist/cli/cli/text.js +180 -0
  21. package/dist/cli/cli/text.types.js +10 -0
  22. package/dist/cli/src/app/core/analysis/analysis.js +661 -0
  23. package/dist/cli/src/app/core/analysis/analysis.types.js +6 -0
  24. package/dist/cli/src/app/core/analysis/barrels.js +128 -0
  25. package/dist/cli/src/app/core/analysis/blast.js +172 -0
  26. package/dist/cli/src/app/core/analysis/cycles.js +110 -0
  27. package/dist/cli/src/app/core/analysis/delivery.js +143 -0
  28. package/dist/cli/src/app/core/analysis/entries.js +217 -0
  29. package/dist/cli/src/app/core/analysis/exclusive.js +91 -0
  30. package/dist/cli/src/app/core/analysis/importers.js +38 -0
  31. package/dist/cli/src/app/core/analysis/insights.js +202 -0
  32. package/dist/cli/src/app/core/analysis/insights.types.js +10 -0
  33. package/dist/cli/src/app/core/analysis/invariant.js +69 -0
  34. package/dist/cli/src/app/core/analysis/metafile.types.js +44 -0
  35. package/dist/cli/src/app/core/analysis/module-graph.js +192 -0
  36. package/dist/cli/src/app/core/analysis/sourcemap.js +231 -0
  37. package/dist/cli/src/app/core/analysis/sourcemap.types.js +3 -0
  38. package/dist/cli/src/app/core/analysis/split-drift.js +47 -0
  39. package/dist/cli/src/app/core/assets/assets.js +296 -0
  40. package/dist/cli/src/app/core/assets/assets.types.js +11 -0
  41. package/dist/cli/src/app/core/baseline/baseline.js +0 -0
  42. package/dist/cli/src/app/core/baseline/baseline.types.js +3 -0
  43. package/dist/cli/src/app/core/caching/caching.js +241 -0
  44. package/dist/cli/src/app/core/caching/caching.types.js +10 -0
  45. package/dist/cli/src/app/core/caching/from-analysis.js +73 -0
  46. package/dist/cli/src/app/core/config/loadline-config.js +110 -0
  47. package/dist/cli/src/app/core/config/loadline-config.types.js +12 -0
  48. package/dist/cli/src/app/core/criteria/criteria.js +228 -0
  49. package/dist/cli/src/app/core/criteria/criteria.types.js +3 -0
  50. package/dist/cli/src/app/core/deps/deps.js +225 -0
  51. package/dist/cli/src/app/core/deps/deps.types.js +15 -0
  52. package/dist/cli/src/app/core/export/markdown-table.utils.js +40 -0
  53. package/dist/cli/src/app/core/export/summary.js +72 -0
  54. package/dist/cli/src/app/core/findings/actions.js +59 -0
  55. package/dist/cli/src/app/core/findings/assets.js +130 -0
  56. package/dist/cli/src/app/core/findings/caching.js +165 -0
  57. package/dist/cli/src/app/core/findings/compose.js +41 -0
  58. package/dist/cli/src/app/core/findings/deps.js +66 -0
  59. package/dist/cli/src/app/core/findings/effort.js +117 -0
  60. package/dist/cli/src/app/core/findings/finding-html.js +13 -0
  61. package/dist/cli/src/app/core/findings/finding-plain.js +26 -0
  62. package/dist/cli/src/app/core/findings/finding-text.js +1231 -0
  63. package/dist/cli/src/app/core/findings/finding.types.js +80 -0
  64. package/dist/cli/src/app/core/findings/findings.js +514 -0
  65. package/dist/cli/src/app/core/findings/graph.js +167 -0
  66. package/dist/cli/src/app/core/findings/own-in-boot.js +88 -0
  67. package/dist/cli/src/app/core/findings/page.js +49 -0
  68. package/dist/cli/src/app/core/findings/requests.js +185 -0
  69. package/dist/cli/src/app/core/findings/scan.js +126 -0
  70. package/dist/cli/src/app/core/findings/shipped.js +244 -0
  71. package/dist/cli/src/app/core/findings/situation.js +116 -0
  72. package/dist/cli/src/app/core/format/format.utils.js +204 -0
  73. package/dist/cli/src/app/core/i18n/en.js +819 -0
  74. package/dist/cli/src/app/core/i18n/es.js +822 -0
  75. package/dist/cli/src/app/core/i18n/ui-strings.js +11 -0
  76. package/dist/cli/src/app/core/i18n/ui.js +7 -0
  77. package/dist/cli/src/app/core/intake/bundle-graph.js +346 -0
  78. package/dist/cli/src/app/core/intake/bundle-graph.types.js +3 -0
  79. package/dist/cli/src/app/core/intake/dist-files.js +160 -0
  80. package/dist/cli/src/app/core/intake/index-html.js +292 -0
  81. package/dist/cli/src/app/core/json/json.utils.js +55 -0
  82. package/dist/cli/src/app/core/measurement/measurement.types.js +14 -0
  83. package/dist/cli/src/app/core/project/budget-advice.js +76 -0
  84. package/dist/cli/src/app/core/project/project-context.js +394 -0
  85. package/dist/cli/src/app/core/project/project-context.types.js +3 -0
  86. package/dist/cli/src/app/core/scan/catalog.js +67 -0
  87. package/dist/cli/src/app/core/scan/scan.js +280 -0
  88. package/dist/cli/src/app/core/scan/scan.types.js +10 -0
  89. package/dist/cli/src/app/core/scan/secrets.js +0 -0
  90. package/dist/cli/src/app/core/situation/situation.js +261 -0
  91. package/dist/cli/src/app/core/situation/situation.types.js +19 -0
  92. package/dist/cli/src/app/core/timing/timing.js +87 -0
  93. package/dist/cli/src/app/core/timing/timing.types.js +3 -0
  94. package/dist/cli/src/app/core/whatif/defer.js +68 -0
  95. package/dist/cli/src/app/state/report-messages.utils.js +73 -0
  96. package/docs/HOW-IT-WORKS.md +1087 -0
  97. package/loadline.html +78 -0
  98. 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
+ [![npm](https://img.shields.io/npm/v/@bymaksym/loadline.svg)](https://www.npmjs.com/package/@bymaksym/loadline)
7
+ [![CI](https://github.com/bymaksym/LoadLine/actions/workflows/ci.yml/badge.svg)](https://github.com/bymaksym/LoadLine/actions/workflows/ci.yml)
8
+ [![license](https://img.shields.io/github/license/bymaksym/LoadLine.svg)](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.
@@ -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
+ `;
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ /** What the command was asked to do, once the arguments are read. */
3
+ Object.defineProperty(exports, "__esModule", { value: true });