@anzusystems/common-admin 2.0.0-rc.5 → 2.0.0-rc.6

package/package.json

@@ -35,7 +35,7 @@
     },
     "./package.json": "./package.json"
   },
-  "version": "2.0.0-rc.5",
+  "version": "2.0.0-rc.6",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -53,7 +53,7 @@
     "lib:build": "run-s --print-name lint:tsc build",
     "ci": "run-p --aggregate-output --continue-on-error --print-label --silent lint:tsc format:check lint:oxlint lint:eslint lint:stylelint",
     "lint": "[ \"$*\" = \"--fix\" ] && yarn lint:fix || yarn ci",
-    "lint:fix": "run-s --print-name lint:tsc lint:oxlint:fix lint:eslint:fix lint:stylelint:fix format",
+    "lint:fix": "run-s --continue-on-error --print-name lint:tsc lint:oxlint:fix lint:eslint:fix lint:stylelint:fix format",
     "lint:tsc": "NODE_OPTIONS=--max-old-space-size=4096 vue-tsc --build",
     "lint:tsc:test": "NODE_OPTIONS=--max-old-space-size=4096 vue-tsc --build tsconfig.test.json",
     "lint:eslint": "eslint",
@@ -74,24 +74,24 @@
     "release:cleanup": "npx -y --allow-git=all github:anzusystems/release-tools#main cleanup"
   },
   "devDependencies": {
-    "@anzusystems/common-admin": "2.0.0-rc.5",
-    "@intlify/unplugin-vue-i18n": "^11.2.7",
+    "@anzusystems/common-admin": "2.0.0-rc.6",
+    "@intlify/unplugin-vue-i18n": "^11.2.8",
     "@mdi/font": "^7.4.47",
-    "@sentry/vite-plugin": "11.9.0",
-    "@sentry/vue": "^11.9.0",
+    "@sentry/vite-plugin": "11.10.0",
+    "@sentry/vue": "^11.10.0",
     "@tsconfig/node22": "^22.0.6",
     "@types/node": "^24.19.2",
     "@types/rusha": "^0.8.3",
     "@types/sortablejs": "^1.15.9",
     "@typescript-eslint/parser": "^8.72.1",
     "@vitejs/plugin-vue": "^6.0.10",
-    "@vitest/browser": "^5.0.5",
-    "@vitest/browser-playwright": "^5.0.5",
-    "@vitest/ui": "^5.0.5",
+    "@vitest/browser": "^5.1.0",
+    "@vitest/browser-playwright": "^5.1.0",
+    "@vitest/ui": "^5.1.0",
     "@vue/compiler-dom": "3.5.44",
     "@vue/devtools-api": "^8.2.1",
     "@vue/eslint-config-typescript": "^14.9.0",
-    "@vue/language-server": "3.3.13",
+    "@vue/language-server": "3.3.14",
     "@vue/test-utils": "^2.5.1",
     "@vue/tsconfig": "0.9.1",
     "@vuelidate/core": "^2.0.3",
@@ -102,20 +102,20 @@
     "axios": "1.21.0",
     "cropperjs": "2.3.1",
     "dayjs": "1.11.23",
-    "eslint": "^10.13.0",
-    "eslint-plugin-oxlint": "1.89.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-oxlint": "1.90.0",
     "eslint-plugin-pinia": "^0.4.2",
     "eslint-plugin-vue": "10.12.0",
     "eslint-plugin-vuetify": "^2.7.3",
     "npm-run-all2": "^9.0.4",
     "oxfmt": "^0.75.0",
-    "oxlint": "1.89.0",
+    "oxlint": "1.90.0",
     "pinia": "4.1.0",
     "playwright": "^1.64.1",
     "postcss": "^8.5.32",
     "postcss-html": "^2.0.0",
     "rusha": "^0.8.14",
-    "sass": "1.106.1",
+    "sass": "1.107.1",
     "socket.io-client": "4.8.4",
     "sortablejs": "^1.15.7",
     "stylelint": "17.16.0",
@@ -124,44 +124,44 @@
     "stylelint-config-recommended-vue": "^2.0.0",
     "stylelint-config-standard-scss": "^17.0.0",
     "typescript": "~6.0.3",
-    "unplugin": "3.5.0",
+    "unplugin": "3.7.0",
     "unplugin-dts": "^1.1.2",
     "uuid": "^14.0.3",
     "vite": "8.3.5",
     "vite-plugin-vuetify": "^2.1.3",
-    "vitest": "^5.0.5",
+    "vitest": "^5.1.0",
     "vue": "3.5.44",
     "vue-eslint-parser": "^10.4.1",
-    "vue-i18n": "11.4.16",
+    "vue-i18n": "11.4.17",
     "vue-router": "5.4.0",
-    "vue-tsc": "3.3.13",
+    "vue-tsc": "3.3.14",
     "vuetify": "4.3.1"
   },
   "peerDependencies": {
     "@mdi/font": "^7.4.47",
-    "@sentry/vite-plugin": "^11.9.0",
-    "@sentry/vue": "^11.9.0",
+    "@sentry/vite-plugin": "^11.10.0",
+    "@sentry/vue": "^11.10.0",
     "@vue/eslint-config-typescript": "^14.9.0",
     "@vuelidate/core": "^2.0.3",
     "@vuelidate/validators": "^2.0.4",
     "@vueuse/core": "^15.0.0",
     "@vueuse/integrations": "^15.0.0",
     "@vueuse/shared": "^15.0.0",
-    "axios": "^1.20.0",
+    "axios": "^1.21.0",
     "dayjs": "^1.11.23",
-    "eslint": "^10.13.0",
-    "eslint-plugin-oxlint": "^1.89.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-oxlint": "^1.90.0",
     "eslint-plugin-pinia": "^0.4.2",
     "eslint-plugin-vue": "^10.12.0",
     "eslint-plugin-vuetify": "^2.7.3",
-    "oxlint": "^1.89.0",
+    "oxlint": "^1.90.0",
     "pinia": "^4.1.0",
     "socket.io-client": "^4.8.4",
     "sortablejs": "^1.15.7",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.5",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0",
     "vue": "^3.5.44",
-    "vue-i18n": "^11.4.16",
+    "vue-i18n": "^11.4.17",
     "vue-router": "^5.4.0",
     "vuetify": "^4.3.1"
   },

package/src/eslint/adminConfig.mjs

@@ -5,9 +5,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import { globalComponentNames } from './globalComponentNames.mjs'
 import { recommended } from './plugin.mjs'
 
-// The target `import` resolves to in an `exports` entry: the first key, in the object's own order, that
-// is one of the conditions an import in node matches. `require.resolve` would take the `require` branch,
-// the CommonJS build, a different module from the one the admin's own `import` gets.
+// The target `import` resolves to in an `exports` entry: the first key, in object order, that node's import matches.
+// `require.resolve` would take the `require` branch, a different CommonJS module.
 const IMPORT_CONDITIONS = new Set(['import', 'node', 'module-sync', 'default'])
 const importTarget = (entry) => {
   if (typeof entry === 'string') return entry
@@ -23,9 +22,9 @@ const importTarget = (entry) => {
   return undefined
 }
 
-// Resolved from the admin, not from this file: the admin declares these plugins, and under pnpm the
-// library's own directory cannot see its consumer's packages. The package's directory is looked up
-// rather than its entry resolved, so a package that only has an `import` entry is found as well.
+// Resolved from the admin, not from this file. The admin declares these
+// plugins, and under pnpm the library cannot see its consumer's packages.
+// The package directory is looked up instead of resolving its entry, so import-only packages are found too.
 const packageDir = (require, name) => {
   for (const base of require.resolve.paths(name) ?? []) {
     const dir = path.join(base, name)
@@ -60,15 +59,11 @@ const vuetifyComponents = (root) => {
 const routeNameSeverity = (value) => (value === false || value === 'off' ? 'off' : value === 'warn' ? 'warn' : 'error')
 
 /**
- * The whole eslint config of an admin, which each of them used to carry as a copy.
- *
- * `root` is the admin's `import.meta.url` (of its eslint.config.mjs): the plugins, Vuetify's component
- * list, `.oxlintrc.json` and `src/typed-router.d.ts` are all resolved against it, never against the
- * cwd -- an eslint run started from a subdirectory would otherwise lose the oxlint-disabled rules and
- * check route names against nothing. `extra` configs come last.
- *
- * @param {import('./plugin.d.mts').AnzuAdminEslintOptions} options
- * @param {...import('eslint').Linter.Config} extra
+ * The whole eslint config of an admin.
+ * `root` is the admin's `import.meta.url` (of its eslint.config.mjs). Plugins, Vuetify's component
+ * list, `.oxlintrc.json` and `src/typed-router.d.ts` resolve against it, not the cwd. Otherwise a
+ * run from a subdirectory loses the oxlint-disabled rules and checks route names against nothing.
+ * `extra` configs come last.
  */
 export async function defineAnzuAdminConfig(options, ...extra) {
   const {
@@ -161,8 +156,8 @@ export async function defineAnzuAdminConfig(options, ...extra) {
         'vue/no-undef-components': [
           'error',
           {
-            // Registered globally rather than imported, so the rule cannot see them: the Vuetify
-            // components, common-admin's button aliases and `Acl`, the router's, and the admin's own.
+            // Registered globally, not imported, so the rule cannot see them: Vuetify components,
+            // common-admin's button aliases and `Acl`, the router's, and the admin's own.
             ignorePatterns: [
               ...vuetifyComponents(rootUrl),
               ...globalComponentNames,
@@ -222,18 +217,15 @@ export async function defineAnzuAdminConfig(options, ...extra) {
       },
     },
     ...vuetify.configs['flat/recommended-v4'],
-    // Derives the disabled-rule list from the oxlint config, so a rule enabled there stops being run
-    // twice. prefer-const is switched off in the shared oxlint rules on purpose, so that it stays
-    // eslint's: oxlint does not run it inside a .vue at all.
+    // Disables in eslint the rules oxlint already runs.
+    // `prefer-const` is off in the shared oxlint rules on purpose so
+    // eslint keeps it. Oxlint does not run it inside `.vue` files.
     ...(oxlint ? await oxlint.buildFromOxlintConfigFile(fileURLToPath(new URL(oxlintConfig, rootUrl))) : []),
     {
-      // The only eslint rules that fight oxfmt. Measured, not assumed: with this block removed, eslint
-      // reports 85 warnings in an admin and 145 in common-admin, and in both they fall on these same
-      // rules and no others.
-      //
-      // html-self-closing is configured rather than switched off, because only its `void` half
-      // conflicts: oxfmt writes `<img />` where the rule's default demands `<img>`. With
-      // `void: 'any'` the formatter keeps that half and eslint keeps `<VBtn></VBtn>`.
+      // The only eslint rules that conflict with oxfmt. Measured: without this
+      // block all warnings in admins and common-admin fall on these rules.
+      // `html-self-closing` is configured, not disabled, because only its `void` half conflicts.
+      // oxfmt writes `<img />`. With `void: 'any'` eslint still enforces `<VBtn></VBtn>`.
       name: 'app/owned-by-oxfmt',
       rules: {
         'vue/html-closing-bracket-newline': 'off',

package/src/eslint/globalComponentNames.mjs

@@ -1,9 +1,8 @@
 // Its own module, without the preset's node imports: a browser test imports it as well.
 /**
- * The components the library registers globally -- the button aliases of its Vuetify config and the
- * plugin's `Acl` and `AChipNoLink` -- for the `ignorePatterns` of `vue/no-undef-components`. Kept equal to the
- * registrations (and to `CommonAdminGlobalComponents`) by a test. Admins used to read the aliases out
- * of the rolled-up declarations with a regex, which the per-module declarations no longer allow.
+ * The components the library registers globally: the Vuetify button aliases and the
+ * plugin's `Acl` and `AChipNoLink`. For the `ignorePatterns` of `vue/no-undef-components`.
+ * A test keeps it equal to the registrations and to `CommonAdminGlobalComponents`.
  */
 export const globalComponentNames = Object.freeze([
   'ABtnPrimary',

package/src/eslint/oxlint.mjs

@@ -1,26 +1,13 @@
 import { anzuPlugin } from './plugin.mjs'
 
 /**
- * Oxlint entry point for the Anzu rules.
- *
- * The rules operate on the standard ESTree AST, so oxlint runs them through its
- * JS plugin bridge with output identical to ESLint - including .vue <script>
- * blocks, scope analysis and autofix.
- *
- * Usage in .oxlintrc.json:
- *
- *   {
- *     "jsPlugins": ["@anzusystems/common-admin/oxlint"],
- *     "rules": {
- *       "anzu/no-ts-extension": "error",
- *       "anzu/url-params-match-template": "error"
- *     }
- *   }
- *
- * When these are enabled here, turn them off in eslint.config.mjs - oxlint's
- * `buildFromOxlintConfigFile` does not know about third-party rule names.
- *
- * NOTE: oxlint JS plugins are alpha and not subject to semver.
+ * Oxlint entry point for the Anzu rules. The rules use the standard ESTree AST, so oxlint runs them
+ * through its JS plugin bridge with the same output as ESLint, including `.vue` script blocks and autofix.
+ * @example .oxlintrc.json: { "jsPlugins": ["@anzusystems/common-admin/oxlint"], "rules":
+ * { "anzu/no-ts-extension": "error", "anzu/url-params-match-template": "error" } }
+ * When enabled here, turn them off in eslint.config.mjs.
+ * `buildFromOxlintConfigFile` does not know third-party rule names.
+ * Oxlint JS plugins are alpha and not covered by semver.
  */
 export default {
   meta: { name: 'anzu' },

package/src/eslint/plugin.d.mts

@@ -1,9 +1,8 @@
 import type { ESLint, Linter } from 'eslint'
 
 /**
- * Types for the plugin, which is javascript because eslint loads it directly from `src`. Written by
- * hand rather than generated, so it says what the plugin offers rather than what it happens to
- * return: a consumer that imports it gets a typed plugin, and the rule tests can import it at all.
+ * Hand-written types for the plugin, which is JavaScript because eslint loads it from `src`. They describe
+ * what the plugin offers, not what it happens to return, so consumers and rule tests get a typed plugin.
  */
 export declare const anzuPlugin: ESLint.Plugin
 
@@ -40,7 +39,6 @@ export interface AnzuAdminEslintOptions {
   ignores?: string[]
   /** Default `'error'`. */
   noExplicitAny?: 'error' | 'warn' | 'off'
-  /** Severities of the anzu rules. */
   anzu?: RecommendedOptions & { validRouteName?: Severity }
   /**
    * `configureVueProject()` of `@vue/eslint-config-typescript`, applied by the preset. `rootDir`

package/src/eslint/plugin.mjs

@@ -1,14 +1,13 @@
 import { validRouteName } from './validRouteName.mjs'
 
-// Shared by `prefer-api-command` and `prefer-api-fetch-items`: both ask the same question -- is this
-// call the `useApiRequest` helper, and what did it say it answers with.
+// Shared by `prefer-api-command` and `prefer-api-fetch-items`: is this
+// call the `useApiRequest` helper, and what response type does it declare.
 const isHelperSource = (source) =>
   typeof source === 'string' &&
   (source.includes('domains/api/composables/useApiRequest') || source === '@anzusystems/common-admin')
 
-// Resolved through the scope rather than matched by name. Matching the name fires on anyone
-// else's function called `useApiRequest` and on a parameter that shadows the import inside
-// one function, and stays silent when the real helper is imported under another name.
+// Resolved through scope, not by name. Name matching fires on other functions
+// called `useApiRequest` and on shadowing parameters, and misses an aliased import.
 const isHelperBinding = (context, node) => {
   let scope = context.sourceCode.getScope(node)
   while (scope !== null) {
@@ -79,8 +78,8 @@ const anzuPlugin = {
       create(context) {
         const reportedMethods = new Set(['DELETE', 'delete'])
 
-        // `any` and `never` satisfy the response constraint without meaning anything, and a call
-        // with no type argument at all infers it -- so the type cannot speak for these three.
+        // `any` and `never` satisfy the response constraint without meaning anything. A call
+        // with no type argument infers it. So the type cannot decide these three cases.
         const unhelpfulTypeArgument = (node) => {
           const first = firstTypeArgument(node)
           if (!first) return true
@@ -161,10 +160,10 @@ const anzuPlugin = {
         const envelopeLiteral = (node) => {
           if (node.type !== 'TSTypeLiteral') return false
 
-          // Exactly one member, on purpose: a literal that also spells out `hasNextPage` or
-          // `totalCount` is an author saying they read the metadata, which is a reason to stay on
-          // `useApiRequest`. The generic form carries no such signal, so it is reported and the one
-          // legitimate reader takes a disable with a reason.
+          // Exactly one member on purpose. A literal that also names `hasNextPage` or `totalCount`
+          // signals the author reads the metadata, a reason to stay on `useApiRequest`.
+          // The generic form carries no such signal, so it is reported.
+          // The one legitimate reader uses a disable with a reason.
           if (node.members.length !== 1) return false
           const member = node.members[0]
 
@@ -324,26 +323,19 @@ const anzuPlugin = {
             const resolved = resolveToString(templateProp.value)
             if (resolved === null) return
 
-            // The path only, because that is all `stringUrlTemplateReplace` substitutes into: it
-            // splits the template on `?` and rejoins the query untouched. Scanning the query too
-            // would fail CI on a perfectly good `...?locale=:locale`, and adding `locale` to
-            // `urlParams` to silence it would change nothing at runtime.
+            // Only the path, because `stringUrlTemplateReplace` substitutes only there and rejoins the query untouched.
+            // Scanning the query would fail CI on a valid `...?locale=:locale`.
             const [path] = resolved.split('?')
 
-            // Exactly what `stringUrlTemplateReplace` does, and nothing else: split the path on `/`,
-            // skip any part that does not START with `:`, and take everything after that colon as the
-            // key. Both halves matter and both were got wrong in turn. Hunting for `:name` anywhere
-            // matches inside `prefix-:id`, which the runtime leaves alone, so the rule demanded a key
-            // that is never filled in. Requiring the key to look like an identifier misses `:asset-id`,
-            // which the runtime substitutes happily, so the rule reported the caller's correct
-            // `urlParams` as having no placeholder to match.
+            // Mirrors `stringUrlTemplateReplace`: split the path on `/`, skip parts
+            // not starting with `:`, and take everything after the colon as the key.
+            // Matching `:name` anywhere wrongly hits `prefix-:id`, which the runtime ignores.
+            // Requiring an identifier-like key misses `:asset-id`, which the runtime substitutes.
             const placeholders = new Set()
             for (const segment of path.split('/')) {
               if (!segment.startsWith(':')) continue
-              // No guard on the name, because the runtime has none: a bare `:` takes `''` as its key
-              // and fills the segment in from `params['']`. Nobody writes that on purpose, which is
-              // the point -- it is a typo, and the rule reporting a missing key is how it gets seen
-              // rather than shipped as a literal colon in the url.
+              // No guard on the name, because the runtime has none. A bare `:` uses `''`
+              // as its key. That is a typo, and reporting the missing key surfaces it.
               placeholders.add(segment.slice(1))
             }
 
@@ -379,12 +371,6 @@ const anzuPlugin = {
 
 /**
  * Creates an ESLint flat config entry for Anzu rules.
- *
- * @param {Object} [options]
- * @param {boolean|'error'|'warn'|'off'} [options.noTsExtension='error'] - Severity for no-ts-extension rule.
- * @param {boolean|'error'|'warn'|'off'} [options.preferApiFetchItems='error']
- *   - Severity for prefer-api-fetch-items rule.
- * @returns {Object} ESLint flat config entry
  */
 export function recommended(options = {}) {
   const {
@@ -402,13 +388,11 @@ export function recommended(options = {}) {
     rules['anzu/no-ts-extension'] = tsExtSeverity
   }
 
-  // prefer-api-command
   const preferApiCommandSeverity = normalizeSeverity(preferApiCommand)
   if (preferApiCommandSeverity) {
     rules['anzu/prefer-api-command'] = preferApiCommandSeverity
   }
 
-  // prefer-api-fetch-items
   const preferApiFetchItemsSeverity = normalizeSeverity(preferApiFetchItems)
   if (preferApiFetchItemsSeverity) {
     rules['anzu/prefer-api-fetch-items'] = preferApiFetchItemsSeverity

package/src/eslint/validRouteName.mjs

@@ -1,15 +1,14 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
-// Route names checked against the admin's generated `src/typed-router.d.ts`: a literal `name`, `route`
-// or `*RouteName` value that starts with `/` has to be one of its routes. The admins had this rule
-// each in its own copy; the path comes from `settings.anzu.typedRouter` (set by
-// `defineAnzuAdminConfig`, absolute) and falls back to the one under the cwd.
+// Checks route names against the admin's generated `src/typed-router.d.ts`. A literal
+// `name`, `route` or `*RouteName` value starting with `/` must be one of its routes.
+// The path comes from `settings.anzu.typedRouter` (absolute, set by
+// `defineAnzuAdminConfig`) and falls back to the one under the cwd.
 
 const loaded = new Map()
-// The declaration is generated and gitignored, so a fresh clone has none until `generate:dts` ran.
-// Staying quiet then would make the rule a no-op exactly when nobody expects it, so the first file of
-// the run says so instead. Once per run and file, not once per linted file.
+// The declaration is generated and gitignored, so a fresh clone lacks it until `generate:dts` runs.
+// Staying silent would make the rule a silent no-op, so it reports once per run and file, not per linted file.
 const reportedMissing = new Set()
 
 function loadRoutes(file) {

package/src/vite/devWatch.mjs

@@ -7,11 +7,10 @@ const BARE_IMPORT = /(?:\bfrom\s*|\bimport\s*\(?\s*)['"]([^'"./][^'"]*)['"]/g
 // A package name with an optional subpath: filters out what the pattern above also finds inside strings.
 const PACKAGE_ID = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(?:\/[\w.-]+)*$/
 
-// `./testing`, which only tests load: its imports (vitest) are nothing the dev server has to bundle.
-// A path relative to `dist`.
+// `./testing` is loaded only by tests. Its imports (vitest) need no dev server bundling.
+// The path is relative to `dist`.
 const isTesting = (file) => /^testing($|\.m?js$|[\\/])/.test(file)
 
-// The other packages one built file imports.
 const bareImports = (code) => {
   const found = new Set()
   for (const [, id] of code.matchAll(BARE_IMPORT)) {
@@ -21,18 +20,17 @@ const bareImports = (code) => {
 }
 
 /**
- * Everything the library's files import from other packages -- `vuetify/components/VMenu`, `dayjs`,
- * `axios`... -- read off the copy in the admin's node_modules. Pre-bundled for them (`pkg > id`) when
- * the library itself is not: a package file importing a dependency that is not pre-bundled gets it
- * raw, as a second copy next to the admin's own pre-bundled one (two Vuetify module instances, each
- * with its own overlay stack), and a CommonJS one not at all. Derived, not listed; an import that
- * appears during a session restarts the server, which derives the list again.
+ * Every package the library's files import, read from the copy in the admin's
+ * node_modules. Pre-bundled for them (`pkg > id`) when the library is not.
+ * A package file importing a non-pre-bundled dependency gets it raw, as a second copy next to
+ * the admin's (two Vuetify instances, two overlay stacks). A CommonJS one does not load at all.
+ * Derived, not listed. A new import during a session restarts the server, which derives the list again.
  */
 const nestedDependencies = (root) => {
   const dist = join(root, 'node_modules', PACKAGE, 'dist')
   const found = new Set()
   if (!existsSync(dist)) return found
-  // `.mjs` too: the dev bundle names its shared chunks so.
+  // Includes `.mjs`: the dev bundle names its shared chunks so.
   const walk = (dir) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const full = join(dir, entry.name)
@@ -45,11 +43,11 @@ const nestedDependencies = (root) => {
   return found
 }
 
-// TODO: remove once Vite ships https://github.com/vitejs/vite/pull/23499 (issue vitejs/vite#23493, not fixed in
-// 8.3.1). A restart hands the new server `previousEnvironments: server.environments`, and the new server keeps
-// that in its closure: every restart kept the previous server's environments, module graphs and all, +45-100 MB
-// a restart. The restart gets a copy, emptied once the new server stands; if the restart failed, the server
-// still runs on the copy and it stays.
+// TODO: remove once Vite ships https://github.com/vitejs/vite/pull/23499 (issue vitejs/vite#23493, not fixed in 8.3.1).
+// A restart passes `previousEnvironments: server.environments`, and the new server keeps it
+// in its closure. Each restart leaked the old environments and module graphs, +45-100 MB.
+// The restart gets a copy, emptied once the new server is up. If the
+// restart fails, the server still runs on the copy and it stays.
 const restartReleasingPrevious = async (server, forceOptimize) => {
   const handover = { ...server.environments }
   server.environments = handover
@@ -59,24 +57,14 @@ const restartReleasingPrevious = async (server, forceOptimize) => {
 }
 
 /**
- * Picks up a common-admin that `./copy.sh` or `yarn dev:admin` wrote into the admin's node_modules.
- * Both write `.common-admin-updated` in the admin's root (copy.sh empties it, `yarn dev:admin` lists
- * the files it changed); this plugin watches it.
- *
- * - common-admin pre-bundled (in `optimizeDeps.include`, the default): restarts the server with a
- *   forced re-optimization. A plain full reload is not enough: the browser keeps the old bundle under
- *   an unchanged `?v=`.
- * - `prebundle: false` (common-admin in `optimizeDeps.exclude`): its files are served one by one, so only the ones the
- *   trigger file lists (`yarn dev:admin` writes them there) are invalidated, then the page reloads.
- *   Their responses get `Cache-Control: no-cache` instead of `immutable`, so the browser revalidates
- *   them (a 304 for the unchanged ones) instead of keeping the old ones under the same `?v=`. A changed
- *   file that imports a package the library did not import before restarts the server instead, and so
- *   do copy.sh and the watch's first copy.
- *
- * Does nothing in a build.
- *
- * @param {import('./index.d.mts').CommonAdminDevWatchOptions} [options]
- * @returns {import('vite').Plugin}
+ * Picks up a common-admin that `./copy.sh` or `yarn dev:admin` wrote into the admin's node_modules. Both write
+ * `.common-admin-updated` in the admin's root (copy.sh empties it, `yarn dev:admin` lists changed files).
+ * - Pre-bundled (default): restarts the server with forced re-optimization. A full reload
+ * is not enough because the browser keeps the old bundle under an unchanged `?v=`.
+ * - `prebundle: false`: only files listed in the trigger file are invalidated, then the page reloads.
+ * They get `Cache-Control: no-cache` instead of `immutable`, so the browser revalidates them.
+ * A changed file importing a new package restarts the server instead,
+ * as do copy.sh and the watch's first copy. Does nothing in a build.
  */
 export function commonAdminDevWatch({ triggerFile = '.common-admin-updated', prebundle = true } = {}) {
   // What the optimizer pre-bundles for the library, as this server started with it.
@@ -90,8 +78,8 @@ export function commonAdminDevWatch({ triggerFile = '.common-admin-updated', pre
         config.optimizeDeps.include = config.optimizeDeps.include.filter((id) => id !== PACKAGE)
       }
       known = nestedDependencies(resolve(config.root ?? process.cwd()))
-      // What the admin excludes reaches it raw; pre-bundled for the library as well, it would load twice.
-      // `known` keeps them, so a change importing one is not taken for a new import.
+      // Packages the admin excludes reach it raw. Pre-bundled for the library too, they would load twice.
+      // `known` keeps them, so a change importing one is not treated as a new import.
       const own = config.optimizeDeps?.exclude ?? []
       const include = [...known].filter((id) => !own.some((pkg) => id === pkg || id.startsWith(`${pkg}/`)))
       return {
@@ -118,17 +106,16 @@ export function commonAdminDevWatch({ triggerFile = '.common-admin-updated', pre
       const onTrigger = (file) => {
         if (file !== trigger) return
         const listed = readFileSync(trigger, 'utf8').split('\n').filter(Boolean)
-        // Pre-bundled: the library is inside the optimizer's bundle, whose hash does not see its content,
-        // so only a forced re-optimization picks the new build up.
+        // Pre-bundled: the optimizer's bundle hash ignores the library's
+        // content, so only a forced re-optimization picks up the new build.
         if (!excluded) {
           log('replaced, restarting the server...')
           void restartReleasingPrevious(server, true)
           return
         }
-        // copy.sh (an empty file, and it deletes the optimized deps) or the watch's first copy (`*`):
-        // everything may have changed. Not forced: the library is not in the pre-bundle, and a changed
-        // list of its imports changes the optimizer's hash by itself; forcing would only throw away what
-        // it discovered at runtime and cost a round of reloads.
+        // copy.sh (empty file, deletes optimized deps) or the watch's first copy (`*`): anything may have changed.
+        // Not forced: the library is not pre-bundled, and a changed import list changes the
+        // optimizer hash itself. Forcing would discard runtime discoveries and cost extra reloads.
         if (listed.length === 0 || listed.includes('*')) {
           log('replaced, restarting the server...')
           void restartReleasingPrevious(server)
@@ -136,8 +123,8 @@ export function commonAdminDevWatch({ triggerFile = '.common-admin-updated', pre
         }
         const packageDir = join(root, 'node_modules', PACKAGE)
         const distDir = join(existsSync(packageDir) ? realpathSync(packageDir) : packageDir, 'dist')
-        // A package none of the library's files imported when this server started: it is not pre-bundled,
-        // and Vite does not discover imports made from node_modules. The restart derives the list again.
+        // A package no library file imported at server start is not pre-bundled, and Vite
+        // does not discover imports from node_modules. The restart derives the list again.
         const added = listed
           .filter((changed) => /\.m?js$/.test(changed) && !isTesting(changed) && existsSync(join(distDir, changed)))
           .flatMap((changed) => [...bareImports(readFileSync(join(distDir, changed), 'utf8'))])

package/src/vite/index.d.mts

@@ -23,11 +23,11 @@ export interface CommonAdminDevWatchOptions {
   /** Relative to the admin's root. Defaults to `.common-admin-updated`, which `copy.sh` and `yarn dev:admin` write. */
   triggerFile?: string
   /**
-   * `false`: common-admin is left out of the dependency pre-bundling (its files are served one by one:
-   * a dozen with `yarn dev:admin`, which builds one bundle, ~800 after `./copy.sh`; the library's own
-   * dependencies are pre-bundled for it, except what the admin excludes itself), so an update from
-   * `yarn dev:admin` invalidates the changed files and reloads the page instead of restarting the server. Defaults to
-   * `true` (pre-bundled; an update restarts the server with a forced re-optimization).
+   * `false`: common-admin is excluded from pre-bundling and served file by file.
+   * Its own dependencies are still pre-bundled, except what the admin excludes.
+   * An update from `yarn dev:admin` then invalidates the changed
+   * files and reloads the page instead of restarting the server.
+   * Defaults to `true`: pre-bundled, and an update restarts the server with forced re-optimization.
    */
   prebundle?: boolean
 }

package/src/vite/sentry.mjs

@@ -19,16 +19,11 @@ function loadSentryVitePlugin() {
 }
 
 /**
- * The Sentry build setup shared by the admins: release, source map upload, and the library's own
- * source maps chained into the admin's (see `commonAdminSourcemaps`).
- *
- * Enabled when both `APP_DEPLOY_ENV` and `SENTRY_URL` are set. Then the build emits `hidden` source
- * maps (the JS does not point at them), uploads them and deletes them from the output directory,
- * so they never reach the deployed site. A missing token, org or project fails the build instead
- * of skipping the upload with a warning, and so does a failed upload.
- *
- * @param {import('./index.d.mts').AnzuSentryOptions} options
- * @returns {import('vite').PluginOption[]}
+ * Sentry build setup shared by the admins: release, source map upload,
+ * and the library's maps chained in (see `commonAdminSourcemaps`).
+ * Enabled when `APP_DEPLOY_ENV` and `SENTRY_URL` are set. The build then emits `hidden` source
+ * maps, uploads them and deletes them from the output, so they never reach the deployed site.
+ * A missing token, org or project fails the build instead of warning, and so does a failed upload.
  */
 export function anzuSentry({ project, org = 'petitpress', release, sourcemaps, ...overrides }) {
   const env = process.env
@@ -44,8 +39,8 @@ export function anzuSentry({ project, org = 'petitpress', release, sourcemaps, .
   }
 
   const sentryVitePlugin = loadSentryVitePlugin()
-  // The upload runs in the output directory, while a relative glob would be matched against the
-  // working directory: derive it from the resolved `build.outDir` instead.
+  // The upload runs in the output directory, but a relative glob matches
+  // against the working directory. Derive it from the resolved `build.outDir`.
   let resolveOutDir
   const filesToDeleteAfterUpload = new Promise((resolveGlob) => {
     resolveOutDir = (outDir) => resolveGlob(`${outDir.split(sep).join('/')}/**/*.js.map`)