openpuppet-language 2.0__py3-none-any.whl

openpuppet_language-2.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+openpuppet_language-2.0.data/data/share/puppet/conformance/README.md,sha256=c0YLKLgVu05PgkP7UZGQCraonbJBt1C1QBpVR4ZlsuI,17495
+openpuppet_language-2.0.data/data/share/puppet/conformance/runner.py,sha256=5psF1f4JaqUTYHpoJivR4eGGrETokHGjOvlx1Rsv7X0,32303
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/binding.json,sha256=tbxo15lbtL5B1bPJcrjQeNz0RiAh7YQenJu8fln5RBs,6887
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/capabilities.json,sha256=V8c3HjW0u3NQcNAbIXDr-ZmzZljLic29PaZxq7lp9Cw,5008
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/grammar.json,sha256=eSe_60W8gpZUwidDjc4679DvVLlvUAn8-F30sXSB2zU,6668
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/interaction.json,sha256=Pxa3cIcUhQDIQUVQ_B5lEaY0QHiRnZXrWXuwL4FH3qU,7556
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/listen.json,sha256=Skk2HHzAjTOupRzrEg2IXnD4Iwna6eOX5UuPUw5hlwI,3939
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/platform.json,sha256=Ikub0GSSR6OQZTZd63OBsmcB-gI-tXrWAlrPII6w05I,8042
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/probes.json,sha256=OJ66wqXoQiuUpB4NgfykMJ3mg0_zbM9vgndTKrZj5QA,3024
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/render.json,sha256=QjMcJO7Kn4E0j7ba_Rd_nfbexOXZUR7tQygyz1mFwYo,5957
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/tabs.json,sha256=LZfCGt5exnVogvFk4qsraN14mYoqr94pQh_f3-5MNbc,973
+openpuppet_language-2.0.data/data/share/puppet/conformance/cases/templates.json,sha256=6eMLhtvdbhb9raZ4h9AKkMsw6ms4P3n9ebEaPwvXTmY,4590
+openpuppet_language-2.0.data/data/share/puppet/conformance/fixtures/capabilities_bad_result.py,sha256=CLcqL_fWmpqfmLvKoP1fJGl1BX78meXPVBlYYbCUt_I,306
+openpuppet_language-2.0.data/data/share/puppet/conformance/fixtures/capabilities_basic.py,sha256=iMMUJF7Qslhc1ef_hZ5cwaVKMQdysQGnizWl1v01Sn0,675
+openpuppet_language-2.0.data/data/share/puppet/conformance/fixtures/capabilities_deps_mismatch.py,sha256=Km57Ix7ZuqvTQpjKcCC6BYVtNrBmf8uc-tEefd5fyo4,316
+openpuppet_language-2.0.data/data/share/puppet/conformance/fixtures/capabilities_no_doc.py,sha256=qBa4U4d_tYg_27ryevra6UUziFI9tUWA4dERCvXUWy0,215
+openpuppet_language-2.0.data/data/share/puppet/spec/01-grammar.md,sha256=ax5nNySdeXvybtKIphWPs8wpvVaM6rp3tFfPDFARrCc,13749
+openpuppet_language-2.0.data/data/share/puppet/spec/02-ir.md,sha256=8Fjx8Wwl6kpwmVB5Y16A7SLOFQ-AHTnWPiZryasFNvQ,4124
+openpuppet_language-2.0.data/data/share/puppet/spec/03-semantics.md,sha256=Ljc9TA28WnfBPYkz_3URr-PbJFlMDYunfps5ThKzfac,9813
+openpuppet_language-2.0.data/data/share/puppet/spec/04-vocabulary.md,sha256=36Ao600pdHXQmPJ7n3_pPaLGrAp6eLaDxXJlSljbTZQ,9809
+openpuppet_language-2.0.data/data/share/puppet/spec/05-render-contract.md,sha256=A9nYzVxItMvEeizr6gM_EKIbymB1suKIitfcPPpjLAw,9507
+openpuppet_language-2.0.data/data/share/puppet/spec/06-diagnostics.md,sha256=Wpa5V3VfYGH7CbyuRzf6N7LdyxtsTKus4mTdGHRsU1c,8746
+openpuppet_language-2.0.data/data/share/puppet/spec/README.md,sha256=GoSflg7wpY-hQ_fI0pGzP9kDRZ5spJgMGfXxrW0l4_U,5297
+puppet/__init__.py,sha256=q4kHbcONrhkCj-u2MGOczy3mm0OvA9ni5auLEs2WKqE,639
+puppet/adapter.py,sha256=WC_d2bIQtSO9h-KERjgrQyXC16i3lqPOz9diFCcI6Ns,4161
+puppet/capabilities.py,sha256=wEnUJLT8-S7xXuNBAKWj1ItFhiFFhRBVDfQpBqLnyx4,7005
+puppet/cli.py,sha256=5jGHDKZOgTR1fbxCbramiDuZO5faxctkHiEzV5xN1Pg,4681
+puppet/diag.py,sha256=bWhP0BjBDlBr9Ywj_Xhxm05VU9dLrk3ioRaLdc8sJuQ,1200
+puppet/engine.py,sha256=uyAfGzgHKZ0y5x3RoT6gvGjk2iuK4I2k4nKWtwe_9Sc,46198
+puppet/eval.py,sha256=FC-l4iUBDbU2LTXb-30n4kbvjYTMq_xC45jgPQZB0dc,8673
+puppet/ir.py,sha256=cP3M5TcLwpxf_X13B4lmU2OKRSzIzbBfrQwL2TGChfk,21452
+puppet/lang.py,sha256=KJ6CC4tYgp0J1irNdauYqK4xNqRKt2wY88MW0U0HssY,23420
+puppet/raster_adapter.py,sha256=btxTENjdZNU9pdwiu0J5fmKpYmLr7fFwlEkvoyi8z9I,15609
+puppet/tk_adapter.py,sha256=JhStuobJu-oH6wNNQWGfuWIv2tfPabpZV4oyQtJnY44,16180
+puppet/vocab.py,sha256=-mX92BjkGqAyOZbR7A9MyjQf78O1CDBcrbC6s5ifMB0,5506
+openpuppet_language-2.0.dist-info/METADATA,sha256=FQK1r413FXZCScqecPAlMi-Nh6NmsXw525KmMSM_PIM,2047
+openpuppet_language-2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+openpuppet_language-2.0.dist-info/entry_points.txt,sha256=T3PaN03V-_GiGTrMawIEh2J5OjWe54N2NpLcvwYy6vI,43
+openpuppet_language-2.0.dist-info/top_level.txt,sha256=O6DGsH-AdDl1k7C2RtsmmtnKBX8kjSgIvhUy3pUiCSY,7
+openpuppet_language-2.0.dist-info/RECORD,,

openpuppet_language-2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openpuppet_language-2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+puppet = puppet.cli:main

openpuppet_language-2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+puppet

puppet/__init__.py

@@ -0,0 +1,19 @@
+"""Puppet 语言标准实现。
+
+本包是 `spec/` 下语言规范的**参考实现**：解析、校验、IR、执行语义。
+它不包含任何渲染实现；渲染由下游软件（puppethub）按渲染契约提供。
+"""
+
+from .capabilities import capability, contract_of, load_capability_module
+from .diag import Diagnostic, ERROR, INFO, WARNING
+from .engine import Engine
+from .ir import Program, new_program, validate
+
+SPEC_VERSION = "2.0"
+
+__all__ = [
+    "Diagnostic", "ERROR", "INFO", "WARNING",
+    "Engine", "Program", "new_program", "validate",
+    "capability", "contract_of", "load_capability_module",
+    "SPEC_VERSION",
+]

puppet/adapter.py

@@ -0,0 +1,112 @@
+"""conformance 适配器：行分隔 JSON over stdio（见 `conformance/README.md` 第 4 节）。
+
+这个文件是"标准实现"与"外部测试者"之间的边界；任何语言都可以实现同一协议。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from . import vocab
+from .engine import Engine
+
+
+def describe_rendering() -> dict:
+    """参考渲染器的能力声明（启动握手 `hello` 的响应体）。
+
+    本实现是**无渲染器的语义引擎**：词汇全支持，但几何与截图**不提供**
+    （二者都必须走可见降级）；可无 GUI 驱动。
+    - 数组 = 声明支持的子集；`null` = 支持全部标准（本实现选择显式列全）。
+    - `geometry` / `snapshot` / `headless` 是布尔观测/驱动能力。
+    """
+    return {
+        "controls": list(vocab.NODE_TYPES),
+        "attributes": sorted(vocab.ALL_ATTRS),
+        "animations": sorted(vocab.ANIMATABLE),
+        "icons": sorted(vocab.CORE_ICONS),
+        "geometry": False,
+        "snapshot": False,
+        "interaction": False,
+        "headless": True,
+        "notes": "参考语义引擎：无渲染器；几何、截图与用户动作投递均按规范可见降级。"
+                 "conformance 可用 load.renderGeometry / load.rendering 注入测试替身。",
+    }
+
+
+def handle(engine: Engine, request: dict) -> dict:
+    op = request.get("op")
+    if op == "hello":
+        return {"protocol": "1", "rendering": describe_rendering()}
+    if op == "load":
+        diags = engine.load(
+            request.get("program", []),
+            capabilities=request.get("capabilities"),
+            limits=request.get("limits"),
+            seed_state=request.get("seedState"),
+            render_geometry=request.get("renderGeometry"),
+            rendering=request.get("rendering"),
+            capability_modules=request.get("capabilityModules"),
+        )
+        return {"diagnostics": [d.to_dict() for d in diags]}
+    if op == "send":
+        diags = engine.apply_batch(request.get("batch", []))
+        return {"diagnostics": [d.to_dict() for d in diags]}
+    if op == "fire":
+        diags = engine.fire(request.get("target", ""), request.get("event", ""),
+                            request.get("row"), request.get("value"))
+        return {"diagnostics": [d.to_dict() for d in diags]}
+    if op == "restart":
+        diags = engine.restart()
+        return {"diagnostics": [d.to_dict() for d in diags]}
+    if op == "observe":
+        return engine.observe()
+    if op == "interact":
+        return engine.deliver_interaction(request.get("target", ""),
+                                          request.get("action", ""),
+                                          request.get("value"))
+    if op == "snapshot":
+        return engine.snapshot()
+    if op == "quit":
+        return {"ok": True}
+    return {"error": "未知操作 %r" % op}
+
+
+def _emit(payload: dict) -> None:
+    """输出纯 ASCII 的行分隔 JSON。
+
+    刻意用 `ensure_ascii=True`：协议不依赖子进程的标准输出编码，
+    在 Windows 上尤为关键（默认可能是 GBK）。
+    """
+    sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> int:
+    try:
+        sys.stdin.reconfigure(encoding="utf-8", errors="replace")
+        sys.stdout.reconfigure(encoding="ascii", errors="backslashreplace")
+    except Exception:  # noqa: BLE001 - 老环境没有 reconfigure 也不致命
+        pass
+    engine = Engine()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as ex:
+            _emit({"error": "请求不是合法 JSON：%s" % ex})
+            continue
+        try:
+            response = handle(engine, request)
+        except Exception as ex:  # noqa: BLE001 - 适配器绝不静默：错误原样回传
+            response = {"error": "%s: %s" % (type(ex).__name__, ex)}
+        _emit(response)
+        if request.get("op") == "quit":
+            break
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

puppet/capabilities.py

@@ -0,0 +1,172 @@
+"""能力（工具）的契约提取与真实加载（规范 `03-semantics.md` 第 4 节）。
+
+三条硬性义务，缺一即违规：
+
+- **说明文本非空**：docstring 是 LLM 发现工具的唯一说明书（`03` 第 4.5 节），
+  缺失即 **错误** `CAP_NO_DOC`，且该能力**不注册**。
+- **依赖显式声明 + 扫描兜底 + 不一致必须报警**：模块级 `REQUIRES` 与源码实际 import
+  不一致时 **警告** `CAP_DEPS_MISMATCH`——否则部署机上才缺包（v1 的教训）。
+- **返回值可序列化**：由引擎校验（`CALL_RESULT`）；`async` 函数直接 await，
+  同步函数走线程池，超时 / 取消由槽负责。
+
+测试替身（conformance 的 `load.capabilities`）与真实模块（`load.capabilityModules`）
+走**同一份契约形状**，因此行为用例对二者同样适用。
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import inspect
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+from .diag import ERROR, INFO, WARNING, Diagnostic
+
+MARKER = "__puppet_capability__"
+
+_PY_TYPES = {"str": str, "int": int, "float": float, "bool": bool,
+             "list": list, "dict": dict, "any": object}
+
+
+def capability(fn=None, *, name: Optional[str] = None, returns: Any = None,
+               requires: Optional[List[str]] = None):
+    """把一个函数标记为能力。
+
+    ```python
+    @capability()
+    def compress(path: str, level: int = 6) -> dict:
+        \"\"\"压缩文件，返回 {"bytes": <大小>}。\"\"\"
+    ```
+
+    `requires` 是**本能力**额外需要的依赖；模块级 `REQUIRES` 覆盖全模块。
+    """
+    def wrap(func):
+        setattr(func, MARKER, {"name": name or func.__name__,
+                               "returns": returns, "requires": requires})
+        return func
+    return wrap if fn is None else wrap(fn)
+
+
+def type_name(annotation: Any) -> str:
+    """把类型注解归一化成规范里的类型名（`str` / `int` / …）。"""
+    if annotation is inspect.Parameter.empty or annotation is None:
+        return "any"
+    if isinstance(annotation, str):
+        return annotation.strip() or "any"
+    return getattr(annotation, "__name__", "any")
+
+
+def contract_of(func) -> Optional[Dict[str, Any]]:
+    """从签名与类型注解提取契约；非能力函数返回 `None`。"""
+    marker = getattr(func, MARKER, None)
+    if marker is None:
+        return None
+    try:
+        sig = inspect.signature(func)
+    except (TypeError, ValueError):       # 不可 introspect 的可调用对象
+        params = []
+    else:
+        params = []
+        for pname, param in sig.parameters.items():
+            if pname in ("self", "cls"):
+                continue
+            params.append({
+                "name": pname,
+                "type": type_name(param.annotation),
+                "required": param.default is inspect.Parameter.empty,
+                **({} if param.default is inspect.Parameter.empty
+                   else {"default": param.default}),
+            })
+    doc = (func.__doc__ or "").strip()
+    return {
+        "name": marker.get("name") or func.__name__,
+        "params": params,
+        "returns": type_name(marker.get("returns"))
+        if marker.get("returns") is not None
+        else type_name(getattr(func, "__annotations__", {}).get("return")),
+        "doc": doc,
+        "requires": list(marker.get("requires") or []),
+        "callable": func,
+        "behavior": "callable",
+    }
+
+
+def type_matches(declared: str, value: Any) -> bool:
+    """按契约声明的类型判定实参；`any` 或未声明一律接受。"""
+    expected = _PY_TYPES.get(str(declared).lower())
+    if expected is None or expected is object:
+        return True
+    if expected is float and isinstance(value, int) and not isinstance(value, bool):
+        return True                      # 整数提升为浮点（规范 04 的隐式转换）
+    if expected is int and isinstance(value, bool):
+        return False                     # 布尔不参与数值比较
+    return isinstance(value, expected)
+
+
+def _imported_modules(path: str) -> List[str]:
+    """扫描源码的顶层 import（兜底：动态 import 扫不到，故仍要求显式声明）。"""
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            tree = ast.parse(fh.read(), filename=path)
+    except (OSError, SyntaxError):
+        return []
+    found = set()
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                found.add(alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            found.add(node.module.split(".")[0])
+    return sorted(found)
+
+
+def load_capability_module(path: str) -> Tuple[Dict[str, dict], List[Diagnostic]]:
+    """加载一个能力模块，返回 `(契约表, 诊断)`。
+
+    失败（找不到文件 / 导入报错）**必须可见**：`CAP_IMPORT` 错误，不静默跳过。
+    """
+    diags: List[Diagnostic] = []
+    name = os.path.splitext(os.path.basename(path))[0]
+    if not os.path.isfile(path):
+        diags.append(Diagnostic("CAP_IMPORT", ERROR, "能力模块不存在：%s" % path))
+        return {}, diags
+    spec = importlib.util.spec_from_file_location("puppet_capability_" + name, path)
+    if spec is None or spec.loader is None:
+        diags.append(Diagnostic("CAP_IMPORT", ERROR, "能力模块无法加载：%s" % path))
+        return {}, diags
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception as ex:  # noqa: BLE001 - 一律转为可见失败
+        diags.append(Diagnostic("CAP_IMPORT", ERROR,
+                                "能力模块导入失败（%s）：%s: %s"
+                                % (name, type(ex).__name__, ex)))
+        return {}, diags
+
+    # 依赖核对：显式声明 vs 实际 import
+    declared = list(getattr(module, "REQUIRES", []) or [])
+    scanned = _imported_modules(path)
+    if declared and sorted(set(declared)) != scanned:
+        diags.append(Diagnostic(
+            "CAP_DEPS_MISMATCH", WARNING,
+            "能力模块 %s 的依赖声明与实际 import 不一致：声明 %s，实际 %s"
+            % (name, sorted(set(declared)), scanned)))
+
+    contracts: Dict[str, dict] = {}
+    for attr in vars(module).values():
+        contract = contract_of(attr)
+        if contract is None:
+            continue
+        if not contract["doc"]:
+            diags.append(Diagnostic(
+                "CAP_NO_DOC", ERROR,
+                "能力 %s 没有说明文本（docstring 是工具的唯一说明书），不予注册"
+                % contract["name"]))
+            continue
+        if contract["name"] in contracts:
+            diags.append(Diagnostic(
+                "CALL_UNKNOWN", ERROR, "能力 %s 重复定义" % contract["name"]))
+            continue
+        contracts[contract["name"]] = contract
+    return contracts, diags

puppet/cli.py

@@ -0,0 +1,132 @@
+"""`puppet` 命令：标准工具（不需要 app 即可运行）。
+
+子命令：`spec`（规范位置）、`validate`（静态校验）、`conformance`（跑合规用例）。
+
+注意：`validate` 只做静态校验——解析与 IR 校验，不起运行时。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+from . import SPEC_VERSION
+from .engine import Engine
+from .ir import apply_stmt, new_program, validate
+from .lang import parse_program
+
+def _assets_dir() -> str:
+    """定位随发行包分发的 `spec/` 与 `conformance/`。
+
+    开发态（源码树 / `pip install -e`）：仓库根。
+    安装态：setuptools 的 data-files 落在 `<prefix>/share/puppet`。
+    可用环境变量 `PUPPET_ASSETS` 覆盖（下游打包可自行安置资产）。
+    """
+    override = os.environ.get("PUPPET_ASSETS")
+    if override:
+        return override
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    if os.path.isdir(os.path.join(root, "spec")):
+        return root
+    installed = os.path.join(sys.prefix, "share", "puppet")
+    if os.path.isdir(os.path.join(installed, "spec")):
+        return installed
+    return root
+
+
+ROOT = _assets_dir()
+
+
+def cmd_spec(_args) -> int:
+    path = os.path.join(ROOT, "spec")
+    if not os.path.isdir(path):
+        print("找不到规范目录：%s（发行包安装不完整？）" % path, file=sys.stderr)
+        return 1
+    print("规范版本：%s" % SPEC_VERSION)
+    print(path)
+    return 0
+
+
+def _validate_target(path: str):
+    with open(path, "r", encoding="utf-8") as fh:
+        lines = fh.read().splitlines()
+    program = new_program()
+    diags = []
+    stmts, pdiags = parse_program(lines)
+    diags += pdiags
+    for stmt in stmts:
+        apply_stmt(program, stmt, diags)
+    diags += validate(program)
+    return diags
+
+
+def cmd_validate(args) -> int:
+    if not os.path.exists(args.path):
+        print("路径不存在：%s" % args.path)
+        return 1
+    if os.path.isdir(args.path):
+        targets = [os.path.join(args.path, name) for name in sorted(os.listdir(args.path))
+                   if name.endswith(".puppet")]
+        if not targets:
+            print("目录里没有 .puppet 文件：%s" % args.path)
+            return 1
+    else:
+        targets = [args.path]
+
+    total_diags = total_errors = 0
+    for target in targets:
+        diags = _validate_target(target)
+        total_diags += len(diags)
+        total_errors += sum(1 for d in diags if d.level == "error")
+        if not diags:
+            print("%s：零诊断" % os.path.basename(target))
+            continue
+        print("%s：" % os.path.basename(target))
+        for diag in diags:
+            mark = {"error": "错误", "warning": "警告", "info": "信息"}[diag.level]
+            location = ("第 %d 行" % diag.line) if diag.line else "全局"
+            print("  %s %s %s: %s" % (location, mark, diag.code, diag.message))
+    print("合计 %d 条诊断，其中错误 %d 条" % (total_diags, total_errors))
+    if args.strict:
+        return 1 if total_diags else 0
+    return 1 if total_errors else 0
+
+
+def cmd_conformance(args) -> int:
+    runner = os.path.join(ROOT, "conformance", "runner.py")
+    if not os.path.isfile(runner):
+        print("找不到 conformance 运行器：%s（发行包安装不完整？）" % runner,
+              file=sys.stderr)
+        return 1
+    module = "puppet.tk_adapter" if args.tk else "puppet.adapter"
+    cmd = [sys.executable, runner, "--impl", '"%s" -m %s' % (sys.executable, module)]
+    if args.filter:
+        cmd += ["--filter", args.filter]
+    return subprocess.call(cmd, cwd=ROOT)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="puppet", description="Puppet 语言标准工具")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("spec", help="显示规范版本与位置").set_defaults(func=cmd_spec)
+
+    p_val = sub.add_parser("validate", help="静态校验 .puppet 文件或目录")
+    p_val.add_argument("path", help="文件路径，或包含 .puppet 的目录")
+    p_val.add_argument("--strict", action="store_true", help="有任何诊断即视为失败")
+    p_val.set_defaults(func=cmd_validate)
+
+    p_conf = sub.add_parser("conformance", help="运行合规用例集")
+    p_conf.add_argument("--filter", default="")
+    p_conf.add_argument("--tk", action="store_true",
+                        help="用 Tk 渲染器适配器跑（真实几何；需要显示器）")
+    p_conf.set_defaults(func=cmd_conformance)
+
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

puppet/diag.py

@@ -0,0 +1,42 @@
+"""诊断：级别、形状、码。
+
+码表与 `spec/06-diagnostics.md` 一致；此处只定义形状，码以字符串常量使用。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+ERROR = "error"
+WARNING = "warning"
+INFO = "info"
+
+
+@dataclass
+class Diagnostic:
+    code: str
+    level: str
+    message: str
+    line: int = 0
+    col: int = 0
+    suggest: str = ""
+    # 仅 DEGRADED_FEATURE 使用：被降级的那个特性（`geometry` / `snapshot` /
+    # `control:<类型>` / `attr:<名>` / `animation:<名>` / `icon:<名>`）。
+    # conformance 的"声明即 oracle"按它比对，故必须机读。
+    feature: str = ""
+
+    def to_dict(self):
+        out = {"code": self.code, "level": self.level, "message": self.message}
+        if self.line:
+            out["line"] = self.line
+        if self.col:
+            out["col"] = self.col
+        if self.suggest:
+            out["suggest"] = self.suggest
+        if self.feature:
+            out["feature"] = self.feature
+        return out
+
+    def key(self):
+        """用于"本步是否新增"的判据（不含行号：行号随批次变化）。"""
+        return (self.code, self.message, self.level)