[Refactoring] Decompose 287-line assembleAndValidateConfig in src/commands/validators/config-assembly.ts #4879

Refactoring Opportunity

Summary

• File: src/commands/validators/config-assembly.ts
• Current size: 329 lines
• Key function: assembleAndValidateConfig — 287 lines (lines 42–329)
• Responsibilities identified: 3 distinct concerns (config assembly + env-file parsing utility + 7 independent post-assembly validation guards)
• Score: 5 (+2 function >80 lines, +3 clearly >2 responsibilities)

Evidence

assembleAndValidateConfig (lines 42–329) is the final stage of the validation pipeline and combines three conceptually separate layers in a single 287-line function:

Concern 1 — Env-file parsing utility (lines 49–77, ~29 lines)
Two nested closure functions (readEnvVarFromEnvFiles, readCopilotModelFromEnvFiles) parse --env-file contents to pre-flight check the COPILOT_MODEL value. This is a filesystem+regex utility that has nothing to do with "assembling config" and is not available to other callers who may also need to read env files.

const readEnvVarFromEnvFiles = (envFile: unknown, key: string): string | undefined => {
  // 24-line inline env-file scanner
};
const readCopilotModelFromEnvFiles = (envFile: unknown): string | undefined => {
  return readEnvVarFromEnvFiles(envFile, 'COPILOT_MODEL');
};

Concern 2 — Config assembly (lines 81–107, ~27 lines)
Calls buildConfig({...}) with the pre-validated sub-results. This is the function's true core and is only ~27 lines.

Concern 3 — Post-assembly validation guards (lines 109–326, ~218 lines)
Seven independent guard blocks, each checking a different feature area:

1. Docker host URI format (lines 113–146)
2. Agent timeout (line 149)
3. Rate-limit config building + flag validation (lines 152–168)
4. --enable-token-steering flag compatibility (lines 171–179)
5. Host access / port rules (lines 192–231)
6. API proxy configuration warnings (lines 233–281)
7. Copilot model validation (lines 283–326)

Each guard is independent — guard #7 (Copilot model) has no dependency on guard #3 (rate limits), etc.

Proposed Decomposition

Extract readEnvVarFromEnvFiles to src/parsers/env-parsers.ts
A module-level exported helper, reusable by any caller that needs to scan env files. This removes the ~29-line nested closure from assembleAndValidateConfig.

Group the validation guards
The 7 post-assembly guards cover two natural clusters:

• Infrastructure guards (docker host, seccomp path): validateInfrastructureOptions(config)
• Feature-flag guards (rate limits, token steering, host access, API proxy, Copilot model): validateFeatureFlags(config, options, networkOptions, agentOptions)

Or simply extract each guard into a small named function (validateDockerHostOption, validateRateLimitOptions, etc.) and call them in sequence — the existing validateRateLimitFlags, validateEnableTokenSteeringFlag, validateAllowHostPorts pattern already used by some guards.

Result: assembleAndValidateConfig reduces from 287 lines to ~50 lines:

export function assembleAndValidateConfig(...): WrapperConfig {
  const config = buildConfig({ ... });
  validateDockerHostOption(config);
  applyAgentTimeout(options.agentTimeout, config, logger);
  applyRateLimitConfig(config, options);
  validateFeatureFlagCompatibility(config);
  validateHostAccessConfig(config, networkOptions);
  validateApiProxyConfig(config, networkOptions, agentOptions);
  validateCopilotModelOption(config, agentOptions);
  return config;
}

Affected Callers

grep -rn "assembleAndValidateConfig\|from.*validators/config-assembly" src/ 2>/dev/null

Known callers:

• src/commands/main-action.ts — the primary production caller
• src/commands/validators/config-assembly.test.ts (933 lines of tests) — will need helper imports updated if guards are extracted

Effort Estimate

Medium — extracting readEnvVarFromEnvFiles is low risk; decomposing 7 guard blocks into named helpers is mechanical but touches many lines.

Benefits

• assembleAndValidateConfig becomes a readable ~50-line orchestrator
• readEnvVarFromEnvFiles becomes reusable and independently testable
• Individual validation guards are easier to unit-test in isolation
• Adding a new post-assembly guard no longer requires editing a 287-line function

Detected by Refactoring Scanner workflow. Run date: 2026-06-13

Generated by Refactoring Opportunity Scanner · ◷

• expires on Aug 12, 2026, 3:35 PM UTC