dataface 0.1.2__py3-none-any.whl

dataface/core/compile/markdown.py

@@ -0,0 +1,154 @@
+"""Markdown report file loader and transformer.
+
+Translates .md files with YAML frontmatter and {{ chart <id> }} embeds
+into YAML face definitions that the normal compile pipeline accepts.
+
+This is a pre-compile step — the output is a YAML string that feeds
+directly into compile().
+"""
+
+import re
+from pathlib import Path
+
+import yaml
+
+_CHART_EMBED_RE = re.compile(r"^\s*\{\{\s*chart\s+(\w+)\s*\}\}\s*$", re.MULTILINE)
+
+# Frontmatter keys that indicate a Dataface markdown report
+_DATAFACE_KEYS = {"queries", "charts", "variables", "source", "sources"}
+
+
+def parse_chart_embeds(body: str) -> list[tuple[str, str]]:
+    """Split markdown body into ordered (type, value) blocks.
+
+    Returns a list of tuples:
+      ("text", <markdown text>)
+      ("chart", <chart_id>)
+
+    Empty/whitespace-only blocks are dropped.
+    """
+    if not body or not body.strip():
+        return []
+
+    blocks: list[tuple[str, str]] = []
+    last_end = 0
+
+    for match in _CHART_EMBED_RE.finditer(body):
+        # Text before this embed
+        text = body[last_end : match.start()].strip()
+        if text:
+            blocks.append(("text", text))
+        blocks.append(("chart", match.group(1)))
+        last_end = match.end()
+
+    # Trailing text after last embed
+    text = body[last_end:].strip()
+    if text:
+        blocks.append(("text", text))
+
+    return blocks
+
+
+def _extract_frontmatter(md_text: str) -> tuple[dict, str]:
+    """Extract YAML frontmatter and markdown body from text.
+
+    Raises ValueError if frontmatter is missing or empty.
+    """
+    if not md_text.startswith("---\n"):
+        raise ValueError(
+            "Markdown face file must have YAML frontmatter (missing opening ---)"
+        )
+
+    end = md_text.find("\n---\n", 4)
+    if end == -1:
+        # Check for --- at very end of file
+        if md_text.endswith("\n---"):
+            end = len(md_text) - 3
+        else:
+            raise ValueError(
+                "Markdown face file must have YAML frontmatter (missing closing ---)"
+            )
+
+    fm_text = md_text[4:end]
+    body = md_text[end + 5 :] if end + 5 <= len(md_text) else ""
+
+    fm = yaml.safe_load(fm_text)
+    if not fm or not isinstance(fm, dict):
+        raise ValueError("Markdown face file must have non-empty YAML frontmatter")
+
+    return fm, body
+
+
+def markdown_to_yaml(md_text: str) -> str:
+    """Transform a markdown face file into a YAML string for the compiler.
+
+    Parses frontmatter, splits the body into content/chart blocks,
+    and emits a face definition with a rows layout.
+    """
+    fm, body = _extract_frontmatter(md_text)
+
+    # Build rows from markdown body
+    blocks = parse_chart_embeds(body)
+    rows: list = []
+    for block_type, value in blocks:
+        if block_type == "text":
+            rows.append({"text": value})
+        elif block_type == "chart":
+            rows.append(value)
+
+    # If body had content but no embeds, ensure we have at least one row
+    if not rows and body.strip():
+        rows.append({"text": body.strip()})
+
+    # Build the face dict from frontmatter + generated rows
+    face_dict = dict(fm)
+    if rows:
+        face_dict["rows"] = rows
+    elif "text" not in face_dict:
+        # No body content and no content in frontmatter — add empty content
+        face_dict["text"] = ""
+
+    return yaml.dump(face_dict, default_flow_style=False, allow_unicode=True)
+
+
+def is_markdown_face(path: Path | str) -> bool:
+    """Check if a .md file is a Dataface markdown report.
+
+    Detection rules:
+    1. Must have .md extension
+    2. Must have YAML frontmatter
+    3. Either in a faces/ directory, OR frontmatter contains Dataface keys
+    """
+    path = Path(path)
+    if path.suffix.lower() != ".md":
+        return False
+
+    if not path.exists():
+        return False
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+
+    # Must have frontmatter
+    if not text.startswith("---\n"):
+        return False
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return False
+
+    # In faces/ directory — any frontmatter is enough
+    if "faces" in path.parts:
+        return True
+
+    # Outside faces/ — require Dataface-specific keys in frontmatter
+    try:
+        fm = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return False
+
+    if not isinstance(fm, dict):
+        return False
+
+    return bool(fm.keys() & _DATAFACE_KEYS)

dataface/core/compile/meta.py

@@ -0,0 +1,388 @@
+"""Meta.yaml cascading configuration resolution.
+
+Stage: COMPILE
+Purpose: Resolve meta.yaml chain from face file to repo root and merge
+configurations according to cascading rules.
+
+Entry Points:
+    - resolve_meta_chain(face_path: Path) -> MetaConfig
+    - merge_meta_with_face(meta: MetaConfig, face_data: Dict) -> Dict
+    - load_meta_file(meta_path: Path) -> MetaConfig
+
+This module implements directory-level configuration files (meta.yaml) that
+cascade settings to all faces in that directory and subdirectories.
+
+Merge Rules:
+    - EXTEND (merge lists/dicts): access, queries, charts
+    - OVERRIDE (child wins): source, face, style, typography
+
+ignore_meta Flag:
+    - Root level: ignore_meta: true ignores ALL parent meta
+    - Field level: access: { ignore_meta: true, ... } ignores just that field
+
+Dependencies:
+    - yaml
+    - pathlib
+
+See also:
+    - config.py: MetaConfig type definition
+    - compiler.py: Integration point
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from dataface.core.compile.config import AccessConfig, MetaConfig
+from dataface.core.compile.errors import CompilationError
+
+# ============================================================================
+# META.YAML FILE LOADING
+# ============================================================================
+
+
+def load_meta_file(meta_path: Path) -> MetaConfig:
+    """Load a meta.yaml file and parse it into MetaConfig.
+
+    Args:
+        meta_path: Path to the meta.yaml file
+
+    Returns:
+        MetaConfig instance
+
+    Raises:
+        CompilationError: If file cannot be parsed
+    """
+    if not meta_path.exists():
+        raise CompilationError(f"Meta file not found: {meta_path}")
+
+    try:
+        with open(meta_path) as f:
+            data = yaml.safe_load(f) or {}
+    except yaml.YAMLError as e:
+        raise CompilationError(f"Failed to parse meta.yaml: {e}") from e
+
+    # Validate no unsupported fields
+    unsupported = {"sources", "variables", "faces"}
+    found_unsupported = unsupported.intersection(data.keys())
+    if found_unsupported:
+        raise CompilationError(
+            f"Unsupported fields in meta.yaml: {found_unsupported}. "
+            f"'sources' must be in dataface.yml, 'variables' and 'faces' "
+            f"must be defined in face files."
+        )
+
+    return MetaConfig.from_dict(data, path=meta_path)
+
+
+def find_meta_files(face_path: Path, root_path: Path | None = None) -> list[Path]:
+    """Find all meta.yaml files from face directory up to root.
+
+    Walks up the directory tree from the face file's directory to the
+    root path, collecting all meta.yaml files found.
+
+    Args:
+        face_path: Path to the face file
+        root_path: Root directory to stop searching (default: filesystem root)
+
+    Returns:
+        List of meta.yaml paths, ordered from root to face directory
+        (so child configs come last for proper override order)
+    """
+    meta_files: list[Path] = []
+
+    # Start from the face's directory
+    current_dir = face_path.parent.resolve()
+
+    # If no root specified, try to find git root or use filesystem root
+    if root_path is None:
+        root_path = find_project_root(current_dir)
+
+    root_path = root_path.resolve()
+
+    # Walk up from face directory to root
+    while True:
+        # Check for meta.yaml (and meta.yml variant)
+        for meta_name in ["meta.yaml", "meta.yml"]:
+            meta_path = current_dir / meta_name
+            if meta_path.exists():
+                meta_files.append(meta_path)
+                break  # Only use one variant per directory
+
+        # Stop if we've reached the root
+        if current_dir == root_path or current_dir.parent == current_dir:
+            break
+
+        current_dir = current_dir.parent
+
+    # Reverse so root comes first (proper merge order: parent -> child)
+    meta_files.reverse()
+
+    return meta_files
+
+
+def find_project_root(start_dir: Path) -> Path:
+    """Find the project root directory.
+
+    Looks for common project markers (.git, dataface.yml, pyproject.toml).
+
+    Args:
+        start_dir: Directory to start searching from
+
+    Returns:
+        Project root path, or filesystem root if not found
+    """
+    current = start_dir.resolve()
+    markers = [".git", "dataface.yml", "dataface.yaml", "pyproject.toml"]
+
+    while current.parent != current:
+        for marker in markers:
+            if (current / marker).exists():
+                return current
+        current = current.parent
+
+    return start_dir  # Fallback to start directory
+
+
+# ============================================================================
+# META CONFIGURATION MERGING
+# ============================================================================
+
+
+def resolve_meta_chain(
+    face_path: Path,
+    root_path: Path | None = None,
+) -> MetaConfig:
+    """Resolve the complete meta.yaml chain for a face file.
+
+    Walks up directory tree from face file to root, collects all meta.yaml
+    files, and merges them according to the cascading rules.
+
+    Args:
+        face_path: Path to the face file
+        root_path: Root directory to stop searching
+
+    Returns:
+        Merged MetaConfig combining all parent configurations
+    """
+    meta_files = find_meta_files(face_path, root_path)
+
+    if not meta_files:
+        # No meta files found, return empty config
+        return MetaConfig()
+
+    # Load all meta configs
+    meta_configs: list[MetaConfig] = []
+    for meta_path in meta_files:
+        try:
+            meta_config = load_meta_file(meta_path)
+            meta_configs.append(meta_config)
+        except CompilationError:
+            # Skip invalid meta files with a warning (could log here)
+            continue
+
+    if not meta_configs:
+        return MetaConfig()
+
+    # Merge configs from root to leaf
+    result = meta_configs[0]
+    for child_config in meta_configs[1:]:
+        result = _merge_meta_configs(result, child_config)
+
+    return result
+
+
+def _merge_meta_configs(parent: MetaConfig, child: MetaConfig) -> MetaConfig:
+    """Merge two MetaConfig objects according to cascading rules.
+
+    Merge rules:
+    - EXTEND (merge lists/dicts): access, queries, charts
+    - OVERRIDE (child wins): source, face, style, typography
+
+    ignore_meta handling:
+    - If child.ignore_meta is True, return child (ignore all parent)
+    - Field-level ignore_meta (e.g., access.ignore_meta) ignores just that field
+
+    Args:
+        parent: Parent (ancestor) configuration
+        child: Child (closer to face) configuration
+
+    Returns:
+        Merged MetaConfig
+    """
+    # If child ignores all parent meta, return child as-is
+    if child.ignore_meta:
+        return child
+
+    # Merge lint config: union of ignore lists, union inner lists per query
+    merged_lint_ignore = list(dict.fromkeys(parent.lint_ignore + child.lint_ignore))
+    merged_lint_ignore_queries: dict[str, list[str]] = dict(parent.lint_ignore_queries)
+    for k, v in child.lint_ignore_queries.items():
+        merged_lint_ignore_queries[k] = list(
+            dict.fromkeys((merged_lint_ignore_queries.get(k) or []) + v)
+        )
+
+    # Merge each field according to its rule
+    return MetaConfig(
+        path=child.path,
+        ignore_meta=False,
+        access=_merge_access(parent.access, child.access),
+        source=child.source if child.source else parent.source,  # Override
+        queries=_merge_dicts(parent.queries, child.queries),  # Extend
+        charts=_merge_dicts(parent.charts, child.charts),  # Extend
+        face=_merge_dicts(parent.face, child.face),  # Override (child wins)
+        style=_merge_dicts(parent.style, child.style),  # Override (child wins)
+        typography=_merge_dicts(
+            parent.typography, child.typography
+        ),  # Override (child wins)
+        lint_ignore=merged_lint_ignore,
+        lint_ignore_queries=merged_lint_ignore_queries,
+    )
+
+
+def _merge_access(
+    parent: AccessConfig | None,
+    child: AccessConfig | None,
+) -> AccessConfig | None:
+    """Merge access configurations.
+
+    Access rules are EXTENDED (merged), unless child has ignore_meta.
+
+    Args:
+        parent: Parent access config
+        child: Child access config
+
+    Returns:
+        Merged access config
+    """
+    if child is None:
+        return parent
+    if parent is None:
+        return child
+
+    # If child ignores parent access, use only child
+    if child.ignore_meta:
+        return AccessConfig(rules=child.rules, ignore_meta=False)
+
+    # Extend: combine rules from both
+    merged_rules = parent.rules + child.rules
+    return AccessConfig(rules=merged_rules, ignore_meta=False)
+
+
+def _merge_dicts(parent: dict[str, Any], child: dict[str, Any]) -> dict[str, Any]:
+    """Merge two dictionaries with child overriding parent.
+
+    For EXTEND fields (queries, charts), items are merged with child taking
+    precedence for same keys.
+
+    For OVERRIDE fields (face, style, typography), child values completely
+    replace parent values for the same keys.
+
+    Args:
+        parent: Parent dictionary
+        child: Child dictionary
+
+    Returns:
+        Merged dictionary
+    """
+    if not parent:
+        return dict(child)
+    if not child:
+        return dict(parent)
+
+    result = dict(parent)
+    result.update(child)
+    return result
+
+
+# ============================================================================
+# FACE INTEGRATION
+# ============================================================================
+
+
+def merge_meta_with_face(
+    meta: MetaConfig,
+    face_data: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge resolved meta configuration with face's own definitions.
+
+    The face's own definitions take precedence over meta settings.
+    This applies the meta configuration as "defaults" that the face can override.
+
+    Args:
+        meta: Resolved MetaConfig from the directory chain
+        face_data: Raw face data from YAML
+
+    Returns:
+        Face data with meta settings applied as defaults
+    """
+    if meta.is_empty():
+        return face_data
+
+    result = dict(face_data)
+
+    # Check if face ignores meta entirely
+    if result.get("ignore_meta", False):
+        # Remove ignore_meta key and return face as-is
+        result.pop("ignore_meta", None)
+        return result
+
+    # Apply source as default (face can override)
+    if meta.source and "source" not in result:
+        result["source"] = meta.source
+
+    # Merge queries (meta queries are defaults, face can override)
+    if meta.queries:
+        merged_queries = dict(meta.queries)
+        merged_queries.update(result.get("queries", {}))
+        result["queries"] = merged_queries
+
+    # Merge charts (meta charts are defaults, face can override)
+    if meta.charts:
+        merged_charts = dict(meta.charts)
+        merged_charts.update(result.get("charts", {}))
+        result["charts"] = merged_charts
+
+    # Apply style as defaults (face style overrides)
+    if meta.style:
+        merged_style = dict(meta.style)
+        merged_style.update(result.get("style", {}))
+        result["style"] = merged_style
+
+    # Apply face config as defaults
+    if meta.face:
+        for key, value in meta.face.items():
+            if key not in result:
+                result[key] = value
+
+    # Apply typography as defaults
+    if meta.typography:
+        merged_typography = dict(meta.typography)
+        merged_typography.update(result.get("typography", {}))
+        result["typography"] = merged_typography
+
+    # Note: access is typically handled at a different layer (routing/auth)
+    # We store it in the result for downstream processing
+    if meta.access and "access" not in result:
+        result["access"] = {"rules": meta.access.rules}
+
+    return result
+
+
+def get_meta_for_face(
+    face_path: Path,
+    root_path: Path | None = None,
+) -> MetaConfig:
+    """Convenience function to get resolved meta config for a face.
+
+    This is the main entry point for compiler integration.
+
+    Args:
+        face_path: Path to the face file
+        root_path: Optional project root path
+
+    Returns:
+        Resolved MetaConfig for the face
+    """
+    return resolve_meta_chain(face_path, root_path)