feat(dacli): CI 关卡 G 自动检查 webapi 镜像架构 (regression audit §4.4 落地)

v3.0+ regression audit §4.4 建议的防御机制, 现已实现:

**新增 src/commands/_gate_webapi.ts** (310 行):
- 自动检查 3 大维度:
  1. 命令 webapi 引用率 (app/dict/menu/form 应有, apis/doc 元工具 0 正确)
  2. _validate.ts 镜像精度 ("镜像 web" 注释数 + 精确行号 + ENCODE_REGEXP 复用)
  3. 回归盲点扫描 (找无 webapi 引用的命令 + 缺镜像注释的 _validate + BS-56 硬编码正则)
- 退出码: 0=PASS / 1=FAIL(阻塞) / 2=WARN(提示)
- 用法: `npx tsx src/commands/_gate_webapi.ts` (CI 集成入口)

**初始扫描结果** (基线):
- 命令: PASS 18 / WARN 2 / FAIL 4 / 总 24
- _validate.ts: 总 18, 镜像注释率 18/18 (100%), ENCODE_REGEXP 复用率 8/18 (44%)
- 总体: FAIL

**当前违规清单** (后续 turn 修复):
- P0 缺 webapi: org / portal / print / report
- BS-56 缺 ENCODE_REGEXP: datasource / di / dict / form / menu / msg / role / schedule
- (这些是历史 _validate.ts 升级遗漏, 不是本次 turn 引入)

**防御价值**:
- 未来所有新代码改动自动检查, 防止重蹈"经验复刻"覆辙
- 新增 _validate.ts 不带"镜像 web" 注释会被 WARN
- 处理 enCode 但硬编码正则会被 FAIL (BS-56 防御)
- 无 webapi 引用的新命令会被 FAIL (P0 防御)

测试: TS 编译干净 + 实际跑通 (输出 24 命令 + 18 _validate 检查)

详见 docs/cmd-review/regression-2026-06-29.md §4.4
This commit is contained in:
ssw committed 2026-06-29 17:12:43 +08:00
1 parent 676fce5778
commit 8c10df63b3
1 file changed
+320
+320
View File
@@ -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());
}