@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
@@ -0,0 +1,173 @@
1
+ "use strict";
2
+ /**
3
+ * The gates: the only part of the command that decides whether a pipeline stops. Kept apart from
4
+ * everything that prints, because "what is wrong" and "what is bad enough to stop a deploy" are
5
+ * two different questions and only the second one has to be answered the same way every time.
6
+ *
7
+ * Growth is measured on what a screen adds beyond the bootstrap, not on its total. The bootstrap
8
+ * is checked once, on its own: otherwise a bootstrap that grew by 30 kB would break the gate of
9
+ * every screen at once and send someone to twenty places to fix one thing.
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.violationLines = exports.anyGate = exports.checkGates = exports.mergeGates = void 0;
13
+ const format_utils_1 = require("../src/app/core/format/format.utils");
14
+ const project_context_1 = require("../src/app/core/project/project-context");
15
+ const text_1 = require("./text");
16
+ const percent = (ratio) => (ratio * 100).toFixed(1);
17
+ /** Which severities the `--fail-on` level covers. `high` alone, or `high` and `mid`. */
18
+ const covered = (level) => level === 'mid' ? new Set(['high', 'mid']) : new Set(['high']);
19
+ /**
20
+ * The gates of `loadline.json` under the ones typed on the command line.
21
+ *
22
+ * Only where the flag is absent: a limit typed by hand is somebody overriding the committed
23
+ * decision for one run, and silently ignoring it would be the worse of the two surprises. Sizes in
24
+ * the file are written the way people read them — `350kB` — and a value that cannot be parsed is
25
+ * dropped rather than read as zero, which would fail every build.
26
+ */
27
+ const mergeGates = (gates, config) => {
28
+ const wanted = config?.gates;
29
+ if (!wanted) {
30
+ return gates;
31
+ }
32
+ const size = (value) => (value === undefined ? null : (0, project_context_1.parseSize)(value));
33
+ return {
34
+ maxBoot: gates.maxBoot ?? size(wanted.maxBoot),
35
+ maxScreen: gates.maxScreen ?? size(wanted.maxScreen),
36
+ maxOwn: gates.maxOwn ?? size(wanted.maxOwn),
37
+ maxGrowth: gates.maxGrowth ?? size(wanted.maxGrowth),
38
+ maxGrowthRatio: gates.maxGrowthRatio ?? (wanted.maxGrowthPct === undefined ? null : wanted.maxGrowthPct / 100),
39
+ failOn: gates.failOn === 'none' ? (wanted.failOn ?? 'none') : gates.failOn,
40
+ failOnNewPackage: gates.failOnNewPackage || wanted.failOnNewPackage === true,
41
+ };
42
+ };
43
+ exports.mergeGates = mergeGates;
44
+ const checkGates = (report, gates) => {
45
+ const text = text_1.CLI_TEXT[report.lang];
46
+ const violations = [];
47
+ const { analysis, comparison } = report;
48
+ if (gates.maxBoot !== null && analysis.bootBytes > gates.maxBoot) {
49
+ violations.push({
50
+ gate: 'boot',
51
+ subject: null,
52
+ limit: gates.maxBoot,
53
+ actual: analysis.bootBytes,
54
+ message: text.overBoot((0, format_utils_1.formatBytes)(analysis.bootBytes), (0, format_utils_1.formatBytes)(gates.maxBoot)),
55
+ });
56
+ }
57
+ for (const screen of analysis.screens) {
58
+ if (gates.maxScreen !== null && screen.total > gates.maxScreen) {
59
+ violations.push({
60
+ gate: 'screen',
61
+ subject: screen.label,
62
+ limit: gates.maxScreen,
63
+ actual: screen.total,
64
+ message: text.overScreen(screen.label, (0, format_utils_1.formatBytes)(screen.total), (0, format_utils_1.formatBytes)(gates.maxScreen)),
65
+ });
66
+ }
67
+ if (gates.maxOwn !== null && screen.own > gates.maxOwn) {
68
+ violations.push({
69
+ gate: 'own',
70
+ subject: screen.label,
71
+ limit: gates.maxOwn,
72
+ actual: screen.own,
73
+ message: text.overOwn(screen.label, (0, format_utils_1.formatBytes)(screen.own), (0, format_utils_1.formatBytes)(gates.maxOwn)),
74
+ });
75
+ }
76
+ }
77
+ if (comparison) {
78
+ const { maxGrowth, maxGrowthRatio } = gates;
79
+ if (maxGrowth !== null && comparison.boot.diff > maxGrowth) {
80
+ violations.push({
81
+ gate: 'growth',
82
+ subject: null,
83
+ limit: maxGrowth,
84
+ actual: comparison.boot.diff,
85
+ message: text.growthBoot((0, format_utils_1.formatDelta)(comparison.boot.diff), (0, format_utils_1.formatBytes)(maxGrowth)),
86
+ });
87
+ }
88
+ if (maxGrowthRatio !== null && comparison.boot.ratio > maxGrowthRatio) {
89
+ violations.push({
90
+ gate: 'growth-pct',
91
+ subject: null,
92
+ limit: maxGrowthRatio,
93
+ actual: comparison.boot.ratio,
94
+ message: text.growthPctBoot(percent(comparison.boot.ratio), percent(maxGrowthRatio)),
95
+ });
96
+ }
97
+ for (const screen of comparison.screens.values()) {
98
+ if (maxGrowth !== null && screen.lazy.diff > maxGrowth) {
99
+ violations.push({
100
+ gate: 'growth',
101
+ subject: screen.label,
102
+ limit: maxGrowth,
103
+ actual: screen.lazy.diff,
104
+ message: text.growthScreen(screen.label, (0, format_utils_1.formatDelta)(screen.lazy.diff), (0, format_utils_1.formatBytes)(maxGrowth)),
105
+ });
106
+ }
107
+ if (maxGrowthRatio !== null && screen.lazy.ratio > maxGrowthRatio) {
108
+ violations.push({
109
+ gate: 'growth-pct',
110
+ subject: screen.label,
111
+ limit: maxGrowthRatio,
112
+ actual: screen.lazy.ratio,
113
+ message: text.growthPctScreen(screen.label, percent(screen.lazy.ratio), percent(maxGrowthRatio)),
114
+ });
115
+ }
116
+ }
117
+ }
118
+ // A package that entered the bootstrap. Two sources, and both are wanted: the baseline says
119
+ // what was there last time, and `loadline.json` says what the team agreed to. Without either,
120
+ // the gate has nothing to compare against and says so rather than passing quietly.
121
+ if (gates.failOnNewPackage) {
122
+ const approved = report.config?.packages;
123
+ const entered = approved
124
+ ? report.analysis.bootBuckets.filter(bucket => !bucket.isProjectCode && !approved.includes(bucket.name))
125
+ : (comparison?.newBootPackages ?? []).map(pkg => ({ name: pkg.name, bytes: pkg.bytes }));
126
+ if (entered.length > 0) {
127
+ violations.push({
128
+ gate: 'new-package',
129
+ subject: null,
130
+ limit: 0,
131
+ actual: entered.length,
132
+ message: text.newPackages(entered.map(pkg => `${pkg.name} (${(0, format_utils_1.formatBytes)(pkg.bytes)})`)),
133
+ });
134
+ }
135
+ }
136
+ if (gates.failOn !== 'none') {
137
+ const levels = covered(gates.failOn);
138
+ const raised = report.findings.filter(finding => levels.has(finding.severity));
139
+ if (raised.length > 0) {
140
+ violations.push({
141
+ gate: 'signals',
142
+ subject: null,
143
+ limit: 0,
144
+ actual: raised.length,
145
+ message: text.signalsRaised(raised.length, gates.failOn),
146
+ });
147
+ }
148
+ }
149
+ return violations;
150
+ };
151
+ exports.checkGates = checkGates;
152
+ /** Whether any gate was asked for at all, which is what tells "passed" from "nothing was checked". */
153
+ const anyGate = (gates) => gates.failOn !== 'none' ||
154
+ gates.failOnNewPackage ||
155
+ [gates.maxBoot, gates.maxScreen, gates.maxOwn, gates.maxGrowth, gates.maxGrowthRatio].some(limit => limit !== null);
156
+ exports.anyGate = anyGate;
157
+ /**
158
+ * The broken gates as lines to print, grouped by gate and every one of them named.
159
+ *
160
+ * It used to print the worst three of each and "and N more". The argument was that when a shared
161
+ * chunk grows every screen breaks the same limit by the same amount, so twenty lines send somebody
162
+ * to twenty places to fix one thing — but that is a reason to group them under their gate, which
163
+ * is what the grouping already does, not a reason to leave seventeen of them out of the log
164
+ * somebody is reading to find out what broke.
165
+ */
166
+ const violationLines = (violations) => {
167
+ const byGate = new Map();
168
+ for (const violation of violations) {
169
+ byGate.set(violation.gate, [...(byGate.get(violation.gate) ?? []), violation]);
170
+ }
171
+ return [...byGate.values()].flatMap(group => group.map(violation => violation.message));
172
+ };
173
+ exports.violationLines = violationLines;
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ /** What a broken gate is, once checked. */
3
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,156 @@
1
+ "use strict";
2
+ /**
3
+ * The command itself: read the arguments, read the files, analyse, check the gates, print, and
4
+ * return the exit code. Everything it does is in the modules around it; what this file owns is
5
+ * the order and the exit code, which is the only part a pipeline actually reads.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.run = exports.UNUSABLE = exports.FAILED = exports.OK = void 0;
9
+ const promises_1 = require("node:fs/promises");
10
+ const summary_1 = require("../src/app/core/export/summary");
11
+ const ui_1 = require("../src/app/core/i18n/ui");
12
+ const report_messages_utils_1 = require("../src/app/state/report-messages.utils");
13
+ const args_1 = require("./args");
14
+ const gates_1 = require("./gates");
15
+ const read_build_1 = require("./read-build");
16
+ const render_json_1 = require("./render-json");
17
+ const render_markdown_1 = require("./render-markdown");
18
+ const render_pr_1 = require("./render-pr");
19
+ const render_sarif_1 = require("./render-sarif");
20
+ const render_text_1 = require("./render-text");
21
+ const report_1 = require("./report");
22
+ const self_check_1 = require("./self-check");
23
+ const text_1 = require("./text");
24
+ /** 0 ran clean · 1 a gate broke · 2 the arguments or the files could not be used. */
25
+ exports.OK = 0;
26
+ exports.FAILED = 1;
27
+ exports.UNUSABLE = 2;
28
+ const write = (stream, value) => {
29
+ stream.write(`${value}\n`);
30
+ };
31
+ const NO_DIST = {
32
+ gzip: null,
33
+ brotli: null,
34
+ splits: null,
35
+ announced: null,
36
+ graph: null,
37
+ pageCss: null,
38
+ assets: null,
39
+ hrefs: [],
40
+ texts: new Map(),
41
+ maps: [],
42
+ };
43
+ /** Everything off the disk, in one place, so the analysis starts with nothing left to fetch. */
44
+ const readInputs = async (options) => {
45
+ // A folder is the build itself, so it is both what is analysed and where the figures come from.
46
+ const derive = await (0, read_build_1.isFolder)(options.target);
47
+ if (derive && options.dist) {
48
+ throw new read_build_1.InputError('--dist is the folder already being analysed; drop one of the two.');
49
+ }
50
+ const folder = derive ? options.target : options.dist;
51
+ const dist = folder ? await (0, read_build_1.readDist)(folder, derive) : NO_DIST;
52
+ return {
53
+ meta: dist.graph ? dist.graph.meta : await (0, read_build_1.readStats)(options.target, ui_1.UI[options.lang]),
54
+ parallel: dist.graph?.parallel ?? null,
55
+ statsName: options.target,
56
+ ...dist,
57
+ ...(await (0, read_build_1.readLoadlineConfig)(options.config, process.cwd()).then(read => ({
58
+ config: read.config,
59
+ configProblems: read.problems,
60
+ configName: read.name,
61
+ }))),
62
+ ...(await (0, read_build_1.readDepsFiles)(options.lock, options.audit)),
63
+ baseline: options.baseline ? await (0, read_build_1.readBaseline)(options.baseline) : null,
64
+ context: options.project ? await (0, read_build_1.readProject)(options.project) : { angular: null, pkg: null, pipelines: [] },
65
+ criteria: options.criteria ? await (0, read_build_1.readCriteria)(options.criteria) : null,
66
+ };
67
+ };
68
+ /**
69
+ * A growth gate with nothing to grow against would pass every build, quietly, forever. Saying so
70
+ * beats a green pipeline that checks nothing.
71
+ */
72
+ const requireBaseline = (options) => {
73
+ const wantsGrowth = options.gates.maxGrowth !== null || options.gates.maxGrowthRatio !== null;
74
+ if (wantsGrowth && !options.baseline) {
75
+ throw new read_build_1.InputError('--max-growth and --max-growth-pct need a --baseline to compare against.');
76
+ }
77
+ };
78
+ const run = async (argv, version) => {
79
+ const parsed = (0, args_1.parseArgs)(argv);
80
+ if (!parsed.ok) {
81
+ write(process.stderr, `${parsed.message}\n\nRun loadline --help to see the options.`);
82
+ return exports.UNUSABLE;
83
+ }
84
+ const options = parsed.options;
85
+ if (options.help) {
86
+ write(process.stdout, args_1.USAGE);
87
+ return exports.OK;
88
+ }
89
+ if (options.version) {
90
+ write(process.stdout, `loadline ${version}`);
91
+ return exports.OK;
92
+ }
93
+ try {
94
+ requireBaseline(options);
95
+ const input = await readInputs(options);
96
+ // The gates the file asks for, where the command line did not ask for that one. A flag typed
97
+ // by hand is somebody overriding the committed decision on purpose, so it wins.
98
+ const gates = (0, gates_1.mergeGates)(options.gates, input.config ?? null);
99
+ const report = (0, report_1.buildReport)(input, { ...options, gates });
100
+ // The self-check is about Loadline, not about the build, so it replaces the report rather
101
+ // than being one more section of it — and it owns the exit code while it is asked for.
102
+ if (options.selfCheck) {
103
+ const checked = (0, self_check_1.selfCheck)(input.meta, report.analysis, input.announced);
104
+ write(checked.ok ? process.stdout : process.stderr, checked.report);
105
+ return checked.ok ? exports.OK : exports.FAILED;
106
+ }
107
+ // Before the gates: a build that broke one is still the build that was made, and a
108
+ // pipeline that only writes the baseline when it is under budget would compare tomorrow
109
+ // against whichever green build came last rather than against yesterday.
110
+ if (options.export) {
111
+ // The message comes off the error as it is. `errorMessage` translates the codes the
112
+ // *analysis* throws and ends every one of them with "what is expected is the stats.json
113
+ // ng build --stats-json writes" — which, bolted onto a directory that does not exist,
114
+ // sends somebody to check the file that was read fine.
115
+ const failed = await (0, promises_1.writeFile)(options.export, JSON.stringify(report.snapshot, null, 2), 'utf8').catch((error) => (error instanceof Error ? error.message : String(error)));
116
+ if (failed) {
117
+ throw new read_build_1.InputError(`Could not write ${options.export}: ${failed}`);
118
+ }
119
+ }
120
+ const asked = (0, gates_1.anyGate)(gates);
121
+ const violations = (0, gates_1.checkGates)(report, gates);
122
+ // Colour is for a person watching a terminal; a redirected stream is a file or a log.
123
+ const color = options.color && process.stdout.isTTY === true && !process.env['NO_COLOR'];
124
+ const rendered = {
125
+ text: () => (0, render_text_1.renderText)(report, violations, asked, color),
126
+ json: () => (0, render_json_1.renderJson)(report, violations, asked),
127
+ markdown: () => (0, render_markdown_1.renderMarkdown)(report, violations, asked),
128
+ 'pr-comment': () => (0, render_pr_1.renderPrComment)(report, violations, asked),
129
+ sarif: () => (0, render_sarif_1.renderSarif)(report),
130
+ summary: () => (0, summary_1.summaryText)({
131
+ analysis: report.analysis,
132
+ findings: report.findings,
133
+ comparison: report.comparison,
134
+ unit: report.unit,
135
+ name: report.statsName,
136
+ firstTrip: report.assets?.firstTrip.total ?? null,
137
+ lang: report.lang,
138
+ }),
139
+ };
140
+ // What is wrong with `loadline.json` goes to stderr, never into the report: something is
141
+ // parsing stdout, and a warning in the middle of a SARIF document breaks it.
142
+ for (const problem of report.configProblems) {
143
+ write(process.stderr, text_1.CLI_TEXT[options.lang].configProblem(problem));
144
+ }
145
+ write(process.stdout, rendered[options.format]());
146
+ return violations.length > 0 ? exports.FAILED : exports.OK;
147
+ }
148
+ catch (error) {
149
+ // The codes the analysis throws are translated with the same table the page uses; anything
150
+ // else is printed as it came, because an unexpected failure should not be reworded.
151
+ const message = error instanceof read_build_1.InputError ? error.message : (0, report_messages_utils_1.errorMessage)(error, ui_1.UI[options.lang]);
152
+ write(process.stderr, message);
153
+ return exports.UNUSABLE;
154
+ }
155
+ };
156
+ exports.run = run;