Coverage for diagrams/code_diagrams/

1"""Targets for :mod:`diagrams.code_diagrams.generate`.

3Each :class:`Target` names a source file and a top-level

4function/method to flowchart. Add new entries here to extend the

5catalogue — the generator and README pick them up automatically.

7Path conventions:

9* ``source`` is relative to the project root (the directory that owns

10 ``cdk.json``).

11* ``function`` is the name as ``pyflowchart`` would resolve it via

12 ``--field``. Use dotted form (``Class.method``) for methods.

13* ``inner`` controls whether to parse the *body* of the function

14 (``True``) or the function definition itself (``False``). Body-level

15 charts read far better for control-flow-heavy functions.

16"""

18from __future__ import annotations

20from dataclasses import dataclass

23@dataclass(frozen=True)

24class Target:

25 """A single function or method to flowchart."""

27 source: str

28 """Path to the source file, relative to project root."""

30 function: str

31 """Name of the function (or ``Class.method``) inside ``source``."""

33 inner: bool = True

34 """If ``True``, chart the body of the function (preferred)."""

36 title: str | None = None

37 """Optional human-readable title for the HTML page and README."""

39 def slug(self) -> str:

40 """File-safe slug for the function component of output names."""

41 return self.function.replace(".", "_")

44# Order matters only for the progress output; README groups by source

45# directory regardless. New targets go at the end of the appropriate

46# section so review diffs stay local.

47TARGETS: list[Target] = [

48 # --- Top-level CDK app entry point -----------------------------------

49 # ``app.py::main`` has real control flow (per-region loop and analytics

50 # gating), so its flowchart is informative. The catalog intentionally

51 # selects externally triggered orchestration and policy boundaries with

52 # branching, retries, fencing, partial failure, or cross-service decisions;

53 # thin wrappers and repetitive adapters stay in close-to-code docs/tests.

54 # Stack constructors are the deliberate exception because they are the

55 # most useful onboarding map from one deployable stack to its helper graph.

56 Target(

57 source="app.py",

58 function="main",

59 title="CDK app entry point (app.py::main)",

60 ),

61 # --- Lambda handlers -------------------------------------------------

62 Target(

63 source="lambda/analytics-presigned-url/handler.py",

64 function="lambda_handler",

65 title="Analytics Presigned-URL Lambda (SageMaker Studio login)",

66 ),

67 Target(

68 source="lambda/analytics-cleanup/handler.py",

69 function="handler",

70 title="Analytics Cleanup Lambda (stack-delete drain)",

71 ),

72 Target(

73 source="lambda/api-gateway-proxy/handler.py",

74 function="lambda_handler",

75 title="API Gateway Proxy Lambda",

76 ),

77 Target(

78 source="lambda/regional-api-proxy/handler.py",

79 function="lambda_handler",

80 title="Regional API Gateway Proxy Lambda",

81 ),

82 Target(

83 source="lambda/cross-region-aggregator/handler.py",

84 function="lambda_handler",

85 title="Cross-Region Aggregator Lambda",

86 ),

87 Target(

88 source="lambda/drift-detection/handler.py",

89 function="lambda_handler",

90 title="CloudFormation Drift Detection Lambda",

91 ),

92 Target(

93 source="lambda/ga-registration/handler.py",

94 function="lambda_handler",

95 title="Global Accelerator Endpoint Registration Lambda",

96 ),

97 Target(

98 source="lambda/helm-installer/handler.py",

99 function="lambda_handler",

100 title="Helm Installer Lambda (CFN custom resource)",

101 ),

102 Target(

103 source="lambda/kubectl-applier-simple/handler.py",

104 function="lambda_handler",

105 title="Kubectl Applier Lambda (CFN custom resource)",

106 ),

107 Target(

108 source="lambda/secret-rotation/handler.py",

109 function="lambda_handler",

110 title="Secrets Manager Rotation Lambda",

111 ),

112 Target(

113 source="lambda/tls-certificate-manager/handler.py",

114 function="lambda_handler",

115 title="Backend TLS Certificate Manager Lambda",

116 ),

117 # --- CLI entry points ------------------------------------------------

118 Target(

119 source="cli/jobs.py",

120 function="JobManager.submit_job",

121 title="gco jobs submit — direct kubectl apply path",

122 ),

123 Target(

124 source="cli/jobs.py",

125 function="JobManager.submit_job_sqs",

126 title="gco jobs submit-sqs — SQS-backed submission path",

127 ),

128 Target(

129 source="cli/analytics_user_mgmt.py",

130 function="srp_authenticate",

131 title="Cognito SRP authentication (gco analytics studio login)",

132 ),

133 Target(

134 source="cli/analytics_user_mgmt.py",

135 function="fetch_studio_url",

136 title="Studio presigned-URL fetch (gco analytics studio login)",

137 ),

138 # --- Additional CLI branchy paths ------------------------------------

139 Target(

140 source="cli/stacks.py",

141 function="StackManager.deploy_orchestrated",

142 title="gco stacks deploy-all — orchestrated multi-stack deploy",

143 ),

144 Target(

145 source="cli/stacks.py",

146 function="StackManager.destroy_orchestrated",

147 title="gco stacks destroy-all — orchestrated multi-stack destroy",

148 ),

149 Target(

150 source="cli/inference.py",

151 function="InferenceManager.deploy",

152 title="gco inference deploy — multi-region endpoint deploy",

153 ),

154 Target(

155 source="cli/inference.py",

156 function="InferenceManager.canary_deploy",

157 title="gco inference canary — weighted canary rollout",

158 ),

159 # --- CDK stack constructors ------------------------------------------

160 # Each ``__init__`` is a mostly-linear wiring sequence (create KMS

161 # key → create VPC → create role → …). We chart them anyway because

162 # they're the single most useful map for readers learning the code:

163 # "given this stack, which helpers run in what order, and what

164 # objects do they produce?".

165 Target(

166 source="gco/stacks/global_stack.py",

167 function="GCOGlobalStack.__init__",

168 title="Global stack constructor (Global Accelerator, SSM, DynamoDB)",

169 ),

170 Target(

171 source="gco/stacks/api_gateway_global_stack.py",

172 function="GCOApiGatewayGlobalStack.__init__",

173 title="API Gateway stack constructor (REST API + IAM + WAF)",

174 ),

175 Target(

176 source="gco/stacks/regional_stack.py",

177 function="GCORegionalStack.__init__",

178 title="Regional stack constructor (VPC, EKS, ALB, SQS, EFS)",

179 ),

180 Target(

181 source="gco/stacks/regional_api_gateway_stack.py",

182 function="GCORegionalApiGatewayStack.__init__",

183 title="Regional API Gateway stack constructor (private access)",

184 ),

185 Target(

186 source="gco/stacks/monitoring_stack.py",

187 function="GCOMonitoringStack.__init__",

188 title="Monitoring stack constructor (CloudWatch + alarms + SNS)",

189 ),

190 Target(

191 source="gco/stacks/analytics_stack.py",

192 function="GCOAnalyticsStack.__init__",

193 title="Analytics stack constructor (KMS, VPC, EFS, Studio, EMR, Cognito)",

194 ),

195 # --- CDK stack helpers with real branches ----------------------------

196 # Most CDK ``__init__`` methods are linear wiring sequences (create

197 # KMS key, create VPC, create role, ...). These helpers are the

198 # exception — they carry real conditional branches tied to

199 # sub-toggles (hyperpod, canvas, fsx, valkey, aurora) and feature

200 # flags, so a flowchart of them is genuinely informative.

201 Target(

202 source="gco/stacks/analytics_stack.py",

203 function="GCOAnalyticsStack._create_execution_role_and_grants",

204 title="Analytics stack SageMaker execution role (hyperpod/canvas branches)",

205 ),

206 Target(

207 source="gco/stacks/analytics_stack.py",

208 function="GCOAnalyticsStack._create_studio_domain",

209 title="Analytics stack Studio domain (Canvas override branch)",

210 ),

211 # --- Runtime service security and reconciliation paths ---------------

212 Target(

213 source="gco/services/auth_middleware.py",

214 function="AuthenticationMiddleware.dispatch",

215 title="Backend authentication gate (health bypass, HMAC validation, fail-closed paths)",

216 ),

217 Target(

218 source="lambda/proxy-shared/proxy_utils.py",

219 function="build_signed_headers",

220 title="Proxy request-bound HMAC envelope construction",

221 ),

222 Target(

223 source="lambda/tls-shared/backend_tls.py",

224 function="get_backend_http_pool",

225 title="Private-root backend TLS trust refresh and verified connection pool",

226 ),

227 Target(

228 source="gco/services/manifest_api.py",

229 function="lifespan",

230 title="Manifest API lifecycle (stores + optional central queue worker)",

231 ),

232 Target(

233 source="gco/services/central_queue_worker.py",

234 function="process_queued_jobs_once",

235 title="Central queue activation pass (migration, fenced claim, heartbeat, deterministic apply)",

236 ),

237 Target(

238 source="gco/services/central_queue_worker.py",

239 function="reconcile_active_jobs_once",

240 title="Central queue status reconciliation (Kubernetes UID fencing + terminal transitions)",

241 ),

242 Target(

243 source="gco/services/template_store.py",

244 function="JobStore.claim_job",

245 title="Global queue fenced claim (conditional write + monotonic generation)",

246 ),

247 Target(

248 source="gco/services/template_store.py",

249 function="JobStore.transition_job",

250 title="Global queue lifecycle transition (lease, status, and Kubernetes UID fencing)",

251 ),

252 Target(

253 source="gco/services/manifest_processor.py",

254 function="ManifestProcessor.apply_queued_job",

255 title="Deterministic queued Job create-or-adopt path",

256 ),

257 Target(

258 source="gco/services/api_routes/inference_proxy.py",

259 function="_resolve_upstream",

260 title="Authenticated inference target resolution (region, readiness, namespace, canary)",

261 ),

262 Target(

263 source="gco/services/api_routes/inference_proxy.py",

264 function="_proxy",

265 title="Managed inference reverse proxy (path allowlist, bounded I/O, streaming cleanup)",

266 ),

267 Target(

268 source="gco/services/inference_monitor.py",

269 function="InferenceMonitor._reconcile_endpoint_authorized",

270 title="Inference endpoint authorized desired-state reconciliation",

271 ),

272 Target(

273 source="lambda/helm-installer/teardown_provider.py",

274 function="on_event",

275 title="Helm teardown provider event path (install drain + idempotent execution start)",

276 ),

277 Target(

278 source="lambda/helm-installer/teardown_provider.py",

279 function="is_complete",

280 title="Helm teardown completion poll (continued fencing + terminal status)",

281 ),

282 # --- MCP server branchy modules --------------------------------------

283 # New code-diagram targets for the branchy MCP modules introduced by

284 # this work. Each one carries real control flow tied to feature

285 # flags, FastMCP Tasks cancellation, image-registry replication,

286 # or audit-log enrichment.

287 Target(

288 source="cli/_container_runtime.py",

289 function="detect_container_runtime",

290 title="Container runtime detection (docker > finch > podman)",

291 ),

292 Target(

293 source="cli/images.py",

294 function="ImageManager.build",

295 title="gco images build — context validation, login, build, push",

296 ),

297 Target(

298 source="cli/images.py",

299 function="ImageManager.push",

300 title="gco images push — auth + push existing local image",

301 ),

302 Target(

303 source="cli/images.py",

304 function="ImageManager.cleanup",

305 title="gco images cleanup — bulk tag delete with filter branches",

306 ),

307 Target(

308 source="gco_mcp/audit.py",

309 function="audit_logged",

310 title="MCP audit_logged decorator (sync + async dispatch, Context capture)",

311 ),

312 Target(

313 source="gco_mcp/tools/_long_task.py",

314 function="_run_long_task",

315 title="MCP long-task runner (drain, progress, cancel + SIGTERM/SIGKILL)",

316 ),

317 Target(

318 source="lambda/image-lookup/handler.py",

319 function="lambda_handler",

320 title="Image-lookup-or-create custom resource Lambda",

321 ),

322 # --- Mission goal-directed iteration loop ----------------------------

323 Target(

324 source="gco_mcp/mission/engine.py",

325 function="MissionEngine.run_iteration",

326 title="Mission iteration loop (propose -> execute -> observe -> evaluate -> decide)",

327 ),

328 Target(

329 source="gco_mcp/mission/decide.py",

330 function="decide_verdict",

331 title="Mission verdict cascade (budget caps, completion, cadence-skip, heuristic)",

332 ),

333 Target(

334 source="gco_mcp/mission/sampling.py",

335 function="maybe_sample_strategy_revision",

336 title="Mission strategy-revision sampling (orchestrator + deterministic fallback)",

337 ),

338 Target(

339 source="gco_mcp/mission/sandbox.py",

340 function="validate_script_ast",

341 title="Mission script AST validator (parse-time allowlist enforcement)",

342 ),

343 Target(

344 source="gco_mcp/mission/criteria_scaffold.py",

345 function="generate_sampled_criteria",

346 title="Mission criteria scaffolder (Bedrock sampling + retry + autofix pipeline)",

347 ),

348 Target(

349 source="gco_mcp/mission/_engine_factory.py",

350 function="build_engine_dependencies",

351 title="Mission engine factory (live vs stub dispatcher, sampling, sandbox wiring)",

352 ),

353 # --- project_name / ECR image-namespace scoping (#139) ---------------

354 # These paths make every ECR image namespace derive from

355 # ``project_name`` so multiple GCO deployments can co-exist in one

356 # account/region without colliding. Each carries real control flow

357 # (enable toggles, project-prefix + regex validation, per-region

358 # mirror loop, replication-rule guards), so a flowchart is genuinely

359 # informative for readers auditing the multi-deployment story.

360 Target(

361 source="cli/_image_mirror.py",

362 function="read_mirror_config",

363 title="Volcano image-mirror config read (project-scoped ECR namespace default, #139)",

364 ),

365 Target(

366 source="cli/_image_mirror.py",

367 function="mirror_images",

368 title="Image mirror into project-scoped ECR (plan, strategy, auth, per-image copy, #139)",

369 ),

370 Target(

371 source="cli/stacks.py",

372 function="StackManager._mirror_images_if_enabled",

373 title="gco stacks deploy — pre-deploy image mirror gate (regional-only, #139)",

374 ),

375 Target(

376 source="gco/stacks/regional_stack.py",

377 function="GCORegionalStack._get_volcano_image_mirror_config",

378 title="Regional volcano image-mirror config (project-prefix + ECR-path validation, #139)",

379 ),

380 Target(

381 source="gco/stacks/global_stack.py",

382 function="GCOGlobalStack._create_image_replication_rule",

383 title="Global ECR replication rule (project-scoped PREFIX_MATCH filter, #139)",

384 ),

385 # --- 6.0: trainer, MLflow, vector store (#252) ------------------------

386 # The validation pipeline gained a workload kind without a single pod

387 # spec (TrainJob decomposes into weighted views), the helm installer

388 # now converges two more charts, and the CLI job lifecycle grew

389 # TrainJob-aware fallback chains. Each target below carries the real

390 # branch structure a reader needs to audit those flows.

391 Target(

392 source="gco/services/queue_processor.py",

393 function="validate_manifest",

394 title="SQS job prevalidation (kinds, TrainJob decomposition, security, weighted caps)",

395 ),

396 Target(

397 source="gco/services/manifest_processor.py",

398 function="ManifestProcessor.validate_manifest",

399 title="REST manifest validation pipeline (structure, kinds, limits, tolerations, images)",

400 ),

401 Target(

402 source="lambda/helm-installer/handler.py",

403 function="handle_task",

404 title="Helm convergence per-chart decision (EnabledCharts authority: install vs uninstall)",

405 ),

406 Target(

407 source="lambda/helm-installer/handler.py",

408 function="validate_releases",

409 title="Helm release-set validation (charts.yaml expected set, deployed vs absent)",

410 ),

411 Target(

412 source="cli/jobs.py",

413 function="JobManager.get_job_logs",

414 title="gco jobs logs — TrainJob rank resolution and CloudWatch fallback chain",

415 ),

416 Target(

417 source="lambda/vector-ingest/handler.py",

418 function="lambda_handler",

419 title="Vector-store corpus ingest (S3 notification -> chunk, embed, write items)",

420 ),

421 # --- pre-v7 high-value orchestration and policy boundaries -----------

422 Target(

423 source="lambda/capacity-poller/handler.py",

424 function="lambda_handler",

425 title="Capacity snapshot poller (Region truth, pooled scores, bounded retries, writes)",

426 ),

427 Target(

428 source="lambda/helm-orchestrator/handler.py",

429 function="on_event",

430 title="Helm convergence orchestrator (start/adopt, replay identity, rollback fencing)",

431 ),

432 Target(

433 source="lambda/traffic-dial-controller/handler.py",

434 function="lambda_handler",

435 title="Traffic dial controller (health evidence, step limits, last-Region safety)",

436 ),

437 Target(

438 source="gco/services/spot_price_gate.py",

439 function="SpotPriceGate.evaluate",

440 title="Spot price gate (unknown/malformed/above-cap dispatch policy)",

441 ),

442 Target(

443 source="cli/commands/autopilot_cmd.py",

444 function="_plan",

445 title="Autopilot launch planner (engine, model, MCP, imports, resume)",

446 ),

447 Target(

448 source="gco_mcp/mission/swarm_runner.py",

449 function="SwarmRunner.run_to_completion",

450 title="Swarm runner lifecycle (fleet guard, respawn, settlement, cascade shutdown)",

451 ),

452 Target(

453 source="gco/services/request_size_middleware.py",

454 function="RequestSizeLimitMiddleware.__call__",

455 title="Request-size trust boundary (declared/streamed limits and exact replay)",

456 ),

457 Target(

458 source="gco/services/webhook_dispatcher.py",

459 function="WebhookDispatcher._deliver_webhook",

460 title="Webhook delivery boundary (DNS pinning, HMAC, retries, redacted accounting)",

461 ),

462 Target(

463 source="gco/services/mooncake_pd_proxy.py",

464 function="_dispatch",

465 title="Mooncake prefill/decode dispatch (admin gate, KV handoff, streaming decode)",

466 ),

467 Target(

468 source="gco/services/health_monitor.py",

469 function="HealthMonitor.get_health_status",

470 title="Health status policy (thresholds, violations, collection failure)",

471 ),

472]

Coverage for diagrams / code_diagrams / _targets.py: 100.00%

15 statements