[Refactor]: Convert 5-6 parameter functions to use options objects

[sjnims]

Feature Type

Pipeline architecture

Problem or Need

19 functions across Stages 2, 3, and 4 have 5-6 parameters, which exceeds the recommended threshold of 4. While less critical than the 8-parameter functions tracked in #306, these would benefit from the same options object pattern for consistency and maintainability.

Stage 2 - Generation (4 functions):

File	Function	Params	Line
src/stages/2-generation/cost-estimator.ts	estimateGenerationCost	6	113
src/stages/2-generation/cost-estimator.ts	countPromptTokens	5	76
src/stages/2-generation/diversity-manager.ts	createBaseScenario	5	71
src/stages/2-generation/agent-scenario-generator.ts	generateAllAgentScenarios	5	321
src/stages/2-generation/skill-scenario-generator.ts	generateAllSkillScenarios	5	207

Stage 3 - Execution (3 functions):

File	Function	Params	Line
src/stages/3-execution/index.ts	runExecution	5	101
src/stages/3-execution/plugin-loader.ts	buildPluginQueryInput	5	98

Stage 4 - Evaluation (12 functions):

File	Function	Params	Line
src/stages/4-evaluation/multi-sampler.ts	evaluateWithMultiSampling	6	173
src/stages/4-evaluation/aggregation/scenario-results.ts	buildEvaluationResult	6	31
src/stages/4-evaluation/detection/capture-detection.ts	createDetection	5	28
src/stages/4-evaluation/detection/orchestrator.ts	detectAllComponentsWithHooks	5	110
src/stages/4-evaluation/index.ts	runSynchronousEvaluation	5	258
src/stages/4-evaluation/index.ts	calculateAndSaveMetrics	5	350
src/stages/4-evaluation/index.ts	runEvaluation	5	408
src/stages/4-evaluation/llm-judge.ts	evaluateWithLLMJudge	5	270
src/stages/4-evaluation/llm-judge.ts	evaluateWithFallback	5	338
src/stages/4-evaluation/llm-judge.ts	evaluateWithJsonFallback	5	397
src/stages/4-evaluation/multi-sampler.ts	evaluateSingleSample	5	304
src/stages/4-evaluation/multi-sampler.ts	runJudgment	5	340

Proposed Solution

Apply the same options object pattern as #306:

// Example for createDetection
interface CreateDetectionOptions {
  componentType: ComponentType;
  componentName: string;
  triggered: boolean;
  confidence: DetectionConfidence;
  reason: string;
}

function createDetection(options: CreateDetectionOptions): Detection

Recommended approach:

1. Address Stage 4 functions first (most functions, highest impact)
2. Then Stage 3 functions
3. Finally Stage 2 functions

Pipeline Stage Affected

General / Multiple stages

Component Type (if applicable)

Not component-specific

Alternatives Considered

• Higher threshold (6 params): Would only catch the worst offenders, but 5 params is already at the boundary of maintainability
• Gradual adoption: Refactor as functions are modified for other reasons (lower priority approach)
• Skip Stage 2: Generation functions are less frequently modified

How important is this feature to you?

Low - Just a suggestion

Additional Context

Acceptance Criteria:

• All 19 functions converted to options object pattern
• Interface types defined and exported as needed
• All call sites updated
• No functional changes (behavior must remain identical)
• All tests pass

Depends on: #306 (address 8-parameter functions first for consistency)

Related: See anti-pattern-audit.md section 3.1.1 for full analysis

---

🤖 Created with Claude Code

[claude]

Analysis: Convert 5-6 Parameter Functions to Options Objects

1. Problem Assessment

Problem is clearly defined: The issue identifies 19 functions across Stages 2, 3, and 4 with 5-6 parameters that would benefit from refactoring to use options objects. This is a code quality improvement complementary to #306 (8-parameter functions).

Root cause: Functions have accumulated multiple parameters over time as features were added. While not as critical as 8-parameter functions, they still present maintainability issues:

• Positional parameters make call sites harder to read
• Type-compatible parameters can be accidentally swapped without type errors
• Adding new parameters requires updating all call sites
• Documentation is less discoverable than named properties

Pipeline stages affected:

• Stage 2 (Generation): 5 functions - cost estimation and scenario generation utilities
• Stage 3 (Execution): 2 functions - execution entry point and plugin loader
• Stage 4 (Evaluation): 12 functions - evaluation orchestration, LLM judge, and result aggregation

The highest concentration is in Stage 4, which makes sense as evaluation involves complex coordination of multiple detection strategies and result aggregation.

2. Proposed Solution Assessment

The proposed approach is sound:

• Options object pattern is the standard TypeScript solution for functions with many parameters
• Maintains backward compatibility if needed via wrapper functions
• Improves IDE support and discoverability
• Self-documenting at call sites

Tradeoffs:

• Pros: Named parameters improve readability, easy to add optional parameters without breaking changes, TypeScript enforces required fields, consistent with [Refactor]: Convert 8-parameter functions to use options objects #306 refactoring
• Cons: Requires updates to all call sites (but this is a one-time cost), slightly more verbose interface definitions

Edge cases to consider:

1. Default parameters: Functions like estimateGenerationCost (src/stages/2-generation/cost-estimator.ts:113) have defaults (concurrency = 10). These should become optional properties with JSDoc defaults.
2. Type inference: Some functions use ReturnType for parameter types (e.g., buildEvaluationResult at src/stages/4-evaluation/aggregation/scenario-results.ts:31). Options interfaces should preserve this.
3. Internal vs public functions: createDetection (src/stages/4-evaluation/detection/capture-detection.ts:28) is internal. Options pattern still improves readability but lower priority for public API concerns.

Files/functions requiring changes:

Stage 2 - Generation (5 functions):

• src/stages/2-generation/cost-estimator.ts:113 - estimateGenerationCost (6 params)
• src/stages/2-generation/cost-estimator.ts:76 - countPromptTokens (5 params)
• src/stages/2-generation/diversity-manager.ts:71 - createBaseScenario (5 params)
• src/stages/2-generation/agent-scenario-generator.ts:321 - generateAllAgentScenarios (5 params)
• src/stages/2-generation/skill-scenario-generator.ts:207 - generateAllSkillScenarios (5 params)

Stage 3 - Execution (2 functions):

• src/stages/3-execution/index.ts:101 - runExecution (5 params)
• src/stages/3-execution/plugin-loader.ts:98 - buildPluginQueryInput (5 params)

Stage 4 - Evaluation (12 functions):

• src/stages/4-evaluation/multi-sampler.ts:173 - evaluateWithMultiSampling (6 params)
• src/stages/4-evaluation/aggregation/scenario-results.ts:31 - buildEvaluationResult (6 params)
• src/stages/4-evaluation/detection/capture-detection.ts:28 - createDetection (5 params)
• src/stages/4-evaluation/detection/orchestrator.ts:110 - detectAllComponentsWithHooks (5 params)
• src/stages/4-evaluation/index.ts:258 - runSynchronousEvaluation (5 params)
• src/stages/4-evaluation/index.ts:350 - calculateAndSaveMetrics (5 params)
• src/stages/4-evaluation/index.ts:408 - runEvaluation (5 params)
• src/stages/4-evaluation/llm-judge.ts:270 - evaluateWithLLMJudge (5 params)
• src/stages/4-evaluation/llm-judge.ts:338 - evaluateWithFallback (5 params)
• src/stages/4-evaluation/llm-judge.ts:397 - evaluateWithJsonFallback (5 params)
• src/stages/4-evaluation/multi-sampler.ts:304 - evaluateSingleSample (5 params)
• src/stages/4-evaluation/multi-sampler.ts:340 - runJudgment (5 params)

3. Alternative Approaches

Option A: Staged refactoring by impact (Recommended) - Prioritize based on public API surface, frequency of calls, and complexity of parameters. Order: Stage 3 to Stage 4 to Stage 2. Rationale: runExecution is the main Stage 3 entry point (called from CLI/library), Stage 4 functions have most instances (12 functions), Stage 2 functions are less frequently modified.

Option B: Per-file refactoring - Refactor all functions in a file at once to maintain file-level consistency. Pros: Logical units, easier to review. Cons: Mixes high and low priority changes.

Option C: Higher threshold (6+ parameters only) - Only refactor functions with 6 parameters: estimateGenerationCost, evaluateWithMultiSampling, buildEvaluationResult. Pros: Minimal change, addresses worst cases. Cons: Leaves inconsistency; 5 parameters is already at the maintainability boundary.

Option D: Gradual adoption - Apply pattern only when functions are modified for other reasons. Pros: Zero immediate cost. Cons: Indefinite inconsistency; may never complete.

4. Implementation Considerations

Files affected: 9 source files containing the 19 functions, test files calling these functions (need updates), call sites within other source files.

Breaking changes: Functions are currently exported, so this is a breaking change to the public API. Mitigation: Provide wrapper functions with old signatures that forward to new implementation. If this is internal-only code, can skip wrappers.

Testing requirements: (1) Unit tests: Update test files that call these functions. (2) Integration tests: Should pass without changes if behavior is identical. (3) Type tests: Ensure TypeScript compilation succeeds with proper type inference.

State/resume capability impact: No impact expected: these functions don't directly interact with state serialization. State interfaces in src/types/state.ts remain unchanged.

Implementation steps:

1. Create options interfaces in same files as functions
2. Update function signatures to accept options objects
3. Update function bodies to destructure options
4. Update all call sites to pass options objects
5. Update tests
6. Run npm run build && npm run lint && npm run typecheck && npm test
7. Consider adding ESLint rule to prevent future parameter accumulation

5. Recommendation

Recommended approach: Option A - Staged refactoring by priority

Phase 1: Stage 3 - runExecution (main execution entry point, called from CLI), buildPluginQueryInput (plugin loading utility)

Phase 2: Stage 4 - Frequently-called functions: buildEvaluationResult, evaluateWithMultiSampling, evaluateWithLLMJudge, evaluateWithFallback, evaluateWithJsonFallback. Then utility functions: createDetection, detectAllComponentsWithHooks, runSynchronousEvaluation, runEvaluation, calculateAndSaveMetrics, evaluateSingleSample, runJudgment.

Phase 3: Stage 2 - estimateGenerationCost, countPromptTokens (cost estimation), createBaseScenario (scenario utilities), generateAllAgentScenarios, generateAllSkillScenarios (top-level generators)

Coordination with #306: This issue correctly identifies dependency on #306. The 8-parameter functions should be addressed first to establish consistent options pattern across the codebase, avoid rework if pattern changes, and learn from any issues encountered with the larger refactoring.

Summary: This is a well-scoped refactoring that will improve code maintainability with minimal risk. The staged approach allows for incremental progress and easier review. Recommend proceeding after #306 is complete.

[sjnims]

PR submitted: #311