simplification: reduce function complexity in .agents/scripts/tech-stack-helper.sh (5 functions >100 lines)

[marcusquinn]

Complexity scan finding (automated, GH#5628)

File: .agents/scripts/tech-stack-helper.sh
Violations: 5 functions exceed 100 lines

Functions exceeding threshold

bq_reverse_lookup() 131 lines
merge_results() 113 lines
cmd_lookup() 138 lines
cmd_reverse() 238 lines
main() 149 lines

Proposed action

Break down the listed functions into smaller, focused helper functions. Each function should ideally be under 100 lines.

Verification

• bash -n <file> (syntax check)
• shellcheck <file> (lint)
• Run existing tests if present
• Confirm no functionality is lost

Confidence: medium

This is an automated scan. The function lengths are factual, but the best decomposition strategy requires human judgment.

---

To approve or decline, comment on this issue:

• approved — removes the review gate and queues for automated dispatch
• declined: <reason> — closes this issue (include your reason after the colon)

[marcusquinn]

Completed via PR #5659

What was done:

• Split all 5 oversized functions into focused single-responsibility helpers (10 new helpers added)
• bq_reverse_lookup 131→82 lines: extracted _bq_reverse_validate_params (param validation/normalisation) and _bq_reverse_build_clauses (SQL WHERE clause construction)
• merge_results 113→64 lines: extracted _merge_collect_results (file-reading loop) and _merge_empty_result (empty-result JSON emitter)
• cmd_lookup 138→78 lines: extracted _lookup_run_parallel and _lookup_run_sequential (the two execution branches)
• cmd_reverse 238→82 lines: extracted _reverse_parse_args (arg-parsing, 99 lines) and _reverse_via_providers (provider-helper path)
• main 149→34 lines: extracted _main_parse_global_opts (option parsing) and _main_route_command (command dispatch)

How it was tested:

• bash -n .agents/scripts/tech-stack-helper.sh → syntax OK
• shellcheck -S warning .agents/scripts/tech-stack-helper.sh → zero violations
• All 5 original functions verified under 100 lines; all 10 new helpers also under 100 lines

Key decisions:

• All helpers kept in the same single file (constraint: max 5 files changed = 1 file here)
• Helper functions prefixed with _ to signal internal use
• _reverse_parse_args uses temp-file output pattern (bash 3.2 compatible — no associative arrays or namerefs)
• _merge_collect_results uses temp files for output rather than global variables

Files changed:

• .agents/scripts/tech-stack-helper.sh — 409 insertions, 281 deletions (1 file)

Blockers encountered:

• None

Follow-up needs:

• None

[marcusquinn]

Completed via PR #5659 (merged).

• Model: sonnet (anthropic/claude-sonnet-4-6)
• Attempts: 1
• Duration: ~10 min