dataface 0.1.2__py3-none-any.whl

dataface/core/render/variable_input_refinement.py

@@ -0,0 +1,140 @@
+"""Data-aware variable input type refinement.
+
+Stage: RENDER (post-query)
+Purpose: Inspect resolved options data to refine the compile-time input type.
+
+The compile-time detector (_detect_variable_input_type) handles YAML-structural
+signals: options → select, min/max → slider, bool default → checkbox. This module
+adds the second phase: data-aware refinement that runs after options queries
+execute — mirroring how chart type auto-detection works at render time.
+
+Detection priority: date > boolean > numeric-slider > unchanged.
+"""
+
+import math
+from datetime import date
+from typing import TYPE_CHECKING, NamedTuple
+
+from dataface.core.compile.models.variable.authored import VariableInputType
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.variable.authored import Variable
+
+# Thresholds
+_SLIDER_MAX_DISTINCT = 200  # Don't offer slider for huge option sets
+_SLIDER_MAX_RANGE_STEPS = 1000  # Range / step must be <= this
+
+_BOOLEAN_PAIRS = frozenset(
+    {
+        frozenset({"true", "false"}),
+        frozenset({"yes", "no"}),
+        # Note: {"0", "1"} is ambiguous — could be numeric range.
+        # We treat it as boolean here since a 0/1 slider isn't useful.
+        frozenset({"0", "1"}),
+    }
+)
+
+
+class RefinedType(NamedTuple):
+    """Result of data-aware input type refinement."""
+
+    input_type: VariableInputType
+    slider_min: int | float | None = None
+    slider_max: int | float | None = None
+    slider_step: int | float | None = None
+
+
+def refine_input_type_from_data(
+    var_def: "Variable",
+    option_values: list[str],
+) -> RefinedType:
+    """Refine a variable's input type based on its resolved option values.
+
+    Only refines when the compile-time type was auto-detected (input_auto_detected).
+    Explicit author-set types are never overridden. Does not mutate var_def.
+
+    Args:
+        var_def: Variable definition (read-only).
+        option_values: Resolved distinct option values as strings.
+
+    Returns:
+        RefinedType with the input type and optional slider bounds.
+    """
+    current = var_def.input
+    if not var_def.input_auto_detected:
+        return RefinedType(current)
+
+    if not option_values:
+        return RefinedType(current)
+
+    # --- Type-based detection (strongest signal) ---
+
+    if _looks_like_dates(option_values):
+        return RefinedType("datepicker")
+
+    if _looks_like_booleans(option_values):
+        return RefinedType("checkbox")
+
+    if len(option_values) <= _SLIDER_MAX_DISTINCT:
+        parsed = _try_parse_numbers(option_values)
+        if parsed is not None:
+            min_val, max_val = min(parsed), max(parsed)
+            val_range = max_val - min_val
+            if val_range > 0:
+                all_ints = all(v.is_integer() for v in parsed)
+                step = 1 if all_ints else round(val_range / 100, 6)
+                if val_range / step <= _SLIDER_MAX_RANGE_STEPS:
+                    return RefinedType(
+                        "slider",
+                        slider_min=int(min_val) if all_ints else min_val,
+                        slider_max=int(max_val) if all_ints else max_val,
+                        slider_step=int(step) if all_ints else step,
+                    )
+
+    # No type-based refinement matched — keep compile-time type (select).
+    return RefinedType(current)
+
+
+def _looks_like_dates(values: list[str]) -> bool:
+    """True if >= 80% of values parse as ISO dates via datetime.date.fromisoformat.
+
+    Single-value lists return False — a single option is too little signal.
+    """
+    if len(values) < 2:
+        return False
+    matches = 0
+    for v in values:
+        try:
+            # Require full YYYY-MM-DD (10 chars minimum)
+            if len(v) < 10:
+                continue
+            date.fromisoformat(v[:10])
+            # Reject if there's trailing content that isn't a time separator
+            if len(v) > 10 and v[10] not in ("T", " ", "\t"):
+                continue
+            matches += 1
+        except ValueError:
+            pass
+    return matches / len(values) >= 0.8
+
+
+def _looks_like_booleans(values: list[str]) -> bool:
+    """True if values are exactly a known boolean pair."""
+    if len(values) != 2:
+        return False
+    pair = frozenset(v.lower().strip() for v in values)
+    return pair in _BOOLEAN_PAIRS
+
+
+def _try_parse_numbers(values: list[str]) -> list[float] | None:
+    """Try to parse all values as finite numbers. Returns None if any fail."""
+    parsed: list[float] = []
+    for v in values:
+        try:
+            n = float(v)
+            if not math.isfinite(n):
+                return None
+            parsed.append(n)
+        except (ValueError, TypeError):
+            return None
+    return parsed

dataface/core/render/warnings/__init__.py

@@ -0,0 +1,15 @@
+"""Render-time warning system: models, registry, runner, and suppression."""
+
+from __future__ import annotations
+
+from dataface.core.render.warnings.base import RenderWarning, WarningContext
+from dataface.core.render.warnings.registry import DETECTORS, run_all
+from dataface.core.render.warnings.suppression import partition
+
+__all__ = [
+    "RenderWarning",
+    "WarningContext",
+    "DETECTORS",
+    "run_all",
+    "partition",
+]

dataface/core/render/warnings/bar_color_1_to_1_with_x.py

@@ -0,0 +1,80 @@
+"""Detector: BAR_COLOR_1_TO_1_WITH_X.
+
+Fires on bar charts where the color field is 1:1 with the x field.
+When this happens Vega-Lite allocates a grouped-bar sub-band for each
+color value per x tick, but since each x tick only has one color value,
+all other sub-bands are empty — the visible bar occupies 1/N of the slot
+width, producing razor-thin bars.
+
+Detection rule:
+  unique (x, color) pairs == unique x values  AND  len(unique x) >= 2
+"""
+
+from __future__ import annotations
+
+from dataface.core.render.warnings.base import RenderWarning, WarningContext
+
+CODE = "BAR_COLOR_1_TO_1_WITH_X"
+
+# Minimum distinct x values before the rule fires; avoids degenerate 1-row data.
+_MIN_UNIQUE_X = 2
+
+# Bar chart types eligible for this detector.
+_BAR_TYPES = frozenset({"bar"})
+
+
+def detect(ctx: WarningContext) -> list[RenderWarning]:
+    """Return one RenderWarning per bar chart with color 1:1 with x."""
+    warnings: list[RenderWarning] = []
+
+    for chart_id, chart in ctx.face_spec.charts.items():
+        # Only bar charts with a color encoding and an x encoding.
+        if chart.type not in _BAR_TYPES:
+            continue
+        if chart.color is None:
+            continue
+        if chart.x is None:
+            continue
+        # color == x is intentional reuse, not the thin-bar pathology.
+        if chart.color == chart.x:
+            continue
+        # Stacked bars don't produce sub-bands; the thin-bar pathology only
+        # appears in grouped layout, which requires chart.stack to be falsy.
+        if chart.stack:
+            continue
+        # Respect the sparse vega_specs contract.
+        if chart_id not in ctx.vega_specs:
+            continue
+
+        x_field: str = chart.x
+        color_field: str = chart.color
+        rows = ctx.chart_results.get(chart_id, [])
+
+        unique_x = {row[x_field] for row in rows if x_field in row}
+        if len(unique_x) < _MIN_UNIQUE_X:
+            continue
+
+        unique_pairs = {
+            (row[x_field], row[color_field])
+            for row in rows
+            if x_field in row and color_field in row
+        }
+
+        if len(unique_x) == len(unique_pairs):
+            warnings.append(
+                RenderWarning(
+                    code=CODE,
+                    chart=chart_id,
+                    field=color_field,
+                    message=(
+                        f"Color field '{color_field}' has the same cardinality as x field "
+                        f"'{x_field}'; every bar gets a solo sub-band, producing razor-thin bars."
+                    ),
+                    fix=(
+                        "Drop the color encoding or pick a color field with lower "
+                        "cardinality than the x axis."
+                    ),
+                )
+            )
+
+    return warnings

dataface/core/render/warnings/base.py

@@ -0,0 +1,44 @@
+"""Pydantic models for render-time warnings.
+
+RenderWarning is the wire shape for a single warning (named RenderWarning, not
+Warning, to avoid shadowing the stdlib Warning base class).
+
+WarningContext carries everything detectors need:
+  - face_spec: the compiled Face (typed — detectors use attribute access).
+  - chart_results: chart id → list of row dicts (query output).
+  - vega_specs: chart id → Vega-Lite spec dict.
+
+vega_specs is SPARSE: KPI, text, and markdown charts do not compile to
+Vega-Lite, so their ids are OMITTED from this dict (not present as None).
+Detectors that key into vega_specs must guard with:
+    if chart_id not in ctx.vega_specs:
+        continue
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from dataface.core.compile.models.face.compiled import Face
+
+
+class RenderWarning(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    chart: str | None = None
+    code: str
+    field: str | None = None
+    message: str
+    fix: str | None = None
+
+
+class WarningContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    face_spec: Face
+    # chart id → list of row dicts from the executed query
+    chart_results: dict[str, list[dict[str, Any]]]
+    # chart id → Vega-Lite spec dict (sparse — non-vega charts are omitted)
+    vega_specs: dict[str, dict[str, Any]]

dataface/core/render/warnings/fanout_risk.py

@@ -0,0 +1,15 @@
+"""Emitter: FANOUT_RISK.
+
+Fires when query validation detects a join that may multiply rows beyond
+what the chart's aggregation can recover. The diagnostic comes from
+``dataface.core.inspect.query_validator`` (code ``fanout_risk``); when a
+cached relationship context (super-schema profiles) is available, severity
+is calibrated against known multiplicities.
+
+Emitted by ``dataface.core.compile.compiler.validate_compiled_queries``
+(invoked indirectly via ``dataface_super_schema.inspect.relationship_warnings``).
+"""
+
+from __future__ import annotations
+
+CODE = "FANOUT_RISK"

dataface/core/render/warnings/from_query_diagnostic.py

@@ -0,0 +1,56 @@
+"""Adapter: QueryDiagnostic → RenderWarning.
+
+The query validator emits ``QueryDiagnostic`` with lowercase snake_case codes
+(``fanout_risk``, ``missing_join_predicate``, etc.). The unified warning
+channel uses ``RenderWarning`` with SCREAMING_SNAKE_CASE codes owned by
+per-code modules. This adapter maps between the two.
+
+Each ``QueryDiagnostic.code`` value has a matching module in this package
+that owns the stable RenderWarning ``CODE``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dataface.core.render.warnings import (
+    fanout_risk,
+    missing_join_predicate,
+    query_parse_error,
+    reaggregation,
+)
+from dataface.core.render.warnings.base import RenderWarning
+
+if TYPE_CHECKING:
+    from dataface.core.inspect.query_validator import QueryDiagnostic
+
+_DIAGNOSTIC_CODE_TO_RENDER_CODE: dict[str, str] = {
+    "fanout_risk": fanout_risk.CODE,
+    "missing_join_predicate": missing_join_predicate.CODE,
+    "parse_error": query_parse_error.CODE,
+    "reaggregation": reaggregation.CODE,
+}
+
+KNOWN_RENDER_CODES: frozenset[str] = frozenset(_DIAGNOSTIC_CODE_TO_RENDER_CODE.values())
+
+
+def from_query_diagnostic(query_name: str, diag: QueryDiagnostic) -> RenderWarning:
+    """Convert a query validator diagnostic into a RenderWarning.
+
+    The query name is woven into the message; ``detail`` and ``evidence`` (which
+    carry table names and relationship info for fanout/join diagnostics) are
+    appended so context survives the lossy conversion.
+    """
+    render_code = _DIAGNOSTIC_CODE_TO_RENDER_CODE.get(diag.code)
+    if render_code is None:
+        raise ValueError(
+            f"No RenderWarning code mapped for QueryDiagnostic.code={diag.code!r}. "
+            f"Add an entry to _DIAGNOSTIC_CODE_TO_RENDER_CODE and a matching module "
+            f"under dataface.core.render.warnings."
+        )
+    parts = [f"Query '{query_name}': {diag.message}", diag.detail, *diag.evidence]
+    stripped = [p.removesuffix(".") for p in parts if p]
+    message = ". ".join(stripped)
+    if message and message[-1] not in "?!":
+        message += "."
+    return RenderWarning(code=render_code, message=message, fix=diag.recommendation)

dataface/core/render/warnings/missing_join_predicate.py

@@ -0,0 +1,13 @@
+"""Emitter: MISSING_JOIN_PREDICATE.
+
+Fires when query validation detects an implicit cross join or an explicit
+CROSS JOIN without a predicate. These almost always indicate a missing
+``ON`` clause and produce wildly fanned-out result sets.
+
+Emitted by ``dataface.core.compile.compiler.validate_compiled_queries`` via
+the query_validator's ``missing_join_predicate`` diagnostic.
+"""
+
+from __future__ import annotations
+
+CODE = "MISSING_JOIN_PREDICATE"

dataface/core/render/warnings/query_parse_error.py

@@ -0,0 +1,14 @@
+"""Emitter: QUERY_PARSE_ERROR.
+
+Fires when the query validator cannot parse a SQL query as a structured
+AST. The query may still execute against the warehouse — this warning
+surfaces that semantic validation (fanout, reaggregation) cannot run on
+unparseable SQL.
+
+Emitted by ``dataface.core.compile.compiler.validate_compiled_queries`` via
+the query_validator's ``parse_error`` diagnostic.
+"""
+
+from __future__ import annotations
+
+CODE = "QUERY_PARSE_ERROR"

dataface/core/render/warnings/query_returned_zero_rows.py

@@ -0,0 +1,42 @@
+"""Detector: QUERY_RETURNED_ZERO_ROWS.
+
+Fires on any chart whose query returned zero rows. An empty chart renders as a
+blank panel with axes — no signal to the viewer that the query returned nothing.
+Most common cause: a WHERE clause or date filter that excludes all data.
+
+Detection rule:
+  len(ctx.chart_results[chart_id]) == 0
+
+This detector intentionally does NOT gate on ctx.vega_specs. KPI, text, and
+markdown charts are omitted from vega_specs, but zero rows is still meaningful
+for them — e.g. a KPI with no data is a silent failure.
+"""
+
+from __future__ import annotations
+
+from dataface.core.render.warnings.base import RenderWarning, WarningContext
+
+CODE = "QUERY_RETURNED_ZERO_ROWS"
+
+
+def detect(ctx: WarningContext) -> list[RenderWarning]:
+    """Return one RenderWarning per chart whose query returned zero rows."""
+    warnings: list[RenderWarning] = []
+
+    for chart_id in ctx.face_spec.charts:
+        # Charts absent from chart_results failed to execute — not a zero-row result.
+        if chart_id not in ctx.chart_results:
+            continue
+
+        if len(ctx.chart_results[chart_id]) == 0:
+            warnings.append(
+                RenderWarning(
+                    code=CODE,
+                    chart=chart_id,
+                    field=None,
+                    message="Query returned zero rows.",
+                    fix="Check WHERE clause or date filter.",
+                )
+            )
+
+    return warnings

dataface/core/render/warnings/reaggregation.py

@@ -0,0 +1,14 @@
+"""Emitter: REAGGREGATION.
+
+Fires when query validation detects aggregation applied on top of an
+already-aggregated input (e.g. ``SUM(SUM(...))`` patterns or aggregation
+over a query result that itself aggregates). The result is usually not
+what the author intended.
+
+Emitted by ``dataface.core.compile.compiler.validate_compiled_queries`` via
+the query_validator's ``reaggregation`` diagnostic.
+"""
+
+from __future__ import annotations
+
+CODE = "REAGGREGATION"

dataface/core/render/warnings/registry.py

@@ -0,0 +1,45 @@
+"""Warning detector registry.
+
+DETECTORS is an explicit list of detector modules. Each module must expose:
+  CODE: str       — stable SCREAMING_SNAKE_CASE identifier for this warning.
+  detect(ctx: WarningContext) -> list[RenderWarning]
+
+Detector tasks append to DETECTORS as they land. Registered detectors run
+sequentially; per-detector exceptions are isolated so a single bad detector
+cannot abort the render pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import ModuleType
+
+import dataface.core.render.warnings.bar_color_1_to_1_with_x as bar_color_1_to_1_with_x
+import dataface.core.render.warnings.query_returned_zero_rows as query_returned_zero_rows
+import dataface.core.render.warnings.temporal_single_point as temporal_single_point
+import dataface.core.render.warnings.y_encoding_mostly_null as y_encoding_mostly_null
+from dataface.core.render.warnings.base import RenderWarning, WarningContext
+
+logger = logging.getLogger(__name__)
+
+DETECTORS: list[ModuleType] = [
+    bar_color_1_to_1_with_x,
+    query_returned_zero_rows,
+    temporal_single_point,
+    y_encoding_mostly_null,
+]
+
+
+def run_all(ctx: WarningContext) -> list[RenderWarning]:
+    """Run every registered detector and return the concatenated warnings.
+
+    A detector that raises must not abort the render — exceptions are caught
+    here, logged, and skipped.
+    """
+    results: list[RenderWarning] = []
+    for detector in DETECTORS:
+        try:
+            results.extend(detector.detect(ctx))
+        except Exception:  # noqa: BLE001 — detector failures must not break renders
+            logger.exception("Warning detector %r raised; skipping", detector)
+    return results

dataface/core/render/warnings/suppression.py

@@ -0,0 +1,46 @@
+"""Warning suppression: partition a list of RenderWarnings into active vs suppressed.
+
+Three ignore layers form a union — a warning is dropped if its code appears in ANY:
+  1. cli_codes: caller-provided set (e.g. --ignore-warning flags).
+  2. project_codes: global ignore list from dataface.yml `warnings.ignore`.
+  3. per_chart_codes: per-chart ignore map, keyed by chart id. Only warnings whose
+     `chart` field matches the chart id are suppressed (face-level warnings with
+     chart=None are never suppressed by per_chart_codes).
+"""
+
+from __future__ import annotations
+
+from dataface.core.render.warnings.base import RenderWarning
+
+
+def partition(
+    warnings: list[RenderWarning],
+    cli_codes: set[str],
+    project_codes: set[str],
+    per_chart_codes: dict[str, set[str]],
+) -> tuple[list[RenderWarning], list[RenderWarning]]:
+    """Partition warnings into (active, suppressed).
+
+    A warning is suppressed when its code is in cli_codes, project_codes, or
+    (warning.chart is not None AND code is in per_chart_codes[warning.chart]).
+
+    Args:
+        warnings: Full pre-suppression list from run_all().
+        cli_codes: Caller-supplied ignore set (CLI --ignore-warning flags).
+        project_codes: Project-global ignore set from dataface.yml.
+        per_chart_codes: Chart-id → set of codes to suppress for that chart only.
+
+    Returns:
+        (active, suppressed) — both lists preserve original order.
+    """
+    active: list[RenderWarning] = []
+    suppressed: list[RenderWarning] = []
+    global_codes = cli_codes | project_codes
+    for w in warnings:
+        if w.code in global_codes or (
+            w.chart is not None and w.code in per_chart_codes.get(w.chart, set())
+        ):
+            suppressed.append(w)
+        else:
+            active.append(w)
+    return active, suppressed

dataface/core/render/warnings/temporal_single_point.py

@@ -0,0 +1,63 @@
+"""Detector: TEMPORAL_SINGLE_POINT.
+
+Fires on line and area charts where the x-axis is temporal and the query
+result has exactly one row. A one-point line is rendered as a single dot;
+a one-point area is a vertical line. Both render but convey nothing about a
+trend — this almost always means the date filter is too narrow.
+
+Detection rule:
+  chart.type in {"line", "area"}
+  AND ctx.vega_specs[chart_id].encoding.x.type == "temporal"
+  AND len(ctx.chart_results[chart_id]) == 1
+"""
+
+from __future__ import annotations
+
+from dataface.core.render.warnings.base import RenderWarning, WarningContext
+
+CODE = "TEMPORAL_SINGLE_POINT"
+
+# Chart types where a single temporal data point is misleading.
+_TEMPORAL_LINE_TYPES = frozenset({"line", "area"})
+
+
+def detect(ctx: WarningContext) -> list[RenderWarning]:
+    """Return one RenderWarning per line/area chart with a single temporal data point."""
+    warnings: list[RenderWarning] = []
+
+    for chart_id, chart in ctx.face_spec.charts.items():
+        if chart.type not in _TEMPORAL_LINE_TYPES:
+            continue
+        # Respect the sparse vega_specs contract — non-Vega charts are omitted.
+        if chart_id not in ctx.vega_specs:
+            continue
+        # Orphan charts (query not in pre_executed_query_names) are absent from chart_results.
+        if chart_id not in ctx.chart_results:
+            continue
+
+        vega_x_type: str = (
+            ctx.vega_specs[chart_id].get("encoding", {}).get("x", {}).get("type", "")
+        )
+        if vega_x_type != "temporal":
+            continue
+
+        if len(ctx.chart_results[chart_id]) != 1:
+            continue
+
+        warnings.append(
+            RenderWarning(
+                code=CODE,
+                chart=chart_id,
+                field=chart.x,
+                message=(
+                    f"Chart '{chart_id}' has only one data point on a temporal x-axis; "
+                    f"a single-point {chart.type} communicates no trend."
+                ),
+                fix=(
+                    "Broaden the time range to include more data points, "
+                    "or switch to a chart type better suited to a single value (e.g. kpi)."
+                ),
+            )
+        )
+
+    return warnings

dataface/core/render/warnings/unreferenced_chart.py

@@ -0,0 +1,15 @@
+"""Emitter: UNREFERENCED_CHART.
+
+Fires at compile time for charts that are defined somewhere in the face tree
+but never placed in any layout (rows/cols/grid/tabs). The face still compiles
+because content-only faces are valid; this warning surfaces lazy authoring —
+an author defined a chart and forgot to display it.
+
+Emitted by ``dataface.core.compile.compiler._collect_orphan_charts`` (not by
+the render-time detector registry). Lives next to the render-time detectors
+so every stable warning code has one home.
+"""
+
+from __future__ import annotations
+
+CODE = "UNREFERENCED_CHART"