precis-cli 0.1.3__tar.gz

precis_cli-0.1.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include pyproject.toml
+recursive-include app *.yaml

precis_cli-0.1.3/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: precis-cli
+Version: 0.1.3
+Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
+Author: Precis Team
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AirSaiga/Precis
+Project-URL: Repository, https://github.com/AirSaiga/Precis
+Project-URL: Bug Tracker, https://github.com/AirSaiga/Precis/issues
+Project-URL: Discussions, https://github.com/AirSaiga/Precis/discussions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pandas<3.0,>=2.2.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: xlrd>=2.0.1
+Requires-Dist: SQLAlchemy>=2.0.48
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: ruamel.yaml>=0.19.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: readchar>=4.2.0
+Requires-Dist: cryptography>=44.0.0
+Requires-Dist: simpleeval>=1.0.0
+Requires-Dist: filelock>=3.12.0
+Provides-Extra: api
+Requires-Dist: fastapi!=0.136.3,>=0.135.0; extra == "api"
+Requires-Dist: uvicorn>=0.42.0; extra == "api"
+Requires-Dist: email-validator>=2.3.0; extra == "api"
+Requires-Dist: uritemplate>=4.2.0; extra == "api"
+Requires-Dist: python-multipart>=0.0.26; extra == "api"
+Requires-Dist: cryptography>=44.0.0; extra == "api"
+Provides-Extra: ai
+Requires-Dist: openai>=1.6.0; extra == "ai"
+Requires-Dist: aiohttp>=3.9.0; extra == "ai"
+Requires-Dist: psutil>=5.9.6; extra == "ai"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30.0; extra == "mcp"
+Provides-Extra: completion
+Requires-Dist: pyreadline3>=0.1.8; sys_platform == "win32" and extra == "completion"
+Provides-Extra: full
+Requires-Dist: precis-cli[ai,api,completion,mcp]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: precis-cli[ai,api,mcp]; extra == "dev"
+Requires-Dist: debugpy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# Precis 后端 / Precis Backend
+
+> **Alpha** — 核心功能已成型，接口可能调整。
+
+FastAPI + CLI + 核心校验引擎，采用三层分离架构。
+
+完整项目说明请见 [根目录 README.md](../README.md)。
+
+---
+
+## 架构
+
+```
+backend/app/
+├── api/                    # API 层
+│   ├── main.py             # FastAPI 应用入口（路由注册、中间件、CORS）
+│   ├── dependencies.py     # 依赖注入
+│   ├── middleware/          # 中间件
+│   ├── models/             # 请求/响应 Pydantic 模型
+│   ├── routers/            # 路由定义
+│   │   ├── core/           # 核心路由（项目、工作区）
+│   │   ├── project/        # V2 项目 CRUD（Schema、Constraint、Regex、Transform）
+│   │   ├── validation/     # 校验执行与历史
+│   │   ├── preview/        # 数据预览
+│   │   └── ai/             # AI 配置生成
+│   └── services/           # API 层服务
+├── cli/                    # 交互式命令行（shell/ REPL、start 启动器、__main__）
+├── shared/                 # 三层分离架构
+│   ├── core/               # 框架级基础设施
+│   │                       # 文件 I/O、配置解析（YAML）、数据加载
+│   ├── domain/             # 纯业务领域逻辑（无 I/O 依赖）
+│   │   ├── constraints/    # 10 种约束类型定义（not_null.py、unique.py 等，每种一个文件）
+│   │   ├── transforms/     # 22 种转换类型定义（string_split.py、math_expr.py 等，每种一个文件）
+│   │   ├── data_types.py   # 数据类型定义（string/integer/float/decimal/boolean/date）
+│   │   ├── dataset_schema.py # Schema 模型
+│   │   ├── expression_system.py # 表达式求值系统
+│   │   └── schema/         # Schema 相关领域逻辑
+│   └── services/           # 应用服务（编排 core 和 domain）
+│       ├── validation/     # 校验引擎（两阶段流水线）
+│       │   ├── executor.py # ValidationExecutor 主编排器
+│       │   ├── engine.py   # 校验执行引擎
+│       │   ├── data_loader.py # 数据加载
+│       │   ├── loader.py   # 配置加载
+│       │   ├── resolver.py # 数据源解析
+│       │   ├── extractors.py # 派生列提取（regex）
+│       │   ├── history.py  # 校验历史持久化
+│       │   ├── dag/        # 转换 DAG 执行
+│       │   ├── validators/ # 各类型校验器（每种约束一个文件）
+│       │   └── types.py    # 校验类型定义
+│       ├── ai/             # AI 服务
+│       ├── llm/            # LLM 集成（OpenAI / Ollama）
+│       ├── preview/        # 数据预览服务
+│       ├── diff/           # 配置差异比较
+│       └── hardware.py     # 硬件检测
+└── start_server.py         # 服务器启动入口
+```
+
+### 关键约定
+
+- `domain/` 不得导入 `core/` 或 `services/`，保持纯净
+- API 路由在 `api/routers/`，请求/响应模型在 `api/models/`
+- 路由注册入口：`api/main.py`
+- 所有请求通过 `X-Project-Config-Path` header 标识当前项目
+- 校验类接口约定"永远返回 200、结果看 body"；配置文件损坏（如清单 YAML 语法错误/空文件）返回 422 并附说明
+- 打包模式下 `Origin: null` 跨域请求须携带 `X-Precis-Auth` 头（值来自 Electron 注入的 `PRECIS_API_TOKEN`，见 `api/middleware/token_auth.py`）；未配置 token 时中间件直通，`PRECIS_ALLOW_NULL_ORIGIN=1` 为旧的全局放行兼容开关
+
+---
+
+## 校验引擎（两阶段流水线）
+
+```
+阶段 1: 数据加载与预处理
+  ├── DataSourceResolver → 解析文件路径
+  ├── DataLoader → 加载 Excel/CSV/JSON
+  ├── process_dataframe → 类型转换、格式检查
+  ├── extractors → 派生列提取（regex）
+  └── Transform DAG → 拓扑排序执行 transform 链
+
+阶段 2: 约束校验
+  └── 逐约束调用 validate()，聚合错误
+        （validators/ 下每种类型一个：not_null.py, unique.py, foreign_key.py ...）
+```
+
+---
+
+## 开发命令
+
+```bash
+# 安装
+python -m venv .venv
+pip install -e ".[dev]"
+
+# 运行
+python -m uvicorn app.api.main:app --reload --port 18000
+
+# 代码检查
+python -m ruff check .              # lint（不自动修复）
+python -m ruff check --fix .        # lint 自动修复
+python -m ruff format .             # 格式化
+python -m mypy .                    # 类型检查
+
+# 测试
+python -m pytest                    # 运行全部测试
+
+# CLI
+python -B -m app.cli
+```
+
+---
+
+## 配置文件格式（V2 YAML）
+
+| 文件类型 | 命名 | 说明 |
+|---------|------|------|
+| 项目清单 | `project.precis.yaml` | 索引所有 Schema/Constraint/Regex/Transform 资源 |
+| Schema | `*.schema.yaml` | 表结构定义（列、数据类型、内嵌约束） |
+| Constraint | `*.constraint.yaml` | 独立约束（refs + params 分离设计） |
+| Regex | `*.regex.yaml` | 正则节点（引用模式或直接模式） |

precis_cli-0.1.3/README.md

@@ -0,0 +1,118 @@
+# Precis 后端 / Precis Backend
+
+> **Alpha** — 核心功能已成型，接口可能调整。
+
+FastAPI + CLI + 核心校验引擎，采用三层分离架构。
+
+完整项目说明请见 [根目录 README.md](../README.md)。
+
+---
+
+## 架构
+
+```
+backend/app/
+├── api/                    # API 层
+│   ├── main.py             # FastAPI 应用入口（路由注册、中间件、CORS）
+│   ├── dependencies.py     # 依赖注入
+│   ├── middleware/          # 中间件
+│   ├── models/             # 请求/响应 Pydantic 模型
+│   ├── routers/            # 路由定义
+│   │   ├── core/           # 核心路由（项目、工作区）
+│   │   ├── project/        # V2 项目 CRUD（Schema、Constraint、Regex、Transform）
+│   │   ├── validation/     # 校验执行与历史
+│   │   ├── preview/        # 数据预览
+│   │   └── ai/             # AI 配置生成
+│   └── services/           # API 层服务
+├── cli/                    # 交互式命令行（shell/ REPL、start 启动器、__main__）
+├── shared/                 # 三层分离架构
+│   ├── core/               # 框架级基础设施
+│   │                       # 文件 I/O、配置解析（YAML）、数据加载
+│   ├── domain/             # 纯业务领域逻辑（无 I/O 依赖）
+│   │   ├── constraints/    # 10 种约束类型定义（not_null.py、unique.py 等，每种一个文件）
+│   │   ├── transforms/     # 22 种转换类型定义（string_split.py、math_expr.py 等，每种一个文件）
+│   │   ├── data_types.py   # 数据类型定义（string/integer/float/decimal/boolean/date）
+│   │   ├── dataset_schema.py # Schema 模型
+│   │   ├── expression_system.py # 表达式求值系统
+│   │   └── schema/         # Schema 相关领域逻辑
+│   └── services/           # 应用服务（编排 core 和 domain）
+│       ├── validation/     # 校验引擎（两阶段流水线）
+│       │   ├── executor.py # ValidationExecutor 主编排器
+│       │   ├── engine.py   # 校验执行引擎
+│       │   ├── data_loader.py # 数据加载
+│       │   ├── loader.py   # 配置加载
+│       │   ├── resolver.py # 数据源解析
+│       │   ├── extractors.py # 派生列提取（regex）
+│       │   ├── history.py  # 校验历史持久化
+│       │   ├── dag/        # 转换 DAG 执行
+│       │   ├── validators/ # 各类型校验器（每种约束一个文件）
+│       │   └── types.py    # 校验类型定义
+│       ├── ai/             # AI 服务
+│       ├── llm/            # LLM 集成（OpenAI / Ollama）
+│       ├── preview/        # 数据预览服务
+│       ├── diff/           # 配置差异比较
+│       └── hardware.py     # 硬件检测
+└── start_server.py         # 服务器启动入口
+```
+
+### 关键约定
+
+- `domain/` 不得导入 `core/` 或 `services/`，保持纯净
+- API 路由在 `api/routers/`，请求/响应模型在 `api/models/`
+- 路由注册入口：`api/main.py`
+- 所有请求通过 `X-Project-Config-Path` header 标识当前项目
+- 校验类接口约定"永远返回 200、结果看 body"；配置文件损坏（如清单 YAML 语法错误/空文件）返回 422 并附说明
+- 打包模式下 `Origin: null` 跨域请求须携带 `X-Precis-Auth` 头（值来自 Electron 注入的 `PRECIS_API_TOKEN`，见 `api/middleware/token_auth.py`）；未配置 token 时中间件直通，`PRECIS_ALLOW_NULL_ORIGIN=1` 为旧的全局放行兼容开关
+
+---
+
+## 校验引擎（两阶段流水线）
+
+```
+阶段 1: 数据加载与预处理
+  ├── DataSourceResolver → 解析文件路径
+  ├── DataLoader → 加载 Excel/CSV/JSON
+  ├── process_dataframe → 类型转换、格式检查
+  ├── extractors → 派生列提取（regex）
+  └── Transform DAG → 拓扑排序执行 transform 链
+
+阶段 2: 约束校验
+  └── 逐约束调用 validate()，聚合错误
+        （validators/ 下每种类型一个：not_null.py, unique.py, foreign_key.py ...）
+```
+
+---
+
+## 开发命令
+
+```bash
+# 安装
+python -m venv .venv
+pip install -e ".[dev]"
+
+# 运行
+python -m uvicorn app.api.main:app --reload --port 18000
+
+# 代码检查
+python -m ruff check .              # lint（不自动修复）
+python -m ruff check --fix .        # lint 自动修复
+python -m ruff format .             # 格式化
+python -m mypy .                    # 类型检查
+
+# 测试
+python -m pytest                    # 运行全部测试
+
+# CLI
+python -B -m app.cli
+```
+
+---
+
+## 配置文件格式（V2 YAML）
+
+| 文件类型 | 命名 | 说明 |
+|---------|------|------|
+| 项目清单 | `project.precis.yaml` | 索引所有 Schema/Constraint/Regex/Transform 资源 |
+| Schema | `*.schema.yaml` | 表结构定义（列、数据类型、内嵌约束） |
+| Constraint | `*.constraint.yaml` | 独立约束（refs + params 分离设计） |
+| Regex | `*.regex.yaml` | 正则节点（引用模式或直接模式） |

precis_cli-0.1.3/app/__init__.py

@@ -0,0 +1,16 @@
+# 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 Precis 后端应用包入口"""

precis_cli-0.1.3/app/api/__init__.py

@@ -0,0 +1,32 @@
+# 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 API 模块包入口
+
+功能概述:
+- 标记 backend/app/api 目录为 Python 包
+- 作为 API 层的统一入口，供外部导入使用
+
+架构设计:
+- 该包包含 FastAPI 应用、依赖注入、中间件、数据模型和路由等子模块
+- 通过 __init__.py 暴露公共接口，简化外部导入路径
+
+输入示例:
+    from app.api import main
+
+输出示例:
+    无直接输出，仅作为包标记
+"""

precis_cli-0.1.3/app/api/dependencies.py

@@ -0,0 +1,185 @@
+# 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 API 依赖注入模块
+
+功能概述:
+- 提供 FastAPI 依赖注入函数
+- 从 HTTP Header 获取并验证项目配置路径
+- 提供 ProjectStore 数据容器在请求生命周期内传递项目路径
+
+架构设计:
+- 使用 FastAPI 的 Depends 机制实现依赖注入
+- 通过 X-Project-Config-Path Header 接收项目路径，支持多项目
+- 路径验证包括绝对路径检查和目录存在性检查
+- ProjectStore 可轻松 mock，便于单元测试
+
+输入示例:
+    Header: X-Project-Config-Path: D:/project （项目根，须含 project.precis.yaml）
+
+输出示例:
+    ProjectStore(project_path="D:/project")
+"""
+
+# backend/app/api/dependencies.py
+import os
+
+from fastapi import Depends, Header, HTTPException
+
+
+class ProjectStore:
+    """
+    项目存储类。
+
+    这是一个简单的数据容器类，用于在 FastAPI 依赖注入链中传递项目路径信息。
+    通过将项目路径封装为对象，可以在类型提示中明确表达依赖关系。
+
+    设计目的：
+    - 提供类型安全的项目路径传递方式
+    - 方便在路由处理器中获取项目根目录
+    - 支持依赖注入的单元测试（可轻松 mock）
+
+    属性：
+        project_path: 项目配置目录的绝对路径
+    """
+
+    def __init__(self, project_path: str):
+        """
+        初始化项目存储对象。
+
+        :param project_path: 项目配置目录的绝对路径
+        """
+        self.project_path = project_path
+
+
+async def get_project_config_path(
+    x_project_config_path: str = Header(..., description="项目根目录的绝对路径（须含 project.precis.yaml）"),
+) -> str:
+    """
+    获取并验证项目配置路径的依赖函数。
+
+    该函数是 FastAPI 的依赖项，用于从 HTTP Header 中提取项目配置路径，
+    并进行合法性验证：
+    1. 检查路径是否为绝对路径
+    2. 检查路径对应的目录是否存在
+    3. 必须含 project.precis.yaml（合法 Precis 项目根标识）
+
+    B-sec3 安全加固: 原校验仅"绝对+是目录"，任意目录都能当项目根，导致后续
+    manifest/数据源/AI 配置写入可能落到任意目录。现对齐 AI 路由的
+    validate_project_path，要求 manifest 存在。项目首次创建走独立的
+    /projects/create 端点（不经此依赖），故不影响创建流程。
+
+    处理流程：
+    1. 从 X-Project-Config-Path Header 获取路径
+    2. 委托 _validate_project_root 做完整校验（绝对路径/拒绝 `..`/目录存在/manifest 存在）
+    3. 返回验证后的绝对路径
+
+    :param x_project_config_path: HTTP Header 中的项目配置路径
+    :return: 验证通过的项目配置绝对路径
+    :raises HTTPException: 路径验证失败时返回 400 或 404 错误
+
+    Header 示例（项目根目录语义，不是 .precis/ 子目录）：
+        X-Project-Config-Path: /path/to/project
+    """
+    return _validate_project_root(x_project_config_path)
+
+
+def _validate_project_root(raw_path: str | None) -> str:
+    """校验路径是否为合法 Precis 项目根（单一事实源）。
+
+    B-sec3: 统一 get_project_config_path 与 ai/utils.validate_project_path 的校验逻辑，
+    消除双套不一致（原 ai 路径要求 manifest，通用依赖不要求，弱者为默认）。
+
+    要求：
+    - 非空
+    - 必须是绝对路径（Windows 下 abspath 会把相对路径转绝对，故须在规范化前先判）
+    - 不含 ".."（normpath 后仍不含）
+    - 必须是存在的目录
+    - 必须含 project.precis.yaml（合法项目根标识）
+
+    参数:
+        raw_path: 原始路径字符串（通常来自 Header）
+
+    返回:
+        规范化后的绝对路径
+
+    抛出:
+        HTTPException(400): 校验失败
+    """
+    if not raw_path:
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path header 不能为空。")
+    # 步骤1：先校验原始输入是否为绝对路径
+    # 在 Windows 下，os.path.abspath 会把相对路径（如 "../project"）解析成绝对路径，
+    # 导致后续 isabs 检查无法拒绝相对路径。因此必须在规范化之前先做判断。
+    if not os.path.isabs(raw_path):
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path header 必须是一个绝对路径。")
+
+    # 路径标准化并解析为绝对路径，防御 Path Traversal
+    normalized_path = os.path.abspath(os.path.normpath(raw_path))
+    # 拒绝路径穿越（normpath 后仍出现 .. 说明超出根）
+    if ".." in normalized_path.split(os.sep):
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path 不允许包含 .. 目录穿越。")
+
+    # 步骤2：验证路径对应的目录是否存在
+    if not os.path.isdir(normalized_path):
+        raise HTTPException(status_code=404, detail=f"提供的项目配置路径不存在: {normalized_path}")
+
+    # 步骤3：验证是合法 Precis 项目根（含 manifest）
+    manifest = os.path.join(normalized_path, "project.precis.yaml")
+    if not os.path.isfile(manifest):
+        # §2.1: manifest 缺失属"资源不存在"语义，统一 404（原 400 与 GET /manifest
+        # 端点对同一情形不同状态码，且前端 404 自愈链永不触发）。detail 携带结构化
+        # 错误码，前端按 detail.code 识别（不再匹配中文措辞前缀）。
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "code": "PROJECT_NOT_FOUND",
+                "message": (
+                    "项目路径下未找到 project.precis.yaml（非合法 Precis 项目根）。"
+                    "若要初始化新项目，请使用 POST /api/latest/projects/create。"
+                ),
+                "path": normalized_path,
+            },
+        )
+
+    return normalized_path
+
+
+async def get_project_store(project_path: str = Depends(get_project_config_path)) -> ProjectStore:
+    """
+    创建项目存储对象的依赖函数。
+
+    该函数是 FastAPI 的依赖项，负责：
+    1. 调用 get_project_config_path 获取验证后的项目路径
+    2. 创建 ProjectStore 实例并返回
+
+    这种分层设计的好处：
+    - 职责分离：路径验证和对象创建分别处理
+    - 可复用性：get_project_config_path 可以被其他依赖函数复用
+    - 可测试性：每个函数都可以独立进行单元测试
+
+    :param project_path: 已验证的项目配置路径（由 get_project_config_path 注入）
+    :return: 包含项目路径的 ProjectStore 实例
+
+    使用示例：
+        @app.get("/projects/{project_id}/schemas")
+        async def get_schemas(project: ProjectStore = Depends(get_project_store)):
+            # 可以直接使用 project.project_path 访问项目路径
+            schemas = load_schemas(project.project_path)
+            return schemas
+    """
+    # 创建并返回项目存储对象，将路径封装为对象形式
+    return ProjectStore(project_path=project_path)