dataface 0.1.2__py3-none-any.whl

dataface/core/compile/config.py

@@ -0,0 +1,823 @@
+"""Compilation configuration module.
+
+Stage: COMPILE
+Purpose: Provide default values and configuration for compilation.
+
+Entry Points:
+    - get_config() -> Config
+    - get_theme(name) -> ThemeConfig
+    - reset_config() -> None
+
+Configuration is loaded from the defaults stack and accessed via dot notation:
+    config = get_config()
+    config.style.board.width       # 1200.0
+    config.style.background # "#ffffff"
+    config.style.charts.aspect_ratio   # 1.6
+
+Runtime defaults are assembled from:
+    - core/defaults/default_config.yml (app-wide defaults + vega.default_theme)
+    - core/defaults/themes/*.yaml (unified theme system)
+    - core/defaults/palettes/<family>/*.yml (color palettes)
+
+YAML is the single source of truth - no Python dataclass defaults.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from functools import cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from dataface.core.compile.models.config import (
+    Config,
+    ConfigNode,
+    ConfigPatch,
+    MarkdownConfig,
+    RenderingConfig,
+    VegaRuntimeConfig,
+    as_plain_mapping,
+    is_mapping_like,
+)
+from dataface.core.compile.models.source import resolve_env_vars_in_dict
+from dataface.core.compile.models.theme import ThemeConfig, normalize_raw_theme_config
+
+# ============================================================================
+# GLOBAL CONFIGURATION
+# ============================================================================
+
+_config: Config | None = None
+_defaults_dir: Path = Path(__file__).parent.parent / "defaults"
+_default_config_path: Path = _defaults_dir / "default_config.yml"
+_built_in_unified_theme_dir: Path = _defaults_dir / "themes"
+_palettes_dir: Path = _defaults_dir / "palettes"
+
+# Per-module default YAML files colocated with their consumers.
+# Each file contributes one or more top-level config namespaces.
+# Add a path here when a new module ships its own defaults.
+_core_dir: Path = Path(__file__).parent.parent
+_MODULE_DEFAULT_PATHS: list[Path] = [
+    _core_dir / "inspect" / "defaults.yml",
+    _core_dir / "render" / "geo_defaults.yml",
+    _core_dir / "render" / "markdown_defaults.yml",
+    _core_dir / "render" / "terminal_defaults.yml",
+]
+
+# Theme caches (avoid repeated resolution of inheritance)
+_theme_cache: dict[str, ThemeConfig] = {}
+_compiled_theme_cache: dict[str, Any] = {}  # str -> Style
+
+#: Name of the built-in default theme shipped with Dataface.
+DEFAULT_THEME_NAME: str = "editorial"
+
+
+def _load_yaml_data(path: Path) -> Any:
+    """Load YAML as plain Python containers."""
+    with path.open("r", encoding="utf-8") as fh:
+        result = yaml.safe_load(fh)
+    return {} if result is None else result
+
+
+def _as_mapping(value: Any, context: str) -> dict[str, Any]:
+    """Normalize mapping-like content into a plain dict."""
+    if is_mapping_like(value):
+        return as_plain_mapping(value)
+    raise TypeError(f"{context} must decode to a mapping")
+
+
+def get_config() -> Config:
+    """Get the current configuration.
+
+    Loads the defaults stack and built-in chart themes on first call.
+    All config is accessed via dot notation:
+        config.style.board.width
+        config.style.layout.rows.gap
+        config.style.charts.bar.padding
+
+    Returns:
+        Config with typed configuration values
+    """
+    global _config
+
+    if _config is None:
+        merged = _load_base_config()
+        merged = _resolve_style_extends(merged)
+        _config = Config.model_validate(merged)
+
+    return _config
+
+
+def reset_config() -> None:
+    """Reset configuration to reload from YAML."""
+    global _config, _theme_cache, _compiled_theme_cache
+    from dataface.core.compile.models.style.merged import clear_resolve_style_cache
+
+    _config = None
+    _theme_cache = {}
+    _compiled_theme_cache = {}
+    clear_resolve_style_cache()
+
+
+def get_chart_rendering() -> ConfigNode:
+    """Narrow getter — engine constants for chart layout and formatting."""
+    return get_config().chart_rendering
+
+
+def get_markdown_config() -> MarkdownConfig:
+    """Narrow getter — markdown rendering color config."""
+    return get_config().markdown
+
+
+def get_terminal_config() -> ConfigNode:
+    """Narrow getter — terminal rendering defaults."""
+    return get_config().terminal
+
+
+def get_rendering_config() -> RenderingConfig:
+    """Narrow getter — export/output rendering settings."""
+    return get_config().rendering
+
+
+def get_vega_config() -> VegaRuntimeConfig:
+    """Narrow getter — Vega-Lite runtime config."""
+    return get_config().vega
+
+
+def load_config(path: Path) -> Config:
+    """Load configuration from a custom YAML file.
+
+    Merges with defaults - file values override defaults.
+
+    Args:
+        path: Path to configuration file
+
+    Returns:
+        Config with merged configuration
+    """
+    global _config, _theme_cache, _compiled_theme_cache
+    from dataface.core.compile.models.style.merged import clear_resolve_style_cache
+
+    # Start with the assembled defaults stack
+    config = _load_base_config()
+
+    # Merge with custom file
+    if path.exists():
+        custom_data = _load_yaml_data(path)
+        custom = ConfigPatch.model_validate(custom_data)
+        config = _deep_merge(
+            config,
+            custom.to_plain_dict(exclude_none=True),
+        )
+
+    config = _resolve_style_extends(config)
+    compiled = Config.model_validate(config)
+
+    _config = compiled
+    _theme_cache = {}
+    _compiled_theme_cache = {}
+    clear_resolve_style_cache()
+
+    return compiled
+
+
+def _load_base_config() -> dict[str, Any]:
+    """Load and merge built-in default config files and themes."""
+    raw_default = _load_yaml_data(_default_config_path)
+    # Extract style before ConfigPatch validation — the style section contains
+    # {extends: "..."} which is not a valid Style. We restore it below
+    # and resolve it to a Style just before Config.model_validate.
+    raw_style = raw_default.pop("style", {}) if isinstance(raw_default, dict) else {}
+
+    config = ConfigPatch.model_validate(raw_default)
+    # ConfigPatch uses None as "not authored in this overlay". Preserve only
+    # explicitly authored keys when projecting patch models back to dicts.
+    config_data = config.to_plain_dict(exclude_none=True)
+    if raw_style:
+        config_data["style"] = raw_style
+
+    for module_path in _MODULE_DEFAULT_PATHS:
+        config_data = _deep_merge(config_data, _load_yaml_data(module_path))
+
+    # Load palette data from defaults/palettes/ into the config tree.
+    config_data = _deep_merge(config_data, _load_palettes())
+
+    return config_data
+
+
+_SCAFFOLD_META_KEYS: frozenset[str] = frozenset({"name", "family", "description"})
+
+
+def _load_palettes() -> dict[str, Any]:
+    """Load palette YAMLs from defaults/palettes/ into the config tree.
+
+    Returns a dict with:
+      - ``palettes``: categorical palettes keyed by name (category-10, hero-6, …)
+        from ``defaults/palettes/categorical/*.yml``.
+      - ``dft_grays`` / ``dft_creams``: flat hex mappings from
+        ``defaults/palettes/scaffold/dft-grays.yml`` and ``dft-creams.yml``.
+
+    Sequential, diverging, and tone palettes are accessed via
+    ``dataface.core.compile.palette`` — not the config tree.
+
+    Shipped YAMLs are expected to be well-formed. Any malformed file raises —
+    no silent skip.
+    """
+    overlay: dict[str, Any] = {}
+    cat_dir = _palettes_dir / "categorical"
+    if cat_dir.is_dir():
+        palettes: dict[str, list[str]] = {}
+        for path in sorted(cat_dir.glob("*.yml")):
+            data = _load_yaml_data(path)
+            name = data.get("name") if isinstance(data, Mapping) else None
+            # Categorical files use colors: (renamed from stops:).
+            colors = data.get("colors") if isinstance(data, Mapping) else None
+            if not isinstance(name, str) or not isinstance(colors, list):
+                raise ValueError(
+                    f"{path}: categorical palette YAML must have string 'name' "
+                    f"and list 'colors' keys"
+                )
+            palettes[name] = list(colors)
+        if palettes:
+            overlay["palettes"] = palettes
+
+    for legacy_attr, palette_name in (
+        ("dft_grays", "dft-grays"),
+        ("dft_creams", "dft-creams"),
+    ):
+        # Use _load_spine (which resolves extends: inheritance) so that child
+        # palettes like dft-creams inherit the full alias graph from their parent.
+        from dataface.core.compile.palette import _load_spine, resolve_alias_chain
+
+        spine = _load_spine(palette_name)
+        if spine.colors is None or spine.aliases is None:
+            raise ValueError(
+                f"scaffold palette '{palette_name}' must have 'colors:' list and "
+                f"'aliases:' mapping (unified palette shape)"
+            )
+        # Flatten: resolve every alias to a terminal hex for legacy consumers.
+        flat: dict[str, str] = {
+            alias_key: resolve_alias_chain(
+                alias_key, dict(spine.aliases), colors=list(spine.colors)
+            )
+            for alias_key in spine.aliases
+        }
+        if not flat:
+            raise ValueError(
+                f"scaffold palette '{palette_name}' has no aliases — check palette YAML shape"
+            )
+        overlay[legacy_attr] = flat
+
+    return overlay
+
+
+def _deep_merge(base: Mapping[str, Any], overlay: Mapping[str, Any]) -> dict[str, Any]:
+    """Recursively merge overlay into base.
+
+    Rebuild only the branches touched by the overlay. Overlay leaves are
+    deep-copied so later mutation cannot bleed back into reusable defaults.
+    """
+    result = dict(base)
+    for key, value in overlay.items():
+        if (
+            key in result
+            and isinstance(result[key], Mapping)
+            and isinstance(value, Mapping)
+        ):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result
+
+
+def _load_built_in_unified_themes() -> dict[str, dict[str, Any]]:
+    """Load unified theme files from themes/ (.yaml extension).
+
+    These are pure Dataface Style-format files. Uses .yaml extension
+    to distinguish from the now-deleted chart_themes/*.yml legacy format.
+    """
+    themes: dict[str, dict[str, Any]] = {}
+    if not _built_in_unified_theme_dir.exists():
+        return themes
+
+    for path in sorted(_built_in_unified_theme_dir.glob("*.yaml")):
+        raw = _as_mapping(_load_yaml_data(path), f"Unified theme file {path.name}")
+        # Unified theme files have the style dict wrapped under 'style:'.
+        # Keep the full structure (extends + style) for _resolve_named_config to handle.
+        themes[path.stem] = raw
+
+    return themes
+
+
+@cache
+def list_built_in_themes() -> list[str]:
+    """Return sorted stem names of all built-in unified themes."""
+    return sorted(p.stem for p in _built_in_unified_theme_dir.glob("*.yaml"))
+
+
+def get_compiled_theme(theme_name: str | None) -> Any:  # -> Style
+    """Load a unified theme as a Style, resolving extends: inheritance.
+
+    Unified themes live in themes/*.yaml. Each file has:
+        extends: <parent-name>  (optional)
+        style:
+          background: ...
+          charts: ...
+
+    The style dicts from the inheritance chain are deep-merged (child wins).
+    The merged dict is validated via Style.model_validate().
+
+    Returns Style with all defaults filled in.
+    """
+    from dataface.core.compile.models.style.compiled import Style
+
+    name = theme_name or DEFAULT_THEME_NAME
+
+    if name in _compiled_theme_cache:
+        return _compiled_theme_cache[name]
+
+    if not _built_in_unified_theme_dir.exists():
+        raise FileNotFoundError(
+            f"Unified themes directory not found: {_built_in_unified_theme_dir}."
+        )
+
+    unified_themes = _load_built_in_unified_themes()
+    if not unified_themes:
+        raise FileNotFoundError(
+            f"No unified theme files (*.yaml) found in {_built_in_unified_theme_dir}."
+        )
+
+    # Build a themes dict that maps name → style dict (without the 'style:' wrapper)
+    # for _resolve_named_config to merge. We expose 'extends' at top level and
+    # the style keys merged in at the same level so the resolver sees them.
+    flat_themes: dict[str, dict[str, Any]] = {}
+    for tname, raw in unified_themes.items():
+        entry: dict[str, Any] = {}
+        if "extends" in raw:
+            entry["extends"] = raw["extends"]
+        style_data = raw.get("style", {})
+        if style_data:
+            entry.update(style_data)
+        flat_themes[tname] = entry
+
+    if name not in flat_themes:
+        raise ValueError(
+            f"Theme '{name}' not found in {_built_in_unified_theme_dir}. "
+            f"Available themes: {sorted(flat_themes)}"
+        )
+
+    from dataface.core.compile.models.style.merged import (
+        _resolve_color_tokens,
+        _resolve_self_tokens,
+    )
+
+    resolved = _resolve_named_config(name, flat_themes, set())
+    compiled = Style.model_validate(resolved)
+    # Substitute theme-self tokens (e.g. ``theme.background`` for canvas-coupled
+    # fields like ``arc.stroke``) BEFORE color-token resolution so the
+    # substituted palette token is itself resolved by the next pass.
+    compiled = _resolve_self_tokens(compiled)
+    # Themes carry palette tokens (e.g. "dft-grays.gray-30") for human readability.
+    # Resolve them to concrete hex once, at theme-load time, so every consumer of
+    # Style sees concrete colors.
+    compiled = _resolve_color_tokens(compiled)
+    _compiled_theme_cache[name] = compiled
+    return compiled
+
+
+def _resolve_style_extends(config: dict[str, Any]) -> dict[str, Any]:
+    """Resolve style.extends into a Style for Config.style.
+
+    Called after preset application, just before Config.model_validate.
+    All visual defaults live in themes/*.yaml; style.extends names the base theme.
+    """
+    style_section = config.get("style", {})
+    if isinstance(style_section, dict) and "extends" in style_section:
+        config = dict(config)
+        config["style"] = get_compiled_theme(style_section["extends"])
+    return config
+
+
+# ============================================================================
+# THEME ACCESS
+# ============================================================================
+
+
+def get_theme(theme_name: str | None) -> ThemeConfig:
+    """Get a typed theme config by name, resolving inheritance.
+
+    Themes can inherit via 'extends':
+        my-theme:
+          extends: default
+          charts:
+            table:
+              header_background: "#f0f0f0"
+
+    Args:
+        theme_name: Name of theme, or None for empty theme
+
+    Returns:
+        ThemeConfig with typed access to theme values
+    """
+    if not theme_name:
+        return ThemeConfig()
+
+    if theme_name in _theme_cache:
+        return _theme_cache[theme_name]
+
+    config = get_config()
+    resolved_dict = _resolve_named_config(
+        theme_name, _as_mapping(config.themes, "themes"), set()
+    )
+    resolved = ThemeConfig.model_validate(normalize_raw_theme_config(resolved_dict))
+    _theme_cache[theme_name] = resolved
+    return resolved
+
+
+def get_theme_dict(theme_name: str | None) -> dict[str, Any]:
+    """Get a theme as raw dict for passing to Vega-Lite.
+
+    Use this when you need the raw dict to merge into a Vega-Lite spec.
+    For typed access to theme values, use get_theme() instead.
+
+    Args:
+        theme_name: Name of theme, or None for empty dict
+
+    Returns:
+        Raw theme dictionary suitable for Vega-Lite config
+    """
+    if not theme_name:
+        return {}
+    return get_theme(theme_name).to_vega_config()
+
+
+def _resolve_named_config(
+    config_name: str, configs: Mapping[str, Any], seen: set[str]
+) -> dict[str, Any]:
+    """Resolve a named theme/preset config, handling inheritance via extends."""
+    if config_name in seen:
+        raise ValueError(
+            f"Circular config inheritance: {' -> '.join(seen)} -> {config_name}"
+        )
+
+    config = configs.get(config_name)
+    if not config:
+        return {}
+    if not is_mapping_like(config):
+        raise TypeError(f"Config '{config_name}' must be a mapping")
+
+    config_data = _as_mapping(config, config_name)
+
+    extends = config_data.get("extends")
+    if not extends:
+        return {k: v for k, v in config_data.items() if k != "extends"}
+
+    seen_with_current = seen | {config_name}
+    parent = _resolve_named_config(extends, configs, seen_with_current)
+    child = {k: v for k, v in config_data.items() if k != "extends"}
+    return _deep_merge(parent, child)
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+
+def get_default_theme_name() -> str:
+    """Return the designated default chart theme name."""
+    config = get_config()
+    return config.vega.default_theme
+
+
+def set_default_theme_name(theme_name: str) -> None:
+    """Override the in-process default theme name.
+
+    Validates the theme exists before patching. Raises ValueError on unknown names.
+    Called at serve startup by apply_default_theme_from_env(); not for general use.
+
+    Args:
+        theme_name: A built-in theme stem (e.g. "carbong100", "light").
+
+    Raises:
+        ValueError: If theme_name is not a built-in theme.
+    """
+    available = list_built_in_themes()
+    if theme_name not in available:
+        raise ValueError(
+            f"Theme '{theme_name}' not found. Available built-in themes: {available}"
+        )
+    # Force initialization so the patch lands on the live singleton.
+    config = get_config()
+    config.vega.default_theme = theme_name
+
+
+def get_palette(name: str = "default") -> list[str]:
+    """Get a named color palette."""
+    config = get_config()
+    palettes = config.palettes
+    palette_name = "category-10" if name == "default" else name
+    if palette_name not in palettes:
+        raise KeyError(f"Unknown palette '{palette_name}'")
+    palette = palettes[palette_name]
+    if not isinstance(palette, list):
+        raise TypeError(f"Palette '{palette_name}' must be a list")
+    return list(palette)
+
+
+# ============================================================================
+# PROJECT SOURCES
+# ============================================================================
+
+_project_sources: dict[Path, ProjectSourcesConfig] = {}
+
+
+def get_project_sources(project_dir: Path | None = None) -> ProjectSourcesConfig:
+    """Get project-level sources configuration.
+
+    Loads from:
+    1. Config sources section
+    2. Project dataface.yml sources section
+    3. _sources.yaml file (merged, takes precedence)
+
+    Args:
+        project_dir: Project directory (default: cwd)
+
+    Returns:
+        ProjectSourcesConfig with 'default' and 'sources' attributes
+    """
+    global _project_sources
+
+    project_dir = (project_dir or Path.cwd()).resolve()
+
+    cached_sources = _project_sources.get(project_dir)
+    if cached_sources is not None:
+        return cached_sources
+
+    config = get_config()
+
+    # Start with config sources
+    default_source = None
+    all_sources: dict[str, dict[str, Any]] = {}
+
+    if config.sources:
+        sources_data = _as_mapping(config.sources, "config.sources")
+        default_source = sources_data.pop("default", None)
+        all_sources.update(
+            {k: v for k, v in sources_data.items() if isinstance(v, dict)}
+        )
+
+    # Project dataface.yml overrides global defaults.
+    project_config_file = None
+    for candidate in (project_dir / "dataface.yml", project_dir / "dataface.yaml"):
+        if candidate.exists():
+            project_config_file = candidate
+            break
+
+    if project_config_file is not None:
+        file_data = _as_mapping(
+            _load_yaml_data(project_config_file), project_config_file.name
+        )
+        if "sources" in file_data:
+            sources_section = _as_mapping(
+                file_data["sources"], f"{project_config_file.name} sources section"
+            )
+
+            if "default" in sources_section:
+                default_source = sources_section.pop("default")
+
+            all_sources.update(
+                {k: v for k, v in sources_section.items() if isinstance(v, dict)}
+            )
+
+    # Load _sources.yaml if it exists
+    sources_file = project_dir / "_sources.yaml"
+    if not sources_file.exists():
+        sources_file = project_dir / "_sources.yml"
+
+    if sources_file.exists():
+        file_data = _as_mapping(_load_yaml_data(sources_file), sources_file.name)
+        # Handle structure where sources are nested under 'sources' key
+        if "sources" in file_data:
+            sources_section = _as_mapping(
+                file_data["sources"], f"{sources_file.name} sources section"
+            )
+        else:
+            sources_section = _as_mapping(file_data, sources_file.name)
+
+        # Extract default
+        if "default" in sources_section:
+            default_source = sources_section.pop("default")
+
+        # Merge source definitions
+        all_sources.update(
+            {k: dict(v) for k, v in sources_section.items() if isinstance(v, dict)}
+        )
+
+    project_sources = ProjectSourcesConfig(
+        default=default_source,
+        sources=_normalize_project_sources(all_sources),
+    )
+    _project_sources[project_dir] = project_sources
+    return project_sources
+
+
+def reset_project_sources() -> None:
+    """Reset project sources cache."""
+    global _project_sources
+    _project_sources = {}
+    reset_project_warnings_ignore()
+
+
+def invalidate_project_sources(project_dir: Path | None) -> None:
+    """Clear cached project sources for a single project directory."""
+    if project_dir is None:
+        return
+
+    _project_sources.pop(project_dir.resolve(), None)
+    invalidate_project_warnings_ignore(project_dir)
+
+
+# ============================================================================
+# PROJECT WARNINGS IGNORE
+# ============================================================================
+
+_project_warnings_ignore: dict[Path, frozenset[str]] = {}
+
+
+def get_project_warnings_ignore(project_dir: Path | None = None) -> frozenset[str]:
+    """Return the set of warning codes to suppress project-wide.
+
+    Reads `warnings.ignore` from `dataface.yml` (or `dataface.yaml`) in
+    `project_dir`.  Returns an empty frozenset when no config file exists or
+    the key is absent.
+
+    Args:
+        project_dir: Project directory.  Defaults to cwd when None.
+
+    Returns:
+        Frozenset of warning code strings.
+    """
+    global _project_warnings_ignore
+
+    resolved_dir = (project_dir or Path.cwd()).resolve()
+    cached = _project_warnings_ignore.get(resolved_dir)
+    if cached is not None:
+        return cached
+
+    for candidate in (resolved_dir / "dataface.yml", resolved_dir / "dataface.yaml"):
+        if candidate.exists():
+            file_data = _as_mapping(_load_yaml_data(candidate), candidate.name)
+            warnings_section = file_data.get("warnings")
+            if warnings_section is not None:
+                warnings_map = _as_mapping(
+                    warnings_section, f"{candidate.name} warnings section"
+                )
+                raw_ignore = warnings_map.get("ignore")
+                if raw_ignore is not None:
+                    if not isinstance(raw_ignore, list):
+                        raise TypeError(
+                            f"{candidate.name}: warnings.ignore must be a list of strings"
+                        )
+                    for entry in raw_ignore:
+                        if not isinstance(entry, str):
+                            raise TypeError(
+                                f"{candidate.name}: warnings.ignore entries must be "
+                                f"strings, got {type(entry).__name__}: {entry!r}"
+                            )
+                    codes = frozenset(raw_ignore)
+                    _project_warnings_ignore[resolved_dir] = codes
+                    return codes
+            break
+
+    empty: frozenset[str] = frozenset()
+    _project_warnings_ignore[resolved_dir] = empty
+    return empty
+
+
+def reset_project_warnings_ignore() -> None:
+    """Reset project warnings ignore cache (for tests)."""
+    global _project_warnings_ignore
+    _project_warnings_ignore = {}
+
+
+def invalidate_project_warnings_ignore(project_dir: Path | None) -> None:
+    """Clear cached warnings ignore for a single project directory."""
+    if project_dir is None:
+        return
+    _project_warnings_ignore.pop(project_dir.resolve(), None)
+
+
+# ============================================================================
+# META CONFIG CLASSES
+# ============================================================================
+# These are used by meta.py for handling meta.yaml files
+
+
+class AccessConfig:
+    """Access control configuration for meta.yaml."""
+
+    def __init__(
+        self,
+        rules: list[dict[str, Any]] | None = None,
+        ignore_meta: bool = False,
+    ):
+        self.rules = rules or []
+        self.ignore_meta = ignore_meta
+
+
+class MetaConfig:
+    """Configuration from meta.yaml file."""
+
+    def __init__(
+        self,
+        path: Path | None = None,
+        ignore_meta: bool = False,
+        access: AccessConfig | None = None,
+        source: str | None = None,
+        queries: dict[str, Any] | None = None,
+        charts: dict[str, Any] | None = None,
+        face: dict[str, Any] | None = None,
+        style: dict[str, Any] | None = None,
+        typography: dict[str, Any] | None = None,
+        lint_ignore: list[str] | None = None,
+        lint_ignore_queries: dict[str, list[str]] | None = None,
+    ):
+        self.path = path
+        self.ignore_meta = ignore_meta
+        self.access = access
+        self.source = source
+        self.queries = queries or {}
+        self.charts = charts or {}
+        self.face = face or {}
+        self.style = style or {}
+        self.typography = typography or {}
+        self.lint_ignore: list[str] = lint_ignore or []
+        self.lint_ignore_queries: dict[str, list[str]] = lint_ignore_queries or {}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], path: Path | None = None) -> MetaConfig:
+        """Create MetaConfig from dictionary."""
+        access_data = data.get("access")
+        access_config = None
+        if access_data:
+            if isinstance(access_data, dict):
+                access_config = AccessConfig(
+                    rules=access_data.get("rules", []),
+                    ignore_meta=access_data.get("ignore_meta", False),
+                )
+            elif isinstance(access_data, list):
+                access_config = AccessConfig(rules=access_data)
+
+        lint_data = data.get("lint", {})
+        if lint_data and not isinstance(lint_data, dict):
+            raise ValueError(
+                f"meta.yaml 'lint' must be a mapping, got {type(lint_data).__name__}"
+            )
+
+        return cls(
+            path=path,
+            ignore_meta=data.get("ignore_meta", False),
+            access=access_config,
+            source=data.get("source"),
+            queries=data.get("queries", {}),
+            charts=data.get("charts", {}),
+            face=data.get("face", {}),
+            style=data.get("style", {}),
+            typography=data.get("typography", {}),
+            lint_ignore=lint_data.get("ignore", []),
+            lint_ignore_queries=lint_data.get("ignore_queries", {}),
+        )
+
+    def is_empty(self) -> bool:
+        """Check if this meta config has no actual configuration."""
+        return (
+            not self.access
+            and not self.source
+            and not self.queries
+            and not self.charts
+            and not self.face
+            and not self.style
+            and not self.typography
+            and not self.lint_ignore
+            and not self.lint_ignore_queries
+        )
+
+
+class ProjectSourcesConfig:
+    """Project-level sources configuration."""
+
+    def __init__(
+        self,
+        default: str | None = None,
+        sources: dict[str, dict[str, Any]] | None = None,
+    ):
+        self.default = default
+        self.sources = sources or {}
+
+
+def _normalize_project_sources(
+    sources: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    return {name: resolve_env_vars_in_dict(config) for name, config in sources.items()}