dataface 0.1.2__py3-none-any.whl

dataface/core/inspect/renderer.py

@@ -0,0 +1,354 @@
+"""Profile rendering module.
+
+Stage: INSPECT
+Purpose: Shared rendering logic for inspect dashboards.
+
+This module provides the core rendering function used by both:
+- CLI: `dft inspect <table> --format html`
+- Server: `dft serve` (via core/serve/server.py)
+
+The renderer substitutes string {{ }} vars in the template YAML, then
+compiles and renders it as HTML. Schema-shaped panels query the
+LayeredSchemaResolver in-process via the `schema_resolver` face query type.
+
+M2 contract: templates contain only string {{ }} vars — no document-level
+{% %} Jinja. Substitution uses simple string replacement for the declared
+set of inspect vars; the schema_resolver compile validator enforces that no
+{{ }} remain after substitution.
+"""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from dataface.core.compile import CompileResult, compile
+from dataface.core.execute import Executor
+from dataface.core.execute.adapters import build_adapter_registry
+from dataface.core.execute.adapters.sql_adapter import SqlAdapter
+from dataface.core.inspect.cache_factory import make_cache_source_for_project
+from dataface.core.inspect.resolver import LayeredSchemaResolver
+from dataface.core.render import render
+
+# Valid identifier pattern for SQL safety
+_VALID_IDENTIFIER = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+_PATH_VAR_KEYS = {"connection"}
+
+# Source name the renderer registers when no project _sources.yaml exists.
+# Templates reference this name through the `source_name` Jinja var; an
+# explicit project source by the same name wins (register_source uses
+# set-if-absent semantics).
+_DEFAULT_SOURCE_NAME = "warehouse"
+
+# The vars the renderer substitutes directly into the template YAML before
+# compile(). schema_resolver fields reject {{ }} Jinja, so these must be
+# literal strings in the compiled YAML. The set is fixed and declared here;
+# adding a new schema_resolver field requires adding it here.
+_SCHEMA_RESOLVER_VARS = ("model", "column", "connection", "source_name", "schema_name")
+
+
+class InspectProfileCompileError(Exception):
+    """Inspect template failed compilation."""
+
+    def __init__(self, result: CompileResult) -> None:
+        self.result = result
+        error_msg = (
+            "; ".join(e.message for e in result.errors)
+            if result.errors
+            else "Unknown error"
+        )
+        super().__init__(f"Failed to compile profile template: {error_msg}")
+
+
+def validate_inspect_variables(variables: dict[str, Any]) -> dict[str, Any]:
+    """Validate and sanitize profile variables.
+
+    Ensures variables are safe to use in SQL queries by:
+    - Checking that model/column names are valid SQL identifiers
+    - Converting all values to strings
+    - Rejecting potentially dangerous inputs
+
+    Args:
+        variables: Raw variables from URL params or CLI
+
+    Returns:
+        Sanitized variables (all string values)
+
+    Raises:
+        ValueError: If variables contain invalid values
+    """
+    sanitized: dict[str, Any] = {}
+
+    for key, value in variables.items():
+        # Convert to string
+        str_value = str(value) if value is not None else ""
+
+        # Validate SQL identifiers (model, column names)
+        if (
+            key in ("model", "column")
+            and str_value
+            and not _VALID_IDENTIFIER.match(str_value)
+        ):
+            raise ValueError(
+                f"Invalid {key} name: '{str_value}'. "
+                "Must be a valid SQL identifier (letters, numbers, underscores)."
+            )
+
+        # Validate file path variables — no shell metacharacters or traversal
+        if key in _PATH_VAR_KEYS and str_value and str_value != ":memory:":
+            if re.search(r"[;&|`$(){}]", str_value):
+                raise ValueError(
+                    f"Invalid {key}: '{str_value}'. Contains disallowed characters."
+                )
+            if ".." in str_value:
+                raise ValueError(
+                    f"Invalid {key}: '{str_value}'. Path traversal is not allowed."
+                )
+
+        sanitized[key] = str_value
+
+    # The renderer always overrides ``source_name`` / ``schema_name`` from
+    # project-root below. Drop any caller-supplied values so a URL like
+    # ``?schema_name=anything-goes`` can't smuggle a string into the rendered YAML.
+    for stripped_key in ("source_name", "schema_name"):
+        sanitized.pop(stripped_key, None)
+
+    return sanitized
+
+
+def _substitute_template_vars(template_yaml: str, vars: dict[str, str]) -> str:
+    """Substitute declared inspect vars into the template YAML.
+
+    Only substitutes the vars named in ``_SCHEMA_RESOLVER_VARS``; the
+    schema_resolver compile validator rejects any remaining ``{{ }}`` Jinja
+    in its fields, so unknown vars cause a compile error rather than silent
+    pass-through.
+
+    Args:
+        template_yaml: Raw template YAML with ``{{ var_name }}`` placeholders.
+        vars: Resolved variable values (all string).
+
+    Returns:
+        Template YAML with placeholders replaced by literal values.
+    """
+    result = template_yaml
+    for key in _SCHEMA_RESOLVER_VARS:
+        value = vars.get(key, "")
+        result = result.replace("{{ " + key + " }}", value)
+        result = result.replace("{{" + key + "}}", value)
+    return result
+
+
+def _resolve_table_schema(
+    resolver: LayeredSchemaResolver,
+    source_name: str,
+    model_name: str,
+) -> str:
+    """Return the schema containing ``model_name``.
+
+    Two-pass strategy that keeps the render path safe for every dialect:
+
+    Pass 1 — cache only (via ``resolver.cache``): no adapter calls, works for
+    every dialect including non-DuckDB warehouses where the adapter may refuse
+    to connect. Returns immediately when the cache has the answer.
+
+    Pass 2 — full resolver walk (via ``resolver.list_schemas`` /
+    ``list_tables``): runs only when the cache pass found nothing. The resolver
+    uses cache-first per-target logic, so cached tables are still served without
+    a second adapter round-trip. Adapter calls happen here for cold-start DuckDB
+    tables that were never profiled.
+
+    First-match semantics: cache iteration order, then dbt-schema order.
+
+    Args:
+        resolver: LayeredSchemaResolver that owns both the cache and the adapter.
+        source_name: Named source registered with the adapter registry.
+        model_name: Bare table/model name to look up.
+
+    Returns:
+        Schema name string, or ``""`` when no match is found or the source is
+        unreachable.
+    """
+    if not source_name:
+        return ""
+
+    def _safe_schema(name: str) -> str:
+        """Return ``name`` only when it's a valid SQL identifier, else ``""``."""
+        return name if name and _VALID_IDENTIFIER.match(name) else ""
+
+    # Cache-first pass: when a warm SuperSchemaSource is available, look up the
+    # schema without adapter calls. This path is only hit when the caller injects
+    # a cache (e.g. Cloud/IDE with dataface-super-schema). The OSS renderer builds
+    # without a cache (cache=None), so this block is skipped in the OSS path.
+    if resolver.cache is not None:
+        cache_schemas = resolver.cache.list_schemas()
+        if cache_schemas is not None:
+            for schema in cache_schemas.get("schemas", {}):
+                cache_tables = resolver.cache.list_tables(schema)
+                if cache_tables is not None and model_name in cache_tables.get(
+                    "tables", {}
+                ):
+                    return _safe_schema(schema)
+
+    # Adapter walk: needed for cold start or when no cache is present.
+    try:
+        schemas_result = resolver.list_schemas(source_name)
+    except Exception:  # noqa: BLE001 — renderer best-effort; fall back to ""
+        return ""
+    schema_names = list(
+        schemas_result.get("sources", {}).get(source_name, {}).get("schemas", {})
+    )
+    for schema in schema_names:
+        try:
+            tables_result = resolver.list_tables(source_name, schema)
+        except Exception:  # noqa: BLE001 — renderer best-effort; per-schema
+            continue
+        tables = (
+            tables_result.get("sources", {})
+            .get(source_name, {})
+            .get("schemas", {})
+            .get(schema, {})
+            .get("tables", {})
+        )
+        if model_name in tables:
+            return _safe_schema(schema)
+    return ""
+
+
+def _ensure_default_source(
+    adapter_registry: Any,
+    connection: str | None,
+    dialect: str,
+) -> None:
+    """Register a synthetic ``warehouse`` source when none are configured.
+
+    The schema_resolver query type requires a named source registered with
+    the adapter registry. Inspect-server projects often have no
+    ``_sources.yaml`` — they're spun up against a single connection. To
+    keep the rewire working for that case we synthesize a default named
+    source from the active connection. An explicit project-source named
+    ``warehouse`` always wins (``register_source`` is idempotent on name).
+
+    Only DuckDB connections are synthesized here — other dialects require
+    credentials that cannot be derived from a bare connection URL; callers
+    that need schema_resolver on non-DuckDB must configure the source in
+    ``_sources.yaml``.
+    """
+    if adapter_registry.list_sql_sources():
+        return
+    # Only DuckDB connection URLs are self-contained enough to synthesize a
+    # valid source config from. Non-DuckDB dialects (Snowflake, Postgres, etc.)
+    # require credentials not present in the URL; callers that need
+    # schema_resolver on non-DuckDB must configure the source in _sources.yaml.
+    if dialect != "duckdb":
+        return
+    fallback_connection: str | None = connection
+    if fallback_connection is None:
+        for adapter in adapter_registry.adapters:
+            if isinstance(adapter, SqlAdapter):
+                fallback_connection = adapter.connection_string
+                break
+    if fallback_connection is None:
+        return
+    # source_config_from_url lives in the private package — use a minimal
+    # inline DuckDB config so the renderer works without the profiler.
+    adapter_registry.register_source(
+        _DEFAULT_SOURCE_NAME,
+        {"type": "duckdb", "path": fallback_connection},
+    )
+
+
+def _resolve_source_name(adapter_registry: Any) -> str:
+    """Pick the source the inspect templates query for schema-shaped data."""
+    sources = adapter_registry.list_sql_sources()
+    if not sources:
+        return ""
+    for entry in sources:
+        if entry["name"] == _DEFAULT_SOURCE_NAME:
+            return _DEFAULT_SOURCE_NAME
+    return str(sources[0]["name"])
+
+
+def render_inspect_dashboard(
+    template_yaml: str,
+    variables: dict[str, Any],
+    project_root: Path | None = None,
+    connection: str | None = None,
+    dialect: str = "duckdb",
+) -> str:
+    """Render a profile template to HTML.
+
+    Substitutes string {{ }} vars into the template YAML (M2: no block-tag
+    Jinja), compiles it, and renders it as HTML. ``source_name`` and
+    ``schema_name`` are resolved from the LayeredSchemaResolver (which uses
+    the cache when present, falls through to dbt/adapter when absent);
+    caller-supplied values for those keys are silently dropped to prevent URL
+    parameter injection.
+
+    Args:
+        template_yaml: YAML template content with string {{ }} placeholders
+        variables: Variables to substitute in the template
+        project_root: Project root for resolving relative paths
+        connection: Database connection string override
+        dialect: Database dialect for the registered SQL adapter — also
+            picked up by the synthetic ``warehouse`` source when no
+            project sources are configured.
+
+    Returns:
+        Rendered HTML string
+
+    Raises:
+        InspectProfileCompileError: If compilation fails
+    """
+    safe_vars = validate_inspect_variables(variables)
+
+    resolved_project_root = project_root or Path.cwd()
+    registry_kwargs: dict[str, Any] = {"read_only": True}
+    if connection:
+        registry_kwargs["connection_string"] = connection
+    registry_kwargs["profile_type"] = dialect
+    adapter_registry = build_adapter_registry(resolved_project_root, **registry_kwargs)
+    _ensure_default_source(adapter_registry, connection, dialect)
+    safe_vars["source_name"] = _resolve_source_name(adapter_registry)
+
+    # Use warm cache when dataface-super-schema is installed; fall back to
+    # dbt-only resolver (cache=None) when it is not. The cache enriches
+    # schema_resolver panels for non-DuckDB warehouses where the adapter
+    # can't connect; without the private package, those panels degrade.
+    cache = make_cache_source_for_project(resolved_project_root)
+    resolver = LayeredSchemaResolver(
+        cache=cache,
+        adapter_registry=adapter_registry,
+        project_root=resolved_project_root,
+    )
+    model_name = safe_vars.get("model", "")
+    safe_vars["schema_name"] = (
+        _resolve_table_schema(resolver, safe_vars["source_name"], model_name)
+        if model_name
+        else ""
+    )
+
+    # Substitute the schema_resolver vars into the YAML before compile().
+    # schema_resolver fields reject {{ }} Jinja — they must be literal strings.
+    safe_vars.setdefault("connection", ":memory:")
+    substituted_yaml = _substitute_template_vars(template_yaml, safe_vars)
+
+    result = compile(substituted_yaml, project_dir=project_root)
+    if result.errors or not result.face:
+        raise InspectProfileCompileError(result=result)
+
+    executor = Executor(
+        result.face,
+        adapter_registry=adapter_registry,
+        query_registry=result.query_registry,
+        project_root=project_root,
+    )
+
+    html_output = render(
+        result.face, executor, format="html", variables=safe_vars
+    ).output
+
+    if html_output is None:
+        return ""
+    if isinstance(html_output, bytes):
+        return html_output.decode("utf-8")
+    return html_output