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

gbc/app/models/errors.py

@@ -0,0 +1,179 @@
+# 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
+
+
+def _t(key: str, **kw) -> str:
+    """惰性取本地化消息。在 __str__ 内部调用，避免 models 层模块级依赖 i18n，
+    保持核心数据契约层干净。i18n 不可用时回退到 key。"""
+    try:
+        from gbc.app.i18n import t
+        return t(key, **kw)
+    except Exception:
+        return key
+
+
+class GBCError(Exception):
+    """
+    所有GBC异常的基类
+    """
+
+class ConfigError(GBCError):
+    """
+    所有配置文件相关的Error
+    """
+
+class ExecutorError(GBCError):
+    """
+    执行器模块的Error
+    """
+
+class GuaranteeError(GBCError):
+    """
+    和保证相关的Error
+    """
+
+class IllegalOperationError(GBCError):
+    """
+    非法操作，操作意图层面就是错误的
+    """
+
+# ======== Illegal Operation ========
+class IntentDocError(IllegalOperationError):
+    """意图文档(gbc.md)领域的非法操作。携带 i18n key + 参数，__str__ 时本地化。"""
+    def __init__(self, msg_key: str, **params):
+        super().__init__(msg_key)
+        self.msg_key = msg_key
+        self.params = params
+
+    def __str__(self):
+        return _t(self.msg_key, **self.params)
+
+
+class IllegalFilePathError(IllegalOperationError):
+    """
+    非法操作，操作意图层面就是错误的
+    """
+    def __init__(self, target_file):
+        super().__init__(target_file)
+        self.target_file = target_file
+
+    def __str__(self):
+        return _t("exc.illegal_file_path", target=self.target_file)
+
+# ======== Config ========
+
+class ConfigNotFoundError(ConfigError):
+    def __init__(self, target_file):
+        super().__init__(target_file)
+        self.target_file = target_file
+
+    def __str__(self):
+        return _t("exc.config_not_found", target=self.target_file)
+
+class ConfigParseError(ConfigError):
+    def __init__(self, target_file, failure_info):
+        super().__init__(target_file)
+        self.target_file = target_file
+        self.failure_info = failure_info
+
+    def __str__(self):
+        return _t("exc.config_parse", target=self.target_file, info=self.failure_info)
+
+# ======== Project ========
+
+class ProjectNotFoundError(GBCError):
+    def __init__(self, target_project):
+        super().__init__(target_project)
+        self.target_project = target_project
+
+    def __str__(self):
+        return _t("exc.project_not_found", target=self.target_project)
+
+# ======== Meta ========
+
+class MetaNotFoundError(GBCError):
+    def __init__(self, original_file, target_file):
+        super().__init__(target_file)
+        self.original_file = original_file
+        self.target_file = target_file
+
+    def __str__(self):
+        return _t("exc.meta_not_found", target=self.target_file, original=self.original_file)
+
+# ======== Guarantee ========
+
+class GuaranteeDuplicatedError(GuaranteeError):
+    def __init__(self, target_file: str, guarantee_path: str):
+        super().__init__(target_file)
+        self.target_file = target_file
+        self.guarantee_path = guarantee_path
+
+    def __str__(self):
+        return _t("exc.guarantee_duplicated", gid=self.guarantee_path, target=self.target_file)
+
+class GuaranteeNotFoundError(GuaranteeError):
+    def __init__(self, target_file: str, guarantee_path: str):
+        super().__init__(target_file)
+        self.target_file = target_file
+        self.guarantee_path = guarantee_path
+
+    def __str__(self):
+        return _t("exc.guarantee_not_found", gid=self.guarantee_path, target=self.target_file)
+
+class GuaranteeTestFailedError(GuaranteeError):
+    def __init__(self, target_file: str, guarantee_path: str, failure_info: str):
+        super().__init__(target_file)
+        self.target_file = target_file
+        self.guarantee_path = guarantee_path
+        self.failure_info = failure_info
+
+    def __str__(self):
+        return _t("exc.guarantee_test_failed", gid=self.guarantee_path, target=self.target_file, info=self.failure_info)
+
+class GuaranteeHasDependentsError(GuaranteeError):
+    """退休保护：拒绝删除仍有 dependents 的保证。
+
+    系统不替使用者「反射式」删掉一条还有人依赖的保证——那必然悄悄弄坏下游。
+    必须先沿依赖线把 dependents 修复/迁移掉，dependents 清空后才允许退休。
+    """
+    def __init__(self, provider: str, guarantee_id: str, dependents: list[str]):
+        super().__init__(guarantee_id)
+        self.provider = provider
+        self.guarantee_id = guarantee_id
+        self.dependents = dependents
+
+    def __str__(self):
+        return _t("exc.guarantee_has_dependents", gid=self.guarantee_id,
+                  provider=self.provider, count=len(self.dependents), dependents=self.dependents)
+
+# ======== Executor ========
+
+class ExecutorNotFoundError(ExecutorError):
+    def __init__(self, config):
+        super().__init__(config)
+        self.config = config
+
+    def __str__(self):
+        return _t("exc.executor_not_found", name=self.config)
+
+
+class ExecutorConfigInvalidError(ExecutorError):
+    def __init__(self, config):
+        super().__init__(config)
+        self.config = config
+
+    def __str__(self):
+        return _t("exc.executor_config_invalid", name=self.config)

gbc/app/models/meta.py

@@ -0,0 +1,92 @@
+# 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 pydantic import BaseModel, Field
+
+# ============================================================================
+# .gbc 元数据模型
+#
+# 每个代码文件对应一份 .gbc json（FileMeta），它是「双段自包含」的：
+#   - provides   : 本文件作为 provider 提供的具名保证（保证为一等公民）
+#   - depends_on : 本文件作为 consumer 声明的依赖边
+# 两段分别承载依赖图的两个方向，由工具层负责跨文件原子地保持双向一致。
+# ============================================================================
+
+
+class Guarantee(BaseModel):
+    """一条具名行为保证，由某个 provider 文件持有、唯一一份。
+
+    身份 = 它在 ``FileMeta.provides`` 中的 key（一个语义化点路径 id，例如
+    ``"config.llm.get_model.returns_loaded"``），**不是** 测试路径——改测试
+    文件名不会改变保证的身份；多个消费者共享同一条保证时也只认这个 id。
+    """
+
+    # 承诺了什么行为、以及为何需要它（富描述，给人和 agent 读）
+    desc: str
+
+    # 测试选择器：交给 executor 做 {file} 替换的那个 str（= 旧 guarantee_path）。
+    # 与 executor 分离——这里只说「跑哪个测试」，不说「怎么跑」。
+    test: str
+
+    # executor 配置名：决定「怎么跑」这个测试（命令/cwd/env/默认超时）。
+    executor: str
+
+    # 单条保证的超时覆写；-1 表示回退到 executor 的默认超时。
+    timeout_override: int = -1
+
+    # 成本秩 + 自动运行授权等级。0 = 普通，批量必跑；>=1 = 贵/慢（如需 LLM），
+    # 批量 verify 中按阈值跳过并响亮报告。数字越大越「别随便跑」，高到一定
+    # 程度应由人类决定是否运行。批量只跑 heavy <= 阈值的；register / 点名
+    # verify_single 无视它、永远跑。
+    heavy: int = 0
+
+    # 依赖这条保证的消费者文件路径列表（多对一：一条保证可被多个文件依赖）。
+    # 这是反向边；非空即代表「还有人靠着它」，退休保护据此拒绝删除。
+    dependents: list[str] = Field(default_factory=list)
+
+    # 临时停用：True 时保证的 id 与全部边（dependents/反向边）原样保留，但「出生即绿」
+    # 门禁与批量 verify 都对它**暂缓执行**——不跑、不判失败、进 skipped(reason=disabled)。
+    # 用途：① 重构窗口(refactor 期间测试会暂时跑不过，先 disable 守住边，改完再 enable
+    #       重跑门禁)；② 循环依赖 bootstrap(测试还过不了时先占位注册)；③ 暂停在修的保证。
+    # 三者本质都是「留住 id+边，但此刻先不强制测试」。disabled 是 born-green 墙上的一个
+    # 洞，因此它必须**永远是响的**：check_consistency 始终把 disabled 保证及「依赖了
+    # disabled 保证」的边报出来(non-empty)，tree 用 ⊘ 标记——藏不住，才不会悄悄烂掉。
+    disabled: bool = False
+
+
+class Dependency(BaseModel):
+    """本文件（作为 consumer）声明的一条依赖边。
+
+    ``symbol`` 写成 ``"<provider 文件>:<符号名>"``，既标明依赖了谁的哪个符号，
+    也隐含了 provider 文件（取 ``:`` 前半段）。
+
+    ``guarantees`` 列出本文件依赖的、该 provider 上的具名保证 id：
+      - 空列表  = symbol 级「免费依赖」：只依赖符号存在/签名，不依赖具体行为，
+                  不需要、也不创建保证与测试。
+      - 非空    = 行为级依赖：每个 id 必须对应 provider ``provides`` 里的一条保证，
+                  且该保证的 ``dependents`` 里登记了本文件（双向一致）。
+    """
+
+    symbol: str
+    guarantees: list[str] = Field(default_factory=list)
+
+
+class FileMeta(BaseModel):
+    """单个代码文件的 .gbc 元数据，对 provider / consumer 两种角色都自包含。"""
+
+    # 本文件作为 provider 提供的保证：key = 保证 id。
+    provides: dict[str, Guarantee] = Field(default_factory=dict)
+
+    # 本文件作为 consumer 声明的依赖边。
+    depends_on: list[Dependency] = Field(default_factory=list)

gbc/app/models/verify.py

@@ -0,0 +1,63 @@
+# 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 pydantic import BaseModel, Field
+
+# ============================================================================
+# 验证结果模型
+#
+# 分两层：
+#   - VerifyModel    : 单个测试跑完的「原始结果」（由 core/executor 直接产出）。
+#   - VerifySummary  : 一次批量 verify 的「三桶汇总」，门禁判定从它读出。
+#
+# 门禁是二元的：跑了的测试只有 过(green) / 挂(red)；没跑的测试不是「一种结果」
+# 而是「缺席」（heavy 跳过）。所以 skipped 不染红，green = (failed 为空)。
+# ============================================================================
+
+
+class VerifyModel(BaseModel):
+    """单个测试跑完的原始结果。"""
+
+    return_code: int
+    stdout: None | str
+    stderr: None | str
+
+
+class SkippedGuarantee(BaseModel):
+    """一条被跳过、未运行的保证（当前只因 heavy 超过运行阈值）。"""
+
+    id: str
+    heavy: int
+    reason: str = "heavy"
+
+
+class VerifySummary(BaseModel):
+    """一次（批量）verify 的三桶汇总 + 门禁判定。
+
+    passed / failed / skipped 三个桶按保证 id 分类；``results`` 保留真正跑过的
+    保证的原始输出，供失败时排查。skipped 必须被响亮报告（"X heavy skipped"），
+    让调用方知道「即便全绿，问题也可能出在这些没跑的保证上」。
+    """
+
+    passed: list[str] = Field(default_factory=list)
+    failed: list[str] = Field(default_factory=list)
+    skipped: list[SkippedGuarantee] = Field(default_factory=list)
+
+    # 真正跑过的保证 id -> 原始结果（passed/failed 都收，skipped 不收）。
+    results: dict[str, VerifyModel] = Field(default_factory=dict)
+
+    @property
+    def green(self) -> bool:
+        """门禁是否通过：没有任何失败即为绿（skipped 不影响）。"""
+        return not self.failed

gbc/app/utils/__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/utils/file_utils.py

@@ -0,0 +1,24 @@
+# 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 gbc.app.config.project import get_current_project
+
+
+def to_gbc_json_path(provider: Path):
+    relative_path = provider.relative_to(get_current_project())
+    target_dir = get_current_project() / ".gbc" / relative_path.parent
+    target_filename = f"gbc.{relative_path.name}.json"
+    return target_dir / target_filename

gbc/app/utils/gbc_md.py

@@ -0,0 +1,121 @@
+# 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.
+
+"""Parse / serialize a single GBC `gbc.md` file — the canonical parser.
+
+This is the single authoritative parser/serializer for the `gbc.md` format. Both
+`interface.base.render_tree` (engine side) and the standalone intent-editor tool
+build on it; neither re-implements the format. Pure text handling, no IO.
+
+Format:
+
+    # 意图
+    <intent text, may span multiple paragraphs>
+
+    # 内部约束            <- optional H1 block
+    <constraints text>
+
+    # 文件                <- container for child entries (only emitted if any)
+    ## game.py            <- H2 entry; no trailing "/" => plain file
+    <desc>
+
+    ## maker/             <- trailing "/" => subfolder
+    <desc>                   (a subfolder's desc == that subfolder's own `# 意图`)
+
+H1 blocks: 意图 (intent) + optional 内部约束 (constraints) + 文件 (files container).
+The `# 文件` heading exists so child entries no longer visually nest under 内部约束.
+H2 blocks (the `# 文件` children): one per child file or subfolder under this path.
+
+Parsing is lenient: any H2 is treated as a child entry regardless of whether a
+`# 文件` heading precedes it, so old-format docs (entries with no `# 文件` section)
+still parse — re-serializing them upgrades them to the new format.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+INTENT_HEADING = "意图"
+CONSTRAINTS_HEADING = "内部约束"
+FILES_HEADING = "文件"
+
+_HEADING_RE = re.compile(r"^(#{1,2})\s+(.*?)\s*$")
+
+
+@dataclass
+class Entry:
+    """An H2 (`##`) child entry: a file or a subfolder."""
+    name: str            # e.g. "main.py" or "app/" (trailing slash kept for dirs)
+    is_dir: bool
+    desc: str = ""       # for files, the only source; for dirs, mirrors child intent
+
+
+@dataclass
+class ParsedDoc:
+    intent: str = ""
+    constraints: str = ""
+    entries: list[Entry] = field(default_factory=list)
+
+
+def parse(text: str) -> ParsedDoc:
+    """Parse gbc.md text into intent / constraints / ordered entries."""
+    doc = ParsedDoc()
+    # current sink: "intent" | "constraints" | entry-index | None (discard)
+    body: list[str] = []
+    sink: str | int | None = None
+
+    def flush() -> None:
+        content = "\n".join(body).strip()
+        if sink == "intent":
+            doc.intent = content
+        elif sink == "constraints":
+            doc.constraints = content
+        elif isinstance(sink, int):
+            doc.entries[sink].desc = content
+
+    for line in text.splitlines():
+        m = _HEADING_RE.match(line)
+        if not m:
+            body.append(line)
+            continue
+        # heading boundary: flush the previous block first
+        flush()
+        body = []
+        level, title = len(m.group(1)), m.group(2).strip()
+        if level == 1:
+            if title == CONSTRAINTS_HEADING:
+                sink = "constraints"
+            elif title == FILES_HEADING:
+                sink = None  # the 文件 container heading has no body; its H2s are entries
+            else:
+                sink = "intent"
+        else:  # level 2 -> child entry
+            is_dir = title.endswith("/")
+            doc.entries.append(Entry(name=title, is_dir=is_dir))
+            sink = len(doc.entries) - 1
+    flush()
+    return doc
+
+
+def serialize(intent: str, constraints: str, entries: list[Entry]) -> str:
+    """Render intent / constraints / entries back into gbc.md text."""
+    blocks: list[str] = []
+    blocks.append(f"# {INTENT_HEADING}\n{intent.strip()}".rstrip())
+    if constraints.strip():
+        blocks.append(f"# {CONSTRAINTS_HEADING}\n{constraints.strip()}".rstrip())
+    if entries:
+        blocks.append(f"# {FILES_HEADING}")
+        for e in entries:
+            blocks.append(f"## {e.name}\n{e.desc.strip()}".rstrip())
+    return "\n\n".join(blocks) + "\n"

gbc/app/utils/json_model_operator.py

@@ -0,0 +1,85 @@
+# 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 json
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from gbc.app.utils.safe_file_writer import SafeFileWriter
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def load_model_from_json(
+        filepath: str | Path,
+        model_class: type[T]
+) -> T:
+    """
+    从指定的 JSON 文件中读取并还原为 Pydantic 模型。
+
+    Args:
+        filepath: 明确的完整文件路径。
+        model_class: 用于解析的 Pydantic 模型类。
+
+    Returns:
+        实例化后的模型对象。
+
+    Raises:
+        FileNotFoundError: 当指定路径不存在时抛出。
+        ValidationError: 当 JSON 内容不符合模型定义时抛出。
+    """
+    path = Path(filepath)
+
+    if not path.exists():
+        raise FileNotFoundError(f"未找到指定的模型文件: {path}")
+
+    with open(path, "r", encoding="utf-8") as f:
+        try:
+            raw_data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"解析 JSON 文件失败: {path}, 错误详情: {e}")
+
+    try:
+        return model_class(**raw_data)
+    except ValidationError as e:
+        # 在这里可以记录日志或者直接抛出
+        raise e
+
+def save_model_to_json(
+        model: BaseModel,
+        filepath: str | Path,
+        num_backups: int = 0
+) -> None:
+    """
+    将 Pydantic 模型安全地序列化为 JSON 文件。
+
+    Args:
+        model: 要保存的 Pydantic 模型对象。
+        filepath: 明确的完整文件路径。
+        num_backups: 备份数量，由 SafeFileWriter 处理。
+    """
+    path = Path(filepath)
+
+    # 确保父目录存在
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    writer = SafeFileWriter(path, num_backups=num_backups)
+
+    # 获取字典数据
+    data = model.model_dump()
+
+    with writer.open(mode='w', encoding='utf-8') as f:
+        json.dump(data, f, ensure_ascii=False, indent=4)