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

package/template/tests/unit/config/releaseArtifact.test.mjs

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import {
+  fnPrepareReleaseArtifact,
+  fnVerifyReleaseArtifact,
+} from '../../../tools/release/artifact.mjs'
+
+const strCommit = 'a'.repeat(40)
+
+const fnCreateFixture = async (objTestContext) => {
+  const strProjectRoot = await mkdtemp(
+    path.resolve(os.tmpdir(), 'react-admin-release-')
+  )
+  objTestContext.after(() =>
+    rm(strProjectRoot, { force: true, recursive: true })
+  )
+  await mkdir(path.resolve(strProjectRoot, 'dist/assets'), { recursive: true })
+  await mkdir(path.resolve(strProjectRoot, 'dist/.vite'), { recursive: true })
+  await Promise.all([
+    writeFile(
+      path.resolve(strProjectRoot, 'package.json'),
+      JSON.stringify({ version: '1.2.3' }),
+      'utf8'
+    ),
+    writeFile(
+      path.resolve(strProjectRoot, 'dist/index.html'),
+      '<main>release</main>',
+      'utf8'
+    ),
+    writeFile(
+      path.resolve(strProjectRoot, 'dist/assets/app.js'),
+      'console.log("release")',
+      'utf8'
+    ),
+    writeFile(
+      path.resolve(strProjectRoot, 'dist/runtime-config.json'),
+      '{"environment":"replace-at-deploy"}',
+      'utf8'
+    ),
+    writeFile(
+      path.resolve(strProjectRoot, 'dist/.vite/manifest.json'),
+      '{"index.html":{"file":"assets/app.js"}}',
+      'utf8'
+    ),
+  ])
+  return strProjectRoot
+}
+
+test('release artifact is deterministic and keeps runtime config external', async (objTestContext) => {
+  const strProjectRoot = await fnCreateFixture(objTestContext)
+  const objPreparedMetadata = await fnPrepareReleaseArtifact({
+    strCommit,
+    strProjectRoot,
+  })
+  const objVerifiedMetadata = await fnVerifyReleaseArtifact({
+    strExpectedCommit: strCommit,
+    strProjectRoot,
+  })
+  const strManifest = await readFile(
+    path.resolve(strProjectRoot, '.artifacts/release/artifact-manifest.sha256'),
+    'utf8'
+  )
+
+  assert.equal(objPreparedMetadata.strVersion, '1.2.3')
+  assert.deepEqual(objVerifiedMetadata, objPreparedMetadata)
+  assert.match(strManifest, /assets\/app\.js/)
+  assert.match(strManifest, /index\.html/)
+  assert.doesNotMatch(strManifest, /runtime-config\.json/)
+  assert.doesNotMatch(strManifest, /\.vite\/manifest\.json/)
+  await assert.rejects(
+    readFile(
+      path.resolve(
+        strProjectRoot,
+        '.artifacts/release/site/runtime-config.json'
+      )
+    ),
+    { code: 'ENOENT' }
+  )
+})
+
+test('release verification rejects content and commit identity drift', async (objTestContext) => {
+  const strProjectRoot = await fnCreateFixture(objTestContext)
+  await fnPrepareReleaseArtifact({ strCommit, strProjectRoot })
+
+  await assert.rejects(
+    fnVerifyReleaseArtifact({
+      strExpectedCommit: 'b'.repeat(40),
+      strProjectRoot,
+    }),
+    /提交身份/
+  )
+
+  await writeFile(
+    path.resolve(strProjectRoot, '.artifacts/release/site/assets/app.js'),
+    'tampered',
+    'utf8'
+  )
+  await assert.rejects(
+    fnVerifyReleaseArtifact({ strExpectedCommit: strCommit, strProjectRoot }),
+    /摘要不一致/
+  )
+})

package/template/tests/unit/config/runtimeConfig.test.ts

@@ -0,0 +1,225 @@
+import {
+  fnLoadRuntimeConfig,
+  fnParseRuntimeConfig,
+  RuntimeConfigError,
+} from '@/config/runtimeConfig'
+import { describe, expect, it, vi } from 'vitest'
+
+const objValidRuntimeConfig = {
+  nSchemaVersion: 1,
+  app: {
+    strTitle: ' Enterprise Admin ',
+    strDescription: ' 企业管理控制台 ',
+    strLogoPath: 'logo.svg',
+    strStorageNamespace: 'enterprise-admin',
+    strMode: 'demo',
+  },
+  api: {
+    strBaseUrl: 'https://api.example.com/',
+  },
+  auth: {
+    strAudience: 'admin-api',
+    strClientId: 'react-admin',
+    strScope: 'openid profile',
+    strSessionStorage: 'memory',
+    strSignInPath: '/api/v1/auth/login',
+    strRefreshPath: '/api/v1/auth/refresh',
+    strSignOutPath: '/api/v1/auth/logout',
+  },
+}
+
+describe('runtime configuration', () => {
+  it('normalizes and freezes a valid public configuration', () => {
+    const objConfig = fnParseRuntimeConfig(objValidRuntimeConfig)
+
+    expect(objConfig.app.strTitle).toBe('Enterprise Admin')
+    expect(objConfig.api.strBaseUrl).toBe('https://api.example.com')
+    expect(Object.isFrozen(objConfig)).toBe(true)
+    expect(Object.isFrozen(objConfig.app)).toBe(true)
+    expect(objConfig.app.strBrandId).toBe('enterprise-admin')
+    expect(objConfig.app.strDarkLogoPath).toBe('logo.svg')
+    expect(objConfig.app.strFaviconPath).toBe('favicon.ico')
+    expect(objConfig.app.objTheme.objLight).toEqual({
+      strPrimaryColor: '#4068d5',
+      strPrimaryForegroundColor: '#ffffff',
+      strSecondaryColor: '#49beff',
+      strSecondaryForegroundColor: '#102a43',
+      strBrowserThemeColor: '#ffffff',
+    })
+    expect(Object.isFrozen(objConfig.app.objTheme)).toBe(true)
+    expect(Object.isFrozen(objConfig.app.objTheme.objLight)).toBe(true)
+    expect(Object.isFrozen(objConfig.api)).toBe(true)
+    expect(Object.isFrozen(objConfig.auth)).toBe(true)
+    expect(objConfig.observability).toEqual({
+      bEnabled: false,
+      strEnvironment: 'local',
+    })
+    expect(Object.isFrozen(objConfig.observability)).toBe(true)
+    expect(objConfig.locale).toEqual({
+      strLocale: 'zh-CN',
+      strTimeZone: 'Asia/Shanghai',
+    })
+    expect(Object.isFrozen(objConfig.locale)).toBe(true)
+  })
+
+  it('accepts an explicit public observability environment without secrets', () => {
+    const objConfig = fnParseRuntimeConfig({
+      ...objValidRuntimeConfig,
+      observability: {
+        bEnabled: true,
+        strEnvironment: 'staging-cn',
+      },
+    })
+
+    expect(objConfig.observability).toEqual({
+      bEnabled: true,
+      strEnvironment: 'staging-cn',
+    })
+  })
+
+  it('accepts a supported locale and rejects an invalid IANA timezone', () => {
+    expect(
+      fnParseRuntimeConfig({
+        ...objValidRuntimeConfig,
+        locale: { strLocale: 'en-US', strTimeZone: 'UTC' },
+      }).locale
+    ).toEqual({ strLocale: 'en-US', strTimeZone: 'UTC' })
+
+    expect(() =>
+      fnParseRuntimeConfig({
+        ...objValidRuntimeConfig,
+        locale: { strLocale: 'zh-CN', strTimeZone: 'Mars/Olympus' },
+      })
+    ).toThrowError(RuntimeConfigError)
+  })
+
+  it('accepts restricted white-label assets and accessible semantic colors', () => {
+    const objConfig = fnParseRuntimeConfig({
+      ...objValidRuntimeConfig,
+      app: {
+        ...objValidRuntimeConfig.app,
+        strBrandId: 'acme.operations',
+        strDarkLogoPath: 'assets/acme-dark.png',
+        strFaviconPath: 'assets/acme-icon.png',
+        objTheme: {
+          objLight: {
+            strPrimaryColor: '#000000',
+            strPrimaryForegroundColor: '#ffffff',
+            strSecondaryColor: '#ffffff',
+            strSecondaryForegroundColor: '#000000',
+            strBrowserThemeColor: '#ffffff',
+          },
+          objDark: {
+            strPrimaryColor: '#ffffff',
+            strPrimaryForegroundColor: '#000000',
+            strSecondaryColor: '#000000',
+            strSecondaryForegroundColor: '#ffffff',
+            strBrowserThemeColor: '#000000',
+          },
+        },
+      },
+    })
+
+    expect(objConfig.app.strBrandId).toBe('acme.operations')
+    expect(objConfig.app.strDarkLogoPath).toBe('assets/acme-dark.png')
+    expect(objConfig.app.objTheme.objDark.strPrimaryColor).toBe('#ffffff')
+  })
+
+  it('rejects arbitrary CSS, unsafe image data and inaccessible color pairs', () => {
+    const objUnsafeTheme = {
+      ...objValidRuntimeConfig,
+      app: {
+        ...objValidRuntimeConfig.app,
+        objTheme: {
+          objLight: {
+            strPrimaryColor: 'var(--arbitrary)',
+            strPrimaryForegroundColor: '#ffffff',
+            strSecondaryColor: '#ffffff',
+            strSecondaryForegroundColor: '#000000',
+            strBrowserThemeColor: '#ffffff',
+          },
+          objDark: {
+            strPrimaryColor: '#ffffff',
+            strPrimaryForegroundColor: '#000000',
+            strSecondaryColor: '#000000',
+            strSecondaryForegroundColor: '#ffffff',
+            strBrowserThemeColor: '#000000',
+          },
+        },
+      },
+    }
+    expect(() => fnParseRuntimeConfig(objUnsafeTheme)).toThrowError(
+      RuntimeConfigError
+    )
+
+    const objUnsafeAsset = structuredClone(objValidRuntimeConfig)
+    objUnsafeAsset.app.strLogoPath =
+      'data:image/svg+xml,<svg onload="alert(1)" />'
+    expect(() => fnParseRuntimeConfig(objUnsafeAsset)).toThrowError(
+      RuntimeConfigError
+    )
+
+    const objLowContrast = structuredClone(objUnsafeTheme)
+    objLowContrast.app.objTheme.objLight.strPrimaryColor = '#ffffff'
+    objLowContrast.app.objTheme.objLight.strPrimaryForegroundColor = '#fefefe'
+    expect(() => fnParseRuntimeConfig(objLowContrast)).toThrowError(
+      /WCAG AA 4\.5:1/
+    )
+  })
+
+  it('rejects unknown fields and unsafe URLs without echoing their values', () => {
+    expect(() =>
+      fnParseRuntimeConfig({
+        ...objValidRuntimeConfig,
+        strClientSecret: 'must-not-appear',
+      })
+    ).toThrowError(RuntimeConfigError)
+
+    try {
+      fnParseRuntimeConfig({
+        ...objValidRuntimeConfig,
+        api: { strBaseUrl: 'https://user:secret@example.com' },
+      })
+    } catch (objError) {
+      expect(objError).toBeInstanceOf(RuntimeConfigError)
+      if (objError instanceof Error) {
+        expect(objError.message).not.toContain('secret')
+      }
+    }
+  })
+
+  it('loads the configuration without browser caching', async () => {
+    const fnFetch = vi.fn<typeof fetch>()
+    fnFetch.mockResolvedValue(
+      new Response(JSON.stringify(objValidRuntimeConfig), { status: 200 })
+    )
+
+    const objConfig = await fnLoadRuntimeConfig(fnFetch)
+
+    expect(objConfig.app.strMode).toBe('demo')
+    expect(fnFetch).toHaveBeenCalledWith('/runtime-config.json', {
+      cache: 'no-store',
+      credentials: 'same-origin',
+      headers: { Accept: 'application/json' },
+    })
+  })
+
+  it('returns stable error codes for HTTP and JSON failures', async () => {
+    const fnHttpFailure = vi.fn<typeof fetch>()
+    fnHttpFailure.mockResolvedValue(new Response(null, { status: 503 }))
+    const fnJsonFailure = vi.fn<typeof fetch>()
+    fnJsonFailure.mockResolvedValue(
+      new Response('{', {
+        headers: { 'Content-Type': 'application/json' },
+        status: 200,
+      })
+    )
+
+    await expect(fnLoadRuntimeConfig(fnHttpFailure)).rejects.toMatchObject({
+      strCode: 'load_failed',
+    })
+    await expect(fnLoadRuntimeConfig(fnJsonFailure)).rejects.toMatchObject({
+      strCode: 'invalid_json',
+    })
+  })
+})

package/template/tests/unit/config/scaffoldCheck.test.mjs

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+
+const strProjectRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../..'
+)
+const strCheckScript = path.resolve(strProjectRoot, 'tools/scaffold/check.mjs')
+
+const fnRunCheck = (...arrArguments) =>
+  spawnSync(process.execPath, [strCheckScript, ...arrArguments], {
+    cwd: strProjectRoot,
+    encoding: 'utf8',
+  })
+
+test('scaffold check validates real project contracts and keeps reminders actionable', () => {
+  const objPackage = JSON.parse(
+    readFileSync(path.resolve(strProjectRoot, 'package.json'), 'utf8')
+  )
+  const objResult = fnRunCheck()
+
+  assert.equal(
+    objPackage.scripts['scaffold:check'],
+    'node tools/scaffold/check.mjs'
+  )
+  assert.equal(objResult.status, 0, objResult.stderr || objResult.stdout)
+  assert.match(objResult.stdout, /BUILD_CONFIG_READY/)
+  assert.match(objResult.stdout, /RUNTIME_CONFIG_READY/)
+  assert.match(objResult.stdout, /OPENAPI_SERVICES_READY/)
+  assert.match(objResult.stdout, /PACKAGE_NAME_PLACEHOLDER/)
+  assert.match(objResult.stdout, /AUTH_CONFIG_PLACEHOLDER/)
+  assert.match(objResult.stdout, /脚手架基础检查通过/)
+})
+
+test('strict scaffold check blocks handoff while placeholders remain', () => {
+  const objResult = fnRunCheck('--strict')
+
+  assert.equal(objResult.status, 1)
+  assert.match(objResult.stdout, /严格模式要求/)
+  assert.match(objResult.stdout, /0 个错误，\d+ 个提醒/)
+})
+
+test('scaffold check rejects unknown options with a stable diagnostic', () => {
+  const objResult = fnRunCheck('--write')
+
+  assert.equal(objResult.status, 1)
+  assert.match(objResult.stdout, /CLI_ARGUMENT_INVALID/)
+  assert.match(objResult.stdout, /只使用 pnpm scaffold:check/)
+})

package/template/tests/unit/config/scaffoldFeature.test.mjs

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { fnCreateFeature } from '../../../tools/scaffold/create-feature.mjs'
+
+const strProjectRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../..'
+)
+const strFeatureScript = path.resolve(
+  strProjectRoot,
+  'tools/scaffold/create-feature.mjs'
+)
+const objFeatureOptions = {
+  strFeatureName: 'customerManagement',
+  strModelName: 'CustomerRecord',
+  strResourceKey: 'customer:record',
+}
+
+const fnCreateProjectFixture = async (objTestContext) => {
+  const strFixtureRoot = await mkdtemp(
+    path.join(os.tmpdir(), 'react-admin-feature-create-')
+  )
+  objTestContext.after(() =>
+    rm(strFixtureRoot, { force: true, recursive: true })
+  )
+  await Promise.all([
+    mkdir(path.resolve(strFixtureRoot, 'src/features'), { recursive: true }),
+    mkdir(path.resolve(strFixtureRoot, 'tests/unit/features'), {
+      recursive: true,
+    }),
+  ])
+  return strFixtureRoot
+}
+
+const fnReadGeneratedFiles = async (strFixtureRoot, arrFiles) =>
+  Promise.all(
+    arrFiles.map((strFilePath) =>
+      readFile(path.resolve(strFixtureRoot, strFilePath), 'utf8')
+    )
+  )
+
+test('Feature generator previews source and tests without creating directories', async (objTestContext) => {
+  const strFixtureRoot = await fnCreateProjectFixture(objTestContext)
+
+  const objResult = await fnCreateFeature({
+    ...objFeatureOptions,
+    strProjectRoot: strFixtureRoot,
+  })
+
+  assert.equal(objResult.bWrite, false)
+  assert.equal(objResult.arrFiles.length, 8)
+  assert.equal(
+    objResult.arrFiles.every(
+      (strFilePath) =>
+        strFilePath.startsWith('src/features/customerManagement/') ||
+        strFilePath.startsWith('tests/unit/features/customerManagement/')
+    ),
+    true
+  )
+  await assert.rejects(
+    readFile(
+      path.resolve(strFixtureRoot, 'src/features/customerManagement/index.ts')
+    ),
+    { code: 'ENOENT' }
+  )
+})
+
+test('Feature generator writes transformed contracts and refuses every overwrite', async (objTestContext) => {
+  const strFixtureRoot = await fnCreateProjectFixture(objTestContext)
+
+  const objResult = await fnCreateFeature({
+    ...objFeatureOptions,
+    bWrite: true,
+    strProjectRoot: strFixtureRoot,
+  })
+  const arrSources = await fnReadGeneratedFiles(
+    strFixtureRoot,
+    objResult.arrFiles
+  )
+  const strCombinedSource = arrSources.join('\n')
+  const strPublicEntry = await readFile(
+    path.resolve(strFixtureRoot, 'src/features/customerManagement/index.ts'),
+    'utf8'
+  )
+
+  assert.equal(objResult.bWrite, true)
+  assert.match(strCombinedSource, /fnCreateCustomerRecordFeature/)
+  assert.match(strCombinedSource, /strFeatureKey = 'customerManagement'/)
+  assert.match(strCombinedSource, /strRecordResourceKey = 'customer:record'/)
+  assert.match(strCombinedSource, /@\/features\/customerManagement/)
+  assert.match(strCombinedSource, /customer:record:read/)
+  assert.match(strCombinedSource, /CUSTOMER_RECORD_CONFLICT/)
+  assert.doesNotMatch(
+    strPublicEntry,
+    /Repository|RecordDto|fnMapCustomerRecord/
+  )
+  assert.doesNotMatch(
+    strCombinedSource,
+    /featureTemplate|TemplateRecord|TEMPLATE_|template:record|template-user/
+  )
+
+  await assert.rejects(
+    fnCreateFeature({
+      ...objFeatureOptions,
+      bWrite: true,
+      strProjectRoot: strFixtureRoot,
+    }),
+    (objError) => {
+      assert.equal(objError.strCode, 'FEATURE_CREATE_CONFLICT')
+      assert.match(objError.message, /不会覆盖已有 Feature/)
+      return true
+    }
+  )
+  assert.deepEqual(
+    await fnReadGeneratedFiles(strFixtureRoot, objResult.arrFiles),
+    arrSources
+  )
+})
+
+test('Feature generator blocks invalid names and cross-platform case collisions', async (objTestContext) => {
+  const strFixtureRoot = await fnCreateProjectFixture(objTestContext)
+
+  await assert.rejects(
+    fnCreateFeature({
+      ...objFeatureOptions,
+      strFeatureName: '../customerManagement',
+      strProjectRoot: strFixtureRoot,
+    }),
+    (objError) => objError.strCode === 'FEATURE_CREATE_ARGUMENT_INVALID'
+  )
+
+  await mkdir(path.resolve(strFixtureRoot, 'src/features/CustomerManagement'))
+  await assert.rejects(
+    fnCreateFeature({
+      ...objFeatureOptions,
+      strProjectRoot: strFixtureRoot,
+    }),
+    (objError) => {
+      assert.equal(objError.strCode, 'FEATURE_CREATE_CONFLICT')
+      assert.match(objError.message, /CustomerManagement/)
+      return true
+    }
+  )
+})
+
+test('Feature generator CLI documents boundaries and stable diagnostics', async () => {
+  const objPackage = JSON.parse(
+    await readFile(path.resolve(strProjectRoot, 'package.json'), 'utf8')
+  )
+  const objHelpResult = spawnSync(
+    process.execPath,
+    [strFeatureScript, '--help'],
+    {
+      cwd: strProjectRoot,
+      encoding: 'utf8',
+    }
+  )
+  const objInvalidResult = spawnSync(
+    process.execPath,
+    [strFeatureScript, '--name', 'customer-management'],
+    { cwd: strProjectRoot, encoding: 'utf8' }
+  )
+
+  assert.equal(
+    objPackage.scripts['scaffold:feature'],
+    'node tools/scaffold/create-feature.mjs'
+  )
+  assert.equal(objHelpResult.status, 0)
+  assert.match(objHelpResult.stdout, /不会注册路由、菜单或生成 API 客户端/)
+  assert.equal(objInvalidResult.status, 1)
+  assert.match(objInvalidResult.stderr, /FEATURE_CREATE_ARGUMENT_INVALID/)
+})