precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/schema/writer.py

@@ -0,0 +1,139 @@
+# 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 表结构写入模块
+
+功能概述:
+- 写入 *.schema.yaml 文件
+- 优化字段顺序，提升 YAML 可读性
+
+架构设计:
+- 唯一入口: 封装 Pydantic 模型到 YAML 文件的转换逻辑
+- 字段排序: 按重要程度分组（核心 / 可选 / 内部）
+- 懒加载: ensure_schema_file 提供内存中创建或获取 Schema 对象的能力
+
+输入示例:
+    schema = TableSchemaFile(
+        version=2,
+        id="users",
+        name="users",
+        source=SourceSpec(mode="relative_file", path="data/users.xlsx"),
+        columns=[ColumnSpec(id="user_id", name="user_id", type="string")],
+    )
+
+输出示例:
+    save_schema(schema, "schemas/users.schema.yaml")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from app.shared.core.io.yaml import write_yaml_atomic
+
+from .types import TableSchemaFile
+
+if TYPE_CHECKING:
+    from .types import TableSchemaFile
+
+
+def save_schema(schema: TableSchemaFile, schema_path: str | Path) -> None:
+    """
+    @methoddesc 保存表结构到 YAML 文件。
+
+    字段顺序优化（按重要程度分组）：
+    L1（核心）：name, source, columns
+    L2（可选）：primary_key（通过 columns 内字段）
+    L3（内部）：version, id, _internal
+
+    处理流程：
+    1. 将 TableSchemaFile 对象序列化为字典（model_dump）
+    2. 按重要程度重新组织字段顺序
+    3. 从 id 提取 sheet 名并写入 source（如果 source 存在但 sheet 为空）
+    4. 写入 YAML 文件
+
+    :param schema: TableSchemaFile 对象，包含表的完整结构定义
+    :param schema_path: 保存路径，可以是相对路径或绝对路径
+    :raises IOError: 文件写入失败时抛出
+    """
+    # 步骤1：将 Pydantic 模型序列化为字典（exclude_none 与其余 writer 对齐）
+    data = schema.model_dump(exclude_none=True)
+
+    # 步骤2：按重要程度重排字段，剩余字段全量保留。
+    # 回归: 原固定白名单只挑 6 个键，会把 TableSchemaFile 的 sheet/constraints/
+    # script_checks 等字段在保存时静默丢弃（内嵌约束 roundtrip 即消失）——
+    # 与 regex/writer 的"全量保留+重排"修复模式对齐，新增字段不再被白名单吞掉。
+    ordered: dict = {}
+    for key in ("name", "source", "columns", "version", "id"):
+        if key in data:
+            ordered[key] = data.pop(key)
+    ordered.update(data)
+
+    # 步骤4：调用底层 YAML 写入工具
+    write_yaml_atomic(Path(schema_path), ordered)
+
+
+def ensure_schema_file(
+    schema_files: dict[str, TableSchemaFile],
+    table_id: str,
+    name: str,
+    columns: list | None = None,
+    source: dict | None = None,
+) -> TableSchemaFile:
+    """
+    @methoddesc 确保 schema_files 字典中包含指定 table_id 的 schema。
+    如果不存在则创建新的 TableSchemaFile。
+
+    处理流程：
+    1. 检查 schema_files 字典中是否已存在对应 table_id 的 Schema
+    2. 如存在，直接返回现有对象（复用）
+    3. 如不存在，创建新的 TableSchemaFile 并存入字典
+
+    使用场景：
+    - 项目初始化时批量创建 Schema
+    - 动态添加新的表结构
+    - 避免重复创建相同的 Schema 对象
+
+    :param schema_files: schema 文件字典，key 为 table_id，value 为 TableSchemaFile
+    :param table_id: 表 ID，作为字典的 key 使用
+    :param name: 表名，用于展示和校验
+    :param columns: 列定义列表，每个元素为列配置的字典
+    :param source: 数据源描述字典，包含 mode、path 等信息
+    :return: TableSchemaFile 对象（已存在或新创建）
+    """
+    # 步骤1：检查是否已存在对应 table_id 的 Schema
+    # 优先复用已有对象，避免重复创建
+    if table_id in schema_files:
+        return schema_files[table_id]
+
+    # 步骤2：导入必要的类型，用于构建对象
+    from .types import ColumnSpec, SourceSpec, TableSchemaFile
+
+    # 步骤3：构建新的 TableSchemaFile 对象
+    # 使用字典解包方式创建列定义列表
+    schema = TableSchemaFile.model_construct(
+        id=table_id,
+        name=name,
+        # 将列配置字典列表转换为 ColumnSpec 对象列表
+        columns=[ColumnSpec(**col) for col in (columns or [])],
+        # 将源配置字典转换为 SourceSpec 对象
+        source=SourceSpec(**source) if source else None,
+    )
+
+    # 步骤4：将新创建的 Schema 存入字典并返回
+    schema_files[table_id] = schema
+    return schema

app/shared/core/project/schema_ref_check.py

@@ -0,0 +1,95 @@
+# 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 Schema 引用扫描（REST 删除守卫与 AI DELETE_SCHEMA 共用，§2.6）
+
+删除 Schema 前扫描 constraints/regex/transforms 三类实体对该表的引用，
+返回引用清单供调用方决定拒绝（REST 409 / AI 失败消息）——单一事实源防两路再漂移。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from app.shared.core.io.yaml import read_yaml
+from app.shared.core.project.manifest.reader import load_manifest
+
+
+def find_schema_references(workspace_path: str, table_id: str) -> dict[str, list[str]]:
+    """扫描引用指定 schema 的实体。
+
+    Args:
+        workspace_path: 项目根目录（含 project.precis.yaml）
+        table_id: 目标表 ID
+
+    Returns:
+        {"constraints": [引用方 id...], "regex": [...], "transforms": [...]}
+        单个引用文件读取失败时跳过（容错与原 REST 守卫一致，不因损坏文件阻断删除）。
+    """
+    result: dict[str, list[str]] = {"constraints": [], "regex": [], "transforms": []}
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return result
+
+    manifest = load_manifest(manifest_path)
+
+    for c_ref in manifest.constraints:
+        try:
+            c_path = os.path.join(workspace_path, c_ref.path)
+            if os.path.isfile(c_path):
+                refs_data = (read_yaml(Path(c_path)) or {}).get("refs", {})
+                if (
+                    refs_data.get("table_id") == table_id
+                    or refs_data.get("from_table_id") == table_id
+                    or refs_data.get("to_table_id") == table_id
+                ):
+                    result["constraints"].append(c_ref.id)
+        except Exception:
+            continue
+
+    for r_ref in manifest.regex_nodes or []:
+        try:
+            r_path = os.path.join(workspace_path, r_ref.path)
+            if os.path.isfile(r_path):
+                source_ref = (read_yaml(Path(r_path)) or {}).get("source_ref", {})
+                if source_ref.get("table_id") == table_id:
+                    result["regex"].append(r_ref.id)
+        except Exception:
+            continue
+
+    for t_ref in manifest.transforms or []:
+        try:
+            t_path = os.path.join(workspace_path, t_ref.path)
+            if os.path.isfile(t_path):
+                t_data: dict[str, Any] = read_yaml(Path(t_path)) or {}
+                if t_data.get("input_from_node") == table_id:
+                    result["transforms"].append(t_ref.id)
+        except Exception:
+            continue
+
+    return result
+
+
+def format_reference_report(refs: dict[str, list[str]]) -> str:
+    """把引用清单格式化为用户可读的单行报告（空清单返回空串）。"""
+    parts = []
+    label_map = [("constraints", "constraint"), ("regex", "regex"), ("transforms", "transform")]
+    for key, label in label_map:
+        ids = refs.get(key) or []
+        if ids:
+            parts.append(f"{label} {', '.join(ids)}")
+    return "、".join(parts)

app/shared/core/project/template/__init__.py

@@ -0,0 +1,27 @@
+# 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 可复用约束模板模块
+
+功能概述:
+- 定义模板数据模型 (TemplateFile)
+- 提供模板 YAML 读取器 (reader)
+- 提供模板展开器 (expander)
+
+架构设计:
+- 模板是配置层概念，在项目加载阶段展开为标准 TransformFile/ConstraintFile/RegexNodeFile
+- 校验引擎（DAG Builder + Validator）无需任何修改
+"""

app/shared/core/project/template/expander.py

@@ -0,0 +1,263 @@
+# 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 模板展开器
+
+功能概述:
+- 将模板定义展开为标准的 TransformFile / ConstraintFile / RegexNodeFile / ManualDataFile
+- 处理 ID 命名空间映射 ({instance_id}__{local_id})
+- 处理 input_from_node 内部引用映射
+- 支持 {{param}} 占位符替换（实例参数覆盖模板默认值）
+
+架构设计:
+- 展开在项目加载阶段完成（config-time expansion）
+- 校验引擎（DAG Builder / Validator）看到的永远是展开后的标准文件
+- 展开结果直接合并到 transform_files / constraint_files / regex_files / manual_data_files
+- 参数替换: 先用模板声明的默认值构建 baseline params，再用实例 params 覆盖，
+  最后对节点值中的 {{param}} 占位符做替换
+
+输入示例:
+    expand_template(
+        template=TemplateFile(id="age_check", parameters=[...], nodes=[...]),
+        instance_id="users_age_check",
+        params={"min_age": 18, "max_age": 100},
+        input_from_node="users-users",
+    )
+
+输出示例:
+    (
+        [TransformFile(id="users_age_check__extract", type="Substring", ...)],
+        [ConstraintFile(id="users_age_check__check", type="Range", params={"min":18,"max":100})],
+        [],
+        [],
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, cast
+
+from app.shared.core.project.constraint.types.constraint_file 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.transform.types import TransformFile
+
+from .types import TemplateFile
+
+logger = logging.getLogger(__name__)
+
+# {{param}} 占位符正则
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+def _build_effective_params(
+    template: TemplateFile,
+    params: dict[str, Any] | None,
+    input_from_node: str | None,
+) -> dict[str, Any]:
+    """合并模板默认参数 + 实例参数，构造最终替换值表。
+
+    优先级: 实例 params > 模板 parameter.default。input_from_node 单独注入。
+    """
+    effective: dict[str, Any] = {}
+    for decl in template.parameters:
+        effective[decl.name] = decl.default
+    if params:
+        effective.update(params)
+    # input_from_node 作为特殊参数注入（供 {{input_from_node}} 占位符使用）
+    if input_from_node is not None:
+        effective["input_from_node"] = input_from_node
+    return effective
+
+
+def _substitute(value: Any, params: dict[str, Any]) -> Any:
+    """递归替换 value 中的 {{param}} 占位符。
+
+    - 字符串: 替换占位符；若整串就是单个占位符，返回原始类型（int/str 等）
+    - dict/list: 递归处理
+    - 其他类型: 原样返回
+    """
+    if isinstance(value, str):
+        # 整串恰好是单个占位符 → 返回原始类型值（保留 int 等）
+        single = _PLACEHOLDER_RE.fullmatch(value.strip())
+        if single and single.group(1) in params:
+            return params[single.group(1)]
+
+        # 否则做子串替换（结果始终为字符串）
+        def _repl(m: re.Match[str]) -> str:
+            key = m.group(1)
+            return str(params.get(key, m.group(0)))
+
+        return _PLACEHOLDER_RE.sub(_repl, value)
+    if isinstance(value, dict):
+        return {k: _substitute(v, params) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_substitute(v, params) for v in value]
+    return value
+
+
+def expand_template(
+    template: TemplateFile,
+    instance_id: str,
+    params: dict[str, Any] | None = None,
+    input_from_node: str | None = None,
+    errors: list[dict[str, str]] | None = None,
+) -> tuple[list[TransformFile], list[ConstraintFile], list[RegexNodeFile], list[ManualDataFile]]:
+    """@methoddesc 展开模板实例为标准配置文件
+
+    参数:
+        template: 模板定义
+        instance_id: 实例 ID（全局唯一）
+        params: 实例参数绑定值（覆盖模板默认值），默认 None
+        input_from_node: 实例级上游节点 ID（通常指向 Schema），默认 None
+        errors: 可选，节点级展开错误收集列表——单节点展开失败不中断其余节点，
+            失败信息以 {"node_id", "kind", "message"} 追加到此列表供调用方上报
+            （不传时失败节点仅记日志，保持旧行为）
+
+    返回:
+        (transforms, constraints, regex_nodes, manual_data_files) 四元组
+    """
+    # 构建最终替换值表（默认值 ← 实例 params ← input_from_node）
+    effective_params = _build_effective_params(template, params, input_from_node)
+
+    # 步骤 1：构建 ID 命名空间映射 {local_id → global_id}
+    id_map = {}
+    for node in template.nodes:
+        id_map[node.id] = f"{instance_id}__{node.id}"
+
+    # 步骤 2：展开各节点
+    transforms: list[TransformFile] = []
+    constraints: list[ConstraintFile] = []
+    regex_nodes: list[RegexNodeFile] = []
+    manual_data_files: list[ManualDataFile] = []
+
+    for node in template.nodes:
+        if not node.enabled:
+            continue
+
+        try:
+            global_id = id_map[node.id]
+
+            # 参数替换：对节点各字段中的 {{param}} 占位符做替换
+            substituted_input = _substitute(node.input_from_node, effective_params)
+            substituted_input_column = _substitute(node.input_column, effective_params)
+            substituted_params = _substitute(node.params, effective_params)
+            substituted_refs = _substitute(node.refs, effective_params)
+            substituted_output_columns = _substitute(node.output_columns, effective_params)
+            substituted_column_name = _substitute(node.column_name, effective_params)
+
+            # 解析 input_from_node（替换后的值）
+            effective_input = _resolve_input_from_node(substituted_input, id_map)
+
+            # 根据类型创建对应文件
+            if node.kind == "transform":
+                tf = TransformFile(
+                    version=2,
+                    id=global_id,
+                    type=cast(Any, node.type),
+                    enabled=True,
+                    description=node.description,
+                    input_from_node=effective_input,
+                    input_column=substituted_input_column,
+                    params=substituted_params,
+                    output_columns=substituted_output_columns,
+                )
+                transforms.append(tf)
+
+            elif node.kind == "constraint":
+                cf = ConstraintFile(
+                    version=2,
+                    id=global_id,
+                    type=cast(Any, node.type),
+                    enabled=True,
+                    description=node.description,
+                    refs=substituted_refs,
+                    params=substituted_params,
+                    input_from_node=effective_input,
+                    input_column=substituted_input_column,
+                )
+                constraints.append(cf)
+
+            elif node.kind == "regex":
+                rf = RegexNodeFile(
+                    version=2,
+                    id=global_id,
+                    name=node.description or global_id,
+                    description=node.description,
+                    pattern=substituted_params.get("pattern", "") if isinstance(substituted_params, dict) else "",
+                    uses_pattern=None,
+                    match_mode="full",
+                    case_sensitive=False,
+                    flags="",
+                    enabled=True,
+                    input_from_node=effective_input,
+                    input_column=substituted_input_column,
+                    output_columns=substituted_output_columns,
+                    source_ref=None,
+                    source_column_name=None,
+                )
+                regex_nodes.append(rf)
+
+            elif node.kind == "manualData":
+                mdf = ManualDataFile(
+                    version=2,
+                    id=global_id,
+                    column_name=substituted_column_name or "Column1",
+                    column_data_type=cast(Any, node.column_data_type or "string"),
+                    rows=node.rows,
+                    enabled=True,
+                    description=node.description,
+                    input_from_node=effective_input,
+                )
+                manual_data_files.append(mdf)
+
+        except Exception as e:
+            logger.warning(f"模板 '{template.id}' 的节点 '{node.id}' 展开失败: {e}")
+            # 节点级失败上报出口：失败节点被跳过但不再不可见——调用方
+            # （loader）据此生成 loading error，UI/CLI 均可见该约束缺失
+            if errors is not None:
+                errors.append({"node_id": node.id, "kind": node.kind, "message": str(e)})
+            continue
+
+    logger.debug(
+        f"模板 '{template.id}' 实例 '{instance_id}' 展开完成: "
+        f"{len(transforms)} transforms, {len(constraints)} constraints, "
+        f"{len(regex_nodes)} regex, {len(manual_data_files)} manual_data"
+    )
+    return transforms, constraints, regex_nodes, manual_data_files
+
+
+def _resolve_input_from_node(
+    raw_input: str | None,
+    id_map: dict[str, str],
+) -> str | None:
+    """解析节点的 input_from_node 字段
+
+    两种情况:
+        - None: 无上游
+        - 模板内部引用: 映射为全局 ID
+    """
+    if raw_input is None:
+        return None
+
+    # 检查是否是模板内部引用
+    if raw_input in id_map:
+        return id_map[raw_input]
+
+    # 可能本身就是一个外部节点 ID（直接引用 schema 等）
+    return raw_input

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

@@ -0,0 +1,120 @@
+# 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 模板配置文件读取模块
+
+功能概述:
+- 读取并解析 *.template.yaml 配置文件
+- 使用 Pydantic 模型进行数据验证
+- 校验模板结构合法性（至少 1 个 manualData + 1 个 constraint）
+
+输入示例:
+    template_path = Path("/path/to/project/templates/age_check.template.yaml")
+
+    # 文件内容:
+    # version: 2
+    # id: age_check
+    # name: 年龄校验
+    # nodes:
+    #   - id: md1
+    #     kind: manualData
+    #     type: ManualData
+    #     column_name: age
+    #     rows: [["18"]]
+    #   - id: check_range
+    #     kind: constraint
+    #     type: Range
+    #     input_from_node: md1
+    #     params:
+    #       min_value: 0
+    #       max_value: 120
+
+输出示例:
+    TemplateFile(
+        id="age_check",
+        name="年龄校验",
+        nodes=[TemplateNode(id="md1", ...), TemplateNode(id="check_range", ...)],
+    )
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .types import TemplateFile
+
+
+def validate_template_structure(template: TemplateFile) -> None:
+    """@methoddesc 校验模板结构合法性
+
+    模板必须满足以下条件：
+    - 至少 1 个 manualData 节点（作为输入起点）
+    - 至少 1 个 constraint 节点（作为校验终点）
+    - 节点 ID 全局唯一
+    - 非 manualData 节点的 input_from_node 必须指向模板内部节点
+
+    参数:
+        template: 模板定义
+
+    异常:
+        ValueError: 模板结构不合法
+    """
+    enabled_nodes = [n for n in template.nodes if n.enabled]
+    has_manual_data = any(n.kind == "manualData" for n in enabled_nodes)
+    has_constraint = any(n.kind == "constraint" for n in enabled_nodes)
+
+    if not has_manual_data:
+        raise ValueError(f"模板 '{template.id}' 结构不合法：至少需要 1 个启用的 manualData 节点作为输入起点")
+    if not has_constraint:
+        raise ValueError(f"模板 '{template.id}' 结构不合法：至少需要 1 个启用的 constraint 节点作为校验终点")
+
+    # 节点 ID 唯一性校验
+    seen_ids: set[str] = set()
+    duplicate_ids: set[str] = set()
+    for node in template.nodes:
+        if node.id in seen_ids:
+            duplicate_ids.add(node.id)
+        seen_ids.add(node.id)
+    if duplicate_ids:
+        raise ValueError(f"模板 '{template.id}' 结构不合法：存在重复节点 ID {sorted(duplicate_ids)}")
+
+    # 连通性校验：非 manualData 节点只能引用模板内部节点
+    enabled_node_ids = {n.id for n in enabled_nodes}
+    for node in enabled_nodes:
+        if node.kind == "manualData":
+            continue
+        input_from = node.input_from_node
+        if input_from is not None and input_from not in enabled_node_ids:
+            raise ValueError(
+                f"模板 '{template.id}' 结构不合法：节点 '{node.id}' 的 input_from_node "
+                f"指向模板外部节点 '{input_from}'，模板必须自包含"
+            )
+
+
+def load_template(template_path: Path) -> TemplateFile:
+    """@methoddesc 加载模板配置文件
+
+    参数:
+        template_path: 模板文件路径
+
+    返回:
+        TemplateFile 对象
+    """
+    with open(template_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return TemplateFile.model_validate(raw)