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

gbc/app/core/guarantee.py

@@ -0,0 +1,338 @@
+# 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.
+
+"""保证系统的核心逻辑（纯模型操作 + 跑测试，无文件 IO / 无路径解析）。
+
+约定：
+  - 所有进出本模块的文件路径都是「项目相对 POSIX 字符串」，路径解析由 base 层负责。
+  - 本模块直接读写 FileMeta 模型对象；跨文件操作（注册依赖）同时收 consumer 与
+    provider 两个 meta，原子地维护双向一致，但落盘仍由 base 层负责。
+  - 「出生即绿」门禁：create / update 改动测试时当场跑测试，不过则拒绝（抛错），
+    绝不留下一条没验证过的保证。
+"""
+
+from gbc.app.core import executor
+from gbc.app.models.errors import (
+    GuaranteeDuplicatedError,
+    GuaranteeNotFoundError,
+    GuaranteeTestFailedError,
+    GuaranteeHasDependentsError,
+)
+from gbc.app.models.meta import FileMeta, Guarantee, Dependency
+from gbc.app.models.verify import VerifyModel, VerifySummary, SkippedGuarantee
+
+
+# ============================================================================
+# 内部小工具
+# ============================================================================
+
+def _run_test(guarantee: Guarantee, *, timeout: int = -1) -> VerifyModel:
+    """跑一条保证的测试，返回原始结果。timeout=-1 时回退到保证自带的 override。"""
+    effective_timeout = timeout if timeout != -1 else guarantee.timeout_override
+    return executor.verify_single(
+        guarantee.executor, guarantee.test, timeout=effective_timeout, return_model=True
+    )
+
+
+def _gate(provider: str, gid: str, guarantee: Guarantee) -> None:
+    """出生即绿门禁：跑测试，不过就抛 GuaranteeTestFailedError。"""
+    result = _run_test(guarantee)
+    if result.return_code != 0:
+        # pytest 将断言错误输出到 stdout，stderr 通常是 warnings
+        details = (result.stderr or "") + "\n" + (result.stdout or "")
+        raise GuaranteeTestFailedError(
+            target_file=provider, guarantee_path=gid, failure_info=details.strip()
+        )
+
+
+def _find_dependency(meta: FileMeta, symbol: str) -> Dependency | None:
+    """在 consumer meta 的 depends_on 里按 symbol 找依赖边。"""
+    for dep in meta.depends_on:
+        if dep.symbol == symbol:
+            return dep
+    return None
+
+
+# ============================================================================
+# Provider 侧：保证生命周期
+# ============================================================================
+
+def create_guarantee(
+    provider_meta: FileMeta,
+    provider: str,
+    gid: str,
+    *,
+    desc: str,
+    test: str,
+    executor_name: str,
+    heavy: int = 0,
+    timeout_override: int = -1,
+    disabled: bool = False,
+) -> Guarantee:
+    """在 provider 上新建一条具名保证。
+
+    默认出生即绿：当场跑测试，不过则拒绝。``disabled=True`` 则**跳过门禁**新建一条停用
+    占位保证(用于循环依赖 bootstrap：测试还过不了时先占住 id 与边，待两边就绪再 enable)。
+    停用保证是 born-green 的逃生口，必须靠 check_consistency 响亮报出、别让它静默留存。
+    """
+    if gid in provider_meta.provides:
+        raise GuaranteeDuplicatedError(target_file=provider, guarantee_path=gid)
+
+    guarantee = Guarantee(
+        desc=desc,
+        test=test,
+        executor=executor_name,
+        timeout_override=timeout_override,
+        heavy=heavy,
+        dependents=[],
+        disabled=disabled,
+    )
+    if not disabled:
+        _gate(provider, gid, guarantee)  # 先验证后落入模型；停用占位则不验证
+    provider_meta.provides[gid] = guarantee
+    return guarantee
+
+
+def update_guarantee(
+    provider_meta: FileMeta,
+    provider: str,
+    gid: str,
+    *,
+    desc: str | None = None,
+    test: str | None = None,
+    executor_name: str | None = None,
+    heavy: int | None = None,
+    timeout_override: int | None = None,
+) -> Guarantee:
+    """更新一条保证的元数据。只传想改的字段；若改动了测试/执行方式则重新跑门禁。"""
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+
+    # 是否动了「怎么验证」——动了就要重新证明出生即绿
+    runner_changed = (
+        (test is not None and test != guarantee.test)
+        or (executor_name is not None and executor_name != guarantee.executor)
+        or (timeout_override is not None and timeout_override != guarantee.timeout_override)
+    )
+
+    if desc is not None:
+        guarantee.desc = desc
+    if test is not None:
+        guarantee.test = test
+    if executor_name is not None:
+        guarantee.executor = executor_name
+    if heavy is not None:
+        guarantee.heavy = heavy
+    if timeout_override is not None:
+        guarantee.timeout_override = timeout_override
+
+    # 停用态下「换测试只换不跑」：runner 变了也不重证门禁——门禁等到 enable 时再补。
+    if runner_changed and not guarantee.disabled:
+        _gate(provider, gid, guarantee)
+
+    return guarantee
+
+
+def disable_guarantee(provider_meta: FileMeta, provider: str, gid: str) -> Guarantee:
+    """停用一条保证：置 disabled=True，id 与全部边(dependents/反向边)原样保留。
+
+    幂等：已停用再调无副作用。停用 ≠ 退休——它不删任何东西、不动依赖关系，只是让门禁与
+    批量 verify 暂缓执行它。用于重构窗口/在修保证：先 disable 守住边，改完测试再 enable。
+    """
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+    guarantee.disabled = True
+    return guarantee
+
+
+def enable_guarantee(provider_meta: FileMeta, provider: str, gid: str) -> Guarantee:
+    """恢复一条停用的保证：当场补跑门禁(born-green)，过了才真正置 disabled=False。
+
+    门禁不过则抛 GuaranteeTestFailedError 且**保持 disabled 不变**(enable 失败=仍停用)，
+    绝不把一条没验证过的保证悄悄转正。幂等：对已启用的保证调用 = 重证一次门禁。
+    """
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+    _gate(provider, gid, guarantee)  # 不过则抛错，下面这行不执行 ⇒ 仍是 disabled
+    guarantee.disabled = False
+    return guarantee
+
+
+def retire_guarantee(provider_meta: FileMeta, provider: str, gid: str) -> None:
+    """退休一条保证。退休保护：仍有 dependents 则拒绝（抛 GuaranteeHasDependentsError）。
+
+    系统不替使用者反射式删掉还有人依赖的保证；必须先沿依赖线修复/迁移 dependents。
+    """
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+
+    if guarantee.dependents:
+        raise GuaranteeHasDependentsError(
+            provider=provider, guarantee_id=gid, dependents=list(guarantee.dependents)
+        )
+
+    del provider_meta.provides[gid]
+
+
+# ============================================================================
+# Consumer 侧：依赖边（跨文件，双向写）
+# ============================================================================
+
+def add_dependency(
+    consumer_meta: FileMeta,
+    consumer: str,
+    provider_meta: FileMeta,
+    provider: str,
+    symbol_name: str,
+    gid: str | None = None,
+) -> None:
+    """登记 consumer 对 provider 的一条依赖。
+
+    - gid 为 None：symbol 级「免费依赖」——只在 consumer.depends_on 记一条 symbol 边，
+      不挂保证、无反向边。
+    - gid 非 None：行为级依赖——gid 必须已存在于 provider.provides（消费者不能凭空要求
+      新行为；要新行为先让 provider create_guarantee）。双向写：consumer 边挂上 gid，
+      provider 该保证的 dependents 追加 consumer。
+    """
+    symbol = f"{provider}:{symbol_name}"
+
+    # 保证 consumer 侧有这条 symbol 边
+    dep = _find_dependency(consumer_meta, symbol)
+    if dep is None:
+        dep = Dependency(symbol=symbol, guarantees=[])
+        consumer_meta.depends_on.append(dep)
+
+    if gid is None:
+        return  # 免费依赖，到此为止
+
+    if gid not in provider_meta.provides:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+
+    # 双向写（各自去重）
+    if gid not in dep.guarantees:
+        dep.guarantees.append(gid)
+    dependents = provider_meta.provides[gid].dependents
+    if consumer not in dependents:
+        dependents.append(consumer)
+
+
+def remove_dependency(
+    consumer_meta: FileMeta,
+    consumer: str,
+    provider_meta: FileMeta,
+    provider: str,
+    symbol_name: str,
+    gid: str | None = None,
+) -> None:
+    """撤销一条依赖（add_dependency 的逆操作，同样维护双向一致）。
+
+    - gid 非 None：只摘掉这一个保证依赖（consumer 边去掉 gid，provider 反向边去掉 consumer），
+      symbol 边若还挂着别的保证则保留。
+    - gid 为 None：整条 symbol 边连同它挂的所有保证一起撤销，并从各保证的 dependents 摘除 consumer。
+    """
+    symbol = f"{provider}:{symbol_name}"
+    dep = _find_dependency(consumer_meta, symbol)
+    if dep is None:
+        raise GuaranteeNotFoundError(target_file=consumer, guarantee_path=symbol)
+
+    def _detach(target_gid: str) -> None:
+        guarantee = provider_meta.provides.get(target_gid)
+        if guarantee and consumer in guarantee.dependents:
+            guarantee.dependents.remove(consumer)
+
+    if gid is None:
+        for g in list(dep.guarantees):
+            _detach(g)
+        consumer_meta.depends_on.remove(dep)
+        return
+
+    if gid in dep.guarantees:
+        dep.guarantees.remove(gid)
+    _detach(gid)
+    # symbol 边变空（无保证）后是否保留：保留——它仍是一条有效的免费 symbol 依赖。
+
+
+# ============================================================================
+# 读 / 反查
+# ============================================================================
+
+def list_provides(provider_meta: FileMeta) -> dict[str, Guarantee]:
+    """provider 提供的全部保证（含各自 dependents）。"""
+    return dict(provider_meta.provides)
+
+
+def list_depends_on(consumer_meta: FileMeta) -> list[Dependency]:
+    """consumer 声明的全部依赖边。"""
+    return list(consumer_meta.depends_on)
+
+
+def dependents_of(provider_meta: FileMeta, gid: str) -> list[str]:
+    """谁依赖 provider 的这条保证——O(1) 直接读反向边。"""
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file="<provider>", guarantee_path=gid)
+    return list(guarantee.dependents)
+
+
+# ============================================================================
+# 验证
+# ============================================================================
+
+def verify_provider(
+    provider_meta: FileMeta,
+    *,
+    auto_run_max_heavy: int = 0,
+    timeout: int = -1,
+) -> VerifySummary:
+    """批量验证 provider 提供的所有保证，按 heavy 阈值跳过并三桶汇总。
+
+    批量只跑 heavy <= auto_run_max_heavy 的；其余进 skipped 桶并被响亮报告。
+    门禁二元：green = failed 桶为空（skipped 不染红）。
+    """
+    summary = VerifySummary()
+    for gid, guarantee in provider_meta.provides.items():
+        if guarantee.disabled:
+            # 停用 = 缺席的另一种：不跑、不染红，进 skipped 并标 reason=disabled 响亮报出。
+            summary.skipped.append(
+                SkippedGuarantee(id=gid, heavy=guarantee.heavy, reason="disabled")
+            )
+            continue
+        if guarantee.heavy > auto_run_max_heavy:
+            summary.skipped.append(SkippedGuarantee(id=gid, heavy=guarantee.heavy))
+            continue
+        result = _run_test(guarantee, timeout=timeout)
+        summary.results[gid] = result
+        if result.return_code == 0:
+            summary.passed.append(gid)
+        else:
+            summary.failed.append(gid)
+    return summary
+
+
+def verify_guarantee(
+    provider_meta: FileMeta,
+    provider: str,
+    gid: str,
+    *,
+    timeout: int = -1,
+) -> VerifyModel:
+    """点名验证单条保证——无视 heavy 阈值，永远跑（你点了名就是要跑）。"""
+    guarantee = provider_meta.provides.get(gid)
+    if guarantee is None:
+        raise GuaranteeNotFoundError(target_file=provider, guarantee_path=gid)
+    return _run_test(guarantee, timeout=timeout)

gbc/app/i18n/__init__.py

@@ -0,0 +1,43 @@
+# 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 面向用户输出的多语言层。
+
+对外提供三件事:
+- `resolve_lang(...)`  语言判定:显式 lang > GBC_LANG > 系统 locale > 默认 en。
+- `t(key, **kw)`       短消息查表(catalog),按当前语言取串并做 str.format 填充。
+- `load_text(name)`    长文本(rules / init 引导)按当前语言整篇读出 Markdown 资源。
+
+设计取舍:短消息用**轻量 dict catalog**(见 catalog.py)而非 gettext——无编译步骤、
+随包走、透明易测;若将来规模变大可平滑迁移。
+"""
+from gbc.app.i18n.lang import (
+    DEFAULT_LANG,
+    supported_langs,
+    resolve_lang,
+    set_lang,
+    current_lang,
+)
+from gbc.app.i18n.translate import t, load_text, catalog_keys
+
+__all__ = [
+    "DEFAULT_LANG",
+    "supported_langs",
+    "resolve_lang",
+    "set_lang",
+    "current_lang",
+    "t",
+    "load_text",
+    "catalog_keys",
+]

gbc/app/i18n/lang.py

@@ -0,0 +1,88 @@
+# 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.
+
+"""语言判定 + **从文件自动发现受支持语言**。
+
+关键设计:受支持语言不硬编码,而是扫描资源文件推导——放一个 `catalog/ja.json`
+(以及可选的 `texts/*.ja.md`)就自动支持日语,无需改代码。
+
+判定优先级(高→低):显式 lang 参数 > 环境变量 GBC_LANG > 系统 locale > 默认 en。
+"""
+import locale
+import os
+from gbc.app.assets import I18N_CATALOG_DIR as _CATALOG_DIR
+
+DEFAULT_LANG = "en"
+
+# 进程内当前语言(命令入口解析一次后 set_lang 固定;库函数读 current_lang)。
+_current: str = DEFAULT_LANG
+
+
+def supported_langs() -> tuple[str, ...]:
+    """扫描 catalog 目录,把每个 `<lang>.json` 的文件名主干当作一门受支持语言。
+
+    永远包含 DEFAULT_LANG(en 必须存在,作为兜底)。结果排序稳定,en 置首。
+    """
+    langs: set[str] = {DEFAULT_LANG}
+    if _CATALOG_DIR.is_dir():
+        for f in _CATALOG_DIR.glob("*.json"):
+            langs.add(f.stem)
+    ordered = [DEFAULT_LANG] + sorted(langs - {DEFAULT_LANG})
+    return tuple(ordered)
+
+
+def normalize(raw: str | None) -> str | None:
+    """把形如 zh_CN.UTF-8 / zh-Hans / EN 的原始值归一到受支持码;不支持则 None。"""
+    if not raw:
+        return None
+    low = raw.strip().lower().replace("_", "-")
+    primary = low.split("-", 1)[0].split(".", 1)[0]
+    if primary in supported_langs():
+        return primary
+    return None
+
+
+def resolve_lang(explicit: str | None = None) -> str:
+    """按优先级判定语言,永远返回一个受支持码(兜底 DEFAULT_LANG)。
+
+    显式 explicit > 环境变量 GBC_LANG > 系统 locale > DEFAULT_LANG。
+    """
+    for candidate in (explicit, os.environ.get("GBC_LANG")):
+        norm = normalize(candidate)
+        if norm:
+            return norm
+
+    try:
+        sys_lang, _ = locale.getlocale()
+    except (ValueError, TypeError):
+        sys_lang = None
+    if not sys_lang:
+        sys_lang = os.environ.get("LANG") or os.environ.get("LC_ALL")
+    norm = normalize(sys_lang)
+    if norm:
+        return norm
+
+    return DEFAULT_LANG
+
+
+def set_lang(lang: str) -> str:
+    """固定进程内当前语言(通常在命令入口解析后调用一次)。返回归一后的实际语言。"""
+    global _current
+    _current = normalize(lang) or DEFAULT_LANG
+    return _current
+
+
+def current_lang() -> str:
+    """读取进程内当前语言。"""
+    return _current

gbc/app/i18n/translate.py

@@ -0,0 +1,80 @@
+# 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.
+
+"""翻译取值:短消息 t() + 长文本 load_text()。
+
+短消息 catalog 从 `catalog/<lang>.json` 按需加载(带缓存);长文本从
+`texts/<name>.<lang>.md` 整篇读出。两者都在缺当前语言时回退 DEFAULT_LANG。
+放文件即加语言,无需改代码。
+"""
+import json
+
+from gbc.app.assets import I18N_CATALOG_DIR as _CATALOG_DIR, I18N_TEXTS_DIR as _TEXTS_DIR
+from gbc.app.i18n.lang import DEFAULT_LANG, current_lang
+
+# 每语言 catalog 缓存:lang -> {key: str}
+_catalog_cache: dict[str, dict[str, str]] = {}
+
+
+def _load_catalog(lang: str) -> dict[str, str]:
+    if lang not in _catalog_cache:
+        path = _CATALOG_DIR / f"{lang}.json"
+        if path.exists():
+            try:
+                _catalog_cache[lang] = json.loads(path.read_text(encoding="utf-8"))
+            except (ValueError, OSError):
+                _catalog_cache[lang] = {}
+        else:
+            _catalog_cache[lang] = {}
+    return _catalog_cache[lang]
+
+
+def t(key: str, *, lang: str | None = None, **kw) -> str:
+    """取短消息:按 key 查当前语言 catalog,缺失回退 DEFAULT_LANG,再缺回退 key 本身。
+
+    串内 {name} 占位用 **kw 填充;填充缺参时不炸,原样保留。
+    """
+    use = lang or current_lang()
+    text = _load_catalog(use).get(key)
+    if text is None and use != DEFAULT_LANG:
+        text = _load_catalog(DEFAULT_LANG).get(key)
+    if text is None:
+        return key
+    if kw:
+        try:
+            return text.format(**kw)
+        except (KeyError, IndexError):
+            return text
+    return text
+
+
+def load_text(name: str, *, lang: str | None = None) -> str:
+    """整篇读出长文本资源(rules / init 引导等)。
+
+    找 <name>.<当前语言>.md;缺则回退 <name>.<DEFAULT_LANG>.md;再缺抛 FileNotFoundError。
+    """
+    use = lang or current_lang()
+    candidate = _TEXTS_DIR / f"{name}.{use}.md"
+    if not candidate.exists():
+        candidate = _TEXTS_DIR / f"{name}.{DEFAULT_LANG}.md"
+    if not candidate.exists():
+        raise FileNotFoundError(
+            f"i18n long-text resource not found: {name} (lang={use}, dir={_TEXTS_DIR})"
+        )
+    return candidate.read_text(encoding="utf-8")
+
+
+def catalog_keys(lang: str | None = None) -> set[str]:
+    """某语言 catalog 的全部键(测试/校验漏译用)。默认 DEFAULT_LANG。"""
+    return set(_load_catalog(lang or DEFAULT_LANG).keys())

gbc/app/intent/__init__.py

@@ -0,0 +1,20 @@
+# 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.md)子系统。
+
+与保证引擎(core + interface)对称:`base` 是唯一 IO/编排点(路径解析、gbc.md
+读写、父子投影、一致性、整树读写);`cli`/`editor` 都是薄表面,只调 base、不碰磁盘。
+gbc.md 解析单源复用 gbc.app.utils.gbc_md。
+"""