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

package/template/tools/scaffold/create-feature.mjs

@@ -0,0 +1,444 @@
+import { lstat, readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { format, resolveConfig } from 'prettier'
+import { fnCommitCreatedDirectoriesTransaction } from './workspace-transaction.mjs'
+
+const strCurrentDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strDefaultProjectRoot = path.resolve(strCurrentDirectory, '../..')
+const strFeatureTemplateDirectory = path.resolve(
+  strCurrentDirectory,
+  'templates/feature'
+)
+const strTestTemplateDirectory = path.resolve(
+  strDefaultProjectRoot,
+  'tests/unit/scaffoldFeatureTemplate'
+)
+const strTestTemplatePublicImport = '../../../tools/scaffold/templates/feature'
+const arrTemplateFiles = [
+  {
+    strDestinationRoot: 'src/features',
+    strFileName: 'index.ts',
+    strSourceRoot: strFeatureTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'src/features',
+    strFileName: 'model.ts',
+    strSourceRoot: strFeatureTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'src/features',
+    strFileName: 'queries.ts',
+    strSourceRoot: strFeatureTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'src/features',
+    strFileName: 'repository.ts',
+    strSourceRoot: strFeatureTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'src/features',
+    strFileName: 'types.ts',
+    strSourceRoot: strFeatureTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'tests/unit/features',
+    strFileName: 'featureTemplate.test.ts',
+    strOutputFileName: 'feature.test.ts',
+    strSourceRoot: strTestTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'tests/unit/features',
+    strFileName: 'queries.test.tsx',
+    strSourceRoot: strTestTemplateDirectory,
+  },
+  {
+    strDestinationRoot: 'tests/unit/features',
+    strFileName: 'publicContract.test.ts',
+    strSourceRoot: strTestTemplateDirectory,
+  },
+]
+
+const objFeatureNamePattern = /^[a-z][A-Za-z0-9]*$/
+const objModelNamePattern = /^[A-Z][A-Za-z0-9]*$/
+const objResourceKeyPattern = /^[a-z][a-z0-9]*(?:[-:][a-z0-9]+)*$/
+
+class FeatureCreationError extends Error {
+  constructor(strCode, strMessage) {
+    super(strMessage)
+    this.name = 'FeatureCreationError'
+    this.strCode = strCode
+  }
+}
+
+const fnToUpperSnakeCase = (strValue) =>
+  strValue
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+    .toUpperCase()
+
+const fnToKebabCase = (strValue) =>
+  strValue.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+
+const fnReplaceAll = (strSource, strSearch, strReplacement) =>
+  strSource.split(strSearch).join(strReplacement)
+
+const fnTransformTemplate = (
+  strSource,
+  { strFeatureName, strModelName, strResourceKey }
+) => {
+  const strFeatureClassName =
+    strFeatureName.charAt(0).toUpperCase() + strFeatureName.slice(1)
+  const strFeatureSlug = fnToKebabCase(strFeatureName)
+  const strModelCode = fnToUpperSnakeCase(strModelName)
+  const arrReplacements = [
+    [strTestTemplatePublicImport, `@/features/${strFeatureName}`],
+    ['featureTemplate', strFeatureName],
+    ['TemplateRecord', strModelName],
+    ['Feature template', `${strFeatureClassName} Feature`],
+    ['template:record', strResourceKey],
+    ['template-user', `${strFeatureSlug}-user`],
+    ['TEMPLATE_RECORD', strModelCode],
+    ['TEMPLATE_INVALID_RESPONSE', `${strModelCode}_INVALID_RESPONSE`],
+    ['Template', strFeatureClassName],
+    ["'records'", `'${strResourceKey}'`],
+  ]
+
+  return arrReplacements.reduce(
+    (strResult, [strSearch, strReplacement]) =>
+      fnReplaceAll(strResult, strSearch, strReplacement),
+    strSource
+  )
+}
+
+const fnAssertSourceFile = async (strFilePath) => {
+  let objStats
+  try {
+    objStats = await lstat(strFilePath)
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_SOURCE_INVALID',
+      `模板文件不存在：${strFilePath}。${strReason}`
+    )
+  }
+  if (!objStats.isFile() || objStats.isSymbolicLink()) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_SOURCE_INVALID',
+      `模板必须是普通文件且不能是符号链接：${strFilePath}。`
+    )
+  }
+}
+
+const fnAssertDestinationAvailable = async (
+  strProjectRoot,
+  strDestinationRoot,
+  strFeatureName
+) => {
+  const strParentPath = path.resolve(strProjectRoot, strDestinationRoot)
+  let objParentStats
+  try {
+    objParentStats = await lstat(strParentPath)
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_TARGET_INVALID',
+      `目标父目录不存在：${strDestinationRoot}。${strReason}`
+    )
+  }
+  if (!objParentStats.isDirectory() || objParentStats.isSymbolicLink()) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_TARGET_INVALID',
+      `目标父目录必须是普通目录且不能是符号链接：${strDestinationRoot}。`
+    )
+  }
+
+  const arrEntries = await readdir(strParentPath)
+  const strCollision = arrEntries.find(
+    (strEntry) =>
+      strEntry.toLocaleLowerCase() === strFeatureName.toLocaleLowerCase()
+  )
+  if (strCollision) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_CONFLICT',
+      `目标已存在：${path.join(strDestinationRoot, strCollision)}。生成器不会覆盖已有 Feature。`
+    )
+  }
+  return path.resolve(strParentPath, strFeatureName)
+}
+
+const fnValidateOptions = ({
+  strFeatureName,
+  strModelName,
+  strResourceKey,
+}) => {
+  if (
+    !strFeatureName ||
+    strFeatureName.length > 60 ||
+    !objFeatureNamePattern.test(strFeatureName) ||
+    strFeatureName === 'featureTemplate'
+  ) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_ARGUMENT_INVALID',
+      '--name 必须是 1 到 60 位 lowerCamelCase，且不能使用 featureTemplate。'
+    )
+  }
+  if (
+    !strModelName ||
+    strModelName.length > 60 ||
+    !objModelNamePattern.test(strModelName) ||
+    ['Template', 'TemplateRecord'].includes(strModelName)
+  ) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_ARGUMENT_INVALID',
+      '--model 必须是 1 到 60 位 PascalCase，且不能保留模板名称。'
+    )
+  }
+  if (
+    !strResourceKey ||
+    strResourceKey.length > 100 ||
+    !objResourceKeyPattern.test(strResourceKey)
+  ) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_ARGUMENT_INVALID',
+      '--resource 必须是小写字母开头的稳定资源或权限前缀，例如 customer:record。'
+    )
+  }
+}
+
+const fnCreateFilePlans = async (
+  strProjectRoot,
+  objOptions,
+  objPrettierConfig
+) => {
+  const arrPlans = []
+  for (const objTemplateFile of arrTemplateFiles) {
+    const strSourcePath = path.resolve(
+      objTemplateFile.strSourceRoot,
+      objTemplateFile.strFileName
+    )
+    await fnAssertSourceFile(strSourcePath)
+    const strOutputFileName =
+      objTemplateFile.strOutputFileName ?? objTemplateFile.strFileName
+    const strRelativePath = path.join(
+      objTemplateFile.strDestinationRoot,
+      objOptions.strFeatureName,
+      strOutputFileName
+    )
+    const strTransformedSource = fnTransformTemplate(
+      await readFile(strSourcePath, 'utf8'),
+      objOptions
+    )
+    const strContent = await format(strTransformedSource, {
+      ...objPrettierConfig,
+      filepath: path.resolve(strProjectRoot, strRelativePath),
+    })
+    const arrUnresolvedTokens = [
+      'featureTemplate',
+      'TemplateRecord',
+      'TEMPLATE_',
+      'template:record',
+      'template-user',
+      strTestTemplatePublicImport,
+    ].filter((strToken) => strContent.includes(strToken))
+    if (arrUnresolvedTokens.length > 0) {
+      throw new FeatureCreationError(
+        'FEATURE_CREATE_OUTPUT_INVALID',
+        `生成文件仍包含模板标识 ${arrUnresolvedTokens.join(', ')}：${strRelativePath}。`
+      )
+    }
+    arrPlans.push({ strContent, strRelativePath })
+  }
+  return arrPlans
+}
+
+const fnWriteFeature = async (strProjectRoot, strFeatureName, arrPlans) => {
+  const arrDestinationDirectories = [
+    path.resolve(strProjectRoot, 'src/features', strFeatureName),
+    path.resolve(strProjectRoot, 'tests/unit/features', strFeatureName),
+  ]
+  await fnCommitCreatedDirectoriesTransaction({
+    arrDirectoryPaths: arrDestinationDirectories,
+    arrFiles: arrPlans.map((objPlan) => ({
+      strContent: objPlan.strContent,
+      strTargetPath: path.resolve(strProjectRoot, objPlan.strRelativePath),
+    })),
+    fnCreateError: (objError) =>
+      new FeatureCreationError(
+        objError?.code === 'EEXIST'
+          ? 'FEATURE_CREATE_CONFLICT'
+          : 'FEATURE_CREATE_WRITE_FAILED',
+        objError instanceof Error
+          ? `Feature 写入失败且已清理未完成目录：${objError.message}`
+          : 'Feature 写入失败且已清理未完成目录。'
+      ),
+  })
+}
+
+/**
+ * 从仓库中性模板生成 Feature 源码和契约测试；默认只预览且永不覆盖已有目录。
+ */
+export async function fnCreateFeature({
+  bWrite = false,
+  strFeatureName,
+  strModelName,
+  strProjectRoot = strDefaultProjectRoot,
+  strResourceKey,
+}) {
+  const objOptions = { strFeatureName, strModelName, strResourceKey }
+  fnValidateOptions(objOptions)
+  const strResolvedProjectRoot = path.resolve(strProjectRoot)
+  await Promise.all([
+    fnAssertDestinationAvailable(
+      strResolvedProjectRoot,
+      'src/features',
+      strFeatureName
+    ),
+    fnAssertDestinationAvailable(
+      strResolvedProjectRoot,
+      'tests/unit/features',
+      strFeatureName
+    ),
+  ])
+  const objPrettierConfig = {
+    ...((await resolveConfig(
+      path.resolve(strDefaultProjectRoot, 'package.json')
+    )) ?? {}),
+  }
+  delete objPrettierConfig.plugins
+  delete objPrettierConfig.tailwindFunctions
+  delete objPrettierConfig.tailwindStylesheet
+  const arrFiles = await fnCreateFilePlans(
+    strResolvedProjectRoot,
+    objOptions,
+    objPrettierConfig
+  )
+  if (bWrite) {
+    await fnWriteFeature(strResolvedProjectRoot, strFeatureName, arrFiles)
+  }
+  return {
+    arrFiles: arrFiles.map((objFile) => objFile.strRelativePath),
+    bWrite,
+    strFeatureName,
+  }
+}
+
+const fnParseArguments = (arrArguments) => {
+  const objValues = new Map()
+  let bHelp = false
+  let bWrite = false
+
+  for (let nIndex = 0; nIndex < arrArguments.length; nIndex += 1) {
+    const strArgument = arrArguments[nIndex]
+    if (strArgument === '--' && nIndex === 0) continue
+    if (strArgument === '--help') {
+      bHelp = true
+      continue
+    }
+    if (strArgument === '--write') {
+      if (bWrite) {
+        throw new FeatureCreationError(
+          'FEATURE_CREATE_ARGUMENT_INVALID',
+          '--write 不能重复声明。'
+        )
+      }
+      bWrite = true
+      continue
+    }
+    if (['--model', '--name', '--resource'].includes(strArgument)) {
+      if (objValues.has(strArgument)) {
+        throw new FeatureCreationError(
+          'FEATURE_CREATE_ARGUMENT_INVALID',
+          `${strArgument} 不能重复声明。`
+        )
+      }
+      const strValue = arrArguments[nIndex + 1]
+      if (!strValue || strValue.startsWith('--')) {
+        throw new FeatureCreationError(
+          'FEATURE_CREATE_ARGUMENT_INVALID',
+          `${strArgument} 必须提供值。`
+        )
+      }
+      objValues.set(strArgument, strValue)
+      nIndex += 1
+      continue
+    }
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_ARGUMENT_INVALID',
+      `不支持参数 ${strArgument}。`
+    )
+  }
+
+  if (bHelp && (bWrite || objValues.size > 0)) {
+    throw new FeatureCreationError(
+      'FEATURE_CREATE_ARGUMENT_INVALID',
+      '--help 不能与其他参数组合。'
+    )
+  }
+  return {
+    bHelp,
+    bWrite,
+    strFeatureName: objValues.get('--name'),
+    strModelName: objValues.get('--model'),
+    strResourceKey: objValues.get('--resource'),
+  }
+}
+
+const fnPrintUsage = () => {
+  process.stdout.write(
+    [
+      '用法：',
+      '  pnpm scaffold:feature --name <lowerCamelCase> --model <PascalCase> --resource <resource> ',
+      '  pnpm scaffold:feature --name <name> --model <model> --resource <resource> --write',
+      '',
+      '默认只预览；生成源码与契约测试，但不会注册路由、菜单或生成 API 客户端。',
+      '',
+    ].join('\n')
+  )
+}
+
+const fnPrintResult = (objResult) => {
+  const strMode = objResult.bWrite ? 'WRITE' : 'PREVIEW'
+  for (const strFilePath of objResult.arrFiles) {
+    process.stdout.write(`[${strMode}] CREATE ${strFilePath}\n`)
+  }
+  process.stdout.write(
+    `\nFeature ${objResult.strFeatureName}：${objResult.bWrite ? '已创建' : '将创建'} ${objResult.arrFiles.length} 个文件。\n`
+  )
+  if (objResult.bWrite) {
+    process.stdout.write(
+      '下一步：接入生成客户端、按真实契约改写模型，并显式注册页面路由。\n'
+    )
+  } else {
+    process.stdout.write(
+      '确认目录和命名后追加 --write；当前没有修改任何文件。\n'
+    )
+  }
+}
+
+const fnRunCli = async () => {
+  try {
+    const objArguments = fnParseArguments(process.argv.slice(2))
+    if (objArguments.bHelp) {
+      fnPrintUsage()
+      return
+    }
+    const objResult = await fnCreateFeature(objArguments)
+    fnPrintResult(objResult)
+  } catch (objError) {
+    const strCode =
+      objError instanceof FeatureCreationError
+        ? objError.strCode
+        : 'FEATURE_CREATE_FAILED'
+    const strMessage =
+      objError instanceof Error ? objError.message : 'Feature 创建失败。'
+    process.stderr.write(`[ERROR] ${strCode} ${strMessage}\n`)
+    process.exitCode = 1
+  }
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  await fnRunCli()
+}