precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/commands/config/init.py

@@ -0,0 +1,123 @@
+# 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.
+# backend/app/cli/shell/commands/config/init.py
+"""
+@fileoverview 配置初始化命令模块
+
+功能概述:
+- 提供 config init 子命令基于模板创建新配置文件
+- 支持 project、constraint、pattern 三种模板类型
+- 自动使用项目名称填充模板变量
+
+架构设计:
+- ConfigInitCommand 继承 Command 基类
+- 使用字典映射模板类型到 (默认文件名, 模板内容)
+- 检查文件是否已存在，避免意外覆盖
+
+输入示例:
+    config init project
+    config init constraint my_constraints.yaml
+
+输出示例:
+    CommandResult.ok("已创建配置文件: project.precis.yaml")
+    CommandResult.error("文件已存在: project.precis.yaml")
+"""
+
+import os
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.commands.config.base import CONSTRAINT_TEMPLATE, PATTERNS_TEMPLATE, PROJECT_TEMPLATE
+
+
+class ConfigInitCommand(Command):
+    """初始化配置命令。
+
+    基于内置模板创建新的配置文件。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("init")
+
+    @property
+    def description(self) -> str:
+        return "初始化新的配置文件"
+
+    @property
+    def usage(self) -> str:
+        return "config init <project|constraint|pattern> [filename]"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行初始化配置命令。
+
+        Args:
+            args: 命令参数列表，第一个为模板类型，第二个可选为文件名
+            context: 项目上下文
+
+        Returns:
+            创建成功或失败的结果
+        """
+        project_path = context.project_path
+        if project_path is None:
+            return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+        if not args:
+            return CommandResult.error(
+                "请指定模板类型: project, constraint, pattern\n用法: config init <type> [filename]"
+            )
+
+        template_type = args[0].lower()
+
+        # 模板类型映射：类型 -> (默认文件名, 模板内容)
+        templates = {
+            "project": ("project.precis.yaml", PROJECT_TEMPLATE),
+            "constraint": ("constraints.yaml", CONSTRAINT_TEMPLATE),
+            "pattern": ("patterns.yaml", PATTERNS_TEMPLATE),
+            "patterns": ("patterns.yaml", PATTERNS_TEMPLATE),
+        }
+
+        if template_type not in templates:
+            return CommandResult.error(f"未知模板类型: {template_type}\n可用类型: project, constraint, pattern")
+
+        default_filename, template = templates[template_type]
+
+        # 使用指定的文件名或默认文件名
+        filename = args[1] if len(args) > 1 else default_filename
+        # 4.7: 路径穿越防护——对齐 config set 的防护语义（禁止绝对路径/../~
+        # 前缀），否则 config init ../../x.yaml 可写项目外
+        from pathlib import Path as _Path
+
+        if os.path.isabs(filename) or any(seg == ".." for seg in _Path(filename).parts) or filename.startswith("~"):
+            return CommandResult.error(f"非法的文件名（不允许绝对路径或 .. 引用）: {filename}")
+        filepath = os.path.join(project_path, filename)
+        if not os.path.abspath(filepath).startswith(os.path.abspath(project_path) + os.sep):
+            return CommandResult.error(f"文件路径超出项目目录: {filename}")
+
+        # 检查文件是否已存在
+        if os.path.exists(filepath):
+            return CommandResult.error(f"文件已存在: {filename}\n如需覆盖，请先删除原文件")
+
+        # 生成文件内容（使用项目名称填充模板变量）。
+        # 用 replace 而非 str.format：模板内含正则量词 {2,} 等花括号字面量，
+        # format 会把它们当替换字段抛 KeyError（config init pattern 必崩）
+        project_name = os.path.basename(project_path)
+        content = template.replace("{project_name}", project_name)
+
+        try:
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(content)
+            return CommandResult.ok(f"已创建配置文件: {filename}")
+        except Exception as e:
+            return CommandResult.error(f"创建文件失败: {e}")

app/cli/shell/commands/config/inspect.py

@@ -0,0 +1,164 @@
+# 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.
+# backend/app/cli/shell/commands/config/inspect.py
+"""
+@fileoverview 配置自检命令模块
+
+功能概述:
+- 提供 config inspect 子命令，执行项目配置的跨文件一致性自检
+- 复用后端 inspect_config 检查引擎（ID 一致性、引用完整性、数据源冲突等）
+- 将检查结果格式化为友好的 CLI 输出（按严重度分组、显示修复建议）
+
+架构设计:
+- ConfigInspectCommand 继承 Command 基类
+- 通过 load_project() 加载项目（内部已执行 inspect_config，结果在 loading_errors）
+- _format_report(): 将 LoadingError 列表格式化为可读文本
+
+输入示例:
+    config inspect
+
+输出示例:
+    CommandResult.ok("✓ 配置自检通过，未发现问题")
+    CommandResult.error("配置自检发现 3 个问题:\n...")
+"""
+
+from __future__ import annotations
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.formatter import _supports_unicode
+from app.shared.core.project.loader.loader_parts.main import load_project
+from app.shared.core.project.loader.types import LoadingError
+
+_CHECK_MARK = "\u2713" if _supports_unicode() else "[OK]"
+_CROSS_MARK = "\u2717" if _supports_unicode() else "[FAIL]"
+
+# 严重度展示符号与标签
+_SEVERITY_DISPLAY = {
+    "blocker": ("🔴", "阻塞"),
+    "warning": ("⚠️", "警告"),
+    "info": ("ℹ️", "提示"),
+}
+
+
+class ConfigInspectCommand(Command):
+    """配置自检命令。
+
+    执行项目配置的跨文件一致性检查，复用后端 inspect_config 引擎。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("inspect")
+
+    @property
+    def description(self) -> str:
+        return "执行配置文件跨文件一致性自检（ID 一致性、引用完整性、数据源冲突）"
+
+    @property
+    def usage(self) -> str:
+        return "config inspect"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行配置自检命令。
+
+        通过 load_project 加载项目，复用其内置的 inspect_config 检查逻辑，
+        将收集到的 loading_errors 格式化为友好的 CLI 报告。
+
+        Args:
+            args: 命令参数列表（本命令不接收参数）
+            context: 项目上下文
+
+        Returns:
+            自检结果，成功表示无问题，失败表示发现问题
+        """
+        project_path = context.project_path
+        if project_path is None:
+            return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+        # 定位 manifest 文件
+        import os
+
+        manifest_path = os.path.join(project_path, "project.precis.yaml")
+        if not os.path.isfile(manifest_path):
+            # 兼容 .yml 后缀
+            alt = os.path.join(project_path, "project.precis.yml")
+            if os.path.isfile(alt):
+                manifest_path = alt
+            else:
+                return CommandResult.error(f"未找到项目清单文件 project.precis.yaml（在 {project_path} 下）")
+
+        # 复用 load_project：其内部已执行 inspect_config，结果在 loading_errors
+        try:
+            loaded = load_project(manifest_path)
+        except Exception as e:
+            return CommandResult.error(f"加载项目失败: {e}")
+
+        errors: list[LoadingError] = loaded.loading_errors or []
+        warnings: list[str] = loaded.warnings or []
+
+        if not errors:
+            extra = f"\n（另有 {len(warnings)} 条加载警告）" if warnings else ""
+            return CommandResult.ok(f"{_CHECK_MARK} 配置自检通过，未发现问题{extra}")
+
+        report = self._format_report(errors)
+        # 有 blocker 时整体视为失败，否则视为成功附带警告
+        has_blocker = any(e.severity == "blocker" for e in errors)
+        summary = f"配置自检发现 {len(errors)} 个问题"
+        if has_blocker:
+            return CommandResult.error(f"{summary}:\n{report}")
+        return CommandResult.ok(f"{summary}（均为非阻塞，建议处理）:\n{report}")
+
+    def _format_report(self, errors: list[LoadingError]) -> str:
+        """将 LoadingError 列表格式化为可读文本报告。
+
+        按 severity 分组展示，每组下列出各问题的标题、文件路径与修复建议。
+
+        Args:
+            errors: 自检收集的错误列表
+
+        Returns:
+            格式化的多行文本报告
+        """
+        lines: list[str] = []
+
+        # 按严重度分组：blocker → warning → info
+        severity_order = ["blocker", "warning", "info"]
+        grouped: dict[str, list[LoadingError]] = {s: [] for s in severity_order}
+        for err in errors:
+            grouped.setdefault(err.severity, []).append(err)
+
+        for sev in severity_order:
+            group = grouped.get(sev, [])
+            if not group:
+                continue
+            icon, label = _SEVERITY_DISPLAY.get(sev, ("•", sev))
+            lines.append(f"\n{icon} {label}（{len(group)}）")
+
+            for err in group:
+                title = err.title or err.error_type or "未知问题"
+                lines.append(f"  {_CROSS_MARK} {title}")
+                if err.file_path:
+                    lines.append(f"     文件: {err.file_path}")
+                if err.ref_id:
+                    lines.append(f"     编号: {err.ref_id}")
+                if err.description:
+                    lines.append(f"     说明: {err.description}")
+                if err.fix_hint:
+                    lines.append(f"     建议: {err.fix_hint}")
+                # 若有一键修复 API，提示用户（CLI 暂不自动修复，但告知可修复）
+                if err.fix_api:
+                    lines.append(f"     可修复: {err.fix_api.get('method', 'POST')} {err.fix_api.get('path', '')}")
+
+        return "\n".join(lines)

app/cli/shell/commands/config/list.py

@@ -0,0 +1,104 @@
+# 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.
+# backend/app/cli/shell/commands/config/list.py
+"""
+@fileoverview 配置列表命令模块
+
+功能概述:
+- 提供 config list 子命令列出项目中所有 YAML 配置文件
+- 递归扫描 schemas、constraints、patterns、regex 目录
+- 格式化显示文件名与大小
+
+架构设计:
+- ConfigListCommand 继承 Command 基类
+- 先扫描项目根目录，再递归扫描子目录
+- _format_size(): 将字节转换为人类可读格式（B/KB/MB）
+
+输入示例:
+    config list
+
+输出示例:
+    配置文件列表表格
+"""
+
+from app.cli.shared_services.config_ops import list_config_files
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.formatter import Formatter
+
+
+class ConfigListCommand(Command):
+    """列出配置命令。
+
+    显示项目中所有 YAML 配置文件及其大小。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("list")
+
+    @property
+    def description(self) -> str:
+        return "列出项目中的所有配置文件"
+
+    @property
+    def usage(self) -> str:
+        return "config list"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行列出配置命令。
+
+        Args:
+            args: 命令参数列表（此命令不需要参数）
+            context: 项目上下文
+
+        Returns:
+            配置文件列表或提示信息
+        """
+        project_path = context.project_path
+        if project_path is None:
+            return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+        # 扫描配置文件（委托 shared_services 纯逻辑，CLI/TUI 同源）
+        config_files = list_config_files(project_path)
+
+        if not config_files:
+            return CommandResult.ok("暂无配置文件")
+
+        output_lines = [Formatter.header("\n配置文件列表:")]
+        output_lines.append(f"{'文件名':<40} {'大小':>10}")
+        output_lines.append("-" * 52)
+
+        for cf in config_files:
+            size_str = self._format_size(cf.size)
+            output_lines.append(f"{cf.name:<40} {size_str:>10}")
+
+        output_lines.append(f"\n共 {len(config_files)} 个配置文件")
+        return CommandResult.ok("\n".join(output_lines))
+
+    def _format_size(self, size: int) -> str:
+        """格式化文件大小。
+
+        Args:
+            size: 文件大小（字节）
+
+        Returns:
+            人类可读的字符串，如 "1.5KB"
+        """
+        if size < 1024:
+            return f"{size}B"
+        elif size < 1024 * 1024:
+            return f"{size / 1024:.1f}KB"
+        else:
+            return f"{size / (1024 * 1024):.1f}MB"

app/cli/shell/commands/config/set.py

@@ -0,0 +1,119 @@
+# 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.
+# backend/app/cli/shell/commands/config/set.py
+"""
+@fileoverview 配置设置命令模块
+
+功能概述:
+- 提供 config set 子命令按点号路径设置配置项值
+- 支持布尔值、整数、浮点数、列表、字典与字符串的自动类型解析
+- 保留 YAML 注释与格式，原子写回，路径解析含穿越防护
+
+架构设计:
+- ConfigSetCommand 继承 Command 基类
+- _parse_value(): 自动推断值的类型（bool -> int -> float -> yaml -> str），已收敛至
+  shared_services 的 parse_config_value（CLI/TUI 同源）
+- 文件定位/写入统一委托 shared_services 的 set_config_value_in_file：
+  find_config_file 防路径穿越 + ruamel round-trip 仅替换目标键的值（保留注释）
+  + 临时文件原子替换
+
+输入示例:
+    config set project.precis.yaml project.name "My Project"
+    config set project.precis.yaml validation.auto_validate true
+
+输出示例:
+    CommandResult.ok("已设置: project.name = My Project")
+    CommandResult.error("配置文件不存在: project.precis.yaml")
+"""
+
+from app.cli.shared_services.config_ops import (
+    MATCH_BASENAME,
+    parse_config_value,
+    resolve_config_file,
+    set_config_value_in_file,
+)
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+
+
+class ConfigSetCommand(Command):
+    """设置配置项命令。
+
+    按点号路径设置 YAML 配置文件中指定项的值。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("set")
+
+    @property
+    def description(self) -> str:
+        return "设置配置项的值（支持点号路径）"
+
+    @property
+    def usage(self) -> str:
+        return "config set [--string] <config_file> <key_path> <value>"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行设置配置项命令。
+
+        Args:
+            args: 命令参数列表，需要包含文件名、路径和值
+            context: 项目上下文
+
+        Returns:
+            设置成功或失败的结果
+        """
+        project_path = context.project_path
+        if project_path is None:
+            return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+        # §4.3: --string 旗标——身份型字段（编号 007/版本 1.10）跳过类型推断按原字面量写入
+        raw_args = args
+        as_string = False
+        if raw_args and raw_args[0] == "--string":
+            as_string = True
+            raw_args = raw_args[1:]
+
+        if len(raw_args) < 3:
+            return CommandResult.error(
+                "用法: config set [--string] <config_file> <key_path> <value>\n"
+                '示例: config set project.precis.yaml project.name "My Project"\n'
+                "      config set --string users.schema.yaml col.code 007  # 保留前导零"
+            )
+
+        config_file = raw_args[0]
+        key_path = raw_args[1]
+        value_str = raw_args[2]
+
+        # 解析值（委托 shared_services 纯逻辑，CLI/TUI 同源）
+        # parse_config_value 始终成功返回三元组，行为与原 _parse_value 一致
+        value = value_str if as_string else parse_config_value(value_str)[1]
+
+        # 定位结果（用于文件名模糊回退命中时披露实际写入路径）
+        resolved_path, match_kind = resolve_config_file(project_path, config_file)
+
+        # 定位文件并写入（委托 shared_services，CLI/TUI 同源）：
+        # - find_config_file 统一路径解析，含 .. / 绝对路径等穿越防护与递归回退
+        # - ruamel round-trip 仅替换目标键的值，保留注释与格式
+        # - 临时文件 + os.replace 原子写回，失败时不损坏原文件
+        ok, error_message = set_config_value_in_file(project_path, config_file, key_path, value)
+        if not ok:
+            return CommandResult.error(error_message)
+
+        message = f"已设置: {key_path} = {value}"
+        if match_kind == MATCH_BASENAME and resolved_path:
+            # 模糊回退命中的是同名文件而非用户输入路径，必须披露实际写入位置
+            message += f"（按文件名回退匹配，实际写入: {resolved_path}）"
+        return CommandResult.ok(message)

app/cli/shell/commands/config/show.py

@@ -0,0 +1,150 @@
+# 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.
+# backend/app/cli/shell/commands/config/show.py
+"""
+@fileoverview 配置显示命令模块
+
+功能概述:
+- 提供 config show 子命令显示项目配置文件内容
+- 支持单文件显示与默认配置文件批量显示
+- 使用 YAML 格式化输出
+
+架构设计:
+- ConfigShowCommand 继承 Command 基类
+- 指定文件时调用 _show_single_file() 显示单个文件
+- 未指定时显示一组默认配置文件的内容
+
+输入示例:
+    config show
+    config show project.precis.yaml
+
+输出示例:
+    格式化的 YAML 配置内容
+"""
+
+import os
+
+import yaml
+
+from app.cli.shared_services.config_ops import find_config_file
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.formatter import Formatter
+
+
+class ConfigShowCommand(Command):
+    """显示配置命令。
+
+    显示项目配置文件的内容，支持单文件或批量显示。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("show")
+
+    @property
+    def description(self) -> str:
+        return "显示当前项目的配置文件内容"
+
+    @property
+    def usage(self) -> str:
+        return "config show [config_file]"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行显示配置命令。
+
+        Args:
+            args: 命令参数列表，可能包含要显示的文件名
+            context: 项目上下文
+
+        Returns:
+            配置文件内容或错误提示
+        """
+        project_path = context.project_path
+        if project_path is None:
+            return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+        # 如果指定了具体文件，只显示该文件
+        if args:
+            config_file = args[0]
+            config_path = find_config_file(project_path, config_file)
+            if not config_path:
+                return CommandResult.error(f"配置文件不存在: {config_file}")
+            # 显示相对路径
+            rel_path = os.path.relpath(config_path, project_path)
+            return self._show_single_file(config_path, rel_path)
+
+        # 否则显示所有配置文件。
+        # §4.26: 无参 show 按 V2 目录结构遍历（schemas/constraints/regex/transforms/
+        # templates 分目录 + 根目录两文件）——原硬编码 V1 根目录文件清单，对 V2
+        # 项目几乎只显示 manifest 一个文件，其余配置全看不到（不做 V1 兼容层）
+        from pathlib import Path as _Path
+
+        output_lines = [Formatter.header("\n项目配置文件:")]
+
+        def _show_file(rel_path: str, abs_path: str) -> None:
+            output_lines.append(f"\n{Formatter.info('--- ' + rel_path + ' ---')}")
+            try:
+                output_lines.append(_Path(abs_path).read_text(encoding="utf-8"))
+            except Exception as e:
+                output_lines.append(f"(读取失败: {e})")
+
+        # 分目录收集（保持稳定的目录顺序）
+        for subdir, pattern in (
+            ("schemas", "*.schema.yaml"),
+            ("constraints", "*.constraint.yaml"),
+            ("regex", "*.regex.yaml"),
+            ("transforms", "*.transform.yaml"),
+            ("templates", "*.template.yaml"),
+        ):
+            dir_path = _Path(project_path) / subdir
+            if not dir_path.is_dir():
+                continue
+            for fp in sorted(dir_path.glob(pattern)):
+                _show_file(f"{subdir}/{fp.name}", str(fp))
+
+        # 根目录核心文件
+        for root_file in ("project.precis.yaml", "patterns.precis.yaml"):
+            root_path = os.path.join(project_path, root_file)
+            if os.path.isfile(root_path):
+                _show_file(root_file, root_path)
+
+        if len(output_lines) == 1:
+            return CommandResult.ok("项目中没有找到任何配置文件。")
+
+        return CommandResult.ok("\n".join(output_lines))
+
+    def _show_single_file(self, config_path: str, config_file: str) -> CommandResult:
+        """显示单个配置文件。
+
+        Args:
+            config_path: 文件的完整路径
+            config_file: 用于显示的相对路径
+
+        Returns:
+            文件内容或错误提示
+        """
+        try:
+            with open(config_path, encoding="utf-8") as f:
+                content = yaml.safe_load(f)
+
+            output_lines = [
+                Formatter.header(f"\n{config_file}"),
+                yaml.dump(content, allow_unicode=True, default_flow_style=False),
+            ]
+            return CommandResult.ok("\n".join(output_lines))
+        except yaml.YAMLError as e:
+            return CommandResult.error(f"YAML 解析失败: {e}")
+        except Exception as e:
+            return CommandResult.error(f"读取失败: {e}")