From 02c06bc06668646bdbfe2cc912ea455f2bad6167 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 08:23:08 -0800 Subject: [PATCH] Factory work queue: ready changes in an order that says why, each with a reading order A factory that builds faster than a person can read moves the wait to the merge. `syberlabs factory work queue` lists every ticket whose thread holds an accepted change, first to read first. Stacked on claude/factory-plan-claim. Read-only: it appends no event, moves no ref, and pushes, splits and merges nothing. - review_queue.queue orders ready tickets by keys, the first difference decides: the change more tickets wait on (their plans name a path it touches), then fewer files, then the smaller diff, then the one ready longest. Every row carries the keys that placed it. Kind and size are shown and are not keys. - review_queue.reading_order groups the accepted commit's files by component, a component after the ones it depends on (the Space graph's depends_on), so the code that is called is read before the code that calls it. Each group is a layer; files with no component are the last one. - A row names the other ready changes that touch the same files. A change whose commit is not in the repository the queue is read from keeps its row, lists its plan's paths and goes last. - work settle with no ticket records every thread that holds an accepted change, the step before reading the queue. tests/test_factory_review_queue.py, 15 tests; the factory simulation campaign now proposes a patch, accepts it and reads the queue. The order is a rule: it has not been compared with the order a person would choose. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs --- docs/FACTORY_INTAKE.md | 4 +- docs/FACTORY_WORK.md | 65 ++++++- docs/ROADMAP_STATUS.md | 1 + syberlabs/factory/review_queue.py | 145 +++++++++++++++ syberlabs/factory/work.py | 7 + syberlabs/factory/work_cli.py | 23 ++- tests/simulation/campaigns.py | 1 + tests/simulation/factory.py | 25 ++- tests/test_factory_review_queue.py | 280 +++++++++++++++++++++++++++++ 9 files changed, 534 insertions(+), 17 deletions(-) create mode 100644 syberlabs/factory/review_queue.py create mode 100644 tests/test_factory_review_queue.py diff --git a/docs/FACTORY_INTAKE.md b/docs/FACTORY_INTAKE.md index 2985e98..933ad5e 100644 --- a/docs/FACTORY_INTAKE.md +++ b/docs/FACTORY_INTAKE.md @@ -24,7 +24,7 @@ comes out, with a person keeping the merge. The stations, and what SyberWork has | One agent, one ticket, inside the plan | A claim on the ledger; a Build Thread whose mutable scope is the plan's files and whose objective names the request | [FACTORY_WORK.md](FACTORY_WORK.md) | | Build | A Build Thread: a model proposes commits, the repair loop feeds it SyberWork's own check results | [BUILD_THREAD.md](BUILD_THREAD.md) | | Review by someone who did not write it | The critic station: findings in the chain, a high finding refuses acceptance | [CRITIC.md](CRITIC.md) | -| A person decides | Accepting moves one branch; pushing, a pull request and a merge are separate acts | [BUILD_THREAD.md](BUILD_THREAD.md), `AGENTS.md` classes | +| A person decides | Accepting moves one branch; pushing, a pull request and a merge are separate acts. `factory work queue` orders what waits for them and says how to read each change | [BUILD_THREAD.md](BUILD_THREAD.md), `AGENTS.md` classes, [FACTORY_WORK.md](FACTORY_WORK.md) | The station names follow Daniel Moka's "Build Your Own Software Factory" (craftbettersoftware.com). Two things differ on purpose. The state of a request is an event on the hash-chained ledger, not a label; `label()` gives @@ -262,5 +262,3 @@ repository. That naming is the owner's to confirm or change at admission. - **`critic-weakened-tests`**: reference-critic rules for a newly skipped test, assertions removed from an existing test, and a credential shape on an added line. -- **A queue for the person who merges**: ready work ordered by what it unblocks, with a reading order by - component. diff --git a/docs/FACTORY_WORK.md b/docs/FACTORY_WORK.md index 6cb5003..de1e69f 100644 --- a/docs/FACTORY_WORK.md +++ b/docs/FACTORY_WORK.md @@ -4,10 +4,11 @@ Build Thread: a plan is written before any code and checked by code, one agent claims the ticket, and the thread that builds it may change the plan's files and no others. -Package: `syberlabs/factory/plan.py`, `work.py` and `work_cli.py`, on the ledger of [FACTORY.md](FACTORY.md). -Standard library only. Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory_work.py`, -35 tests, and the `factory` simulation campaign). Nothing here is measured: no model has written a plan through -it, and no agent fleet has run on it. +Package: `syberlabs/factory/plan.py`, `work.py`, `review_queue.py` and `work_cli.py`, on the ledger of +[FACTORY.md](FACTORY.md). Standard library only. Claim ceiling for this page: **implemented** and **tested** +(`tests/test_factory_work.py`, 35 tests; `tests/test_factory_review_queue.py`, 15 tests; the `factory` simulation +campaign). Nothing here is measured: no model has written a plan through it, no agent fleet has run on it, and +the queue's order has not been compared with the order a person would choose. ## The four rules @@ -156,6 +157,54 @@ with the thread, the candidate, the commit and the branch. That is the end of th accepted change is on `syberlabs/`. Pushing it and opening a pull request are the thread's own publishing actions, and merging is the act [BUILD_THREAD.md](BUILD_THREAD.md) leaves to a person on GitHub. +## The queue for the person who merges + +A factory that builds faster than a person can read moves the wait to the merge. `work queue` does not shorten +the reading; it orders it. It lists every `ready` ticket, first to read first, and for each change the order to +read its files in. It is computed from the ledger, the Space graph and Git. No model is asked. + +**The order of the queue** is an ordered list of keys; the first difference decides (`review_queue.sort_key`): + +| Key | First | Why | +| --- | --- | --- | +| `blocks` | the change more tickets are waiting on | A ticket that is not ready yet waits on a change when its plan names a path the change touches. Merging that change first is what lets the others build on what will be there | +| `files` | fewer files | Small before large is shortest job first: the order in which the changes behind wait least in total | +| `diff_bytes` | the smaller diff | The same, when the file counts are equal | +| `waiting_since` | the one ready longest | So nothing waits forever behind newer work | + +A change whose accepted commit is not in the repository the queue is read from (another clone, a deleted +branch) keeps its row, lists its plan's paths, and goes last: what cannot be read is not read first. Every row +carries the keys that placed it, so a person who orders differently sees what they overrule. Kind and size from +intake are shown and are not keys: nothing here knows which request matters more to the business. + +**The reading order of one change** (`review_queue.reading_order`) groups the files the accepted commit changes +by component and puts a component after the ones it depends on (the Space graph's `depends_on`), so the code +that is called is read before the code that calls it. Each group is a layer; files with no component are the +last one. Components that depend on each other, and ties, go by name. The paths are the accepted commit's +against the thread's base, not the plan's: a plan may allow a file the change did not touch. + +```text +1. github_issue:acme/app#12 rules crash on quantity zero + ticket 5c0f6f0be7b9d6b4 bug S class R owner mateo + placed by: blocks 1, 3 file(s), 612 bytes, ready since event 41 + waiting on it: 9a41c2d07e6f1b35 + branch syberlabs/7f3a9c at 1e2d3c4b5a; accepted, not pushed or merged here + read in 3 layer(s), each after what it depends on: + 1. rules: fxapp/rules.py + 2. main: fxapp/main.py + 3. (no component): tests/test_rules_request.py +``` + +A row also names the other ready changes that touch the same files: whichever merges second is rebased. + +The queue reads `work_ready` records, and those are written by `work settle`. `work settle` with no ticket looks +at every ticket that has a thread and records the ones that hold an accepted change, so run it before reading the +queue. + +What it is not: it splits nothing. A change with several layers can be read layer by layer, and a person who +wants one pull request per layer makes them; the layers say where the cuts are. It pushes and merges nothing, +appends no event and moves no ref. It reads one ledger, so it lists the work of the agents that share it. + ## From a terminal ```sh @@ -167,6 +216,8 @@ python -m syberlabs.factory work claim OWNER/REPO#12 --by model:claude-1 python -m syberlabs.factory work start OWNER/REPO#12 --by model:claude-1 --check "tests=/abs/python -m unittest -q" python -m syberlabs.factory work settle OWNER/REPO#12 # exit 0 once the thread holds an accepted change python -m syberlabs.factory work release OWNER/REPO#12 --by model:claude-1 --reason "blocked on a decision" +python -m syberlabs.factory work settle # the same for every ticket that has a thread +python -m syberlabs.factory work queue # ready work, first to read first; --json for a tool ``` A ticket is named by its id, the first eight or more characters of it, or its request. `--home` is the factory @@ -181,8 +232,8 @@ or put it in a script file. - **Call a model.** The planner is a command; this packet ran only the stand-in (`tests/fixtures/intake/standin_planner.py`). A planning agent behind it, Claude Code with read-only tools for example, is an adapter nobody has written here. -- **Choose which ticket an agent takes.** `work list --status planned` shows what may be taken. Ordering it is - the queue packet. +- **Choose which ticket an agent takes.** `work list --status planned` shows what may be taken, in the order the + requests were decided. The queue orders what a person merges, not what an agent starts. - **Enforce a class.** The floors route a plan and name the thread's class, so a plan a person approved above `auto` does not become a pull request that says R. The class is still recorded, not enforced (`AGENTS.md`): neither the kit nor a ruleset asks for the key it names. What a candidate cannot do is leave the plan's paths. @@ -215,8 +266,6 @@ one proposed here. The `AGENTS.md` section it adds is canonical text and waits f ## Next packets -- **A queue for the person who merges**: `ready` work ordered by what it unblocks and how much it touches, with - a reading order by component from the Space graph. - **A planning agent**: Claude Code with read-only tools behind the planner command, on its own credential lane ([CLAUDE_CODE.md](CLAUDE_CODE.md)). - **Claims across machines**: the ledger anchored somewhere two operators can both read. diff --git a/docs/ROADMAP_STATUS.md b/docs/ROADMAP_STATUS.md index 703975c..7309c5c 100644 --- a/docs/ROADMAP_STATUS.md +++ b/docs/ROADMAP_STATUS.md @@ -127,4 +127,5 @@ A coordination record is not a case event. A displayed comment, diversity score, | Replay viewer at scale: grid layout past eight components, io in the panel; 40 scrubs in 39 ms on a 3,275-span run | Implemented; one measured run | `syberlabs/static/factory.html` | | Intake: a request from outside is screened by code (hidden text removed, order shapes and credential shapes found), six closed questions go to one decider command in the System One wire shape, an ordered rule list picks `agent_ready`, `needs_human`, `unclear` or `duplicate` with a 0.80 floor, every answer is on the ledger without the text, and `agent_ready` opens a ticket | Implemented and tested with a stand-in decider; no decision model run; pattern precision unmeasured; Class C, awaiting an owner's key and a confirmed first consumer | `syberlabs/factory/intake.py`, `factory intake ...`, `tests/test_factory_intake.py`, [docs/FACTORY_INTAKE.md](FACTORY_INTAKE.md) | | Work from a ticket: a planner command names files, steps and risks; code checks the plan against HEAD, computes the class floor and the dependent components from the paths, and an ordered rule list routes it `planned` or `needs_human`; a claim on the ledger keeps one agent per ticket; the Build Thread it starts may change the plan's files and no others, records the class those paths floor at, and names the request in its objective | Implemented and tested with a stand-in planner; no model has planned through it and no pull request was opened from it; Class C, awaiting an owner's key and a confirmed first consumer | `syberlabs/factory/plan.py`, `work.py`, `factory work ...`, `tests/test_factory_work.py`, [docs/FACTORY_WORK.md](FACTORY_WORK.md) | +| A queue for the person who merges: every ticket whose thread holds an accepted change, ordered by how many tickets wait on it, then fewer files, the smaller diff and the longer wait, each with a reading order by component from the Space graph; read-only | Implemented and tested on the fixture app; the order has not been compared with a person's; awaiting the same key as the work line it reads | `syberlabs/factory/review_queue.py`, `factory work queue`, `tests/test_factory_review_queue.py`, [docs/FACTORY_WORK.md](FACTORY_WORK.md) | | Real model adapters behind the commands; a learned vectorizer; journal forking; change coupling | Proposed (v2) | [docs/FACTORY.md](FACTORY.md) | diff --git a/syberlabs/factory/review_queue.py b/syberlabs/factory/review_queue.py new file mode 100644 index 0000000..9a69eaa --- /dev/null +++ b/syberlabs/factory/review_queue.py @@ -0,0 +1,145 @@ +"""The queue for the person who merges: every ticket whose thread holds an accepted change, in an order that says +why, with a reading order for each change. + +A factory that builds faster than a person can read moves the wait to the merge. This module does not shorten the +reading; it orders it. Two things are computed, from the ledger, the Space graph and Git, and nothing is asked of a +model: + +- **The order of the queue.** An ordered list of keys, the first difference decides (``ORDER``): a change that other + tickets are waiting on comes first (their plans name a path this change touches, so merging it first is what lets + them build on what will be there); then the change with fewer files; then the smaller diff; then the one that has + waited longest. Small before large is the shortest-job-first rule: it is the order in which the changes behind + wait least in total. The keys are printed with every row, so a person who orders differently can see what they + are overruling. +- **The reading order of one change.** Its files grouped by component, a component after the ones it depends on + (the Space graph's ``depends_on``), so the code that is called is read before the code that calls it. Each group + is a layer. A change with several layers can be read, and if the person wants, split, layer by layer; this module + splits nothing. + +Read-only: ``queue`` appends no event, moves no ref and runs no command but ``git diff`` and ``git rev-parse``. +Accepting was a person's act on the thread, and pushing, opening a pull request and merging stay theirs. +""" + +from __future__ import annotations + +from pathlib import Path + +from syberlabs.errors import Rejected +from syberlabs.factory import intake, work +from syberlabs.factory import plan as planmod +from syberlabs.gitspace import GitError, Repo + +ORDER = ("blocks", "files", "diff_bytes", "waiting_since") # most first, then fewest, smallest, oldest (``sort_key``) +WAITING = ("open", "plan_held", "plan_rejected", "planned", "claimed", "working") # not ready, and may hold a plan +NO_COMPONENT = None + + +def reading_order(space: dict | None, paths: list[str]) -> list[dict]: + """``[{"layer", "component", "paths"}]``: ``paths`` grouped by the component each belongs to + (``plan.components_of``; the first by name when globs overlap), a component after every component it depends + on. Components that depend on each other in a cycle, and ties, go by name. Paths with no component are the last + layer.""" + groups: dict = {} + for path in sorted(paths): + owners = planmod.components_of(space, path) + groups.setdefault(owners[0] if owners else NO_COMPONENT, []).append(path) + touched = sorted(name for name in groups if name is not NO_COMPONENT) + needs = {name: set() for name in touched} + for edge in (space or {}).get("depends_on", []): + if edge["from"] in needs and edge["to"] in needs and edge["from"] != edge["to"]: + needs[edge["from"]].add(edge["to"]) + placed: list = [] + while len(placed) < len(touched): + free = [name for name in touched if name not in placed and needs[name] <= set(placed)] + placed.append(free[0] if free else next(name for name in touched if name not in placed)) + layers = [{"component": name, "paths": groups[name]} for name in placed] + if NO_COMPONENT in groups: + layers.append({"component": NO_COMPONENT, "paths": groups[NO_COMPONENT]}) + return [{"layer": number, **layer} for number, layer in enumerate(layers, 1)] + + +def _changed(repo: Repo, base: str | None, commit: str) -> tuple[list[str], int] | None: + """The paths the accepted commit changes against the thread's base and the size of that diff in bytes, or None + when either commit is not in this repository any more.""" + if not base: + return None + try: + return repo.changed_paths(base, commit), repo.diff(base, commit, max_bytes=0)[1] + except GitError: # one of the two commits is not here + return None + + +def sort_key(row: dict) -> tuple: + """Where a row goes: more waiting tickets first, then fewer files, then the smaller diff, then the longer + wait. A change whose commit is gone has no diff to measure and goes after every change that can be read.""" + order = row["order"] + return (not row["found"], -order["blocks"], order["files"], order["diff_bytes"] or 0, order["waiting_since"]) + + +def queue(ledger, *, repo_root: str | Path, now: int | None = None) -> list[dict]: + """Every ``ready`` ticket, first to read first. Each row: ``position``, ``ticket_id``, ``source``, ``title`` + (the request's visible title), ``kind``, ``size``, ``act_class``, ``human_owner``, ``thread``, ``target_ref``, + ``commit``, ``paths`` and ``diff_bytes`` (of the accepted commit against the thread's base; the plan's paths + and None when the commit is gone, with ``found`` False), ``blocks`` (tickets not ready yet whose plan names + one of these paths), ``overlaps`` (other ready tickets that touch one), ``layers`` (``reading_order``) and + ``order`` (the keys that placed it).""" + events = ledger.events() + space = ledger.latest_space() + repo = Repo(Path(repo_root).resolve()) + states = work.tickets(ledger, now=now) + waiting = {s["ticket_id"]: set(s["plan"]["files"] + s["plan"]["new_files"]) for s in states + if s["status"] in WAITING and s["plan"] is not None and s["plan"]["plan_digest"] is not None} + rows = [] + for current in states: + if current["status"] != "ready": + continue + ready, started = current["ready"], current["work"] + found = _changed(repo, (started or {}).get("base"), ready["commit"]) + paths, size = found if found is not None else (sorted(current["plan"]["files"] + current["plan"]["new_files"]), None) + item = work.find(ledger, current["ticket_id"], events) + try: + title = intake.load_snapshot(ledger, item["snapshot_digest"])["visible"]["title"] + except Rejected: # a missing or edited snapshot costs the row its title, not the queue its row + title = "" + rows.append({"ticket_id": current["ticket_id"], "source": current["source"], "title": " ".join(title.split())[:120], + "kind": (item.get("work") or {}).get("kind"), "size": (item.get("work") or {}).get("size"), + "act_class": (started or {}).get("act_class"), "human_owner": current["human_owner"], + "thread": ready["thread"], "target_ref": ready["target_ref"], "commit": ready["commit"], + "found": found is not None, "paths": paths, "diff_bytes": size, + "blocks": sorted(tid for tid, planned in waiting.items() if planned & set(paths)), + "layers": reading_order(space, paths), "order": {"waiting_since": ready["seq"]}}) + for row in rows: + row["overlaps"] = sorted(other["ticket_id"] for other in rows + if other is not row and set(other["paths"]) & set(row["paths"])) + row["order"] = {"blocks": len(row["blocks"]), "files": len(row["paths"]), "diff_bytes": row["diff_bytes"], + "waiting_since": row["order"]["waiting_since"]} + return [{"position": number, **row} for number, row in enumerate(sorted(rows, key=sort_key), 1)] + + +def text(rows: list[dict]) -> str: + """The queue as a person reads it in a terminal: one block per change, the keys that placed it, where it is, + and its layers in reading order.""" + if not rows: + return "nothing is ready: no ticket's thread holds an accepted change\n" + lines = [] + for row in rows: + source = row["source"] + size = "size unknown" if row["diff_bytes"] is None else f"{row['diff_bytes']} bytes" + lines.append(f"{row['position']}. {source['kind']}:{source['ref']} {row['title'] or '(no title)'}") + lines.append(f" ticket {row['ticket_id']} {row['kind'] or 'kind unknown'} {row['size'] or ''}".rstrip() + + f" class {row['act_class'] or 'not recorded'} owner {row['human_owner']}") + lines.append(f" placed by: blocks {len(row['blocks'])}, {len(row['paths'])} file(s), {size}, ready since event " + f"{row['order']['waiting_since']}") + if row["blocks"]: + lines.append(f" waiting on it: {', '.join(row['blocks'])}") + if row["overlaps"]: + lines.append(f" touches the same files as: {', '.join(row['overlaps'])} (whichever merges second is rebased)") + where = f"{row['target_ref']} at {str(row['commit'])[:10]}" + lines.append(f" branch {where}; " + ("accepted, not pushed or merged here" if row["found"] + else "that commit is not in this repository, so the plan's paths are listed")) + many = len(row["layers"]) > 1 + lines.append(f" read in {len(row['layers'])} layer(s)" + (", each after what it depends on:" if many else ":")) + for layer in row["layers"]: + lines.append(f" {layer['layer']}. {layer['component'] or '(no component)'}: {', '.join(layer['paths'])}") + lines.append(f"{len(rows)} change(s) ready. Nothing here pushes, splits or merges one.") + return "\n".join(lines) + "\n" diff --git a/syberlabs/factory/work.py b/syberlabs/factory/work.py index 72d1c43..c265591 100644 --- a/syberlabs/factory/work.py +++ b/syberlabs/factory/work.py @@ -470,3 +470,10 @@ def once(events): "refs": {"thread": status["thread"], "candidate": status["accepted"], "commit": status["target"], "target_ref": status["target_ref"]}}, once) return state(ledger, tid, now=now) + + +def settle_all(ledger, *, repo_root: str | Path, kit_home: str | Path, now: int | None = None) -> list[dict]: + """``settle`` for every ticket that has a thread and no ``work_ready`` yet, whether or not its claim is still + live: the step before reading the queue. Returns the state of each ticket it looked at.""" + return [settle(ledger, row["ticket_id"], repo_root=repo_root, kit_home=kit_home, now=now) + for row in tickets(ledger, now=now) if row["work"] is not None and row["ready"] is None] diff --git a/syberlabs/factory/work_cli.py b/syberlabs/factory/work_cli.py index ec12c12..35e2430 100644 --- a/syberlabs/factory/work_cli.py +++ b/syberlabs/factory/work_cli.py @@ -9,6 +9,8 @@ syberlabs factory work start acme/app#12 --by model:claude-1 --check "tests=/abs/python -m unittest -q" syberlabs factory work settle acme/app#12 # record that its thread holds an accepted change syberlabs factory work release acme/app#12 --by model:claude-1 --reason "blocked on a decision" + syberlabs factory work settle # the same for every ticket that has a thread + syberlabs factory work queue # ready work, first to read first Registered through ``extend`` from one hook line at the end of ``cli.py``. ``--home`` is the factory ledger and ``--root`` the repository, as for every ``factory`` command. A ticket is named by its id, by the first characters @@ -23,7 +25,7 @@ from pathlib import Path from syberlabs.errors import Rejected -from syberlabs.factory import work +from syberlabs.factory import review_queue, work from syberlabs.factory import plan as planmod from syberlabs.factory import spec as specmod from syberlabs.providers import split_command @@ -103,10 +105,15 @@ def add_commands(steps) -> None: start.add_argument("--kit-home", default=".syberlabs", help="the Build Thread home under --root (default .syberlabs)") start.add_argument("--max-candidates", type=int, default=6) - settle = sub.add_parser("settle", help="record, once, that a ticket's thread holds an accepted change; nothing is merged") - settle.add_argument("ticket") + settle = sub.add_parser("settle", help="record, once, that a ticket's thread holds an accepted change; nothing is merged. " + "Without a ticket: every ticket that has a thread") + settle.add_argument("ticket", nargs="?") settle.add_argument("--kit-home", default=".syberlabs") + queue = sub.add_parser("queue", help="every ready change, first to read first, with the reasons for the order and a " + "reading order by component; nothing is pushed, split or merged") + queue.add_argument("--json", action="store_true") + def _read_json(path: str, what: str): try: @@ -222,6 +229,16 @@ def _run(args) -> int: print(f"objective {found['objective'].splitlines()[0]}") print(f"next syberlabs use {found['thread']}; then propose, check, and a person accepts. Nothing was proposed or merged.") return 0 + if command == "queue": + rows = review_queue.queue(home, repo_root=args.root) + print(json.dumps(rows, indent=2, sort_keys=True) if args.json else review_queue.text(rows), end="" if not args.json else "\n") + return 0 + if command == "settle" and args.ticket is None: + looked = work.settle_all(home, repo_root=args.root, kit_home=args.kit_home) + for current in looked: + print(_line(current)) + print(f"{sum(1 for current in looked if current['status'] == 'ready')} of {len(looked)} thread(s) hold an accepted change") + return 0 if command == "settle": current = work.settle(home, args.ticket, repo_root=args.root, kit_home=args.kit_home) print(_line(current)) diff --git a/tests/simulation/campaigns.py b/tests/simulation/campaigns.py index ba07255..90f9597 100644 --- a/tests/simulation/campaigns.py +++ b/tests/simulation/campaigns.py @@ -97,6 +97,7 @@ "syberlabs.factory.loop", "syberlabs.factory.plan", "syberlabs.factory.policy", + "syberlabs.factory.review_queue", "syberlabs.factory.space", "syberlabs.factory.spec", "syberlabs.factory.work", diff --git a/tests/simulation/factory.py b/tests/simulation/factory.py index 507bb32..830c8f1 100644 --- a/tests/simulation/factory.py +++ b/tests/simulation/factory.py @@ -14,8 +14,9 @@ Part four is the work line: in a Git repository, a ticket from intake is planned by the stand-in planner in a temporary checkout, claimed by one agent, refused to a second, and started as a Build Thread whose scope is the -plan's files; a plan that names a credentials file waits for a person. Nothing leaves loopback; every step runs in -a scratch folder. +plan's files; a plan that names a credentials file waits for a person. A patch is proposed and a person accepts +it, and the queue for the person who merges then lists that one change. Nothing leaves loopback; every step runs +in a scratch folder. """ from __future__ import annotations @@ -233,7 +234,25 @@ def command(script: str, *mode: str) -> str: raise AssertionError(started) if "1 ticket(s) working" not in _cli(project, "work", "list", "--status", "working"): raise AssertionError("the started ticket is not working") - _cli(project, "work", "release", "acme/app#5", "--by", "human:tester", "--reason", "campaign over") + if "nothing is ready" not in _cli(project, "work", "queue"): + raise AssertionError("a thread with no accepted change is in the queue") + from syberlabs.build import Kit + from syberlabs.providers import PatchProvider + + kit = Kit.local(project / ".syberlabs", project) + try: + thread = kit.open(work.state(home, "acme/app#5")["work"]["thread"]) + rules = (project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(PatchProvider({"fxapp/rules.py": rules + "\n# guarded\n"})) + thread.check(candidate.id) + if thread.accept(candidate.id).status != "succeeded": + raise AssertionError("the change inside the plan was not accepted") + finally: + kit.close() + _cli(project, "work", "settle", "acme/app#5") + queued = _cli(project, "work", "queue") + if "1. github_issue:acme/app#5" not in queued or "1. rules: fxapp/rules.py" not in queued or "1 change(s) ready" not in queued: + raise AssertionError(queued) after = subprocess.run(["git", "-C", str(project), "rev-parse", "main"], check=True, capture_output=True, text=True, env=env).stdout.strip() if after != base or not home.verify(): raise AssertionError("the work line moved main or left a ledger that does not verify") diff --git a/tests/test_factory_review_queue.py b/tests/test_factory_review_queue.py new file mode 100644 index 0000000..2dd4c7e --- /dev/null +++ b/tests/test_factory_review_queue.py @@ -0,0 +1,280 @@ +"""The queue for the person who merges: ready work in an order that says why, and a reading order for each change. +Offline on the fixture app: plans a person wrote, a patch as the proposer, nothing pushed or merged.""" + +import io +import json +import os +import unittest +from contextlib import redirect_stderr, redirect_stdout + +from syberlabs.build import Kit +from syberlabs.factory import cli as factory_cli +from syberlabs.factory import intake, review_queue, work +from syberlabs.providers import PatchProvider +from tests.test_factory_work import AGENT, CHECKS, HUMAN, OTHER, Scratch, git + +REQUESTS = { + "acme/app#1": ("rules crash on quantity zero", + "Steps: run the order path with quantity 0.\nExpected: no order is posted.\nInstead the rules module raises ZeroDivisionError."), + "acme/app#2": ("effects fail when the ledger file is absent", + "Steps: post one order with no ledger file present.\nExpected: the effects module creates it.\nInstead it fails with FileNotFoundError."), + "acme/app#3": ("ingest wrong for an empty line", + "Steps: feed the ingest module a file with one empty line.\nExpected: the line is skipped.\nInstead the parser returns a wrong record."), + "acme/app#4": ("main exits with a traceback on a missing fixture", + "Steps: start main with a fixture path that does not exist.\nExpected: one clear error line.\nInstead main fails with a traceback."), +} + + +def plan_of(files, new_files=()): + return {"files": list(files), "new_files": list(new_files), "steps": ["Make the change the request asks for."], "risks": []} + + +class Queue(Scratch): + def ticket(self, ref): + return work.state(self.home, ref)["ticket_id"] + + def planned_by_hand(self, ref, files, new_files=()): + self.triaged(ref, *REQUESTS[ref]) + found = work.make_plan(self.home, ref, repo_root=self.project, written=(HUMAN, plan_of(files, new_files)), limits={"max_files": 12}) + self.assertEqual(found["state"]["status"], "planned", found["planned"]) + + def ready(self, ref, files, new_files=(), by=AGENT): + """Plan, claim, start, propose a change to every planned path, accept, settle.""" + self.planned_by_hand(ref, files, new_files) + work.claim(self.home, ref, by) + found = work.start(self.home, ref, by, repo_root=self.project, kit_home=".syberlabs", checks=CHECKS) + kit = Kit.local(self.project / ".syberlabs", self.project) + try: + thread = kit.open(found["thread"]) + changes = {path: (self.project / path).read_text(encoding="utf-8") + f"\n# {ref}\n" for path in files} + changes.update({path: f"# {ref}\n" for path in new_files}) + [candidate] = thread.propose(PatchProvider(changes)) + thread.check(candidate.id) + self.assertEqual(thread.accept(candidate.id).status, "succeeded") + finally: + kit.close() + self.assertEqual(work.settle(self.home, ref, repo_root=self.project, kit_home=".syberlabs")["status"], "ready") + return found["thread"] + + def rows(self): + return review_queue.queue(self.home, repo_root=self.project) + + +class ReadingOrder(Scratch): + def test_a_component_is_read_after_the_ones_it_depends_on(self): + graph = self.home.latest_space() + paths = ["fxapp/main.py", "fxapp/ingest.py", "tests/test_x.py", "fxapp/effects.py", "fxapp/rules.py", "README.md", "fxapp/variants.py"] + self.assertEqual(review_queue.reading_order(graph, paths), [ + {"layer": 1, "component": "rules", "paths": ["fxapp/rules.py"]}, + {"layer": 2, "component": "effects", "paths": ["fxapp/effects.py"]}, + {"layer": 3, "component": "ingest", "paths": ["fxapp/ingest.py"]}, + {"layer": 4, "component": "main", "paths": ["fxapp/main.py", "fxapp/variants.py"]}, + {"layer": 5, "component": None, "paths": ["README.md", "tests/test_x.py"]}]) + self.assertEqual(review_queue.reading_order(graph, ["fxapp/main.py"]), [{"layer": 1, "component": "main", "paths": ["fxapp/main.py"]}]) + self.assertEqual(review_queue.reading_order(None, ["b.py", "a.py"]), [{"layer": 1, "component": None, "paths": ["a.py", "b.py"]}]) + self.assertEqual(review_queue.reading_order(graph, []), []) + + def test_a_cycle_and_a_tie_go_by_name(self): + graph = {"files": {}, "components": {name: {"paths": [f"{name}/**"]} for name in ("a", "b", "c", "d")}, + "depends_on": [{"from": "a", "to": "b"}, {"from": "b", "to": "a"}, {"from": "c", "to": "a"}, {"from": "d", "to": "d"}]} + order = [layer["component"] for layer in review_queue.reading_order(graph, ["c/x.py", "b/x.py", "a/x.py", "d/x.py"])] + self.assertEqual(order, ["d", "a", "b", "c"], "d needs nothing; a and b need each other, so the first by name goes; c follows a") + + +class Ordering(Queue): + def test_nothing_ready_is_an_empty_queue(self): + self.planned_by_hand("acme/app#1", ["fxapp/rules.py"]) + self.assertEqual(self.rows(), []) + self.assertIn("nothing is ready", review_queue.text([])) + + def test_the_change_others_wait_on_is_first_then_the_smaller_then_the_older(self): + self.ready("acme/app#3", ["fxapp/ingest.py", "fxapp/effects.py"]) # two files, ready first + self.ready("acme/app#1", ["fxapp/rules.py"], ["tests/test_rules_request.py"]) # two files, ready second + self.ready("acme/app#4", ["fxapp/main.py"]) # one file, ready last + rows = self.rows() + self.assertEqual(rows[0]["source"]["ref"], "acme/app#4", "the fewest files first") + keys = [(row["order"]["files"], row["order"]["diff_bytes"], row["order"]["waiting_since"]) for row in rows] + self.assertEqual(keys, sorted(keys), "then the smaller diff") + self.assertEqual([row["position"] for row in rows], [1, 2, 3]) + self.assertEqual([row["overlaps"] for row in rows], [[], [], []], "three changes to different files") + self.planned_by_hand("acme/app#2", ["fxapp/effects.py", "fxapp/rules.py"]) # waits on #3's effects.py and on #1's rules.py + waiting = self.ticket("acme/app#2") + rows = self.rows() + self.assertEqual(rows[2]["source"]["ref"], "acme/app#4", + "a change another ticket is waiting on is read before a smaller one nobody waits on") + self.assertEqual([row["blocks"] for row in rows], [[waiting], [waiting], []]) + self.assertEqual(rows[0]["order"]["blocks"], 1) + self.assertEqual(rows[2]["order"], {"blocks": 0, "files": 1, "diff_bytes": rows[2]["diff_bytes"], "waiting_since": rows[2]["order"]["waiting_since"]}) + + def test_the_keys_decide_in_their_order(self): + def row(name, blocks, files, size, since, found=True): + return {"name": name, "found": found, "order": {"blocks": blocks, "files": files, "diff_bytes": size, "waiting_since": since}} + + rows = [row("older", 0, 2, 500, 10), row("newer", 0, 2, 500, 20), row("smaller", 0, 2, 400, 30), row("fewer", 0, 1, 900, 40), + row("waited on", 1, 9, 9000, 50), row("gone", 3, 1, None, 5, found=False)] + self.assertEqual([r["name"] for r in sorted(reversed(rows), key=review_queue.sort_key)], + ["waited on", "fewer", "smaller", "older", "newer", "gone"]) + self.assertEqual(review_queue.ORDER, ("blocks", "files", "diff_bytes", "waiting_since")) + + def test_a_row_says_what_was_accepted_and_how_to_read_it(self): + thread = self.ready("acme/app#1", ["fxapp/main.py", "fxapp/rules.py"], ["tests/test_rules_request.py"]) + [row] = self.rows() + self.assertEqual((row["title"], row["kind"], row["size"], row["act_class"], row["human_owner"], row["thread"], row["found"]), + ("rules crash on quantity zero", "bug", "S", "R", "tester", thread, True)) + self.assertEqual(row["paths"], ["fxapp/main.py", "fxapp/rules.py", "tests/test_rules_request.py"]) + self.assertEqual(row["commit"], git(self.project, "rev-parse", row["target_ref"])) + self.assertGreater(row["diff_bytes"], 0) + self.assertEqual([(layer["component"], layer["paths"]) for layer in row["layers"]], + [("rules", ["fxapp/rules.py"]), ("main", ["fxapp/main.py"]), (None, ["tests/test_rules_request.py"])]) + shown = review_queue.text([row]) + for part in ("1. github_issue:acme/app#1 rules crash on quantity zero", "bug S class R owner tester", + "placed by: blocks 0, 3 file(s),", f"at {row['commit'][:10]}; accepted, not pushed or merged here", + "read in 3 layer(s), each after what it depends on:", + " 1. rules: fxapp/rules.py", " 3. (no component): tests/test_rules_request.py", + "1 change(s) ready. Nothing here pushes, splits or merges one."): + self.assertIn(part, shown) + + def test_two_ready_changes_to_one_file_name_each_other(self): + self.ready("acme/app#1", ["fxapp/rules.py"]) + self.ready("acme/app#2", ["fxapp/rules.py", "fxapp/effects.py"], by=OTHER) + first, second = self.rows() + self.assertEqual((first["overlaps"], second["overlaps"]), ([second["ticket_id"]], [first["ticket_id"]])) + self.assertIn("whichever merges second is rebased", review_queue.text([first, second])) + + def test_the_paths_are_the_accepted_commit_s_not_the_plan_s(self): + self.planned_by_hand("acme/app#1", ["fxapp/rules.py", "fxapp/effects.py"]) + work.claim(self.home, "acme/app#1", AGENT) + found = work.start(self.home, "acme/app#1", AGENT, repo_root=self.project, kit_home=".syberlabs", checks=CHECKS) + kit = Kit.local(self.project / ".syberlabs", self.project) + try: + thread = kit.open(found["thread"]) + rules = (self.project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(PatchProvider({"fxapp/rules.py": rules + "\n# only this one\n"})) + thread.check(candidate.id) + thread.accept(candidate.id) + finally: + kit.close() + work.settle(self.home, "acme/app#1", repo_root=self.project, kit_home=".syberlabs") + [row] = self.rows() + self.assertEqual(row["paths"], ["fxapp/rules.py"], "the plan allowed two files; the accepted change touched one") + + def test_a_commit_this_repository_does_not_have_keeps_its_row_and_goes_last(self): + self.ready("acme/app#1", ["fxapp/rules.py", "fxapp/effects.py"]) + self.ready("acme/app#4", ["fxapp/main.py"]) + here = {row["source"]["ref"]: row for row in self.rows()} + self.assertEqual(list(here), ["acme/app#4", "acme/app#1"], "with both commits at hand, the one file is read first") + clone = self.scratch / "clone" # another clone with the ledger: main and one of the two accepted branches + git(self.scratch, "clone", "-q", "--no-local", "--single-branch", "--branch", "main", str(self.project), str(clone)) + kept = here["acme/app#1"]["target_ref"] + git(clone, "fetch", "-q", "origin", f"{kept}:{kept}") + rows = review_queue.queue(self.home, repo_root=clone) + self.assertEqual([(row["source"]["ref"], row["found"], row["diff_bytes"] is None) for row in rows], + [("acme/app#1", True, False), ("acme/app#4", False, True)], "a change that cannot be read is not read first") + self.assertEqual(rows[1]["paths"], ["fxapp/main.py"], "the plan's paths stand in") + self.assertIn("that commit is not in this repository", review_queue.text(rows)) + + def test_a_long_title_is_one_short_line_and_a_lost_snapshot_costs_only_the_title(self): + title = "rules crash on quantity zero " + "when the order path runs again " * 6 + self.triaged("acme/app#1", title, REQUESTS["acme/app#1"][1]) + work.make_plan(self.home, "acme/app#1", repo_root=self.project, written=(HUMAN, plan_of(["fxapp/rules.py"]))) + work.claim(self.home, "acme/app#1", AGENT) + found = work.start(self.home, "acme/app#1", AGENT, repo_root=self.project, kit_home=".syberlabs", checks=CHECKS) + kit = Kit.local(self.project / ".syberlabs", self.project) + try: + thread = kit.open(found["thread"]) + rules = (self.project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(PatchProvider({"fxapp/rules.py": rules + "\n# guarded\n"})) + thread.check(candidate.id) + thread.accept(candidate.id) + finally: + kit.close() + work.settle(self.home, "acme/app#1", repo_root=self.project, kit_home=".syberlabs") + [row] = self.rows() + self.assertEqual((len(row["title"]), row["title"]), (120, " ".join(title.split())[:120])) + for snapshot in (self.scratch / "ledger" / intake.ARTIFACTS).glob("*.json"): + snapshot.unlink() + [row] = self.rows() + self.assertEqual((row["title"], row["paths"]), ("", ["fxapp/rules.py"])) + self.assertIn("(no title)", review_queue.text([row])) + + def test_a_ready_record_without_its_start_record_still_has_a_row(self): + """A ledger someone appended to by hand: the queue lists what it can and reads no base it was not given.""" + self.planned_by_hand("acme/app#1", ["fxapp/rules.py"]) + current = work.state(self.home, "acme/app#1") + self.home.append("note", {"note": "work_ready", "ticket_id": current["ticket_id"], "plan_digest": current["plan"]["plan_digest"], + "refs": {"thread": "t-by-hand", "candidate": "c1", "commit": self.base, "target_ref": "refs/heads/by-hand"}}) + [row] = self.rows() + self.assertEqual((row["found"], row["paths"], row["act_class"], row["diff_bytes"]), (False, ["fxapp/rules.py"], None, None)) + + def test_settling_everything_finds_the_accepted_threads_and_leaves_the_rest(self): + self.planned_by_hand("acme/app#1", ["fxapp/rules.py"]) + self.planned_by_hand("acme/app#2", ["fxapp/effects.py"]) + self.planned_by_hand("acme/app#3", ["fxapp/ingest.py"]) + threads = {} + for ref, by in (("acme/app#1", AGENT), ("acme/app#2", OTHER)): + work.claim(self.home, ref, by) + threads[ref] = work.start(self.home, ref, by, repo_root=self.project, kit_home=".syberlabs", checks=CHECKS)["thread"] + kit = Kit.local(self.project / ".syberlabs", self.project) + try: + thread = kit.open(threads["acme/app#1"]) + rules = (self.project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(PatchProvider({"fxapp/rules.py": rules + "\n# guarded\n"})) + thread.check(candidate.id) + thread.accept(candidate.id) + finally: + kit.close() + self.assertEqual(self.rows(), [], "accepted on its thread, and the ledger has not been told") + later = work.state(self.home, "acme/app#2")["claim"]["until"] + 1 # the newer claim's end: both have lapsed by then + looked = work.settle_all(self.home, repo_root=self.project, kit_home=".syberlabs", now=later) + self.assertEqual([(row["source"]["ref"], row["status"]) for row in looked], [("acme/app#1", "ready"), ("acme/app#2", "planned")], + "the ticket with no thread is not looked at; a lapsed claim does not hide an accepted change") + self.assertEqual([row["source"]["ref"] for row in self.rows()], ["acme/app#1"]) + self.assertEqual(len(work.settle_all(self.home, repo_root=self.project, kit_home=".syberlabs")), 1, "only the one still without a record") + self.assertEqual(len(self.notes("work_ready")), 1) + + def test_reading_the_queue_writes_nothing(self): + self.ready("acme/app#1", ["fxapp/rules.py"]) + before = (len(self.home.events()), git(self.project, "for-each-ref"), git(self.project, "status", "--porcelain")) + self.rows() + review_queue.text(self.rows()) + self.assertEqual((len(self.home.events()), git(self.project, "for-each-ref"), git(self.project, "status", "--porcelain")), before) + self.assertTrue(self.home.verify()) + + def test_a_declined_request_leaves_the_queue(self): + self.ready("acme/app#1", ["fxapp/rules.py"]) + intake.resolve(self.home, "acme/app#1", "declined", HUMAN, reason="not now") + self.assertEqual(self.rows(), []) + + +class Cli(Queue): + def run_cli(self, *argv, code=0) -> str: + out, err = io.StringIO(), io.StringIO() + here = os.getcwd() + os.chdir(self.scratch) + try: + with redirect_stdout(out), redirect_stderr(err): + found = factory_cli.main(["--home", str(self.scratch / "ledger"), "--root", str(self.project), *argv]) + finally: + os.chdir(here) + self.assertEqual(found, code, err.getvalue() + out.getvalue()) + return out.getvalue() + + def test_the_queue_from_a_terminal(self): + self.assertIn("nothing is ready", self.run_cli("work", "queue")) + self.assertIn("0 of 0 thread(s) hold an accepted change", self.run_cli("work", "settle")) + self.ready("acme/app#1", ["fxapp/rules.py"], ["tests/test_rules_request.py"]) + self.planned_by_hand("acme/app#2", ["fxapp/effects.py"]) + work.claim(self.home, "acme/app#2", OTHER) + work.start(self.home, "acme/app#2", OTHER, repo_root=self.project, kit_home=".syberlabs", checks=CHECKS) + settled = self.run_cli("work", "settle") + self.assertIn("working", settled) + self.assertIn("0 of 1 thread(s) hold an accepted change", settled, "the ready ticket already has its record") + shown = self.run_cli("work", "queue") + self.assertIn("1. github_issue:acme/app#1 rules crash on quantity zero", shown) + self.assertIn("read in 2 layer(s), each after what it depends on:", shown) + [row] = json.loads(self.run_cli("work", "queue", "--json")) + self.assertEqual((row["position"], row["source"]["ref"], [layer["component"] for layer in row["layers"]]), (1, "acme/app#1", ["rules", None])) + + +if __name__ == "__main__": + unittest.main()