Defer cfn-lint and Guard initialization until needed

[satyakigh]

Motivation

Previously, the language server initialized the Pyodide-based cfn-lint runtime and mounted every workspace folder during server startup. Guard also loaded its rules before a CloudFormation template needed validation.

This added avoidable startup work and memory usage when users opened a workspace without a CloudFormation template. The existing lifecycle also had several race conditions:

• Failed deferred initialization could subsequently be reported as successful.
• A stale initialization could settle callers while a replacement generation was still pending.
• Guard could reload rules and validate after being disabled during initialization.
• Concurrent first lints could submit duplicate Pyodide mounts for the same workspace.
• Superseded, cancelled, or failed queued lint requests could remain unsettled.

Changes

• Add a shared, generation-aware initializer that defers cfn-lint and Guard until a compatible document is open, shares concurrent initialization, preserves failures, and ignores stale results.
• Initialize cfn-lint and mount workspaces on demand. Concurrent mounts for the same workspace now share one request, propagate failures consistently, and remain retryable.
• Make queued lint requests settle predictably when superseded, cancelled, initialization fails, or the service shuts down.
• Load and reload Guard rules through the deferred lifecycle, preventing stale settings from winning and stopping validation if Guard is disabled during initialization.
• Add document-type tracking and a shared validation trigger to connect deferred initialization to document lifecycle events.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/vitest

The overall coverage in commit 24f3403 in the delay-cfn-lint branch remains at 91%, unchanged from commit af97e1e in the main branch.

Show a code coverage summary of the most impacted files.

File	main af97e1e	delay-cfn-lint 24f3403	+/-
src/telemetry/LoggerFactory.ts	71%	57%	-14%
src/handlers/Do...umentHandler.ts	96%	96%	0%
src/handlers/Initialize.ts	80%	80%	0%
src/document/Do...umentManager.ts	79%	80%	+1%
src/services/cf...nLintService.ts	85%	87%	+2%
src/services/gu...GuardService.ts	78%	81%	+3%
src/document/YamlParser.ts	54%	59%	+5%
src/utils/ValidationUtils.ts	0%	87%	+87%

---

_{Updated August 11, 2026 20:51 UTC}