@anzusystems/common-admin 1.49.0 → 2.0.0-rc.2

package/src/eslint/validRouteName.mjs

@@ -0,0 +1,126 @@
+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.
+
+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.
+const reportedMissing = new Set()
+
+function loadRoutes(file) {
+  let stat
+  try {
+    stat = fs.statSync(file)
+  } catch {
+    return loaded.get(file)?.routes ?? new Set()
+  }
+  const cached = loaded.get(file)
+  if (cached && stat.mtimeMs === cached.mtimeMs) return cached.routes
+
+  const content = fs.readFileSync(file, 'utf8')
+  const routes = new Set()
+  const re = /'([^']+)':\s*RouteRecordInfo/g
+  let m
+  while ((m = re.exec(content)) !== null) {
+    routes.add(m[1])
+  }
+  loaded.set(file, { routes, mtimeMs: stat.mtimeMs })
+  return routes
+}
+
+function isRouteKey(key) {
+  if (!key) return false
+  const normalized = String(key).replace(/-/g, '').toLowerCase()
+  return normalized === 'name' || normalized === 'route' || normalized.endsWith('routename')
+}
+
+export const validRouteName = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Validate route names against generated src/typed-router.d.ts',
+    },
+    schema: [],
+    messages: {
+      unknown:
+        "Unknown route name '{{name}}'. Not found in {{file}}. " + 'Run `yarn generate:dts` if routes were just added.',
+      missing: '{{file}} is missing or empty, so route names cannot be validated. Run `yarn generate:dts`.',
+    },
+  },
+  create(context) {
+    const file = context.settings?.anzu?.typedRouter ?? path.join(context.cwd ?? process.cwd(), 'src/typed-router.d.ts')
+    const routes = loadRoutes(file)
+    const shown = path.relative(context.cwd ?? process.cwd(), file) || file
+    if (routes.size === 0) {
+      if (reportedMissing.has(file)) return {}
+      reportedMissing.add(file)
+      return {
+        Program(node) {
+          context.report({ node, messageId: 'missing', data: { file: shown } })
+        },
+      }
+    }
+
+    function checkLiteral(node, value) {
+      if (typeof value !== 'string') return
+      if (!value.startsWith('/')) return
+      if (routes.has(value)) return
+      context.report({ node, messageId: 'unknown', data: { name: value, file: shown } })
+    }
+
+    function checkProperty(prop) {
+      if (!prop || prop.type !== 'Property') return
+      const key = prop.key
+      const keyName = key.type === 'Identifier' ? key.name : key.type === 'Literal' ? String(key.value) : null
+      if (!isRouteKey(keyName)) return
+      const val = prop.value
+      if (val && val.type === 'Literal') {
+        checkLiteral(val, val.value)
+      }
+    }
+
+    function checkAttributeLiteral(node) {
+      const key = node.key
+      if (!key) return
+      let name
+      if (key.type === 'VIdentifier') {
+        name = key.name
+      } else if (key.type === 'VDirectiveKey') {
+        if (key.name?.name !== 'bind') return
+        const arg = key.argument
+        if (!arg || arg.type !== 'VIdentifier') return
+        name = arg.name
+      }
+      if (!isRouteKey(name)) return
+      const val = node.value
+      if (!val) return
+      if (val.type === 'VLiteral') {
+        checkLiteral(val, val.value)
+        return
+      }
+      if (val.type === 'VExpressionContainer' && val.expression?.type === 'Literal') {
+        checkLiteral(val.expression, val.expression.value)
+      }
+    }
+
+    const scriptVisitor = {
+      Property: checkProperty,
+    }
+
+    const templateVisitor = {
+      VAttribute: checkAttributeLiteral,
+      'VElement > VStartTag > VAttribute > VExpressionContainer Property': checkProperty,
+    }
+
+    const parserServices = context.sourceCode?.parserServices ?? context.parserServices
+    if (parserServices?.defineTemplateBodyVisitor) {
+      return parserServices.defineTemplateBodyVisitor(templateVisitor, scriptVisitor)
+    }
+    return scriptVisitor
+  },
+}

package/src/vite/devWatch.mjs

@@ -0,0 +1,169 @@
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+const PACKAGE = '@anzusystems/common-admin'
+const PACKAGE_URL = `/node_modules/${PACKAGE}/`
+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`.
+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)) {
+    if (PACKAGE_ID.test(id) && !id.startsWith(PACKAGE) && !id.endsWith('.css')) found.add(id)
+  }
+  return found
+}
+
+/**
+ * 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.
+ */
+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.
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name)
+      if (isTesting(relative(dist, full))) continue
+      if (entry.isDirectory()) walk(full)
+      else if (/\.m?js$/.test(entry.name)) for (const id of bareImports(readFileSync(full, 'utf8'))) found.add(id)
+    }
+  }
+  walk(dist)
+  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.
+const restartReleasingPrevious = async (server, forceOptimize) => {
+  const handover = { ...server.environments }
+  server.environments = handover
+  await (forceOptimize ? server.restart(true) : server.restart())
+  if (server.environments === handover) return
+  for (const name of Object.keys(handover)) delete handover[name]
+}
+
+/**
+ * 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}
+ */
+export function commonAdminDevWatch({ triggerFile = '.common-admin-updated', prebundle = true } = {}) {
+  // What the optimizer pre-bundles for the library, as this server started with it.
+  let known = new Set()
+  return {
+    name: 'anzu:common-admin-dev-watch',
+    apply: 'serve',
+    config(config) {
+      if (prebundle) return
+      if (config.optimizeDeps?.include) {
+        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.
+      const own = config.optimizeDeps?.exclude ?? []
+      const include = [...known].filter((id) => !own.some((pkg) => id === pkg || id.startsWith(`${pkg}/`)))
+      return {
+        optimizeDeps: { exclude: [PACKAGE], include: include.sort().map((id) => `${PACKAGE} > ${id}`) },
+      }
+    },
+    configureServer(server) {
+      const { root, logger, optimizeDeps } = server.config
+      const trigger = resolve(root, triggerFile)
+      const excluded = !!optimizeDeps.exclude?.includes(PACKAGE)
+      const log = (message) => logger.info(`[common-admin] ${message}`, { timestamp: true })
+
+      if (excluded) {
+        server.middlewares.use((req, res, next) => {
+          if (req.url?.includes(PACKAGE_URL)) {
+            const setHeader = res.setHeader.bind(res)
+            res.setHeader = (name, value) =>
+              setHeader(name, name.toLowerCase() === 'cache-control' ? 'no-cache' : value)
+          }
+          next()
+        })
+      }
+
+      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.
+        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.
+        if (listed.length === 0 || listed.includes('*')) {
+          log('replaced, restarting the server...')
+          void restartReleasingPrevious(server)
+          return
+        }
+        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.
+        const added = listed
+          .filter((changed) => /\.m?js$/.test(changed) && !isTesting(changed) && existsSync(join(distDir, changed)))
+          .flatMap((changed) => [...bareImports(readFileSync(join(distDir, changed), 'utf8'))])
+          .filter((id) => !known.has(id))
+        if (added.length > 0) {
+          log(`new import of ${[...new Set(added)].join(', ')}, restarting the server...`)
+          void restartReleasingPrevious(server)
+          return
+        }
+        const environment = server.environments.client
+        let invalidated = 0
+        for (const changed of listed) {
+          // The module graph keys files by forward-slash paths, also on Windows.
+          const file = join(distDir, changed).replaceAll('\\', '/')
+          for (const mod of environment.moduleGraph.getModulesByFile(file) ?? []) {
+            environment.moduleGraph.invalidateModule(mod)
+            invalidated++
+          }
+        }
+        log(`${listed.length} file(s) changed, ${invalidated} module(s) invalidated, reloading the page`)
+        environment.hot.send({ type: 'full-reload', path: '*' })
+      }
+      server.watcher.add(trigger)
+      // `add` too: on a fresh checkout the file does not exist until the first copy creates it
+      server.watcher.on('add', onTrigger)
+      server.watcher.on('change', onTrigger)
+    },
+  }
+}

package/src/vite/index.d.mts

@@ -0,0 +1,39 @@
+import type { SentryVitePluginOptions } from '@sentry/vite-plugin'
+import type { Plugin, PluginOption } from 'vite'
+
+export interface AnzuSentryOptions extends Omit<SentryVitePluginOptions, 'project' | 'org'> {
+  /** Sentry project slug, e.g. `anzu-admin-cms`. */
+  project: string
+  /** Sentry organization slug. Defaults to `petitpress`. */
+  org?: string
+}
+
+/**
+ * Sentry release and source map upload for an admin build, enabled when `APP_DEPLOY_ENV` and
+ * `SENTRY_URL` are set. Put it first in `plugins`: `plugins: [...anzuSentry({ project }), vue(), …]`.
+ * Options other than `project` and `org` override the defaults passed to `sentryVitePlugin`;
+ * `release` and `sourcemaps` are merged into them.
+ */
+export declare function anzuSentry(options: AnzuSentryOptions): PluginOption[]
+
+/** Chains the source maps common-admin publishes into the admin's build (only when it emits maps). */
+export declare function commonAdminSourcemaps(): Plugin
+
+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).
+   */
+  prebundle?: boolean
+}
+
+/**
+ * Local development against a common-admin copied into node_modules (`copy.sh`, `yarn dev:admin`):
+ * reacts to `.common-admin-updated`. Does nothing in a build.
+ */
+export declare function commonAdminDevWatch(options?: CommonAdminDevWatchOptions): Plugin

package/src/vite/index.mjs

@@ -0,0 +1,3 @@
+export { anzuSentry } from './sentry.mjs'
+export { commonAdminSourcemaps } from './sourcemaps.mjs'
+export { commonAdminDevWatch } from './devWatch.mjs'

package/src/vite/sentry.mjs

@@ -0,0 +1,80 @@
+import { createRequire } from 'node:module'
+import { resolve, sep } from 'node:path'
+import { commonAdminSourcemaps } from './sourcemaps.mjs'
+
+/**
+ * `@sentry/vite-plugin` is an optional peer, and `anzuSentry()` has to hand its plugins to
+ * `plugins: []` synchronously, so a lazy `import()` is not an option.
+ */
+function loadSentryVitePlugin() {
+  try {
+    return createRequire(import.meta.url)('@sentry/vite-plugin').sentryVitePlugin
+  } catch (error) {
+    throw new Error(
+      'anzuSentry: Sentry is enabled (APP_DEPLOY_ENV and SENTRY_URL are set), but @sentry/vite-plugin ' +
+        'cannot be loaded. Add it to the devDependencies of the admin.',
+      { cause: error }
+    )
+  }
+}
+
+/**
+ * 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[]}
+ */
+export function anzuSentry({ project, org = 'petitpress', release, sourcemaps, ...overrides }) {
+  const env = process.env
+  const enabled = !!env.APP_DEPLOY_ENV && !!env.SENTRY_URL
+  if (!enabled) return [commonAdminSourcemaps()]
+
+  const authToken = overrides.authToken ?? env.SENTRY_AUTH_TOKEN
+  const missing = Object.entries({ SENTRY_AUTH_TOKEN: authToken, org, project })
+    .filter(([, value]) => !value)
+    .map(([name]) => name)
+  if (missing.length > 0) {
+    throw new Error(`anzuSentry: Sentry is enabled, but ${missing.join(', ')} is empty.`)
+  }
+
+  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.
+  let resolveOutDir
+  const filesToDeleteAfterUpload = new Promise((resolveGlob) => {
+    resolveOutDir = (outDir) => resolveGlob(`${outDir.split(sep).join('/')}/**/*.js.map`)
+  })
+
+  return [
+    commonAdminSourcemaps(),
+    {
+      name: 'anzu:sentry-config',
+      apply: 'build',
+      config() {
+        return { build: { sourcemap: 'hidden' } }
+      },
+      configResolved(config) {
+        resolveOutDir(resolve(config.root, config.build.outDir))
+      },
+    },
+    ...sentryVitePlugin({
+      url: env.SENTRY_URL,
+      authToken,
+      org,
+      project,
+      telemetry: false,
+      errorHandler: (error) => {
+        throw error
+      },
+      ...overrides,
+      release: { name: env.GITVAR_SHORTVERSION, ...release },
+      sourcemaps: { filesToDeleteAfterUpload, ...sourcemaps },
+    }),
+  ]
+}

package/src/vite/sourcemaps.mjs

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+const LIBRARY_DIST_FILE = /[\\/]node_modules[\\/]@anzusystems[\\/]common-admin[\\/]dist[\\/].+\.m?js$/
+const SOURCE_MAPPING_URL = /\/\/# sourceMappingURL=([^\s'"]+)\s*$/
+
+/**
+ * Feeds the source maps common-admin publishes into the admin's build.
+ *
+ * Vite ignores `sourceMappingURL` in files it loads from node_modules, so without this the admin's
+ * maps end at `dist/common-admin.js` and Sentry shows the library minified. Loading the file
+ * together with its map lets the bundler chain them: frames resolve to the library's `.vue` and
+ * `.ts` sources. Does nothing unless the build emits source maps.
+ *
+ * @returns {import('vite').Plugin}
+ */
+export function commonAdminSourcemaps() {
+  let enabled = false
+
+  return {
+    name: 'anzu:common-admin-sourcemaps',
+    apply: 'build',
+    enforce: 'pre',
+    configResolved(config) {
+      enabled = !!config.build.sourcemap
+    },
+    load: {
+      filter: { id: LIBRARY_DIST_FILE },
+      handler(id) {
+        if (!enabled) return null
+        const code = readFileSync(id, 'utf8')
+        const mapFile = resolve(dirname(id), code.match(SOURCE_MAPPING_URL)?.[1] ?? `${id}.map`)
+        if (!existsSync(mapFile)) return null
+        return { code, map: readFileSync(mapFile, 'utf8') }
+      },
+    },
+  }
+}