create-react-admin-template 0.0.0-stage → 0.1.0

package/template/tools/scaffold/check.mjs

@@ -0,0 +1,326 @@
+import { createServer, loadConfigFromFile } from 'vite'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const strCurrentDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strProjectRoot = path.resolve(strCurrentDirectory, '../..')
+const bStrict = process.argv.includes('--strict')
+const arrUnknownArguments = process.argv
+  .slice(2)
+  .filter((strArgument) => strArgument !== '--strict')
+const arrFindings = []
+
+const fnAddFinding = (strLevel, strCode, strMessage, strFix) => {
+  arrFindings.push({ strLevel, strCode, strMessage, strFix })
+}
+
+const fnReadJson = async (strRelativePath) => {
+  const strFilePath = path.resolve(strProjectRoot, strRelativePath)
+  const strSource = await readFile(strFilePath, 'utf8')
+  return JSON.parse(strSource)
+}
+
+const fnCompareVersions = (arrCurrent, arrRequired) => {
+  for (let nIndex = 0; nIndex < 3; nIndex += 1) {
+    if (arrCurrent[nIndex] !== arrRequired[nIndex]) {
+      return arrCurrent[nIndex] - arrRequired[nIndex]
+    }
+  }
+  return 0
+}
+
+const fnIsNodeVersionSupported = (strVersion, strRange) => {
+  const arrCurrent = strVersion.split('.').map(Number)
+  const arrBranches = strRange.split('||').map((strBranch) => strBranch.trim())
+
+  return arrBranches.some((strBranch) => {
+    const objMatch = /^(\^|>=)(\d+)\.(\d+)\.(\d+)$/.exec(strBranch)
+    if (!objMatch) return false
+    const [, strOperator, ...arrRequiredParts] = objMatch
+    const arrRequired = arrRequiredParts.map(Number)
+    if (strOperator === '^' && arrCurrent[0] !== arrRequired[0]) return false
+    return fnCompareVersions(arrCurrent, arrRequired) >= 0
+  })
+}
+
+const fnCheckArguments = () => {
+  if (arrUnknownArguments.length === 0) return
+  fnAddFinding(
+    'error',
+    'CLI_ARGUMENT_INVALID',
+    `不支持参数 ${arrUnknownArguments.join(', ')}。`,
+    '只使用 pnpm scaffold:check 或 pnpm scaffold:check --strict。'
+  )
+}
+
+const fnCheckToolchain = async () => {
+  try {
+    const [objPackage, strRecommendedNode] = await Promise.all([
+      fnReadJson('package.json'),
+      readFile(path.resolve(strProjectRoot, '.nvmrc'), 'utf8'),
+    ])
+    if (!objPackage.packageManager?.startsWith('pnpm@')) {
+      fnAddFinding(
+        'error',
+        'PACKAGE_MANAGER_MISSING',
+        'package.json 没有锁定 pnpm 版本。',
+        '恢复 packageManager 字段并使用 Corepack 安装声明的 pnpm 版本。'
+      )
+    } else if (
+      !fnIsNodeVersionSupported(
+        process.versions.node,
+        objPackage.engines?.node ?? ''
+      )
+    ) {
+      fnAddFinding(
+        'error',
+        'NODE_VERSION_UNSUPPORTED',
+        `当前 Node ${process.versions.node} 不满足 package.json#engines.node。`,
+        '执行 nvm use 后重新安装依赖并再次检查。'
+      )
+    } else {
+      fnAddFinding(
+        'pass',
+        'TOOLCHAIN_READY',
+        `Node ${process.versions.node} 与 ${objPackage.packageManager} 声明完整；.nvmrc 推荐 ${strRecommendedNode.trim()}。`
+      )
+    }
+
+    if (objPackage.name === 'enterprise-react-admin') {
+      fnAddFinding(
+        'warning',
+        'PACKAGE_NAME_PLACEHOLDER',
+        'package.json 仍使用脚手架默认包名。',
+        '在首次提交前改为项目稳定英文标识，并同步部署和监控中的应用名。'
+      )
+    }
+  } catch (objError) {
+    fnAddFinding(
+      'error',
+      'TOOLCHAIN_CONFIG_INVALID',
+      '无法读取 package.json 或 .nvmrc。',
+      objError instanceof Error
+        ? `修复文件后重试。原因：${objError.message}`
+        : '修复文件后重试。'
+    )
+  }
+}
+
+const fnCheckBuildConfiguration = async () => {
+  const strConfigPath = path.resolve(strProjectRoot, 'vite.config.ts')
+
+  try {
+    const [objDevelopmentConfig, objProductionConfig] = await Promise.all([
+      loadConfigFromFile(
+        { command: 'serve', mode: 'development' },
+        strConfigPath,
+        strProjectRoot,
+        'silent'
+      ),
+      loadConfigFromFile(
+        { command: 'build', mode: 'production' },
+        strConfigPath,
+        strProjectRoot,
+        'silent'
+      ),
+    ])
+    if (!objDevelopmentConfig || !objProductionConfig) {
+      throw new TypeError('无法加载 vite.config.ts。')
+    }
+    fnAddFinding(
+      'pass',
+      'BUILD_CONFIG_READY',
+      'development 与 production 的 Vite 公开配置均通过校验。'
+    )
+  } catch (objError) {
+    fnAddFinding(
+      'error',
+      'BUILD_CONFIG_INVALID',
+      objError instanceof Error
+        ? objError.message
+        : 'Vite 配置校验发生未知错误。',
+      '按错误中的环境变量和修复动作更新 .env.local 或对应 Mode 文件。'
+    )
+  }
+}
+
+const fnCheckRuntimeConfiguration = async () => {
+  let objRuntimeConfig
+
+  try {
+    objRuntimeConfig = await fnReadJson('public/runtime-config.json')
+  } catch (objError) {
+    fnAddFinding(
+      'error',
+      'RUNTIME_CONFIG_JSON_INVALID',
+      'public/runtime-config.json 不存在或不是有效 JSON。',
+      objError instanceof Error
+        ? `修复 JSON 后重试。原因：${objError.message}`
+        : '修复 JSON 后重试。'
+    )
+    return
+  }
+
+  let objViteServer
+
+  try {
+    objViteServer = await createServer({
+      appType: 'custom',
+      configFile: false,
+      logLevel: 'silent',
+      root: strProjectRoot,
+      server: { middlewareMode: true },
+    })
+    const { fnParseRuntimeConfig } = await objViteServer.ssrLoadModule(
+      '/src/config/runtimeConfig.ts'
+    )
+    const objValidatedConfig = fnParseRuntimeConfig(objRuntimeConfig)
+    fnAddFinding(
+      'pass',
+      'RUNTIME_CONFIG_READY',
+      'runtime-config.json 已通过浏览器启动时使用的同一份 Zod 契约。'
+    )
+
+    if (
+      objValidatedConfig.app.strTitle === 'Enterprise Admin' ||
+      objValidatedConfig.app.strDescription === '企业管理控制台'
+    ) {
+      fnAddFinding(
+        'warning',
+        'APP_TITLE_PLACEHOLDER',
+        '应用标题或描述仍使用脚手架默认品牌文案。',
+        '修改 runtime-config.json 的 app.strTitle 和 app.strDescription。'
+      )
+    }
+    if (objValidatedConfig.app.strStorageNamespace === 'enterprise-admin') {
+      fnAddFinding(
+        'warning',
+        'STORAGE_NAMESPACE_PLACEHOLDER',
+        '浏览器存储命名空间仍使用脚手架默认值。',
+        '首次发布前设置项目唯一且稳定的 app.strStorageNamespace。'
+      )
+    }
+    if (objValidatedConfig.app.strMode === 'demo') {
+      fnAddFinding(
+        'warning',
+        'DEMO_MODE_ACTIVE',
+        '当前仍是 demo 模式，不会连接真实业务后端。',
+        '完成认证和 Repository Adapter 后切换为 connected，并重新执行检查。'
+      )
+    }
+    if (
+      objValidatedConfig.auth.strAudience === 'admin-api' ||
+      objValidatedConfig.auth.strClientId === 'react-admin'
+    ) {
+      fnAddFinding(
+        'warning',
+        'AUTH_CONFIG_PLACEHOLDER',
+        '认证 Audience 或公开 Client ID 仍使用脚手架默认值。',
+        '根据真实身份服务更新 runtime-config.json 的 auth 公开配置。'
+      )
+    }
+    if (
+      objValidatedConfig.app.strMode === 'connected' &&
+      objValidatedConfig.auth.strSessionStorage !== 'memory'
+    ) {
+      fnAddFinding(
+        'warning',
+        'CONNECTED_SESSION_STORAGE',
+        'connected 模式仍把会话写入 sessionStorage。',
+        '生产连接模式优先使用 memory，除非已完成明确的安全评审。'
+      )
+    }
+  } catch (objError) {
+    fnAddFinding(
+      'error',
+      'RUNTIME_CONFIG_INVALID',
+      objError instanceof Error
+        ? objError.message
+        : '运行时配置校验发生未知错误。',
+      '按字段路径修改 public/runtime-config.json；不得加入密钥。'
+    )
+  } finally {
+    await objViteServer?.close()
+  }
+}
+
+const fnCheckApiServices = async () => {
+  try {
+    const arrServices = await fnReadJson('src/api/config/services.json')
+    if (!Array.isArray(arrServices) || arrServices.length === 0) {
+      throw new TypeError('服务配置必须是非空数组。')
+    }
+    for (const [nIndex, objService] of arrServices.entries()) {
+      if (
+        !objService ||
+        typeof objService !== 'object' ||
+        typeof objService.name !== 'string' ||
+        typeof objService.baseUrlEnv !== 'string' ||
+        typeof objService.openapiPath !== 'string'
+      ) {
+        throw new TypeError(
+          `第 ${nIndex + 1} 项缺少 name/baseUrlEnv/openapiPath。`
+        )
+      }
+    }
+    fnAddFinding(
+      'pass',
+      'OPENAPI_SERVICES_READY',
+      `已识别 ${arrServices.length} 个 swagger-typescript-api 服务配置。`
+    )
+    if (arrServices.some((objService) => objService.name === 'backend')) {
+      fnAddFinding(
+        'warning',
+        'OPENAPI_SERVICE_PLACEHOLDER',
+        'OpenAPI 服务仍包含中性占位名 backend。',
+        '根据真实后端边界重命名服务，并重新执行 pnpm api。'
+      )
+    }
+  } catch (objError) {
+    fnAddFinding(
+      'error',
+      'OPENAPI_SERVICES_INVALID',
+      objError instanceof Error
+        ? objError.message
+        : 'OpenAPI 服务配置校验发生未知错误。',
+      '修复 src/api/config/services.json 后再执行 pnpm api。'
+    )
+  }
+}
+
+const fnPrintReport = () => {
+  const objLabels = { error: 'ERROR', pass: 'PASS', warning: 'WARN' }
+  for (const objFinding of arrFindings) {
+    process.stdout.write(
+      `[${objLabels[objFinding.strLevel]}] ${objFinding.strCode} ${objFinding.strMessage}\n`
+    )
+    if (objFinding.strFix) {
+      process.stdout.write(`       修复：${objFinding.strFix}\n`)
+    }
+  }
+
+  const nErrors = arrFindings.filter(
+    (objFinding) => objFinding.strLevel === 'error'
+  ).length
+  const nWarnings = arrFindings.filter(
+    (objFinding) => objFinding.strLevel === 'warning'
+  ).length
+  const bFailed = nErrors > 0 || (bStrict && nWarnings > 0)
+  const strSummary = bFailed
+    ? `脚手架检查失败：${nErrors} 个错误，${nWarnings} 个提醒。`
+    : `脚手架基础检查通过：${nWarnings} 个项目化提醒。`
+
+  process.stdout.write(`\n${strSummary}\n`)
+  if (bStrict && nWarnings > 0) {
+    process.stdout.write('严格模式要求在项目首次交付前处理全部提醒。\n')
+  }
+  if (bFailed) process.exitCode = 1
+}
+
+fnCheckArguments()
+await fnCheckToolchain()
+await fnCheckBuildConfiguration()
+await fnCheckRuntimeConfiguration()
+await fnCheckApiServices()
+fnPrintReport()