evidgate 0.9.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,105 @@
1
+ """Built-in check commands: `method: builtin:prose:absolutes draft.md`.
2
+
3
+ Why this exists: a check generated by this tool must run under the way this tool is
4
+ installed. Shelling out to `evidgate ...` breaks for the most common case -- a clone
5
+ run through ./bin/evidgate -- and produces `exit 127` with no explanation. Built-ins
6
+ are dispatched in-process, so there is no PATH to get wrong.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import contextlib
11
+ import io
12
+ import os
13
+ import time
14
+ from typing import Callable, Dict, List, Tuple
15
+
16
+ from .evidence import Evidence
17
+
18
+ PLUGINS: Dict[str, Dict[str, Callable]] = {}
19
+
20
+
21
+ def register(plugin: str, rules: Dict[str, Callable]) -> None:
22
+ PLUGINS[plugin] = rules
23
+
24
+
25
+ def is_builtin(method: str) -> bool:
26
+ return method.strip().startswith("builtin:")
27
+
28
+
29
+ def _load_default_plugins() -> None:
30
+ if PLUGINS:
31
+ return
32
+ # each builtin entry takes (path) and returns an exit code; prose.scan is that entry
33
+ from ..plugins import artifact, prose
34
+ register("prose", {rule: (lambda argv, _r=rule: prose.scan(argv[0], _r))
35
+ for rule in prose.RULES})
36
+ register("artifact", {rule: (lambda argv, _r=rule: artifact.run(_r, argv))
37
+ for rule in artifact.RULES})
38
+
39
+
40
+ def parse(method: str) -> Tuple[str, str, List[str]]:
41
+ """'builtin:prose:absolutes draft.md' -> ('prose', 'absolutes', ['draft.md'])."""
42
+ spec, _, rest = method.strip().partition(" ")
43
+ parts = spec.split(":")
44
+ if len(parts) != 3 or parts[0] != "builtin":
45
+ raise ValueError(
46
+ f"bad builtin method {method!r}; expected builtin:<plugin>:<rule> [args]"
47
+ )
48
+ return parts[1], parts[2], rest.split()
49
+
50
+
51
+ def dispatch(method: str, cwd: str = ".") -> Evidence:
52
+ """Run a builtin check in-process and wrap the result as Evidence.
53
+
54
+ cwd matters: a check declared against the project must see the project's files,
55
+ exactly like a shell check does.
56
+ """
57
+ _load_default_plugins()
58
+ plugin, rule, args = parse(method)
59
+ started = time.strftime("%Y-%m-%dT%H:%M:%S")
60
+ t0 = time.time()
61
+
62
+ if plugin not in PLUGINS:
63
+ return Evidence(method, None, "", f"unknown builtin plugin {plugin!r}", 0.0, started)
64
+ if rule not in PLUGINS[plugin]:
65
+ return Evidence(method, None, "", f"unknown builtin rule {rule!r}", 0.0, started)
66
+
67
+ buf = io.StringIO()
68
+ prev = os.getcwd()
69
+ try:
70
+ if cwd and os.path.isdir(cwd):
71
+ os.chdir(cwd)
72
+ with contextlib.redirect_stdout(buf):
73
+ code = int(PLUGINS[plugin][rule](args))
74
+ except SystemExit as exc: # a rule may call sys.exit
75
+ code = int(exc.code or 0)
76
+ except TypeError as exc:
77
+ return Evidence(method, None, "", f"builtin arg error: {exc}", 0.0, started)
78
+ except FileNotFoundError as exc:
79
+ return Evidence(method, 2, "", f"file not found: {exc}", 0.0, started)
80
+ finally:
81
+ try:
82
+ os.chdir(prev)
83
+ except OSError:
84
+ pass
85
+ out = buf.getvalue()
86
+ return Evidence(method, code, out, "", round(time.time() - t0, 3), started)
87
+
88
+
89
+ def describe(method: str, cwd: str = ".") -> str:
90
+ """Human-readable form used by `evidgate doctor`."""
91
+ try:
92
+ plugin, rule, args = parse(method)
93
+ except ValueError as exc:
94
+ return f"BAD: {exc}"
95
+ _load_default_plugins()
96
+ if plugin not in PLUGINS:
97
+ return f"BAD: unknown plugin {plugin!r} (have: {sorted(PLUGINS)})"
98
+ if rule not in PLUGINS[plugin]:
99
+ return f"BAD: unknown rule {rule!r} in {plugin} (have: {sorted(PLUGINS[plugin])})"
100
+ missing = [a for a in args
101
+ if not a.startswith("-")
102
+ and not os.path.exists(a if os.path.isabs(a) else os.path.join(cwd, a))]
103
+ if missing:
104
+ return f"WARN: file not found: {', '.join(missing)}"
105
+ return "OK"
evidgate/core/check.py ADDED
@@ -0,0 +1,175 @@
1
+ """Check registry.
2
+
3
+ A check is only a check if it has a counter-test: the thing you would break to make
4
+ it go red. A check without a counter-test is a wish, not a gate -- load_checks()
5
+ refuses it.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import os
11
+ import re
12
+ from dataclasses import dataclass
13
+ from typing import List
14
+
15
+ SEVERITIES = ("red", "yellow")
16
+ SHELLS = ("", "sh", "bash", "cmd", "powershell", "pwsh")
17
+
18
+
19
+ @dataclass
20
+ class Check:
21
+ cid: str # C1
22
+ name: str # what is being checked
23
+ method: str # shell command that produces evidence
24
+ expect: str # assertion, e.g. "exit:0; contains:OK" or "manual"
25
+ counter: str = "" # counter-test; empty is refused by validate()
26
+ severity: str = "red" # red -> blocking, yellow -> non-blocking (DIFF)
27
+ optional: bool = False # true -> a failing command becomes SKIP (not applicable), not red
28
+ timeout: int = 120
29
+ note: str = ""
30
+ shell: str = "" # "" = exec the command directly (no shell);
31
+ # "bash" / "sh" / "cmd" / "powershell" / "pwsh"
32
+ # = run it through that shell explicitly
33
+
34
+ def validate(self) -> None:
35
+ if not self.cid:
36
+ raise ValueError("check without id")
37
+ if not self.name:
38
+ raise ValueError(f"{self.cid}: check without name")
39
+ if not self.counter.strip():
40
+ raise ValueError(
41
+ f"{self.cid} ({self.name}): no counter-test. "
42
+ "Declare how this check goes red, or drop it -- "
43
+ "a gate that cannot fail is not a gate."
44
+ )
45
+ if self.shell not in SHELLS:
46
+ raise ValueError(
47
+ f"{self.cid}: shell must be one of {SHELLS} (or empty for no shell)"
48
+ )
49
+ if self.severity not in SEVERITIES:
50
+ raise ValueError(f"{self.cid}: severity must be one of {SEVERITIES}")
51
+ if "not_contains" in self.expect and "exit:" not in self.expect:
52
+ raise ValueError(
53
+ f"{self.cid} ({self.name}): 'not_contains' without an 'exit:' clause. "
54
+ "If the command fails and prints nothing, not_contains passes on empty "
55
+ "output -- a tautology that reports green when the file is gone. "
56
+ "Pair it with exit:0."
57
+ )
58
+
59
+
60
+ _HEAD = re.compile(r"^\s*-\s*(\w+)\s*:\s*(.*)$")
61
+ _KV = re.compile(r"^\s+(\w+)\s*:\s*(.*)$")
62
+
63
+
64
+ def _scalar(v: str):
65
+ v = v.strip()
66
+ if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
67
+ return v[1:-1]
68
+ if v.lower() in ("true", "false"):
69
+ return v.lower() == "true"
70
+ if re.fullmatch(r"-?\d+", v):
71
+ return int(v)
72
+ return v
73
+
74
+
75
+ def _mini_yaml(text: str) -> dict:
76
+ """Tiny YAML subset: top-level keys, and lists of flat key/value maps.
77
+
78
+ Keeps evidgate dependency-free; a real YAML parser is used when available.
79
+ """
80
+ try:
81
+ import yaml # type: ignore
82
+ return yaml.safe_load(text) or {}
83
+ except Exception:
84
+ pass
85
+
86
+ out, cur, cur_list = {}, None, None
87
+ pending_nested = "" # a key whose block turned out to be a mapping, not a list
88
+ for raw in text.splitlines():
89
+ if not raw.strip() or raw.lstrip().startswith("#"):
90
+ continue
91
+ m = _HEAD.match(raw)
92
+ if m: # "- key: value" starts a new list item
93
+ if cur_list is None:
94
+ cur_list = []
95
+ cur = {}
96
+ if out.get("_pending_list"):
97
+ out[out.pop("_pending_list")] = cur_list
98
+ cur_list.append(cur)
99
+ cur[m.group(1)] = _scalar(m.group(2))
100
+ continue
101
+ m = re.match(r"^\s*(\w+)\s*:\s*$", raw)
102
+ if m: # "key:" with no value opens a list under that key
103
+ if pending_nested:
104
+ raise ValueError(
105
+ f"{pending_nested}: 下面跟着的是嵌套 mapping,内置解析器只支持一层;"
106
+ f"改成一行写法(packs: repo:test_cmd=...)或 pip install pyyaml"
107
+ )
108
+ out[m.group(1)] = []
109
+ cur_list = out[m.group(1)]
110
+ cur = None
111
+ pending_nested = m.group(1)
112
+ continue
113
+ m = re.match(r"^(\w+)\s*:\s*(.+)$", raw)
114
+ if m: # top-level "key: value" (no indentation, value present)
115
+ out[m.group(1)] = _scalar(m.group(2))
116
+ cur = None
117
+ cur_list = None
118
+ pending_nested = ""
119
+ continue
120
+ m = _KV.match(raw)
121
+ if m:
122
+ if cur is not None:
123
+ cur[m.group(1)] = _scalar(m.group(2))
124
+ elif pending_nested:
125
+ raise ValueError(
126
+ f"{pending_nested}: 下面跟着的是嵌套 mapping,内置解析器只支持一层;"
127
+ f"改成一行写法(packs: repo:test_cmd=...)或 pip install pyyaml"
128
+ )
129
+ else:
130
+ out[m.group(1)] = _scalar(m.group(2))
131
+ continue
132
+ if re.match(r"^\s*\w+\s*:", raw) is None and re.match(r"^\s+-\s", raw) is None:
133
+ raise ValueError(
134
+ f"无法解析的行(既不是 key: value,也不是 - key: value):{raw!r};"
135
+ "这种嵌套结构需要 PyYAML:pip install pyyaml"
136
+ )
137
+ if cur_list is not None:
138
+ for k, v in out.items():
139
+ if v is cur_list:
140
+ break
141
+ out.setdefault(k, v)
142
+ return out
143
+
144
+
145
+ def load_checks(path: str, allow_empty: bool = False) -> List[Check]:
146
+ """Load and validate checks from a .yaml / .json file.
147
+
148
+ allow_empty: a project that declares `packs:` may legitimately write no checks
149
+ of its own; the packs supply them.
150
+ """
151
+ if not os.path.exists(path):
152
+ raise FileNotFoundError(path)
153
+ with open(path, encoding="utf-8") as fh:
154
+ text = fh.read()
155
+ if path.endswith(".json"):
156
+ data = json.loads(text)
157
+ else:
158
+ data = _mini_yaml(text)
159
+ raw = data.get("checks") or []
160
+ checks = []
161
+ for i, item in enumerate(raw, 1):
162
+ item = dict(item)
163
+ item.setdefault("cid", f"C{i}")
164
+ item.setdefault("severity", "red")
165
+ item.setdefault("expect", "exit:0")
166
+ checks.append(Check(**{k: v for k, v in item.items() if k in Check.__annotations__}))
167
+ for c in checks:
168
+ c.validate()
169
+ if not checks and not allow_empty:
170
+ raise ValueError(f"{path}: 没有任何启用的检查项(注释模板不算);打开它,去掉 # 写下第一条")
171
+ ids = [c.cid for c in checks]
172
+ dup = {x for x in ids if ids.count(x) > 1}
173
+ if dup:
174
+ raise ValueError(f"duplicate check ids: {sorted(dup)}")
175
+ return checks
@@ -0,0 +1,243 @@
1
+ """Evidence: fresh, verifiable, traceable.
2
+
3
+ A check that cannot show *what was run*, *what came back*, and *when* did not run.
4
+ """
5
+ from __future__ import annotations
6
+
7
+ import hashlib
8
+ import os
9
+ import re
10
+ import shlex
11
+ import subprocess
12
+ import time
13
+ from dataclasses import dataclass, field
14
+ from typing import List, Optional
15
+
16
+
17
+ @dataclass
18
+ class Artifact:
19
+ path: str
20
+ exists: bool
21
+ size: int = 0
22
+ md5: str = ""
23
+
24
+
25
+ @dataclass
26
+ class Evidence:
27
+ command: str
28
+ exit_code: Optional[int]
29
+ stdout: str
30
+ stderr: str
31
+ seconds: float
32
+ started_at: str
33
+ artifacts: List[Artifact] = field(default_factory=list)
34
+ command_not_found: bool = False # the command itself never ran
35
+ not_found_hint: str = ""
36
+
37
+ def key_output(self, n: int = 3) -> str:
38
+ lines = [line for line in self.stdout.splitlines() if line.strip()]
39
+ return redact(" | ".join(lines[-n:]))[:400]
40
+
41
+ def missing(self, needs_stdout: bool = False) -> List[str]:
42
+ """Evidence three-piece self-check. Empty list == evidence is complete.
43
+
44
+ An exit-code-only assertion is fully evidenced by the exit code; demanding
45
+ stdout there would flag every quiet-but-correct check as incomplete.
46
+ """
47
+ gaps = []
48
+ if self.exit_code is None:
49
+ gaps.append("no exit code")
50
+ if needs_stdout and not self.stdout.strip():
51
+ gaps.append("assertion needs stdout but the command printed nothing")
52
+ if not self.started_at:
53
+ gaps.append("no timestamp")
54
+ for a in self.artifacts:
55
+ if not a.exists:
56
+ gaps.append(f"artifact missing: {a.path}")
57
+ return gaps
58
+
59
+
60
+ _SECRET = re.compile(
61
+ r"(AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}"
62
+ r"|xox[baprs]-[A-Za-z0-9-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)"
63
+ )
64
+
65
+
66
+ _NOT_FOUND = re.compile(
67
+ r"command not found" # bash/dash
68
+ r"|: not found" # sh
69
+ r"|is not recognized as an internal or external command" # cmd (en)
70
+ r"|不是内部或外部命令" # cmd (zh, GBK)
71
+ r"|не является внутренней", # cmd (ru) -- harmless extra
72
+ )
73
+
74
+
75
+ def _missing_tool(code, stderr: str, stdout: str = "") -> bool:
76
+ """Did the shell fail to find the command, rather than the command failing?
77
+
78
+ Exit codes alone are not usable here: measured on Windows, the same missing
79
+ command yields 1, 9009 and even 0 depending on the shell wrapper. The text is
80
+ the reliable signal; the codes only corroborate it.
81
+ """
82
+ if code == 9009: # cmd's dedicated "command not found"
83
+ return True
84
+ blob = (stderr or "") + "\n" + (stdout or "")
85
+ if _NOT_FOUND.search(blob):
86
+ return True
87
+ return code == 127 and not blob.strip().startswith("usage")
88
+
89
+
90
+ def _decode(raw: bytes) -> str:
91
+ """Decode a child process's output on any platform.
92
+
93
+ A Chinese Windows console writes GBK; decoding that as utf-8 with 'replace'
94
+ turns "不是内部或外部命令" into mojibake, which silently defeats the
95
+ "command not found" detection below.
96
+ """
97
+ for enc in ("utf-8", "gbk"):
98
+ try:
99
+ return raw.decode(enc)
100
+ except UnicodeDecodeError:
101
+ continue
102
+ return raw.decode("utf-8", "replace")
103
+
104
+
105
+ def redact(text: str) -> str:
106
+ """Never let a credential reach the ledger.
107
+
108
+ A check like `grep -n AKIA .env` is exactly the check you want, and its stdout
109
+ is exactly what must not land in a file you then commit. Detection uses the raw
110
+ text; only display is redacted.
111
+ """
112
+ return _SECRET.sub("***REDACTED***", text)
113
+
114
+
115
+ def _md5(path: str) -> str:
116
+ h = hashlib.md5()
117
+ with open(path, "rb") as fh:
118
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
119
+ h.update(chunk)
120
+ return h.hexdigest()
121
+
122
+
123
+ def _split_argv(command: str) -> List[str]:
124
+ """Split a command into argv without a shell (the default path)."""
125
+ try:
126
+ return shlex.split(command, posix=True)
127
+ except ValueError as exc:
128
+ raise ValueError(
129
+ f"命令无法拆成参数({exc})。如果用了管道 | 重定向 > $() 或 &&,"
130
+ f"请在检查项上显式写 shell: bash"
131
+ )
132
+
133
+
134
+ def find_posix_shell() -> str:
135
+ """Locate a real POSIX shell; on Windows this must be Git Bash.
136
+
137
+ Deliberately does NOT consult PATH on Windows: `where bash` resolves to
138
+ C:\\Windows\\System32\\bash.exe, which is the WSL entry point and uses an
139
+ entirely different path scheme (/mnt/e/... vs /e/...).
140
+ """
141
+ import shutil
142
+ if os.name != "nt":
143
+ for name in ("bash", "sh"):
144
+ path = shutil.which(name)
145
+ if path:
146
+ return path
147
+ return ""
148
+ candidates = [
149
+ r"C:\\Program Files\\Git\\bin\\bash.exe",
150
+ r"C:\\Program Files (x86)\\Git\\bin\\bash.exe",
151
+ os.path.join(os.path.expanduser("~"), "AppData", "Local", "Programs",
152
+ "Git", "bin", "bash.exe"),
153
+ ]
154
+ for path in candidates:
155
+ if os.path.exists(path):
156
+ return path
157
+ return ""
158
+
159
+
160
+ def _build_argv(command: str, shell: str):
161
+ """-> (argv, error). An error means the check could not be run at all."""
162
+ import shutil
163
+ shell = (shell or "").strip().lower()
164
+ if not shell:
165
+ try:
166
+ return _split_argv(command), ""
167
+ except ValueError as exc:
168
+ return [], str(exc)
169
+ if shell in ("bash", "sh"):
170
+ found = find_posix_shell()
171
+ if not found:
172
+ return [], (f"检查项声明 shell: {shell},但本机没找到可用的 POSIX shell"
173
+ f"(Windows 请安装 Git Bash,或改用 builtin: 检查项)")
174
+ return [found, "-lc", command], ""
175
+ if shell == "cmd":
176
+ if os.name != "nt":
177
+ return [], "shell: cmd 只能在 Windows 上使用"
178
+ return ["cmd", "/c", command], ""
179
+ if shell in ("powershell", "pwsh"):
180
+ exe = shutil.which(shell)
181
+ if not exe:
182
+ return [], f"检查项声明 shell: {shell},但没找到该可执行文件"
183
+ return [exe, "-Command", command], ""
184
+ return [], f"未知 shell {shell!r}"
185
+
186
+
187
+ def collect(command: str, cwd: str = ".", timeout: int = 120,
188
+ artifacts: Optional[List[str]] = None, shell: str = "") -> Evidence:
189
+ """Run a shell command and record everything needed to re-check it later."""
190
+ from . import builtin
191
+ if builtin.is_builtin(command):
192
+ return builtin.dispatch(command, cwd=cwd)
193
+
194
+ started = time.strftime("%Y-%m-%dT%H:%M:%S")
195
+ t0 = time.time()
196
+ argv, build_error = _build_argv(command, shell)
197
+ missing_tool = False
198
+ if build_error:
199
+ return Evidence(command, None, "", build_error, 0.0, started, [],
200
+ True, build_error)
201
+ env = dict(os.environ)
202
+ env.setdefault("PYTHONIOENCODING", "utf-8")
203
+ try:
204
+ p = subprocess.run(argv, cwd=cwd, capture_output=True,
205
+ timeout=timeout, env=env)
206
+ code = p.returncode
207
+ out, err = _decode(p.stdout), _decode(p.stderr)
208
+ except FileNotFoundError:
209
+ code, out = 127, ""
210
+ err = (f"命令未找到:{argv[0] if argv else command}(默认不经 shell 直接执行;"
211
+ f"若命令里有 | > $() && 等语法,请在该检查项上写 shell: bash)")
212
+ missing_tool = True
213
+ except subprocess.TimeoutExpired:
214
+ code, out, err = None, "", f"timeout after {timeout}s"
215
+ except Exception as exc: # pragma: no cover - environment failure path
216
+ code, out, err = None, "", f"could not run: {exc}"
217
+
218
+ missing_tool = missing_tool or _missing_tool(code, err, out)
219
+ arts = []
220
+ for rel in artifacts or []:
221
+ full = rel if os.path.isabs(rel) else os.path.join(cwd, rel)
222
+ if os.path.exists(full):
223
+ arts.append(Artifact(rel, True, os.path.getsize(full), _md5(full)))
224
+ else:
225
+ arts.append(Artifact(rel, False))
226
+
227
+ hint = ""
228
+ if missing_tool:
229
+ hint = (err.strip().splitlines() or [""])[0][:120]
230
+ return Evidence(command, code, out, err, round(time.time() - t0, 2), started, arts,
231
+ missing_tool, hint)
232
+
233
+
234
+ def artifacts_in(expect: str) -> List[str]:
235
+ """Pull artifact paths out of an expect string (file:/md5: clauses)."""
236
+ paths = []
237
+ for clause in expect.split(";"):
238
+ clause = clause.strip()
239
+ if clause.startswith("file:"):
240
+ paths.append(clause[5:].strip())
241
+ elif clause.startswith("md5:"):
242
+ paths.append(clause.split("=")[0][4:].strip())
243
+ return paths
evidgate/core/gate.py ADDED
@@ -0,0 +1,154 @@
1
+ """Three-state gate: PASS / DIFF (yellow) / FAIL (red).
2
+
3
+ Two states is not enough. Forcing every "has evidence but differs from intent" item
4
+ into FAIL makes a run that can never be green; nobody looks at the report after that.
5
+ Downgrading red to yellow is worse: it is a fake pass.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import os
11
+ import re
12
+ from dataclasses import dataclass
13
+ from typing import List, Tuple
14
+
15
+ from .check import Check
16
+ from .evidence import Evidence, artifacts_in, collect
17
+
18
+ PASS, DIFF, FAIL, PENDING, SKIP = "PASS", "DIFF", "FAIL", "PENDING", "SKIP"
19
+ LABEL = {PASS: "PASS", DIFF: "DIFF(黄)", FAIL: "FAIL(红)",
20
+ PENDING: "待补", SKIP: "SKIP(未覆盖)"}
21
+
22
+
23
+ @dataclass
24
+ class Verdict:
25
+ cid: str
26
+ status: str
27
+ detail: str
28
+ evidence: Evidence
29
+
30
+ @property
31
+ def done(self) -> bool:
32
+ return self.status in (PASS, DIFF, FAIL)
33
+
34
+
35
+ def _md5(path: str) -> str:
36
+ h = hashlib.md5()
37
+ with open(path, "rb") as fh:
38
+ for chunk in iter(lambda: fh.read(1 << 20), b""):
39
+ h.update(chunk)
40
+ return h.hexdigest()
41
+
42
+
43
+ def evaluate(check: Check, ev: Evidence, cwd: str = ".") -> Tuple[str, str]:
44
+ """Return (status, detail). Pure function of check + evidence + cwd."""
45
+ expr = check.expect.strip()
46
+ if not expr or expr == "manual":
47
+ return PENDING, "manual: no command assertion declared"
48
+
49
+ notes: List[str] = []
50
+ ok = True
51
+ for clause in [c.strip() for c in expr.split(";") if c.strip()]:
52
+ kind, _, arg = clause.partition(":")
53
+ kind, arg = kind.strip(), arg.strip()
54
+
55
+ if kind == "exit":
56
+ want = int(arg)
57
+ good = ev.exit_code == want
58
+ note = f"exit {ev.exit_code} (want {want})"
59
+ if not good and ev.exit_code == 127:
60
+ note += (" | 命令未找到(127):它不在 PATH 里。改用 "
61
+ "builtin:<plugin>:<rule>,或写绝对路径")
62
+ elif not good:
63
+ tail = ev.key_output(2) or (ev.stderr.strip().splitlines() or [""])[-1][:160]
64
+ if tail:
65
+ note += f" | got: {tail}"
66
+ elif kind == "contains":
67
+ good = arg in ev.stdout
68
+ note = f"contains {'OK' if good else 'MISSING'}:{arg}"
69
+ elif kind == "not_contains":
70
+ good = arg not in ev.stdout
71
+ note = f"not_contains {'OK' if good else 'HIT'}:{arg}"
72
+ elif kind == "regex":
73
+ m = re.search(arg, ev.stdout, re.M)
74
+ good = bool(m)
75
+ note = f"regex {'OK' if good else 'MISS'} ─ {arg}"
76
+ if m:
77
+ note += f" -> {m.group(0)[:40]}"
78
+ elif kind == "lines>=":
79
+ n = len([line for line in ev.stdout.splitlines() if line.strip()])
80
+ good = n >= int(arg)
81
+ note = f"lines {n} (want >={arg})"
82
+ elif kind == "lines<=":
83
+ n = len([line for line in ev.stdout.splitlines() if line.strip()])
84
+ good = n <= int(arg)
85
+ note = f"lines {n} (want <={arg})"
86
+ elif kind == "file":
87
+ full = arg if os.path.isabs(arg) else os.path.join(cwd, arg)
88
+ good = os.path.exists(full)
89
+ note = f"file {'exists' if good else 'MISSING'}:{arg}"
90
+ elif kind == "md5":
91
+ path, _, want = arg.partition("=")
92
+ full = path if os.path.isabs(path) else os.path.join(cwd, path)
93
+ got = _md5(full) if os.path.exists(full) else ""
94
+ good = got == want.strip()
95
+ note = f"md5 {'MATCH' if good else 'MISMATCH'}:{path}"
96
+ else:
97
+ good, note = False, f"unknown clause '{clause}'"
98
+
99
+ notes.append(("+" if good else "-") + note)
100
+ ok = ok and good
101
+
102
+ if ok:
103
+ return PASS, " ; ".join(notes)
104
+ return (FAIL if check.severity == "red" else DIFF), " ; ".join(notes)
105
+
106
+
107
+ def run_check(check: Check, cwd: str = ".") -> Verdict:
108
+ ev = collect(check.method, cwd=cwd, timeout=check.timeout,
109
+ artifacts=artifacts_in(check.expect), shell=check.shell)
110
+ if ev.command_not_found:
111
+ # The command never ran. On Windows `grep ...` exits 1, which is exactly
112
+ # what `expect: exit:1` ("grep found nothing") wants -- so a check can flip
113
+ # to green without having looked at anything.
114
+ hint = f" ({ev.not_found_hint})" if ev.not_found_hint else ""
115
+ return Verdict(check.cid, SKIP if check.optional else FAIL,
116
+ f"命令未找到{hint}:检查没能执行,不能算通过", ev)
117
+ status, detail = evaluate(check, ev, cwd=cwd)
118
+ if check.optional and status in (FAIL, DIFF):
119
+ return Verdict(check.cid, SKIP, "optional (未覆盖): " + detail, ev)
120
+ gaps = ev.missing(needs_stdout=any(k in check.expect for k in ("contains", "regex", "lines")))
121
+ if status in (PASS, DIFF) and gaps:
122
+ # a green verdict built on incomplete evidence is not a green verdict
123
+ status = PENDING if check.expect.strip() == "manual" else status
124
+ detail += " | evidence gaps: " + ", ".join(gaps)
125
+ return Verdict(check.cid, status, detail, ev)
126
+
127
+
128
+ def summarize(verdicts: List[Verdict]) -> dict:
129
+ counts = {PASS: 0, DIFF: 0, FAIL: 0, PENDING: 0, SKIP: 0}
130
+ for v in verdicts:
131
+ counts[v.status] = counts.get(v.status, 0) + 1
132
+ total = len(verdicts)
133
+ done = counts[PASS] + counts[DIFF] + counts[FAIL] + counts.get(SKIP, 0)
134
+ return {
135
+ **counts,
136
+ "total": total,
137
+ "done": done,
138
+ "coverage": 0.0 if total == 0 else round(done / total, 3),
139
+ }
140
+
141
+
142
+ def release_allowed(verdicts: List[Verdict]) -> Tuple[bool, str]:
143
+ """Red blocks. Yellow goes to a confirmation list. Pending is never 'done'."""
144
+ fails = [v for v in verdicts if v.status == FAIL]
145
+ pend = [v for v in verdicts if v.status == PENDING]
146
+ if fails:
147
+ return False, "blocked by " + ", ".join(v.cid for v in fails)
148
+ if pend:
149
+ return False, "unchecked: " + ", ".join(v.cid for v in pend)
150
+ skips = [v for v in verdicts if v.status == SKIP]
151
+ tail = "; yellow items go to the confirmation list"
152
+ if skips:
153
+ tail += f" ({len(skips)} optional/未覆盖: " + ", ".join(v.cid for v in skips) + ")"
154
+ return True, "all red checks green" + tail