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/new.py
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
"""`pubrules new`: a new Rust package that meets the standard from its first
|
|
2
|
+
commit.
|
|
3
|
+
|
|
4
|
+
pubrules new --name=pubfoo --tag=PKG-PUBFOO-10-2026 [--owner=OWNER] [--description=TEXT]
|
|
5
|
+
|
|
6
|
+
Run in an empty repository (a README or LICENSE already there is kept). The
|
|
7
|
+
package's repository is OWNER's, by default the owner the `origin` remote
|
|
8
|
+
names; without either it stops. It:
|
|
9
|
+
|
|
10
|
+
1. checks the toolchain first, refusing a `pubrel` or `pub` older than the
|
|
11
|
+
releases the pipeline needs;
|
|
12
|
+
2. writes everything the standard requires: the managed and seeded files,
|
|
13
|
+
a crate whose docs, `_documentation` module, test, test vectors, fuzz
|
|
14
|
+
target and Gherkin scenarios pass every check, `deny.toml`,
|
|
15
|
+
`supply-chain/` with the shared imports, `SECURITY.md`;
|
|
16
|
+
3. sets up the release side: `release.json` with its security checks (the
|
|
17
|
+
quality audit among them) and `corpus/corpus.json`, with
|
|
18
|
+
`corpus/.publet` gitignored. `pubrel add` records each change in a
|
|
19
|
+
file of its own under `corpus/publets/pkg.<name>/unreleased/`, so
|
|
20
|
+
nothing is written there yet;
|
|
21
|
+
4. creates the corpus's workspace and its release key, labelled "<name>
|
|
22
|
+
release key", names it in `release.json`, and writes its public object
|
|
23
|
+
to `corpus/objects`, checked against its identifier;
|
|
24
|
+
5. pins pubrel (ci.release.pubrel) and pubtest (tests/requirements.txt) at
|
|
25
|
+
the releases the release-state file PUBRULES_RELEASES lists, or else at
|
|
26
|
+
their latest GitHub releases (releases.py), which the nightly moves on;
|
|
27
|
+
6. generates TESTING.md, SUPPLY-CHAIN.md and the test vectors, and locks
|
|
28
|
+
the test requirements;
|
|
29
|
+
7. prints the protect block its pubrules.json needs, and that the repository
|
|
30
|
+
is then switched on in the release app.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
from __future__ import annotations
|
|
34
|
+
|
|
35
|
+
import json
|
|
36
|
+
import re
|
|
37
|
+
import shutil
|
|
38
|
+
import subprocess
|
|
39
|
+
import sys
|
|
40
|
+
from pathlib import Path
|
|
41
|
+
|
|
42
|
+
from . import cbor
|
|
43
|
+
from .refs import OWNER_NAME
|
|
44
|
+
|
|
45
|
+
# The releases a new package's pipeline needs on this machine: pubrel 0.6.0
|
|
46
|
+
# records each unreleased change in a file of its own (0.5.3 gave security
|
|
47
|
+
# checks the release they check, which the quality audit reads), and pub
|
|
48
|
+
# 0.2.1 rotates keys.
|
|
49
|
+
MIN_PUBREL = (0, 6, 0)
|
|
50
|
+
MIN_PUB = (0, 2, 1)
|
|
51
|
+
# Where pub comes from: publet-cli, at a tag of this repository.
|
|
52
|
+
PUB_GIT = "https://github.com/Sustenaut/publet"
|
|
53
|
+
|
|
54
|
+
NAME = re.compile(r"[a-z][a-z0-9-]*")
|
|
55
|
+
TAG = re.compile(r"PKG-[A-Z0-9]{6}-(0[1-9]|1[0-2])-\d{4}")
|
|
56
|
+
# An object's identifier, as cbor.cid makes it: its sha-256, in base32.
|
|
57
|
+
CID = re.compile(r"pub:sha2-256:[a-z2-7]{52}")
|
|
58
|
+
KEPT = {"README.md", "LICENSE"}
|
|
59
|
+
RENAMED = {"gitignore": ".gitignore", "fuzz/gitignore": "fuzz/.gitignore"}
|
|
60
|
+
|
|
61
|
+
# The checks a new package's ruleset requires: its CI and its release job.
|
|
62
|
+
CHECKS = ["ci / passed", "release / release"]
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
VERSION = re.compile(r"v?(\d+)\.(\d+)\.(\d+)")
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def version_of(tool: str) -> tuple[int, ...] | None:
|
|
69
|
+
"""The version `tool --version` prints, or `None` when it is missing."""
|
|
70
|
+
if shutil.which(tool) is None:
|
|
71
|
+
return None
|
|
72
|
+
out = subprocess.run([tool, "--version"], capture_output=True, text=True, check=False).stdout
|
|
73
|
+
# Word by word, each matched from its start: one unanchored search for
|
|
74
|
+
# digits backtracks quadratically on a long run of them.
|
|
75
|
+
for word in (out.splitlines()[0] if out else "").split():
|
|
76
|
+
m = VERSION.match(word)
|
|
77
|
+
if m:
|
|
78
|
+
return tuple(int(x) for x in m.groups())
|
|
79
|
+
return None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def check_tools() -> list[str]:
|
|
83
|
+
problems = []
|
|
84
|
+
for tool, least, install in (
|
|
85
|
+
("pubrel", MIN_PUBREL, "cargo install --locked pubrel"),
|
|
86
|
+
("pub", MIN_PUB, f"cargo install --locked --git {PUB_GIT} --tag v{{v}} publet-cli"),
|
|
87
|
+
("cargo", None, "https://rustup.rs"),
|
|
88
|
+
):
|
|
89
|
+
found = version_of(tool)
|
|
90
|
+
need = ".".join(map(str, least)) if least else ""
|
|
91
|
+
if found is None:
|
|
92
|
+
problems.append(f"{tool} is not installed: {install.format(v=need)}")
|
|
93
|
+
elif least and found < least:
|
|
94
|
+
have = ".".join(map(str, found))
|
|
95
|
+
problems.append(f"{tool} {have} is older than {need}, which a new package's "
|
|
96
|
+
f"pipeline needs: {install.format(v=need)}"
|
|
97
|
+
+ (f" --version {need}" if tool == "pubrel" else ""))
|
|
98
|
+
return problems
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def run_in(where: Path, *argv: str) -> str:
|
|
102
|
+
out = subprocess.run(argv, cwd=where, capture_output=True, text=True, check=False)
|
|
103
|
+
if out.returncode != 0:
|
|
104
|
+
sys.exit(f"pubrules: `{' '.join(argv)}` failed in {where}:\n{out.stdout}{out.stderr}")
|
|
105
|
+
return out.stdout
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def export_object(corpus: Path, cid: str) -> None:
|
|
109
|
+
"""Write the object `cid` names from the workspace's store to objects/,
|
|
110
|
+
re-encoded from `pub read --json` and checked against `cid`."""
|
|
111
|
+
shown = json.loads(run_in(corpus, "pub", "read", cid, "--json"))["object"]
|
|
112
|
+
data = cbor.encode(shown)
|
|
113
|
+
if cbor.cid(data) != cid:
|
|
114
|
+
sys.exit(f"pubrules: re-encoding {cid} gave {cbor.cid(data)}; not writing it")
|
|
115
|
+
objects = corpus / "objects"
|
|
116
|
+
objects.mkdir(exist_ok=True)
|
|
117
|
+
(objects / f"{cid.replace(':', '_')}.cbor").write_bytes(data)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def release_json(name: str, tag: str) -> dict:
|
|
121
|
+
return {
|
|
122
|
+
"name": name,
|
|
123
|
+
"package": f"pkg.{name}",
|
|
124
|
+
"tag": tag,
|
|
125
|
+
"corpus": "corpus",
|
|
126
|
+
"manifest": {"kind": "cargo-package", "path": "Cargo.toml"},
|
|
127
|
+
"code": ["src/", "Cargo.toml", "Cargo.lock"],
|
|
128
|
+
"command": {"name": name, "check": f"{name} --version"},
|
|
129
|
+
"install": "cargo install --locked " + name + " --version {version}",
|
|
130
|
+
"semver-checks": True,
|
|
131
|
+
"security": {
|
|
132
|
+
"checks": [
|
|
133
|
+
{"name": "advisories, licences, bans and sources",
|
|
134
|
+
"run": "cargo deny --locked check --hide-inclusion-graph",
|
|
135
|
+
"version": "cargo deny --version"},
|
|
136
|
+
{"name": "supply-chain audits", "run": "cargo vet --locked",
|
|
137
|
+
"version": "cargo vet --version"},
|
|
138
|
+
{"name": "supply-chain report current",
|
|
139
|
+
"run": f".venv/bin/pubrules supply-chain --check {name}",
|
|
140
|
+
"version": ".venv/bin/pubrules --version"},
|
|
141
|
+
{"name": "quality audit current", "run": ".venv/bin/pubrules audit --check",
|
|
142
|
+
"version": ".venv/bin/pubrules --version"},
|
|
143
|
+
],
|
|
144
|
+
},
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def remote_owner(root: Path) -> str | None:
|
|
149
|
+
"""The owner of the GitHub repository `origin` points at, if it does."""
|
|
150
|
+
out = subprocess.run(["git", "-C", str(root), "remote", "get-url", "origin"],
|
|
151
|
+
capture_output=True, text=True, check=False).stdout
|
|
152
|
+
m = re.search(r"github\.com[:/]([A-Za-z0-9-]+)/", out)
|
|
153
|
+
return m.group(1) if m else None
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def run(root: Path, name: str, tag: str, description: str, *, owner: str | None = None,
|
|
157
|
+
key: bool = True, lock: bool = True) -> int:
|
|
158
|
+
from .cli import CONFIG, init_files # noqa: PLC0415 - avoids an import cycle
|
|
159
|
+
|
|
160
|
+
root = root.resolve()
|
|
161
|
+
named = NAME.fullmatch(name)
|
|
162
|
+
if not named:
|
|
163
|
+
sys.exit(f"pubrules: --name must be lower-case letters, digits and hyphens: {name}")
|
|
164
|
+
name = named.group(0)
|
|
165
|
+
if not TAG.fullmatch(tag):
|
|
166
|
+
sys.exit(f"pubrules: --tag must be a Section 9.1 tag, PKG-XXXXXX-MM-YYYY: {tag}")
|
|
167
|
+
owner = owner or remote_owner(root)
|
|
168
|
+
if not owner:
|
|
169
|
+
sys.exit("pubrules: origin is not a GitHub repository; name the package's owner with "
|
|
170
|
+
"--owner=OWNER")
|
|
171
|
+
if not OWNER_NAME.fullmatch(owner):
|
|
172
|
+
sys.exit(f"pubrules: --owner must be a GitHub owner: {owner}")
|
|
173
|
+
for there in (CONFIG, "Cargo.toml", "release.json"):
|
|
174
|
+
if (root / there).exists():
|
|
175
|
+
sys.exit(f"pubrules: {there} already exists; `pubrules new` starts a package, "
|
|
176
|
+
f"`pubrules init` adds pubrules to one")
|
|
177
|
+
problems = check_tools()
|
|
178
|
+
if problems:
|
|
179
|
+
for p in problems:
|
|
180
|
+
print(f"pubrules: {p}", file=sys.stderr)
|
|
181
|
+
return 1
|
|
182
|
+
|
|
183
|
+
# The pubrel its release job calls: the release state's, else pubrel's
|
|
184
|
+
# latest release (releases.py); the nightly moves it from there. Its
|
|
185
|
+
# tests/requirements.txt pins pubtest the same way (cli.pubtest_pin).
|
|
186
|
+
from .releases import version # noqa: PLC0415
|
|
187
|
+
config = {"kind": "rust", "bin": name, "ci": {"release": {"pubrel": version("pubrel")}}}
|
|
188
|
+
extra = {"name": name, "owner": owner, "crate": name.replace("-", "_"), "tag": tag,
|
|
189
|
+
"description": description or f"{name}: a pub* package."}
|
|
190
|
+
init_files(root, config, layers=("common", "rust", "new-rust"), extra=extra,
|
|
191
|
+
keep=KEPT)
|
|
192
|
+
for src, dst in RENAMED.items():
|
|
193
|
+
if (root / src).exists():
|
|
194
|
+
(root / src).rename(root / dst)
|
|
195
|
+
(root / "fuzz" / "regressions" / "greet").mkdir(parents=True, exist_ok=True)
|
|
196
|
+
(root / "fuzz" / "regressions" / "greet" / ".gitkeep").touch()
|
|
197
|
+
|
|
198
|
+
release = release_json(name, tag)
|
|
199
|
+
corpus = root / "corpus"
|
|
200
|
+
if key:
|
|
201
|
+
run_in(corpus, "pub", "init")
|
|
202
|
+
out = run_in(corpus, "pub", "sign", "--generate-key", "--principal=human",
|
|
203
|
+
f"--label={name} release key")
|
|
204
|
+
printed = next(line.split()[1] for line in out.splitlines() if line.startswith("key"))
|
|
205
|
+
cid = CID.fullmatch(printed)
|
|
206
|
+
if not cid:
|
|
207
|
+
sys.exit(f"pubrules: `pub sign` printed {printed!r} for the key, which is not an "
|
|
208
|
+
f"object's identifier; not using it")
|
|
209
|
+
key_cid = cid.group(0)
|
|
210
|
+
run_in(corpus, "pub", "policy", f"--root={key_cid}")
|
|
211
|
+
export_object(corpus, key_cid)
|
|
212
|
+
release["key"] = key_cid
|
|
213
|
+
print(f"key {key_cid} (\"{name} release key\", secret in corpus/.publet, gitignored)")
|
|
214
|
+
(root / "release.json").write_text(json.dumps(release, indent=2) + "\n")
|
|
215
|
+
|
|
216
|
+
run_in(root, sys.executable, "tools/vectors/generate.py")
|
|
217
|
+
run_in(root, "cargo", "generate-lockfile")
|
|
218
|
+
from .doc_coverage import run as coverage # noqa: PLC0415
|
|
219
|
+
from .supply_chain import run as supply_chain # noqa: PLC0415
|
|
220
|
+
coverage(root, [name], check=False)
|
|
221
|
+
supply_chain(root, [name], check=False)
|
|
222
|
+
if lock:
|
|
223
|
+
from .cli import lock as lock_requirements # noqa: PLC0415
|
|
224
|
+
lock_requirements(root)
|
|
225
|
+
|
|
226
|
+
block = json.dumps({"checks": CHECKS})
|
|
227
|
+
print(f"""
|
|
228
|
+
{name} is ready: every file the standard asks for, a release key, and a
|
|
229
|
+
crate that passes every check. Next:
|
|
230
|
+
|
|
231
|
+
make venv && make check # the whole suite, as CI runs it
|
|
232
|
+
cargo vet # fetch the shared audits into supply-chain/
|
|
233
|
+
git add -A && git commit -m "{name}: a new pub* package" && git push
|
|
234
|
+
|
|
235
|
+
Then add a protect block to pubrules.json, which says how {owner}/{name} is
|
|
236
|
+
protected (in an organization, add its release app's id too, as
|
|
237
|
+
"release_app"):
|
|
238
|
+
|
|
239
|
+
"protect": {block}
|
|
240
|
+
|
|
241
|
+
and switch the repository on in the release app.""")
|
|
242
|
+
return 0
|