@anzusystems/common-admin 1.49.0 → 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

@@ -0,0 +1,246 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+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 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
+  if (Array.isArray(entry)) return entry.map(importTarget).find(Boolean)
+  if (!entry || typeof entry !== 'object') return undefined
+  if (Object.keys(entry).some((key) => key.startsWith('.'))) return importTarget(entry['.'])
+  for (const [condition, target] of Object.entries(entry)) {
+    if (IMPORT_CONDITIONS.has(condition)) {
+      const resolved = importTarget(target)
+      if (resolved) return resolved
+    }
+  }
+  return undefined
+}
+
+// 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)
+    if (fs.existsSync(path.join(dir, 'package.json'))) return fs.realpathSync(dir)
+  }
+  return undefined
+}
+
+const loader = (root) => {
+  const require = createRequire(root)
+  return (name) => {
+    const dir = packageDir(require, name)
+    const exports = dir ? JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8')).exports : undefined
+    const target = exports === undefined ? undefined : importTarget(exports)
+    return import(pathToFileURL(target ? path.join(dir, target) : require.resolve(name)).href)
+  }
+}
+
+// The component names in the admin's installed Vuetify, for `vue/no-undef-components`: registered by
+// vite-plugin-vuetify, never imported, so the rule cannot see them otherwise.
+const vuetifyComponents = (root) => {
+  try {
+    const content = fs.readFileSync(new URL('./node_modules/vuetify/dist/vuetify.d.ts', root), 'utf-8')
+    const match = content.match(/interface GlobalComponents \{([\s\S]*?)\}/)
+    return match?.[1] ? Array.from(match[1].matchAll(/^\s+([V][a-zA-Z0-9]+):/gm), (m) => m[1]) : []
+  } catch (e) {
+    console.error('Error reading vuetify.d.ts', e)
+    return []
+  }
+}
+
+const routeNameSeverity = (value) => (value === false || value === 'off' ? 'off' : value === 'warn' ? 'warn' : 'error')
+
+/**
+ * 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 {
+    root,
+    oxlintConfig = '.oxlintrc.json',
+    typedRouter = 'src/typed-router.d.ts',
+    globalComponents = [],
+    ignores = [],
+    noExplicitAny = 'error',
+    anzu = {},
+    vueProject = {},
+  } = options
+  // A plain path is read as the path of the config file, like `import.meta.url` is.
+  const rootUrl = String(root).startsWith('file:') ? String(root) : pathToFileURL(String(root)).href
+  const load = loader(rootUrl)
+  const { configureVueProject, defineConfigWithVueTs, vueTsConfigs } = await load('@vue/eslint-config-typescript')
+  // Its `.vue` scan for type-aware rules starts at the admin's root rather than the cwd.
+  configureVueProject({ rootDir: fileURLToPath(new URL('.', rootUrl)), ...vueProject })
+  const plugin = async (name) => {
+    const module = await load(name)
+    return module.default ?? module
+  }
+  const pluginVue = await plugin('eslint-plugin-vue')
+  const pluginPinia = await plugin('eslint-plugin-pinia')
+  const vuetify = await plugin('eslint-plugin-vuetify')
+  const oxlint = oxlintConfig ? await plugin('eslint-plugin-oxlint') : null
+
+  return defineConfigWithVueTs(
+    {
+      name: 'app/files-to-lint',
+      files: ['**/*.{ts,mts,tsx,vue}'],
+    },
+    {
+      name: 'app/files-to-ignore',
+      ignores: [
+        '**/dist/**',
+        '**/dist-ssr/**',
+        '**/coverage/**',
+        '.stylelintrc.js',
+        '**/e2e/**',
+        'src/typed-router.d.ts',
+        ...ignores,
+      ],
+    },
+    pluginVue.configs['flat/essential'],
+    pluginVue.configs['flat/strongly-recommended'],
+    pluginVue.configs['flat/recommended'],
+    vueTsConfigs.recommended,
+    {
+      name: 'app/pinia',
+      plugins: {
+        pinia: pluginPinia,
+      },
+      rules: {
+        'pinia/never-export-initialized-store': 'error',
+        'pinia/no-duplicate-store-ids': 'error',
+        'pinia/no-return-global-properties': 'error',
+        'pinia/no-store-to-refs-in-store': 'error',
+        'pinia/prefer-single-store-per-file': 'error',
+        'pinia/prefer-use-store-naming-convention': 'error',
+        'pinia/require-setup-store-properties-export': 'error',
+      },
+    },
+    recommended(anzu),
+    {
+      name: 'app/rules',
+      settings: {
+        anzu: { typedRouter: fileURLToPath(new URL(typedRouter, rootUrl)) },
+      },
+      rules: {
+        'anzu/valid-route-name': routeNameSeverity(anzu.validRouteName),
+        '@typescript-eslint/ban-ts-comment': 'off',
+        '@typescript-eslint/no-explicit-any': noExplicitAny,
+        '@typescript-eslint/no-empty-interface': 'off',
+        '@typescript-eslint/no-empty-object-type': 'off',
+        '@typescript-eslint/no-unused-expressions': 'off',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            caughtErrors: 'none',
+          },
+        ],
+        'vue/multi-word-component-names': [
+          'error',
+          {
+            ignores: ['Acl'],
+          },
+        ],
+        'vue/valid-v-slot': ['error', { allowModifiers: true }],
+        'vue/no-undef-components': [
+          'error',
+          {
+            // 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,
+              'RouterLink',
+              'RouterView',
+              ...globalComponents,
+            ],
+          },
+        ],
+        'vue/attribute-hyphenation': ['error', 'always'],
+        'vue/v-on-event-hyphenation': ['error', 'always'],
+        'vue/custom-event-name-casing': ['error', 'camelCase'],
+        // `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'],
+        'vue/component-name-in-template-casing': ['error'],
+        'vue/component-api-style': ['error'],
+        'vue/prefer-define-options': ['error'],
+        'vue/no-setup-props-reactivity-loss': ['error'],
+        'vue/no-ref-object-reactivity-loss': ['error'],
+      },
+    },
+    {
+      name: 'app/no-relative-imports',
+      files: ['src/**/*.{ts,vue}'],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              {
+                group: ['../*', './*'],
+                message: 'Use absolute imports with @ instead of relative imports',
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      // File-based routing names these files, not us: `index.vue`, `new.vue`, `edit.vue`.
+      name: 'app/file-based-routing',
+      files: ['src/pages/**/*.vue'],
+      rules: {
+        'vue/multi-word-component-names': 'off',
+      },
+    },
+    {
+      name: 'app/test-files',
+      files: ['**/*.test.{ts,js}', '**/*.spec.{ts,js}', '**/test/**/*.{ts,js}'],
+      rules: {
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        'vue/one-component-per-file': 'off',
+      },
+    },
+    ...vuetify.configs['flat/recommended-v4'],
+    // 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 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',
+        'vue/html-indent': 'off',
+        'vue/singleline-html-element-content-newline': 'off',
+        'vue/html-self-closing': [
+          'error',
+          {
+            html: { void: 'any', normal: 'always', component: 'always' },
+            svg: 'always',
+            math: 'always',
+          },
+        ],
+      },
+    },
+    ...extra
+  )
+}

package/src/eslint/globalComponentNames.d.mts

@@ -0,0 +1,9 @@
+/** The components the library registers globally: for the `ignorePatterns` of `vue/no-undef-components`. */
+export declare const globalComponentNames: readonly [
+  'ABtnPrimary',
+  'ABtnSecondary',
+  'ABtnTertiary',
+  'ABtnIcon',
+  'AChipNoLink',
+  'Acl',
+]

package/src/eslint/globalComponentNames.mjs

@@ -0,0 +1,14 @@
+// Its own module, without the preset's node imports: a browser test imports it as well.
+/**
+ * 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',
+  'ABtnSecondary',
+  'ABtnTertiary',
+  'ABtnIcon',
+  'AChipNoLink',
+  'Acl',
+])

package/src/eslint/oxlint-admin.json

@@ -0,0 +1,48 @@
+{
+  // The oxlint rules the admins share; an admin's .oxlintrc.json extends it and keeps its own env,
+  // categories and ignorePatterns (oxlint merges only rules, plugins and overrides from `extends`, and
+  // eslint-plugin-oxlint follows `extends` the same way).
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "vue", "import"],
+  "rules": {
+    "no-unused-vars": ["error", { "caughtErrors": "none" }],
+    "no-unused-expressions": "off",
+
+    "no-var": "error",
+    "prefer-rest-params": "error",
+    "prefer-spread": "error",
+    "typescript/no-array-constructor": "error",
+    "typescript/no-namespace": "error",
+    "typescript/no-require-imports": "error",
+    "typescript/no-unnecessary-type-constraint": "error",
+    "typescript/no-unsafe-function-type": "error",
+    "vue/component-definition-name-casing": "error",
+    "vue/no-multiple-slot-args": "error",
+    "vue/no-required-prop-with-default": "error",
+    "vue/prop-name-casing": "error",
+    "vue/require-default-prop": "error",
+    "vue/require-prop-types": "error",
+    "vue/require-typed-ref": "error",
+
+    // oxlint does not run prefer-const inside a .vue file at all, so handing it over
+    // would switch it off for every SFC. Left to eslint, which does both.
+    "prefer-const": "off",
+
+    // Enabled here, so that eslint stops running its copies: it had to while the imports were implicit.
+    "vue/no-async-in-computed-properties": "error",
+    "vue/no-side-effects-in-computed-properties": "error",
+    "vue/return-in-computed-property": "error",
+    "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 }],
+    "import/no-duplicates": ["error", { "considerQueryString": true }],
+    "import/consistent-type-specifier-style": ["error", "prefer-top-level"],
+    // Reads `@/typed-router.d.ts?raw` in the route tests as a module without a default export.
+    "import/default": "off"
+  }
+}

package/src/eslint/oxlint.mjs

@@ -0,0 +1,15 @@
+import { anzuPlugin } from './plugin.mjs'
+
+/**
+ * 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' },
+  rules: anzuPlugin.rules,
+}

package/src/eslint/plugin.d.mts

@@ -0,0 +1,62 @@
+import type { ESLint, Linter } from 'eslint'
+
+/**
+ * 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
+
+type Severity = boolean | 'error' | 'warn' | 'off'
+
+export interface RecommendedOptions {
+  noTsExtension?: Severity
+  preferApiCommand?: Severity
+  preferApiFetchItems?: Severity
+  urlParamsMatchTemplate?: Severity
+  /** @deprecated The rule is gone with the helpers it guarded; the option is ignored. */
+  deprecatedImports?: Severity
+}
+
+/** One flat-config block: the plugin plus the rule severities the options ask for. */
+export declare function recommended(options?: RecommendedOptions): {
+  plugins: Record<string, ESLint.Plugin>
+  rules: Linter.RulesRecord
+}
+
+export interface AnzuAdminEslintOptions {
+  /**
+   * The admin's `import.meta.url` (of its eslint.config.mjs), or that file's path; everything below
+   * resolves against it.
+   */
+  root: string | URL
+  /** Default `.oxlintrc.json`; its enabled rules are switched off in eslint. `false` skips that. */
+  oxlintConfig?: string | false
+  /** Default `src/typed-router.d.ts`, read by `anzu/valid-route-name`. */
+  typedRouter?: string
+  /** More globally registered components for `vue/no-undef-components` (inhouse: the `GMap*` family). */
+  globalComponents?: string[]
+  /** Added to the ignored paths. */
+  ignores?: string[]
+  /** Default `'error'`. */
+  noExplicitAny?: 'error' | 'warn' | 'off'
+  anzu?: RecommendedOptions & { validRouteName?: Severity }
+  /**
+   * `configureVueProject()` of `@vue/eslint-config-typescript`, applied by the preset. `rootDir`
+   * defaults to the admin's directory.
+   */
+  vueProject?: {
+    scriptLangs?: string[]
+    tsSyntaxInTemplates?: boolean
+    allowComponentTypeUnsafety?: boolean
+    rootDir?: string
+    includeDotFolders?: boolean
+  }
+}
+
+/** The whole eslint config of an admin; `extra` configs come last. */
+export declare function defineAnzuAdminConfig(
+  options: AnzuAdminEslintOptions,
+  ...extra: Linter.Config[]
+): Promise<Linter.Config[]>
+
+export { globalComponentNames } from './globalComponentNames.mjs'