dataface 0.1.5.dev215__py3-none-any.whl → 0.1.5.dev278__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -19,7 +19,7 @@ dft validate faces/my_dashboard.yml
 To verify that your database connection works, run a simple query:
 
 ```bash
-dft query <your_source> 'SELECT 1'
+dft query 'SELECT 1' --source <your_source>
 ```
 
 A successful result means your data source is reachable.
@@ -138,7 +138,7 @@ variables:
   region:
     input: select                  # See `dft docs variables` for all 14 input types
     options: { static: [US, EU, APAC] }
-    # No default: starts on All regions
+    default: US
 ```
 
 Reference variables inside queries with bare `{{ region }}` — no `variables.` prefix.
@@ -238,6 +238,27 @@ Top-level fields (23 total):
 
 `face:` as a top-level key is rejected. Put face properties (title, rows, queries, …) directly at the YAML root.
 
+### Aliases
+
+`aliases:` is a list of absolute URL paths that 302-redirect to this face's canonical file-path URL.  Each entry must start with `/`; trailing slashes are normalized automatically.
+
+```yaml
+aliases:
+  - /old-reports/
+  - /legacy/sales/
+```
+
+Rules:
+- An alias must not collide with a real face file path — the server raises an error at startup if it does.
+- Each alias must be unique across the project — two faces claiming the same alias is a startup error.
+- Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
+
+There are two ways to override a data/inspector route for a given path:
+- **Face file at that path** — create `faces/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
+- **`aliases:` entry** — any face can declare `/data/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.
+
+Both approaches work.  A face file wins without a redirect round-trip; an alias lets a face live anywhere and still capture a system-view URL.
+
 ### Board style
 
 `style:` on a face, nested face, or layout section accepts a fixed set of keys — not arbitrary CSS:
@@ -346,7 +367,7 @@ queries:
       - [Bob, 87.1]
 ```
 
-Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema` is internal-only and not part of the authored surface.
+Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema_resolver` is internal-only and not part of the authored surface.
 
 Common fields (all query types):
 
@@ -461,7 +482,6 @@ charts:
 
     # Style + behavior
     sort: { by: total, order: desc }
-    format: integer           # named alias or raw D3 spec (e.g. ",.0f")
     x_label: "Month"
     y_label: "Revenue (USD)"
     link: "/orders?month={{ month }}"      # Click-through URL template (drill-down)
@@ -469,6 +489,7 @@ charts:
 
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
       orientation: vertical   # style: does NOT accept height or aspect_ratio
+      number_format: ",.0f"   # D3 format string or named alias for axis/tooltip format
       stack: zero               # false | true | zero | normalize | center
 ```
 
@@ -597,14 +618,12 @@ support:                # Optional support line (same shape: value/label/format/
   glyph: "▲"
   tone: positive
 
-# table — renders all query columns unless `style.columns` selects a subset.
-# `columns` is a MAPPING keyed by column name (NOT a list). Omit it to show
-# every query column; include it to choose a subset and/or style columns.
+# table — renders all query columns unless `style.columns` selects a subset
 type: table
 style:
   columns:
-    order_id: {}                         # include with default styling
-    amount:                              # the key is the column name
+    - column: order_id
+    - column: amount
       label: Amount
       format: currency_whole
       align: right                       # left | center | right
@@ -700,7 +719,7 @@ layers:
     y: target
     label: Target
     axis_y:
-      orient: right                 # left | right
+      position: right            # left | right
       title: "Target"
 ```
 
@@ -846,7 +865,7 @@ variables:
     description: "Restrict every query to one region."
     options:
       static: [US, EU, APAC]
-    # No default: starts on All regions
+    default: US
 ```
 
 Input types (14 total):
@@ -878,6 +897,7 @@ Common variable fields:
 | `default` | any | Default value when no URL param is set |
 | `placeholder` | string | Placeholder text |
 | `required` | bool | Block rendering until a value exists |
+| `allow_null` | bool | `null` is a valid selection |
 | `visible` | bool | Hidden when `false`; still settable via URL param |
 | `disabled` | bool \| string \| `{query, column}` | Static, Jinja expr, or query-backed disable |
 | `data_type` | string | Upstream type hint (informational; preserved through migrations) |
@@ -893,7 +913,7 @@ variables:
   product:
     input: select
     options:
-      static: [Electronics, Clothing]         # Hardcoded list; blank -- All -- is implicit
+      static: [All, Electronics, Clothing]    # Hardcoded list
       # OR
       query: products_list                     # Query whose first column is the option list
       column: product_name                     # Optional: which column in that query
@@ -906,25 +926,23 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
-Variables are optional by default. For `select` and `multiselect`, omitting `default` starts the variable unset. The renderer adds a blank `-- All --` option for that unset state; `{{ filter('column', variable) }}` emits `1=1` unless the SQL call site opts into `none='deny'`. Add `required: true` only when the dashboard cannot render without a value.
-
-Disabled forms:
+Enabled/disabled forms (`enabled: false` means the control is inactive):
 
 ```yaml
 variables:
-  # Static bool
-  closed: { input: checkbox, disabled: true }
+  # Static bool — enabled: false disables the control
+  closed: { input: checkbox, enabled: false }
 
   # Jinja expression against current variable values
-  q4_only: { input: select, options: { static: [Q4] }, disabled: "{{ year < 2024 }}" }
+  q4_only: { input: select, options: { static: [Q4] }, enabled: "{{ year >= 2024 }}" }
 
   # Query-backed (must return exactly 1 row with the named boolean column)
   territory:
     input: select
     options: { query: territory_options }
-    disabled:
+    enabled:
       query: control_state
-      column: territory_disabled
+      column: territory_enabled
 ```
 
 **Multiselect SQL antipattern** — the first instinct for filtering a multiselect variable in SQL is `IN ({{ plans | map('tojson') | join(', ') }})`. This is wrong: `tojson` produces double-quoted strings (`"trial"`), which most SQL dialects (including DuckDB) treat as *column references*, not string literals. The query silently returns an empty result and `dft render` exits 0.

dataface/__init__.py

@@ -22,7 +22,8 @@ Quick Start:
     ...     face = result.face
     ...
     ...     # Create executor and render
-    ...     registry = build_adapter_registry(Path.cwd())
+    ...     from dataface.core.compile.config import load_project_sources
+    ...     registry = build_adapter_registry(Path.cwd(), project_sources=load_project_sources(Path.cwd()))
     ...     executor = Executor(face, registry, query_registry=result.query_registry)
     ...     svg = render(face, executor, format="svg")
 """

dataface/agent_api/__init__.py

@@ -37,10 +37,6 @@ CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
 from dataface.agent_api import skills as skills
-from dataface.agent_api.dashboards import (
-    RenderedDashboard as RenderedDashboard,
-    render_dashboard as render_dashboard,
-)
 from dataface.agent_api.describe import (
     DescribeFaceArgs,
     DescribeFaceResult,
@@ -53,8 +49,24 @@ from dataface.agent_api.init import (
 )
 from dataface.agent_api.project import Project as Project
 from dataface.agent_api.query import QueryFaceResult, query_face
+from dataface.agent_api.schema_hints import (
+    SchemaHints as SchemaHints,
+    schema_hints as schema_hints,
+)
 from dataface.agent_api.validate import ValidateDashboardArgs, ValidateResult
+from dataface.agent_api.validate_query import (
+    QueryDiagnostic as QueryDiagnostic,
+    validate_query as validate_query,
+)
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
+from dataface.core.dashboard import (
+    RenderedDashboard as RenderedDashboard,
+    render_dashboard as render_dashboard,
+)
+from dataface.core.errors.structured import StructuredError as StructuredError
+from dataface.core.fonts import get_inter_font_path as get_inter_font_path
+from dataface.core.render.board_links import LinkContext as LinkContext
+from dataface.core.render.errors import RenderError as RenderError
 
 __all__ = [
     "DescribeFaceArgs",
@@ -63,15 +75,23 @@ __all__ = [
     "DocsResult",
     "DocsSearchHit",
     "InitResult",
+    "LinkContext",
     "Project",
     "ProjectSourcesConfig",
+    "QueryDiagnostic",
     "QueryFaceResult",
     "RenderedDashboard",
+    "RenderError",
+    "SchemaHints",
+    "StructuredError",
     "Topic",
     "ValidateDashboardArgs",
     "ValidateResult",
     "describe_face",
+    "get_inter_font_path",
     "init_project",
     "query_face",
     "render_dashboard",
+    "schema_hints",
+    "validate_query",
 ]

dataface/agent_api/_init_templates/guide.yaml

@@ -82,7 +82,9 @@ charts:
     query: kpi_summary
     label: Total Revenue (H1)
     value: total_revenue
-    format: currency_compact
+    style:
+      value:
+        format: currency_compact
     support:
       value: revenue_delta
       label: vs H1 last year
@@ -95,7 +97,9 @@ charts:
     query: kpi_summary
     label: Avg Deal Size
     value: avg_deal
-    format: currency_compact
+    style:
+      value:
+        format: currency_compact
 
   data_table:
     type: table

dataface/agent_api/dashboards.py

@@ -3,10 +3,6 @@
 All public functions have concrete typed arguments and typed Pydantic return
 values. No bare dict[str, Any] in any return position. Tool/CLI callers use
 .model_dump() at the wire boundary.
-
-`RenderedDashboard` and `render_dashboard` live in `dataface.core.dashboard`
-so the embedded HTTP server can call them without inverting the layer stack; they
-are re-exported here so the agent_api thin-wrapper rule still holds.
 """
 
 from __future__ import annotations
@@ -20,10 +16,7 @@ from pydantic import BaseModel, Field
 from dataface.agent_api._paths import resolve_scoped_path
 from dataface.core.compile import Face, compile_file
 from dataface.core.compile.errors import DatafaceError
-from dataface.core.dashboard import (
-    RenderedDashboard as RenderedDashboard,
-    render_dashboard as render_dashboard,
-)
+from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
 from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
 from dataface.core.render.warnings.base import RenderWarning
 

dataface/agent_api/data_paths.py

@@ -0,0 +1,225 @@
+"""Data URL surfacing and alias typo lint.
+
+Provides:
+- DataPathInfo: the agent-facing wire shape for a canonical data URL
+  (url, resolves_to: "generic" | "authored", face)
+- data_paths_for_source/schema/table: compute data URLs and check the
+  alias index to determine whether a face overrides the generic system view
+- data_paths_list: flat list of DataPathInfo (source + schema + table level)
+  from a SchemaResponse — used for --data-paths CLI flag and agent discovery
+- validate_data_aliases: typo lint for /data/ prefixed aliases — checks
+  source names only (config only, no DB connection required).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from dataface.core.registered_views.data_urls import (
+    data_schema_url,
+    data_source_url,
+    data_table_url,
+)
+
+if TYPE_CHECKING:
+    from dataface.agent_api.schema import SchemaResponse
+    from dataface.core.serve.alias_index import AliasIndex
+
+
+@dataclass
+class DataPathInfo:
+    """Canonical data URL with resolution status.
+
+    Wire shape (pinned by contract test — any change is a breaking API change):
+        {"url": "/data/src/schema/table/", "resolves_to": "generic"}
+        {"url": "...", "resolves_to": "authored", "face": "/sales/"}
+    """
+
+    url: str
+    resolves_to: Literal["generic", "authored"]
+    face: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the agent wire shape, omitting face when generic."""
+        d: dict[str, Any] = {"url": self.url, "resolves_to": self.resolves_to}
+        if self.face is not None:
+            d["face"] = self.face
+        return d
+
+
+def data_paths_for_source(
+    source: str,
+    *,
+    alias_index: AliasIndex,
+) -> DataPathInfo:
+    """Return the data URL info for a source.
+
+    The canonical URL is /data/<source>/. When a face aliases it the
+    resolves_to is 'authored' and face is the canonical face URL.
+    """
+    url = data_source_url(source)
+    face = alias_index.lookup(url)
+    if face is not None:
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
+
+
+def data_paths_for_schema(
+    source: str,
+    schema: str,
+    *,
+    alias_index: AliasIndex,
+) -> DataPathInfo:
+    """Return the data URL info for a schema.
+
+    The canonical URL is /data/<source>/<schema>/. When a face aliases it
+    the resolves_to is 'authored' and face is the canonical face URL.
+    """
+    url = data_schema_url(source, schema)
+    face = alias_index.lookup(url)
+    if face is not None:
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
+
+
+def data_paths_for_table(
+    source: str,
+    schema: str,
+    table: str,
+    *,
+    alias_index: AliasIndex,
+) -> DataPathInfo:
+    """Return the data URL info for a table.
+
+    The canonical URL is /data/<source>/<schema>/<table>/. When a face
+    aliases it the resolves_to is 'authored' and face is the canonical face URL.
+    """
+    url = data_table_url(source, schema, table)
+    face = alias_index.lookup(url)
+    if face is not None:
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
+
+
+def validate_data_aliases(
+    aliases: list[str],
+    *,
+    source_names: frozenset[str],
+) -> list[str]:
+    """Lint /data/ prefixed aliases against configured source names.
+
+    Called at dft-validate time (connection-free). Checks that every
+    /data/ URL references a known source, and errors with available
+    sources as a hint when not.
+
+    Returns a list of error message strings (empty = all valid).
+    Aliases not prefixed with /data/ are silently skipped.
+    """
+    errors: list[str] = []
+    for raw_alias in aliases:
+        # Normalize: trailing-slash canonical, strip percent-encoding
+        from urllib.parse import unquote
+
+        alias = unquote(raw_alias)
+        if not alias.endswith("/"):
+            alias = alias + "/"
+
+        if not alias.startswith("/data/"):
+            continue
+
+        # Strip leading "/data/" and trailing "/" to get segments
+        inner = alias[len("/data/") :]
+        if inner.endswith("/"):
+            inner = inner[:-1]
+        segments = [s for s in inner.split("/") if s]
+
+        if not segments:
+            # Bare /data/ — no validation needed
+            continue
+
+        # Segment 0: source
+        source = segments[0]
+        if source not in source_names:
+            available = sorted(source_names)
+            hint = (
+                f"available sources: {', '.join(available)}"
+                if available
+                else "no sources configured"
+            )
+            errors.append(
+                f"Data alias {raw_alias!r} references unknown source {source!r}. "
+                f"Did you mean one of: {hint}"
+            )
+
+    return errors
+
+
+def data_paths_list(
+    schema_response: SchemaResponse,
+    *,
+    alias_index: AliasIndex,
+) -> list[DataPathInfo]:
+    """Build a flat list of DataPathInfo from a SchemaResponse.
+
+    Iterates all sources → schemas → tables in the response and returns one
+    DataPathInfo per source, per schema, and per table, checking the alias
+    index for author overrides at each level.
+    """
+    result: list[DataPathInfo] = []
+    for source_name, source_data in schema_response.sources.items():
+        result.append(data_paths_for_source(source_name, alias_index=alias_index))
+        for schema_name, schema_data in (source_data.get("schemas") or {}).items():
+            result.append(
+                data_paths_for_schema(source_name, schema_name, alias_index=alias_index)
+            )
+            for table_name in schema_data.get("tables") or {}:
+                result.append(
+                    data_paths_for_table(
+                        source_name,
+                        schema_name,
+                        table_name,
+                        alias_index=alias_index,
+                    )
+                )
+    return result
+
+
+def build_alias_index_for_project(project_dir: Path) -> AliasIndex:
+    """Build an AliasIndex from a project directory.
+
+    Uses the same faces_at_root detection logic as the server. Intended for
+    CLI commands (dft schema --data-paths) that need alias lookup without
+    starting a server.
+    """
+    from dataface.core.serve.alias_index import AliasIndex
+
+    faces_dir = project_dir / "faces"
+    faces_at_root = faces_dir.is_dir()
+    return AliasIndex.build(
+        project_dir=project_dir,
+        faces_dir=faces_dir,
+        faces_at_root=faces_at_root,
+    )
+
+
+def data_alias_errors_for_file(
+    face_file: Path,
+    source_names: frozenset[str],
+) -> list[str]:
+    """Read aliases from a face file and lint any /data/ prefixed ones.
+
+    Source-name check only — no DB connection, no resolver. Called from the
+    validate path which must stay connection-free.
+
+    Returns a list of error message strings; empty means no data alias issues.
+    Silently returns [] when the file cannot be parsed (compile catches that).
+    """
+    from dataface.core.serve.alias_index import read_aliases_from_file
+
+    try:
+        aliases = read_aliases_from_file(face_file)
+    except ValueError:
+        return []  # compile path reports alias parse errors with better context
+    return validate_data_aliases(aliases, source_names=source_names)