@qingflow-tech/qingflow-cli 1.1.43 → 1.1.44-beta.1

package/src/qingflow_mcp/builder_facade/app_form_schema.py

@@ -0,0 +1,425 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+from typing import Any, Iterable
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+
+JSONObject = dict[str, Any]
+SCHEMA_ROOT = Path(__file__).with_name("schemas") / "app_form"
+
+
+def _discriminator_score(schema: Any, instance: Any, root_schema: Any = None, seen_refs: set[str] | None = None) -> int:
+    """Score a schema branch against its input discriminator values."""
+    if not isinstance(schema, dict) or not isinstance(instance, dict):
+        return 0
+    reference = schema.get("$ref")
+    if isinstance(reference, str) and reference.startswith("#/") and isinstance(root_schema, dict):
+        seen_refs = seen_refs or set()
+        if reference in seen_refs:
+            return 0
+        target: Any = root_schema
+        for part in reference[2:].split("/"):
+            if not isinstance(target, dict):
+                return 0
+            target = target.get(part.replace("~1", "/").replace("~0", "~"))
+        return _discriminator_score(target, instance, root_schema, seen_refs | {reference})
+    score = 0
+    properties = schema.get("properties")
+    if isinstance(properties, dict):
+        for key, constraint in properties.items():
+            if not isinstance(constraint, dict) or key not in instance:
+                continue
+            value = instance.get(key)
+            if "const" in constraint:
+                score += 3 if value == constraint["const"] else -3
+            elif isinstance(constraint.get("enum"), list):
+                score += 3 if value in constraint["enum"] else -3
+    for combinator in ("allOf", "anyOf", "oneOf"):
+        children = schema.get(combinator)
+        if not isinstance(children, list):
+            continue
+        child_scores = [_discriminator_score(child, instance, root_schema, seen_refs) for child in children]
+        if combinator == "allOf":
+            score += sum(child_score for child_score in child_scores if child_score > 0)
+        elif child_scores:
+            score += max(child_scores)
+    return score
+
+
+def _selected_combinator_children(error: Any, root_schema: Any = None) -> list[Any] | None:
+    """Return errors from the branch matching a known discriminator.
+
+    jsonschema flattens errors from nested ``allOf`` branches into the parent
+    combinator context, so branch identity is recovered from the schema path.
+    """
+    if not isinstance(error.schema, dict):
+        return None
+    branches = error.schema.get(error.validator)
+    if not isinstance(branches, list) or not branches:
+        return None
+    scores = [_discriminator_score(branch, error.instance, root_schema) for branch in branches]
+    best = max(scores)
+    if best <= 0:
+        return None
+    selected = {index for index, score in enumerate(scores) if score == best}
+    prefix = tuple(error.absolute_schema_path)
+    children = [
+        child
+        for child in error.context
+        if len(tuple(child.absolute_schema_path)) > len(prefix)
+        and tuple(child.absolute_schema_path)[: len(prefix)] == prefix
+        and tuple(child.absolute_schema_path)[len(prefix)] in selected
+    ]
+    return children or None
+
+
+def _iter_compact_schema_errors(error: Any, root_schema: Any = None) -> Iterable[Any]:
+    if error.validator in {"oneOf", "anyOf"}:
+        selected = _selected_combinator_children(error, root_schema)
+        if selected:
+            for child in selected:
+                yield from _iter_compact_schema_errors(child, root_schema)
+            return
+        yield error
+        return
+    if error.context:
+        for child in error.context:
+            yield from _iter_compact_schema_errors(child, root_schema)
+        return
+    yield error
+
+
+def compact_schema_errors(errors: Iterable[Any], root_schema: Any = None) -> list[Any]:
+    """Collapse polymorphic-schema noise while retaining actionable errors."""
+    flattened = [leaf for error in errors for leaf in _iter_compact_schema_errors(error, root_schema)]
+    descendant_paths = [tuple(error.absolute_path) for error in flattened]
+    result: list[Any] = []
+    seen: set[tuple[tuple[Any, ...], str, str]] = set()
+    for error in flattened:
+        path = tuple(error.absolute_path)
+        if error.validator == "unevaluatedProperties" and any(
+            len(other) > len(path) and other[: len(path)] == path for other in descendant_paths
+        ):
+            continue
+        key = (path, str(error.validator), schema_error_message(error))
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(error)
+    return result
+
+
+def schema_error_message(error: Any) -> str:
+    """Render a bounded, user-facing message for a JSON Schema error."""
+    if error.validator == "oneOf":
+        return "value is not valid under any of the given schemas"
+    if error.validator == "anyOf":
+        return "value is not valid under any of the given schemas"
+    return str(error.message)
+
+
+class AppFormContractError(ValueError):
+    def __init__(self, error_code: str, message: str, *, path: str | None = None, details: JSONObject | None = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+        self.path = path
+        self.details = details or {}
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormSchemaContext:
+    schema_version: str
+    api_version: str
+    complete_schema: JSONObject
+    supported_types: tuple[str, ...]
+    supported_schema_kinds: tuple[str, ...]
+    contract_source: str
+    contract_version: str
+    normalizer_version: str
+    apply_dto: type[AppFormApplyDTO]
+
+    def validate(self, payload: JSONObject) -> None:
+        validator = Draft202012Validator(self.complete_schema, format_checker=FormatChecker())
+        errors = sorted(validator.iter_errors(payload), key=lambda item: (list(item.absolute_path), item.message))
+        if not errors:
+            return
+        compact_errors = compact_schema_errors(errors, self.complete_schema)
+        error = compact_errors[0] if compact_errors else errors[0]
+        pointer = "".join(f"/{str(part).replace('~', '~0').replace('/', '~1')}" for part in error.absolute_path) or "/"
+        raise AppFormContractError(
+            "INVALID_SPEC",
+            schema_error_message(error),
+            path=pointer,
+            details={"validator": error.validator, "schemaPath": "/".join(str(part) for part in error.absolute_schema_path)},
+        )
+
+    def parse_apply(self, payload: JSONObject) -> AppFormApplyDTO:
+        self.validate(payload)
+        return self.apply_dto(
+            contract_source=self.contract_source,
+            contract_version=self.contract_version,
+            normalizer_version=self.normalizer_version,
+            resource=deepcopy(payload),
+        )
+
+    def assert_apply_dto(self, value: AppFormApplyDTO) -> None:
+        if not isinstance(value, self.apply_dto):
+            raise AppFormContractError(
+                "SCHEMA_VERSION_MISMATCH",
+                "AppForm declaration was parsed by a different DTO type",
+                details={"expected": self.apply_dto.__name__, "actual": type(value).__name__},
+            )
+        actual = (value.contract_source, value.contract_version, value.normalizer_version)
+        expected = (self.contract_source, self.contract_version, self.normalizer_version)
+        if actual != expected:
+            raise AppFormContractError(
+                "SCHEMA_VERSION_MISMATCH",
+                "AppForm declaration was parsed by a different contract version",
+                details={"expected": expected, "actual": actual},
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormApplyDTO:
+    contract_source: str
+    contract_version: str
+    normalizer_version: str
+    resource: JSONObject
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormV1Alpha1ApplyDTO(AppFormApplyDTO):
+    pass
+
+
+APPLY_DTO_TYPES: dict[str, type[AppFormApplyDTO]] = {
+    "v1alpha1": AppFormV1Alpha1ApplyDTO,
+}
+
+
+class AppFormSchemaRegistry:
+    def __init__(self, root: Path = SCHEMA_ROOT, *, enabled_versions: tuple[str, ...] | None = None) -> None:
+        self.root = root
+        self.manifest = self._read_json(root / "manifest.json")
+        versions = self.manifest.get("versions")
+        if not isinstance(versions, dict) or not versions:
+            raise RuntimeError("AppForm schema manifest must define versions")
+        configured = enabled_versions or self._configured_versions()
+        self.stored_versions = tuple(str(version) for version in versions)
+        self.latest_version = str(self.manifest.get("latestVersion") or "")
+        self._stored_api_to_version: dict[str, str] = {}
+        for version, metadata in versions.items():
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"AppForm schema metadata must be an object: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            if not api_version:
+                raise RuntimeError(f"AppForm schema version has no apiVersion: {version}")
+            if api_version in self._stored_api_to_version:
+                raise RuntimeError(f"duplicate AppForm apiVersion: {api_version}")
+            self._stored_api_to_version[api_version] = str(version)
+        defaults = tuple(
+            str(version)
+            for version, metadata in versions.items()
+            if isinstance(metadata, dict) and bool(metadata.get("enabledByDefault"))
+        )
+        self.enabled_versions = configured or defaults
+        if self.latest_version not in versions:
+            raise RuntimeError("AppForm latestVersion is not stored")
+        if self.latest_version not in self.enabled_versions:
+            raise RuntimeError("AppForm latestVersion must remain enabled")
+        self._contexts: dict[str, AppFormSchemaContext] = {}
+        self._api_to_version: dict[str, str] = {}
+        for version in self.enabled_versions:
+            metadata = versions.get(version)
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"enabled AppForm schema version is not stored: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            complete = self._read_json(root / version / "complete.json")
+            supported = tuple(str(item) for item in metadata.get("fieldTypes") or ())
+            supported_schema_kinds = tuple(str(item) for item in metadata.get("schemaKinds") or ("summary", "field"))
+            if not {"summary", "field"}.issubset(supported_schema_kinds):
+                raise RuntimeError(f"AppForm schema version must support summary and field Schemas: {version}")
+            if complete.get("properties", {}).get("apiVersion", {}).get("const") != api_version:
+                raise RuntimeError(f"AppForm schema apiVersion mismatch for {version}")
+            schema_id = str(complete.get("$id") or "")
+            if version not in schema_id:
+                raise RuntimeError(f"AppForm schema $id mismatch for {version}")
+            Draft202012Validator.check_schema(complete)
+            self._validate_local_refs(complete, root / version / "complete.json")
+            summary = self._read_json(root / version / "summary.json")
+            if summary.get("properties", {}).get("apiVersion", {}).get("const") != api_version:
+                raise RuntimeError(f"AppForm summary apiVersion mismatch for {version}")
+            Draft202012Validator.check_schema(summary)
+            self._validate_local_refs(summary, root / version / "summary.json")
+            if "formula" in supported_schema_kinds:
+                formula_path = root / version / "formula.json"
+                formula = self._read_json(formula_path)
+                Draft202012Validator.check_schema(formula)
+                self._validate_local_refs(formula, formula_path)
+            for field_type in supported:
+                field_path = root / version / "fields" / f"{field_type}.json"
+                field_schema = self._read_json(field_path)
+                Draft202012Validator.check_schema(field_schema)
+                self._validate_local_refs(field_schema, field_path)
+            context = AppFormSchemaContext(
+                version,
+                api_version,
+                complete,
+                supported,
+                supported_schema_kinds,
+                str(metadata.get("contractSource") or "app_form"),
+                str(metadata.get("contractVersion") or version),
+                str(metadata.get("normalizerVersion") or version),
+                self._apply_dto_type(version, metadata),
+            )
+            self._contexts[version] = context
+            self._api_to_version[api_version] = version
+
+    def schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        field_type: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        context = self.resolve_schema_version(schema_version)
+        requested_kind = str(schema_kind or ("field" if field_type is not None else "summary")).strip()
+        if requested_kind not in context.supported_schema_kinds:
+            raise AppFormContractError(
+                "UNSUPPORTED_SCHEMA_KIND",
+                f"unsupported AppForm schema kind: {requested_kind}",
+                details={"supportedKinds": list(context.supported_schema_kinds)},
+            )
+        if requested_kind == "formula":
+            if field_type is not None:
+                raise AppFormContractError(
+                    "INVALID_SCHEMA_SELECTION",
+                    "field_type cannot be combined with schema_kind=formula",
+                    details={"schemaKind": requested_kind, "fieldType": field_type},
+                )
+            schema = self._read_json(self.root / context.schema_version / "formula.json")
+            resolved_kind = "formula"
+        elif requested_kind == "summary":
+            if field_type is not None:
+                raise AppFormContractError(
+                    "INVALID_SCHEMA_SELECTION",
+                    "field_type requires schema_kind=field or an omitted schema_kind",
+                    details={"schemaKind": requested_kind, "fieldType": field_type},
+                )
+            schema = self._read_json(self.root / context.schema_version / "summary.json")
+            resolved_kind = "summary"
+        else:
+            if field_type is None:
+                raise AppFormContractError(
+                    "INVALID_SCHEMA_SELECTION",
+                    "schema_kind=field requires field_type",
+                    details={"schemaKind": requested_kind, "supportedTypes": list(context.supported_types)},
+                )
+            if field_type not in context.supported_types:
+                raise AppFormContractError(
+                    "UNSUPPORTED_SCHEMA_FIELD_TYPE",
+                    f"unsupported AppForm field type: {field_type}",
+                    details={"supportedTypes": list(context.supported_types)},
+                )
+            schema = self._read_json(self.root / context.schema_version / "fields" / f"{field_type}.json")
+            resolved_kind = "field"
+        return {
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "latestVersion": self.latest_version,
+            "storedVersions": list(self.stored_versions),
+            "enabledVersions": list(self.enabled_versions),
+            "supportedSchemaKinds": list(context.supported_schema_kinds),
+            "schemaKind": resolved_kind,
+            "fieldType": field_type,
+            "schema": schema,
+        }
+
+    def resolve_schema_version(self, schema_version: str | None) -> AppFormSchemaContext:
+        version = str(schema_version or self.latest_version).strip()
+        if version not in self.stored_versions:
+            raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", version)
+        if version not in self.enabled_versions:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", version)
+        return self._resolved_context(version)
+
+    def resolve_api_version(self, api_version: str) -> AppFormSchemaContext:
+        version = self._api_to_version.get(api_version)
+        if version is not None:
+            return self._resolved_context(version)
+        stored = self._stored_api_to_version.get(api_version)
+        if stored is not None:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", stored)
+        raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", api_version)
+
+    def _resolved_context(self, version: str) -> AppFormSchemaContext:
+        return self._contexts[version]
+
+    @staticmethod
+    def _apply_dto_type(version: str, metadata: JSONObject) -> type[AppFormApplyDTO]:
+        dto_name = str(metadata.get("applyDto") or version)
+        dto_type = APPLY_DTO_TYPES.get(dto_name)
+        if dto_type is None:
+            raise RuntimeError(f"AppForm schema version {version} references unknown apply DTO: {dto_name}")
+        return dto_type
+
+    def _version_error(self, error_code: str, requested: str) -> AppFormContractError:
+        return AppFormContractError(
+            error_code,
+            f"unsupported AppForm schema selection: {requested}",
+            details={
+                "requestedVersion": requested,
+                "latestVersion": self.latest_version,
+                "storedVersions": list(self.stored_versions),
+                "enabledVersions": list(self.enabled_versions),
+            },
+        )
+
+    @staticmethod
+    def _read_json(path: Path) -> JSONObject:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise RuntimeError(f"AppForm schema artifact must be an object: {path}")
+        return value
+
+    @staticmethod
+    def _validate_local_refs(document: JSONObject, path: Path) -> None:
+        stack: list[Any] = [document]
+        while stack:
+            value = stack.pop()
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if ref is not None:
+                    if not isinstance(ref, str) or (ref != "#" and not ref.startswith("#/")):
+                        raise RuntimeError(f"AppForm schema contains an external or invalid $ref in {path}: {ref}")
+                    target: Any = document
+                    for raw_part in ref[2:].split("/") if ref.startswith("#/") else ():
+                        part = raw_part.replace("~1", "/").replace("~0", "~")
+                        if not isinstance(target, dict) or part not in target:
+                            raise RuntimeError(f"AppForm schema contains a dangling $ref in {path}: {ref}")
+                        target = target[part]
+                stack.extend(value.values())
+            elif isinstance(value, list):
+                stack.extend(value)
+
+    @staticmethod
+    def _configured_versions() -> tuple[str, ...]:
+        raw = os.environ.get("QINGFLOW_APP_FORM_SCHEMA_VERSIONS", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+_REGISTRY: AppFormSchemaRegistry | None = None
+
+
+def app_form_schema_registry() -> AppFormSchemaRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = AppFormSchemaRegistry()
+    return _REGISTRY

package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json

@@ -0,0 +1,42 @@
+{
+  "latestVersion": "v1alpha1",
+  "versions": {
+    "v1alpha1": {
+      "apiVersion": "builder.qingflow.com/v1alpha1",
+      "applyDto": "v1alpha1",
+      "contractSource": "app_form",
+      "contractVersion": "v1alpha1",
+      "enabledByDefault": true,
+      "fieldTypes": [
+        "text",
+        "long_text",
+        "number",
+        "amount",
+        "link",
+        "date",
+        "datetime",
+        "member",
+        "department",
+        "single_choice",
+        "single_select",
+        "multi_select",
+        "phone",
+        "email",
+        "address",
+        "attachment",
+        "q_linker",
+        "code_block",
+        "data_relation",
+        "relation",
+        "subtable"
+      ],
+      "normalizerVersion": "v1alpha1",
+      "schemaKinds": [
+        "summary",
+        "field",
+        "formula"
+      ],
+      "status": "active"
+    }
+  }
+}