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