How caseycs/vscode-terragrunt-navigator works
Terragrunt Navigator is a TypeScript-based VS Code extension. Its architecture is centered on turning Terragrunt HCL references into clickable navigation targets inside the editor.
At a high level, the system has four main layers:
1. VS Code integration layer
2. Parsing and classification layer
3. Resolution layer
4. Caching/background pre-resolution layer
1) VS Code integration layer
This is the extension entry point in src/extension.ts. It wires the extension into the VS Code runtime and registers the language features that drive navigation.
Main responsibilities
• Activate the extension when Terragrunt files are opened or when a relevant command/path lookup is needed.
• Register providers for:
- definition/navigation behavior
- document links
• Respect user settings such as:
- render timeout
- whether background resolution is enabled
Boundary
This layer is the only part directly coupled to the VS Code API. It receives editor events and document context, then delegates all Terragrunt-specific logic to the resolver and parser subsystems.
2) Parsing and classification layer
The parsing layer is in src/parsers/sourceParser.ts.
Main responsibilities
• Inspect HCL lines and determine whether a token is a Terragrunt target worth navigating to.
• Identify supported constructs such as:
- terraform { source = ... }
- dependency { config_path = ... }
- find_in_parent_folders("...")
• Ignore commented-out content.
• Distinguish between static paths, relative paths, dynamic interpolations, and remote sources.
Why this layer exists
The extension does not treat every string as a path. It first classifies the text so the downstream resolvers know:
• whether this is a source reference or dependency config path
• whether it is resolvable locally without running Terragrunt
• whether it requires Terragrunt rendering to evaluate interpolations
Boundary
This layer is purely syntactic/semantic classification. It does not touch the filesystem or run external commands.
3) Resolution layer
This is the core of the architecture. It is split into several focused resolvers under src/resolvers/.
a) Path resolution
src/resolvers/pathResolver.ts
Handles turning a Terragrunt expression into an actual filesystem path. This includes:
• resolving ${get_repo_root()}
• handling Terragrunt’s // path convention
• converting relative references into canonical paths
• normalizing source paths to the expected target file, often main.tf
• resolving dependency destinations to terragrunt.hcl
This is the central “path interpretation” component.
b) Parent search
src/resolvers/parentFinder.ts
Implements the behavior of find_in_parent_folders("filename"):
• start from the current file/directory
• walk upward through parent directories
• return the first matching file
This resolver encodes Terragrunt’s parent lookup semantics.
c) Reference resolution
src/resolvers/referenceResolver.ts
Coordinates resolution of a source reference from the parsed document context. This is likely the orchestration layer that combines:
• parse result
• path resolution
• parent lookup
• dynamic rendering when required
It sits above the narrower resolvers and decides the overall strategy for a clicked token.
d) Target finding
src/resolvers/targetFinder.ts
Determines the final file that should be opened once a reference is resolved. Based on the README and fixture structure, this includes rules like:
• source module paths map to main.tf
• dependency config paths map to terragrunt.hcl
• parent-file search returns the located file itself
e) Terragrunt rendering
src/resolvers/terragruntRenderer.ts
Handles the external Terragrunt CLI integration:
• runs terragrunt render --json
• resolves dynamic interpolations such as ${local.*}
• provides the fully evaluated output used for navigation
This is the main integration point with an external executable.
f) Render result caching
src/resolvers/renderCache.ts
Caches outputs from terragrunt render --json and invalidates them using a hash-based mechanism. This is important because rendering is expensive and may involve CLI process startup. The cache makes repeated clicks and background resolution fast.
g) Background pre-resolution
src/resolvers/backgroundResolver.ts
Pre-computes dynamic resolutions when a file is opened, if the user enables background resolution. This allows the extension to answer click/navigation requests with minimal latency later.
Boundary
The resolver layer is responsible for file system access, path normalization, parent traversal, and subprocess execution. It is deliberately separated from the VS Code API so the core logic can be tested independently.
4) Provider layer
The provider layer in src/providers/ adapts the resolution logic to VS Code features.
a) Definition provider
src/providers/definitionProvider.ts
This is the primary implementation for Ctrl+Click / “Go to Definition” style behavior.
Typical flow:
• receive cursor position and document
• ask the parser whether the token is relevant
• resolve the target through the resolver stack
• return a location that VS Code can open
This is the user-facing navigation path.
b) Document link provider
src/providers/documentLinkProvider.ts
Provides link detection inside Terragrunt files. This enables URLs or file-like references to be treated as clickable document links, complementing definition navigation.
Boundary
These providers are presentation adapters. They do not implement Terragrunt semantics directly; they translate resolved targets into VS Code-native navigation primitives.
End-to-end data flow
A typical navigation request flows like this:
1. User opens or clicks inside a Terragrunt HCL file in VS Code.
2. The provider receives the document position.
3. The source parser inspects the relevant line/token and determines the reference type.
4. The resolver layer decides how to interpret it:
- static path
- repo-root-based path
- parent-folder search
- dynamic interpolated path
5. If the path is dynamic, terragrunt render --json is executed.
6. Render results are cached and reused.
7. The target finder determines the exact file to open.
8. VS Code opens that file or shows the navigation target.
Important architectural boundaries
VS Code API vs domain logic
The extension keeps VS Code-specific code in the providers and activation module, while Terragrunt semantics live in parser/resolver modules.
Static resolution vs dynamic resolution
Static paths can be resolved directly from file contents and filesystem rules. Dynamic interpolations require Terragrunt CLI rendering. This is a major architectural split because dynamic resolution depends on an external process and cache.
Local filesystem vs remote references
Remote source URLs such as git::, s3::, and https:// are explicitly skipped. The architecture focuses on local navigation targets only.
Precomputation vs on-demand resolution
Background resolution preloads likely dynamic results, but the system still supports on-demand evaluation when the user clicks.
Supporting code and shared types
• src/constants.ts likely holds extension identifiers, defaults, and shared string constants.
• src/types.ts centralizes TypeScript types for parsed references, resolution results, and configuration.
These modules reduce coupling across the parser, resolvers, and providers.
Tests and fixtures
The test suite is a significant part of the repository structure and reflects the architecture well.
Unit tests
Located under test/unit, they cover:
• source parsing
• path resolution
• target finding
• background resolution
• Terragrunt rendering
• render caching
• reference resolution
These tests validate the resolver pipeline independently of VS Code.
Integration tests
Located under test/integration, they validate the providers in a VS Code-like environment:
• definition provider behavior
• document link provider behavior
Fixtures
The fixture tree under test/fixtures captures real Terragrunt patterns:
• simple module source paths
• nested repo structures
• missing main.tf cases
• dependency graphs
• dynamic path interpolation
• parent-file search scenarios
These fixtures are effectively executable documentation for the navigation rules.
Tooling and operational context
• Runtime: Node.js / TypeScript
• Packaging/build: esbuild.js
• Testing: Mocha-based test setup (.mocharc.yml, test/runTests.ts)
• Distribution target: VS Code extension marketplace
• CI: GitHub Actions workflows for continuous integration and automated tagging
Architectural summary
This repository is a navigation engine for Terragrunt HCL inside VS Code. The system is intentionally layered:
• Providers adapt VS Code events into requests
• Parsers classify Terragrunt expressions
• Resolvers turn expressions into concrete files
• Terragrunt CLI is used only when static resolution is insufficient
• Caching and background work reduce latency
• Tests validate both the pure resolution logic and the VS Code-facing integration
For an architecture diagram, the most important arrows are:
• VS Code editor event → provider
• provider → parser
• parser → resolver chain
• resolver chain → filesystem / Terragrunt CLI
• Terragrunt CLI → render cache → resolver
• resolver → VS Code navigation target
Main entry points: referenceResolver.ts Reference Resolver · referenceResolver.test.ts Unit Tests · definitionProvider.ts Definition · sourceParser.ts Source Parser
Components 18
VS Code layer
Extension activation and editor-facing providers.
- Extension · Registers VS Code features and wires the extension together.
src/extension.ts - Definition · Go to Definition integration for Terragrunt navigation.
src/providers/definitionProvider.ts - Document Links · Detects clickable links in Terragrunt documents.
src/providers/documentLinkProvider.ts
Parsing layer
Classifies Terragrunt references before resolution.
- Source Parser · Classifies HCL tokens and identifies navigable Terragrunt references.
src/parsers/sourceParser.ts
Resolution layer
Turns parsed references into concrete navigation targets.
- Reference Resolver · Coordinates parsing, path logic, and dynamic resolution strategy.
src/resolvers/referenceResolver.ts - Path Resolver · Normalizes Terragrunt paths and repo-root-based references.
src/resolvers/pathResolver.ts - Parent Finder · Implements find_in_parent_folders upward search semantics.
src/resolvers/parentFinder.ts - Target Finder · Chooses the final file to open for a resolved reference.
src/resolvers/targetFinder.ts - Terragrunt Renderer · Runs terragrunt render --json for dynamic interpolations.
src/resolvers/terragruntRenderer.ts - Render Cache · Caches render outputs and invalidates them by content hash.
src/resolvers/renderCache.ts - Background Resolve · Pre-resolves dynamic targets when files are opened.
src/resolvers/backgroundResolver.ts - Constants · Shared extension identifiers, defaults, and string constants.
src/constants.ts - Types · Central TypeScript types for parsed references and results.
src/types.ts
Tooling
Build, tests, and repository support files.
- Package · Extension metadata, scripts, and dependency declarations.
package.json - Build · Build and packaging configuration for the extension.
esbuild.js - Unit Tests · Validates parser, resolver, cache, and renderer behavior.
test/unit/referenceResolver.test.ts - Integration Tests · Exercises VS Code-facing providers in an extension-like environment.
test/integration/definitionProvider.test.ts - Fixtures · Terragrunt scenarios used to verify navigation rules.
test/fixtures/simple/terragrunt.hcl
Connections 23
- Extension → Definition: registers · Extension activates and registers definition navigation.
- Extension → Document Links: registers · Extension activates and registers document link handling.
- Definition → Source Parser: classifies · Provider asks parser whether the clicked token is relevant.
- Document Links → Source Parser: classifies · Document links are derived from parsed Terragrunt text.
- Definition → Reference Resolver: resolves · Definition requests flow into the resolver stack.
- Reference Resolver → Path Resolver: normalizes · Resolver delegates path interpretation and canonicalization.
- Reference Resolver → Parent Finder: searches · Resolver uses parent lookup for find_in_parent_folders.
- Reference Resolver → Terragrunt Renderer: renders · Dynamic references are evaluated through the Terragrunt CLI.
- Terragrunt Renderer → Render Cache: stores · Rendered JSON results are cached for reuse.
- Background Resolve → Render Cache: warms · Background pre-resolution populates the render cache.
- Reference Resolver → Target Finder: targets · Resolved references are mapped to the final file to open.
- Target Finder → Constants: uses · Target rules rely on shared naming and defaults.
- Source Parser → Types: emits · Parser produces typed reference classifications.
- Reference Resolver → Types: returns · Resolver produces typed resolution results.
- Extension → Background Resolve: optionally starts · Background resolution is enabled from extension settings.
- Unit Tests → Source Parser: covers · Unit tests exercise parsing behavior.
- Unit Tests → Reference Resolver: covers · Unit tests exercise orchestration and resolution.
- Unit Tests → Render Cache: covers · Unit tests validate cache behavior.
- Integration Tests → Definition: covers · Integration tests validate go-to-definition behavior.
- Integration Tests → Document Links: covers · Integration tests validate clickable link behavior.
- Fixtures → Unit Tests: drives · Fixture scenarios support resolver-focused tests.
- Fixtures → Integration Tests: drives · Fixture scenarios support VS Code-facing integration tests.
- Package → Build: builds · Package scripts invoke the build pipeline.