napkinstack 0.29.1__tar.gz → 0.31.0__tar.gz
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.
- {napkinstack-0.29.1 → napkinstack-0.31.0}/PKG-INFO +6 -6
- {napkinstack-0.29.1 → napkinstack-0.31.0}/README.md +5 -5
- {napkinstack-0.29.1 → napkinstack-0.31.0}/pyproject.toml +1 -1
- {napkinstack-0.29.1 → napkinstack-0.31.0}/pyproject.toml.orig +1 -1
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/attest.py +116 -6
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/board.py +39 -4
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/cli.py +8 -5
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/doctor.py +50 -3
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/evidence.py +34 -3
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/manifests.py +6 -1
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/plan.py +20 -8
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/modules.py +14 -6
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/project.py +49 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/pull_request.py +181 -14
- {napkinstack-0.29.1 → napkinstack-0.31.0}/LICENSE +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/__init__.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/__main__.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/agent.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/assurance.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/compat.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/discovery.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/__init__.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/boundaries.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/hygiene.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/pr_scope.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/hold.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/landed.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/owners.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/provenance.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/settings.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/skills.py +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/README.md +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/README.md +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
- {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/tests/.gitkeep +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: napkinstack
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.31.0
|
|
4
4
|
Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -22,7 +22,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
|
|
|
22
22
|
the project, which then receives new versions on demand; no application stack is imposed.
|
|
23
23
|
Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
|
|
24
24
|
|
|
25
|
-
> **Status: v0.
|
|
25
|
+
> **Status: v0.31.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
|
|
26
26
|
> What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
|
|
27
27
|
> What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
|
|
28
28
|
|
|
@@ -86,8 +86,8 @@ To try it without installing anything, or to install it from this repository ins
|
|
|
86
86
|
registry — always pinned to a release tag:
|
|
87
87
|
|
|
88
88
|
```bash
|
|
89
|
-
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.
|
|
90
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.
|
|
89
|
+
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.31.0" nstack init my-project
|
|
90
|
+
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.31.0"
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
|
|
@@ -117,12 +117,12 @@ Each project then pins its version and changes it through `nstack update`.
|
|
|
117
117
|
| `nstack claim <deliverable or '#issue'> [--take-over]`; `nstack unclaim …` | Takes a ready deliverable — or an issue no cycle plans — for a session before its first change, on a branch of its own the shared remote refuses to a second taker; gives it back ([ADR-0007](docs/adr/0007-hold-a-deliverable-on-a-branch-of-its-own.md)) |
|
|
118
118
|
| `nstack deliver <deliverable> --held [N=]#PR` | Records that a merged deliverable is delivered, criterion by criterion, with no pull request; refused with no merge of it; `--write-states` writes the states at a closure ([PDR-0022](docs/pdr/0022-agents-deliver-alone-a-person-is-asked-only-where-it-matters.md)) |
|
|
119
119
|
| `nstack agent add <name>`; `nstack agent run <name> -- <command>`; `nstack agent status` | Gives an agent its own GitHub App and a clone that commits as it and runs the project's hooks — `add` is a person's, two clicks at the forge; starts the agent there without the person's credentials, says what it keeps of them, gives Claude Code settings of its own; `status` tells an agent who it is, a person this project's agents (`--all`: every project's) ([ADR-0004](docs/adr/0004-give-agents-their-own-github-identity.md)) |
|
|
120
|
-
| `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)) |
|
|
120
|
+
| `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)); a dry run also previews what a proposed cycle's acceptance would create |
|
|
121
121
|
| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
|
|
122
122
|
| `nstack pr-scope` | One PR = one module, review budget |
|
|
123
123
|
| `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
|
|
124
124
|
| `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
|
|
125
|
-
| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
|
|
125
|
+
| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
|
|
126
126
|
| `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
|
|
127
127
|
| `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
|
|
128
128
|
| `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
|
|
@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
|
|
|
5
5
|
the project, which then receives new versions on demand; no application stack is imposed.
|
|
6
6
|
Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
|
|
7
7
|
|
|
8
|
-
> **Status: v0.
|
|
8
|
+
> **Status: v0.31.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
|
|
9
9
|
> What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
|
|
10
10
|
> What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
|
|
11
11
|
|
|
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
|
|
|
69
69
|
registry — always pinned to a release tag:
|
|
70
70
|
|
|
71
71
|
```bash
|
|
72
|
-
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.
|
|
73
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.
|
|
72
|
+
uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.31.0" nstack init my-project
|
|
73
|
+
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.31.0"
|
|
74
74
|
```
|
|
75
75
|
|
|
76
76
|
**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
|
|
@@ -100,12 +100,12 @@ Each project then pins its version and changes it through `nstack update`.
|
|
|
100
100
|
| `nstack claim <deliverable or '#issue'> [--take-over]`; `nstack unclaim …` | Takes a ready deliverable — or an issue no cycle plans — for a session before its first change, on a branch of its own the shared remote refuses to a second taker; gives it back ([ADR-0007](docs/adr/0007-hold-a-deliverable-on-a-branch-of-its-own.md)) |
|
|
101
101
|
| `nstack deliver <deliverable> --held [N=]#PR` | Records that a merged deliverable is delivered, criterion by criterion, with no pull request; refused with no merge of it; `--write-states` writes the states at a closure ([PDR-0022](docs/pdr/0022-agents-deliver-alone-a-person-is-asked-only-where-it-matters.md)) |
|
|
102
102
|
| `nstack agent add <name>`; `nstack agent run <name> -- <command>`; `nstack agent status` | Gives an agent its own GitHub App and a clone that commits as it and runs the project's hooks — `add` is a person's, two clicks at the forge; starts the agent there without the person's credentials, says what it keeps of them, gives Claude Code settings of its own; `status` tells an agent who it is, a person this project's agents (`--all`: every project's) ([ADR-0004](docs/adr/0004-give-agents-their-own-github-identity.md)) |
|
|
103
|
-
| `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)) |
|
|
103
|
+
| `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)); a dry run also previews what a proposed cycle's acceptance would create |
|
|
104
104
|
| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
|
|
105
105
|
| `nstack pr-scope` | One PR = one module, review budget |
|
|
106
106
|
| `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
|
|
107
107
|
| `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
|
|
108
|
-
| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
|
|
108
|
+
| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
|
|
109
109
|
| `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
|
|
110
110
|
| `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
|
|
111
111
|
| `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
|
|
@@ -7,7 +7,10 @@ test — on a clean tree at a commit, and appends the run to that commit's note
|
|
|
7
7
|
`refs/notes/nstack/checks`, one JSON line per run. The note travels with the branch's remote
|
|
8
8
|
and is merged line by line; the latest line for a commit is its record. On GitHub, with a token
|
|
9
9
|
that may write statuses, the run is also shown as `nstack / local checks` — a name no CI job
|
|
10
|
-
has. A
|
|
10
|
+
has. A passed `Module checks` is kept, not run again, while the digest of what it reads is
|
|
11
|
+
unchanged — the modules it runs and those they consume from or assemble, the files outside the
|
|
12
|
+
modules, `contracts/` and `platform/` included, the engine and the person — for 7 days and 20 commits of the default branch at most (ADR-0006,
|
|
13
|
+
D223). A ruleset that requires that name gates the merge on the record, and the forge's pull
|
|
11
14
|
request run leaves the record to it (D221): notes start no run, a status is an event.
|
|
12
15
|
A record is *attested*, never *checked*: it makes a claim traceable, not true.
|
|
13
16
|
|
|
@@ -293,6 +296,93 @@ def why(output: str) -> list[str]:
|
|
|
293
296
|
NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
|
|
294
297
|
|
|
295
298
|
|
|
299
|
+
FRESH_DAYS = 7 # a check kept by its inputs, at most this old (ADR-0006, D223)
|
|
300
|
+
FRESH_COMMITS = 20 # and the default branch moved by at most this many commits since its run
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
SHARED_MODULES = ("contracts", "platform") # read by every module: counted as shared files (D223)
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def inputs(root: Path, base: str, identity: str = "") -> str | None:
|
|
307
|
+
"""The digest of what `Module checks` reads at HEAD (ADR-0006 decision 2, D223): the folders of
|
|
308
|
+
the modules it runs, of those they consume from or assemble, every tracked path outside the
|
|
309
|
+
module folders — `contracts/` and `platform/` included, which every module reads — and who runs
|
|
310
|
+
it with which engine; git's ids, never hashed by hand. None when it cannot be told: no key."""
|
|
311
|
+
import yaml
|
|
312
|
+
|
|
313
|
+
from napkinstack import modules
|
|
314
|
+
|
|
315
|
+
ran = modules.listing(root, base, with_contract_sides=True)
|
|
316
|
+
every = {module["name"]: module["folder"] for module in modules.listing(root) or []}
|
|
317
|
+
if ran is None:
|
|
318
|
+
return None
|
|
319
|
+
folders = {module["folder"] for module in ran}
|
|
320
|
+
for module in ran:
|
|
321
|
+
try:
|
|
322
|
+
data = yaml.safe_load((root / module["folder"] / "MANIFEST.yaml").read_text(encoding="utf-8")) or {}
|
|
323
|
+
except (OSError, yaml.YAMLError):
|
|
324
|
+
return None
|
|
325
|
+
consumes = data.get("consumes") if isinstance(data, dict) else None
|
|
326
|
+
assembles = data.get("assembles") if isinstance(data, dict) else None
|
|
327
|
+
named = [entry.get("module") for entry in consumes if isinstance(entry, dict) and entry.get("module")] \
|
|
328
|
+
if isinstance(consumes, list) else []
|
|
329
|
+
named += [name for name in assembles if isinstance(name, str)] if isinstance(assembles, list) else []
|
|
330
|
+
for name in named:
|
|
331
|
+
if name not in every:
|
|
332
|
+
return None # a dependency the project does not hold: what it reads is unknown
|
|
333
|
+
folders.add(every[name])
|
|
334
|
+
lines = [f"ran {' '.join(sorted(module['name'] for module in ran))}", f"identity {identity}"]
|
|
335
|
+
for folder in sorted(folders):
|
|
336
|
+
tree = _git(root, "rev-parse", "--verify", "--quiet", f"HEAD:{folder}", check=False).stdout.strip()
|
|
337
|
+
if not tree:
|
|
338
|
+
return None
|
|
339
|
+
lines.append(f"{folder} {tree}")
|
|
340
|
+
inside = tuple(f"{folder}/" for folder in every.values() if folder.split("/", 1)[0] not in SHARED_MODULES)
|
|
341
|
+
listed = _git(root, "ls-tree", "-r", "--full-tree", "HEAD", check=False)
|
|
342
|
+
if listed.returncode:
|
|
343
|
+
return None
|
|
344
|
+
lines += [line for line in listed.stdout.splitlines() if not line.split("\t", 1)[-1].startswith(inside)]
|
|
345
|
+
return hashlib.sha256("\n".join(lines).encode("utf-8", "surrogateescape")).hexdigest()
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def _fresh(root: Path, at: str, run_base: str | None, base_commit: str | None) -> bool:
|
|
349
|
+
"""Whether a run kept by its inputs is recent enough (ADR-0006, D223)."""
|
|
350
|
+
try:
|
|
351
|
+
when = datetime.datetime.fromisoformat(at)
|
|
352
|
+
except (TypeError, ValueError):
|
|
353
|
+
return False
|
|
354
|
+
now = datetime.datetime.now(datetime.timezone.utc)
|
|
355
|
+
if when.tzinfo is None or now - when > datetime.timedelta(days=FRESH_DAYS) or when - now > datetime.timedelta(minutes=5):
|
|
356
|
+
return False # too old, or from a clock ahead: never fresh for longer than the bound
|
|
357
|
+
if not run_base or not base_commit:
|
|
358
|
+
return False
|
|
359
|
+
moved = _git(root, "rev-list", "--count", f"{run_base}..{base_commit}", check=False)
|
|
360
|
+
return moved.returncode == 0 and int(moved.stdout.strip() or 0) <= FRESH_COMMITS
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine: str, origin: str | None,
|
|
364
|
+
base_commit: str | None, who: str, said: str | None) -> dict | None:
|
|
365
|
+
"""The check as a passed run on this branch's history left it, when what it reads is the same
|
|
366
|
+
— the digest of its inputs, whatever the commit — and the run is fresh (ADR-0006, D223)."""
|
|
367
|
+
if digest is None or not check.kept or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
|
|
368
|
+
return None
|
|
369
|
+
for commit in _git(root, "rev-list", f"{base_commit}..HEAD", check=False).stdout.split():
|
|
370
|
+
record = latest(root, commit)
|
|
371
|
+
if record is None or (record.get("engine"), record.get("origin"), record.get("published"),
|
|
372
|
+
record.get("by")) != (engine, said, origin is None, who):
|
|
373
|
+
continue
|
|
374
|
+
checks = record.get("checks") if isinstance(record.get("checks"), list) else []
|
|
375
|
+
found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
|
|
376
|
+
if not found or found.get("passed") is not True or found.get("inputs") != digest:
|
|
377
|
+
continue
|
|
378
|
+
first = str(found.get("kept_from") or record.get("at", ""))
|
|
379
|
+
run_base = found.get("kept_base") or record.get("base_commit")
|
|
380
|
+
if not _fresh(root, first, run_base, base_commit):
|
|
381
|
+
continue
|
|
382
|
+
return {**found, "kept_from": first, "kept_commit": found.get("kept_commit") or commit, "kept_base": run_base}
|
|
383
|
+
return None
|
|
384
|
+
|
|
385
|
+
|
|
296
386
|
def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
|
|
297
387
|
who: str, said: str | None = None) -> dict | None:
|
|
298
388
|
"""The check as the commit's record last passed it, when what it reads is the same: the commit,
|
|
@@ -307,8 +397,8 @@ def _kept(previous: dict | None, check: Check, engine: str, origin: str | None,
|
|
|
307
397
|
return None
|
|
308
398
|
checks = previous.get("checks") if isinstance(previous.get("checks"), list) else []
|
|
309
399
|
found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
|
|
310
|
-
if not found or found.get("passed") is not True:
|
|
311
|
-
return None
|
|
400
|
+
if not found or found.get("passed") is not True or found.get("kept_commit"):
|
|
401
|
+
return None # kept by its inputs from another commit: its freshness is _by_inputs' to judge (D223)
|
|
312
402
|
return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
|
|
313
403
|
|
|
314
404
|
|
|
@@ -355,8 +445,16 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
355
445
|
engine, origin = provenance.engine()
|
|
356
446
|
base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
|
|
357
447
|
previous = None if again else latest(root, commit)
|
|
358
|
-
# The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147)
|
|
359
|
-
|
|
448
|
+
# The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147) — and the
|
|
449
|
+
# pull request's own when the forge answers, a label it does not carry refused (#368).
|
|
450
|
+
from napkinstack.pull_request import labels_for
|
|
451
|
+
|
|
452
|
+
judged, labels_from, refused = labels_for(root, commit, os.environ.get("PR_LABELS", "") if labels is None else labels)
|
|
453
|
+
if refused:
|
|
454
|
+
print(f"FAIL [attest] {refused}")
|
|
455
|
+
return 1
|
|
456
|
+
print(f"Labels: {', '.join(sorted(judged)) or 'none'} — {labels_from}", flush=True)
|
|
457
|
+
env = dict(os.environ, PR_LABELS=",".join(sorted(judged)))
|
|
360
458
|
# The engine that runs this command runs the checks: its folder first on the path.
|
|
361
459
|
env["PATH"] = os.pathsep.join([str(Path(sys.argv[0]).resolve().parent), env.get("PATH", "")])
|
|
362
460
|
results = []
|
|
@@ -369,6 +467,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
369
467
|
# without asking for the record this run is making (A1, A2) — found rehearsing v0.10.0.
|
|
370
468
|
env.update(NSTACK_BASE=base, NSTACK_BODY=str(Path(body).resolve()), NSTACK_TMP=tmp,
|
|
371
469
|
NSTACK_ATTESTING=commit)
|
|
470
|
+
digest = inputs(root, base, json.dumps([engine, unplaced(origin, root), origin is None, who]))
|
|
471
|
+
env["NSTACK_INPUTS"] = digest or "" # the head's, for pr-check's T4 while this record is made (D223)
|
|
372
472
|
for check in CHECKS:
|
|
373
473
|
kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
|
|
374
474
|
if kept is not None:
|
|
@@ -376,6 +476,14 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
376
476
|
print(f"ok [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
|
|
377
477
|
"and engine (nstack attest --again runs it)", flush=True)
|
|
378
478
|
continue
|
|
479
|
+
kept = None if again else _by_inputs(root, base, digest, check, engine, origin, base_commit, who,
|
|
480
|
+
unplaced(origin, root))
|
|
481
|
+
if kept is not None:
|
|
482
|
+
results.append(kept)
|
|
483
|
+
print(f"ok [attest] {check.name}: kept from the run on {kept['kept_commit'][:7]} at {kept['kept_from']} — "
|
|
484
|
+
f"same inputs ({digest[:12]}), within {FRESH_DAYS} days and {FRESH_COMMITS} commits of the "
|
|
485
|
+
"default branch (nstack attest --again runs it)", flush=True)
|
|
486
|
+
continue
|
|
379
487
|
steps = []
|
|
380
488
|
for step in check.steps:
|
|
381
489
|
done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
|
|
@@ -384,7 +492,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
384
492
|
"output": capped(done.stdout),
|
|
385
493
|
"sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
|
|
386
494
|
passed = all(step["exit"] == 0 for step in steps)
|
|
387
|
-
results.append({"name": check.name, "passed": passed, "steps": steps
|
|
495
|
+
results.append({"name": check.name, "passed": passed, "steps": steps,
|
|
496
|
+
**({"inputs": digest} if check.kept and digest else {})})
|
|
388
497
|
failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
|
|
389
498
|
print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok [attest] {check.name}", flush=True)
|
|
390
499
|
for step in steps:
|
|
@@ -395,6 +504,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
395
504
|
"engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(root, commit),
|
|
396
505
|
"base": base, "base_commit": base_commit, "checks": results,
|
|
397
506
|
"sheet": sheet_of(body_text),
|
|
507
|
+
"labels": {"names": sorted(judged), "from": labels_from},
|
|
398
508
|
# The audits of the run the module checks come from: kept with them, never read again (#275).
|
|
399
509
|
"evidence": (previous.get("evidence") if isinstance(previous.get("evidence"), list) else [])
|
|
400
510
|
if previous and any(r.get("kept_from") for r in results) else evidence_of(root, commit)}
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
The plan shown on the forge, one way (PDR-0016, ADR-0008).
|
|
3
3
|
|
|
4
4
|
The cycle files are the plan; this command shows them on GitHub — a milestone per accepted,
|
|
5
|
-
closed or stopped cycle, an issue per deliverable — and keeps the display equal to them.
|
|
5
|
+
closed or stopped cycle, an issue per deliverable — and keeps the display equal to them. A dry
|
|
6
|
+
run also previews what a proposed cycle's acceptance would create, and makes none of it. Its own
|
|
6
7
|
objects carry a marker in their body; an object without one is never touched. What the forge
|
|
7
8
|
holds decides nothing but whether the display must be rewritten.
|
|
8
9
|
|
|
@@ -72,7 +73,8 @@ def _reason(state: str) -> str:
|
|
|
72
73
|
|
|
73
74
|
|
|
74
75
|
def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str, list[int]] | None = None,
|
|
75
|
-
today: datetime.date | None = None, delivered: set[str] | None = None
|
|
76
|
+
today: datetime.date | None = None, delivered: set[str] | None = None,
|
|
77
|
+
statuses: set[str] = SHOWN) -> tuple[list[Shown], list[str]]:
|
|
76
78
|
"""The display the cycle files call for, and what cannot be shown and why. `holders`:
|
|
77
79
|
deliverable identifier to the hold's person; `pulls`: identifier to the pull requests whose
|
|
78
80
|
description names it."""
|
|
@@ -81,7 +83,7 @@ def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str,
|
|
|
81
83
|
for path in plan.cycle_files(root):
|
|
82
84
|
data = plan.read_front_matter(path)[0]
|
|
83
85
|
found = NUMBER.match(path.stem)
|
|
84
|
-
if data and plan.one_of(data.get("status"),
|
|
86
|
+
if data and plan.one_of(data.get("status"), statuses) and found:
|
|
85
87
|
cycles.setdefault(found[1], []).append((path, data))
|
|
86
88
|
said = [f"cycle {number} not shown: {len(files)} cycle files carry its number "
|
|
87
89
|
f"({', '.join(path.name for path, _ in files)})" for number, files in cycles.items() if len(files) > 1]
|
|
@@ -99,7 +101,7 @@ def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str,
|
|
|
99
101
|
continue
|
|
100
102
|
path, data = files[0]
|
|
101
103
|
relative = path.relative_to(root).as_posix()
|
|
102
|
-
closed = data.get("status")
|
|
104
|
+
closed = data.get("status") not in ("accepted", "proposed") # proposed: only ever previewed
|
|
103
105
|
text = path.read_text(encoding="utf-8", errors="replace")
|
|
104
106
|
front = plan.FRONT_MATTER.match(text)
|
|
105
107
|
heading = HEADING.search(text[front.end():] if front else text)
|
|
@@ -206,6 +208,8 @@ def _clean(text) -> str:
|
|
|
206
208
|
def run(root: Path, dry_run: bool = False, today: datetime.date | None = None) -> int:
|
|
207
209
|
from napkinstack import hold
|
|
208
210
|
|
|
211
|
+
if dry_run:
|
|
212
|
+
_preview(root, today)
|
|
209
213
|
first, said = desired(root, today=today)
|
|
210
214
|
if not first:
|
|
211
215
|
_tell(said, "Plan on the forge: nothing to show — no accepted, closed or stopped cycle")
|
|
@@ -240,6 +244,37 @@ def run(root: Path, dry_run: bool = False, today: datetime.date | None = None) -
|
|
|
240
244
|
return 0
|
|
241
245
|
|
|
242
246
|
|
|
247
|
+
def _preview(root: Path, today: datetime.date | None) -> None:
|
|
248
|
+
"""What a proposed cycle's acceptance would create, said on a dry run and never made (#372): the
|
|
249
|
+
decider reviews the breakdown as the board will show it, before the acceptance decides it."""
|
|
250
|
+
numbers, idents = set(), set()
|
|
251
|
+
for path in plan.cycle_files(root):
|
|
252
|
+
data = plan.read_front_matter(path)[0]
|
|
253
|
+
found = NUMBER.match(path.stem)
|
|
254
|
+
if data and data.get("status") == "proposed" and found:
|
|
255
|
+
numbers.add(found[1])
|
|
256
|
+
items = data.get("deliverables")
|
|
257
|
+
idents |= {str(item["id"]) for item in items if isinstance(item, dict) and item.get("id")} \
|
|
258
|
+
if isinstance(items, list) else set()
|
|
259
|
+
if not numbers:
|
|
260
|
+
return
|
|
261
|
+
# Read beside the cycles already shown: what their acceptance would collide with is said too.
|
|
262
|
+
every, said = desired(root, today=today, statuses=SHOWN | {"proposed"})
|
|
263
|
+
for number in sorted(numbers):
|
|
264
|
+
cycle = next((item for item in every if item.kind == "cycle" and item.key == number), None)
|
|
265
|
+
if cycle is None:
|
|
266
|
+
continue
|
|
267
|
+
print(f"On acceptance of cycle {number} — previewed, nothing made:\n"
|
|
268
|
+
f" milestone {cycle.title}, ends {cycle.due or 'with no end date'}")
|
|
269
|
+
for item in every:
|
|
270
|
+
if item.kind == "deliverable" and item.cycle == number:
|
|
271
|
+
state = item.labels[-1].removeprefix("state: ") if item.labels else ""
|
|
272
|
+
print(f" issue {item.title} — {state}" + (", shown closed" if item.state == "closed" else ""))
|
|
273
|
+
for line in said:
|
|
274
|
+
if any(re.search(rf"\b{re.escape(key)}\b", line) for key in numbers | idents):
|
|
275
|
+
print(f" NOTE on acceptance: {line}")
|
|
276
|
+
|
|
277
|
+
|
|
243
278
|
def _tell(lines: list[str], head: str) -> None:
|
|
244
279
|
"""Said in the output; in GitHub Actions, also in the job's summary, and what was not shown as
|
|
245
280
|
a warning a person sees on the run."""
|
|
@@ -121,7 +121,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
121
121
|
lambda a: modules.create(a.root, a.name, a.owner, a.criticality, a.user_facing))
|
|
122
122
|
nm.add_argument("name", help="module name, kebab-case")
|
|
123
123
|
nm.add_argument("owner", help="GitHub team, organisation/team, or a user when the project has "
|
|
124
|
-
"no organisation")
|
|
124
|
+
"no organisation — on GitHub, never an organisation's name alone")
|
|
125
125
|
nm.add_argument("criticality", choices=list(assurance.CRITICALITIES),
|
|
126
126
|
help="what a failure of this module costs — prototype: nothing, it is "
|
|
127
127
|
"thrown away and nothing depends on it · standard: real code, no "
|
|
@@ -169,7 +169,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
169
169
|
lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
|
|
170
170
|
pc.add_argument("--base", default="origin/main")
|
|
171
171
|
pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
|
|
172
|
-
pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)"
|
|
172
|
+
pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
|
|
173
|
+
"token and one open pull request at the head, its own are read")
|
|
173
174
|
ld = _add(sub, "landed", "what reached this branch outside a pull request, recorded (W1)",
|
|
174
175
|
lambda a: landed.run(a.root, a.span, landed.from_environment(a.root)))
|
|
175
176
|
ld.add_argument("--span", default="HEAD~1..HEAD",
|
|
@@ -178,7 +179,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
178
179
|
lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
|
|
179
180
|
at.add_argument("--base", default="origin/main")
|
|
180
181
|
at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
|
|
181
|
-
at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)"
|
|
182
|
+
at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
|
|
183
|
+
"token and one open pull request at the head, its own are read")
|
|
182
184
|
at.add_argument("--accept-identity", action="store_true",
|
|
183
185
|
help="record under an identity the project's history does not show yet — a first record of yours")
|
|
184
186
|
at.add_argument("--again", action="store_true",
|
|
@@ -207,7 +209,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
207
209
|
dl.add_argument("--write-states", action="store_true", help="at a closure: writes the records' states in the cycle file, for its one pull request")
|
|
208
210
|
bd = _add(sub, "board", "shows the cycles and their deliverables on the forge, one way: milestones and issues",
|
|
209
211
|
lambda a: board.run(a.root, a.dry_run))
|
|
210
|
-
bd.add_argument("--dry-run", action="store_true", help="say what would change, change nothing")
|
|
212
|
+
bd.add_argument("--dry-run", action="store_true", help="say what would change, change nothing — and preview what a proposed cycle's acceptance would create")
|
|
211
213
|
ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent",
|
|
212
214
|
lambda a: discovery.run(a.root, a.idea))
|
|
213
215
|
ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
|
|
@@ -250,7 +252,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
250
252
|
ini.add_argument("--repository", help="the repository's path at another forge, group/name or "
|
|
251
253
|
"group/subgroup/name (asked when absent)")
|
|
252
254
|
ini.add_argument("--owner-team", help="owner of the foundation: organisation/team, or a user "
|
|
253
|
-
"when the project has no organisation
|
|
255
|
+
"when the project has no organisation — on GitHub, never an "
|
|
256
|
+
"organisation's name alone (asked when absent)")
|
|
254
257
|
ini.add_argument("--source", help="template: URL or path (default: the NapkinStack repository)")
|
|
255
258
|
ini.add_argument("--ref", help="skeleton version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
|
|
256
259
|
ini.set_defaults(func=_init)
|
|
@@ -12,7 +12,8 @@ either: whether its default branch holds that commit (GITHUB_API_URL, otherwise
|
|
|
12
12
|
https://api.github.com). No answer leaves L1 as it is.
|
|
13
13
|
|
|
14
14
|
GitHub is read with a token supplied by a human (GH_TOKEN, otherwise GITHUB_TOKEN):
|
|
15
|
-
fine-grained, limited to the repository, Administration: read permission (Actions: read for N2
|
|
15
|
+
fine-grained, limited to the repository, Administration: read permission (Actions: read for N2,
|
|
16
|
+
Contents: read for L10 on a private repository). Without a token,
|
|
16
17
|
or when the API refuses a read, the setting is "not verified", never compliant. No write.
|
|
17
18
|
|
|
18
19
|
Rules:
|
|
@@ -35,6 +36,10 @@ Rules:
|
|
|
35
36
|
L9 the `forge` answer is the one the project's files were written for — never changed by
|
|
36
37
|
hand, which Copier would misread; `nstack update --forge` changes it. A remote on another
|
|
37
38
|
known public forge is said, never judged: a mirror is a choice
|
|
39
|
+
L10 on GitHub, every owner the code owners file names is one GitHub knows, read from GitHub's
|
|
40
|
+
own validation of the default branch's file (#382): an organisation by its bare name, a
|
|
41
|
+
deleted user or a team without access is no owner. Unread — a private repository and a token
|
|
42
|
+
without Contents: read — it is said, never counted
|
|
38
43
|
N1 information, never a gap (D91): a published version newer than the project's, read from
|
|
39
44
|
the registry — the one place a project learns of it. Elsewhere, only `nstack update` asks
|
|
40
45
|
it, whether the version it lays is published yet (D201)
|
|
@@ -59,6 +64,7 @@ Output: 0 when everything is verified and compliant; 1 when a setting is missin
|
|
|
59
64
|
from __future__ import annotations
|
|
60
65
|
|
|
61
66
|
import fnmatch
|
|
67
|
+
import http.client
|
|
62
68
|
import json
|
|
63
69
|
import os
|
|
64
70
|
import re
|
|
@@ -79,6 +85,7 @@ from napkinstack.project import ANSWERS
|
|
|
79
85
|
OK, GAP, UNKNOWN, NOT_APPLICABLE = "OK", "FAIL", "NOT VERIFIED", "NOT APPLICABLE"
|
|
80
86
|
SOURCES = "SOURCES" # a contributor's checkout holding the project's version: said, not a gap (D136)
|
|
81
87
|
OUT_OF_REACH = "OUT OF REACH" # the plan forbids it: a state, not a fault (PDR-0006)
|
|
88
|
+
NOT_READ = "NOT READ" # an optional read that did not answer: said, never counted (L10)
|
|
82
89
|
# The settings that make the forge refuse a merge. A repository is guarded when they are
|
|
83
90
|
# all in force; the others matter and none of them stops a merge.
|
|
84
91
|
BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13", "G21")
|
|
@@ -390,6 +397,40 @@ def _default_owner(root: Path) -> tuple[str, str]:
|
|
|
390
397
|
"its first rule: the code owner review then covers every path (.nstack/handbook/07-governance.md §7).")
|
|
391
398
|
|
|
392
399
|
|
|
400
|
+
SHOWN_ERRORS = 5 # lines of GitHub's validation said one by one; the rest counted
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def _owners_known(repo: str) -> tuple[str, str]:
|
|
404
|
+
"""L10: the ownership file as GitHub validates it on the default branch (#382). An owner GitHub
|
|
405
|
+
does not know — an organisation by its bare name, a deleted user, a team without access — is
|
|
406
|
+
no owner: the paths it names have none. GitHub's own reading, not a second one: no syntax check
|
|
407
|
+
tells a user from an organisation. Unread, it is said and counted neither as a gap nor as
|
|
408
|
+
not verified: the token doctor asks for reads settings, not contents."""
|
|
409
|
+
api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
|
|
410
|
+
token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
|
|
411
|
+
headers = {"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": API_VERSION,
|
|
412
|
+
"User-Agent": f"nstack/{__version__}"}
|
|
413
|
+
if token:
|
|
414
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
415
|
+
request = urllib.request.Request(f"{api}/repos/{repo}/codeowners/errors", headers=headers)
|
|
416
|
+
try:
|
|
417
|
+
with urllib.request.urlopen(request, timeout=10) as response:
|
|
418
|
+
errors = json.load(response)["errors"]
|
|
419
|
+
lines = [f"line {error['line']}: {error['kind']} — {str(error['source']).strip()}" for error in errors]
|
|
420
|
+
except (OSError, ValueError, KeyError, TypeError, http.client.HTTPException) as error:
|
|
421
|
+
said = f"HTTP {error.code}" if isinstance(error, urllib.error.HTTPError) else type(error).__name__
|
|
422
|
+
return NOT_READ, (f"Reason: GitHub's validation of the file did not answer ({said}): no file on the "
|
|
423
|
+
"default branch, or a private repository out of the token's reach.\nTo read it: a "
|
|
424
|
+
"token that may also read the repository's contents (Contents: read).")
|
|
425
|
+
if not lines:
|
|
426
|
+
return OK, ""
|
|
427
|
+
more = f"\n…and {len(lines) - SHOWN_ERRORS} more" if len(lines) > SHOWN_ERRORS else ""
|
|
428
|
+
return GAP, ("GitHub reads no valid owner on these lines of the default branch's file:\n"
|
|
429
|
+
+ "\n".join(lines[:SHOWN_ERRORS]) + more
|
|
430
|
+
+ "\nAction: name a user, or a team written organisation/team, with write access to the "
|
|
431
|
+
"repository — never an organisation by its name (.nstack/handbook/07-governance.md §7).")
|
|
432
|
+
|
|
433
|
+
|
|
393
434
|
def _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
|
|
394
435
|
"""L6 on `approval: agent`: no default owner, and every path a human must approve ends on a
|
|
395
436
|
rule with an owner (`owners.py`; in CI, rule M13)."""
|
|
@@ -522,14 +563,18 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
|
|
|
522
563
|
if answers.get("approval") == "agent" else "CODEOWNERS starts with a default owner",
|
|
523
564
|
*_default_owner(root)))
|
|
524
565
|
|
|
566
|
+
from napkinstack.project import forge, remote_forge, written_for
|
|
567
|
+
|
|
568
|
+
if forge(root) == "github":
|
|
569
|
+
results.append(("L10", "Every owner CODEOWNERS names is one GitHub knows",
|
|
570
|
+
*_owners_known(str(answers.get("github_repo") or ""))))
|
|
571
|
+
|
|
525
572
|
source = str(answers.get("_src_path") or "")
|
|
526
573
|
local = not REMOTE.match(source)
|
|
527
574
|
results.append(("L7", "Template source reachable by anyone", GAP if local else OK,
|
|
528
575
|
f"The project was generated from '{source}', a path on one machine: nobody else can "
|
|
529
576
|
"update it.\nAction: nstack update, from the published source." if local else ""))
|
|
530
577
|
|
|
531
|
-
from napkinstack.project import forge, remote_forge, written_for
|
|
532
|
-
|
|
533
578
|
name = forge(root)
|
|
534
579
|
written, remote = written_for(root), remote_forge(root)
|
|
535
580
|
if written is not None:
|
|
@@ -798,6 +843,8 @@ def run(root: Path) -> int:
|
|
|
798
843
|
suffix = f", {skipped} not applicable" if skipped else ""
|
|
799
844
|
if not gaps and not unknown:
|
|
800
845
|
reach = f"; {out_of_reach} setting(s) out of reach on this plan" if out_of_reach else ""
|
|
846
|
+
unread = [rule for rule, _, status, _ in results if status == NOT_READ]
|
|
847
|
+
reach += f"; {', '.join(unread)} not read" if unread else ""
|
|
801
848
|
print(f"\nnstack doctor: compliant{suffix}{reach}.")
|
|
802
849
|
return 0
|
|
803
850
|
print(f"\nnstack doctor: {gaps} gap(s), {unknown} not verified{suffix}.\nWorkflows inform; "
|
|
@@ -266,15 +266,34 @@ def prepare(root: Path, module: Path) -> Path | str:
|
|
|
266
266
|
|
|
267
267
|
|
|
268
268
|
HELD = "NSTACK_E2E_HELD" # set for what the run starts: an e2e inside an e2e waits for nothing
|
|
269
|
+
WAIT_SAID_EVERY = 60.0 # seconds between two lines of a run that waits: a long wait is never read as a hang (#402)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def sealed(manifest: Path) -> bool:
|
|
273
|
+
"""Whether the module declares its end-to-end run sealed, `evidence.sealed: true` (#402): its own
|
|
274
|
+
session, devices, ports, the files it writes and its processes, and timings that hold whatever the load
|
|
275
|
+
(#419) — nothing another run shares."""
|
|
276
|
+
try:
|
|
277
|
+
data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
|
|
278
|
+
except (OSError, yaml.YAMLError):
|
|
279
|
+
return False
|
|
280
|
+
section = data.get("evidence") if isinstance(data, dict) else None
|
|
281
|
+
return isinstance(section, dict) and section.get("sealed") is True
|
|
269
282
|
|
|
270
283
|
|
|
271
284
|
@contextlib.contextmanager
|
|
272
|
-
def one_at_a_time(root: Path, target: str):
|
|
285
|
+
def one_at_a_time(root: Path, target: str, is_sealed: bool = False):
|
|
273
286
|
"""One e2e at a time on this machine, for this user, whichever project or command starts it —
|
|
274
287
|
`nstack e2e`, or `nstack attest` through it: what an end-to-end run drives (a sound server, a
|
|
275
288
|
display, a port) is the machine's, and two runs reading it see each other's (#287). An advisory
|
|
276
289
|
lock, `flock(2)`, released by the system when the holder exits however it exits; the one that
|
|
277
|
-
waits says for whom.
|
|
290
|
+
waits says for whom, and again every WAIT_SAID_EVERY seconds. A sealed run shares nothing of the
|
|
291
|
+
machine's: it neither waits nor holds the lock (#402)."""
|
|
292
|
+
if is_sealed:
|
|
293
|
+
print(f"-> {target}: sealed (evidence.sealed): runs beside any other end-to-end run on this machine",
|
|
294
|
+
flush=True)
|
|
295
|
+
yield
|
|
296
|
+
return
|
|
278
297
|
try:
|
|
279
298
|
import fcntl
|
|
280
299
|
except ImportError: # no flock on this system: the runs are not kept apart
|
|
@@ -299,7 +318,19 @@ def one_at_a_time(root: Path, target: str):
|
|
|
299
318
|
handle.seek(0)
|
|
300
319
|
holder = handle.read().strip() or "another run"
|
|
301
320
|
print(f"-> {target}: waits for the end-to-end run already on this machine — {holder}", flush=True)
|
|
302
|
-
|
|
321
|
+
began = said = time.monotonic()
|
|
322
|
+
while True:
|
|
323
|
+
try:
|
|
324
|
+
fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
325
|
+
break
|
|
326
|
+
except BlockingIOError:
|
|
327
|
+
time.sleep(min(1.0, WAIT_SAID_EVERY / 3))
|
|
328
|
+
if time.monotonic() - said >= WAIT_SAID_EVERY:
|
|
329
|
+
said = time.monotonic()
|
|
330
|
+
handle.seek(0)
|
|
331
|
+
holder = handle.read().strip() or holder
|
|
332
|
+
print(f"-> {target}: still waits for the end-to-end run already on this machine, "
|
|
333
|
+
f"{int(said - began) // 60} min {int(said - began) % 60} s so far — {holder}", flush=True)
|
|
303
334
|
handle.seek(0)
|
|
304
335
|
handle.truncate()
|
|
305
336
|
started = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
|
|
@@ -385,7 +385,7 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
|
|
|
385
385
|
continue # absent, or not a mapping: M2 says it
|
|
386
386
|
name, at = manifest.parent.name, f"{manifest.relative_to(root).as_posix()}:{line_of(text, 'evidence')}"
|
|
387
387
|
action = " Action: evidence.provoked — a list of {pattern, level: warning|error, scenario} (.nstack/playbooks/tests.md)."
|
|
388
|
-
for key in sorted(set(section) - {"provoked", "levels"}):
|
|
388
|
+
for key in sorted(set(section) - {"provoked", "levels", "sealed"}):
|
|
389
389
|
fail(name, "M12", f"evidence has an unknown key '{key}': it declares nothing.\n{action}", at)
|
|
390
390
|
provoked = section.get("provoked", [])
|
|
391
391
|
if not isinstance(provoked, list):
|
|
@@ -410,6 +410,11 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
|
|
|
410
410
|
fail(name, "M12", f"level {item['level']!r}: warning or error.\n{action}", at)
|
|
411
411
|
if not isinstance(item["scenario"], str) or not item["scenario"].strip():
|
|
412
412
|
fail(name, "M12", f"the declaration of {item['pattern']!r} names no scenario: say which provokes it.\n{action}", at)
|
|
413
|
+
if "sealed" in section and not isinstance(section["sealed"], bool):
|
|
414
|
+
fail(name, "M12", "evidence.sealed must be true or false: true when the module's end-to-end run shares "
|
|
415
|
+
"nothing with another run — session, devices, ports, files it writes, processes — and "
|
|
416
|
+
"passes whatever the machine's load.\n Action: evidence.sealed: true or false, or no key: the run then waits "
|
|
417
|
+
"its turn (.nstack/playbooks/tests.md).", at)
|
|
413
418
|
if "levels" in section and not isinstance(section["levels"], str):
|
|
414
419
|
fail(name, "M12", "evidence.levels must be text, a regular expression.\n"
|
|
415
420
|
" Action: an expression whose group named level captures the line's level word.", at)
|
|
@@ -9,7 +9,7 @@ Rules:
|
|
|
9
9
|
C1 front matter readable: a YAML mapping at the top of the file
|
|
10
10
|
C2 charter: status proposed or accepted, a decider who is one named person, at least
|
|
11
11
|
one success criterion
|
|
12
|
-
C3 cycle: a goal, a known status, appetite_weeks, start and end, end = start + appetite;
|
|
12
|
+
C3 cycle: a goal, a known status, appetite_weeks or appetite_days, start and end, end = start + appetite;
|
|
13
13
|
accepted_on, when written, a date: the next cycle's acceptance while another runs
|
|
14
14
|
C4 deliverables: ids D1, D2… unique, a title, a known state, acceptance criteria once ready
|
|
15
15
|
C5 at most one accepted cycle, and only under an accepted charter
|
|
@@ -621,6 +621,9 @@ def _check_success(path: Path, data: dict, status, numbers: list[int] | None, fa
|
|
|
621
621
|
fail("C6", path, f"{where}: observing since when? {action}")
|
|
622
622
|
|
|
623
623
|
|
|
624
|
+
APPETITES = {"appetite_weeks": "weeks", "appetite_days": "days"} # a cycle's key, and its unit
|
|
625
|
+
|
|
626
|
+
|
|
624
627
|
def _check_cycle(path: Path, fail, numbers: list[int] | None = None) -> str | None:
|
|
625
628
|
data, reason = read_front_matter(path)
|
|
626
629
|
if data is None:
|
|
@@ -631,16 +634,25 @@ def _check_cycle(path: Path, fail, numbers: list[int] | None = None) -> str | No
|
|
|
631
634
|
status = data.get("status")
|
|
632
635
|
if not one_of(status, CYCLE_STATUSES):
|
|
633
636
|
fail("C3", path, f"status '{status}': expected one of {sorted(CYCLE_STATUSES)}")
|
|
634
|
-
weeks
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
637
|
+
# The appetite in weeks, or in days for an engagement shorter than one (#370): one or the
|
|
638
|
+
# other, never both — one decision, and the one date it sets.
|
|
639
|
+
given = [unit for unit in APPETITES if data.get(unit) is not None] # a key left empty is no appetite
|
|
640
|
+
unit = given[0] if len(given) == 1 else None
|
|
641
|
+
amount = data.get(unit) if unit else None
|
|
642
|
+
if len(given) > 1:
|
|
643
|
+
fail("C3", path, "appetite_weeks and appetite_days both set: the appetite is one decision.\n"
|
|
644
|
+
" Action: keep one — appetite_days for a cycle shorter than a week")
|
|
645
|
+
amount = None
|
|
646
|
+
elif isinstance(amount, bool) or not isinstance(amount, int) or amount < 1:
|
|
647
|
+
fail("C3", path, "appetite_weeks, or appetite_days for a cycle counted in days: a whole number of at "
|
|
648
|
+
"least 1, decided rather than estimated")
|
|
649
|
+
amount = None
|
|
638
650
|
start, end = as_date(data.get("start")), as_date(data.get("end"))
|
|
639
651
|
if start is None or end is None:
|
|
640
652
|
fail("C3", path, "start and end: dates, YYYY-MM-DD")
|
|
641
|
-
elif
|
|
642
|
-
fail("C3", path, f"end {end}: the appetite sets it, start + {
|
|
643
|
-
f"{start + datetime.timedelta(
|
|
653
|
+
elif amount is not None and end != start + datetime.timedelta(**{APPETITES[unit]: amount}):
|
|
654
|
+
fail("C3", path, f"end {end}: the appetite sets it, start + {amount} {APPETITES[unit][:-1]}(s) = "
|
|
655
|
+
f"{start + datetime.timedelta(**{APPETITES[unit]: amount})}")
|
|
644
656
|
if "accepted_on" in data and as_date(data.get("accepted_on")) is None:
|
|
645
657
|
fail("C3", path, "accepted_on: the day the decider accepted this cycle, YYYY-MM-DD")
|
|
646
658
|
_check_deliverables(path, data.get("deliverables"), fail)
|
|
@@ -20,7 +20,7 @@ from pathlib import Path
|
|
|
20
20
|
import yaml
|
|
21
21
|
|
|
22
22
|
from napkinstack import assurance
|
|
23
|
-
from napkinstack.project import answer, forge, ownership
|
|
23
|
+
from napkinstack.project import answer, forge, organisation_owner, ownership
|
|
24
24
|
from napkinstack.fitness.manifests import (changed_files, contract_entries, find_manifests,
|
|
25
25
|
module_content)
|
|
26
26
|
|
|
@@ -73,6 +73,8 @@ def create(root: Path, name: str, owner: str, criticality: str, user_facing: boo
|
|
|
73
73
|
"GitLab group/subgroup off GitHub — or a user when the project has no organisation, for "
|
|
74
74
|
"example acme/billing (CODEOWNERS, .nstack/handbook/07-governance.md §7).")
|
|
75
75
|
return 1
|
|
76
|
+
if forge(root) == "github" and organisation_owner(owner, "new-module", f"{owner}/<team>"):
|
|
77
|
+
return 1
|
|
76
78
|
folder = root / "modules" / name
|
|
77
79
|
if folder.exists():
|
|
78
80
|
print(f"FAIL [new-module] modules/{name} already exists.")
|
|
@@ -160,18 +162,20 @@ def create_contract(root: Path, name: str, owner: str | None = None) -> int:
|
|
|
160
162
|
except (OSError, yaml.YAMLError):
|
|
161
163
|
answers = {}
|
|
162
164
|
owner = owner or str(answers.get("owner_team") or "")
|
|
163
|
-
|
|
165
|
+
module, folder = root / "contracts", root / "contracts" / name
|
|
166
|
+
created = not (module / "MANIFEST.yaml").is_file() # the owner is written only with the module
|
|
167
|
+
if created and not owner_valid(root, owner):
|
|
164
168
|
print(f"FAIL [new-contract] no valid owner for the contracts module ('{owner}').\n"
|
|
165
169
|
" Action: pass --owner organisation/team — a boundary is never orphaned "
|
|
166
170
|
"(.nstack/handbook/03-contracts.md §2).")
|
|
167
171
|
return 1
|
|
168
|
-
|
|
172
|
+
if created and forge(root) == "github" and organisation_owner(owner, "new-contract", f"--owner {owner}/<team>"):
|
|
173
|
+
return 1
|
|
169
174
|
if folder.exists():
|
|
170
175
|
print(f"FAIL [new-contract] contracts/{name} already exists.\n Action: a change to it is a new "
|
|
171
176
|
"version beside the first, never an edit of it (.nstack/handbook/03-contracts.md §4).")
|
|
172
177
|
return 1
|
|
173
178
|
|
|
174
|
-
created = not (module / "MANIFEST.yaml").is_file()
|
|
175
179
|
if created:
|
|
176
180
|
shutil.copytree(CONTRACTS, module, dirs_exist_ok=True)
|
|
177
181
|
# The contact: the project's discussions on GitHub; elsewhere, the module's owner (ADR-0010).
|
|
@@ -392,13 +396,17 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
|
|
|
392
396
|
# Its evidence: a folder of its own, its output kept, its logs read after (ADR-0009).
|
|
393
397
|
from napkinstack import evidence
|
|
394
398
|
|
|
395
|
-
|
|
399
|
+
sealed = evidence.sealed(manifest)
|
|
400
|
+
# HELD says an ancestor holds the machine: a sealed run holds nothing, so what it starts
|
|
401
|
+
# does not inherit it — a run it nests waits as any other would (#402).
|
|
402
|
+
held_for_children = {} if sealed else {evidence.HELD: "1"}
|
|
403
|
+
with evidence.one_at_a_time(root, target, is_sealed=sealed):
|
|
396
404
|
folder = evidence.prepare(root, known[target])
|
|
397
405
|
if isinstance(folder, str):
|
|
398
406
|
print(f"FAIL [e2e] module '{target}': {folder}")
|
|
399
407
|
return 1
|
|
400
408
|
print(f"-> {target}: {command}", flush=True)
|
|
401
|
-
code, held = evidence.run(command, known[target], {**os.environ,
|
|
409
|
+
code, held = evidence.run(command, known[target], {**os.environ, **held_for_children,
|
|
402
410
|
"NSTACK_EVIDENCE": str(folder.resolve())}, folder)
|
|
403
411
|
passed = evidence.finish(root, target, known[target], folder, code, held)
|
|
404
412
|
if code == evidence.NOT_RUN and passed:
|
|
@@ -12,11 +12,14 @@ hook and CI reject any remaining marker.
|
|
|
12
12
|
|
|
13
13
|
from __future__ import annotations
|
|
14
14
|
|
|
15
|
+
import json
|
|
15
16
|
import os
|
|
16
17
|
import re
|
|
17
18
|
import subprocess
|
|
18
19
|
import sys
|
|
19
20
|
import tempfile
|
|
21
|
+
import urllib.parse
|
|
22
|
+
import urllib.request
|
|
20
23
|
from pathlib import Path
|
|
21
24
|
|
|
22
25
|
import yaml
|
|
@@ -30,6 +33,47 @@ DOWNGRADE = re.compile(r"You are downgrading from (\S+) to (\S+)\.")
|
|
|
30
33
|
GITHUB = re.compile(r"^(?:https://github\.com/|git@github\.com:|gh:)(?P<repo>[^/]+/[^/]+?)(?:\.git)?/?$")
|
|
31
34
|
|
|
32
35
|
|
|
36
|
+
def organisation_owner(owner: str, command: str, instead: str) -> bool:
|
|
37
|
+
"""True, with the refusal printed, when a bare handle written as a code owner on GitHub names an
|
|
38
|
+
organisation (#382): GitHub takes a user, or a team as organisation/team — never an organisation
|
|
39
|
+
by its name, and every CODEOWNERS line naming it would have no valid owner. A team needs no
|
|
40
|
+
asking; a forge that does not answer lets the owner pass, said: `nstack doctor` reads the file as
|
|
41
|
+
GitHub validates it (L10). A token is sent when there is one: a server in private mode answers
|
|
42
|
+
no one without it."""
|
|
43
|
+
import http.client
|
|
44
|
+
import urllib.error
|
|
45
|
+
|
|
46
|
+
if "/" in owner:
|
|
47
|
+
return False
|
|
48
|
+
api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
|
|
49
|
+
headers = {"Accept": "application/vnd.github+json", "User-Agent": f"nstack/{__version__}"}
|
|
50
|
+
if token := os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN"):
|
|
51
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
52
|
+
request = urllib.request.Request(f"{api}/users/{urllib.parse.quote(owner, safe='')}", headers=headers)
|
|
53
|
+
try:
|
|
54
|
+
with urllib.request.urlopen(request, timeout=5) as response:
|
|
55
|
+
kind = (json.load(response) or {}).get("type")
|
|
56
|
+
except urllib.error.HTTPError as error:
|
|
57
|
+
kind = "unknown" if error.code == 404 else None
|
|
58
|
+
except (OSError, ValueError, AttributeError, http.client.HTTPException):
|
|
59
|
+
kind = None
|
|
60
|
+
if kind == "unknown":
|
|
61
|
+
print(f"NOTE [{command}] GitHub knows no user or organisation '{owner}': written as given — check the "
|
|
62
|
+
"spelling; nstack doctor reads the file as GitHub validates it.")
|
|
63
|
+
return False
|
|
64
|
+
if kind == "Organization":
|
|
65
|
+
print(f"FAIL [{command}] '{owner}' is an organisation: GitHub takes as a code owner a user, or a team "
|
|
66
|
+
f"written organisation/team — never an organisation by its name. Every CODEOWNERS line naming "
|
|
67
|
+
f"it would name no valid owner.\n Action: pass {instead} — a team of {owner} with write "
|
|
68
|
+
"access to the repository — or a user (.nstack/handbook/07-governance.md §7).")
|
|
69
|
+
return True
|
|
70
|
+
if kind is None:
|
|
71
|
+
print(f"NOTE [{command}] GitHub did not say what '{owner}' names: written as given. A code owner is a "
|
|
72
|
+
"user or organisation/team, never an organisation's name; nstack doctor reads the file as GitHub "
|
|
73
|
+
"validates it.")
|
|
74
|
+
return False
|
|
75
|
+
|
|
76
|
+
|
|
33
77
|
def default_ref() -> str:
|
|
34
78
|
"""The skeleton of the engine version: they move up together (PDR-0001 R2)."""
|
|
35
79
|
return f"v{__version__}"
|
|
@@ -233,6 +277,11 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
|
|
|
233
277
|
# Not asked at init (Copier would ask): a project on GitHub starts on its CI; elsewhere no CI
|
|
234
278
|
# is shipped, and its checks are attested (PDR-0018) — settled after the copy when the forge
|
|
235
279
|
# was asked by Copier itself.
|
|
280
|
+
# Asked by Copier instead — the owner, or the forge —, the owner is read by nstack doctor (L10):
|
|
281
|
+
# a prompt cannot ask the forge.
|
|
282
|
+
owner = str(data.get("owner_team") or "")
|
|
283
|
+
if data.get("forge") == "github" and owner and organisation_owner(owner, "init", f"--owner-team {owner}/<team>"):
|
|
284
|
+
return 1
|
|
236
285
|
data.setdefault("checks", "forge" if named == "github" else "attested")
|
|
237
286
|
data.setdefault("hold_days", 7) # a hold goes stale after a week without work (ADR-0007)
|
|
238
287
|
data.setdefault("approval", "human") # a code owner approves, until the decider says otherwise (PDR-0021)
|
|
@@ -32,7 +32,9 @@ The out-of-cycle label lifts K1 to K3 and K5, visibly and countably (.nstack/han
|
|
|
32
32
|
|
|
33
33
|
Usage : nstack pr-check [--root ROOT] [--base BASE] [--body-file FILE] [--labels a,b]
|
|
34
34
|
In CI : PR_BODY, PR_LABELS, PR_HEAD_SHA and PR_AUTHOR come from the pull_request event;
|
|
35
|
-
--labels, when given, takes the place of PR_LABELS, as for nstack attest.
|
|
35
|
+
--labels, when given, takes the place of PR_LABELS, as for nstack attest. Elsewhere, with
|
|
36
|
+
a token and one open pull request at the head, its own labels are read, and a label
|
|
37
|
+
given that it does not carry is refused (#368).
|
|
36
38
|
|
|
37
39
|
The verifier (T2) is a person, `@handle`, or an agent session, `session <id>`. The change's
|
|
38
40
|
authors are the pull request's author, the GitHub accounts behind its commits' authors,
|
|
@@ -276,11 +278,10 @@ TRACES = """query($owner: String!, $name: String!, $number: Int!) {
|
|
|
276
278
|
userContentEdits(first: 100) { totalCount nodes { editor { login } } } } } }"""
|
|
277
279
|
|
|
278
280
|
|
|
279
|
-
def
|
|
280
|
-
"""The
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
judged on the forge's run, which an edit of the description starts again."""
|
|
281
|
+
def _pull_request(root: Path, query: str) -> dict | str | None:
|
|
282
|
+
"""The pull request as one GraphQL query reads it; why it is not read; None with no pull
|
|
283
|
+
request number, on a workstation, and while `nstack attest` records the head: what the forge
|
|
284
|
+
holds is judged on the forge's own run."""
|
|
284
285
|
number = os.environ.get("PR_NUMBER", "").strip()
|
|
285
286
|
if not re.fullmatch(r"[0-9]+", number) or os.environ.get("NSTACK_ATTESTING"):
|
|
286
287
|
return None
|
|
@@ -291,7 +292,7 @@ def traces(root: Path) -> set[str] | str | None:
|
|
|
291
292
|
owner, name = repository.split("/", 1)
|
|
292
293
|
request = urllib.request.Request(
|
|
293
294
|
os.environ.get("GITHUB_GRAPHQL_URL") or "https://api.github.com/graphql",
|
|
294
|
-
data=json.dumps({"query":
|
|
295
|
+
data=json.dumps({"query": query, "variables": {"owner": owner, "name": name, "number": int(number)}}).encode(),
|
|
295
296
|
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", "User-Agent": "nstack"})
|
|
296
297
|
try:
|
|
297
298
|
with urllib.request.urlopen(request, timeout=10) as response:
|
|
@@ -299,16 +300,85 @@ def traces(root: Path) -> set[str] | str | None:
|
|
|
299
300
|
if answer.get("errors"): # a field refused leaves the rest of the answer partial
|
|
300
301
|
return f"the forge refused part of the query ({answer['errors'][0].get('type', 'error')})"
|
|
301
302
|
found = answer["data"]["repository"]["pullRequest"]
|
|
303
|
+
return found if isinstance(found, dict) else "the forge did not answer (no pull request)"
|
|
304
|
+
except (OSError, ValueError, KeyError, TypeError, AttributeError, IndexError) as error:
|
|
305
|
+
return f"the forge did not answer ({type(error).__name__})"
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def traces(root: Path) -> set[str] | str | None:
|
|
309
|
+
"""The accounts whose hand is on the pull request — its description's editors, its reviewers,
|
|
310
|
+
its commenters —, lower case and without `[bot]`; why they are not read; None where the pull
|
|
311
|
+
request is not read (`_pull_request`): the hand is judged on the forge's run, which an edit of
|
|
312
|
+
the description starts again."""
|
|
313
|
+
found = _pull_request(root, TRACES)
|
|
314
|
+
if not isinstance(found, dict):
|
|
315
|
+
return found
|
|
316
|
+
try:
|
|
302
317
|
hands = [(found[kind], key) for kind, key in (("reviews", "author"), ("comments", "author"),
|
|
303
318
|
("userContentEdits", "editor"))]
|
|
304
319
|
if any(connection["totalCount"] > len(connection["nodes"]) for connection, _ in hands):
|
|
305
320
|
return "more traces than one page"
|
|
306
321
|
return {node[key]["login"].lower().removesuffix("[bot]") for connection, key in hands
|
|
307
322
|
for node in connection["nodes"] if node and node.get(key)}
|
|
308
|
-
except (
|
|
323
|
+
except (KeyError, TypeError, AttributeError) as error:
|
|
309
324
|
return f"the forge did not answer ({type(error).__name__})"
|
|
310
325
|
|
|
311
326
|
|
|
327
|
+
# Each reviewer's latest review that approved or asked for changes: a dismissed one is not APPROVED,
|
|
328
|
+
# so where the forge dismisses stale approvals (G13) none is ever read here as covering the head.
|
|
329
|
+
APPROVALS = """query($owner: String!, $name: String!, $number: Int!) {
|
|
330
|
+
repository(owner: $owner, name: $name) { pullRequest(number: $number) {
|
|
331
|
+
latestOpinionatedReviews(first: 100) { totalCount nodes { state author { login } commit { oid } } } } } }"""
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
def approvals(root: Path) -> list[tuple[str, str]] | str | None:
|
|
335
|
+
"""Each approving reviewer's login and the commit their approval was given on; why they are not
|
|
336
|
+
read; None where the pull request is not read (`_pull_request`)."""
|
|
337
|
+
found = _pull_request(root, APPROVALS)
|
|
338
|
+
if not isinstance(found, dict):
|
|
339
|
+
return found
|
|
340
|
+
try:
|
|
341
|
+
reviews = found["latestOpinionatedReviews"]
|
|
342
|
+
if reviews["totalCount"] > len(reviews["nodes"]):
|
|
343
|
+
return "more reviewers than one page"
|
|
344
|
+
return [(node["author"]["login"] if node.get("author") else "a deleted account",
|
|
345
|
+
str((node.get("commit") or {}).get("oid") or "").lower())
|
|
346
|
+
for node in reviews["nodes"] if node and node.get("state") == "APPROVED"]
|
|
347
|
+
except (KeyError, TypeError, AttributeError) as error:
|
|
348
|
+
return f"the forge did not answer ({type(error).__name__})"
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def check_approvals(root: Path, base: str, head: str, found: list[tuple[str, str]] | str | None,
|
|
352
|
+
warn: Callable[[str], None]) -> None:
|
|
353
|
+
"""R1 (#377): where the forge keeps an approval once new commits are pushed — no ruleset, or
|
|
354
|
+
stale approvals not dismissed —, "approved" no longer says the head was read. An approval on
|
|
355
|
+
an earlier commit covers the head when only the base branch was merged in since; otherwise it
|
|
356
|
+
is said, with whom and which commits. A warning, never a failure: a review starts no run (D218),
|
|
357
|
+
so a check failed on it would stay red after the approver read the head and approved again."""
|
|
358
|
+
if isinstance(found, str):
|
|
359
|
+
warn(f"[R1] whether each approval covers the head is not read: {found}.")
|
|
360
|
+
return
|
|
361
|
+
for login, commit in found or []:
|
|
362
|
+
if commit == head:
|
|
363
|
+
continue
|
|
364
|
+
known = bool(commit) and not _git(root, "merge-base", "--is-ancestor", commit, head).returncode
|
|
365
|
+
since = _git(root, "rev-list", f"{commit}..{head}", f"^{base}").stdout.split() if known else []
|
|
366
|
+
# A merge counts when it carries content of its own — a conflict resolved, an edit made
|
|
367
|
+
# while merging —: what a clean merge of the base would not have written.
|
|
368
|
+
since = [one for one in since if _git(root, "rev-list", "--no-walk", "--merges", one).stdout.strip() == ""
|
|
369
|
+
or _git(root, "show", "--remerge-diff", "--format=", one).stdout.strip()]
|
|
370
|
+
if known and not since:
|
|
371
|
+
continue # only the base branch merged in: nothing the approver has not read
|
|
372
|
+
what = (f"{len(since)} commit(s) pushed since" if known
|
|
373
|
+
else "a commit this branch does not hold — rewritten since, or not found here")
|
|
374
|
+
line = (f"[R1] @{login} approved {commit[:7] or 'an unknown commit'}, not the head {head[:7]}, at this run: "
|
|
375
|
+
f"{what}, which the approval does not cover.")
|
|
376
|
+
warn(f"{line}\n Action: @{login} reads them and approves again before the merge; where the forge "
|
|
377
|
+
"dismisses stale approvals on push, it does this itself (.nstack/handbook/07-governance.md §7).")
|
|
378
|
+
if os.environ.get("GITHUB_ACTIONS") == "true": # seen on the check, not only in its log
|
|
379
|
+
print(f"::warning title=R1 approval behind the head::{line.removeprefix('[R1] ')}")
|
|
380
|
+
|
|
381
|
+
|
|
312
382
|
def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str]], fail: Fail,
|
|
313
383
|
hands: set[str] | None = None) -> None:
|
|
314
384
|
"""T2: the verifier is named — people as @handle anywhere on the line, an agent session as
|
|
@@ -360,7 +430,7 @@ def _split(row: dict, width: int) -> bool:
|
|
|
360
430
|
def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
|
|
361
431
|
authorship: tuple[set[str], set[str], list[str]] = (set(), set(), []),
|
|
362
432
|
strict: bool = False, unchanged: Callable[[str], bool] = lambda commit: False,
|
|
363
|
-
hands: set[str] | None = None) -> list[str]:
|
|
433
|
+
hands: set[str] | None = None, same_inputs: Callable[[str], bool] = lambda commit: False) -> list[str]:
|
|
364
434
|
"""T1 to T5; returns the human-only scenarios, listed apart for the approver."""
|
|
365
435
|
verifier, header, rows = read_sheet(body)
|
|
366
436
|
if reasons and not rows:
|
|
@@ -416,7 +486,9 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
|
|
|
416
486
|
# joins an earlier one after a `;`, never replacing it (#288).
|
|
417
487
|
confirmed = [clause.strip().split(" ", 1)[0].strip("`").lower()
|
|
418
488
|
for clause in row.get(CONFIRMED, "").split(";")]
|
|
419
|
-
if kind.lower() == "automated"
|
|
489
|
+
if kind.lower() == "automated" and not strict and same_inputs(commit):
|
|
490
|
+
pass # what its module reads is unchanged since that run, and the run is fresh (D223)
|
|
491
|
+
elif kind.lower() == "automated" or strict:
|
|
420
492
|
rerun.append(ident)
|
|
421
493
|
elif not any(SHA.fullmatch(commit) and head.startswith(commit) for commit in confirmed):
|
|
422
494
|
unconfirmed.append(ident)
|
|
@@ -490,8 +562,8 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
|
|
|
490
562
|
fail("K3", f"no deliverable named.\n Action: \"Deliverable: D<n>\" in the description, "
|
|
491
563
|
f"a deliverable of {path.name}."
|
|
492
564
|
+ ("" if labels else f"\n This run read no label. If the pull request is out of cycle, it "
|
|
493
|
-
f"carries the {LABEL} label
|
|
494
|
-
"
|
|
565
|
+
f"carries the {LABEL} label, put on the pull request: a run on a workstation reads it there "
|
|
566
|
+
f"with a token, or is given it with --labels {LABEL} (or PR_LABELS)."))
|
|
495
567
|
elif match[1] not in states:
|
|
496
568
|
fail("K3", f"deliverable {match[1]} is not in {path.name}.\n Action: name one of "
|
|
497
569
|
f"{', '.join(states) or 'its deliverables'}, or re-frame the cycle with the decider.")
|
|
@@ -631,6 +703,51 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
|
|
|
631
703
|
"description; restore it from the description's history otherwise.")
|
|
632
704
|
|
|
633
705
|
|
|
706
|
+
def _pull_labels(root: Path, head: str) -> tuple[int, set[str]] | str | None:
|
|
707
|
+
"""The open pull request whose head is `head`, and its labels, read on the forge (#368); why not,
|
|
708
|
+
when it was asked; None when nothing is asked: off GitHub or without a token, and where the
|
|
709
|
+
labels given are already the pull request's — the forge's own run, and the checks nstack attest
|
|
710
|
+
runs with the labels it read."""
|
|
711
|
+
if os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("NSTACK_ATTESTING") == head:
|
|
712
|
+
return None
|
|
713
|
+
from napkinstack import attest, hold
|
|
714
|
+
|
|
715
|
+
forge = hold._forge(root, attest._remote(root) or "origin")
|
|
716
|
+
if forge is None:
|
|
717
|
+
return None
|
|
718
|
+
try:
|
|
719
|
+
answer = hold._call(forge, "GET", f"/commits/{head}/pulls")
|
|
720
|
+
except hold.Refused as error:
|
|
721
|
+
return str(error)
|
|
722
|
+
pulls = [pull for pull in answer if isinstance(pull, dict) and pull.get("state") == "open"
|
|
723
|
+
and isinstance(pull.get("head"), dict) and pull["head"].get("sha") == head] if isinstance(answer, list) else []
|
|
724
|
+
if len(pulls) != 1:
|
|
725
|
+
return "no open pull request has this head" if not pulls else f"{len(pulls)} open pull requests have this head"
|
|
726
|
+
names = {str(label["name"]) for label in pulls[0].get("labels") or [] if isinstance(label, dict) and label.get("name")}
|
|
727
|
+
return int(pulls[0].get("number") or 0), names
|
|
728
|
+
|
|
729
|
+
|
|
730
|
+
def labels_for(root: Path, head: str, given: str) -> tuple[set[str], str, str | None]:
|
|
731
|
+
"""The labels judged, where they come from, and a refusal: the pull request's own when it is read
|
|
732
|
+
— a label given that it does not carry is refused, since a label is what the reviewer sees on the
|
|
733
|
+
forge (#368); else the ones given, said as the caller's."""
|
|
734
|
+
named = {label.strip() for label in given.split(",") if label.strip()}
|
|
735
|
+
found = _pull_labels(root, head)
|
|
736
|
+
if isinstance(found, tuple):
|
|
737
|
+
number, carried = found
|
|
738
|
+
if extra := sorted(name for name in named if name.lower() not in {label.lower() for label in carried}):
|
|
739
|
+
return named, "", (f"pull request #{number} carries no label {', '.join(extra)}: a label is judged as the "
|
|
740
|
+
f"reviewer sees it on the forge.\n Action: put it on pull request #{number}, or "
|
|
741
|
+
"run without --labels and with PR_LABELS unset: the pull request's own are read.")
|
|
742
|
+
return carried, f"read from pull request #{number}", None
|
|
743
|
+
if os.environ.get("GITHUB_ACTIONS") == "true":
|
|
744
|
+
return named, "the pull request event's", None
|
|
745
|
+
if os.environ.get("NSTACK_ATTESTING") == head:
|
|
746
|
+
return named, "as nstack attest read them", None
|
|
747
|
+
return named, ("given by the caller (--labels, PR_LABELS)" if named else "none given") + (
|
|
748
|
+
f" — the pull request's not read: {found}" if found else ""), None
|
|
749
|
+
|
|
750
|
+
|
|
634
751
|
def status_required(root: Path) -> bool:
|
|
635
752
|
"""Whether the base branch's rules require the record's own status, `nstack / local checks`
|
|
636
753
|
(D221, #399): read on the forge's run only, from the rules that apply to the branch — readable
|
|
@@ -660,6 +777,50 @@ def status_required(root: Path) -> bool:
|
|
|
660
777
|
for rule in rules if isinstance(rules, list))
|
|
661
778
|
|
|
662
779
|
|
|
780
|
+
def _module_inputs(record: dict | None) -> tuple[str, str, str | None] | None:
|
|
781
|
+
"""A record's `Module checks` digest, its first run's time and base (ADR-0006, D223)."""
|
|
782
|
+
checks = record.get("checks") if isinstance(record, dict) and isinstance(record.get("checks"), list) else []
|
|
783
|
+
found = next((c for c in checks if isinstance(c, dict) and c.get("name") == "Module checks"), None)
|
|
784
|
+
if not found or found.get("passed") is not True or not found.get("inputs"):
|
|
785
|
+
return None
|
|
786
|
+
return str(found["inputs"]), str(found.get("kept_from") or record.get("at", "")), \
|
|
787
|
+
found.get("kept_base") or record.get("base_commit")
|
|
788
|
+
|
|
789
|
+
|
|
790
|
+
def same_inputs(root: Path, head: str, base: str) -> Callable[[str], bool]:
|
|
791
|
+
"""T4's relief for an automated row (D223): the record of the row's commit and the head's hold
|
|
792
|
+
the same inputs digest, and the row's run is fresh. While nstack attest makes the head's record,
|
|
793
|
+
the digest it computed stands in for it."""
|
|
794
|
+
from napkinstack import attest
|
|
795
|
+
|
|
796
|
+
try:
|
|
797
|
+
answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
|
|
798
|
+
except (OSError, yaml.YAMLError):
|
|
799
|
+
answers = {}
|
|
800
|
+
if not isinstance(answers, dict) or answers.get("checks") != "attested":
|
|
801
|
+
return lambda commit: False # the forge's CI replays it: the relief is for attested checks
|
|
802
|
+
cache: dict[str, str | None] = {}
|
|
803
|
+
|
|
804
|
+
def head_digest() -> str | None:
|
|
805
|
+
if "head" not in cache:
|
|
806
|
+
if os.environ.get("NSTACK_ATTESTING") == head:
|
|
807
|
+
cache["head"] = os.environ.get("NSTACK_INPUTS") or None
|
|
808
|
+
else:
|
|
809
|
+
attest.read_remote(root)
|
|
810
|
+
found = _module_inputs(attest.latest(root, head))
|
|
811
|
+
cache["head"] = found[0] if found else None
|
|
812
|
+
return cache["head"]
|
|
813
|
+
|
|
814
|
+
def same(commit: str) -> bool:
|
|
815
|
+
full = _git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}").stdout.strip()
|
|
816
|
+
digest = head_digest()
|
|
817
|
+
found = _module_inputs(attest.latest(root, full)) if full and digest else None
|
|
818
|
+
base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}").stdout.strip() or None
|
|
819
|
+
return bool(found and found[0] == digest and attest._fresh(root, found[1], found[2], base_commit))
|
|
820
|
+
|
|
821
|
+
return same
|
|
822
|
+
|
|
823
|
+
|
|
663
824
|
def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> str:
|
|
664
825
|
"""Where the checks are judged, as the decider's answer `checks` says (A1, A2): on the forge's
|
|
665
826
|
CI, or attested on a workstation by `nstack attest` — then a complete, passed record of the
|
|
@@ -738,7 +899,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
|
|
|
738
899
|
modules = touched_modules(root, fork, files)
|
|
739
900
|
# The option, else PR_LABELS: one way for pr-check and attest alike (D147).
|
|
740
901
|
given = os.environ.get("PR_LABELS", "") if labels_given is None else labels_given
|
|
741
|
-
labels
|
|
902
|
+
labels, labels_from, refused = labels_for(root, head, given)
|
|
742
903
|
|
|
743
904
|
failures: list[str] = []
|
|
744
905
|
warnings = charter_without_pdr(root, base, files)
|
|
@@ -746,6 +907,9 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
|
|
|
746
907
|
def fail(rule: str, message: str) -> None:
|
|
747
908
|
failures.append(f"[{rule}] {message}")
|
|
748
909
|
|
|
910
|
+
if refused:
|
|
911
|
+
fail("labels", refused)
|
|
912
|
+
|
|
749
913
|
reasons = [reason for folder, found in modules.items() if (reason := sheet_reason(folder, found))]
|
|
750
914
|
authorship = authors(root, base, head, os.environ.get("PR_AUTHOR", ""))
|
|
751
915
|
# A commit whose tree is the head's is the head, for a sheet (D93): merging the default
|
|
@@ -764,11 +928,13 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
|
|
|
764
928
|
f"request is not read: {hands}.")
|
|
765
929
|
human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules),
|
|
766
930
|
lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head),
|
|
767
|
-
hands if isinstance(hands, set) else None) if carried else []
|
|
931
|
+
hands if isinstance(hands, set) else None, same_inputs(root, head, base)) if carried else []
|
|
768
932
|
if modules:
|
|
769
933
|
check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
|
|
770
934
|
check_hold(root, body, labels, authorship, fail, warnings.append, identities(root, base, head))
|
|
771
935
|
checks = check_attested(root, head, fail, warnings.append)
|
|
936
|
+
if forge == "github":
|
|
937
|
+
check_approvals(root, base, head, approvals(root), warnings.append)
|
|
772
938
|
if carried and reasons:
|
|
773
939
|
check_moved(body, recorded_rows(root, fork, head), fail, warnings.append,
|
|
774
940
|
lambda one, other: bool(tree_of(one)) and tree_of(one) == tree_of(other))
|
|
@@ -778,6 +944,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
|
|
|
778
944
|
+ ("" if carried or not reasons else " — no carrier: forge none has no pull request. T1 to T5 "
|
|
779
945
|
"judge a sheet filled in docs/pull_request_template.md — with its Deliverable line — passed by "
|
|
780
946
|
"nstack attest --body-file <file>"))
|
|
947
|
+
print(f"Labels : {', '.join(sorted(labels)) or 'none'} — {labels_from}")
|
|
781
948
|
print(f"Checks : {checks}")
|
|
782
949
|
for line in summary(body, authorship) if reasons and carried else []:
|
|
783
950
|
print(line)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/docs/runbook.md
RENAMED
|
File without changes
|
{napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/tests/.gitkeep
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|