Allow locals to access settings, vars, and env from the same file. Add locals design patterns. Add Atmos YAML functions support in locals (#1994)

* fix locals

* fix locals

* [autofix.ci] apply automated fixes

* address comments

* improve docs, add example for `locals`

* [autofix.ci] apply automated fixes

* address comments

* update docs

* address comments, update docs, add tests for locals example, add locals design patterns, add blog post

* address comments, update docs, add tests

* address comments, update docs, add tests

* address comments, update docs, add tests

* address comments, update docs, add tests

* address comments

* update docs

* update docs

* fix: Align diagram with numbered steps and add missing periods

- Update mermaid diagram to show template processing as step 4 after merge
- Remove step 3 from per-file boxes (templates processed after merge)
- Add periods to list items in troubleshooting section for consistency

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* update docs

* update docs

* update docs

* update docs and example

* update docs and example

* locals with Atmos YAML functions, update docs, add tests, add blog posts

* update roadmap

* address comments, add tests

* update docs

* docs: Condense locals documentation by 60% for clarity (#2000)

- Reduced stacks/locals.mdx from 827 to 331 lines (60% cut)
- Consolidated Configuration Scopes (3 examples → 1 comprehensive example)
- Moved Processing Order diagram to <details> block ("How does processing work?")
- Deleted redundant "Complete Example" section, rely on "Try It" embed instead
- Removed duplicate explanations of file-scoped isolation across sections
- Moved debugging output examples to <details> block
- Condensed error handling section and best practices
- Removed "Scope Merging", "Limitations", "When to Use Each" sections as redundant

- Reduced examples/locals/README.md from 155 to 35 lines (77% cut)
- Aligned with standard example README pattern (demo-stacks/README.md style)
- Removed 60-line "Example Output" section
- Removed 40-line "Key Concepts" section duplicating main docs
- Fixed broken documentation link (/core-concepts/stacks/locals → /stacks/locals)

Locals is a minor feature with key gotchas. Documentation now appropriately sized.

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

* update tests

* address comments

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

Author: 4 people

NOTICE

@@ -23,7 +23,7 @@ APACHE 2.0 LICENSED DEPENDENCIES
 
   - cloud.google.com/go/auth
     License: Apache-2.0
-    URL: https://github.com/googleapis/google-cloud-go/blob/auth/v0.17.0/auth/LICENSE
+    URL: https://github.com/googleapis/google-cloud-go/blob/auth/v0.18.0/auth/LICENSE
 
   - cloud.google.com/go/auth/oauth2adapt
     License: Apache-2.0
@@ -307,7 +307,7 @@ APACHE 2.0 LICENSED DEPENDENCIES
 
   - github.com/googleapis/enterprise-certificate-proxy/client
     License: Apache-2.0
-    URL: https://github.com/googleapis/enterprise-certificate-proxy/blob/v0.3.7/LICENSE
+    URL: https://github.com/googleapis/enterprise-certificate-proxy/blob/v0.3.9/LICENSE
 
   - github.com/gosimple/unidecode
     License: Apache-2.0
@@ -507,15 +507,15 @@ APACHE 2.0 LICENSED DEPENDENCIES
 
   - google.golang.org/genproto/googleapis/rpc
     License: Apache-2.0
-    URL: https://github.com/googleapis/go-genproto/blob/97cd9d5aeac2/googleapis/rpc/LICENSE
+    URL: https://github.com/googleapis/go-genproto/blob/0a764e51fe1b/googleapis/rpc/LICENSE
 
   - google.golang.org/grpc
     License: Apache-2.0
     URL: https://github.com/grpc/grpc-go/blob/v1.78.0/LICENSE
 
   - gopkg.in/ini.v1
     License: Apache-2.0
-    URL: https://github.com/go-ini/ini/blob/v1.67.0/LICENSE
+    URL: https://github.com/go-ini/ini/blob/v1.67.1/LICENSE
 
   - gopkg.in/yaml.v2
     License: Apache-2.0
@@ -788,11 +788,11 @@ BSD LICENSED DEPENDENCIES
 
   - google.golang.org/api
     License: BSD-3-Clause
-    URL: https://github.com/googleapis/google-api-go-client/blob/v0.258.0/LICENSE
+    URL: https://github.com/googleapis/google-api-go-client/blob/v0.260.0/LICENSE
 
   - google.golang.org/api/internal/third_party/uritemplates
     License: BSD-3-Clause
-    URL: https://github.com/googleapis/google-api-go-client/blob/v0.258.0/internal/third_party/uritemplates/LICENSE
+    URL: https://github.com/googleapis/google-api-go-client/blob/v0.260.0/internal/third_party/uritemplates/LICENSE
 
   - google.golang.org/protobuf
     License: BSD-3-Clause
@@ -1074,7 +1074,7 @@ MIT LICENSED DEPENDENCIES
 
   - github.com/bmatcuk/doublestar/v4
     License: MIT
-    URL: https://github.com/bmatcuk/doublestar/blob/v4.9.1/LICENSE
+    URL: https://github.com/bmatcuk/doublestar/blob/v4.9.2/LICENSE
 
   - github.com/catppuccin/go
     License: MIT

errors/errors.go

@@ -743,10 +743,11 @@ var (
 	ErrNoOptionsAvailable          = errors.New("no options available")
 
 	// Locals-related errors.
-	ErrLocalsInvalidType       = errors.New("locals must be a map")
-	ErrLocalsCircularDep       = errors.New("circular dependency in locals")
-	ErrLocalsDependencyExtract = errors.New("failed to extract dependencies for local")
-	ErrLocalsResolution        = errors.New("failed to resolve local")
+	ErrLocalsInvalidType        = errors.New("locals must be a map")
+	ErrLocalsCircularDep        = errors.New("circular dependency in locals")
+	ErrLocalsDependencyExtract  = errors.New("failed to extract dependencies for local")
+	ErrLocalsResolution         = errors.New("failed to resolve local")
+	ErrLocalsYamlFunctionFailed = errors.New("failed to process YAML function in local")
 
 	// Source provisioner errors.
 	ErrSourceProvision       = errors.New("source provisioning failed")

examples/locals/README.md

@@ -0,0 +1,35 @@
+# Example: Locals
+
+Reduce repetition and build computed values using file-scoped locals.
+
+Learn more about [Locals](https://atmos.tools/stacks/locals).
+
+## What You'll See
+
+- **Basic locals**: Define reusable values within a file
+- **Dependency resolution**: Locals can reference other locals
+- **Context access**: Locals can access `settings`, `vars`, and `env` from the same file
+- **File-scoped isolation**: Each stack file has independent locals
+
+## Try It
+
+```shell
+cd examples/locals
+
+# View resolved locals for the dev stack
+atmos describe locals -s dev
+
+# View resolved locals for a specific component
+atmos describe locals myapp -s dev
+
+# Compare dev vs prod
+atmos describe locals myapp -s prod
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `stacks/deploy/dev.yaml` | Development stack with locals |
+| `stacks/deploy/prod.yaml` | Production stack with locals |
+| `components/terraform/myapp/main.tf` | Terraform component |

examples/locals/atmos.yaml

@@ -0,0 +1,25 @@
+# Atmos Locals Example
+
+base_path: "."
+
+components:
+  terraform:
+    base_path: "components/terraform"
+    apply_auto_approve: false
+    deploy_run_init: true
+    init_run_reconfigure: true
+    auto_generate_backend_file: false
+
+stacks:
+  base_path: "stacks"
+  included_paths:
+    - "deploy/**/*"
+  name_template: "{{ .vars.stage }}"
+
+templates:
+  settings:
+    enabled: true
+    sprig:
+      enabled: true
+    gomplate:
+      enabled: true

examples/locals/components/terraform/myapp/main.tf

@@ -0,0 +1,45 @@
+# Mock component for locals demo.
+#
+# This component outputs the variables it receives, allowing you to see
+# how locals are resolved and passed to components.
+
+variable "name" {
+  type        = string
+  description = "Application name"
+}
+
+variable "environment" {
+  type        = string
+  description = "Environment name"
+}
+
+variable "full_name" {
+  type        = string
+  description = "Full application name (computed from locals)"
+}
+
+variable "tags" {
+  type        = map(string)
+  description = "Resource tags (computed from locals)"
+  default     = {}
+}
+
+output "name" {
+  description = "Application name"
+  value       = var.name
+}
+
+output "environment" {
+  description = "Environment name"
+  value       = var.environment
+}
+
+output "full_name" {
+  description = "Full application name"
+  value       = var.full_name
+}
+
+output "tags" {
+  description = "Resource tags"
+  value       = var.tags
+}

examples/locals/stacks/deploy/dev.yaml

@@ -0,0 +1,46 @@
+# Development Environment Stack
+#
+# This stack demonstrates locals for reducing repetition and building
+# computed values. Locals are file-scoped (cannot be accessed from other files).
+
+settings:
+  version: v1
+  team: platform
+
+vars:
+  stage: dev
+
+# Locals can reference other locals, settings, and vars.
+locals:
+  # Basic values
+  namespace: acme
+  environment: development
+
+  # Reference other locals
+  name_prefix: "{{ .locals.namespace }}-{{ .locals.environment }}"
+
+  # Access settings
+  app_version: "{{ .settings.version }}"
+
+  # Access vars
+  stage_name: "{{ .vars.stage }}"
+
+  # Build complex computed values
+  full_name: "{{ .locals.name_prefix }}-{{ .locals.stage_name }}"
+
+  # Maps work too
+  default_tags:
+    Namespace: "{{ .locals.namespace }}"
+    Environment: "{{ .locals.environment }}"
+    Team: "{{ .settings.team }}"
+    ManagedBy: Atmos
+
+# Components use the resolved locals
+components:
+  terraform:
+    myapp:
+      vars:
+        name: "{{ .locals.namespace }}"
+        environment: "{{ .locals.environment }}"
+        full_name: "{{ .locals.full_name }}"
+        tags: "{{ .locals.default_tags }}"

examples/locals/stacks/deploy/prod.yaml

@@ -0,0 +1,36 @@
+# Production Environment Stack
+#
+# This stack shows locals with different values for production.
+# Each file has its own isolated locals scope.
+
+settings:
+  version: v2
+  team: platform
+
+vars:
+  stage: prod
+
+locals:
+  namespace: acme
+  environment: production
+
+  # Same pattern, different values
+  name_prefix: "{{ .locals.namespace }}-{{ .locals.environment }}"
+  full_name: "{{ .locals.name_prefix }}-{{ .vars.stage }}"
+
+  # Production-specific tags
+  default_tags:
+    Namespace: "{{ .locals.namespace }}"
+    Environment: "{{ .locals.environment }}"
+    Team: "{{ .settings.team }}"
+    ManagedBy: Atmos
+    CostCenter: production
+
+components:
+  terraform:
+    myapp:
+      vars:
+        name: "{{ .locals.namespace }}"
+        environment: "{{ .locals.environment }}"
+        full_name: "{{ .locals.full_name }}"
+        tags: "{{ .locals.default_tags }}"

go.mod

@@ -358,7 +358,7 @@ func processStackFileForLocals(
 		return &stackFileLocalsResult{}, nil
 	}
 
-	localsCtx, err := ProcessStackLocals(atmosConfig, rawConfig, filePath)
+	localsCtx, err := ProcessStackLocals(atmosConfig, rawConfig, filePath, stackName)
 	if err != nil {
 		return &stackFileLocalsResult{Found: true}, fmt.Errorf("failed to process locals for stack %s: %w", stackFileName, err)
 	}