dataface 0.3.1.dev78__py3-none-any.whl → 0.3.1.dev132__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -394,7 +394,7 @@ queries:
 
   # Inline values (no database)
   sample:
-    type: values                 # Optional — also implied by `values:` presence
+    type: values                 # Optional — implied by `rows:`, `columns:`, or `values:`
     columns: [name, score]
     values:
       - [Alice, 92.4]

dataface/agent_api/__init__.py

@@ -37,6 +37,9 @@ CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
 from dataface.agent_api import skills as skills
+from dataface.agent_api._paths import (
+    project_sources_for_face as project_sources_for_face,
+)
 from dataface.agent_api.describe import (
     DescribeFaceArgs,
     DescribeFaceResult,
@@ -47,6 +50,11 @@ from dataface.agent_api.init import (
     InitResult as InitResult,
     init_project as init_project,
 )
+from dataface.agent_api.migrate import (
+    MigrateError as MigrateError,
+    MigrateSummary as MigrateSummary,
+    migrate_paths as migrate_paths,
+)
 from dataface.agent_api.project_session import ProjectSession as ProjectSession
 from dataface.agent_api.query import QueryFaceResult, query_face
 from dataface.agent_api.schema_hints import (
@@ -106,6 +114,8 @@ __all__ = [
     "InMemoryFace",
     "InitResult",
     "LinkContext",
+    "MigrateError",
+    "MigrateSummary",
     "Project",
     "ProjectSession",
     "ProjectSourcesConfig",
@@ -126,6 +136,7 @@ __all__ = [
     "describe_face",
     "get_inter_font_path",
     "init_project",
+    "migrate_paths",
     "query_face",
     "render_dashboard",
     "schema_hints",

dataface/agent_api/_paths.py

@@ -6,8 +6,9 @@ import os
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 
-# tach-ignore(agent_api->cli: runtime host-type guard in no_project_hint; the local-filesystem check needs a non-cli signal on Project — deferred)
+# tach-ignore(agent_api->cli: runtime host-type guard in resolve_face_or_error / _relpath_for_fs_location; the local-filesystem check needs a non-cli signal on Project — deferred)
 from dataface.cli.filesystem_project import FilesystemProject
+from dataface.core.compile.config import ProjectSourcesConfig
 from dataface.core.diagnostics import (
     ERR_FILE_NOT_FOUND,
     ERR_INTERNAL,
@@ -27,54 +28,6 @@ from dataface.core.project_roots import (
 )
 
 
-def resolve_project_dir(project_dir: Path | None) -> Path:
-    """Resolve the caller's `project_dir`, walking up from cwd when omitted.
-
-    Boundary helper: every agent_api / CLI callsite that today forwards a
-    possibly-None `project_dir` into a core helper routes through this so the
-    cwd read stays at the agent_api boundary, not inside `dataface/core`.
-    """
-    if project_dir is not None:
-        return project_dir.resolve()
-    cwd = Path.cwd().resolve()
-    return find_dft_root(cwd) or cwd
-
-
-def resolve_project_dir_from_paths(
-    paths: list[Path] | None, project_dir: Path | None
-) -> Path:
-    """Resolve project_dir for a multi-path CLI verb (validate / describe).
-
-    Explicit `--project-dir` wins. Otherwise, when all supplied paths are
-    absolute, walk up from the first path's parent to anchor on the project
-    that contains the file. Otherwise fall back to a cwd walk.
-    """
-    if project_dir is not None:
-        return project_dir.resolve()
-    if paths and all(p.is_absolute() for p in paths):
-        anchor = paths[0].parent.resolve()
-        return find_dft_root(anchor) or anchor
-    return resolve_project_dir(None)
-
-
-def no_project_hint(project: Project) -> str:
-    """Return a hint string when no project marker is found, else empty string.
-
-    Only walks the local filesystem for a `FilesystemProject` — a non-filesystem
-    host's `project.root` is not a real on-disk project directory (it's the
-    server cwd), so there is no marker to walk up to and nothing to hint about.
-    """
-    if not isinstance(project, FilesystemProject):
-        return ""
-    project_root = project.root
-    if find_dft_root(project_root) is not None:
-        return ""
-    return (
-        f" No Dataface project marker found at or above {project_root}."
-        f" Run from inside a Dataface project, or set project_dir."
-    )
-
-
 def resolve_face_relpath(relpath: PurePosixPath, project: Project) -> ProjectPath:
     """Project-relative face identity -> ProjectPath, with the faces-first retry.
 
@@ -179,7 +132,6 @@ def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic
         return DatafaceError.from_code(
             ERR_FILE_NOT_FOUND,
             path=resolved.relpath,
-            hint=no_project_hint(project),
         ).to_diagnostic(file=resolved.relpath)
     if (
         isinstance(project, FilesystemProject)
@@ -269,3 +221,26 @@ def build_yaml_render_context(
         project_root=project_root,
         output_dir=project_root,
     )
+
+
+def project_sources_for_face(face_path: Path) -> ProjectSourcesConfig:
+    """The `sources:` registry of the project owning ``face_path``.
+
+    Editor surfaces compile buffer text rather than a file on disk, so they
+    have no `Project` to hand `compile()` — but without the source registry
+    compile cannot tell a query's SQL dialect, and dialect is what makes a SQL
+    parse finding trustworthy enough to report.
+
+    A face outside any project needs no special case: `find_project_root`
+    falls back to the starting directory, which has no `dataface.yml`, and the
+    registry comes back empty — compile then stays silent about SQL syntax
+    rather than guessing a dialect.
+
+    A `dataface.yml` that exists but does not load raises, deliberately. That
+    is a real fault at a real location, and swallowing it here would decide on
+    the author's behalf that a broken project config is invisible — while
+    handing the caller an empty registry indistinguishable from "no project".
+    Callers attribute the failure; they do not get to pretend it did not
+    happen.
+    """
+    return FilesystemProject(find_project_root(face_path.parent, None)).sources

dataface/agent_api/board_artifact.py

@@ -70,7 +70,7 @@ class RenderBoardArtifactResult(BaseModel):
 
 def _read_or_error(path: Path) -> bytes:
     if not path.exists():
-        raise DatafaceError.from_code(ERR_FILE_NOT_FOUND, path=str(path), hint="")
+        raise DatafaceError.from_code(ERR_FILE_NOT_FOUND, path=str(path))
     return path.read_bytes()
 
 

dataface/agent_api/describe.py

@@ -197,19 +197,15 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
             ],
         )
 
-    return _describe_resolved(resolved, project=project)
+    return _describe_resolved(resolved)
 
 
-def _describe_resolved(
-    resolved: ProjectPath, *, project: Project
-) -> DescribeFaceResult:
+def _describe_resolved(resolved: ProjectPath) -> DescribeFaceResult:
     """Describe an already-resolved face path — no re-resolution."""
-    from dataface.agent_api._paths import no_project_hint
     from dataface.core.compile.compiler import compile_file
     from dataface.core.diagnostics.base import DatafaceError
 
     if not resolved.exists():
-        hint = no_project_hint(project)
         return DescribeFaceResult(
             success=False,
             path=Path(resolved.relpath),
@@ -217,7 +213,6 @@ def _describe_resolved(
                 DatafaceError.from_code(
                     ERR_FILE_NOT_FOUND,
                     path=resolved.relpath,
-                    hint=hint,
                 ).to_diagnostic()
             ],
         )
@@ -349,7 +344,7 @@ def _describe_one_path(
         ]
 
     if resolved.is_yaml:
-        return [_describe_resolved(resolved, project=project)]
+        return [_describe_resolved(resolved)]
 
     faces = sorted(
         pf
@@ -371,4 +366,4 @@ def _describe_one_path(
                 ],
             )
         ]
-    return [_describe_resolved(pf, project=project) for pf in faces]
+    return [_describe_resolved(pf) for pf in faces]

dataface/agent_api/docs/yaml-reference.md

@@ -15,7 +15,7 @@ AuthoredFace (dataface) definition from YAML.
 | `source` | str | ✓ | Default source name for all queries in this face. Inheritable via meta.yaml cascade. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
-| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
+| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
 | `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order. |
 | `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
 | `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
@@ -55,7 +55,7 @@ Variable definition from YAML.
 | `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
 | `enabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default). |
 | `column` | str | ✓ | Column name in the query result to use as option values. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) | ✓ | Query name or inline query definition for populating options. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) | ✓ | Query name or inline query definition for populating options. |
 | `dimension` | str | ✓ | MetricFlow dimension name for populating options. |
 | `measure` | str | ✓ | MetricFlow measure name for populating options. |
 | `model` | str | ✓ | dbt model name for populating options. |
@@ -104,12 +104,12 @@ REST API query.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `url` | str |  | HTTP endpoint URL for REST API queries. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "http" | ✓ | Query adapter type. |
-| `url` | str | ✓ | HTTP endpoint URL for REST API queries. |
 | `method` | enum: "GET", "POST", "PUT", "DELETE", "PATCH" | ✓ | HTTP method (GET, POST, PUT, DELETE, PATCH). |
 | `headers` | dict[str, str] | ✓ | HTTP request headers. |
 | `params` | dict[str, Any] | ✓ | HTTP query string parameters. |
@@ -119,18 +119,30 @@ REST API query.
 
 <a id="valuesquery"></a>
 ## ValuesQuery
-Inline rows embedded in YAML.
+Inline data authored as a list of row mappings.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `rows` | list[dict[str, Any]] |  | Inline data rows (list of row dicts). Use the compact columns-and-values form instead when row values are positional. |
+| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
+| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
+| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
+| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `type` | enum: "values" | ✓ | Query adapter type. |
+
+<a id="compactvaluesquery"></a>
+## CompactValuesQuery
+Inline data authored as column names plus positional row values.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `columns` | list[str] |  | Column names for the compact syntax. Every compact values query also requires values. |
+| `values` | list[list[Any]] |  | Inline row-oriented data (list of lists) for the compact syntax. Every compact values query also requires columns. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "values" | ✓ | Query adapter type. |
-| `rows` | list[dict[str, Any]] | ✓ | Inline data rows (list of row dicts). |
-| `values` | list[list[Any]] | ✓ | Inline row-oriented data (list of lists) for the compact 'columns + values' syntax. |
-| `columns` | list[str] | ✓ | Column names for the compact 'columns + values' syntax. |
 
 <a id="schemaquery"></a>
 ## SchemaQuery
@@ -149,17 +161,40 @@ dbt source schema query.
 
 <a id="lookmlquery"></a>
 ## LookmlQuery
-LookML semantic query — compiled to SQL through likeml at compile time.
+LookML query rooted at one explore.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `explore` | str |  | LookML explore name. Presence of this key infers type: lookml. Use a merge query instead to combine multiple sources. |
+| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
+| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
+| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
+| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
+| `type` | enum: "lookml" | ✓ | Query adapter type. |
+| `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
+| `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
+| `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
+| `pivots_unwrapped` | bool | ✓ | Which of Looker's two pivot SQL shapes to emit: False/None = wrapped (5-layer DENSE_RANK), True = plain GROUP BY. |
+| `total` | bool | ✓ | Looker grand-totals flag. |
+| `subtotals` | list[str] | ✓ | Dimension refs to subtotal via GROUP BY ROLLUP. |
+| `filter_expression` | str | ✓ | Looker query-level free-form boolean filter over ${view.field} refs. |
+| `dynamic_fields` | list[dict[str, Any]] | ✓ | Looker dynamic fields: custom measures / custom dimensions synthesized into SQL. Table calculations compose as a derived wrapper query, not here. |
+| `limit` | int | ✓ | Maximum number of rows returned. |
+| `column_limit` | int | ✓ | Looker column_limit — caps wrapped-pivot columns. |
+| `filters` | dict[str, Any] | ✓ | RAW Looker filter expressions keyed by 'view.field' (e.g. "13 months", "gold") — translated to SQL predicates by likeml. |
+
+<a id="lookmlmergequery"></a>
+## LookmlMergeQuery
+LookML query that merges multiple sources.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `merge` | list[dict[str, Any]] |  | LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's `merge_on` maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml. |
 | `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
 | `type` | enum: "lookml" | ✓ | Query adapter type. |
-| `explore` | str | ✓ | LookML explore name. Presence of this key infers type: lookml. |
-| `merge` | list[dict[str, Any]] | ✓ | LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's `merge_on` maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml. |
 | `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
 | `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
 | `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
@@ -182,7 +217,7 @@ Authored patch for bar and histogram charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -211,7 +246,7 @@ Authored patch for line charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -240,7 +275,7 @@ Authored patch for area charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -269,7 +304,7 @@ Authored patch for scatter charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -299,7 +334,7 @@ Authored patch for heatmap charts.
 | `type` | enum: "heatmap" |  | Heatmap chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -328,7 +363,7 @@ Authored patch for pie and donut charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -351,7 +386,7 @@ Authored patch for KPI (key performance indicator) charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -371,7 +406,7 @@ Authored patch for table charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -392,7 +427,7 @@ Authored patch for point_map and bubble_map charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -409,7 +444,7 @@ Authored patch for point_map and bubble_map charts.
 | `latitude` | str | ✓ | Column containing latitude values for point/bubble maps. |
 | `longitude` | str | ✓ | Column containing longitude values for point/bubble maps. |
 | `size` | str | ✓ | Data column used to scale bubble radius (quantitative). Only meaningful on bubble_map. |
-| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Tile-layer configuration for the map background. |
+| `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Styled geographic background layer. |
 | `style` | [PointMapChartStyle](#pointmapchartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="geoshapechart"></a>
@@ -422,7 +457,7 @@ Authored patch for map and geoshape charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -459,7 +494,7 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `type` | enum: "spark_bar" |  | SparkBar chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
 | `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
@@ -929,14 +964,11 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 
 <a id="basemapconfig"></a>
 ## BasemapConfig
-Tile-layer configuration for point_map and bubble_map charts.
+Styled geographic background layer for point_map and bubble_map charts.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | str | ✓ | Tile provider type (e.g. 'mapbox', 'raster'). |
-| `style` | str | ✓ | Tile style URL (e.g. Mapbox style URI). |
 | `source` | str | ✓ | Named geographic boundary source (e.g. 'us-states') for overlay rendering. |
-| `attribution` | str | ✓ | Attribution text for the tile provider. |
 | `fill` | str | ✓ | Fill color for geographic boundary overlay. |
 | `stroke` | str | ✓ | Stroke color for geographic boundary overlay. |
 

dataface/agent_api/migrate.py

@@ -0,0 +1,101 @@
+"""Typed API for rewriting retained face YAML grammars."""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dataface.agent_api._paths import resolve_face_relpath
+from dataface.core.project import FACES_SUBDIR, Project, ProjectPath
+
+
+class MigrateError(BaseModel):
+    """One file that could not be migrated without manual action."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    path: PurePosixPath = Field(
+        description="Project-relative path that requires manual action."
+    )
+    message: str = Field(description="User-ready explanation of the migration failure.")
+
+
+class MigrateSummary(BaseModel):
+    """Results of a migration run, separated by outcome."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    updated: list[PurePosixPath] = Field(
+        default_factory=list,
+        description="Files that were migrated, or would be migrated during a dry run.",
+    )
+    current: list[PurePosixPath] = Field(
+        default_factory=list,
+        description="Files that already satisfy the current YAML grammar.",
+    )
+    errors: list[MigrateError] = Field(
+        default_factory=list,
+        description="Files that require manual migration.",
+    )
+
+    @property
+    def success(self) -> bool:
+        return not self.errors
+
+
+def migrate_paths(
+    paths: list[PurePosixPath] | None,
+    *,
+    project: Project,
+    dry_run: bool,
+) -> MigrateSummary:
+    """Migrate named face files/directories, or all public faces by default."""
+    updated: list[PurePosixPath] = []
+    current: list[PurePosixPath] = []
+    errors: list[MigrateError] = []
+    for face_path in _migration_paths(paths, project):
+        path = PurePosixPath(face_path.relpath)
+        try:
+            original = face_path.read_text()
+            from dataface.core.compile.migrations import migrate_face_yaml_text
+            from dataface.core.compile.parser import parse_yaml
+
+            migrated = migrate_face_yaml_text(original)
+            if migrated == original:
+                current.append(path)
+                continue
+            parse_yaml(migrated)
+            if not dry_run:
+                project.write_text(face_path.relpath, migrated)
+            updated.append(path)
+        except (OSError, ValueError) as exc:
+            errors.append(MigrateError(path=path, message=str(exc)))
+    return MigrateSummary(
+        updated=updated,
+        current=current,
+        errors=errors,
+    )
+
+
+def _migration_paths(
+    paths: list[PurePosixPath] | None, project: Project
+) -> list[ProjectPath]:
+    if not paths:
+        return [
+            path
+            for path in project.iter_faces(under=FACES_SUBDIR)
+            if path.is_yaml and not path.is_private and not path.is_meta
+        ]
+    resolved: list[ProjectPath] = []
+    for path in paths:
+        selected = resolve_face_relpath(path, project)
+        if selected.is_yaml:
+            resolved.append(selected)
+            continue
+        resolved.extend(
+            child
+            for child in project.iter_faces(under=selected.relpath)
+            if child.is_yaml and not child.is_private and not child.is_meta
+        )
+    return resolved

dataface/agent_api/project_session.py

@@ -6,7 +6,7 @@ import importlib.util
 import sys
 from dataclasses import dataclass
 from functools import cached_property
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
 if sys.version_info >= (3, 11):
@@ -20,11 +20,13 @@ from dataface.agent_api import (
     board_artifact as _board_artifact,
     describe as _describe,
     describe_query as _describe_query,
+    migrate as _migrate,
     query as _query,
     search as _search,
     validate as _validate,
 )
 from dataface.agent_api.board_artifact import EmitBoardArtifactResult
+from dataface.agent_api.migrate import MigrateSummary
 from dataface.agent_api.validate import (
     ValidateResult,
 )
@@ -291,6 +293,16 @@ class ProjectSession:
         results = _validate.validate_paths(paths, project=self.project)
         return _validate.annotate_with_data_lint(results, project=self.project)
 
+    def migrate_paths(
+        self, paths: list[PurePosixPath] | None, *, dry_run: bool
+    ) -> MigrateSummary:
+        """Rewrite supported retired YAML syntax without touching current files."""
+        return _migrate.migrate_paths(
+            paths,
+            project=self.project,
+            dry_run=dry_run,
+        )
+
     @overload
     def validate_query(
         self,

dataface/agent_api/query.py

@@ -280,12 +280,7 @@ def query_face(
 
     resolved_display = PurePosixPath(file_path.relpath)
     if not file_path.exists():
-        from dataface.agent_api._paths import no_project_hint
-
-        hint = no_project_hint(project)
-        return _fail(
-            name, resolved_display, [f"File not found: {resolved_display}{hint}"]
-        )
+        return _fail(name, resolved_display, [f"File not found: {resolved_display}"])
 
     compile_result = compile_file(file_path.read_face())
     if not compile_result.success: