precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/actions/action_validator.py

@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 动作预验证器模块
+
+功能概述:
+- 在 AI 生成的动作执行前进行业务逻辑验证
+- 提前发现表/字段不存在、约束类型不支持、参数缺失等问题
+- 避免执行时失败，提升用户体验
+- 支持错误分级：errors（阻止执行）和 warnings（提醒但不阻止）
+
+架构设计:
+- 与项目结构联动：加载 schemas 目录下的 YAML 文件构建表/字段索引
+- 约束类型白名单：VALID_CONSTRAINT_TYPES 定义支持的约束类型
+- 参数完整性检查：CONSTRAINT_REQUIRED_PARAMS 定义各类型必填参数
+- 返回结构化结果：ValidationResult 包含 errors、warnings、valid_actions
+
+输入示例:
+    actions = [
+        {
+            "action": "create_constraint",
+            "tableName": "users",
+            "constraintType": "Unique",
+            "columnNames": ["email"]
+        }
+    ]
+    validator = ActionValidator("/path/to/project")
+    result = validator.validate(actions)
+
+输出示例:
+    ValidationResult(
+        errors=[ValidationError(action_index=0, action_type="create_constraint",
+                                error_type="column_not_found", message="字段 email 不存在")],
+        warnings=[],
+        valid_actions=[],
+        invalid_action_indices={0}
+    )
+
+实现说明:
+- 数据类 (ValidationError/ValidationResult) 与格式化函数已提取到 validation_types.py
+- 各动作类型验证逻辑已拆分到 _constraint_validator / _schema_validator /
+  _regex_validator / _transform_validator / _settings_validator
+- 本模块保留 ActionValidator 主类，作为门面委托给上述子模块
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from app.shared.services.llm.actions._canvas_validator import validate_canvas_action
+from app.shared.services.llm.actions._constraint_validator import (
+    validate_constraint_action,
+    validate_foreign_key_reference,
+    validate_type_compatibility,
+    validate_validate_action,
+)
+from app.shared.services.llm.actions._regex_validator import validate_regex_action
+from app.shared.services.llm.actions._schema_validator import validate_schema_action
+from app.shared.services.llm.actions._settings_validator import validate_settings_action
+from app.shared.services.llm.actions._transform_validator import validate_transform_action
+from app.shared.services.llm.actions.registry import (
+    ALL_CONSTRAINT_TYPES,
+    REGEX_ACTION_TYPES,
+    SCHEMA_ACTION_TYPES,
+    SETTINGS_CATEGORIES,
+    TRANSFORM_ACTION_TYPES,
+)
+from app.shared.services.llm.actions.registry import CONSTRAINT_REQUIRED_PARAMS as CONSTRAINT_REQUIRED_PARAMS_REGISTRY
+from app.shared.services.llm.actions.specs import SpecParseError, parse_action_spec
+from app.shared.services.llm.actions.validation_types import (
+    ValidationError,
+    ValidationResult,
+    format_validation_result,
+)
+
+# 重新导出以保持向后兼容
+__all__ = [
+    "ActionValidator",
+    "ValidationError",
+    "ValidationResult",
+    "format_validation_result",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class ActionValidator:
+    """
+    @classdesc 动作预验证器
+
+    验证 AI 生成的动作在执行前的业务逻辑可行性。
+    加载项目 schema，检查表/字段存在性、约束类型有效性、参数完整性等。
+
+    Attributes:
+        project_path: 项目路径
+        _project_schema: 缓存的项目结构信息
+    """
+
+    # 以下白名单均从动作注册表（单一事实源）派生，禁止本地硬编码。
+    # 保留类属性形式以兼容现有引用（如 _constraint_validator 经回调注入使用）。
+    VALID_CONSTRAINT_TYPES = set(ALL_CONSTRAINT_TYPES)
+    VALID_SCHEMA_TYPES = set(SCHEMA_ACTION_TYPES)
+    VALID_REGEX_TYPES = set(REGEX_ACTION_TYPES)
+    VALID_TRANSFORM_TYPES = set(TRANSFORM_ACTION_TYPES)
+    VALID_SETTINGS_CATEGORIES = set(SETTINGS_CATEGORIES)
+
+    # 需要特定参数的约束类型（从注册表派生）
+    CONSTRAINT_REQUIRED_PARAMS = dict(CONSTRAINT_REQUIRED_PARAMS_REGISTRY)
+
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path)
+        self._project_schema: dict[str, Any] | None = None
+
+    def _load_project_schema(self) -> dict[str, Any]:
+        """加载项目结构信息
+
+        读取 schemas 目录下的 YAML 文件，构建表和字段索引。
+        结果会被缓存。
+        """
+        if self._project_schema is not None:
+            return self._project_schema
+
+        schema: dict[str, Any] = {
+            "tables": {},
+            "table_name_to_id": {},
+        }
+
+        schemas_dir = self.project_path / "schemas"
+        if not schemas_dir.exists():
+            logger.warning(f"Schemas 目录不存在: {schemas_dir}")
+            self._project_schema = schema
+            return schema
+
+        try:
+            import yaml
+
+            for schema_file in schemas_dir.glob("*.yaml"):
+                try:
+                    with open(schema_file, encoding="utf-8") as f:
+                        data = yaml.safe_load(f) or {}
+
+                    table_id = data.get("id", "")
+                    table_name = data.get("name", "")
+                    columns = data.get("columns", [])
+
+                    if table_id:
+                        column_info = {}
+                        for col in columns:
+                            col_id = col.get("id", col.get("name", ""))
+                            col_name = col.get("name", col_id)
+                            col_type = col.get("type", "string")
+                            if col_id:
+                                column_info[col_id] = {
+                                    "name": col_name,
+                                    "type": col_type,
+                                }
+
+                        schema["tables"][table_id] = {
+                            "name": table_name,
+                            "columns": column_info,
+                        }
+
+                        if table_name:
+                            if table_name not in schema["table_name_to_id"]:
+                                schema["table_name_to_id"][table_name] = []
+                            schema["table_name_to_id"][table_name].append(table_id)
+
+                except Exception as e:
+                    logger.debug(f"读取 schema 文件失败 {schema_file}: {e}")
+
+        except Exception as e:
+            logger.error(f"加载项目 schema 失败: {e}")
+
+        self._project_schema = schema
+        return schema
+
+    def _fk_check(self, spec: dict[str, Any], index: int, action_type: str) -> list[ValidationError]:
+        """外键引用检查（注入到约束验证的回调中）"""
+        return validate_foreign_key_reference(spec, index, action_type, self._load_project_schema())
+
+    def _type_compat_check(
+        self, column_info: dict[str, Any], constraint_type: str, index: int, action_type: str
+    ) -> list[ValidationError]:
+        """类型兼容性检查（注入到约束验证的回调中）"""
+        return validate_type_compatibility(column_info, constraint_type, index, action_type)
+
+    def validate(self, actions: list[dict[str, Any]]) -> ValidationResult:
+        """验证动作列表
+
+        遍历所有动作，根据动作类型调用对应的验证方法。
+        """
+        result = ValidationResult()
+        schema = self._load_project_schema()
+
+        for index, action in enumerate(actions):
+            action_type = action.get("actionType", "")
+
+            # 结构校验前置（Pydantic）：枚举、必填、Range min<=max 等不依赖项目状态的规则。
+            # 失败则跳过该动作的上下文校验（数据已非法，上下文校验无意义），直接标记无效。
+            # 这是 specs.py 与各 validator 的分工：specs 管结构，validator 管上下文（表/列/FK 存在性）。
+            try:
+                parse_action_spec(action)
+            except SpecParseError as e:
+                result.errors.append(
+                    ValidationError(
+                        action_index=index,
+                        action_type=action_type,
+                        error_type="spec_structure_invalid",
+                        message=e.message,
+                        suggestion="请检查 spec 字段结构（类型枚举、必填字段、参数关系）",
+                    )
+                )
+                result.invalid_action_indices.add(index)
+                continue
+
+            if action_type in [
+                "ADD_CONSTRAINT_NODE",
+                "UPDATE_CONSTRAINT_NODE",
+                "DELETE_CONSTRAINT_NODE",
+            ]:
+                errors = validate_constraint_action(
+                    action,
+                    schema,
+                    index,
+                    self.CONSTRAINT_REQUIRED_PARAMS,
+                    self._type_compat_check,
+                    self._fk_check,
+                )
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type == "VALIDATE_PROJECT":
+                errors = validate_validate_action(action, schema, index)
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type in self.VALID_SCHEMA_TYPES:
+                errors = validate_schema_action(action, index)
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type in self.VALID_REGEX_TYPES:
+                errors = validate_regex_action(action, index)
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type in self.VALID_TRANSFORM_TYPES:
+                errors = validate_transform_action(action, index)
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type == "UPDATE_SETTINGS":
+                errors = validate_settings_action(action, index)
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            elif action_type == "ADD_TO_CANVAS":
+                # ADD_TO_CANVAS 不写盘，但仍需校验目标资源真实存在（避免显示不存在的资源）
+                errors = validate_canvas_action(action, index, str(self.project_path))
+                result.errors.extend(errors)
+                if errors:
+                    result.invalid_action_indices.add(index)
+                else:
+                    result.valid_actions.append(action)
+
+            else:
+                result.warnings.append(
+                    ValidationError(
+                        action_index=index,
+                        action_type=action_type,
+                        error_type="unknown_action_type",
+                        message=f"未知的动作类型: {action_type}",
+                        suggestion="系统可能不支持此操作，请检查 AI 响应",
+                    )
+                )
+                result.valid_actions.append(action)
+
+        return result

app/shared/services/llm/actions/diff_compute.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview apply_actions dry-run diff 计算
+
+shadow-copy 配置目录到临时目录 → process_actions(临时目录) → unified diff。
+dry-run 不触碰真实项目文件。
+
+核心函数:
+- compute_action_diff: 主入口，返回 DiffResult
+- _shadow_copy: 拷贝配置目录到临时位置
+- _build_file_diff: 生成单个文件的 unified diff
+"""
+
+from __future__ import annotations
+
+import difflib
+import logging
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from typing import Any
+
+from app.shared.services.llm.actions.action_processor import (
+    _collect_affected_files,
+    _snapshot_resource_files,
+    process_actions,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FileDiff:
+    """单个文件的 diff 信息。"""
+
+    path: str
+    status: str  # modified|created|deleted
+    diff: str
+    before_preview: str = ""
+    after_preview: str = ""
+
+
+@dataclass
+class DiffResult:
+    """dry-run diff 计算结果。"""
+
+    files: list[FileDiff] = field(default_factory=list)
+    summary: dict[str, int] = field(default_factory=lambda: {"modified": 0, "created": 0, "deleted": 0})
+    frontend_instructions: list[Any] = field(default_factory=list)
+    success: bool = True
+    error: str | None = None
+
+
+def compute_action_diff(actions: list[dict[str, Any]], workspace_path: str) -> DiffResult:
+    """计算 actions 对配置文件的预期变更(dry-run)。
+
+    参数:
+        actions: LLM 生成的 actions 列表
+        workspace_path: 项目配置目录路径
+
+    返回:
+        DiffResult: 含 file diffs、summary、frontend_instructions
+    """
+    result = DiffResult()
+
+    affected = _collect_affected_files(actions, workspace_path)
+    workspace_abs = os.path.abspath(workspace_path)
+
+    before_contents: dict[str, str | None] = {}
+    rel_paths: list[str] = []
+
+    for abs_p in affected:
+        rel = os.path.relpath(abs_p, workspace_abs)
+        rel_paths.append(rel)
+        try:
+            with open(abs_p, encoding="utf-8") as f:
+                before_contents[rel] = f.read()
+        except FileNotFoundError:
+            before_contents[rel] = None
+        except OSError:
+            before_contents[rel] = ""
+
+    tmp_root = tempfile.mkdtemp(prefix="precis_dryrun_")
+    try:
+        _shadow_copy(workspace_path, tmp_root)
+        proc = process_actions(actions, tmp_root)
+
+        if not proc.get("success"):
+            result.success = False
+            msgs = [r.get("message", "") for r in proc.get("results", []) if not r.get("success")]
+            result.error = "; ".join(msgs) if msgs else "process_actions 失败"
+            return result
+
+        # dry-run 后用资源文件快照对比检测新建文件（比按 spec 收集可靠——
+        # spec 可能不含 constraintFile，而 handler 内部派生的路径不在 _collect_affected_files 结果中）
+        pre_snapshot = _snapshot_resource_files(workspace_path)
+        post_snapshot = _snapshot_resource_files(tmp_root)
+        created_in_tmp = post_snapshot - pre_snapshot
+        for abs_p in created_in_tmp:
+            rel = os.path.relpath(abs_p, tmp_root)
+            if rel not in before_contents:
+                rel_paths.append(rel)
+                # 新建文件执行前不存在
+                before_contents[rel] = None
+
+        for rel in rel_paths:
+            tmp_p = os.path.join(tmp_root, rel)
+            try:
+                with open(tmp_p, encoding="utf-8") as f:
+                    after = f.read()
+            except FileNotFoundError:
+                after = None
+
+            before = before_contents.get(rel)
+            fd = _build_file_diff(rel, before, after)
+            if fd is not None:  # None = 无变化，跳过（避免确认框噪音）
+                result.files.append(fd)
+
+        for fd in result.files:
+            result.summary[fd.status] = result.summary.get(fd.status, 0) + 1
+
+        for r in proc.get("results", []):
+            fi = r.get("frontendInstructions")
+            if fi:
+                result.frontend_instructions.append(fi)
+
+        return result
+    finally:
+        shutil.rmtree(tmp_root, ignore_errors=True)
+
+
+def _shadow_copy(src_workspace: str, dst: str) -> None:
+    """将项目配置目录浅拷贝到临时目录(跳过 .precis 和 __pycache__)。"""
+    os.makedirs(dst, exist_ok=True)
+    ignore = shutil.ignore_patterns(".precis", "__pycache__")
+    for entry in os.listdir(src_workspace):
+        if entry in (".precis", "__pycache__"):
+            continue
+        s = os.path.join(src_workspace, entry)
+        d = os.path.join(dst, entry)
+        if os.path.isdir(s):
+            shutil.copytree(s, d, ignore=ignore, dirs_exist_ok=True)
+        else:
+            shutil.copy2(s, d)
+
+
+def _build_file_diff(rel: str, before: str | None, after: str | None) -> FileDiff | None:
+    """对比 before/after 生成 FileDiff。
+
+    返回 None 表示该文件无变化（before==after），调用方应跳过，
+    避免在确认框中显示"修改 → 无文本差异"误导用户。
+    """
+    if before is None and after is not None:
+        return FileDiff(
+            path=rel, status="created", diff=f"--- /dev/null\n+++ {rel}\n{after}", after_preview=after[:500]
+        )
+
+    if after is None and before is not None:
+        return FileDiff(path=rel, status="deleted", diff=f"--- {rel}\n+++ /dev/null\n", before_preview=before[:500])
+
+    # before 和 after 都存在（或都不存在）：计算真实 diff
+    if before == after:
+        # 内容完全一致——无变化，不生成 FileDiff（避免确认框出现"无文本差异"噪音）
+        return None
+
+    diff = "".join(
+        difflib.unified_diff(
+            (before or "").splitlines(keepends=True),
+            (after or "").splitlines(keepends=True),
+            fromfile=f"a/{rel}",
+            tofile=f"b/{rel}",
+        )
+    )
+    # diff 为空但内容不同（如仅末尾换行差异）——仍算 modified 但标注
+    return FileDiff(
+        path=rel,
+        status="modified",
+        diff=diff or "(无文本差异)",
+        before_preview=(before or "")[:500],
+        after_preview=(after or "")[:500],
+    )