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/standard.py ADDED
@@ -0,0 +1,266 @@
1
+ """The Rust crate standard's checked rules, as data.
2
+
3
+ Every `[checked: ...]` tag in `plugins/rust-crate-quality/rust-crate-standard.md`
4
+ gives a rule a stable ID and names what checks it. `generate` reads the tags
5
+ into `standard.json`, which ships inside pubrules; `required` turns that into
6
+ the make targets each `rust-ci.yml` job runs for a repository.
7
+
8
+ python -m pubrules.standard # rewrite src/pubrules/standard.json
9
+ python -m pubrules.standard --check # fail if it differs from the tags
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import hashlib
15
+ import json
16
+ import re
17
+ import subprocess
18
+ import sys
19
+ from importlib import resources
20
+ from pathlib import Path
21
+
22
+ SOURCE = "plugins/rust-crate-quality/rust-crate-standard.md"
23
+ GENERATED = "src/pubrules/standard.json"
24
+
25
+ # Which rust-ci.yml job runs each make target the standard names, in the
26
+ # order the job runs them.
27
+ JOBS = {
28
+ "gates": ["fmt-check", "lint", "doc", "doc-coverage-check", "publish-check"],
29
+ "functional": ["functional", "vectors-check", "supply-chain-check"],
30
+ "msrv": ["msrv"],
31
+ "fuzz": ["fuzz-smoke"],
32
+ "audit": ["deny", "vet"],
33
+ }
34
+ # Run for every Rust repository, though no tag names them: formatting, the
35
+ # lints and docs section 6's table requires of every kind of crate, and the
36
+ # Gherkin suite every package has.
37
+ BASELINE = {"fmt-check": "gates", "lint": "gates", "doc": "gates", "functional": "functional"}
38
+ WORKFLOW_JOBS = {"test", "cross", "fuzz"}
39
+
40
+ # The fields after the rule ID keep their leading space: `\s*` before
41
+ # `[^\]]*` could match the same spaces either way, which backtracks.
42
+ TAG = re.compile(r"(?<!`)\[checked:\s*(RS-[A-Z]+-\d{2}),([^\]]*)\]")
43
+ HEADING = re.compile(r"^## (\d+)\. (.+)$", re.M)
44
+ # The question after `judged:` keeps its leading space (stripped later):
45
+ # `\s*` before `[^\]]*` could match the same spaces either way.
46
+ JUDGED = re.compile(r"\[judged(?::([^\]]*))?\]|; *judged:([^\]]*)\]")
47
+ # Sections whose judged rules only a crate of one kind is held to: the crate
48
+ # root and item docs are a library's, section 9 a command-line tool's.
49
+ JUDGED_APPLIES = {"1": "library", "2": "library", "9": "binary"}
50
+ # Judged rules, by key, that apply to a library only though their section
51
+ # applies to every crate: docs.rs renders nothing for a binary.
52
+ LIBRARY_ONLY = {"5.4"}
53
+
54
+
55
+ def job_of(target: str) -> str:
56
+ for job, targets in JOBS.items():
57
+ if target in targets:
58
+ return job
59
+ raise ValueError(f"no rust-ci.yml job runs `make {target}`; add it to JOBS")
60
+
61
+
62
+ def parse(text: str) -> list[dict]:
63
+ """The checked rules of the standard's text, in order."""
64
+ headings = [(m.start(), f"{m.group(1)}. {m.group(2)}") for m in HEADING.finditer(text)]
65
+ rules, seen = [], set()
66
+ for m in TAG.finditer(text):
67
+ rule = m.group(1)
68
+ if rule in seen:
69
+ raise ValueError(f"{rule} tags two rules")
70
+ seen.add(rule)
71
+ fields = " ".join(m.group(2).split()).split(";")[0]
72
+ checks, applies = [], "every crate"
73
+ for field in (f.strip() for f in fields.split(",")):
74
+ if field == "library":
75
+ applies = "library"
76
+ elif field.startswith("make "):
77
+ target = field.removeprefix("make ")
78
+ checks.append({"kind": "make", "target": target, "job": job_of(target)})
79
+ elif field.startswith("rust-ci "):
80
+ job = field.removeprefix("rust-ci ")
81
+ if job not in WORKFLOW_JOBS:
82
+ raise ValueError(f"{rule}: rust-ci.yml has no always-run job `{job}`")
83
+ checks.append({"kind": "job", "job": job})
84
+ elif field in ("pubrel", "pubrules conform"):
85
+ checks.append({"kind": field.split()[-1]})
86
+ else:
87
+ raise ValueError(f"{rule}: unknown check `{field}`")
88
+ if not checks:
89
+ raise ValueError(f"{rule} names no check")
90
+ section = next((h for start, h in reversed(headings) if start < m.start()), "")
91
+ rules.append({"id": rule, "section": section, "applies": applies, "checks": checks})
92
+ return rules
93
+
94
+
95
+ def _blocks(body: str) -> list[str]:
96
+ """A section's text as its top-level items: each list item or paragraph
97
+ starting at the margin, with everything indented under it."""
98
+ blocks, current, blank = [], [], True
99
+ for line in body.splitlines():
100
+ if not line.strip():
101
+ blank = True
102
+ if current:
103
+ current.append("")
104
+ continue
105
+ margin = not line.startswith((" ", "\t"))
106
+ if margin and (re.match(r"(- |\d+\. )", line) or blank) and current:
107
+ blocks.append("\n".join(current).strip())
108
+ current = []
109
+ current.append(line)
110
+ blank = False
111
+ if current:
112
+ blocks.append("\n".join(current).strip())
113
+ return blocks
114
+
115
+
116
+ def _title(block: str) -> str:
117
+ """A judged rule's short name: its bold lead, or its first sentence."""
118
+ bold = re.match(r"(?:- |\d+\. )?\*\*(.+?)\*\*", block)
119
+ if bold:
120
+ return bold.group(1).rstrip(":.").strip()
121
+ text = " ".join(re.sub(r"^(- |\d+\. )", "", block).split())
122
+ text = re.sub(r"\*\*([^*`/]+?)\*\*", r"\1", text)
123
+ return re.split(r"(?<=[.:])\s", text, maxsplit=1)[0].rstrip(":.")
124
+
125
+
126
+ def judged(text: str) -> list[dict]:
127
+ """The judged rules of the standard's text, in order.
128
+
129
+ The standard tags only its checked rules with IDs. A judged rule is
130
+ keyed here by its section and its place among the section's judged
131
+ rules (`1.6`, Related crates), which holds for as long as the text does:
132
+ a report names the standard's sha256, so a key never outlives the text
133
+ it was read from. Section 10, on writing, carries no tags and is judged
134
+ throughout, as one rule.
135
+ """
136
+ heads = list(HEADING.finditer(text))
137
+ rules = []
138
+ for i, head in enumerate(heads):
139
+ end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
140
+ body = text[head.end():end].split("\n## ", 1)[0]
141
+ number, name = head.group(1), head.group(2)
142
+ found = 0
143
+ for block in _blocks(body):
144
+ for m in JUDGED.finditer(block):
145
+ found += 1
146
+ key = f"{number}.{found}"
147
+ checked = TAG.search(block)
148
+ applies = "library" if key in LIBRARY_ONLY else JUDGED_APPLIES.get(number, "every crate")
149
+ rules.append({
150
+ "id": key, "section": f"{number}. {name}", "title": _title(block),
151
+ "applies": applies, "question": (m.group(1) or m.group(2) or "").strip(),
152
+ "checked": checked.group(1) if checked else "",
153
+ "text": " ".join(block.split()),
154
+ })
155
+ if not found and name == "Writing":
156
+ rules.append({"id": f"{number}.1", "section": f"{number}. {name}", "title": "Writing",
157
+ "applies": "every crate", "question": "", "checked": "",
158
+ "text": " ".join(body.split())})
159
+ return rules
160
+
161
+
162
+ def generate(root: Path) -> str:
163
+ text = (root / SOURCE).read_text(encoding="utf-8")
164
+ data = {
165
+ "comment": f"Generated from {SOURCE} by `make standard`. Do not edit.",
166
+ "source": SOURCE,
167
+ "sha256": hashlib.sha256(text.encode()).hexdigest(),
168
+ "baseline": [{"target": t, "job": j} for t, j in BASELINE.items()],
169
+ "rules": parse(text),
170
+ "judged": judged(text),
171
+ }
172
+ return json.dumps(data, indent=2) + "\n"
173
+
174
+
175
+ def load() -> dict:
176
+ """The standard.json this pubrules ships."""
177
+ return json.loads((resources.files("pubrules") / "standard.json").read_text(encoding="utf-8"))
178
+
179
+
180
+ def has_library(root: Path) -> bool:
181
+ """Whether a published package here has a library target."""
182
+ meta = json.loads(subprocess.run(
183
+ ["cargo", "metadata", "--no-deps", "--format-version", "1"],
184
+ cwd=root, check=True, capture_output=True, text=True,
185
+ ).stdout)
186
+ for pkg in meta["packages"]:
187
+ if pkg.get("publish") == []:
188
+ continue
189
+ if any("lib" in t["kind"] for t in pkg["targets"]):
190
+ return True
191
+ return False
192
+
193
+
194
+ def required(standard: dict, library: bool, waived: frozenset[str] = frozenset()) -> dict:
195
+ """The make targets each job must run, in order, and the workflow jobs
196
+ the rules turn on.
197
+
198
+ A target is required by the baseline, or by any rule that applies and is
199
+ not waived. `waived` holds rule IDs a repository has excepted.
200
+ """
201
+ wanted: set[str] = {b["target"] for b in standard["baseline"]}
202
+ jobs_on = set()
203
+ for rule in standard["rules"]:
204
+ if rule["id"] in waived or (rule["applies"] == "library" and not library):
205
+ continue
206
+ for check in rule["checks"]:
207
+ if check["kind"] == "make":
208
+ wanted.add(check["target"])
209
+ elif check["kind"] == "job":
210
+ jobs_on.add(check["job"])
211
+ out = {job: [t for t in targets if t in wanted] for job, targets in JOBS.items()}
212
+ return {"targets": out, "jobs": sorted(jobs_on)}
213
+
214
+
215
+ # What a change must touch for a pull request to run fuzzing and the
216
+ # emulated cross-platform tests: Rust sources, Cargo's files and the pinned
217
+ # toolchain, the fuzz targets, and the workflows.
218
+ SLOW_JOBS = ("fuzz", "cross")
219
+
220
+
221
+ def touches_code(path: str) -> bool:
222
+ """Whether a change to `path` can change what fuzzing or the cross tests
223
+ run: a Rust source, a Cargo manifest or lock, the toolchain pin, anything
224
+ under fuzz/, or a GitHub workflow."""
225
+ name = path.rsplit("/", 1)[-1]
226
+ return (
227
+ name.endswith(".rs")
228
+ or name in ("Cargo.toml", "Cargo.lock", "rust-toolchain.toml", "rust-toolchain")
229
+ or path.startswith("fuzz/")
230
+ or path.startswith(".github/workflows/")
231
+ )
232
+
233
+
234
+ def skip_slow(event: str, head_ref: str, changed: list[str] | None) -> str | None:
235
+ """Why fuzz and cross can be skipped, or `None` when they must run.
236
+
237
+ Only on a pull request, only when the changed files are known, and only
238
+ when none of them touches code. A release pull request (its branch is
239
+ `release/...`), a push, and a scheduled or manual run always run
240
+ everything.
241
+ """
242
+ if event != "pull_request" or changed is None or head_ref.startswith("release/"):
243
+ return None
244
+ if any(touches_code(p) for p in changed):
245
+ return None
246
+ return ("this pull request touches no Rust code, Cargo files, fuzz/ or workflow "
247
+ "files, so fuzz and cross are skipped; releases and the nightly run them")
248
+
249
+
250
+ def main(argv: list[str]) -> int:
251
+ root = Path(__file__).resolve().parents[2]
252
+ text = generate(root)
253
+ path = root / GENERATED
254
+ if "--check" in argv:
255
+ if not path.exists() or path.read_text(encoding="utf-8") != text:
256
+ print(f"{GENERATED} is stale; run `make standard`", file=sys.stderr)
257
+ return 1
258
+ print(f"{GENERATED} current")
259
+ return 0
260
+ path.write_text(text, encoding="utf-8")
261
+ print(f"wrote {GENERATED}")
262
+ return 0
263
+
264
+
265
+ if __name__ == "__main__":
266
+ sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,188 @@
1
+ """`pubrules supply-chain`: write each named crate's SUPPLY-CHAIN.md from supply-chain/.
2
+
3
+ For every crate a published crate depends on -- at build time or run
4
+ time, on any target -- the report says how its code is vouched for: an
5
+ audit imported from an organisation that publishes them, a publisher those
6
+ organisations trust, or an exemption, with the evidence recorded in the
7
+ exemption's notes. It also marks the dependencies that run code while
8
+ compiling (a build script or a procedural macro).
9
+
10
+ The report is a view of what `cargo vet` enforces, never edited by hand:
11
+ `make supply-chain` regenerates it, and `make supply-chain-check` fails in
12
+ CI if the committed copy is stale. It goes beside each crate's manifest.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import subprocess
19
+ import sys
20
+ import textwrap
21
+ import tomllib
22
+ from pathlib import Path
23
+
24
+ # The organisations whose audit sets cargo vet imports, by import name.
25
+ ORGANISATIONS = {
26
+ "bytecode-alliance": "the Bytecode Alliance",
27
+ "embark-studios": "Embark Studios",
28
+ "google": "Google",
29
+ "isrg": "ISRG",
30
+ "mozilla": "Mozilla",
31
+ "zcash": "Zcash",
32
+ }
33
+
34
+
35
+ def load(root, name):
36
+ with open(root / "supply-chain" / name, "rb") as f:
37
+ return tomllib.load(f)
38
+
39
+
40
+ def metadata(root):
41
+ out = subprocess.run(
42
+ ["cargo", "metadata", "--format-version", "1", "--locked"],
43
+ capture_output=True, text=True, check=True, cwd=root).stdout
44
+ return json.loads(out)
45
+
46
+
47
+ def dependencies(root, meta, crate):
48
+ """Every registry crate `crate` needs to build and run, with flags.
49
+
50
+ Resolved with `cargo tree -p`, so features are those `crate` itself
51
+ enables: what a user depending on it alone builds, not what other
52
+ workspace members switch on. Every target counts, so a dependency built
53
+ only on some platforms is listed; one that is locked but never built,
54
+ such as an optional dependency nothing enables, is not.
55
+ """
56
+ # The name cargo gets is the workspace's own, never the argument, so it
57
+ # cannot be an option.
58
+ name = next((p["name"] for p in meta["packages"]
59
+ if p.get("source") is None and p["name"] == crate), None)
60
+ if name is None:
61
+ sys.exit(f"pubrules: {crate!r} is not a crate in this workspace")
62
+ out = subprocess.run(
63
+ ["cargo", "tree", "--locked", "-q", f"--package={name}", "-e", "normal,build", "--target", "all",
64
+ "--prefix", "none", "--format", "{p}"],
65
+ capture_output=True, text=True, check=True, cwd=root).stdout
66
+ wanted = set()
67
+ for line in out.splitlines():
68
+ parts = line.split()
69
+ if len(parts) >= 2 and parts[1].startswith("v") and "(/" not in line:
70
+ wanted.add((parts[0], parts[1][1:]))
71
+ kinds = {}
72
+ for pkg in meta["packages"]:
73
+ if pkg.get("source") is not None:
74
+ kinds[(pkg["name"], pkg["version"])] = {
75
+ k for t in pkg["targets"] for k in t["kind"]}
76
+ return sorted(
77
+ ({"name": n, "version": v,
78
+ "build_script": "custom-build" in kinds.get((n, v), set()),
79
+ "proc_macro": "proc-macro" in kinds.get((n, v), set())}
80
+ for n, v in wanted),
81
+ key=lambda d: (d["name"], d["version"]))
82
+
83
+
84
+ def imported_audits(imports, name, version):
85
+ """Organisations whose imported audit covers exactly this version."""
86
+ orgs = []
87
+ for org, data in imports.get("audits", {}).items():
88
+ for audit in data.get("audits", {}).get(name, []):
89
+ if audit.get("version") == version or (
90
+ audit.get("delta", "").split("->")[-1].strip() == version):
91
+ orgs.append(org)
92
+ return sorted(set(orgs))
93
+
94
+
95
+ def status(dep, config, audits, imports):
96
+ name, version = dep["name"], dep["version"]
97
+ for ex in config.get("exemptions", {}).get(name, []):
98
+ if ex["version"] == version:
99
+ return "not audited (exempt)", ex.get("notes", "")
100
+ for audit in audits.get("audits", {}).get(name, []):
101
+ if audit.get("version") == version or (
102
+ audit.get("delta", "").split("->")[-1].strip() == version):
103
+ return "audited by this project", audit.get("notes", "")
104
+ trusted = audits.get("trusted", {}).get(name, [])
105
+ if trusted:
106
+ publishers = [p for p in imports.get("publisher", {}).get(name, [])
107
+ if p["version"] == version]
108
+ who = publishers[0]["user-login"] if publishers else "its publisher"
109
+ return f"trusted publisher ({who})", trusted[0].get("notes", "")
110
+ orgs = imported_audits(imports, name, version)
111
+ if orgs:
112
+ return "audited by " + ", ".join(orgs), ""
113
+ return "audited (a chain of imported audits)", ""
114
+
115
+
116
+ def sources(config):
117
+ """The organisations whose audits `config` imports, as a phrase."""
118
+ names = [ORGANISATIONS.get(n, n) for n in config.get("imports", {})]
119
+ if not names:
120
+ return "No audits are imported."
121
+ listed = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " and " + names[-1]
122
+ return f"Audits are imported from {listed}."
123
+
124
+
125
+ def report(crate, deps, config, audits, imports):
126
+ intro = (
127
+ "Every crate this one needs to build and run, and how its code is vouched for, "
128
+ f"as `cargo vet` enforces it in CI. {sources(config)} A trusted publisher is one "
129
+ "those organisations trust, or this project's own author; the evidence column "
130
+ "says which. *Build-time code* marks a build script (B) or a procedural macro "
131
+ "(P): code that runs while compiling."
132
+ )
133
+ lines = [
134
+ f"# Supply chain: {crate}",
135
+ "",
136
+ "Generated by `pubrules supply-chain` from `supply-chain/`; do not edit.",
137
+ "",
138
+ *textwrap.wrap(intro, 79),
139
+ "",
140
+ "| Crate | Version | Build-time code | Status | Evidence |",
141
+ "|---|---|---|---|---|",
142
+ ]
143
+ counts = {}
144
+ for dep in deps:
145
+ state, notes = status(dep, config, audits, imports)
146
+ key = ("exempt" if state.startswith("not audited")
147
+ else "trusted publisher" if state.startswith("trusted")
148
+ else "audited")
149
+ counts[key] = counts.get(key, 0) + 1
150
+ build = "".join(f for f, on in (("B", dep["build_script"]), ("P", dep["proc_macro"])) if on) or "-"
151
+ lines.append(f"| `{dep['name']}` | {dep['version']} | {build} | {state} | {notes} |")
152
+ summary = ", ".join(f"{n} {k}" for k, n in sorted(counts.items()))
153
+ lines[3:3] = [f"{len(deps)} dependencies: {summary}."]
154
+ return "\n".join(lines) + "\n"
155
+
156
+
157
+ def run(root: Path, crates: list[str], check: bool) -> int:
158
+ """Write, or with `check` compare, each crate's SUPPLY-CHAIN.md."""
159
+ if not (root / "supply-chain" / "config.toml").exists():
160
+ print("pubrules: no supply-chain/config.toml here; run `cargo vet init` first",
161
+ file=sys.stderr)
162
+ return 1
163
+ config = load(root, "config.toml")
164
+ audits, imports = load(root, "audits.toml"), load(root, "imports.lock")
165
+ meta = metadata(root)
166
+ dirs = {p["name"]: Path(p["manifest_path"]).parent
167
+ for p in meta["packages"] if p.get("source") is None}
168
+ unknown = [c for c in crates if c not in dirs]
169
+ if unknown:
170
+ print(f"pubrules: no crate here named {', '.join(unknown)}", file=sys.stderr)
171
+ return 1
172
+ stale = []
173
+ for crate in crates:
174
+ text = report(crate, dependencies(root, meta, crate), config, audits, imports)
175
+ path = dirs[crate] / "SUPPLY-CHAIN.md"
176
+ shown = path.relative_to(root)
177
+ if check:
178
+ if not path.exists() or path.read_text() != text:
179
+ stale.append(str(shown))
180
+ else:
181
+ path.write_text(text)
182
+ print(f"wrote {shown}")
183
+ if stale:
184
+ print("pubrules: stale; run `make supply-chain`: " + ", ".join(stale), file=sys.stderr)
185
+ return 1
186
+ if check:
187
+ print("SUPPLY-CHAIN.md current for " + ", ".join(crates))
188
+ return 0
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "release tags only from CI",
3
+ "target": "tag",
4
+ "enforcement": "active",
5
+ "conditions": { "ref_name": { "exclude": [], "include": ["refs/tags/v*"] } },
6
+ "rules": [
7
+ { "type": "creation" },
8
+ { "type": "update" },
9
+ { "type": "deletion" }
10
+ ],
11
+ "bypass_actors": [
12
+ { "actor_id": 15368, "actor_type": "Integration", "bypass_mode": "always" }
13
+ ]
14
+ }
@@ -0,0 +1,32 @@
1
+ # Working in this repository
2
+
3
+ Managed by pubrules {version}: `pubrules sync` rewrites this file and `pubrules
4
+ sync --check` fails when it differs, so every pub* repository gives agents
5
+ and people the same rules. Repository-specific guidance lives in the
6
+ README. The standard behind these rules is pubrules' README:
7
+ <https://github.com/Sustenaut/pubrules#readme>.
8
+
9
+ ## Pull requests: ready, or draft
10
+
11
+ - Open a pull request **ready for review** by default. Merging is gated by
12
+ the checks main's ruleset requires (`ci / passed`, and `release /
13
+ release` where pubrel releases), and `ci / passed` fails when any CI job
14
+ does, SonarQube Cloud's quality gate included. Draft adds no safety.
15
+ - Mark it **draft** only when something else must happen first: another
16
+ pull request merged, a release published, a pin moved, a person's
17
+ decision or action. Say in its description what it waits on, and mark it
18
+ ready once that is done.
19
+ - A stacked pull request says so in its title and description.
20
+
21
+ ## Branches: up to date with main
22
+
23
+ - Before each push, `git fetch origin main` and bring `origin/main` into
24
+ the branch, so a pull request arrives as up to date as main's ruleset
25
+ requires and a conflict shows while someone is working on the branch.
26
+ - A branch never pushed: `git rebase origin/main`. A branch already pushed,
27
+ or with a pull request: `git merge origin/main`, which needs no force
28
+ push and leaves reviewers' views where they were.
29
+ - A conflict: resolve it when the resolution is clear; otherwise stop,
30
+ push nothing half-done, and say what conflicts.
31
+ - A folder that only follows main fast-forwards to `origin/main`. Never
32
+ sync on a timer: the rule runs when the branch gets new code.
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env bash
2
+ # Managed by pubrules {version}: `pubrules sync` rewrites this file, and
3
+ # `pubrules sync --check` fails when it differs.
4
+ #
5
+ # Run this repository's pubrules: the version its managed files and
6
+ # tests/requirements.lock pin, whichever pubrules is installed, if any.
7
+ #
8
+ # ./pubrules sync --check
9
+ #
10
+ # uvx fetches that release's wheel once and keeps it in uv's cache; nothing
11
+ # is installed into the repository or the system. pubrules runs in the
12
+ # repository's root, where pubrules.json is, from whichever directory this is
13
+ # called.
14
+ #
15
+ # With a wheel mirror in pubrules.json (mirror.wheels), the wheel is fetched
16
+ # here instead, checked against the sha256 tests/requirements.lock pins, and
17
+ # taken from the mirror when GitHub's release download fails.
18
+ set -euo pipefail
19
+
20
+ if ! command -v uvx >/dev/null 2>&1; then
21
+ echo "pubrules: ./pubrules runs pubrules {version} with uv, which is not installed: curl -LsSf https://astral.sh/uv/install.sh | sh" >&2
22
+ exit 127
23
+ fi
24
+
25
+ cd "$(dirname "$0")"
26
+ {providers}{launch}{with}pubrules "$@"
@@ -0,0 +1,11 @@
1
+ Feature: The repository
2
+ Seeded by `pubrules init`, so the suite is Gherkin from the first commit
3
+ (`pubrules gherkin`): every test here is a scenario, set up by Givens, one
4
+ action (its When) and checks of what came of it, on pubtest's steps
5
+ (its GRAMMAR.md). Replace this one with the repository's
6
+ own behaviour.
7
+
8
+ Scenario: pubrules.json says what kind of repository this is
9
+ When I read the repository's pubrules.json
10
+ Then it is not refused
11
+ And the result includes "kind"
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env bash
2
+ # Managed by pubrules {version}: `pubrules sync` rewrites this file, and
3
+ # `pubrules sync --check` fails when it differs.
4
+ #
5
+ # Install a hash-locked requirements file with pip, and ride out release
6
+ # downloads that fail: pip retries no 504.
7
+ #
8
+ # tests/install-lock .venv/bin/pip # tests/requirements.lock
9
+ # tests/install-lock .venv/bin/pip other.lock
10
+ # tests/install-lock --rewrite tests/requirements.lock > mirrored.lock
11
+ #
12
+ # The install is tried three times, 15 s apart. When pubrules.json names a
13
+ # wheel mirror (mirror.wheels), a fourth try takes each wheel the lock pins
14
+ # by a GitHub release URL from the mirror instead, at the address its
15
+ # sha256 gives: <mirror>/f/<sha256>/<file>.whl. The hashes stay as they
16
+ # are, so pip checks every file: the mirror only has to be there, never
17
+ # trusted. --rewrite writes that version of a lock, for pip-audit. With a
18
+ # PyPI mirror too (mirror.pypi, a simple repository index at
19
+ # <mirror>/simple/), the fourth try takes the other packages from it
20
+ # instead of PyPI.
21
+ set -euo pipefail
22
+
23
+ MIRROR='{mirror}'
24
+ PYPI='{pypi}'
25
+ PAUSE="${INSTALL_LOCK_PAUSE:-15}"
26
+
27
+ rewrite() {
28
+ if [ -z "$MIRROR" ]; then cat "$1"; return; fi
29
+ python3 - "$MIRROR" "$1" <<'PY'
30
+ import re
31
+ import sys
32
+
33
+ mirror, path = sys.argv[1].rstrip("/"), sys.argv[2]
34
+ text = open(path, encoding="utf-8").read()
35
+ # A wheel's URL, then its hash, on the same line or the next (after a \).
36
+ pinned = re.compile(r"https://github\.com/[^/\s]+/[^/\s]+/releases/download/[^/\s]+/([^/\s]+\.whl)"
37
+ r"((?:[ \t]*\\\r?\n)?[ \t]*--hash=sha256:([0-9a-f]{64}))")
38
+ sys.stdout.write(pinned.sub(lambda m: f"{mirror}/f/{m.group(3)}/{m.group(1)}{m.group(2)}", text))
39
+ PY
40
+ }
41
+
42
+ if [ "${1:-}" = --rewrite ]; then
43
+ rewrite "${2:?usage: tests/install-lock --rewrite LOCK}"
44
+ exit 0
45
+ fi
46
+
47
+ pip="${1:?usage: tests/install-lock PIP [LOCK]}"
48
+ lock="${2:-tests/requirements.lock}"
49
+ for attempt in 1 2 3; do
50
+ "$pip" install --quiet --require-hashes -r "$lock" && exit 0
51
+ echo "install-lock: installing $lock failed (attempt $attempt of 3)" >&2
52
+ [ "$attempt" = 3 ] || sleep "$PAUSE"
53
+ done
54
+ [ -n "$MIRROR$PYPI" ] || exit 1
55
+
56
+ index=()
57
+ if [ -n "$PYPI" ]; then
58
+ index=(--index-url "${PYPI%/}/simple/")
59
+ echo "install-lock: trying again with the packages from $PYPI" >&2
60
+ fi
61
+ [ -z "$MIRROR" ] || echo "install-lock: trying again with our release wheels from $MIRROR" >&2
62
+ mirrored="$(mktemp)"
63
+ trap 'rm -f "$mirrored"' EXIT
64
+ rewrite "$lock" > "$mirrored"
65
+ "$pip" install --quiet --require-hashes ${index[@]+"${index[@]}"} -r "$mirrored"
@@ -0,0 +1,4 @@
1
+ [pytest]
2
+ bdd_features_base_dir = features/
3
+ testpaths = .
4
+ addopts = --strict-markers -ra
@@ -0,0 +1,17 @@
1
+ # Managed by pubrules {version}: `pubrules sync` rewrites this file, and
2
+ # `pubrules sync --check` fails when it differs. Add your own requirements to
3
+ # requirements.txt, which includes this one; `pubrules lock` then pins the lot
4
+ # with hashes in requirements.lock.
5
+ pytest==9.0.3
6
+ pytest-bdd==8.1.0
7
+ pytest-xdist==3.8.0
8
+ hypothesis==6.170.5
9
+ # The steps and the pytest plugin every suite loads (pubtest's GRAMMAR.md):
10
+ # requirements.txt pins the release wheel, which the nightly moves, and
11
+ # `pubrules sync --check` fails on one older than the release whose steps
12
+ # pubrules' own files use. Not a requirement here: the wheel's distribution
13
+ # is pubtest or, from its PyPI release on, pubtestrules, and a floor naming
14
+ # the other would resolve PyPI's unrelated pubtest.
15
+ # pubtest floor: 0.2.2
16
+ pubrules @ https://github.com/Sustenaut/pubrules/releases/download/v{version}/pubrules-{version}-py3-none-any.whl
17
+ {provider_requirements}
@@ -0,0 +1,3 @@
1
+ # The functional suite's direct dependencies. Exact pins only; the resolved
2
+ # set with hashes lives in requirements.lock. Regenerate it with `pubrules lock`.
3
+ -r requirements-pubrules.txt
@@ -0,0 +1,14 @@
1
+ """Steps for repository.feature, which `pubrules init` seeded. Its Thens are
2
+ pubtest's; the When is the repository's own, through `ctx.attempt`."""
3
+
4
+ import json
5
+ from pathlib import Path
6
+
7
+ from pytest_bdd import scenarios, when
8
+
9
+ scenarios("repository.feature")
10
+
11
+
12
+ @when("I read the repository's pubrules.json")
13
+ def read_config(ctx):
14
+ ctx.attempt(lambda: json.loads((Path(__file__).parents[2] / "pubrules.json").read_text(encoding="utf-8")))