fix: validate metric dependency references

Resolve metric dependencies iteratively and report cycles or unknown references with their dependency chain and defining file. Preserve forward references, shared dependencies, and case-insensitive metric names with execution-based regression coverage.

Signed-off-by: tchivs <topivn@live.cn>

Author: tchivs

docs/concepts/metrics/definition.md

@@ -59,7 +59,7 @@ Because the `prod.users.country` and `prod.searches.num_searches` models have sp
 
 Metrics can perform additional operations/calculations with other metrics.
 
-In this example, the third metric `clicks_per_search` is calculated by dividing the first metric `total_searches` by the second metric `total_clicks`:
+In this example, the third metric `clicks_per_search` is calculated by dividing `total_clicks` by `total_searches`:
 
 ```sql linenums="1"
 METRIC (
@@ -78,6 +78,8 @@ METRIC (
 );
 ```
 
+Metric references are case insensitive, including quoted references, and may refer to metrics defined later in the project. Shared dependencies are resolved once during expansion. An unknown dependency or a dependency cycle raises a configuration error with the dependency chain and the path of the definition containing the invalid reference.
+
 ## Properties
 
 The `METRIC` definition supports the following keys. The `name` and `expression` keys are required.

sqlmesh/core/metric/definition.py

@@ -99,43 +99,71 @@ def to_metric(
         self, metas: t.Dict[str, MetricMeta], metrics: UniqueKeyDict[str, Metric]
     ) -> Metric:
         """Converts a metric meta into a fully expanded and standalone metric."""
-        metric_refs = {}
-        agg_or_ref = False
-
-        for node in self.expression.walk():
-            if isinstance(node, exp.Alias):
-                _raise_metric_config_error(
-                    f"Alias found for metric '{self.name}' which is not allowed", self._path
-                )
-            elif isinstance(node, exp.AggFunc):
-                agg_or_ref = True
-            elif isinstance(node, exp.Column) and not node.table:
-                agg_or_ref = True
-                ref = node.sql(dialect=self.dialect)
-
-                if ref not in metrics:
-                    metrics[ref] = metas[ref].to_metric(metas, metrics)
-
-                metric_refs[node] = metrics[ref]
-
-        if not agg_or_ref:
-            _raise_metric_config_error(
-                f"Metric '{self.name}' missing an aggregation or metric ref", self._path
-            )
-
-        if metric_refs:
-            expanded = self.expression.copy()
-            for column in expanded.find_all(exp.Column):
-                metric = metric_refs.get(column)
-
-                if metric:
-                    column.replace(metric.expanded.copy())
-        else:
-            expanded = exp.alias_(self.expression, self.name)
-
-        metric = Metric(**self.dict(), expanded=expanded)
-        metric._path = self._path
-        return metric
+        # Suspend each expression walk while resolving a dependency so cycles of
+        # any depth can be diagnosed without using the Python call stack.
+        stack: t.List[t.Tuple[MetricMeta, t.Iterator[exp.Expr], t.Dict[exp.Column, str], bool]] = [
+            (self, self.expression.walk(), {}, False)
+        ]
+        visiting = {self.name}
+
+        while True:
+            meta, nodes, metric_refs, agg_or_ref = stack.pop()
+
+            for node in nodes:
+                if isinstance(node, exp.Alias):
+                    _raise_metric_config_error(
+                        f"Alias found for metric '{meta.name}' which is not allowed", meta._path
+                    )
+                elif isinstance(node, exp.AggFunc):
+                    agg_or_ref = True
+                elif isinstance(node, exp.Column) and not node.table:
+                    agg_or_ref = True
+                    ref = node.name.lower()
+                    metric_refs[node] = ref
+
+                    if ref not in metrics:
+                        is_cycle = ref in visiting
+                        if is_cycle or ref not in metas:
+                            dependency_path = " -> ".join(
+                                [frame[0].name for frame in stack] + [meta.name, ref]
+                            )
+                            if is_cycle:
+                                message = f"Metric dependency cycle detected: {dependency_path}"
+                            else:
+                                message = (
+                                    f"Unknown metric '{ref}' referenced by metric '{meta.name}' "
+                                    f"(dependency path: {dependency_path})"
+                                )
+                            _raise_metric_config_error(message, meta._path)
+
+                        dependency = metas[ref]
+                        stack.append((meta, nodes, metric_refs, agg_or_ref))
+                        stack.append((dependency, dependency.expression.walk(), {}, False))
+                        visiting.add(ref)
+                        break
+            else:
+                if not agg_or_ref:
+                    _raise_metric_config_error(
+                        f"Metric '{meta.name}' missing an aggregation or metric ref", meta._path
+                    )
+
+                if metric_refs:
+                    expanded = meta.expression.copy()
+                    for column in expanded.find_all(exp.Column):
+                        reference = metric_refs.get(column)
+                        if reference is not None:
+                            column.replace(metrics[reference].expanded.copy())
+                else:
+                    expanded = exp.alias_(meta.expression, meta.name)
+
+                metric = Metric(**meta.dict(), expanded=expanded)
+                metric._path = meta._path
+                visiting.remove(meta.name)
+
+                if not stack:
+                    return metric
+
+                metrics[meta.name] = metric
 
 
 class Metric(MetricMeta, frozen=True):