@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,244 @@
1
+ "use strict";
2
+ /**
3
+ * Three things that ship inside the bundle without being code anybody wrote for this screen. None
4
+ * of them is found by looking at what is heavy — they are small enough to hide in a treemap and
5
+ * they are all avoidable, which is why they are worth naming:
6
+ *
7
+ * - **Every language of a library, to use one.** The classic 90 % cut: a date library that ships
8
+ * its whole `locale/` folder.
9
+ * - **Data shipped as code.** An `import` of a `.json` embeds the file in a chunk of JavaScript
10
+ * instead of referencing it.
11
+ * - **The source maps left in the deployed folder.** Not weight — whoever downloads them has the
12
+ * original source.
13
+ *
14
+ * The rules use folder conventions and file extensions, never a list of package names: a list would
15
+ * be wrong for the library that comes out next year and right only for the ones in fashion today.
16
+ */
17
+ Object.defineProperty(exports, "__esModule", { value: true });
18
+ exports.buildFolderFindings = exports.buildShippedFindings = void 0;
19
+ const format_utils_1 = require("../format/format.utils");
20
+ const finding_text_1 = require("./finding-text");
21
+ /**
22
+ * A file named after a language: `es.js`, `pt-BR.json`, `zh-Hant.mjs`. Counting **codes** and not
23
+ * files is what keeps the count right — `date-fns` splits one language across ten files under
24
+ * `locale/en-US/_lib/`, and counting those would report ten languages where there is one.
25
+ */
26
+ const LOCALE_CODE = /^([a-z]{2,3})(-[A-Za-z0-9]{2,8})?$/;
27
+ /**
28
+ * What a library calls the folder it keeps its languages in. `locale` and `locales` were the whole
29
+ * list, which quietly meant that a package shipping them under `i18n/` — which plenty do — raised
30
+ * nothing at all.
31
+ */
32
+ const LOCALE_FOLDERS = new Set(['locale', 'locales', 'i18n', 'lang', 'langs', 'languages', 'translations']);
33
+ /**
34
+ * The language a file belongs to, if it belongs to one. Libraries name it in two places and both
35
+ * are needed: `moment/locale/es.js` and `primelocale/es.json` put it in the file name,
36
+ * `date-fns/locale/es/index.js` puts it in the folder right after `locale/`.
37
+ */
38
+ const localeOf = (path) => {
39
+ const parts = path.split('/');
40
+ const marker = parts.findIndex(part => LOCALE_FOLDERS.has(part));
41
+ const candidates = marker === -1 ? [parts.at(-1)] : [parts[marker + 1], parts.at(-1)];
42
+ for (const candidate of candidates) {
43
+ const code = (candidate ?? '').replace(/\.[^.]+$/, '');
44
+ if (LOCALE_CODE.test(code)) {
45
+ return code;
46
+ }
47
+ }
48
+ return null;
49
+ };
50
+ const sum = (modules) => modules.reduce((total, module) => total + module.bytes, 0);
51
+ /** The worst place a set of files lands: the bootstrap is the one everybody pays for. */
52
+ const inBoot = (modules) => modules.some(module => module.places.some(place => place.zone === 'boot'));
53
+ /**
54
+ * Languages of a library, shipped whole. Grouped by package because that is the unit the decision
55
+ * is about: one `moment` shipping 130 locales is one finding, not 130.
56
+ */
57
+ const localePackages = (analysis, c) => {
58
+ const byPackage = new Map();
59
+ for (const module of analysis.modules) {
60
+ if (module.pkg && localeOf(module.path)) {
61
+ byPackage.set(module.pkg, [...(byPackage.get(module.pkg) ?? []), module]);
62
+ }
63
+ }
64
+ return [...byPackage]
65
+ .map(([pkg, modules]) => ({
66
+ pkg,
67
+ modules,
68
+ bytes: sum(modules),
69
+ codes: new Set(modules.map(module => localeOf(module.path))).size,
70
+ }))
71
+ .filter(entry => entry.codes >= c.minLocales && entry.bytes >= c.shippedMinBytes)
72
+ .toSorted((a, b) => b.bytes - a.bytes);
73
+ };
74
+ const localeFinding = (analysis, lang, c) => {
75
+ const text = finding_text_1.TEXT[lang];
76
+ const worst = localePackages(analysis, c);
77
+ const top = worst[0];
78
+ if (!top) {
79
+ return null;
80
+ }
81
+ const boot = worst.some(entry => inBoot(entry.modules));
82
+ // Every language file, whichever package it belongs to: the fix is one import per package and
83
+ // what it takes off is what those files weigh where they land.
84
+ const files = worst.flatMap(entry => entry.modules.map(module => module.path));
85
+ return {
86
+ severity: boot ? 'mid' : 'info',
87
+ target: { tab: 'search', key: top.pkg },
88
+ kind: 'locales',
89
+ saving: boot ? analysis.insights().exclusiveOf(files) : 0,
90
+ sources: boot ? files : [],
91
+ ...text.locales({
92
+ packages: worst.map(entry => ({
93
+ name: entry.pkg,
94
+ files: entry.codes,
95
+ size: (0, format_utils_1.formatBytes)(entry.bytes),
96
+ })),
97
+ size: (0, format_utils_1.formatBytes)(worst.reduce((total, entry) => total + entry.bytes, 0)),
98
+ boot,
99
+ }),
100
+ };
101
+ };
102
+ /** Files that are data, embedded in a chunk because somebody imported them instead of asking for them. */
103
+ const dataFinding = (analysis, lang, c, counted) => {
104
+ const text = finding_text_1.TEXT[lang];
105
+ // Whatever the languages signal already reported is not reported twice with different advice.
106
+ const data = analysis.modules.filter(module => module.path.endsWith('.json') && !counted.has(module.path));
107
+ const bytes = sum(data);
108
+ if (data.length === 0 || bytes < c.shippedMinBytes) {
109
+ return null;
110
+ }
111
+ const heaviest = data.toSorted((a, b) => b.bytes - a.bytes);
112
+ const boot = inBoot(data);
113
+ const files = data.map(module => module.path);
114
+ return {
115
+ severity: boot ? 'mid' : 'info',
116
+ target: { tab: 'search', key: heaviest[0]?.label ?? '' },
117
+ kind: 'dataAsCode',
118
+ saving: boot ? analysis.insights().exclusiveOf(files) : 0,
119
+ sources: boot ? files : [],
120
+ ...text.dataAsCode({
121
+ count: data.length,
122
+ size: (0, format_utils_1.formatBytes)(bytes),
123
+ items: heaviest.map(module => ({ name: module.label, size: (0, format_utils_1.formatBytes)(module.bytes) })),
124
+ boot,
125
+ }),
126
+ };
127
+ };
128
+ /** The two signals that come out of the analysis alone. */
129
+ const buildShippedFindings = (analysis, lang, c) => {
130
+ const asLocales = new Set(localePackages(analysis, c).flatMap(entry => entry.modules.map(module => module.path)));
131
+ return [localeFinding(analysis, lang, c), dataFinding(analysis, lang, c, asLocales)].filter((finding) => !!finding);
132
+ };
133
+ exports.buildShippedFindings = buildShippedFindings;
134
+ /**
135
+ * What the build folder itself gives away. Conditional on purpose: the folder dropped here may be a
136
+ * local build rather than the one that gets deployed, and the report says so instead of accusing.
137
+ */
138
+ /**
139
+ * A screen row nobody can identify: `chunk-Brh4_81T`, `0fPdmq0U`.
140
+ *
141
+ * The `chunk-` prefix is decisive on its own — no one names a route that, and it is what Angular
142
+ * writes for every lazy chunk. Past that the test is deliberately strict: mixed case **and** a
143
+ * digit, so a screen that really is called `Dashboard` is never mistaken for a hash. Missing one is
144
+ * a hint not given; claiming one wrongly is the report calling a real name gibberish.
145
+ */
146
+ const unnamedScreen = (label) => {
147
+ const rest = label.replace(/^chunk[-._]/i, '');
148
+ if (rest !== label) {
149
+ return true;
150
+ }
151
+ return /^[\dA-Za-z_-]{6,}$/.test(rest) && /[a-z]/.test(rest) && /[A-Z]/.test(rest) && /\d/.test(rest);
152
+ };
153
+ /**
154
+ * How far the two measurements of the same chunks have to be apart before it is worth a line.
155
+ *
156
+ * A per-file breakdown never lands exactly on the file: a bundler's own runtime is in the output
157
+ * and belongs to no input. Measured on an Angular 17 build the sum is 99 % of the file, which is
158
+ * that overhead and nothing else. At five per cent something other than rounding is going on, and
159
+ * at fifteen every figure measured inside a chunk is wrong by enough to change what somebody does
160
+ * about it — that is where it stops being a note and becomes the first thing to fix.
161
+ */
162
+ const DRIFT_WORTH_SAYING = 0.05;
163
+ const DRIFT_WORTH_ACTING_ON = 0.15;
164
+ /**
165
+ * And how many bytes apart, which is the half a percentage cannot express.
166
+ *
167
+ * That overhead — the module wrapper, the banners, the `sourceMappingURL` line — is a fixed cost per
168
+ * chunk and not a proportion of one. A plain esbuild build of five chunks weighing 90 to 330 bytes
169
+ * each came out at **59 %**, which read as a `mid` on a build where nothing whatsoever was wrong:
170
+ * 395 bytes of wrapper across five tiny chunks. On anything the size of a real application the same
171
+ * 395 bytes are invisible. So the ratio says whether it matters and this says whether it is real,
172
+ * and both have to agree before a line is printed.
173
+ */
174
+ const DRIFT_OVERHEAD_PER_CHUNK = 1024;
175
+ /**
176
+ * The report's own margin of error, when it has one and can measure it.
177
+ *
178
+ * Every figure taken from *inside* a chunk is a sum of per-file weights, and the chunk's own weight
179
+ * is a second measurement of the same thing. When they disagree the first set is wrong by exactly
180
+ * that ratio — measured here at 125 % on three Angular 22 builds, where the metafile is written
181
+ * before a later pass shrinks the output — while the headline weight beside it stays exact. Nothing
182
+ * said so, and a quarter is enough to change which row somebody spends an afternoon on.
183
+ */
184
+ const driftFinding = (drift, lang) => {
185
+ if (!drift) {
186
+ return [];
187
+ }
188
+ const off = Math.abs(drift.ratio - 1);
189
+ const bytes = Math.abs(drift.measured - drift.file);
190
+ if (off < DRIFT_WORTH_SAYING || bytes < DRIFT_OVERHEAD_PER_CHUNK * drift.chunks) {
191
+ return [];
192
+ }
193
+ return [
194
+ {
195
+ severity: off >= DRIFT_WORTH_ACTING_ON ? 'mid' : 'info',
196
+ kind: 'splitDrift',
197
+ ...finding_text_1.TEXT[lang].splitDrift({
198
+ percent: Math.round(drift.ratio * 100),
199
+ off: Math.round(off * 100),
200
+ high: drift.ratio > 1,
201
+ chunks: drift.chunks,
202
+ file: (0, format_utils_1.formatBytes)(drift.file),
203
+ measured: (0, format_utils_1.formatBytes)(drift.measured),
204
+ }),
205
+ },
206
+ ];
207
+ };
208
+ const buildFolderFindings = (build, lang) => {
209
+ // The drift is about the metafile, not about the folder, so it is raised whichever way in was
210
+ // used and whether or not the maps are there: the early returns below are about the folder.
211
+ const drift = driftFinding(build.drift ?? null, lang);
212
+ if (build.sourceMaps > 0) {
213
+ return [
214
+ ...drift,
215
+ { severity: 'info', kind: 'sourceMaps', ...finding_text_1.TEXT[lang].sourceMaps({ count: build.sourceMaps }) },
216
+ ];
217
+ }
218
+ if (!build.derived) {
219
+ return drift;
220
+ }
221
+ /**
222
+ * The other half of the same fact, and the one nothing said out loud. A folder read without
223
+ * maps knows what a chunk weighs and not what is inside it, so every screen is named after its
224
+ * chunk file — on a real build that means rows called `0fPdmq0U`, and nothing in the report
225
+ * explained why or what to do about it. Only for a folder: a `stats.json` names every file
226
+ * whether or not the build shipped maps.
227
+ *
228
+ * It said it as context, at the bottom, in a card about source maps — and on a real Angular
229
+ * application with eighteen screens, all eighteen rows unreadable, that is the finding that
230
+ * decides whether the table can be used at all. When every row is a hash it is named as what it
231
+ * is and it stops being a footnote.
232
+ */
233
+ const unnamed = (build.screens ?? []).filter(label => unnamedScreen(label)).length;
234
+ const blind = unnamed > 0 && unnamed === (build.screens ?? []).length;
235
+ return [
236
+ ...drift,
237
+ {
238
+ severity: blind ? 'mid' : 'info',
239
+ kind: 'noSourceMaps',
240
+ ...finding_text_1.TEXT[lang].noSourceMaps({ unnamed: blind ? unnamed : 0 }),
241
+ },
242
+ ];
243
+ };
244
+ exports.buildFolderFindings = buildFolderFindings;
@@ -0,0 +1,116 @@
1
+ "use strict";
2
+ /**
3
+ * The signals that exist because somebody answered the five questions.
4
+ *
5
+ * They are the third source of facts in the report, next to what the build says and what a browser
6
+ * measured, and they are the weakest of the three: a declared answer is worth more than a guess and
7
+ * less than a measurement. Everything below is written to keep that ranking visible — who answered,
8
+ * when, and which figure came from a band rather than from a query.
9
+ *
10
+ * **What they are for.** Four claims in this report have been grey on purpose. The update cost
11
+ * shows its percentage and withholds its colour; the cascade names its topology and refuses to say
12
+ * whether it matters; the granularity signal puts two magnitudes on the table and declines to
13
+ * recommend a direction. None of that is caution for its own sake — the facts that would settle
14
+ * them are facts about a team and its users, and no folder on disk contains them. These answers
15
+ * are the only way they ever arrive.
16
+ *
17
+ * **What they must never do.** The asymmetry holds here exactly as it does for measurements, and
18
+ * harder, because the evidence is softer: an answer may raise a severity and may not lower one.
19
+ * `unknown` does nothing at all. The consequence worth stating is that a team cannot quiet this
20
+ * report by answering the questions optimistically — the most an optimistic answer buys is a
21
+ * paragraph saying the cost was priced and found small.
22
+ */
23
+ Object.defineProperty(exports, "__esModule", { value: true });
24
+ exports.buildSituationFindings = void 0;
25
+ const situation_1 = require("../situation/situation");
26
+ const finding_text_1 = require("./finding-text");
27
+ /**
28
+ * Which signal being on the report makes which question worth asking.
29
+ *
30
+ * Without this the missing-answers card is boilerplate: five questions listed on every report
31
+ * whatever it found, which is the shape of text people learn to scroll past. With it the card only
32
+ * ever names a question whose answer would change something on the page in front of them.
33
+ *
34
+ * The fifth question is the odd one: it is not tied to a signal that fires but to a **tension**
35
+ * between signals, so it is asked whenever the report is both counting round trips and weighing
36
+ * what to defer — which is when "which wait is worse" stops being academic.
37
+ */
38
+ const ASKED_BY = {
39
+ navigation: ['shared', 'prefetched', 'twinScreens'],
40
+ deploys: ['updateWeight', 'cascadeShape', 'unstableChunk'],
41
+ returning: ['updateWeight', 'cascadeShape', 'unstableChunk'],
42
+ connection: ['bootWaves', 'slowScreens', 'manyRequests', 'poolExhausted'],
43
+ priority: ['manyRequests', 'bootWaves', 'prefetched', 'slowScreens'],
44
+ };
45
+ /** The questions still open whose answer would change something on this particular report. */
46
+ const missingThatMatter = (situation, kinds) => (0, situation_1.unanswered)(situation).filter(key => ASKED_BY[key].some(kind => kinds.has(kind)));
47
+ const buildSituationFindings = (situation, findings, lang, c, today = new Date().toISOString().slice(0, 10)) => {
48
+ const text = finding_text_1.TEXT[lang];
49
+ const out = [];
50
+ const kinds = new Set(findings.map(finding => finding.kind));
51
+ // --- what was declared, and by whom ---------------------------------------------------------
52
+ // First, because it is the frame the other two are read through: a figure below is only worth
53
+ // as much as the answer it came from, and this is where the answer has its name and its date.
54
+ if ((0, situation_1.hasSituation)(situation)) {
55
+ const perWeek = (0, situation_1.invalidationsPerWeek)(situation);
56
+ out.push({
57
+ severity: 'info',
58
+ target: { tab: 'situation', key: '' },
59
+ kind: 'situationAsked',
60
+ ...text.situationAsked({
61
+ answered: (0, situation_1.answeredCount)(situation),
62
+ total: 5,
63
+ by: situation.answeredBy,
64
+ at: situation.answeredAt,
65
+ stale: (0, situation_1.isStaleSituation)(situation, today),
66
+ freshDays: situation_1.SITUATION_FRESH_DAYS,
67
+ rum: situation.rum,
68
+ // The multiplication rather than its result: somebody who disagrees with the number
69
+ // needs to see which of the two halves they disagree with.
70
+ deploys: (0, situation_1.deploysPerWeek)(situation),
71
+ returning: (0, situation_1.returningShare)(situation),
72
+ perWeek,
73
+ exposure: (0, situation_1.cascadeExposure)(situation),
74
+ breadth: (0, situation_1.sessionBreadth)(situation),
75
+ latencyMs: c.latencyMs,
76
+ }),
77
+ });
78
+ }
79
+ // --- the one question no file can answer -----------------------------------------------------
80
+ // The report refuses to give a direction on defer-versus-prefetch everywhere else, and it is
81
+ // right to: the two magnitudes trade against each other and nothing in a build folder ranks
82
+ // them. This is the answer arriving, so the direction is finally allowed to be said out loud.
83
+ if (situation.priority !== 'unknown') {
84
+ out.push({
85
+ severity: 'info',
86
+ target: { tab: 'situation', key: '' },
87
+ kind: 'situationPriority',
88
+ ...text.situationPriority({
89
+ priority: situation.priority,
90
+ breadth: (0, situation_1.sessionBreadth)(situation),
91
+ // Whether this build has anything the answer applies to. Without it the card is
92
+ // advice about somebody else's application.
93
+ prefetching: kinds.has('prefetched'),
94
+ waves: kinds.has('bootWaves') || kinds.has('slowScreens'),
95
+ }),
96
+ });
97
+ }
98
+ // --- what is still missing, and only where it would matter ------------------------------------
99
+ const missing = missingThatMatter(situation, kinds);
100
+ if (missing.length > 0) {
101
+ out.push({
102
+ severity: 'info',
103
+ target: { tab: 'situation', key: '' },
104
+ kind: 'situationMissing',
105
+ ...text.situationMissing({
106
+ keys: missing,
107
+ asks: missing.map(key => text.situationAsks[key]),
108
+ // A report where nobody has answered anything reads differently from one where two
109
+ // of the five are still open, and the opening sentence has to be the right one.
110
+ started: (0, situation_1.hasSituation)(situation),
111
+ }),
112
+ });
113
+ }
114
+ return out;
115
+ };
116
+ exports.buildSituationFindings = buildSituationFindings;
@@ -0,0 +1,204 @@
1
+ "use strict";
2
+ /** Presentation helpers and metafile path normalisation. */
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.formatDelta = exports.elidePath = exports.screenLabel = exports.SOURCE_EXTENSION = exports.ROUTE_SUFFIXES = exports.VIEW_SUFFIXES = exports.projectFolderOf = exports.chainSteps = exports.packageOf = exports.shortName = exports.baseName = exports.formatCount = exports.formatBytes = exports.setNumberLang = void 0;
5
+ const KB = 1024;
6
+ /**
7
+ * The language the figures are written in. It only decides the decimal separator, and it is set
8
+ * once from outside — by `I18nService` when the language changes, by the command when it reads
9
+ * `--lang` — because these helpers are called from everywhere and threading a language through
10
+ * every call site would touch every table in the report to move one comma.
11
+ */
12
+ const formatter = (lang) => new Intl.NumberFormat(lang, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
13
+ /** The same thing for figures that are not sizes, where two decimals would be false precision. */
14
+ const counter = (lang) => new Intl.NumberFormat(lang, { maximumFractionDigits: 1 });
15
+ const numbers = { lang: 'en', decimals: formatter('en'), counts: counter('en') };
16
+ const setNumberLang = (lang) => {
17
+ if (lang === numbers.lang) {
18
+ return;
19
+ }
20
+ numbers.lang = lang;
21
+ numbers.decimals = formatter(lang);
22
+ numbers.counts = counter(lang);
23
+ };
24
+ exports.setNumberLang = setNumberLang;
25
+ /**
26
+ * Human-readable size. Stays in kB up to the megabyte so columns compare at a glance.
27
+ *
28
+ * The step is 1024, and the label is `kB` rather than `KiB` on purpose: Angular CLI prints its
29
+ * budgets the same way, and this tool exists to be read next to those. Two labels for the same
30
+ * figure would cost more than the pedantry gains.
31
+ */
32
+ const formatBytes = (bytes) => {
33
+ if (bytes >= KB * KB) {
34
+ return `${numbers.decimals.format(bytes / KB / KB)} MB`;
35
+ }
36
+ if (bytes >= KB) {
37
+ return `${Math.round(bytes / KB)} kB`;
38
+ }
39
+ return `${bytes} B`;
40
+ };
41
+ exports.formatBytes = formatBytes;
42
+ /**
43
+ * A small figure that is not a size: releases a week, screens a session, times a week something
44
+ * gets paid for.
45
+ *
46
+ * One decimal at most, and none when the number is whole. `4.00` reads as a precision none of
47
+ * these have — most of them come from a band somebody picked out of four options — and the whole
48
+ * value of showing them is that a reader can see how rough they are.
49
+ */
50
+ const formatCount = (value) => numbers.counts.format(value);
51
+ exports.formatCount = formatCount;
52
+ /** Last segment of a path: `chunk-ABC.js`, `login.page.ts`. */
53
+ const baseName = (path) => path.split('/').pop() ?? path;
54
+ exports.baseName = baseName;
55
+ /**
56
+ * Strips the `node_modules` noise to leave the name a package is recognised by.
57
+ * pnpm adds an extra segment (`.pnpm/pkg@version/node_modules/`) that has to be skipped first.
58
+ */
59
+ const shortName = (path) => path.replace(/^.*node_modules\/\.pnpm\/[^/]+\/node_modules\//, '').replace(/^.*node_modules\//, '');
60
+ exports.shortName = shortName;
61
+ /** Name of the npm package a path belongs to, or `null` if it is project code. */
62
+ const packageOf = (path) => {
63
+ const short = (0, exports.shortName)(path);
64
+ if (short === path) {
65
+ return null;
66
+ }
67
+ const parts = short.split('/');
68
+ const head = parts[0] ?? short;
69
+ return head.startsWith('@') ? parts.slice(0, 2).join('/') : head;
70
+ };
71
+ exports.packageOf = packageOf;
72
+ /**
73
+ * An import chain as something a person reads: own files stay as paths, package files collapse to
74
+ * the package name, and consecutive steps inside the same package become one.
75
+ * `[main.ts, app.config.ts, node_modules/x/a.js, node_modules/x/b.js]` -> `[main.ts, app.config.ts, x]`
76
+ */
77
+ const chainSteps = (chain) => {
78
+ const steps = [];
79
+ for (const file of chain) {
80
+ const step = (0, exports.packageOf)(file) ?? file;
81
+ if (steps.at(-1) !== step) {
82
+ steps.push(step);
83
+ }
84
+ }
85
+ return steps;
86
+ };
87
+ exports.chainSteps = chainSteps;
88
+ /**
89
+ * Folder names that say "the project's own code starts here" rather than naming a part of it.
90
+ * They are looked for anywhere in the path, not only at the front, which is the whole point: in a
91
+ * workspace the same file is at `apps/web/src/app/features/users/x.ts`.
92
+ */
93
+ const SOURCE_ROOTS = new Set(['src', 'app', 'apps', 'lib', 'libs', 'source', 'packages', 'projects']);
94
+ /**
95
+ * Project folder a source file is attributed to: `shared/enums`, `core/services`.
96
+ *
97
+ * It used to anchor at the start of the path (`src/`, `app/` or `lib/`) and fall back to the first
98
+ * two segments. In a workspace nothing anchored, so **every** file of an application fell back to
99
+ * the same two segments — `apps/web` — and the bootstrap breakdown by folder came out as a single
100
+ * row while the signal that looks for a layer of yours in the bootstrap could not find one by
101
+ * construction. Now the anchor is the innermost source root, wherever it sits.
102
+ */
103
+ const projectFolderOf = (path) => {
104
+ const parts = path.split('/');
105
+ // The file itself never names the folder.
106
+ const dirs = parts.slice(0, -1);
107
+ if (dirs.length === 0) {
108
+ return path;
109
+ }
110
+ let start = 0;
111
+ for (const [index, part] of dirs.entries()) {
112
+ if (SOURCE_ROOTS.has(part)) {
113
+ start = index + 1;
114
+ }
115
+ }
116
+ const inside = dirs.slice(start);
117
+ if (inside.length >= 2) {
118
+ return inside.slice(0, 2).join('/');
119
+ }
120
+ // A library whose code sits right under its own root has nothing two levels deep. What names
121
+ // it is the library, which is on the other side of the root: `libs/shared/ui/src/lib/button`.
122
+ const outside = dirs.slice(0, start).filter(part => !SOURCE_ROOTS.has(part));
123
+ return [outside.at(-1), ...inside].filter(Boolean).join('/') || dirs.join('/');
124
+ };
125
+ exports.projectFolderOf = projectFolderOf;
126
+ /**
127
+ * The suffixes a framework puts between the name and the extension. One list, because two of them
128
+ * drifted apart: the screens table recognised `.view` and `.container` as views while the label
129
+ * only knew how to strip `.page` and `.component`, so a screen in `user.view.ts` was listed as
130
+ * `user.view`.
131
+ */
132
+ exports.VIEW_SUFFIXES = ['component', 'page', 'view', 'container'];
133
+ exports.ROUTE_SUFFIXES = ['route', 'routes'];
134
+ /**
135
+ * What a screen can be written in. Single-file components are here because two frameworks the tool
136
+ * says it reads write them: without `vue` and `svelte`, every screen of a Vue application was
137
+ * listed as `orders.page.vue`, extension and all.
138
+ */
139
+ exports.SOURCE_EXTENSION = '(?:[tj]sx?|vue|svelte)';
140
+ const SUFFIX = new RegExp(String.raw `\.(?:${[...exports.VIEW_SUFFIXES, ...exports.ROUTE_SUFFIXES].join('|')})\.${exports.SOURCE_EXTENSION}$`);
141
+ const EXTENSION = new RegExp(String.raw `\.${exports.SOURCE_EXTENSION}$`);
142
+ /**
143
+ * SvelteKit names a route file by its role and the route by its folder: `+page.svelte` in every
144
+ * one of them. Left alone, three screens came out as three rows called `+page.svelte`.
145
+ */
146
+ const ROLE_FILE = /^\+/;
147
+ /** Folders that are the root of the routes rather than one route: there the file name is all there is. */
148
+ const ROUTE_ROOTS = new Set(['routes', 'pages', 'app', 'src']);
149
+ /**
150
+ * Readable screen name from the file it originates from.
151
+ * `features/users/users.page.ts` -> `users`
152
+ * `src/routes/orders/+page.svelte` -> `orders`
153
+ */
154
+ const screenLabel = (source) => {
155
+ const name = (0, exports.baseName)(source).replace(SUFFIX, '').replace(EXTENSION, '') || (0, exports.baseName)(source);
156
+ if (!ROLE_FILE.test(name)) {
157
+ return name;
158
+ }
159
+ const folder = source.split('/').at(-2) ?? '';
160
+ return folder && !ROUTE_ROOTS.has(folder) ? folder : name.slice(1);
161
+ };
162
+ exports.screenLabel = screenLabel;
163
+ /**
164
+ * A path shortened to fit a table cell by dropping middle folders, never by cutting a word in two.
165
+ *
166
+ * `overflow-wrap: anywhere` was doing the shortening before, and it produced things like
167
+ * `…ICustomerSummary.interfa` / `ce.ts` — the half of the name that identifies the file split
168
+ * across two lines. Folders in the middle are the part nobody reads; the first one says where in
169
+ * the project this is and the last one says what it is, so those two are what survives.
170
+ *
171
+ * `src/app/features/customers/detail/ICustomerSummary.interface.ts`
172
+ * -> `src/…/detail/ICustomerSummary.interface.ts`
173
+ *
174
+ * The full path always goes in a `title`: this shortens what is drawn, never what is known.
175
+ */
176
+ const elidePath = (path, max = 46) => {
177
+ if (path.length <= max) {
178
+ return path;
179
+ }
180
+ const parts = path.split('/');
181
+ const [first] = parts;
182
+ // Two segments or fewer have no middle to drop, and a single long name cannot be helped here.
183
+ if (parts.length < 3 || first === undefined) {
184
+ return path;
185
+ }
186
+ // The tail grows from the end while it fits; the last segment always goes in, however long.
187
+ const tail = [];
188
+ let width = first.length + 3;
189
+ for (const part of parts.slice(1).toReversed()) {
190
+ if (tail.length > 0 && width + part.length + 1 > max) {
191
+ break;
192
+ }
193
+ tail.unshift(part);
194
+ width += part.length + 1;
195
+ }
196
+ return tail.length === parts.length - 1 ? path : [first, '…', ...tail].join('/');
197
+ };
198
+ exports.elidePath = elidePath;
199
+ /**
200
+ * A difference as it reads next to a figure: `+12 kB`, `−3 kB`, with the typographic minus.
201
+ * Zero comes out as `+0 B`; every caller that would rather say "the same" checks for it first.
202
+ */
203
+ const formatDelta = (diff) => `${diff >= 0 ? '+' : '−'}${(0, exports.formatBytes)(Math.abs(diff))}`;
204
+ exports.formatDelta = formatDelta;