fix(dacli): restore _aiMeta side effect + Phase 1 JSDoc + outputHelp test

- installHelpHook: restore _aiMeta side effect (170 call sites depend on
  --ai-help/--example/--source flag interception, all broken at HEAD)
- installHelpHook: add empty-content guard (skip addHelpText if renderDacliHelp
  returns empty string to avoid blank trailing newline in --help)
- help.ts: restore Phase 1 architecture JSDoc (Task 1.1/1.2/1.3 + legacy compat
  notes for Task 1.6)
- tests/core/help.spec.ts: re-add outputHelp integration test (verifies
  addHelpText content actually reaches --help output, not just helpInformation)
This commit is contained in:
ssw committed 2026-07-16 22:02:41 +08:00
1 parent da8c1db076
commit 3adbd656d6
2 files changed
+41 -5

No files matched your search

+20 -5
View File
@@ -1,9 +1,15 @@
/**
* help.ts — AI 友好帮助体系
* dacli --help system: 知识落地到 CLI 自己 (Phase 1 改造).
*
* 用法: 给 Commander.js 命令对象挂元数据 (cmd as any)._aiMeta = meta
* 由 cli.ts 顶层在 parse 之前扫 argv 拦截 --ai-help / --example / --source
* 打印后 process.exit, 避免命令真正执行 / 校验 requiredOption
* 架构 (v0.22+):
* - DacliHelp interface (Task 1.1): 含 4 新字段 pitfalls/bestPractices/decisionTree/relatedRefs
* - renderDacliHelp() (Task 1.2): 把 DacliHelp 序列化为 addHelpText 文本
* - installHelpHook() (Task 1.3): 双路径注入 — .description(purpose) + .addHelpText('after', ...)
*
* Legacy compat (Task 1.6 将清理):
* - installAiHelpHook = installHelpHook (alias for source-compat during migration)
* - _aiMeta 副作用保留到 Task 1.6 删 --ai-help flag 时
* - AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp 是遗留代码
*/
import type { Command } from 'commander'
@@ -128,8 +134,17 @@ const AI_FLAGS = new Set(['--ai-help', '--example', '--source'])
* (Commander `helpInformation()` 不内置, 仅 `outputHelp()` / `--help` 实际输出可见)
*/
export function installHelpHook(command: Command, help: DacliHelp): void {
// Primary path: dual-path Commander integration (purpose + addHelpText)
command.description(help.purpose)
command.addHelpText('after', renderDacliHelp(help))
const rendered = renderDacliHelp(help)
if (rendered.trim().length > 0) {
command.addHelpText('after', `\n${rendered}`)
}
// Legacy compat: preserve _aiMeta side effect for --ai-help/--example/--source
// flag interception. Task 1.6 will delete this and the interceptor.
;(command as unknown as { _aiMeta?: DacliHelp })._aiMeta = help
}
/** Backward-compat alias during migration */
+21
View File
@@ -100,4 +100,25 @@ describe('installHelpHook', () => {
const helpOutput = cmd.helpInformation()
expect(helpOutput).toContain('test purpose')
})
it('should inject sections via addHelpText into actual --help output', () => {
const cmd = new Command('test')
installHelpHook(cmd, {
purpose: 'test purpose',
example: 'dacli foo --bar',
bestPractices: ['use --autoRelease'],
})
// Capture the full output via configureOutput
let captured = ''
cmd.configureOutput({ writeOut: (s) => { captured += s } })
cmd.outputHelp()
// Sections must appear in actual --help output (NOT helpInformation)
expect(captured).toContain('test purpose') // from .description()
expect(captured).toContain('Examples:')
expect(captured).toContain('dacli foo --bar')
expect(captured).toContain('Best Practices:')
expect(captured).toContain('use --autoRelease')
})
})