dataface 0.1.2__py3-none-any.whl

dataface/core/compile/schema_renderers/vscode_schema.py

@@ -0,0 +1,301 @@
+"""VS Code JSON Schema renderer — wraps render_json_schema with IDE-specific decoration.
+
+Calls render_json_schema(ir) for the IR-driven core, then adds the IDE-specific
+extras that have no Pydantic counterpart (fileMatch, layout anyOf constraint,
+theme enum, chart type aliases, LayoutItem definition, Source oneOf).
+
+Entry point: render_vscode_schema(schema, *, themes, chart_aliases) -> dict
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface.core.compile.introspection import AuthorableSchema
+from dataface.core.compile.schema_renderers.json_schema import render_json_schema
+
+_SOURCE_CONNECTOR_NAMES = (
+    "PostgresSourceConfig",
+    "SnowflakeSourceConfig",
+    "BigQuerySourceConfig",
+    "RedshiftSourceConfig",
+    "MySQLSourceConfig",
+    "DuckDBSourceConfig",
+    "CsvSourceConfig",
+    "ParquetSourceConfig",
+    "JsonSourceConfig",
+    "HttpSourceConfig",
+    "DbtProfileSourceConfig",
+)
+
+
+def _rename_defs(obj: Any) -> Any:
+    """Deep-walk obj, renaming $defs → definitions and updating $ref strings."""
+    if isinstance(obj, dict):
+        return {
+            ("definitions" if k == "$defs" else k): _rename_defs(v)
+            for k, v in obj.items()
+        }
+    if isinstance(obj, list):
+        return [_rename_defs(item) for item in obj]
+    if isinstance(obj, str) and obj.startswith("#/$defs/"):
+        return "#/definitions/" + obj[len("#/$defs/") :]
+    return obj
+
+
+def _extract_description(prop: dict[str, Any]) -> str:
+    if "description" in prop:
+        return prop["description"]
+    for branch in prop.get("anyOf", []):
+        if "description" in branch:
+            return branch["description"]
+    return ""
+
+
+def _build_layout_item_def() -> dict[str, Any]:
+    return {
+        "oneOf": [
+            {"type": "string", "description": "Chart name reference."},
+            {"$ref": "#/definitions/AuthoredChart"},
+            {
+                "type": "object",
+                "description": "Nested layout.",
+                "properties": {
+                    "rows": {
+                        "type": "array",
+                        "items": {"$ref": "#/definitions/LayoutItem"},
+                        "description": "Nested vertical layout items.",
+                    },
+                    "cols": {
+                        "type": "array",
+                        "items": {"$ref": "#/definitions/LayoutItem"},
+                        "description": "Nested horizontal layout items.",
+                    },
+                    "grid": {
+                        "allOf": [{"$ref": "#/definitions/GridLayout"}],
+                        "description": "Nested grid layout.",
+                    },
+                    "tabs": {
+                        "allOf": [{"$ref": "#/definitions/TabLayout"}],
+                        "description": "Nested tab layout.",
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "Section title.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Section description.",
+                    },
+                    "details": {
+                        "anyOf": [
+                            {
+                                "type": "string",
+                                "description": "String shorthand: sets the summary label.",
+                            },
+                            {
+                                "type": "object",
+                                "properties": {
+                                    "summary": {
+                                        "type": "string",
+                                        "description": "Label shown when collapsed.",
+                                    },
+                                    "expanded_title": {
+                                        "type": "string",
+                                        "description": "Label shown when expanded.",
+                                    },
+                                    "expanded": {
+                                        "type": "boolean",
+                                        "default": False,
+                                        "description": "Default open state.",
+                                    },
+                                },
+                                "required": ["summary"],
+                                "additionalProperties": False,
+                            },
+                        ],
+                        "description": "Collapsible section. String shorthand → FaceDetails(summary=str).",
+                    },
+                    "style": {
+                        "type": "object",
+                        "description": "CSS-like style overrides for this section.",
+                    },
+                },
+            },
+        ]
+    }
+
+
+def _decorate_for_vscode(
+    base: dict[str, Any],
+    themes: list[str],
+    chart_aliases: dict[str, str],
+) -> dict[str, Any]:
+    schema = _rename_defs(base)
+    props = schema.setdefault("properties", {})
+    defns = schema.setdefault("definitions", {})
+
+    # IDE metadata
+    schema["title"] = "Dataface Dashboard"
+    schema["fileMatch"] = [
+        "*.dataface.yml",
+        "*.dataface.yaml",
+        "dataface.yml",
+        "dataface.yaml",
+    ]
+    schema["anyOf"] = [
+        {"required": ["rows"]},
+        {"required": ["cols"]},
+        {"required": ["grid"]},
+        {"required": ["tabs"]},
+        {"required": ["charts"]},
+        {"required": ["content"]},
+    ]
+
+    # Inject computed theme enum
+    props["theme"] = {
+        "type": "string",
+        "enum": themes,
+        "description": _extract_description(props.get("theme", {})),
+    }
+
+    # Override charts → typed additionalProperties (IR has untyped dict[str, Any])
+    _chart_ref_schema = {
+        "type": "string",
+        "pattern": r"^.+\.charts\.\w+$",
+        "description": "Cross-file chart reference: '<file>.charts.<name>'.",
+    }
+    props["charts"] = {
+        "type": "object",
+        "description": _extract_description(props.get("charts", {})),
+        "additionalProperties": {
+            "oneOf": [
+                {"$ref": "#/definitions/AuthoredChart"},
+                _chart_ref_schema,
+            ]
+        },
+    }
+
+    # Override variables/queries → typed additionalProperties with cross-file ref support.
+    # IR emits only the inline model (Variable/AuthoredQuery); the ref form is a string
+    # matching '<file>.<section>.<name>' and is coerced to a typed model at parse time.
+    for key, ref_name, section_label, pattern in (
+        ("variables", "Variable", "variable", r"^.+\.variables\.\w+$"),
+        ("queries", "AuthoredQuery", "query", r"^.+\.queries\.\w+$"),
+    ):
+        if key in props:
+            string_arms: list[dict[str, object]] = [
+                {
+                    "type": "string",
+                    "pattern": pattern,
+                    "description": f"Cross-file {section_label} reference.",
+                },
+            ]
+            # queries also accept bare SQL shorthand ("SELECT …") — add an unconstrained
+            # string arm so IDE validation does not red-squiggle valid SQL strings.
+            # Runtime (Pydantic) already enforces the grammar; the schema arm is advisory only.
+            if key == "queries":
+                string_arms.append({"type": "string"})
+            props[key] = {
+                "type": "object",
+                "description": _extract_description(props[key]),
+                "additionalProperties": {
+                    "oneOf": [
+                        {"$ref": f"#/definitions/{ref_name}"},
+                        *string_arms,
+                    ]
+                },
+            }
+
+    # Override rows/cols → typed items (IR has untyped list[str | dict])
+    for key in ("rows", "cols"):
+        if key in props:
+            props[key] = {
+                "type": "array",
+                "description": _extract_description(props[key]),
+                "items": {"$ref": "#/definitions/LayoutItem"},
+            }
+
+    # Override sources → hand-assembled oneOf (IR refs SourcesSection which is too narrow)
+    props["sources"] = {
+        "description": _extract_description(props.get("sources", {})),
+        "oneOf": [
+            {
+                "type": "object",
+                "additionalProperties": {"$ref": "#/definitions/Source"},
+            },
+            {"type": "string"},
+        ],
+    }
+
+    # Add chart type aliases to AuthoredChart.type enum
+    if "AuthoredChart" in defns:
+        type_prop = defns["AuthoredChart"].get("properties", {}).get("type", {})
+        _add_aliases_to_enum(type_prop, chart_aliases)
+
+    # Source: oneOf over all concrete connector class definitions
+    defns["Source"] = {
+        "description": "Data source configuration.",
+        "oneOf": [
+            {"$ref": f"#/definitions/{name}"} for name in _SOURCE_CONNECTOR_NAMES
+        ],
+    }
+
+    defns["LayoutItem"] = _build_layout_item_def()
+
+    # Override FilterDef → authored surface schema (string | {op: var}).
+    # The IR reflects the internal model shape {op, var, template}; authors never
+    # write that. Authors write a plain variable name, a Jinja template string, or
+    # a single-key operator dict.
+    defns["FilterDef"] = {
+        "description": "Chart-level filter binding: plain variable name, Jinja template, or operator dict.",
+        "oneOf": [
+            {
+                "type": "string",
+                "description": (
+                    "Plain variable name (implicit eq) or Jinja template "
+                    "(e.g. '{{ region }}' or '{{ x if x else \"\" }}')."
+                ),
+            },
+            {
+                "type": "object",
+                "minProperties": 1,
+                "maxProperties": 1,
+                "additionalProperties": {"type": "string"},
+                "description": (
+                    "Single-key operator dict: {op: variable_name}. "
+                    "op is one of: eq, neq, gt, gte, lt, lte, like, ilike, in, not_in, between."
+                ),
+            },
+        ],
+    }
+
+    return schema
+
+
+def _add_aliases_to_enum(type_prop: dict[str, Any], aliases: dict[str, str]) -> None:
+    """Append alias keys to the enum list in a type property (in-place)."""
+    if "enum" in type_prop:
+        existing = type_prop["enum"]
+        type_prop["enum"] = existing + [k for k in aliases if k not in existing]
+    elif "anyOf" in type_prop:
+        for branch in type_prop["anyOf"]:
+            if "enum" in branch:
+                existing = branch["enum"]
+                branch["enum"] = existing + [k for k in aliases if k not in existing]
+                break
+
+
+def render_vscode_schema(
+    schema: AuthorableSchema,
+    *,
+    themes: list[str],
+    chart_aliases: dict[str, str],
+) -> dict[str, Any]:
+    """Render an AuthorableSchema as a VS Code draft-07 JSON Schema.
+
+    Calls render_json_schema for the IR-driven core and decorates with
+    IDE-specific extras (fileMatch, layout constraints, theme enum, etc.).
+    """
+    base = render_json_schema(schema)
+    return _decorate_for_vscode(base, themes=themes, chart_aliases=chart_aliases)