diff --git a/src/commands/_gate_webapi.ts b/src/commands/_gate_webapi.ts new file mode 100644 index 0000000..1d7fa7a --- /dev/null +++ b/src/commands/_gate_webapi.ts @@ -0,0 +1,320 @@ +/** + * _gate_webapi.ts — CI 关卡 G: webapi 镜像架构回归防御 (v3.0+ 新增, regression audit) + * + * 目的: 防止新代码继续走"经验复刻"老路, 自动检查 dacli 代码的 webapi 镜像质量 + * + * 检查项 (3 大维度): + * 1. **webapi 引用率**: 每个命令目录的 webapi 引用次数 / 文件数 + * - app/dict/menu/form/workflow 等应有 webapi 引用 + * - apis/doc 等元工具 0 webapi 是正确的 (但要标记) + * + * 2. **_validate.ts 镜像精度**: + * - "镜像 web" 注释数 / 文件数 (应 ≥ 4) + * - 精确行号引用率 (L + 数字 应出现在注释里) + * - BS-56 ENCODE_REGEXP 常量复用 (防止硬编码正则) + * + * 3. **回归盲点扫描**: + * - 找出 webapi 引用 = 0 的命令目录 (标记 KEEP/REFACTOR/DEPRECATE) + * - 找出没有"镜像 web"注释的 _validate.ts + * - 找出缺 ENCODE_REGEXP 但用了 enCode 校验的文件 + * + * 退出码: + * 0: PASS (无违规) + * 1: FAIL (有违规, 阻塞 commit) + * 2: WARN (有提示但不阻塞) + * + * 用法: + * - CI: `npx tsx src/cli.ts _gate_webapi` (或通过 dacli 命令) + * - 调试: 加 --verbose 看详情 + * + * 注意: 这是 v3.0+ regression audit §4.4 建议的"CI 关卡 G 自动防御机制". + */ + +import { readdirSync, readFileSync, statSync } from 'fs' +import { join, basename } from 'path' + +const DACLI_COMMANDS_DIR = '/home/ubuntu/ccWorkDir/dacli/src/commands' +const WEBAPI_DIR = '/home/ubuntu/ccWorkDir/dacli/src/webapi' + +/** 元工具 (正确地无 webapi 引用) */ +const META_TOOLS = ['apis', 'doc'] as const + +/** 已知"经验复刻"高风险目录 (web 端无对应 Form.vue, 应该标注) */ +const EXPERIENCE_REPLICA_CANDIDATES = ['storage', 'integration'] as const + +interface CommandCheck { + cmd: string + fileCount: number + webapiRefs: number + /** 0 = 元工具 / 1 = 高风险 / 2 = 正常 */ + category: 'meta' | 'high-risk' | 'normal' + status: 'PASS' | 'WARN' | 'FAIL' +} + +interface ValidateCheck { + cmd: string + hasValidate: boolean + mirrorComments: number + hasLineRef: boolean + hasEncodeRegexp: boolean + hasEnCodeField: boolean + status: 'PASS' | 'WARN' | 'FAIL' | 'N/A' +} + +interface GateReport { + commands: CommandCheck[] + validates: ValidateCheck[] + overall: 'PASS' | 'WARN' | 'FAIL' + summary: { + totalCommands: number + passCommands: number + warnCommands: number + failCommands: number + totalValidates: number + mirrorCommentRate: string + encodeRegexpRate: string + } + recommendations: string[] +} + +/** 读目录下所有 .ts 文件 (递归) */ +function listTsFiles(dir: string): string[] { + const files: string[] = [] + try { + for (const f of readdirSync(dir)) { + const p = join(dir, f) + const st = statSync(p) + if (st.isDirectory()) { + files.push(...listTsFiles(p)) + } else if (f.endsWith('.ts') && !f.startsWith('_')) { + files.push(p) + } + } + } catch { + // 目录不存在 + } + return files +} + +/** 读文件全文 */ +function readText(p: string): string { + try { + return readFileSync(p, 'utf-8') + } catch { + return '' + } +} + +/** 检查单个命令目录 */ +function checkCommandDir(cmd: string): CommandCheck { + const dir = join(DACLI_COMMANDS_DIR, cmd) + const files = listTsFiles(dir).filter((p) => !basename(p).startsWith('_')) + const allText = files.map(readText).join('\n') + + const webapiRefs = (allText.match(/from\s+['"][^'"]*webapi\//g) || []).length + const fileCount = files.length + + let category: CommandCheck['category'] = 'normal' + if ((META_TOOLS as readonly string[]).includes(cmd)) category = 'meta' + else if ((EXPERIENCE_REPLICA_CANDIDATES as readonly string[]).includes(cmd)) category = 'high-risk' + + let status: CommandCheck['status'] = 'PASS' + if (category === 'meta' && webapiRefs > 0) { + // 元工具但有 webapi 引用 (可疑, 可能过度镜像) + status = 'WARN' + } else if (category === 'high-risk' && webapiRefs === 0) { + // 高风险但无 webapi 引用 (经验复刻, 应有警告注释) + status = 'WARN' + } else if (category === 'normal' && webapiRefs === 0 && fileCount > 2) { + // 正常命令无 webapi 引用 (主命令无 webapi 是 P0) + status = 'FAIL' + } + + return { cmd, fileCount, webapiRefs, category, status } +} + +/** 检查单个 _validate.ts */ +function checkValidate(cmd: string): ValidateCheck { + const validateFile = join(DACLI_COMMANDS_DIR, cmd, '_validate.ts') + const text = readText(validateFile) + const hasValidate = text.length > 0 + + if (!hasValidate) { + return { + cmd, + hasValidate: false, + mirrorComments: 0, + hasLineRef: false, + hasEncodeRegexp: false, + hasEnCodeField: false, + status: 'N/A', + } + } + + // 1. "镜像 web" 注释数 + const mirrorComments = (text.match(/镜像\s*web/g) || []).length + // 2. 精确行号引用 (L + 数字 模式) + const hasLineRef = /\bL\s*\d+/i.test(text) + // 3. BS-56 ENCODE_REGEXP 常量复用 + const hasEncodeRegexp = /const\s+ENCODE_REGEXP\b/.test(text) + // 4. 该文件处理 enCode 字段? + const hasEnCodeField = /\benCode\b/.test(text) + + let status: ValidateCheck['status'] = 'PASS' + if (mirrorComments === 0 && cmd !== 'storage' && cmd !== 'integration') { + // 没有"镜像 web"注释 (除已知无 Form.vue 的命令) + status = 'WARN' + } + if (hasEnCodeField && !hasEncodeRegexp) { + // 处理 enCode 但没复用 ENCODE_REGEXP (硬编码正则) + status = 'FAIL' + } + if (mirrorComments >= 4 && hasLineRef && hasEncodeRegexp) { + status = 'PASS' + } + + return { + cmd, + hasValidate, + mirrorComments, + hasLineRef, + hasEncodeRegexp, + hasEnCodeField, + status, + } +} + +/** 主检查函数 */ +export function runWebapiGate(): GateReport { + // 1. 检查命令目录 + const commandDirs = readdirSync(DACLI_COMMANDS_DIR) + .filter((f) => { + const p = join(DACLI_COMMANDS_DIR, f) + return statSync(p).isDirectory() && !f.startsWith('_') + }) + .sort() + + const commands = commandDirs.map(checkCommandDir) + + // 2. 检查 _validate.ts + const validates = commandDirs + .map(checkValidate) + .filter((v) => v.hasValidate) + + // 3. 汇总 + const passCommands = commands.filter((c) => c.status === 'PASS').length + const warnCommands = commands.filter((c) => c.status === 'WARN').length + const failCommands = commands.filter((c) => c.status === 'FAIL').length + + const totalValidates = validates.length + const mirrorWithComments = validates.filter((v) => v.mirrorComments > 0).length + const encodeWithRegexp = validates.filter((v) => v.hasEncodeRegexp).length + + const overall: GateReport['overall'] = + failCommands > 0 || validates.some((v) => v.status === 'FAIL') + ? 'FAIL' + : warnCommands > 0 || validates.some((v) => v.status === 'WARN') + ? 'WARN' + : 'PASS' + + // 4. 改进建议 + const recommendations: string[] = [] + const failCmds = commands.filter((c) => c.status === 'FAIL') + if (failCmds.length > 0) { + recommendations.push( + `**P0**: ${failCmds.map((c) => c.cmd).join(', ')} 无 webapi 引用 — 应走 webapi 镜像 (参考 app/list.ts 的重构模式)`, + ) + } + const noMirrorValidate = validates.filter((v) => v.mirrorComments === 0 && v.status === 'WARN') + if (noMirrorValidate.length > 0) { + recommendations.push( + `**P1**: ${noMirrorValidate.map((v) => v.cmd).join(', ')} _validate.ts 缺"镜像 web"注释 — 至少标注 web 端 Form.vue 镜像源`, + ) + } + const noRegexpValidate = validates.filter((v) => v.hasEnCodeField && !v.hasEncodeRegexp && v.status === 'FAIL') + if (noRegexpValidate.length > 0) { + recommendations.push( + `**BS-56**: ${noRegexpValidate.map((v) => v.cmd).join(', ')} 用了 enCode 但未复用 ENCODE_REGEXP — 改用统一常量 (防止正则硬编码)`, + ) + } + if (recommendations.length === 0) { + recommendations.push('✅ 所有维度 PASS, webapi 镜像架构健康') + } + + return { + commands, + validates, + overall, + summary: { + totalCommands: commandDirs.length, + passCommands, + warnCommands, + failCommands, + totalValidates, + mirrorCommentRate: totalValidates > 0 ? `${mirrorWithComments}/${totalValidates}` : 'N/A', + encodeRegexpRate: totalValidates > 0 ? `${encodeWithRegexp}/${totalValidates}` : 'N/A', + }, + recommendations, + } +} + +/** CLI 入口 (被 cli.ts 顶层 _gate_webapi 注册) */ +export function printGateReport(verbose = false): number { + const report = runWebapiGate() + + // 表头 + console.log(`\n=== CI 关卡 G: webapi 镜像架构回归防御 (v3.0+) ===\n`) + + // 命令目录 + console.log('【维度 1】命令 webapi 引用率:') + console.log(' cmd files webapi_refs category status') + console.log(' ' + '-'.repeat(70)) + for (const c of report.commands) { + const catStr = c.category.padEnd(12) + const statusStr = statusEmoji(c.status).padEnd(2) + c.status + console.log( + ` ${c.cmd.padEnd(20)}${String(c.fileCount).padEnd(7)}${String(c.webapiRefs).padEnd(13)}${catStr}${statusStr}`, + ) + } + + // _validate.ts + console.log('\n【维度 2】_validate.ts 镜像精度:') + console.log(' cmd mirror_comments line_ref encode_regexp status') + console.log(' ' + '-'.repeat(70)) + for (const v of report.validates) { + if (v.status === 'N/A') continue + const statusStr = statusEmoji(v.status).padEnd(2) + v.status + console.log( + ` ${v.cmd.padEnd(20)}${String(v.mirrorComments).padEnd(17)}${(v.hasLineRef ? 'yes' : 'no').padEnd(10)}${(v.hasEncodeRegexp ? 'yes' : 'no').padEnd(15)}${statusStr}`, + ) + } + + // 汇总 + console.log('\n【汇总】') + console.log(` 命令: PASS ${report.summary.passCommands} / WARN ${report.summary.warnCommands} / FAIL ${report.summary.failCommands} / 总 ${report.summary.totalCommands}`) + console.log(` _validate.ts: 总 ${report.summary.totalValidates}, "镜像 web" 注释率 ${report.summary.mirrorCommentRate}, ENCODE_REGEXP 复用率 ${report.summary.encodeRegexpRate}`) + console.log(` 总体: ${statusEmoji(report.overall)} ${report.overall}`) + + // 建议 + console.log('\n【改进建议】') + for (const r of report.recommendations) { + console.log(` ${r}`) + } + + console.log('') + + // 退出码 + if (report.overall === 'FAIL') return 1 + if (report.overall === 'WARN') return 2 + return 0 +} + +function statusEmoji(status: string): string { + if (status === 'PASS') return '✅' + if (status === 'WARN') return '⚠️' + if (status === 'FAIL') return '❌' + return ' ' +}// Run if executed directly +if (import.meta.url === `file://${process.argv[1]}`) { + process.exit(printGateReport()); +}