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:
1 parent
da8c1db076
commit
3adbd656d6
2 files changed
+41
-5
No files matched your search
+20
-5
@@ -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 */
|
||||
|
||||
@@ -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')
|
||||
})
|
||||
})
|
||||
Reference in new issue
Block a user