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/cli.py ADDED
@@ -0,0 +1,1069 @@
1
+ """`pubrules`: keep a repository's shared testing files in step.
2
+
3
+ pubrules init --kind=rust|utility|service|content [--bin=NAME]
4
+ pubrules new --name=NAME --tag=PKG-XXXXXX-MM-YYYY [--owner=OWNER] [--description=TEXT]
5
+ pubrules sync [--check]
6
+ pubrules lock
7
+ pubrules supply-chain [--check] CRATE...
8
+ pubrules doc-coverage [--check] [CRATE...]
9
+ pubrules required [--github-output]
10
+ pubrules conform
11
+ pubrules audit --check [PACKAGE VERSION] | --standard
12
+ pubrules audit prepare --package NAME [--version V] [--out FILE] [--quick] [--force]
13
+ pubrules audit draft --package NAME [--report FILE] [--model ID]
14
+ pubrules bump
15
+ pubrules pins --pubrel V [--no-lock]
16
+ pubrules actions
17
+ pubrules crates [--report FILE]
18
+ pubrules record TEXT
19
+ pubrules nightly --pubrel V --body FILE
20
+ pubrules protect [--check] [--repos FILE | --require CHECK...] [REPO...]
21
+
22
+ The deploy walk and the k8s checks are pubdeploy's: ./pubdeploy, which
23
+ `pubrules sync` writes in a repository with a deploy block, runs them. What a
24
+ control plane runs across many repositories (the board, state files,
25
+ variables, freshness), and a repository's hosting (the Terraform modules,
26
+ terraform.yml, deploy-static, docker-build, dns check and site check), are
27
+ not pubrules': pubrules' README says where each went.
28
+
29
+ Deprecated, each now ./pubsec with the same arguments, and removed in the
30
+ next minor: secrets run, app-secrets, github-app create,
31
+ service-account-key create, signing-key backup. Each prints the line that
32
+ says so and exits 2.
33
+
34
+ Files are either *managed* -- owned by pubrules, rewritten by `sync`, and
35
+ compared by `sync --check`, so they cannot drift -- or *seeded*: written once
36
+ by `init` and the repository's own from then on. Extensions go in seeded
37
+ files (the Makefile includes `pubrules.mk`, or a Python package's `pubrules-python.mk`; requirements.txt includes
38
+ requirements-pubrules.txt), so nothing managed is ever edited by hand. One
39
+ file is neither: .gitignore is the repository's own, but `init` and `sync`
40
+ add `.env` and `.venv` to it when they're missing (ignores.py), and `sync --check` fails
41
+ until they have.
42
+ """
43
+
44
+ from __future__ import annotations
45
+
46
+ import argparse
47
+ import hashlib
48
+ import json
49
+ import os
50
+ import re
51
+ import subprocess
52
+ import sys
53
+ import tempfile
54
+ import urllib.request
55
+ from importlib import resources
56
+ from pathlib import Path
57
+
58
+ from . import __version__
59
+
60
+ KINDS = ("rust", "utility", "service", "content")
61
+
62
+
63
+ def bin_var(name: str) -> str:
64
+ """The variable naming the directory that holds `name`: pub -> PUB_BIN_DIR,
65
+ as pubtest's binary() reads it."""
66
+ return re.sub(r"[^A-Za-z0-9]", "_", name).upper() + "_BIN_DIR"
67
+
68
+ # The commands that hold a secret, pubsec's now: each prints where it went.
69
+ MOVED = ("app-secrets", "github-app", "service-account-key", "signing-key")
70
+ # Kinds pubrules no longer has, and what each became. Not accepted: a
71
+ # repository says which it is in one way only.
72
+ RENAMED_KINDS = {"python": "utility", "python-utility": "utility"}
73
+ MANAGED = {
74
+ # The pinned pubrules, and a way to run exactly it.
75
+ # The rules agents and people follow in every repository (AGENTS.md).
76
+ # The one install of a hash-locked file, retried and mirrored.
77
+ "common": ["tests/requirements-pubrules.txt", "pubrules", "AGENTS.md", "tests/install-lock"],
78
+ "rust": ["rust-toolchain.toml", "pubrules.mk"],
79
+ "utility": [],
80
+ # A private repository that deploys: the one secrets wrapper every
81
+ # service runs its secret-needing commands through.
82
+ "service": ["with-secrets", "pubsec"],
83
+ # A private repository of authored content (documents, data) that pubrules
84
+ # neither releases nor deploys: its own tooling builds and checks it, and
85
+ # versions it, if anything does. The common files only.
86
+ "content": [],
87
+ }
88
+ # Managed files that are programs, written executable.
89
+ EXECUTABLE = {"with-secrets", "pubrules", "pubsec", "pubdeploy", "tests/install-lock"}
90
+ WITH_SECRETS = "with-secrets"
91
+ # The pinned pubsec, which ./with-secrets runs and whose types the deploy walk loads.
92
+ PUBSEC = "pubsec"
93
+ # The pinned pubdeploy, the deploy walk, in a repository with a deploy block.
94
+ PUBDEPLOY = "pubdeploy"
95
+ # A Python package's shared make targets (templates/python/): managed, and
96
+ # included by its seeded Makefile.
97
+ PYTHON_MK = "pubrules-python.mk"
98
+ CONFIG = "pubrules.json"
99
+ LOCK = Path("tests/requirements.lock")
100
+ REQUIREMENTS = Path("tests/requirements.txt")
101
+
102
+
103
+ def templates(kind: str, layers: tuple[str, ...] | None = None) -> dict[str, str]:
104
+ """Every template for `kind`, by repository path; later layers win."""
105
+ out: dict[str, str] = {}
106
+ for layer in layers or ("common", kind):
107
+ root = resources.files("pubrules") / "templates" / layer
108
+ if not root.is_dir(): # a kind with no templates of its own, such as utility
109
+ continue
110
+ stack = [(root, "")]
111
+ while stack:
112
+ node, prefix = stack.pop()
113
+ for child in node.iterdir():
114
+ # What an installer compiles beside a seeded .py template (pip
115
+ # writes __pycache__ into site-packages) is no template.
116
+ if child.name == "__pycache__" or child.name.endswith((".pyc", ".pyo")):
117
+ continue
118
+ path = f"{prefix}{child.name}"
119
+ if child.is_dir():
120
+ stack.append((child, path + "/"))
121
+ else:
122
+ out[path] = child.read_text(encoding="utf-8")
123
+ return out
124
+
125
+
126
+ def render(text: str, values: dict[str, str]) -> str:
127
+ for key, value in values.items():
128
+ text = text.replace("{" + key + "}", value)
129
+ return text
130
+
131
+
132
+ def managed(kind: str) -> list[str]:
133
+ return MANAGED["common"] + MANAGED[kind]
134
+
135
+
136
+ def is_python(config: dict, root: Path) -> bool:
137
+ """A Python package: a utility whose CI is Python's (its ci block says
138
+ so, or it has no package.json without a pyproject.toml beside it)."""
139
+ if config.get("kind") != "utility":
140
+ return False
141
+ from .ci import is_node # noqa: PLC0415
142
+ given = (config.get("ci") or {}).get("language") if isinstance(config.get("ci"), dict) else None
143
+ return given == "python" if given else not is_node(root)
144
+
145
+
146
+ # The Makefile's line that takes pubrules-python.mk in.
147
+ INCLUDES_PYTHON_MK = re.compile(r"^[ \t]*-?include[ \t]+(?:\$\(CURDIR\)/)?pubrules-python\.mk[ \t]*$", re.M)
148
+
149
+
150
+ def python_problems(root: Path) -> list[str]:
151
+ """What keeps a Python package's suite from following the shared rules:
152
+ a Makefile that does not include pubrules-python.mk, and coverage.py
153
+ settings that would lose what xdist's workers and the programs the suite
154
+ starts run ([tool.coverage.run] patch = ["subprocess"], parallel = true)."""
155
+ out = []
156
+ makefile = root / "Makefile"
157
+ if not makefile.is_file():
158
+ out.append(f"there is no Makefile; `pubrules sync` seeds one that includes {PYTHON_MK}")
159
+ elif not INCLUDES_PYTHON_MK.search(makefile.read_text(encoding="utf-8")):
160
+ out.append(f"the Makefile does not include {PYTHON_MK}: put `include {PYTHON_MK}` at its top, "
161
+ f"and drop the targets it defines (venv, functional, lock, sync-check, wheel, clean, help)")
162
+ pyproject = root / "pyproject.toml"
163
+ if pyproject.is_file():
164
+ import tomllib # noqa: PLC0415
165
+ try:
166
+ run = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {}).get(
167
+ "coverage", {}).get("run", {})
168
+ except tomllib.TOMLDecodeError as e:
169
+ return [*out, f"pyproject.toml is not TOML ({e})"]
170
+ patch = run.get("patch", [])
171
+ if not isinstance(patch, list) or "subprocess" not in patch or run.get("parallel") is not True:
172
+ out.append('pyproject.toml\'s [tool.coverage.run] must set patch = ["subprocess"] and '
173
+ "parallel = true, so the coverage of xdist's workers and of the programs the "
174
+ "suite starts is combined")
175
+ return out
176
+
177
+
178
+ def read_config(root: Path) -> dict[str, str]:
179
+ path = root / CONFIG
180
+ if not path.exists():
181
+ sys.exit(f"pubrules: no {CONFIG} here; run `pubrules init --kind={'|'.join(KINDS)}` first")
182
+ config = json.loads(path.read_text(encoding="utf-8"))
183
+ if config.get("kind") in RENAMED_KINDS:
184
+ sys.exit(f"pubrules: the kind \"{config['kind']}\" is now \"{RENAMED_KINDS[config['kind']]}\" "
185
+ f"(pubrules 0.10.0); change it in {CONFIG}")
186
+ if config.get("kind") not in KINDS:
187
+ sys.exit(f"pubrules: {CONFIG} must give a kind: one of {', '.join(KINDS)}")
188
+ return config
189
+
190
+
191
+ # The launcher's wheels, each fetched once into the user's cache and checked
192
+ # against its sha256 on every run before uv is given the file: uv does not
193
+ # check a --with URL's #sha256. With a wheel mirror, a wheel GitHub fails to
194
+ # give is taken from the mirror, by its sha256; the check is the same.
195
+ FETCH = """# A wheel, fetched once into the user's cache, checked against its sha256 on every run.
196
+ fetch() {
197
+ local dir="${XDG_CACHE_HOME:-$HOME/.cache}/pubrules/$3/$2" sum
198
+ fetched="$dir/${1##*/}"
199
+ if [ ! -f "$fetched" ]; then
200
+ mkdir -p "$dir"
201
+ curl -fsSL -o "$fetched.part" "$1"{fallback} \\
202
+ || { rm -f "$fetched.part"; echo "pubrules: could not fetch $1" >&2; exit 1; }
203
+ mv "$fetched.part" "$fetched"
204
+ fi
205
+ if command -v sha256sum >/dev/null 2>&1; then sum=$(sha256sum "$fetched"); else sum=$(shasum -a 256 "$fetched"); fi
206
+ if [ "${sum%% *}" != "$2" ]; then
207
+ rm -f "$fetched"
208
+ echo "pubrules: $1 is not the wheel $4 pins (sha256 $2)" >&2
209
+ exit 1
210
+ fi
211
+ }
212
+ """
213
+ FALLBACK = ' \\\n || curl -fsSL -o "$fetched.part" "{mirror}/f/$2/${{1##*/}}"'
214
+ PROVIDER = """# The packages pubrules.json's deploy.providers names, each wheel checked against its sha256.
215
+ with=()
216
+ provider() {
217
+ fetch "$1" "$2" providers deploy.providers
218
+ with+=(--with "$fetched")
219
+ }
220
+ """
221
+ # With a wheel mirror, pubrules' own wheel too, when tests/requirements.lock
222
+ # pins this version of it by its sha256.
223
+ OWN = """# pubrules' own wheel, by the sha256 tests/requirements.lock pins, from the mirror when GitHub fails.
224
+ from="https://github.com/Sustenaut/pubrules/releases/download/v{version}/pubrules-{version}-py3-none-any.whl"
225
+ pin=$(sed -n "\\#^pubrules @ $from#,/--hash=sha256:/s/.*--hash=sha256:\\([0-9a-f]\\{{64\\}}\\).*/\\1/p" tests/requirements.lock 2>/dev/null | head -n 1)
226
+ if [ -n "$pin" ]; then
227
+ fetch "$from" "$pin" wheels tests/requirements.lock
228
+ from="$fetched"
229
+ fi
230
+ """
231
+
232
+
233
+ def providers(config: dict) -> list[dict[str, str]]:
234
+ deploy = config.get("deploy")
235
+ given = deploy.get("providers") if isinstance(deploy, dict) else None
236
+ return [p for p in given or [] if isinstance(p, dict) and isinstance(p.get("wheel"), str)
237
+ and isinstance(p.get("sha256"), str)]
238
+
239
+
240
+ def provider_requirements(wheels: list[dict[str, str]]) -> str:
241
+ """deploy.providers' wheels, as requirements: `pubrules sync --check` runs in
242
+ the tests' environment, and reads the need types these packages offer.
243
+ `pubrules lock` pins each with its hash, which is the provider's sha256."""
244
+ named = [p for p in wheels if isinstance(p.get("distribution"), str)]
245
+ if not named:
246
+ return ""
247
+ return ("# deploy.providers' packages, whose need types `pubrules sync --check` reads:\n"
248
+ + "".join(f"{p['distribution']} @ {p['wheel']}\n" for p in named))
249
+
250
+
251
+ MIRRORS = {
252
+ # tests/install-lock and ./pubrules: <base>/f/<sha256>/<file>.whl.
253
+ "wheels": "the base its files are at as <base>/f/<sha256>/<file>.whl",
254
+ # The Terraform workflows' last init: a provider network mirror.
255
+ "terraform": "a Terraform provider network mirror",
256
+ # tests/install-lock's last try: a simple repository index at <base>/simple/.
257
+ "pypi": "a simple repository index (PEP 503) at <base>/simple/",
258
+ }
259
+
260
+
261
+ def mirrors(config: dict) -> dict[str, str]:
262
+ """pubrules.json's mirror block: where installs find what GitHub's release
263
+ downloads (and the registries) fail to give, each checked against its
264
+ pinned hash, so a mirror only has to be there, never trusted."""
265
+ mirror = config.get("mirror")
266
+ if mirror is None:
267
+ return {}
268
+ known = ", ".join(f"{k}: {v}" for k, v in MIRRORS.items())
269
+ if not isinstance(mirror, dict) or set(mirror) - set(MIRRORS) or not all(
270
+ isinstance(url, str) and re.fullmatch(r"https://[A-Za-z0-9.-]+(/[A-Za-z0-9._~-]+)*", url)
271
+ for url in mirror.values()):
272
+ sys.exit(f'pubrules: {CONFIG}\'s mirror is {{"wheels": "https://host/path", "terraform": "https://host/path", "pypi": "https://host/path"}}, '
273
+ f"each an https base with no / at its end ({known})")
274
+ return mirror
275
+
276
+
277
+ def wheel_mirror(config: dict) -> str:
278
+ """mirror.wheels, or empty for none."""
279
+ return mirrors(config).get("wheels", "")
280
+
281
+
282
+ def values(config: dict[str, str], root: Path | None = None, launchers: frozenset[str] = frozenset()) -> dict[str, str]:
283
+ """What the templates are filled with; the pubsec and pubdeploy launchers'
284
+ only for those of `launchers` written, each the repository's own pin
285
+ (providers.pinned)."""
286
+ import shlex # noqa: PLC0415
287
+ wheels = providers(config)
288
+ mirror = wheel_mirror(config)
289
+ fetch = FETCH.replace("{fallback}", FALLBACK.format(mirror=mirror) if mirror else "")
290
+ launched = PROVIDER + "".join(f"provider {shlex.quote(p['wheel'])} {shlex.quote(p['sha256'])}\n"
291
+ for p in wheels) + "\n" if wheels else ""
292
+ own = OWN.format(version=__version__) if mirror else ""
293
+ if own:
294
+ launch = 'exec uvx --from "$from" '
295
+ else:
296
+ launch = f'exec uvx --from "https://github.com/Sustenaut/pubrules/releases/download/v{__version__}/pubrules-{__version__}-py3-none-any.whl" '
297
+ out = {"version": __version__, "bin_var": bin_var(config.get("bin", "app")),
298
+ "providers": (fetch + "\n" if wheels or own else "") + launched + own,
299
+ "launch": launch, "with": '"${with[@]}" ' if wheels else "", "mirror": mirror,
300
+ "pypi": mirrors(config).get("pypi", ""),
301
+ "provider_requirements": provider_requirements(wheels)}
302
+ from .providers import PUBDEPLOY as DEPLOYS, PUBSEC as SECRETS, pinned # noqa: PLC0415
303
+ if SECRETS in launchers:
304
+ wheel = pinned(root, config, SECRETS)
305
+ out["pubsec"] = (fetch + f"\nfetch {shlex.quote(wheel['wheel'])} {shlex.quote(wheel['sha256'])} providers "
306
+ f"deploy.providers\n")
307
+ if DEPLOYS in launchers:
308
+ walker = pinned(root, config, DEPLOYS)
309
+ others = [p for p in wheels if p.get("distribution") != DEPLOYS]
310
+ out["pubdeploy"] = (fetch + "\n" + (PROVIDER + "".join(
311
+ f"provider {shlex.quote(p['wheel'])} {shlex.quote(p['sha256'])}\n" for p in others) + "\n"
312
+ if others else "with=()\n")
313
+ + f"fetch {shlex.quote(walker['wheel'])} {shlex.quote(walker['sha256'])} providers deploy.providers\n")
314
+ return out
315
+
316
+
317
+ def init_files(root: Path, config: dict[str, str], layers: tuple[str, ...] | None = None,
318
+ extra: dict[str, str] | None = None, keep: set[str] | None = None) -> None:
319
+ """Write pubrules.json and the templates of `layers`: managed files always,
320
+ seeded ones unless already present."""
321
+ kind = config["kind"]
322
+ (root / CONFIG).write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
323
+ owned = set(managed(kind)) | ({PYTHON_MK} if is_python(config, root) else set())
324
+ files = templates(kind, layers)
325
+ fill = {**values(config, root, frozenset(files) & {PUBSEC, PUBDEPLOY}), **(extra or {})}
326
+ for path, text in sorted(files.items()):
327
+ target = root / path
328
+ if target.exists() and path not in owned:
329
+ print(f"kept {path} (already present)")
330
+ continue
331
+ target.parent.mkdir(parents=True, exist_ok=True)
332
+ target.write_text(render(text, fill), encoding="utf-8")
333
+ if (path.endswith(".py") and text.startswith("#!")) or path in EXECUTABLE:
334
+ target.chmod(0o755)
335
+ print(f"{'managed' if path in owned else 'seeded '} {path}")
336
+ for line in pubtest_pin(root, check=False)[0]:
337
+ print(line)
338
+ from .security import DEPENDABOT_PATH, dependabot # noqa: PLC0415
339
+ from .ci import generated as workflows # noqa: PLC0415
340
+ written = workflows(config, root)
341
+ if (generated := dependabot(config)) is not None:
342
+ written.append((DEPENDABOT_PATH, generated))
343
+ from .ci import review_licenses # noqa: PLC0415
344
+ if (licenses := review_licenses(config, root, written)) is not None:
345
+ written.append(licenses)
346
+ for path, text in written:
347
+ target = root / path
348
+ target.parent.mkdir(parents=True, exist_ok=True)
349
+ target.write_text(text, encoding="utf-8")
350
+ print(f"managed {path}")
351
+ from .ignores import GITIGNORE, heal # noqa: PLC0415
352
+ if added := heal(root):
353
+ print(f"ignored {', '.join(added)} (in {GITIGNORE})")
354
+
355
+
356
+ def init(root: Path, kind: str, binary: str | None, project: str | None = None) -> int:
357
+ config: dict = {"kind": kind}
358
+ if binary:
359
+ config["bin"] = binary
360
+ if kind == "service" and not project:
361
+ sys.exit("pubrules: a service names the Bitwarden Secrets Manager project its secrets are in: --project=NAME")
362
+ # The CI is generated from the ci block (ci.py): a utility's is Node's
363
+ # for a package.json without a pyproject.toml, Python's otherwise.
364
+ config["ci"] = {}
365
+ layers = ("common", kind, "python") if is_python(config, root) else None
366
+ init_files(root, config, layers, extra={"project": project or ""})
367
+ print("next: add your requirements to tests/requirements.txt, then `pubrules lock`")
368
+ return 0
369
+
370
+
371
+ def sync(root: Path, check: bool) -> int:
372
+ config = read_config(root)
373
+ from .hosting import settings # noqa: PLC0415
374
+ settings(config)
375
+ if "cache" in config:
376
+ from .cache import CacheError, check as check_cache # noqa: PLC0415
377
+ try:
378
+ check_cache(config["cache"])
379
+ except CacheError as e:
380
+ sys.exit(f"pubrules: {e}")
381
+ if "site" in config:
382
+ from .ci import site # noqa: PLC0415
383
+ site(config, root)
384
+ from .nightly import named_crates # noqa: PLC0415
385
+ named_crates(config)
386
+ if "protect" in config:
387
+ from .protect import entry # noqa: PLC0415
388
+ try:
389
+ entry("", config, CONFIG)
390
+ except ValueError as e:
391
+ sys.exit(f"pubrules: {e}")
392
+ if "signing_keys" in config:
393
+ from .secrets_config import signing_key_problems as key_problems # noqa: PLC0415
394
+ if bad := key_problems(config["signing_keys"]):
395
+ sys.exit(f"pubrules: {CONFIG}: {'; '.join(bad)}")
396
+ if "github_app" in config or "secrets" in config:
397
+ from .secrets_config import config_problems # noqa: PLC0415
398
+ if bad := config_problems(config):
399
+ sys.exit(f"pubrules: {CONFIG}: {'; '.join(bad)}")
400
+ if "variables" in config:
401
+ from .variables import block_problems # noqa: PLC0415
402
+ if bad := block_problems(config["variables"]):
403
+ sys.exit(f"pubrules: {CONFIG}'s variables block: {'; '.join(bad)}")
404
+ # pubrules 0.43.2's go-live block is the service-needs block, with the same keys: sync
405
+ # renames the key in pubrules.json, as the rest of it reads, and --check says it is stale.
406
+ from .service_needs import OLD_BLOCK, renamed_block # noqa: PLC0415
407
+ renamed = OLD_BLOCK in config
408
+ if renamed and check:
409
+ print(f"pubrules: {CONFIG}'s {OLD_BLOCK} block is the service-needs block now; run `pubrules sync`, "
410
+ f"which renames it", file=sys.stderr)
411
+ elif renamed:
412
+ (root / CONFIG).write_text(renamed_block((root / CONFIG).read_text(encoding="utf-8")), encoding="utf-8")
413
+ print(f"updated {CONFIG} ({OLD_BLOCK} is service-needs now)")
414
+ config = read_config(root)
415
+ if "service-needs" in config:
416
+ from .service_needs import block_problems as service_needs_problems # noqa: PLC0415
417
+ if bad := service_needs_problems(config["service-needs"]):
418
+ sys.exit(f"pubrules: {CONFIG}'s service-needs block: {'; '.join(bad)}")
419
+ deploy_failed = False
420
+ if "deploy" in config:
421
+ # pubsec and pubdeploy, whose types and walk a deploy block needs, in
422
+ # deploy.providers, each the repository's own pin.
423
+ from .providers import ensure # noqa: PLC0415
424
+ lines, deploy_failed = ensure(root, config, check)
425
+ for line in lines:
426
+ print(line, file=sys.stderr if check else sys.stdout)
427
+ if lines and not check:
428
+ config = read_config(root)
429
+ # What the installed packages check and seed (pubdeploy's: the deploy
430
+ # block's offline check, and the scheduled walk's caller).
431
+ from .hooks import sync as sync_hooks # noqa: PLC0415
432
+ lines, hooks_failed = sync_hooks(root, config, check)
433
+ deploy_failed = deploy_failed or hooks_failed
434
+ for line in lines:
435
+ print(line, file=sys.stderr if line.startswith(("pubrules:", "pubdeploy:")) else sys.stdout)
436
+ lines, unpinned = pubtest_pin(root, check)
437
+ deploy_failed = deploy_failed or unpinned
438
+ for line in lines:
439
+ print(line, file=sys.stderr if check else sys.stdout)
440
+ kind = config["kind"]
441
+ every = templates(kind)
442
+ stale = []
443
+ from .security import DEPENDABOT_PATH, dependabot # noqa: PLC0415
444
+ from .ci import INTEGRATIONS, declared, generated as workflows, leftovers, review_licenses # noqa: PLC0415
445
+ owned = managed(kind)
446
+ # Any repository with a with-secrets.json runs it through the managed
447
+ # with-secrets, and that, or a deploy block, through ./pubsec.
448
+ if WITH_SECRETS not in owned and (root / f"{WITH_SECRETS}.json").is_file():
449
+ owned = [*owned, WITH_SECRETS]
450
+ every = {**every, WITH_SECRETS: templates("service", ("service",))[WITH_SECRETS]}
451
+ if PUBSEC not in owned and (WITH_SECRETS in owned or "deploy" in config):
452
+ owned = [*owned, PUBSEC]
453
+ every = {**every, PUBSEC: templates("service", ("service",))[PUBSEC]}
454
+ if "deploy" in config:
455
+ owned = [*owned, PUBDEPLOY]
456
+ every = {**every, PUBDEPLOY: templates("deploy", ("deploy",))[PUBDEPLOY]}
457
+ python = is_python(config, root)
458
+ if python:
459
+ python_templates = templates("utility", ("python",))
460
+ owned = [*owned, PYTHON_MK]
461
+ every = {**every, PYTHON_MK: python_templates[PYTHON_MK]}
462
+ if not check and not (root / "Makefile").exists():
463
+ (root / "Makefile").write_text(python_templates["Makefile"], encoding="utf-8")
464
+ print("seeded Makefile")
465
+ filled = values(config, root, frozenset(owned) & {PUBSEC, PUBDEPLOY})
466
+ wanted = [(path, render(every[path], filled)) for path in owned]
467
+ wanted += workflows(config, root)
468
+ from .service_needs import CALLER, OLD_CALLER, caller, is_caller # noqa: PLC0415
469
+ from .refs import owner, ref, release_commit # noqa: PLC0415
470
+ if (service_needs := caller(config, owner(config), ref(__version__, release_commit()))) is not None:
471
+ wanted.append((CALLER, service_needs))
472
+ if (generated := dependabot(config)) is not None:
473
+ wanted.append((DEPENDABOT_PATH, generated))
474
+ # The go-live workflow pubrules 0.43.2 wrote is the service-needs workflow now: sync takes it
475
+ # away below, and what names it (integrations.json, the review's exceptions) forgets it now.
476
+ old = root / OLD_CALLER
477
+ gone = frozenset({OLD_CALLER} if old.is_file() and is_caller(old.read_text(encoding="utf-8")) else ())
478
+ if (integrations := declared(root, wanted, gone)) is not None:
479
+ wanted.append(integrations)
480
+ if (licenses := review_licenses(config, root, wanted, gone)) is not None:
481
+ wanted.append(licenses)
482
+ replaced = leftovers(config, root)
483
+ if service_needs is None and (root / CALLER).is_file() and is_caller((root / CALLER).read_text(encoding="utf-8")):
484
+ replaced.append(CALLER)
485
+ if gone:
486
+ if check:
487
+ print(f"pubrules: {OLD_CALLER} is the service-needs workflow now; run `pubrules sync`, which removes it",
488
+ file=sys.stderr)
489
+ stale.append(OLD_CALLER)
490
+ else:
491
+ old.unlink()
492
+ print(f"removed {OLD_CALLER} (now {CALLER})")
493
+ from .ignores import GITIGNORE, REQUIRED, heal, missing # noqa: PLC0415
494
+ unignored = missing(root) if check else heal(root)
495
+ if unignored and not check:
496
+ print(f"updated {GITIGNORE} (now ignores {', '.join(unignored)})")
497
+ for path, want in wanted:
498
+ target = root / path
499
+ have = target.read_text(encoding="utf-8") if target.exists() else None
500
+ if have == want:
501
+ continue
502
+ stale.append(path)
503
+ if not check:
504
+ target.parent.mkdir(parents=True, exist_ok=True)
505
+ target.write_text(want, encoding="utf-8")
506
+ if path in EXECUTABLE:
507
+ target.chmod(0o755)
508
+ print(f"updated {path}")
509
+ lock = root / LOCK
510
+ wheel = f"/download/v{__version__}/pubrules-{__version__}-py3-none-any.whl"
511
+ lock_stale = lock.exists() and wheel not in lock.read_text(encoding="utf-8")
512
+ for path in replaced:
513
+ why = ("pubrules.json has no deploy block, so it has no needs to check" if path == CALLER
514
+ else "pubrules.json's ci block writes the workflows now")
515
+ print(f"pubrules: delete {path}: {why}", file=sys.stderr)
516
+ if check:
517
+ for path in stale:
518
+ held = root / path
519
+ if path == WITH_SECRETS and held.is_file() and "Managed by pubrules" not in held.read_text(
520
+ encoding="utf-8", errors="replace"):
521
+ print(f"pubrules: {path} differs from pubrules {__version__}'s: it is an older script, which does not "
522
+ f"say which Bitwarden project it read (PUBRULES_SECRETS_PROJECT), so pubdeploy finds every bitwarden.* need "
523
+ f"unknown through it; run `pubrules sync`, which writes the managed one", file=sys.stderr)
524
+ continue
525
+ if path == OLD_CALLER:
526
+ continue # said above
527
+ if path == INTEGRATIONS:
528
+ print(f"pubrules: {path} doesn't declare what the files pubrules writes use (the "
529
+ f"sonar job's token, or with-secrets.json for Bitwarden); run `pubrules sync`",
530
+ file=sys.stderr)
531
+ continue
532
+ print(f"pubrules: {path} differs from pubrules {__version__}'s; run `pubrules sync`",
533
+ file=sys.stderr)
534
+ for name in unignored:
535
+ print(f"pubrules: {GITIGNORE} doesn't ignore {name}. {REQUIRED[name]} "
536
+ f"Run `pubrules sync`, which adds it.", file=sys.stderr)
537
+ if lock_stale:
538
+ print(f"pubrules: {LOCK} does not pin pubrules {__version__}; run `pubrules lock`",
539
+ file=sys.stderr)
540
+ from .refs import release_commit, stale_pins # noqa: PLC0415
541
+ actions, unversioned = stale_pins(root, __version__, release_commit())
542
+ for problem in actions:
543
+ print(f"pubrules: {problem}", file=sys.stderr)
544
+ for use in unversioned:
545
+ print(f"pubrules: {use} names no pubrules version, so `pubrules bump` leaves it as it is",
546
+ file=sys.stderr)
547
+ unreported = unreported_checks(root, config)
548
+ python_bad = python_checks(root) if python else []
549
+ from .gherkin import run as gherkin # noqa: PLC0415
550
+ gherkin_lines, gherkin_bad = gherkin(root, config)
551
+ for problem in gherkin_bad:
552
+ print(f"pubrules: {problem}", file=sys.stderr)
553
+ if (stale or lock_stale or replaced or actions or unignored or deploy_failed or unreported or renamed
554
+ or python_bad or gherkin_bad):
555
+ return 1
556
+ print(f"in step with pubrules {__version__}")
557
+ for line in gherkin_lines:
558
+ if line.startswith("open exception"):
559
+ print(line)
560
+ if kind == "rust":
561
+ if not (root / "Cargo.toml").exists():
562
+ print("no Cargo.toml yet: the standard's checks wait for a crate")
563
+ return 0
564
+ return conform(root)
565
+ return 0
566
+ unreported = unreported_checks(root, config)
567
+ python_bad = python_checks(root) if python else []
568
+ if not stale and not unignored and not unreported and not python_bad:
569
+ print(f"already in step with pubrules {__version__}")
570
+ if lock_stale:
571
+ print(f"now run `pubrules lock`: {LOCK} pins another pubrules")
572
+ return 1 if unreported or python_bad else 0
573
+
574
+
575
+ def python_checks(root: Path) -> list[str]:
576
+ """python_problems, each printed."""
577
+ problems = python_problems(root)
578
+ for problem in problems:
579
+ print(f"pubrules: {problem}", file=sys.stderr)
580
+ return problems
581
+
582
+
583
+ def unreported_checks(root: Path, config: dict) -> list[str]:
584
+ """The checks pubrules.json's protect block requires that none of the
585
+ repository's workflows, as sync leaves them, reports where the ruleset
586
+ waits for them; each is printed."""
587
+ if "protect" not in config:
588
+ return []
589
+ from .protect import entry, unreported # noqa: PLC0415
590
+ protected = entry("", config, CONFIG)
591
+ missing = unreported(root, protected["checks"], protected["queue"])
592
+ for problem in missing:
593
+ print(f"pubrules: {CONFIG}'s protect.checks: {problem}", file=sys.stderr)
594
+ return missing
595
+
596
+
597
+ def sha256_of(url: str) -> str:
598
+ digest = hashlib.sha256()
599
+ with urllib.request.urlopen(url) as response: # noqa: S310 - a URL the requirements name
600
+ for chunk in iter(lambda: response.read(1 << 16), b""):
601
+ digest.update(chunk)
602
+ return digest.hexdigest()
603
+
604
+
605
+ INDEX_JSON = "https://pypi.org/pypi"
606
+
607
+
608
+ def published_hashes(name: str, version: str) -> list[str]:
609
+ """The sha256 of every file the index publishes for name==version.
610
+
611
+ A package with compiled wheels has one per platform; pinning only the
612
+ one this machine resolved would make the lock uninstallable everywhere
613
+ else. PUBRULES_INDEX_JSON points at another index's JSON API.
614
+ """
615
+ base = os.environ.get("PUBRULES_INDEX_JSON", INDEX_JSON).rstrip("/")
616
+ with urllib.request.urlopen(f"{base}/{name}/{version}/json") as response: # noqa: S310
617
+ files = json.load(response)["urls"]
618
+ return sorted({f["digests"]["sha256"] for f in files})
619
+
620
+
621
+ def pip() -> list[str]:
622
+ """How to run pip: the installed one, else the wheel Python's ensurepip
623
+ carries (Debian keeps it in /usr/share/python-wheels), which runs as it
624
+ is. `uvx` and `./pubrules` environments have no pip."""
625
+ import importlib.util
626
+ if importlib.util.find_spec("pip") is not None:
627
+ return [sys.executable, "-m", "pip"]
628
+ import ensurepip
629
+ wheels = [wheel for where in (Path(ensurepip.__file__).parent / "_bundled", Path("/usr/share/python-wheels"))
630
+ for wheel in sorted(where.glob("pip-*.whl"))]
631
+ if not wheels:
632
+ raise SystemExit("pubrules lock needs pip, and this Python has neither pip nor ensurepip's wheel of it")
633
+ return [sys.executable, f"{wheels[0]}/pip"]
634
+
635
+
636
+ def lock(root: Path) -> int:
637
+ """Resolve requirements.txt and pin every package, with its sha256s.
638
+
639
+ pip's own resolver, through `--dry-run --report`, so locking needs
640
+ nothing beyond pip; the index's JSON API then supplies the hash of every
641
+ file of each pinned version, so the lock installs on any platform.
642
+ """
643
+ with tempfile.TemporaryDirectory() as tmp:
644
+ report = Path(tmp) / "report.json"
645
+ # pip takes pubtest's wheel only when its URL comes before the floor
646
+ # requirements-pubrules.txt names, so the pin is read first.
647
+ given = root / REQUIREMENTS
648
+ first = [m.group(0) for m in PUBTEST_PIN.finditer(given.read_text(encoding="utf-8"))] \
649
+ if given.is_file() else []
650
+ if first:
651
+ ordered = Path(tmp) / "requirements.txt"
652
+ ordered.write_text("\n".join(first) + f"\n-r {given.resolve()}\n", encoding="utf-8")
653
+ given = ordered
654
+ subprocess.run(
655
+ [*pip(), "install", "--dry-run", "--ignore-installed",
656
+ "--quiet", "--report", str(report), "-r", str(given)],
657
+ check=True, stdout=subprocess.DEVNULL,
658
+ )
659
+ items = json.loads(report.read_text(encoding="utf-8"))["install"]
660
+ indexed = [i["metadata"]["name"] for i in items
661
+ if i["metadata"]["name"].lower() == "pubtest" and not i.get("is_direct")]
662
+ if indexed:
663
+ sys.exit(f"pubrules: {REQUIREMENTS} must pin pubtest by its release wheel (`pubtest @ https://...`): "
664
+ f"from an index it is PyPI's pubtest, another project; `pubrules sync` pins it")
665
+ out = [f"# Generated by `pubrules lock` from {REQUIREMENTS.name}. Do not edit.",
666
+ "# Installed with --require-hashes: a changed artifact fails the install.", ""]
667
+ for item in sorted(items, key=lambda i: i["metadata"]["name"].lower()):
668
+ name = item["metadata"]["name"]
669
+ info = item["download_info"]
670
+ digest = info.get("archive_info", {}).get("hashes", {}).get("sha256")
671
+ if item.get("is_direct"):
672
+ digest = digest or sha256_of(info["url"])
673
+ # pip's report drops a URL's #sha256= fragment. A package that requires this one by URL
674
+ # names it with one (pubdeploy's python-statemachine), and --require-hashes counts the
675
+ # two as different requirements: a pin only a package requires keeps its fragment.
676
+ url = info["url"] if item.get("requested") else info["url"].split("#", 1)[0] + f"#sha256={digest}"
677
+ out.append(f"{name} @ {url} \\\n --hash=sha256:{digest}")
678
+ else:
679
+ version = item["metadata"]["version"]
680
+ digests = sorted(set(published_hashes(name, version)) | ({digest} if digest else set()))
681
+ hashes = " \\\n ".join(f"--hash=sha256:{d}" for d in digests)
682
+ out.append(f"{name}=={version} \\\n {hashes}")
683
+ (root / LOCK).write_text("\n".join(out) + "\n", encoding="utf-8")
684
+ print(f"locked {len(items)} packages in {LOCK}")
685
+ return 0
686
+
687
+
688
+ # The repository's own pin of pubtest, in its tests/requirements.txt: the
689
+ # release wheel, which the nightly moves. requirements-pubrules.txt names
690
+ # only the floor, and PyPI's "pubtest" is another project, so the lock never
691
+ # takes pubtest from an index. Known by the repository it comes from: the
692
+ # wheel, and so the requirement, is named by its distribution, which from
693
+ # pubtest's PyPI release on is pubtestrules.
694
+ PUBTEST_PIN = re.compile(r"^(?P<name>[A-Za-z0-9][A-Za-z0-9_.-]*)\s*@\s*(?P<wheel>https://github\.com/[A-Za-z0-9-]+/pubtest/"
695
+ r"releases/download/v[0-9][^/\s]*/[A-Za-z0-9_.]+-[^/\s]+\.whl)", re.M)
696
+
697
+
698
+ # The line sync writes above the pubtest pin.
699
+ PUBTEST_COMMENT = "# The steps and plugin the suite runs with; the nightly moves the pin.\n"
700
+
701
+
702
+ def _release(text: str) -> tuple[int, ...]:
703
+ return tuple(int(part) for part in text.split("."))
704
+
705
+
706
+ def pubtest_floor() -> str:
707
+ """The least pubtest this pubrules' steps need, as its
708
+ requirements-pubrules.txt says (`# pubtest floor: X`)."""
709
+ text = (resources.files("pubrules") / "templates" / "common" / "tests" / "requirements-pubrules.txt"
710
+ ).read_text(encoding="utf-8")
711
+ return re.search(r"^# pubtest floor: ([0-9]+\.[0-9]+\.[0-9]+)$", text, re.M)[1]
712
+
713
+
714
+ def _held(wheel: str) -> tuple[int, ...] | None:
715
+ """The release a pubtest wheel URL names, or None."""
716
+ m = re.search(r"/download/v([0-9]+\.[0-9]+\.[0-9]+)/", wheel)
717
+ return _release(m[1]) if m else None
718
+
719
+
720
+ def is_pubtest(root: Path) -> bool:
721
+ """Whether the repository is pubtest itself: its pyproject.toml registers
722
+ the pubtest pytest plugin. Its suite runs on its own checkout, installed
723
+ editable; a pinned release beside it would be another distribution once
724
+ pubtest's is pubtestrules, and the two would share the package."""
725
+ import tomllib # noqa: PLC0415
726
+ try:
727
+ project = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8")).get("project", {})
728
+ except (OSError, ValueError):
729
+ return False
730
+ return "pubtest" in project.get("entry-points", {}).get("pytest11", {})
731
+
732
+
733
+ def pubtest_pin(root: Path, check: bool) -> tuple[list[str], bool]:
734
+ """tests/requirements.txt pins pubtest by its release wheel: `sync` adds
735
+ the one tests/requirements.lock has, where it is at least the pubtest
736
+ requirements-pubrules.txt takes (a lock of an older pubrules may hold an
737
+ older one), else the latest release, where it pins none; `--check` fails
738
+ instead. Lines to print, and whether that fails."""
739
+ path = root / REQUIREMENTS
740
+ if not path.is_file() or is_pubtest(root):
741
+ return [], False
742
+ text = path.read_text(encoding="utf-8")
743
+ floor = _release(pubtest_floor())
744
+ given = PUBTEST_PIN.search(text)
745
+ if given and (_held(given["wheel"]) or (0,)) >= floor:
746
+ return [], False
747
+ if check:
748
+ if given:
749
+ return [f"pubrules: {REQUIREMENTS} pins a pubtest older than the {pubtest_floor()} pubrules' "
750
+ f"steps need; run `pubrules sync`, which pins the latest release"], True
751
+ return [f"pubrules: {REQUIREMENTS} does not pin pubtest by its release wheel, which the lock needs "
752
+ f"(PyPI's pubtest is another project); run `pubrules sync`, which pins the one "
753
+ f"{LOCK.name} has, or the latest release"], True
754
+ if given:
755
+ # Too old: dropped, and pinned again below as if it had none.
756
+ before, after = text[:given.start()], text[given.end():].removeprefix("\n")
757
+ text = before.removesuffix(PUBTEST_COMMENT) + after
758
+ lock = root / LOCK
759
+ found = PUBTEST_PIN.search(lock.read_text(encoding="utf-8")) if lock.is_file() else None
760
+ if found and (_held(found["wheel"]) or (0,)) < floor:
761
+ found = None
762
+ if found:
763
+ wheel = found["wheel"]
764
+ else:
765
+ from .releases import version, wheel_url # noqa: PLC0415
766
+ wheel = wheel_url("pubtest", version("pubtest"))
767
+ from .nightly import distribution # noqa: PLC0415
768
+ pin = (f"{PUBTEST_COMMENT}"
769
+ f"{distribution(wheel.rsplit('/', 1)[1])} @ {wheel}\n")
770
+ included = re.search(r"^-r requirements-pubrules\.txt$", text, re.M)
771
+ at = included.start() if included else len(text)
772
+ path.write_text(text[:at] + ("" if text[:at].endswith("\n") or not at else "\n") + pin + text[at:],
773
+ encoding="utf-8")
774
+ return [f"updated {REQUIREMENTS} (pubtest: {wheel.rsplit('/', 2)[-2][1:]})"], False
775
+
776
+
777
+ def conform(root: Path) -> int:
778
+ """The standard's file and setting checks, and the declared exceptions."""
779
+ from . import conform as checks
780
+ config = read_config(root)
781
+ if config["kind"] != "rust":
782
+ sys.exit("pubrules: conform checks the Rust crate standard; this is not a Rust repository")
783
+ lines, problems = checks.run(root, config)
784
+ for problem in problems:
785
+ print(f"pubrules: {problem}", file=sys.stderr)
786
+ if problems:
787
+ return 1
788
+ print("\n".join(lines))
789
+ return 0
790
+
791
+
792
+ def required(root: Path, github_output: bool, event: str = "", head_ref: str = "",
793
+ changed_file: str | None = None) -> int:
794
+ """The make targets each rust-ci.yml job must run here, from the standard.
795
+
796
+ Given the event, the pull request's branch and the files it changes, a
797
+ pull request that touches no code skips fuzz and cross, and says
798
+ slow=false."""
799
+ from . import conform as checks
800
+ from . import standard
801
+ config = read_config(root)
802
+ if config["kind"] != "rust":
803
+ sys.exit("pubrules: required checks come from the Rust crate standard; this is not a Rust repository")
804
+ rules = standard.load()
805
+ waived, _, _ = checks.exceptions(config, {r["id"] for r in rules["rules"]})
806
+ plan = standard.required(rules, standard.has_library(root), frozenset(waived))
807
+ changed = None
808
+ if changed_file is not None:
809
+ from .paths import confined
810
+ listed = confined(changed_file, "the --changed-files file")
811
+ changed = [line.strip() for line in listed.read_text(encoding="utf-8").splitlines()
812
+ if line.strip()]
813
+ reason = standard.skip_slow(event, head_ref, changed)
814
+ if reason:
815
+ plan["targets"]["fuzz"] = []
816
+ plan["jobs"] = [j for j in plan["jobs"] if j not in standard.SLOW_JOBS]
817
+ lines = [f"{job}={' '.join(targets)}" for job, targets in plan["targets"].items()]
818
+ lines += [f"{job}_job={'true' if job in plan['jobs'] else 'false'}"
819
+ for job in sorted(standard.WORKFLOW_JOBS)]
820
+ # Whether this change can change what the slow jobs test: the generated
821
+ # CI's fuzz and cross jobs read it, and pass at once when it is false.
822
+ lines.append(f"slow={'false' if reason else 'true'}")
823
+ if reason:
824
+ print(f"pubrules: {reason}", file=sys.stderr)
825
+ if github_output:
826
+ path = os.environ.get("GITHUB_OUTPUT")
827
+ if not path:
828
+ sys.exit("pubrules: --github-output needs GITHUB_OUTPUT set, as in a GitHub Actions step")
829
+ with open(path, "a", encoding="utf-8") as out:
830
+ out.write("\n".join(lines) + "\n")
831
+ print("\n".join(lines))
832
+ return 0
833
+
834
+
835
+ # Commands that judge or write a repository by its pinned standard: run as
836
+ # any other pubrules, they would check it against rules it does not pin, or
837
+ # write files `sync --check` then rejects. Commands that move a repository
838
+ # to this pubrules (bump, pins, nightly), start one (init, new), or act on
839
+ # other repositories run as whichever pubrules is installed.
840
+ PINNED_COMMANDS = {"sync", "lock", "supply-chain", "doc-coverage", "required", "conform", "gherkin", "audit",
841
+ "record"}
842
+
843
+
844
+ def wrong_pubrules(root: Path, command: str) -> str | None:
845
+ """Why this pubrules must not run `command` here: the repository's lock pins
846
+ another release. None when it pins this one or none, or with
847
+ $PUBRULES_ANY_VERSION set."""
848
+ if command not in PINNED_COMMANDS or os.environ.get("PUBRULES_ANY_VERSION"):
849
+ return None
850
+ from .freshness import pinned_package
851
+ found = pinned_package(root)
852
+ if found is None or found == ("pubrules", __version__):
853
+ return None
854
+ package, pin = found
855
+ move = ("; `pubrules bump` moves the repository to this one"
856
+ if package == "pubkit" or _release(__version__) > _release(pin) else "")
857
+ return (f"this repository pins {package} {pin}, and this is pubrules {__version__}: run "
858
+ f"`make venv` to install the pinned one, or `./pubrules {command} ...`, which runs it"
859
+ f"{move} (PUBRULES_ANY_VERSION=1 runs this one anyway)")
860
+
861
+
862
+ def _release(version: str) -> tuple[int, ...]:
863
+ """A release's numbers, for ordering: `0.15.2` is (0, 15, 2)."""
864
+ return tuple(int(n) for n in version.split("+")[0].split("-")[0].split(".") if n.isdigit())
865
+
866
+
867
+ def main(argv: list[str] | None = None) -> int:
868
+ given = sys.argv[1:] if argv is None else argv
869
+ if given[:1] == ["cache"]:
870
+ # Its own parser: `run` passes everything after -- to the command.
871
+ from .cache import main as cache
872
+ return cache(given[1:])
873
+ if given[:1] == ["service-needs"]:
874
+ # Its own parser too: the service-needs workflow's step (service_needs.py).
875
+ from .service_needs import main as service_needs # noqa: PLC0415
876
+ return service_needs(given[1:])
877
+ if given[:1] in (["secrets"], *([c] for c in MOVED)):
878
+ # Moved to pubsec: say where, whatever the arguments.
879
+ print(f"pubrules: this is now ./pubsec {' '.join(given[1:] if given[0] == 'secrets' else given)}; "
880
+ "run pubrules sync to get the launcher", file=sys.stderr)
881
+ return 2
882
+ parser = argparse.ArgumentParser(prog="pubrules", description=__doc__.split("\n")[0])
883
+ parser.add_argument("--version", action="version", version=f"pubrules {__version__}")
884
+ commands = parser.add_subparsers(dest="command", required=True)
885
+ commands.add_parser("cache", help="keep what a build fetched or made, by pubrules.json's cache rules "
886
+ "(pubrules cache --help)")
887
+ commands.add_parser("service-needs", help="in the service-needs workflow: ask the convergence engine to check "
888
+ "a unit's needs, or fulfil them once a person approves, and wait for "
889
+ "the end (pubrules service-needs --help)")
890
+ for moved in ("secrets", *MOVED):
891
+ commands.add_parser(moved, help="deprecated: now ./pubsec, with the same arguments")
892
+ p = commands.add_parser("init", help="write the shared files into this repository")
893
+ p.add_argument("--kind", choices=KINDS, required=True)
894
+ p.add_argument("--bin", help="the program under test, for <NAME>_BIN_DIR")
895
+ p.add_argument("--project", help="service: the Bitwarden Secrets Manager project (name or id) with-secrets reads")
896
+ p = commands.add_parser("new", help="start a new Rust package that meets the standard")
897
+ p.add_argument("--name", required=True, help="the package's name, which is also its binary's")
898
+ p.add_argument("--tag", required=True, help="its Section 9.1 tag, PKG-XXXXXX-MM-YYYY")
899
+ p.add_argument("--owner", help="the GitHub owner of its repository; by default the owner "
900
+ "of the origin remote")
901
+ p.add_argument("--description", default="", help="one sentence on what it is for")
902
+ p.add_argument("--no-key", action="store_true",
903
+ help="do not create the corpus workspace and release key (for tests)")
904
+ p.add_argument("--no-lock", action="store_true",
905
+ help="do not lock the test requirements, which needs the network")
906
+ p = commands.add_parser("sync", help="rewrite, or with --check verify, the managed files")
907
+ p.add_argument("--check", action="store_true")
908
+ commands.add_parser("lock", help="pin tests/requirements.txt with hashes")
909
+ p = commands.add_parser("supply-chain",
910
+ help="write, or with --check verify, each crate's SUPPLY-CHAIN.md")
911
+ p.add_argument("--check", action="store_true")
912
+ p.add_argument("crates", nargs="+", metavar="CRATE")
913
+ p = commands.add_parser("doc-coverage",
914
+ help="write, or with --check verify, each library's TESTING.md")
915
+ p.add_argument("--check", action="store_true")
916
+ p.add_argument("crates", nargs="*", metavar="CRATE",
917
+ help="the crates; by default every published library here")
918
+ p = commands.add_parser("audit",
919
+ help="prepare, draft or check a release's quality audit (RS-REL-01)")
920
+ p.add_argument("step", nargs="?", choices=("prepare", "draft"),
921
+ help="prepare: write the report with every rule a machine can decide; "
922
+ "draft: have Claude draft the rules left for review")
923
+ p.add_argument("--package", help="for prepare and draft: the package being released")
924
+ p.add_argument("--version", dest="release_version",
925
+ help="for prepare: the version being released; by default `pubrel next --package NAME`")
926
+ p.add_argument("--out", help="for prepare: write here, not audit/PACKAGE-VERSION.md")
927
+ p.add_argument("--quick", action="store_true",
928
+ help="for prepare: skip the docs.rs, MSRV and publish builds and the make targets")
929
+ p.add_argument("--force", action="store_true",
930
+ help="for prepare: write over an existing report")
931
+ p.add_argument("--report", help="for draft: the report to draft into; by default audit/PACKAGE-VERSION.md")
932
+ p.add_argument("--model", help="for draft: the Claude model; by default $PUBRULES_AUDIT_MODEL, "
933
+ "or claude-opus-5-5")
934
+ group = p.add_mutually_exclusive_group()
935
+ group.add_argument("--check", nargs="*", metavar="PACKAGE VERSION",
936
+ help="pass only if audit/PACKAGE-VERSION.md is current, blocks nothing and has "
937
+ "nothing left to review; without them, the release pubrel prepare is "
938
+ "cutting ($PUBREL_PACKAGE, $PUBREL_VERSION)"),
939
+ group.add_argument("--standard", action="store_true",
940
+ help="print the sha256 of the standard this pubrules ships, for a report's header")
941
+ p = commands.add_parser("pins", help="move every outdated pub* pin to its latest release")
942
+ p.add_argument("--pubrel", default="", help="pubrel's latest release, for its workflow pins")
943
+ p.add_argument("--no-lock", action="store_true", help="do not relock (it needs the network)")
944
+ commands.add_parser("actions",
945
+ help="move each third-party GitHub Action pinned by commit to its latest release")
946
+ p = commands.add_parser("crates",
947
+ help="update other crates, keeping only what cargo vet audits and cargo deny passes")
948
+ p.add_argument("--report", type=Path, help="write what was updated and skipped, as JSON")
949
+ p = commands.add_parser("record",
950
+ help="add an internal pubrel row for each package the last commit needs one for")
951
+ p.add_argument("text", help="what changed")
952
+ p = commands.add_parser("nightly",
953
+ help="commit the pins, the actions, then the audited crate updates, and write the PR body")
954
+ p.add_argument("--pubrel", required=True)
955
+ p.add_argument("--body", required=True, type=Path)
956
+ commands.add_parser("bump",
957
+ help="move this repository to this pubrules: managed files, lock, workflow pins")
958
+ commands.add_parser("conform",
959
+ help="check the standard's required files and settings, and the exceptions")
960
+ commands.add_parser("gherkin",
961
+ help="check that every test is a Gherkin scenario (TEST-01..03), and list the exceptions")
962
+ p = commands.add_parser("protect",
963
+ help="put pubrules' ruleset on the default branch of each repository")
964
+ p.add_argument("--check", action="store_true",
965
+ help="change nothing: print how each differs, and fail when one does")
966
+ p.add_argument("--repos", dest="repos_file", type=Path, metavar="FILE",
967
+ help="the repos file: protect those it marks, each by its own pubrules.json")
968
+ p.add_argument("--require", action="append", metavar="CHECK",
969
+ help="a check the named repositories require, instead of their own "
970
+ "pubrules.json; repeat it")
971
+ p.add_argument("--no-tags", dest="tags", action="store_false",
972
+ help="leave out the release tag ruleset, for repositories that release no tags")
973
+ p.add_argument("--no-queue", dest="queue", action="store_false",
974
+ help="merge from a branch up to date with main instead of through the merge "
975
+ "queue, for repositories GitHub offers no merge queue (a user's, or a "
976
+ "private one)")
977
+ p.add_argument("repos", nargs="*", metavar="REPO",
978
+ help="OWNER/NAME, read from its own pubrules.json on GitHub; by default "
979
+ "those the repos file marks, or this repository from ./pubrules.json")
980
+ p = commands.add_parser("required",
981
+ help="the make targets each rust-ci.yml job must run, from the standard")
982
+ p.add_argument("--github-output", action="store_true",
983
+ help="also append them to $GITHUB_OUTPUT")
984
+ p.add_argument("--event", default="",
985
+ help="the GitHub event: on a pull_request, fuzz and cross may be skipped")
986
+ p.add_argument("--head-ref", default="",
987
+ help="the pull request's branch; a release/ branch runs everything")
988
+ p.add_argument("--changed-files", metavar="FILE",
989
+ help="a file listing the paths the pull request changes, one per line")
990
+ args = parser.parse_args(argv)
991
+ root = Path.cwd()
992
+ if (why := wrong_pubrules(root, args.command)) is not None:
993
+ print(f"pubrules: {why}", file=sys.stderr)
994
+ return 2
995
+ if args.command == "init":
996
+ return init(root, args.kind, args.bin, args.project)
997
+ if args.command == "new":
998
+ from .new import run as new
999
+ return new(root, args.name, args.tag, args.description, owner=args.owner,
1000
+ key=not args.no_key, lock=not args.no_lock)
1001
+ if args.command == "sync":
1002
+ return sync(root, args.check)
1003
+ if args.command == "supply-chain":
1004
+ from .supply_chain import run
1005
+ return run(root, args.crates, args.check)
1006
+ if args.command == "doc-coverage":
1007
+ from .doc_coverage import run as coverage
1008
+ return coverage(root, args.crates, args.check)
1009
+ if args.command == "required":
1010
+ return required(root, args.github_output, args.event, args.head_ref,
1011
+ args.changed_files)
1012
+ if args.command == "conform":
1013
+ return conform(root)
1014
+ if args.command == "gherkin":
1015
+ from .gherkin import main as gherkin # noqa: PLC0415
1016
+ return gherkin(root, read_config(root))
1017
+ if args.command == "pins":
1018
+ from .nightly import pins
1019
+ for line in pins(root, args.pubrel, lock=not args.no_lock):
1020
+ print(line)
1021
+ return 0
1022
+ if args.command == "actions":
1023
+ from .nightly import actions
1024
+ for line in actions(root):
1025
+ print(line)
1026
+ return 0
1027
+ if args.command == "crates":
1028
+ from .nightly import crates
1029
+ return crates(root, args.report)
1030
+ if args.command == "record":
1031
+ from .nightly import record
1032
+ for package in record(root, args.text):
1033
+ print(f"recorded for {package}")
1034
+ return 0
1035
+ if args.command == "nightly":
1036
+ from .nightly import nightly
1037
+ return nightly(root, args.pubrel, args.body)
1038
+ if args.command == "bump":
1039
+ from .freshness import bump
1040
+ return bump(root)
1041
+ if args.command == "protect":
1042
+ from .paths import confined
1043
+ from .protect import run as protect
1044
+ if args.repos_file and args.require:
1045
+ sys.exit("pubrules protect: --repos takes the place of --require")
1046
+ repos_file = confined(args.repos_file, "the --repos file") if args.repos_file else None
1047
+ return protect(args.repos, args.check, args.require, tags=args.tags,
1048
+ queue=args.queue, repos_file=repos_file)
1049
+ if args.command == "audit" and args.step:
1050
+ if not args.package:
1051
+ sys.exit(f"pubrules: audit {args.step} needs --package NAME")
1052
+ if args.check is not None or args.standard:
1053
+ sys.exit(f"pubrules: audit {args.step} takes neither --check nor --standard")
1054
+ if args.step == "prepare":
1055
+ from .audit_prepare import prepare
1056
+ return prepare(root, args.package, args.release_version, args.out, args.quick, args.force)
1057
+ from .audit_draft import draft
1058
+ draft(root, args.package, args.report, args.model)
1059
+ return 0
1060
+ if args.command == "audit":
1061
+ if args.check is None and not args.standard:
1062
+ sys.exit("pubrules: audit takes prepare, draft, --check or --standard")
1063
+ from .audit import run as audit
1064
+ return audit(root, args.check if args.check is not None else [], args.standard)
1065
+ return lock(root)
1066
+
1067
+
1068
+ if __name__ == "__main__":
1069
+ sys.exit(main())