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

dataface/core/compile/validator.py

@@ -32,19 +32,80 @@ See also:
     - compile/normalizer.py: Next step
 """
 
+import re
 from collections.abc import Mapping
 from typing import Any
 
 from dataface.core.compile.errors import ValidationError
 from dataface.core.compile.models.chart.authored import (
+    AuthoredChart,
     CalloutChart,
     _BaseChartFields,
 )
-from dataface.core.compile.models.face.authored import AuthoredFace
+from dataface.core.compile.models.face.authored import (
+    AuthoredFace,
+    TabItem,
+)
 from dataface.core.compile.models.query.authored import _BaseQueryFields
 from dataface.core.compile.models.refs import ChartRef, QueryRef
 from dataface.core.compile.parser import looks_like_sql
-from dataface.core.diagnostics.codes_compile import ERR_UNKNOWN_QUERY
+from dataface.core.diagnostics.codes_compile import (
+    ERR_UNKNOWN_QUERY,
+    ERR_UNRESOLVED_REFERENCE,
+)
+
+LayoutNode = str | AuthoredFace | AuthoredChart | TabItem | dict[str, AuthoredChart]
+
+
+_DOTTED_INDEX = re.compile(r"\.(\d+)(?=\.|$)")
+
+
+def _display_location(location: str) -> str:
+    """A layout location in the click-to-source spelling, for prose.
+
+    Two vocabularies exist and neither is going away: the source map keys
+    sequences by dotted index (`rows.0`), while `LayoutItem.source_path` and
+    Cloud's path parser use brackets (`rows[0]`). Locations are carried in the
+    source-map spelling because that is what has to resolve; this converts at
+    the one boundary where a human reads the value.
+    """
+    return _DOTTED_INDEX.sub(r"[\1]", location)
+
+
+def _layout_children(node: LayoutNode) -> list[LayoutNode]:
+    """Direct layout children of a face or tab node."""
+    if not isinstance(node, (AuthoredFace, TabItem)):
+        return []
+    children: list[LayoutNode] = []
+    if node.rows:
+        children.extend(node.rows)
+    if node.cols:
+        children.extend(node.cols)
+    if node.grid:
+        children.extend(gi.item for gi in node.grid.items)
+    if node.tabs:
+        children.extend(node.tabs.items)
+    return children
+
+
+def _declared_names(face: AuthoredFace) -> tuple[set[str], set[str]]:
+    """Chart and query names declared anywhere in the face tree.
+
+    The compiler's chart and query registries are board-global — any layout
+    may reference any chart declared anywhere in the tree — so validation has
+    to resolve against that same namespace. Resolving against only the top
+    level reports valid cross-face authoring as an unresolved reference.
+    """
+    charts: set[str] = set()
+    queries: set[str] = set()
+    stack: list[LayoutNode] = [face]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, AuthoredFace):
+            charts |= set(node.charts or {})
+            queries |= set(node.queries or {})
+        stack.extend(_layout_children(node))
+    return charts, queries
 
 
 def validate_face(face: AuthoredFace) -> list[ValidationError]:
@@ -74,9 +135,8 @@ def validate_face(face: AuthoredFace) -> list[ValidationError]:
     """
     errors: list[ValidationError] = []
 
-    # Collect available names
-    query_names = set((face.queries or {}).keys())
-    chart_names = set((face.charts or {}).keys())
+    # Board-global, matching the registries the compiler resolves against.
+    chart_names, query_names = _declared_names(face)
 
     # Validate chart → query references
     errors.extend(_validate_chart_query_references(face.charts or {}, query_names))
@@ -173,11 +233,16 @@ def _validate_layout_references(
                 continue
 
             if item not in chart_names:
-                errors.append(
-                    ValidationError(
-                        f"Layout references unknown chart '{item}'", location=location
-                    )
+                error = ValidationError.from_code(
+                    ERR_UNRESOLVED_REFERENCE, ref=item, context=" in layout item"
                 )
+                # `{context}` is a pre-formatted message suffix, but `fields`
+                # is the machine-readable surface — store the bare value, so
+                # this agrees with the `ReferenceError` site that raises the
+                # same code from the normalizer.
+                error.fields["context"] = "layout item"
+                error.field_path = location
+                errors.append(error)
 
         elif isinstance(item, (dict, _BaseChartFields)):
             # Inline chart - validate its query reference
@@ -199,13 +264,16 @@ def _validate_layout_references(
             if "." not in query_ref and query_ref not in query_names:
                 if looks_like_sql(query_ref):
                     continue
-                errors.append(
-                    ValidationError.from_code(
-                        ERR_UNKNOWN_QUERY,
-                        chart_name=location,
-                        query_name=query_ref,
-                    )
+                error = ValidationError.from_code(
+                    ERR_UNKNOWN_QUERY,
+                    chart_name=_display_location(location),
+                    query_name=query_ref,
                 )
+                # The offending value is the inline chart's `query:`, not the
+                # whole item — same precision as the named-chart site, which
+                # resolves to `charts.<id>.query`.
+                error.field_path = f"{location}.query"
+                errors.append(error)
 
     return errors
 
@@ -213,6 +281,12 @@ def _validate_layout_references(
 def _get_layout_items(face: AuthoredFace) -> list[tuple[str, Any]]:
     """Extract all layout items with their locations.
 
+    Locations are source-map keys: dotted all the way down, sequence indices
+    included (`rows.0`, `tabs.items.1.rows.0`). They are used both to resolve
+    a diagnostic's position and as the human-readable location in its message,
+    so there is one spelling rather than a display form and a lookup form that
+    can drift.
+
     Args:
         face: AuthoredFace to extract items from
 
@@ -223,26 +297,34 @@ def _get_layout_items(face: AuthoredFace) -> list[tuple[str, Any]]:
 
     if face.rows:
         for idx, item in enumerate(face.rows):
-            items.append((f"rows[{idx}]", item))
-            items.extend(_get_nested_items(item, f"rows[{idx}]"))
+            items.append((f"rows.{idx}", item))
+            items.extend(_get_nested_items(item, f"rows.{idx}"))
 
     if face.cols:
         for idx, item in enumerate(face.cols):
-            items.append((f"cols[{idx}]", item))
-            items.extend(_get_nested_items(item, f"cols[{idx}]"))
+            items.append((f"cols.{idx}", item))
+            items.extend(_get_nested_items(item, f"cols.{idx}"))
 
     if face.grid:
+        # `GridItem.item` is a nested field, so the authored scalar lives at
+        # `grid.items.<n>.item` — `grid.items.<n>` is the wrapper block.
         for idx, grid_item in enumerate(face.grid.items):
-            items.append((f"grid.items[{idx}]", grid_item.item))
+            location = f"grid.items.{idx}.item"
+            items.append((location, grid_item.item))
+            items.extend(_get_nested_items(grid_item.item, location))
 
     if face.tabs:
         for idx, tab_item in enumerate(face.tabs.items):
             if tab_item.rows:
                 for i, item in enumerate(tab_item.rows):
-                    items.append((f"tabs.items[{idx}].rows[{i}]", item))
+                    location = f"tabs.items.{idx}.rows.{i}"
+                    items.append((location, item))
+                    items.extend(_get_nested_items(item, location))
             if tab_item.cols:
                 for i, item in enumerate(tab_item.cols):
-                    items.append((f"tabs.items[{idx}].cols[{i}]", item))
+                    location = f"tabs.items.{idx}.cols.{i}"
+                    items.append((location, item))
+                    items.extend(_get_nested_items(item, location))
 
     return items
 
@@ -250,6 +332,13 @@ def _get_layout_items(face: AuthoredFace) -> list[tuple[str, Any]]:
 def _get_nested_items(item: Any, parent_location: str) -> list[tuple[str, Any]]:
     """Extract items from nested face structures.
 
+    A nested face reaches here as an `AuthoredFace`: the parser types layout
+    items, so matching `dict` would miss every nesting.
+
+    A nested face declaring its own `charts:` needs no special case — those
+    names are already in the board-global set `_declared_names` collects, so
+    its items resolve like any other.
+
     Args:
         item: Item that might be a nested face
         parent_location: Parent location string
@@ -257,29 +346,17 @@ def _get_nested_items(item: Any, parent_location: str) -> list[tuple[str, Any]]:
     Returns:
         List of (location, item) tuples from nested structures
     """
-    items: list[tuple[str, Any]] = []
-
-    if isinstance(item, dict):
-        # If nested face has its own charts, skip validation here -
-        # the nested face's layout items will reference its own charts,
-        # which will be validated during normalization
-        if "charts" in item:
-            return items
-
-        # Nested face without its own charts - extract its layout items
-        if "rows" in item:
-            for idx, nested in enumerate(item["rows"]):
-                items.append((f"{parent_location}.rows[{idx}]", nested))
-                items.extend(
-                    _get_nested_items(nested, f"{parent_location}.rows[{idx}]")
-                )
-        if "cols" in item:
-            for idx, nested in enumerate(item["cols"]):
-                items.append((f"{parent_location}.cols[{idx}]", nested))
-                items.extend(
-                    _get_nested_items(nested, f"{parent_location}.cols[{idx}]")
-                )
+    if not isinstance(item, AuthoredFace):
+        return []
 
+    items: list[tuple[str, Any]] = []
+    for key, entries in (("rows", item.rows), ("cols", item.cols)):
+        if entries is None:
+            continue
+        for idx, entry in enumerate(entries):
+            location = f"{parent_location}.{key}.{idx}"
+            items.append((location, entry))
+            items.extend(_get_nested_items(entry, location))
     return items
 
 

dataface/core/compile/yaml_error_formatter.py

@@ -10,6 +10,7 @@ Refs #94
 """
 
 import difflib
+import re
 from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import lru_cache
@@ -62,7 +63,6 @@ _PRIMITIVE_TYPE_DISCRIMINATORS = {"str", "int", "float", "bool", "bytes", "None"
 
 # Names of our known union-branch model types (not real YAML fields)
 _MODEL_TYPE_DISCRIMINATORS = {
-    "ForeachItem",
     "ChartPatch",
     "AuthoredFace",
     "Variable",
@@ -116,7 +116,7 @@ def _collapse_union_validation_errors(
     """Collapse Pydantic union-branch noise into the most informative errors.
 
     Pydantic tries every branch of a union type annotation (str | AuthoredFace
-    | ChartPatch | ForeachItem | dict[str,ChartPatch]) for each
+    | ChartPatch | dict[str,ChartPatch]) for each
     layout row. A single invalid row can produce 14+ error dicts — one per
     (branch × wrong-field) combination. This function keeps only the errors
     from the best-matching branch per unique loc prefix.
@@ -716,6 +716,95 @@ def format_validation_errors_structured(
     return structured
 
 
+_SHAPE_NOUN_SEPARATORS = re.compile(r"[\s_-]+")
+
+
+def _normalize_shape_noun(value: str) -> str:
+    """Fold the spellings of one shape noun together.
+
+    Authors reach for `streamgraph`, `stream_graph`, and `Stream Graph` for the same
+    chart, so separators are dropped rather than unified — otherwise every entry below
+    would need a row per punctuation variant.
+    """
+    return _SHAPE_NOUN_SEPARATORS.sub("", value.strip().lower())
+
+
+# Chart shapes the world names that Dataface draws by composing existing fields
+# rather than by a `type:` tag. The value spells the recipe out: an author who
+# reached this error already looked for the noun and did not find it, so a bare
+# pointer to the docs repeats the failure. Every entry is pinned by a spec
+# assertion in tests/core/test_chart_shape_recipes.py.
+_CHART_SHAPE_RECIPES = {
+    "streamgraph": "type: area with color: and style.stack: center",
+    "stacked_area": "type: area with color: and style.stack: zero",
+    "stacked_bar": "type: bar with color: and style.stack: zero",
+    "grouped_bar": "type: bar with color: and style.stack: none",
+    "clustered_bar": "type: bar with color: and style.stack: none",
+    "horizontal_bar": "type: bar with style.orientation: horizontal",
+    "column": "type: bar with style.orientation: vertical",
+    "100% stacked": "type: bar or type: area with color: and style.stack: normalize",
+    "percent_stacked_bar": "type: bar with color: and style.stack: normalize",
+    "normalized_bar": "type: bar with color: and style.stack: normalize",
+    "small_multiples": "multiples.rows: <column> (or multiples.columns:) on a cartesian chart",
+    "trellis": "multiples.rows: <column> (or multiples.columns:) on a cartesian chart",
+    "faceted": "multiples.rows: <column> (or multiples.columns:) on a cartesian chart",
+    "dual_axis": (
+        "layers: on a cartesian chart, with axis_y.position: right on the "
+        "added layer for its own y-axis"
+    ),
+    "combo": (
+        "layers: on a cartesian chart, with axis_y.position: right on the "
+        "added layer for its own y-axis"
+    ),
+    "bar_and_line": (
+        "layers: on a cartesian chart, with axis_y.position: right on the "
+        "added layer for its own y-axis"
+    ),
+    # The _column nouns promise a vertical layout, which orientation inference
+    # doesn't guarantee for a categorical x — style.orientation: vertical is
+    # explicit here, unlike the plain _bar recipes above.
+    "stacked_column": "type: bar with style.orientation: vertical, color:, and style.stack: zero",
+    "grouped_column": "type: bar with style.orientation: vertical, color:, and style.stack: none",
+    "clustered_column": "type: bar with style.orientation: vertical, color:, and style.stack: none",
+    "row_chart": "type: bar with style.orientation: horizontal",
+    "vertical_bar": "type: bar with style.orientation: vertical",
+    "stream_chart": "type: area with color: and style.stack: center",
+}
+
+# Shapes Dataface cannot draw at all. Naming them is the half a recipe cannot
+# cover: without it an author settles for the nearest tag, which validates clean
+# and renders the wrong chart.
+_UNSUPPORTED_CHART_SHAPES = frozenset(
+    {
+        "sankey",
+        "treemap",
+        "violin",
+        "waterfall",
+        "funnel",
+        "gauge",
+        "radar",
+        "sunburst",
+        "chord",
+        "marimekko",
+        "spider",
+        "alluvial",
+        "gantt",
+        "word cloud",
+        "network",
+        "candlestick",
+    }
+)
+
+# Both tables are keyed for reading; lookups go through the normalized forms so a
+# noun is spelled once at the source of truth.
+_RECIPE_BY_NORMALIZED_NOUN = {
+    _normalize_shape_noun(noun): recipe for noun, recipe in _CHART_SHAPE_RECIPES.items()
+}
+_NORMALIZED_UNSUPPORTED_SHAPES = frozenset(
+    _normalize_shape_noun(noun) for noun in _UNSUPPORTED_CHART_SHAPES
+)
+
+
 def _format_chart_type_discriminator_error(
     err: dict[str, Any],
     field_path: list[str],
@@ -735,6 +824,22 @@ def _format_chart_type_discriminator_error(
     if not isinstance(invalid_type, str):
         return f"Missing required field 'type'. Supported chart types: {supported}."
 
+    # A known shape noun beats a fuzzy tag guess: both branches below answer the
+    # question the author actually asked, so neither falls through to "did you mean".
+    normalized = _normalize_shape_noun(invalid_type)
+    recipe = _RECIPE_BY_NORMALIZED_NOUN.get(normalized)
+    if recipe:
+        return (
+            f"Unknown chart type {invalid_type!r}. Dataface draws that shape as "
+            f"{recipe}. Run `dft docs charts` for the chart reference. "
+            f"Supported chart types: {supported}."
+        )
+    if normalized in _NORMALIZED_UNSUPPORTED_SHAPES:
+        return (
+            f"Unknown chart type {invalid_type!r}. Dataface cannot draw that shape "
+            f"today. Supported chart types: {supported}."
+        )
+
     suggestion = suggest_similar_value(invalid_type, valid_chart_types)
     if suggestion:
         return (

dataface/core/dashboard.py

@@ -27,7 +27,7 @@ from typing import Any, Literal, get_args
 
 _logger = logging.getLogger(__name__)
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 from dataface.core.compile import (
     CompileResult,
@@ -94,6 +94,8 @@ RenderStatus = Literal["ok", "partial", "failed"]
 
 
 class RenderedDashboard(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
     status: RenderStatus
     # bytes for binary formats (png/pdf); str for text-based; dict for json.
     # MCP callers should not request binary formats — `model_dump_json()` /

dataface/core/defaults/default_config.yml

@@ -76,6 +76,10 @@ cache:
 execution:
   max_workers: 8
   max_query_duration_seconds: 120
+  # Hard cap on matched files per glob pattern in file sources. Prevents
+  # runaway fan-out when a wildcard accidentally matches thousands of files.
+  # Override in dataface.yml under execution.max_glob_file_count.
+  max_glob_file_count: 1000
   dialect_aliases:
     sqlserver: tsql
     mssql: tsql

dataface/core/defaults/themes/_base.yaml

@@ -939,7 +939,6 @@ style:
     title_inline_band_bottom_pad: 24.0
     gap: 10.0
     label_position: inline
-    line_height: 24.0
     padding: 4.0
     container_height: 36.0
     container_padding: 8.0

dataface/core/defaults/themes/editorial.yaml

@@ -202,6 +202,9 @@ style:
       header:
         font:
           color: dft-grays.heading
+      row:
+        stripe:
+          color: dft-grays.surface-subtle   # subtle zebra (one scaffold stop off canvas)
   variables:
     # Variable-strip labels track the muted gray rather than the
     # cooler #666666 stark uses.

dataface/core/defaults/themes/stark.yaml

@@ -63,6 +63,7 @@ style:
           color: *color_ink
 
     legend:
+      visible: false               # direct-labeling by default (editorial posture)
       label:
         font:
           color: *color_ink
@@ -178,6 +179,13 @@ style:
     bar:
       endpoint_labels:
         visible: true
+      legend:
+        # A bar that direct-labels has this suppressed again by resolve. It is
+        # load-bearing for the bars that cannot — grouped, or stacked but
+        # disqualified by `multiples:`, a negative measure, or a series absent
+        # from the last column — which would otherwise carry no series key at
+        # all, since the theme hides legends globally.
+        visible: true
 
     pie:
       total:

dataface/core/diagnostics/__init__.py

@@ -48,6 +48,9 @@ from dataface.core.diagnostics.codes_compile import (
 from dataface.core.diagnostics.codes_execute import (
     ERR_BINDER_TYPE_MISMATCH,
     ERR_BINDER_UNKNOWN_COLUMN,
+    ERR_GLOB_EMPTY,
+    ERR_GLOB_SCHEMA_MISMATCH,
+    ERR_GLOB_TOO_MANY,
     ERR_MUTATING_SQL,
     ERR_NO_DEFAULT_SOURCE,
     ERR_QUERY_DURATION_EXCEEDED,
@@ -68,6 +71,7 @@ from dataface.core.diagnostics.codes_query import (
 )
 from dataface.core.diagnostics.codes_render import (
     ERR_BAR_DUPLICATE_ROWS,
+    ERR_CHART_PAINTED_NO_MARKS,
     ERR_CONCAT_OVERSHOOT_NONPOSITIVE,
     ERR_DUPLICATE_CHART_ID,
     ERR_EMITTER_NOT_FOUND,
@@ -88,6 +92,7 @@ from dataface.core.diagnostics.codes_render import (
     ERR_VEGA_LITE_UNSUPPORTED_TYPE,
     WARN_BAR_BAND_WIDTH_TOO_NARROW,
     WARN_LAYERED_CHART_SHARED_Y_AXIS_SCALE_MISMATCH,
+    WARN_LAYOUT_MIN_EXCEEDS_HEIGHT,
     WARN_LIKELY_CURRENCY_OR_PERCENT_MISSING_FORMATTER,
     WARN_PALETTE_UNSUPPORTED,
     WARN_PIE_DOMINANT_SEGMENT,
@@ -177,6 +182,9 @@ __all__ = [
     "WARN_H1_BODY_NO_TITLE",
     "WARN_SINGLE_CHART_REDUNDANT_TITLE",
     # Execute errors
+    "ERR_GLOB_EMPTY",
+    "ERR_GLOB_SCHEMA_MISMATCH",
+    "ERR_GLOB_TOO_MANY",
     "ERR_REPO_FILE_TOO_LARGE",
     "ERR_SOURCE_NOT_FOUND_EMPTY",
     "ERR_NO_DEFAULT_SOURCE",
@@ -197,6 +205,7 @@ __all__ = [
     # Render errors
     "ERR_KPI_MULTIROW",
     "ERR_BAR_DUPLICATE_ROWS",
+    "ERR_CHART_PAINTED_NO_MARKS",
     "ERR_MAP_LOOKUP_KEY_MISMATCH",
     "ERR_DUPLICATE_CHART_ID",
     "ERR_FORMAT_UNSUPPORTED",
@@ -218,6 +227,7 @@ __all__ = [
     # Render warnings
     "WARN_BAR_BAND_WIDTH_TOO_NARROW",
     "WARN_LAYERED_CHART_SHARED_Y_AXIS_SCALE_MISMATCH",
+    "WARN_LAYOUT_MIN_EXCEEDS_HEIGHT",
     "WARN_LIKELY_CURRENCY_OR_PERCENT_MISSING_FORMATTER",
     "WARN_PALETTE_UNSUPPORTED",
     "WARN_PIE_DOMINANT_SEGMENT",

dataface/core/diagnostics/codes_compile.py

@@ -359,12 +359,14 @@ ERR_BAR_LOG_SCALE_NOT_SUPPORTED = REGISTRY.register(
         message_template=(
             "Chart {chart_id!r} (bar): axis_y.scale.type: log is not "
             "supported — a bar's length encodes magnitude from zero, which a "
-            "log scale makes meaningless. Use line or area, or drop the log scale."
+            "log scale makes meaningless. Use scale.type: symlog on the bar "
+            "chart, or switch to a line or area chart for a log scale."
         ),
         doc=(
             "Fired when a bar chart's y axis is set to `scale.type: log`. A bar's "
             "length encodes magnitude from zero, which a log scale makes meaningless. "
-            "Use a line or area chart, or drop the log scale."
+            "Use `scale.type: symlog` on the bar chart, or switch to a line or area "
+            "chart for a log scale."
         ),
         summary="Fired when a bar chart's y-axis uses a log scale, which magnitude-from-zero bars can't represent.",
         docs_topic="charts",

dataface/core/diagnostics/codes_execute.py

@@ -11,6 +11,76 @@ from dataface.core.diagnostics.hints import (
 )
 from dataface.core.diagnostics.registry import REGISTRY, ErrorCode
 
+ERR_GLOB_EMPTY = REGISTRY.register(
+    ErrorCode(
+        code="ERR-GLOB-EMPTY",
+        domain="execute",
+        title="Glob pattern in file source matched no files",
+        message_template=(
+            "File source {source_name!r}, table {table_name!r}: "
+            "glob pattern {pattern!r} matched no files. "
+            "Provide at least one matching file or fix the pattern."
+        ),
+        doc=(
+            "Fired when a glob pattern in a file source's `files:` mapping expands "
+            "to zero files. Every glob must match at least one file — an empty match "
+            "is always a configuration error. Check the pattern for typos, verify the "
+            "files exist at the expected paths, and confirm the path is relative to "
+            "the project root."
+        ),
+        docs_topic="queries",
+    )
+)
+
+ERR_GLOB_TOO_MANY = REGISTRY.register(
+    ErrorCode(
+        code="ERR-GLOB-TOO-MANY",
+        domain="execute",
+        title="Glob pattern in file source exceeded the file-count cap",
+        message_template=(
+            "File source {source_name!r}, table {table_name!r}: "
+            "glob pattern {pattern!r} matched {count} files, "
+            "exceeding the {cap}-file cap. "
+            "Increase execution.max_glob_file_count in dataface.yml if needed."
+        ),
+        summary=(
+            "Fired when a glob pattern in a file source matches more files "
+            "than the configured cap."
+        ),
+        doc=(
+            "Fired when a glob pattern in a file source's `files:` mapping matches "
+            "more files than the configured `execution.max_glob_file_count` limit. "
+            "Narrow the pattern, or raise the cap in `dataface.yml` under "
+            "`execution: max_glob_file_count: <N>`."
+        ),
+        docs_topic="queries",
+    )
+)
+
+ERR_GLOB_SCHEMA_MISMATCH = REGISTRY.register(
+    ErrorCode(
+        code="ERR-GLOB-SCHEMA-MISMATCH",
+        domain="execute",
+        title="Glob-matched files have inconsistent column schemas",
+        message_template=(
+            "File source {source_name!r}, table {table_name!r}: "
+            "{path!r} has different columns than {first_path!r}. "
+            "{detail}"
+            "All files matched by a glob must share the same column schema."
+        ),
+        summary=(
+            "Fired when files matched by a glob pattern have different column sets."
+        ),
+        doc=(
+            "Fired when a glob pattern in a file source's `files:` mapping expands "
+            "to files with different column schemas. All matched files must share the "
+            "same column names. Align the column schemas across all files, or split "
+            "the source into separate entries with non-overlapping patterns."
+        ),
+        docs_topic="queries",
+    )
+)
+
 ERR_REPO_FILE_TOO_LARGE = REGISTRY.register(
     ErrorCode(
         code="ERR-REPO-FILE-TOO-LARGE",