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.
- evidgate/__init__.py +6 -0
- evidgate/cli.py +599 -0
- evidgate/core/__init__.py +10 -0
- evidgate/core/builtin.py +105 -0
- evidgate/core/check.py +175 -0
- evidgate/core/evidence.py +243 -0
- evidgate/core/gate.py +154 -0
- evidgate/core/packs.py +90 -0
- evidgate/core/suggest.py +185 -0
- evidgate/ledger/__init__.py +4 -0
- evidgate/ledger/table.py +135 -0
- evidgate/packs/build.yaml +25 -0
- evidgate/packs/figures.yaml +29 -0
- evidgate/packs/repo.yaml +17 -0
- evidgate/plugins/__init__.py +1 -0
- evidgate/plugins/artifact.py +303 -0
- evidgate/plugins/prose.py +181 -0
- evidgate-0.9.2.dist-info/METADATA +386 -0
- evidgate-0.9.2.dist-info/RECORD +23 -0
- evidgate-0.9.2.dist-info/WHEEL +5 -0
- evidgate-0.9.2.dist-info/entry_points.txt +2 -0
- evidgate-0.9.2.dist-info/licenses/LICENSE +21 -0
- evidgate-0.9.2.dist-info/top_level.txt +1 -0
evidgate/core/builtin.py
ADDED
|
@@ -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
|