jj-stack 0.1.0__py3-none-any.whl

jj_stack/stack/convergence_observation.py

@@ -0,0 +1,162 @@
+"""Observe the additional repo facts needed to plan selected convergence."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from jj_stack.bootstrap import CommandContext
+from jj_stack.github.client import GithubClient
+from jj_stack.github.resolution import GithubRepoAddress
+from jj_stack.models.github import GithubStack
+from jj_stack.models.stack import LocalCommit
+from jj_stack.stack.pr_facts import (
+    PRFacts,
+    RepoFacts,
+    observe_prs,
+)
+from jj_stack.stack.repo import observe_repo_paths
+
+
+async def complete_sync_observation(
+    *,
+    context: CommandContext,
+    github: GithubClient,
+    initial: RepoFacts,
+    remote_name: str,
+    repo: GithubRepoAddress,
+    selected: tuple[LocalCommit, ...],
+    stacks: tuple[GithubStack, ...],
+) -> tuple[RepoFacts, tuple[GithubStack, ...], bool]:
+    state = context.state_store.load()
+    selected_prs = {
+        identity.pr_number
+        for change in selected
+        if (identity := state.pr_identities.get(change.change_id)) is not None
+    }
+    affected = tuple(stack for stack in stacks if not selected_prs.isdisjoint(stack.pr_numbers))
+    resource_prs = {number for stack in affected for number in stack.pr_numbers}
+    tracked_prs = {
+        identity.pr_number
+        for identity in state.pr_identities.values()
+        if identity.repo_key == repo.repo_key
+    }
+    if not any(
+        _pr_changed(observed, include_remote_target=False)
+        for change in selected
+        if (observed := initial.prs.get(change.change_id)) is not None
+    ) and (resource_prs & tracked_prs).issubset(selected_prs):
+        return initial, (), False
+    change_ids = tuple(
+        change_id
+        for change_id, identity in state.pr_identities.items()
+        if identity.repo_key == repo.repo_key
+        and identity.pr_number in resource_prs
+        and change_id in state.submitted_baselines
+    )
+    missing_ids = tuple(change_id for change_id in change_ids if change_id not in initial.prs)
+    missing = (
+        await observe_prs(
+            change_ids=missing_ids,
+            context=context,
+            github_client=github,
+            github_repo_snapshot=initial.github_repo,
+            include_remote_targets=False,
+            remote_name=remote_name,
+        )
+        if missing_ids
+        else None
+    )
+    prs = {
+        **initial.prs,
+        **(missing.prs if missing is not None else {}),
+    }
+    identities = tuple(item.identity for item in prs.values() if item.identity is not None)
+    remote = initial.remote or (missing.remote if missing is not None else None)
+    targets = (
+        context.jj_client.list_remote_branches(
+            remote=remote.name,
+            patterns=tuple(f"refs/heads/{item.head_ref}" for item in identities),
+        )
+        if remote is not None and identities
+        else {}
+    )
+    observation = replace(
+        initial,
+        prs={
+            change_id: replace(
+                item,
+                remote_pr_branch_target=(
+                    targets.get(item.identity.head_ref) if item.identity is not None else None
+                ),
+            )
+            for change_id, item in prs.items()
+        },
+    )
+    changed = any(_pr_changed(item) for item in observation.prs.values())
+    return observation, stacks if changed else (), changed
+
+
+def queued_pr_numbers(
+    observation: RepoFacts,
+    selected: tuple[LocalCommit, ...],
+) -> tuple[int, ...]:
+    return tuple(
+        pr.number
+        for change in selected
+        if (observed := observation.prs.get(change.change_id)) is not None
+        and (pr := observed.pr) is not None
+        and pr.normalize_state().state == "open"
+        and pr.is_queued
+    )
+
+
+def dependent_path_heads(
+    *,
+    ancestor_commit_ids: tuple[str, ...],
+    context: CommandContext,
+    excluded_change_ids: frozenset[str],
+) -> dict[str, tuple[LocalCommit, ...]]:
+    if not ancestor_commit_ids:
+        return {}
+    paths = observe_repo_paths(
+        jj_client=context.jj_client,
+        descendant_of=ancestor_commit_ids,
+        include_working_copies=True,
+        state=context.state_store.load(),
+    ).paths
+    result: dict[str, tuple[LocalCommit, ...]] = {}
+    for ancestor in ancestor_commit_ids:
+        heads: dict[str, LocalCommit] = {}
+        for path in paths:
+            if not any(item.commit_id == ancestor for item in path.stack.changes):
+                continue
+            head = next(
+                (
+                    change
+                    for change in reversed(path.stack.changes)
+                    if change.change_id not in excluded_change_ids
+                ),
+                None,
+            )
+            if head is not None:
+                heads[head.commit_id] = head
+        result[ancestor] = tuple(heads.values())
+    return result
+
+
+def _pr_changed(
+    observed: PRFacts,
+    *,
+    include_remote_target: bool = True,
+) -> bool:
+    pr = observed.pr
+    if (baseline := observed.baseline) is None:
+        return False
+    if pr is None:
+        return True
+    return (
+        pr.normalize_state().state == "merged"
+        or pr.head.sha != baseline.commit_id
+        or (include_remote_target and observed.remote_pr_branch_target != baseline.commit_id)
+        or any(commit.immutable for commit in observed.local_commits)
+    )

jj_stack/stack/github_stack_safety.py

@@ -0,0 +1,132 @@
+"""Mutation guards for GitHub stack resources."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Sequence
+from dataclasses import dataclass
+
+import jj_stack.ui as ui
+from jj_stack.errors import CliError
+from jj_stack.github.client import GithubClient, GithubClientError
+from jj_stack.models.github import GithubStack
+
+
+def selected_github_stack(
+    *,
+    selected_pr_numbers: Collection[int],
+    stacks: Sequence[GithubStack],
+) -> GithubStack | None:
+    """Return the one GitHub stack the selected pull requests belong to.
+
+    The selection may overlap at most one resource, and every active member of that resource
+    must be selected. A merged prefix GitHub retains is always valid, so a resource the selection
+    touches only through merged members is still returned for callers that reconcile them.
+    Callers that mutate a resource separately require a selected pull request to remain active.
+    """
+
+    selected = set(selected_pr_numbers)
+    overlapping = tuple(stack for stack in stacks if not selected.isdisjoint(stack.pr_numbers))
+    if not overlapping:
+        return None
+    # Only a resource the selection still has an active member in can be dissolved. GitHub keeps
+    # merged members forever, so unstacking a fully merged resource changes nothing, and naming
+    # one in a hint would leave the user retrying a command that cannot make progress.
+    dissolvable = tuple(
+        stack for stack in overlapping if not selected.isdisjoint(stack.active_pr_numbers)
+    )
+    if len(dissolvable) > 1:
+        numbers = tuple(sorted(stack.number for stack in dissolvable))
+        raise CliError(
+            t"The selected pull requests belong to GitHub stacks "
+            t"{ui.join(lambda number: f'#{number}', numbers)}.",
+            hint=t"Run "
+            t"{ui.join(lambda number: ui.cmd(f'jj-stack unstack --stack {number}'), numbers)}, "
+            t"then retry.",
+        )
+    if not dissolvable and len(overlapping) > 1:
+        numbers = tuple(sorted(stack.number for stack in overlapping))
+        raise CliError(
+            t"The selected pull requests are merged members of GitHub stacks "
+            t"{ui.join(lambda number: f'#{number}', numbers)}.",
+            hint="Select changes belonging to one of those stacks, then retry.",
+        )
+    stack = dissolvable[0] if dissolvable else overlapping[0]
+    unselected = tuple(number for number in stack.active_pr_numbers if number not in selected)
+    if unselected:
+        raise CliError(
+            t"GitHub stack #{stack.number} keeps "
+            t"{ui.join(lambda number: f'#{number}', unselected)} active outside the selected "
+            t"stack.",
+            hint=t"Select the complete stack, or run "
+            t"{ui.cmd(f'jj-stack unstack --stack {stack.number}')}, then retry.",
+        )
+    return stack
+
+
+async def dissolve_github_stack(
+    *,
+    github_client: GithubClient,
+    stack: GithubStack,
+) -> None:
+    """Dissolve an observed stack and reject an incomplete mutation result."""
+
+    try:
+        remaining = await github_client.unstack(stack_number=stack.number)
+    except GithubClientError as error:
+        if error.status_code == 422:
+            raise CliError(
+                t"GitHub could not remove any pull requests from stack #{stack.number}.",
+                hint=t"Resolve its locked pull requests, then retry "
+                t"{ui.cmd(f'jj-stack unstack --stack {stack.number}')}",
+            ) from None
+        raise CliError(t"Could not remove GitHub stack grouping #{stack.number}.") from error
+    if remaining is not None and remaining.active_pr_numbers:
+        members = ", ".join(f"#{number}" for number in remaining.active_pr_numbers)
+        raise CliError(
+            t"GitHub stack #{stack.number} still contains {members}.",
+            hint=t"Resolve its locked pull requests, then retry "
+            t"{ui.cmd(f'jj-stack unstack --stack {stack.number}')}.",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class GithubStackSelection:
+    """Live stack membership for one exact ordered PR selection."""
+
+    github_client: GithubClient
+    pr_numbers: tuple[int, ...]
+
+    async def observe(self) -> tuple[GithubStack, ...]:
+        """Return the current complete GitHub stack resources."""
+
+        try:
+            return await self.github_client.list_stacks()
+        except GithubClientError as error:
+            raise CliError("Could not inspect GitHub stack membership.") from error
+
+    async def active_stacks(self) -> tuple[GithubStack, ...]:
+        """Return resources in which a selected pull request is still an active member.
+
+        Only these resources can be dissolved or blocked on: GitHub keeps merged members
+        forever, so a resource the selection only touches through them needs no mutation.
+        """
+
+        if not self.pr_numbers:
+            return ()
+        stacks = await self.observe()
+        selected = set(self.pr_numbers)
+        return tuple(
+            stack for stack in stacks if not selected.isdisjoint(stack.active_pr_numbers)
+        )
+
+    async def require_unstacked(self) -> None:
+        """Reject a mutation while a selected pull request is still an active member."""
+
+        blocking = await self.active_stacks()
+        if not blocking:
+            return
+        stack_number = blocking[0].number
+        raise CliError(
+            t"GitHub stack #{stack_number} blocks this jj-stack operation.",
+            hint=t"Run {ui.cmd(f'jj-stack unstack --stack {stack_number}')} and retry.",
+        )

jj_stack/stack/global_convergence.py

@@ -0,0 +1,270 @@
+"""Observe and classify repo-wide convergence without mutating it."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import jj_stack.github.resolution as github_resolution
+from jj_stack.bootstrap import CommandContext
+from jj_stack.github.client import GithubClient
+from jj_stack.models.github import GithubPR, GithubStack
+from jj_stack.models.stack import LocalCommit
+from jj_stack.models.tracking import TrackedPR, TrackingState
+from jj_stack.stack.convergence_models import (
+    FinishPR,
+    PRFinishPlan,
+    SkipPRFinish,
+)
+from jj_stack.stack.path import RepoStackPath
+from jj_stack.stack.pr_branches import prepare_visible_pr_snapshots
+from jj_stack.stack.pr_facts import (
+    RepoFacts,
+    observe_github_stacks,
+    observe_prs,
+)
+from jj_stack.stack.repo import observe_repo_paths
+from jj_stack.stack.trunk_evidence import (
+    CommitAncestry,
+    TrunkEvidenceKind,
+    classify_commit_ancestries,
+    classify_proven_kind,
+)
+from jj_stack.ui import Message
+
+
+@dataclass(frozen=True, slots=True)
+class GlobalConvergencePlan:
+    blocked: tuple[tuple[TrackedPR, Message], ...]
+    finishes: tuple[PRFinishPlan, ...]
+    sync_change_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GlobalSyncFacts:
+    """One repo-wide observation for global classification."""
+
+    ancestries: Mapping[str, CommitAncestry]
+    local_copies: Mapping[str, tuple[LocalCommit, ...]]
+    paths: tuple[RepoStackPath, ...]
+    pr_facts: RepoFacts
+    stacks: tuple[GithubStack, ...]
+
+
+async def observe_global_sync(
+    *,
+    context: CommandContext,
+    github: GithubClient,
+    remote_name: str,
+    trunk_commit_id: str,
+) -> GlobalSyncFacts:
+    """Observe tracked pull requests from tracking toward affected local paths."""
+
+    state = context.state_store.load()
+    candidates = state.tracked_prs()
+    change_ids = tuple(candidate.change_id for candidate in candidates)
+    prepare_visible_pr_snapshots(
+        jj_client=context.jj_client,
+        state=state,
+    )
+    all_copies, local_copies = context.jj_client.query_commits_by_change_ids_with_off_trunk(
+        change_ids
+    )
+    anchors = tuple(commit.commit_id for commits in local_copies.values() for commit in commits)
+    paths = (
+        observe_repo_paths(
+            jj_client=context.jj_client,
+            descendant_of=anchors,
+            exclude_trunk_descendants=True,
+            include_working_copies=True,
+            state=state,
+        ).paths
+        if anchors
+        else ()
+    )
+    pr_observations, stacks = await asyncio.gather(
+        observe_prs(
+            change_ids=change_ids,
+            context=context,
+            github_client=github,
+            include_remote_targets=False,
+            local_commits_snapshot=all_copies,
+            remote_name=remote_name,
+        ),
+        observe_github_stacks(github=github),
+    )
+    commit_ids = _observation_commit_ids(pr_observations)
+    return GlobalSyncFacts(
+        ancestries=classify_commit_ancestries(
+            commit_ids=commit_ids,
+            context=context,
+            trunk_commit_id=trunk_commit_id,
+        ),
+        local_copies=local_copies,
+        paths=paths,
+        pr_facts=pr_observations,
+        stacks=stacks,
+    )
+
+
+def build_global_convergence_plan(
+    *,
+    facts: GlobalSyncFacts,
+    repo: github_resolution.GithubRepoAddress,
+    state: TrackingState,
+) -> GlobalConvergencePlan:
+    blocked: list[tuple[TrackedPR, Message]] = []
+    finishes: list[PRFinishPlan] = []
+    heads: list[str] = []
+    tracked_prs = frozenset(
+        identity.pr_number
+        for identity in state.pr_identities.values()
+        if identity.repo_key == repo.repo_key
+    )
+    for candidate in state.tracked_prs():
+        reason, finish, candidate_heads = _classify_global_candidate(
+            candidate=candidate,
+            facts=facts,
+            repo=repo,
+            tracked_pr_numbers=tracked_prs,
+        )
+        heads.extend(candidate_heads)
+        if reason is not None:
+            blocked.append((candidate, reason))
+        if finish is not None:
+            finishes.append(finish)
+    return GlobalConvergencePlan(
+        blocked=tuple(blocked),
+        finishes=tuple(finishes),
+        sync_change_ids=tuple(dict.fromkeys(heads)),
+    )
+
+
+def _classify_global_candidate(
+    *,
+    candidate: TrackedPR,
+    facts: GlobalSyncFacts,
+    repo: github_resolution.GithubRepoAddress,
+    tracked_pr_numbers: frozenset[int],
+) -> tuple[Message | None, PRFinishPlan | None, tuple[str, ...]]:
+    ancestry = facts.ancestries[candidate.submitted_baseline.commit_id]
+    pr = facts.pr_facts.prs[candidate.change_id].pr
+    evidence: TrunkEvidenceKind | None = None
+    reason: Message = ""
+    if pr is not None:
+        evidence, reason = classify_proven_kind(
+            ancestries=facts.ancestries,
+            candidate=candidate,
+            pr=pr,
+            repo=repo,
+        )
+    heads = _candidate_path_heads(candidate, facts=facts)
+    affected = ancestry == "on_trunk" or evidence == "rewritten"
+    if affected:
+        return _affected_candidate_plan(
+            candidate=candidate,
+            evidence=evidence,
+            facts=facts,
+            heads=heads,
+            pr=pr,
+            reason=reason,
+            tracked_prs=tracked_pr_numbers,
+        )
+    if pr is None:
+        return t"GitHub no longer reports PR #{candidate.pr_identity.pr_number}", None, ()
+    if ancestry == "unresolved":
+        return "the submitted commit is unavailable locally", None, ()
+    if reason and (
+        pr.normalize_state().state != "open" or not candidate.pr_identity.matches_pr(pr)
+    ):
+        return reason, None, ()
+    return None, None, ()
+
+
+def _affected_candidate_plan(
+    *,
+    candidate: TrackedPR,
+    evidence: TrunkEvidenceKind | None,
+    facts: GlobalSyncFacts,
+    heads: tuple[str, ...] | None,
+    pr: GithubPR | None,
+    reason: Message,
+    tracked_prs: frozenset[int],
+) -> tuple[Message | None, PRFinishPlan | None, tuple[str, ...]]:
+    if heads is None:
+        return "local history is not a supported stack", None, ()
+    if heads:
+        return None, None, heads
+    if pr is None:
+        return t"GitHub no longer reports PR #{candidate.pr_identity.pr_number}", None, ()
+    if evidence is None:
+        return reason, None, ()
+    stack_reason, historical = _detached_stack_blocker(
+        candidate=candidate,
+        stacks=facts.stacks,
+        tracked_pr_numbers=tracked_prs,
+    )
+    if stack_reason is not None:
+        return stack_reason, None, ()
+    finish = (
+        SkipPRFinish(candidate)
+        if evidence == "rewritten" or historical or pr.normalize_state().state != "open"
+        else FinishPR(candidate, pr)
+    )
+    return None, finish, ()
+
+
+def _candidate_path_heads(
+    candidate: TrackedPR, *, facts: GlobalSyncFacts
+) -> tuple[str, ...] | None:
+    copies = {commit.commit_id for commit in facts.local_copies[candidate.change_id]}
+    if not copies:
+        return ()
+    heads = tuple(
+        path.stack.head.change_id
+        for path in facts.paths
+        if any(change.commit_id in copies for change in path.stack.changes)
+    )
+    return heads or None
+
+
+def _detached_stack_blocker(
+    *,
+    candidate: TrackedPR,
+    stacks: tuple[GithubStack, ...],
+    tracked_pr_numbers: frozenset[int],
+) -> tuple[Message | None, bool]:
+    number = candidate.pr_identity.pr_number
+    matching = tuple(
+        member for stack in stacks for member in stack.prs if member.number == number
+    )
+    if not matching:
+        return None, False
+    if not matching[0].is_historical:
+        return t"GitHub still lists PR #{number} as an active member of its stack", False
+    blocked = any(
+        number in stack.pr_numbers
+        and not set(stack.active_pr_numbers).isdisjoint(tracked_pr_numbers)
+        for stack in stacks
+    )
+    return (
+        (
+            t"PR #{number} is in a GitHub stack that still has active members tracked here"
+            if blocked
+            else None
+        ),
+        True,
+    )
+
+
+def _observation_commit_ids(observation: RepoFacts) -> tuple[str, ...]:
+    return tuple(
+        commit_id
+        for item in observation.prs.values()
+        for commit_id in (
+            item.baseline.commit_id if item.baseline is not None else None,
+            item.pr.merge_commit_sha if item.pr is not None else None,
+        )
+        if commit_id is not None
+    )