dataface 0.3.2.dev22__py3-none-any.whl → 0.3.2.dev111__py3-none-any.whl

dataface/core/compile/compiler.py

@@ -86,7 +86,10 @@ from dataface.core.compile.normalize_charts import (
     collect_lookml_channel_refs,
     collect_metricflow_channel_refs,
 )
-from dataface.core.compile.normalize_queries import find_lookml_model_source
+from dataface.core.compile.normalize_queries import (
+    find_lookml_model_source,
+    split_external_query_ref,
+)
 from dataface.core.compile.normalize_variables import (
     VariableReferenceErrors,
     synthetic_query_name,
@@ -100,6 +103,7 @@ from dataface.core.compile.parser import (
 )
 from dataface.core.compile.source_map import (
     LiteralBlock,
+    build_container_paths,
     build_literal_blocks,
     build_source_map,
     stamp_diagnostics,
@@ -163,6 +167,12 @@ class CompileResult:
             diagnostics (chart-render errors, render warnings, query
             diagnostics) reuse this same map via ``stamp_diagnostics`` instead
             of each doing its own position resolution.
+        container_paths: Dotted paths addressing a mapping/sequence rather
+            than a scalar, built alongside ``source_map``. Lets the stamping
+            pass collapse a container's whole-body range to its key line, so a
+            diagnostic about a chart marks the line naming it instead of every
+            line inside. Carried on the result for the same reason as
+            ``sql_blocks``: render-side stamping reuses it without recompiling.
         sql_blocks: Dotted-path -> LiteralBlock for every literal (``|``)
             block scalar, built alongside ``source_map``. Render-side
             diagnostics pass this to ``stamp_diagnostics`` too, so a query
@@ -188,6 +198,7 @@ class CompileResult:
     meta_lint: MetaLintConfig | None = None
     source_map: dict[str, SourceRange] = field(default_factory=dict)
     sql_blocks: dict[str, LiteralBlock] = field(default_factory=dict)
+    container_paths: frozenset[str] = frozenset()
 
     @property
     def success(self) -> bool:
@@ -211,11 +222,13 @@ def _stamp_compile_result(
         return result
     source_map = build_source_map(yaml_content, file)
     sql_blocks = build_literal_blocks(yaml_content)
+    containers = build_container_paths(yaml_content)
     result.source_map = source_map
     result.sql_blocks = sql_blocks
-    stamp_diagnostics(result.errors, source_map, sql_blocks)
-    stamp_diagnostics(result.warnings, source_map, sql_blocks)
-    stamp_diagnostics(result.suppressed_warnings, source_map, sql_blocks)
+    result.container_paths = containers
+    stamp_diagnostics(result.errors, source_map, sql_blocks, containers)
+    stamp_diagnostics(result.warnings, source_map, sql_blocks, containers)
+    stamp_diagnostics(result.suppressed_warnings, source_map, sql_blocks, containers)
     return result
 
 
@@ -1523,20 +1536,53 @@ def pull_cross_face_query_chain(
 
 
 def _is_lexically_scoped_query_name(value: str) -> bool:
-    """True when a chart's `query:`/`layers[].query` string is a bare name
-    that should resolve against the source face's own `queries:` section,
-    rather than: inline SQL (self-contained), a `#`-external ref (separate,
-    pre-existing mechanism — resolving it correctly for imported charts is a
-    tracked follow-up, not this task), or a full `<file>.queries.<name>`
-    cross-file ref written directly on the chart itself (an already-
-    ambiguous, unrelated edge case for local charts too — left untouched).
+    """True when a chart's `query:`/`layers[].query` string must resolve
+    against the *source* face rather than the importer: a bare name declared
+    in the source face's own `queries:` section, or a `<file>#<name>`
+    external ref anchored at the source face's own directory. Excluded is
+    inline SQL (self-contained) and a full `<file>.queries.<name>` cross-file
+    ref written directly on the chart itself (an already-ambiguous, unrelated
+    edge case for local charts too — left untouched).
     """
     stripped = value.strip()
-    return (
-        "#" not in stripped
-        and ".queries." not in stripped
-        and not looks_like_sql(stripped)
-    )
+    return ".queries." not in stripped and not looks_like_sql(stripped)
+
+
+def _read_queries_section(
+    file_dir: ProjectDirectory, target_file_str: str, ref: str, chart_ref: str
+) -> tuple[ProjectPath, dict[str, YamlValue]]:
+    """The `queries:` section of `target_file_str`, resolved relative to
+    `file_dir` — the *declaring* file's own directory, never the importer's.
+
+    `ref` is the authored ref string this file part came from and `chart_ref`
+    the chart import that pulled it in; both are named in every failure, since
+    the author is looking at neither file when the resolution breaks.
+    """
+    where = f"Chart ref '{chart_ref}' requires '{ref}'"
+    try:
+        target_path = file_dir / target_file_str
+    except ValueError as e:
+        raise CompilationError(f"{where}: {e}") from e
+    if not target_path.exists():
+        raise CompilationError(
+            f"{where}, but {target_file_str} does not exist "
+            f"(resolved relative to {file_dir.relpath})."
+        )
+    try:
+        target_content = target_path.read_yaml()
+    except (OSError, yaml.YAMLError) as e:
+        raise CompilationError(f"{where}: failed to load {target_file_str}: {e}") from e
+    # read_yaml is -> Any: a file whose top level is a list or scalar parses
+    # fine and would only fail at the .get below, as an AttributeError escaping
+    # compile() rather than a diagnostic.
+    if target_content is not None and not isinstance(target_content, dict):
+        raise CompilationError(f"{where}, but {target_file_str} is not a YAML mapping.")
+    target_queries = target_content.get("queries") if target_content else None
+    if not isinstance(target_queries, dict):
+        raise CompilationError(
+            f"{where}, but {target_file_str} has no queries: section."
+        )
+    return target_path, target_queries
 
 
 def _resolve_cross_face_query(
@@ -1593,19 +1639,9 @@ def _resolve_cross_face_query(
         target_file_str, target_name = raw_def["ref"].rsplit(".queries.", 1)
         if not (target_file_str.endswith(".yml") or target_file_str.endswith(".yaml")):
             target_file_str += ".yml"
-        try:
-            target_path = file_dir / target_file_str
-        except ValueError as e:
-            raise CompilationError(str(e)) from e
-        if not target_path.exists():
-            raise CompilationError(f"Referenced file not found: {target_file_str}")
-        try:
-            target_content = target_path.read_yaml()
-        except (OSError, yaml.YAMLError) as e:
-            raise CompilationError(f"Failed to load {target_file_str}: {e}") from e
-        target_queries = target_content.get("queries") if target_content else None
-        if not isinstance(target_queries, dict):
-            raise CompilationError(f"No queries found in {target_file_str}")
+        target_path, target_queries = _read_queries_section(
+            file_dir, target_file_str, raw_def["ref"], chart_ref
+        )
         target_key = _resolve_cross_face_query(
             target_name,
             target_path.parent,
@@ -1713,12 +1749,39 @@ def _load_chart_ref_with_lexical_queries(
     key_cache: dict[tuple[str, str], str] = {}
     resolving: set[tuple[str, str]] = set()
 
-    def resolve_name(bare_name: str) -> str:
+    def resolve_name(name: str) -> str:
+        """A bare name resolves in the source face's own `queries:`; a
+        `<file>#<name>` external ref resolves in that file's, reached relative
+        to the source face's directory. Either way the resulting query lands
+        in `cross_face_queries` under a key qualified by the file it was
+        actually declared in — so an importer `#`-ref spelled identically to
+        the imported chart's, but pointing at a different file, stays its own
+        query.
+        """
+        stripped = name.strip()
+        if "#" not in stripped:
+            return _resolve_cross_face_query(
+                stripped,
+                file_dir,
+                file_relpath,
+                queries_section,
+                cross_face_queries,
+                key_cache,
+                resolving,
+                chart_ref.ref,
+                sources=sources,
+                cache_root=cache_root,
+                face_cache=face_cache,
+            )
+        target_file_str, target_name = split_external_query_ref(stripped)
+        target_path, target_queries = _read_queries_section(
+            file_dir, target_file_str, stripped, chart_ref.ref
+        )
         return _resolve_cross_face_query(
-            bare_name.strip(),
-            file_dir,
-            file_relpath,
-            queries_section,
+            target_name,
+            target_path.parent,
+            target_path.relpath,
+            target_queries,
             cross_face_queries,
             key_cache,
             resolving,

dataface/core/compile/data_table.py

@@ -53,11 +53,16 @@ def axis_offset(charts_style: ResolvedChartsStyle, style: DataTableStyle) -> flo
     # Visibility is read from the fully-merged cascade (includes Layer-6 authored-
     # label flips) so both label and title heights reflect the actual rendered state.
     merged = resolved_axis_style(charts_style, "axis_x", "band")
+    # labels.padding is always required by build_resolved_axis (the shared
+    # ResolvedAxisElementStyle dataclass types it Optional only to let title
+    # leave it unset — see AxisTitleStyle).
+    assert merged.labels.padding is not None, "axis_x.labels.padding unset"
     label_h = (
-        merged.label.padding + merged.label.font.size * style.label_max_lines
-        if merged.label.visible is not False and merged.label.font.size > 0
+        merged.labels.padding + merged.labels.font.size * style.label_max_lines
+        if merged.labels.visible is not False and merged.labels.font.size > 0
         else 0.0
     )
+    assert merged.title.padding is not None, "axis_x.title.padding unset"
     title_h = (
         merged.title.padding + merged.title.font.size
         if merged.title.visible is not False and merged.title.font.size > 0

dataface/core/compile/enrich.py

@@ -13,9 +13,9 @@ Pipeline position:
 Key principle: every auto-decision is overridable by explicit YAML.
 If the user sets scale/fields, those win over any auto-detection.
 
-Format defaults come from the theme cascade (axis_quantitative.format in _base.yaml,
+Format defaults come from the theme cascade (axis_quantitative.labels.format in _base.yaml,
 which references the number_default alias → .3~s), not from column-name inference.
-Authors override per-chart via chart.format or style.axis_y.format.
+Authors override per-chart via chart.format or style.axis_y.labels.format.
 
 Note on database driver compatibility:
     The type_code mapping in db_type_to_dtype works for DuckDB (which uses
@@ -33,6 +33,7 @@ from decimal import Decimal
 from typing import Any
 
 from dataface.core.compile.models.chart.normalized import Chart, _CartesianChartFields
+from dataface.core.utils import is_year_shaped
 
 # Chart types that use x/y axes (not KPI, table, pie)
 _AXIS_CHART_TYPES = frozenset({"bar", "line", "area", "scatter", "heatmap"})
@@ -137,8 +138,8 @@ def enrich_chart(
        fall back to value-based heuristics)
     3. User YAML annotations (always win — never overridden)
 
-    Format defaults come from the theme cascade (axis_quantitative.format) —
-    not from inference here. Authors override via chart.format or style.axis_y.format.
+    Format defaults come from the theme cascade (axis_quantitative.labels.format) —
+    not from inference here. Authors override via chart.format or style.axis_y.labels.format.
     """
     if not data:
         return chart
@@ -282,41 +283,6 @@ def classify_column_type(
     return "categorical"
 
 
-_YEAR_MIN = 1900
-_YEAR_MAX = 2100
-_YEAR_STRING_PATTERN = re.compile(r"^\d{4}$")
-
-
-def is_year_shaped(samples: list[Any]) -> bool:
-    """True iff every non-null sample is a year-range value.
-
-    Value-only heuristic (no column-name signal): an ``int`` in
-    ``[1900, 2100]``, a ``str`` matching ``^\\d{4}$`` in that range, or an
-    integral ``Decimal`` (``v == v.to_integral_value()``) in range — warehouses
-    (BigQuery NUMERIC, Snowflake NUMBER) return year integers as ``Decimal``.
-    A non-integral ``Decimal`` (e.g. ``2024.5``) is not a year. ``bool`` and
-    ``float`` are excluded — bool is never a year, and float years don't occur
-    in practice. Empty input is not year-shaped.
-    """
-    if not samples:
-        return False
-    for v in samples:
-        if isinstance(v, bool):
-            return False
-        if isinstance(v, int):
-            if not (_YEAR_MIN <= v <= _YEAR_MAX):
-                return False
-        elif isinstance(v, Decimal):
-            if v != v.to_integral_value() or not (_YEAR_MIN <= v <= _YEAR_MAX):
-                return False
-        elif isinstance(v, str) and _YEAR_STRING_PATTERN.match(v):
-            if not (_YEAR_MIN <= int(v) <= _YEAR_MAX):
-                return False
-        else:
-            return False
-    return True
-
-
 def is_column_discrete_for_bar_orientation(
     samples: list[int | float | Decimal | str | bool | date | datetime],
 ) -> bool:
@@ -470,7 +436,7 @@ def _pick_axis_style(
 ) -> dict[str, Any]:
     """Pick y-axis scale style updates.
 
-    Format defaults come from the theme cascade (axis_quantitative.format in _base.yaml).
+    Format defaults come from the theme cascade (axis_quantitative.labels.format in _base.yaml).
     This function only handles the zero-baseline heuristic.
 
     Returns flat dict with a ``scale`` key when a scale override is needed — the caller
@@ -489,11 +455,17 @@ def _pick_axis_style(
     )
 
     # "auto" means "run the picker" — not a pinned value, so treat as absent.
+    _existing_scale_cont = (
+        existing_scale.continuous if existing_scale is not None else None
+    )
+    _existing_ay_scale_cont = (
+        existing_axis_y_scale.continuous if existing_axis_y_scale is not None else None
+    )
     has_zero = (
-        existing_scale is not None and isinstance(existing_scale.zero, bool)
+        _existing_scale_cont is not None and isinstance(_existing_scale_cont.zero, bool)
     ) or (
-        existing_axis_y_scale is not None
-        and isinstance(existing_axis_y_scale.zero, bool)
+        _existing_ay_scale_cont is not None
+        and isinstance(_existing_ay_scale_cont.zero, bool)
     )
     if not has_zero:
         scale = _pick_scale(y_profile, chart_type=chart.type)
@@ -501,7 +473,9 @@ def _pick_axis_style(
             scale_data = (
                 existing_scale.model_dump(exclude_none=True) if existing_scale else {}
             )
-            scale_data.update(scale)
+            # zero is nested under continuous; merge to preserve any existing continuous fields
+            existing_continuous = scale_data.get("continuous", {})
+            scale_data["continuous"] = {**existing_continuous, **scale}
             updates["scale"] = scale_data
 
     return updates

dataface/core/compile/face_warnings.py

@@ -16,6 +16,7 @@ from dataface.core.diagnostics import (
     WARN_SINGLE_CHART_REDUNDANT_TITLE,
     WARN_UNREFERENCED_CHART,
     Diagnostic,
+    RelatedLocation,
 )
 
 
@@ -45,7 +46,15 @@ def _detect_double_headers(face: Face, warnings: list[Diagnostic]) -> None:
     heading = _body_opening_heading(face)
     if heading is None:
         return
-    level, text = heading
+    level, text, heading_line = heading
+    # Prose reaching here from a layout slot came through a normalized nested
+    # face, which no longer carries the authored path it was written at — only
+    # the face's own `text:` can be marked inside.
+    body_is_own_text = bool(face.text)
+    # The heading line, verbatim, lets stamping narrow a `text:` block range
+    # down to just it. Reconstructing it from `level` + `text` would guess wrong
+    # on `#   Sales` and on setext headings.
+    needle = {"source_needle": heading_line}
     if not face.title:
         # No title to compare a lower-level heading against — only a literal
         # level 1 stands in for a missing document title.
@@ -55,6 +64,7 @@ def _detect_double_headers(face: Face, warnings: list[Diagnostic]) -> None:
             Diagnostic.from_code(
                 WARN_H1_BODY_NO_TITLE,
                 path="text",
+                fields=needle,
                 message=WARN_H1_BODY_NO_TITLE.message_template.format(heading=text),
                 fix=WARN_H1_BODY_NO_TITLE.fix_template.format(heading=text),
             )
@@ -65,12 +75,29 @@ def _detect_double_headers(face: Face, warnings: list[Diagnostic]) -> None:
     # the title is; `## Overview` under `title: Sales` is section structure.
     if level != 1 and _comparable(text) != _comparable(face.title):
         return
+    # The heading is the line to delete, so it gets the mark; `title:` is the
+    # other half of the pair and rides along as a related location. When the
+    # prose lives in a layout slot rather than the face's own `text:`, the body
+    # path is not recoverable from the normalized tree, so the two swap roles
+    # and `title:` carries the mark — still one line, never the whole face.
+    related: tuple[RelatedLocation, ...]
+    if body_is_own_text:
+        path = "text"
+        related = (
+            RelatedLocation(
+                path="title",
+                message=f"the face title {face.title!r} already heads the board",
+            ),
+        )
+    else:
+        path = "title"
+        related = ()
     warnings.append(
         Diagnostic.from_code(
             WARN_DOUBLE_HEADER,
-            # Dotted authoring path, not the face id — this is the source-map key
-            # that gives the diagnostic its editor position.
-            path="title",
+            path=path,
+            related=related,
+            fields=needle,
             message=WARN_DOUBLE_HEADER.message_template.format(
                 title=face.title, level=level, heading=text
             ),
@@ -79,17 +106,27 @@ def _detect_double_headers(face: Face, warnings: list[Diagnostic]) -> None:
     )
 
 
-def _body_opening_heading(face: Face) -> tuple[int, str] | None:
-    """Return (level, text) when the face's body opens with a markdown heading.
+def _body_opening_heading(face: Face) -> tuple[int, str, str] | None:
+    """Return (level, text, heading_line) for a body that opens with a markdown
+    heading.
 
     The body is either the face's own ``text`` (text-only face) or, for a face
     with a layout, a bare text block in the first slot — the two ways prose lands
     directly under the board header.
+
+    ``heading_line`` is the body's first non-blank line — the heading exactly as
+    authored, whatever its spacing or style — so stamping can narrow a ``text:``
+    block range down to it.
     """
     first = next(iter(face.layout.items), None)
-    body = face.text or (_bare_text_block_body(first) if first is not None else None)
+    own_text = face.text
+    body = own_text or (_bare_text_block_body(first) if first is not None else None)
     if not body:
         return None
+    heading_line = next(
+        (line for line in body.splitlines() if line.strip()),
+        "",
+    )
 
     # mdsvg is the parser that renders face text, so asking it what a heading is
     # keeps the warning from firing on something that renders as prose (a fenced
@@ -100,7 +137,8 @@ def _body_opening_heading(face: Face) -> tuple[int, str] | None:
     first_block = next(iter(blocks), None)
     if not isinstance(first_block, Heading):
         return None
-    return first_block.level, "".join(span.text for span in first_block.spans)
+    text = "".join(span.text for span in first_block.spans)
+    return first_block.level, text, heading_line
 
 
 def _bare_text_block_body(item: LayoutItem) -> str | None:

dataface/core/compile/format.py

@@ -1,8 +1,11 @@
-"""Format-alias resolution — a compile-layer concern.
+"""Format resolution and finalization — a compile-layer concern.
 
 Resolving a face/theme format alias to a concrete d3 spec is part of the style
 cascade, so it lives in the compile layer where the cascade is baked. The render
 layer's d3 formatters (format_utils.py) import ``resolve_format`` from here.
+This module also owns ``finalize_kpi_value_format()``, the KPI headline's
+data-aware format defaulting rule — baked into ``ResolvedKpiChart.format`` at
+resolve, consumed as-is by render.
 """
 
 from __future__ import annotations
@@ -60,3 +63,46 @@ def resolve_format(
 
     # Raw d3 passthrough — let d3 parse or raise
     return format_str
+
+
+# d3's first SI prefix ("k") engages at 1000. Below it, ".2s" doesn't compact —
+# it rounds to 2 significant figures on plain digits instead (131 -> "130"),
+# which drops information the author never asked to lose. Digit-integrity
+# rule: rounding is acceptable under SI compaction, never on plain digits —
+# so the default only compacts once compaction is real.
+_KPI_SI_COMPACT_THRESHOLD = 1000.0
+
+
+def finalize_kpi_value_format(
+    format_input: str | FormatConfig | None,
+    value: float | None,
+) -> FormatConfig | None:
+    """Finalize the KPI headline's number format from its cascaded style and value.
+
+    KPI is a hero number that the reader pauses on, so it defaults to the
+    narrative notation register (``1.5mn``) instead of the analytic register
+    (``1.5 M``) used on axis ticks and table cells. When neither spec nor
+    notation is authored, and ``value`` is large enough to actually compact
+    (``|value| >= 1000``), it also defaults to compact SI form (``".2s"``) so
+    narrative notation shows up — notation alone is a no-op against a non-SI
+    spec. Below that threshold there is nothing to compact, so the value
+    renders its exact digits (no spec at all) rather than a misleadingly
+    rounded plain number. An explicit spec always wins over the SI default.
+    """
+    compact_eligible = value is not None and abs(value) >= _KPI_SI_COMPACT_THRESHOLD
+    if isinstance(format_input, str):
+        return FormatConfig(spec=format_input, notation="narrative")
+    spec = format_input.spec if format_input is not None else None
+    notation = format_input.notation if format_input is not None else None
+    if notation is None:
+        notation = "narrative"
+    if spec is None and notation in ("narrative", "analytic") and compact_eligible:
+        spec = ".2s"
+    if format_input is None and spec is None:
+        return None
+    return FormatConfig(
+        spec=spec,
+        prefix=format_input.prefix if format_input is not None else None,
+        suffix=format_input.suffix if format_input is not None else None,
+        notation=notation,
+    )

dataface/core/compile/inherit_graph.py

@@ -3,10 +3,10 @@
 Usage::
 
     links = build_inherit_graph(Style)
-    # {"Style.charts.axis_x.label.font.color": "Style.charts.axis.label.font.color", ...}
+    # {"Style.charts.axis_x.labels.font.color": "Style.charts.axis.labels.font.color", ...}
 
     chains = flatten_inherit_chains(links)
-    # {"Style.charts.axis_x.label.font.color": ("Style.charts.axis.label.font.color",), ...}
+    # {"Style.charts.axis_x.labels.font.color": ("Style.charts.axis.labels.font.color",), ...}
 
 Production entry point::
 
@@ -166,7 +166,7 @@ def _build_graph(
                     # Already inside an outer slot expansion.  The inner InheritSlot
                     # applies at the canonical source path, not at this derived-axis
                     # path.  Preserve the outer slot so leaves still expand as
-                    # axis_x.label.font.color → axis.label.font.color rather than
+                    # axis_x.labels.font.color → axis.labels.font.color rather than
                     # jumping directly to charts.font.color.
                     _build_graph(
                         nested,

dataface/core/compile/inherit_registry.yaml

@@ -20,7 +20,7 @@ Style.charts.area.padding:
 - Style.charts.padding
 Style.charts.area.preferred_width:
 - Style.charts.preferred_width
-Style.charts.axis.label.font:
+Style.charts.axis.labels.font:
 - Style.charts.font
 - Style.font
 Style.charts.axis.title.font: