# caseycs/vscode-terragrunt-navigator architecture

> Architecture diagram of the GitHub repository caseycs/vscode-terragrunt-navigator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caseycs/vscode-terragrunt-navigator
- Repository: https://github.com/caseycs/vscode-terragrunt-navigator

## Overview

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: [`src/resolvers/referenceResolver.ts`](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/referenceResolver.ts) (Reference Resolver), [`test/unit/referenceResolver.test.ts`](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/test/unit/referenceResolver.test.ts) (Unit Tests), [`src/providers/definitionProvider.ts`](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/providers/definitionProvider.ts) (Definition), [`src/parsers/sourceParser.ts`](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/parsers/sourceParser.ts) (Source Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "VS Code layer"
  src_extension["Extension<br/>activation<br/>[extension.ts]"]
  src_definition_provider["Definition<br/>provider"]
  src_document_link_provider["Document Links<br/>provider"]
end

subgraph "Parsing layer"
  src_source_parser["Source Parser<br/>[sourceParser.ts]"]
end

subgraph "Resolution layer"
  src_reference_resolver["Reference Resolver<br/>orchestrator"]
  src_path_resolver["Path Resolver<br/>[pathResolver.ts]"]
  src_parent_finder["Parent Finder<br/>resolver<br/>[parentFinder.ts]"]
  src_target_finder["Target Finder<br/>resolver<br/>[targetFinder.ts]"]
  src_renderer["Terragrunt Renderer<br/>cli bridge"]
  src_render_cache[("Render Cache<br/>[renderCache.ts]")]
  src_background_resolver["Background Resolve<br/>precompute"]
  src_constants["Constants<br/>shared config<br/>[constants.ts]"]
  src_types["Types<br/>[types.ts]"]
end

subgraph "Tooling"
  package_json["Package<br/>manifest<br/>[package.json]"]
  esbuild_js["Build<br/>bundler<br/>[esbuild.js]"]
  test_unit["Unit Tests"]
  test_integration["Integration Tests"]
  fixtures["Fixtures<br/>test data<br/>[terragrunt.hcl]"]
end

src_extension -->|"registers"| src_definition_provider
src_extension -->|"registers"| src_document_link_provider
src_definition_provider -->|"classifies"| src_source_parser
src_document_link_provider -->|"classifies"| src_source_parser
src_definition_provider -->|"resolves"| src_reference_resolver
src_reference_resolver -->|"normalizes"| src_path_resolver
src_reference_resolver -->|"searches"| src_parent_finder
src_reference_resolver -->|"renders"| src_renderer
src_renderer -->|"stores"| src_render_cache
src_background_resolver -->|"warms"| src_render_cache
src_reference_resolver -->|"targets"| src_target_finder
src_target_finder -->|"uses"| src_constants
src_source_parser -->|"emits"| src_types
src_reference_resolver -->|"returns"| src_types
src_extension -->|"optionally starts"| src_background_resolver
test_unit -->|"covers"| src_source_parser
test_unit -->|"covers"| src_reference_resolver
test_unit -->|"covers"| src_render_cache
test_integration -->|"covers"| src_definition_provider
test_integration -->|"covers"| src_document_link_provider
fixtures -->|"drives"| test_unit
fixtures -->|"drives"| test_integration
package_json -->|"builds"| esbuild_js

click src_extension "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/extension.ts"
click src_definition_provider "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/providers/definitionProvider.ts"
click src_document_link_provider "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/providers/documentLinkProvider.ts"
click src_source_parser "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/parsers/sourceParser.ts"
click src_reference_resolver "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/referenceResolver.ts"
click src_path_resolver "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/pathResolver.ts"
click src_parent_finder "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/parentFinder.ts"
click src_target_finder "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/targetFinder.ts"
click src_renderer "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/terragruntRenderer.ts"
click src_render_cache "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/renderCache.ts"
click src_background_resolver "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/resolvers/backgroundResolver.ts"
click src_constants "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/constants.ts"
click src_types "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/src/types.ts"
click package_json "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/package.json"
click esbuild_js "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/esbuild.js"
click test_unit "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/test/unit/referenceResolver.test.ts"
click test_integration "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/test/integration/definitionProvider.test.ts"
click fixtures "https://github.com/caseycs/vscode-terragrunt-navigator/blob/main/test/fixtures/simple/terragrunt.hcl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class src_extension,src_definition_provider,src_document_link_provider toneBlue
class src_source_parser toneAmber
class src_reference_resolver,src_path_resolver,src_parent_finder,src_target_finder,src_renderer,src_render_cache,src_background_resolver,src_constants,src_types toneMint
class package_json,esbuild_js,test_unit,test_integration,fixtures toneRose
```

## Components

### VS Code layer

Extension activation and editor-facing providers.

- [Extension](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/extension.ts): activation · Registers VS Code features and wires the extension together. · `src/extension.ts`
- [Definition](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/providers/definitionProvider.ts): provider · Go to Definition integration for Terragrunt navigation. · `src/providers/definitionProvider.ts`
- [Document Links](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/providers/documentLinkProvider.ts): provider · Detects clickable links in Terragrunt documents. · `src/providers/documentLinkProvider.ts`

### Parsing layer

Classifies Terragrunt references before resolution.

- [Source Parser](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/parsers/sourceParser.ts): parser · Classifies HCL tokens and identifies navigable Terragrunt references. · `src/parsers/sourceParser.ts`

### Resolution layer

Turns parsed references into concrete navigation targets.

- [Reference Resolver](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/referenceResolver.ts): orchestrator · Coordinates parsing, path logic, and dynamic resolution strategy. · `src/resolvers/referenceResolver.ts`
- [Path Resolver](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/pathResolver.ts): resolver · Normalizes Terragrunt paths and repo-root-based references. · `src/resolvers/pathResolver.ts`
- [Parent Finder](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/parentFinder.ts): resolver · Implements find_in_parent_folders upward search semantics. · `src/resolvers/parentFinder.ts`
- [Target Finder](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/targetFinder.ts): resolver · Chooses the final file to open for a resolved reference. · `src/resolvers/targetFinder.ts`
- [Terragrunt Renderer](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/terragruntRenderer.ts): cli bridge · Runs terragrunt render --json for dynamic interpolations. · `src/resolvers/terragruntRenderer.ts`
- [Render Cache](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/renderCache.ts): cache · Caches render outputs and invalidates them by content hash. · `src/resolvers/renderCache.ts`
- [Background Resolve](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/resolvers/backgroundResolver.ts): precompute · Pre-resolves dynamic targets when files are opened. · `src/resolvers/backgroundResolver.ts`
- [Constants](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/constants.ts): shared config · Shared extension identifiers, defaults, and string constants. · `src/constants.ts`
- [Types](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/src/types.ts): shared types · Central TypeScript types for parsed references and results. · `src/types.ts`

### Tooling

Build, tests, and repository support files.

- [Package](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/package.json): manifest · Extension metadata, scripts, and dependency declarations. · `package.json`
- [Build](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/esbuild.js): bundler · Build and packaging configuration for the extension. · `esbuild.js`
- [Unit Tests](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/test/unit/referenceResolver.test.ts): tests · Validates parser, resolver, cache, and renderer behavior. · `test/unit/referenceResolver.test.ts`
- [Integration Tests](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/test/integration/definitionProvider.test.ts): tests · Exercises VS Code-facing providers in an extension-like environment. · `test/integration/definitionProvider.test.ts`
- [Fixtures](https://github.com/caseycs/vscode-terragrunt-navigator/blob/HEAD/test/fixtures/simple/terragrunt.hcl): test data · Terragrunt scenarios used to verify navigation rules. · `test/fixtures/simple/terragrunt.hcl`

## Connections

- 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.
