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
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
@@ -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