repomarshal 0.1.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.
@@ -0,0 +1,3 @@
1
+ """RepoMarshal: compile each repository change into an explained plan, then verify it."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from repomarshal.cli import main
2
+
3
+ raise SystemExit(main())
repomarshal/anchor.py ADDED
@@ -0,0 +1,143 @@
1
+ """BASE anchoring across invocations (owner: lead; fail-open review #2).
2
+
3
+ The automatic BASE comes from refs (origin/*, main, master) that the coding agent can move, for
4
+ example by fast-forwarding local `main` onto its own commits so they are never judged. The first
5
+ BASE seen for a branch is therefore remembered in `$GIT_DIR/repomarshal/base.json`. Later automatic
6
+ resolutions use merge-base(remembered, automatic): the older commit wins, so moving a ref can only
7
+ *widen* the diff. An explicit `--base` can likewise only widen the diff (merge-base with the
8
+ automatic/remembered BASE) and is never remembered, because the agent can pass one too (v0.2
9
+ fail-open review).
10
+
11
+ The state lives inside the git directory, never in the working tree (v0.3 fail-open review #2): a
12
+ file in the tree can be committed, so a pull request could ship its own "remembered" BASE and move
13
+ the CI judge's BASE (and with it policy and CODEOWNERS) to an older commit it picked. Locally the
14
+ file is still agent-writable, like everything the agent's user owns. Deleting or editing it
15
+ only restores plain automatic resolution. It never narrows the diff below what the refs give.
16
+ That is the same "may only add work" rule as for duration data (architecture §3.3). The
17
+ authoritative anchor remains a CI run with an explicit BASE.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import os
24
+ import stat
25
+ from pathlib import Path
26
+ from typing import Any
27
+
28
+ from repomarshal import git
29
+
30
+ STATE_NAME = "repomarshal/base.json" # relative to the git directory (`git rev-parse --git-path`)
31
+ MAX_STATE_BYTES = 1 << 20
32
+
33
+
34
+ def state_path(repo: Path) -> Path | None:
35
+ r = git._git(repo, "rev-parse", "--git-path", STATE_NAME, check=False)
36
+ out = r.stdout.strip()
37
+ if r.returncode != 0 or not out:
38
+ return None
39
+ path = Path(out)
40
+ return path if path.is_absolute() else repo / path
41
+
42
+
43
+ def read_small_json(path: Path | None, limit: int = MAX_STATE_BYTES) -> Any:
44
+ """Parse a small JSON state file, or return None. Never follows a final symlink, reads only a
45
+ regular file, and never reads more than `limit` bytes: a state file pointed at /dev/zero or a
46
+ FIFO must not hang or exhaust memory (v0.3 fail-open review #4)."""
47
+ if path is None:
48
+ return None
49
+ try:
50
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
51
+ except OSError:
52
+ return None
53
+ try:
54
+ if not stat.S_ISREG(os.fstat(fd).st_mode):
55
+ return None
56
+ data = os.read(fd, limit + 1)
57
+ except OSError:
58
+ return None
59
+ finally:
60
+ os.close(fd)
61
+ if len(data) > limit:
62
+ return None
63
+ try:
64
+ return json.loads(data.decode("utf-8"))
65
+ except (ValueError, UnicodeDecodeError):
66
+ return None
67
+
68
+
69
+ def _branch(repo: Path) -> str:
70
+ r = git._git(repo, "symbolic-ref", "-q", "--short", "HEAD", check=False)
71
+ return r.stdout.strip() or "(detached)"
72
+
73
+
74
+ def _load(repo: Path) -> dict[str, str]:
75
+ data = read_small_json(state_path(repo))
76
+ return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
77
+
78
+
79
+ def _is_commit(repo: Path, sha: str) -> bool:
80
+ return git._git(repo, "cat-file", "-e", f"{sha}^{{commit}}", check=False).returncode == 0
81
+
82
+
83
+ def _floor(repo: Path) -> tuple[str | None, str]:
84
+ """The automatic BASE combined with the remembered one (the older wins)."""
85
+ auto = git.resolve_base(repo, None)
86
+ remembered = _load(repo).get(_branch(repo))
87
+ if not remembered or not _is_commit(repo, remembered):
88
+ return auto, "automatic"
89
+ if auto is None:
90
+ return remembered, "remembered"
91
+ if remembered == auto:
92
+ return auto, "automatic (matches remembered)"
93
+ older = _merge_base(repo, remembered, auto)
94
+ if older:
95
+ how = "automatic" if older == auto else "remembered (automatic BASE moved forward)"
96
+ return older, how
97
+ return remembered, "remembered (automatic BASE unrelated to remembered)"
98
+
99
+
100
+ def _merge_base(repo: Path, a: str, b: str) -> str | None:
101
+ mb = git._git(repo, "merge-base", a, b, check=False)
102
+ return mb.stdout.strip() if mb.returncode == 0 and mb.stdout.strip() else None
103
+
104
+
105
+ def effective_base(repo: Path, explicit: str | None) -> tuple[str | None, str]:
106
+ """Return (base sha, how it was chosen). Never writes state.
107
+
108
+ An explicit BASE (CLI --base, MCP `base`) may come from the agent itself, so it can only
109
+ WIDEN the diff: the result is merge-base(explicit, floor), where floor is the automatic BASE
110
+ combined with the remembered one (v0.2 fail-open review #1/#2).
111
+ """
112
+ floor, how = _floor(repo)
113
+ if explicit is None:
114
+ return floor, how
115
+ pinned = git.resolve_base(repo, explicit) # raises GitError for a bad ref
116
+ if floor is None or pinned is None or pinned == floor:
117
+ return pinned if pinned is not None else floor, "explicit"
118
+ older = _merge_base(repo, pinned, floor)
119
+ if older == pinned:
120
+ return pinned, "explicit"
121
+ if older:
122
+ return older, f"explicit, widened to the older {how} BASE (an explicit BASE cannot narrow)"
123
+ return floor, f"{how} (explicit BASE unrelated; ignored)"
124
+
125
+
126
+ def remember(repo: Path, base: str | None, explicit: bool) -> None:
127
+ """Record the BASE for the current branch, once. Explicit (possibly agent-supplied) BASEs are
128
+ never recorded, so they cannot poison later automatic runs (v0.2 review #1)."""
129
+ if base is None or explicit:
130
+ return
131
+ path = state_path(repo)
132
+ if path is None:
133
+ return
134
+ state = _load(repo)
135
+ branch = _branch(repo)
136
+ if branch in state:
137
+ return
138
+ state[branch] = base
139
+ try:
140
+ path.parent.mkdir(parents=True, exist_ok=True)
141
+ path.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8")
142
+ except OSError:
143
+ return # state is an optimisation of safety, never required for a verdict
repomarshal/api.py ADDED
@@ -0,0 +1,299 @@
1
+ """Public Python API (owner: lead). The acceptance tests (agent "fixture") code against this and
2
+ the CLI only.
3
+
4
+ plan(repo, task=None, base=None, env=None) -> Plan
5
+ Compile the plan. Never executes repository code. Raises PolicyInvalid / GitError /
6
+ NotAGitRepository.
7
+
8
+ done(repo, task=None, base=None, env=None, dry_run=False) -> DoneResult
9
+ 1. tree_digest_before; 2. compile the binding plan; 3. run every REQUIRED gate (cheap
10
+ first, all of them; no fail-fast); 4. tree_digest_after; 5. fold the verdict; 6. write the
11
+ evidence record under .repomarshal/evidence/ (not when dry_run). PolicyInvalid ->
12
+ DoneResult with verdict BLOCKED and no gates run. dry_run: no gate runs, verdict UNKNOWN,
13
+ result lists the gates that would run.
14
+
15
+ `env` is passed to gate subprocesses and its PATH is used for tool availability (tests use it to
16
+ put stub executables on PATH). None means os.environ.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import dataclasses
22
+ import os
23
+ import time
24
+ from collections.abc import Mapping
25
+ from dataclasses import dataclass
26
+ from pathlib import Path
27
+
28
+ from repomarshal import __version__, anchor, evidence, git, planner, runner, verdict
29
+ from repomarshal.model import (
30
+ Cost,
31
+ DecisionStatus,
32
+ EvidenceRecord,
33
+ Gate,
34
+ GateDecision,
35
+ GateResult,
36
+ Plan,
37
+ PolicyInvalid,
38
+ ResultStatus,
39
+ Verdict,
40
+ )
41
+
42
+ _COST_ORDER = {Cost.CHEAP: 0, Cost.STANDARD: 1, Cost.EXPENSIVE: 2}
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class DoneResult:
47
+ verdict: Verdict
48
+ reasons: tuple[str, ...]
49
+ plan: Plan | None # None when BLOCKED before a plan could be compiled
50
+ record: EvidenceRecord | None # None on dry_run or BLOCKED-before-plan
51
+ evidence_path: Path | None
52
+ would_run: tuple[str, ...] = () # gate ids (dry_run only)
53
+
54
+
55
+ def _path_env(env: Mapping[str, str] | None) -> str | None:
56
+ return (env if env is not None else os.environ).get("PATH")
57
+
58
+
59
+ def plan(
60
+ repo: str | Path,
61
+ task: str | None = None,
62
+ base: str | None = None,
63
+ env: Mapping[str, str] | None = None,
64
+ ) -> Plan:
65
+ root = git.repo_root(repo)
66
+ base_sha, _ = anchor.effective_base(root, base)
67
+ return planner.compile_plan(root, task=task, base=base_sha, path_env=_path_env(env))
68
+
69
+
70
+ def _record(
71
+ root: Path, p: Plan, results, before: str, after: str, v, reasons, granted=()
72
+ ) -> DoneResult:
73
+ record = EvidenceRecord(
74
+ plan_hash=p.plan_hash,
75
+ base=p.change.base,
76
+ head=p.change.head,
77
+ tree_digest_before=before,
78
+ tree_digest_after=after,
79
+ policy_digest=p.policy.digest,
80
+ results=tuple(results),
81
+ verdict=v,
82
+ verdict_reasons=tuple(reasons),
83
+ repomarshal_version=__version__,
84
+ created_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
85
+ waivers=tuple(granted),
86
+ ).with_digest()
87
+ evidence.write_plan(root, p)
88
+ path = evidence.write_record(root, record)
89
+ return DoneResult(v, tuple(reasons), p, record, path)
90
+
91
+
92
+ def _nested_problem(root: Path) -> str | None:
93
+ """A repository the agent created inside another project (v0.2 fail-open review #3).
94
+
95
+ If `root` sits inside an outer git work tree and the outer project sees it as a new,
96
+ untracked (not ignored) directory, verifying it would judge a throwaway repository instead
97
+ of the project. Registered submodules (tracked gitlinks) and ignored directories are fine.
98
+ """
99
+ outer_r = git._git(root.parent, "rev-parse", "--show-toplevel", check=False)
100
+ if outer_r.returncode != 0 or not outer_r.stdout.strip():
101
+ return None
102
+ outer = Path(outer_r.stdout.strip()).resolve()
103
+ rel = root.relative_to(outer).as_posix() if root.is_relative_to(outer) else None
104
+ if rel is None:
105
+ return None
106
+ st = git._git(
107
+ outer, "status", "--porcelain", "--untracked-files=normal", "--", rel, check=False
108
+ )
109
+ if any(line.startswith("??") for line in st.stdout.splitlines()):
110
+ return (
111
+ f"{root} is a git repository nested, untracked, inside the project {outer}; "
112
+ "verify the project itself"
113
+ )
114
+ return None
115
+
116
+
117
+ @dataclass(frozen=True)
118
+ class Prepared:
119
+ """A binding plan ready for gates: what done() and the split CI steps (ci.py) share."""
120
+
121
+ root: Path
122
+ plan: Plan
123
+ base_sha: str | None
124
+ before: str # tree digest taken before the plan was compiled
125
+ inventory: dict[str, Gate]
126
+ required: tuple[GateDecision, ...] # REQUIRED decisions with a gate id, cheap first
127
+
128
+
129
+ def prepare(
130
+ repo: str | Path,
131
+ task: str | None = None,
132
+ base: str | None = None,
133
+ env: Mapping[str, str] | None = None,
134
+ remember: bool = True,
135
+ record: bool = False,
136
+ ) -> Prepared | DoneResult:
137
+ """Steps 1-2 of done(): a Prepared plan, or the DoneResult that ends the run early (nested
138
+ repository, invalid policy, untrustworthy plan, no change, duplicate gate ids). The early
139
+ result is recorded (evidence written) only when `record` is set and a plan exists."""
140
+ root = git.repo_root(repo)
141
+ nested = _nested_problem(root)
142
+ if nested:
143
+ return DoneResult(Verdict.UNKNOWN, (nested,), None, None, None)
144
+ base_sha, base_how = anchor.effective_base(root, base)
145
+ before = git.tree_digest(root, base=base_sha)
146
+ try:
147
+ p = planner.compile_plan(root, task=task, base=base_sha, path_env=_path_env(env))
148
+ except PolicyInvalid as e:
149
+ return DoneResult(
150
+ Verdict.BLOCKED,
151
+ tuple(f"invalid repomarshal.toml at BASE: {err}" for err in e.errors),
152
+ None,
153
+ None,
154
+ None,
155
+ )
156
+ except ValueError as e: # e.g. duplicate gate ids from the inventory: fail closed
157
+ return DoneResult(
158
+ Verdict.UNKNOWN, (f"could not compile a trustworthy plan: {e}",), None, None, None
159
+ )
160
+ if remember:
161
+ anchor.remember(root, base_sha, explicit=base is not None)
162
+
163
+ # Fail-open review #1: with no change there is nothing to verify, whatever the task says.
164
+ if not p.change.files:
165
+ reasons = (
166
+ "nothing was verified: no change relative to BASE "
167
+ f"{p.change.base or '(none)'} ({base_how})",
168
+ )
169
+ if record:
170
+ return _record(root, p, (), before, before, Verdict.UNKNOWN, reasons)
171
+ return DoneResult(Verdict.UNKNOWN, reasons, p, None, None)
172
+
173
+ # Fail-open review #11: ids must identify gates uniquely, or one gate could stand in for
174
+ # another. Duplicates are an internal inconsistency: fail closed.
175
+ ids = [g.id for g in p.inventory]
176
+ duplicates = sorted({i for i in ids if ids.count(i) > 1})
177
+ if duplicates:
178
+ reasons = (f"duplicate gate ids {duplicates}: cannot tell which gate a result belongs to",)
179
+ if record:
180
+ return _record(root, p, (), before, before, Verdict.UNKNOWN, reasons)
181
+ return DoneResult(Verdict.UNKNOWN, reasons, p, None, None)
182
+
183
+ inv = {g.id: g for g in p.inventory}
184
+ required = [d for d in p.gates if d.status == DecisionStatus.REQUIRED and d.gate_id]
185
+ required.sort(
186
+ key=lambda d: (
187
+ (_COST_ORDER.get(inv[d.gate_id].cost, 3), d.gate_id)
188
+ if d.gate_id in inv
189
+ else (9, d.gate_id)
190
+ )
191
+ )
192
+ return Prepared(root, p, base_sha, before, inv, tuple(required))
193
+
194
+
195
+ def adjust(d: GateDecision, result: GateResult, before: str, now: str) -> GateResult:
196
+ """The per-gate rules applied to every result, wherever the gate ran: test-tamper taint, and
197
+ a tree that changed while the gate ran. Both only ever DOWNGRADE a PASS (v0.2 review #6)."""
198
+ if d.taint:
199
+ # v0.2 tamper signals: the change weakens what this gate runs (deleted or skipped
200
+ # tests, narrowed discovery), so its result cannot vouch for the change.
201
+ taint = "; ".join(t.text for t in d.taint)
202
+ if result.status in (ResultStatus.PASS, ResultStatus.WAIVED):
203
+ result = dataclasses.replace(
204
+ result,
205
+ status=ResultStatus.UNKNOWN,
206
+ reason=f"{taint}; was: {result.status.value} ({result.reason})",
207
+ )
208
+ else:
209
+ result = dataclasses.replace(result, reason=f"{result.reason}; also: {taint}")
210
+ # Fail-open review #3: check the tree after EVERY gate. A gate that swaps files for later
211
+ # gates (and a final gate that restores them) would otherwise go unnoticed.
212
+ if now != before and result.status in (ResultStatus.PASS, ResultStatus.WAIVED):
213
+ result = dataclasses.replace(
214
+ result,
215
+ status=ResultStatus.UNKNOWN,
216
+ reason=f"gate modified the working tree (digest {before[:12]} -> {now[:12]}); "
217
+ f"was: {result.status.value} ({result.reason})",
218
+ )
219
+ return result
220
+
221
+
222
+ def collect_waivers(
223
+ prep: Prepared,
224
+ waivers: str,
225
+ env: Mapping[str, str] | None,
226
+ extra_targets: Mapping[str, tuple[str, ...]] | None = None,
227
+ ) -> tuple[tuple, tuple[str, ...]]:
228
+ """v0.3 human override: only the caller decides where waivers may come from (the hook and
229
+ the MCP server pass "none"); waivers.collect decides which ones are genuine. Call it BEFORE
230
+ any gate runs (v0.3 fail-open review #1): gates execute the change's code as the same user,
231
+ so anything read afterwards (the GitHub event file, git objects, even this module's source
232
+ on disk) could have been rewritten by the change being judged."""
233
+ if waivers == "none":
234
+ return (), ()
235
+ from repomarshal import waivers as waivers_mod # lazy: keeps urllib off the `plan` path
236
+
237
+ return waivers_mod.collect_report(prep.root, prep.plan, waivers, env, extra_targets)
238
+
239
+
240
+ def finish(
241
+ prep: Prepared,
242
+ results: list[GateResult],
243
+ after: str,
244
+ tree_changed: bool,
245
+ granted: tuple = (),
246
+ waiver_notes: tuple[str, ...] = (),
247
+ extra_reasons: tuple[str, ...] = (),
248
+ blockers: tuple[str, ...] = (),
249
+ ) -> DoneResult:
250
+ """Steps 5-6 of done(): fold the verdict and write the evidence record. Any `blockers`
251
+ (e.g. results that cannot be bound to the change) turn a PASS into UNKNOWN; waivers never
252
+ lift them."""
253
+ p = prep.plan
254
+ v, reasons = verdict.fold(
255
+ p, tuple(results), tree_changed, p.policy.waivers_permit_pass, granted
256
+ )
257
+ if blockers and v is Verdict.PASS:
258
+ v = Verdict.UNKNOWN
259
+ reasons = tuple(extra_reasons) + tuple(reasons) + tuple(f"waivers: {n}" for n in waiver_notes)
260
+ return _record(prep.root, p, results, prep.before, after, v, reasons, granted)
261
+
262
+
263
+ def done(
264
+ repo: str | Path,
265
+ task: str | None = None,
266
+ base: str | None = None,
267
+ env: Mapping[str, str] | None = None,
268
+ dry_run: bool = False,
269
+ waivers: str = "none",
270
+ ) -> DoneResult:
271
+ prep = prepare(repo, task=task, base=base, env=env, remember=not dry_run, record=not dry_run)
272
+ if isinstance(prep, DoneResult):
273
+ return prep
274
+ if dry_run:
275
+ return DoneResult(
276
+ Verdict.UNKNOWN,
277
+ ("dry run: no gates were executed",),
278
+ prep.plan,
279
+ None,
280
+ None,
281
+ would_run=tuple(d.gate_id for d in prep.required),
282
+ )
283
+
284
+ granted, waiver_notes = collect_waivers(prep, waivers, env)
285
+
286
+ root, p, before = prep.root, prep.plan, prep.before
287
+ results: list[GateResult] = []
288
+ tree_changed = before != p.change.tree_digest
289
+ for d in prep.required:
290
+ gate = prep.inventory.get(d.gate_id)
291
+ if gate is None:
292
+ continue # verdict.fold reports a REQUIRED gate without a result as UNKNOWN
293
+ result = runner.run_gate(root, gate, p.change, env)
294
+ now = git.tree_digest(root, base=prep.base_sha)
295
+ tree_changed = tree_changed or now != before
296
+ results.append(adjust(d, result, before, now))
297
+ after = git.tree_digest(root, base=prep.base_sha)
298
+ tree_changed = tree_changed or before != after
299
+ return finish(prep, results, after, tree_changed, granted, waiver_notes)