precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/constraint/builders/base.py

@@ -0,0 +1,100 @@
+# 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 约束构建器基类与共享工具
+
+定义 BuilderInput / BuilderResult / BuilderFn 协议，以及各构建器共享的辅助函数。
+
+架构设计（参考前端 nodeDataBuilder/registry.ts 的可注册构建器模式）：
+- 每种约束类型的构建逻辑封装为独立 BuilderFn
+- 共享的单列映射逻辑提取为 resolve_single_column，消除 NotNull/AllowedValues/
+  DateLogic/Range/Charset 之间的重复代码
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..schema.types import TableSchemaFile
+    from ..types import ConstraintFile
+
+
+class BuilderInput:
+    """构建器输入上下文（所有 BuilderFn 共享）。
+
+    封装 refs/params/const_id/column_map/schema_files，以及 Composite 递归所需的
+    create_child 回调（依赖注入，避免 builder 直接 import factory 形成循环依赖）。
+    """
+
+    def __init__(
+        self,
+        const: ConstraintFile,
+        refs: dict[str, Any],
+        params: dict[str, Any],
+        column_name_by_table_id: dict[str, dict[str, str]],
+        schema_files: dict[str, TableSchemaFile],
+        create_child: Callable[[ConstraintFile, dict[str, TableSchemaFile]], tuple[Any | None, str | None]],
+    ) -> None:
+        self.const = const
+        self.refs = refs
+        self.params = params
+        self.column_name_by_table_id = column_name_by_table_id
+        self.schema_files = schema_files
+        self.create_child = create_child
+
+    @property
+    def const_id(self) -> str:
+        return self.const.id
+
+
+# 构建结果：(kwargs, error)。成功时 error 为 None；失败时 kwargs 为空字典。
+BuilderResult = tuple[dict[str, Any], str | None]
+
+# 构建器函数签名：接收 BuilderInput，返回 BuilderResult
+BuilderFn = Callable[[BuilderInput], BuilderResult]
+
+
+def table_display_name(inp: BuilderInput, table_id: str) -> str:
+    """构建期错误消息用的表显示名（schema 缺失或未命名时兜底原 ID）。"""
+    schema = inp.schema_files.get(table_id)
+    return (schema.name if schema is not None else None) or table_id
+
+
+def resolve_single_column(
+    inp: BuilderInput,
+    table_key: str = "table_id",
+    col_key: str = "column_id",
+) -> BuilderResult:
+    """单列映射共享逻辑（NotNull/AllowedValues/DateLogic/Range/Charset 共用）。
+
+    从 refs 提取 table_id 和 column_id，映射为 table_id（保持稳定）和 column_name。
+    映射失败时返回错误。
+    """
+    table_id = inp.refs.get(table_key)
+    col_id = inp.refs.get(col_key)
+    if table_id is None:
+        return {}, f"缺少 {table_key}"
+    if col_id is None:
+        return {}, f"缺少 {col_key}"
+
+    col_name = inp.column_name_by_table_id.get(table_id, {}).get(col_id)
+    if col_name is None:
+        # 表此时必然存在（factory 已做过存在性检查），用显示名报错便于定位；
+        # 兜底保留 ID 防御上游裸调用路径
+        return {}, f"引用的列 '{col_id}' 不存在于表 '{table_display_name(inp, table_id)}' 中"
+
+    return {"table": table_id, "column": col_name}, None

app/shared/core/project/constraint/builders/composite.py

@@ -0,0 +1,77 @@
+# 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 Composite 复合约束构建器
+
+递归创建子约束（通过 BuilderInput.create_child 回调，避免直接 import factory 形成循环依赖）。
+禁止嵌套 Composite；子约束用 model_validate 正常校验；子错误聚合为 warning。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..registry import normalize_constraint_type
+from ..types import ConstraintFile
+from .base import BuilderInput, BuilderResult
+from .registry import register_builder
+
+logger = logging.getLogger(__name__)
+
+
+@register_builder("Composite")
+def build_composite(inp: BuilderInput) -> BuilderResult:
+    """Composite: params {logic, sub_constraints: [ConstraintFile-like dict]}，refs 原样保留。"""
+    params = inp.params
+    refs = inp.refs
+    sub_configs = params.get("sub_constraints", [])
+    sub_constraints = []
+    sub_errors: list[str] = []
+
+    for sub_cfg in sub_configs:
+        sub_type = normalize_constraint_type(sub_cfg.get("type", ""))
+        if sub_type == "Composite":
+            # 禁止递归嵌套 Composite；计入子错误而非静默跳过
+            sub_errors.append("不允许嵌套 Composite 子约束")
+            continue
+        # 使用 model_validate 正常构造（执行 Pydantic 校验），
+        # 过去用 model_construct 跳过校验导致非法子约束被静默接受
+        try:
+            sub_file = ConstraintFile.model_validate(sub_cfg)
+        except Exception as e:
+            sub_errors.append(f"子约束 '{sub_cfg.get('id', '?')}' 配置非法: {e}")
+            continue
+        # 通过依赖注入的回调创建子约束（不直接 import factory.create_constraint）
+        sub_constraint, sub_error = inp.create_child(sub_file, inp.schema_files)
+        if sub_constraint is not None:
+            sub_constraints.append(sub_constraint)
+        elif sub_error is not None:
+            # 收集子错误而非静默忽略（过去注释"忽略即可"掩盖了真实问题）
+            sub_errors.append(f"子约束 '{sub_file.id}' 创建失败: {sub_error}")
+        # sub_error 为 None 且 sub_constraint 为 None：未启用，正常跳过
+
+    if sub_errors:
+        # 存在任何子错误即整条复合约束构建失败（fail-closed）：复合是 all-or-nothing
+        # 的逻辑单元，缺一个子约束都会改变语义（all 少一项 → 假通过；any 多一项 → 假失败）。
+        # 返回 error 交由工厂跳过该约束并写入项目 warnings，对用户可见。
+        # 原实现仅 logger.warning 且返回空 sub_constraints——约束静默空过、客户端不可见。
+        logger.warning(f"Composite 约束 '{inp.const_id}' 子约束存在错误: {'; '.join(sub_errors)}")
+        return {}, f"子约束配置非法已跳过整条约束: {'; '.join(sub_errors)}"
+
+    return {
+        "sub_constraints": sub_constraints,
+        "logic": params.get("logic", "all"),
+        "refs": refs,
+    }, None

app/shared/core/project/constraint/builders/conditional.py

@@ -0,0 +1,67 @@
+# 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 Conditional 约束构建器
+
+THEN 列 + IF 条件列表逐项映射。条件列支持回退用 column_id（transform 派生列不在 schema 中）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import BuilderInput, BuilderResult
+from .registry import register_builder
+
+
+@register_builder("Conditional")
+def build_conditional(inp: BuilderInput) -> BuilderResult:
+    """Conditional: refs {table_id, then_column_id, if_conditions, if_logic}，params {then_condition}。"""
+    refs = inp.refs
+    table_id = refs.get("table_id")
+    then_col_id = refs.get("then_column_id")
+    if table_id is None:
+        return {}, "缺少 table_id"
+    if then_col_id is None:
+        return {}, "缺少 then_column_id"
+    if_logic = refs.get("if_logic", "and")
+    if_conditions = refs.get("if_conditions") or []
+
+    col_map = inp.column_name_by_table_id.get(table_id, {})
+    # 列名映射：优先从 schema 查找，找不到则直接使用 column_id
+    # （支持 transform 生成的派生列，这些列不在原始 schema 中）
+    then_col_name = col_map.get(then_col_id) or then_col_id
+
+    # 处理 IF 条件列表，将 column_id 映射为 column_name
+    normalized_conditions: list[dict[str, Any]] = []
+    for cond in if_conditions:
+        if_col_id = cond.get("if_column_id")
+        if_col_name = col_map.get(if_col_id) or if_col_id
+        normalized_conditions.append(
+            {
+                "if_column": if_col_name,
+                "operator": cond.get("operator", "eq"),
+                "value": cond.get("value"),
+                "values": cond.get("values"),
+            }
+        )
+
+    return {
+        "table": table_id,
+        "then_column": then_col_name,
+        "then_condition": inp.params.get("then_condition"),
+        "if_conditions": normalized_conditions,
+        "if_logic": if_logic,
+    }, None

app/shared/core/project/constraint/builders/foreign_key.py

@@ -0,0 +1,53 @@
+# 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 ForeignKey 约束构建器
+
+双向引用（from/to 两端表+列），与其他单端约束不同。
+"""
+
+from __future__ import annotations
+
+from .base import BuilderInput, BuilderResult, table_display_name
+from .registry import register_builder
+
+
+@register_builder("ForeignKey")
+def build_foreign_key(inp: BuilderInput) -> BuilderResult:
+    """ForeignKey: refs {from_table_id, from_column_id, to_table_id, to_column_id}。"""
+    refs = inp.refs
+    from_table_id = refs.get("from_table_id")
+    from_col_id = refs.get("from_column_id")
+    to_table_id = refs.get("to_table_id")
+    to_col_id = refs.get("to_column_id")
+
+    if from_table_id is None or to_table_id is None:
+        return {}, "缺少必要的表引用"
+
+    from_col_name = inp.column_name_by_table_id.get(from_table_id, {}).get(str(from_col_id))
+    to_col_name = inp.column_name_by_table_id.get(to_table_id, {}).get(str(to_col_id))
+
+    if from_col_name is None:
+        # 报错用表显示名（from 侧经 factory 存在性检查；to 侧可能悬空，兜底 ID）
+        return {}, f"引用的列 '{from_col_id}' 不存在于表 '{table_display_name(inp, from_table_id)}' 中"
+    if to_col_name is None:
+        return {}, f"引用的列 '{to_col_id}' 不存在于表 '{table_display_name(inp, to_table_id)}' 中"
+
+    return {
+        "from_table": from_table_id,
+        "from_column": from_col_name,
+        "to_table": to_table_id,
+        "to_column": to_col_name,
+    }, None

app/shared/core/project/constraint/builders/registry.py

@@ -0,0 +1,64 @@
+# 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 约束构建器注册表
+
+核心入口：build_kwargs(type_name, inp) → BuilderResult
+各约束类型通过 register_builder 装饰器注册到 CONSTRAINT_BUILDERS 字典。
+未注册的类型返回 (None, None)，由 factory 走通用降级路径。
+
+设计（参考前端 nodeDataBuilder/registry.ts）：
+- 注册表是 dict[type_name, BuilderFn]
+- 新增约束类型 = 在对应 builder 文件加一个 @register_builder，其余自动派生
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import BuilderFn, BuilderInput, BuilderResult
+
+
+# 构建器注册表：type_name -> BuilderFn
+CONSTRAINT_BUILDERS: dict[str, BuilderFn] = {}
+
+
+def register_builder(type_name: str) -> Callable[[BuilderFn], BuilderFn]:
+    """装饰器：注册约束构建器到 CONSTRAINT_BUILDERS。
+
+    用法：
+        @register_builder("NotNull")
+        def build_not_null(inp: BuilderInput) -> BuilderResult:
+            ...
+    """
+
+    def decorator(fn: BuilderFn) -> BuilderFn:
+        CONSTRAINT_BUILDERS[type_name] = fn
+        return fn
+
+    return decorator
+
+
+def build_kwargs(type_name: str, inp: BuilderInput) -> BuilderResult | None:
+    """主入口：根据约束类型查找构建器并执行。
+
+    :return: (kwargs, error) 元组；若类型未注册返回 None（调用方走通用降级）
+    """
+    builder = CONSTRAINT_BUILDERS.get(type_name)
+    if builder is None:
+        return None
+    return builder(inp)

app/shared/core/project/constraint/builders/scripted.py

@@ -0,0 +1,51 @@
+# 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 Scripted 约束构建器
+
+column_id 可选（表达式可不绑定到具体列）。
+"""
+
+from __future__ import annotations
+
+from .base import BuilderInput, BuilderResult
+from .registry import register_builder
+
+
+@register_builder("Scripted")
+def build_scripted(inp: BuilderInput) -> BuilderResult:
+    """Scripted: refs {table_id, column_id?}，params {name, expression}。"""
+    refs = inp.refs
+    table_id = refs.get("table_id")
+    col_id = refs.get("column_id")
+
+    if table_id is None:
+        # 配置残缺 fail-fast：与 base.resolve_single_column 的"缺少 table_id"同口径，
+        # 不再以 table=None 静默构建出语义偷换的约束
+        return {}, "缺少 table_id"
+
+    kwargs: dict[str, object] = {"table": table_id}
+    # 使用约束 ID 作为默认名称
+    kwargs["name"] = inp.params.get("name", inp.const_id)
+    kwargs["expression"] = inp.params.get("expression", "")
+    # column_id 是可选的；一旦配置则必须映射成功——原实现 .get 链返回 None 时
+    # 照样写入 kwargs（column=None 即整行脚本语义），列改名后的失效引用被静默降级
+    if col_id:
+        col_name = inp.column_name_by_table_id.get(table_id, {}).get(str(col_id))
+        if col_name is None:
+            return {}, f"引用的列 '{col_id}' 不存在于表 '{table_id}' 中"
+        kwargs["column"] = col_name
+
+    return kwargs, None  # type: ignore[return-value]

app/shared/core/project/constraint/builders/single_column.py

@@ -0,0 +1,86 @@
+# 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 单列约束构建器
+
+NotNull / AllowedValues / DateLogic / Range / Charset 共享"单列映射"结构，
+区别仅在于从 params 提取的额外字段。本模块用统一的 build_single_column 加上各类型的
+params 适配器，消除原 factory.py 中 4 处近乎逐行重复的代码。
+
+Charset 此前无独立分支（走通用路径导致残缺实例），此处补全修复。
+"""
+
+from __future__ import annotations
+
+from .base import BuilderInput, BuilderResult, resolve_single_column
+from .registry import register_builder
+
+
+@register_builder("NotNull")
+def build_not_null(inp: BuilderInput) -> BuilderResult:
+    """NotNull: refs {table_id, column_id}，无 params。"""
+    return resolve_single_column(inp)
+
+
+@register_builder("AllowedValues")
+def build_allowed_values(inp: BuilderInput) -> BuilderResult:
+    """AllowedValues: refs {table_id, column_id}，params {allowed_values}。"""
+    kwargs, error = resolve_single_column(inp)
+    if error:
+        return {}, error
+    kwargs["allowed_values"] = inp.params.get("allowed_values", [])
+    return kwargs, None
+
+
+@register_builder("DateLogic")
+def build_date_logic(inp: BuilderInput) -> BuilderResult:
+    """DateLogic: refs {table_id, column_id}，params 全量透传（filter_kwargs_for_class 兜底）。"""
+    kwargs, error = resolve_single_column(inp)
+    if error:
+        return {}, error
+    # 将 params 中的所有参数添加到 kwargs，filter_kwargs_for_class 会过滤不需要的
+    kwargs.update(inp.params)
+    return kwargs, None
+
+
+@register_builder("Range")
+def build_range(inp: BuilderInput) -> BuilderResult:
+    """Range: refs {table_id, column_id}，params {min→min_value, max→max_value, boundary_mode}。"""
+    kwargs, error = resolve_single_column(inp)
+    if error:
+        return {}, error
+    params = inp.params
+    # min -> min_value, max -> max_value 的字段重命名
+    if "min" in params:
+        kwargs["min_value"] = params["min"]
+    if "max" in params:
+        kwargs["max_value"] = params["max"]
+    if "boundary_mode" in params:
+        kwargs["boundary_mode"] = params["boundary_mode"]
+    return kwargs, None
+
+
+@register_builder("Charset")
+def build_charset(inp: BuilderInput) -> BuilderResult:
+    """Charset: refs {table_id, column_id}，params {charset_mode}。
+
+    修复：此前 factory.py 无 Charset 独立分支，走通用路径导致无 table/column 的残缺实例。
+    """
+    kwargs, error = resolve_single_column(inp)
+    if error:
+        return {}, error
+    # charset_mode 默认 "ascii"（与 CharsetConstraint.__init__ 默认值一致）
+    kwargs["charset_mode"] = inp.params.get("charset_mode", "ascii")
+    return kwargs, None

app/shared/core/project/constraint/builders/unique.py

@@ -0,0 +1,53 @@
+# 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 Unique 约束构建器
+
+Unique 的 column 支持 list 语义（多列联合唯一），与其他单列约束不同，需独立构建器。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import BuilderInput, BuilderResult
+from .registry import register_builder
+
+
+@register_builder("Unique")
+def build_unique(inp: BuilderInput) -> BuilderResult:
+    """Unique: refs {table_id, column_ids | column_id}。
+
+    column_ids 支持列表（多列）或字符串（单列兼容）。
+    """
+    refs = inp.refs
+    table_id = refs.get("table_id")
+    col_id = refs.get("column_ids") or refs.get("column_id")
+    if not isinstance(table_id, str):
+        return {}, "缺少 table_id"
+    # 确保 col_id 是列表
+    if isinstance(col_id, str):
+        col_id = [col_id]
+    elif not col_id:
+        col_id = []
+
+    kwargs: dict[str, Any] = {"table": table_id}
+    # 映射 column_ids -> column_names
+    mapped_cols = [inp.column_name_by_table_id.get(table_id, {}).get(str(cid)) for cid in col_id]
+    if None in mapped_cols:
+        invalid_cols = [cid for cid, name in zip(col_id, mapped_cols) if name is None]
+        return {}, f"引用的列不存在: {invalid_cols}"
+    kwargs["column"] = mapped_cols
+    return kwargs, None