DEV-1450 principled redesign of syntax (WIP)

slayer/core/errors.py

@@ -114,3 +114,264 @@ def __init__(self, cycle: List[Tuple[str, str]]) -> None:
         self.cycle: List[Tuple[str, str]] = list(cycle)
         chain = " → ".join(f"{m}.{c}" for m, c in self.cycle)
         super().__init__(f"Circular column reference detected: {chain}")
+
+
+# ---------------------------------------------------------------------------
+# DEV-1450 stage-5 errors — typed, stable str() format.
+#
+# All error classes below build their message via ``_format_error_message``
+# so ``str(error)`` follows the documented snapshot-friendly shape::
+#
+#     <ErrorName>: <one-line summary>
+#       at <location>
+#       scope: <short scope summary>
+#       suggestion: <did-you-mean>
+#
+# Each indented line is optional. The first line ALWAYS starts with the
+# class name so log greps and snapshot tests bind to a stable prefix.
+# ---------------------------------------------------------------------------
+
+
+def _format_error_message(
+    *,
+    cls_name: str,
+    summary: str,
+    location: str | None = None,
+    scope: str | None = None,
+    suggestion: str | None = None,
+    extras: List[Tuple[str, str]] | None = None,
+) -> str:
+    """Build the stable error-message string used by stage-5 error classes.
+
+    ``extras`` lets a class add bespoke key/value rows after the summary
+    while keeping the leading ``ClassName:`` token intact.
+    """
+    lines = [f"{cls_name}: {summary}"]
+    if location:
+        lines.append(f"  at {location}")
+    if scope:
+        lines.append(f"  scope: {scope}")
+    for k, v in (extras or []):
+        lines.append(f"  {k}: {v}")
+    if suggestion:
+        lines.append(f"  suggestion: {suggestion}")
+    return "\n".join(lines)
+
+
+class UnknownReferenceError(SlayerError):
+    """A bare or dotted reference cannot be resolved in the current scope."""
+
+    def __init__(
+        self,
+        name: str,
+        scope_kind: str,
+        scope_summary: str,
+        suggestion: str | None = None,
+    ) -> None:
+        self.name = name
+        self.scope_kind = scope_kind
+        self.scope_summary = scope_summary
+        self.suggestion = suggestion
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Cannot resolve reference {name!r}.",
+            scope=f"{scope_kind}: {scope_summary}",
+            suggestion=suggestion,
+        ))
+
+
+class AmbiguousReferenceError(SlayerError):
+    """A reference matches multiple candidates in scope and can't pick one."""
+
+    def __init__(self, name: str, candidates: List[str]) -> None:
+        self.name = name
+        self.candidates = sorted(candidates)
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Reference {name!r} has multiple candidates.",
+            extras=[("candidates", repr(self.candidates))],
+        ))
+
+
+class IllegalScopeReferenceError(SlayerError):
+    """A reference is syntactically rejected by the current scope kind.
+
+    Examples: ``__`` in a Mode-B ``ModelScope`` ref (use the dotted form);
+    a dotted ref against a ``StageSchema`` (downstream stages see a flat
+    namespace, no join syntax).
+    """
+
+    def __init__(self, name: str, scope_kind: str, reason: str) -> None:
+        self.name = name
+        self.scope_kind = scope_kind
+        self.reason = reason
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Reference {name!r} is not legal in this scope.",
+            scope=scope_kind,
+            extras=[("reason", reason)],
+        ))
+
+
+class IllegalWindowInFilterError(SlayerError):
+    """A filter contains a raw ``OVER(...)`` window expression, or refers
+    to a ``Column.sql`` whose body contains a window function (DEV-1369 /
+    DEV-1336 — predicate promotion was removed). Use a rank-family
+    transform instead.
+    """
+
+    def __init__(
+        self,
+        filter_expr: str,
+        source: str,
+        suggestion: str = "use a rank-family transform (e.g. `rank(<measure>) <= N`).",
+    ) -> None:
+        self.filter_expr = filter_expr
+        self.source = source
+        self.suggestion = suggestion
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary="Window expressions are not allowed in filters.",
+            extras=[
+                ("expr", repr(filter_expr)),
+                ("source", source),
+            ],
+            suggestion=suggestion,
+        ))
+
+
+class AggregationNotAllowedError(SlayerError):
+    """An aggregation cannot apply to a column.
+
+    Covers type-bucket violations (``sum`` on TEXT), primary-key
+    restrictions (only ``count`` / ``count_distinct``), and explicit
+    ``Column.allowed_aggregations`` whitelist violations.
+    """
+
+    def __init__(self, column: str, agg: str, reason: str) -> None:
+        self.column = column
+        self.agg = agg
+        self.reason = reason
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Aggregation {agg!r} is not allowed on column {column!r}.",
+            extras=[("reason", reason)],
+        ))
+
+
+class UnknownFunctionError(SlayerError):
+    """A function call in Mode B is not in the ``SCALAR_FUNCTIONS`` allowlist,
+    the transform registry, or the model's aggregation set (C12).
+    """
+
+    _DEFAULT_SUGGESTION = "move the call to a derived Column.sql (Mode A)."
+
+    def __init__(
+        self,
+        name: str,
+        location: str,
+        suggestion: str | None = None,
+    ) -> None:
+        self.name = name
+        self.location = location
+        self.suggestion = suggestion or self._DEFAULT_SUGGESTION
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Function {name!r} is not allowed in Mode B.",
+            location=location,
+            suggestion=self.suggestion,
+        ))
+
+
+class MeasureRecursionLimitError(SlayerError):
+    """Named-measure expansion exceeded the configurable depth limit
+    (default 32; ``SLAYER_MEASURE_EXPANSION_DEPTH``).
+    """
+
+    def __init__(self, chain: List[str], limit: int = 32) -> None:
+        self.chain = list(chain)
+        self.limit = limit
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Named-measure expansion exceeded depth (limit={limit}).",
+            extras=[("chain", " → ".join(self.chain))],
+        ))
+
+
+class MeasureCycleError(SlayerError):
+    """Named-measure expansion encountered a cycle."""
+
+    def __init__(self, chain: List[str]) -> None:
+        self.chain = list(chain)
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary="Cyclic reference in named-measure expansion.",
+            extras=[("chain", " → ".join(self.chain))],
+        ))
+
+
+class DuplicateMeasureNameError(SlayerError):
+    """Two measures in the same query declare the same explicit ``name``
+    (DEV-1443).
+    """
+
+    def __init__(self, name: str, occurrences: List[str]) -> None:
+        self.name = name
+        self.occurrences = list(occurrences)
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=f"Measure name {name!r} is declared more than once.",
+            extras=[("occurrences", repr(self.occurrences))],
+        ))
+
+
+class MeasureNameCollidesWithColumnError(SlayerError):
+    """A declared measure ``name`` matches a source column on the model
+    (DEV-1443) — the alias-form filter would silently bind to the source
+    column instead of the aggregate.
+    """
+
+    def __init__(self, name: str, model: str) -> None:
+        self.name = name
+        self.model = model
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=(
+                f"Declared measure name {name!r} matches a source column on "
+                f"model {model!r}."
+            ),
+        ))
+
+
+class CanonicalAliasShadowsColumnError(SlayerError):
+    """A formula's canonical alias (e.g., ``amount_sum`` for ``amount:sum``)
+    shadows a source column on the same model (DEV-1443).
+    """
+
+    def __init__(self, formula: str, canonical: str, model: str) -> None:
+        self.formula = formula
+        self.canonical = canonical
+        self.model = model
+        super().__init__(_format_error_message(
+            cls_name=type(self).__name__,
+            summary=(
+                f"Canonical alias {canonical!r} for formula {formula!r} "
+                f"shadows a source column on model {model!r}."
+            ),
+        ))
+
+
+class UnreachableFilterDroppedWarning(UserWarning):
+    """A host filter referenced slots that aren't reachable from a
+    cross-model CTE's root, so the filter was dropped from the CTE.
+    The host query still applies the filter to its own rows; this is a
+    visibility/debug warning, not an error.
+    """
+
+    def __init__(self, filter_text: str, reason: str) -> None:
+        self.filter_text = filter_text
+        self.reason = reason
+        super().__init__(
+            f"Filter {filter_text!r} dropped from cross-model CTE "
+            f"(unreachable from CTE root): {reason}"
+        )