precis-cli 0.1.3__py3-none-any.whl

app/shared/services/preview/path_validation.py

@@ -0,0 +1,138 @@
+# 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 文件路径安全校验
+
+功能概述:
+- 提供统一的文件路径安全校验工具，供所有涉及文件系统操作的 HTTP 端点使用
+- 两层校验策略:
+  1. assert_no_traversal: 反穿越校验（拒绝 `..` 相对成分 + resolve 解析 symlink），
+     适用于用户在项目外选择的数据文件场景（preview/validation/files-ops），保留任意数据文件能力
+  2. assert_path_within_root: 限定到指定根目录（白名单语义），
+     适用于临时文件（TEMP_DIR）、校验历史（configPath）等有明确归属的场景
+
+设计原则:
+- 只做必要的防御:拒绝 `..` 穿越和 resolve 符号链接。不做系统目录黑名单之类的
+  额外层——应用层重复 OS 权限边界既不完整(挡不住 ~/.ssh)又增加误伤与维护负担。
+- 校验失败统一抛 HTTPException（403 拒绝 / 400 参数错误 / 404 不存在）
+- 基于 Path.resolve() 解析符号链接与 `..`，避免 abspath+normpath 无法防 symlink 的缺陷
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fastapi import HTTPException
+
+
+def assert_no_traversal(file_path: str, *, must_exist: bool = True) -> str:
+    """
+    @methoddesc 反穿越校验，不限根目录
+
+    适用于用户在项目外选择的数据文件场景（preview/validation/files-ops）。
+    保留访问任意合法数据文件的能力，仅阻止路径穿越（`..` 相对成分）。
+
+    参数:
+        file_path: 待校验的文件路径（原始字符串）
+        must_exist: 是否要求文件必须存在（默认 True）
+
+    返回:
+        解析后的绝对路径字符串
+
+    抛出:
+        HTTPException: 400 路径为空/含穿越成分; 404 文件不存在
+    """
+    if not file_path or not file_path.strip():
+        raise HTTPException(status_code=400, detail="文件路径不能为空")
+
+    raw = file_path.strip()
+
+    # 拒绝显式 `..` 段：数据文件访问场景不应需要 `..`，用户应直接提供目标文件绝对路径
+    path_obj = Path(raw)
+    if any(part == ".." for part in path_obj.parts):
+        raise HTTPException(
+            status_code=400,
+            detail="路径包含 `..` 相对穿越成分，请提供目标文件的绝对路径。",
+        )
+
+    # resolve() 解析符号链接与剩余相对成分，得到真实绝对路径
+    try:
+        resolved = path_obj.resolve()
+    except OSError as e:
+        raise HTTPException(status_code=400, detail=f"路径解析失败: {e}")
+
+    if must_exist and not resolved.exists():
+        raise HTTPException(status_code=404, detail=f"文件未找到: {file_path}")
+
+    return str(resolved)
+
+
+def assert_path_within_root(file_path: str, root: str, *, must_exist: bool = True) -> str:
+    """
+    @methoddesc 限定路径必须落在指定根目录内（白名单语义）
+
+    适用于临时文件（TEMP_DIR）、校验历史（configPath）等有明确归属的场景。
+    基于 resolve() 解析后做包含关系检查，能正确处理符号链接。
+
+    参数:
+        file_path: 待校验的文件路径（原始字符串）
+        root: 允许的根目录绝对路径
+        must_exist: 是否要求文件必须存在（默认 True）
+
+    返回:
+        解析后的绝对路径字符串
+
+    抛出:
+        HTTPException: 400 路径为空; 403 越出根目录; 404 不存在
+    """
+    if not file_path or not file_path.strip():
+        raise HTTPException(status_code=400, detail="文件路径不能为空")
+
+    raw = file_path.strip()
+    try:
+        resolved = Path(raw).resolve()
+    except OSError as e:
+        raise HTTPException(status_code=400, detail=f"路径解析失败: {e}")
+
+    try:
+        root_resolved = Path(root).resolve()
+    except OSError as e:
+        raise HTTPException(status_code=500, detail=f"根目录解析失败: {e}")
+
+    root_str = str(root_resolved)
+    resolved_str = str(resolved)
+    # 包含关系：resolved == root 或 resolved 在 root 之下
+    if resolved_str != root_str and not resolved_str.startswith(root_str + os.sep):
+        raise HTTPException(status_code=403, detail="路径越出允许的根目录范围。")
+
+    if must_exist and not resolved.exists():
+        raise HTTPException(status_code=404, detail=f"文件未找到: {file_path}")
+
+    return resolved_str
+
+
+def validate_file_access(file_path: str) -> str:
+    """
+    @methoddesc 文件路径可访问性校验（反穿越硬化版）
+
+    兼容历史调用点（preview/content_mode、path_mode、validation 等），
+    内部委托给 assert_no_traversal。返回解析后的绝对路径供调用方使用。
+
+    抛出:
+        HTTPException: 400 路径为空/含 `..` 穿越成分/解析失败; 404 文件不存在
+        （本函数不做根目录限定，不会抛 403；403 仅由 assert_path_within_root 抛出）
+    """
+    return assert_no_traversal(file_path, must_exist=True)

app/shared/services/project_loader.py

@@ -0,0 +1,57 @@
+# 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 项目加载服务辅助模块
+
+功能概述:
+- 负责将 core 层加载的配置文件对象转换为 domain 层运行时数据集 Schema
+- 作为 core 层与 domain 层之间的转换桥梁，避免 core 层反向依赖 domain
+
+架构设计:
+- 转换层: core (TableSchemaFile / ConstraintFile) -> domain (DataSetSchema)
+- 由 core.project.loader 的主加载流程调用
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.shared.core.project.constraint.factory import create_constraints
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.domain import DataSetSchema
+
+from .schema_runtime_builder import build_runtime_schemas
+
+
+def build_dataset_schema(
+    schema_files: dict[str, TableSchemaFile],
+    constraint_files: dict[str, Any],
+    registries: dict[str, Any],
+) -> tuple[DataSetSchema, list[str]]:
+    """@methoddesc 构建 domain 层的 DataSetSchema 运行时对象。
+
+    将 core 层加载的 TableSchemaFile 和 ConstraintFile 转换为 domain 层的
+    TableSchema 列表和约束实例，最终组装为 DataSetSchema。
+
+    :param schema_files: schema 配置文件字典（table_id -> TableSchemaFile）
+    :param constraint_files: constraint 配置文件字典（constraint_id -> ConstraintFile）
+    :param registries: 表达式注册表等辅助对象
+    :return: (DataSetSchema, 约束构建过程中的警告列表)
+    """
+    runtime_tables = build_runtime_schemas(schema_files, registries)
+    runtime_constraints, warnings = create_constraints(constraint_files, schema_files)
+    dataset_schema = DataSetSchema(tables=runtime_tables, constraints=runtime_constraints)
+    return dataset_schema, warnings

app/shared/services/schema_inference.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 数据文件 → Schema YAML 推断服务（headless infer_schema）
+
+功能概述:
+- 读取 CSV/Excel/JSON 数据文件的头部样本，推断每列的 V2 数据类型
+- 产出可直接落盘的 schema 文件内容（dict 形式，YAML 序列化由调用方决定）
+- 供 CLI 子命令 `precis infer-schema` 与 MCP tool `infer_schema` 复用
+
+推断规则（按列，忽略空值）:
+- 全部可解析为整数 → integer
+- 全部可解析为有限浮点（含整数）→ float
+- 全部为 true/false 字面量 → boolean
+- 全部为 ISO 日期（YYYY-MM-DD）→ date
+- 其余（含混合类型、全空列）→ string
+
+设计说明:
+- CSV/Excel 以 dtype=str 读入，避免 pandas 预转换掩盖原始格式
+  （"1.0" 与 "1" 的区别、日期字符串等）；JSON 值为原生类型，
+  分类器同时接受 str 与原生标量
+- 只采样头部（默认 1000 行）控制大文件成本；类型冲突按保守回退 string
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import uuid
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+# V2 支持的 6 种数据类型（与 backend schema 类型定义一致）
+DATA_TYPES = ("string", "integer", "float", "decimal", "boolean", "date")
+
+# 支持的输入扩展名
+_CSV_EXTS = {".csv"}
+_EXCEL_EXTS = {".xlsx", ".xls"}
+_JSON_EXTS = {".json", ".jsonl"}
+
+# boolean 字面量集合（大小写不敏感）
+_BOOL_LITERALS = {"true", "false"}
+
+# 默认采样行数
+DEFAULT_SAMPLE_ROWS = 1000
+
+
+def _classify_value(value: Any) -> str | None:
+    """对单个非空值做候选类型判定。
+
+    Args:
+        value: 单元格值（str 或 JSON 原生标量）
+
+    Returns:
+        候选类型（string/integer/float/boolean/date）；无法判定返回 string
+    """
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        # 非有限浮点（NaN/Inf）不能作为类型证据
+        return "float" if math.isfinite(value) else "string"
+
+    text = str(value).strip()
+    if not text:
+        return None
+    if text.lower() in _BOOL_LITERALS:
+        return "boolean"
+    # 整数：可选符号的纯数字
+    if _is_int_text(text):
+        return "integer"
+    # 浮点：排除 nan/inf 等非有限字面量
+    try:
+        parsed = float(text)
+        if math.isfinite(parsed):
+            return "float"
+    except ValueError:
+        pass
+    # 日期：严格 ISO 格式（YYYY-MM-DD）
+    try:
+        date.fromisoformat(text)
+        return "date"
+    except ValueError:
+        pass
+    return "string"
+
+
+def _is_int_text(text: str) -> bool:
+    """判断字符串是否为整数文本（允许前后符号）。"""
+    body = text[1:] if text[:1] in "+-" else text
+    return body.isdigit() and len(body) > 0
+
+
+def infer_column_type(values: list[Any], dominant_ratio: float = 0.9) -> str:
+    """对一列采样值推断 V2 类型。
+
+    规则：
+    1. 全部非空值同属一类 → 该类型（integer/float 合并时 float 优先提升）
+    2. 否则若单一数值/日期/布尔候选占比 >= dominant_ratio → 采信该候选
+       （数据中的少量脏值正是校验要抓的问题，不应把整列拖回 string）
+    3. 其余（含混合类型、全空列）→ string
+
+    Args:
+        values: 该列的非空采样值列表
+        dominant_ratio: 主导类型采信阈值（占非空值的比例）
+
+    Returns:
+        6 种 V2 类型之一；空列表（全空列）返回 string（安全默认）
+    """
+    counts: dict[str, int] = {}
+    total = 0
+    for value in values:
+        candidate = _classify_value(value)
+        if candidate is None:
+            continue
+        total += 1
+        counts[candidate] = counts.get(candidate, 0) + 1
+    if total == 0:
+        return "string"
+
+    def _ratio(kind: str) -> float:
+        return counts.get(kind, 0) / total
+
+    # 数值合并视角：integer 与 float 同属数值，浮点出现则整列提升 float
+    numeric_count = counts.get("integer", 0) + counts.get("float", 0)
+    if numeric_count == total:
+        return "float" if counts.get("float") else "integer"
+    if _ratio("boolean") == 1.0:
+        return "boolean"
+    if _ratio("date") == 1.0:
+        return "date"
+
+    # 主导采信：少量脏值不拖垮整列（如 17 行里 1 个非法日期）
+    if numeric_count >= dominant_ratio * total:
+        return "float" if counts.get("float") else "integer"
+    for kind in ("boolean", "date"):
+        if _ratio(kind) >= dominant_ratio:
+            return kind
+    return "string"
+
+
+def _read_head(data_file: Path, sample_rows: int) -> pd.DataFrame:
+    """按扩展名读取数据文件头部样本。
+
+    CSV/Excel 以 dtype=str 读入保留原始格式；JSON 解析原生类型。
+    JSONL（.jsonl / 逐行 JSON 对象）按行解析。
+
+    Args:
+        data_file: 数据文件路径
+        sample_rows: 采样行数上限
+
+    Returns:
+        采样 DataFrame（空数据返回空 DataFrame）
+
+    Raises:
+        ValueError: 文件不存在或不支持的扩展名
+    """
+    if not data_file.exists():
+        raise ValueError(f"数据文件不存在: {data_file}")
+
+    suffix = data_file.suffix.lower()
+    try:
+        if suffix in _CSV_EXTS:
+            return pd.read_csv(data_file, dtype=str, nrows=sample_rows, keep_default_na=True)
+        if suffix in _EXCEL_EXTS:
+            # Excel 不支持按行采样，整体读入后取头部（大文件场景后续再优化）
+            df = pd.read_excel(data_file, dtype=str)
+            return df.head(sample_rows)
+        if suffix in _JSON_EXTS:
+            return _read_json_head(data_file, sample_rows)
+    except pd.errors.EmptyDataError as e:
+        raise ValueError(f"数据文件无表头或无数据行，无法推断 schema: {data_file}") from e
+    raise ValueError(f"不支持的文件扩展名: {suffix}（支持 CSV/Excel/JSON）")
+
+
+def _read_json_head(data_file: Path, sample_rows: int) -> pd.DataFrame:
+    """读取 JSON（对象数组）或 JSONL（逐行对象）头部样本。"""
+    text = data_file.read_text(encoding="utf-8")
+    if data_file.suffix.lower() == ".jsonl":
+        records = []
+        for line in text.splitlines():
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+        return pd.DataFrame(records).head(sample_rows)
+    data = json.loads(text)
+    if isinstance(data, dict):
+        data = [data]
+    if not isinstance(data, list):
+        raise ValueError(f"JSON 顶层必须是对象数组: {data_file}")
+    return pd.DataFrame(data).head(sample_rows)
+
+
+def infer_schema(
+    data_file: str | Path,
+    sample_rows: int = DEFAULT_SAMPLE_ROWS,
+    table_id: str | None = None,
+    table_name: str | None = None,
+    source_path: str | None = None,
+) -> dict[str, Any]:
+    """推断数据文件的 V2 schema 结构。
+
+    Args:
+        data_file: 数据文件路径
+        sample_rows: 类型推断的采样行数上限
+        table_id: 表 ID（默认生成 UUID v4；替换既有 schema 时传入原 id 保持引用不变）
+        table_name: 表显示名（默认取文件名去扩展名）
+        source_path: 写入 schema 的 source.path（默认为 data_file 原样路径）
+
+    Returns:
+        schema 文件结构的字典（version/id/name/source/columns），
+        经 yaml.safe_dump 即可落盘为合法 *.schema.yaml
+
+    Raises:
+        ValueError: 文件不存在、扩展名不支持或无任何列可推断
+    """
+    path = Path(data_file)
+    df = _read_head(path, sample_rows)
+
+    if df.empty or len(df.columns) == 0:
+        raise ValueError(f"数据文件无表头或无数据行，无法推断 schema: {data_file}")
+
+    columns: list[dict[str, Any]] = []
+    for col in df.columns:
+        # 逐列收集非空采样值后推断类型
+        non_null = [v for v in df[col].tolist() if v is not None and not (isinstance(v, float) and math.isnan(v))]
+        columns.append(
+            {
+                "id": str(col),
+                "name": str(col),
+                "type": infer_column_type(non_null),
+            }
+        )
+
+    return {
+        "version": 2,
+        "id": table_id or str(uuid.uuid4()),
+        "name": table_name or path.stem,
+        "source": {
+            "mode": "relative_file",
+            "path": source_path if source_path is not None else str(data_file),
+        },
+        "columns": columns,
+    }

app/shared/services/schema_runtime_builder.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 Schema 运行时对象构建服务
+
+功能概述:
+- 将 core 层的 TableSchemaFile 配置转换为 domain 层的运行时 TableSchema 对象
+- 负责 core DTO 与 domain model 之间的转换，避免 core 层直接依赖 domain
+
+架构设计:
+- 转换层: config (TableSchemaFile) -> domain (TableSchema/ColumnSchema)
+- 依赖 domain 的 build_type_from_config 解析列类型
+- 由 services 层（如 project_loader、validation）调用
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.domain import ColumnSchema, TableSchema, build_type_from_config
+
+
+def build_runtime_schema(schema_file: TableSchemaFile, registries: dict[str, Any]) -> TableSchema:
+    """@methoddesc 从 TableSchemaFile 构建运行时 TableSchema 对象。
+
+    本函数位于 services 层，负责将 core 层的配置文件对象转换为 domain 层运行时对象，
+    从而消除 core.project.schema.reader 对 domain 的反向依赖。
+
+    :param schema_file: TableSchemaFile 配置对象
+    :param registries: 包含 expression_registry 的字典
+    :return: 运行时 TableSchema 对象
+    """
+    columns: list[ColumnSchema] = []
+    for col in schema_file.columns:
+        data_type = build_type_from_config(col.type, registries)
+        col_schema = ColumnSchema(
+            name=col.name,
+            data_type=data_type,
+            is_primary_key=col.primary_key,
+            expand=col.expand,
+            nullable=col.nullable,
+            id=col.id,
+            json_path=col.json_path,
+        )
+        if col.children:
+            child_columns = []
+            for child in col.children:
+                child_data_type = build_type_from_config(child.type, registries)
+                child_columns.append(
+                    ColumnSchema(
+                        name=child.name,
+                        data_type=child_data_type,
+                        is_primary_key=child.primary_key,
+                        expand=child.expand,
+                        nullable=child.nullable,
+                        id=child.id,
+                        json_path=child.json_path,
+                    )
+                )
+            col_schema.children = child_columns
+        columns.append(col_schema)
+
+    # 提取数据源信息
+    source_file = None
+    sheet_name = None
+    header_row = 0
+    source_config: dict[str, Any] = {}
+    if schema_file.source:
+        source_file = schema_file.source.path
+        sheet_name = schema_file.source.sheet
+        header_row = schema_file.source.header_row
+        # 保存完整的 source 配置，用于数据加载
+        source_config = schema_file.source.to_loader_config()
+    elif schema_file.sheet:
+        # 向后兼容：无 source 时回退到顶层 sheet 字段
+        # （source.sheet 与顶层 sheet 互斥，但单独的顶层 sheet 是合法配置）
+        sheet_name = schema_file.sheet
+
+    # 构建运行时 TableSchema 对象
+    return TableSchema(
+        id=schema_file.id,
+        name=schema_file.name,
+        columns=columns,
+        source_file=source_file,
+        sheet_name=sheet_name,
+        header_row=header_row,
+        script_checks=schema_file.script_checks,
+        source_config=source_config,
+    )
+
+
+def build_runtime_schemas(
+    schema_files: dict[str, TableSchemaFile],
+    registries: dict[str, Any],
+) -> dict[str, TableSchema]:
+    """@methoddesc 批量构建运行时 TableSchema 对象。
+
+    :param schema_files: schema 文件字典（table_id -> TableSchemaFile）
+    :param registries: 表达式注册表
+    :return: 运行时 TableSchema 字典（table_id -> TableSchema）
+    """
+    tables: dict[str, TableSchema] = {}
+    for table_id, schema in schema_files.items():
+        # 使用 table_id 作为键，与新的文件命名规则保持一致
+        tables[table_id] = build_runtime_schema(schema, registries)
+    return tables

app/shared/services/validation/__init__.py

@@ -0,0 +1,52 @@
+# 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 校验服务模块入口
+
+功能概述:
+- 统一导出校验服务相关的类型、服务和校验器
+- 提供 ValidationType、ValidationResult 等核心类型
+- 提供 UnifiedValidationService 统一校验服务
+- 提供文件加载便捷函数
+"""
+
+from .chunked_loader import ChunkedDataLoader, ChunkedValidationResult
+from .loader import load_file_data
+from .memory_monitor import MemoryMonitor
+from .service import UnifiedValidationService
+from .types import ValidationResult, ValidationType
+from .validators import (
+    BaseValidator,
+    CompositeValidator,
+    ConstraintAdapter,
+    DateLogicValidator,
+    PreCheck,
+)
+
+__all__ = [
+    "ValidationType",
+    "ValidationResult",
+    "UnifiedValidationService",
+    "load_file_data",
+    "BaseValidator",
+    "ConstraintAdapter",
+    "PreCheck",
+    "CompositeValidator",
+    "DateLogicValidator",
+    "MemoryMonitor",
+    "ChunkedDataLoader",
+    "ChunkedValidationResult",
+]