dataface 0.1.2__py3-none-any.whl

dataface/core/inspect/templates/string_column.yml

@@ -0,0 +1,263 @@
+# String Column Profile Template
+#
+# Analysis of a string/text column. Schema panel pulls from the
+# LayeredSchemaResolver; live aggregations stay on warehouse SQL.
+#
+# URL: /inspect/string_column/?model=<table>&column=<col>
+#
+# Required variables:
+#   - model: Table/model name
+#   - column: Column name to analyze
+#
+# Optional variables:
+#   - connection: DuckDB file path or :memory: (default: :memory:)
+#
+# Theme is set via DFT_DEFAULT_THEME env var at serve startup.
+
+title: "String Column: {{ model }}.{{ column }}"
+
+text: |
+  [Back to {{ model }}](/inspect/model/?model={{ model }}&connection={{ connection }})
+
+variables:
+  model:
+    input: text
+    visible: false
+    default: ""
+  column:
+    input: text
+    visible: false
+    default: ""
+  connection:
+    input: text
+    visible: false
+    default: ":memory:"
+  source_name:
+    input: text
+    visible: false
+    default: ""
+  schema_name:
+    input: text
+    visible: false
+    default: ""
+
+queries:
+  column_schema:
+    type: schema_resolver
+    source: "{{ source_name }}"
+    schema: "{{ schema_name }}"
+    table: "{{ model }}"
+    column: "{{ column }}"
+
+  # Basic string stats
+  stats:
+    source:
+      type: duckdb
+      path: "{{ connection }}"
+    sql: |
+      SELECT
+        COUNT(*) as total_count,
+        COUNT({{ column }}) as non_null_count,
+        COUNT(*) - COUNT({{ column }}) as null_count,
+        ROUND(100.0 * (COUNT(*) - COUNT({{ column }})) / COUNT(*), 2) as null_pct,
+        COUNT(DISTINCT {{ column }}) as distinct_count,
+        COUNT(CASE WHEN TRIM({{ column }}) = '' THEN 1 END) as empty_count,
+        MIN(LENGTH({{ column }})) as min_length,
+        MAX(LENGTH({{ column }})) as max_length,
+        ROUND(AVG(LENGTH({{ column }})), 1) as avg_length
+      FROM {{ model }}
+
+  # Top values by frequency
+  top_values:
+    source:
+      type: duckdb
+      path: "{{ connection }}"
+    sql: |
+      SELECT
+        COALESCE({{ column }}, '(null)') as value,
+        COUNT(*) as count,
+        ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM {{ model }}), 2) as pct
+      FROM {{ model }}
+      GROUP BY {{ column }}
+      ORDER BY COUNT(*) DESC
+      LIMIT 20
+
+  # Length distribution
+  length_distribution:
+    source:
+      type: duckdb
+      path: "{{ connection }}"
+    sql: |
+      SELECT
+        LENGTH({{ column }}) as length,
+        COUNT(*) as count
+      FROM {{ model }}
+      WHERE {{ column }} IS NOT NULL
+      GROUP BY LENGTH({{ column }})
+      ORDER BY length
+
+  # Pattern analysis (first character distribution)
+  first_char:
+    source:
+      type: duckdb
+      path: "{{ connection }}"
+    sql: |
+      SELECT
+        UPPER(SUBSTRING({{ column }}, 1, 1)) as first_char,
+        COUNT(*) as count
+      FROM {{ model }}
+      WHERE {{ column }} IS NOT NULL AND LENGTH({{ column }}) > 0
+      GROUP BY UPPER(SUBSTRING({{ column }}, 1, 1))
+      ORDER BY COUNT(*) DESC
+      LIMIT 26
+
+  # Sample values
+  samples:
+    source:
+      type: duckdb
+      path: "{{ connection }}"
+    sql: |
+      SELECT DISTINCT {{ column }} as value
+      FROM {{ model }}
+      WHERE {{ column }} IS NOT NULL
+      LIMIT 20
+
+charts:
+  schema_panel:
+    title: Schema
+    type: table
+    query: column_schema
+    style:
+      header_overflow: wrap-two
+      columns:
+        name:
+          label: Column
+        type:
+          label: Type
+        role:
+          label: Role
+        semantic_type:
+          label: Semantic
+        description:
+          label: Description
+
+  # Stats KPIs
+  distinct:
+    label: Distinct Values
+    type: kpi
+    query: stats
+    value: distinct_count
+    format: ",.0f"
+
+  null_pct:
+    label: "Null %"
+    type: kpi
+    query: stats
+    value: null_pct
+    format: ".1f"
+
+  empty_count:
+    label: Empty Strings
+    type: kpi
+    query: stats
+    value: empty_count
+    format: ",.0f"
+
+  min_len:
+    label: Min Length
+    type: kpi
+    query: stats
+    value: min_length
+    format: ",.0f"
+
+  max_len:
+    label: Max Length
+    type: kpi
+    query: stats
+    value: max_length
+    format: ",.0f"
+
+  avg_len:
+    label: Avg Length
+    type: kpi
+    query: stats
+    value: avg_length
+    format: ".1f"
+
+  # Spark bar (compact top values for profiler cards)
+  top_values_spark:
+    title: Top Values
+    type: spark_bar
+    query: top_values
+    x: count
+    y: value
+
+  # Top values chart (full-size)
+  top_values_chart:
+    title: Top Values (Full)
+    type: bar
+    query: top_values
+    x: value
+    y: count
+    style:
+      orientation: horizontal
+
+  # Top values table
+  top_values_table:
+    title: Value Frequency
+    type: table
+    query: top_values
+    style:
+      header_overflow: wrap-two
+      columns:
+        value:
+          label: Value
+        count:
+          label: Count
+          format: ",.0f"
+        pct:
+          label: "%"
+          format: ".1f"
+
+  # Length distribution
+  length_chart:
+    title: Length Distribution
+    type: bar
+    query: length_distribution
+    x: length
+    y: count
+    x_label: String Length
+    y_label: Count
+
+  # First character distribution
+  first_char_chart:
+    title: First Character
+    type: bar
+    query: first_char
+    x: first_char
+    y: count
+
+  # Sample values
+  samples_table:
+    title: Sample Values
+    type: table
+    query: samples
+    style:
+      header_overflow: wrap-two
+
+rows:
+  - schema_panel
+  - cols:
+      - distinct
+      - null_pct
+      - empty_count
+      - min_len
+      - max_len
+      - avg_len
+  - cols:
+      - top_values_spark
+      - top_values_table
+  - cols:
+      - length_chart
+      - first_char_chart
+  - samples_table

dataface/core/project_roots.py

@@ -0,0 +1,165 @@
+"""Shared project/dbt root discovery used by render and MCP commands."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Marker files that indicate a project root, checked in priority order.
+PROJECT_MARKERS = ("dataface.yml", "dataface.yaml", "dbt_project.yml")
+
+
+def discovery_boundary_for_face(
+    face_parent: Path, project_dir: Path | str | None
+) -> Path | None:
+    """Return the directory ceiling for upward discovery, or None to walk to the filesystem root.
+
+    When ``--project-dir`` is omitted, callers should pass ``project_dir=None`` so we can walk
+    above the face directory (required for ``…/tutorial_dbt/faces/*.yml``).
+
+    When ``project_dir`` resolves to the same directory as ``face_parent`` (e.g. cwd is the
+    faces folder and no ``--project-dir`` was passed, so Python uses ``.``), treat the
+    ceiling as unbounded so we still find ``dbt_project.yml`` in a parent folder.
+    """
+    if project_dir is None:
+        return None
+    boundary = Path(project_dir).resolve()
+    if boundary == face_parent.resolve():
+        return None
+    return boundary
+
+
+def discover_render_context(
+    start_dir: Path,
+    boundary: Path | None,
+) -> tuple[Path, Path | None]:
+    """Infer project and dbt roots for a render request.
+
+    Walks upward from ``start_dir``. If ``boundary`` is None, walks until the filesystem
+    root. If set, stops after processing the ``boundary`` directory (inclusive).
+    """
+    project_root: Path | None = None
+    dbt_project_path: Path | None = None
+    start_resolved = start_dir.resolve()
+    current = start_resolved
+    boundary_resolved = boundary.resolve() if boundary is not None else None
+
+    while True:
+        if dbt_project_path is None and (current / "dbt_project.yml").exists():
+            dbt_project_path = current
+
+        if project_root is None and (
+            (current / "dataface.yml").exists()
+            or (current / "dataface.yaml").exists()
+            or (current / "_sources.yaml").exists()
+            or (current / "_sources.yml").exists()
+        ):
+            project_root = current
+
+        if current.parent == current:
+            break
+        if boundary_resolved is not None and current == boundary_resolved:
+            break
+
+        current = current.parent
+
+    if project_root is None:
+        project_root = dbt_project_path or boundary_resolved or start_resolved
+
+    return project_root, dbt_project_path
+
+
+def discover_project_root(start_dir: Path | None = None) -> Path:
+    """Walk up from *start_dir* to find the project root for ``dft serve``.
+
+    Looks for ``dataface.yml``, ``dataface.yaml``, or ``dbt_project.yml``.
+    Returns the directory containing the first match, or *start_dir* if no
+    marker is found.
+    """
+    start = (start_dir or Path.cwd()).resolve()
+    return find_dataface_project(start) or start
+
+
+def find_dataface_project(start_dir: Path) -> Path | None:
+    """Walk up from *start_dir* looking for a Dataface or dbt project marker.
+
+    Returns the first directory containing ``dataface.yml``, ``dataface.yaml``,
+    or ``dbt_project.yml``. Returns ``None`` if no marker is found before the
+    filesystem root.
+
+    Distinct from :func:`discover_project_root`, which falls back to ``start_dir``
+    when nothing is found — that fallback is right for render context but
+    wrong for MCP project targeting, where the caller must distinguish
+    "found a project" from "user is in the wrong place."
+    """
+    current = start_dir.resolve()
+    while True:
+        for marker in PROJECT_MARKERS:
+            if (current / marker).exists():
+                return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def find_git_root(start: Path) -> Path | None:
+    """Walk up from start looking for a .git directory.
+
+    Returns the directory containing .git, or None if not found before the
+    filesystem root.
+    """
+    current = start.resolve()
+    while True:
+        if (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def infer_dialect_from_dbt(
+    project_dir: Path,
+    target_name: str | None = None,
+) -> str | None:
+    """Read the resolved dbt profile target and return its adapter ``type``.
+
+    Resolution order for profiles.yml:
+      1. ``project_dir/profiles.yml``
+      2. ``~/.dbt/profiles.yml``
+
+    Returns ``None`` when the dbt project or profile cannot be resolved.
+    """
+    import yaml
+
+    dbt_project_path = project_dir / "dbt_project.yml"
+    if not dbt_project_path.exists():
+        return None
+
+    try:
+        dbt_config = yaml.safe_load(dbt_project_path.read_text()) or {}
+    except Exception:  # noqa: BLE001
+        return None
+
+    profile_name = dbt_config.get("profile")
+    if not profile_name:
+        return None
+
+    # Locate profiles.yml
+    profiles_path = project_dir / "profiles.yml"
+    if not profiles_path.exists():
+        profiles_path = Path.home() / ".dbt" / "profiles.yml"
+    if not profiles_path.exists():
+        return None
+
+    try:
+        profiles = yaml.safe_load(profiles_path.read_text()) or {}
+    except Exception:  # noqa: BLE001
+        return None
+
+    profile = profiles.get(profile_name, {})
+    target = target_name or profile.get("target", "dev")
+    target_config = profile.get("outputs", {}).get(target, {})
+    return target_config.get("type")

dataface/core/render/__init__.py

@@ -0,0 +1,87 @@
+"""Rendering stage: Face + data → output.
+
+Stage: RENDER
+Purpose: Transform compiled datafaces into visual output formats.
+
+This module provides the rendering pipeline that takes a Face
+and data (from the execute stage) and produces output in various formats
+(SVG, HTML, PNG, PDF, Terminal).
+
+Main Entry Points:
+    render(): Render a full dataface
+
+The render stage:
+1. Takes a Face (from compile stage)
+2. Uses Executor to fetch data lazily as needed
+3. Generates Vega-Lite specs for charts
+4. Produces output in requested format
+
+Supported Formats:
+    - svg: Scalable vector graphics (default)
+    - html: Interactive HTML pages with embedded charts
+    - png: Raster image format
+    - pdf: PDF documents
+    - terminal: Terminal output with ASCII/Unicode charts
+"""
+
+from dataface.core.render.chart import (
+    generate_vega_lite_spec,
+    render_table_svg,
+    slug_to_text,
+)
+from dataface.core.render.control_registry import ControlRegistry
+from dataface.core.render.errors import (
+    ChartDataError,
+    MissingRequiredVariablesError,
+    MissingVariable,
+    RenderError,
+)
+from dataface.core.render.render_result import RenderResult
+from dataface.core.render.renderer import render
+
+# Terminal rendering
+from dataface.core.render.terminal import (
+    render_chart_item_terminal,
+    render_face_terminal,
+    render_layout_item_terminal,
+)
+from dataface.core.render.terminal_charts import (
+    render_chart_terminal,
+    render_kpi_terminal,
+    render_table_terminal,
+)
+from dataface.core.render.variable_controls import (
+    generate_svg_variable_icons,
+    generate_svg_variable_script,
+    render_interactive_variables_svg,
+    render_variables_svg,
+)
+
+__all__ = [
+    # Main functions
+    "render",
+    "RenderResult",
+    # Errors
+    "ChartDataError",
+    "MissingRequiredVariablesError",
+    "MissingVariable",
+    "RenderError",
+    # Variable controls
+    "render_variables_svg",
+    "render_interactive_variables_svg",
+    "generate_svg_variable_script",
+    "generate_svg_variable_icons",
+    "ControlRegistry",
+    # Vega-Lite
+    "generate_vega_lite_spec",
+    "render_chart",
+    "render_table_svg",
+    "slug_to_text",
+    # Terminal rendering
+    "render_face_terminal",
+    "render_layout_item_terminal",
+    "render_chart_item_terminal",
+    "render_chart_terminal",
+    "render_table_terminal",
+    "render_kpi_terminal",
+]

dataface/core/render/board_links.py

@@ -0,0 +1,176 @@
+"""Board link resolution.
+
+Rewrites markdown board links at render time so authors can use
+dashboard-root-relative paths (e.g. ``/zendesk/tickets/list?status=open``)
+that work in both ``dft serve`` and Cloud.
+"""
+
+from __future__ import annotations
+
+import re
+from contextvars import ContextVar
+from dataclasses import dataclass
+from posixpath import normpath
+
+# Markdown link pattern: [text](url), excluding image syntax ![alt](src)
+_MD_LINK_RE = re.compile(r"(?<!!)\[([^\]]*)\]\(([^)]+)\)")
+
+# Suffixes stripped as author sugar
+_STRIP_SUFFIXES = (".md", ".yml", ".yaml")
+
+# Schemes that bypass rewriting. cursor://, vscode://, file:// pass through so
+# editor-deeplink URLs (e.g. ``cursor://file/{abs}/face.yaml`` from the compare
+# UI) reach the browser unchanged — both the scheme and the .yaml suffix.
+# "?" passes through so variable-update links (?var=value) reach variables.js
+# unchanged instead of being treated as relative board paths.
+_PASSTHROUGH_PREFIXES = (
+    "http://",
+    "https://",
+    "mailto:",
+    "#",
+    "?",
+    "command:",
+    "cursor://",
+    "vscode://",
+    "file://",
+)
+
+
+@dataclass(frozen=True)
+class LinkContext:
+    """Runtime context for resolving board links.
+
+    Attributes:
+        runtime: ``"serve"`` or ``"cloud"``.
+        current_board_slug: Author-space slug of the board being rendered
+            (e.g. ``"zendesk/tickets/list"``).
+        storage_prefix: On-disk directory prefix for serve mode (default ``"faces"``).
+        org_slug: Cloud organization slug (Cloud only).
+        project_slug: Cloud project slug (Cloud only).
+        branch: Current branch name to merge into outbound links (Cloud only).
+    """
+
+    runtime: str  # "serve" | "cloud"
+    current_board_slug: str = ""
+    storage_prefix: str = "faces"
+    org_slug: str = ""
+    project_slug: str = ""
+    branch: str = ""
+
+
+def resolve_href(href: str, ctx: LinkContext) -> str:
+    """Resolve a single href against *ctx*.
+
+    - External URLs (``http:``, ``https:``, ``mailto:``, ``#``) pass through.
+    - Query-string-only URLs (``?…``) pass through unchanged for variables.js interception.
+    - Root-relative (``/path``) maps from author namespace.
+    - Relative (``../``, ``./``, bare) resolves against current board directory.
+    - ``.md`` / ``.yml`` / ``.yaml`` suffixes are stripped.
+    - Cloud URLs get ``/{org}/{project}/d/{slug}/`` shape + branch merge.
+    - Serve URLs get ``/{storage_prefix}/{slug}`` shape.
+    """
+    for prefix in _PASSTHROUGH_PREFIXES:
+        if href.startswith(prefix):
+            return href
+
+    # Split path and query (can't use urlparse fully — Jinja braces aren't valid)
+    path, query = _split_path_query(href)
+
+    # Resolve path
+    if path.startswith("/"):
+        # Root-relative: strip leading slash
+        resolved = path.lstrip("/")
+    else:
+        # Relative: resolve against current board's directory
+        board_dir = "/".join(ctx.current_board_slug.split("/")[:-1])
+        resolved = normpath(f"{board_dir}/{path}") if board_dir else normpath(path)
+        # normpath may produce leading ".." — clamp to root
+        if resolved.startswith(".."):
+            resolved = resolved.lstrip("./")
+
+    # Strip author-sugar suffixes
+    for suffix in _STRIP_SUFFIXES:
+        if resolved.endswith(suffix):
+            resolved = resolved[: -len(suffix)]
+            break
+
+    # Build final URL based on runtime
+    if ctx.runtime == "cloud":
+        return _build_cloud_url(resolved, query, ctx)
+    return _build_serve_url(resolved, query, ctx)
+
+
+def _split_path_query(href: str) -> tuple[str, str]:
+    """Split href into (path, query) preserving Jinja templates in query."""
+    idx = href.find("?")
+    if idx == -1:
+        return href, ""
+    return href[:idx], href[idx + 1 :]
+
+
+def _build_serve_url(slug: str, query: str, ctx: LinkContext) -> str:
+    if ctx.storage_prefix:
+        url = f"/{ctx.storage_prefix}/{slug}"
+    else:
+        url = f"/{slug}" if slug else "/"
+    if query:
+        url = f"{url}?{query}"
+    return url
+
+
+def _build_cloud_url(slug: str, query: str, ctx: LinkContext) -> str:
+    base = f"/{ctx.org_slug}/{ctx.project_slug}/d/{slug}/"
+
+    # Merge branch if present in context and not already in query
+    if ctx.branch and not _query_has_key(query, "branch"):
+        separator = "&" if query else ""
+        query = f"{query}{separator}branch={ctx.branch}"
+
+    if query:
+        base = f"{base}?{query}"
+    return base
+
+
+def _query_has_key(query: str, key: str) -> bool:
+    """Check if *key* appears in a query string (handles Jinja-laden strings)."""
+    # Simple prefix check — good enough for branch= detection
+    return f"{key}=" in query
+
+
+# ---------------------------------------------------------------------------
+# Markdown-level rewriting
+# ---------------------------------------------------------------------------
+
+
+def rewrite_board_links(markdown: str, ctx: LinkContext | None) -> str:
+    """Rewrite board links in *markdown* using *ctx*.
+
+    Returns *markdown* unchanged when *ctx* is ``None``.
+    """
+    if ctx is None:
+        return markdown
+
+    def _replace(m: re.Match[str]) -> str:
+        text, href = m.group(1), m.group(2)
+        return f"[{text}]({resolve_href(href, ctx)})"
+
+    return _MD_LINK_RE.sub(_replace, markdown)
+
+
+# ---------------------------------------------------------------------------
+# Render-scoped context variable
+# ---------------------------------------------------------------------------
+
+_current_link_context: ContextVar[LinkContext | None] = ContextVar(
+    "_current_link_context", default=None
+)
+
+
+def get_link_context() -> LinkContext | None:
+    """Return the active link context (set by the renderer)."""
+    return _current_link_context.get()
+
+
+def set_link_context(ctx: LinkContext | None) -> None:
+    """Set the active link context for the current render pass."""
+    _current_link_context.set(ctx)