Coverage for little_loops / cli_args.py: 36%

1"""Shared CLI argument definitions for little-loops tools. 

2 

3Provides reusable functions for adding common command-line arguments 

4to argparse parsers, ensuring consistency across ll-auto, ll-parallel, 

5and ll-sprint commands. 

6""" 

7 

8from __future__ import annotations 

9 

10import argparse 

11import re 

12from pathlib import Path 

13 

14 

15def add_dry_run_arg(parser: argparse.ArgumentParser) -> None: 

16 """Add --dry-run/-n argument to parser.""" 

17 parser.add_argument( 

18 "--dry-run", 

19 "-n", 

20 action="store_true", 

21 help="Show what would be done without making changes", 

22 ) 

23 

24 

25def add_resume_arg(parser: argparse.ArgumentParser) -> None: 

26 """Add --resume/-r argument to parser.""" 

27 parser.add_argument( 

28 "--resume", 

29 "-r", 

30 action="store_true", 

31 help="Resume from previous checkpoint", 

32 ) 

33 

34 

35def add_config_arg(parser: argparse.ArgumentParser) -> None: 

36 """Add --config/-C argument to parser.""" 

37 parser.add_argument( 

38 "--config", 

39 "-C", 

40 type=Path, 

41 default=None, 

42 help="Path to project root (default: current directory)", 

43 ) 

44 

45 

46def add_only_arg(parser: argparse.ArgumentParser) -> None: 

47 """Add --only/-o argument for filtering specific issues.""" 

48 parser.add_argument( 

49 "--only", 

50 "-o", 

51 type=str, 

52 default=None, 

53 help="Comma-separated list of issue IDs to process (e.g., BUG-001,FEAT-002)", 

54 ) 

55 

56 

57def add_skip_arg(parser: argparse.ArgumentParser, help_text: str | None = None) -> None: 

58 """Add --skip argument for excluding specific issues. 

59 

60 Args: 

61 parser: The argument parser to add the argument to 

62 help_text: Optional custom help text. If not provided, uses default. 

63 """ 

64 if help_text is None: 

65 help_text = "Comma-separated list of issue IDs to skip (e.g., BUG-003,FEAT-004)" 

66 parser.add_argument( 

67 "--skip", 

68 "-s", 

69 type=str, 

70 default=None, 

71 help=help_text, 

72 ) 

73 

74 

75def add_max_workers_arg(parser: argparse.ArgumentParser, default: int | None = None) -> None: 

76 """Add --max-workers/-w argument for parallel execution. 

77 

78 Args: 

79 parser: The argument parser to add the argument to 

80 default: Default value. If None, no default is specified. 

81 """ 

82 if default is not None: 

83 parser.add_argument( 

84 "--max-workers", 

85 "-w", 

86 type=int, 

87 default=default, 

88 help=f"Maximum parallel workers (default: {default})", 

89 ) 

90 else: 

91 parser.add_argument( 

92 "--max-workers", 

93 "-w", 

94 type=int, 

95 default=None, 

96 help="Maximum parallel workers", 

97 ) 

98 

99 

100def add_timeout_arg(parser: argparse.ArgumentParser, default: int | None = None) -> None: 

101 """Add --timeout/-t argument for per-issue timeout. 

102 

103 Args: 

104 parser: The argument parser to add the argument to 

105 default: Default value in seconds. If None, no default is specified. 

106 """ 

107 if default is not None: 

108 parser.add_argument( 

109 "--timeout", 

110 "-t", 

111 type=int, 

112 default=default, 

113 help=f"Timeout in seconds (default: {default})", 

114 ) 

115 else: 

116 parser.add_argument( 

117 "--timeout", 

118 "-t", 

119 type=int, 

120 default=None, 

121 help="Timeout in seconds", 

122 ) 

123 

124 

125def add_idle_timeout_arg(parser: argparse.ArgumentParser) -> None: 

126 """Add --idle-timeout argument for idle process termination. 

127 

128 Args: 

129 parser: The argument parser to add the argument to 

130 """ 

131 parser.add_argument( 

132 "--idle-timeout", 

133 type=int, 

134 default=None, 

135 help="Kill worker if no output for N seconds (0 to disable, default: from config)", 

136 ) 

137 

138 

139def add_handoff_threshold_arg(parser: argparse.ArgumentParser) -> None: 

140 """Add --handoff-threshold argument for per-run context handoff override. 

141 

142 Args: 

143 parser: The argument parser to add the argument to 

144 """ 

145 parser.add_argument( 

146 "--handoff-threshold", 

147 type=int, 

148 default=None, 

149 help="Override auto-handoff context threshold (1-100, default: from config)", 

150 ) 

151 

152 

153def add_context_limit_arg(parser: argparse.ArgumentParser) -> None: 

154 """Add --context-limit argument for per-run context window size override. 

155 

156 Args: 

157 parser: The argument parser to add the argument to 

158 """ 

159 parser.add_argument( 

160 "--context-limit", 

161 type=int, 

162 default=None, 

163 help="Override context window token estimate (default: from config or 1000000 for Sonnet/Opus, 200000 for Haiku 4.5)", 

164 ) 

165 

166 

167def add_quiet_arg(parser: argparse.ArgumentParser) -> None: 

168 """Add --quiet/-q argument to suppress output.""" 

169 parser.add_argument( 

170 "--quiet", 

171 "-q", 

172 action="store_true", 

173 help="Suppress non-essential output", 

174 ) 

175 

176 

177def add_skip_analysis_arg(parser: argparse.ArgumentParser) -> None: 

178 """Add --skip-analysis argument to skip dependency discovery.""" 

179 parser.add_argument( 

180 "--skip-analysis", 

181 action="store_true", 

182 help="Skip dependency analysis (use when dependencies are known to be current)", 

183 ) 

184 

185 

186def add_max_issues_arg(parser: argparse.ArgumentParser) -> None: 

187 """Add --max-issues/-m argument for limiting issues processed.""" 

188 parser.add_argument( 

189 "--max-issues", 

190 "-m", 

191 type=int, 

192 default=0, 

193 help="Limit number of issues to process (0 = unlimited)", 

194 ) 

195 

196 

197def parse_issue_ids(value: str | None) -> set[str] | None: 

198 """Parse comma-separated issue IDs into a set. 

199 

200 Args: 

201 value: Comma-separated string like "BUG-001,FEAT-002" or None 

202 

203 Returns: 

204 Set of uppercase issue IDs, or None if value is None 

205 

206 Example: 

207 >>> parse_issue_ids("BUG-001,feat-002") 

208 {'BUG-001', 'FEAT-002'} 

209 >>> parse_issue_ids(None) 

210 None 

211 """ 

212 if value is None: 

213 return None 

214 return {i.strip().upper() for i in value.split(",")} 

215 

216 

217def parse_issue_ids_ordered(value: str | None) -> list[str] | None: 

218 """Parse comma-separated issue IDs into an ordered list. 

219 

220 Like parse_issue_ids but preserves input order, enabling callers to 

221 honor the sequence in which IDs were specified. 

222 

223 Args: 

224 value: Comma-separated string like "BUG-001,FEAT-002" or None 

225 

226 Returns: 

227 List of uppercase issue IDs in input order, or None if value is None 

228 

229 Example: 

230 >>> parse_issue_ids_ordered("BUG-010,FEAT-005,ENH-020") 

231 ['BUG-010', 'FEAT-005', 'ENH-020'] 

232 >>> parse_issue_ids_ordered(None) 

233 None 

234 """ 

235 if value is None: 

236 return None 

237 return [i.strip().upper() for i in value.split(",")] 

238 

239 

240_NUMERIC_RE = re.compile(r"^\d+$") 

241 

242 

243def _id_matches(candidate: str, pattern: str) -> bool: 

244 """Return True if candidate matches pattern, supporting numeric-only patterns. 

245 

246 Args: 

247 candidate: Full issue ID like 'ENH-732' 

248 pattern: Full ID like 'ENH-732' or numeric suffix like '732' 

249 

250 Returns: 

251 True if candidate matches the pattern 

252 

253 Example: 

254 >>> _id_matches("ENH-732", "732") 

255 True 

256 >>> _id_matches("ENH-732", "ENH-732") 

257 True 

258 >>> _id_matches("ENH-732", "BUG-732") 

259 False 

260 """ 

261 if _NUMERIC_RE.match(pattern): 

262 return candidate.split("-")[-1] == pattern 

263 return candidate == pattern 

264 

265 

266VALID_ISSUE_TYPES = {"BUG", "FEAT", "ENH"} 

267 

268VALID_PRIORITIES: frozenset[str] = frozenset({"P0", "P1", "P2", "P3", "P4", "P5"}) 

269 

270 

271def parse_priorities(value: str | None) -> set[str] | None: 

272 """Parse comma-separated priority levels into a validated set. 

273 

274 Args: 

275 value: Comma-separated string like "P1,P2" or None 

276 

277 Returns: 

278 Set of uppercase priority strings, or None if value is None 

279 

280 Raises: 

281 SystemExit: If invalid priority levels are provided (exit code 2) 

282 

283 Example: 

284 >>> parse_priorities("p1,P2") 

285 {'P1', 'P2'} 

286 >>> parse_priorities(None) 

287 None 

288 """ 

289 if value is None: 

290 return None 

291 priorities = {p.strip().upper() for p in value.split(",")} 

292 invalid = priorities - VALID_PRIORITIES 

293 if invalid: 

294 import sys 

295 

296 print( 

297 f"error: invalid priority level(s): {', '.join(sorted(invalid))}. " 

298 f"Valid priorities: {', '.join(sorted(VALID_PRIORITIES))}", 

299 file=sys.stderr, 

300 ) 

301 sys.exit(2) 

302 return priorities 

303 

304 

305def add_priority_arg(parser: argparse.ArgumentParser) -> None: 

306 """Add --priority/-p argument for filtering issues by priority level.""" 

307 parser.add_argument( 

308 "--priority", 

309 "-p", 

310 type=str, 

311 default=None, 

312 help="Comma-separated priority levels to process (e.g., P0, P1,P2)", 

313 ) 

314 

315 

316def add_type_arg(parser: argparse.ArgumentParser) -> None: 

317 """Add --type/-T argument for filtering issues by type prefix.""" 

318 parser.add_argument( 

319 "--type", 

320 "-T", 

321 type=str, 

322 default=None, 

323 help="Comma-separated issue types to process (e.g., BUG, FEAT, ENH)", 

324 ) 

325 

326 

327def parse_issue_types(value: str | None) -> set[str] | None: 

328 """Parse comma-separated issue types into a validated set. 

329 

330 Args: 

331 value: Comma-separated string like "BUG,ENH" or None 

332 

333 Returns: 

334 Set of uppercase type prefixes, or None if value is None 

335 

336 Raises: 

337 SystemExit: If invalid issue types are provided (via argparse error) 

338 

339 Example: 

340 >>> parse_issue_types("bug,enh") 

341 {'BUG', 'ENH'} 

342 >>> parse_issue_types(None) 

343 None 

344 """ 

345 if value is None: 

346 return None 

347 types = {t.strip().upper() for t in value.split(",")} 

348 invalid = types - VALID_ISSUE_TYPES 

349 if invalid: 

350 import sys 

351 

352 print( 

353 f"error: invalid issue type(s): {', '.join(sorted(invalid))}. " 

354 f"Valid types: {', '.join(sorted(VALID_ISSUE_TYPES))}", 

355 file=sys.stderr, 

356 ) 

357 sys.exit(2) 

358 return types 

359 

360 

361def add_common_auto_args(parser: argparse.ArgumentParser) -> None: 

362 """Add arguments common to ll-auto command. 

363 

364 Adds: --resume, --dry-run, --max-issues, --quiet, --only, --skip, --type, --priority, 

365 --config, --idle-timeout, --handoff-threshold, --context-limit 

366 """ 

367 add_resume_arg(parser) 

368 add_dry_run_arg(parser) 

369 add_max_issues_arg(parser) 

370 add_quiet_arg(parser) 

371 add_only_arg(parser) 

372 add_skip_arg(parser) 

373 add_type_arg(parser) 

374 add_priority_arg(parser) 

375 add_config_arg(parser) 

376 add_idle_timeout_arg(parser) 

377 add_handoff_threshold_arg(parser) 

378 add_context_limit_arg(parser) 

379 

380 

381def add_common_parallel_args(parser: argparse.ArgumentParser) -> None: 

382 """Add arguments common to parallel execution tools. 

383 

384 Adds: --dry-run, --resume, --max-workers, --timeout, --idle-timeout, --quiet, --only, --skip, --type, --config, 

385 --context-limit 

386 """ 

387 add_dry_run_arg(parser) 

388 add_resume_arg(parser) 

389 add_max_workers_arg(parser) 

390 add_timeout_arg(parser) 

391 add_idle_timeout_arg(parser) 

392 add_quiet_arg(parser) 

393 add_only_arg(parser) 

394 add_skip_arg(parser) 

395 add_type_arg(parser) 

396 add_config_arg(parser) 

397 add_context_limit_arg(parser) 

398 

399 

400__all__ = [ 

401 "add_dry_run_arg", 

402 "add_resume_arg", 

403 "add_config_arg", 

404 "add_only_arg", 

405 "add_skip_arg", 

406 "add_type_arg", 

407 "add_priority_arg", 

408 "add_max_workers_arg", 

409 "add_timeout_arg", 

410 "add_idle_timeout_arg", 

411 "add_handoff_threshold_arg", 

412 "add_context_limit_arg", 

413 "add_quiet_arg", 

414 "add_skip_analysis_arg", 

415 "add_max_issues_arg", 

416 "parse_issue_ids", 

417 "parse_issue_types", 

418 "parse_priorities", 

419 "VALID_ISSUE_TYPES", 

420 "VALID_PRIORITIES", 

421 "add_common_auto_args", 

422 "add_common_parallel_args", 

423]