Inline References as First-Class Values (string or reference)

[pewpewpotato]

Summary

Adopt inline references as first-class value expressions alongside string literals. Any key’s value can be either:

• a string literal, or
• a reference expression of the form reference:{alias}:{path}

Top-level reference: statements are deprecated and will be removed in a future major version.

Motivation

• Co-locate references with their usage to reduce boilerplate and cognitive load.
• Improve diagnostics by reporting errors precisely at the value site.
• Keep the value model simple and explicit: values are either literals or resolvable references.

Syntax

• String value:
  • name: 'prod-vpc'
• Reference value:
  • cidr: reference:network:vpc.cidr
• Both forms can appear wherever a value is allowed (mapping values, list items).

Example:

infrastructure:
  vpc:
    cidr: reference:network:vpc.cidr   # reference value
    name: 'prod-vpc'                   # string value

Parser/AST

• Section entry values are expressions (Expr) that can be:
  • StringLiteral
  • ReferenceExpr (alias + dotted path)
• Both variants carry precise SourceSpan info for diagnostics.
• Legacy top-level ReferenceStmt remains temporarily for back-compat with deprecation warnings.

See also: libs/parser/README.md — updated to document that a key’s value can be a string literal or an inline reference, and that ReferenceExpr is a supported expression type.

Compiler/Analyzer changes

• Name resolution: resolve ReferenceExpr after symbol tables/imports are established; respect aliasing and shadowing rules.
• Evaluation order: two-phase (collect → resolve/evaluate) to allow forward references; detect and report cycles with clear spans.
• Codegen: emit snapshots with references resolved to concrete values; preserve output determinism.
• Diagnostics: path-aware, actionable errors for unresolved/ambiguous references and cycles.

Backward compatibility & migration

• Current: Inline references ON; accept legacy reference: with deprecation warnings.
• Next major: Remove legacy top-level reference: form; provide codemod guidance.

Testing

• Parser golden tests for:
  • values as strings, references, and mixed lists/maps
  • alias + dotted path combos
  • error cases (unresolved, ambiguous, cycles)
• Integration tests to ensure resolved outputs match expectations and remain deterministic.

Open questions

• Deprecation window length for top-level reference:.
• Standardize error wording and suggestion text for unresolved references.
• Any large-config performance considerations for multi-pass resolve.

Acceptance criteria

• Values parse as either StringLiteral or ReferenceExpr with correct spans.
• Resolver produces correct concrete values; clear errors for unresolved references and cycles.
• Back-compat verified by tests and deprecation warnings.