pubrules 0.48.0__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.
- pubrules/__init__.py +14 -0
- pubrules/audit.py +116 -0
- pubrules/audit_draft.py +295 -0
- pubrules/audit_prepare.py +1128 -0
- pubrules/cache.py +319 -0
- pubrules/cbor.py +45 -0
- pubrules/ci.py +910 -0
- pubrules/cli.py +1069 -0
- pubrules/conform.py +295 -0
- pubrules/doc_coverage.py +235 -0
- pubrules/freshness.py +75 -0
- pubrules/gherkin.py +348 -0
- pubrules/hooks.py +59 -0
- pubrules/hosting.py +372 -0
- pubrules/ignores.py +86 -0
- pubrules/new.py +242 -0
- pubrules/nightly.py +1002 -0
- pubrules/paths.py +32 -0
- pubrules/protect.py +596 -0
- pubrules/providers.py +129 -0
- pubrules/refs.py +213 -0
- pubrules/release-commit +1 -0
- pubrules/releases.py +107 -0
- pubrules/repos.py +67 -0
- pubrules/ruleset.json +43 -0
- pubrules/secrets_config.py +165 -0
- pubrules/security.py +134 -0
- pubrules/service_needs.py +467 -0
- pubrules/standard.json +635 -0
- pubrules/standard.py +266 -0
- pubrules/supply_chain.py +188 -0
- pubrules/tag-ruleset.json +14 -0
- pubrules/templates/common/AGENTS.md +32 -0
- pubrules/templates/common/pubrules +26 -0
- pubrules/templates/common/tests/features/repository.feature +11 -0
- pubrules/templates/common/tests/install-lock +65 -0
- pubrules/templates/common/tests/pytest.ini +4 -0
- pubrules/templates/common/tests/requirements-pubrules.txt +17 -0
- pubrules/templates/common/tests/requirements.txt +3 -0
- pubrules/templates/common/tests/steps/test_repository.py +14 -0
- pubrules/templates/deploy/pubdeploy +28 -0
- pubrules/templates/new-rust/CHANGELOG.md +3 -0
- pubrules/templates/new-rust/Cargo.toml +46 -0
- pubrules/templates/new-rust/LICENSE +202 -0
- pubrules/templates/new-rust/Makefile +18 -0
- pubrules/templates/new-rust/README.md +34 -0
- pubrules/templates/new-rust/SECURITY.md +26 -0
- pubrules/templates/new-rust/corpus/corpus.json +11 -0
- pubrules/templates/new-rust/deny.toml +32 -0
- pubrules/templates/new-rust/fuzz/Cargo.toml +23 -0
- pubrules/templates/new-rust/fuzz/fuzz_targets/greet.rs +8 -0
- pubrules/templates/new-rust/fuzz/gitignore +4 -0
- pubrules/templates/new-rust/fuzz/regressions/README.md +4 -0
- pubrules/templates/new-rust/gitignore +10 -0
- pubrules/templates/new-rust/src/lib.rs +91 -0
- pubrules/templates/new-rust/src/main.rs +19 -0
- pubrules/templates/new-rust/supply-chain/audits.toml +4 -0
- pubrules/templates/new-rust/supply-chain/config.toml +23 -0
- pubrules/templates/new-rust/supply-chain/imports.lock +2 -0
- pubrules/templates/new-rust/tests/conftest.py +9 -0
- pubrules/templates/new-rust/tests/features/cli.feature +14 -0
- pubrules/templates/new-rust/tests/steps/test_cli.py +15 -0
- pubrules/templates/new-rust/tests/vectors.rs +30 -0
- pubrules/templates/new-rust/tools/vectors/generate.py +24 -0
- pubrules/templates/python/Makefile +5 -0
- pubrules/templates/python/pubrules-python.mk +47 -0
- pubrules/templates/rust/Makefile +9 -0
- pubrules/templates/rust/pubrules.mk +138 -0
- pubrules/templates/rust/rust-toolchain.toml +8 -0
- pubrules/templates/service/pubsec +27 -0
- pubrules/templates/service/with-secrets +20 -0
- pubrules/templates/service/with-secrets.json +8 -0
- pubrules/variables.py +45 -0
- pubrules-0.48.0.dist-info/METADATA +1241 -0
- pubrules-0.48.0.dist-info/RECORD +79 -0
- pubrules-0.48.0.dist-info/WHEEL +5 -0
- pubrules-0.48.0.dist-info/entry_points.txt +2 -0
- pubrules-0.48.0.dist-info/licenses/LICENSE +202 -0
- pubrules-0.48.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,1128 @@
|
|
|
1
|
+
"""`pubrules audit prepare`: a release's quality audit, with every rule a
|
|
2
|
+
machine can decide already decided.
|
|
3
|
+
|
|
4
|
+
pubrules audit prepare --package NAME [--version V] [--out FILE] [--quick] [--force]
|
|
5
|
+
|
|
6
|
+
It writes `audit/<package>-<version>.md` in the shape the rust-crate-quality
|
|
7
|
+
agent writes it, for the release `pubrel next --package NAME` gives:
|
|
8
|
+
|
|
9
|
+
- the header `pubrules audit --check` reads, with the commit audited and the
|
|
10
|
+
release it follows;
|
|
11
|
+
- every machine-decidable rule decided, each finding under its severity
|
|
12
|
+
with its file and line: the docs and lint warnings, public functions with
|
|
13
|
+
no example or no `# Errors`, hidden setup lines in examples, the
|
|
14
|
+
"Related crates" versions against `Cargo.lock`, the claims `SECURITY.md`
|
|
15
|
+
makes against what the workflows run, the packaging metadata, and the
|
|
16
|
+
checks the standard's tags name;
|
|
17
|
+
- every rule that needs judgement under "Needs review", marked
|
|
18
|
+
`[needs review]`, with what the machine found for it.
|
|
19
|
+
|
|
20
|
+
`pubrules audit --check` refuses a report while any mark remains, so a release
|
|
21
|
+
needs a person (helped, perhaps, by `pubrules audit draft`) to judge those
|
|
22
|
+
rules. `--quick` skips what takes minutes: the builds as docs.rs and the
|
|
23
|
+
minimum Rust version make them, `cargo publish --dry-run`, and the make
|
|
24
|
+
targets.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
import datetime
|
|
30
|
+
import json
|
|
31
|
+
import os
|
|
32
|
+
import re
|
|
33
|
+
import shutil
|
|
34
|
+
import subprocess
|
|
35
|
+
import sys
|
|
36
|
+
import tarfile
|
|
37
|
+
import tempfile
|
|
38
|
+
import tomllib
|
|
39
|
+
from dataclasses import dataclass, field
|
|
40
|
+
from pathlib import Path
|
|
41
|
+
|
|
42
|
+
from . import __version__, standard
|
|
43
|
+
from .audit import DIR, current
|
|
44
|
+
from .doc_coverage import COVERS, impl_of, strip
|
|
45
|
+
|
|
46
|
+
REVIEW = "**[needs review]**"
|
|
47
|
+
SEVERITIES = (("blocks", "Blocks a release"), ("short", "Falls short of the standard"),
|
|
48
|
+
("consider", "Worth considering"))
|
|
49
|
+
FN = re.compile(r"\s*pub (?:const |async |unsafe )*fn (\w+)")
|
|
50
|
+
TYPE = re.compile(r"\s*pub (struct|enum|trait|type) (\w+)")
|
|
51
|
+
VERSION = re.compile(r"\b(\d+\.\d+(?:\.\d+)?)\b")
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class Finding:
|
|
56
|
+
severity: str # blocks, short or consider
|
|
57
|
+
rule: str # "§2 `# Errors`", "RS-DOC-04"
|
|
58
|
+
where: str # "src/lib.rs:12", or "" when no line is meant
|
|
59
|
+
text: str
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@dataclass
|
|
63
|
+
class Judged:
|
|
64
|
+
"""A judged rule: met, not applicable, or for a person to review."""
|
|
65
|
+
rule: dict
|
|
66
|
+
status: str = "review" # met, n/a or review
|
|
67
|
+
evidence: list[str] = field(default_factory=list)
|
|
68
|
+
note: str = ""
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass
|
|
72
|
+
class Check:
|
|
73
|
+
name: str
|
|
74
|
+
result: str
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class Audit:
|
|
78
|
+
"""What the audit found, as it goes."""
|
|
79
|
+
|
|
80
|
+
def __init__(self):
|
|
81
|
+
self.findings: list[Finding] = []
|
|
82
|
+
self.checks: list[Check] = []
|
|
83
|
+
self.not_run: list[Check] = []
|
|
84
|
+
self.judged: dict[str, Judged] = {}
|
|
85
|
+
self.met: list[str] = []
|
|
86
|
+
|
|
87
|
+
def find(self, severity: str, rule: str, where: str, text: str, judged: str = ""):
|
|
88
|
+
"""Record a finding. `judged` names a judged rule the finding
|
|
89
|
+
settles, such as a section that is not there: nothing is left there
|
|
90
|
+
for a person to judge."""
|
|
91
|
+
self.findings.append(Finding(severity, rule, where, text))
|
|
92
|
+
if judged and judged in self.judged and self.judged[judged].status == "review":
|
|
93
|
+
self.judged[judged].status = "decided"
|
|
94
|
+
|
|
95
|
+
def evidence(self, key: str, line: str):
|
|
96
|
+
if key in self.judged:
|
|
97
|
+
self.judged[key].evidence.append(line)
|
|
98
|
+
|
|
99
|
+
def decide(self, key: str, met_line: str = ""):
|
|
100
|
+
"""A judged rule the machine decides in full: met, unless a finding
|
|
101
|
+
was recorded against it."""
|
|
102
|
+
j = self.judged.get(key)
|
|
103
|
+
if j is None or j.status == "n/a":
|
|
104
|
+
return
|
|
105
|
+
if any(f.rule.startswith(f"§{key} ") for f in self.findings):
|
|
106
|
+
j.status = "decided"
|
|
107
|
+
else:
|
|
108
|
+
j.status = "met"
|
|
109
|
+
if met_line:
|
|
110
|
+
self.met.append(met_line)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
# --- the package ---------------------------------------------------------------
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def run(args: list[str], cwd: Path, env: dict | None = None, timeout: int | None = None):
|
|
117
|
+
return subprocess.run(args, cwd=cwd, capture_output=True, text=True, check=False,
|
|
118
|
+
env={**os.environ, **(env or {})}, timeout=timeout)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class Package:
|
|
122
|
+
"""The package being released, and the repository around it."""
|
|
123
|
+
|
|
124
|
+
def __init__(self, root: Path, name: str, version: str | None):
|
|
125
|
+
self.root = root
|
|
126
|
+
self.name = name
|
|
127
|
+
meta = run(["cargo", "metadata", "--format-version", "1", "--no-deps"], root)
|
|
128
|
+
if meta.returncode:
|
|
129
|
+
sys.exit(f"pubrules: cargo metadata failed: {meta.stderr.strip()}")
|
|
130
|
+
self.meta = json.loads(meta.stdout)
|
|
131
|
+
pkg = next((p for p in self.meta["packages"]
|
|
132
|
+
if p["name"] == name and p["id"] in self.meta["workspace_members"]), None)
|
|
133
|
+
if pkg is None:
|
|
134
|
+
sys.exit(f"pubrules: no package here named {name}")
|
|
135
|
+
self.pkg = pkg
|
|
136
|
+
self.manifest = Path(pkg["manifest_path"])
|
|
137
|
+
self.dir = self.manifest.parent
|
|
138
|
+
self.targets = pkg["targets"]
|
|
139
|
+
self.lib = next((Path(t["src_path"]) for t in self.targets if "lib" in t["kind"]), None)
|
|
140
|
+
self.bins = [t for t in self.targets if "bin" in t["kind"]]
|
|
141
|
+
self.toml = tomllib.loads(self.manifest.read_text(encoding="utf-8"))
|
|
142
|
+
workspace = root / "Cargo.toml"
|
|
143
|
+
self.workspace = tomllib.loads(workspace.read_text(encoding="utf-8")) if workspace.is_file() else {}
|
|
144
|
+
self.release = self._release_entry()
|
|
145
|
+
self.version = version or self._next_version()
|
|
146
|
+
self.tag_prefix = self._tag_prefix()
|
|
147
|
+
self.last_tag = self._last_tag()
|
|
148
|
+
head = run(["git", "rev-parse", "HEAD"], root)
|
|
149
|
+
self.commit = head.stdout.strip() if head.returncode == 0 else ""
|
|
150
|
+
self.dirty = bool(run(["git", "status", "--porcelain"], root).stdout.strip())
|
|
151
|
+
self.config = self._pubrules_config()
|
|
152
|
+
|
|
153
|
+
@property
|
|
154
|
+
def library(self) -> bool:
|
|
155
|
+
return self.lib is not None
|
|
156
|
+
|
|
157
|
+
def rel(self, path: Path) -> str:
|
|
158
|
+
try:
|
|
159
|
+
return str(path.relative_to(self.root))
|
|
160
|
+
except ValueError:
|
|
161
|
+
return str(path)
|
|
162
|
+
|
|
163
|
+
def _release_entry(self) -> dict:
|
|
164
|
+
path = self.root / "release.json"
|
|
165
|
+
if not path.is_file():
|
|
166
|
+
return {}
|
|
167
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
168
|
+
entries = data.get("packages") or [data]
|
|
169
|
+
entry = next((e for e in entries if e.get("name") == self.name), None)
|
|
170
|
+
if entry is None:
|
|
171
|
+
return {}
|
|
172
|
+
return {**{k: v for k, v in data.items() if k != "packages"}, **entry,
|
|
173
|
+
"_listed": "packages" in data}
|
|
174
|
+
|
|
175
|
+
def _next_version(self) -> str:
|
|
176
|
+
pubrel = os.environ.get("PUBREL", "pubrel")
|
|
177
|
+
if shutil.which(pubrel) is None:
|
|
178
|
+
sys.exit("pubrules: audit prepare needs pubrel for the version being released "
|
|
179
|
+
"(`pubrel next --package NAME`); install it, or give --version")
|
|
180
|
+
out = run([pubrel, "next", "--package", self.name], self.root)
|
|
181
|
+
version = out.stdout.strip().split()[-1] if out.stdout.strip() else ""
|
|
182
|
+
if out.returncode or not re.fullmatch(r"\d+\.\d+\.\d+", version):
|
|
183
|
+
sys.exit(f"pubrules: `pubrel next --package {self.name}` gives no version to release: "
|
|
184
|
+
f"{(out.stderr or out.stdout).strip()}")
|
|
185
|
+
return version
|
|
186
|
+
|
|
187
|
+
def _tag_prefix(self) -> str:
|
|
188
|
+
"""The tag prefix pubrel gives this package's releases."""
|
|
189
|
+
if self.release.get("tag-prefix"):
|
|
190
|
+
return self.release["tag-prefix"]
|
|
191
|
+
manifest = Path(self.release.get("manifest", {}).get("path", "Cargo.toml"))
|
|
192
|
+
if self.release.get("_listed") and str(manifest.parent) not in ("", "."):
|
|
193
|
+
return f"{self.name}-v"
|
|
194
|
+
return "v"
|
|
195
|
+
|
|
196
|
+
def _last_tag(self) -> str:
|
|
197
|
+
out = run(["git", "tag", "-l", f"{self.tag_prefix}[0-9]*", "--sort=-v:refname"], self.root)
|
|
198
|
+
tags = [t for t in out.stdout.split() if re.fullmatch(re.escape(self.tag_prefix) + r"\d+\.\d+\.\d+", t)]
|
|
199
|
+
return tags[0] if tags else ""
|
|
200
|
+
|
|
201
|
+
def _pubrules_config(self) -> dict:
|
|
202
|
+
path = self.root / "pubrules.json"
|
|
203
|
+
return json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
|
|
204
|
+
|
|
205
|
+
def field(self, key: str):
|
|
206
|
+
"""A `[package]` field, following `key.workspace = true`."""
|
|
207
|
+
value = self.toml.get("package", {}).get(key)
|
|
208
|
+
if isinstance(value, dict) and value.get("workspace"):
|
|
209
|
+
return self.workspace.get("workspace", {}).get("package", {}).get(key)
|
|
210
|
+
return value
|
|
211
|
+
|
|
212
|
+
def sources(self) -> list[Path]:
|
|
213
|
+
"""The package's Rust sources, not its tests or other members'."""
|
|
214
|
+
src = (self.lib or (Path(self.bins[0]["src_path"]) if self.bins else self.dir / "src")).parent
|
|
215
|
+
others = [Path(p["manifest_path"]).parent for p in self.meta["packages"]
|
|
216
|
+
if p["id"] in self.meta["workspace_members"] and p["name"] != self.name]
|
|
217
|
+
return sorted(p for p in src.rglob("*.rs")
|
|
218
|
+
if not any(o != self.dir and o in p.parents for o in others))
|
|
219
|
+
|
|
220
|
+
def readme(self) -> Path | None:
|
|
221
|
+
named = self.pkg.get("readme")
|
|
222
|
+
for candidate in ([Path(named)] if named else []) + [self.dir / "README.md", self.root / "README.md"]:
|
|
223
|
+
path = candidate if candidate.is_absolute() else self.dir / candidate
|
|
224
|
+
if path.is_file():
|
|
225
|
+
return path
|
|
226
|
+
return None
|
|
227
|
+
|
|
228
|
+
def lock_versions(self) -> dict[str, set[str]]:
|
|
229
|
+
path = self.root / "Cargo.lock"
|
|
230
|
+
if not path.is_file():
|
|
231
|
+
return {}
|
|
232
|
+
out: dict[str, set[str]] = {}
|
|
233
|
+
for p in tomllib.loads(path.read_text(encoding="utf-8")).get("package", []):
|
|
234
|
+
out.setdefault(p["name"], set()).add(p["version"])
|
|
235
|
+
return out
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
# --- reading Rust --------------------------------------------------------------
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
@dataclass
|
|
242
|
+
class Item:
|
|
243
|
+
name: str
|
|
244
|
+
kind: str
|
|
245
|
+
path: Path
|
|
246
|
+
line: int
|
|
247
|
+
docs: list[tuple[int, str]] # (line, text without the `///`)
|
|
248
|
+
attrs: list[str]
|
|
249
|
+
signature: str
|
|
250
|
+
body: str
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def items(paths: list[Path]) -> list[Item]:
|
|
254
|
+
"""Public items with their docs, attributes, signature and body, as
|
|
255
|
+
`pubrules doc-coverage` finds them."""
|
|
256
|
+
out = []
|
|
257
|
+
for path in paths:
|
|
258
|
+
lines = path.read_text(encoding="utf-8").splitlines()
|
|
259
|
+
depth, impls, in_test = 0, [], None
|
|
260
|
+
for i, line in enumerate(lines):
|
|
261
|
+
if in_test is None and re.match(r"\s*#\[cfg\(test\)\]", line):
|
|
262
|
+
in_test = depth
|
|
263
|
+
code = strip(line)
|
|
264
|
+
if in_test is None:
|
|
265
|
+
impl = impl_of(line) if line.strip().startswith("impl") else None
|
|
266
|
+
fn, ty = FN.match(line), TYPE.match(line)
|
|
267
|
+
if fn or ty:
|
|
268
|
+
docs, attrs, j = [], [], i - 1
|
|
269
|
+
while j >= 0 and (lines[j].strip().startswith("///") or lines[j].strip().startswith("#[")):
|
|
270
|
+
text = lines[j].strip()
|
|
271
|
+
if text.startswith("///"):
|
|
272
|
+
docs.append((j + 1, text[3:].removeprefix(" ")))
|
|
273
|
+
else:
|
|
274
|
+
attrs.append(text)
|
|
275
|
+
j -= 1
|
|
276
|
+
docs.reverse()
|
|
277
|
+
sig, k = [], i
|
|
278
|
+
while k < len(lines) and k < i + 20:
|
|
279
|
+
sig.append(lines[k])
|
|
280
|
+
if "{" in strip(lines[k]) or strip(lines[k]).rstrip().endswith(";"):
|
|
281
|
+
break
|
|
282
|
+
k += 1
|
|
283
|
+
body = []
|
|
284
|
+
if fn and "{" in strip(lines[k] if k < len(lines) else ""):
|
|
285
|
+
level = 0
|
|
286
|
+
for m in range(k, min(len(lines), k + 400)):
|
|
287
|
+
body.append(lines[m])
|
|
288
|
+
level += strip(lines[m]).count("{") - strip(lines[m]).count("}")
|
|
289
|
+
if level <= 0 and m > k or (level <= 0 and "}" in strip(lines[m])):
|
|
290
|
+
break
|
|
291
|
+
if fn:
|
|
292
|
+
owner = impls[-1][1] if impls else ""
|
|
293
|
+
name = f"{owner}::{fn.group(1)}" if owner else fn.group(1)
|
|
294
|
+
out.append(Item(name, "fn", path, i + 1, docs, attrs, " ".join(s.strip() for s in sig), "\n".join(body)))
|
|
295
|
+
else:
|
|
296
|
+
out.append(Item(ty.group(2), ty.group(1), path, i + 1, docs, attrs, " ".join(s.strip() for s in sig), ""))
|
|
297
|
+
if impl and "{" in code:
|
|
298
|
+
impls.append((depth, impl))
|
|
299
|
+
depth += code.count("{") - code.count("}")
|
|
300
|
+
while impls and depth <= impls[-1][0]:
|
|
301
|
+
impls.pop()
|
|
302
|
+
if in_test is not None and depth <= in_test and "}" in code:
|
|
303
|
+
in_test = None
|
|
304
|
+
return out
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
NOT_RUST = {"text", "json", "sh", "bash", "console", "toml", "yaml", "plain", "md", "markdown", "cbor"}
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def examples(docs: list[tuple[int, str]]) -> list[list[tuple[int, str]]]:
|
|
311
|
+
"""The Rust examples in an item's docs: each the lines between its fences."""
|
|
312
|
+
out, current, fence = [], None, None
|
|
313
|
+
for line, text in docs:
|
|
314
|
+
stripped = text.strip()
|
|
315
|
+
if current is None and stripped.startswith("```"):
|
|
316
|
+
tags = {t.strip() for t in stripped[3:].split(",") if t.strip()}
|
|
317
|
+
fence = not (tags & NOT_RUST)
|
|
318
|
+
current = []
|
|
319
|
+
elif current is not None and stripped.startswith("```"):
|
|
320
|
+
if fence:
|
|
321
|
+
out.append(current)
|
|
322
|
+
current = None
|
|
323
|
+
elif current is not None:
|
|
324
|
+
current.append((line, text))
|
|
325
|
+
return out
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def hidden(text: str) -> bool:
|
|
329
|
+
return text.strip() == "#" or text.strip().startswith("# ")
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
def plumbing(text: str) -> bool:
|
|
333
|
+
"""A hidden line that only carries the error plumbing or an import."""
|
|
334
|
+
t = text.strip()[1:].strip()
|
|
335
|
+
return (not t or t.startswith(("Ok::<", "Ok(", "fn main", "}", "use ", "#!", "#[", "extern crate"))
|
|
336
|
+
or t in ("{",))
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def headings(doc: list[tuple[int, str]]) -> list[tuple[int, int, str]]:
|
|
340
|
+
"""Markdown headings outside code: (line, level, text)."""
|
|
341
|
+
out, code = [], False
|
|
342
|
+
for line, text in doc:
|
|
343
|
+
if text.strip().startswith("```"):
|
|
344
|
+
code = not code
|
|
345
|
+
continue
|
|
346
|
+
m = re.match(r"(#{1,6})\s+(.+)", text)
|
|
347
|
+
if m and not code:
|
|
348
|
+
out.append((line, len(m.group(1)), m.group(2).strip()))
|
|
349
|
+
return out
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
def crate_root_docs(lib: Path) -> list[tuple[int, str]]:
|
|
353
|
+
"""The crate root's docs: its `//!` lines or its `/*! ... */` block."""
|
|
354
|
+
lines = lib.read_text(encoding="utf-8").splitlines()
|
|
355
|
+
out, block = [], False
|
|
356
|
+
for i, line in enumerate(lines):
|
|
357
|
+
stripped = line.strip()
|
|
358
|
+
if block:
|
|
359
|
+
if "*/" in stripped:
|
|
360
|
+
out.append((i + 1, line.split("*/", 1)[0]))
|
|
361
|
+
block = False
|
|
362
|
+
continue
|
|
363
|
+
out.append((i + 1, line))
|
|
364
|
+
elif stripped.startswith("/*!"):
|
|
365
|
+
rest = stripped[3:]
|
|
366
|
+
if "*/" in rest:
|
|
367
|
+
out.append((i + 1, rest.split("*/", 1)[0]))
|
|
368
|
+
else:
|
|
369
|
+
block = True
|
|
370
|
+
if rest.strip():
|
|
371
|
+
out.append((i + 1, rest))
|
|
372
|
+
elif stripped.startswith("//!"):
|
|
373
|
+
out.append((i + 1, stripped[3:].removeprefix(" ")))
|
|
374
|
+
return out
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
def markdown(path: Path) -> list[tuple[int, str]]:
|
|
378
|
+
return list(enumerate(path.read_text(encoding="utf-8").splitlines(), start=1))
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def section_of(doc: list[tuple[int, str]], title: re.Pattern) -> list[tuple[int, str]]:
|
|
382
|
+
"""The lines under the first heading matching `title`, to the next
|
|
383
|
+
heading of the same level or higher."""
|
|
384
|
+
heads = headings(doc)
|
|
385
|
+
start = next(((line, level) for line, level, text in heads if title.search(text)), None)
|
|
386
|
+
if start is None:
|
|
387
|
+
return []
|
|
388
|
+
end = next((line for line, level, _ in heads if line > start[0] and level <= start[1]), None)
|
|
389
|
+
return [(n, t) for n, t in doc if start[0] < n and (end is None or n < end)]
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
# --- the checks ----------------------------------------------------------------
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def cargo_messages(pkg: Package, args: list[str], env: dict | None = None):
|
|
396
|
+
"""(exit code, this package's warnings and errors as (level, where, text))."""
|
|
397
|
+
proc = run(["cargo", *args, "-p", pkg.name, "--message-format=json"], pkg.root, env=env)
|
|
398
|
+
out = []
|
|
399
|
+
for line in proc.stdout.splitlines():
|
|
400
|
+
try:
|
|
401
|
+
msg = json.loads(line)
|
|
402
|
+
except json.JSONDecodeError:
|
|
403
|
+
continue
|
|
404
|
+
if msg.get("reason") != "compiler-message" or msg.get("package_id") != pkg.pkg["id"]:
|
|
405
|
+
continue
|
|
406
|
+
m = msg["message"]
|
|
407
|
+
if m.get("level") not in ("warning", "error") or not m.get("spans"):
|
|
408
|
+
continue
|
|
409
|
+
span = next((s for s in m["spans"] if s.get("is_primary")), m["spans"][0])
|
|
410
|
+
where = f"{pkg.rel(pkg.root / span['file_name'])}:{span['line_start']}"
|
|
411
|
+
if (where, m["message"]) not in [(w, t) for _, w, t in out]:
|
|
412
|
+
out.append((m["level"], where, m["message"]))
|
|
413
|
+
return proc, out
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def check_builds(pkg: Package, audit: Audit):
|
|
417
|
+
"""cargo doc and clippy for this package, each warning with its place."""
|
|
418
|
+
proc, msgs = cargo_messages(pkg, ["doc", "--no-deps"])
|
|
419
|
+
for level, where, text in msgs:
|
|
420
|
+
audit.find("blocks", "RS-DOC-01, `make doc`", where, f"rustdoc {level}: {text}")
|
|
421
|
+
audit.checks.append(Check(f"`cargo doc -p {pkg.name} --no-deps`",
|
|
422
|
+
"pass" if proc.returncode == 0 and not msgs else
|
|
423
|
+
f"{len(msgs)} warning(s) or error(s)" if msgs else "fails"))
|
|
424
|
+
proc, msgs = cargo_messages(pkg, ["clippy", "--all-targets"])
|
|
425
|
+
for level, where, text in msgs:
|
|
426
|
+
audit.find("blocks", "RS-DOC-03, `make lint`", where, f"clippy {level}: {text}")
|
|
427
|
+
audit.checks.append(Check(f"`cargo clippy -p {pkg.name} --all-targets`",
|
|
428
|
+
"pass" if proc.returncode == 0 and not msgs else
|
|
429
|
+
f"{len(msgs)} warning(s) or error(s)" if msgs else "fails"))
|
|
430
|
+
if pkg.library:
|
|
431
|
+
proc = run(["cargo", "test", "--doc", "-p", pkg.name], pkg.root)
|
|
432
|
+
passed = re.findall(r"test result: ok\. (\d+) passed", proc.stdout)
|
|
433
|
+
if proc.returncode:
|
|
434
|
+
audit.find("blocks", "§2 examples", "", f"`cargo test --doc -p {pkg.name}` fails: "
|
|
435
|
+
f"{tail(proc.stdout + proc.stderr)}")
|
|
436
|
+
audit.checks.append(Check(f"`cargo test --doc -p {pkg.name}`",
|
|
437
|
+
f"pass ({sum(map(int, passed))} doctests)" if proc.returncode == 0 else "fails"))
|
|
438
|
+
else:
|
|
439
|
+
proc, msgs = cargo_messages(pkg, ["clippy", "--", "-W", "clippy::missing_docs_in_private_items"])
|
|
440
|
+
undocumented = [m for m in msgs if "missing documentation" in m[2]]
|
|
441
|
+
for _, where, text in undocumented[:10]:
|
|
442
|
+
audit.evidence("9.2", f"`{where}`: {text}")
|
|
443
|
+
audit.checks.append(Check(f"`cargo clippy -p {pkg.name} -- -W clippy::missing_docs_in_private_items`",
|
|
444
|
+
f"{len(undocumented)} undocumented private item(s)"))
|
|
445
|
+
if undocumented:
|
|
446
|
+
audit.find("consider", "§9.2 module docs", "",
|
|
447
|
+
f"{len(undocumented)} private items have no docs "
|
|
448
|
+
f"(`clippy::missing_docs_in_private_items`); the first are under Needs review")
|
|
449
|
+
check_help(pkg, audit)
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
def check_help(pkg: Package, audit: Audit):
|
|
453
|
+
"""A tool's `--help` exits 0 and prints to stdout (§9)."""
|
|
454
|
+
build = run(["cargo", "build", "-p", pkg.name, "--bins"], pkg.root)
|
|
455
|
+
if build.returncode:
|
|
456
|
+
audit.not_run.append(Check("`--help`", "the binaries do not build"))
|
|
457
|
+
return
|
|
458
|
+
target = Path(pkg.meta["target_directory"])
|
|
459
|
+
for b in pkg.bins:
|
|
460
|
+
exe = target / "debug" / b["name"]
|
|
461
|
+
proc = run([str(exe), "--help"], pkg.root, timeout=60)
|
|
462
|
+
if proc.returncode != 0 or not proc.stdout.strip() or proc.stderr.strip():
|
|
463
|
+
audit.find("short", "§9.5 usage text", "",
|
|
464
|
+
f"`{b['name']} --help` exits {proc.returncode}, with "
|
|
465
|
+
f"{'nothing' if not proc.stdout.strip() else 'its text'} on stdout"
|
|
466
|
+
f"{' and output on stderr' if proc.stderr.strip() else ''}; the standard asks "
|
|
467
|
+
f"that it exit 0 and print to stdout", judged="9.5")
|
|
468
|
+
else:
|
|
469
|
+
audit.evidence("9.5", f"`{b['name']} --help` exits 0 and prints "
|
|
470
|
+
f"{len(proc.stdout.splitlines())} lines to stdout, nothing to stderr")
|
|
471
|
+
audit.checks.append(Check(f"`{b['name']} --help`", f"exit {proc.returncode}"))
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
def tail(text: str, lines: int = 3) -> str:
|
|
475
|
+
kept = [line.strip() for line in text.strip().splitlines() if line.strip()][-lines:]
|
|
476
|
+
return " / ".join(kept)[:400]
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def check_items(pkg: Package, audit: Audit):
|
|
480
|
+
"""§2: examples, `# Errors`, `# Panics`, hidden setup, error types, usize."""
|
|
481
|
+
if not pkg.library:
|
|
482
|
+
return
|
|
483
|
+
found = items(pkg.sources())
|
|
484
|
+
unwrapping, hidden_setup, setups = 0, 0, []
|
|
485
|
+
for it in found:
|
|
486
|
+
where = f"{pkg.rel(it.path)}:{it.line}"
|
|
487
|
+
text = "\n".join(t for _, t in it.docs)
|
|
488
|
+
exs = examples(it.docs)
|
|
489
|
+
if it.kind == "fn" and not exs:
|
|
490
|
+
audit.find("blocks", "RS-DOC-04, §2", where, f"`{it.name}` has no example")
|
|
491
|
+
if it.kind == "fn" and re.search(r"->\s*(?:[\w:]+::)?Result\b", it.signature) and "# Errors" not in text:
|
|
492
|
+
audit.find("short", "§2.3 `# Errors`", where, f"`{it.name}` returns a `Result` and its docs have no `# Errors`")
|
|
493
|
+
if it.kind == "fn" and re.search(r"\bpanic!\(|\.unwrap\(\)|\.expect\(|\bunreachable!\(|\btodo!\(|(?<!debug_)assert(?:_eq|_ne)?!\(", it.body) \
|
|
494
|
+
and "# Panics" not in text:
|
|
495
|
+
audit.evidence("2.4", f"`{where}`: `{it.name}` can panic (its body has a panic, an `unwrap` "
|
|
496
|
+
f"or an assertion) and its docs have no `# Panics`")
|
|
497
|
+
for ex in exs:
|
|
498
|
+
visible = [(n, t) for n, t in ex if not hidden(t)]
|
|
499
|
+
setup = [(n, t) for n, t in ex if hidden(t) and not plumbing(t)]
|
|
500
|
+
uses_q = any("?" in strip(t) for _, t in visible)
|
|
501
|
+
if any(re.search(r"\.unwrap\(\)|\.expect\(", t) for _, t in visible):
|
|
502
|
+
unwrapping += 1
|
|
503
|
+
n = next(n for n, t in visible if re.search(r"\.unwrap\(\)|\.expect\(", t))
|
|
504
|
+
returns_result = re.search(r"->\s*(?:[\w:]+::)?Result\b", it.signature)
|
|
505
|
+
audit.find("short" if returns_result else "consider", "§2.1 examples use `?`",
|
|
506
|
+
f"{pkg.rel(it.path)}:{n}",
|
|
507
|
+
f"`{it.name}`'s example unwraps; the standard asks for `?`, with "
|
|
508
|
+
f"`# Ok::<(), Box<dyn std::error::Error>>(())` hidden"
|
|
509
|
+
+ ("" if returns_result else " (it returns no `Result`: `?` on an "
|
|
510
|
+
"`Option` needs `.ok_or(...)`, so this may be the clearer choice)"))
|
|
511
|
+
if uses_q and not any(re.search(r"Ok::<|fn main\(\)\s*->", t) for _, t in ex):
|
|
512
|
+
audit.find("short", "§2.1 examples use `?`", f"{pkg.rel(it.path)}:{ex[0][0]}",
|
|
513
|
+
f"`{it.name}`'s example uses `?` without the hidden `# Ok::<...>(())` line")
|
|
514
|
+
if setup:
|
|
515
|
+
hidden_setup += len(setup)
|
|
516
|
+
setups.append(f"`{pkg.rel(it.path)}:{setup[0][0]}`: `{it.name}`'s example hides "
|
|
517
|
+
f"{len(setup)} setup line(s), from `{setup[0][1].strip()[:70]}`")
|
|
518
|
+
if it.kind == "enum" and it.name.endswith("Error") and not any("non_exhaustive" in a for a in it.attrs):
|
|
519
|
+
if "exhaustive" in text:
|
|
520
|
+
audit.evidence("2.6", f"`{where}`: `{it.name}` is exhaustive and its docs say why: "
|
|
521
|
+
f"is the reason sound?")
|
|
522
|
+
else:
|
|
523
|
+
audit.find("short", "§2.6 error types", where,
|
|
524
|
+
f"`{it.name}` is a public error enum without `#[non_exhaustive]`, and its "
|
|
525
|
+
f"docs do not say why it is exhaustive (a code change, for a person to decide)",
|
|
526
|
+
judged="2.6")
|
|
527
|
+
if re.search(r"\busize\b", it.signature):
|
|
528
|
+
audit.evidence("2.7", f"`{where}`: `{it.name}` has `usize` in its signature: does the value "
|
|
529
|
+
f"index this machine's memory, or come from someone else?")
|
|
530
|
+
for line in setups[:15]:
|
|
531
|
+
audit.evidence("2.2", line)
|
|
532
|
+
if len(setups) > 15:
|
|
533
|
+
audit.evidence("2.2", f"and {len(setups) - 15} more examples with hidden setup")
|
|
534
|
+
audit.decide("2.1", "**§2, examples:** every example uses `?`, with the error plumbing hidden.")
|
|
535
|
+
audit.decide("2.6", "**§2, error types:** every public error enum is `#[non_exhaustive]` or says why not.")
|
|
536
|
+
if not audit.judged.get("2.2", Judged({})).evidence:
|
|
537
|
+
audit.decide("2.2", "**§2, hidden setup:** no example hides a setup line.")
|
|
538
|
+
fns = [i for i in found if i.kind == "fn"]
|
|
539
|
+
audit.checks.append(Check("public items read (pubrules)", f"{len(found)} items, {len(fns)} functions, "
|
|
540
|
+
f"{hidden_setup} hidden setup line(s)"))
|
|
541
|
+
|
|
542
|
+
|
|
543
|
+
ROOT_SECTIONS = [ # (judged rule, heading pattern, what it is)
|
|
544
|
+
("1.2", re.compile(r"overview", re.I), "Overview"),
|
|
545
|
+
("1.4", re.compile(r"example", re.I), "Examples"),
|
|
546
|
+
("1.5", re.compile(r"\bwhy\b", re.I), "Why this crate?"),
|
|
547
|
+
("1.6", re.compile(r"related", re.I), "Related crates"),
|
|
548
|
+
("1.7", re.compile(r"feature", re.I), "Crate features"),
|
|
549
|
+
("1.8", re.compile(r"minimum (supported )?rust|msrv", re.I), "Minimum Rust version"),
|
|
550
|
+
("1.9", re.compile(r"version", re.I), "Versioning"),
|
|
551
|
+
]
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
def check_crate_root(pkg: Package, audit: Audit):
|
|
555
|
+
"""§1: the crate root's sections, in order; its features, MSRV and
|
|
556
|
+
versioning against Cargo.toml and release.json; its Related crates
|
|
557
|
+
against Cargo.lock."""
|
|
558
|
+
if not pkg.library:
|
|
559
|
+
return
|
|
560
|
+
lib = pkg.rel(pkg.lib)
|
|
561
|
+
source = pkg.lib.read_text(encoding="utf-8")
|
|
562
|
+
if re.search(r"#!\[doc\s*=\s*include_str!\([^)]*README", source):
|
|
563
|
+
audit.find("short", "§1 crate documentation", lib,
|
|
564
|
+
"the crate root includes the README; the standard asks for crate docs written in `lib.rs`")
|
|
565
|
+
doc = crate_root_docs(pkg.lib)
|
|
566
|
+
if not doc:
|
|
567
|
+
audit.find("blocks", "§1 crate documentation", lib, "the crate root has no documentation")
|
|
568
|
+
return
|
|
569
|
+
heads = headings(doc)
|
|
570
|
+
first_head = heads[0][0] if heads else None
|
|
571
|
+
intro = [(n, t) for n, t in doc if first_head is None or n < first_head]
|
|
572
|
+
if not examples(intro):
|
|
573
|
+
audit.find("short", "§1.1 one sentence and an example", lib,
|
|
574
|
+
"the crate docs have no runnable example before their first heading", judged="1.1")
|
|
575
|
+
found = []
|
|
576
|
+
for key, pattern, name in ROOT_SECTIONS:
|
|
577
|
+
if key == "1.9":
|
|
578
|
+
line = next((n for n, _, t in heads if pattern.search(t) and not ROOT_SECTIONS[5][1].search(t)), None)
|
|
579
|
+
else:
|
|
580
|
+
line = next((n for n, _, t in heads if pattern.search(t)), None)
|
|
581
|
+
if line is None:
|
|
582
|
+
audit.find("short", f"§{key} {name}", lib, f"the crate docs have no {name} section", judged=key)
|
|
583
|
+
else:
|
|
584
|
+
found.append((line, key, name))
|
|
585
|
+
audit.evidence(key, f"`{lib}:{line}`: the {name} section")
|
|
586
|
+
order = [key for _, key, _ in sorted(found)]
|
|
587
|
+
if order != sorted(order, key=lambda k: float(k)):
|
|
588
|
+
audit.find("short", "§1 crate documentation", lib,
|
|
589
|
+
f"the sections come in the order {', '.join(n for _, _, n in sorted(found))}; "
|
|
590
|
+
f"the standard's order is Overview, Examples, Why, Related crates, Features, "
|
|
591
|
+
f"Minimum Rust version, Versioning")
|
|
592
|
+
examples_at = next((n for n, key, _ in found if key == "1.4"), None)
|
|
593
|
+
links = [(n, t) for n, t in doc if re.search(r"\]\(#", t) and (examples_at is None or n < examples_at)]
|
|
594
|
+
if links:
|
|
595
|
+
audit.evidence("1.3", f"`{lib}:{links[0][0]}`: {len(links)} line(s) link to sections of the page "
|
|
596
|
+
f"before Examples: does the map cover the page?")
|
|
597
|
+
else:
|
|
598
|
+
audit.find("short", "§1.3 a map of the page", lib,
|
|
599
|
+
"no line before Examples links to the page's sections", judged="1.3")
|
|
600
|
+
check_features(pkg, audit, doc, lib)
|
|
601
|
+
check_msrv(pkg, audit, doc, lib)
|
|
602
|
+
check_versioning(pkg, audit, doc, lib)
|
|
603
|
+
check_related(pkg, audit, section_of(doc, ROOT_SECTIONS[3][1]), lib, "1.6")
|
|
604
|
+
|
|
605
|
+
|
|
606
|
+
def check_features(pkg: Package, audit: Audit, doc, lib: str):
|
|
607
|
+
text = " ".join(t for _, t in section_of(doc, ROOT_SECTIONS[4][1]))
|
|
608
|
+
if not text:
|
|
609
|
+
return
|
|
610
|
+
features = sorted(f for f in pkg.pkg.get("features", {}) if f != "default" or pkg.pkg["features"][f])
|
|
611
|
+
if not features and not re.search(r"\bnone\b|no (cargo )?features", text, re.I):
|
|
612
|
+
audit.find("short", "§1.7 Crate features", lib, "the crate has no features, and its Crate features "
|
|
613
|
+
"section does not say \"None\"", judged="1.7")
|
|
614
|
+
for f in features:
|
|
615
|
+
if not re.search(rf"`{re.escape(f)}`|\b{re.escape(f)}\b", text):
|
|
616
|
+
audit.find("short", "§1.7 Crate features", lib, f"the feature `{f}` is not in the Crate features section")
|
|
617
|
+
audit.decide("1.7", "**§1, features:** the Crate features section names every feature Cargo.toml declares.")
|
|
618
|
+
|
|
619
|
+
|
|
620
|
+
def check_msrv(pkg: Package, audit: Audit, doc, lib: str):
|
|
621
|
+
text = " ".join(t for _, t in section_of(doc, ROOT_SECTIONS[5][1]))
|
|
622
|
+
msrv = pkg.pkg.get("rust_version") or ""
|
|
623
|
+
if not text:
|
|
624
|
+
return
|
|
625
|
+
if msrv and msrv not in text and msrv.rsplit(".0", 1)[0] not in text:
|
|
626
|
+
audit.find("short", "§1.8 Minimum Rust version", lib,
|
|
627
|
+
f"`rust-version` is {msrv}, which the Minimum Rust version section does not state")
|
|
628
|
+
if not re.search(r"minor|second number|\by\b|0\.y", text, re.I):
|
|
629
|
+
audit.find("short", "§1.8 Minimum Rust version", lib,
|
|
630
|
+
"the Minimum Rust version section states no policy for raising it")
|
|
631
|
+
audit.decide("1.8", f"**§1, MSRV:** the section states {msrv or 'the rust-version'} and the policy.")
|
|
632
|
+
|
|
633
|
+
|
|
634
|
+
def check_versioning(pkg: Package, audit: Audit, doc, lib: str):
|
|
635
|
+
lines = section_of(doc, re.compile(r"^versioning", re.I))
|
|
636
|
+
text = " ".join(t for _, t in lines)
|
|
637
|
+
if not text:
|
|
638
|
+
return
|
|
639
|
+
claims_checked = re.search(r"semver-checks|checked against|api is checked", text, re.I)
|
|
640
|
+
if claims_checked and not pkg.release.get("semver-checks"):
|
|
641
|
+
audit.find("blocks", "§1.9 Versioning", f"{lib}:{lines[0][0]}",
|
|
642
|
+
"the docs say the public API is checked against the last release, but release.json "
|
|
643
|
+
"does not set `\"semver-checks\": true` for this package: a false claim")
|
|
644
|
+
elif not claims_checked:
|
|
645
|
+
audit.find("short", "§1.9 Versioning", f"{lib}:{lines[0][0]}",
|
|
646
|
+
"the Versioning section does not say the public API is checked against the last release")
|
|
647
|
+
if not re.search(r"cargo|semver|semantic", text, re.I):
|
|
648
|
+
audit.find("short", "§1.9 Versioning", f"{lib}:{lines[0][0]}", "the Versioning section does not name Cargo's convention")
|
|
649
|
+
audit.decide("1.9", "**§1, versioning:** Cargo's convention, and the API checked by cargo-semver-checks, "
|
|
650
|
+
"as release.json sets.")
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
def check_related(pkg: Package, audit: Audit, lines, where: str, key: str):
|
|
654
|
+
"""Each row of a Related crates (or tools) table: its version, against
|
|
655
|
+
Cargo.lock when the crate is a dependency."""
|
|
656
|
+
lock = pkg.lock_versions()
|
|
657
|
+
table = [(n, t.strip()) for n, t in lines if t.strip().startswith("|")]
|
|
658
|
+
separator = re.compile(r"\|\s*:?-")
|
|
659
|
+
# A row over a |---| line is a header; a section may hold several tables.
|
|
660
|
+
headers = {table[i][0] for i in range(len(table) - 1) if separator.match(table[i + 1][1])}
|
|
661
|
+
rows = [(n, t) for n, t in table if not separator.match(t) and n not in headers]
|
|
662
|
+
for n, t in rows:
|
|
663
|
+
cells = [c.strip() for c in t.strip("|").split("|")]
|
|
664
|
+
name = re.sub(r"[`*\[\]]|\(.*?\)", "", cells[0]).strip().split()[0] if cells and cells[0] else ""
|
|
665
|
+
found = next((m for c in cells[1:] for m in [re.fullmatch(r"v?(\d+(?:\.\d+){0,2})", c)] if m), None) \
|
|
666
|
+
or VERSION.search(" ".join(cells[1:]))
|
|
667
|
+
version = found.group(1) if found else ""
|
|
668
|
+
if not name:
|
|
669
|
+
continue
|
|
670
|
+
locked = lock.get(name) or lock.get(name.replace("-", "_")) or set()
|
|
671
|
+
# A version short of three parts ("1", "0.22") is a requirement: it
|
|
672
|
+
# matches each locked version it covers.
|
|
673
|
+
covered = any(v == version or v.startswith(version + ".") for v in locked)
|
|
674
|
+
if not version:
|
|
675
|
+
audit.find("short", f"§{key} Related crates", f"{where}:{n}",
|
|
676
|
+
f"the row for `{name}` gives no version checked")
|
|
677
|
+
elif locked and not covered:
|
|
678
|
+
audit.find("consider", f"§{key} Related crates", f"{where}:{n}",
|
|
679
|
+
f"the row for `{name}` says {version}; Cargo.lock has "
|
|
680
|
+
f"{', '.join(sorted(locked))}: re-check the claim at that version")
|
|
681
|
+
audit.evidence(key, f"`{where}:{n}`: `{name}` {version or '(no version)'}"
|
|
682
|
+
f"{'; Cargo.lock: ' + ', '.join(sorted(locked)) if locked else '; not a dependency'}"
|
|
683
|
+
f": is the claim checked by a run?")
|
|
684
|
+
|
|
685
|
+
|
|
686
|
+
def check_manifest(pkg: Package, audit: Audit):
|
|
687
|
+
"""§5: Cargo.toml's metadata and `include`, and how publish-check runs."""
|
|
688
|
+
where = pkg.rel(pkg.manifest)
|
|
689
|
+
for key in ("description", "license", "repository", "documentation", "keywords", "categories"):
|
|
690
|
+
value = pkg.pkg.get(key.replace("-", "_"))
|
|
691
|
+
if not value:
|
|
692
|
+
audit.find("short", "§5.1 Cargo.toml", where, f"`{key}` is not set")
|
|
693
|
+
if not pkg.pkg.get("rust_version"):
|
|
694
|
+
audit.find("short", "§5.1 Cargo.toml", where, "`rust-version` is not set")
|
|
695
|
+
include = pkg.field("include")
|
|
696
|
+
if not include:
|
|
697
|
+
audit.find("short", "§5.1 Cargo.toml", where, "there is no explicit `include` list")
|
|
698
|
+
docsrs = pkg.toml.get("package", {}).get("metadata", {}).get("docs", {}).get("rs", {})
|
|
699
|
+
if pkg.library:
|
|
700
|
+
if docsrs.get("all-features") is not True:
|
|
701
|
+
audit.find("short", "§5.1 Cargo.toml", where, "`[package.metadata.docs.rs]` does not set `all-features = true`")
|
|
702
|
+
if "--generate-link-to-definition" not in (docsrs.get("rustdoc-args") or []):
|
|
703
|
+
audit.find("short", "§5.1 Cargo.toml", where,
|
|
704
|
+
"`[package.metadata.docs.rs]` rustdoc-args lack `--generate-link-to-definition`")
|
|
705
|
+
else:
|
|
706
|
+
doc = pkg.pkg.get("documentation") or ""
|
|
707
|
+
if doc and "readme" not in doc.lower() and "docs.rs" in doc:
|
|
708
|
+
audit.find("short", "§9.6 metadata", where, f"`documentation` is {doc}; for a command-line "
|
|
709
|
+
f"tool it points at the README", judged="9.6")
|
|
710
|
+
audit.decide("9.6", "**§9, metadata:** `documentation` points at the README.")
|
|
711
|
+
audit.decide("5.1", "**§5, metadata:** description, licence, repository, documentation, keywords, "
|
|
712
|
+
"categories, `include` and `rust-version` are set"
|
|
713
|
+
+ (", with docs.rs metadata." if pkg.library else "."))
|
|
714
|
+
for pattern in include or []:
|
|
715
|
+
if not pattern.startswith("/"):
|
|
716
|
+
audit.find("short", "§5.2 `include` anchored", where,
|
|
717
|
+
f"the include pattern \"{pattern}\" is not anchored with `/`")
|
|
718
|
+
audit.decide("5.2", "**§5, include:** every pattern is anchored with `/`.")
|
|
719
|
+
mk = pkg.root / "pubrules.mk"
|
|
720
|
+
recipe = mk.read_text(encoding="utf-8").split("\npublish-check:", 1) if mk.is_file() else ["", ""]
|
|
721
|
+
if len(recipe) < 2 or "CARGO_TARGET_DIR=$(CURDIR)/target/publish-check" not in recipe[1].split("\n\n", 1)[0]:
|
|
722
|
+
audit.find("short", "§5.3 publish-check", "pubrules.mk" if mk.is_file() else "",
|
|
723
|
+
"`make publish-check` does not build in a target directory of its own (`pubrules sync` writes it)")
|
|
724
|
+
audit.decide("5.3", "**§5, publish-check:** pubrules.mk's `publish-check` builds in `target/publish-check`.")
|
|
725
|
+
|
|
726
|
+
|
|
727
|
+
README_LIBRARY = [("a Documentation link", re.compile(r"docs\.rs|documentation", re.I)),
|
|
728
|
+
("Usage", re.compile(r"usage|install", re.I)),
|
|
729
|
+
("Minimum Rust version", re.compile(r"minimum (supported )?rust|msrv", re.I)),
|
|
730
|
+
("Security", re.compile(r"security", re.I))]
|
|
731
|
+
README_TOOL = [("an overview of its commands", re.compile(r"command|usage", re.I)),
|
|
732
|
+
("why this tool", re.compile(r"\bwhy\b", re.I)),
|
|
733
|
+
("related tools", re.compile(r"related", re.I)),
|
|
734
|
+
("installation", re.compile(r"install", re.I)),
|
|
735
|
+
("Minimum Rust version", re.compile(r"minimum (supported )?rust|msrv", re.I)),
|
|
736
|
+
("versioning", re.compile(r"version", re.I))]
|
|
737
|
+
|
|
738
|
+
|
|
739
|
+
def check_readme(pkg: Package, audit: Audit):
|
|
740
|
+
path = pkg.readme()
|
|
741
|
+
if path is None:
|
|
742
|
+
audit.find("short", "§5.5 README", "", "the package has no README")
|
|
743
|
+
return
|
|
744
|
+
where = pkg.rel(path)
|
|
745
|
+
doc = markdown(path)
|
|
746
|
+
heads = " | ".join(t for _, _, t in headings(doc))
|
|
747
|
+
text = "\n".join(t for _, t in doc)
|
|
748
|
+
key, wanted = ("5.5", README_LIBRARY) if pkg.library else ("9.1", README_TOOL)
|
|
749
|
+
for name, pattern in wanted:
|
|
750
|
+
if not pattern.search(heads) and not (name == "a Documentation link" and pattern.search(text)):
|
|
751
|
+
audit.find("short", f"§{key} README", where, f"the README has no {name} section")
|
|
752
|
+
if "```" not in text:
|
|
753
|
+
audit.find("short", f"§{key} README", where, "the README has no example")
|
|
754
|
+
audit.evidence(key, f"`{where}`: sections {heads[:300]}")
|
|
755
|
+
if not pkg.library:
|
|
756
|
+
check_related(pkg, audit, section_of(doc, re.compile(r"related", re.I)), where, "9.8")
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
TOOLS = [ # (name, what SECURITY.md says, the pubrules jobs that run it, a command that does)
|
|
760
|
+
("cargo deny", re.compile(r"cargo[ -]deny", re.I), {"job-rust-audit"}, re.compile(r"cargo deny|make deny")),
|
|
761
|
+
("cargo vet", re.compile(r"cargo[ -]vet", re.I), {"job-rust-audit"}, re.compile(r"cargo vet|make vet")),
|
|
762
|
+
("OSV-Scanner", re.compile(r"\bOSV\b|osv-scanner", re.I), {"job-osv"}, re.compile(r"osv-scanner")),
|
|
763
|
+
("fuzzing", re.compile(r"\bfuzz", re.I), {"job-rust-fuzz"}, re.compile(r"cargo fuzz|fuzz-smoke")),
|
|
764
|
+
("the 32-bit and big-endian tests", re.compile(r"\bi686\b|\bs390x\b|big-endian|32-bit", re.I),
|
|
765
|
+
{"job-rust-cross"}, re.compile(r"\bcross\b")),
|
|
766
|
+
("miri", re.compile(r"\bmiri\b", re.I), set(), re.compile(r"\bmiri\b")),
|
|
767
|
+
("dependency review", re.compile(r"dependency review|dependency-review", re.I), {"job-review"},
|
|
768
|
+
re.compile(r"dependency-review-action")),
|
|
769
|
+
]
|
|
770
|
+
RUST_CI = {"job-rust-gates", "job-rust-test", "job-rust-functional", "job-rust-msrv", "job-rust-fuzz",
|
|
771
|
+
"job-rust-cross", "job-rust-audit", "job-osv", "job-review", "job-sonar"}
|
|
772
|
+
|
|
773
|
+
|
|
774
|
+
def workflows(root: Path) -> list[dict]:
|
|
775
|
+
"""Each workflow: its file, its triggers, the pubrules jobs it calls, its text."""
|
|
776
|
+
out = []
|
|
777
|
+
for path in sorted((root / ".github" / "workflows").glob("*.y*ml")):
|
|
778
|
+
text = path.read_text(encoding="utf-8")
|
|
779
|
+
# Under any owner: pubrules', or the one before its transfer.
|
|
780
|
+
jobs = set(re.findall(r"[\w-]+/pubrules/\.github/workflows/(job-[a-z-]+)\.yml@", text))
|
|
781
|
+
if re.search(r"[\w-]+/pubrules/\.github/workflows/rust-ci\.yml@", text):
|
|
782
|
+
jobs |= RUST_CI
|
|
783
|
+
on = text.split("\njobs:", 1)[0]
|
|
784
|
+
triggers = {t for t in ("pull_request", "push", "schedule", "workflow_dispatch") if re.search(rf"\b{t}\b", on)}
|
|
785
|
+
out.append({"file": f".github/workflows/{path.name}", "triggers": triggers, "jobs": jobs, "text": text})
|
|
786
|
+
return out
|
|
787
|
+
|
|
788
|
+
|
|
789
|
+
def runs(flows: list[dict], tool: tuple) -> list[dict]:
|
|
790
|
+
_, _, jobs, command = tool
|
|
791
|
+
return [w for w in flows if w["jobs"] & jobs or command.search(w["text"])]
|
|
792
|
+
|
|
793
|
+
|
|
794
|
+
def check_security(pkg: Package, audit: Audit):
|
|
795
|
+
"""§7: SECURITY.md's claims against the workflows that would make them true."""
|
|
796
|
+
path = next((p for p in (pkg.dir / "SECURITY.md", pkg.root / "SECURITY.md") if p.is_file()), None)
|
|
797
|
+
if path is None:
|
|
798
|
+
audit.find("blocks", "RS-SUP-04", "", "there is no SECURITY.md")
|
|
799
|
+
return
|
|
800
|
+
where = pkg.rel(path)
|
|
801
|
+
lines = markdown(path)
|
|
802
|
+
text = "\n".join(t for _, t in lines)
|
|
803
|
+
flows = workflows(pkg.root)
|
|
804
|
+
if not re.search(r"security/advisories|privately|private (vulnerability )?report", text, re.I):
|
|
805
|
+
audit.find("short", "§7.1 SECURITY.md", where, "it does not say how to report a vulnerability privately")
|
|
806
|
+
mentioned = set()
|
|
807
|
+
for n, line in lines:
|
|
808
|
+
for tool in TOOLS:
|
|
809
|
+
name, says = tool[0], tool[1]
|
|
810
|
+
if not says.search(line):
|
|
811
|
+
continue
|
|
812
|
+
mentioned.add(name)
|
|
813
|
+
running = runs(flows, tool)
|
|
814
|
+
if not running:
|
|
815
|
+
audit.find("short", "§7.1 SECURITY.md", f"{where}:{n}",
|
|
816
|
+
f"it names {name}, which no workflow in .github/workflows runs: if the "
|
|
817
|
+
f"claim is that it runs, it is false, which blocks a release")
|
|
818
|
+
continue
|
|
819
|
+
if re.search(r"pull request", line, re.I) and not any("pull_request" in w["triggers"] for w in running):
|
|
820
|
+
audit.find("short", "§7.1 SECURITY.md", f"{where}:{n}",
|
|
821
|
+
f"it says {name} runs on pull requests; only "
|
|
822
|
+
f"{', '.join(w['file'] for w in running)} run it, none on `pull_request`")
|
|
823
|
+
if re.search(r"nightly|daily|every day|schedule", line, re.I) and not any("schedule" in w["triggers"] for w in running):
|
|
824
|
+
audit.find("short", "§7.1 SECURITY.md", f"{where}:{n}",
|
|
825
|
+
f"it says {name} runs on a schedule; no scheduled workflow runs it")
|
|
826
|
+
audit.evidence("7.1", f"`{where}:{n}`: {name}, run by "
|
|
827
|
+
f"{', '.join(w['file'] + ' (' + ', '.join(sorted(w['triggers'])) + ')' for w in running)}")
|
|
828
|
+
for tool in TOOLS[:4]:
|
|
829
|
+
if tool[0] not in mentioned and runs(flows, tool):
|
|
830
|
+
audit.find("consider", "§7.1 SECURITY.md", where,
|
|
831
|
+
f"{', '.join(w['file'] for w in runs(flows, tool))} run {tool[0]}, which SECURITY.md does not mention")
|
|
832
|
+
config = pkg.root / "supply-chain" / "config.toml"
|
|
833
|
+
if config.is_file():
|
|
834
|
+
imports = sorted(tomllib.loads(config.read_text(encoding="utf-8")).get("imports", {}))
|
|
835
|
+
spelled = lambda i: re.escape(i).replace(r"\-", "[- ]")
|
|
836
|
+
named = [i for i in imports if re.search(rf"\b{spelled(i)}\b", text, re.I)]
|
|
837
|
+
if named and len(named) < len(imports):
|
|
838
|
+
missing = [i for i in imports if i not in named]
|
|
839
|
+
audit.find("short", "§7.1 SECURITY.md", where,
|
|
840
|
+
f"it names the imported audit sets {', '.join(named)} but not "
|
|
841
|
+
f"{', '.join(missing)}, which supply-chain/config.toml imports")
|
|
842
|
+
|
|
843
|
+
|
|
844
|
+
def check_tests(pkg: Package, audit: Audit):
|
|
845
|
+
"""§3, §4 and §9: the evidence a person needs for the judged test rules."""
|
|
846
|
+
testdata = [d for d in (pkg.dir / "testdata", pkg.root / "testdata") if d.is_dir()]
|
|
847
|
+
sources = set()
|
|
848
|
+
for d in testdata:
|
|
849
|
+
for f in sorted(d.rglob("*.json")):
|
|
850
|
+
try:
|
|
851
|
+
data = json.loads(f.read_text(encoding="utf-8"))
|
|
852
|
+
except (json.JSONDecodeError, UnicodeDecodeError):
|
|
853
|
+
continue
|
|
854
|
+
for case in data if isinstance(data, list) else data.get("cases", data.get("vectors", [])) if isinstance(data, dict) else []:
|
|
855
|
+
if isinstance(case, dict) and case.get("source"):
|
|
856
|
+
sources.add(str(case["source"])[:120])
|
|
857
|
+
if isinstance(data, dict) and data.get("source"):
|
|
858
|
+
sources.add(str(data["source"])[:120])
|
|
859
|
+
for s in sorted(sources)[:12]:
|
|
860
|
+
audit.evidence("3.1", f"a source: {s}")
|
|
861
|
+
if testdata and not sources:
|
|
862
|
+
audit.evidence("3.1", "no case in testdata/ names a `source`")
|
|
863
|
+
dev = set(pkg.toml.get("dev-dependencies", {}))
|
|
864
|
+
if "proptest" in dev:
|
|
865
|
+
audit.evidence("3.2", "proptest is a dev-dependency")
|
|
866
|
+
else:
|
|
867
|
+
audit.find("consider", "§3.2 property tests", pkg.rel(pkg.manifest), "proptest is not a dev-dependency")
|
|
868
|
+
if dev:
|
|
869
|
+
audit.evidence("3.3", f"dev-dependencies: {', '.join(sorted(dev))}")
|
|
870
|
+
count = 0
|
|
871
|
+
for f in pkg.sources() + sorted((pkg.dir / "tests").rglob("*.rs")):
|
|
872
|
+
for n, line in enumerate(f.read_text(encoding="utf-8").splitlines(), start=1):
|
|
873
|
+
if COVERS.search(line):
|
|
874
|
+
count += 1
|
|
875
|
+
if count <= 5:
|
|
876
|
+
audit.evidence("3.4", f"`{pkg.rel(f)}:{n}`: {line.strip()}")
|
|
877
|
+
audit.evidence("3.4", f"{count} `// covers:` comments in all; spot-check that each test exercises what it claims")
|
|
878
|
+
targets = sorted(p.stem for p in (pkg.root / "fuzz" / "fuzz_targets").glob("*.rs"))
|
|
879
|
+
audit.evidence("4.1", f"fuzz targets: {', '.join(targets) or 'none'}")
|
|
880
|
+
entry = [i for i in items(pkg.sources()) if i.kind == "fn"
|
|
881
|
+
and re.search(r"(^|::)(parse|from_bytes|from_slice|from_str|decode|verify|read|load|deserialize)\w*$", i.name)]
|
|
882
|
+
for i in entry[:15]:
|
|
883
|
+
audit.evidence("4.1", f"`{pkg.rel(i.path)}:{i.line}`: `{i.name}` reads outside input: has it a target?")
|
|
884
|
+
if not pkg.library:
|
|
885
|
+
features = pkg.root / "tests" / "features"
|
|
886
|
+
if features.is_dir() and any(features.glob("*.feature")):
|
|
887
|
+
audit.evidence("9.4", f"tests/features has {len(list(features.glob('*.feature')))} feature files")
|
|
888
|
+
else:
|
|
889
|
+
audit.find("short", "§9.4 tested end to end", "", "there is no functional suite (tests/features)", judged="9.4")
|
|
890
|
+
|
|
891
|
+
|
|
892
|
+
def check_writing(pkg: Package, audit: Audit):
|
|
893
|
+
"""§10: words the standard rules out, and sentences joined by a semicolon."""
|
|
894
|
+
files = [p for p in [pkg.readme(), pkg.root / "SECURITY.md"] if p and p.is_file()]
|
|
895
|
+
hits = []
|
|
896
|
+
for f in files + pkg.sources():
|
|
897
|
+
code = False
|
|
898
|
+
lines = list(enumerate(f.read_text(encoding="utf-8").splitlines(), start=1))
|
|
899
|
+
if f.suffix == ".rs":
|
|
900
|
+
root = dict(crate_root_docs(f)) if f == pkg.lib else {}
|
|
901
|
+
lines = [(n, root[n]) if n in root else (n, t.strip()[3:]) for n, t in lines
|
|
902
|
+
if n in root or t.strip().startswith(("///", "//!"))]
|
|
903
|
+
for n, line in lines:
|
|
904
|
+
prose = line.strip()
|
|
905
|
+
if prose.startswith("```"):
|
|
906
|
+
code = not code
|
|
907
|
+
continue
|
|
908
|
+
if code or not prose or prose.startswith(("|", "#", "- ")) and "`" in prose[:3]:
|
|
909
|
+
continue
|
|
910
|
+
words = re.findall(r"\b(simply|just|easily|obviously|blazing(?:ly)?)\b", prose, re.I)
|
|
911
|
+
if words:
|
|
912
|
+
hits.append(f"`{pkg.rel(f)}:{n}`: \"{words[0]}\"")
|
|
913
|
+
if re.search(r"[a-z]; [a-z]", re.sub(r"`[^`]*`", "x", prose)):
|
|
914
|
+
hits.append(f"`{pkg.rel(f)}:{n}`: two ideas joined by a semicolon")
|
|
915
|
+
for h in hits[:20]:
|
|
916
|
+
audit.evidence("10.1", h)
|
|
917
|
+
if len(hits) > 20:
|
|
918
|
+
audit.evidence("10.1", f"and {len(hits) - 20} more")
|
|
919
|
+
|
|
920
|
+
|
|
921
|
+
# --- checks that take minutes ------------------------------------------------------
|
|
922
|
+
|
|
923
|
+
|
|
924
|
+
def check_docsrs(pkg: Package, audit: Audit):
|
|
925
|
+
"""§5.4: the docs build from the packaged crate on nightly, as docs.rs builds them."""
|
|
926
|
+
if not pkg.library:
|
|
927
|
+
return
|
|
928
|
+
if run(["cargo", "+nightly", "--version"], pkg.root).returncode:
|
|
929
|
+
audit.not_run.append(Check("docs.rs build", "no nightly toolchain"))
|
|
930
|
+
return
|
|
931
|
+
target = pkg.root / "target" / "audit"
|
|
932
|
+
packaged = run(["cargo", "package", "--no-verify", "--allow-dirty", "-p", pkg.name],
|
|
933
|
+
pkg.root, env={"CARGO_TARGET_DIR": str(target)})
|
|
934
|
+
crate = target / "package" / f"{pkg.name}-{pkg.pkg['version']}.crate"
|
|
935
|
+
if packaged.returncode or not crate.is_file():
|
|
936
|
+
audit.find("blocks", "§5.4 docs.rs build", "", f"`cargo package -p {pkg.name}` fails: {tail(packaged.stderr)}")
|
|
937
|
+
audit.checks.append(Check("docs.rs build", "packaging fails"))
|
|
938
|
+
return
|
|
939
|
+
flags = "--cfg docsrs -Z unstable-options --generate-link-to-definition -D warnings"
|
|
940
|
+
with tempfile.TemporaryDirectory() as tmp:
|
|
941
|
+
with tarfile.open(crate) as tar:
|
|
942
|
+
tar.extractall(tmp, filter="data")
|
|
943
|
+
unpacked = Path(tmp) / f"{pkg.name}-{pkg.pkg['version']}"
|
|
944
|
+
proc = run(["cargo", "+nightly", "doc", "--no-deps", "--all-features"], unpacked,
|
|
945
|
+
env={"RUSTDOCFLAGS": flags, "CARGO_TARGET_DIR": str(target / "docsrs")})
|
|
946
|
+
if proc.returncode:
|
|
947
|
+
audit.find("blocks", "§5.4 docs.rs build", "", f"the docs.rs build fails: {tail(proc.stderr)}",
|
|
948
|
+
judged="5.4")
|
|
949
|
+
audit.checks.append(Check(f"docs.rs build: packaged crate, `cargo +nightly doc --no-deps "
|
|
950
|
+
f"--all-features` with `{flags}`", "fails"))
|
|
951
|
+
else:
|
|
952
|
+
audit.checks.append(Check(f"docs.rs build: packaged crate, `cargo +nightly doc --no-deps "
|
|
953
|
+
f"--all-features` with `{flags}`", "pass, no warnings"))
|
|
954
|
+
audit.decide("5.4", "**§5, docs.rs:** the packaged crate's docs build on nightly with docs.rs's flags, "
|
|
955
|
+
"with no warnings.")
|
|
956
|
+
|
|
957
|
+
|
|
958
|
+
def check_slow(pkg: Package, audit: Audit, waived: set[str]):
|
|
959
|
+
"""publish --dry-run and the MSRV build for this package, and the
|
|
960
|
+
standard's other make targets, which act on the whole repository."""
|
|
961
|
+
env = {"CARGO_TARGET_DIR": str(pkg.root / "target" / "publish-check")}
|
|
962
|
+
args = ["cargo", "publish", "--dry-run", "--locked", "-p", pkg.name] + (["--allow-dirty"] if pkg.dirty else [])
|
|
963
|
+
proc = run(args, pkg.root, env=env)
|
|
964
|
+
note = " (with --allow-dirty: the tree has uncommitted changes)" if pkg.dirty else ""
|
|
965
|
+
if proc.returncode:
|
|
966
|
+
audit.find("blocks", "RS-PKG-01, `make publish-check`", "", f"`cargo publish --dry-run` fails: {tail(proc.stderr)}")
|
|
967
|
+
audit.checks.append(Check(f"`cargo publish --dry-run --locked -p {pkg.name}`{note}",
|
|
968
|
+
"pass" if proc.returncode == 0 else "fails"))
|
|
969
|
+
msrv = pkg.pkg.get("rust_version")
|
|
970
|
+
if "RS-VER-02" not in waived and msrv:
|
|
971
|
+
if run(["cargo", f"+{msrv}", "--version"], pkg.root).returncode:
|
|
972
|
+
audit.not_run.append(Check(f"MSRV build (Rust {msrv})", f"no {msrv} toolchain: rustup toolchain install {msrv}"))
|
|
973
|
+
else:
|
|
974
|
+
proc = run(["cargo", f"+{msrv}", "check", "--locked", "-p", pkg.name], pkg.root)
|
|
975
|
+
if proc.returncode:
|
|
976
|
+
audit.find("blocks", "RS-VER-02, `make msrv`", "", f"the crate does not build on Rust {msrv}: {tail(proc.stderr)}")
|
|
977
|
+
audit.checks.append(Check(f"`cargo +{msrv} check --locked -p {pkg.name}` (MSRV)",
|
|
978
|
+
"pass" if proc.returncode == 0 else "fails"))
|
|
979
|
+
rules = standard.load()
|
|
980
|
+
plan = standard.required(rules, pkg.library, frozenset(waived))
|
|
981
|
+
wanted = [t for t in plan["targets"]["gates"] + plan["targets"]["functional"] + plan["targets"]["audit"]
|
|
982
|
+
if t in ("doc-coverage-check", "supply-chain-check", "vectors-check", "deny", "vet")]
|
|
983
|
+
if not (pkg.root / "Makefile").is_file():
|
|
984
|
+
audit.not_run.append(Check("make targets", "no Makefile"))
|
|
985
|
+
return
|
|
986
|
+
for target in wanted:
|
|
987
|
+
proc = run(["make", "-s", target], pkg.root)
|
|
988
|
+
ids = [r["id"] for r in rules["rules"] if any(c.get("target") == target for c in r["checks"])]
|
|
989
|
+
if proc.returncode:
|
|
990
|
+
audit.find("blocks", f"{', '.join(ids)}, `make {target}`", "", f"`make {target}` fails: {tail(proc.stdout + proc.stderr)}")
|
|
991
|
+
audit.checks.append(Check(f"`make {target}` (whole repository)",
|
|
992
|
+
"pass" if proc.returncode == 0 else "fails"))
|
|
993
|
+
|
|
994
|
+
|
|
995
|
+
# --- the report ------------------------------------------------------------------
|
|
996
|
+
|
|
997
|
+
|
|
998
|
+
def rule_text(rule: dict) -> str:
|
|
999
|
+
"""A judged rule's words, without its list marker or its tags."""
|
|
1000
|
+
text = " ".join(re.sub(r"\[(?:judged|checked)[^\]]*\]", "", rule["text"]).split())
|
|
1001
|
+
return re.sub(r"^(?:- |\d+\. )", "", text).strip()
|
|
1002
|
+
|
|
1003
|
+
|
|
1004
|
+
def rule_label(j: Judged) -> str:
|
|
1005
|
+
return f"§{j.rule['id']} {j.rule['title']}"
|
|
1006
|
+
|
|
1007
|
+
|
|
1008
|
+
def render(pkg: Package, audit: Audit, today: str, quick: bool, waived: dict[str, str]) -> str:
|
|
1009
|
+
blocking = sum(1 for f in audit.findings if f.severity == "blocks")
|
|
1010
|
+
review = [j for j in audit.judged.values() if j.status == "review"]
|
|
1011
|
+
kind = "a library" if pkg.library else "a command-line tool (binary only): section 9 applies"
|
|
1012
|
+
out = [
|
|
1013
|
+
"---",
|
|
1014
|
+
f"package: {pkg.name}",
|
|
1015
|
+
f"version: {pkg.version}",
|
|
1016
|
+
f"standard: {current()}",
|
|
1017
|
+
f"blocking: {blocking}",
|
|
1018
|
+
f"date: {today}",
|
|
1019
|
+
f"auditor: pubrules audit prepare (pubrules {__version__})",
|
|
1020
|
+
f"commit: {pkg.commit}",
|
|
1021
|
+
f"last-release: {pkg.last_tag or 'none'}",
|
|
1022
|
+
"---",
|
|
1023
|
+
"",
|
|
1024
|
+
f"# Quality audit: {pkg.name} {pkg.version}",
|
|
1025
|
+
"",
|
|
1026
|
+
f"Prepared by `pubrules audit prepare` at `{pkg.commit[:7] or 'no commit'}`"
|
|
1027
|
+
f"{' plus uncommitted changes' if pkg.dirty else ''}, against the Rust crate standard named "
|
|
1028
|
+
f"above. {pkg.name} is {kind}. {pkg.version} is the version to release"
|
|
1029
|
+
f" (`pubrel next --package {pkg.name}`), after "
|
|
1030
|
+
f"{('`' + pkg.last_tag + '`') if pkg.last_tag else 'no earlier release'}.",
|
|
1031
|
+
"",
|
|
1032
|
+
f"Every rule a machine can decide is decided below, each finding with its file and line. "
|
|
1033
|
+
f"{len(review)} rule(s) that need judgement are under \"Needs review\", each with its "
|
|
1034
|
+
f"mark and what the machine found for it. `pubrules audit --check` refuses this report "
|
|
1035
|
+
f"while any mark remains: a person judges each rule, moves what they find into the "
|
|
1036
|
+
f"sections above it with `blocking` counted again, and removes the mark. "
|
|
1037
|
+
f"`pubrules audit draft --package {pkg.name}` drafts those verdicts for that review. "
|
|
1038
|
+
f"This file should be committed with the release's changes.",
|
|
1039
|
+
]
|
|
1040
|
+
n = 0
|
|
1041
|
+
for severity, title in SEVERITIES:
|
|
1042
|
+
out += ["", f"## {title}", ""]
|
|
1043
|
+
found = [f for f in audit.findings if f.severity == severity]
|
|
1044
|
+
if not found:
|
|
1045
|
+
out.append("None.")
|
|
1046
|
+
for f in found:
|
|
1047
|
+
n += 1
|
|
1048
|
+
where = f" (`{f.where}`)" if f.where else ""
|
|
1049
|
+
out.append(f"{n}. **{f.rule}**{where}. {f.text}.")
|
|
1050
|
+
out += ["", "## Needs review", ""]
|
|
1051
|
+
if not review:
|
|
1052
|
+
out.append("None.")
|
|
1053
|
+
for j in review:
|
|
1054
|
+
r = j.rule
|
|
1055
|
+
out += [f"<!-- rule {r['id']} review -->", f"### {rule_label(j)} {REVIEW}", ""]
|
|
1056
|
+
words = rule_text(r)
|
|
1057
|
+
out.append(f"The standard, section {r['section']}: {words[:700]}{'...' if len(words) > 700 else ''}")
|
|
1058
|
+
if r.get("question"):
|
|
1059
|
+
out += ["", f"To judge: {r['question']}"]
|
|
1060
|
+
out += [""]
|
|
1061
|
+
if j.evidence:
|
|
1062
|
+
out.append("What the machine found:")
|
|
1063
|
+
out += [f"- {e}" for e in j.evidence]
|
|
1064
|
+
else:
|
|
1065
|
+
out.append("The machine found nothing to check here: read the code and docs.")
|
|
1066
|
+
out += ["<!-- /rule -->", ""]
|
|
1067
|
+
if out[-1] == "":
|
|
1068
|
+
out.pop()
|
|
1069
|
+
out += ["", "## Sections met", ""]
|
|
1070
|
+
out += [f"- {m}" for m in audit.met] or ["None decided by machine alone."]
|
|
1071
|
+
applies_not = [j for j in audit.judged.values() if j.status == "n/a"]
|
|
1072
|
+
if applies_not:
|
|
1073
|
+
out.append(f"- **Not applicable to {kind.split(':')[0]}:** "
|
|
1074
|
+
+ ", ".join(f"§{j.rule['id']}" for j in applies_not) + ".")
|
|
1075
|
+
for rule, reason in sorted(waived.items()):
|
|
1076
|
+
out.append(f"- **{rule}:** under a declared exception ({reason}), so not reported as a gap.")
|
|
1077
|
+
out += ["", "## Checks run", "", "| Check | Result |", "|---|---|"]
|
|
1078
|
+
out += [f"| {c.name} | {c.result} |" for c in audit.checks]
|
|
1079
|
+
out += ["", "## Checks not run", ""]
|
|
1080
|
+
not_run = list(audit.not_run)
|
|
1081
|
+
if quick:
|
|
1082
|
+
not_run.append(Check("docs.rs build, `cargo publish --dry-run`, the MSRV build and the make targets",
|
|
1083
|
+
"`--quick` skips them; run `pubrules audit prepare` without it before the release"))
|
|
1084
|
+
not_run.append(Check("`make fuzz-smoke` and `make functional`", "CI runs them on the release pull request"))
|
|
1085
|
+
out += [f"- **{c.name}:** {c.result}." for c in not_run]
|
|
1086
|
+
return "\n".join(out) + "\n"
|
|
1087
|
+
|
|
1088
|
+
|
|
1089
|
+
def prepare(root: Path, name: str, version: str | None, out: str | None,
|
|
1090
|
+
quick: bool, force: bool) -> int:
|
|
1091
|
+
pkg = Package(root, name, version)
|
|
1092
|
+
rules = standard.load()
|
|
1093
|
+
from .conform import exceptions
|
|
1094
|
+
waived_ids, open_, _ = exceptions(pkg.config, {r["id"] for r in rules["rules"]})
|
|
1095
|
+
waived = {e.split(" until ")[0]: e.split(": ", 1)[-1] for e in open_}
|
|
1096
|
+
audit = Audit()
|
|
1097
|
+
for r in rules["judged"]:
|
|
1098
|
+
applies = (r["applies"] == "every crate" or (r["applies"] == "library") == pkg.library)
|
|
1099
|
+
audit.judged[r["id"]] = Judged(r, "review" if applies else "n/a")
|
|
1100
|
+
if "RS-TEST-01" in waived_ids:
|
|
1101
|
+
audit.judged["3.1"].status = "n/a"
|
|
1102
|
+
from .paths import confined
|
|
1103
|
+
target = confined(out, "the --out file") if out else root / DIR / f"{pkg.name}-{pkg.version}.md"
|
|
1104
|
+
if target.exists() and not force:
|
|
1105
|
+
sys.exit(f"pubrules: {pkg.rel(target)} exists, and may hold a person's review: give --force "
|
|
1106
|
+
f"to write over it, or --out for another file")
|
|
1107
|
+
print(f"auditing {pkg.name} {pkg.version} at {pkg.commit[:12]}"
|
|
1108
|
+
f" (last release {pkg.last_tag or 'none'})", file=sys.stderr)
|
|
1109
|
+
check_crate_root(pkg, audit)
|
|
1110
|
+
check_items(pkg, audit)
|
|
1111
|
+
check_manifest(pkg, audit)
|
|
1112
|
+
check_readme(pkg, audit)
|
|
1113
|
+
check_security(pkg, audit)
|
|
1114
|
+
check_tests(pkg, audit)
|
|
1115
|
+
check_writing(pkg, audit)
|
|
1116
|
+
check_builds(pkg, audit)
|
|
1117
|
+
if not quick:
|
|
1118
|
+
check_docsrs(pkg, audit)
|
|
1119
|
+
check_slow(pkg, audit, waived_ids)
|
|
1120
|
+
today = os.environ.get("PUBRULES_TODAY") or datetime.date.today().isoformat()
|
|
1121
|
+
text = render(pkg, audit, today, quick, waived)
|
|
1122
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
1123
|
+
target.write_text(text, encoding="utf-8")
|
|
1124
|
+
review = sum(1 for j in audit.judged.values() if j.status == "review")
|
|
1125
|
+
blocking = sum(1 for f in audit.findings if f.severity == "blocks")
|
|
1126
|
+
print(f"wrote {pkg.rel(target)}: {len(audit.findings)} finding(s), {blocking} blocking; "
|
|
1127
|
+
f"{review} rule(s) need review")
|
|
1128
|
+
return 0
|