diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index df18e473..77b1a097 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,12 +72,12 @@ jobs: - name: build working-directory: ui run: npm ci && npm run build - # Advisories for what ships (the dashboard's runtime dependencies): a - # warning here, required in the release workflow. + # Advisories for what ships (the packages with code in the dashboard's + # bundle, ADR-0111): a warning here, required in the release workflow. - name: npm audit working-directory: ui continue-on-error: true - run: npm audit --omit=dev + run: node scripts/audit-shipped.mjs - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: ui-dist diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1c93ab87..99d71abf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -57,10 +57,11 @@ jobs: - name: dashboard working-directory: ui run: npm ci && npm run build - # What ships has no known advisory (a warning in ci, required here). + # What ships has no known advisory (a warning in ci, required here): + # the packages with code in the bundle (ADR-0111). - name: npm audit working-directory: ui - run: npm audit --omit=dev + run: node scripts/audit-shipped.mjs - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: ui-dist diff --git a/.gitignore b/.gitignore index 5cd8242d..47caf3dd 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ # No trailing slash: a lane's linked node_modules (a symlink) is ignored too. node_modules /ui/dist/ +/ui/bundle-packages.json .devstack/ *.stackdump .env diff --git a/docs/adr/0111-the-dashboards-advisory-gate-counts-what-the-bundle-holds.md b/docs/adr/0111-the-dashboards-advisory-gate-counts-what-the-bundle-holds.md new file mode 100644 index 00000000..909236a3 --- /dev/null +++ b/docs/adr/0111-the-dashboards-advisory-gate-counts-what-the-bundle-holds.md @@ -0,0 +1,76 @@ +# ADR-0111: The dashboard's advisory gate counts what the bundle holds + +- **Status:** Accepted (card in the pull request); built +- **Date:** 2026-11-17 +- **Deciders:** project owner +- **Related:** [ADR-0006](0006-dashboard-vue-same-origin.md) (the dashboard), [ADR-0021](0021-a-hub-serves-the-dashboard.md) (the hub embeds it), `docs/releasing.md` ("No known advisory") + +## Context + +The release workflow refused a release whose dashboard dependencies had a +known advisory: `npm audit --omit=dev` in `ui/`, a warning in CI and +required in the release. On 2026-11-17 the tag `v0.49.0` failed there: an +advisory for picomatch (GHSA-fc5q-39xc-vjpf, every version, no fix yet) +reached the dashboard's "runtime" tree because vue-router 5 lists picomatch, +vite and unplugin as `dependencies` for its build plugin (file-based +routing). None of them has code in the bundle the hub embeds. npm cannot +tell the two apart (`--omit=peer` and `--omit=optional` change nothing), so +the gate refused what does not ship, with no way out but waiting for the +advisory's fix. + +## Decision + +The owner approved the review card in the conversation on **2026-11-17**: +points 2 to 4, and point 1 in a second form (1′) after the first proved +not to hold. + +| # | Category | Point | Beats | Reversing costs | +|---|---|---|---|---| +| 1′ | trust | "Shipped" is a package with code in the built bundle: a Vite plugin writes the packages whose modules Rollup puts into the bundle to `ui/bundle-packages.json` (outside `dist`) at `npm run build`; the gate refuses an advisory only for a package on that list; no list fails the gate. | Counting `npm ls --omit=dev` (build plugins a package lists as a dependency count); a hand-kept list of exceptions | Low: plugin and script go | +| 2 | trust | It fails when it cannot tell: no readable answer from `npm audit` fails the check. | A script that lets through on a tool error | Low | +| 3 | contract | CI (a warning) and the release (required) run the same `ui/scripts/audit-shipped.mjs` (Node, Windows and Linux); `docs/releasing.md` names it as the local check before the tag. | Two rules that drift apart | Low | +| 4 | term | The tag `v0.49.0` stays and is not published; the same content is released as 0.49.1, its changelog section headed `[0.49.1]` with a line that 0.49.0 was tagged but not published; `FORWARD_SINCE` and the docs keep `0.49.0`, which 0.49.1 satisfies. | Deleting and re-setting `v0.49.0` (`releasing.md` rules it out) | — | + +The first form of point 1 counted a package in `npm ls --omit=dev`. It was +approved on an analysis made without `node_modules` installed, where +`npm ls` lists nothing; installed, picomatch is in that tree through +vue-router. The check as first written would also have let every advisory +through when nothing was installed; it now refuses that (point 2). + +As built: + +1. **The list** (`ui/vite.config.ts`, plugin `devstack:bundle-packages`, + build only): every chunk's module ids below `node_modules`, as package + names (`@scope/name` kept whole); written at `closeBundle`, sorted. + Two kinds count as shipped although Rollup does not show them: every + installed `workbox-*` package (the service worker is bundled by workbox + in a build of its own), and every declared `dependency` (`vue` ships as + `@vue/*`, and an advisory names `vue`). +2. **The gate** (`ui/scripts/audit-shipped.mjs`): reads the list (none: + exit 2), runs `npm audit --omit=dev --json` (no JSON or no + `vulnerabilities`: exit 2), and fails (exit 1) for each entry whose + advisory is its own (an object in `via`, not a "through" name) and whose + package is on the list. Every other entry is printed as "not shipped". +3. **Where it runs:** the `ui` job of `ci.yml` (with `continue-on-error`) + and of `release.yml`, after `npm ci && npm run build`. + +Decided while building, not on the card: + +- An entry npm marks only "through" another package does not count even + when its own package ships (vue-router, through its build plugin's + dependencies): the advisory is for the other package, which is checked + on its own. + +## Alternatives considered + +- **A list of advisory ids to ignore,** each with a reason: has to be kept + by hand, and an id stays ignored after the package starts to ship. +- **Waiting for the advisory's fix:** the release waits on a package that + does not ship. + +## Consequences + +- An advisory for a build tool shows in the log of CI and the release, but + no longer holds a release. +- The list is only as good as the build that wrote it: run the gate after + `npm run build` of the same tree, as both workflows do. diff --git a/docs/adr/README.md b/docs/adr/README.md index 52760625..e1a70b4c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -193,3 +193,4 @@ stay. | [0108](0108-the-start-page-has-large-and-small-tiles-and-a-list.md) | The start page shows the stacks as large tiles, small tiles or a sortable list | Accepted (card in the pull request); built | | [0109](0109-the-order-of-the-stacks-is-one-choice-for-the-sidebar-and-the-start-page.md) | The order of the stacks is one choice for the sidebar and the start page | Accepted (card in the pull request); built | | [0110](0110-a-static-service-forwards-paths-to-another-server.md) | A static service forwards paths to another server, as a reverse proxy in front of it would | Accepted (card in the pull request); built | +| [0111](0111-the-dashboards-advisory-gate-counts-what-the-bundle-holds.md) | The dashboard's advisory gate counts what the bundle holds, not npm's runtime tree | Accepted (card in the pull request); built | diff --git a/docs/releasing.md b/docs/releasing.md index 46be1b0d..3cdaf031 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -30,8 +30,13 @@ patch version. through, its failed job is run again (`gh run rerun --failed`). - [ ] **No known advisory.** CI only warns about one; the release workflow refuses it. Checked before the tag: - `cargo deny --all-features check advisories` and, in `ui/`, - `npm audit --omit=dev` (`cargo install cargo-deny --locked` once). + `cargo deny --all-features check advisories` and, in `ui/` after + `npm ci` and `npm run build`, `node scripts/audit-shipped.mjs` + (`cargo install cargo-deny --locked` once). The latter counts an npm + advisory only for a package with code in the dashboard's bundle (the + build lists them in `ui/bundle-packages.json`); one for a build tool + alone is listed, not counted + ([ADR-0111](adr/0111-the-dashboards-advisory-gate-counts-what-the-bundle-holds.md)). ## 2. The release pull request diff --git a/ui/scripts/audit-shipped.mjs b/ui/scripts/audit-shipped.mjs new file mode 100644 index 00000000..a7ac4074 --- /dev/null +++ b/ui/scripts/audit-shipped.mjs @@ -0,0 +1,69 @@ +// The dashboard's advisory gate (ADR-0111): an npm advisory counts when the +// package it is for has code in what ships, the built bundle. The build +// lists those packages in `bundle-packages.json` (vite.config.ts). One for a +// build tool alone (vite, a bundler plugin, also where a runtime package +// lists it as a dependency for its build plugin) is listed here, not +// counted. No list, or no readable answer from npm, fails the check. +// +// npm run build && node scripts/audit-shipped.mjs (from ui/; exit 1 when +// a shipped package has a known advisory, 2 when it cannot tell) + +import { spawnSync } from 'node:child_process' +import { readFileSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' + +const ui = join(dirname(fileURLToPath(import.meta.url)), '..') + +let shipped +try { + shipped = new Set(JSON.parse(readFileSync(join(ui, 'bundle-packages.json'), 'utf8'))) +} catch (e) { + console.error(`no bundle-packages.json (run \`npm run build\` first): ${e.message}`) + process.exit(2) +} + +// npm is a script on Windows (npm.cmd), started only through a shell; the +// arguments are this file's own. npm exits 1 on a finding, so the exit code +// says nothing, only the JSON does. +const r = spawnSync('npm audit --omit=dev --json', { + cwd: ui, + encoding: 'utf8', + maxBuffer: 64 * 1024 * 1024, + shell: true, +}) +let audit +try { + audit = JSON.parse(r.stdout) +} catch { + console.error(`npm audit gave no JSON (exit ${r.status}):\n${r.stderr}`) + process.exit(2) +} +if (typeof audit.vulnerabilities !== 'object' || audit.vulnerabilities === null) { + console.error('npm audit --json has no `vulnerabilities`: cannot tell what is affected') + process.exit(2) +} + +// `via` holds the advisories for the package itself (objects) and the names +// of the packages it is marked through (strings). +const own = (v) => v.via.filter((x) => typeof x === 'object') + +let failed = 0 +for (const v of Object.values(audit.vulnerabilities)) { + const line = `${v.name} ${v.range}: ${ + own(v) + .map((x) => `${x.url ?? x.title} (${x.severity})`) + .join(', ') || `through ${v.via.join(', ')}` + }` + if (own(v).length > 0 && shipped.has(v.name)) { + console.error(`shipped: ${line}`) + failed++ + } else { + console.log(`not shipped: ${line}`) + } +} +if (failed) { + console.error(`${failed} package(s) in the dashboard's bundle have a known advisory`) + process.exit(1) +} +console.log(`no known advisory in the dashboard's bundle (${shipped.size} packages: ${[...shipped].join(', ')})`) diff --git a/ui/vite.config.ts b/ui/vite.config.ts index 6a622c2e..6d4d8a8b 100644 --- a/ui/vite.config.ts +++ b/ui/vite.config.ts @@ -1,10 +1,57 @@ import { fileURLToPath, URL } from 'node:url'; -import { readFileSync } from 'node:fs'; -import { defineConfig } from 'vite'; +import { readdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { defineConfig, type Plugin } from 'vite'; import vue from '@vitejs/plugin-vue'; import { VitePWA } from 'vite-plugin-pwa'; -const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')) as { version: string }; +const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')) as { + version: string; + dependencies?: Record; +}; + +/** The package a module path below `node_modules` belongs to, if any. */ +function packageOf(id: string): string | undefined { + const parts = id.replace(/\\/g, '/').split('/node_modules/'); + if (parts.length < 2) return undefined; + const [first, second] = parts[parts.length - 1].split('/'); + return first.startsWith('@') ? `${first}/${second}` : first; +} + +/** + * Writes `bundle-packages.json`: the packages whose code the build puts into + * `dist`, for the advisory gate (scripts/audit-shipped.mjs, ADR-0111). The + * service worker is bundled by workbox in a build of its own that this does + * not see: every installed `workbox-*` package counts as shipped. So do the + * declared `dependencies`: `vue` ships as `@vue/*`, and an advisory names + * `vue`. + */ +function bundlePackages(): Plugin { + const found = new Set(); + return { + name: 'devstack:bundle-packages', + apply: 'build', + generateBundle(_, bundle) { + for (const chunk of Object.values(bundle)) { + if (chunk.type !== 'chunk') continue; + for (const id of Object.keys(chunk.modules)) { + const name = packageOf(id); + if (name) found.add(name); + } + } + }, + closeBundle() { + const modules = fileURLToPath(new URL('./node_modules', import.meta.url)); + for (const name of readdirSync(modules)) { + if (name.startsWith('workbox-')) found.add(name); + } + for (const name of Object.keys(pkg.dependencies ?? {})) found.add(name); + writeFileSync( + fileURLToPath(new URL('./bundle-packages.json', import.meta.url)), + `${JSON.stringify([...found].sort(), null, 2)}\n`, + ); + }, + }; +} /** The part of the service worker's CacheStorage the shell fallback uses. */ type ShellCaches = { match(url: string, options: { ignoreSearch: boolean }): Promise }; @@ -34,6 +81,7 @@ export default defineConfig(({ mode }) => { }, plugins: [ vue(), + bundlePackages(), VitePWA({ registerType: 'autoUpdate', injectRegister: null,