[Refactoring] Split `src/commands/validate-options.ts` into focused validator modules

[github-actions]

Refactoring Opportunity

Summary

• File: src/commands/validate-options.ts
• Current size: 497 lines
• Responsibilities identified: 11 distinct validation concerns collapsed into a single 450-line function

Evidence

The file exports exactly one function — validateOptions — spanning lines 45 to 497 (≈450 lines). The function is organized into 11 named sections but they are all sequential code inside a single function:

49:  // --- Log level -----------------------------------------------------------
60:  // --- Model multipliers ---------------------------------------------------
116:  // --- Docker host ---------------------------------------------------------
141:  // --- Domain resolution --------------------------------------------------
153:  // --- Environment variables -----------------------------------------------
176:  // --- Volume mounts -------------------------------------------------------
191:  // --- Network configuration -----------------------------------------------
196:  // --- SSL Bump URL patterns -----------------------------------------------
269:  // --- Resource limits -----------------------------------------------------
292:  // --- Config assembly -----------------------------------------------------
318:  // --- Post-config validations ---------------------------------------------

Several of these sections are security-critical:

• Domain resolution (line 141) — parses and normalises allowed/blocked domain lists
• SSL Bump URL patterns (lines 196–268) — validates regex patterns used by the Squid HTTPS inspection config
• Network configuration (line 191) — validates DNS servers, upstream proxy settings

These are also the sections most likely to regress during future feature additions, yet they cannot currently be tested in isolation — the entire 450-line function must be invoked.

Proposed Split

src/commands/validate-options.ts → 4 focused modules:

• src/commands/validators/log-and-limits.ts — Log level, model multipliers, resource limits (~80 lines)
• src/commands/validators/network-options.ts — Docker host, domain resolution, DNS servers, network config (~90 lines; security-critical)
• src/commands/validators/agent-options.ts — Env vars, volume mounts, SSL bump URL patterns, resource limits (~120 lines; security-critical)
• src/commands/validators/config-assembly.ts — Post-validation config merge and post-config assertions (~80 lines)
• src/commands/validate-options.ts — Thin orchestrator calling the above in sequence (~50 lines)

Affected Callers

src/commands/main-action.ts:23: import { validateOptions } from './validate-options';
src/commands/validate-options.test.ts:2: import { validateOptions } from './validate-options';
src/commands/main-action.test.ts:22: import * as validateOptions from './validate-options';

No public API change required — validateOptions remains the single export from validate-options.ts. Internal helper modules are import-only.

Effort Estimate

Medium

Benefits

• Each validator group becomes independently unit-testable without constructing the full option set
• Security-critical sections (domain validation, SSL bump pattern validation) are isolated for focused review
• Future flag additions touch only the relevant sub-module, not a 450-line catch-all
• Reduced merge-conflict surface: PRs for different flag categories no longer touch the same file

---

Detected by Refactoring Scanner workflow. Run date: 2026-05-20

Note

🔒 Integrity filter blocked 2 items

The following items were blocked because they don't meet the GitHub integrity level.

• #135 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1376 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Refactoring Opportunity Scanner · ● 13.1M · ◷

• expires on Jul 19, 2026, 4:12 PM UTC