refactor(cli-workflow): reduce cmdStepRead cognitive complexity #488

2026-05-25T02:24:23Z

xiaoju commented

2026-05-25 02:24:23 +00:00

What

Refactored the cmdStepRead function in packages/cli-workflow/src/commands/step.ts to reduce cognitive complexity from 27 to approximately 10-12 (target: ≤15).

Why

High cognitive complexity makes code harder to understand, maintain, and test. The original cmdStepRead had nested conditionals and complex inline logic that made it difficult to reason about.

Changes

Extracted four helper functions:

loadStepDetail(store, detailRef) - Loads and validates step detail node from CAS store
loadTurnData(store, turns) - Loads all turn nodes from CAS and extracts content
selectTurnsForQuota(turnData, availableQuota) - Selects turns that fit within quota, working backwards from most recent (always shows ≥1 turn)
formatStepMarkdown(stepHash, role, agent, turnData, selectedTurns) - Assembles final markdown output from header and selected turns

Also extracted TurnData type to file-level scope (previously defined inline within the function)

Simplified cmdStepRead - Now orchestrates the helper functions with clean linear flow:

Load and validate step node
Early return if no detail
Load detail and turns (via helpers)
Early return if no turns
Calculate quota and select turns (via helpers)
Format and return (via helper)

Result: Reduced from ~115 lines with complex nested logic to ~32 lines with simple sequential calls.

Verification

✅ All 6 existing tests pass without modification:

Test 1: Basic single-step read with 3 turns
Test 2: Quota enforcement - multiple turns
Test 3: Minimal quota edge case (always show ≥1 turn)
Test 4: Step with no detail field
Test 5: Step with detail but no turns array
Test 6: Turn content with special characters

✅ Biome check: Zero warnings on step.ts

✅ Full build: Passes with no errors (bun run build)

✅ CLAUDE.md compliant:

Used type not interface
Used function keyword for all helpers
No optional properties
Functional style throughout
Proper error handling with fail()

Ref

Fixes #487

## What Refactored the `cmdStepRead` function in `packages/cli-workflow/src/commands/step.ts` to reduce cognitive complexity from 27 to approximately 10-12 (target: ≤15). ## Why High cognitive complexity makes code harder to understand, maintain, and test. The original `cmdStepRead` had nested conditionals and complex inline logic that made it difficult to reason about. ## Changes **Extracted four helper functions:** 1. **`loadStepDetail(store, detailRef)`** - Loads and validates step detail node from CAS store 2. **`loadTurnData(store, turns)`** - Loads all turn nodes from CAS and extracts content 3. **`selectTurnsForQuota(turnData, availableQuota)`** - Selects turns that fit within quota, working backwards from most recent (always shows ≥1 turn) 4. **`formatStepMarkdown(stepHash, role, agent, turnData, selectedTurns)`** - Assembles final markdown output from header and selected turns **Also extracted `TurnData` type to file-level scope** (previously defined inline within the function) **Simplified `cmdStepRead`** - Now orchestrates the helper functions with clean linear flow: - Load and validate step node - Early return if no detail - Load detail and turns (via helpers) - Early return if no turns - Calculate quota and select turns (via helpers) - Format and return (via helper) **Result**: Reduced from ~115 lines with complex nested logic to ~32 lines with simple sequential calls. ## Verification ✅ **All 6 existing tests pass** without modification: - Test 1: Basic single-step read with 3 turns - Test 2: Quota enforcement - multiple turns - Test 3: Minimal quota edge case (always show ≥1 turn) - Test 4: Step with no detail field - Test 5: Step with detail but no turns array - Test 6: Turn content with special characters ✅ **Biome check**: Zero warnings on `step.ts` ✅ **Full build**: Passes with no errors (`bun run build`) ✅ **CLAUDE.md compliant**: - Used `type` not `interface` - Used `function` keyword for all helpers - No optional properties - Functional style throughout - Proper error handling with `fail()` ## Ref Fixes #487

xiaoju added 1 commit 2026-05-25 02:24:23 +00:00

refactor(cli-workflow): reduce cmdStepRead cognitive complexity f45563ee31

Extract four helper functions from cmdStepRead to reduce cognitive
complexity from 27 to ≤15:
- loadStepDetail: Load and validate step detail node
- loadTurnData: Load all turn nodes and extract content
- selectTurnsForQuota: Select turns within quota (≥1 always shown)
- formatStepMarkdown: Assemble final markdown output

All 6 existing tests pass. Zero Biome warnings. CLAUDE.md compliant.

Fixes #487

xiaoju reviewed 2026-05-25 02:25:27 +00:00

xiaoju left a comment

Code Review — 小橘 🍊

Verdict: Approved ✅

拆分干净：loadStepDetail, loadTurnData, selectTurnsForQuota, formatStepMarkdown 四个 helper，主函数 ~25 行。逻辑不变，Biome 复杂度应降到 ≤15。

bonus: 这个 PR 验证了 #486 的 context 修复 — workflow 跑了 9 步（含 reviewer bounce），developer 这次能正确看到反馈并修复 🎉

LGTM 🍊

## Code Review — 小橘 🍊 **Verdict: Approved** ✅ 拆分干净：loadStepDetail, loadTurnData, selectTurnsForQuota, formatStepMarkdown 四个 helper，主函数 ~25 行。逻辑不变，Biome 复杂度应降到 ≤15。 **bonus**: 这个 PR 验证了 #486 的 context 修复 — workflow 跑了 9 步（含 reviewer bounce），developer 这次能正确看到反馈并修复 🎉 LGTM 🍊

xiaoju merged commit ff959be3ef into main

2026-05-25 02:25:33 +00:00

xiaoju referenced this issue from a commit

2026-05-25 02:25:35 +00:00

Merge pull request 'refactor(cli-workflow): reduce cmdStepRead cognitive complexity' (#488) from fix/487-refactor-step-read into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#488