skilldrop-cli 0.16.36 → 0.16.37

package/packs/frontend/skills/bundle-size-review/examples/larkspur-sparkline.md

@@ -0,0 +1,52 @@
+# Worked example: a chart library moves into the first load while the total stays flat
+
+## Input
+
+> PR #241 on larkspur-dispatch-web adds a small jobs-per-hour sparkline to the dashboard header. Our CI checks that total JS stays under 850 KB and it passed. A reviewer says the dashboard feels slower to open. Before and after webpack stats are attached (`inputs/stats-before.json`, `inputs/stats-after.json`). Did this PR make the first load heavier?
+
+## What the script printed (abridged)
+
+```bash
+python3 scripts/bundle_stats.py --compare examples/inputs/stats-before.json examples/inputs/stats-after.json --budget main=330kB
+```
+
+```text
+Chunk sizes: emitted asset bytes (after minification, before compression).
+Module and package sizes: webpack module size, before minification.
+Compressed sizes: not measured; no built files were read (pass --dist DIR after a build).
+
+All JS chunks: 812,606 B (812.6 kB) -> 810,657 B (810.7 kB) (-1,949 B); initial +492,392 B, lazy -494,341 B
+
+Initial JS per entry
+  main: 311,282 B (311.3 kB) -> 803,674 B (803.7 kB) (+492,392 B)
+
+Chunks that changed
+  reports    lazy       498,212 B ->   3,871 B (-494,341 B) changed; loaded with import() from src/routes.js
+  vendors    initial    301,412 B -> 792,840 B (+491,428 B) changed
+  main       initial      9,870 B ->  10,834 B (+964 B) changed
+
+Packages that changed (sorted by change in initial size)
+  echarts   total 503,088 B -> 503,088 B (0 B); initial 0 B -> 503,088 B (+503,088 B) changed
+      chain: src/index.js > src/App.jsx > src/components/JobsSparkline.jsx > node_modules/echarts/index.js
+  zrender   total 167,660 B -> 167,660 B (0 B); initial 0 B -> 167,660 B (+167,660 B) changed
+  moved from lazy to initial: echarts, zrender
+
+Project files (root: examples/inputs)
+  found: (none)
+  absent: package.json, .browserslistrc, bundler config (webpack/vite/rollup/esbuild config, build.mjs), lockfile
+  bundled source files not on disk here (9): src/App.jsx, ..., src/components/JobsSparkline.jsx, ...
+
+Budgets on each entry's initial JS, before -> after
+  main: budget 330,000 B (raw); before 311,282 B (PASS), after 803,674 B (OVER)
+```
+
+## Reply
+
+Yes, the reviewer is right: the first load went from 311,282 to 803,674 bytes of JavaScript (+492,392), while the total fell by 1,949 bytes, which is why the 850 KB total check passed. The new `JobsSparkline.jsx` imports echarts directly, and that pulled echarts and zrender out of the lazy `reports` chunk (498,212 → 3,871 bytes) into `vendors`, which every page loads before the first screen. Sizes are webpack's emitted files, minified and before compression; no built files were attached, so there is no compressed figure here.
+
+1. **Load the sparkline's chart code on demand.** Chain: `src/index.js` → `App.jsx` → `components/JobsSparkline.jsx` → `echarts`. Render the header without the sparkline, then `import("echarts/core")` inside the component and draw once it resolves. Check the reports page still opens its charts, and that the header doesn't jump when the sparkline appears (reserve its height).
+2. **Register only the line chart.** The bare `echarts` import brings every chart type and component; the moved modules include geo, dataZoom and bar views that a line sparkline never draws. Switch to `echarts/core` with `use([LineChart, GridComponent, CanvasRenderer])` plus what the reports page draws; open every report chart afterwards, since an unregistered type fails at runtime. Confirm the installed echarts is 5.x first (no `package.json` was attached), since `echarts/core` arrived in 5.
+
+**Guard:** a per-entry limit on `main`'s initial JavaScript would have failed this PR: webpack `performance: { hints: "error", maxEntrypointSize: 330000 }` passes today's 311,282 bytes and fails 803,674. The total-size limit can't see a lazy-to-initial move; keep it, but add the per-entry one.
+
+To confirm: whether the sparkline has to show on first paint. If it does, a plain SVG path drawn from the hourly counts needs no chart library at all.

package/packs/frontend/skills/bundle-size-review/manifest.json

@@ -0,0 +1,52 @@
+{
+  "name": "bundle-size-review",
+  "version": "0.2.0",
+  "description": "Find what makes a JavaScript bundle heavy and what can safely come out, from the bundler's stats file (webpack stats.json, an esbuild metafile, or the rollup-plugin-visualizer raw-data JSON that Vite builds use) read together with the repo around it (package.json, .browserslistrc, the lockfile, the bundler config and the source files that import the heavy modules). Gives each entry's first-load JavaScript in the exact bytes the stats record, kept apart from lazy chunks; finds whole-library imports, CommonJS packages that can't be tree-shaken, packages bundled twice and polyfills the browser targets don't need; names the import chain that pulls each module in before suggesting a removal; and, given before and after stats, says what grew, why, whether it lands in the first load and which per-entry budget would have caught it. Use when the user says \"why is our bundle so big\", \"what can we cut from the bundle\", \"review this stats.json\", \"why is lodash or moment in our bundle\", \"the bundle grew in this PR\", or \"set a bundle size budget\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "dependency-upgrade-review",
+    "pre-merge-review",
+    "rendering-strategy",
+    "web-performance-review"
+  ],
+  "tags": [
+    "frontend",
+    "bundle-size",
+    "webpack",
+    "tree-shaking",
+    "performance-budget"
+  ],
+  "permissions": {
+    "network": [
+      "registry.npmjs.org"
+    ],
+    "commands": [
+      "npx",
+      "npm",
+      "pnpm",
+      "yarn"
+    ],
+    "files": "named-paths",
+    "notes": "The script reads only the stats files it is given (or stdin), the project files next to them (package.json, .browserslistrc, the lockfile, bundler and TypeScript configs, and source files outside node_modules/dist/build, or the --root folder) and, with --dist, the built files in that folder; it writes only the -o path and makes no network calls. The instructions run the project's own bundler through npx --no to produce the stats, npm ls / pnpm why / yarn why to read versions, and npm view / npm dedupe, which reach the npm registry, to check which versions a dependent accepts and to align duplicates."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "Sizes, duplicates and what pulls each module in are computed from the bundler's stats file by its script; the judgment is which removal is safe."
+  },
+  "handoff": [
+    {
+      "to": "web-performance-review",
+      "when": "the user's real question is why the page is slow for users, with a Lighthouse or PageSpeed report in hand",
+      "purpose": "Rank fixes by how much each moves LCP, INP and CLS, of which JavaScript weight is only one cause.",
+      "fallback": "If web-performance-review is absent, say the bundle findings cover download and parse cost only, and name the Lighthouse audits (LCP element, long tasks, render-blocking resources) that would show whether JavaScript is the bottleneck."
+    }
+  ]
+}

package/packs/frontend/skills/bundle-size-review/reference.md

@@ -0,0 +1,147 @@
+# bundle-size-review reference
+
+## Producing the stats file
+
+webpack 5 (webpack-cli 4 or later writes the JSON straight to the file, so build logs cannot corrupt it):
+
+```bash
+npx --no webpack --mode production --json=stats.json
+```
+
+esbuild, from the CLI or from `esbuild.build({ metafile: true })` with `result.metafile` written to a file:
+
+```bash
+npx --no esbuild src/main.tsx --bundle --minify --splitting --format=esm --outdir=dist --metafile=meta.json
+```
+
+Vite or Rollup: add rollup-plugin-visualizer with the raw-data template, then run the normal build. `gzipSize` and `brotliSize` make the plugin record compressed sizes per module, which beats an estimate.
+
+```js
+// vite.config.js
+import { visualizer } from "rollup-plugin-visualizer";
+export default {
+  plugins: [visualizer({ filename: "stats.json", template: "raw-data", gzipSize: true, brotliSize: true })],
+};
+```
+
+Keep the built folder (`dist/`) next to the stats and pass it with `--dist`: the script then gzips the real emitted files (level 9). Without it, no compressed size is printed.
+
+## What each format carries, and what its sizes mean
+
+| Format | Detected by | Raw size of a chunk | Module size | Initial vs lazy | Importers |
+|---|---|---|---|---|---|
+| webpack stats | `assets`, `chunks`, `modules`, `entrypoints` | emitted asset bytes, after minification (`assets[].size`) | `modules[].size`, **before minification** | `chunks[].initial`; an entry's chunks are `entrypoints.<name>.chunks` | `modules[].reasons[].moduleName`, with `type` (`import()` = lazy) and `userRequest` |
+| esbuild metafile | `inputs` and `outputs` objects | `outputs[].bytes`, minified if `--minify` was on | `outputs[].inputs[].bytesInOutput`, what each input adds to that output | entry outputs have `entryPoint`; their `imports` of kind `import-statement` are initial, `dynamic-import` are lazy | `inputs[].imports[]` with `kind` and `original` |
+| rollup-plugin-visualizer raw data | `tree`, `nodeParts`, `nodeMetas` | sum of `renderedLength`, after tree-shaking, before minification unless the plugin runs after the minifier | `nodeParts[].renderedLength`, plus `gzipLength` / `brotliLength` when enabled | modules reached from an `isEntry` module by static imports are initial; `imported[].dynamic` marks lazy | `nodeMetas[].importedBy` |
+
+Consequences for the reply:
+
+- Quote these bytes exactly, in one unit system: bytes, with kB = 1000 bytes beside them. Name the kind once ("webpack module sizes, before minification"; "esbuild output bytes, minified, uncompressed").
+- A webpack stats file without `assets` has no emitted sizes: each chunk's size is the sum of its module sizes, before minification. Say so; the emitted figure comes from a build.
+- webpack module sizes and visualizer rendered lengths rank modules; they are not the download. The saving from a removal is measured by rebuilding and running `--compare`.
+- Prebuilt production files (`react-dom.production.min.js`) are already minified, so their module size is close to what ships.
+- esbuild lists `.js.map` outputs beside the code; they are not downloaded by users and stay out of every count.
+
+## Compressed sizes
+
+| Basis | Where it comes from | How to word it |
+|---|---|---|
+| built-file | the emitted files under `--dist`, gzipped at level 9 | "measured from the built files" |
+| visualizer | sum of the plugin's per-module gzip / brotli lengths | "from the visualizer"; slightly above the whole-file figure, because each module is compressed alone |
+| none | no built files and no visualizer gzip | no figure. Say how to measure it after a build: gzip the entry's `.js` files at level 9 (`gzip -9c`) and count the bytes (`wc -c`) |
+
+A ratio applied to raw bytes is a guess, and a guess in the lead line reads as a measurement. Leave it out.
+
+## Project files read around the stats
+
+The script picks the project root as the first of the stats folder, its parent and its grandparent that holds `package.json` or `.browserslistrc` (else one with `src/`), or `--root`. It prints what it found and what is absent, so a reply can say "no `.browserslistrc`, no `browserslist` field in `package.json`" only when that is what was looked for.
+
+| File | What it gives | Used for |
+|---|---|---|
+| `.browserslistrc`, `package.json` `browserslist` | browser queries (the `[production]` section when present) | polyfill check; plain `chrome >= 110` style queries resolve offline, others (`defaults`, `> 0.5%`) need `npx --no browserslist` |
+| `webpack.config.*`, `vite.config.*`, `rollup.config.*`, `build.mjs` / `build.js`, `esbuild.config.*` (root, `config/`, `scripts/`) | `target` (esbuild style `chrome110`), `performance.maxEntrypointSize` / `hints` | the targets when no browserslist exists (esbuild lowers syntax, it does not add polyfills); existing budgets |
+| `tsconfig.json` | `target` | syntax level only; it never decides polyfills |
+| `package-lock.json` / `npm-shrinkwrap.json` (v1 to v3) | installed version per install path, each package's declared ranges | versions of duplicate copies, who asks for which range, API checks before suggesting a fix |
+| `yarn.lock`, `pnpm-lock.yaml` | listed, not parsed | read versions with `yarn why` / `pnpm why` |
+| source files (outside `node_modules`, `dist`, `build`) | who imports each bundled package, namespace imports read with `X[...]`, which files use a polyfilled feature | the fix lands in a named file |
+
+The polyfill table in the script holds the first browser version with each feature native (MDN browser-compat data) for the common core-js modules. core-js sometimes keeps a polyfill longer to patch a spec bug, so a rebuild confirms each removal. A module outside the table is reported as "check by hand".
+
+## Version-correct fixes
+
+- Read the installed version before naming an API, an import path or an option. `echarts/core` exists from echarts 5; `lodash-es` named imports need an ESM-aware build; `@aws-sdk/client-*` is a different package from `aws-sdk`.
+- Never fix a duplicate by moving the app's own range down a major: that is a downgrade of the app.
+- `overrides` (npm), `pnpm.overrides` or `resolutions` (Yarn) that force a dependent onto a major it never declared is a change to test by hand, not a free removal. Check whether a newer dependent accepts the newer major, with network access:
+
+```bash
+npm view @harbor/calendar versions
+npm view @harbor/calendar@latest dependencies
+```
+
+## Reading the stats by hand
+
+When no script can run:
+
+1. **webpack:** take `entrypoints.main.assets[]` (or the `files` of each chunk in `entrypoints.main.chunks`), keep `.js`, add their `size` from `assets[]`. That is the initial raw size. Every chunk with `"initial": false` is lazy; its `origins[].moduleName` is the file that loads it.
+2. **esbuild:** start at the output whose `entryPoint` is the app entry, follow its `imports` of kind `import-statement` through `outputs`, and add the `bytes` of each. Outputs reached only through `dynamic-import` are lazy.
+3. **visualizer:** each top-level child of `tree` is an output file; add `gzipLength` over the `nodeParts` of the files the entry loads statically.
+4. **Chains:** from the module, follow its importers (`reasons`, `inputs[].imports` reversed, `importedBy`) until reaching the entry. Prefer the chain with no `import()` step: that is the one that puts it in the first load.
+
+## Replacements for the usual heavy packages
+
+| In the bundle | Change | What to check after |
+|---|---|---|
+| `lodash/lodash.js` from `import _ from "lodash"` | per-method imports (`import groupBy from "lodash/groupBy"`) or named imports from `lodash-es`; native methods where the targets have them | every importer the stats list; `_.chain(...)` usage, which needs the whole library; that Babel or TypeScript is not compiling ESM imports to `require` |
+| `moment` (and `moment/locale/*` or `moment-with-locales`) | date-fns, Day.js, Luxon or `Intl.DateTimeFormat`; to keep moment, drop the locales (webpack: `new webpack.IgnorePlugin({ resourceRegExp: /^\.\/locale$/, contextRegExp: /moment$/ })`, then import the locales in use) | moment objects mutate and the others don't; lenient parsing of non-ISO strings; time zones (moment-timezone); every locale shown to users. If a dependency imports moment, the dependency has to change, not the app |
+| `core-js` from `import "core-js/stable"` or `@babel/polyfill` | `@babel/preset-env` with `useBuiltIns: "usage"`, `corejs: 3` and the project's `browserslist`; for Vite, `@vitejs/plugin-legacy` serves polyfills only to old browsers | run `npx --no browserslist` to see the real targets; the features the polyfills cover against those targets |
+| full `echarts` from `import * as echarts from "echarts"` | `echarts/core` with `use([...])` for the charts, components and renderer in use | open every chart: a type that is not registered fails at runtime |
+| `chart.js/auto` | import the controllers, elements and scales in use and `Chart.register(...)` them | every chart type and plugin |
+| `aws-sdk` (v2) in browser code | the modular `@aws-sdk/client-*` packages | that each call's request and error shapes match the v3 client |
+| an icon pack or component library through its index | per-path imports, or confirm the package is ESM with `"sideEffects": false` so the index is shaken | the bundle after rebuild: compare with `--compare` |
+| a CommonJS package with an ESM build | point the import at the ESM entry (`module` / `exports`) | that the bundler resolves the ESM file (the stats path shows it) |
+
+## Side effects and barrel files
+
+A bundler keeps a module, used or not, when it might have side effects. `"sideEffects": false` in a package's `package.json` (or a list such as `["*.css"]`) tells it that unused re-exports can go. App code has the same problem: `src/components/index.ts` re-exporting forty components, one of which registers something at the top level, keeps all forty. Symptoms in the stats: many modules from one folder or package, all reached through one `index` file, most of them never imported by anything else.
+
+## Duplicates and package managers
+
+- npm hoists one copy to `node_modules/<pkg>` and nests another under `node_modules/<dependent>/node_modules/<pkg>` only when the hoisted version does not satisfy that dependent's range. Two install paths means two versions.
+- Versions are in the path only for pnpm (`node_modules/.pnpm/<pkg>@<version>/...`) and Yarn PnP caches. Otherwise read them:
+
+```bash
+npm ls date-fns
+pnpm why date-fns
+yarn why date-fns
+```
+
+- To get one copy when the ranges overlap: reinstall so one version satisfies both (`npm dedupe`). When they don't (the dependent wants 2.x and the app 3.x), the options are a newer dependent that accepts 3.x, or an override tested by hand; see "Version-correct fixes".
+
+```bash
+npm dedupe
+```
+
+- Two copies of React, Vue, or a state library are a bug as well as a size cost (hooks fail with "Invalid hook call", stores split). Name that when it applies.
+- The same module in several webpack chunks (not two installs, one module copied) means the split-chunks settings did not extract it to a shared chunk.
+
+## Budgets
+
+A budget is a limit on one entry's initial JavaScript, in the unit of the tool that enforces it. Set it between the good build and the bad one: the current figure plus about 5%, or the team's target. The script checks it on the stats' own bytes, or on measured gzip:
+
+```bash
+python3 scripts/bundle_stats.py stats.json --budget main=320kB
+python3 scripts/bundle_stats.py stats.json --dist dist/ --budget main=gzip:100kB
+```
+
+Exit 1 fails the job. Sizes are bytes or carry a `kB` (1000) or `KiB` (1024) suffix; `--budget '*=320kB'` applies to every entry; repeat `--budget` for several. A gzip budget with no built files is reported as not measured rather than passed.
+
+webpack's own check counts emitted bytes, minified and uncompressed, per entrypoint:
+
+```js
+// webpack.config.js
+module.exports = { performance: { hints: "error", maxEntrypointSize: 330000, maxAssetSize: 250000 } };
+```
+
+When the stats carry only module sizes (no `assets`), read the entry's emitted size from one build before fixing `maxEntrypointSize`. size-limit measures compressed size from the built files itself, so its limit is a compressed figure.
+
+A total-size limit across all chunks is the wrong guard on its own: it passes a change that moves a library from a lazy chunk into the entry (the total stays flat) and fails a change that only grows a route few users open.