@anzusystems/common-admin 2.0.0-rc.1 → 2.0.0-rc.10

package/src/e2e/types.d.mts

@@ -0,0 +1,161 @@
+import type {
+  Expect,
+  Page,
+  PlaywrightTestArgs,
+  PlaywrightTestOptions,
+  PlaywrightWorkerArgs,
+  PlaywrightWorkerOptions,
+  Request,
+  TestType,
+} from 'playwright/test'
+
+/** Something a page did wrong, matched by `RouteWalkIgnore.problem` as text. */
+export type RouteWalkProblem = string
+
+export interface RouteWalkIgnore {
+  /** Matched against the problem's text, e.g. `/^console\.error: .*ResizeObserver/`. */
+  problem: RegExp
+  /** Only on these routes (their declared path); everywhere when left out. */
+  routes?: RegExp
+  /** Why it is not a failure. Required, so that an exception never goes unexplained. */
+  reason: string
+}
+
+/** How long the walk waits, in milliseconds. */
+export interface RouteWalkTimings {
+  /** For the app to render its `main`. */
+  app: number
+  /** For the card loaders to finish, once the page has settled. */
+  loader: number
+  /** How long no API request, script or style may be running before the page counts as loaded. */
+  quiet: number
+  /** How long a page that keeps requesting (autorefresh) is waited for. */
+  settleLimit: number
+  /**
+   * An API request that takes this long, answered or not, is a problem: it hung, or its client gave up on it (the
+   * clients time out at 15–30 s).
+   */
+  slowRequest: number
+}
+
+/**
+ * The admin's own `test` and `expect` from `@playwright/test`. The walk does not import Playwright Test: an admin
+ * keeps it in its e2e project, out of reach of this package, and a second copy in one run fails.
+ */
+export interface RouteWalkPlaywright {
+  test: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>
+  expect: Expect
+}
+
+export interface RouteWalkOptions {
+  /** Title of the describe block, e.g. `ADMIN-CMS (LOCAL) - Routes`. */
+  title: string
+  /** The app's `src/typed-router.d.ts`. */
+  declarationFile: string
+  /** The app's `src/pages`. The declaration must hold one route per page file but the catch-all. */
+  pagesDir: string
+  /** Logs the worker's page in. The page has the project's `baseURL`. */
+  login: (page: Page) => Promise<void>
+  /** Routes not opened at all, by declared path, with the reason. */
+  skip?: Record<string, string>
+  /**
+   * Routes not opened while a condition holds, e.g. a system the app's `config.json` disables: its routes
+   * send the visitor to `/unauthorized` by design.
+   */
+  skipIf?: { routes: RegExp; reason: string; when: (page: Page) => Promise<boolean> }[]
+  /** Values of parameters by name, used wherever the parameter appears (e.g. `{ system: 'cms' }`). */
+  params?: Record<string, string>
+  /**
+   * Routes whose address cannot come from a listing, by declared path: returns the path to open, or
+   * `undefined` when there is no record to open (the route is skipped, as for an empty listing).
+   */
+  resolve?: Record<string, (page: Page) => Promise<string | undefined>>
+  /**
+   * Routes whose listing cannot give a record, by declared path, with the reason: the address before the
+   * parameter is not a page, or its rows open something else. Any other such route fails. An empty listing
+   * only skips its routes, since what a listing holds depends on the environment's data.
+   */
+  noRecord?: Record<string, string>
+  /**
+   * Routes that forward by design, by declared path: where they may land (a pathname pattern). Landing
+   * anywhere but the address opened fails any other route, so a page that gives up and goes back is seen.
+   */
+  redirects?: Record<string, RegExp>
+  /** Problems that do not fail a route. */
+  ignore?: RouteWalkIgnore[]
+  /** The rows of a listing, clicked to find a record when no link to one is found. Default: Vuetify's data table. */
+  rowSelector?: string
+  /**
+   * Requests that stay open for the whole session, e.g. a server-sent event stream: neither waited for nor
+   * checked. Default: a notification stream (`/notifications/stream/`).
+   */
+  openRequests?: RegExp
+  /**
+   * Where the app sends a visitor it cannot serve. The boot check must not end on one of them.
+   * Default: `/unauthorized`, `/error` and `/login`.
+   */
+  problemPages?: string[]
+  /** Overrides of `DEFAULT_TIMINGS`. */
+  timings?: Partial<RouteWalkTimings>
+  /**
+   * Timings of single routes, by declared path, over `timings`, with the reason: a page known to be slow gets
+   * more time without every route getting it.
+   */
+  routeTimings?: Record<string, { timings: Partial<RouteWalkTimings>; reason: string }>
+}
+
+/** What a page did while the walk watched it. */
+export interface PageWatcher {
+  /** Forgets everything seen so far, before the next page; `slowRequest` for that page, else the watcher's own. */
+  reset(options?: { slowRequest?: number }): void
+  push(problem: RouteWalkProblem): void
+  /**
+   * The problems, once each: common-admin's `Api error: <url> …` and Chromium's "Failed to load resource" repeat a
+   * failed response the walk reports itself, so they are kept only for a url no response accounts for.
+   */
+  problems(): RouteWalkProblem[]
+  /** API requests answered with a success. */
+  readonly apiAnswered: number
+  /** When an API request, script or style last started or ended (ms since the epoch); 0 after `reset`. */
+  readonly lastActivity: number
+  /** The API requests, scripts and styles still running, with when they started. */
+  readonly inFlight: ReadonlyMap<Request, number>
+}
+
+export interface RouteVisit {
+  /** Whether no request was running at the end; a page that keeps requesting does not settle. */
+  settled: boolean
+  /** The pathname the page ended on. */
+  landedOn: string
+  problems: RouteWalkProblem[]
+  apiAnswered: number
+}
+
+export type RecordLookup = { id: string } | { missing: string; empty?: true }
+
+// The walk's functions, declared once: `routeWalk.d.mts` exports them by these types, and `routeWalk.mjs` gives
+// each its type, so that the type check holds the code to its declaration.
+
+export type ReadDeclaredRoutes = (declarationFile: string) => string[]
+
+export type DefineRouteWalk = (playwright: RouteWalkPlaywright, options: RouteWalkOptions) => void
+
+export type WatchPage = (
+  page: Page,
+  options?: { openRequests?: RegExp; timings?: Partial<RouteWalkTimings> }
+) => PageWatcher
+
+export type VisitRoute = (
+  page: Page,
+  watcher: PageWatcher,
+  target: string,
+  options?: { redirect?: RegExp; timings?: Partial<RouteWalkTimings> }
+) => Promise<RouteVisit>
+
+export type FirstRecordOf = (
+  page: Page,
+  watcher: PageWatcher,
+  listing: string,
+  pattern: RegExp,
+  options: { outputDir: string; rowSelector?: string; timings?: Partial<RouteWalkTimings> }
+) => Promise<RecordLookup>

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,
@@ -175,7 +170,8 @@ export async function defineAnzuAdminConfig(options, ...extra) {
         'vue/attribute-hyphenation': ['error', 'always'],
         'vue/v-on-event-hyphenation': ['error', 'always'],
         'vue/custom-event-name-casing': ['error', 'camelCase'],
-        'vue/define-emits-declaration': ['error', 'type-based'],
+        // `defineEmits<{ submit: [] }>()`, not the call-signature form `(e: 'submit'): void`.
+        'vue/define-emits-declaration': ['error', 'type-literal'],
         'vue/no-template-target-blank': ['error'],
         'vue/block-order': ['error', { order: [['script', 'template'], 'style'] }],
         'vue/define-macros-order': ['error'],
@@ -221,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-admin.json

@@ -34,6 +34,9 @@
     "vue/no-lifecycle-after-await": "error",
     "vue/no-watch-after-await": "error",
 
+    // `() => x`, not `() => { return x }`.
+    "arrow-body-style": ["error", "as-needed"],
+
     // Imports: oxfmt sorts the statements (`sortImports` in .oxfmtrc.json); these sort the names
     // inside the braces, merge two imports of one module and keep types in their own `import type`.
     "sort-imports": ["error", { "ignoreDeclarationSort": true }],

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
 }