imgtune 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +322 -0
  2. package/LICENSE +21 -0
  3. package/NOTICE +20 -0
  4. package/README.md +350 -2
  5. package/THIRD_PARTY_LICENSES +295 -0
  6. package/dist/address.js +221 -0
  7. package/dist/animated.js +176 -0
  8. package/dist/app-routes.js +211 -0
  9. package/dist/atomic.js +63 -0
  10. package/dist/audit.js +372 -0
  11. package/dist/backgrounds.js +363 -0
  12. package/dist/broken.js +106 -0
  13. package/dist/browser.js +30 -0
  14. package/dist/calibrate.js +221 -0
  15. package/dist/candidates.js +151 -0
  16. package/dist/check-report.js +302 -0
  17. package/dist/check.js +416 -0
  18. package/dist/cli.js +531 -0
  19. package/dist/compare.js +398 -0
  20. package/dist/concurrency.js +37 -0
  21. package/dist/config.js +10 -0
  22. package/dist/crawl.js +186 -0
  23. package/dist/deep.js +76 -0
  24. package/dist/egress-proxy.js +151 -0
  25. package/dist/encode.js +101 -0
  26. package/dist/estimate-jobs.js +114 -0
  27. package/dist/fetch.js +179 -0
  28. package/dist/ffmpeg.js +495 -0
  29. package/dist/gpu.js +353 -0
  30. package/dist/group-sizes.js +120 -0
  31. package/dist/hints.js +1102 -0
  32. package/dist/image-file.js +553 -0
  33. package/dist/images.js +361 -0
  34. package/dist/layout.js +240 -0
  35. package/dist/lcp.js +66 -0
  36. package/dist/loaders.js +267 -0
  37. package/dist/loads.js +29 -0
  38. package/dist/locate-join.js +511 -0
  39. package/dist/locate-only.js +178 -0
  40. package/dist/locate.js +382 -0
  41. package/dist/lru.js +34 -0
  42. package/dist/measure.js +238 -0
  43. package/dist/media-encode.js +1050 -0
  44. package/dist/media-file.js +284 -0
  45. package/dist/media-limits.js +31 -0
  46. package/dist/media-model.js +247 -0
  47. package/dist/media-phase.js +652 -0
  48. package/dist/media-prepare.js +31 -0
  49. package/dist/metric.js +227 -0
  50. package/dist/next-config.js +87 -0
  51. package/dist/qualities-cap.js +141 -0
  52. package/dist/recheck-rows.js +40 -0
  53. package/dist/recheck.js +376 -0
  54. package/dist/remote.js +3582 -0
  55. package/dist/report.js +253 -0
  56. package/dist/result-cache.js +183 -0
  57. package/dist/routes.js +280 -0
  58. package/dist/run.js +445 -0
  59. package/dist/search.js +88 -0
  60. package/dist/site.js +31 -0
  61. package/dist/sizes-outcome.js +81 -0
  62. package/dist/sizes-recheck.js +332 -0
  63. package/dist/sizes.js +148 -0
  64. package/dist/source-root.js +77 -0
  65. package/dist/srcset-parse.js +98 -0
  66. package/dist/srcset.js +44 -0
  67. package/dist/ssim.js +196 -0
  68. package/dist/stage.js +51 -0
  69. package/dist/summary.js +495 -0
  70. package/dist/survey.js +13 -0
  71. package/dist/text.js +72 -0
  72. package/dist/third-party.js +127 -0
  73. package/dist/timing.js +60 -0
  74. package/dist/types.js +1 -0
  75. package/dist/urls.js +300 -0
  76. package/dist/version.js +3 -0
  77. package/dist/video-analysis.js +273 -0
  78. package/dist/webp-animation.js +283 -0
  79. package/dist/worst.js +42 -0
  80. package/package.json +70 -4
  81. package/skills/imgtune/AGENTS.snippet.md +47 -0
  82. package/skills/imgtune/SKILL.md +344 -0
  83. package/skills/imgtune/reference.md +339 -0
  84. package/vendor/ssimulacra2/ssim_wasm.cjs +113 -0
  85. package/vendor/ssimulacra2/ssim_wasm.d.ts +8 -0
  86. package/vendor/ssimulacra2/ssim_wasm_bg.wasm +0 -0
  87. package/vendor/ssimulacra2/ssim_wasm_bg.wasm.d.ts +6 -0
@@ -0,0 +1,495 @@
1
+ // `imgtune summary`: the one-screen read of a run (or of scan files). The renderer is pure and never prints more than
2
+ // MAX_SUMMARY_LINES lines, so an agent decides the next step from it without opening the JSON.
3
+ import { readdir, readFile, stat } from "node:fs/promises";
4
+ import { isAbsolute, join, relative, resolve } from "node:path";
5
+ import { hintsCommand, videoTotalsLine } from "./hints.js";
6
+ import { safeText, shellWord } from "./text.js";
7
+ import { APPROX_MARK, APPROX_NOTE, pageFileName, siteNumbers, surveyLabelOf } from "./remote.js";
8
+ import { candidatesOf, patternRanking } from "./worst.js";
9
+ import { groupRoutes, parseRouteMap } from "./routes.js";
10
+ /** The phases a manifest may name: the only values a manifest's phase name can take when it is printed. */
11
+ export const PHASE_NAMES = ["survey", "deep", "locate", "hints"];
12
+ /** A plain file name in the run directory: letters, digits, dots, dashes and underscores, not starting with a dot. */
13
+ const PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
14
+ /** The modes a manifest may name: a plain run leaves `mode` out, a check or an audit writes one of these. */
15
+ const RUN_MODES = ["run", "check", "audit"];
16
+ /** The largest count a manifest may carry (pages, images, patterns): far above any real run. */
17
+ const MAX_COUNT = 1_000_000_000;
18
+ /** The most lines the summary prints. */
19
+ export const MAX_SUMMARY_LINES = 40;
20
+ /** Rows shown in each table; the rest are counted on one line. */
21
+ const PATTERN_ROWS = 3;
22
+ const DEEP_ROWS = 5;
23
+ const CALL_SITE_ROWS = 10;
24
+ const WARNING_ROWS = 3;
25
+ const NEXT_ROWS = 2;
26
+ /** Longest label printed for a page or a call site, in characters. */
27
+ const LABEL_WIDTH = 34;
28
+ const trim = (text, width) => {
29
+ const clean = safeText(text);
30
+ return clean.length <= width ? clean : `${clean.slice(0, width - 3)}...`;
31
+ };
32
+ /** A path as the reader should type it: relative to the working directory when it is inside it, else absolute. */
33
+ export function showPath(path, cwd) {
34
+ const absolute = resolve(cwd, path);
35
+ const rel = relative(cwd, absolute);
36
+ return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? absolute : rel;
37
+ }
38
+ /** The path and query of a page URL, the short label of a page in the tables. */
39
+ export function labelOf(url) {
40
+ try {
41
+ const parsed = new URL(url);
42
+ return `${parsed.pathname}${parsed.search}`;
43
+ }
44
+ catch {
45
+ return url;
46
+ }
47
+ }
48
+ const kbText = (kb) => kb.toFixed(1);
49
+ const pctText = (value) => `${value.toFixed(1)}%`;
50
+ /** The lines of the summary, capped at MAX_SUMMARY_LINES (the row limits keep it under the cap; the cap is the backstop). */
51
+ export function renderSummary(input) {
52
+ const lines = [safeText(input.heading)];
53
+ if (input.out !== undefined)
54
+ lines.push(`out: ${safeText(input.out)}`);
55
+ if (input.timings.length > 0) {
56
+ const total = input.timings.reduce((sum, t) => sum + t.seconds, 0);
57
+ const parts = input.timings.map((t) => `${safeText(t.name)} ${t.seconds.toFixed(0)} s`).join(", ");
58
+ lines.push(`time: ${total.toFixed(0)} s total (${parts})`);
59
+ }
60
+ // The media phase's note is printed once, at the top (the same note is on each page that has media).
61
+ const media = [...(input.survey ?? []), ...input.deep].find((p) => p.mediaNote !== undefined)?.mediaNote;
62
+ if (media !== undefined)
63
+ lines.push(safeText(media));
64
+ lines.push("");
65
+ if (input.stop !== undefined) {
66
+ lines.push(`STOPPED before the deep phase: ${safeText(input.stop.reason)}`, ` fix: ${safeText(input.stop.fix)}`, "");
67
+ }
68
+ if (input.survey !== undefined)
69
+ lines.push(...surveyBlock(input.survey, input.surveyLabel, input.routes), "");
70
+ else if (input.surveyLabel !== undefined)
71
+ lines.push(safeText(input.surveyLabel), "");
72
+ if (input.deep.length > 0)
73
+ lines.push(...deepBlock(input.deep), "");
74
+ const withVideo = input.deep.filter((p) => p.status === "ok" && (p.videos ?? []).length > 0);
75
+ if (withVideo.length > 0)
76
+ lines.push(...videoBlock(withVideo), "");
77
+ if (input.callSites !== undefined)
78
+ lines.push(...callSiteBlock(input.callSites), "");
79
+ if (input.warnings.length > 0)
80
+ lines.push(...listBlock("warnings", input.warnings, WARNING_ROWS), "");
81
+ if (input.next.length > 0)
82
+ lines.push(...listBlock("next", input.next, NEXT_ROWS));
83
+ while (lines.length > 0 && lines[lines.length - 1] === "")
84
+ lines.pop();
85
+ if (lines.length > MAX_SUMMARY_LINES) {
86
+ const cut = lines.length - (MAX_SUMMARY_LINES - 1);
87
+ return `${[...lines.slice(0, MAX_SUMMARY_LINES - 1), `... ${cut} line(s) cut: the JSON files have the rest`].join("\n")}\n`;
88
+ }
89
+ return `${lines.join("\n")}\n`;
90
+ }
91
+ /** The survey: its page counts, the label (exact only), the site totals, and the worst route patterns. */
92
+ function surveyBlock(survey, label, routes) {
93
+ const grouping = routes ?? groupRoutes(survey.map((p) => p.url));
94
+ const ok = survey.filter((p) => p.status === "ok" && p.page !== undefined);
95
+ const count = (status) => survey.filter((p) => p.status === status).length;
96
+ const broken = count("broken");
97
+ const failed = count("failed");
98
+ const other = survey.length - ok.length - broken - failed;
99
+ const lines = [`survey: ${survey.length} page(s), ${ok.length} ok, ${broken} broken, ${failed} failed, ${other} not measured`];
100
+ if (label !== undefined)
101
+ lines.push(` ${safeText(label.replace(/^survey: /, ""))}`);
102
+ const numbers = ok.map((p) => p.page);
103
+ lines.push(numbers.length === 0
104
+ ? " site: no page measured"
105
+ : ` site (${numbers.length} ok, mean): image KB/view ${kbText(siteNumbers(numbers).meanImageBytes / 1024)} · exact ${pctText(siteNumbers(numbers).exactPct)} · exact + est. ${pctText(siteNumbers(numbers).exactEstPct)}${siteNumbers(numbers).estApprox === true ? APPROX_MARK : ""}`);
106
+ const ranks = patternRanking(candidatesOf(survey, grouping.typeOf));
107
+ if (ranks.length > 0) {
108
+ const shown = Math.min(PATTERN_ROWS, ranks.length);
109
+ lines.push(` worst route types (mean exact KB/view per page, ${shown} of ${ranks.length} shown):`);
110
+ for (const rank of ranks.slice(0, PATTERN_ROWS)) {
111
+ lines.push(` ${trim(rank.pattern, 22).padEnd(22)} ${String(rank.pages).padStart(3)} page(s) ${kbText(rank.meanExactKB).padStart(6)} KB worst ${trim(labelOf(rank.worst.url), 30)}`);
112
+ }
113
+ }
114
+ return lines;
115
+ }
116
+ /** The full-scan pages, worst first by exact KB per view. */
117
+ function deepBlock(deep) {
118
+ const ok = deep.filter((p) => p.status === "ok" && p.page !== undefined);
119
+ const sorted = [...ok].sort((a, b) => exactOf(b) - exactOf(a) || a.url.localeCompare(b.url));
120
+ const shown = Math.min(DEEP_ROWS, sorted.length);
121
+ const failed = deep.filter((p) => p.status === "failed").length;
122
+ const lines = [`deep: ${deep.length} page(s) full-scanned, ${ok.length} ok, ${failed} failed (${shown} of ${ok.length} shown, worst first)`];
123
+ if (sorted.length === 0)
124
+ return lines;
125
+ lines.push(` ${"page".padEnd(LABEL_WIDTH)} ${"KB/view".padStart(8)} ${"exact".padStart(7)} ${"exact+est".padStart(10)} ${"sharp KB".padStart(9)}`);
126
+ for (const page of sorted.slice(0, DEEP_ROWS)) {
127
+ const n = page.page;
128
+ lines.push(` ${trim(labelOf(page.url), LABEL_WIDTH).padEnd(LABEL_WIDTH)} ${kbText(n.meanImageBytes / 1024).padStart(8)} ${pctText(n.exactPct).padStart(7)} ${(pctText(n.exactEstPct) + (n.estApprox === true ? APPROX_MARK : "")).padStart(10)} ${`+${n.sharpnessKB.toFixed(1)}`.padStart(9)}`);
129
+ }
130
+ if (sorted.slice(0, DEEP_ROWS).some((page) => page.page.estApprox === true))
131
+ lines.push(` ${APPROX_NOTE}`);
132
+ return lines;
133
+ }
134
+ const exactOf = (page) => {
135
+ const n = page.page;
136
+ return (n.meanImageBytes * n.exactPct) / 100;
137
+ };
138
+ /** The deep pages with a `<video>`: one line each, the page's video totals (per view, per play, saveable est.). */
139
+ function videoBlock(pages) {
140
+ const shown = Math.min(DEEP_ROWS, pages.length);
141
+ const lines = [`videos: ${pages.length} deep page(s) with <video> (${shown} of ${pages.length} shown)`];
142
+ for (const page of pages.slice(0, DEEP_ROWS)) {
143
+ lines.push(` ${trim(labelOf(page.url), LABEL_WIDTH).padEnd(LABEL_WIDTH)} ${videoTotalsLine(page.videos ?? []) ?? ""}`);
144
+ }
145
+ return lines;
146
+ }
147
+ function callSiteBlock(sites) {
148
+ if (sites.length === 0)
149
+ return ["call sites by saving per view: none (no deep page has a fix hint)"];
150
+ const lines = [`call sites by saving per view (top ${Math.min(CALL_SITE_ROWS, sites.length)} of ${sites.length}):`];
151
+ sites.slice(0, CALL_SITE_ROWS).forEach((site, index) => {
152
+ const saved = `${(site.saved / 1024).toFixed(1)} KB`.padStart(9);
153
+ const where = site.file !== undefined
154
+ ? `${trim(`${site.file}:${site.line ?? 0}`, 52)}${site.component !== undefined ? ` (${trim(site.component, 20)})` : ""}`
155
+ : `not located: ${trim(site.reason ?? "no source found", 60)}`;
156
+ lines.push(` ${String(index + 1).padStart(2)}. ${saved} ${where} ${site.count} img, ${site.pages} page(s)`);
157
+ });
158
+ return lines;
159
+ }
160
+ /** A titled list: the count in the title, and only the first `limit` rows. */
161
+ function listBlock(title, rows, limit) {
162
+ const head = rows.length > limit ? `${title} (${rows.length}, first ${limit} shown):` : `${title}:`;
163
+ return [head, ...rows.slice(0, limit).map((row) => ` ${trim(row, 150)}`)];
164
+ }
165
+ // ---------------------------------------------------------------------------------------------------------------------
166
+ // Loading: a run directory (run.json, survey/, deep/, located/, hints.json) or a list of scan files
167
+ // ---------------------------------------------------------------------------------------------------------------------
168
+ /** The page JSON files of a folder: the ones that hold a scan result (a url and an image list). */
169
+ export async function readPages(dir) {
170
+ let names;
171
+ try {
172
+ names = (await readdir(dir)).filter((name) => name.endsWith(".json") && !name.endsWith(".located.json") && name !== "hints.json").sort();
173
+ }
174
+ catch {
175
+ return [];
176
+ }
177
+ const pages = [];
178
+ for (const name of names) {
179
+ const page = await readPageFile(join(dir, name));
180
+ // A page without the completeness marker is an interrupted run's: its media results are not in yet (see remote.ts).
181
+ if (page.complete === true)
182
+ pages.push(page);
183
+ }
184
+ return pages;
185
+ }
186
+ async function readPageFile(file) {
187
+ let parsed;
188
+ try {
189
+ parsed = JSON.parse(await readFile(file, "utf8"));
190
+ }
191
+ catch (err) {
192
+ throw new Error(`cannot read ${safeText(file)} as a scan file: ${err.message}`);
193
+ }
194
+ const page = parsed;
195
+ if (page === null || typeof page !== "object" || typeof page.url !== "string" || !Array.isArray(page.images)) {
196
+ throw new Error(`${safeText(file)} is not a scan file (no url and image list)`);
197
+ }
198
+ return page;
199
+ }
200
+ async function exists(path) {
201
+ try {
202
+ await stat(path);
203
+ return true;
204
+ }
205
+ catch {
206
+ return false;
207
+ }
208
+ }
209
+ /** Reads the call sites of the pages' scan files (the grouped hints, worst first). */
210
+ async function callSitesOf(files, cwd, qualities) {
211
+ const argv = [...files, "--format", "json"];
212
+ if (qualities !== undefined)
213
+ argv.push("--qualities", qualities);
214
+ const { output } = await hintsCommand(argv, cwd);
215
+ return callSitesFromJson(output);
216
+ }
217
+ /** The call sites of the hints JSON (the `callSites` of `hints --format json`). */
218
+ export function callSitesFromJson(text) {
219
+ const body = JSON.parse(text);
220
+ return (body.callSites ?? []).map((site) => {
221
+ const out = { saved: site.saved, count: site.count, pages: site.pages.length };
222
+ if (typeof site.file === "string") {
223
+ out.file = site.file;
224
+ out.line = typeof site.line === "number" ? site.line : 0;
225
+ }
226
+ else {
227
+ const find = site.hints?.[0]?.find;
228
+ out.reason = find !== undefined ? `search ${find.component} in ${find.glob}` : "no source found";
229
+ }
230
+ if (site.component?.[0] !== undefined)
231
+ out.component = site.component[0];
232
+ return out;
233
+ });
234
+ }
235
+ /** The warnings the pages themselves carry: broken pages by kind, and pages that were not measured, by status. */
236
+ function pageWarnings(label, pages) {
237
+ const warnings = [];
238
+ const broken = pages.filter((p) => p.status === "broken" && p.broken !== undefined);
239
+ const byKind = new Map();
240
+ for (const page of broken) {
241
+ const info = page.broken;
242
+ const entry = byKind.get(info.kind);
243
+ if (entry)
244
+ entry.n++;
245
+ else
246
+ byKind.set(info.kind, { reason: info.reason, fix: info.fix, n: 1 });
247
+ }
248
+ for (const entry of byKind.values())
249
+ warnings.push(`${label}: ${entry.n} page(s) broken: ${entry.reason}`);
250
+ const notMeasured = new Map();
251
+ for (const page of pages) {
252
+ if (page.status === "ok" || page.status === "broken")
253
+ continue;
254
+ notMeasured.set(page.status, (notMeasured.get(page.status) ?? 0) + 1);
255
+ }
256
+ if (notMeasured.size > 0) {
257
+ const detail = [...notMeasured].map(([status, n]) => `${n} ${status}`).join(", ");
258
+ warnings.push(`${label}: not measured: ${detail}`);
259
+ }
260
+ const robotsIgnored = pages.filter((p) => p.robotsIgnored === true).length;
261
+ if (robotsIgnored > 0)
262
+ warnings.push(`${label}: ${robotsIgnored} page(s) scanned past robots.txt (--ignore-robots)`);
263
+ return warnings;
264
+ }
265
+ /** The located pages' gaps: flagged images with no file:line, by the page's locate summary. */
266
+ async function locateWarnings(dir) {
267
+ const warnings = [];
268
+ let names;
269
+ try {
270
+ names = (await readdir(join(dir, "located"))).filter((name) => name.endsWith(".json")).sort();
271
+ }
272
+ catch {
273
+ return warnings;
274
+ }
275
+ for (const name of names) {
276
+ const page = await readPageFile(join(dir, "located", name));
277
+ const locate = page.locate;
278
+ if (locate === undefined || locate.notJoined === 0)
279
+ continue;
280
+ const reasons = Object.entries(locate.reasons).map(([code, n]) => `${n} ${code}`).join(", ");
281
+ warnings.push(`located ${labelOf(page.url)}: ${locate.notJoined} of ${locate.flagged} flagged image(s) not located (${reasons})`);
282
+ }
283
+ return warnings;
284
+ }
285
+ /** `imgtune summary <dir|scan files...> [--qualities list]`: the arguments after `summary`. */
286
+ export async function summaryCommand(argv, cwd) {
287
+ let qualities;
288
+ const paths = [];
289
+ for (let i = 0; i < argv.length; i++) {
290
+ if (argv[i] === "--qualities") {
291
+ const value = argv[i + 1];
292
+ if (value === undefined || value.startsWith("--"))
293
+ throw new Error("--qualities needs a list, e.g. 75,85,100");
294
+ qualities = value;
295
+ i++;
296
+ }
297
+ else if (argv[i].startsWith("--")) {
298
+ throw new Error(`Unknown option ${safeText(argv[i])} (usage: imgtune summary <run dir | scan.json ...> [--qualities list])`);
299
+ }
300
+ else {
301
+ paths.push(argv[i]);
302
+ }
303
+ }
304
+ if (paths.length === 0)
305
+ throw new Error("usage: imgtune summary <run dir | scan.json ...> [--qualities list]");
306
+ const first = resolve(cwd, paths[0]);
307
+ const isDir = paths.length === 1 && (await stat(first).then((s) => s.isDirectory(), () => false));
308
+ if (isDir && (await exists(join(first, "run.json")))) {
309
+ // The exit code is the run's own (its manifest), so a summary and the run that wrote it agree.
310
+ const { input, exitCode } = await runDirInput(first, cwd);
311
+ return { output: renderSummary(input), exitCode };
312
+ }
313
+ let files = paths.map((p) => resolve(cwd, p));
314
+ if (isDir) {
315
+ files = (await readdir(first)).filter((n) => n.endsWith(".json") && n !== "hints.json").sort().map((n) => join(first, n));
316
+ if (files.length === 0)
317
+ throw new Error(`${safeText(paths[0])} has no scan files and no run.json`);
318
+ }
319
+ return { output: renderSummary(await scanFilesInput(files, cwd, qualities)), exitCode: 0 };
320
+ }
321
+ async function runDirInput(dir, cwd) {
322
+ const manifestFile = join(dir, "run.json");
323
+ const manifest = parseManifest(await readFile(manifestFile, "utf8"), manifestFile);
324
+ const survey = (await exists(join(dir, "survey"))) ? await readPages(join(dir, "survey")) : undefined;
325
+ const deep = (await exists(join(dir, "deep"))) ? await readPages(join(dir, "deep")) : [];
326
+ const routeMap = manifest.options.routeMap !== undefined ? parseRouteMap(await readFile(resolve(cwd, manifest.options.routeMap), "utf8")) : [];
327
+ const routes = survey !== undefined ? groupRoutes(survey.map((p) => p.url), { routeMap }) : undefined;
328
+ const warnings = [];
329
+ if (survey !== undefined)
330
+ warnings.push(...pageWarnings("survey", survey));
331
+ warnings.push(...pageWarnings("deep", deep));
332
+ warnings.push(...(await locateWarnings(dir)));
333
+ warnings.push(...(manifest.warnings ?? []));
334
+ // Every value in a printed command is quoted (shellWord): an agent pastes these lines.
335
+ const qualities = manifest.options.qualities !== undefined ? ` --qualities ${shellWord(manifest.options.qualities.join(","))}` : "";
336
+ const next = [];
337
+ if (manifest.stop != null) {
338
+ next.push(`after the fix, run again: imgtune run --urls-from ${shellWord(showPath(join(dir, manifest.urls.file), cwd))} --out <new dir>`);
339
+ }
340
+ else if (deep.some((p) => p.status === "ok")) {
341
+ const located = (await exists(join(dir, "located"))) && (await readdir(join(dir, "located"))).some((n) => n.endsWith(".json"));
342
+ if (located) {
343
+ next.push(`imgtune hints ${shellWord(showPath(join(dir, "located"), cwd))}/*.json --limit 10${qualities}`);
344
+ }
345
+ else {
346
+ // The worst deep page, the one the table shows first (scan order is not the worst order).
347
+ const worst = [...deep.filter((p) => p.status === "ok" && p.page !== undefined)].sort((a, b) => exactOf(b) - exactOf(a))[0];
348
+ next.push(`locate: imgtune scan <dev-url> --locate-only --from ${shellWord(showPath(join(dir, "deep", pageFileName(new URL(worst.url))), cwd))}`);
349
+ next.push(`imgtune hints ${shellWord(showPath(join(dir, "deep"), cwd))}/*.json --limit 10${qualities}`);
350
+ }
351
+ }
352
+ const hintsFile = join(dir, "hints.json");
353
+ const callSites = (await exists(hintsFile)) ? callSitesFromJson(await readFile(hintsFile, "utf8")) : undefined;
354
+ const input = {
355
+ heading: `imgtune run: ${manifest.urls.count} URL(s), ${manifest.urls.types} route type(s), exit ${manifest.exitCode}`,
356
+ out: showPath(dir, cwd),
357
+ timings: manifest.phases.map((p) => ({ name: p.name, seconds: p.seconds })),
358
+ surveyLabel: survey !== undefined ? surveyLabelOf(survey) : undefined,
359
+ survey,
360
+ routes,
361
+ deep,
362
+ callSites,
363
+ stop: manifest.stop ?? undefined,
364
+ warnings,
365
+ next,
366
+ };
367
+ return { input, exitCode: manifest.exitCode };
368
+ }
369
+ async function scanFilesInput(files, cwd, qualities) {
370
+ const pages = [];
371
+ for (const file of files)
372
+ pages.push(await readPageFile(resolve(cwd, file)));
373
+ const callSites = await callSitesOf(files, cwd, qualities);
374
+ const next = [
375
+ `imgtune hints ${files.map((f) => shellWord(showPath(f, cwd))).join(" ")} --limit 10${qualities ? ` --qualities ${shellWord(qualities)}` : ""}`,
376
+ ];
377
+ return {
378
+ heading: `imgtune summary: ${pages.length} scan file(s)`,
379
+ timings: [],
380
+ surveyLabel: surveyLabelOf(pages),
381
+ deep: pages,
382
+ callSites,
383
+ warnings: pageWarnings("scan", pages),
384
+ next,
385
+ };
386
+ }
387
+ function bad(file, field, why) {
388
+ throw new Error(`${safeText(file)} is not a valid run manifest: ${field} ${why}`);
389
+ }
390
+ function objectOf(value, file, field) {
391
+ if (typeof value !== "object" || value === null || Array.isArray(value))
392
+ bad(file, field, "must be an object");
393
+ return value;
394
+ }
395
+ function integerOf(value, file, field, min, max) {
396
+ if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
397
+ bad(file, field, `must be a whole number from ${min} to ${max}`);
398
+ }
399
+ return value;
400
+ }
401
+ function numberOf(value, file, field) {
402
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
403
+ bad(file, field, "must be a number of at least 0");
404
+ return value;
405
+ }
406
+ function stringOf(value, file, field) {
407
+ if (typeof value !== "string")
408
+ bad(file, field, "must be a string");
409
+ return value;
410
+ }
411
+ /**
412
+ * Parses and checks a run.json. A field the summary prints or puts in a command is checked here: qualities are whole numbers,
413
+ * urls.file and report are plain names in the run directory (no path, no `..`), counts and exitCode are numbers, phase names are
414
+ * known, mode is one of the run modes, and each deepLeftOut entry has a type, a page count, a size and a known reason.
415
+ * Anything else is an error that names the field, so nothing unchecked reaches the terminal or a pasted command.
416
+ */
417
+ export function parseManifest(text, file) {
418
+ let parsed;
419
+ try {
420
+ parsed = JSON.parse(text);
421
+ }
422
+ catch {
423
+ throw new Error(`${safeText(file)} is not JSON`);
424
+ }
425
+ const root = objectOf(parsed, file, "the file");
426
+ if (root.tool !== "imgtune")
427
+ bad(file, "tool", 'must be "imgtune"');
428
+ const urls = objectOf(root.urls, file, "urls");
429
+ const fileName = stringOf(urls.file, file, "urls.file");
430
+ if (!PLAIN_NAME.test(fileName) || fileName.includes(".."))
431
+ bad(file, "urls.file", "must be a plain file name in the run directory");
432
+ integerOf(urls.count, file, "urls.count", 0, MAX_COUNT);
433
+ integerOf(urls.types, file, "urls.types", 0, MAX_COUNT);
434
+ const options = objectOf(root.options, file, "options");
435
+ if (options.qualities !== undefined) {
436
+ if (!Array.isArray(options.qualities) || options.qualities.length === 0)
437
+ bad(file, "options.qualities", "must be a list of whole numbers");
438
+ for (const quality of options.qualities)
439
+ integerOf(quality, file, "options.qualities", 1, 100);
440
+ }
441
+ integerOf(root.exitCode, file, "exitCode", 0, 255);
442
+ if (!Array.isArray(root.phases))
443
+ bad(file, "phases", "must be a list");
444
+ for (const phase of root.phases) {
445
+ const entry = objectOf(phase, file, "phases[]");
446
+ if (!PHASE_NAMES.includes(entry.name))
447
+ bad(file, "phases[].name", `must be one of ${PHASE_NAMES.join(", ")}`);
448
+ numberOf(entry.seconds, file, "phases[].seconds");
449
+ for (const key of ["pages", "ok", "broken", "failed", "exitCode"])
450
+ if (entry[key] !== undefined)
451
+ numberOf(entry[key], file, `phases[].${key}`);
452
+ }
453
+ if (root.deepRetries !== undefined) {
454
+ if (!Array.isArray(root.deepRetries))
455
+ bad(file, "deepRetries", "must be a list");
456
+ for (const retry of root.deepRetries) {
457
+ const entry = objectOf(retry, file, "deepRetries[]");
458
+ stringOf(entry.type, file, "deepRetries[].type");
459
+ stringOf(entry.failed, file, "deepRetries[].failed");
460
+ stringOf(entry.replacement, file, "deepRetries[].replacement");
461
+ }
462
+ }
463
+ if (root.stop !== null && root.stop !== undefined) {
464
+ const stop = objectOf(root.stop, file, "stop");
465
+ stringOf(stop.phase, file, "stop.phase");
466
+ stringOf(stop.reason, file, "stop.reason");
467
+ stringOf(stop.fix, file, "stop.fix");
468
+ }
469
+ if (root.warnings !== undefined) {
470
+ if (!Array.isArray(root.warnings))
471
+ bad(file, "warnings", "must be a list of strings");
472
+ for (const warning of root.warnings)
473
+ stringOf(warning, file, "warnings[]");
474
+ }
475
+ if (root.mode !== undefined && !RUN_MODES.includes(root.mode))
476
+ bad(file, "mode", 'must be "run", "check" or "audit"');
477
+ if (root.site !== undefined)
478
+ stringOf(root.site, file, "site");
479
+ if (root.report !== undefined) {
480
+ const report = stringOf(root.report, file, "report");
481
+ if (!PLAIN_NAME.test(report) || report.includes(".."))
482
+ bad(file, "report", "must be a plain file name in the run directory");
483
+ }
484
+ if (!Array.isArray(root.deepLeftOut))
485
+ bad(file, "deepLeftOut", "must be a list");
486
+ for (const left of root.deepLeftOut) {
487
+ const entry = objectOf(left, file, "deepLeftOut[]");
488
+ stringOf(entry.type, file, "deepLeftOut[].type");
489
+ integerOf(entry.pages, file, "deepLeftOut[].pages", 0, MAX_COUNT);
490
+ numberOf(entry.typeKbPerView, file, "deepLeftOut[].typeKbPerView");
491
+ if (entry.reason !== "cap" && entry.reason !== "no-images")
492
+ bad(file, "deepLeftOut[].reason", 'must be "cap" or "no-images"');
493
+ }
494
+ return root;
495
+ }
package/dist/survey.js ADDED
@@ -0,0 +1,13 @@
1
+ // The `--survey` preset: a fast site-wide pass over many pages. It measures two viewports, skips the quality estimate, scans
2
+ // four pages at once and caps the network-idle wait at 3 s. Its numbers are exact savings only, so its results are labelled
3
+ // wherever they are printed, and `compare` and `report` never mix them with a full scan.
4
+ /** The viewports a survey measures, unless --viewports names others. */
5
+ export const SURVEY_VIEWPORTS = ["iphone-15", "desktop"];
6
+ /** Pages in flight at once in a survey, unless --page-concurrency says otherwise. */
7
+ export const SURVEY_PAGE_CONCURRENCY = 4;
8
+ /** The network-idle cap of a survey, unless --idle-timeout says otherwise. */
9
+ export const SURVEY_IDLE_TIMEOUT_MS = 3_000;
10
+ /** The label of a survey result: its viewport count, exact savings only, and no estimate. */
11
+ export function surveyNote(viewports) {
12
+ return `survey: ${viewports} ${viewports === 1 ? "viewport" : "viewports"}, exact savings only, no est.`;
13
+ }
package/dist/text.js ADDED
@@ -0,0 +1,72 @@
1
+ // Text that goes to the terminal, a file or a Markdown comment: control characters removed and length capped
2
+ // (safeText), and the escapes that stop page-derived text from formatting, linking or mentioning (mdText, mdCode).
3
+ // Page text is untrusted: every path that prints it goes through one of these.
4
+ // C0 and C1 controls, bidi embeddings, overrides and isolates, zero-width marks and the BOM: none of them may reach a reader
5
+ // of page-derived text (a bidi override reorders what follows it on screen).
6
+ const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g;
7
+ /** An ANSI escape sequence (a colour or cursor code): ESC, the parameter bytes, the final byte. Removed whole, not just ESC. */
8
+ const ANSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]/g;
9
+ const TEXT_LIMIT = 200;
10
+ /**
11
+ * Page-derived text as it may be printed: ANSI escape sequences and C0 and C1 control characters removed (no escape
12
+ * sequence reaches the terminal, and none leaves its parameters behind), and at most TEXT_LIMIT characters, the last
13
+ * three of them "...". JSON output is not passed through here.
14
+ */
15
+ export function stripControls(text) {
16
+ return text.replace(ANSI_SEQUENCE, "").replace(CONTROL_CHARS, "");
17
+ }
18
+ /**
19
+ * The first non-empty line of an error message, as it may be printed in a report or a terminal line. A browser error
20
+ * carries more: Playwright adds a "Call log:" block of lines with ANSI colour codes, which a one-line report cannot hold.
21
+ * The full message stays in the page's JSON.
22
+ */
23
+ export function errorLine(text, limit = TEXT_LIMIT) {
24
+ const first = text.split(/\r?\n/).find((line) => line.trim() !== "") ?? "";
25
+ return safeText(first.trim(), limit);
26
+ }
27
+ export function safeText(text, limit = TEXT_LIMIT) {
28
+ const clean = stripControls(text);
29
+ return clean.length > limit ? `${clean.slice(0, limit - 3)}...` : clean;
30
+ }
31
+ /** Markdown-significant characters of plain text, replaced by HTML entities so they cannot format, link or mention. */
32
+ const MD_ENTITIES = {
33
+ "&": "&amp;",
34
+ "<": "&lt;",
35
+ ">": "&gt;",
36
+ "[": "&#91;",
37
+ "]": "&#93;",
38
+ "`": "&#96;",
39
+ "*": "&#42;",
40
+ _: "&#95;",
41
+ "|": "&#124;",
42
+ "\\": "&#92;",
43
+ "@": "&#64;",
44
+ "#": "&#35;",
45
+ "~": "&#126;",
46
+ "$": "&#36;",
47
+ ":": "&#58;",
48
+ };
49
+ /**
50
+ * Plain text for a Markdown cell or list line, for text this module writes itself: control characters removed, then
51
+ * escaped. The colon and the "www." prefix are escaped too, so GitHub does not autolink a URL typed in a page's text.
52
+ */
53
+ export function mdText(text, limit) {
54
+ return safeText(text, limit).replace(/www\.|[&<>[\]`*_|\\@#~$:]/gi, (match) => (match === "." || match.toLowerCase() === "www." ? "www&#46;" : MD_ENTITIES[match]));
55
+ }
56
+ /**
57
+ * Page-derived text as an inline code span. A code span does not autolink, mention, link or format its content, so
58
+ * this is what every page-derived field uses. Inside: backticks become an apostrophe-like modifier, `<` becomes a
59
+ * single-angle quote (no HTML comment can open), and pipes are escaped so the table cell does not split.
60
+ */
61
+ export function mdCode(text) {
62
+ const clean = safeText(text).replace(/`/g, "ʼ").replace(/</g, "‹").replace(/\|/g, "\\|");
63
+ return `\`${clean === "" ? "-" : clean}\``;
64
+ }
65
+ /**
66
+ * A shell word for a printed command: the text as it is when it has only characters a shell reads literally, else
67
+ * single-quoted with each embedded quote closed, escaped and reopened. Every path or value a printed command interpolates
68
+ * goes through this, so a name in a run directory or a manifest cannot run anything when an agent pastes the command.
69
+ */
70
+ export function shellWord(text) {
71
+ return /^[A-Za-z0-9_@%+=:,./-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
72
+ }