@qingflow-tech/qingflow-cli 1.1.43 → 1.1.44

package/src/qingflow_mcp/app_form_validator.py

@@ -0,0 +1,462 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+import re
+from typing import Any, Iterable
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+from .app_form_compat import normalize_app_form_declaration
+from .builder_facade.app_form_schema import AppFormContractError, compact_schema_errors, schema_error_message
+
+
+_INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
+    "text",
+    "long_text",
+    "number",
+    "amount",
+    "date",
+    "datetime",
+    "single_choice",
+    "single_select",
+    "multi_select",
+}
+_Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
+_FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+class AppFormValidationError(ValueError):
+    """Raised when a declaration fails local AppForm validation."""
+
+    def __init__(self, issues: list[dict[str, str]], *, schema_version: str, api_version: str) -> None:
+        super().__init__("AppForm declaration is invalid")
+        self.issues = issues
+        self.schema_version = schema_version
+        self.api_version = api_version
+
+
+def _field_type(field: dict[str, Any]) -> str:
+    return str(field.get("questionType") or field.get("type") or "").strip()
+
+
+def _field_types(payload: dict[str, Any]) -> tuple[str, ...]:
+    found: set[str] = set()
+
+    def visit(field: Any) -> None:
+        if not isinstance(field, dict):
+            return
+        field_type = _field_type(field)
+        if field_type:
+            found.add(field_type)
+        for child in field.get("subfields") or []:
+            visit(child)
+
+    spec = payload.get("spec")
+    for block in spec.get("body") or [] if isinstance(spec, dict) else []:
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row in rows:
+            for field in row.get("fields") or [] if isinstance(row, dict) else []:
+                visit(field)
+    return tuple(sorted(found))
+
+
+def _local_schema_call(schema_version: str | None, field_type: str | None) -> dict[str, Any]:
+    from .builder_facade.app_form_schema import app_form_schema_registry
+
+    return {"status": "success", **app_form_schema_registry().schema(schema_version=schema_version, field_type=field_type)}
+
+
+def _supported_formula_functions(schema_version: str) -> frozenset[str]:
+    """Load the version-pinned formula function catalogue used by local validation."""
+    from .builder_facade.app_form_schema import app_form_schema_registry
+
+    response = app_form_schema_registry().schema(schema_version=schema_version, schema_kind="formula")
+    schema = response.get("schema") if isinstance(response, dict) else None
+    functions = schema.get("x-qingflow-functions") if isinstance(schema, dict) else None
+    if not isinstance(functions, dict) or not functions:
+        raise RuntimeError(f"/: AppForm formula Schema has no function catalogue for {schema_version}")
+    return frozenset(str(name).upper() for name in functions if isinstance(name, str) and name)
+
+
+def _compose(summary: dict[str, Any], details: list[dict[str, Any]]) -> dict[str, Any]:
+    if not details:
+        raise RuntimeError("at least one field Schema is required to compose AppForm validation")
+    schema = deepcopy(summary["schema"])
+    shared_defs = deepcopy(schema.get("$defs") or {})
+    field_branches = []
+    for detail in details:
+        detail_schema = detail["schema"]
+        for name, definition in (detail_schema.get("$defs") or {}).items():
+            existing = shared_defs.get(name)
+            if existing is not None and existing != definition:
+                raise RuntimeError(f"field Schema definition conflict: {name}")
+            shared_defs[name] = deepcopy(definition)
+        branch = {
+            key: deepcopy(value)
+            for key, value in detail_schema.items()
+            if key not in {"$schema", "$id", "$defs", "title"}
+        }
+        field_branches.append(branch)
+    shared_defs["TopField"] = {"oneOf": field_branches}
+    schema["$defs"] = shared_defs
+    schema["properties"]["spec"] = {
+        "$ref": "#/$defs/AppFormSpec",
+        "description": "Application form target state.",
+    }
+    return schema
+
+
+def _pointer(parts: Iterable[Any]) -> str:
+    encoded = [str(item).replace("~", "~0").replace("/", "~1") for item in parts]
+    return "/" + "/".join(encoded) if encoded else "/"
+
+
+def _formula_function_calls(expression: str) -> set[str]:
+    """Extract calls outside quoted string literals without parsing the full formula grammar."""
+    calls: set[str] = set()
+    index = 0
+    while index < len(expression):
+        character = expression[index]
+        if character in {"'", '"'}:
+            quote = character
+            index += 1
+            while index < len(expression):
+                if expression[index] == "\\":
+                    index += 2
+                    continue
+                if expression[index] == quote:
+                    index += 1
+                    break
+                index += 1
+            continue
+        match = _FORMULA_IDENTIFIER_RE.match(expression, index)
+        if match is None:
+            index += 1
+            continue
+        name = match.group(0)
+        cursor = match.end()
+        while cursor < len(expression) and expression[cursor].isspace():
+            cursor += 1
+        if cursor < len(expression) and expression[cursor] in {"(", "（"}:
+            calls.add(name)
+        index = match.end()
+    return calls
+
+
+def _iter_formula_expressions(payload: dict[str, Any]) -> Iterable[tuple[str, str]]:
+    spec = payload.get("spec")
+    body = spec.get("body") if isinstance(spec, dict) else None
+    if not isinstance(body, list):
+        return
+
+    def visit(field: Any, path: str) -> Iterable[tuple[str, str]]:
+        if not isinstance(field, dict):
+            return
+        if field.get("defaultType") == 3 and isinstance(field.get("defaultValue"), str):
+            yield f"{path}/defaultValue", field["defaultValue"]
+        config = field.get("config") if isinstance(field.get("config"), dict) else {}
+        default_value_formula = config.get("defaultValueFormula")
+        if isinstance(default_value_formula, str):
+            yield f"{path}/config/defaultValueFormula", default_value_formula
+        filters = config.get("filters") if isinstance(config.get("filters"), dict) else {}
+        if filters.get("mode") == "advanced" and isinstance(filters.get("formula"), str):
+            yield f"{path}/config/filters/formula", filters["formula"]
+        for child_index, child in enumerate(field.get("subfields") or []):
+            yield from visit(child, f"{path}/subfields/{child_index}")
+
+    for block_index, block in enumerate(body):
+        if not isinstance(block, dict):
+            continue
+        rows = [(block, f"/spec/body/{block_index}")] if block.get("kind") == "row" else [
+            (row, f"/spec/body/{block_index}/rows/{row_index}")
+            for row_index, row in enumerate(block.get("rows") or [])
+        ]
+        for row, row_path in rows:
+            if not isinstance(row, dict):
+                continue
+            for field_index, field in enumerate(row.get("fields") or []):
+                yield from visit(field, f"{row_path}/fields/{field_index}")
+
+
+def _formula_errors(payload: dict[str, Any], supported_functions: frozenset[str]) -> list[tuple[str, str]]:
+    errors: list[tuple[str, str]] = []
+    for pointer, expression in _iter_formula_expressions(payload):
+        unknown = sorted(name for name in _formula_function_calls(expression) if name.upper() not in supported_functions)
+        for name in unknown:
+            errors.append(
+                (
+                    pointer,
+                    f"unsupported formula function '{name}'; use a function declared by builder app-form schema --schema-kind formula",
+                )
+            )
+    return errors
+
+
+def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
+    errors: list[tuple[str, str]] = []
+    spec = payload.get("spec")
+    body = spec.get("body") if isinstance(spec, dict) else None
+    if not isinstance(body, list):
+        return errors
+    top_fields: list[tuple[str, dict[str, Any]]] = []
+    for block_index, block in enumerate(body):
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row_index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                continue
+            fields = row.get("fields")
+            if not isinstance(fields, list):
+                continue
+            row_path = f"/spec/body/{block_index}/" + ("fields" if block.get("kind") == "row" else f"rows/{row_index}/fields")
+            widths = ["width" in field for field in fields if isinstance(field, dict)]
+            if widths and any(widths) and not all(widths):
+                errors.append((row_path, "width must be present on every field in the row or omitted from all"))
+            if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
+                errors.append((row_path, "field widths must total 100"))
+            for field_index, field in enumerate(fields):
+                if isinstance(field, dict):
+                    top_fields.append((f"{row_path}/{field_index}", field))
+    def resolve_local_selector(selector: Any) -> tuple[str, tuple[str, dict[str, Any]] | None]:
+        """Resolve against the declared body, preserving backend-dependent ID-only cases."""
+        if not isinstance(selector, dict):
+            return "schema", None
+        raw_que_id = selector.get("queId")
+        que_id = raw_que_id if isinstance(raw_que_id, int) and not isinstance(raw_que_id, bool) else None
+        raw_name = selector.get("name")
+        name = raw_name if isinstance(raw_name, str) and raw_name else ""
+        if raw_que_id is not None and que_id is None:
+            return "schema", None
+        if raw_name is not None and not name:
+            return "schema", None
+        if que_id is not None:
+            matches = [(path, field) for path, field in top_fields if field.get("queId") == que_id]
+            if len(matches) != 1:
+                return "invalid", None
+            declared_name = str(matches[0][1].get("name") or "")
+            if name and declared_name and name != declared_name:
+                return "invalid", None
+            return "resolved", matches[0]
+        if name:
+            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "") == name]
+            if len(matches) == 1:
+                return "resolved", matches[0]
+            if len(matches) > 1:
+                return "invalid", None
+            if any(not str(field.get("name") or "") for _, field in top_fields):
+                return "unknown", None
+            return "invalid", None
+        return "schema", None
+
+    title_selector = spec.get("dataTitleField")
+    if top_fields:
+        if "dataTitleField" not in spec and "appKey" in payload:
+            pass
+        elif title_selector is None or resolve_local_selector(title_selector)[0] == "invalid":
+            errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
+    elif title_selector is not None:
+        errors.append(("/spec/dataTitleField", "dataTitleField must be null when body is empty"))
+
+    cover_selector = spec.get("dataCoverField")
+    if cover_selector is not None:
+        cover_resolution, cover = resolve_local_selector(cover_selector)
+        if cover_resolution == "invalid":
+            errors.append(("/spec/dataCoverField", "dataCoverField must resolve to exactly one top-level field"))
+        elif cover_resolution == "resolved" and cover is not None and _field_type(cover[1]) != "attachment":
+            errors.append(("/spec/dataCoverField", "dataCoverField must select a top-level attachment field"))
+    names: dict[str, str] = {}
+    fields_by_id = {
+        field.get("queId"): field
+        for _, field in top_fields
+        if isinstance(field.get("queId"), int) and not isinstance(field.get("queId"), bool)
+    }
+    output_targets: dict[str, tuple[str, str]] = {}
+    for path, field in top_fields:
+        name = str(field.get("name") or "")
+        if name:
+            if name in names:
+                errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
+            else:
+                names[name] = f"{path}/name"
+        field_type = _field_type(field)
+        if field_type == "data_relation":
+            config = field.get("config") if isinstance(field.get("config"), dict) else {}
+            filters = config.get("filters") if isinstance(config.get("filters"), dict) else {}
+            if filters.get("mode") == "simple":
+                for group_index, group in enumerate(filters.get("groups") or []):
+                    for condition_index, condition in enumerate(group if isinstance(group, list) else []):
+                        if not isinstance(condition, dict):
+                            continue
+                        operator = condition.get("operator")
+                        operand = condition.get("operand") if isinstance(condition.get("operand"), dict) else {}
+                        values = operand.get("values") if isinstance(operand.get("values"), list) else None
+                        operand_path = (
+                            f"{path}/config/filters/groups/{group_index}/{condition_index}/operand"
+                        )
+                        if operator in {"is_empty", "is_not_empty"}:
+                            if operand.get("kind") != "literal" or values != []:
+                                errors.append(
+                                    (
+                                        operand_path,
+                                        "is_empty and is_not_empty require a literal operand with values: []",
+                                    )
+                                )
+                        elif operand.get("kind") == "literal" and not values:
+                            errors.append(
+                                (
+                                    f"{operand_path}/values",
+                                    "literal operands for non-empty operators must contain at least one value",
+                                )
+                            )
+        if field_type == "q_linker":
+            binding_name = "qLinkerBinding"
+        elif field_type == "code_block":
+            binding_name = "codeBlockBinding"
+        else:
+            continue
+        binding = (field.get("config") or {}).get(binding_name) if isinstance(field.get("config"), dict) else None
+        if not isinstance(binding, dict):
+            continue
+        for index, item in enumerate(binding.get("inputs") or []):
+            if not isinstance(item, dict):
+                continue
+            selector = item.get("field") if isinstance(item.get("field"), dict) else {}
+            input_path = f"{path}/config/{binding_name}/inputs/{index}"
+            resolution, selected = resolve_local_selector(selector)
+            if resolution == "invalid":
+                errors.append((f"{input_path}/field", "input field must resolve to exactly one top-level field"))
+                continue
+            if field_type != "q_linker" or item.get("source") != "json_path":
+                continue
+            selected_name = selected[1].get("name") if selected is not None else selector.get("name")
+            if not selected_name and selector.get("queId") in fields_by_id:
+                selected_name = fields_by_id[selector["queId"]].get("name")
+            if selected_name and item.get("key") != selected_name:
+                errors.append((f"{input_path}/key", "json_path key must equal the selected field name"))
+
+        if field_type == "q_linker":
+            request = binding.get("request") if isinstance(binding.get("request"), dict) else {}
+            template_paths: dict[str, list[str]] = {}
+            for property_name in ("url", "jsonValue", "xmlValue"):
+                raw_template = request.get(property_name)
+                if not isinstance(raw_template, str):
+                    continue
+                for match in _Q_LINKER_TEMPLATE_RE.finditer(raw_template):
+                    template_paths.setdefault(match.group("key"), []).append(
+                        f"{path}/config/{binding_name}/request/{property_name}"
+                    )
+            input_items = [item for item in binding.get("inputs") or [] if isinstance(item, dict)]
+            json_path_inputs: dict[str, list[int]] = {}
+            for index, item in enumerate(input_items):
+                key = str(item.get("key") or "")
+                if key and item.get("source") == "json_path":
+                    json_path_inputs.setdefault(key, []).append(index)
+            for key, request_paths in template_paths.items():
+                providers = json_path_inputs.get(key) or []
+                if len(providers) == 1:
+                    continue
+                if not providers:
+                    message = (
+                        f"placeholder '{{{{{key}}}}}' requires an input with source 'json_path' and the same key; "
+                        "query_param, header, and url_encoded inputs do not replace request templates"
+                    )
+                else:
+                    message = f"placeholder '{{{{{key}}}}}' must have exactly one json_path input"
+                errors.append((request_paths[0], message))
+            for key, indexes in json_path_inputs.items():
+                if key in template_paths:
+                    continue
+                for index in indexes:
+                    errors.append(
+                        (
+                            f"{path}/config/{binding_name}/inputs/{index}/source",
+                            f"json_path input key '{key}' must appear as '{{{{{key}}}}}' in request.url, request.jsonValue, or request.xmlValue",
+                        )
+                    )
+
+        producer = name or str(field.get("queId") or field_type)
+        for index, item in enumerate(binding.get("outputs") or []):
+            if not isinstance(item, dict):
+                continue
+            selector = item.get("targetField")
+            target_path = f"{path}/config/{binding_name}/outputs/{index}/targetField"
+            resolution, selected = resolve_local_selector(selector)
+            if resolution == "invalid":
+                errors.append((target_path, "targetField must resolve to exactly one top-level field"))
+                continue
+            if resolution != "resolved" or selected is None:
+                continue
+            selected_path, target_field = selected
+            target_name = str(target_field.get("name") or target_field.get("queId") or "")
+            target_type = _field_type(target_field)
+            if target_type and target_type not in _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES:
+                allowed = ", ".join(sorted(_INTEGRATION_OUTPUT_TARGET_FIELD_TYPES))
+                errors.append(
+                    (
+                        target_path,
+                        f"output target field '{target_name}' uses unsupported questionType '{target_type}'; allowed types: {allowed}",
+                    )
+                )
+            previous = output_targets.get(selected_path)
+            if previous is None:
+                output_targets[selected_path] = (producer, target_path)
+                continue
+            previous_producer, previous_path = previous
+            errors.append(
+                (
+                    target_path,
+                    f"field '{target_name}' is already targeted by output from '{previous_producer}' at {previous_path}; "
+                    "each field can receive output from only one Q-Linker or code block relation",
+                )
+            )
+    return errors
+
+
+def validate_declaration(
+    payload: dict[str, Any],
+    *,
+    schema_version: str | None = None,
+    schema_call: Any = _local_schema_call,
+) -> dict[str, Any]:
+    """Validate a complete AppForm declaration without network or write calls."""
+    summary = schema_call(schema_version, None)
+    if not isinstance(summary, dict) or summary.get("status") != "success" or not isinstance(summary.get("schema"), dict):
+        raise RuntimeError(f"AppForm Schema query failed: {json.dumps(summary, ensure_ascii=False)}")
+    pinned = str(summary.get("schemaVersion") or "")
+    api_version = str(summary.get("apiVersion") or "")
+    if schema_version and pinned != schema_version:
+        raise ValueError(f"/: requested schemaVersion {schema_version!r} resolved to {pinned!r}")
+    try:
+        declaration, _warnings = normalize_app_form_declaration(payload)
+    except AppFormContractError as error:
+        raise AppFormValidationError(
+            [{"pointer": error.path or "/", "message": error.message}],
+            schema_version=pinned,
+            api_version=api_version,
+        ) from error
+    if declaration.get("apiVersion") != api_version:
+        raise ValueError(f"/apiVersion: expected {api_version!r} for schemaVersion {pinned!r}")
+    supported_formula_functions = _supported_formula_functions(pinned)
+    types = _field_types(declaration)
+    details = [schema_call(pinned, field_type) for field_type in (types or ("text",))]
+    for detail in details:
+        if not isinstance(detail, dict) or detail.get("status") != "success" or detail.get("schemaVersion") != pinned or detail.get("apiVersion") != api_version:
+            raise RuntimeError("/: AppForm Schema responses mixed versions")
+    schema = _compose(summary, details)
+    Draft202012Validator.check_schema(schema)
+    validator = Draft202012Validator(schema, format_checker=FormatChecker())
+    found: dict[tuple[str, str], None] = {}
+    for error in compact_schema_errors(validator.iter_errors(declaration), schema):
+        found[(_pointer(error.absolute_path), f"{error.validator}: {schema_error_message(error)}")] = None
+    for pointer, message in _static_errors(declaration):
+        found[(pointer, message)] = None
+    for pointer, message in _formula_errors(declaration, supported_formula_functions):
+        found[(pointer, message)] = None
+    if found:
+        issues = [{"pointer": pointer, "message": message} for pointer, message in sorted(found)]
+        raise AppFormValidationError(issues, schema_version=pinned, api_version=api_version)
+    return {"valid": True, "schemaVersion": pinned, "apiVersion": api_version, "fieldTypes": list(types)}