precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/manifest/reader.py

@@ -0,0 +1,260 @@
+# 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 项目清单读取模块
+
+功能概述:
+- 从 project.precis.yaml 文件读取项目清单配置
+- 提供清单文件的加载、解析和校验功能
+- 支持批量加载多个约束配置文件
+
+架构设计:
+- 单一职责: 仅负责清单文件读取，不涉及写入逻辑
+- 依赖注入: 使用 YAML 读取工具进行文件解析
+- 类型安全: 使用 Pydantic 模型验证确保清单格式正确
+
+输入示例:
+    # project.precis.yaml
+    version: 2
+    project:
+      id: my-project
+      name: My Project
+    schemas:
+      - id: users
+        path: schemas/users.schema.yaml
+
+输出示例:
+    manifest = load_manifest("project.precis.yaml")
+    print(manifest.project.name)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from app.shared.core.io.yaml import read_yaml
+
+from .types import ProjectManifest
+
+if TYPE_CHECKING:
+    from .types import ProjectManifest
+
+
+def load_manifest(manifest_path: str | Path) -> ProjectManifest:
+    """
+    @methoddesc 从 project.precis.yaml 文件加载项目清单。
+
+    ============================================================================
+    配置文件示例 (本函数处理的配置文件长这样)
+    ============================================================================
+    本函数处理以下格式的 project.precis.yaml 文件：
+
+    ```yaml
+    # ============================================================
+    # Precis 项目清单文件 (project.precis.yaml)
+    # ============================================================
+    # 这是项目的入口文件，记录所有配置文件的索引引用
+    # 通过此文件，系统可以定位项目中所有的 schema、constraint 和 regex 配置
+
+    # 配置版本号，固定为 2
+    version: 2
+
+    # 项目基本信息
+    project:
+      id: my-data-project           # 项目唯一标识符（系统内部使用）
+      name: My Data Project         # 项目展示名称（UI 显示使用）
+
+    # 项目设置（所有可选字段都有默认值）
+    settings:
+      validation:                   # 校验行为设置
+        auto_validate: true         # 配置变更时自动执行校验
+        strict_mode: false          # 非严格模式（发现错误继续校验）
+        error_handling: continue    # 错误处理策略：continue/report/stop
+        timeout_seconds: 30         # 单次校验超时时间（秒）
+        batch_max_files: 100        # 批量校验最大文件数
+      file_processing:              # 文件处理设置
+        default_encoding: utf-8     # 默认文件编码
+        csv_delimiter: ","          # CSV 分隔符
+      script_security:              # 脚本安全设置
+        allow_eval: false           # 禁止 eval() 函数
+        allow_exec: false           # 禁止 exec() 函数
+        sandbox_mode: true          # 启用沙箱模式
+        timeout_seconds: 10         # 脚本执行超时时间（秒）
+
+    # Schema 文件索引列表
+    schemas:
+      - id: users                   # 表 ID（必须与 schema 文件内的 id 一致）
+        path: schemas/users.schema.yaml   # 相对于 manifest 所在目录的路径
+      - id: orders
+        path: schemas/orders.schema.yaml
+
+    # Constraint 文件索引列表
+    constraints:
+      - id: unique_user_email
+        path: constraints/unique_user_email.constraint.yaml
+
+    # Regex 节点文件索引列表
+    regex_nodes:
+      - id: phone_number
+        path: regex_nodes/phone_number.regex.yaml
+
+    # Patterns 目录路径
+    patterns_dir: patterns
+    ```
+
+    ============================================================================
+    业务场景 (什么情况下会调用这个函数)
+    ============================================================================
+    - 场景1: CLI 启动数据校验
+      用户在命令行执行 `precis validate --project ./my-project` 启动数据校验。
+      系统自动在项目目录查找 project.precis.yaml 文件，调用 load_manifest 读取并解析该文件。
+
+    - 场景2: 前端加载项目配置
+      用户在前端打开一个已存在的项目。
+      前端发送请求到后端获取项目配置，后端调用 load_manifest 读取项目清单，
+      将 ProjectManifest 对象序列化为 JSON 返回给前端。
+
+    - 场景3: 项目初始化向导
+      用户创建新项目时，系统会创建一个默认的 project.precis.yaml 文件，
+      然后调用 load_manifest 验证配置文件是否有效。
+
+    ============================================================================
+    数据流 (输入如何变成输出)
+    ============================================================================
+    输入参数:
+      - manifest_path: str | Path，项目清单文件路径
+        示例值: "./my-project/project.precis.yaml" 或 Path("project.precis.yaml")
+
+    处理步骤:
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 1: 参数标准化                                      │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: 字符串或 Path 对象                                  │
+      │ 操作: 使用 Path() 构造函数转换为 Path 对象                 │
+      │       确保跨平台兼容性，统一处理路径格式                    │
+      │ 输出: Path 对象                                          │
+      │ 示例:                                                    │
+      │   输入: "./my-project/project.precis.yaml" (str)       │
+      │   处理: Path("./my-project/project.precis.yaml")        │
+      │   输出: Path("./my-project/project.precis.yaml")        │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 2: 文件存在性检查                                   │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: Path 对象                                           │
+      │ 操作: 使用 path.exists() 方法检查文件是否存在             │
+      │       快速失败，避免后续无效的 I/O 操作                   │
+      │ 输出: 布尔值（存在为 True，不存在为 False）             │
+      │ 示例:                                                    │
+      │   输入: Path("./my-project/project.precis.yaml")        │
+      │   处理: Path("./my-project/project.precis.yaml").exists() │
+      │   输出: True (如果文件存在)                              │
+      │ 异常:                                                    │
+      │   - 不存在: 抛出 ValueError("manifest 文件不存在: ...") │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 3: YAML 解析                                       │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: Path 对象                                           │
+      │ 操作: 调用 read_yaml() 读取 YAML 文件内容                 │
+      │       返回包含所有配置项的字典对象                        │
+      │ 输出: Dict[str, Any] - 原始配置字典                     │
+      │ 示例:                                                    │
+      │   输入: Path("project.precis.yaml")                   │
+      │   处理: read_yaml(Path("project.precis.yaml"))         │
+      │   输出: {"version": 2, "project": {...}, "schemas": []} │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 4: Pydantic 模型验证                               │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: Dict[str, Any] - 原始配置字典                       │
+      │ 操作: 使用 ProjectManifest.model_validate() 验证数据       │
+      │       自动执行类型检查、必填字段验证、格式校验等           │
+      │ 输出: ProjectManifest 对象                                │
+      │ 示例:                                                    │
+      │   输入: {"version": 2, "project": {"id": "test"}}       │
+      │   处理: ProjectManifest.model_validate(字典)              │
+      │   输出: ProjectManifest(version=2, project=ProjectInfo(...)) │
+      │ 验证内容:                                                 │
+      │   - version 必须是整数 2                                 │
+      │   - project 必须是包含 id 和 name 的对象                 │
+      │   - settings 会被赋予默认值（如果省略）                   │
+      │   - schemas/constraints/regex_nodes 中的 ID 必须唯一       │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 5: 异常包装（验证失败时）                           │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: 验证异常                                            │
+      │ 操作: 将验证异常包装为 ValueError，添加文件路径信息       │
+      │       便于调用方定位问题                                  │
+      │ 输出: ValueError 异常                                     │
+      │ 示例:                                                    │
+      │   输入: ValidationError (Pydantic 验证错误)              │
+      │   处理: raise ValueError(f"manifest 校验失败: {path}\n{e}")│
+      │   输出: ValueError("manifest 校验失败: project.precis.yaml\n...") │
+      └─────────────────────────────────────────────────────────────┘
+
+    最终输出: ProjectManifest - 验证通过的项目清单对象
+      示例:
+        manifest = load_manifest("./my-project/project.precis.yaml")
+        print(manifest.project.name)  # 输出: My Data Project
+        print(len(manifest.schemas))  # 输出: 2
+        print(manifest.settings.validation.auto_validate)  # 输出: True
+
+    ============================================================================
+    异常处理 (可能出什么问题)
+    ============================================================================
+    | 异常类型 | 触发条件 | 处理方式 |
+    |---------|---------|---------|
+    | ValueError | manifest 文件不存在 | 检查文件路径是否正确 |
+    | ValueError | YAML 格式错误（如缩进错误）| 使用 YAML 格式检查工具验证文件 |
+    | ValueError | 必填字段缺失（如 project 字段）| 补全缺失的必填字段 |
+    | ValueError | 类型错误（如 version 不是整数）| 检查字段类型是否正确 |
+    | ValueError | ID 重复（schemas/constraints/regex_nodes）| 检查并移除重复的 ID |
+
+    :param manifest_path: 清单文件路径，支持字符串或 Path 对象
+    :return: ProjectManifest - 验证通过的项目清单对象
+    :raises ValueError: 文件不存在或格式校验失败时抛出
+
+    示例:
+        >>> manifest = load_manifest("./my-project/project.precis.yaml")
+        >>> print(manifest.project.name)
+        'My Data Project'
+        >>> print(f"Found {len(manifest.schemas)} schemas")
+        'Found 5 schemas'
+    """
+    # Step 1: 参数标准化 - 将输入转换为 Path 对象，确保统一处理
+    path = Path(manifest_path)
+
+    # Step 2: 文件存在性检查 - 快速失败，避免后续无效的 I/O 操作
+    if not path.exists():
+        raise ValueError(f"manifest 文件不存在: {manifest_path}")
+
+    # Step 3: YAML 解析 - 读取原始配置文件内容，返回字典结构
+    raw = read_yaml(path)
+
+    # Step 4: Pydantic 模型验证 - 确保配置符合预期的数据结构
+    #         自动执行类型检查、必填字段验证、格式校验等
+    try:
+        return ProjectManifest.model_validate(raw)
+    except Exception as e:
+        # Step 5: 异常包装 - 添加文件路径上下文，便于问题定位
+        raise ValueError(f"manifest 校验失败: {manifest_path}\n{e}") from e

app/shared/core/project/manifest/types.py

@@ -0,0 +1,91 @@
+# 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 项目清单类型统一导出模块
+
+功能概述:
+- 从 types_parts 各子模块聚合导出项目清单相关类型
+- 提供 V2 版本别名（如 ProjectManifestV2）以保持版本兼容
+
+架构设计:
+- 聚合导出模式: 将分散在 types_parts 中的类型集中暴露
+- 版本别名: 通过 ProjectManifestV2 = ProjectManifest 等映射降低上层迁移成本
+
+输入示例:
+    from app.shared.core.project.manifest.types import ProjectManifestV2, SchemaRefV2
+
+输出示例:
+    manifest = ProjectManifestV2(version=2, project=ProjectInfo(id="demo", name="Demo"))
+"""
+
+from __future__ import annotations
+
+from app.shared.core.project.manifest.types_parts.constants import V2_VERSION
+from app.shared.core.project.manifest.types_parts.data_source import DataSourceRef
+from app.shared.core.project.manifest.types_parts.info import ProjectInfo
+from app.shared.core.project.manifest.types_parts.manifest import ProjectManifest
+from app.shared.core.project.manifest.types_parts.refs import (
+    ConstraintRef,
+    ManualDataRef,
+    RegexRef,
+    SchemaRef,
+    TransformRef,
+)
+from app.shared.core.project.manifest.types_parts.settings import ProjectSettings
+from app.shared.core.project.manifest.types_parts.settings_file_processing import FileProcessingSettings
+from app.shared.core.project.manifest.types_parts.settings_script_security import ScriptSecuritySettings
+from app.shared.core.project.manifest.types_parts.settings_validation import ValidationSettings
+
+ProjectManifestV2 = ProjectManifest
+ProjectInfoV2 = ProjectInfo
+SchemaRefV2 = SchemaRef
+ConstraintRefV2 = ConstraintRef
+RegexNodeRefV2 = RegexRef
+TransformRefV2 = TransformRef
+DataSourceRefV2 = DataSourceRef
+ManualDataRefV2 = ManualDataRef
+ValidationSettingsV2 = ValidationSettings
+FileProcessingSettingsV2 = FileProcessingSettings
+ScriptSecuritySettingsV2 = ScriptSecuritySettings
+ProjectSettingsV2 = ProjectSettings
+
+__all__ = [
+    "ConstraintRef",
+    "ConstraintRefV2",
+    "DataSourceRef",
+    "DataSourceRefV2",
+    "FileProcessingSettings",
+    "FileProcessingSettingsV2",
+    "ManualDataRef",
+    "ManualDataRefV2",
+    "ProjectInfo",
+    "ProjectInfoV2",
+    "ProjectManifest",
+    "ProjectManifestV2",
+    "ProjectSettings",
+    "ProjectSettingsV2",
+    "RegexNodeRefV2",
+    "RegexRef",
+    "SchemaRef",
+    "SchemaRefV2",
+    "TransformRef",
+    "TransformRefV2",
+    "ScriptSecuritySettings",
+    "ScriptSecuritySettingsV2",
+    "V2_VERSION",
+    "ValidationSettings",
+    "ValidationSettingsV2",
+]

app/shared/core/project/manifest/types_parts/__init__.py

@@ -0,0 +1,60 @@
+# 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 项目清单子类型聚合导出模块
+
+功能概述:
+- 集中导出项目清单各组成部分的类型定义
+- 简化上层模块对 types_parts 的导入路径
+
+架构设计:
+- 扁平化导出: 将多层类型统一暴露为一级符号
+- 向后兼容: __all__ 明确控制公开接口
+
+输入示例:
+    from app.shared.core.project.manifest.types_parts import ProjectManifest, SchemaRef, ProjectSettings
+
+输出示例:
+    manifest = ProjectManifest(version=2, project=ProjectInfo(id="demo", name="Demo"))
+"""
+
+from app.shared.core.project.manifest.types_parts.constants import V2_VERSION
+from app.shared.core.project.manifest.types_parts.data_source import DataSourceRef
+from app.shared.core.project.manifest.types_parts.info import ProjectInfo
+from app.shared.core.project.manifest.types_parts.manifest import ProjectManifest
+from app.shared.core.project.manifest.types_parts.refs import ConstraintRef, ManualDataRef, RegexRef, SchemaRef
+from app.shared.core.project.manifest.types_parts.settings import ProjectSettings
+from app.shared.core.project.manifest.types_parts.settings_file_processing import FileProcessingSettings
+from app.shared.core.project.manifest.types_parts.settings_script_security import ScriptSecuritySettings
+from app.shared.core.project.manifest.types_parts.settings_validation import ValidationSettings
+from app.shared.core.project.manifest.types_parts.template import TemplateInstanceRef, TemplateRef
+
+__all__ = [
+    "ConstraintRef",
+    "DataSourceRef",
+    "FileProcessingSettings",
+    "ManualDataRef",
+    "ProjectInfo",
+    "ProjectManifest",
+    "ProjectSettings",
+    "RegexRef",
+    "SchemaRef",
+    "ScriptSecuritySettings",
+    "TemplateInstanceRef",
+    "TemplateRef",
+    "ValidationSettings",
+    "V2_VERSION",
+]

app/shared/core/project/manifest/types_parts/constants.py

@@ -0,0 +1,40 @@
+# 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 Manifest 常量定义模块
+
+功能概述:
+- 定义 manifest 相关的常量值
+- 当前仅包含版本号常量
+- 未来版本升级时在此添加新常量
+
+架构设计:
+- 版本号: V2_VERSION = 2
+- 集中管理: 所有 manifest 相关常量统一放在此模块
+- 未来版本升级时在此添加新常量
+
+输入示例:
+    从其他模块导入版本号常量
+    from app.shared.core.project.manifest.types_parts.constants import V2_VERSION
+
+输出示例:
+    print(V2_VERSION)  # 输出: 2
+"""
+
+# 当前支持的 manifest 配置版本号
+# 版本号用于区分不同版本的配置格式，确保兼容性
+# 当配置格式发生重大变更时，需要增加版本号
+V2_VERSION = 2

app/shared/core/project/manifest/types_parts/data_source.py

@@ -0,0 +1,68 @@
+# 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 数据源配置类型定义模块
+
+功能概述:
+- 定义项目数据源的引用结构
+- 支持多数据源配置，便于扩展
+
+架构设计:
+- DataSourceRef: 单个数据源的引用定义
+- 支持多种路径模式：相对路径、绝对路径
+
+使用场景:
+- 全量校验时，后端根据此配置自动查找数据文件
+- 支持多数据源目录配置
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class DataSourceRef(BaseModel):
+    """@classdesc 数据源引用配置
+
+    用于在 manifest.yaml 中定义数据源的位置。
+    支持多种路径模式，方便项目迁移和共享。
+
+    字段说明:
+        - id: 数据源唯一标识符
+        - path: 数据源目录路径
+        - mode: 路径模式，'relative' 表示相对于项目目录，'absolute' 表示绝对路径
+        - description: 数据源描述（可选）
+
+    示例:
+        # 相对路径模式（推荐，便于项目迁移）
+        data_sources:
+          - id: primary
+            path: data
+            mode: relative
+            description: 主数据目录
+
+        # 绝对路径模式
+        data_sources:
+          - id: external
+            path: /mnt/data/external
+            mode: absolute
+            description: 外部数据源
+    """
+
+    id: str = Field(..., description="数据源唯一标识符")
+    path: str = Field(..., description="数据源目录路径")
+    mode: str = Field("relative", description="路径模式: 'relative' 或 'absolute'")
+    description: str | None = Field(None, description="数据源描述（可选）")

app/shared/core/project/manifest/types_parts/info.py

@@ -0,0 +1,59 @@
+# 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 项目信息类型定义模块
+
+功能概述:
+- 定义项目的基本信息结构
+- 包括项目 ID 和展示名称
+
+架构设计:
+- 轻量级模型: 仅包含必要的基本信息
+- 必需字段: id 和 name 都是必填的
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ProjectInfo(BaseModel):
+    """@classdesc 项目基本信息
+
+    用于在 manifest.yaml 中定义项目的基本信息。
+
+    字段说明:
+        - id: 项目的稳定标识符，用于系统内部引用（不应改变）
+        - name: 项目的展示名称，用于 UI 显示
+        - description: 项目描述（可选）
+
+    示例:
+        # manifest.yaml 中的定义
+        project:
+          id: user-management
+          name: 用户管理系统
+          description: 管理公司用户数据
+
+        # 对应的 Python 对象
+        ProjectInfo(id="user-management", name="用户管理系统", description="...")
+    """
+
+    id: str = Field(..., description="项目 ID（稳定标识）")
+    name: str = Field(..., description="项目展示名称")
+    # 回归: manifest 类型 docstring 的示例一直包含 description，模型却曾缺失该字段——
+    # 任何 manifest 重写（PUT manifest/schema/settings 等）都会把用户手写的
+    # description 从磁盘上静默抹掉。恢复为可选字段以保全 roundtrip。
+    description: str | None = Field(None, description="项目描述（可选）")