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.
Files changed (79) hide show
  1. pubrules/__init__.py +14 -0
  2. pubrules/audit.py +116 -0
  3. pubrules/audit_draft.py +295 -0
  4. pubrules/audit_prepare.py +1128 -0
  5. pubrules/cache.py +319 -0
  6. pubrules/cbor.py +45 -0
  7. pubrules/ci.py +910 -0
  8. pubrules/cli.py +1069 -0
  9. pubrules/conform.py +295 -0
  10. pubrules/doc_coverage.py +235 -0
  11. pubrules/freshness.py +75 -0
  12. pubrules/gherkin.py +348 -0
  13. pubrules/hooks.py +59 -0
  14. pubrules/hosting.py +372 -0
  15. pubrules/ignores.py +86 -0
  16. pubrules/new.py +242 -0
  17. pubrules/nightly.py +1002 -0
  18. pubrules/paths.py +32 -0
  19. pubrules/protect.py +596 -0
  20. pubrules/providers.py +129 -0
  21. pubrules/refs.py +213 -0
  22. pubrules/release-commit +1 -0
  23. pubrules/releases.py +107 -0
  24. pubrules/repos.py +67 -0
  25. pubrules/ruleset.json +43 -0
  26. pubrules/secrets_config.py +165 -0
  27. pubrules/security.py +134 -0
  28. pubrules/service_needs.py +467 -0
  29. pubrules/standard.json +635 -0
  30. pubrules/standard.py +266 -0
  31. pubrules/supply_chain.py +188 -0
  32. pubrules/tag-ruleset.json +14 -0
  33. pubrules/templates/common/AGENTS.md +32 -0
  34. pubrules/templates/common/pubrules +26 -0
  35. pubrules/templates/common/tests/features/repository.feature +11 -0
  36. pubrules/templates/common/tests/install-lock +65 -0
  37. pubrules/templates/common/tests/pytest.ini +4 -0
  38. pubrules/templates/common/tests/requirements-pubrules.txt +17 -0
  39. pubrules/templates/common/tests/requirements.txt +3 -0
  40. pubrules/templates/common/tests/steps/test_repository.py +14 -0
  41. pubrules/templates/deploy/pubdeploy +28 -0
  42. pubrules/templates/new-rust/CHANGELOG.md +3 -0
  43. pubrules/templates/new-rust/Cargo.toml +46 -0
  44. pubrules/templates/new-rust/LICENSE +202 -0
  45. pubrules/templates/new-rust/Makefile +18 -0
  46. pubrules/templates/new-rust/README.md +34 -0
  47. pubrules/templates/new-rust/SECURITY.md +26 -0
  48. pubrules/templates/new-rust/corpus/corpus.json +11 -0
  49. pubrules/templates/new-rust/deny.toml +32 -0
  50. pubrules/templates/new-rust/fuzz/Cargo.toml +23 -0
  51. pubrules/templates/new-rust/fuzz/fuzz_targets/greet.rs +8 -0
  52. pubrules/templates/new-rust/fuzz/gitignore +4 -0
  53. pubrules/templates/new-rust/fuzz/regressions/README.md +4 -0
  54. pubrules/templates/new-rust/gitignore +10 -0
  55. pubrules/templates/new-rust/src/lib.rs +91 -0
  56. pubrules/templates/new-rust/src/main.rs +19 -0
  57. pubrules/templates/new-rust/supply-chain/audits.toml +4 -0
  58. pubrules/templates/new-rust/supply-chain/config.toml +23 -0
  59. pubrules/templates/new-rust/supply-chain/imports.lock +2 -0
  60. pubrules/templates/new-rust/tests/conftest.py +9 -0
  61. pubrules/templates/new-rust/tests/features/cli.feature +14 -0
  62. pubrules/templates/new-rust/tests/steps/test_cli.py +15 -0
  63. pubrules/templates/new-rust/tests/vectors.rs +30 -0
  64. pubrules/templates/new-rust/tools/vectors/generate.py +24 -0
  65. pubrules/templates/python/Makefile +5 -0
  66. pubrules/templates/python/pubrules-python.mk +47 -0
  67. pubrules/templates/rust/Makefile +9 -0
  68. pubrules/templates/rust/pubrules.mk +138 -0
  69. pubrules/templates/rust/rust-toolchain.toml +8 -0
  70. pubrules/templates/service/pubsec +27 -0
  71. pubrules/templates/service/with-secrets +20 -0
  72. pubrules/templates/service/with-secrets.json +8 -0
  73. pubrules/variables.py +45 -0
  74. pubrules-0.48.0.dist-info/METADATA +1241 -0
  75. pubrules-0.48.0.dist-info/RECORD +79 -0
  76. pubrules-0.48.0.dist-info/WHEEL +5 -0
  77. pubrules-0.48.0.dist-info/entry_points.txt +2 -0
  78. pubrules-0.48.0.dist-info/licenses/LICENSE +202 -0
  79. 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