dataface 0.1.2__py3-none-any.whl

dataface/core/compile/yaml_error_formatter.py

@@ -0,0 +1,838 @@
+"""Enhanced YAML error formatting.
+
+This module provides utilities to format YAML validation errors with:
+1. Line numbers where errors occur
+2. Context - the actual YAML snippet
+3. Helpful suggestions ("Did you mean?")
+4. Graceful handling of common mistakes
+
+Refs #94
+"""
+
+import difflib
+import re
+from collections.abc import Sequence
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, get_args
+
+if TYPE_CHECKING:
+    from dataface.core.errors.structured import StructuredError
+
+# Union-branch discriminator patterns: strings in Pydantic loc tuples that
+# identify which branch of a union was being tried, not a real field name.
+# These are NOT real YAML keys — they are Pydantic-internal identifiers.
+_UNION_DISCRIMINATOR_PREFIXES = (
+    "function-after[",
+    "function-before[",
+    "function-wrap[",
+    "function-plain[",
+    "dict[",
+    "list[",
+    "tagged-union[",
+    "union[",
+)
+
+# Branch names that are literal Pydantic type names (not real YAML fields)
+_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",
+    "VariableRef",
+    "QueryRef",
+    "ChartRef",
+}
+
+
+def _is_union_discriminator(part: Any) -> bool:
+    """Return True when a loc element is a Pydantic union-branch label, not a YAML key."""
+    if not isinstance(part, str):
+        return False
+    if part in _PRIMITIVE_TYPE_DISCRIMINATORS:
+        return True
+    if part in _MODEL_TYPE_DISCRIMINATORS:
+        return True
+    # Functional discriminator tags (authored.py) use '@' prefix to prevent collision
+    # with user-chosen YAML keys ('ref', 'inline', etc.).
+    if part.startswith("@"):
+        return True
+    return any(part.startswith(pfx) for pfx in _UNION_DISCRIMINATOR_PREFIXES)
+
+
+def _find_discriminator_index(loc: tuple[Any, ...]) -> int | None:
+    """Return the index of the union-branch discriminator in loc, or None."""
+    for i, part in enumerate(loc):
+        if _is_union_discriminator(part):
+            return i
+    return None
+
+
+def _branch_score(err: dict[str, Any]) -> int:
+    """Score a branch error — lower is better (more informative).
+
+    extra_forbidden → field we actually authored that's forbidden here → 0 (best)
+    missing         → required field for this branch missing → 1
+    other           → some other type mismatch → 2 (noisier)
+    """
+    t = err.get("type", "")
+    if t == "extra_forbidden":
+        return 0
+    if t == "missing":
+        return 1
+    return 2
+
+
+def _collapse_union_validation_errors(
+    errors: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """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
+    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.
+
+    Algorithm:
+    1. Partition errors into "union branch" (loc contains a discriminator) and
+       "non-union" (plain field errors with no discriminator in loc).
+    2. For each unique prefix (loc up to the discriminator), collect all branches.
+    3. Pick the branch whose errors have the lowest aggregate _branch_score.
+    4. Keep the errors from that winning branch, mapped to the canonical loc
+       (prefix + remaining path after the discriminator).
+    5. Return non-union errors + winning-branch errors, capped at MAX_GROUPS.
+    """
+    MAX_GROUPS = 8
+
+    non_union: list[dict[str, Any]] = []
+    # Maps prefix_key → {branch_name: [error_dicts]}
+    branch_groups: dict[tuple, dict[str, list[dict[str, Any]]]] = {}
+
+    for err in errors:
+        loc = err.get("loc", ())
+        disc_idx = _find_discriminator_index(loc)
+        if disc_idx is None:
+            non_union.append(err)
+            continue
+
+        prefix = loc[:disc_idx]
+        branch_name = str(loc[disc_idx])
+        branch_groups.setdefault(prefix, {}).setdefault(branch_name, []).append(err)
+
+    # Pick the best branch per prefix
+    collapsed: list[dict[str, Any]] = list(non_union)
+
+    for _prefix, branches in branch_groups.items():
+        # Score each branch: sum of individual error scores
+        scored = sorted(
+            branches.items(),
+            key=lambda kv: (
+                sum(_branch_score(e) for e in kv[1]),
+                len(kv[1]),  # tie-break: fewer errors
+            ),
+        )
+        best_branch_name, best_errors = scored[0]
+
+        # Rewrite locs to strip the discriminator so downstream path logic works
+        for err in best_errors:
+            loc = err.get("loc", ())
+            disc_idx = _find_discriminator_index(loc)
+            if disc_idx is not None:
+                # Canonical loc: prefix + everything after the discriminator
+                canonical_loc = loc[:disc_idx] + loc[disc_idx + 1 :]
+                collapsed.append({**err, "loc": canonical_loc})
+            else:
+                collapsed.append(err)
+
+    return collapsed[:MAX_GROUPS]
+
+
+def _all_authored_chart_fields() -> list[str]:
+    """Union of all field names declared across every per-family chart patch class."""
+    from dataface.core.compile.models.chart.authored import (
+        AreaChart,
+        BarChart,
+        CalloutChart,
+        GeoshapeChart,
+        HeatmapChart,
+        KpiChart,
+        LayeredChart,
+        LineChart,
+        PieChart,
+        PointMapChart,
+        ScatterChart,
+        SparkBarChart,
+        TableChart,
+    )
+
+    fields: set[str] = set()
+    for cls in (
+        BarChart,
+        LineChart,
+        AreaChart,
+        ScatterChart,
+        HeatmapChart,
+        PieChart,
+        KpiChart,
+        TableChart,
+        PointMapChart,
+        GeoshapeChart,
+        LayeredChart,
+        CalloutChart,
+        SparkBarChart,
+    ):
+        fields.update(cls.model_fields.keys())
+    return sorted(fields)
+
+
+@lru_cache(maxsize=1)
+def get_valid_chart_types() -> tuple[str, ...]:
+    """Dynamically extract valid chart types from the ChartType enum.
+
+    This ensures the valid types list stays in sync with the actual
+    type definitions in types.py. Uses lru_cache for thread-safe caching.
+
+    Returns:
+        Tuple of valid chart type strings (tuple for hashability/immutability)
+    """
+    from dataface.core.compile.models.chart.authored import (
+        ChartType,
+    )
+
+    return tuple(ct.value for ct in ChartType)
+
+
+@lru_cache(maxsize=1)
+def get_valid_input_types() -> tuple[str, ...]:
+    """Dynamically extract valid input types from VariableInputType.
+
+    This ensures the valid types list stays in sync with the actual
+    type definitions in types.py. Uses lru_cache for thread-safe caching.
+
+    Returns:
+        Tuple of valid input type strings (tuple for hashability/immutability)
+    """
+    from dataface.core.compile.models.variable.authored import VariableInputType
+
+    return tuple(get_args(VariableInputType))
+
+
+@lru_cache(maxsize=1)
+def get_valid_chart_types_with_aliases() -> tuple[str, ...]:
+    """Valid chart-type values including alias names (e.g. 'point', 'choropleth').
+
+    Tools that surface valid-name lists for users (LSP completion, hover,
+    diagnostics) need aliases included. The compiler does not — it normalizes
+    aliases to canonical names before validating.
+    """
+    from dataface.core.compile.normalize_charts import CHART_TYPE_ALIASES
+
+    return get_valid_chart_types() + tuple(CHART_TYPE_ALIASES)
+
+
+def find_yaml_line_number(
+    yaml_content: str,
+    field_path: list[str],
+) -> int | None:
+    """Find the line number for a field path in YAML content.
+
+    Uses a simple regex-based approach to find where a field is defined.
+    More reliable than YAML parsing for error reporting since we need
+    to match the original source positions.
+
+    Args:
+        yaml_content: Raw YAML string
+        field_path: List of keys forming the path (e.g., ["charts", "revenue", "type"])
+
+    Returns:
+        Line number (1-indexed) or None if not found
+    """
+    if not yaml_content or not field_path:
+        return None
+
+    lines = yaml_content.split("\n")
+
+    # Track current position in path and indentation level
+    current_path_idx = 0
+    target_key = field_path[current_path_idx]
+    expected_indent = 0
+
+    for line_num, line in enumerate(lines, start=1):
+        # Skip empty lines and comments
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Calculate current indentation
+        indent = len(line) - len(line.lstrip())
+
+        # Check if this line has a key
+        if ":" in stripped:
+            key_part = stripped.split(":")[0].strip()
+
+            # If we're looking for a key at this level and found it
+            if key_part == target_key and indent >= expected_indent:
+                # Move to next part of path
+                current_path_idx += 1
+
+                # If we've found all parts, this is the line
+                if current_path_idx >= len(field_path):
+                    return line_num
+
+                # Otherwise, update expected indent and target key
+                expected_indent = indent + 2  # YAML typically uses 2-space indent
+                target_key = field_path[current_path_idx]
+
+    return None
+
+
+def get_yaml_context(
+    yaml_content: str,
+    line_number: int,
+    context_lines: int = 2,
+) -> str:
+    """Get YAML context around an error line.
+
+    Returns the surrounding lines with the error line highlighted.
+
+    Args:
+        yaml_content: Raw YAML string
+        line_number: Line number of the error (1-indexed)
+        context_lines: Number of lines to show before/after
+
+    Returns:
+        Formatted context string with line numbers and error marker
+    """
+    lines = yaml_content.split("\n")
+
+    # Ensure valid line number
+    if line_number < 1 or line_number > len(lines):
+        return ""
+
+    # Calculate range
+    start = max(0, line_number - context_lines - 1)
+    end = min(len(lines), line_number + context_lines)
+
+    # Build context with line numbers
+    result_lines: list[str] = []
+    for idx in range(start, end):
+        actual_line_num = idx + 1
+        line = lines[idx]
+
+        # Mark the error line
+        if actual_line_num == line_number:
+            marker = ">>>"
+            suffix = "  # <-- Error here"
+        else:
+            marker = "   "
+            suffix = ""
+
+        result_lines.append(f"{marker} {actual_line_num:4d} | {line}{suffix}")
+
+    return "\n".join(result_lines)
+
+
+def suggest_similar_value(
+    invalid_value: str,
+    valid_values: Sequence[str],
+    cutoff: float = 0.6,
+) -> str | None:
+    """Suggest a similar valid value for a typo.
+
+    Uses difflib to find close matches to the invalid value.
+
+    Args:
+        invalid_value: The invalid value that was provided
+        valid_values: List of valid values to match against
+        cutoff: Minimum similarity ratio (0-1) for a match
+
+    Returns:
+        The closest valid value, or None if no good match
+    """
+    if not invalid_value or not valid_values:
+        return None
+
+    # Normalize for comparison
+    normalized_input = invalid_value.lower().strip()
+
+    # First check for exact match (case insensitive)
+    for valid in valid_values:
+        if valid.lower() == normalized_input:
+            return valid
+
+    # Use difflib to find close matches
+    matches = difflib.get_close_matches(
+        normalized_input,
+        [v.lower() for v in valid_values],
+        n=1,
+        cutoff=cutoff,
+    )
+
+    if matches:
+        # Return the original case version
+        for valid in valid_values:
+            if valid.lower() == matches[0]:
+                return valid
+
+    return None
+
+
+def parse_pydantic_error_path(error_message: str) -> tuple[list[str], str | None]:
+    """Parse a Pydantic error message to extract field path and invalid value.
+
+    Pydantic errors have patterns like:
+    - "Field 'charts -> revenue -> type': Input should be ..."
+    - "validation error for AuthoredFace\\ncharts -> revenue -> type\\n  Input should be..."
+
+    Args:
+        error_message: The error message from Pydantic
+
+    Returns:
+        Tuple of (field_path as list, invalid_value or None)
+    """
+    field_path: list[str] = []
+    invalid_value: str | None = None
+
+    # Pattern for "Field 'path -> path -> field'" format
+    field_match = re.search(r"Field ['\"]([^'\"]+)['\"]", error_message)
+    if field_match:
+        path_str = field_match.group(1)
+        # Split by " -> " (with spaces)
+        field_path = [p.strip() for p in path_str.split("->")]
+
+    # Alternative pattern for raw Pydantic output
+    if not field_path:
+        # Look for "charts -> revenue -> type" style paths
+        path_match = re.search(r"(\w+(?:\s*->\s*\w+)+)", error_message)
+        if path_match:
+            path_str = path_match.group(1)
+            field_path = [p.strip() for p in path_str.split("->")]
+
+    # Try to extract the invalid value from "Input should be" messages
+    # These often list valid values, with the invalid one being what was provided
+    input_match = re.search(
+        r"input[_\s]?value['\"]?:?\s*['\"]?(\w+)", error_message, re.I
+    )
+    if input_match:
+        invalid_value = input_match.group(1)
+
+    return field_path, invalid_value
+
+
+def extract_valid_values_from_error(error_message: str) -> list[str]:
+    """Extract list of valid values from an error message.
+
+    Pydantic validation errors often include messages like:
+    "Input should be 'bar', 'line', 'area', ..."
+
+    Args:
+        error_message: The error message to parse
+
+    Returns:
+        List of valid values extracted from the message
+    """
+    valid_values: list[str] = []
+
+    # Pattern for "should be 'val1', 'val2', ... or 'valN'"
+    should_be_match = re.search(
+        r"should be\s+['\"]?(\w+)['\"]?(?:,\s*['\"]?(\w+)['\"]?)*(?:\s+or\s+['\"]?(\w+)['\"]?)?",
+        error_message,
+        re.I,
+    )
+    if should_be_match:
+        # Extract all quoted values
+        values = re.findall(r"['\"](\w+)['\"]", error_message)
+        valid_values.extend(values)
+
+    return list(set(valid_values))  # Deduplicate
+
+
+def format_validation_error(
+    error: Exception,
+    yaml_content: str | None = None,
+) -> str:
+    """Format a validation error with enhanced information.
+
+    Adds line numbers, context, and suggestions to validation errors.
+
+    Args:
+        error: The validation error (Pydantic or other)
+        yaml_content: Optional YAML content for context extraction
+
+    Returns:
+        Formatted error message with enhanced information
+    """
+    error_msg = str(error)
+
+    from pydantic import ValidationError as PydanticValidationError
+
+    if isinstance(error, PydanticValidationError):
+        return _format_pydantic_validation_error(error, yaml_content)
+
+    # For non-Pydantic errors, try to enhance based on message pattern
+    return _enhance_error_message(error_msg, yaml_content)
+
+
+def format_validation_errors_structured(
+    error: Any,
+    yaml_content: str | None = None,
+) -> "list[StructuredError]":
+    """Format a Pydantic ValidationError into collapsed StructuredError objects.
+
+    Each returned StructuredError corresponds to one collapsed error group (not
+    one raw Pydantic error). Union-branch phantom failures are suppressed; the
+    best-matching branch per loc prefix is kept. Cap: MAX_GROUPS errors.
+
+    Args:
+        error: A pydantic.ValidationError instance.
+        yaml_content: Raw YAML string — used for line-number resolution.
+
+    Returns:
+        list of StructuredError (≤ MAX_GROUPS elements).
+    """
+    from dataface.core.errors.codes_compile import DF_COMPILE_EXTRA_FIELD
+    from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL
+    from dataface.core.errors.structured import StructuredError
+
+    raw_errors = error.errors()
+    if not raw_errors:
+        return [
+            StructuredError(
+                code=DF_UNKNOWN_INTERNAL.code,
+                message=str(error),
+                domain=DF_UNKNOWN_INTERNAL.domain,
+                doc_url=DF_UNKNOWN_INTERNAL.doc_url,
+            )
+        ]
+
+    collapsed = _collapse_union_validation_errors(raw_errors)
+
+    structured: list[StructuredError] = []
+    for err in collapsed:
+        loc = err.get("loc", ())
+        err_type = err.get("type", "")
+        err_msg = err.get("msg", "Validation error")
+
+        field_path_parts = [str(p) for p in loc if not str(p).startswith("function-")]
+        field_path_str = " -> ".join(field_path_parts) if field_path_parts else ""
+
+        # Resolve line number from the field path.
+        # Strip numeric indices (list positions) — find_yaml_line_number only
+        # understands named keys and cannot navigate by index. Skipping them
+        # still yields a useful line for the surrounding block.
+        line_num: int | None = None
+        if yaml_content and field_path_parts:
+            named_parts = [p for p in field_path_parts if not p.isdigit()]
+            if named_parts:
+                line_num = find_yaml_line_number(yaml_content, named_parts)
+
+        # Pick the most specific error code based on Pydantic error type
+        if err_type == "extra_forbidden":
+            ec = DF_COMPILE_EXTRA_FIELD
+        else:
+            ec = DF_UNKNOWN_INTERNAL
+
+        # Include input value in message when it's a simple string (not a dict/list)
+        # so error consumers can see what value was actually provided.
+        input_val = err.get("input")
+        if field_path_str:
+            if isinstance(input_val, str):
+                message = f"Field '{field_path_str}': {err_msg} (got: {input_val!r})"
+            else:
+                message = f"Field '{field_path_str}': {err_msg}"
+        else:
+            message = err_msg
+
+        hint = _get_suggestion_for_error(
+            err, field_path_parts, err.get("input"), yaml_content
+        )
+
+        structured.append(
+            StructuredError(
+                code=ec.code,
+                message=message,
+                domain=ec.domain,
+                field_path=field_path_str or None,
+                line=line_num,
+                hint=hint,
+                doc_url=ec.doc_url,
+                docs_topic=ec.docs_topic,
+            )
+        )
+
+    return structured
+
+
+def _format_pydantic_validation_error(
+    error: Any,
+    yaml_content: str | None = None,
+) -> str:
+    """Format a Pydantic ValidationError with enhanced information.
+
+    Args:
+        error: Pydantic ValidationError
+        yaml_content: Optional YAML content for context
+
+    Returns:
+        Formatted error message
+    """
+
+    errors = error.errors()
+    if not errors:
+        return str(error)
+
+    formatted_parts: list[str] = []
+
+    for err in errors:
+        loc = err.get("loc", [])
+        err_msg = err.get("msg", "Validation error")
+        input_value = err.get("input")
+
+        # Build human-readable field path, stripping Pydantic discriminated-union
+        # internals: "function-after[...](...)" wrappers and "tagged-union[...]" labels
+        # that appear in loc when using Annotated[..., Discriminator(...)].
+        field_path = [
+            str(p)
+            for p in loc
+            if not str(p).startswith("function-")
+            and not str(p).startswith("tagged-union[")
+        ]
+        path_str = " -> ".join(field_path) if field_path else "root"
+
+        # Determine what kind of error this is
+        parts: list[str] = []
+
+        # Find line number if we have YAML content
+        line_num = None
+        context = ""
+        if yaml_content and field_path:
+            line_num = find_yaml_line_number(yaml_content, field_path)
+            if line_num:
+                context = get_yaml_context(yaml_content, line_num)
+
+        # Build error header with location
+        if line_num:
+            parts.append(f"Error at line {line_num}:")
+        else:
+            parts.append("Validation error:")
+
+        # Add context if available
+        if context:
+            parts.append(context)
+            parts.append("")  # Blank line
+
+        # Add the actual error message
+        parts.append(f"  Field '{path_str}': {err_msg}")
+
+        # Add suggestion for invalid values
+        suggestion = _get_suggestion_for_error(
+            err, field_path, input_value, yaml_content
+        )
+        if suggestion:
+            parts.append(f"\n  {suggestion}")
+
+        formatted_parts.append("\n".join(parts))
+
+    return "\n\n".join(formatted_parts)
+
+
+def _get_suggestion_for_error(
+    err: dict[str, Any],
+    field_path: list[str],
+    input_value: Any,
+    yaml_content: str | None = None,
+) -> str | None:
+    """Get a helpful suggestion for an error.
+
+    Args:
+        err: Pydantic error dict
+        field_path: Path to the field
+        input_value: The invalid input value
+
+    Returns:
+        Suggestion string or None
+    """
+    err_type = err.get("type", "")
+    err_msg = err.get("msg", "")
+
+    # Check if this is a chart type error
+    if (
+        field_path
+        and field_path[-1] == "type"
+        and "charts" in field_path
+        and isinstance(input_value, str)
+    ):
+        valid_chart_types = get_valid_chart_types()
+        suggestion = suggest_similar_value(input_value, valid_chart_types)
+        if suggestion:
+            return f"💡 Did you mean '{suggestion}'? Valid chart types: {', '.join(valid_chart_types[:10])}..."
+        return f"💡 Valid chart types: {', '.join(valid_chart_types[:10])}..."
+
+    # Check if this is a variable input type error
+    if (
+        field_path
+        and field_path[-1] == "input"
+        and "variables" in field_path
+        and isinstance(input_value, str)
+    ):
+        valid_input_types = get_valid_input_types()
+        suggestion = suggest_similar_value(input_value, valid_input_types)
+        if suggestion:
+            return f"💡 Did you mean '{suggestion}'? Valid input types: {', '.join(valid_input_types)}"
+
+    # Missing required field
+    if "required" in err_type.lower() or "missing" in err_msg.lower():
+        field_name = field_path[-1] if field_path else "field"
+        return f"💡 The '{field_name}' field is required."
+
+    # Unknown fields. When AuthoredChart is nested inside AuthoredFace the Pydantic
+    # error loc is ("charts", chart_name, family_name, field_name) — length 4
+    # (with discriminated union: the family name like "bar", "kpi" is included).
+    # The legacy non-discriminated-union path was length 3.
+    # At the face root level the loc is length 1. Both cases use the same
+    # suggestion engine; only the path heuristic differs.
+    if err_type == "extra_forbidden":
+        if field_path[0:1] == ["charts"] and len(field_path) >= 3:
+            # Nested chart field: charts → chart_name → [family_name →] unknown_key
+            field_name = field_path[-1]
+            # Migration hint: height/width must be at chart root, not in style:.
+            if "style" in field_path and field_name in ("height", "width"):
+                return (
+                    f"💡 chart.{field_name} must be set at the chart root, "
+                    f"not under style: — move it up one level."
+                )
+            valid_fields = _all_authored_chart_fields()
+            suggestion = suggest_similar_value(field_name, valid_fields)
+            if suggestion:
+                return f"💡 Unknown chart field. Did you mean '{suggestion}'?"
+            return "💡 Unknown chart field. Check the chart schema for supported keys."
+
+        if len(field_path) == 1:
+            field_name = field_path[0]
+            yaml_parent_path = _find_yaml_parent_path_for_key(yaml_content, field_name)
+
+            if yaml_parent_path == []:
+                from dataface.core.compile.models.face.authored import AuthoredFace
+
+                valid_fields = sorted(AuthoredFace.model_fields)
+                suggestion = suggest_similar_value(field_name, valid_fields)
+                if suggestion:
+                    return f"💡 Unknown field. Did you mean '{suggestion}'?"
+                return "💡 Unknown field. Check the face schema for supported keys."
+
+            if (
+                yaml_parent_path is not None
+                and len(yaml_parent_path) == 2
+                and yaml_parent_path[0] == "charts"
+            ):
+                valid_fields = _all_authored_chart_fields()
+                suggestion = suggest_similar_value(field_name, valid_fields)
+                if suggestion:
+                    return f"💡 Unknown chart field. Did you mean '{suggestion}'?"
+                return (
+                    "💡 Unknown chart field. Check the chart schema for supported keys."
+                )
+
+            return "💡 Unknown field. Check the schema for supported keys."
+
+    # For literal/enum type errors, extract valid values from message
+    if "literal" in err_type.lower() or "should be" in err_msg.lower():
+        valid_values = extract_valid_values_from_error(err_msg)
+        if valid_values and isinstance(input_value, str):
+            suggestion = suggest_similar_value(input_value, valid_values)
+            if suggestion:
+                return f"💡 Did you mean '{suggestion}'?"
+
+    return None
+
+
+def _find_yaml_parent_path_for_key(
+    yaml_content: str | None,
+    field_name: str,
+) -> list[str] | None:
+    if not yaml_content:
+        return None
+
+    stack: list[tuple[int, str]] = []
+    for line in yaml_content.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or ":" not in stripped:
+            continue
+
+        indent = len(line) - len(line.lstrip())
+        while stack and indent <= stack[-1][0]:
+            stack.pop()
+
+        key_part, value_part = stripped.split(":", 1)
+        if key_part.startswith("- "):
+            key_part = key_part[2:].strip()
+        key = key_part.strip().strip("'\"")
+        parent_path = [name for _, name in stack]
+
+        if key == field_name:
+            return parent_path
+
+        if value_part.strip() == "":
+            stack.append((indent, key))
+
+    return None
+
+
+def _enhance_error_message(
+    error_msg: str,
+    yaml_content: str | None = None,
+) -> str:
+    """Enhance a non-Pydantic error message.
+
+    Args:
+        error_msg: The error message string
+        yaml_content: Optional YAML content for context
+
+    Returns:
+        Enhanced error message
+    """
+    # Try to find field path in the error message
+    field_path, invalid_value = parse_pydantic_error_path(error_msg)
+
+    parts: list[str] = []
+
+    # Find line number if possible
+    line_num = None
+    context = ""
+    if yaml_content and field_path:
+        line_num = find_yaml_line_number(yaml_content, field_path)
+        if line_num:
+            context = get_yaml_context(yaml_content, line_num)
+
+    # Add line number header
+    if line_num:
+        parts.append(f"Error at line {line_num}:")
+    else:
+        parts.append("Error:")
+
+    # Add context
+    if context:
+        parts.append(context)
+        parts.append("")
+
+    # Add the original error
+    parts.append(f"  {error_msg}")
+
+    # Try to add suggestions based on content
+    if "chart" in error_msg.lower() and "type" in error_msg.lower():
+        # Extract potential invalid type from message
+        type_match = re.search(r"['\"](\w+)['\"]", error_msg)
+        if type_match:
+            invalid_type = type_match.group(1)
+            valid_chart_types = get_valid_chart_types()
+            if invalid_type not in valid_chart_types:
+                suggestion = suggest_similar_value(invalid_type, valid_chart_types)
+                if suggestion:
+                    parts.append(
+                        f"\n  💡 Did you mean '{suggestion}'? Valid types: {', '.join(valid_chart_types[:10])}..."
+                    )
+
+    return "\n".join(parts)