Support for Terraform Search (.tfquery.hcl) files (#2007)

* feat(tfsearch): TF-26847 TF-27074: Added: init search feature

* feat(tfsearch): TF-26847 TF-27074: Modified: renamed file name

* feat(tfsearch): TF-26847 TF-27288: Added: dynamic schema for provider block

* Update metadata to update provider references correctly.

This reverts commit 21a998a.

* feat(tfsearch): TF-26847: Modified: terraform-json version to  pseudo-version

* feat(tfsearch): TF-26847: Modified: terraform-schema version to  pseudo-version

* feat(tfsearch): TF-26847: Added: changelog

* feat(tfsearch): TF-26847: Modified: terrform-schema version

* feat(tfsearch): TF-26847: Modified: terrform-schema version

* feat(tfsearch): TF-26847: Modified: added terraform version in meta

* feat(tfsearch): TF-26847: Modified: removed unused code

* feat(tfsearch): TF-26847: Modified: added test cases

* feat(tfsearch): TF-26847: Refactored: removed unused code

* feature/tfsearch-TF-26847: fix: Remove Deploy checks from search config

* feat(tfsearch): TF-26847 TF-27270: Modified: docs md files

* feat(tfsearch): TF-26847: Bumped: terraform-json

* feat(tfsearch): TF-26847: Bumped: terraform-schema

* feat(tfsearch): TF-26847: Fixed: typo in tfstack file regex

Co-authored-by: James Pogran <[email protected]>

* feat(tfsearch): TF-26847: Added: ReferenceValidation

* feat(tfsearch): TF-26847: Added: MissingRequiredAttribute

* feat(tfsearch): TF-26847: Refactored: renamed function name

* feat(tfsearch): TF-26847: Bumped: terraform-schema version

* feat(tfsearch): TF-26847: Fixed: test case

* feat(tfsearch): TF-26847: Modified: removed corerequirements and providerrequirements from search meta

* feat(tfsearch): TF-26847: Bumped: terraform-schema

* feat(tfsearch): TF-26847: Bumped: terraform-schema

---------

Co-authored-by: sunnyhashi <[email protected]>
Co-authored-by: James Pogran <[email protected]>

Author: 3 people

.changes/unreleased/ENHANCEMENTS-20250806-104456.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: Add support for Terraform Search files. This provides block and attribute completion, hover, and diagnostics along with syntax validation for Terraform Search files.
+time: 2025-08-06T10:44:56.893693+05:30
+custom:
+    Issue: "2007"
+    Repository: terraform-ls

docs/USAGE.md

@@ -10,6 +10,7 @@ The following filetypes are supported by the Terraform Language Server:
 - `terraform-vars` - variable files (`*.tfvars`)
 - `terraform-stack` - standard `*.tfcomponent.hcl` and `*.tfstack.hcl` files
 - `terraform-deploy` - standard `*.tfdeploy.hcl` files
+- `terraform-search` - standard `*.tfquery.hcl` files
 
 _NOTE:_ Clients should be configured to follow the above language ID conventions
 and do **not** send `*.tf.json`, `*.tfvars.json` nor Packer HCL config

docs/architecture.md

@@ -60,6 +60,7 @@ We currently have several features:
 - `*.tfvars` and `*.tfvars.json` files are handled in the `variables` feature
 - `.terraform/` and `.terraform.lock.hcl` related operations are handled in the `rootmodules` feature
 - `*.tfcomponent.hcl`, `*.tfstack.hcl` and `*.tfdeploy.hcl` files are handled in the `stacks` feature
+- `*.tfquery.hcl` files are handled in the `search` feature
 
 A feature can provide data to the external consumers through methods. For example, the `variables` feature needs a list of variables from the `modules` feature. There should be no direct import from feature packages (we could enforce this by using `internal/`, but we won't for now) into other parts of the codebase. The "hot path" service mentioned above takes care of initializing each feature at the start of a new LS session.
 
@@ -93,13 +94,23 @@ The `jobs` package of each feature contains all the different indexing jobs need
 ### Stack Feature Jobs
 
 - `ParseStackConfiguration` - parses `*.tfcomponent.hcl`, `*.tfstack.hcl` and `*.tfdeploy.hcl` files to turn `[]byte` into `hcl` types (AST)
-- `LoadStackMetadata` - uses [`earlydecoder`](https://pkg.go.dev/github.com/hashicorp/terraform-schema@main/stacks/earlydecoder) to do early TF version-agnostic decoding to obtain metadata (variables, outputs etc.) which can be used to do more detailed decoding in hot-path within `hcl-lang` decoder
+- `LoadStackMetadata` - uses [`earlydecoder`](https://pkg.go.dev/github.com/hashicorp/terraform-schema@main/earlydecoder/stacks) to do early TF version-agnostic decoding to obtain metadata (variables, outputs etc.) which can be used to do more detailed decoding in hot-path within `hcl-lang` decoder
 - `PreloadEmbeddedSchema` – loads provider schemas based on provider requirements from the bundled schemas
 - `DecodeReferenceTargets` - uses `hcl-lang` decoder to collect reference targets within `*.tfcomponent.hcl`, `*.tfstack.hcl` and `*.tfdeploy.hcl`
 - `DecodeReferenceOrigins` - uses `hcl-lang` decoder to collect reference origins within `*.tfcomponent.hcl`, `*.tfstack.hcl` and `*.tfdeploy.hcl`
 - `SchemaStackValidation` - does schema-based validation of module files (`*.tfcomponent.hcl`, `*.tfstack.hcl` and `*.tfdeploy.hcl`) and produces diagnostics associated with any "invalid" parts of code
 - `ReferenceValidation` - does validation based on (mis)matched reference origins and targets, to flag up "orphaned" references
 
+### Search Feature Jobs
+
+- `ParseSearchConfiguration` - parses `*.tfquery.hcl` files to turn `[]byte` into `hcl` types (AST)
+- `LoadSearchMetadata` - uses [`earlydecoder`](https://pkg.go.dev/github.com/hashicorp/terraform-schema@main/earlydecoder/search) to do early TF version-agnostic decoding to obtain metadata (variables, outputs etc.) which can be used to do more detailed decoding in hot-path within `hcl-lang` decoder
+- `PreloadEmbeddedSchema` – loads provider schemas based on provider requirements from the bundled schemas
+- `DecodeReferenceTargets` - uses `hcl-lang` decoder to collect reference targets within `*.tfquery.hcl`
+- `DecodeReferenceOrigins` - uses `hcl-lang` decoder to collect reference origins within `*.tfquery.hcl`
+- `SchemaSearchValidation` - does schema-based validation of module files (`*.hcl.hcl`) and produces diagnostics associated with any "invalid" parts of code
+- `ReferenceValidation` - does validation based on (mis)matched reference origins and targets, to flag up "orphaned" references
+
 ### Adding a new feature / "language"
 
 The existing `variables` feature is a good starting point when introducing a new language. Usually you need to roughly follow these steps to get a minimal working example:

docs/language-clients.md

@@ -10,6 +10,7 @@ The following file types are currently supported and language IDs expected:
 - `terraform-vars` - variable files (`*.tfvars`)
 - `terraform-stack` - standard `*.tfcomponent.hcl` and `*.tfstack.hcl` files
 - `terraform-deploy` - standard `*.tfdeploy.hcl` files
+- `terraform-search` - standard `*.tfquery.hcl` files
 
 Client can choose to highlight other files locally, but such other files
 must **not** be send to the server as the server isn't equipped to handle those.
@@ -46,7 +47,7 @@ This allows IntelliSense to remain accurate e.g. when switching branches in VCS
 or when there are any other changes made to these files outside the editor.
 
 If the client implements file watcher, it should watch for any changes
-in `**/*.tf`, `**/*.tfvars`, `*.tfstack.hcl`, `**/*.tfstack.hcl` and `**/*.tfstack.hcl` files in the workspace.
+in `**/*.tf`, `**/*.tfvars`, `**/*.tfstack.hcl`, `**/*.tfcomponent.hcl`, `**/*.tfdeploy.hcl` and `**/*.tfquery.hcl` files in the workspace.
 
 Client should **not** send changes for any other files.
 

go.mod

@@ -19,7 +19,7 @@ require (
 	github.com/hashicorp/terraform-exec v0.23.0
 	github.com/hashicorp/terraform-json v0.26.0
 	github.com/hashicorp/terraform-registry-address v0.3.0
-	github.com/hashicorp/terraform-schema v0.0.0-20250616115602-34f2164294a0
+	github.com/hashicorp/terraform-schema v0.0.0-20250828062434-26de354af365
 	github.com/mcuadros/go-defaults v1.2.0
 	github.com/mh-cbon/go-fmt-fail v0.0.0-20160815164508-67765b3fbcb5
 	github.com/mitchellh/cli v1.1.5

go.sum

@@ -126,8 +126,8 @@ github.com/hashicorp/terraform-json v0.26.0 h1:+BnJavhRH+oyNWPnfzrfQwVWCZBFMvjdi
 github.com/hashicorp/terraform-json v0.26.0/go.mod h1:eyWCeC3nrZamyrKLFnrvwpc3LQPIJsx8hWHQ/nu2/v4=
 github.com/hashicorp/terraform-registry-address v0.3.0 h1:HMpK3nqaGFPS9VmgRXrJL/dzHNdheGVKk5k7VlFxzCo=
 github.com/hashicorp/terraform-registry-address v0.3.0/go.mod h1:jRGCMiLaY9zii3GLC7hqpSnwhfnCN5yzvY0hh4iCGbM=
-github.com/hashicorp/terraform-schema v0.0.0-20250616115602-34f2164294a0 h1:fpu271clSg0mDkfy7CYr1fs3ntT9AEioutKZR5r1n2s=
-github.com/hashicorp/terraform-schema v0.0.0-20250616115602-34f2164294a0/go.mod h1:si3wjikcavAEF1QIx+p+tk5EvVubBpzu9sl8YasITTs=
+github.com/hashicorp/terraform-schema v0.0.0-20250828062434-26de354af365 h1:BvAqqJmgvh5ga1Ivrmta3V35oMusrOtvCdl+J/kWoSw=
+github.com/hashicorp/terraform-schema v0.0.0-20250828062434-26de354af365/go.mod h1:nnx41+GPagX9rK6V0ZLKAM+ws5nPxO1G50DhXt44ZhQ=
 github.com/hashicorp/terraform-svchost v0.1.1 h1:EZZimZ1GxdqFRinZ1tpJwVxxt49xc/S52uzrw4x0jKQ=
 github.com/hashicorp/terraform-svchost v0.1.1/go.mod h1:mNsjQfZyf/Jhz35v6/0LWcv26+X7JPS+buii2c9/ctc=
 github.com/hexops/autogold v1.3.1 h1:YgxF9OHWbEIUjhDbpnLhgVsjUDsiHDTyDfy2lrfdlzo=

internal/features/search/ast/search.go

@@ -0,0 +1,119 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package ast
+
+import (
+	"strings"
+
+	"github.com/hashicorp/hcl/v2"
+	globalAst "github.com/hashicorp/terraform-ls/internal/terraform/ast"
+)
+
+type Filename interface {
+	String() string
+	IsJSON() bool
+	IsIgnored() bool
+}
+
+// SearchFilename is a custom type for search configuration files
+type SearchFilename string
+
+func (mf SearchFilename) String() string {
+	return string(mf)
+}
+
+func (mf SearchFilename) IsJSON() bool {
+	return strings.HasSuffix(string(mf), ".json")
+}
+
+func (mf SearchFilename) IsIgnored() bool {
+	return globalAst.IsIgnoredFile(string(mf))
+}
+
+func IsSearchFilename(name string) bool {
+	return strings.HasSuffix(name, ".tfquery.hcl") ||
+		strings.HasSuffix(name, ".tfquery.json")
+}
+
+// FilenameFromName returns a valid SearchFilename
+func FilenameFromName(name string) Filename {
+	if IsSearchFilename(name) {
+		return SearchFilename(name)
+	}
+
+	return nil
+}
+
+type Files map[Filename]*hcl.File
+
+func (sf Files) Copy() Files {
+	m := make(Files, len(sf))
+	for name, file := range sf {
+		m[name] = file
+	}
+	return m
+}
+
+func (mf Files) AsMap() map[string]*hcl.File {
+	m := make(map[string]*hcl.File, len(mf))
+	for name, file := range mf {
+		m[name.String()] = file
+	}
+	return m
+}
+
+type Diagnostics map[Filename]hcl.Diagnostics
+
+func (sd Diagnostics) Copy() Diagnostics {
+	m := make(Diagnostics, len(sd))
+	for name, diags := range sd {
+		m[name] = diags
+	}
+	return m
+}
+
+// AutoloadedOnly returns only diagnostics that are not from ignored files
+func (sd Diagnostics) AutoloadedOnly() Diagnostics {
+	diags := make(Diagnostics)
+	for name, f := range sd {
+		if !name.IsIgnored() {
+			diags[name] = f
+		}
+	}
+	return diags
+}
+
+func (sd Diagnostics) AsMap() map[string]hcl.Diagnostics {
+	m := make(map[string]hcl.Diagnostics, len(sd))
+	for name, diags := range sd {
+		m[name.String()] = diags
+	}
+	return m
+}
+
+func (sd Diagnostics) Count() int {
+	count := 0
+	for _, diags := range sd {
+		count += len(diags)
+	}
+	return count
+}
+
+func DiagnosticsFromMap(m map[string]hcl.Diagnostics) Diagnostics {
+	mf := make(Diagnostics, len(m))
+	for name, file := range m {
+		mf[FilenameFromName(name)] = file
+	}
+	return mf
+}
+
+type SourceDiagnostics map[globalAst.DiagnosticSource]Diagnostics
+
+func (svd SourceDiagnostics) Count() int {
+	count := 0
+	for _, diags := range svd {
+		count += diags.Count()
+	}
+	return count
+}

internal/features/search/decoder/path_reader.go

@@ -0,0 +1,164 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package decoder
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hashicorp/go-version"
+	"github.com/hashicorp/hcl-lang/decoder"
+	"github.com/hashicorp/hcl-lang/lang"
+	"github.com/hashicorp/hcl-lang/reference"
+	"github.com/hashicorp/hcl-lang/schema"
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/terraform-ls/internal/features/search/ast"
+	"github.com/hashicorp/terraform-ls/internal/features/search/state"
+	ilsp "github.com/hashicorp/terraform-ls/internal/lsp"
+	tfaddr "github.com/hashicorp/terraform-registry-address"
+	tfmod "github.com/hashicorp/terraform-schema/module"
+	tfschema "github.com/hashicorp/terraform-schema/schema"
+	searchSchema "github.com/hashicorp/terraform-schema/schema/search"
+	tfsearch "github.com/hashicorp/terraform-schema/search"
+)
+
+type PathReader struct {
+	StateReader  StateReader
+	ModuleReader ModuleReader
+	RootReader   RootReader
+}
+
+var _ decoder.PathReader = &PathReader{}
+
+type CombinedReader struct {
+	ModuleReader
+	StateReader
+	RootReader
+}
+
+type StateReader interface {
+	List() ([]*state.SearchRecord, error)
+	GetSearchRecordByPath(modPath string) (*state.SearchRecord, error)
+	ProviderSchema(modPath string, addr tfaddr.Provider, vc version.Constraints) (*tfschema.ProviderSchema, error)
+}
+
+type ModuleReader interface {
+	// LocalModuleMeta returns the module meta data for a local module. This is the result
+	// of the [earlydecoder] when processing module files
+	LocalModuleMeta(modPath string) (*tfmod.Meta, error)
+}
+
+type RootReader interface {
+	InstalledModulePath(rootPath string, normalizedSource string) (string, bool)
+
+	TerraformVersion(modPath string) *version.Version
+}
+
+// PathContext returns a PathContext for the given path based on the language ID
+func (pr *PathReader) PathContext(path lang.Path) (*decoder.PathContext, error) {
+	record, err := pr.StateReader.GetSearchRecordByPath(path.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	switch path.LanguageID {
+	case ilsp.Search.String():
+		return searchPathContext(record, CombinedReader{
+			StateReader:  pr.StateReader,
+			ModuleReader: pr.ModuleReader,
+			RootReader:   pr.RootReader,
+		})
+	}
+
+	return nil, fmt.Errorf("unknown language ID: %q", path.LanguageID)
+}
+
+func searchPathContext(record *state.SearchRecord, stateReader CombinedReader) (*decoder.PathContext, error) {
+	resolvedVersion := tfschema.ResolveVersion(stateReader.TerraformVersion(record.Path()), record.Meta.CoreRequirements)
+
+	sm := searchSchema.NewSearchSchemaMerger(mustCoreSchemaForVersion(resolvedVersion))
+	sm.SetStateReader(stateReader)
+
+	meta := &tfsearch.Meta{
+		Path:               record.Path(),
+		Lists:              record.Meta.Lists,
+		Variables:          record.Meta.Variables,
+		Filenames:          record.Meta.Filenames,
+		ProviderReferences: record.Meta.ProviderReferences,
+	}
+
+	mergedSchema, err := sm.SchemaForSearch(meta)
+	if err != nil {
+		return nil, err
+	}
+
+	pathCtx := &decoder.PathContext{
+		Schema:           mergedSchema,
+		ReferenceOrigins: make(reference.Origins, 0),
+		ReferenceTargets: make(reference.Targets, 0),
+		Files:            make(map[string]*hcl.File, 0),
+		Validators:       searchValidators,
+	}
+
+	// TODO: Add reference origins and targets if needed
+	for _, origin := range record.RefOrigins {
+		if ast.IsSearchFilename(origin.OriginRange().Filename) {
+			pathCtx.ReferenceOrigins = append(pathCtx.ReferenceOrigins, origin)
+		}
+	}
+
+	for _, target := range record.RefTargets {
+		if target.RangePtr != nil && ast.IsSearchFilename(target.RangePtr.Filename) {
+			pathCtx.ReferenceTargets = append(pathCtx.ReferenceTargets, target)
+		} else if target.RangePtr == nil {
+			pathCtx.ReferenceTargets = append(pathCtx.ReferenceTargets, target)
+		}
+	}
+
+	for name, f := range record.ParsedFiles {
+		if _, ok := name.(ast.SearchFilename); ok {
+			pathCtx.Files[name.String()] = f
+		}
+	}
+
+	return pathCtx, nil
+}
+
+func (pr *PathReader) Paths(ctx context.Context) []lang.Path {
+	paths := make([]lang.Path, 0)
+
+	searchRecords, err := pr.StateReader.List()
+	if err != nil {
+		return paths
+	}
+
+	for _, record := range searchRecords {
+		foundSearch := false
+		for name := range record.ParsedFiles {
+			if _, ok := name.(ast.SearchFilename); ok {
+				foundSearch = true
+			}
+
+		}
+
+		if foundSearch {
+			paths = append(paths, lang.Path{
+				Path:       record.Path(),
+				LanguageID: ilsp.Search.String(),
+			})
+		}
+
+	}
+
+	return paths
+}
+
+func mustCoreSchemaForVersion(v *version.Version) *schema.BodySchema {
+	s, err := searchSchema.CoreSearchSchemaForVersion(v)
+	if err != nil {
+		// this should never happen
+		panic(err)
+	}
+	return s
+}