guarantee-based-coding 0.2.0__py3-none-any.whl

gbc/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+"""GBC — Guarantee-Based Coding.
+
+让代码在不被完全理解的情况下也能被安全修改：把模块间依赖从隐含变成
+显式、可执行、可验证的保证。本包是该方法的实现，也是它的第一个使用者。
+"""
+
+__version__ = "0.2.0"

gbc/app/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+

gbc/app/assets.py

@@ -0,0 +1,38 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+"""静态资源定位的单一入口。
+
+所有随包分发的**数据**（i18n catalog/texts、editor 前端）集中在 `gbc/assets/`
+下，与**代码**彻底分离。任何模块要读资源都从这里取路径，不各自
+`Path(__file__).parent` ——加一类资源只需在此登记一处 + 打包声明一条。
+
+打包：`pyproject.toml` 的 `[tool.setuptools.package-data]` 以 `"gbc" = ["assets/**"]`
+把整个 assets 树纳入 wheel（散在各子包时易漏声明，这正是集中的理由）。
+"""
+from pathlib import Path
+
+# assets 根：本文件在 gbc/app/assets.py，上溯到 gbc/ 再进 assets/。
+ASSETS_DIR = Path(__file__).resolve().parent.parent / "assets"
+
+# i18n 短消息查表 与 长文本资源。
+I18N_CATALOG_DIR = ASSETS_DIR / "i18n" / "catalog"
+I18N_TEXTS_DIR = ASSETS_DIR / "i18n" / "texts"
+
+# 意图编辑器 web 前端静态页。
+EDITOR_FRONTEND_DIR = ASSETS_DIR / "editor"
+
+# 给 CLI-only agent 的预组 skills（教 agent 怎么调 gbc 子命令，等价于 MCP 工具描述）。
+# gbc setup 只告知此目录坐标，由用户自行放到其 agent 读 skill 的位置。
+SKILLS_DIR = ASSETS_DIR / "skills"

gbc/app/config/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+

gbc/app/config/backups.py

@@ -0,0 +1,28 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+import os
+from pathlib import Path
+
+from gbc.app.config.base import PROJECT_ROOT
+
+# 初始化备份数量
+def _init_meta_backups() -> int:
+    var = os.environ.get("GBC_META_BACKUPS", None)
+    if var and var.isdigit():
+        return int(var)
+
+    return 0
+
+META_BACKUPS = _init_meta_backups()

gbc/app/config/base.py

@@ -0,0 +1,29 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+import os
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """获取工具仓根目录。
+
+    注意:文件已迁入 `gbc/app/config/base.py`,比旧布局(`app/config/base.py`)多一层
+    `gbc/`,故上溯四层(base.py -> config -> app -> gbc -> 仓根)。
+    """
+    return Path(__file__).resolve().parent.parent.parent.parent
+
+
+PROJECT_ROOT = get_project_root()
+CONFIG_DIR = PROJECT_ROOT / "config"

gbc/app/config/executor.py

@@ -0,0 +1,132 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ValidationError
+
+from gbc.app.config.project import get_current_project
+from gbc.app.utils.json_model_operator import load_model_from_json, save_model_to_json
+
+
+# ---- 落盘位置 --------------------------------------------------------------
+# executor 配置是**每台机器都不同**的可变状态(解释器路径、项目路径),因此:
+#   - 落在**目标项目**的 `.gbc/` 下(而非工具仓),让工具仓保持只读、可 pip 安装;
+#   - 私有真配置 `executors.json` 应进 gitignore;
+#   - 可提交的清单 `executors.example.json` 脱敏(只留名字 + 结构骨架),供协作者
+#     知道"本项目需要配哪些 executor",而绝不泄露任何机器相关值或密钥。
+EXECUTORS_FILENAME = "executors.json"
+EXECUTORS_EXAMPLE_FILENAME = "executors.example.json"
+
+
+def executors_config_path() -> Path:
+    """当前目标项目的私有 executor 配置路径。随 `get_current_project()` 走。"""
+    return get_current_project() / ".gbc" / EXECUTORS_FILENAME
+
+
+def executors_example_path() -> Path:
+    """当前目标项目的脱敏 executor 清单路径(可提交进 git)。"""
+    return get_current_project() / ".gbc" / EXECUTORS_EXAMPLE_FILENAME
+
+
+class EnvAction(BaseModel):
+    # key: 环境变量名
+    key: str
+    # action: 支持 set (覆盖), append (后补), prepend (前缀), remove (删除)
+    action: Literal["set", "append", "prepend", "remove"]
+    # value: 操作的值 (remove 时可为 None)
+    value: str | None = None
+
+
+# 单个执行器
+class ExecutorModel(BaseModel):
+    command: list[str]
+    cwd: str
+    timeout: int = -1
+    env_ops: None | list[EnvAction] = None
+    # 人类可读说明:example 清单里唯一保留的"内容",由登记方**显式撰写**,
+    # 用来告诉协作者这个 executor 是什么、该怎么填。绝不从 command 自动推导(可能含密钥)。
+    comment: str | None = None
+
+
+# 执行器配置
+class ExecutorsConfig(BaseModel):
+    executors: dict[str, ExecutorModel]
+
+
+# ---- 惰性单例 --------------------------------------------------------------
+# 关键:**不在 import 时读盘**。import 时项目根往往还没经 argv/set_current_project
+# 设定好(MCP server 场景),此刻读盘只会命中错误位置。改为首次访问时按当前项目定位。
+_cache: ExecutorsConfig | None = None
+_cache_path: Path | None = None
+
+
+def _load(path: Path) -> ExecutorsConfig:
+    try:
+        return load_model_from_json(path, ExecutorsConfig)
+    except FileNotFoundError:
+        return ExecutorsConfig(executors={})
+    except (ValueError, ValidationError):
+        return ExecutorsConfig(executors={})
+
+
+def get_executors_config() -> ExecutorsConfig:
+    """惰性获取当前项目的 executor 配置单例。
+
+    随目标项目变化自动重载:当 `get_current_project()` 指向的项目变了(缓存路径
+    与当前路径不一致),重新按新路径加载——保证一个进程内切换项目时不串配置。
+    """
+    global _cache, _cache_path
+    path = executors_config_path()
+    if _cache is None or _cache_path != path:
+        _cache = _load(path)
+        _cache_path = path
+    return _cache
+
+
+def _to_example(config: ExecutorsConfig) -> dict:
+    """把真配置脱敏成可提交的清单。
+
+    约定(已拍板):**全删机器相关字段**——只留 executor 名字(作 key)与显式
+    `comment`。command/cwd/timeout/env_ops 一律**不出现**(不是置空、而是缺失),
+    因为无注释的空占位 ≈ 字段缺失,那就选更简单的「缺失」;缺失不静默——
+    Pydantic 必填校验与 `gbc doctor` 会替它嗊出「你需要配 X」。绝不拷任何原始值。
+    """
+    executors: dict[str, dict] = {}
+    for name, model in config.executors.items():
+        entry: dict = {}
+        if model.comment is not None:
+            entry["comment"] = model.comment
+        executors[name] = entry
+    return {"executors": executors}
+
+
+def save_executors_config() -> None:
+    """保存当前项目的 executor 配置,并同步重算脱敏清单 example。
+
+    二者始终一起写,避免 example 腐烂。example 是宽松 dict(非 ExecutorModel),
+    因为它故意缺字段。
+    """
+    import json
+
+    config = get_executors_config()
+    save_model_to_json(config, executors_config_path(), num_backups=0)
+
+    example_path = executors_example_path()
+    example_path.parent.mkdir(parents=True, exist_ok=True)
+    example_path.write_text(
+        json.dumps(_to_example(config), ensure_ascii=False, indent=4),
+        encoding="utf-8",
+    )

gbc/app/config/project.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+from pathlib import Path
+
+
+# 初始化当前路径：进程启动时的 cwd。CLI 单次命令默认就用这个——“当前项目 = 跑命令时所在目录”，
+# 无需环境变量，不会静默回退到包安装位置。常驻服务（mcp up / editor up）cwd 不可靠，
+# 它们自己收显式参数覆盖，不依赖这个默认值。
+def _init_current_project() -> Path:
+    return Path.cwd()
+
+# 会被使用的当前路径变量
+CURRENT_PROJECT = _init_current_project()
+
+# 更新当前路径
+def set_current_project(new_path: str):
+    new_path = Path(new_path)
+
+    global CURRENT_PROJECT
+    CURRENT_PROJECT = new_path
+
+def get_current_project():
+    return CURRENT_PROJECT

gbc/app/core/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+

gbc/app/core/env.py

@@ -0,0 +1,64 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+import os
+
+from gbc.app.config.executor import EnvAction
+
+
+def get_clean_python_path():
+    env = os.environ.copy()
+    pp_list = env.get("PYTHONPATH", "").split(os.pathsep)
+    pp_list = pp_list[1:]
+    env["PYTHONPATH"] = os.pathsep.join(pp_list)
+
+    return env
+
+
+def apply_env_action(env: dict[str, str], op: EnvAction, sep: str = os.pathsep) -> dict[str, str]:
+    """
+    对传入的 env 字典执行单个 EnvAction 操作。
+    注：为了安全，建议传入 env.copy() 以避免副作用。
+    """
+
+    key = op.key
+    val = op.value or ""
+
+    match op.action:
+        case "set":
+            env[key] = val
+
+        case "remove":
+            env.pop(key, None)
+
+        case "append":
+            current = env.get(key, "")
+            # 如果当前有值，则用分隔符连接；否则直接设为 val
+            env[key] = f"{current}{sep}{val}" if current else val
+
+        case "prepend":
+            current = env.get(key, "")
+            # 如果当前有值，则用分隔符连接；否则直接设为 val
+            env[key] = f"{val}{sep}{current}" if current else val
+
+    return env
+
+def apply_env_actions(env: dict[str, str], ops: None | list[EnvAction], sep: str = os.pathsep) -> dict[str, str]:
+    if not ops:
+        return env
+
+    for op in ops:
+        apply_env_action(env, op, sep)
+
+    return env

gbc/app/core/executor.py

@@ -0,0 +1,116 @@
+# Copyright 2026 Jesse-x86
+#
+# 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.
+
+import subprocess
+
+from gbc.app.config.executor import get_executors_config, ExecutorModel, save_executors_config
+from gbc.app.core.env import apply_env_actions, get_clean_python_path
+from gbc.app.models.errors import ExecutorNotFoundError
+from gbc.app.models.verify import VerifyModel
+
+FILE_PLACEHOLDERS = ["{file}", "{f}"]
+DEFAULT_TIMEOUT = 15
+
+def has_exec_config(config: str) -> bool:
+    """
+    是否存在该 config
+    :param config:
+    :return:
+    """
+    return config in get_executors_config().executors
+
+def _execute(config: str, file: str, timeout: int = -1) -> subprocess.CompletedProcess[str]:
+    """
+    使用特定配置文件，执行单个测试
+    :param config:
+    :param file:
+    :param timeout:
+    :return:
+    """
+    if not has_exec_config(config):
+        raise ExecutorNotFoundError(config)
+
+    executor_cfg = get_executors_config().executors[config]
+
+    args = executor_cfg.command.copy()
+    args = [arg.replace("{file}", file).replace("{f}", file) for arg in args]
+
+    env = apply_env_actions(get_clean_python_path(), executor_cfg.env_ops)
+
+    if timeout < 0:
+        timeout = executor_cfg.timeout
+
+    if timeout < 0:
+        timeout = DEFAULT_TIMEOUT
+
+    result = subprocess.run(
+        args=args,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        cwd=executor_cfg.cwd,
+        env=env,
+        # 绝不让被测进程继承父进程的 stdin。作为 MCP server 运行时父进程 stdin 是
+        # JSON-RPC 协议管道，子进程继承后会阻塞（"终端能跑、当服务挂"的经典坑）。
+        stdin=subprocess.DEVNULL,
+    )
+
+    return result
+
+def verify_single(config: str, file: str, *, timeout: int = -1, return_model: bool = True) -> bool | VerifyModel:
+    """
+    验证单个测试
+    :param config:
+    :param file:
+    :param timeout:
+    :param return_model:
+    :return:
+    """
+    result = _execute(config, file, timeout)
+
+    if not return_model:
+        return result.returncode == 0
+
+    return VerifyModel(
+        return_code=result.returncode,
+        stdout=result.stdout,
+        stderr=result.stderr
+    )
+
+def upsert_exec_config(config_name: str, model: ExecutorModel):
+    """
+    插入或更新执行器配置
+    :param config_name:
+    :param model:
+    :return:
+    """
+    get_executors_config().executors[config_name] = model
+    save_executors_config()
+
+def remove_exec_config(config_name: str):
+    """
+    删除执行器配置
+    :param config_name:
+    :return:
+    """
+    if has_exec_config(config_name):
+        del get_executors_config().executors[config_name]
+    save_executors_config()
+
+def get_all_exec_configs():
+    """
+    获取全部执行器配置
+    :return:
+    """
+    return get_executors_config().copy()