precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/loader/loader_parts/inspector_helpers.py

@@ -0,0 +1,312 @@
+# 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.
+"""配置自检公共工具模块。
+
+提供所有检查模块共享的：
+- 展示名工具（display helpers）：将数据文件对象转为面向用户的友好显示字符串
+- Actions 工具：生成 LoadingError.actions 中的 UI 动作列表
+- 列标识符收集工具：递归收集 schema 列 id/name
+
+这些纯函数被 inspector_id_checks / inspector_reference_checks 共享，
+是跨检查模块的公共基础设施。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.shared.core.project.constraint.types import ConstraintFile
+    from app.shared.core.project.manual_data.types import ManualDataFile
+    from app.shared.core.project.regex.types import RegexNodeFile
+    from app.shared.core.project.schema.types import ColumnSpec, TableSchemaFile
+    from app.shared.core.project.transform.types import TransformFile
+
+
+# ============================================================================
+# 常量
+# ============================================================================
+
+_UUID_PATTERN = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+_CONSTRAINT_LABELS: dict[str, str] = {
+    "NotNull": "非空",
+    "Unique": "唯一",
+    "AllowedValues": "允许值",
+    "ForeignKey": "外键",
+    "Conditional": "条件",
+    "Scripted": "脚本",
+    "Range": "区间",
+    "Charset": "字符集",
+    "DateLogic": "日期逻辑",
+    "Composite": "组合",
+}
+
+_PLACEHOLDER_NAMES = {
+    "新建",
+    "未命名",
+    "新建规则",
+    "新规则",
+    "约束",
+    "规则",
+    "脚本约束",
+    "新建脚本约束",
+    "未命名约束",
+    "新建正则",
+    "正则",
+    "constraint",
+    "rule",
+    "new rule",
+}
+# 形如"新建XXX规则/约束/正则"这类类型词堆叠、无实质内容的占位值
+_PLACEHOLDER_PATTERN = re.compile(r"(新建|未命名|新的?|新增)[\w\u4e00-\u9fa5]*(规则|约束|正则)?")
+
+
+# ============================================================================
+# 展示名工具（display helpers）
+# ============================================================================
+
+
+def is_machine_id(value: str) -> bool:
+    """判断一个 id 是否为机器生成的不可读标识（UUID 或冗长编码）。
+
+    这类 id 直接拼进面向用户的文案会变成噪音，应由友好化处理转为中性占位。
+    """
+    if not value:
+        return False
+    # 标准 UUID
+    if _UUID_PATTERN.match(value):
+        return True
+    # 较长的 base64url / 编码串（schema id 常见形态，如 sc_ 后接 22 位编码）
+    stripped = value.split("_", 1)[-1] if value.startswith(("sc_", "c_", "r_", "t_")) else value
+    if len(stripped) >= 20 and re.fullmatch(r"[A-Za-z0-9_\-]+", stripped):
+        return True
+    return False
+
+
+def schema_display(schema_file: TableSchemaFile | None, fallback_id: str = "") -> str:
+    """生成数据表的友好显示名称。"""
+    if schema_file is None:
+        id_text = fallback_id or "未知"
+        return f"数据表「{id_text}」"
+    name = getattr(schema_file, "name", None) or getattr(schema_file, "id", "")
+    return f"数据表「{name}」"
+
+
+def is_meaningful_name(name: str | None) -> bool:
+    """判断 description/name 是否对用户有定位价值。
+
+    项目里约束的 description 常被填成"新建脚本约束""未命名规则"这类占位值，
+    把它们当"规则名"展示反而误导用户、无法定位。
+    """
+    if not name:
+        return False
+    text = name.strip()
+    if len(text) < 2:
+        return False
+    if text.lower() in _PLACEHOLDER_NAMES:
+        return False
+    if _PLACEHOLDER_PATTERN.fullmatch(text):
+        return False
+    return True
+
+
+def constraint_display(cf: ConstraintFile | None) -> str:
+    """生成约束规则的友好显示名称。
+
+    优先用有信息量的 description；若 description 是占位垃圾值（如"新建脚本约束"），
+    则不展示名字，只给类型标签（如"脚本规则"），避免误导。
+    """
+    if cf is None:
+        return "未知规则"
+    label = _CONSTRAINT_LABELS.get(getattr(cf, "type", ""), "规则")
+    desc = getattr(cf, "description", None)
+    if is_meaningful_name(desc):
+        return f"{label}规则「{desc}」"
+    return f"{label}规则"
+
+
+def regex_display(rf: RegexNodeFile | None) -> str:
+    """生成正则规则的友好显示名称。"""
+    if rf is None:
+        return "未知正则规则"
+    name = getattr(rf, "name", None) or getattr(rf, "id", "")
+    return f"正则规则「{name}」"
+
+
+def transform_display(tf: TransformFile | None) -> str:
+    """生成转换规则的友好显示名称。"""
+    if tf is None:
+        return "未知转换规则"
+    name = getattr(tf, "name", None) or getattr(tf, "id", "")
+    return f"转换规则「{name}」"
+
+
+def manual_data_display(mdf: ManualDataFile | None) -> str:
+    """生成 ManualData 节点的友好显示名称。"""
+    if mdf is None:
+        return "未知 ManualData 节点"
+    name = getattr(mdf, "column_name", None) or getattr(mdf, "id", "")
+    return f"ManualData 节点「{name}」"
+
+
+# ============================================================================
+# Actions 工具（UI 动作列表构建）
+# ============================================================================
+
+
+def default_actions_for_file(
+    file_path: str,
+    ref_id: str | None = None,
+    include_dismiss: bool = True,
+) -> list[dict]:
+    """为指向某个文件的错误生成通用动作列表。"""
+    actions: list[dict] = []
+    if file_path:
+        actions.append(
+            {
+                "type": "open_file",
+                "label": "打开文件",
+                "label_key": "inspection.actions.openFile",
+                "file_path": file_path,
+            }
+        )
+        actions.append(
+            {
+                "type": "copy",
+                "label": "复制文件路径",
+                "label_key": "inspection.actions.copyFilePath",
+                "text": file_path,
+            }
+        )
+    if ref_id:
+        actions.append(
+            {
+                "type": "copy",
+                "label": "复制 ID",
+                "label_key": "inspection.actions.copyId",
+                "text": ref_id,
+            }
+        )
+    if include_dismiss:
+        actions.append(
+            {
+                "type": "dismiss",
+                "label": "忽略",
+                "label_key": "inspection.actions.dismiss",
+            }
+        )
+    return actions
+
+
+def actions_for_node_ref(node_id: str | None) -> list[dict]:
+    """为指向画布节点（约束/正则等）的问题生成动作列表。
+
+    核心是提供 navigate（定位到画布节点），让用户能直接跳转到出问题的规则，
+    解决"不知道是哪条约束"的定位难题。辅以复制 ID 和忽略。
+    """
+    actions: list[dict] = []
+    if node_id:
+        actions.append(
+            {
+                "type": "navigate",
+                "label": "定位到节点",
+                "label_key": "inspection.actions.navigateToNode",
+                "target": node_id,
+            }
+        )
+        actions.append(
+            {
+                "type": "copy",
+                "label": "复制 ID",
+                "label_key": "inspection.actions.copyId",
+                "text": node_id,
+            }
+        )
+    actions.append(
+        {
+            "type": "dismiss",
+            "label": "忽略",
+            "label_key": "inspection.actions.dismiss",
+        }
+    )
+    return actions
+
+
+# ============================================================================
+# 涉事实体工具（context.involved 清单构建）
+# ============================================================================
+
+
+def file_entity_label(path: str) -> str:
+    """文件实体的用户可读显示名：取路径 basename；路径为空时回退原始串。"""
+    return os.path.basename(path) if path else ""
+
+
+def involved_entity(
+    kind: str,
+    entity_id: str = "",
+    path: str = "",
+    label: str = "",
+    navigable: bool = False,
+    role: str = "",
+) -> dict:
+    """构造 context.involved 实体条目（前后端契约，镜像前端 InspectionInvolvedEntity）。
+
+    所有配置自检问题经此统一发射涉事实体，kind/role 枚举与前端静态映射保持一致：
+        - kind: 实体类型 —— schema / constraint / regex / transform / manual_data 等
+        - role: 实体角色 —— conflicting（冲突方）/ referrer（引用方）/ target（被引用目标）
+                / file（纯文件实体）/ manifest（manifest 引用条目）；为空时不发射该字段
+        - navigable: 画布节点可否按 id 唯一寻址（如 id 冲突无法区分时为 False）
+
+    参数:
+        kind: 实体类型（必填）
+        entity_id: 实体 id（画布节点 id / 文件内 id / 引用 id）
+        path: 相对配置文件路径（未知时为空串，前端据此隐藏"打开文件"）
+        label: 用户可读显示名（缺省时回退 entity_id，再退化为 path）
+        navigable: 画布节点可否按 id 唯一寻址
+        role: 实体角色枚举串（空串表示不标注角色）
+    """
+    return {
+        "kind": kind,
+        "id": entity_id,
+        "path": path,
+        "label": label or entity_id or path,
+        "navigable": navigable,
+        **({"role": role} if role else {}),
+    }
+
+
+# ============================================================================
+# 列标识符收集工具
+# ============================================================================
+
+
+def collect_column_identifiers(columns: list[ColumnSpec]) -> set[str]:
+    """递归收集 schema 中所有列的 id 和 name（包括嵌套子列）。"""
+    collected: set[str] = set()
+    for c in columns or []:
+        if c.id is not None:
+            collected.add(c.id)
+        if c.name is not None:
+            collected.add(c.name)
+        if c.children:
+            collected |= collect_column_identifiers(c.children)
+    return collected

app/shared/core/project/loader/loader_parts/inspector_id_checks.py

@@ -0,0 +1,274 @@
+# 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.
+"""ID 一致性检查模块。
+
+检查 manifest 引用 ID 与文件内部 id 字段是否一致。
+不一致会导致配置无法正常生效（manifest 找不到文件，或文件被错误引用）。
+
+依赖：→ inspector_helpers（display + actions）+ inspection_ids + LoadingError
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from app.shared.core.project.loader.loader_parts import inspection_ids as ids
+from app.shared.core.project.loader.loader_parts.inspector_helpers import (
+    constraint_display,
+    default_actions_for_file,
+    file_entity_label,
+    involved_entity,
+    manual_data_display,
+    regex_display,
+    schema_display,
+    transform_display,
+)
+from app.shared.core.project.loader.types import LoadingError
+
+if TYPE_CHECKING:
+    from app.shared.core.project.constraint.types import ConstraintFile
+    from app.shared.core.project.manifest.types import ProjectManifest
+    from app.shared.core.project.manual_data.types import ManualDataFile
+    from app.shared.core.project.regex.types import RegexNodeFile
+    from app.shared.core.project.schema.types import TableSchemaFile
+    from app.shared.core.project.transform.types import TransformFile
+
+
+def build_id_mismatch_loading_error(
+    resource_type: str,
+    manifest_id: str,
+    file_id: str,
+    file_path: str,
+    manifest_display: str,
+    file_display: str,
+) -> LoadingError:
+    """构建 ID 不一致类型的 LoadingError（通用）。
+
+    involved 实体双侧对照，说明"哪一边的什么对不上"：
+        - file: 文件实体（文件内 id 为准，但画布无法按文件路径寻址 → 不可导航）
+        - manifest: project.precis.yaml 中的引用条目（不可导航）
+    """
+    return LoadingError(
+        id=ids.id_mismatch(resource_type, manifest_id, file_id),
+        severity="warning",
+        title="名字对不上",
+        description=(
+            f"项目配置里记的名字（{manifest_id}）和文件里的名字（{file_id}）对不上，可能导致这条配置无法正常生效。"
+        ),
+        fix_hint="点「一键修正」让两边名字统一即可。",
+        error_type="IdMismatchWarning",
+        file_path=file_path,
+        ref_id=manifest_id,
+        suggestion="请更新项目配置中的引用编号，或修改文件内部的编号使其一致",
+        actions=default_actions_for_file(file_path, manifest_id),
+        context={
+            "involved": [
+                involved_entity(
+                    kind=resource_type,
+                    entity_id=file_id,
+                    path=file_path,
+                    label=file_entity_label(file_path),
+                    navigable=False,
+                    role="file",
+                ),
+                involved_entity(
+                    kind=resource_type,
+                    entity_id=manifest_id,
+                    path="project.precis.yaml",
+                    label="project.precis.yaml",
+                    navigable=False,
+                    role="manifest",
+                ),
+            ]
+        },
+        title_key=f"inspection.issues.idMismatch.{resource_type}.title",
+        description_key=f"inspection.issues.idMismatch.{resource_type}.description",
+        fix_hint_key=f"inspection.issues.idMismatch.{resource_type}.fixHint",
+        message_params={
+            "manifestId": manifest_id,
+            "fileId": file_id,
+            "manifestDisplay": manifest_display,
+            "fileDisplay": file_display,
+        },
+        fix_api={
+            "method": "POST",
+            "path": "/project/manifest/fix-id-mismatch",
+            "body": {"resource_type": resource_type, "manifest_id": manifest_id, "file_id": file_id},
+        },
+    )
+
+
+def inspect_id_consistency(
+    manifest: ProjectManifest,
+    schema_files: dict[str, TableSchemaFile],
+    constraint_files: dict[str, ConstraintFile],
+    regex_node_files: dict[str, RegexNodeFile],
+    transform_files: dict[str, TransformFile],
+    manual_data_files: dict[str, ManualDataFile],
+    warnings: list[str],
+    loading_errors: list[LoadingError],
+) -> None:
+    """检查 manifest 引用 ID 与文件内部 ID 的一致性。"""
+    for schema_ref in manifest.schemas or []:
+        schema_file = schema_files.get(schema_ref.id)
+        if schema_file and schema_file.id != schema_ref.id:
+            manifest_display = schema_display(schema_files.get(schema_ref.id))
+            file_display = schema_display(schema_file)
+            msg = (
+                f"表结构 {schema_ref.path} 的 ID 与清单登记不一致"
+                f"（清单登记为「{schema_ref.id}」，文件内为「{schema_file.id}」），已按文件内的 ID 为准"
+            )
+            warnings.append(msg)
+            loading_errors.append(
+                build_id_mismatch_loading_error(
+                    "schema", schema_ref.id, schema_file.id, schema_ref.path, manifest_display, file_display
+                )
+            )
+
+    for constraint_ref in manifest.constraints or []:
+        constraint_file = constraint_files.get(constraint_ref.id)
+        if constraint_file and constraint_file.id != constraint_ref.id:
+            manifest_display = constraint_display(constraint_files.get(constraint_ref.id))
+            file_display = constraint_display(constraint_file)
+            msg = (
+                f"约束 {constraint_ref.path} 的 ID 与清单登记不一致"
+                f"（清单登记为「{constraint_ref.id}」，文件内为「{constraint_file.id}」），已按文件内的 ID 为准"
+            )
+            warnings.append(msg)
+            correct_ref_exists = any(
+                other_ref.id == constraint_file.id
+                for other_ref in (manifest.constraints or [])
+                if other_ref.id != constraint_ref.id
+            )
+            if correct_ref_exists:
+                loading_errors.append(
+                    LoadingError(
+                        id=ids.constraint_dup_ref(constraint_ref.id, constraint_file.id),
+                        severity="warning",
+                        title="同一条规则被重复登记",
+                        description=(
+                            f"项目配置中，规则文件「{constraint_ref.path}」被登记了两次，"
+                            f"其中一条的编号「{constraint_ref.id}」与文件中实际编号「{constraint_file.id}」不一致。"
+                            "重复登记会导致这条规则加载冲突。"
+                        ),
+                        fix_hint="点击「一键去重」自动清理重复记录（推荐），或手动从项目配置中删除多余条目。",
+                        error_type="IdMismatchWarning",
+                        file_path="project.precis.yaml",
+                        ref_id=constraint_ref.id,
+                        message=msg,
+                        suggestion="请更新项目配置中的引用编号，或修改文件内部的编号使其一致",
+                        actions=default_actions_for_file("project.precis.yaml", constraint_ref.id),
+                        # involved：被重复登记的规则文件 + project.precis.yaml 中的多余引用条目
+                        context={
+                            "involved": [
+                                involved_entity(
+                                    kind="constraint",
+                                    entity_id=constraint_file.id,
+                                    path=constraint_ref.path,
+                                    label=file_entity_label(constraint_ref.path),
+                                    navigable=False,
+                                    role="file",
+                                ),
+                                involved_entity(
+                                    kind="constraint",
+                                    entity_id=constraint_ref.id,
+                                    path="project.precis.yaml",
+                                    label="project.precis.yaml",
+                                    navigable=False,
+                                    role="manifest",
+                                ),
+                            ]
+                        },
+                        title_key="inspection.issues.dupConstraintRef.title",
+                        description_key="inspection.issues.dupConstraintRef.description",
+                        fix_hint_key="inspection.issues.dupConstraintRef.fixHint",
+                        message_params={
+                            "manifestId": constraint_ref.id,
+                            "fileId": constraint_file.id,
+                            "filePath": constraint_ref.path,
+                            "manifestDisplay": manifest_display,
+                            "fileDisplay": file_display,
+                        },
+                        fix_api={
+                            "method": "POST",
+                            "path": "/project/manifest/constraint/deduplicate",
+                        },
+                    )
+                )
+            else:
+                loading_errors.append(
+                    build_id_mismatch_loading_error(
+                        "constraint",
+                        constraint_ref.id,
+                        constraint_file.id,
+                        constraint_ref.path,
+                        manifest_display,
+                        file_display,
+                    )
+                )
+
+    for regex_ref in manifest.regex_nodes or []:
+        regex_file = regex_node_files.get(regex_ref.id)
+        if regex_file and regex_file.id != regex_ref.id:
+            manifest_display = regex_display(regex_node_files.get(regex_ref.id))
+            file_display = regex_display(regex_file)
+            msg = (
+                f"Regex ID 不一致: manifest 引用 ID '{regex_ref.id}' "
+                f"与文件内部 id '{regex_file.id}' 不匹配 (文件: {regex_ref.path})"
+            )
+            warnings.append(msg)
+            loading_errors.append(
+                build_id_mismatch_loading_error(
+                    "regex", regex_ref.id, regex_file.id, regex_ref.path, manifest_display, file_display
+                )
+            )
+
+    for transform_ref in manifest.transforms or []:
+        transform_file = transform_files.get(transform_ref.id)
+        if transform_file and transform_file.id != transform_ref.id:
+            manifest_display = transform_display(transform_files.get(transform_ref.id))
+            file_display = transform_display(transform_file)
+            msg = (
+                f"Transform ID 不一致: manifest 引用 ID '{transform_ref.id}' "
+                f"与文件内部 id '{transform_file.id}' 不匹配 (文件: {transform_ref.path})"
+            )
+            warnings.append(msg)
+            loading_errors.append(
+                build_id_mismatch_loading_error(
+                    "transform", transform_ref.id, transform_file.id, transform_ref.path, manifest_display, file_display
+                )
+            )
+
+    for manual_data_ref in manifest.manual_data or []:
+        manual_data_file = manual_data_files.get(manual_data_ref.id)
+        if manual_data_file and manual_data_file.id != manual_data_ref.id:
+            manifest_display = manual_data_display(manual_data_files.get(manual_data_ref.id))
+            file_display = manual_data_display(manual_data_file)
+            msg = (
+                f"ManualData ID 不一致: manifest 引用 ID '{manual_data_ref.id}' "
+                f"与文件内部 id '{manual_data_file.id}' 不匹配 (文件: {manual_data_ref.path})"
+            )
+            warnings.append(msg)
+            loading_errors.append(
+                build_id_mismatch_loading_error(
+                    "manual_data",
+                    manual_data_ref.id,
+                    manual_data_file.id,
+                    manual_data_ref.path,
+                    manifest_display,
+                    file_display,
+                )
+            )