Merge remote-tracking branch 'origin/main' into patch-0.10.1
# Conflicts: # CHANGELOG.md # README.md # bin/loop_claude/loop/chunk_start.py # bin/loop_claude/loop/close.py # bin/loop_claude/loop/main.py # bin/loop_claude/routing.py # bin/loop_claude/test_loop_claude.py # bin/project_config/main.py # bin/project_config/test_project_config.py # docs/decisions.md
This commit is contained in:
+25
-6
@@ -23,6 +23,13 @@
|
||||
!agents/
|
||||
!agents/*.md
|
||||
!bin/
|
||||
!bin/adf_codec/
|
||||
!bin/adf_codec/*.py
|
||||
!bin/adf_codec/node_shim/
|
||||
!bin/adf_codec/node_shim/Dockerfile
|
||||
!bin/adf_codec/node_shim/package-lock.json
|
||||
!bin/adf_codec/node_shim/package.json
|
||||
!bin/adf_codec/node_shim/shim.mjs
|
||||
!bin/branch_chunks/
|
||||
!bin/branch_chunks/*.py
|
||||
!bin/chunk-pr
|
||||
@@ -51,20 +58,15 @@
|
||||
!bin/larv_review/
|
||||
!bin/larv_review/*.py
|
||||
!bin/loop-claude
|
||||
!bin/loop-inbox
|
||||
!bin/loop_claude/
|
||||
!bin/loop_claude/**/
|
||||
!bin/loop_claude/**/*.py
|
||||
!bin/loop_effects/
|
||||
!bin/loop_effects/*.py
|
||||
!bin/loop_inbox/
|
||||
!bin/loop_inbox/*.py
|
||||
!bin/loop_state/
|
||||
!bin/loop_state/**/
|
||||
!bin/loop_state/**/*.py
|
||||
!bin/loop_state/*.py
|
||||
!bin/machine_load/
|
||||
!bin/machine_load/*.py
|
||||
!bin/mattermost-dm
|
||||
!bin/mattermost_dm/
|
||||
!bin/mattermost_dm/*.py
|
||||
!bin/metric-bench
|
||||
@@ -76,17 +78,29 @@
|
||||
!bin/mutate-changes
|
||||
!bin/mutate_changes/
|
||||
!bin/mutate_changes/*.py
|
||||
!bin/notifier/
|
||||
!bin/notifier/*.py
|
||||
!bin/notify
|
||||
!bin/plan_store/
|
||||
!bin/plan_store/*.py
|
||||
!bin/project-config
|
||||
!bin/project-record
|
||||
!bin/project_config/
|
||||
!bin/project_config/*.py
|
||||
!bin/project_record/
|
||||
!bin/project_record/*.py
|
||||
!bin/rank_todo.py
|
||||
!bin/reading-cost
|
||||
!bin/reading_cost/
|
||||
!bin/reading_cost/*.py
|
||||
!bin/record_store/
|
||||
!bin/record_store/*.py
|
||||
!bin/release_plan/
|
||||
!bin/release_plan/*.py
|
||||
!bin/repo_checks/
|
||||
!bin/repo_checks/*.py
|
||||
!bin/rest_client/
|
||||
!bin/rest_client/*.py
|
||||
!bin/review-replay
|
||||
!bin/review_replay/
|
||||
!bin/review_replay/*.py
|
||||
@@ -112,6 +126,8 @@
|
||||
!bin/score_outcomes/*.py
|
||||
!bin/settings_filter.py
|
||||
!bin/setup.cfg
|
||||
!bin/slack_dm/
|
||||
!bin/slack_dm/*.py
|
||||
!bin/statusline.py
|
||||
!bin/subagent-rung
|
||||
!bin/subagent_rung/
|
||||
@@ -122,6 +138,9 @@
|
||||
!bin/todo-item
|
||||
!bin/todo_item/
|
||||
!bin/todo_item/*.py
|
||||
!bin/touch-predictions
|
||||
!bin/touch_predictions/
|
||||
!bin/touch_predictions/*.py
|
||||
!bin/transcript_archive/
|
||||
!bin/transcript_archive/*.py
|
||||
!bin/wait-for
|
||||
|
||||
@@ -1,5 +1,33 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
- Two loop-claude runs in one project now work side by side, each on its own chunk. Each loop holds a slot of the project, a locked file under `~/.local/state/loop-claude/<key>/`, and names its session after it: the first loop's session keeps its name, `A <key> loop-claude`, and the second's is `A <key> loop-claude 2`. A rerun resumes a chunk left open first. A commit in the config's folder now takes only the file it changed, as `git commit -m <title> -- <file>`.
|
||||
- `todo-item finish` finishes an item of a plan kept in a Jira epic: it moves the item's issue by the workflow transition, and to the status, that the config's new optional settings `jira-finish-transition` and `jira-finish-status` name, both as Jira shows them. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither.
|
||||
- Reviewers and loop-claude's judge read the review standards from the folder a project's config sets as `standards`, in place of `~/.claude/skills/larv-review/standards/`. The setting is required. To upgrade, add `standards = "~/.claude/skills/larv-review/standards"` to every config under `~/.claude-projects/` right after `deploy-release` moves `~/.claude` to this release, and not before.
|
||||
- A project's config may keep each of its five records on a Confluence Cloud page: set, for example, `decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>"`, with the credentials in the config's `env-file`. `decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic. The loop reads and writes the page as markdown, so a save replaces a mention or a macro on it with plain text. It never overwrites a teammate's edit: where someone saved the page since the loop read it, `project-record save` refuses and the loop asks you.
|
||||
- `todo-item add` files an item into a plan kept in a Jira epic: a Task under the epic, under the project's Fix Version for the release, labelled `security` for a security finding and linked to each item that blocks it. Editing an issue still happens in Jira.
|
||||
- An item of the next release may predict the files and parts it will touch, under a `Touches:` line in its detail. `chunk-preflight` then names the items that may start chunks at once, and the new `touch-predictions record` keeps each prediction beside what the merged chunk touched, in the record a project's config places with `touch-predictions`.
|
||||
- CLAUDE.md and the todo-items rule define the plan as a todo.md or a Jira epic, and say plan where todo.md was false for a Jira plan.
|
||||
- Reviewers without a shell read the plan from a listing that larv-review writes into the review folder, whichever store holds it.
|
||||
- A project's config may set `tooling-on-host = true`, so the loop runs a legacy project's language runtime, package manager, tests and task runner directly on the host.
|
||||
- A project's config may set `readability-floor` to a number from 1 to 10: the comprehension score under which code health is very important. It is 7.0 where left out.
|
||||
- A project whose plan is a Jira epic can keep its goals and audience in an epic's description too: set `goals-and-audience = "jira:https://<site>/browse/<KEY>"`. The loop only reads it, and `project-record open goals-and-audience` prints a file holding its text.
|
||||
- A project with a Jira plan can name each chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`. The README shows the three templates to set.
|
||||
- A read of a plan in a Jira epic converts every issue description in one `adf_codec` container run, however many issues the epic holds. The codec builds its image inside one of the machine's heavy slots that `run-heavy` shares, so sessions reading at once build it once.
|
||||
- A project config may name its plan as `jira:https://<site>/browse/<KEY>`: the plan is then read from the open child issues of that Jira Cloud epic, in backlog order, with the credentials in the config's `env-file`. Such a plan is only read so far: file, edit and finish its issues in Jira.
|
||||
- A new `adf_codec` package converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back with `@larvit/adf-codec` 0.3.1. It runs in a pinned Node container with a memory limit and no network, and returns adf-codec's error codes as a `Failure`. No tool calls it yet.
|
||||
- The new `todo-item list [--release <version>]` prints the plan's items in the plan's order, `todo-item edit <ID>` sets an item's cells or detail, and `todo-item move <ID> --release <version>` moves it to another release; each change ranks the plan. Agents now read and change the plan's items only with `todo-item`, and the tools read the plan as it stands through one store, `bin/plan_store`, so a later backend can keep a plan outside `todo.md`. `todo-item list --release` with a bad version exits 2, and `finish <ID> --no-changelog` also drops an item no chunk built.
|
||||
- A project's config may name the language its prose is written in (`language`) and templates for its commit titles, pull request titles and branch names (`commit-title`, `pull-request-title`, `branch`), in which `{id}` stands for the plan item's ID and `{summary}` for the one-line summary. The tools and the prose reviewer follow them. On a branch that fits the `branch` template, rule-hook's new `commit-title` rule refuses a commit title that doesn't fit, and `chunk-pr` such a pull request title. While a project's config holds a fault, rule-hook refuses every commit there.
|
||||
- `chunk-pr merge` waits for a human's approval of the pull request where the project's config sets `wait-for-approval = true`: it merges once GitHub reports the pull request approved, and gives up after 90 minutes. It reads approvals on GitHub only. Set it for a client whose pull requests need another person's approval.
|
||||
- The technical principles ask for code in files and folders before `// --- name ---` banner comments. They also ask for an entry point a newcomer finds at once: the root holds it, the README and the files a tool reads only from there.
|
||||
- In a client project, the loop reads the team's own `CLAUDE.md` and `AGENTS.md` and proposes each change that aligns them with this setup in a pull request of its own. Where the team declines or doesn't answer, the loop follows the team's rule unless it breaks a project goal, and records the conflict as a decision in the `decisions` record.
|
||||
- The new `project-record open <record>` prints the file in which an agent reads and edits one of a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`), and `project-record save <record>` stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change.
|
||||
- `loop-inbox` is gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and `/talk` opens the worker's session. The DM still tells you a loop waits. To upgrade, quit any `loop-inbox` still open and remove your `~/.local/bin/loop-inbox` link.
|
||||
- rule-hook refuses a Read or a Grep of `~/.claude/.env` or of the `env-file` any project's config names, and a Bash command that names either or searches a folder holding either with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through.
|
||||
- A project's config names the service for loop-claude's DMs: `notifier = "mattermost"` or `"slack"`, with the bot's token and the recipient in the `env-file`. To upgrade, move the Mattermost keys from `~/.claude/.env` into a file outside the checkout and the config's folder, such as `~/.claude-projects/<key>.env`, name it as `env-file` and add `notifier = "mattermost"`. A project with no `notifier` gets no DM, and `~/.claude/.env` is no longer read. A failure names each missing key and holds no token.
|
||||
- `mattermost-dm` is now `notify`, which sends through the project's `notifier`; `notify --help` names the keys.
|
||||
|
||||
## 0.10.1
|
||||
|
||||
- The routing ladder is now a file, `bin/model_routing/routing-ladder.json`, and a project may run on a ladder of its own: a `routing-ladder.json` in its config's folder, `~/.claude-projects/<key>/`, replaces the shipped ladder whole for that project, and loop-claude says so as each cycle starts. loop-claude, `subagent-rung` and rule-hook read the project's ladder; the routing figures, `judge-replay` and `review-replay` read the shipped one. `subagent-rung` now reads the config of the checkout it runs in, and exits 1 where that config or the ladder holds a fault; loop-claude stops on a faulty ladder as it does on a faulty config. `loop-claude --help` shows the file's shape, and README → Install → "Set up a project" says when to write one.
|
||||
|
||||
@@ -2,22 +2,24 @@
|
||||
|
||||
## Working loop
|
||||
|
||||
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
|
||||
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Where the config names a Jira epic as the plan, the plan is the epic's open child issues. Read and edit a project record in the file `~/.claude/bin/project-record open <record>` prints, and run `project-record save <record>` after each edit. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
|
||||
|
||||
- **Until the goals file has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. In a README both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **Until the goals file has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning. In a README both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Keep a plan in `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **Read and change the plan's items only with `~/.claude/bin/todo-item`**, which lists, shows, files, edits, moves and finishes them; `todo-item --help` says how. It reads a plan in Jira as it does a file, and there it files and finishes an item but doesn't edit or move one yet. Two open the file itself: whoever plans a release, to compare Scores across releases, which `todo-item list` doesn't print; and whoever edits `## Scoring` or `## Renamed`, or reshapes an old table.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
|
||||
- **A client project's `CLAUDE.md` and `AGENTS.md` in its repo belong to its team.** Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in `AGENTS.md`. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the `decisions` record, as `rules/decisions.md` asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
|
||||
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; open `todo.md` only for what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in `todo.md`, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in the plan, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in the plan before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the row and detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item.
|
||||
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item.
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
|
||||
|
||||
## Shared goal
|
||||
@@ -25,7 +27,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its goals file states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
|
||||
**Achieve:** Code health: the code stays easy to read, change safely and debug, tomorrow and after seven years of development.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under the project's readability floor it is very important. The floor is 7.0, unless the project's config sets `readability-floor`.
|
||||
- Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
|
||||
- Why: a score that rises while changes still misread the code measures the wrong thing.
|
||||
|
||||
@@ -33,7 +35,7 @@ Fewer items shipped per release is a price this goal accepts, not a counter-sign
|
||||
|
||||
## Prose
|
||||
|
||||
Everything written — chat, commit messages, comments, docs, code — is in **English**. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
|
||||
Everything written — chat, commit messages, comments, docs, code — is in **English**. Where a project's config names another `language`, which `~/.claude/bin/project-config language` prints, the prose that project's readers see is in that language instead: its docs, comments, commit messages, pull requests and tracker text. These stay English: chat, names in code, a reviewer's report, and what a tool reads, which is the fixed words of a title, such as `Answer <pass> round <n>:`, `todo.md`'s table, and a record's headings, such as `## Unreleased`. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
|
||||
|
||||
1. **Easy to understand.** A reader with little time gets it on one read: one idea per sentence, and each term explained before it is used.
|
||||
2. **Most important first**, judged by what the reader wants to know first.
|
||||
@@ -44,7 +46,7 @@ Write the thing, not an introduction to it. State what holds and stop; name a re
|
||||
|
||||
Write negations as people say them: after a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
|
||||
|
||||
Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-review/standards/prose.md`.
|
||||
Reviewers hold prose to the full rules, with examples: `prose.md` in the project's review standards, which "Topic rules" below defines.
|
||||
|
||||
## Public API specs
|
||||
- Text in public API specs (OpenAPI `description`/`title` fields, in a spec file or in code, and the generated api-docs) is read by external consumers. Never leak internal references: no ticket IDs, internal URLs, repo/system code-names, "see ticket X". Describe behaviour in consumer terms. GOOD: `Deprecated alias for paymentAccountId`. BANNED: `…will be removed (ABC-123)`.
|
||||
@@ -56,27 +58,27 @@ Claude Code loads a rule file when a session writes a file its `paths:` frontmat
|
||||
|
||||
- The decision log: `~/.claude/rules/decisions.md`.
|
||||
- Goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`.
|
||||
- Plan items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`. Read it before you file, score, edit or move an item: a session that runs `todo-item` never opens `todo.md` itself, so the rule doesn't load.
|
||||
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, live in `~/.claude/skills/larv-review/standards/`.
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, are the project's review standards: the folder its config sets as `standards`, which `~/.claude/bin/project-config standards` prints.
|
||||
|
||||
## Working with the codebase
|
||||
- Always start a new git worktree when doing something in a codebase, and clean it up when done. Unless told otherwise, branch it off a freshly-updated default branch (`git fetch origin`, then base on `origin/main`), not whatever happens to be checked out.
|
||||
- Keep the project's main checkout (e.g. `~/code/log`, never a worktree) current: when it is behind `origin` — a merge landed, or a fetch shows it — run `git pull --ff-only` there instead of reporting the lag, never with `--autostash`: a dirty checkout is a finding to report, not to carry along.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host, unless the project's config sets `tooling-on-host = true` or a decision puts them there. Example: `docker compose run --rm app <tool> …`.
|
||||
- Tear down test containers after a run.
|
||||
- Give every container you start a memory limit and a swap limit, as large as its work needs: `--memory 4g --memory-swap 4g` on `docker run`, or `mem_limit` and `memswap_limit` in a compose file, scripts included. rule-hook checks only the `docker run` and `docker create` in your Bash commands.
|
||||
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. It also caps each container the command makes at the slot's share of memory, where the container sets no limits; give a container that needs more its own. Run the command in the background, since run-heavy's wait can outlast the Bash tool's timeout; `~/.claude/bin/wait-for <file> [<pattern>]` waits for a line in a log the command writes.
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a `todo.md` item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a plan item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
|
||||
1. A reviewer, a comprehension seat or the security pass: those loop-claude's prompt gives it. Given none, pass no model or effort, so it runs on your model.
|
||||
2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores `todo.md` items and that rung is higher.
|
||||
3. A subagent that files or scores `todo.md` items: what `~/.claude/bin/subagent-rung --plan <model> <L>` prints, which is never below the project's rung.
|
||||
2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores plan items and that rung is higher.
|
||||
3. A subagent that files or scores plan items: what `~/.claude/bin/subagent-rung --plan <model> <L>` prints, which is never below the project's rung.
|
||||
4. Any other: what `~/.claude/bin/subagent-rung <model> <L>` prints.
|
||||
- Escalate a task that proves too hard for your rung. Four escalation triggers say so:
|
||||
1. A re-score of the item's L, made on the project's rung or above, picks a rung above yours.
|
||||
2. The same failing test or finding survives two fix attempts.
|
||||
3. A pass reports a 🔴 in round 2.
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against larv-review's `standards/quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up"). It doesn't fire where the fix changes only prose (`larv-review` §3 says what is prose): fix that on your own rung.
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against the review standards' `quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up"). It doesn't fire where the fix changes only prose (`larv-review` §3 says what is prose): fix that on your own rung.
|
||||
|
||||
When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.
|
||||
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. A reviewer under `~/.claude/agents/` writes only its report, under `~/.local/state/larv-review/`, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to a folder it makes under the chunk's review folder (`~/.claude/bin/larv-review review-folder` prints it), and removes no image or file it did not create.
|
||||
@@ -90,11 +92,12 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
## Git, commits, and PRs
|
||||
- Mark no commit, PR, issue comment or file as the work of Claude, Anthropic or an agent.
|
||||
- Commit message and PR title: **one line**, prefixed with the ticket ID when the work has one. Example: `ABC-123 - Regression tests for GET /v4/clients`. Never include the repo/project name (like "twu-4") — we're already in that context.
|
||||
- Where the project's config names a `commit-title`, `pull-request-title` or `branch` template, fill it instead of following the formats in this section. `{summary}` is the one line that says what the change does, without a ticket ID, and `{id}` is the ID of the chunk's first item. A chunk without a plan item, such as a release review, works on a branch that doesn't fit the `branch` template, and its titles are the summary alone. `~/.claude/bin/project-config --help` describes the templates, and `chunk-preflight`'s facts quote them. A title a tool reads, such as `Answer <pass> round <n>: …`, `Drop item <ID>: …` or `Release review of <release>`, is the template's `{summary}`.
|
||||
- When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
|
||||
- PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
|
||||
- Branch for a ticket: exactly the ticket ID, nothing more. `ABC-123`, never `ABC-123-some-description`.
|
||||
- Branch for a `todo.md` item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them.
|
||||
- Where the project's config keeps a file in the config's folder, `~/.claude-projects/<key>/`, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title.
|
||||
- Branch for a plan item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them. Under a `branch` template, `chunk-preflight` names both by the template.
|
||||
- Where the project's config keeps a file in the config's folder, `~/.claude-projects/<key>/`, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Two chunks may commit there at once, so commit only that file: `git commit -m <title> -- <file>`, after `git add <file>` where it is new. Where git finds `index.lock` held, the other chunk is committing: try again. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title.
|
||||
- Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both.
|
||||
- On GitHub and Gitea, open a chunk's pull request as a draft, mark it ready and merge it with `~/.claude/bin/chunk-pr`, which picks `gh` or `tea` from the remote; `chunk-pr --help` says how. Once it has merged, run `chunk-pr clean` in the chunk's worktree: it removes the worktree and the branch and fast-forwards the main checkout.
|
||||
|
||||
@@ -111,7 +114,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
Claude Code reads this section by its heading when it compacts a conversation. Keep in the summary:
|
||||
|
||||
- what remains before the chunk is finished;
|
||||
- the task loop-claude gave, and each `todo.md` item the chunk takes with its L and E + I;
|
||||
- the task loop-claude gave, and each plan item the chunk takes with its L and E + I;
|
||||
- the worktree, branch and PR;
|
||||
- the rung loop-claude named for each review launch, rerun and escalated subagent;
|
||||
- each review pass's rounds so far, each open 🔴 and 🟡, and how the answered ones were answered;
|
||||
@@ -124,16 +127,17 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from the premises or the judge's records.
|
||||
- **gate** — the merge gate: the checks a PR passes before it merges.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`, which `~/.claude/bin/project-config goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal and in `loop-inbox`, for a decision that is theirs. They type a one-line answer in either, or `/talk` to open the worker's session with `claude --resume` where they typed it. A release ready to cut opens that session at once, on loop-claude's terminal. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`. Read it in the file `~/.claude/bin/project-record open goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, which the loop only reads.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or `/talk` to open the worker's session there with `claude --resume`. A release ready to cut opens that session at once. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/`, then those in the project's review standards.
|
||||
- **paired ruling** — the seats vote whether the project reads better, the same or worse at the branch's head than at the base, the commit `larv-review ruling-base` prints; `larv-review --help` says how the votes make the ruling.
|
||||
- **pass** — one kind of review a chunk may take, run in rounds by its reviewers until clean; `larv-review` §3 lists them.
|
||||
- **place** — the smallest addressable unit, such as a function or a section heading, that a seat names with its `path:line` when it judges how hard the project is to read there.
|
||||
- **plan** — the project's `todo.md`, at the path its config names as `plan`.
|
||||
- **plan** — where the project keeps its items, as the `plan` setting of its config names it: a `todo.md` at a path, or a Jira epic.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's goals file, with code health ("Shared goal") first among the goals unless the goals file voids it.
|
||||
- **project's rung** — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
|
||||
- **project record** — one of five documents a project keeps beside its plan, each where its config names it: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`.
|
||||
- **release** — a semver version the human cuts.
|
||||
- **release review** — a release's last chunk: the architecture and principles passes over the whole project, before the release is ready to cut; `larv-review` §3 → "Release review".
|
||||
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Claude Code configuration
|
||||
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `.claude/rules/` for the rules that load in this repo alone; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`, with the routing ladder they ship, `bin/model_routing/routing-ladder.json`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; `judge-field-trials/`, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; `stability-skip-count/`, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `.claude/rules/` for the rules that load in this repo alone; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to, which a project's config names as `principles` and `standards`; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`, with the routing ladder they ship, `bin/model_routing/routing-ladder.json`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; `judge-field-trials/`, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; `stability-skip-count/`, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
|
||||
|
||||
## Goals
|
||||
|
||||
@@ -71,15 +71,15 @@ git config filter.settings.clean bin/settings_filter.py
|
||||
|
||||
Then pick a model with `/model`.
|
||||
|
||||
Link `loop-claude` and `loop-inbox` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude` and `ln -s ~/.claude/bin/loop-inbox ~/.local/bin/loop-inbox`. Every claude they start, the interactive ones included, skips every permission prompt.
|
||||
Link `loop-claude` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude`. Every claude it starts, the interactive ones included, skips every permission prompt.
|
||||
|
||||
To get loop-claude's questions and stops as Mattermost DMs from a bot, write the server, the bot's token and your username into `~/.claude/.env`, in the keys `~/.claude/bin/mattermost-dm --help` names, and run `chmod 600 ~/.claude/.env`. Without that file, loop-claude sends no DM.
|
||||
To get loop-claude's questions and stops as DMs from a bot, write the bot's token, your username or member ID and, for Mattermost, the server into `~/.claude-projects/<key>.env`, in the keys `~/.claude/bin/notify --help` names, run `chmod 600` on it, and add `env-file = "~/.claude-projects/<key>.env"` and `notifier = "mattermost"` (or `"slack"`) to the project's config, as Install → "Set up a project" describes.
|
||||
|
||||
### Set up a project
|
||||
|
||||
Each project the loop runs in has a folder, `~/.claude-projects/<key>/`, where `<key>` is the project's name, and a config in it, `config.toml`. The folder is a git repo of its own, so the config has a history and a client's files never enter this repo. The loop commits each change it makes to a file there, such as the plan, in that repo, titled as its commits in the checkout. A project is a whole git checkout, never a subfolder of one.
|
||||
|
||||
The config names the project's main checkout and the path of every file the loop keeps for it. No setting has a default: `project-config` fails and names each setting a config leaves out. A path is `checkout:<path>` inside the checkout, `folder:<path>` inside the config's folder, or one that starts with `/` or `~/`. Every tool reads and writes each file at the path its setting gives, and `chunk-preflight` and `todo-item` print those paths for the agents. Keep each file's name, such as `todo.md`: the rules for a file load by its name. A project of your own keeps every file but the principles in its checkout:
|
||||
The config names the project's main checkout and the path of every file the loop keeps for it. No path setting has a default: `project-config` fails and names each setting a config leaves out. A path is `checkout:<path>` inside the checkout, `folder:<path>` inside the config's folder, or one that starts with `/` or `~/`. Every tool reads and writes each file at the path its setting gives, and `chunk-preflight` and `todo-item` print those paths for the agents. Five of the settings name the project's records: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`. Keep each file's name, such as `todo.md`: the rules for a file load by its name. A project of your own keeps every file but the principles and the review standards in its checkout:
|
||||
|
||||
```toml
|
||||
checkout = "~/code/log"
|
||||
@@ -92,10 +92,40 @@ reading-cost = "checkout:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "checkout:README.md"
|
||||
principles = "~/.claude/principles"
|
||||
standards = "~/.claude/skills/larv-review/standards"
|
||||
```
|
||||
|
||||
`principles` and `standards` name the folders the reviewers hold the project to: the technical principles and the review standards. Both ship with this setup, at the paths above. A folder of your own replaces the shipped one. A standards folder must hold `quality.md`, `prose.md`, `comments.md` and `readme.md`, since the reviewers and the rules name those files.
|
||||
|
||||
A project may also set `env-file`, the file of `KEY=value` credentials its tools read, such as `env-file = "~/.claude-projects/log.env"`. It is a path that starts with `/` or `~/`, outside the checkout and the config's folder, so that no git remote receives it. A tool that needs a key fails and names each one the file lacks. No failure message, prompt, log line or archived loop output holds a token from the file. rule-hook refuses a Read or a Grep of the file and a Bash command that names it or searches a folder holding it with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so a worker doesn't read it in passing; `rule-hook --help` says which calls it checks. A project without the setting has no credentials, and never reads another project's. `project-config env-file` prints the path.
|
||||
|
||||
A project may also set `touch-predictions`, a path spelt as `changelog`'s is, such as `touch-predictions = "checkout:docs/touch-predictions.md"`. `touch-predictions record` appends each chunk's predicted files and parts there, beside those it touched. A project that leaves it out keeps no such record.
|
||||
|
||||
A project may also set `notifier` to `"mattermost"` or `"slack"`, the service that sends loop-claude's DMs. The `env-file` then holds that service's keys. A project that sets none gets no DMs, whatever its env file holds. `project-config notifier` prints the setting.
|
||||
|
||||
A project's config may set four more things, each optional, as `project-config --help` describes. `language` names the language its owners write in, where that isn't English: the worker writes the project's prose in it, and the prose reviewer judges the prose in it. `commit-title`, `pull-request-title` and `branch` are templates for a project that titles and names these in another way than `CLAUDE.md` → "Git, commits, and PRs" says. `chunk-preflight` names the branch and the worktree by the `branch` template. On a branch that fits it, rule-hook refuses a commit, and `chunk-pr` a pull request, whose title doesn't fit its template; on any other branch, such as a release review's, a title is the summary alone. A tool that reads a commit title, such as a round's `Answer <pass> round <n>:`, reads the template's `{summary}`: it tries `commit-title`, then `pull-request-title`, since a squash merge titles the commit as the pull request, then takes the title whole. While a project's config holds a fault, rule-hook refuses every commit there, and the tools that read its titles fail naming the fault.
|
||||
|
||||
A legacy project with no container setup sets `tooling-on-host = true`, so the loop runs its language runtime, package manager, tests and task runner directly on the host. One whose code the comprehension panel scores low may lower `readability-floor` from 7.0: under it, the ranking weighs code health 4 times as much, and a scoring run asks for a floor item.
|
||||
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
A client that plans in Jira Cloud names an epic as its project's plan: `plan = "jira:https://acme.atlassian.net/browse/ABC-12"`, which is `jira:` and the epic's address as the browser shows it. The plan is then the epic's open child issues, in Jira's backlog order, which the team sets. An issue in a done status is a finished item. Each part of an item comes from one part of its issue:
|
||||
|
||||
- The ID is the issue's number, so every child must be in the epic's own Jira project.
|
||||
- The tagline is the summary.
|
||||
- The detail is the description, which a docker container converts to markdown.
|
||||
- The release is the earliest Fix Version named as a semver version, such as `1.2.0`. Every open child needs one.
|
||||
- A blocker is an "is blocked by" link to another open child.
|
||||
- The scores are the issue property `plan-item`, a JSON object such as `{"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}`. An issue without it reads as an item nobody scored yet.
|
||||
|
||||
A read fails, naming the issue, where a child is in another Jira project or names no such Fix Version. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account, and only its owner may read that file: `chmod 600` it. The loop reads such a plan and files items into it, each as a Task under the epic, and doesn't edit an issue yet. `todo-item edit` and `move` fail, so edit its issues in Jira. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. `todo-item add` needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. `rank_todo.py` doesn't rank it, since Jira's backlog does. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
|
||||
|
||||
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. Such a config keeps its plan in Jira too, and reads both with the same `env-file`. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor. The loop only reads the description, so edit it in Jira; `project-record open goals-and-audience` prints a file holding its text. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
|
||||
|
||||
To name a chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`, set these three templates, with your Jira project's key in place of `ABC`: `branch = "ABC-{id}"`, `commit-title = "ABC-{id} - {summary}"` and `pull-request-title = "ABC-{id} - {summary}"`. `project-config --help` says how the templates work.
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.claude-projects/acme && cd ~/.claude-projects/acme
|
||||
git init
|
||||
@@ -132,7 +162,7 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
|
||||
|
||||
## Tools
|
||||
|
||||
Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
|
||||
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
|
||||
|
||||
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere; once it is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
|
||||
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
|
||||
@@ -141,26 +171,28 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
|
||||
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints what each rung a review climbs to misses, and the lowest rung below them that, like each candidate above it, returns them; `judge-replay --help` states the replay.
|
||||
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
|
||||
- `loop-claude <task>` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract.
|
||||
- `loop-inbox` shows the interrupts of every loop-claude on the machine, oldest first, takes each one's answer, `/talk` included, and lists every running loop with the `todo.md` items its chunk takes; `loop-inbox --help` states how.
|
||||
- `mattermost-dm [<message>]` sends a message, or else stdin, from the Mattermost bot to the human; `~/.claude/.env` names the server, the bot's token and the human, and `mattermost-dm --help` names its keys. `loop-claude --help` says when loop-claude sends one.
|
||||
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
|
||||
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
|
||||
- `notify [<message>]` sends a message, or else stdin, as a DM from the bot of the project's `notifier`, Mattermost or Slack, to the human; the project's `env-file` holds the bot's token, the recipient and, for Mattermost, the server, and `notify --help` names its keys. `loop-claude --help` says when loop-claude sends one.
|
||||
- `project-config [<setting>]` prints the paths a project's config sets, or the one asked for, and fails naming each setting the config leaves out; Install → "Set up a project" shows a config.
|
||||
- `project-record open <record>` prints the path of a file holding one of a project's records, for an agent to read and edit, and `project-record save <record>` stores the edit; for a record kept as a file, that file is the record. `goals-and-audience` opens the goals file the same way.
|
||||
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`, by default the one its config names; `rank_todo.py --help` states the format.
|
||||
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
|
||||
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, qualifies: it finds no less of the 🔴 and 🟡 findings than two replays on the project's rung find, within a margin, and misses no 🔴 that both found. `review-replay --help` states the replay. With `--omit-claude-md` it tests instead whether the pass's reviewer may start without `CLAUDE.md`: it replays each round three times as archived and once without the instruction files, and prints whether the reviewer passes: whether the last replay missed no more findings than the most an unchanged replay missed, with each count and each finding it missed. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, Grep, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `run-heavy <command>` runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares; `run-heavy --help` states the slots, and the memory cap it gives a container that sets no limit.
|
||||
- `run-tests [<pytest args>...]` runs this repo's test suite, as Test says.
|
||||
- `score-outcomes [L E I S]` shows what each finished item's chunk measured beside the scores the item was guessed at, to score a new item by. Per chunk it also shows code health's two counter-signals, misread findings and later fixes, and how many of the human's answers reversed a worker's choice; `score-outcomes --help` states the report.
|
||||
- `settings_filter.py` is git's clean filter for `settings.json`: it drops `"model"` and sorts the keys. `.gitattributes` sets the filter `settings` on `settings.json`, and Install's `git config` line makes this script that filter.
|
||||
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
|
||||
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model on the project's routing ladder, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
|
||||
- `todo-item add …` files an item in a project's `todo.md`, taking `Next ID` as the item's ID, and `todo-item finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`; both rank the file. `todo-item show <ID>` prints an item's row and detail. `todo-item --help` states the flags.
|
||||
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`. Each change ranks a markdown plan. `todo-item --help` states the flags.
|
||||
- `touch-predictions record <ID>...` appends what a chunk's items were predicted to touch, under `Touches:` in their details, beside the files and parts its branch touched, to the record the config names as `touch-predictions`; `touch-predictions --help` shows the spelling and how a part is named. `chunk-preflight` reads the same predictions to name the items that may start chunks at once.
|
||||
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
|
||||
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `mattermost_dm/`, `model_routing/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool.
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool.
|
||||
|
||||
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
|
||||
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
|
||||
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
|
||||
- `chunk_pr` imports `deploy_release`'s forge calls, and `forge_of` as `deploy_release` does.
|
||||
@@ -168,14 +200,17 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
|
||||
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
|
||||
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
|
||||
- `loop_claude` runs `chunk-preflight` as a process of its own.
|
||||
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, loop-inbox, both replay tools and `reviewer-merge-trials`' driver use it.
|
||||
- `loop_state/` holds the files loop-claude and loop-inbox share: the question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), their paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes both tools.
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
|
||||
- `mattermost_dm/` sends the human a Mattermost DM, for `mattermost-dm` and for loop-claude through `loop_effects`.
|
||||
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, both replay tools and `reviewer-merge-trials`' driver use it.
|
||||
- `loop_state/` holds where loop-claude keeps its files (`paths.py`), which `rung_replay` reads too.
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy` and `adf_codec`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
|
||||
- `model_routing/` holds the shipped routing ladder (`routing-ladder.json`) and its steps (`ladder.py`), and reads a ladder from that file or a project's own (`ladder_file.py`), for loop-claude, `rule_hook`, both replay tools and `subagent-rung`. It finds a project's config folder through `project_config`. It also holds the list prices, which `routing_figures` and `transcript_archive` read.
|
||||
- `notifier/` sends the human a DM through the notifier a project's config names, for `notify` and for loop-claude through `loop_effects`; `mattermost_dm/` and `slack_dm/` are its two backends.
|
||||
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`), with the markdown file's edits in `markdown_edits.py`. `contract.py` holds the tests every backend that writes must pass, which `jira_epic.py` doesn't yet, and `fakes.py` a plan in memory.
|
||||
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
|
||||
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` reads, ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py`, `rule_hook` and `todo_item`.
|
||||
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`): a markdown file, a Confluence Cloud page (`confluence_page.py`), or, for the goals, a Jira epic's description (`jira_description.py`). `contract.py` holds the tests every backend must pass, and `fakes.py` a store in memory that the tests of other tools use.
|
||||
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py` and `rule_hook`.
|
||||
- `repo_checks/` tests the repo itself.
|
||||
- `rest_client/` sends a JSON request to a REST API and reads its credentials from an env file, for `mattermost_dm`, `slack_dm`, `plan_store` and `record_store`.
|
||||
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
|
||||
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
|
||||
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `loop_claude`'s retry count and models file, and finds that file through `loop_state`'s paths.
|
||||
|
||||
@@ -7,9 +7,9 @@ omitClaudeMd: true
|
||||
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under `## Goals` in the file your prompt's `Goals and audience:` line names, with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, or one principles file, every principle in it.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and `todo.md` first, then all of the project's code, config, tests and CI.
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and the plan first, then all of the project's code, config, tests and CI. Your prompt's `Plan:` line names the plan.
|
||||
|
||||
- Per principle or goal: every place the project departs from it, with file:line, the defect in one sentence and its concrete consequence. Then one line: followed, mostly, not followed, or does not apply and why.
|
||||
- A departure a `todo.md` item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the `todo.md` item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- A departure a plan item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the plan item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- Report under one heading per yardstick.
|
||||
|
||||
@@ -47,7 +47,7 @@ Before anything else, **read the technical principles** in the folder your promp
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Report only a defect a persona hits; a requirement that the change breaks, of the plan, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
Report only a defect a persona hits; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -9,19 +9,21 @@ You read the prose as someone who did not write it: you see only what it says, n
|
||||
|
||||
The bar, read each time, since it changes:
|
||||
|
||||
- every file under `~/.claude/skills/larv-review/standards/`, of `quality.md` only "A false claim is a bug";
|
||||
- every file in the folder your prompt's `Review standards:` line names, of `quality.md` only "A false claim is a bug";
|
||||
- `~/.claude/CLAUDE.md` → "Public API specs";
|
||||
- each file under `~/.claude/rules/` whose `paths:` frontmatter matches a file the diff changes.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
|
||||
|
||||
Your prompt's `Prose language:` line names the language the project's config sets. Apply every check below to prose in that language, by that language's grammar and idiom. The bar's examples are English: find the same fault in the other language, never the same English words. Prose in another language is a finding, except what `prose.md` in the review standards says stays English. Write your report in English.
|
||||
|
||||
## Checks, in priority order
|
||||
|
||||
Run them in this order. A fix for a later check never breaks an earlier one.
|
||||
|
||||
1. **Easy to understand.** Read each sentence once, cold. A sentence you had to reread, a term used before it is explained, or an "it" or "them" that could point at two things is a finding. Fix: **Rewrite**, giving the plain sentence.
|
||||
2. **Most important first.** Name the document's reader and what they want to know first. Check that the sections run in that order, then the paragraphs within each section, then the items within each list. If not, fix: **Reorder**, naming the new order. A section so long that a reader has to search it gets sub-headings or an index. Fix: **Split**.
|
||||
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md` unless a project principle there covers it, and a goal to the README. A pointer standing where a definition belongs (`~/.claude/skills/larv-review/standards/comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
|
||||
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md` unless a project principle there covers it, and a goal to the README. A pointer standing where a definition belongs (the review standards' `comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
|
||||
4. **Short.** Words that do not clearly help 1–3 fail. Fix: **Cut**.
|
||||
|
||||
Also report a list whose order carries no meaning and is not sorted (the technical principles' "Deterministic order", in the folder your prompt's `Technical principles:` line names; without one, open your report by saying so), a sentence contradicting another, a claim the code shows false, and a word used against `CLAUDE.md` → "Vocabulary".
|
||||
|
||||
@@ -11,9 +11,9 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
|
||||
## First Steps
|
||||
|
||||
1. **Scope the change.** You review every PR; a fresh invocation has no prior context, so determine the diff yourself. Diff the PR branch against its base (`gh pr diff`, or `git merge-base <base> HEAD` then `git diff`), and review the changed lines **plus enough surrounding code and callers** to judge correctness — read the whole changed file when practical; a diff alone hides whether a caller breaks. Read the PR description and, when the project uses an issue tracker (project-specific — check its docs) and the change references a ticket, that ticket: the diff is judged against its stated intent, and a scope mismatch in either direction is a finding — claimed-but-unimplemented, and implemented-but-unasked (#2).
|
||||
2. **Read every file in the folder your prompt's `Technical principles:` line names**, and `~/.claude/skills/larv-review/standards/quality.md`. These are mandatory guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently. Where your prompt has no such line, without one, open your report by saying so.
|
||||
2. **Read every file in the folder your prompt's `Technical principles:` line names**, and `quality.md` in the folder your prompt's `Review standards:` line names. These are mandatory guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently. Where your prompt lacks either line, open your report by saying so.
|
||||
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you run them unless your prompt hands you a passing run on the head (step 4).
|
||||
4. **Verify, don't just read.** Where your prompt hands you the commit on which the worker's run of the test suite and static analysis last passed, and it is the head, don't run them again, and say so in Coverage & Verification. Otherwise run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; don't delete anything else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
|
||||
4. **Verify, don't just read.** Where your prompt hands you the commit on which the worker's run of the test suite and static analysis last passed, and it is the head, don't run them again, and say so in Coverage & Verification. Otherwise run the test suite and static analysis/linters through the project's container tooling, unless `~/.claude/bin/project-config tooling-on-host` prints true or a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; don't delete anything else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
|
||||
5. **Judge the surviving mutants.** Your prompt hands you what the project's mutation command printed on the change, with the commit it ran on: the mutants of changed lines that no test kills, or the message of a run that failed. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch. Where the prompt doesn't hand you any output, or names a commit other than the head, run the command yourself in the change's checkout, through run-heavy as in step 4: the one the project's README documents, else `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix '<how the project runs its tools>'`. `~/.claude/bin/mutate-changes --help` says which tool it runs for each language, how to set `--jobs`, and what it prints. Mutation-test the changed code that no run mutated, in a language mutate-changes doesn't cover or where a run failed, with a widely deployed mutation tool limited to the changed lines, else with mutants you make by hand. Report the wall time and mutant count in Coverage & Verification, or why nothing was mutated.
|
||||
6. **Two passes minimum, then hunt absences.**
|
||||
- *Breadth:* every hunk in every changed file, no skimming. Track which files you have covered; batch large diffs, never truncate the review.
|
||||
@@ -130,7 +130,7 @@ Every PR gets at least this sweep.
|
||||
|
||||
## Output Format
|
||||
|
||||
Report only a defect; a requirement that the change breaks, of the plan, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
Report only a defect; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with:
|
||||
- **Location**: File and line/function
|
||||
|
||||
@@ -184,7 +184,7 @@ This is where unjustified duplication and accidental complexity get caught. Run
|
||||
6. **Price the reasoned complexity too.** Essential-looking complexity has a requirement behind it. For each hotspot that survives the steps above, name that requirement, then sketch the design without it. When a much simpler near-equivalent exists, report the trade as a finding: the simpler shape, the exact functionality delta, and the complexity saved. A requirement nobody has priced is not a decision — offer the trade once, plainly, and let the owner accept or reject it.
|
||||
7. **Hunt the imagined requirement.** The step above prices complexity a real requirement forces; this one removes complexity no requirement forces. For every abstraction, indirection, configuration point, and layer of generality, name the present, Stage 0-recorded requirement it serves. An interface with one implementation, a plugin system with one plugin, a cache or shard — or a load-testing rig — for load nobody recorded, a canary rig for a blast radius nobody recorded, "in case we swap the database" — speculative generality is the over-engineered twin of copy-paste drift: complexity nobody's requirement chose. The future that justifies flexibility must be a recorded goal or horizon, not the author's imagination — and the shorter the horizon, the harder this step cuts. Rate removals with the same severity as unreasoned duplication.
|
||||
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no `todo.md` item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no plan item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
|
||||
## Communication Style
|
||||
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
"""Converts markdown to ADF (Atlassian Document Format, the rich text of Jira Cloud and Confluence) and back.
|
||||
|
||||
It runs @larvit/adf-codec, a Node package, in a throwaway container that holds node_shim/shim.mjs; the shim's header says what its exit status means.
|
||||
"""
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from machine_load.slots import HELD, slot_count, slot_folder, usable_cpus, waited_slot
|
||||
|
||||
SHIM = pathlib.Path(__file__).resolve().parent / "node_shim"
|
||||
SHIM_FILES = ("Dockerfile", "package.json", "package-lock.json", "shim.mjs")
|
||||
# `--memory` and `--memory-swap` both take this, so the container can't swap: a document too big for it ends in a Failure.
|
||||
MEMORY = "256m"
|
||||
RUN_SECONDS = 60
|
||||
BUILD_SECONDS = 300
|
||||
REFUSED = 2
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Ran:
|
||||
status: int
|
||||
out: str
|
||||
err: str
|
||||
|
||||
|
||||
# Runs the shim in the given mode (`to-adf` or `to-markdown`) on a text, or fails to run it.
|
||||
Run = typing.Callable[[str, str], Ran | Failure]
|
||||
# Runs a docker command line on a text, in at most the given seconds, or fails to run it.
|
||||
Docker = typing.Callable[[list[str], str, int], Ran | Failure]
|
||||
# Holds one of the machine's heavy slots for a with block, or yields why none could be taken.
|
||||
Slot = typing.Callable[[], typing.ContextManager[Failure | None]]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Refused:
|
||||
"""Why adf-codec refused one of the documents handed to adfs_to_markdown, and that document's index among them."""
|
||||
index: int
|
||||
failure: Failure
|
||||
|
||||
|
||||
def image_tag(shim: pathlib.Path) -> str:
|
||||
"""A tag that changes with every file the image is built from, so an edited shim or a bumped adf-codec builds a new image."""
|
||||
digest = hashlib.sha256()
|
||||
for name in SHIM_FILES:
|
||||
digest.update((shim / name).read_bytes())
|
||||
return f"claude-config-adf-codec:{digest.hexdigest()[:12]}"
|
||||
|
||||
|
||||
def docker_args(image: str, mode: str) -> list[str]:
|
||||
return ["docker", "run", "--rm", "-i", "--memory", MEMORY, "--memory-swap", MEMORY, "--network", "none", "--read-only", image, mode]
|
||||
|
||||
|
||||
def docker(args: list[str], text: str, seconds: int, call: typing.Callable[..., typing.Any] = subprocess.run) -> Ran | Failure:
|
||||
try:
|
||||
done = call(args, input=text, capture_output=True, text=True, encoding="utf-8", timeout=seconds)
|
||||
except FileNotFoundError:
|
||||
return Failure("docker is not installed, and the adf-codec shim runs in a container")
|
||||
except subprocess.TimeoutExpired:
|
||||
return Failure(f"`{' '.join(args[:2])}` took more than {seconds} seconds")
|
||||
return Ran(done.returncode, done.stdout, done.stderr)
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def heavy_slot(env: typing.Mapping[str, str] = os.environ, slots: int | None = None) -> typing.Iterator[Failure | None]:
|
||||
"""Holds one of the machine's heavy slots, which run-heavy shares, for the with block. Under run-heavy the process already holds one, so it doesn't wait."""
|
||||
if HELD in env:
|
||||
yield None
|
||||
return
|
||||
folder = slot_folder(env, pathlib.Path.home())
|
||||
count = slot_count(usable_cpus()) if slots is None else slots
|
||||
try:
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
_, fd = waited_slot(folder, count, lambda: print(f"adf-codec: waiting for a heavy slot, of {count} on this machine, in {folder}, to build the shim's image; `fuser {folder}/slot-*` names the processes that hold them", file=sys.stderr, flush=True))
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot take a heavy slot in {folder}: {failure.strerror}")
|
||||
return
|
||||
try:
|
||||
yield None
|
||||
finally:
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def ensure_image(shim: pathlib.Path, run_docker: Docker = docker, slot: Slot = heavy_slot) -> str | Failure:
|
||||
"""The tag of the image for the shim folder, built from that folder first where this machine has no image under that tag.
|
||||
|
||||
The build waits for a heavy slot. Once this process holds the slot, it inspects again, as another process may have built the image meanwhile."""
|
||||
tag = image_tag(shim)
|
||||
found = image_found(tag, run_docker)
|
||||
if found is not False:
|
||||
return tag if found is True else found
|
||||
with slot() as refused:
|
||||
if refused is not None:
|
||||
return refused
|
||||
found = image_found(tag, run_docker)
|
||||
if found is not False:
|
||||
return tag if found is True else found
|
||||
return build_image(shim, tag, run_docker)
|
||||
|
||||
|
||||
def image_found(tag: str, run_docker: Docker) -> bool | Failure:
|
||||
found = run_docker(["docker", "image", "inspect", tag], "", RUN_SECONDS)
|
||||
return found if isinstance(found, Failure) else found.status == 0
|
||||
|
||||
|
||||
def build_image(shim: pathlib.Path, tag: str, run_docker: Docker) -> str | Failure:
|
||||
ran = run_docker(["docker", "build", "--quiet", "--memory", "1g", "--memory-swap", "1g", "--tag", tag, str(shim)], "", BUILD_SECONDS)
|
||||
if isinstance(ran, Failure):
|
||||
return ran
|
||||
if ran.status != 0:
|
||||
return Failure(f"building the adf-codec shim's image failed with exit {ran.status}: {ran.err.strip()}")
|
||||
return tag
|
||||
|
||||
|
||||
def container_run(mode: str, text: str, run_docker: Docker = docker, shim: pathlib.Path = SHIM) -> Ran | Failure:
|
||||
image = ensure_image(shim, run_docker)
|
||||
if isinstance(image, Failure):
|
||||
return image
|
||||
return run_docker(docker_args(image, mode), text, RUN_SECONDS)
|
||||
|
||||
|
||||
def answer(mode: str, text: str, run: Run) -> str | Refused | Failure:
|
||||
"""What the shim printed for text, or why it gave no answer: a Refused where it named the refused document's index."""
|
||||
ran = run(mode, text)
|
||||
if isinstance(ran, Failure):
|
||||
return ran
|
||||
if ran.status == 0:
|
||||
return ran.out
|
||||
if ran.status == REFUSED:
|
||||
return refusal(ran.out)
|
||||
return Failure(f"the adf-codec shim failed with exit {ran.status}: {ran.err.strip()}")
|
||||
|
||||
|
||||
def refusal(out: str) -> Refused | Failure:
|
||||
try:
|
||||
refused = json.loads(out)
|
||||
error = refused["error"]
|
||||
where = f"line {error['position']['line']}" if "position" in error else ".".join(str(step) for step in error["path"]) or "the document"
|
||||
failure = Failure(f"adf-codec refused the input with {error['code']}: {error['message']} (at {where})")
|
||||
return Refused(refused["index"], failure) if isinstance(refused.get("index"), int) else failure
|
||||
except (ValueError, KeyError, TypeError, AttributeError):
|
||||
return Failure(f"the adf-codec shim refused with output that is not an error: {out.strip()}")
|
||||
|
||||
|
||||
def markdown_to_adf(markdown: str, run: Run = container_run) -> dict[str, typing.Any] | Failure:
|
||||
"""The ADF document for the markdown."""
|
||||
out = answer("to-adf", markdown, run)
|
||||
if isinstance(out, Refused):
|
||||
return out.failure
|
||||
if isinstance(out, Failure):
|
||||
return out
|
||||
try:
|
||||
document = json.loads(out)
|
||||
except ValueError:
|
||||
return Failure(f"the adf-codec shim printed output that is not JSON: {out.strip()}")
|
||||
return document
|
||||
|
||||
|
||||
def adfs_to_markdown(documents: list[dict[str, typing.Any]], run: Run = container_run) -> list[str] | Refused | Failure:
|
||||
"""The markdown for each ADF document, in their order, from one container run, so a caller with many documents pays one container start."""
|
||||
if not documents:
|
||||
return []
|
||||
out = answer("to-markdown", json.dumps(documents), run)
|
||||
if isinstance(out, Refused) and not 0 <= out.index < len(documents):
|
||||
return Failure(f"the adf-codec shim refused a document at index {out.index}, past the {len(documents)} it was handed")
|
||||
if isinstance(out, Refused | Failure):
|
||||
return out
|
||||
try:
|
||||
texts = json.loads(out)
|
||||
except ValueError:
|
||||
texts = None
|
||||
if not isinstance(texts, list) or len(texts) != len(documents) or not all(isinstance(text, str) for text in texts):
|
||||
return Failure(f"the adf-codec shim printed output that is not a JSON array of {len(documents)} texts: {out.strip()}")
|
||||
return texts
|
||||
|
||||
|
||||
def adf_to_markdown(document: dict[str, typing.Any], run: Run = container_run) -> str | Failure:
|
||||
"""The markdown for the ADF document."""
|
||||
texts = adfs_to_markdown([document], run)
|
||||
if isinstance(texts, Refused):
|
||||
return texts.failure
|
||||
return texts if isinstance(texts, Failure) else texts[0]
|
||||
@@ -0,0 +1,9 @@
|
||||
FROM node:24.19.0-alpine3.24
|
||||
WORKDIR /shim
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm ci --ignore-scripts --omit=dev
|
||||
COPY shim.mjs ./
|
||||
USER node
|
||||
# The deadline is inside the container, since a timeout in the caller kills only the docker client and leaves the container running.
|
||||
# It is under convert.py's RUN_SECONDS, so it fires first.
|
||||
ENTRYPOINT ["timeout", "50", "node", "shim.mjs"]
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "adf-codec-shim",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "adf-codec-shim",
|
||||
"dependencies": {
|
||||
"@larvit/adf-codec": "0.3.1"
|
||||
}
|
||||
},
|
||||
"node_modules/@larvit/adf-codec": {
|
||||
"version": "0.3.1",
|
||||
"resolved": "https://registry.npmjs.org/@larvit/adf-codec/-/adf-codec-0.3.1.tgz",
|
||||
"integrity": "sha512-hI15WrztaGU90nEc2+IeFj16LtqpTxb2hahdhfj/YvdFTwd2lzhdQN1MRG4/65i6FiEZR2lIlFxyIYqx6EXjvg==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "adf-codec-shim",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"dependencies": {
|
||||
"@larvit/adf-codec": "0.3.1"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
// Converts between markdown and ADF with @larvit/adf-codec's portable calls. The mode is the one argument:
|
||||
// to-adf stdin is markdown, stdout is the ADF document as JSON
|
||||
// to-markdown stdin is a JSON array of ADF documents, stdout a JSON array of their markdown texts, in their order
|
||||
// Exit 0: stdout holds the answer. Exit 2: adf-codec refused the input, and stdout holds {"error": {code, message, path, position?}},
|
||||
// with "index", the refused document's place in the array, beside "error" in to-markdown.
|
||||
// Exit 1: the shim could not run, and stderr says why.
|
||||
import { adfToPortableMarkdown, portableMarkdownToAdf } from '@larvit/adf-codec'
|
||||
|
||||
const REFUSED = 2
|
||||
|
||||
async function readStdin() {
|
||||
const chunks = []
|
||||
for await (const chunk of process.stdin) chunks.push(chunk)
|
||||
return Buffer.concat(chunks).toString('utf8')
|
||||
}
|
||||
|
||||
function refuse(refusal) {
|
||||
process.stdout.write(JSON.stringify(refusal))
|
||||
return REFUSED
|
||||
}
|
||||
|
||||
function toAdf(markdown) {
|
||||
const result = portableMarkdownToAdf(markdown)
|
||||
if (!result.ok) return refuse({ error: result.error })
|
||||
process.stdout.write(JSON.stringify(result.value))
|
||||
return 0
|
||||
}
|
||||
|
||||
function toMarkdown(documents) {
|
||||
const texts = []
|
||||
for (const [index, document] of documents.entries()) {
|
||||
const result = adfToPortableMarkdown(document)
|
||||
if (!result.ok) return refuse({ index, error: result.error })
|
||||
texts.push(result.value)
|
||||
}
|
||||
process.stdout.write(JSON.stringify(texts))
|
||||
return 0
|
||||
}
|
||||
|
||||
async function main(mode) {
|
||||
const input = await readStdin()
|
||||
if (mode === 'to-adf') return toAdf(input)
|
||||
if (mode === 'to-markdown') return toMarkdown(JSON.parse(input))
|
||||
throw new Error(`mode must be to-adf or to-markdown, not ${mode}`)
|
||||
}
|
||||
|
||||
main(process.argv[2]).then(
|
||||
(code) => { process.exitCode = code },
|
||||
(failure) => {
|
||||
process.stderr.write(`${failure instanceof Error ? failure.message : failure}\n`)
|
||||
process.exitCode = 1
|
||||
},
|
||||
)
|
||||
@@ -0,0 +1,281 @@
|
||||
import contextlib
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
|
||||
import pytest
|
||||
|
||||
from adf_codec import convert
|
||||
from failure import Failure
|
||||
from machine_load import slots
|
||||
|
||||
DOC = {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Hi"}]}]}
|
||||
|
||||
|
||||
def fake(status: int, out: str = "", err: str = ""):
|
||||
calls: list[tuple[str, str]] = []
|
||||
|
||||
def run(mode: str, text: str) -> convert.Ran:
|
||||
calls.append((mode, text))
|
||||
return convert.Ran(status, out, err)
|
||||
|
||||
run.calls = calls # type: ignore[attr-defined]
|
||||
return run
|
||||
|
||||
|
||||
def test_markdown_to_adf_returns_the_document_the_shim_printed():
|
||||
run = fake(0, json.dumps(DOC))
|
||||
assert convert.markdown_to_adf("Hi\n", run) == DOC
|
||||
assert run.calls == [("to-adf", "Hi\n")]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_sends_every_document_in_one_run_and_returns_the_texts_in_order():
|
||||
run = fake(0, json.dumps(["Hi\n", "Yo\n"]))
|
||||
assert convert.adfs_to_markdown([DOC, DOC], run) == ["Hi\n", "Yo\n"]
|
||||
assert run.calls == [("to-markdown", json.dumps([DOC, DOC]))]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_of_no_documents_runs_no_container():
|
||||
run = fake(1)
|
||||
assert convert.adfs_to_markdown([], run) == []
|
||||
assert run.calls == []
|
||||
|
||||
|
||||
def test_a_refused_document_names_its_index():
|
||||
refusal = {"index": 1, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
refused = convert.adfs_to_markdown([DOC, DOC], fake(2, json.dumps(refusal)))
|
||||
assert refused == convert.Refused(1, Failure("adf-codec refused the input with not-an-adf-document: no type (at the document)"))
|
||||
|
||||
|
||||
def test_a_refusal_whose_index_is_past_the_documents_becomes_a_failure():
|
||||
refusal = {"index": 2, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
failure = convert.adfs_to_markdown([DOC, DOC], fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("the adf-codec shim refused a document at index 2, past the 2 it was handed")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("out", ["not json", json.dumps(["Hi\n"]), json.dumps({"0": "Hi\n"}), json.dumps(["Hi\n", 7])])
|
||||
def test_texts_that_do_not_match_the_documents_become_a_failure(out):
|
||||
failure = convert.adfs_to_markdown([DOC, DOC], fake(0, out))
|
||||
assert failure == Failure(f"the adf-codec shim printed output that is not a JSON array of 2 texts: {out}")
|
||||
|
||||
|
||||
def test_adf_to_markdown_returns_the_text_of_its_one_document():
|
||||
run = fake(0, json.dumps(["Hi\n"]))
|
||||
assert convert.adf_to_markdown(DOC, run) == "Hi\n"
|
||||
assert run.calls == [("to-markdown", json.dumps([DOC]))]
|
||||
|
||||
|
||||
def test_a_refusal_becomes_a_failure_with_adf_codecs_code_and_message():
|
||||
refusal = {"error": {"code": "malformed-pipe-table", "message": "row has too many cells", "path": [], "position": {"line": 3, "offset": 9}}}
|
||||
failure = convert.markdown_to_adf("| a |\n", fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with malformed-pipe-table: row has too many cells (at line 3)")
|
||||
|
||||
|
||||
def test_a_refusal_without_a_position_names_the_path():
|
||||
refusal = {"index": 0, "error": {"code": "unsupported-node-shape", "message": "bad node", "path": ["content", 0]}}
|
||||
failure = convert.adf_to_markdown(DOC, fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with unsupported-node-shape: bad node (at content.0)")
|
||||
|
||||
|
||||
def test_a_shim_that_could_not_run_becomes_a_failure_with_its_stderr():
|
||||
failure = convert.adf_to_markdown(DOC, fake(1, "", "Unexpected token"))
|
||||
assert failure == Failure("the adf-codec shim failed with exit 1: Unexpected token")
|
||||
|
||||
|
||||
def test_a_shim_killed_for_memory_becomes_a_failure_with_its_exit_status():
|
||||
failure = convert.markdown_to_adf("x", fake(137))
|
||||
assert isinstance(failure, Failure) and "137" in failure.reason
|
||||
|
||||
|
||||
def test_output_that_is_not_json_becomes_a_failure():
|
||||
failure = convert.markdown_to_adf("x", fake(0, "not json"))
|
||||
assert failure == Failure("the adf-codec shim printed output that is not JSON: not json")
|
||||
|
||||
|
||||
def test_a_refusal_that_is_not_the_expected_json_becomes_a_failure():
|
||||
failure = convert.markdown_to_adf("x", fake(2, "oops"))
|
||||
assert failure == Failure("the adf-codec shim refused with output that is not an error: oops")
|
||||
|
||||
|
||||
def test_a_failure_from_the_runner_passes_through():
|
||||
def run(mode: str, text: str) -> Failure:
|
||||
return Failure("docker is not installed")
|
||||
|
||||
assert convert.markdown_to_adf("x", run) == Failure("docker is not installed")
|
||||
|
||||
|
||||
def test_the_image_tag_changes_with_the_shim_files(tmp_path):
|
||||
for name in convert.SHIM_FILES:
|
||||
(tmp_path / name).write_text("a")
|
||||
before = convert.image_tag(tmp_path)
|
||||
(tmp_path / "shim.mjs").write_text("b")
|
||||
assert convert.image_tag(tmp_path) != before
|
||||
|
||||
|
||||
def test_the_container_command_line_is_exactly_this():
|
||||
assert convert.docker_args("image:1", "to-adf") == [
|
||||
"docker", "run", "--rm", "-i", "--memory", "256m", "--memory-swap", "256m", "--network", "none", "--read-only", "image:1", "to-adf",
|
||||
]
|
||||
|
||||
|
||||
def test_a_refusal_at_the_root_says_the_document():
|
||||
refusal = {"index": 0, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
failure = convert.adf_to_markdown(DOC, fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with not-an-adf-document: no type (at the document)")
|
||||
|
||||
|
||||
def test_docker_passes_the_text_on_stdin_and_returns_the_output():
|
||||
seen = {}
|
||||
|
||||
def call(args, **kwargs):
|
||||
seen.update(kwargs, args=args)
|
||||
return subprocess.CompletedProcess(args, 3, "out", "err")
|
||||
|
||||
assert convert.docker(["docker", "x"], "text", 7, call) == convert.Ran(3, "out", "err")
|
||||
assert seen == {"args": ["docker", "x"], "input": "text", "capture_output": True, "text": True, "encoding": "utf-8", "timeout": 7}
|
||||
|
||||
|
||||
def test_docker_missing_becomes_a_failure():
|
||||
def call(args, **kwargs):
|
||||
raise FileNotFoundError
|
||||
|
||||
failure = convert.docker(["docker", "x"], "", 7, call)
|
||||
assert failure == Failure("docker is not installed, and the adf-codec shim runs in a container")
|
||||
|
||||
|
||||
def test_docker_that_takes_too_long_becomes_a_failure():
|
||||
def call(args, **kwargs):
|
||||
raise subprocess.TimeoutExpired(args, 7)
|
||||
|
||||
assert convert.docker(["docker", "build", "x"], "", 7, call) == Failure("`docker build` took more than 7 seconds")
|
||||
|
||||
|
||||
def shim_dir(tmp_path):
|
||||
for name in convert.SHIM_FILES:
|
||||
(tmp_path / name).write_text("a")
|
||||
return tmp_path
|
||||
|
||||
|
||||
def scripted(*answers):
|
||||
lines: list[tuple[list[str], str, int]] = []
|
||||
queue = list(answers)
|
||||
|
||||
def run_docker(args, text, seconds):
|
||||
lines.append((args, text, seconds))
|
||||
return queue.pop(0)
|
||||
|
||||
run_docker.lines = lines # type: ignore[attr-defined]
|
||||
return run_docker
|
||||
|
||||
|
||||
def test_an_image_that_exists_is_not_built(tmp_path):
|
||||
run_docker = scripted(convert.Ran(0, "", ""))
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker) == tag
|
||||
assert run_docker.lines == [(["docker", "image", "inspect", tag], "", convert.RUN_SECONDS)]
|
||||
|
||||
|
||||
class Slot:
|
||||
"""Stands in for a heavy slot: records the docker lines run while it is held, or yields the given Failure."""
|
||||
def __init__(self, run_docker, failure: Failure | None = None):
|
||||
self.run_docker, self.failure, self.held_lines = run_docker, failure, None
|
||||
|
||||
@contextlib.contextmanager
|
||||
def __call__(self):
|
||||
before = len(self.run_docker.lines)
|
||||
yield self.failure
|
||||
self.held_lines = self.run_docker.lines[before:]
|
||||
|
||||
|
||||
def test_a_missing_image_is_built_from_the_shim_folder_with_a_memory_limit_inside_a_heavy_slot(tmp_path):
|
||||
missing = convert.Ran(1, "", "")
|
||||
run_docker = scripted(missing, missing, convert.Ran(0, "", ""))
|
||||
slot = Slot(run_docker)
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker, slot) == tag
|
||||
inspect = (["docker", "image", "inspect", tag], "", convert.RUN_SECONDS)
|
||||
build = (["docker", "build", "--quiet", "--memory", "1g", "--memory-swap", "1g", "--tag", tag, str(tmp_path)], "", convert.BUILD_SECONDS)
|
||||
assert run_docker.lines == [inspect, inspect, build]
|
||||
assert slot.held_lines == [inspect, build]
|
||||
|
||||
|
||||
def test_an_image_another_process_built_while_this_one_waited_for_a_slot_is_not_built_again(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""), convert.Ran(0, "", ""))
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == tag
|
||||
assert len(run_docker.lines) == 2
|
||||
|
||||
|
||||
def test_a_heavy_slot_that_cannot_be_taken_fails_before_the_build(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""))
|
||||
shim_dir(tmp_path)
|
||||
down = Failure("cannot take a heavy slot in /x: Permission denied")
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker, down)) == down
|
||||
assert len(run_docker.lines) == 1
|
||||
|
||||
|
||||
def test_a_failed_build_becomes_a_failure_with_its_stderr(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""), convert.Ran(1, "", ""), convert.Ran(5, "", "no network\n"))
|
||||
shim_dir(tmp_path)
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == Failure("building the adf-codec shim's image failed with exit 5: no network")
|
||||
|
||||
|
||||
DOWN, MISSING = Failure("docker is not installed"), convert.Ran(1, "", "")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("answers", [(DOWN,), (MISSING, DOWN), (MISSING, MISSING, DOWN)], ids=["first inspect", "second inspect", "build"])
|
||||
def test_a_failure_to_start_docker_passes_through_inspect_and_build(tmp_path, answers):
|
||||
shim_dir(tmp_path)
|
||||
run_docker = scripted(*answers)
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == DOWN
|
||||
|
||||
|
||||
def test_a_heavy_slot_is_held_until_the_block_ends(tmp_path):
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path)}, 1) as held:
|
||||
assert held is None
|
||||
assert slots.taken_slot(tmp_path / "run-heavy", 1) is None
|
||||
slot, fd = slots.taken_slot(tmp_path / "run-heavy", 1)
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def test_a_process_under_run_heavy_takes_no_second_slot(tmp_path):
|
||||
(tmp_path / "run-heavy").mkdir()
|
||||
slot, fd = slots.taken_slot(tmp_path / "run-heavy", 1)
|
||||
try:
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path), slots.HELD: "0"}, 1) as held:
|
||||
assert held is None
|
||||
finally:
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def test_a_heavy_slot_folder_that_cannot_be_made_yields_a_failure(tmp_path):
|
||||
(tmp_path / "run-heavy").write_text("a file where the folder goes")
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path)}, 1) as held:
|
||||
assert isinstance(held, Failure) and held.reason.startswith(f"cannot take a heavy slot in {tmp_path / 'run-heavy'}: ")
|
||||
|
||||
|
||||
def test_container_run_runs_the_image_on_the_text(tmp_path):
|
||||
run_docker = scripted(convert.Ran(0, "", ""), convert.Ran(0, "answer", ""))
|
||||
assert convert.container_run("to-adf", "text", run_docker, shim_dir(tmp_path)) == convert.Ran(0, "answer", "")
|
||||
assert run_docker.lines[1] == (convert.docker_args(convert.image_tag(tmp_path), "to-adf"), "text", convert.RUN_SECONDS)
|
||||
|
||||
|
||||
def test_container_run_passes_an_image_failure_through(tmp_path):
|
||||
down = Failure("docker is not installed")
|
||||
assert convert.container_run("to-adf", "text", scripted(down), shim_dir(tmp_path)) == down
|
||||
|
||||
|
||||
@pytest.mark.skipif(shutil.which("docker") is None or subprocess.run(["docker", "info"], capture_output=True, timeout=20).returncode != 0, reason="needs a docker daemon")
|
||||
def test_round_trip_through_the_real_container():
|
||||
doc = convert.markdown_to_adf("# Title\n\nSome **bold** text.\n")
|
||||
assert isinstance(doc, dict) and doc["type"] == "doc" and doc["content"][0]["type"] == "heading"
|
||||
markdown = convert.adf_to_markdown(doc)
|
||||
assert isinstance(markdown, str) and markdown.startswith("# Title") and "**bold**" in markdown
|
||||
refused = convert.adf_to_markdown({"type": "nope"})
|
||||
assert isinstance(refused, Failure) and "not-an-adf-document" in refused.reason
|
||||
assert convert.adfs_to_markdown([doc, doc]) == [markdown, markdown]
|
||||
second = convert.adfs_to_markdown([doc, {"type": "nope"}])
|
||||
assert isinstance(second, convert.Refused) and second.index == 1 and "not-an-adf-document" in second.failure.reason
|
||||
crashed = convert.answer("to-markdown", "not json", convert.container_run)
|
||||
assert isinstance(crashed, Failure) and crashed.reason.startswith("the adf-codec shim failed with exit 1: ")
|
||||
@@ -6,6 +6,7 @@ from failure import Failure
|
||||
from review_rules.comprehension_history import HISTORY
|
||||
from release_plan.todo_table import Item, items
|
||||
from reading_cost.figures import RECORD
|
||||
from project_config import templates
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
# The plan, and the records tools append to: none of their lines are the chunk's work.
|
||||
@@ -58,9 +59,9 @@ class Branch:
|
||||
owner: dict[str, int]
|
||||
|
||||
|
||||
def cut_branch(log: str) -> Branch | Failure:
|
||||
def cut_branch(log: str, titles: templates.Titles) -> Branch | Failure:
|
||||
"""The branch LOG printed, cut into chunks as chunk_log cuts its first-parent line; a commit belongs to the oldest chunk whose commits reach it."""
|
||||
commits = parsed(log)
|
||||
commits = parsed(log, titles)
|
||||
if isinstance(commits, Failure):
|
||||
return commits
|
||||
if not commits:
|
||||
@@ -71,9 +72,9 @@ def cut_branch(log: str) -> Branch | Failure:
|
||||
line.append(commits[line[-1].parents[0]])
|
||||
runs = chunk_log(line)
|
||||
owner = owners(runs, commits)
|
||||
titles: list[list[str]] = [[] for _ in runs]
|
||||
held: list[list[str]] = [[] for _ in runs]
|
||||
for commit in commits.values():
|
||||
titles[owner[commit.hash]].append(commit.title)
|
||||
held[owner[commit.hash]].append(commit.title)
|
||||
spans = []
|
||||
for index, run in enumerate(runs):
|
||||
spans.append(Span(
|
||||
@@ -82,13 +83,13 @@ def cut_branch(log: str) -> Branch | Failure:
|
||||
label=label(run[-1].short, run[0].short),
|
||||
landing=landing(run),
|
||||
merged=utc(run[0].committed),
|
||||
titles=tuple(titles[index]),
|
||||
titles=tuple(held[index]),
|
||||
))
|
||||
return Branch(commits, spans, owner)
|
||||
|
||||
|
||||
def parsed(log: str) -> dict[str, Commit] | Failure:
|
||||
"""Each commit LOG printed, by hash, in the order it printed them."""
|
||||
def parsed(log: str, titles: templates.Titles) -> dict[str, Commit] | Failure:
|
||||
"""Each commit LOG printed, by hash, in the order it printed them, its title read as its summary in titles, the project's title templates. So a round title or a `Drop item` title reads the same in every project."""
|
||||
commits = {}
|
||||
for record in log.split("\x00")[1:]:
|
||||
found = LOG_RECORD.fullmatch(record)
|
||||
@@ -96,7 +97,7 @@ def parsed(log: str) -> dict[str, Commit] | Failure:
|
||||
return Failure(f"git log printed a commit it could not read: {record[:200]!r}")
|
||||
full, committed, authored, parents, short, rest = found.groups()
|
||||
title, *files = rest.split("\n")
|
||||
commits[full] = Commit(full, short, int(committed), int(authored), tuple(parents.split()), title, tuple(name for name in files if name))
|
||||
commits[full] = Commit(full, short, int(committed), int(authored), tuple(parents.split()), titles.summary(title), tuple(name for name in files if name))
|
||||
return commits
|
||||
|
||||
|
||||
|
||||
@@ -5,6 +5,9 @@ from branch_chunks.cut import BranchChunk, cut_branch, LOG, NOT_WORK, plan_revis
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import git, Git, text_at
|
||||
from project_config.main import located
|
||||
from project_config.settings import ProjectConfig
|
||||
from record_store.stores import store
|
||||
from project_config import templates
|
||||
|
||||
|
||||
# Where branch_chunks reads the plan and the records, by the setting that names each in a project's config.
|
||||
@@ -16,21 +19,29 @@ def unsupported(checkout: str | None, home: pathlib.Path, run: Git = git) -> str
|
||||
config = located(checkout, home, run)
|
||||
if isinstance(config, Failure):
|
||||
return None
|
||||
elsewhere = [str(config.paths[setting]) for setting, path in READ_AT.items() if config.tracked(setting) != path]
|
||||
elsewhere = [label for name, path in READ_AT.items() for label, tracked in [held(config, name)] if tracked != path]
|
||||
if not elsewhere:
|
||||
return None
|
||||
return f"the project's config puts {', '.join(elsewhere)} elsewhere than {', '.join(READ_AT.values())} in the checkout, the only paths whose commits are read so far"
|
||||
|
||||
|
||||
def branch_chunks(default: str, run: Git) -> list[BranchChunk] | Failure:
|
||||
def held(config: ProjectConfig, name: str) -> tuple[str, str | None]:
|
||||
"""What a message calls the plan or the record that setting name names in config, and its path from the checkout's top, None where it is kept elsewhere."""
|
||||
if name == "plan":
|
||||
return config.plan_label, config.tracked(name)
|
||||
record = store(config, name)
|
||||
return record.label, record.tracked
|
||||
|
||||
|
||||
def branch_chunks(default: str, run: Git, titles: templates.Titles) -> list[BranchChunk] | Failure:
|
||||
"""Each chunk on the default branch's first-parent line, newest first, with the todo.md items it shipped and the later chunks that fixed code it shipped.
|
||||
|
||||
run must run git in the checkout's top: the diff names each path from the top, while blame and a pathspec read a path from the current directory."""
|
||||
titles holds the project's title templates, which each commit's title is read through. run must run git in the checkout's top: the diff names each path from the top, while blame and a pathspec read a path from the current directory."""
|
||||
# The -- keeps a file named like the branch from making it ambiguous.
|
||||
log = run(*LOG, default, "--")
|
||||
if isinstance(log, Failure):
|
||||
return log
|
||||
branch = cut_branch(log)
|
||||
branch = cut_branch(log, titles)
|
||||
if isinstance(branch, Failure):
|
||||
return branch
|
||||
plans = plans_at(plan_revisions(branch), run)
|
||||
|
||||
@@ -9,6 +9,7 @@ import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.templates import BARE, Titles
|
||||
from branch_chunks.fixes import blamed, fixing_changes, removed, removed_work, Traced, with_fixes
|
||||
from branch_chunks.cut import Branch, chunk_log, Commit, cut_branch, landing, NOT_WORK, shipped, Span
|
||||
from branch_chunks.read import branch_chunks, traced_to, unsupported
|
||||
@@ -77,15 +78,21 @@ class Shipped(unittest.TestCase):
|
||||
|
||||
class CutBranch(unittest.TestCase):
|
||||
def test_reads_a_title_that_holds_a_control_character(self):
|
||||
found = cut_branch(f"\x00{'a' * 40} 100 100 \x1faaaaaaa\x1fTake \x1e and \x1f\n\nb.py\n")
|
||||
found = cut_branch(f"\x00{'a' * 40} 100 100 \x1faaaaaaa\x1fTake \x1e and \x1f\n\nb.py\n", BARE)
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([found.titles for found in found.chunks], [("Take \x1e and \x1f",)])
|
||||
|
||||
def test_reads_each_title_as_its_summary_in_the_projects_commit_title_template(self):
|
||||
log = f"\x00{'a' * 40} 100 100 {'b' * 40}\x1faaaaaaa\x1fPAY-7 - Drop item 6: moot\n\nb.py\n\x00{'b' * 40} 90 90 \x1fbbbbbbb\x1fFrom before the template\n\nb.py\n"
|
||||
found = cut_branch(log, Titles("PAY-{id} - {summary}", "{summary}"))
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual(sorted(title for chunk in found.chunks for title in chunk.titles), ["Drop item 6: moot", "From before the template"])
|
||||
|
||||
def test_fails_on_a_commit_it_cannot_read(self):
|
||||
self.assertIsInstance(cut_branch(f"\x00{'a' * 40} 100\x1faaaaaaa\n"), Failure)
|
||||
self.assertIsInstance(cut_branch(f"\x00{'a' * 40} 100\x1faaaaaaa\n", BARE), Failure)
|
||||
|
||||
def test_fails_on_a_log_that_holds_no_commit(self):
|
||||
self.assertIsInstance(cut_branch(""), Failure)
|
||||
self.assertIsInstance(cut_branch("", BARE), Failure)
|
||||
|
||||
|
||||
class ChunkLog(unittest.TestCase):
|
||||
@@ -249,10 +256,10 @@ class BranchChunks(unittest.TestCase):
|
||||
self.env.pop(name)
|
||||
return self.git("rev-parse", "--short", "HEAD").strip()
|
||||
|
||||
def read(self, run=None):
|
||||
def read(self, run=None, titles=BARE):
|
||||
"""branch_chunks over main, run by git_repo's git, or else by run."""
|
||||
with unittest.mock.patch.dict(os.environ, self.env, clear=True):
|
||||
return branch_chunks("main", functools.partial(run or git, cwd=str(self.checkout)))
|
||||
return branch_chunks("main", functools.partial(run or git, cwd=str(self.checkout)), titles)
|
||||
|
||||
def fixing_history(self):
|
||||
"""Merges seven chunks onto main, then checks out a branch off it. Returns each of main's chunks by label, with the chunks that fixed it.
|
||||
@@ -310,8 +317,15 @@ class BranchChunks(unittest.TestCase):
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([([item.id for item in found.shipped], found.fixed_by) for found in found[:2]], [([], ()), ([4], ())])
|
||||
|
||||
def test_reads_a_drop_title_through_the_projects_commit_title(self):
|
||||
self.merge("four", "Do four", {"b.py": "x\ny\n", "todo.md": todo(SECOND, FIX)}, "2026-10-13T10:00:00Z")
|
||||
self.merge("six", "PAY-6 Drop item 6: item 4 fixed it", {"b.py": "x\nY\n", "todo.md": todo(SECOND)}, "2026-10-14T10:00:00Z")
|
||||
found = self.read(titles=Titles("{summary}", "PAY-{id} {summary}"))
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([[item.id for item in found.shipped] for found in found[:2]], [[], [4]])
|
||||
|
||||
def test_fails_where_git_cannot_read_the_branch(self):
|
||||
self.assertEqual(branch_chunks("main", lambda *args: Failure("no log")), Failure("no log"))
|
||||
self.assertEqual(branch_chunks("main", lambda *args: Failure("no log"), BARE), Failure("no log"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
"""The human approval that `chunk-pr merge` waits for where the project's config sets `wait-for-approval`."""
|
||||
import json
|
||||
import pathlib
|
||||
import time
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge
|
||||
from deploy_release.forge import Run
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
# A human answers in hours, so merge polls once a minute and gives up after 90 minutes, which leaves room for the checks wait inside the 2 hours a background command may run, so that the give-up message prints.
|
||||
POLL_SECONDS = 60
|
||||
WAIT_SECONDS = 90 * 60
|
||||
|
||||
|
||||
def awaited(forge: Forge, run: Run) -> bool | Failure:
|
||||
"""Whether merge waits for an approval: the project config's `wait-for-approval`. A config that cannot be read fails, so that merge never skips an approval the config may require. chunk-pr reads approvals on GitHub only, so a Gitea project that sets it fails too."""
|
||||
answer = run([str(BIN / "project-config"), "wait-for-approval"])
|
||||
if isinstance(answer, Failure):
|
||||
return answer
|
||||
if answer.strip() not in ("true", "false"):
|
||||
return Failure(f"project-config wait-for-approval printed {answer.strip()[:80]!r}, not true or false")
|
||||
if answer.strip() == "true" and forge != "gh":
|
||||
return Failure("the project's config sets wait-for-approval, but chunk-pr reads approvals on GitHub only, so it cannot merge this pull request; ask the human to merge it")
|
||||
return answer.strip() == "true"
|
||||
|
||||
|
||||
def approved(number: str, run: Run, sleep: typing.Callable[[float], None] = time.sleep) -> Failure | None:
|
||||
"""None once GitHub reports pull request number approved, as its branch protection asks; a Failure where a reviewer requested changes, where the protection asks for no review, or where no approval came within WAIT_SECONDS."""
|
||||
for waited in range(0, WAIT_SECONDS + 1, POLL_SECONDS):
|
||||
viewed = run(["gh", "pr", "view", number, "--json", "reviewDecision"])
|
||||
try:
|
||||
decision = viewed if isinstance(viewed, Failure) else json.loads(viewed)["reviewDecision"]
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return Failure(f"gh pr view printed no review decision: {str(viewed).strip()[:200]}")
|
||||
if isinstance(decision, Failure):
|
||||
return decision
|
||||
if decision == "APPROVED":
|
||||
return None
|
||||
if decision == "CHANGES_REQUESTED":
|
||||
return Failure(f"a reviewer requested changes on pull request {number}")
|
||||
if not decision:
|
||||
return Failure("wait-for-approval is set, but the branch protection requires no review, so GitHub reports no decision; ask the human to require a review in the protection or to set wait-for-approval to false")
|
||||
if decision != "REVIEW_REQUIRED":
|
||||
return Failure(f"GitHub reports the review decision {decision!r} on pull request {number}, and chunk-pr doesn't know that decision")
|
||||
if waited < WAIT_SECONDS:
|
||||
sleep(POLL_SECONDS)
|
||||
return Failure(f"pull request {number} wasn't approved within {WAIT_SECONDS // 60} minutes; run chunk-pr merge again once it is")
|
||||
+33
-4
@@ -11,7 +11,10 @@ pull request only while its head is the commit checked out, so push before you r
|
||||
|
||||
open pushes the branch, setting its upstream, and opens a draft pull request into origin's
|
||||
default branch. <title> is one line, as ~/.claude/CLAUDE.md → "Git, commits, and PRs"
|
||||
says, and <body> is the pull request's summary. Where the branch's pull request is open
|
||||
says, and <body> is the pull request's summary. On a branch that fits the config's `branch`
|
||||
template, it refuses a <title> that doesn't fit the `pull-request-title` template the
|
||||
project's config names (`project-config --help`); on any other branch, as for a
|
||||
chunk with no plan item, the title may be the bare summary. It fails where no config names the checkout. Where the branch's pull request is open
|
||||
already, it opens no second one. On origin's default branch it refuses without pushing anything.
|
||||
sync fetches origin and merges its default branch into the branch checked out, where the
|
||||
branch does not hold it already, and prints which it did. Then, where the project's config
|
||||
@@ -19,7 +22,8 @@ sync fetches origin and merges its default branch into the branch checked ou
|
||||
failing where the check fails or no config names the checkout. On a merge conflict it names the conflicted files and leaves the merge in
|
||||
progress, to resolve and commit. On origin's default branch it refuses and doesn't fetch anything.
|
||||
ready marks the pull request ready for review. On Gitea a draft is a pull request whose title
|
||||
starts with `WIP: `, so there it drops that prefix. Given <title>, one line, it sets that
|
||||
starts with `WIP: `, so there it drops that prefix. Given <title>, one line, which it holds
|
||||
to the template as open does, it sets that
|
||||
as the pull request's title first; where that fails, the pull request stays a draft.
|
||||
merge waits for the pull request's checks, and those origin's default branch requires, to pass
|
||||
on the head, then merges the pull request, and only while its head is still the commit
|
||||
@@ -31,6 +35,12 @@ merge waits for the pull request's checks, and those origin's default branch
|
||||
only, a rebase followed by a merge commit, a rebase, a squash. GitHub offers only the
|
||||
merge commit, the rebase and the squash. It also refuses where `larv-review
|
||||
scoring-run-owed` exits 1, because the chunk owes a scoring run it has not recorded.
|
||||
Where the project's config sets `wait-for-approval = true` (`project-config --help`), it
|
||||
also waits, once the checks have passed, until GitHub reports the pull request approved
|
||||
as its branch protection requires. It refuses at once where a reviewer requested changes,
|
||||
where the protection requires no review, on Gitea, and where it cannot read the config.
|
||||
After 90 minutes without an approval it refuses too; run it again once the pull request
|
||||
is approved.
|
||||
clean acts once the forge reports the branch's pull request merged at the commit checked out,
|
||||
by any merge method. It fetches origin, fast-forwards the main checkout to origin's
|
||||
default branch, removes the chunk's worktree, then deletes the local branch; origin's
|
||||
@@ -49,10 +59,12 @@ import sys
|
||||
import time
|
||||
import typing
|
||||
|
||||
from chunk_pr.approval import approved, awaited
|
||||
from deploy_release.forge import checks_passed, gitea, merged_pull, open_pull, required_checks, Run, runner
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge
|
||||
from chunk_preflight.choices import forge_of
|
||||
from project_config import templates
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
# How long merge waits for a check to report before it takes a pull request without any as passed: CI queues its checks within seconds of a push, and merge may run right after one.
|
||||
@@ -82,11 +94,11 @@ def step(argv: list[str], run: Run) -> str | Failure:
|
||||
"""Run the step argv names: the line to print, or a Failure. A malformed argv doesn't run anything."""
|
||||
match argv:
|
||||
case ["open", title, *body] if len(body) <= 1 and not title.startswith("-"):
|
||||
return Failure("give a title of one line") if not one_line(title) else opened(title, body[0] if body else "", run)
|
||||
return Failure("give a title of one line") if not one_line(title) else misfit(title, run) or opened(title, body[0] if body else "", run)
|
||||
case ["sync"]:
|
||||
return synced(run)
|
||||
case ["ready", *title] if len(title) <= 1 and not any(given.startswith("-") for given in title):
|
||||
return Failure("give a title of one line") if title and not one_line(title[0]) else marked_ready(run, title[0] if title else None)
|
||||
return Failure("give a title of one line") if title and not one_line(title[0]) else (misfit(title[0], run) if title else None) or marked_ready(run, title[0] if title else None)
|
||||
case ["merge"]:
|
||||
return merged(run)
|
||||
case ["clean"]:
|
||||
@@ -94,6 +106,17 @@ def step(argv: list[str], run: Run) -> str | Failure:
|
||||
return Failure(USAGE)
|
||||
|
||||
|
||||
def misfit(title: str, run: Run) -> Failure | None:
|
||||
"""Why title doesn't fit the `pull-request-title` template the project's config names; None where it fits. A branch that doesn't fit the config's `branch` template is no plan item's, so it has no ID for {id}, and any title fits there. A config that cannot be read fails, so that no pull request reaches the project's owners under a title they don't use."""
|
||||
read = [run([str(BIN / "project-config"), "pull-request-title"]), run([str(BIN / "project-config"), "branch"]), run(["git", "symbolic-ref", "--short", "HEAD"])]
|
||||
if failed := next((answer for answer in read if isinstance(answer, Failure)), None):
|
||||
return failed
|
||||
template, branch_template, branch = (answer.strip("\n") for answer in read if isinstance(answer, str))
|
||||
if not templates.branch_fits(branch_template, branch) or templates.fits(template, title.strip()):
|
||||
return None
|
||||
return Failure(f"title the pull request as the project's config asks, `{template}`, where {{id}} is the ID of the chunk's first item; {title.strip()!r} doesn't fit")
|
||||
|
||||
|
||||
def one_line(title: str) -> bool:
|
||||
return bool(title.strip()) and "\n" not in title
|
||||
|
||||
@@ -223,6 +246,9 @@ def merged(run: Run, sleep: typing.Callable[[float], None] = time.sleep) -> str
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, number, head = found
|
||||
waits = awaited(forge, run)
|
||||
if isinstance(waits, Failure):
|
||||
return waits
|
||||
owed = run([str(BIN / "larv-review"), "scoring-run-owed"])
|
||||
if isinstance(owed, Failure):
|
||||
return owed
|
||||
@@ -234,6 +260,9 @@ def merged(run: Run, sleep: typing.Callable[[float], None] = time.sleep) -> str
|
||||
checked = required if isinstance(required, Failure) else checks_passed(forge, number, head, required, run, sleep, NO_CHECKS_SECONDS)
|
||||
if isinstance(checked, Failure):
|
||||
return checked
|
||||
approval = approved(number, run, sleep) if waits else None
|
||||
if isinstance(approval, Failure):
|
||||
return approval
|
||||
if forge == "gh":
|
||||
done = run(["gh", "pr", "merge", number, method, "--match-head-commit", head])
|
||||
else:
|
||||
|
||||
@@ -25,6 +25,10 @@ GH_CHECKS = ["gh", "pr", "checks", "12", "--watch", "--fail-fast"]
|
||||
TEA_BRANCH = ["tea", "api", "repos/{owner}/{repo}/branches/main"]
|
||||
TEA_STATUS = ["tea", "api", f"repos/{{owner}}/{{repo}}/commits/{HEAD}/status"]
|
||||
OWED = [str(pathlib.Path(__file__).resolve().parents[1] / "larv-review"), "scoring-run-owed"]
|
||||
TITLE = [str(pathlib.Path(__file__).resolve().parents[1] / "project-config"), "pull-request-title"]
|
||||
BRANCH = [str(pathlib.Path(__file__).resolve().parents[1] / "project-config"), "branch"]
|
||||
WAITS = [str(pathlib.Path(__file__).resolve().parents[1] / "project-config"), "wait-for-approval"]
|
||||
GH_DECISION = ["gh", "pr", "view", "12", "--json", "reviewDecision"]
|
||||
|
||||
|
||||
class Checkout:
|
||||
@@ -37,12 +41,19 @@ class Checkout:
|
||||
self.open = open
|
||||
self.allowed = allowed
|
||||
self.statuses: list[str] = []
|
||||
# What GitHub reports as the pull request's review decision on each read; the last one repeats.
|
||||
self.decisions = ["APPROVED"]
|
||||
# Set, what GitHub prints instead of a decision's JSON.
|
||||
self.unreadable: str | Failure | None = None
|
||||
self.ran: list[list[str]] = []
|
||||
self.answers: dict[tuple[str, ...], str | Failure] = {
|
||||
("git", "remote", "get-url", "origin"): f"{origin}\n",
|
||||
("git", "symbolic-ref", "--short", "HEAD"): "item-7\n",
|
||||
("git", "rev-parse", "HEAD"): f"{HEAD}\n",
|
||||
("git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"): "origin/main\n",
|
||||
tuple(WAITS): "false\n",
|
||||
tuple(TITLE): "{summary}\n",
|
||||
tuple(BRANCH): "item-{id}\n",
|
||||
}
|
||||
|
||||
def __call__(self, command: list[str]) -> str | Failure:
|
||||
@@ -59,6 +70,10 @@ class Checkout:
|
||||
return json.dumps([{"number": 12, "head": {"ref": "item-7", "label": "item-7", "sha": HEAD, "repo": {"full_name": "me/project"}}, "base": {"repo": {"full_name": "me/project"}}}] if self.open else [])
|
||||
if command == TEA_STATUS:
|
||||
return self.statuses.pop(0) if self.statuses else json.dumps({"total_count": 1, "state": "success", "statuses": [{"context": "CI / tests (pull_request)", "status": "success"}]})
|
||||
if command == GH_DECISION and self.unreadable is not None:
|
||||
return self.unreadable
|
||||
if command == GH_DECISION:
|
||||
return json.dumps({"reviewDecision": self.decisions.pop(0) if len(self.decisions) > 1 else self.decisions[0]})
|
||||
if command == TEA_BRANCH:
|
||||
return json.dumps({"enable_status_check": False})
|
||||
if command in (GH_SETTINGS, TEA_SETTINGS):
|
||||
@@ -67,11 +82,23 @@ class Checkout:
|
||||
|
||||
def acted(self) -> list[list[str]]:
|
||||
"""What it ran beyond reading the checkout, the pull requests and the repository's settings."""
|
||||
reads = [GH_LIST, TEA_LIST, GH_SETTINGS, TEA_SETTINGS, OWED, GH_CHECKS, TEA_BRANCH, TEA_STATUS]
|
||||
reads = [GH_LIST, GH_DECISION, TEA_LIST, GH_SETTINGS, TEA_SETTINGS, OWED, GH_CHECKS, TEA_BRANCH, TEA_STATUS]
|
||||
return [command for command in self.ran if tuple(command) not in self.answers and command not in reads]
|
||||
|
||||
|
||||
class Open(unittest.TestCase):
|
||||
def test_a_title_must_fit_the_template_only_on_a_branch_that_fits_the_configs_branch_template(self):
|
||||
for argv in (["open", "Release review of 0.3.0"], ["ready", "Release review of 0.3.0"]):
|
||||
with self.subTest(argv=argv):
|
||||
checkout = Checkout(GITHUB, open=argv[0] == "ready")
|
||||
checkout.answers[tuple(TITLE)] = "PAY-{id} - {summary}\n"
|
||||
checkout.answers[tuple(BRANCH)] = "feature/PAY-{id}\n"
|
||||
self.assertNotIsInstance(step(argv, checkout), Failure)
|
||||
checkout.answers[("git", "symbolic-ref", "--short", "HEAD")] = "feature/PAY-7\n"
|
||||
refused = step(argv, checkout)
|
||||
assert isinstance(refused, Failure), refused
|
||||
self.assertIn("'Release review of 0.3.0' doesn't fit", refused.reason)
|
||||
|
||||
def test_github_pushes_and_opens_a_draft_into_the_default_branch(self):
|
||||
checkout = Checkout(GITHUB, open=False)
|
||||
opened = step(["open", "ABC-1 - Do it", "The body."], checkout)
|
||||
@@ -94,6 +121,25 @@ class Open(unittest.TestCase):
|
||||
self.assertIsInstance(step(["open", "Do it"], checkout), Failure)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def test_a_title_that_does_not_fit_the_configs_template_is_refused_before_anything_runs(self):
|
||||
for argv in (["open", "Do it"], ["ready", "Do it"]):
|
||||
with self.subTest(argv=argv):
|
||||
checkout = Checkout(GITHUB, open=argv[0] == "ready")
|
||||
checkout.answers[tuple(TITLE)] = "PAY-{id} - {summary}\n"
|
||||
refused = step(argv, checkout)
|
||||
assert isinstance(refused, Failure), refused
|
||||
self.assertIn("`PAY-{id} - {summary}`", refused.reason)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
self.assertNotIsInstance(step([argv[0], "PAY-7 - Do it"], checkout), Failure)
|
||||
checkout.answers[tuple(TITLE)] = Failure("no config names the checkout")
|
||||
self.assertEqual(step(argv, checkout), Failure("no config names the checkout"))
|
||||
checkout.answers[tuple(TITLE)] = "PAY-{id} - {summary}\n"
|
||||
checkout.answers[tuple(BRANCH)] = Failure("`branch` is 'x', which holds no {id}")
|
||||
self.assertEqual(step(argv, checkout), Failure("`branch` is 'x', which holds no {id}"))
|
||||
untitled = Checkout(GITHUB, open=True)
|
||||
untitled.answers[tuple(TITLE)] = Failure("no config names the checkout")
|
||||
self.assertNotIsInstance(step(["ready"], untitled), Failure)
|
||||
|
||||
def test_a_title_of_more_than_one_line_or_a_second_body_is_refused_before_anything_runs(self):
|
||||
for argv, refusal in ((["open", "Do it\nand more"], "give a title of one line"), (["open", " "], "give a title of one line"), (["open", "Do it", "Body", "More"], USAGE)):
|
||||
with self.subTest(argv):
|
||||
@@ -273,6 +319,85 @@ class Merge(unittest.TestCase):
|
||||
self.assertEqual(merged(checkout, slept.append), "Merged pull request #12 (merge).")
|
||||
self.assertEqual(sum(slept), 60)
|
||||
|
||||
def requiring_approval(self, origin: str = GITHUB, *decisions: str) -> Checkout:
|
||||
"""A Checkout whose project config sets wait-for-approval, and which reports each of decisions in turn as the review decision."""
|
||||
checkout = Checkout(origin, open=True)
|
||||
checkout.answers[tuple(WAITS)] = "true\n"
|
||||
checkout.decisions = list(decisions) or ["APPROVED"]
|
||||
return checkout
|
||||
|
||||
def test_a_project_without_wait_for_approval_never_reads_the_review_decision(self):
|
||||
checkout = Checkout(GITHUB, open=True)
|
||||
checkout.decisions = ["REVIEW_REQUIRED"]
|
||||
self.assertEqual(step(["merge"], checkout), "Merged pull request #12 (merge).")
|
||||
self.assertNotIn(GH_DECISION, checkout.ran)
|
||||
|
||||
def test_an_approved_pull_request_merges_after_the_checks_and_the_approval(self):
|
||||
checkout = self.requiring_approval()
|
||||
self.assertEqual(step(["merge"], checkout), "Merged pull request #12 (merge).")
|
||||
self.assertEqual(checkout.ran[-3:], [GH_CHECKS, GH_DECISION, ["gh", "pr", "merge", "12", "--merge", "--match-head-commit", HEAD]])
|
||||
|
||||
def test_it_waits_a_minute_at_a_time_while_the_branch_protection_still_wants_a_review(self):
|
||||
checkout = self.requiring_approval(GITHUB, "REVIEW_REQUIRED", "REVIEW_REQUIRED", "APPROVED")
|
||||
slept: list[float] = []
|
||||
self.assertEqual(merged(checkout, slept.append), "Merged pull request #12 (merge).")
|
||||
self.assertEqual(slept, [60, 60])
|
||||
|
||||
def test_an_approval_that_never_comes_leaves_it_unmerged_after_90_minutes(self):
|
||||
checkout = self.requiring_approval(GITHUB, "REVIEW_REQUIRED")
|
||||
slept: list[float] = []
|
||||
failed = merged(checkout, slept.append)
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn("90 minutes", failed.reason)
|
||||
self.assertEqual(sum(slept), 90 * 60)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def test_an_approval_that_comes_in_the_last_minute_still_merges(self):
|
||||
checkout = self.requiring_approval(GITHUB, *["REVIEW_REQUIRED"] * 90, "APPROVED")
|
||||
slept: list[float] = []
|
||||
self.assertEqual(merged(checkout, slept.append), "Merged pull request #12 (merge).")
|
||||
self.assertEqual(sum(slept), 90 * 60)
|
||||
|
||||
def test_a_review_decision_it_cannot_read_or_does_not_know_leaves_it_unmerged(self):
|
||||
for answer in (Failure("gh pr view failed"), "not json", "[]", "{}", json.dumps({"reviewDecision": "DISMISSED"})):
|
||||
with self.subTest(answer):
|
||||
checkout = self.requiring_approval()
|
||||
checkout.unreadable = answer
|
||||
self.assertIsInstance(step(["merge"], checkout), Failure)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def test_requested_changes_leave_it_unmerged_without_waiting(self):
|
||||
checkout = self.requiring_approval(GITHUB, "CHANGES_REQUESTED")
|
||||
slept: list[float] = []
|
||||
failed = merged(checkout, slept.append)
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn("requested changes", failed.reason)
|
||||
self.assertEqual((slept, checkout.acted()), ([], []))
|
||||
|
||||
def test_a_branch_protection_that_asks_for_no_review_leaves_it_unmerged_naming_the_setting(self):
|
||||
for decision in ("", None):
|
||||
with self.subTest(decision):
|
||||
checkout = self.requiring_approval(GITHUB, decision)
|
||||
failed = step(["merge"], checkout)
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn("requires no review", failed.reason)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def test_gitea_with_wait_for_approval_leaves_it_unmerged_since_chunk_pr_reads_approvals_on_github_only(self):
|
||||
checkout = self.requiring_approval(GITEA)
|
||||
failed = step(["merge"], checkout)
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn("GitHub", failed.reason)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def test_a_config_it_cannot_read_or_that_prints_neither_true_nor_false_leaves_it_unmerged(self):
|
||||
for answer in (Failure("no config names the checkout"), "maybe\n", ""):
|
||||
with self.subTest(answer):
|
||||
checkout = Checkout(GITHUB, open=True)
|
||||
checkout.answers[tuple(WAITS)] = answer
|
||||
self.assertIsInstance(step(["merge"], checkout), Failure)
|
||||
self.assertEqual(checkout.acted(), [])
|
||||
|
||||
def protected(self, *reads: list[tuple[str, str]]) -> Checkout:
|
||||
"""A Gitea Checkout whose main requires a check matching CI / tests*, its status at HEAD holding each of reads in turn."""
|
||||
checkout = Checkout(GITEA, open=True)
|
||||
|
||||
@@ -4,7 +4,8 @@ import pathlib
|
||||
from release_plan.release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, NoItem, Plan
|
||||
from release_plan.todo_table import item_details, items, NoItemsTable
|
||||
from release_plan.todo_table import NoItemsTable
|
||||
from plan_store import stores as plan_stores
|
||||
from release_plan.release import version
|
||||
|
||||
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
|
||||
@@ -19,21 +20,19 @@ def cut_name(cut: LastCut) -> str | None:
|
||||
return None if headed is None else f"{version(headed)} (dated in CHANGELOG.md)"
|
||||
|
||||
|
||||
def plan_name(default: str, outside: pathlib.Path | None) -> str:
|
||||
"""How the preflight names the plan it read: the default branch's todo.md, or the file, where the project's config puts it outside the checkout."""
|
||||
return str(outside) if outside else f"{default}'s todo.md"
|
||||
def plan_name(default: str, outside: str | None) -> str:
|
||||
"""How the preflight names the plan it read: the default branch's todo.md, or the file or Jira epic, where the project's config puts it outside the checkout."""
|
||||
return outside if outside else f"{default}'s todo.md"
|
||||
|
||||
|
||||
def planned(todo: str | Failure, cut: LastCut, default: str, outside: pathlib.Path | None = None) -> Plan | NoItem:
|
||||
"""The plan in todo, the text of the todo.md plan_name names, with the item the next chunk takes first, release_standing.chunk_item's pick; else why there is none."""
|
||||
def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch: str, outside: str | None = None) -> Plan | NoItem:
|
||||
"""todo, which is the project's plan as its store read it and which plan_name names, with the item the next chunk takes first, release_standing.chunk_item's pick; else why there is none. branch is the project's `branch` template."""
|
||||
where = plan_name(default, outside)
|
||||
if isinstance(todo, NoItemsTable):
|
||||
return NoItem(f"{where} holds no items table.")
|
||||
if isinstance(todo, Failure):
|
||||
return NoItem(f"{where} cannot be read: {todo.reason}.")
|
||||
found = items(todo)
|
||||
if isinstance(found, NoItemsTable):
|
||||
return NoItem(f"{where} holds no items table.")
|
||||
if isinstance(found, Failure):
|
||||
return NoItem(f"{where} cannot be read: {found.reason}.")
|
||||
found = todo.items
|
||||
if isinstance(cut.tag, Failure):
|
||||
return NoItem(f"{default}'s tags cannot be read: {cut.tag.reason}. So which release is next cannot be told. Find the next release yourself.")
|
||||
named = cut_name(cut)
|
||||
@@ -53,9 +52,7 @@ def planned(todo: str | Failure, cut: LastCut, default: str, outside: pathlib.Pa
|
||||
first = pick.item
|
||||
if first is None:
|
||||
return NoItem(f"every item of release {version(pick.release)} in {where} waits." if pick.release is not None else f"{where}'s items table holds no item.")
|
||||
details = item_details(todo)
|
||||
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
|
||||
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip(), details)
|
||||
return Plan(found, first, f"{first.tagline}\n\n{first.detail}".strip(), branch)
|
||||
|
||||
|
||||
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
"""The lines the preflight prints, stated from what it gathered."""
|
||||
from release_plan.todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
|
||||
from touch_predictions.beside import chunks_beside
|
||||
from chunk_preflight.choices import cut_name, PULLS_LIST
|
||||
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries, UNSEEN_RELEASES
|
||||
from failure import Failure
|
||||
@@ -17,11 +18,12 @@ def render(found: Gathered) -> list[str]:
|
||||
note = [f"- {found.note}"] if found.note else []
|
||||
unseen = [f"- {UNSEEN_RELEASES}"] if found.plan_outside else []
|
||||
head = [*note, f"- {last_release(found.default, found.cut)}", *unseen]
|
||||
paths = f"- The project's config puts its files at: {'; '.join(f'{setting} {path}' for setting, path in found.paths.items())}."
|
||||
paths = f"- The project's config puts its files and plan at: {'; '.join(f'{setting} {path}' for setting, path in found.places.items())}."
|
||||
texts = f"- The project's config sets: {'; '.join(f'{setting} {text}' for setting, text in found.texts.items())}."
|
||||
if isinstance(found.item, NoItem):
|
||||
return [*head, f"- No plan item: {found.item.why} No worktree was made.", paths]
|
||||
return [*head, f"- No plan item: {found.item.why} No worktree was made.", paths, texts]
|
||||
lines = item_lines(found.plan, found.item)
|
||||
return [*head, *lines[:2], paths, *lines[2:]]
|
||||
return [*head, *lines[:2], paths, texts, *lines[2:]]
|
||||
|
||||
|
||||
def last_release(default: str, release: LastCut) -> str:
|
||||
@@ -47,6 +49,7 @@ def item_lines(plan: str, item: ItemFacts) -> list[str]:
|
||||
f"- Worktree: {worktree}",
|
||||
f"- Open pull requests from {item.plan.branch}: {pulls_text(item.pulls, item.plan.branch)}",
|
||||
*bundled(item.plan),
|
||||
*beside(item.plan),
|
||||
*named_lines(item.named),
|
||||
f"\nItem {first.id}'s tagline and detail:\n\n{quoted(item.plan.text)}",
|
||||
*joining_details(item.plan),
|
||||
@@ -55,16 +58,14 @@ def item_lines(plan: str, item: ItemFacts) -> list[str]:
|
||||
|
||||
|
||||
def joining_details(plan: Plan) -> list[str]:
|
||||
"""The detail of each of the first JOINING_DETAILS items that may join the chunk, in the table's order, and what the worker lacks: an item with no detail, the items left out, or details that cannot be read."""
|
||||
"""The detail of each of the first JOINING_DETAILS items that may join the chunk, in the table's order, and what the worker lacks: an item with no detail, or the items left out."""
|
||||
joining = bundle_candidates(plan.items, plan.first)
|
||||
if not joining:
|
||||
return []
|
||||
if isinstance(plan.details, Failure):
|
||||
return [f"\nThe details of the items that may join cannot be read: {plan.details.reason}"]
|
||||
shown, left = joining[:JOINING_DETAILS], joining[JOINING_DETAILS:]
|
||||
lines = [f"\nItem {item.id}'s detail:\n\n{quoted(detail)}" if (detail := plan.details.get(item.id)) else f"\nItem {item.id} has no detail." for item in shown]
|
||||
lines = [f"\nItem {item.id}'s detail:\n\n{quoted(detail)}" if (detail := item.detail) else f"\nItem {item.id} has no detail." for item in shown]
|
||||
if left:
|
||||
lines.append(f"\nThe details of items {listed([str(item.id) for item in left], 'and')} are not quoted: only the first {JOINING_DETAILS} are. Open `todo.md` for them.")
|
||||
lines.append(f"\nThe details of items {listed([str(item.id) for item in left], 'and')} are not quoted: only the first {JOINING_DETAILS} are. Run `~/.claude/bin/todo-item show <ID>` for each.")
|
||||
return lines
|
||||
|
||||
|
||||
@@ -95,10 +96,25 @@ def bundled(plan: Plan) -> list[str]:
|
||||
return [f"- Item {first.id} has R above {BUNDLE_MAX_R}, so it ships alone."]
|
||||
if not candidates:
|
||||
return [f"- No other item of release {version(first.release)} may join item {first.id}'s chunk."]
|
||||
listed = [f" - item {item.id}, {levels(item)}, S {item.scores['S']}: {item.tagline}" for item in candidates]
|
||||
listed = [f" - item {item.id}, {levels(item)}, S {item.scores.get('S', 'unscored')}: {item.tagline}" for item in candidates]
|
||||
return [f'- The items of release {version(first.release)} that may join the chunk of item {first.id}, where `~/.claude/CLAUDE.md` → "Working loop" lets them share it:', *listed]
|
||||
|
||||
|
||||
def beside(plan: Plan) -> list[str]:
|
||||
"""The items that may start chunks while first's runs, by touch_predictions' pick; no line where none of the release's items holds a prediction."""
|
||||
first = plan.first
|
||||
found = chunks_beside(plan.items, first)
|
||||
if found is None:
|
||||
return []
|
||||
none = f"- No item of release {version(first.release)} may start a chunk beside item {first.id}'s"
|
||||
if isinstance(found, str):
|
||||
return [f"{none}: {found}."]
|
||||
refused = f" Not beside it: {'; '.join(found.refused)}." if found.refused else ""
|
||||
if not found.picked:
|
||||
return [f"{none}.{refused}"]
|
||||
return [f"- The items of release {version(first.release)} that may start chunks beside item {first.id}'s: {', '.join(map(str, found.picked))}. None is predicted to touch a part that item {first.id} touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own.{refused}"]
|
||||
|
||||
|
||||
def named_lines(named: list[NamedPath] | Failure) -> list[str]:
|
||||
if isinstance(named, Failure):
|
||||
return [f"- The files the item names: cannot be listed: {named.reason}"]
|
||||
|
||||
@@ -6,6 +6,7 @@ import typing
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import Item
|
||||
from release_plan.release_standing import LastCut
|
||||
from project_config import templates
|
||||
|
||||
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
|
||||
Forge = typing.Literal["gh", "tea"]
|
||||
@@ -21,18 +22,17 @@ class Ran:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Plan:
|
||||
"""The default branch's todo.md items, and `first`: the item the next chunk takes first."""
|
||||
"""The default branch's plan items, each with its detail, and `first`: the item the next chunk takes first."""
|
||||
items: list[Item]
|
||||
first: Item
|
||||
# first's tagline and detail.
|
||||
text: str
|
||||
# Every item's detail by its ID, or why todo.md's details cannot be read.
|
||||
details: dict[int, str] | Failure
|
||||
branch_template: str
|
||||
|
||||
@property
|
||||
def branch(self) -> str:
|
||||
"""The branch first's worktree is on."""
|
||||
return f"item-{self.first.id}"
|
||||
return templates.branch_of(self.branch_template, self.first.id)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -81,7 +81,9 @@ class Gathered:
|
||||
item: ItemFacts | NoItem
|
||||
# The plan that was read, as choices.plan_name names it.
|
||||
plan: str
|
||||
# Each path the project's config sets, by its setting: in the item's worktree where one was made or continued, else in the checkout.
|
||||
paths: dict[str, pathlib.Path]
|
||||
# Each path the project's config sets, and the epic of a plan kept in Jira, by its setting: in the item's worktree where one was made or continued, else in the checkout.
|
||||
places: dict[str, str]
|
||||
# Whether the project's config puts the plan outside the checkout, where a release whose items are all done is not seen.
|
||||
plan_outside: bool
|
||||
# The language and the templates the project's config names, by their settings.
|
||||
texts: dict[str, str]
|
||||
|
||||
@@ -29,17 +29,27 @@ and prints that the release reviews and the cuts are the human's to call. It pri
|
||||
such a commit counts only where its <release> is after the version under the dated heading.
|
||||
Where todo.md's earliest release is x.y.z or earlier, it says todo.md files items under a release
|
||||
already cut;
|
||||
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-item-<ID>, on
|
||||
the branch item-<ID>. It continues a worktree already on that branch; else it adds one on the
|
||||
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-<branch>,
|
||||
each / of the branch a dash, on the branch the config's `branch` template names, which is
|
||||
item-<ID> where the config names none. It continues a worktree already on that branch; else it adds one on the
|
||||
local branch, else on a new branch tracking origin's, else on a new branch off the default
|
||||
branch. Without --worktree, it prints that none was made;
|
||||
- each path the project's config sets, as `project-config` prints them in that worktree, or else
|
||||
in the checkout;
|
||||
- the language the config names for the project's prose, and its templates for commit titles,
|
||||
pull request titles and branches;
|
||||
- the open pull requests whose head is the item's branch, each by its number and URL, as gh lists
|
||||
them on a github.com origin, and else as tea does. No title reaches the output;
|
||||
- the items of that release that a chunk taking the item may take too, each with its L, E + I,
|
||||
S and tagline: those that are not questions, that have R 5 or less, and that no item outside
|
||||
the chunk blocks; none where the item's own R is above 5;
|
||||
- the other items of that release that may start chunks while the item's chunk runs, then why each
|
||||
of the rest may not. An item's prediction is the bullets under a `Touches:` line in its detail,
|
||||
which `touch-predictions --help` describes. Another item may start a chunk where it doesn't
|
||||
wait and its prediction shares no part with the item's, or with that of an item picked before
|
||||
it in the plan's order. A part either prediction marks (small) doesn't count. This line is left
|
||||
out where no item of the release that doesn't wait holds a prediction. The plan and the records
|
||||
belong in no prediction, since every chunk writes them;
|
||||
- each file or folder git tracks that the item's tagline or detail names in backticks, with a
|
||||
file's lines or a folder's files, then the item's tagline and detail, then the detail of each
|
||||
of the first {JOINING_DETAILS} items that may join, or that one has none;
|
||||
@@ -64,13 +74,13 @@ import sys
|
||||
import typing
|
||||
|
||||
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
|
||||
from release_plan.release_standing import default_plan
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
|
||||
from chunk_preflight.choices import forge_of, plan_name, planned, pulls_command, worktree_add, worktree_on
|
||||
from chunk_preflight.facts import JOINING_DETAILS, render
|
||||
from project_config.main import located
|
||||
from release_plan.named_code import named_paths
|
||||
from release_plan.release_standing import project_plan
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
# Each tool run in the item's worktree, {item} standing for the item's ID.
|
||||
@@ -124,13 +134,13 @@ def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Fai
|
||||
config = located(str(root), pathlib.Path.home())
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
outside = None if config.tracked("plan") else config.paths["plan"]
|
||||
held = default_plan(str(root), ref, config.place("plan"), config.place("changelog"))
|
||||
plan = planned(held.todo, held.cut, ref, outside)
|
||||
outside = None if config.tracked("plan") else config.plan_label
|
||||
held = project_plan(config, ref, str(root))
|
||||
plan = planned(held.todo, held.cut, ref, config.branch, outside)
|
||||
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
|
||||
# A `checkout:` path lands in the worktree the chunk works in.
|
||||
made = located(str(item.worktree.path), pathlib.Path.home()) if isinstance(item, ItemFacts) and isinstance(item.worktree, Worktree) else config
|
||||
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).paths, outside is not None))
|
||||
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).places, outside is not None, config.texts))
|
||||
|
||||
|
||||
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float, make: bool) -> ItemFacts:
|
||||
@@ -146,7 +156,8 @@ def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | F
|
||||
return listing
|
||||
if (path := worktree_on(listing, branch)) is not None:
|
||||
return Worktree(path, f"continued, on the branch {branch}.")
|
||||
path = root.parent / f"{root.name}-{branch}"
|
||||
# A branch such as feature/7 would nest the worktree in a folder, so its slashes become dashes.
|
||||
path = root.parent / f"{root.name}-{branch.replace('/', '-')}"
|
||||
if path.exists():
|
||||
return Failure(f"none made, since {path} exists and holds no worktree on the branch {branch}")
|
||||
args, how = worktree_add(branch, path, default, commit_exists(f"refs/heads/{branch}"), commit_exists(f"refs/remotes/origin/{branch}"))
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import dataclasses
|
||||
import os
|
||||
import pathlib
|
||||
import shutil
|
||||
@@ -8,13 +9,16 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.templates import BRANCH
|
||||
from chunk_preflight import choices
|
||||
from failure import Failure
|
||||
from chunk_preflight.choices import forge_of, planned, worktree_add
|
||||
from chunk_preflight.choices import forge_of, worktree_add
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, NoItem, Ran, Worktree
|
||||
from test_env import isolated_env
|
||||
from release_plan.release_standing import LastCut, UNSEEN_RELEASES
|
||||
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
|
||||
from chunk_preflight.facts import open_pulls, render
|
||||
from plan_store.stores import plan_of
|
||||
from project_config.test_project_config import write_config
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
@@ -136,7 +140,7 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
worktree = repo.temp / "proj-item-7"
|
||||
self.assertIn("item 7, L 1, E + I 2", done.stdout, "origin's todo.md still holds item 3, which the plan in the config's folder does not")
|
||||
self.assertIn(f"- The project's config puts its files at: plan {folder}/todo.md; working-rules {worktree}/AGENTS.md; decisions {worktree}/docs/decisions.md; ", done.stdout)
|
||||
self.assertIn(f"- The project's config puts its files and plan at: plan {folder}/todo.md; working-rules {worktree}/AGENTS.md; decisions {worktree}/docs/decisions.md; ", done.stdout)
|
||||
self.assertIn("`rank_todo.py --check` exited 0", done.stdout)
|
||||
self.assertIn(f"- {UNSEEN_RELEASES}\n", done.stdout)
|
||||
config.unlink()
|
||||
@@ -144,6 +148,20 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertEqual((refused.returncode, refused.stdout), (1, ""))
|
||||
self.assertIn(f"no config names the checkout {repo.root}", refused.stderr)
|
||||
|
||||
def test_names_the_branch_and_the_worktree_by_the_configs_template_and_states_the_language_and_templates(self):
|
||||
repo = Repo(self)
|
||||
repo.push_from_elsewhere("todo.md", SHIPPED)
|
||||
plain = repo.preflight()
|
||||
self.assertIn("- The project's config sets: language English; commit-title {summary}; pull-request-title {summary}; branch item-{id}.\n", plain.stdout)
|
||||
config = repo.temp / "home" / ".claude-projects" / "proj" / "config.toml"
|
||||
config.write_text(config.read_text() + 'language = "Swedish"\ncommit-title = "PAY-{id} - {summary}"\nbranch = "feature/PAY-{id}"\n')
|
||||
done = repo.preflight("--worktree")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
worktree = repo.temp / "proj-feature-PAY-7"
|
||||
self.assertEqual(repo.git(worktree, "rev-parse", "--abbrev-ref", "HEAD").strip(), "feature/PAY-7")
|
||||
self.assertIn("- Open pull requests from feature/PAY-7: ", done.stdout)
|
||||
self.assertIn("- The project's config sets: language Swedish; commit-title PAY-{id} - {summary}; pull-request-title {summary}; branch feature/PAY-{id}.\n", done.stdout)
|
||||
|
||||
def test_reads_the_fetched_default_branchs_plan_and_makes_the_items_worktree_off_it_leaving_the_checkout_as_it_was(self):
|
||||
repo = Repo(self)
|
||||
repo.push_from_elsewhere("todo.md", SHIPPED)
|
||||
@@ -342,13 +360,18 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertIn("git rev-parse --show-toplevel", done.stderr)
|
||||
|
||||
|
||||
def planned(todo, *rest):
|
||||
"""choices.planned for the plan a todo.md's text holds, or for the Failure given."""
|
||||
return choices.planned(plan_of(todo) if isinstance(todo, str) else todo, *rest)
|
||||
|
||||
|
||||
def item_facts(todo=TODO, **fields):
|
||||
"""The facts of todo's next item, its worktree made, with fields given replacing the rest."""
|
||||
return ItemFacts(**{"plan": planned(todo, CUT, "origin/main"), "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "added on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields})
|
||||
return ItemFacts(**{"plan": planned(todo, CUT, "origin/main", BRANCH), "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "added on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields})
|
||||
|
||||
|
||||
def gathered(item, release=CUT, note=None, plan_outside=False):
|
||||
return Gathered("origin/main", note, release, item, "origin/main's todo.md", {"plan": pathlib.Path("/c/proj-item-3/todo.md"), "changelog": pathlib.Path("/c/proj-item-3/CHANGELOG.md")}, plan_outside)
|
||||
return Gathered("origin/main", note, release, item, "origin/main's todo.md", {"plan": pathlib.Path("/c/proj-item-3/todo.md"), "changelog": pathlib.Path("/c/proj-item-3/CHANGELOG.md")}, plan_outside, {"language": "English"})
|
||||
|
||||
|
||||
def rendered(item, release=CUT, note=None):
|
||||
@@ -366,8 +389,8 @@ class Render(unittest.TestCase):
|
||||
|
||||
def test_states_each_fact_once_with_the_paths_between_the_worktree_and_the_open_pull_requests(self):
|
||||
lines = render(gathered(item_facts()))
|
||||
self.assertEqual([line.partition(":")[0] for line in lines[:5]], ["- Last version cut", "- The earliest release in origin/main's todo.md", "- Worktree", "- The project's config puts its files at", "- Open pull requests from item-3"])
|
||||
self.assertEqual([line for line in lines[5:] if line.startswith("- Open pull requests")], [])
|
||||
self.assertEqual([line.partition(":")[0] for line in lines[:6]], ["- Last version cut", "- The earliest release in origin/main's todo.md", "- Worktree", "- The project's config puts its files and plan at", "- The project's config sets", "- Open pull requests from item-3"])
|
||||
self.assertEqual([line for line in lines[6:] if line.startswith("- Open pull requests")], [])
|
||||
|
||||
def test_says_that_a_plan_outside_the_checkout_hides_a_release_whose_items_are_all_done(self):
|
||||
for item in (item_facts(), NoItem("the plan holds no item.")):
|
||||
@@ -382,23 +405,24 @@ class Render(unittest.TestCase):
|
||||
self.assertIn("Item 7's detail:\n\n> Touch `src/other.py`.\n> \n> Run the e2e leg.", said)
|
||||
self.assertNotIn("Not quoted", said)
|
||||
|
||||
def test_lists_a_joining_item_nobody_scored_as_unscored(self):
|
||||
plan = item_facts().plan
|
||||
unscored = [dataclasses.replace(item, scores={}) if item.id == 7 else item for item in plan.items]
|
||||
said = rendered(item_facts(plan=dataclasses.replace(plan, items=unscored)))
|
||||
self.assertIn(" - item 7, L unscored, E + I unscored, S unscored: ", said)
|
||||
|
||||
def test_states_that_a_joining_item_has_no_detail(self):
|
||||
said = rendered(item_facts())
|
||||
self.assertIn("Item 7 has no detail.", said)
|
||||
self.assertNotIn("Item 7's detail", said)
|
||||
|
||||
def test_states_that_the_joining_items_details_cannot_be_read(self):
|
||||
said = rendered(item_facts(TODO + "\n```\nx\n```\n"))
|
||||
self.assertIn("The details of the items that may join cannot be read: ## Details holds a fenced code block", said)
|
||||
self.assertNotIn("has no detail", said)
|
||||
|
||||
def test_quotes_the_details_of_the_first_ten_joining_items_and_names_the_rest(self):
|
||||
rows = "".join(f"| {id_} | 0.2.0 | | | **Do thing {id_}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n" for id_ in range(20, 32))
|
||||
details = "".join(f"\n### {id_}. Do thing {id_}.\n\nDetail {id_}.\n" for id_ in range(7, 8)) + "".join(f"\n### {id_}. Do thing {id_}.\n\nDetail {id_}.\n" for id_ in range(20, 32))
|
||||
said = rendered(item_facts(TODO.replace("\n## Details", rows + "\n## Details") + details))
|
||||
self.assertIn("> Detail 28.", said)
|
||||
self.assertNotIn("Detail 29.", said)
|
||||
self.assertIn("The details of items 29, 30 and 31 are not quoted: only the first 10 are. Open `todo.md` for them.", said)
|
||||
self.assertIn("The details of items 29, 30 and 31 are not quoted: only the first 10 are. Run `~/.claude/bin/todo-item show <ID>` for each.", said)
|
||||
|
||||
def test_states_the_items_worktree_or_why_none_was_made(self):
|
||||
self.assertIn("/c/proj-item-3", rendered(item_facts()))
|
||||
@@ -493,40 +517,40 @@ class OpenPulls(unittest.TestCase):
|
||||
|
||||
class Plans(unittest.TestCase):
|
||||
def test_picks_the_earliest_releases_first_item_that_does_not_wait_or_says_why_there_is_none(self):
|
||||
self.assertEqual(planned(TODO, CUT, "origin/main").first.id, 3)
|
||||
waits = planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |"), CUT, "origin/main")
|
||||
self.assertEqual(planned(TODO, CUT, "origin/main", BRANCH).first.id, 3)
|
||||
waits = planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |"), CUT, "origin/main", BRANCH)
|
||||
self.assertIn("waits", waits.why)
|
||||
self.assertIn("0.2.0", waits.why)
|
||||
self.assertIn("Permission denied", planned(Failure("Permission denied"), CUT, "origin/main").why)
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main").why, "origin/main's todo.md cannot be read: Permission denied.")
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main", pathlib.Path("/projects/acme/todo.md")).why, "/projects/acme/todo.md cannot be read: Permission denied.")
|
||||
self.assertIn("L 'x'", planned(TODO.replace("| 2 | 2 | 3 | 5 |", "| x | 2 | 3 | 5 |"), CUT, "origin/main").why)
|
||||
self.assertIn("details cannot be read", planned(TODO + "```\n", CUT, "origin/main").text)
|
||||
self.assertIn("Permission denied", planned(Failure("Permission denied"), CUT, "origin/main", BRANCH).why)
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main", BRANCH).why, "origin/main's todo.md cannot be read: Permission denied.")
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main", BRANCH, pathlib.Path("/projects/acme/todo.md")).why, "/projects/acme/todo.md cannot be read: Permission denied.")
|
||||
self.assertIn("L 'x'", planned(TODO.replace("| 2 | 2 | 3 | 5 |", "| x | 2 | 3 | 5 |"), CUT, "origin/main", BRANCH).why)
|
||||
self.assertIn("## Details holds a fenced code block", planned(TODO + "```\n", CUT, "origin/main", BRANCH).why)
|
||||
|
||||
def test_tells_a_plan_with_no_items_table_from_one_whose_table_holds_no_item(self):
|
||||
without = planned("", CUT, "origin/main").why
|
||||
without = planned("", CUT, "origin/main", BRANCH).why
|
||||
self.assertIn("origin/main", without)
|
||||
self.assertIn("no items table", without)
|
||||
self.assertNotIn("cannot be read", without)
|
||||
empty = planned(EMPTY, LastCut(None, "", 4, []), "origin/main").why
|
||||
empty = planned(EMPTY, LastCut(None, "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("holds no item", empty)
|
||||
self.assertNotIn("no items table", empty)
|
||||
|
||||
def test_names_a_release_cut_under_a_dated_heading_as_the_last_cut_on_a_branch_with_no_tag(self):
|
||||
said = planned(EMPTY, LastCut(None, "## 0.0.1 - 2026-10-03\n", 0, []), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(None, "## 0.0.1 - 2026-10-03\n", 0, []), "origin/main", BRANCH).why
|
||||
self.assertIn("the next release after the last cut, 0.0.1 (dated in CHANGELOG.md)", said)
|
||||
|
||||
def test_says_the_tags_cannot_be_read_with_gits_reason_and_names_no_cut(self):
|
||||
said = planned(EMPTY, LastCut(Failure("git exited 128: not a git repository"), "", 4, []), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(Failure("git exited 128: not a git repository"), "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("origin/main's tags cannot be read: git exited 128: not a git repository.", said)
|
||||
self.assertIn("Find the next release yourself.", said)
|
||||
self.assertNotIn("no release is cut yet", said)
|
||||
|
||||
def test_names_the_start_as_the_last_cut_where_nothing_is_cut(self):
|
||||
said = planned(EMPTY, LastCut(None, "", 4, [TODO]), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(None, "", 4, [TODO]), "origin/main", BRANCH).why
|
||||
self.assertIn("release 0.2.0, the next after the start, since no release is cut yet,", said)
|
||||
self.assertIn("has landed yet.", said)
|
||||
self.assertIn("since the cut.", planned(EMPTY, LastCut(None, "## 0.1.0 - 2026-10-03\n", 4, [TODO]), "origin/main").why)
|
||||
self.assertIn("since the cut.", planned(EMPTY, LastCut(None, "## 0.1.0 - 2026-10-03\n", 4, [TODO]), "origin/main", BRANCH).why)
|
||||
|
||||
def test_finds_the_release_after_the_last_cut_finished_or_to_be_planned_where_the_plan_holds_no_item_for_it(self):
|
||||
named = "release 0.2.0, the next after the last cut, v0.1.0"
|
||||
@@ -542,24 +566,24 @@ class Plans(unittest.TestCase):
|
||||
)
|
||||
for todo, commits, todos, reviewed, fact, release in cases:
|
||||
with self.subTest(todo=todo, commits=commits, todos=todos, reviewed=reviewed):
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos, reviewed), "origin/main").why
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos, reviewed), "origin/main", BRANCH).why
|
||||
self.assertIn(fact, why)
|
||||
self.assertIn(release, why)
|
||||
|
||||
def test_says_what_todo_md_named_since_the_last_cut_cannot_be_read(self):
|
||||
self.assertIn("cannot be read", planned(LATER, LastCut("v0.1.0", "", 4, Failure("log unreadable")), "origin/main").why)
|
||||
self.assertIn("cannot be read", planned(LATER, LastCut("v0.1.0", "", 4, Failure("log unreadable")), "origin/main", BRANCH).why)
|
||||
|
||||
def test_takes_the_earliest_release_where_no_earlier_one_was_named_since_the_last_cut(self):
|
||||
self.assertEqual(planned(LATER, LastCut("v0.1.0", "", 4, [LATER]), "origin/main").first.id, 9)
|
||||
self.assertEqual(planned(LATER, LastCut("v0.1.0", "", 4, [LATER]), "origin/main", BRANCH).first.id, 9)
|
||||
|
||||
def test_says_the_plan_files_items_under_a_release_already_cut(self):
|
||||
why = planned(TODO, LastCut("v0.2.0", "", 4, []), "origin/main").why
|
||||
why = planned(TODO, LastCut("v0.2.0", "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("release 0.2.0", why)
|
||||
self.assertIn("v0.2.0", why)
|
||||
self.assertIn("not after", why)
|
||||
|
||||
def test_takes_an_item_without_a_detail_as_its_tagline_alone(self):
|
||||
self.assertEqual(planned(TODO[:TODO.index("## Details")], CUT, "origin/main").text, "**Do the next thing.**")
|
||||
self.assertEqual(planned(TODO[:TODO.index("## Details")], CUT, "origin/main", BRANCH).text, "**Do the next thing.**")
|
||||
|
||||
|
||||
class Gathering(unittest.TestCase):
|
||||
@@ -604,5 +628,33 @@ class Running(unittest.TestCase):
|
||||
self.assertIsNone(line_count(folder))
|
||||
|
||||
|
||||
class BesideTest(unittest.TestCase):
|
||||
"""The fact that names the items that may start chunks beside the next one."""
|
||||
# Items 3 and 4 touch other parts of one file, and item 6 touches what item 3 does.
|
||||
ROWS = "| 4 | 0.2.0 | | | **Do four.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n| 6 | 0.2.0 | | | **Do six.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
|
||||
DETAILS = "\nTouches:\n\n- `src/app.py`: `run`\n\n### 4. Do four.\n\nTouches:\n\n- `src/app.py`: `stop`\n\n### 6. Do six.\n\nTouches:\n\n- `src/app.py`: `run`\n"
|
||||
|
||||
def said(self, todo):
|
||||
return [line for line in rendered(item_facts(todo)).splitlines() if "beside" in line]
|
||||
|
||||
def test_names_the_items_that_may_start_chunks_beside_it_and_why_the_others_may_not(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS
|
||||
self.assertEqual(self.said(todo), ["- The items of release 0.2.0 that may start chunks beside item 3's: 4. None is predicted to touch a part that item 3 touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own. Not beside it: item 6, which overlaps item 3 at `src/app.py` `run`."])
|
||||
|
||||
def test_names_each_item_that_may_and_stops_there_when_none_is_refused(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS.removesuffix("`run`\n") + "`other`\n"
|
||||
self.assertEqual(self.said(todo), ["- The items of release 0.2.0 that may start chunks beside item 3's: 4, 6. None is predicted to touch a part that item 3 touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own."])
|
||||
|
||||
def test_says_when_none_may(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS.replace("`stop`", "`run`")
|
||||
self.assertEqual(self.said(todo), ["- No item of release 0.2.0 may start a chunk beside item 3's. Not beside it: item 4, which overlaps item 3 at `src/app.py` `run`; item 6, which overlaps item 3 at `src/app.py` `run`."])
|
||||
alone = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + "\n### 4. Do four.\n\nTouches:\n\n- `src/app.py`\n"
|
||||
self.assertEqual(self.said(alone), ["- No item of release 0.2.0 may start a chunk beside item 3's: item 3's detail has no `Touches:` list."])
|
||||
|
||||
def test_says_nothing_in_a_plan_without_predictions(self):
|
||||
self.assertEqual(self.said(TODO), [])
|
||||
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -95,6 +95,11 @@ def resolved(base: str, path: str, home: str) -> str:
|
||||
return posixpath.normpath(posixpath.join(base, home + path[1:] if path == "~" or path.startswith("~/") else path))
|
||||
|
||||
|
||||
def home_word(token: str) -> str:
|
||||
"""The word with a leading $HOME or ${HOME} spelt as ~; the lexer has joined a quoted "$HOME" to the rest of its word."""
|
||||
return re.sub(r"^\$(HOME|\{HOME\})(?=/|$)", "~", token)
|
||||
|
||||
|
||||
def tool_name(word: str) -> str:
|
||||
"""The tool a word names, such as mutmut for `mutmut>=3,<4` or `.venv/bin/mutmut`; empty for a word that names none, such as a file name."""
|
||||
named = re.fullmatch(r"([A-Za-z_-]+)(?:[<>=!~@].*)?", posixpath.basename(word))
|
||||
|
||||
@@ -9,13 +9,16 @@ import sys
|
||||
import tempfile
|
||||
|
||||
from release_plan.release_standing import chunk_item, Cut, default_plan, Next, ReadyToCut, ReviewDue, Unplanned
|
||||
from project_config.settings import DEFAULT_FLOOR
|
||||
from git_cli.git_repo import default_ref, git
|
||||
from deploy_release.deploy import deploy
|
||||
from failure import Failure
|
||||
from plan_store.stores import FilePlan
|
||||
from record_store.stores import FileStore
|
||||
from deploy_release import forge
|
||||
from chunk_preflight.choices import forge_of
|
||||
from release_plan.todo_table import items
|
||||
from release_plan.release import newest_tag, Release, version
|
||||
from project_config import templates
|
||||
|
||||
|
||||
def cut(clone: str, checkout: str) -> str | Failure:
|
||||
@@ -106,13 +109,19 @@ def same_origin(clone: str, checkout: str) -> Failure | None:
|
||||
return None
|
||||
|
||||
|
||||
def clone_plan(clone: str) -> FilePlan:
|
||||
"""The clone's plan, at the path this repo keeps it. ready_release only reads it; FilePlan also takes the files and the floor a write would rank it against, and the clone has no config to set the floor."""
|
||||
goals, decisions, history = (FileStore(pathlib.Path(clone, path), path) for path in ("README.md", "docs/decisions.md", "docs/comprehension-history.md"))
|
||||
return FilePlan(pathlib.Path(clone, "todo.md"), "todo.md", goals, decisions, history, DEFAULT_FLOOR)
|
||||
|
||||
|
||||
def ready_release(clone: str, ref: str) -> Release | Failure:
|
||||
"""The next release, as chunk-preflight works it out, where it is ready to cut: it holds no item in todo.md, its release review has landed and changes are unreleased."""
|
||||
plan = default_plan(clone, ref, "todo.md", "CHANGELOG.md")
|
||||
found = items(plan.todo) if isinstance(plan.todo, str) else plan.todo
|
||||
if isinstance(found, Failure):
|
||||
return Failure(f"todo.md on {ref} cannot be read: {found.reason}")
|
||||
match chunk_item(found, plan.cut):
|
||||
# No project's config names the clone, so its changelog is read at the fixed path, on ref like the plan, and its titles as they stand.
|
||||
plan = default_plan(clone, ref, clone_plan(clone), FileStore(pathlib.Path(clone, "CHANGELOG.md"), "CHANGELOG.md"), templates.BARE)
|
||||
if isinstance(plan.todo, Failure):
|
||||
return Failure(f"todo.md on {ref} cannot be read: {plan.todo.reason}")
|
||||
match chunk_item(plan.todo.items, plan.cut):
|
||||
case ReadyToCut(release=release) if release is not None:
|
||||
return release
|
||||
case ReadyToCut():
|
||||
|
||||
@@ -126,7 +126,7 @@ class Main(unittest.TestCase):
|
||||
result = reply(Rung(args[args.index("--model") + 1], args[args.index("--effort") + 1]), "said Verdict: interrupt" in prompt.rsplit("latest last:", 1)[-1])
|
||||
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
|
||||
|
||||
effects = Effects(alive=unused, claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, input_or=unused, local_time=unused, memory=unused, new_id=unused, now=unused, on_terminal=unused, pid=unused, python=unused, sleep=unused, stream_claude=unused)
|
||||
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
|
||||
out, err = io.StringIO(), io.StringIO()
|
||||
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
|
||||
code = main.main(argv, {}, self.home, effects)
|
||||
|
||||
@@ -4,18 +4,20 @@ from failure import Failure
|
||||
from git_cli.git_repo import file_at, full_history, git
|
||||
from review_rules.comprehension_history import HistoryChange
|
||||
from project_config.main import located
|
||||
from record_store.stores import store
|
||||
|
||||
|
||||
def history_changes(default: str, home: pathlib.Path) -> list[HistoryChange] | Failure:
|
||||
"""Each merged change on the default branch that touched the history, newest first. A Failure where the project's config puts the history outside the checkout, where no commit holds it."""
|
||||
"""Each merged change on the default branch that touched the history, newest first. A Failure where no commit holds the history, as for one the project's config puts outside the checkout."""
|
||||
if partial := full_history():
|
||||
return partial
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
history = config.tracked("comprehension-history")
|
||||
record = store(config, "comprehension-history")
|
||||
history = record.tracked
|
||||
if history is None:
|
||||
return Failure(f"larv-review doesn't support a comprehension history outside the checkout: no commit holds {config.paths['comprehension-history']}, so it cannot tell which commit was last measured")
|
||||
return Failure(f"larv-review doesn't support a comprehension history outside the checkout: no commit holds {record.label}, so it cannot tell which commit was last measured")
|
||||
# history names the file from the checkout's top, and git reads a path from the directory it runs in.
|
||||
root = str(config.top)
|
||||
commits = git("log", "--first-parent", "--format=%H", default, "--", history, cwd=root)
|
||||
|
||||
@@ -2,7 +2,7 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from larv_review.agreement import agreement_report
|
||||
from review_rules.comprehension_history import appended, DIMENSIONS, FLOOR, heading, Heading, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
|
||||
from review_rules.comprehension_history import appended, DIMENSIONS, heading, Heading, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
|
||||
from larv_review.plan import checkout_plan, plan_reasons
|
||||
from git_cli.git_repo import commit_exists
|
||||
from larv_review.ruling import counted, overall, ruling, split, surplus, votes
|
||||
@@ -11,8 +11,9 @@ from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile
|
||||
from larv_review.scoring import floor_step, means, under_floor
|
||||
from project_config.main import located
|
||||
from release_plan import plan_file
|
||||
from plan_store.stores import store as plan_store
|
||||
from record_store.stores import RecordStore, store
|
||||
from larv_review.scoring_setup import removed_setup
|
||||
from text_files.file_writes import replace_file
|
||||
|
||||
Say = typing.Callable[[str], None]
|
||||
|
||||
@@ -56,18 +57,18 @@ def record_scoring(default: str, scores_file: pathlib.Path, ids: list[int], home
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
checkout = str(config.top)
|
||||
todo = checkout_plan(config.paths["plan"])
|
||||
todo = checkout_plan(plan_store(config))
|
||||
if isinstance(todo, Failure):
|
||||
return todo
|
||||
_, plan = todo
|
||||
plan = todo.items
|
||||
appended_to = append(given.read, scoring_entry(named.title, scoring), home)
|
||||
if isinstance(appended_to, Failure):
|
||||
return appended_to
|
||||
say(appended_to)
|
||||
say(f"Means: {', '.join(f'{name} {value}' for name, value in zip(DIMENSIONS, scoring.means))}.")
|
||||
if under := under_floor(scoring.means):
|
||||
say(f"Floor: {', '.join(under)} under the floor of {FLOOR}.")
|
||||
if step := floor_step(scoring.means, plan, ids):
|
||||
if under := under_floor(scoring.means, config.readability_floor):
|
||||
say(f"Floor: {', '.join(under)} under the floor of {config.readability_floor}.")
|
||||
if step := floor_step(scoring.means, plan, ids, config.readability_floor):
|
||||
say(step)
|
||||
reranked = rerank(home, warn)
|
||||
removed = removed_setup(checkout, home)
|
||||
@@ -79,7 +80,10 @@ def rerank(home: pathlib.Path, warn: Say) -> Failure | None:
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
todo = config.paths["plan"]
|
||||
todo = config.plan_file
|
||||
if todo is None:
|
||||
# A plan in Jira is ranked by Jira's backlog, which no score moves.
|
||||
return None
|
||||
ranked = plan_file.rank_file(todo, config)
|
||||
if isinstance(ranked, Failure):
|
||||
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
|
||||
@@ -109,7 +113,7 @@ def read_seats(path: pathlib.Path, paired: bool, home: pathlib.Path, now: float)
|
||||
return decided(text, now, paired, commit_exists, history)
|
||||
|
||||
|
||||
def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[str], bool], history: tuple[pathlib.Path, str]) -> tuple[Heading, SeatsFile] | Failure:
|
||||
def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[str], bool], history: tuple[RecordStore, str]) -> tuple[Heading, SeatsFile] | Failure:
|
||||
"""The heading the seats file's entry goes under, stamped with now, and the file parsed from text. Fails when text names a commit that commit_known denies, or when the history already holds an entry on what the seats read."""
|
||||
given = seats_file(text)
|
||||
if isinstance(given, Failure):
|
||||
@@ -120,7 +124,7 @@ def decided(text: str, now: float, paired: bool, commit_known: typing.Callable[[
|
||||
if unknown := [commit for commit in (named.commit, named.against) if commit and not commit_known(commit)]:
|
||||
return Failure(f"the seats file names {', '.join(unknown)}, which is no commit in this checkout")
|
||||
if recorded(history[1], given.read):
|
||||
return Failure(f"{history[0]} already holds an entry on {given.read}; record each ruling or run once")
|
||||
return Failure(f"{history[0].label} already holds an entry on {given.read}; record each ruling or run once")
|
||||
return named, given
|
||||
|
||||
|
||||
@@ -139,16 +143,14 @@ def read_agreement(home: pathlib.Path) -> str | Failure:
|
||||
return history if isinstance(history, Failure) else agreement_report(history[1])
|
||||
|
||||
|
||||
def history_file(home: pathlib.Path) -> tuple[pathlib.Path, str] | Failure:
|
||||
"""The project's comprehension history, where its config puts it, and its text, empty when the file is missing."""
|
||||
def history_file(home: pathlib.Path) -> tuple[RecordStore, str] | Failure:
|
||||
"""The store the project's config names for its comprehension history, and the history's text, empty where there is none yet."""
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
history = config.paths["comprehension-history"]
|
||||
try:
|
||||
return history, history.read_text(encoding="utf-8") if history.exists() else ""
|
||||
except (OSError, UnicodeDecodeError) as failure:
|
||||
return Failure(f"could not read {history}: {failure}")
|
||||
history = store(config, "comprehension-history")
|
||||
text = history.read()
|
||||
return text if isinstance(text, Failure) else (history, text)
|
||||
|
||||
|
||||
def append(read: str, entry: str, home: pathlib.Path) -> str | Failure:
|
||||
@@ -158,11 +160,7 @@ def append(read: str, entry: str, home: pathlib.Path) -> str | Failure:
|
||||
return read_history
|
||||
history, text = read_history
|
||||
if recorded(text, read):
|
||||
return Failure(f"{history} already holds an entry on {read}; record each ruling or run once")
|
||||
try:
|
||||
history.parent.mkdir(parents=True, exist_ok=True)
|
||||
except OSError as failure:
|
||||
return Failure(f"could not create {history.parent}: {failure}")
|
||||
if unwritten := replace_file(history, appended(text, entry).encode()):
|
||||
return Failure(f"could not write {history}: {unwritten.reason}")
|
||||
return f"Appended to {history}."
|
||||
return Failure(f"{history.label} already holds an entry on {read}; record each ruling or run once")
|
||||
if unwritten := history.write(appended(text, entry)):
|
||||
return unwritten
|
||||
return f"Appended to {history.label}."
|
||||
|
||||
+17
-11
@@ -101,7 +101,8 @@ record-scoring never removed is still there, it removes it first and says so.
|
||||
record-scoring takes the scores file of a run needs-scoring-run calls, whose first line names no
|
||||
`, against`, and the same item IDs, and exits 1 when they call no run. It appends the seats' scores
|
||||
and their means, rounded half up to two decimals, prints the means and, when a mean is under the
|
||||
floor of {floor}, a line opening `Floor:` naming each one. A line opening `Next:` follows it. It
|
||||
project's readability floor, a line opening `Floor:` naming each one and the floor. The config sets
|
||||
the floor as `readability-floor`, {floor} where left out. A line opening `Next:` follows it. It
|
||||
says to file a floor item aimed at the lowest of the four dimensions, and names the tagline's opening
|
||||
`Reach the comprehension floor:`. Where the project's todo.md holds such an item other than those given, it says to
|
||||
refresh that item instead. Then it ranks the project's todo.md as rank_todo.py does, since the
|
||||
@@ -129,16 +130,17 @@ reviewer-header takes the name of a pass that an agent under agents/ reviews, sp
|
||||
prints it, such as stability. It prints the header of the prompt that launches the pass's reviewer
|
||||
in its next round: the pass and round, the branch's open pull request at its pushed head, the
|
||||
worktree and branch, the merge base of HEAD and the default branch, and the paths of the reviewer's
|
||||
report, the branch diff, the folder of technical principles the project's config sets and, for
|
||||
architecture and stability, the places. For a reviewer whose
|
||||
report, the branch diff, the folders of technical principles and review standards the project's
|
||||
config sets, the goals and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
definition under ~/.claude/agents/ has `omitClaudeMd: true`, it then names the file that holds the
|
||||
project principles and decision titles, where the project keeps one. It writes the diff, from
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, and writes what
|
||||
places prints into places.md; a file whose text is unchanged is left as it is. With --rerun, the
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, writes what
|
||||
places prints into places.md, and lists the plan's items into
|
||||
plan.md, whatever store holds the plan; a file whose text is unchanged is left as it is. With --rerun, the
|
||||
header names the report of a relaunch one rung up, in the same round, and the report that asked for
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when the
|
||||
principles folder it names is not a folder with a file in it, or, with --rerun, when the report that
|
||||
asked is missing.
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when
|
||||
the principles or standards folder is not a folder with a file in it, or, with --rerun, when the
|
||||
report that asked is missing.
|
||||
|
||||
reviewer-context is the SubagentStart hook. It reads the hook's input on stdin. For a reviewer
|
||||
whose definition under ~/.claude/agents/ has `omitClaudeMd: true`, and so starts without CLAUDE.md,
|
||||
@@ -161,8 +163,8 @@ import typing
|
||||
|
||||
from git_cli.git_repo import branch_titles, default_branch, git, top
|
||||
from review_rules.round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
|
||||
from project_config.settings import DEFAULT_FLOOR
|
||||
from failure import Failure
|
||||
from review_rules.comprehension_history import FLOOR
|
||||
from larv_review.history_changes import history_changes
|
||||
from review_rules.reviewer_context import hook_reply
|
||||
from review_rules.review_folder import made_review_folder
|
||||
@@ -174,6 +176,7 @@ from larv_review.plan import plan_reasons
|
||||
from larv_review.scoring_setup import prepare_scoring
|
||||
from larv_review.history_commands import read_agreement, read_places, record_ruling, record_scoring
|
||||
from larv_review.reviewer_header import reviewer_header
|
||||
from project_config.main import title_templates
|
||||
|
||||
|
||||
class Command(typing.NamedTuple):
|
||||
@@ -236,7 +239,7 @@ USAGE = f"usage: larv-review {SHAPES}"
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if argv in (["-h"], ["--help"]):
|
||||
print(__doc__.strip().format(commands=SHAPES, cap=CAP, release_cap=RELEASE_REVIEW_CAP, floor=FLOOR, pairs=MIN_PAIRS))
|
||||
print(__doc__.strip().format(commands=SHAPES, cap=CAP, release_cap=RELEASE_REVIEW_CAP, floor=DEFAULT_FLOOR, pairs=MIN_PAIRS))
|
||||
return 0
|
||||
if not argv:
|
||||
print(USAGE, file=sys.stderr)
|
||||
@@ -313,7 +316,10 @@ def round_count(default: str) -> Failure | None:
|
||||
titles = branch_titles(default)
|
||||
if isinstance(titles, Failure):
|
||||
return titles
|
||||
for name, count in round_counts(titles).items():
|
||||
templates = title_templates(None, pathlib.Path.home())
|
||||
if isinstance(templates, Failure):
|
||||
return templates
|
||||
for name, count in round_counts([templates.summary(title) for title in titles]).items():
|
||||
print(f"{name}: {count}{cap_note(count, cap(name)) if name in PASSES else ', not a pass: check the commit title'}")
|
||||
return None
|
||||
|
||||
|
||||
+13
-14
@@ -5,8 +5,10 @@ from larv_review.plan import EMPTIED_WORDS, plan_reasons
|
||||
from review_rules.comprehension_history import entries
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import file_at, git
|
||||
from release_plan.todo_table import items, NoItemsTable
|
||||
from project_config.main import located
|
||||
from release_plan.todo_table import NoItemsTable
|
||||
from plan_store.stores import store as plan_store, PlanStore
|
||||
from record_store.stores import store
|
||||
|
||||
|
||||
def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[str], None]) -> Failure | None:
|
||||
@@ -18,13 +20,14 @@ def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[st
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
checkout = str(config.top)
|
||||
if not has_plan(config.paths["plan"]):
|
||||
if not has_plan(plan_store(config)):
|
||||
return None
|
||||
# No commit holds a file outside the checkout. So the plan as the chunk found it cannot be read, nor the runs the branch recorded counted; the merge goes on, as `docs/decisions.md` → "project config: a tool that reads a file's commits …" says.
|
||||
plan, history = config.tracked("plan"), config.tracked("comprehension-history")
|
||||
# No commit holds a file outside the checkout, nor a record kept outside git. So the plan as the chunk found it cannot be read, nor the runs the branch recorded counted; the merge goes on, as `docs/decisions.md` → "project config: a tool that reads a file's commits …" says.
|
||||
record = store(config, "comprehension-history")
|
||||
plan, history = config.tracked("plan"), record.tracked
|
||||
if plan is None or history is None:
|
||||
name, setting = ("plan", "plan") if plan is None else ("comprehension history", "comprehension-history")
|
||||
warn(f"larv-review doesn't support a {name} outside the checkout, so it cannot tell whether the chunk owes a scoring run: {config.paths[setting]}")
|
||||
name, where = ("plan", config.plan_label) if plan is None else ("comprehension history", record.label)
|
||||
warn(f"larv-review doesn't support a {name} outside the checkout, so it cannot tell whether the chunk owes a scoring run: {where}")
|
||||
return None
|
||||
base = git("merge-base", default, "HEAD", cwd=checkout)
|
||||
if isinstance(base, Failure):
|
||||
@@ -51,14 +54,10 @@ def shortfall(reasons: list[str], recorded: int) -> Failure | None:
|
||||
return Failure(f"the chunk owes {needed} scoring run{'s' if needed > 1 else ''} and the branch's committed history records {max(recorded, 0)}: it {' and '.join(reasons)}. larv-review's SKILL.md → 'Scoring run' says how to run and record {'them' if needed > 1 else 'it'}{"; → 'Second run' says how the second is titled" if needed > 1 else ""}")
|
||||
|
||||
|
||||
def has_plan(todo: pathlib.Path) -> bool:
|
||||
"""Whether todo, the project's plan, exists and holds an items table. A file that can't be read counts, so `plan_reasons` reports it."""
|
||||
try:
|
||||
return not isinstance(items(todo.read_text(encoding="utf-8")), NoItemsTable)
|
||||
except FileNotFoundError:
|
||||
return False
|
||||
except (OSError, UnicodeDecodeError):
|
||||
return True
|
||||
def has_plan(plan: PlanStore) -> bool:
|
||||
"""Whether the project has set a plan up. One that can't be read counts, so `plan_reasons` reports it."""
|
||||
return not isinstance(plan.read(), NoItemsTable)
|
||||
|
||||
|
||||
|
||||
def scoring_runs(history: str) -> list[str]:
|
||||
|
||||
+30
-34
@@ -1,12 +1,16 @@
|
||||
import pathlib
|
||||
|
||||
from release_plan.release_standing import Cut, default_plan, held_at, LastCut, next_release, Unknown
|
||||
from release_plan.release_standing import Cut, LastCut, next_release, project_plan, Unknown
|
||||
from failure import Failure
|
||||
from larv_review.scoring import is_floor_item
|
||||
from release_plan.todo_table import Item, items, NoItemsTable, renames
|
||||
from release_plan.todo_table import Item, NoItemsTable
|
||||
from project_config.main import located
|
||||
from release_plan.goals_file import OPTED_OUT
|
||||
from plan_store.stores import Plan, PlanStore
|
||||
from plan_store import stores as plan_stores
|
||||
from project_config.settings import ProjectConfig
|
||||
from release_plan.release import Release, version
|
||||
from record_store import stores
|
||||
from larv_review.unmeasured import unmeasured_cut
|
||||
|
||||
|
||||
@@ -14,7 +18,7 @@ from larv_review.unmeasured import unmeasured_cut
|
||||
EMPTIED_WORDS = "with no plan item"
|
||||
|
||||
|
||||
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed_release: Release | None, renamed: set[Release], unmeasured: str | None = None) -> list[str] | Failure:
|
||||
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed_release: Release | None, renamed: frozenset[Release], unmeasured: str | None = None) -> list[str] | Failure:
|
||||
"""Why the plan calls a scoring run, empty when it does not.
|
||||
|
||||
A chunk that ships a floor item is due one, so it can prove the floor met. So is a chunk that empties a release after work has landed towards it, so no release ends unmeasured. A release the chunk's plan marks renamed is due none. A chunk after a release `unmeasured_cut` names is due one too, so a release cut with no scoring run is caught up.
|
||||
@@ -56,64 +60,56 @@ def landed_towards(found: list[Item], cut: LastCut) -> Release | None | Failure:
|
||||
return upcoming.release if upcoming.unreleased else None
|
||||
|
||||
|
||||
def emptied(before: list[Item], after: list[Item], shipped: list[Item], renamed: set[Release]) -> list[Release]:
|
||||
def emptied(before: list[Item], after: list[Item], shipped: list[Item], renamed: frozenset[Release]) -> list[Release]:
|
||||
"""Each release the default branch's plan or a shipped item names that the chunk's plan, less the shipped items, names no longer, unless the chunk's plan marks it renamed."""
|
||||
named = {item.release for item in before + shipped}
|
||||
kept = [item for item in after if item.id not in {ship.id for ship in shipped}]
|
||||
return sorted(named - {item.release for item in kept} - renamed)
|
||||
|
||||
|
||||
def finished_unseen(config: ProjectConfig, ids: list[int], chunk: list[Item]) -> Failure | None:
|
||||
"""Why the items under ids cannot all be read, where the plan lies outside the checkout: such a plan is read as it stands for both plans, so a finished item is in neither."""
|
||||
if config.tracked("plan") is None and (gone := sorted(set(ids) - {item.id for item in chunk})):
|
||||
return Failure(f"the plan as it stands holds no item {', '.join(map(str, gone))}, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {config.plan_label}")
|
||||
return None
|
||||
|
||||
|
||||
def plan_reasons(ref: str, ids: list[int] | None, home: pathlib.Path) -> list[str] | Failure:
|
||||
"""Why the plan calls a scoring run, from todo.md at ref and the checkout's, each file where the project's config puts it; empty where the project opts out of the comprehension check. ref is the default branch, or the commit where the chunk began. Where ids is None, the chunk ships each item the plan at ref holds and the checkout's does not."""
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
checkout = str(config.top)
|
||||
decisions = held_at(ref, config.place("decisions"), checkout)
|
||||
decisions = stores.held_at(ref, stores.store(config, "decisions"), checkout)
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
if OPTED_OUT.search(decisions):
|
||||
return []
|
||||
held = default_plan(checkout, ref, config.place("plan"), config.place("changelog"))
|
||||
held = project_plan(config, ref, checkout)
|
||||
before = held.todo
|
||||
if isinstance(before, Failure):
|
||||
return before
|
||||
read = checkout_plan(config.paths["plan"])
|
||||
read = checkout_plan(plan_stores.store(config))
|
||||
if isinstance(read, Failure):
|
||||
return read
|
||||
after, chunk = read
|
||||
chunk, renamed = read.items, read.renamed
|
||||
# While a chunk reshapes todo.md into one table, the default branch's todo.md has no items table.
|
||||
planned = items(before)
|
||||
if isinstance(planned, NoItemsTable):
|
||||
if isinstance(before, NoItemsTable):
|
||||
planned = []
|
||||
if isinstance(planned, Failure):
|
||||
return Failure(f"{ref}'s todo.md: {planned.reason}")
|
||||
renamed = renames(after)
|
||||
if isinstance(renamed, Failure):
|
||||
return Failure(f"the project's todo.md: {renamed.reason}")
|
||||
elif isinstance(before, Failure):
|
||||
return Failure(f"{ref}'s todo.md: {before.reason}")
|
||||
else:
|
||||
planned = before.items
|
||||
landed_release = landed_towards(planned, held.cut)
|
||||
if isinstance(landed_release, Failure):
|
||||
return landed_release
|
||||
unmeasured = unmeasured_cut(ref, config.place("comprehension-history"), checkout)
|
||||
unmeasured = unmeasured_cut(ref, stores.store(config, "comprehension-history"), checkout)
|
||||
if isinstance(unmeasured, Failure):
|
||||
return unmeasured
|
||||
if ids is None:
|
||||
ids = sorted({item.id for item in planned} - {item.id for item in chunk})
|
||||
# A plan outside the checkout is read as it stands for both plans, so a finished item is in neither.
|
||||
if config.tracked("plan") is None and (gone := sorted(set(ids) - {item.id for item in chunk})):
|
||||
return Failure(f"todo.md as it stands holds no item {', '.join(map(str, gone))}, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {config.paths['plan']}")
|
||||
return scoring_run_due(planned, chunk, ids, landed_release, renamed, unmeasured)
|
||||
return finished_unseen(config, ids, chunk) or scoring_run_due(planned, chunk, ids, landed_release, renamed, unmeasured)
|
||||
|
||||
|
||||
def checkout_plan(todo: pathlib.Path) -> tuple[str, list[Item]] | Failure:
|
||||
"""The checkout's plan, the todo.md the project's config names, as its text and its items."""
|
||||
try:
|
||||
text = todo.read_text(encoding="utf-8")
|
||||
except (OSError, UnicodeDecodeError) as failure:
|
||||
return Failure(f"could not read {todo}: {failure}")
|
||||
found = items(text)
|
||||
if isinstance(found, NoItemsTable):
|
||||
return Failure("the project's todo.md has no items table; rank_todo.py --help shows one")
|
||||
if isinstance(found, Failure):
|
||||
return Failure(f"the project's todo.md: {found.reason}")
|
||||
return text, found
|
||||
def checkout_plan(plan: PlanStore) -> Plan | Failure:
|
||||
"""The project's plan as it stands."""
|
||||
read = plan.read()
|
||||
return Failure(f"the project's plan: {read.reason}") if isinstance(read, Failure) else read
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
"""The plan as a listing a reviewer reads with the Read tool, whatever store holds the plan."""
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import Item
|
||||
from plan_store.stores import PlanStore
|
||||
from release_plan.release import version
|
||||
|
||||
|
||||
def plan_listing(plan: PlanStore) -> str:
|
||||
"""The plan's items as the store supplies them, each with its release, tagline, blockers and detail. Where the plan can't be read, says so, so a reviewer doesn't take it for empty."""
|
||||
read = plan.read()
|
||||
opening = f"# Plan, as {plan.label} holds it\n\n"
|
||||
if isinstance(read, Failure):
|
||||
return f"{opening}The plan cannot be read, so no item is listed: {read.reason}\n"
|
||||
if not read.items:
|
||||
return f"{opening}The plan holds no item.\n"
|
||||
return opening + "\n".join(item_listing(item) for item in read.items)
|
||||
|
||||
|
||||
def item_listing(item: Item) -> str:
|
||||
blockers = ", ".join(map(str, item.blocked_by))
|
||||
parts = [f"## Item {item.id}, release {version(item.release)}", item.tagline, *([f"Blocked by: {blockers}."] if blockers else []), *([item.detail] if item.detail else [])]
|
||||
return "\n\n".join(parts) + "\n"
|
||||
@@ -1,4 +1,4 @@
|
||||
"""reviewer-header: write the branch diff and the places into the chunk's review folder, and print the header of a reviewer's prompt."""
|
||||
"""reviewer-header: write the branch diff, the places and the plan into the chunk's review folder, and print the header of a reviewer's prompt."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
|
||||
@@ -6,10 +6,13 @@ from git_cli.git_repo import branch_titles, git, top
|
||||
from review_rules.round_titles import cap, round_counts
|
||||
from failure import Failure
|
||||
from chunk_preflight.choices import forge_of
|
||||
from record_store.stores import goals_store, local_file, store
|
||||
from larv_review.history_commands import history_file, places_report
|
||||
from project_config.main import located
|
||||
from project_config.main import located, title_templates
|
||||
from review_rules.review_folder import made_review_folder
|
||||
from deploy_release.forge import open_pull, runner
|
||||
from larv_review.plan_listing import plan_listing
|
||||
from plan_store.stores import store as plan_store
|
||||
from review_rules.reviewer_context import principles_line, starts_bare
|
||||
from review_rules.review_passes import REVIEWERS
|
||||
|
||||
@@ -31,11 +34,16 @@ class Launch:
|
||||
folder: pathlib.Path
|
||||
diff: pathlib.Path
|
||||
principles: pathlib.Path
|
||||
standards: pathlib.Path
|
||||
goals: pathlib.Path
|
||||
# The plan's listing, for a reviewer that reads files, whatever store holds the plan.
|
||||
plan: pathlib.Path
|
||||
bare: bool
|
||||
# The project's `AGENTS.md` and its decision log, where its config puts them.
|
||||
# The project's `AGENTS.md`, where its config puts it, and a local file of its decision log.
|
||||
rules: pathlib.Path
|
||||
decisions: pathlib.Path
|
||||
# The language the project's config names for its prose.
|
||||
language: str
|
||||
|
||||
def asked(self) -> pathlib.Path:
|
||||
"""The round's report, which asks for the rerun where there is one."""
|
||||
@@ -52,7 +60,10 @@ class Launch:
|
||||
f"Report: write it to {report}.",
|
||||
f"Diff: {self.diff}",
|
||||
f"Technical principles: {self.principles}",
|
||||
f"Review standards: {self.standards}",
|
||||
f"Goals and audience: {self.goals}",
|
||||
f"Plan: {self.plan}",
|
||||
f"Prose language: {self.language}.",
|
||||
*([f"Places: {self.folder / 'places.md'}"] if self.pass_ in TAKE_PLACES else []),
|
||||
*([principles] if self.bare and (principles := principles_line(self.rules, self.decisions)) else []),
|
||||
])
|
||||
@@ -67,11 +78,14 @@ def unanswered_round(titles: list[str], pass_: str) -> int | Failure:
|
||||
|
||||
|
||||
def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -> str | Failure:
|
||||
"""Writes the branch diff and the places into the review folder, and returns the header that launches pass_'s reviewer in the pass's unanswered round, or its relaunch one rung up where rerun."""
|
||||
"""Writes the branch diff, the places and the plan's listing into the review folder, and returns the header that launches pass_'s reviewer in the pass's unanswered round, or its relaunch one rung up where rerun."""
|
||||
titles = branch_titles(default)
|
||||
if isinstance(titles, Failure):
|
||||
return titles
|
||||
round_ = unanswered_round(titles, pass_)
|
||||
templates = title_templates(None, home)
|
||||
if isinstance(templates, Failure):
|
||||
return templates
|
||||
round_ = unanswered_round([templates.summary(title) for title in titles], pass_)
|
||||
if isinstance(round_, Failure):
|
||||
return round_
|
||||
found = [top(), *(git(*args) for args in (["symbolic-ref", "--short", "HEAD"], ["rev-parse", "--short", "HEAD"], ["merge-base", "HEAD", default]))]
|
||||
@@ -85,21 +99,29 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
principles = config.paths["principles"]
|
||||
# A typo in the config would otherwise hand every reviewer an empty folder, and the review would run with no principles.
|
||||
if not principles.is_dir() or not any(principles.iterdir()):
|
||||
return Failure(f"{principles} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `principles`")
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, config.paths["goals-and-audience"], starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], config.paths["decisions"])
|
||||
principles, standards = config.paths["principles"], config.paths["standards"]
|
||||
# A typo in the config would otherwise hand every reviewer an empty folder, and the review would run with no principles or standards.
|
||||
empty = next((setting for setting in ("principles", "standards") if not config.paths[setting].is_dir() or not any(config.paths[setting].iterdir())), None)
|
||||
if empty is not None:
|
||||
return Failure(f"{config.paths[empty]} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `{empty}`")
|
||||
decisions = local_file(store(config, "decisions"), folder / "decisions.md")
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
# A reviewer reads files, so goals kept in a Jira epic's description are copied into the review folder.
|
||||
goals = local_file(goals_store(config), folder / "goals.md")
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, standards, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
if rerun and not launch.asked().exists():
|
||||
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
|
||||
written = write_inputs(launch, base, home)
|
||||
written = write_inputs(launch, base, home, plan_listing(plan_store(config)))
|
||||
if isinstance(written, Failure):
|
||||
return written
|
||||
return launch.header()
|
||||
|
||||
|
||||
def write_inputs(launch: Launch, base: str, home: pathlib.Path) -> Failure | None:
|
||||
"""Writes the branch diff from base to HEAD and what `larv-review places` prints into the review folder."""
|
||||
def write_inputs(launch: Launch, base: str, home: pathlib.Path, listing: str) -> Failure | None:
|
||||
"""Writes the branch diff from base to HEAD, what `larv-review places` prints, and the plan's listing into the review folder."""
|
||||
diff = git("diff", base, "HEAD", errors="replace")
|
||||
if isinstance(diff, Failure):
|
||||
return diff
|
||||
@@ -107,7 +129,7 @@ def write_inputs(launch: Launch, base: str, home: pathlib.Path) -> Failure | Non
|
||||
if isinstance(history, Failure):
|
||||
return history
|
||||
try:
|
||||
for path, text in ((launch.diff, diff), (launch.folder / "places.md", places_report(history[1]) + "\n")):
|
||||
for path, text in ((launch.diff, diff), (launch.folder / "places.md", places_report(history[1]) + "\n"), (launch.plan, listing)):
|
||||
# review-replay copies a file into a round's replay by its mtime, so rewriting one unchanged would drop it from every earlier round.
|
||||
if not path.exists() or path.read_text(encoding="utf-8") != text:
|
||||
path.write_text(text, encoding="utf-8")
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import decimal
|
||||
|
||||
from review_rules.comprehension_history import DIMENSIONS, FLOOR
|
||||
from review_rules.comprehension_history import DIMENSIONS
|
||||
from release_plan.todo_table import Item
|
||||
|
||||
# A floor item's tagline opens with this phrase, which a tagline quoting or mentioning the floor never does; a floor item's chunk runs a scoring run.
|
||||
@@ -21,16 +21,17 @@ def mean(values: list[decimal.Decimal]) -> decimal.Decimal:
|
||||
return (sum(values, decimal.Decimal(0)) / len(values)).quantize(decimal.Decimal("0.01"), decimal.ROUND_HALF_UP)
|
||||
|
||||
|
||||
def under_floor(found: list[decimal.Decimal]) -> list[str]:
|
||||
return [f"{name} {value}" for name, value in zip(DIMENSIONS, found) if value < FLOOR]
|
||||
def under_floor(found: list[decimal.Decimal], floor: decimal.Decimal) -> list[str]:
|
||||
"""Each mean in found under floor, the project's readability floor, with its dimension's name."""
|
||||
return [f"{name} {value}" for name, value in zip(DIMENSIONS, found) if value < floor]
|
||||
|
||||
|
||||
def floor_step(found: list[decimal.Decimal], plan: list[Item], ships: list[int]) -> str | None:
|
||||
def floor_step(found: list[decimal.Decimal], plan: list[Item], ships: list[int], floor: decimal.Decimal) -> str | None:
|
||||
"""The `Next:` line of a scoring run with a mean under the floor, None when no mean is under it (SKILL.md → "Floor item").
|
||||
|
||||
The line aims at the lowest of the four dimensions, or at each where they tie, since the lowest caps the overall. A floor item in plan is open unless ships holds its ID, so a chunk that ships one still files the next.
|
||||
"""
|
||||
if not under_floor(found):
|
||||
if not under_floor(found, floor):
|
||||
return None
|
||||
dimensions = dict(zip(DIMENSIONS[:-1], found))
|
||||
lowest = [name for name, value in dimensions.items() if value == min(dimensions.values())]
|
||||
@@ -39,4 +40,4 @@ def floor_step(found: list[decimal.Decimal], plan: list[Item], ships: list[int])
|
||||
rule = 'as larv-review §3 → "Floor item" says.'
|
||||
if open_items := [item for item in plan if is_floor_item(item) and item.id not in ships]:
|
||||
return f"Next: refresh floor item {open_items[0].id} to lift {aim}, with this run's places, and file no other, {rule}"
|
||||
return f"Next: file one floor item, a refactor lifting {aim}, with a tagline that opens with `{FLOOR_ITEM}`, until every mean reaches {FLOOR}, {rule}"
|
||||
return f"Next: file one floor item, a refactor lifting {aim}, with a tagline that opens with `{FLOOR_ITEM}`, until every mean reaches {floor}, {rule}"
|
||||
|
||||
@@ -11,6 +11,7 @@ from git_cli.git_repo import git
|
||||
from project_config.main import located
|
||||
from review_rules.review_folder import made_review_folder, review_folder
|
||||
from project_config.settings import ProjectConfig
|
||||
from record_store.stores import store
|
||||
|
||||
CLAUDE_MD = "CLAUDE.md"
|
||||
PANEL = pathlib.Path(__file__).resolve().parents[2] / "skills" / "comprehension-panel"
|
||||
@@ -79,8 +80,8 @@ def project_values(text: str, source: str) -> dict[str, str] | Failure:
|
||||
|
||||
|
||||
def forbidden(config: ProjectConfig) -> tuple[list[str], str]:
|
||||
"""The files no seat may open, as git names them, and the words that tell a seat so. A file the project's config puts outside the checkout is in neither: the scoring worktree doesn't hold it."""
|
||||
held = [(path, what) for setting, what in FORBIDDEN if (path := config.tracked(setting))]
|
||||
"""The files no seat may open, as git names them, and the words that tell a seat so. The plan or a record that no commit holds is in neither: the scoring worktree doesn't hold it."""
|
||||
held = [(path, what) for setting, what in FORBIDDEN if (path := config.tracked(setting) if setting == "plan" else store(config, setting).tracked)]
|
||||
files = [path for path, _ in held]
|
||||
return files, f"{listed(files, 'or')} ({listed([what for _, what in held], 'and')})" if held else "any record of a past panel"
|
||||
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import contextlib
|
||||
import decimal
|
||||
import itertools
|
||||
import json
|
||||
@@ -16,14 +17,19 @@ from larv_review.agreement import agreement_report, ruling_agreement, run_agreem
|
||||
from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
|
||||
from larv_review.plan import checkout_plan, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due
|
||||
from review_rules import comprehension_history
|
||||
from project_config.test_project_config import configured
|
||||
from larv_review.ruling import counted, ruling, split, surplus, votes
|
||||
from larv_review.history_commands import decided
|
||||
from larv_review.history_commands import decided, rerank
|
||||
from project_config.settings import DEFAULT_FLOOR
|
||||
from failure import Failure
|
||||
from plan_store.stores import FilePlan
|
||||
from record_store.stores import FileStore
|
||||
from larv_review.scoring import floor_step, means, under_floor
|
||||
from test_env import isolated_env
|
||||
from release_plan.todo_table import Item, items, NoItemsTable
|
||||
from release_plan.release_standing import LastCut
|
||||
from larv_review.ruling_base import measured_commit
|
||||
from record_store.fakes import MemoryStore
|
||||
from larv_review.seats import score_line, scores, seats_file, SeatsFile
|
||||
from larv_review.owed import shortfall
|
||||
|
||||
@@ -114,48 +120,57 @@ class Seats(unittest.TestCase):
|
||||
def test_rounds_each_mean_half_up_and_names_each_under_the_floor(self):
|
||||
found = means([["7.5", "6.5", "7", "7", "7"], ["7.5", "7", "7", "6.5", "7"], ["7", "6.5", "7", "6.5", "6.5"], ["7.5", "6.5", "7", "6.5", "7"]])
|
||||
self.assertEqual([str(mean) for mean in found], ["7.38", "6.63", "7.00", "6.63", "6.88"])
|
||||
self.assertEqual(under_floor(found), ["Locality 6.63", "Self-sufficiency 6.63", "Overall 6.88"])
|
||||
self.assertEqual(under_floor([decimal.Decimal("7.00")] * 5), [])
|
||||
self.assertEqual(under_floor(found, DEFAULT_FLOOR), ["Locality 6.63", "Self-sufficiency 6.63", "Overall 6.88"])
|
||||
self.assertEqual(under_floor([decimal.Decimal("7.00")] * 5, DEFAULT_FLOOR), [])
|
||||
|
||||
def test_names_only_the_means_under_the_floor_it_is_given_and_aims_the_next_item_at_it(self):
|
||||
found = [decimal.Decimal(mean) for mean in ("6.50", "5.75", "6.00", "5.50", "5.94")]
|
||||
self.assertEqual(under_floor(found, decimal.Decimal("6")), ["Locality 5.75", "Self-sufficiency 5.50", "Overall 5.94"])
|
||||
self.assertEqual(under_floor(found, decimal.Decimal("5.5")), [])
|
||||
self.assertIsNone(floor_step(found, [], [], decimal.Decimal("5.5")))
|
||||
self.assertIn("until every mean reaches 6, ", floor_step(found, [], [], decimal.Decimal("6")))
|
||||
|
||||
def test_floor_step_files_one_item_at_the_lowest_dimension_unless_one_is_open(self):
|
||||
found = [decimal.Decimal(mean) for mean in ("7.38", "6.63", "7.00", "6.50", "6.88")]
|
||||
floor_item = item(5, (0, 2, 0), "**Reach the comprehension floor: restructure the reload, lifting Locality.**")
|
||||
with self.subTest("none open"):
|
||||
step = floor_step(found, [item(1, (0, 1, 0))], [])
|
||||
step = floor_step(found, [item(1, (0, 1, 0))], [], DEFAULT_FLOOR)
|
||||
self.assertTrue(step.startswith("Next: file one floor item"), step)
|
||||
self.assertIn("with a tagline that opens with `Reach the comprehension floor:`,", step)
|
||||
self.assertIn(" Self-sufficiency, the lowest dimension,", step)
|
||||
self.assertIn('"Floor item"', step)
|
||||
with self.subTest("one open"):
|
||||
step = floor_step(found, [item(1, (0, 1, 0)), floor_item], [])
|
||||
step = floor_step(found, [item(1, (0, 1, 0)), floor_item], [], DEFAULT_FLOOR)
|
||||
self.assertTrue(step.startswith("Next: refresh floor item 5 "), step)
|
||||
self.assertIn(" Self-sufficiency, the lowest dimension,", step)
|
||||
self.assertIn("file no other", step)
|
||||
with self.subTest("the shipped one is not open"):
|
||||
self.assertTrue(floor_step(found, [floor_item], [5]).startswith("Next: file one floor item"))
|
||||
self.assertTrue(floor_step(found, [floor_item], [5], DEFAULT_FLOOR).startswith("Next: file one floor item"))
|
||||
with self.subTest("a tie names both"):
|
||||
tied = [decimal.Decimal(mean) for mean in ("7.38", "6.50", "7.00", "6.50", "6.88")]
|
||||
self.assertIn(" Locality and Self-sufficiency, the lowest dimensions,", floor_step(tied, [], []))
|
||||
self.assertIn(" Locality and Self-sufficiency, the lowest dimensions,", floor_step(tied, [], [], DEFAULT_FLOOR))
|
||||
with self.subTest("a tagline that only mentions the floor is no floor item"):
|
||||
quoting = item(6, (0, 2, 0), "**Rename the decision `comprehension floor: …` in the log.**")
|
||||
self.assertTrue(floor_step(found, [quoting], []).startswith("Next: file one floor item"))
|
||||
self.assertTrue(floor_step(found, [quoting], [], DEFAULT_FLOOR).startswith("Next: file one floor item"))
|
||||
with self.subTest("none under the floor"):
|
||||
self.assertIsNone(floor_step([decimal.Decimal("7.00")] * 5, [floor_item], []))
|
||||
self.assertIsNone(floor_step([decimal.Decimal("7.00")] * 5, [floor_item], [], DEFAULT_FLOOR))
|
||||
with self.subTest("only the overall under the floor"):
|
||||
step = floor_step([decimal.Decimal("7.00")] * 4 + [decimal.Decimal("6.75")], [], [])
|
||||
step = floor_step([decimal.Decimal("7.00")] * 4 + [decimal.Decimal("6.75")], [], [], DEFAULT_FLOOR)
|
||||
self.assertIn(" Navigation, Locality, Shape and Self-sufficiency, the lowest dimensions,", step)
|
||||
self.assertIn("until every mean reaches 7.0", step)
|
||||
|
||||
def test_checkout_plan_fails_on_a_missing_or_tableless_todo(self):
|
||||
with tempfile.TemporaryDirectory() as checkout:
|
||||
path = pathlib.Path(checkout, "todo.md")
|
||||
plan = FilePlan(path, "todo.md", FileStore(pathlib.Path(checkout, "README.md"), None), MemoryStore(), MemoryStore(), DEFAULT_FLOOR)
|
||||
with self.subTest("missing"):
|
||||
self.assertIsInstance(checkout_plan(pathlib.Path(checkout, "todo.md")), Failure)
|
||||
self.assertEqual(checkout_plan(plan).reason, f"the project's plan: {path}: not found; every project keeps a todo.md, and rank_todo.py --help shows one")
|
||||
with self.subTest("no items table"):
|
||||
pathlib.Path(checkout, "todo.md").write_text("# todo\n", encoding="utf-8")
|
||||
self.assertIn("no items table", checkout_plan(pathlib.Path(checkout, "todo.md")).reason)
|
||||
path.write_text("# todo\n", encoding="utf-8")
|
||||
self.assertIn("no items table", checkout_plan(plan).reason)
|
||||
with self.subTest("a malformed row"):
|
||||
pathlib.Path(checkout, "todo.md").write_text(todo("| x | 0.1.0 |"), encoding="utf-8")
|
||||
self.assertIn("the project's todo.md:", checkout_plan(pathlib.Path(checkout, "todo.md")).reason)
|
||||
path.write_text(todo("| x | 0.1.0 |"), encoding="utf-8")
|
||||
self.assertIn("the project's plan:", checkout_plan(plan).reason)
|
||||
|
||||
|
||||
class History(unittest.TestCase):
|
||||
@@ -167,6 +182,14 @@ class History(unittest.TestCase):
|
||||
votes = {"Mid A": ["better", "worse", "same", "same", "better"]}
|
||||
self.assertEqual(ruling_entry("2026-10-09T09:47:25Z, PR #232 at 324d650, against 12d6d75", [seat], votes, votes, "same"), "\n".join(sample) + "\n")
|
||||
|
||||
def test_reads_tables_whose_separators_hold_spaces_as_adf_codec_writes_them(self):
|
||||
scoring = ScoringRun([Seat("Junior A", "", [])], {"Junior A": ["7", "6.5", "7", "7", "7"]}, [decimal.Decimal(mean) for mean in ("7.00", "6.50", "7.00", "7.00", "7.00")])
|
||||
history = appended("", scoring_entry("2026-10-08T12:00:00Z, PR #1 at aaaaaaa", scoring))
|
||||
spaced = "\n".join("| " + " | ".join(["---"] * line.count("---")) + " |" if line.startswith("|-") else line for line in history.splitlines())
|
||||
self.assertNotEqual(spaced, history)
|
||||
self.assertEqual(entries(spaced)[0].score_rows, entries(history)[0].score_rows)
|
||||
self.assertIn("Mean", entries(spaced)[0].score_rows)
|
||||
|
||||
def test_reads_back_what_it_writes(self):
|
||||
seats = [Seat("Mid A", said("better", "worse"), ["`bin/a.py:3` `f`: hard, with `:9` `g`"]), Seat("Inherited architect", said("worse", "worse"), [])]
|
||||
written = {"Mid A": ["same", "worse", "same", "same", "better"], "Inherited architect": ["same", "worse", "same", "same", "worse"]}
|
||||
@@ -322,7 +345,7 @@ class Agreement(unittest.TestCase):
|
||||
|
||||
class Decided(unittest.TestCase):
|
||||
AT = 1_700_000_000.0
|
||||
HISTORY = (pathlib.Path("history.md"), "")
|
||||
HISTORY = (MemoryStore(label="history.md"), "")
|
||||
|
||||
def test_heads_the_entry_with_the_time_it_is_given(self):
|
||||
decided_on = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, self.HISTORY)
|
||||
@@ -336,7 +359,7 @@ class Decided(unittest.TestCase):
|
||||
|
||||
def test_fails_where_the_history_already_holds_an_entry_on_the_file(self):
|
||||
held = scored("2023-11-14T22:13:20Z", "PR #2", "abcdef1", "7", "7")
|
||||
failed = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, (pathlib.Path("history.md"), appended("", held)))
|
||||
failed = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, (MemoryStore(label="history.md"), appended("", held)))
|
||||
self.assertEqual(failed, Failure("history.md already holds an entry on PR #2 at abcdef1; record each ruling or run once"))
|
||||
|
||||
def test_fails_on_a_seats_file_that_does_not_parse_without_asking_about_a_commit(self):
|
||||
@@ -460,6 +483,7 @@ reading-cost = "checkout:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "checkout:README.md"
|
||||
principles = "~/principles"
|
||||
standards = "~/standards"
|
||||
"""
|
||||
|
||||
|
||||
@@ -482,6 +506,8 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.config.write_text(PROJECT_CONFIG)
|
||||
(root / "principles").mkdir()
|
||||
(root / "principles" / "technical-principles.md").write_text("# Principles\n")
|
||||
(root / "standards").mkdir()
|
||||
(root / "standards" / "quality.md").write_text("# Quality\n")
|
||||
|
||||
def git(self, *args):
|
||||
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], cwd=self.checkout, check=True, env=self.env, capture_output=True, text=True).stdout
|
||||
@@ -583,11 +609,11 @@ class LarvReviewTool(unittest.TestCase):
|
||||
(self.config.parent / "decisions.md").unlink()
|
||||
gone = plan_reasons("origin/main", [1, 7], pathlib.Path.home())
|
||||
assert isinstance(gone, Failure), gone
|
||||
self.assertEqual(gone.reason, f"todo.md as it stands holds no item 7, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {self.config.parent}/todo.md")
|
||||
self.assertEqual(gone.reason, f"the plan as it stands holds no item 7, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {self.config.parent}/todo.md")
|
||||
(self.config.parent / "todo.md").write_bytes(b"\xff")
|
||||
unreadable = plan_reasons("origin/main", [2], pathlib.Path.home())
|
||||
assert isinstance(unreadable, Failure), unreadable
|
||||
self.assertTrue(unreadable.reason.startswith(f"cannot read {self.config.parent}/todo.md: "), unreadable.reason)
|
||||
self.assertEqual(unreadable.reason, f"the project's plan: {self.config.parent}/todo.md: not UTF-8")
|
||||
|
||||
ROW = "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"
|
||||
|
||||
@@ -762,7 +788,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
(self.checkout / "todo.md").write_text("# todo\n")
|
||||
ran = self.run_tool("needs-scoring-run", "2")
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn("the project's todo.md has no items table", ran.stderr)
|
||||
self.assertIn("the project's plan: ", ran.stderr)
|
||||
|
||||
def test_records_a_ruling_once_four_seats_settle_a_split(self):
|
||||
lines = """\
|
||||
@@ -810,6 +836,31 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertIn("already holds an entry on", again.stderr)
|
||||
self.assertEqual([entry.ruling for entry in entries((self.checkout / "docs" / "comprehension-history.md").read_text())], ["better"])
|
||||
|
||||
def test_leaves_a_history_it_cannot_read_as_it_is(self):
|
||||
history = self.checkout / "docs" / "comprehension-history.md"
|
||||
history.parent.mkdir(exist_ok=True)
|
||||
history.write_bytes(b"# Comprehension history\n\xff\n")
|
||||
votes_file = self.seats_file(f"PR #2 at {self.start}, against {self.start}\n\nMid A: {said('better')}\n\nInherited architect: {said('better')}\n", "votes.md")
|
||||
ran = self.run_tool("record-ruling", votes_file)
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"cannot read {history}: not UTF-8 on line 2", ran.stderr)
|
||||
self.assertEqual(history.read_bytes(), b"# Comprehension history\n\xff\n")
|
||||
|
||||
def test_holds_a_scoring_run_to_the_readability_floor_the_config_sets(self):
|
||||
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 6.5, Overall 7"
|
||||
seats = "".join(f"\n{seat}: {line}\n\n- `bin/a.py:3` `f`: long\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
|
||||
self.plan()
|
||||
self.config.write_text(PROJECT_CONFIG + "readability-floor = 6.5\n")
|
||||
ran = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
|
||||
self.assertEqual(ran.returncode, 0, ran.stderr)
|
||||
self.assertIn("\nMeans: ", ran.stdout)
|
||||
self.assertNotIn("Floor:", ran.stdout)
|
||||
self.config.write_text(PROJECT_CONFIG + "readability-floor = 6.8\n")
|
||||
ran = self.run_tool("record-scoring", self.seats_file(f"PR #3 at {self.start}\n" + seats), "1")
|
||||
self.assertEqual(ran.returncode, 0, ran.stderr)
|
||||
self.assertIn("\nFloor: Locality 6.50, Self-sufficiency 6.50 under the floor of 6.8.\nNext: file one floor item,", ran.stdout)
|
||||
self.assertIn("until every mean reaches 6.8,", ran.stdout)
|
||||
|
||||
def test_records_a_scoring_run_with_its_means(self):
|
||||
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 6.5, Overall 7"
|
||||
seats = "".join(f"\n{seat}: {line}\n\n- `bin/a.py:3` `f`: long\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
|
||||
@@ -857,7 +908,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.addCleanup(docs.chmod, 0o700)
|
||||
for ran in (self.run_tool("record-ruling", votes_file), self.record_sevens()):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""), ran.stderr)
|
||||
self.assertIn("could not write", ran.stderr)
|
||||
self.assertIn("cannot write", ran.stderr)
|
||||
|
||||
def record_sevens(self):
|
||||
"""Run record-scoring for item 1 on a scores file in which every seat scores 7 throughout."""
|
||||
@@ -915,7 +966,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
# This checkout has no README.md beside its todo.md.
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: not found", ran.stderr)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: missing or empty", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
@@ -927,6 +978,18 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
def test_a_plan_in_jira_is_not_reranked(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
checkout = pathlib.Path(temp, "acme")
|
||||
checkout.mkdir()
|
||||
config = configured(self, checkout) / "config.toml"
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"jira:https://acme.atlassian.net/browse/ABC-12"') + 'env-file = "~/acme.env"\n')
|
||||
(checkout / "todo.md").write_text("the owners' own notes\n")
|
||||
self.enterContext(contextlib.chdir(checkout))
|
||||
said: list[str] = []
|
||||
self.assertIsNone(rerank(pathlib.Path.home(), said.append))
|
||||
self.assertEqual((said, (checkout / "todo.md").read_text()), ([], "the owners' own notes\n"))
|
||||
|
||||
def test_reranks_todo_md_by_the_overall_it_records(self):
|
||||
self.plan()
|
||||
ran = self.record_sevens()
|
||||
@@ -1068,11 +1131,20 @@ class LarvReviewTool(unittest.TestCase):
|
||||
f"Report: write it to {folder}/stability-round-1.md.\n"
|
||||
f"Diff: {folder}/branch-{short}.diff\n"
|
||||
f"Technical principles: {self.checkout.parent}/principles\n"
|
||||
f"Review standards: {self.checkout.parent}/standards\n"
|
||||
f"Goals and audience: {self.checkout}/README.md\n"
|
||||
f"Plan: {folder}/plan.md\n"
|
||||
"Prose language: English.\n"
|
||||
f"Places: {folder}/places.md\n"
|
||||
)), ran.stderr)
|
||||
self.assertEqual((folder / f"branch-{short}.diff").read_text(), self.git("diff", base, "HEAD"))
|
||||
self.assertEqual((folder / "places.md").read_text(), self.run_tool("places").stdout)
|
||||
self.assertEqual((folder / "plan.md").read_text(), (
|
||||
f"# Plan, as {self.checkout}/todo.md holds it\n\n"
|
||||
"## Item 1, release 0.1.0\n\n**Do it.**\n\n"
|
||||
"## Item 2, release 0.2.0\n\n**Then this.**\n\n"
|
||||
"## Item 3, release 0.2.0\n\n**And this.**\n"
|
||||
))
|
||||
|
||||
def test_counts_the_round_from_the_branchs_answers_and_names_the_report_that_asked_for_a_rerun(self):
|
||||
self.commit("Answer prose round 1: a")
|
||||
@@ -1098,15 +1170,15 @@ class LarvReviewTool(unittest.TestCase):
|
||||
for given in (["security"], ["Stability"], ["prose", "--again"], []):
|
||||
self.assertEqual(self.run_tool("reviewer-header", *given).returncode, 1, given)
|
||||
|
||||
def test_reviewer_header_leaves_an_unchanged_diff_and_places_untouched_so_an_earlier_rounds_replay_keeps_them(self):
|
||||
def test_reviewer_header_leaves_an_unchanged_diff_places_and_plan_untouched_so_an_earlier_rounds_replay_keeps_them(self):
|
||||
self.commit("Work", {"a.txt": "one\n"})
|
||||
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
|
||||
self.assertEqual(self.run_tool("reviewer-header", "stability").returncode, 0)
|
||||
written = [folder / f"branch-{self.git('rev-parse', '--short', 'HEAD').strip()}.diff", folder / "places.md"]
|
||||
written = [folder / f"branch-{self.git('rev-parse', '--short', 'HEAD').strip()}.diff", folder / "places.md", folder / "plan.md"]
|
||||
for path in written:
|
||||
os.utime(path, (0, 0))
|
||||
self.assertEqual(self.run_tool("reviewer-header", "prose").returncode, 0)
|
||||
self.assertEqual([path.stat().st_mtime for path in written], [0, 0])
|
||||
self.assertEqual([path.stat().st_mtime for path in written], [0, 0, 0])
|
||||
|
||||
def test_reviewer_header_names_why_it_names_no_pull_request(self):
|
||||
self.git("push", "-q", "-u", "origin", "chunk")
|
||||
@@ -1152,15 +1224,44 @@ class LarvReviewTool(unittest.TestCase):
|
||||
def test_reviewer_header_names_the_principles_folder_the_projects_config_sets(self):
|
||||
self.assertEqual(self.header_line("Technical principles:", "prose"), f"Technical principles: {self.checkout.parent}/principles")
|
||||
|
||||
def test_reviewer_header_names_the_review_standards_folder_the_projects_config_sets(self):
|
||||
self.assertEqual(self.header_line("Review standards:", "prose"), f"Review standards: {self.checkout.parent}/standards")
|
||||
|
||||
def test_reviewer_header_names_the_language_and_counts_rounds_through_the_commit_title_the_projects_config_sets(self):
|
||||
self.config.write_text(PROJECT_CONFIG + 'language = "Swedish"\ncommit-title = "PAY-{id} - {summary}"\n')
|
||||
self.commit("PAY-7 - Answer prose round 1: 0 🔴, 1 🟡 (0 misread); a")
|
||||
self.assertEqual(self.header_line("Prose language:", "prose"), "Prose language: Swedish.")
|
||||
self.assertEqual(self.header_line("Pass:", "prose"), "Pass: prose, round 2.")
|
||||
self.assertIn("prose: 1\n", self.run_tool("round-count").stdout)
|
||||
|
||||
def test_round_count_fails_naming_the_fault_of_a_config_it_cannot_read(self):
|
||||
self.config.write_text(PROJECT_CONFIG + 'commit-title = "PAY-{id}"\n')
|
||||
ran = self.run_tool("round-count")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("`commit-title` is 'PAY-{id}'", ran.stderr)
|
||||
|
||||
def test_reviewer_header_names_the_goals_file_the_projects_config_sets(self):
|
||||
self.config.write_text(PROJECT_CONFIG.replace('"checkout:README.md"', '"folder:goals.md"'))
|
||||
self.assertEqual(self.header_line("Goals and audience:", "principles"), f"Goals and audience: {self.config.parent}/goals.md")
|
||||
|
||||
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_folder(self):
|
||||
self.config.write_text(PROJECT_CONFIG.replace('principles = "~/principles"\n', ""))
|
||||
def test_reviewer_header_fails_naming_the_epic_where_it_cannot_read_goals_kept_in_jira(self):
|
||||
# Port 1 on the loopback refuses the connection, so the read fails without leaving the machine.
|
||||
epic = "jira:https://127.0.0.1:1/browse/ABC-12"
|
||||
credentials = self.config.parents[2] / "acme.env"
|
||||
credentials.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
credentials.chmod(0o600)
|
||||
self.config.write_text(PROJECT_CONFIG.replace('"checkout:todo.md"', f'"{epic}"').replace('"checkout:README.md"', f'"{epic}"') + 'env-file = "~/acme.env"\n')
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("`principles` is missing", ran.stderr)
|
||||
self.assertIn("cannot read the epic ABC-12", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_or_standards_folder(self):
|
||||
for setting in ("principles", "standards"):
|
||||
with self.subTest(setting=setting):
|
||||
self.config.write_text(PROJECT_CONFIG.replace(f'{setting} = "~/{setting}"\n', ""))
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"`{setting}` is missing", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_where_no_config_names_the_checkout(self):
|
||||
self.config.unlink()
|
||||
@@ -1168,15 +1269,19 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"no config names the checkout {self.checkout}", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_where_the_principles_folder_is_missing_or_empty(self):
|
||||
folder = self.checkout.parent / "principles"
|
||||
(folder / "technical-principles.md").unlink()
|
||||
empty = self.run_tool("reviewer-header", "prose")
|
||||
folder.rmdir()
|
||||
missing = self.run_tool("reviewer-header", "prose")
|
||||
for ran in (empty, missing):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `principles`", ran.stderr)
|
||||
def test_reviewer_header_fails_where_the_principles_or_standards_folder_is_missing_or_empty(self):
|
||||
for setting, file in (("principles", "technical-principles.md"), ("standards", "quality.md")):
|
||||
with self.subTest(setting=setting):
|
||||
folder = self.checkout.parent / setting
|
||||
(folder / file).unlink()
|
||||
empty = self.run_tool("reviewer-header", "prose")
|
||||
folder.rmdir()
|
||||
missing = self.run_tool("reviewer-header", "prose")
|
||||
folder.mkdir()
|
||||
(folder / file).write_text("# Restored\n")
|
||||
for ran in (empty, missing):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `{setting}`", ran.stderr)
|
||||
|
||||
def test_reviewer_header_gives_the_architect_the_places(self):
|
||||
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
|
||||
@@ -1190,6 +1295,14 @@ class LarvReviewTool(unittest.TestCase):
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual(ran.stdout.splitlines()[-1], f"Principles: read {self.checkout}/AGENTS.md first, for the project principles and the decision titles.")
|
||||
|
||||
def test_reviewer_header_names_the_decision_log_where_the_project_keeps_no_agents_md(self):
|
||||
(self.checkout / "docs").mkdir(exist_ok=True)
|
||||
(self.checkout / "docs" / "decisions.md").write_text("1. A principle.\n\n# Decisions\n")
|
||||
(self.checkout / "CHANGELOG.md").write_text("# Changelog\n")
|
||||
self.bare("prose-reviewer")
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual(ran.stdout.splitlines()[-1], f"Principles: read {self.checkout}/docs/decisions.md first, up to `# Decisions`, for the project principles and the decision titles.")
|
||||
|
||||
def bare(self, agent):
|
||||
(self.checkout.parent / ".claude" / "agents").mkdir(parents=True, exist_ok=True)
|
||||
(self.checkout.parent / ".claude" / "agents" / f"{agent}.md").write_text("---\nomitClaudeMd: true\n---\n")
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from plan_store.stores import BLOCKED_BY
|
||||
from plan_store.contract import FIRST, SECOND
|
||||
from plan_store.fakes import MemoryPlan
|
||||
from larv_review.plan_listing import plan_listing
|
||||
|
||||
|
||||
class PlanListing(unittest.TestCase):
|
||||
def test_lists_each_item_with_its_release_tagline_blockers_and_detail_in_the_stores_order(self):
|
||||
plan = MemoryPlan(label="the epic ABC-12")
|
||||
plan.add(FIRST, "\nCount them where they are made.\n\nSay why.\n\n")
|
||||
plan.add(SECOND | {BLOCKED_BY: "1, 7"}, "")
|
||||
self.assertEqual(plan_listing(plan), (
|
||||
"# Plan, as the epic ABC-12 holds it\n"
|
||||
"\n"
|
||||
"## Item 1, release 0.1.0\n"
|
||||
"\n"
|
||||
"**Count the runs.**\n"
|
||||
"\n"
|
||||
"Count them where they are made.\n"
|
||||
"\n"
|
||||
"Say why.\n"
|
||||
"\n"
|
||||
"## Item 2, release 0.2.0\n"
|
||||
"\n"
|
||||
"**Ship the later thing.**\n"
|
||||
"\n"
|
||||
"Blocked by: 1, 7.\n"
|
||||
))
|
||||
|
||||
def test_says_so_where_the_plan_holds_no_item(self):
|
||||
self.assertEqual(plan_listing(MemoryPlan(label="the epic ABC-12")), "# Plan, as the epic ABC-12 holds it\n\nThe plan holds no item.\n")
|
||||
|
||||
def test_says_why_where_the_plan_cannot_be_read_so_a_reviewer_does_not_take_it_for_empty(self):
|
||||
self.assertEqual(plan_listing(MemoryPlan(label="the epic ABC-12", fails="Jira answered 401")), "# Plan, as the epic ABC-12 holds it\n\nThe plan cannot be read, so no item is listed: Jira answered 401\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -3,12 +3,11 @@ import datetime
|
||||
from review_rules.comprehension_history import entries
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import git
|
||||
from release_plan.release_standing import held_at
|
||||
from project_config.settings import Place
|
||||
from record_store.stores import held_at, RecordStore
|
||||
|
||||
|
||||
def unmeasured_cut(default: str, history: Place, checkout: str) -> str | None | Failure:
|
||||
"""Whether the default branch's newest release was cut unmeasured, as `v0.7.0, cut with no scoring run since v0.6.0`. It was where no scoring run in the default branch's history, the file at history, is newer than the second-newest v* tag. None where the branch holds fewer than two such tags, or a run since the earlier one.
|
||||
def unmeasured_cut(default: str, history: RecordStore, checkout: str) -> str | None | Failure:
|
||||
"""Whether the default branch's newest release was cut unmeasured, as `v0.7.0, cut with no scoring run since v0.6.0`. It was where no scoring run in the default branch's comprehension history is newer than the second-newest v* tag. None where the branch holds fewer than two such tags, or a run since the earlier one.
|
||||
|
||||
The reason ends once a run follows the earlier tag, so it asks only after a release was cut with none; it lets the chunk that finds the gap record the run.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""loop-claude: headless claude cycles, judged, that interrupt the human only for a decision that is theirs (loop/usage.py's help).
|
||||
|
||||
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. The files it shares with loop-inbox live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
|
||||
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. Its paths live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
|
||||
"""
|
||||
|
||||
@@ -3,8 +3,8 @@ import re
|
||||
|
||||
from claude_code.entries import AssistantTurn, Entry, Text
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import items
|
||||
from loop_claude.quotes import plain
|
||||
from plan_store.stores import Plan
|
||||
from loop_claude.verdicts import TakenIn
|
||||
|
||||
# The label opening the line; prompts.NAME_THE_ITEMS asks the worker for it.
|
||||
@@ -17,12 +17,11 @@ SAID_OF_AN_ITEM = re.compile(r"\([^)]*\)")
|
||||
ITEM_ID = re.compile(r"\s*(?:item\s+)?#?(\d+)", re.IGNORECASE)
|
||||
|
||||
|
||||
def taken_in(entries: list[Entry], todo: str | Failure) -> TakenIn:
|
||||
"""The items named, with the highest L and the highest E + I that todo.md, as read when the cycle started, gives any of them. An item todo.md doesn't hold, or a todo.md that can't be read, adds no level, so the route holds."""
|
||||
def taken_in(entries: list[Entry], plan: Plan | Failure) -> TakenIn:
|
||||
"""The items named, with the highest L and the highest E + I that the plan, as read when the cycle started, gives any of them. An item the plan doesn't hold, or a plan that can't be read, adds no level, so the route holds."""
|
||||
ids = named(entries)
|
||||
found = items(todo) if isinstance(todo, str) else todo
|
||||
scored = [item for item in found if item.id in ids] if isinstance(found, list) else []
|
||||
return TakenIn(ids, max((item.likelihood for item in scored), default=0), max((item.escape_and_impact for item in scored), default=0))
|
||||
scored = [] if isinstance(plan, Failure) else [item for item in plan.items if item.id in ids]
|
||||
return TakenIn(max((item.likelihood for item in scored), default=0), max((item.escape_and_impact for item in scored), default=0))
|
||||
|
||||
|
||||
def named(entries: list[Entry]) -> tuple[int, ...]:
|
||||
|
||||
@@ -1,29 +1,25 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import sys
|
||||
import typing
|
||||
import uuid
|
||||
|
||||
from loop_state.waiting.answers import Answer, answered, claude_ended, ClaudeOpening, Typed
|
||||
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
|
||||
from loop_state.hand_over import claude_args, ClaudeCommand, hand_over
|
||||
from loop_effects.effects import Effects, POLL_SECONDS, say
|
||||
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from claude_code.transcript import human_turns, read_transcript
|
||||
from loop_state.waiting.listing import listed, shown
|
||||
from loop_state.waiting.talk import make_way, TALK
|
||||
from loop_claude.stop import needs_human, needs_terminal, Stop
|
||||
from model_routing.ladder import Rung
|
||||
from loop_claude.direct_message import tell
|
||||
|
||||
ANSWER_QUESTION = "answer the question above"
|
||||
# ASK_ANSWER was picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
|
||||
# TALK, what the human types at loop-claude's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
|
||||
TALK = "/talk"
|
||||
ASK_ANSWER = f"Answer ({TALK} opens claude, Enter stops the loop): "
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class WorkerSession:
|
||||
"""The worker's claude session, which /talk opens on loop-claude's terminal or in loop-inbox."""
|
||||
"""The worker's claude session, which /talk opens on loop-claude's terminal."""
|
||||
root: str
|
||||
id: uuid.UUID
|
||||
rung: Rung
|
||||
@@ -40,8 +36,8 @@ class Talked:
|
||||
"""The human typed in the worker's claude session."""
|
||||
|
||||
|
||||
def interrupt(question: str, answer_here: bool, session: WorkerSession, questions: pathlib.Path, effects: Effects) -> str | Talked | Stop:
|
||||
"""Prints question for the human and returns their answer: where answer_here, the first line typed at loop-claude's terminal or in loop-inbox, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. loop-inbox lists the question meanwhile. A Stop where loop-claude is off a terminal, or they type no answer, or the input ends."""
|
||||
def interrupt(question: str, answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
|
||||
"""Prints question for the human and returns their answer: where answer_here, the first line typed at loop-claude's terminal, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where loop-claude is off a terminal, or they type no answer, or the input ends."""
|
||||
say(f"\n{question}", effects)
|
||||
on_terminal = effects.on_terminal()
|
||||
if on_terminal:
|
||||
@@ -51,51 +47,26 @@ def interrupt(question: str, answer_here: bool, session: WorkerSession, question
|
||||
tell(f"loop-claude in {session.root} asks:\n\n{question}", effects)
|
||||
if stop := needs_terminal(ANSWER_QUESTION, on_terminal):
|
||||
return stop
|
||||
ask = Ask(effects.new_id(), str(session.id), session.root, question, effects.now(), Asking(session.claude_command()) if answer_here else OpenOnTerminal())
|
||||
with listed(questions, ask, effects):
|
||||
answer = first_answer(ask, questions, effects) if answer_here else OpenOnTerminal()
|
||||
if isinstance(answer, OpenOnTerminal | OpenInInbox):
|
||||
return human_typed(session.transcript_path, lambda: claude_open(ask, answer, session, questions, effects)) or Talked()
|
||||
answer = typed_answer(effects) if answer_here else TALK
|
||||
if answer != TALK:
|
||||
return answer
|
||||
return human_typed(session.transcript_path, lambda: claude_open(session, effects)) or Talked()
|
||||
|
||||
|
||||
def first_answer(ask: Ask, questions: pathlib.Path, effects: Effects) -> str | OpenOnTerminal | OpenInInbox | Stop:
|
||||
"""The first answer to ask, from loop-claude's terminal or loop-inbox: the line typed, stripped, or where claude is to open for it. A Stop where they type no answer, or the input ends."""
|
||||
def typed_answer(effects: Effects) -> str | Stop:
|
||||
"""The line typed at loop-claude's terminal, stripped. A Stop where they type no answer, or the input ends."""
|
||||
try:
|
||||
# Annotated since mypy infers input_or's T as object from the lambda.
|
||||
answer: str | Answer = effects.input_or(ASK_ANSWER, lambda: answered(questions, ask))
|
||||
text = effects.input(ASK_ANSWER).strip()
|
||||
except EOFError:
|
||||
print(file=sys.stderr) # Ends the prompt's line. It isn't a message, so it gets no time.
|
||||
return needs_human(ANSWER_QUESTION, "the input ended")
|
||||
match answer:
|
||||
case ClaudeOpening(pid):
|
||||
return OpenInInbox(pid)
|
||||
case Typed(text):
|
||||
say(f"Answered in loop-inbox: {text}", effects)
|
||||
case str(text):
|
||||
pass
|
||||
case _:
|
||||
typing.assert_never(answer)
|
||||
text = text.strip()
|
||||
if not text:
|
||||
return needs_human(ANSWER_QUESTION, "nothing was typed")
|
||||
return OpenOnTerminal() if text == TALK else text
|
||||
return text or needs_human(ANSWER_QUESTION, "nothing was typed")
|
||||
|
||||
|
||||
def claude_open(ask: Ask, where: OpenOnTerminal | OpenInInbox, session: WorkerSession, questions: pathlib.Path, effects: Effects) -> Stop | None:
|
||||
"""Lists ask in loop-inbox as having claude open where, then returns once that claude has ended: the one it opens on the terminal, or the one loop-inbox opened."""
|
||||
match where:
|
||||
case OpenOnTerminal():
|
||||
shown(questions, dataclasses.replace(ask, state=where), effects)
|
||||
if unstarted := hand_over(session.claude_command(), effects):
|
||||
return Stop(1, f"could not start claude for the interrupt: {unstarted.reason}")
|
||||
case OpenInInbox(pid):
|
||||
make_way(questions, ask, pid, effects)
|
||||
say("claude is open for this question in loop-inbox; waiting for it to end", effects)
|
||||
while not claude_ended(questions, ask) and effects.alive(pid):
|
||||
effects.sleep(POLL_SECONDS)
|
||||
case _:
|
||||
typing.assert_never(where)
|
||||
def claude_open(session: WorkerSession, effects: Effects) -> Stop | None:
|
||||
"""Opens the worker's claude session on the terminal, and returns once it has ended."""
|
||||
if unstarted := hand_over(session.claude_command(), effects):
|
||||
return Stop(1, f"could not start claude for the interrupt: {unstarted.reason}")
|
||||
return None
|
||||
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ FINISHED_RULES = (
|
||||
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
|
||||
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}.\n\n"
|
||||
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, ~/.claude/skills/larv-review/standards/) included. "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, the project's review standards, each headed by its path) included. "
|
||||
f"It also counts where the transcript shows the worker writing it into {ANSWER_DESTINATIONS}, "
|
||||
"but not into one of the human's rules.\n\n"
|
||||
"finished=false when work remains that a further run can "
|
||||
|
||||
@@ -17,6 +17,7 @@ from loop_claude.routing import judge_rung, next_route, step_up, StepUp
|
||||
from model_routing.ladder import Ladder, Rung
|
||||
from transcript_archive.read import last_spent
|
||||
from transcript_archive import outcomes
|
||||
from plan_store.stores import Plan
|
||||
from loop_claude.cycle import prompts
|
||||
from claude_code.transcript import read_transcript
|
||||
from loop_claude.cycle.retry import retried
|
||||
@@ -44,17 +45,13 @@ class Cycle:
|
||||
# The project's rung; None for a model off the ladder.
|
||||
project: Rung | None
|
||||
project_archive: pathlib.Path
|
||||
# Where the loop keeps its questions for loop-inbox: running_loops.Listed.folder.
|
||||
questions: pathlib.Path
|
||||
records: str
|
||||
root: str
|
||||
route: Route
|
||||
session: Session
|
||||
# Lists in loop-inbox the items the chunk takes, given the IDs on the worker's latest `Chunk items:` line.
|
||||
show_taken_in: typing.Callable[[tuple[int, ...]], None]
|
||||
task: str
|
||||
# todo.md on the default branch as the cycle starts, which scores the items the worker names.
|
||||
todo: str | Failure
|
||||
todo: Plan | Failure
|
||||
# Empty when the previous cycle's verdict was not Unfinished.
|
||||
unfinished_evidence: str
|
||||
|
||||
@@ -76,8 +73,6 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
|
||||
# Only a ruling's step-up changes the route within a cycle, here, once rule has archived the ruling on the route before it. No transition reads the current route, so Cycle holds it, not the states.
|
||||
if isinstance(event, Ruled) and event.stepped_to:
|
||||
cycle = dataclasses.replace(cycle, route=event.stepped_to)
|
||||
if isinstance(event, Ruled) and not isinstance(event.verdict, Finished):
|
||||
cycle.show_taken_in(event.verdict.taken_in.items)
|
||||
state = transition(state, event)
|
||||
except KeyboardInterrupt:
|
||||
return stopped(cycle, Stop(130, ""), "Ctrl-C")
|
||||
@@ -203,7 +198,7 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
|
||||
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
|
||||
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
|
||||
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
|
||||
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.questions, cycle.effects)
|
||||
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.effects)
|
||||
match answer:
|
||||
case Stop():
|
||||
return answer
|
||||
|
||||
@@ -9,7 +9,7 @@ QUOTED_ANSWERS_PER_CYCLE = 3
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class TypedAnswer:
|
||||
"""The human's answer to an interrupt, typed at loop-claude's terminal or in loop-inbox."""
|
||||
"""The human's answer to an interrupt, typed at loop-claude's terminal."""
|
||||
question: str
|
||||
answer: str
|
||||
|
||||
|
||||
@@ -4,4 +4,4 @@ from loop_effects.effects import Effects, say
|
||||
def tell(text: str, effects: Effects) -> None:
|
||||
"""DMs text to the human. Where the DM fails, it says why on stderr and goes on: the DM only copies what the terminal shows, so its failure never stops the loop."""
|
||||
if failed := effects.dm(text):
|
||||
say(f"could not DM you on Mattermost: {failed.reason}", effects)
|
||||
say(f"could not DM you: {failed.reason}", effects)
|
||||
|
||||
@@ -19,7 +19,7 @@ def claude_args(rung: Rung, args: list[str]) -> list[str]:
|
||||
|
||||
|
||||
# CLAUDE_CODE_SANDBOXED, which Claude Code doesn't document, skips its trust dialog without writing ~/.claude.json:
|
||||
# docs/decisions.md → `loop-claude: every claude it or loop-inbox opens on a terminal has CLAUDE_CODE_SANDBOXED set`.
|
||||
# docs/decisions.md → `loop-claude: every claude it opens on a terminal has CLAUDE_CODE_SANDBOXED set`.
|
||||
def hand_over(command: ClaudeCommand, effects: Effects) -> Failure | None:
|
||||
"""Runs claude on the terminal as command says, with CLAUDE_CODE_SANDBOXED=1 added to its environment; the failure is why claude could not start."""
|
||||
try:
|
||||
@@ -0,0 +1,46 @@
|
||||
"""The slot a loop holds in its project, so that loops of one project, each on its own chunk, run side by side, each in a session named after its slot."""
|
||||
import dataclasses
|
||||
import os
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
from machine_load.slots import first_free_slot
|
||||
from loop_claude.loop.reload import LoopRun
|
||||
from loop_state.paths import Paths
|
||||
from transcript_archive.project_key import project_key
|
||||
from claude_code.session import Session, session_named, session_open
|
||||
|
||||
# Under the home folder, a folder per project key holds a file per slot, which a running loop keeps locked with flock.
|
||||
SLOTS = ".local/state/loop-claude"
|
||||
# A bound no project reaches. Once todo.md item 375 lands, the project's config sets how many loops run at once.
|
||||
MOST = 64
|
||||
|
||||
|
||||
def held_slot(home: pathlib.Path, key: str, claude_code_transcripts: pathlib.Path) -> int | Failure:
|
||||
"""The slot this loop takes, or why it could take none: the lowest free slot whose session is open, so that a rerun resumes a chunk left open, or else the lowest free slot. The loop holds it until it exits; a reload's exec keeps the lock."""
|
||||
folder = home / SLOTS / key
|
||||
order = sorted(range(MOST), key=lambda slot: not session_open(session_named(session_name(key, slot), claude_code_transcripts)))
|
||||
try:
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
taken = first_free_slot(folder, order)
|
||||
except OSError as failure:
|
||||
return Failure(f"cannot take a slot in {folder}: {failure.strerror}")
|
||||
if taken is None:
|
||||
return Failure(f"{MOST} loops of this project are running already; `fuser {folder}/slot-*` names them")
|
||||
slot, fd = taken
|
||||
os.set_inheritable(fd, True)
|
||||
return slot
|
||||
|
||||
|
||||
def session_name(key: str, slot: int) -> str:
|
||||
""""A " is the human's cue in the session picker that the session is the loop's. Slot 0 keeps the name every loop had before slots, so a chunk left open before slots resumes in it."""
|
||||
return f"A {key} loop-claude" if slot == 0 else f"A {key} loop-claude {slot + 1}"
|
||||
|
||||
|
||||
def slotted(loop_run: LoopRun, paths: Paths) -> tuple[LoopRun, Session] | Failure:
|
||||
"""loop_run holding its slot, and the worker's session, named after the slot. A reloaded script keeps the slot it is handed."""
|
||||
key = project_key(loop_run.root, paths.home)
|
||||
slot = held_slot(paths.home, key, paths.claude_code_transcripts) if loop_run.slot is None else loop_run.slot
|
||||
if isinstance(slot, Failure):
|
||||
return slot
|
||||
return dataclasses.replace(loop_run, slot=slot), session_named(session_name(key, slot), paths.claude_code_transcripts)
|
||||
@@ -1,13 +1,14 @@
|
||||
"""How a cycle starts: the route it runs on, from the archive or the plan, the facts chunk-preflight finds for a fresh chunk, and the items loop-inbox lists."""
|
||||
"""How a cycle starts: the route it runs on, from the archive or the plan, and the facts chunk-preflight finds for a fresh chunk."""
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from release_plan.release_standing import default_plan, DefaultPlan, held_at, UNSEEN_RELEASES
|
||||
from git_cli.git_repo import default_ref
|
||||
from release_plan.release_standing import DefaultPlan, project_plan, UNSEEN_RELEASES
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from loop_claude.routing import first_route, kept, routed_item
|
||||
from release_plan.todo_table import Item, items
|
||||
from plan_store.stores import held_at, Plan, store as plan_store
|
||||
from release_plan.todo_table import Item
|
||||
from model_routing.ladder import Ladder, Rung
|
||||
from transcript_archive.read import latest_worker
|
||||
from project_config.main import located
|
||||
@@ -15,27 +16,21 @@ from loop_claude.loop.this_loop import Loop
|
||||
from loop_claude.cycle import prompts
|
||||
from model_routing.route import Route, route_from
|
||||
from claude_code.session import session_open, transcript_file
|
||||
from loop_state.running_loops import taken_items
|
||||
|
||||
# Seconds routing waits for origin to name its default branch, asked only where the checkout records none; past them, the chunk runs on the project's rung.
|
||||
ORIGIN_TIMEOUT = 60
|
||||
|
||||
|
||||
def shown_items(loop: Loop, todo: str | Failure, routed: int) -> typing.Callable[[tuple[int, ...]], None]:
|
||||
"""A function that lists in loop-inbox the items a chunk takes, given the IDs the worker names, with their taglines in todo, as fetched_todo read it as the cycle started. routed is the item the chunk was routed on, 0 for none."""
|
||||
return lambda taken_in: loop.listed.show(taken_items(todo, routed, taken_in))
|
||||
|
||||
|
||||
def fetched_todo(loop: Loop) -> str | Failure:
|
||||
"""The plan, which lists and scores the items a chunk takes: on the default branch as last fetched, or as it stands where the project's config puts it outside the checkout. fetched_plan reads it too, but also the release tag, CHANGELOG.md and each todo.md since the tag, which listing and scoring the items don't need. Where it can't be read or scored, it says why."""
|
||||
def fetched_todo(loop: Loop) -> Plan | Failure:
|
||||
"""The plan, which scores the items a chunk takes: on the default branch as last fetched, or as it stands where the project's config puts it outside the checkout. fetched_plan reads it too, but also the release tag, CHANGELOG.md and each todo.md since the tag, which scoring the items doesn't need. Where it can't be read or scored, it says why."""
|
||||
ref = default_ref(loop.root, ORIGIN_TIMEOUT, run=loop.effects.git)
|
||||
config = located(loop.root, loop.paths.home)
|
||||
if isinstance(config, Failure):
|
||||
todo: str | Failure = config
|
||||
todo: Plan | Failure = config
|
||||
else:
|
||||
todo = ref if isinstance(ref, Failure) else held_at(ref, config.place("plan"), loop.root, loop.effects.git)
|
||||
if isinstance(scored := items(todo) if isinstance(todo, str) else todo, Failure):
|
||||
say(f"the items the worker names lift no rung: {scored.reason}", loop.effects)
|
||||
todo = ref if isinstance(ref, Failure) else held_at(ref, plan_store(config), loop.root, loop.effects.git)
|
||||
if isinstance(todo, Failure):
|
||||
say(f"the items the worker names lift no rung: {todo.reason}", loop.effects)
|
||||
return todo
|
||||
|
||||
|
||||
@@ -85,7 +80,7 @@ def fetched_plan(loop: Loop) -> DefaultPlan | Failure:
|
||||
if config.tracked("plan") is None:
|
||||
say(UNSEEN_RELEASES, loop.effects)
|
||||
ref = default_ref(loop.root, ORIGIN_TIMEOUT, run=loop.effects.git)
|
||||
return ref if isinstance(ref, Failure) else default_plan(loop.root, ref, config.place("plan"), config.place("changelog"), loop.effects.git)
|
||||
return ref if isinstance(ref, Failure) else project_plan(config, ref, loop.root, loop.effects.git)
|
||||
|
||||
|
||||
def plan_item(plan: DefaultPlan | Failure, effects: Effects) -> Item | None:
|
||||
@@ -93,8 +88,6 @@ def plan_item(plan: DefaultPlan | Failure, effects: Effects) -> Item | None:
|
||||
# It prints the reason itself, through effects, like the other loop-claude functions that print. todo.md item 51 moves them all to one injected effect, so changing this one alone would be undone.
|
||||
if isinstance(plan, Failure):
|
||||
item: Item | Failure | None = plan
|
||||
elif isinstance(plan.todo, Failure):
|
||||
item = plan.todo
|
||||
else:
|
||||
item = routed_item(plan.todo, plan.cut)
|
||||
if isinstance(item, Failure):
|
||||
|
||||
@@ -39,9 +39,9 @@ def reached_limit(loop_run: LoopRun) -> Stop | None:
|
||||
|
||||
|
||||
def after_verdict(loop_run: LoopRun, ladder: Ladder, project: Rung | None, concluded: Concluded) -> LoopRun:
|
||||
"""The loop run the next cycle starts from. A finished chunk drops its route, its run of unfinished verdicts and the items it took in. An unfinished one takes the route routing.next_route makes of the route its cycle ended on, which an interrupt's or a quoted answer's escalation may have raised; the evidence the judge gave for the verdict, and the items the worker names on its latest `Chunk items:` line; and counts the verdict."""
|
||||
"""The loop run the next cycle starts from. A finished chunk drops its route and its run of unfinished verdicts. An unfinished one takes the route routing.next_route makes of the route its cycle ended on, which an interrupt's or a quoted answer's escalation may have raised, and the evidence the judge gave for the verdict; and counts the verdict."""
|
||||
verdict = concluded.verdict
|
||||
if isinstance(verdict, Finished):
|
||||
return dataclasses.replace(loop_run, route=None, unfinished_evidence="", unfinished_run=0, items_taken_in=())
|
||||
return dataclasses.replace(loop_run, route=None, unfinished_evidence="", unfinished_run=0)
|
||||
route = next_route(ladder, project, concluded.route, verdict)
|
||||
return dataclasses.replace(loop_run, route=route, unfinished_evidence=verdict.evidence, unfinished_run=loop_run.unfinished_run + 1, items_taken_in=verdict.taken_in.items)
|
||||
return dataclasses.replace(loop_run, route=route, unfinished_evidence=verdict.evidence, unfinished_run=loop_run.unfinished_run + 1)
|
||||
|
||||
@@ -3,7 +3,7 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from transcript_archive.location import archive_root, project_archive
|
||||
from loop_claude.loop.chunk_start import archived_route, chunk_start, fetched_todo, routed, shown_items
|
||||
from loop_claude.loop.chunk_start import archived_route, chunk_start, fetched_todo, routed
|
||||
from loop_claude.loop.routing_check import check_routing
|
||||
from loop_claude.project.checkout import checkout_root
|
||||
from loop_claude.loop.close import closed_cycle
|
||||
@@ -20,8 +20,7 @@ from transcript_archive.project_key import project_key
|
||||
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
|
||||
from loop_claude.project.premises import read_premises
|
||||
from loop_claude.project.records import read_records
|
||||
from claude_code.session import session_named
|
||||
from loop_state.running_loops import shown_running
|
||||
from loop_claude.loop.chunk_slot import slotted
|
||||
from loop_claude.stop import Stop
|
||||
from loop_claude.direct_message import tell
|
||||
|
||||
@@ -36,7 +35,7 @@ def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
|
||||
raise
|
||||
if stop.reason:
|
||||
say(stop.reason, effects, stdout=not stop.code)
|
||||
# Every stop but the human's own Ctrl-C and the help is DMed, so a loop left overnight never ends unseen. A loop given no task prints the help.
|
||||
# Every stop but the human's own Ctrl-C and the help is DMed where the project's config can be read and sets `env-file`, so a loop left overnight never ends unseen. A loop given no task prints the help.
|
||||
if stop.code != 130 and stop.reason != HELP:
|
||||
tell(f"loop-claude in {cwd} stopped: {stop.reason}", effects)
|
||||
return stop.code
|
||||
@@ -47,27 +46,28 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
|
||||
if isinstance(loop_run, Stop):
|
||||
return loop_run
|
||||
baseline = fingerprint(launcher)
|
||||
# "A " is the human's cue in the session picker that the session is the loop's.
|
||||
session = session_named(f"A {project_key(loop_run.root, paths.home)} loop-claude", paths.claude_code_transcripts)
|
||||
with shown_running(paths.waiting, str(session.id), loop_run.root, effects) as listed:
|
||||
loop = Loop(root=loop_run.root, session=session, listed=listed, paths=paths, env=env, launcher=launcher, effects=effects)
|
||||
while True:
|
||||
if stop := exec_if_edited(loop, baseline, loop_run):
|
||||
return stop
|
||||
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
|
||||
cycle = next_cycle(loop_run, loop)
|
||||
if isinstance(cycle, Stop):
|
||||
return cycle
|
||||
concluded = run_cycle(cycle)
|
||||
if isinstance(concluded, Stop):
|
||||
return concluded
|
||||
closed = closed_cycle(loop_run, cycle.ladder, cycle.project, concluded, cycle.project_archive, loop)
|
||||
if isinstance(closed, Stop):
|
||||
return closed
|
||||
loop_run = closed
|
||||
# Off the ladder the worker runs on the project's model itself, which its route names.
|
||||
if stop := check_routing(archive_root(paths.home, env), cycle.project or cycle.route.rung, loop):
|
||||
return stop
|
||||
held = slotted(loop_run, paths)
|
||||
if isinstance(held, Failure):
|
||||
return Stop(1, held.reason)
|
||||
loop_run, session = held
|
||||
loop = Loop(root=loop_run.root, session=session, paths=paths, env=env, launcher=launcher, effects=effects)
|
||||
while True:
|
||||
if stop := exec_if_edited(loop, baseline, loop_run):
|
||||
return stop
|
||||
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
|
||||
cycle = next_cycle(loop_run, loop)
|
||||
if isinstance(cycle, Stop):
|
||||
return cycle
|
||||
concluded = run_cycle(cycle)
|
||||
if isinstance(concluded, Stop):
|
||||
return concluded
|
||||
closed = closed_cycle(loop_run, cycle.ladder, cycle.project, concluded, cycle.project_archive, loop)
|
||||
if isinstance(closed, Stop):
|
||||
return closed
|
||||
loop_run = closed
|
||||
# Off the ladder the worker runs on the project's model itself, which its route names.
|
||||
if stop := check_routing(archive_root(paths.home, env), cycle.project or cycle.route.rung, loop):
|
||||
return stop
|
||||
|
||||
|
||||
def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
|
||||
@@ -96,9 +96,7 @@ def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
|
||||
if ladder_file != SHIPPED:
|
||||
say(own_ladder(ladder_file, models.worker, project is None), loop.effects)
|
||||
todo = fetched_todo(loop)
|
||||
show_taken_in = shown_items(loop, todo, route.item)
|
||||
show_taken_in(loop_run.items_taken_in)
|
||||
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge_model=models.judge, ladder=ladder, premises=premises, project=project, project_archive=archive_folder, questions=loop.listed.folder, records=records, root=loop.root, route=route, session=loop.session, show_taken_in=show_taken_in, task=loop_run.task, todo=todo, unfinished_evidence=loop_run.unfinished_evidence)
|
||||
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge_model=models.judge, ladder=ladder, premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, todo=todo, unfinished_evidence=loop_run.unfinished_evidence)
|
||||
|
||||
|
||||
def own_ladder(file: pathlib.Path, model: str, unrouted: bool) -> str:
|
||||
|
||||
@@ -25,8 +25,8 @@ class LoopRun:
|
||||
route: Route | None = None
|
||||
# How many unfinished verdicts the chunk has had running; a finished chunk and a rerun each set it to 0. It stays apart from route and unfinished_evidence, though all three change together at each verdict: merging or renaming a field stops a running loop at its next reload.
|
||||
unfinished_run: int = 0
|
||||
# The IDs of the items the last unfinished verdict found the chunk takes, which loop-inbox lists until the next ruling.
|
||||
items_taken_in: tuple[int, ...] = ()
|
||||
# The project's slot this loop holds (chunk_slot.py); None until it takes one. A loop started before slots reloads with None, and so takes a slot then.
|
||||
slot: int | None = None
|
||||
|
||||
|
||||
class Unreadable(Exception):
|
||||
@@ -39,6 +39,9 @@ def decode_handed(handed: str) -> LoopRun | None:
|
||||
fields = json.loads(handed)
|
||||
except ValueError:
|
||||
return None
|
||||
# A loop started before 0.11.0 hands the items loop-inbox listed; dropping them keeps it running across its reload.
|
||||
if isinstance(fields, dict):
|
||||
fields.pop("items_taken_in", None)
|
||||
try:
|
||||
return LoopRun(**decoded_fields(fields, LOOP_RUN_FIELDS, "cycle_number", "root", "task", "unfinished_evidence"))
|
||||
except Unreadable:
|
||||
@@ -61,12 +64,6 @@ def exactly(kind: type) -> typing.Callable[[typing.Any], typing.Any]:
|
||||
return decode
|
||||
|
||||
|
||||
def decoded_ids(value: object) -> tuple[int, ...]:
|
||||
if not isinstance(value, list):
|
||||
raise Unreadable
|
||||
return tuple(exactly(int)(each) for each in value)
|
||||
|
||||
|
||||
def decoded_route(value: object) -> Route | None:
|
||||
"""The Route the JSON holds; None for null. dataclasses.asdict wrote it as a worker line's fields, with the rung nested and the unfinished count added. route_of reads it once the rung's model and effort are lifted to the top and the count is set aside."""
|
||||
if value is None:
|
||||
@@ -80,7 +77,7 @@ def decoded_route(value: object) -> Route | None:
|
||||
|
||||
|
||||
# One decoder per field of LoopRun, which a test holds to the dataclass's fields: a field missing here stops a loop at the reload after it joined.
|
||||
LOOP_RUN_FIELDS = {"cycle_number": exactly(int), "root": exactly(str), "task": exactly(str), "unfinished_evidence": exactly(str), "route": decoded_route, "unfinished_run": exactly(int), "items_taken_in": decoded_ids}
|
||||
LOOP_RUN_FIELDS = {"cycle_number": exactly(int), "root": exactly(str), "task": exactly(str), "unfinished_evidence": exactly(str), "route": decoded_route, "unfinished_run": exactly(int), "slot": lambda value: None if value is None else exactly(int)(value)}
|
||||
|
||||
|
||||
def fingerprint(launcher: pathlib.Path) -> str:
|
||||
|
||||
@@ -2,12 +2,10 @@
|
||||
import pathlib
|
||||
|
||||
from routing_figures import archive
|
||||
from loop_state.waiting.ask import Ask, OpenOnTerminal
|
||||
from routing_figures.calls import Call, calls, totals
|
||||
from loop_state.hand_over import claude_args, ClaudeCommand, hand_over
|
||||
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from loop_state.waiting.listing import listed
|
||||
from loop_claude.loop.this_loop import Loop
|
||||
from loop_state.paths import Paths
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
@@ -56,7 +54,7 @@ def new_calls(root: pathlib.Path, paths: Paths, effects: Effects) -> list[Call]
|
||||
|
||||
|
||||
def raise_calls(root: pathlib.Path, new: list[Call], rung: Rung, loop: Loop) -> Stop | None:
|
||||
"""Puts the calls to the human through a claude in this setup's development clone, where the routing decision is changed; loop-inbox lists them under the loop's checkout while that claude is open. Off a terminal they are only said, and stay in the figures, raised at the next measurement on a terminal."""
|
||||
"""Puts the calls to the human through a claude in this setup's development clone, where the routing decision is changed. Off a terminal they are only said, and stay in the figures, raised at the next measurement on a terminal."""
|
||||
bullets = "".join(f"- {call.sentence()}\n" for call in new)
|
||||
question = f"loop-claude's routing figures call for a routing change:\n{bullets}The figures: {root / archive.FIGURES}"
|
||||
say(f"\n{question}", loop.effects)
|
||||
@@ -65,9 +63,7 @@ def raise_calls(root: pathlib.Path, new: list[Call], rung: Rung, loop: Loop) ->
|
||||
say("Not on a terminal: the calls are raised again at the next measurement.", loop.effects)
|
||||
return None
|
||||
prompt = f"Put these calls for a routing change from loop-claude's figures to the human, and don't change anything until they answer:\n{bullets}The figures are in {root / archive.FIGURES}. The ladder, its steps and the delegation rule are docs/decisions.md → `routing:`, and a change to them is the human's. Record what they decide in this checkout, the development clone, as ~/.claude/CLAUDE.md says; the next chunk of this repo files the plan item for these calls."
|
||||
ask = Ask(loop.effects.new_id(), str(loop.session.id), loop.root, question, loop.effects.now(), OpenOnTerminal())
|
||||
with listed(loop.listed.folder, ask, loop.effects):
|
||||
unstarted = hand_over(ClaudeCommand(claude_args(rung, [prompt]), str(loop.paths.config_clone), {}), loop.effects)
|
||||
unstarted = hand_over(ClaudeCommand(claude_args(rung, [prompt]), str(loop.paths.config_clone), {}), loop.effects)
|
||||
if unstarted:
|
||||
return Stop(1, f"could not start claude for the routing calls in {loop.paths.config_clone}, the setup's development clone: {unstarted.reason}")
|
||||
# Raised once the human has seen them, answered or not: an unanswered call reaches the plan through docs/decisions.md → "Working rules", so it is not asked twice.
|
||||
|
||||
@@ -3,7 +3,6 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from loop_effects.effects import Effects
|
||||
from loop_state.running_loops import Listed
|
||||
from loop_state.paths import Paths
|
||||
from claude_code.session import Session
|
||||
|
||||
@@ -13,9 +12,8 @@ class Loop:
|
||||
"""What stays the same through one run of loop-claude; run_loop builds it once per process, so a reload builds it afresh."""
|
||||
# The checkout the loop runs in. LoopRun.root names it too, since a reload hands it on there.
|
||||
root: str
|
||||
# The worker's session, under whose id loop-inbox lists the loop and its questions.
|
||||
# The worker's session.
|
||||
session: Session
|
||||
listed: Listed
|
||||
paths: Paths
|
||||
env: typing.Mapping[str, str]
|
||||
# The loop-claude script, whose edits reload the loop and beside which chunk-preflight lies.
|
||||
|
||||
@@ -4,50 +4,51 @@ usage: loop-claude <task>
|
||||
|
||||
Run it anywhere inside a project checkout whose goals file has ## Goals and ## Audience, the
|
||||
premises. The goals file is the one the project's config, ~/.claude-projects/<key>/config.toml, sets
|
||||
as goals-and-audience; `project-config goals-and-audience` prints it. The task runs at the checkout
|
||||
root. Each cycle a worker runs the task. A chunk's first worker prompt also quotes the premises.
|
||||
They, with code health (~/.claude/CLAUDE.md → "Shared goal") ranked first unless the goals file
|
||||
voids it, choose between ways to deliver the chunk's todo.md items, or else the task, and never
|
||||
widen them. A judge then reads the transcript's end, the premises, and the records: the project's
|
||||
AGENTS.md and docs/decisions.md, and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
|
||||
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work
|
||||
of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a
|
||||
later chunk could need is recorded: the premises or the records hold it, or the transcript shows the
|
||||
worker writing it into the premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A
|
||||
choice the worker made that the premises or the records settle is not asked about. When the worker
|
||||
asks a question they answer, the judge quotes the answer, loop-claude prints it, and the worker
|
||||
resumes with it. A quote they do not hold word for word is dropped, and the question goes to the
|
||||
human. So does a question asked again after its answer. A question the human answered earlier in the
|
||||
chunk goes back to the worker with that answer, unless the question quotes the words of the answer
|
||||
that leave it open. The fourth question they answer in one cycle goes to the human too, with the
|
||||
quote. An unfinished chunk resumes its session next cycle, and the worker is shown the passage the
|
||||
judge quoted as the work remaining. The next chunk starts a fresh session. Cycles continue until an
|
||||
exit below or Ctrl-C. Words: ~/.claude/CLAUDE.md → "Vocabulary".
|
||||
as goals-and-audience: a file, or a Jira epic's description. `project-config goals-and-audience`
|
||||
prints where it is. The task runs at the checkout root. Each cycle a worker runs the task. A chunk's
|
||||
first worker prompt also quotes the premises. They, with code health (~/.claude/CLAUDE.md →
|
||||
"Shared goal") ranked first unless the goals file voids it, choose between ways to deliver the
|
||||
chunk's todo.md items, or else the task, and never widen them. A judge then reads the transcript's
|
||||
end, the premises, and the records: the project's AGENTS.md and docs/decisions.md, and the human's
|
||||
~/.claude/CLAUDE.md and ~/.claude/rules/*.md, then the .md files in the folder of review standards
|
||||
the project's config sets, where they exist. It rules whether the chunk, the work of one PR, is
|
||||
finished. A chunk stays unfinished until each answer the human typed in it that a later chunk could
|
||||
need is recorded: the premises or the records hold it, or the transcript shows the worker writing it
|
||||
into the premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A choice the worker made
|
||||
that the premises or the records settle is not asked about. When the worker asks a question they
|
||||
answer, the judge quotes the answer, loop-claude prints it, and the worker resumes with it. A quote
|
||||
they do not hold word for word is dropped, and the question goes to the human. So does a question
|
||||
asked again after its answer. A question the human answered earlier in the chunk goes back to the
|
||||
worker with that answer, unless the question quotes the words of the answer that leave it open. The
|
||||
fourth question they answer in one cycle goes to the human too, with the quote. An unfinished chunk
|
||||
resumes its session next cycle, and the worker is shown the passage the judge quoted as the work
|
||||
remaining. The next chunk starts a fresh session. Cycles continue until an exit below or Ctrl-C.
|
||||
Words: ~/.claude/CLAUDE.md → "Vocabulary".
|
||||
|
||||
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
|
||||
loop-claude prints the question on its terminal and lists it in loop-inbox, which shows the
|
||||
interrupts of every loop on the machine. The first answer counts, from either place:
|
||||
loop-claude prints the question on its terminal, where the human answers it:
|
||||
- A line of text: the worker resumes headless with it. The judge reads it as the human's, so the
|
||||
chunk stays unfinished until the answer is recorded.
|
||||
- /talk: opens the worker's session with `claude --resume` where it was typed, to read the diff or
|
||||
- /talk: opens the worker's session with `claude --resume` on the terminal, to read the diff or
|
||||
discuss first. Once that claude exits, the judge rules on what was typed there.
|
||||
- Enter alone, on loop-claude's terminal: stops the loop.
|
||||
A release ready to cut opens that session on the terminal at once, since only the human may cut it;
|
||||
loop-inbox lists it too. While claude is open, Ctrl-C reaches it alone, and the loop goes on.
|
||||
Where ~/.claude/.env exists, loop-claude also sends the human each question, each release ready
|
||||
to cut and each stop as a Mattermost DM, as bin/mattermost-dm sends it. Two stops are left out:
|
||||
Ctrl-C, and printing this help. A DM that fails is said on stderr, and the loop goes on.
|
||||
|
||||
While it runs, loop-claude also lists itself in loop-inbox, with the todo.md items its chunk takes,
|
||||
as bin/loop_state/running_loops.py describes.
|
||||
- Enter alone: stops the loop.
|
||||
A release ready to cut opens that session on the terminal at once, since only the human may cut it.
|
||||
While claude is open, Ctrl-C reaches it alone, and the loop goes on.
|
||||
Where the project's config sets notifier, loop-claude also sends the human each question, each
|
||||
release ready to cut and each stop as a DM, as bin/notify sends it. Two stops are
|
||||
left out: Ctrl-C, and printing this help. A DM that fails is said on stderr, and the loop goes on.
|
||||
|
||||
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree and quotes
|
||||
what it prints in the first prompt (prompts.preflight_facts in bin/loop_claude/cycle/prompts.py);
|
||||
chunk-preflight --help says what it finds and makes. A preflight that fails, or is still running
|
||||
after 600 s and is stopped, leaves the worker to find the facts itself.
|
||||
|
||||
Each project has one session, named "A <key> loop-claude", where <key> is the checkout's path
|
||||
relative to ~/code, or to / outside it. The session is deleted when its chunk finishes. At every
|
||||
Loops of one project run side by side, each on one chunk at a time. Each holds a slot of the
|
||||
project, the file slot-<n> under ~/.local/state/loop-claude/<key>/, locked while the loop runs.
|
||||
<key> is the checkout's path relative to ~/code, or to / outside it. A loop takes the lowest free
|
||||
slot whose session is open, so a rerun resumes a chunk left open, or else the lowest free slot.
|
||||
slot-0's session is named "A <key> loop-claude", and slot-<n>'s "A <key> loop-claude <n+1>".
|
||||
The session is deleted when its chunk finishes. At every
|
||||
interrupt, and as every cycle ends, Ctrl-C and a failure included, the session's transcript is
|
||||
copied into a folder per chunk under $LOOP_CLAUDE_TRANSCRIPTS/<key> (default root
|
||||
~/.claude/loop-claude-transcripts), named by its hash, with an outcomes file beside it: the task,
|
||||
@@ -64,9 +65,9 @@ compacts its context at about 170k tokens.
|
||||
Every claude loop-claude starts runs the project's model, saved per <key> in
|
||||
~/.claude/loop-claude-models.json and read each cycle, unless routing, below, puts the worker,
|
||||
the session /talk opens and the judge on another rung, a model at an effort. A project without an
|
||||
entry, as on its first run, is asked for one on the terminal; loop-inbox doesn't list that
|
||||
question. LOOP_CLAUDE_JUDGE_MODEL overrides the model for the judge, LOOP_CLAUDE_WORKER_MODEL for
|
||||
the worker and the session /talk opens; with both set, nothing is asked.
|
||||
entry, as on its first run, is asked for one on the terminal. LOOP_CLAUDE_JUDGE_MODEL overrides
|
||||
the model for the judge, LOOP_CLAUDE_WORKER_MODEL for the worker and the session /talk opens; with
|
||||
both set, nothing is asked.
|
||||
|
||||
The routing ladder is a list of rungs, least competent first, each a model at an effort. Where the
|
||||
project's model is on it, the worker and the session /talk opens run on
|
||||
@@ -104,7 +105,7 @@ loop to close one measures every finished chunk there, with no model run, and wr
|
||||
routing-figures.md at the archive's root (bin/routing_figures/). Each call the figures make for a
|
||||
routing change, unless raised before, is an interrupt: claude, on the project's model, on the
|
||||
terminal in the setup's development clone, ~/code/claude-config, asked to put the calls to the
|
||||
human; loop-inbox lists it too. Once that claude ends, the calls are listed in
|
||||
human. Once that claude ends, the calls are listed in
|
||||
routing-calls-raised.md beside the figures, kept in routing-state.json, and not raised again. Off a
|
||||
terminal, the calls are said on stderr, the loop goes on, and they are raised again at the next
|
||||
measurement.
|
||||
@@ -115,8 +116,9 @@ loop-claude --help succeeds: the loop reloads into the edited script.
|
||||
Exit 1, saying why, when:
|
||||
- no task is given
|
||||
- git cannot start or finds no checkout
|
||||
- its slot in the project cannot be taken
|
||||
- the goals file, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
|
||||
~/.claude/skills/larv-review/standards/*.md where they exist, cannot be read or is not UTF-8
|
||||
the project's review standards where they exist, cannot be read or is not UTF-8
|
||||
- no config names the checkout, its config cannot be read, or the goals file holds no premises
|
||||
- the models file cannot be read or written
|
||||
- the project's routing ladder cannot be read or holds a fault
|
||||
@@ -141,7 +143,7 @@ Exit 2, when the human is needed to go on:
|
||||
- stdin or stdout is not a terminal, when a model must be picked or an interrupt answered
|
||||
- the input ends while a model is picked
|
||||
- an interrupt's answer is empty, or the input ends before one is typed
|
||||
- the claude opened for /talk, here or in loop-inbox, or for a release ready to cut, ends without
|
||||
- the claude opened for /talk, or for a release ready to cut, ends without
|
||||
anything typed
|
||||
- the judge rules a chunk unfinished 6 cycles running; rerun to give it 6 more
|
||||
Rerunning resumes any open session."""
|
||||
Rerunning resumes an open session that no running loop holds, the lowest one first."""
|
||||
|
||||
@@ -1,23 +1,26 @@
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
from project_config.main import goals_file
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from record_store.stores import goals_store
|
||||
from project_config.main import located
|
||||
from release_plan.goals_file import section
|
||||
|
||||
|
||||
def read_premises(root: str, home: pathlib.Path) -> str | Failure:
|
||||
"""The goals file's path, then its ## Goals and ## Audience; the goals file is the one that the config under home of root's project names. A Failure where no config names root's checkout, the file cannot be read, or the file lacks a section, holds one twice or leaves one empty."""
|
||||
path = goals_file(root, home)
|
||||
if isinstance(path, Failure):
|
||||
return Failure(f"{path.reason} - no premises.")
|
||||
text = read_utf8(str(path.parent), path.name, "no premises")
|
||||
"""Where the goals file is kept, then its ## Goals and ## Audience. The goals file is the one that the config of root's checkout, under home, names: a file or a Jira epic's description. A Failure where no config names the checkout, or the goals file cannot be read, is missing or empty, lacks a section, holds one twice or leaves one empty."""
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - no premises.")
|
||||
goals = goals_store(config)
|
||||
text = goals.read()
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
return Failure(f"{text.reason} - no premises.")
|
||||
if not text:
|
||||
return Failure(f"{goals.label} is missing or empty - no premises.")
|
||||
bodies: list[str] = []
|
||||
for name in ("Goals", "Audience"):
|
||||
body = section(text, name)
|
||||
if isinstance(body, Failure):
|
||||
return Failure(f"{path} {body.reason} - no premises.")
|
||||
return Failure(f"{goals.label} {body.reason} - no premises.")
|
||||
bodies.append(body)
|
||||
return f"{path}:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}"
|
||||
return f"{goals.label}:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}"
|
||||
|
||||
@@ -3,33 +3,49 @@ import pathlib
|
||||
from failure import Failure
|
||||
from project_config.main import located
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from record_store.stores import store
|
||||
|
||||
# The records the judge reads beside the premises: these project files, then the human's rules below.
|
||||
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
|
||||
# The setting in the project's config that places each of RECORD_FILES.
|
||||
RECORD_SETTINGS = ("working-rules", "decisions")
|
||||
# The human's rules for every project, under ~/.claude: CLAUDE.md, then each .md file in these folders, which a repo check keeps present.
|
||||
# The human's rules, in the order the judge reads them: ~/.claude/CLAUDE.md, each .md file in ~/.claude/rules/,
|
||||
# then each .md file in the review standards folder the project's config sets.
|
||||
HUMAN_RULES_FILE = "CLAUDE.md"
|
||||
HUMAN_RULE_DIRS = ("rules", "skills/larv-review/standards")
|
||||
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", *(f"~/.claude/{folder}/" for folder in HUMAN_RULE_DIRS))
|
||||
HUMAN_RULE_DIR = "rules"
|
||||
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", f"~/.claude/{HUMAN_RULE_DIR}/", "the project's review standards")
|
||||
|
||||
|
||||
CONSEQUENCE = "the judge cannot read the records"
|
||||
|
||||
|
||||
def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str | Failure:
|
||||
"""The project's record files, then the human's rules for every project, CLAUDE.md first, each headed by its name; a file that does not exist is left out.
|
||||
"""The project's `AGENTS.md` and decision log, then the human's rules, CLAUDE.md first, each headed by its name; one that does not exist, or is empty, is left out.
|
||||
|
||||
The record files are read where the config under home of root's project puts them, and headed by their names in RECORD_FILES wherever that is."""
|
||||
`AGENTS.md` is read where the config under home of root's project puts it, and the decision log from the store that config names. Each is headed by its name in RECORD_FILES wherever it is kept."""
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - the judge cannot read the records.")
|
||||
rules = [claude_dir / HUMAN_RULES_FILE] + [rule for folder in HUMAN_RULE_DIRS for rule in sorted((claude_dir / folder).glob("*.md"))]
|
||||
sources = [(str(config.paths[setting].parent), config.paths[setting].name, name) for setting, name in zip(RECORD_SETTINGS, RECORD_FILES)]
|
||||
sources += [(str(rule.parent), rule.name, f"~/.claude/{rule.relative_to(claude_dir)}") for rule in rules]
|
||||
return Failure(f"{config.reason} - {CONSEQUENCE}.")
|
||||
rules = [claude_dir / HUMAN_RULES_FILE, *sorted((claude_dir / HUMAN_RULE_DIR).glob("*.md")), *sorted(config.paths["standards"].glob("*.md"))]
|
||||
decisions = store(config, RECORD_SETTINGS[1]).read()
|
||||
texts = [(RECORD_FILES[0], file_text(config.paths[RECORD_SETTINGS[0]])), (RECORD_FILES[1], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)]
|
||||
texts += [(named(rule, home, claude_dir), file_text(rule)) for rule in rules]
|
||||
records = []
|
||||
for folder, name, heading in sources:
|
||||
if not pathlib.Path(folder, name).exists():
|
||||
continue
|
||||
text = read_utf8(folder, name, "the judge cannot read the records")
|
||||
for heading, text in texts:
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
records.append(f"From {heading}:\n{text.strip()}")
|
||||
if text:
|
||||
records.append(f"From {heading}:\n{text.strip()}")
|
||||
return "\n\n".join(records)
|
||||
|
||||
|
||||
def file_text(path: pathlib.Path) -> str | Failure:
|
||||
"""path's text, empty where no such file exists."""
|
||||
return read_utf8(str(path.parent), path.name, CONSEQUENCE) if path.exists() else ""
|
||||
|
||||
|
||||
def named(rule: pathlib.Path, home: pathlib.Path, claude_dir: pathlib.Path) -> str:
|
||||
"""rule's path as the human writes it: under ~/.claude, or ~/ for the rest of home, or else in full."""
|
||||
if rule.is_relative_to(claude_dir):
|
||||
return f"~/.claude/{rule.relative_to(claude_dir)}"
|
||||
return f"~/{rule.relative_to(home)}" if rule.is_relative_to(home) else str(rule)
|
||||
|
||||
@@ -33,8 +33,9 @@ from release_plan.release_standing import chunk_item, LastCut, Next
|
||||
from loop_claude import escalation_mark
|
||||
from failure import Failure
|
||||
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
|
||||
from release_plan.todo_table import Item, items, NoItemsTable
|
||||
from release_plan.todo_table import Item, NoItemsTable
|
||||
from model_routing.ladder import Ladder, Rung
|
||||
from plan_store.stores import Plan
|
||||
from model_routing.route import Route
|
||||
|
||||
UNFINISHED_PER_STEP = 2
|
||||
@@ -44,14 +45,13 @@ ESCALATION_CAP = 2
|
||||
JUDGE_REPLAYED = ("claude-opus-5-5",)
|
||||
|
||||
|
||||
def routed_item(todo: str, cut: LastCut) -> Item | Failure | None:
|
||||
"""The item release_standing.chunk_item picks from todo.md, weighed against the last cut; None when there is none, or it lacks L, E or I."""
|
||||
found = items(todo)
|
||||
if isinstance(found, NoItemsTable):
|
||||
def routed_item(plan: Plan | Failure, cut: LastCut) -> Item | Failure | None:
|
||||
"""The item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
|
||||
if isinstance(plan, NoItemsTable):
|
||||
return None
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
pick = chunk_item(found, cut)
|
||||
if isinstance(plan, Failure):
|
||||
return plan
|
||||
pick = chunk_item(plan.items, cut)
|
||||
takes = pick.item if isinstance(pick, Next) else None
|
||||
return takes if takes and takes.likelihood and takes.escape_and_impact else None
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import dataclasses
|
||||
import datetime
|
||||
import fcntl
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
@@ -18,9 +19,6 @@ import unittest
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from test_env import isolated_env
|
||||
from loop_state.waiting.answers import send, Typed
|
||||
from loop_state import session_lock
|
||||
from loop_state.waiting.listing import waiting
|
||||
from project_config.test_project_config import write_config
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
@@ -41,8 +39,6 @@ role = "judge" if "--json-schema" in argv else "worker" if "-p" in argv else "in
|
||||
scenario = pathlib.Path(os.environ["FAKE_CLAUDE_SCENARIO"])
|
||||
steps = json.loads(scenario.read_text())
|
||||
call = {{"argv": argv, "cwd": os.getcwd(), "role": role, "ctrl_c_ignored": signal.getsignal(signal.SIGINT) == signal.SIG_IGN, "sandboxed": os.environ.get("CLAUDE_CODE_SANDBOXED")}}
|
||||
# The items each loop lists in loop-inbox as this claude starts.
|
||||
call["running"] = [json.loads(path.read_text())["items"] for path in sorted((pathlib.Path.home() / ".local" / "state" / "loop-claude").glob("*.running"))]
|
||||
if role == "judge":
|
||||
call["stdin"] = sys.stdin.read()
|
||||
with open(os.environ["FAKE_CLAUDE_LOG"], "a") as log:
|
||||
@@ -340,8 +336,8 @@ class Premises(unittest.TestCase):
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertRegex(run.raw_stderr, rf"(?m)^{STAMP} .*not a git repository")
|
||||
readmes = {
|
||||
None: "README.md in {root}: No such file or directory - no premises.",
|
||||
b"# P\n## Goals\n1. g\xff\n## Audience\nme\n": "README.md in {root} is not UTF-8 on line 3 - no premises.",
|
||||
None: "{root}/README.md is missing or empty - no premises.",
|
||||
b"# P\n## Goals\n1. g\xff\n## Audience\nme\n": "cannot read {root}/README.md: not UTF-8 on line 3 - no premises.",
|
||||
b"# P\n## Audience\nme\n": "{root}/README.md has no ## Goals heading - no premises.",
|
||||
b"# P\n## Goals\n1. g\n": "{root}/README.md has no ## Audience heading - no premises.",
|
||||
b"# P\n## Goals\n\n## Audience\nme\n": "{root}/README.md has no text under ## Goals - no premises.",
|
||||
@@ -361,7 +357,7 @@ class Premises(unittest.TestCase):
|
||||
(checkout.root / "README.md").mkdir()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertEqual(run.stderr.strip(), f"README.md in {checkout.root}: Is a directory - no premises.")
|
||||
self.assertEqual(run.stderr.strip(), f"cannot read {checkout.root}/README.md: Is a directory - no premises.")
|
||||
(checkout.home / ".claude-projects" / "proj" / "config.toml").unlink()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
@@ -528,16 +524,6 @@ class Cycles(unittest.TestCase):
|
||||
self.assertIn("item 6, L 4, E + I 5", prompt)
|
||||
self.assertTrue((checkout.home / "code" / "proj-item-6").is_dir())
|
||||
|
||||
def test_lists_itself_in_loop_inbox_with_its_routed_item_then_those_the_worker_names_on_its_chunk_items_line_until_the_chunk_finishes(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
|
||||
checkout.commit_plan(TODO)
|
||||
run = checkout.run([worker(say="working\nChunk items: 7, 4"), judge(), worker(), judge(finished=True), worker()])
|
||||
self.assertEqual(run.code, 130)
|
||||
routed, taken_in = {"id": 4, "tagline": "Do it."}, {"id": 7, "tagline": ""}
|
||||
self.assertEqual([call["running"] for call in run.calls], [[[routed]], [[routed]], [[routed, taken_in]], [[routed, taken_in]], [[routed]], [[routed]]])
|
||||
self.assertEqual(list((checkout.home / ".local" / "state" / "loop-claude").glob("*.running")), [])
|
||||
|
||||
def test_steps_the_worker_up_a_rung_when_the_judge_finds_in_the_transcript_the_escalation_trigger_it_cites(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
|
||||
@@ -622,6 +608,27 @@ class Cycles(unittest.TestCase):
|
||||
self.assertIsNotNone(argument(run.calls[0], "--resume"))
|
||||
self.assertEqual((argument(run.calls[0], "--model"), argument(run.calls[0], "--effort")), ("claude-fable-5-2", "medium"))
|
||||
|
||||
def test_a_second_loop_in_the_project_runs_its_own_session_and_leaves_the_first_loops_open_chunk_alone(self):
|
||||
checkout = Checkout(self)
|
||||
first = checkout.run([worker(say="first chunk"), judge(evidence="first chunk")])
|
||||
session = argument(first.calls[0], "--session-id")
|
||||
transcript = checkout.transcripts()[0]
|
||||
kept, archived = transcript.read_bytes(), checkout.archived()
|
||||
slot = checkout.home / ".local" / "state" / "loop-claude" / "proj" / "slot-0"
|
||||
slot.parent.mkdir(parents=True, exist_ok=True)
|
||||
# The test holds the first loop's slot, as the first loop does while it runs.
|
||||
with open(slot, "a") as running:
|
||||
fcntl.flock(running, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
second = checkout.run([worker(say="second chunk"), judge(evidence="second chunk")])
|
||||
self.assertEqual(argument(second.calls[0], "--name"), "A proj loop-claude 2")
|
||||
self.assertNotIn(session, [argument(call, "--session-id") or argument(call, "--resume") for call in second.calls if call["role"] == "worker"])
|
||||
self.assertNotIn("first chunk", second.calls[1]["stdin"])
|
||||
self.assertEqual(transcript.read_bytes(), kept)
|
||||
self.assertLessEqual(archived.items(), checkout.archived().items())
|
||||
self.assertEqual(len(checkout.archived()), len(archived) + 1)
|
||||
rerun = checkout.run([worker()])
|
||||
self.assertEqual(argument(rerun.calls[0], "--resume"), session)
|
||||
|
||||
def test_exits_1_when_the_transcript_cannot_be_archived_and_resumes_on_the_next_run(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.archive().parent.mkdir(parents=True)
|
||||
@@ -788,6 +795,23 @@ class Interrupt(unittest.TestCase):
|
||||
self.assertEqual(run.code, 2)
|
||||
self.assertEqual(len(checkout.archived()), 2)
|
||||
|
||||
def test_sends_the_dm_through_the_notifier_and_env_file_the_config_names_and_no_credential_reaches_a_prompt_a_line_printed_or_a_file_written(self):
|
||||
checkout = Checkout(self)
|
||||
token = "tok-3f9a1c7e-sentinel"
|
||||
env_file = checkout.home / ".claude-projects" / "proj.env"
|
||||
env_file.write_text(f"MATTERMOST_URL=https://127.0.0.1:1\nMATTERMOST_TOKEN={token}\nMATTERMOST_RECIPIENT=lilleman\n")
|
||||
env_file.chmod(0o600)
|
||||
with (checkout.home / ".claude-projects" / "proj" / "config.toml").open("a") as config:
|
||||
config.write('env-file = "~/.claude-projects/proj.env"\nnotifier = "mattermost"\n')
|
||||
run = checkout.run([worker(say="Shall I use A or B?"), judge(interrupt=True, evidence="Shall I use A or B?", question="A or B?")])
|
||||
self.assertEqual((run.code, run.roles()), (2, ["worker", "judge"]))
|
||||
self.assertIn("could not DM you: cannot reach https://127.0.0.1:1", run.stderr)
|
||||
held = [run.raw_stdout, run.raw_stderr, json.dumps(run.calls), json.dumps(run.starts)]
|
||||
held += [file.read_text(errors="replace") for file in checkout.home.rglob("*") if file.is_file() and file != env_file and not file.is_symlink()]
|
||||
self.assertGreater(len(held), 8, "the walk reached the archive, the state and the transcripts")
|
||||
for text in held:
|
||||
self.assertNotIn(token, text)
|
||||
|
||||
def test_resumes_the_worker_headless_with_the_answer_typed_at_its_terminal_not_with_keys_typed_before_it(self):
|
||||
checkout = Checkout(self)
|
||||
asked = [worker(say="Shall I use A or B?"), judge(interrupt=True, evidence="Shall I use A or B?", question="A or B?")]
|
||||
@@ -799,34 +823,6 @@ class Interrupt(unittest.TestCase):
|
||||
self.assertIn("[human] B\n\nUsing B.", run.calls[3]["stdin"])
|
||||
self.assertNotIn("stray", run.calls[3]["stdin"])
|
||||
|
||||
def test_resumes_the_worker_headless_with_the_answer_typed_in_loop_inbox(self):
|
||||
checkout = Checkout(self)
|
||||
folder = checkout.home / ".local" / "state" / "loop-claude"
|
||||
def answered_in_inbox():
|
||||
[ask] = waiting(folder)
|
||||
send(folder, ask, Typed("B"))
|
||||
asked = [worker(say="Shall I use A or B?"), judge(interrupt=True, evidence="Shall I use A or B?", question="A or B?")]
|
||||
run = checkout.run([*asked, worker(say="Using B."), judge(evidence="Using B.")], terminal_input="", before_typing=("Answer (", answered_in_inbox))
|
||||
self.assertEqual(run.code, 130)
|
||||
self.assertEqual(run.roles(), ["worker", "judge", "worker", "judge", "worker"])
|
||||
self.assertIn("Answer (/talk opens claude, Enter stops the loop): \nAnswered in loop-inbox: B\n", run.stderr)
|
||||
self.assertIn("[human] B\n\nUsing B.", run.calls[3]["stdin"])
|
||||
self.assertEqual([path for path in folder.iterdir() if path.suffix != ".lock"], [])
|
||||
|
||||
def test_a_second_loop_on_the_session_runs_unlisted_and_keeps_its_question_out_of_the_first_loops_folder(self):
|
||||
checkout = Checkout(self)
|
||||
folder = checkout.home / ".local" / "state" / "loop-claude"
|
||||
asked = [worker(say="Shall I use A or B?"), judge(interrupt=True, evidence="Shall I use A or B?", question="A or B?")]
|
||||
session = argument(checkout.run(asked).calls[0], "--session-id")
|
||||
# The first loop on the session, still running.
|
||||
self.enterContext(session_lock.held(folder, session))
|
||||
asks = []
|
||||
run = checkout.run(asked, terminal_input="\n", before_typing=("Answer (", lambda: asks.extend(folder.glob("*.json"))))
|
||||
self.assertEqual(run.code, 2)
|
||||
self.assertIn(f"loop-inbox cannot list this loop or its questions: another process holds {session_lock.lock_file(folder, session)}", run.stderr)
|
||||
self.assertEqual((asks, run.calls[0]["running"]), ([], []))
|
||||
self.assertFalse((folder / "unlisted").exists() and any((folder / "unlisted").iterdir()))
|
||||
|
||||
def test_hands_the_terminal_over_and_exits_2_when_nothing_is_typed(self):
|
||||
checkout = Checkout(self)
|
||||
checkout.git("commit", "--allow-empty", "--quiet", "-m", "start")
|
||||
@@ -975,7 +971,7 @@ class Reload(unittest.TestCase):
|
||||
self.assertEqual(run.roles(), ["worker", "judge"] * 5)
|
||||
self.assertIn("keeping the running script", run.stderr)
|
||||
reloads = [json.loads(argv[1]) for argv in run.starts if argv[:1] == ["--reloaded"]]
|
||||
self.assertEqual(reloads, [{"cycle_number": cycle, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "working", "route": OFF_LADDER_ROUTE, "unfinished_run": cycle, "items_taken_in": []} for cycle in (2, 3, 4)])
|
||||
self.assertEqual(reloads, [{"cycle_number": cycle, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "working", "route": OFF_LADDER_ROUTE, "unfinished_run": cycle, "slot": 0} for cycle in (2, 3, 4)])
|
||||
self.assertIn("=== cycle 5,", run.stdout)
|
||||
|
||||
outside = checkout.temp / "outside"
|
||||
|
||||
+147
-222
@@ -18,37 +18,33 @@ import uuid
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from routing_figures import archive, state
|
||||
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
|
||||
from routing_figures.calls import Call
|
||||
from loop_claude.project import checkout, model_choice, records
|
||||
from loop_claude.cycle import chunk_items
|
||||
from loop_claude.loop import chunk_start, close
|
||||
from loop_state.waiting.answers import ClaudeEnded, ClaudeOpening, send, Typed
|
||||
from loop_claude.loop import chunk_slot, chunk_start, close
|
||||
from project_config.test_project_config import configured
|
||||
from release_plan.release_standing import DefaultPlan, LastCut, UNSEEN_RELEASES
|
||||
from loop_effects.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT
|
||||
from loop_effects.effects import Effects, PYTHON_TIMEOUT
|
||||
from claude_code import entries, reply, session
|
||||
from failure import Failure
|
||||
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
|
||||
from git_cli.git_repo import git
|
||||
from loop_state import hand_over, paths, running_loops, session_lock
|
||||
from loop_claude.cycle import interrupt, judge, prompts, retry, run, spend, states, worker
|
||||
from claude_code.reply import Limited
|
||||
from loop_claude.loop import main, reload, routing_check, this_loop, usage
|
||||
from loop_state.waiting.talk import make_way
|
||||
from machine_load import memory
|
||||
from transcript_archive import outcomes, write
|
||||
from loop_state import paths
|
||||
from plan_store.stores import plan_of
|
||||
from transcript_archive.location import project_archive
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from model_routing.route import Route, route_from, WorkerLine
|
||||
from loop_claude import routing
|
||||
from model_routing.ladder import Rung
|
||||
from loop_claude.stop import Stop
|
||||
from loop_state.running_loops import Taken
|
||||
from claude_code.tokens import Tokens, tokens_of
|
||||
from text_files.utc_stamp import utc
|
||||
from loop_claude.cycle.judge import verdict_from
|
||||
from loop_state.waiting.listing import waiting
|
||||
|
||||
# How the archive records a worker that runs off the ladder.
|
||||
LADDER = read_ladder(SHIPPED)
|
||||
@@ -66,10 +62,6 @@ NOW = 1790000000
|
||||
STAMP = f"<{NOW}>"
|
||||
# How git answers in a project's checkout it cannot read, such as one that is gone.
|
||||
UNREAD = Failure("not a git repository")
|
||||
# The id FakeEffects gives each new ask, and its pid for loop-claude's process.
|
||||
ASK_ID, PID = "ask-1", 4242
|
||||
# The pid of a loop-inbox that opens claude for an ask.
|
||||
INBOX = 4343
|
||||
|
||||
|
||||
def assistant(*parts):
|
||||
@@ -84,15 +76,10 @@ def human(content):
|
||||
return {"type": "user", "message": {"content": content}}
|
||||
|
||||
|
||||
def asks_and_answers(folder):
|
||||
"""folder's files but the session's lock file, which stays once the loop lets go of the lock."""
|
||||
return [path for path in sorted(folder.iterdir()) if path.suffix != ".lock"]
|
||||
|
||||
|
||||
def a_loop(effects, **fields):
|
||||
"""A loop in /r on effects, with fields in place of its defaults."""
|
||||
home = pathlib.Path("/h")
|
||||
defaults = {"root": "/r", "session": session.session_named("A proj loop-claude", home / ".claude" / "projects"), "listed": running_loops.Listed(home / "waiting", lambda items: None), "paths": paths.paths_from(home), "env": {}, "launcher": pathlib.Path("/b/loop-claude")}
|
||||
defaults = {"root": "/r", "session": session.session_named("A proj loop-claude", home / ".claude" / "projects"), "paths": paths.paths_from(home), "env": {}, "launcher": pathlib.Path("/b/loop-claude")}
|
||||
return this_loop.Loop(**{**defaults, **fields}, effects=effects)
|
||||
|
||||
|
||||
@@ -114,7 +101,6 @@ class FakeEffects:
|
||||
|
||||
def effects(self):
|
||||
return Effects(
|
||||
alive=lambda pid: True,
|
||||
claude=lambda args, cwd, stdin: self.answer("claude", (args, stdin)),
|
||||
claude_on_terminal=self.on_terminal_claude,
|
||||
discard_typed=lambda: self.calls.append(("discard_typed", None)),
|
||||
@@ -122,13 +108,10 @@ class FakeEffects:
|
||||
execv=self.execv,
|
||||
git=lambda *args, cwd=None, timeout=None, guarded=False, errors="strict": self.answer("git", list(args)),
|
||||
input=lambda prompt: self.answer("input", prompt),
|
||||
input_or=self.input_or,
|
||||
local_time=lambda seconds: f"<{seconds}>",
|
||||
memory=self.memory,
|
||||
new_id=lambda: ASK_ID,
|
||||
now=lambda: NOW,
|
||||
on_terminal=lambda: self.terminal,
|
||||
pid=lambda: PID,
|
||||
python=lambda args, cwd: self.answer("python", (args, cwd)),
|
||||
sleep=lambda seconds: self.calls.append(("sleep", seconds)),
|
||||
stream_claude=self.stream,
|
||||
@@ -142,14 +125,6 @@ class FakeEffects:
|
||||
self.calls.append(("memory", None))
|
||||
return self.free_memory.pop(0) if self.free_memory else memory.Memory(available=16, total=16)
|
||||
|
||||
def input_or(self, prompt, other):
|
||||
"""Answers from the input script as input does; a callable in the script gets other, the source of loop-inbox's answer."""
|
||||
self.calls.append(("input", prompt))
|
||||
answer = self.scripts["input"].pop(0)
|
||||
if isinstance(answer, BaseException):
|
||||
raise answer
|
||||
return answer(other) if callable(answer) else answer
|
||||
|
||||
def on_terminal_claude(self, args, cwd, env):
|
||||
self.terminal_environments.append(env)
|
||||
self.terminal_folders.append(cwd)
|
||||
@@ -277,7 +252,7 @@ class Transitions(unittest.TestCase):
|
||||
class QuestionFor(unittest.TestCase):
|
||||
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
|
||||
self.assertEqual(run.question_for(Interrupt("e", "Which one?")), "Which one?")
|
||||
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
|
||||
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
|
||||
|
||||
|
||||
class Cycles(unittest.TestCase):
|
||||
@@ -290,7 +265,7 @@ class Cycles(unittest.TestCase):
|
||||
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
|
||||
|
||||
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
|
||||
return run.Cycle(config=CONFIG, effects=fake.effects(), facts=facts, judge_model="judge-model", ladder=LADDER, premises="## Goals", project=None, project_archive=self.archive, questions=self.paths.waiting, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, show_taken_in=lambda items: None, task="Do it.", todo="", unfinished_evidence=unfinished_evidence)
|
||||
return run.Cycle(config=CONFIG, effects=fake.effects(), facts=facts, judge_model="judge-model", ladder=LADDER, premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", todo=plan_of(""), unfinished_evidence=unfinished_evidence)
|
||||
|
||||
def archived_outcomes(self):
|
||||
return sorted(path.read_text() for path in self.archive.glob("*/*.outcomes.md"))
|
||||
@@ -330,20 +305,6 @@ Judge: judge-model
|
||||
Worker: {OFF_LADDER}
|
||||
"""])
|
||||
|
||||
def test_shows_the_items_each_ruling_finds_the_worker_names_on_its_chunk_items_line(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent, text="working\nChunk items: 14 (L 2, E + I 3), 3 (L 1, E + I 2)")
|
||||
fake = FakeEffects(streams=[worker], claude=[judged("unfinished")])
|
||||
shown = []
|
||||
run.run_cycle(dataclasses.replace(self.cycle(fake), show_taken_in=shown.append))
|
||||
self.assertEqual(shown, [(14, 3)])
|
||||
|
||||
def test_shows_no_items_for_a_finished_chunk(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent, text="working\nChunk items: 3")
|
||||
fake = FakeEffects(streams=[worker], claude=[judged("finished")])
|
||||
shown = []
|
||||
run.run_cycle(dataclasses.replace(self.cycle(fake), show_taken_in=shown.append))
|
||||
self.assertEqual(shown, [])
|
||||
|
||||
def test_a_fresh_worker_reads_the_preflights_facts_and_a_resumed_one_does_not(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent)
|
||||
fake = FakeEffects(streams=[worker, worker], claude=[judged("unfinished"), judged("finished")])
|
||||
@@ -532,12 +493,12 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said, contextlib.redirect_stdout(io.StringIO()) as printed:
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
|
||||
resumed = fake.made("stream_claude")[1]
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(len(fake.made("stream_claude")), 4)
|
||||
self.assertEqual(printed.getvalue().count("=== the goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
self.assertEqual(printed.getvalue().count("=== the goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
|
||||
def test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("quoted", answer="Use A.", escalation="working"), judged("finished")])
|
||||
@@ -772,25 +733,11 @@ class Interrupts(unittest.TestCase):
|
||||
self.session = interrupt.WorkerSession(str(self.home), uuid.uuid7(), Rung("m", "high"), str(self.transcript), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
|
||||
|
||||
def put(self, fake, answer_here=True, effects=None, question="Which one?"):
|
||||
"""interrupt's answer and what it said, run while the session's lock is held, as a running loop holds it."""
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said, session_lock.held(self.paths.waiting, str(self.session.id)):
|
||||
answer = interrupt.interrupt(question, answer_here, self.session, self.paths.waiting, effects or fake.effects())
|
||||
"""interrupt's answer and what it said."""
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
answer = interrupt.interrupt(question, answer_here, self.session, effects or fake.effects())
|
||||
return answer, said.getvalue()
|
||||
|
||||
def asked(self):
|
||||
return waiting(self.paths.waiting)
|
||||
|
||||
def ask(self, question="Which one?", state=None):
|
||||
"""The ask interrupt makes for question, in state; by default it waits for an answer, and /talk resumes the worker's session."""
|
||||
resumed = hand_over.ClaudeCommand(["--model", "m", "--effort", "high", "--permission-mode", "bypassPermissions", "--resume", str(self.session.id)], str(self.home), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
|
||||
return Ask(ASK_ID, str(self.session.id), str(self.home), question, NOW, state or Asking(resumed))
|
||||
|
||||
def opening(self, other):
|
||||
"""loop-inbox's /talk, as the loop's input sees it: loop-inbox claims the one ask listed, and the claim is the first answer."""
|
||||
[ask] = self.asked()
|
||||
send(self.paths.waiting, ask, ClaudeOpening(INBOX))
|
||||
return other()
|
||||
|
||||
def typed_there(self, args):
|
||||
"""The claude opened on the terminal: the human types a line in the worker's session, and it ends."""
|
||||
with open(self.transcript, "a") as handle:
|
||||
@@ -818,7 +765,7 @@ class Interrupts(unittest.TestCase):
|
||||
|
||||
def test_says_why_a_dm_failed_and_still_takes_the_answer(self):
|
||||
fake = FakeEffects(inputs=["Use B."], dm_failures=[Failure("cannot reach https://chat.example: timed out")])
|
||||
self.assertEqual(self.put(fake), ("Use B.", f"\n{STAMP} Which one?\n{STAMP} could not DM you on Mattermost: cannot reach https://chat.example: timed out\n"))
|
||||
self.assertEqual(self.put(fake), ("Use B.", f"\n{STAMP} Which one?\n{STAMP} could not DM you: cannot reach https://chat.example: timed out\n"))
|
||||
|
||||
def test_returns_the_line_typed_after_the_question_stripped_dropping_what_was_typed_before(self):
|
||||
fake = FakeEffects(inputs=[" Use B. "])
|
||||
@@ -837,86 +784,6 @@ class Interrupts(unittest.TestCase):
|
||||
for typed, why, said in ((" ", "nothing was typed", ""), (EOFError(), "the input ended", "\n")):
|
||||
with self.subTest(why=why):
|
||||
self.assertEqual(self.put(FakeEffects(inputs=[typed])), (Stop(2, f"the human is needed to answer the question above, but {why}"), f"\n{STAMP} Which one?\n{said}"))
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_shows_the_question_in_loop_inbox_while_it_waits_and_only_then(self):
|
||||
def typed(_):
|
||||
self.assertEqual(self.asked(), [self.ask()])
|
||||
return "Use B."
|
||||
self.assertEqual(self.put(FakeEffects(inputs=[typed]))[0], "Use B.")
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_takes_a_line_typed_in_loop_inbox_for_this_question_and_no_other(self):
|
||||
def answered(_, other):
|
||||
[ask] = self.asked()
|
||||
send(self.paths.waiting, dataclasses.replace(ask, id="an earlier ask"), Typed("Use A."))
|
||||
self.assertIsNone(other())
|
||||
send(self.paths.waiting, ask, Typed(" Use C. "))
|
||||
return other()
|
||||
fake = FakeEffects()
|
||||
effects = dataclasses.replace(fake.effects(), input_or=answered)
|
||||
self.assertEqual(self.put(fake, effects=effects), ("Use C.", f"\n{STAMP} Which one?\n{STAMP} Answered in loop-inbox: Use C. \n"))
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_takes_the_answer_typed_on_its_terminal_where_loop_inbox_cannot_list_the_question(self):
|
||||
self.paths.waiting.parent.mkdir(parents=True)
|
||||
self.paths.waiting.write_text("")
|
||||
answer, said = self.put(FakeEffects(inputs=["Use B."]))
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertIn(f"loop-inbox cannot show this question: cannot make {self.paths.waiting}: File exists", said)
|
||||
stop, _ = self.put(FakeEffects(inputs=["/talk"], on_terminal_claude=[0]))
|
||||
self.assertEqual(stop, Stop(2, "the human is needed to answer the question above, but the interrupt ended without anything typed"))
|
||||
|
||||
def test_makes_way_only_warns_where_loop_inbox_cannot_list_the_open_claude(self):
|
||||
self.paths.waiting.parent.mkdir(parents=True)
|
||||
self.paths.waiting.write_text("")
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
make_way(self.paths.waiting, self.ask(), INBOX, FakeEffects().effects())
|
||||
self.assertIn(f"loop-inbox cannot show this question: cannot make {self.paths.waiting}: File exists", said.getvalue())
|
||||
|
||||
def test_makes_way_for_the_claude_loop_inbox_opens_and_goes_on_once_the_human_typed_there(self):
|
||||
def claude_ran(_):
|
||||
# loop-inbox opens claude only once the loop lists it as open there.
|
||||
self.assertEqual(self.asked(), [self.ask(state=OpenInInbox(INBOX))])
|
||||
with open(self.transcript, "a") as handle:
|
||||
handle.write(json.dumps(human("cut it")) + "\n")
|
||||
send(self.paths.waiting, self.ask(), ClaudeEnded())
|
||||
fake = FakeEffects(inputs=[self.opening])
|
||||
self.assertEqual(self.put(fake, effects=dataclasses.replace(fake.effects(), sleep=claude_ran)), (interrupt.Talked(), f"\n{STAMP} Which one?\n{STAMP} claude is open for this question in loop-inbox; waiting for it to end\n"))
|
||||
self.assertEqual((fake.made("claude_on_terminal"), asks_and_answers(self.paths.waiting)), ([], []))
|
||||
|
||||
def test_stops_when_loop_inbox_ends_its_claude_with_nothing_typed(self):
|
||||
looked, slept = [], []
|
||||
def alive(pid):
|
||||
looked.append(pid)
|
||||
return pid == INBOX
|
||||
def ended(seconds):
|
||||
slept.append(seconds)
|
||||
send(self.paths.waiting, self.ask(), ClaudeEnded())
|
||||
fake = FakeEffects(inputs=[self.opening])
|
||||
stop, _ = self.put(fake, effects=dataclasses.replace(fake.effects(), alive=alive, sleep=ended))
|
||||
self.assertEqual((stop, looked, slept), (Stop(2, "the human is needed to answer the question above, but the interrupt ended without anything typed"), [INBOX], [POLL_SECONDS]))
|
||||
|
||||
def test_stops_when_loop_inbox_is_gone_with_nothing_typed(self):
|
||||
looked = []
|
||||
def alive(pid):
|
||||
looked.append(pid)
|
||||
# loop-inbox's process ends while the loop waits for its claude.
|
||||
return pid == INBOX and len(looked) == 1
|
||||
fake = FakeEffects(inputs=[self.opening])
|
||||
stop, _ = self.put(fake, effects=dataclasses.replace(fake.effects(), alive=alive))
|
||||
self.assertEqual((stop, looked, fake.made("sleep")), (Stop(2, "the human is needed to answer the question above, but the interrupt ended without anything typed"), [INBOX, INBOX], [POLL_SECONDS]))
|
||||
|
||||
def test_lists_the_claude_open_on_its_terminal_in_loop_inbox_while_it_runs(self):
|
||||
for typed, answer_here in (([" /talk "], True), ([], False)):
|
||||
with self.subTest(typed=typed):
|
||||
def ran(args):
|
||||
self.assertEqual(self.asked(), [self.ask("Cut 0.4.0?", OpenOnTerminal())])
|
||||
return 0
|
||||
fake = FakeEffects(inputs=typed, on_terminal_claude=[ran])
|
||||
self.put(fake, answer_here, question="Cut 0.4.0?")
|
||||
self.assertEqual(len(fake.made("claude_on_terminal")), 1)
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_stops_when_nothing_was_typed_in_the_session(self):
|
||||
fake = FakeEffects(inputs=["/talk"], on_terminal_claude=[0])
|
||||
@@ -939,8 +806,8 @@ class RoutingCheck(unittest.TestCase):
|
||||
self.session = session.session_named("A log loop-claude", self.paths.claude_code_transcripts)
|
||||
|
||||
def loop(self, fake):
|
||||
"""The loop in /code/log, whose questions loop-inbox lists."""
|
||||
return a_loop(fake.effects(), root="/code/log", session=self.session, listed=running_loops.Listed(self.paths.waiting, lambda items: None), paths=self.paths)
|
||||
"""The loop in /code/log."""
|
||||
return a_loop(fake.effects(), root="/code/log", session=self.session, paths=self.paths)
|
||||
|
||||
def chunks(self, count, verdicts, project="log"):
|
||||
"""count finished chunks, each closed by verdicts verdicts, each with one Explore subagent whose report outgrew its searches."""
|
||||
@@ -959,37 +826,28 @@ class RoutingCheck(unittest.TestCase):
|
||||
def check(self, fake):
|
||||
"""What check_routing returns and says for a loop in /code/log."""
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
self.enterContext(session_lock.held(self.paths.waiting, str(self.session.id)))
|
||||
stop = routing_check.check_routing(self.root, Rung("m", "high"), self.loop(fake))
|
||||
return stop, said.getvalue()
|
||||
|
||||
def test_lists_the_calls_in_loop_inbox_while_their_claude_is_open(self):
|
||||
self.chunks(5, 4)
|
||||
question = f"loop-claude's routing figures call for a routing change:\n- Explore subagents' reports took more of the worker's context than their searches would have.\nThe figures: {self.root / 'routing-figures.md'}"
|
||||
def ran(args):
|
||||
self.assertEqual(waiting(self.paths.waiting), [Ask(ASK_ID, str(self.session.id), "/code/log", question, NOW, OpenOnTerminal())])
|
||||
return 0
|
||||
self.check(FakeEffects(on_terminal_claude=[ran], git=[UNREAD] * 2))
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_measures_once_20_cycles_have_closed_since_the_last_measurement(self):
|
||||
self.chunks(5, 3)
|
||||
self.assertEqual(self.check(FakeEffects()), (None, ""))
|
||||
self.assertFalse((self.root / "routing-figures.md").exists())
|
||||
self.chunks(6, 1, "other")
|
||||
self.assertEqual(self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 4))[0], None)
|
||||
self.assertEqual(self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 6))[0], None)
|
||||
self.assertIn("at cycle 21 across", (self.root / "routing-figures.md").read_text())
|
||||
|
||||
def test_reads_each_projects_history_through_the_loops_git_and_names_each_it_cannot_read(self):
|
||||
self.chunks(5, 4)
|
||||
fake = FakeEffects(on_terminal=False, git=[UNREAD] * 2)
|
||||
fake = FakeEffects(on_terminal=False, git=[UNREAD] * 3)
|
||||
self.check(fake)
|
||||
self.assertEqual(fake.made("git"), [["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], ["remote"]])
|
||||
located = ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]
|
||||
self.assertEqual(fake.made("git"), [located, located, ["remote"]], "the config is located for its title templates, then for where it keeps the plan")
|
||||
self.assertIn("## Default branches unread\n\n- log: not a git repository\n", (self.root / "routing-figures.md").read_text())
|
||||
|
||||
def test_hands_the_terminal_over_once_for_each_new_call(self):
|
||||
self.chunks(5, 4)
|
||||
fake = FakeEffects(on_terminal_claude=[0], git=[UNREAD] * 2)
|
||||
fake = FakeEffects(on_terminal_claude=[0], git=[UNREAD] * 3)
|
||||
stop, said = self.check(fake)
|
||||
self.assertIsNone(stop)
|
||||
call = "Explore subagents' reports took more of the worker's context than their searches would have."
|
||||
@@ -1002,13 +860,13 @@ class RoutingCheck(unittest.TestCase):
|
||||
self.assertEqual(fake.terminal_folders, [str(self.home / "code" / "claude-config")], "the development clone, since ~/.claude holds only a release")
|
||||
self.assertIn("Record what they decide in this checkout, the development clone", args[6])
|
||||
self.assertIsNone(state.mark_measured(self.root, 0))
|
||||
self.assertEqual(self.check(FakeEffects(git=[UNREAD] * 2))[0], None)
|
||||
self.assertEqual(self.check(FakeEffects(git=[UNREAD] * 3))[0], None)
|
||||
self.assertNotIn(call, self.check(FakeEffects())[1])
|
||||
|
||||
def test_stamps_the_figures_and_the_calls_raised_when_it_measures(self):
|
||||
self.chunks(5, 4)
|
||||
(self.root / "routing-calls-raised.md").write_text("# Routing calls raised\n\n- 2026-10-14T10:02:00Z Reset\n")
|
||||
self.check(FakeEffects(on_terminal_claude=[0], git=[UNREAD] * 2))
|
||||
self.check(FakeEffects(on_terminal_claude=[0], git=[UNREAD] * 3))
|
||||
figures = (self.root / "routing-figures.md").read_text()
|
||||
self.assertIn(f"Measured {utc(NOW)}, at cycle 20 across", figures)
|
||||
self.assertIn("that finished after the reset of 2026-10-14T10:02:00Z", figures)
|
||||
@@ -1021,11 +879,11 @@ class RoutingCheck(unittest.TestCase):
|
||||
|
||||
def test_goes_on_off_a_terminal_and_raises_the_call_again_next_time(self):
|
||||
self.chunks(5, 4)
|
||||
stop, said = self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 2))
|
||||
stop, said = self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 3))
|
||||
self.assertIsNone(stop)
|
||||
self.assertIn("Not on a terminal: the calls are raised again at the next measurement.", said)
|
||||
self.assertIsNone(state.mark_measured(self.root, 0))
|
||||
self.assertIn("Not on a terminal", self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 2))[1])
|
||||
self.assertIn("Not on a terminal", self.check(FakeEffects(on_terminal=False, git=[UNREAD] * 3))[1])
|
||||
|
||||
def test_leaves_the_measuring_to_a_loop_holding_the_lock(self):
|
||||
self.chunks(5, 4)
|
||||
@@ -1034,9 +892,8 @@ class RoutingCheck(unittest.TestCase):
|
||||
|
||||
def test_stops_when_claude_cannot_start_for_the_calls(self):
|
||||
self.chunks(5, 4)
|
||||
stop, _ = self.check(FakeEffects(on_terminal_claude=[OSError(2, "No such file or directory")], git=[UNREAD] * 2))
|
||||
stop, _ = self.check(FakeEffects(on_terminal_claude=[OSError(2, "No such file or directory")], git=[UNREAD] * 3))
|
||||
self.assertEqual(stop, Stop(1, f"could not start claude for the routing calls in {self.home / 'code' / 'claude-config'}, the setup's development clone: No such file or directory"))
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
@unittest.skipIf(os.geteuid() == 0, "root writes into a read-only directory")
|
||||
def test_says_a_figure_it_cannot_write_and_goes_on(self):
|
||||
@@ -1044,7 +901,7 @@ class RoutingCheck(unittest.TestCase):
|
||||
(self.root / "routing-figures.lock").touch()
|
||||
self.root.chmod(0o555)
|
||||
self.addCleanup(self.root.chmod, 0o755)
|
||||
stop, said = self.check(FakeEffects(git=[UNREAD] * 2))
|
||||
stop, said = self.check(FakeEffects(git=[UNREAD] * 3))
|
||||
self.assertIsNone(stop)
|
||||
self.assertIn("routing figures: could not write", said)
|
||||
|
||||
@@ -1082,6 +939,11 @@ class ModelPrompt(unittest.TestCase):
|
||||
|
||||
# A plan read with no release cut yet.
|
||||
NO_CUT = LastCut(None, "", 0, [])
|
||||
def routed_item(todo, cut):
|
||||
"""routing.routed_item for the plan a todo.md's text holds."""
|
||||
return routing.routed_item(plan_of(todo), cut)
|
||||
|
||||
|
||||
TODO = """# todo
|
||||
|
||||
## Items
|
||||
@@ -1112,32 +974,32 @@ class Routing(unittest.TestCase):
|
||||
SONNET = Rung("claude-sonnet-5-5", "high")
|
||||
|
||||
def test_routes_on_the_next_releases_top_item_that_waits_on_no_question(self):
|
||||
self.assertEqual(routing.routed_item(TODO, NO_CUT).id, 3)
|
||||
self.assertIsNone(routing.routed_item(TODO.replace("| | **Do", "| question | **Do"), NO_CUT))
|
||||
self.assertIsNone(routing.routed_item("# todo\n", NO_CUT))
|
||||
self.assertIsNone(routing.routed_item(TODO[:TODO.index("| 7 |")], NO_CUT))
|
||||
self.assertEqual(routed_item(TODO, NO_CUT).id, 3)
|
||||
self.assertIsNone(routed_item(TODO.replace("| | **Do", "| question | **Do"), NO_CUT))
|
||||
self.assertIsNone(routed_item("# todo\n", NO_CUT))
|
||||
self.assertIsNone(routed_item(TODO[:TODO.index("| 7 |")], NO_CUT))
|
||||
old_shape = "## Items\n\n| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n| 3 | 0.2.0 | | **Do the next thing.** | 5 | 3 | 6 | 8 | 9 | 1 | 25 |\n"
|
||||
self.assertIsNone(routing.routed_item(old_shape, NO_CUT))
|
||||
self.assertEqual(routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), NO_CUT), Failure("item 3's L 'x' is not a whole number from 1 to 4"))
|
||||
self.assertIsNone(routed_item(old_shape, NO_CUT))
|
||||
self.assertEqual(routed_item(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), NO_CUT), Failure("item 3's L 'x' is not a whole number from 1 to 4"))
|
||||
|
||||
def test_routes_on_no_item_where_the_release_after_the_last_cut_has_none(self):
|
||||
self.assertEqual(routing.routed_item(TODO, LastCut("v0.1.0", "", 3, [TODO])).id, 3)
|
||||
self.assertIsNone(routing.routed_item(TODO, LastCut("v0.2.0", "", 3, [TODO])))
|
||||
self.assertEqual(routed_item(TODO, LastCut("v0.1.0", "", 3, [TODO])).id, 3)
|
||||
self.assertIsNone(routed_item(TODO, LastCut("v0.2.0", "", 3, [TODO])))
|
||||
later_only = TODO[:TODO.index("| 7 |")] + TODO[TODO.index("| 1 | 0.3.0 |"):]
|
||||
self.assertIsNone(routing.routed_item(later_only, LastCut("v0.1.0", "", 3, [TODO])))
|
||||
self.assertIsNone(routing.routed_item(later_only, LastCut("v0.1.0", "", 0, [TODO])))
|
||||
self.assertEqual(routing.routed_item(later_only, LastCut("v0.2.0", "", 3, [later_only])).id, 1)
|
||||
self.assertIsNone(routed_item(later_only, LastCut("v0.1.0", "", 3, [TODO])))
|
||||
self.assertIsNone(routed_item(later_only, LastCut("v0.1.0", "", 0, [TODO])))
|
||||
self.assertEqual(routed_item(later_only, LastCut("v0.2.0", "", 3, [later_only])).id, 1)
|
||||
|
||||
def test_routes_past_an_item_a_waiting_item_blocks(self):
|
||||
todo = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 7 | 0.2.0 | | question | **Ask first.** | 4 | 3 | 5 | 10 | 1 | 1 by 9 | 30 |\n| 8 | 0.2.0 | 7 | | **Use the answer.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 30 |\n| 9 | 0.2.0 | 8 | | **Build on it.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 30 |\n| 3 | 0.2.0 | | | **Do the next thing.** | 4 | 2 | 3 | 7 | 3 | 1 by 9 | 25 |\n"
|
||||
self.assertEqual(routing.routed_item(todo, NO_CUT).id, 3)
|
||||
self.assertEqual(routing.routed_item(todo.replace("| question |", "| |"), NO_CUT).id, 7)
|
||||
self.assertEqual(routed_item(todo, NO_CUT).id, 3)
|
||||
self.assertEqual(routed_item(todo.replace("| question |", "| |"), NO_CUT).id, 7)
|
||||
first = "| 7 | 0.2.0 | | question | **Ask first.** | 4 | 3 | 5 | 10 | 1 | 1 by 9 | 30 |\n"
|
||||
self.assertEqual(routing.routed_item(todo.replace(first, "") + first, NO_CUT).id, 3)
|
||||
self.assertEqual(routed_item(todo.replace(first, "") + first, NO_CUT).id, 3)
|
||||
|
||||
def test_starts_a_chunk_on_the_rung_its_items_l_picks_below_the_projects_too(self):
|
||||
self.assertEqual(routing.first_route(LADDER, self.OPUS, routing.routed_item(TODO, NO_CUT)), Route(self.ONE_UP, 3, 4, 5))
|
||||
cheap = routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| 1 | 2 | 3 |"), NO_CUT)
|
||||
self.assertEqual(routing.first_route(LADDER, self.OPUS, routed_item(TODO, NO_CUT)), Route(self.ONE_UP, 3, 4, 5))
|
||||
cheap = routed_item(TODO.replace("| 4 | 2 | 3 |", "| 1 | 2 | 3 |"), NO_CUT)
|
||||
self.assertEqual(routing.first_route(LADDER, self.OPUS, cheap), Route(Rung("claude-sonnet-5-5", "high"), 3, 1, 5))
|
||||
self.assertEqual(routing.first_route(LADDER, self.OPUS, None), Route(self.OPUS))
|
||||
|
||||
@@ -1223,7 +1085,7 @@ class Routing(unittest.TestCase):
|
||||
|
||||
def test_routes_nothing_on_an_item_without_e_or_i(self):
|
||||
without_i = TODO.replace("| E | I | R |", "| E | R |").replace("|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|").replace("| 4 | 3 | 5 | 10 |", "| 4 | 3 | 10 |").replace("| 4 | 2 | 3 | 7 |", "| 4 | 2 | 7 |").replace("| 1 | 1 | 1 | 1 |", "| 1 | 1 | 1 |")
|
||||
self.assertIsNone(routing.routed_item(without_i, NO_CUT))
|
||||
self.assertIsNone(routed_item(without_i, NO_CUT))
|
||||
|
||||
def test_archives_the_route_as_a_json_worker_line_it_reads_back_field_by_field(self):
|
||||
route = Route(self.ONE_UP, 3, 4, 5)
|
||||
@@ -1245,7 +1107,7 @@ class Routing(unittest.TestCase):
|
||||
self.assertIsNone(route_from(line))
|
||||
|
||||
def test_keeps_a_chunks_route_or_its_archived_one_at_or_above_the_rung_its_item_picks_and_else_routes_afresh(self):
|
||||
item = routing.routed_item(TODO, NO_CUT)
|
||||
item = routed_item(TODO, NO_CUT)
|
||||
archived = Route(self.TWO_UP, 3, 4, 5)
|
||||
def never():
|
||||
raise AssertionError("not asked")
|
||||
@@ -1261,11 +1123,11 @@ class Routing(unittest.TestCase):
|
||||
|
||||
class RouteSources(unittest.TestCase):
|
||||
def test_routes_on_the_plan_item_and_says_why_it_routes_on_the_projects_rung(self):
|
||||
self.assertIsNone(chunk_start.plan_item(DefaultPlan("", NO_CUT), FakeEffects().effects()))
|
||||
self.assertEqual(chunk_start.plan_item(DefaultPlan(TODO, LastCut("v0.1.0", "", 3, [TODO])), FakeEffects().effects()).id, 3)
|
||||
self.assertIsNone(chunk_start.plan_item(DefaultPlan(TODO, LastCut("v0.2.0", "", 3, [TODO])), FakeEffects().effects()))
|
||||
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(""), NO_CUT), FakeEffects().effects()))
|
||||
self.assertEqual(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.1.0", "", 3, [TODO])), FakeEffects().effects()).id, 3)
|
||||
self.assertIsNone(chunk_start.plan_item(DefaultPlan(plan_of(TODO), LastCut("v0.2.0", "", 3, [TODO])), FakeEffects().effects()))
|
||||
unreadable = Failure("git show origin/main:todo.md printed text that is not UTF-8")
|
||||
for plan, said in ((DefaultPlan(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), NO_CUT), "routing on the project's rung: item 3's L 'x' is not a whole number from 1 to 4\n"), (DefaultPlan(unreadable, NO_CUT), f"routing on the project's rung: {unreadable.reason}\n"), (Failure("no origin remote"), "routing on the project's rung: no origin remote\n")):
|
||||
for plan, said in ((DefaultPlan(plan_of(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |")), NO_CUT), "routing on the project's rung: item 3's L 'x' is not a whole number from 1 to 4\n"), (DefaultPlan(unreadable, NO_CUT), f"routing on the project's rung: {unreadable.reason}\n"), (Failure("no origin remote"), "routing on the project's rung: no origin remote\n")):
|
||||
with self.subTest(said=said):
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
self.assertIsNone(chunk_start.plan_item(plan, FakeEffects().effects()))
|
||||
@@ -1280,6 +1142,17 @@ class RouteSources(unittest.TestCase):
|
||||
chunk_start.fetched_todo(a_loop(FakeEffects(git=git).effects(), root=root, paths=paths.paths_from(home)))
|
||||
self.assertEqual(stderr.getvalue(), f"{STAMP} {said}" if said else "")
|
||||
|
||||
def test_reads_the_changelog_the_default_branch_holds_through_the_loops_git(self):
|
||||
def git(*args, **options):
|
||||
answers = {"remote": "origin\n", "symbolic-ref": "origin/main\n", "show": f"what {args[-1]} holds\n"}
|
||||
return answers.get(args[0], "1\n")
|
||||
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
folder = configured(self, pathlib.Path(root))
|
||||
effects = dataclasses.replace(FakeEffects().effects(), git=git)
|
||||
held = chunk_start.fetched_plan(a_loop(effects, root=root, paths=paths.paths_from(folder.parents[1])))
|
||||
self.assertEqual(held.cut.changelog, "what origin/main:CHANGELOG.md holds\n")
|
||||
|
||||
def test_reads_a_plan_outside_the_checkout_as_it_stands_and_stops_without_a_config(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
folder = configured(self, pathlib.Path(root))
|
||||
@@ -1291,12 +1164,12 @@ class RouteSources(unittest.TestCase):
|
||||
self.assertEqual(stderr.getvalue(), "", "a plan git tracks hides no release")
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"folder:todo.md"'))
|
||||
(folder / "todo.md").write_text(TODO)
|
||||
self.assertEqual(chunk_start.fetched_todo(loop), TODO)
|
||||
self.assertEqual(chunk_start.fetched_todo(loop), plan_of(TODO))
|
||||
unread = Failure("no git")
|
||||
standing = a_loop(FakeEffects(git=["origin\n", "origin/main\n", unread, unread, unread, unread]).effects(), root=root, paths=paths.paths_from(folder.parents[1]))
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
held = chunk_start.fetched_plan(standing)
|
||||
self.assertEqual((held.todo, held.cut.todos_since, held.cut.changelog), (TODO, [], ""), "the plan as it stands, whatever git answers")
|
||||
self.assertEqual((held.todo, held.cut.todos_since, held.cut.changelog), (plan_of(TODO), [], ""), "the plan as it stands, whatever git answers")
|
||||
self.assertEqual(stderr.getvalue(), f"{STAMP} {UNSEEN_RELEASES}\n", "a release review loop-claude cannot call due is never skipped silently")
|
||||
config.unlink()
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
@@ -1335,6 +1208,63 @@ class RouteSources(unittest.TestCase):
|
||||
self.assertTrue(stderr.getvalue().startswith(f"{STAMP} routing the chunk afresh: could not read the archive"), stderr.getvalue())
|
||||
|
||||
|
||||
class ChunkSlots(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.home = pathlib.Path(temp.name)
|
||||
self.paths = paths.paths_from(self.home)
|
||||
self.addCleanup(self.release)
|
||||
|
||||
def held(self):
|
||||
"""This process's open files on a slot, each with whether an exec keeps it."""
|
||||
folder = self.home / chunk_slot.SLOTS
|
||||
found = {}
|
||||
for fd in os.listdir("/proc/self/fd"):
|
||||
with contextlib.suppress(OSError):
|
||||
if pathlib.Path(os.readlink(f"/proc/self/fd/{fd}")).is_relative_to(folder):
|
||||
found[os.readlink(f"/proc/self/fd/{fd}")] = os.get_inheritable(int(fd))
|
||||
return found
|
||||
|
||||
def release(self):
|
||||
folder = str(self.home / chunk_slot.SLOTS)
|
||||
for fd in os.listdir("/proc/self/fd"):
|
||||
with contextlib.suppress(OSError):
|
||||
if os.readlink(f"/proc/self/fd/{fd}").startswith(folder):
|
||||
os.close(int(fd))
|
||||
|
||||
def test_each_loop_takes_the_lowest_free_slot_and_names_its_session_after_it(self):
|
||||
loop_run = main.LoopRun(cycle_number=0, root=str(self.home / "code" / "proj"), task="do it", unfinished_evidence="")
|
||||
first, second = chunk_slot.slotted(loop_run, self.paths), chunk_slot.slotted(loop_run, self.paths)
|
||||
self.assertEqual((first[0], first[1].name), (dataclasses.replace(loop_run, slot=0), "A proj loop-claude"))
|
||||
self.assertEqual((second[0].slot, second[1].name), (1, "A proj loop-claude 2"))
|
||||
self.assertEqual(second[1], session.session_named("A proj loop-claude 2", self.paths.claude_code_transcripts))
|
||||
folder = self.home / ".local" / "state" / "loop-claude" / "proj"
|
||||
self.assertEqual(self.held(), {str(folder / "slot-0"): True, str(folder / "slot-1"): True})
|
||||
|
||||
def test_a_rerun_takes_the_lowest_free_slot_whose_session_is_open_before_a_lower_closed_one(self):
|
||||
loop_run = main.LoopRun(cycle_number=0, root=str(self.home / "code" / "proj"), task="do it", unfinished_evidence="")
|
||||
for name in ("A proj loop-claude 3", "A proj loop-claude 4"):
|
||||
transcript = self.paths.claude_code_transcripts / "-home-proj" / f"{session.session_named(name, self.paths.claude_code_transcripts).id}.jsonl"
|
||||
transcript.parent.mkdir(parents=True, exist_ok=True)
|
||||
transcript.write_text("")
|
||||
self.assertEqual([chunk_slot.slotted(loop_run, self.paths)[0].slot for _ in range(4)], [2, 3, 0, 1])
|
||||
|
||||
def test_a_reload_keeps_the_slot_it_is_handed_and_takes_no_other(self):
|
||||
loop_run = main.LoopRun(cycle_number=3, root="/srv/proj", task="do it", unfinished_evidence="", slot=2)
|
||||
self.assertEqual(chunk_slot.slotted(loop_run, self.paths), (loop_run, session.session_named("A srv/proj loop-claude 3", self.paths.claude_code_transcripts)))
|
||||
self.assertEqual(self.held(), {})
|
||||
|
||||
def test_says_why_it_takes_no_slot(self):
|
||||
loop_run = main.LoopRun(cycle_number=0, root="/srv/proj", task="do it", unfinished_evidence="")
|
||||
with unittest.mock.patch.object(chunk_slot, "MOST", 1):
|
||||
chunk_slot.slotted(loop_run, self.paths)
|
||||
self.assertEqual(chunk_slot.slotted(loop_run, self.paths), Failure(f"1 loops of this project are running already; `fuser {self.home}/.local/state/loop-claude/srv/proj/slot-*` names them"))
|
||||
(self.home / ".local" / "state" / "loop-claude").mkdir(parents=True, exist_ok=True)
|
||||
(self.home / ".local" / "state" / "loop-claude" / "other").write_text("")
|
||||
self.assertEqual(chunk_slot.slotted(dataclasses.replace(loop_run, root="/other"), self.paths), Failure(f"cannot take a slot in {self.home}/.local/state/loop-claude/other: File exists"))
|
||||
|
||||
|
||||
class Steps(unittest.TestCase):
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
|
||||
@@ -1344,11 +1274,6 @@ class Steps(unittest.TestCase):
|
||||
self.assertEqual(close.after_verdict(dataclasses.replace(run_with, unfinished_run=3), LADDER, self.OPUS, run.Concluded(Finished("x"), run_with.route)).unfinished_run, 0)
|
||||
self.assertEqual(close.after_verdict(run_with, LADDER, self.OPUS, run.Concluded(Unfinished("new", taken_in=TakenIn(highest_likelihood=4)), run_with.route)), dataclasses.replace(run_with, route=Route(Rung("claude-fable-5-2", "low"), unfinished=1), unfinished_evidence="new", unfinished_run=1))
|
||||
|
||||
def test_an_unfinished_chunk_keeps_the_items_its_verdict_found_taken_in_and_a_finished_one_drops_them(self):
|
||||
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=Route(self.OPUS), items_taken_in=(3,))
|
||||
self.assertEqual(close.after_verdict(run_with, LADDER, self.OPUS, run.Concluded(Unfinished("new", taken_in=TakenIn((3, 12))), run_with.route)).items_taken_in, (3, 12))
|
||||
self.assertEqual(close.after_verdict(run_with, LADDER, self.OPUS, run.Concluded(Finished("x"), run_with.route)).items_taken_in, ())
|
||||
|
||||
def test_steps_from_the_route_its_cycle_ended_on_which_a_ruling_may_have_raised(self):
|
||||
run_with = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=Route(self.OPUS, 3, 3, 4))
|
||||
raised = Route(Rung("claude-fable-5-2", "low"), 3, 3, 4, escalated_at=5)
|
||||
@@ -1404,12 +1329,6 @@ class Steps(unittest.TestCase):
|
||||
|
||||
|
||||
class ChunkFacts(unittest.TestCase):
|
||||
def test_names_the_routed_item_then_each_taken_in_once_by_its_tagline_on_the_default_branch(self):
|
||||
self.assertEqual(running_loops.taken_items(TODO, 3, (99, 3, 99)), (Taken(3, "Do the next thing."), Taken(99, "")))
|
||||
self.assertEqual(running_loops.taken_items(TODO, 0, (3,)), (Taken(3, "Do the next thing."),))
|
||||
self.assertEqual(running_loops.taken_items(Failure("no todo.md"), 3, ()), (Taken(3, ""),))
|
||||
self.assertEqual(running_loops.taken_items(TODO, 0, ()), ())
|
||||
|
||||
# The launcher beside which chunk_start finds /b/chunk-preflight.
|
||||
LAUNCHER = pathlib.Path("/b/loop-claude")
|
||||
|
||||
@@ -1611,6 +1530,14 @@ class Records(unittest.TestCase):
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards").mkdir(parents=True)
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards", "comments.md").write_text("# Comments\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith("From ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/goals-and-audience.md:\n# Goals\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/.claude/skills/larv-review/standards/comments.md:\n# Comments"))
|
||||
config.write_text(config.read_text().replace('"~/.claude/skills/larv-review/standards"', '"~/review-standards"'))
|
||||
pathlib.Path(claude_md.parents[1], "review-standards").mkdir()
|
||||
pathlib.Path(claude_md.parents[1], "review-standards", "quality.md").write_text("# Ours\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith("From ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/review-standards/quality.md:\n# Ours"), "the config's standards folder replaces the default")
|
||||
config.write_text(config.read_text().replace('"~/review-standards"', f'"{root}/standards"'))
|
||||
pathlib.Path(root, "standards").mkdir()
|
||||
pathlib.Path(root, "standards", "quality.md").write_text("# Elsewhere\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith(f"From {root}/standards/quality.md:\n# Elsewhere"), "a folder outside home is named in full")
|
||||
|
||||
config.write_text(config.read_text().replace('"checkout:AGENTS.md"', '"folder:AGENTS.md"').replace('"checkout:docs/decisions.md"', '"folder:log/decisions.md"'))
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).startswith("From ~/.claude/CLAUDE.md:\n# Global"), "the checkout's AGENTS.md and docs/decisions.md are its owners'")
|
||||
@@ -1628,7 +1555,7 @@ class Records(unittest.TestCase):
|
||||
claude_md.mkdir(parents=True)
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"CLAUDE.md in {claude_md.parent}: Is a directory - the judge cannot read the records."))
|
||||
pathlib.Path(root, "docs", "decisions.md").mkdir(parents=True)
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"decisions.md in {root}/docs: Is a directory - the judge cannot read the records."))
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"cannot read {root}/docs/decisions.md: Is a directory - the judge cannot read the records."))
|
||||
pathlib.Path(root, "AGENTS.md").write_bytes(b"# Rules\n\xff\n")
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
|
||||
|
||||
@@ -1826,13 +1753,13 @@ class ChunkItems(unittest.TestCase):
|
||||
self.assertEqual(chunk_items.named([prompt, written, mentioned]), ())
|
||||
|
||||
def test_takes_the_highest_l_and_e_plus_i_todo_md_scores_among_the_named_items(self):
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297 (L 1, E + I 2), 298, 400")], SCORED), TakenIn((297, 298, 400), 4, 7))
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 400")], SCORED), TakenIn((400,)))
|
||||
self.assertEqual(chunk_items.taken_in([], SCORED), TakenIn())
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297 (L 1, E + I 2), 298, 400")], plan_of(SCORED)), TakenIn(4, 7))
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 400")], plan_of(SCORED)), TakenIn())
|
||||
self.assertEqual(chunk_items.taken_in([], plan_of(SCORED)), TakenIn())
|
||||
|
||||
def test_names_the_items_at_no_level_where_todo_md_cannot_be_read(self):
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297")], Failure("no todo.md")), TakenIn((297,)))
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297")], "no items table"), TakenIn((297,)))
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297")], Failure("no todo.md")), TakenIn())
|
||||
self.assertEqual(chunk_items.taken_in([said("Chunk items: 297")], plan_of("no items table")), TakenIn())
|
||||
|
||||
|
||||
class Verdict(unittest.TestCase):
|
||||
@@ -1931,7 +1858,7 @@ class LoopRuns(unittest.TestCase):
|
||||
self.assertEqual(main.loop_run_from([main.RELOAD_FLAG, *handed], CWD, FakeEffects().effects()), Stop(1, f"the edited loop-claude cannot read the state the running one handed it, likely because the edit changed that handover; rerun loop-claude <task>. Handed: {' '.join(handed)}"))
|
||||
|
||||
def test_decodes_every_field_of_the_state_and_its_route(self):
|
||||
state = main.LoopRun(cycle_number=2, root="/r", task="do it", unfinished_evidence="old", route=Route(Rung("claude-fable-5-2", "low"), 3, 4, 5, 1, 7, 9), unfinished_run=2, items_taken_in=(12, 14))
|
||||
state = main.LoopRun(cycle_number=2, root="/r", task="do it", unfinished_evidence="old", route=Route(Rung("claude-fable-5-2", "low"), 3, 4, 5, 1, 7, 9), unfinished_run=2)
|
||||
self.assertEqual(reload.decode_handed(json.dumps(dataclasses.asdict(state))), state)
|
||||
self.assertEqual(set(reload.LOOP_RUN_FIELDS), {field.name for field in dataclasses.fields(main.LoopRun)})
|
||||
|
||||
@@ -1991,12 +1918,9 @@ class LoopRuns(unittest.TestCase):
|
||||
def test_decodes_a_state_from_before_a_field_with_a_default_joined_it(self):
|
||||
self.assertEqual(reload.decode_handed(json.dumps({"cycle_number": 3, "root": "/r", "task": "do it", "unfinished_evidence": ""})), main.LoopRun(3, "/r", "do it", ""))
|
||||
|
||||
def test_decodes_the_items_taken_in_as_a_tuple_of_ids(self):
|
||||
state = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", items_taken_in=(12, 14))
|
||||
self.assertEqual(reload.decode_handed(json.dumps(dataclasses.asdict(state))), state)
|
||||
for taken_in in ([12, "14"], [True], "12", {"12": 1}, "", {}):
|
||||
with self.subTest(taken_in=taken_in):
|
||||
self.assertIsNone(reload.decode_handed(json.dumps(dataclasses.asdict(state) | {"items_taken_in": taken_in})))
|
||||
def test_drops_the_items_taken_in_that_a_loop_started_before_0_11_0_hands_on(self):
|
||||
state = main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="")
|
||||
self.assertEqual(reload.decode_handed(json.dumps(dataclasses.asdict(state) | {"items_taken_in": [12, 14]})), state)
|
||||
|
||||
def test_stops_when_the_reload_cannot_start_python(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
@@ -2038,7 +1962,7 @@ class StopDms(unittest.TestCase):
|
||||
|
||||
def test_says_why_the_dm_of_a_stop_failed_after_the_reason(self):
|
||||
fake = FakeEffects(dm_failures=[Failure("cannot reach https://chat.example: timed out")])
|
||||
self.assertTrue(self.run_main([main.RELOAD_FLAG, "3"], fake)[1].endswith(f"Handed: 3\n{STAMP} could not DM you on Mattermost: cannot reach https://chat.example: timed out\n"))
|
||||
self.assertTrue(self.run_main([main.RELOAD_FLAG, "3"], fake)[1].endswith(f"Handed: 3\n{STAMP} could not DM you: cannot reach https://chat.example: timed out\n"))
|
||||
|
||||
def test_skips_the_dm_where_it_prints_its_help(self):
|
||||
for argv, code in (([], 1), (["--help"], 0)):
|
||||
@@ -2077,7 +2001,7 @@ class ExitContract(unittest.TestCase):
|
||||
def test_every_exit_1_stop_has_its_clause_in_help(self):
|
||||
read, git, premises_ = "a transcript cannot be read or archived", "git cannot start or finds no checkout", "no config names the checkout, its config cannot be read, or the goals file holds no premises"
|
||||
models_ = "the models file cannot be read or written"
|
||||
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], *(f"{folder}*.md" for folder in records.HUMAN_RULE_NAMES[1:]))
|
||||
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], f"{records.HUMAN_RULE_NAMES[1]}*.md", records.HUMAN_RULE_NAMES[2])
|
||||
unreadable = f"the goals file, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
|
||||
# Every Stop whose code is not a literal 0, 2 or 130, in source order: path, function, code, start of reason, its --help clause.
|
||||
clauses = [
|
||||
@@ -2095,6 +2019,7 @@ class ExitContract(unittest.TestCase):
|
||||
("cycle/run.py", "close", "1", "failure.reason", read),
|
||||
("cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
|
||||
("loop/close.py", "closed_cycle", "1", "failure.reason", read),
|
||||
("loop/main.py", "run_loop", "1", "held.reason", "its slot in the project cannot be taken"),
|
||||
("loop/main.py", "next_cycle", "1", "premises.reason", premises_),
|
||||
("loop/main.py", "next_cycle", "1", "records.reason", unreadable),
|
||||
("loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
|
||||
|
||||
@@ -6,9 +6,7 @@ from claude_code.tokens import Tokens
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class TakenIn:
|
||||
"""The todo.md items the worker names on its latest `Chunk items:` line, as cycle.chunk_items reads them. The item the chunk was routed on counts only where the worker names it."""
|
||||
# Their IDs; loop-inbox lists them.
|
||||
items: tuple[int, ...] = ()
|
||||
"""The levels of the todo.md items the worker names on its latest `Chunk items:` line, as cycle.chunk_items reads them. The item the chunk was routed on counts only where the worker names it."""
|
||||
# The highest L among them, 0 for none: an escalation steps up from the rung that L picks, and an unfinished verdict also raises the worker to it.
|
||||
highest_likelihood: int = 0
|
||||
# The highest E + I among them, 0 for none: after an unfinished verdict, it routes the next cycle's reviewers.
|
||||
|
||||
@@ -5,32 +5,23 @@ A change here, such as to how input reads a line, changes every tool that runs o
|
||||
import dataclasses
|
||||
import os
|
||||
import pathlib
|
||||
import select
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import termios
|
||||
import time
|
||||
import typing
|
||||
import uuid
|
||||
|
||||
from mattermost_dm.dm import dm, http_json
|
||||
from notifier.notify import Backend, BACKENDS, notify
|
||||
from failure import Failure
|
||||
from git_cli import git_repo
|
||||
from machine_load.memory import Memory, read_memory
|
||||
from project_config.settings import Notifier
|
||||
|
||||
# Seconds between a loop's looks for an answer from loop-inbox while it reads its terminal, and for the end of the claude loop-inbox opened.
|
||||
POLL_SECONDS = 0.5
|
||||
# Seconds before a Python script loop-claude runs is stopped, so a hung one, such as chunk-preflight, cannot hold the loop.
|
||||
PYTHON_TIMEOUT = 600
|
||||
|
||||
|
||||
class InputOr(typing.Protocol):
|
||||
"""Prints a prompt, then returns the line typed at the terminal, or the first answer that other returns, called every POLL_SECONDS. Raises EOFError where the input ends."""
|
||||
|
||||
def __call__[T](self, prompt: str, other: typing.Callable[[], T | None]) -> str | T: ...
|
||||
|
||||
|
||||
class Streaming(typing.Protocol):
|
||||
"""A started claude whose stream-json lines arrive as it works."""
|
||||
|
||||
@@ -41,26 +32,21 @@ class Streaming(typing.Protocol):
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Effects:
|
||||
# Whether the process with this pid still runs.
|
||||
alive: typing.Callable[[int], bool]
|
||||
claude: typing.Callable[[list[str], str, str], subprocess.CompletedProcess[str]]
|
||||
claude_on_terminal: typing.Callable[[list[str], str, dict[str, str]], int]
|
||||
# Drops what was typed on the terminal and not yet read.
|
||||
discard_typed: typing.Callable[[], None]
|
||||
# Sends the human a direct message on Mattermost, as `mattermost-dm` does; a Failure where it could not.
|
||||
# Sends the human a direct message through the notifier the project's config names, as `notify` does, for the project whose checkout holds the current directory; a Failure where it could not.
|
||||
dm: typing.Callable[[str], Failure | None]
|
||||
execv: typing.Callable[[str, list[str]], None]
|
||||
git: git_repo.Git
|
||||
input: typing.Callable[[str], str]
|
||||
input_or: InputOr
|
||||
# A date and time in the machine's zone, as `2026-10-28 11:46:01`. lilleman chose this spelling and local time over UTC on 2026-10-28, since the human reads these on their own clock.
|
||||
local_time: typing.Callable[[float], str]
|
||||
# The machine's memory; None where it cannot be read.
|
||||
memory: typing.Callable[[], Memory | None]
|
||||
new_id: typing.Callable[[], str]
|
||||
now: typing.Callable[[], float]
|
||||
on_terminal: typing.Callable[[], bool]
|
||||
pid: typing.Callable[[], int]
|
||||
# Runs a Python script in a directory, as run_python does.
|
||||
python: typing.Callable[[list[str], str], subprocess.CompletedProcess[str]]
|
||||
sleep: typing.Callable[[float], None]
|
||||
@@ -79,23 +65,20 @@ class StreamingClaude:
|
||||
return self.proc.wait()
|
||||
|
||||
|
||||
def system_effects() -> Effects:
|
||||
def system_effects(backends: typing.Mapping[Notifier, Backend[typing.Any]] = BACKENDS) -> Effects:
|
||||
"""The effects on this machine; `backends` are the notifiers loop-claude's DM can go through, where a test swaps in one that sends nowhere."""
|
||||
return Effects(
|
||||
alive=alive,
|
||||
claude=lambda args, cwd, stdin: subprocess.run(["claude", *args], capture_output=True, cwd=cwd, input=stdin, text=True),
|
||||
claude_on_terminal=claude_on_terminal,
|
||||
discard_typed=lambda: termios.tcflush(sys.stdin, termios.TCIFLUSH),
|
||||
dm=lambda text: dm(text, pathlib.Path.home(), http_json),
|
||||
dm=lambda text: notify(text, None, pathlib.Path.home(), backends),
|
||||
execv=os.execv,
|
||||
git=git_repo.git,
|
||||
input=input,
|
||||
input_or=input_or,
|
||||
local_time=lambda seconds: time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(seconds)),
|
||||
memory=read_memory,
|
||||
new_id=lambda: str(uuid.uuid4()),
|
||||
now=time.time,
|
||||
on_terminal=lambda: sys.stdin.isatty() and sys.stdout.isatty(),
|
||||
pid=os.getpid,
|
||||
python=lambda args, cwd: run_python(args, cwd, PYTHON_TIMEOUT),
|
||||
sleep=time.sleep,
|
||||
stream_claude=StreamingClaude,
|
||||
@@ -112,16 +95,6 @@ def claude_on_terminal(args: list[str], cwd: str, env: dict[str, str]) -> int:
|
||||
signal.signal(signal.SIGINT, previous)
|
||||
|
||||
|
||||
def alive(pid: int) -> bool:
|
||||
try:
|
||||
os.kill(pid, 0)
|
||||
except ProcessLookupError:
|
||||
return False
|
||||
except PermissionError:
|
||||
return True
|
||||
return True
|
||||
|
||||
|
||||
def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.CompletedProcess[str]:
|
||||
"""Runs a Python script in cwd. One that cannot start, or still runs after timeout seconds and is stopped, reads as exit 1, saying why on stderr."""
|
||||
command = [sys.executable, *args]
|
||||
@@ -133,21 +106,6 @@ def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.Complete
|
||||
return subprocess.CompletedProcess(command, 1, "", f"stopped after {timeout} s")
|
||||
|
||||
|
||||
def input_or[T](prompt: str, other: typing.Callable[[], T | None]) -> str | T:
|
||||
# On stderr, where input prints its prompt on a terminal.
|
||||
print(prompt, end="", file=sys.stderr, flush=True)
|
||||
while True:
|
||||
if select.select([sys.stdin], [], [], POLL_SECONDS)[0]:
|
||||
# On a terminal, one read returns at most one line, so nothing typed after it is buffered here, out of discard_typed's reach.
|
||||
line = os.read(sys.stdin.fileno(), 65536)
|
||||
if not line:
|
||||
raise EOFError
|
||||
return line.decode("utf-8", "replace").removesuffix("\n")
|
||||
if (got := other()) is not None:
|
||||
print(file=sys.stderr, flush=True) # Ends the prompt's line.
|
||||
return got
|
||||
|
||||
|
||||
def say(text: str, effects: Effects, *, stdout: bool = False) -> None:
|
||||
"""Prints text on stderr, or on stdout where stdout, opening the first line of words with the machine's local time. Blank lines before those words stay blank, and later lines get no time."""
|
||||
body = text.lstrip("\n")
|
||||
|
||||
@@ -4,7 +4,6 @@ import io
|
||||
import os
|
||||
import pathlib
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
@@ -58,7 +57,6 @@ class Said(unittest.TestCase):
|
||||
self.assertEqual(flushes, [f"{STAMP} hello\n"])
|
||||
|
||||
|
||||
|
||||
class LocalTime(unittest.TestCase):
|
||||
def test_renders_seconds_in_the_machines_zone(self):
|
||||
# A POSIX zone two hours ahead of UTC, so a time in UTC would read 14:13:20. Cleanups run last in, first out: the zone is restored before time.tzset makes the clock read it again.
|
||||
@@ -71,15 +69,6 @@ class LocalTime(unittest.TestCase):
|
||||
|
||||
|
||||
|
||||
class Alive(unittest.TestCase):
|
||||
def test_a_process_that_runs_is_alive_and_one_that_ended_is_not(self):
|
||||
ended = subprocess.Popen([sys.executable, "-c", "pass"])
|
||||
ended.wait()
|
||||
# Unless this process runs as root, it may not signal pid 1, which still runs.
|
||||
self.assertEqual([system_effects().alive(pid) for pid in (os.getpid(), ended.pid, 1)], [True, False, True])
|
||||
|
||||
|
||||
|
||||
class ClaudeOnTerminal(unittest.TestCase):
|
||||
def test_leaves_ctrl_c_to_claude_while_it_runs_and_returns_its_exit_code(self):
|
||||
caught = []
|
||||
|
||||
@@ -1,179 +0,0 @@
|
||||
"""What loop-inbox shows, and what each key does there: the core that main.py's curses screen runs.
|
||||
|
||||
How it shows the loops and a question was picked on 2026-10-28 by a bench of three readers seated as the README's
|
||||
audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it: a block per
|
||||
loop with its checkout's path and how long it has waited, and an answer prompt saying that Enter alone doesn't stop the loop.
|
||||
A second bench, on 2026-10-29, picked the running loops' section: below the waiting loops, a line per loop with its
|
||||
checkout and its number in the list above where it waits for an answer, then a line per item its chunk takes, with its ID and tagline.
|
||||
"""
|
||||
import dataclasses
|
||||
import textwrap
|
||||
import typing
|
||||
|
||||
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
|
||||
from loop_state.running_loops import RunningLoop, Taken
|
||||
from loop_state.waiting.talk import TALK
|
||||
|
||||
ENTER = "enter"
|
||||
BACKSPACE = "backspace"
|
||||
ESCAPE = "escape"
|
||||
# Lines of a question the list shows; the answer screen shows as much as fits.
|
||||
SHOWN_LINES = 2
|
||||
QUIT = "q"
|
||||
ANSWER_PROMPT = f"Answer ({TALK} opens claude; Enter alone, or Esc, goes back, and the loop keeps waiting):"
|
||||
INDENT = " "
|
||||
ELLIPSIS = "…"
|
||||
NARROWEST = 20
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Listing:
|
||||
"""The waiting and running loops as they were when the human began typing a number, so a loop's number doesn't change while they type it."""
|
||||
shown: tuple[Ask, ...] = ()
|
||||
typed: str = ""
|
||||
note: str = ""
|
||||
running: tuple[RunningLoop, ...] = ()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Answering:
|
||||
ask: Ask
|
||||
typed: str = ""
|
||||
|
||||
|
||||
Screen = Listing | Answering
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Send:
|
||||
ask: Ask
|
||||
text: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Open:
|
||||
"""Opens the worker's claude session for /talk."""
|
||||
ask: Ask
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Quit:
|
||||
pass
|
||||
|
||||
|
||||
def pressed(screen: Screen, key: str) -> Screen | Send | Open | Quit:
|
||||
"""What follows key, which is ENTER, BACKSPACE, ESCAPE or one character typed."""
|
||||
match screen:
|
||||
case Listing(shown, typed):
|
||||
if key == QUIT and not typed:
|
||||
return Quit()
|
||||
if key == ENTER:
|
||||
return picked(shown, typed)
|
||||
if key == BACKSPACE:
|
||||
return dataclasses.replace(screen, typed=typed[:-1], note="")
|
||||
# isdigit would also take "²", which int() rejects.
|
||||
return dataclasses.replace(screen, typed=typed + key, note="") if key.isdecimal() else screen
|
||||
case Answering(ask, typed):
|
||||
if key == ESCAPE or (key == ENTER and not typed.strip()):
|
||||
return Listing()
|
||||
if key == ENTER:
|
||||
return Open(ask) if typed.strip() == TALK else Send(ask, typed.strip())
|
||||
if key == BACKSPACE:
|
||||
return Answering(ask, typed[:-1])
|
||||
return Answering(ask, typed + key) if len(key) == 1 and key.isprintable() else screen
|
||||
case _:
|
||||
typing.assert_never(screen)
|
||||
|
||||
|
||||
def picked(shown: tuple[Ask, ...], typed: str) -> Listing | Answering:
|
||||
if not typed:
|
||||
return Listing()
|
||||
number = int(typed)
|
||||
if not 1 <= number <= len(shown):
|
||||
return Listing(note=f"No loop has the number {number}.")
|
||||
ask = shown[number - 1]
|
||||
if not isinstance(ask.state, Asking):
|
||||
return Listing(note=f"{ask.root}: claude is open {where_open(ask.state)}; answer there.")
|
||||
return Answering(ask)
|
||||
|
||||
|
||||
def where_open(state: OpenOnTerminal | OpenInInbox) -> str:
|
||||
return "in loop-inbox" if isinstance(state, OpenInInbox) else "on its terminal"
|
||||
|
||||
|
||||
def listing_lines(screen: Listing, now: float, local_time: typing.Callable[[float], str], width: int) -> tuple[list[str], list[str]]:
|
||||
"""The list, in lines of at most width characters, and its foot: the note, what the keys do, and the prompt for a number."""
|
||||
count = len(screen.shown)
|
||||
head = "No loop waits for you." if not count else "1 loop waits for you." if count == 1 else f"{count} loops wait for you, oldest first."
|
||||
lines = [*wrapped(head, width), ""]
|
||||
for number, ask in enumerate(screen.shown, 1):
|
||||
state = "" if isinstance(ask.state, Asking) else f"; claude is open {where_open(ask.state)}"
|
||||
lines += wrapped(f"[{number}] {ask.root}, waiting since {local_time(ask.asked)} ({waited(now - ask.asked)}){state}", width)
|
||||
lines += cut(wrapped(ask.question, width - len(INDENT) - len(ELLIPSIS)), SHOWN_LINES)
|
||||
lines.append("")
|
||||
lines += running_lines(screen.running, screen.shown, width)
|
||||
ask_for = "Type a number and Enter to answer that loop; " if count else ""
|
||||
return lines, [*wrapped(screen.note, width), *wrapped(f"{ask_for}{QUIT} quits loop-inbox, and the loops keep waiting.", width), *typed_after(">", screen.typed, width)]
|
||||
|
||||
|
||||
def running_lines(running: tuple[RunningLoop, ...], shown: tuple[Ask, ...], width: int) -> list[str]:
|
||||
"""Each running loop's checkout, with its number in the waiting list where it waits for an answer, and a line per item its chunk takes."""
|
||||
if not running:
|
||||
return ["No loop runs."]
|
||||
numbers = {ask.session: number for number, ask in enumerate(shown, 1)}
|
||||
lines = wrapped(f"Running: {len(running)} loop{'s' if len(running) > 1 else ''}", width)
|
||||
for loop in running:
|
||||
waits_as = f", waiting as [{numbers[loop.session]}]" if loop.session in numbers else ""
|
||||
lines += wrapped(f"- {loop.root}{waits_as}", width)
|
||||
for item in loop.items or (None,):
|
||||
lines += cut(wrapped(item_line(item), width - len(INDENT) - len(ELLIPSIS)), 1)
|
||||
return lines
|
||||
|
||||
|
||||
def item_line(item: Taken | None) -> str:
|
||||
if item is None:
|
||||
return "no todo.md item yet"
|
||||
return f"item {item.id}: {item.tagline}" if item.tagline else f"item {item.id}"
|
||||
|
||||
|
||||
def answering_lines(screen: Answering, now: float, local_time: typing.Callable[[float], str], width: int) -> tuple[list[str], list[str]]:
|
||||
"""The question, in lines of at most width characters, and its foot, the prompt for the answer."""
|
||||
ask = screen.ask
|
||||
head = f"{ask.root}, waiting since {local_time(ask.asked)} ({waited(now - ask.asked)}):"
|
||||
return [*wrapped(head, width), "", *wrapped(ask.question, width), ""], typed_after(ANSWER_PROMPT, screen.typed, width)
|
||||
|
||||
|
||||
def fitted(lines: list[str], foot: list[str], height: int) -> list[str]:
|
||||
"""lines, then foot, cut to height: lines lose their end first, and the cut is marked with an ellipsis."""
|
||||
if len(lines) + len(foot) <= height:
|
||||
return [*lines, *foot]
|
||||
return [*lines[: max(height - len(foot) - 1, 0)], ELLIPSIS, *foot][-height:]
|
||||
|
||||
|
||||
def wrapped(text: str, width: int) -> list[str]:
|
||||
return [line for paragraph in text.splitlines() for line in textwrap.wrap(paragraph, max(width, NARROWEST)) or [""]]
|
||||
|
||||
|
||||
def typed_after(prompt: str, typed: str, width: int) -> list[str]:
|
||||
"""prompt wrapped to width, then what the human typed after it, cut every width characters so that each space typed shows."""
|
||||
*lines, last = wrapped(prompt, width)
|
||||
line = f"{last} {typed}"
|
||||
step = max(width, NARROWEST)
|
||||
return [*lines, *(line[start : start + step] for start in range(0, len(line), step))]
|
||||
|
||||
|
||||
def cut(lines: list[str], count: int) -> list[str]:
|
||||
"""The first count lines, indented; a cut is marked with an ellipsis."""
|
||||
shown = [f"{INDENT}{line}" for line in lines[:count]]
|
||||
return [*shown[:-1], f"{shown[-1]}{ELLIPSIS}"] if len(lines) > count else shown
|
||||
|
||||
|
||||
def waited(seconds: float) -> str:
|
||||
minutes = int(seconds // 60)
|
||||
if minutes < 60:
|
||||
return f"{minutes} min"
|
||||
hours, minutes = divmod(minutes, 60)
|
||||
if hours < 24:
|
||||
return f"{hours} h {minutes} min"
|
||||
days, hours = divmod(hours, 24)
|
||||
return f"{days} d {hours} h"
|
||||
@@ -1,189 +0,0 @@
|
||||
"""Show the interrupts of every loop-claude on this machine, oldest first, and answer each one here.
|
||||
Below them, list every loop-claude that runs and the todo.md items its chunk takes.
|
||||
|
||||
usage: loop-inbox
|
||||
|
||||
Each loop-claude lists its interrupt here, as well as on its own terminal, until it is answered or
|
||||
the loop stops. The list shows each loop's checkout, when it asked and how long it has waited, and
|
||||
the question's first lines; it refreshes every second. Type a loop's number and Enter to see as much
|
||||
of its question as fits; the loop's terminal shows it whole. Answer as on the loop's terminal:
|
||||
|
||||
- A line and Enter sends it to that loop, which goes on with it. Of a pasted answer, only the first
|
||||
line is sent, and the rest is dropped; a longer answer goes through /talk.
|
||||
- /talk opens the worker's claude session here, with `claude --resume`, as /talk does on the loop's
|
||||
terminal. Once that claude ends, the loop goes on if you typed there, and the judge rules on what
|
||||
you typed; if you typed no answer, the loop stops.
|
||||
- Enter alone, or Esc, goes back to the list; unlike on the loop's terminal, it doesn't stop the loop.
|
||||
|
||||
The loop takes whichever answer comes first, here or on its terminal, so it keeps working with no
|
||||
loop-inbox running. A loop with claude open, for a release ready to cut, the routing calls or a
|
||||
/talk, says where, and is answered there. A loop whose process is gone drops off the list. A loop
|
||||
asking for its project's model, as on a project's first run, asks on its own terminal only. q quits
|
||||
loop-inbox; the loops keep waiting.
|
||||
|
||||
Below the questions, loop-inbox lists each running loop: its checkout, its number in the list
|
||||
above where it waits for an answer, and a line per todo.md item its chunk takes, with the item's
|
||||
tagline on the default branch. A loop whose process is gone drops off this list too.
|
||||
|
||||
The loops' questions are files in ~/.local/state/loop-claude, read and written as
|
||||
bin/loop_state/waiting/ describes; the running loops are files beside them, as
|
||||
bin/loop_state/running_loops.py describes.
|
||||
|
||||
Exit 2 when stdin or stdout is not a terminal, or on an unknown argument.
|
||||
"""
|
||||
import contextlib
|
||||
import curses
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from loop_inbox.inbox import Answering, answering_lines, BACKSPACE, ENTER, ESCAPE, fitted, Listing, listing_lines, Open, pressed, Quit, Screen, Send
|
||||
from loop_state.waiting.ask import Ask, Asking, read_ask
|
||||
from loop_state.waiting.listing import ask_file, drop_ended, waiting
|
||||
from loop_state.waiting.talk import claim_talk, MAKE_WAY_SECONDS
|
||||
from loop_state.waiting.answers import ClaudeEnded, send, Typed
|
||||
from loop_state.running_loops import drop_ended_loops, running_loops
|
||||
from loop_effects.effects import Effects, system_effects
|
||||
from failure import Failure
|
||||
from loop_state.hand_over import hand_over
|
||||
from loop_state.paths import Paths, paths_from
|
||||
from loop_state.session_lock import running
|
||||
|
||||
USAGE = "usage: loop-inbox"
|
||||
# Milliseconds between refreshes of the list while no key is pressed.
|
||||
REFRESH_MS = 1000
|
||||
KEYS = {"\n": ENTER, "\r": ENTER, curses.KEY_ENTER: ENTER, "\x7f": BACKSPACE, "\b": BACKSPACE, curses.KEY_BACKSPACE: BACKSPACE, "\x1b": ESCAPE}
|
||||
|
||||
|
||||
def main(argv: list[str], home: pathlib.Path) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
if argv:
|
||||
print(f"loop-inbox: unknown argument {argv[0]}; {USAGE}", file=sys.stderr)
|
||||
return 2
|
||||
if not (sys.stdin.isatty() and sys.stdout.isatty()):
|
||||
print("loop-inbox: stdin or stdout is not a terminal; run it on one", file=sys.stderr)
|
||||
return 2
|
||||
# curses may hold keys it has read ahead, which only flushinp drops.
|
||||
effects = dataclasses.replace(system_effects(), discard_typed=curses.flushinp)
|
||||
try:
|
||||
curses.wrapper(lambda window: run(window, lambda: off_screen(window), paths_from(home), effects))
|
||||
except KeyboardInterrupt:
|
||||
pass
|
||||
return 0
|
||||
|
||||
|
||||
def run(window: curses.window, screen_off: typing.Callable[[], typing.ContextManager[None]], paths: Paths, effects: Effects) -> None:
|
||||
folder = paths.waiting
|
||||
window.timeout(REFRESH_MS)
|
||||
screen: Screen = Listing()
|
||||
while True:
|
||||
drop_ended(folder)
|
||||
drop_ended_loops(folder)
|
||||
screen = entered(screen, refreshed(screen, folder), effects)
|
||||
draw(window, screen, effects)
|
||||
try:
|
||||
key = window.get_wch()
|
||||
except curses.error:
|
||||
continue # No key within REFRESH_MS.
|
||||
after: Screen
|
||||
match pressed(screen, key_name(key)):
|
||||
case Quit():
|
||||
return
|
||||
case Send(ask, text):
|
||||
after = Listing(note=sent(folder, ask, text))
|
||||
case Open(ask):
|
||||
after = Listing(note=opened(screen_off, paths, ask, effects))
|
||||
case Listing() | Answering() as next_screen:
|
||||
after = next_screen
|
||||
screen = entered(screen, after, effects)
|
||||
|
||||
|
||||
def entered(before: Screen, after: Screen, effects: Effects) -> Screen:
|
||||
"""after, the screen that follows before. Leaving the answer screen drops the keys typed ahead, since on the list the rest of a pasted answer would pick a loop and answer it."""
|
||||
if isinstance(before, Answering) and isinstance(after, Listing):
|
||||
effects.discard_typed()
|
||||
return after
|
||||
|
||||
|
||||
def key_name(key: str | int) -> str:
|
||||
"""inbox's name for a key curses read; an empty string for a key loop-inbox has no use for, such as an arrow."""
|
||||
return KEYS.get(key, key if isinstance(key, str) else "")
|
||||
|
||||
|
||||
def refreshed(screen: Screen, folder: pathlib.Path) -> Screen:
|
||||
"""screen with the loops as they wait and run now, unless the human is typing a number; a question that no longer waits leaves the answer screen."""
|
||||
match screen:
|
||||
case Listing(_, "", note):
|
||||
return Listing(tuple(waiting(folder)), "", note, tuple(running_loops(folder)))
|
||||
case Answering(ask) if not still_waits(folder, ask):
|
||||
return Listing(note=no_longer_waits(ask))
|
||||
return screen
|
||||
|
||||
|
||||
def draw(window: curses.window, screen: Screen, effects: Effects) -> None:
|
||||
height, columns = window.getmaxyx()
|
||||
# The screen's last cell cannot be written without an error, so lines leave the last column empty.
|
||||
width = columns - 1
|
||||
now = effects.now()
|
||||
lines, foot = listing_lines(screen, now, effects.local_time, width) if isinstance(screen, Listing) else answering_lines(screen, now, effects.local_time, width)
|
||||
window.erase()
|
||||
for row, line in enumerate(fitted(lines, foot, height)):
|
||||
# addnstr counts characters, not cells, so a line of wide characters, such as emoji, can still run into the last cell.
|
||||
with contextlib.suppress(curses.error):
|
||||
window.addnstr(row, 0, line, width)
|
||||
window.refresh()
|
||||
|
||||
|
||||
def still_waits(folder: pathlib.Path, ask: Ask) -> bool:
|
||||
"""Whether ask's loop still runs and still waits for an answer from loop-inbox."""
|
||||
now = read_ask(ask_file(folder, ask.session))
|
||||
return now is not None and now.id == ask.id and isinstance(now.state, Asking) and running(folder, ask.session)
|
||||
|
||||
|
||||
def no_longer_waits(ask: Ask) -> str:
|
||||
return f"{ask.root} no longer waits for that answer: it was answered elsewhere, or stopped."
|
||||
|
||||
|
||||
def sent(folder: pathlib.Path, ask: Ask, text: str) -> str:
|
||||
"""Sends text to the loop that asked ask, and says what came of it."""
|
||||
if not still_waits(folder, ask):
|
||||
return no_longer_waits(ask)
|
||||
if unsent := send(folder, ask, Typed(text)):
|
||||
return f"Could not send the answer to {ask.root}: {unsent.reason}"
|
||||
return f"Sent to {ask.root}."
|
||||
|
||||
|
||||
def opened(screen_off: typing.Callable[[], typing.ContextManager[None]], paths: Paths, ask: Ask, effects: Effects) -> str:
|
||||
"""Opens the worker's claude session on this terminal, inside screen_off, once the loop has made way for it, and says what came of it."""
|
||||
folder = paths.waiting
|
||||
if not (isinstance(ask.state, Asking) and still_waits(folder, ask)):
|
||||
return no_longer_waits(ask)
|
||||
claimed = claim_talk(folder, ask, effects.pid(), effects.now, effects.sleep)
|
||||
if isinstance(claimed, Failure):
|
||||
return f"Could not open claude for {ask.root}: {claimed.reason}"
|
||||
if not claimed:
|
||||
return f"Could not open claude for {ask.root}: the loop was answered elsewhere or stopped, or didn't respond within {MAKE_WAY_SECONDS:g} s. If it is still listed, pick it again."
|
||||
with screen_off():
|
||||
try:
|
||||
unstarted = hand_over(ask.state.talk, effects)
|
||||
finally:
|
||||
unsent = send(folder, ask, ClaudeEnded())
|
||||
# The loop goes on only where the human typed in the worker's session, as interrupt.human_typed checks.
|
||||
said = f"Could not start claude for {ask.root}: {unstarted.reason}. The loop stops." if unstarted else f"claude for {ask.root} has ended; the loop goes on if you typed there, and stops if you didn't."
|
||||
# The loop also stops waiting for claude once loop-inbox's process ends.
|
||||
return f"{said} Could not tell the loop that claude ended: {unsent.reason}; it waits until you quit loop-inbox." if unsent else said
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def off_screen(window: curses.window) -> typing.Iterator[None]:
|
||||
"""Hands the terminal to another program, and draws loop-inbox again once it ends."""
|
||||
curses.def_prog_mode()
|
||||
curses.endwin()
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
curses.reset_prog_mode()
|
||||
window.refresh()
|
||||
@@ -1,610 +0,0 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from loop_state.waiting.answers import answered, claude_ended, ClaudeEnded, ClaudeOpening, send, Typed
|
||||
from loop_inbox.inbox import Answering, BACKSPACE, ENTER, ESCAPE, Listing, Open, Quit, Send
|
||||
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal, read_ask
|
||||
from loop_state.waiting.listing import ask_file, drop_ended, listed, publish, waiting, withdraw
|
||||
from loop_state.waiting.talk import claim_talk, MAKE_WAY_SECONDS
|
||||
from loop_state.hand_over import ClaudeCommand
|
||||
from failure import Failure
|
||||
from loop_inbox import inbox, main
|
||||
from loop_state.paths import paths_from
|
||||
from loop_state import running_loops, session_lock
|
||||
from loop_state.running_loops import RunningLoop, Taken
|
||||
from loop_effects.effects import system_effects
|
||||
|
||||
ASKING = Asking(ClaudeCommand(["--resume", "s"], "/c", {}))
|
||||
# The pid of this loop-inbox.
|
||||
INBOX = 4343
|
||||
ANSWERED_ON_TERMINAL = object()
|
||||
|
||||
|
||||
def asked(session, root, question="Which one?", at=100.0, state=ASKING):
|
||||
return Ask(f"ask-{session}", session, root, question, at, state)
|
||||
|
||||
|
||||
def loops_hold(test, folder, *sessions):
|
||||
"""Holds each session's lock until the test ends, as a running loop does."""
|
||||
for session in sessions:
|
||||
test.enterContext(session_lock.held(folder, session))
|
||||
|
||||
|
||||
def asks_and_answers(folder):
|
||||
return sorted(path.name for path in folder.iterdir() if path.suffix != ".lock")
|
||||
|
||||
|
||||
def keyed(screen, *keys):
|
||||
for key in keys:
|
||||
screen = inbox.pressed(screen, key)
|
||||
return screen
|
||||
|
||||
|
||||
class OutOfKeys(Exception):
|
||||
pass
|
||||
|
||||
|
||||
class Window:
|
||||
"""A curses window that records the lines drawn on it, and hands out keys in turn, running each callable among them as it comes."""
|
||||
|
||||
def __init__(self, keys=(), height=24, width=80):
|
||||
self.keys, self.height, self.width = list(keys), height, width
|
||||
self.lines = {}
|
||||
|
||||
def getmaxyx(self):
|
||||
return self.height, self.width
|
||||
|
||||
def timeout(self, milliseconds):
|
||||
pass
|
||||
|
||||
def get_wch(self):
|
||||
while self.keys and callable(self.keys[0]):
|
||||
self.keys.pop(0)()
|
||||
if not self.keys:
|
||||
raise OutOfKeys
|
||||
return self.keys.pop(0)
|
||||
|
||||
def drop_typed(self):
|
||||
"""Drops the keys not yet read, as curses.flushinp does."""
|
||||
self.keys.clear()
|
||||
|
||||
def erase(self):
|
||||
self.lines = {}
|
||||
|
||||
def addnstr(self, row, column, text, count):
|
||||
self.lines[row] = text[:count]
|
||||
|
||||
def refresh(self):
|
||||
pass
|
||||
|
||||
|
||||
class Answers(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.folder = pathlib.Path(tempfile.mkdtemp())
|
||||
self.addCleanup(shutil.rmtree, self.folder)
|
||||
loops_hold(self, self.folder, "s1", "s2")
|
||||
|
||||
def answer(self, number, text):
|
||||
"""Picks loop number from the list as it waits now and types text to it, as the human does in loop-inbox."""
|
||||
action = keyed(Listing(tuple(waiting(self.folder))), *number, ENTER, *text, ENTER)
|
||||
self.assertIsInstance(action, Send)
|
||||
return main.sent(self.folder, action.ask, action.text)
|
||||
|
||||
def test_two_waiting_loops_each_get_their_own_answer(self):
|
||||
log, bender = asked("s1", "/code/log", at=100), asked("s2", "/code/bender", at=200)
|
||||
for ask in (bender, log):
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(self.answer("2", "Use B."), "Sent to /code/bender.")
|
||||
self.assertEqual(self.answer("1", "Use A."), "Sent to /code/log.")
|
||||
self.assertEqual((answered(self.folder, log), answered(self.folder, bender)), (Typed("Use A."), Typed("Use B.")))
|
||||
|
||||
def test_an_answer_to_a_loop_that_stopped_waiting_reaches_no_loop(self):
|
||||
log, bender = asked("s1", "/code/log", at=100), asked("s2", "/code/bender", at=200)
|
||||
for ask in (log, bender):
|
||||
publish(self.folder, ask)
|
||||
picked = keyed(Listing(tuple(waiting(self.folder))), "1", ENTER, "A", ENTER)
|
||||
# log is answered on its terminal before the answer typed here is sent; bender is now first.
|
||||
withdraw(self.folder, "s1")
|
||||
self.assertEqual(main.sent(self.folder, picked.ask, picked.text), "/code/log no longer waits for that answer: it was answered elsewhere, or stopped.")
|
||||
self.assertEqual(asks_and_answers(self.folder), ["s2.json"])
|
||||
|
||||
def test_the_list_shows_the_loops_still_waiting_and_keeps_its_note(self):
|
||||
log = asked("s1", "/code/log")
|
||||
for ask in (log, asked("s3", "/code/bender")):
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(main.refreshed(Listing(note="Sent to /a."), self.folder), Listing((log,), "", "Sent to /a."))
|
||||
|
||||
def test_the_list_shows_the_loops_running_now(self):
|
||||
self.enterContext(running_loops.shown_running(self.folder, "s9", "/code/web", system_effects()))
|
||||
self.assertEqual(main.refreshed(Listing(), self.folder), Listing(running=(RunningLoop("s9", "/code/web", ()),)))
|
||||
|
||||
def test_a_number_picks_the_loop_it_had_when_the_human_began_typing_it(self):
|
||||
log, bender = asked("s1", "/code/log", at=100), asked("s2", "/code/bender", at=200)
|
||||
typing = keyed(Listing((log, bender)), "2")
|
||||
publish(self.folder, bender)
|
||||
self.assertEqual(main.refreshed(typing, self.folder), typing)
|
||||
self.assertEqual(inbox.pressed(typing, ENTER), Answering(bender))
|
||||
|
||||
def test_a_loop_whose_claude_is_open_takes_no_answer_here(self):
|
||||
for state, where in ((OpenOnTerminal(), "on its terminal"), (OpenInInbox(7), "in loop-inbox")):
|
||||
with self.subTest(where=where):
|
||||
self.assertEqual(keyed(Listing((asked("s1", "/code/log", state=state),)), "1", ENTER), Listing(note=f"/code/log: claude is open {where}; answer there."))
|
||||
|
||||
def test_an_ask_file_says_when_the_loop_asked_as_an_iso_utc_datetime(self):
|
||||
ask = asked("s1", "/code/log", at=100)
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(json.loads(ask_file(self.folder, "s1").read_text())["asked"], "1970-01-01T00:01:40Z")
|
||||
self.assertEqual(read_ask(ask_file(self.folder, "s1")), ask)
|
||||
|
||||
def test_an_answer_screen_leaves_once_its_loop_no_longer_waits(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(main.refreshed(Answering(ask, "Us"), self.folder), Answering(ask, "Us"))
|
||||
publish(self.folder, dataclasses.replace(ask, id="a later ask"))
|
||||
self.assertEqual(main.refreshed(Answering(ask, "Us"), self.folder), Listing(note="/code/log no longer waits for that answer: it was answered elsewhere, or stopped."))
|
||||
|
||||
def test_an_answer_screen_leaves_once_its_loop_ends_though_its_ask_stays_on_disk(self):
|
||||
ask = asked("s3", "/code/bender")
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(main.refreshed(Answering(ask, "Us"), self.folder), Listing(note="/code/bender no longer waits for that answer: it was answered elsewhere, or stopped."))
|
||||
|
||||
def claim(self, ask, loop_does):
|
||||
"""claim_talk's result for ask, and the seconds it waited; loop_does acts as the loop at claim_talk's first wait."""
|
||||
tenths = [0]
|
||||
def sleep(seconds):
|
||||
if not tenths[0]:
|
||||
loop_does()
|
||||
tenths[0] += round(seconds * 10)
|
||||
return claim_talk(self.folder, ask, INBOX, lambda: tenths[0] / 10, sleep), tenths[0] / 10
|
||||
|
||||
def test_talk_opens_claude_only_once_the_loop_has_made_way_for_this_loop_inbox(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
def made_way_for_the_claim():
|
||||
claim = answered(self.folder, ask)
|
||||
if isinstance(claim, ClaudeOpening):
|
||||
publish(self.folder, dataclasses.replace(ask, state=OpenInInbox(claim.pid)))
|
||||
for loop_does, claimed in (
|
||||
(made_way_for_the_claim, (True, 0.1)),
|
||||
(lambda: withdraw(self.folder, "s1"), (False, 0.1)),
|
||||
(lambda: publish(self.folder, dataclasses.replace(ask, state=OpenOnTerminal())), (False, 0.1)),
|
||||
(lambda: publish(self.folder, dataclasses.replace(ask, state=OpenInInbox(7))), (False, 0.1)),
|
||||
(lambda: None, (False, MAKE_WAY_SECONDS)),
|
||||
):
|
||||
with self.subTest(claimed=claimed):
|
||||
publish(self.folder, ask)
|
||||
self.assertEqual(self.claim(ask, loop_does), claimed)
|
||||
|
||||
def test_a_claim_the_loop_did_not_make_way_for_in_time_is_taken_back(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
publish(self.folder, ask)
|
||||
self.claim(ask, lambda: None)
|
||||
# A loop that reads it late ends its wait at once, as for a claude that has ended.
|
||||
self.assertEqual((answered(self.folder, ask), claude_ended(self.folder, ask)), (None, True))
|
||||
|
||||
|
||||
def never_opens(args, cwd, env):
|
||||
raise AssertionError("claude opened")
|
||||
|
||||
|
||||
class Opens(unittest.TestCase):
|
||||
def setUp(self):
|
||||
home = pathlib.Path(tempfile.mkdtemp())
|
||||
self.addCleanup(shutil.rmtree, home)
|
||||
self.paths = paths_from(home)
|
||||
self.ask = asked("s1", "/code/log")
|
||||
loops_hold(self, self.paths.waiting, "s1")
|
||||
publish(self.paths.waiting, self.ask)
|
||||
|
||||
def open(self, claude, loop_shows=OpenInInbox(INBOX)):
|
||||
"""What /talk in loop-inbox says for self.ask, whose loop shows loop_shows once claim_talk has asked it to make way; claude stands in for claude_on_terminal. Sets self.ended to whether it told the loop that claude ended."""
|
||||
def loop_looks(_):
|
||||
publish(self.paths.waiting, dataclasses.replace(self.ask, state=loop_shows))
|
||||
effects = dataclasses.replace(system_effects(), claude_on_terminal=claude, git=lambda *args, **kwargs: Failure("not a checkout"), now=lambda: 0.0, pid=lambda: INBOX, sleep=loop_looks)
|
||||
try:
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
return main.opened(contextlib.nullcontext, self.paths, self.ask, effects)
|
||||
finally:
|
||||
self.ended = claude_ended(self.paths.waiting, self.ask)
|
||||
|
||||
def test_tells_the_loop_once_claude_ends_or_cannot_start_and_says_what_the_loop_does(self):
|
||||
def unstarted(args, cwd, env):
|
||||
raise OSError(2, "No such file or directory")
|
||||
for claude, said in (
|
||||
(lambda args, cwd, env: 0, "claude for /code/log has ended; the loop goes on if you typed there, and stops if you didn't."),
|
||||
(unstarted, "Could not start claude for /code/log: No such file or directory. The loop stops."),
|
||||
):
|
||||
with self.subTest(said=said):
|
||||
publish(self.paths.waiting, self.ask)
|
||||
self.assertEqual(self.open(claude), said)
|
||||
self.assertTrue(self.ended)
|
||||
|
||||
def test_says_the_loop_waits_for_loop_inbox_to_quit_where_it_cannot_tell_it_that_claude_ended(self):
|
||||
def folder_lost(args, cwd, env):
|
||||
shutil.rmtree(self.paths.waiting)
|
||||
self.paths.waiting.write_text("")
|
||||
said = "claude for /code/log has ended; the loop goes on if you typed there, and stops if you didn't. Could not tell the loop that claude ended: Not a directory; it waits until you quit loop-inbox."
|
||||
self.assertEqual(self.open(folder_lost), said)
|
||||
|
||||
def test_opens_no_claude_for_a_loop_that_takes_talk_on_its_terminal_first(self):
|
||||
said = "Could not open claude for /code/log: the loop was answered elsewhere or stopped, or didn't respond within 5 s. If it is still listed, pick it again."
|
||||
self.assertEqual(self.open(never_opens, loop_shows=OpenOnTerminal()), said)
|
||||
|
||||
def test_opens_no_claude_and_sends_nothing_to_a_loop_that_no_longer_waits(self):
|
||||
withdraw(self.paths.waiting, "s1")
|
||||
self.assertEqual(self.open(never_opens), "/code/log no longer waits for that answer: it was answered elsewhere, or stopped.")
|
||||
self.assertEqual(asks_and_answers(self.paths.waiting), [])
|
||||
|
||||
def test_tells_the_loop_when_claude_is_interrupted(self):
|
||||
def interrupted(args, cwd, env):
|
||||
raise KeyboardInterrupt
|
||||
with self.assertRaises(KeyboardInterrupt):
|
||||
self.open(interrupted)
|
||||
self.assertTrue(self.ended)
|
||||
|
||||
|
||||
class Typing(unittest.TestCase):
|
||||
def typed(self, *keys):
|
||||
"""What the log and bender loops get once keys are typed into loop-inbox, which lists log first. ANSWERED_ON_TERMINAL among the keys stands for log being answered on its terminal. Fails where loop-inbox quits before the keys run out."""
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
paths = paths_from(pathlib.Path(home))
|
||||
log, bender = asked("s1", "/code/log", at=100), asked("s2", "/code/bender", at=200)
|
||||
loops_hold(self, paths.waiting, "s1", "s2")
|
||||
for ask in (log, bender):
|
||||
publish(paths.waiting, ask)
|
||||
def answered_on_terminal():
|
||||
withdraw(paths.waiting, "s1")
|
||||
window = Window(answered_on_terminal if key is ANSWERED_ON_TERMINAL else key for key in keys)
|
||||
def made_way(seconds):
|
||||
publish(paths.waiting, dataclasses.replace(log, state=OpenInInbox(INBOX)))
|
||||
effects = dataclasses.replace(system_effects(), claude_on_terminal=lambda args, cwd, env: 0, discard_typed=window.drop_typed, git=lambda *args, **kwargs: Failure("not a checkout"), now=lambda: 0.0, pid=lambda: INBOX, sleep=made_way)
|
||||
with self.assertRaises(OutOfKeys), contextlib.redirect_stderr(io.StringIO()):
|
||||
main.run(window, contextlib.nullcontext, paths, effects)
|
||||
return answered(paths.waiting, log), answered(paths.waiting, bender)
|
||||
|
||||
def test_keys_typed_ahead_are_dropped_once_the_answer_screen_is_left(self):
|
||||
# Each case types, after leaving log's answer screen, a line that would pick bender and one that would answer it, or a line that would quit.
|
||||
for case, keys, got in (
|
||||
("a pasted answer", "1\nYes.\nSee item 2.\nThen release.\n", (Typed("Yes."), None)),
|
||||
("a pasted answer with a line that would quit", "1\nOk.\nquick check first\n", (Typed("Ok."), None)),
|
||||
("/talk", "1\n/talk\n2\nUse B.\n", (None, None)),
|
||||
("a paste that opens with an empty line", "1\n\nSee item 2.\nThen release.\n", (None, None)),
|
||||
("an answer typed as log is answered on its terminal", ["1", "\n", "U", "s", "e", ANSWERED_ON_TERMINAL, *" option 1.\nThen release.\n"], (None, None)),
|
||||
):
|
||||
with self.subTest(case):
|
||||
self.assertEqual(self.typed(*keys), got)
|
||||
|
||||
|
||||
class Keys(unittest.TestCase):
|
||||
def test_the_list_takes_a_number_and_quits_on_q(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
for keys, after in (
|
||||
(("q",), Quit()),
|
||||
(("1", "q"), Listing((ask,), "1")),
|
||||
(("1", "2", "3", BACKSPACE), Listing((ask,), "12")),
|
||||
(("x",), Listing((ask,))),
|
||||
(("²",), Listing((ask,))),
|
||||
((ENTER,), Listing()),
|
||||
(("2", ENTER), Listing(note="No loop has the number 2.")),
|
||||
(("1", ENTER), Answering(ask)),
|
||||
):
|
||||
with self.subTest(keys=keys):
|
||||
self.assertEqual(keyed(Listing((ask,)), *keys), after)
|
||||
|
||||
def test_a_number_typed_keeps_the_running_loops_shown_and_clears_the_note(self):
|
||||
running = (RunningLoop("s1", "/code/log", ()),)
|
||||
self.assertEqual(keyed(Listing(note="No loop has the number 7.", running=running), "1", "2", BACKSPACE), Listing((), "1", "", running))
|
||||
self.assertEqual(keyed(Listing(typed="1", note="No loop has the number 7.", running=running), BACKSPACE), Listing((), "", "", running))
|
||||
|
||||
def test_an_answer_is_sent_stripped_talk_opens_claude_and_enter_alone_or_esc_goes_back(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
for keys, after in (
|
||||
((*" Use B. ", ENTER), Send(ask, "Use B.")),
|
||||
((*" /talk", ENTER), Open(ask)),
|
||||
(("U", "s", "e", "x", BACKSPACE), Answering(ask, "Use")),
|
||||
((" ", ENTER), Listing()),
|
||||
(("U", ESCAPE), Listing()),
|
||||
(("\t",), Answering(ask)),
|
||||
):
|
||||
with self.subTest(keys=keys):
|
||||
self.assertEqual(keyed(Answering(ask), *keys), after)
|
||||
|
||||
def test_curses_keys_get_inboxs_names(self):
|
||||
for key, name in (("\n", ENTER), (main.curses.KEY_ENTER, ENTER), ("\x7f", BACKSPACE), (main.curses.KEY_BACKSPACE, BACKSPACE), ("\x1b", ESCAPE), ("a", "a"), (main.curses.KEY_LEFT, "")):
|
||||
with self.subTest(key=key):
|
||||
self.assertEqual(main.key_name(key), name)
|
||||
|
||||
|
||||
class Waiting(unittest.TestCase):
|
||||
def test_lists_the_loops_still_running_oldest_first_and_skips_a_file_it_cannot_read(self):
|
||||
with tempfile.TemporaryDirectory() as folder:
|
||||
late, early, stopped = asked("s1", "/a", at=300, state=OpenInInbox(7)), asked("s2", "/b", at=100), asked("s3", "/c", at=50, state=OpenOnTerminal())
|
||||
loops_hold(self, pathlib.Path(folder), "s1", "s2")
|
||||
for ask in (late, early, stopped):
|
||||
publish(pathlib.Path(folder), ask)
|
||||
pathlib.Path(folder, "s4.json").write_text("{")
|
||||
pathlib.Path(folder, "s5.json").write_text('{"question": "Which one?"}')
|
||||
pathlib.Path(folder, "s6.json").write_text(pathlib.Path(folder, "s2.json").read_text().replace('"Asking"', '"Waiting"'))
|
||||
self.assertEqual(waiting(pathlib.Path(folder)), [early, late])
|
||||
|
||||
def test_drops_and_removes_the_ask_a_killed_loop_left_behind(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
folder = pathlib.Path(temp)
|
||||
lists_and_waits = "import pathlib, sys, time\nfrom test_loop_inbox import asked, session_lock, listed, system_effects\nwith session_lock.held(pathlib.Path(sys.argv[1]), 's1'), listed(pathlib.Path(sys.argv[1]), asked('s1', '/a'), system_effects()):\n\tprint(flush=True); time.sleep(60)"
|
||||
loop = subprocess.Popen([sys.executable, "-c", lists_and_waits, temp], cwd=pathlib.Path(__file__).parent, stdout=subprocess.PIPE)
|
||||
self.addCleanup(loop.wait)
|
||||
self.addCleanup(loop.kill)
|
||||
loop.stdout.readline()
|
||||
send(folder, asked("s1", "/a"), Typed("Use A."))
|
||||
self.assertEqual(waiting(folder), [asked("s1", "/a")])
|
||||
# SIGKILL runs none of the loop's cleanup.
|
||||
loop.kill()
|
||||
loop.wait()
|
||||
self.assertEqual(waiting(folder), [])
|
||||
drop_ended(folder)
|
||||
self.assertEqual(asks_and_answers(folder), [])
|
||||
|
||||
def test_loop_inbox_removes_a_killed_loops_ask_answer_and_running_file_as_it_looks(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
paths = paths_from(pathlib.Path(home))
|
||||
ask = asked("s1", "/a")
|
||||
publish(paths.waiting, ask)
|
||||
send(paths.waiting, ask, Typed("Use A."))
|
||||
running_loops.running_file(paths.waiting, "s1").write_text(json.dumps({"root": "/a", "items": []}))
|
||||
main.run(Window("q"), contextlib.nullcontext, paths, system_effects())
|
||||
self.assertEqual(asks_and_answers(paths.waiting), [])
|
||||
|
||||
def test_removes_only_the_asks_answers_and_running_files_whose_loop_has_ended_each_by_its_own_module(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
folder = pathlib.Path(temp)
|
||||
loops_hold(self, folder, "s1")
|
||||
for ask in (asked("s1", "/a"), asked("s2", "/b")):
|
||||
publish(folder, ask)
|
||||
send(folder, ask, Typed("Use A."))
|
||||
for session in ("s1", "s2", "s3"):
|
||||
running_loops.running_file(folder, session).write_text(json.dumps({"root": "/a", "items": []}))
|
||||
drop_ended(folder)
|
||||
self.assertEqual(asks_and_answers(folder), ["s1.answer", "s1.json", "s1.running", "s2.running", "s3.running"])
|
||||
running_loops.drop_ended_loops(folder)
|
||||
self.assertEqual(asks_and_answers(folder), ["s1.answer", "s1.json", "s1.running"])
|
||||
|
||||
def test_a_talk_claim_from_pid_0_or_below_is_no_answer_since_it_would_name_a_process_group(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
ask = asked("s1", "/a")
|
||||
for pid in (0, -1):
|
||||
with self.subTest(pid=pid):
|
||||
send(pathlib.Path(temp), ask, ClaudeOpening(pid))
|
||||
self.assertIsNone(answered(pathlib.Path(temp), ask))
|
||||
|
||||
def test_leaves_out_an_ask_with_a_field_of_the_wrong_type_or_value(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
path = ask_file(pathlib.Path(temp), "s1")
|
||||
publish(path.parent, asked("s1", "/a"))
|
||||
good = json.loads(path.read_text())
|
||||
self.assertEqual(read_ask(path), asked("s1", "/a"))
|
||||
for field, value in (
|
||||
("id", 1),
|
||||
("session", "s2"),
|
||||
("root", None),
|
||||
("question", 3),
|
||||
("asked", "noon"),
|
||||
("asked", 100.0),
|
||||
("state", {"kind": "Asking", "talk": {"args": [1], "cwd": "/c", "env": {}}}),
|
||||
("state", {"kind": "Asking", "talk": {"args": [], "cwd": "/c", "env": {"A": 1}}}),
|
||||
):
|
||||
with self.subTest(field=field, value=value):
|
||||
path.write_text(json.dumps(good | {field: value}))
|
||||
self.assertIsNone(read_ask(path))
|
||||
|
||||
def test_withdraw_says_what_it_cannot_remove(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
folder = pathlib.Path(temp, "a file")
|
||||
folder.write_text("")
|
||||
self.assertEqual(withdraw(folder, "s1"), Failure(f"cannot remove {folder / 's1.json'}: Not a directory"))
|
||||
|
||||
def test_a_message_reaches_only_the_ask_it_names(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
folder, ask = pathlib.Path(temp), asked("s1", "/a")
|
||||
another = dataclasses.replace(ask, id="another")
|
||||
for message, answer, ended in ((Typed("A"), Typed("A"), False), (ClaudeOpening(7), ClaudeOpening(7), False), (ClaudeEnded(), None, True)):
|
||||
with self.subTest(message=message):
|
||||
send(folder, ask, message)
|
||||
self.assertEqual((answered(folder, ask), claude_ended(folder, ask)), (answer, ended))
|
||||
self.assertEqual((answered(folder, another), claude_ended(folder, another)), (None, False))
|
||||
|
||||
|
||||
class RunningLoops(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.folder = pathlib.Path(tempfile.mkdtemp())
|
||||
self.addCleanup(shutil.rmtree, self.folder)
|
||||
self.effects = dataclasses.replace(system_effects(), sleep=lambda seconds: None)
|
||||
|
||||
def test_lists_a_loop_with_the_items_it_shows_until_it_ends(self):
|
||||
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as listed:
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
|
||||
listed.show((Taken(255, "Have loop-inbox list every running loop."),))
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", (Taken(255, "Have loop-inbox list every running loop."),))])
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [])
|
||||
|
||||
def test_lists_the_loops_by_checkout_and_leaves_out_one_that_was_killed_or_whose_file_cannot_be_read(self):
|
||||
# Five, so the order the files are found in is unlikely to be the order by checkout.
|
||||
for session, root in (("s1", "/code/web"), ("s2", "/code/c"), ("s7", "/code/a"), ("s8", "/code/z"), ("s9", "/code/m")):
|
||||
self.enterContext(running_loops.shown_running(self.folder, session, root, self.effects))
|
||||
# A killed loop leaves its file behind, and its lock free.
|
||||
(self.folder / "s3.running").write_text(json.dumps({"root": "/code/old", "items": []}))
|
||||
for session, content in (("s4", "{"), ("s5", json.dumps({"root": "/code/x", "items": [{"id": "1", "tagline": ""}]})), ("s6", json.dumps({"root": "/code/x"})), ("s10", json.dumps({"root": "/code/x", "items": [{"id": True, "tagline": ""}]}))):
|
||||
self.enterContext(session_lock.held(self.folder, session))
|
||||
(self.folder / f"{session}.running").write_text(content)
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s7", "/code/a", ()), RunningLoop("s2", "/code/c", ()), RunningLoop("s9", "/code/m", ()), RunningLoop("s1", "/code/web", ()), RunningLoop("s8", "/code/z", ())])
|
||||
|
||||
def test_a_second_loop_on_the_session_warns_and_leaves_the_first_listed_with_its_question(self):
|
||||
ask = asked("s1", "/code/log")
|
||||
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as first:
|
||||
publish(first.folder, ask)
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
with running_loops.shown_running(self.folder, "s1", "/code/log", self.effects) as second:
|
||||
second.show((Taken(1, "Do it."),))
|
||||
with listed(second.folder, asked("s1", "/code/log", question="Mine?"), self.effects):
|
||||
self.assertEqual(waiting(self.folder), [ask])
|
||||
self.assertIn(f"loop-inbox cannot list this loop or its questions: another process holds {session_lock.lock_file(self.folder, 's1')}", said.getvalue())
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
|
||||
self.assertEqual(waiting(self.folder), [ask])
|
||||
self.assertEqual(list((self.folder / "unlisted").iterdir()), [])
|
||||
|
||||
def test_takes_the_lock_once_loop_inbox_lets_go_of_it(self):
|
||||
# loop-inbox holds the lock for a moment as it checks whether the loop runs.
|
||||
looking = contextlib.ExitStack()
|
||||
looking.enter_context(session_lock.held(self.folder, "s1"))
|
||||
with running_loops.shown_running(self.folder, "s1", "/code/log", dataclasses.replace(self.effects, sleep=lambda seconds: looking.close())):
|
||||
self.assertEqual(running_loops.running_loops(self.folder), [RunningLoop("s1", "/code/log", ())])
|
||||
|
||||
|
||||
class Shown(unittest.TestCase):
|
||||
def drawn(self, screen, window):
|
||||
"""The lines draw puts on window for screen, 3700 s after the epoch."""
|
||||
main.draw(window, screen, dataclasses.replace(system_effects(), local_time=lambda seconds: f"<{seconds}>", now=lambda: 3700))
|
||||
return [window.lines[row] for row in range(len(window.lines))]
|
||||
|
||||
def test_the_list_shows_each_loops_checkout_wait_and_the_first_lines_of_its_question(self):
|
||||
log = asked("s1", "/code/log", "Which store should the cache use: Redis or SQLite? Redis is already deployed for sessions.", at=0)
|
||||
cut = asked("s2", "/code/c", "Cut 0.4.0?\nIts changelog is ready.", at=3600 * 25, state=OpenInInbox(INBOX))
|
||||
lines = inbox.listing_lines(Listing((log, cut), "1"), 3600 * 26 + 120, lambda seconds: f"<{seconds}>", 50)
|
||||
self.assertEqual(lines, ([
|
||||
"2 loops wait for you, oldest first.",
|
||||
"",
|
||||
"[1] /code/log, waiting since <0> (1 d 2 h)",
|
||||
" Which store should the cache use: Redis or",
|
||||
" SQLite? Redis is already deployed for…",
|
||||
"",
|
||||
"[2] /code/c, waiting since <90000> (1 h 2 min);",
|
||||
"claude is open in loop-inbox",
|
||||
" Cut 0.4.0?",
|
||||
" Its changelog is ready.",
|
||||
"",
|
||||
"No loop runs.",
|
||||
], [
|
||||
"Type a number and Enter to answer that loop; q",
|
||||
"quits loop-inbox, and the loops keep waiting.",
|
||||
"> 1",
|
||||
]))
|
||||
|
||||
def test_the_running_loops_follow_the_waiting_ones_each_with_the_items_its_chunk_takes(self):
|
||||
log = asked("s1", "/code/log", "Which one?", at=0)
|
||||
running = (
|
||||
RunningLoop("s2", "/code/c", (Taken(12, "Accept undefined in MetadataValue and drop such keys on output."), Taken(14, ""))),
|
||||
RunningLoop("s1", "/code/log", (Taken(255, "Have loop-inbox list every running loop-claude on the machine."),)),
|
||||
RunningLoop("s3", "/code/web", ()),
|
||||
)
|
||||
lines, _ = inbox.listing_lines(Listing((log,), running=running), 120, lambda seconds: f"<{seconds}>", 50)
|
||||
self.assertEqual(lines, [
|
||||
"1 loop waits for you.",
|
||||
"",
|
||||
"[1] /code/log, waiting since <0> (2 min)",
|
||||
" Which one?",
|
||||
"",
|
||||
"Running: 3 loops",
|
||||
"- /code/c",
|
||||
" item 12: Accept undefined in MetadataValue…",
|
||||
" item 14",
|
||||
"- /code/log, waiting as [1]",
|
||||
" item 255: Have loop-inbox list every running…",
|
||||
"- /code/web",
|
||||
" no todo.md item yet",
|
||||
])
|
||||
|
||||
def test_the_running_section_counts_one_loop(self):
|
||||
lines, _ = inbox.listing_lines(Listing(running=(RunningLoop("s1", "/code/log", ()),)), 0, str, 79)
|
||||
self.assertEqual(lines, ["No loop waits for you.", "", "Running: 1 loop", "- /code/log", " no todo.md item yet"])
|
||||
|
||||
def test_an_empty_list_says_no_loop_waits_or_runs(self):
|
||||
self.assertEqual(inbox.listing_lines(Listing(note="Sent to /a."), 0, str, 79), (["No loop waits for you.", "", "No loop runs."], ["Sent to /a.", "q quits loop-inbox, and the loops keep waiting.", "> "]))
|
||||
|
||||
def test_the_answer_screen_at_80_columns_shows_every_character_of_each_line_and_says_what_enter_alone_does(self):
|
||||
# The question's first line has 80 characters, one more than a line drawn at 80 columns holds.
|
||||
ask = asked("s1", "/code/log", "The changelog lists four fixes and three new tools, so the next release is 0.6.0\n\nCut it?", at=100)
|
||||
self.assertEqual(self.drawn(Answering(ask, "Yes"), Window(width=80)), [
|
||||
"/code/log, waiting since <100> (1 h 0 min):",
|
||||
"",
|
||||
"The changelog lists four fixes and three new tools, so the next release is",
|
||||
"0.6.0",
|
||||
"",
|
||||
"Cut it?",
|
||||
"",
|
||||
"Answer (/talk opens claude; Enter alone, or Esc, goes back, and the loop keeps",
|
||||
"waiting): Yes",
|
||||
])
|
||||
|
||||
def test_an_answer_longer_than_its_line_goes_on_below_it_with_every_space_typed(self):
|
||||
typed = "Use B, as the cache then runs next to the sessions it serves and then cut 0.6.0."
|
||||
lines = self.drawn(Answering(asked("s1", "/code/log", "A or B?", at=100), typed), Window(width=80))
|
||||
self.assertEqual(lines[-2:], ["waiting): Use B, as the cache then runs next to the sessions it serves and then", " cut 0.6.0."])
|
||||
|
||||
def test_a_line_that_runs_into_the_screens_last_cell_leaves_the_screen_drawn(self):
|
||||
class Refusing(Window):
|
||||
"""Refuses the screen's last row, as curses refuses a line of wide characters, such as emoji, that runs into the last cell."""
|
||||
|
||||
def addnstr(self, row, column, text, count):
|
||||
super().addnstr(row, column, text, count)
|
||||
if row == self.height - 1:
|
||||
raise main.curses.error("addnwstr() returned ERR")
|
||||
self.assertEqual(self.drawn(Listing(), Refusing(height=3)), ["…", "q quits loop-inbox, and the loops keep waiting.", "> "])
|
||||
|
||||
def test_a_screen_too_short_keeps_the_foot_and_marks_the_cut(self):
|
||||
for lines, foot, height, shown in (
|
||||
(["a", "b", "c"], ["> "], 4, ["a", "b", "c", "> "]),
|
||||
(["a", "b", "c"], ["> "], 3, ["a", "…", "> "]),
|
||||
(["a", "b", "c"], ["n", "> "], 4, ["a", "…", "n", "> "]),
|
||||
(["a", "b", "c", "d"], ["n", "h", "> "], 2, ["h", "> "]),
|
||||
):
|
||||
with self.subTest(lines=lines, foot=foot, height=height):
|
||||
self.assertEqual(inbox.fitted(lines, foot, height), shown)
|
||||
|
||||
def test_a_wait_reads_in_minutes_under_an_hour_and_in_hours_under_a_day(self):
|
||||
for seconds, read in ((3599, "59 min"), (3600, "1 h 0 min"), (86399, "23 h 59 min"), (86400, "1 d 0 h")):
|
||||
with self.subTest(seconds=seconds):
|
||||
self.assertEqual(inbox.waited(seconds), read)
|
||||
|
||||
|
||||
class Terminal(io.StringIO):
|
||||
def isatty(self):
|
||||
return True
|
||||
|
||||
|
||||
class Starts(unittest.TestCase):
|
||||
def started(self, argv, stdin, stdout):
|
||||
"""What main returns for argv, run with stdin and stdout, and what it writes to stderr."""
|
||||
stderr = io.StringIO()
|
||||
with unittest.mock.patch.object(sys, "stdin", stdin), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
||||
code = main.main(argv, pathlib.Path("/no home"))
|
||||
return code, stderr.getvalue()
|
||||
|
||||
def test_help_prints_the_docstring(self):
|
||||
for flag in ("-h", "--help"):
|
||||
with self.subTest(flag):
|
||||
stdout = io.StringIO()
|
||||
self.assertEqual(self.started([flag], io.StringIO(), stdout), (0, ""))
|
||||
self.assertEqual(stdout.getvalue(), f"{main.__doc__.strip()}\n")
|
||||
|
||||
def test_exits_2_on_an_unknown_argument_or_off_a_terminal(self):
|
||||
off_a_terminal = "loop-inbox: stdin or stdout is not a terminal; run it on one\n"
|
||||
for case, argv, stdin, stdout, said in (
|
||||
("an unknown argument", ["--x"], Terminal(), Terminal(), "loop-inbox: unknown argument --x; usage: loop-inbox\n"),
|
||||
("stdout off a terminal", [], Terminal(), io.StringIO(), off_a_terminal),
|
||||
("stdin off a terminal", [], io.StringIO(), Terminal(), off_a_terminal),
|
||||
):
|
||||
with self.subTest(case):
|
||||
self.assertEqual(self.started(argv, stdin, stdout), (2, said))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,4 +1,4 @@
|
||||
"""The files loop-claude and loop-inbox share: a running loop lists itself (running_loops.py, session_lock.py) and its question (waiting/), and both read the same paths (paths.py) and open claude for the human the same way (hand_over.py).
|
||||
"""Where loop-claude keeps its files (paths.py), which the tools that replay its runs read too.
|
||||
|
||||
A change here changes both tools. It doesn't import anything from loop_claude/.
|
||||
It doesn't import anything from loop_claude/.
|
||||
"""
|
||||
|
||||
@@ -11,8 +11,6 @@ class Paths:
|
||||
home: pathlib.Path
|
||||
model_catalog: pathlib.Path
|
||||
models_file: pathlib.Path
|
||||
# Where a loop shows its interrupt to loop-inbox (bin/loop_state/waiting/).
|
||||
waiting: pathlib.Path
|
||||
|
||||
|
||||
def paths_from(home: pathlib.Path) -> Paths:
|
||||
@@ -24,5 +22,4 @@ def paths_from(home: pathlib.Path) -> Paths:
|
||||
home=home,
|
||||
model_catalog=claude / "cache" / "model-catalog",
|
||||
models_file=claude / "loop-claude-models.json",
|
||||
waiting=home / ".local" / "state" / "loop-claude",
|
||||
)
|
||||
|
||||
@@ -1,137 +0,0 @@
|
||||
"""The files by which a loop-claude shows loop-inbox that it runs, and the todo.md items its chunk takes.
|
||||
|
||||
A running loop holds its session's lock (session_lock.py) in Paths.waiting for its whole run. Beside the lock it keeps
|
||||
<session>.running, which holds the loop's checkout and each item its chunk takes, by ID and by its tagline on the default
|
||||
branch as last fetched. The items are the one the chunk was routed on, then those the worker names on its latest
|
||||
`Chunk items:` line, each listed once. loop-inbox lists a loop, and its question (waiting/), only while the loop holds its
|
||||
lock. So a killed loop drops off the list, though its files stay until loop-inbox removes them: <session>.running
|
||||
through drop_ended_loops here, and the question through waiting.listing.drop_ended.
|
||||
"""
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
import shutil
|
||||
import typing
|
||||
|
||||
from loop_effects.effects import Effects, say
|
||||
from loop_state.session_lock import ended, held, running
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import items
|
||||
from text_files.file_writes import replace_json
|
||||
|
||||
# How many times, 0.1 s apart, a loop tries to take its lock: loop-inbox takes it for a moment each time it checks whether the loop has ended.
|
||||
LOCK_TRIES = 10
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Taken:
|
||||
"""A todo.md item a chunk takes."""
|
||||
id: int
|
||||
# The item's tagline without its bold marks; empty where the default branch's todo.md can't be read or holds no such item.
|
||||
tagline: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class RunningLoop:
|
||||
session: str
|
||||
# The checkout the loop runs in.
|
||||
root: str
|
||||
# The routed item first; empty until the chunk has an item.
|
||||
items: tuple[Taken, ...]
|
||||
|
||||
|
||||
Show = typing.Callable[[tuple[Taken, ...]], None]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Listed:
|
||||
"""How a running loop shows itself in loop-inbox."""
|
||||
# Where the loop keeps its questions: Paths.waiting where it holds its session's lock. Where another loop on the session holds the lock, a folder of its own that loop-inbox doesn't read, so this loop never touches the other's questions.
|
||||
folder: pathlib.Path
|
||||
show: Show
|
||||
|
||||
|
||||
def running_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
return folder / f"{session}.running"
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def shown_running(folder: pathlib.Path, session: str, root: str, effects: Effects) -> typing.Iterator[Listed]:
|
||||
"""Lists the loop in loop-inbox as running while the with block runs, at first with no item. A failure only warns: the loop runs unlisted, and its questions are answered on its terminal."""
|
||||
with contextlib.ExitStack() as stack:
|
||||
if unlocked := locked_soon(stack, folder, session, effects):
|
||||
say(f"loop-inbox cannot list this loop or its questions: {unlocked.reason}", effects)
|
||||
unlisted = folder / "unlisted" / effects.new_id()
|
||||
try:
|
||||
yield Listed(unlisted, lambda items: None)
|
||||
finally:
|
||||
shutil.rmtree(unlisted, ignore_errors=True)
|
||||
return
|
||||
def show(items: tuple[Taken, ...]) -> None:
|
||||
if unshown := replace_json(running_file(folder, session), {"root": root, "items": [dataclasses.asdict(item) for item in items]}):
|
||||
say(f"loop-inbox cannot list this loop's items: {unshown.reason}", effects)
|
||||
show(())
|
||||
try:
|
||||
yield Listed(folder, show)
|
||||
finally:
|
||||
# A file this fails to remove stays until loop-inbox removes it, once the lock is let go.
|
||||
with contextlib.suppress(OSError):
|
||||
running_file(folder, session).unlink(missing_ok=True)
|
||||
|
||||
|
||||
def locked_soon(stack: contextlib.ExitStack, folder: pathlib.Path, session: str, effects: Effects) -> Failure | None:
|
||||
"""Holds the session's lock until stack closes, trying LOCK_TRIES times; returns None once it holds the lock, else the last try's failure."""
|
||||
for _ in range(LOCK_TRIES):
|
||||
attempt = contextlib.ExitStack()
|
||||
unlocked = attempt.enter_context(held(folder, session))
|
||||
if not unlocked:
|
||||
stack.enter_context(attempt)
|
||||
return None
|
||||
attempt.close()
|
||||
effects.sleep(0.1)
|
||||
return unlocked
|
||||
|
||||
|
||||
def running_loops(folder: pathlib.Path) -> list[RunningLoop]:
|
||||
"""The loops that hold their lock, by checkout. A file that cannot be read or parsed is left out."""
|
||||
try:
|
||||
paths = list(folder.glob("*.running"))
|
||||
except OSError:
|
||||
return []
|
||||
loops = [loop for path in paths if (loop := read_running(path)) and running(folder, loop.session)]
|
||||
return sorted(loops, key=lambda loop: loop.root)
|
||||
|
||||
|
||||
def drop_ended_loops(folder: pathlib.Path) -> None:
|
||||
"""Removes each running file whose session's lock no loop holds: a loop that was killed leaves it behind. A file it cannot remove stays on disk, and running_loops leaves it out all the same."""
|
||||
for session in ended(folder, "*.running"):
|
||||
with contextlib.suppress(OSError):
|
||||
running_file(folder, session).unlink(missing_ok=True)
|
||||
|
||||
|
||||
def read_running(path: pathlib.Path) -> RunningLoop | None:
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError):
|
||||
return None
|
||||
match data:
|
||||
case {"root": str(root), "items": list(items)} if all(is_item(item) for item in items):
|
||||
return RunningLoop(path.name.removesuffix(".running"), root, tuple(Taken(item["id"], item["tagline"]) for item in items))
|
||||
return None
|
||||
|
||||
|
||||
def is_item(item: object) -> bool:
|
||||
match item:
|
||||
# type(), not isinstance(): JSON true is no ID.
|
||||
case {"id": id_, "tagline": str()} if type(id_) is int:
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def taken_items(todo: str | Failure, routed: int, taken_in: tuple[int, ...]) -> tuple[Taken, ...]:
|
||||
"""The items a chunk takes, as the module docstring says, with their taglines from todo, the default branch's todo.md. routed, the item the chunk was routed on, is 0 for none."""
|
||||
found = items(todo) if isinstance(todo, str) else []
|
||||
taglines = {item.id: item.tagline.removeprefix("**").removesuffix("**") for item in found} if isinstance(found, list) else {}
|
||||
ids = dict.fromkeys(([routed] if routed else []) + list(taken_in))
|
||||
return tuple(Taken(id_, taglines.get(id_, "")) for id_ in ids)
|
||||
@@ -1,66 +0,0 @@
|
||||
"""The lock by which loop-inbox tells whether a loop-claude still runs.
|
||||
|
||||
A loop holds <session>.lock for its whole run (running_loops.py), with flock, which the kernel frees however the loop
|
||||
ends, killed included. The lock file stays once the loop ends: docs/decisions.md → `loop-inbox: …` says why.
|
||||
"""
|
||||
import contextlib
|
||||
import fcntl
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from text_files.file_writes import make_private
|
||||
|
||||
|
||||
def lock_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
return folder / f"{session}.lock"
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def held(folder: pathlib.Path, session: str) -> typing.Iterator[Failure | None]:
|
||||
"""Holds the session's lock while the with block runs, or yields a Failure where it cannot. loop-inbox takes the lock for a moment through ended, on each session whose files are still on disk, so a loop may find it held."""
|
||||
path = lock_file(folder, session)
|
||||
try:
|
||||
make_private(folder)
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot make {folder}: {failure.strerror}")
|
||||
return
|
||||
try:
|
||||
handle = open(path, "a")
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot open {path}: {failure.strerror}")
|
||||
return
|
||||
with handle:
|
||||
try:
|
||||
fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
except BlockingIOError:
|
||||
yield Failure(f"another process holds {path}")
|
||||
return
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot lock {path}: {failure.strerror}")
|
||||
return
|
||||
yield None
|
||||
|
||||
|
||||
def ended(folder: pathlib.Path, pattern: str) -> typing.Iterator[str]:
|
||||
"""Each session with a file in folder that matches pattern, such as "*.json", and whose lock no loop holds. It yields each while holding that lock, so a loop that starts meanwhile keeps its files."""
|
||||
try:
|
||||
sessions = {path.stem for path in folder.glob(pattern)}
|
||||
except OSError:
|
||||
return
|
||||
for session in sessions:
|
||||
with held(folder, session) as unlocked:
|
||||
if not unlocked:
|
||||
yield session
|
||||
|
||||
|
||||
def running(folder: pathlib.Path, session: str) -> bool:
|
||||
"""Whether a loop holds the session's lock; False also where the lock file cannot be opened or locked."""
|
||||
try:
|
||||
with open(lock_file(folder, session)) as handle:
|
||||
fcntl.flock(handle, fcntl.LOCK_SH | fcntl.LOCK_NB)
|
||||
except BlockingIOError:
|
||||
return True
|
||||
except OSError:
|
||||
return False
|
||||
return False
|
||||
@@ -1,41 +0,0 @@
|
||||
import errno
|
||||
import pathlib
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from loop_state import session_lock
|
||||
|
||||
|
||||
class SessionLock(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.folder = pathlib.Path(tempfile.mkdtemp())
|
||||
self.addCleanup(shutil.rmtree, self.folder)
|
||||
self.path = session_lock.lock_file(self.folder, "s1")
|
||||
|
||||
def test_a_held_lock_refuses_a_second_taker_and_reads_as_running_until_let_go(self):
|
||||
self.assertFalse(session_lock.running(self.folder, "s1"))
|
||||
with session_lock.held(self.folder, "s1") as first:
|
||||
self.assertIsNone(first)
|
||||
with session_lock.held(self.folder, "s1") as second:
|
||||
self.assertEqual(second, Failure(f"another process holds {self.path}"))
|
||||
self.assertTrue(session_lock.running(self.folder, "s1"))
|
||||
self.assertFalse(session_lock.running(self.folder, "s1"))
|
||||
|
||||
def test_a_lock_that_cannot_be_opened_is_a_failure_and_no_loop_running(self):
|
||||
self.path.mkdir()
|
||||
with session_lock.held(self.folder, "s1") as unlocked:
|
||||
self.assertEqual(unlocked, Failure(f"cannot open {self.path}: Is a directory"))
|
||||
self.assertFalse(session_lock.running(self.folder, "s1"))
|
||||
|
||||
def test_a_lock_the_kernel_refuses_is_a_failure_and_no_loop_running(self):
|
||||
self.path.touch()
|
||||
with unittest.mock.patch("fcntl.flock", side_effect=OSError(errno.ENOLCK, "No locks available")):
|
||||
with session_lock.held(self.folder, "s1") as unlocked:
|
||||
self.assertEqual(unlocked, Failure(f"cannot lock {self.path}: No locks available"))
|
||||
self.assertFalse(session_lock.running(self.folder, "s1"))
|
||||
@@ -1,11 +0,0 @@
|
||||
"""The files by which a loop-claude shows its interrupt in loop-inbox, and takes an answer typed there.
|
||||
|
||||
A waiting loop keeps its ask in <session>.json in Paths.waiting: the question, with an id new for each question.
|
||||
<session> is the worker's session id, so a loop lists one question at a time. The loop removes the ask once the question
|
||||
is answered or the loop stops. loop-inbox lists an ask only while the loop holds the session's lock (running_loops.py),
|
||||
and removes one whose lock is free. loop-inbox answers by replacing <session>.answer, which names the
|
||||
ask's id. So an answer meant for an earlier question, or sent as the loop took an answer on its terminal,
|
||||
never answers a later one.
|
||||
|
||||
Its modules import only those before them: ask, answers, listing, talk.
|
||||
"""
|
||||
@@ -1,68 +0,0 @@
|
||||
"""What loop-inbox sends to a waiting ask, in <session>.answer, and how the loop reads it.
|
||||
|
||||
The message types stay here beside `received`, which reads them back, so that a change to one meets the other."""
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
|
||||
from loop_state.waiting.ask import Ask, tagged
|
||||
from failure import Failure
|
||||
from text_files.file_writes import replace_json
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Typed:
|
||||
text: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ClaudeOpening:
|
||||
"""loop-inbox, whose process is pid, asks the loop to make way for the claude it opens for /talk."""
|
||||
pid: int
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ClaudeEnded:
|
||||
"""The claude loop-inbox opened for the ask has ended."""
|
||||
|
||||
|
||||
# What answers a waiting ask.
|
||||
Answer = Typed | ClaudeOpening
|
||||
Message = Answer | ClaudeEnded
|
||||
|
||||
|
||||
def answer_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
return folder / f"{session}.answer"
|
||||
|
||||
|
||||
def send(folder: pathlib.Path, ask: Ask, message: Message) -> Failure | None:
|
||||
return replace_json(answer_file(folder, ask.session), {"ask": ask.id, **tagged(message)})
|
||||
|
||||
|
||||
def answered(folder: pathlib.Path, ask: Ask) -> Answer | None:
|
||||
"""The answer loop-inbox sent to this ask; None for none, or one meant for another ask of the session."""
|
||||
message = received(folder, ask)
|
||||
return message if isinstance(message, Typed | ClaudeOpening) else None
|
||||
|
||||
|
||||
def claude_ended(folder: pathlib.Path, ask: Ask) -> bool:
|
||||
"""Whether loop-inbox said the claude it opened for this ask has ended."""
|
||||
return isinstance(received(folder, ask), ClaudeEnded)
|
||||
|
||||
|
||||
def received(folder: pathlib.Path, ask: Ask) -> Message | None:
|
||||
try:
|
||||
data = json.loads(answer_file(folder, ask.session).read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError):
|
||||
return None
|
||||
if not isinstance(data, dict) or data.get("ask") != ask.id:
|
||||
return None
|
||||
match data:
|
||||
case {"kind": "Typed", "text": str(text)}:
|
||||
return Typed(text)
|
||||
# alive is always True for a pid of 0 or below, which names a process group or every process, so the loop would wait for claude forever.
|
||||
case {"kind": "ClaudeOpening", "pid": int(pid)} if pid > 0:
|
||||
return ClaudeOpening(pid)
|
||||
case {"kind": "ClaudeEnded"}:
|
||||
return ClaudeEnded()
|
||||
return None
|
||||
@@ -1,79 +0,0 @@
|
||||
"""An interrupt's question as loop-inbox lists it, and how its file is read; `tagged` writes the kind that `ask_state` reads.
|
||||
|
||||
The ask's state says whether the loop waits for an answer, or has claude open for it, on the loop's own terminal or in loop-inbox."""
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from loop_state.hand_over import ClaudeCommand
|
||||
from text_files.utc_stamp import seconds, utc
|
||||
|
||||
if typing.TYPE_CHECKING:
|
||||
from _typeshed import DataclassInstance
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Asking:
|
||||
"""The ask waits for an answer; talk opens the worker's claude session for /talk."""
|
||||
talk: ClaudeCommand
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class OpenOnTerminal:
|
||||
"""claude is open for the ask on the loop's own terminal; the loop takes no answer from loop-inbox."""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class OpenInInbox:
|
||||
"""claude is open for the ask in the loop-inbox whose process is pid."""
|
||||
pid: int
|
||||
|
||||
|
||||
AskState = Asking | OpenOnTerminal | OpenInInbox
|
||||
|
||||
|
||||
def tagged(value: "DataclassInstance") -> dict[str, object]:
|
||||
"""value's fields, with its kind, which ask_state and answers.received read it back by."""
|
||||
return dataclasses.asdict(value) | {"kind": type(value).__name__}
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Ask:
|
||||
"""An interrupt's question, as loop-inbox lists it."""
|
||||
id: str
|
||||
session: str
|
||||
# The checkout the loop runs in.
|
||||
root: str
|
||||
question: str
|
||||
# When the loop asked, in seconds since the epoch; its file holds it as an ISO UTC datetime, as ask_fields writes it.
|
||||
asked: float
|
||||
state: AskState
|
||||
|
||||
|
||||
def ask_fields(ask: Ask) -> dict[str, object]:
|
||||
"""ask as its file holds it, which read_ask reads back to the second."""
|
||||
return dataclasses.asdict(ask) | {"asked": utc(ask.asked), "state": tagged(ask.state)}
|
||||
|
||||
|
||||
def read_ask(path: pathlib.Path) -> Ask | None:
|
||||
"""The ask in path. None where a field has the wrong type, where utc_stamp.seconds cannot read asked, or where the ask names another session than path does."""
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
ask = Ask(**{**data, "asked": seconds(data["asked"]), "state": ask_state(data["state"])})
|
||||
except (OSError, ValueError, TypeError, KeyError):
|
||||
return None
|
||||
texts = all(isinstance(text, str) for text in (ask.id, ask.session, ask.root, ask.question))
|
||||
return ask if texts and ask.session == path.stem else None
|
||||
|
||||
|
||||
def ask_state(data: object) -> AskState:
|
||||
match data:
|
||||
case {"kind": "Asking", "talk": {"args": list(args), "cwd": str(cwd), "env": dict(env)}} if all(isinstance(text, str) for text in [*args, *env.values()]):
|
||||
return Asking(ClaudeCommand(args, cwd, env))
|
||||
case {"kind": "OpenOnTerminal"}:
|
||||
return OpenOnTerminal()
|
||||
case {"kind": "OpenInInbox", "pid": int(pid)}:
|
||||
return OpenInInbox(pid)
|
||||
raise ValueError(f"not an ask's state: {data!r}")
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
"""The ask's file in the folder loop-inbox reads, and which asks it lists."""
|
||||
import contextlib
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from loop_state.waiting.answers import answer_file
|
||||
from loop_state.waiting.ask import Ask, ask_fields, read_ask
|
||||
from loop_effects.effects import Effects, say
|
||||
from loop_state.session_lock import ended, running
|
||||
from failure import Failure
|
||||
from text_files.file_writes import make_private, replace_json
|
||||
|
||||
|
||||
def ask_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
return folder / f"{session}.json"
|
||||
|
||||
|
||||
def publish(folder: pathlib.Path, ask: Ask) -> Failure | None:
|
||||
try:
|
||||
make_private(folder)
|
||||
except OSError as failure:
|
||||
return Failure(f"cannot make {folder}: {failure.strerror}")
|
||||
return replace_json(ask_file(folder, ask.session), ask_fields(ask))
|
||||
|
||||
|
||||
def withdraw(folder: pathlib.Path, session: str) -> Failure | None:
|
||||
"""Removes the session's ask and any answer to it."""
|
||||
for path in (ask_file(folder, session), answer_file(folder, session)):
|
||||
try:
|
||||
path.unlink(missing_ok=True)
|
||||
except OSError as failure:
|
||||
return Failure(f"cannot remove {path}: {failure.strerror}")
|
||||
return None
|
||||
|
||||
|
||||
def shown(folder: pathlib.Path, ask: Ask, effects: Effects) -> None:
|
||||
"""Lists ask in loop-inbox, in its state. A failure only warns: the question is still answered on the loop's terminal."""
|
||||
if unshown := publish(folder, ask):
|
||||
say(f"loop-inbox cannot show this question: {unshown.reason}", effects)
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def listed(folder: pathlib.Path, ask: Ask, effects: Effects) -> typing.Iterator[None]:
|
||||
"""Lists ask in loop-inbox while the with block runs, then takes it out, with any answer. A failure to list it only warns: the question is still answered on the loop's terminal.
|
||||
|
||||
listed doesn't take the session's lock, which loop-inbox needs held to list the ask. Pass the folder running_loops.shown_running yields: shown_running holds the lock for the loop's whole run.
|
||||
"""
|
||||
shown(folder, ask, effects)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
# An ask this fails to remove is left to loop-inbox, which stops listing it once the lock is let go, and removes it.
|
||||
withdraw(folder, ask.session)
|
||||
|
||||
|
||||
def waiting(folder: pathlib.Path) -> list[Ask]:
|
||||
"""The asks of loops still running, oldest first. A file that cannot be read or parsed is left out."""
|
||||
try:
|
||||
paths = sorted(folder.glob("*.json"))
|
||||
except OSError:
|
||||
return []
|
||||
asks = [ask for path in paths if (ask := read_ask(path)) and running(folder, ask.session)]
|
||||
return sorted(asks, key=lambda ask: ask.asked)
|
||||
|
||||
|
||||
def drop_ended(folder: pathlib.Path) -> None:
|
||||
"""Removes each ask, with any answer, whose session's lock no loop holds: a loop that was killed leaves its ask behind. An ask it cannot remove stays on disk, and waiting leaves it out all the same."""
|
||||
for session in ended(folder, "*.json"):
|
||||
withdraw(folder, session)
|
||||
@@ -1,45 +0,0 @@
|
||||
"""/talk from loop-inbox goes in three steps, so that only one claude ever holds the worker's session:
|
||||
1. loop-inbox's claim_talk sends ClaudeOpening, with its pid.
|
||||
2. The loop stops reading its terminal, and its make_way lists the ask as OpenInInbox with that pid. claim_talk
|
||||
returns True once it reads that, and loop-inbox opens claude.
|
||||
3. loop-inbox sends ClaudeEnded once claude exits, which the loop reads with answers.claude_ended. The loop also stops waiting
|
||||
if loop-inbox's process is gone.
|
||||
"""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, read_ask
|
||||
from loop_state.waiting.listing import ask_file, shown
|
||||
from loop_state.waiting.answers import ClaudeEnded, ClaudeOpening, send
|
||||
from loop_effects.effects import Effects, POLL_SECONDS
|
||||
from failure import Failure
|
||||
|
||||
# Seconds loop-inbox waits for a loop to make way for its claude: ten of the loop's looks, so a loop slow for a moment still makes way.
|
||||
MAKE_WAY_SECONDS = 10 * POLL_SECONDS
|
||||
# What the human types, on the loop's terminal or in loop-inbox, to open claude for the ask; picked on 2026-10-17 by a bench of three readers seated as the README's audience.
|
||||
TALK = "/talk"
|
||||
|
||||
|
||||
def claim_talk(folder: pathlib.Path, ask: Ask, pid: int, now: typing.Callable[[], float], sleep: typing.Callable[[float], None]) -> bool | Failure:
|
||||
"""loop-inbox's side of /talk, where pid is loop-inbox's process: asks the loop to make way for the claude loop-inbox opens for ask. True once the loop shows it has stopped reading its terminal, within MAKE_WAY_SECONDS. False where the ask is gone or replaced, its state is no longer Asking (answered first, claude open on the loop's own terminal, or the loop made way for another loop-inbox), or the loop didn't make way in time."""
|
||||
if unsent := send(folder, ask, ClaudeOpening(pid)):
|
||||
return unsent
|
||||
deadline = now() + MAKE_WAY_SECONDS
|
||||
while now() < deadline:
|
||||
current = read_ask(ask_file(folder, ask.session))
|
||||
if current is None or current.id != ask.id:
|
||||
return False
|
||||
if current.state == OpenInInbox(pid):
|
||||
return True
|
||||
if not isinstance(current.state, Asking):
|
||||
return False
|
||||
sleep(0.1)
|
||||
# Takes the claim back: a loop that reads it late waits for no claude, and one that made way late, or failed to show it had, ends its wait.
|
||||
send(folder, ask, ClaudeEnded())
|
||||
return False
|
||||
|
||||
|
||||
def make_way(folder: pathlib.Path, ask: Ask, pid: int, effects: Effects) -> None:
|
||||
"""The loop's side of /talk from loop-inbox, once it has stopped reading its terminal: lists ask as having claude open in the loop-inbox whose process is pid, which claim_talk waits for. A failure only warns: claim_talk then gives up, and the loop stops."""
|
||||
shown(folder, dataclasses.replace(ask, state=OpenInInbox(pid)), effects)
|
||||
@@ -8,6 +8,8 @@ import typing
|
||||
CPUS_PER_SLOT = 4
|
||||
# Seconds between tries while every slot is held; a slot frees as its command exits.
|
||||
POLL_SECONDS = 1
|
||||
# Names the environment variable run-heavy sets for the command it runs. A process that finds it set already holds a slot, and takes no second one.
|
||||
HELD = "RUN_HEAVY_SLOT"
|
||||
|
||||
|
||||
def usable_cpus() -> int | None:
|
||||
@@ -25,8 +27,13 @@ def slot_folder(env: typing.Mapping[str, str], home: pathlib.Path) -> pathlib.Pa
|
||||
|
||||
|
||||
def taken_slot(folder: pathlib.Path, slots: int) -> tuple[int, int] | None:
|
||||
"""The number and open file of a slot this call locked; None while every slot is held. Raises OSError where a slot file cannot be opened or locked."""
|
||||
for slot in range(slots):
|
||||
"""The number and open file of the lowest slot this call locked; None while every slot is held. Raises OSError where a slot file cannot be opened or locked."""
|
||||
return first_free_slot(folder, range(slots))
|
||||
|
||||
|
||||
def first_free_slot(folder: pathlib.Path, order: typing.Iterable[int]) -> tuple[int, int] | None:
|
||||
"""The number and open file of the first slot in order that this call locked; None while every slot in order is held. Raises OSError where a slot file cannot be opened or locked."""
|
||||
for slot in order:
|
||||
fd = os.open(folder / f"slot-{slot}", os.O_RDWR | os.O_CREAT, 0o644)
|
||||
try:
|
||||
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from mattermost_dm import dm, main
|
||||
|
||||
sys.exit(main.main(sys.argv[1:], sys.stdin, lambda: dm.read_config(dm.env_file(pathlib.Path.home())), dm.http_json, sys.stderr))
|
||||
+11
-81
@@ -1,32 +1,17 @@
|
||||
"""Sends a direct message from a Mattermost bot to one user, through Mattermost's REST API v4."""
|
||||
"""Sends a direct message from a Mattermost bot to one user, through Mattermost's REST API v4. The `notifier` setting `mattermost` picks it."""
|
||||
import dataclasses
|
||||
import http.client
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
from failure import Failure
|
||||
from rest_client.json_request import Http
|
||||
from rest_client import json_request
|
||||
from rest_client.env_file import read_env
|
||||
|
||||
KEYS = ("MATTERMOST_URL", "MATTERMOST_TOKEN", "MATTERMOST_RECIPIENT")
|
||||
# Seconds each connect and each read may wait, so an unreachable server holds loop-claude's interrupt only briefly.
|
||||
TIMEOUT = 10
|
||||
|
||||
# Sends a request, the body as JSON where there is one, and returns the JSON answer, or a Failure saying why there is none.
|
||||
Http = typing.Callable[[str, str, str, object], object]
|
||||
|
||||
|
||||
class NoRedirect(urllib.request.HTTPRedirectHandler):
|
||||
"""Refuses every redirect, which Mattermost's API never sends: urllib would resend the token to the new location, even one off https."""
|
||||
|
||||
def redirect_request(self, *args: typing.Any, **kwargs: typing.Any) -> None:
|
||||
return None
|
||||
|
||||
|
||||
OPENER = urllib.request.build_opener(NoRedirect)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Config:
|
||||
@@ -35,43 +20,17 @@ class Config:
|
||||
recipient: str
|
||||
|
||||
|
||||
def env_file(home: pathlib.Path) -> pathlib.Path:
|
||||
return home / ".claude" / ".env"
|
||||
|
||||
|
||||
def read_config(path: pathlib.Path) -> Config | Failure:
|
||||
"""The server, bot token and recipient that path's KEY=value lines hold."""
|
||||
try:
|
||||
mode = path.stat().st_mode
|
||||
text = path.read_text(encoding="utf-8")
|
||||
except FileNotFoundError:
|
||||
return Failure(f"{path} does not exist; it needs {', '.join(KEYS[:-1])} and {KEYS[-1]}")
|
||||
except (OSError, UnicodeDecodeError) as failure:
|
||||
return Failure(f"cannot read {path}: {failure}")
|
||||
if mode & 0o077:
|
||||
return Failure(f"{path} holds the bot's token, so only its owner may read it; run chmod 600 {path}")
|
||||
values = parse_env(text)
|
||||
if missing := [key for key in KEYS if not values.get(key)]:
|
||||
return Failure(f"{path} lacks {' and '.join(missing)}")
|
||||
values = read_env(path, KEYS, "the bot's token")
|
||||
if isinstance(values, Failure):
|
||||
return values
|
||||
url, token, recipient = (values[key] for key in KEYS)
|
||||
if not url.startswith("https://"):
|
||||
return Failure(f"{path} → MATTERMOST_URL must start with https://, so the token is never sent in the clear")
|
||||
return Config(url.rstrip("/"), token, recipient)
|
||||
|
||||
|
||||
def parse_env(text: str) -> dict[str, str]:
|
||||
values = {}
|
||||
for line in text.splitlines():
|
||||
key, equals, value = line.partition("=")
|
||||
if not equals or key.lstrip().startswith("#"):
|
||||
continue
|
||||
value = value.strip()
|
||||
if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
|
||||
value = value[1:-1]
|
||||
values[key.strip()] = value
|
||||
return values
|
||||
|
||||
|
||||
def send(config: Config, message: str, http: Http) -> Failure | None:
|
||||
api = f"{config.url}/api/v4"
|
||||
bot = id_of(http("GET", f"{api}/users/me", config.token, None), "GET /api/v4/users/me")
|
||||
@@ -95,41 +54,12 @@ def id_of(answer: object, request: str) -> str | Failure:
|
||||
|
||||
|
||||
def http_json(method: str, url: str, token: str, body: object) -> object:
|
||||
"""The JSON that url answers; a Failure naming the server where it cannot be reached, and the request where it answers an error, breaks HTTP or answers something other than JSON."""
|
||||
request_name = f"{method} {urllib.parse.urlsplit(url).path}"
|
||||
data = None if body is None else json.dumps(body).encode()
|
||||
request = urllib.request.Request(url, data, {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, method=method)
|
||||
try:
|
||||
with OPENER.open(request, timeout=TIMEOUT) as response:
|
||||
raw = response.read()
|
||||
except urllib.error.HTTPError as failure:
|
||||
with failure:
|
||||
return Failure(f"{request_name} answered {failure.code}: {error_message(failure) or failure.reason}")
|
||||
except http.client.HTTPException as failure:
|
||||
return Failure(f"{request_name} got a broken answer: {failure!r}")
|
||||
except (OSError, ValueError) as failure:
|
||||
server = urllib.parse.urlunsplit(urllib.parse.urlsplit(url)[:2] + ("", "", ""))
|
||||
return Failure(f"cannot reach {server}: {getattr(failure, 'reason', failure)}")
|
||||
try:
|
||||
return json.loads(raw)
|
||||
except ValueError:
|
||||
return Failure(f"{request_name} answered with something other than JSON")
|
||||
"""The JSON that url answers to the bot's request, None where the answer has no body, or a Failure saying why there is none."""
|
||||
return json_request.http_json(method, url, f"Bearer {token}", body, TIMEOUT, error_message)
|
||||
|
||||
|
||||
def error_message(failure: urllib.error.HTTPError) -> str:
|
||||
"""Mattermost's message in an error answer; empty where the body is cut short, breaks HTTP or holds none."""
|
||||
try:
|
||||
answer = json.loads(failure.read())
|
||||
except (http.client.HTTPException, OSError, ValueError):
|
||||
return ""
|
||||
def error_message(answer: object) -> str:
|
||||
"""Mattermost's message in the JSON of an error answer; empty where it holds none."""
|
||||
message = answer.get("message") if isinstance(answer, dict) else None
|
||||
return message if isinstance(message, str) else ""
|
||||
|
||||
|
||||
def dm(text: str, home: pathlib.Path, http: Http) -> Failure | None:
|
||||
"""Sends text as home's .claude/.env configures it. A machine without that file hasn't asked for DMs, so there the DM is skipped."""
|
||||
path = env_file(home)
|
||||
if not path.exists():
|
||||
return None
|
||||
config = read_config(path)
|
||||
return config if isinstance(config, Failure) else send(config, text, http)
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
"""Send a direct message from the Mattermost bot to the human.
|
||||
|
||||
usage: mattermost-dm [<message>]
|
||||
|
||||
Sends <message>, or else stdin, from the bot to the recipient that ~/.claude/.env names. That file
|
||||
holds three KEY=value lines, and only its owner may read it, since it holds the bot's token:
|
||||
|
||||
MATTERMOST_URL=https://chat.example
|
||||
MATTERMOST_TOKEN=<the bot's access token>
|
||||
MATTERMOST_RECIPIENT=<the recipient's username>
|
||||
|
||||
Exit 0 once the message is sent.
|
||||
Exit 1, saying why, when Mattermost cannot be reached or refuses the message.
|
||||
Exit 2, saying why, on misuse: bad arguments, an empty message, or a ~/.claude/.env that is
|
||||
missing or unreadable, lacks a key, names a server off https, or that others may read.
|
||||
"""
|
||||
import typing
|
||||
|
||||
from mattermost_dm.dm import Config, Http, send
|
||||
from failure import Failure
|
||||
|
||||
USAGE = "usage: mattermost-dm [<message>]"
|
||||
|
||||
|
||||
def main(argv: list[str], stdin: typing.TextIO, config: typing.Callable[[], Config | Failure], http: Http, stderr: typing.TextIO) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
if len(argv) > 1:
|
||||
print(f"mattermost-dm: takes one message, or none to read stdin; got {len(argv)} arguments\n{USAGE}", file=stderr)
|
||||
return 2
|
||||
message = (argv[0] if argv else stdin.read()).strip()
|
||||
if not message:
|
||||
print("mattermost-dm: the message is empty", file=stderr)
|
||||
return 2
|
||||
found = config()
|
||||
if isinstance(found, Failure):
|
||||
print(f"mattermost-dm: {found.reason}", file=stderr)
|
||||
return 2
|
||||
if failed := send(found, message, http):
|
||||
print(f"mattermost-dm: {failed.reason}", file=stderr)
|
||||
return 1
|
||||
return 0
|
||||
@@ -1,22 +1,14 @@
|
||||
import http.server
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import socket
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import threading
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from mattermost_dm import dm, main
|
||||
from mattermost_dm import dm
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
|
||||
TOOL = pathlib.Path(__file__).resolve().parents[1] / "mattermost-dm"
|
||||
CONFIG = dm.Config("https://chat.example", "secret-token", "lilleman")
|
||||
|
||||
|
||||
@@ -108,160 +100,17 @@ class Send(unittest.TestCase):
|
||||
self.assertEqual(dm.send(CONFIG, "Which one?", server), Failure("POST /api/v4/posts answered 403: You do not have the appropriate permissions."))
|
||||
|
||||
|
||||
class Recorded(http.server.BaseHTTPRequestHandler):
|
||||
"""Answers each request with the server's next scripted status and body, recording what it got."""
|
||||
|
||||
def do_GET(self) -> None:
|
||||
self.answer()
|
||||
|
||||
def do_POST(self) -> None:
|
||||
self.answer()
|
||||
|
||||
def answer(self) -> None:
|
||||
length = int(self.headers.get("Content-Length") or 0)
|
||||
self.server.got.append((self.command, self.path, dict(self.headers), self.rfile.read(length))) # type: ignore[attr-defined]
|
||||
status, body = self.server.script.pop(0) # type: ignore[attr-defined]
|
||||
if status is None:
|
||||
# Raw bytes, as a server that breaks HTTP sends them.
|
||||
self.wfile.write(body)
|
||||
self.close_connection = True
|
||||
return
|
||||
self.send_response(status)
|
||||
if 300 <= status < 400:
|
||||
self.send_header("Location", "/elsewhere")
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
|
||||
def log_message(self, format: str, *args: object) -> None:
|
||||
pass
|
||||
|
||||
|
||||
class HttpJson(unittest.TestCase):
|
||||
def serve(self, *script: tuple[int, bytes]) -> str:
|
||||
server = http.server.HTTPServer(("127.0.0.1", 0), Recorded)
|
||||
server.script = list(script) # type: ignore[attr-defined]
|
||||
server.got = [] # type: ignore[attr-defined]
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
self.addCleanup(server.server_close)
|
||||
self.addCleanup(server.shutdown)
|
||||
self.server = server
|
||||
return f"http://127.0.0.1:{server.server_port}"
|
||||
def test_sends_the_token_as_a_bearer_and_reads_mattermosts_message_from_an_error(self):
|
||||
with unittest.mock.patch.object(dm.json_request, "http_json", return_value={"id": "post-id"}) as sent:
|
||||
self.assertEqual(dm.http_json("POST", "https://chat.example/api/v4/posts", "secret-token", {"message": "hi"}), {"id": "post-id"})
|
||||
sent.assert_called_once_with("POST", "https://chat.example/api/v4/posts", "Bearer secret-token", {"message": "hi"}, dm.TIMEOUT, dm.error_message)
|
||||
self.assertEqual(dm.TIMEOUT, 10)
|
||||
|
||||
def test_sends_the_token_as_a_bearer_and_the_body_as_json_and_reads_the_json_answer(self):
|
||||
base = self.serve((201, b'{"id": "post-id"}'))
|
||||
self.assertEqual(dm.http_json("POST", f"{base}/api/v4/posts", "secret-token", {"message": "hi"}), {"id": "post-id"})
|
||||
[(method, path, headers, body)] = self.server.got # type: ignore[attr-defined]
|
||||
self.assertEqual((method, path, headers["Authorization"], headers["Content-Type"], json.loads(body)), ("POST", "/api/v4/posts", "Bearer secret-token", "application/json", {"message": "hi"}))
|
||||
|
||||
def test_names_the_request_the_status_and_mattermosts_message_on_an_error(self):
|
||||
base = self.serve((401, b'{"message": "Invalid or expired session, please login again."}'))
|
||||
self.assertEqual(dm.http_json("GET", f"{base}/api/v4/users/me", "bad", None), Failure("GET /api/v4/users/me answered 401: Invalid or expired session, please login again."))
|
||||
|
||||
def test_follows_no_redirect_so_the_token_goes_only_to_the_server_named(self):
|
||||
base = self.serve((302, b"{}"))
|
||||
self.assertEqual(dm.http_json("GET", f"{base}/api/v4/users/me", "t", None), Failure("GET /api/v4/users/me answered 302: Found"))
|
||||
self.assertEqual(len(self.server.got), 1) # type: ignore[attr-defined]
|
||||
|
||||
def test_sends_no_body_with_a_get(self):
|
||||
base = self.serve((200, b'{"id": "bot-id"}'))
|
||||
dm.http_json("GET", f"{base}/api/v4/users/me", "t", None)
|
||||
[(_, _, headers, body)] = self.server.got # type: ignore[attr-defined]
|
||||
self.assertEqual((headers.get("Content-Length"), body), (None, b""))
|
||||
|
||||
def test_fails_on_an_answer_that_breaks_http(self):
|
||||
for raw in (b"garbage\r\n\r\n", b"HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n{}"):
|
||||
with self.subTest(raw=raw):
|
||||
base = self.serve((None, raw))
|
||||
failed = dm.http_json("GET", f"{base}/api/v4/users/me", "t", None)
|
||||
self.assertTrue(isinstance(failed, Failure) and failed.reason.startswith("GET /api/v4/users/me got a broken answer: "), failed)
|
||||
|
||||
def test_names_the_status_of_an_error_whose_body_is_cut_short(self):
|
||||
base = self.serve((None, b"HTTP/1.1 500 Internal Server Error\r\nContent-Length: 100\r\n\r\n{}"))
|
||||
self.assertEqual(dm.http_json("GET", f"{base}/api/v4/users/me", "t", None), Failure("GET /api/v4/users/me answered 500: Internal Server Error"))
|
||||
|
||||
def test_gives_up_on_a_server_that_never_answers_after_the_timeout(self):
|
||||
silent = socket.socket()
|
||||
self.addCleanup(silent.close)
|
||||
silent.bind(("127.0.0.1", 0))
|
||||
silent.listen(1)
|
||||
base = f"http://127.0.0.1:{silent.getsockname()[1]}"
|
||||
with unittest.mock.patch.object(dm, "TIMEOUT", 0.2):
|
||||
self.assertEqual(dm.http_json("GET", f"{base}/api/v4/users/me", "t", None), Failure(f"cannot reach {base}: timed out"))
|
||||
|
||||
def test_fails_on_an_answer_that_is_not_json(self):
|
||||
base = self.serve((200, b"<html>"))
|
||||
self.assertEqual(dm.http_json("GET", f"{base}/api/v4/users/me", "t", None), Failure("GET /api/v4/users/me answered with something other than JSON"))
|
||||
|
||||
def test_fails_naming_the_server_it_cannot_reach(self):
|
||||
base = self.serve()
|
||||
self.server.server_close()
|
||||
failed = dm.http_json("GET", f"{base}/api/v4/users/me", "t", None)
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertTrue(str(getattr(failed, "reason", "")).startswith(f"cannot reach {base}: "), failed)
|
||||
|
||||
|
||||
class Dm(unittest.TestCase):
|
||||
def home_with(self, home: str, text: str) -> pathlib.Path:
|
||||
folder = pathlib.Path(home, ".claude")
|
||||
folder.mkdir()
|
||||
return env_file(str(folder), text)
|
||||
|
||||
def test_sends_through_the_env_file_under_home(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
self.home_with(home, "MATTERMOST_URL=https://chat.example\nMATTERMOST_TOKEN=secret-token\nMATTERMOST_RECIPIENT=lilleman\n")
|
||||
server = mattermost()
|
||||
self.assertIsNone(dm.dm("Which one?", pathlib.Path(home), server))
|
||||
self.assertEqual(server.requests[-1], ("POST", "https://chat.example/api/v4/posts", "secret-token", {"channel_id": "channel-id", "message": "Which one?"}))
|
||||
|
||||
def test_skips_the_dm_on_a_machine_without_the_env_file(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
server = mattermost()
|
||||
self.assertIsNone(dm.dm("Which one?", pathlib.Path(home), server))
|
||||
self.assertEqual(server.requests, [])
|
||||
|
||||
def test_fails_naming_the_mistake_where_the_env_file_is_there_but_wrong(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
path = self.home_with(home, "MATTERMOST_URL=https://chat.example\n")
|
||||
self.assertEqual(dm.dm("Which one?", pathlib.Path(home), mattermost()), Failure(f"{path} lacks MATTERMOST_TOKEN and MATTERMOST_RECIPIENT"))
|
||||
|
||||
|
||||
class Main(unittest.TestCase):
|
||||
def run_main(self, argv: list[str], stdin: str = "", config: object = CONFIG, server: object = None) -> tuple[int, str]:
|
||||
stderr = io.StringIO()
|
||||
sent = server or mattermost()
|
||||
code = main.main(argv, io.StringIO(stdin), lambda: config, sent, stderr) # type: ignore[arg-type]
|
||||
return code, stderr.getvalue()
|
||||
|
||||
def test_sends_its_argument_or_else_stdin_and_exits_0(self):
|
||||
for argv, stdin in ((["Which one?"], ""), ([], "Which one?\n")):
|
||||
with self.subTest(argv=argv):
|
||||
server = mattermost()
|
||||
self.assertEqual(self.run_main(argv, stdin, server=server), (0, ""))
|
||||
self.assertEqual(server.requests[-1][3], {"channel_id": "channel-id", "message": "Which one?"})
|
||||
|
||||
def test_exits_2_on_misuse_naming_it(self):
|
||||
missing = Failure("/h/.claude/.env does not exist; it needs MATTERMOST_URL, MATTERMOST_TOKEN and MATTERMOST_RECIPIENT")
|
||||
for argv, stdin, config, said in (
|
||||
([], " \n", CONFIG, "mattermost-dm: the message is empty\n"),
|
||||
(["a", "b"], "", CONFIG, f"mattermost-dm: takes one message, or none to read stdin; got 2 arguments\n{main.USAGE}\n"),
|
||||
(["hi"], "", missing, f"mattermost-dm: {missing.reason}\n"),
|
||||
):
|
||||
with self.subTest(argv=argv, stdin=stdin):
|
||||
self.assertEqual(self.run_main(argv, stdin, config), (2, said))
|
||||
|
||||
def test_exits_1_naming_why_the_send_failed(self):
|
||||
server = mattermost()
|
||||
server.answers[("GET", "/api/v4/users/me")] = Failure("GET /api/v4/users/me answered 401: Invalid or expired session, please login again.")
|
||||
self.assertEqual(self.run_main(["hi"], server=server), (1, "mattermost-dm: GET /api/v4/users/me answered 401: Invalid or expired session, please login again.\n"))
|
||||
|
||||
def test_the_launcher_prints_help_and_reads_the_env_file_under_home(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
env = {**isolated_env(), "HOME": home}
|
||||
helped = subprocess.run([sys.executable, str(TOOL), "--help"], capture_output=True, text=True, env=env)
|
||||
self.assertEqual((helped.returncode, helped.stdout.splitlines()[0]), (0, main.__doc__.strip().splitlines()[0]))
|
||||
sent = subprocess.run([sys.executable, str(TOOL), "hi"], capture_output=True, text=True, env=env)
|
||||
self.assertEqual((sent.returncode, sent.stderr), (2, f"mattermost-dm: {home}/.claude/.env does not exist; it needs MATTERMOST_URL, MATTERMOST_TOKEN and MATTERMOST_RECIPIENT\n"))
|
||||
def test_reads_mattermosts_message_from_an_error_answer(self):
|
||||
for answer, message in (({"message": "Invalid or expired session."}, "Invalid or expired session."), ({"message": 7}, ""), ({}, ""), (["message"], "")):
|
||||
with self.subTest(answer=answer):
|
||||
self.assertEqual(dm.error_message(answer), message)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
+11
-10
@@ -38,6 +38,7 @@ import sys
|
||||
from metric_bench.bench import bench, co_changed, medians, METRICS, RunScores, Score, tracked_places
|
||||
from review_rules.comprehension_history import entries, Entry
|
||||
from failure import Failure
|
||||
from record_store.stores import FileStore, RecordStore, store
|
||||
from git_cli.git_repo import git
|
||||
from metric_bench.python_units import measured, python_units, Unit
|
||||
from project_config.main import project
|
||||
@@ -64,25 +65,25 @@ def main(argv: list[str]) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
def read_history(given: pathlib.Path | None) -> tuple[str, pathlib.Path, str] | Failure:
|
||||
"""The checkout that holds the history, the history's path and its text."""
|
||||
def read_history(given: pathlib.Path | None) -> tuple[str, str, str] | Failure:
|
||||
"""The checkout that holds the history, the history's label for a message, and the history's text. The history is the file given, else the one in the store the project's config names."""
|
||||
if given and not given.parent.is_dir():
|
||||
return Failure(f"could not read {given}: no folder {given.parent}")
|
||||
found = git("rev-parse", "--show-toplevel", cwd=str(given.parent) if given else None)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
if given:
|
||||
history = given
|
||||
history: RecordStore = FileStore(given, None)
|
||||
elif isinstance(config := project(), Failure):
|
||||
return config
|
||||
else:
|
||||
history = config.paths["comprehension-history"]
|
||||
if not given and not history.exists():
|
||||
return Failure(f"no comprehension history at {history}; larv-review writes one at a project's first paired ruling or scoring run")
|
||||
try:
|
||||
return found.strip(), history, history.read_text(encoding="utf-8")
|
||||
except (OSError, UnicodeDecodeError) as failure:
|
||||
return Failure(f"could not read {history}: {failure}")
|
||||
history = store(config, "comprehension-history")
|
||||
text = history.read()
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
if not text:
|
||||
return Failure(f"no comprehension history at {history.label}; larv-review writes one at a project's first paired ruling or scoring run")
|
||||
return found.strip(), history.label, text
|
||||
|
||||
|
||||
def scored_runs(found: list[Entry]) -> list[Entry]:
|
||||
|
||||
@@ -232,7 +232,7 @@ class BlackBox(unittest.TestCase):
|
||||
|
||||
def test_exits_1_naming_a_history_it_cannot_read_and_unknown_arguments(self):
|
||||
top = self.project("")
|
||||
self.assertIn("could not read", self.run_tool(top, str(pathlib.Path(top, "missing.md"))).stderr)
|
||||
self.assertIn(f"no comprehension history at {top}/missing.md", self.run_tool(top, str(pathlib.Path(top, "missing.md"))).stderr)
|
||||
pathlib.Path(top, "docs", "comprehension-history.md").unlink()
|
||||
self.assertIn("no comprehension history at", self.run_tool(top).stderr)
|
||||
self.assertIn("could not read", self.run_tool(top, str(pathlib.Path(top, "gone", "x.md"))).stderr)
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
"""Send a message from the notifier's bot to the human.
|
||||
|
||||
usage: notify [<message>]
|
||||
|
||||
Sends <message>, or else stdin, through the notifier that a project's config names, from the bot to the
|
||||
recipient that the project's env file names. Run it inside the project's checkout, or a worktree of it.
|
||||
The project's config, ~/.claude-projects/<key>/config.toml, sets `notifier` to "mattermost" or "slack"
|
||||
and `env-file` to a path outside the checkout and the config's folder, such as
|
||||
"~/.claude-projects/<key>.env". The env file holds the notifier's KEY=value lines, and only its owner
|
||||
may read it, since it holds the bot's token. For mattermost:
|
||||
|
||||
MATTERMOST_URL=https://chat.example
|
||||
MATTERMOST_TOKEN=<the bot's access token>
|
||||
MATTERMOST_RECIPIENT=<the recipient's username>
|
||||
|
||||
For slack, a bot token with the `chat:write` scope, and the recipient's member ID, which Slack shows
|
||||
under Profile → ⋮ → Copy member ID:
|
||||
|
||||
SLACK_TOKEN=<the bot's token, xoxb-…>
|
||||
SLACK_RECIPIENT=<the recipient's member ID, U…>
|
||||
|
||||
Exit 0 once the message is sent.
|
||||
Exit 1, saying why, when the notifier cannot be reached or refuses the message.
|
||||
Exit 2, saying why, on misuse: bad arguments, an empty message, a directory with no project config,
|
||||
a config that sets no `notifier` or no `env-file`, or an env file that is missing or unreadable, lacks
|
||||
a key, names a Mattermost server off https, or that others may read. None of these messages holds the
|
||||
token.
|
||||
"""
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from notifier.notify import Sender
|
||||
|
||||
USAGE = "usage: notify [<message>]"
|
||||
|
||||
|
||||
def main(argv: list[str], stdin: typing.TextIO, sender: typing.Callable[[], Sender | Failure], stderr: typing.TextIO) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
if len(argv) > 1:
|
||||
print(f"notify: takes one message, or none to read stdin; got {len(argv)} arguments\n{USAGE}", file=stderr)
|
||||
return 2
|
||||
message = (argv[0] if argv else stdin.read()).strip()
|
||||
if not message:
|
||||
print("notify: the message is empty", file=stderr)
|
||||
return 2
|
||||
found = sender()
|
||||
if isinstance(found, Failure):
|
||||
print(f"notify: {found.reason}", file=stderr)
|
||||
return 2
|
||||
if failed := found(message):
|
||||
print(f"notify: {failed.reason}", file=stderr)
|
||||
return 1
|
||||
return 0
|
||||
@@ -0,0 +1,61 @@
|
||||
"""Sends a DM through the notifier that a project's config names."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from rest_client.json_request import Http
|
||||
from project_config.main import located
|
||||
import mattermost_dm.dm
|
||||
from project_config.settings import Notifier, NOTIFIER, NOTIFIERS, ProjectConfig
|
||||
import slack_dm.dm
|
||||
|
||||
# Sends one message, with the credentials already read.
|
||||
Sender = typing.Callable[[str], Failure | None]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Backend[C]:
|
||||
"""What one notifier needs: `read_config` reads its credentials from an env file, and returns what `send` takes as its config; `send` posts a message with them through `http`; `keys` are the env file's keys."""
|
||||
read_config: typing.Callable[[pathlib.Path], C | Failure]
|
||||
send: typing.Callable[[C, str, Http], Failure | None]
|
||||
http: Http
|
||||
keys: tuple[str, ...]
|
||||
|
||||
|
||||
# The one place each notifier is wired to the network: a caller that tests a send passes a table with its own `http`.
|
||||
BACKENDS: dict[Notifier, Backend[typing.Any]] = {
|
||||
"mattermost": Backend(mattermost_dm.dm.read_config, mattermost_dm.dm.send, mattermost_dm.dm.http_json, mattermost_dm.dm.KEYS),
|
||||
"slack": Backend(slack_dm.dm.read_config, slack_dm.dm.send, slack_dm.dm.http_json, slack_dm.dm.KEYS),
|
||||
}
|
||||
assert tuple(BACKENDS) == NOTIFIERS
|
||||
|
||||
|
||||
def sender_of(project: ProjectConfig, backends: typing.Mapping[Notifier, Backend[typing.Any]]) -> Sender | Failure:
|
||||
"""A sender through the project's notifier in backends, with the credentials in its env file read. A Failure where the project names no notifier or its env file cannot be used."""
|
||||
if project.notifier is None:
|
||||
return Failure(f"{project.folder / 'config.toml'} sets no `{NOTIFIER}`; set `notifier` to {' or '.join(NOTIFIERS)}, and `env-file` to the file that holds that service's keys ({'; '.join(f'{name}: {', '.join(backend.keys)}' for name, backend in backends.items())})")
|
||||
if project.env_file is None:
|
||||
return Failure(f"{project.folder / 'config.toml'} sets `{NOTIFIER}` but no `env-file`, the file that holds its credentials")
|
||||
backend = backends[project.notifier]
|
||||
config = backend.read_config(project.env_file)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
return lambda message: backend.send(config, message, backend.http)
|
||||
|
||||
|
||||
def notify(text: str, directory: str | None, home: pathlib.Path, backends: typing.Mapping[Notifier, Backend[typing.Any]]) -> Failure | None:
|
||||
"""Sends text through the notifier of the project whose checkout holds directory.
|
||||
|
||||
The DM is skipped where the config names no notifier, since the project hasn't asked for DMs. It is skipped too where no config can be read: loop-claude has stopped with that reason, and without a config there is no notifier to ask."""
|
||||
project = located(directory, home)
|
||||
if isinstance(project, Failure) or project.notifier is None:
|
||||
return None
|
||||
sender = sender_of(project, backends)
|
||||
return sender if isinstance(sender, Failure) else sender(text)
|
||||
|
||||
|
||||
def sender_in(directory: str | None, home: pathlib.Path, backends: typing.Mapping[Notifier, Backend[typing.Any]]) -> Sender | Failure:
|
||||
"""sender_of the project whose checkout holds directory."""
|
||||
project = located(directory, home)
|
||||
return project if isinstance(project, Failure) else sender_of(project, backends)
|
||||
@@ -0,0 +1,179 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import typing
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.test_project_config import configured
|
||||
from failure import Failure
|
||||
from rest_client.json_request import Http
|
||||
from test_env import isolated_env
|
||||
from project_config.main import located
|
||||
from notifier import main, notify
|
||||
from mattermost_dm.test_mattermost_dm import mattermost
|
||||
from project_config.settings import Notifier
|
||||
from slack_dm.test_slack_dm import Slack
|
||||
from loop_effects.effects import system_effects
|
||||
|
||||
TOOL = pathlib.Path(__file__).resolve().parents[1] / "notify"
|
||||
MATTERMOST_KEYS = "MATTERMOST_URL=https://chat.example\nMATTERMOST_TOKEN=secret-token\nMATTERMOST_RECIPIENT=lilleman\n"
|
||||
SLACK_KEYS = "SLACK_TOKEN=xoxb-secret\nSLACK_RECIPIENT=U0123ABCD\n"
|
||||
MATTERMOST_POST = ("POST", "https://chat.example/api/v4/posts", "secret-token", {"channel_id": "channel-id", "message": "Which one?"})
|
||||
SLACK_POST = ("POST", "https://slack.com/api/chat.postMessage", "xoxb-secret", {"channel": "U0123ABCD", "text": "Which one?"})
|
||||
MISSING_MATTERMOST = "does not exist; it needs MATTERMOST_URL, MATTERMOST_TOKEN and MATTERMOST_RECIPIENT"
|
||||
|
||||
|
||||
def through(name: Notifier, http: Http) -> dict[Notifier, notify.Backend[typing.Any]]:
|
||||
"""The notifier table with the named backend sending through http."""
|
||||
return {**notify.BACKENDS, name: dataclasses.replace(notify.BACKENDS[name], http=http)}
|
||||
|
||||
|
||||
class Project(unittest.TestCase):
|
||||
"""A home with a git checkout that a config names; `folder` is the config's folder."""
|
||||
|
||||
def setUp(self) -> None:
|
||||
made = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(made.cleanup)
|
||||
self.home = pathlib.Path(made.name).resolve()
|
||||
self.checkout = self.home / "code" / "proj"
|
||||
self.checkout.mkdir(parents=True)
|
||||
self.folder = configured(self, self.checkout, home=self.home)
|
||||
|
||||
def name_notifier(self, notifier: str | None, keys: str | None = None) -> pathlib.Path:
|
||||
"""Makes the config name ~/.claude-projects/proj.env as its env file, and the notifier where there is one; the file holds keys where that is not None."""
|
||||
with (self.folder / "config.toml").open("a") as config:
|
||||
config.write('env-file = "~/.claude-projects/proj.env"\n' + (f'notifier = "{notifier}"\n' if notifier else ""))
|
||||
path = self.home / ".claude-projects" / "proj.env"
|
||||
if keys is not None:
|
||||
path.write_text(keys)
|
||||
path.chmod(0o600)
|
||||
return path
|
||||
|
||||
|
||||
class Notify(Project):
|
||||
def test_sends_through_mattermost_where_the_config_names_it(self):
|
||||
self.name_notifier("mattermost", MATTERMOST_KEYS)
|
||||
server = mattermost()
|
||||
self.assertIsNone(notify.notify("Which one?", str(self.checkout), self.home, through("mattermost", server)))
|
||||
self.assertEqual(server.requests[-1], MATTERMOST_POST)
|
||||
|
||||
def test_sends_through_slack_where_the_config_names_it(self):
|
||||
self.name_notifier("slack", SLACK_KEYS)
|
||||
slack = Slack({"ok": True})
|
||||
self.assertIsNone(notify.notify("Which one?", str(self.checkout), self.home, through("slack", slack)))
|
||||
self.assertEqual(slack.requests, [SLACK_POST])
|
||||
|
||||
def test_loop_claudes_dm_goes_through_the_notifier_for_the_project_holding_the_current_directory(self):
|
||||
self.name_notifier("slack", SLACK_KEYS)
|
||||
slack = Slack({"ok": True})
|
||||
with contextlib.chdir(self.checkout):
|
||||
self.assertIsNone(system_effects(through("slack", slack)).dm("Which one?"))
|
||||
self.assertEqual(slack.requests, [SLACK_POST])
|
||||
|
||||
def test_skips_the_notice_for_a_project_that_names_no_notifier_even_where_its_env_file_holds_the_keys(self):
|
||||
self.name_notifier(None, MATTERMOST_KEYS)
|
||||
server = mattermost()
|
||||
self.assertIsNone(notify.notify("Which one?", str(self.checkout), self.home, through("mattermost", server)))
|
||||
self.assertEqual(server.requests, [])
|
||||
|
||||
def test_skips_the_notice_where_no_config_names_the_checkout_since_loop_claude_stops_on_that_itself(self):
|
||||
other = self.home / "code" / "other"
|
||||
other.mkdir()
|
||||
subprocess.run(["git", "init", "--quiet", str(other)], check=True, env=isolated_env())
|
||||
server = mattermost()
|
||||
self.assertIsNone(notify.notify("Which one?", str(other), self.home, through("mattermost", server)))
|
||||
self.assertEqual(server.requests, [])
|
||||
|
||||
def test_fails_naming_the_file_or_the_key_where_the_env_file_is_missing_or_wrong(self):
|
||||
path = self.name_notifier("slack")
|
||||
self.assertEqual(notify.notify("hi", str(self.checkout), self.home, through("slack", Slack({"ok": True}))), Failure(f"{path} does not exist; it needs SLACK_TOKEN and SLACK_RECIPIENT"))
|
||||
path.write_text("SLACK_TOKEN=xoxb-secret\n")
|
||||
path.chmod(0o600)
|
||||
self.assertEqual(notify.notify("hi", str(self.checkout), self.home, through("slack", Slack({"ok": True}))), Failure(f"{path} lacks SLACK_RECIPIENT"))
|
||||
|
||||
def test_the_failure_for_an_unreachable_server_names_the_server_and_not_the_token(self):
|
||||
self.name_notifier("mattermost", MATTERMOST_KEYS.replace("https://chat.example", "https://127.0.0.1:1"))
|
||||
failed = notify.notify("Which one?", str(self.checkout), self.home, notify.BACKENDS)
|
||||
assert isinstance(failed, Failure), failed
|
||||
self.assertIn("cannot reach https://127.0.0.1:1", failed.reason)
|
||||
self.assertNotIn("secret-token", failed.reason)
|
||||
|
||||
def test_sender_in_fails_for_an_env_file_that_no_notifier_reads(self):
|
||||
self.name_notifier(None, MATTERMOST_KEYS)
|
||||
failed = notify.sender_in(str(self.checkout), self.home, notify.BACKENDS)
|
||||
assert isinstance(failed, Failure), failed
|
||||
self.assertIn("sets no `notifier`", failed.reason)
|
||||
|
||||
def test_sender_of_names_the_missing_env_file_for_a_config_built_by_hand_with_a_notifier_and_none(self):
|
||||
self.name_notifier("slack", SLACK_KEYS)
|
||||
project = located(str(self.checkout), self.home)
|
||||
assert not isinstance(project, Failure), project
|
||||
failed = notify.sender_of(dataclasses.replace(project, env_file=None), notify.BACKENDS)
|
||||
self.assertEqual(failed, Failure(f"{self.folder / 'config.toml'} sets `notifier` but no `env-file`, the file that holds its credentials"))
|
||||
|
||||
def test_sender_in_fails_with_the_configs_reason_where_no_config_names_the_checkout(self):
|
||||
other = self.home / "code" / "other"
|
||||
other.mkdir()
|
||||
subprocess.run(["git", "init", "--quiet", str(other)], check=True, env=isolated_env())
|
||||
self.assertIsInstance(notify.sender_in(str(other), self.home, notify.BACKENDS), Failure)
|
||||
|
||||
def test_sender_in_names_the_settings_to_add_where_the_config_names_no_notifier(self):
|
||||
failed = notify.sender_in(str(self.checkout), self.home, notify.BACKENDS)
|
||||
assert isinstance(failed, Failure), failed
|
||||
self.assertEqual(failed.reason, f"{self.folder / 'config.toml'} sets no `notifier`; set `notifier` to mattermost or slack, and `env-file` to the file that holds that service's keys (mattermost: MATTERMOST_URL, MATTERMOST_TOKEN, MATTERMOST_RECIPIENT; slack: SLACK_TOKEN, SLACK_RECIPIENT)")
|
||||
|
||||
|
||||
class Main(Project):
|
||||
def run_main(self, argv: list[str], stdin: str = "", sender: object = None) -> tuple[int, str]:
|
||||
stderr = io.StringIO()
|
||||
ready = sender or (lambda message: None)
|
||||
code = main.main(argv, io.StringIO(stdin), lambda: ready, stderr) # type: ignore[arg-type]
|
||||
return code, stderr.getvalue()
|
||||
|
||||
def test_sends_its_argument_or_else_stdin_and_exits_0(self):
|
||||
for argv, stdin in ((["Which one?"], ""), ([], "Which one?\n")):
|
||||
with self.subTest(argv=argv):
|
||||
sent: list[str] = []
|
||||
self.assertEqual(self.run_main(argv, stdin, lambda message: sent.append(message)), (0, ""))
|
||||
self.assertEqual(sent, ["Which one?"])
|
||||
|
||||
def test_prints_help_for_either_help_flag_whatever_follows_it(self):
|
||||
for argv in (["-h"], ["--help"], ["--help", "extra"]):
|
||||
with self.subTest(argv=argv), contextlib.redirect_stdout(io.StringIO()) as printed:
|
||||
self.assertEqual(self.run_main(argv), (0, ""))
|
||||
self.assertEqual(printed.getvalue(), main.__doc__.strip() + "\n")
|
||||
|
||||
def test_exits_2_on_misuse_naming_it(self):
|
||||
for argv, stdin, said in (
|
||||
([], " \n", "notify: the message is empty\n"),
|
||||
(["a", "b"], "", f"notify: takes one message, or none to read stdin; got 2 arguments\n{main.USAGE}\n"),
|
||||
):
|
||||
with self.subTest(argv=argv, stdin=stdin):
|
||||
self.assertEqual(self.run_main(argv, stdin), (2, said))
|
||||
|
||||
def test_exits_2_naming_the_config_fault_where_there_is_no_sender(self):
|
||||
stderr = io.StringIO()
|
||||
self.assertEqual(main.main(["hi"], io.StringIO(), lambda: Failure("/h/proj.env does not exist"), stderr), 2) # type: ignore[arg-type]
|
||||
self.assertEqual(stderr.getvalue(), "notify: /h/proj.env does not exist\n")
|
||||
|
||||
def test_exits_1_naming_why_the_send_failed(self):
|
||||
failed = Failure("POST /api/chat.postMessage refused the message: invalid_auth")
|
||||
self.assertEqual(self.run_main(["hi"], sender=lambda message: failed), (1, f"notify: {failed.reason}\n"))
|
||||
|
||||
def test_the_launcher_prints_help_and_reads_the_env_file_the_projects_config_names(self):
|
||||
env = {**isolated_env(), "HOME": str(self.home)}
|
||||
helped = subprocess.run([sys.executable, str(TOOL), "--help"], capture_output=True, text=True, env=env, cwd=self.checkout)
|
||||
self.assertEqual((helped.returncode, helped.stdout.splitlines()[0]), (0, main.__doc__.strip().splitlines()[0]))
|
||||
path = self.name_notifier("mattermost")
|
||||
sent = subprocess.run([sys.executable, str(TOOL), "hi"], capture_output=True, text=True, env=env, cwd=self.checkout)
|
||||
self.assertEqual((sent.returncode, sent.stderr), (2, f"notify: {path} {MISSING_MATTERMOST}\n"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Executable
+9
@@ -0,0 +1,9 @@
|
||||
#!/usr/bin/env python3
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from notifier import main, notify
|
||||
|
||||
sys.exit(main.main(sys.argv[1:], sys.stdin, lambda: notify.sender_in(None, pathlib.Path.home(), notify.BACKENDS), sys.stderr))
|
||||
@@ -0,0 +1,99 @@
|
||||
"""What every plan backend must hold, as tests. A backend's test case inherits PlanStoreContract and unittest.TestCase, and builds its store in new_store. record_store.contract is its twin for records."""
|
||||
import typing
|
||||
|
||||
from release_plan.todo_table import BLOCKED_BY, Item, MOVES
|
||||
from failure import Failure
|
||||
from plan_store.stores import Plan, PlanStore, TAGLINE, Written
|
||||
from release_plan.release import release_of
|
||||
|
||||
FIRST = {"Release": "0.1.0", TAGLINE: "Count the runs.", "L": "1", "E": "2", "I": "3", "S": "1", MOVES: "1 by 9"}
|
||||
SECOND = {"Release": "0.2.0", TAGLINE: "Ship the later thing.", "L": "2", "E": "1", "I": "1", "S": "2", MOVES: "1 by 8", "Exempt": "owner"}
|
||||
|
||||
|
||||
class PlanStoreContract:
|
||||
"""Runs against the store new_store returns: a plan that holds no item yet. The project's goals file must hold a goal numbered 1, which the test items move."""
|
||||
assertEqual: typing.Callable[..., None]
|
||||
assertIsInstance: typing.Callable[..., None]
|
||||
assertNotEqual: typing.Callable[..., None]
|
||||
assertTrue: typing.Callable[..., None]
|
||||
|
||||
def new_store(self) -> PlanStore:
|
||||
raise NotImplementedError
|
||||
|
||||
def filed(self, store: PlanStore, fields: dict[str, str], detail: str = "") -> int:
|
||||
written = store.add(fields, detail)
|
||||
assert isinstance(written, Written), written
|
||||
return written.id
|
||||
|
||||
def items(self, store: PlanStore) -> dict[int, Item]:
|
||||
plan = store.read()
|
||||
assert isinstance(plan, Plan), plan
|
||||
return {item.id: item for item in plan.items}
|
||||
|
||||
def test_a_plan_with_no_item_reads_empty(self) -> None:
|
||||
self.assertEqual(self.new_store().read(), Plan([]))
|
||||
|
||||
def test_reads_back_every_field_of_an_item_it_filed(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST, "Why it counts.\n\nA second paragraph, with a | pipe.")
|
||||
item = self.items(store)[id_]
|
||||
self.assertEqual((item.release, item.exempt, item.tagline, item.moves, item.blocked_by), (release_of("0.1.0"), "", "**Count the runs.**", (("1", 9),), ()))
|
||||
self.assertEqual({name: item.scores[name] for name in "LEIS"}, {"L": 1, "E": 2, "I": 3, "S": 1})
|
||||
self.assertEqual(item.detail, "Why it counts.\n\nA second paragraph, with a | pipe.")
|
||||
|
||||
def test_files_each_item_under_its_own_id(self) -> None:
|
||||
store = self.new_store()
|
||||
first = self.filed(store, FIRST)
|
||||
second = self.filed(store, SECOND | {BLOCKED_BY: str(first)})
|
||||
self.assertNotEqual(first, second)
|
||||
held = self.items(store)
|
||||
self.assertEqual(set(held), {first, second})
|
||||
self.assertEqual((held[second].exempt, held[second].blocked_by, held[second].detail), ("owner", (first,), ""))
|
||||
|
||||
def test_an_edit_sets_the_fields_given_and_leaves_the_rest(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST, "Why it counts.")
|
||||
self.assertEqual(store.edit(id_, {"L": "2", TAGLINE: "Count every run."}, None), Written(id_))
|
||||
item = self.items(store)[id_]
|
||||
self.assertEqual((item.scores["L"], item.scores["E"], item.tagline, item.release, item.detail), (2, 2, "**Count every run.**", release_of("0.1.0"), "Why it counts."))
|
||||
|
||||
def test_an_edit_replaces_the_detail_and_an_empty_one_removes_it(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST, "Why it counts.")
|
||||
store.edit(id_, {}, "A new reason.")
|
||||
self.assertEqual(self.items(store)[id_].detail, "A new reason.")
|
||||
store.edit(id_, {}, "")
|
||||
self.assertEqual(self.items(store)[id_].detail, "")
|
||||
|
||||
def test_an_edit_of_the_release_moves_the_item(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST)
|
||||
store.edit(id_, {"Release": "0.3.0"}, None)
|
||||
self.assertEqual(self.items(store)[id_].release, release_of("0.3.0"))
|
||||
self.assertEqual(self.items(store)[id_].detail, "")
|
||||
|
||||
def test_finish_removes_the_item_and_keeps_the_others(self) -> None:
|
||||
store = self.new_store()
|
||||
first, second = self.filed(store, FIRST, "Why it counts."), self.filed(store, SECOND, "Later detail.")
|
||||
self.assertEqual(store.finish(first), Written(first))
|
||||
held = self.items(store)
|
||||
self.assertEqual({id_: item.detail for id_, item in held.items()}, {second: "Later detail."})
|
||||
|
||||
def test_an_id_it_holds_no_item_for_fails_and_changes_nothing(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST, "Why it counts.")
|
||||
before = store.read()
|
||||
self.assertIsInstance(store.edit(id_ + 1, {"L": "2"}, None), Failure)
|
||||
self.assertIsInstance(store.finish(id_ + 1), Failure)
|
||||
self.assertEqual(store.read(), before)
|
||||
|
||||
def test_a_field_out_of_format_fails_and_changes_nothing(self) -> None:
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST)
|
||||
before = store.read()
|
||||
self.assertIsInstance(store.add(FIRST | {"L": "9"}, ""), Failure)
|
||||
self.assertIsInstance(store.edit(id_, {"Release": "soon"}, None), Failure)
|
||||
self.assertEqual(store.read(), before)
|
||||
|
||||
def test_names_itself_for_a_message(self) -> None:
|
||||
self.assertTrue(self.new_store().label.strip())
|
||||
@@ -0,0 +1,55 @@
|
||||
"""Plan stores for tests, held to plan_store.contract like every backend."""
|
||||
import dataclasses
|
||||
|
||||
from plan_store.markdown_edits import bold_cell, plain
|
||||
from plan_store.stores import cells, Plan, Written
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import Item, parse_row, SHAPE, Table
|
||||
|
||||
|
||||
@dataclasses.dataclass
|
||||
class MemoryPlan:
|
||||
"""A plan held in memory, as a tracker holds one: in the order filed, unranked, with no bar. Where fails is set, every read and write fails with it as the reason."""
|
||||
rows: dict[int, dict[str, str]] = dataclasses.field(default_factory=dict)
|
||||
details: dict[int, str] = dataclasses.field(default_factory=dict)
|
||||
next_id: int = 1
|
||||
label: str = "the plan in memory"
|
||||
tracked: str | None = None
|
||||
fails: str | None = None
|
||||
|
||||
def read(self) -> Plan | Failure:
|
||||
if self.fails:
|
||||
return Failure(self.fails)
|
||||
found = [self.item(id_, row) for id_, row in self.rows.items()]
|
||||
return next((item for item in found if isinstance(item, Failure)), None) or Plan([item for item in found if isinstance(item, Item)])
|
||||
|
||||
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
|
||||
return self.put(self.next_id, cells(fields), detail)
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
if id_ not in self.rows:
|
||||
return Failure(f"{self.label} holds no item {id_}")
|
||||
return self.put(id_, self.rows[id_] | cells(fields), self.details.get(id_, "") if detail is None else detail)
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
if self.fails or id_ not in self.rows:
|
||||
return Failure(self.fails or f"{self.label} holds no item {id_}")
|
||||
del self.rows[id_]
|
||||
self.details.pop(id_, None)
|
||||
return Written(id_)
|
||||
|
||||
def put(self, id_: int, row: dict[str, str], detail: str) -> Written | Failure:
|
||||
"""Holds row as item id_, or fails where row's cells don't make an item."""
|
||||
if self.fails:
|
||||
return Failure(self.fails)
|
||||
row = row | {"Item": bold_cell(plain(row.get("Item", "")))}
|
||||
read = self.item(id_, row)
|
||||
if isinstance(read, Failure):
|
||||
return read
|
||||
self.rows[id_], self.details[id_], self.next_id = row, detail.strip(), max(self.next_id, id_ + 1)
|
||||
return Written(id_)
|
||||
|
||||
def item(self, id_: int, row: dict[str, str]) -> Item | Failure:
|
||||
line = "| " + " | ".join({**row, "ID": str(id_)}.get(column, "") for column in SHAPE.columns) + " |"
|
||||
read = parse_row(line, Table(0, SHAPE.columns, [line]))
|
||||
return read if isinstance(read, Failure) else dataclasses.replace(read, detail=self.details.get(id_, ""))
|
||||
@@ -0,0 +1,382 @@
|
||||
"""A plan kept as the child issues of one Jira Cloud epic, read, filed into and finished over Jira's REST API.
|
||||
|
||||
An item is an open child issue. Its ID is the issue's number, so every child must be in the epic's own Jira project: ABC-34 is item 34 of the plan under ABC-12. The summary is the tagline, the description the detail, the earliest Fix Version the release, and an "is blocked by" link a blocker. L, E, I, S, Moves and Exempt sit in one issue property, PROPERTY, which needs no Jira admin to set up; an issue a teammate filed holds none, and reads as an item without scores.
|
||||
|
||||
`add` files an item as a new child issue, marked with FILED_BY, and `finish` moves an item's issue to a done status. edit is a Failure until todo.md's item 382."""
|
||||
import base64
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import re
|
||||
import typing
|
||||
|
||||
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
|
||||
from release_plan.todo_table import BLOCKED_BY, EXEMPTIONS, is_exempt, Item, MOVES, parse_ids, parse_moves, parse_scores, SHAPE
|
||||
from plan_store.markdown_edits import bold_cell, plain, unfit_text
|
||||
from plan_store.stores import cells, Plan, Written
|
||||
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
|
||||
from failure import Failure
|
||||
from rest_client import json_request
|
||||
from release_plan.release import parsed, Release, tagged
|
||||
from rest_client.env_file import read_env
|
||||
|
||||
# One pair of keys for Jira and Confluence: one Atlassian account's API token opens both.
|
||||
KEYS = ("ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN")
|
||||
# The issue property that holds an item's scores, as a JSON object such as {"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}.
|
||||
PROPERTY = "plan-item"
|
||||
ISSUE_KEY = re.compile(r"([A-Z][A-Z0-9_]*)-([0-9]+)")
|
||||
# Seconds each connect and each read may wait.
|
||||
TIMEOUT = 30
|
||||
PAGE = 100
|
||||
# The pages one read asks for at most, so an answer that never names a last page ends the read.
|
||||
MAX_PAGES = 100
|
||||
READ_ONLY = "the loop doesn't edit an issue of a plan in Jira yet: edit it in Jira"
|
||||
# The key in PROPERTY's value that marks an issue the loop filed, and its value. The loop never edits the summary or description of an issue without it, which a person filed.
|
||||
FILED_BY = ("Filed by", "loop")
|
||||
# The issue type of an issue the loop files, which Jira Software's project templates all have; a project without it refuses the issue, saying so.
|
||||
ISSUE_TYPE = "Task"
|
||||
# The name of the link type whose inward side reads "is blocked by", as Jira Cloud ships it.
|
||||
BLOCKS = "Blocks"
|
||||
SECURITY = "security"
|
||||
# The key of the status category Jira Cloud gives every done status.
|
||||
DONE = "done"
|
||||
# What a failed create ends with: a request Jira never answered, or answered brokenly, may still have filed the issue.
|
||||
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {epic} before filing the item again"
|
||||
# What a failed move ends with, for the same reason.
|
||||
PERHAPS_MOVED = "unless Jira refused the request, the issue may have moved: look at {key} before finishing the item again"
|
||||
|
||||
# Sends a request with the Authorization header given, the body as JSON where there is one, and returns the JSON answer, None where the answer has no body, or a Failure saying why there is none.
|
||||
Http = typing.Callable[[str, str, str, object], object]
|
||||
ToMarkdown = typing.Callable[[list[dict[str, typing.Any]]], list[str] | Refused | Failure]
|
||||
ToAdf = typing.Callable[[str], dict[str, typing.Any] | Failure]
|
||||
|
||||
|
||||
def http_json(method: str, url: str, authorization: str, body: object) -> object:
|
||||
return json_request.http_json(method, url, authorization, body, TIMEOUT, error_message)
|
||||
|
||||
|
||||
def error_message(answer: object) -> str:
|
||||
"""Jira's messages in the JSON of an error answer; empty where it holds none."""
|
||||
if not isinstance(answer, dict):
|
||||
return ""
|
||||
messages, errors = answer.get("errorMessages"), answer.get("errors")
|
||||
found = [*(messages if isinstance(messages, list) else []), *(errors.values() if isinstance(errors, dict) else [])]
|
||||
return "; ".join(text for text in found if isinstance(text, str))
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Issue:
|
||||
"""A child issue as Jira answered it, checked to hold what an item is read from."""
|
||||
key: str
|
||||
summary: str
|
||||
description: dict[str, typing.Any] | None
|
||||
fix_versions: tuple[str, ...]
|
||||
# The key of each issue this one "is blocked by".
|
||||
blockers: tuple[str, ...]
|
||||
# PROPERTY's value; an empty object where the issue holds none.
|
||||
scores: object
|
||||
|
||||
@property
|
||||
def number(self) -> int:
|
||||
return number(self.key)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class JiraPlan:
|
||||
"""The plan under epic, read and written with the credentials env_file holds."""
|
||||
epic: Epic
|
||||
env_file: pathlib.Path
|
||||
http: Http = http_json
|
||||
to_markdown: ToMarkdown = adfs_to_markdown
|
||||
to_adf: ToAdf = markdown_to_adf
|
||||
# How a finished item moves; None where the config doesn't say, and then `finish` is a Failure.
|
||||
finish_by: Finish | None = None
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
return self.epic.spelling
|
||||
|
||||
@property
|
||||
def tracked(self) -> str | None:
|
||||
return None
|
||||
|
||||
def read(self) -> Plan | Failure:
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
answered = children(self.epic, authorization, self.http)
|
||||
if isinstance(answered, Failure):
|
||||
return answered
|
||||
issues = [issue_of(raw) for raw in answered]
|
||||
return next((issue for issue in issues if isinstance(issue, Failure)), None) or plan_of([issue for issue in issues if isinstance(issue, Issue)], self.epic, self.to_markdown)
|
||||
|
||||
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
|
||||
"""Files the item as a child issue, which Jira ranks last in the backlog. No bar applies and the goals file isn't read, since a plan in Jira has no place for a formula or a bar yet (todo.md's item 384).
|
||||
|
||||
Jira takes the links after the issue. A link it refuses leaves the issue filed, so the write counts as landed, and a note names each link to make by hand."""
|
||||
filing = filing_of(fields, detail, self.epic)
|
||||
if isinstance(filing, Failure):
|
||||
return filing
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
issue_fields = filing.fields
|
||||
if detail.strip():
|
||||
description = self.to_adf(detail)
|
||||
if isinstance(description, Failure):
|
||||
return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}")
|
||||
issue_fields = issue_fields | {"description": description}
|
||||
version = self.fix_version(filing.release, authorization)
|
||||
if isinstance(version, Failure):
|
||||
return version
|
||||
if filing.blockers and (missing := self.missing_blocker(filing.blockers, authorization)):
|
||||
return missing
|
||||
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": issue_fields | {"fixVersions": [{"name": version}]}, "properties": [{"key": PROPERTY, "value": filing.scores}]})
|
||||
if isinstance(created, Failure):
|
||||
return Failure(f"cannot file the item under {self.epic.key}: {created.reason}; {PERHAPS_FILED.format(epic=self.epic.key)}")
|
||||
key = created.get("key") if isinstance(created, dict) else None
|
||||
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key) or project_of(key) != project_of(self.epic.key):
|
||||
return Failure(f"Jira answered the new issue without an issue key in {project_of(self.epic.key)}; {PERHAPS_FILED.format(epic=self.epic.key)}")
|
||||
notes = []
|
||||
for blocker in filing.blockers:
|
||||
# Jira names the two ends by the link type's sides: the inward issue blocks the outward one, which then reads "is blocked by" it.
|
||||
linked = self.http("POST", f"{self.epic.site}/rest/api/3/issueLink", authorization, {"type": {"name": BLOCKS}, "inwardIssue": {"key": blocker}, "outwardIssue": {"key": key}})
|
||||
if isinstance(linked, Failure):
|
||||
notes.append(f"filed {key}, but cannot link it as blocked by {blocker}: {linked.reason}; link it in Jira")
|
||||
return Written(number(key), tuple(notes))
|
||||
|
||||
def fix_version(self, release: str, authorization: str) -> str | Failure:
|
||||
"""The name of the Jira project's Fix Version for release, which a project may spell with a leading v, as `earliest_release` reads it."""
|
||||
project = project_of(self.epic.key)
|
||||
versions = self.http("GET", f"{self.epic.site}/rest/api/3/project/{project}/versions", authorization, None)
|
||||
if isinstance(versions, Failure):
|
||||
return Failure(f"cannot read {project}'s Fix Versions: {versions.reason}")
|
||||
names = {name for version in versions if isinstance(version, dict) and isinstance(name := version.get("name"), str)} if isinstance(versions, list) else set()
|
||||
return next((name for name in (release, f"v{release}") if name in names), None) or Failure(f"the Jira project {project} has no Fix Version {release} or v{release}; create it in Jira, or file the item under a release it has")
|
||||
|
||||
def missing_blocker(self, blockers: tuple[str, ...], authorization: str) -> Failure | None:
|
||||
"""A Failure naming the first of blockers that is no open child of the epic. `item` reads only an open child as a blocker, so a link to any other issue would be lost on the next read."""
|
||||
answered = children(self.epic, authorization, self.http)
|
||||
if isinstance(answered, Failure):
|
||||
return answered
|
||||
held = {raw.get("key") for raw in answered if isinstance(raw, dict)}
|
||||
return next((Failure(f"{self.label} holds no item {number(blocker)} to be blocked by") for blocker in blockers if blocker not in held), None)
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
return Failure(READ_ONLY)
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
"""Moves item id_'s issue by the transition that the config names, to the status it names. Any open child of the epic may move, whoever filed it."""
|
||||
if self.finish_by is None:
|
||||
return Failure(f"the config names no transition to finish an item by: set `{JIRA_FINISH_TRANSITION}` and `{JIRA_FINISH_STATUS}`, as `project-config --help` shows")
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
answered = children(self.epic, authorization, self.http)
|
||||
if isinstance(answered, Failure):
|
||||
return answered
|
||||
key = f"{project_of(self.epic.key)}-{id_}"
|
||||
if not any(isinstance(raw, dict) and raw.get("key") == key for raw in answered):
|
||||
return Failure(f"{self.label} holds no item {id_}")
|
||||
url = f"{self.epic.site}/rest/api/3/issue/{key}/transitions"
|
||||
offered = self.http("GET", url, authorization, None)
|
||||
if isinstance(offered, Failure):
|
||||
return Failure(f"cannot read {key}'s transitions: {offered.reason}")
|
||||
transition = transition_of(offered, key, self.finish_by)
|
||||
if isinstance(transition, Failure):
|
||||
return transition
|
||||
moved = self.http("POST", url, authorization, {"transition": {"id": transition}})
|
||||
return Failure(f"cannot move {key} by {self.finish_by.transition!r}: {moved.reason}; {PERHAPS_MOVED.format(key=key)}") if isinstance(moved, Failure) else Written(id_)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Filing:
|
||||
"""An item checked and ready to file."""
|
||||
# The new issue's fields, without its description and its Fix Version.
|
||||
fields: dict[str, typing.Any]
|
||||
release: str
|
||||
# PROPERTY's value.
|
||||
scores: dict[str, typing.Any]
|
||||
# The key of each issue the item is blocked by.
|
||||
blockers: tuple[str, ...]
|
||||
|
||||
|
||||
def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failure:
|
||||
"""The issue to file for an item with these fields under epic, or why a field cannot be filed."""
|
||||
named = cells(fields)
|
||||
summary = plain(named.get("Item", "")).strip()
|
||||
if not summary:
|
||||
return Failure("the item has no tagline")
|
||||
if unfit := unfit_text(summary, detail):
|
||||
return unfit
|
||||
release = named.get("Release", "")
|
||||
if parsed(release) is None:
|
||||
return Failure(f"the item's Release {release!r} is not a version such as 1.2.0")
|
||||
# Named so the shared messages read "item to file's L": they open with "item" and an ID, which this item has none of yet.
|
||||
levels = parse_scores("to file", named, SHAPE.score_columns)
|
||||
if isinstance(levels, Failure):
|
||||
return levels
|
||||
moves, exempt = named.get(MOVES, ""), named.get("Exempt", "")
|
||||
if isinstance(unfit_moves := parse_moves("to file", moves), Failure):
|
||||
return unfit_moves
|
||||
if not is_exempt(exempt):
|
||||
return Failure(f"the item's Exempt {exempt!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
|
||||
blockers = parse_ids(named.get(BLOCKED_BY, ""))
|
||||
if blockers is None:
|
||||
return Failure(f"the item's {BLOCKED_BY} {named[BLOCKED_BY]!r} is not empty or IDs separated by \", \"")
|
||||
project = project_of(epic.key)
|
||||
issue_fields: dict[str, typing.Any] = {"project": {"key": project}, "parent": {"key": epic.key}, "issuetype": {"name": ISSUE_TYPE}, "summary": summary}
|
||||
if exempt == SECURITY:
|
||||
issue_fields["labels"] = [SECURITY]
|
||||
value = levels | {MOVES: moves, "Exempt": exempt, FILED_BY[0]: FILED_BY[1]}
|
||||
return Filing(issue_fields, release, value, tuple(f"{project}-{blocker}" for blocker in blockers))
|
||||
|
||||
|
||||
def offer_of(raw: object) -> tuple[str, str, str, str] | None:
|
||||
"""One transition Jira offers, as its ID, its name, the name of the status it leads to and the key of that status's category; None where raw holds no such transition."""
|
||||
to = raw.get("to") if isinstance(raw, dict) else None
|
||||
category = to.get("statusCategory") if isinstance(to, dict) else None
|
||||
if not isinstance(raw, dict) or not isinstance(to, dict) or not isinstance(category, dict):
|
||||
return None
|
||||
id_, name, status, key = raw.get("id"), raw.get("name"), to.get("name"), category.get("key")
|
||||
return (id_, name, status, key) if isinstance(id_, str) and isinstance(name, str) and isinstance(status, str) and isinstance(key, str) else None
|
||||
|
||||
|
||||
def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
|
||||
"""The ID of the transition finish names, among those Jira offered for the issue named key, which are the ones its present status has; or why none of them finishes the item."""
|
||||
raw = offered.get("transitions") if isinstance(offered, dict) else None
|
||||
found = [offer for each in raw if (offer := offer_of(each))] if isinstance(raw, list) else []
|
||||
if not isinstance(raw, list) or len(found) != len(raw):
|
||||
return Failure(f"Jira answered {key}'s transitions in a shape other than the one it documents")
|
||||
named = [each for each in found if each[1] == finish.transition]
|
||||
if not named:
|
||||
others = " and ".join(f"{name!r} to {status!r}" for _, name, status, _ in found)
|
||||
return Failure(f"{key} has no transition {finish.transition!r} from its status, " + (f"only {others}: move the issue in Jira to a status that has it, or name in `{JIRA_FINISH_TRANSITION}` one that leads to a done status" if found else "nor any other the account may make"))
|
||||
id_, _, status, category = next((each for each in named if each[2] == finish.status), named[0])
|
||||
if status != finish.status:
|
||||
return Failure(f"{key}'s transition {finish.transition!r} leads to the status {status!r}, not to {finish.status!r}, which `{JIRA_FINISH_STATUS}` names")
|
||||
# `children` reads an issue as finished by its status's category, so a move to any other category would leave the item in the plan.
|
||||
if category != DONE:
|
||||
return Failure(f"{key}'s transition {finish.transition!r} leads to the status {status!r}, which Jira doesn't count as done, so the item would stay in the plan: name a transition to a done status")
|
||||
return id_
|
||||
|
||||
|
||||
def project_of(key: str) -> str:
|
||||
"""The key of the Jira project an issue key lies in."""
|
||||
return key.rpartition("-")[0]
|
||||
|
||||
|
||||
def basic_auth(env_file: pathlib.Path) -> str | Failure:
|
||||
"""The Authorization header for the email and API token that env_file holds."""
|
||||
values = read_env(env_file, KEYS, "an API token")
|
||||
if isinstance(values, Failure):
|
||||
return values
|
||||
return "Basic " + base64.b64encode(":".join(values[key] for key in KEYS).encode()).decode()
|
||||
|
||||
|
||||
def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failure:
|
||||
"""The epic's open child issues in backlog order, which is the order the team ranks them in. An issue in a done status is a finished item, so it is no longer in the plan."""
|
||||
# The search answers no issues for an epic the account cannot see, as for one whose children are all done; asking for the epic itself tells them apart.
|
||||
seen = http("GET", f"{epic.site}/rest/api/3/issue/{epic.key}?fields=summary", authorization, None)
|
||||
if isinstance(seen, Failure):
|
||||
return Failure(f"cannot read the epic {epic.key}: {seen.reason}")
|
||||
body: dict[str, object] = {
|
||||
"jql": f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC',
|
||||
"fields": ["summary", "description", "fixVersions", "issuelinks"],
|
||||
"properties": [PROPERTY],
|
||||
"maxResults": PAGE,
|
||||
}
|
||||
found: list[object] = []
|
||||
for _ in range(MAX_PAGES):
|
||||
page = http("POST", f"{epic.site}/rest/api/3/search/jql", authorization, body)
|
||||
if isinstance(page, Failure):
|
||||
return page
|
||||
if not isinstance(page, dict) or not isinstance(page.get("issues"), list):
|
||||
return Failure("the search answered something other than a page of issues")
|
||||
found += page["issues"]
|
||||
if not page.get("nextPageToken"):
|
||||
return found
|
||||
body = body | {"nextPageToken": page["nextPageToken"]}
|
||||
return Failure(f"the search for {epic.key}'s children did not end within {MAX_PAGES} pages")
|
||||
|
||||
|
||||
def issue_of(raw: object) -> Issue | Failure:
|
||||
"""The issue in one entry of the search's answer, or which issue is not in the shape Jira documents, and how."""
|
||||
key = raw.get("key") if isinstance(raw, dict) else None
|
||||
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
|
||||
return Failure("the search answered an issue without an issue key")
|
||||
try:
|
||||
fields = typing.cast(dict[str, typing.Any], raw)["fields"]
|
||||
blockers = tuple(link["inwardIssue"]["key"] for link in fields["issuelinks"] if "inwardIssue" in link and link["type"]["inward"] == "is blocked by")
|
||||
issue = Issue(key, fields["summary"].strip(), fields["description"], tuple(version["name"] for version in fields["fixVersions"]), blockers, typing.cast(dict[str, typing.Any], raw).get("properties", {}).get(PROPERTY, {}))
|
||||
except (AttributeError, KeyError, TypeError) as failure:
|
||||
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: {failure!r}")
|
||||
if not isinstance(issue.description, dict | None) or not all(isinstance(name, str) for name in issue.fix_versions + issue.blockers) or not all(ISSUE_KEY.fullmatch(blocker) for blocker in issue.blockers):
|
||||
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: its description, a Fix Version's name or a linked issue's key holds another kind of value")
|
||||
return issue
|
||||
|
||||
|
||||
def plan_of(issues: list[Issue], epic: Epic, to_markdown: ToMarkdown) -> Plan | Failure:
|
||||
"""The plan the issues hold, in their order."""
|
||||
project = project_of(epic.key)
|
||||
if strangers := [issue.key for issue in issues if project_of(issue.key) != project]:
|
||||
return Failure(f"{strangers[0]} is a child of {epic.key} in another Jira project, and an item's ID is its number in {project}; move it into {project} or out of the epic")
|
||||
ids = {issue.number for issue in issues}
|
||||
items = [item(issue, project, ids) for issue in issues]
|
||||
if failed := next((found for found in items if isinstance(found, Failure)), None):
|
||||
return failed
|
||||
# The descriptions convert last, since that costs a container run, which a read that fails doesn't need.
|
||||
texts = details(issues, epic, to_markdown)
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
return Plan([dataclasses.replace(found, detail=texts.get(found.id, "")) for found in items if isinstance(found, Item)])
|
||||
|
||||
|
||||
def number(key: str) -> int:
|
||||
return int(key.rpartition("-")[2])
|
||||
|
||||
|
||||
def details(issues: list[Issue], epic: Epic, to_markdown: ToMarkdown) -> dict[int, str] | Failure:
|
||||
"""Each described issue's description as markdown, under the issue's number, all converted at once."""
|
||||
described = [(issue, issue.description) for issue in issues if issue.description is not None]
|
||||
texts = to_markdown([description for _, description in described])
|
||||
if isinstance(texts, Refused):
|
||||
return Failure(f"{described[texts.index][0].key}'s description: {texts.failure.reason}")
|
||||
if isinstance(texts, Failure):
|
||||
return Failure(f"cannot convert the descriptions of {epic.key}'s children to markdown: {texts.reason}")
|
||||
return {issue.number: text.strip() for (issue, _), text in zip(described, texts)}
|
||||
|
||||
|
||||
def item(issue: Issue, project: str, ids: set[int]) -> Item | Failure:
|
||||
"""The item an issue holds, without its detail. It is blocked by each of its blockers among ids, the plan's items: a blocker that is done or lies outside the epic doesn't make the item wait."""
|
||||
release = earliest_release(issue.fix_versions)
|
||||
if release is None:
|
||||
# Until a project can tie its releases to something other than semver versions, an item with no release cannot be placed in the plan.
|
||||
return Failure(f"{issue.key} names no Fix Version that is a semver version, such as 1.2.0; set one in Jira")
|
||||
scored = scores(issue.key, issue.scores)
|
||||
if isinstance(scored, Failure):
|
||||
return scored
|
||||
blockers = {number(key) for key in issue.blockers if project_of(key) == project}
|
||||
return Item(issue.number, release, scored[2], bold_cell(issue.summary), scored[0], scored[1], tuple(sorted(blockers & ids)), "")
|
||||
|
||||
|
||||
def earliest_release(names: tuple[str, ...]) -> Release | None:
|
||||
"""The earliest release among Fix Versions named as a semver version, with a leading v or without; None where none is."""
|
||||
releases = [release for name in names if (release := parsed(name) or tagged(name))]
|
||||
return min(releases, default=None)
|
||||
|
||||
|
||||
def scores(key: str, held: object) -> tuple[dict[str, int], typing.Any, typing.Any] | Failure:
|
||||
"""The scores, Moves and Exempt that an issue's PROPERTY value holds, each in the format the items table of a todo.md takes."""
|
||||
if not isinstance(held, dict):
|
||||
return Failure(f"{key}'s issue property {PROPERTY} is not a JSON object")
|
||||
named = {name: str(value) for name, value in held.items()}
|
||||
levels = parse_scores(key, named, SHAPE.score_columns)
|
||||
if isinstance(levels, Failure):
|
||||
return levels
|
||||
moves = parse_moves(key, named.get(MOVES, ""))
|
||||
if isinstance(moves, Failure):
|
||||
return moves
|
||||
exempt = named.get("Exempt", "")
|
||||
if not is_exempt(exempt):
|
||||
return Failure(f"{key}'s issue property {PROPERTY} holds the Exempt {exempt!r}, which is not empty or one of {', '.join(EXEMPTIONS[1:])}")
|
||||
return levels, moves, exempt
|
||||
@@ -0,0 +1,121 @@
|
||||
"""The text edits behind the markdown plan: filing an item in todo.md, changing one and removing one. Each returns new text; ranking.rank then orders the table and details and writes the derived cells."""
|
||||
import re
|
||||
|
||||
from release_plan.todo_table import cells, DETAILS, item_details, items_table, Table
|
||||
from failure import Failure
|
||||
from release_plan.ranking import stated
|
||||
|
||||
# A line that would end ## Details (##) or could open another item's detail (###).
|
||||
HEADING = re.compile(r"^#{2,3} ", re.M)
|
||||
|
||||
|
||||
def added(todo: str, named: dict[str, str], detail: str, label: str) -> tuple[int, str] | Failure:
|
||||
"""todo with an item filed under Next ID, and that ID; named holds its cells by column name, its Item cell the tagline, bold or not."""
|
||||
next_id = stated(todo, "Next ID")
|
||||
if isinstance(next_id, Failure):
|
||||
return next_id
|
||||
if not next_id.isdigit():
|
||||
return Failure(f"Next ID {next_id!r} is not a whole number")
|
||||
tagline = plain(named["Item"])
|
||||
if unfit := unfit_text(tagline, detail):
|
||||
return unfit
|
||||
id_ = int(next_id)
|
||||
lines = re.sub(r"^`Next ID = [0-9]+`$", f"`Next ID = {id_ + 1}`", todo, count=1, flags=re.M).split("\n")
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
row = {**named, "ID": str(id_), "Item": bold_cell(tagline)}
|
||||
lines.insert(table.start + len(table.rows), "| " + " | ".join(row.get(column, "") for column in table.columns) + " |")
|
||||
return id_, with_detail("\n".join(lines), id_, tagline, detail)
|
||||
|
||||
|
||||
def edited(todo: str, id_: int, named: dict[str, str], detail: str | None, label: str) -> str | Failure:
|
||||
"""todo with item id_'s cells set from named, which holds each new value by its column's name, and its detail set to detail unless None; an empty detail removes it. label is what a message calls the file."""
|
||||
lines = todo.split("\n")
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
at = row_index(table, id_, label)
|
||||
if isinstance(at, Failure):
|
||||
return at
|
||||
if absent := [column for column in named if column not in table.columns]:
|
||||
return Failure(f"{label}'s items table has no {', '.join(absent)} column")
|
||||
held = cells(lines[at], len(table.columns))
|
||||
details = item_details(todo)
|
||||
if isinstance(held, Failure):
|
||||
return held
|
||||
if isinstance(details, Failure):
|
||||
return details
|
||||
row = dict(zip(table.columns, held))
|
||||
tagline = plain(named["Item"]) if "Item" in named else plain(row["Item"]).replace("\\|", "|")
|
||||
kept = details.get(id_, "") if detail is None else detail
|
||||
if unfit := unfit_text(tagline, "" if detail is None else detail):
|
||||
return unfit
|
||||
row |= {**named, "Item": bold_cell(tagline)}
|
||||
lines[at] = "| " + " | ".join(row[column] for column in table.columns) + " |"
|
||||
return with_detail(without_detail("\n".join(lines), id_), id_, tagline, kept)
|
||||
|
||||
|
||||
def finished(todo: str, id_: int, label: str) -> str | Failure:
|
||||
"""todo without item id_'s row and its detail."""
|
||||
lines = todo.split("\n")
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
at = row_index(table, id_, label)
|
||||
if isinstance(at, Failure):
|
||||
return at
|
||||
del lines[at]
|
||||
return without_detail("\n".join(lines), id_)
|
||||
|
||||
|
||||
def plain(tagline: str) -> str:
|
||||
return tagline.strip().removeprefix("**").removesuffix("**")
|
||||
|
||||
|
||||
def bold_cell(tagline: str) -> str:
|
||||
"""tagline as the Item cell holds it: bold, each | escaped."""
|
||||
return "**" + re.sub(r"(?<!\\)\|", r"\\|", tagline) + "**"
|
||||
|
||||
|
||||
def unfit_text(tagline: str, detail: str) -> Failure | None:
|
||||
if "\n" in tagline:
|
||||
return Failure("the tagline holds a line break; keep it on one line")
|
||||
if HEADING.search(detail):
|
||||
return Failure("the detail holds a ## or ### heading, which would split ## Details; use #### or drop the #s")
|
||||
return None
|
||||
|
||||
|
||||
def with_detail(text: str, id_: int, tagline: str, detail: str) -> str:
|
||||
"""text with detail first under ## Details, headed by id_ and tagline; text itself where detail is blank."""
|
||||
if not detail.strip():
|
||||
return text
|
||||
entry = f"### {id_}. {tagline}\n\n{detail.strip()}\n"
|
||||
section = DETAILS.search(text)
|
||||
if section is None:
|
||||
return text.rstrip("\n") + f"\n\n## Details\n\n{entry}"
|
||||
return text[:section.start(1)] + f"\n{entry}" + text[section.start(1):]
|
||||
|
||||
|
||||
def without_detail(text: str, id_: int) -> str:
|
||||
section = DETAILS.search(text)
|
||||
if section is None:
|
||||
return text
|
||||
body = re.sub(rf"^### {id_}\. .*?(?=^### \d+\. |\Z)", "", section.group(1), count=1, flags=re.M | re.S)
|
||||
return text[:section.start(1)] + body + text[section.end(1):]
|
||||
|
||||
|
||||
def row_index(table: Table, id_: int, label: str) -> int | Failure:
|
||||
"""The index in the file's lines of item id_'s row."""
|
||||
for at, row in enumerate(table.rows, table.start):
|
||||
found = cells(row, len(table.columns))
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
if found[0] == str(id_):
|
||||
return at
|
||||
return Failure(f"{label} holds no item {id_}")
|
||||
|
||||
|
||||
def held_table(lines: list[str], label: str) -> Table | Failure:
|
||||
table = items_table(lines)
|
||||
return Failure(f"{label} holds no items table; rank_todo.py --help shows one") if table is None else table
|
||||
@@ -0,0 +1,208 @@
|
||||
"""The one way a tool reads or writes a project's plan: through the store its config names.
|
||||
|
||||
The config's `plan` setting names the backend. A path names a markdown file, todo.md. `jira:` and an epic's address name a Jira epic, whose open child issues are the plan: `jira_epic` reads them, and files an item as a new child issue. An agent reads and changes the plan with `todo-item`, which works through the same store.
|
||||
|
||||
A tool that reads what a past commit held, such as `score-outcomes`, still parses that commit's todo.md itself, with `release_plan.todo_table`: only the markdown backend has commits, and todo.md's items 365, 366 and 368 port those tools to the other backends."""
|
||||
import dataclasses
|
||||
import decimal
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from release_plan.todo_table import BLOCKED_BY, Item, item_details, items, MOVES, NoItemsTable, renames
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import file_at, git, Git
|
||||
from record_store.stores import goals_store, store as record_store, RecordStore
|
||||
from plan_store import markdown_edits
|
||||
from project_config.settings import ProjectConfig
|
||||
from release_plan import ranking
|
||||
from release_plan.release import Release
|
||||
from text_files.file_writes import replace_file
|
||||
|
||||
TAGLINE = "Tagline"
|
||||
# What a caller may set on an item, each as text in the format `rank_todo.py --help` states for the cell of that name. TAGLINE is the Item cell, bold or not.
|
||||
FIELDS = ("Release", BLOCKED_BY, "Exempt", TAGLINE, "L", "E", "I", "S", MOVES)
|
||||
|
||||
|
||||
# What the reader of a missing todo.md is told.
|
||||
MISSING = "every project keeps a todo.md, and rank_todo.py --help shows one"
|
||||
# What the reader of a missing or empty goals file is told.
|
||||
GOALS_HINT = "rank_todo.py weighs goals from the goals file the project's config names as goals-and-audience"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Plan:
|
||||
"""A plan as one read found it."""
|
||||
# Each item with its detail, in the order the backend supplies: by release and then by rank for a markdown file, by backlog rank for a tracker.
|
||||
items: list[Item]
|
||||
# The releases the plan marks renamed. Such a release holds no item because its items moved, not because it is finished.
|
||||
renamed: frozenset[Release] = frozenset()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Written:
|
||||
"""A write that landed."""
|
||||
id: int
|
||||
# What the backend says of the plan after the write, for stderr, such as an item now under the bar.
|
||||
notes: tuple[str, ...] = ()
|
||||
|
||||
|
||||
class PlanStore(typing.Protocol):
|
||||
"""A project's plan. plan_store.contract holds every backend that writes to the same behaviour; `jira_epic` reads, files and finishes, and fails an edit until todo.md's item 382. A write that fails leaves the plan as it was, except where its Failure says the tracker may have taken the write all the same, as when Jira's answer to a new issue or to a move is lost."""
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
"""What a message calls the plan, such as its path."""
|
||||
|
||||
@property
|
||||
def tracked(self) -> str | None:
|
||||
"""The plan's path from the checkout's top, as git names a file in a commit; None where no commit holds a version of it, as for a file outside the checkout or a tracker."""
|
||||
|
||||
def read(self) -> Plan | Failure:
|
||||
"""The plan as it stands. A NoItemsTable where the project has not set one up."""
|
||||
|
||||
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
|
||||
"""Files an item under an ID the backend picks. fields holds each of FIELDS the caller sets; detail may be empty."""
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
"""Sets item id_'s fields to those given, and its detail unless None, leaving the rest. Moving an item sets its Release."""
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
"""Removes item id_ with its detail."""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class FilePlan:
|
||||
"""A plan kept as a markdown file at path, in the shape `rank_todo.py --help` shows. Every write ranks the file, reading the goals file from goals, the decision log and the comprehension history."""
|
||||
path: pathlib.Path
|
||||
tracked: str | None
|
||||
goals: RecordStore
|
||||
decisions: RecordStore
|
||||
history: RecordStore
|
||||
# The project's readability floor: while the comprehension overall is under it, ranking weighs code health 4 times as much.
|
||||
floor: decimal.Decimal
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
return str(self.path)
|
||||
|
||||
def read(self) -> Plan | Failure:
|
||||
if not self.path.exists():
|
||||
return NoItemsTable(f"{self.path}: not found; {MISSING}")
|
||||
text = read_text(self.path, MISSING)
|
||||
return text if isinstance(text, Failure) else plan_of(text)
|
||||
|
||||
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
filed = markdown_edits.added(texts[0], cells(fields), detail, self.label)
|
||||
return filed if isinstance(filed, Failure) else self.kept(*filed, texts)
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
text = markdown_edits.edited(texts[0], id_, cells(fields), detail, self.label)
|
||||
return text if isinstance(text, Failure) else self.kept(id_, text, texts)
|
||||
|
||||
def kept(self, id_: int, text: str, texts: tuple[str, str, str, str]) -> Written | Failure:
|
||||
"""Ranks text, the file with item id_ filed or edited, and writes it where the item scores at the bar or above."""
|
||||
ranked = ranking.rank(text, *texts[1:], self.floor)
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
# The write may lower another item under the bar, which the notes then say; the write is refused only where the written item itself scores under the bar.
|
||||
if under := [line for line in ranked.under_bar if line.startswith(f"item {id_} ")]:
|
||||
return Failure(under[0])
|
||||
return self.written(id_, ranked)
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
text = markdown_edits.finished(texts[0], id_, self.label)
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
ranked = ranking.rank(text, *texts[1:], self.floor)
|
||||
return ranked if isinstance(ranked, Failure) else self.written(id_, ranked)
|
||||
|
||||
def written(self, id_: int, ranked: ranking.Ranked) -> Written | Failure:
|
||||
"""Writes ranked's text to the file."""
|
||||
unwritten = replace_file(self.path.resolve(), ranked.text.encode("utf-8"))
|
||||
if unwritten:
|
||||
return Failure(f"{self.path}: {unwritten.reason}")
|
||||
return Written(id_, tuple(f"{self.path}: {line}" for line in ranked.notes + ranked.under_bar))
|
||||
|
||||
def texts(self) -> tuple[str, str, str, str] | Failure:
|
||||
"""What ranking reads: the file, the goals file, the decision log and the comprehension history. The last two are empty when missing; a missing plan, or a goals file that is missing or empty, is a Failure."""
|
||||
plan = read_text(self.path, MISSING)
|
||||
if isinstance(plan, Failure):
|
||||
return plan
|
||||
goals = self.goals.read()
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
if not goals:
|
||||
return Failure(f"{self.goals.label}: missing or empty; {GOALS_HINT}")
|
||||
decisions = self.decisions.read()
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
history = self.history.read()
|
||||
return history if isinstance(history, Failure) else (plan, goals, decisions, history)
|
||||
|
||||
|
||||
def store(config: ProjectConfig) -> PlanStore:
|
||||
"""The store config names for the plan."""
|
||||
if config.epic is None:
|
||||
return file_plan(config)
|
||||
# Imported here, since jira_epic builds on this module's Plan and Written.
|
||||
from plan_store.jira_epic import JiraPlan
|
||||
# load refuses a config that names an epic and no env-file.
|
||||
assert config.env_file is not None
|
||||
return JiraPlan(config.epic, config.env_file, finish_by=config.jira_finish)
|
||||
|
||||
|
||||
def file_plan(config: ProjectConfig, path: pathlib.Path | None = None) -> FilePlan:
|
||||
"""The markdown file config names as its plan, for a tool that works on the file itself, as ranking does. path stands in for the configured one where given."""
|
||||
return FilePlan(path or config.paths["plan"], config.tracked("plan"), goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), config.readability_floor)
|
||||
|
||||
|
||||
def held_at(revision: str, plan: PlanStore, cwd: str, run: Git = git) -> Plan | Failure:
|
||||
"""plan at revision, read in the checkout at cwd, where its commits hold the plan; else as it stands. A NoItemsTable where there is no plan."""
|
||||
if plan.tracked is None:
|
||||
return plan.read()
|
||||
text = file_at(revision, plan.tracked, cwd, run)
|
||||
return text if isinstance(text, Failure) else plan_of(text)
|
||||
|
||||
|
||||
def plan_of(todo: str) -> Plan | Failure:
|
||||
"""The plan a todo.md's text holds."""
|
||||
found = items(todo)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
details = item_details(todo)
|
||||
if isinstance(details, Failure):
|
||||
return details
|
||||
marked = renames(todo)
|
||||
if isinstance(marked, Failure):
|
||||
return marked
|
||||
return Plan([dataclasses.replace(item, detail=details.get(item.id, "")) for item in found], frozenset(marked))
|
||||
|
||||
|
||||
def cells(fields: dict[str, str]) -> dict[str, str]:
|
||||
"""fields by the items table's column names."""
|
||||
unknown = set(fields) - set(FIELDS)
|
||||
if unknown:
|
||||
# A programming error, so nothing catches it: a caller takes its fields from FIELDS.
|
||||
raise ValueError(f"{', '.join(sorted(unknown))}: not a field; the fields are {', '.join(FIELDS)}")
|
||||
return {"Item" if name == TAGLINE else name: value for name, value in fields.items()}
|
||||
|
||||
|
||||
def read_text(path: pathlib.Path, missing: str) -> str | Failure:
|
||||
"""path's text; where it is missing, a Failure saying missing."""
|
||||
try:
|
||||
return path.read_text(encoding="utf-8")
|
||||
except FileNotFoundError:
|
||||
return Failure(f"{path}: not found; {missing}")
|
||||
except OSError as failure:
|
||||
return Failure(f"{path}: {failure.strerror}")
|
||||
except UnicodeDecodeError:
|
||||
return Failure(f"{path}: not UTF-8")
|
||||
@@ -0,0 +1,480 @@
|
||||
import base64
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic, Finish
|
||||
from release_plan.todo_table import EXEMPTIONS
|
||||
from failure import Failure
|
||||
from plan_store import jira_epic
|
||||
from plan_store.stores import Plan, Written
|
||||
from adf_codec.convert import Refused
|
||||
from release_plan.release import release_of
|
||||
|
||||
EPIC = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
SEARCH = "https://acme.atlassian.net/rest/api/3/search/jql"
|
||||
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
|
||||
|
||||
|
||||
def issue(key: str, summary: str = "Count the runs.", versions: tuple[str, ...] = ("0.1.0",), scores: dict[str, object] | None = None, blocked_by: tuple[str, ...] = (), description: object = None, blocks: tuple[str, ...] = ()) -> dict[str, object]:
|
||||
links = [{"type": {"inward": "is blocked by", "outward": "blocks"}, "inwardIssue": {"key": blocker}} for blocker in blocked_by]
|
||||
links += [{"type": {"inward": "is blocked by", "outward": "blocks"}, "outwardIssue": {"key": blocked}} for blocked in blocks]
|
||||
return {
|
||||
"key": key,
|
||||
"fields": {"summary": summary, "description": description, "fixVersions": [{"name": name} for name in versions], "issuelinks": links},
|
||||
"properties": {} if scores is None else {jira_epic.PROPERTY: scores},
|
||||
}
|
||||
|
||||
|
||||
def adf(text: str) -> dict[str, object]:
|
||||
return {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": text}]}]}
|
||||
|
||||
|
||||
def text_of(document: dict[str, object]) -> str | Failure:
|
||||
"""Stands in for the adf-codec shim: the text of the one paragraph adf builds."""
|
||||
return document["content"][0]["content"][0]["text"] + "\n" # type: ignore[index]
|
||||
|
||||
|
||||
class JiraPlan(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env.chmod(0o600)
|
||||
self.pages: list[object] = []
|
||||
self.calls: list[tuple[str, str, str, object]] = []
|
||||
self.epic: object = {"key": "ABC-12"}
|
||||
self.epic_calls: list[tuple[str, str, str, object]] = []
|
||||
self.converted: list[list[dict[str, object]]] = []
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
"""Stands in for Jira: answers self.epic to the request for the epic, and the next of self.pages to each search."""
|
||||
if method == "GET":
|
||||
self.epic_calls.append((method, url, authorization, body))
|
||||
return self.epic
|
||||
self.calls.append((method, url, authorization, body))
|
||||
return self.pages[len(self.calls) - 1]
|
||||
|
||||
def to_markdown(self, documents: list[dict[str, object]]) -> list[str] | Refused | Failure:
|
||||
self.converted.append(documents)
|
||||
return [text_of(document) for document in documents]
|
||||
|
||||
def store(self) -> jira_epic.JiraPlan:
|
||||
return jira_epic.JiraPlan(EPIC, self.env, self.http, self.to_markdown)
|
||||
|
||||
def read(self, *issues: dict[str, object]) -> Plan | Failure:
|
||||
self.pages, self.calls = [{"issues": list(issues)}], []
|
||||
return self.store().read()
|
||||
|
||||
def items(self, *issues: dict[str, object]):
|
||||
plan = self.read(*issues)
|
||||
assert isinstance(plan, Plan), plan
|
||||
return plan.items
|
||||
|
||||
def test_an_epic_with_no_open_child_reads_as_an_empty_plan(self):
|
||||
self.assertEqual(self.read(), Plan([]))
|
||||
|
||||
def test_asks_for_the_epics_open_children_in_backlog_order_with_basic_auth(self):
|
||||
self.read()
|
||||
method, url, authorization, body = self.calls[0]
|
||||
self.assertEqual((method, url), ("POST", SEARCH))
|
||||
self.assertEqual(authorization, AUTHORIZATION)
|
||||
self.assertEqual(body, {
|
||||
"jql": 'parent = "ABC-12" AND statusCategory != Done ORDER BY Rank ASC',
|
||||
"fields": ["summary", "description", "fixVersions", "issuelinks"],
|
||||
"properties": ["plan-item"],
|
||||
"maxResults": 100,
|
||||
})
|
||||
|
||||
def test_an_epic_that_cannot_be_read_fails_the_read_before_any_search(self):
|
||||
self.epic = Failure("GET /rest/api/3/issue/ABC-12 answered 404: Issue does not exist or you do not have permission to see it.")
|
||||
self.assertEqual(self.read(), Failure("cannot read the epic ABC-12: GET /rest/api/3/issue/ABC-12 answered 404: Issue does not exist or you do not have permission to see it."))
|
||||
self.assertEqual(self.epic_calls, [("GET", "https://acme.atlassian.net/rest/api/3/issue/ABC-12?fields=summary", AUTHORIZATION, None)])
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_an_issue_reads_as_an_item_under_its_number(self):
|
||||
scores = {"L": 1, "E": 2, "I": 3, "S": 1, "Moves": "1 by 9", "Exempt": "owner"}
|
||||
item, = self.items(issue("ABC-34", "Count the runs.", ("0.1.0",), scores, description=adf("Why it counts.")))
|
||||
self.assertEqual((item.id, item.release, item.tagline, item.detail), (34, release_of("0.1.0"), "**Count the runs.**", "Why it counts."))
|
||||
self.assertEqual((item.scores, item.moves, item.exempt, item.blocked_by), ({"L": 1, "E": 2, "I": 3, "S": 1}, (("1", 9),), "owner", ()))
|
||||
|
||||
def test_keeps_jiras_order_whatever_the_releases_and_scores(self):
|
||||
found = self.items(issue("ABC-40", versions=("0.2.0",)), issue("ABC-7", versions=("0.1.0",)), issue("ABC-21", versions=("0.3.0",)))
|
||||
self.assertEqual([item.id for item in found], [40, 7, 21])
|
||||
|
||||
def test_an_issue_nobody_scored_reads_without_scores(self):
|
||||
bare = issue("ABC-35")
|
||||
del bare["properties"]
|
||||
for item in self.items(issue("ABC-34"), bare):
|
||||
with self.subTest(item=item.id):
|
||||
self.assertEqual((item.scores, item.moves, item.exempt, item.detail, item.likelihood), ({}, (), "", "", 0))
|
||||
|
||||
def test_an_issue_is_blocked_by_each_blocker_still_in_the_plan(self):
|
||||
blocked, _ = self.items(issue("ABC-34", blocked_by=("ABC-35", "ABC-2", "OTHER-9"), blocks=("ABC-35",)), issue("ABC-35", blocks=("ABC-34",)))
|
||||
self.assertEqual(blocked.blocked_by, (35,))
|
||||
|
||||
def test_the_release_is_the_earliest_fix_version_with_or_without_a_v(self):
|
||||
for versions in (("v1.2.0", "0.9.1", "Later"), ("1.2.0", "v0.9.1")):
|
||||
with self.subTest(versions=versions):
|
||||
item, = self.items(issue("ABC-34", versions=versions))
|
||||
self.assertEqual(item.release, release_of("0.9.1"))
|
||||
|
||||
def test_an_issue_with_no_semver_fix_version_fails_the_read_naming_it(self):
|
||||
for versions in ((), ("Sprint 4",)):
|
||||
with self.subTest(versions=versions):
|
||||
failure = self.read(issue("ABC-33", description=adf("Why.")), issue("ABC-34", versions=versions))
|
||||
self.assertEqual(failure, Failure("ABC-34 names no Fix Version that is a semver version, such as 1.2.0; set one in Jira"))
|
||||
self.assertEqual(self.converted, [])
|
||||
|
||||
def test_a_child_in_another_jira_project_fails_the_read_naming_it(self):
|
||||
failure = self.read(issue("ABC-34"), issue("OTHER-5"))
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("OTHER-5", failure.reason) # type: ignore[union-attr]
|
||||
|
||||
def test_scores_out_of_format_fail_the_read_naming_the_issue(self):
|
||||
for scores in ({"L": 9}, {"L": "high"}, {"Moves": "everything"}, {"Exempt": "because"}, "L 3"):
|
||||
with self.subTest(scores=scores):
|
||||
failure = self.read(issue("ABC-34", scores=scores)) # type: ignore[arg-type]
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("ABC-34", failure.reason) # type: ignore[union-attr]
|
||||
|
||||
def test_an_exempt_out_of_format_fails_naming_the_reasons_it_may_hold(self):
|
||||
self.assertEqual(self.read(issue("ABC-34", scores={"Exempt": "because"})), Failure("ABC-34's issue property plan-item holds the Exempt 'because', which is not empty or one of decision, defect, owner, principle, question, security"))
|
||||
|
||||
def test_reads_every_page(self):
|
||||
self.pages = [{"issues": [issue("ABC-1")], "nextPageToken": "t1"}, {"issues": [issue("ABC-2")]}]
|
||||
plan = self.store().read()
|
||||
self.assertEqual([item.id for item in plan.items], [1, 2]) # type: ignore[union-attr]
|
||||
self.assertNotIn("nextPageToken", self.calls[0][3]) # type: ignore[operator]
|
||||
self.assertEqual(self.calls[1][3]["nextPageToken"], "t1") # type: ignore[index]
|
||||
|
||||
def test_a_failing_request_fails_the_read(self):
|
||||
self.pages = [Failure("POST /rest/api/3/search/jql answered 401: no")]
|
||||
self.assertEqual(self.store().read(), Failure("POST /rest/api/3/search/jql answered 401: no"))
|
||||
|
||||
def test_an_answer_in_another_shape_fails_the_read(self):
|
||||
no_page, no_key = "the search answered something other than a page of issues", "the search answered an issue without an issue key"
|
||||
for page, reason in (([], no_page), ({"issues": "none"}, no_page), ({"issues": ["ABC-1"]}, no_key), ({"issues": [{"key": 7, "fields": {}}]}, no_key), ({"issues": [{"key": "abc", "fields": {}}]}, no_key)):
|
||||
with self.subTest(page=page):
|
||||
self.pages, self.calls = [page], []
|
||||
self.assertEqual(self.store().read(), Failure(reason))
|
||||
|
||||
def test_a_search_that_never_names_a_last_page_fails_the_read(self):
|
||||
self.pages = [{"issues": [], "nextPageToken": "more"}] * 2
|
||||
with unittest.mock.patch.object(jira_epic, "MAX_PAGES", 2):
|
||||
self.assertEqual(self.store().read(), Failure("the search for ABC-12's children did not end within 2 pages"))
|
||||
|
||||
def test_an_issue_in_another_shape_fails_the_read_naming_it(self):
|
||||
good = issue("ABC-1")
|
||||
for wrong in ({"key": "ABC-1"}, issue("ABC-1", summary=None), issue("ABC-1", description="text"), good | {"fields": good["fields"] | {"fixVersions": [{"name": 7}]}}, good | {"fields": good["fields"] | {"issuelinks": [{"type": {"inward": "is blocked by"}, "inwardIssue": {"key": 7}}]}}, good | {"fields": good["fields"] | {"issuelinks": [{"type": {"inward": "is blocked by"}, "inwardIssue": {"key": "ABC-x"}}]}}, good | {"properties": None}): # type: ignore[arg-type, operator]
|
||||
with self.subTest(wrong=wrong):
|
||||
failure = self.read(wrong) # type: ignore[arg-type]
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertTrue(failure.reason.startswith("ABC-1 is not in the shape Jira Cloud's REST API version 3 documents: "), failure) # type: ignore[union-attr]
|
||||
|
||||
def test_converts_every_description_in_one_run_and_none_for_an_issue_without_one(self):
|
||||
found = self.items(issue("ABC-1", description=adf("One.")), issue("ABC-2"), issue("ABC-3", description=adf("Three.")), issue("ABC-4", description=adf("Four.")))
|
||||
self.assertEqual([item.detail for item in found], ["One.", "", "Three.", "Four."])
|
||||
self.assertEqual(self.converted, [[adf("One."), adf("Three."), adf("Four.")]])
|
||||
|
||||
def test_a_description_the_codec_refuses_fails_the_read_naming_the_issue(self):
|
||||
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Refused(1, Failure("adf-codec refused")))
|
||||
self.pages = [{"issues": [issue("ABC-33", description=adf("x")), issue("ABC-34"), issue("ABC-35", description=adf("y"))]}]
|
||||
self.assertEqual(store.read(), Failure("ABC-35's description: adf-codec refused"))
|
||||
|
||||
def test_a_codec_that_cannot_run_fails_the_read(self):
|
||||
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Failure("docker is not installed"))
|
||||
self.pages = [{"issues": [issue("ABC-34", description=adf("x"))]}]
|
||||
self.assertEqual(store.read(), Failure("cannot convert the descriptions of ABC-12's children to markdown: docker is not installed"))
|
||||
|
||||
def test_an_env_file_without_the_credentials_fails_before_any_request(self):
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\n")
|
||||
failure = self.read()
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("ATLASSIAN_API_TOKEN", failure.reason) # type: ignore[union-attr]
|
||||
self.assertEqual(self.calls + self.epic_calls, [])
|
||||
|
||||
def test_an_env_file_others_may_read_fails_before_any_request(self):
|
||||
self.env.chmod(0o644)
|
||||
self.assertEqual(self.read(), Failure(f"{self.env} holds an API token, so only its owner may read it; run chmod 600 {self.env}"))
|
||||
self.assertEqual(self.calls + self.epic_calls, [])
|
||||
|
||||
def test_a_missing_env_file_fails(self):
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.read(), Failure)
|
||||
|
||||
def test_no_failure_holds_the_token(self):
|
||||
self.pages = [{"issues": [issue("OTHER-5")]}]
|
||||
self.assertNotIn("s3cret", self.store().read().reason) # type: ignore[union-attr]
|
||||
|
||||
def test_edit_fails_since_the_store_does_not_edit_yet(self):
|
||||
self.assertEqual(self.store().edit(34, {"L": "2"}, None), Failure("the loop doesn't edit an issue of a plan in Jira yet: edit it in Jira"))
|
||||
self.assertEqual(self.calls + self.epic_calls, [])
|
||||
|
||||
def test_names_itself_by_the_configs_spelling_and_no_commit_holds_it(self):
|
||||
self.assertEqual((self.store().label, self.store().tracked), ("jira:https://acme.atlassian.net/browse/ABC-12", None))
|
||||
|
||||
|
||||
ISSUES = "https://acme.atlassian.net/rest/api/3/issue"
|
||||
LINKS = "https://acme.atlassian.net/rest/api/3/issueLink"
|
||||
VERSIONS = "https://acme.atlassian.net/rest/api/3/project/ABC/versions"
|
||||
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under ABC-12 before filing the item again"
|
||||
FIELDS = {"Release": "0.1.0", "Tagline": "Count the runs.", "L": "1", "E": "2", "I": "3", "S": "1", "Moves": "1 by 9"}
|
||||
PROPERTY = {"L": 1, "E": 2, "I": 3, "S": 1, "Moves": "1 by 9", "Exempt": "", "Filed by": "loop"}
|
||||
|
||||
|
||||
class Filing(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env.chmod(0o600)
|
||||
self.calls: list[tuple[str, str, object]] = []
|
||||
self.open: list[dict[str, object]] = []
|
||||
self.created: object = {"id": "10040", "key": "ABC-40"}
|
||||
self.linked: object = None
|
||||
self.versions: object = [{"name": "0.1.0"}, {"name": "v0.2.0"}, "odd", {"name": ["0.1.0"]}, {"name": {"en": "0.1.0"}}]
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.open to the search, self.created to a new issue and self.linked to a new link."""
|
||||
self.calls.append((method, url, body))
|
||||
assert authorization == AUTHORIZATION
|
||||
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked, VERSIONS: self.versions}.get(url, {"key": "ABC-12"})
|
||||
|
||||
def to_adf(self, markdown: str) -> dict[str, object] | Failure:
|
||||
return adf(markdown)
|
||||
|
||||
def add(self, fields: dict[str, str] = FIELDS, detail: str = ""):
|
||||
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf).add(fields, detail)
|
||||
|
||||
def sent(self, url: str) -> list[object]:
|
||||
return [body for _, sent_to, body in self.calls if sent_to == url]
|
||||
|
||||
def test_files_the_item_as_a_task_under_the_epic_marked_as_the_loops(self):
|
||||
self.assertEqual(self.add(), Written(40))
|
||||
self.assertEqual(self.calls, [("GET", VERSIONS, None), ("POST", ISSUES, {
|
||||
"fields": {"project": {"key": "ABC"}, "parent": {"key": "ABC-12"}, "issuetype": {"name": "Task"}, "summary": "Count the runs.", "fixVersions": [{"name": "0.1.0"}]},
|
||||
"properties": [{"key": "plan-item", "value": PROPERTY}],
|
||||
})])
|
||||
|
||||
def test_a_bold_tagline_is_filed_plain(self):
|
||||
self.add(FIELDS | {"Tagline": "**Count the runs.**"})
|
||||
self.assertEqual(self.sent(ISSUES)[0]["fields"]["summary"], "Count the runs.") # type: ignore[index]
|
||||
|
||||
def test_the_detail_is_the_description_as_adf(self):
|
||||
self.add(detail="Why it counts.")
|
||||
self.assertEqual(self.sent(ISSUES)[0]["fields"]["description"], adf("Why it counts.")) # type: ignore[index]
|
||||
|
||||
def test_a_security_finding_is_labelled_security(self):
|
||||
self.add(FIELDS | {"Exempt": "security"})
|
||||
sent, = self.sent(ISSUES)
|
||||
self.assertEqual((sent["fields"]["labels"], sent["properties"][0]["value"]["Exempt"]), (["security"], "security")) # type: ignore[index]
|
||||
|
||||
def test_no_other_item_is_labelled(self):
|
||||
self.add(FIELDS | {"Exempt": "owner"})
|
||||
self.assertNotIn("labels", self.sent(ISSUES)[0]["fields"]) # type: ignore[index]
|
||||
|
||||
def test_links_the_issue_as_blocked_by_each_blocker_once_filed(self):
|
||||
self.open = [issue("ABC-34"), issue("ABC-35")]
|
||||
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 35"}), Written(40))
|
||||
self.assertEqual([(method, url) for method, url, _ in self.calls][-3:], [("POST", ISSUES), ("POST", LINKS), ("POST", LINKS)])
|
||||
self.assertEqual(self.sent(LINKS), [{"type": {"name": "Blocks"}, "inwardIssue": {"key": f"ABC-{blocker}"}, "outwardIssue": {"key": "ABC-40"}} for blocker in (34, 35)])
|
||||
|
||||
def test_a_blocker_that_is_no_open_child_fails_before_anything_is_filed(self):
|
||||
self.open = [issue("ABC-34")]
|
||||
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 36"}), Failure("jira:https://acme.atlassian.net/browse/ABC-12 holds no item 36 to be blocked by"))
|
||||
self.assertEqual(self.sent(ISSUES), [])
|
||||
|
||||
def test_a_field_out_of_format_fails_before_any_request(self):
|
||||
cases = ({"L": "9"}, {"Release": "soon"}, {"Release": ""}, {"Moves": "much"}, {"Exempt": "whim"}, {"Blocked by": "ABC-34"}, {"Tagline": "Count\nthe runs."}, {"Tagline": " "})
|
||||
for change in cases:
|
||||
with self.subTest(change=change):
|
||||
self.assertIsInstance(self.add(FIELDS | change), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_each_field_out_of_format_fails_saying_how(self):
|
||||
cases = (
|
||||
({"Tagline": "** **"}, "the item has no tagline"),
|
||||
({"L": "9"}, "item to file's L '9' is not a whole number from 1 to 4"),
|
||||
({"Exempt": "whim"}, f"the item's Exempt 'whim' is not empty or one of {', '.join(EXEMPTIONS[1:])}"),
|
||||
({"Blocked by": "ABC-34"}, "the item's Blocked by 'ABC-34' is not empty or IDs separated by \", \""),
|
||||
)
|
||||
for change, reason in cases:
|
||||
with self.subTest(change=change):
|
||||
self.assertEqual(self.add(FIELDS | change), Failure(reason))
|
||||
self.assertEqual(self.add({name: value for name, value in FIELDS.items() if name != "Tagline"}), Failure("the item has no tagline"))
|
||||
|
||||
def test_an_item_without_moves_files_with_none(self):
|
||||
self.assertEqual(self.add({name: value for name, value in FIELDS.items() if name != "Moves"}), Written(40))
|
||||
self.assertEqual(self.sent(ISSUES)[0]["properties"][0]["value"]["Moves"], "") # type: ignore[index]
|
||||
|
||||
def test_a_field_the_plan_does_not_have_is_a_programming_error(self):
|
||||
with self.assertRaises(ValueError):
|
||||
self.add(FIELDS | {"Colour": "red"})
|
||||
|
||||
def test_an_item_without_a_release_fails_naming_the_field(self):
|
||||
self.assertEqual(self.add({name: value for name, value in FIELDS.items() if name != "Release"}), Failure("the item's Release '' is not a version such as 1.2.0"))
|
||||
|
||||
def test_a_detail_that_does_not_convert_fails_before_any_request(self):
|
||||
self.to_adf = lambda markdown: Failure("docker is not running") # type: ignore[method-assign]
|
||||
self.assertEqual(self.add(detail="Why."), Failure("cannot convert the item's detail to a Jira description: docker is not running"))
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_an_item_jira_refuses_fails_with_jiras_reason(self):
|
||||
self.created = Failure("POST /rest/api/3/issue answered 400: Version name '0.1.0' is not valid")
|
||||
self.assertEqual(self.add(), Failure(f"cannot file the item under ABC-12: POST /rest/api/3/issue answered 400: Version name '0.1.0' is not valid; {PERHAPS_FILED}"))
|
||||
|
||||
def test_an_answer_that_names_no_issue_of_the_epics_project_fails(self):
|
||||
for answer in ({}, {"key": 7}, {"key": "OTHER-5"}, ["ABC-40"]):
|
||||
with self.subTest(answer=answer):
|
||||
self.created = answer
|
||||
self.assertEqual(self.add(), Failure(f"Jira answered the new issue without an issue key in ABC; {PERHAPS_FILED}"))
|
||||
|
||||
def test_a_link_jira_refuses_leaves_the_item_filed_with_a_note_and_the_other_links_made(self):
|
||||
refusal = "POST /rest/api/3/issueLink answered 404: No issue link type with name 'Blocks' found."
|
||||
self.open, self.linked = [issue("ABC-34"), issue("ABC-35")], Failure(refusal)
|
||||
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 35"}), Written(40, tuple(f"filed ABC-40, but cannot link it as blocked by ABC-{blocker}: {refusal}; link it in Jira" for blocker in (34, 35))))
|
||||
self.assertEqual(len(self.sent(LINKS)), 2)
|
||||
|
||||
def test_files_under_the_fix_version_as_the_project_spells_it(self):
|
||||
self.assertEqual(self.add(FIELDS | {"Release": "0.2.0"}), Written(40))
|
||||
self.assertEqual(self.sent(ISSUES)[0]["fields"]["fixVersions"], [{"name": "v0.2.0"}]) # type: ignore[index]
|
||||
|
||||
def test_a_release_the_project_has_no_fix_version_for_fails_before_anything_is_filed(self):
|
||||
for versions in ([{"name": "0.1.0"}], {"name": "0.3.0"}, [], 7):
|
||||
with self.subTest(versions=versions):
|
||||
self.versions = versions
|
||||
self.assertEqual(self.add(FIELDS | {"Release": "0.3.0"}), Failure("the Jira project ABC has no Fix Version 0.3.0 or v0.3.0; create it in Jira, or file the item under a release it has"))
|
||||
self.assertEqual(self.sent(ISSUES), [])
|
||||
|
||||
def test_fix_versions_that_cannot_be_read_fail_before_anything_is_filed(self):
|
||||
self.versions = Failure("GET /rest/api/3/project/ABC/versions answered 403: Forbidden")
|
||||
self.assertEqual(self.add(), Failure("cannot read ABC's Fix Versions: GET /rest/api/3/project/ABC/versions answered 403: Forbidden"))
|
||||
self.assertEqual(self.sent(ISSUES), [])
|
||||
|
||||
def test_what_it_files_reads_back_as_the_item(self):
|
||||
self.add(FIELDS | {"Exempt": "owner"}, "Why it counts.")
|
||||
sent, = self.sent(ISSUES)
|
||||
raw = {"key": "ABC-40", "fields": sent["fields"] | {"issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in sent["properties"]}} # type: ignore[index, operator, union-attr]
|
||||
filed = jira_epic.issue_of(raw)
|
||||
assert isinstance(filed, jira_epic.Issue), filed
|
||||
plan = jira_epic.plan_of([filed], EPIC, lambda documents: [text_of(document) for document in documents])
|
||||
assert isinstance(plan, Plan), plan
|
||||
item, = plan.items
|
||||
self.assertEqual((item.id, item.release, item.exempt, item.tagline, item.moves, item.detail), (40, release_of("0.1.0"), "owner", "**Count the runs.**", (("1", 9),), "Why it counts."))
|
||||
self.assertEqual({name: item.scores[name] for name in "LEIS"}, {"L": 1, "E": 2, "I": 3, "S": 1})
|
||||
|
||||
def test_a_missing_env_file_fails_before_any_request(self):
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.add(), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
|
||||
TRANSITIONS = "https://acme.atlassian.net/rest/api/3/issue/ABC-34/transitions"
|
||||
|
||||
|
||||
def transition(id_: str, name: str, status: str, category: str = "done") -> dict[str, object]:
|
||||
return {"id": id_, "name": name, "to": {"name": status, "statusCategory": {"key": category}}}
|
||||
|
||||
|
||||
class Finishing(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env.chmod(0o600)
|
||||
self.calls: list[tuple[str, str, object]] = []
|
||||
self.open = [issue("ABC-34"), issue("ABC-35")]
|
||||
self.transitions: object = {"transitions": [transition("11", "Start", "In Progress", "indeterminate"), transition("31", "Mark as done", "Done")]}
|
||||
self.moved: object = None
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
"""Stands in for Jira: answers the epic, self.open to the search, self.transitions for ABC-34's transitions and self.moved to a transition of it."""
|
||||
self.calls.append((method, url, body))
|
||||
assert authorization == AUTHORIZATION
|
||||
if url == TRANSITIONS:
|
||||
return self.transitions if method == "GET" else self.moved
|
||||
return {SEARCH: {"issues": self.open}}.get(url, {"key": "ABC-12"})
|
||||
|
||||
def finish(self, id_: int = 34, by: Finish | None = Finish("Mark as done", "Done")):
|
||||
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, finish_by=by).finish(id_)
|
||||
|
||||
def posts(self) -> list[tuple[str, str, object]]:
|
||||
return [call for call in self.calls if call[0] == "POST" and call[1] != SEARCH]
|
||||
|
||||
def test_moves_the_issue_by_the_transition_the_config_names(self):
|
||||
self.assertEqual(self.finish(), Written(34))
|
||||
self.assertEqual(self.posts(), [("POST", TRANSITIONS, {"transition": {"id": "31"}})])
|
||||
|
||||
def test_a_config_that_names_no_transition_fails_before_any_request(self):
|
||||
self.assertEqual(self.finish(by=None), Failure("the config names no transition to finish an item by: set `jira-finish-transition` and `jira-finish-status`, as `project-config --help` shows"))
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_an_issue_that_is_no_open_child_of_the_epic_is_not_moved(self):
|
||||
self.assertEqual(self.finish(36), Failure("jira:https://acme.atlassian.net/browse/ABC-12 holds no item 36"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_a_transition_the_issue_does_not_have_fails_naming_those_it_has(self):
|
||||
self.assertEqual(self.finish(by=Finish("Close", "Done")), Failure("ABC-34 has no transition 'Close' from its status, only 'Start' to 'In Progress' and 'Mark as done' to 'Done': move the issue in Jira to a status that has it, or name in `jira-finish-transition` one that leads to a done status"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_a_transition_that_leads_to_another_status_fails(self):
|
||||
self.assertEqual(self.finish(by=Finish("Mark as done", "Closed")), Failure("ABC-34's transition 'Mark as done' leads to the status 'Done', not to 'Closed', which `jira-finish-status` names"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_two_transitions_share_the_name_and_the_one_to_the_status_is_made(self):
|
||||
self.transitions = {"transitions": [transition("30", "Close", "Rejected"), transition("31", "Close", "Done")]}
|
||||
self.assertEqual(self.finish(by=Finish("Close", "Done")), Written(34))
|
||||
self.assertEqual(self.posts(), [("POST", TRANSITIONS, {"transition": {"id": "31"}})])
|
||||
|
||||
def test_a_status_jira_does_not_count_as_done_fails_since_the_item_would_stay_in_the_plan(self):
|
||||
self.assertEqual(self.finish(by=Finish("Start", "In Progress")), Failure("ABC-34's transition 'Start' leads to the status 'In Progress', which Jira doesn't count as done, so the item would stay in the plan: name a transition to a done status"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_an_issue_with_no_transition_fails_saying_so(self):
|
||||
self.transitions = {"transitions": []}
|
||||
self.assertEqual(self.finish(), Failure("ABC-34 has no transition 'Mark as done' from its status, nor any other the account may make"))
|
||||
|
||||
def test_transitions_that_cannot_be_read_fail(self):
|
||||
self.transitions = Failure("HTTP 403")
|
||||
self.assertEqual(self.finish(), Failure("cannot read ABC-34's transitions: HTTP 403"))
|
||||
|
||||
def test_transitions_in_another_shape_fail(self):
|
||||
odd = [transition(31, "Mark as done", "Done"), transition("31", None, "Done"), transition("31", "Mark as done", ["Done"]), transition("31", "Mark as done", "Done", 4), {"id": "31", "name": "Mark as done", "to": "Done"}, {"id": "31", "name": "Mark as done", "to": {"name": "Done"}}, "odd"] # type: ignore[arg-type]
|
||||
for answered in ([], {"transitions": "none"}, *({"transitions": [each]} for each in odd)):
|
||||
with self.subTest(answered=answered):
|
||||
self.transitions = answered
|
||||
self.assertEqual(self.finish(), Failure("Jira answered ABC-34's transitions in a shape other than the one it documents"))
|
||||
|
||||
def test_a_move_jira_refuses_fails_with_jiras_reason(self):
|
||||
self.moved = Failure("HTTP 400: Resolution is required")
|
||||
self.assertEqual(self.finish(), Failure("cannot move ABC-34 by 'Mark as done': HTTP 400: Resolution is required; unless Jira refused the request, the issue may have moved: look at ABC-34 before finishing the item again"))
|
||||
|
||||
def test_a_missing_env_file_fails_before_any_request(self):
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.finish(), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
|
||||
class Requests(unittest.TestCase):
|
||||
def test_sends_each_request_through_the_shared_client_with_jiras_error_messages(self):
|
||||
with unittest.mock.patch.object(jira_epic.json_request, "http_json", return_value={"issues": []}) as sent:
|
||||
self.assertEqual(jira_epic.http_json("POST", SEARCH, AUTHORIZATION, {"jql": "x"}), {"issues": []})
|
||||
sent.assert_called_once_with("POST", SEARCH, AUTHORIZATION, {"jql": "x"}, 30, jira_epic.error_message)
|
||||
|
||||
def test_reads_jiras_messages_from_an_error_answer(self):
|
||||
cases = (
|
||||
({"errorMessages": ["Issue does not exist or you do not have permission to see it."], "errors": {}}, "Issue does not exist or you do not have permission to see it."),
|
||||
({"errorMessages": ["One."], "errors": {"jql": "Two."}}, "One.; Two."),
|
||||
({"errorMessages": "One.", "errors": ["Two."]}, ""),
|
||||
({"errorMessages": [7, "One."]}, "One."),
|
||||
(["One."], ""),
|
||||
)
|
||||
for answer, message in cases:
|
||||
with self.subTest(answer=answer):
|
||||
self.assertEqual(jira_epic.error_message(answer), message)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,220 @@
|
||||
import dataclasses
|
||||
import decimal
|
||||
import os
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import DEFAULT_FLOOR, Epic, Finish, ProjectConfig, SETTINGS
|
||||
from failure import Failure
|
||||
from record_store.stores import FileStore
|
||||
from plan_store.contract import FIRST, MOVES, PlanStoreContract, SECOND
|
||||
from plan_store.jira_epic import JiraPlan
|
||||
from plan_store.fakes import MemoryPlan
|
||||
from record_store.fakes import MemoryStore
|
||||
from release_plan.todo_table import NoItemsTable
|
||||
from release_plan.test_ranking import README, SCORED, VOID
|
||||
from release_plan.release import release_of
|
||||
from plan_store import stores
|
||||
|
||||
EMPTY = "# todo\n\n## Scoring\n\n`Score = 100 * V / 2**S`\n\n`Bar = 2`\n\n`Next ID = 1`\n\n## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
|
||||
|
||||
class MemoryPlanContract(PlanStoreContract, unittest.TestCase):
|
||||
def new_store(self) -> stores.PlanStore:
|
||||
return MemoryPlan()
|
||||
|
||||
|
||||
class FilePlanContract(PlanStoreContract, unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.folder = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
|
||||
|
||||
def new_store(self) -> stores.FilePlan:
|
||||
(self.folder / "todo.md").write_text(EMPTY)
|
||||
(self.folder / "README.md").write_text(README)
|
||||
return stores.FilePlan(self.folder / "todo.md", "todo.md", FileStore(self.folder / "README.md", None), MemoryStore(), MemoryStore(), DEFAULT_FLOOR)
|
||||
|
||||
|
||||
class FilePlan(FilePlanContract):
|
||||
def test_supplies_its_items_by_release_then_score(self):
|
||||
store = self.new_store()
|
||||
later, low, high = self.filed(store, SECOND), self.filed(store, FIRST | {"S": "4"}), self.filed(store, FIRST)
|
||||
plan = store.read()
|
||||
self.assertEqual([item.id for item in plan.items], [high, low, later])
|
||||
|
||||
def test_refuses_an_item_that_scores_under_the_bar_and_says_so(self):
|
||||
store = self.new_store()
|
||||
refused = store.add(FIRST | {"S": "10"}, "")
|
||||
self.assertIsInstance(refused, Failure)
|
||||
self.assertIn("under the bar", refused.reason)
|
||||
self.assertEqual((self.folder / "todo.md").read_text(), EMPTY)
|
||||
|
||||
def test_an_edit_that_puts_the_item_under_the_bar_is_refused(self):
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST)
|
||||
before = (self.folder / "todo.md").read_text()
|
||||
self.assertIsInstance(store.edit(id_, {"S": "10"}, None), Failure)
|
||||
self.assertEqual((self.folder / "todo.md").read_text(), before)
|
||||
|
||||
def test_an_edited_tagline_heads_the_detail_too(self):
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST, "Why it counts.")
|
||||
store.edit(id_, {stores.TAGLINE: "Count `a | b` runs."}, None)
|
||||
text = (self.folder / "todo.md").read_text()
|
||||
self.assertIn("| **Count `a \\| b` runs.** |", text)
|
||||
self.assertIn(f"### {id_}. Count `a | b` runs.\n\nWhy it counts.\n", text)
|
||||
self.assertNotIn("Count the runs.", text)
|
||||
|
||||
def test_a_write_notes_what_ranking_says_under_the_files_path(self):
|
||||
store = self.new_store()
|
||||
self.filed(store, FIRST)
|
||||
(self.folder / "todo.md").write_text((self.folder / "todo.md").read_text().replace("| 4 | 1 | 1 by 9 |", "| 4 | 10 | 1 by 9 |"))
|
||||
written = store.add(SECOND, "")
|
||||
self.assertEqual([note.split(": ")[0] for note in written.notes], [str(self.folder / "todo.md")])
|
||||
self.assertIn("item 1 ", written.notes[0])
|
||||
|
||||
def test_only_the_item_written_refuses_the_write(self):
|
||||
store = self.new_store()
|
||||
first = self.filed(store, FIRST)
|
||||
todo = self.folder / "todo.md"
|
||||
todo.write_text(todo.read_text().replace("`Next ID = 2`", "`Next ID = 10`"))
|
||||
self.assertEqual(self.filed(store, FIRST), 10)
|
||||
todo.write_text("".join(line.replace("| 4 | 1 | 1 by 9 |", "| 4 | 10 | 1 by 9 |") if line.startswith("| 10 ") else line for line in todo.read_text().splitlines(keepends=True)))
|
||||
written = store.edit(first, {"E": "2"}, None)
|
||||
assert isinstance(written, stores.Written), written
|
||||
self.assertIn("item 10 ", written.notes[0])
|
||||
|
||||
def test_an_id_it_holds_no_item_for_fails_naming_the_file(self):
|
||||
store = self.new_store()
|
||||
missing = Failure(f"{self.folder / 'todo.md'} holds no item 99")
|
||||
self.assertEqual((store.edit(99, {"L": "1"}, None), store.finish(99)), (missing, missing))
|
||||
|
||||
def test_a_missing_file_fails_naming_it(self):
|
||||
store = self.new_store()
|
||||
(self.folder / "todo.md").unlink()
|
||||
for failed in (store.read(), store.add(FIRST, ""), store.finish(1)):
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn(f"{self.folder / 'todo.md'}: not found", failed.reason)
|
||||
|
||||
def test_a_file_without_an_items_table_reads_as_no_plan(self):
|
||||
store = self.new_store()
|
||||
(self.folder / "todo.md").write_text("# todo\n")
|
||||
self.assertIsInstance(store.read(), NoItemsTable)
|
||||
|
||||
def test_a_write_to_a_file_without_an_items_table_fails_naming_the_file(self):
|
||||
store = self.new_store()
|
||||
(self.folder / "todo.md").write_text(EMPTY.split("## Items")[0])
|
||||
tableless = Failure(f"{self.folder / 'todo.md'} holds no items table; rank_todo.py --help shows one")
|
||||
self.assertEqual((store.add(FIRST, ""), store.edit(1, {"L": "1"}, None), store.finish(1)), (tableless,) * 3)
|
||||
|
||||
def test_an_edit_of_a_cell_the_table_has_no_column_for_fails_naming_the_file(self):
|
||||
store = self.new_store()
|
||||
(self.folder / "todo.md").write_text("## Items\n\n| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n| 3 | 0.2.0 | | **Do the next thing.** | 5 | 2 | 1 | 2 | 3 | 1 | 1.0 |\n")
|
||||
self.assertEqual(store.edit(3, {"L": "1", "E": "2"}, None), Failure(f"{self.folder / 'todo.md'}'s items table has no L, E column"))
|
||||
|
||||
def test_reads_the_releases_marked_renamed(self):
|
||||
store = self.new_store()
|
||||
(self.folder / "todo.md").write_text(EMPTY + "\n## Renamed\n\n- 0.2.1 renamed to 0.3.0\n")
|
||||
self.assertEqual(store.read(), stores.Plan([], frozenset({release_of("0.2.1")})))
|
||||
|
||||
def test_a_field_it_does_not_know_is_a_programming_error(self):
|
||||
with self.assertRaises(ValueError):
|
||||
self.new_store().add(FIRST | {"Score": "9"}, "")
|
||||
|
||||
|
||||
def test_refuses_a_tagline_with_a_line_break_and_a_detail_with_a_heading(self):
|
||||
store = self.new_store()
|
||||
id_ = self.filed(store, FIRST)
|
||||
before = (self.folder / "todo.md").read_text()
|
||||
broken, split = "the tagline holds a line break; keep it on one line", "the detail holds a ## or ### heading, which would split ## Details; use #### or drop the #s"
|
||||
self.assertEqual(store.add(FIRST | {stores.TAGLINE: "Count\nthe runs."}, ""), Failure(broken))
|
||||
self.assertEqual(store.add(FIRST, "## Why\n"), Failure(split))
|
||||
self.assertEqual(store.edit(id_, {stores.TAGLINE: "Count\nthe runs."}, None), Failure(broken))
|
||||
self.assertEqual(store.edit(id_, {}, "### Why\n"), Failure(split))
|
||||
self.assertEqual((self.folder / "todo.md").read_text(), before)
|
||||
|
||||
@unittest.skipIf(os.geteuid() == 0, "root writes into a read-only directory")
|
||||
def test_a_file_it_cannot_write_fails_naming_it(self):
|
||||
store = self.new_store()
|
||||
self.folder.chmod(0o555)
|
||||
self.addCleanup(self.folder.chmod, 0o755)
|
||||
written = store.add(FIRST, "")
|
||||
assert isinstance(written, Failure), written
|
||||
self.assertTrue(written.reason.startswith(f"{self.folder / 'todo.md'}: "), written.reason)
|
||||
|
||||
def test_a_history_it_cannot_read_fails_every_write(self):
|
||||
store = dataclasses.replace(self.new_store(), history=MemoryStore(fails="no history"))
|
||||
self.assertEqual(store.add(FIRST, ""), Failure("no history"))
|
||||
|
||||
|
||||
def test_ranks_every_write_with_its_floor(self):
|
||||
# At an overall of 6.50 code health weighs 4 times under the default floor of 7.0, and once at a floor of 6.0.
|
||||
def health_row(floor):
|
||||
store = dataclasses.replace(self.new_store(), history=MemoryStore(SCORED.format(overall="6.50")), floor=decimal.Decimal(floor))
|
||||
(self.folder / "README.md").write_text(README.replace(VOID, ""))
|
||||
kept, finished = self.filed(store, FIRST | {MOVES: "code health by 1"}), self.filed(store, SECOND)
|
||||
row = [line for line in (self.folder / "todo.md").read_text().splitlines() if line.startswith(f"| {kept} ")]
|
||||
self.assertIsInstance(store.finish(finished), stores.Written)
|
||||
self.assertIn(row[0], (self.folder / "todo.md").read_text())
|
||||
return row[0]
|
||||
self.assertNotEqual(health_row("6.0"), health_row("7.0"))
|
||||
|
||||
class HeldAt(unittest.TestCase):
|
||||
def test_reads_the_revisions_file_where_commits_hold_the_plan(self):
|
||||
shown = []
|
||||
|
||||
def run(*args, cwd):
|
||||
if args[0] != "show":
|
||||
return "plans/todo.md\n"
|
||||
shown.append((args, cwd))
|
||||
return EMPTY.replace("`Next ID = 1`", "`Next ID = 2`") + "| 1 | 0.1.0 | | | **Count the runs.** | 1 | 2 | 3 | 4 | 1 | 1 by 9 | 0 |\n"
|
||||
|
||||
plan = stores.held_at("origin/main", MemoryPlan(tracked="plans/todo.md"), "/checkout", run)
|
||||
self.assertEqual([item.id for item in plan.items], [1])
|
||||
self.assertEqual(shown, [(("show", "origin/main:plans/todo.md"), "/checkout")])
|
||||
|
||||
def test_reads_the_plan_as_it_stands_where_no_commit_holds_it(self):
|
||||
held = MemoryPlan()
|
||||
held.add(FIRST, "")
|
||||
|
||||
def run(*args, cwd):
|
||||
raise AssertionError("git has no version of this plan")
|
||||
|
||||
self.assertEqual(stores.held_at("origin/main", held, "/checkout", run), held.read())
|
||||
|
||||
def test_fails_where_the_revision_cannot_be_read(self):
|
||||
def run(*args, cwd):
|
||||
return Failure("no git") if args[0] == "ls-tree" else "a commit\n"
|
||||
|
||||
self.assertEqual(stores.held_at("origin/main", MemoryPlan(tracked="todo.md"), "/checkout", run), Failure("no git"))
|
||||
|
||||
|
||||
class Store(unittest.TestCase):
|
||||
def config(self, **named) -> ProjectConfig:
|
||||
paths = {name: pathlib.Path("/checkout", name) for name in SETTINGS[1:]}
|
||||
return ProjectConfig("acme", pathlib.Path("/folder"), pathlib.Path("/checkout"), paths, **named)
|
||||
|
||||
def test_a_path_picks_the_markdown_file(self):
|
||||
config = self.config()
|
||||
picked = stores.store(dataclasses.replace(config, paths=config.paths | {"plan": pathlib.Path("/checkout/todo.md")}))
|
||||
self.assertEqual((type(picked), picked.label, picked.tracked), (stores.FilePlan, "/checkout/todo.md", "todo.md"))
|
||||
|
||||
def test_the_markdown_file_ranks_with_the_configs_floor(self):
|
||||
self.assertEqual(stores.file_plan(self.config(readability_floor=decimal.Decimal("6.5")), pathlib.Path("/checkout/todo.md")).floor, decimal.Decimal("6.5"))
|
||||
|
||||
def test_an_epic_picks_jira_with_the_env_files_credentials(self):
|
||||
epic = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
picked = stores.store(self.config(epic=epic, env_file=pathlib.Path("/secrets/acme.env")))
|
||||
self.assertEqual(picked, JiraPlan(epic, pathlib.Path("/secrets/acme.env"), picked.http))
|
||||
|
||||
def test_an_epic_finishes_an_item_as_the_config_says(self):
|
||||
finish = Finish("Mark as done", "Done")
|
||||
picked = stores.store(self.config(epic=Epic("https://acme.atlassian.net", "ABC-12"), env_file=pathlib.Path("/secrets/acme.env"), jira_finish=finish))
|
||||
self.assertEqual(picked.finish_by, finish)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -4,6 +4,6 @@ import sys
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from loop_inbox import main
|
||||
from project_record import main
|
||||
|
||||
sys.exit(main.main(sys.argv[1:], pathlib.Path.home()))
|
||||
sys.exit(main.main(sys.argv[1:]))
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user