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
pubrules/conform.py
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
"""`pubrules conform`: the checks of the Rust crate standard that no make
|
|
2
|
+
target runs, and the repository's declared exceptions.
|
|
3
|
+
|
|
4
|
+
Each check belongs to a rule the standard tags `pubrules conform`:
|
|
5
|
+
|
|
6
|
+
- RS-DOC-01: each published library declares a `_documentation` module;
|
|
7
|
+
- RS-DOC-03: each published library sets `missing_docs` in its lints;
|
|
8
|
+
- RS-SAFE-01: each published crate forbids `unsafe_code`;
|
|
9
|
+
- RS-TEST-01: test vectors exist (`testdata/`, or `crates/*/testdata/`);
|
|
10
|
+
- RS-FUZZ-01: fuzz targets exist (`fuzz/fuzz_targets/*.rs`);
|
|
11
|
+
- RS-SUP-01: `deny.toml` keeps the shared baseline, and
|
|
12
|
+
`supply-chain/config.toml` imports the shared audit sets;
|
|
13
|
+
- RS-SUP-04: `SECURITY.md` exists;
|
|
14
|
+
- RS-REL-01: `release.json` declares `pubrules audit --check` as a security
|
|
15
|
+
check, so no release is cut without a current quality audit;
|
|
16
|
+
- RS-SUP-05: the release key `release.json` names is labelled for what it
|
|
17
|
+
releases (the package's name and "release key"), not with a person's
|
|
18
|
+
name: its label is public in every release it signs.
|
|
19
|
+
|
|
20
|
+
It also checks, without an exception possible, that every workflow calling
|
|
21
|
+
pubrules' `rust-ci.yml`, or the `job-rust-*.yml` jobs a ci block's
|
|
22
|
+
generated workflows call, pins the pubrules this repository's lock pins, so the
|
|
23
|
+
workflow and the standard it enforces never drift apart.
|
|
24
|
+
|
|
25
|
+
Exceptions are declared in `pubrules.json`, each with a rule ID, a reason, and
|
|
26
|
+
the date by which it will be met or reviewed. An expired exception, or one
|
|
27
|
+
naming no rule, fails. `pubrules sync --check` runs all of this for a Rust
|
|
28
|
+
repository, so CI runs it on every change.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import datetime
|
|
34
|
+
import json
|
|
35
|
+
import os
|
|
36
|
+
import re
|
|
37
|
+
import subprocess
|
|
38
|
+
import tomllib
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
|
|
41
|
+
from . import __version__, standard
|
|
42
|
+
from .refs import ANY_OWNER, AT, VERSION, owner, release_commit, stale_pins
|
|
43
|
+
|
|
44
|
+
# The audit sets every repository imports (cargo vet).
|
|
45
|
+
SHARED_IMPORTS = {
|
|
46
|
+
"bytecode-alliance": "https://raw.githubusercontent.com/bytecodealliance/wasmtime/main/supply-chain/audits.toml",
|
|
47
|
+
"embark-studios": "https://raw.githubusercontent.com/EmbarkStudios/rust-ecosystem/main/audits.toml",
|
|
48
|
+
"google": "https://raw.githubusercontent.com/google/supply-chain/main/audits.toml",
|
|
49
|
+
"isrg": "https://raw.githubusercontent.com/divviup/libprio-rs/main/supply-chain/audits.toml",
|
|
50
|
+
"mozilla": "https://raw.githubusercontent.com/mozilla/supply-chain/main/audits.toml",
|
|
51
|
+
"zcash": "https://raw.githubusercontent.com/zcash/rust-ecosystem/main/supply-chain/audits.toml",
|
|
52
|
+
}
|
|
53
|
+
# deny.toml settings the baseline fixes: (table, key) -> value.
|
|
54
|
+
DENY_BASELINE = {
|
|
55
|
+
("advisories", "unmaintained"): "all",
|
|
56
|
+
("advisories", "unsound"): "all",
|
|
57
|
+
("advisories", "yanked"): "deny",
|
|
58
|
+
("bans", "wildcards"): "deny",
|
|
59
|
+
("sources", "unknown-registry"): "deny",
|
|
60
|
+
("sources", "unknown-git"): "deny",
|
|
61
|
+
}
|
|
62
|
+
# By commit, with the version in a comment, or by tag (refs.py).
|
|
63
|
+
WORKFLOW_PIN = re.compile(
|
|
64
|
+
ANY_OWNER + r"pubrules/\.github/workflows/(?P<name>rust-ci|job-rust-[a-z]+)\.yml@" + AT + VERSION)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def today() -> datetime.date:
|
|
68
|
+
"""Today, or PUBRULES_TODAY (YYYY-MM-DD), which tests set."""
|
|
69
|
+
fixed = os.environ.get("PUBRULES_TODAY")
|
|
70
|
+
return datetime.date.fromisoformat(fixed) if fixed else datetime.date.today()
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def exceptions(config: dict, known: set[str],
|
|
74
|
+
family=lambda rule: not str(rule).startswith(("WEB-", "TEST-"))) -> tuple[set[str], list[str], list[str]]:
|
|
75
|
+
"""The rule IDs waived, a description of each open exception, and the
|
|
76
|
+
problems with the declarations. Only the exceptions whose rule is in
|
|
77
|
+
`family` are read: the Rust crate standard's by default. The site rules
|
|
78
|
+
(WEB-) are another package's, which reads them with its own copy."""
|
|
79
|
+
waived, open_, problems = set(), [], []
|
|
80
|
+
for i, e in enumerate(config.get("exceptions", [])):
|
|
81
|
+
where = f"pubrules.json exceptions[{i}]"
|
|
82
|
+
if isinstance(e, dict) and "rule" in e and not family(e["rule"]):
|
|
83
|
+
continue
|
|
84
|
+
if not isinstance(e, dict) or set(e) != {"rule", "reason", "until"}:
|
|
85
|
+
problems.append(f"{where}: give exactly a rule, a reason and an until date")
|
|
86
|
+
continue
|
|
87
|
+
rule, reason, until = e["rule"], str(e["reason"]).strip(), e["until"]
|
|
88
|
+
if rule not in known:
|
|
89
|
+
problems.append(f"{where}: {rule} is not a rule of the standard")
|
|
90
|
+
continue
|
|
91
|
+
if not reason:
|
|
92
|
+
problems.append(f"{where}: {rule} needs a reason")
|
|
93
|
+
continue
|
|
94
|
+
try:
|
|
95
|
+
date = datetime.date.fromisoformat(str(until))
|
|
96
|
+
except ValueError:
|
|
97
|
+
problems.append(f"{where}: {rule}'s until must be a date, YYYY-MM-DD")
|
|
98
|
+
continue
|
|
99
|
+
if date < today():
|
|
100
|
+
problems.append(f"{rule}: the exception expired on {date}; meet the rule, or "
|
|
101
|
+
f"review the exception and set a new date ({reason})")
|
|
102
|
+
continue
|
|
103
|
+
waived.add(rule)
|
|
104
|
+
open_.append(f"{rule} until {date}: {reason}")
|
|
105
|
+
return waived, open_, problems
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def packages(root: Path, config: dict) -> list[dict]:
|
|
109
|
+
"""The published packages: pubrules.json's `published`, or else every
|
|
110
|
+
package that does not set `publish = false`."""
|
|
111
|
+
meta = json.loads(subprocess.run(
|
|
112
|
+
["cargo", "metadata", "--no-deps", "--format-version", "1"],
|
|
113
|
+
cwd=root, check=True, capture_output=True, text=True,
|
|
114
|
+
).stdout)
|
|
115
|
+
names = config.get("published")
|
|
116
|
+
if names is not None:
|
|
117
|
+
return [p for p in meta["packages"] if p["name"] in names]
|
|
118
|
+
return [p for p in meta["packages"] if p.get("publish") != []]
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def lints(root: Path, manifest: Path) -> dict:
|
|
122
|
+
"""A package's lints, following `[lints] workspace = true`."""
|
|
123
|
+
data = tomllib.loads(manifest.read_text(encoding="utf-8"))
|
|
124
|
+
table = data.get("lints", {})
|
|
125
|
+
if table.get("workspace") is True:
|
|
126
|
+
workspace = tomllib.loads((root / "Cargo.toml").read_text(encoding="utf-8"))
|
|
127
|
+
return workspace.get("workspace", {}).get("lints", {})
|
|
128
|
+
return table
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def level(table: dict, group: str, name: str) -> str | None:
|
|
132
|
+
value = table.get(group, {}).get(name)
|
|
133
|
+
return value.get("level") if isinstance(value, dict) else value
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def checks(root: Path, config: dict) -> dict[str, list[str]]:
|
|
137
|
+
"""The problems found, by rule ID."""
|
|
138
|
+
found: dict[str, list[str]] = {}
|
|
139
|
+
|
|
140
|
+
def problem(rule: str, text: str) -> None:
|
|
141
|
+
found.setdefault(rule, []).append(text)
|
|
142
|
+
|
|
143
|
+
for pkg in packages(root, config):
|
|
144
|
+
manifest = Path(pkg["manifest_path"])
|
|
145
|
+
rel = manifest.relative_to(root)
|
|
146
|
+
table = lints(root, manifest)
|
|
147
|
+
if level(table, "rust", "unsafe_code") != "forbid":
|
|
148
|
+
problem("RS-SAFE-01", f"{rel}: set unsafe_code = \"forbid\" in [lints.rust]")
|
|
149
|
+
lib = next((t for t in pkg["targets"] if "lib" in t["kind"]), None)
|
|
150
|
+
if lib is None:
|
|
151
|
+
continue
|
|
152
|
+
if level(table, "rust", "missing_docs") not in ("warn", "deny", "forbid"):
|
|
153
|
+
problem("RS-DOC-03", f"{rel}: set missing_docs in [lints.rust]")
|
|
154
|
+
source = Path(lib["src_path"]).read_text(encoding="utf-8")
|
|
155
|
+
if not re.search(r"^\s*pub mod _documentation\b", source, re.M):
|
|
156
|
+
problem("RS-DOC-01", f"{Path(lib['src_path']).relative_to(root)}: "
|
|
157
|
+
f"declare `pub mod _documentation`")
|
|
158
|
+
if not (root / "testdata").is_dir() and not list(root.glob("crates/*/testdata")):
|
|
159
|
+
problem("RS-TEST-01", "no testdata/: the standard asks for test vectors")
|
|
160
|
+
if not list(root.glob("fuzz/fuzz_targets/*.rs")):
|
|
161
|
+
problem("RS-FUZZ-01", "no fuzz/fuzz_targets/*.rs: the standard asks for fuzzing")
|
|
162
|
+
if not (root / "SECURITY.md").is_file():
|
|
163
|
+
problem("RS-SUP-04", "no SECURITY.md")
|
|
164
|
+
for text in release_key_label(root):
|
|
165
|
+
problem("RS-SUP-05", text)
|
|
166
|
+
for text in audit_declared(root):
|
|
167
|
+
problem("RS-REL-01", text)
|
|
168
|
+
deny = root / "deny.toml"
|
|
169
|
+
if not deny.is_file():
|
|
170
|
+
problem("RS-SUP-01", "no deny.toml")
|
|
171
|
+
else:
|
|
172
|
+
data = tomllib.loads(deny.read_text(encoding="utf-8"))
|
|
173
|
+
for (table, key), want in DENY_BASELINE.items():
|
|
174
|
+
if data.get(table, {}).get(key) != want:
|
|
175
|
+
problem("RS-SUP-01", f"deny.toml: set {key} = \"{want}\" in [{table}]")
|
|
176
|
+
vet = root / "supply-chain" / "config.toml"
|
|
177
|
+
if not vet.is_file():
|
|
178
|
+
problem("RS-SUP-01", "no supply-chain/config.toml; run `cargo vet init`")
|
|
179
|
+
else:
|
|
180
|
+
imports = tomllib.loads(vet.read_text(encoding="utf-8")).get("imports", {})
|
|
181
|
+
for name, url in SHARED_IMPORTS.items():
|
|
182
|
+
if imports.get(name, {}).get("url") != url:
|
|
183
|
+
problem("RS-SUP-01", f"supply-chain/config.toml: import {name} from {url}")
|
|
184
|
+
return found
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def cbor(data: bytes, i: int = 0):
|
|
188
|
+
"""Decode one CBOR item at `i`: (value, next index). Only what key
|
|
189
|
+
objects hold: integers, byte and text strings, arrays and maps."""
|
|
190
|
+
first = data[i]
|
|
191
|
+
major, info = first >> 5, first & 31
|
|
192
|
+
i += 1
|
|
193
|
+
if info < 24:
|
|
194
|
+
n = info
|
|
195
|
+
elif info in (24, 25, 26, 27):
|
|
196
|
+
size = 1 << (info - 24)
|
|
197
|
+
n = int.from_bytes(data[i:i + size], "big")
|
|
198
|
+
i += size
|
|
199
|
+
else:
|
|
200
|
+
raise ValueError("indefinite or reserved length")
|
|
201
|
+
if major == 0:
|
|
202
|
+
return n, i
|
|
203
|
+
if major == 1:
|
|
204
|
+
return -1 - n, i
|
|
205
|
+
if major in (2, 3):
|
|
206
|
+
raw = data[i:i + n]
|
|
207
|
+
return (raw if major == 2 else raw.decode()), i + n
|
|
208
|
+
if major == 4:
|
|
209
|
+
items = []
|
|
210
|
+
for _ in range(n):
|
|
211
|
+
item, i = cbor(data, i)
|
|
212
|
+
items.append(item)
|
|
213
|
+
return items, i
|
|
214
|
+
if major == 5:
|
|
215
|
+
out = {}
|
|
216
|
+
for _ in range(n):
|
|
217
|
+
key, i = cbor(data, i)
|
|
218
|
+
out[key], i = cbor(data, i)
|
|
219
|
+
return out, i
|
|
220
|
+
raise ValueError(f"CBOR major type {major}")
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def release_key_label(root: Path) -> list[str]:
|
|
224
|
+
"""Problems with the label of the key release.json names (RS-SUP-05)."""
|
|
225
|
+
path = root / "release.json"
|
|
226
|
+
if not path.is_file():
|
|
227
|
+
return ["no release.json: the release key cannot be checked"]
|
|
228
|
+
release = json.loads(path.read_text(encoding="utf-8"))
|
|
229
|
+
key = release.get("key")
|
|
230
|
+
if not key:
|
|
231
|
+
return ["release.json names no key"]
|
|
232
|
+
names = [release.get("name")] + [p.get("name") for p in release.get("packages", [])]
|
|
233
|
+
names = [n for n in names if n]
|
|
234
|
+
# A workspace's crates share a family name: example-core, example-cli.
|
|
235
|
+
names += [n.split("-")[0] for n in names]
|
|
236
|
+
obj = root / release.get("corpus", "corpus") / "objects" / (key.replace(":", "_") + ".cbor")
|
|
237
|
+
if not obj.is_file():
|
|
238
|
+
return [f"the key object {key} is not in {obj.parent.relative_to(root)}/: export it"]
|
|
239
|
+
try:
|
|
240
|
+
label = cbor(obj.read_bytes())[0].get("body", {}).get("label", "")
|
|
241
|
+
except (ValueError, IndexError, UnicodeDecodeError, AttributeError):
|
|
242
|
+
return [f"{obj.relative_to(root)} is not a key object"]
|
|
243
|
+
if not label.endswith("release key") or not any(n in label for n in names):
|
|
244
|
+
want = f"{min(names, key=len)} release key" if names else "<package> release key"
|
|
245
|
+
return [f"the release key is labelled {label!r}: label it for what it releases, "
|
|
246
|
+
f"such as {want!r}, not with a person's name; rotate to a key labelled so"]
|
|
247
|
+
return []
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def audit_declared(root: Path) -> list[str]:
|
|
251
|
+
"""Problems with release.json's declaration of the audit check (RS-REL-01)."""
|
|
252
|
+
path = root / "release.json"
|
|
253
|
+
if not path.is_file():
|
|
254
|
+
return [] # RS-SUP-05 already reports a missing release.json
|
|
255
|
+
release = json.loads(path.read_text(encoding="utf-8"))
|
|
256
|
+
checks = release.get("security", {}).get("checks", [])
|
|
257
|
+
if any("pubrules audit --check" in str(c.get("run", "")) for c in checks):
|
|
258
|
+
return []
|
|
259
|
+
return ["release.json declares no `pubrules audit --check` security check: add one "
|
|
260
|
+
"named \"quality audit current\", whose run is `.venv/bin/pubrules audit --check` "
|
|
261
|
+
"and whose version is `.venv/bin/pubrules --version`"]
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def workflow_pins(root: Path, calls: str) -> list[str]:
|
|
265
|
+
"""Problems with the pins of pubrules' reusable workflows and actions in
|
|
266
|
+
this repository's workflows, under any owner, and a repository that
|
|
267
|
+
calls neither rust-ci.yml nor the job-rust-*.yml jobs; `calls` is the
|
|
268
|
+
owner whose rust-ci.yml it should call."""
|
|
269
|
+
problems, uses = [], 0
|
|
270
|
+
commit = release_commit()
|
|
271
|
+
for path in sorted((root / ".github" / "workflows").glob("*.y*ml")):
|
|
272
|
+
uses += len(WORKFLOW_PIN.findall(path.read_text(encoding="utf-8")))
|
|
273
|
+
# Every pin of pubrules, rust-ci.yml's among them, against this pubrules.
|
|
274
|
+
problems += stale_pins(root, __version__, commit)[0]
|
|
275
|
+
if not uses:
|
|
276
|
+
problems.append(f"no workflow calls {calls}/pubrules/.github/workflows/rust-ci.yml; "
|
|
277
|
+
"give pubrules.json a ci block, and `pubrules sync` writes them")
|
|
278
|
+
return problems
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def run(root: Path, config: dict) -> tuple[list[str], list[str]]:
|
|
282
|
+
"""(lines to print, problems). An empty problem list means the
|
|
283
|
+
repository conforms."""
|
|
284
|
+
rules = standard.load()["rules"]
|
|
285
|
+
known = {r["id"] for r in rules}
|
|
286
|
+
waived, open_, problems = exceptions(config, known)
|
|
287
|
+
for rule, texts in sorted(checks(root, config).items()):
|
|
288
|
+
if rule in waived:
|
|
289
|
+
continue
|
|
290
|
+
problems += [f"{rule}: {t}" for t in texts]
|
|
291
|
+
problems += workflow_pins(root, owner(config))
|
|
292
|
+
conformed = sum(1 for r in rules if any(c["kind"] == "conform" for c in r["checks"]))
|
|
293
|
+
lines = [f"conforms to the Rust crate standard ({conformed} rules checked here)"]
|
|
294
|
+
lines += [f"open exception: {e}" for e in open_]
|
|
295
|
+
return lines, problems
|
pubrules/doc_coverage.py
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
"""`pubrules doc-coverage`: every public function of a published library has
|
|
2
|
+
an example, and every public item says which tests cover it.
|
|
3
|
+
|
|
4
|
+
For each crate this:
|
|
5
|
+
|
|
6
|
+
- lists its public functions and methods (`pub fn`; with `unreachable_pub`
|
|
7
|
+
every `pub` item is reachable) and fails if any has no example in its
|
|
8
|
+
documentation;
|
|
9
|
+
- reads `// covers: Item` comments in the crate's tests and sources -- a test
|
|
10
|
+
names the items it exercises, such as `// covers: Object::parse, Cid::of`
|
|
11
|
+
-- and fails if one names an item that does not exist;
|
|
12
|
+
- writes the crate's TESTING.md beside its Cargo.toml: for every public
|
|
13
|
+
item, how many examples its documentation runs and which tests cover it.
|
|
14
|
+
|
|
15
|
+
TESTING.md is a view, never edited by hand. `make doc-coverage` writes it;
|
|
16
|
+
`make doc-coverage-check` (in CI) fails if it is stale or the rules above
|
|
17
|
+
are broken. The crates are the published packages with a library target,
|
|
18
|
+
from `cargo metadata`, unless named.
|
|
19
|
+
|
|
20
|
+
It lives here so every repository runs the same version.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import json
|
|
26
|
+
import re
|
|
27
|
+
import subprocess
|
|
28
|
+
import sys
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
|
|
31
|
+
FN = re.compile(r"\s*pub (?:const )?fn (\w+)")
|
|
32
|
+
TYPE = re.compile(r"\s*pub (?:struct|enum|trait|type) (\w+)")
|
|
33
|
+
IMPL = re.compile(r"\s*impl(?:<[^>]*>)?\s+")
|
|
34
|
+
TRAIT = re.compile(r"[\w:<>, ]+")
|
|
35
|
+
TEST_FN = re.compile(r"\s*(?:pub )?fn (\w+)")
|
|
36
|
+
COVERS = re.compile(r"//\s*covers:\s*(.+)")
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def impl_of(line: str) -> str | None:
|
|
40
|
+
"""The type an `impl` line implements for: `Foo` in `impl Foo` and in
|
|
41
|
+
`impl<T> Trait<T> for Foo<T>`. Split on ` for ` rather than matched in
|
|
42
|
+
one pattern, which would backtrack."""
|
|
43
|
+
m = IMPL.match(line)
|
|
44
|
+
if not m:
|
|
45
|
+
return None
|
|
46
|
+
rest = line[m.end():]
|
|
47
|
+
trait, sep, target = rest.partition(" for ")
|
|
48
|
+
if sep and TRAIT.fullmatch(trait.rstrip()):
|
|
49
|
+
rest = target.lstrip()
|
|
50
|
+
name = re.match(r"\w+", rest)
|
|
51
|
+
return name.group(0) if name else None
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def strip(line: str) -> str:
|
|
55
|
+
"""The line without string literals or a trailing comment, for brace counting."""
|
|
56
|
+
line = re.sub(r'"(?:\\.|[^"\\])*"', '""', line)
|
|
57
|
+
line = re.sub(r"'(?:\\.|[^'\\])'", "''", line)
|
|
58
|
+
return line.split("//", 1)[0]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def public_module(src: Path, lib: Path, path: Path) -> str:
|
|
62
|
+
"""The module path users write for items defined in `path`.
|
|
63
|
+
|
|
64
|
+
Only modules declared `pub mod` appear: a private module's items are
|
|
65
|
+
re-exported into its parent (`mod sig; pub use sig::sign;` makes `sign`
|
|
66
|
+
a crate-root function), so they are named from there.
|
|
67
|
+
"""
|
|
68
|
+
rel = path.relative_to(src).with_suffix("")
|
|
69
|
+
parts = [p for p in rel.parts if p not in (lib.stem, "mod")]
|
|
70
|
+
chain, parent = [], lib
|
|
71
|
+
for part in parts:
|
|
72
|
+
declared = parent.read_text() if parent.exists() else ""
|
|
73
|
+
if re.search(rf"^\s*pub mod {part}\s*;", declared, re.M):
|
|
74
|
+
chain.append(part)
|
|
75
|
+
directory = parent.parent if parent.name in (lib.name, "mod.rs") else parent.with_suffix("")
|
|
76
|
+
parent = directory / part / "mod.rs"
|
|
77
|
+
if not parent.exists():
|
|
78
|
+
parent = directory / f"{part}.rs"
|
|
79
|
+
return "::".join(chain)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class Crate:
|
|
83
|
+
"""A published library: its name, directory, library root and binaries."""
|
|
84
|
+
|
|
85
|
+
def __init__(self, name: str, directory: Path, lib: Path, skip: set[Path], repo: str):
|
|
86
|
+
self.name, self.dir, self.lib, self.skip, self.repo = name, directory, lib, skip, repo
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def crates(root: Path, names: list[str]) -> list[Crate]:
|
|
90
|
+
meta = json.loads(subprocess.run(
|
|
91
|
+
["cargo", "metadata", "--no-deps", "--format-version", "1"],
|
|
92
|
+
cwd=root, check=True, capture_output=True, text=True,
|
|
93
|
+
).stdout)
|
|
94
|
+
out = []
|
|
95
|
+
packages = {pkg["name"] for pkg in meta["packages"]}
|
|
96
|
+
unknown = set(names) - packages
|
|
97
|
+
if unknown:
|
|
98
|
+
sys.exit(f"pubrules: no crate here named {', '.join(sorted(unknown))}")
|
|
99
|
+
for pkg in meta["packages"]:
|
|
100
|
+
lib = next((t for t in pkg["targets"] if "lib" in t["kind"]), None)
|
|
101
|
+
# A named crate with no library, a command-line tool, has no
|
|
102
|
+
# TESTING.md: its README and --help are its documentation.
|
|
103
|
+
if lib is None or (names and pkg["name"] not in names):
|
|
104
|
+
continue
|
|
105
|
+
if not names and pkg.get("publish") == []:
|
|
106
|
+
continue
|
|
107
|
+
skip = {Path(t["src_path"]) for t in pkg["targets"] if "bin" in t["kind"]}
|
|
108
|
+
repo = (pkg.get("repository") or "").rstrip("/")
|
|
109
|
+
out.append(Crate(pkg["name"], Path(pkg["manifest_path"]).parent, Path(lib["src_path"]),
|
|
110
|
+
skip, repo))
|
|
111
|
+
return out
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def items(crate: Crate) -> list[tuple]:
|
|
115
|
+
"""Public items: (name, kind, file, line, examples)."""
|
|
116
|
+
out = []
|
|
117
|
+
src = crate.lib.parent
|
|
118
|
+
for path in sorted(p for p in src.rglob("*.rs") if p not in crate.skip):
|
|
119
|
+
lines = path.read_text().splitlines()
|
|
120
|
+
depth, impl_stack, in_test = 0, [], None
|
|
121
|
+
module = public_module(src, crate.lib, path)
|
|
122
|
+
for i, line in enumerate(lines):
|
|
123
|
+
if in_test is None and re.match(r"\s*#\[cfg\(test\)\]", line):
|
|
124
|
+
in_test = depth
|
|
125
|
+
code = strip(line)
|
|
126
|
+
if in_test is None:
|
|
127
|
+
impl = impl_of(line) if line.strip().startswith("impl") else None
|
|
128
|
+
fn, ty = FN.match(line), TYPE.match(line)
|
|
129
|
+
if fn or ty:
|
|
130
|
+
j, doc = i - 1, []
|
|
131
|
+
while j >= 0 and (lines[j].strip().startswith("///")
|
|
132
|
+
or lines[j].strip().startswith("#[")):
|
|
133
|
+
doc.append(lines[j])
|
|
134
|
+
j -= 1
|
|
135
|
+
examples = sum(1 for d in doc if d.strip().startswith("/// ```")) // 2
|
|
136
|
+
if fn:
|
|
137
|
+
owner = impl_stack[-1][1] if impl_stack else module
|
|
138
|
+
name = f"{owner}::{fn.group(1)}" if owner else fn.group(1)
|
|
139
|
+
out.append((name, "fn", path, i + 1, examples))
|
|
140
|
+
else:
|
|
141
|
+
out.append((ty.group(1), "type", path, i + 1, examples))
|
|
142
|
+
if impl and "{" in code:
|
|
143
|
+
impl_stack.append((depth, impl))
|
|
144
|
+
depth += code.count("{") - code.count("}")
|
|
145
|
+
while impl_stack and depth <= impl_stack[-1][0]:
|
|
146
|
+
impl_stack.pop()
|
|
147
|
+
if in_test is not None and depth <= in_test and "}" in code:
|
|
148
|
+
in_test = None
|
|
149
|
+
return out
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def covered(crate: Crate, root: Path) -> dict:
|
|
153
|
+
"""Tests that say what they cover: {item: [(file, test, line)]}."""
|
|
154
|
+
found: dict = {}
|
|
155
|
+
files = list((crate.dir / "tests").rglob("*.rs")) + list(crate.lib.parent.rglob("*.rs"))
|
|
156
|
+
for path in sorted(files):
|
|
157
|
+
lines = path.read_text().splitlines()
|
|
158
|
+
for i, line in enumerate(lines):
|
|
159
|
+
m = COVERS.search(line)
|
|
160
|
+
if not m:
|
|
161
|
+
continue
|
|
162
|
+
test = None
|
|
163
|
+
for later in lines[i + 1:i + 8]:
|
|
164
|
+
t = TEST_FN.match(later)
|
|
165
|
+
if t:
|
|
166
|
+
test = t.group(1)
|
|
167
|
+
break
|
|
168
|
+
for name in (n.strip() for n in m.group(1).split(",")):
|
|
169
|
+
if name:
|
|
170
|
+
found.setdefault(name, []).append((path.relative_to(root), test, i + 1))
|
|
171
|
+
return found
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def report(crate: Crate, public: list[tuple], tests: dict) -> str:
|
|
175
|
+
fns = [p for p in public if p[1] == "fn"]
|
|
176
|
+
with_examples = sum(1 for p in fns if p[4] > 0)
|
|
177
|
+
with_tests = sum(1 for p in public if p[0] in tests)
|
|
178
|
+
lines = [
|
|
179
|
+
f"# Testing: {crate.name}",
|
|
180
|
+
"",
|
|
181
|
+
"Generated by `pubrules doc-coverage`; do not edit.",
|
|
182
|
+
"",
|
|
183
|
+
f"{len(public)} public items; {with_examples} of {len(fns)} functions have examples, "
|
|
184
|
+
f"and {with_tests} items name the tests that cover them.",
|
|
185
|
+
"",
|
|
186
|
+
"Every example in the documentation runs as a test (`cargo test --doc`). A",
|
|
187
|
+
"test is listed against an item when its `// covers:` comment says it exercises",
|
|
188
|
+
"that item: as the subject of the test, or within the same module to set it up.",
|
|
189
|
+
"A test claims only items of the module it tests. The files are linked below.",
|
|
190
|
+
"",
|
|
191
|
+
"| Item | Examples | Tests |",
|
|
192
|
+
"|---|---|---|",
|
|
193
|
+
]
|
|
194
|
+
for name, kind, _path, _line, examples in sorted(public, key=lambda p: p[0].lower()):
|
|
195
|
+
names = sorted({f"`{t}`" for _, t, _ in tests.get(name, []) if t})
|
|
196
|
+
lines.append(f"| `{name}` | {examples if kind == 'fn' or examples else '-'} | "
|
|
197
|
+
f"{', '.join(names) if names else '-'} |")
|
|
198
|
+
files = sorted({str(f) for v in tests.values() for f, _, _ in v})
|
|
199
|
+
if files:
|
|
200
|
+
lines += ["", "Test files:", ""]
|
|
201
|
+
if crate.repo:
|
|
202
|
+
lines += [f"- [`{f}`]({crate.repo}/blob/main/{f})" for f in files]
|
|
203
|
+
else:
|
|
204
|
+
lines += [f"- `{f}`" for f in files]
|
|
205
|
+
return "\n".join(lines) + "\n"
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def run(root: Path, names: list[str], check: bool) -> int:
|
|
209
|
+
problems = []
|
|
210
|
+
for crate in crates(root, names):
|
|
211
|
+
public = items(crate)
|
|
212
|
+
known = {p[0] for p in public}
|
|
213
|
+
tests = covered(crate, root)
|
|
214
|
+
for p in public:
|
|
215
|
+
if p[1] == "fn" and p[4] == 0:
|
|
216
|
+
problems.append(f"{p[2].relative_to(root)}:{p[3]}: `{p[0]}` has no example")
|
|
217
|
+
for name, sites in tests.items():
|
|
218
|
+
if name not in known:
|
|
219
|
+
for f, _, line in sites:
|
|
220
|
+
problems.append(f"{f}:{line}: covers `{name}`, which is not a public item "
|
|
221
|
+
f"of {crate.name}")
|
|
222
|
+
text = report(crate, public, tests)
|
|
223
|
+
path = crate.dir / "TESTING.md"
|
|
224
|
+
if check:
|
|
225
|
+
if not path.exists() or path.read_text() != text:
|
|
226
|
+
problems.append(f"{path.relative_to(root)} is stale; run `make doc-coverage`")
|
|
227
|
+
else:
|
|
228
|
+
print(f"{path.relative_to(root)} current for {crate.name}")
|
|
229
|
+
else:
|
|
230
|
+
path.write_text(text)
|
|
231
|
+
print(f"wrote {path.relative_to(root)}")
|
|
232
|
+
if problems:
|
|
233
|
+
print("\n".join(problems), file=sys.stderr)
|
|
234
|
+
return 1 if check else 0
|
|
235
|
+
return 0
|
pubrules/freshness.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""`pubrules bump`: keep a pub* repository on the latest pubrules, so none sits on
|
|
2
|
+
an old standard unnoticed. (a control plane's reusable workflow reports which pubrules each
|
|
3
|
+
repository pins; `pinned` here is what it, and the version guard, read.)
|
|
4
|
+
|
|
5
|
+
`pubrules bump`, run in a repository, moves it to this pubrules: the managed
|
|
6
|
+
files (`pubrules sync`), the lock (`pubrules lock`), and every workflow's pin of
|
|
7
|
+
pubrules' reusable workflows (rust-ci.yml, service-ci.yml...) and actions
|
|
8
|
+
(cache), to the commit of this pubrules' tag (refs.py). The nightly
|
|
9
|
+
workflow does this, and more, through `pubrules nightly` (nightly.py).
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
from . import __version__
|
|
18
|
+
from .refs import (ANY_OWNER, AT, PUBRULES_PIN, VERSION, owner_of, ref, release_commit, repin,
|
|
19
|
+
stale_pins)
|
|
20
|
+
|
|
21
|
+
# pubrules's wheel in a lock: one group, the version, as pubfleet's board
|
|
22
|
+
# reads it (PIN.findall).
|
|
23
|
+
PIN = re.compile(r"/download/v([0-9][^/]*)/pubrules-")
|
|
24
|
+
# pubrules's wheel, or pubkit's, which pubrules was called before 0.43.0.
|
|
25
|
+
PACKAGE_PIN = re.compile(r"/download/v(?P<version>[0-9][^/]*)/(?P<package>pubrules|pubkit)-")
|
|
26
|
+
WORKFLOW_PIN = re.compile(ANY_OWNER + r"(?P<path>pubrules/\.github/workflows/rust-ci\.yml@)"
|
|
27
|
+
+ AT + VERSION)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def pinned_package(repo: Path) -> tuple[str, str] | None:
|
|
31
|
+
"""(the package, its version) a repository's lock pins: pubrules, or
|
|
32
|
+
pubkit for a repository not yet moved past the rename."""
|
|
33
|
+
lock = repo / "tests" / "requirements.lock"
|
|
34
|
+
if not lock.is_file():
|
|
35
|
+
return None
|
|
36
|
+
m = PACKAGE_PIN.search(lock.read_text(encoding="utf-8"))
|
|
37
|
+
return (m["package"], m["version"]) if m else None
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def pinned(repo: Path) -> str | None:
|
|
41
|
+
"""The pubrules version a repository's lock pins (pubkit's, before the rename)."""
|
|
42
|
+
found = pinned_package(repo)
|
|
43
|
+
return found[1] if found else None
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def bump(root: Path) -> int:
|
|
47
|
+
"""Move this repository to this pubrules: managed files, lock, workflow pins."""
|
|
48
|
+
from .cli import lock, sync # noqa: PLC0415
|
|
49
|
+
|
|
50
|
+
# What installed packages move (pubdeploy's: deploy.providers, and the
|
|
51
|
+
# uses of its workflows), before sync writes the launchers from them.
|
|
52
|
+
from .hooks import bump as bump_hooks # noqa: PLC0415
|
|
53
|
+
for line in bump_hooks(root):
|
|
54
|
+
print(line)
|
|
55
|
+
before = pinned_package(root)
|
|
56
|
+
sync(root, check=False)
|
|
57
|
+
lock(root)
|
|
58
|
+
# A rule this pubrules brings that the repository fails is waived, for a
|
|
59
|
+
# while, by the move that brings it.
|
|
60
|
+
from .gherkin import grandfather # noqa: PLC0415
|
|
61
|
+
for line in grandfather(root, *(before or (None, None))):
|
|
62
|
+
print(line)
|
|
63
|
+
commit, calls = release_commit(), owner_of(root)
|
|
64
|
+
for path in sorted((root / ".github" / "workflows").glob("*.y*ml")):
|
|
65
|
+
text = path.read_text(encoding="utf-8")
|
|
66
|
+
new = repin(PUBRULES_PIN, text, calls, __version__, commit)
|
|
67
|
+
if new != text:
|
|
68
|
+
path.write_text(new, encoding="utf-8")
|
|
69
|
+
print(f"updated {path.relative_to(root)} (pubrules@{ref(__version__, commit)})")
|
|
70
|
+
for use in stale_pins(root, __version__, commit)[1]:
|
|
71
|
+
print(f"left {use}: it names no pubrules version; pin it "
|
|
72
|
+
f"@{ref(__version__, commit)} for `pubrules bump` to move it")
|
|
73
|
+
print(f"bumped to pubrules {__version__}; run `make check`, record nothing (no code "
|
|
74
|
+
f"changed), and open the pull request")
|
|
75
|
+
return 0
|