feat(dacli): render pitfalls rationale + clarify purpose JSDoc
This commit is contained in:
1 parent
319221148b
commit
cfa3135986
2 files changed
+34
-1
No files matched your search
+9
-1
@@ -14,10 +14,12 @@ export interface DacliHelp {
|
||||
example?: string | string[]
|
||||
source?: { web?: string; api?: string; ref?: string }
|
||||
|
||||
/** 反模式: ❌ 错 / ✅ 对 配对 */
|
||||
/** 反模式: ❌ 错 / → 理由 / ✅ 对 三段式 (AI 学习用的关键知识) */
|
||||
pitfalls?: Array<{
|
||||
wrong: string
|
||||
right: string
|
||||
/** 1-2 句解释: 为什么错的方式有问题 — 这是 AI 学习的核心知识 */
|
||||
rationale?: string
|
||||
severity?: 'P0' | 'P1' | 'P2'
|
||||
}>
|
||||
|
||||
@@ -41,6 +43,9 @@ export type AiHelp = DacliHelp
|
||||
* 渲染 DacliHelp 为 Commander addHelpText('after', ...) 可接受的字符串.
|
||||
* 包含 4 新段: Pitfalls / Best Practices / Decision Tree / Related Refs.
|
||||
* 也渲染 example / source / notes (legacy) 段.
|
||||
*
|
||||
* Note: `help.purpose` is NOT rendered here — it is intended for Commander's
|
||||
* `.description(help.purpose)` call, which commands should make separately.
|
||||
*/
|
||||
export function renderDacliHelp(help: DacliHelp): string {
|
||||
const sections: string[] = []
|
||||
@@ -67,6 +72,9 @@ export function renderDacliHelp(help: DacliHelp): string {
|
||||
for (const p of help.pitfalls) {
|
||||
const sev = p.severity ? ` [${p.severity}]` : ''
|
||||
sections.push(` ❌ ${p.wrong}${sev}`)
|
||||
if (p.rationale) {
|
||||
sections.push(` → ${p.rationale.replace(/\n/g, '\n ')}`)
|
||||
}
|
||||
sections.push(` ✅ ${p.right.replace(/\n/g, '\n ')}`)
|
||||
sections.push('')
|
||||
}
|
||||
|
||||
@@ -66,3 +66,28 @@ describe('renderDacliHelp', () => {
|
||||
expect(out).not.toContain('Related Refs')
|
||||
})
|
||||
})
|
||||
|
||||
describe('renderDacliHelp pitfalls rationale', () => {
|
||||
it('should render rationale as intermediate → line when provided', () => {
|
||||
const out = renderDacliHelp({
|
||||
purpose: 'Create a form',
|
||||
pitfalls: [{
|
||||
wrong: 'wrong way',
|
||||
right: 'right way',
|
||||
rationale: 'AI defaults to wrong',
|
||||
severity: 'P0',
|
||||
}],
|
||||
})
|
||||
expect(out).toContain('→ AI defaults to wrong')
|
||||
expect(out).toContain('❌ wrong way [P0]')
|
||||
expect(out).toContain('✅ right way')
|
||||
})
|
||||
|
||||
it('should omit rationale line when not provided', () => {
|
||||
const out = renderDacliHelp({
|
||||
purpose: 'Create a form',
|
||||
pitfalls: [{ wrong: 'wrong', right: 'right', severity: 'P0' }],
|
||||
})
|
||||
expect(out).not.toContain('→')
|
||||
})
|
||||
})
|
||||
Reference in new issue
Block a user