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/core/packs.py ADDED
@@ -0,0 +1,90 @@
1
+ """Reusable check bundles.
2
+
3
+ `packs: figures, build:outdir=dist` in evidgate.yaml pulls in ready-made checks.
4
+ A pack is nothing but checks with placeholders -- it obeys the same rule as a
5
+ hand-written check: no counter-test, no load.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import re
11
+ from typing import Dict, List, Tuple
12
+
13
+ from .check import Check, _mini_yaml
14
+
15
+ PACK_DIR = os.path.join(
16
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "packs"
17
+ )
18
+
19
+ # Defaults so `packs: figures` works with no arguments. Override with
20
+ # `packs: figures manifest=my.json,outdir=figs`.
21
+ DEFAULTS: Dict[str, Dict[str, str]] = {
22
+ "figures": {"manifest": "artifacts.json", "outdir": "png"},
23
+ "build": {
24
+ "outdir": "dist",
25
+ "secret": "AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}"
26
+ "|-----BEGIN [A-Z ]*PRIVATE KEY-----",
27
+ },
28
+ "repo": {"test_cmd": "python3 -m pytest -q", "pattern": "TODO|FIXME|breakpoint\\(\\)"},
29
+ }
30
+
31
+ _PH = re.compile(r"\{(\w+)\}")
32
+
33
+
34
+ def available() -> List[str]:
35
+ if not os.path.isdir(PACK_DIR):
36
+ return []
37
+ return sorted(f[:-5] for f in os.listdir(PACK_DIR) if f.endswith(".yaml"))
38
+
39
+
40
+ def _split(entry) -> Tuple[str, Dict[str, str]]:
41
+ """'figures:manifest=a.json,outdir=figs' -> ('figures', {...})"""
42
+ if not isinstance(entry, str):
43
+ return str(entry.get("name", "")), dict(entry.get("options") or {})
44
+ head, _, tail = entry.partition(":")
45
+ opts: Dict[str, str] = {}
46
+ for pair in tail.split(","):
47
+ if "=" in pair:
48
+ k, v = pair.split("=", 1)
49
+ opts[k.strip()] = v.strip().strip("\"'")
50
+ return head.strip(), opts
51
+
52
+
53
+ def _sub(text: str, params: Dict[str, str], pack: str) -> str:
54
+ def rep(m):
55
+ key = m.group(1)
56
+ if key not in params:
57
+ raise SystemExit(
58
+ f"pack {pack}: 没有 {key} 的值。写法:packs: {pack}:{key}=..."
59
+ )
60
+ return params[key]
61
+
62
+ return _PH.sub(rep, text)
63
+
64
+
65
+ def load_packs(entries) -> List[Check]:
66
+ out: List[Check] = []
67
+ for entry in entries:
68
+ name, opts = _split(entry)
69
+ if not name:
70
+ continue
71
+ path = os.path.join(PACK_DIR, name + ".yaml")
72
+ if not os.path.exists(path):
73
+ raise SystemExit(
74
+ f"unknown pack {name!r}; 可用:{', '.join(available()) or '(none)'}"
75
+ )
76
+ with open(path, encoding="utf-8") as fh:
77
+ cfg = _mini_yaml(fh.read())
78
+ params = dict(DEFAULTS.get(name) or {})
79
+ params.update(opts)
80
+ for item in cfg.get("checks") or []:
81
+ item = dict(item)
82
+ for key in ("name", "method", "expect", "counter", "note"):
83
+ if isinstance(item.get(key), str):
84
+ item[key] = _sub(item[key], params, name)
85
+ item.setdefault("severity", "red")
86
+ check = Check(**{k: v for k, v in item.items() if k in Check.__annotations__})
87
+ check.validate()
88
+ check.note = (check.note + f" [pack:{name}]").strip()
89
+ out.append(check)
90
+ return out
@@ -0,0 +1,185 @@
1
+ """Look at a project and say what is worth checking.
2
+
3
+ The first minute with a gate tool is the hard part: the config is empty and the
4
+ user has no idea whether their project even has anything to check. This module
5
+ answers that question from evidence on disk -- directories, file types, a
6
+ bibliography -- instead of from a template.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ import re
12
+ from dataclasses import dataclass, field
13
+ from typing import Dict, List
14
+
15
+ FIG_DIRS = ("figures", "figs", "plots", "charts", "images", "imgs", "img", "pictures")
16
+ # Vector/authoring sources that real theses actually use, not just SVG.
17
+ FIG_SRC_EXTS = (".svg", ".fig", ".dia", ".drawio", ".ipe", ".gp")
18
+ FIG_OUT_EXTS = (".png", ".pdf", ".eps", ".jpg", ".jpeg", ".tif", ".tiff")
19
+ # A script or Makefile that regenerates the figures is proof of a derivation chain
20
+ # even when the produced file is not checked in next to its source.
21
+ GEN_HINT = re.compile(r"(mkplot|mkfig|mkimage|makefig|makeplot|plot.*\.sh|fig.*\.sh)", re.I)
22
+ OUT_DIRS = ("dist", "build", "output", "out", "release")
23
+ DOC_NAMES = ("paper.md", "draft.md", "manuscript.md", "report.md")
24
+ # files evidgate itself (or common project furniture) writes; never "documents to audit"
25
+ SKIP_DOCS = {"readme.md", "changelog.md", "license.md", "contributing.md",
26
+ "evidgate_ledger.md", "gate_report.md", "gate_report.example.md"}
27
+ TEST_HINTS = ("test_", "_test.", "tests", "spec")
28
+
29
+
30
+ @dataclass
31
+ class Finding:
32
+ what: str
33
+ packs: List[str] = field(default_factory=list)
34
+ note: str = ""
35
+
36
+
37
+ def _stems(root: str, ext: str) -> set:
38
+ """Basenames (without extension) of files with this extension, anywhere."""
39
+ out = set()
40
+ for dirpath, dirnames, filenames in os.walk(root):
41
+ dirnames[:] = [d for d in dirnames if d != ".git"]
42
+ out |= {os.path.splitext(f)[0] for f in filenames if f.lower().endswith(ext)}
43
+ return out
44
+
45
+
46
+ def _count(root: str, ext: str) -> int:
47
+ """Count files by extension anywhere under root (skipping .git)."""
48
+ total = 0
49
+ for dirpath, dirnames, filenames in os.walk(root):
50
+ dirnames[:] = [d for d in dirnames if d != ".git"]
51
+ total += sum(1 for f in filenames if f.lower().endswith(ext))
52
+ return total
53
+
54
+
55
+ def _has_bibliography(path: str) -> bool:
56
+ try:
57
+ with open(path, encoding="utf-8", errors="replace") as fh:
58
+ text = fh.read()
59
+ except OSError:
60
+ return False
61
+ if re.search(r"^#{1,3}\s*(参考文献|References|Bibliography)", text, re.M | re.I):
62
+ return True
63
+ return len(re.findall(r"^\s*\[\d+\]\s+\S", text, re.M)) >= 3
64
+
65
+
66
+ def probe(root: str = ".") -> Dict[str, object]:
67
+ """Return findings plus the packs they imply. Read-only."""
68
+ findings: List[Finding] = []
69
+ packs: List[str] = []
70
+ entries = os.listdir(root) if os.path.isdir(root) else []
71
+
72
+ # 1. figures: a vector source plus a raster/print derivative somewhere in the tree
73
+ # Only a shared basename proves a derivative relationship (a.svg -> a.png).
74
+ # A tree with unrelated svgs and pngs has nothing for the figures pack to guard:
75
+ # it would go green on an empty check set, which is worse than saying nothing.
76
+ src_stems = set()
77
+ for ext in FIG_SRC_EXTS:
78
+ src_stems |= _stems(root, ext)
79
+ out_stems = set()
80
+ for ext in FIG_OUT_EXTS:
81
+ out_stems |= _stems(root, ext)
82
+ paired = src_stems & out_stems
83
+ gen_scripts = [f for f in entries if GEN_HINT.search(f)]
84
+ has_makefile = any(f.lower() in ("makefile", "makefile.am") for f in entries)
85
+ # Two independent ways to see a derivation chain:
86
+ # 1. same basename in a source format and an output format (a.svg -> a.png)
87
+ # 2. a figure-generating script or Makefile plus outputs on disk
88
+ chained = bool(paired) or bool(gen_scripts) or (has_makefile and out_stems)
89
+ if (src_stems or gen_scripts) and out_stems and chained:
90
+ where = next((n for n in FIG_DIRS if os.path.isdir(os.path.join(root, n))), ".")
91
+ outs = sum(_count(root, e) for e in FIG_OUT_EXTS)
92
+ proof = (f"{len(paired)} 组同名" if paired
93
+ else ("生成脚本 " + "、".join(gen_scripts[:2]) if gen_scripts
94
+ else ("Makefile" if has_makefile else "输出文件")))
95
+ findings.append(Finding(
96
+ what=f"{where} 一带:{outs} 个位图/PDF 输出,派生依据:{proof}",
97
+ packs=["figures"],
98
+ note="有源就有派生链 —— figures 包盯的是「派生是不是跟着源更新」"))
99
+ packs.append("figures")
100
+
101
+ # 2. build output directories
102
+ for name in OUT_DIRS:
103
+ d = os.path.join(root, name)
104
+ if os.path.isdir(d):
105
+ n = sum(len(fs) for _r, _ds, fs in os.walk(d))
106
+ if n:
107
+ findings.append(Finding(
108
+ what=f"{name}/ 里有 {n} 个文件",
109
+ packs=["build"],
110
+ note="交付前值得确认:非空、无明文密钥、无临时文件"))
111
+ packs.append("build")
112
+ break
113
+
114
+ # 3. documents with a bibliography (README alone is not a document to audit)
115
+ doc_hit = None
116
+ for name in DOC_NAMES:
117
+ p = os.path.join(root, name)
118
+ if os.path.isfile(p) and _has_bibliography(p):
119
+ doc_hit = name
120
+ break
121
+ if doc_hit:
122
+ findings.append(Finding(
123
+ what=f"{doc_hit} 带参考文献表",
124
+ packs=[],
125
+ note="prose 检查可用:evidgate prose-init(列而不引、缺口径、绝对化词)"))
126
+ else:
127
+ docs = [f for f in entries
128
+ if f.lower().endswith(".md") and f.lower() not in SKIP_DOCS]
129
+ if len(docs) >= 2:
130
+ findings.append(Finding(
131
+ what=f"有 {len(docs)} 个 .md({', '.join(docs[:3])}…),没有识别到参考文献表",
132
+ note="正文要与文献表对得上,得用 [n] 编号制;否则 citation_chain 无法判断"))
133
+
134
+ # 4. tests
135
+ has_tests = any(any(h in e.lower() for h in TEST_HINTS) for e in entries)
136
+ if not has_tests:
137
+ has_tests = any(os.path.isdir(os.path.join(root, n)) for n in ("tests", "test", "spec"))
138
+ if has_tests:
139
+ findings.append(Finding(what="有测试文件或 tests/ 目录", packs=["repo"],
140
+ note="交付前跑一遍单测;没装依赖的话用 optional: true"))
141
+ packs.append("repo")
142
+
143
+ # 5. credential risk: a secret-looking file that is not ignored
144
+ risky = [n for n in (".env", "secrets.yml", "credentials.json")
145
+ if os.path.isfile(os.path.join(root, n))]
146
+ if risky:
147
+ findings.append(Finding(
148
+ what="存在 " + "、".join(risky),
149
+ note="确认它被 .gitignore 挡住;build 包的密钥扫描只查交付目录"))
150
+
151
+ # de-duplicate, keep order
152
+ seen, ordered = set(), []
153
+ for p in packs:
154
+ if p not in seen:
155
+ seen.add(p)
156
+ ordered.append(p)
157
+
158
+ return {"findings": findings, "packs": ordered}
159
+
160
+
161
+ def render(result: Dict[str, object]) -> str:
162
+ findings: List[Finding] = result["findings"] # type: ignore[assignment]
163
+ packs: List[str] = result["packs"] # type: ignore[assignment]
164
+ lines: List[str] = []
165
+ if not findings:
166
+ lines.append("这个目录里没扫到图目录、构建产物、文档或测试 —— 不需要 evidgate。")
167
+ return "\n".join(lines)
168
+
169
+ lines.append("扫到的东西:")
170
+ for f in findings:
171
+ lines.append(f" · {f.what}")
172
+ if f.note:
173
+ lines.append(f" → {f.note}")
174
+
175
+ lines.append("")
176
+ if packs:
177
+ spec = ", ".join(packs)
178
+ lines.append("建议在 evidgate.yaml 里写一行:")
179
+ lines.append(f" packs: {spec}")
180
+ lines.append("")
181
+ lines.append(f"生成它:evidgate init --packs {spec.replace(', ', ',')}")
182
+ else:
183
+ lines.append("没有现成的包能覆盖上面这些 —— 需要自己写检查项。")
184
+
185
+ return "\n".join(lines)
@@ -0,0 +1,4 @@
1
+ """Ledger: one line is the check, the evidence, the resume point and the decision."""
2
+ from .table import build, load_rows, render, resume_cids
3
+
4
+ __all__ = ["build", "load_rows", "resume_cids", "render"]
@@ -0,0 +1,135 @@
1
+ """The ledger table.
2
+
3
+ Why one table: a report and a ledger kept apart drift. Here a line carries the check,
4
+ its command, its counter-test, the evidence, the timestamp and the verdict -- so
5
+ "what is left" and "what proves it" are the same read.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import re
11
+ from typing import Dict, List, Optional
12
+
13
+ from ..core.check import Check
14
+ from ..core.gate import LABEL, Verdict
15
+
16
+ HEADER = ("| cid | check | method | expect | counter-test | sev | status | evidence | ts |\n"
17
+ "|---|---|---|---|---|---|---|---|---|\n")
18
+
19
+
20
+ def _cell(s: str, limit: int = 90) -> str:
21
+ s = (s or "").replace("|", "\\|").replace("\n", " ").strip()
22
+ return s if len(s) <= limit else s[: limit - 1] + "…"
23
+
24
+
25
+ def _evidence_cell(v: Optional[Verdict]) -> str:
26
+ if v is None:
27
+ return "—"
28
+ ev = v.evidence
29
+ bits = [f"`{_cell(ev.command, 60)}`", f"exit={ev.exit_code}"]
30
+ if ev.stdout.strip():
31
+ bits.append(f"out: {_cell(ev.key_output(2), 60)}")
32
+ for a in ev.artifacts:
33
+ if a.exists:
34
+ bits.append(f"{a.path} {a.size}B md5={a.md5[:8]}")
35
+ else:
36
+ bits.append(f"{a.path} MISSING")
37
+ bits.append(f"{ev.seconds}s")
38
+ return _cell(" · ".join(bits), 200)
39
+
40
+
41
+ def render(checks: List[Check], verdicts: Dict[str, Verdict],
42
+ project: str = "project", prev: Optional[Dict[str, dict]] = None) -> str:
43
+ prev = prev or {}
44
+ body = []
45
+ for c in checks:
46
+ v = verdicts.get(c.cid)
47
+ if v is None and c.cid in prev and prev[c.cid]["status"] not in ("—", ""):
48
+ # resumed run: keep the row we already verified instead of blanking it
49
+ row = prev[c.cid]
50
+ body.append("| " + " | ".join([
51
+ c.cid, _cell(c.name, 46), f"`{_cell(c.method, 70)}`",
52
+ f"`{_cell(c.expect, 40)}`", _cell(c.counter, 46), c.severity,
53
+ row["status"], _cell(row["evidence"], 200), row["ts"],
54
+ ]) + " |")
55
+ continue
56
+ body.append("| " + " | ".join([
57
+ c.cid,
58
+ _cell(c.name, 46),
59
+ f"`{_cell(c.method, 70)}`",
60
+ f"`{_cell(c.expect, 40)}`",
61
+ _cell(c.counter, 46),
62
+ c.severity,
63
+ LABEL.get(v.status, "—") if v else "—",
64
+ _evidence_cell(v),
65
+ (v.evidence.started_at if v else "—"),
66
+ ]) + " |")
67
+
68
+ counts = {"PASS": 0, "DIFF": 0, "FAIL": 0, "PENDING": 0}
69
+ for c in checks:
70
+ v = verdicts.get(c.cid)
71
+ if v:
72
+ counts[v.status] = counts.get(v.status, 0) + 1
73
+ total = len(checks)
74
+ done = counts["PASS"] + counts["DIFF"] + counts["FAIL"]
75
+ pct = 0 if total == 0 else round(100 * done / total, 1)
76
+
77
+ head = [
78
+ f"# evidgate ledger · {project}",
79
+ "",
80
+ "> One line == one check == one piece of evidence == one resume point.",
81
+ "> Rebuild it with `evidgate run`; do not edit verdicts by hand.",
82
+ "",
83
+ HEADER.rstrip("\n"),
84
+ ]
85
+ tail = [
86
+ "",
87
+ "## progress",
88
+ "",
89
+ f"- total: {total} · PASS {counts['PASS']} · DIFF(黄) {counts['DIFF']} · "
90
+ f"FAIL(红) {counts['FAIL']} · 待补 {counts['PENDING']}",
91
+ f"- coverage: {done}/{total} ({pct}%)",
92
+ "",
93
+ ]
94
+ return "\n".join(head + body) + "\n" + "\n".join(tail)
95
+
96
+
97
+ def build(path: str, checks: List[Check], verdicts: Dict[str, Verdict],
98
+ project: str = "project", previous: Optional[Dict[str, dict]] = None) -> str:
99
+ """Write the ledger. Idempotent: same checks + same verdicts -> same bytes."""
100
+ text = render(checks, verdicts, project)
101
+ os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
102
+ with open(path, "w", encoding="utf-8", newline="\n") as fh:
103
+ fh.write(text)
104
+ return text
105
+
106
+
107
+ _ROW = re.compile(r"^\|\s*([A-Za-z]+\d+)\s*\|")
108
+
109
+
110
+ def load_rows(path: str) -> Dict[str, dict]:
111
+ """Parse existing ledger rows -> {cid: {status, evidence, ts}} (for resume)."""
112
+ if not os.path.exists(path):
113
+ return {}
114
+ rows: Dict[str, dict] = {}
115
+ with open(path, encoding="utf-8") as fh:
116
+ lines = fh.readlines()
117
+ for line in lines:
118
+ m = _ROW.match(line)
119
+ if not m:
120
+ continue
121
+ cells = [c.strip() for c in line.strip().strip("|").split("|")]
122
+ if len(cells) < 9:
123
+ continue
124
+ rows[cells[0]] = {"status": cells[6], "evidence": cells[7], "ts": cells[8]}
125
+ return rows
126
+
127
+
128
+ def resume_cids(checks: List[Check], rows: Dict[str, dict]) -> List[str]:
129
+ """Checks never run, or run but unresolved, are the resume set."""
130
+ out = []
131
+ for c in checks:
132
+ row = rows.get(c.cid)
133
+ if not row or row["status"] in ("—", "待补", ""):
134
+ out.append(c.cid)
135
+ return out
@@ -0,0 +1,25 @@
1
+ # pack: build — 构建产物交付前的完整性
2
+ checks:
3
+ - cid: GB1
4
+ shell: bash
5
+ name: 构建产物目录非空({outdir})
6
+ method: test -d {outdir} -a -n "$(ls -A {outdir} 2>/dev/null)"
7
+ expect: exit:0
8
+ counter: 清空 {outdir}/ 后,本项必须变红
9
+ severity: red
10
+ - cid: GB2
11
+ shell: bash
12
+ name: 交付物里没有明文密钥
13
+ method: grep -rIl -E "{secret}" {outdir}
14
+ expect: exit:1
15
+ counter: 在 {outdir}/ 放一个假的 AKIA 开头令牌后,本项必须变红
16
+ severity: red
17
+ note: 命中时只报文件名与所在项,不把密钥本身写进台账
18
+ - cid: GB3
19
+ shell: bash
20
+ name: 交付物里没有临时文件(.tmp/.bak/.swp/.orig)
21
+ method: test -z "$(find {outdir} -type f \( -name '*.tmp' -o -name '*.bak' -o -name '*.swp' -o -name '*.orig' \) -print -quit)"
22
+ expect: exit:0
23
+ counter: 在 {outdir}/ 放一个 a.tmp 后,本项必须变红
24
+ severity: red
25
+ note: 按文件名判断;早先误用 grep 搜文件内容,放了 .bak 也报 PASS
@@ -0,0 +1,29 @@
1
+ # pack: figures — 一个源、多种派生的产物目录(svg -> png/pdf/eps)
2
+ checks:
3
+ - cid: GF0
4
+ name: 清单里至少有一条派生项({manifest})
5
+ method: builtin:artifact:derivatives {manifest}
6
+ expect: exit:0
7
+ counter: 把 artifacts.json 里所有 role 改成 source 后,本项必须变红
8
+ severity: red
9
+ note: 没有派生项时,后三项全在空转 —— 先标注谁是派生
10
+ - cid: GF1
11
+ name: 派生登记齐全且未被手改({manifest})
12
+ method: builtin:artifact:manifest {manifest}
13
+ expect: exit:0
14
+ counter: 手改任一派生文件的字节后,本项必须变红
15
+ severity: red
16
+ note: 登记与哈希都写在 {manifest} 里;用 evidgate artifact-init 生成初稿
17
+ - cid: GF2
18
+ name: 派生是否跟随源的变化
19
+ method: builtin:artifact:stale {manifest}
20
+ expect: exit:0
21
+ counter: 改源但不重新生成派生后,本项必须变黄
22
+ severity: yellow
23
+ note: 从未盖过章的派生只会报「无法判断」,不算错
24
+ - cid: GF3
25
+ name: {outdir}/ 里没有漏纳管的文件
26
+ method: builtin:artifact:orphan {manifest} --dir {outdir}
27
+ expect: exit:0
28
+ counter: 在 {outdir}/ 放一个未登记的图后,本项必须变黄
29
+ severity: yellow
@@ -0,0 +1,17 @@
1
+ # pack: repo — 代码交付前的最后两道
2
+ checks:
3
+ - cid: GR1
4
+ shell: bash
5
+ name: 单测全绿
6
+ method: {test_cmd}
7
+ expect: exit:0
8
+ counter: 改坏一个断言后,本项必须变红
9
+ severity: red
10
+ note: 参数化:packs: repo test_cmd="python3 -m pytest -q"
11
+ - cid: GR2
12
+ shell: bash
13
+ name: 没有遗留调试钩子({pattern})
14
+ method: grep -rn -E "{pattern}" --include=*.py .
15
+ expect: exit:1
16
+ counter: 在任一 .py 里加一行 TODO 后,本项必须变黄
17
+ severity: yellow
@@ -0,0 +1 @@
1
+ """Plugins supply checks; the engine does not know what a document is."""