Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@
- A restack now settles conflicts in files a repository's `generated` setting covers by taking
the base's version (or removing the file where the base has none), without asking the
resolver; only source conflicts reach it, and its prompt names the generated paths as
handled. Reading a conflict no longer fails on a path missing from the working tree.
handled. Reading a conflict no longer fails on a path missing from the working tree. After
the restack, each `generated` entry whose paths the unit touched is run in its `cwd` and the
result committed as one `chore:` commit; a failing command holds the unit under the
`generated_files` cause with its output in the note.

- The red check and the push gate no longer give the test runner a test file the tests commit
deletes or renames away. Before, the runner was named a path that no longer existed and
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -947,7 +947,7 @@ A standing cause names a situation that lasts until a state change passes anothe
`review_escalated_disagreement`, `late_failure`, `needs_human`, `reviewer_hold`, `gated`, `restack_conflict`,
`restack_deferred`, `restack_handed_back`, `dirty_worktree`, `attached`, `host_unavailable`,
`network_unavailable`, `service_unavailable`, `environment`, `split_held`, `manual_step`,
`too_big_for_tier`, `landed_off_default` (a pull request merged into a branch that is not the default branch) and `base_not_moved` (a pull request whose retarget failed three rounds in a row).
`too_big_for_tier`, `landed_off_default` (a pull request merged into a branch that is not the default branch), `base_not_moved` (a pull request whose retarget failed three rounds in a row) and `generated_files` (a repository's `generated` command failed after a restack).
An event cause names a transition that has happened and is over: `requeued`, `released`,
`adopted`, `merged`, `auto_landed`, `closed`, `retired`, `superseded` and `failed`. Recording an event cause ends a standing
one explicitly. A state change the store makes on its own account (a replan's demotion and
Expand Down
18 changes: 18 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -676,6 +676,24 @@ repos: # ordered: deploy order is derived from
# one here to give agents one.
# Each must match the build allow-list (the tool
# list the build starts with) or the load fails
generated: # `generated`: files built from others, regenerated
# after a restack and not merged
- paths: ["web/dist/**"] # `paths`: patterns; a slash-free pattern matches
# by file name anywhere in the repository (`*.js`
# covers every tracked .js). They also count as
# generated for the size rule and the doctor
command: ["npm", "run", "build"]
# `command`: argv run in `cwd` (default `.`, a
# path inside the repository) after a restack
cwd: web
# A restack settles a conflict in these paths
# by taking the base's version (removing the file
# where the base has none), never asking the
# resolver. Then, if the unit touched a path,
# the command runs once and its changes are
# committed. A failing command holds the unit
# with cause `generated_files`, its output in
# the note
changelog: CHANGELOG.md # where the repo keeps its changelog. Set, the
# build, rework, resolver and review prompts
# carry its convention and unit-test runs
Expand Down
2 changes: 1 addition & 1 deletion docs/designs/unit-graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ until a state change passes another cause: `rework`, `base_changed`, `upstream_w
`depth`, `toolchain`, `review_escalated_class`, `review_escalated_disagreement`, `late_failure`,
`needs_human`, `reviewer_hold`, `gated`, `restack_conflict`, `restack_deferred`, `restack_handed_back`,
`dirty_worktree`, `attached`, `host_unavailable`, `network_unavailable`, `service_unavailable`,
`environment`, `split_held`, `manual_step`, `too_big_for_tier`, `landed_off_default` and `base_not_moved`. The event causes (`EVENT_CAUSES`) name a transition that is over:
`environment`, `split_held`, `manual_step`, `too_big_for_tier`, `landed_off_default`, `generated_files` and `base_not_moved`. The event causes (`EVENT_CAUSES`) name a transition that is over:
`requeued`, `released`, `adopted`, `merged`, `auto_landed`, `closed`, `retired`, `superseded` and `failed`. An event cause ends
a standing one explicitly. A replan carries a standing cause through the demotion and the promotion
(and a vanished change and a join do the same), marking the entry `carried`, and a caller's state
Expand Down
11 changes: 11 additions & 0 deletions src/agent_build_kit/graph/nodes.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@
waiting_note,
)
from agent_build_kit.pipeline.gateway_usage import attribution
from agent_build_kit.pipeline.generated import GeneratedFilesFailed, hold_note
from agent_build_kit.pipeline.group_mode import GroupMode
from agent_build_kit.pipeline.manual_steps import unmet_steps
from agent_build_kit.pipeline.metric_records import emit_metric
Expand Down Expand Up @@ -1301,6 +1302,13 @@ def prepare(self, state: UnitRun) -> Update:
**remembered,
**self.hold(PLANNED, note, note, cause=Cause.RESTACK_DEFERRED),
}
except GeneratedFilesFailed as error:
note = hold_note(base, error)
return {
**FRESH,
**remembered,
**self.hold(HELD, note, note, cause=Cause.GENERATED_FILES),
}
except Exception as error: # noqa: BLE001
why = f"restack onto {base} conflicted: {error}"
self.append_feedback(why)
Expand Down Expand Up @@ -3139,6 +3147,9 @@ def restack_now(self, state: UnitRun, point: str, *, find_base: bool = True) ->
)
except (AgentRateLimited, AgentInterrupted, NetworkUnavailable, ServiceUnavailable):
raise
except GeneratedFilesFailed as error:
note = hold_note(base, error)
return self.hold(HELD, note, note, cause=Cause.GENERATED_FILES)
except Exception as error: # noqa: BLE001
return self.rebase(
state,
Expand Down
10 changes: 10 additions & 0 deletions src/agent_build_kit/pipeline/events.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@
is_fix_change,
waiting_note,
)
from agent_build_kit.pipeline.generated import GeneratedFilesFailed, hold_note
from agent_build_kit.pipeline.landing_check import Landing, merged_on_branch, merged_on_default
from agent_build_kit.pipeline.landing_intent import clear_intent, has_intent
from agent_build_kit.pipeline.pr_poller import ( # noqa: F401 — FAILING_CHECKS_REASON re-exported
Expand Down Expand Up @@ -2749,6 +2750,15 @@ def restack(
cause=Cause.RESTACK_CONFLICT,
)
return RestackOutcome.CONFLICT
except GeneratedFilesFailed as error:
# The branch is back where it was; a person fixes the command and requeues.
store.set_state(
child.id,
HELD,
note=hold_note(new_base, error),
cause=Cause.GENERATED_FILES,
)
return RestackOutcome.DEFERRED
except AGENT_UNAVAILABLE as error:
# The resolver could not run, which says nothing about the branch.
# Not raised on: the merge is handled once, and the parent's branch
Expand Down
96 changes: 96 additions & 0 deletions src/agent_build_kit/pipeline/generated.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
"""Rebuild a repository's generated files after a restack and commit the result."""

import subprocess
from collections.abc import Sequence
from pathlib import Path

from agent_build_kit.budget import cut_head
from agent_build_kit.config import GeneratedConfig
from agent_build_kit.pipeline.check_runner import COMMAND_TIMEOUT_SECONDS
from agent_build_kit.pipeline.shell import git
from agent_build_kit.pipeline.unit_size import is_generated


class GeneratedFilesFailed(RuntimeError):
"""A regenerate command could not run, timed out or exited non-zero; `output` says why."""

output: str

def __init__(self, output: str) -> None:
super().__init__(f"regenerating the generated files failed:\n{output}")
self.output = output


def hold_note(onto: str, error: GeneratedFilesFailed) -> str:
"""The note a unit is held with when its generated files could not be rebuilt: the one
text every restack path records under the `generated_files` cause."""
return (
f"rebuilding the generated files after restacking onto {onto} failed:\n"
f"{cut_head(error.output, 1000, 'char')}"
)


def _changed_under(repo: Path, patterns: Sequence[str]) -> list[str]:
"""Paths the working tree modifies, deletes or adds that `patterns` cover."""
listed = git(
repo, "ls-files", "-z", "--modified", "--deleted", "--others", "--exclude-standard"
).stdout
return sorted({name for name in listed.split("\0") if name and is_generated(name, patterns)})


def discard_output(repo: Path, entries: Sequence[GeneratedConfig]) -> None:
"""Remove what a failed command left under its entries' paths: edits and new files."""
left = _changed_under(repo, [pattern for entry in entries for pattern in entry.paths])
if left:
git(repo, "checkout", "-q", "HEAD", "--", *left, check=False)
git(repo, "clean", "-fdq", "--", *left, check=False)


def regenerate(
repo: Path,
entries: Sequence[GeneratedConfig],
*,
onto: str,
timeout: float = COMMAND_TIMEOUT_SECONDS,
) -> None:
"""Run each entry whose paths the unit's commits (`onto...HEAD`) touched, in its `cwd`,
and commit what changed under those entries' paths as one `chore:` commit. A command that
cannot start, runs past `timeout` seconds or exits non-zero raises `GeneratedFilesFailed`."""
touched = git(repo, "diff", "--name-only", f"{onto}...HEAD").stdout.split()
ran: list[GeneratedConfig] = []
for entry in entries:
if not any(is_generated(name, entry.paths) for name in touched):
continue
shown = " ".join(entry.command)
try:
done = subprocess.run(
list(entry.command),
cwd=repo / entry.cwd,
capture_output=True,
text=True,
check=False,
timeout=timeout,
)
except OSError as error:
raise GeneratedFilesFailed(f"`{shown}` could not be run: {error}") from error
except subprocess.TimeoutExpired as error:
raise GeneratedFilesFailed(f"`{shown}` timed out after {timeout:g}s") from error
if done.returncode != 0:
raise GeneratedFilesFailed((done.stdout + done.stderr).strip())
ran.append(entry)
if not ran:
return
changed = _changed_under(repo, [pattern for entry in ran for pattern in entry.paths])
if not changed:
return
git(repo, "add", "-A", "--", *changed)
if not git(repo, "diff", "--cached", "--name-only").stdout.strip():
return
git(
repo,
"commit",
"--no-verify",
"-q",
"-m",
f"chore: Rebuild the generated files after restacking onto {onto}",
)
24 changes: 23 additions & 1 deletion src/agent_build_kit/pipeline/restack.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
changelog_path,
resolver_changelog_rule,
)
from agent_build_kit.pipeline.generated import GeneratedFilesFailed, discard_output, regenerate
from agent_build_kit.pipeline.git_output import (
PUSH_OPERATION,
GitLockFailed,
Expand Down Expand Up @@ -527,6 +528,22 @@ def _land_detached(repo: Path, branch: str, *, started: str) -> Moved:
return Moved(sha=head)


def _regenerate(repo: Path, config: RepoConfig | None, *, onto: str, started: str) -> None:
"""Rebuild the repo's generated files once the rebase has finished. Inside the turn.

A failed rebuild puts the head back at `started` (the branch's, or a detached tree's, head
before the move) and removes what the command wrote under its entries' paths, so the move
is replayed, and the rebuild tried again, the next time it is asked for."""
if config is None or not config.generated:
return
try:
regenerate(repo, config.generated, onto=onto)
except GeneratedFilesFailed:
git(repo, "reset", "-q", "--hard", started)
discard_output(repo, config.generated)
raise


def _separate_changelog(repo: Path, config: RepoConfig | None) -> None:
"""Put back the blank line a union merge took from between two changelog bullets, in a
commit of its own on the replayed branch. Inside the turn, with the rebase finished."""
Expand Down Expand Up @@ -658,7 +675,9 @@ def move_branch_onto(
with the rebase aborted. With `detached`, `repo` is a worktree on no branch:
the rebase runs on its detached head and the branch is moved at the end by
compare-and-swap, unless another worktree has it checked out
(`BranchCheckedOut`).
(`BranchCheckedOut`). The regenerate commands of the repository's `generated` entries run
inside the turn, once the rebase has finished, so a long build holds the turn; one that
fails puts the branch back where the move started and raises `GeneratedFilesFailed`.

`repo_config` (else the `context`'s) names the repo whose `changelog` setting decides
which file is separated once the branch is replayed; with neither, the default name.
Expand All @@ -685,6 +704,7 @@ def move_branch_onto(
)
if result.returncode == 0:
_separate_changelog(repo, repo_config)
_regenerate(repo, repo_config, onto=new_base, started=started)
if detached:
return _land_detached(repo, branch, started=started)
return Moved(sha=git(repo, "rev-parse", branch).stdout.strip())
Expand All @@ -695,6 +715,7 @@ def move_branch_onto(
done, result = _settle_generated(repo, result, patterns, settled)
if done:
_separate_changelog(repo, repo_config)
_regenerate(repo, repo_config, onto=new_base, started=started)
if detached:
return _land_detached(repo, branch, started=started)
return Moved(sha=git(repo, "rev-parse", branch).stdout.strip())
Expand Down Expand Up @@ -828,6 +849,7 @@ def move_branch_onto(
tried="\n".join(failures),
)
_separate_changelog(repo, repo_config)
_regenerate(repo, repo_config, onto=new_base, started=started)
if detached:
landed = _land_detached(repo, branch, started=started)
return Moved(sha=landed.sha, resolved=resolved)
Expand Down
1 change: 1 addition & 0 deletions src/agent_build_kit/pipeline/unit_store.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ class Cause(StrEnum):
TOO_BIG_FOR_TIER = "too_big_for_tier"
SUPERSEDED = "superseded"
LANDED_OFF_DEFAULT = "landed_off_default"
GENERATED_FILES = "generated_files"
BASE_NOT_MOVED = "base_not_moved"


Expand Down
5 changes: 5 additions & 0 deletions src/agent_build_kit/skills/abk-config/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,11 @@ repos: # ordered; a task group's [repo] tag is a key here
# scope: whole|file|node-id|affected}; `{path}` in the command exactly
# when the scope is file or node-id. null follows the profiles, a list
# replaces them. Each must match the build allow-list: refused at load
generated: [] # [{paths: [...], command: [argv], cwd: "."}]: files built from others.
# A restack takes the base's version of a conflicted path (no
# resolver), then runs `command` in `cwd` once if the unit touched a
# path and commits the result; a failure holds the unit, cause
# `generated_files`. A slash-free pattern matches by file name anywhere
changelog: CHANGELOG.md # the repo's changelog; null = no convention, no check.
# Convention: AGENTS.md `## Changelog`, else CLAUDE.md,
# else the packaged text. Doctor warns if the file is absent
Expand Down
53 changes: 53 additions & 0 deletions tests/docs/test_generated_docs.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
"""The documents and the `abk-config` skill describe `repos.<repo>.generated`: its keys, what a
restack does with the paths, the hold cause, and the changelog entry."""

from __future__ import annotations

from pathlib import Path

import pytest

from agent_build_kit import skills
from tests.prompt_text import flat

ROOT = Path(__file__).resolve().parents[2]


def doc(*parts: str) -> str:
return flat(ROOT.joinpath(*parts).read_text(encoding="utf-8")).lower()


def unreleased_section() -> str:
text = ROOT.joinpath("CHANGELOG.md").read_text(encoding="utf-8")
after = text.split("## Unreleased", 1)[1]
return flat(after.split("\n## ", 1)[0]).lower()


def test_configuration_documents_the_generated_setting_keys() -> None:
text = doc("docs", "configuration.md")
for term in ("generated", "paths", "command", "cwd"):
assert f"`{term}`" in text


def test_configuration_says_what_a_restack_does_with_generated_files() -> None:
text = doc("docs", "configuration.md")
assert "restack" in text
assert "base" in text
assert "`generated_files`" in text


def test_configuration_says_a_slash_free_pattern_matches_by_file_name_anywhere() -> None:
text = doc("docs", "configuration.md")
assert "slash-free pattern" in text
assert "file name" in text


def test_the_abk_config_skill_mentions_the_generated_setting() -> None:
text = flat(skills.source("abk-config")).lower()
assert "generated:" in text
assert "cwd" in text


@pytest.mark.parametrize("term", ["generated", "restack", "`generated_files`"])
def test_the_changelog_entry_under_unreleased_covers_the_setting(term: str) -> None:
assert term in unreleased_section()
17 changes: 14 additions & 3 deletions tests/pipeline/test_events_restack_scope.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,21 @@ def __call__(self, **kwargs: Any) -> tuple[bool, str]:


def restacking(
installation: Installation, moved: Moved, *, name: str = "feature", diff_changes: bool = False
installation: Installation,
moved: Moved | Exception,
*,
name: str = "feature",
diff_changes: bool = False,
):
"""The handler over unit `name`, approved at `approved`, and a way to run it; returns the
store, the unit-test it was given, the pushes and the run."""
store, the unit-test it was given, the pushes and the run. A `moved` that is an exception
is raised by the move."""

def move(*args: Any, **kwargs: Any) -> Moved:
if isinstance(moved, Exception):
raise moved
return moved

child = change_with_unit(installation, name, f"{name}/1").model_copy(
update={"pr": 2, "branch": f"spec/{name}/1", "approved": "approved"}
)
Expand All @@ -47,7 +58,7 @@ def restacking(
repos={"app": installation.checkouts["app"]},
store=store,
root=installation.root,
move=lambda *a, **k: moved,
move=move,
unit_test=unit_test,
push=lambda *a, **k: pushed.append("pushed") or "newsha",
retarget=lambda *a, **k: None,
Expand Down
Loading