Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
9 changes: 7 additions & 2 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,13 @@ patch version.
through, its failed job is run again (`gh run rerun <run> --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

Expand Down
69 changes: 69 additions & 0 deletions ui/scripts/audit-shipped.mjs
Original file line number Diff line number Diff line change
@@ -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(', ')})`)
54 changes: 51 additions & 3 deletions ui/vite.config.ts
Original file line number Diff line number Diff line change
@@ -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<string, string>;
};

/** 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<string>();
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<Response | undefined> };
Expand Down Expand Up @@ -34,6 +81,7 @@ export default defineConfig(({ mode }) => {
},
plugins: [
vue(),
bundlePackages(),
VitePWA({
registerType: 'autoUpdate',
injectRegister: null,
Expand Down
Loading