precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/suggestion_utils.py

@@ -0,0 +1,219 @@
+# 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 建议工具模块
+
+功能概述:
+- 提供约束类型标准化
+- 根据输入提供相似表名、字段名、约束类型的建议
+- 根据字段类型建议适用的约束
+
+输入示例:
+    suggestion = suggest_similar_table("user", schema)
+    normalized = normalize_constraint_type("not_null")
+
+输出示例:
+    "是否指: users?"
+    "NotNull"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# 支持的约束类型（标准名 + 别名）。
+# 单一事实源是 actions/registry.py 的 ALL_CONSTRAINT_TYPES；此处保持同步副本。
+# 直接 import registry 会形成循环导入（actions/__init__ → action_validator →
+# _constraint_validator → suggestion_utils → actions 包），故维持副本。
+# 新增约束类型时，两处都必须同步更新。
+VALID_CONSTRAINT_TYPES = {
+    "NotNull",
+    "Unique",
+    "Range",
+    "AllowedValues",
+    "ForeignKey",
+    "Conditional",
+    "Scripted",
+    "DateLogic",
+    "Charset",
+    "Composite",
+    # 别名兼容
+    "NOT_NULL",
+    "UNIQUE",
+    "RANGE",
+    "ALLOWED_VALUES",
+    "FOREIGN_KEY",
+    "CONDITIONAL",
+    "DATE_LOGIC",
+    "CHARSET",
+    "COMPOSITE",
+    "REGEX",
+}
+
+
+def normalize_constraint_type(constraint_type: str) -> str:
+    """
+    @methoddesc 标准化约束类型名
+
+    将各种别名、下划线命名、小写形式统一转换为标准 PascalCase 命名。
+    例如："not_null" -> "NotNull", "regex" -> "Scripted"
+
+    参数:
+        constraint_type: 原始类型名
+
+    返回:
+        标准化后的类型名
+
+    示例:
+        >>> normalize_constraint_type("not_null")
+        'NotNull'
+        >>> normalize_constraint_type("regex")
+        'Scripted'
+    """
+    # 处理下划线命名和小写
+    normalized = constraint_type.replace("_", "").lower()
+
+    # 映射到标准名
+    type_mapping = {
+        "notnull": "NotNull",
+        "unique": "Unique",
+        "range": "Range",
+        "allowedvalues": "AllowedValues",
+        "foreignkey": "ForeignKey",
+        "conditional": "Conditional",
+        "scripted": "Scripted",
+        "datelogic": "DateLogic",
+        "charset": "Charset",
+        "composite": "Composite",
+        "regex": "Scripted",  # 别名
+    }
+
+    return type_mapping.get(normalized, constraint_type)
+
+
+def suggest_similar_table(table_ref: str, schema: dict[str, Any]) -> str | None:
+    """
+    @methoddesc 建议相似的表名
+
+    当用户输入的表名不存在时，通过前缀/包含匹配查找相似表名并给出建议。
+
+    参数:
+        table_ref: 用户输入的表名或 ID
+        schema: 项目结构字典
+
+    返回:
+        建议文本字符串，如果没有相似表则返回 None
+
+    示例:
+        >>> suggest_similar_table("user", schema)
+        '是否指: users?'
+    """
+    all_names = list(schema["table_name_to_id"].keys()) + list(schema["tables"].keys())
+
+    # 简单的相似度匹配（前缀匹配）
+    suggestions = [name for name in all_names if table_ref.lower() in name.lower()]
+
+    if suggestions:
+        return f"是否指: {', '.join(suggestions[:3])}?"
+    return "请检查表名拼写或使用 'list tables' 查看可用表"
+
+
+def suggest_similar_column(column_name: str, table_info: dict[str, Any]) -> str | None:
+    """
+    @methoddesc 建议相似的字段名
+
+    当用户输入的字段名不存在时，通过包含匹配查找相似字段名并给出建议。
+
+    参数:
+        column_name: 用户输入的字段名
+        table_info: 表信息字典
+
+    返回:
+        建议文本字符串，如果没有相似字段则返回 None
+
+    示例:
+        >>> suggest_similar_column("emial", table_info)
+        '是否指: email?'
+    """
+    all_columns = [col["name"] for col in table_info["columns"].values()]
+
+    # 简单的相似度匹配
+    suggestions = [col for col in all_columns if column_name.lower() in col.lower()]
+
+    if suggestions:
+        return f"是否指: {', '.join(suggestions[:3])}?"
+
+    available = ", ".join(list(table_info["columns"].keys())[:5])
+    return f"可用字段: {available}..."
+
+
+def suggest_similar_constraint_type(constraint_type: str) -> str | None:
+    """
+    @methoddesc 建议相似的约束类型
+
+    当用户输入的约束类型不存在时，通过编辑距离和包含匹配查找相似类型并给出建议。
+
+    参数:
+        constraint_type: 用户输入的约束类型
+
+    返回:
+        建议文本字符串，如果没有相似类型则返回 None
+
+    示例:
+        >>> suggest_similar_constraint_type("NotNul")
+        '是否指: NotNull?'
+    """
+    # 简单的编辑距离或包含匹配
+    normalized = constraint_type.lower().replace("_", "")
+    suggestions = []
+
+    for valid_type in VALID_CONSTRAINT_TYPES:
+        valid_normalized = valid_type.lower().replace("_", "")
+        if normalized in valid_normalized or valid_normalized in normalized:
+            suggestions.append(valid_type)
+
+    if suggestions:
+        return f"是否指: {', '.join(suggestions[:3])}?"
+    return "支持的约束类型: NotNull, Unique, Range, AllowedValues, ForeignKey, Conditional, Scripted, DateLogic, Charset, Composite"
+
+
+def suggest_constraints_for_type(col_type: str) -> str:
+    """
+    @methoddesc 根据字段类型建议适用的约束
+
+    根据字段的数据类型返回推荐使用的约束类型列表，用于类型兼容性校验失败时的用户提示。
+
+    参数:
+        col_type: 字段类型，如 string、integer、decimal、boolean、date
+
+    返回:
+        建议的约束类型字符串
+
+    示例:
+        >>> suggest_constraints_for_type("string")
+        'NotNull, Unique, AllowedValues, Scripted(Regex)'
+        >>> suggest_constraints_for_type("integer")
+        'NotNull, Unique, Range, AllowedValues, ForeignKey'
+    """
+    type_to_constraints = {
+        "string": "NotNull, Unique, AllowedValues, Scripted(Regex)",
+        "integer": "NotNull, Unique, Range, AllowedValues, ForeignKey",
+        "decimal": "NotNull, Unique, Range, AllowedValues, ForeignKey",
+        "float": "NotNull, Unique, Range, AllowedValues",
+        "boolean": "NotNull, AllowedValues",
+        "date": "NotNull, Range, DateLogic",
+    }
+
+    return type_to_constraints.get(col_type.lower(), "NotNull, Unique")

app/shared/services/llm/validate_executor.py

@@ -0,0 +1,163 @@
+# 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 项目数据校验执行模块
+
+功能概述:
+- 调用后端校验引擎执行数据校验
+- 支持全量校验和指定表的过滤校验
+- 格式化校验结果和错误信息
+
+输入示例:
+    result = execute_validate_project("/workspace", table_filter="users")
+
+输出示例:
+    {
+        "success": True,
+        "message": "发现 3 个数据错误:\n  - users.email: ...",
+        "details": {"error_count": 3, "errors": [...], "duration_ms": 150}
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def execute_validate_project(workspace_path: str, table_filter: str | list[str] | None = None) -> dict[str, Any]:
+    """
+    @methoddesc 执行项目数据校验
+
+    调用后端校验引擎，根据项目清单和数据目录执行全量或指定表的数据校验。
+    格式化校验结果，最多显示前 10 个错误。
+
+    参数:
+        workspace_path: 项目工作区路径（包含 project.precis.yaml）
+        table_filter: 可选的表名过滤，支持单个表名字符串或表名列表
+
+    返回:
+        校验结果字典，包含 success、message、details
+        - success=True 表示校验流程执行成功（即使发现数据错误）
+        - details 中包含 error_count、errors 列表等
+
+    示例:
+        >>> result = execute_validate_project("/workspace", table_filter="users")
+        >>> result["success"]
+        True
+    """
+    manifest_path = os.path.join(workspace_path, "project.precis.yaml")
+    data_dir = workspace_path
+
+    if not os.path.exists(manifest_path):
+        return {"success": False, "message": f"项目配置文件不存在: {manifest_path}", "details": None}
+
+    try:
+        from app.shared.services.validation.executor import ValidationExecutor, ValidationOptions
+
+        # 使用默认配置执行校验
+        options = ValidationOptions(
+            timeout_seconds=30,
+            allow_unsafe_eval=False,
+            table_filter=table_filter,
+        )
+
+        executor = ValidationExecutor(manifest_path)
+        result = executor.execute(data_dir, options)
+
+        errors = result.get("errors", [])
+        loading_errors = result.get("loading_errors", [])
+        duration_ms = result.get("duration_ms", 0)
+
+        # 格式化加载警告（loading_errors 为非致命的加载阶段问题）
+        loading_section = ""
+        if loading_errors:
+            loading_details = []
+            for le in loading_errors[:10]:
+                le_type = le.get("error_type") or le.get("type") or "未知错误"
+                le_table = le.get("table", "")
+                # message 可能为空（inspect 级错误），优先读 title，与 CLI validate.py 处理一致
+                le_message = le.get("title") or le.get("message") or ""
+                prefix = f"{le_table}." if le_table else ""
+                loading_details.append(f"  - [{le_type}] {prefix}{le_message}")
+            if len(loading_errors) > 10:
+                loading_details.append(f"  ... 还有 {len(loading_errors) - 10} 个加载警告")
+            loading_section = "加载警告:\n" + "\n".join(loading_details)
+
+        if errors:
+            # 格式化错误信息，最多显示前 10 个
+            error_details = []
+            for err in errors[:10]:
+                # 兼容 error_type（真实数据）和 type（遗留 mock）
+                err_type = err.get("error_type") or err.get("type") or "未知错误"
+                table = err.get("table", "未知表")
+                column = err.get("column", "")
+                message = err.get("message", "")
+
+                if column:
+                    error_details.append(f"  - {table}.{column}: {message} ({err_type})")
+                else:
+                    error_details.append(f"  - {table}: {message} ({err_type})")
+
+            if len(errors) > 10:
+                error_details.append(f"  ... 还有 {len(errors) - 10} 个错误")
+
+            full_message = f"发现 {len(errors)} 个数据错误:\n" + "\n".join(error_details)
+            if loading_section:
+                full_message += "\n" + loading_section
+
+            return {
+                "success": True,  # 校验执行成功，只是发现数据错误
+                "message": full_message,
+                "details": {
+                    "error_count": len(errors),
+                    "duration_ms": duration_ms,
+                    "errors": errors[:20],  # 返回前20个错误详情
+                    "has_errors": True,
+                    "loading_errors": loading_errors[:20],
+                    "has_loading_errors": len(loading_errors) > 0,
+                    "table_filter": table_filter,
+                },
+            }
+        else:
+            if loading_section:
+                # 无校验错误但存在加载警告
+                full_message = f"数据校验通过，但存在 {len(loading_errors)} 个加载警告:\n" + "\n".join(
+                    loading_section.split("\n")[1:]  # 去掉 "加载警告:" 标题行，改用计数前缀
+                )
+            else:
+                full_message = f"数据校验通过（耗时 {duration_ms}ms）"
+
+            return {
+                "success": True,
+                "message": full_message,
+                "details": {
+                    "error_count": 0,
+                    "duration_ms": duration_ms,
+                    "errors": [],
+                    "has_errors": False,
+                    "loading_errors": loading_errors[:20],
+                    "has_loading_errors": len(loading_errors) > 0,
+                    "table_filter": table_filter,
+                },
+            }
+
+    except Exception as e:
+        logger.error(f"执行校验失败: {e}", exc_info=True)
+        return {"success": False, "message": f"校验执行失败: {str(e)}", "details": None}