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

package/template/tools/component-governance/check.mjs

@@ -0,0 +1,703 @@
+import { execFileSync, spawnSync } from 'node:child_process'
+import { access, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const strToolDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strProjectRoot = path.resolve(strToolDirectory, '../..')
+const strDefaultManifest = path.resolve(strToolDirectory, 'manifest.json')
+const strSourceManifestReference = 'tools/component-governance/manifest.json'
+const objRevisionPattern = /^[a-f0-9]{40}$/
+const objEmbeddedRevisionPattern = /\b[a-f0-9]{40}\b/i
+
+class ComponentGovernanceError extends Error {
+  constructor(strCode, strMessage, strFix) {
+    super(strMessage)
+    this.name = 'ComponentGovernanceError'
+    this.strCode = strCode
+    this.strFix = strFix
+  }
+}
+
+const fnFail = (strCode, strMessage, strFix) => {
+  throw new ComponentGovernanceError(strCode, strMessage, strFix)
+}
+
+const fnRequireString = (value, strPath) => {
+  if (typeof value !== 'string' || !value.trim()) {
+    fnFail(
+      'COMPONENT_MANIFEST_INVALID',
+      `${strPath} 必须是非空字符串。`,
+      `修复 ${strSourceManifestReference} 后重试。`
+    )
+  }
+  return value
+}
+
+const fnRequireStringArray = (value, strPath) => {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.some((strValue) => typeof strValue !== 'string' || !strValue.trim())
+  ) {
+    fnFail(
+      'COMPONENT_MANIFEST_INVALID',
+      `${strPath} 必须是非空字符串数组。`,
+      `修复 ${strSourceManifestReference} 后重试。`
+    )
+  }
+  return value
+}
+
+const fnResolveProjectPath = (strRelativePath) => {
+  const strPath = fnRequireString(strRelativePath, '项目相对路径')
+  if (path.isAbsolute(strPath)) {
+    fnFail(
+      'COMPONENT_MANIFEST_PATH_INVALID',
+      `清单路径不能是绝对路径：${strPath}。`,
+      '只记录仓库根目录下的相对路径。'
+    )
+  }
+  const strResolvedPath = path.resolve(strProjectRoot, strPath)
+  if (
+    strResolvedPath !== strProjectRoot &&
+    !strResolvedPath.startsWith(`${strProjectRoot}${path.sep}`)
+  ) {
+    fnFail(
+      'COMPONENT_MANIFEST_PATH_INVALID',
+      `清单路径越过了仓库边界：${strPath}。`,
+      '删除 .. 路径段并只引用当前仓库文件。'
+    )
+  }
+  return strResolvedPath
+}
+
+const fnReadJson = async (strFilePath, strCode) => {
+  try {
+    return JSON.parse(await readFile(strFilePath, 'utf8'))
+  } catch (objError) {
+    fnFail(
+      strCode,
+      `${path.relative(strProjectRoot, strFilePath)} 不存在或不是有效 JSON。`,
+      objError instanceof Error ? objError.message : '修复 JSON 后重试。'
+    )
+  }
+}
+
+const fnAssertFile = async (strRelativePath, strCode, strFix) => {
+  const strFilePath = fnResolveProjectPath(strRelativePath)
+  try {
+    await access(strFilePath)
+  } catch {
+    fnFail(strCode, `缺少 ${strRelativePath}。`, strFix)
+  }
+  return strFilePath
+}
+
+const fnValidateManifest = (objManifest) => {
+  if (!objManifest || typeof objManifest !== 'object') {
+    fnFail(
+      'COMPONENT_MANIFEST_INVALID',
+      '组件源码清单必须是 JSON 对象。',
+      `修复 ${strSourceManifestReference} 后重试。`
+    )
+  }
+  if (objManifest.schemaVersion !== 1) {
+    fnFail(
+      'COMPONENT_MANIFEST_VERSION_UNSUPPORTED',
+      `不支持 schemaVersion ${String(objManifest.schemaVersion)}。`,
+      '使用当前脚本支持的 schemaVersion 1。'
+    )
+  }
+  if (
+    !Array.isArray(objManifest.components) ||
+    objManifest.components.length === 0
+  ) {
+    fnFail(
+      'COMPONENT_MANIFEST_INVALID',
+      'components 必须是非空数组。',
+      `修复 ${strSourceManifestReference} 后重试。`
+    )
+  }
+  if (!Array.isArray(objManifest.thirdParty)) {
+    fnFail(
+      'COMPONENT_MANIFEST_INVALID',
+      'thirdParty 必须是数组。',
+      `修复 ${strSourceManifestReference} 后重试。`
+    )
+  }
+
+  const objNames = new Set()
+  const objLocalPaths = new Set()
+  for (const [nIndex, objComponent] of objManifest.components.entries()) {
+    const strPrefix = `components[${nIndex}]`
+    const strName = fnRequireString(objComponent?.name, `${strPrefix}.name`)
+    if (objNames.has(strName)) {
+      fnFail(
+        'COMPONENT_MANIFEST_DUPLICATE',
+        `组件 ${strName} 在清单中重复。`,
+        '每个内建组件只保留一条来源记录。'
+      )
+    }
+    objNames.add(strName)
+    const strLocalPath = fnRequireString(
+      objComponent.localPath,
+      `${strPrefix}.localPath`
+    )
+    if (objLocalPaths.has(strLocalPath)) {
+      fnFail(
+        'COMPONENT_MANIFEST_DUPLICATE',
+        `本地源码路径 ${strLocalPath} 在清单中重复。`,
+        '每个源码目录只能归属于一个内建组件。'
+      )
+    }
+    objLocalPaths.add(strLocalPath)
+    const strPublicEntry = fnRequireString(
+      objComponent.publicEntry,
+      `${strPrefix}.publicEntry`
+    )
+    const strSourceNote = fnRequireString(
+      objComponent.sourceNote,
+      `${strPrefix}.sourceNote`
+    )
+    if (
+      strPublicEntry !== `${strLocalPath}/index.ts` ||
+      strSourceNote !== `${strLocalPath}/SOURCE.md`
+    ) {
+      fnFail(
+        'COMPONENT_MANIFEST_PATH_INVALID',
+        `${strName} 的公共入口或 SOURCE.md 不在组件根目录。`,
+        '使用 <localPath>/index.ts 与 <localPath>/SOURCE.md，避免额外模块层。'
+      )
+    }
+    fnRequireString(
+      objComponent.source?.repository,
+      `${strPrefix}.source.repository`
+    )
+    const strRevision = fnRequireString(
+      objComponent.source?.revision,
+      `${strPrefix}.source.revision`
+    )
+    if (!objRevisionPattern.test(strRevision)) {
+      fnFail(
+        'COMPONENT_SOURCE_REVISION_INVALID',
+        `${strName} 的 revision 必须是完整的 40 位 Git Commit。`,
+        '从干净来源仓库执行 git rev-parse HEAD 后更新清单。'
+      )
+    }
+    fnRequireString(
+      objComponent.source.packageVersion,
+      `${strPrefix}.source.packageVersion`
+    )
+    fnRequireString(
+      objComponent.source.importedAt,
+      `${strPrefix}.source.importedAt`
+    )
+    fnRequireStringArray(
+      objComponent.source.includedPaths,
+      `${strPrefix}.source.includedPaths`
+    )
+    fnRequireStringArray(
+      objComponent.source.excludedCapabilities,
+      `${strPrefix}.source.excludedCapabilities`
+    )
+    const strLicenseStatus = fnRequireString(
+      objComponent.source.license?.status,
+      `${strPrefix}.source.license.status`
+    )
+    const strDistributionPolicy = fnRequireString(
+      objComponent.source.license?.distributionPolicy,
+      `${strPrefix}.source.license.distributionPolicy`
+    )
+    if (!['documented', 'not-provided'].includes(strLicenseStatus)) {
+      fnFail(
+        'COMPONENT_SOURCE_LICENSE_STATUS_INVALID',
+        `${strName} 使用了未知许可证状态 ${strLicenseStatus}。`,
+        '只使用 not-provided 或完成权属材料后的 documented。'
+      )
+    }
+    if (!['authorized', 'internal-only'].includes(strDistributionPolicy)) {
+      fnFail(
+        'COMPONENT_SOURCE_DISTRIBUTION_INVALID',
+        `${strName} 使用了未知分发策略 ${strDistributionPolicy}。`,
+        '只使用 internal-only 或取得书面授权后的 authorized。'
+      )
+    }
+    if (
+      strLicenseStatus === 'not-provided' &&
+      strDistributionPolicy !== 'internal-only'
+    ) {
+      fnFail(
+        'COMPONENT_SOURCE_DISTRIBUTION_UNSAFE',
+        `${strName} 未提供许可证，却声明为 ${strDistributionPolicy}。`,
+        '在取得书面权属与再分发授权前保持 internal-only。'
+      )
+    }
+    fnRequireStringArray(
+      objComponent.localAdaptations,
+      `${strPrefix}.localAdaptations`
+    )
+    fnRequireStringArray(
+      objComponent.regressionTests,
+      `${strPrefix}.regressionTests`
+    )
+    const arrRequiredCommands = fnRequireStringArray(
+      objComponent.requiredCommands,
+      `${strPrefix}.requiredCommands`
+    )
+    if (
+      !arrRequiredCommands.includes('pnpm components:check') ||
+      !arrRequiredCommands.includes('pnpm verify')
+    ) {
+      fnFail(
+        'COMPONENT_REGRESSION_COMMAND_MISSING',
+        `${strName} 缺少标准治理或全量验证命令。`,
+        'requiredCommands 必须同时包含 pnpm components:check 与 pnpm verify。'
+      )
+    }
+  }
+
+  for (const [nIndex, objDependency] of objManifest.thirdParty.entries()) {
+    const strPrefix = `thirdParty[${nIndex}]`
+    fnRequireString(objDependency?.packageName, `${strPrefix}.packageName`)
+    fnRequireString(
+      objDependency.expectedVersion,
+      `${strPrefix}.expectedVersion`
+    )
+    fnRequireString(
+      objDependency.expectedLicense,
+      `${strPrefix}.expectedLicense`
+    )
+    fnRequireString(objDependency.licenseFile, `${strPrefix}.licenseFile`)
+    fnRequireStringArray(objDependency.usedBy, `${strPrefix}.usedBy`)
+    fnRequireString(
+      objDependency.productionPolicy,
+      `${strPrefix}.productionPolicy`
+    )
+    if (!Array.isArray(objDependency.policyEvidence)) {
+      fnFail(
+        'COMPONENT_MANIFEST_INVALID',
+        `${strPrefix}.policyEvidence 必须是数组。`,
+        `修复 ${strSourceManifestReference} 后重试。`
+      )
+    }
+    for (const [
+      nEvidenceIndex,
+      objEvidence,
+    ] of objDependency.policyEvidence.entries()) {
+      fnRequireString(
+        objEvidence?.path,
+        `${strPrefix}.policyEvidence[${nEvidenceIndex}].path`
+      )
+      fnRequireStringArray(
+        objEvidence.markers,
+        `${strPrefix}.policyEvidence[${nEvidenceIndex}].markers`
+      )
+    }
+    for (const strConsumer of objDependency.usedBy) {
+      if (!objNames.has(strConsumer)) {
+        fnFail(
+          'COMPONENT_MANIFEST_INVALID',
+          `${objDependency.packageName} 引用了未知组件 ${strConsumer}。`,
+          '把 usedBy 限制为 components 中已登记的名称。'
+        )
+      }
+    }
+  }
+  return objManifest
+}
+
+const fnCheckComponent = async (objComponent) => {
+  const [strPublicEntryPath, strSourceNotePath] = await Promise.all([
+    fnAssertFile(
+      objComponent.publicEntry,
+      'COMPONENT_PUBLIC_ENTRY_MISSING',
+      `恢复 ${objComponent.name} 公共入口。`
+    ),
+    fnAssertFile(
+      objComponent.sourceNote,
+      'COMPONENT_SOURCE_NOTE_MISSING',
+      `恢复 ${objComponent.name} 的 SOURCE.md。`
+    ),
+    fnAssertFile(
+      objComponent.localPath,
+      'COMPONENT_SOURCE_DIRECTORY_MISSING',
+      `恢复 ${objComponent.name} 本地源码目录。`
+    ),
+    ...objComponent.regressionTests.map((strTestPath) =>
+      fnAssertFile(
+        strTestPath,
+        'COMPONENT_REGRESSION_EVIDENCE_MISSING',
+        `恢复 ${objComponent.name} 回归测试或更新清单。`
+      )
+    ),
+  ])
+  const [strPublicEntry, strSourceNote] = await Promise.all([
+    readFile(strPublicEntryPath, 'utf8'),
+    readFile(strSourceNotePath, 'utf8'),
+  ])
+  if (!strPublicEntry.includes(objComponent.name)) {
+    fnFail(
+      'COMPONENT_PUBLIC_ENTRY_INVALID',
+      `${objComponent.publicEntry} 没有导出 ${objComponent.name}。`,
+      '恢复稳定公共组件边界，业务不得依赖内部目录。'
+    )
+  }
+  if (
+    !strSourceNote.includes(strSourceManifestReference) ||
+    !strSourceNote.includes('pnpm components:check')
+  ) {
+    fnFail(
+      'COMPONENT_SOURCE_NOTE_INVALID',
+      `${objComponent.sourceNote} 没有指向唯一清单或治理命令。`,
+      `引用 ${strSourceManifestReference} 并说明 pnpm components:check。`
+    )
+  }
+  if (objEmbeddedRevisionPattern.test(strSourceNote)) {
+    fnFail(
+      'COMPONENT_SOURCE_REVISION_DUPLICATED',
+      `${objComponent.sourceNote} 重复保存了 Git revision。`,
+      `只在 ${strSourceManifestReference} 保存 revision，SOURCE.md 只描述本地改造。`
+    )
+  }
+}
+
+const fnCheckThirdParty = async (objDependency, objPackage) => {
+  if (!objPackage.dependencies?.[objDependency.packageName]) {
+    fnFail(
+      'COMPONENT_DEPENDENCY_NOT_DIRECT',
+      `${objDependency.packageName} 未声明为直接运行时依赖。`,
+      '恢复 dependencies 声明，许可证治理不能依赖传递依赖。'
+    )
+  }
+  const strDependencyRoot = path.resolve(
+    strProjectRoot,
+    'node_modules',
+    objDependency.packageName
+  )
+  const objInstalledPackage = await fnReadJson(
+    path.resolve(strDependencyRoot, 'package.json'),
+    'COMPONENT_DEPENDENCY_NOT_INSTALLED'
+  )
+  if (objInstalledPackage.version !== objDependency.expectedVersion) {
+    fnFail(
+      'COMPONENT_DEPENDENCY_VERSION_DRIFT',
+      `${objDependency.packageName} 实际版本 ${String(objInstalledPackage.version)} 与清单 ${objDependency.expectedVersion} 不一致。`,
+      '确认升级影响和许可证后更新锁文件与组件源码清单。'
+    )
+  }
+  if (objInstalledPackage.license !== objDependency.expectedLicense) {
+    fnFail(
+      'COMPONENT_DEPENDENCY_LICENSE_DRIFT',
+      `${objDependency.packageName} 的 package.json#license 已变化。`,
+      '暂停发布，复核新许可证文本和分发义务后更新清单。'
+    )
+  }
+  try {
+    await access(path.resolve(strDependencyRoot, objDependency.licenseFile))
+  } catch {
+    fnFail(
+      'COMPONENT_DEPENDENCY_LICENSE_FILE_MISSING',
+      `${objDependency.packageName} 缺少 ${objDependency.licenseFile}。`,
+      '重新安装依赖；仍缺失时暂停发布并联系依赖维护方。'
+    )
+  }
+  for (const objEvidence of objDependency.policyEvidence) {
+    const strEvidencePath = await fnAssertFile(
+      objEvidence.path,
+      'COMPONENT_LICENSE_POLICY_EVIDENCE_MISSING',
+      `恢复 ${objDependency.packageName} 的许可证策略证据。`
+    )
+    const strEvidence = await readFile(strEvidencePath, 'utf8')
+    for (const strMarker of objEvidence.markers) {
+      if (!strEvidence.includes(strMarker)) {
+        fnFail(
+          'COMPONENT_LICENSE_POLICY_EVIDENCE_INVALID',
+          `${objEvidence.path} 缺少 ${objDependency.packageName} 策略标记 ${strMarker}。`,
+          '恢复构建门禁或测试后再发布。'
+        )
+      }
+    }
+  }
+}
+
+const fnCheckManifest = async (objManifest) => {
+  const objPackage = await fnReadJson(
+    path.resolve(strProjectRoot, 'package.json'),
+    'COMPONENT_PROJECT_PACKAGE_INVALID'
+  )
+  if (
+    objPackage.scripts?.['components:check'] !==
+      'node tools/component-governance/check.mjs check' ||
+    objPackage.scripts?.['components:diff'] !==
+      'node tools/component-governance/check.mjs diff' ||
+    !objPackage.scripts?.verify?.includes('pnpm components:check')
+  ) {
+    fnFail(
+      'COMPONENT_GOVERNANCE_GATE_MISSING',
+      'package.json 没有把组件源码检查接入 verify。',
+      '恢复 components:check，并让 verify 在测试和构建前执行它。'
+    )
+  }
+  const [strPackageSource, strLockSource] = await Promise.all([
+    readFile(path.resolve(strProjectRoot, 'package.json'), 'utf8'),
+    readFile(path.resolve(strProjectRoot, 'pnpm-lock.yaml'), 'utf8'),
+  ])
+  if (
+    /@hgw\/|frontend\/package\//.test(`${strPackageSource}\n${strLockSource}`)
+  ) {
+    fnFail(
+      'COMPONENT_PRIVATE_PACKAGE_REFERENCE_FOUND',
+      'package.json 或锁文件重新出现了内部组件包引用。',
+      '移除私有包依赖，继续使用仓库内 AppPageForm/AppTable 源码。'
+    )
+  }
+  await Promise.all([
+    ...objManifest.components.map(fnCheckComponent),
+    ...objManifest.thirdParty.map((objDependency) =>
+      fnCheckThirdParty(objDependency, objPackage)
+    ),
+  ])
+}
+
+const fnRunGit = (strSourceRoot, arrArguments) => {
+  try {
+    return execFileSync('git', ['-C', strSourceRoot, ...arrArguments], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim()
+  } catch (objError) {
+    const strReason = objError?.stderr?.toString().trim()
+    fnFail(
+      'COMPONENT_SOURCE_GIT_FAILED',
+      `无法读取来源 Git 仓库${strReason ? `：${strReason}` : '。'}`,
+      '确认 --source-root 指向可读取的 Git 仓库。'
+    )
+  }
+}
+
+const fnCheckGitSuccess = (strSourceRoot, arrArguments) =>
+  spawnSync('git', ['-C', strSourceRoot, ...arrArguments], {
+    encoding: 'utf8',
+    stdio: 'ignore',
+  }).status === 0
+
+const fnListLicenseFiles = (strSourceRoot, strRevision) =>
+  fnRunGit(strSourceRoot, ['ls-tree', '-r', '--name-only', strRevision])
+    .split('\n')
+    .filter((strFilePath) => /(^|\/)(LICENSE|NOTICE)(\.|$)/i.test(strFilePath))
+    .sort()
+
+const fnDiffComponentSource = (objComponent, strSourceRoot) => {
+  if (!fnCheckGitSuccess(strSourceRoot, ['rev-parse', '--git-dir'])) {
+    fnFail(
+      'COMPONENT_SOURCE_NOT_GIT_REPOSITORY',
+      `${strSourceRoot} 不是 Git 仓库。`,
+      '把 --source-root 指向对应内部来源仓库。'
+    )
+  }
+  const strStatus = fnRunGit(strSourceRoot, ['status', '--porcelain=v1'])
+  if (strStatus) {
+    fnFail(
+      'COMPONENT_SOURCE_DIRTY',
+      `${objComponent.name} 来源仓库存在未提交修改。`,
+      '提交、暂存到其他分支或恢复来源工作区后再生成升级差异。'
+    )
+  }
+  const strRemote = fnRunGit(strSourceRoot, ['remote', 'get-url', 'origin'])
+    .replace(/\.git$/, '')
+    .replace(/\\/g, '/')
+  if (!strRemote.endsWith(objComponent.source.repository)) {
+    fnFail(
+      'COMPONENT_SOURCE_REPOSITORY_MISMATCH',
+      `来源 origin 与 ${objComponent.source.repository} 不匹配。`,
+      '确认没有把同名组件的其他仓库作为升级来源。'
+    )
+  }
+  const strBaseRevision = objComponent.source.revision
+  if (
+    !fnCheckGitSuccess(strSourceRoot, [
+      'cat-file',
+      '-e',
+      `${strBaseRevision}^{commit}`,
+    ])
+  ) {
+    fnFail(
+      'COMPONENT_SOURCE_REVISION_NOT_FOUND',
+      `${objComponent.name} 已记录 revision 不在来源仓库中。`,
+      '执行 git fetch --all --prune，仍不存在时核对清单与来源仓库。'
+    )
+  }
+  const strTargetRevision = fnRunGit(strSourceRoot, ['rev-parse', 'HEAD'])
+  if (
+    strTargetRevision !== strBaseRevision &&
+    !fnCheckGitSuccess(strSourceRoot, [
+      'merge-base',
+      '--is-ancestor',
+      strBaseRevision,
+      strTargetRevision,
+    ])
+  ) {
+    fnFail(
+      'COMPONENT_SOURCE_HISTORY_DIVERGED',
+      `${objComponent.name} 候选 HEAD 不是已记录 revision 的后继。`,
+      '切换到正式升级分支；不要用无共同升级历史的提交覆盖本地源码。'
+    )
+  }
+
+  const arrDiffArguments = [
+    'diff',
+    '--name-status',
+    `${strBaseRevision}..${strTargetRevision}`,
+    '--',
+    ...objComponent.source.includedPaths,
+  ]
+  const strDiff = fnRunGit(strSourceRoot, arrDiffArguments)
+  const arrChangedFiles = strDiff ? strDiff.split('\n') : []
+  const arrBaseLicenses = fnListLicenseFiles(strSourceRoot, strBaseRevision)
+  const arrTargetLicenses = fnListLicenseFiles(strSourceRoot, strTargetRevision)
+  const bLicenseChanged =
+    JSON.stringify(arrBaseLicenses) !== JSON.stringify(arrTargetLicenses)
+
+  process.stdout.write(
+    `[PASS] COMPONENT_SOURCE_IDENTIFIED ${objComponent.name} 来源、工作区和 Git 历史有效。\n`
+  )
+  process.stdout.write(`       已记录：${strBaseRevision}\n`)
+  process.stdout.write(`       候选：  ${strTargetRevision}\n`)
+  if (arrChangedFiles.length === 0) {
+    process.stdout.write(
+      `[PASS] COMPONENT_SOURCE_CURRENT ${objComponent.name} 纳入范围的源码没有候选变化。\n`
+    )
+  } else {
+    process.stdout.write(
+      `[INFO] COMPONENT_UPGRADE_AVAILABLE ${objComponent.name} 有 ${arrChangedFiles.length} 个候选文件变化：\n`
+    )
+    for (const strChangedFile of arrChangedFiles) {
+      process.stdout.write(`       ${strChangedFile}\n`)
+    }
+  }
+  if (bLicenseChanged) {
+    process.stdout.write(
+      '[WARN] COMPONENT_SOURCE_LICENSE_CHANGED 来源 LICENSE/NOTICE 文件集合发生变化，必须在同步前完成权属评审。\n'
+    )
+    process.stdout.write(`       旧：${arrBaseLicenses.join(', ') || '无'}\n`)
+    process.stdout.write(`       新：${arrTargetLicenses.join(', ') || '无'}\n`)
+  }
+  process.stdout.write(
+    '[INFO] COMPONENT_UPGRADE_VERIFICATION 同步后必须执行：\n'
+  )
+  for (const strCommand of objComponent.requiredCommands) {
+    process.stdout.write(`       ${strCommand}\n`)
+  }
+  for (const strTestPath of objComponent.regressionTests) {
+    process.stdout.write(`       回归证据：${strTestPath}\n`)
+  }
+  process.stdout.write(
+    '       本命令不会修改本地组件或清单；完成选择性同步与评审后再更新 revision。\n'
+  )
+}
+
+const fnParseArguments = (arrArguments) => {
+  const [strCommand, ...arrRawOptions] = arrArguments
+  const arrOptions =
+    arrRawOptions[0] === '--' ? arrRawOptions.slice(1) : arrRawOptions
+  if (strCommand !== 'check' && strCommand !== 'diff') {
+    fnFail(
+      'COMPONENT_GOVERNANCE_ARGUMENT_INVALID',
+      `不支持命令 ${strCommand ?? '(empty)'}。`,
+      '使用 pnpm components:check，或 pnpm components:diff -- --component <name> --source-root <path>。'
+    )
+  }
+  const objOptions = {}
+  for (let nIndex = 0; nIndex < arrOptions.length; nIndex += 2) {
+    const strKey = arrOptions[nIndex]
+    const strValue = arrOptions[nIndex + 1]
+    if (
+      !['--component', '--manifest', '--source-root'].includes(strKey) ||
+      !strValue ||
+      strValue.startsWith('--')
+    ) {
+      fnFail(
+        'COMPONENT_GOVERNANCE_ARGUMENT_INVALID',
+        `参数 ${strKey ?? '(empty)'} 缺少值或不受支持。`,
+        '只使用 --component、--source-root 和测试/迁移所需的 --manifest。'
+      )
+    }
+    if (objOptions[strKey]) {
+      fnFail(
+        'COMPONENT_GOVERNANCE_ARGUMENT_INVALID',
+        `参数 ${strKey} 重复。`,
+        '每个参数只提供一次。'
+      )
+    }
+    objOptions[strKey] = strValue
+  }
+  if (
+    strCommand === 'check' &&
+    (objOptions['--component'] || objOptions['--source-root'])
+  ) {
+    fnFail(
+      'COMPONENT_GOVERNANCE_ARGUMENT_INVALID',
+      'check 不接受 --component 或 --source-root。',
+      '直接执行 pnpm components:check。'
+    )
+  }
+  if (
+    strCommand === 'diff' &&
+    (!objOptions['--component'] || !objOptions['--source-root'])
+  ) {
+    fnFail(
+      'COMPONENT_GOVERNANCE_ARGUMENT_INVALID',
+      'diff 必须同时提供 --component 和 --source-root。',
+      '执行 pnpm components:diff -- --component <name> --source-root <path>。'
+    )
+  }
+  return { objOptions, strCommand }
+}
+
+const fnMain = async () => {
+  try {
+    const { objOptions, strCommand } = fnParseArguments(process.argv.slice(2))
+    const strManifestPath = path.resolve(
+      process.cwd(),
+      objOptions['--manifest'] ?? strDefaultManifest
+    )
+    const objManifest = fnValidateManifest(
+      await fnReadJson(strManifestPath, 'COMPONENT_MANIFEST_JSON_INVALID')
+    )
+    if (strCommand === 'check') {
+      await fnCheckManifest(objManifest)
+      process.stdout.write(
+        `[PASS] COMPONENT_GOVERNANCE_READY ${objManifest.components.length} 个内建组件与 ${objManifest.thirdParty.length} 个第三方许可证边界通过检查。\n`
+      )
+      return
+    }
+    const objComponent = objManifest.components.find(
+      (objItem) => objItem.name === objOptions['--component']
+    )
+    if (!objComponent) {
+      fnFail(
+        'COMPONENT_GOVERNANCE_COMPONENT_UNKNOWN',
+        `清单中不存在 ${objOptions['--component']}。`,
+        `可选组件：${objManifest.components.map((objItem) => objItem.name).join(', ')}。`
+      )
+    }
+    fnDiffComponentSource(
+      objComponent,
+      path.resolve(process.cwd(), objOptions['--source-root'])
+    )
+  } catch (objError) {
+    if (objError instanceof ComponentGovernanceError) {
+      process.stderr.write(`[ERROR] ${objError.strCode} ${objError.message}\n`)
+      if (objError.strFix)
+        process.stderr.write(`        修复：${objError.strFix}\n`)
+    } else {
+      process.stderr.write(
+        `[ERROR] COMPONENT_GOVERNANCE_INTERNAL ${objError instanceof Error ? objError.message : '未知错误'}\n`
+      )
+    }
+    process.exitCode = 1
+  }
+}
+
+await fnMain()