dataface 0.1.2__py3-none-any.whl

dataface/core/compile/detect.py

@@ -0,0 +1,110 @@
+"""
+Dataface file detection utilities.
+
+Determines whether a file is a Dataface YAML (or markdown report) by path
+conventions or content analysis.
+
+IMPORTANT: This detection logic is duplicated in the VS Code extension for performance.
+If you update the detection rules here, also update:
+  - apps/ide/vscode-extension/src/detection.ts (pathSegmentsIncludeFaces, hasDatafaceKeys)
+  - apps/ide/vscode-extension/src/extension.ts (autoDetectDatafaceFile, isDatafaceFile)
+
+Detection methods (in order of precedence):
+1. File extension: *.dataface.yml, *.dataface.yaml
+2. Directory convention: faces/*.yml, faces/*.yaml, faces/*.md
+3. Content detection: YAML with (queries: OR charts:) AND (rows: OR cols: OR grid: OR tabs:)
+4. Markdown reports: .md files with Dataface YAML frontmatter
+"""
+
+import re
+from pathlib import Path
+
+
+def is_dataface_file(path: Path | str) -> bool:
+    """
+    Check if a file is a Dataface YAML or markdown report by path or content.
+
+    Args:
+        path: Path to the file to check
+
+    Returns:
+        True if the file is detected as a Dataface file
+    """
+    path = Path(path)
+
+    # Markdown report files
+    if path.suffix.lower() == ".md":
+        from dataface.core.compile.markdown import is_markdown_face
+
+        return is_markdown_face(path)
+
+    # Must be a YAML file
+    if path.suffix.lower() not in (".yml", ".yaml"):
+        return False
+
+    # Check file extension pattern: *.dataface.yml
+    if path.name.endswith(".dataface.yml") or path.name.endswith(".dataface.yaml"):
+        return True
+
+    # Check exact filename: dataface.yml
+    if path.name.lower() in ("dataface.yml", "dataface.yaml"):
+        return True
+
+    # Check directory convention: faces/*.yml
+    if "faces" in path.parts:
+        return True
+
+    # Content detection: check for Dataface-specific keys
+    if path.exists():
+        try:
+            content = path.read_text(encoding="utf-8")
+            return has_dataface_keys(content)
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    return False
+
+
+def has_dataface_keys(content: str) -> bool:
+    """
+    Check if YAML content contains Dataface-specific key patterns.
+
+    A file is considered Dataface if it has:
+    - (queries: OR charts:) AND (rows: OR cols: OR grid: OR tabs:)
+
+    This combination is distinctive enough to avoid false positives with
+    other YAML formats (dbt, Kubernetes, Docker Compose, etc.)
+
+    Args:
+        content: YAML file content as string
+
+    Returns:
+        True if content appears to be a Dataface file
+    """
+    # Check for data definition keys
+    has_queries = bool(re.search(r"^queries:", content, re.MULTILINE))
+    has_charts = bool(re.search(r"^charts:", content, re.MULTILINE))
+
+    # Check for layout keys
+    has_layout = bool(re.search(r"^(rows|cols|grid|tabs):", content, re.MULTILINE))
+
+    return (has_queries or has_charts) and has_layout
+
+
+def find_dataface_files(directory: Path | str, recursive: bool = True) -> list[Path]:
+    """
+    Find all Dataface files in a directory.
+
+    Args:
+        directory: Directory to search
+        recursive: Whether to search subdirectories (default: True)
+
+    Returns:
+        List of paths to Dataface files
+    """
+    directory = Path(directory)
+    yaml_pattern = "**/*.y*ml" if recursive else "*.y*ml"
+    md_pattern = "**/*.md" if recursive else "*.md"
+
+    candidates = list(directory.glob(yaml_pattern)) + list(directory.glob(md_pattern))
+    return [p for p in candidates if is_dataface_file(p)]

dataface/core/compile/errors.py

@@ -0,0 +1,302 @@
+"""Compilation error types.
+
+Stage: COMPILE
+Purpose: Define error types for all compilation failures.
+
+These errors are raised during:
+- YAML parsing (ParseError, YAMLError)
+- Schema validation (ValidationError)
+- Reference resolution (ReferenceError)
+- Jinja template rendering (JinjaError)
+
+All errors inherit from CompilationError for easy catching.
+
+Enhanced error messages include:
+- Line numbers where errors occur
+- YAML context showing the problematic snippet
+- Helpful suggestions ("Did you mean 'bar'?")
+
+Refs #94
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from dataface.core.errors.registry import ErrorCode
+    from dataface.core.errors.structured import StructuredError
+
+
+class DatafaceError(Exception):
+    """Base error for all Dataface errors."""
+
+    code: ErrorCode | None = None
+    fields: dict[str, Any]
+
+    @classmethod
+    def from_code(cls, ec: ErrorCode, **fields: Any) -> Self:
+        """Construct an instance carrying a registry ErrorCode + structured fields.
+
+        Bypasses the subclass __init__ (and its `_format_message` decoration);
+        the rendered message is exactly `ec.message_template.format(**fields)`.
+        Reserved field names (`code`, `message`, `fields`) are skipped so the
+        registry-set values can't be clobbered by a caller-supplied field.
+        """
+        message = ec.message_template.format(**fields)
+        inst: Self = cls.__new__(cls)
+        Exception.__init__(inst, message)
+        inst.message = message  # type: ignore[attr-defined]
+        inst.code = ec
+        inst.fields = dict(fields)
+        # Mirror fields onto typed subclass attributes so callers reading
+        # e.chart_id / e.chart_type / e.format / e.element get the same value
+        # whether the error was raised via legacy __init__ or from_code.
+        # Class-level None defaults on every subclass attr make setattr safe.
+        _reserved = {"code", "message", "fields"}
+        for key, value in fields.items():
+            if key in _reserved:
+                continue
+            setattr(inst, key, value)
+        return inst
+
+    def to_structured(self, *, file: str | None = None) -> StructuredError:
+        from dataface.core.errors.structured import build_structured
+
+        return build_structured(self, file=file)
+
+
+class CompilationError(DatafaceError):
+    """Base error for all compilation failures.
+
+    This is the parent class for all compilation-related errors.
+    Catch this to handle any compilation error.
+
+    Attributes:
+        message: Human-readable error description
+        location: Optional location in source (line number, path, etc.)
+        line: Optional line number in the YAML file
+        column: Optional column number in the YAML file
+        context: Optional YAML snippet showing the error location
+        suggestion: Optional helpful suggestion for fixing the error
+    """
+
+    # Class-level None defaults so `from_code`-constructed instances (which
+    # bypass __init__) still satisfy `e.line` / `e.column` access without
+    # crashing. Mirrors the same pattern on RenderError / ExecutionError
+    # subclasses.
+    location: str | None = None
+    line: int | None = None
+    column: int | None = None
+    context: str | None = None
+    suggestion: str | None = None
+
+    def __init__(
+        self,
+        message: str,
+        location: str | None = None,
+        line: int | None = None,
+        column: int | None = None,
+        context: str | None = None,
+        suggestion: str | None = None,
+    ):
+        self.message = message
+        self.location = location
+        self.line = line
+        self.column = column
+        self.context = context
+        self.suggestion = suggestion
+        self.fields: dict[str, Any] = {}
+        super().__init__(self._format_message())
+        if self.code is None:
+            from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL
+
+            self.code = DF_UNKNOWN_INTERNAL
+
+    def _format_message(self) -> str:
+        """Format error message with location, context, and suggestion."""
+        parts = []
+
+        # Add line/column header if available
+        if self.line:
+            if self.column:
+                parts.append(f"Error at line {self.line}, column {self.column}:")
+            else:
+                parts.append(f"Error at line {self.line}:")
+        elif self.location:
+            parts.append(f"Error at {self.location}:")
+
+        # Add YAML context if available
+        if self.context:
+            parts.append(self.context)
+            parts.append("")  # Blank line after context
+
+        # Add the main message
+        parts.append(f"  {self.message}" if parts else self.message)
+
+        # Add suggestion if available
+        if self.suggestion:
+            parts.append(f"\n  {self.suggestion}")
+
+        return (
+            "\n".join(parts) if len(parts) > 1 else parts[0] if parts else self.message
+        )
+
+
+class ParseError(CompilationError):
+    """Error during YAML parsing.
+
+    Raised when:
+    - YAML syntax is invalid
+    - YAML structure cannot be parsed
+
+    Attributes:
+        line: Line number where the error occurred
+        context: YAML snippet showing the error location
+        suggestion: Helpful fix suggestion
+
+    Example:
+        >>> try:
+        ...     compile("invalid: yaml: content")
+        ... except ParseError as e:
+        ...     print(f"Parse failed at line {e.line}: {e}")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        line: int | None = None,
+        context: str | None = None,
+        suggestion: str | None = None,
+    ):
+        # Don't double-prefix if message already has "YAML parse error"
+        if not message.startswith("YAML parse error"):
+            message = f"YAML parse error: {message}"
+        super().__init__(
+            message,
+            location=f"line {line}" if line and not context else None,
+            line=line,
+            context=context,
+            suggestion=suggestion,
+        )
+
+
+class ValidationError(CompilationError):
+    """Error during schema validation.
+
+    Raised when:
+    - Required fields are missing
+    - Field values are invalid type
+    - Enum values are not recognized
+    - Schema constraints are violated
+
+    Attributes:
+        field_path: Path to the field that failed validation
+        invalid_value: The value that caused the error
+        valid_values: List of valid values (if applicable)
+        line: Line number where the error occurred
+        context: YAML snippet showing the error location
+        suggestion: Helpful fix suggestion
+
+    Example:
+        >>> try:
+        ...     compile("charts:\\n  my_chart:\\n    type: invalid_type")
+        ... except ValidationError as e:
+        ...     print(f"Validation failed at line {e.line}: {e}")
+    """
+
+    field_path: str | None = None
+    invalid_value: str | None = None
+    valid_values: list | None = None
+
+    def __init__(
+        self,
+        message: str,
+        location: str | None = None,
+        line: int | None = None,
+        context: str | None = None,
+        suggestion: str | None = None,
+        field_path: str | None = None,
+        invalid_value: str | None = None,
+        valid_values: list | None = None,
+    ):
+        self.field_path = field_path
+        self.invalid_value = invalid_value
+        self.valid_values = valid_values
+
+        # Don't double-prefix if message already has "Validation error"
+        if not message.startswith("Validation error"):
+            message = f"Validation error: {message}"
+
+        super().__init__(
+            message,
+            location=location if not context else None,
+            line=line,
+            context=context,
+            suggestion=suggestion,
+        )
+
+
+class ReferenceError(CompilationError):
+    """Error resolving a reference.
+
+    Raised when:
+    - Chart references unknown query
+    - Layout references unknown chart
+    - Remote reference cannot be resolved
+    - Partial file not found
+
+    Attributes:
+        ref: The reference that could not be resolved
+        context: Where the reference was used
+
+    Example:
+        >>> try:
+        ...     compile("charts:\\n  my_chart:\\n    query: unknown_query")
+        ... except ReferenceError as e:
+        ...     print(f"Reference '{e.ref}' not found")
+    """
+
+    ref: str | None = None
+
+    def __init__(self, ref: str, context: str | None = None):
+        self.ref = ref
+        message = f"Reference '{ref}' not found"
+        location = f"in {context}" if context else None
+        super().__init__(message, location)
+
+
+class JinjaError(CompilationError):
+    """Error during Jinja template resolution.
+
+    Raised when:
+    - Jinja syntax is invalid
+    - Variable not found in template context
+    - Filter not found
+
+    Attributes:
+        template: The template that caused the error (if available)
+
+    Example:
+        >>> try:
+        ...     compile("queries:\\n  q: SELECT * FROM {{ undefined_var }}")
+        ... except JinjaError as e:
+        ...     print(f"Template error: {e}")
+    """
+
+    template: str | None = None
+
+    def __init__(self, message: str, template: str | None = None):
+        self.template = template
+        location = (
+            f"template: {template[:50]}..."
+            if template and len(template) > 50
+            else template
+        )
+        super().__init__(f"Jinja error: {message}", location)