1panel-toolkit 0.3.0__py3-none-any.whl

p1toolkit/evidence.py

@@ -0,0 +1,523 @@
+"""Audit a generation spec against the decision ledger.
+
+``p1 resolve`` answers the ten generation decisions from upstream evidence and
+refuses to guess the blocking ones. The generator used to accept whatever spec
+it was handed, so a draft carrying ``"status": "missing"`` still became a
+package: it installs, then loses data on upgrade or never answers on its port.
+
+This module carries resolve's discipline into ``p1 gen``. It reads the ledger
+resolve wrote (``spec["decisions"]``), cross-checks it against what the spec is
+about to generate, and reports findings per decision id. A blocking finding
+stops the build unless the spec acknowledges the decision (``acknowledged``)
+or the caller explicitly allows unresolved evidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from . import rules
+from .report import FAIL, INFO, WARN
+
+EVIDENCED = "evidenced"
+INFERRED = "inferred"
+MISSING = "missing"
+
+# Supplied by the generator or the panel, never by the application: these never
+# need a D01/D02 evidence entry of their own.
+GENERATED_ENV_KEYS = {"TZ", "CONTAINER_NAME"}
+
+# The ledger itself, rather than one of the ten decisions.
+LEDGER = "ledger"
+
+
+@dataclass(frozen=True)
+class Finding:
+    decision: str
+    level: str
+    message: str
+    hint: str = ""
+
+    def render(self) -> str:
+        line = f"{self.level.upper():4s} {self.decision:<6s} {self.message}"
+        if self.hint:
+            line += f"\n            → {self.hint}"
+        return line
+
+
+@dataclass
+class Audit:
+    findings: list[Finding] = field(default_factory=list)
+    ledger: dict[str, dict[str, Any]] = field(default_factory=dict)
+    acknowledged: dict[str, str] = field(default_factory=dict)
+    allowed_unresolved: bool = False
+
+    def add(self, decision: str, level: str, message: str, hint: str = "") -> None:
+        self.findings.append(Finding(decision, level, message, hint))
+
+    @property
+    def failures(self) -> list[Finding]:
+        return [item for item in self.findings if item.level == FAIL]
+
+    @property
+    def warnings(self) -> list[Finding]:
+        return [item for item in self.findings if item.level == WARN]
+
+    @property
+    def ok(self) -> bool:
+        return not self.failures
+
+    @property
+    def blocked_decisions(self) -> list[str]:
+        return list(dict.fromkeys(item.decision for item in self.failures))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "has_ledger": bool(self.ledger),
+            "allowed_unresolved": self.allowed_unresolved,
+            "acknowledged": dict(self.acknowledged),
+            "decisions": {
+                key: {
+                    "status": value.get("status"),
+                    "question": value.get("question"),
+                    "answer": value.get("answer"),
+                }
+                for key, value in sorted(self.ledger.items())
+            },
+            "findings": [asdict(item) for item in self.findings],
+            "counts": {
+                "fail": len(self.failures),
+                "warn": len(self.warnings),
+                "info": len([i for i in self.findings if i.level == INFO]),
+            },
+        }
+
+    def render(self, indent: str = "  ") -> str:
+        if not self.findings:
+            return f"{indent}OK  没有需要人工确认的证据缺口"
+        ordered = sorted(self.findings, key=lambda item: (item.level != FAIL, item.decision))
+        lines: list[str] = []
+        for item in ordered:
+            lines.extend(indent + row for row in item.render().splitlines())
+        counts = self.to_dict()["counts"]
+        lines.append(
+            f"{indent}-> 证据审计: {counts['fail']} fail, {counts['warn']} warn, "
+            f"{counts['info']} info"
+        )
+        return "\n".join(lines)
+
+    def violations(self) -> str:
+        """The message that stops the build, one line per blocking decision."""
+        lines = [
+            "生成前证据审计没有通过，以下决策缺证据或与 spec 不一致；",
+            "猜一个默认值会让包装上就出问题，所以这里停下来：",
+            "",
+        ]
+        for item in self.failures:
+            lines.append(item.render())
+        lines += [
+            "",
+            "三条出路：补上游证据后重跑 `p1 resolve`；把答案写进 spec；",
+            '或者在 spec 里写 "acknowledged": {"D03": "为什么可以不挂载"} 明确承担这个决定。',
+            "确知自己在做什么时，也可以用 `p1 gen --allow-unresolved` 强行生成。",
+        ]
+        return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------
+# ledger helpers
+# --------------------------------------------------------------------------
+
+
+def ledger_of(spec: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    raw = spec.get("decisions")
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        str(key).upper(): value
+        for key, value in raw.items()
+        if isinstance(value, dict)
+    }
+
+
+def _answer_values(entry: dict[str, Any] | None) -> list[str]:
+    """Split a ledger answer back into its values.
+
+    ``resolve`` joins them with ", " and truncates long lists with "…（共 N 项）".
+    """
+    if not entry:
+        return []
+    answer = str(entry.get("answer") or "").split("…")[0]
+    return [part.strip() for part in answer.split(",") if part.strip()]
+
+
+def _status(ledger: dict[str, dict[str, Any]], decision: str) -> str:
+    entry = ledger.get(decision) or {}
+    return str(entry.get("status") or "").lower()
+
+
+def _answer_text(entry: dict[str, Any] | None) -> str:
+    return str((entry or {}).get("answer") or "—")
+
+
+def _image_repo(image: str) -> str:
+    """``docker.io/library/nginx:1.27-alpine`` -> ``nginx``."""
+    value = str(image).strip().split("@", 1)[0]
+    head, _, tail = value.rpartition("/")
+    last = tail.split(":", 1)[0]
+    value = f"{head}/{last}" if head else last
+    parts = value.split("/")
+    if len(parts) > 1 and ("." in parts[0] or ":" in parts[0] or parts[0] == "localhost"):
+        parts = parts[1:]
+    if len(parts) > 1 and parts[0] == "library":
+        parts = parts[1:]
+    return "/".join(parts).lower()
+
+
+def _mount_targets(service: dict[str, Any]) -> list[str]:
+    mounts = service.get("mounts")
+    if isinstance(mounts, list) and mounts:
+        targets = [
+            str(item["target"])
+            for item in mounts
+            if isinstance(item, dict) and item.get("target")
+        ]
+        if targets:
+            return targets
+    if service.get("mount_targets"):
+        return [str(item) for item in service["mount_targets"]]
+    if service.get("mount_target"):
+        return [str(service["mount_target"])]
+    return []
+
+
+def _mount_host(service: dict[str, Any]) -> str:
+    host = service.get("mount_host")
+    if host:
+        return str(host)
+    hosts = service.get("mount_hosts")
+    if isinstance(hosts, list) and hosts:
+        return str(hosts[0])
+    return ""
+
+
+# --------------------------------------------------------------------------
+# checks
+# --------------------------------------------------------------------------
+
+
+def _audit_ledger(audit: Audit) -> None:
+    if not audit.ledger:
+        audit.add(
+            LEDGER,
+            INFO,
+            "spec 没有 decisions 账本（不是 `p1 resolve` 产出的），只做结构性检查",
+            "用 `p1 resolve <仓库> --out <目录>` 生成带证据的 draft-spec.json 更稳妥",
+        )
+        return
+
+    for definition in rules.decisions():
+        decision_id = str(definition.get("id") or "")
+        question = str(definition.get("question") or "")
+        blocking = bool(definition.get("blocking"))
+        entry = audit.ledger.get(decision_id)
+        if entry is None:
+            audit.add(decision_id, WARN, f"账本里没有 {decision_id} {question}")
+            continue
+
+        status = str(entry.get("status") or "").lower()
+        reason = audit.acknowledged.get(decision_id)
+        if status == MISSING:
+            if reason:
+                audit.add(
+                    decision_id,
+                    INFO,
+                    f"{decision_id} {question} 无上游证据，已按 spec 的 acknowledged 继续：{reason}",
+                )
+            elif blocking:
+                audit.add(
+                    decision_id,
+                    FAIL,
+                    f"{decision_id} {question} 没有上游证据",
+                    f"补证据，或在 spec 里写 \"acknowledged\": "
+                    f"{{\"{decision_id}\": \"理由\"}}；{definition.get('if_unknown') or ''}",
+                )
+            else:
+                audit.add(
+                    decision_id,
+                    WARN,
+                    f"{decision_id} {question} 无上游证据，"
+                    f"按 if_unknown 处理：{definition.get('if_unknown') or '—'}",
+                )
+        elif status == INFERRED:
+            answer = entry.get("answer") or "—"
+            if blocking:
+                audit.add(
+                    decision_id,
+                    WARN,
+                    f"{decision_id} {question} 只有间接证据（{answer}），生成前请人工确认",
+                )
+            else:
+                audit.add(
+                    decision_id,
+                    INFO,
+                    f"{decision_id} {question} 为间接证据：{answer}",
+                )
+        elif status != EVIDENCED:
+            audit.add(
+                decision_id,
+                WARN,
+                f"账本里的 {decision_id}.status={entry.get('status')!r} 不是 "
+                "evidenced / inferred / missing 之一",
+            )
+
+
+def _audit_services(audit: Audit, spec: dict[str, Any]) -> None:
+    services = spec.get("services")
+    if not isinstance(services, list) or not services:
+        return
+
+    d03 = _answer_values(audit.ledger.get("D03"))
+    d05 = _answer_values(audit.ledger.get("D05"))
+    d06 = _answer_values(audit.ledger.get("D06"))
+
+    for index, service in enumerate(services):
+        if not isinstance(service, dict):
+            continue
+        name = str(service.get("name") or f"services[{index}]")
+        image = str(service.get("image") or "").strip()
+        targets = _mount_targets(service)
+        host = _mount_host(service)
+        port = service.get("container_port")
+
+        # D06 — the image, and whether it still matches its evidence.
+        if not image:
+            # The ledger check may already have failed D06; say it once, then
+            # keep this as context instead of a second identical failure.
+            already_blocked = any(
+                item.decision == "D06" and item.level == FAIL for item in audit.findings
+            )
+            audit.add(
+                "D06",
+                INFO if already_blocked else FAIL,
+                f"{name}: 没有 image",
+                "镜像必须来自上游证据（README 的 docker run / 官方镜像页）",
+            )
+        elif d06 and _image_repo(image) not in {_image_repo(item) for item in d06}:
+            audit.add(
+                "D06",
+                WARN if not audit.acknowledged.get("D06") else INFO,
+                f"{name}: spec 的镜像 {image} 与 D06 证据（{', '.join(d06)}）不一致",
+                "确认是有意换镜像；第三方镜像要在 README 里写明来源与风险",
+            )
+
+        # D03 — a host path without a container path silently drops persistence.
+        if targets:
+            if d03:
+                unknown = [item for item in targets if item not in d03]
+                if unknown:
+                    audit.add(
+                        "D03",
+                        WARN,
+                        f"{name}: 挂载点 {unknown} 不在 D03 证据（{', '.join(d03)}）里",
+                        "每个挂载点都要能指回上游 VOLUME / 官方 compose",
+                    )
+        elif host:
+            if audit.acknowledged.get("D03"):
+                audit.add(
+                    "D03",
+                    INFO,
+                    f"{name}: 声明了 mount_host 但没有容器内路径，"
+                    f"已按 acknowledged 当作无持久化处理",
+                )
+            else:
+                audit.add(
+                    "D03",
+                    FAIL,
+                    f"{name}: 声明了 mount_host（{host}）却没有容器内挂载路径",
+                    "在 mounts / mount_targets 里写出 target；"
+                    "如果这个应用确实不持久化数据，删掉 mount_host 并确认 D03",
+                )
+
+        # D05 — the container port.
+        if port in (None, ""):
+            status = _status(audit.ledger, "D05")
+            if audit.acknowledged.get("D05"):
+                audit.add("D05", INFO, f"{name}: 没有 container_port，已按 acknowledged 继续")
+            elif status in (EVIDENCED, INFERRED):
+                audit.add(
+                    "D05",
+                    FAIL,
+                    f"{name}: D05 证据是 {_answer_text(audit.ledger.get('D05'))}，"
+                    "但 spec 没有 container_port",
+                    "端口必须来自上游 EXPOSE / 官方 compose，不能省略",
+                )
+            else:
+                audit.add(
+                    "D05",
+                    WARN,
+                    f"{name}: 没有 container_port，这个包不会映射端口",
+                    '应用不对外提供端口（例如后台 worker）时，写 "public": false 说明是有意的',
+                )
+        else:
+            value = str(port)
+            if d05 and value not in d05:
+                audit.add(
+                    "D05",
+                    WARN if not audit.acknowledged.get("D05") else INFO,
+                    f"{name}: 容器端口 {value} 不在 D05 证据（{', '.join(d05)}）里",
+                    "抄模板默认端口是已知翻车点（openviking 1933 曾被写成 8080）",
+                )
+
+def _audit_env_keys(audit: Audit, spec: dict[str, Any]) -> None:
+    """D01: an invented variable name starts a container that ignores the value."""
+    if not audit.ledger:
+        return
+    known = set(_answer_values(audit.ledger.get("D01")))
+    known |= set(_answer_values(audit.ledger.get("D02")))
+    known.discard("")
+    if not known:
+        return
+    ignore = rules.implicit_envkeys() | GENERATED_ENV_KEYS
+    acknowledged = bool(audit.acknowledged.get("D01") or audit.acknowledged.get("D02"))
+
+    seen: set[str] = set()
+    for service in spec.get("services") or []:
+        if not isinstance(service, dict):
+            continue
+        for key in (service.get("env") or {}):
+            key = str(key)
+            if key in seen or key in ignore or key.startswith("PANEL_"):
+                continue
+            seen.add(key)
+            if key in known:
+                continue
+            audit.add(
+                "D01",
+                INFO if acknowledged else WARN,
+                f"环境变量 {key} 不在 D01/D02 证据（{', '.join(sorted(known))}）里",
+                "确认变量名拼写与上游一致；改错名字的变量容器照样起得来，只是不生效",
+            )
+
+
+# Runtime fields whose presence is a claim about the upstream image. Writing
+# one without evidence is how a package ends up fighting its own image (L004).
+RUNTIME_KEYS = (
+    "user",
+    "privileged",
+    "cap_add",
+    "cap_drop",
+    "devices",
+    "security_opt",
+    "group_add",
+    "sysctls",
+    "network_mode",
+    "pid",
+    "ipc",
+)
+
+
+def _audit_runtime(audit: Audit, spec: dict[str, Any]) -> None:
+    if not audit.ledger:
+        return
+    declared: list[str] = []
+    for service in spec.get("services") or []:
+        if not isinstance(service, dict):
+            continue
+        declared.extend(key for key in RUNTIME_KEYS if service.get(key))
+    if spec.get("data_owner"):
+        declared.append("data_owner")
+    if not declared:
+        return
+    status = _status(audit.ledger, "D07")
+    if status == EVIDENCED:
+        return
+    audit.add(
+        "D07",
+        INFO if audit.acknowledged.get("D07") else WARN,
+        f"spec 声明了运行时字段 {sorted(set(declared))}，但 D07（上游运行时要求）"
+        f"在账本里是 {status or '缺失'}",
+        "运行用户/权限只以上游 Dockerfile、compose 为准；凭空 chown 或加 user 会让"
+        "挂载目录权限出错（lesson L004）",
+    )
+
+
+def _audit_dependency_and_scripts(audit: Audit, spec: dict[str, Any]) -> None:
+    """The spec must not quietly disagree with what resolve found."""
+    if not audit.ledger:
+        return
+    acknowledged = bool(
+        audit.acknowledged.get("D09") or audit.acknowledged.get("D10")
+    )
+
+    if spec.get("dependencies"):
+        status = _status(audit.ledger, "D10")
+        answer = _answer_text(audit.ledger.get("D10"))
+        if status != EVIDENCED:
+            audit.add(
+                "D10",
+                INFO if acknowledged else WARN,
+                f"spec 声明了面板依赖，但账本里 D10 是 {status or '缺失'}（{answer}）",
+                "确认上游确实支持外部数据库/缓存，并且依赖的 key 与面板上的应用一致",
+            )
+
+    uses_scripts = bool(spec.get("scripts") or spec.get("init_script"))
+    ships_config = bool(spec.get("config_files"))
+    if not (uses_scripts or ships_config):
+        return
+    status = _status(audit.ledger, "D09")
+    answer = _answer_text(audit.ledger.get("D09"))
+    if status == EVIDENCED and not uses_scripts:
+        return
+    if status == MISSING and not acknowledged:
+        audit.add(
+            "D09",
+            WARN,
+            f"spec 带了 {'脚本' if uses_scripts else ''}"
+            f"{' 和' if uses_scripts and ships_config else ''}"
+            f"{'配置文件模板' if ships_config else ''}，但账本里 D09 没有证据",
+            "确认上游首次启动真的需要它；不需要就别带（少了 init.sh 是 L001，"
+            "凭空多了脚本则是没必要的维护面）",
+        )
+    elif status == INFERRED and "暂定无" in answer:
+        audit.add(
+            "D09",
+            WARN,
+            f"spec 带了{'脚本' if uses_scripts else ''}"
+            f"{'配置文件模板' if ships_config else ''}，但账本里 D09 的间接结论是「暂定无」",
+            "这次人工判断与 resolve 的推断不一致，确认后把 D09 的证据补进 spec",
+        )
+
+
+def audit(spec: dict[str, Any], allowed_unresolved: bool = False) -> Audit:
+    """Run every evidence check against a generation spec."""
+    result = Audit(
+        ledger=ledger_of(spec),
+        acknowledged={
+            str(key).upper(): str(value)
+            for key, value in (spec.get("acknowledged") or {}).items()
+        }
+        if isinstance(spec.get("acknowledged"), dict)
+        else {},
+        allowed_unresolved=allowed_unresolved,
+    )
+    _audit_ledger(result)
+    _audit_services(result, spec)
+    _audit_env_keys(result, spec)
+    _audit_runtime(result, spec)
+    _audit_dependency_and_scripts(result, spec)
+    return result
+
+
+__all__ = [
+    "Audit",
+    "EVIDENCED",
+    "Finding",
+    "INFERRED",
+    "LEDGER",
+    "MISSING",
+    "audit",
+    "ledger_of",
+]