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

gbc/app/intent/base.py

@@ -0,0 +1,308 @@
+# 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 总线 —— 唯一碰 gbc.md 磁盘的地方。
+
+对称于 interface.base(保证引擎的总线):
+- 路径解析(.gbc 镜像层)、单文档读写、父子意图单源投影都收在这里;
+- 单文档操作(set_intent/set_constraints/set_file/rm_entry/show);
+- 整树读写(read_tree/write_tree)供 web 编辑器用;
+- 全树一致性(check/sync/migrate)。
+
+上层表面(cli / editor)只调本模块,绝不自己碰磁盘或解析路径。
+gbc.md 解析单源复用 gbc.app.utils.gbc_md。
+"""
+from pathlib import Path
+
+from gbc.app.utils import gbc_md as gf
+from gbc.app.models.errors import IntentDocError
+
+GBC_FILE = "gbc.md"
+
+
+# ---- 路径解析(.gbc 镜像层) --------------------------------------------------
+
+def resolve_gbc(root_str: str) -> tuple[Path, str]:
+    """把用户给的路径映射成 (gbc_root, project_name)。
+
+    `.gbc` 镜像层对树是隐藏的:展示的根是**项目**目录,内容始终落在 <project>/.gbc/ 下。
+      - 路径以 `.gbc` 结尾 -> gbc_root = 该路径,        project = 其父目录名
+      - 否则               -> gbc_root = 路径/.gbc,     project = 该路径名
+    因此加载 `…/proj` 与 `…/proj/.gbc` 行为一致。
+    """
+    p = Path(root_str).expanduser().resolve()
+    if p.name == ".gbc":
+        return p, p.parent.name
+    return p / ".gbc", p.name
+
+
+def _norm(rel: str) -> str:
+    """规范化文件夹相对路径:去首尾斜杠;'.' 与 '' 都表示根。"""
+    rel = (rel or "").strip().strip("/")
+    return "" if rel in ("", ".") else rel
+
+
+def _doc_path(gbc_root: Path, rel: str) -> Path:
+    return (gbc_root / rel / GBC_FILE) if rel else (gbc_root / GBC_FILE)
+
+
+def _parent_name(rel: str) -> tuple[str | None, str | None]:
+    """(父文件夹 rel, 本文件夹名)。根 -> (None, None)。"""
+    rel = _norm(rel)
+    if not rel:
+        return None, None
+    parts = rel.split("/")
+    return "/".join(parts[:-1]), parts[-1]
+
+
+def _find_entry(doc: gf.ParsedDoc, name: str) -> gf.Entry | None:
+    key = name.rstrip("/")
+    for e in doc.entries:
+        if e.name.rstrip("/") == key:
+            return e
+    return None
+
+
+# ---- 单文档读写(唯一 IO 点) ------------------------------------------------
+
+def read_doc(gbc_root: Path, rel: str) -> gf.ParsedDoc:
+    p = _doc_path(gbc_root, rel)
+    return gf.parse(p.read_text(encoding="utf-8")) if p.exists() else gf.ParsedDoc()
+
+
+def write_doc(gbc_root: Path, rel: str, doc: gf.ParsedDoc) -> Path:
+    p = _doc_path(gbc_root, rel)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(gf.serialize(doc.intent, doc.constraints, doc.entries), encoding="utf-8")
+    return p
+
+
+# ---- 单文档操作 -------------------------------------------------------------
+
+def set_intent(gbc_root: Path, rel: str, text: str) -> list[Path]:
+    """设文件夹意图,并单源投影到父文档对应的 `## <name>/` 条目。"""
+    rel = _norm(rel)
+    doc = read_doc(gbc_root, rel)
+    doc.intent = text
+    written = [write_doc(gbc_root, rel, doc)]
+
+    parent_rel, name = _parent_name(rel)
+    if name is not None:  # 非根:把意图投影到父条目(单一事实源)
+        pdoc = read_doc(gbc_root, parent_rel)
+        entry = _find_entry(pdoc, name)
+        if entry is None:
+            pdoc.entries.append(gf.Entry(name=f"{name}/", is_dir=True, desc=text))
+        else:
+            entry.name = f"{name}/"
+            entry.is_dir = True
+            entry.desc = text
+        written.append(write_doc(gbc_root, parent_rel, pdoc))
+    return written
+
+
+def set_constraints(gbc_root: Path, rel: str, text: str) -> list[Path]:
+    rel = _norm(rel)
+    doc = read_doc(gbc_root, rel)
+    doc.constraints = text
+    return [write_doc(gbc_root, rel, doc)]
+
+
+def set_file(gbc_root: Path, rel: str, name: str, desc: str) -> list[Path]:
+    """新增/更新一个文件条目(name 不带斜杠)。"""
+    if name.rstrip().endswith("/"):
+        raise IntentDocError("exc.doc_filename_slash", name=name)
+    rel = _norm(rel)
+    doc = read_doc(gbc_root, rel)
+    entry = _find_entry(doc, name)
+    if entry is not None and entry.is_dir:
+        raise IntentDocError("exc.doc_name_is_folder", name=name)
+    if entry is None:
+        doc.entries.append(gf.Entry(name=name, is_dir=False, desc=desc))
+    else:
+        entry.desc = desc
+    return [write_doc(gbc_root, rel, doc)]
+
+
+def rm_entry(gbc_root: Path, rel: str, name: str) -> list[Path]:
+    """从文件夹文档里删掉一个条目(只改文档,不删盘上文件/子目录,留给 git 复核)。"""
+    rel = _norm(rel)
+    doc = read_doc(gbc_root, rel)
+    before = len(doc.entries)
+    key = name.rstrip("/")
+    doc.entries = [e for e in doc.entries if e.name.rstrip("/") != key]
+    if len(doc.entries) == before:
+        raise IntentDocError("exc.doc_entry_not_found", name=name)
+    return [write_doc(gbc_root, rel, doc)]
+
+
+def show(gbc_root: Path, rel: str) -> str:
+    rel = _norm(rel)
+    p = _doc_path(gbc_root, rel)
+    if not p.exists():
+        return f"(无 gbc.md) {p}"
+    doc = read_doc(gbc_root, rel)
+    lines = [f"# 文件夹: {rel or '(根)'}  -> {p}", "", "[意图]", doc.intent or "(空)"]
+    if doc.constraints:
+        lines += ["", "[内部约束]", doc.constraints]
+    lines += ["", "[文件]"]
+    lines += [f"  {'📁' if e.is_dir else '📄'} {e.name}: {e.desc}" for e in doc.entries] or ["  (无)"]
+    return "\n".join(lines)
+
+
+# ---- 整树读写(供 web 编辑器) -----------------------------------------------
+
+def empty_tree(gbc_root: Path) -> dict:
+    return {"name": gbc_root.name, "path": "", "intent": "", "constraints": "", "entries": []}
+
+
+def read_tree(abs_dir: Path, rel: str = "") -> dict:
+    """把一个 .gbc 目录读成嵌套 dict 树(供前端编辑)。条目类型由名字尾部 '/' 推导。"""
+    md = abs_dir / GBC_FILE
+    doc = gf.parse(md.read_text(encoding="utf-8")) if md.exists() else gf.ParsedDoc()
+
+    entries: list[dict] = []
+    seen_dirs: set[str] = set()
+    for e in doc.entries:
+        if not e.is_dir:
+            entries.append({"name": e.name, "desc": e.desc})
+            continue
+        child_name = e.name.rstrip("/")
+        seen_dirs.add(child_name)
+        child_abs = abs_dir / child_name
+        child_rel = f"{rel}/{child_name}".lstrip("/") if rel else child_name
+        if (child_abs / GBC_FILE).exists():
+            child = read_tree(child_abs, child_rel)  # 子自己的 gbc.md 是权威
+        else:
+            child = {"name": child_name, "path": child_rel,
+                     "intent": e.desc, "constraints": "", "entries": []}
+        entries.append({"name": e.name, "child": child})
+
+    # 有 gbc.md 但父条目没引用的子文件夹,也一并浮现
+    for sub in sorted(p for p in abs_dir.iterdir() if p.is_dir() and (p / GBC_FILE).exists()):
+        if sub.name in seen_dirs:
+            continue
+        child_rel = f"{rel}/{sub.name}".lstrip("/") if rel else sub.name
+        entries.append({"name": f"{sub.name}/", "child": read_tree(sub, child_rel)})
+
+    return {"name": abs_dir.name, "path": rel,
+            "intent": doc.intent, "constraints": doc.constraints, "entries": entries}
+
+
+def _is_dir_name(name: str) -> bool:
+    return name.rstrip().endswith("/")
+
+
+def write_tree(node_dir: Path, node: dict, written: list[str] | None = None) -> list[str]:
+    """把嵌套 dict 树写回文件系统。目标目录由树结构(父目录 + 条目名)推导,
+    改名即写到新位置——绝不信任存储的 path。"""
+    if written is None:
+        written = []
+    node_dir.mkdir(parents=True, exist_ok=True)
+
+    gf_entries: list[gf.Entry] = []
+    for e in node["entries"]:
+        if not e["name"].strip():
+            continue  # 跳过空白幽灵行
+        if _is_dir_name(e["name"]):
+            child = e.get("child") or {}
+            # 单一事实源:父条目文本就是子的意图
+            gf_entries.append(gf.Entry(name=e["name"], is_dir=True, desc=child.get("intent", "")))
+        else:
+            gf_entries.append(gf.Entry(name=e["name"], is_dir=False, desc=e.get("desc", "")))
+
+    text = gf.serialize(node["intent"], node.get("constraints", ""), gf_entries)
+    (node_dir / GBC_FILE).write_text(text, encoding="utf-8")
+    written.append(str(node_dir / GBC_FILE))
+
+    for e in node["entries"]:
+        if e["name"].strip() and _is_dir_name(e["name"]) and e.get("child"):
+            child_dir = node_dir / e["name"].rstrip().rstrip("/")
+            write_tree(child_dir, e["child"], written)
+    return written
+
+
+# ---- 全树一致性 -------------------------------------------------------------
+
+def check(gbc_root: Path) -> tuple[list[str], list[str]]:
+    """全树一致性体检。返回 (errors, notes):
+
+    errors = DRIFT(子有 gbc.md 且其意图与父条目描述不一致) / ORPHAN(子有 gbc.md 但父未登记);
+    notes  = STUB(父登记了子文件夹条目但子无 gbc.md)——叶子文件夹的正常状态,仅提示。
+    """
+    errors: list[str] = []
+    notes: list[str] = []
+    if not gbc_root.exists():
+        return [f"(.gbc 不存在: {gbc_root})"], []
+
+    for md in sorted(gbc_root.rglob(GBC_FILE)):
+        rel = md.parent.relative_to(gbc_root).as_posix()
+        rel = "" if rel == "." else rel
+        doc = gf.parse(md.read_text(encoding="utf-8"))
+        for e in doc.entries:
+            if not e.is_dir:
+                continue
+            child_rel = f"{rel}/{e.name.rstrip('/')}".lstrip("/")
+            child_md = gbc_root / child_rel / GBC_FILE
+            if not child_md.exists():
+                notes.append(f"[STUB] {rel or '(根)'} 的条目 '{e.name}' 没有对应 gbc.md(叶子文件夹?)")
+                continue
+            child_intent = gf.parse(child_md.read_text(encoding="utf-8")).intent.strip()
+            if child_intent != (e.desc or "").strip():
+                errors.append(f"[DRIFT] '{child_rel}' 的意图 与 父文档条目描述 不一致")
+
+        parent_rel, name = _parent_name(rel)
+        if name is not None:
+            pmd = gbc_root / (parent_rel or "") / GBC_FILE
+            if not pmd.exists():
+                errors.append(f"[ORPHAN] '{rel}' 有 gbc.md 但父 '{parent_rel or '(根)'}' 没有 gbc.md")
+            elif _find_entry(gf.parse(pmd.read_text(encoding="utf-8")), name) is None:
+                errors.append(f"[ORPHAN] '{rel}' 有 gbc.md 但父文档未登记 '{name}/' 条目")
+    return errors, notes
+
+
+def sync(gbc_root: Path) -> list[str]:
+    """确定性修复 DRIFT/ORPHAN:把每个有 gbc.md 的子文件夹的意图(唯一事实源)重投影到
+    其父文档的 `## <name>/` 条目(缺则补、不一致则覆盖)。只动父条目,不碰子意图。"""
+    fixed: list[str] = []
+    for md in sorted(gbc_root.rglob(GBC_FILE)):
+        rel = md.parent.relative_to(gbc_root).as_posix()
+        rel = "" if rel == "." else rel
+        parent_rel, name = _parent_name(rel)
+        if name is None:
+            continue
+        child_intent = gf.parse(md.read_text(encoding="utf-8")).intent
+        pdoc = read_doc(gbc_root, parent_rel)
+        entry = _find_entry(pdoc, name)
+        if entry is None:
+            pdoc.entries.append(gf.Entry(name=f"{name}/", is_dir=True, desc=child_intent))
+            write_doc(gbc_root, parent_rel, pdoc)
+            fixed.append(f"+ 补登记 '{rel}' 到父 '{parent_rel or '(根)'}'")
+        elif (entry.desc or "").strip() != child_intent.strip():
+            entry.name, entry.is_dir, entry.desc = f"{name}/", True, child_intent
+            write_doc(gbc_root, parent_rel, pdoc)
+            fixed.append(f"~ 重投影 '{rel}' 意图到父 '{parent_rel or '(根)'}'")
+    return fixed
+
+
+def migrate(gbc_root: Path) -> list[str]:
+    """把所有 gbc.md parse→serialize 重写一遍,升级到带 `# 文件` 段的新格式。"""
+    changed: list[str] = []
+    for md in sorted(gbc_root.rglob(GBC_FILE)):
+        old = md.read_text(encoding="utf-8")
+        doc = gf.parse(old)
+        new = gf.serialize(doc.intent, doc.constraints, doc.entries)
+        if new != old:
+            md.write_text(new, encoding="utf-8")
+            changed.append(str(md))
+    return changed

gbc/app/intent/cli.py

@@ -0,0 +1,124 @@
+# 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)的 CLI 表面 —— 薄。
+
+`gbc doc <command>`。只做参数收集 → 调 intent.base → 渲染;不碰磁盘、不解析路径。
+"""
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from gbc.app.intent import base
+
+doc_app = typer.Typer(help="cli.doc.help")
+console = Console()
+
+
+def _gbc_root(project: Optional[str]):
+    """确定作用的项目根:显式 project > 当前 GBC 目标项目。"""
+    if project:
+        gbc_root, _ = base.resolve_gbc(project)
+        return gbc_root
+    from gbc.app.config.project import get_current_project
+    gbc_root, _ = base.resolve_gbc(str(get_current_project()))
+    return gbc_root
+
+
+@doc_app.command("show")
+def doc_show(
+    folder: str = typer.Argument("", help="项目相对文件夹路径，根用空串"),
+    project: Optional[str] = typer.Option(None, "--project", "-C", help="目标项目根；省略则用当前项目"),
+):
+    """查看文件夹的意图 / 约束 / 条目。"""
+    print(base.show(_gbc_root(project), folder))
+
+
+@doc_app.command("set-intent")
+def doc_set_intent(
+    folder: str = typer.Argument(...),
+    text: str = typer.Argument(...),
+    project: Optional[str] = typer.Option(None, "--project", "-C"),
+):
+    """设文件夹意图（自动单源投影到父文档条目）。"""
+    for p in base.set_intent(_gbc_root(project), folder, text):
+        console.print(f"[green]written:[/green] {p}")
+
+
+@doc_app.command("set-constraints")
+def doc_set_constraints(
+    folder: str = typer.Argument(...),
+    text: str = typer.Argument(...),
+    project: Optional[str] = typer.Option(None, "--project", "-C"),
+):
+    """设文件夹的内部约束（只活在本地，不冒泡到父节点）。"""
+    for p in base.set_constraints(_gbc_root(project), folder, text):
+        console.print(f"[green]written:[/green] {p}")
+
+
+@doc_app.command("set-file")
+def doc_set_file(
+    folder: str = typer.Argument(...),
+    name: str = typer.Argument(...),
+    desc: str = typer.Argument(...),
+    project: Optional[str] = typer.Option(None, "--project", "-C"),
+):
+    """新增/更新一个文件条目（name 不带 /）。"""
+    for p in base.set_file(_gbc_root(project), folder, name, desc):
+        console.print(f"[green]written:[/green] {p}")
+
+
+@doc_app.command("rm-entry")
+def doc_rm_entry(
+    folder: str = typer.Argument(...),
+    name: str = typer.Argument(...),
+    project: Optional[str] = typer.Option(None, "--project", "-C"),
+):
+    """删条目（只改文档，不删盘上文件，留给 git 复核）。"""
+    for p in base.rm_entry(_gbc_root(project), folder, name):
+        console.print(f"[green]written:[/green] {p}")
+
+
+@doc_app.command("check")
+def doc_check(project: Optional[str] = typer.Option(None, "--project", "-C")):
+    """全树意图一致性体检（DRIFT/ORPHAN 为错误，STUB 为提示）。"""
+    errors, notes = base.check(_gbc_root(project))
+    for e in errors:
+        console.print(f"[red]{e}[/red]")
+    for n in notes:
+        console.print(f"[dim]{n}[/dim]")
+    if errors:
+        raise typer.Exit(code=1)
+    console.print("[green]✔ intent tree consistent[/green]")
+
+
+@doc_app.command("sync")
+def doc_sync(project: Optional[str] = typer.Option(None, "--project", "-C")):
+    """确定性修复 DRIFT/ORPHAN：把子意图重投影到父条目。"""
+    fixed = base.sync(_gbc_root(project))
+    for f in fixed:
+        console.print(f"[green]{f}[/green]")
+    if not fixed:
+        console.print("[dim]nothing to sync[/dim]")
+
+
+@doc_app.command("migrate")
+def doc_migrate(project: Optional[str] = typer.Option(None, "--project", "-C")):
+    """把所有 gbc.md 升级到最新格式。"""
+    changed = base.migrate(_gbc_root(project))
+    for c in changed:
+        console.print(f"[green]migrated:[/green] {c}")
+    if not changed:
+        console.print("[dim]all up to date[/dim]")

gbc/app/intent/editor.py

@@ -0,0 +1,93 @@
+# 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.
+
+"""意图编辑器的 web 表面 —— 薄。
+
+只做 HTTP 收发 + 静态资源;所有 gbc.md 的解析/读写/整树读写都调 intent.base,
+本模块不自己解析路径、不自己拼 gbc.md。`gbc editor up` 调 run_editor()。
+"""
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlparse, parse_qs
+
+from gbc.app.assets import EDITOR_FRONTEND_DIR as FRONTEND_DIR
+from gbc.app.intent import base
+
+# 前端预填 + 自动加载的默认项目路径(经 --root 设定)。
+DEFAULT_ROOT = ""
+
+
+class Handler(BaseHTTPRequestHandler):
+    def _send(self, code: int, body: bytes, ctype: str) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _json(self, code: int, obj) -> None:
+        self._send(code, json.dumps(obj, ensure_ascii=False).encode("utf-8"),
+                   "application/json; charset=utf-8")
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/api/config":
+            return self._json(200, {"root": DEFAULT_ROOT})
+        if parsed.path == "/api/tree":
+            qs = parse_qs(parsed.query)
+            gbc_root, proj_name = base.resolve_gbc((qs.get("root") or [""])[0])
+            if gbc_root.exists() and not gbc_root.is_dir():
+                return self._json(404, {"error": f"not a directory: {gbc_root}"})
+            # 路径不存在也 OK:回一棵空树从头开始
+            tree = base.read_tree(gbc_root) if gbc_root.exists() else base.empty_tree(gbc_root)
+            tree["name"] = proj_name           # 展示项目,而非 .gbc 层
+            return self._json(200, tree)
+        # 静态资源:根路径给 index.html,或 frontend 下任意文件
+        name = "index.html" if parsed.path == "/" else parsed.path.lstrip("/")
+        fpath = (FRONTEND_DIR / name).resolve()
+        if FRONTEND_DIR in fpath.parents and fpath.is_file():
+            ctype = "text/html; charset=utf-8" if fpath.suffix == ".html" else "text/plain"
+            return self._send(200, fpath.read_bytes(), ctype)
+        return self._json(404, {"error": "not found"})
+
+    def do_POST(self) -> None:
+        if urlparse(self.path).path != "/api/tree":
+            return self._json(404, {"error": "not found"})
+        length = int(self.headers.get("Content-Length", 0))
+        try:
+            req = json.loads(self.rfile.read(length) or b"{}")
+            gbc_root, _ = base.resolve_gbc(req["root"])
+            if gbc_root.exists() and not gbc_root.is_dir():
+                return self._json(404, {"error": f"not a directory: {gbc_root}"})
+            gbc_root.mkdir(parents=True, exist_ok=True)  # 首次保存时建 <project>/.gbc
+            written = base.write_tree(gbc_root, req["tree"])
+            return self._json(200, {"written": written, "count": len(written)})
+        except Exception as exc:  # noqa: BLE001 - 报回客户端
+            return self._json(500, {"error": str(exc)})
+
+    def log_message(self, fmt, *args):  # 静默控制台
+        return
+
+
+def run_editor(host: str = "127.0.0.1", port: int = 8765, root: str = "") -> None:
+    """启动意图编辑器 web 服务(常驻,Ctrl-C 退出)。root 为可选默认项目路径。"""
+    global DEFAULT_ROOT
+    if root:
+        DEFAULT_ROOT = str(Path(root).expanduser())
+    srv = ThreadingHTTPServer((host, port), Handler)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        srv.shutdown()

gbc/app/interface/__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.
+